@mmerterden/multi-agent-pipeline 20.2.1 → 20.3.1

package/README.md

@@ -17,7 +17,7 @@ Runs natively on Claude Code, Copilot CLI and Codex CLI. macOS only. Zero runtim
 ### Prerequisites
 
 - **Node.js >= 20.11** - required; the pipeline's own tooling runs on it.
-- **`jq`** - required for nine paths, optional for the rest. 84 shell files call it. The nine that publish or decide - the autopilot queue, Jira comments, PR reviews, issue updates, the plan file, both Figma fetchers, log search and Jira auth - now refuse with exit 3 rather than run, because a missing `jq` renders as empty DATA and the work carries on with it. Everywhere else it still degrades. The install prints a note when it is missing.
+- **`jq`** - required for nine paths, optional for the rest. 89 shell files call it. The nine that publish or decide - the autopilot queue, Jira comments, PR reviews, issue updates, the plan file, both Figma fetchers, log search and Jira auth - refuse with exit 3 rather than run, because a missing `jq` renders as empty DATA and the work carries on with it. Everywhere else it still degrades. The install prints a note when it is missing.
 - **`gh`** - for GitHub issue and PR work. Its built-in `--jq` is independent of the `jq` binary.
 
 ## Quick Start
@@ -96,55 +96,38 @@ 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; 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).
-- **5 · Report** - technical summary + a Jira comment with test scenarios, posted through the channels layer. This is the one step autopilot still pauses at, in every mode.
+- **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 are one decision, so they are one phase ([ADR-0014](./docs/adr/0014-six-phase-consolidation.md)). 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 reads that log rather than building again.
+- **3 · Review** - a **CLI-aware parallel review** against the logs Dev produced - Claude Code runs 3 models (Fable + Opus + Sonnet; Opus + Sonnet while the fable rung is off), 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). An unattended run stops at the commit and hands a PR request to the autopilot runner, which verifies it and opens a draft PR.
+- **5 · Report** - technical summary + a Jira comment with test scenarios, posted through the channels layer. This is the one step a terminal autopilot run still pauses at; an unattended run ends at the Phase 4 hand-off, and the runner posts the reports you configured once the PR is open.
 
-`/multi-agent:analysis` runs its own shorter chain and, since v16.12.0, reviews what it wrote before publishing it: the draft goes through the same three-reviewer set and triage as a code diff, a blocking finding returns it to synthesis with dispatch closed, and the gaps that survive are either searched, asked about, or recorded with an owner. It used to publish behind a structural validator alone.
+The phase list lives in `pipeline/schemas/phases.json`, and `smoke-phase-contract.sh` holds every other copy of it - the generator's output, the token budget, the state-schema bounds, the progress fractions in sample output - to that one file.
 
-### 19.0.0: six phases, and a gate for the number
+`/multi-agent:analysis` runs its own shorter chain and reviews what it wrote before publishing it: the draft goes through the same three-reviewer set and triage as a code diff, a blocking finding returns it to synthesis with dispatch closed, and the gaps that survive are either searched, asked about, or recorded with an owner.
 
-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, 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, 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).
-
-### 18.0.0: one state directory, and a way to ask whether your install is real
+### Install verification, cost, and one state directory
 
 - **`multi-agent-pipeline verify`.** The install is a copy, and from the moment it is written the two halves drift independently: an edit in the installed tree is behaviour with no source, and a file the installer skipped is a script the docs describe and nobody has. `verify` compares both against a manifest built at pack time. What a green result proves is stated plainly - the bytes match what the publisher recorded, not who published them.
 - **Cost, past the single run.** The per-task ceiling cannot see the two ways a budget actually empties: a drift that trips nothing, and one session that burns a week in an hour while every run stays under its cap. `cost-analyze` projects, finds days out of family by median absolute deviation, and reports acceleration - as LIST-price estimates, which it says on every run rather than in a footnote.
 - **A run's state lives in one place.** `{project}/{taskId}/` is canonical, the flat layout is still read, and a run that exists in both is counted once.
-- **Server readiness, entirely opt-in.** `doctor --profile=server` adds four checks that only matter when nobody is at the keyboard, `install --unattended` writes a permission profile after printing it, and the autopilot runner now survives a month unwatched. The default install writes no permissions and the default doctor run is unchanged, because a laptop told it fails a server check learns to ignore doctor.
+- **Server readiness, entirely opt-in.** `doctor --profile=server` adds four checks that only matter when nobody is at the keyboard, and `install --unattended` writes a permission profile after printing it. The default install writes no permissions and the default doctor run leaves the server checks out, because a laptop told it fails a server check learns to ignore doctor.
 
 ### Your package manager, your hooks, your MCP surface
 
-Three smaller things in 17.6.0, each closing a gap where the pipeline assumed instead of looking:
+Three places where the pipeline looks instead of assuming:
 
-- **Phase 2 stopped typing `npm`.** A repo on pnpm, yarn or bun used to fail in the development phase, with a worktree and a branch already created. The manager is resolved from the repo now - an env override, then `package.json#packageManager`, then the lock file, then npm reported as a default rather than as evidence. iOS and Android are untouched.
-- **A compaction no longer eats what a phase learned.** The capture hook ran at session end; an auto-compaction summarizes a long review or development phase while it is still running, and anything not yet written was gone before session end ever fired. The hooks template now flushes at `PreCompact` too.
+- **Phase 2 uses the repo's package manager.** It is resolved from the repo - an env override, then `package.json#packageManager`, then the lock file, then npm reported as a default rather than as evidence - so a pnpm, yarn or bun repo does not fail after its worktree and branch exist. iOS and Android are untouched.
+- **A compaction keeps what a phase learned.** The hooks template flushes captures at `PreCompact` as well as at session end, because an auto-compaction summarizes a long review or development phase while it is still running.
 - **`doctor` counts your MCP servers.** Every registered server sends its tool list on every turn and they are added one at a time, so nobody ever sees the total. It reports the count and nothing else: no warning, no blocking, no disabling.
 
-### Maturity: the check now has an effect
+### Maturity: the check has an effect
 
-Phase 0 scores how ready the item is before anything is built, and until 17.6.0 it scored and stopped: a blocker halted the run, an autopilot queue moved on, and the item stayed exactly as immature as it was found. Nobody was told, so nothing changed, so the next scan halted on the same item for the same reason.
+Phase 0 scores how ready the item is before anything is built. A score that only halts leaves the item exactly as immature as it was found, and the next scan halts on it for the same reason, so the result drives a next step.
 
-An interactive run now **asks at that step** - open the item and fix it, continue without it, or abort - and records which gap you waved through rather than just that you continued. An autopilot run can be told to **ask on the item itself** (`prefs.global.maturityFollowup.autopilotCommentsOnIssue`, off by default): one comment naming what is missing, then it stops and waits. Never a status change, never an assignee, never a close, `Ref:` and never `Closes:`.
+An interactive run **asks at that step** - open the item and fix it, continue without it, or abort - and records which gap you waved through rather than just that you continued. An autopilot run parks the item and can be told to **ask on the item itself** (`prefs.global.maturityFollowup.autopilotCommentsOnIssue`, off by default): one comment naming what is missing. Never a status change, never an assignee, never a close, `Ref:` and never `Closes:`.
 
-Edit the item and the next scan re-checks it; if the gap closed, development starts on its own. An edit is only a reason to look again - a reply reading "will do later" moves the timestamp and fixes nothing, so the check re-runs against the new content and decides. The same question is never asked twice.
+`resume` re-enters the maturity step with the item re-fetched, and the check decides. An edit is only a reason to look again - a reply reading "will do later" moves the timestamp and fixes nothing. The same question is never asked twice.
 
 ### Base branch: evidence, then a question
 
@@ -152,7 +135,7 @@ Phase 0 Step 3 collects the candidates **with the evidence behind each one** bef
 
 Nothing is hardcoded: any Jira field whose schema resolves to `version` is read whatever the board calls it, and the release-branch naming convention is inferred from the refs that exist rather than read off a table - one repo yields `<prefix>/develop_<version>`, another `release-<version>`, out of the same code. A version whose branch has not been cut yet is reported as a note, never offered as an option you cannot check out.
 
-A failed `git fetch` degrades loudly rather than silently: the list falls back to local refs, the question says so, it gains a retry row, and the exit gate refuses to close Phase 0 if a degraded run recorded its list as the remote's answer. Turn the whole thing off with `prefs.global.baseBranchEvidence.enabled: false` and Step 3 asks the way it always did.
+A failed `git fetch` degrades loudly rather than silently: the list falls back to local refs, the question says so, it gains a retry row, and the exit gate refuses to close Phase 0 if a degraded run recorded its list as the remote's answer. Turn the whole thing off with `prefs.global.baseBranchEvidence.enabled: false` and Step 3 asks with the plain branch list.
 
 ### Workspace: worktree or local
 
@@ -175,7 +158,7 @@ The discipline behind all of this - bounded loops, evidence gates, token-budgete
 
 ## Commands
 
-`/multi-agent` plus 58 sub-commands. `/multi-agent:help` renders the same catalog in your terminal, in your `outputLanguage`.
+`/multi-agent` plus 61 sub-commands. `/multi-agent:help` renders the same catalog in your terminal, in your `outputLanguage`.
 
 ### Pipeline entries
 
@@ -212,6 +195,7 @@ The discipline behind all of this - bounded loops, evidence gates, token-budgete
 | `/multi-agent:scan`                | Skill security scan of local skill directories against a tiered pattern catalog             |
 | `/multi-agent:prune-prompts`       | Zero-base review of the always-on instruction footprint; keep / trial / delete per rule     |
 | `/multi-agent:ios-coding-standard` | Audit an iOS module against the 99-rule registry, produce a remediation plan                |
+| `/multi-agent:security-review`    | Standalone static security review of a diff, branch or repo: threat model, OWASP + CWE findings with CVSS, offline dependency inventory |
 
 ### Analysis
 
@@ -219,6 +203,9 @@ The discipline behind all of this - bounded loops, evidence gates, token-budgete
 | --------------------------------- | ----------------------------------------------------------------------------------------- |
 | `/multi-agent:analysis`           | Standalone feature spec: global (23-section handoff) or corporate (IG/UC/FG) profile      |
 | `/multi-agent:analysis-resolve`   | Answer an analysis doc's Section 20 open questions one row at a time                      |
+| `/multi-agent:analysis-jira`      | Turn a final analysis document into a Jira story tree: stories from its rule ids, two-way coverage, full preview, creates only what is missing |
+| `/multi-agent:graph`              | Build and query the repo's code graph: symbols, imports, references; deterministic, no API tokens |
+| `/multi-agent:research <id>`      | Answer an item's gaps from its tracker thread, linked docs and repo before anyone is asked |
 | `/multi-agent:complaint-analysis` | Customer-complaint triage with Graylog evidence: client / bff root cause, or core routing |
 
 ### Testing on a device
@@ -265,15 +252,18 @@ The discipline behind all of this - bounded loops, evidence gates, token-budgete
 | -------------------------------- | ------------------------------------------------------------------------------ |
 | `/multi-agent:setup`             | First-run wizard: keychain token discovery, git identity, pipeline preparation |
 | `/multi-agent:stack [ids]`       | Enable the marketplace plugin(s) for this repo. Multi-select                   |
+| `/multi-agent:scaffold <stack> <name>` | New project skeleton from the toolkit's scaffold skill, green before its first commit |
 | `/multi-agent:language [en\|tr]` | Show or set `outputLanguage`; `promptLanguage` stays English                   |
 | `/multi-agent:sync`              | One-shot sync: Claude Code, Copilot CLI, pipeline repo, website, toolkit MCP   |
 | `/multi-agent:update`            | Update to the latest published npm release and run migrations                  |
+| `/multi-agent:doctor`            | Health check of the install: layout, preferences, credentials, hooks, host capabilities; the exit code is the verdict |
 | `/multi-agent:uninstall`         | Remove the pipeline from every CLI. Keychain tokens always left intact         |
+| `/multi-agent:serve`             | Local contract server for a client: 127.0.0.1 only, token, stops when idle     |
 | `/multi-agent:help`              | This catalog, in the terminal, in your `outputLanguage`                        |
 
 ### Subagents
 
-Eight are installed alongside the commands and dispatched by the phases: `explorer` and `task-clarifier` (Phase 0-1), `ios-architect` / `android-architect` / `backend-architect` (Phase 2), `dev-critic` (Phase 3), `code-reviewer` and `security-auditor` (Phase 4).
+Ten are installed alongside the commands: `explorer` and `task-clarifier` (Phase 0-1), `ios-architect` / `android-architect` / `backend-architect` and `plan-critic` (Phase 1, the critic only with the quality gates active), `dev-critic` (end of Phase 2), `code-reviewer` and `security-auditor` (Phase 3), and `bulk-reader`, which `bulk-read.sh` dispatches to summarise one large file when a whole-file read is blocked.
 
 ### Skills that are not commands
 
@@ -286,35 +276,30 @@ 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-on`     | Pick the repos this machine watches. Labelled GitHub issues and assigned + labelled Jira items then run in a worktree and stop at a draft 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                                                                                          |
+| `/multi-agent:autopilot-off`    | Remove the schedule. Work already running finishes; the repo selection is kept. `--now` also stops the item in flight, after naming it and asking                      |
 
-## Which model answers
+### Autopilot (unattended)
 
-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 runner is a launchd tick. Each tick takes the head of the queue, runs the
+whole pipeline on it in a worktree with `MULTI_AGENT_UNATTENDED=1` set, and
+ends at a **draft** pull request. A person reviews it and merges it; nothing in
+the pipeline merges.
 
-**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.
+- **Research before asking.** A run that parks on a maturity blocker or an open analysis question gets a research pass before it is left for a person. `/multi-agent:research <id> --autonomous` reads the tracker thread, linked items and documents, similar closed items and the repository; `research-gate.mjs` closes only what a quoted source or a resolving `file:line` backs, and the maturity check or the open-questions gate re-runs on the result and decides. Whatever is still open parks the run with the candidates found. [Research](./pipeline/multi-agent-refs/features/research.md)
+- **One outward writer.** The session never pushes. Phase 4 writes a PR request, and the runner, outside the session, re-runs the stack's build and tests itself, re-checks the gate ledger, the secret scan over the commit range and the outbound gate, pushes the branch the run recorded from a clean staging repository, and opens the PR with `gh pr create --draft`. A check that fails leaves the item `verification-failed` with the verdict on disk. On Bitbucket the branch is pushed and a summary written, since there is no draft PR to open. [Unattended security](./pipeline/multi-agent-refs/features/unattended-security.md)
+- **Operations around a run.** A second launchd agent keeps the Mac awake while the mode is on (`caffeinate -s -i`, plus `-d` if you answer yes to the display question at `autopilot-on`), and each run holds a sleep lock until its tick ends. Every credential a configured repo needs is probed before the schedule is offered and again on every tick, so a locked keychain refuses with the key and the fix. A circuit breaker stops launching after consecutive attempts that produced nothing, `costCeilingUsd` caps spend over a rolling 24 hours, `maxParallelAgents` caps sessions working at once, and once a day the runner writes a cleanup report and, when enabled, a digest. [Autopilot operations](./pipeline/multi-agent-refs/features/autopilot-operations.md)
+- **A fail-closed guard.** Under the variable, the Bash guard judges a command only when it reduces to simple commands joined by `;`, `&&`, `||` and plain pipes, and refuses anything else unparsed. On what it can parse: no push, PR, issue or tracker write, no Keychain read, no fetch outside the network allowlist, no package install or manifest edit, no write into a protected path. Ticket, page and PR text reaches the model inside untrusted-data delimiters. The permission profile (`install --unattended`) is a second line; the boundary is a separate non-admin macOS user and GitHub rulesets on the default and release branches, which the operator applies. [Unattended security](./pipeline/multi-agent-refs/features/unattended-security.md)
+- **Claims are checked, not trusted.** With the quality gates active, a run's claims about the repository are checked before it commits: a localization key or endpoint the change references exists, open analysis questions are answered or park the run, a triage citation quotes the line it cites, a "pre-existing" finding points at a line the diff did not touch, the plan's steps are covered, and a test pass shows a positive executed count read with the stack's own markers (8 stacks: `ios`, `android`, `web`, `backend-node`, `python`, `go`, `rust`, `jvm`) along with a new test that fails without the change. Every verdict goes to a gate ledger, and the commit hook refuses a commit whose mandatory gates did not pass for HEAD. [Unattended gates](./pipeline/multi-agent-refs/features/unattended-gates.md), [stack adapters](./pipeline/multi-agent-refs/features/stack-adapters.md)
+- **Spec, plan and review discipline.** `/multi-agent:analysis` writes a project constitution (security, accessibility, architecture and licensing rules, each tied to a source), and a spec-consistency gate checks by id that every requirement has a task and a test and that nothing waives a binding rule. Phase 1 ends with one plan-critic round under four lenses (scope, feasibility, security, a cheaper alternative), answered once and judged by a script. In review, a `blocking` finding stops the run only when two independent reviewers carry it or a failing test shows it; otherwise it is lowered to `important`, never dropped. [Constitution](./pipeline/multi-agent-refs/features/constitution.md), [plan critic](./pipeline/multi-agent-refs/features/plan-critic.md), [review decision](./pipeline/multi-agent-refs/features/review-decision.md)
+- **A client contract.** Commands and run questions are declared as data. `/multi-agent:serve` starts a localhost HTTP server over the same JSON the CLI prints, and `pipeline/contract/` ships the manifest, TypeScript types and fixtures a client builds against. Four phone routes read redacted runs, answer a parked question with one of its offered options, and, only when switched on, queue a launch; every request carries an Ed25519 signature from an enrolled device. The phone app is a separate project. [Client kit](./pipeline/contract/README.md), [phone API](./pipeline/multi-agent-refs/features/phone-api.md)
 
-**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.
+**Attended use is unchanged.** Every behaviour above keys on
+`MULTI_AGENT_UNATTENDED=1` or on autopilot mode. With neither, no gate writes a
+ledger entry or parks a run, and the guard answers as it did before; a smoke
+suite holds each direction. The full contract, entry point by entry point:
+[unattended-contract.md](./pipeline/multi-agent-refs/unattended-contract.md).
 
 **Nothing is on by default and nothing is added implicitly.** Installing the
 package writes no state and schedules nothing; `smoke-autopilot-default-off.sh`
@@ -326,19 +311,22 @@ The biggest win is not parallelism. Measured here, the median run is 44 minutes,
 but an item that finishes at 14:00 waits until you sit down again: overnight that
 is 16 hours against 40 minutes. Continuous mode removes the waiting, not the work.
 
-**What it will not do.** It does not merge - the runner stops at an open PR and
+**What it will not do.** It does not merge - the runner stops at a draft PR and
 the decision stays yours. It does not touch an attended run: per-repo concurrency
 is always 1, so the queue steps around a repo you are working in rather than
 competing for `.git/index.lock`. There is no cap on PRs; the bounds are
-`costCeilingUsd` over a rolling 24 hours and what the machine can hold.
+`costCeilingUsd` over a rolling 24 hours, `maxParallelAgents` when you set it,
+and what the machine can hold.
 
 **A menu bar indicator**, when `swiftc` is present, draws the same `status.json`
-in the top right and refreshes on its own: one row per item with its id, Full or
-Short, the phase as a fraction, the elapsed time and the stack. A row disappears
-the moment the item finishes and reappears under Reports with its PR. It only
-draws - it cannot start, stop or change a run. ActivityKit is unavailable on
-macOS, so this is an `NSStatusItem`, built from source on demand rather than
-shipped as a binary that would need signing.
+in the top right and refreshes on its own: one row per item with its id, the
+phase as a fraction, the elapsed time and the stack. A row disappears the moment
+the item finishes and reappears under Reports with its PR. It only draws - it
+cannot start, stop or change a run, and the one command it names is spelled the
+way your CLI spells it. Its labels render in `prefs.global.outputLanguage`, from
+the same table the terminal renders from. ActivityKit is unavailable on macOS,
+so this is an `NSStatusItem`, built from source on demand rather than shipped as
+a binary that would need signing.
 
 **It survives a restart with no command to run.** launchd loads the job at
 **login**, not at boot, and that is correct rather than a limitation: the login
@@ -347,8 +335,11 @@ reach Jira or GitHub anyway. There is no `autopilot-resume` - a command you have
 to remember is a queue that silently stops when you forget it. `doctor` reports
 the real failure instead: configured, but launchd holds no job.
 
-Sleep is held **only on AC**. A queue that flattens a laptop off the charger is a
-bug; on battery the assertion is released and work resumes when you plug in.
+**Sleep.** launchd's interval does not wake a sleeping Mac, so while the mode is
+on the awake agent holds system sleep off on AC and idle sleep off on battery
+too. A laptop left unplugged with the mode on stays awake until it is plugged in
+or the mode is turned off; `awake.enabled: false` removes the agent and leaves
+only the per-run lock, which macOS honours on AC only.
 
 **The three commands ship to all three CLIs and behave identically there**, because
 what they control is not a CLI feature: it is a launchd user agent whose tick
@@ -357,6 +348,38 @@ Continuous mode therefore needs the `claude` binary on `PATH` everywhere. The
 queue and the repo selection live in `~/.claude/autopilot/` on every host, on
 purpose - two CLIs on one machine must read one queue, not two.
 
+## 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.
+
+**The top rung is a switch.** `/multi-agent:model` turns `fable` on or off
+(`prefs.global.modelFallback.fableEnabled`, shipped off). The review commands,
+triage and the plan critic resolve their slots through it: on Claude Code,
+`/multi-agent:review` runs Fable + Opus + Sonnet while it is on and Opus + Sonnet
+while it is off.
+
 ## Stacks
 
 Stack skills ship as versioned plugins in the [`mmerterden/multi-agent-plugins`](https://github.com/mmerterden/multi-agent-plugins) marketplace. Select a stack per-repo:
@@ -369,17 +392,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 58 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 61 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 + 58 sub-command skills + scripts                                                         |
-| Codex CLI   | `--codex`            | one router skill + 58 specs as refs + 9 agent TOML + `AGENTS.md` block + `codex mcp add`               |
+| Copilot CLI | `--copilot`          | instructions + 61 sub-command skills + scripts                                                         |
+| Codex CLI   | `--codex`            | one router skill + 61 specs as refs + 10 agent TOML + `AGENTS.md` block + `codex mcp add`               |
 
 Filter skills by stack with `--platform=ios\|android\|all`.
 
-**Why Codex gets one skill and not 58.** Codex assembles every discovered skill's name
+**Why Codex gets one skill and not 61.** 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
@@ -387,7 +410,7 @@ error. Measured on 0.145: installing one plugin that declares 142 skills surface
 nothing until read - same commands, same behaviour, a layout the host can actually hold.
 
 Reviewer sets differ because the available models do: Claude Code runs 3 reviewers
-(Fable + Opus + Sonnet), Copilot CLI 3 (Opus + GPT-5.4 + Sonnet), Codex CLI 3 (gpt-5.6 at
+(Fable + Opus + Sonnet; 2 while the fable rung is off), Copilot CLI 3 (Opus + GPT-5.4 + Sonnet), Codex CLI 3 (gpt-5.6 at
 xhigh, gpt-5.4, gpt-5.6 at medium). Claude Code and Codex are single-vendor panels, so
 consensus among their three is weaker evidence than the same consensus on Copilot CLI,
 the one host whose panel spans two vendors, and the triage note says so.
@@ -398,12 +421,12 @@ the one host whose panel spans two vendors, and the triage note says so.
 
 | Token                 | Used for                                                         | Phase                   |
 | --------------------- | ---------------------------------------------------------------- | ----------------------- |
-| `jira`                | fetch the issue · post the report comment                        | 0, 7                    |
-| `github`              | issues · PRs · `gh` auth                                         | 0, 6                    |
-| `bitbucket`           | PR create/update (reviewer-preserving) · diff                    | 6                       |
-| `confluence`          | publish analysis / wiki pages                                    | 7                       |
+| `jira`                | fetch the issue · post the report comment                        | 0, 5                    |
+| `github`              | issues · PRs · `gh` auth                                         | 0, 4                    |
+| `bitbucket`           | PR create/update (reviewer-preserving) · diff                    | 4                       |
+| `confluence`          | publish analysis / wiki pages                                    | 5                       |
 | `figma` + `figma_mcp` | fetch design context                                             | analysis only           |
-| `fortify`             | security-scan findings gate                                      | 4                       |
+| `fortify`             | security-scan findings gate                                      | 2                       |
 | `firebase`            | Firebase service-account JSON for Firebase projects              | as needed               |
 | `jenkins`             | CI trigger / status                                              | build / deploy          |
 | `npm`                 | package publish (mostly CI)                                      | release                 |