@mmerterden/multi-agent-pipeline 17.6.0 → 19.0.0

package/pipeline/multi-agent-refs/phases/phase-2-planning.md

@@ -1,344 +0,0 @@
-### Phase 2: Planning (Fable)
-
-> **TLDR**  -  Fable decomposes the analysis (Opus when the fallback ladder engages) into concrete tasks with file-level targets, risk grading, and architecture review. Before Phase 3 a **Plan Approval Gate** runs in normal mode: if the Jira/issue description is ambiguous the orchestrator asks the user structured clarification questions (max 2 rounds)  -  once scope is clear it renders the plan and loops on free-text edit requests until the user approves or aborts. The gate is **skipped entirely** for a Short run and for `autopilot` (a Short run has no plan to approve; autopilot may not ask).
-
-<!-- progress-contract: applied -->
-Progress emission per `$HOME/.claude/multi-agent-refs/progress-contract.md`  -  lines for plan-draft start, clarification-ask, clarification-answer, plan render, plan-edit-request, plan-approved, plan-aborted.
-
-## Phase 2 Pre-flight (BLOCKING, v9.0.0)
-
-Phase 2 Planning consumes the analysis document. **Figma** MCP / REST forbidden; the toolkit MCP is not.
-
-1. **Analysis document presence**: read `state.analysis.docStatus`, which Phase 1 Step 4 set.
-   - `produced` | `reused` -> the file is at `state.analysis.docPath[]`; continue with steps 2-4.
-   - `not-applicable` -> no document by design (bugfix/chore, no Figma). Record it, skip steps 2-4, plan from `state.analysis` alone.
-   - Unreadable or key missing -> `ERR: Phase 1 reported <status> but no analysis doc is readable. Resume with /multi-agent:resume #N.` Producing it is Phase 1's job; never send the user to another command.
-
-2. **Parse YAML front-matter** into `state.analysis.frontMatter` and abort below `template_version: v3` - same contract as `phase-3-dev.md` step 2.
-
-3. **Section coverage check**: verify these sections are non-empty (template v3 required sections per Locked 2):
-   - Section 1 Summary, Section 2 Goals + Non-Goals, Section 4 User Stories, Section 9 API Contracts, Section 13 Architecture Plan, Section 14 Files to Add, Section 20 Risks, Section 21 References
-   - Missing -> WARN, plan is allowed to proceed but Phase 4 reviewer flags it.
-
-4. **Convert analysis tasks to plan**: Section 14 Files-to-Add becomes the seed task list. Carry each row's tag onto its todo as `sourceTag` (`Reuse` | `Add new` | `Modify`); it is an instruction Phase 3 follows and Phase 4 checks, not a label.
-
-5. **MCP forbidden**: same rule as Phase 3.
-
-#### Input contract
-
-Phase 2 consumes the Phase 1 output object conforming to `$HOME/.claude/schemas/analysis-output.schema.json`. Read `state.analysis` (the explorer's return value) and treat its `touchedAreas` and `risks` arrays (plus `stack` and `summary`) as authoritative input  -  do not re-explore the codebase here. (Field names are exactly those in the analysis schema; the planner's own `targetFiles` belongs to `planning-output.schema.json`, not the analysis input.)
-
-#### Step 0.9  -  Post-analysis confirmation (derive first, ask only what cannot be derived)
-
-Runs when `state.analysis.docStatus` is `produced` or `reused`, before any planning.
-
-**Derived is shown, not asked**: platform set, the seven convention groups, existing components (Code Connect + `uiComponents`), localization keys, analytics events, DI registration, test-method naming. **Only Section 20 rows are asked**, through `$HOME/.claude/multi-agent-refs/analysis/resolve.md` - one row, at most three source-labeled candidates, plus Defer. The engine never invents.
-
-```
-Türetildi (onay için):  platform=ios,android · 7 konvansiyon grubu (5 high, 2 medium)
-                        · 12 mevcut bileşen (9 Code Connect bağlı) · 34 lokalizasyon anahtarı
-Sorulacak:              4 açık soru (Bölüm 20)
-```
-
-A corrected value rewrites its Pass B footnote as `^[user-override: resolved <date>]` (Locked 24). Deferred rows stay in `state.analysis.openQuestions[]` and Phase 4 flags them `review_blocking`. Here and not Phase 4 because Phase 4 runs after development - answered there is answered too late. Autopilot skips the asking and defers every row.
-
-#### Step 1  -  Task Decomposition
-
-Break the work from Phase 1 analysis into discrete, implementable tasks:
-
-```
-For each identified change area:
-  1. Define a task with clear scope (one file group or one logical change)
-  2. Estimate complexity: trivial (1 file) / moderate (2-5 files) / complex (6+ files)
-  3. Identify dependencies between tasks (which must complete before others)
-```
-
-Create tasks using TaskCreate with imperative subject, description (what/which files/expected behavior), and `addBlockedBy` for dependencies.
-
-##### Analysis citation requirement (every UI task)
-
-Every UI-touching task in the plan MUST cite:
-
-- The analysis Section 6 (Bileşen Envanteri) row it implements (one task per row when a single component covers several variants), AND
-- The canonical component name, sourced from the analysis doc:
-  - **Code Connect mapping present**: take the component name verbatim from the matching repo `*.figma.swift` / `*.figma.kt` row referenced by analysis Section 6.
-  - **Mapping absent**: cite "best-fit pending design review" and add a Risk row to the plan. The task description MUST also flag that Phase 4 will gate it as `review_blocking`.
-
-Tasks without an analysis Section 6 citation when the doc lists UI components are rejected at the plan-approval gate; the user is asked to either re-run `/multi-agent:analysis` to extend Section 6 or rescope the task to a non-UI change. Direct Figma fetches in Phase 2 are forbidden (Locked decision 30).
-
-Example task graph:
-
-```
-Task 1: Add new token to common module          (no deps)
-Task 2: Create ButtonConfiguration.swift         (blocked by 1)
-Task 3: Create ButtonView.swift                  (blocked by 2)
-Task 4: Add ButtonView+Modifiers.swift           (blocked by 3)
-Task 5: Write ViewInspector tests                (blocked by 3)
-Task 6: Write snapshot tests                     (blocked by 3)
-```
-
-#### Step 2  -  Architecture Review (conditional)
-
-Trigger architecture review if ANY of these are true:
-
-- New module or package being created
-- Cross-module dependency being added
-- Public API surface changing
-- Data model / schema change
-- Navigation flow change
-
-If triggered:
-
-1. Launch Agent with `subagent_type: "ios-architect"` (or `architecture` skill for non-iOS)
-2. Provide: task list, affected files, proposed approach
-3. Agent returns: recommendation, risks, alternative approaches
-4. Incorporate recommendations into task descriptions
-
-If NOT triggered: skip, log "Phase 2: Architecture review  -  not needed (scope contained)"
-
-#### Step 3  -  Development Approach per Task
-
-For each task, determine:
-| Approach | When | Example |
-|----------|------|---------|
-| **New file** | Feature doesn't exist | Create ButtonConfiguration.swift |
-| **Modify** | Extending existing code | Add property to existing Configuration |
-| **Refactor** | Restructuring without behavior change | Extract protocol from class |
-| **Fix** | Bug correction | Fix nil crash in edge case |
-
-Store approach in task metadata for Phase 3 agent.
-
-#### Step 4  -  Skill Selection per Task
-
-Based on Phase 1 `detectedStack`, assign relevant skills:
-
-- iOS tasks -> `ai-ios-toolkit:*` SwiftUI skills, iOS patterns
-- Python tasks -> `ai-backend-toolkit:fastapi-pro`, `ai-backend-toolkit:api-patterns`
-- Node tasks -> `ai-backend-toolkit:nodejs-backend-patterns`
-- Security-sensitive -> `ai-backend-toolkit:api-security-best-practices`
-- Multi-submodule -> `ai-backend-toolkit:monorepo-architect`
-
-#### Output contract
-
-Phase 2 produces an object conforming to `$HOME/.claude/schemas/planning-output.schema.json`  -  `tasks[]` with `id`, `title`, `type`, `files`, plus optional `dependsOn` and `acceptanceCriteria`. Phase 3 reads `tasks[]` in dependency order; the schema's `dependsOn` field drives the ready-task picker.
-
-**Required: validator gate (deterministic)  -  run on the persisted file before the approval gate renders the plan; the validator's exit code decides, not the LLM turn:**
-
-```bash
-PLAN_FILE="$WORKTREE/.pipeline/plan.json"
-mkdir -p "$(dirname "$PLAN_FILE")"
-printf '%s' "$PLAN_JSON" > "$PLAN_FILE"
-node $HOME/.claude/scripts/validate-planning.mjs "$PLAN_FILE"
-```
-
-Progress line: `    → checking validator validate-planning`
-
-Non-zero exit fails CLOSED: emit the validator stderr + `errors[]` verbatim, attempt ONE self-correction rework (re-invoke the planner with the errors quoted, overwrite `$PLAN_FILE`), re-run the validator. If it fails again -> HALT the phase (never enter Phase 3 with an invalid plan) with recovery hint: `ERR: plan output failed validate-planning.mjs twice. Inspect $PLAN_FILE against $HOME/.claude/schemas/planning-output.schema.json, then resume with /multi-agent:resume #N.` Record `agent-state.phases["2"].validator` (`pass` | `pass-after-rework` | `halted`).
-
-Log: "Phase 2: Plan  -  {N} tasks created, {M} with architecture review, validator:pass"
-
-#### Step 4.45  -  Put the plan on the widget (required)
-
-```bash
-printf '%s' "$PLAN_JSON" | bash "$HOME/.claude/scripts/phase-tracker.sh" plan 3
-```
-
-Then do what its output asks - it prints a tile rebuild, because the widget
-orders by creation. `dependsOn` becomes `addBlockedBy`, so the widget answers
-"why has t3 not started". Required, unlike Step 4.5: the plan was always computed
-and stored, only invisible.
-
-#### Step 4.5  -  Emit Plan Todo List (opt-in)
-
-**Gated by `prefs.global.planTodos.enabled`** (default: `false`). When enabled, after the planning-output JSON validates and BEFORE the approval gate, transform `tasks[]` into a structured Todo list conforming to `$HOME/.claude/schemas/plan-todos.schema.json` and persist into `agent-state.plan`. The plan is rendered as a live, always-visible Todo list.
-
-```bash
-printf '%s' "$PLAN_JSON" | bash "$HOME/.claude/lib/plan-todos.sh" set "$TASK_ID" -
-```
-
-`set` accepts a planning-output document and converts it itself. The conversion
-used to be written out here, which made the `tasks[]`-to-`todos[]` mapping a
-thing two files defined, and this was the copy nothing tested.
-
-Phase 3 (Dev) then iterates with `plan-todos.sh next "$TASK_ID"` until empty, calling `start` before each step and `complete` (with notes) or `fail`/`skip` after. Phase 4 (Review) reads the Todo list to verify all `completed` items map to diff hunks. Phase 7 (Report) renders `list` into the agent-log + PR body.
-
-**Why opt-in:** the existing `planning-output.schema.json` already drives Phase 3 dependency order  -  `plan.todos[]` is a richer surface (notes, durations, status transitions) but adds state writes per step. Off by default to keep the bare-bones flow unchanged; flip on for visibility into long features.
-
-#### Step 4.8  -  Cross-artifact consistency check (required, before presenting the plan)
-
-Before the plan is rendered for approval (Step 5b) or silently accepted (the autopilot skip path), verify it against `state.analysis` (drifted plans are the root cause of "PR does not match the ticket"):
-
-1. **Requirement coverage**  -  every analysis requirement (`touchedAreas[]` entry, Section 14 row, acceptance criterion) maps to at least one plan task.
-2. **Anchor integrity**  -  No plan task without an analysis anchor (each task cites the `touchedAreas[].path`, Section 6 row, or `risks[]` mitigation it implements).
-3. **Open-question carry-over**  -  every analysis open question lands in the plan (clarification item, risk row, or explicit descope note); none silently dropped.
-
-Progress line: `    → checking plan-vs-analysis consistency (3 checks)`
-
-**On mismatch:** revise the plan ONCE (re-run Steps 1-4 with the gap list quoted, re-run the validator gate and this checklist). If gaps remain, do NOT loop: surface them in the Step 5b render under a `⚠️ Consistency gaps` banner (autopilot: log `plan.consistency_gaps={list}`). Persist `state.phases["2"].consistencyCheck = { "unmappedRequirements": [], "unanchoredTasks": [], "droppedOpenQuestions": [], "revised": true|false }`.
-
-Log: "Phase 2: Consistency  -  requirements:{N/N mapped} anchors:{ok|M unanchored} open-questions:{carried|K dropped}"
-
-#### Step 5  -  Plan Approval Gate (normal mode + autopilot safety)
-
-**Scope guard  -  skip this step entirely when BOTH of these hold:**
-
-- `state.autopilot === true` (autopilot contract: zero interaction)
-- Autopilot safety classifier returns `recommendPause: false` (see Step 5c below)
-
-OR:
-
-- `state.onlyDevelop === true` (Short pipeline: direct to Phase 3, no plan)
-
-In the skipped case, log `🧠 Phase 2: Plan  -  gate skipped ({mode}), proceeding to Phase 3` and go to Phase 3.
-
-##### 5c  -  Autopilot safety classifier (runs before 5a/5b skip decision)
-
-**Only relevant when `state.autopilot === true` and `prefs.global.autopilotSafetyGate !== false`.** The classifier protects autopilot's zero-interaction contract from edge cases where silent execution is genuinely dangerous (security-path touch, schema migration, many-file sprawl, delete-without-paired-test).
-
-```bash
-verdict=$(node $HOME/.claude/scripts/classify-plan-safety.mjs <(echo "$PLAN_JSON"))
-pause=$(jq -r '.recommendPause' <<< "$verdict")
-score=$(jq -r '.score' <<< "$verdict")
-reasons=$(jq -r '.reasons[] | "• \(.rule) (+\(.weight)): \(.detail)"' <<< "$verdict")
-```
-
-| `recommendPause` | Action |
-|---|---|
-| `false` | Skip 5a/5b as before  -  autopilot proceeds to Phase 3. Log `🧠 Phase 2: Safety classifier  -  score {N}, autopilot proceeds`. |
-| `true`  | Inject a one-time manual approval prompt even though we are in autopilot. Render the plan (5b shape) with the `reasons[]` list prepended. User sees `⚠️ Autopilot safety gate tripped (score {N})` banner and must explicitly choose Approve / Cancel (or edit via Other) in the 5b `AskUserQuestion` picker. Log `🧠 Phase 2: Safety classifier  -  score {N}, autopilot paused, reasons={rules}`. |
-
-**Why opt-out instead of opt-in:** the asymmetry favors pausing. A pause on a high-blast-radius plan costs seconds; a silent auto-merge of a bad one costs hours of rollback or a revert PR. Users running tightly-scoped batch workflows (e.g. figma component iteration over known-safe components) can set `prefs.global.autopilotSafetyGate = false` if they've validated the task class is safe.
-
-**Rules + weights**  -  see `classify-plan-safety.mjs` header comment for the canonical list. Summary: `file-count-high` (30) / `destructive-verb` (25) / `security-path` (35) / `delete-without-test` (30) / `schema-migration` (25) / `infrastructure` (20). Threshold: score ≥ 50 flips `recommendPause` true. Tuned so any single heavy signal or any two medium signals trigger the pause.
-
-**Telemetry:** emit `phase.plan.safety` OTel span (when `MULTI_AGENT_OTEL_SPANS=1`) with `{score, recommendPause, rules}` so post-hoc analysis can tune weights.
-
-Otherwise (normal mode), run the gate. The gate has **two modes** that chain: Clarification → Approval. Each round emits a progress line and persists to `agent-state.json.phases["2"]` for audit.
-
-##### 5a  -  Clarification Mode (conditional, max 2 rounds)
-
-Trigger if the plan Fable produced in Step 1-4 carries ANY ambiguity signal from Phase 1 analysis:
-
-| Signal | Check |
-|---|---|
-| Vague acceptance | Jira/issue description < 200 chars AND no `## Acceptance Criteria` section |
-| UI work, no design | Task touches `*View.swift` / `*Screen.kt` but Phase 1 captured no Figma URL |
-| API work, no contract | Task touches network/repository layer but no endpoint/OpenAPI reference in Phase 1 |
-| Ambiguous language | Phase 1 analysis flagged `ambiguityScore >= 2` (e.g. "improve", "fix", "update" with no object) |
-| Parent-story scope drift | `state.relatedIssues[]` names a sibling overlapping this scope |
-
-If any signal trips, DO NOT render the plan yet. Render structured questions:
-
-```
-📋 Development Plan  -  {taskId}
-────────────────────────────────────
-⚠️  There are points that need clarifying before drafting a plan for this item:
-
-1. {question 1}
-2. {question 2}
-3. {question 3}
-
-Write your answers, then I will draft the plan.
-(or tell me you want to pause  -  the task can be resumed later)
-```
-
-Wait for user response. On reply:
-
-- **User asks to pause / cancel** (intent, in any language) → `state.status = "paused"`, log `🧠 Phase 2: Gate aborted (clarification)`, stop.
-- **Free-text answer** → append to `state.phases["2"].clarificationAnswers`, bump `clarificationRounds`, re-run Steps 1-4 with answers as context, re-evaluate signals.
-
-**Cap: 2 rounds.** If `clarificationRounds === 2` and signals still trip, do NOT ask again  -  render the plan anyway with a `⚠️ best-effort (item still unclear)` banner in Mode 5b, and let the user decide via approval/edit. This prevents infinite grooming loops on chronically under-specified tickets.
-
-Persist to `state.phases["2"]`:
-
-```json
-{
-  "clarificationRounds": 1,
-  "clarificationQuestions": ["Pasaport scan sonrası...", "Backend endpoint...", "Android kapsamda mı?"],
-  "clarificationAnswers": ["Silent reject. Toast yok.", "Backend hazır, v3.4 release'de.", "Sadece iOS bu task'ta."]
-}
-```
-
-##### 5b  -  Approval Loop (always runs after clarification resolves or is skipped)
-
-Render the plan:
-
-```
-📋 Development Plan  -  {taskId}          {best-effort banner if 5a capped}
-────────────────────────────────────
-Summary:    {1-line summary}
-Approach:   {1-paragraph approach}
-Risk:       {low|medium|high}  -  {reason}
-Scope:      {S|M|L} ({N} files, {K} new)
-Files to touch:
-  - {path1}
-  - {path2}
-
-Todos ({N} total):
-  1. {subject}  -  {approach}
-  2. {subject}  -  {approach} (blocked by #1)
-  ...
-
-```
-
-Then ask for the decision with a **native `AskUserQuestion` picker** (never a typed-keyword prompt):
-
-- `question`: "Do you approve this plan?" (rendered in `outputLanguage`)
-- `header`: "Plan" (English, <=12 chars)
-- `options` (label + description in `outputLanguage`; the names below are the option
-  SEMANTICS, not strings to print):
-  - option 1  -  "Approve": proceed to development (Phase 3)
-  - option 2  -  "Cancel": pause the task; resume later with `:resume`
-
-The picker's built-in **Other** field is the free-text edit channel: the user types an edit request there (e.g. "also look at the auth service but keep LoginView out of scope") instead of typing a keyword. Per the `rules.md` matrix `question`, `label` and `description` all follow `outputLanguage`; only `header` stays English. Branch on which option was picked, never on its rendered text.
-
-Handle the selection:
-
-- **Option 1 (Approve)**:
-  - Set `state.phases["2"].planApprovedAt = now()`, bump `planIterations` if not yet set (default 1)
-  - Log `🧠 Phase 2: Plan approved (iterations={N}, clarificationRounds={M})`
-  - Proceed to Phase 3
-- **Cancel**:
-  - Set `state.status = "paused"`, log `🧠 Phase 2: Plan aborted by user`, stop
-- **Other (free-text edit request)**:
-  - Treat the typed text as an edit request. Append to `state.phases["2"].planEditRequests`, bump `planIterations`
-  - Pass the edit request + current plan to the planning model (Fable; Opus when the fallback ladder engages); it revises and returns a new plan (same schema, same validator)
-  - Re-render the plan (5b), loop
-
-No hard cap on edit iterations  -  the user controls exit via the Approve / Cancel options. Between iterations, keep only the **latest plan** as canonical; previous renders are in the log for audit but do not re-enter the validator.
-
-**Validator**: every revised plan goes through `node $HOME/.claude/scripts/validate-planning.mjs -` before re-render. If validation fails after an edit, log `⚠️ Phase 2: Plan validator failed after edit request #N  -  retrying the planning model once` and retry once; on second failure surface the validator error to the user and go back to approval prompt with the pre-edit plan.
-
-#### Step 6  -  Mode-specific short-circuit (reference)
-
-The pipeline shapes interact with the gate as follows. This table is the source of truth for the gate's mode-awareness  -  if behavior diverges in code, fix the code, not the table.
-
-| Mode | Clarification | Approval Loop | Safety Classifier | Notes |
-|---|---|---|---|---|
-| Full, interactive (`/multi-agent`, `:local`) | ✅ (max 2 rounds) | ✅ |  -  (redundant when a human approves) | Full gate |
-| Short (depth picker answered Short) | ❌ | ❌ |  -  | Phase 1-2 skipped at Step 7.5; Phase 3 starts immediately |
-| `autopilot`, `:local-autopilot` | ❌ | ❌ conditional | ✅ (if `autopilotSafetyGate !== false`) | Always Full, so a plan exists. Safe plans proceed silently; high-risk plans trigger a one-time manual approval. Log records the score. |
-
-**Why autopilot now has an escape hatch:** the old "zero interaction  -  fully trust the scope" contract held well for tightly-scoped batch workflows (figma component iteration over known-safe components) but broke in edge cases  -  schema migrations auto-merging, security-path drift going silent, delete-without-test sprawls. The safety classifier (Step 5c) is opt-out so the default protects against the edge-case cost; users running known-safe workflows can flip `prefs.global.autopilotSafetyGate = false` to restore pre-v7.0 behavior.
-
-#### Telemetry  -  token forwarding
-
-After plan generation (and after each edit-loop iteration), forward the planning model's call totals so Phase 7's Cost Breakdown captures Phase 2 (`model=` names the rung that actually ran: `fable`, or `opus` after a fallback step):
-
-```bash
-LOG_METRIC_FORWARD_TO_TRACKER=1 $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 2 plan.generated \
-  model=fable tokens_in=$IN tokens_out=$OUT duration_ms=$DUR iteration=$N
-```
-
-Best-effort. See `$HOME/.claude/multi-agent-refs/progress-contract.md#token-telemetry-forwarding`.
-
----
-
-## Token telemetry  -  invoke after every LLM call
-
-```bash
-bash $HOME/.claude/scripts/phase-tracker.sh tokens 2 <input_count> <output_count>
-```
-
-Contract and rationale: `progress-contract.md` -> Token telemetry forwarding.
-

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

@@ -1,182 +0,0 @@
-### 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. 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 5. If issues found, loops back to Phase 3.
-
-<!-- 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 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 $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 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"
-   ```
-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. Mark the tracker as waiting, then wait for the user response:
-   ```bash
-   bash $HOME/.claude/scripts/phase-tracker.sh now 5 "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 5 completed with `Result "local test passed (user)"`. The "fix: ..." path below is unchanged.
-6. If fix needed:
-   - Branch already has WIP commit (from step 2)  -  changes are safe
-   - **Heal stale admin state first** (same contract as Phase 0  -  step 3's
-     `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 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                                   |
-| ------------------- | ----------------- | ----------------------------------------- |
-| UI flow video       | `state.visualEvidence.required` AND Phase 3 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 3 produced none
-
-Phase 3 Step 3.55 is the primary host and runs in every mode. Phase 5 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 5 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 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 $HOME/.claude/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 `$HOME/.claude/multi-agent-refs/progress-contract.md#token-telemetry-forwarding`.