@mmerterden/multi-agent-pipeline 16.19.0 → 16.21.0

package/pipeline/multi-agent-refs/features/review-delta.md

@@ -0,0 +1,89 @@
+# Feature: Cross-round review delta (Phase 4 Steps 2.1, 2.2, 3.8)
+
+**Pattern**: reviewers re-read the whole diff every round with no memory of the round before, so they rediscover last round's findings in new words and nothing can tell "still broken" from "new". A finding therefore needs an identity that survives the fix: `finding-fingerprint.mjs` computes `F:xxxxxxxx` from the file and either the cited `ruleId` or the normalised issue text (lowercase, quotes stripped, paths reduced to basenames, digit runs collapsed). The line, the severity, the fix text and the reviewer take no part, because all of them change between rounds without the finding changing. `review-delta.mjs` then compares round N with round N-1 and reports `stillPresent`, `resolved`, `downgraded` (re-reported but no longer accepted by triage) and `new`, plus `recurrence`: how many consecutive rework cycles each survivor has lasted. That count is the autopilot circuit-breaker's trigger 2.
+
+Gated by `prefs.global.autopilotCircuitBreaker` (`enabled` default true, `identicalFindingCycles` default 2). Computed by scripts, never by the model: an older triage JSON gets its fingerprints on the fly, and a reviewer that echoes one is respected but not relied on.
+
+## Files per round
+
+Phase 4 Step 3.2.1 writes `$WORKTREE/.pipeline/triage-round-<N>.json` (N = `state.reviewIterations | length`), validates it, annotates it and copies it to `$WORKTREE/triage-output.json`, the name Phase 7, `worktree-finalize.sh`, `render-work-summary.sh` and `diff-explain.mjs` read. A copy rather than a symlink because the salvage is `cp -R`, and `.pipeline/` is on the salvage list, so every round survives into `artifactsPath`. Step 3.7 rewrites the round file; the copy is repeated after it.
+
+## Step 2.1 block: previous-round findings (iteration >= 2)
+
+```bash
+ITERATION=$(jq '.reviewIterations | length' "$STATE_FILE")
+PREV_ROUND="$WORKTREE/.pipeline/triage-round-$((ITERATION-1)).json"
+PREV_BLOCK=""
+[ "$ITERATION" -ge 2 ] && [ -f "$PREV_ROUND" ] && PREV_BLOCK=$(node $HOME/.claude/scripts/finding-fingerprint.mjs annotate "$PREV_ROUND" 2>/dev/null \
+  | jq -r '[.accepted[] | select(.severity=="blocking" or .severity=="important")] | sort_by(.severity != "blocking") | .[:40][] | "- \(.fingerprint) [\(.severity)] \(.file): \(.issue)"')
+```
+
+Rendered at the end of the shared prefix (Step 1.9), identical for every reviewer and for the triage call of that iteration:
+
+```
+<previous-round-findings>
+Each entry below was accepted last round and sent for rework.
+- If the issue is still present, report it again with the SAME fingerprint value and the current line.
+- If it is fixed, omit it. Omission is how you report resolution; never emit a "resolved" finding.
+- Any finding not listed here is new: leave fingerprint unset.
+{PREV_BLOCK}
+</previous-round-findings>
+```
+
+The cap of 40 entries drops `important` before `blocking` so the prefix stays bounded. The block never enters the repo-stable prefix `prompt-assembly.md` describes: the diff it follows is already per-run. After each reviewer's validator gate, `finding-fingerprint.mjs annotate --in-place` fills in any fingerprint the reviewer left unset; `anonymize-findings.mjs` strips only identity keys, so the fingerprint reaches triage, and the triage prompt tells the model to preserve it verbatim.
+
+## Step 2.2 block: scope self-check (every iteration)
+
+Phase 3 Step 3.7 wrote `$WORKTREE/.pipeline/scope-check.json` (contract: `features/scope-check.md`). Render it so reviewers judge the diff against the dev's stated scope and do not re-propose what was rejected:
+
+```bash
+SCOPE_JSON="$WORKTREE/.pipeline/scope-check.json"
+SCOPE_GATE=$(git -C "$WORKTREE" diff --name-only "origin/$BASE_BRANCH"...HEAD \
+  | node $HOME/.claude/scripts/scope-check-gate.mjs --check "$SCOPE_JSON" --diff-files - --advisory 2>/dev/null)
+```
+
+```
+<scope-self-check>
+Files and the reason the dev gave for touching each:
+{jq -r '.files[] | "- \(.path): \(.reason)"' "$SCOPE_JSON"}
+Files in the diff with no stated reason (flag as scope drift if the change is not obviously required):
+{jq -r '.unjustified[]' <<< "$SCOPE_GATE"}
+Deliberately not done (do not raise these as findings; they are known):
+{jq -r '.notDone[] | "- \(.what) (\(.why))"' "$SCOPE_JSON"}
+</scope-self-check>
+```
+
+A missing record renders the block with `no scope-check.json written` and a `review.scope_check=missing` metric; the review proceeds, and the absence is itself information for the reviewer.
+
+## Step 3.8: delta + trigger 2
+
+```bash
+TRIP=$(jq -r '.global.autopilotCircuitBreaker.identicalFindingCycles // 2' "$PREFS_FILE")
+DELTA_JSON=$(node $HOME/.claude/scripts/review-delta.mjs --rounds-dir "$WORKTREE/.pipeline" --iteration "$ITERATION" --trip-cycles "$TRIP"); DELTA_RC=$?
+jq -c --argjson d "$DELTA_JSON" --argjson i "$((ITERATION-1))" \
+  '{reviewIterations: (.reviewIterations | .[$i] += {delta: ($d + {computedAt: (now | todate)})})}' "$STATE_FILE" \
+  | node $HOME/.claude/scripts/write-state.mjs "$STATE_FILE"
+$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 4 review.delta iteration=$ITERATION \
+  new=$(jq '.counts.new // 0' <<< "$DELTA_JSON") still_present=$(jq '.counts.stillPresent // 0' <<< "$DELTA_JSON") \
+  resolved=$(jq '.counts.resolved // 0' <<< "$DELTA_JSON") plateau=$(jq '.plateau // false' <<< "$DELTA_JSON") tripped=$([ "$DELTA_RC" -eq 3 ] && echo true || echo false)
+```
+
+| Exit | Meaning | Action |
+|---|---|---|
+| 0 | Progress, or nothing to compare (iteration 1, missing previous round) | Continue to Step 4. |
+| 3 | A blocking/important finding survived `identicalFindingCycles` consecutive rework cycles | **Autopilot** with `enabled`: trip the breaker. `state.circuitBreaker = {tripped: true, trigger: 2, detail: "finding <fingerprint> (<file>: <issue>) survived <n> consecutive rework cycles", checkpoint: {phase: 4, step: "3.8", iteration: N}, trippedAt, counters: {identicalFindingCycles: <max recurrence>, reworkCycles: N-1}}`, then the halt-visibility protocol from `phases/operations.md` (`status=paused`, `haltReason="4:circuit-breaker:identical-finding"`, tracker meta, the `>&2 HALT` line, the usage report). **Interactive modes**: do not trip; show `delta.stillPresent` and ask (picker-contract) `Continue rework` / `Escalate to me` / `Accept as deferred`, the last moving those findings to `deferred[]` with reason `circuit-breaker: accepted by user after <n> cycles`. |
+| 1 | Unreadable round file | Log `review.delta_skipped reason=invalid` and continue; the delta is advisory and never blocks on its own failure. |
+
+`plateau` (the still-present set unchanged from the previous delta) is logged, not acted on: at the default threshold it coincides with trigger 2 and with the Phase 3 `retryCount` hard-kill. The rework-storm cap itself is trigger 3, recorded by the Phase 3 re-entry. The Phase 3 reflection prompt names each accepted finding by `fingerprint` and quotes `delta.stillPresent` first, marked `STILL PRESENT after round N-1's fix`.
+
+## Why fingerprints are computed, not stored
+
+Same argument `shortId()` in `_retrieval.mjs` makes for corpus rows: derived from the finding's own content, so existing triage files get ids without a migration and a re-annotated file keeps the ids it had. The known trade-off is over-merging: two findings in one file that differ only by a number share a fingerprint. The delta output prints `file: issue` beside every id and the trip needs two consecutive recurrences, so a merge is visible and cannot halt a run by itself. Under-merging (a reviewer that rewrites rather than echoes) only ever suppresses a trip; it never causes one.
+
+## Telemetry
+
+`review.delta` once per iteration >= 2: `iteration`, `new`, `still_present`, `resolved`, `plateau`, `tripped`. `run-metrics.mjs` reports `reviewDelta.stillPresentFinal`, `resolvedTotal` and `tripped`; Phase 7 renders the three counts per round.
+
+## Reference
+
+Scripts: `$HOME/.claude/scripts/_fingerprint.mjs`, `finding-fingerprint.mjs`, `review-delta.mjs`. Schemas: `reviewer-output` 1.2.0, `triage-output` 3.4.0, `dev-critic-output` (optional `fingerprint`), `agent-state` (`reviewIterations[].delta`, `circuitBreaker`). Breaker: `features/autopilot-circuit-breaker.md`. Smokes: `smoke-review-delta.sh`, `smoke-autopilot-circuit-breaker.sh`.

package/pipeline/multi-agent-refs/features/scope-check.md

@@ -0,0 +1,41 @@
+# Feature: Scope self-check (Phase 3 Step 3.7)
+
+**Pattern**: Phase 4 reconstructs everything from the diff. The one thing it cannot reconstruct is why each file was touched and what was left out on purpose, so Dev states both before the handoff, and a deterministic gate checks the statement against the real diff. The record also carries the code-simplifier rationales (Step 3.6) that used to be discarded, and it feeds two later consumers: the `<scope-self-check>` block in the Phase 4 reviewer prefix and the PR body in Phase 6.
+
+## The record
+
+`$WORKTREE/.pipeline/scope-check.json`, schema `schemas/scope-check.schema.json`:
+
+```json
+{
+  "version": "1.0.0",
+  "taskId": "<taskId>",
+  "files": [{ "path": "<repo-relative path>", "reason": "<why this task needs this exact file>" }],
+  "notDone": [{ "what": "<change considered and not made>", "why": "out-of-scope | follow-up | rejected-abstraction" }],
+  "simplifier": { "applied": 0, "skipped": 0, "rationales": ["<Step 3.6 rationale strings>"] }
+}
+```
+
+Rules:
+
+- One entry per file in the diff, no entry for a file outside it. A reason names the task requirement, never "while I was here".
+- `notDone` carries every hypothetical the dev chose not to defend against and every abstraction it considered and rejected, so review does not re-propose them.
+- Component tasks (`taskType === "component"`) write the record too; the plugin skill's file table is the `files[]` source.
+
+## The gate
+
+```bash
+git -C "$WORKTREE" diff --name-only "origin/$BASE_BRANCH"...HEAD \
+  | node $HOME/.claude/scripts/scope-check-gate.mjs --check "$WORKTREE/.pipeline/scope-check.json" --diff-files -
+```
+
+Output `{ok, justified, unjustified[], unlisted[], notDone}`. Exit 1 lists `unjustified[]` (in the diff, no reason or an empty one); `unlisted[]` (in the record, not in the diff) is reported and never fatal. Complete the record once and re-run. A second exit 1 does not block: log `dev.scope_check=incomplete unjustified=<n>` and hand off; Phase 4 receives the gate output inside `<scope-self-check>`, so reviewers see which files arrived without a stated reason. `--advisory` (used by Phase 4) always exits 0. Progress line: `    → checking scope self-check ({n} files, {m} not done)`.
+
+## Consumers
+
+- Phase 4 Step 2.2 renders file reasons, unjustified files and `notDone[]` into the shared reviewer prefix (`features/review-delta.md`).
+- Phase 6 Step 3 builds the PR `## Changes` bullets from `files[].reason` and lists `notDone[]` under `## Related` as "Follow-ups not done in this PR", merged with the final triage `deferred[]` (`channels/pr.md`).
+
+## Reference
+
+Script: `$HOME/.claude/scripts/scope-check-gate.mjs`. Schema: `$HOME/.claude/schemas/scope-check.schema.json`. Smoke: `smoke-scope-check.sh`. Unit: `test/scope-check-gate.test.mjs`.

package/pipeline/multi-agent-refs/features/verify-by-test.md

@@ -5,7 +5,7 @@
 **Gated by `prefs.global.verifyByTest.enabled`** (default: `false`). When enabled, after triage 3.6 and before Step 4, IF the validated triage output contains at least one `accepted` blocking finding:
 
 1. Dispatch ONE verifier sub-agent for the iteration (model: `verifyByTest.model`, default `sonnet`)  -  never one dispatch per finding. Input: up to `verifyByTest.maxFindings` (default 3) accepted blocking findings, the diff hunks for their files, and the Phase 1 test conventions.
-2. Per finding, the verifier writes ONE minimal repro test asserting the correct behavior the finding claims is broken, then runs ONLY that test via the Phase 3 single-test invocation (`xcodebuild test -only-testing:`, `pytest {file}::{name}`, `npm test -- --testPathPattern=`, `./gradlew test --tests`) under `acquire_build_lock`/`release_build_lock`, log tee'd to `$WORKTREE/.pipeline/verify-<i>.test.log`.
+2. Per finding, the verifier writes ONE minimal repro test asserting the correct behavior the finding claims is broken, then runs ONLY that test via the Phase 3 single-test invocation (`xcodebuild test -only-testing:`, `pytest {file}::{name}`, `npm test -- --testPathPattern=`, `./gradlew test --tests`) under `acquire_build_lock`/`release_build_lock`. One green run is not trusted: the same single-test invocation runs `verifyByTest.repeatCount` times (default 3; value 1 disables the repeat) as a shell loop, each run's log tee'd to `$WORKTREE/.pipeline/verify-<i>-<k>.test.log` for `k` in `1..repeatCount`. ALL runs must pass, and each log must clear `evidence-gate.mjs --claim test --status passed`, before the outcome counts as "passes". A first run that fails as predicted ends the loop early (`confirmed` needs no repeat).
 3. Stamp each processed finding with a `verification` object (triage-output schema v3.2.0) and re-run `validate-triage.mjs` on the mutated triage file under the standard 3.2.1 gate protocol.
 4. Findings beyond `maxFindings` keep their judgment-only verdict (log `verify_by_test=cap-exceeded`).
 5. The whole step is bounded by `verifyByTest.stepTimeoutSec` (default 600); on breach or verifier crash, remaining findings keep judgment-only verdicts and the pipeline proceeds. Never blocks.
@@ -15,7 +15,8 @@
 | Repro test outcome | `verification.result` | Action |
 |---|---|---|
 | Fails as the finding predicts | `confirmed` | Finding stays accepted blocking. Repro test KEPT in the worktree, recorded in `redTests[]`. |
-| Passes (not reproducible) | `not-reproduced` | Downgrade gated by `evidence-gate.mjs --claim test --status passed` on the test log (exit 0 required). Finding moves `accepted[]` -> `deferred[]` with reason `verify-by-test: not reproduced - repro test <testRef> passed`; repro test file deleted. Evidence-gate failure -> treat as `inconclusive`. |
+| Passes (not reproducible) | `not-reproduced` | Only when ALL `verifyByTest.repeatCount` runs pass and every `verify-<i>-<k>.test.log` clears `evidence-gate.mjs --claim test --status passed` (exit 0 required on each). Finding moves `accepted[]` -> `deferred[]` with reason `verify-by-test: not reproduced - repro test <testRef> passed`; repro test file deleted. Evidence-gate failure on any run -> treat as `inconclusive`. |
+| Passes on some runs, fails on others | `inconclusive` | Flake, not proof either way. Finding stays accepted blocking, `verification.note = "flaky: passed k/N"`, repro test file deleted, telemetry line gains `flaky=<count>`. |
 | Compile error / timeout / not unit-testable | `inconclusive` | Finding stays accepted blocking (judgment stands). Partial test deleted, cause in `verification.note`. |
 
 Downgrades go to `deferred`, never `rejected`: triage judged the issue real, and deferred items surface in the Phase 7 report for a human eye.
@@ -30,12 +31,12 @@ After Step 3.7, the only uncommitted verifier artifacts are the confirmed repro
 
 ## Telemetry
 
-One `review.verify_by_test` metric per iteration: `attempted`, `confirmed`, `downgraded`, `inconclusive`, `duration_ms` (plus `tokens_in/out` when available), forwarded to the tracker like all Phase 4 metrics. Timeout emits `triage=verify-by-test-timeout`.
+One `review.verify_by_test` metric per iteration: `attempted`, `confirmed`, `downgraded`, `inconclusive`, `flaky` (findings whose repeat runs disagreed), `duration_ms` (plus `tokens_in/out` when available), forwarded to the tracker like all Phase 4 metrics. Timeout emits `triage=verify-by-test-timeout`.
 
 ## Off by default reason
 
-Adds one Sonnet call plus up to `maxFindings` single-test runs (and build-lock contention on Xcode projects) per review iteration that has accepted blockers. On clean runs it never fires, but on noisy-reviewer repos it can add minutes per iteration. Flip on for security-critical work, release branches, or repos where reviewer false-positive rate is high.
+Adds one Sonnet call plus up to `maxFindings` single-test runs (and build-lock contention on Xcode projects) per review iteration that has accepted blockers. Each passing repro test is re-run `verifyByTest.repeatCount` times (default 3), so a downgrade costs up to `repeatCount` single-test runs rather than one. On clean runs it never fires, but on noisy-reviewer repos it can add minutes per iteration. Flip on for security-critical work, release branches, or repos where reviewer false-positive rate is high.
 
 ## Reference
 
-Wiring: `$HOME/.claude/multi-agent-refs/phases/phase-4-review.md` Step 3.7. Schema: `$HOME/.claude/schemas/triage-output.schema.json` v3.2.0 (`$defs.verification`). Evidence gate: `$HOME/.claude/scripts/evidence-gate.mjs`. Prefs: `prefs.global.verifyByTest` in `$HOME/.claude/schemas/prefs.schema.json`.
+Wiring: `$HOME/.claude/multi-agent-refs/phases/phase-4-review.md` Step 3.7. Schema: `$HOME/.claude/schemas/triage-output.schema.json` v3.2.0 (`$defs.verification`). Evidence gate: `$HOME/.claude/scripts/evidence-gate.mjs`. Prefs: `prefs.global.verifyByTest` (including `repeatCount`) in `$HOME/.claude/schemas/prefs.schema.json`.

package/pipeline/multi-agent-refs/features/worktree-finalize.md

@@ -49,7 +49,7 @@ This is why the removal is safe:
 
 | Consumer | Reads | Without salvage |
 |---|---|---|
-| Phase 7 triage-memory ingest | `triage-output.json` | `[ -f ]`-guarded, so it degrades **silently**: the triage corpus and learnings ledger stop being fed and no error appears |
+| Phase 7 triage-memory ingest | `triage-output.json` | `[ -f ]`-guarded, so it degrades **silently**: the triage corpus and learnings ledger stop being fed and no error appears. Since v16.20.0 Phase 4 writes `triage-output.json` itself (Step 3.2.1, the latest copy of `.pipeline/triage-round-<N>.json`), so the salvage is a second copy, not the only bridge |
 | Phase 7 learnings-ledger distill | same file | same silent degradation |
 | `render-work-summary.sh` | `agent-state.json`, `phase-tracker.json` (falls back to `logs/multi-agent/<task>/tracker-state.json`, which survives removal) | loses the salvaged copies but keeps the tracker via the logs fallback |
 | `:resume` | `agent-state.json` | cannot continue a Phase 7 pause |

package/pipeline/multi-agent-refs/payload-contracts.md

@@ -10,7 +10,7 @@ description: "Canonical required-reading list for outward-facing payloads (PR bo
 
 | Read | Before | Governs |
 |---|---|---|
-| [`channels/pr.md`]($HOME/.claude/multi-agent-refs/channels/pr.md) | assembling the PR body | fixed section set (`summary` → `changes` → `architecture` cond. → `verification` → `dependencies` cond. → `related`), Markdown-only rule, reviewer-preserving Bitbucket PUT payload |
+| [`channels/pr.md`]($HOME/.claude/multi-agent-refs/channels/pr.md) | assembling the PR body | fixed section set (`summary` → `changes` → `architecture` cond. → `verification` → `risk` cond. → `dependencies` cond. → `related`), Markdown-only rule, reviewer-preserving Bitbucket PUT payload |
 | [`phases/phase-6-commit.md`]($HOME/.claude/multi-agent-refs/phases/phase-6-commit.md) | committing | commit convention, default-reviewer fetch, draft/ready prompt, push-must-succeed loop |
 | [`rules.md`]($HOME/.claude/multi-agent-refs/rules.md) "External System Outputs" | any REST payload | real newlines, no HTML entities, no hand-rolled JSON, markup dialect per surface |
 

package/pipeline/multi-agent-refs/phases/phase-3-dev.md

@@ -84,7 +84,8 @@ When re-entering from Phase 4:
 3. `accepted.suggestion` items are applied opportunistically (no TDD loop required) unless the user asked for suggestions to be treated strictly.
 4. `deferred` items are NOT actioned in this re-entry  -  they surface in Phase 7's "Follow-up items" section.
 5. `rejected` items are never touched. Log their IDs + triage reasons for audit only.
-6. After rework, increment `state.phases["3"].retryCount`; hard-kill at `retryCount === 3` and escalate to the user. Do not loop indefinitely.
+6. After rework, increment `state.phases["3"].retryCount`; hard-kill at `retryCount === 3` and escalate to the user. Do not loop indefinitely. When `prefs.global.autopilotCircuitBreaker.enabled` is true (default), record the hard-kill before escalating as `state.circuitBreaker = {tripped: true, trigger: 3, detail: "rework cycles exhausted", checkpoint: {phase: 3, step: "re-entry", iteration: <n>}, trippedAt, counters: {reworkCycles: <n>}}`: the rework-storm trigger; `autopilotCircuitBreaker.maxReworkCycles` (default 3) is bounded above by this cap.
+7. When `state.reviewIterations[-1].delta` exists, `stillPresent[]` findings come first in the task list, quoted `STILL PRESENT after round N-1's fix`; repeating the previous attempt is the loop the circuit-breaker stops.
 
 If the latest iteration has `triage.approved === true` AND `accepted === []`, Phase 3 was entered by mistake  -  log the anomaly and return to Phase 5.
 
@@ -155,6 +156,7 @@ For each task (respecting dependency order):
    **REFACTOR (if needed):**
    - Only if duplication or naming is poor
    - Re-run tests after refactor → still GREEN
+   - **Stability (required):** run every test added or changed in this diff `prefs.global.testStability.repeatCount` times (default 3; 1 disables) with the single-test invocation above. Disagreeing outcomes are not GREEN: log `test.flake_signal file=<f> passed=<k> of=<N>` and fix the test or the code first. A pass only on retry is a flake signal, not a pass. Same rule on the Phase 4 rework re-entry.
 
    **Target resolution** (auto-detect once per project, cache in `agent-state.json`; ios resolves scheme + simulator, android resolves module + variant, backend/web need none):
    ```bash
@@ -243,7 +245,7 @@ After the build/test green step and BEFORE Phase 4 handoff, run one diff-shrink
    - **Over-abstraction**  -  single-call-site protocols/wrappers/helpers from this diff
 
    Progress line: `    → dispatching code-simplifier diff-shrink`
-2. **Return contract**  -  a list of shrink edits `{ "file", "lines", "edit", "rationale", "risk": "safe|unsafe" }`; the subagent never writes files.
+2. **Return contract**  -  a list of shrink edits `{ "file", "lines", "edit", "rationale", "risk": "safe|unsafe" }`; the subagent never writes files. Keep the `rationale` strings: Step 3.7 writes them into `scope-check.json`.
 3. **Apply safe edits only**  -  skip `unsafe` (logged). Zero edits is normal  -  log and continue. Progress line: `    → applying shrink edits ({N} applied, {M} skipped)`
 4. **Re-run build + tests** (same build-queue lock + evidence-gate rule as Step 4). Any breakage -> revert shrink edits wholesale and proceed pre-shrink; the simplifier must never cost a green state.
 5. **Record tokens in the cost ledger** so Phase 7's Cost Breakdown captures the pass:
@@ -258,6 +260,19 @@ Scope guard: a single pass, never looped. Runs in a Short run too; component tas
 
 ---
 
+#### Step 3.7  -  Scope self-check (required handoff artifact)
+
+Phase 4 cannot reconstruct why each file was touched or what was left out on purpose, so Dev states both before the handoff: write `$WORKTREE/.pipeline/scope-check.json` (`schemas/scope-check.schema.json`: one `{path, reason}` per file in the diff, `notDone[]` with `why` in `out-of-scope | follow-up | rejected-abstraction`, and the Step 3.6 `simplifier` rationales), then run the gate. **Record rules, consumers and the full contract: `$HOME/.claude/multi-agent-refs/features/scope-check.md`.**
+
+```bash
+git -C "$WORKTREE" diff --name-only "origin/$BASE_BRANCH"...HEAD \
+  | node $HOME/.claude/scripts/scope-check-gate.mjs --check "$WORKTREE/.pipeline/scope-check.json" --diff-files -
+```
+
+Exit 1 lists `unjustified[]`: complete the record once and re-run. A second exit 1 does not block; log `dev.scope_check=incomplete unjustified=<n>` and hand off, and Phase 4 shows the gate output to reviewers inside `<scope-self-check>`. Progress line: `    → checking scope self-check ({n} files, {m} not done)`.
+
+---
+
 #### Short pipeline (`state.onlyDevelop === true`)
 
 Set by the Phase 0 Step 7.5 depth picker, or by autopilot never (autopilot always runs Full). When it is true, Phase 3 runs self-contained with **Opus** (not Sonnet). No Phase 2 plan exists  -  the agent creates its own scope.

package/pipeline/multi-agent-refs/phases/phase-4-review.md

@@ -152,6 +152,12 @@ echo "$RISK_FULL" | node $HOME/.claude/scripts/validate-diff-risk.mjs - >/dev/nu
 RISK_JSON=$([ -n "$RISK_FULL" ] && jq -c '.files |= (sort_by(-.score) | .[:5])' <<< "$RISK_FULL" || echo "")
 ```
 
+Persist the totals as `state.diffRisk` (Phase 6 `risk` section, Phase 7, `run-metrics.mjs` read them):
+
+```bash
+[ -n "$RISK_FULL" ] && jq -c '{diffRisk: (.totals + {signals: ([.files[].signals[]?.name] | unique)})}' <<< "$RISK_FULL" | node $HOME/.claude/scripts/write-state.mjs "$STATE_FILE"
+```
+
 **Signals & weights** (see `$HOME/.claude/schemas/diff-risk.schema.json`):
 
 | Signal | Weight | Triggers when |
@@ -179,7 +185,9 @@ On success, emit a single summary metric:
 $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 4 review.diff_risk \
   top_files=$(jq '.files | length' <<< "$RISK_JSON") \
   max_score=$(jq '.totals.max_score' <<< "$RISK_JSON") \
-  loc_added=$(jq '.totals.loc_added' <<< "$RISK_JSON")
+  loc_added=$(jq '.totals.loc_added' <<< "$RISK_JSON") \
+  loc_removed=$(jq '.totals.loc_removed' <<< "$RISK_JSON") \
+  files=$(jq '.totals.files' <<< "$RISK_JSON")
 ```
 
 **Opt-out**: `prefs.global.diffRiskAdvisory = false` skips this step entirely (no script invocation, no priority block injection). Default `true` because the cost is bounded and the signal-to-noise has been measured against the golden-task fixture set.
@@ -269,7 +277,7 @@ When `state.figmaAccess.tier === 3` (user-attached screenshot, no Code Connect s
 
 Phase 4 sends the same diff to every reviewer and then to triage, so the diff is the dominant token cost. Two measures keep it bounded:
 
-**Shared cache prefix.** Build the reviewer and triage prompts so the large invariant context  -  the full diff, the `${CRITERIA}` block from Step 1.78, the Phase 1 analysis summary, the Phase 2 plan  -  is a byte-identical leading block across all dispatches in this iteration. Only the per-reviewer focus + skill line varies, and it goes AFTER the shared block. `${CRITERIA}` goes in the prefix, identical for every reviewer: subsetting it per reviewer would invalidate the prefix for the whole panel and re-bill the largest block in the phase. Per-reviewer emphasis stays a one-line pointer in the suffix. When the host supports prompt caching, the 2nd/3rd reviewer and the triage call then read that prefix at the discounted cache-read rate instead of re-billing it as fresh input. Forward the host-reported cache-read count as `tokens_cached` per the Token telemetry contract so the saving lands in the cost ledger.
+**Shared cache prefix.** Build the reviewer and triage prompts so the large invariant context  -  the full diff, the `${CRITERIA}` block from Step 1.78, the Phase 1 analysis summary, the Phase 2 plan  -  is a byte-identical leading block across all dispatches in this iteration. Only the per-reviewer focus + skill line varies, and it goes AFTER the shared block. `${CRITERIA}` goes in the prefix, identical for every reviewer: subsetting it per reviewer would invalidate the prefix for the whole panel and re-bill the largest block in the phase. Per-reviewer emphasis stays a one-line pointer in the suffix. When the host supports prompt caching, the 2nd/3rd reviewer and the triage call then read that prefix at the discounted cache-read rate instead of re-billing it as fresh input. Forward the host-reported cache-read count as `tokens_cached` per the Token telemetry contract so the saving lands in the cost ledger. The `<scope-self-check>` block and, from iteration 2, the `<previous-round-findings>` block (Step 2.1) close the shared block, after the plan and before the per-reviewer suffix.
 
 **Single-repo diff cap.** If the diff exceeds the Phase 4 token allowance (`token-budget.json`), truncate the largest files and append a footer `[truncated  -  full diff in file://$WORKTREE/.review-diff.txt]`, writing the full diff to that path. Reviewers and triage receive the same capped view + the marker so they can flag "review the full diff manually." Log `review.diff_truncated bytes_dropped=<N>`. (Multi-repo already caps the combined diff at 80% of budget; this is the single-repo equivalent.)
 
@@ -328,7 +336,9 @@ Each reviewer inherits the `code-reviewer` agent's focus areas (Security, Archit
 | Docker | `ai-backend-toolkit:docker-expert` | `ai-backend-toolkit:docker-expert` | `ai-backend-toolkit:ci-cd-pipelines` |
 | Generic | `security-review` | `ai-backend-toolkit:clean-code` | `ai-backend-toolkit:clean-code` |
 
-Skills are injected into reviewer prompt context  -  the reviewer uses them as reference, not as commands.
+##### 2.1 Previous-round findings (iteration >= 2) and 2.2 scope self-check (every iteration)
+
+A reviewer has no memory of the round before, so it rediscovers last round's findings in new words. From iteration 2, render the previous round's accepted blocking/important findings (`.pipeline/triage-round-$((ITERATION-1)).json`, max 40) into a `<previous-round-findings>` block at the end of the shared prefix: a still-present issue is reported with the SAME fingerprint and the current line, a fixed one is omitted, anything new leaves `fingerprint` unset. Every iteration also renders `.pipeline/scope-check.json` (Phase 3 Step 3.7) plus `scope-check-gate.mjs --advisory` output as `<scope-self-check>`: file reasons, unjustified files, and `notDone[]` (never re-raised as findings); a missing record logs `review.scope_check=missing`. Block text and recipes: `$HOME/.claude/multi-agent-refs/features/review-delta.md`.
 
 #### Step 2.8  -  Visual conformance gate (component / screen work only)
 
@@ -382,11 +392,14 @@ Step 2 produces N reviewer-output objects (one per dispatched reviewer), each co
 REVIEWER_FILE="$WORKTREE/.pipeline/reviewer-$N.json"
 printf '%s' "$REVIEWER_JSON" > "$REVIEWER_FILE"
 node $HOME/.claude/scripts/validate-reviewer.mjs "$REVIEWER_FILE" \
-  --criteria "$WORKTREE/.pipeline/criteria-manifest.json"
+  --criteria "$WORKTREE/.pipeline/criteria-manifest.json" \
+  && node $HOME/.claude/scripts/finding-fingerprint.mjs annotate --in-place "$REVIEWER_FILE"
 ```
 
 Progress line: `    → checking validator validate-reviewer ({reviewer})`
 
+`finding-fingerprint.mjs` stamps each finding with its cross-round id once the validator passes; an echoed one is kept, and anonymization leaves it intact.
+
 Exit 0 = valid. Exit 2 = contradiction (approved=true with blocking findings)  -  flip `approved` to `false`, continue. With `--criteria`, exit 1 also covers the conformance checklist: a selected rule ID with no verdict, a verdict for an ID that was never selected, a `conformant` row with no file evidence, or a `violated` row with no matching finding. Those are the four ways a review can look complete without being complete, and the validator is what makes the checklist more than decoration  -  it is hand-written and does not apply `additionalProperties`, so an unchecked array would otherwise pass. Exit 1 = malformed; gate protocol (fails CLOSED, same handling as the evidence gate): emit the validator stderr + `errors[]` verbatim, attempt ONE self-correction rework (re-invoke that reviewer with the errors quoted, overwrite the file), re-run the validator. If it fails again -> HALT the phase (no merge, no triage). Recovery hint: `ERR: reviewer output failed validate-reviewer.mjs twice. Inspect $REVIEWER_FILE against $HOME/.claude/schemas/reviewer-output.schema.json, then resume with /multi-agent:resume #N.`
 
 #### Step 2.5  -  Disagreement-round loop (opt-in)
@@ -499,6 +512,7 @@ bash $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 4 memory.hit rows=$CITED_COU
 ```
 You are the Review Triage agent. Three reviewers (fewer on a single-scope run) returned findings on this diff.
 Your job: separate signal from noise. Do NOT add new findings. Do NOT re-review code.
+Preserve `fingerprint` verbatim on every finding you carry through; it is the finding's identity across rounds.
 
 For each finding, decide:
 - ACCEPTED: real issue, in scope, must be fixed now
@@ -529,14 +543,19 @@ Return ONLY valid JSON conforming to $HOME/.claude/schemas/triage-output.schema.
 Run on the persisted file immediately after the triage agent returns, before acting on the verdict; the validator's exit code decides, not the LLM turn:
 
 ```bash
-TRIAGE_FILE="$WORKTREE/.pipeline/triage.json"
+ITERATION=$(jq '.reviewIterations | length' "$STATE_FILE")
+TRIAGE_FILE="$WORKTREE/.pipeline/triage-round-$ITERATION.json"
 mkdir -p "$(dirname "$TRIAGE_FILE")"
 printf '%s' "$TRIAGE_JSON" > "$TRIAGE_FILE"
-node $HOME/.claude/scripts/validate-triage.mjs "$TRIAGE_FILE"
+node $HOME/.claude/scripts/validate-triage.mjs "$TRIAGE_FILE" \
+  && node $HOME/.claude/scripts/finding-fingerprint.mjs annotate --in-place "$TRIAGE_FILE" \
+  && cp "$TRIAGE_FILE" "$WORKTREE/triage-output.json"
 ```
 
 Progress line: `    → checking validator validate-triage`
 
+One file per round; `triage-output.json` is the latest copy every downstream reader expects (Phase 7, finalize, work-summary, diff-explain). Step 3.7 rewrites `$TRIAGE_FILE`; repeat the `cp` after it.
+
 | Exit  | Meaning                      | Action                                            |
 | ----- | ---------------------------- | ------------------------------------------------- |
 | **0** | Valid and clean              | Act on triage output as-is                        |
@@ -607,7 +626,26 @@ After the triage verdict is computed, populate `triage.consensus`:
 
 A triage verdict is judgment; a failing repro test is proof. Runs only when `prefs.global.verifyByTest.enabled` is `true` AND `accepted` contains a `blocking` finding; otherwise skip silently. **Full contract (verdict table, cleanup invariant, prompts): `$HOME/.claude/multi-agent-refs/features/verify-by-test.md`  -  read it before executing this step.**
 
-Compressed flow: dispatch ONE verifier agent (model `verifyByTest.model`, default `sonnet`) for up to `maxFindings` (default 3) accepted blocking findings. Per finding it writes ONE minimal repro test and runs ONLY that test (Phase 3 single-test invocation, build lock, log tee'd to `$WORKTREE/.pipeline/verify-<i>.test.log`). Outcomes: test FAILS as predicted -> `confirmed`, finding stays blocking and the test is KEPT in `redTests[]` as the Phase 3 rework RED test; test PASSES -> `not-reproduced` ONLY if `evidence-gate.mjs --claim test --status passed` exits 0 on the log, finding moves to `deferred[]`, test deleted; compile error / timeout / not unit-testable -> `inconclusive`, judgment verdict stands. Stamp findings with `verification` (schema v3.2.0), persist `state.reviewIterations[-1].verifyByTest = {attempted, confirmed, downgraded, inconclusive, redTests[]}`, recompute `approved`, re-run `validate-triage.mjs` under the 3.2.1 gate. Whole step bounded by `stepTimeoutSec` (default 600); on breach or crash remaining findings keep judgment verdicts  -  never blocks. Telemetry per 3.4: `review.verify_by_test attempted= confirmed= downgraded= inconclusive= duration_ms=`.
+Compressed flow: dispatch ONE verifier agent (model `verifyByTest.model`, default `sonnet`) for up to `maxFindings` (default 3) accepted blocking findings. Per finding it writes ONE minimal repro test and runs ONLY that test (Phase 3 single-test invocation, build lock, log tee'd to `$WORKTREE/.pipeline/verify-<i>.test.log`). Outcomes: test FAILS as predicted -> `confirmed`, finding stays blocking and the test is KEPT in `redTests[]` as the Phase 3 rework RED test; test PASSES on every one of `verifyByTest.repeatCount` runs (default 3) -> `not-reproduced` ONLY if `evidence-gate.mjs --claim test --status passed` exits 0 on each log; a run that disagrees with the others -> `inconclusive` with `flaky: passed k/N`, finding moves to `deferred[]`, test deleted; compile error / timeout / not unit-testable -> `inconclusive`, judgment verdict stands. Stamp findings with `verification` (schema v3.2.0), persist `state.reviewIterations[-1].verifyByTest = {attempted, confirmed, downgraded, inconclusive, redTests[]}`, recompute `approved`, re-run `validate-triage.mjs` under the 3.2.1 gate. Whole step bounded by `stepTimeoutSec` (default 600); on breach or crash remaining findings keep judgment verdicts  -  never blocks. Telemetry per 3.4: `review.verify_by_test attempted= confirmed= downgraded= inconclusive= duration_ms=`.
+
+##### 3.8 Cross-round delta + circuit-breaker trigger 2 (iteration >= 2)
+
+**Full contract (state merge, telemetry line, picker wording): `$HOME/.claude/multi-agent-refs/features/review-delta.md`.**
+
+```bash
+TRIP=$(jq -r '.global.autopilotCircuitBreaker.identicalFindingCycles // 2' "$PREFS_FILE")
+DELTA_JSON=$(node $HOME/.claude/scripts/review-delta.mjs --rounds-dir "$WORKTREE/.pipeline" --iteration "$ITERATION" --trip-cycles "$TRIP"); DELTA_RC=$?
+```
+
+Merge the JSON into `state.reviewIterations[-1].delta` via `write-state.mjs`; emit `review.delta iteration= new= still_present= resolved= plateau= tripped=`. Progress line: `    → comparing round {N} vs {N-1} (new={n} still={n} resolved={n})`.
+
+| Exit | Action |
+|---|---|
+| **0** | Continue to Step 4 (also iteration 1 and a missing previous round). |
+| **3** | Autopilot with `prefs.global.autopilotCircuitBreaker.enabled` (default true): write `state.circuitBreaker = {tripped: true, trigger: 2, detail, checkpoint: {phase: 4, step: "3.8", iteration: N}, trippedAt, counters}`, then the `operations.md` halt protocol with `haltReason="4:circuit-breaker:identical-finding"`. Interactive: show `delta.stillPresent`, ask `Continue rework` / `Escalate to me` / `Accept as deferred`. |
+| **1** | Log `review.delta_skipped reason=invalid`, continue; the delta never blocks on its own failure. |
+
+`plateau` is logged, not acted on; trigger 3 (the rework cap) is recorded by the Phase 3 re-entry.
 
 #### Step 4  -  Consensus + Action (triage-driven)
 
@@ -615,7 +653,7 @@ If `triage.consensus.verdict` is `split` or `unverified`, surface `consensus.dis
 
 Act **only on triage.accepted**:
 
-- **accepted.blocking** → back to Phase 3 (max 3 iterations, with reflection prompt citing only accepted items). When Step 3.7 ran and `state.reviewIterations[-1].verifyByTest.redTests[]` is non-empty, the reflection prompt cites each red test: "a failing repro test already exists at <testRef>; make it green; do not delete or weaken it."
+- **accepted.blocking** → back to Phase 3 (max 3 iterations, with reflection prompt citing only accepted items). The reflection prompt names findings by `fingerprint` and quotes `delta.stillPresent` first, marked `STILL PRESENT after round N-1's fix`. When Step 3.7 ran and `state.reviewIterations[-1].verifyByTest.redTests[]` is non-empty, the reflection prompt cites each red test: "a failing repro test already exists at <testRef>; make it green; do not delete or weaken it."
 - **accepted.important** → fix and re-review
 - **accepted.suggestion** → apply if reasonable
 - **deferred** → append to Phase 7 report as "follow-up items" (do not block)

package/pipeline/multi-agent-refs/phases/phase-5-test.md

@@ -103,6 +103,16 @@ Tier 1 / Tier 2 records print `screenshotUrl` from the captured evidence (Tier 2
    bash $HOME/.claude/scripts/phase-tracker.sh render
    ```
    The waiting state persists in `tracker-state.json` across the handoff; `/multi-agent:resume-local` and `/multi-agent:manual-test` CONTINUE this state file and never re-init it (`$HOME/.claude/multi-agent-refs/tracker-contract.md` "Continuation runs").
+
+   **"ok" is a structured result, not a word.** Before "ok" is accepted, the run writes `$WORKTREE/.pipeline/manual-test.json`: one entry per acceptance criterion, the criteria taken from the analysis doc test plan (Section 15 / 20), the plan tasks, and the user's own words in the reply. Every criterion records what was seen; a criterion that was not tried says so with a reason.
+   ```json
+   {"criteria":[{"spec":"<quote>","source":"analysis 15.2 | plan task 3 | user","observed":"<what was seen>","verdict":"pass|fail|not-tested","reason":"<required when not-tested>","screenshot":"<path or null>"}],"verdict":"passed|failed"}
+   ```
+   Then gate it:
+   ```bash
+   node $HOME/.claude/scripts/evidence-gate.mjs --claim manual --status passed --evidence "$WORKTREE/.pipeline/manual-test.json"
+   ```
+   Exit 1 means the "ok" is not accepted: tell the user which criterion is missing evidence (a `fail` verdict, or `not-tested` without a reason) and wait for the next reply. Exit 0 marks Phase 5 completed with `Result "local test passed (user)"`. The "fix: ..." path below is unchanged.
 6. If fix needed:
    - Branch already has WIP commit (from step 2)  -  changes are safe
    - **Heal stale admin state first** (same contract as Phase 0  -  step 3's

package/pipeline/multi-agent-refs/phases/phase-6-commit.md

@@ -136,6 +136,8 @@ Branch **deterministically**, no implicit fallback. Read `agent-state.json` and
 
 Generate a structured PR description based on task type. The PR body targets **code reviewers**  -  it should be technical: what changed, why, architecture decisions, how to verify.
 
+Two inputs are read from state and the worktree before writing, not recalled from the conversation: `$WORKTREE/.pipeline/scope-check.json` (Phase 3 Step 3.7) supplies the `## Changes` bullets from `files[].reason` and the "Follow-ups not done in this PR" list under `## Related` from `notDone[]`; `state.diffRisk.signals` (Phase 4 Step 1.75) decides whether the conditional `## Risk and Security` section is required. When a high-stakes signal is present and the section is missing, this step blocks until it is written; a placeholder answer ("TBD") counts as missing.
+
 **required**: Run all generated text (PR body, commit message) through the `humanizer` skill before posting. This removes AI-generated patterns (inflated language, filler phrases, repetitive structure) and makes the output sound like a developer wrote it.
 
 **IMPORTANT  -  Issue auto-close prevention**: Never use these keywords in PR title, body, or commit messages  -  they auto-close the issue on merge:

package/pipeline/multi-agent-refs/phases/phase-7-report.md

@@ -163,8 +163,10 @@ Skipped sections: when `planTodos.enabled` is false or no `plan.todos[]` was emi
 
 ## Review Iterations
 
-| Iteration | Blocking | Important | Suggestion | Decision |
-| --------- | -------- | --------- | ---------- | -------- |
+| Iteration | Blocking | Important | Suggestion | Decision | Still present | Resolved | New |
+| --------- | -------- | --------- | ---------- | -------- | ------------- | -------- | --- |
+
+(the last three columns come from `reviewIterations[i].delta.counts` (Phase 4 Step 3.8) and read `-` on iteration 1 and on runs that predate the delta; a tripped circuit-breaker is one extra line under the table: `Circuit-breaker tripped: trigger {n}, {detail}`)
 
 ## Files Changed
 

package/pipeline/multi-agent-refs/picker-contract.md

@@ -81,6 +81,6 @@ In autopilot, `ask_choice` resolves to `default` (or the safe first option) with
 
 ## Deterministic gates note
 
-Claude Code's `PreToolUse` exit-2 hooks are the HARD blocking gates. Two ship, both needing no run-specific arguments so they are naturally hookable: (1) `pre-commit-check.sh` scans the staged diff on every `git commit` and blocks on a detected secret; (2) `agent-guard.sh` runs on `git commit` + `git push` and blocks AI/assistant attribution in a commit message and force-push to a protected branch (main/master/develop). Both are self-contained, fail-open on internal error, and never execute the inspected command. The recommended hook block ships at `install/templates/claude-hooks.json`; `multi-agent:setup` offers to merge it into `~/.claude/settings.json`. The other deterministic gates (evidence, consensus, intent, learnings) are invoked by the pipeline phases with per-run arguments (a build-log path, the triage JSON, the free-text input), so they are phase-enforced by contract, not OS-hookable.
+Claude Code's `PreToolUse` exit-2 hooks are the HARD blocking gates. Three ship, none needing run-specific arguments so they are naturally hookable: (1) `pre-commit-check.sh` scans the staged diff on every `git commit` and blocks on a detected secret; (2) `agent-guard.sh` runs on `git commit` + `git push` and blocks AI/assistant attribution in a commit message and force-push to a protected branch (main/master/develop); (3) `check-read-size.sh` runs on `Read` and on the shell commands that read a file whole, and routes an oversized read to a cheap worker (`bulk-read.sh`) instead of the caller's own rung. The first two inspect what a run WRITES; the third inspects what it pays to READ, and it is inert until `bulkRead.mode` is set to `observe` or `enforce`, so merging the block changes nothing until the user opts in. Its `observe` mode blocks nothing and only logs, which is how the baseline is measured before anything is routed. All three are self-contained, fail-open on internal error, and never execute the inspected command. The recommended hook block ships at `install/templates/claude-hooks.json`; `multi-agent:setup` offers to merge it into `~/.claude/settings.json`. The other deterministic gates (evidence, consensus, intent, learnings) are invoked by the pipeline phases with per-run arguments (a build-log path, the triage JSON, the free-text input), so they are phase-enforced by contract, not OS-hookable.
 
 Copilot CLI has no `PreToolUse` equivalent, so the secret scan there is workflow-enforced (run as a phase step, not OS-blocked) plus a CI smoke-gate step.

package/pipeline/multi-agent-refs/rules.md

@@ -52,10 +52,10 @@ This is the single source of truth. When a contributor or model is unsure where
 - **NEVER** commit without passing build (all gates in Phase 4 Step 1 must be green).
 - **NEVER** commit without passing review (at least one AI reviewer must return `approved: true` with no blocking findings).
 - **NEVER** skip tests. Every public method, every error path, every edge case.
-- **NEVER** delete, rename, or weaken an existing test to get a green run. Existing tests are immutable during a task. A test may change only when the task itself changes the spec that test encodes, and the commit body must name the changed test and the spec change. Deterministic backstop: the `test_lines_removed` diff-risk signal (Phase 4 Step 1.75) flags test files that shrink.
+- **NEVER** delete, rename, or weaken an existing test to get a green run. Existing tests are immutable during a task; one may change only when the task changes the spec it encodes, and the commit body names both. Deterministic backstop: the `test_lines_removed` diff-risk signal (Phase 4 Step 1.75) flags test files that shrink. A pass only on retry is a flake signal, not a pass: Phase 3 repeats new and changed tests (`testStability.repeatCount`, default 3) and logs `test.flake_signal` when runs disagree.
 - **Follow existing code style and conventions.** Read neighbor files before writing new ones  -  match naming, structure, import order.
 - **Use design tokens, no magic numbers.** `16` → `.Spacing.spacing16`. `#E31837` → `Color.Primary.primary`. `.font(.system(size: 14))` → `.typographyStyle(.body1)`.
-- **Design system primitives before custom views.** Before writing a new SwiftUI / Compose / React / View / Configuration triplet inside a domain or feature module, grep the shared component library (project-specific path, e.g. `Common/UIComponents/`, `core-ui/`, `packages/ui/`) for an existing primitive that solves the same problem. New domain-level wrappers, custom modals, custom buttons, or hand-rolled toasts are forbidden when the design system already has an equivalent. If the primitive exists but lacks a modifier (placeholder, size, error binding), **add the modifier to the primitive** in its `+Modifiers` extension  -  do not fork the primitive into the consumer domain. The Figma `CodeConnectSnippet` is the authoritative pointer to which primitive to use.
+- **Design system primitives before custom views.** Before writing a new View / Configuration triplet in a feature module, grep the shared component library (e.g. `Common/UIComponents/`, `core-ui/`, `packages/ui/`) for a primitive that already solves it. Domain-level wrappers, custom modals, buttons or toasts are forbidden when the design system has an equivalent. If the primitive exists but lacks a modifier (placeholder, size, error binding), **add the modifier to the primitive** in its `+Modifiers` extension; never fork it into the consumer domain. The Figma `CodeConnectSnippet` is the authoritative pointer to which primitive to use.
 
 ## Swift-Specific Rules
 

package/pipeline/schemas/agent-state.schema.json

@@ -650,6 +650,90 @@
             "type": "string",
             "enum": ["fix", "accept", "escalate"]
           },
+          "delta": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Written by Phase 4 Step 3.8 from review-delta.mjs: how this round's accepted findings relate to the previous round's rework mandate. Absent on iteration 1 and on runs from before the delta existed.",
+            "properties": {
+              "previousIteration": { "type": "integer", "minimum": 1 },
+              "new": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": true,
+                  "properties": {
+                    "fingerprint": { "type": "string" },
+                    "severity": { "type": ["string", "null"] },
+                    "file": { "type": ["string", "null"] },
+                    "issue": { "type": ["string", "null"] }
+                  }
+                }
+              },
+              "stillPresent": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": true,
+                  "properties": {
+                    "fingerprint": { "type": "string" },
+                    "severity": { "type": ["string", "null"] },
+                    "file": { "type": ["string", "null"] },
+                    "issue": { "type": ["string", "null"] }
+                  }
+                }
+              },
+              "resolved": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": true,
+                  "properties": {
+                    "fingerprint": { "type": "string" },
+                    "severity": { "type": ["string", "null"] },
+                    "file": { "type": ["string", "null"] },
+                    "issue": { "type": ["string", "null"] }
+                  }
+                }
+              },
+              "downgraded": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": true,
+                  "properties": {
+                    "fingerprint": { "type": "string" },
+                    "severity": { "type": ["string", "null"] },
+                    "file": { "type": ["string", "null"] },
+                    "issue": { "type": ["string", "null"] }
+                  }
+                }
+              },
+              "stillPresentBlocking": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": true,
+                  "properties": {
+                    "fingerprint": { "type": "string" },
+                    "severity": { "type": ["string", "null"] },
+                    "file": { "type": ["string", "null"] },
+                    "issue": { "type": ["string", "null"] }
+                  }
+                }
+              },
+              "recurrence": {
+                "type": "object",
+                "additionalProperties": { "type": "integer", "minimum": 1 },
+                "description": "fingerprint -> consecutive rework cycles the finding has survived."
+              },
+              "plateau": {
+                "type": "boolean",
+                "description": "The still-present set is unchanged from the previous delta and non-empty."
+              },
+              "tripped": { "type": "boolean" },
+              "computedAt": { "type": "string", "format": "date-time" }
+            }
+          },
           "reviewers": {
             "type": "array",
             "description": "One entry per reviewer dispatch that RETURNED. Typed because two consumers depend on the shape: anonymize-findings.mjs needs model+findings to build the label map, and run-metrics.mjs reports acceptedRatio per reviewer. Extra keys are allowed; nothing is required, so a run written before this shape existed still validates and surfaces as model \"unknown\" rather than failing.",
@@ -699,6 +783,51 @@
         }
       }
     },
+    "circuitBreaker": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Autopilot circuit-breaker record (refs/features/autopilot-circuit-breaker.md). Written only when a trigger trips: trigger 2 by Phase 4 Step 3.8 (a mandate finding survived identicalFindingCycles rework cycles), trigger 3 by the Phase 3 re-entry hard-kill. /multi-agent:resume clears tripped and keeps counters.",
+      "required": ["tripped"],
+      "properties": {
+        "tripped": { "type": "boolean" },
+        "trigger": { "type": ["integer", "null"], "minimum": 1, "maximum": 5 },
+        "detail": { "type": "string" },
+        "checkpoint": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "phase": { "type": "integer", "minimum": 0, "maximum": 7 },
+            "step": { "type": "string" },
+            "iteration": { "type": "integer", "minimum": 1 }
+          }
+        },
+        "trippedAt": { "type": "string", "format": "date-time" },
+        "counters": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "identicalFindingCycles": { "type": "integer", "minimum": 0 },
+            "reworkCycles": { "type": "integer", "minimum": 0 }
+          }
+        }
+      }
+    },
+    "diffRisk": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Totals from diff-risk-score.mjs, persisted by Phase 4 Step 1.75 so Phase 6 (PR risk section), Phase 7 and run-metrics.mjs read the same numbers the review scope decision used.",
+      "properties": {
+        "files": { "type": "integer", "minimum": 0 },
+        "loc_added": { "type": "integer", "minimum": 0 },
+        "loc_removed": { "type": "integer", "minimum": 0 },
+        "max_score": { "type": "number" },
+        "signals": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Distinct signal names seen across files (security_path, migration, public_api, no_test_change, test_lines_removed, ...)."
+        }
+      }
+    },
     "confluenceSpace": {
       "type": ["string", "null"],
       "description": "Cached Confluence space key for the project  -  avoids re-asking on every run."