From 1602613bb64bf3934e5ac10fb3420f51a3be07a4 Mon Sep 17 00:00:00 2001
From: Gabor Bakos <gabor@bitraptors.com>
Date: Fri, 19 Jun 2026 18:19:59 +0200
Subject: [PATCH 01/15] docs: add Archie Intent Review design & handoff

Captures the brainstormed design for a PR-time semantic review that checks a
branch's folded blueprint/rules diff (branch vs base) against retained
invariants, posts an FYI comment, and never blocks. POC scope: GitHub Action +
zero-dep script. Documents that /archie-sync already folds into the blueprint
on the branch, the Layer 1/2 design, guardrails from the adversarial review,
the decisions log, dependency chain, and open questions for planning.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs/archie-intent-review-design.md | 335 ++++++++++++++++++++++++++++
 1 file changed, 335 insertions(+)
 create mode 100644 docs/archie-intent-review-design.md

diff --git a/docs/archie-intent-review-design.md b/docs/archie-intent-review-design.md
new file mode 100644
index 0000000..85921d8
--- /dev/null
+++ b/docs/archie-intent-review-design.md
@@ -0,0 +1,335 @@
+# Archie Intent Review — Design & Handoff
+
+- **Status:** Design approved in brainstorm; ready for implementation planning.
+- **Date:** 2026-06-19
+- **Branch:** `feature/archie-intent-review`
+- **Scope of this document:** the POC. The path beyond the POC is captured in §10 so planning
+  can see where it leads, but only the POC is in scope for the first implementation plan.
+
+---
+
+## 1. One-sentence summary
+
+A GitHub Action that, when a PR is opened, **reviews the proposed change to the architectural
+source of truth** (the Archie blueprint) and posts a plain-language comment telling the reviewer
+whether the PR silently weakened an invariant, introduced a contradiction, or has behavior that
+breaks a standing rule. **It surfaces; the human decides. It never blocks.**
+
+---
+
+## 2. Motivation — the problem we're solving
+
+Archie maintains a **living blueprint**: a semantic snapshot of a codebase's architecture
+(`blueprint.json`) plus synthesized enforceable rules (`rules.json`). When a developer works with
+Archie, `/archie-sync` **folds their change back into that blueprint on their branch** — and that
+fold can ADD, UPDATE, or **REMOVE** sections, including load-bearing invariants
+(`domain_invariants`, key decisions).
+
+Because the team's intended governance model is **"merge = acceptance"** (the blueprint is a
+versioned in-repo file; merging a PR accepts whatever blueprint state is on the branch), a folded
+edit to the source of truth **becomes organizational law the instant the PR merges** — buried in a
+diff that no human reads carefully.
+
+**The danger:** a low-confidence sync that quietly deletes or weakens a `tenant-isolation`
+invariant becomes "truth," silently, on merge. There is currently **no checkpoint** between "sync
+folded something into the blueprint" and "that something is now law."
+
+**Archie Intent Review is that checkpoint**, placed at the only moment it can still matter: PR
+review.
+
+### Why this is defensible (vs. a generic "your code broke a rule" bot)
+
+- It operates on a **structured diff of the blueprint**, not fuzzy raw source code → high
+  precision, verifiable explanations, small hallucination surface.
+- It catches a class of problem **no linter can** (linters have no semantic source of truth to
+  diff against).
+- It targets the **corruption of the source of truth**, which is uniquely Archie's concern.
+
+---
+
+## 3. Glossary — the cast of artifacts
+
+| Artifact | What it is | Where |
+|---|---|---|
+| `blueprint.json` | Semantic architecture snapshot: components, decisions, `domain_invariants`, pitfalls, data models | `.archie/` |
+| `rules.json` | Synthesized enforceable rules; each has `severity_class`, `description`, `why` | `.archie/` |
+| The **ledger** | `/archie-sync record` output: `claims[]` with `kind`, `statement`, `status`, `evidence_files`, `confidence`, `reconstructed` | `.archie/changes/change_*.json` + `latest.json` |
+| The **Action** | The new component — runs in CI on the PR | `.github/workflows/` + script |
+| The **reviewer** | A human who reads the Action's comment and makes the calls | — |
+
+### Ledger claim schema (verified against `archie/standalone/sync.py`)
+
+```jsonc
+{
+  "version": 3,
+  "id": "20260619-143022-a1b2c3d",
+  "folded": true,                         // Phase 2 marks this true after fold-apply
+  "provenance": { "git_head": "...", "branch": "...", "agent": "claude", "reconstructed": false },
+  "diff": { "changed_files": [...], "affected_folders": [...], "ratio": 0.0 },
+  "claims": [
+    { "id": "rule:dunning-cap",
+      "kind": "rule",                     // ADVISORY: decision|pitfall|rule|guideline
+                                          // DESCRIPTIVE: behavior|structure|dataflow|data|tech|reference
+      "status": "eligible",               // eligible = confident + non-reconstructed + evidenced in diff; else staged
+      "statement": "Dunning retries capped at 3 per invoice",
+      "evidence_files": ["jobs/dunning_job.py"],
+      "confidence": "high",
+      "reconstructed": false }
+  ]
+}
+```
+
+The `kind` field's advisory/descriptive split gives us **Layer 1 vs Layer 2 separation for free** —
+no change to sync is required.
+
+---
+
+## 4. How `/archie-sync` already behaves (verified against `archie/assets/workflow/sync/SKILL.md`)
+
+This is load-bearing context — the design depends on it being true:
+
+- `/archie-sync` is a **two-phase skill**.
+- **Phase 1 (`record`)** writes the ledger. It is *mostly descriptive* ("what the code now is");
+  advisory rules are an occasional side-output, not the point.
+- **Phase 2 (fold)** runs when `eligible > 0`: the agent reconciles blueprint sections + per-folder
+  CLAUDE.md using **NO-OP / UPDATE / ADD / REMOVE** ops, then `fold-apply` re-renders
+  `CLAUDE.md`/`AGENTS.md`/`rules.json` and marks the record `folded: true`.
+- **Sync edits files but does NOT commit** — the developer decides what to commit.
+
+**Consequences for our design:**
+1. By the time the dev pushes, `blueprint.json` / `rules.json` are *already modified on the branch*.
+2. So **"merge = acceptance" already works via plain git** — no fold-on-merge automation needed.
+3. The **cleanest review input is the blueprint/rules git-diff (branch vs `origin/main`)** — the
+   ledger is corroborating context, not the primary signal.
+4. Because fold includes UPDATE/REMOVE, the source of truth can be **silently weakened** — which is
+   exactly what we review for.
+
+---
+
+## 5. End-to-end workflow
+
+**Prerequisite (one-time per repo):** `/archie-deep-scan` → baseline `blueprint.json` + `rules.json`
+committed on `main`.
+
+1. **Dev works** on a feature branch in Claude Code (Archie installed).
+2. **Dev runs `/archie-sync`.** Phase 1 records the ledger; Phase 2 folds eligible claims into
+   `blueprint.json`/`rules.json` on the branch and re-renders. Sync does not commit.
+3. **Dev commits** code **+ the folded blueprint changes + the ledger**, pushes, opens a PR.
+4. **The Action fires** (`on: pull_request`) and gathers three inputs:
+   - **Proposed change to truth:** `git diff` of `.archie/blueprint.json` + `rules.json`, **branch
+     vs `origin/main`**.
+   - **Evidence behind it:** all `.archie/changes/change_*.json` files new on the branch (NOT just
+     `latest.json` — see §8, note 2).
+   - **What must still hold:** the retained rules/invariants from the base-ref blueprint.
+5. **One Claude API call (Haiku)** judges the blueprint diff against the retained rules, using the
+   ledger as corroboration → structured findings.
+6. **The Action posts one FYI comment** (upserted — re-pushes update the same comment, no spam).
+   **The human reads it and decides** per finding: fix the code, or accept the rule change. Dev
+   pushes fixes → Action re-runs → comment updates.
+7. **Merge.** The folded blueprint is in the PR, so merging *is* the acceptance — `main`'s baseline
+   evolves automatically via git. **No extra automation.**
+
+---
+
+## 6. What the review checks (the brain)
+
+It reads the **blueprint/rules diff** and flags three things:
+
+| Flag | Detected from the diff | Why it matters |
+|---|---|---|
+| **Silent weakening / removal** | a REMOVE/UPDATE that retires or softens a `domain_invariant` / `decision` | the corruption case — about to become law on merge |
+| **Contradiction** | an ADD/UPDATE that conflicts with a *retained* rule | the fold introduced an inconsistency into the source of truth |
+| **Behavior-violates-rule** | a descriptive change implying a retained rule is now broken | the undeclared violation (the "magic" catch) |
+
+**The ledger sharpens severity.** A fold that REMOVE'd an invariant whose backing claim was
+`confidence: low, reconstructed: true` is a five-alarm flag — *a low-confidence guess just deleted a
+load-bearing rule.*
+
+### Two layers — both on structured data, never raw code
+
+- **Layer 1 — rule-vs-rule** (the `rules.json` / decision diff): conflict / duplicate / refine /
+  net-new. Highest precision — text-vs-text contradiction detection.
+- **Layer 2 — behavior-vs-rule** (the descriptive `blueprint.json` diff + descriptive claims):
+  catches undeclared violations *without reading raw code*, because sync already distilled the
+  behavior into a claim.
+
+### Deferred — Layer 3
+
+Reading the raw source `git diff` against invariants. This is the low-precision, "because-theater"
+zone (a model can always produce a plausible-but-wrong cited explanation). It is **explicitly out of
+the POC** and must be gated behind an eval harness before it is allowed to comment, let alone block.
+
+---
+
+## 7. The output — the PR comment
+
+One comment, grouped by flag. Each entry carries:
+- the affected rule/invariant,
+- what the diff did to it (REMOVE/UPDATE/ADD/contradiction),
+- a one-line **because drawn from the two texts** — verifiable, not free-generated prose,
+- (where relevant) the ledger confidence/provenance that sharpens severity.
+
+Framing is **FYI to the reviewer — never blocking.** The comment explicitly leaves the
+violation-vs-evolution decision to the human and notes that merge accepts the shown blueprint
+changes as the new baseline.
+
+**Hard rule — because-or-suppress:** if a finding cannot produce a verifiable, cited because, it is
+**suppressed, not shown.** This is the single discipline that keeps the tool out of the cry-wolf
+death spiral.
+
+---
+
+## 8. The build (technical)
+
+Two files, dropped into the target repo (least-complex delivery, per the decision in §11):
+
+### File 1 — `.github/workflows/archie-intent-review.yml`
+- `on: pull_request` (types: `opened`, `synchronize`)
+- `permissions: { pull-requests: write, contents: read }`
+- `actions/checkout` with `fetch-depth: 0` (needed to diff against the base ref)
+- Runs `intent_review.py` with `ANTHROPIC_API_KEY` (their secret) + `GITHUB_TOKEN` (built-in)
+
+### File 2 — `intent_review.py`
+- Zero-dependency Python 3.9+ (Archie's standalone DNA — matches `archie/standalone/*.py`)
+- Steps: compute blueprint/rules diff (branch vs base) → load ledger + retained rules → one Claude
+  API call (structured JSON output) → upsert the PR comment via the GitHub API.
+
+### Implementation notes for planning
+1. **Base ref:** diff against `origin/<base>` (`github.event.pull_request.base.sha`), not the branch's
+   own prior state.
+2. **Read all branch ledger files, not just `latest.json`.** `latest.json` is overwritten on every
+   `record`; if a dev synced multiple times on the branch, earlier harvests live only in
+   `change_*.json`. The PR's full intent = the union of all `change_*.json` new on the branch vs base.
+3. **Comment upsert:** find an existing comment authored by the Action (tagged with a hidden marker)
+   and update it; otherwise create. Prevents spam on `synchronize`.
+4. **Model:** Haiku is the default target for cost; confirm it clears the quality bar during the
+   first dogfood runs (see §12).
+5. **Empty/None states:** no blueprint diff (dev didn't commit blueprint changes), no ledger, or no
+   findings → post a minimal/no comment rather than a noisy "nothing found" wall.
+
+---
+
+## 9. Design guardrails (carried over from the adversarial review)
+
+These are non-negotiable for the POC. They each neutralize a specific identified failure mode:
+
+- **Non-blocking** (FYI comment, no CI gate) → avoids the cry-wolf death spiral.
+- **Human decides violation-vs-evolution** (the Action never auto-classifies) → avoids the
+  *asymmetric* danger where a wrong "it's an intended evolution" call launders a bug into law.
+- **Because-or-suppress** → no verifiable cited because, no comment.
+- **Structured inputs only** (blueprint diff + ledger), never raw code in the POC → keeps precision
+  high and avoids because-theater.
+
+---
+
+## 10. POC scope vs. the road beyond
+
+### In the POC (this plan)
+Steps 0–6 of §5 + a normal merge. **The deliverable is that comment, appearing and being correct.**
+
+### Explicitly deferred (NOT in this plan)
+- **Layer 3** — raw-code reading, gated behind an eval harness.
+- **The judge as a blocking gate** — a CI status check that can fail the PR.
+- **Auto violation-vs-evolution categorization.**
+- **The eval / observability plane** (Langfuse-style): replay historical PRs, score
+  precision/false-evolution, store traces. Reuses `archie/benchmark/` + Supabase when built. This is
+  what must exist before the tool is allowed to *block*.
+- **The setup webapp + GitHub App + backend** (server-side execution, "connect repo + GitHub +
+  Claude key + go"). The scalable solution, only if the POC works.
+- **BYO-key onboarding flow.**
+- **Post-merge fold automation** — not needed; git already handles acceptance because the fold
+  happened on the branch.
+
+---
+
+## 11. Key decisions & rationale (the trail planning should not re-litigate)
+
+| Decision | Choice | Why |
+|---|---|---|
+| Delivery vehicle for POC | **GitHub Action** (CI-side, their key) | Least-complex way to prove value on a PR. App + backend is the *scalable* path, deferred. |
+| Review input | **Blueprint/rules git-diff (branch vs base)**, ledger as context | Sync already folds on the branch, so the diff IS the proposed change to truth — deterministic, no AI to find *what* changed. |
+| Judgment depth | **Layers 1 + 2 only** (structured claims/diff) | High precision; Layer 3 (raw code) is the fatal-flaw zone, gated behind eval. |
+| Blocking? | **No — FYI only** | Precision bar for a public governance bot is ~95%+; we have no eval data yet. Non-blocking survives socially. |
+| Who decides violation-vs-evolution | **The human** | Auto-deciding risks laundering a bug into law (asymmetric miscategorization). |
+| Baseline evolution (step 7) | **Automatic via git** (fold already on branch) | No separate automation; "merge = acceptance" falls out of the in-repo blueprint. |
+
+---
+
+## 12. Dependency chain & how to interpret POC results
+
+The review is only as good as a chain that is almost entirely **upstream** of the Action:
+
+> baseline exists → baseline is good (not trivia) → dev ran `/archie-sync` → sync folded well →
+> dev committed the blueprint changes.
+
+So the POC tests **three things at once**: the review idea, **plus** sync's fold quality, **plus**
+the blueprint's quality. **A weak sync or a trivia blueprint can make a sound idea look like a
+failed POC.**
+
+**Interpretation rule:** when a review is bad, first diagnose *was the idea wrong, or was the
+upstream input (claim/baseline) wrong?* before concluding anything about the concept.
+
+**De-risking the first run:** dogfood on **Archie's own repo** first, on a PR where you know what
+sync should produce — so the first signal isolates the *idea* from *upstream quality*. Note:
+Archie's repo is **not currently self-instrumented** (no `.archie/changes/`, empty
+`.claude/commands/`), so this requires running deep-scan + sync against Archie itself first.
+
+---
+
+## 13. Open questions for planning
+
+These do not block starting the plan, but the plan must resolve them:
+
+1. **Diff granularity for `blueprint.json`.** It's a large JSON. Do we diff semantically
+   (parse + compare keyed sections: `decisions[]`, `domain_invariants[]`, `rules`) or textually
+   (raw `git diff` with the model interpreting hunks)? Semantic is more precise but more code.
+2. **Which retained rules to feed the model.** All of them, or only those touched/adjacent to the
+   diff (to bound prompt size + cost)? Likely a relevance pre-filter.
+3. **Comment marker mechanism** for upsert (hidden HTML comment vs. a known title).
+4. **Failure/auth modes** — missing `ANTHROPIC_API_KEY`, API error, fork PRs (where secrets are
+   unavailable). What does the Action do — skip silently, or post a setup note?
+5. **Dogfood prerequisite** — do we instrument Archie's own repo (deep-scan + sync) as part of this
+   work, or stand up a separate minimal fixture repo?
+6. **Where the two files live in the Archie repo** — canonical source under `archie/standalone/` +
+   `archie/assets/` and synced to `npm-package/assets/` per the repo's file-sync rule, or a new
+   home? (See `CLAUDE.md` "File Sync".)
+
+---
+
+## Appendix A — Worked example ("Acme Billing")
+
+Baseline rules on `main`:
+
+| ID | Rule | Kind |
+|---|---|---|
+| R1 | Every tenant-table read/write must be `tenant_id`-scoped. No cross-tenant access. | `domain_invariant` |
+| R2 | All money movement goes through `PaymentGateway`. No direct Stripe calls. | `decision` |
+| R3 | Webhook handlers must be idempotent (Stripe retries → duplicates → double-charge). | `pitfall` |
+| R4 | Background jobs live in `jobs/` and register with the scheduler. | `guideline` |
+
+Task **LIN-482**: *Add automatic dunning — retry failed charges 3× over 5 days, then email.*
+
+The dev builds it, but: the nightly sweep queries charges **globally (no tenant scoping)**, and the
+retry calls **`stripe.Charge.create()` directly**. They run `/archie-sync`; eligible claims fold
+into the blueprint on the branch. The PR's blueprint diff + ledger drive this comment:
+
+> **📐 Archie Intent Review — LIN-482**
+>
+> **⚠️ Silent weakening (Layer 1)** — the fold UPDATE'd **R1 · Tenant Isolation** to allow an
+> unscoped global sweep "for performance". Backing claim: `confidence: medium`. *Intended change to
+> R1, or should the sweep loop per-tenant?* Your call.
+>
+> **⚠️ Behavior-violates-rule (Layer 2, undeclared)** — descriptive claim *"DunningJob calls
+> `stripe.Charge.create()` directly"* conflicts with **R2 · Centralized Payments**. The retry path
+> bypasses `PaymentGateway`. *(Not declared as a rule — surfaced from behavior.)*
+>
+> **🔁 Refines (Layer 1)** — declared *"Webhook handlers must log a `dedupe_key`"* strengthens
+> **R3**. On merge, R3 gains the clause.
+>
+> **✨ Net-new (Layer 1)** — *"Dunning retries capped at 3 per invoice"* — no baseline rule covers
+> this. Will be added on merge.
+>
+> *Archie surfaces; it doesn't block. Merge accepts the rule changes above as the new baseline.*
+
+The reviewer fixes R2 (route through `PaymentGateway`) and R1 (loop per-tenant), keeps the refine +
+net-new, merges. The R2 catch — which **nobody declared** — is the catch that pays for the tool.

From 632547cc241cd8ec95d9805f93bdcc4af72bedf1 Mon Sep 17 00:00:00 2001
From: Gabor Bakos <gabor@bitraptors.com>
Date: Fri, 19 Jun 2026 18:41:42 +0200
Subject: [PATCH 02/15] docs+assets: Archie Intent Review delivery plan + setup
 script
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

End-to-end delivery plan (7 milestones, grounded against deep-scan/sync/
distribution internals via a research+critique+revise pass) plus the two
canonical setup assets the plan's M4/M5 produce:

- docs/archie-intent-review-delivery-plan.md — the plan
- archie/assets/workflows/archie-intent-review.yml — the Action (on: pull_request,
  fetch base ref, runs .archie/intent_review.py)
- archie/assets/setup-archie-intent-review.sh — idempotent gh-based one-command
  CI setup (prereq checks, silent secret via gh secret set, copies the canonical
  YAML, fork-PR caveat) — no GitHub-web tinkering

NOTE: not yet distributed. The file-sync wiring (npm-package/assets copies +
verify_sync.py .sh/.yml/plural-workflows checks + archie.mjs/install.py entries)
and the review engine intent_review.py are milestones M1a-M3 of the plan.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 archie/assets/setup-archie-intent-review.sh   |  99 ++++
 .../assets/workflows/archie-intent-review.yml |  29 ++
 docs/archie-intent-review-delivery-plan.md    | 468 ++++++++++++++++++
 3 files changed, 596 insertions(+)
 create mode 100755 archie/assets/setup-archie-intent-review.sh
 create mode 100644 archie/assets/workflows/archie-intent-review.yml
 create mode 100644 docs/archie-intent-review-delivery-plan.md

diff --git a/archie/assets/setup-archie-intent-review.sh b/archie/assets/setup-archie-intent-review.sh
new file mode 100755
index 0000000..89229a3
--- /dev/null
+++ b/archie/assets/setup-archie-intent-review.sh
@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# setup-archie-intent-review.sh
+#
+# Idempotent setup for the Archie Intent Review GitHub Action.
+# Prereq checks, secure secret setup, workflow install (copies the canonical
+# YAML — no embedded duplicate), Actions probe, fork-PR caveat.
+#
+# Usage: bash setup-archie-intent-review.sh
+set -euo pipefail
+
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; BLUE='\033[0;34m'; NC='\033[0m'
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="${REPO_ROOT:-.}"
+WORKFLOW_FILE="${REPO_ROOT}/.github/workflows/archie-intent-review.yml"
+
+log_info()    { echo -e "${BLUE}i ${NC}$*"; }
+log_success() { echo -e "${GREEN}OK ${NC}$*"; }
+log_warn()    { echo -e "${YELLOW}! ${NC}$*"; }
+log_error()   { echo -e "${RED}x ${NC}$*"; }
+die() { log_error "$1"; exit 1; }
+
+# Resolve the canonical workflow YAML (single source of truth). Priority:
+#  1. .archie/workflows/  (if the npx bundle ever places it there)
+#  2. <script dir>/workflows/  (running from a checked-out asset bundle)
+resolve_workflow_src() {
+    local candidates=(
+        "${REPO_ROOT}/.archie/workflows/archie-intent-review.yml"
+        "${SCRIPT_DIR}/workflows/archie-intent-review.yml"
+    )
+    for c in "${candidates[@]}"; do
+        if [ -f "$c" ]; then printf '%s\n' "$c"; return 0; fi
+    done
+    return 1
+}
+
+# ===== SECTION 1: PREREQUISITES =====
+log_info "Checking prerequisites..."
+
+git rev-parse --git-dir >/dev/null 2>&1 || die "Not inside a git repository. Run from the repo root."
+log_success "Inside a git repository"
+
+git config --get remote.origin.url >/dev/null 2>&1 || die "No 'origin' remote found."
+log_success "Git remote 'origin' found"
+
+command -v gh >/dev/null 2>&1 || die "gh CLI not found. Install from https://github.com/cli/cli or 'brew install gh'."
+log_success "gh CLI is installed ($(gh --version | head -1))"
+
+gh auth status >/dev/null 2>&1 || die "gh CLI not authenticated. Run 'gh auth login' first."
+GITHUB_ACCOUNT="$(gh api user --jq .login)"
+log_success "gh authenticated as ${GITHUB_ACCOUNT}"
+
+[ -f "${REPO_ROOT}/.archie/blueprint.json" ] || die ".archie/blueprint.json not found. Run '/archie-deep-scan' first to establish the baseline."
+log_success ".archie/blueprint.json baseline exists"
+
+WORKFLOW_SRC="$(resolve_workflow_src)" || die "Canonical workflow YAML not found (looked in .archie/workflows/ and ${SCRIPT_DIR}/workflows/). Reinstall archie assets."
+log_success "Canonical workflow YAML resolved: ${WORKFLOW_SRC}"
+
+# ===== SECTION 2: SECRET SETUP =====
+log_info "Setting up ANTHROPIC_API_KEY secret (available to GitHub Actions on this repo)..."
+printf 'Enter your ANTHROPIC_API_KEY (will not be displayed): '
+read -rs ANTHROPIC_API_KEY
+echo ""
+[ -n "$ANTHROPIC_API_KEY" ] || die "ANTHROPIC_API_KEY cannot be empty."
+
+printf '%s' "$ANTHROPIC_API_KEY" | gh secret set ANTHROPIC_API_KEY
+unset ANTHROPIC_API_KEY
+log_success "ANTHROPIC_API_KEY secret set (stored encrypted on GitHub)"
+
+# ===== SECTION 3: WORKFLOW INSTALL (copy canonical, no heredoc) =====
+log_info "Installing workflow file..."
+mkdir -p "$(dirname "$WORKFLOW_FILE")"
+cp "$WORKFLOW_SRC" "$WORKFLOW_FILE"
+log_success "Workflow installed at ${WORKFLOW_FILE} (byte-identical to canonical)"
+
+# ===== SECTION 4: ACTIONS ENABLEMENT PROBE (advisory) =====
+log_info "Probing GitHub Actions (advisory only)..."
+REPO_SLUG="$(git config --get remote.origin.url | sed 's|.*github.com[:/]||; s|\.git$||')"
+if gh workflow list -R "$REPO_SLUG" >/dev/null 2>&1; then
+    log_success "Actions appear enabled (probe is advisory; verify in repo settings if unsure)"
+else
+    log_warn "Could not verify Actions status — you may need to enable Actions on GitHub"
+fi
+
+# ===== SECTION 5: SUMMARY & CAVEATS =====
+log_success "Setup complete."
+echo ""
+echo "Next steps:"
+echo "  1. Commit .github/workflows/archie-intent-review.yml"
+echo "  2. Push and open a PR"
+echo "  3. The Action posts an FYI comment on the PR"
+echo ""
+echo -e "${YELLOW}Fork PR limitation:${NC}"
+echo "  - Uses the 'pull_request' event (non-blocking FYI)."
+echo "  - Fork PRs cannot access repo secrets; the Action skips silently on them."
+echo "  - To cover fork PRs, 'pull_request_target' is a security tradeoff (out of scope)."
+echo ""
+log_info "To rotate the key later: gh secret set ANTHROPIC_API_KEY"
+log_info "Design doc: docs/archie-intent-review-design.md"
diff --git a/archie/assets/workflows/archie-intent-review.yml b/archie/assets/workflows/archie-intent-review.yml
new file mode 100644
index 0000000..918b4e2
--- /dev/null
+++ b/archie/assets/workflows/archie-intent-review.yml
@@ -0,0 +1,29 @@
+name: Archie Intent Review
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+permissions:
+  pull-requests: write
+  contents: read
+
+jobs:
+  intent-review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Fetch base ref
+        run: git fetch --no-tags --depth=1 origin "${{ github.base_ref }}"
+
+      - name: Run Archie Intent Review
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: python3 .archie/intent_review.py
diff --git a/docs/archie-intent-review-delivery-plan.md b/docs/archie-intent-review-delivery-plan.md
new file mode 100644
index 0000000..d970bca
--- /dev/null
+++ b/docs/archie-intent-review-delivery-plan.md
@@ -0,0 +1,468 @@
+<!-- Generated via a 9-agent research+critique+revise workflow on 2026-06-19. Implements docs/archie-intent-review-design.md. -->
+
+# Archie Intent Review POC — End-to-End Delivery Plan
+
+> Implements `docs/archie-intent-review-design.md` (approved). This plan does not re-litigate the design's decisions (§11) or scope (§10); it makes them buildable. All file paths are repo-relative to `/Users/hamutarto/DEV/Repos/Archie`.
+
+---
+
+## 1. Overview & goal
+
+Archie Intent Review is a GitHub Action that fires on PR open/synchronize, computes a **deterministic structured diff of the architectural source of truth** (`.archie/blueprint.json` + `.archie/rules.json`, branch vs `origin/<base>`), corroborates it with the sync ledger (`.archie/changes/change_*.json`), makes **one Claude Haiku call** to *judge* (not re-derive) that diff against the *retained* rules/invariants, and posts **one upserted FYI comment** flagging silent weakening, contradiction, or behavior-violates-rule. It surfaces; the human decides; it never blocks. The deliverable is **two files dropped into a target repo** (`intent_review.py` + `archie-intent-review.yml`) plus one idempotent `gh`-based setup script, all authored canonically in `archie/` and file-synced to `npm-package/assets/` per the repo's three-tier distribution rule.
+
+**Definition of done for the POC:**
+1. On a real PR to Archie's own repo that folds a blueprint change, the Action posts a correct, verifiable, cited FYI comment grouped by flag — and re-pushes update the same comment (no spam).
+2. The comment honors **because-or-suppress** (§7): every finding carries a cited `because`; findings that can't are dropped, not shown.
+3. Empty/None states (no blueprint diff, no ledger, no findings) produce a minimal or no comment, never a noisy wall (§8 note 5).
+4. The Action degrades safely on fork PRs (no secret → skip cleanly **before any GitHub write**) and on malformed/missing JSON.
+5. `python3 scripts/verify_sync.py` passes with the new files wired in **at every interim commit** (not just at the end); `pytest tests/` green.
+6. The dependency chain (§12) is satisfied: Archie's repo is self-instrumented (deep-scan baseline on `main`, sync run on the test branch) so the first signal isolates the *idea* from *upstream quality*.
+
+---
+
+## 2. Architecture recap
+
+**Two installed files** (design §8), one CI setup helper.
+
+### Inputs the Action gathers (design §5 step 4)
+1. **Proposed change to truth** — structured diff of `.archie/blueprint.json` + `.archie/rules.json`, **branch vs `origin/<base>`** (`github.base_ref`). The base versions are fetched via `git show <base-sha>:.archie/blueprint.json` *after* an explicit `git fetch` of the base ref (see §4). The branch versions are already on disk after `actions/checkout`.
+2. **Evidence behind it** — the **union of all** `.archie/changes/change_*.json` new on the branch, NOT `latest.json` alone (`latest.json` is overwritten on every `record`; each sync writes a unique versioned file via `sync.py` `_next_version`).
+3. **What must still hold** — the *retained* rules/invariants from the base-ref blueprint (rules untouched by the diff), pre-filtered by relevance to bound tokens.
+
+### Division of labor — deterministic script vs. model (critique gap M6, design §4/§11)
+The diff is **deterministic by design**: "no AI to find *what* changed." Therefore:
+- The **script** owns and computes: `diff_op` (REMOVE/UPDATE/ADD/CONFLICT), `rule_id`/keyed id, `layer` (1 vs 2, derived from section + ledger `kind`), and the ledger join.
+- The **model** owns only *judgment*: `type` (which flag), `what_changed` (human prose), `because` (cited rationale), and whether to suppress.
+- The model's output object **echoes** the script's `diff_op`/`rule_id`/`layer` for traceability, but the script **overwrites** those fields from its own diff before rendering — the model's claimed op is never trusted over the deterministic diff. There is therefore no reconciliation ambiguity.
+
+### Real schemas this consumes (from research)
+- **`blueprint.json` invariant-bearing sections** (deep-scan): `domain_invariants[]`, `derived_invariants[]`, `unenforced_invariants[]` (each `{id, entity, category, domain_role, invariant, mechanism, enforced_at[], evidence[], failure_mode, confidence: stated|inferred, keywords[]}`); `decisions.key_decisions[]` (`{title, forced_by, enables, rationale, alternatives_rejected}` — **no id**); `decisions.trade_offs[]` (carry `violation_signals`); `decisions.decision_chain` (root + `forces[].violation_keywords`); `pitfalls[]` (`{id, problem_statement, root_cause, fix_direction, evidence}`).
+- **`rules.json`** is `{rules: [...]}` or a flat legacy list; each rule: `{id, kind, topic, severity_class, description, why, example, source, forced_by, enables, alternative, keywords[], triggers{path_glob[], code_shape[]}, check, applies_to, file_pattern, forbidden_patterns[]}`. Both new and legacy shapes must parse. **A missing or empty `rules.json` (on either side) is treated as `{rules: []}`, never an error** — fresh `archie init` writes an empty `rules.json`, but a repo may predate that, so the absent file is also the empty case.
+- **Ledger claim** (archie-sync / design §3): `{id, kind, status: eligible|staged, statement, evidence_files[], confidence: low|medium|high, reconstructed: bool}` inside a record with `{version, id, folded, provenance{git_head, branch, reconstructed}, diff{changed_files[], affected_folders[], ratio}, claims[]}`. The `kind` advisory/descriptive split gives **Layer 1 vs Layer 2 for free** (design §3): advisory = `decision|pitfall|rule|guideline`, descriptive = `behavior|structure|dataflow|data|tech|reference`.
+
+### One Haiku call → FYI comment
+`claude-haiku-4-5` (exact id, no date suffix) at `https://api.anthropic.com/v1/messages`, `anthropic-version: 2023-06-01`, structured output forced via `tool_use` + `input_schema` (Haiku 4.5 has no `output_config.format`). `max_tokens: 4096` (the Acme worked example alone produces four prose findings; 2048 risks truncation). Comment upserted on `/repos/{owner}/{repo}/issues/{pr}/comments` via hidden marker `<!-- archie-intent-review -->`.
+
+---
+
+## 3. Milestones
+
+> File-sync rule (CLAUDE.md §"File Sync"): author **canonical first**, then byte-copy to the npm asset, then run `scripts/verify_sync.py`. Every code milestone below lists CANONICAL → COPY. **Critical sequencing fix:** the installer/checker wiring (formerly M7) is split — its blocking parts move into **M1** so the repo never enters a sync-failing state. CLAUDE.md mandates `verify_sync.py` before every commit; the moment `intent_review.py` exists in both trees without the `archie.mjs` entry, the checker fails and blocks all interim commits.
+
+### M1 — Installer/checker wiring + `intent_review.py` core (load + diff + glob)
+**Goal:** make the repo sync-clean for the new files *first*, then build deterministic diff + input assembly (no AI yet).
+
+**M1a — Wiring (do this in the same commit that first creates the two `.py` files, before any other work):**
+- Add `"intent_review.py"` to the script list in `npm-package/bin/archie.mjs` (line 359 `const script of [...]`). This makes the installer copy it into every target `.archie/` on `npx` install. **This is required and accepted** — there is no allowlist mechanism in `verify_sync.py`; the script installing everywhere is fine because the workflow invokes it from `.archie/`.
+- Add `"intent_review.py"` to `_STANDALONE_SCRIPTS` in `archie/install.py` (the list at line 52) **AND** to the mirrored `npm-package/assets/_install_pkg/install.py` (byte-checked by `check_install_pkg_mirror` in `verify_sync.py` — editing only the canonical fails the check).
+- Extend `scripts/verify_sync.py` with the **three concrete checker edits** the byte-identical guarantee actually requires (none exist today; see §6 "verify_sync edits"). Land these in M1a so they're green the instant the new files appear.
+- Do **NOT** add to `manifest_data.py:COMMANDS`, do **NOT** write a SKILL.md, do **NOT** add a `_copy_github_workflows()` to `install.py` — intent-review is not a user-facing skill, and the setup script is the **sole** installer of the workflow `.yml` (see §5 / §8 decision). The `npx` installer does not inject `.github/workflows/`.
+
+**M1b — Core script (`intent_review.py`):**
+- Skeleton: read env (`ANTHROPIC_API_KEY`, `GITHUB_TOKEN`, `GITHUB_REPOSITORY`, `GITHUB_BASE_REF`, `GITHUB_EVENT_PATH`), stdlib-only.
+- **Derive owner/repo/PR number explicitly** (critique low gap): split `GITHUB_REPOSITORY` on `/` → `owner, repo`; parse `json.load(open(GITHUB_EVENT_PATH))["pull_request"]["number"]` → `pr_number`. Implement `parse_event_context()` returning `(owner, repo, pr_number, base_ref)`; fail clean (exit 0) if the payload lacks `pull_request`.
+- **Early fork-PR / no-secret guard FIRST**, before any diff or GitHub call: if `ANTHROPIC_API_KEY` is empty → log + `exit 0` (fork PRs have read-only `GITHUB_TOKEN` and no secret; exiting before any write means even the "cannot parse" marker is never attempted on a fork, satisfying "degrade safely on fork PRs").
+- Implement `fetch_base_file(repo_root, rel_path, base_ref)` via `subprocess git show <base_ref>:<path>` returning `(exists, dict|None, error)`. Missing-on-base (`returncode != 0` with "does not exist"/"Invalid object") → treat all branch items as ADD. Apply the same to `rules.json`: **base-side AND branch-side missing/empty `rules.json` → empty list, not crash.**
+- Implement `keyed_diff(base_section, branch_section, id_field, title_field)` → list of `{id, status: REMOVE|UPDATE|ADD, base_item, branch_item, fields_changed}`. Fall back to `_hash_title()` when `id` absent (domain_invariants on older blueprints; all of `key_decisions`/`trade_offs`).
+- Wire the section→key map: keyed-by-`id` = `domain_invariants`, `derived_invariants`, `unenforced_invariants`, `rules.rules`, `platform_rules.rules`; keyed-by-`name` = `data_models`, `persistence_stores`; heuristic-by-`title` = `decisions.key_decisions`, `decisions.trade_offs`, `decisions.out_of_scope`. Everything else → textual hunk (suppress if > 500 tokens).
+- Implement `glob_ledger(repo_root, base_ref)`: enumerate `.archie/changes/change_*.json`, union all claims new on the branch (records not present on base ref). Defensive parse; skip malformed records.
+- Compute `retained_rules`: base-ref rules whose `id` is NOT in the diff's UPDATE/REMOVE set, pre-filtered by keyword overlap with changed invariant/decision titles (design §13 Q2 → relevance pre-filter, see §4).
+- Malformed/missing JSON: catch `json.JSONDecodeError`; if branch blueprint unparseable → post marker comment "Cannot parse blueprint.json; manual review needed." then exit 0. (This path runs only after the secret guard, so it never fires on a fork.)
+
+**Deliverable files:**
+- CANONICAL `archie/standalone/intent_review.py` → COPY `npm-package/assets/intent_review.py`
+- Edits: `archie/install.py` (+ `npm-package/assets/_install_pkg/install.py` mirror), `npm-package/bin/archie.mjs`, `scripts/verify_sync.py`
+
+**Acceptance criteria:** `python3 scripts/verify_sync.py` exits 0 with the new files present. Given fixtures (`tests/fixtures/blueprint_domain_invariants.json`, `tests/fixtures/legacy_rules.json`), the diff emits correct REMOVE/UPDATE/ADD on `domain_invariants[]` and `rules[]` by id, and on `key_decisions[]` by title hash; reordered-but-unchanged arrays produce zero diffs; missing base file → all-ADD; missing/empty `rules.json` either side → empty list; malformed JSON handled without crash; `parse_event_context` extracts owner/repo/PR correctly from a sample event payload.
+**Dependencies:** none.
+
+### M2 — Anthropic structured-output call + finding schema
+**Goal:** turn the assembled diff into structured *judgments* (the script already computed *what* changed).
+**Tasks:**
+- Implement `call_anthropic(blueprint_diff, rules_diff, ledger_claims, retained_rules, max_retries=3)`: urllib POST, headers `x-api-key`/`anthropic-version: 2023-06-01`/`content-type`, `claude-haiku-4-5`, `max_tokens: 4096`, `tool_use` with the `emit_findings` `input_schema` (§5). Read `block["input"]` directly (already a dict — no second `json.loads`). Retry on 429/500/502/503 with `min(2**attempt, 60)` backoff, honoring `Retry-After`.
+- **Script overwrites deterministic fields:** after the model returns, for each finding the script replaces `diff_op`/`rule_id`/`layer` with the values from its own keyed diff (matched on the finding's referenced item), discarding the model's echo. A finding the model emits that references no real diff item is dropped.
+- Build the prompt: system = "architecture reviewer; the diff op and which rule changed are GIVEN — judge whether it's a silent weakening / contradiction / behavior-violates-rule, and produce a cited because; because-or-suppress"; user = changed sections (with their deterministic `diff_op`/ids) + retained rules + ledger claims (token-bounded payload, §4).
+- Enforce **because-or-suppress** post-hoc: drop any finding whose `because` is empty/blank before it reaches the comment (design §7, §9).
+- **Severity sharpening via the explicit, conservative ledger join (critique medium gap, §4):** map ledger confidence/`reconstructed` onto a finding *only* when the join succeeds (claim `evidence_files` ∩ invariant `enforced_at` file paths AND keyword overlap above threshold). When the join fails, the finding still surfaces (a REMOVE is the corruption case) but **without** the confidence sharpener rather than guessing — guessing is exactly the because-theater the design forbids.
+
+**Deliverable files:** same `intent_review.py` (CANONICAL → COPY).
+**Acceptance criteria:** With a known REMOVE of a `domain_invariant`, the call returns a `silent_weakening` finding naming the invariant id with the script's deterministic `diff_op: REMOVE` and a cited `because`; a finding lacking a because is suppressed; a finding whose model-claimed op disagrees with the diff has the op overwritten from the diff; a join that fails emits the finding without confidence; wrong model id / missing key fails loudly (`RuntimeError`).
+**Dependencies:** M1.
+
+### M3 — PR comment upsert
+**Goal:** one comment, deduped, FYI framing.
+**Tasks:**
+- Implement `post_or_update_comment(owner, repo, pr_number, findings)`: GET `/repos/{owner}/{repo}/issues/{pr_number}/comments`, find body containing `<!-- archie-intent-review -->`, PATCH if found else POST. (PR number = issue number for this endpoint; owner/repo/pr_number are passed in from `parse_event_context`, M1b.)
+- Render body grouped by flag (Silent weakening / Contradiction / Behavior-violates-rule), each with affected rule/invariant, the deterministic `diff_op`, the cited `because`, and ledger confidence/provenance **only where the join succeeded** (design §7; example §Appendix A of design doc).
+- Footer: "Archie surfaces; it doesn't block. Merge accepts the rule changes above as the new baseline."
+- Empty/None states: zero findings AND there *was* a blueprint diff → minimal "No findings — blueprint changes consistent with retained rules." No blueprint diff at all → post nothing (return before any GitHub call), per §8 note 5.
+- Exit code 0 always (non-blocking, design §9).
+
+**Deliverable files:** same `intent_review.py` (CANONICAL → COPY).
+**Acceptance criteria:** First run POSTs; second run on same PR PATCHes the same comment id (verified by marker); no-diff run posts nothing; findings render grouped with cited becauses.
+**Dependencies:** M2.
+
+### M4 — Workflow YAML (single canonical source)
+**Goal:** the CI entry point that runs the script — authored **once**, consumed by the setup script.
+**Tasks:**
+- Author the static workflow (no template tokens): `on: pull_request` (`opened`, `synchronize`); `permissions: { pull-requests: write, contents: read }`; `actions/checkout@v4` with `fetch-depth: 0`; `actions/setup-python@v5` (`3.11`); an explicit base-ref fetch step; then `python3 .archie/intent_review.py`.
+- **Explicit base-ref fetch (critique medium gap):** `fetch-depth: 0` fetches the PR head history but does **not** guarantee `origin/<base>` is resolvable. Add a step before the script:
+  ```yaml
+  - name: Fetch base ref
+    run: git fetch --no-tags --depth=1 origin "${{ github.base_ref }}"
+  ```
+  The script then diffs against `origin/${GITHUB_BASE_REF}`. (Verify on a real Action run, not just locally — critique flags this as a CI-only failure mode.)
+- Pass `ANTHROPIC_API_KEY` (secret) + `GITHUB_TOKEN` (built-in) as `env`. Use `pull_request` (NOT `pull_request_target`) — fork-PR secret limitation accepted for POC (design §8). The script's M1b guard exits 0 silently when the secret is empty.
+
+**Deliverable files:**
+- CANONICAL `archie/assets/workflows/archie-intent-review.yml` (new **`workflows/` plural** dir, distinct from the singular skill `workflow/` tree) → COPY `npm-package/assets/workflows/archie-intent-review.yml`. Installed to target `<repo>/.github/workflows/archie-intent-review.yml` **by the setup script only**.
+
+**Acceptance criteria:** Valid GitHub workflow schema; the fetch step makes `origin/<base>` resolvable; running it on a PR invokes the script; fork PR run skips cleanly; `verify_sync.py` confirms the canonical↔asset `workflows/` byte mirror.
+**Dependencies:** M1–M3 (script must exist to invoke). M4 is the **sole** definition of the YAML — M5 copies it, never re-authors it.
+
+### M5 — `gh` setup script (copies the canonical YAML, no heredoc duplicate)
+**Goal:** one-command, idempotent CI enablement, with a **single source of truth** for the workflow YAML.
+**Tasks:**
+- The setup script does prereq checks (git repo, origin remote, `gh` installed + authed, `.archie/blueprint.json` baseline), silent `ANTHROPIC_API_KEY` via stdin → `gh secret set` (client-side encrypted), then **installs the workflow by copying the already-present asset**, not by embedding a heredoc. The script resolves the YAML from one of two locations in priority order: (1) `.archie/workflows/archie-intent-review.yml` (the path the `npx` installer would have to place — see note below), else (2) the script's own sibling `setup-archie-intent-review.sh`-adjacent `workflows/archie-intent-review.yml` (present when run from a checked-out Archie asset bundle). This collapses the dual-source-of-truth problem the critique flagged: there is no second copy of the YAML body to drift.
+- **Note on YAML availability:** because the `npx` installer copies `.py` scripts but the plan deliberately does **not** auto-inject `.github/workflows/`, the setup script needs the canonical `.yml` on disk to copy. Ship the canonical `.yml` alongside the setup script in the asset bundle (`archie/assets/workflows/` and its mirror) and have the setup script look there. If neither location resolves, the script `die`s with a clear message ("canonical workflow YAML not found — reinstall archie assets"), rather than falling back to an embedded copy.
+- Actions-enabled probe (cosmetic warning only — `gh workflow list` can succeed even when Actions are disabled; treat its result as advisory), fork-PR caveat summary.
+
+**Deliverable files:**
+- CANONICAL `archie/assets/setup-archie-intent-review.sh` → COPY `npm-package/assets/setup-archie-intent-review.sh`. One-time installer helper (NOT copied into target `.archie/`; run from the repo root by the user).
+
+**Acceptance criteria:** Re-runnable without cleanup (secret overwrite, workflow upsert); fails loudly if `.archie/blueprint.json` missing, `gh` unauthed, or canonical YAML unresolvable; secret never echoed to history; the installed `.github/workflows/archie-intent-review.yml` is **byte-identical** to `archie/assets/workflows/archie-intent-review.yml` (no heredoc divergence possible). `verify_sync.py` confirms the `.sh` canonical↔copy.
+**Dependencies:** M4 (canonical YAML must exist to copy), M1–M3 (script the YAML invokes).
+
+### M6 — Dogfood on Archie's own repo (instrumentation is a hard prerequisite)
+**Goal:** prove the comment appears and is correct, isolating idea from upstream quality (design §12, §13 Q5).
+**Tasks (sequenced — the instrumentation step gates M5's acceptance too, not just M6):**
+- **Instrument Archie itself FIRST and commit the baseline to `main` before cutting the dogfood branch.** Run `/archie-deep-scan` to produce `.archie/blueprint.json` + `rules.json`; verify the baseline is non-trivia (real `domain_invariants`/`decisions`, not housekeeping) — a trivia blueprint invalidates the POC signal. **This `main` baseline is also what makes `setup-archie-intent-review.sh`'s `.archie/blueprint.json` prereq check pass; without it M5 cannot be exercised at all.** This step is independent code and can start in parallel with M1, but it MUST land on `main` before M5's acceptance run and before M6's branch.
+- Cut a feature branch with a **deliberate, known** change whose fold should REMOVE/UPDATE a load-bearing invariant or contradict a retained rule (mirror the design's Acme worked example, Appendix A). Run `/archie-sync` so Phase 2 folds onto the branch; commit code + folded `blueprint.json`/`rules.json` + `.archie/changes/change_*.json`.
+- Run `setup-archie-intent-review.sh`, push, open the PR, observe the comment.
+- **Diagnose any bad review** per the interpretation rule (§7 below / design §12) BEFORE concluding the idea failed.
+
+**Deliverable files:** committed `.archie/` baseline on `main`; a dogfood PR; a short results note (in PR description, NOT a tracked `.md`).
+**Acceptance criteria:** Comment posts, is correct and cited, updates on re-push; at least one finding matches the planted intent; any miss is attributed to an idea-vs-upstream cause.
+**Dependencies:** baseline-on-`main` (the instrumentation step) precedes M5's acceptance run AND M6; M6's PR step needs M1–M5 complete.
+
+### M7 — Tests
+**Goal:** ship-ready test coverage. (Wiring + checker edits moved to M1a; M7 is now tests only.)
+**Tasks:**
+- Unit tests (`tests/test_intent_review.py`): `keyed_diff` (REMOVE/UPDATE/ADD, title-hash fallback, reorder no-op), `fetch_base_file` (missing/malformed, missing-rules→empty), `glob_ledger` (multi-`change_*.json` union, skip malformed, dedup by claim id), `parse_event_context` (owner/repo split, PR number parse, missing-`pull_request` clean exit), the deterministic-field-overwrite logic, the conservative ledger-join (match success annotates, join failure surfaces-without-confidence), comment-body rendering, and the because-or-suppress filter.
+- Mock urllib for the Anthropic + GitHub calls (no network in tests).
+- **Parallelization caveat (sequencing fix):** only the M1 diff/glob/event-parse tests are writable from the start. Tests for `call_anthropic` (M2) and `post_or_update_comment` (M3) can't be written until those signatures are fixed — schedule them after M2/M3 respectively, not "from M1."
+
+**Deliverable files:** `tests/test_intent_review.py`.
+**Acceptance criteria:** `pytest tests/ -v` green.
+**Dependencies:** M1 (for M1-scope tests); M2/M3 (for their respective tests).
+
+**Suggested order:** M1 (incl. M1a wiring + checker, M1b core) → M2 → M3 → M4 → M5 → M6. The instrumentation step of M6 (deep-scan + sync baseline on `main`) starts in parallel with M1 but must merge to `main` before M5's acceptance run. M7 tests track their milestone (M1 tests with M1, M2/M3 tests after those land). **Any later YAML change touches only M4's canonical asset — M5 copies it, so there is exactly one place to edit.**
+
+---
+
+## 4. Blueprint/rules diff algorithm
+
+Deterministic, zero-dependency. The script computes `diff_op` and keyed ids; the model never re-derives them (§2).
+
+**Base-ref fetch:** the workflow runs `git fetch --no-tags --depth=1 origin "$GITHUB_BASE_REF"` (M4) so `origin/<base>` resolves. The script then runs `git show origin/<base_ref>:.archie/blueprint.json` (and `rules.json`, `platform_rules.json`) via `subprocess.run([...], timeout=10)`, returning `(exists, dict|None, error)`. `returncode != 0` with "does not exist"/"Invalid object" → file absent on base (new on branch) → all-ADD. Missing/empty `rules.json` either side → empty list. JSON parse failure on the branch blueprint → "cannot parse" marker comment, exit 0. Branch versions read directly from disk (checkout already placed them). Use `origin/<base_ref>`, never local `HEAD`/`main`.
+
+**Keyed semantic diff** (preferred — high precision):
+```
+For each keyed section:
+  base_by_key   = { item[id_field] or _hash_title(item[title_field]): item }
+  branch_by_key = { ... same ... }
+  REMOVE = keys in base not in branch
+  UPDATE = keys in both whose dicts differ (emit fields_changed)
+  ADD    = keys in branch not in base
+```
+- **Keyed by `id`:** `domain_invariants[]`, `derived_invariants[]`, `unenforced_invariants[]`, `rules.rules[]`, `platform_rules.rules[]`.
+- **Keyed by `name`:** `data_models[]`, `persistence_stores[]`.
+- **Heuristic by `title` hash** (no id field): `decisions.key_decisions[]`, `decisions.trade_offs[]`, `decisions.out_of_scope[]`. Caveat: a RENAME reads as REMOVE+ADD, not UPDATE — note this in the finding rendering so the model isn't misled.
+- **`_hash_title()`** = `"title_" + md5(title)[:8]`; also the fallback when a `domain_invariant` lacks `id` (older blueprints).
+
+**Textual fallback:** `components[]`, `communication[]`, `architecture_diagram`, `architecture_rules`, and `decisions.architectural_style` (a single dict, not an array) → send the raw `git diff` hunk **only if < 500 tokens**; suppress larger hunks (too noisy for semantic review).
+
+**Token bounding** (design §13 Q2 → relevance pre-filter): send only sections WITH changes + the changed items themselves (not the whole 50–150 KB blueprint) + `retained_rules` pre-filtered to those whose `keywords`/`description` overlap the changed invariant/decision titles + the unioned ledger claims. Target payload ~5 KB / ~5000 tokens.
+
+**Severity sharpening — the explicit, conservative ledger join (critique medium gap):** a domain_invariant has `enforced_at[]` (file:line) and `keywords[]`; a ledger claim has `evidence_files[]` (file paths) and a free-text `statement`. There is no shared id, so the join is defined as:
+```
+match(diff_item, claim) is TRUE iff
+    file_set(claim.evidence_files) ∩ file_set(diff_item.enforced_at paths)  is non-empty
+    AND  keyword_overlap(claim.statement tokens, diff_item.keywords)  >= THRESHOLD
+```
+On match, pull the claim's `confidence` + `reconstructed` and apply the sharpener (e.g. REMOVE of a `domain_invariant` backed by `confidence: low, reconstructed: true` = highest severity, design §6). **On no match, the finding still surfaces but carries no confidence annotation** — an unmatched REMOVE is the corruption case and must be shown; it simply loses the ledger-confidence sharpener rather than receiving a guessed one. Guessing an attribution is the because-theater the design forbids.
+
+**Edge cases:** rules files optional → missing = empty list. Both rule sources (`rules.json` + `platform_rules.json`) diffed.
+
+---
+
+## 5. Finding JSON schema (model output) + flag mapping
+
+The model is forced to call `emit_findings` (Haiku 4.5 has no `output_config.format`; must use `tool_use` + `input_schema`). The model **judges**; the script **owns** `diff_op`/`rule_id`/`layer` and overwrites them post-call (§2):
+
+```json
+{
+  "name": "emit_findings",
+  "description": "Emit structured review findings. The diff op and which rule changed are GIVEN to you per item — judge the TYPE and produce a cited BECAUSE. Because-or-suppress: omit any finding lacking a verifiable cited because.",
+  "input_schema": {
+    "type": "object",
+    "properties": {
+      "findings": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "type":         { "type": "string", "enum": ["silent_weakening", "contradiction", "behavior_violates_rule"] },
+            "rule_name":    { "type": "string", "description": "Which retained rule/invariant this is about." },
+            "what_changed": { "type": "string" },
+            "because":      { "type": "string", "description": "Verifiable, cited rationale drawn from the two texts. Empty/uncited => finding is dropped." },
+            "diff_op":      { "type": "string", "enum": ["REMOVE","UPDATE","ADD","CONFLICT"], "description": "ECHO of the given op; the script overwrites this from its deterministic diff." },
+            "rule_id":      { "type": "string", "description": "ECHO of the given id; the script overwrites this." },
+            "layer":        { "type": "integer", "enum": [1,2], "description": "ECHO of the given layer; the script overwrites this." }
+          },
+          "required": ["type", "rule_name", "what_changed", "because"]
+        }
+      },
+      "severity_notes": { "type": "array" }
+    },
+    "required": ["findings", "severity_notes"]
+  }
+}
+```
+
+Note `diff_op`/`rule_id`/`layer` are **not required** of the model and are **echo-only** — the script overwrites each from its own keyed diff before rendering, and drops any finding that references no real diff item. This removes the disagreement-with-no-reconciliation-rule problem.
+
+**Mapping to the three flags (design §6) and Layers — all computed by the script:**
+
+| `type` | Detected from (deterministic) | Layer (script-set) | Diff source |
+|---|---|---|---|
+| `silent_weakening` | REMOVE/UPDATE retiring or softening a `domain_invariant` / `decisions.key_decisions` | **Layer 1** (rule-vs-rule) | keyed diff of `domain_invariants[]` / `decisions` |
+| `contradiction` | ADD/UPDATE conflicting with a *retained* rule | **Layer 1** (text-vs-text) | `rules.json` diff vs retained rules |
+| `behavior_violates_rule` | a **descriptive** claim/blueprint change implying a retained rule is now broken | **Layer 2** (behavior-vs-rule) | descriptive `blueprint.json` diff + descriptive ledger claims (`behavior|structure|dataflow|data|tech|reference`) |
+
+The ledger `kind` split supplies Layer 1 vs Layer 2: advisory kinds (`decision|pitfall|rule|guideline`) → Layer 1; descriptive kinds → Layer 2 (design §3). **Layer 3 (raw code) is out of scope.** **Because-or-suppress** is enforced twice: the prompt instructs it, and `intent_review.py` drops any finding with empty/blank `because` post-call (design §7).
+
+---
+
+## 6. Setup script + verify_sync edits (verbatim, runnable)
+
+> **Single source of truth for the YAML:** the setup script **copies** the canonical `archie/assets/workflows/archie-intent-review.yml` (resolved on disk) — it does **not** embed a heredoc copy. This eliminates the silent-divergence risk the critique identified.
+
+> **Fork-PR / secret caveat (call-out):** uses the `pull_request` event (non-blocking FYI). Per GitHub's security model, **fork PRs cannot access repository secrets** — so `ANTHROPIC_API_KEY` is unavailable and the Action skips silently *before any GitHub write* on external contributions. Accepted for the POC. Switching to `pull_request_target` to cover forks is a deliberate security tradeoff, explicitly out of scope.
+
+### The setup script (`archie/assets/setup-archie-intent-review.sh`)
+
+```bash
+#!/usr/bin/env bash
+# setup-archie-intent-review.sh
+#
+# Idempotent setup for the Archie Intent Review GitHub Action.
+# Prereq checks, secure secret setup, workflow install (copies the canonical
+# YAML — no embedded duplicate), Actions probe, fork-PR caveat.
+#
+# Usage: bash setup-archie-intent-review.sh
+set -euo pipefail
+
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; BLUE='\033[0;34m'; NC='\033[0m'
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="${REPO_ROOT:-.}"
+WORKFLOW_FILE="${REPO_ROOT}/.github/workflows/archie-intent-review.yml"
+
+log_info()    { echo -e "${BLUE}i ${NC}$*"; }
+log_success() { echo -e "${GREEN}OK ${NC}$*"; }
+log_warn()    { echo -e "${YELLOW}! ${NC}$*"; }
+log_error()   { echo -e "${RED}x ${NC}$*"; }
+die() { log_error "$1"; exit 1; }
+
+# Resolve the canonical workflow YAML (single source of truth). Priority:
+#  1. .archie/workflows/  (if the npx bundle ever places it there)
+#  2. <script dir>/workflows/  (running from a checked-out asset bundle)
+resolve_workflow_src() {
+    local candidates=(
+        "${REPO_ROOT}/.archie/workflows/archie-intent-review.yml"
+        "${SCRIPT_DIR}/workflows/archie-intent-review.yml"
+    )
+    for c in "${candidates[@]}"; do
+        if [ -f "$c" ]; then printf '%s\n' "$c"; return 0; fi
+    done
+    return 1
+}
+
+# ===== SECTION 1: PREREQUISITES =====
+log_info "Checking prerequisites..."
+
+git rev-parse --git-dir >/dev/null 2>&1 || die "Not inside a git repository. Run from the repo root."
+log_success "Inside a git repository"
+
+git config --get remote.origin.url >/dev/null 2>&1 || die "No 'origin' remote found."
+log_success "Git remote 'origin' found"
+
+command -v gh >/dev/null 2>&1 || die "gh CLI not found. Install from https://github.com/cli/cli or 'brew install gh'."
+log_success "gh CLI is installed ($(gh --version | head -1))"
+
+gh auth status >/dev/null 2>&1 || die "gh CLI not authenticated. Run 'gh auth login' first."
+GITHUB_ACCOUNT="$(gh api user --jq .login)"
+log_success "gh authenticated as ${GITHUB_ACCOUNT}"
+
+[ -f "${REPO_ROOT}/.archie/blueprint.json" ] || die ".archie/blueprint.json not found. Run '/archie-deep-scan' first to establish the baseline."
+log_success ".archie/blueprint.json baseline exists"
+
+WORKFLOW_SRC="$(resolve_workflow_src)" || die "Canonical workflow YAML not found (looked in .archie/workflows/ and ${SCRIPT_DIR}/workflows/). Reinstall archie assets."
+log_success "Canonical workflow YAML resolved: ${WORKFLOW_SRC}"
+
+# ===== SECTION 2: SECRET SETUP =====
+log_info "Setting up ANTHROPIC_API_KEY secret (available to GitHub Actions on this repo)..."
+printf 'Enter your ANTHROPIC_API_KEY (will not be displayed): '
+read -rs ANTHROPIC_API_KEY
+echo ""
+[ -n "$ANTHROPIC_API_KEY" ] || die "ANTHROPIC_API_KEY cannot be empty."
+
+printf '%s' "$ANTHROPIC_API_KEY" | gh secret set ANTHROPIC_API_KEY
+unset ANTHROPIC_API_KEY
+log_success "ANTHROPIC_API_KEY secret set (stored encrypted on GitHub)"
+
+# ===== SECTION 3: WORKFLOW INSTALL (copy canonical, no heredoc) =====
+log_info "Installing workflow file..."
+mkdir -p "$(dirname "$WORKFLOW_FILE")"
+cp "$WORKFLOW_SRC" "$WORKFLOW_FILE"
+log_success "Workflow installed at ${WORKFLOW_FILE} (byte-identical to canonical)"
+
+# ===== SECTION 4: ACTIONS ENABLEMENT PROBE (advisory) =====
+log_info "Probing GitHub Actions (advisory only)..."
+REPO_SLUG="$(git config --get remote.origin.url | sed 's|.*github.com[:/]||; s|\.git$||')"
+if gh workflow list -R "$REPO_SLUG" >/dev/null 2>&1; then
+    log_success "Actions appear enabled (probe is advisory; verify in repo settings if unsure)"
+else
+    log_warn "Could not verify Actions status — you may need to enable Actions on GitHub"
+fi
+
+# ===== SECTION 5: SUMMARY & CAVEATS =====
+log_success "Setup complete."
+echo ""
+echo "Next steps:"
+echo "  1. Commit .github/workflows/archie-intent-review.yml"
+echo "  2. Push and open a PR"
+echo "  3. The Action posts an FYI comment on the PR"
+echo ""
+echo -e "${YELLOW}Fork PR limitation:${NC}"
+echo "  - Uses the 'pull_request' event (non-blocking FYI)."
+echo "  - Fork PRs cannot access repo secrets; the Action skips silently on them."
+echo "  - To cover fork PRs, 'pull_request_target' is a security tradeoff (out of scope)."
+echo ""
+log_info "To rotate the key later: gh secret set ANTHROPIC_API_KEY"
+log_info "Design doc: docs/archie-intent-review-design.md"
+```
+
+> The setup script ships **alongside** `workflows/archie-intent-review.yml` in the asset bundle so `resolve_workflow_src` finds it. The bundle layout under `archie/assets/` (and its `npm-package/assets/` mirror) is: `setup-archie-intent-review.sh` + `workflows/archie-intent-review.yml`.
+
+### The canonical workflow YAML (`archie/assets/workflows/archie-intent-review.yml`)
+
+```yaml
+name: Archie Intent Review
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+permissions:
+  pull-requests: write
+  contents: read
+
+jobs:
+  intent-review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Fetch base ref
+        run: git fetch --no-tags --depth=1 origin "${{ github.base_ref }}"
+
+      - name: Run Archie Intent Review
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: python3 .archie/intent_review.py
+```
+
+### verify_sync.py edits (three concrete checks — none exist today)
+
+The current `verify_sync.py` only globs `*.py`/`*.json` for content equality, mirrors the **singular** `workflow/` tree, and has **no allowlist**. To make the byte-identical guarantee real, M1a adds, inside `check_archie_asset_mirrors` (or a new sibling function called from `main`):
+
+1. **`workflows/` (plural) byte-mirror** — parallel to the existing singular-`workflow/` block (lines ~173–204): compare every file under `archie/assets/workflows/` against `npm-package/assets/workflows/`, flagging missing, stale, and content-differing files.
+2. **`.yml` content check** — the new mirror must compare `.yml` bytes (the main loop only does `.py`/`.json`); the plural-dir block above handles this by globbing all files, not just `*.py`/`*.json`.
+3. **Setup `.sh` canonical→copy** — add a direct byte check `archie/assets/setup-archie-intent-review.sh` ↔ `npm-package/assets/setup-archie-intent-review.sh` (the `.sh` is not covered by any existing glob), mirroring the `archieignore.default`/`gitignore.default` pattern already in `check_archie_asset_mirrors` (lines ~165–171).
+
+These are explicit code edits in M1a, not afterthoughts — without them the `.yml` mirror and the `.sh` have **zero** sync enforcement and will silently drift.
+
+---
+
+## 7. Testing & dogfood strategy
+
+**Unit (no network, M7):** mock urllib for both Anthropic and GitHub. Cover `keyed_diff` (REMOVE/UPDATE/ADD + title-hash fallback + reorder-is-no-op), `fetch_base_file` (missing → all-ADD, malformed → "cannot parse", missing-rules → empty), `glob_ledger` (multi-file union, skip malformed, dedup by claim id), `parse_event_context` (owner/repo split, PR number, missing-`pull_request` clean exit), the deterministic-field-overwrite, the conservative ledger-join (match annotates, no-match surfaces-without-confidence), comment-body rendering grouped by flag, and the because-or-suppress filter.
+
+**Instrument Archie itself first (design §12, §13 Q5 → instrument in-repo, no separate fixture):**
+1. Run `/archie-deep-scan` on Archie's own repo; commit `.archie/blueprint.json` + `rules.json` to `main`. **Verify the baseline is substantive** — real `domain_invariants` and `decisions`, not housekeeping trivia. A trivia baseline must be fixed before dogfooding, or the POC signal is meaningless. **This baseline-on-`main` also unblocks the `setup-archie-intent-review.sh` prereq check (M5 acceptance) — it is a hard prerequisite for M5, not only M6.**
+2. On a branch, make a planted change mirroring the design's Appendix A (e.g. fold UPDATEs a load-bearing invariant to "allow unscoped X for performance," plus a descriptive claim contradicting a retained `decision`). Run `/archie-sync` (Phase 2 folds on-branch), commit code + folded blueprint/rules + `change_*.json`.
+3. Run the setup script, push, open the PR, read the comment.
+
+**Interpreting a bad review (design §12 interpretation rule — non-negotiable):** the POC tests three things at once — the *review idea*, *sync's fold quality*, and *the blueprint's quality*. When a review is wrong or empty, **first diagnose whether the idea was wrong OR the upstream input (claim/baseline) was wrong** before concluding anything about the concept. Checklist: (a) Did the baseline actually contain the invariant the review should have caught? If not → blueprint-quality problem, not idea. (b) Did sync fold the planted change with an eligible claim? If not → sync-quality problem. (c) Only if both upstream stages produced correct inputs and the review still missed/misfired is it an *idea* signal. Dogfooding on Archie's own repo (where you control what sync should produce) is what isolates the idea from upstream quality.
+
+---
+
+## 8. Risks, mitigations & resolved open questions
+
+### Decisions this plan commits to (critique-flagged ambiguities, now resolved)
+- **Single owner of `.github/workflows/archie-intent-review.yml`:** the **setup script**, exclusively. The `npx` installer does **NOT** auto-inject the workflow (it can't set the Actions secret anyway, and a double-writer would clobber a user's file on every `npx` run). No `_copy_github_workflows()` is added to `install.py` — this also removes the need to mirror an `install.py` workflow-injection change.
+- **Single source of truth for the YAML:** the canonical `archie/assets/workflows/archie-intent-review.yml`. The setup script copies it; there is no heredoc duplicate, so no equivalence test is needed (the dual-source problem is designed out, not tested around).
+- **No allowlist in `verify_sync.py`:** `intent_review.py` is added to `archie.mjs` + both `install.py` copies and installs to `.archie/` everywhere. Accepted.
+
+### Risks & mitigations
+| Risk | Mitigation |
+|---|---|
+| `latest.json` read as single source → miss earlier syncs | Glob ALL `.archie/changes/change_*.json`; union claims (design §8 note 2). |
+| Whole 50–150 KB blueprint blows token budget/cost | Send only changed sections + changed items + relevance-filtered retained rules; ~5 KB payload (§4). |
+| `key_decisions`/`trade_offs` have no `id` → RENAME reads as REMOVE+ADD | Title-hash keying; flag this limitation in finding text. |
+| Model re-derives `diff_op`/ids and disagrees with the diff | Script computes these deterministically and overwrites the model's echo (§2, §5). |
+| Wrong ledger attribution = because-theater | Conservative join (file-overlap AND keyword threshold); no match → surface without confidence, never guess (§4). |
+| Because-theater (plausible-but-wrong cited prose) | Structured inputs only (Layer 3 deferred); because-or-suppress in prompt AND post-call (design §9). |
+| Cry-wolf death spiral | Non-blocking FYI, exit 0 always, minimal/no comment on empty states. |
+| Fork PR has no secret → confusing failure / failed write | Script early-exits 0 when `ANTHROPIC_API_KEY` empty, **before any GitHub call** (so the read-only fork `GITHUB_TOKEN` is never exercised). |
+| `origin/<base>` unresolvable in CI despite `fetch-depth: 0` | Explicit `git fetch --no-tags origin "$github.base_ref"` step in the workflow (M4, §6); verify on a real Action run. |
+| Missing/empty `rules.json` on either side | Treated as `{rules: []}`, not an error (§2, §4). |
+| `max_tokens` truncates multi-finding output | `max_tokens: 4096` (Acme example alone has 4 prose findings). |
+| `verify_sync.py` blocks interim commits | Wiring + the three checker edits land in **M1a**, before the new files exist standalone — repo never sync-fails. |
+| Two script-list sources (`archie.mjs` + `install.py` + its mirror) | Add to all three in M1a; note a future single-source refactor. |
+
+### Design §13 open questions — resolved
+1. **Diff granularity** → semantic-keyed where keys exist (`id`/`name`), title-hash for `key_decisions`/`trade_offs`, textual hunks (<500 tok) otherwise.
+2. **Which retained rules to feed** → relevance pre-filter on keyword/description overlap with changed titles.
+3. **Comment marker** → hidden HTML comment `<!-- archie-intent-review -->`, clean upsert.
+4. **Failure/auth modes** → missing key/fork PR → skip silently, exit 0 **before any GitHub write**; API error → retry then `RuntimeError`; malformed branch JSON → "cannot parse" marker comment.
+5. **Dogfood prerequisite** → instrument Archie's own repo (deep-scan + sync); baseline-on-`main` is a hard prerequisite for M5 acceptance and M6.
+6. **Where the files live** → `archie/standalone/intent_review.py` → `npm-package/assets/`; workflow in new `archie/assets/workflows/` (plural) → `npm-package/assets/workflows/`; setup script `archie/assets/setup-archie-intent-review.sh` → `npm-package/assets/`; **no** `manifest_data.py:COMMANDS` entry, **no** SKILL.md, **no** `.github/workflows` injection by the `npx` installer.
+
+### Genuinely still open (flag for implementer)
+- **Are `derived_invariants` / `unenforced_invariants` keyed-diffed like `domain_invariants`, or sent textually?** Both carry `id` (keyable), but `unenforced_invariants` are gaps not stated law — recommend: keyed-diff `derived_invariants` (reasoned law), treat `unenforced_invariants` as advisory (don't raise silent-weakening on its removal). Confirm during M2 prompt tuning.
+- **Does a pure `key_decision.rationale` UPDATE (title unchanged) warrant a finding** without a backing ledger claim? Recommend surfacing only when a ledger claim corroborates, to keep precision high. Validate in M6.
+- **`fold_guardrail` sub-section protection** — the guardrail only checks top-level blueprint keys, not nested arrays. A fold could drop the entire `domain_invariants[]` *contents* without tripping it. The review *catches* this (REMOVE of every invariant id), but note the on-branch guardrail won't.
+
+---
+
+## 9. Out of scope (carried over from design §10)
+
+- **Layer 3** — raw source `git diff` read against invariants (the because-theater zone; gated behind an eval harness before it may comment, let alone block).
+- **Blocking gate** — a CI status check that can fail the PR.
+- **Auto violation-vs-evolution categorization** — the human decides (avoids laundering a bug into law).
+- **The eval / observability plane** (Langfuse-style: replay historical PRs, score precision/false-evolution, store traces; reuses `archie/benchmark/` + Supabase). Prerequisite for any future blocking mode.
+- **The setup webapp + GitHub App + backend** (server-side execution, "connect repo + GitHub + Claude key + go").
+- **BYO-key onboarding flow.**
+- **`npx`-installer injection of `.github/workflows/`** — deliberately excluded; the setup script is the sole workflow installer (§8 decision).
+- **Post-merge fold automation** — unneeded; the fold already happened on the branch, so git's "merge = acceptance" handles baseline evolution automatically.
+
+Canonical deliverable paths (for the implementer): `archie/standalone/intent_review.py`, `archie/assets/workflows/archie-intent-review.yml`, `archie/assets/setup-archie-intent-review.sh`, `tests/test_intent_review.py`; edits to `archie/install.py`, `npm-package/assets/_install_pkg/install.py`, `npm-package/bin/archie.mjs`, `scripts/verify_sync.py`; byte-copies under `npm-package/assets/` (`intent_review.py`, `workflows/archie-intent-review.yml`, `setup-archie-intent-review.sh`).
\ No newline at end of file

From 846d423e8ad27c439097bf3fdfd4e7b1ab9e561e Mon Sep 17 00:00:00 2001
From: Gabor Bakos <gabor@bitraptors.com>
Date: Fri, 19 Jun 2026 19:23:38 +0200
Subject: [PATCH 03/15] =?UTF-8?q?feat(intent-review):=20implement=20M1-M3,?=
 =?UTF-8?q?M7=20=E2=80=94=20diff=20core,=20model=20judge,=20comment,=20tes?=
 =?UTF-8?q?ts=20+=20wiring?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

intent_review.py (zero-dep): deterministic keyed diff of branch-folded
blueprint/rules vs base ref, sync-ledger glob (union of change_*.json),
conservative ledger join (file overlap AND keyword), one Haiku tool_use call
that JUDGES only (script overwrites diff_op/ids/layer), because-or-suppress,
upserted FYI PR comment, always exit 0 (never blocks; fork/no-secret early skip).

Wiring (M1a): archie.mjs + install.py (+ mirror) script lists; verify_sync.py
now byte-checks the plural workflows/ mirror and the setup .sh (drift-tested).

Tests (M7): 25 cases, all green; full suite 1003 passed / 1 skipped; verify_sync
green. Workflow YAML + gh setup script are the M4/M5 canonical assets.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .gitignore                                    |   2 +
 archie/install.py                             |   1 +
 archie/standalone/intent_review.py            | 816 ++++++++++++++++++
 npm-package/assets/_install_pkg/install.py    |   1 +
 npm-package/assets/intent_review.py           | 816 ++++++++++++++++++
 .../assets/setup-archie-intent-review.sh      |  99 +++
 .../assets/workflows/archie-intent-review.yml |  29 +
 npm-package/bin/archie.mjs                    |   2 +-
 scripts/verify_sync.py                        |  43 +
 tests/test_intent_review.py                   | 402 +++++++++
 10 files changed, 2210 insertions(+), 1 deletion(-)
 create mode 100644 archie/standalone/intent_review.py
 create mode 100644 npm-package/assets/intent_review.py
 create mode 100755 npm-package/assets/setup-archie-intent-review.sh
 create mode 100644 npm-package/assets/workflows/archie-intent-review.yml
 create mode 100644 tests/test_intent_review.py

diff --git a/.gitignore b/.gitignore
index 8279b2b..eeb1309 100644
--- a/.gitignore
+++ b/.gitignore
@@ -78,3 +78,5 @@ docs/superpowers/
 
 # Internal benchmark scratch configs/logs/results
 .archie-bench/
+
+.venv-test/
diff --git a/archie/install.py b/archie/install.py
index e07f217..d28ccb2 100644
--- a/archie/install.py
+++ b/archie/install.py
@@ -61,6 +61,7 @@ def _resolve_targets(requested: list[str] | None, connectors: list[Connector]) -
     "analytics.py", "config.py",
     "update_check.py", "upload.py", "share_setup.py", "refresh.py",
     "viewer.py", "install_hooks.py", "_common.py", "sync.py",
+    "intent_review.py",
 ]
 
 
diff --git a/archie/standalone/intent_review.py b/archie/standalone/intent_review.py
new file mode 100644
index 0000000..628667f
--- /dev/null
+++ b/archie/standalone/intent_review.py
@@ -0,0 +1,816 @@
+#!/usr/bin/env python3
+"""Archie Intent Review — PR-time semantic review of the architectural source of truth.
+
+Runs inside a GitHub Action on `pull_request`. It does NOT re-derive what changed —
+the change is already folded into `.archie/blueprint.json` + `rules.json` on the branch
+by `/archie-sync`. This script:
+
+  1. Diffs the branch's blueprint/rules against the PR base ref (DETERMINISTIC — the
+     script owns `diff_op`/ids/layer; the model never re-derives them).
+  2. Globs the sync ledger (`.archie/changes/change_*.json`) for corroborating intent.
+  3. Makes ONE Claude (Haiku) call to JUDGE the diff against the *retained* rules:
+     is a change a silent weakening, a contradiction, or behavior that violates a rule?
+  4. Posts ONE upserted FYI comment. It surfaces; the human decides. It NEVER blocks
+     (always exits 0) and honors because-or-suppress (no cited rationale -> dropped).
+
+Zero dependencies beyond the Python 3.9+ stdlib. Designed to run as
+`python3 .archie/intent_review.py` with env: ANTHROPIC_API_KEY, GITHUB_TOKEN,
+GITHUB_REPOSITORY, GITHUB_BASE_REF, GITHUB_EVENT_PATH.
+
+Pure functions (diff/glob/parse/render) are importable and network-free so the test
+suite can exercise them without hitting any API.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# constants
+# ---------------------------------------------------------------------------
+MODEL = "claude-haiku-4-5"
+ANTHROPIC_URL = "https://api.anthropic.com/v1/messages"
+ANTHROPIC_VERSION = "2023-06-01"
+MAX_TOKENS = 4096
+COMMENT_MARKER = "<!-- archie-intent-review -->"
+GITHUB_API = "https://api.github.com"
+
+ADVISORY_KINDS = {"decision", "pitfall", "rule", "guideline"}
+DESCRIPTIVE_KINDS = {"behavior", "structure", "dataflow", "data", "tech", "reference"}
+
+# Blueprint sections we diff for Layer-1 silent-weakening, with their identity field.
+# (field is None -> key on a hash of the title field instead.)
+INVARIANT_SECTIONS = [
+    # (top_key, sub_key_or_None, id_field, title_field)
+    ("domain_invariants", None, "id", "invariant"),
+    ("derived_invariants", None, "id", "invariant"),
+]
+# decisions.key_decisions has no id -> title-hash keyed.
+DECISION_TITLE_FIELD = "title"
+
+# Data sections we diff for Layer-2 behavior-violates-rule (keyed by name).
+DATA_SECTIONS = [
+    ("data_models", "name"),
+    ("persistence_stores", "name"),
+]
+
+RELEVANCE_SEND_ALL_THRESHOLD = 25   # if retained rules are few, skip the keyword filter
+KEYWORD_JOIN_THRESHOLD = 1          # >=1 shared keyword token to attach ledger confidence
+
+
+# ---------------------------------------------------------------------------
+# git / file loading
+# ---------------------------------------------------------------------------
+def run_git(repo_root: Path, *args: str, timeout: int = 15):
+    """Run git; return (returncode, stdout, stderr). Never raises."""
+    try:
+        p = subprocess.run(
+            ["git", "-C", str(repo_root), *args],
+            capture_output=True, text=True, timeout=timeout,
+        )
+        return p.returncode, p.stdout, p.stderr
+    except Exception as e:  # pragma: no cover - defensive
+        return 1, "", str(e)
+
+
+def _parse_json(text: str):
+    """Parse JSON text; return (data, error). Empty/whitespace -> ({}, None)."""
+    if text is None or not text.strip():
+        return {}, None
+    try:
+        return json.loads(text), None
+    except json.JSONDecodeError as e:
+        return None, f"JSON parse error: {e}"
+
+
+def fetch_base_file(repo_root: Path, base_ref: str, rel_path: str):
+    """Read `rel_path` from the base ref via `git show`.
+
+    Returns (exists: bool, data: dict|list|None, error: str|None).
+    A file absent on the base ref -> (False, None, None): treat everything as ADD.
+    A malformed JSON on the base ref -> (True, None, "<err>").
+    """
+    code, out, err = run_git(repo_root, "show", f"{base_ref}:{rel_path}")
+    if code != 0:
+        low = (err or "").lower()
+        if "does not exist" in low or "exists on disk, but not" in low \
+                or "invalid object" in low or "unknown revision" in low \
+                or "path" in low and "does not exist" in low or "fatal" in low:
+            # absent on base ref
+            return False, None, None
+        return False, None, err.strip() or "git show failed"
+    data, perr = _parse_json(out)
+    return True, data, perr
+
+
+def load_branch_file(repo_root: Path, rel_path: str):
+    """Read `rel_path` from the working tree (already checked out).
+
+    Returns (exists, data, error) mirroring fetch_base_file.
+    """
+    p = repo_root / rel_path
+    if not p.exists():
+        return False, None, None
+    try:
+        data, perr = _parse_json(p.read_text())
+        return True, data, perr
+    except OSError as e:  # pragma: no cover - defensive
+        return True, None, str(e)
+
+
+# ---------------------------------------------------------------------------
+# rules normalization
+# ---------------------------------------------------------------------------
+def normalize_rules(data) -> list:
+    """rules.json may be {'rules': [...]}, a flat list, or absent. Always -> list."""
+    if data is None:
+        return []
+    if isinstance(data, dict):
+        rules = data.get("rules")
+        return rules if isinstance(rules, list) else []
+    if isinstance(data, list):
+        return data
+    return []
+
+
+# ---------------------------------------------------------------------------
+# keyed semantic diff
+# ---------------------------------------------------------------------------
+def _hash_title(title: str) -> str:
+    return "title_" + hashlib.md5((title or "").strip().encode("utf-8")).hexdigest()[:8]
+
+
+def item_key(item: dict, id_field: str, title_field: str) -> str:
+    """Stable key for an item: its id if present, else a hash of its title."""
+    if id_field and isinstance(item, dict):
+        val = item.get(id_field)
+        if val:
+            return str(val)
+    title = ""
+    if isinstance(item, dict):
+        title = str(item.get(title_field, "") or "")
+    return _hash_title(title)
+
+
+def _changed_fields(base_item: dict, branch_item: dict) -> list:
+    keys = set()
+    if isinstance(base_item, dict):
+        keys |= set(base_item.keys())
+    if isinstance(branch_item, dict):
+        keys |= set(branch_item.keys())
+    changed = []
+    for k in sorted(keys):
+        if (base_item or {}).get(k) != (branch_item or {}).get(k):
+            changed.append(k)
+    return changed
+
+
+def keyed_diff(base_list, branch_list, id_field, title_field):
+    """Return [{status, key, base_item, branch_item, fields_changed}].
+
+    status in REMOVE | UPDATE | ADD. Reordered-but-identical lists -> no diffs.
+    """
+    base_list = base_list if isinstance(base_list, list) else []
+    branch_list = branch_list if isinstance(branch_list, list) else []
+    base_by = {}
+    for it in base_list:
+        if isinstance(it, dict):
+            base_by[item_key(it, id_field, title_field)] = it
+    branch_by = {}
+    for it in branch_list:
+        if isinstance(it, dict):
+            branch_by[item_key(it, id_field, title_field)] = it
+
+    out = []
+    for key in base_by:
+        if key not in branch_by:
+            out.append({"status": "REMOVE", "key": key,
+                        "base_item": base_by[key], "branch_item": None,
+                        "fields_changed": []})
+        else:
+            fc = _changed_fields(base_by[key], branch_by[key])
+            if fc:
+                out.append({"status": "UPDATE", "key": key,
+                            "base_item": base_by[key], "branch_item": branch_by[key],
+                            "fields_changed": fc})
+    for key in branch_by:
+        if key not in base_by:
+            out.append({"status": "ADD", "key": key,
+                        "base_item": None, "branch_item": branch_by[key],
+                        "fields_changed": []})
+    return out
+
+
+def _get_section(bp, top_key, sub_key):
+    if not isinstance(bp, dict):
+        return []
+    node = bp.get(top_key)
+    if sub_key:
+        node = node.get(sub_key) if isinstance(node, dict) else None
+    return node if isinstance(node, list) else []
+
+
+def _title_of(item, title_field) -> str:
+    if isinstance(item, dict):
+        return str(item.get(title_field) or item.get("title") or item.get("name")
+                   or item.get("invariant") or item.get("id") or "(unnamed)")
+    return "(unnamed)"
+
+
+# ---------------------------------------------------------------------------
+# build the list of CHANGED ITEMS the model will judge
+# ---------------------------------------------------------------------------
+def build_changed_items(base_bp, branch_bp, base_rules, branch_rules, ledger_claims):
+    """Deterministically assemble every reviewable change with a stable `ref`.
+
+    Each item: {ref, source, section, diff_op, layer, title, base_item, branch_item,
+                fields_changed, keywords, enforced_at_files}.
+    The model references `ref`; the script owns diff_op/layer/section/title.
+    """
+    items = []
+    n = [0]
+
+    def add(source, section, diff_op, layer, title, base_item, branch_item,
+            fields_changed, keywords, enforced_at_files):
+        ref = f"c{n[0]}"
+        n[0] += 1
+        items.append({
+            "ref": ref, "source": source, "section": section,
+            "diff_op": diff_op, "layer": layer, "title": title,
+            "base_item": base_item, "branch_item": branch_item,
+            "fields_changed": fields_changed, "keywords": keywords,
+            "enforced_at_files": enforced_at_files,
+        })
+
+    # Layer 1 — invariant sections (silent weakening)
+    for top_key, sub_key, id_field, title_field in INVARIANT_SECTIONS:
+        diffs = keyed_diff(_get_section(base_bp, top_key, sub_key),
+                           _get_section(branch_bp, top_key, sub_key),
+                           id_field, title_field)
+        for d in diffs:
+            ref_item = d["branch_item"] or d["base_item"] or {}
+            add("blueprint", top_key, d["status"], 1,
+                _title_of(ref_item, title_field),
+                d["base_item"], d["branch_item"], d["fields_changed"],
+                _keywords_of(ref_item), _enforced_files(ref_item))
+
+    # Layer 1 — decisions.key_decisions (title-hash keyed, silent weakening)
+    dec_diffs = keyed_diff(_get_section(base_bp, "decisions", "key_decisions"),
+                           _get_section(branch_bp, "decisions", "key_decisions"),
+                           None, DECISION_TITLE_FIELD)
+    for d in dec_diffs:
+        ref_item = d["branch_item"] or d["base_item"] or {}
+        add("blueprint", "decisions.key_decisions", d["status"], 1,
+            _title_of(ref_item, DECISION_TITLE_FIELD),
+            d["base_item"], d["branch_item"], d["fields_changed"],
+            _keywords_of(ref_item), [])
+
+    # Layer 1 — rules (contradiction candidates): ADD/UPDATE only
+    rule_diffs = keyed_diff(base_rules, branch_rules, "id", "description")
+    for d in rule_diffs:
+        if d["status"] == "REMOVE":
+            # a removed rule is a weakening of the ruleset
+            ref_item = d["base_item"] or {}
+            add("rules", "rules", "REMOVE", 1,
+                _rule_title(ref_item), d["base_item"], None, [],
+                _keywords_of(ref_item), [])
+        else:
+            ref_item = d["branch_item"] or {}
+            add("rules", "rules", d["status"], 1,
+                _rule_title(ref_item), d["base_item"], d["branch_item"],
+                d["fields_changed"], _keywords_of(ref_item), [])
+
+    # Layer 2 — data sections (behavior-violates-rule)
+    for top_key, name_field in DATA_SECTIONS:
+        diffs = keyed_diff(_get_section(base_bp, top_key, None),
+                           _get_section(branch_bp, top_key, None),
+                           name_field, name_field)
+        for d in diffs:
+            if d["status"] == "ADD" and not d["fields_changed"]:
+                pass  # pure additions of data models rarely violate a rule on their own
+            ref_item = d["branch_item"] or d["base_item"] or {}
+            add("blueprint", top_key, d["status"], 2,
+                _title_of(ref_item, name_field),
+                d["base_item"], d["branch_item"], d["fields_changed"],
+                _keywords_of(ref_item), [])
+
+    # Layer 2 — descriptive ledger claims (behavior-violates-rule)
+    for claim in ledger_claims:
+        if not isinstance(claim, dict):
+            continue
+        if claim.get("kind") in DESCRIPTIVE_KINDS:
+            stmt = str(claim.get("statement", "")).strip()
+            if not stmt:
+                continue
+            add("ledger", f"claim:{claim.get('kind')}", "DECLARED", 2,
+                stmt[:80], None, claim, [],
+                _keywords_from_text(stmt), list(claim.get("evidence_files") or []))
+
+    return items
+
+
+def _keywords_of(item) -> list:
+    if not isinstance(item, dict):
+        return []
+    kw = item.get("keywords")
+    if isinstance(kw, list):
+        return [str(k).lower() for k in kw]
+    return _keywords_from_text(" ".join(
+        str(item.get(f, "")) for f in ("invariant", "title", "description", "name")))
+
+
+def _keywords_from_text(text: str) -> list:
+    toks = [t.strip(".,:;()[]'\"").lower() for t in (text or "").split()]
+    return [t for t in toks if len(t) >= 4]
+
+
+def _enforced_files(item) -> list:
+    """File paths referenced by an invariant's enforced_at / evidence."""
+    if not isinstance(item, dict):
+        return []
+    files = []
+    for field in ("enforced_at", "evidence"):
+        vals = item.get(field)
+        if isinstance(vals, list):
+            for v in vals:
+                files.append(str(v).split(":")[0].strip())
+    return [f for f in files if f]
+
+
+def _rule_title(rule) -> str:
+    if not isinstance(rule, dict):
+        return "(rule)"
+    return str(rule.get("id") or rule.get("topic") or rule.get("description", "")[:60] or "(rule)")
+
+
+# ---------------------------------------------------------------------------
+# ledger
+# ---------------------------------------------------------------------------
+def glob_ledger(repo_root: Path, base_ref: str) -> list:
+    """Union of all claims from `.archie/changes/change_*.json` new on the branch.
+
+    `latest.json` is overwritten on every record, so it is NOT a complete source — we
+    glob the versioned files. Records already present on the base ref are skipped.
+    Malformed records are skipped, not fatal. Claims deduped by id (or statement).
+    """
+    changes_dir = repo_root / ".archie" / "changes"
+    if not changes_dir.is_dir():
+        return []
+
+    # which change files already exist on the base ref (so they aren't "new")
+    base_files = set()
+    code, out, _ = run_git(repo_root, "ls-tree", "-r", "--name-only", base_ref, ".archie/changes")
+    if code == 0:
+        base_files = {line.strip() for line in out.splitlines() if line.strip()}
+
+    claims = []
+    seen = set()
+    for fp in sorted(changes_dir.glob("change_*.json")):
+        rel = f".archie/changes/{fp.name}"
+        if rel in base_files:
+            continue  # already on base — not part of this PR's intent
+        try:
+            record = json.loads(fp.read_text())
+        except (OSError, json.JSONDecodeError):
+            continue
+        for claim in (record.get("claims") or []):
+            if not isinstance(claim, dict):
+                continue
+            key = claim.get("id") or claim.get("statement")
+            if key in seen:
+                continue
+            seen.add(key)
+            claims.append(claim)
+    return claims
+
+
+def ledger_join(changed_item: dict, claims: list):
+    """Conservative join: attach a claim's confidence to an invariant change only when
+    file paths overlap AND keyword overlap clears the threshold. No match -> None
+    (the finding still surfaces, just without the confidence sharpener — never guess).
+    """
+    item_files = set(changed_item.get("enforced_at_files") or [])
+    item_kw = set(changed_item.get("keywords") or [])
+    best = None
+    for claim in claims:
+        if not isinstance(claim, dict):
+            continue
+        claim_files = set(str(f) for f in (claim.get("evidence_files") or []))
+        file_overlap = bool(item_files & claim_files) or _path_overlap(item_files, claim_files)
+        claim_kw = set(_keywords_from_text(str(claim.get("statement", ""))))
+        kw_overlap = len(item_kw & claim_kw)
+        if file_overlap and kw_overlap >= KEYWORD_JOIN_THRESHOLD:
+            cand = {
+                "confidence": claim.get("confidence"),
+                "reconstructed": bool(claim.get("reconstructed", False)),
+                "statement": claim.get("statement"),
+            }
+            if best is None or kw_overlap > best.get("_kw", 0):
+                cand["_kw"] = kw_overlap
+                best = cand
+    if best:
+        best.pop("_kw", None)
+    return best
+
+
+def _path_overlap(a: set, b: set) -> bool:
+    for x in a:
+        for y in b:
+            if x and y and (x == y or x.endswith("/" + y) or y.endswith("/" + x)
+                            or x in y or y in x):
+                return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# retained rules (context for the model)
+# ---------------------------------------------------------------------------
+def retained_rules(base_rules: list, changed_items: list) -> list:
+    """Base-ref rules NOT themselves changed, optionally relevance-filtered."""
+    changed_rule_keys = {
+        it["title"] for it in changed_items if it.get("source") == "rules"
+    }
+    retained = [r for r in base_rules if isinstance(r, dict)
+                and _rule_title(r) not in changed_rule_keys]
+    if len(retained) <= RELEVANCE_SEND_ALL_THRESHOLD:
+        return retained
+    # relevance filter: keep rules sharing a keyword with any changed item
+    changed_kw = set()
+    for it in changed_items:
+        changed_kw |= set(it.get("keywords") or [])
+        changed_kw |= set(_keywords_from_text(it.get("title", "")))
+    filtered = []
+    for r in retained:
+        rkw = set(_keywords_of(r)) | set(_keywords_from_text(str(r.get("description", ""))))
+        if rkw & changed_kw:
+            filtered.append(r)
+    return filtered or retained[:RELEVANCE_SEND_ALL_THRESHOLD]
+
+
+# ---------------------------------------------------------------------------
+# model call
+# ---------------------------------------------------------------------------
+EMIT_FINDINGS_TOOL = {
+    "name": "emit_findings",
+    "description": (
+        "Emit structured review findings about a PR's change to the architectural "
+        "source of truth. For each CHANGED ITEM you judge to be a real concern, emit a "
+        "finding. The diff op and which item changed are GIVEN to you (cite item_ref). "
+        "Your job is ONLY to judge the TYPE and write a verifiable, cited BECAUSE drawn "
+        "from the item's own text and the retained rules. BECAUSE-OR-SUPPRESS: if you "
+        "cannot ground a finding in the provided texts, omit it entirely."
+    ),
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "findings": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "item_ref": {"type": "string",
+                                     "description": "ref of the CHANGED ITEM this is about (e.g. c0). Findings referencing no listed item are discarded."},
+                        "type": {"type": "string",
+                                 "enum": ["silent_weakening", "contradiction", "behavior_violates_rule"]},
+                        "rule_name": {"type": "string", "description": "the invariant/rule this concerns"},
+                        "what_changed": {"type": "string"},
+                        "because": {"type": "string",
+                                    "description": "verifiable cited rationale from the texts; empty => dropped"},
+                    },
+                    "required": ["item_ref", "type", "rule_name", "what_changed", "because"],
+                },
+            },
+        },
+        "required": ["findings"],
+    },
+}
+
+
+def build_prompt(changed_items: list, retained: list, claims: list) -> tuple:
+    """Return (system, user) prompt strings. Pure; token-bounded payload."""
+    system = (
+        "You are an architecture reviewer for a pull request. The change has already been "
+        "folded into the project's blueprint and rules; you are given a DETERMINISTIC diff "
+        "of the source of truth (you do NOT decide what changed). Judge each CHANGED ITEM:\n"
+        "- silent_weakening: a REMOVE/UPDATE that retires or softens an invariant or key decision.\n"
+        "- contradiction: an ADD/UPDATE to the rules that conflicts with a RETAINED rule.\n"
+        "- behavior_violates_rule: a described behavior/data change that breaks a RETAINED rule.\n"
+        "Only emit a finding when it is real and you can cite WHY from the provided texts "
+        "(because-or-suppress). Do not flag benign additions. Call emit_findings exactly once."
+    )
+
+    def trim(item, n=600):
+        s = json.dumps(item, ensure_ascii=False)
+        return s if len(s) <= n else s[:n] + "...(truncated)"
+
+    lines = ["CHANGED ITEMS (cite item_ref):"]
+    for it in changed_items:
+        lines.append(
+            f"- ref={it['ref']} layer={it['layer']} op={it['diff_op']} "
+            f"section={it['section']} title={it['title']!r}"
+        )
+        if it.get("base_item") is not None:
+            lines.append(f"    base: {trim(it['base_item'])}")
+        if it.get("branch_item") is not None:
+            lines.append(f"    branch: {trim(it['branch_item'])}")
+        if it.get("fields_changed"):
+            lines.append(f"    fields_changed: {it['fields_changed']}")
+    lines.append("")
+    lines.append("RETAINED RULES (must still hold):")
+    for r in retained:
+        lines.append(f"- {trim(r, 400)}")
+    if claims:
+        lines.append("")
+        lines.append("DECLARED INTENT (sync ledger claims, context only):")
+        for c in claims:
+            lines.append(f"- kind={c.get('kind')} conf={c.get('confidence')} "
+                         f"stmt={str(c.get('statement',''))[:160]!r}")
+    return system, "\n".join(lines)
+
+
+def call_anthropic(system: str, user: str, api_key: str, max_retries: int = 3) -> list:
+    """POST one Messages request forcing the emit_findings tool. Return the raw
+    findings list from the model (judgment only). Raises RuntimeError on hard failure.
+    """
+    body = json.dumps({
+        "model": MODEL,
+        "max_tokens": MAX_TOKENS,
+        "system": system,
+        "tools": [EMIT_FINDINGS_TOOL],
+        "tool_choice": {"type": "tool", "name": "emit_findings"},
+        "messages": [{"role": "user", "content": user}],
+    }).encode("utf-8")
+
+    last_err = None
+    for attempt in range(max_retries):
+        req = urllib.request.Request(ANTHROPIC_URL, data=body, method="POST", headers={
+            "x-api-key": api_key,
+            "anthropic-version": ANTHROPIC_VERSION,
+            "content-type": "application/json",
+        })
+        try:
+            with urllib.request.urlopen(req, timeout=90) as resp:
+                payload = json.loads(resp.read().decode("utf-8"))
+            return _extract_findings(payload)
+        except urllib.error.HTTPError as e:
+            last_err = f"HTTP {e.code}"
+            if e.code in (429, 500, 502, 503, 529) and attempt < max_retries - 1:
+                retry_after = e.headers.get("Retry-After") if e.headers else None
+                delay = float(retry_after) if retry_after and retry_after.isdigit() \
+                    else min(2 ** attempt, 30)
+                time.sleep(delay)
+                continue
+            raise RuntimeError(f"Anthropic API error: {last_err}: {e.read().decode('utf-8', 'replace')[:300]}")
+        except (urllib.error.URLError, TimeoutError) as e:
+            last_err = str(e)
+            if attempt < max_retries - 1:
+                time.sleep(min(2 ** attempt, 30))
+                continue
+            raise RuntimeError(f"Anthropic API unreachable: {last_err}")
+    raise RuntimeError(f"Anthropic API failed: {last_err}")
+
+
+def _extract_findings(api_response: dict) -> list:
+    """Pull the emit_findings tool_use input out of a Messages response."""
+    for block in (api_response.get("content") or []):
+        if block.get("type") == "tool_use" and block.get("name") == "emit_findings":
+            inp = block.get("input") or {}
+            findings = inp.get("findings")
+            return findings if isinstance(findings, list) else []
+    return []
+
+
+# ---------------------------------------------------------------------------
+# finalize: overwrite deterministic fields, because-or-suppress, ledger join
+# ---------------------------------------------------------------------------
+def finalize_findings(model_findings: list, changed_items: list, claims: list) -> list:
+    """Bind each model finding to its real changed item, overwrite the deterministic
+    fields from the script's own diff, drop unciteable/unmatched findings, and attach a
+    ledger-confidence sharpener where the conservative join succeeds.
+    """
+    by_ref = {it["ref"]: it for it in changed_items}
+    out = []
+    for f in model_findings:
+        if not isinstance(f, dict):
+            continue
+        item = by_ref.get(f.get("item_ref"))
+        if item is None:
+            continue  # references no real diff item -> drop
+        because = str(f.get("because", "")).strip()
+        if not because:
+            continue  # because-or-suppress
+        finding = {
+            # deterministic, script-owned (overwrite the model's echo):
+            "diff_op": item["diff_op"],
+            "layer": item["layer"],
+            "section": item["section"],
+            "rule_name": item["title"],
+            # model judgment:
+            "type": f.get("type", "behavior_violates_rule"),
+            "what_changed": str(f.get("what_changed", "")).strip(),
+            "because": because,
+            "confidence": None,
+        }
+        join = ledger_join(item, claims)
+        if join:
+            finding["confidence"] = join.get("confidence")
+            finding["reconstructed"] = join.get("reconstructed")
+        out.append(finding)
+    return out
+
+
+# ---------------------------------------------------------------------------
+# render + post comment
+# ---------------------------------------------------------------------------
+_FLAG_HEADERS = {
+    "silent_weakening": "⚠️ Silent weakening / removal",
+    "contradiction": "⚠️ Contradiction with a retained rule",
+    "behavior_violates_rule": "⚠️ Behavior may violate a rule",
+}
+_FLAG_ORDER = ["silent_weakening", "contradiction", "behavior_violates_rule"]
+
+
+def render_comment(findings: list, had_diff: bool):
+    """Return the markdown comment body, or None to post nothing."""
+    if not had_diff:
+        return None
+    if not findings:
+        return (f"{COMMENT_MARKER}\n## 📐 Archie Intent Review\n\n"
+                "No findings — the blueprint changes in this PR are consistent with the "
+                "retained rules.\n\n*Archie surfaces; it doesn't block.*")
+
+    lines = [COMMENT_MARKER, "## 📐 Archie Intent Review", ""]
+    n = len(findings)
+    lines.append(f"This PR changes the architectural source of truth. **{n} finding"
+                 f"{'s' if n != 1 else ''}** for a human to weigh:")
+    for flag in _FLAG_ORDER:
+        group = [f for f in findings if f.get("type") == flag]
+        if not group:
+            continue
+        lines.append("")
+        lines.append(f"### {_FLAG_HEADERS[flag]}")
+        for f in group:
+            conf = ""
+            if f.get("confidence"):
+                rec = " · reconstructed guess" if f.get("reconstructed") else ""
+                conf = f" _(ledger confidence: {f['confidence']}{rec})_"
+            lines.append(
+                f"- **{f['rule_name']}** ({f['diff_op']}, Layer {f['layer']}){conf}  \n"
+                f"  {f['what_changed']}  \n"
+                f"  _Because:_ {f['because']}"
+            )
+    lines.append("")
+    lines.append("*Archie surfaces; it doesn't block. Whether a change means \"fix the "
+                 "code\" or \"evolve the rule\" is your call — merge accepts the blueprint "
+                 "changes above as the new baseline.*")
+    return "\n".join(lines)
+
+
+def _gh_request(method: str, url: str, token: str, body: dict = None):
+    data = json.dumps(body).encode("utf-8") if body is not None else None
+    req = urllib.request.Request(url, data=data, method=method, headers={
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+        "Content-Type": "application/json",
+        "User-Agent": "archie-intent-review",
+    })
+    with urllib.request.urlopen(req, timeout=30) as resp:
+        raw = resp.read().decode("utf-8")
+        return json.loads(raw) if raw.strip() else {}
+
+
+def post_or_update_comment(owner, repo, pr_number, body, token):
+    """Upsert the single Archie comment (find by marker -> PATCH, else POST)."""
+    list_url = f"{GITHUB_API}/repos/{owner}/{repo}/issues/{pr_number}/comments?per_page=100"
+    existing_id = None
+    try:
+        comments = _gh_request("GET", list_url, token)
+        for c in comments if isinstance(comments, list) else []:
+            if COMMENT_MARKER in (c.get("body") or ""):
+                existing_id = c.get("id")
+                break
+    except urllib.error.HTTPError as e:  # pragma: no cover - network
+        print(f"[intent-review] could not list comments: HTTP {e.code}", file=sys.stderr)
+
+    if existing_id:
+        url = f"{GITHUB_API}/repos/{owner}/{repo}/issues/comments/{existing_id}"
+        _gh_request("PATCH", url, token, {"body": body})
+        print(f"[intent-review] updated comment {existing_id}")
+    else:
+        url = f"{GITHUB_API}/repos/{owner}/{repo}/issues/{pr_number}/comments"
+        _gh_request("POST", url, token, {"body": body})
+        print("[intent-review] posted new comment")
+
+
+# ---------------------------------------------------------------------------
+# event context
+# ---------------------------------------------------------------------------
+def parse_event_context(env: dict):
+    """Return (owner, repo, pr_number, base_ref) or None if not a usable PR event."""
+    repo_full = env.get("GITHUB_REPOSITORY", "")
+    base_ref = env.get("GITHUB_BASE_REF", "")
+    event_path = env.get("GITHUB_EVENT_PATH", "")
+    if "/" not in repo_full:
+        return None
+    owner, repo = repo_full.split("/", 1)
+    pr_number = None
+    if event_path and Path(event_path).exists():
+        try:
+            event = json.loads(Path(event_path).read_text())
+            pr = event.get("pull_request")
+            if isinstance(pr, dict):
+                pr_number = pr.get("number")
+                base_ref = base_ref or (pr.get("base") or {}).get("ref", "")
+        except (OSError, json.JSONDecodeError):
+            return None
+    if pr_number is None or not base_ref:
+        return None
+    return owner, repo, pr_number, base_ref
+
+
+# ---------------------------------------------------------------------------
+# main
+# ---------------------------------------------------------------------------
+def main(argv=None) -> int:
+    repo_root = Path(os.environ.get("GITHUB_WORKSPACE") or ".").resolve()
+    env = os.environ
+
+    # 1. Fork-PR / no-secret guard FIRST — before any GitHub write.
+    api_key = env.get("ANTHROPIC_API_KEY", "").strip()
+    if not api_key:
+        print("[intent-review] ANTHROPIC_API_KEY not set (fork PR?) — skipping.", file=sys.stderr)
+        return 0
+
+    ctx = parse_event_context(env)
+    if ctx is None:
+        print("[intent-review] not a usable pull_request event — skipping.", file=sys.stderr)
+        return 0
+    owner, repo, pr_number, base_ref = ctx
+    token = env.get("GITHUB_TOKEN", "").strip()
+    base_ref_full = f"origin/{base_ref}"
+
+    # 2. Load branch + base versions of the source of truth.
+    b_exists, branch_bp, b_err = load_branch_file(repo_root, ".archie/blueprint.json")
+    if b_exists and branch_bp is None:
+        # branch blueprint is malformed — surface, don't crash.
+        if token:
+            post_or_update_comment(owner, repo, pr_number,
+                                   f"{COMMENT_MARKER}\n## 📐 Archie Intent Review\n\n"
+                                   f"Could not parse `.archie/blueprint.json` on this branch "
+                                   f"({b_err}). Manual review needed.", token)
+        return 0
+    if not b_exists:
+        print("[intent-review] no .archie/blueprint.json on branch — nothing to review.", file=sys.stderr)
+        return 0
+
+    _, base_bp, _ = fetch_base_file(repo_root, base_ref_full, ".archie/blueprint.json")
+    base_bp = base_bp if isinstance(base_bp, dict) else {}
+
+    _, base_rules_raw, _ = fetch_base_file(repo_root, base_ref_full, ".archie/rules.json")
+    _, branch_rules_raw, _ = load_branch_file(repo_root, ".archie/rules.json")
+    base_rules = normalize_rules(base_rules_raw)
+    branch_rules = normalize_rules(branch_rules_raw)
+
+    claims = glob_ledger(repo_root, base_ref_full)
+
+    # 3. Deterministic diff -> changed items.
+    changed_items = build_changed_items(base_bp, branch_bp, base_rules, branch_rules, claims)
+    had_diff = bool(changed_items)
+    if not had_diff:
+        print("[intent-review] no source-of-truth changes detected — posting nothing.", file=sys.stderr)
+        return 0
+
+    # 4. Judge with one model call.
+    retained = retained_rules(base_rules, changed_items)
+    system, user = build_prompt(changed_items, retained, claims)
+    try:
+        model_findings = call_anthropic(system, user, api_key)
+    except RuntimeError as e:
+        print(f"[intent-review] model call failed: {e}", file=sys.stderr)
+        return 0  # never block
+    findings = finalize_findings(model_findings, changed_items, claims)
+
+    # 5. Render + upsert.
+    body = render_comment(findings, had_diff)
+    if body is None:
+        return 0
+    if not token:
+        print("[intent-review] no GITHUB_TOKEN — printing body:\n" + body)
+        return 0
+    try:
+        post_or_update_comment(owner, repo, pr_number, body, token)
+    except urllib.error.HTTPError as e:  # pragma: no cover - network
+        print(f"[intent-review] could not post comment: HTTP {e.code}", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/npm-package/assets/_install_pkg/install.py b/npm-package/assets/_install_pkg/install.py
index e07f217..d28ccb2 100644
--- a/npm-package/assets/_install_pkg/install.py
+++ b/npm-package/assets/_install_pkg/install.py
@@ -61,6 +61,7 @@ def _resolve_targets(requested: list[str] | None, connectors: list[Connector]) -
     "analytics.py", "config.py",
     "update_check.py", "upload.py", "share_setup.py", "refresh.py",
     "viewer.py", "install_hooks.py", "_common.py", "sync.py",
+    "intent_review.py",
 ]
 
 
diff --git a/npm-package/assets/intent_review.py b/npm-package/assets/intent_review.py
new file mode 100644
index 0000000..628667f
--- /dev/null
+++ b/npm-package/assets/intent_review.py
@@ -0,0 +1,816 @@
+#!/usr/bin/env python3
+"""Archie Intent Review — PR-time semantic review of the architectural source of truth.
+
+Runs inside a GitHub Action on `pull_request`. It does NOT re-derive what changed —
+the change is already folded into `.archie/blueprint.json` + `rules.json` on the branch
+by `/archie-sync`. This script:
+
+  1. Diffs the branch's blueprint/rules against the PR base ref (DETERMINISTIC — the
+     script owns `diff_op`/ids/layer; the model never re-derives them).
+  2. Globs the sync ledger (`.archie/changes/change_*.json`) for corroborating intent.
+  3. Makes ONE Claude (Haiku) call to JUDGE the diff against the *retained* rules:
+     is a change a silent weakening, a contradiction, or behavior that violates a rule?
+  4. Posts ONE upserted FYI comment. It surfaces; the human decides. It NEVER blocks
+     (always exits 0) and honors because-or-suppress (no cited rationale -> dropped).
+
+Zero dependencies beyond the Python 3.9+ stdlib. Designed to run as
+`python3 .archie/intent_review.py` with env: ANTHROPIC_API_KEY, GITHUB_TOKEN,
+GITHUB_REPOSITORY, GITHUB_BASE_REF, GITHUB_EVENT_PATH.
+
+Pure functions (diff/glob/parse/render) are importable and network-free so the test
+suite can exercise them without hitting any API.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# constants
+# ---------------------------------------------------------------------------
+MODEL = "claude-haiku-4-5"
+ANTHROPIC_URL = "https://api.anthropic.com/v1/messages"
+ANTHROPIC_VERSION = "2023-06-01"
+MAX_TOKENS = 4096
+COMMENT_MARKER = "<!-- archie-intent-review -->"
+GITHUB_API = "https://api.github.com"
+
+ADVISORY_KINDS = {"decision", "pitfall", "rule", "guideline"}
+DESCRIPTIVE_KINDS = {"behavior", "structure", "dataflow", "data", "tech", "reference"}
+
+# Blueprint sections we diff for Layer-1 silent-weakening, with their identity field.
+# (field is None -> key on a hash of the title field instead.)
+INVARIANT_SECTIONS = [
+    # (top_key, sub_key_or_None, id_field, title_field)
+    ("domain_invariants", None, "id", "invariant"),
+    ("derived_invariants", None, "id", "invariant"),
+]
+# decisions.key_decisions has no id -> title-hash keyed.
+DECISION_TITLE_FIELD = "title"
+
+# Data sections we diff for Layer-2 behavior-violates-rule (keyed by name).
+DATA_SECTIONS = [
+    ("data_models", "name"),
+    ("persistence_stores", "name"),
+]
+
+RELEVANCE_SEND_ALL_THRESHOLD = 25   # if retained rules are few, skip the keyword filter
+KEYWORD_JOIN_THRESHOLD = 1          # >=1 shared keyword token to attach ledger confidence
+
+
+# ---------------------------------------------------------------------------
+# git / file loading
+# ---------------------------------------------------------------------------
+def run_git(repo_root: Path, *args: str, timeout: int = 15):
+    """Run git; return (returncode, stdout, stderr). Never raises."""
+    try:
+        p = subprocess.run(
+            ["git", "-C", str(repo_root), *args],
+            capture_output=True, text=True, timeout=timeout,
+        )
+        return p.returncode, p.stdout, p.stderr
+    except Exception as e:  # pragma: no cover - defensive
+        return 1, "", str(e)
+
+
+def _parse_json(text: str):
+    """Parse JSON text; return (data, error). Empty/whitespace -> ({}, None)."""
+    if text is None or not text.strip():
+        return {}, None
+    try:
+        return json.loads(text), None
+    except json.JSONDecodeError as e:
+        return None, f"JSON parse error: {e}"
+
+
+def fetch_base_file(repo_root: Path, base_ref: str, rel_path: str):
+    """Read `rel_path` from the base ref via `git show`.
+
+    Returns (exists: bool, data: dict|list|None, error: str|None).
+    A file absent on the base ref -> (False, None, None): treat everything as ADD.
+    A malformed JSON on the base ref -> (True, None, "<err>").
+    """
+    code, out, err = run_git(repo_root, "show", f"{base_ref}:{rel_path}")
+    if code != 0:
+        low = (err or "").lower()
+        if "does not exist" in low or "exists on disk, but not" in low \
+                or "invalid object" in low or "unknown revision" in low \
+                or "path" in low and "does not exist" in low or "fatal" in low:
+            # absent on base ref
+            return False, None, None
+        return False, None, err.strip() or "git show failed"
+    data, perr = _parse_json(out)
+    return True, data, perr
+
+
+def load_branch_file(repo_root: Path, rel_path: str):
+    """Read `rel_path` from the working tree (already checked out).
+
+    Returns (exists, data, error) mirroring fetch_base_file.
+    """
+    p = repo_root / rel_path
+    if not p.exists():
+        return False, None, None
+    try:
+        data, perr = _parse_json(p.read_text())
+        return True, data, perr
+    except OSError as e:  # pragma: no cover - defensive
+        return True, None, str(e)
+
+
+# ---------------------------------------------------------------------------
+# rules normalization
+# ---------------------------------------------------------------------------
+def normalize_rules(data) -> list:
+    """rules.json may be {'rules': [...]}, a flat list, or absent. Always -> list."""
+    if data is None:
+        return []
+    if isinstance(data, dict):
+        rules = data.get("rules")
+        return rules if isinstance(rules, list) else []
+    if isinstance(data, list):
+        return data
+    return []
+
+
+# ---------------------------------------------------------------------------
+# keyed semantic diff
+# ---------------------------------------------------------------------------
+def _hash_title(title: str) -> str:
+    return "title_" + hashlib.md5((title or "").strip().encode("utf-8")).hexdigest()[:8]
+
+
+def item_key(item: dict, id_field: str, title_field: str) -> str:
+    """Stable key for an item: its id if present, else a hash of its title."""
+    if id_field and isinstance(item, dict):
+        val = item.get(id_field)
+        if val:
+            return str(val)
+    title = ""
+    if isinstance(item, dict):
+        title = str(item.get(title_field, "") or "")
+    return _hash_title(title)
+
+
+def _changed_fields(base_item: dict, branch_item: dict) -> list:
+    keys = set()
+    if isinstance(base_item, dict):
+        keys |= set(base_item.keys())
+    if isinstance(branch_item, dict):
+        keys |= set(branch_item.keys())
+    changed = []
+    for k in sorted(keys):
+        if (base_item or {}).get(k) != (branch_item or {}).get(k):
+            changed.append(k)
+    return changed
+
+
+def keyed_diff(base_list, branch_list, id_field, title_field):
+    """Return [{status, key, base_item, branch_item, fields_changed}].
+
+    status in REMOVE | UPDATE | ADD. Reordered-but-identical lists -> no diffs.
+    """
+    base_list = base_list if isinstance(base_list, list) else []
+    branch_list = branch_list if isinstance(branch_list, list) else []
+    base_by = {}
+    for it in base_list:
+        if isinstance(it, dict):
+            base_by[item_key(it, id_field, title_field)] = it
+    branch_by = {}
+    for it in branch_list:
+        if isinstance(it, dict):
+            branch_by[item_key(it, id_field, title_field)] = it
+
+    out = []
+    for key in base_by:
+        if key not in branch_by:
+            out.append({"status": "REMOVE", "key": key,
+                        "base_item": base_by[key], "branch_item": None,
+                        "fields_changed": []})
+        else:
+            fc = _changed_fields(base_by[key], branch_by[key])
+            if fc:
+                out.append({"status": "UPDATE", "key": key,
+                            "base_item": base_by[key], "branch_item": branch_by[key],
+                            "fields_changed": fc})
+    for key in branch_by:
+        if key not in base_by:
+            out.append({"status": "ADD", "key": key,
+                        "base_item": None, "branch_item": branch_by[key],
+                        "fields_changed": []})
+    return out
+
+
+def _get_section(bp, top_key, sub_key):
+    if not isinstance(bp, dict):
+        return []
+    node = bp.get(top_key)
+    if sub_key:
+        node = node.get(sub_key) if isinstance(node, dict) else None
+    return node if isinstance(node, list) else []
+
+
+def _title_of(item, title_field) -> str:
+    if isinstance(item, dict):
+        return str(item.get(title_field) or item.get("title") or item.get("name")
+                   or item.get("invariant") or item.get("id") or "(unnamed)")
+    return "(unnamed)"
+
+
+# ---------------------------------------------------------------------------
+# build the list of CHANGED ITEMS the model will judge
+# ---------------------------------------------------------------------------
+def build_changed_items(base_bp, branch_bp, base_rules, branch_rules, ledger_claims):
+    """Deterministically assemble every reviewable change with a stable `ref`.
+
+    Each item: {ref, source, section, diff_op, layer, title, base_item, branch_item,
+                fields_changed, keywords, enforced_at_files}.
+    The model references `ref`; the script owns diff_op/layer/section/title.
+    """
+    items = []
+    n = [0]
+
+    def add(source, section, diff_op, layer, title, base_item, branch_item,
+            fields_changed, keywords, enforced_at_files):
+        ref = f"c{n[0]}"
+        n[0] += 1
+        items.append({
+            "ref": ref, "source": source, "section": section,
+            "diff_op": diff_op, "layer": layer, "title": title,
+            "base_item": base_item, "branch_item": branch_item,
+            "fields_changed": fields_changed, "keywords": keywords,
+            "enforced_at_files": enforced_at_files,
+        })
+
+    # Layer 1 — invariant sections (silent weakening)
+    for top_key, sub_key, id_field, title_field in INVARIANT_SECTIONS:
+        diffs = keyed_diff(_get_section(base_bp, top_key, sub_key),
+                           _get_section(branch_bp, top_key, sub_key),
+                           id_field, title_field)
+        for d in diffs:
+            ref_item = d["branch_item"] or d["base_item"] or {}
+            add("blueprint", top_key, d["status"], 1,
+                _title_of(ref_item, title_field),
+                d["base_item"], d["branch_item"], d["fields_changed"],
+                _keywords_of(ref_item), _enforced_files(ref_item))
+
+    # Layer 1 — decisions.key_decisions (title-hash keyed, silent weakening)
+    dec_diffs = keyed_diff(_get_section(base_bp, "decisions", "key_decisions"),
+                           _get_section(branch_bp, "decisions", "key_decisions"),
+                           None, DECISION_TITLE_FIELD)
+    for d in dec_diffs:
+        ref_item = d["branch_item"] or d["base_item"] or {}
+        add("blueprint", "decisions.key_decisions", d["status"], 1,
+            _title_of(ref_item, DECISION_TITLE_FIELD),
+            d["base_item"], d["branch_item"], d["fields_changed"],
+            _keywords_of(ref_item), [])
+
+    # Layer 1 — rules (contradiction candidates): ADD/UPDATE only
+    rule_diffs = keyed_diff(base_rules, branch_rules, "id", "description")
+    for d in rule_diffs:
+        if d["status"] == "REMOVE":
+            # a removed rule is a weakening of the ruleset
+            ref_item = d["base_item"] or {}
+            add("rules", "rules", "REMOVE", 1,
+                _rule_title(ref_item), d["base_item"], None, [],
+                _keywords_of(ref_item), [])
+        else:
+            ref_item = d["branch_item"] or {}
+            add("rules", "rules", d["status"], 1,
+                _rule_title(ref_item), d["base_item"], d["branch_item"],
+                d["fields_changed"], _keywords_of(ref_item), [])
+
+    # Layer 2 — data sections (behavior-violates-rule)
+    for top_key, name_field in DATA_SECTIONS:
+        diffs = keyed_diff(_get_section(base_bp, top_key, None),
+                           _get_section(branch_bp, top_key, None),
+                           name_field, name_field)
+        for d in diffs:
+            if d["status"] == "ADD" and not d["fields_changed"]:
+                pass  # pure additions of data models rarely violate a rule on their own
+            ref_item = d["branch_item"] or d["base_item"] or {}
+            add("blueprint", top_key, d["status"], 2,
+                _title_of(ref_item, name_field),
+                d["base_item"], d["branch_item"], d["fields_changed"],
+                _keywords_of(ref_item), [])
+
+    # Layer 2 — descriptive ledger claims (behavior-violates-rule)
+    for claim in ledger_claims:
+        if not isinstance(claim, dict):
+            continue
+        if claim.get("kind") in DESCRIPTIVE_KINDS:
+            stmt = str(claim.get("statement", "")).strip()
+            if not stmt:
+                continue
+            add("ledger", f"claim:{claim.get('kind')}", "DECLARED", 2,
+                stmt[:80], None, claim, [],
+                _keywords_from_text(stmt), list(claim.get("evidence_files") or []))
+
+    return items
+
+
+def _keywords_of(item) -> list:
+    if not isinstance(item, dict):
+        return []
+    kw = item.get("keywords")
+    if isinstance(kw, list):
+        return [str(k).lower() for k in kw]
+    return _keywords_from_text(" ".join(
+        str(item.get(f, "")) for f in ("invariant", "title", "description", "name")))
+
+
+def _keywords_from_text(text: str) -> list:
+    toks = [t.strip(".,:;()[]'\"").lower() for t in (text or "").split()]
+    return [t for t in toks if len(t) >= 4]
+
+
+def _enforced_files(item) -> list:
+    """File paths referenced by an invariant's enforced_at / evidence."""
+    if not isinstance(item, dict):
+        return []
+    files = []
+    for field in ("enforced_at", "evidence"):
+        vals = item.get(field)
+        if isinstance(vals, list):
+            for v in vals:
+                files.append(str(v).split(":")[0].strip())
+    return [f for f in files if f]
+
+
+def _rule_title(rule) -> str:
+    if not isinstance(rule, dict):
+        return "(rule)"
+    return str(rule.get("id") or rule.get("topic") or rule.get("description", "")[:60] or "(rule)")
+
+
+# ---------------------------------------------------------------------------
+# ledger
+# ---------------------------------------------------------------------------
+def glob_ledger(repo_root: Path, base_ref: str) -> list:
+    """Union of all claims from `.archie/changes/change_*.json` new on the branch.
+
+    `latest.json` is overwritten on every record, so it is NOT a complete source — we
+    glob the versioned files. Records already present on the base ref are skipped.
+    Malformed records are skipped, not fatal. Claims deduped by id (or statement).
+    """
+    changes_dir = repo_root / ".archie" / "changes"
+    if not changes_dir.is_dir():
+        return []
+
+    # which change files already exist on the base ref (so they aren't "new")
+    base_files = set()
+    code, out, _ = run_git(repo_root, "ls-tree", "-r", "--name-only", base_ref, ".archie/changes")
+    if code == 0:
+        base_files = {line.strip() for line in out.splitlines() if line.strip()}
+
+    claims = []
+    seen = set()
+    for fp in sorted(changes_dir.glob("change_*.json")):
+        rel = f".archie/changes/{fp.name}"
+        if rel in base_files:
+            continue  # already on base — not part of this PR's intent
+        try:
+            record = json.loads(fp.read_text())
+        except (OSError, json.JSONDecodeError):
+            continue
+        for claim in (record.get("claims") or []):
+            if not isinstance(claim, dict):
+                continue
+            key = claim.get("id") or claim.get("statement")
+            if key in seen:
+                continue
+            seen.add(key)
+            claims.append(claim)
+    return claims
+
+
+def ledger_join(changed_item: dict, claims: list):
+    """Conservative join: attach a claim's confidence to an invariant change only when
+    file paths overlap AND keyword overlap clears the threshold. No match -> None
+    (the finding still surfaces, just without the confidence sharpener — never guess).
+    """
+    item_files = set(changed_item.get("enforced_at_files") or [])
+    item_kw = set(changed_item.get("keywords") or [])
+    best = None
+    for claim in claims:
+        if not isinstance(claim, dict):
+            continue
+        claim_files = set(str(f) for f in (claim.get("evidence_files") or []))
+        file_overlap = bool(item_files & claim_files) or _path_overlap(item_files, claim_files)
+        claim_kw = set(_keywords_from_text(str(claim.get("statement", ""))))
+        kw_overlap = len(item_kw & claim_kw)
+        if file_overlap and kw_overlap >= KEYWORD_JOIN_THRESHOLD:
+            cand = {
+                "confidence": claim.get("confidence"),
+                "reconstructed": bool(claim.get("reconstructed", False)),
+                "statement": claim.get("statement"),
+            }
+            if best is None or kw_overlap > best.get("_kw", 0):
+                cand["_kw"] = kw_overlap
+                best = cand
+    if best:
+        best.pop("_kw", None)
+    return best
+
+
+def _path_overlap(a: set, b: set) -> bool:
+    for x in a:
+        for y in b:
+            if x and y and (x == y or x.endswith("/" + y) or y.endswith("/" + x)
+                            or x in y or y in x):
+                return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# retained rules (context for the model)
+# ---------------------------------------------------------------------------
+def retained_rules(base_rules: list, changed_items: list) -> list:
+    """Base-ref rules NOT themselves changed, optionally relevance-filtered."""
+    changed_rule_keys = {
+        it["title"] for it in changed_items if it.get("source") == "rules"
+    }
+    retained = [r for r in base_rules if isinstance(r, dict)
+                and _rule_title(r) not in changed_rule_keys]
+    if len(retained) <= RELEVANCE_SEND_ALL_THRESHOLD:
+        return retained
+    # relevance filter: keep rules sharing a keyword with any changed item
+    changed_kw = set()
+    for it in changed_items:
+        changed_kw |= set(it.get("keywords") or [])
+        changed_kw |= set(_keywords_from_text(it.get("title", "")))
+    filtered = []
+    for r in retained:
+        rkw = set(_keywords_of(r)) | set(_keywords_from_text(str(r.get("description", ""))))
+        if rkw & changed_kw:
+            filtered.append(r)
+    return filtered or retained[:RELEVANCE_SEND_ALL_THRESHOLD]
+
+
+# ---------------------------------------------------------------------------
+# model call
+# ---------------------------------------------------------------------------
+EMIT_FINDINGS_TOOL = {
+    "name": "emit_findings",
+    "description": (
+        "Emit structured review findings about a PR's change to the architectural "
+        "source of truth. For each CHANGED ITEM you judge to be a real concern, emit a "
+        "finding. The diff op and which item changed are GIVEN to you (cite item_ref). "
+        "Your job is ONLY to judge the TYPE and write a verifiable, cited BECAUSE drawn "
+        "from the item's own text and the retained rules. BECAUSE-OR-SUPPRESS: if you "
+        "cannot ground a finding in the provided texts, omit it entirely."
+    ),
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "findings": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "item_ref": {"type": "string",
+                                     "description": "ref of the CHANGED ITEM this is about (e.g. c0). Findings referencing no listed item are discarded."},
+                        "type": {"type": "string",
+                                 "enum": ["silent_weakening", "contradiction", "behavior_violates_rule"]},
+                        "rule_name": {"type": "string", "description": "the invariant/rule this concerns"},
+                        "what_changed": {"type": "string"},
+                        "because": {"type": "string",
+                                    "description": "verifiable cited rationale from the texts; empty => dropped"},
+                    },
+                    "required": ["item_ref", "type", "rule_name", "what_changed", "because"],
+                },
+            },
+        },
+        "required": ["findings"],
+    },
+}
+
+
+def build_prompt(changed_items: list, retained: list, claims: list) -> tuple:
+    """Return (system, user) prompt strings. Pure; token-bounded payload."""
+    system = (
+        "You are an architecture reviewer for a pull request. The change has already been "
+        "folded into the project's blueprint and rules; you are given a DETERMINISTIC diff "
+        "of the source of truth (you do NOT decide what changed). Judge each CHANGED ITEM:\n"
+        "- silent_weakening: a REMOVE/UPDATE that retires or softens an invariant or key decision.\n"
+        "- contradiction: an ADD/UPDATE to the rules that conflicts with a RETAINED rule.\n"
+        "- behavior_violates_rule: a described behavior/data change that breaks a RETAINED rule.\n"
+        "Only emit a finding when it is real and you can cite WHY from the provided texts "
+        "(because-or-suppress). Do not flag benign additions. Call emit_findings exactly once."
+    )
+
+    def trim(item, n=600):
+        s = json.dumps(item, ensure_ascii=False)
+        return s if len(s) <= n else s[:n] + "...(truncated)"
+
+    lines = ["CHANGED ITEMS (cite item_ref):"]
+    for it in changed_items:
+        lines.append(
+            f"- ref={it['ref']} layer={it['layer']} op={it['diff_op']} "
+            f"section={it['section']} title={it['title']!r}"
+        )
+        if it.get("base_item") is not None:
+            lines.append(f"    base: {trim(it['base_item'])}")
+        if it.get("branch_item") is not None:
+            lines.append(f"    branch: {trim(it['branch_item'])}")
+        if it.get("fields_changed"):
+            lines.append(f"    fields_changed: {it['fields_changed']}")
+    lines.append("")
+    lines.append("RETAINED RULES (must still hold):")
+    for r in retained:
+        lines.append(f"- {trim(r, 400)}")
+    if claims:
+        lines.append("")
+        lines.append("DECLARED INTENT (sync ledger claims, context only):")
+        for c in claims:
+            lines.append(f"- kind={c.get('kind')} conf={c.get('confidence')} "
+                         f"stmt={str(c.get('statement',''))[:160]!r}")
+    return system, "\n".join(lines)
+
+
+def call_anthropic(system: str, user: str, api_key: str, max_retries: int = 3) -> list:
+    """POST one Messages request forcing the emit_findings tool. Return the raw
+    findings list from the model (judgment only). Raises RuntimeError on hard failure.
+    """
+    body = json.dumps({
+        "model": MODEL,
+        "max_tokens": MAX_TOKENS,
+        "system": system,
+        "tools": [EMIT_FINDINGS_TOOL],
+        "tool_choice": {"type": "tool", "name": "emit_findings"},
+        "messages": [{"role": "user", "content": user}],
+    }).encode("utf-8")
+
+    last_err = None
+    for attempt in range(max_retries):
+        req = urllib.request.Request(ANTHROPIC_URL, data=body, method="POST", headers={
+            "x-api-key": api_key,
+            "anthropic-version": ANTHROPIC_VERSION,
+            "content-type": "application/json",
+        })
+        try:
+            with urllib.request.urlopen(req, timeout=90) as resp:
+                payload = json.loads(resp.read().decode("utf-8"))
+            return _extract_findings(payload)
+        except urllib.error.HTTPError as e:
+            last_err = f"HTTP {e.code}"
+            if e.code in (429, 500, 502, 503, 529) and attempt < max_retries - 1:
+                retry_after = e.headers.get("Retry-After") if e.headers else None
+                delay = float(retry_after) if retry_after and retry_after.isdigit() \
+                    else min(2 ** attempt, 30)
+                time.sleep(delay)
+                continue
+            raise RuntimeError(f"Anthropic API error: {last_err}: {e.read().decode('utf-8', 'replace')[:300]}")
+        except (urllib.error.URLError, TimeoutError) as e:
+            last_err = str(e)
+            if attempt < max_retries - 1:
+                time.sleep(min(2 ** attempt, 30))
+                continue
+            raise RuntimeError(f"Anthropic API unreachable: {last_err}")
+    raise RuntimeError(f"Anthropic API failed: {last_err}")
+
+
+def _extract_findings(api_response: dict) -> list:
+    """Pull the emit_findings tool_use input out of a Messages response."""
+    for block in (api_response.get("content") or []):
+        if block.get("type") == "tool_use" and block.get("name") == "emit_findings":
+            inp = block.get("input") or {}
+            findings = inp.get("findings")
+            return findings if isinstance(findings, list) else []
+    return []
+
+
+# ---------------------------------------------------------------------------
+# finalize: overwrite deterministic fields, because-or-suppress, ledger join
+# ---------------------------------------------------------------------------
+def finalize_findings(model_findings: list, changed_items: list, claims: list) -> list:
+    """Bind each model finding to its real changed item, overwrite the deterministic
+    fields from the script's own diff, drop unciteable/unmatched findings, and attach a
+    ledger-confidence sharpener where the conservative join succeeds.
+    """
+    by_ref = {it["ref"]: it for it in changed_items}
+    out = []
+    for f in model_findings:
+        if not isinstance(f, dict):
+            continue
+        item = by_ref.get(f.get("item_ref"))
+        if item is None:
+            continue  # references no real diff item -> drop
+        because = str(f.get("because", "")).strip()
+        if not because:
+            continue  # because-or-suppress
+        finding = {
+            # deterministic, script-owned (overwrite the model's echo):
+            "diff_op": item["diff_op"],
+            "layer": item["layer"],
+            "section": item["section"],
+            "rule_name": item["title"],
+            # model judgment:
+            "type": f.get("type", "behavior_violates_rule"),
+            "what_changed": str(f.get("what_changed", "")).strip(),
+            "because": because,
+            "confidence": None,
+        }
+        join = ledger_join(item, claims)
+        if join:
+            finding["confidence"] = join.get("confidence")
+            finding["reconstructed"] = join.get("reconstructed")
+        out.append(finding)
+    return out
+
+
+# ---------------------------------------------------------------------------
+# render + post comment
+# ---------------------------------------------------------------------------
+_FLAG_HEADERS = {
+    "silent_weakening": "⚠️ Silent weakening / removal",
+    "contradiction": "⚠️ Contradiction with a retained rule",
+    "behavior_violates_rule": "⚠️ Behavior may violate a rule",
+}
+_FLAG_ORDER = ["silent_weakening", "contradiction", "behavior_violates_rule"]
+
+
+def render_comment(findings: list, had_diff: bool):
+    """Return the markdown comment body, or None to post nothing."""
+    if not had_diff:
+        return None
+    if not findings:
+        return (f"{COMMENT_MARKER}\n## 📐 Archie Intent Review\n\n"
+                "No findings — the blueprint changes in this PR are consistent with the "
+                "retained rules.\n\n*Archie surfaces; it doesn't block.*")
+
+    lines = [COMMENT_MARKER, "## 📐 Archie Intent Review", ""]
+    n = len(findings)
+    lines.append(f"This PR changes the architectural source of truth. **{n} finding"
+                 f"{'s' if n != 1 else ''}** for a human to weigh:")
+    for flag in _FLAG_ORDER:
+        group = [f for f in findings if f.get("type") == flag]
+        if not group:
+            continue
+        lines.append("")
+        lines.append(f"### {_FLAG_HEADERS[flag]}")
+        for f in group:
+            conf = ""
+            if f.get("confidence"):
+                rec = " · reconstructed guess" if f.get("reconstructed") else ""
+                conf = f" _(ledger confidence: {f['confidence']}{rec})_"
+            lines.append(
+                f"- **{f['rule_name']}** ({f['diff_op']}, Layer {f['layer']}){conf}  \n"
+                f"  {f['what_changed']}  \n"
+                f"  _Because:_ {f['because']}"
+            )
+    lines.append("")
+    lines.append("*Archie surfaces; it doesn't block. Whether a change means \"fix the "
+                 "code\" or \"evolve the rule\" is your call — merge accepts the blueprint "
+                 "changes above as the new baseline.*")
+    return "\n".join(lines)
+
+
+def _gh_request(method: str, url: str, token: str, body: dict = None):
+    data = json.dumps(body).encode("utf-8") if body is not None else None
+    req = urllib.request.Request(url, data=data, method=method, headers={
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+        "Content-Type": "application/json",
+        "User-Agent": "archie-intent-review",
+    })
+    with urllib.request.urlopen(req, timeout=30) as resp:
+        raw = resp.read().decode("utf-8")
+        return json.loads(raw) if raw.strip() else {}
+
+
+def post_or_update_comment(owner, repo, pr_number, body, token):
+    """Upsert the single Archie comment (find by marker -> PATCH, else POST)."""
+    list_url = f"{GITHUB_API}/repos/{owner}/{repo}/issues/{pr_number}/comments?per_page=100"
+    existing_id = None
+    try:
+        comments = _gh_request("GET", list_url, token)
+        for c in comments if isinstance(comments, list) else []:
+            if COMMENT_MARKER in (c.get("body") or ""):
+                existing_id = c.get("id")
+                break
+    except urllib.error.HTTPError as e:  # pragma: no cover - network
+        print(f"[intent-review] could not list comments: HTTP {e.code}", file=sys.stderr)
+
+    if existing_id:
+        url = f"{GITHUB_API}/repos/{owner}/{repo}/issues/comments/{existing_id}"
+        _gh_request("PATCH", url, token, {"body": body})
+        print(f"[intent-review] updated comment {existing_id}")
+    else:
+        url = f"{GITHUB_API}/repos/{owner}/{repo}/issues/{pr_number}/comments"
+        _gh_request("POST", url, token, {"body": body})
+        print("[intent-review] posted new comment")
+
+
+# ---------------------------------------------------------------------------
+# event context
+# ---------------------------------------------------------------------------
+def parse_event_context(env: dict):
+    """Return (owner, repo, pr_number, base_ref) or None if not a usable PR event."""
+    repo_full = env.get("GITHUB_REPOSITORY", "")
+    base_ref = env.get("GITHUB_BASE_REF", "")
+    event_path = env.get("GITHUB_EVENT_PATH", "")
+    if "/" not in repo_full:
+        return None
+    owner, repo = repo_full.split("/", 1)
+    pr_number = None
+    if event_path and Path(event_path).exists():
+        try:
+            event = json.loads(Path(event_path).read_text())
+            pr = event.get("pull_request")
+            if isinstance(pr, dict):
+                pr_number = pr.get("number")
+                base_ref = base_ref or (pr.get("base") or {}).get("ref", "")
+        except (OSError, json.JSONDecodeError):
+            return None
+    if pr_number is None or not base_ref:
+        return None
+    return owner, repo, pr_number, base_ref
+
+
+# ---------------------------------------------------------------------------
+# main
+# ---------------------------------------------------------------------------
+def main(argv=None) -> int:
+    repo_root = Path(os.environ.get("GITHUB_WORKSPACE") or ".").resolve()
+    env = os.environ
+
+    # 1. Fork-PR / no-secret guard FIRST — before any GitHub write.
+    api_key = env.get("ANTHROPIC_API_KEY", "").strip()
+    if not api_key:
+        print("[intent-review] ANTHROPIC_API_KEY not set (fork PR?) — skipping.", file=sys.stderr)
+        return 0
+
+    ctx = parse_event_context(env)
+    if ctx is None:
+        print("[intent-review] not a usable pull_request event — skipping.", file=sys.stderr)
+        return 0
+    owner, repo, pr_number, base_ref = ctx
+    token = env.get("GITHUB_TOKEN", "").strip()
+    base_ref_full = f"origin/{base_ref}"
+
+    # 2. Load branch + base versions of the source of truth.
+    b_exists, branch_bp, b_err = load_branch_file(repo_root, ".archie/blueprint.json")
+    if b_exists and branch_bp is None:
+        # branch blueprint is malformed — surface, don't crash.
+        if token:
+            post_or_update_comment(owner, repo, pr_number,
+                                   f"{COMMENT_MARKER}\n## 📐 Archie Intent Review\n\n"
+                                   f"Could not parse `.archie/blueprint.json` on this branch "
+                                   f"({b_err}). Manual review needed.", token)
+        return 0
+    if not b_exists:
+        print("[intent-review] no .archie/blueprint.json on branch — nothing to review.", file=sys.stderr)
+        return 0
+
+    _, base_bp, _ = fetch_base_file(repo_root, base_ref_full, ".archie/blueprint.json")
+    base_bp = base_bp if isinstance(base_bp, dict) else {}
+
+    _, base_rules_raw, _ = fetch_base_file(repo_root, base_ref_full, ".archie/rules.json")
+    _, branch_rules_raw, _ = load_branch_file(repo_root, ".archie/rules.json")
+    base_rules = normalize_rules(base_rules_raw)
+    branch_rules = normalize_rules(branch_rules_raw)
+
+    claims = glob_ledger(repo_root, base_ref_full)
+
+    # 3. Deterministic diff -> changed items.
+    changed_items = build_changed_items(base_bp, branch_bp, base_rules, branch_rules, claims)
+    had_diff = bool(changed_items)
+    if not had_diff:
+        print("[intent-review] no source-of-truth changes detected — posting nothing.", file=sys.stderr)
+        return 0
+
+    # 4. Judge with one model call.
+    retained = retained_rules(base_rules, changed_items)
+    system, user = build_prompt(changed_items, retained, claims)
+    try:
+        model_findings = call_anthropic(system, user, api_key)
+    except RuntimeError as e:
+        print(f"[intent-review] model call failed: {e}", file=sys.stderr)
+        return 0  # never block
+    findings = finalize_findings(model_findings, changed_items, claims)
+
+    # 5. Render + upsert.
+    body = render_comment(findings, had_diff)
+    if body is None:
+        return 0
+    if not token:
+        print("[intent-review] no GITHUB_TOKEN — printing body:\n" + body)
+        return 0
+    try:
+        post_or_update_comment(owner, repo, pr_number, body, token)
+    except urllib.error.HTTPError as e:  # pragma: no cover - network
+        print(f"[intent-review] could not post comment: HTTP {e.code}", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/npm-package/assets/setup-archie-intent-review.sh b/npm-package/assets/setup-archie-intent-review.sh
new file mode 100755
index 0000000..89229a3
--- /dev/null
+++ b/npm-package/assets/setup-archie-intent-review.sh
@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# setup-archie-intent-review.sh
+#
+# Idempotent setup for the Archie Intent Review GitHub Action.
+# Prereq checks, secure secret setup, workflow install (copies the canonical
+# YAML — no embedded duplicate), Actions probe, fork-PR caveat.
+#
+# Usage: bash setup-archie-intent-review.sh
+set -euo pipefail
+
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; BLUE='\033[0;34m'; NC='\033[0m'
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="${REPO_ROOT:-.}"
+WORKFLOW_FILE="${REPO_ROOT}/.github/workflows/archie-intent-review.yml"
+
+log_info()    { echo -e "${BLUE}i ${NC}$*"; }
+log_success() { echo -e "${GREEN}OK ${NC}$*"; }
+log_warn()    { echo -e "${YELLOW}! ${NC}$*"; }
+log_error()   { echo -e "${RED}x ${NC}$*"; }
+die() { log_error "$1"; exit 1; }
+
+# Resolve the canonical workflow YAML (single source of truth). Priority:
+#  1. .archie/workflows/  (if the npx bundle ever places it there)
+#  2. <script dir>/workflows/  (running from a checked-out asset bundle)
+resolve_workflow_src() {
+    local candidates=(
+        "${REPO_ROOT}/.archie/workflows/archie-intent-review.yml"
+        "${SCRIPT_DIR}/workflows/archie-intent-review.yml"
+    )
+    for c in "${candidates[@]}"; do
+        if [ -f "$c" ]; then printf '%s\n' "$c"; return 0; fi
+    done
+    return 1
+}
+
+# ===== SECTION 1: PREREQUISITES =====
+log_info "Checking prerequisites..."
+
+git rev-parse --git-dir >/dev/null 2>&1 || die "Not inside a git repository. Run from the repo root."
+log_success "Inside a git repository"
+
+git config --get remote.origin.url >/dev/null 2>&1 || die "No 'origin' remote found."
+log_success "Git remote 'origin' found"
+
+command -v gh >/dev/null 2>&1 || die "gh CLI not found. Install from https://github.com/cli/cli or 'brew install gh'."
+log_success "gh CLI is installed ($(gh --version | head -1))"
+
+gh auth status >/dev/null 2>&1 || die "gh CLI not authenticated. Run 'gh auth login' first."
+GITHUB_ACCOUNT="$(gh api user --jq .login)"
+log_success "gh authenticated as ${GITHUB_ACCOUNT}"
+
+[ -f "${REPO_ROOT}/.archie/blueprint.json" ] || die ".archie/blueprint.json not found. Run '/archie-deep-scan' first to establish the baseline."
+log_success ".archie/blueprint.json baseline exists"
+
+WORKFLOW_SRC="$(resolve_workflow_src)" || die "Canonical workflow YAML not found (looked in .archie/workflows/ and ${SCRIPT_DIR}/workflows/). Reinstall archie assets."
+log_success "Canonical workflow YAML resolved: ${WORKFLOW_SRC}"
+
+# ===== SECTION 2: SECRET SETUP =====
+log_info "Setting up ANTHROPIC_API_KEY secret (available to GitHub Actions on this repo)..."
+printf 'Enter your ANTHROPIC_API_KEY (will not be displayed): '
+read -rs ANTHROPIC_API_KEY
+echo ""
+[ -n "$ANTHROPIC_API_KEY" ] || die "ANTHROPIC_API_KEY cannot be empty."
+
+printf '%s' "$ANTHROPIC_API_KEY" | gh secret set ANTHROPIC_API_KEY
+unset ANTHROPIC_API_KEY
+log_success "ANTHROPIC_API_KEY secret set (stored encrypted on GitHub)"
+
+# ===== SECTION 3: WORKFLOW INSTALL (copy canonical, no heredoc) =====
+log_info "Installing workflow file..."
+mkdir -p "$(dirname "$WORKFLOW_FILE")"
+cp "$WORKFLOW_SRC" "$WORKFLOW_FILE"
+log_success "Workflow installed at ${WORKFLOW_FILE} (byte-identical to canonical)"
+
+# ===== SECTION 4: ACTIONS ENABLEMENT PROBE (advisory) =====
+log_info "Probing GitHub Actions (advisory only)..."
+REPO_SLUG="$(git config --get remote.origin.url | sed 's|.*github.com[:/]||; s|\.git$||')"
+if gh workflow list -R "$REPO_SLUG" >/dev/null 2>&1; then
+    log_success "Actions appear enabled (probe is advisory; verify in repo settings if unsure)"
+else
+    log_warn "Could not verify Actions status — you may need to enable Actions on GitHub"
+fi
+
+# ===== SECTION 5: SUMMARY & CAVEATS =====
+log_success "Setup complete."
+echo ""
+echo "Next steps:"
+echo "  1. Commit .github/workflows/archie-intent-review.yml"
+echo "  2. Push and open a PR"
+echo "  3. The Action posts an FYI comment on the PR"
+echo ""
+echo -e "${YELLOW}Fork PR limitation:${NC}"
+echo "  - Uses the 'pull_request' event (non-blocking FYI)."
+echo "  - Fork PRs cannot access repo secrets; the Action skips silently on them."
+echo "  - To cover fork PRs, 'pull_request_target' is a security tradeoff (out of scope)."
+echo ""
+log_info "To rotate the key later: gh secret set ANTHROPIC_API_KEY"
+log_info "Design doc: docs/archie-intent-review-design.md"
diff --git a/npm-package/assets/workflows/archie-intent-review.yml b/npm-package/assets/workflows/archie-intent-review.yml
new file mode 100644
index 0000000..918b4e2
--- /dev/null
+++ b/npm-package/assets/workflows/archie-intent-review.yml
@@ -0,0 +1,29 @@
+name: Archie Intent Review
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+permissions:
+  pull-requests: write
+  contents: read
+
+jobs:
+  intent-review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Fetch base ref
+        run: git fetch --no-tags --depth=1 origin "${{ github.base_ref }}"
+
+      - name: Run Archie Intent Review
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: python3 .archie/intent_review.py
diff --git a/npm-package/bin/archie.mjs b/npm-package/bin/archie.mjs
index b24d2df..3319fd8 100755
--- a/npm-package/bin/archie.mjs
+++ b/npm-package/bin/archie.mjs
@@ -356,7 +356,7 @@ if (cleanedCount > 0) {
   console.log(`  ${DIM}cleaned ${cleanedCount} previous Archie files${RESET}`);
 }
 
-for (const script of ["_common.py", "scanner.py", "refresh.py", "intent_layer.py", "renderer.py", "install_hooks.py", "merge.py", "finalize.py", "validate.py", "viewer.py", "c4.py", "extract_output.py", "arch_review.py", "measure_health.py", "check_rules.py", "detect_cycles.py", "upload.py", "share_setup.py", "telemetry.py", "lint_gate.py", "code_shape.py", "rule_index.py", "align_check.py", "agent_cli.py", "verify_findings.py", "apply_verdicts.py", "migrate_blueprint_rules.py", "rule_kinds.py", "backfill_kinds.py", "config.py", "telemetry_sync.py", "update_check.py", "analytics.py", "sync.py"]) {
+for (const script of ["_common.py", "scanner.py", "refresh.py", "intent_layer.py", "renderer.py", "install_hooks.py", "merge.py", "finalize.py", "validate.py", "viewer.py", "c4.py", "extract_output.py", "arch_review.py", "measure_health.py", "check_rules.py", "detect_cycles.py", "upload.py", "share_setup.py", "telemetry.py", "lint_gate.py", "code_shape.py", "rule_index.py", "align_check.py", "agent_cli.py", "verify_findings.py", "apply_verdicts.py", "migrate_blueprint_rules.py", "rule_kinds.py", "backfill_kinds.py", "config.py", "telemetry_sync.py", "update_check.py", "analytics.py", "sync.py", "intent_review.py"]) {
   const src = join(ASSETS, script);
   const dest = join(archieDir, script);
   if (existsSync(src)) {
diff --git a/scripts/verify_sync.py b/scripts/verify_sync.py
index 49c819e..c03681a 100644
--- a/scripts/verify_sync.py
+++ b/scripts/verify_sync.py
@@ -203,6 +203,49 @@ def check_archie_asset_mirrors(errors: list[str]) -> None:
                     f"OUT OF SYNC: archie/assets/workflow/{rel} != npm-package/assets/workflow/{rel}"
                 )
 
+    # CI workflow files (PLURAL `workflows/`, distinct from the singular skill tree):
+    # archie/assets/workflows/ is canonical; npm-package/assets/workflows/ is the mirror.
+    # Globs ALL files so the .yml content is byte-checked (the main loop only does .py/.json).
+    backend_workflows = ARCHIE_ASSETS / "workflows"
+    asset_workflows = ASSETS / "workflows"
+    if backend_workflows.is_dir() and not asset_workflows.is_dir():
+        errors.append("npm-package/assets/workflows/ missing")
+    elif backend_workflows.is_dir() and asset_workflows.is_dir():
+        backend_files = sorted(
+            p.relative_to(backend_workflows).as_posix()
+            for p in backend_workflows.rglob("*")
+            if p.is_file() and p.name != ".DS_Store"
+        )
+        asset_files = sorted(
+            p.relative_to(asset_workflows).as_posix()
+            for p in asset_workflows.rglob("*")
+            if p.is_file() and p.name != ".DS_Store"
+        )
+        only_backend = set(backend_files) - set(asset_files)
+        only_asset = set(asset_files) - set(backend_files)
+        if only_backend:
+            errors.append(
+                "npm-package/assets/workflows/ missing files: " + ",".join(sorted(only_backend))
+            )
+        if only_asset:
+            errors.append(
+                "npm-package/assets/workflows/ has stale files: " + ",".join(sorted(only_asset))
+            )
+        for rel in sorted(set(backend_files) & set(asset_files)):
+            if (backend_workflows / rel).read_bytes() != (asset_workflows / rel).read_bytes():
+                errors.append(
+                    f"OUT OF SYNC: archie/assets/workflows/{rel} != npm-package/assets/workflows/{rel}"
+                )
+
+    # Standalone setup helper (.sh is not covered by any glob above).
+    for name in ("setup-archie-intent-review.sh",):
+        backend = ARCHIE_ASSETS / name
+        asset = ASSETS / name
+        if backend.exists() and not asset.exists():
+            errors.append(f"npm-package/assets/{name} missing")
+        elif backend.exists() and asset.exists() and backend.read_bytes() != asset.read_bytes():
+            errors.append(f"OUT OF SYNC: archie/assets/{name} != npm-package/assets/{name}")
+
 
 def check_install_pkg_mirror(errors: list[str]) -> None:
     """Verify npm-package/assets/_install_pkg mirrors the canonical installer code."""
diff --git a/tests/test_intent_review.py b/tests/test_intent_review.py
new file mode 100644
index 0000000..5333ca9
--- /dev/null
+++ b/tests/test_intent_review.py
@@ -0,0 +1,402 @@
+"""Tests for intent_review.py — the PR-time semantic review.
+
+Covers the deterministic, network-free core: keyed diff, base-ref fetch, ledger glob,
+event parsing, the conservative ledger join, the deterministic-field overwrite +
+because-or-suppress filter, and comment rendering. The two network calls
+(call_anthropic, post_or_update_comment) are exercised with monkeypatched urllib.
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+_STANDALONE = Path(__file__).resolve().parent.parent / "archie" / "standalone"
+sys.path.insert(0, str(_STANDALONE))
+
+import intent_review as ir  # noqa: E402
+
+
+# ---------------------------------------------------------------------------
+# git helpers (mirror test_sync.py)
+# ---------------------------------------------------------------------------
+def _git(root: Path, *args: str) -> str:
+    return subprocess.run(
+        ["git", "-C", str(root), *args],
+        check=True, capture_output=True, text=True,
+    ).stdout.strip()
+
+
+def _init_repo(tmp_path: Path) -> Path:
+    _git(tmp_path, "init", "-q")
+    _git(tmp_path, "config", "user.email", "t@t.com")
+    _git(tmp_path, "config", "user.name", "Tester")
+    _git(tmp_path, "checkout", "-q", "-b", "main")
+    return tmp_path
+
+
+def _write(root: Path, rel: str, data) -> None:
+    p = root / rel
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(json.dumps(data, indent=2) if not isinstance(data, str) else data)
+
+
+def _commit(root: Path, msg: str) -> None:
+    _git(root, "add", "-A")
+    _git(root, "commit", "-q", "-m", msg)
+
+
+# ---------------------------------------------------------------------------
+# normalize_rules
+# ---------------------------------------------------------------------------
+def test_normalize_rules_shapes():
+    assert ir.normalize_rules({"rules": [{"id": "r1"}]}) == [{"id": "r1"}]
+    assert ir.normalize_rules([{"id": "r1"}]) == [{"id": "r1"}]
+    assert ir.normalize_rules(None) == []
+    assert ir.normalize_rules({}) == []
+    assert ir.normalize_rules({"rules": "bad"}) == []
+    assert ir.normalize_rules(42) == []
+
+
+# ---------------------------------------------------------------------------
+# keyed_diff
+# ---------------------------------------------------------------------------
+def test_keyed_diff_remove_update_add():
+    base = [{"id": "a", "v": 1}, {"id": "b", "v": 1}]
+    branch = [{"id": "b", "v": 2}, {"id": "c", "v": 1}]
+    diffs = {d["key"]: d for d in ir.keyed_diff(base, branch, "id", "v")}
+    assert diffs["a"]["status"] == "REMOVE"
+    assert diffs["b"]["status"] == "UPDATE"
+    assert "v" in diffs["b"]["fields_changed"]
+    assert diffs["c"]["status"] == "ADD"
+
+
+def test_keyed_diff_reorder_is_noop():
+    base = [{"id": "a", "v": 1}, {"id": "b", "v": 2}]
+    branch = [{"id": "b", "v": 2}, {"id": "a", "v": 1}]
+    assert ir.keyed_diff(base, branch, "id", "v") == []
+
+
+def test_keyed_diff_title_hash_fallback():
+    # no id field -> keyed on hash of the title field
+    base = [{"title": "Tenant isolation", "body": "x"}]
+    branch = [{"title": "Tenant isolation", "body": "y"}]
+    diffs = ir.keyed_diff(base, branch, None, "title")
+    assert len(diffs) == 1
+    assert diffs[0]["status"] == "UPDATE"
+    assert diffs[0]["key"] == ir._hash_title("Tenant isolation")
+
+
+def test_keyed_diff_handles_missing_or_nonlist():
+    assert ir.keyed_diff(None, None, "id", "t") == []
+    add_only = ir.keyed_diff([], [{"id": "x"}], "id", "t")
+    assert add_only[0]["status"] == "ADD"
+
+
+# ---------------------------------------------------------------------------
+# fetch_base_file / load_branch_file
+# ---------------------------------------------------------------------------
+def test_fetch_base_file_present_and_absent(tmp_path):
+    root = _init_repo(tmp_path)
+    _write(root, ".archie/blueprint.json", {"domain_invariants": [{"id": "d1"}]})
+    _commit(root, "base")
+
+    exists, data, err = ir.fetch_base_file(root, "main", ".archie/blueprint.json")
+    assert exists and err is None
+    assert data["domain_invariants"][0]["id"] == "d1"
+
+    # absent file on the ref -> (False, None, None) => treat as all-ADD
+    exists, data, err = ir.fetch_base_file(root, "main", ".archie/rules.json")
+    assert exists is False and data is None and err is None
+
+
+def test_fetch_base_file_malformed(tmp_path):
+    root = _init_repo(tmp_path)
+    _write(root, ".archie/blueprint.json", "{not valid json")
+    _commit(root, "bad")
+    exists, data, err = ir.fetch_base_file(root, "main", ".archie/blueprint.json")
+    assert exists is True and data is None and err is not None
+
+
+def test_load_branch_file_missing_and_empty(tmp_path):
+    root = _init_repo(tmp_path)
+    exists, data, err = ir.load_branch_file(root, ".archie/rules.json")
+    assert exists is False and data is None
+    _write(root, ".archie/rules.json", "")
+    exists, data, err = ir.load_branch_file(root, ".archie/rules.json")
+    assert exists is True and data == {} and err is None
+    # empty rules normalize to []
+    assert ir.normalize_rules(data) == []
+
+
+# ---------------------------------------------------------------------------
+# glob_ledger
+# ---------------------------------------------------------------------------
+def test_glob_ledger_unions_and_skips_malformed(tmp_path):
+    root = _init_repo(tmp_path)
+    # base commit with no changes dir
+    _write(root, "seed.txt", "seed")
+    _commit(root, "seed")
+
+    _write(root, ".archie/changes/change_1.json",
+           {"claims": [{"id": "rule:a", "kind": "rule", "statement": "A"}]})
+    _write(root, ".archie/changes/change_2.json",
+           {"claims": [{"id": "behavior:b", "kind": "behavior", "statement": "B"},
+                       {"id": "rule:a", "kind": "rule", "statement": "A"}]})  # dup id
+    (root / ".archie/changes/change_3.json").write_text("{bad json")
+    (root / ".archie/changes/latest.json").write_text(
+        json.dumps({"claims": [{"id": "z", "kind": "rule", "statement": "Z"}]}))
+
+    claims = ir.glob_ledger(root, "main")
+    ids = sorted(c["id"] for c in claims)
+    # union of change_1 + change_2, dedup rule:a, malformed skipped, latest.json ignored
+    assert ids == ["behavior:b", "rule:a"]
+
+
+def test_glob_ledger_excludes_records_on_base(tmp_path):
+    root = _init_repo(tmp_path)
+    _write(root, ".archie/changes/change_1.json",
+           {"claims": [{"id": "old", "kind": "rule", "statement": "old"}]})
+    _commit(root, "base has change_1")
+    _git(root, "checkout", "-q", "-b", "feature")
+    _write(root, ".archie/changes/change_2.json",
+           {"claims": [{"id": "new", "kind": "rule", "statement": "new"}]})
+    _commit(root, "feature adds change_2")
+
+    claims = ir.glob_ledger(root, "main")  # base = main (only has change_1)
+    ids = [c["id"] for c in claims]
+    assert ids == ["new"]  # change_1 is on base -> excluded
+
+
+# ---------------------------------------------------------------------------
+# parse_event_context
+# ---------------------------------------------------------------------------
+def test_parse_event_context_ok(tmp_path):
+    event = tmp_path / "event.json"
+    event.write_text(json.dumps({"pull_request": {"number": 42, "base": {"ref": "main"}}}))
+    ctx = ir.parse_event_context({
+        "GITHUB_REPOSITORY": "octo/repo",
+        "GITHUB_BASE_REF": "main",
+        "GITHUB_EVENT_PATH": str(event),
+    })
+    assert ctx == ("octo", "repo", 42, "main")
+
+
+def test_parse_event_context_pulls_base_from_payload(tmp_path):
+    event = tmp_path / "event.json"
+    event.write_text(json.dumps({"pull_request": {"number": 7, "base": {"ref": "develop"}}}))
+    ctx = ir.parse_event_context({
+        "GITHUB_REPOSITORY": "octo/repo",
+        "GITHUB_BASE_REF": "",
+        "GITHUB_EVENT_PATH": str(event),
+    })
+    assert ctx == ("octo", "repo", 7, "develop")
+
+
+def test_parse_event_context_rejects_non_pr(tmp_path):
+    event = tmp_path / "event.json"
+    event.write_text(json.dumps({"push": {}}))
+    ctx = ir.parse_event_context({
+        "GITHUB_REPOSITORY": "octo/repo",
+        "GITHUB_BASE_REF": "main",
+        "GITHUB_EVENT_PATH": str(event),
+    })
+    assert ctx is None
+    # malformed repo
+    assert ir.parse_event_context({"GITHUB_REPOSITORY": "noslash"}) is None
+
+
+# ---------------------------------------------------------------------------
+# build_changed_items
+# ---------------------------------------------------------------------------
+def test_build_changed_items_invariant_remove_and_claim():
+    base_bp = {"domain_invariants": [
+        {"id": "INV1", "invariant": "tenant writes scoped", "keywords": ["tenant"],
+         "enforced_at": ["db/payments.py:10"]}]}
+    branch_bp = {"domain_invariants": []}  # removed
+    claims = [{"kind": "behavior", "statement": "DunningJob calls stripe directly",
+               "evidence_files": ["jobs/dunning.py"]}]
+    items = ir.build_changed_items(base_bp, branch_bp, [], [], claims)
+    inv = [i for i in items if i["section"] == "domain_invariants"]
+    assert inv and inv[0]["diff_op"] == "REMOVE" and inv[0]["layer"] == 1
+    assert inv[0]["enforced_at_files"] == ["db/payments.py"]
+    desc = [i for i in items if i["source"] == "ledger"]
+    assert desc and desc[0]["layer"] == 2 and desc[0]["diff_op"] == "DECLARED"
+    # every item has a unique ref
+    refs = [i["ref"] for i in items]
+    assert len(refs) == len(set(refs))
+
+
+def test_build_changed_items_rule_remove_and_add():
+    base_rules = [{"id": "R1", "description": "no direct stripe"}]
+    branch_rules = [{"id": "R2", "description": "cap retries at 3"}]
+    items = ir.build_changed_items({}, {}, base_rules, branch_rules, [])
+    ops = {i["title"]: i["diff_op"] for i in items if i["source"] == "rules"}
+    assert ops["R1"] == "REMOVE"
+    assert ops["R2"] == "ADD"
+
+
+# ---------------------------------------------------------------------------
+# ledger_join
+# ---------------------------------------------------------------------------
+def test_ledger_join_matches_on_file_and_keyword():
+    item = {"enforced_at_files": ["db/payments.py"], "keywords": ["tenant", "writes"]}
+    claims = [{"statement": "tenant writes now unscoped", "evidence_files": ["db/payments.py"],
+               "confidence": "low", "reconstructed": True}]
+    join = ir.ledger_join(item, claims)
+    assert join and join["confidence"] == "low" and join["reconstructed"] is True
+
+
+def test_ledger_join_no_match_returns_none():
+    item = {"enforced_at_files": ["db/payments.py"], "keywords": ["tenant"]}
+    # file matches but no keyword overlap
+    assert ir.ledger_join(item, [{"statement": "unrelated change",
+                                  "evidence_files": ["db/payments.py"],
+                                  "confidence": "high"}]) is None
+    # keyword matches but no file overlap
+    assert ir.ledger_join(item, [{"statement": "tenant logic",
+                                  "evidence_files": ["other/file.py"],
+                                  "confidence": "high"}]) is None
+
+
+# ---------------------------------------------------------------------------
+# finalize_findings
+# ---------------------------------------------------------------------------
+def _items():
+    return [
+        {"ref": "c0", "diff_op": "REMOVE", "layer": 1, "section": "domain_invariants",
+         "title": "Tenant isolation", "enforced_at_files": ["db/p.py"], "keywords": ["tenant"]},
+        {"ref": "c1", "diff_op": "ADD", "layer": 1, "section": "rules",
+         "title": "R2", "enforced_at_files": [], "keywords": ["retry"]},
+    ]
+
+
+def test_finalize_overwrites_and_suppresses():
+    model = [
+        # valid finding, but model lies about diff_op -> script overwrites
+        {"item_ref": "c0", "type": "silent_weakening", "rule_name": "wrong",
+         "what_changed": "removed", "because": "rule text says X", "diff_op": "ADD"},
+        # because blank -> dropped
+        {"item_ref": "c1", "type": "contradiction", "rule_name": "R2",
+         "what_changed": "", "because": "   "},
+        # ref doesn't exist -> dropped
+        {"item_ref": "zzz", "type": "contradiction", "rule_name": "ghost",
+         "what_changed": "x", "because": "y"},
+    ]
+    out = ir.finalize_findings(model, _items(), [])
+    assert len(out) == 1
+    f = out[0]
+    assert f["diff_op"] == "REMOVE"          # overwritten from the item, not the model's "ADD"
+    assert f["rule_name"] == "Tenant isolation"  # script-owned title, not model's "wrong"
+    assert f["layer"] == 1
+    assert f["because"] == "rule text says X"
+
+
+def test_finalize_attaches_ledger_confidence():
+    items = _items()
+    claims = [{"statement": "tenant scoping dropped", "evidence_files": ["db/p.py"],
+               "confidence": "low", "reconstructed": True}]
+    model = [{"item_ref": "c0", "type": "silent_weakening", "rule_name": "x",
+              "what_changed": "removed", "because": "cited"}]
+    out = ir.finalize_findings(model, items, claims)
+    assert out[0]["confidence"] == "low" and out[0]["reconstructed"] is True
+
+
+# ---------------------------------------------------------------------------
+# render_comment
+# ---------------------------------------------------------------------------
+def test_render_comment_no_diff_returns_none():
+    assert ir.render_comment([], had_diff=False) is None
+
+
+def test_render_comment_no_findings_is_consistent_message():
+    body = ir.render_comment([], had_diff=True)
+    assert ir.COMMENT_MARKER in body
+    assert "consistent" in body.lower()
+
+
+def test_render_comment_groups_and_cites():
+    findings = [
+        {"type": "silent_weakening", "diff_op": "REMOVE", "layer": 1,
+         "rule_name": "Tenant isolation", "what_changed": "removed scoping",
+         "because": "invariant text required tenant_id", "confidence": "low",
+         "reconstructed": True},
+        {"type": "behavior_violates_rule", "diff_op": "DECLARED", "layer": 2,
+         "rule_name": "Centralized payments", "what_changed": "calls stripe directly",
+         "because": "R2 forbids direct stripe", "confidence": None},
+    ]
+    body = ir.render_comment(findings, had_diff=True)
+    assert ir.COMMENT_MARKER in body
+    assert "Silent weakening" in body and "Behavior may violate" in body
+    assert "Because:" in body
+    assert "ledger confidence: low" in body
+    assert "reconstructed guess" in body
+    assert "doesn't block" in body
+
+
+# ---------------------------------------------------------------------------
+# model + github calls (monkeypatched urllib)
+# ---------------------------------------------------------------------------
+def test_extract_findings_from_tool_use():
+    resp = {"content": [
+        {"type": "text", "text": "ignore"},
+        {"type": "tool_use", "name": "emit_findings",
+         "input": {"findings": [{"item_ref": "c0", "type": "contradiction"}]}},
+    ]}
+    out = ir._extract_findings(resp)
+    assert out == [{"item_ref": "c0", "type": "contradiction"}]
+    assert ir._extract_findings({"content": []}) == []
+
+
+def test_call_anthropic_parses_tool_use(monkeypatch):
+    class FakeResp:
+        def __init__(self, payload):
+            self._b = json.dumps(payload).encode()
+        def read(self):
+            return self._b
+        def __enter__(self):
+            return self
+        def __exit__(self, *a):
+            return False
+
+    captured = {}
+
+    def fake_urlopen(req, timeout=0):
+        captured["url"] = req.full_url
+        captured["headers"] = {k.lower(): v for k, v in req.headers.items()}
+        return FakeResp({"content": [
+            {"type": "tool_use", "name": "emit_findings",
+             "input": {"findings": [{"item_ref": "c0", "type": "silent_weakening",
+                                     "rule_name": "x", "what_changed": "y", "because": "z"}]}}]})
+
+    monkeypatch.setattr(ir.urllib.request, "urlopen", fake_urlopen)
+    out = ir.call_anthropic("sys", "user", "sk-test")
+    assert out[0]["item_ref"] == "c0"
+    assert captured["url"] == ir.ANTHROPIC_URL
+    assert captured["headers"]["x-api-key"] == "sk-test"
+    assert captured["headers"]["anthropic-version"] == ir.ANTHROPIC_VERSION
+
+
+def test_post_or_update_comment_creates_then_updates(monkeypatch):
+    calls = []
+
+    def fake_gh(method, url, token, body=None):
+        calls.append((method, url, body))
+        if method == "GET":
+            # first call: no existing comment; second call: existing with marker
+            if len([c for c in calls if c[0] == "POST"]) == 0:
+                return []
+            return [{"id": 99, "body": ir.COMMENT_MARKER + "\nold"}]
+        return {}
+
+    monkeypatch.setattr(ir, "_gh_request", fake_gh)
+
+    ir.post_or_update_comment("o", "r", 1, ir.COMMENT_MARKER + "\nnew", "tok")
+    assert calls[-1][0] == "POST"  # created
+
+    ir.post_or_update_comment("o", "r", 1, ir.COMMENT_MARKER + "\nnewer", "tok")
+    assert calls[-1][0] == "PATCH"  # updated existing id 99
+    assert "/comments/99" in calls[-1][1]

From 659a2980d4265740fc4d98f8124143f2ddc85eb8 Mon Sep 17 00:00:00 2001
From: Gabor Bakos <gabor@bitraptors.com>
Date: Fri, 19 Jun 2026 19:35:18 +0200
Subject: [PATCH 04/15] =?UTF-8?q?fix(intent-review):=20address=20adversari?=
 =?UTF-8?q?al=20review=20=E2=80=94=20blockers,=20robustness,=20coverage?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

From a 6-agent adversarial verification pass:

Blockers:
- never-block guarantee: route both comment posts through safe_post_comment()
  which swallows URLError (covers HTTPError) + OSError — a network hiccup no
  longer fails the Action.
- data-section diff: removed a dead `pass` that let pure-ADD data models through
  unintentionally; the script now surfaces every data change and the model judges.

Coverage / faithfulness (plan-required sections):
- diff platform_rules.json too (unioned with rules.json).
- diff pitfalls (id), decisions.trade_offs + out_of_scope (title-hash).
- unenforced_invariants deliberately excluded (advisory gaps) — documented.
- item_key falls back to a full-item hash so title-less items don't collide.
- comment lookup follows Link-header pagination (no dup comment past 100).
- workflow: continue-on-error on the base-ref fetch.

Distribution:
- npx installer now places setup-archie-intent-review.sh and workflows/ into
  .archie/, so `bash .archie/setup-archie-intent-review.sh` works post-install
  and resolve_workflow_src() finds the canonical YAML.

Tests: +18 (43 total) — new sections, pagination, URLError-swallow, retry/backoff,
flag order, path-overlap, item_key fallback, and a full main() integration via a
real origin clone. Full suite 1021 passed / 1 skipped; verify_sync green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../assets/workflows/archie-intent-review.yml |   1 +
 archie/standalone/intent_review.py            | 128 +++++++----
 npm-package/assets/intent_review.py           | 128 +++++++----
 .../assets/workflows/archie-intent-review.yml |   1 +
 npm-package/bin/archie.mjs                    |  12 +
 tests/test_intent_review.py                   | 217 +++++++++++++++++-
 6 files changed, 405 insertions(+), 82 deletions(-)

diff --git a/archie/assets/workflows/archie-intent-review.yml b/archie/assets/workflows/archie-intent-review.yml
index 918b4e2..ae845e3 100644
--- a/archie/assets/workflows/archie-intent-review.yml
+++ b/archie/assets/workflows/archie-intent-review.yml
@@ -20,6 +20,7 @@ jobs:
           python-version: '3.11'
 
       - name: Fetch base ref
+        continue-on-error: true
         run: git fetch --no-tags --depth=1 origin "${{ github.base_ref }}"
 
       - name: Run Archie Intent Review
diff --git a/archie/standalone/intent_review.py b/archie/standalone/intent_review.py
index 628667f..2be0398 100644
--- a/archie/standalone/intent_review.py
+++ b/archie/standalone/intent_review.py
@@ -51,8 +51,14 @@
     # (top_key, sub_key_or_None, id_field, title_field)
     ("domain_invariants", None, "id", "invariant"),
     ("derived_invariants", None, "id", "invariant"),
+    ("pitfalls", None, "id", "problem_statement"),
 ]
-# decisions.key_decisions has no id -> title-hash keyed.
+# `unenforced_invariants` are DELIBERATELY not diffed: they are documented GAPS
+# (advisory, ungrounded), not standing law, so removing one is not a "weakening".
+# (Design open question — see docs/archie-intent-review-design.md §13.)
+
+# decisions.* sub-sections have no id -> title-hash keyed (Layer 1).
+DECISION_SECTIONS = ["key_decisions", "trade_offs", "out_of_scope"]
 DECISION_TITLE_FIELD = "title"
 
 # Data sections we diff for Layer-2 behavior-violates-rule (keyed by name).
@@ -61,6 +67,9 @@
     ("persistence_stores", "name"),
 ]
 
+# Rule sources diffed for contradiction / rule-removal (both keyed by id).
+RULE_FILES = [".archie/rules.json", ".archie/platform_rules.json"]
+
 RELEVANCE_SEND_ALL_THRESHOLD = 25   # if retained rules are few, skip the keyword filter
 KEYWORD_JOIN_THRESHOLD = 1          # >=1 shared keyword token to attach ledger confidence
 
@@ -148,7 +157,10 @@ def _hash_title(title: str) -> str:
 
 
 def item_key(item: dict, id_field: str, title_field: str) -> str:
-    """Stable key for an item: its id if present, else a hash of its title."""
+    """Stable key for an item: its id if present, else a hash of its title, else a
+    hash of the whole item — so title-less items (e.g. some trade_offs) do NOT all
+    collide on the empty-string key.
+    """
     if id_field and isinstance(item, dict):
         val = item.get(id_field)
         if val:
@@ -156,7 +168,13 @@ def item_key(item: dict, id_field: str, title_field: str) -> str:
     title = ""
     if isinstance(item, dict):
         title = str(item.get(title_field, "") or "")
-    return _hash_title(title)
+    if title.strip():
+        return _hash_title(title)
+    try:
+        blob = json.dumps(item, sort_keys=True, ensure_ascii=False)
+        return "item_" + hashlib.md5(blob.encode("utf-8")).hexdigest()[:8]
+    except (TypeError, ValueError):
+        return _hash_title(title)
 
 
 def _changed_fields(base_item: dict, branch_item: dict) -> list:
@@ -261,16 +279,17 @@ def add(source, section, diff_op, layer, title, base_item, branch_item,
                 d["base_item"], d["branch_item"], d["fields_changed"],
                 _keywords_of(ref_item), _enforced_files(ref_item))
 
-    # Layer 1 — decisions.key_decisions (title-hash keyed, silent weakening)
-    dec_diffs = keyed_diff(_get_section(base_bp, "decisions", "key_decisions"),
-                           _get_section(branch_bp, "decisions", "key_decisions"),
-                           None, DECISION_TITLE_FIELD)
-    for d in dec_diffs:
-        ref_item = d["branch_item"] or d["base_item"] or {}
-        add("blueprint", "decisions.key_decisions", d["status"], 1,
-            _title_of(ref_item, DECISION_TITLE_FIELD),
-            d["base_item"], d["branch_item"], d["fields_changed"],
-            _keywords_of(ref_item), [])
+    # Layer 1 — decisions.{key_decisions,trade_offs,out_of_scope} (title-hash keyed)
+    for sub in DECISION_SECTIONS:
+        dec_diffs = keyed_diff(_get_section(base_bp, "decisions", sub),
+                               _get_section(branch_bp, "decisions", sub),
+                               None, DECISION_TITLE_FIELD)
+        for d in dec_diffs:
+            ref_item = d["branch_item"] or d["base_item"] or {}
+            add("blueprint", f"decisions.{sub}", d["status"], 1,
+                _title_of(ref_item, DECISION_TITLE_FIELD),
+                d["base_item"], d["branch_item"], d["fields_changed"],
+                _keywords_of(ref_item), [])
 
     # Layer 1 — rules (contradiction candidates): ADD/UPDATE only
     rule_diffs = keyed_diff(base_rules, branch_rules, "id", "description")
@@ -293,8 +312,9 @@ def add(source, section, diff_op, layer, title, base_item, branch_item,
                            _get_section(branch_bp, top_key, None),
                            name_field, name_field)
         for d in diffs:
-            if d["status"] == "ADD" and not d["fields_changed"]:
-                pass  # pure additions of data models rarely violate a rule on their own
+            # Surface every data-section change (incl. pure ADDs). The script owns
+            # WHAT changed; the model decides whether a new/changed model violates a
+            # retained rule (it's told not to flag benign additions).
             ref_item = d["branch_item"] or d["base_item"] or {}
             add("blueprint", top_key, d["status"], 2,
                 _title_of(ref_item, name_field),
@@ -674,6 +694,10 @@ def render_comment(findings: list, had_diff: bool):
 
 
 def _gh_request(method: str, url: str, token: str, body: dict = None):
+    """One GitHub REST call. urllib raises HTTPError on >=400, so non-2xx is NOT a
+    silent success. Returns (data, link_header). Raises on transport/HTTP errors —
+    callers that must never block use safe_post_comment().
+    """
     data = json.dumps(body).encode("utf-8") if body is not None else None
     req = urllib.request.Request(url, data=data, method=method, headers={
         "Authorization": f"Bearer {token}",
@@ -684,22 +708,37 @@ def _gh_request(method: str, url: str, token: str, body: dict = None):
     })
     with urllib.request.urlopen(req, timeout=30) as resp:
         raw = resp.read().decode("utf-8")
-        return json.loads(raw) if raw.strip() else {}
+        link = resp.headers.get("Link", "") if resp.headers else ""
+    return (json.loads(raw) if raw.strip() else {}), link
 
 
-def post_or_update_comment(owner, repo, pr_number, body, token):
-    """Upsert the single Archie comment (find by marker -> PATCH, else POST)."""
-    list_url = f"{GITHUB_API}/repos/{owner}/{repo}/issues/{pr_number}/comments?per_page=100"
-    existing_id = None
-    try:
-        comments = _gh_request("GET", list_url, token)
+def _next_link(link_header: str):
+    """Parse a GitHub `Link` header for the rel="next" URL, or None."""
+    for part in (link_header or "").split(","):
+        segs = part.split(";")
+        if len(segs) >= 2 and 'rel="next"' in segs[1]:
+            return segs[0].strip().strip("<>")
+    return None
+
+
+def _find_existing_comment_id(owner, repo, pr_number, token):
+    """Find the Archie comment by marker, following pagination (PRs with >100
+    comments won't cause a duplicate POST).
+    """
+    url = f"{GITHUB_API}/repos/{owner}/{repo}/issues/{pr_number}/comments?per_page=100"
+    while url:
+        comments, link = _gh_request("GET", url, token)
         for c in comments if isinstance(comments, list) else []:
             if COMMENT_MARKER in (c.get("body") or ""):
-                existing_id = c.get("id")
-                break
-    except urllib.error.HTTPError as e:  # pragma: no cover - network
-        print(f"[intent-review] could not list comments: HTTP {e.code}", file=sys.stderr)
+                return c.get("id")
+        url = _next_link(link)
+    return None
+
 
+def post_or_update_comment(owner, repo, pr_number, body, token):
+    """Upsert the single Archie comment (find by marker -> PATCH, else POST). May raise
+    (HTTPError/URLError); callers in CI must use safe_post_comment()."""
+    existing_id = _find_existing_comment_id(owner, repo, pr_number, token)
     if existing_id:
         url = f"{GITHUB_API}/repos/{owner}/{repo}/issues/comments/{existing_id}"
         _gh_request("PATCH", url, token, {"body": body})
@@ -710,6 +749,18 @@ def post_or_update_comment(owner, repo, pr_number, body, token):
         print("[intent-review] posted new comment")
 
 
+def safe_post_comment(owner, repo, pr_number, body, token):
+    """Post but NEVER raise — the Action must always exit 0 (design §9). Catches every
+    network/HTTP error (URLError covers HTTPError; OSError covers socket failures)."""
+    if not token:
+        print("[intent-review] no GITHUB_TOKEN — skipping comment post.", file=sys.stderr)
+        return
+    try:
+        post_or_update_comment(owner, repo, pr_number, body, token)
+    except (urllib.error.URLError, OSError, ValueError) as e:
+        print(f"[intent-review] could not post comment: {e}", file=sys.stderr)
+
+
 # ---------------------------------------------------------------------------
 # event context
 # ---------------------------------------------------------------------------
@@ -761,11 +812,10 @@ def main(argv=None) -> int:
     b_exists, branch_bp, b_err = load_branch_file(repo_root, ".archie/blueprint.json")
     if b_exists and branch_bp is None:
         # branch blueprint is malformed — surface, don't crash.
-        if token:
-            post_or_update_comment(owner, repo, pr_number,
-                                   f"{COMMENT_MARKER}\n## 📐 Archie Intent Review\n\n"
-                                   f"Could not parse `.archie/blueprint.json` on this branch "
-                                   f"({b_err}). Manual review needed.", token)
+        safe_post_comment(owner, repo, pr_number,
+                          f"{COMMENT_MARKER}\n## 📐 Archie Intent Review\n\n"
+                          f"Could not parse `.archie/blueprint.json` on this branch "
+                          f"({b_err}). Manual review needed.", token)
         return 0
     if not b_exists:
         print("[intent-review] no .archie/blueprint.json on branch — nothing to review.", file=sys.stderr)
@@ -774,10 +824,13 @@ def main(argv=None) -> int:
     _, base_bp, _ = fetch_base_file(repo_root, base_ref_full, ".archie/blueprint.json")
     base_bp = base_bp if isinstance(base_bp, dict) else {}
 
-    _, base_rules_raw, _ = fetch_base_file(repo_root, base_ref_full, ".archie/rules.json")
-    _, branch_rules_raw, _ = load_branch_file(repo_root, ".archie/rules.json")
-    base_rules = normalize_rules(base_rules_raw)
-    branch_rules = normalize_rules(branch_rules_raw)
+    # Diff BOTH rule sources (rules.json + platform_rules.json), unioned.
+    base_rules, branch_rules = [], []
+    for rel in RULE_FILES:
+        _, base_raw, _ = fetch_base_file(repo_root, base_ref_full, rel)
+        _, branch_raw, _ = load_branch_file(repo_root, rel)
+        base_rules.extend(normalize_rules(base_raw))
+        branch_rules.extend(normalize_rules(branch_raw))
 
     claims = glob_ledger(repo_root, base_ref_full)
 
@@ -805,10 +858,7 @@ def main(argv=None) -> int:
     if not token:
         print("[intent-review] no GITHUB_TOKEN — printing body:\n" + body)
         return 0
-    try:
-        post_or_update_comment(owner, repo, pr_number, body, token)
-    except urllib.error.HTTPError as e:  # pragma: no cover - network
-        print(f"[intent-review] could not post comment: HTTP {e.code}", file=sys.stderr)
+    safe_post_comment(owner, repo, pr_number, body, token)
     return 0
 
 
diff --git a/npm-package/assets/intent_review.py b/npm-package/assets/intent_review.py
index 628667f..2be0398 100644
--- a/npm-package/assets/intent_review.py
+++ b/npm-package/assets/intent_review.py
@@ -51,8 +51,14 @@
     # (top_key, sub_key_or_None, id_field, title_field)
     ("domain_invariants", None, "id", "invariant"),
     ("derived_invariants", None, "id", "invariant"),
+    ("pitfalls", None, "id", "problem_statement"),
 ]
-# decisions.key_decisions has no id -> title-hash keyed.
+# `unenforced_invariants` are DELIBERATELY not diffed: they are documented GAPS
+# (advisory, ungrounded), not standing law, so removing one is not a "weakening".
+# (Design open question — see docs/archie-intent-review-design.md §13.)
+
+# decisions.* sub-sections have no id -> title-hash keyed (Layer 1).
+DECISION_SECTIONS = ["key_decisions", "trade_offs", "out_of_scope"]
 DECISION_TITLE_FIELD = "title"
 
 # Data sections we diff for Layer-2 behavior-violates-rule (keyed by name).
@@ -61,6 +67,9 @@
     ("persistence_stores", "name"),
 ]
 
+# Rule sources diffed for contradiction / rule-removal (both keyed by id).
+RULE_FILES = [".archie/rules.json", ".archie/platform_rules.json"]
+
 RELEVANCE_SEND_ALL_THRESHOLD = 25   # if retained rules are few, skip the keyword filter
 KEYWORD_JOIN_THRESHOLD = 1          # >=1 shared keyword token to attach ledger confidence
 
@@ -148,7 +157,10 @@ def _hash_title(title: str) -> str:
 
 
 def item_key(item: dict, id_field: str, title_field: str) -> str:
-    """Stable key for an item: its id if present, else a hash of its title."""
+    """Stable key for an item: its id if present, else a hash of its title, else a
+    hash of the whole item — so title-less items (e.g. some trade_offs) do NOT all
+    collide on the empty-string key.
+    """
     if id_field and isinstance(item, dict):
         val = item.get(id_field)
         if val:
@@ -156,7 +168,13 @@ def item_key(item: dict, id_field: str, title_field: str) -> str:
     title = ""
     if isinstance(item, dict):
         title = str(item.get(title_field, "") or "")
-    return _hash_title(title)
+    if title.strip():
+        return _hash_title(title)
+    try:
+        blob = json.dumps(item, sort_keys=True, ensure_ascii=False)
+        return "item_" + hashlib.md5(blob.encode("utf-8")).hexdigest()[:8]
+    except (TypeError, ValueError):
+        return _hash_title(title)
 
 
 def _changed_fields(base_item: dict, branch_item: dict) -> list:
@@ -261,16 +279,17 @@ def add(source, section, diff_op, layer, title, base_item, branch_item,
                 d["base_item"], d["branch_item"], d["fields_changed"],
                 _keywords_of(ref_item), _enforced_files(ref_item))
 
-    # Layer 1 — decisions.key_decisions (title-hash keyed, silent weakening)
-    dec_diffs = keyed_diff(_get_section(base_bp, "decisions", "key_decisions"),
-                           _get_section(branch_bp, "decisions", "key_decisions"),
-                           None, DECISION_TITLE_FIELD)
-    for d in dec_diffs:
-        ref_item = d["branch_item"] or d["base_item"] or {}
-        add("blueprint", "decisions.key_decisions", d["status"], 1,
-            _title_of(ref_item, DECISION_TITLE_FIELD),
-            d["base_item"], d["branch_item"], d["fields_changed"],
-            _keywords_of(ref_item), [])
+    # Layer 1 — decisions.{key_decisions,trade_offs,out_of_scope} (title-hash keyed)
+    for sub in DECISION_SECTIONS:
+        dec_diffs = keyed_diff(_get_section(base_bp, "decisions", sub),
+                               _get_section(branch_bp, "decisions", sub),
+                               None, DECISION_TITLE_FIELD)
+        for d in dec_diffs:
+            ref_item = d["branch_item"] or d["base_item"] or {}
+            add("blueprint", f"decisions.{sub}", d["status"], 1,
+                _title_of(ref_item, DECISION_TITLE_FIELD),
+                d["base_item"], d["branch_item"], d["fields_changed"],
+                _keywords_of(ref_item), [])
 
     # Layer 1 — rules (contradiction candidates): ADD/UPDATE only
     rule_diffs = keyed_diff(base_rules, branch_rules, "id", "description")
@@ -293,8 +312,9 @@ def add(source, section, diff_op, layer, title, base_item, branch_item,
                            _get_section(branch_bp, top_key, None),
                            name_field, name_field)
         for d in diffs:
-            if d["status"] == "ADD" and not d["fields_changed"]:
-                pass  # pure additions of data models rarely violate a rule on their own
+            # Surface every data-section change (incl. pure ADDs). The script owns
+            # WHAT changed; the model decides whether a new/changed model violates a
+            # retained rule (it's told not to flag benign additions).
             ref_item = d["branch_item"] or d["base_item"] or {}
             add("blueprint", top_key, d["status"], 2,
                 _title_of(ref_item, name_field),
@@ -674,6 +694,10 @@ def render_comment(findings: list, had_diff: bool):
 
 
 def _gh_request(method: str, url: str, token: str, body: dict = None):
+    """One GitHub REST call. urllib raises HTTPError on >=400, so non-2xx is NOT a
+    silent success. Returns (data, link_header). Raises on transport/HTTP errors —
+    callers that must never block use safe_post_comment().
+    """
     data = json.dumps(body).encode("utf-8") if body is not None else None
     req = urllib.request.Request(url, data=data, method=method, headers={
         "Authorization": f"Bearer {token}",
@@ -684,22 +708,37 @@ def _gh_request(method: str, url: str, token: str, body: dict = None):
     })
     with urllib.request.urlopen(req, timeout=30) as resp:
         raw = resp.read().decode("utf-8")
-        return json.loads(raw) if raw.strip() else {}
+        link = resp.headers.get("Link", "") if resp.headers else ""
+    return (json.loads(raw) if raw.strip() else {}), link
 
 
-def post_or_update_comment(owner, repo, pr_number, body, token):
-    """Upsert the single Archie comment (find by marker -> PATCH, else POST)."""
-    list_url = f"{GITHUB_API}/repos/{owner}/{repo}/issues/{pr_number}/comments?per_page=100"
-    existing_id = None
-    try:
-        comments = _gh_request("GET", list_url, token)
+def _next_link(link_header: str):
+    """Parse a GitHub `Link` header for the rel="next" URL, or None."""
+    for part in (link_header or "").split(","):
+        segs = part.split(";")
+        if len(segs) >= 2 and 'rel="next"' in segs[1]:
+            return segs[0].strip().strip("<>")
+    return None
+
+
+def _find_existing_comment_id(owner, repo, pr_number, token):
+    """Find the Archie comment by marker, following pagination (PRs with >100
+    comments won't cause a duplicate POST).
+    """
+    url = f"{GITHUB_API}/repos/{owner}/{repo}/issues/{pr_number}/comments?per_page=100"
+    while url:
+        comments, link = _gh_request("GET", url, token)
         for c in comments if isinstance(comments, list) else []:
             if COMMENT_MARKER in (c.get("body") or ""):
-                existing_id = c.get("id")
-                break
-    except urllib.error.HTTPError as e:  # pragma: no cover - network
-        print(f"[intent-review] could not list comments: HTTP {e.code}", file=sys.stderr)
+                return c.get("id")
+        url = _next_link(link)
+    return None
+
 
+def post_or_update_comment(owner, repo, pr_number, body, token):
+    """Upsert the single Archie comment (find by marker -> PATCH, else POST). May raise
+    (HTTPError/URLError); callers in CI must use safe_post_comment()."""
+    existing_id = _find_existing_comment_id(owner, repo, pr_number, token)
     if existing_id:
         url = f"{GITHUB_API}/repos/{owner}/{repo}/issues/comments/{existing_id}"
         _gh_request("PATCH", url, token, {"body": body})
@@ -710,6 +749,18 @@ def post_or_update_comment(owner, repo, pr_number, body, token):
         print("[intent-review] posted new comment")
 
 
+def safe_post_comment(owner, repo, pr_number, body, token):
+    """Post but NEVER raise — the Action must always exit 0 (design §9). Catches every
+    network/HTTP error (URLError covers HTTPError; OSError covers socket failures)."""
+    if not token:
+        print("[intent-review] no GITHUB_TOKEN — skipping comment post.", file=sys.stderr)
+        return
+    try:
+        post_or_update_comment(owner, repo, pr_number, body, token)
+    except (urllib.error.URLError, OSError, ValueError) as e:
+        print(f"[intent-review] could not post comment: {e}", file=sys.stderr)
+
+
 # ---------------------------------------------------------------------------
 # event context
 # ---------------------------------------------------------------------------
@@ -761,11 +812,10 @@ def main(argv=None) -> int:
     b_exists, branch_bp, b_err = load_branch_file(repo_root, ".archie/blueprint.json")
     if b_exists and branch_bp is None:
         # branch blueprint is malformed — surface, don't crash.
-        if token:
-            post_or_update_comment(owner, repo, pr_number,
-                                   f"{COMMENT_MARKER}\n## 📐 Archie Intent Review\n\n"
-                                   f"Could not parse `.archie/blueprint.json` on this branch "
-                                   f"({b_err}). Manual review needed.", token)
+        safe_post_comment(owner, repo, pr_number,
+                          f"{COMMENT_MARKER}\n## 📐 Archie Intent Review\n\n"
+                          f"Could not parse `.archie/blueprint.json` on this branch "
+                          f"({b_err}). Manual review needed.", token)
         return 0
     if not b_exists:
         print("[intent-review] no .archie/blueprint.json on branch — nothing to review.", file=sys.stderr)
@@ -774,10 +824,13 @@ def main(argv=None) -> int:
     _, base_bp, _ = fetch_base_file(repo_root, base_ref_full, ".archie/blueprint.json")
     base_bp = base_bp if isinstance(base_bp, dict) else {}
 
-    _, base_rules_raw, _ = fetch_base_file(repo_root, base_ref_full, ".archie/rules.json")
-    _, branch_rules_raw, _ = load_branch_file(repo_root, ".archie/rules.json")
-    base_rules = normalize_rules(base_rules_raw)
-    branch_rules = normalize_rules(branch_rules_raw)
+    # Diff BOTH rule sources (rules.json + platform_rules.json), unioned.
+    base_rules, branch_rules = [], []
+    for rel in RULE_FILES:
+        _, base_raw, _ = fetch_base_file(repo_root, base_ref_full, rel)
+        _, branch_raw, _ = load_branch_file(repo_root, rel)
+        base_rules.extend(normalize_rules(base_raw))
+        branch_rules.extend(normalize_rules(branch_raw))
 
     claims = glob_ledger(repo_root, base_ref_full)
 
@@ -805,10 +858,7 @@ def main(argv=None) -> int:
     if not token:
         print("[intent-review] no GITHUB_TOKEN — printing body:\n" + body)
         return 0
-    try:
-        post_or_update_comment(owner, repo, pr_number, body, token)
-    except urllib.error.HTTPError as e:  # pragma: no cover - network
-        print(f"[intent-review] could not post comment: HTTP {e.code}", file=sys.stderr)
+    safe_post_comment(owner, repo, pr_number, body, token)
     return 0
 
 
diff --git a/npm-package/assets/workflows/archie-intent-review.yml b/npm-package/assets/workflows/archie-intent-review.yml
index 918b4e2..ae845e3 100644
--- a/npm-package/assets/workflows/archie-intent-review.yml
+++ b/npm-package/assets/workflows/archie-intent-review.yml
@@ -20,6 +20,7 @@ jobs:
           python-version: '3.11'
 
       - name: Fetch base ref
+        continue-on-error: true
         run: git fetch --no-tags --depth=1 origin "${{ github.base_ref }}"
 
       - name: Run Archie Intent Review
diff --git a/npm-package/bin/archie.mjs b/npm-package/bin/archie.mjs
index 3319fd8..19a46f1 100755
--- a/npm-package/bin/archie.mjs
+++ b/npm-package/bin/archie.mjs
@@ -375,11 +375,23 @@ for (const dataFile of ["platform_rules.json", "platform_pitfalls.json"]) {
   }
 }
 
+// One-time CI setup helper — runnable as `bash .archie/setup-archie-intent-review.sh`.
+for (const helper of ["setup-archie-intent-review.sh"]) {
+  const src = join(ASSETS, helper);
+  const dest = join(archieDir, helper);
+  if (existsSync(src)) {
+    writeFileSync(dest, readFileSync(src, "utf8"));
+    chmodSync(dest, 0o755);
+    console.log(`  ${GREEN}✓${RESET} .archie/${helper}`);
+  }
+}
+
 // The canonical workflow templates (assets/workflow/) are NOT copied raw —
 // the Python install loop renders them per-CLI into .archie/workflow/<cli>/.
 const ASSET_SUBDIR_MAP = [
   ["hook_scripts", "hooks"],
   ["_install_pkg", "_install_pkg"],
+  ["workflows", "workflows"],   // CI workflow YAMLs (e.g. archie-intent-review.yml)
 ];
 for (const [srcName, destName] of ASSET_SUBDIR_MAP) {
   const src = join(ASSETS, srcName);
diff --git a/tests/test_intent_review.py b/tests/test_intent_review.py
index 5333ca9..bfb99a0 100644
--- a/tests/test_intent_review.py
+++ b/tests/test_intent_review.py
@@ -386,11 +386,12 @@ def test_post_or_update_comment_creates_then_updates(monkeypatch):
     def fake_gh(method, url, token, body=None):
         calls.append((method, url, body))
         if method == "GET":
-            # first call: no existing comment; second call: existing with marker
+            # first GET: no existing comment; later GET: existing with marker.
+            # _gh_request now returns (data, link_header).
             if len([c for c in calls if c[0] == "POST"]) == 0:
-                return []
-            return [{"id": 99, "body": ir.COMMENT_MARKER + "\nold"}]
-        return {}
+                return [], None
+            return [{"id": 99, "body": ir.COMMENT_MARKER + "\nold"}], None
+        return {}, None
 
     monkeypatch.setattr(ir, "_gh_request", fake_gh)
 
@@ -400,3 +401,211 @@ def fake_gh(method, url, token, body=None):
     ir.post_or_update_comment("o", "r", 1, ir.COMMENT_MARKER + "\nnewer", "tok")
     assert calls[-1][0] == "PATCH"  # updated existing id 99
     assert "/comments/99" in calls[-1][1]
+
+
+def test_next_link_parses_pagination():
+    hdr = '<https://api.github.com/x?page=2>; rel="next", <https://api.github.com/x?page=5>; rel="last"'
+    assert ir._next_link(hdr) == "https://api.github.com/x?page=2"
+    assert ir._next_link("") is None
+
+
+def test_find_existing_comment_follows_pagination(monkeypatch):
+    # marker only on page 2 -> must follow the Link header, not duplicate-POST
+    pages = {
+        "url1": ([{"id": 1, "body": "noise"}], "<url2>; rel=\"next\""),
+        "url2": ([{"id": 2, "body": ir.COMMENT_MARKER}], None),
+    }
+    seq = ["url1", "url2"]
+
+    def fake_gh(method, url, token, body=None):
+        return pages[seq.pop(0)]
+
+    monkeypatch.setattr(ir, "_gh_request", fake_gh)
+    assert ir._find_existing_comment_id("o", "r", 1, "tok") == 2
+
+
+def test_safe_post_comment_swallows_urlerror(monkeypatch):
+    def boom(*a, **k):
+        raise ir.urllib.error.URLError("network down")
+
+    monkeypatch.setattr(ir, "post_or_update_comment", boom)
+    # must NOT raise (never block)
+    ir.safe_post_comment("o", "r", 1, "body", "tok")
+
+
+def test_safe_post_comment_skips_without_token():
+    # no token -> no attempt, no raise
+    ir.safe_post_comment("o", "r", 1, "body", "")
+
+
+# ---------------------------------------------------------------------------
+# item_key fallback + newly-diffed sections
+# ---------------------------------------------------------------------------
+def test_item_key_fallback_avoids_collision():
+    a = {"note": "x"}   # no id, no title
+    b = {"note": "y"}
+    ka, kb = ir.item_key(a, None, "title"), ir.item_key(b, None, "title")
+    assert ka != kb and ka.startswith("item_")
+
+
+def test_pitfalls_remove_is_layer1():
+    base_bp = {"pitfalls": [{"id": "pf1", "problem_statement": "don't double-migrate"}]}
+    items = ir.build_changed_items(base_bp, {"pitfalls": []}, [], [], [])
+    pf = [i for i in items if i["section"] == "pitfalls"]
+    assert pf and pf[0]["diff_op"] == "REMOVE" and pf[0]["layer"] == 1
+
+
+def test_trade_offs_and_out_of_scope_diffed():
+    base_bp = {"decisions": {
+        "trade_offs": [{"title": "latency for consistency"}],
+        "out_of_scope": [{"title": "no multi-region"}],
+    }}
+    branch_bp = {"decisions": {"trade_offs": [], "out_of_scope": [{"title": "no multi-region"}]}}
+    items = ir.build_changed_items(base_bp, branch_bp, [], [], [])
+    sections = {i["section"]: i["diff_op"] for i in items}
+    assert sections.get("decisions.trade_offs") == "REMOVE"
+    assert "decisions.out_of_scope" not in sections  # unchanged -> no diff
+
+
+def test_unenforced_invariants_not_diffed():
+    base_bp = {"unenforced_invariants": [{"id": "u1", "invariant": "advisory gap"}]}
+    items = ir.build_changed_items(base_bp, {"unenforced_invariants": []}, [], [], [])
+    assert not [i for i in items if i["section"] == "unenforced_invariants"]
+
+
+def test_data_model_pure_add_is_surfaced():
+    # pure ADD of a data model is now surfaced (script owns WHAT changed; model judges)
+    items = ir.build_changed_items({}, {"data_models": [{"name": "Invoice"}]}, [], [], [])
+    dm = [i for i in items if i["section"] == "data_models"]
+    assert dm and dm[0]["diff_op"] == "ADD" and dm[0]["layer"] == 2
+
+
+def test_rule_remove_is_layer1_branch_none():
+    items = ir.build_changed_items({}, {}, [{"id": "R1", "description": "x"}], [], [])
+    r = [i for i in items if i["source"] == "rules"][0]
+    assert r["diff_op"] == "REMOVE" and r["layer"] == 1 and r["branch_item"] is None
+
+
+# ---------------------------------------------------------------------------
+# retained_rules + _path_overlap
+# ---------------------------------------------------------------------------
+def test_retained_rules_under_threshold_returns_all():
+    rules = [{"id": f"R{i}", "description": "d"} for i in range(3)]
+    # none changed -> all retained, count under threshold -> returned as-is
+    assert ir.retained_rules(rules, []) == rules
+
+
+def test_retained_rules_excludes_changed():
+    rules = [{"id": "R1", "description": "a"}, {"id": "R2", "description": "b"}]
+    changed = [{"source": "rules", "title": "R1", "keywords": []}]
+    out = ir.retained_rules(rules, changed)
+    assert [ir._rule_title(r) for r in out] == ["R2"]
+
+
+def test_path_overlap_cases():
+    assert ir._path_overlap({"db/p.py"}, {"db/p.py"}) is True       # exact
+    assert ir._path_overlap({"src/db/p.py"}, {"db/p.py"}) is True   # suffix
+    assert ir._path_overlap({"a/x.py"}, {"b/y.py"}) is False        # disjoint
+
+
+# ---------------------------------------------------------------------------
+# call_anthropic retry
+# ---------------------------------------------------------------------------
+def test_call_anthropic_retries_on_429(monkeypatch):
+    n = {"calls": 0}
+
+    class R:
+        def read(self):
+            return json.dumps({"content": [{"type": "tool_use", "name": "emit_findings",
+                              "input": {"findings": [{"item_ref": "c0"}]}}]}).encode()
+        def __enter__(self):
+            return self
+        def __exit__(self, *a):
+            return False
+
+    def fake_urlopen(req, timeout=0):
+        n["calls"] += 1
+        if n["calls"] < 3:
+            raise ir.urllib.error.HTTPError(ir.ANTHROPIC_URL, 429, "rate", None, None)
+        return R()
+
+    monkeypatch.setattr(ir.urllib.request, "urlopen", fake_urlopen)
+    monkeypatch.setattr(ir.time, "sleep", lambda *a: None)
+    out = ir.call_anthropic("s", "u", "k")
+    assert n["calls"] == 3 and out[0]["item_ref"] == "c0"
+
+
+def test_call_anthropic_raises_on_non_retryable(monkeypatch):
+    def fake_urlopen(req, timeout=0):
+        raise ir.urllib.error.HTTPError(ir.ANTHROPIC_URL, 401, "unauth", None,
+                                        __import__("io").BytesIO(b'{"error":"bad key"}'))
+
+    monkeypatch.setattr(ir.urllib.request, "urlopen", fake_urlopen)
+    monkeypatch.setattr(ir.time, "sleep", lambda *a: None)
+    with pytest.raises(RuntimeError):
+        ir.call_anthropic("s", "u", "k")
+
+
+# ---------------------------------------------------------------------------
+# render flag order
+# ---------------------------------------------------------------------------
+def test_render_comment_preserves_flag_order():
+    findings = [
+        {"type": "behavior_violates_rule", "diff_op": "DECLARED", "layer": 2,
+         "rule_name": "B", "what_changed": "", "because": "b"},
+        {"type": "silent_weakening", "diff_op": "REMOVE", "layer": 1,
+         "rule_name": "A", "what_changed": "", "because": "a"},
+    ]
+    body = ir.render_comment(findings, had_diff=True)
+    assert body.index("Silent weakening") < body.index("Behavior may violate")
+
+
+# ---------------------------------------------------------------------------
+# full main() integration via a real origin clone (the base-ref diff path)
+# ---------------------------------------------------------------------------
+def test_main_flags_removed_invariant_via_origin(tmp_path, monkeypatch):
+    # upstream repo (origin) on main holds the invariant
+    up = tmp_path / "up"
+    up.mkdir()
+    _init_repo(up)
+    _write(up, ".archie/blueprint.json", {"domain_invariants": [
+        {"id": "INV1", "invariant": "tenant writes scoped",
+         "keywords": ["tenant"], "enforced_at": ["db/p.py:1"]}]})
+    _write(up, ".archie/rules.json", {"rules": []})
+    _commit(up, "base")
+
+    # working clone gets origin/main
+    work = tmp_path / "work"
+    subprocess.run(["git", "clone", "-q", str(up), str(work)], check=True)
+    _git(work, "config", "user.email", "t@t.com")
+    _git(work, "config", "user.name", "T")
+    _git(work, "checkout", "-q", "-b", "feature")
+    _write(work, ".archie/blueprint.json", {"domain_invariants": []})  # removed
+    _write(work, ".archie/changes/change_1.json", {"claims": [
+        {"id": "d", "kind": "behavior", "statement": "tenant scoping removed",
+         "evidence_files": ["db/p.py"], "confidence": "low", "reconstructed": True}]})
+    _commit(work, "remove invariant")
+
+    event = work / "event.json"
+    event.write_text(json.dumps({"pull_request": {"number": 5, "base": {"ref": "main"}}}))
+
+    captured = {}
+    monkeypatch.setattr(ir, "call_anthropic", lambda s, u, k, **kw: [
+        {"item_ref": "c0", "type": "silent_weakening", "rule_name": "x",
+         "what_changed": "removed tenant scoping", "because": "base invariant required tenant_id scoping"}])
+    monkeypatch.setattr(ir, "safe_post_comment",
+                        lambda o, r, n, body, t: captured.update(body=body))
+    for k, v in {"GITHUB_WORKSPACE": str(work), "ANTHROPIC_API_KEY": "sk-x",
+                 "GITHUB_REPOSITORY": "o/r", "GITHUB_BASE_REF": "main",
+                 "GITHUB_EVENT_PATH": str(event), "GITHUB_TOKEN": "tok"}.items():
+        monkeypatch.setenv(k, v)
+
+    rc = ir.main()
+    assert rc == 0
+    assert "Silent weakening" in captured["body"]
+    assert "ledger confidence: low" in captured["body"]  # the conservative join attached it
+
+
+def test_main_skips_without_secret(monkeypatch):
+    monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)
+    assert ir.main() == 0  # fork PR / no secret -> never block

From 22b4281cf8bb5361a17f4df0a7f013ab660bc656 Mon Sep 17 00:00:00 2001
From: Gabor Bakos <gabor@bitraptors.com>
Date: Fri, 19 Jun 2026 20:33:25 +0200
Subject: [PATCH 05/15] =?UTF-8?q?fix(intent-review):=20right-thing=20revie?=
 =?UTF-8?q?w=20=E2=80=94=20robust=20base-ref=20+=20components=20coverage?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Validation review (does it deliver the value, not just pass tests) surfaced the
linchpin risk and a coverage gap:

- Base ref: diff against github.event.pull_request.base.sha (always in merge-ref
  history with fetch-depth:0) instead of origin/<base>. Removed the fragile
  `git fetch` + continue-on-error step that could silently degrade the diff to
  "everything is new" and post a confident-but-wrong review.
- fetch_base_file now distinguishes "file genuinely absent at a valid ref"
  (legitimate all-ADD) from "ref unresolvable" — the latter posts a loud
  "review skipped" note rather than a misleading all-new result.
- Coverage: components[] now diffed (keyed, Layer 2) so component removal /
  responsibility changes are caught; communication/descriptive snapshots remain
  deliberately out of POC scope, now documented (not a silent divergence).

Tests: +3 (45 total) incl. unresolvable-ref-is-error, component-remove, and the
main() integration now drives the base-SHA path via a real origin clone. Full
suite 1023 passed / 1 skipped; verify_sync green. Delivery plan §10 records the
amendments. M6 dogfood remains the user's real-repo step.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../assets/workflows/archie-intent-review.yml |  7 +--
 archie/standalone/intent_review.py            | 61 ++++++++++++++-----
 docs/archie-intent-review-delivery-plan.md    | 33 +++++++++-
 npm-package/assets/intent_review.py           | 61 ++++++++++++++-----
 .../assets/workflows/archie-intent-review.yml |  7 +--
 tests/test_intent_review.py                   | 29 +++++++--
 6 files changed, 157 insertions(+), 41 deletions(-)

diff --git a/archie/assets/workflows/archie-intent-review.yml b/archie/assets/workflows/archie-intent-review.yml
index ae845e3..487adca 100644
--- a/archie/assets/workflows/archie-intent-review.yml
+++ b/archie/assets/workflows/archie-intent-review.yml
@@ -19,10 +19,9 @@ jobs:
         with:
           python-version: '3.11'
 
-      - name: Fetch base ref
-        continue-on-error: true
-        run: git fetch --no-tags --depth=1 origin "${{ github.base_ref }}"
-
+      # No `git fetch` needed: with fetch-depth:0 the PR base SHA
+      # (github.event.pull_request.base.sha) is already in history, and the script
+      # diffs against it directly — so there is no origin/<base> resolution to fail.
       - name: Run Archie Intent Review
         env:
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
diff --git a/archie/standalone/intent_review.py b/archie/standalone/intent_review.py
index 2be0398..5d8e0c7 100644
--- a/archie/standalone/intent_review.py
+++ b/archie/standalone/intent_review.py
@@ -61,8 +61,16 @@
 DECISION_SECTIONS = ["key_decisions", "trade_offs", "out_of_scope"]
 DECISION_TITLE_FIELD = "title"
 
-# Data sections we diff for Layer-2 behavior-violates-rule (keyed by name).
+# Structured Layer-2 sections (keyed by name) we diff for behavior-violates-rule.
+# `components` is included so a component REMOVE / responsibility change is caught
+# cleanly (keyed, not noisy textual). NOT covered (deliberate POC scope): the purely
+# descriptive snapshots — communication[], architecture_diagram, technology[],
+# quick_reference[], implementation_guidelines[], data_overview. Those reflect current
+# code (not prescriptive law) and a textual diff of them is the design's lower-precision
+# path; behavior-level violations still surface via DESCRIPTIVE LEDGER CLAIMS. Textual
+# fallback for those sections is a documented future enhancement.
 DATA_SECTIONS = [
+    ("components", "name"),
     ("data_models", "name"),
     ("persistence_stores", "name"),
 ]
@@ -102,18 +110,22 @@ def _parse_json(text: str):
 def fetch_base_file(repo_root: Path, base_ref: str, rel_path: str):
     """Read `rel_path` from the base ref via `git show`.
 
-    Returns (exists: bool, data: dict|list|None, error: str|None).
-    A file absent on the base ref -> (False, None, None): treat everything as ADD.
-    A malformed JSON on the base ref -> (True, None, "<err>").
+    Returns (exists: bool, data: dict|list|None, error: str|None) and CRITICALLY
+    distinguishes two non-zero outcomes:
+      - the file is genuinely ABSENT at a VALID ref (e.g. the first PR to add .archie/)
+        -> (False, None, None): a legitimate all-ADD case.
+      - the REF ITSELF is unresolvable (bad SHA / unknown revision) -> (False, None, err):
+        the DANGEROUS case — the caller must NOT silently degrade to an empty baseline,
+        or it would post a confident but wrong "everything is new" review.
+    Malformed JSON at a valid ref -> (True, None, "<err>").
     """
     code, out, err = run_git(repo_root, "show", f"{base_ref}:{rel_path}")
     if code != 0:
         low = (err or "").lower()
-        if "does not exist" in low or "exists on disk, but not" in low \
-                or "invalid object" in low or "unknown revision" in low \
-                or "path" in low and "does not exist" in low or "fatal" in low:
-            # absent on base ref
+        # File absent at a VALID ref — git says the path doesn't exist *in* the ref.
+        if "does not exist in" in low or "exists on disk, but not in" in low:
             return False, None, None
+        # Ref unresolvable or any other git failure — surface it, do not pretend absent.
         return False, None, err.strip() or "git show failed"
     data, perr = _parse_json(out)
     return True, data, perr
@@ -765,7 +777,12 @@ def safe_post_comment(owner, repo, pr_number, body, token):
 # event context
 # ---------------------------------------------------------------------------
 def parse_event_context(env: dict):
-    """Return (owner, repo, pr_number, base_ref) or None if not a usable PR event."""
+    """Return (owner, repo, pr_number, base_ref, base_sha) or None.
+
+    `base_sha` (pull_request.base.sha) is the robust base to diff against: with
+    `actions/checkout` `fetch-depth: 0` it is always present in the merge-ref history,
+    so no `git fetch` is needed and there is no `origin/<base>` resolution to fail.
+    """
     repo_full = env.get("GITHUB_REPOSITORY", "")
     base_ref = env.get("GITHUB_BASE_REF", "")
     event_path = env.get("GITHUB_EVENT_PATH", "")
@@ -773,18 +790,21 @@ def parse_event_context(env: dict):
         return None
     owner, repo = repo_full.split("/", 1)
     pr_number = None
+    base_sha = ""
     if event_path and Path(event_path).exists():
         try:
             event = json.loads(Path(event_path).read_text())
             pr = event.get("pull_request")
             if isinstance(pr, dict):
                 pr_number = pr.get("number")
-                base_ref = base_ref or (pr.get("base") or {}).get("ref", "")
+                base = pr.get("base") or {}
+                base_ref = base_ref or base.get("ref", "")
+                base_sha = base.get("sha", "") or ""
         except (OSError, json.JSONDecodeError):
             return None
     if pr_number is None or not base_ref:
         return None
-    return owner, repo, pr_number, base_ref
+    return owner, repo, pr_number, base_ref, base_sha
 
 
 # ---------------------------------------------------------------------------
@@ -804,9 +824,11 @@ def main(argv=None) -> int:
     if ctx is None:
         print("[intent-review] not a usable pull_request event — skipping.", file=sys.stderr)
         return 0
-    owner, repo, pr_number, base_ref = ctx
+    owner, repo, pr_number, base_ref, base_sha = ctx
     token = env.get("GITHUB_TOKEN", "").strip()
-    base_ref_full = f"origin/{base_ref}"
+    # Prefer the base SHA (always in merge-ref history with fetch-depth:0); fall back to
+    # origin/<base> only if the payload lacked a sha. No `git fetch` is required.
+    base_ref_full = base_sha or f"origin/{base_ref}"
 
     # 2. Load branch + base versions of the source of truth.
     b_exists, branch_bp, b_err = load_branch_file(repo_root, ".archie/blueprint.json")
@@ -821,7 +843,18 @@ def main(argv=None) -> int:
         print("[intent-review] no .archie/blueprint.json on branch — nothing to review.", file=sys.stderr)
         return 0
 
-    _, base_bp, _ = fetch_base_file(repo_root, base_ref_full, ".archie/blueprint.json")
+    base_exists, base_bp, base_err = fetch_base_file(repo_root, base_ref_full, ".archie/blueprint.json")
+    if base_err:
+        # The base REF could not be resolved (not "file absent"). Do NOT silently degrade
+        # to an empty baseline and post a confident-but-wrong "everything is new" review.
+        print(f"[intent-review] base ref {base_ref_full} unresolvable: {base_err}", file=sys.stderr)
+        safe_post_comment(owner, repo, pr_number,
+                          f"{COMMENT_MARKER}\n## 📐 Archie Intent Review\n\n"
+                          f"Could not resolve the PR base (`{base_ref_full}`) to diff against "
+                          f"(`{base_err}`). **Review skipped** to avoid a misleading "
+                          f"\"everything is new\" result — re-run once the base ref is available.",
+                          token)
+        return 0
     base_bp = base_bp if isinstance(base_bp, dict) else {}
 
     # Diff BOTH rule sources (rules.json + platform_rules.json), unioned.
diff --git a/docs/archie-intent-review-delivery-plan.md b/docs/archie-intent-review-delivery-plan.md
index d970bca..24e9a66 100644
--- a/docs/archie-intent-review-delivery-plan.md
+++ b/docs/archie-intent-review-delivery-plan.md
@@ -465,4 +465,35 @@ These are explicit code edits in M1a, not afterthoughts — without them the `.y
 - **`npx`-installer injection of `.github/workflows/`** — deliberately excluded; the setup script is the sole workflow installer (§8 decision).
 - **Post-merge fold automation** — unneeded; the fold already happened on the branch, so git's "merge = acceptance" handles baseline evolution automatically.
 
-Canonical deliverable paths (for the implementer): `archie/standalone/intent_review.py`, `archie/assets/workflows/archie-intent-review.yml`, `archie/assets/setup-archie-intent-review.sh`, `tests/test_intent_review.py`; edits to `archie/install.py`, `npm-package/assets/_install_pkg/install.py`, `npm-package/bin/archie.mjs`, `scripts/verify_sync.py`; byte-copies under `npm-package/assets/` (`intent_review.py`, `workflows/archie-intent-review.yml`, `setup-archie-intent-review.sh`).
\ No newline at end of file
+Canonical deliverable paths (for the implementer): `archie/standalone/intent_review.py`, `archie/assets/workflows/archie-intent-review.yml`, `archie/assets/setup-archie-intent-review.sh`, `tests/test_intent_review.py`; edits to `archie/install.py`, `npm-package/assets/_install_pkg/install.py`, `npm-package/bin/archie.mjs`, `scripts/verify_sync.py`; byte-copies under `npm-package/assets/` (`intent_review.py`, `workflows/archie-intent-review.yml`, `setup-archie-intent-review.sh`).
+
+---
+
+## 10. Amendments from the "right-thing" validation review (2026-06-19)
+
+Three findings from a post-implementation validation review (does it deliver the
+intended value, not just pass tests) were folded in:
+
+1. **Base-ref resolution — switched from `origin/<base>` to `pull_request.base.sha`.**
+   The original `git fetch origin <base>` + `continue-on-error: true` could fail
+   silently, leaving `origin/<base>` unresolvable, which degraded the diff to "everything
+   is new" and posted a confident-but-wrong review — the exact corruption the tool exists
+   to catch. Now the script diffs against `github.event.pull_request.base.sha`, which is
+   always present in the merge-ref history with `fetch-depth: 0`. The `Fetch base ref` step
+   was removed. **`fetch_base_file` now distinguishes "file genuinely absent at a valid
+   ref" (legitimate all-ADD) from "ref unresolvable" (a hard error) — the latter posts a
+   loud "review skipped" note instead of a wrong all-new result.**
+
+2. **Diff coverage — `components[]` added (keyed, Layer 2).** A component REMOVE /
+   responsibility change is now caught with the same structured, low-noise keyed diff as
+   `data_models`. **Deliberately still out of POC scope (documented, not silent):** the
+   purely descriptive snapshots — `communication[]`, `architecture_diagram`,
+   `technology[]`, `quick_reference[]`, `implementation_guidelines[]`, `data_overview` —
+   because they reflect current code (not prescriptive law), a textual diff of them is the
+   design's lower-precision path, and behavior-level violations still surface via
+   descriptive ledger claims. Textual fallback for those is a future enhancement.
+
+3. **M6 dogfood remains the user's step.** It requires the interactive `/archie-deep-scan`
+   + `/archie-sync` AI workflows and a real PR, so it is exercised by the user in a real
+   repository. The deterministic pipeline is validated offline (the Acme smoke + a
+   `main()` integration test driving a real `origin` clone via the base SHA).
\ No newline at end of file
diff --git a/npm-package/assets/intent_review.py b/npm-package/assets/intent_review.py
index 2be0398..5d8e0c7 100644
--- a/npm-package/assets/intent_review.py
+++ b/npm-package/assets/intent_review.py
@@ -61,8 +61,16 @@
 DECISION_SECTIONS = ["key_decisions", "trade_offs", "out_of_scope"]
 DECISION_TITLE_FIELD = "title"
 
-# Data sections we diff for Layer-2 behavior-violates-rule (keyed by name).
+# Structured Layer-2 sections (keyed by name) we diff for behavior-violates-rule.
+# `components` is included so a component REMOVE / responsibility change is caught
+# cleanly (keyed, not noisy textual). NOT covered (deliberate POC scope): the purely
+# descriptive snapshots — communication[], architecture_diagram, technology[],
+# quick_reference[], implementation_guidelines[], data_overview. Those reflect current
+# code (not prescriptive law) and a textual diff of them is the design's lower-precision
+# path; behavior-level violations still surface via DESCRIPTIVE LEDGER CLAIMS. Textual
+# fallback for those sections is a documented future enhancement.
 DATA_SECTIONS = [
+    ("components", "name"),
     ("data_models", "name"),
     ("persistence_stores", "name"),
 ]
@@ -102,18 +110,22 @@ def _parse_json(text: str):
 def fetch_base_file(repo_root: Path, base_ref: str, rel_path: str):
     """Read `rel_path` from the base ref via `git show`.
 
-    Returns (exists: bool, data: dict|list|None, error: str|None).
-    A file absent on the base ref -> (False, None, None): treat everything as ADD.
-    A malformed JSON on the base ref -> (True, None, "<err>").
+    Returns (exists: bool, data: dict|list|None, error: str|None) and CRITICALLY
+    distinguishes two non-zero outcomes:
+      - the file is genuinely ABSENT at a VALID ref (e.g. the first PR to add .archie/)
+        -> (False, None, None): a legitimate all-ADD case.
+      - the REF ITSELF is unresolvable (bad SHA / unknown revision) -> (False, None, err):
+        the DANGEROUS case — the caller must NOT silently degrade to an empty baseline,
+        or it would post a confident but wrong "everything is new" review.
+    Malformed JSON at a valid ref -> (True, None, "<err>").
     """
     code, out, err = run_git(repo_root, "show", f"{base_ref}:{rel_path}")
     if code != 0:
         low = (err or "").lower()
-        if "does not exist" in low or "exists on disk, but not" in low \
-                or "invalid object" in low or "unknown revision" in low \
-                or "path" in low and "does not exist" in low or "fatal" in low:
-            # absent on base ref
+        # File absent at a VALID ref — git says the path doesn't exist *in* the ref.
+        if "does not exist in" in low or "exists on disk, but not in" in low:
             return False, None, None
+        # Ref unresolvable or any other git failure — surface it, do not pretend absent.
         return False, None, err.strip() or "git show failed"
     data, perr = _parse_json(out)
     return True, data, perr
@@ -765,7 +777,12 @@ def safe_post_comment(owner, repo, pr_number, body, token):
 # event context
 # ---------------------------------------------------------------------------
 def parse_event_context(env: dict):
-    """Return (owner, repo, pr_number, base_ref) or None if not a usable PR event."""
+    """Return (owner, repo, pr_number, base_ref, base_sha) or None.
+
+    `base_sha` (pull_request.base.sha) is the robust base to diff against: with
+    `actions/checkout` `fetch-depth: 0` it is always present in the merge-ref history,
+    so no `git fetch` is needed and there is no `origin/<base>` resolution to fail.
+    """
     repo_full = env.get("GITHUB_REPOSITORY", "")
     base_ref = env.get("GITHUB_BASE_REF", "")
     event_path = env.get("GITHUB_EVENT_PATH", "")
@@ -773,18 +790,21 @@ def parse_event_context(env: dict):
         return None
     owner, repo = repo_full.split("/", 1)
     pr_number = None
+    base_sha = ""
     if event_path and Path(event_path).exists():
         try:
             event = json.loads(Path(event_path).read_text())
             pr = event.get("pull_request")
             if isinstance(pr, dict):
                 pr_number = pr.get("number")
-                base_ref = base_ref or (pr.get("base") or {}).get("ref", "")
+                base = pr.get("base") or {}
+                base_ref = base_ref or base.get("ref", "")
+                base_sha = base.get("sha", "") or ""
         except (OSError, json.JSONDecodeError):
             return None
     if pr_number is None or not base_ref:
         return None
-    return owner, repo, pr_number, base_ref
+    return owner, repo, pr_number, base_ref, base_sha
 
 
 # ---------------------------------------------------------------------------
@@ -804,9 +824,11 @@ def main(argv=None) -> int:
     if ctx is None:
         print("[intent-review] not a usable pull_request event — skipping.", file=sys.stderr)
         return 0
-    owner, repo, pr_number, base_ref = ctx
+    owner, repo, pr_number, base_ref, base_sha = ctx
     token = env.get("GITHUB_TOKEN", "").strip()
-    base_ref_full = f"origin/{base_ref}"
+    # Prefer the base SHA (always in merge-ref history with fetch-depth:0); fall back to
+    # origin/<base> only if the payload lacked a sha. No `git fetch` is required.
+    base_ref_full = base_sha or f"origin/{base_ref}"
 
     # 2. Load branch + base versions of the source of truth.
     b_exists, branch_bp, b_err = load_branch_file(repo_root, ".archie/blueprint.json")
@@ -821,7 +843,18 @@ def main(argv=None) -> int:
         print("[intent-review] no .archie/blueprint.json on branch — nothing to review.", file=sys.stderr)
         return 0
 
-    _, base_bp, _ = fetch_base_file(repo_root, base_ref_full, ".archie/blueprint.json")
+    base_exists, base_bp, base_err = fetch_base_file(repo_root, base_ref_full, ".archie/blueprint.json")
+    if base_err:
+        # The base REF could not be resolved (not "file absent"). Do NOT silently degrade
+        # to an empty baseline and post a confident-but-wrong "everything is new" review.
+        print(f"[intent-review] base ref {base_ref_full} unresolvable: {base_err}", file=sys.stderr)
+        safe_post_comment(owner, repo, pr_number,
+                          f"{COMMENT_MARKER}\n## 📐 Archie Intent Review\n\n"
+                          f"Could not resolve the PR base (`{base_ref_full}`) to diff against "
+                          f"(`{base_err}`). **Review skipped** to avoid a misleading "
+                          f"\"everything is new\" result — re-run once the base ref is available.",
+                          token)
+        return 0
     base_bp = base_bp if isinstance(base_bp, dict) else {}
 
     # Diff BOTH rule sources (rules.json + platform_rules.json), unioned.
diff --git a/npm-package/assets/workflows/archie-intent-review.yml b/npm-package/assets/workflows/archie-intent-review.yml
index ae845e3..487adca 100644
--- a/npm-package/assets/workflows/archie-intent-review.yml
+++ b/npm-package/assets/workflows/archie-intent-review.yml
@@ -19,10 +19,9 @@ jobs:
         with:
           python-version: '3.11'
 
-      - name: Fetch base ref
-        continue-on-error: true
-        run: git fetch --no-tags --depth=1 origin "${{ github.base_ref }}"
-
+      # No `git fetch` needed: with fetch-depth:0 the PR base SHA
+      # (github.event.pull_request.base.sha) is already in history, and the script
+      # diffs against it directly — so there is no origin/<base> resolution to fail.
       - name: Run Archie Intent Review
         env:
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
diff --git a/tests/test_intent_review.py b/tests/test_intent_review.py
index bfb99a0..d69f770 100644
--- a/tests/test_intent_review.py
+++ b/tests/test_intent_review.py
@@ -113,6 +113,15 @@ def test_fetch_base_file_present_and_absent(tmp_path):
     assert exists is False and data is None and err is None
 
 
+def test_fetch_base_file_unresolvable_ref_is_error_not_absent(tmp_path):
+    # A bad SHA must NOT be mistaken for "file absent" (the silent-degradation trap).
+    root = _init_repo(tmp_path)
+    _write(root, ".archie/blueprint.json", {"domain_invariants": []})
+    _commit(root, "base")
+    exists, data, err = ir.fetch_base_file(root, "deadbeefdeadbeef", ".archie/blueprint.json")
+    assert exists is False and data is None and err  # error surfaced, not (False,None,None)
+
+
 def test_fetch_base_file_malformed(tmp_path):
     root = _init_repo(tmp_path)
     _write(root, ".archie/blueprint.json", "{not valid json")
@@ -176,13 +185,14 @@ def test_glob_ledger_excludes_records_on_base(tmp_path):
 # ---------------------------------------------------------------------------
 def test_parse_event_context_ok(tmp_path):
     event = tmp_path / "event.json"
-    event.write_text(json.dumps({"pull_request": {"number": 42, "base": {"ref": "main"}}}))
+    event.write_text(json.dumps({"pull_request": {"number": 42,
+                                "base": {"ref": "main", "sha": "abc123"}}}))
     ctx = ir.parse_event_context({
         "GITHUB_REPOSITORY": "octo/repo",
         "GITHUB_BASE_REF": "main",
         "GITHUB_EVENT_PATH": str(event),
     })
-    assert ctx == ("octo", "repo", 42, "main")
+    assert ctx == ("octo", "repo", 42, "main", "abc123")  # base_sha extracted
 
 
 def test_parse_event_context_pulls_base_from_payload(tmp_path):
@@ -193,7 +203,7 @@ def test_parse_event_context_pulls_base_from_payload(tmp_path):
         "GITHUB_BASE_REF": "",
         "GITHUB_EVENT_PATH": str(event),
     })
-    assert ctx == ("octo", "repo", 7, "develop")
+    assert ctx == ("octo", "repo", 7, "develop", "")  # no sha in payload -> ""
 
 
 def test_parse_event_context_rejects_non_pr(tmp_path):
@@ -480,6 +490,14 @@ def test_data_model_pure_add_is_surfaced():
     assert dm and dm[0]["diff_op"] == "ADD" and dm[0]["layer"] == 2
 
 
+def test_component_remove_is_diffed_layer2():
+    # a component REMOVE is caught (keyed by name, Layer 2) — coverage gap fix
+    base_bp = {"components": [{"name": "PaymentGateway", "responsibility": "money"}]}
+    items = ir.build_changed_items(base_bp, {"components": []}, [], [], [])
+    c = [i for i in items if i["section"] == "components"]
+    assert c and c[0]["diff_op"] == "REMOVE" and c[0]["layer"] == 2
+
+
 def test_rule_remove_is_layer1_branch_none():
     items = ir.build_changed_items({}, {}, [{"id": "R1", "description": "x"}], [], [])
     r = [i for i in items if i["source"] == "rules"][0]
@@ -573,6 +591,7 @@ def test_main_flags_removed_invariant_via_origin(tmp_path, monkeypatch):
          "keywords": ["tenant"], "enforced_at": ["db/p.py:1"]}]})
     _write(up, ".archie/rules.json", {"rules": []})
     _commit(up, "base")
+    base_sha = _git(up, "rev-parse", "HEAD")
 
     # working clone gets origin/main
     work = tmp_path / "work"
@@ -586,8 +605,10 @@ def test_main_flags_removed_invariant_via_origin(tmp_path, monkeypatch):
          "evidence_files": ["db/p.py"], "confidence": "low", "reconstructed": True}]})
     _commit(work, "remove invariant")
 
+    # Drive the diff off the base SHA (the robust path), not origin/<base>.
     event = work / "event.json"
-    event.write_text(json.dumps({"pull_request": {"number": 5, "base": {"ref": "main"}}}))
+    event.write_text(json.dumps({"pull_request": {"number": 5,
+                                "base": {"ref": "main", "sha": base_sha}}}))
 
     captured = {}
     monkeypatch.setattr(ir, "call_anthropic", lambda s, u, k, **kw: [

From cd22c97db9bd461db9b4700c80b9d00511104b77 Mon Sep 17 00:00:00 2001
From: Gabor Bakos <gabor@bitraptors.com>
Date: Fri, 19 Jun 2026 21:20:26 +0200
Subject: [PATCH 06/15] fix(intent-review): commit intent_review.py via
 gitignore exception
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

.archie/*.py is gitignored (regenerated by the installer), so intent_review.py
would never reach CI — the Action runs `python3 .archie/intent_review.py` where
no Archie install exists. Add it to the committed hook-runtime exception set
(alongside _common/lint_gate/align_check/arch_review) so it ships in the repo.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 archie/assets/gitignore.default      | 5 ++++-
 npm-package/assets/gitignore.default | 5 ++++-
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/archie/assets/gitignore.default b/archie/assets/gitignore.default
index 6ef6b37..b508c84 100644
--- a/archie/assets/gitignore.default
+++ b/archie/assets/gitignore.default
@@ -24,9 +24,12 @@ tmp/
 # them. EXCEPTION: the small hook-runtime set below is committed so the
 # enforcement hooks keep working even without a local Archie install. Their file
 # reads are routed through one validated sink (_common.safe_read_text), so a
-# security scanner has nothing to flag.
+# security scanner has nothing to flag. intent_review.py is committed for the same
+# reason — the Intent Review GitHub Action runs `python3 .archie/intent_review.py`
+# in CI, where no Archie install exists to regenerate it.
 *.py
 !_common.py
 !lint_gate.py
 !align_check.py
 !arch_review.py
+!intent_review.py
diff --git a/npm-package/assets/gitignore.default b/npm-package/assets/gitignore.default
index 6ef6b37..b508c84 100644
--- a/npm-package/assets/gitignore.default
+++ b/npm-package/assets/gitignore.default
@@ -24,9 +24,12 @@ tmp/
 # them. EXCEPTION: the small hook-runtime set below is committed so the
 # enforcement hooks keep working even without a local Archie install. Their file
 # reads are routed through one validated sink (_common.safe_read_text), so a
-# security scanner has nothing to flag.
+# security scanner has nothing to flag. intent_review.py is committed for the same
+# reason — the Intent Review GitHub Action runs `python3 .archie/intent_review.py`
+# in CI, where no Archie install exists to regenerate it.
 *.py
 !_common.py
 !lint_gate.py
 !align_check.py
 !arch_review.py
+!intent_review.py

From cc2abf901e5c7fa3beb929fbd2e52a5cb0e11ac2 Mon Sep 17 00:00:00 2001
From: Gabor Bakos <gabor@bitraptors.com>
Date: Mon, 22 Jun 2026 10:50:26 +0200
Subject: [PATCH 07/15] =?UTF-8?q?feat(intent-review):=20consolidate=20find?=
 =?UTF-8?q?ings=20=E2=80=94=20one=20per=20change,=20list=20colliding=20rul?=
 =?UTF-8?q?es?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Real-repo test produced 8 near-identical findings (2 functions x 4 rules) for a
single change (cap 7->12). Now the model emits ONE finding per distinct change,
spanning multiple item_refs and listing ALL colliding_rules in a single cited
because. A dedup backstop merges any findings the model still splits (same type +
same colliding-rule set). Render shows "<change> (op, Layer N · K sites) — Collides
with: rule1, rule2…". 8 -> 1.

Tests: +2 (consolidate-across-items, dedup-merges-split); 47 in-file, full suite
1025 passed / 1 skipped; verify_sync green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 archie/standalone/intent_review.py  | 133 ++++++++++++++++++++--------
 npm-package/assets/intent_review.py | 133 ++++++++++++++++++++--------
 tests/test_intent_review.py         |  75 +++++++++++-----
 3 files changed, 245 insertions(+), 96 deletions(-)

diff --git a/archie/standalone/intent_review.py b/archie/standalone/intent_review.py
index 5d8e0c7..3fc2b5a 100644
--- a/archie/standalone/intent_review.py
+++ b/archie/standalone/intent_review.py
@@ -492,12 +492,15 @@ def retained_rules(base_rules: list, changed_items: list) -> list:
 EMIT_FINDINGS_TOOL = {
     "name": "emit_findings",
     "description": (
-        "Emit structured review findings about a PR's change to the architectural "
-        "source of truth. For each CHANGED ITEM you judge to be a real concern, emit a "
-        "finding. The diff op and which item changed are GIVEN to you (cite item_ref). "
-        "Your job is ONLY to judge the TYPE and write a verifiable, cited BECAUSE drawn "
-        "from the item's own text and the retained rules. BECAUSE-OR-SUPPRESS: if you "
-        "cannot ground a finding in the provided texts, omit it entirely."
+        "Emit CONSOLIDATED review findings about a PR's change to the architectural "
+        "source of truth. Emit ONE finding per DISTINCT change — NOT one per rule, and "
+        "NOT one per code symbol. If the SAME underlying change appears across multiple "
+        "functions/files/items, report it ONCE and list every item_ref it spans. In each "
+        "finding, list ALL rules/invariants it collides with in `colliding_rules`, and "
+        "write ONE consolidated, verifiable BECAUSE covering them. The diff op and which "
+        "items changed are GIVEN (cite item_refs); you judge the TYPE and the BECAUSE. "
+        "BECAUSE-OR-SUPPRESS: if you cannot ground it in the provided texts, omit it. "
+        "Prefer FEW, well-consolidated findings over many repetitive ones."
     ),
     "input_schema": {
         "type": "object",
@@ -507,16 +510,18 @@ def retained_rules(base_rules: list, changed_items: list) -> list:
                 "items": {
                     "type": "object",
                     "properties": {
-                        "item_ref": {"type": "string",
-                                     "description": "ref of the CHANGED ITEM this is about (e.g. c0). Findings referencing no listed item are discarded."},
+                        "item_refs": {"type": "array", "items": {"type": "string"},
+                                      "description": "ALL changed-item refs this one change spans (e.g. ['c0','c1']). A finding resolving to no listed item is discarded."},
                         "type": {"type": "string",
                                  "enum": ["silent_weakening", "contradiction", "behavior_violates_rule"]},
-                        "rule_name": {"type": "string", "description": "the invariant/rule this concerns"},
-                        "what_changed": {"type": "string"},
+                        "change_summary": {"type": "string",
+                                           "description": "short, specific title of the change, e.g. 'Backend billable-step cap raised 7 -> 12'"},
+                        "colliding_rules": {"type": "array", "items": {"type": "string"},
+                                            "description": "every retained rule/invariant id or name this change collides with"},
                         "because": {"type": "string",
-                                    "description": "verifiable cited rationale from the texts; empty => dropped"},
+                                    "description": "one consolidated, cited rationale covering the colliding rules; empty => dropped"},
                     },
-                    "required": ["item_ref", "type", "rule_name", "what_changed", "because"],
+                    "required": ["item_refs", "type", "change_summary", "colliding_rules", "because"],
                 },
             },
         },
@@ -530,12 +535,16 @@ def build_prompt(changed_items: list, retained: list, claims: list) -> tuple:
     system = (
         "You are an architecture reviewer for a pull request. The change has already been "
         "folded into the project's blueprint and rules; you are given a DETERMINISTIC diff "
-        "of the source of truth (you do NOT decide what changed). Judge each CHANGED ITEM:\n"
+        "of the source of truth (you do NOT decide what changed). Report CONSOLIDATED findings:\n"
+        "- ONE finding per DISTINCT change. If a change spans multiple functions/files "
+        "(several changed items), report it ONCE, list every item_ref, and list ALL the "
+        "rules it collides with in colliding_rules. NEVER emit a separate finding per rule "
+        "or per code symbol — that is noise.\n"
         "- silent_weakening: a REMOVE/UPDATE that retires or softens an invariant or key decision.\n"
-        "- contradiction: an ADD/UPDATE to the rules that conflicts with a RETAINED rule.\n"
-        "- behavior_violates_rule: a described behavior/data change that breaks a RETAINED rule.\n"
-        "Only emit a finding when it is real and you can cite WHY from the provided texts "
-        "(because-or-suppress). Do not flag benign additions. Call emit_findings exactly once."
+        "- contradiction: an ADD/UPDATE that conflicts with a RETAINED rule.\n"
+        "- behavior_violates_rule: a described behavior/data change that breaks RETAINED rule(s).\n"
+        "Only emit real, cited findings (because-or-suppress); do not flag benign additions. "
+        "Prefer FEW, well-consolidated findings. Call emit_findings exactly once."
     )
 
     def trim(item, n=600):
@@ -623,39 +632,88 @@ def _extract_findings(api_response: dict) -> list:
 # finalize: overwrite deterministic fields, because-or-suppress, ledger join
 # ---------------------------------------------------------------------------
 def finalize_findings(model_findings: list, changed_items: list, claims: list) -> list:
-    """Bind each model finding to its real changed item, overwrite the deterministic
-    fields from the script's own diff, drop unciteable/unmatched findings, and attach a
-    ledger-confidence sharpener where the conservative join succeeds.
+    """Bind each model finding to the real changed item(s) it spans, derive the
+    deterministic fields from the script's own diff, drop unciteable/unmatched findings,
+    attach a ledger-confidence sharpener, and merge any findings the model left split.
+
+    A finding is ONE distinct change spanning >=1 changed item, with the full list of
+    rules it collides with — so a cap-raise touching two functions and four rules is one
+    finding, not eight.
     """
     by_ref = {it["ref"]: it for it in changed_items}
     out = []
     for f in model_findings:
         if not isinstance(f, dict):
             continue
-        item = by_ref.get(f.get("item_ref"))
-        if item is None:
-            continue  # references no real diff item -> drop
+        # accept the consolidated shape (item_refs[]) and the legacy single item_ref.
+        refs = f.get("item_refs")
+        if not refs and f.get("item_ref"):
+            refs = [f["item_ref"]]
+        items = [by_ref[r] for r in (refs or []) if r in by_ref]
+        if not items:
+            continue  # resolves to no real diff item -> drop
         because = str(f.get("because", "")).strip()
         if not because:
             continue  # because-or-suppress
+
+        rules = f.get("colliding_rules")
+        if not rules and f.get("rule_name"):
+            rules = [f["rule_name"]]
+        rules = _dedup_preserve([str(r).strip() for r in (rules or []) if str(r).strip()])
+        summary = (str(f.get("change_summary", "")).strip()
+                   or str(f.get("what_changed", "")).strip()
+                   or items[0]["title"])
+
+        ops = sorted({it["diff_op"] for it in items})
+        layers = sorted({it["layer"] for it in items})
         finding = {
-            # deterministic, script-owned (overwrite the model's echo):
-            "diff_op": item["diff_op"],
-            "layer": item["layer"],
-            "section": item["section"],
-            "rule_name": item["title"],
+            # deterministic, script-owned:
+            "diff_op": ops[0] if len(ops) == 1 else "/".join(ops),
+            "layer": layers[0],
+            "sections": sorted({it["section"] for it in items}),
+            "site_count": len(items),
             # model judgment:
             "type": f.get("type", "behavior_violates_rule"),
-            "what_changed": str(f.get("what_changed", "")).strip(),
+            "change_summary": summary,
+            "colliding_rules": rules,
             "because": because,
             "confidence": None,
         }
-        join = ledger_join(item, claims)
-        if join:
-            finding["confidence"] = join.get("confidence")
-            finding["reconstructed"] = join.get("reconstructed")
+        for it in items:  # first conservative ledger-join wins
+            join = ledger_join(it, claims)
+            if join:
+                finding["confidence"] = join.get("confidence")
+                finding["reconstructed"] = join.get("reconstructed")
+                break
         out.append(finding)
-    return out
+    return _dedupe_findings(out)
+
+
+def _dedup_preserve(seq):
+    seen = set()
+    return [x for x in seq if not (x in seen or seen.add(x))]
+
+
+def _dedupe_findings(findings: list) -> list:
+    """Backstop: merge findings the model left split — same type colliding with the SAME
+    set of rules is the same logical change. Combines site counts + keeps a confidence."""
+    merged = {}
+    order = []
+    for f in findings:
+        if f["colliding_rules"]:
+            key = (f["type"], frozenset(r.lower() for r in f["colliding_rules"]))
+        else:
+            key = (f["type"], f["change_summary"].lower())
+        if key in merged:
+            m = merged[key]
+            m["site_count"] += f["site_count"]
+            if f.get("confidence") and not m.get("confidence"):
+                m["confidence"] = f.get("confidence")
+                m["reconstructed"] = f.get("reconstructed")
+        else:
+            merged[key] = dict(f)
+            order.append(key)
+    return [merged[k] for k in order]
 
 
 # ---------------------------------------------------------------------------
@@ -693,9 +751,12 @@ def render_comment(findings: list, had_diff: bool):
             if f.get("confidence"):
                 rec = " · reconstructed guess" if f.get("reconstructed") else ""
                 conf = f" _(ledger confidence: {f['confidence']}{rec})_"
+            sites = f" · {f['site_count']} sites" if f.get("site_count", 1) > 1 else ""
+            collides = ""
+            if f.get("colliding_rules"):
+                collides = "  \n  Collides with: **" + ", ".join(f["colliding_rules"]) + "**"
             lines.append(
-                f"- **{f['rule_name']}** ({f['diff_op']}, Layer {f['layer']}){conf}  \n"
-                f"  {f['what_changed']}  \n"
+                f"- **{f['change_summary']}** ({f['diff_op']}, Layer {f['layer']}{sites}){conf}{collides}  \n"
                 f"  _Because:_ {f['because']}"
             )
     lines.append("")
diff --git a/npm-package/assets/intent_review.py b/npm-package/assets/intent_review.py
index 5d8e0c7..3fc2b5a 100644
--- a/npm-package/assets/intent_review.py
+++ b/npm-package/assets/intent_review.py
@@ -492,12 +492,15 @@ def retained_rules(base_rules: list, changed_items: list) -> list:
 EMIT_FINDINGS_TOOL = {
     "name": "emit_findings",
     "description": (
-        "Emit structured review findings about a PR's change to the architectural "
-        "source of truth. For each CHANGED ITEM you judge to be a real concern, emit a "
-        "finding. The diff op and which item changed are GIVEN to you (cite item_ref). "
-        "Your job is ONLY to judge the TYPE and write a verifiable, cited BECAUSE drawn "
-        "from the item's own text and the retained rules. BECAUSE-OR-SUPPRESS: if you "
-        "cannot ground a finding in the provided texts, omit it entirely."
+        "Emit CONSOLIDATED review findings about a PR's change to the architectural "
+        "source of truth. Emit ONE finding per DISTINCT change — NOT one per rule, and "
+        "NOT one per code symbol. If the SAME underlying change appears across multiple "
+        "functions/files/items, report it ONCE and list every item_ref it spans. In each "
+        "finding, list ALL rules/invariants it collides with in `colliding_rules`, and "
+        "write ONE consolidated, verifiable BECAUSE covering them. The diff op and which "
+        "items changed are GIVEN (cite item_refs); you judge the TYPE and the BECAUSE. "
+        "BECAUSE-OR-SUPPRESS: if you cannot ground it in the provided texts, omit it. "
+        "Prefer FEW, well-consolidated findings over many repetitive ones."
     ),
     "input_schema": {
         "type": "object",
@@ -507,16 +510,18 @@ def retained_rules(base_rules: list, changed_items: list) -> list:
                 "items": {
                     "type": "object",
                     "properties": {
-                        "item_ref": {"type": "string",
-                                     "description": "ref of the CHANGED ITEM this is about (e.g. c0). Findings referencing no listed item are discarded."},
+                        "item_refs": {"type": "array", "items": {"type": "string"},
+                                      "description": "ALL changed-item refs this one change spans (e.g. ['c0','c1']). A finding resolving to no listed item is discarded."},
                         "type": {"type": "string",
                                  "enum": ["silent_weakening", "contradiction", "behavior_violates_rule"]},
-                        "rule_name": {"type": "string", "description": "the invariant/rule this concerns"},
-                        "what_changed": {"type": "string"},
+                        "change_summary": {"type": "string",
+                                           "description": "short, specific title of the change, e.g. 'Backend billable-step cap raised 7 -> 12'"},
+                        "colliding_rules": {"type": "array", "items": {"type": "string"},
+                                            "description": "every retained rule/invariant id or name this change collides with"},
                         "because": {"type": "string",
-                                    "description": "verifiable cited rationale from the texts; empty => dropped"},
+                                    "description": "one consolidated, cited rationale covering the colliding rules; empty => dropped"},
                     },
-                    "required": ["item_ref", "type", "rule_name", "what_changed", "because"],
+                    "required": ["item_refs", "type", "change_summary", "colliding_rules", "because"],
                 },
             },
         },
@@ -530,12 +535,16 @@ def build_prompt(changed_items: list, retained: list, claims: list) -> tuple:
     system = (
         "You are an architecture reviewer for a pull request. The change has already been "
         "folded into the project's blueprint and rules; you are given a DETERMINISTIC diff "
-        "of the source of truth (you do NOT decide what changed). Judge each CHANGED ITEM:\n"
+        "of the source of truth (you do NOT decide what changed). Report CONSOLIDATED findings:\n"
+        "- ONE finding per DISTINCT change. If a change spans multiple functions/files "
+        "(several changed items), report it ONCE, list every item_ref, and list ALL the "
+        "rules it collides with in colliding_rules. NEVER emit a separate finding per rule "
+        "or per code symbol — that is noise.\n"
         "- silent_weakening: a REMOVE/UPDATE that retires or softens an invariant or key decision.\n"
-        "- contradiction: an ADD/UPDATE to the rules that conflicts with a RETAINED rule.\n"
-        "- behavior_violates_rule: a described behavior/data change that breaks a RETAINED rule.\n"
-        "Only emit a finding when it is real and you can cite WHY from the provided texts "
-        "(because-or-suppress). Do not flag benign additions. Call emit_findings exactly once."
+        "- contradiction: an ADD/UPDATE that conflicts with a RETAINED rule.\n"
+        "- behavior_violates_rule: a described behavior/data change that breaks RETAINED rule(s).\n"
+        "Only emit real, cited findings (because-or-suppress); do not flag benign additions. "
+        "Prefer FEW, well-consolidated findings. Call emit_findings exactly once."
     )
 
     def trim(item, n=600):
@@ -623,39 +632,88 @@ def _extract_findings(api_response: dict) -> list:
 # finalize: overwrite deterministic fields, because-or-suppress, ledger join
 # ---------------------------------------------------------------------------
 def finalize_findings(model_findings: list, changed_items: list, claims: list) -> list:
-    """Bind each model finding to its real changed item, overwrite the deterministic
-    fields from the script's own diff, drop unciteable/unmatched findings, and attach a
-    ledger-confidence sharpener where the conservative join succeeds.
+    """Bind each model finding to the real changed item(s) it spans, derive the
+    deterministic fields from the script's own diff, drop unciteable/unmatched findings,
+    attach a ledger-confidence sharpener, and merge any findings the model left split.
+
+    A finding is ONE distinct change spanning >=1 changed item, with the full list of
+    rules it collides with — so a cap-raise touching two functions and four rules is one
+    finding, not eight.
     """
     by_ref = {it["ref"]: it for it in changed_items}
     out = []
     for f in model_findings:
         if not isinstance(f, dict):
             continue
-        item = by_ref.get(f.get("item_ref"))
-        if item is None:
-            continue  # references no real diff item -> drop
+        # accept the consolidated shape (item_refs[]) and the legacy single item_ref.
+        refs = f.get("item_refs")
+        if not refs and f.get("item_ref"):
+            refs = [f["item_ref"]]
+        items = [by_ref[r] for r in (refs or []) if r in by_ref]
+        if not items:
+            continue  # resolves to no real diff item -> drop
         because = str(f.get("because", "")).strip()
         if not because:
             continue  # because-or-suppress
+
+        rules = f.get("colliding_rules")
+        if not rules and f.get("rule_name"):
+            rules = [f["rule_name"]]
+        rules = _dedup_preserve([str(r).strip() for r in (rules or []) if str(r).strip()])
+        summary = (str(f.get("change_summary", "")).strip()
+                   or str(f.get("what_changed", "")).strip()
+                   or items[0]["title"])
+
+        ops = sorted({it["diff_op"] for it in items})
+        layers = sorted({it["layer"] for it in items})
         finding = {
-            # deterministic, script-owned (overwrite the model's echo):
-            "diff_op": item["diff_op"],
-            "layer": item["layer"],
-            "section": item["section"],
-            "rule_name": item["title"],
+            # deterministic, script-owned:
+            "diff_op": ops[0] if len(ops) == 1 else "/".join(ops),
+            "layer": layers[0],
+            "sections": sorted({it["section"] for it in items}),
+            "site_count": len(items),
             # model judgment:
             "type": f.get("type", "behavior_violates_rule"),
-            "what_changed": str(f.get("what_changed", "")).strip(),
+            "change_summary": summary,
+            "colliding_rules": rules,
             "because": because,
             "confidence": None,
         }
-        join = ledger_join(item, claims)
-        if join:
-            finding["confidence"] = join.get("confidence")
-            finding["reconstructed"] = join.get("reconstructed")
+        for it in items:  # first conservative ledger-join wins
+            join = ledger_join(it, claims)
+            if join:
+                finding["confidence"] = join.get("confidence")
+                finding["reconstructed"] = join.get("reconstructed")
+                break
         out.append(finding)
-    return out
+    return _dedupe_findings(out)
+
+
+def _dedup_preserve(seq):
+    seen = set()
+    return [x for x in seq if not (x in seen or seen.add(x))]
+
+
+def _dedupe_findings(findings: list) -> list:
+    """Backstop: merge findings the model left split — same type colliding with the SAME
+    set of rules is the same logical change. Combines site counts + keeps a confidence."""
+    merged = {}
+    order = []
+    for f in findings:
+        if f["colliding_rules"]:
+            key = (f["type"], frozenset(r.lower() for r in f["colliding_rules"]))
+        else:
+            key = (f["type"], f["change_summary"].lower())
+        if key in merged:
+            m = merged[key]
+            m["site_count"] += f["site_count"]
+            if f.get("confidence") and not m.get("confidence"):
+                m["confidence"] = f.get("confidence")
+                m["reconstructed"] = f.get("reconstructed")
+        else:
+            merged[key] = dict(f)
+            order.append(key)
+    return [merged[k] for k in order]
 
 
 # ---------------------------------------------------------------------------
@@ -693,9 +751,12 @@ def render_comment(findings: list, had_diff: bool):
             if f.get("confidence"):
                 rec = " · reconstructed guess" if f.get("reconstructed") else ""
                 conf = f" _(ledger confidence: {f['confidence']}{rec})_"
+            sites = f" · {f['site_count']} sites" if f.get("site_count", 1) > 1 else ""
+            collides = ""
+            if f.get("colliding_rules"):
+                collides = "  \n  Collides with: **" + ", ".join(f["colliding_rules"]) + "**"
             lines.append(
-                f"- **{f['rule_name']}** ({f['diff_op']}, Layer {f['layer']}){conf}  \n"
-                f"  {f['what_changed']}  \n"
+                f"- **{f['change_summary']}** ({f['diff_op']}, Layer {f['layer']}{sites}){conf}{collides}  \n"
                 f"  _Because:_ {f['because']}"
             )
     lines.append("")
diff --git a/tests/test_intent_review.py b/tests/test_intent_review.py
index d69f770..091bea3 100644
--- a/tests/test_intent_review.py
+++ b/tests/test_intent_review.py
@@ -286,31 +286,56 @@ def _items():
 
 def test_finalize_overwrites_and_suppresses():
     model = [
-        # valid finding, but model lies about diff_op -> script overwrites
-        {"item_ref": "c0", "type": "silent_weakening", "rule_name": "wrong",
-         "what_changed": "removed", "because": "rule text says X", "diff_op": "ADD"},
+        # valid finding (consolidated shape); model lies about op -> script ignores it
+        {"item_refs": ["c0"], "type": "silent_weakening", "change_summary": "removed scoping",
+         "colliding_rules": ["der-006"], "because": "rule text says X", "diff_op": "ADD"},
         # because blank -> dropped
-        {"item_ref": "c1", "type": "contradiction", "rule_name": "R2",
-         "what_changed": "", "because": "   "},
-        # ref doesn't exist -> dropped
-        {"item_ref": "zzz", "type": "contradiction", "rule_name": "ghost",
-         "what_changed": "x", "because": "y"},
+        {"item_refs": ["c1"], "type": "contradiction", "change_summary": "R2",
+         "colliding_rules": ["x"], "because": "   "},
+        # refs don't exist -> dropped
+        {"item_refs": ["zzz"], "type": "contradiction", "change_summary": "ghost",
+         "colliding_rules": ["y"], "because": "z"},
     ]
     out = ir.finalize_findings(model, _items(), [])
     assert len(out) == 1
     f = out[0]
-    assert f["diff_op"] == "REMOVE"          # overwritten from the item, not the model's "ADD"
-    assert f["rule_name"] == "Tenant isolation"  # script-owned title, not model's "wrong"
-    assert f["layer"] == 1
+    assert f["diff_op"] == "REMOVE"            # from c0, not the model's "ADD"
+    assert f["change_summary"] == "removed scoping"
+    assert f["colliding_rules"] == ["der-006"]
+    assert f["layer"] == 1 and f["site_count"] == 1
     assert f["because"] == "rule text says X"
 
 
+def test_finalize_consolidates_one_change_across_items_and_rules():
+    # one change spanning BOTH items, colliding with FOUR rules -> ONE finding
+    model = [{"item_refs": ["c0", "c1"], "type": "behavior_violates_rule",
+              "change_summary": "cap raised 7->12",
+              "colliding_rules": ["inv-002", "der-001", "der-005", "tra-001"],
+              "because": "raising the cap unbinds the 7-step constraint"}]
+    out = ir.finalize_findings(model, _items(), [])
+    assert len(out) == 1
+    assert out[0]["site_count"] == 2
+    assert out[0]["colliding_rules"] == ["inv-002", "der-001", "der-005", "tra-001"]
+
+
+def test_dedupe_merges_split_findings_with_same_rule_set():
+    # model split the same change into 2 findings hitting the same rule set -> merged
+    model = [
+        {"item_refs": ["c0"], "type": "behavior_violates_rule", "change_summary": "fn A caps at 12",
+         "colliding_rules": ["inv-002", "der-001"], "because": "A violates the cap"},
+        {"item_refs": ["c1"], "type": "behavior_violates_rule", "change_summary": "fn B caps at 12",
+         "colliding_rules": ["der-001", "inv-002"], "because": "B violates the cap"},
+    ]
+    out = ir.finalize_findings(model, _items(), [])
+    assert len(out) == 1 and out[0]["site_count"] == 2
+
+
 def test_finalize_attaches_ledger_confidence():
     items = _items()
     claims = [{"statement": "tenant scoping dropped", "evidence_files": ["db/p.py"],
                "confidence": "low", "reconstructed": True}]
-    model = [{"item_ref": "c0", "type": "silent_weakening", "rule_name": "x",
-              "what_changed": "removed", "because": "cited"}]
+    model = [{"item_refs": ["c0"], "type": "silent_weakening", "change_summary": "removed",
+              "colliding_rules": ["der-006"], "because": "cited"}]
     out = ir.finalize_findings(model, items, claims)
     assert out[0]["confidence"] == "low" and out[0]["reconstructed"] is True
 
@@ -330,19 +355,21 @@ def test_render_comment_no_findings_is_consistent_message():
 
 def test_render_comment_groups_and_cites():
     findings = [
-        {"type": "silent_weakening", "diff_op": "REMOVE", "layer": 1,
-         "rule_name": "Tenant isolation", "what_changed": "removed scoping",
+        {"type": "silent_weakening", "diff_op": "REMOVE", "layer": 1, "site_count": 1,
+         "change_summary": "Tenant isolation dropped", "colliding_rules": ["der-002"],
          "because": "invariant text required tenant_id", "confidence": "low",
          "reconstructed": True},
-        {"type": "behavior_violates_rule", "diff_op": "DECLARED", "layer": 2,
-         "rule_name": "Centralized payments", "what_changed": "calls stripe directly",
-         "because": "R2 forbids direct stripe", "confidence": None},
+        {"type": "behavior_violates_rule", "diff_op": "DECLARED", "layer": 2, "site_count": 2,
+         "change_summary": "cap raised 7->12", "colliding_rules": ["inv-002", "der-001"],
+         "because": "R2 forbids it", "confidence": None},
     ]
     body = ir.render_comment(findings, had_diff=True)
     assert ir.COMMENT_MARKER in body
     assert "Silent weakening" in body and "Behavior may violate" in body
     assert "Because:" in body
     assert "ledger confidence: low" in body
+    assert "Collides with: **inv-002, der-001**" in body   # rules listed in ONE finding
+    assert "2 sites" in body                                 # consolidated across sites
     assert "reconstructed guess" in body
     assert "doesn't block" in body
 
@@ -569,10 +596,10 @@ def fake_urlopen(req, timeout=0):
 # ---------------------------------------------------------------------------
 def test_render_comment_preserves_flag_order():
     findings = [
-        {"type": "behavior_violates_rule", "diff_op": "DECLARED", "layer": 2,
-         "rule_name": "B", "what_changed": "", "because": "b"},
-        {"type": "silent_weakening", "diff_op": "REMOVE", "layer": 1,
-         "rule_name": "A", "what_changed": "", "because": "a"},
+        {"type": "behavior_violates_rule", "diff_op": "DECLARED", "layer": 2, "site_count": 1,
+         "change_summary": "B", "colliding_rules": [], "because": "b"},
+        {"type": "silent_weakening", "diff_op": "REMOVE", "layer": 1, "site_count": 1,
+         "change_summary": "A", "colliding_rules": [], "because": "a"},
     ]
     body = ir.render_comment(findings, had_diff=True)
     assert body.index("Silent weakening") < body.index("Behavior may violate")
@@ -612,8 +639,8 @@ def test_main_flags_removed_invariant_via_origin(tmp_path, monkeypatch):
 
     captured = {}
     monkeypatch.setattr(ir, "call_anthropic", lambda s, u, k, **kw: [
-        {"item_ref": "c0", "type": "silent_weakening", "rule_name": "x",
-         "what_changed": "removed tenant scoping", "because": "base invariant required tenant_id scoping"}])
+        {"item_refs": ["c0"], "type": "silent_weakening", "change_summary": "tenant scoping removed",
+         "colliding_rules": ["der-002"], "because": "base invariant required tenant_id scoping"}])
     monkeypatch.setattr(ir, "safe_post_comment",
                         lambda o, r, n, body, t: captured.update(body=body))
     for k, v in {"GITHUB_WORKSPACE": str(work), "ANTHROPIC_API_KEY": "sk-x",

From 16d791b5bbc6d656424a1f7248c21a3737b18db7 Mon Sep 17 00:00:00 2001
From: Gabor Bakos <gabor@bitraptors.com>
Date: Mon, 22 Jun 2026 10:55:24 +0200
Subject: [PATCH 08/15] chore(intent-review): bump actions to checkout@v5 +
 setup-python@v6 (Node24)

---
 archie/assets/workflows/archie-intent-review.yml      | 4 ++--
 npm-package/assets/workflows/archie-intent-review.yml | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/archie/assets/workflows/archie-intent-review.yml b/archie/assets/workflows/archie-intent-review.yml
index 487adca..2214112 100644
--- a/archie/assets/workflows/archie-intent-review.yml
+++ b/archie/assets/workflows/archie-intent-review.yml
@@ -11,11 +11,11 @@ jobs:
   intent-review:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: '3.11'
 
diff --git a/npm-package/assets/workflows/archie-intent-review.yml b/npm-package/assets/workflows/archie-intent-review.yml
index 487adca..2214112 100644
--- a/npm-package/assets/workflows/archie-intent-review.yml
+++ b/npm-package/assets/workflows/archie-intent-review.yml
@@ -11,11 +11,11 @@ jobs:
   intent-review:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: '3.11'
 

From cd98c21ab665b13b4ff4a55d983251cf642ce1dc Mon Sep 17 00:00:00 2001
From: Gabor Bakos <gabor@bitraptors.com>
Date: Mon, 22 Jun 2026 13:44:51 +0200
Subject: [PATCH 09/15] docs: plan for snapshot-vs-contract sync methodology
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phased plan to split the blueprint into a mirror (sync auto-updates from the
diff) and a contract (the law — deliberate edits only), so Intent Review reliably
catches drift and distinguishes violation from intended amendment via the diff,
not commit prose. Phase 1: sync code-fold becomes contract-readonly. Phase 2:
deliberate amendment path. Phase 3: review labels amendment vs violation. Grounded
in sync.py _SECTION_MAP/fold-context/fold-apply + the cap worked example.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs/archie-snapshot-vs-contract-plan.md | 99 ++++++++++++++++++++++++
 1 file changed, 99 insertions(+)
 create mode 100644 docs/archie-snapshot-vs-contract-plan.md

diff --git a/docs/archie-snapshot-vs-contract-plan.md b/docs/archie-snapshot-vs-contract-plan.md
new file mode 100644
index 0000000..235193e
--- /dev/null
+++ b/docs/archie-snapshot-vs-contract-plan.md
@@ -0,0 +1,99 @@
+# Living Blueprint — Snapshot vs. Contract (implementation plan)
+
+- **Status:** Design agreed; ready to plan into work.
+- **Builds on:** `docs/archie-intent-review-design.md` + `docs/archie-intent-review-delivery-plan.md`.
+- **One-line goal:** split the blueprint into a **mirror** (tracks the code, auto-updated by sync) and a **contract** (the law — changes only by deliberate edit), so the Intent Review reliably catches drift *and* distinguishes a **violation** from an **intended amendment** using the diff — never commit-message prose.
+
+This is not a redesign. The cap test already behaved this way by luck (sync moved the description to 12, left the rules at 7, the review caught the gap). The plan just makes that behavior **the rule**, and makes "did the contract change?" the intent signal.
+
+---
+
+## 1. The two layers
+
+| Layer | Meaning | Blueprint keys / files | Who moves it |
+|---|---|---|---|
+| **Mirror** (descriptive) | "what the code *is* now" | `components`, `communication`, `data_overview`, `data_models`*, `architecture_diagram`, `technology`, `quick_reference`, decision `how_it_works`/rationale prose | **sync auto-updates** from the diff |
+| **Contract** (prescriptive) | "what *must hold*" | `domain_invariants`, `derived_invariants`, `rules.json`, `platform_rules.json`, key `decisions` (forced_by/enables), `pitfalls`, the rendered `.claude/rules/*.md` | **deliberate edit only** |
+
+\* `data_models` is mirror for *shape* changes; a genuinely new persistence guarantee is a contract amendment. Edge case — flag in implementation.
+
+**Principle:** the review's value is detecting when the **mirror drifts from the contract**. A collision fires only when a change contradicts something that *stayed the same*.
+
+---
+
+## 2. Phase 1 — sync's code-fold is contract-readonly (the core change)
+
+Today `/archie-sync`'s fold can write the contract: `_SECTION_MAP` ([sync.py:412-425](archie/standalone/sync.py)) routes a `rule` claim to `rules.json` and `pitfall` to `findings.json`/`pitfalls`; `cmd_fold_apply` re-renders all docs (incl. `.claude/rules/*.md`) via `renderer.generate_all` ([sync.py:607](archie/standalone/sync.py)). That's the path that *could* silently move the law.
+
+**Change A — `_SECTION_MAP` / `cmd_fold_context` ([sync.py:412-485](archie/standalone/sync.py)):** in the **default (descriptive) fold**, only mirror sections are valid edit targets. Advisory/contract kinds (`rule`, contract-level `decision`, `pitfall`-as-invariant) are **not auto-folded** into `rules.json`/invariants — they're recorded in the ledger as **`staged` amendments** (already a concept: `eligible` vs `staged`) and surfaced to the dev, not written to the contract.
+
+**Change B — `cmd_fold_apply` ([sync.py:560-637](archie/standalone/sync.py)):** the re-render must not let a descriptive fold mutate contract artifacts. Render mirror-derived docs from the blueprint; render contract docs (`.claude/rules/*.md`) **from `rules.json` (unchanged)** so they can't drift to match the mirror. Extend the existing guardrail snapshot to assert `rules.json` + the invariant sections are **byte-identical** before/after a descriptive fold.
+
+**Change C — `archie/assets/workflow/sync/SKILL.md` (Step 4 "where edits land"):** rewrite the instruction so the agent's code-fold edits **mirror sections only**; a claim that would change the law is reported as a *proposed amendment* (Phase 2), never folded in place.
+
+**Acceptance:** after a code-fold, `git diff` of `.archie/rules.json`, `domain_invariants`, `derived_invariants`, and `.claude/rules/*.md` is **empty**; only mirror sections + `.archie/changes/*` changed. Add a sync test asserting this on a cap-style change.
+
+---
+
+## 3. Phase 2 — the deliberate amendment path
+
+When a contract *is* obsolete and should move, there must be an explicit, opt-in way to move it — and it must land in the PR diff so it's reviewable.
+
+**Change A — an amend mode.** Either (pick one during planning):
+- (a) **Hand-edit** `rules.json`/invariants in the PR (zero new tooling; the dev just edits the law deliberately), or
+- (b) **`/archie-sync --amend` / `/archie-amend`** — an explicit step where the agent reconciles `staged` contract claims *into* `rules.json`/invariants, marked `folded_as: amendment`.
+
+**Change B — completeness help (optional, high-value):** when amending one rule, surface the **interlocked** rules (those sharing keywords/`forced_by`/`enables` — e.g. `inv-002` → `der-001`/`der-005`/`tra-001`) so the dev amends them together and doesn't ship a half-amendment.
+
+**Acceptance:** amending the contract requires a deliberate action; the change appears in the PR's `rules.json`/invariant diff; nothing about a *code* change alone can produce it.
+
+---
+
+## 4. Phase 3 — the review labels amendment vs. violation
+
+The review already diffs `rules.json` and treats changed rules as *changed items* and unchanged ones as *retained* context ([intent_review.py](archie/standalone/intent_review.py) `build_changed_items` / `retained_rules`). So Cases B/C below already largely fall out — Phase 3 is mostly **labeling + visibility**.
+
+**Change A — classify each finding** by whether the rule it concerns was **changed in this PR** (contract moved → *amendment*) or **retained** (contract unchanged → *violation*).
+
+**Change B — render three buckets** instead of one undiscriminated list:
+- **✅ Intended amendments (N)** — contract rules this PR deliberately changed. *"Merge accepts these as the new baseline — confirm."* (Visibility for "merge = acceptance.")
+- **⚠️ Violations (M)** — the mirror changed but the unchanged contract forbids it.
+- **⚠️ Inconsistent amendments** — a changed contract rule contradicts a *retained* one ("you raised `inv-002` to 12 but `der-001` still says 7 — finish the amendment").
+
+**Acceptance** — the three cases from the discussion produce the three buckets:
+- **A** code only, contract unchanged → *Violation*.
+- **B** contract amended completely → *Intended amendment*, no violation.
+- **C** contract amended partially → *Inconsistent amendment*.
+
+---
+
+## 5. Worked example (cap 7 → 12)
+
+| What the dev does | Mirror | Contract | Review says |
+|---|---|---|---|
+| change code, run sync | "now 12" | unchanged (7) | **Violation** — `inv-002`/`der-001`/`der-005`/`tra-001` |
+| change code + amend `inv-002`,`der-001`,`der-005`, retire `tra-001` | "now 12" | all → 12 | **Intended amendment (4 rules)** — confirm & merge |
+| change code + amend only `inv-002` | "now 12" | `inv-002`→12, rest 7 | **Inconsistent amendment** — also update `der-001`/`der-005`/`tra-001` |
+
+---
+
+## 6. Out of scope
+- Auto-deciding whether an amendment is *correct* (still the human's call on merge — design §11).
+- Reading commit/PR prose for intent (deliberately rejected — unreliable).
+- Layer-3 raw-code reading (still eval-gated).
+
+## 7. Risks & mitigations
+| Risk | Mitigation |
+|---|---|
+| Phase 1 breaks existing sync users who relied on auto-folding rules | Advisory claims still recorded (as `staged`); only the *auto-write* stops. Document in the SKILL + changelog. |
+| `data_models` ambiguity (shape vs guarantee) | Treat as mirror by default; a new persistence *guarantee* is an explicit amendment — flag during impl. |
+| Renderer regenerates contract docs from blueprint, re-introducing drift | Phase 1 Change B: render `.claude/rules/*.md` from `rules.json`, not the mirror; assert byte-identity in the guardrail. |
+| Dev forgets to amend interlocked rules | Phase 2 Change B completeness help + Phase 3 "inconsistent amendment" bucket catch it. |
+
+## 8. Open questions
+1. Phase 2 path: hand-edit vs. an `--amend` command — which ergonomics? (Recommend starting with hand-edit + Phase 3 visibility; add `--amend` if friction warrants.)
+2. Are `decisions` one layer or split (prose = mirror, forced_by/enables = contract)? Likely split — confirm against the schema.
+3. Does `renderer.generate_all` cleanly separate mirror-docs from contract-docs today, or does Change B need a renderer split?
+
+## 9. Sequencing
+**Phase 1 first** (contract-readonly fold) — it alone makes the drift reliable and fixes the rendered-doc inconsistency you found. **Phase 3** (labeling) is small and high-visibility — do it next. **Phase 2** (amend ergonomics) last, only if hand-editing proves too rough. Each phase ships independently and is testable on its own.

From 6ef5d125da18b44240dfbaeb0ed303074e7405bf Mon Sep 17 00:00:00 2001
From: Gabor Bakos <gabor@bitraptors.com>
Date: Mon, 22 Jun 2026 13:50:52 +0200
Subject: [PATCH 10/15] =?UTF-8?q?docs:=20refine=20snapshot-vs-contract=20p?=
 =?UTF-8?q?lan=20=E2=80=94=20Accept=20IS=20the=20amendment?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

No manual rule-editing: the human only Fixes (code complies) or Accepts (merge).
Accept's contract change is auto-drafted by the system (affected + interlocked
rules) and applied on merge — the "auto-drafted amendment" from the original
brainstorm. The merge-vs-fix choice is the intent signal. Phase 3 drafts the
amendment + presents Fix-or-Accept; Phase 2 applies the draft (in-PR suggestion
or on-merge reconcile).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs/archie-snapshot-vs-contract-plan.md | 55 +++++++++++++-----------
 1 file changed, 31 insertions(+), 24 deletions(-)

diff --git a/docs/archie-snapshot-vs-contract-plan.md b/docs/archie-snapshot-vs-contract-plan.md
index 235193e..365e0ab 100644
--- a/docs/archie-snapshot-vs-contract-plan.md
+++ b/docs/archie-snapshot-vs-contract-plan.md
@@ -35,45 +35,52 @@ Today `/archie-sync`'s fold can write the contract: `_SECTION_MAP` ([sync.py:412
 
 ---
 
-## 3. Phase 2 — the deliberate amendment path
+## 3. Phase 2 — Accept *is* the amendment (no manual rule-editing)
 
-When a contract *is* obsolete and should move, there must be an explicit, opt-in way to move it — and it must land in the PR diff so it's reviewable.
+There is **no separate "edit the rules" task**. At the PR the human has exactly two moves:
 
-**Change A — an amend mode.** Either (pick one during planning):
-- (a) **Hand-edit** `rules.json`/invariants in the PR (zero new tooling; the dev just edits the law deliberately), or
-- (b) **`/archie-sync --amend` / `/archie-amend`** — an explicit step where the agent reconciles `staged` contract claims *into* `rules.json`/invariants, marked `folded_as: amendment`.
+- **Fix** — change the code to comply. The mirror returns to the old behavior; the contract is never touched. ("The rule still holds.")
+- **Accept (merge)** — the change becomes the new baseline, and the contract moves to match it. ("The rule is obsolete; this is the new law.")
 
-**Change B — completeness help (optional, high-value):** when amending one rule, surface the **interlocked** rules (those sharing keywords/`forced_by`/`enables` — e.g. `inv-002` → `der-001`/`der-005`/`tra-001`) so the dev amends them together and doesn't ship a half-amendment.
+The contract move on Accept is **auto-drafted by the system, not hand-written.** The review already knows which rules the change hits (it computed the diff) and which **interlocked** rules must move with them (shared keywords / `forced_by` / `enables` — e.g. `inv-002` → `der-001`/`der-005`/`tra-001`). It drafts that *consistent* amendment; merging applies it. This is the **"auto-drafted amendment"** from the original brainstorm — Archie writes the rule change; the human just takes it or rejects it.
 
-**Acceptance:** amending the contract requires a deliberate action; the change appears in the PR's `rules.json`/invariant diff; nothing about a *code* change alone can produce it.
+**The merge-vs-fix choice is the intent signal** — no commit prose, no manual editing.
+
+**Mechanism (pick during planning):**
+- (a) **In-PR suggestion** — the review posts the drafted contract change as a suggested commit; "Accept" applies it (one action), then merge accepts a consistent branch. Cleanest fit with "merge = acceptance" (the branch already holds the amended contract).
+- (b) **On-merge reconcile** — a post-merge step applies the drafted amendment to the contract on `main`.
+
+**Acceptance:** the human never hand-edits `rules.json`; **Accept** yields a *consistent* contract change (all interlocked rules moved together); **Fix** leaves the contract untouched. If the auto-draft is incomplete (misses an interlocked rule), Phase 3's consistency check flags it *before* Accept.
 
 ---
 
-## 4. Phase 3 — the review labels amendment vs. violation
+## 4. Phase 3 — the review presents Fix-or-Accept (and drafts the amendment)
 
-The review already diffs `rules.json` and treats changed rules as *changed items* and unchanged ones as *retained* context ([intent_review.py](archie/standalone/intent_review.py) `build_changed_items` / `retained_rules`). So Cases B/C below already largely fall out — Phase 3 is mostly **labeling + visibility**.
+The review already diffs `rules.json` and separates *changed* rules from *retained* context ([intent_review.py](archie/standalone/intent_review.py) `build_changed_items` / `retained_rules`), so most of this falls out.
 
-**Change A — classify each finding** by whether the rule it concerns was **changed in this PR** (contract moved → *amendment*) or **retained** (contract unchanged → *violation*).
+**Change A — draft the consistent amendment.** For each drift, compute the contract change Accept would apply: the affected rules **plus their interlocked rules** (shared keywords / `forced_by` / `enables`), with the new values — so Accept has something concrete to take.
 
-**Change B — render three buckets** instead of one undiscriminated list:
-- **✅ Intended amendments (N)** — contract rules this PR deliberately changed. *"Merge accepts these as the new baseline — confirm."* (Visibility for "merge = acceptance.")
-- **⚠️ Violations (M)** — the mirror changed but the unchanged contract forbids it.
-- **⚠️ Inconsistent amendments** — a changed contract rule contradicts a *retained* one ("you raised `inv-002` to 12 but `der-001` still says 7 — finish the amendment").
+**Change B — present each finding as the two moves:**
+- **⚠️ Drift — Fix or Accept.** *"The code now does 12; the contract says 7. **Fix** the code, or **Accept** to move `inv-002`/`der-001`/`der-005`→12 and retire `tra-001` (drafted below) as the new baseline."*
+- **⚠️ Inconsistent amendment.** If a contract change already on the branch moved one rule but left an interlocked one, flag it *before* Accept ("also update `der-001`").
 
-**Acceptance** — the three cases from the discussion produce the three buckets:
-- **A** code only, contract unchanged → *Violation*.
-- **B** contract amended completely → *Intended amendment*, no violation.
-- **C** contract amended partially → *Inconsistent amendment*.
+**Acceptance** — the discussion cases:
+- code only, no amendment applied → **Fix-or-Accept drift** (replaces "violation"); the draft is shown.
+- drafted amendment applied consistently → **clean Accept**, no inconsistency flag.
+- amendment applied partially → **inconsistent amendment** flag.
 
 ---
 
 ## 5. Worked example (cap 7 → 12)
 
-| What the dev does | Mirror | Contract | Review says |
+The dev changes code (cap→12) and runs sync. The mirror says "now 12"; the contract still says 7. The review flags the drift and **drafts** the consistent contract amendment. The dev then has exactly two moves:
+
+| Human move | Mirror | Contract | Result |
 |---|---|---|---|
-| change code, run sync | "now 12" | unchanged (7) | **Violation** — `inv-002`/`der-001`/`der-005`/`tra-001` |
-| change code + amend `inv-002`,`der-001`,`der-005`, retire `tra-001` | "now 12" | all → 12 | **Intended amendment (4 rules)** — confirm & merge |
-| change code + amend only `inv-002` | "now 12" | `inv-002`→12, rest 7 | **Inconsistent amendment** — also update `der-001`/`der-005`/`tra-001` |
+| **Fix** — revert the cap to 7 | back to 7 | unchanged | drift gone, no finding |
+| **Accept** — take the drafted amendment + merge | 12 | system moves `inv-002`/`der-001`/`der-005`→12, retires `tra-001` | consistent new baseline |
+
+No manual rule-editing in either path. Safety net: if the auto-draft moved `inv-002` but missed `der-001`, the review flags an **inconsistent amendment** *before* Accept — a half-amendment can't merge.
 
 ---
 
@@ -91,9 +98,9 @@ The review already diffs `rules.json` and treats changed rules as *changed items
 | Dev forgets to amend interlocked rules | Phase 2 Change B completeness help + Phase 3 "inconsistent amendment" bucket catch it. |
 
 ## 8. Open questions
-1. Phase 2 path: hand-edit vs. an `--amend` command — which ergonomics? (Recommend starting with hand-edit + Phase 3 visibility; add `--amend` if friction warrants.)
+1. Phase 2 mechanism for the auto-draft: **in-PR drafted suggestion** (Accept applies it pre-merge) vs. **on-merge reconcile**. Recommend the in-PR suggestion — it keeps "merge = acceptance" literal (the branch already holds the amended contract) and needs no post-merge automation. Who computes the consistent draft: the review model, or a deterministic interlock walk from `forced_by`/`enables`? (Likely model-proposed, deterministically scoped.)
 2. Are `decisions` one layer or split (prose = mirror, forced_by/enables = contract)? Likely split — confirm against the schema.
 3. Does `renderer.generate_all` cleanly separate mirror-docs from contract-docs today, or does Change B need a renderer split?
 
 ## 9. Sequencing
-**Phase 1 first** (contract-readonly fold) — it alone makes the drift reliable and fixes the rendered-doc inconsistency you found. **Phase 3** (labeling) is small and high-visibility — do it next. **Phase 2** (amend ergonomics) last, only if hand-editing proves too rough. Each phase ships independently and is testable on its own.
+**Phase 1 first** (contract-readonly fold) — it alone makes the drift reliable and fixes the rendered-doc inconsistency you found. **Phase 3** (Fix-or-Accept presentation + the drafted amendment) is the high-value UX step — do it next. **Phase 2** (actually *applying* the draft: in-PR suggestion or on-merge reconcile) last. Each phase ships independently and is testable on its own. Note: with this framing Phase 3 *drafts* the amendment and Phase 2 *applies* it — the human only ever Fixes or Accepts.

From c4d90aa74ecac592f083e9b996a5dc64835319f9 Mon Sep 17 00:00:00 2001
From: Gabor Bakos <gabor@bitraptors.com>
Date: Mon, 22 Jun 2026 14:10:50 +0200
Subject: [PATCH 11/15] docs: implementation plan for snapshot-vs-contract

Phase 1 (sync code-fold contract-readonly: gate _KIND_TARGET to mirror kinds +
byte-identity guardrail + rendered-doc audit + SKILL/tests), Phase 3 (review
drafts the consistent interlock amendment + Fix-or-Accept render + consistency
check), Phase 2 (apply the draft on Accept via in-PR suggestion or on-merge
reconcile). Grounded in sync.py _KIND_TARGET/fold-context/fold-apply and
intent_review.py. Ship order 1 -> 3 -> 2.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 ...hie-snapshot-vs-contract-implementation.md | 96 +++++++++++++++++++
 1 file changed, 96 insertions(+)
 create mode 100644 docs/archie-snapshot-vs-contract-implementation.md

diff --git a/docs/archie-snapshot-vs-contract-implementation.md b/docs/archie-snapshot-vs-contract-implementation.md
new file mode 100644
index 0000000..02f6bff
--- /dev/null
+++ b/docs/archie-snapshot-vs-contract-implementation.md
@@ -0,0 +1,96 @@
+# Snapshot vs. Contract — Implementation Plan
+
+- **Implements:** `docs/archie-snapshot-vs-contract-plan.md`.
+- **Goal, restated in your words:** baseline (rules+blueprint) vs branch (rules+blueprint) → flag the deviation → user **merges** (accept) or **fixes the code**. The one nuance: sync moves the *blueprint* but not the *rules*, so "accept" must also move the rules — drafted by the system, applied on merge.
+- **File-sync rule (CLAUDE.md):** every `archie/standalone/*.py` and `archie/assets/**` edit is mirrored to `npm-package/assets/`, then `python3 scripts/verify_sync.py`. Each milestone lists CANONICAL → COPY.
+
+Ship order: **Phase 1 → Phase 3 → Phase 2.** Each is independently shippable and testable.
+
+---
+
+## Phase 1 — sync's code-fold is contract-readonly (the core; ship first)
+
+**Why:** today `_KIND_TARGET` ([sync.py:413-426](archie/standalone/sync.py)) routes advisory claims into the contract (`rule`→`rules.json`, `decision`→`decisions`, `pitfall`→`pitfalls`+`findings.json`, `guideline`→`implementation_guidelines`). A code-fold should never silently move the law — that's what makes the deviation real and reliable.
+
+### M1.1 — Gate the fold to mirror-only
+- In `cmd_fold_context` ([sync.py:485](archie/standalone/sync.py)): emit fold edit-targets **only for descriptive kinds** (`behavior`, `structure`, `dataflow`, `data`, `tech`, `reference`). Advisory kinds (`decision`, `pitfall`, `guideline`, `rule`) are **not** emitted as edit targets — they stay in the ledger as `staged` and are reported to the dev as *proposed amendments*, not written.
+- Keep `_KIND_TARGET` as the source of truth but split it: `_MIRROR_KINDS` (foldable) vs `_CONTRACT_KINDS` (staged-only in a normal fold).
+- **Files:** CANONICAL `archie/standalone/sync.py` → COPY `npm-package/assets/sync.py`.
+- **Acceptance:** after a descriptive fold, `git diff` of `.archie/rules.json`, `blueprint.json` `domain_invariants`/`derived_invariants`/`decisions`/`pitfalls`, and `.archie/findings.json` is **empty**.
+
+### M1.2 — Guardrail: assert contract byte-identity
+- Extend the guardrail snapshot in `cmd_fold_context`/`cmd_fold_apply` ([sync.py:532, 560](archie/standalone/sync.py)) to capture a hash of `rules.json` + the contract blueprint sections **before** the agent edits, and in `fold-apply` **abort the render** if a descriptive fold changed them (mirrors the existing "dropped a top-level section" guard).
+- **Files:** same `sync.py` (CANONICAL → COPY).
+- **Acceptance:** a fold that touches a contract section is rejected with a clear message.
+
+### M1.3 — Rendered-doc consistency
+- Audit `renderer.generate_all` ([sync.py:607](archie/standalone/sync.py) calls it; logic in `renderer.py`): confirm which `.claude/rules/*.md` derive from `rules.json` (contract) vs from blueprint pattern/decision sections (mirror). Contract-derived docs must render from `rules.json` (unchanged) so they can't drift to match the mirror — the inconsistency seen in the cap test.
+- **Files:** `archie/standalone/renderer.py` (CANONICAL → COPY) if a split is needed; else just a test pinning it.
+- **Acceptance:** after a descriptive fold, every contract-derived `.claude/rules/*.md` is byte-identical.
+
+### M1.4 — SKILL instructions + tests
+- Rewrite `archie/assets/workflow/sync/SKILL.md` Step 4 "where edits land": the code-fold edits **mirror sections only**; a claim that would change the law is reported as a *proposed amendment*, never folded. (CANONICAL → COPY `npm-package/assets/workflow/sync/SKILL.md`.)
+- Tests (`tests/test_sync.py`): a cap-style change with a descriptive claim folds the mirror and leaves `rules.json`/invariants/contract-docs untouched; an advisory claim is recorded `staged`, not folded.
+- **Acceptance:** `pytest tests/test_sync.py` green; `verify_sync` green.
+
+---
+
+## Phase 3 — review drafts the amendment + presents Fix-or-Accept
+
+**Why:** for "accept" to mean something, the dev needs to see the drafted rule change. The review already separates changed vs retained rules ([intent_review.py](archie/standalone/intent_review.py)); this adds the draft + the two-move framing.
+
+### M3.1 — Draft the consistent amendment
+- For each deviation, compute the **interlock set**: the violated rule(s) + rules sharing `forced_by`/`enables`/keywords (e.g. `inv-002` → `der-001`/`der-005`/`tra-001`). Deterministic candidate scoping in the script; the model proposes the new text for each.
+- New `emit_findings` field per finding: `proposed_amendment: [{rule_id, current, proposed}]`.
+- **Files:** `archie/standalone/intent_review.py` (CANONICAL → COPY).
+- **Acceptance:** a cap deviation yields a draft covering all four interlocked rules with new values.
+
+### M3.2 — Render Fix-or-Accept
+- `render_comment`: each deviation shows the two moves + the drafted change:
+  *"The code now does 12; the contract says 7. **Fix** the code, or **Accept** to apply: `inv-002` 7→12, `der-001` 7→12, `der-005` 7→12, retire `tra-001`."*
+- **Acceptance:** comment renders the draft as an applyable block.
+
+### M3.3 — Consistency check (incomplete-amendment safety net)
+- If the branch already changed some contract rules but left an interlocked one, flag **inconsistent amendment** ("also update `der-001`") — this already half-exists (changed-vs-retained contradiction); make it explicit.
+- **Tests** (`tests/test_intent_review.py`): draft covers the interlock set; partial branch-amendment → inconsistency flag; clean branch-amendment → no flag.
+
+---
+
+## Phase 2 — apply the draft on Accept (novel; ship last)
+
+**Why:** the human only Fixes or Accepts; Accept must move the rules with no hand-editing. Two candidate mechanisms — pick one (see open question):
+
+### M2.1 — (Recommended) in-PR suggested change
+- The Action posts the drafted amendment as a **GitHub suggested change** on the `rules.json` lines (or a companion commit). "Accept" = apply the suggestion → the branch's `rules.json` now matches → merge accepts a consistent baseline. Keeps "merge = acceptance" literal.
+- Needs: stable line-anchoring of each rule in `rules.json` (it's structured JSON — anchor on the rule object). Falls back to a single "apply this patch" comment if line-level suggestions are infeasible.
+- **Files:** `archie/standalone/intent_review.py` (the comment/suggestion payload) → COPY.
+
+### M2.2 — (Alternative) on-merge reconcile
+- A second workflow on `push` to the base applies the last drafted amendment to `rules.json` on `main` and commits it. Simpler anchoring, but the law moves *after* merge (a beat later) and needs write-to-main perms.
+
+- **Acceptance:** Accept produces a consistent `rules.json` change with zero hand-editing; Fix leaves `rules.json` untouched; the next PR no longer re-flags the accepted change.
+
+---
+
+## Out of scope
+- Auto-deciding whether an amendment is *correct* (human's call on merge).
+- Commit/PR prose as an intent source (rejected — unreliable).
+- Layer-3 raw-code reading (eval-gated, separate).
+
+## Risks & mitigations
+| Risk | Mitigation |
+|---|---|
+| M1.1 breaks teams relying on advisory auto-fold | Advisory claims still recorded (`staged`) + surfaced; only the silent write stops. Document in SKILL + changelog. |
+| Interlock scoping misses a rule → incomplete draft | M3.3 consistency check flags it before Accept; conservative keyword+`forced_by`/`enables` walk. |
+| GitHub line-suggestions on JSON are fragile (M2.1) | Anchor on rule-object boundaries; fall back to a patch comment / M2.2. |
+| Renderer can't cleanly split contract vs mirror docs | M1.3 is an audit first; only split the renderer if needed. |
+
+## Open questions
+1. **Phase 2 mechanism:** in-PR suggestion (M2.1) vs on-merge reconcile (M2.2). Recommend M2.1.
+2. **Interlock computation:** deterministic graph walk over `forced_by`/`enables` only, or include keyword overlap? Start with the explicit links; add keywords if recall is low.
+3. **`data_models`:** mirror for shape changes, contract for a new persistence *guarantee* — where's the line? Decide in M1.1.
+
+## Sequencing & effort
+- **Phase 1** (M1.1–M1.4): the contract-readonly fold. Self-contained, the highest-leverage change, ships alone. *Largest single chunk, but bounded to `sync.py` + SKILL + tests.*
+- **Phase 3** (M3.1–M3.4): drafting + Fix-or-Accept rendering. Builds on the working review; medium.
+- **Phase 2** (M2.1): applying the draft. Smallest logic, most integration risk (GitHub suggestion mechanics) — do last, behind the others.

From e92aa6e5c4d39a829f65605fc2c9e5a376fba1ea Mon Sep 17 00:00:00 2001
From: Gabor Bakos <gabor@bitraptors.com>
Date: Mon, 22 Jun 2026 14:15:36 +0200
Subject: [PATCH 12/15] docs: scope snapshot-vs-contract plan to Phase 1 (defer
 2+3)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Goal narrowed to 'reliably see deviations on the PR'. The review already shows
them; the only remaining gap is Phase 1 — stop sync's code-fold from silently
moving the rules to match the code (which would hide a deviation). Drafting +
Fix-or-Accept + on-merge apply are deferred until the seeing-problems loop is solid.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 ...hie-snapshot-vs-contract-implementation.md | 102 +++++-------------
 1 file changed, 29 insertions(+), 73 deletions(-)

diff --git a/docs/archie-snapshot-vs-contract-implementation.md b/docs/archie-snapshot-vs-contract-implementation.md
index 02f6bff..86e193e 100644
--- a/docs/archie-snapshot-vs-contract-implementation.md
+++ b/docs/archie-snapshot-vs-contract-implementation.md
@@ -1,96 +1,52 @@
-# Snapshot vs. Contract — Implementation Plan
+# Snapshot vs. Contract — Implementation Plan (Phase 1 only)
 
 - **Implements:** `docs/archie-snapshot-vs-contract-plan.md`.
-- **Goal, restated in your words:** baseline (rules+blueprint) vs branch (rules+blueprint) → flag the deviation → user **merges** (accept) or **fixes the code**. The one nuance: sync moves the *blueprint* but not the *rules*, so "accept" must also move the rules — drafted by the system, applied on merge.
-- **File-sync rule (CLAUDE.md):** every `archie/standalone/*.py` and `archie/assets/**` edit is mirrored to `npm-package/assets/`, then `python3 scripts/verify_sync.py`. Each milestone lists CANONICAL → COPY.
-
-Ship order: **Phase 1 → Phase 3 → Phase 2.** Each is independently shippable and testable.
+- **Goal (scoped down):** *clearly and reliably see the deviations on the PR.* The review already posts clear, consolidated findings (proven on the cap PR). The one remaining gap: make sure a deviation can't be **hidden** by sync silently moving the rules to match the code.
+- **Deferred (revisit later):** drafting the rule amendment + "Fix or Accept" + applying it on merge. Not needed to *see* problems — only to *resolve* them. We'll evolve that once the seeing-problems loop is solid.
 
 ---
 
-## Phase 1 — sync's code-fold is contract-readonly (the core; ship first)
+## What already works (no action)
+
+The Intent Review Action diffs branch vs base, judges with one model call, and posts a consolidated FYI comment. The cap PR showed it works end to end. Nothing to do here.
+
+## The one change: Phase 1 — sync's code-fold can't move the rules
 
-**Why:** today `_KIND_TARGET` ([sync.py:413-426](archie/standalone/sync.py)) routes advisory claims into the contract (`rule`→`rules.json`, `decision`→`decisions`, `pitfall`→`pitfalls`+`findings.json`, `guideline`→`implementation_guidelines`). A code-fold should never silently move the law — that's what makes the deviation real and reliable.
+**Why:** today `_KIND_TARGET` ([sync.py:413-426](archie/standalone/sync.py)) lets a fold write the contract (`rule`→`rules.json`, `decision`→`decisions`, `pitfall`→`pitfalls`+`findings.json`, `guideline`→`implementation_guidelines`). If a code-fold ever moves the rules to match the code, the deviation vanishes and the PR shows nothing — a hidden problem. Phase 1 closes that.
 
 ### M1.1 — Gate the fold to mirror-only
-- In `cmd_fold_context` ([sync.py:485](archie/standalone/sync.py)): emit fold edit-targets **only for descriptive kinds** (`behavior`, `structure`, `dataflow`, `data`, `tech`, `reference`). Advisory kinds (`decision`, `pitfall`, `guideline`, `rule`) are **not** emitted as edit targets — they stay in the ledger as `staged` and are reported to the dev as *proposed amendments*, not written.
-- Keep `_KIND_TARGET` as the source of truth but split it: `_MIRROR_KINDS` (foldable) vs `_CONTRACT_KINDS` (staged-only in a normal fold).
+- `cmd_fold_context` ([sync.py:485](archie/standalone/sync.py)): emit fold edit-targets **only for descriptive kinds** (`behavior`, `structure`, `dataflow`, `data`, `tech`, `reference`). Advisory kinds (`decision`, `pitfall`, `guideline`, `rule`) stay `staged` in the ledger — recorded and surfaced to the dev, **never written** to the contract.
+- Split `_KIND_TARGET` into `_MIRROR_KINDS` (foldable) and `_CONTRACT_KINDS` (staged-only).
 - **Files:** CANONICAL `archie/standalone/sync.py` → COPY `npm-package/assets/sync.py`.
-- **Acceptance:** after a descriptive fold, `git diff` of `.archie/rules.json`, `blueprint.json` `domain_invariants`/`derived_invariants`/`decisions`/`pitfalls`, and `.archie/findings.json` is **empty**.
+- **Acceptance:** after a descriptive fold, `git diff` of `.archie/rules.json` + the contract blueprint sections (`domain_invariants`, `derived_invariants`, `decisions`, `pitfalls`) + `.archie/findings.json` is **empty**.
 
-### M1.2 — Guardrail: assert contract byte-identity
-- Extend the guardrail snapshot in `cmd_fold_context`/`cmd_fold_apply` ([sync.py:532, 560](archie/standalone/sync.py)) to capture a hash of `rules.json` + the contract blueprint sections **before** the agent edits, and in `fold-apply` **abort the render** if a descriptive fold changed them (mirrors the existing "dropped a top-level section" guard).
+### M1.2 — Guardrail: refuse a fold that touched the contract
+- In `cmd_fold_context`/`cmd_fold_apply` ([sync.py:532, 560](archie/standalone/sync.py)): snapshot a hash of `rules.json` + contract sections before the edit; in `fold-apply`, **abort the render** if a descriptive fold changed them (mirrors the existing dropped-section guard).
 - **Files:** same `sync.py` (CANONICAL → COPY).
-- **Acceptance:** a fold that touches a contract section is rejected with a clear message.
+- **Acceptance:** a fold that mutates a contract section is rejected with a clear message.
 
 ### M1.3 — Rendered-doc consistency
-- Audit `renderer.generate_all` ([sync.py:607](archie/standalone/sync.py) calls it; logic in `renderer.py`): confirm which `.claude/rules/*.md` derive from `rules.json` (contract) vs from blueprint pattern/decision sections (mirror). Contract-derived docs must render from `rules.json` (unchanged) so they can't drift to match the mirror — the inconsistency seen in the cap test.
-- **Files:** `archie/standalone/renderer.py` (CANONICAL → COPY) if a split is needed; else just a test pinning it.
-- **Acceptance:** after a descriptive fold, every contract-derived `.claude/rules/*.md` is byte-identical.
+- Audit `renderer.generate_all` (called at [sync.py:607](archie/standalone/sync.py)): the `.claude/rules/*.md` that derive from `rules.json` must render from `rules.json` (unchanged), not from the mirror — so they can't drift to "12" while the rule says "7" (the inconsistency in the cap test).
+- **Files:** `archie/standalone/renderer.py` (CANONICAL → COPY) only if a split is needed; otherwise a test pinning current behavior.
+- **Acceptance:** after a descriptive fold, contract-derived `.claude/rules/*.md` are byte-identical.
 
 ### M1.4 — SKILL instructions + tests
-- Rewrite `archie/assets/workflow/sync/SKILL.md` Step 4 "where edits land": the code-fold edits **mirror sections only**; a claim that would change the law is reported as a *proposed amendment*, never folded. (CANONICAL → COPY `npm-package/assets/workflow/sync/SKILL.md`.)
-- Tests (`tests/test_sync.py`): a cap-style change with a descriptive claim folds the mirror and leaves `rules.json`/invariants/contract-docs untouched; an advisory claim is recorded `staged`, not folded.
-- **Acceptance:** `pytest tests/test_sync.py` green; `verify_sync` green.
-
----
-
-## Phase 3 — review drafts the amendment + presents Fix-or-Accept
-
-**Why:** for "accept" to mean something, the dev needs to see the drafted rule change. The review already separates changed vs retained rules ([intent_review.py](archie/standalone/intent_review.py)); this adds the draft + the two-move framing.
-
-### M3.1 — Draft the consistent amendment
-- For each deviation, compute the **interlock set**: the violated rule(s) + rules sharing `forced_by`/`enables`/keywords (e.g. `inv-002` → `der-001`/`der-005`/`tra-001`). Deterministic candidate scoping in the script; the model proposes the new text for each.
-- New `emit_findings` field per finding: `proposed_amendment: [{rule_id, current, proposed}]`.
-- **Files:** `archie/standalone/intent_review.py` (CANONICAL → COPY).
-- **Acceptance:** a cap deviation yields a draft covering all four interlocked rules with new values.
-
-### M3.2 — Render Fix-or-Accept
-- `render_comment`: each deviation shows the two moves + the drafted change:
-  *"The code now does 12; the contract says 7. **Fix** the code, or **Accept** to apply: `inv-002` 7→12, `der-001` 7→12, `der-005` 7→12, retire `tra-001`."*
-- **Acceptance:** comment renders the draft as an applyable block.
-
-### M3.3 — Consistency check (incomplete-amendment safety net)
-- If the branch already changed some contract rules but left an interlocked one, flag **inconsistent amendment** ("also update `der-001`") — this already half-exists (changed-vs-retained contradiction); make it explicit.
-- **Tests** (`tests/test_intent_review.py`): draft covers the interlock set; partial branch-amendment → inconsistency flag; clean branch-amendment → no flag.
+- `archie/assets/workflow/sync/SKILL.md` Step 4 "where edits land": the code-fold edits **mirror sections only**; a law-changing claim is reported as a *proposed amendment* (deferred work), never folded. (CANONICAL → COPY `npm-package/assets/workflow/sync/SKILL.md`.)
+- Tests (`tests/test_sync.py`): a cap-style descriptive fold updates the mirror and leaves `rules.json`/invariants/contract-docs untouched; an advisory claim is recorded `staged`, not folded.
+- **Acceptance:** `pytest tests/test_sync.py` green; `python3 scripts/verify_sync.py` green.
 
 ---
 
-## Phase 2 — apply the draft on Accept (novel; ship last)
-
-**Why:** the human only Fixes or Accepts; Accept must move the rules with no hand-editing. Two candidate mechanisms — pick one (see open question):
-
-### M2.1 — (Recommended) in-PR suggested change
-- The Action posts the drafted amendment as a **GitHub suggested change** on the `rules.json` lines (or a companion commit). "Accept" = apply the suggestion → the branch's `rules.json` now matches → merge accepts a consistent baseline. Keeps "merge = acceptance" literal.
-- Needs: stable line-anchoring of each rule in `rules.json` (it's structured JSON — anchor on the rule object). Falls back to a single "apply this patch" comment if line-level suggestions are infeasible.
-- **Files:** `archie/standalone/intent_review.py` (the comment/suggestion payload) → COPY.
-
-### M2.2 — (Alternative) on-merge reconcile
-- A second workflow on `push` to the base applies the last drafted amendment to `rules.json` on `main` and commits it. Simpler anchoring, but the law moves *after* merge (a beat later) and needs write-to-main perms.
-
-- **Acceptance:** Accept produces a consistent `rules.json` change with zero hand-editing; Fix leaves `rules.json` untouched; the next PR no longer re-flags the accepted change.
-
----
-
-## Out of scope
-- Auto-deciding whether an amendment is *correct* (human's call on merge).
-- Commit/PR prose as an intent source (rejected — unreliable).
-- Layer-3 raw-code reading (eval-gated, separate).
-
 ## Risks & mitigations
 | Risk | Mitigation |
 |---|---|
-| M1.1 breaks teams relying on advisory auto-fold | Advisory claims still recorded (`staged`) + surfaced; only the silent write stops. Document in SKILL + changelog. |
-| Interlock scoping misses a rule → incomplete draft | M3.3 consistency check flags it before Accept; conservative keyword+`forced_by`/`enables` walk. |
-| GitHub line-suggestions on JSON are fragile (M2.1) | Anchor on rule-object boundaries; fall back to a patch comment / M2.2. |
-| Renderer can't cleanly split contract vs mirror docs | M1.3 is an audit first; only split the renderer if needed. |
+| Teams relied on advisory auto-fold into the contract | Advisory claims still recorded (`staged`) + surfaced; only the *silent write* stops. Note in SKILL + changelog. |
+| `data_models`: shape (mirror) vs a new persistence *guarantee* (contract) | Treat as mirror by default; flag the guarantee edge case in M1.1. |
+| Renderer can't cleanly separate contract-docs from mirror-docs | M1.3 is an audit first; only split the renderer if the audit shows real coupling. |
 
-## Open questions
-1. **Phase 2 mechanism:** in-PR suggestion (M2.1) vs on-merge reconcile (M2.2). Recommend M2.1.
-2. **Interlock computation:** deterministic graph walk over `forced_by`/`enables` only, or include keyword overlap? Start with the explicit links; add keywords if recall is low.
-3. **`data_models`:** mirror for shape changes, contract for a new persistence *guarantee* — where's the line? Decide in M1.1.
+## Out of scope (for now)
+- Drafting / applying rule amendments, "Fix or Accept" UX, on-merge reconcile — **deferred**.
+- Auto-deciding violation vs. evolution, commit-prose intent, Layer-3 raw code — unchanged from prior scope.
 
-## Sequencing & effort
-- **Phase 1** (M1.1–M1.4): the contract-readonly fold. Self-contained, the highest-leverage change, ships alone. *Largest single chunk, but bounded to `sync.py` + SKILL + tests.*
-- **Phase 3** (M3.1–M3.4): drafting + Fix-or-Accept rendering. Builds on the working review; medium.
-- **Phase 2** (M2.1): applying the draft. Smallest logic, most integration risk (GitHub suggestion mechanics) — do last, behind the others.
+## Done = 
+A descriptive `/archie-sync` fold can never alter the contract, so every code-vs-law deviation reliably reaches the PR. Tests + `verify_sync` green.

From d61774cb5ef51d8dc68f94ded46582d8f07ac4f1 Mon Sep 17 00:00:00 2001
From: Gabor Bakos <gabor@bitraptors.com>
Date: Mon, 22 Jun 2026 14:26:15 +0200
Subject: [PATCH 13/15] =?UTF-8?q?feat(sync):=20Phase=201=20=E2=80=94=20cod?=
 =?UTF-8?q?e-fold=20is=20contract-readonly=20(snapshot=20vs=20contract)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A code-fold must never silently move the law, or a real code-vs-contract deviation
would be hidden from the PR Intent Review.

- _classify: advisory kinds (decision/pitfall/rule/guideline) are ALWAYS `staged`,
  never eligible/folded — they're the contract. Only the descriptive mirror folds.
- fold-context: surfaces advisory claims as `staged_amendments` (proposed, not
  folded) and snapshots a contract fingerprint (invariant sections + rules.json +
  platform_rules.json).
- fold-apply: refuses (before render) any fold that changed the contract fingerprint.
- SKILL.md Step 4: edit the mirror only; advisory = proposed amendments.

Tests: advisory-always-staged, advisory-not-a-fold-target, contract guardrail
aborts on rules.json and invariant edits; updated the fold tests that encoded the
old advisory-folds behavior. test_sync 21 pass; full suite 1028 passed/1 skipped;
verify_sync green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 archie/assets/workflow/sync/SKILL.md      | 12 +++-
 archie/standalone/sync.py                 | 81 +++++++++++++++++----
 npm-package/assets/sync.py                | 81 +++++++++++++++++----
 npm-package/assets/workflow/sync/SKILL.md | 12 +++-
 tests/test_sync.py                        | 87 +++++++++++++++++++----
 5 files changed, 228 insertions(+), 45 deletions(-)

diff --git a/archie/assets/workflow/sync/SKILL.md b/archie/assets/workflow/sync/SKILL.md
index a985ca7..09ea3df 100644
--- a/archie/assets/workflow/sync/SKILL.md
+++ b/archie/assets/workflow/sync/SKILL.md
@@ -77,13 +77,19 @@ For each statement, read the target section of the CURRENT snapshot and pick ONE
 - **ADD** — not represented → add it to the right section.
 - **REMOVE** — the section describes behavior the code no longer has → remove/correct it.
 
-Where edits land (descriptive = the headline):
+Where edits land — **the descriptive MIRROR only** (what the code is now):
 - `behavior`/`structure` → `.archie/blueprint.json` `components[]` (responsibilities) / `communication`
 - `dataflow` → `communication`, `architecture_diagram`
 - `data` → `data_models` / `persistence_stores` / `data_overview`
 - `tech` → `technology` · `reference` → `quick_reference`
-- advisory: `decision` → `decisions` · `pitfall` → `pitfalls` + a verifier entry in
-  `.archie/findings.json` · `rule` → `.archie/rules.json`
+
+**Do NOT touch the CONTRACT (the law).** Advisory claims (`decision`/`pitfall`/`rule`/
+`guideline`) are recorded `staged` and surface under `staged_amendments` in `fold-context` —
+they are PROPOSED changes for a separate, deliberate decision, NOT something a code-fold
+applies. A fold must never edit `.archie/rules.json`, `domain_invariants`,
+`derived_invariants`, `decisions`, or `pitfalls`; **`fold-apply` refuses a render that moved
+them.** (Why: the PR Intent Review catches code-vs-law drift — if a fold silently moved the
+law to match the code, the deviation would be hidden.)
 
 Then **reconcile the intent layer**: for each touched folder in `intent_files`, update the
 **descriptive (AI-authored) section** of that folder's CLAUDE.md to match the code now —
diff --git a/archie/standalone/sync.py b/archie/standalone/sync.py
index 1de49f7..6d13bb5 100644
--- a/archie/standalone/sync.py
+++ b/archie/standalone/sync.py
@@ -27,6 +27,7 @@
 """
 from __future__ import annotations
 
+import hashlib
 import json
 import re
 import subprocess
@@ -236,7 +237,16 @@ def _evidence_in_diff(evidence_files: list[str], changed_files: list[str], affec
 
 
 def _classify(claim: dict, changed_files: list[str], affected: list[str]) -> str:
-    """eligible = confident + non-reconstructed + evidenced inside the diff; else staged."""
+    """eligible = confident + non-reconstructed + evidenced inside the diff; else staged.
+
+    Snapshot-vs-contract (Phase 1): ADVISORY kinds (decision/pitfall/rule/guideline) are
+    the *contract* (the law). A code-fold must never silently move the law, or a real
+    deviation would be hidden from the PR review — so advisory claims are ALWAYS `staged`
+    (recorded + surfaced as proposed amendments), never `eligible`/folded. Only the
+    descriptive *mirror* (what the code is now) folds automatically.
+    """
+    if claim.get("kind") in _ADVISORY_KINDS:
+        return "staged"
     if claim["reconstructed"]:
         return "staged"
     if claim["confidence"] not in ("medium", "high"):
@@ -425,6 +435,30 @@ def cmd_list(root: Path, as_json: bool) -> int:
     "rule":      {"sections": [], "edit_file": ".archie/rules.json"},
 }
 
+# Snapshot-vs-contract guardrail (Phase 1): the "contract" (the law) a code-fold must
+# never move. The invariant sections + the rule files. (decisions/pitfalls carry mixed
+# descriptive prose, so they're governed by the advisory->staged gate in _classify, not
+# this byte-level fingerprint.)
+_CONTRACT_SECTIONS = ("domain_invariants", "derived_invariants", "unenforced_invariants")
+_CONTRACT_FILES = ("rules.json", "platform_rules.json")
+
+
+def _contract_fingerprint(root: Path, bp: dict) -> str:
+    """Stable hash of the contract (invariant sections + rule files); used to refuse a
+    fold-apply that moved the law."""
+    h = hashlib.sha256()
+    h.update(json.dumps({k: bp.get(k) for k in _CONTRACT_SECTIONS},
+                        sort_keys=True, ensure_ascii=False).encode("utf-8"))
+    for fname in _CONTRACT_FILES:
+        p = root / ".archie" / fname
+        h.update(b"\x00")
+        if p.exists():
+            try:
+                h.update(p.read_bytes())
+            except OSError:
+                pass
+    return h.hexdigest()
+
 
 def _newest_change(root: Path) -> Path | None:
     changes_dir = _changes_dir(root)
@@ -492,6 +526,15 @@ def cmd_fold_context(root: Path, change_file: str | None) -> int:
         print(json.dumps({"ok": False, "error": "no change record found"}))
         return 1
     eligible = [c for c in data.get("claims", []) if c.get("status") == "eligible"]
+    # Advisory claims are the CONTRACT (the law) — a code-fold never writes them. They
+    # surface as PROPOSED amendments for a separate, deliberate decision (not folded).
+    staged_amendments = [
+        {"claim_id": c.get("id"), "kind": c.get("kind") or c.get("section"),
+         "statement": c.get("statement") or c.get("title"),
+         "evidence_files": c.get("evidence_files", [])}
+        for c in data.get("claims", [])
+        if (c.get("kind") or c.get("section")) in _ADVISORY_KINDS
+    ]
     archie = root / ".archie"
     bp_path = archie / "blueprint.json"
     bp = {}
@@ -529,9 +572,12 @@ def cmd_fold_context(root: Path, change_file: str | None) -> int:
         if cf.exists():
             intent_files.append(str(cf.relative_to(root)))
 
-    # Persist a guardrail snapshot so fold-apply can refuse a render that dropped
-    # a whole top-level section.
-    data["fold_guardrail"] = {"blueprint_top_level_keys": sorted(bp.keys())}
+    # Persist a guardrail snapshot so fold-apply can refuse a render that dropped a whole
+    # top-level section OR moved the contract (the law) during a descriptive fold.
+    data["fold_guardrail"] = {
+        "blueprint_top_level_keys": sorted(bp.keys()),
+        "contract_fingerprint": _contract_fingerprint(root, bp),
+    }
     _persist_change(root, path, data)
 
     print(json.dumps({
@@ -539,19 +585,20 @@ def cmd_fold_context(root: Path, change_file: str | None) -> int:
         "change_file": str(path.relative_to(root)) if path.is_relative_to(root) else str(path),
         "eligible_count": len(eligible),
         "targets": targets,
+        "staged_amendments": staged_amendments,
         "intent_files": intent_files,
         "instructions": (
             "RECONCILE each statement into the snapshot — do not just append. For each "
-            "target: read ONLY the named blueprint_sections (the descriptive snapshot of "
+            "target: read ONLY the named blueprint_sections (the descriptive MIRROR of "
             "what the code IS) and the evidence files, then pick ONE op: NO-OP (already "
             "accurately described — common), UPDATE (described but now wrong — correct in "
-            "place), ADD (new), REMOVE (code dropped it). Descriptive kinds "
-            "(behavior/structure/dataflow/data/tech/reference) are the point; advisory "
-            "kinds (decision/pitfall/rule) only when genuinely warranted. Edit "
-            "blueprint.json (source of truth); rule -> rules.json; pitfall -> also "
-            "findings.json. Then reconcile the DESCRIPTIVE section of each touched "
-            "per-folder CLAUDE.md in `intent_files` (direct edit — these are the folder "
-            "snapshots). Finally run: sync.py fold-apply ."
+            "place), ADD (new), REMOVE (code dropped it). Edit ONLY descriptive mirror "
+            "sections of blueprint.json. DO NOT edit the CONTRACT — rules.json, "
+            "domain_invariants, derived_invariants, decisions, or pitfalls. Advisory "
+            "claims are listed under `staged_amendments` as PROPOSED contract changes; "
+            "they must NOT be folded — changing the law is a separate, deliberate step. "
+            "Then reconcile the DESCRIPTIVE section of each touched per-folder CLAUDE.md "
+            "in `intent_files` (direct edit). Finally run: sync.py fold-apply ."
         ),
     }, indent=2))
     return 0
@@ -582,6 +629,16 @@ def cmd_fold_apply(root: Path, change_file: str | None) -> int:
         print(json.dumps({"ok": False, "error": f"guardrail tripped — blueprint top-level sections dropped: {missing}"}))
         return 1
 
+    # Contract guardrail (Phase 1): a code-fold must not move the law. Checked BEFORE the
+    # render/normalize so normalization can neither mask nor falsely trip it.
+    expected_fp = (data.get("fold_guardrail") or {}).get("contract_fingerprint")
+    if expected_fp is not None and _contract_fingerprint(root, bp) != expected_fp:
+        print(json.dumps({"ok": False, "error": (
+            "guardrail tripped — a code-fold changed the contract (rules.json / "
+            "invariants). The contract (the law) changes only by a deliberate amendment, "
+            "never a sync fold. Revert the contract edits, then re-run fold-apply.")}))
+        return 1
+
     sys.path.insert(0, str(_SCRIPT_DIR))
     try:
         from _common import normalize_blueprint  # noqa: E402
diff --git a/npm-package/assets/sync.py b/npm-package/assets/sync.py
index 1de49f7..6d13bb5 100644
--- a/npm-package/assets/sync.py
+++ b/npm-package/assets/sync.py
@@ -27,6 +27,7 @@
 """
 from __future__ import annotations
 
+import hashlib
 import json
 import re
 import subprocess
@@ -236,7 +237,16 @@ def _evidence_in_diff(evidence_files: list[str], changed_files: list[str], affec
 
 
 def _classify(claim: dict, changed_files: list[str], affected: list[str]) -> str:
-    """eligible = confident + non-reconstructed + evidenced inside the diff; else staged."""
+    """eligible = confident + non-reconstructed + evidenced inside the diff; else staged.
+
+    Snapshot-vs-contract (Phase 1): ADVISORY kinds (decision/pitfall/rule/guideline) are
+    the *contract* (the law). A code-fold must never silently move the law, or a real
+    deviation would be hidden from the PR review — so advisory claims are ALWAYS `staged`
+    (recorded + surfaced as proposed amendments), never `eligible`/folded. Only the
+    descriptive *mirror* (what the code is now) folds automatically.
+    """
+    if claim.get("kind") in _ADVISORY_KINDS:
+        return "staged"
     if claim["reconstructed"]:
         return "staged"
     if claim["confidence"] not in ("medium", "high"):
@@ -425,6 +435,30 @@ def cmd_list(root: Path, as_json: bool) -> int:
     "rule":      {"sections": [], "edit_file": ".archie/rules.json"},
 }
 
+# Snapshot-vs-contract guardrail (Phase 1): the "contract" (the law) a code-fold must
+# never move. The invariant sections + the rule files. (decisions/pitfalls carry mixed
+# descriptive prose, so they're governed by the advisory->staged gate in _classify, not
+# this byte-level fingerprint.)
+_CONTRACT_SECTIONS = ("domain_invariants", "derived_invariants", "unenforced_invariants")
+_CONTRACT_FILES = ("rules.json", "platform_rules.json")
+
+
+def _contract_fingerprint(root: Path, bp: dict) -> str:
+    """Stable hash of the contract (invariant sections + rule files); used to refuse a
+    fold-apply that moved the law."""
+    h = hashlib.sha256()
+    h.update(json.dumps({k: bp.get(k) for k in _CONTRACT_SECTIONS},
+                        sort_keys=True, ensure_ascii=False).encode("utf-8"))
+    for fname in _CONTRACT_FILES:
+        p = root / ".archie" / fname
+        h.update(b"\x00")
+        if p.exists():
+            try:
+                h.update(p.read_bytes())
+            except OSError:
+                pass
+    return h.hexdigest()
+
 
 def _newest_change(root: Path) -> Path | None:
     changes_dir = _changes_dir(root)
@@ -492,6 +526,15 @@ def cmd_fold_context(root: Path, change_file: str | None) -> int:
         print(json.dumps({"ok": False, "error": "no change record found"}))
         return 1
     eligible = [c for c in data.get("claims", []) if c.get("status") == "eligible"]
+    # Advisory claims are the CONTRACT (the law) — a code-fold never writes them. They
+    # surface as PROPOSED amendments for a separate, deliberate decision (not folded).
+    staged_amendments = [
+        {"claim_id": c.get("id"), "kind": c.get("kind") or c.get("section"),
+         "statement": c.get("statement") or c.get("title"),
+         "evidence_files": c.get("evidence_files", [])}
+        for c in data.get("claims", [])
+        if (c.get("kind") or c.get("section")) in _ADVISORY_KINDS
+    ]
     archie = root / ".archie"
     bp_path = archie / "blueprint.json"
     bp = {}
@@ -529,9 +572,12 @@ def cmd_fold_context(root: Path, change_file: str | None) -> int:
         if cf.exists():
             intent_files.append(str(cf.relative_to(root)))
 
-    # Persist a guardrail snapshot so fold-apply can refuse a render that dropped
-    # a whole top-level section.
-    data["fold_guardrail"] = {"blueprint_top_level_keys": sorted(bp.keys())}
+    # Persist a guardrail snapshot so fold-apply can refuse a render that dropped a whole
+    # top-level section OR moved the contract (the law) during a descriptive fold.
+    data["fold_guardrail"] = {
+        "blueprint_top_level_keys": sorted(bp.keys()),
+        "contract_fingerprint": _contract_fingerprint(root, bp),
+    }
     _persist_change(root, path, data)
 
     print(json.dumps({
@@ -539,19 +585,20 @@ def cmd_fold_context(root: Path, change_file: str | None) -> int:
         "change_file": str(path.relative_to(root)) if path.is_relative_to(root) else str(path),
         "eligible_count": len(eligible),
         "targets": targets,
+        "staged_amendments": staged_amendments,
         "intent_files": intent_files,
         "instructions": (
             "RECONCILE each statement into the snapshot — do not just append. For each "
-            "target: read ONLY the named blueprint_sections (the descriptive snapshot of "
+            "target: read ONLY the named blueprint_sections (the descriptive MIRROR of "
             "what the code IS) and the evidence files, then pick ONE op: NO-OP (already "
             "accurately described — common), UPDATE (described but now wrong — correct in "
-            "place), ADD (new), REMOVE (code dropped it). Descriptive kinds "
-            "(behavior/structure/dataflow/data/tech/reference) are the point; advisory "
-            "kinds (decision/pitfall/rule) only when genuinely warranted. Edit "
-            "blueprint.json (source of truth); rule -> rules.json; pitfall -> also "
-            "findings.json. Then reconcile the DESCRIPTIVE section of each touched "
-            "per-folder CLAUDE.md in `intent_files` (direct edit — these are the folder "
-            "snapshots). Finally run: sync.py fold-apply ."
+            "place), ADD (new), REMOVE (code dropped it). Edit ONLY descriptive mirror "
+            "sections of blueprint.json. DO NOT edit the CONTRACT — rules.json, "
+            "domain_invariants, derived_invariants, decisions, or pitfalls. Advisory "
+            "claims are listed under `staged_amendments` as PROPOSED contract changes; "
+            "they must NOT be folded — changing the law is a separate, deliberate step. "
+            "Then reconcile the DESCRIPTIVE section of each touched per-folder CLAUDE.md "
+            "in `intent_files` (direct edit). Finally run: sync.py fold-apply ."
         ),
     }, indent=2))
     return 0
@@ -582,6 +629,16 @@ def cmd_fold_apply(root: Path, change_file: str | None) -> int:
         print(json.dumps({"ok": False, "error": f"guardrail tripped — blueprint top-level sections dropped: {missing}"}))
         return 1
 
+    # Contract guardrail (Phase 1): a code-fold must not move the law. Checked BEFORE the
+    # render/normalize so normalization can neither mask nor falsely trip it.
+    expected_fp = (data.get("fold_guardrail") or {}).get("contract_fingerprint")
+    if expected_fp is not None and _contract_fingerprint(root, bp) != expected_fp:
+        print(json.dumps({"ok": False, "error": (
+            "guardrail tripped — a code-fold changed the contract (rules.json / "
+            "invariants). The contract (the law) changes only by a deliberate amendment, "
+            "never a sync fold. Revert the contract edits, then re-run fold-apply.")}))
+        return 1
+
     sys.path.insert(0, str(_SCRIPT_DIR))
     try:
         from _common import normalize_blueprint  # noqa: E402
diff --git a/npm-package/assets/workflow/sync/SKILL.md b/npm-package/assets/workflow/sync/SKILL.md
index a985ca7..09ea3df 100644
--- a/npm-package/assets/workflow/sync/SKILL.md
+++ b/npm-package/assets/workflow/sync/SKILL.md
@@ -77,13 +77,19 @@ For each statement, read the target section of the CURRENT snapshot and pick ONE
 - **ADD** — not represented → add it to the right section.
 - **REMOVE** — the section describes behavior the code no longer has → remove/correct it.
 
-Where edits land (descriptive = the headline):
+Where edits land — **the descriptive MIRROR only** (what the code is now):
 - `behavior`/`structure` → `.archie/blueprint.json` `components[]` (responsibilities) / `communication`
 - `dataflow` → `communication`, `architecture_diagram`
 - `data` → `data_models` / `persistence_stores` / `data_overview`
 - `tech` → `technology` · `reference` → `quick_reference`
-- advisory: `decision` → `decisions` · `pitfall` → `pitfalls` + a verifier entry in
-  `.archie/findings.json` · `rule` → `.archie/rules.json`
+
+**Do NOT touch the CONTRACT (the law).** Advisory claims (`decision`/`pitfall`/`rule`/
+`guideline`) are recorded `staged` and surface under `staged_amendments` in `fold-context` —
+they are PROPOSED changes for a separate, deliberate decision, NOT something a code-fold
+applies. A fold must never edit `.archie/rules.json`, `domain_invariants`,
+`derived_invariants`, `decisions`, or `pitfalls`; **`fold-apply` refuses a render that moved
+them.** (Why: the PR Intent Review catches code-vs-law drift — if a fold silently moved the
+law to match the code, the deviation would be hidden.)
 
 Then **reconcile the intent layer**: for each touched folder in `intent_files`, update the
 **descriptive (AI-authored) section** of that folder's CLAUDE.md to match the code now —
diff --git a/tests/test_sync.py b/tests/test_sync.py
index 3ccea5d..a50c28a 100644
--- a/tests/test_sync.py
+++ b/tests/test_sync.py
@@ -293,19 +293,20 @@ def test_fold_context_resolves_scope(tmp_path, capsys):
     rc = sync.main(["sync.py", "fold-context", str(root)])
     out = json.loads(capsys.readouterr().out)
     assert rc == 0 and out["ok"]
-    assert out["eligible_count"] == 2
+    # advisory 'rule' is now staged (contract), so only the descriptive claim folds
+    assert out["eligible_count"] == 1
     by = {t["kind"]: t for t in out["targets"]}
-    # descriptive kind is the default: behavior -> components/communication, not rules
+    assert "rule" not in by                       # advisory is NOT a fold target
     assert by["behavior"]["edit_file"].endswith("blueprint.json")
     assert by["behavior"]["blueprint_sections"] == ["components", "communication"]
     assert by["behavior"]["advisory"] is False
-    # advisory rule routes to rules.json
-    assert by["rule"]["edit_file"].endswith("rules.json")
-    assert by["rule"]["advisory"] is True
+    # the rule surfaces as a PROPOSED amendment, not folded
+    assert "rule" in {a["kind"] for a in out["staged_amendments"]}
     assert "app/CLAUDE.md" in out["intent_files"]
-    # guardrail snapshot persisted into the change record
+    # guardrail snapshot persisted into the change record (keys + contract fingerprint)
     rec = json.loads((archie / "changes" / "latest.json").read_text())
     assert "blueprint_top_level_keys" in rec["fold_guardrail"]
+    assert "contract_fingerprint" in rec["fold_guardrail"]
 
 
 def test_fold_context_intent_files_are_leaf_scoped(tmp_path, capsys):
@@ -336,27 +337,83 @@ def test_fold_context_intent_files_are_leaf_scoped(tmp_path, capsys):
     assert "a/CLAUDE.md" not in out["intent_files"]     # NOT the ancestor
 
 
-def test_fold_context_pitfall_also_updates_findings(tmp_path, capsys):
+def test_fold_context_advisory_is_staged_not_folded(tmp_path, capsys):
+    # Advisory kinds (pitfall/rule/decision/guideline) are the CONTRACT — never a fold
+    # target. They surface as proposed amendments; the law changes only deliberately.
     root, archie = _setup_foldable(tmp_path, capsys, [
         _claim(kind="pitfall", statement="P", evidence=["app/Main.kt"], confidence="high"),
     ])
     rc = sync.main(["sync.py", "fold-context", str(root)])
     out = json.loads(capsys.readouterr().out)
-    t = out["targets"][0]
-    assert t["kind"] == "pitfall"
-    assert t["blueprint_sections"] == ["pitfalls"]
-    assert t["also_update"].endswith("findings.json")
-    assert t["advisory"] is True
+    assert rc == 0 and out["ok"]
+    assert out["eligible_count"] == 0
+    assert out["targets"] == []
+    assert [a["kind"] for a in out["staged_amendments"]] == ["pitfall"]
+
+
+def test_advisory_kinds_always_staged(tmp_path, capsys):
+    root = _init_repo(tmp_path)
+    _stage_change(root, "app/Main.kt")
+    claims = [_claim(kind=k, statement=f"adv {k}", evidence=["app/Main.kt"], confidence="high")
+              for k in ("decision", "pitfall", "rule", "guideline")]
+    claims.append(_claim(kind="behavior", statement="desc one", evidence=["app/Main.kt"], confidence="high"))
+    res = _record(root, _write_payload(tmp_path, claims), capsys)
+    assert res["eligible"] == 1 and res["staged"] == 4  # only the descriptive folds
+    rec = json.loads((root / ".archie" / "changes" / "latest.json").read_text())
+    by = {c["statement"]: c["status"] for c in rec["claims"]}
+    for k in ("decision", "pitfall", "rule", "guideline"):
+        assert by[f"adv {k}"] == "staged"
+    assert by["desc one"] == "eligible"
+
+
+def test_fold_apply_contract_guardrail_aborts_on_rules_edit(tmp_path, capsys):
+    # A fold that moves the LAW (rules.json) is refused — the deviation must reach the PR.
+    root, archie = _setup_foldable(tmp_path, capsys, [
+        _claim(kind="behavior", statement="desc", evidence=["app/Main.kt"], confidence="high"),
+    ])
+    (archie / "rules.json").write_text(json.dumps({"rules": [{"id": "r1", "description": "old"}]}))
+    sync.main(["sync.py", "fold-context", str(root)]); capsys.readouterr()
+    # Illegal: a code-fold rewrote the contract.
+    (archie / "rules.json").write_text(json.dumps({"rules": [{"id": "r1", "description": "CHANGED"}]}))
+    rc = sync.main(["sync.py", "fold-apply", str(root)])
+    out = json.loads(capsys.readouterr().out)
+    assert rc == 1 and out["ok"] is False
+    assert "contract" in out["error"].lower()
+    rec = json.loads((archie / "changes" / "latest.json").read_text())
+    assert rec.get("folded") in (False, None)
+
+
+def test_fold_apply_contract_guardrail_aborts_on_invariant_edit(tmp_path, capsys):
+    root = _init_repo(tmp_path)
+    archie = root / ".archie"
+    archie.mkdir()
+    bp = _minimal_blueprint()
+    bp["domain_invariants"] = [{"id": "inv-1", "invariant": "must hold"}]
+    (archie / "blueprint.json").write_text(json.dumps(bp))
+    (root / "app").mkdir()
+    (root / "app" / "CLAUDE.md").write_text("# app\n")
+    _stage_change(root, "app/Main.kt")
+    _record(root, _write_payload(tmp_path, [
+        _claim(kind="behavior", statement="d", evidence=["app/Main.kt"], confidence="high")]), capsys)
+    capsys.readouterr()
+    sync.main(["sync.py", "fold-context", str(root)]); capsys.readouterr()
+    # Illegal: weaken an invariant during the fold.
+    bp2 = json.loads((archie / "blueprint.json").read_text())
+    bp2["domain_invariants"][0]["invariant"] = "WEAKENED"
+    (archie / "blueprint.json").write_text(json.dumps(bp2))
+    rc = sync.main(["sync.py", "fold-apply", str(root)])
+    out = json.loads(capsys.readouterr().out)
+    assert rc == 1 and "contract" in out["error"].lower()
 
 
 def test_fold_apply_renders_and_marks_folded(tmp_path, capsys):
     root, archie = _setup_foldable(tmp_path, capsys, [
-        _claim(kind="pitfall", statement="P", evidence=["app/Main.kt"], confidence="high"),
+        _claim(kind="behavior", statement="X now does Y", evidence=["app/Main.kt"], confidence="high"),
     ])
     sync.main(["sync.py", "fold-context", str(root)]); capsys.readouterr()
-    # Simulate the AI fold: add a pitfall to the blueprint (source of truth).
+    # Simulate the AI fold: update a descriptive MIRROR section (not the contract).
     bp = json.loads((archie / "blueprint.json").read_text())
-    bp["pitfalls"].append({"id": "pf_new", "problem_statement": "P", "evidence": []})
+    bp["components"]["components"].append({"name": "X", "responsibilities": ["does Y"]})
     (archie / "blueprint.json").write_text(json.dumps(bp))
 
     rc = sync.main(["sync.py", "fold-apply", str(root)])

From 746df8010523e6e44299c3f8b594f4602bdbf690 Mon Sep 17 00:00:00 2001
From: Gabor Bakos <gabor@bitraptors.com>
Date: Mon, 22 Jun 2026 14:31:20 +0200
Subject: [PATCH 14/15] fix(sync): surface deliberate contract changes instead
 of blocking them
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Rules legitimately change during real work — the guardrail must not refuse them.
fold-apply no longer aborts when a fold also changed the contract; it proceeds and
reports contract_changed + a note, so the law can move DELIBERATELY but never
SILENTLY. advisory->staged still stops AUTOMATIC contract moves; deep-scan and
deliberate edits change rules as before. SKILL updated. test_sync 21 pass; full
suite green; verify_sync green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 archie/assets/workflow/sync/SKILL.md      | 13 +++++++------
 archie/standalone/sync.py                 | 20 ++++++++++++--------
 npm-package/assets/sync.py                | 20 ++++++++++++--------
 npm-package/assets/workflow/sync/SKILL.md | 13 +++++++------
 tests/test_sync.py                        | 20 ++++++++++----------
 5 files changed, 48 insertions(+), 38 deletions(-)

diff --git a/archie/assets/workflow/sync/SKILL.md b/archie/assets/workflow/sync/SKILL.md
index 09ea3df..c2373d4 100644
--- a/archie/assets/workflow/sync/SKILL.md
+++ b/archie/assets/workflow/sync/SKILL.md
@@ -83,13 +83,14 @@ Where edits land — **the descriptive MIRROR only** (what the code is now):
 - `data` → `data_models` / `persistence_stores` / `data_overview`
 - `tech` → `technology` · `reference` → `quick_reference`
 
-**Do NOT touch the CONTRACT (the law).** Advisory claims (`decision`/`pitfall`/`rule`/
+**Don't AUTO-change the CONTRACT (the law).** Advisory claims (`decision`/`pitfall`/`rule`/
 `guideline`) are recorded `staged` and surface under `staged_amendments` in `fold-context` —
-they are PROPOSED changes for a separate, deliberate decision, NOT something a code-fold
-applies. A fold must never edit `.archie/rules.json`, `domain_invariants`,
-`derived_invariants`, `decisions`, or `pitfalls`; **`fold-apply` refuses a render that moved
-them.** (Why: the PR Intent Review catches code-vs-law drift — if a fold silently moved the
-law to match the code, the deviation would be hidden.)
+proposed changes for a separate, deliberate decision, NOT something the code-fold applies.
+The fold reconciles the descriptive **mirror only**. If the law genuinely changes during the
+work, change it **deliberately** (edit `rules.json` / `domain_invariants` on purpose) —
+`fold-apply` allows it but reports `contract_changed` so the law never moves *silently*.
+(Why: the PR Intent Review catches code-vs-law drift; the law must move deliberately and
+visibly, never as a silent side effect of reconciling code.)
 
 Then **reconcile the intent layer**: for each touched folder in `intent_files`, update the
 **descriptive (AI-authored) section** of that folder's CLAUDE.md to match the code now —
diff --git a/archie/standalone/sync.py b/archie/standalone/sync.py
index 6d13bb5..f2154f8 100644
--- a/archie/standalone/sync.py
+++ b/archie/standalone/sync.py
@@ -629,15 +629,15 @@ def cmd_fold_apply(root: Path, change_file: str | None) -> int:
         print(json.dumps({"ok": False, "error": f"guardrail tripped — blueprint top-level sections dropped: {missing}"}))
         return 1
 
-    # Contract guardrail (Phase 1): a code-fold must not move the law. Checked BEFORE the
-    # render/normalize so normalization can neither mask nor falsely trip it.
+    # Contract awareness (Phase 1): a code-fold reconciles the descriptive MIRROR; the
+    # contract (rules.json / invariants) changes only DELIBERATELY. We do NOT block a
+    # deliberate rule change — rules legitimately change during real work — but we surface
+    # it so the law never moves SILENTLY. Computed BEFORE normalize so normalization can't
+    # mask or falsely flag it. (advisory->staged already stops AUTOMATIC contract moves.)
     expected_fp = (data.get("fold_guardrail") or {}).get("contract_fingerprint")
-    if expected_fp is not None and _contract_fingerprint(root, bp) != expected_fp:
-        print(json.dumps({"ok": False, "error": (
-            "guardrail tripped — a code-fold changed the contract (rules.json / "
-            "invariants). The contract (the law) changes only by a deliberate amendment, "
-            "never a sync fold. Revert the contract edits, then re-run fold-apply.")}))
-        return 1
+    contract_changed = bool(
+        expected_fp is not None and _contract_fingerprint(root, bp) != expected_fp
+    )
 
     sys.path.insert(0, str(_SCRIPT_DIR))
     try:
@@ -692,6 +692,10 @@ def cmd_fold_apply(root: Path, change_file: str | None) -> int:
         "ok": True,
         "folded": folded,
         "rendered_count": len(rendered),
+        "contract_changed": contract_changed,
+        **({"note": "This fold ALSO changed the contract (rules.json / invariants) — a "
+                    "DELIBERATE amendment, not an automatic mirror update. It will be "
+                    "reviewed on the PR."} if contract_changed else {}),
     }))
     return 0
 
diff --git a/npm-package/assets/sync.py b/npm-package/assets/sync.py
index 6d13bb5..f2154f8 100644
--- a/npm-package/assets/sync.py
+++ b/npm-package/assets/sync.py
@@ -629,15 +629,15 @@ def cmd_fold_apply(root: Path, change_file: str | None) -> int:
         print(json.dumps({"ok": False, "error": f"guardrail tripped — blueprint top-level sections dropped: {missing}"}))
         return 1
 
-    # Contract guardrail (Phase 1): a code-fold must not move the law. Checked BEFORE the
-    # render/normalize so normalization can neither mask nor falsely trip it.
+    # Contract awareness (Phase 1): a code-fold reconciles the descriptive MIRROR; the
+    # contract (rules.json / invariants) changes only DELIBERATELY. We do NOT block a
+    # deliberate rule change — rules legitimately change during real work — but we surface
+    # it so the law never moves SILENTLY. Computed BEFORE normalize so normalization can't
+    # mask or falsely flag it. (advisory->staged already stops AUTOMATIC contract moves.)
     expected_fp = (data.get("fold_guardrail") or {}).get("contract_fingerprint")
-    if expected_fp is not None and _contract_fingerprint(root, bp) != expected_fp:
-        print(json.dumps({"ok": False, "error": (
-            "guardrail tripped — a code-fold changed the contract (rules.json / "
-            "invariants). The contract (the law) changes only by a deliberate amendment, "
-            "never a sync fold. Revert the contract edits, then re-run fold-apply.")}))
-        return 1
+    contract_changed = bool(
+        expected_fp is not None and _contract_fingerprint(root, bp) != expected_fp
+    )
 
     sys.path.insert(0, str(_SCRIPT_DIR))
     try:
@@ -692,6 +692,10 @@ def cmd_fold_apply(root: Path, change_file: str | None) -> int:
         "ok": True,
         "folded": folded,
         "rendered_count": len(rendered),
+        "contract_changed": contract_changed,
+        **({"note": "This fold ALSO changed the contract (rules.json / invariants) — a "
+                    "DELIBERATE amendment, not an automatic mirror update. It will be "
+                    "reviewed on the PR."} if contract_changed else {}),
     }))
     return 0
 
diff --git a/npm-package/assets/workflow/sync/SKILL.md b/npm-package/assets/workflow/sync/SKILL.md
index 09ea3df..c2373d4 100644
--- a/npm-package/assets/workflow/sync/SKILL.md
+++ b/npm-package/assets/workflow/sync/SKILL.md
@@ -83,13 +83,14 @@ Where edits land — **the descriptive MIRROR only** (what the code is now):
 - `data` → `data_models` / `persistence_stores` / `data_overview`
 - `tech` → `technology` · `reference` → `quick_reference`
 
-**Do NOT touch the CONTRACT (the law).** Advisory claims (`decision`/`pitfall`/`rule`/
+**Don't AUTO-change the CONTRACT (the law).** Advisory claims (`decision`/`pitfall`/`rule`/
 `guideline`) are recorded `staged` and surface under `staged_amendments` in `fold-context` —
-they are PROPOSED changes for a separate, deliberate decision, NOT something a code-fold
-applies. A fold must never edit `.archie/rules.json`, `domain_invariants`,
-`derived_invariants`, `decisions`, or `pitfalls`; **`fold-apply` refuses a render that moved
-them.** (Why: the PR Intent Review catches code-vs-law drift — if a fold silently moved the
-law to match the code, the deviation would be hidden.)
+proposed changes for a separate, deliberate decision, NOT something the code-fold applies.
+The fold reconciles the descriptive **mirror only**. If the law genuinely changes during the
+work, change it **deliberately** (edit `rules.json` / `domain_invariants` on purpose) —
+`fold-apply` allows it but reports `contract_changed` so the law never moves *silently*.
+(Why: the PR Intent Review catches code-vs-law drift; the law must move deliberately and
+visibly, never as a silent side effect of reconciling code.)
 
 Then **reconcile the intent layer**: for each touched folder in `intent_files`, update the
 **descriptive (AI-authored) section** of that folder's CLAUDE.md to match the code now —
diff --git a/tests/test_sync.py b/tests/test_sync.py
index a50c28a..0c96f16 100644
--- a/tests/test_sync.py
+++ b/tests/test_sync.py
@@ -366,24 +366,24 @@ def test_advisory_kinds_always_staged(tmp_path, capsys):
     assert by["desc one"] == "eligible"
 
 
-def test_fold_apply_contract_guardrail_aborts_on_rules_edit(tmp_path, capsys):
-    # A fold that moves the LAW (rules.json) is refused — the deviation must reach the PR.
+def test_fold_apply_reports_deliberate_rule_change(tmp_path, capsys):
+    # A deliberate rule change during a fold is ALLOWED (rules legitimately change) but
+    # SURFACED via contract_changed, so the law never moves silently.
     root, archie = _setup_foldable(tmp_path, capsys, [
         _claim(kind="behavior", statement="desc", evidence=["app/Main.kt"], confidence="high"),
     ])
     (archie / "rules.json").write_text(json.dumps({"rules": [{"id": "r1", "description": "old"}]}))
     sync.main(["sync.py", "fold-context", str(root)]); capsys.readouterr()
-    # Illegal: a code-fold rewrote the contract.
+    # The dev deliberately moved a rule (extensive work) alongside the fold.
     (archie / "rules.json").write_text(json.dumps({"rules": [{"id": "r1", "description": "CHANGED"}]}))
     rc = sync.main(["sync.py", "fold-apply", str(root)])
     out = json.loads(capsys.readouterr().out)
-    assert rc == 1 and out["ok"] is False
-    assert "contract" in out["error"].lower()
-    rec = json.loads((archie / "changes" / "latest.json").read_text())
-    assert rec.get("folded") in (False, None)
+    assert rc == 0 and out["ok"] is True          # NOT blocked
+    assert out["contract_changed"] is True         # but surfaced
+    assert "note" in out
 
 
-def test_fold_apply_contract_guardrail_aborts_on_invariant_edit(tmp_path, capsys):
+def test_fold_apply_reports_deliberate_invariant_change(tmp_path, capsys):
     root = _init_repo(tmp_path)
     archie = root / ".archie"
     archie.mkdir()
@@ -397,13 +397,13 @@ def test_fold_apply_contract_guardrail_aborts_on_invariant_edit(tmp_path, capsys
         _claim(kind="behavior", statement="d", evidence=["app/Main.kt"], confidence="high")]), capsys)
     capsys.readouterr()
     sync.main(["sync.py", "fold-context", str(root)]); capsys.readouterr()
-    # Illegal: weaken an invariant during the fold.
+    # Deliberately weaken an invariant during the fold — allowed, but flagged.
     bp2 = json.loads((archie / "blueprint.json").read_text())
     bp2["domain_invariants"][0]["invariant"] = "WEAKENED"
     (archie / "blueprint.json").write_text(json.dumps(bp2))
     rc = sync.main(["sync.py", "fold-apply", str(root)])
     out = json.loads(capsys.readouterr().out)
-    assert rc == 1 and "contract" in out["error"].lower()
+    assert rc == 0 and out["contract_changed"] is True
 
 
 def test_fold_apply_renders_and_marks_folded(tmp_path, capsys):

From a89b4bb29bd44a95360f54a43cd531e5e89f126f Mon Sep 17 00:00:00 2001
From: Gabor Bakos <gabor@bitraptors.com>
Date: Mon, 22 Jun 2026 14:43:48 +0200
Subject: [PATCH 15/15] fix(sync): align archie-sync fully with
 snapshot-vs-contract
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Audit gaps:
- contract fingerprint now covers the prescriptive blueprint sections too
  (development_rules / infrastructure_rules / architecture_rules), not just the
  invariants + rule files — these are the law-in-the-blueprint and no descriptive
  kind targets them, so it's safe.
- corrected stale comment ("rule is the only kind that edits rules.json") and the
  SKILL eligibility line to state advisory kinds are ALWAYS staged.

test_sync 22 pass; full suite green; verify_sync green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 archie/assets/workflow/sync/SKILL.md      |  6 ++++--
 archie/standalone/sync.py                 | 19 ++++++++++++-------
 npm-package/assets/sync.py                | 19 ++++++++++++-------
 npm-package/assets/workflow/sync/SKILL.md |  6 ++++--
 tests/test_sync.py                        | 14 ++++++++++++++
 5 files changed, 46 insertions(+), 18 deletions(-)

diff --git a/archie/assets/workflow/sync/SKILL.md b/archie/assets/workflow/sync/SKILL.md
index c2373d4..8d11f6d 100644
--- a/archie/assets/workflow/sync/SKILL.md
+++ b/archie/assets/workflow/sync/SKILL.md
@@ -49,8 +49,10 @@ echo '<your JSON array>' | python3 .archie/sync.py record .
 (Add `--agent claude` under Claude Code, or `--agent codex` under Codex, to tag the
 record's provenance.)
 
-A statement is **eligible** to fold only if `confidence: medium|high`, `reconstructed:
-false`, and grounded in a file inside the diff; else it's `staged` (provisional).
+A statement is **eligible** to fold only if it is a DESCRIPTIVE kind (the mirror) AND
+`confidence: medium|high`, `reconstructed: false`, and grounded in a file inside the diff.
+ADVISORY kinds (`decision`/`pitfall`/`rule`/`guideline`) are ALWAYS `staged` — the contract
+(the law) changes only deliberately, never via a code-fold. Everything else is `staged`.
 
 ## Phase 2 — reconcile eligible statements into the snapshot
 
diff --git a/archie/standalone/sync.py b/archie/standalone/sync.py
index f2154f8..80effce 100644
--- a/archie/standalone/sync.py
+++ b/archie/standalone/sync.py
@@ -417,9 +417,10 @@ def cmd_list(root: Path, as_json: bool) -> int:
 # these are the deterministic bookends: scope resolution + apply/re-render/validate)
 # ---------------------------------------------------------------------------
 
-# claim kind -> the descriptive blueprint section(s) the agent reconciles.
-# Descriptive kinds (the default) keep the snapshot current; advisory kinds are
-# optional. `rule` is the only kind that edits rules.json instead of blueprint.json.
+# claim kind -> the blueprint section(s) for that kind. Only DESCRIPTIVE kinds fold
+# (the mirror); ADVISORY kinds (decision/pitfall/rule/guideline) are always `staged`
+# (never folded). The advisory entries below document where a DELIBERATE amendment would
+# land — NOT where a code-fold writes (a code-fold writes the mirror only).
 _KIND_TARGET = {
     # descriptive — the snapshot of what the code IS
     "behavior":  {"sections": ["components", "communication"]},
@@ -436,10 +437,14 @@ def cmd_list(root: Path, as_json: bool) -> int:
 }
 
 # Snapshot-vs-contract guardrail (Phase 1): the "contract" (the law) a code-fold must
-# never move. The invariant sections + the rule files. (decisions/pitfalls carry mixed
-# descriptive prose, so they're governed by the advisory->staged gate in _classify, not
-# this byte-level fingerprint.)
-_CONTRACT_SECTIONS = ("domain_invariants", "derived_invariants", "unenforced_invariants")
+# never move. The invariant sections + the prescriptive rule sections + the rule files.
+# (decisions/pitfalls carry mixed descriptive prose, so they're governed by the
+# advisory->staged gate in _classify, not this byte-level fingerprint — which would be
+# noisy on them. The sections below are pure law that NO descriptive kind targets.)
+_CONTRACT_SECTIONS = (
+    "domain_invariants", "derived_invariants", "unenforced_invariants",
+    "development_rules", "infrastructure_rules", "architecture_rules",
+)
 _CONTRACT_FILES = ("rules.json", "platform_rules.json")
 
 
diff --git a/npm-package/assets/sync.py b/npm-package/assets/sync.py
index f2154f8..80effce 100644
--- a/npm-package/assets/sync.py
+++ b/npm-package/assets/sync.py
@@ -417,9 +417,10 @@ def cmd_list(root: Path, as_json: bool) -> int:
 # these are the deterministic bookends: scope resolution + apply/re-render/validate)
 # ---------------------------------------------------------------------------
 
-# claim kind -> the descriptive blueprint section(s) the agent reconciles.
-# Descriptive kinds (the default) keep the snapshot current; advisory kinds are
-# optional. `rule` is the only kind that edits rules.json instead of blueprint.json.
+# claim kind -> the blueprint section(s) for that kind. Only DESCRIPTIVE kinds fold
+# (the mirror); ADVISORY kinds (decision/pitfall/rule/guideline) are always `staged`
+# (never folded). The advisory entries below document where a DELIBERATE amendment would
+# land — NOT where a code-fold writes (a code-fold writes the mirror only).
 _KIND_TARGET = {
     # descriptive — the snapshot of what the code IS
     "behavior":  {"sections": ["components", "communication"]},
@@ -436,10 +437,14 @@ def cmd_list(root: Path, as_json: bool) -> int:
 }
 
 # Snapshot-vs-contract guardrail (Phase 1): the "contract" (the law) a code-fold must
-# never move. The invariant sections + the rule files. (decisions/pitfalls carry mixed
-# descriptive prose, so they're governed by the advisory->staged gate in _classify, not
-# this byte-level fingerprint.)
-_CONTRACT_SECTIONS = ("domain_invariants", "derived_invariants", "unenforced_invariants")
+# never move. The invariant sections + the prescriptive rule sections + the rule files.
+# (decisions/pitfalls carry mixed descriptive prose, so they're governed by the
+# advisory->staged gate in _classify, not this byte-level fingerprint — which would be
+# noisy on them. The sections below are pure law that NO descriptive kind targets.)
+_CONTRACT_SECTIONS = (
+    "domain_invariants", "derived_invariants", "unenforced_invariants",
+    "development_rules", "infrastructure_rules", "architecture_rules",
+)
 _CONTRACT_FILES = ("rules.json", "platform_rules.json")
 
 
diff --git a/npm-package/assets/workflow/sync/SKILL.md b/npm-package/assets/workflow/sync/SKILL.md
index c2373d4..8d11f6d 100644
--- a/npm-package/assets/workflow/sync/SKILL.md
+++ b/npm-package/assets/workflow/sync/SKILL.md
@@ -49,8 +49,10 @@ echo '<your JSON array>' | python3 .archie/sync.py record .
 (Add `--agent claude` under Claude Code, or `--agent codex` under Codex, to tag the
 record's provenance.)
 
-A statement is **eligible** to fold only if `confidence: medium|high`, `reconstructed:
-false`, and grounded in a file inside the diff; else it's `staged` (provisional).
+A statement is **eligible** to fold only if it is a DESCRIPTIVE kind (the mirror) AND
+`confidence: medium|high`, `reconstructed: false`, and grounded in a file inside the diff.
+ADVISORY kinds (`decision`/`pitfall`/`rule`/`guideline`) are ALWAYS `staged` — the contract
+(the law) changes only deliberately, never via a code-fold. Everything else is `staged`.
 
 ## Phase 2 — reconcile eligible statements into the snapshot
 
diff --git a/tests/test_sync.py b/tests/test_sync.py
index 0c96f16..1b091d4 100644
--- a/tests/test_sync.py
+++ b/tests/test_sync.py
@@ -406,6 +406,20 @@ def test_fold_apply_reports_deliberate_invariant_change(tmp_path, capsys):
     assert rc == 0 and out["contract_changed"] is True
 
 
+def test_contract_fingerprint_covers_prescriptive_blueprint_sections(tmp_path):
+    # The law-in-the-blueprint (development_rules / infrastructure_rules / architecture_rules)
+    # is part of the contract fingerprint, not just the invariants + rule files.
+    root = tmp_path
+    (root / ".archie").mkdir()
+    fp = sync._contract_fingerprint
+    assert fp(root, {"development_rules": [{"rule": "A"}]}) != fp(root, {"development_rules": [{"rule": "B"}]})
+    assert fp(root, {"infrastructure_rules": [{"rule": "A"}]}) != fp(root, {"infrastructure_rules": [{"rule": "B"}]})
+    assert fp(root, {"architecture_rules": {"naming_conventions": ["A"]}}) != \
+           fp(root, {"architecture_rules": {"naming_conventions": ["B"]}})
+    # a pure mirror section is NOT part of the contract fingerprint
+    assert fp(root, {"components": {"components": [1]}}) == fp(root, {"components": {"components": [2]}})
+
+
 def test_fold_apply_renders_and_marks_folded(tmp_path, capsys):
     root, archie = _setup_foldable(tmp_path, capsys, [
         _claim(kind="behavior", statement="X now does Y", evidence=["app/Main.kt"], confidence="high"),