@mmerterden/multi-agent-pipeline 8.6.2 → 10.2.0

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

@@ -1,28 +1,40 @@
 ### Phase 4: Review (deterministic gates + parallel + triage)
 
-> **TLDR** — Three-stage review. Stage 1: deterministic gates (build + lint + test + secret scan) that MUST pass. Stage 2: AI models in parallel — reviewer set is **CLI-aware**: Claude Code dispatches 2 reviewers (Opus + Sonnet); Copilot CLI dispatches 3 reviewers (GPT-5.4 + Opus + Sonnet). Stage 3: Opus triage — evaluates raw findings, filters false-positives/out-of-scope, keeps only actionable items. Only triage-accepted blocking items loop back to Phase 3.
+> **TLDR**  -  Three-stage review. Stage 1: deterministic gates (build + lint + test + secret scan) that MUST pass. Stage 2: AI models in parallel  -  reviewer set is **CLI-aware**: Claude Code dispatches 2 reviewers (Opus + Sonnet); Copilot CLI dispatches 3 reviewers (GPT-5.4 + Opus + Sonnet). Stage 3: Opus triage  -  evaluates raw findings, filters false-positives/out-of-scope, keeps only actionable items. Only triage-accepted blocking items loop back to Phase 3.
 
 <!-- progress-contract: applied -->
-Progress emission per `refs/progress-contract.md` — lines for each gate, each reviewer dispatch + finish, triage start, triage verdict, fix dispatch.
+Progress emission per `refs/progress-contract.md`  -  lines for each gate, each reviewer dispatch + finish, triage start, triage verdict, fix dispatch.
 
-#### Step 1 — Deterministic Gates (run BEFORE AI review)
+#### Step 1  -  Deterministic Gates (run BEFORE AI review)
 
 If any gate fails → fix first, don't waste AI tokens reviewing broken code.
 
 ```bash
-# Gate 1: Build (Xcode uses build queue lock — see Phase 3)
-# Gate 2: Lint (swiftlint/ktlint/ruff/eslint — stack-dependent)
-# Gate 3: Tests pass (xcodebuild test/gradle test/pytest/npm test)
-# Gate 4: No secrets (grep for sk-/password=/api_key=/BEGIN PRIVATE KEY)
+# Gate 1: Build (Xcode uses build queue lock  -  see Phase 3)  -  tee output to a log
+xcodebuild ... 2>&1 | tee "$WORKTREE/.build.log"
+# Gate 2: Lint (swiftlint/ktlint/ruff/eslint  -  stack-dependent)
+# Gate 3: Tests pass (xcodebuild test/gradle test/pytest/npm test)  -  tee output to a log
+<test-command> 2>&1 | tee "$WORKTREE/.test.log"
+# Gate 4: Secrets  -  run the scanner against the staged diff
+bash pipeline/scripts/pre-commit-check.sh
 ```
 
+**Default-FAIL evidence gate (required before recording any pass):** a green exit code is not enough  -  the captured log must actually show success. Before marking build/test passed, run the evidence gate against the tee'd log; it fails CLOSED when the log is missing, empty, or shows failure markers:
+
+```bash
+node pipeline/scripts/evidence-gate.mjs --claim build --status passed --evidence "$WORKTREE/.build.log" || BUILD_PASS=false
+node pipeline/scripts/evidence-gate.mjs --claim test  --status passed --evidence "$WORKTREE/.test.log"  || TEST_PASS=false
+```
+
+This prevents a false "it built" claim with no log behind it. On exit 1, treat the gate as failed (do NOT proceed to AI review) and surface the gate's `reason`.
+
 **Gate results:**
 
-- All pass -> proceed to AI review
+- All pass (including the evidence gate) -> proceed to AI review
 - Any fail -> fix immediately, re-run gates (no AI review until clean)
-  Log: "Phase 4: Gates — build:{pass/fail} lint:{pass/fail} test:{pass/fail} secrets:{clean/found}"
+  Log: "Phase 4: Gates  -  build:{pass/fail} lint:{pass/fail} test:{pass/fail} secrets:{clean/found} evidence:{ok/unverified}"
 
-##### Gate 5 — Fortify SSC findings (runs when `state.contextLinks[]` contains a `fortify` entry, or when `prefs.global.fortify.alwaysCheck === true`)
+##### Gate 5  -  Fortify SSC findings (runs when `state.contextLinks[]` contains a `fortify` entry, or when `prefs.global.fortify.alwaysCheck === true`)
 
 If the task description referenced a Fortify version, `~/.claude/lib/fetch-fortify.sh` already populated `state.fortifyFinding` in Phase 0. Phase 4 reuses that payload and applies the deterministic gate:
 
@@ -35,7 +47,7 @@ elif [ "$(jq -r '.fortifyFinding.gateOutcome.blocking' "$STATE_FILE")" = "true"
   reason=$(jq -r '.fortifyFinding.gateOutcome.reason' "$STATE_FILE")
   critical=$(jq -r '.fortifyFinding.severityCounts.Critical' "$STATE_FILE")
   echo "→ fortify gate: BLOCKED ($reason, critical=$critical)"
-  # Treat as a deterministic gate failure — fix the critical findings before AI review.
+  # Treat as a deterministic gate failure  -  fix the critical findings before AI review.
   exit 1
 else
   high=$(jq -r '.fortifyFinding.severityCounts.High // 0' "$STATE_FILE")
@@ -47,13 +59,13 @@ Gate semantics:
 
 | `gateOutcome.reason` | Phase 4 action |
 |---|---|
-| `critical-findings` | **Blocking** — Phase 3 re-dispatches with the finding list; pipeline does not advance until Critical count is 0. |
-| `high-findings-warning` | Pass-with-warning — High findings appear in the channels summary (`## Güvenlik Taraması (Fortify)` section in PR + Jira); they don't block the merge. |
-| `clean` | Pass silently — section omitted from the channels summary. |
+| `critical-findings` | **Blocking**  -  Phase 3 re-dispatches with the finding list; pipeline does not advance until Critical count is 0. |
+| `high-findings-warning` | Pass-with-warning  -  High findings appear in the channels summary (`## Security Scan (Fortify)` section in PR + Jira); they don't block the merge. |
+| `clean` | Pass silently  -  section omitted from the channels summary. |
 
-When `state.fortifyFinding.status === "skipped"` (token missing, VPN unreachable, or host mismatch) the gate logs `→ fortify gate: skipped (<reason>)` and never blocks — the user already saw the structured Save Flow signal at Phase 0 and chose to proceed.
+When `state.fortifyFinding.status === "skipped"` (token missing, VPN unreachable, or host mismatch) the gate logs `→ fortify gate: skipped (<reason>)` and never blocks  -  the user already saw the structured Save Flow signal at Phase 0 and chose to proceed.
 
-#### Step 1.5 — Platform Compliance Review (skill-based, no device needed)
+#### Step 1.5  -  Platform Compliance Review (skill-based, no device needed)
 
 If changes include UI files (iOS: `*View.swift`, `*Screen.swift`, `*Cell.swift`; Android: `*Screen.kt`, `*Content.kt`, `*Composable.kt`), run platform-specific checks:
 
@@ -63,13 +75,21 @@ If changes include UI files (iOS: `*View.swift`, `*Screen.swift`, `*Cell.swift`;
 - Missing `.accessibilityIdentifier` / `testTag` → **important**
 - Dynamic Type / font scaling not supported → **important**
 
-**iOS — Apple HIG compliance** (skills: `hig-patterns`, `hig-components-layout`, `hig-foundations`):
+**iOS  -  Apple HIG compliance** (skills: `hig-patterns`, `hig-components-layout`, `hig-foundations`):
 - Navigation pattern mismatch (e.g. custom back button instead of system) → **important**
 - Non-standard gesture without discoverability hint → **suggestion**
 - Missing safe area / keyboard avoidance → **important**
 - Hardcoded colors instead of system/semantic colors → **suggestion**
 
-**Android — Material Design compliance** (skills: `compose-components`, `android-architecture`):
+**iOS  -  SwiftUI interaction & accessibility conventions** (skills: `figma-navigation`, `figma-overlays`, `figma-bottom-sheets`, plus the enriched `figma-to-swiftui` accessibility rules). Gated to changed SwiftUI files; each is native-SwiftUI-first unless the project's `figma-config` `ui.*` declares a custom system, in which case check against that system instead:
+- A reusable component that **routes itself** (hardcoded `NavigationLink(destination: ConcreteScreen())`, calls a router) instead of emitting a typed `Output` → **important** (breaks reuse).
+- A reusable component that **presents its own app-level overlay** (toast/alert/modal) instead of emitting an intent for the caller → **important** (double-fires when composed).
+- `AnyView` routed through an overlay center / data-modal path (rich content should be a local `.sheet/.modal { }`) → **important**.
+- Loading HUD not **ref-counted** / missing `end` on an error path / no min-show (flash) → **important**.
+- A pinned bottom CTA built as a presented sheet instead of `.safeAreaInset(edge:.bottom)`, or detents that aren't ascending / use magic-number heights → **suggestion**.
+- **Accessibility over-annotation** (redundant `.isButton` on `Button` / `.isStaticText` on `Text`, `.accessibilityLabel` duplicating visible text, a per-enum-variant a11y key for non-interactive visual state, hints on self-explanatory actions) → **suggestion**; **missing** decorative-image hiding or interactive-state `.accessibilityValue` → **important**.
+
+**Android  -  Material Design compliance** (skills: `compose-components`, `android-architecture`):
 - Non-Material3 component when M3 equivalent exists → **suggestion**
 - Missing `contentDescription` on icons/images → **blocking**
 - Hardcoded dp values instead of Material spacing tokens → **suggestion**
@@ -80,17 +100,17 @@ If changes include UI files (iOS: `*View.swift`, `*Screen.swift`, `*Cell.swift`;
 
 Device-level audit runs in Phase 5 (`audit-guide.md`).
 
-#### Step 1.6 — Repo Map Injection (advisory, opt-in)
+#### Step 1.6  -  Repo Map Injection (advisory, opt-in)
 
-**Gated by `prefs.global.repoMap.enabled`** (default: `false`). Same pattern as Phase 1 Step 2.5 — runs `pipeline/scripts/repo-map.mjs` and injects the result as `${REPO_MAP}` into each reviewer's prompt context. Reviewers treat it the same way the priority files block is treated: advisory hint, not gospel.
+**Gated by `prefs.global.repoMap.enabled`** (default: `false`). Same pattern as Phase 1 Step 2.5  -  runs `pipeline/scripts/repo-map.mjs` and injects the result as `${REPO_MAP}` into each reviewer's prompt context. Reviewers treat it the same way the priority files block is treated: advisory hint, not gospel.
 
 Phase 4 reuses the cached map from Phase 1 when both phases run in the same task (avoid recomputing the same scan twice). The orchestrator caches under `state.repoMap.<sha>` keyed by `git rev-parse HEAD`; cache miss → regenerate. When `enabled=false`, both phases skip the script entirely and no `${REPO_MAP}` placeholder appears in prompts (no empty-string artefact).
 
-Cost ledger: `phase-4.repo_map_emitted bytes=N budget=B cache_hit=true|false` — Phase 7 cost rollup distinguishes a cache hit (free) from a regeneration (~150-300ms wall, 0 LLM cost either way).
+Cost ledger: `phase-4.repo_map_emitted bytes=N budget=B cache_hit=true|false`  -  Phase 7 cost rollup distinguishes a cache hit (free) from a regeneration (~150-300ms wall, 0 LLM cost either way).
 
-#### Step 1.75 — Diff Risk Scoring (advisory)
+#### Step 1.75  -  Diff Risk Scoring (advisory)
 
-Before dispatching reviewers, run the deterministic diff risk scorer and inject the top-N files into each reviewer's prompt as a priority hint. **Advisory only — never gates the pipeline.** Heuristic, zero LLM, runs in well under a second.
+Before dispatching reviewers, run the deterministic diff risk scorer and inject the top-N files into each reviewer's prompt as a priority hint. **Advisory only  -  never gates the pipeline.** Heuristic, zero LLM, runs in well under a second.
 
 ```bash
 RISK_JSON=$(node pipeline/scripts/diff-risk-score.mjs \
@@ -111,9 +131,9 @@ echo "$RISK_JSON" | node pipeline/scripts/validate-diff-risk.mjs - >/dev/null 2>
 | `ui_critical` | 1.5 | path matches `*View.swift`, `*Screen.kt`, `*Configuration.swift`, etc. |
 | `loc_changed` | 1.0 | base sensitivity to total `+/-` lines |
 
-**Reviewer prompt injection**: when `$RISK_JSON` is non-empty, the orchestrator builds a `${PRIORITY_FILES}` block (numbered list of top-N files with their score + signals) and injects it once per reviewer. Reviewer prompt template (`code-reviewer.md`) treats it as advisory and does not echo it back. Triage does not see the priority list — its job is to filter the merged findings, not the diff.
+**Reviewer prompt injection**: when `$RISK_JSON` is non-empty, the orchestrator builds a `${PRIORITY_FILES}` block (numbered list of top-N files with their score + signals) and injects it once per reviewer. Reviewer prompt template (`code-reviewer.md`) treats it as advisory and does not echo it back. Triage does not see the priority list  -  its job is to filter the merged findings, not the diff.
 
-**Gate behavior**: this step is **never blocking**. If risk scoring fails (git error, parse error, validator rejection), continue with no priority hint — reviewers receive the full diff in their default order. Failures are logged via metrics:
+**Gate behavior**: this step is **never blocking**. If risk scoring fails (git error, parse error, validator rejection), continue with no priority hint  -  reviewers receive the full diff in their default order. Failures are logged via metrics:
 
 ```bash
 [ -z "$RISK_JSON" ] && pipeline/scripts/log-metric.sh "$TASK_ID" 4 review.diff_risk_skipped reason=$REASON
@@ -130,9 +150,34 @@ pipeline/scripts/log-metric.sh "$TASK_ID" 4 review.diff_risk \
 
 **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.
 
-#### Step 2 — Parallel AI Review (CLI-aware reviewer set)
+#### Step 1.8  -  Figma visual-fidelity context (when task carries a Figma reference)
+
+When `state.evidence.figma[]` is non-empty, the reviewer subagents MUST receive the captured screenshot URLs / paths and the canonical-component name (from `state.evidence.figma[i].screenshotUrl` and `state.evidence.figma[i].codeConnectSnippets[0].componentName` when present) so they can compare visual fidelity. Pass them inline in each reviewer prompt under a `## Figma evidence` block, one row per frame.
+
+Visual-fidelity mismatches against the captured screenshot are BLOCKING findings, not nits:
+
+- Avatar icon (presence, glyph, shape, position)
+- Field grouping (one rounded box vs two; separator vs gap)
+- Character counter visibility
+- Header style (size, weight, alignment)
+- Inline error layout (icon presence, text colour, position relative to the input)
+- Button height
+- Indicator chip placement
+- Placeholder copy and position
+
+When `state.figmaAccess.tier === 3` (user-attached screenshot, no Code Connect snippet), the reviewer additionally sets `findings[i].severity = "blocking"` and `findings[i].tag = "review_blocking_tier3"` on every UI atom that lacks a confirmed canonical-component mapping. The triage step preserves these findings unless the user has explicitly cleared the open question.
+
+#### Step 1.9  -  Context economy (cache prefix + diff cap)
+
+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:
 
-Launch Agent instances **in parallel** using the shared `code-reviewer` subagent definition (`~/.claude/agents/code-reviewer.md`). The reviewer set is determined by the host CLI — GPT-5.4 is only available on Copilot CLI, so Claude Code skips that reviewer and runs a 2-model parallel review; Copilot CLI runs all three.
+**Shared cache prefix.** Build the reviewer and triage prompts so the large invariant context  -  the full diff, 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. 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.
+
+**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.)
+
+#### Step 2  -  Parallel AI Review (CLI-aware reviewer set)
+
+Launch Agent instances **in parallel** using the shared `code-reviewer` subagent definition (`~/.claude/agents/code-reviewer.md`). The reviewer set is determined by the host CLI  -  GPT-5.4 is only available on Copilot CLI, so Claude Code skips that reviewer and runs a 2-model parallel review; Copilot CLI runs all three.
 
 | Reviewer   | subagent_type     | Model               | Focus                             | Skills Referenced                             | Where it runs        |
 | ---------- | ----------------- | ------------------- | --------------------------------- | --------------------------------------------- | -------------------- |
@@ -140,13 +185,23 @@ Launch Agent instances **in parallel** using the shared `code-reviewer` subagent
 | Reviewer 2 | `code-reviewer`   | `gpt-5.4`           | Edge cases, different perspective | cross-model diversity                         | **Copilot CLI only** |
 | Reviewer 3 | `code-reviewer`   | `claude-sonnet-4.6` | Quality + correctness + naming    | `clean-code`, stack-specific skill            | Both CLIs            |
 
-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.
+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: opus`, so Reviewer 1 uses the persona default. Reviewer 2 (Copilot-only, `gpt-5.4`) and Reviewer 3 (`claude-sonnet-4.6`) 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`. Opus dispatches are additionally subject to the fallback contract (`refs/features/model-fallback.md`): dispatch-error retry on `fallbackModel` (sonnet) and budget-ceiling downgrade.
+
+**Adapter platforms (Cursor / Antigravity / VS Code Copilot Chat) - reviewer set.** The native trio above is a Claude-Code / Copilot-CLI capability. On the adapter platforms the pipeline configures a 2-model cross-vendor review using the models each platform actually exposes (lineup in `pipeline/adapters/_base.mjs#REVIEWER_MODELS`; update as the platforms ship new versions):
+
+| Platform | Reviewer agents emitted | Models |
+|---|---|---|
+| Cursor | `ma-code-reviewer` + `ma-code-reviewer-x` (per-agent `model:` pinning is supported) | primary `inherit` (your selected model, usually Claude) + `gpt-5.5` |
+| VS Code Copilot Chat | `ma-code-reviewer` + `ma-code-reviewer-x` (frontmatter `model:` takes the picker label) | `Claude Opus 4.8` + `GPT-5.5` |
+| Antigravity | two parallel review agents (model chosen in the UI, not a file) | recommended `Gemini 3 Pro` + `Claude Opus 4.6`, set via the side-panel dropdown |
 
-**Model override wiring:** `code-reviewer.md` declares `preferredModel: opus`, so Reviewer 1 uses the persona default. Reviewer 2 (Copilot-only, `gpt-5.4`) and Reviewer 3 (`claude-sonnet-4.6`) 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`.
+So cross-vendor review IS restored on the adapter platforms (two different models on the code review), with the stack architect + `ma-security-auditor` as before. Two honest caveats remain vs the native hosts: (1) the exact model availability depends on the user's subscription (a pinned model the user lacks must be swapped in `REVIEWER_MODELS` / the dropdown), and (2) there is no `PreToolUse` hook, so gates are workflow-enforced not OS-blocked. Antigravity's models are dropdown-selected, so its pair is documented in the workflow rather than file-pinned.
 
-**Stack-specific skills loaded per reviewer** (from Phase 1 `detectedStack`). On Claude Code, Reviewer 2 (GPT-5.4) is not dispatched — its skill column is ignored. On Copilot CLI all three columns are used.
+**Stack-specific skills loaded per reviewer** (from Phase 1 `detectedStack`). On Claude Code, Reviewer 2 (GPT-5.4) is not dispatched  -  its skill column is ignored. On Copilot CLI all three columns are used.
 
-| Stack | Reviewer 1 (Opus) | Reviewer 2 (GPT-5.4 — Copilot CLI only) | Reviewer 3 (Sonnet) |
+| Stack | Reviewer 1 (Opus) | Reviewer 2 (GPT-5.4  -  Copilot CLI only) | Reviewer 3 (Sonnet) |
 |-------|-------------------|-----------------------------------------|---------------------|
 | iOS/Swift | `ios-security`, `swiftui-performance`, `hig-patterns` | `swift-concurrency`, `ios-accessibility` | `swiftui-pro`, `swift-testing` |
 | Android/Kotlin | `android-security`, `android-performance` | `compose-testing`, `android-architecture` | `compose-components`, `kotlin-coroutines-expert` |
@@ -155,30 +210,44 @@ Each reviewer inherits the `code-reviewer` agent's focus areas (Security, Archit
 | Docker | `docker-expert` | `docker-expert` | `ci-cd-pipelines` |
 | Generic | `security-review` | `clean-code` | `clean-code` |
 
-Skills are injected into reviewer prompt context — the reviewer uses them as reference, not as commands.
+Skills are injected into reviewer prompt context  -  the reviewer uses them as reference, not as commands.
+
+**iOS/Swift  -  interaction & convention skills (conditional).** When the diff touches SwiftUI UI files (`*View.swift`, `*Screen.swift`, `*Configuration.swift`, `*+Modifiers.swift`), additionally inject the relevant `figma-common` convention skills as reference for the iOS reviewers: `figma-navigation`, `figma-overlays`, `figma-bottom-sheets` (interaction: emit-intent vs self-route/self-present; native-SwiftUI-first vs the project's `ui.*` custom system), and the enriched `figma-to-swiftui` accessibility rules (minimalism). These back the Step 1.5 iOS convention checks. Generic across SwiftUI projects  -  not tied to any one app. Omit when the diff has no SwiftUI UI changes (keeps the reviewer prompt lean).
+
+**Dispatch timeout (required, mirrors triage 3.3).** Reviewers run in parallel and triage waits on all of them, so one stalled reviewer hangs the phase. Bound each reviewer dispatch by `REVIEWER_TIMEOUT_SECONDS` (default 180). If a reviewer has not returned by the budget: log `review.reviewer_timeout reviewer=<name>`, treat that reviewer as absent, and proceed to triage with the reviewers that did return. The merged-findings count and `consensus.reviewerCount` reflect only the reviewers that returned. If **zero** reviewers return, retry the Opus reviewer once; on a second total failure HALT with `ERR: no reviewer returned within ${REVIEWER_TIMEOUT_SECONDS}s; resume with /multi-agent:resume #N.`. The Step 2.5 rebuttal round uses the same per-dispatch timeout. Never block indefinitely on a slow or dead reviewer dispatch.
 
-#### Output contract — reviewer step
+#### Output contract  -  reviewer step
 
-Step 2 produces N reviewer-output objects (one per dispatched reviewer), each conforming to `pipeline/schemas/reviewer-output.schema.json`. They are persisted to `state.reviewIterations[<iteration>].reviewers[]` and consumed by Step 3 (Opus triage) — never by Phase 6 directly. The triage step (below) is the producer of the only review artifact Phase 6 reads, conforming to `pipeline/schemas/triage-output.schema.json`.
+Step 2 produces N reviewer-output objects (one per dispatched reviewer), each conforming to `pipeline/schemas/reviewer-output.schema.json`. They are persisted to `state.reviewIterations[<iteration>].reviewers[]` and consumed by Step 3 (Opus triage)  -  never by Phase 6 directly. The triage step (below) is the producer of the only review artifact Phase 6 reads, conforming to `pipeline/schemas/triage-output.schema.json`.
 
-**Subagent return format** — each reviewer returns JSON conforming to `pipeline/schemas/reviewer-output.schema.json`:
+**Subagent return format**  -  each reviewer returns JSON conforming to `pipeline/schemas/reviewer-output.schema.json`:
 
 ```json
 {"findings":[{"severity":"blocking|important|suggestion","file":"...","line":N,"issue":"...","fix":"..."}],"approved":true|false}
 ```
 
-**Validate before merging** with `node pipeline/scripts/validate-reviewer.mjs -`. Exit 0=valid, 1=malformed (re-invoke once, then drop), 2=contradiction (flip approved to false).
+**Required: validator gate (deterministic)  -  run immediately after each reviewer returns, before merging findings.** Persist each reviewer's output and validate the file  -  the validator's exit code decides, not the LLM turn:
+
+```bash
+REVIEWER_FILE="$WORKTREE/.pipeline/reviewer-$N.json"
+printf '%s' "$REVIEWER_JSON" > "$REVIEWER_FILE"
+node $HOME/.claude/scripts/validate-reviewer.mjs "$REVIEWER_FILE"
+```
 
-#### Step 2.5 — Disagreement-round loop (opt-in)
+Progress line: `    → checking validator validate-reviewer ({reviewer})`
 
-**Rationale:** When reviewers disagree (e.g. 1 blocker vs 2 pass), straight-to-triage discards potential insight — the minority reviewer might see something real, or the majority reviewers might all miss a subtle issue. One rebuttal round lifts signal quality without adding a new phase.
+Exit 0 = valid. Exit 2 = contradiction (approved=true with blocking findings)  -  flip `approved` to `false`, continue. 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 pipeline/schemas/reviewer-output.schema.json, then resume with /multi-agent:resume #N.`
+
+#### Step 2.5  -  Disagreement-round loop (opt-in)
+
+**Rationale:** When reviewers disagree (e.g. 1 blocker vs 2 pass), straight-to-triage discards potential insight  -  the minority reviewer might see something real, or the majority reviewers might all miss a subtle issue. One rebuttal round lifts signal quality without adding a new phase.
 
 **Gated by `prefs.global.reviewDisagreementRound`** (default: `false`). When enabled:
 
 1. Compute disagreement: reviewers agree iff all return `approved=true` with no `blocking` findings, OR all return `approved=false` with overlapping `blocking` findings. Anything else is disagreement.
 2. Agreement → skip the rebuttal round, go straight to Step 3 triage.
 3. Disagreement → one rebuttal round:
-   - For each reviewer, re-prompt with: (a) their original output, (b) the OTHER reviewers' blocker findings verbatim, (c) instruction: *"Given the opposing arguments, keep / withdraw / modify each of your findings. You may also newly agree with a finding you previously missed. Return the SAME JSON schema — this is a revision, not a new review."*
+   - For each reviewer, re-prompt with: (a) their original output, (b) the OTHER reviewers' blocker findings verbatim, (c) instruction: *"Given the opposing arguments, keep / withdraw / modify each of your findings. You may also newly agree with a finding you previously missed. Return the SAME JSON schema  -  this is a revision, not a new review."*
    - Launch all reviewers in parallel (same CLI-aware set as Step 2).
    - Max one round. Results replace the original outputs.
 4. Proceed to Step 3 triage with the round-2 outputs.
@@ -187,11 +256,11 @@ Step 2 produces N reviewer-output objects (one per dispatched reviewer), each co
 
 **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.
 
-**Off by default reason:** mixed-verdict cases are ~8% of runs in practice; the extra ~$0.20–$0.50 per run isn't worth automating for users who'd rather let triage resolve it cleanly. Users with high-stakes tasks (security-critical, release branches) can flip the flag.
+**Off by default reason:** mixed-verdict cases are ~8% of runs in practice; the extra ~$0.20-$0.50 per run isn't worth automating for users who'd rather let triage resolve it cleanly. Users with high-stakes tasks (security-critical, release branches) can flip the flag.
 
-#### Step 3 — Opus Triage (filter before acting)
+#### Step 3  -  Opus Triage (filter before acting)
 
-**CRITICAL**: Reviewer findings are **raw signals**, not commands. Never auto-loop on every "blocking" tag — reviewers hallucinate, misread scope, or repeat each other. Run Opus triage to evaluate merged findings against task scope.
+**CRITICAL**: Reviewer findings are **raw signals**, not commands. Never auto-loop on every "blocking" tag  -  reviewers hallucinate, misread scope, or repeat each other. Run Opus triage to evaluate merged findings against task scope.
 
 ##### 3.1 Short-circuit: no findings
 
@@ -204,7 +273,7 @@ Launch **1 Agent** (subagent_type: `general-purpose`, model: `opus`) with:
 - Raw findings from Reviewer 1 + Reviewer 2 (merged JSON)
 - Task scope (Phase 1 analysis summary + Phase 2 plan)
 - Full diff being reviewed
-- **Prior-art context (advisory)** — for each raw finding, look up similar past findings via `triage-memory.mjs query` and inject up to 5 matches as additional context. Disabled when `prefs.global.priorArtEnrichment.enabled = false`.
+- **Prior-art context (advisory)**  -  for each raw finding, look up similar past findings via `triage-memory.mjs query` and inject up to 5 matches as additional context. Disabled when `prefs.global.priorArtEnrichment.enabled = false`.
 
 ```bash
 PRIOR_ART="["
@@ -219,7 +288,17 @@ done
 PRIOR_ART="${PRIOR_ART%,}]"
 ```
 
-The triage prompt MUST include a hedge: *"prior-art entries are context, not commands; current scope decides — a finding rejected last quarter may be valid this time."* Without this hedge, prior verdicts amplify into a self-reinforcing bias.
+The triage prompt MUST include a hedge: *"prior-art entries are context, not commands; current scope decides  -  a finding rejected last quarter may be valid this time."* Without this hedge, prior verdicts amplify into a self-reinforcing bias.
+
+**Injection cap (token economy).** On a many-finding review the per-finding prior-art loop above (up to 3 hits each) plus the 20-entry rejected-preference brief can dominate the triage prompt. Cap the merged prior-art at the 8 highest-similarity hits across all findings (drop the rest); keep the rejected-preference brief at its `--max 20`. Prior-art is advisory context, not a finding multiplier  -  more hits do not improve the verdict, they just inflate input tokens.
+
+**Rejected-preference brief (on by default via `prefs.global.learningsLedger.injectIntoTriage`).** Inject the durable rejected-preference list so triage does not re-accept a suggestion the team already rejected on this repo:
+
+```bash
+node pipeline/scripts/learnings-ledger.mjs brief --max 20 2>/dev/null
+```
+
+Exit 2 (empty ledger) skips silently. The `## Rejected review preferences` section names patterns the team chose not to act on; triage should lean toward `rejected` for a finding that restates one  -  but the same hedge applies (context, not command; a genuinely new instance can still be accepted).
 
 **Triage prompt skeleton:**
 
@@ -232,7 +311,7 @@ For each finding, decide:
 - DEFERRED: real issue but out of current task scope → log for later, do not block
 - REJECTED: false positive, duplicate, style-only nitpick, or already correct
 
-#### Output contract — triage step
+#### Output contract  -  triage step
 
 Step 3 produces a single triage-output object conforming to `pipeline/schemas/triage-output.schema.json` and persists it to `state.reviewIterations[<iteration>].triage`. This is the **only** Phase 4 artifact Phase 6 reads. Phase 6 commits MUST cite only `accepted` findings that were resolved; `deferred` items get linked in the PR description as follow-up work; `rejected` items never appear in any user-facing output.
 
@@ -241,20 +320,28 @@ Return ONLY valid JSON conforming to pipeline/schemas/triage-output.schema.json:
   "accepted":  [{ "severity": "blocking|important|suggestion", "file": "...", "line": N, "issue": "...", "fix": "...", "reviewer": "opus|sonnet" }],
   "deferred":  [{ "finding": {...}, "reason": "..." }],
   "rejected":  [{ "finding": {...}, "reason": "..." }],
-  "approved":  true|false   // true if no accepted blocking items remain
+  "approved":  true|false,  // true if no accepted blocking items remain
+  "consensus": { "reviewerCount": N, "verdict": "unanimous-pass|unanimous-block|split|unverified", "disagreements": [{ "file": "...", "line": N, "issue": "...", "note": "Opus blocking, Sonnet approved" }] }  // optional, see 3.6
 }
 ```
 
-##### 3.2.1 Required: Run the runtime validator
+##### 3.2.1 Required: validator gate (deterministic)
+
+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
-echo "$TRIAGE_JSON" | node pipeline/scripts/validate-triage.mjs -
+TRIAGE_FILE="$WORKTREE/.pipeline/triage.json"
+mkdir -p "$(dirname "$TRIAGE_FILE")"
+printf '%s' "$TRIAGE_JSON" > "$TRIAGE_FILE"
+node $HOME/.claude/scripts/validate-triage.mjs "$TRIAGE_FILE"
 ```
 
+Progress line: `    → checking validator validate-triage`
+
 | Exit  | Meaning                      | Action                                            |
 | ----- | ---------------------------- | ------------------------------------------------- |
 | **0** | Valid and clean              | Act on triage output as-is                        |
-| **1** | Invalid structure            | Retry once; on second failure apply §3.3 fallback |
+| **1** | Invalid structure            | Gate protocol (strict, fails CLOSED): (a) emit the validator's stderr and `errors[]` JSON into the log verbatim; (b) attempt ONE self-correction rework  -  re-prompt triage with the errors quoted, overwrite `$TRIAGE_FILE`; (c) re-run the validator. Second failure -> HALT the phase with the recovery hint: `ERR: triage output failed validate-triage.mjs twice. Inspect $TRIAGE_FILE against pipeline/schemas/triage-output.schema.json, fix or regenerate it, then resume with /multi-agent:resume #N.` |
 | **2** | Over-rejection guard tripped | Pause for human confirm (autopilot: log + accept) |
 | **3** | Contradiction auto-corrected | Proceed with `result.corrected`                   |
 
@@ -262,7 +349,7 @@ Capture stdout into `state.reviewIterations[-1].validatorResult` for Phase 7 aud
 
 ##### 3.3 Edge case handling
 
-Failure fallback (invalid JSON, schema mismatch, timeout >120s): retry triage ONCE → on second failure treat ALL raw findings as `accepted`, log cause.
+Failure fallback (timeout >120s, or agent crash before any JSON is produced): retry triage ONCE → on second failure treat ALL raw findings as `accepted`, log cause. Structural validator failures (exit 1) do NOT take this fallback  -  they follow the section 3.2.1 gate protocol (one self-correction rework, then halt with the recovery hint).
 
 | Scenario                                       | Action                                                                      |
 | ---------------------------------------------- | --------------------------------------------------------------------------- |
@@ -284,13 +371,31 @@ LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" 4 revi
 pipeline/scripts/log-metric.sh "$TASK_ID" 4 review.completed raw_count=$RAW accepted=$ACC deferred=$DEF rejected=$REJ approved=$APPROVED duration_ms=$DURATION
 ```
 
-`LOG_METRIC_FORWARD_TO_TRACKER=1` mirrors `tokens_in`/`tokens_out`/`model` into `phase-tracker.sh` (see `refs/progress-contract.md#token-telemetry-forwarding-v83`). On non-zero validator exit (1/2/3), also emit `triage.edge_case` with cause. Omit `tokens_in`/`tokens_out` if unavailable. Best-effort — never fails the pipeline.
+`LOG_METRIC_FORWARD_TO_TRACKER=1` mirrors `tokens_in`/`tokens_out`/`model` into `phase-tracker.sh` (see `refs/progress-contract.md#token-telemetry-forwarding-v83`). On non-zero validator exit (1/2/3), also emit `triage.edge_case` with cause. Omit `tokens_in`/`tokens_out` if unavailable. Best-effort  -  never fails the pipeline.
 
 ##### 3.5 Optional cross-check (single-point-of-failure mitigation)
 
 Opt-in via `prefs.global.triageCrossCheck.enabled` (default `false`). Sampled runs dispatch a **Sonnet** triage agent as second opinion, validated via `validate-triage.mjs` (same fallback rules). Disagreements logged as `triage.cross_check_diff`; `blockOnDisagreement` pauses for user (autopilot: proceed with Opus verdict). Doubles triage cost on sampled runs.
 
-#### Step 4 — Consensus + Action (triage-driven)
+##### 3.6 Consensus surfacing (anti-correlation)
+
+**Rationale:** Reviewer 1 (Opus) and Reviewer 3 (Sonnet) share a base model family, 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.
+
+After the triage verdict is computed, populate `triage.consensus`:
+
+1. `reviewerCount` = number of reviewers dispatched this iteration (`2` on Claude Code, `3` on Copilot CLI).
+2. Classify the iteration `verdict`:
+   - `unanimous-block` -> all reviewers returned at least one overlapping `blocking` finding.
+   - `split` -> reviewers disagreed on existence or severity of one or more findings (the Step 2.5 disagreement definition). List each split in `disagreements[]` with a `note` naming who held which position (e.g. "Opus blocking, Sonnet approved").
+   - `unanimous-pass` -> all reviewers approved AND the diff is low-risk (no security/auth/concurrency surface per Phase 1 `touchedAreas`). Clear-cut; trust it.
+   - `unverified` -> all reviewers approved BUT the diff touches a judgment-heavy surface (security, auth, concurrency, money, data migration). Agreement here may be correlated; do NOT treat it as a confirmed pass. Surface it.
+3. `disagreements[]` is populated for `split` and is also used to carry `unverified` notes (e.g. "both approved a keychain change  -  agreement unverified, confirm manually").
+
+**Surfacing (Step 4 + Phase 7):** When `verdict` is `split` or `unverified`, the disagreements are shown to the user at the Step 4 checkpoint (interactive modes) and always written to the Phase 7 report. Autopilot does not block on `unverified` (it logs `review.consensus=unverified` and proceeds), matching the maturity-check model  -  but the report records it so a human review can catch it. This is additive: omitting `consensus` is valid and means "not computed."
+
+#### Step 4  -  Consensus + Action (triage-driven)
+
+If `triage.consensus.verdict` is `split` or `unverified`, surface `consensus.disagreements[]` to the user before acting: interactive modes show the split and ask whether to treat the unverified agreement as a pass (picker-contract: Trust / Re-review / Treat-as-blocking); autopilot logs `review.consensus=<verdict>` and proceeds on the triage verdict. Never silently average a split into a pass.
 
 Act **only on triage.accepted**:
 
@@ -300,15 +405,29 @@ Act **only on triage.accepted**:
 - **deferred** → append to Phase 7 report as "follow-up items" (do not block)
 - **rejected** → log reasons for audit; do not touch
 
-Log: "Phase 4: Review — raw={N1+N2} accepted={Na} deferred={Nd} rejected={Nr} approved={bool}"
+##### Lesson memory loop (required, end of each fix/rework round)
+
+At the end of every fix/rework round (each Phase 3 re-entry that resolved accepted findings, including the final one), append ONE one-line root-cause lesson per resolved blocking/important finding to the existing learnings ledger (`learnings-ledger.mjs`  -  the store Phase 1 and triage already replay; never invent a parallel store):
+
+```bash
+node pipeline/scripts/learnings-ledger.mjs add --kind fact \
+  --statement "<one-line root cause: what class of mistake produced the finding and why (<=140 chars)>" \
+  --scope "<file-or-area glob from the finding>" --task "$TASK_ID"
+```
+
+Statement shape: root cause, not symptom  -  "force-unwrapped optional in async callback path", not "fixed crash in LoginView". Dedup built in (exit 2 = already stored, skip). Lessons re-enter Phase 1 + triage via `learnings-ledger.mjs brief`.
+
+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}"
 
 ---
 
 #### Multi-Repo Mode
 
-Active when `state.projects[].length > 1`. The 3-reviewer/triage architecture is unchanged — what changes is the diff that reviewers see.
+Active when `state.projects[].length > 1`. The 3-reviewer/triage architecture is unchanged  -  what changes is the diff that reviewers see.
 
-**Combined diff assembly** — reviewers get **one combined diff** covering all repos, with explicit per-repo headers so they can flag cross-repo impact:
+**Combined diff assembly**  -  reviewers get **one combined diff** covering all repos, with explicit per-repo headers so they can flag cross-repo impact:
 
 ```bash
 COMBINED_DIFF=$(mktemp)
@@ -346,15 +465,15 @@ For cross-repo findings, set `crossRepo: true` and list all impacted repos in `a
 
 `file` paths are repo-name-prefixed (`<repo-name>/<path-relative-to-repo>`) so triage and rework can resolve them back to the right worktree. The triage prompt receives `state.projects[]` so it can validate `affectedRepos` entries.
 
-**Triage cross-check**: Cross-repo findings are NEVER auto-rejected — the cross-cutting nature is exactly what reviewers are best at catching. Triage may still defer (out-of-scope) but rejection requires explicit reasoning.
+**Triage cross-check**: Cross-repo findings are NEVER auto-rejected  -  the cross-cutting nature is exactly what reviewers are best at catching. Triage may still defer (out-of-scope) but rejection requires explicit reasoning.
 
 **Token-budget guard** (per `token-budget.json` Phase 4 allowance): if `COMBINED_DIFF` exceeds 80% of the budget, truncate the largest repo's diff with a footer header:
 ```
-[truncated — full diff in file://$WORKTREE/.review-diff.txt]
+[truncated  -  full diff in file://$WORKTREE/.review-diff.txt]
 ```
 And log `review.diff_truncated repo=<name> bytes_dropped=<N>`. Triage receives the same truncated view + the truncation marker so it can flag suggestions to "review the full diff manually."
 
-**Deterministic gates per repo**: Step 1 gates (build/lint/test/secrets) run **per repo** — failure in any one repo blocks AI review for the whole task. Build queue lock applies as in Phase 3 (multi-repo doesn't change Xcode serialization).
+**Deterministic gates per repo**: Step 1 gates (build/lint/test/secrets) run **per repo**  -  failure in any one repo blocks AI review for the whole task. Build queue lock applies as in Phase 3 (multi-repo doesn't change Xcode serialization).
 
 **Telemetry**: Per-repo build/test gate timings + a single combined review/triage call set:
 ```bash
@@ -365,14 +484,14 @@ pipeline/scripts/log-metric.sh "$TASK_ID" 4 review.combined_diff repos=2 bytes=$
 
 ---
 
-## Token telemetry — invoke after every LLM call
+## Token telemetry  -  invoke after every LLM call
 
 After every LLM call in this phase (analysis, plan generation, code/diff write, review verdict, triage), invoke:
 
 ```bash
-bash $HOME/.claude/scripts/phase-tracker.sh tokens 4 <input_count> <output_count>
+bash $HOME/.claude/scripts/phase-tracker.sh tokens 4 <input_count> <output_count> [cached_count]
 ```
 
-The tracker accumulates the totals additively, so multiple calls in the same phase compound. The render output then shows live cost on the active phase tile (e.g. `Phase 4  Dev   2m 14s · 12.4k tok`). This satisfies the contract in `refs/tracker-contract.md` and the `smoke-tracker-tokens-invocation.sh` enforcement gate. Skipping this call is the #1 cause of "I can't see how much it cost" complaints.
+The optional 4th `cached_count` is the prompt-cache-read token count when the host reports it (Anthropic `cache_read_input_tokens`); it defaults to 0 and is priced at the cheaper `cacheReadPerMtok` rate in the Phase 7 cost ledger. The tracker accumulates the totals additively, so multiple calls in the same phase compound. The render output then shows live cost on the active phase tile (e.g. `Phase 4  Dev   2m 14s · 12.4k tok`). This satisfies the contract in `refs/tracker-contract.md` and the `smoke-tracker-tokens-invocation.sh` enforcement gate. Skipping this call is the #1 cause of "I can't see how much it cost" complaints.
 
-If you do not have access to the model's reported token counts, pass best-effort estimates derived from input length / output length — partial cost data is better than none.
+If you do not have access to the model's reported token counts, pass best-effort estimates derived from input length / output length  -  partial cost data is better than none.

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

@@ -1,11 +1,11 @@
 ### Phase 5: Test
 
-> **TLDR** — Optional test gate. Offers to boot the simulator/emulator (UI Bug Hunter) or hand off to the user for manual QA. Skipped in `autopilot` and `--dev` modes. If issues found, loops back to Phase 3.
+> **TLDR**  -  Optional test gate. Offers to boot the simulator/emulator (UI Bug Hunter) or hand off to the user for manual QA. Skipped in `autopilot` and `--dev` modes. If issues found, loops back to Phase 3.
 
 <!-- progress-contract: applied -->
-Progress emission per `refs/progress-contract.md` — lines for local-test prompt render, user-answer capture, repo checkout (if selected).
+Progress emission per `refs/progress-contract.md`  -  lines for local-test prompt render, user-answer capture, repo checkout (if selected).
 
-#### Step 0 — Test Gap Report (advisory)
+#### Step 0  -  Test Gap Report (advisory)
 
 Before the local-checkout prompt, run the static test-gap detector. Heuristic, deterministic, no LLM, sub-second. The report ends up in `agent-log.md` under "Test Scenarios" and surfaces public symbols added in this branch that have no paired test.
 
@@ -44,7 +44,7 @@ fi
 | Other public API additions (`public_func`, `open_fun`, `named_export`, `default_export`, ...) | suggestion |
 | `--severity-promote` | forces every gap to `important` (used when audit-mode is on) |
 
-**Gating** (opt-in): if `prefs.testGap.blockingThreshold` is set and `gapBySeverity.important + gapBySeverity.blocking` exceeds it, Phase 5 surfaces the report as a Phase 4 rework finding and loops back. **Default off** — gaps render as advisory under "Test Gap Report" only.
+**Gating** (opt-in): if `prefs.testGap.blockingThreshold` is set and `gapBySeverity.important + gapBySeverity.blocking` exceeds it, Phase 5 surfaces the report as a Phase 4 rework finding and loops back. **Default off**  -  gaps render as advisory under "Test Gap Report" only.
 
 **Telemetry**:
 
@@ -55,24 +55,39 @@ LOG_METRIC_FORWARD_TO_TRACKER=0 pipeline/scripts/log-metric.sh "$TASK_ID" 5 test
   gaps=$(jq '.totals.gapCount' <<< "$GAP_JSON")
 ```
 
-(No tracker forwarding — the scanner has no token cost.)
+(No tracker forwarding  -  the scanner has no token cost.)
 
-1. Ask the user in English (`promptLanguage` is locked to `en`). The prompt MUST make the local-checkout side effect explicit — saying yes removes the worktree and checks the branch out into the main repo:
-   - `Want to check out locally to test? (y/N)`
-     `(yes → worktree is removed and branch is checked out locally for Xcode/manual test · no → stay in worktree and go to Phase 6)`
-   - **No** → set `state.phases["5"].status = "skipped"` (so Phase 6 can offer the local-checkout prompt) → Phase 6
-   - **Yes** → set `state.phases["5"].status = "in_progress"` → continue:
+**Figma reference panel (when `state.evidence.figma[]` is non-empty).** Before the local-checkout prompt, print a single block listing each captured frame so the user has a side-by-side reference during manual test:
+
+```
+Figma evidence (tier=<n>):
+  <fileKey>:<nodeId>  <canonicalComponentName>
+    screenshot: <screenshotUrl or local path>
+  <fileKey>:<nodeId>  <canonicalComponentName>
+    screenshot: <screenshotUrl or local path>
+```
+
+Tier 1 / Tier 2 records print `screenshotUrl` from the captured evidence (Tier 2 URLs expire after 30 days, re-fetch on the spot if needed). Tier 3 records print the local path to the user-attached screenshot. The block is informational; it never blocks the prompt.
+
+1. Ask with a native `AskUserQuestion` picker (never a typed y/N prompt). The options MUST make the local-checkout side effect explicit  -  testing removes the worktree and checks the branch out into the main repo:
+   - `question`: "Check out locally to test now?" (rendered in `outputLanguage`)
+   - `header`: "Test" (English, <=12 chars)
+   - `options`:
+     - `{ label: "Test now", description: "Removes the worktree and checks the branch out into the main repo for Xcode / manual test" }`
+     - `{ label: "Skip", description: "Stay in the worktree and go to Phase 6" }`
+   - **Skip** → set `state.phases["5"].status = "skipped"` (so Phase 6 can offer the local-checkout prompt) → Phase 6
+   - **Test now** → set `state.phases["5"].status = "in_progress"` → continue:
 2. **Commit changes in worktree BEFORE removing** (WIP commit to preserve work):
    ```
    git -C {worktree-path} add -A
-   git -C {worktree-path} commit -m "WIP: {jiraId} — changes for user test"
+   git -C {worktree-path} commit -m "WIP: {jiraId}  -  changes for user test"
    ```
 3. Remove worktree, checkout branch in main repo:
    ```
    git worktree remove .worktrees/{jiraId} --force
    git checkout {branch-name}
    ```
-   Branch now has the WIP commit — all changes are preserved.
+   Branch now has the WIP commit  -  all changes are preserved.
 4. Show test instructions:
    ```
    Switched to branch: {branch-name}
@@ -82,11 +97,11 @@ LOG_METRIC_FORWARD_TO_TRACKER=0 pipeline/scripts/log-metric.sh "$TASK_ID" 5 test
    ```
 5. Wait for user response
 6. If fix needed:
-   - Branch already has WIP commit (from step 2) — changes are safe
+   - Branch already has WIP commit (from step 2)  -  changes are safe
    - Recreate worktree from branch: `git -C $PROJECT_ROOT worktree add {worktree-path} {branch}`
    - Re-set git identity: `git -C {worktree-path} config user.name/email` (from state)
    - Go back to Phase 3
-7. Log: "Phase 5: Test — {result}"
+7. Log: "Phase 5: Test  -  {result}"
 
 **CRITICAL**: Never remove a worktree with uncommitted changes. Always WIP commit first.
 
@@ -103,9 +118,9 @@ Before or during user testing, run device-level audits via Bash if user requests
 | Snapshot regression | Component / pixel-stable UI changes | `mcp__dev_toolkit__ios_visual_diff` (dev-toolkit-mcp ≥ 2.3.0) |
 | App Store screenshots | `taskType === screenshot` | `mcp__dev_toolkit__ios_status_bar({preset: "clean"})` before each capture |
 
-Results included in Phase 7 report. MCP tools preferred when available — concise structured output, lower token cost.
+Results included in Phase 7 report. MCP tools preferred when available  -  concise structured output, lower token cost.
 
-**Snapshot regression flow (optional):** when the task changes a stable component, capture a screenshot before the change (baseline) and after (current), then call `ios_visual_diff({baseline, current, max_diff_pct: 1.0})`. Threshold can be relaxed for animated / non-deterministic regions — keep `max_diff_pct ≤ 1.0` for static layouts.
+**Snapshot regression flow (optional):** when the task changes a stable component, capture a screenshot before the change (baseline) and after (current), then call `ios_visual_diff({baseline, current, max_diff_pct: 1.0})`. Threshold can be relaxed for animated / non-deterministic regions  -  keep `max_diff_pct ≤ 1.0` for static layouts.
 
 #### Security Audit (store-readiness)
 
@@ -115,9 +130,9 @@ When the task touches authentication, keychain, network, or is scheduled for an
 Agent(subagent_type: "security-auditor", prompt: "<diff + context>")
 ```
 
-Returns severity-tagged findings (Critical / High / Medium). Critical items block Phase 6 just like Phase 4 blockers; High items are logged and surfaced in Phase 7 report. Skipped by default — opt-in for release branches or on explicit `/multi-agent "<task>" --audit` flag.
+Returns severity-tagged findings (Critical / High / Medium). Critical items block Phase 6 just like Phase 4 blockers; High items are logged and surfaced in Phase 7 report. Skipped by default  -  opt-in for release branches or on explicit `/multi-agent "<task>" --audit` flag.
 
-#### Telemetry — token forwarding
+#### Telemetry  -  token forwarding
 
 When the security-auditor or any other Phase 5 sub-agent runs, forward its token totals so Phase 7's Cost Breakdown captures Phase 5: