@mmerterden/multi-agent-pipeline 19.1.3 → 20.0.0

package/CHANGELOG.md

@@ -14,6 +14,149 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ---
 
+## [20.0.0] - 2026-09-21
+
+### Removed
+
+- **The Phase 0 Step 7.5 depth question, and `state.onlyDevelop` with it.** A
+  picker asked Full or Short before the run had read anything, and Short skipped
+  the plan phase outright - a guess about work not yet examined, recommended
+  from `taskType` alone. It was the same defect v19.0.0 removed from the
+  analysis phase when Lite went: a fixed selector overriding a rule that reads
+  evidence. There is one pipeline; every mode runs its whole phase set.
+- **`/multi-agent:local`, `/multi-agent:local-autopilot` and the `--local`
+  flag.** Where the branch lives is the Phase 0 Step 5b question and nothing
+  else answers it. `autopilot` resolves it to a worktree without asking,
+  because an unattended run commits and pushes from wherever it stands.
+- **`/multi-agent:resume-local`**, folded into `/multi-agent:resume`. One
+  command now lists both kinds of unfinished work - runs that stopped
+  mid-phase, and the current branch when it carries work no run produced - and
+  asks which to pick up. The tail it runs (Review → Commit → Report, no Plan
+  and no Dev) is unchanged; only its entry point moved.
+
+  Command inventory: 60 → 57.
+
+### Fixed
+
+- **Every phase reported its telemetry under the number it had before the
+  six-phase merge.** 29 `log-metric.sh` and `phase-tracker.sh tokens` calls
+  across the phase docs carried literal ids from the eight-phase contract, so
+  Dev's spend landed on Review's tile, Review's on Commit's, and Commit's on a
+  number no phase has. The accounting gate then refused to close those phases,
+  because the phase whose completion it guarded had recorded nothing. Each doc
+  now emits under its own id, and `smoke-phase-telemetry-ids.sh` derives that
+  id from the file name rather than a list.
+- **The accounting gate covered phases 1-4 by literal**, which under the new
+  numbering left Report ungated and, before the renumbering above, gated
+  Commit against a doc that recorded nowhere. `TRACKER_LLM_PHASES` now defaults
+  to every phase that dispatches a model, and the gate checks each covered
+  phase has a recording path.
+- **`/multi-agent:doctor` was missing from the Turkish help catalog and
+  `:analysis-jira` from the Turkish one too.** Half the audience could not see
+  two commands that ship. `smoke-help-catalog.sh` now compares both language
+  blocks against the command tree, and fails a row pointing at a command that
+  does not ship.
+- **`smoke-description-tr.sh` sampled a hardcoded command** that no longer
+  exists, so its round-trip check passed on a missing file. The sample is
+  derived from the tree.
+
+### Added
+
+- **`smoke-picker-callers.sh`** - `AskUserQuestion` refuses a call declaring
+  fewer than two options and discards every question batched with it, so the
+  rules that prevent it have to reach whoever writes a picker. Every spec that
+  renders one now cites `picker-contract.md`, the gate holds that at 47
+  callers, and a third check fails any spec that narrates the one-candidate
+  skip the contract forbids. A fourth holds the Phase 0 chain to its step
+  breadcrumb, so a six-question intake keeps saying which step it is on.
+- **`smoke-phase-telemetry-ids.sh`** and **`smoke-help-catalog.sh`**, described
+  under Fixed above.
+
+### Changed
+
+- **Phase 1 always runs, and what it produces scales with the evidence.** The
+  Locked 2 omission rule already drops a section with nothing behind it, so a
+  one-line chore yields a short document rather than a skipped phase. Phase 2
+  steps 1, 2, 3, 5 and 6 read that document; a step whose section is absent
+  records `not-applicable (no <section> in this document)` instead of aborting.
+- **The Plan Approval Gate has one skip left: `autopilot`**, and it is a skip
+  because there is nobody to ask, not because the run is a lighter kind of run.
+- **Tracker registration is a single batch at Step -1.** Nothing is deferred:
+  no answer later in the run can add or remove a phase, so `gen-mode-dispatch.mjs`
+  loses its deferred branch and every generated tracker section shrinks to one
+  registration loop.
+- **`global.resumeLocal` → `global.resume`**, preferences schema 2.8.0. The
+  `autoFix` value carries across; the key follows the command the tail now
+  enters through.
+- **`phases.json` modes drop their `local` flag.** No mode set it once the two
+  local commands went, and a generator branch no caller can reach reads as a
+  capability. The generated dispatch blocks are byte-identical, so the drift
+  gate holds.
+- Two gates now assert the ABSENCE: `smoke-pipeline-surface.sh` fails if Phase 0
+  grows a depth step or writes a depth key, or if any of the four downstream
+  readers reads one; `smoke-plan-approval-gate.sh` fails if the gate's scope
+  clause widens past autopilot.
+
+### Breaking
+
+`state.onlyDevelop` is gone from a schema with `additionalProperties: false`, so
+a state file written before v20 does not validate. The floor moves with
+`dist-tags.required` rather than a migration: a run below it halts rather than
+reading a record written under a contract that no longer exists.
+
+Decision, alternatives and consequences: [ADR-0015](docs/adr/0015-one-pipeline-no-depth-answer.md) and [ADR-0016](docs/adr/0016-the-run-shape-is-asked-not-typed.md).
+
+---
+
+## [19.1.4] - 2026-09-21
+
+### Added
+
+- **`smoke-gui-json-contract.sh` - the JSON a non-model consumer decodes stays
+  put.** `runs-index.mjs` and `update-check.sh` already had their output pinned;
+  `doctor.mjs --json` and `autopilot-status.sh --json` did not, and a renamed key
+  there breaks every consumer at once while the pipeline's own callers, which
+  read the human output, notice nothing. The gate drives both scripts and reads
+  their real stdout: `checks[]` with `{id, severity, step, problem, detail}` and
+  unique ids, `exit` an integer, severities from the documented set, the queue
+  triple as lists, the counters as numbers and `on` as a boolean. Adding a key
+  is deliberately not a failure - a decoder ignores what it does not know.
+- **`smoke-no-confessional-prose.sh`** - shipped comments and docs describe the
+  code, not the project's own history. A reason a rule exists still ships; a
+  past-defect narration belongs in this file. Four allow-list entries are
+  anchored to the lines that carry them, so a stale exemption fails the gate.
+- **A deterministic test for write-state's mid-write refusal.** The refusal
+  needs another writer to take the lock between acquiring it and renaming, which
+  on an idle machine is too narrow to hit and under load is a coin flip.
+  `WRITE_STATE_TEST_DELAY_MS` opens that window on purpose; the gate then asserts
+  both halves - exit 4, and nothing of that writer in the file.
+
+### Fixed
+
+- **The concurrent-writer gate counted an honest exit 4 as an unexpected code.**
+  A writer whose lock is taken mid-write refuses and writes nothing, which is the
+  same class of outcome as an exit-2 lock timeout. It is now counted with its
+  invariant attached - a refusal that wrote nothing must leave nothing behind -
+  and both refusal counts are reported so a rising one stays visible.
+- **`bulk-read.sh` claimed routing could send it outside the Anthropic ladder.**
+  It delegates to the `claude` CLI, which speaks that ladder and nothing else, so
+  the dispatcher's refusal of an external rung is the correct behaviour and the
+  comment was the wrong half. Both READMEs now state the limit: no call site
+  sends a model request itself, and a delegated read must not put a file's full
+  text outside the account that owns it.
+
+### Changed
+
+- **Both READMEs gained a "which model answers" section**, listing
+  `/multi-agent:{route-on,route-off,route-status,model}` with the two lines that
+  matter: `scope` has no `host-session` value and that is a schema gate, and an
+  external rung is refused at dispatch.
+- Confessional history removed from 57 shipped comments and doc paragraphs
+  across 40 files; each reason the rule exists was kept and rewritten with the
+  code as its subject.
+
+---
+
 ## [19.1.3] - 2026-09-21
 
 ### Fixed
@@ -101,6 +244,7 @@ them.
   is refused for a subagent, because subagent dispatch belongs to the host - the
   script says so on stderr instead of substituting an Anthropic rung and leaving
   the user believing a rule worked that never could.
+
 - `cost-table.json` rungs declare a `provider`. Without it every rung looks
   alike and the subagent limit above cannot be checked at all.
 - `smoke-model-dispatch.sh` (18 assertions). Half of them drive the router; the
@@ -495,7 +639,7 @@ gate cannot be loaded.
   and producing no effect.
 
   **Interactive runs ask at the step instead of ending at it**: open the item and
-  fix it, continue without it (recording in `state.maturity.accepted[]` *which*
+  fix it, continue without it (recording in `state.maturity.accepted[]` _which_
   gap was waved through, which is what separates an informed continue from a
   skipped check), or abort. `askInteractively: false` restores the old halt.
 
@@ -519,7 +663,7 @@ gate cannot be loaded.
 
   **The rule that shapes the rest: an edit is a reason to look again, never proof
   the gap closed.** A reply reading "will do later" moves the timestamp and fixes
-  nothing, so a changed item is re-fetched and re-scored and the *check* decides.
+  nothing, so a changed item is re-fetched and re-scored and the _check_ decides.
   Only a genuinely DIFFERENT gap set earns a second comment - otherwise an
   unattended queue turns an item into a wall of identical bot text. "Cannot tell
   whether it moved" resolves to re-check, never to wait, because folding unknown
@@ -886,6 +1030,7 @@ were the same shape: a chain fixed on one side and left broken on the other.
   than attaching nothing because a present artefact does not get re-checked.
   `fit` gained `webm`, which had been falling through to the pass-through arm and
   reaching the uploader at full size.
+
 - **Continuous mode's node half still named one host.** 17.2.0 fixed the shell
   side and closed the class. `autopilot-runner.mjs` was still resolving its three
   siblings from `~/.claude/scripts`, and `autopilot-intake.mjs` looked for
@@ -1233,7 +1378,6 @@ The flow video existed as a contract with no recorder, no UI test ever ran, and
 
 - **`install/templates/` now reaches the user tree.** It shipped in the tarball and was never copied, so `setup` told people to merge `install/templates/claude-hooks.json` - a path that exists only in a checkout. From an install the instruction named a file the reader did not have, and nothing said so. The doctor's `hook-coverage` check would have been a permanent `SKIP` for the same reason.
 
-
 ### Fixed
 
 - **The widget came back empty of everything except the phase name.** The native tile renders exactly one string, its subject, so whatever a reader wants from the card has to travel in that subject. It carried `Phase 1 Analysis` and nothing else, while the tracker already held the model, the elapsed time, the tokens and the cost for that phase and the fallback card printed all four. `phase-tracker.sh subjects [id]` now renders the same values in the one shape the host accepts, `tiles` builds its `TaskCreate` calls from it, and every boundary hint re-reads it so the numbers advance instead of freezing at creation time. A phase with nothing to report is still just its name - no empty separators.
@@ -1286,7 +1430,6 @@ The flow video existed as a contract with no recorder, no UI test ever ran, and
 
 - **`council-view.mjs`** renders what each reviewer found and what triage did with it. Everything it needs was already on the state and nothing displayed it; `run-metrics.mjs` reduced it to a ratio and the rows behind the ratio were invisible. De-anonymization is safe here because it runs after triage has ruled, and the gate pins that the map reaches no prompt. `/multi-agent:log` renders it; exit 2 means the run never reached Phase 4.
 
-
 - **A validator summary that says which checks ran.** `validate-analysis-doc.mjs --report` prints every check by name with a verdict each: `ok`, a finding count, or `skipped: <reason>`. The gap it closes is specific - the traceability matrix only runs in the corporate profile, so on a global document it never executed and the output was byte-identical to "ran, found nothing". Attribution is positional and reconciles by construction, so a check added without its mark misnames a finding but can never lose one; the gate asserts the printed set equals the set the file defines. Default output is unchanged for gate callers.
 
 - **Provenance in the reports a human reads.** `evidence_digest` and `base_commit` were already in the document front-matter, on the side only a machine reads. The analysis Phase 5 report, the `review-analysis` verdict and `--report` now carry them too: a timestamp cannot separate two reports made the same day, and the first question anyone asks of an older verdict is which version of the document it judged.
@@ -1312,6 +1455,7 @@ The flow video existed as a contract with no recorder, no UI test ever ran, and
   The contract, its reasoning and the check table live in `analysis/redesign.md`, which `analysis/SKILL.md` does not name and which therefore loads only on a redesign run.
 
 - `ANALYSIS_CEILING` 155000 -> 158500, the largest single raise it has taken. What could not be moved out is the argument: the section skeletons belong in `analysis-template.md`, where every other conditional section (15.6, 16.2) is already defined; Locked 37 belongs in `analysis/locked.md`, because a decision recorded only where it is implemented is not locked; and the intake question belongs in `analysis/intake.md`, because the option is chosen before anything knows the run is a redesign. 5.9 kB stayed outside the count. Everything was compressed twice before the number was picked.
+
 ### Fixed
 
 - `learn-from-transcripts.mjs` called `process.exit(0)` on the line after writing its `--json` result, so a large mining result was cut at the 64 KB pipe buffer - the exact defect the gate added in 16.27.0 exists to prevent, in the file that motivated it. The gate caught it; the two sites it named are now a `main()` with a return.
@@ -1368,12 +1512,11 @@ The flow video existed as a contract with no recorder, no UI test ever ran, and
 
 - **Setup merged one hook event and dropped the rest.** The instruction said to deep-merge `hooks.PreToolUse`, so the capture hooks would never have installed - the fix would have shipped inert.
 
-
 ## [16.26.0] - 2026-09-09
 
 ### Fixed
 
-- **The credential store mangled every multi-line secret, and the failure surfaced three layers away.** `security` picks its output format from the *content* of the value: anything it deems non-printable - a newline included - comes back as bare hex with no marker, and the reader took that at face value. A Firebase service-account JSON went in and `7b0a2020...` came out, which is neither JSON nor base64, so the Crashlytics fetcher reported a token-exchange error for a credential that was stored perfectly. The write side had the mirror defect: `security -i` is line-oriented, so a newline inside `-w` terminated the command mid-value and the item was never written at all.
+- **The credential store mangled every multi-line secret, and the failure surfaced three layers away.** `security` picks its output format from the _content_ of the value: anything it deems non-printable - a newline included - comes back as bare hex with no marker, and the reader took that at face value. A Firebase service-account JSON went in and `7b0a2020...` came out, which is neither JSON nor base64, so the Crashlytics fetcher reported a token-exchange error for a credential that was stored perfectly. The write side had the mirror defect: `security -i` is line-oriented, so a newline inside `-w` terminated the command mid-value and the item was never written at all.
 
   `keychain.py` now reads with `-g` and decodes on the explicit `0x` marker rather than guessing from shape, and writes with `-X <hex>` so no value can be cut at a newline. Lookup also walks all four attribute conventions (`-a`+`-l`, `-a`+`-s`, `-l`, `-s`) instead of one.
 
@@ -1397,7 +1540,7 @@ The flow video existed as a contract with no recorder, no UI test ever ran, and
 
 - **`firebase-app-discovery.sh` - the repo already knew the appIds.** Every Crashlytics call needs the opaque `1:<n>:ios:<hex>`, and a console URL carries only the bundle id, so the fetcher spent a Management API round trip resolving it on every run. `GoogleService-Info*.plist` and `google-services.json` name both ids; the script reads every match (a repo with several targets has several plists, and they do not all point at one project), skips build outputs, and emits entries shaped for `prefs.global.firebase.accounts[].apps[]`. The fetcher prefers that when present and falls through to the API when absent, so an install that never ran discovery behaves exactly as before.
 
-- **An encoding-regression gate.** `smoke-keychain.sh` stored a short ASCII word, which is exactly the value class that never reproduced the bug. It now round-trips a multi-line service-account JSON (and asserts it still *parses*, not merely compares equal), a hex-looking string, embedded quotes and backslashes, non-ASCII, and leading/trailing spaces.
+- **An encoding-regression gate.** `smoke-keychain.sh` stored a short ASCII word, which is exactly the value class that never reproduced the bug. It now round-trips a multi-line service-account JSON (and asserts it still _parses_, not merely compares equal), a hex-looking string, embedded quotes and backslashes, non-ASCII, and leading/trailing spaces.
 
 - **A gate for the shipped-but-dead script.** `firebase-app-discovery.sh` was written, installed onto every machine by all three hosts, and invoked by nothing: its only mention sat inside a comment in another script. That is the declared-but-inert defect in its purest form - the docs describe a capability, the install carries the code, and nothing connects them. `smoke-consumer-smoke-surface.sh` now checks every shipped script for an actual invoker, and is deliberately picky about what counts: comment lines, JSON schema descriptions, CHANGELOG and ROADMAP entries all name a script without ever running it, and each of those, left in the corpus, made the check pass on the broken state while it was being built.
 

package/README.md

@@ -43,12 +43,12 @@ package. Check first, then pick the row that matches:
 node -v; npm -v; command -v node npm npx
 ```
 
-| What you see | What to do |
-|---|---|
-| nothing at all | Install Node >= 20.11: `brew install node`, or the LTS installer from nodejs.org |
-| `node` works, `npx` does not | `npm i -g @mmerterden/multi-agent-pipeline` then `multi-agent-pipeline install --claude` |
-| nvm is installed but the shell does not see it | `source ~/.nvm/nvm.sh && nvm use --lts`, or just open a new terminal |
-| npm is ancient (< 5.2, which predates npx) | `npm i -g npm@latest`, or use the global-install row above |
+| What you see                                   | What to do                                                                               |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| nothing at all                                 | Install Node >= 20.11: `brew install node`, or the LTS installer from nodejs.org         |
+| `node` works, `npx` does not                   | `npm i -g @mmerterden/multi-agent-pipeline` then `multi-agent-pipeline install --claude` |
+| nvm is installed but the shell does not see it | `source ~/.nvm/nvm.sh && nvm use --lts`, or just open a new terminal                     |
+| npm is ancient (< 5.2, which predates npx)     | `npm i -g npm@latest`, or use the global-install row above                               |
 
 And the path that needs neither `npx` nor a global install - clone and run the
 installer directly:
@@ -83,7 +83,7 @@ Run a task - the input type is auto-detected:
 
 Every input runs the same short intake - **account → (repo) → maturity check → dev-context** - then enters Phase 0. A Jira id or GitHub URL is fetched and maturity-checked _before_ any code is written; free-text skips the fetch and goes straight to planning. Multi-repo tasks add extra repos at the dev-context step.
 
-Add `autopilot` to skip confirmations (e.g. `/multi-agent:autopilot "PROJ-1234"`). Neither the workspace nor the depth is a flag any more - they are two questions the run asks at Phase 0: where to run (worktree or your current checkout), then how deep (Full or Short). `--local` and `:local` answer the first up front.
+Add `autopilot` to skip confirmations (e.g. `/multi-agent:autopilot "PROJ-1234"`). The workspace is not a flag either - it is the one question the run asks about its own shape at Phase 0: where to run, a worktree or your current checkout.
 
 Update later with `/multi-agent:update`. Uninstall (tokens preserved) with `npx @mmerterden/multi-agent-pipeline uninstall`.
 
@@ -91,13 +91,12 @@ Update later with `/multi-agent:update`. Uninstall (tokens preserved) with `npx
 
 ## How it works
 
-One command runs up to 6 phases, with a gate between the risky ones. Phase 0
-asks two questions that decide the shape of the rest - how deep the run goes
-(Full or Short) and where the branch lives (a worktree or your current
-checkout):
+One command runs 6 phases, with a gate between the risky ones. Every run
+carries the whole set; the one question Phase 0 asks about shape is where the
+branch lives, a worktree or your current checkout:
 
 - **0 · Init** - parse the input (Jira id / GitHub URL / free text), pick account + repo(s), fetch the issue, run a maturity check.
-- **1 · Plan** - detect the stack, scan the codebase and write the analysis document, then break it into tasks with file-level targets and **stop for your approval** before touching code. Analysis and planning were two phases until 19.0.0; the depth picker always skipped them together, because they are one decision. Codebase scanning runs on the explorer persona (Sonnet).
+- **1 · Plan** - detect the stack, scan the codebase and write the analysis document, then break it into tasks with file-level targets and **stop for your approval** before touching code. Analysis and planning were two phases until 19.0.0; they are one decision, so they are one phase. Codebase scanning runs on the explorer persona (Sonnet).
 - **2 · Dev** - TDD: failing test → code → green, following the repo's style + the active stack skills. The phase ends at its own gate: build, lint, tests and a secret scan, run **once**. Review used to build again, and nothing consumed the difference.
 - **3 · Review** - a **CLI-aware parallel review** against the logs Dev produced - Claude Code runs 3 models (Fable + Opus + Sonnet), Copilot CLI runs 3 (GPT-5.4 + Opus + Sonnet) - then a **Fable triage** keeps only actionable findings; blockers loop back to Phase 2. The optional user test lives here, keeping its waiting state.
 - **4 · Commit/PR** - conventional commit, push (must succeed), open a PR (`Ref: #N`, never auto-close).
@@ -109,16 +108,17 @@ checkout):
 
 Two of the six phases were doing the same work twice. Dev built the project
 and tee'd a log; Review opened by building it again. Analysis and Planning were
-already one decision - the depth picker skipped them together and the state
-schema described them as one unit. Six phases now, one build per run.
+already one decision, and the state schema described them as one unit. Six
+phases now, one build per run.
 
 The other half of the change is that the count is finally guarded.
 `smoke-phase-contract.sh` derives it from `pipeline/schemas/phases.json` and
 holds every other copy to it: the generator's output, the token budget, the
 state-schema bounds, the progress fractions in sample output, and the named
-thresholds that used to be literals scattered across scripts. The phase count
-appeared in 91 places across 40 files with nothing checking any of them, while
-the command count, the jq count and the persona count all had gates.
+thresholds, none of which is a literal in a script any more. A phase count is
+otherwise the kind of number that spreads across dozens of files with nothing
+checking any of them, the way the command count, the jq count and the persona
+count are each held by a gate.
 
 Reasoning, mapping and rejected alternatives:
 [ADR-0014](./docs/adr/0014-six-phase-consolidation.md).
@@ -156,7 +156,7 @@ A failed `git fetch` degrades loudly rather than silently: the list falls back t
 
 ### Workspace: worktree or local
 
-Phase 0 Step 5b asks where the branch lives. **Worktree** (`.worktrees/{id}/`) leaves your current checkout untouched; **Local** works in the project root on a new branch, which drops Phase 5 - the user-test gate checks the change out of a worktree and there is none - and needs the project root clean. `/multi-agent:local` and `--local` answer it up front. Every autopilot entry resolves it to a worktree without asking: an unattended run commits and pushes from wherever it stands, and doing that in your own checkout is what worktrees exist to prevent. `:local-autopilot` is the explicit opt-out.
+Phase 0 Step 5b asks where the branch lives. **Worktree** (`.worktrees/{id}/`) leaves your current checkout untouched; **Local** works in the project root on a new branch, and needs the project root clean. It is a question, not a flag: there is no `:local` command and no `--local` switch, so the answer is always visible in the run rather than buried in how the run was typed. `autopilot` resolves it to a worktree without asking, because an unattended run commits and pushes from wherever it stands and doing that in your own checkout is what worktrees exist to prevent. The manual-test offer at the end of Review follows the same answer: a worktree run is asked whether to check the branch out and test it, a local run already is that checkout, so there is nothing to offer.
 
 Under the hood: each task runs in its own **git worktree** (or the current branch when you choose local), commits use the **git identity routed from the repo's origin URL**, and **multi-repo** tasks get per-repo worktrees plus an integration build. Tokens stay in the OS keychain; nothing is committed or logged. `/multi-agent:review` can also review an existing GitHub/Bitbucket PR - per-finding inline comments anchored to `file:line` + an explicit Approve / Needs-Work state.
 
@@ -167,39 +167,23 @@ The discipline behind all of this - bounded loops, evidence gates, token-budgete
 | Mode      | Command                              | Flow                                                                                                                                                             |
 | --------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Full      | `/multi-agent "task"`                | All 6 phases, interactive                                                                                                                                        |
-| Autopilot | `/multi-agent:autopilot "task"`      | 6 phases (interactive Test gate dropped), no confirmations                                                                                                       |
-| Local     | `/multi-agent:local "task"`          | Full pipeline minus the interactive Test gate, current branch (no worktree)                                                                                      |
-| Depth     | asked at Phase 0 Step 7.5            | Full (all phases) or Short (Dev → Review → Test → Commit → Report). Not a command name - `/multi-agent` and `:local` ask, both autopilot entries always run Full |
-| Ship      | `/multi-agent:resume-local`          | Run the review→test→commit→report tail over local work                                                                                                           |
+| Autopilot | `/multi-agent:autopilot "task"`      | The same 6 phases, no confirmations; the workspace resolves to a worktree and the user-test gate inside Review is skipped                                                                                                       |
 | Audit     | `/multi-agent:design-check`          | Mock-mode vs Figma conformance, local-only                                                                                                                       |
 | Audit     | `/multi-agent:testflight-validation` | Pre-submission gates for a TestFlight build: static archive audit → Apple's `altool --validate-app` → Review-Guidelines check. Validates only, never uploads     |
 
-Depth, autopilot and `--local` are the only knobs on the run itself; everything else is its own command. The full catalog is below.
-### Pipeline depth: Full or Short
-
-Depth is the one question the run asks about its own shape. `/multi-agent` and `/multi-agent:local` ask it at Phase 0 Step 7.5 - after the issue is fetched and the task type is known, because that is what the recommendation is drawn from.
-
-- **Full** runs everything: Analysis reads the codebase and maps impact, Planning writes a task breakdown and stops for your approval, and Dev works from that plan.
-- **Short** starts at Dev: Init → Dev → Review → Test → Commit → Report. Analysis and Planning do not run, so there is no plan gate and no analysis document; Dev derives its own task list from the issue, and runs on **Opus** rather than Sonnet because it has no plan to follow. Review, the deterministic gates and the test suite are untouched - Short skips the thinking, never the proof.
-
-Short is right when you already know the fix and the file: a one-line guard, a copy change, a rename, a revert. It is wrong when the cause is still a hypothesis, when the task carries a Figma reference or an analysis document (Planning is what turns those into a breakdown), or when the change spans repos.
-
-The widget follows the answer rather than predicting it: Phase 0 is the only tile drawn before you choose, and a Short run never draws an Analysis tile at all. Both autopilot entries skip the question and always run Full. `agent-state.json` records which one ran as `onlyDevelop`.
-
+`autopilot` is the only knob on the run itself; everything else is its own command. The full catalog is below.
 
 ## Commands
 
-`/multi-agent` plus 56 sub-commands. `/multi-agent:help` renders the same catalog in your terminal, in your `outputLanguage`.
+`/multi-agent` plus 57 sub-commands. `/multi-agent:help` renders the same catalog in your terminal, in your `outputLanguage`.
 
 ### Pipeline entries
 
 | Command                               | What it does                                                                                         |
 | ------------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| `/multi-agent "task"`                 | Full pipeline in a worktree. Asks Full or Short depth at Phase 0                                     |
-| `/multi-agent:local "task"`           | Same pipeline on the current branch, no worktree                                                     |
-| `/multi-agent:autopilot "task"`       | Worktree, no confirmations, always Full                                                              |
-| `/multi-agent:local-autopilot "task"` | Current branch, no confirmations, always Full                                                        |
-| `/multi-agent:resume-local`           | Pipeline tail over work already done locally: Review → Build+Test → Commit/PR → Report. No dev phase |
+| `/multi-agent "task"`                 | The pipeline; Phase 0 asks where the branch lives                                                    |
+| `/multi-agent:autopilot "task"`       | The same pipeline, unattended: worktree resolved, no confirmations                                   |
+| `/multi-agent:resume`                 | Unfinished work, either source: a stopped run picks up where it left off, a branch with no run behind it gets the tail (Review → Build+Test → Commit/PR → Report) |
 
 ### Task control
 
@@ -207,7 +191,7 @@ The widget follows the answer rather than predicting it: Phase 0 is the only til
 | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `/multi-agent:status`                   | Every task's ID, phase, branch and state                                                                                                                 |
 | `/multi-agent:log [#N]`                 | Show a task's `agent-log.md` (most recent by default)                                                                                                    |
-| `/multi-agent:resume [#N]`              | Carry a stopped or failed task on from its last phase                                                                                                    |
+| `/multi-agent:resume [#N]`              | Carry a stopped or failed task on from its last phase, or run the tail over a branch with no run behind it                                                |
 | `/multi-agent:kill [#N]`                | Stop a task, remove its worktree and branch                                                                                                              |
 | `/multi-agent:steer #N "<instruction>"` | Correct a running task without stopping it; applied at the next phase boundary                                                                           |
 | `/multi-agent:search`                   | Ranked search across every task log; `--semantic` queries the triage corpus                                                                              |
@@ -300,11 +284,37 @@ Two compliance skills install on every host and back the store gates: `apple-arc
 Everything above starts when you start it. Continuous mode is the same pipeline
 picking work up on its own, on ONE machine you choose, from repos you choose.
 
-| Command | What it does |
-| --- | --- |
-| `/multi-agent:autopilot-on` | Pick the repos this machine watches. Labelled GitHub issues and assigned + labelled Jira items then run in a worktree and stop at an open PR. Re-run to change the list |
-| `/multi-agent:autopilot-status` | What is running and at which phase, what is queued, what is waiting for an answer, the PRs of the last day, and the rolling spend |
-| `/multi-agent:autopilot-off` | Remove the schedule. Work already running finishes; the repo selection is kept |
+| Command                         | What it does                                                                                                                                                            |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/multi-agent:autopilot-on`     | Pick the repos this machine watches. Labelled GitHub issues and assigned + labelled Jira items then run in a worktree and stop at an open PR. Re-run to change the list |
+| `/multi-agent:autopilot-status` | What is running and at which phase, what is queued, what is waiting for an answer, the PRs of the last day, and the rolling spend                                       |
+| `/multi-agent:autopilot-off`    | Remove the schedule. Work already running finishes; the repo selection is kept                                                                                          |
+
+## Which model answers
+
+The ladder is `fable -> opus -> sonnet -> haiku`, and a run walks it on failure.
+Routing lets a policy pick the rung instead, per call site, and is off until you
+turn it on.
+
+| Command                     | What it does                                                                                                                                        |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/multi-agent:route-on`     | Pick a strategy, a scope and the rules that say which rung a call lands on. Validated against `route-config.schema.json` before anything is written |
+| `/multi-agent:route-off`    | Disarm it. The rules are KEPT, so turning it back on does not re-ask for the same configuration                                                     |
+| `/multi-agent:route-status` | Whether it is armed, which rule applies where, which rung the last dispatches took, and what this run has cost                                      |
+| `/multi-agent:model`        | Turn the top rung on or off, and move the cost ledger's pricing with it in the same step                                                            |
+
+**The scope cannot be the whole session.** `scope` accepts `subagent`,
+`bulk-read` and `research`; there is no `host-session` value and that is a schema
+gate, not a convention. Owning the host's base URL would send every call you make
+through a third layer, including work that has nothing to do with this pipeline.
+
+**The honest limit, which `route-status` prints rather than hides.** A rung on a
+non-Anthropic provider is refused at dispatch. No call site sends a model
+request itself: the one that routes, `bulk-read.sh`, delegates to the `claude`
+CLI, which speaks that ladder and nothing else. Sending a read to a third-party
+provider would also put the file's full text outside the account that owns it,
+so it is a decision a user makes rather than a default. Routing chooses inside
+the ladder.
 
 **Nothing is on by default and nothing is added implicitly.** Installing the
 package writes no state and schedules nothing; `smoke-autopilot-default-off.sh`
@@ -359,17 +369,17 @@ This enables the matching plugin (+ the shared `ai-common` plugin) in the repo's
 
 ## Tool support
 
-The pipeline runs natively on **Claude Code**, **Copilot CLI** and **Codex CLI** - all three install from the same `pipeline/` source and get the same 60 commands.
+The pipeline runs natively on **Claude Code**, **Copilot CLI** and **Codex CLI** - all three install from the same `pipeline/` source and get the same 57 commands.
 
 | Tool        | Flag                 | What it installs                                                                                       |
 | ----------- | -------------------- | ------------------------------------------------------------------------------------------------------ |
 | Claude Code | `--claude` (default) | slash commands + skills + agents + three `PreToolUse` hooks (secret scan, agent-guard, read-size gate) |
-| Copilot CLI | `--copilot`          | instructions + 60 sub-command skills + scripts                                                         |
-| Codex CLI   | `--codex`            | one router skill + 60 specs as refs + 9 agent TOML + `AGENTS.md` block + `codex mcp add`               |
+| Copilot CLI | `--copilot`          | instructions + 57 sub-command skills + scripts                                                         |
+| Codex CLI   | `--codex`            | one router skill + 57 specs as refs + 9 agent TOML + `AGENTS.md` block + `codex mcp add`               |
 
 Filter skills by stack with `--platform=ios\|android\|all`.
 
-**Why Codex gets one skill and not 60.** Codex assembles every discovered skill's name
+**Why Codex gets one skill and not 57.** Codex assembles every discovered skill's name
 and description into a single prompt block and drops entries when it overflows, with no
 error. Measured on 0.145: installing one plugin that declares 142 skills surfaced only
 75 of them and evicted an unrelated user skill. So on Codex the pipeline ships a single