@mmerterden/multi-agent-pipeline 17.6.0 → 19.0.0

package/pipeline/multi-agent-refs/rules.md

@@ -49,10 +49,10 @@ This is the single source of truth. When a contributor or model is unsure where
 ## Code & Commit Rules
 
 - **NEVER** put "Copilot", "AI", "generated by", or similar attribution in code, comments, commit messages, PR descriptions, or issue comments. The pipeline is a tool  -  it writes on behalf of the configured Git identity, not as itself.
-- **NEVER** commit without passing build (all gates in Phase 4 Step 1 must be green).
+- **NEVER** commit without passing build (all gates in Phase 3 Step 1 must be green).
 - **NEVER** commit without passing review (at least one AI reviewer must return `approved: true` with no blocking findings).
 - **NEVER** skip tests. Every public method, every error path, every edge case.
-- **NEVER** delete, rename, or weaken an existing test to get a green run. Existing tests are immutable during a task; one may change only when the task changes the spec it encodes, and the commit body names both. Deterministic backstop: the `test_lines_removed` diff-risk signal (Phase 4 Step 1.75) flags test files that shrink. A pass only on retry is a flake signal, not a pass: Phase 3 repeats new and changed tests (`testStability.repeatCount`, default 3) and logs `test.flake_signal` when runs disagree.
+- **NEVER** delete, rename, or weaken an existing test to get a green run. Existing tests are immutable during a task; one may change only when the task changes the spec it encodes, and the commit body names both. Deterministic backstop: the `test_lines_removed` diff-risk signal (Phase 3 Step 1.75) flags test files that shrink. A pass only on retry is a flake signal, not a pass: Phase 3 repeats new and changed tests (`testStability.repeatCount`, default 3) and logs `test.flake_signal` when runs disagree.
 - **Follow existing code style and conventions.** Read neighbor files before writing new ones  -  match naming, structure, import order.
 - **Use design tokens, no magic numbers.** `16` → `.Spacing.spacing16`. `#E31837` → `Color.Primary.primary`. `.font(.system(size: 14))` → `.typographyStyle(.body1)`.
 - **Design system primitives before custom views.** Before writing a new View / Configuration triplet in a feature module, grep the shared component library (e.g. `Common/UIComponents/`, `core-ui/`, `packages/ui/`) for a primitive that already solves it. Domain-level wrappers, custom modals, buttons or toasts are forbidden when the design system has an equivalent. If the primitive exists but lacks a modifier (placeholder, size, error binding), **add the modifier to the primitive** in its `+Modifiers` extension; never fork it into the consumer domain. The Figma `CodeConnectSnippet` is the authoritative pointer to which primitive to use.
@@ -158,7 +158,7 @@ This is the single source of truth. When a contributor or model is unsure where
 
 ## Provider CLI Invocations
 
-Provider tools that print failed argv on retry leak credentials into the conversation transcript. Every Vercel call from the pipeline (Phase 6 deploy hooks, Phase 7 site updates, manual `vercel deploy` shells) MUST go through the wrapper:
+Provider tools that print failed argv on retry leak credentials into the conversation transcript. Every Vercel call from the pipeline (Phase 4 deploy hooks, Phase 5 site updates, manual `vercel deploy` shells) MUST go through the wrapper:
 
 ```bash
 # CORRECT  -  the wrapper resolves the token itself, via the logical key `vercel`
@@ -193,13 +193,13 @@ These rules govern when and how the pipeline asks the user, and when it must NOT
 
 ## Figma Access Tier (pipeline-wide, BLOCKING)
 
-When any task references a Figma frame (URL, node ID, or free-text "from the design"), the pipeline MUST establish a Figma ground-truth artefact via a 3-tier fallback chain before any UI line is written. The tier in use is persisted as `state.figmaAccess.tier` and read by every phase that consumes or verifies the reference (Phase 0 intake, Phase 1 analysis, Phase 2 planning, Phase 3 dev, Phase 4 review, Phase 5 manual test, Phase 7 channels).
+When any task references a Figma frame (URL, node ID, or free-text "from the design"), the pipeline MUST establish a Figma ground-truth artefact via a 3-tier fallback chain before any UI line is written. The tier in use is persisted as `state.figmaAccess.tier` and read by every phase that consumes or verifies the reference (Phase 0 intake, Phase 1 analysis, Phase 1 planning, Phase 2 dev, Phase 3 review, Phase 5 manual test, Phase 5 channels).
 
 | Tier | Source | When chosen | Code Connect available |
 |---|---|---|---|
 | 1 | Figma MCP server (`mcp__claude_ai_Figma__get_design_context`, `get_screenshot`, `get_metadata`); MCP token resolves through `prefs.global.keychainMapping.figma_mcp` (for MCP server config bootstrap) | The host serves the `mcp__claude_ai_Figma__*` tools AND MCP auth succeeds (after one re-auth retry; on continued auth failure the user is asked: recreate the MCP token or continue with the PAT  -  never a silent fallthrough) | yes (`CodeConnectSnippet` blocks) |
 | 2 | Figma REST API (`GET /v1/files/{fileKey}/nodes`, `GET /v1/images/{fileKey}`) with Personal Access Token resolved via `~/.claude/lib/credential-store.sh get <logical-key>` where `<logical-key>` = `prefs.global.keychainMapping.figma` | Tier 1 unreachable AND PAT is mapped; on a 401/403 the user is asked the Expired-token decision (regenerate / different token / skip) before moving to Tier 3 | no, fall back to repo `*.figma.swift` / `*.figma.kt` mappings keyed by `fileKey` + `nodeId` |
-| 3 | User-attached screenshot in chat or task attachment | Tiers 1 + 2 both unreachable AND user has provided a screenshot | no  -  record an Open Question, pick the closest existing primitive WITH user confirmation, set Phase 4 reviewer flag to `review_blocking` |
+| 3 | User-attached screenshot in chat or task attachment | Tiers 1 + 2 both unreachable AND user has provided a screenshot | no  -  record an Open Question, pick the closest existing primitive WITH user confirmation, set Phase 3 reviewer flag to `review_blocking` |
 
 **Tier 1 availability is per host, and "unavailable" is not "auth failed".** Tools absent (the normal case on Copilot CLI and Codex CLI, where the installer registers only the toolkit MCP) means Tier 2 is the expected entry point: record `figmaAccess.tier1Unavailable = "host"`, skip the re-auth retry, and never raise the MCP-token question. Tools present but failing auth is `"auth"`, where the retry does apply. Probe mechanics: `phases/phase-0-init.md`.
 
@@ -211,9 +211,9 @@ Full chain definition, REST endpoints, URL parsing, Code Connect snippet rules,
 
 ### Figma Access by Phase (pipeline-wide BLOCKING, v9.0.0)
 
-Per Locked decision 30 of `/multi-agent:analysis` and the parallel rule in `$HOME/.claude/rules/figma-pipeline.md`, Figma MCP / REST is allowed only in the analysis phase. Phase 2 through Phase 7 in every orchestrator mode (Full or Short, `--local`, autopilot) consume the analysis document + repo Code Connect mappings.
+Per Locked decision 30 of `/multi-agent:analysis` and the parallel rule in `$HOME/.claude/rules/figma-pipeline.md`, Figma MCP / REST is allowed only in the analysis phase. Phase 2 through Phase 5 in every orchestrator mode (Full or Short, `--local`, autopilot) consume the analysis document + repo Code Connect mappings.
 
-The ban is **Figma**-shaped, not MCP-shaped: the multi-agent-toolkit MCP (simulator, screenshot, xcodebuild, accessibility) is unaffected in every phase, and `smoke-no-mcp-in-dev-phases.sh` agrees - it matches `figma` in the tool name and nothing else. A bare "MCP forbidden" has been read as banning the screenshot and UI-test tools, which is how a run reaches Phase 7 with no evidence.
+The ban is **Figma**-shaped, not MCP-shaped: the multi-agent-toolkit MCP (simulator, screenshot, xcodebuild, accessibility) is unaffected in every phase, and `smoke-no-mcp-in-dev-phases.sh` agrees - it matches `figma` in the tool name and nothing else. A bare "MCP forbidden" has been read as banning the screenshot and UI-test tools, which is how a run reaches Phase 5 with no evidence.
 
 The per-phase matrix (which phase may fetch Figma, and what its sole design source is instead) lives in `rules/figma-pipeline.md` "Phase access matrix". It was copied here as a seven-row table for several releases, two paragraphs below this file's own instruction not to duplicate that rule file. Violation of either copy: `smoke-no-mcp-in-dev-phases.sh` fails the run.
 

package/pipeline/multi-agent-refs/swiftui-guide.md

@@ -17,7 +17,7 @@
 - [Figma URL Given](#figma-url-given)
 <!-- /toc -->
 
-> **MUST: Figma MCP-first (BLOCKING).** If the task references any Figma frame (URL, node ID, or "from the design"), the Dev phase MUST call `mcp__claude_ai_Figma__get_design_context` for every frame BEFORE writing a single UI line. Use the `CodeConnectSnippet` component name verbatim - no sound-alike substitutions. Authentication failure is not a skip path. Full rule, trigger conditions, and gate failure modes: `$HOME/.claude/rules/figma-pipeline.md` "MUST: Figma MCP-first (BLOCKING)". Phase wiring: `$HOME/.claude/multi-agent-refs/phases/phase-3-dev.md` "MUST: Figma MCP-first (BLOCKING pre-step)".
+> **MUST: Figma MCP-first (BLOCKING).** If the task references any Figma frame (URL, node ID, or "from the design"), the Dev phase MUST call `mcp__claude_ai_Figma__get_design_context` for every frame BEFORE writing a single UI line. Use the `CodeConnectSnippet` component name verbatim - no sound-alike substitutions. Authentication failure is not a skip path. Full rule, trigger conditions, and gate failure modes: `$HOME/.claude/rules/figma-pipeline.md` "MUST: Figma MCP-first (BLOCKING)". Phase wiring: `$HOME/.claude/multi-agent-refs/phases/phase-2-dev.md` "MUST: Figma MCP-first (BLOCKING pre-step)".
 
 When the task involves creating a SwiftUI component (any project), follow this architecture.
 These practices come from the battle-tested Figma-to-SwiftUI pipeline  -  apply them in every iOS project.
@@ -270,4 +270,4 @@ FLEXManager.shared.showExplorer()
 
 If user provides a Figma URL, use Figma MCP tools (get_design_context, get_screenshot) to fetch design data, map to project tokens, and apply Configuration/View/Modifiers pattern.
 
-For figma project specifically: multi-agent reads `.instructions/figma/` SKILL.md files for the full 8-phase pipeline.
+For figma project specifically: multi-agent reads `.instructions/figma/` SKILL.md files for the full 6-phase pipeline.

package/pipeline/multi-agent-refs/tracker-contract.md

@@ -66,7 +66,7 @@ Two constraints on `update_plan`, both of which fail quietly if ignored:
 - **It is unavailable in Codex plan mode.** Fall back to
   `bash phase-tracker.sh render` there rather than skipping the visual channel.
 
-The plan step is the phase label, not a restatement of the work: `Phase 4  -  Review`
+The plan step is the phase label, not a restatement of the work: `Phase 3  -  Review`
 in the step list, with detail going to the agent log. A plan that mirrors the phase
 list is legible; one that mirrors the task list duplicates what the log already
 holds.
@@ -89,10 +89,10 @@ Phases by mode:
 
 | Mode | Phases |
 |---|---|
-| `/multi-agent` | 0,1,2,3,4,5,6,7 |
-| `/multi-agent:local` | 0,1,2,3,4,6,7 (Phase 5 User Test needs a worktree checkout; local has none) |
-| `/multi-agent:autopilot`, `/multi-agent:local-autopilot` | 0,1,2,3,4,6,7 (always Full; autopilot drops the interactive Phase 5 gate) |
-| `/multi-agent:analysis` | 0,1,2,4,6,7 (no code is written, so no Dev and no Test) |
+| `/multi-agent` | 0,1,2,3,4,5 |
+| `/multi-agent:local` | 0,1,2,3,4,5 (the user test needs a worktree checkout and local has none, so that STEP inside Review is skipped - the phase is not) |
+| `/multi-agent:autopilot`, `/multi-agent:local-autopilot` | 0,1,2,3,4,5 (always Full; autopilot drops the interactive user test inside Review) |
+| `/multi-agent:analysis` | 0,1,3,4,5 (no code is written, so Dev is not in the set) |
 
 The two picker entries (`/multi-agent`, `:local`) register in two batches, because at Step -1 they do not yet know which set is theirs: see "Deferred registration" below. Every other mode registers its whole set at Step -1.
 
@@ -107,7 +107,7 @@ bash $HOME/.claude/scripts/phase-tracker.sh add 1 "Analysis"
 ### Claude Code  -  also register a TaskList tile per phase
 
 ```text
-For each phase in the current mode, IN PHASE-NUMBER ORDER (0 → 1 → 2 → ... → 7):
+For each phase in the current mode, IN PHASE-NUMBER ORDER (0 → 1 → 2 → ... → 5):
   TaskCreate({
     subject: "Phase 0: Init",
     description: "Repo discovery, branch, worktree, identity bind",
@@ -178,39 +178,37 @@ The correct sequence is **always**:
 ```text
 # Step A  -  register every phase tile in the ACTIVE MODE'S SET, in phase-number
 # order. A phase outside the mode's set gets no TaskCreate at all  -  the example
-# below is the full pipeline, whose set happens to be all eight.
+# below is the full pipeline, whose set happens to be all six.
 TaskCreate(Phase 0)  → taskId₀
 TaskCreate(Phase 1)  → taskId₁
 TaskCreate(Phase 2)  → taskId₂
 TaskCreate(Phase 3)  → taskId₃
 TaskCreate(Phase 4)  → taskId₄
 TaskCreate(Phase 5)  → taskId₅
-TaskCreate(Phase 6)  → taskId₆
-TaskCreate(Phase 7)  → taskId₇
 
 # Step B  -  only AFTER every tile is created, apply status updates
 TaskUpdate(taskId₀, status="in_progress")              # Phase 0 starts
 # A phase that IS in the set but short-circuits at runtime flips here, e.g. a
-# full-pipeline run whose Phase 5 test gate is suppressed by autopilot:
-TaskUpdate(taskId₅, status="completed", activeForm="[SKIPPED]")
+# full-pipeline run whose Phase 3 user test is suppressed by autopilot:
+TaskUpdate(taskId₃, status="completed", activeForm="[SKIPPED]")
 ```
 
 Mode-specific phase sets:
 
 | Mode | TaskCreate set (in order) |
 |---|---|
-| `/multi-agent` | 0 at Step -1; then at Step 7.5 either 1 → 2 → 3 → 4 → 5 → 6 → 7 (Full) or 3 → 4 → 5 → 6 → 7 (Short) |
-| `:local` | same two batches, with Phase 5 in neither |
-| `:autopilot`, `:local-autopilot` | 0 → 1 → 2 → 3 → 4 → 6 → 7 (7 phases  -  always Full, and the interactive Phase 5 gate is dropped) |
-| `:analysis` | 0 → 1 → 2 → 4 → 6 → 7 (6 phases  -  no code is written, so 3 and 5 are not in the set) |
+| `/multi-agent` | 0 at Step -1; then at Step 7.5 either 1 → 2 → 3 → 4 → 5 (Full) or 2 → 3 → 4 → 5 (Short) |
+| `:local` | same two batches; nothing is dropped, because the user test that needs a worktree checkout is a step inside Review rather than a phase of its own |
+| `:autopilot`, `:local-autopilot` | 0 → 1 → 2 → 3 → 4 → 5 (6 phases  -  always Full; the user test is inside Review now, so no phase is dropped) |
+| `:analysis` | 0 → 1 → 3 → 4 → 5 (5 phases  -  no code is written, so Dev is not in the set) |
 
-A phase outside the mode's set gets no TaskCreate at all; the `[SKIPPED]` pattern applies only to a phase that IS in the set and short-circuits at runtime. Phase 4 is in every mode's set as of v14.0.0. The authoritative per-mode set is the `for p in ...` init block in each mode's own entry doc, generated by `gen-mode-dispatch.mjs`; this table mirrors those blocks.
+A phase outside the mode's set gets no TaskCreate at all; the `[SKIPPED]` pattern applies only to a phase that IS in the set and short-circuits at runtime. Phase 3 is in every mode's set as of v14.0.0. The authoritative per-mode set is the `for p in ...` init block in each mode's own entry doc, generated by `gen-mode-dispatch.mjs`; this table mirrors those blocks.
 
 #### Deferred registration  -  the depth picker
 
 `/multi-agent` and `:local` cannot know their phase set at Step -1. Depth decides it, and the depth picker cannot run before Step 7.5: its recommendation needs `taskType`, which needs the fetched issue and the branch.
 
-Until v17.5.0 they registered all eight anyway and flipped 1 and 2 to `skipped` at 7.5. That put a widget reading "8 tasks, 7 open  -  Phase 1 Analysis, Phase 2 Planning, ..." on screen *beside* the question asking whether to run Analysis and Planning at all, and a Short answer then contradicted a list the user had just been shown. The widget was asserting a shape the run had not chosen.
+Until v17.5.0 they registered all eight anyway and flipped 1 and 2 to `skipped` at 7.5. That put a widget reading "8 tasks, 7 open  -  Phase 1 Plan, Phase 1 Plan, ..." on screen *beside* the question asking whether to run Analysis and Planning at all, and a Short answer then contradicted a list the user had just been shown. The widget was asserting a shape the run had not chosen.
 
 So registration splits at the moment the shape is known:
 
@@ -222,9 +220,10 @@ bash $HOME/.claude/scripts/phase-tracker.sh tiles        # -> TaskCreate(Phase 0
 bash $HOME/.claude/scripts/phase-tracker.sh update 0 in_progress
 
 # Step 7.5, immediately after the depth answer:
-#   Full  -> 1 2 3 4 5 6 7        Short -> 3 4 5 6 7
-#   :local drops 5 from either (no worktree to check out from)
-for p in "3:Dev" "4:Review" "5:Test" "6:Commit" "7:Report"; do
+#   Full  -> 1 2 3 4 5            Short -> 2 3 4 5
+#   :local drops nothing - the user test lives inside Review now, so there is
+#   no separate phase for it to skip
+for p in "1:Plan" "2:Dev" "3:Review" "4:Commit" "5:Report"; do
   bash $HOME/.claude/scripts/phase-tracker.sh add "${p%%:*}" "${p#*:}"
 done
 bash $HOME/.claude/scripts/phase-tracker.sh tiles --new   # -> TaskCreate for the new tiles only
@@ -232,7 +231,7 @@ bash $HOME/.claude/scripts/phase-tracker.sh tiles --new   # -> TaskCreate for th
 
 `tiles --new` emits `TaskCreate` only for phases that carry no `tasklist_id` yet, so the Phase 0 tile is not created twice. It is the same ordering rule, applied per batch: every tile in a batch is created in ascending phase order, and a deferred batch only ever appends phases numbered above everything already registered. Nothing is pre-marked, and a phase the run will not execute never gets a tile at all.
 
-A phase that IS registered and short-circuits later still flips with `[SKIPPED]` - autopilot suppressing Phase 5, for instance. That is a runtime outcome, not an unknown set.
+A phase that IS registered and short-circuits later still flips with `[SKIPPED]` - autopilot suppressing the Phase 3 user test, for instance. That is a runtime outcome, not an unknown set.
 
 **Enforcement**: `smoke-tasklist-ordering.sh` scans the dispatcher (`commands/multi-agent/SKILL.md`) and every mode entry point doc (`commands/multi-agent/{autopilot,local,local-autopilot,analysis,resume-local}/SKILL.md` + the Copilot full-inline orchestrator mirror) for the explicit "in phase-number order" rule. Inventory drift fails the smoke.
 
@@ -300,12 +299,12 @@ Throttling rules: mirror only canonical-set lines (`verbose`-tier internals are
 
 ### Delegated phases  -  mirror limitation + chunked dispatch (required)
 
-When a phase's work is delegated to a subagent (Phase 3 Dev on Opus in a Short run, `create-component` plugin dispatch, Phase 1 explorers, Phase 4 reviewers), the visual channel freezes for the duration of the Agent call: the orchestrator is blocked while the call is in flight, so it cannot fire `TaskUpdate` / `now` / `tokens`, and a subagent cannot drive the parent session's TaskList (its own TaskCreate/TaskUpdate calls land on an invisible child list). The progress-line mirror above can therefore only fire while the orchestrator holds control. Rules:
+When a phase's work is delegated to a subagent (Phase 2 Dev on Opus in a Short run, `create-component` plugin dispatch, Phase 1 explorers, Phase 3 reviewers), the visual channel freezes for the duration of the Agent call: the orchestrator is blocked while the call is in flight, so it cannot fire `TaskUpdate` / `now` / `tokens`, and a subagent cannot drive the parent session's TaskList (its own TaskCreate/TaskUpdate calls land on an invisible child list). The progress-line mirror above can therefore only fire while the orchestrator holds control. Rules:
 
 1. **Pre-dispatch marker.** Immediately before every Agent call, set the active-phase line to the delegation itself, so the frozen interval at least states what is running and on which model:
    - Claude Code: `TaskUpdate({activeForm: "Dev subagent (opus): <task subject>"})`
    - Other CLIs: `phase-tracker.sh now <N> "dev subagent (opus): <task subject>"`
-2. **Chunk long delegations.** A phase whose delegated work spans multiple tasks MUST NOT go out as one monolithic Agent call. Dispatch per task (the Phase 2 task graph, or in a Short run the self-generated task list, is the natural chunk boundary) so the orchestrator regains control at each boundary and refreshes `activeForm`, `tokens`, and `now` between chunks. Single-task phases and inherently atomic dispatches (one reviewer, one explorer) are exempt.
+2. **Chunk long delegations.** A phase whose delegated work spans multiple tasks MUST NOT go out as one monolithic Agent call. Dispatch per task (the Phase 1 task graph, or in a Short run the self-generated task list, is the natural chunk boundary) so the orchestrator regains control at each boundary and refreshes `activeForm`, `tokens`, and `now` between chunks. Single-task phases and inherently atomic dispatches (one reviewer, one explorer) are exempt.
 3. **Post-chunk accounting.** When each chunk returns, record its token estimate (`phase-tracker.sh tokens <N> <in> <out>`) before dispatching the next chunk  -  not accumulated once at phase end.
 
 ### 5. Token accounting  -  automatic (manual top-up optional)
@@ -322,7 +321,7 @@ Token counts are additive  -  multiple calls accumulate. `input_count` is FRESH
 **Required: per-phase token narration on completion (v9.10.2).** The native
 TaskList widget cannot display per-phase tokens  -  it shows name, status, and
 duration only. Without this rule the user sees durations and nothing else
-until the Phase 7 Cost Breakdown. So whenever a phase transitions to
+until the Phase 5 Cost Breakdown. So whenever a phase transitions to
 `completed`, in addition to the `TaskUpdate` call, print ONE narrator line in
 `outputLanguage` immediately after, using the same totals just written via
 `phase-tracker.sh tokens`:
@@ -344,7 +343,7 @@ fixed at TaskCreate time). So on phase completion, in addition to the
 narration line, append the spend to the tile subject:
 
 ```text
-TaskUpdate({taskId: <phase_task>, subject: "Phase 3: Dev · ~35k tok · ~$0.26"})
+TaskUpdate({taskId: <phase_task>, subject: "Phase 2: Dev · ~35k tok · ~$0.26"})
 ```
 
 Skip the suffix when the phase recorded zero tokens (subject stays clean).
@@ -353,7 +352,7 @@ Skip the suffix when the phase recorded zero tokens (subject stays clean).
 usage metering, so per-phase counts are content-size estimates (chars/4 for
 prompts dispatched + responses received, subagent payloads included). Prefix
 estimates with `~`. The authoritative end-of-run numbers remain the state file
-and the Phase 7 Cost Breakdown; the narration line exists so the user sees
+and the Phase 5 Cost Breakdown; the narration line exists so the user sees
 live per-phase spend instead of duration-only tiles.
 
 ### 6. Phase context  -  rich summaries via `meta`
@@ -393,19 +392,19 @@ TaskUpdate({taskId: <phase_task>, activeForm: "Running explorer: repo-map"})
 
 ## The plan is part of the list
 
-Phase 2 computes `tasks[]`, their order and their `dependsOn[]` edges, stores
-them, and uses them to drive Phase 3's ready-task picker. For releases the card
+Phase 1 computes `tasks[]`, their order and their `dependsOn[]` edges, stores
+them, and uses them to drive Phase 2's ready-task picker. For releases the card
 drew them as sub-phases and the widget did not, which meant the one surface the
 user actually watches was the one place the plan did not exist.
 
-Phase 2 Step 4.45 calls `phase-tracker.sh plan 3` with the planning-output
+Phase 1 Step 4.45 calls `phase-tracker.sh plan 3` with the planning-output
 document on stdin. Each task becomes a sub-phase of the phase that will execute
-it, `pending`, carrying its `dependsOn[]` as `deps`. Phase 3 moves them with
+it, `pending`, carrying its `dependsOn[]` as `deps`. Phase 2 moves them with
 `sub` as it works.
 
 **A rebuild, not an append.** Creation order is the only ordering the native
 widget has - there is no parent field and no insert - so steps arriving at
-Phase 2 cannot be appended without landing after Phase 7. `tiles` detects that
+Phase 2 cannot be appended without landing after Phase 5. `tiles` detects that
 sub-steps exist and asks for the list to be deleted and recreated. That is one
 rebuild at one boundary, and it is the same thing Resume already does below for
 a different reason.
@@ -439,7 +438,7 @@ A pre-existing `tracker-state.json` for the task is never re-initialized. Rules
 
 1. `init` runs ONLY when no state file exists for the task. Otherwise the existing file is kept - phase history (elapsed, tokens, model, meta) survives.
 2. The continuing command re-declares its phase set with `add` - `add` is idempotent, so existing phases keep their name, status, and token history; only genuinely new phases are appended. The card renders phases sorted by numeric id, so mixed sets stay in order.
-3. If Phase 5 was left `in_progress` with `Now: awaiting local test (user)`, the continuing command marks it `update 5 completed` + `meta 5 Result "local test done (user)"` before its own work starts (finish may re-open it with `update 5 in_progress` when its build+test gate runs; elapsed keeps the original `started_at`, which is acceptable).
+3. If Phase 3 was left `in_progress` with `Now: awaiting local test (user)`, the continuing command marks it `update 5 completed` + `meta 5 Result "local test done (user)"` before its own work starts (finish may re-open it with `update 5 in_progress` when its build+test gate runs; elapsed keeps the original `started_at`, which is acceptable).
 4. On Claude Code, rebuild the FULL TaskList from the state file (completed tiles included) in phase order before any `TaskUpdate`, refreshing every `tasklist_id` meta - exactly the Resume behaviour above.
 5. Print ONE line in `outputLanguage` summarizing the inherited history, e.g. `Continuing PROJ-12345: phases 0-3 finished earlier (12m, 38.4k tok, ~$0.74)` (USD via `cost total`), then `render`.
 

package/pipeline/multi-agent-refs/unattended-contract.md

@@ -0,0 +1,129 @@
+# Unattended contract (`MULTI_AGENT_UNATTENDED=1`)
+
+<!-- toc -->
+- [What the variable means](#what-the-variable-means)
+- [The three effects](#the-three-effects)
+- [What it does NOT do](#what-it-does-not-do)
+- [Who honours it](#who-honours-it)
+- [The model side already has a contract](#the-model-side-already-has-a-contract)
+- [Default behaviour is unchanged, and a gate says so](#default-behaviour-is-unchanged-and-a-gate-says-so)
+- [The permission posture](#the-permission-posture)
+<!-- /toc -->
+
+## What the variable means
+
+`MULTI_AGENT_UNATTENDED=1` is the operator stating that **nobody is watching
+this process**, and it is the only way to state it reliably.
+
+The usual test for that is `[ -t 0 ]`: no terminal, no human. It is wrong in
+both directions on a server. A run under `screen`, `tmux`, `ssh -t` or a login
+shell HAS a terminal and still has nobody in front of it, so the test says
+"ask" and the process waits for an answer that will never come - printing
+nothing, exiting never, and looking exactly like slow work. That is the failure
+this contract exists to remove, and it is not hypothetical: two setup scripts
+shipped that way.
+
+The variable is opt-in and defaults to absent. Nothing in this file describes
+behaviour that changes on a machine that does not set it.
+
+## The three effects
+
+**1. No prompt blocks.** Every shell entry point that asks a question either
+resolves it from a documented default or refuses with a reason on stderr and a
+non-zero exit. Waiting is never one of the outcomes. Refusing beats hanging:
+one of them can be read in a log.
+
+**2. Output is greppable.** Colour is off even when stdout is a terminal.
+ANSI escapes in a log file make it unsearchable, and on a server the terminal
+that is attached is not the one anyone reads.
+
+**3. A secret is never a prompt.** Credentials arrive through stdin or a file
+path, never through an interactive read and never through an environment
+variable. An env value is inherited by every child process and is visible to
+`ps e` on some systems; a pipe stays in the one process that needs it.
+
+## What it does NOT do
+
+- It does not grant permissions. An unattended run still needs a permission
+  posture, which is a separate opt-in (`install --unattended`) and a separate
+  doctor check.
+- It does not suppress errors. A run that cannot proceed still fails; it just
+  fails visibly instead of hanging.
+- It does not change any default. With the variable unset, every script below
+  behaves exactly as it did before this contract existed.
+
+## Who honours it
+
+Paths below are install-relative: `lib/` and `scripts/` under the host root,
+which is `~/.claude`, `~/.copilot` or `~/.codex` depending on the install. A
+ref that ships to users must not name a checkout path, because a run happens
+in the user's worktree and the checkout is not there.
+
+| Entry point | Without the variable | With `MULTI_AGENT_UNATTENDED=1` |
+|---|---|---|
+| `lib/ask-choice.sh` | TTY: renders the menu and reads. No TTY: first option, notice on stderr | First option (or `ASK_CHOICE_DEFAULT`), never prompts |
+| `scripts/github-ssh-setup.sh` | TTY: three questions. No TTY: refuses, naming `SSH_SETUP_EMAIL` | Refuses the same way even with a terminal |
+| `scripts/keychain-save.sh` | TTY: menu + secret prompt. No TTY: refuses, naming `--stdin` / `--json` | Refuses the same way even with a terminal |
+| `scripts/phase-banner.sh` | Colour when stdout is a TTY and `TERM != dumb` | Plain text |
+
+Anything not in this table does not read the variable. That is deliberate: a
+list of four that is true beats a claim of coverage that is not.
+
+## The model side already has a contract
+
+The prompt-level question - what an agent does when it would call
+`AskUserQuestion` and no one can answer - is `refs/picker-contract.md`, section
+"Autopilot / non-interactive contract", and it predates this file. It resolves
+from the remembered choice first, then the documented default, and records
+which rule fired so the run stays readable afterwards.
+
+The two are different layers and should not be merged. The picker contract
+governs a model deciding; this file governs a process waiting. A run on a
+server needs both, and only one of them can be enforced by a gate.
+
+## Default behaviour is unchanged, and a gate says so
+
+`smoke-unattended-profile.sh` (a maintainer gate, not shipped) asserts both directions. With the variable set,
+each entry point above resolves or refuses under a hard timeout. With it unset,
+each one produces byte-identical output to the behaviour it had before - the
+assertion that matters most, because the whole point is that a local
+interactive machine is not affected by any of this.
+
+## The permission posture
+
+Everything above concerns a process that would otherwise WAIT. There is a second
+way an unattended run stops, and it does not wait at all.
+
+autopilot spawns its child with `--permission-prompts none`. That stops Claude
+Code from ASKING; it grants nothing. The tools the child then calls still have
+to be allowed, and on a fresh machine they are not - so the run stops at the
+first tool call, with no prompt anywhere for a person to answer. From the
+outside it is indistinguishable from a queue with nothing to do.
+
+`install --unattended` writes the profile that closes it:
+
+```bash
+npx @mmerterden/multi-agent-pipeline install --unattended --dry-run   # show it
+npx @mmerterden/multi-agent-pipeline install --unattended             # write it
+```
+
+Three properties, each one a promise to somebody who did not ask for this:
+
+1. A DEFAULT install writes no permissions at all. Widening a permission set is
+   not something an installer does to a person who wanted files copied.
+2. The profile is printed in full, with a reason per line, BEFORE anything is
+   written. "The installer changed my permissions" must never be a thing
+   discovered afterwards.
+3. It is additive and idempotent. An entry a person added by hand survives, a
+   narrower rule is kept alongside, unrelated settings are untouched, and a
+   second run changes nothing. A `settings.json` that does not parse is refused
+   rather than overwritten.
+
+The entries are broad, and that breadth is what unattended operation costs
+rather than an oversight: a run builds and tests whatever the target repo uses,
+so an allowlist narrow enough to be interesting is one the first unfamiliar repo
+stops at. `doctor --profile=server` reports `unattended-permissions` against the
+same rule the writer applies, so the two cannot disagree.
+
+`smoke-unattended-install-profile.sh` asserts all of it, including that a plain
+install still writes nothing.

package/pipeline/multi-agent-refs/wiki-capture.md

@@ -11,9 +11,9 @@
 - [Cross-CLI parity](#cross-cli-parity)
 <!-- /toc -->
 
-> **TLDR**  -  Component tasks can auto-generate wiki docs + Figma screenshots. The Wiki adapter is invoked from `/multi-agent:channels` (Phase 7 delegates, or user invokes post-hoc). Four layouts supported (`submodule`, `in-repo`, `github-wiki`, `separate-repo`)  -  adapter picked from `figmaConfig.wiki.mode`. Non-blocking: failures log a warning and channels continues to other adapters. The Wiki adapter supports scope multi-select (Case A) and a precondition-failure menu (Case B)  -  see below.
+> **TLDR**  -  Component tasks can auto-generate wiki docs + Figma screenshots. The Wiki adapter is invoked from `/multi-agent:channels` (Phase 5 delegates, or user invokes post-hoc). Four layouts supported (`submodule`, `in-repo`, `github-wiki`, `separate-repo`)  -  adapter picked from `figmaConfig.wiki.mode`. Non-blocking: failures log a warning and channels continues to other adapters. The Wiki adapter supports scope multi-select (Case A) and a precondition-failure menu (Case B)  -  see below.
 
-This doc is referenced from `commands/multi-agent/channels/SKILL.md` (Wiki adapter) and indirectly from `$HOME/.claude/multi-agent-refs/phases/phase-7-report.md` (which delegates all external delivery to channels). Keeping it separate keeps both files under their token budgets and gives the contract a stable location for Claude-side + Copilot-side implementations.
+This doc is referenced from `commands/multi-agent/channels/SKILL.md` (Wiki adapter) and indirectly from `$HOME/.claude/multi-agent-refs/phases/phase-5-report.md` (which delegates all external delivery to channels). Keeping it separate keeps both files under their token budgets and gives the contract a stable location for Claude-side + Copilot-side implementations.
 
 ## Applicability
 
@@ -43,7 +43,7 @@ What should I update in the wiki? (space = toggle, enter = confirm)
 Pre-ticks from `prefs.global.wikiScope` (array of scope IDs). Saved after selection for next run.
 
 - Selecting a subset (e.g. only Screenshots) → adapter runs with `scope=["screenshots"]`, skipping main/iOS/index writes.
-- Selecting "Other" alone → adapter dispatch is skipped entirely. Phase 7 / channels logs `Wiki: manual override  -  skipped by user`. No git push, no file changes.
+- Selecting "Other" alone → adapter dispatch is skipped entirely. Phase 5 / channels logs `Wiki: manual override  -  skipped by user`. No git push, no file changes.
 - Selecting nothing and confirming → same as "Other" alone (explicit skip).
 
 The adapter receives `scope: string[]` alongside `{componentName, componentPath, figmaConfig, agentState}` and writes only the requested artifacts.
@@ -53,7 +53,7 @@ The adapter receives `scope: string[]` alongside `{componentName, componentPath,
 When preconditions fail, the gap is surfaced with a fix menu instead of a silent no-op:
 
 ```
-Phase 7 · Wiki  -  preconditions not met
+Phase 5 · Wiki  -  preconditions not met
 
   taskType:          {current}     ({component expected} ✗)
   figma-config.json: {found/missing}
@@ -67,11 +67,11 @@ Phase 7 · Wiki  -  preconditions not met
 ```
 
 - **[1]** dispatches to `setup.md` Token Save Flow for Figma, then bootstraps `figma-config.json` from `preferences-template.json` `_figmaConfigTemplate`. After success, re-check preconditions  -  if met, fall into Case A. If user cancels the setup, fall back to [2].
-- **[2]** `phase-tracker.sh sub 7 1 "Channels/Wiki" skipped`, log line: `Wiki skipped  -  preconditions not met (this run only)`. Next run re-prompts.
+- **[2]** `phase-tracker.sh sub 5 1 "Channels/Wiki" skipped`, log line: `Wiki skipped  -  preconditions not met (this run only)`. Next run re-prompts.
 - **[3]** write `figmaConfig.wiki.enabled = false` to the project config. Subsequent runs silently skip Wiki (no menu, no prompt)  -  exactly the pre-v5.7 behavior for projects that don't want wiki.
 - **[4]** free-text prompt, user's note appended to agent-log under `### Wiki Manual Override`. No adapter action.
 
-Autopilot in Phase 7 pauses at the channels menu (per modes.md contract)  -  if user selects Wiki and preconditions fail, Case B opens, user picks. Post-hoc `/multi-agent:channels` with `--channels wiki` + failed preconditions: Case B opens non-negotiably (autopilot rules don't apply to post-hoc invocations).
+Autopilot in Phase 5 pauses at the channels menu (per modes.md contract)  -  if user selects Wiki and preconditions fail, Case B opens, user picks. Post-hoc `/multi-agent:channels` with `--channels wiki` + failed preconditions: Case B opens non-negotiably (autopilot rules don't apply to post-hoc invocations).
 
 ## Legacy prompt + preference flow (pre-v5.7, still supported for backward compat)
 
@@ -91,23 +91,23 @@ Save the answer to `prefs.global.wikiDefault` for next run. Migration script (`m
 1. Resolve wiki mode from `figmaConfig.wiki.mode`  -  one of `submodule`, `in-repo`, `github-wiki`, `separate-repo`. Each has a dedicated adapter inside the `figma-component-wiki` skill; see the `ai-ios-toolkit:figma-component-wiki` plugin skill for per-mode path layout and push semantics.
 2. Emit progress line: `→ writing wiki {componentName} (mode: {mode})`.
 3. Dispatch to the plugin skill `ai-ios-toolkit:figma-component-wiki` (iOS) or `ai-android-toolkit:figma-component-wiki` (Android), passing `{componentName, componentPath, figmaConfig}`.
-4. Skill returns `{ writtenPaths[], committedSha?, pushedRemote? }`. Write `writtenPaths` to Phase 7 summary's "Files written" section and push metadata (if any) to "External publishes".
-5. On adapter failure  -  log the adapter + mode + error, continue Phase 7. Wiki is a non-blocking augmentation; the Jira comment in Step 3 already carries the component summary, so the developer is never left in the dark if wiki misfires.
+4. Skill returns `{ writtenPaths[], committedSha?, pushedRemote? }`. Write `writtenPaths` to Phase 5 summary's "Files written" section and push metadata (if any) to "External publishes".
+5. On adapter failure  -  log the adapter + mode + error, continue Phase 5. Wiki is a non-blocking augmentation; the Jira comment in Step 3 already carries the component summary, so the developer is never left in the dark if wiki misfires.
 
 ## Skip conditions (explicit log lines)
 
 Explicit logs help the developer understand why wiki did or did not run:
 
 - `state.taskType !== "component"` → skip silently (no log).
-- `figmaConfig.wiki.enabled === false` → log `Phase 7: wiki disabled in figma-config.json`.
-- `figmaConfig` missing entirely → log `Phase 7: wiki skipped (no figma-config for this project)`.
-- User declined at prompt → log `Phase 7: wiki skipped by user`.
-- Autopilot with `wikiDefault=false` → log `Phase 7: wiki skipped (autopilot + wikiDefault=false)`.
+- `figmaConfig.wiki.enabled === false` → log `Phase 5: wiki disabled in figma-config.json`.
+- `figmaConfig` missing entirely → log `Phase 5: wiki skipped (no figma-config for this project)`.
+- User declined at prompt → log `Phase 5: wiki skipped by user`.
+- Autopilot with `wikiDefault=false` → log `Phase 5: wiki skipped (autopilot + wikiDefault=false)`.
 - Short run: DO prompt  -  wiki is cheap and keeps docs fresh on the fast path; skip only if the user says no.
 
 ## Success log
 
-`Phase 7: Component wiki generated  -  {componentName} via {mode} ({paths.length} files)`
+`Phase 5: Component wiki generated  -  {componentName} via {mode} ({paths.length} files)`
 
 ## Cross-CLI parity
 
@@ -118,6 +118,6 @@ Claude Code and Copilot CLI MUST:
 - Render byte-identical Case A / Case B menus (spacing, brackets, numbering).
 - Respect `prefs.global.wikiScope` array. Legacy `wikiDefault` boolean is migrated on first v5.7 load.
 - Treat adapter failures as non-blocking with the same log shape.
-- Pause the Case A / Case B menu in autopilot  -  per Phase 7 autopilot exception (`$HOME/.claude/multi-agent-refs/phases/modes.md`). 30-min timeout ends session cleanly; resume re-opens menu.
+- Pause the Case A / Case B menu in autopilot  -  per Phase 5 autopilot exception (`$HOME/.claude/multi-agent-refs/phases/modes.md`). 30-min timeout ends session cleanly; resume re-opens menu.
 
 `smoke-wiki-integration.sh` asserts every contract item documented above.

package/pipeline/preferences-template.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "2.6.0",
+  "schemaVersion": "2.7.0",
   "global": {
     "identities": [],
     "keychainMapping": {
@@ -67,6 +67,14 @@
       "fableEnabled": false,
       "onDispatchError": true
     },
+    "modelRouting": {
+      "enabled": false,
+      "strategy": "manual",
+      "scope": ["subagent"],
+      "rules": [],
+      "budgetCeilingUsd": null,
+      "recordDecisions": true
+    },
     "costBudget": {
       "enabled": true,
       "maxUsd": 5.0,

package/pipeline/rules/outside-the-pipeline.md

@@ -1,7 +1,7 @@
 ## Outside a pipeline run
 
 `/multi-agent` is not the only way to use what the install set up. Reach for
-these when the work calls for it - not eagerly, and not by starting an 8-phase
+these when the work calls for it - not eagerly, and not by starting a 6-phase
 run to read one ticket. Detail, commands and the safety contract:
 `$HOME/.claude/multi-agent-refs/outside-the-pipeline.md` - absent on a host that
 installs no refs tree, in which case the summary below is the contract.