@mmerterden/multi-agent-pipeline 8.6.0

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

@@ -0,0 +1,378 @@
+### 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.
+
+<!-- progress-contract: applied -->
+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)
+
+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 results:**
+
+- All pass -> 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}"
+
+##### 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:
+
+```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 (`## Güvenlik Taraması (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.
+
+#### 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:
+
+**Accessibility** (both platforms):
+- Missing `.accessibilityLabel` / `contentDescription` → **blocking**
+- Tap target < 44×44pt (iOS) / 48×48dp (Android) → **blocking**
+- Missing `.accessibilityIdentifier` / `testTag` → **important**
+- Dynamic Type / font scaling not supported → **important**
+
+**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`):
+- Non-Material3 component when M3 equivalent exists → **suggestion**
+- Missing `contentDescription` on icons/images → **blocking**
+- Hardcoded dp values instead of Material spacing tokens → **suggestion**
+
+**App Store / Play Store readiness** (skills: `app-store-review`, `play-store-review`):
+- 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`).
+
+#### 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.
+
+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).
+
+#### 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.
+
+```bash
+RISK_JSON=$(node pipeline/scripts/diff-risk-score.mjs \
+  --base "$BASE_BRANCH" --head HEAD \
+  --task-id "$TASK_ID" --top 5 2>/dev/null)
+echo "$RISK_JSON" | node pipeline/scripts/validate-diff-risk.mjs - >/dev/null 2>&1 || RISK_JSON=""
+```
+
+**Signals & weights** (see `pipeline/schemas/diff-risk.schema.json`):
+
+| Signal | Weight | Triggers when |
+|---|---|---|
+| `security_path` | 3.0 | path matches Auth/Keychain/Credential/Token/Crypto/Networking glob |
+| `migration` | 4.0 | path matches DB schema / migration glob (.sql, /Migrations/, alembic/, prisma/migrations) |
+| `public_api` | 2.0 | added line declares `public func/class/struct/enum`, `@objc`, `open fun`, `@Composable`, or `export function/class/...` |
+| `no_test_change` | 2.5 | source file changed, no paired test file (`{Base}Tests.{ext}`, `{Base}.test.{ext}`, etc.) appears in the diff |
+| `complexity_delta` | 1.5 | added control-flow tokens (`if`/`guard`/`switch`/`while`/`for`/ternary/`&&`/`\|\|`) |
+| `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.
+
+**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
+```
+
+On success, emit a single summary metric:
+
+```bash
+pipeline/scripts/log-metric.sh "$TASK_ID" 4 review.diff_risk \
+  top_files=$(jq '.files | length' <<< "$RISK_JSON") \
+  max_score=$(jq '.totals.max_score' <<< "$RISK_JSON") \
+  loc_added=$(jq '.totals.loc_added' <<< "$RISK_JSON")
+```
+
+**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)
+
+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        |
+| ---------- | ----------------- | ------------------- | --------------------------------- | --------------------------------------------- | -------------------- |
+| Reviewer 1 | `code-reviewer`   | `claude-opus-4.6`   | Deep security + architecture      | `api-security-best-practices`, `architecture` | Both CLIs            |
+| 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.
+
+**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`.
+
+**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) |
+|-------|-------------------|-----------------------------------------|---------------------|
+| 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` |
+| Python | `api-security-best-practices` | `fastapi-pro` | `python-patterns` |
+| Node.js | `api-security-best-practices` | `nodejs-backend-patterns` | `typescript-patterns` |
+| 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.
+
+#### 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`.
+
+**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).
+
+#### 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."*
+   - 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.
+
+**Parity contract:** both CLI sides (Claude 2-model, Copilot 3-model) run the round identically. Telemetry emits `review_round_count={1|2}` per reviewer for Phase 7 rollup.
+
+**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.
+
+#### 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.
+
+##### 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.
+
+##### 3.2 Launch triage agent
+
+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`.
+
+```bash
+PRIOR_ART="["
+for finding in $(jq -c '.findings[]' <<< "$MERGED_FINDINGS"); do
+  issue=$(jq -r '.issue' <<< "$finding")
+  file=$(jq -r '.file' <<< "$finding")
+  hits=$(node pipeline/scripts/triage-memory.mjs query \
+    --issue "$issue" --file-glob "$(dirname "$file")/*" --top 3 2>/dev/null \
+    | jq -c '.hits // []')
+  PRIOR_ART="$PRIOR_ART$hits,"
+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.
+
+**Triage prompt skeleton:**
+
+```
+You are the Review Triage agent. Two reviewers returned findings on this diff.
+Your job: separate signal from noise. Do NOT add new findings. Do NOT re-review code.
+
+For each finding, decide:
+- ACCEPTED: real issue, in scope, must be fixed now
+- 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
+
+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.
+
+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
+}
+```
+
+##### 3.2.1 Required: Run the runtime validator
+
+```bash
+echo "$TRIAGE_JSON" | node pipeline/scripts/validate-triage.mjs -
+```
+
+| 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 |
+| **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.
+
+##### 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.
+
+| Scenario                                       | Action                                                                      |
+| ---------------------------------------------- | --------------------------------------------------------------------------- |
+| Over-rejection (>80% rejected, ≥5 findings)    | Pause for user; autopilot: log `triage=high-rejection-rate`, accept verdict |
+| Contradiction (`approved: false`, no blockers) | Force `approved: true`, log `triage=contradiction-corrected`                |
+| Hallucinated findings (not in raw input)       | Strip; log `triage=hallucinated-finding-stripped`                           |
+
+##### 3.4 Telemetry emission (required)
+
+Emit metrics per review pass for Phase 7 cost rollup:
+
+```bash
+LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" 4 review.reviewer_call model=opus duration_ms=$OPUS_DURATION tokens_in=$OPUS_IN tokens_out=$OPUS_OUT
+# GPT-5.4 metric emitted only on Copilot CLI (skip on Claude Code):
+[ "${CLI_HOST:-claude}" = "copilot" ] && \
+  LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" 4 review.reviewer_call model=gpt-5.4 duration_ms=$GPT_DURATION tokens_in=$GPT_IN tokens_out=$GPT_OUT
+LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" 4 review.reviewer_call model=sonnet duration_ms=$SONNET_DURATION tokens_in=$SONNET_IN tokens_out=$SONNET_OUT
+LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" 4 review.triage_call model=opus duration_ms=$TRIAGE_DURATION tokens_in=$TRIAGE_IN tokens_out=$TRIAGE_OUT
+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.
+
+##### 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)
+
+Act **only on triage.accepted**:
+
+- **accepted.blocking** → back to Phase 3 (max 3 iterations, with reflection prompt citing only accepted items)
+- **accepted.important** → fix and re-review
+- **accepted.suggestion** → apply if reasonable
+- **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}"
+
+---
+
+#### Multi-Repo Mode
+
+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:
+
+```bash
+COMBINED_DIFF=$(mktemp)
+for proj in $(jq -r '.projects[] | "\(.name)\t\(.worktreePath)\t\(.baseBranch)"' "$STATE_FILE"); do
+  IFS=$'\t' read -r name wt base <<< "$proj"
+  ORIGIN=$(git -C "$wt" config --get remote.origin.url)
+  printf '\n=== repo: %s (origin: %s) ===\n' "$name" "$ORIGIN" >> "$COMBINED_DIFF"
+  printf 'Base: %s ... HEAD\n\n' "$base" >> "$COMBINED_DIFF"
+  git -C "$wt" diff "origin/$base...HEAD" >> "$COMBINED_DIFF"
+done
+```
+
+Same 3 reviewers (Opus / GPT-5.4 / Sonnet) receive `COMBINED_DIFF` with a multi-repo prefix in the system prompt:
+
+```
+This is a multi-repo task spanning {N} repos: {repo names}.
+Each repo's diff is prefixed with `=== repo: <name> ===`.
+A finding may span repos (e.g. "common adds API X, but uicomponents calls X with wrong type").
+For cross-repo findings, set `crossRepo: true` and list all impacted repos in `affectedRepos: []`.
+```
+
+**Schema extension for findings** (additive, single-repo `crossRepo` defaults to false):
+
+```json
+{
+  "severity": "blocking|important|suggestion",
+  "file": "uicomponents/Sources/Foo.swift",
+  "line": 42,
+  "issue": "...",
+  "fix": "...",
+  "crossRepo": false,
+  "affectedRepos": []
+}
+```
+
+`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.
+
+**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]
+```
+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).
+
+**Telemetry**: Per-repo build/test gate timings + a single combined review/triage call set:
+```bash
+pipeline/scripts/log-metric.sh "$TASK_ID" 4 gate.build repo=common status=pass duration_ms=$D
+pipeline/scripts/log-metric.sh "$TASK_ID" 4 gate.build repo=uicomponents status=pass duration_ms=$D
+pipeline/scripts/log-metric.sh "$TASK_ID" 4 review.combined_diff repos=2 bytes=$BYTES truncated=false
+```
+
+---
+
+## 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>
+```
+
+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.

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

@@ -0,0 +1,129 @@
+### 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.
+
+<!-- progress-contract: applied -->
+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)
+
+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_JSON=$(node pipeline/scripts/test-gap-scan.mjs \
+    --base "$BASE_BRANCH" --head HEAD --stack "$SCAN_STACK" 2>/dev/null)
+  echo "$GAP_JSON" | node pipeline/scripts/validate-test-gap.mjs - >/dev/null 2>&1 || GAP_JSON=""
+fi
+```
+
+**What the report contains** (per `pipeline/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 |
+| `--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.
+
+**Telemetry**:
+
+```bash
+LOG_METRIC_FORWARD_TO_TRACKER=0 pipeline/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.)
+
+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:
+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 6 (WIP commit will be replaced via git reset HEAD~1 + proper commit)
+   "fix: ..." -> worktree is recreated, returns to Phase 3
+   ```
+5. Wait for user response
+6. If fix needed:
+   - 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}"
+
+**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                                   |
+| ------------------- | ----------------- | ----------------------------------------- |
+| Accessibility audit | UI changes        | `mcp__dev_toolkit__ios_accessibility_audit` (or `swift ui-tree-dumper.swift`) |
+| Biometric test      | Auth flow changes | `mcp__dev_toolkit__ios_biometric` (or `xcrun simctl keychain biometric-match`) |
+| Launch time         | Android project   | `adb shell am start -W`                   |
+| Visual test         | Any UI changes    | `/multi-agent test` (sim-test)            |
+| 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.
+
+**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 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
+
+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:
+
+```bash
+LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" 5 audit.completed \
+  model=opus tokens_in=$IN tokens_out=$OUT duration_ms=$DUR
+```
+
+If Phase 5 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 `refs/progress-contract.md#token-telemetry-forwarding-v83`.