@mmerterden/multi-agent-pipeline 19.1.3 → 20.0.0

package/pipeline/multi-agent-refs/features/external-context-injection.md

@@ -7,6 +7,8 @@
 - [Log line shape](#log-line-shape)
 <!-- /toc -->
 
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
 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 and prepends the result to the analysis prompt under a **Referenced External Sources** section, so the agent doesn't re-discover what the ticket already pointed at.
 
 ```bash

package/pipeline/multi-agent-refs/features/review-delta.md

@@ -63,7 +63,7 @@ DELTA_JSON=$(node $HOME/.claude/scripts/review-delta.mjs --rounds-dir "$WORKTREE
 jq -c --argjson d "$DELTA_JSON" --argjson i "$((ITERATION-1))" \
   '{reviewIterations: (.reviewIterations | .[$i] += {delta: ($d + {computedAt: (now | todate)})})}' "$STATE_FILE" \
   | node $HOME/.claude/scripts/write-state.mjs "$STATE_FILE"
-$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 4 review.delta iteration=$ITERATION \
+$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 3 review.delta iteration=$ITERATION \
   new=$(jq '.counts.new // 0' <<< "$DELTA_JSON") still_present=$(jq '.counts.stillPresent // 0' <<< "$DELTA_JSON") \
   resolved=$(jq '.counts.resolved // 0' <<< "$DELTA_JSON") plateau=$(jq '.plateau // false' <<< "$DELTA_JSON") tripped=$([ "$DELTA_RC" -eq 3 ] && echo true || echo false)
 ```

package/pipeline/multi-agent-refs/features/review-multi-repo.md

@@ -57,9 +57,9 @@ And log `review.diff_truncated repo=<name> bytes_dropped=<N>`. Triage receives t
 
 **Telemetry**: Per-repo build/test gate timings + a single combined review/triage call set:
 ```bash
-$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 4 gate.build repo=common status=pass duration_ms=$D
-$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 4 gate.build repo=uicomponents status=pass duration_ms=$D
-$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 4 review.combined_diff repos=2 bytes=$BYTES truncated=false
+$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 3 gate.build repo=common status=pass duration_ms=$D
+$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 3 gate.build repo=uicomponents status=pass duration_ms=$D
+$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 3 review.combined_diff repos=2 bytes=$BYTES truncated=false
 ```
 
 ---

package/pipeline/multi-agent-refs/features/scope-check.md

@@ -1,6 +1,6 @@
 # Feature: Scope self-check (Phase 2 Step 3.7)
 
-**Pattern**: Phase 3 reconstructs everything from the diff. The one thing it cannot reconstruct is why each file was touched and what was left out on purpose, so Dev states both before the handoff, and a deterministic gate checks the statement against the real diff. The record also carries the code-simplifier rationales (Step 3.6) that used to be discarded, and it feeds two later consumers: the `<scope-self-check>` block in the Phase 3 reviewer prefix and the PR body in Phase 4.
+**Pattern**: Phase 3 reconstructs everything from the diff. The one thing it cannot reconstruct is why each file was touched and what was left out on purpose, so Dev states both before the handoff, and a deterministic gate checks the statement against the real diff. The record also carries the code-simplifier rationales (Step 3.6) that would otherwise be discarded, and it feeds two later consumers: the `<scope-self-check>` block in the Phase 3 reviewer prefix and the PR body in Phase 4.
 
 ## The record
 

package/pipeline/multi-agent-refs/features/skill-conformance.md

@@ -22,7 +22,7 @@ Phase 4 used to select its review criteria from `detectedStack`, a string Phase
 - The dev side and the review side could disagree about the standard without either noticing. A component built by a plugin skill was reviewed against `clean-code`.
 - "Did it do this correctly?" had no fixed denominator, so the only available answer was "it looks fine", and a reviewer that opened nothing produced the same output as a reviewer that checked everything.
 
-A Short run makes this sharper: it has no Phase 1 at all, so the sole input to the old selection logic was absent.
+The sharper case is a document whose evidence supported few sections: the sole input to the old selection logic was then nearly empty.
 
 ## The four rules that make it work
 

package/pipeline/multi-agent-refs/features/stack-skill-routing.md

@@ -41,7 +41,7 @@ Nothing enabled is not an error: a repo whose stack was never selected legitimat
 no toolkit. Record the no-op with the enabled set that was read, so "none applied" is
 distinguishable from "never looked".
 
-**Not enabled is not an error here**, unlike component dispatch: a repo whose stack was never selected legitimately has no toolkit, and halting would make the pipeline unusable there. Record the no-op and continue. (This paragraph used to say "a backend or web repo legitimately has no toolkit" - that stopped being true when the web and backend toolkits shipped, and the sentence outlived the fact by several releases.)
+**Not enabled is not an error here**, unlike component dispatch: a repo whose stack was never selected legitimately has no toolkit, and halting would make the pipeline unusable there. Record the no-op and continue. Every stack now has a toolkit, so "no toolkit" means the stack was never selected, not that none exists for it.
 
 Two marketplaces may ship the same toolkit name (a public one and a corporate one). Resolve whichever is enabled and record its **name and version** in the ledger entry, because the routing table and the skill set differ between versions  -  a finding that cites a skill has to be traceable to the version that defined it.
 

package/pipeline/multi-agent-refs/features/visual-evidence.md

@@ -123,7 +123,8 @@ section still renders, saying so.
 ## 3. After  -  Phase 2, not the Phase 3 user test
 
 The user test is the natural home: the simulator is already up. It is also **dropped by
-every `autopilot` and `--local` entry** (`phase-3-review.md` TLDR), so a capture
+every `autopilot` entry and by any run whose
+workspace is local** (`phase-3-review.md` TLDR), so a capture
 that lives only there produces nothing for unattended runs - which are exactly
 the runs where nobody watched the screen.
 

package/pipeline/multi-agent-refs/features/worktree-finalize.md

@@ -20,7 +20,7 @@ Removing it at PR-open is only safe because of the salvage, so the two are one s
 
 | Condition | Why it blocks |
 |---|---|
-| `worktreePath == projectRoot` (`--local` mode) | there is no worktree; removing it would delete the user's checkout |
+| `worktreePath == projectRoot` (local workspace) | there is no worktree; removing it would delete the user's checkout |
 | cwd is inside the worktree | a shell left on a deleted inode is worse than a leftover directory, and Phase 4 legitimately `cd`s into the worktree earlier |
 | not a registered worktree of the project root | a mistyped path must not delete an unrelated directory |
 | real uncommitted changes | never discarded; see the artefact carve-out below |

package/pipeline/multi-agent-refs/generate-issue.md

@@ -9,6 +9,8 @@
 
 > **TLDR**  -  Shared 12-step flow for `/multi-agent:create-jira`. Asks the issue type (Task / Bug / Story), mines the target project's existing same-type issues to learn team conventions, detects the active sprint, drafts a standards-compliant issue from a fixed standard template with auto-sizing sections, asks the user about every genuinely unknown field, renders a full preview, and creates the Jira issue only after explicit approval. Creates exactly one Jira issue per run  -  no branches, no commits, no worktrees.
 
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
 Consumed by `create-jira/SKILL.md`. This ref is never invoked directly.
 
 ## Hard rules (must not regress)

package/pipeline/multi-agent-refs/issue-jira-triad.md

@@ -9,6 +9,8 @@
 - [Cross-CLI parity](#cross-cli-parity)
 <!-- /toc -->
 
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
 > **TLDR**  -  When a GitHub issue triggers the pipeline and has no Jira ID, the `autoJiraFromGithubIssue` policy decides whether to auto-create a Jira task (and patch the GitHub issue body with the new Jira link). Phase 5 then posts a humanizer'd wiki-content summary back as a Jira comment, closing the loop. Autopilot treats `ask` as `always`.
 
 This doc is referenced from `$HOME/.claude/multi-agent-refs/phases/phase-0-init.md` Step 1 (GitHub issue input) and `$HOME/.claude/multi-agent-refs/phases/phase-5-report.md` Step 2 (component wiki). Keeps the phase docs tight and gives the triad contract a stable home.

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

@@ -1,5 +1,7 @@
 ## Keychain Token Registry
 
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
 Tokens live in the platform-native credential store (macOS Keychain / Linux libsecret / Windows Credential Manager). Key names are resolved via **preferences mapping**  -  never hardcoded.
 
 ### Rule 1  -  Never prompt for a token *value* mid-run

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

@@ -49,13 +49,6 @@ Each task teaches the project a bit more. Token cost decreases over time.
 
 They all complement each other  -  no conflicts.
 
-### Knowledge in a Short run
-
-A Short run skips Phase 1, but knowledge **is still read**:
-
-- Knowledge files are added to the prompt before the Opus agent starts in Phase 3
-- Knowledge capture is still performed in Phase 5 (simplified report)
-
 ### Knowledge Maintenance
 
 Knowledge files grow over time. Maintenance rules:

package/pipeline/multi-agent-refs/outside-the-pipeline.md

@@ -47,7 +47,7 @@ and a review between fetch and action; an ordinary session has neither.
 | Read an issue, page, log, crash, scan result | Resolve the credential and fetch |
 | Comment on Jira, edit an issue, move a board column | `/multi-agent:channels` |
 | Create an issue | `/multi-agent:create-jira` |
-| Open or update a PR | a pipeline run, or `/multi-agent:resume-local` |
+| Open or update a PR | a pipeline run, or `/multi-agent:resume` |
 
 The split is not bureaucracy. Outward writes carry rules that live in those commands:
 issues are never auto-closed (four approvals), PR bodies use `Ref:` and never

package/pipeline/multi-agent-refs/payload-contracts.md

@@ -64,4 +64,4 @@ Non-empty `UNTRACKED` → both the agent-log report and the closing chat summary
 
 ## Fast modes are not exempt
 
-A Short run skips Analysis and Planning, and the autopilot and local entries skip the interactive test gate. They run Phase 4 and Phase 5 **unchanged**. A short pipeline is not a licence for an improvised payload shape, a missing Test Scenarios section, or a report without numbers.
+The autopilot and local entries skip the interactive test gate. They run Phase 4 and Phase 5 **unchanged**. A short pipeline is not a licence for an improvised payload shape, a missing Test Scenarios section, or a report without numbers.

package/pipeline/multi-agent-refs/phases/modes.md

@@ -1,18 +1,16 @@
-> **TLDR**  -  four entry commands, two axes, and depth is no longer one of them:
+> **TLDR**  -  four entry commands, one pipeline, two axes:
 >
-> - **Depth** is a picker, not a flag. Phase 0 Step 7.5 asks Full or Short and sets `state.onlyDevelop`. Short strips to Init → Dev(Opus self-contained) → Review → Test → Commit → Report. Review is never stripped.
-> - **`autopilot`** skips confirmations (Plan, Test, Commit, PR prompts) and therefore skips the depth question too, always running Full. Still fails safe on review blockers and build retries.
-> - **`--local`** means no worktree: work happens in `$PROJECT_ROOT` on a local branch.
+> - **`autopilot`** skips confirmations (Plan, Test, Commit, PR prompts). Still fails safe on review blockers and build retries.
+> - **Workspace** is the one question the run asks about its own shape: a worktree, or the project root on a local branch. Phase 0 Step 5b asks it; autopilot resolves it to a worktree and never asks.
 >
-> Fastest path is `/multi-agent:local` then Short. There is no fast-and-unattended combination any more, and that is deliberate  -  see "Pipeline depth".
+> There is one pipeline and every mode runs its whole phase set. What a run costs follows the evidence the task carries, not an answer taken before the evidence exists.
 
 ## Autopilot Mode
 
 <!-- toc -->
 - [Autopilot Mode](#autopilot-mode)
-- [Pipeline depth (Full / Short)](#pipeline-depth-full-short)
 - [Analysis Mode (`/multi-agent:analysis`)](#analysis-mode-multi-agentanalysis)
-- [Local Mode (`--local`)](#local-mode---local)
+- [Local Mode](#local-mode)
 <!-- /toc -->
 
 Autopilot mode skips interactive confirmations and runs the pipeline end-to-end autonomously.
@@ -27,15 +25,19 @@ Autopilot mode skips interactive confirmations and runs the pipeline end-to-end
 /multi-agent "LoginView dark mode fix" autopilot
 ```
 
-**What changes in autopilot (Tablo 1  -  Full pipeline modes):**
+**What changes in autopilot (Tablo 1)**
 
-| Phase               | Normal (full)                                           | autopilot (full)                            | local (full)                                | local autopilot (full)                      |
-| ------------------- | ------------------------------------------------------- | ------------------------------------------- | ------------------------------------------- | ------------------------------------------- |
-| Phase 1 (Plan Approval Gate) | Clarification (max 2 rounds) + approval loop  -  user: approve/abort/free-text edit | **Gate skip**  -  log the plan, proceed directly to Phase 2 (autopilot contract: zero interaction) | Same as Normal | Same as autopilot |
-| Phase 3 (User Test) | Interactive prompt ("Want to test?" -> wait)            | Skip (autopilot suppresses interactive prompts) -> proceed directly to Phase 4 | **Not in the phase set** (the gate checks the change out of a worktree; local has none) | Not in the phase set |
-| Phase 4 (Commit)    | "Want to commit?" -> wait                               | Auto commit + push                          | "Want to commit?" -> wait                   | Auto commit + push                          |
-| Phase 4 (PR)        | "Want to open a PR?" -> wait                            | Auto create PR                              | "Want to open a PR?" -> wait                | Auto create PR                              |
-| **Phase 5 (Channels)**  | Multi-select channel + content menu                 | **STILL PAUSES**  -  see "Phase 5 autopilot exception" below | Multi-select (same as Normal) | **STILL PAUSES** (same as autopilot) |
+Two axes, and only the first is a command: whether anything is confirmed
+(`autopilot`), and where the work happens (the Step 5b answer). An autopilot run
+always gets a worktree, so there is no unattended-local column.
+
+| Phase | Interactive, worktree | Interactive, local | autopilot (always worktree) |
+| --- | --- | --- | --- |
+| Phase 1 (Plan Approval Gate) | Clarification (max 2 rounds) + approval loop  -  user: approve/abort/free-text edit | Same as worktree | **Gate skip**  -  log the plan, proceed directly to Phase 2 (autopilot contract: zero interaction) |
+| Phase 3 (User Test step) | Interactive prompt ("Want to test?" -> wait) | **Not offered**  -  the step checks the change out of a worktree and there is none; the phase itself still runs | Skip (autopilot suppresses interactive prompts) -> proceed directly to Phase 4 |
+| Phase 4 (Commit) | "Want to commit?" -> wait | "Want to commit?" -> wait | Auto commit + push |
+| Phase 4 (PR) | "Want to open a PR?" -> wait | "Want to open a PR?" -> wait | Auto create PR |
+| **Phase 5 (Channels)** | Multi-select channel + content menu | Multi-select (same) | **STILL PAUSES**  -  see "Phase 5 autopilot exception" |
 
 **What NEVER skips (even in autopilot):**
 
@@ -51,7 +53,7 @@ Autopilot mode skips interactive confirmations and runs the pipeline end-to-end
 
 The generic "zero-interaction" contract covers Phases 0-4 only. Phase 5 channels dispatch is the **single exception**:
 
-- ALL modes (`autopilot`, `--local autopilot`, and a Short run reaching Phase 5) pause at the channels multi-select menu.
+- ALL modes, `autopilot` included, pause at the channels multi-select menu.
 - Menu pre-ticks from `prefs.global.reportChannels` + `prefs.global.reportContent`  -  user can accept with one keypress if prefs are stable.
 - **30-minute timeout**  -  if user does not respond, session ends cleanly:
   - External delivery aborted (no silent apply  -  prevents accidental Jira comments / Confluence pages).
@@ -62,79 +64,9 @@ The generic "zero-interaction" contract covers Phases 0-4 only. Phase 5 channels
 
 Full contract: `$HOME/.claude/multi-agent-refs/phases/phase-5-report.md` (Autopilot pause contract) + `commands/multi-agent/channels/SKILL.md`.
 
----
-
-## Pipeline depth (Full / Short)
-
-Short strips the pipeline to what an already-scoped task needs: no deep analysis, no planning phase. The **Opus** dev agent reads the task scope and implements, and Phase 3 then reviews what it produced. Review is deliberately NOT part of the strip: analysis and planning shape work that has not happened yet, so a task the user has already scoped can skip them, while review judges work that now exists and has no substitute.
-
-**How it is chosen.** Phase 0 Step 7.5, after `taskType` is known:
-
-```
-Bu is icin hangi pipeline? / Which pipeline for this task?
-  1. Tam / Full    Analysis -> Plan -> Dev -> Review -> Test -> Commit -> Report
-  2. Kisa / Short  Dev (self-contained, Opus) -> Review -> Test -> Commit -> Report
-```
-
-`bugfix` and `chore` recommend Short; `feature`, `refactor` and `component` recommend Full. The recommendation is presented first and passed as `ASK_CHOICE_DEFAULT` on hosts without a native picker, because `ask-choice.sh` picks the first option on a non-TTY and option order is not a contract. Pass it as the **1-based index** (Full = 1, Short = 2), not as the label: labels render in `outputLanguage`, so a label-valued default matches nothing on a `tr` run.
-
-**Who is asked.** `/multi-agent` and `/multi-agent:local`. Both autopilot entries always run Full without asking.
-
-**Why there is no fast-and-unattended combination.** It existed until v16.0.0, and removing it was a real behaviour change, not a rename. Autopilot may not ask, so something has to choose, and unattended is the worst place to drop analysis and planning: nobody is watching to notice what the shortcut lost. A cron job or script that wants both now has to pick - stay unattended and pay for the full pipeline, or stay fast and have a person present.
-
-**Pipeline in a Short run:**
-
-```
-Phase 0: Init -> Phase 2: Dev (self-contained) -> Phase 3: Review -> Phase 3: Review (user test) -> Phase 4: Commit -> Phase 5: Report
-```
-
-**What changes (Tablo 2  -  Short runs):**
-
-| Phase               | Full                                            | Short                                                                              | Short + `--local`                             |
-| ------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------- |
-| Phase 0 (Init)      | Full setup                                      | Same  -  worktree, branch, state, and the depth question itself                      | Same  -  no worktree, branch on `$PROJECT_ROOT` |
-| Phase 1 (Analysis)  | Parallel Explore agents + analysis document     | **SKIP**  -  no tile is ever drawn for it (registration is deferred to Step 7.5)     | **SKIP**                                      |
-| Phase 1 (Planning)  | TaskCreate + architecture review + **Plan Approval Gate** | **SKIP** (no plan means no plan gate)                                    | **SKIP**                                      |
-| Phase 2 (Dev)       | Follows the Phase 1 plan, TDD cycle (Sonnet)    | **Self-contained** (Opus): agent scans relevant files, implements with TDD, builds | Same, on the local branch                     |
-| Phase 3 (Review)    | Parallel review + Fable triage (3 reviewers on every host: Claude Code Fable + Opus + Sonnet, Copilot GPT-5.4 + Opus + Sonnet) | **Same**  -  gates, parallel review, triage; blocking findings return to Phase 2 (cap 3) | **Same**, on the local branch diff |
-| Phase 3 (User Test) | Interactive prompt                              | **Interactive prompt**                                                             | Not in the set  -  no worktree to check out    |
-| Phase 4 (Commit)    | Commit + PR                                     | Same  -  still asks                                                                  | Same                                          |
-| Phase 5 (Report)    | Full report + channels multi-select             | Simplified  -  no analysis section, review section IS present, channels menu still pauses | Same                              |
-
-**Phase 2 in a Short run (self-contained):**
-
-The **Opus** agent receives the task description (from Jira, GitHub issue, or free-text) and:
-
-1. Quickly scans relevant files in the codebase (lightweight, not full Explore)
-2. Implements the change following TDD cycle (test -> code -> build)
-3. Runs build verification (max 3 retries on failure)
-
-No separate task breakdown  -  the agent handles scope autonomously.
-
-**State tracking**: `agent-state.json` gets `"onlyDevelop": true`. The tracker boots at Step -1 with Phase 0 alone and the rest of the tiles are registered at Step 7.5, once this answer says which phases the run actually has - so a Short run never draws an Analysis tile it will not use. Full contract: `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "Deferred registration".
-
-### Intake warnings for a Short run
-
-**An analysis document was supplied.** Because Phase 1 and Phase 1 are skipped, no phase turns that document into a task breakdown. The doc becomes raw context for one Dev pass, and work comes out ordered by whatever the model read first: the bottom of the dependency chain lands, the screen wiring does not.
-
-The depth picker is where this is caught. When the intake carried an analysis document or a Figma reference, say so in the question itself rather than after the choice:
-
-```
-This task carries an analysis document. Short skips Analysis and Planning, so
-the document will not be turned into a task breakdown.
-  1. Tam / Full    (recommended here)
-  2. Kisa / Short  (doc as context only)
-```
-
-Autopilot never sees this: it runs Full.
-
-**The branch already carries the work.** When the change was developed outside the pipeline, or by hand, Short is still the wrong entry point: it will try to develop again. `/multi-agent:resume-local` puts the existing diff through the same review, adds a build+test success gate, opens the PR, and posts the Jira technical-analysis + test-scenario comment  -  without re-developing. Offer it when the working tree or branch is already ahead of the base with the task's changes.
-
----
-
 ## Analysis Mode (`/multi-agent:analysis`)
 
-Not a depth permutation - a different **output kind**. It produces the analysis document and stops; no code, no branch, no PR. The 6-phase contract holds, with four phases reinterpreted the same way a Short run reinterprets Phase 2.
+A different **output kind**, not a shorter pipeline. It produces the analysis document and stops; no code, no branch, no PR. The 6-phase contract holds, with four phases reinterpreted the same way a Short run reinterprets Phase 2.
 
 ```
 Phase 0: Init -> Phase 1: Plan (analysis) -> Phase 1: Plan -> Phase 3: Review -> Phase 4: Publish -> Phase 5: Report
@@ -151,18 +83,19 @@ Phase 0: Init -> Phase 1: Plan (analysis) -> Phase 1: Plan -> Phase 3: Review ->
 | 6 Commit | **Publish** instead: Local file / Confluence / Jira. Locked 6 still forbids `git add` and `git commit` |
 | 7 Report | Channels, same as every mode |
 
-**No `local` or `autopilot` variant.** Worktree isolation buys nothing when no code is written, and the intake, the Pass B convention preview and the open-question resolution are interactive by nature; a zero-interaction analysis would be a document nobody agreed to.
+**No `autopilot` variant.** Worktree isolation buys nothing when no code is written, and the intake, the Pass B convention preview and the open-question resolution are interactive by nature; a zero-interaction analysis would be a document nobody agreed to.
 
 **Where the document lands.** Drafts go to `/tmp/analysis-<slug>-<ts>/` first, then the Phase 4 picker decides: Local writes `<repo>/analysis/<feature>-<platform>.md` uncommitted, Confluence posts the page, Jira updates the description. In the full pipeline the same engine writes into the worktree instead and `prefs.global.analysisPhase.commitDoc` decides whether it rides along with the commit.
 
 ---
 
-## Local Mode (`--local`)
+## Local Mode
 
 Local mode skips worktree creation  -  works directly on a local branch in the project root. Useful for single-task workflows or when worktrees cause issues.
 
-**Activation**: answer the Phase 0 Step 5b workspace question, or state it up
-front so the question resolves without being asked.
+**Activation**: answer the Phase 0 Step 5b workspace question. There is no flag
+and no command name for it - the answer is the only way in, which is why the
+question carries what the choice costs.
 
 ```
 Bu is nerede kossun? / Where should this task run?
@@ -171,25 +104,16 @@ Bu is nerede kossun? / Where should this task run?
 ```
 
 Two genuine options, so it meets the two-option floor in `picker-contract.md` on
-its own. **Say what local costs inside the question**: Phase 3 is not in a local
-run's set (the user-test gate checks the change out of a worktree, and there is
-none), and uncommitted work in the project root is in the way of the checkout. A
-user choosing local should learn both before choosing, not after.
-
-The ways to state it up front:
-
-```
-/multi-agent:local "PROJ-12345"
-/multi-agent:local "#316"
-/multi-agent:local "LoginView dark mode fix"
-/multi-agent:local-autopilot "PROJ-12345"
-/multi-agent "PROJ-12345" --local
-```
+its own. **Say what local costs inside the question**: the user-test STEP inside
+Phase 3 checks the change out of a worktree, so a local run does not get that
+offer (the phase itself still runs), and uncommitted work in the project root is
+in the way of the checkout. A user choosing local should learn both before
+choosing, not after.
 
 Every autopilot entry resolves this to **worktree** and never asks. That is not a
 skipped question: an unattended run commits and pushes from wherever it stands,
-and doing that in the user's own checkout is what worktrees exist to prevent.
-`:local-autopilot` is the explicit opt-out.
+and doing that in the user's own checkout is what worktrees exist to prevent. An
+unattended run therefore always gets its own checkout.
 
 **What changes in local mode:**
 
@@ -221,4 +145,4 @@ git -C $PROJECT_ROOT config user.email "{identity.email}"
 - Uncommitted changes in PROJECT_ROOT may conflict  -  pipeline warns if dirty
 - Build queue lock still applies for xcodebuild
 
-**Combinable**: `/multi-agent:local-autopilot` is the no-worktree unattended path; `/multi-agent:local` then Short is the no-worktree fast path.
+Fast path.

package/pipeline/multi-agent-refs/phases/operations.md

@@ -17,6 +17,8 @@
 - [Phase Pipeline](#phase-pipeline)
 <!-- /toc -->
 
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
 Every task gets an auto-incremented short ID. Counter stored at `$HOME/.claude/logs/multi-agent/{project}/.counter` (persists across sessions).
 
 ```
@@ -176,7 +178,7 @@ This keeps orchestrator context lean and enables programmatic routing.
   bash $HOME/.claude/scripts/capture-flush.sh --state "$STATE_FILE" --quiet
   ```
 
-  The durable stores used to be written only in Phase 5, which is the phase a run is LEAST likely to reach: a run killed in Phase 2 threw away every finding it had established, and the next run on the same repo paid to rediscover it. The flush is idempotent (the second call through writes 0 rows), costs no API tokens, calls no model, and never fails the transition. Phase 5 is now the LAST flush rather than the only one. The trigger is deliberately mechanical - a phase transition, not a model noticing that a moment qualifies.
+  The durable stores are NOT written only in Phase 5, which is the phase a run is LEAST likely to reach: a run killed in Phase 2 threw away every finding it had established, and the next run on the same repo paid to rediscover it. The flush is idempotent (the second call through writes 0 rows), costs no API tokens, calls no model, and never fails the transition. Phase 5 is now the LAST flush rather than the only one. The trigger is deliberately mechanical - a phase transition, not a model noticing that a moment qualifies.
 - *Compaction trigger.* If conversation context exceeds ~50%, run `/compact` preserving "modified files, plan, open review findings, current phase + sub-step" before continuing. Don't wait for auto-compaction near the limit  -  it triggers exactly when context is worst and is lossy. After compaction, re-read `agent-state.json` AND the latest `## Handoff` block in `agent-log.md` to re-ground.
 
 **Handoff block (v10.8.0)**: the structured artifact the phase-boundary checkpoint appends to `agent-log.md`. Written by the orchestrator from state it already holds  -  no agent dispatch, no extra LLM call. Cap at ~15 lines; the latest block is authoritative (earlier ones are history). This is the fresh-context re-entry contract: a resume or post-compaction session rebuilds working context from the latest handoff + `agent-state.json` + git log, never from conversation memory.

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

@@ -14,23 +14,21 @@ $HOME/.claude/scripts/phase-tracker.sh tiles
 $HOME/.claude/scripts/phase-tracker.sh update 0 in_progress
 ```
 
-**Phase 0 only.** `/multi-agent` and `:local` do not know their phase set yet -
-depth decides it, and depth is Step 7.5 - so they register the rest there rather
-than drawing eight tiles the user has not chosen. Every other mode registers its
-whole set here, in phase-number order. Contract: `tracker-contract.md`,
-"Deferred registration".
+**Every mode registers its whole set here**, in phase-number order. The phase
+set is known at Phase 0 because there is one pipeline: no answer later in the
+run can add or remove a phase. Contract: `tracker-contract.md`.
 
 `tiles` prints this host's widget-registration calls: **make them before continuing.** The card alone lands in collapsed tool output, so a run that skips them runs in silence. Contract: `tracker-contract.md`, "The card is not the widget".
 
 If `INPUT_TASK_ID` isn't known yet (free-text, project not selected), use a placeholder; rename later via `mv` once parsed in Step 1.
 
-Every subsequent phase (1-7) MUST call `phase-tracker.sh update <N> in_progress` on entry and `phase-tracker.sh update <N> completed|failed|skipped` on exit. Each `update` prints a `-- NEXT (required) --` block: act on it. Sub-phase milestones use `phase-tracker.sh sub <N> <subN> "<name>" <status>`. See `$HOME/.claude/multi-agent-refs/phases.md` "Visual Phase Tracker" for the full contract.
+Every subsequent phase (1-5) MUST call `phase-tracker.sh update <N> in_progress` on entry and `phase-tracker.sh update <N> completed|failed|skipped` on exit. Each `update` prints a `-- NEXT (required) --` block: act on it. Sub-phase milestones use `phase-tracker.sh sub <N> <subN> "<name>" <status>`. See `$HOME/.claude/multi-agent-refs/phases.md` "Visual Phase Tracker" for the full contract.
 
-`update <N> completed` **exits 3** for phases 1-4 with no recorded spend: record `model` + `tokens`, or pass `--no-llm`, then re-run it. Contract: `tracker-contract.md`, "Accounting is a gate".
+`update <N> completed` **exits 3** for phases 1-5 with no recorded spend: record `model` + `tokens`, or pass `--no-llm`, then re-run it. Contract: `tracker-contract.md`, "Accounting is a gate".
 
 ##### TaskCreate ordering on Claude Code (strict)
 
-On Claude Code, fire every `TaskCreate` in a registration batch in strict phase-number order BEFORE any `TaskUpdate` in that batch - which is the order `tiles` prints them in - and never register a phase whose number is below one already registered. A deferred batch (Step 7.5) therefore appends, it does not interleave. Full contract: `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
+On Claude Code, fire every `TaskCreate` in a registration batch in strict phase-number order BEFORE any `TaskUpdate` in that batch - which is the order `tiles` prints them in - and never register a phase whose number is below one already registered. Full contract: `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
 
 ---
 
@@ -46,6 +44,13 @@ OUTPUT_LANG=$(jq -r '.global.outputLanguage // "en"' "$PREFS_FILE" 2>/dev/null |
 
 From this point on, everything the user reads renders in `$OUTPUT_LANG`: conversational lines, `AskUserQuestion` `question`/`label`/`description`, and external payload bodies (PR/Jira/Confluence). English stays only on `header`, commit messages, branch names, PR title prefixes, identifiers. Full matrix: `rules.md` "Language Application".
 
+**Every picker in this phase prints its breadcrumb.** Phase 0 is one chain -
+account, repos, base branch, maturity, dev-context, workspace - and each step
+emits the narrator line `<localized: "Step i/n: what this step decides">` above
+its question, per `picker-contract.md` "Step narration". A step that resolves
+without asking (one account, no siblings) still prints its line with the
+resolution noted, so the numbering reads continuously instead of jumping.
+
 **Model tier resolution** (same step, once per run): read `prefs.global.modelFallback`. If `fableEnabled` is `false`, every `preferredModel: fable` persona resolves to `opus` for this run and the Phase 3 Claude Code panel is 2 reviewers, not 3; print the one-line INFO. Then, if `premiumTierUntil` is set and in the past, apply the date-gate trigger - `preferredModel` personas dispatch on `fallbackModel`, with the one-line WARN. Both lines and the exact ordering: `$HOME/.claude/multi-agent-refs/features/model-fallback.md`. Dispatch-error and budget triggers 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:
@@ -323,8 +328,7 @@ above, recorded as `baseBranchSource: "input"`. Everything else asks, and
 One row is a normal outcome of the rule-5 filter and is **still asked**, with a
 real second option - `picker-contract.md`, "Two options or it is not a question".
 
-This holds in every mode. A Short run skips the *LLM* phases (Analysis, Planning); it
-does not skip Phase 0's pickers. Autopilot resolves them without prompting, which still
+This holds in every mode. Autopilot resolves them without prompting, which still
 writes the fields; its base-branch resolution order is in `features/base-branch-evidence.md`.
 
 **TTL filter for recent branches**:
@@ -412,11 +416,11 @@ Branch name is deterministic  -  no user confirmation needed.
 #### Step 5b  -  Workspace (worktree or local)
 
 Ask where the branch lives - the wording, the two options and what local costs
-are in `modes.md`, "Local Mode". Here because Step 4 named the branch, Step 6b
-acts on the answer, and Step 7.5 needs the phase set it implies.
+are in `modes.md`, "Local Mode". Here because Step 4 named the branch and Step
+6b acts on the answer.
 
-**Who is asked.** `/multi-agent` only (`workspaceSource: "asked"`). `:local` and
-`--local` state it up front (`command`).
+**Who is asked.** Every interactive entry (`workspaceSource: "asked"`). There is
+no flag and no command name that pre-answers it.
 Every autopilot entry resolves it to a worktree and never asks (`autopilot`).
 
 **Persist** `state.localMode` (semantics unchanged) and `state.workspaceSource`,
@@ -448,7 +452,7 @@ Log: `Identity: {identity.name} <{identity.email}>`
 
 1. `git -C $PROJECT_ROOT fetch origin`
 
-**If local** (Step 5b answered local, by question, by `:local` / `--local`):
+**If local** (Step 5b answered local):
 
 ```bash
 if [ -n "$(git -C $PROJECT_ROOT status --porcelain)" ]; then
@@ -464,7 +468,7 @@ git -C $PROJECT_ROOT config user.email "{identity.email}"
 
 **If worktree** (Step 5b answered worktree, or autopilot resolved it): 2. Worktree path: Jira → `.worktrees/{jiraId}/`, GitHub → `.worktrees/GH{issueNo}/`, free-text → `.worktrees/task-{shortId}/` 3. **Heal stale admin state first** (see "Worktree stale-lock heal" below) and **apply the residue guard** (see "Worktree residue guard" below), then `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` at `$HOME/.claude/logs/multi-agent/{project}/{task-id}/`, never inside the worktree:
 
-**Worktree location convention (cited by every other command):** always `{projectRoot}/.worktrees/{taskId}`, inside the repo, never under `$HOME`. `{taskId}` is the directory name from the rule above (`DC-<shortId>` for `/multi-agent:design-check`). `.worktrees` is fixed, not a preference: no `worktreeBasePath` key exists, and `gc-worktrees.sh`, `purge.sh`, the cost renderers and `usage-report.mjs` resolve `<repo>/.worktrees/` by name. Multi-repo tasks get one worktree per repo (the loop below); `--local` creates none and `worktreePath` is `$PROJECT_ROOT`.
+**Worktree location convention (cited by every other command):** always `{projectRoot}/.worktrees/{taskId}`, inside the repo, never under `$HOME`. `{taskId}` is the directory name from the rule above (`DC-<shortId>` for `/multi-agent:design-check`). `.worktrees` is fixed, not a preference: no `worktreeBasePath` key exists, and `gc-worktrees.sh`, `purge.sh`, the cost renderers and `usage-report.mjs` resolve `<repo>/.worktrees/` by name. Multi-repo tasks get one worktree per repo (the loop below); a local answer creates none and `worktreePath` is `$PROJECT_ROOT`.
 
 **Worktree stale-lock heal (required before every `worktree add`):** a run killed mid-`worktree add` (OOM, SIGTERM, disk full) leaves a locked or broken admin entry under `.git/worktrees/{id}/`, so the retry fails with `fatal: '<path>' already exists`. Always run the heal first  -  it is a no-op on a clean repo:
 
@@ -584,30 +588,6 @@ Persist: `"taskType": "component" | "bugfix" | "feature" | "refactor" | "chore"`
 
 Log: `Phase 0 Step 7: taskType = {component|bugfix|feature|refactor|chore}`
 
-#### Step 7.5  -  Pipeline depth (Full / Short)
-
-Ask the depth question from `$HOME/.claude/multi-agent-refs/phases/modes.md` "Pipeline depth" - it carries the wording, the per-`taskType` recommendation and the mode tables. Here because the recommendation needs `taskType` (Step 7), which needs the fetched issue (Step 1) and the branch (Step 3).
-
-**Who is asked.** `/multi-agent` and `/multi-agent:local` only. Both autopilot entries and analysis mode skip it; autopilot always runs Full.
-
-When the intake carried an analysis document or a Figma reference, say so **inside** the question: Short skips the only two phases that would turn that document into a task breakdown, and the user should learn that before choosing, not after.
-
-**Pass the default as a 1-based index, never a label.** `ask-choice.sh` takes the first option on a non-TTY, and a label-valued default matches nothing once the options render in `outputLanguage`. Reasoning: `modes.md`, "Pipeline depth".
-
-```bash
-# Full is option 1, Short is option 2 (modes.md "Pipeline depth")
-DEPTH_DEFAULT_INDEX=1; [ "$DEPTH_RECOMMENDATION" = "short" ] && DEPTH_DEFAULT_INDEX=2
-ASK_CHOICE_DEFAULT="$DEPTH_DEFAULT_INDEX" \
-  $HOME/.claude/lib/ask-choice.sh "<localized: 'Which pipeline for this task?'>" \
-  "<localized: 'Full'>" "<localized: 'Short'>"
-```
-
-**Persist.** Short sets `state.onlyDevelop = true`; Full leaves it `false`. The key is unchanged - only who sets it changed - so every downstream reader keeps working.
-
-**Now register the rest of the widget.** This answer is the first moment the phase set is known, so the remaining tiles are created here and not before - Full `1 2 3 4 5 6 7`, Short `3 4 5 6 7`, `:local` dropping 5 from either. `add` each, then `phase-tracker.sh tiles --new`, which emits TaskCreate only for phases that carry no tile yet. Contract: `tracker-contract.md`, "Deferred registration".
-
-Log: `Phase 0 Step 7.5: depth = {full|short} (recommended {full|short}, source {user|autopilot|default})`
-
 #### Step 7.6  -  Test baseline (opt-in, `prefs.global.testBaseline.enabled`, default `false`)
 
 Phase 3 Gate 3 cannot tell an inherited red suite from one this run broke, so it blocks on someone else's bug or the agent "fixes" tests it never touched. Runs after Step 6, only when the stack has a test command; skipped in analysis mode.
@@ -644,7 +624,8 @@ Persist that file as `state.evidenceCapability`, then build the menu from it, ne
 
 A closed option keeps its row and prints the probe's reason verbatim. No `uiTestTargets` closes 2; `mcp` false closes 3; a missing `device` or `recorder` closes both. Targets present with no `matchingTests` leaves 2 open, warning that the whole UI suite will run. **When only option 1 is open, do not ask**: `testDepth = unit`, `testDepthSource = forced`, and the tier 3 gap is written.
 
-Default as a 1-based index, never a label - same rule and same reason as Step 7.5:
+Default as a 1-based index, never a label: `ask-choice.sh` takes the first
+option on a non-TTY, so a label-valued default silently becomes option 1.
 
 ```bash
 DEPTH_DEFAULT_INDEX=1
@@ -653,7 +634,7 @@ DEPTH_DEFAULT_INDEX=1
 ASK_CHOICE_DEFAULT="$DEPTH_DEFAULT_INDEX" $HOME/.claude/lib/ask-choice.sh ...
 ```
 
-Asked by `/multi-agent` and `:local`; autopilot reads `prefs.global.testDepth.default` and degrades to the best open option. Asked here, not Phase 3, which four of the eight modes drop.
+Asked by every interactive entry; autopilot reads `prefs.global.testDepth.default` and degrades to the best open option. Asked here, not Phase 3, which four of the eight modes drop.
 
 Log: `Phase 0 Step 7.7: testDepth = {unit|unit+ui|unit+mcp} (source {user|autopilot|default|forced}), tier1/tier2 = {open|closed}`
 

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

@@ -1,6 +1,8 @@
 ### Phase 1: Plan (Opus)
 
-> **TLDR**  -  One phase, two halves. First the codebase is explored and the analysis document written (the design contract the rest of the run reads); then that document is decomposed into concrete tasks with file-level targets, risk grading and architecture review. The phase ends at the **Plan Approval Gate**: in normal mode the orchestrator asks structured clarification questions when scope is ambiguous (max 2 rounds), renders the plan, and loops on free-text edits until the user approves or aborts. The gate is **skipped entirely** for a Short run and for `autopilot`. Analysis and planning were Phases 1 and 2 until v19.0.0; the depth picker already skipped them as one unit (`state.onlyDevelop`), which is why they are one phase now.
+> **TLDR**  -  One phase, two halves. First the codebase is explored and the analysis document written (the design contract the rest of the run reads); then that document is decomposed into concrete tasks with file-level targets, risk grading and architecture review. The phase ends at the **Plan Approval Gate**: in normal mode the orchestrator asks structured clarification questions when scope is ambiguous (max 2 rounds), renders the plan, and loops on free-text edits until the user approves or aborts. The gate is **skipped entirely** for `autopilot`, which has no one to ask.
+
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
 
 <!-- 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.
@@ -412,9 +414,9 @@ and stored, only invisible.
 printf '%s' "$PLAN_JSON" | bash "$HOME/.claude/lib/plan-todos.sh" set "$TASK_ID" -
 ```
 
-`set` accepts a planning-output document and converts it itself. The conversion
-used to be written out here, which made the `tasks[]`-to-`todos[]` mapping a
-thing two files defined, and this was the copy nothing tested.
+`set` accepts a planning-output document and converts it itself. Writing the
+conversion out here too would make the `tasks[]`-to-`todos[]` mapping a thing two
+files define, and the copy in prose is the one nothing tests.
 
 Phase 2 (Dev) then iterates with `plan-todos.sh next "$TASK_ID"` until empty, calling `start` before each step and `complete` (with notes) or `fail`/`skip` after. Phase 3 (Review) reads the Todo list to verify all `completed` items map to diff hunks. Phase 5 (Report) renders `list` into the agent-log + PR body.
 
@@ -441,10 +443,6 @@ Log: "Phase 1: Consistency  -  requirements:{N/N mapped} anchors:{ok|M unanchore
 - `state.autopilot === true` (autopilot contract: zero interaction)
 - Autopilot safety classifier returns `recommendPause: false` (see Step 5c below)
 
-OR:
-
-- `state.onlyDevelop === true` (Short pipeline: direct to Phase 2, no plan)
-
 In the skipped case, log `🧠 Phase 1: Plan  -  gate skipped ({mode}), proceeding to Phase 2` and go to Phase 2.
 
 ##### 5c  -  Autopilot safety classifier (runs before 5a/5b skip decision)
@@ -571,9 +569,8 @@ The pipeline shapes interact with the gate as follows. This table is the source
 
 | Mode | Clarification | Approval Loop | Safety Classifier | Notes |
 |---|---|---|---|---|
-| Full, interactive (`/multi-agent`, `:local`) | ✅ (max 2 rounds) | ✅ |  -  (redundant when a human approves) | Full gate |
-| Short (depth picker answered Short) | ❌ | ❌ |  -  | Phase 1-2 skipped at Step 7.5; Phase 2 starts immediately |
-| `autopilot`, `:local-autopilot` | ❌ | ❌ conditional | ✅ (if `autopilotSafetyGate !== false`) | Always Full, so a plan exists. Safe plans proceed silently; high-risk plans trigger a one-time manual approval. Log records the score. |
+| Interactive (`/multi-agent`) | ✅ (max 2 rounds) | ✅ |  -  (redundant when a human approves) | Full gate |
+| `/multi-agent:autopilot` | ❌ | ❌ conditional | ✅ (if `autopilotSafetyGate !== false`) | A plan always exists. Safe plans proceed silently; high-risk plans trigger a one-time manual approval. Log records the score. |
 
 **Why autopilot now has an escape hatch:** the old "zero interaction  -  fully trust the scope" contract held well for tightly-scoped batch workflows (figma component iteration over known-safe components) but broke in edge cases  -  schema migrations auto-merging, security-path drift going silent, delete-without-test sprawls. The safety classifier (Step 5c) is opt-out so the default protects against the edge-case cost; users running known-safe workflows can flip `prefs.global.autopilotSafetyGate = false` to restore pre-v7.0 behavior.
 
@@ -582,18 +579,10 @@ The pipeline shapes interact with the gate as follows. This table is the source
 After plan generation (and after each edit-loop iteration), forward the planning model's call totals so Phase 5's Cost Breakdown captures Phase 1 (`model=` names the rung that actually ran: `fable`, or `opus` after a fallback step):
 
 ```bash
-LOG_METRIC_FORWARD_TO_TRACKER=1 $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 2 plan.generated \
+LOG_METRIC_FORWARD_TO_TRACKER=1 $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 1 plan.generated \
   model=fable tokens_in=$IN tokens_out=$OUT duration_ms=$DUR iteration=$N
 ```
 
 Best-effort. See `$HOME/.claude/multi-agent-refs/progress-contract.md#token-telemetry-forwarding`.
 
----
-
-## Token telemetry  -  invoke after every LLM call
-
-```bash
-bash $HOME/.claude/scripts/phase-tracker.sh tokens 2 <input_count> <output_count>
-```
-
-Contract and rationale: `progress-contract.md` -> Token telemetry forwarding.
+Both halves of this phase report into the same counter: see "Token telemetry" above.