@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/commands/multi-agent/refs/phases/phase-1-analysis.md

@@ -0,0 +1,264 @@
+### Phase 1: Analysis (Opus)
+
+> **TLDR** — Opus-driven codebase exploration. Detects if the issue is already fixed (git blame, closed PRs), then launches parallel Explore sub-agents to map the affected code paths. Outputs: impact analysis, stack detection (auto-selects platform guide), relevant files, risk areas. Feeds Phase 2 planning.
+
+<!-- progress-contract: applied -->
+Progress emission per `refs/progress-contract.md` — lines for each Explore dispatch, each finish, analyst synthesis start, `analysis.json` write.
+
+#### Step 0 — Prior Fix Detection
+
+Before any analysis, check if this issue was already fixed by someone else.
+
+**Check order:**
+
+1. **Git commit search** — look for commits referencing this issue ID across all branches:
+
+   ```bash
+   git -C $PROJECT_ROOT log --all --oneline --grep="{jiraId}" --since="8 weeks ago"
+   ```
+
+2. **Affected file history** — after identifying key files (from issue description keywords), check recent changes:
+
+   ```bash
+   git -C $PROJECT_ROOT log --oneline --since="4 weeks ago" -- {affected_file_paths}
+   ```
+
+3. **Jira comments/status** — fetch latest comments to see if someone reported a fix:
+   ```bash
+   curl -s -H "Authorization: Bearer $JIRA_TOKEN" \
+     "$JIRA_BASE/issue/{jiraId}?fields=status,comment&expand=changelog" \
+     | jq '.fields.status.name, .fields.comment.comments[-3:][]?.body'
+   ```
+
+**If prior fix commit(s) found:**
+
+```
+This issue appears to already have been addressed:
+  {hash} — {message} (by {author}, {date})
+
+Options:
+  1. Verify fix (check if cherry-pick/merge to base branch is needed)
+  2. Stop pipeline (already resolved)
+  3. Continue anyway (different fix needed)
+```
+
+- Option 1 → Check if the commit exists on `baseBranch`. If not, suggest cherry-pick. Pipeline pauses.
+- Option 2 → Cleanup and exit:
+  1. Checkout back to base branch: `git -C $PROJECT_ROOT checkout {baseBranch}`
+  2. Delete the created branch: `git -C $PROJECT_ROOT branch -D {branch}`
+  3. If worktree was used: `git -C $PROJECT_ROOT worktree remove {worktreePath} --force`
+  4. Set `agent-state.json` status to `"stopped_already_fixed"`. Log and exit.
+- Option 3 → Continue to Step 1 as normal.
+
+**If no prior fix found** → continue to Step 1.
+
+#### Step 1 — Knowledge Injection (cached context)
+
+Before launching Explore agents, check if project knowledge exists:
+
+```
+$HOME/.claude/knowledge/{project-name}/
+  architecture.md    — file structure, module map, dependency graph
+  patterns.md        — patterns in use, conventions, idioms
+  gotchas.md         — encountered issues, edge cases and solutions
+  decisions.md       — architectural decisions and rationale (ADR-lite)
+```
+
+Also read project-level CLAUDE.md if exists:
+
+- `$PROJECT_ROOT/CLAUDE.md`
+- `$PROJECT_ROOT/.claude/CLAUDE.md`
+
+**Per-repo memory injection (opt-in via `prefs.global.perRepoMemory`):**
+
+```bash
+bash pipeline/scripts/memory-load.sh "$PROJECT_ROOT"
+```
+
+Exit 0 with empty output = pref off or no memory on disk — skip. Otherwise the script emits a `<repo-memory path="…">…</repo-memory>` block (≤ 30 lines of MEMORY.md pointers) suitable for direct injection into the analysis prompt. Individual memory files are read on-demand when a pointer looks relevant to the current task.
+
+**If knowledge files exist and are fresh** (modified within last 90 days — see knowledge.md staleness rules):
+
+1. Read relevant knowledge files based on task description
+2. Use knowledge to **narrow Explore scope** — instead of "very thorough" full scan, do targeted exploration of only unknown/changed areas
+3. Log: "Phase 1: Knowledge injected ({N} files), targeted explore"
+
+**If no knowledge exists** (first time for this project):
+
+1. Launch full Explore agents as before
+2. Log: "Phase 1: Full explore (no cached knowledge)"
+
+#### Step 1.5 — External Context Injection (`state.contextLinks[]`)
+
+Phase 0 Step 1b catalogued every typed external link from the task description into `state.contextLinks[]`. Phase 1 now dispatches each entry to its matching fetcher and prepends the result to the analysis prompt under a **Referenced External Sources** section, so the agent doesn't re-discover what the ticket already pointed at.
+
+```bash
+jq -c '.contextLinks // []' "$STATE_FILE" \
+  | python3 -c '
+import json, sys, os
+links = json.loads(sys.stdin.read() or "[]")
+by_type = {}
+for l in links:
+    by_type.setdefault(l["type"], []).append(l)
+print(json.dumps(by_type))
+' > /tmp/context-by-type-${TASK_ID}.json
+```
+
+Dispatch table — one fetcher per type. Each fetcher emits a normalized JSON view that the analysis prompt consumes as ground truth for the referenced source.
+
+| Type | Fetcher | Output stored in |
+|---|---|---|
+| `crashlytics` | `~/.claude/lib/fetch-crashlytics.sh <url>` (already invoked in Phase 0 Step 1b.1 for the legacy `state.crashContext` field; Phase 1 reads that field directly) | `state.crashContext` |
+| `fortify` | `~/.claude/lib/fetch-fortify.sh <url>` (already invoked in Phase 0 Step 1b.2 for the legacy `state.fortifyFinding` field; Phase 1 reads that field, Phase 4 reads the full payload for the security gate) | `state.fortifyFinding` |
+| `swagger` | `~/.claude/lib/fetch-swagger.sh <url>` → endpoints[], request/response examples | `state.fetchedContext.swagger[]` |
+| `confluence` | `~/.claude/lib/fetch-confluence.sh <url>` → page body, code blocks, extracted API contracts | `state.fetchedContext.confluence[]` |
+| `figma` | `~/.claude/lib/fetch-figma.sh <url>` (via existing MCP / REST fallback path) when the task is a component; otherwise advisory only | `state.fetchedContext.figma[]` |
+| `generic-doc` | no automatic fetcher — surfaced as advisory; the agent uses WebFetch on demand when the URL turns out to be load-bearing | n/a |
+
+Each fetcher exit code is treated as follows:
+- `0` (success) → output appended to `state.fetchedContext.<type>[]` and injected into the prompt.
+- `2` (blocked / missing token) → run the inline Token Save Flow per `setup.md`; on skip, mark the entry as `{status: "skipped", reason: "missing-token"}` and continue.
+- `3` (network/auth) → mark as `{status: "failed", reason: "<exit-msg>"}`, continue.
+- `4`/`5`/`6` (config errors) → mark as `{status: "failed", reason: "<exit-msg>"}`, continue and log a setup hint.
+
+Failures are never fatal at Phase 1 — the agent still runs analysis, just without the referenced source.
+
+**Prompt injection shape** (added immediately after the knowledge-injection block, before codebase exploration):
+
+```
+## Referenced External Sources
+
+(when fetchers populated `state.fetchedContext.<type>`)
+### <type> — <url>
+<fetched content, scoped to relevance>
+
+(when fetcher pending)
+### Pending references
+- <type>: <url> — <one-line metadata>
+```
+
+The agent treats fetched content as **ground truth** for the referenced source (no re-discovery, no contradiction). Pending references are advisories — the agent decides whether to fetch via WebFetch on demand when the task hinges on that source.
+
+**Log line shape**:
+
+```
+→ context injection: total=<N>, fetched=<n>, pending=<n>, by-type={swagger:F/P, confluence:F/P, ...}
+```
+
+`F` = fetched, `P` = pending. Empty contextLinks → `total=0`, skip the section entirely.
+
+#### Step 2 — Stack Detection
+
+Detect the project's tech stack to load appropriate skills and tooling throughout the pipeline. Auto-detect by scanning `$PROJECT_ROOT` (maxdepth 2) for project markers:
+
+| Stack          | Marker Files                                    | Skills                                                       |
+| -------------- | ----------------------------------------------- | ------------------------------------------------------------ |
+| iOS/Swift      | `.xcodeproj`, `Package.swift`                   | iOS skills, `swift-testing`                                  |
+| Android/Kotlin | `build.gradle`, `build.gradle.kts`              | `android-jetpack-compose-expert`, `kotlin-coroutines-expert` |
+| Python         | `requirements.txt`, `pyproject.toml`, `Pipfile` | `fastapi-pro`, `api-patterns`                                |
+| Node.js        | `package.json`                                  | `nodejs-backend-patterns`, `api-patterns`                    |
+| Go             | `go.mod`                                        | `api-patterns`, `clean-code`                                 |
+| Docker         | `Dockerfile`, `docker-compose.yml`              | `docker-expert`                                              |
+| Monorepo       | Multiple of above                               | `monorepo-architect`                                         |
+
+Store in `agent-state.json` → `"detectedStack": ["ios", "python", "docker"]`
+
+This informs:
+
+- Phase 3: which build/test commands to use
+- Phase 4: which deterministic gates and reviewer skills to load
+- Phase 6: which PR template fits best
+
+#### Step 2.5 — Repo Map Injection (advisory, opt-in)
+
+**Gated by `prefs.global.repoMap.enabled`** (default: `false`). Pattern source: <https://aider.chat/docs/repomap.html>.
+
+Before launching Explore agents, run the deterministic repo map renderer and inject the result into each Explore prompt as `${REPO_MAP}`. This gives every explorer a token-budgeted overview of the most-referenced files in the repo — ranked via cross-file declaration references with TF-IDF-style credit splitting so universally-shared helper names (`pass`, `fail`, `init`) don't dominate.
+
+```bash
+REPO_MAP=""
+if [ "$(jq -r '.global.repoMap.enabled // false' "$PREFS")" = "true" ]; then
+  BUDGET=$(jq -r '.global.repoMap.tokenBudget // 1500' "$PREFS")
+  TOP=$(jq -r '.global.repoMap.topFiles // 25' "$PREFS")
+  INCLUDE=$(jq -r '.global.repoMap.include // empty' "$PREFS")
+  EXCLUDE=$(jq -r '.global.repoMap.exclude // empty' "$PREFS")
+  args=(--root "$WORKTREE" --budget "$BUDGET" --top "$TOP" --format md)
+  [ -n "$INCLUDE" ] && args+=(--include "$INCLUDE")
+  [ -n "$EXCLUDE" ] && args+=(--exclude "$EXCLUDE")
+  REPO_MAP=$(node pipeline/scripts/repo-map.mjs "${args[@]}" 2>/dev/null || echo "")
+fi
+```
+
+**Properties:**
+
+- **Deterministic** — same worktree state → same map. No embeddings, no network. Sub-second on monorepos.
+- **Advisory** — Explore agents may ignore the map if they have stronger signals (Phase 0 knowledge cache, explicit user context). Never gates the pipeline.
+- **Truncation-safe** — output is capped at `tokenBudget`; the script falls back to "no files extracted within budget" rather than over-spending.
+- **Cost ledger** — emit `phase-1.repo_map_emitted bytes=$(wc -c <<<"$REPO_MAP") budget=$BUDGET` so Phase 7 cost summary can show the size injected.
+
+**When to enable:** large repos (>200 source files) where Explore otherwise spends multiple rounds finding the right starting files. Skip on small repos — the overhead exceeds the gain.
+
+#### Step 3 — Codebase Exploration
+
+Launch parallel Explore agents to scan codebase:
+
+- Related files to the task
+- Existing patterns and conventions
+- Potential impact areas
+
+Use `subagent_type: "Explore"` with thoroughness based on knowledge availability:
+
+- Knowledge exists → "medium" (targeted, cheaper)
+- No knowledge → "very thorough" (full scan, first time investment)
+
+#### Output contract
+
+Phase 1 produces an object conforming to `pipeline/schemas/analysis-output.schema.json` and persists it to `state.analysis`. Required fields: `stack` (detected stack identifier + primary language), `touchedAreas[]` (path + why), `findings[]` (existing-code observations the planner must respect), `summary` (one-paragraph human-readable). Phase 2 reads this object as its sole input — see `phase-2-planning.md`'s Input contract.
+
+**Required: validate the explorer output before passing to Phase 2.**
+
+Explorer must return an object conforming to `pipeline/schemas/analysis-output.schema.json`. Validate with:
+
+```bash
+echo "$ANALYSIS_JSON" | node pipeline/scripts/validate-analysis.mjs -
+```
+
+Exit 1 means malformed — re-invoke once, then fall back to a minimal placeholder (`{"stack":{"primary":"unknown"},"touchedAreas":[{"path":".","why":"explorer validation failed, Phase 2 will ask user"}],"summary":"Phase 1 exploration unavailable — Phase 2 runs with user-provided context."}`) and log the failure in `agent-state.phases["1"].warnings`.
+
+Log: "Phase 1: Analysis — stack:{detectedStack} | {N} files identified, {summary}"
+
+#### Telemetry — token forwarding
+
+Forward the explorer/Opus call's token totals into the tracker so Phase 7's Cost Breakdown captures Phase 1:
+
+```bash
+LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" 1 analysis.completed \
+  model=opus tokens_in=$IN tokens_out=$OUT duration_ms=$DUR
+```
+
+Best-effort. See `refs/progress-contract.md#token-telemetry-forwarding-v83` for the canonical contract.
+
+#### Prior-Art Enrichment (advisory)
+
+After the explorer returns its summary, consult the per-repo triage corpus for similar past tasks. Inject up to 3 matches into the analysis output as `priorArt[]` so Phase 2 planning can read them. Disabled when `prefs.global.priorArtEnrichment.enabled = false`.
+
+```bash
+PRIOR=$(node pipeline/scripts/triage-memory.mjs query \
+  --issue "$TASK_TITLE $TASK_DESCRIPTION" --top 3 2>/dev/null | jq -c '.hits // []')
+```
+
+Treat hits as **context only** — they are past Phase 4 verdicts, not prescriptions. Useful when the new task touches the same files or symbols as a previous run.
+
+---
+
+## 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 1 <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 1  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-2-planning.md

@@ -0,0 +1,278 @@
+### Phase 2: Planning (Opus)
+
+> **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.
+
+#### 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.
+
+#### 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.
+
+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 -> SwiftUI skills, iOS patterns
+- Python tasks -> `fastapi-pro`, `api-patterns`
+- Node tasks -> `nodejs-backend-patterns`
+- Security-sensitive -> `api-security-best-practices`
+- Multi-submodule -> `monorepo-architect`
+
+#### 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.
+
+**required: validate the final plan before entering Phase 3.**
+
+The plan object must conform to `pipeline/schemas/planning-output.schema.json`. Validate with:
+
+```bash
+echo "$PLAN_JSON" | node pipeline/scripts/validate-planning.mjs -
+```
+
+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.
+
+Log: "Phase 2: Plan — {N} tasks created, {M} with architecture review, validator:pass"
+
+#### 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>).
+
+```bash
+TODO_BLOB=$(jq '
+  {
+    title: .summary,
+    todos: [ .tasks[] | {
+      id:               .id,
+      task:             .subject,
+      status:           "pending",
+      deps:             (.dependsOn // .blockedBy // []),
+      estimatedMinutes: (.estimatedMinutes // null)
+    } | with_entries(select(.value != null)) ]
+  }
+' <<<"$PLAN_JSON")
+
+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.
+
+#### 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` (--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.
+
+##### 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 pipeline/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 `onayla`/`iptal`/edit. 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 Opus 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 | 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}
+────────────────────────────────────
+⚠️  Madde üzerinde plan çıkarmadan önce netleşmesi gereken noktalar var:
+
+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)
+```
+
+Wait for user response. On reply:
+
+- **"iptal"** → `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.
+
+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:
+
+```
+📋 Geliştirme 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:
+  - {path1}
+  - {path2}
+
+Todo'lar ({N} adet):
+  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:
+
+- **`onayla` / `e` / `y` / `yes` / `evet`** (case-insensitive, trimmed):
+  - 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`**:
+  - 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`
+  - 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.
+
+**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)
+
+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 |
+| `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) |
+
+**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 Opus call totals so Phase 7's Cost Breakdown captures Phase 2:
+
+```bash
+LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" 2 plan.generated \
+  model=opus tokens_in=$IN tokens_out=$OUT duration_ms=$DUR iteration=$N
+```
+
+Best-effort. See `refs/progress-contract.md#token-telemetry-forwarding-v83`.
+
+---
+
+## 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 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.