@mmerterden/multi-agent-pipeline 17.6.0 → 19.0.0

package/pipeline/multi-agent-refs/phases/{phase-4-review.md → phase-3-review.md}

@@ -1,87 +1,15 @@
-### Phase 4: Review (deterministic gates + parallel + triage)
+### Phase 3: Review (parallel + triage + user test)
 
-> **TLDR**  -  Three-stage review. Stage 1: deterministic gates (build + lint + test + secret scan) that MUST pass. Stage 2: 3 reviewers in parallel per host, second slot **CLI-aware** (Claude Code Fable + Opus + Sonnet; Copilot CLI GPT-5.4 + Opus + Sonnet). Stage 3: Fable triage (Opus on Copilot CLI) filters raw findings for false positives and out-of-scope 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: 3 reviewers in parallel per host, second slot **CLI-aware** (Claude Code Fable + Opus + Sonnet; Copilot CLI GPT-5.4 + Opus + Sonnet). Stage 3: Fable triage (Opus on Copilot CLI) filters raw findings for false positives and out-of-scope items. Only triage-accepted blocking items loop back to Phase 2.
 
 <!-- progress-contract: applied -->
 Progress emission per `$HOME/.claude/multi-agent-refs/progress-contract.md`  -  lines for each gate, each reviewer dispatch + finish, triage start, triage verdict, fix dispatch.
 
 #### Step 0  -  Analysis mode branch
 
-`state.mode === "analysis"` has no diff: the artefact is the document. Replace Steps 1-3 with (1) `validate-analysis-doc.mjs <file> --strict` per platform, (2) the same CLI-aware reviewer set reading the document against one question - **could an implementer build the right thing from this alone?** a finding is anything that would force a guess - and (3) `$HOME/.claude/multi-agent-refs/analysis/resolve.md` over the Section 20 rows still `Acik / Open`; deferred rows report `review_blocking`. Then go to Phase 6.
-
-Log: `Phase 4: Document review  -  validator:{pass/fail} | {N} findings | {M} resolved, {K} deferred`
-
-#### 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 (xcodebuild/gradle assemble/tsc/py compile  -  stack-dependent; Xcode uses the build queue lock, see Phase 3)  -  tee output to a log
-<build-command> 2>&1 | tee "$WORKTREE/.build.log"
-# Gate 2: Lint (swiftlint/ktlint/ruff/eslint  -  stack-dependent)
-# Gate 3: Tests pass (xcodebuild/gradle/pytest/the resolved node command)  -  tee output to a log
-<test-command> 2>&1 | tee "$WORKTREE/.test.log"
-# Gate 4: Secrets  -  run the scanner against the staged diff
-bash $HOME/.claude/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 $HOME/.claude/scripts/evidence-gate.mjs --claim build --status passed --evidence "$WORKTREE/.build.log" || BUILD_PASS=false
-node $HOME/.claude/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`.
-
-**Inherited failures (when `state.baseline.tests` exists).** Phase 0 Step 7.6 recorded whether the suite was already red, so Gate 3 blocks on what this work broke, not what it walked into:
-
-| baseline status | Gate 3 |
-|---|---|
-| `green` | unchanged; every failure is this run's |
-| `red` + `failing[]` | subtract those ids. Nothing left -> pass, logged `test:pass (inherited {N})`. A NEW failure still blocks. |
-| `red`, empty `failing[]` | do NOT pass and do NOT silently block: report `test:inherited-red (not attributable, <logPath>)` and ask. Inventing a set here masks regressions. |
-| `unknown` / absent | unchanged from today |
-
-The subtraction never widens: match on identifier only, and when identifiers cannot be compared fall to the `not attributable` row.
-
-**Gate results:**
-
-- 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/inherited-red} 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`)
-
-If the task description referenced a Fortify version, or named a bare issue instance id, `~/.claude/lib/fetch-fortify.sh` already populated `state.fortifyFinding` in Phase 0 (`alwaysCheck` needs `prefs.global.fortify.versionIds` to know what to scan). Phase 4 reuses that payload and applies the deterministic gate:
-
-```bash
-gate=$(jq -r '.fortifyFinding.gateOutcome // empty' "$STATE_FILE")
-if [ -z "$gate" ]; then
-  # No fortify entry in contextLinks; gate is N/A.
-  echo "→ fortify gate: n/a (no Fortify URL referenced)"
-elif [ "$(jq -r '.fortifyFinding.gateOutcome.blocking' "$STATE_FILE")" = "true" ]; then
-  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.
-  exit 1
-else
-  high=$(jq -r '.fortifyFinding.severityCounts.High // 0' "$STATE_FILE")
-  echo "→ fortify gate: pass (high=$high warnings carry into the channel summary)"
-fi
-```
-
-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 (`## 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.
+`state.mode === "analysis"` has no diff: the artefact is the document. Replace Steps 1-3 with (1) `validate-analysis-doc.mjs <file> --strict` per platform, (2) the same CLI-aware reviewer set reading the document against one question - **could an implementer build the right thing from this alone?** a finding is anything that would force a guess - and (3) `$HOME/.claude/multi-agent-refs/analysis/resolve.md` over the Section 20 rows still `Acik / Open`; deferred rows report `review_blocking`. Then go to Phase 4.
 
+Log: `Phase 3: Document review  -  validator:{pass/fail} | {N} findings | {M} resolved, {K} deferred`
 #### Step 1.45  -  Test plan coverage cross-check (Phase 1 modes with a test plan)
 
 Every `state.dev.testPlan[]` row must map to a real test in the diff, matched on the planned name. Missing -> `important` ("planned test <name> (BR-<id>) has no implementation"); present but asserting something else -> `blocking`, plan and code disagree about the rule. This is what makes "analysis quality is output quality" measurable. Skipped when `docStatus === "not-applicable"` or the mode has no Phase 1.
@@ -115,15 +43,15 @@ If changes include UI files (iOS: `*View.swift`, `*Screen.swift`, `*Cell.swift`;
 - Privacy: API usage without purpose string / permission rationale → **blocking**
 - Deprecated API usage flagged by latest SDK → **important**
 
-Device-level audit runs in Phase 5 (`audit-guide.md`).
+Device-level audit runs in Phase 3 (`audit-guide.md`).
 
 #### 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 `$HOME/.claude/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).
+Phase 3 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 5 cost rollup distinguishes a cache hit (free) from a regeneration (~150-300ms wall, 0 LLM cost either way).
 
 #### Step 1.8  -  Platform parity cross-check (advisory, read-only)
 
@@ -152,7 +80,7 @@ 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):
+Persist the totals as `state.diffRisk` (Phase 4 `risk` section, Phase 5, `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"
@@ -252,14 +180,14 @@ Output conforms to `$HOME/.claude/schemas/criteria-manifest.schema.json`. The fo
 | Absent input | Substitute |
 |---|---|
 | `detectedStack` (Phase 1 Step 2) | the language census in `criteria-manifest.json` → `languages`, from the diff's file extensions |
-| Phase 1 analysis summary + Phase 2 plan (triage scope, cache prefix) | the task description plus the inline task list Phase 3 generated for itself |
+| Phase 1 analysis summary + Phase 1 plan (triage scope, cache prefix) | the task description plus the inline task list Phase 2 generated for itself |
 | `state.evidence.figma[]` (this step), Step 2.8 visual conformance | nothing. Record each as `not-applicable (no Phase 1 evidence)` in `consensus.visualConformance`; never silently omit |
 
 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:
 
-- Canonical component usage: the Code Connect-mapped component is used verbatim  -  a sound-alike substitute, a forked copy, or ad-hoc inline UI where a mapping exists is blocking (Phase 3 "Design fidelity contract")
+- Canonical component usage: the Code Connect-mapped component is used verbatim  -  a sound-alike substitute, a forked copy, or ad-hoc inline UI where a mapping exists is blocking (Phase 2 "Design fidelity contract")
 - Inter-component spacing: gaps, paddings, and alignment BETWEEN components match the design's measured values mapped to spacing tokens  -  invented numeric values are blocking
 - Everything else: the 30-group catalog in `$HOME/.claude/multi-agent-refs/features/design-conformance.md`. Two of its rules carry into review: a height or inset is **measured**, never read from the token under test; an unrun check is a fail-to-verify, not a pass.
 
@@ -279,11 +207,11 @@ git -C "$WORKTREE" diff --name-only "$BASE_BRANCH"...HEAD \
 
 #### 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:
+Phase 3 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 `${REVIEW_FILES}` list from Step 1.85, 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.
+**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 `${REVIEW_FILES}` list from Step 1.85, the Phase 1 analysis summary, the Phase 1 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.** Applied to the Step 1.85 `reviewed[]` set only. If it 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.)
+**Single-repo diff cap.** Applied to the Step 1.85 `reviewed[]` set only. If it exceeds the Phase 3 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)
 
@@ -311,7 +239,7 @@ statement: the managed block in `~/.codex/AGENTS.md`, always loaded on that host
 2. **Three concurrent children is the ceiling** - 4 slots including the orchestrator,
    so the reviewer count on Codex is capability-derived, not a preference.
 
-Sub-agent delegation itself is authorized by that same managed block; without it Phase 4
+Sub-agent delegation itself is authorized by that same managed block; without it Phase 3
 degrades to a single in-thread review.
 
 **Single-vendor caveat.** Claude Code and Codex both run a one-vendor panel, so their
@@ -336,7 +264,7 @@ Each reviewer inherits the `code-reviewer` agent's focus areas (Security, Archit
 
 ##### 2.1 Previous-round findings (iteration >= 2) and 2.2 scope self-check (every iteration)
 
-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. 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`.
+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. Every iteration also renders `.pipeline/scope-check.json` (Phase 2 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)
 
@@ -358,7 +286,7 @@ blocking finding.
 Why this is a gate and not advice: `design-conformance.md`, "Why this runs as a gate".
 
 Skip only when the diff has no UI change. Record the outcome in
-`consensus.visualConformance` so Phase 7 reports whether it ran.
+`consensus.visualConformance` so Phase 5 reports whether it ran.
 
 **iOS/Swift  -  interaction & convention checks (conditional).** Step 1.78 resolves these. Where no registry covers the change, reviewers fall back to the analysis doc (Section 14 Code Connect mapping) and, when `ai-ios-toolkit` is enabled, that plugin's navigation / overlay / bottom-sheet + accessibility conventions.
 
@@ -368,7 +296,7 @@ Skip only when the diff has no UI change. Record the outcome in
 
 #### Output contract  -  reviewer step
 
-Step 2 produces N reviewer-output objects (one per dispatched reviewer), each conforming to `$HOME/.claude/schemas/reviewer-output.schema.json`. They are persisted to `state.reviewIterations[<iteration>].reviewers[]` and consumed by Step 3 (Fable triage)  -  never by Phase 6 directly. The triage step (below) is the producer of the only review artifact Phase 6 reads, conforming to `$HOME/.claude/schemas/triage-output.schema.json`.
+Step 2 produces N reviewer-output objects (one per dispatched reviewer), each conforming to `$HOME/.claude/schemas/reviewer-output.schema.json`. They are persisted to `state.reviewIterations[<iteration>].reviewers[]` and consumed by Step 3 (Fable triage)  -  never by Phase 4 directly. The triage step (below) is the producer of the only review artifact Phase 4 reads, conforming to `$HOME/.claude/schemas/triage-output.schema.json`.
 
 **Subagent return format**  -  each reviewer returns JSON conforming to `$HOME/.claude/schemas/reviewer-output.schema.json`:
 
@@ -417,7 +345,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:** 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.
+**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 5 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.
 
@@ -427,9 +355,9 @@ Exit 0 = valid. Exit 2 = contradiction (approved=true with blocking findings)  -
 
 **CRITICAL**: Reviewer findings are **raw signals**, not commands. Never auto-loop on every "blocking" tag  -  reviewers hallucinate, misread scope, or repeat each other. Run Fable triage (Opus on Copilot CLI) to evaluate merged findings against task scope.
 
-Optional: when `ai-analyst-toolkit` is enabled and a finding blames a third-party library rather than this diff, ask `evidence-github` whether it is already open upstream. A confirmed one is `deferred` with its `GitHub:<owner>/<repo>#<n>` citation, not `accepted` and handed to Phase 3 to fix code that is not ours.
+Optional: when `ai-analyst-toolkit` is enabled and a finding blames a third-party library rather than this diff, ask `evidence-github` whether it is already open upstream. A confirmed one is `deferred` with its `GitHub:<owner>/<repo>#<n>` citation, not `accepted` and handed to Phase 2 to fix code that is not ours.
 
-Opt-in empirical layer: when `prefs.global.verifyByTest.enabled` is `true`, accepted blocking findings additionally go through Step 3.7 (verify-by-test), which tries to reproduce each one with a minimal failing test before the Phase 3 rework loop fires. Full wiring: `$HOME/.claude/multi-agent-refs/features/verify-by-test.md`.
+Opt-in empirical layer: when `prefs.global.verifyByTest.enabled` is `true`, accepted blocking findings additionally go through Step 3.7 (verify-by-test), which tries to reproduce each one with a minimal failing test before the Phase 2 rework loop fires. Full wiring: `$HOME/.claude/multi-agent-refs/features/verify-by-test.md`.
 
 ##### 3.0 Anonymize the reviewer findings, then merge the deterministic ones
 
@@ -441,7 +369,7 @@ ANON=$(jq -n --argjson r "$REVIEWERS_JSON" --arg t "$TASK_ID" --argjson i "$ITER
       | node "$HOME/.claude/scripts/anonymize-findings.mjs" --map "/tmp/review-$TASK_ID-$ITERATION-map.json")
 ```
 
-`$REVIEWERS_JSON` is `state.reviewIterations[i].reviewers`. Findings come back with `foundBy: "Source A|B|C"` and every identity key removed. Persist the map to `state.reviewIterations[i].anonymizationMap` for Phase 7 per-reviewer telemetry, and **never put the map in a prompt**.
+`$REVIEWERS_JSON` is `state.reviewIterations[i].reviewers`. Findings come back with `foundBy: "Source A|B|C"` and every identity key removed. Persist the map to `state.reviewIterations[i].anonymizationMap` for Phase 5 per-reviewer telemetry, and **never put the map in a prompt**.
 
 Then append the Step 1.76 test-integrity findings, so they are adjudicated rather than never seen:
 
@@ -454,14 +382,14 @@ Deterministic findings keep `tag: test_integrity` and carry no `foundBy`: a revi
 
 ##### 3.1 Short-circuit: no findings
 
-If **merged** findings `length === 0`, **skip triage**: write empty result `{"accepted": [], "deferred": [], "rejected": [], "approved": true}`, log, proceed to Phase 5. Note this is the merged count from 3.0: a run with zero reviewer findings but a non-empty test-integrity set must NOT short-circuit.
+If **merged** findings `length === 0`, **skip triage**: write empty result `{"accepted": [], "deferred": [], "rejected": [], "approved": true}`, log, proceed to Phase 3. Note this is the merged count from 3.0: a run with zero reviewer findings but a non-empty test-integrity set must NOT short-circuit.
 
 ##### 3.2 Launch triage agent
 
 Launch **1 Agent** (subagent_type: `general-purpose`, model: `fable` on Claude Code / `opus` on Copilot CLI) with:
 
 - The anonymized merged findings from 3.0 (`Source A/B/C` labels; no model name anywhere in the prompt)
-- Task scope (Phase 1 analysis summary + Phase 2 plan)
+- Task scope (Phase 1 analysis summary + Phase 1 plan)
 - Full diff being reviewed
 - **Prior-art context (advisory)**  -  per raw finding, `triage-memory.mjs query --top <prefs.global.priorArtEnrichment.topN>` (default 3). Pass `--top`: without it the script falls back to `memoryRecall.maxResults`, a different concern, and `topN` silently does nothing. Off when `priorArtEnrichment.enabled = false`.
 
@@ -527,7 +455,7 @@ a reason. Preserve `ruleId` and `criteriaSource` on every finding you keep.
 
 #### Output contract  -  triage step
 
-Step 3 produces a single triage-output object conforming to `$HOME/.claude/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.
+Step 3 produces a single triage-output object conforming to `$HOME/.claude/schemas/triage-output.schema.json` and persists it to `state.reviewIterations[<iteration>].triage`. This is the **only** Phase 3 artifact Phase 4 reads. Phase 4 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.
 
 Return ONLY valid JSON conforming to $HOME/.claude/schemas/triage-output.schema.json:
 {
@@ -555,7 +483,7 @@ node $HOME/.claude/scripts/validate-triage.mjs "$TRIAGE_FILE" \
 
 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.
+One file per round; `triage-output.json` is the latest copy every downstream reader expects (Phase 5, finalize, work-summary, diff-explain). Step 3.7 rewrites `$TRIAGE_FILE`; repeat the `cp` after it.
 
 | Exit  | Meaning                      | Action                                            |
 | ----- | ---------------------------- | ------------------------------------------------- |
@@ -564,7 +492,7 @@ One file per round; `triage-output.json` is the latest copy every downstream rea
 | **2** | Over-rejection guard tripped | Pause for human confirm (autopilot: log + accept) |
 | **3** | Contradiction auto-corrected | Proceed with `result.corrected`                   |
 
-Capture stdout into `state.reviewIterations[-1].validatorResult` for Phase 7 audit.
+Capture stdout into `state.reviewIterations[-1].validatorResult` for Phase 5 audit.
 
 ##### 3.3 Edge case handling
 
@@ -578,7 +506,7 @@ Failure fallback (timeout >120s, or agent crash before any JSON is produced): re
 
 ##### 3.4 Telemetry emission (required)
 
-Emit metrics per review pass for Phase 7 cost rollup:
+Emit metrics per review pass for Phase 5 cost rollup:
 
 One `review.reviewer_call` per dispatched reviewer, one `review.triage_call`, one `review.completed` to close the pass:
 
@@ -621,13 +549,13 @@ After the triage verdict is computed, populate `triage.consensus`:
    - `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."
+**Surfacing (Step 4 + Phase 5):** 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 5 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."
 
 ##### 3.7 Verify-by-test (opt-in, empirical validation of blocking findings)
 
 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 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=`.
+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 2 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 2 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)
 
@@ -646,7 +574,7 @@ Merge the JSON into `state.reviewIterations[-1].delta` via `write-state.mjs`; em
 | **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.
+`plateau` is logged, not acted on; trigger 3 (the rework cap) is recorded by the Phase 2 re-entry.
 
 #### Step 4  -  Consensus + Action (triage-driven)
 
@@ -654,15 +582,15 @@ 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). 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.blocking** → back to Phase 2 (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)
+- **deferred** → append to Phase 5 report as "follow-up items" (do not block)
 - **rejected** → log reasons for audit; do not touch
 
 ##### 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):
+At the end of every fix/rework round (each Phase 2 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 $HOME/.claude/scripts/learnings-ledger.mjs add --kind fact \
@@ -675,7 +603,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+N3} accepted={Na} deferred={Nd} rejected={Nr} approved={bool} consensus={verdict}"
+Log: "Phase 3: Review  -  raw={N1+N2+N3} accepted={Na} deferred={Nd} rejected={Nr} approved={bool} consensus={verdict}"
 
 ---
 
@@ -689,7 +617,197 @@ Log: "Phase 4: Review  -  raw={N1+N2+N3} accepted={Na} deferred={Nd} rejected={N
 bash $HOME/.claude/scripts/phase-tracker.sh tokens 4 <input_count> <output_count> [cached_count]
 ```
 
-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 `$HOME/.claude/multi-agent-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 5 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 3  Dev   2m 14s · 12.4k tok`). This satisfies the contract in `$HOME/.claude/multi-agent-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.
 
 Contract and rationale: `progress-contract.md` -> Token telemetry forwarding.
 
+---
+
+## User test (was Phase 3 until v19.0.0)
+
+Optional test gate, now the tail of Review rather than a phase of its own: it
+judges work that already exists, which is what Review does. Needs an interactive
+prompt AND a worktree checkout, so it is skipped where either is missing. If
+issues are found, the run returns to Phase 1 Dev.
+
+
+> **TLDR**  -  Optional test gate. Offers to boot the simulator/emulator (UI Bug Hunter) or hand off to the user for manual QA. Needs an interactive prompt AND a worktree checkout, so it is in the phase set of `/multi-agent` alone and dropped by every `autopilot` or `--local` entry. Depth does not affect it: a Short run still reaches Phase 3. If issues found, loops back to Phase 2.
+
+<!-- progress-contract: applied -->
+Progress emission per `$HOME/.claude/multi-agent-refs/progress-contract.md`  -  lines for local-test prompt render, user-answer capture, repo checkout (if selected).
+
+#### Step 0  -  Test Gap Report (advisory)
+
+`state.testPolicy: none` → skip the gap scan (the gap IS the recorded policy) and run only pre-existing test targets; none → recorded no-op. Otherwise, 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.
+
+```bash
+STACK=$(jq -r '.analysis.stack.primary // "unknown"' "$STATE_FILE")
+case "$STACK" in
+  ios|swift)             SCAN_STACK=ios ;;
+  android|kotlin)        SCAN_STACK=android ;;
+  python)                SCAN_STACK=python ;;
+  node|typescript|js)    SCAN_STACK=node ;;
+  *)                     SCAN_STACK="" ;;
+esac
+if [ -n "$SCAN_STACK" ] && [ "${prefs_testGap_enabled:-true}" = "true" ]; then
+  GAP_FLAGS=""
+  [ "${prefs_testGap_scanTree:-false}" = "true" ] && GAP_FLAGS="$GAP_FLAGS --scan-tree"
+  [ "${prefs_testGap_promoteSeverity:-false}" = "true" ] && GAP_FLAGS="$GAP_FLAGS --severity-promote"
+  GAP_JSON=$(node $HOME/.claude/scripts/test-gap-scan.mjs \
+    --base "$BASE_BRANCH" --head HEAD --stack "$SCAN_STACK" $GAP_FLAGS 2>/dev/null)
+  echo "$GAP_JSON" | node $HOME/.claude/scripts/validate-test-gap.mjs - >/dev/null 2>&1 || GAP_JSON=""
+fi
+```
+
+**What the report contains** (per `$HOME/.claude/schemas/test-gap.schema.json`):
+
+| Field | Meaning |
+|---|---|
+| `gaps[].sourcePath` | source file with the unprotected symbol |
+| `gaps[].symbol` | symbol name |
+| `gaps[].kind` | rule id (e.g. `public_func`, `composable_fun`, `named_export`) |
+| `gaps[].severity` | `blocking` / `important` / `suggestion` (see severity table below) |
+| `gaps[].expectedTestPaths` | likely test paths the user should land at, in priority order |
+| `gaps[].hint` | stack-specific testing reminder (e.g. swiftui-qa.md 3-layer) |
+
+**Severity defaults**:
+
+| Symbol kind | Severity |
+|---|---|
+| `composable_fun`, `view_struct`, `config_struct`, `interface`, `objc_export`, `public_proto` | important |
+| Other public API additions (`public_func`, `open_fun`, `named_export`, `default_export`, ...) | suggestion |
+
+**Gating** (opt-in): if `prefs.testGap.blockingThreshold` is set and `gapBySeverity.important + gapBySeverity.blocking` exceeds it, Phase 3 surfaces the report as a Phase 3 rework finding and loops back. **Default off**  -  gaps render as advisory under "Test Gap Report" only.
+
+**Telemetry**:
+
+```bash
+LOG_METRIC_FORWARD_TO_TRACKER=0 $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 5 test_gap.scanned \
+  stack=$SCAN_STACK \
+  sources=$(jq '.totals.sourcesScanned' <<< "$GAP_JSON") \
+  gaps=$(jq '.totals.gapCount' <<< "$GAP_JSON")
+```
+
+(No tracker forwarding  -  the scanner has no token cost.)
+
+**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 4" }`
+   - **Skip** → set `state.phases["3"].status = "skipped"` (so Phase 4 can offer the local-checkout prompt) → Phase 4
+   - **Test now** → set `state.phases["3"].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"
+   ```
+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.
+4. Show test instructions:
+   ```
+   Switched to branch: {branch-name}
+   To test: Xcode -> build -> run -> manual test
+   "ok" -> proceeds to Phase 4 (WIP commit will be replaced via git reset HEAD~1 + proper commit)
+   "fix: ..." -> worktree is recreated, returns to Phase 2
+   ```
+5. Mark the tracker as waiting, then wait for the user response:
+   ```bash
+   bash $HOME/.claude/scripts/phase-tracker.sh now 3 "awaiting local test (user)"
+   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"
+   ```
+   Add `--require-screenshot` when `state.visualEvidence.required` is true: a passing criterion then has to name a file that exists, because a `screenshot` key pointing nowhere is not evidence.
+
+   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 3 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
+     `worktree remove` or an interrupted run can leave a stale entry, so a bare
+     re-add fails with `already exists`/`already registered`):
+     ```bash
+     git -C "$PROJECT_ROOT" worktree prune 2>/dev/null || true
+     if git -C "$PROJECT_ROOT" worktree list --porcelain | grep -qF "{worktree-path}"; then
+       git -C "$PROJECT_ROOT" worktree unlock "{worktree-path}" 2>/dev/null || true
+     fi
+     ```
+     Phase 0's repo residue guard is already in `.git/info/exclude`  -  no re-add.
+   - 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 2
+7. Log: "Phase 3: Review (user test)  -  {result}"
+
+**CRITICAL**: Never remove a worktree with uncommitted changes. Always WIP commit first.
+
+#### Automated Device Checks (on-demand)
+
+Before or during user testing, run device-level audits via Bash if user requests. See `audit-guide.md` for commands.
+
+| Check               | When              | Command                                   |
+| ------------------- | ----------------- | ----------------------------------------- |
+| UI flow video       | `state.visualEvidence.required` AND Phase 2 recorded none | `capture-evidence.sh video start` -> drive the flow -> `video stop` -> `fit`. See below |
+| Accessibility audit | UI changes        | `mcp__multi-agent-toolkit__{ios,android}_accessibility_audit` |
+| Biometric test      | Auth flow changes | ios: `mcp__multi-agent-toolkit__ios_biometric` (android: manual) |
+| Launch time         | Perf-sensitive changes | ios: app-launch instrument · android: `mcp__multi-agent-toolkit__android_launch_time` |
+| Visual test         | Any UI changes    | `/multi-agent test` (sim-test, both platforms) |
+| Snapshot regression | Component / pixel-stable UI changes | ios: `mcp__multi-agent-toolkit__ios_visual_diff` · android: `mcp__multi-agent-toolkit__android_screenshot` + compare |
+| Store screenshots   | `taskType === screenshot` | ios: `ios_status_bar({preset: "clean"})` · android: `android_screenshot` |
+
+##### UI flow video, when Phase 2 produced none
+
+Phase 2 Step 3.55 is the primary host and runs in every mode. Phase 3 is the richer one where it exists: the device is up and a person is watching, so the flow is one somebody confirmed. It adds, never replaces.
+
+Run only when `visualEvidence.required` and `visualEvidence.video.file` is empty: re-check the device with `$HOME/.claude/scripts/probe-evidence-capability.sh --only device`, then `$HOME/.claude/scripts/capture-evidence.sh video start` -> drive the flow (`run-ui-tests.sh run`, or the Phase 3 scenarios by hand) -> `video stop` -> `fit`. The cap is `visualEvidence.maxVideoSeconds`, read through `capture-evidence.sh limits` so one value serves both. Update `videoTier` and `videoTierReason` with what ran.
+
+When the intake answer was `unit` there is no recording here either: overriding it in a phase the user may not be watching makes the question decorative.
+
+Results included in Phase 5 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.
+
+#### Security Audit (store-readiness)
+
+When the task touches authentication, keychain, network, or is scheduled for an imminent release, launch the `security-auditor` subagent to run an OWASP Mobile Top 10 pass plus App Store / Play Store compliance checks:
+
+```
+Agent(subagent_type: "security-auditor", prompt: "<diff + context>")
+```
+
+Returns severity-tagged findings (Critical / High / Medium). Critical items block Phase 4 just like Phase 3 blockers; High items are logged and surfaced in Phase 5 report. Skipped by default  -  opt-in for release branches or on explicit `/multi-agent "<task>" --audit` flag.
+
+#### Telemetry  -  token forwarding
+
+When the security-auditor or any other Phase 3 sub-agent runs, forward its token totals so Phase 5's Cost Breakdown captures Phase 3:
+
+```bash
+LOG_METRIC_FORWARD_TO_TRACKER=1 $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 5 audit.completed \
+  model=opus tokens_in=$IN tokens_out=$OUT duration_ms=$DUR
+```
+
+If Phase 3 is purely user-driven (no sub-agent ran), no token forwarding is required and the cost block stays empty for this phase. Best-effort. See `$HOME/.claude/multi-agent-refs/progress-contract.md#token-telemetry-forwarding`.