@mmerterden/multi-agent-pipeline 16.19.0 → 16.20.0

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/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."

package/pipeline/schemas/dev-critic-output.schema.json

@@ -100,6 +100,11 @@
             "description": "Citation. Format: 'rules/<file>.md#<anchor>' or 'gate/<name>'."
           },
           "issue": { "type": "string", "description": "Short, one-sentence description." },
+          "fingerprint": {
+            "type": "string",
+            "pattern": "^F:[0-9a-f]{8}$",
+            "description": "Stable id computed by finding-fingerprint.mjs --kind dev-critic. Round-2 findings carry the round-1 fingerprint; a round-2 finding with none is the scope creep the loop contract forbids."
+          },
           "fix": {
             "type": "string",
             "description": "Concrete suggestion the generator can act on without re-reading the rule."

package/pipeline/schemas/prefs.schema.json

@@ -927,6 +927,53 @@
               "maximum": 1800,
               "default": 600,
               "description": "Wall-clock budget for the whole Step 3.7 pass. On breach, remaining findings keep judgment-only verdicts and the pipeline proceeds (never blocks)."
+            },
+            "repeatCount": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 10,
+              "default": 3,
+              "description": "v16.20+ - how many times a repro test must pass before a finding is downgraded to not-reproduced. Any red run makes the verdict inconclusive with a flaky note. 1 disables the repeat."
+            }
+          }
+        },
+        "autopilotCircuitBreaker": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "v16.20+ - autopilot circuit-breaker (refs/features/autopilot-circuit-breaker.md). Trigger 2 (a finding that survives consecutive rework cycles) and trigger 3 (the rework-cycle cap) are evaluated in code; the other triggers stay documented behaviour. When a trigger trips in autopilot the run halts visibly with state.circuitBreaker set; interactive modes show the still-present list and ask instead.",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": true,
+              "description": "Master switch for the code-evaluated triggers."
+            },
+            "identicalFindingCycles": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 5,
+              "default": 2,
+              "description": "Consecutive rework cycles a blocking/important finding may survive before trigger 2 trips (review-delta.mjs --trip-cycles)."
+            },
+            "maxReworkCycles": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 3,
+              "default": 3,
+              "description": "Phase 4 -> Phase 3 rework cycles before trigger 3 trips. Bounded above by the Phase 3 retryCount hard-kill."
+            }
+          }
+        },
+        "testStability": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "v16.20+ - a test that passes only on retry is a flake signal, not a pass. Phase 3 runs new and changed tests repeatCount times before GREEN; disagreeing outcomes block and are recorded as test.flake_signal.",
+          "properties": {
+            "repeatCount": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 10,
+              "default": 3,
+              "description": "Runs per new or changed test. 1 disables the repeat."
             }
           }
         },

package/pipeline/schemas/reviewer-output.schema.json

@@ -1,9 +1,9 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/reviewer-output.schema.json",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "title": "Multi-Agent Pipeline  -  Phase 4 reviewer output",
-  "description": "Contract for a single code-reviewer subagent's JSON output in Phase 4 Step 2. Every host dispatches 3 parallel reviewers; the middle slot is CLI-aware: Claude Code (Fable, Opus, Sonnet); Copilot CLI (Opus, GPT-5.4, Sonnet); Codex CLI dispatches 3 (gpt-5.6 at xhigh, gpt-5.4, gpt-5.6 at medium). Every reviewer must return an object matching this shape before Opus triage merges them. v1.1.0 adds the rule-ID conformance checklist: when the orchestrator supplies a ${CRITERIA} block (Phase 4 Step 1.78), the reviewer must return one conformance row per selected rule ID. Findings alone cannot answer 'was this applied completely' - a reviewer that opened nothing returns the same empty findings array as one that checked everything.",
+  "description": "Contract for a single code-reviewer subagent's JSON output in Phase 4 Step 2. Every host dispatches 3 parallel reviewers; the middle slot is CLI-aware: Claude Code (Fable, Opus, Sonnet); Copilot CLI (Opus, GPT-5.4, Sonnet); Codex CLI dispatches 3 (gpt-5.6 at xhigh, gpt-5.4, gpt-5.6 at medium). Every reviewer must return an object matching this shape before Opus triage merges them. v1.1.0 adds the rule-ID conformance checklist: when the orchestrator supplies a ${CRITERIA} block (Phase 4 Step 1.78), the reviewer must return one conformance row per selected rule ID. Findings alone cannot answer 'was this applied completely' - a reviewer that opened nothing returns the same empty findings array as one that checked everything. v1.2.0 adds the optional per-finding fingerprint (Phase 4 Step 2.1): the stable id a finding keeps across review rounds.",
   "type": "object",
   "additionalProperties": false,
   "required": ["findings", "approved"],
@@ -97,6 +97,11 @@
           "type": "string",
           "minLength": 1,
           "description": "Which criteria source the rule came from: a registry name, a module-guide path, or 'exception-marker-audit'. Lets Phase 7 attribute findings to the standard that produced them."
+        },
+        "fingerprint": {
+          "type": "string",
+          "pattern": "^F:[0-9a-f]{8}$",
+          "description": "Stable cross-round identity of the finding, computed by finding-fingerprint.mjs from (file, ruleId or normalized issue text). Never includes the line. On iteration >= 2 a reviewer that recognises an entry from <previous-round-findings> echoes its fingerprint; otherwise leave it unset and the script fills it in."
         }
       }
     }

package/pipeline/schemas/scope-check.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/scope-check.schema.json",
+  "version": "1.0.0",
+  "title": "Multi-Agent Pipeline  -  Phase 3 scope self-check",
+  "description": "Written by Phase 3 Step 3.7 to $WORKTREE/.pipeline/scope-check.json before the Phase 4 handoff: one stated reason per file in the diff, the changes deliberately not made, and the code-simplifier rationales. scope-check-gate.mjs compares files[] with the real diff; Phase 4 injects the record as <scope-self-check>; Phase 6 builds the PR Changes bullets and the follow-up list from it.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "taskId", "files"],
+  "properties": {
+    "version": { "type": "string", "const": "1.0.0" },
+    "taskId": { "type": "string", "minLength": 1 },
+    "files": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "reason"],
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Repo-relative path as it appears in git diff --name-only."
+          },
+          "reason": {
+            "type": "string",
+            "minLength": 4,
+            "description": "Why this task needs this exact file. Names the requirement, never 'while I was here'."
+          }
+        }
+      }
+    },
+    "notDone": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["what", "why"],
+        "properties": {
+          "what": { "type": "string", "minLength": 4 },
+          "why": { "type": "string", "enum": ["out-of-scope", "follow-up", "rejected-abstraction"] }
+        }
+      }
+    },
+    "simplifier": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "applied": { "type": "integer", "minimum": 0 },
+        "skipped": { "type": "integer", "minimum": 0 },
+        "rationales": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}