@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

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

@@ -1,15 +1,33 @@
-### Phase 2: Planning (Opus)
+### Phase 2: Planning (Fable)
 
-> **TLDR** — Opus decomposes the analysis 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 `--dev`, `autopilot`, and `--dev autopilot` (their speed/zero-interaction contracts are preserved).
+> **TLDR**  -  Opus decomposes the analysis 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 `--dev`, `autopilot`, and `--dev autopilot` (their speed/zero-interaction contracts are preserved).
 
 <!-- progress-contract: applied -->
-Progress emission per `refs/progress-contract.md` — lines for plan-draft start, clarification-ask, clarification-answer, plan render, plan-edit-request, plan-approved, plan-aborted.
+Progress emission per `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. MCP forbidden.
+
+1. **Analysis document presence**: same path resolution as Phase 3.
+   - Abort with `ERR: analysis doc missing. Run /multi-agent:analysis "<feature>" first.`
+
+2. **Parse YAML front-matter**: `feature`, `platform`, `language`, `mode`, `evidence_digest`, `template_version`. Persist into `state.analysis.frontMatter`.
+   - **Soft-skip (v9.1.0+, Locked 30)**: when `template_version == v2` AND (`prefs.global.legacyV2AnalysisAllowed == true` OR env `MULTI_AGENT_LEGACY_V2_ANALYSIS=allow`), emit `WARN: legacy v2 analysis doc detected; v3 expected. Continuing in degraded mode.` Step 3 section coverage check skips v3-specific sections (10 Localization, 11 Analytics, 12 Deeplink/Push, 13.6 SwiftUI Preview, 21 References). Phase 4 reviewer flags missing v3 sections rather than blocking. Escape hatch removed in v9.2.0; users must regenerate v3 docs by then.
+
+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. Apply Reuse / Add new / Modify tags from the inventory column.
+
+5. **MCP forbidden**: same rule as Phase 3.
 
 #### Input contract
 
-Phase 2 consumes the Phase 1 output object conforming to `pipeline/schemas/analysis-output.schema.json`. Read `state.analysis` (the explorer's return value) and treat its `findings`, `riskAreas`, and `targetFiles` arrays as authoritative input — do not re-explore the codebase here.
+Phase 2 consumes the Phase 1 output object conforming to `pipeline/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 1 — Task Decomposition
+#### Step 1  -  Task Decomposition
 
 Break the work from Phase 1 analysis into discrete, implementable tasks:
 
@@ -22,6 +40,17 @@ For each identified change area:
 
 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:
 
 ```
@@ -33,7 +62,7 @@ Task 5: Write ViewInspector tests                (blocked by 3)
 Task 6: Write snapshot tests                     (blocked by 3)
 ```
 
-#### Step 2 — Architecture Review (conditional)
+#### Step 2  -  Architecture Review (conditional)
 
 Trigger architecture review if ANY of these are true:
 
@@ -50,9 +79,9 @@ If triggered:
 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)"
+If NOT triggered: skip, log "Phase 2: Architecture review  -  not needed (scope contained)"
 
-#### Step 3 — Development Approach per Task
+#### Step 3  -  Development Approach per Task
 
 For each task, determine:
 | Approach | When | Example |
@@ -64,7 +93,7 @@ For each task, determine:
 
 Store approach in task metadata for Phase 3 agent.
 
-#### Step 4 — Skill Selection per Task
+#### Step 4  -  Skill Selection per Task
 
 Based on Phase 1 `detectedStack`, assign relevant skills:
 
@@ -76,21 +105,24 @@ Based on Phase 1 `detectedStack`, assign relevant skills:
 
 #### Output contract
 
-Phase 2 produces an object conforming to `pipeline/schemas/planning-output.schema.json` — `tasks[]` with `id`, `subject`, `targetFiles`, `complexity`, `blockedBy`, plus optional `architectureNotes` and `mode`. Phase 3 reads `tasks[]` in dependency order; the schema's `blockedBy` field drives the ready-task picker.
+Phase 2 produces an object conforming to `pipeline/schemas/planning-output.schema.json`  -  `tasks[]` with `id`, `subject`, `targetFiles`, `complexity`, `blockedBy`, plus optional `architectureNotes` and `mode`. Phase 3 reads `tasks[]` in dependency order; the schema's `blockedBy` field drives the ready-task picker.
 
-**required: validate the final plan before entering Phase 3.**
-
-The plan object must conform to `pipeline/schemas/planning-output.schema.json`. Validate with:
+**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
-echo "$PLAN_JSON" | node pipeline/scripts/validate-planning.mjs -
+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"
 ```
 
-Exit 1 means malformed — inspect errors (bad task id format, missing `files`, broken `dependsOn` edges, or cycle detection). Fix the plan and re-validate. Never enter Phase 3 with an invalid plan — downstream TDD iteration will silently drop ill-formed tasks.
+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 pipeline/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"
+Log: "Phase 2: Plan  -  {N} tasks created, {M} with architecture review, validator:pass"
 
-#### Step 4.5 — Emit Plan Todo List (opt-in)
+#### 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 `pipeline/schemas/plan-todos.schema.json` and persist into `agent-state.plan`. Pattern source: Windsurf Cascade's always-visible Todo list (<https://docs.windsurf.com/windsurf/cascade>) and Cursor Plan Mode's reviewable plan (<https://cursor.com/docs/agent/planning>).
 
@@ -113,11 +145,25 @@ bash "$HOME/.claude/lib/plan-todos.sh" set "$TASK_ID" "$TODO_BLOB"
 
 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.
+**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 (autopilot / `--dev` 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)`
 
-#### Step 5 — Plan Approval Gate (normal mode + autopilot safety)
+**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 }`.
 
-**Scope guard — skip this step entirely when BOTH of these hold:**
+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)
@@ -126,9 +172,9 @@ OR:
 
 - `state.onlyDevelop === true` (--dev contract: 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.
+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)
+##### 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).
 
@@ -141,18 +187,18 @@ reasons=$(jq -r '.reasons[] | "• \(.rule) (+\(.weight)): \(.detail)"' <<< "$ve
 
 | `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 `onayla`/`iptal`/edit. Log `🧠 Phase 2: Safety classifier — score {N}, autopilot paused, reasons={rules}`. |
+| `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.
+**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)
+##### 5a  -  Clarification Mode (conditional, max 2 rounds)
 
 Trigger if the plan Opus produced in Step 1-4 carries ANY ambiguity signal from Phase 1 analysis:
 
@@ -162,29 +208,29 @@ Trigger if the plan Opus produced in Step 1-4 carries ANY ambiguity signal from
 | 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 | Sub-task covers wording from siblings of its parent story — child scope unclear |
+| Parent-story scope drift | Sub-task covers wording from siblings of its parent story  -  child scope unclear |
 
 If any signal trips, DO NOT render the plan yet. Render structured questions:
 
 ```
-📋 Geliştirme Planı — {taskId}
+📋 Development Plan  -  {taskId}
 ────────────────────────────────────
-⚠️  Madde üzerinde plan çıkarmadan önce netleşmesi gereken noktalar var:
+⚠️  There are points that need clarifying before drafting a plan for this item:
 
 1. {question 1}
 2. {question 2}
 3. {question 3}
 
-Cevaplarını yaz, sonra plan çıkaracağım.
-(veya "iptal" yaz → task paused, sonra resume'la devam edebilirsin)
+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:
 
-- **"iptal"** → `state.status = "paused"`, log `🧠 Phase 2: Gate aborted (clarification)`, stop.
+- **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 (madde hâlâ net değil)` banner in Mode 5b, and let the user decide via approval/edit. This prevents infinite grooming loops on chronically under-specified tickets.
+**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"]`:
 
@@ -196,63 +242,69 @@ Persist to `state.phases["2"]`:
 }
 ```
 
-##### 5b — Approval Loop (always runs after clarification resolves or is skipped)
+##### 5b  -  Approval Loop (always runs after clarification resolves or is skipped)
 
 Render the plan:
 
 ```
-📋 Geliştirme Planı — {taskId}          {best-effort banner if 5a capped}
+📋 Development Plan  -  {taskId}          {best-effort banner if 5a capped}
 ────────────────────────────────────
-Özet:       {1-line summary}
-Yaklaşım:   {1-paragraph approach}
-Risk:       {low|medium|high} — {reason}
-Scope:      {S|M|L} ({N} dosya, {K} yeni)
-Dokunulacak dosyalar:
+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}
 
-Todo'lar ({N} adet):
-  1. {subject} — {approach}
-  2. {subject} — {approach} (blocked by #1)
+Todos ({N} total):
+  1. {subject}  -  {approach}
+  2. {subject}  -  {approach} (blocked by #1)
   ...
 
-Onaylıyor musun?
-  • "onayla" / "e" / "y"   → Phase 3'e geç
-  • "iptal" / "h" / "n"    → task paused (resume ile devam)
-  • serbest metin          → plan düzenleme isteği (örn. "auth servisine de bakalım ama LoginView kapsamda olmasın")
 ```
 
-Wait for user response:
+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: "Approve", description: "Proceed to development (Phase 3)" }`
+  - `{ label: "Cancel", description: "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. (`option.label` stays English per the language matrix; `question` + `description` follow `outputLanguage`.)
+
+Handle the selection:
 
-- **`onayla` / `e` / `y` / `yes` / `evet`** (case-insensitive, trimmed):
+- **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
-- **`iptal` / `h` / `n` / `no` / `hayır`**:
+- **Cancel**:
   - Set `state.status = "paused"`, log `🧠 Phase 2: Plan aborted by user`, stop
-- **Anything else (free-text)**:
-  - Treat as an edit request. Append to `state.phases["2"].planEditRequests`, bump `planIterations`
+- **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 Opus; Opus 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 `onayla` or `iptal`. Between iterations, keep only the **latest plan** as canonical; previous renders are in the log for audit but do not re-enter the validator.
+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 pipeline/scripts/validate-planning.mjs -` before re-render. If validation fails after an edit, log `⚠️ Phase 2: Plan validator failed after edit request #N — retrying Opus 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.
+**Validator**: every revised plan goes through `node pipeline/scripts/validate-planning.mjs -` before re-render. If validation fails after an edit, log `⚠️ Phase 2: Plan validator failed after edit request #N  -  retrying Opus 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)
+#### Step 6  -  Mode-specific short-circuit (reference)
 
-The 4 pipeline modes 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.
+The 4 pipeline modes 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 |
 |---|---|---|---|---|
-| Normal (`multi-agent "task"`) | ✅ (max 2 rounds) | ✅ | — (redundant in normal mode) | Full gate |
-| `--dev` | ❌ | ❌ | — | Phase 1-2 already skipped; Phase 3 starts immediately |
+| Normal (`multi-agent "task"`) | ✅ (max 2 rounds) | ✅ |  -  (redundant in normal mode) | Full gate |
+| `--dev` | ❌ | ❌ |  -  | Phase 1-2 already skipped; Phase 3 starts immediately |
 | `autopilot` | ❌ | ❌ conditional | ✅ (if `autopilotSafetyGate !== false`) | Safe plans proceed silently; high-risk plans trigger a one-time manual approval. Log records the score. |
-| `--dev autopilot` | ❌ | ❌ | — | Phase 3 starts immediately (no plan exists to classify) |
+| `--dev autopilot` | ❌ | ❌ |  -  | Phase 3 starts immediately (no plan exists to classify) |
 
-**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.
+**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
+#### Telemetry  -  token forwarding
 
 After plan generation (and after each edit-loop iteration), forward Opus call totals so Phase 7's Cost Breakdown captures Phase 2:
 
@@ -265,7 +317,7 @@ Best-effort. See `refs/progress-contract.md#token-telemetry-forwarding-v83`.
 
 ---
 
-## Token telemetry — invoke after every LLM call
+## Token telemetry  -  invoke after every LLM call
 
 After every LLM call in this phase (analysis, plan generation, code/diff write, review verdict, triage), invoke:
 
@@ -275,4 +327,4 @@ bash $HOME/.claude/scripts/phase-tracker.sh tokens 2 <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 2  Dev   2m 14s · 12.4k tok`). This satisfies the contract in `refs/tracker-contract.md` and the `smoke-tracker-tokens-invocation.sh` enforcement gate. Skipping this call is the #1 cause of "I can't see how much it cost" complaints.
 
-If you do not have access to the model's reported token counts, pass best-effort estimates derived from input length / output length — partial cost data is better than none.
+If you do not have access to the model's reported token counts, pass best-effort estimates derived from input length / output length  -  partial cost data is better than none.