@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

package/pipeline/commands/multi-agent/refs/phases/phase-0-init.md

@@ -1,10 +1,10 @@
 ### Phase 0: Init
 
-> **TLDR** — 8 sequential steps: load prefs → parse input (Jira/GitHub/free-text) → select project → detect remote + pick base branch → optional design input → branch name → git identity → instruction files → create worktree/local branch + agent-state.json. Every input type (Jira URL, GitHub issue, free-text) flows through the same 8 steps.
+> **TLDR**  -  8 sequential steps: load prefs → parse input (Jira/GitHub/free-text) → select project → detect remote + pick base branch → optional design input → branch name → git identity → instruction files → create worktree/local branch + agent-state.json. Every input type (Jira URL, GitHub issue, free-text) flows through the same 8 steps.
 
-#### Step −1 — Bootstrap the cross-CLI tracker (FIRST thing in every run)
+#### Step −1  -  Bootstrap the cross-CLI tracker (FIRST thing in every run)
 
-Before anything else — initialize the visual tracker so the user sees the pipeline's shape immediately. This is the **only** progress signal Copilot CLI users get; Claude users also get native TaskCreate tiles.
+Before anything else  -  initialize the visual tracker so the user sees the pipeline's shape immediately. This is the **only** progress signal Copilot CLI users get; Claude users also get native TaskCreate tiles.
 
 ```bash
 TASK_ID="${INPUT_TASK_ID:-pipeline-$(date +%Y%m%d-%H%M%S)}"
@@ -21,11 +21,11 @@ Every subsequent phase (1-7) MUST call `phase-tracker.sh update <N> in_progress`
 
 ##### TaskCreate ordering on Claude Code (strict)
 
-On Claude Code, fire all `TaskCreate` calls in strict phase-number order (0 → 7) BEFORE any `TaskUpdate`. Full contract: `refs/tracker-contract.md` § "TaskCreate ordering (strict)".
+On Claude Code, fire all `TaskCreate` calls in strict phase-number order (0 → 7) BEFORE any `TaskUpdate`. Full contract: `refs/tracker-contract.md` section "TaskCreate ordering (strict)".
 
 ---
 
-#### Step 0 — Load Preferences
+#### Step 0  -  Load Preferences
 
 Read preferences: `PREFS_FILE="$HOME/.claude/multi-agent-preferences.json"` (if missing, start with `{"projects": {}, "global": {}}`).
 
@@ -37,7 +37,9 @@ OUTPUT_LANG=$(jq -r '.global.outputLanguage // "en"' "$PREFS_FILE" 2>/dev/null |
 
 From this point on, every assistant-authored conversational line (status updates, findings, phase headers, summaries, error explanations) renders in `$OUTPUT_LANG`. `AskUserQuestion` payloads stay English. External payloads stay English. See `refs/rules.md` "Language Application" for the full contract. Skipping this step is the failure mode where the user sees an English wall of text in a Turkish session.
 
-**First-run guard**: After loading prefs, check if `keychainMapping` has at least one non-null value. If ALL values are null (template defaults — setup never ran), show:
+**Model fallback date gate** (same step, once per run): read `prefs.global.modelFallback`. If `premiumTierUntil` is set and in the past, apply the date-gate trigger from `refs/features/model-fallback.md` - fable personas dispatch on `fallbackModel` for this run, with the one-line WARN. Dispatch-error and budget triggers in that contract apply per-dispatch later; nothing else to do here.
+
+**First-run guard**: After loading prefs, check if `keychainMapping` has at least one non-null value. If ALL values are null (template defaults  -  setup never ran), show:
 ```
 ⚠ No keychain tokens mapped. Run /multi-agent setup first to discover
   and map your tokens. Without this, the pipeline cannot authenticate
@@ -45,18 +47,18 @@ From this point on, every assistant-authored conversational line (status updates
 
   → /multi-agent setup    (interactive, ~2 min)
 ```
-Then STOP Phase 0 — do not proceed with a broken token state. This prevents the user from hitting auth errors deep in Phase 1-6 and wondering why.
+Then STOP Phase 0  -  do not proceed with a broken token state. This prevents the user from hitting auth errors deep in Phase 1-6 and wondering why.
 
-**Preferences schema** — see `prefs.schema.json` for full definition. Key paths: `projects[{name}]` (branches, lastIdentity, jiraProjectKeys, jiraTeams, jiraComponents, jiraVersions, confluenceUrls, remoteType, jiraTeamFieldId, taskCount, lastUsed) + `global` (identities, keychainMapping, defaultJiraKey, jiraCommentDefault, confluenceDefault, recentProjects, recentBranches, recentGroups, platformIdentityRouting, serviceStatus, settings, triageCrossCheck, promptLanguage).
+**Preferences schema**  -  see `prefs.schema.json` for full definition. Key paths: `projects[{name}]` (branches, lastIdentity, jiraProjectKeys, jiraTeams, jiraComponents, jiraVersions, confluenceUrls, remoteType, jiraTeamFieldId, taskCount, lastUsed) + `global` (identities, keychainMapping, defaultJiraKey, jiraCommentDefault, confluenceDefault, recentProjects, recentBranches, recentGroups, platformIdentityRouting, serviceStatus, settings, triageCrossCheck, promptLanguage).
 
 **Key design**: Every field is an **array of all historical values** (most recent first) → "recently used" list.
 
-**Token resolution rule**: ALWAYS check `prefs.global.keychainMapping.<service_id>` first for the key name — this holds the user's actual Keychain key name (which may differ from the standard convention). Fall back to standard key name ONLY when setup has never run (mapping absent). The standard fallback exists as a safety net, not as the primary path. Service IDs: `jira`, `bitbucket_token`, `bitbucket_user`, `github`, `confluence`, `figma`, `figma_mcp`, `fortify`, `firebase`, `jenkins`.
+**Token resolution rule**: ALWAYS check `prefs.global.keychainMapping.<service_id>` first for the key name  -  this holds the user's actual Keychain key name (which may differ from the standard convention). Fall back to standard key name ONLY when setup has never run (mapping absent). The standard fallback exists as a safety net, not as the primary path. Service IDs: `jira`, `bitbucket_token`, `bitbucket_user`, `github`, `confluence`, `figma`, `figma_mcp`, `fortify`, `firebase`, `jenkins`.
 
 **Jira project key resolution** (first match wins):
 
-1. `prefs.projects[{project}].jiraProjectKeys[0]` — project-specific
-2. `prefs.global.defaultJiraKey` — global default
+1. `prefs.projects[{project}].jiraProjectKeys[0]`  -  project-specific
+2. `prefs.global.defaultJiraKey`  -  global default
 3. Ask user → save to `prefs.global.defaultJiraKey`
 
 Used for: input parsing, branch naming, commit messages.
@@ -75,9 +77,28 @@ Used for: input parsing, branch naming, commit messages.
 | Service ping (any external API call) | `global.serviceStatus[{service}]` | `{ok, checkedAt, reason?}` (TTL `settings.serviceStatusCacheSeconds`, default 300s) | n/a |
 | Git identity routed (Step 6a) | `projects[{name}].lastIdentity` | int (index into `global.identities`) | n/a |
 
-All updates are O(1) — read-modify-write on the in-memory `prefs` object; single atomic write at the end of Phase 0 (and again at Phase 7).
+All updates are O(1)  -  read-modify-write on the in-memory `prefs` object; single atomic write at the end of Phase 0 (and again at Phase 7).
+
+#### Step 0.5 - Figma access pre-flight (BLOCKING when task carries a Figma reference)
+
+When Step 1 input parsing surfaces a Figma reference (URL, node ID, or "from the design" free-text alongside a UI file target), Phase 0 MUST establish the Figma access tier before any other phase runs. Persist `state.figmaAccess.tier` (1, 2, or 3) into the run state so every downstream phase reads the same value.
+
+Probe order:
+
+1. **Tier 1 (Figma MCP)**: dispatch a lightweight probe `mcp__claude_ai_Figma__get_metadata(fileKey, nodeId)` for the first referenced frame. Auth failure runs `mcp__claude_ai_Figma__authenticate` + `mcp__claude_ai_Figma__complete_authentication` then retries once. Success → `state.figmaAccess.tier = 1`.
+2. **Tier 2 (Figma REST)**: when Tier 1 fails, resolve the PAT via `~/.claude/lib/credential-store.sh get <logical-key>` where `<logical-key>` = `prefs.global.keychainMapping.figma_pat`. Probe `GET https://api.figma.com/v1/files/{fileKey}/nodes?ids={nodeId}` with header `X-Figma-Token: $TOKEN`. HTTP 200 → `state.figmaAccess.tier = 2`. Token missing / 401 / 403 → fall through.
+3. **Tier 3 (User-attached screenshot)**: when Tiers 1 + 2 both fail, scan the task payload for inline screenshots or attachments. Present → `state.figmaAccess.tier = 3` and `state.figmaAccess.reviewBlocking = true` (Phase 4 enforces this).
+4. **Halt**: all three tiers fail → emit a single AskUserQuestion asking the user how to proceed (provide PAT, paste a screenshot, abort). Never proceed with text-derived guesses.
+
+Log the resolved tier in the agent log:
+
+```
+→ figma access tier: <1|2|3>
+```
 
-#### Step 1 — Parse Input
+Full chain definition, REST endpoints, URL parsing, canonical-component contract: `pipeline/rules/figma-pipeline.md` "MUST: Figma access - 3-tier fallback chain (BLOCKING, pipeline-wide)". Do not duplicate it here.
+
+#### Step 1  -  Parse Input
 
 **Branch from input**: If the user provided a branch name after the issue reference (space-separated), store as `baseBranch` and skip Step 3. Otherwise Step 3 asks interactively.
 
@@ -93,7 +114,7 @@ Classify and fetch external data:
 
 **GitHub Issue #** (`#316` or `316`):
 
-1. Store issueNumber — repo determined after project selection (Step 2)
+1. Store issueNumber  -  repo determined after project selection (Step 2)
 2. After selection: `git remote get-url origin` → extract org/repo → fetch as above
 
 **Jira URL** (`https://{JIRA_HOST}/browse/{jiraId}`):
@@ -112,24 +133,38 @@ Classify and fetch external data:
 
 **Free-text**:
 
+0. **Intent guard (conceptual-vs-edit)**  -  gated by `prefs.global.intentGuard.enabled` (default `true`). Before any project selection, worktree, or Jira prompt, classify the input:
+   ```bash
+   INTENT=$(bash pipeline/lib/classify-intent.sh "$DESCRIPTION")
+   ```
+   - `question` -> the user asked something conceptual, not a task to implement. Do NOT create a branch/worktree/Jira. Surface a picker (picker-contract): **Answer here** (default) / **Treat as a task**. On "Answer here" (autopilot default for `question`), answer the question directly in chat and end the run cleanly  -  no dev chain, no commits. On "Treat as a task", fall through to step 1 below.
+   - `ambiguous` or `task` -> proceed to step 1 (normal task flow). Ambiguous input is treated as a task; the guard never blocks an actionable request.
+
+   This kills the most-cited daily annoyance (the agent starts editing when asked a question) without adding latency to real tasks  -  the check is a deterministic local classifier, no model call. Other input types (Jira id, issue URL/number, repo#N) are always explicit tasks and skip the guard.
+
 1. Store as description. No external fetch.
-2. After project selection (Step 2), ask: `Want to create a Jira issue for this task? (y/n)`
+2. After project selection (Step 2), ask with a native `AskUserQuestion` picker (never a typed y/n):
+   - `question`: "Create a Jira issue for this task?" (rendered in `outputLanguage`)
+   - `header`: "Jira" (English, <=12 chars)
+   - `options`:
+     - `{ label: "Create", description: "Open the interactive Jira issue creation flow" }`
+     - `{ label: "Skip", description: "Continue without Jira; branch uses feature/{short-kebab} or bugfix/{short-kebab}" }`
 
-**If yes → Interactive Jira Issue Creation** (resolve `JIRA_TOKEN` via keychainMapping):
+**If Create → Interactive Jira Issue Creation** (resolve `JIRA_TOKEN` via keychainMapping):
 
 Sequential prompts (standard UX pattern with Recent suggestion): Project Key → Issue Type → Summary → Target Version → Team → Component/s → Priority → Description. All selections saved to `prefs.projects[{project}]`. Create via `POST $JIRA_BASE/issue`; team uses custom field (discover via `/field` API, cache in `jiraTeamFieldId`).
 
-**If no → continue without Jira.** Branch uses `feature/{short-kebab}` or `bugfix/{short-kebab}`.
+**If Skip → continue without Jira.** Branch uses `feature/{short-kebab}` or `bugfix/{short-kebab}`.
 
-**Token pre-check** (after parsing): Jira input → resolve key via `prefs.global.keychainMapping.jira`, verify token with a lightweight API call (e.g. `GET /myself`). GitHub input → verify `gh auth status`. On failure (missing key, 401, 403) → run the **Token Save Flow** from `setup.md` inline. This is the same clipboard-based flow used during setup — token never appears in terminal. If user skips and the token is critical for the input type (e.g. Jira token for Jira input), halt Phase 0.
+**Token pre-check** (after parsing): Jira input → resolve key via `prefs.global.keychainMapping.jira`, verify token with a lightweight API call (e.g. `GET /myself`). GitHub input → verify `gh auth status`. On failure (missing key, 401, 403) → run the **Token Save Flow** from `setup.md` inline. This is the same clipboard-based flow used during setup  -  token never appears in terminal. If user skips and the token is critical for the input type (e.g. Jira token for Jira input), halt Phase 0.
 
 **VPN connectivity check**: Test VPN-dependent services (Jira, Bitbucket, Confluence, Fortify) with `curl --connect-timeout 3`. If unreachable, warn and offer to continue. Fallback: Jira → manual input, Bitbucket → `git push` only, Confluence → skip Phase 7, Fortify → skip scan. Cache in `agent-state.json` → `"vpnServices": {"jira": true, ...}`.
 
-#### Step 1b — URL Enrichment (catalogue + targeted deep fetches)
+#### Step 1b  -  URL Enrichment (catalogue + targeted deep fetches)
 
 After Step 1 fetches the Jira description (or free-text input), every URL in the text gets classified and catalogued. Targeted deep fetches (Crashlytics, Fortify) run when the matching link type is present; the rest (Swagger, Confluence, Figma, generic doc) are catalogued so Phase 1 (Analysis) can consume them via the typed fetchers documented in `refs/channels/*.md`.
 
-##### Step 1b.0 — Extract context links (always runs)
+##### Step 1b.0  -  Extract context links (always runs)
 
 Pipe the description text through `~/.claude/lib/context-link-extractor.sh` and store the result on the state:
 
@@ -144,7 +179,7 @@ jq --slurpfile links /tmp/context-links-${TASK_ID}.json \
    "$STATE_FILE" > "$STATE_FILE.tmp" && mv "$STATE_FILE.tmp" "$STATE_FILE"
 ```
 
-Output schema (one array entry per URL — full contract in `~/.claude/lib/context-link-extractor.sh`):
+Output schema (one array entry per URL  -  full contract in `~/.claude/lib/context-link-extractor.sh`):
 
 ```jsonc
 "contextLinks": [
@@ -157,26 +192,26 @@ Output schema (one array entry per URL — full contract in `~/.claude/lib/conte
 ]
 ```
 
-The catalogue is the single source of truth for downstream phases — they read `state.contextLinks[]` and dispatch per `type`. The extractor is deterministic: same input → same output, no network calls, no auth.
+The catalogue is the single source of truth for downstream phases  -  they read `state.contextLinks[]` and dispatch per `type`. The extractor is deterministic: same input → same output, no network calls, no auth.
 
-##### Step 1b.1 — Firebase Crashlytics deep fetch (runs when `type == "crashlytics"` present in `state.contextLinks[]`)
+##### Step 1b.1  -  Firebase Crashlytics deep fetch (runs when `type == "crashlytics"` present in `state.contextLinks[]`)
 
 URL pattern (caught by the extractor): `console.firebase.google.com/(u/[0-9]+/)?project/<projectId>/crashlytics/app/(ios|android)(:|%3A)<bundleOrPackage>/issues/<issueId>(/sessions/<sessionId>)?`
 
 - Host is fixed (`console.firebase.google.com`); no `hosts.firebase` pref needed.
-- Token resolution: `prefs.global.keychainMapping.firebase` → `~/.claude/lib/credential-store.sh get "<key>" | base64 -d` → Service Account JSON. `project_id` read from decoded JSON — verify it matches the `<projectId>` from the URL; mismatch → warn, skip enrichment.
-- Exchange the SA JSON for a short-lived GCP access token (scope `https://www.googleapis.com/auth/firebase https://www.googleapis.com/auth/cloud-platform`) using `google-auth` (Python) or an inline JWT exchange (OpenSSL sign → `https://oauth2.googleapis.com/token`). Cache in-memory for the pipeline run only — never persist.
+- Token resolution: `prefs.global.keychainMapping.firebase` → `~/.claude/lib/credential-store.sh get "<key>" | base64 -d` → Service Account JSON. `project_id` read from decoded JSON  -  verify it matches the `<projectId>` from the URL; mismatch → warn, skip enrichment.
+- Exchange the SA JSON for a short-lived GCP access token (scope `https://www.googleapis.com/auth/firebase https://www.googleapis.com/auth/cloud-platform`) using `google-auth` (Python) or an inline JWT exchange (OpenSSL sign → `https://oauth2.googleapis.com/token`). Cache in-memory for the pipeline run only  -  never persist.
 - Fetch crash detail: `GET https://firebasecrashlytics.googleapis.com/v1alpha/projects/<projectId>/apps/<appId>/issues/<issueId>` (issue summary + top device + OS + impacted users + top stack frame). If `sessionId` present, also fetch `/sessions/<sessionId>` for the full session timeline.
 - Store as `state.crashContext = { projectId, appId, issueId, title, subtitle, impactedUsers, topDevices[], topOS[], topStackFrame, sessionTimeline?, fetchedAt }`.
 - Phase 1 Analysis prepends `state.crashContext` to the agent prompt under a **Known Crash Context** section (do not rediscover, use as ground truth).
 - Soft-fail: any network/auth error → log warning, continue pipeline without enrichment (ticket still gets manually analysed).
 
-##### Step 1b.2 — Fortify SSC deep fetch (runs when `type == "fortify"` present in `state.contextLinks[]`)
+##### Step 1b.2  -  Fortify SSC deep fetch (runs when `type == "fortify"` present in `state.contextLinks[]`)
 
 URL pattern (caught by the extractor): `https://<prefs.global.hosts.fortify>/ssc/html/(ssc/)?version/<versionId>(/.*)?(#/version/<versionId>)?(/audit|/issues|/artifacts)?(\?issue=<issueId>)?` (plus the short-link variant `/ssc/html/ssc/version/<versionId>/fix/<issueInstanceId>`).
 
 - Host comes from `prefs.global.hosts.fortify` (collected during Token Save Flow Step 3.5). URL host must match, else warn and skip (protects against pasting another company's Fortify URL by accident).
-- Token resolution: `prefs.global.keychainMapping.fortify` → `~/.claude/lib/credential-store.sh get "<key>"` → API token. Auth header: `Authorization: FortifyToken <base64(token)>` (legacy tokens) or `Bearer <token>` (scoped tokens) — try Bearer first, fall back to FortifyToken on 401.
+- Token resolution: `prefs.global.keychainMapping.fortify` → `~/.claude/lib/credential-store.sh get "<key>"` → API token. Auth header: `Authorization: FortifyToken <base64(token)>` (legacy tokens) or `Bearer <token>` (scoped tokens)  -  try Bearer first, fall back to FortifyToken on 401.
 - Fetch finding detail (VPN required; respect `vpnServices.fortify`):
   - Version: `GET /ssc/api/v1/projectVersions/<versionId>` → name, project name, current issue count.
   - Issue list / single issue: if `issueInstanceId` in URL → `GET /ssc/api/v1/projectVersions/<versionId>/issues?q=issueInstanceId:"<id>"&fields=id,issueName,friority,fullFileName,lineNumber,analyzer,kingdom`. Otherwise fetch top open issue of the version.
@@ -185,11 +220,11 @@ URL pattern (caught by the extractor): `https://<prefs.global.hosts.fortify>/ssc
 - Phase 2 Planning injects `state.fortifyFinding` into the architectural-review prompt under a **Known Security Finding** section, and the generated task breakdown includes a task addressing the finding (naming convention: `sec(fortify-<issueId>): <issueName> at <file>:<line>`).
 - Soft-fail: 401 → re-run Token Save Flow for `fortify`; 403 → warn and skip; network timeout → respect VPN fallback (skip enrichment, mark `state.fortifyFinding = { skipped: "vpn-unreachable" }`).
 
-##### Step 1b.3 — Other link types (catalogued only at Phase 0; fetched at Phase 1)
+##### Step 1b.3  -  Other link types (catalogued only at Phase 0; fetched at Phase 1)
 
-For `swagger`, `confluence`, `figma`, `generic-doc` entries in `state.contextLinks[]`, no Phase 0 fetch runs. The entries pass through to Phase 1, which dispatches the matching fetcher (Block B work: `fetch-swagger.sh`, `fetch-confluence.sh`, etc.). Until those fetchers land, the entries are surfaced in Phase 1 context as "referenced but not fetched — agent should treat the URL as an authoritative external source and read it directly when relevant."
+For `swagger`, `confluence`, `figma`, `generic-doc` entries in `state.contextLinks[]`, no Phase 0 fetch runs. The entries pass through to Phase 1, which dispatches the matching fetcher (Block B work: `fetch-swagger.sh`, `fetch-confluence.sh`, etc.). Until those fetchers land, the entries are surfaced in Phase 1 context as "referenced but not fetched  -  agent should treat the URL as an authoritative external source and read it directly when relevant."
 
-**Jira project key addendum**: Support multi-tenant Jira — `prefs.projects[{project}].jiraProjectKeys[]` is already a list. When Step 1 extracts a Jira key from input, `upsert` it at the head (dedup, cap 10). Sibling keys for the same project (e.g. one key per team or tracker board) coexist; `prefs.global.defaultJiraKey` is the fallback for ambiguous free-text input only.
+**Jira project key addendum**: Support multi-tenant Jira  -  `prefs.projects[{project}].jiraProjectKeys[]` is already a list. When Step 1 extracts a Jira key from input, `upsert` it at the head (dedup, cap 10). Sibling keys for the same project (e.g. one key per team or tracker board) coexist; `prefs.global.defaultJiraKey` is the fallback for ambiguous free-text input only.
 
 **Log line shape** (progress contract):
 
@@ -198,25 +233,25 @@ For `swagger`, `confluence`, `figma`, `generic-doc` entries in `state.contextLin
 → URL deep fetch: crashlytics=<hit|miss|skipped>, fortify=<hit|miss|skipped>
 ```
 
-Two lines emit at the end of Step 1b. The first reports the catalogue from 1b.0 (always runs). The second reports the deep-fetch outcomes from 1b.1 / 1b.2 — `miss` = URL type not present in catalogue (normal), `skipped` = URL present but auth/VPN/mismatch skipped the fetch, `hit` = URL-derived context stored in state.
+Two lines emit at the end of Step 1b. The first reports the catalogue from 1b.0 (always runs). The second reports the deep-fetch outcomes from 1b.1 / 1b.2  -  `miss` = URL type not present in catalogue (normal), `skipped` = URL present but auth/VPN/mismatch skipped the fetch, `hit` = URL-derived context stored in state.
 
-#### Step 2 — Project Selection
+#### Step 2  -  Project Selection
 
 Scan `$HOME` (maxdepth 2) for project markers (`.xcodeproj`, `Package.swift`, `build.gradle`, `package.json`, `requirements.txt`, `go.mod`, `Cargo.toml`, `pom.xml`), excluding `DerivedData`, `node_modules`, `.build`, `Pods`, `.worktrees`, `build`, `.gradle`.
 
 **Skip if deterministic**: GitHub Issue URL → extract repo name → check `$HOME/{repo}` exists → auto-set.
 
-**Otherwise**: Present discovered projects as numbered list (standard UX pattern). Stack tag (`[iOS]`, `[Android]`, etc.) auto-detected from project files. Set `PROJECT_ROOT` to selected directory — all subsequent commands use `git -C $PROJECT_ROOT`. Save to `prefs.global.recentProjects` (dedup, max 10). If bare `#N` was given, now fetch GitHub issue from project's remote.
+**Otherwise**: Present discovered projects as numbered list (standard UX pattern). Stack tag (`[iOS]`, `[Android]`, etc.) auto-detected from project files. Set `PROJECT_ROOT` to selected directory  -  all subsequent commands use `git -C $PROJECT_ROOT`. Save to `prefs.global.recentProjects` (dedup, max 10). If bare `#N` was given, now fetch GitHub issue from project's remote.
 
 **v2.1.0+ Multi-Repo Mode** (gated by `prefs.global.settings.multiRepoEnabled`):
 
 - The picker accepts space-separated numbers (`1 3 4`) for multi-select.
 - `prefs.global.recentGroups[]` (set in setup.md Step 6) surfaces at the top: pressing the group's number selects all its repos in one keystroke.
 - Multi-select activates when ≥2 repos are chosen → populate `state.projects[]` array; the legacy scalar `state.project`/`projectRoot`/`worktreePath` fields mirror the **first** entry for backward-compat (single-repo phases that still read scalars don't break).
-- After selection, if the chosen set matches an existing `recentGroups` entry, bump `count` + `lastUsed`. If it's a new combination of ≥2 repos, prompt: `Save this combo as a multi-repo group? [y/N]` — on `y`, prepend to `recentGroups` (LRU cap 10).
+- After selection, if the chosen set matches an existing `recentGroups` entry, bump `count` + `lastUsed`. If it's a new combination of ≥2 repos, ask with a native `AskUserQuestion` picker (`question`: "Save this repo combo as a reusable multi-repo group?" in `outputLanguage`; `header`: "Save"; `options`: `{ label: "Save", ... }`, `{ label: "Skip", ... }`)  -  on **Save**, prepend to `recentGroups` (LRU cap 10).
 - Single-repo selection (1 repo) → legacy single-repo path; `state.projects[]` is omitted, scalars are populated as before.
 
-#### Step 3 — Remote Detection + Branch Selection
+#### Step 3  -  Remote Detection + Branch Selection
 
 1. **Check preferences first**: If `prefs.projects[{project}].remoteType` exists, use cached value.
 2. Read remote: `git -C $PROJECT_ROOT remote get-url origin`
@@ -244,7 +279,7 @@ Scan `$HOME` (maxdepth 2) for project markers (`.xcodeproj`, `Package.swift`, `b
 **TTL filter for recent branches**:
 
 - `prefs.global.recentBranches[{projectKey}][]` carries `{name, lastUsed}`. Filter to those whose `lastUsed` is within `settings.branchTtlDays` (default 15).
-- Stale entries (>TTL) are pruned in-place during the read — keeps the picker uncluttered without a separate cleanup pass.
+- Stale entries (>TTL) are pruned in-place during the read  -  keeps the picker uncluttered without a separate cleanup pass.
 - The filtered "Recent" list precedes the fresh `git branch -r` list; cap at 5 visible recent entries.
 
 **Fetch-fail handling** (replaces silent `git fetch origin` failure):
@@ -258,7 +293,7 @@ Likely causes: VPN closed, host unreachable, auth expired.
   [1] Connect VPN / fix network, then resume #{taskId}     (safest)
   [2] Use cached origin/{baseBranch} ref                    (stale risk: base sha {sha}, fetched {since})
   [3] Use local branch "{baseBranch}" as base               (only if local branch exists; commit {sha})
-  [4] Abort — no worktree, no branch, no state file
+  [4] Abort  -  no worktree, no branch, no state file
 
 Select:
 ```
@@ -269,11 +304,11 @@ Persist user choice in `agent-state.json.baseFetchStatus` ∈ `"fresh" | "cached
 ```
 Phase 6 (commit/push) MUST re-attempt `git fetch origin` before push; if successful, prompt to rebase before pushing.
 
-In multi-repo mode, the prompt fires per-repo. Choosing `[4] Abort` for any single repo aborts the entire task (atomic — no partial worktrees).
+In multi-repo mode, the prompt fires per-repo. Choosing `[4] Abort` for any single repo aborts the entire task (atomic  -  no partial worktrees).
 
-#### Step 4 — Branch Naming (automatic)
+#### Step 4  -  Branch Naming (automatic)
 
-Branch name is deterministic — no user confirmation needed.
+Branch name is deterministic  -  no user confirmation needed.
 
 **Type resolution** (first match wins):
 - Jira `Bug|Hotfix|Defect` → `bugfix`
@@ -295,7 +330,7 @@ Branch name is deterministic — no user confirmation needed.
 5. Truncate to 50 chars, then trim trailing partial word at the last `-`
 6. If empty after kebab (e.g. all-emoji title) → fall back to `task-{shortId}`
 
-**Collision handling** (automatic — no prompt):
+**Collision handling** (automatic  -  no prompt):
 - Probe local + remote for existing branch:
   ```bash
   LOCAL_HIT=$(git -C "$root" rev-parse --verify --quiet "refs/heads/$branch")
@@ -306,16 +341,16 @@ Branch name is deterministic — no user confirmation needed.
   `bugfix/ABC-12345` exists → `bugfix/ABC-12345-v2`
 - Log: `Branch collision: {branch} exists, using {branch}-v2`
 
-**Multi-Repo Mode** — branch name is **shared across all repos in the group**. Collision check runs per-repo; if any repo collides, the suffix applies to **all** repos (keeps cross-repo uniformity).
+**Multi-Repo Mode**  -  branch name is **shared across all repos in the group**. Collision check runs per-repo; if any repo collides, the suffix applies to **all** repos (keeps cross-repo uniformity).
 
-#### Step 5 — Instruction Files (optional)
+#### Step 5  -  Instruction Files (optional)
 
 1. Check `$PROJECT_ROOT/.instructions/` exists → scan for `SKILL.md` files
 2. If figmaUrl exists AND instructions include figma workflow → `instructionDriven: true`
 3. Map instruction files to `"instructionFiles": { "start": "...", "validate": "...", "dev": "...", "commit": "..." }`
 4. Instruction-driven → later phases read SKILL.md; no instructions → standard phases
 
-#### Step 6 — Branch + Workspace Setup
+#### Step 6  -  Branch + Workspace Setup
 
 **6a. Resolve git identity** (automatic, no prompt):
 
@@ -352,7 +387,7 @@ git -C $PROJECT_ROOT config user.email "{identity.email}"
 
 `worktreePath` = `$PROJECT_ROOT`, `localMode` = `true`.
 
-**If normal mode** (worktree — default): 2. Worktree path: Jira → `.worktrees/{jiraId}/`, GitHub → `.worktrees/GH{issueNo}/`, free-text → `.worktrees/task-{shortId}/` 3. `git -C $PROJECT_ROOT worktree add {path} -b {branch} origin/{baseBranch}` (if exists: enter, pull) 4. Set identity: `git -C {worktree-path} config user.name/email` 5. Create log dir + `agent-log.md` + `agent-state.json`:
+**If normal mode** (worktree  -  default): 2. Worktree path: Jira → `.worktrees/{jiraId}/`, GitHub → `.worktrees/GH{issueNo}/`, free-text → `.worktrees/task-{shortId}/` 3. `git -C $PROJECT_ROOT worktree add {path} -b {branch} origin/{baseBranch}` (if exists: enter, pull) 4. Set identity: `git -C {worktree-path} config user.name/email` 5. Create log dir + `agent-log.md` + `agent-state.json`:
 
 **v2.1.0+ Multi-Repo Worktree Setup**:
 
@@ -369,11 +404,11 @@ done
 
 State file in multi-repo mode:
 - Single shared `agent-state.json` lives at `$HOME/.claude/logs/multi-agent/{first-project}/{task-id}/agent-state.json` (anchored on the first repo for back-compat with `multi-agent log`/`status` commands)
-- `state.projects[]` holds per-repo `{name, root, worktreePath, branch, baseBranch, identity, platform, baseFetchStatus, commit, pr, pushAttempts, buildStatus}` — see `agent-state.schema.json`
+- `state.projects[]` holds per-repo `{name, root, worktreePath, branch, baseBranch, identity, platform, baseFetchStatus, commit, pr, pushAttempts, buildStatus}`  -  see `agent-state.schema.json`
 - Scalar fields (`project`, `projectRoot`, `worktreePath`, `branch`, `baseBranch`, `identity`) mirror `projects[0]` so legacy phases that read scalars keep working
 - Atomicity: if any repo's worktree creation fails (collision aborted, fetch aborted, disk full), roll back already-created worktrees: `git -C $proj worktree remove --force $WT_PATH; git -C $proj branch -D $BRANCH`. Never leave a partial multi-repo state.
 
-Single-repo mode (`projects.length === 1` or scalar-only) uses the legacy single-worktree path verbatim — no behavior change for existing tasks.
+Single-repo mode (`projects.length === 1` or scalar-only) uses the legacy single-worktree path verbatim  -  no behavior change for existing tasks.
 
 ```json
 {
@@ -394,11 +429,12 @@ Single-repo mode (`projects.length === 1` or scalar-only) uses the legacy single
   "localMode": false, "instructionDriven": true|false, "instructionFiles": {},
   "identity": {"name": "...", "email": "...", "keychainKey": "..."},
   "currentPhase": 0, "status": "in_progress", "startedAt": "{ISO}", "shortId": "#N",
+  "telemetry": { "mcpCalls": [] },
   "phases": { "0": {"status":"done","files":[]}, "1-7": {"status":"pending","files":[]} }
 }
 ```
 
-**Local-only flow** — when every entry in `state.projects[]` has `provider="local"`:
+**Local-only flow**  -  when every entry in `state.projects[]` has `provider="local"`:
 - `taskId` format: `LOCAL-{slug-of-freetext}-{yyyymmdd-HHMMSS}` (e.g. `LOCAL-purchase-flow-20260510-143200`). Slug = lowercase, non-alnum → `-`, trimmed, max 32 chars.
 - `state.offlineOnly = true` (Phases 6/7 read this flag).
 - `state.remoteType` per project = `"local"`.
@@ -407,9 +443,9 @@ Single-repo mode (`projects.length === 1` or scalar-only) uses the legacy single
 - No `gh`/`bb` API calls anywhere in Step 8. Worktree creation still applies if the user prefers worktree mode; collision handling stays the same.
 - Multi-repo + mixed mode: any project with `provider != "local"` keeps its normal remote workflow; the `offlineOnly` flag is set only when **all** projects are local.
 
-6. Log: "Phase 0: Init complete — {project} / {branch} / {identity.name}"
+6. Log: "Phase 0: Init complete  -  {project} / {branch} / {identity.name}"
 
-#### Step 7 — Task Type Detection (deterministic, sets the contract for downstream phases)
+#### Step 7  -  Task Type Detection (deterministic, sets the contract for downstream phases)
 
 Classify task _before_ Phase 1 so downstream phases branch on it. Persist to `agent-state.json.taskType`.
 
@@ -429,19 +465,19 @@ Persist: `"taskType": "component" | "bugfix" | "feature" | "refactor" | "chore"`
 
 | Phase   | Behavior change                                                                                          |
 | ------- | -------------------------------------------------------------------------------------------------------- |
-| Phase 3 | `component` → delegate to `pipeline/skills/figma-ios/figma-to-component` (orchestrator runs 3.0–3.8 internally); else standard TDD |
+| Phase 3 | `component` → delegate to `pipeline/skills/figma-ios/figma-to-component` (orchestrator runs 3.0-3.8 internally); else standard TDD |
 | Phase 4 | `bugfix` → test coverage; `component` → accessibility+tokens; `refactor` → behavior preservation         |
 | Phase 6 | `bugfix`/`hotfix` → `fix(...)` prefix; `feature`/`component` → `feat(...)`; `refactor` → `refactor(...)` |
 | Phase 7 | `component` → includes SubPhase breakdown                                                                |
 
 Log: `Phase 0 Step 7: taskType = {component|bugfix|feature|refactor|chore}`
 
-#### Step 8 — Clarification (opt-in, runs AFTER maturity, BEFORE Phase 1)
+#### Step 8  -  Clarification (opt-in, runs AFTER maturity, BEFORE Phase 1)
 
 **Gated by `prefs.global.clarifyAmbiguous.enabled`** (default: `false`). When enabled and `state.maturity.status != "blocker"`:
 
 1. Dispatch `agents/task-clarifier.md` (Haiku by default) with the task title + body + acceptance + maturity warnings already on `agent-state`.
-2. The agent returns JSON conforming to `pipeline/schemas/clarify-output.schema.json` — `clarityScore` (0-10), `questions[]`, `stopAndAsk`.
+2. The agent returns JSON conforming to `pipeline/schemas/clarify-output.schema.json`  -  `clarityScore` (0-10), `questions[]`, `stopAndAsk`.
 3. If `clarityScore >= prefs.clarifyAmbiguous.minScoreToProceed` (default 6) or `stopAndAsk == false` → write `state.clarification` (score + rationale, no questions), proceed to Phase 1 silently.
 4. If `stopAndAsk == true`:
 
@@ -451,16 +487,16 @@ Log: `Phase 0 Step 7: taskType = {component|bugfix|feature|refactor|chore}`
      | Mode  | Behavior |
      |---|---|
      | `skip`  | Discard questions, proceed to Phase 1 with no extra context. Logs `clarify.skipped` |
-     | `log`   | Append questions to `agent-log.md` for human review, proceed. Default — keeps the signal |
+     | `log`   | Append questions to `agent-log.md` for human review, proceed. Default  -  keeps the signal |
      | `abort` | Pause Phase 0 (`state.status = "clarify-pending"`); user resumes via `multi-agent:resume #N`. Then Step 8 re-dispatches AskUserQuestion |
 
-5. Phase 1 Analysis reads `state.clarification.userAnswers` (when present) as additional context — fold answers into the Explore prompt so downstream phases inherit the resolution.
+5. Phase 1 Analysis reads `state.clarification.userAnswers` (when present) as additional context  -  fold answers into the Explore prompt so downstream phases inherit the resolution.
 
-**Cost:** ~$0.0025 per Haiku call. The pipeline's other expensive phases (Phase 4 reviewers, Phase 3 Sonnet codegen) far outweigh this — the value is avoiding the ~30 min wasted when Phase 3 builds the wrong thing because Phase 0 didn't ask.
+**Cost:** ~$0.0025 per Haiku call. The pipeline's other expensive phases (Phase 4 reviewers, Phase 3 Sonnet codegen) far outweigh this  -  the value is avoiding the ~30 min wasted when Phase 3 builds the wrong thing because Phase 0 didn't ask.
 
 **Reference:** see `pipeline/agents/task-clarifier.md` for the full scoring rubric, question quality rules, and prior-art citations (Devin Knowledge / Cursor Plan Mode).
 
-**Why this fits Phase 0 (not a new phase):** clarification doesn't change what code gets written — it changes what gets understood before code is written. Phase 0 already collects identity / project / branch / maturity; ambiguity scoring fits naturally as the last contextual gate.
+**Why this fits Phase 0 (not a new phase):** clarification doesn't change what code gets written  -  it changes what gets understood before code is written. Phase 0 already collects identity / project / branch / maturity; ambiguity scoring fits naturally as the last contextual gate.
 
 #### Telemetry
 

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

@@ -1,24 +1,24 @@
-### Phase 1: Analysis (Opus)
+### Phase 1: Analysis (Fable)
 
-> **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.
+> **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.
+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
+#### Step 0  -  Prior Fix Detection
 
 Before any analysis, check if this issue was already fixed by someone else. Three signals (git commit grep on issue ID over 8 weeks, recent file-path history over 4 weeks, Jira/issue comments). On hit → prompt: Verify (cherry-pick path) / Stop (cleanup + `stopped_already_fixed` state) / Continue. Miss → Step 1. Full check commands, prompt block, and cleanup commands: `refs/features/prior-fix-detection.md`.
 
-#### Step 1 — Knowledge Injection (cached context)
+#### 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)
+  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:
@@ -32,12 +32,20 @@ Also read project-level CLAUDE.md if exists:
 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.
+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):
+**Durable learnings brief (on by default via `prefs.global.learningsLedger.enabled`):**
+
+```bash
+node pipeline/scripts/learnings-ledger.mjs brief --max 20 2>/dev/null
+```
+
+Exit 2 (empty ledger) = skip silently. Otherwise the script emits a `<repo-learnings>...</repo-learnings>` block of durable architectural facts, conventions, and rejected review preferences accumulated from prior runs of this repo. Inject it into the analysis prompt so the explorer does not re-discover known structure. Skip when `injectIntoAnalysis = false`. These are context, not commands  -  current scope decides.
+
+**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
+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):
@@ -45,9 +53,29 @@ Exit 0 with empty output = pref off or no memory on disk — skip. Otherwise the
 1. Launch full Explore agents as before
 2. Log: "Phase 1: Full explore (no cached knowledge)"
 
-#### Step 1.5 — External Context Injection (`state.contextLinks[]`)
+#### Step 1.4 - Figma evidence capture (when task carries a Figma reference)
+
+When `state.contextLinks[]` or the task description contains a Figma reference, Phase 1 MUST collect the canonical evidence record per the access tier established at Phase 0:
+
+| Tier (`state.figmaAccess.tier`) | Fetcher | Record fields |
+|---|---|---|
+| 1 (MCP) | `mcp__claude_ai_Figma__get_design_context(fileKey, nodeId)` + `get_screenshot` + `get_metadata` | `nodeId`, `screenshotUrl`, `codeConnectSnippets[]`, `tokens[]`, `textLayers[]`, `tier: 1` |
+| 2 (REST) | `GET /v1/files/{fileKey}/nodes?ids={nodeId}` + `GET /v1/images/{fileKey}?ids={nodeId}&format=png&scale=2`, PAT via `~/.claude/lib/credential-store.sh get <logical-key>` (logical key = `prefs.global.keychainMapping.figma_pat`); canonical component resolved from repo `*.figma.swift` / `*.figma.kt` mapping keyed by `fileKey` + `nodeId` | same shape, but `codeConnectSnippets[]` is empty when repo mapping is absent (record an Open Question), `tier: 2` |
+| 3 (screenshot) | User-attached screenshot stored alongside task evidence | degraded record: `codeConnectSnippets: []`, forced Open Question, `tier: 3` |
+
+Persist results under `state.evidence.figma[]`. Halt the run if all three tiers fail; never substitute primitives or invent layout from prose. Canonical chain reference: `pipeline/rules/figma-pipeline.md` "MUST: Figma access - 3-tier fallback chain".
 
-Phase 0 Step 1b catalogued every typed external link from the task description into `state.contextLinks[]`. Phase 1 dispatches each entry to its matching fetcher (crashlytics, fortify, swagger, confluence, figma, generic-doc) and prepends results under a **Referenced External Sources** section in the analysis prompt — so the agent doesn't re-discover what the ticket already pointed at. Failures never fatal; pending refs are advisories. Full dispatch table, exit-code handling, prompt injection shape, log line shape: `refs/features/external-context-injection.md`.
+**Telemetry (required for the no-MCP gate):** Tier 1 uses `mcp__claude_ai_Figma__*` tools. Every such MCP invocation MUST append an entry to `state.telemetry.mcpCalls[]` as `{ "tool": "<full mcp tool name>", "phase": 1, "timestamp": "<ISO-8601>" }`. This is the only phase permitted to record `phase: 1` (or `0`) entries; `smoke-no-mcp-in-dev-phases.sh` fails the run if any entry carries `phase >= 2`. Recording is what makes that BLOCKING contract enforceable  -  an MCP call left unrecorded defeats the gate, so record every one.
+
+Progress lines:
+
+```
+→ figma evidence: <N> frames captured (tier=<n>, code-connect=<M>, open-questions=<K>)
+```
+
+#### 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 dispatches each entry to its matching fetcher (crashlytics, fortify, swagger, confluence, figma, generic-doc) and prepends results under a **Referenced External Sources** section in the analysis prompt  -  so the agent doesn't re-discover what the ticket already pointed at. Failures never fatal; pending refs are advisories. Full dispatch table, exit-code handling, prompt injection shape, log line shape: `refs/features/external-context-injection.md`.
 
 **Log line shape** (progress contract):
 
@@ -55,7 +83,7 @@ Phase 0 Step 1b catalogued every typed external link from the task description i
 → context injection: total=<N>, fetched=<n>, pending=<n>, by-type={swagger:F/P, confluence:F/P, ...}
 ```
 
-#### Step 2 — Stack Detection
+#### 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:
 
@@ -77,11 +105,11 @@ This informs:
 - 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)
+#### Step 2.5  -  Repo Map Injection (advisory, opt-in)
 
 Gated by `prefs.global.repoMap.enabled` (default: `false`). When enabled, runs `pipeline/scripts/repo-map.mjs` and injects the budgeted result into each Explore prompt as `${REPO_MAP}`. Aider-style: deterministic, no embeddings, sub-second, advisory only. Full wiring (helper invocation, properties, when-to-enable): `refs/features/repo-map.md`.
 
-#### Step 3 — Codebase Exploration
+#### Step 3  -  Codebase Exploration
 
 Launch parallel Explore agents to scan codebase:
 
@@ -96,21 +124,24 @@ Use `subagent_type: "Explore"` with thoroughness based on knowledge availability
 
 #### 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.
+Phase 1 produces an object conforming to `pipeline/schemas/analysis-output.schema.json` and persists it to `state.analysis`. Required fields (exact names per the schema): `stack` (detected stack identifier + primary language), `touchedAreas[]` (path + why), `risks[]` (existing-code hazards/observations the planner must respect  -  each `{risk, severity, mitigation}`; use an empty array when none), `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:
+**Required: validator gate (deterministic)  -  run on the persisted file immediately after the analysis object is produced; the validator's exit code decides, not the LLM turn:**
 
 ```bash
-echo "$ANALYSIS_JSON" | node pipeline/scripts/validate-analysis.mjs -
+ANALYSIS_FILE="$WORKTREE/.pipeline/analysis.json"
+mkdir -p "$(dirname "$ANALYSIS_FILE")"
+printf '%s' "$ANALYSIS_JSON" > "$ANALYSIS_FILE"
+node $HOME/.claude/scripts/validate-analysis.mjs "$ANALYSIS_FILE"
 ```
 
-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`.
+Progress line: `    → checking validator validate-analysis`
+
+Non-zero exit fails CLOSED: emit the validator stderr + `errors[]` verbatim, attempt ONE self-correction rework (re-invoke the explorer with the errors quoted, overwrite `$ANALYSIS_FILE`), re-run the validator. If it fails again -> HALT the phase with recovery hint: `ERR: analysis output failed validate-analysis.mjs twice. Inspect $ANALYSIS_FILE against pipeline/schemas/analysis-output.schema.json, then resume with /multi-agent:resume #N.` Record `agent-state.phases["1"].validator` (`pass` | `pass-after-rework` | `halted`).
 
-Log: "Phase 1: Analysis — stack:{detectedStack} | {N} files identified, {summary}"
+Log: "Phase 1: Analysis  -  stack:{detectedStack} | {N} files identified, {summary}"
 
-#### Telemetry — token forwarding
+#### Telemetry  -  token forwarding
 
 Forward the explorer/Opus call's token totals into the tracker so Phase 7's Cost Breakdown captures Phase 1:
 
@@ -130,11 +161,11 @@ 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.
+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
+## Token telemetry  -  invoke after every LLM call
 
 After every LLM call in this phase (analysis, plan generation, code/diff write, review verdict, triage), invoke:
 
@@ -144,4 +175,4 @@ 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.
+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.