@mmerterden/multi-agent-pipeline 16.18.0 → 16.20.0

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

@@ -104,7 +104,7 @@ If changes include UI files (iOS: `*View.swift`, `*Screen.swift`, `*Cell.swift`;
 - Missing safe area / keyboard avoidance → **important**
 - Hardcoded colors instead of system/semantic colors → **suggestion**
 
-**iOS  -  SwiftUI interaction & accessibility conventions.** Gated to changed SwiftUI files. These are rule-registry territory as of v14.0.0, not a list transcribed here: Step 1.78 resolves them from whichever registry declares SwiftUI scope, so the criteria and their severities live in one place instead of drifting between this doc and the skill. Reviewers receive the resolved rule IDs. Native-SwiftUI-first unless the project's `figma-config` `ui.*` declares a custom system, in which case check against that system. Reference skills, when no registry covers the change: `figma-navigation`, `figma-overlays`, `figma-bottom-sheets`, `figma-to-swiftui`.
+**iOS  -  SwiftUI interaction & accessibility conventions.** Gated to changed SwiftUI files. These are rule-registry territory as of v14.0.0, not a list transcribed here: Step 1.78 resolves them from whichever registry declares SwiftUI scope, so the criteria and their severities live in one place instead of drifting between this doc and the skill. Reviewers receive the resolved rule IDs. Native-SwiftUI-first unless the project's `figma-config` `ui.*` declares a custom system, in which case check against that system. Reference skills, when no registry covers the change: the enabled stack plugin's `navigation`, `overlays` and `bottom-sheets` skills (`ai-ios-toolkit:*` / `ai-android-toolkit:*`), plus `figma-to-swiftui`.
 
 **Android  -  Material Design compliance** (skills: `ai-android-toolkit:compose-components`, `ai-android-toolkit:android-architecture`):
 - Non-Material3 component when M3 equivalent exists → **suggestion**
@@ -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.)
 
@@ -303,17 +311,19 @@ looks like it ran. The full statement lives in the managed block at `~/.codex/AG
 Sub-agent delegation itself is authorized by that same managed block; without it Phase 4
 degrades to a single in-thread review.
 
-**Single-vendor caveat.** Every Codex reviewer is an OpenAI model, so the
-cross-vendor disagreement that Claude Code and Copilot CLI get for free is absent.
-The diversity budget shifts to reasoning effort and persona focus: Reviewer 1 runs
-`xhigh` on security and architecture, Reviewer 2 runs a different model family
-member on edge cases, Reviewer 3 runs `medium` on quality. Treat consensus among
-them as weaker evidence than the same consensus on a two-vendor host, and say so
-in the triage note when all three agree on a borderline finding.
+**Single-vendor caveat.** Every Codex reviewer is an OpenAI model, and every Claude
+Code reviewer is an Anthropic model, so the cross-vendor disagreement that Copilot CLI
+gets for free (GPT-5.4 beside two Claude models) is absent on both. The diversity budget
+shifts to model generation, reasoning effort and persona focus: on Codex Reviewer 1 runs
+`xhigh` on security and architecture, Reviewer 2 runs a different model family member
+on edge cases, Reviewer 3 runs `medium` on quality; on Claude Code the three slots are
+three different Claude tiers. Treat consensus among a single-vendor panel as weaker
+evidence than the same consensus on Copilot CLI, and say so in the triage note when all
+three agree on a borderline finding.
 
 Each reviewer inherits the `code-reviewer` agent's focus areas (Security, Architecture, Quality, Performance) and output contract. The orchestrator overrides only the model and the stack-specific skill per-reviewer  -  no prompt duplication.
 
-**Model override wiring:** `code-reviewer.md` declares `preferredModel: fable`, so Reviewer 1 uses the persona default (Fable 5). Reviewer 2 (`claude-opus-5` on Claude Code, `gpt-5.4` elsewhere) and Reviewer 3 (`claude-sonnet-5`) set `PHASE_MODEL_OVERRIDE=<model>` before dispatch  -  the orchestrator exports `CLAUDE_CODE_SUBAGENT_MODEL` on Claude Code, or passes `--model` on Copilot CLI. Full precedence rule: `skills/shared/core/multi-agent/SKILL.md#agent-dispatch--per-persona-model-routing-v610`. Fable dispatches are subject to the fallback contract (`$HOME/.claude/multi-agent-refs/features/model-fallback.md`): dispatch-error retry walks `fable -> opus -> sonnet` and budget-ceiling downgrade.
+**Model override wiring:** `code-reviewer.md` declares `preferredModel: fable`, so Reviewer 1 uses the persona default (Fable 5). Reviewer 2 (`claude-opus-5` on Claude Code, `gpt-5.4` elsewhere) and Reviewer 3 (`claude-sonnet-5`) set `PHASE_MODEL_OVERRIDE=<model>` before dispatch  -  the orchestrator exports `CLAUDE_CODE_SUBAGENT_MODEL` on Claude Code, or passes `--model` on Copilot CLI. Full precedence rule: `skills/shared/core/multi-agent/SKILL.md#agent-dispatch--per-persona-model-routing`. Fable dispatches are subject to the fallback contract (`$HOME/.claude/multi-agent-refs/features/model-fallback.md`): dispatch-error retry walks `fable -> opus -> sonnet` and budget-ceiling downgrade.
 
 **Stack-specific skills loaded per reviewer** (from Phase 1 `detectedStack`). All three columns are used on every host; Reviewer 2 reads them as Opus on Claude Code and as GPT-5.4 elsewhere.
 
@@ -326,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)
 
@@ -380,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)
@@ -401,7 +416,7 @@ Exit 0 = valid. Exit 2 = contradiction (approved=true with blocking findings)  -
    - Max one round. Results replace the original outputs.
 4. Proceed to Step 3 triage with the round-2 outputs.
 
-**Parity contract:** both CLI sides (Claude 2-model, Copilot 3-model) run the round identically. Telemetry emits `review_round_count={1|2}` per reviewer for Phase 7 rollup.
+**Parity contract:** every host (three reviewers each: Claude Code, Copilot CLI, Codex CLI) runs the round identically. Telemetry emits `review_round_count={1|2}` per reviewer for Phase 7 rollup.
 
 **Cost ceiling:** rebuttal round consumes ~1× the original Step 2 token budget. Smoke + budget tests treat this as opt-in so the default cost stays the same.
 
@@ -495,8 +510,9 @@ bash $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 4 memory.hit rows=$CITED_COU
 **Triage prompt skeleton:**
 
 ```
-You are the Review Triage agent. Two reviewers returned findings on this diff.
+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
@@ -527,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                        |
@@ -567,10 +588,13 @@ emit() {  # $1=event $2=model $3=duration $4=tokens_in $5=tokens_out
     model="$2" duration_ms="$3" tokens_in="$4" tokens_out="$5"
 }
 emit review.reviewer_call fable  "$R1_DURATION"     "$R1_IN"     "$R1_OUT"      # opus on Copilot CLI
-emit review.reviewer_call sonnet "$SONNET_DURATION" "$SONNET_IN" "$SONNET_OUT"
 # Reviewer 2 is Opus on Claude Code and GPT-5.4 elsewhere:
-[ "${CLI_HOST:-claude}" = "copilot" ] && \
-  emit review.reviewer_call gpt-5.4 "$GPT_DURATION" "$GPT_IN" "$GPT_OUT"
+if [ "${CLI_HOST:-claude}" = "claude" ]; then
+  emit review.reviewer_call opus    "$R2_DURATION" "$R2_IN" "$R2_OUT"
+else
+  emit review.reviewer_call gpt-5.4 "$R2_DURATION" "$R2_IN" "$R2_OUT"
+fi
+emit review.reviewer_call sonnet "$SONNET_DURATION" "$SONNET_IN" "$SONNET_OUT"
 emit review.triage_call fable "$TRIAGE_DURATION" "$TRIAGE_IN" "$TRIAGE_OUT"
 bash "$M" "$TASK_ID" 4 review.completed raw_count=$RAW accepted=$ACC \
   deferred=$DEF rejected=$REJ approved=$APPROVED duration_ms=$DURATION
@@ -584,7 +608,7 @@ Opt-in via `prefs.global.triageCrossCheck.enabled` (default `false`). Sampled ru
 
 ##### 3.6 Consensus surfacing (anti-correlation)
 
-**Rationale:** Reviewer 1 (Fable) and Reviewer 3 (Sonnet) are both Anthropic Claude models, so unanimous agreement on a *judgment call* is not independent confirmation  -  same-family models drift the same way on ambiguous prompts. Treating "both approved" as proof produces false-consensus passes. Triage therefore records a `consensus` block (schema v3.1.0) and surfaces disagreement and unverified agreement to the user rather than burying it.
+**Rationale:** On Claude Code all three reviewers are Anthropic models, on Codex CLI all three are OpenAI, and on Copilot CLI two of three are Anthropic, so unanimous agreement on a *judgment call* is not independent confirmation: same-family models drift the same way on ambiguous prompts, and "all approved" taken as proof produces false-consensus passes. Triage therefore records a `consensus` block (schema v3.1.0) and surfaces disagreement and unverified agreement instead of burying it.
 
 After the triage verdict is computed, populate `triage.consensus`:
 
@@ -602,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)
 
@@ -610,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)
@@ -631,7 +674,7 @@ Statement shape: the durable rule/root cause, not the symptom  -  "force-unwrapp
 
 Progress line: `    → writing lesson to learnings ledger ({N} entries)`
 
-Log: "Phase 4: Review  -  raw={N1+N2} accepted={Na} deferred={Nd} rejected={Nr} approved={bool} consensus={verdict}"
+Log: "Phase 4: Review  -  raw={N1+N2+N3} accepted={Na} deferred={Nd} rejected={Nr} approved={bool} consensus={verdict}"
 
 ---
 

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/multi-agent-refs/tracker-contract.md

@@ -246,7 +246,7 @@ bash $HOME/.claude/scripts/phase-tracker.sh model  <N> <model_name>
 
 Token counts are additive  -  multiple calls accumulate. `input_count` is FRESH input (cache-exclusive); the optional 4th arg is the prompt-cache-read count, priced at the discounted rate. `model` tags the phase so the card and the cost helper can price it. Stored per phase in the state file; surfaced in `:log` reports, on the bash card tile (`<elapsed> · <tok> tok · ~$<usd>`), and in the card footer (total USD + cached tokens).
 
-**MANDATORY: per-phase token narration on completion (v9.10.2).** The native
+**Required: per-phase token narration on completion (v9.10.2).** The native
 TaskList widget cannot display per-phase tokens  -  it shows name, status, and
 duration only. Without this rule the user sees durations and nothing else
 until the Phase 7 Cost Breakdown. So whenever a phase transitions to

package/pipeline/rules/figma-pipeline.md

@@ -96,7 +96,7 @@ Re-fetching Figma in dev phases:
 
 ### Verification
 
-The pipeline ships a smoke gate `pipeline/scripts/smoke-no-mcp-in-dev-phases.sh` that reads `state.telemetry.mcpCalls[]`. If any entry has `phase >= 2`, the gate fails. CI runs this gate after every run as a regression check.
+The pipeline ships a smoke gate `pipeline/scripts/smoke-no-mcp-in-dev-phases.sh` that reads `state.telemetry.mcpCalls[]`. If any entry has `phase >= 2`, the gate fails. It is a maintainer-side regression check: it runs locally as part of `npm test` and the pre-push hook, not in CI (the CI workflow is dormant) and not after every pipeline run.
 
 Memory: [[mcp-only-in-analysis]]
 
@@ -174,12 +174,14 @@ When Figma pipeline is active (`figmaConfigPath` set in project preferences),
 multi-agent Phase 3 (DEV) dispatches Figma sub-phases instead of standard TDD:
 
 ```
-Phase 3.0: figma-to-swift-ui-start    → Branch, assign, registry
-Phase 3.1: figma-to-swiftui           → Full 8-phase implementation
-Phase 3.2: figma-commit               → 14-item review + commit + PR
-Phase 3.3: figma-iteration-commit     → Batch iteration commit (if iterating)
+Phase 3.0: figma-validate                          → registry, Code Connect, token compliance (halts Phase 3 on failure)
+Phase 3.1: create-component / create-screen        → full implementation by the enabled stack plugin (evolve-component for an existing one)
+Phase 3.2: figma-commit                            → 14-item review + commit + PR
+Phase 3.3: figma-iteration-commit                  → Batch iteration commit (if iterating)
 ```
 
+Skill names are the enabled stack plugin's (`ai-ios-toolkit:*` / `ai-android-toolkit:*`); the dispatch contract is `multi-agent-refs/component-dispatch.md`.
+
 ### Abstraction Layers
 
 | Layer | Provider Options | Config |
@@ -219,70 +221,14 @@ Provider interfaces are defined inline in the plugin skill sets  -  see the `ai-
 13. Build verification (xcodebuild)
 14. Test verification (ViewInspector + Snapshot)
 
-### Command Catalog (31 commands)
-
-**Core Pipeline:**
-
-| Command | What It Does |
-|---------|-------------|
-| `/figma-to-swiftui <url>` | Full 8-phase pipeline |
-| `/figma-to-swift-ui-start #N` | Start from issue: branch, assign |
-| `/figma-to-swift-ui-implement <url>` | Phases 0-4 only (implementation) |
-| `/figma-to-swift-ui-test <url>` | Phase 5 only (tests) |
-| `/figma-to-swift-ui-wiki <Name>` | Phase 7 only (wiki docs) |
-| `/figma-to-swift-ui-code-connect <url>` | Phase 6 only (Code Connect) |
-| `/figma-to-swift-ui-confluence-sync` | Sync wiki → Confluence |
-| `/figma-to-swift-ui-status-update` | Refresh Confluence dashboard |
-
-**Issue & Board:**
-
-| Command | What It Does |
-|---------|-------------|
-| `/figma-issue open <url>` | Create GitHub Issue + optional Jira |
-| `/figma-review <Name>` | Interactive review (approve/bug) |
-| `/figma-validate <url>` | Pre-implementation validation |
-
-**Commit & PR:**
-
-| Command | What It Does |
-|---------|-------------|
-| `/figma-commit <Name>` | 14-item review + commit + PR |
-| `/figma-iteration-commit <Name>` | Commit to iteration/develop + PR |
-
-**Iteration & Batch:**
-
-| Command | What It Does |
-|---------|-------------|
-| `/figma-iterate` | Auto loop: pick → implement → commit |
-| `/figma-cli-iterate` | Full CLI iterate (all phases) |
-| `/figma-cli-lean-iterate` | Lean iterate (skip test+wiki) |
-| `/figma-cli-iterate-mend` | Re-implement discarded components |
-| `/figma-cli-skip` | Mark component as skipped |
-| `/figma-skip` | Skip + update Confluence |
-
-**Bugfix:**
-
-| Command | What It Does |
-|---------|-------------|
-| `/figma-fix` | Apply targeted bug fixes |
-| `/figma-mend` | Re-implement from scratch |
-
-**Setup & Utility:**
-
-| Command | What It Does |
-|---------|-------------|
-| `/figma-setup` | Environment setup wizard |
-| `/figma-utility` | Figma data fetch (screenshots, metadata) |
-| `/figma-remote-mcp-auth` | Figma MCP OAuth flow |
-| `/figma-ui-patterns` | UI pattern library index |
-| `/figma-price-integration` | Price protocol adoption guide |
-
-**Performance (batch production):**
-
-| Command | What It Does |
-|---------|-------------|
-| `/performance-start #N` | Start component with perf tracking |
-| `/performance-swiftui` | Perf-optimized pipeline |
-| `/performance-tour` | Batch produce multiple components |
-| `/performance-review-next` | Interactive batch review |
-| `/performance-iteration-commit-all` | Batch validate + push all |
+### Figma Skill Surfaces (current)
+
+The old 31-command personal catalog is retired; none of those `/figma-*` commands ships with the pipeline. Figma capabilities live on three surfaces. Screens are ALWAYS drawn 1:1 from the Figma design context resolved in analysis, and a Code Connect-mapped component is ALWAYS used when one exists (see the fallback chain + Code Connect rules above).
+
+| Surface | What it carries | When to use |
+|---------|-----------------|-------------|
+| `ai-ios-toolkit` / `ai-android-toolkit` (marketplace stack plugins, enabled per repo by `/multi-agent:stack`; skill names below are the iOS plugin's, the Android plugin carries the Compose equivalents) | Component skills: `create-component`, `create-screen`, `evolve-component`, `figma-validate`, `figma-review`, `figma-commit`, `figma-iteration-commit`, `figma-component-start`, `figma-utility`, `figma-setup`, `code-connect`, `component-docs`, `component-wiki`, plus the `navigation` / `overlays` / `bottom-sheets` / `ui-patterns` reference skills | Direct component work in a repo where the stack plugin is enabled; Phase 3 dispatches here for `taskType === component` |
+| Pipeline commands | `/multi-agent:analysis` (the only phase allowed to fetch Figma), `/multi-agent:design-check` (mock-mode vs Figma conformance, Phase 4 Step 2.8), `/multi-agent:review` (cites the analysis doc, never Figma) | Inside multi-agent pipeline runs |
+| Legacy `/figma-to-swiftui` (single standalone command) | The old full 8-phase flow | Kept for the old flow only; prefer the plugin's `create-component` for new work |
+
+The pipeline keeps no Figma command catalog of its own: the routing table for component skills is maintained inside each stack plugin's `index` skill, and `/multi-agent:stack` decides which plugin is active for a repo.

package/pipeline/rules/outside-the-pipeline.md

@@ -21,6 +21,7 @@ available. Read the effective `enabledPlugins` and load each enabled toolkit's
 `ai-common-toolkit` and `ai-analyst-toolkit` are on everywhere. Nothing enabled
 is a normal state.
 
-**multi-agent-toolkit MCP.** 80+ tools for a running app: `ui-inspect`,
-`crash-logs`, `design-check`, `ios-app-store-audit`, `ios-testflight`. Use them
-instead of guessing about on-screen state. Not registered is a silent no-op.
+**multi-agent-toolkit MCP.** 80+ tools for a running app: `ios_get_ui_tree` /
+`android_get_ui_tree`, `ios_list_crashes` / `android_list_crashes`, `design_*`,
+`ios_app_store_audit`, `ios_testflight_validate`. Use them instead of guessing
+about on-screen state. Not registered is a silent no-op.

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

@@ -107,7 +107,7 @@
     "siblings": {
       "type": "array",
       "maxItems": 10,
-      "description": "Repos the dev-context picker offered that this run does not modify: read-only siblings, plus any extra the user selected. Persisted at Phase 0 because the phases that consume them run much later - Phase 4's platform-parity cross-check reads this and nothing else, so a picker result that is not written here is a step that can never fire.",
+      "description": "Repos the dev-context picker offered that this run does not modify: read-only siblings, plus any extra the user selected. Persisted at Phase 0 because the phases that consume them run much later - Phase 4's platform-parity cross-check reads this as the fourth of its four counterpart sources (after --with, prefs.projects[<slug>].counterpartRoots[] and the primary checkout's sibling directories; see multi-agent-refs/platform-parity.md), so a picker result that is not written here is a candidate the check can never see.",
       "items": {
         "type": "object",
         "additionalProperties": false,
@@ -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."