@mmerterden/multi-agent-pipeline 17.6.0 → 19.0.0

package/pipeline/skills/shared/core/multi-agent-sync/SKILL.md

@@ -32,8 +32,8 @@ Run all steps automatically:
 ```
 Step 0: DOCTOR      node $HOME/.claude/scripts/doctor.mjs  -  exit 2 or 4 STOPS the sync
 Step 1: DETECT      Compare timestamps, find stale targets
-Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 56 sub-command skills)
-Step 2b: CODEX      Claude Code -> Codex CLI (1 router skill + 56 specs as refs + 8 agent TOML)
+Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 60 sub-command skills)
+Step 2b: CODEX      Claude Code -> Codex CLI (1 router skill + 60 specs as refs + 8 agent TOML)
 Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scrub)
 Step 3d: DEV-TOOLKIT Companion MCP server -> detect movement, ship gates, commit + publish
 Step 4: WEBSITE     Version + phase/model counts -> {website-host} (i18n + projects.ts)
@@ -228,16 +228,17 @@ When invoked with the `release` argument:
 |-------------|-------------|
 | `~/.claude/commands/multi-agent/{cmd}/SKILL.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
 
-**56 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
+**60 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
 ```
 analysis, analysis-jira, analysis-resolve, autopilot, autopilot-off,
 autopilot-on, autopilot-status, build-optimize, channels, complaint-analysis,
 create-jira, design-check, diff-explain, doctor, feedback, forget,
 garbage-collect, graph, help, ios-coding-standard, issue, jira, kill,
-language, local, local-autopilot, log, manual-test, prune-logs,
+language, local, local-autopilot, log, manual-test, model, prune-logs,
 prune-prompts, purge, refactor, resume, resume-local, review,
-review-analysis, review-issue, review-jira, routines, save, scan, search,
+review-analysis, review-issue, review-jira, route-off, route-on,
+route-status, routines, save, scan, search,
 setup, stack, status, steer, store-ready, sync, test, test-accessibility,
 test-dark-mode, test-dynamic-type, test-screenshots, testflight-validation,
 uninstall, update

package/pipeline/skills/shared/external/macos-spm-app-packaging/assets/templates/package_app.sh

@@ -19,7 +19,10 @@ else
   BUILD_NUMBER=${BUILD_NUMBER:-1}
 fi
 
-ARCH_LIST=( ${ARCHES:-} )
+# read -ra, not ( $ARCHES ): a bare expansion into an array splits on IFS and
+# then GLOBS each word, so an ARCHES carrying a * builds for whatever files are
+# in the working directory.
+read -ra ARCH_LIST <<< "${ARCHES:-}"
 if [[ ${#ARCH_LIST[@]} -eq 0 ]]; then
   HOST_ARCH=$(uname -m)
   ARCH_LIST=("$HOST_ARCH")

package/pipeline/skills/shared/external/macos-spm-app-packaging/assets/templates/setup_dev_signing.sh

@@ -15,7 +15,10 @@ fi
 echo "Creating self-signed certificate '$CERT_NAME'..."
 
 TEMP_CONFIG=$(mktemp)
-trap "rm -f $TEMP_CONFIG" EXIT
+# Single-quoted on purpose: the path is read when the trap FIRES, not when it is
+# installed. Double quotes bake in whatever the variable held at install time,
+# which is a template users copy into scripts where the order differs.
+trap 'rm -f "$TEMP_CONFIG"' EXIT
 
 cat > "$TEMP_CONFIG" <<EOFCONF
 [ req ]

package/pipeline/skills/shared/external/macos-spm-app-packaging/assets/templates/sign-and-notarize.sh

@@ -17,7 +17,8 @@ echo "$APP_STORE_CONNECT_API_KEY_P8" | sed 's/\\n/\n/g' > /tmp/app-store-connect
 trap 'rm -f /tmp/app-store-connect-key.p8 /tmp/${APP_NAME}Notarize.zip' EXIT
 
 ARCHES_VALUE=${ARCHES:-"arm64 x86_64"}
-ARCH_LIST=( ${ARCHES_VALUE} )
+# See package_app.sh: a bare expansion into an array globs as well as splits.
+read -ra ARCH_LIST <<< "${ARCHES_VALUE}"
 for ARCH in "${ARCH_LIST[@]}"; do
   swift build -c release --arch "$ARCH"
 done

package/pipeline/skills/skills-index.md

@@ -3,7 +3,7 @@
 > Auto-generated by `pipeline/scripts/build-skills-index.mjs`  -  do not hand-edit.
 > Regenerate with `node pipeline/scripts/build-skills-index.mjs`.
 
-**207 skills** across 2 groups.
+**216 skills** across 2 groups.
 
 | Group | Name | Platform | Description |
 |-------|------|----------|-------------|
@@ -94,14 +94,19 @@
 | external | `monorepo-architect` |  -  | Expert in monorepo architecture, build systems, and dependency management at scale. Masters Nx, Turborepo, Bazel, and Lerna for efficient mu |
 | core | `multi-agent` |  -  | Task orchestrator: runs the full pipeline from a Jira ID or GitHub Issue URL  -  analysis → plan → TDD development → parallel review (Fable  |
 | core | `multi-agent-analysis` |  -  | Standalone feature-spec analysis. Two profiles picked at intake: global (23-section development handoff, 8 of them in Lite mode) or corporat |
+| core | `multi-agent-analysis-jira` |  -  | Turn a rendered analysis document into a Jira story tree: derive stories from the document's own rule ids, check coverage both ways, preview |
 | core | `multi-agent-analysis-resolve` |  -  | Resolve the Section 20 Risks and Open Questions of an analysis v3 document one row at a time: up to 3 source-labeled answer candidates per r |
 | core | `multi-agent-autopilot` |  -  | Launch any task in autopilot mode: skips every confirmation, runs end-to-end autonomously. Use when a task should run end to end with no con |
+| core | `multi-agent-autopilot-off` |  -  | Turn off continuous mode on this machine: the schedule is removed, work already running finishes, the repo selection is kept. Use when the m |
+| core | `multi-agent-autopilot-on` |  -  | Turn on continuous mode on THIS machine: pick the repos it watches; labelled GitHub issues and assigned+labelled Jira items then run in a wo |
+| core | `multi-agent-autopilot-status` |  -  | Show what continuous mode is doing here: what runs at which phase, what is queued, what waits for an answer, what PRs it opened today. Use w |
 | core | `multi-agent-build-optimize` |  -  | Wrapper that dispatches to xcode-build-orchestrator on iOS repos. Benchmarks the current Xcode build, runs compilation / project / SPM analy |
 | core | `multi-agent-channels` |  -  | Multi-channel reporter  -  Jira/Confluence/Wiki/PR description. Multi-select channels + content, humanizer pass, reviewer-preserving Bitbuck |
 | core | `multi-agent-complaint-analysis` |  -  | Customer-complaint triage. Ingests complaints (paste, csv/xlsx/txt/json file, Jira issue, Confluence URL), fetches Graylog evidence per trx/ |
 | core | `multi-agent-create-jira` |  -  | Create a standards-compliant Jira issue (Task / Bug / Story): asks the type, mines project conventions, drafts from a standard template with |
 | core | `multi-agent-design-check` |  -  | Mock-mode vs Figma design audit (iOS / Android, local-only). Pick repo + module, gate on mock support, enumerate every state driver into a c |
-| core | `multi-agent-diff-explain` |  -  | Map Phase 4 triage findings to branch diff lines. Read-only post-hoc command, used after review to answer 'which finding lines up with which |
+| core | `multi-agent-diff-explain` |  -  | Map Phase 3 triage findings to branch diff lines. Read-only post-hoc command, used after review to answer 'which finding lines up with which |
+| core | `multi-agent-doctor` |  -  | Health check for the installed pipeline: layout, preferences, credentials, hooks and host capabilities, each with one actionable step. Exit  |
 | core | `multi-agent-feedback` |  -  | Send one message to the maintainer: a bug, an idea or a question. Only the text you type is sent - no logs, no repo names, no paths. Shows t |
 | core | `multi-agent-forget` |  -  | Remove a saved /multi-agent routine (created by /multi-agent:save): deletes its local-only command and its registry entry. Asks which one an |
 | core | `multi-agent-garbage-collect` |  -  | Sweep leftover /tmp scratch (picker state, review diffs, channel payloads, analysis drafts) from past runs. Dry-run first; confirms before d |
@@ -113,19 +118,23 @@
 | core | `multi-agent-kill` |  -  | Stop the given task, then remove its worktree and branch. Asks for confirmation. Use when a running or stuck task should be stopped and its  |
 | core | `multi-agent-language` |  -  | Toggle outputLanguage (assistant explanations, picker questions, PR/Jira/Confluence bodies). promptLanguage is fixed to English; commit mess |
 | core | `multi-agent-local` |  -  | Full pipeline in local mode  -  no worktree, runs directly on the current branch. Use when the full pipeline should run on the current branc |
-| core | `multi-agent-local-autopilot` |  -  | Full pipeline + local + autopilot  -  no worktree, no confirmations, all 8 phases run end-to-end on the current branch. Use when the full pi |
+| core | `multi-agent-local-autopilot` |  -  | Full pipeline + local + autopilot  -  no worktree, no confirmations, all 6 phases run end-to-end on the current branch. Use when the full pi |
 | core | `multi-agent-log` |  -  | Show the agent-log.md for the given task. With no ID, shows the most recent task. Use when asked what a task did, or to read its log. |
 | core | `multi-agent-manual-test` |  -  | Switch to the active task's branch and prepare it for manual testing in Xcode. Phase 5 standalone (the UI Bug Hunter lives at multi-agent-te |
+| core | `multi-agent-model` |  -  | Turn the top model rung on or off and keep the cost ledger's pricing in step with it. Use when asked to enable or disable Fable, or which mo |
 | core | `multi-agent-prune-logs` |  -  | Delete per-task project logs under ~/.claude/logs/multi-agent (filter by age/project/task). Audit trail + metrics are preserved. Dry-run fir |
 | core | `multi-agent-prune-prompts` |  -  | Zero-base prompt review: measure the always-on instruction footprint, classify every rule block, propose keep/trial-removal/delete; applies  |
 | core | `multi-agent-purge` |  -  | ⚠️ Wipes every worktree, branch, log, and state file. Irreversible; asks for double confirmation. Use when every worktree, branch, log and s |
 | core | `multi-agent-refactor` |  -  | Analyse the project: extract adapted best-practices, hunt real bugs + improvement areas, check upstream drift of derived skills, research th |
 | core | `multi-agent-resume` |  -  | Resume a stopped or failed task from the phase where it left off. Use when a task stopped or failed and should carry on from where it left o |
-| core | `multi-agent-resume-local` |  -  | Continue already-done LOCAL work through the pipeline tail: Review → Build+Test → Commit/PR → Report (technical analysis + Jira test-scenari |
+| core | `multi-agent-resume-local` |  -  | Continue already-done LOCAL work through the pipeline tail: Review (with its build gate) → Commit/PR → Report (technical analysis + Jira tes |
 | core | `multi-agent-review` |  -  | Run parallel review on a branch diff or a Pull Request: 3 models on Claude Code (Fable + Opus + Sonnet), 3 models on Copilot CLI (GPT + Opus |
 | core | `multi-agent-review-analysis` |  -  | Review a written analysis document instead of a diff: resolve it from a path, a Confluence page or a Jira issue, run the deterministic gates |
 | core | `multi-agent-review-issue` |  -  | Assess whether a GitHub issue is ready for multi-agent development: fetch it, grade scope / acceptance criteria / repro / design / API / sta |
 | core | `multi-agent-review-jira` |  -  | Assess whether a Jira issue is ready for multi-agent development: fetch it, grade scope / acceptance criteria / repro / design / API / stack |
+| core | `multi-agent-route-off` |  -  | Disable model routing and keep its rules, so turning it back on does not re-ask for the same configuration. Use when asked to turn model rou |
+| core | `multi-agent-route-on` |  -  | Enable policy-driven model routing: pick a strategy, a scope, and the rules that say which rung a call lands on. Use when asked to turn mode |
+| core | `multi-agent-route-status` |  -  | Report model routing: whether it is armed, which rule applies where, which rung the last dispatches took, and what this run has cost. Use wh |
 | core | `multi-agent-routines` |  -  | List your saved /multi-agent routines (from /multi-agent:save) with what each one does, rendered in outputLanguage. Use when asked which sav |
 | core | `multi-agent-save` |  -  | Save a recurring job as a reusable /multi-agent:<name> command. Reviews the conversation + your CLAUDE.md for candidate routines, you pick o |
 | core | `multi-agent-scan` |  -  | Skill security scan: walks local skill directories against a tiered pattern catalog. Use when local skill directories need checking for unsa |

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

@@ -1,263 +0,0 @@
-### Phase 1: Analysis (Sonnet)
-
-> **TLDR**  -  Sonnet-driven codebase exploration: the `explorer` persona declares `preferredModel: sonnet` (haiku when the fallback ladder engages). 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 `$HOME/.claude/multi-agent-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. 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: `$HOME/.claude/multi-agent-refs/features/prior-fix-detection.md`.
-
-#### 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 $HOME/.claude/scripts/memory-load.sh "$PROJECT_ROOT" "$TASK_TITLE $TASK_DESCRIPTION"
-```
-
-Exit 0 with empty output = pref off or no memory on disk  -  skip. Otherwise the script emits a `<repo-memory path="...">...</repo-memory>` block of MEMORY.md pointers suitable for direct injection into the analysis prompt. Passing the task text ranks the pointers against it instead of printing the first thirty; individual memory files are read on-demand when a pointer looks relevant.
-
-**Durable knowledge (on by default via `prefs.global.learningsLedger.enabled`):** two blocks, and where each goes is part of the contract  -  see `$HOME/.claude/multi-agent-refs/prompt-assembly.md`.
-
-```bash
-# HEAD of the prompt: task-independent, byte-stable, so it caches.
-node $HOME/.claude/scripts/learnings-ledger.mjs profile 2>/dev/null
-# END of the prompt, after the task text: ranked against this task.
-node $HOME/.claude/scripts/learnings-ledger.mjs brief --max "${prefs_learningsLedger_maxBriefEntries:-20}" \
-  --task "$TASK_TITLE $TASK_DESCRIPTION" 2>/dev/null
-```
-
-Exit 2 (empty ledger) = skip silently. Lines end with an `L:<id>` pointer; `show --id L:<id>` returns the full entry. Skip both when `injectIntoAnalysis = false`. Context, not commands  -  current scope decides. Then log the injection so recall quality stays measurable:
-
-```bash
-bash $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 1 memory.injected \
-  kind=<profile|task-relevant> rows=$N chars=$C
-```
-
-**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.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. **Phase 0 Step 0.5 already resolved the tier** and the credential - read `state.figmaAccess.tier` and fetch with that tier's tool set; do not re-probe. Chain, tiers and halt conditions: `$HOME/.claude/multi-agent-refs/rules.md` "Figma Access Tier".
-
-What Phase 1 owns is the record. Every frame gets one entry in `state.evidence.figma[]`:
-
-| Field | Tier 1 (MCP) | Tier 2 (REST) | Tier 3 (screenshot) |
-|---|---|---|---|
-| `nodeId`, `screenshotUrl`, `tokens[]`, `textLayers[]` | required | required | required |
-| `codeConnectSnippets[]` | from `CodeConnectSnippet` blocks | from repo `*.figma.swift` / `*.figma.kt` keyed on `fileKey`+`nodeId`; empty -> Open Question | always `[]` -> forced Open Question |
-| `tier` | `1` | `2` | `3` |
-
-Halt if all three tiers fail; never substitute primitives or invent layout from prose.
-
-**Spacing goes in by token NAME, per atom  -  never a pixel number.** `tokens[]` must
-carry each frame's spacing/padding as Figma names them (`Spacing/12`, edge `4`), keyed
-to the atom. Phase 3 cannot call Figma, so what is missed here is gone: one run guessed
-`16` where the frame said `Spacing/12` and the sheet was rebuilt. A pixel number also
-cannot map back to a token. No spacing entries on a UI frame is a **capture failure**,
-not an empty frame  -  Open Question and halt. Canonical chain reference: `$HOME/.claude/rules/figma-pipeline.md` "MUST: Figma access - 3-tier fallback chain".
-
-**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.45  -  Reuse discovery (BLOCKING for new services, entities, mappers)
-
-Before proposing any new service call, entity or mapper, search for what already
-covers it. Record hits under `state.reuse[]` and cite them in the doc; proposing new
-code over a hit needs a one-line reason.
-
-Search for: a **wrapper** over the same endpoint (especially one supplying parameters
-the generated call leaves optional); an **entity** for the same concept (module's
-shared entities first, then siblings); a **mapper** over the same response; a **screen**
-doing the same interaction.
-
-Why blocking: one run proposed a new repository over an endpoint a sibling already
-wrapped **with its country parameter**, called the generated method without it, and
-re-invented an entity the module had. Half that branch's commits went to converging
-back. "Copy X and rename it" is the reuse answer, not a hint  -  name X's files.
-
-#### 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, graylog, 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. `state.graylogContext` (advisory) and `state.relatedIssues[]` (sibling issues) are injected there too. Failures never fatal (a non-zero fetcher exit is marked skipped and the analysis still runs, exactly as for crashlytics); pending refs are advisories. Full dispatch table, exit-code handling, prompt injection shape, log line shape: `$HOME/.claude/multi-agent-refs/features/external-context-injection.md`.
-
-**Log line shape** (progress contract):
-
-```
-→ context injection: total=<N>, fetched=<n>, pending=<n>, by-type={swagger:F/P, confluence:F/P, ...}
-```
-
-#### Step 2  -  Stack Detection
-
-Two questions shared one answer here, and the shared answer was wrong on both.
-
-**What the repo is BUILT WITH** - one owner, no marker list in this file:
-
-```bash
-eval "$(bash $HOME/.claude/lib/stack-detect.sh "$PROJECT_ROOT")"
-```
-
-Persist `MA_STACKS` as `state.stacks[]` (a subset of `ios android web backend`,
-always in that order) and `MA_STACK_WHY` as `state.stackWhy`. Empty is a real
-answer meaning no marker matched; `stackWhy` separates that from a directory that
-could not be read, and a caller that cannot tell those apart treats an unreadable
-repo as a language-free one. `state.stacks[]` routes toolkits, through
-`pluginsForStacks()` in `$HOME/.claude/scripts/_stack-routing.mjs`. Do not derive
-plugin names here.
-
-The table that used to live here scanned at depth 2, and `AndroidManifest.xml`
-sits at `<module>/src/main/` - depth 4 in every multi-module app - so **Android
-was never detected**. The owner goes to depth 5 for that one file, prunes
-submodules (a vendored checkout ships its own `Package.swift`, which reported a
-Compose app as iOS) and checks the root first so traversal order cannot decide.
-
-**What the code is WRITTEN IN** - a different axis with its own field.
-`state.detectedStack[]` stays the language answer (`ios`, `python`, `node`, `go`,
-`docker`, `monorepo`): `graph-build.mjs --stack` takes `ios|android|node|python|go`
-and has no notion of `web` or `backend`. Folding the two together is what made a
-Gradle-built JVM service read as an Android app.
-
-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`). When enabled, runs `$HOME/.claude/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): `$HOME/.claude/multi-agent-refs/features/repo-map.md`.
-
-#### Step 2.6  -  Code Graph Injection (advisory, opt-in)
-
-Gated by `prefs.global.codeGraph.enabled` (default: `false`). With a rule file for `detectedStack`, Phase 1 refreshes the graph and queries it; `graph-affected` feeds `analysis.touchedAreas[]`. Zero API cost, read-only. Commands and measurements: `$HOME/.claude/multi-agent-refs/features/code-graph.md`.
-
-**A valid result REPLACES the opening sweep** rather than sitting beside it: Explore starts from those files and walks outward, with no broad `Glob`/`Grep` pass first - running both pays twice, and the second re-derives what the graph said. No graph (missing rule, stale, or disabled) leaves the previous behaviour untouched; a task naming a symbol or path is still grepped directly.
-
-#### 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 scaled to task size AND knowledge availability (first match wins):
-
-- A fresh code graph answered the task's query with a ranked file set (Step 2.6) → "light" (the starting set is already narrowed; explore outward from it, do not re-scan)
-- `taskType` is `bugfix`/`chore` AND scope is small (single named file, or a referenced crash/stack frame that pinpoints the site) → "light" (cheapest  -  scan only the named area + its direct callers)
-- Knowledge exists → "medium" (targeted, cheaper)
-- No knowledge, or `taskType` is `feature`/`refactor`/`component` → "very thorough" (full scan, first-time investment)
-
-The light tier keeps a one-line bug fix from triggering a full-repo scan; pairing it with the deterministic `taskType` (Phase 0 Step 7) prevents the cheap path from firing on feature work.
-
-**Dispatch resilience (required).** Explore agents run in parallel and the analyst synthesis waits on them, so a single stalled agent hangs the phase. Bound each Explore dispatch by a wall-clock budget (`EXPLORE_TIMEOUT_SECONDS`, default 180). If an agent has not returned by the budget: log `explore.timeout agent=<id>`, drop that agent's slice, and synthesize from the agents that did return. Proceed as long as at least one Explore agent returned; if zero returned, retry the cheapest single Explore once, then HALT with `ERR: no Explore agent returned within ${EXPLORE_TIMEOUT_SECONDS}s; resume with /multi-agent:resume #N.`. Never block indefinitely on a slow or dead dispatch.
-
-#### Step 4  -  Analysis document (the design contract Phase 2 and Phase 3 demand)
-
-Phase 2 and Phase 3 pre-flights BLOCK on `analysis/<feature-slug>-<platform>.md`. **This step produces it.**
-
-**When it runs.** From signals Phase 0 already computed:
-
-| `taskType` | Figma reference in `state.contextLinks[]` | Document |
-|---|---|---|
-| `feature` · `refactor` · `component` | any | **produced** |
-| `bugfix` · `chore` | present | **produced** |
-| `bugfix` · `chore` | absent | **skipped** - record `state.analysis.docStatus = "not-applicable"` |
-
-`analysisPhase.forceFull` (default `false`) overrides the skip row, for a small change that must still leave a spec behind. `analysisPhase.mode` sets depth: `auto` is Lite on the skip-row shape and Full otherwise; `full` / `lite` pin it.
-
-A fresh document is also skipped when one already exists for this feature and platform AND its front-matter `evidence_digest` still matches (Locked 27 cache); record `docStatus = "reused"`.
-
-**How it runs.** Load `$HOME/.claude/multi-agent-refs/analysis/` on demand, in order: `locked.md` (the 31 binding decisions) then `evidence.md`, `synthesis.md`, `render.md`. Intake is NOT re-asked; platform, repos and account come from Phase 0 state. Autopilot auto-approves the Phase 2a convention preview and writes the local file, because it may not ask.
-
-**Where it lands.** `<worktree>/analysis/<feature-slug>-<platform>.md`, one file per platform in `state.analysisSpec.platforms[]`. Persist the paths to `state.analysis.docPath[]` and set `docStatus` to `produced` | `reused` | `not-applicable`. Also persist `state.run.lastAnalysisDigest` (this document's `evidence_digest`) and `state.run.analysisBaseCommit` (`git rev-parse HEAD`). Phase 3's freshness check reads both; unwritten, it has nothing to compare and passes silently. Whether the file is committed with the work is `prefs.global.analysisPhase.commitDoc` (default `true`), read at Phase 6.
-
-**The gate is not optional.** `node $HOME/.claude/scripts/validate-analysis-doc.mjs <file>` must exit 0 for every produced file; non-zero fails CLOSED like the JSON validator below (rework once, then halt).
-
-Progress line: `→ analysis doc: <produced|reused|not-applicable> (<N> platform, validator <pass|pass-after-rework>)`
-
-#### Output contract
-
-Two artefacts, both read downstream: `state.analysis` (the object below, for Phase 2 decomposition) and the Step 4 document (Phase 2 pre-flight + Phase 3's sole design source, Locked 30).
-
-Phase 1 produces an object conforming to `$HOME/.claude/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: 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
-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"
-```
-
-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 $HOME/.claude/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:{stacks} lang:{detectedStack} | {N} files identified, {summary}"
-
-#### Telemetry  -  token forwarding
-
-Forward the explorer call's token totals into the tracker so Phase 7's Cost Breakdown captures Phase 1:
-
-```bash
-LOG_METRIC_FORWARD_TO_TRACKER=1 $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 1 analysis.completed \
-  model=sonnet tokens_in=$IN tokens_out=$OUT duration_ms=$DUR
-```
-
-Best-effort. See `$HOME/.claude/multi-agent-refs/progress-contract.md#token-telemetry-forwarding` 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 $HOME/.claude/scripts/triage-memory.mjs query \
-  --issue "$TASK_TITLE $TASK_DESCRIPTION" --top 3 2>/dev/null | jq -c '.hits // []')
-```
-
-Hits are relevance-ranked, and a query matching nothing returns nothing. Each hit carries an `id`: `triage-memory.mjs show --id <id>` returns the full row.
-
-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
-
-```bash
-bash $HOME/.claude/scripts/phase-tracker.sh tokens 1 <input_count> <output_count>
-```
-
-Contract and rationale: `progress-contract.md` -> Token telemetry forwarding.
-