@mmerterden/multi-agent-pipeline 16.28.0 → 16.29.0

package/pipeline/multi-agent-refs/features/doctor.md

@@ -0,0 +1,197 @@
+# doctor - the check registry
+
+Every check `/multi-agent:doctor` can report has a `### <id>` heading here, and
+`doctor.mjs --list-checks` prints exactly the same set. The equality is checked
+in both directions by `smoke-doctor.sh`: a check that ships without an entry
+cannot be released, and an entry whose check was deleted cannot linger as orphan
+prose. That is the mechanism that keeps this file from rotting into a list of
+things the tool used to do.
+
+## What the exit code means
+
+| Code | Meaning |
+|---|---|
+| 0 | healthy - nothing above INFO |
+| 1 | degraded - at least one WARN, no BLOCK |
+| 2 | blocked - at least one BLOCK |
+| 3 | usage error |
+| 4 | indeterminate - the installed layout could not be resolved, so nothing was checked |
+
+4 exists so that "I could not look" never borrows the exit code of "I looked and
+it is fine". A consumer that treats 0 as healthy would otherwise read a broken
+resolver as a clean bill.
+
+## What BLOCK means, exactly
+
+**A state in which a run will fail or leak. Not a state in which it will merely
+be worse.** Without a closed definition "blocked" grows until nobody respects
+exit 2, so only five checks can produce it: `install-present`, `script-surface`,
+`state-writable`, `prefs-valid` and `embedded-credentials`. Every other check
+tops out at WARN however bad it looks.
+
+## Who calls it, and what they do with the code
+
+| Caller | When | On exit 2 |
+|---|---|---|
+| `/multi-agent:setup` | before the first question, and again at the end | the closing run is the evidence for or against "setup complete" |
+| `/multi-agent:update` | after the install | report that the update left a state a run will fail from, rather than "updated" |
+| `/multi-agent:sync` | step 0 | **stop.** Syncing a blocked install copies one fault onto five surfaces, and the copies are what people then debug |
+
+`/multi-agent:sync` stops on exit 4 as well: the layout did not resolve, so
+nothing was checked, and syncing from an unknown state is worse than not syncing
+at all. Exit 1 never stops anything - a degraded install still syncs correctly,
+and a gate that blocked on every warning would be routed around within a week.
+
+## The four severities
+
+| Severity | Meaning |
+|---|---|
+| BLOCK | a run will fail or leak |
+| WARN | a run will work and be worse: a degraded capability, a stale copy, a rejected credential |
+| INFO | a capability the user chose not to enable; nothing to fix |
+| SKIP | not checked, and why |
+
+`SKIP` is printed in the same list, in the same position, and the summary always
+carries its count (`... 2 not checked, 15 checks`). Absence is a finding: a run
+without `--probe` exits 0 **and** prints `SKIP credential-liveness`, so "healthy"
+and "not looked at" are never the same output.
+
+The INFO / WARN boundary is already decided in `lib/credential-inventory.sh` and
+this tool only renders it: an unmapped key is INFO because it is a capability the
+user chose not to enable, while `auth-rejected`, `malformed` and
+`tier-1-no-grant` are WARN because the configuration made a claim the service
+refused. **A missing optional capability is information; a mapped credential the
+service rejected is a warning. The difference is whether the configuration
+asserted anything.**
+
+## The line shape
+
+```
+<SEV> <id>  -  <what is wrong>  -  <single imperative step>
+```
+
+The third field is one step, and its first word comes from a closed list:
+`run`, `set`, `map`, `revoke`, `install`, `remove`, `free`, `export`, `merge`,
+`record`, `re-run`. `consider`, `may want` and `should probably` are refused by
+the gate. One problem, one step: a reader with five suggestions does nothing.
+
+## It recommends, it never fixes
+
+Nothing here rewrites a remote URL, edits `settings.json` or touches a token.
+A remote whose URL carries a token may be the only credential that repo has, the
+remote may be a mirror a script depends on verbatim, and doctor can run inside a
+checkout the user does not own. Silent repair breaks all three.
+
+For an embedded credential the honest single step is **not** "hide it". A token
+that reached `.git/config` is already burned: it is in the shell history and
+readable by anything that can read the working tree. The step is to revoke it at
+its host; everything after that is behind `--explain`.
+
+---
+
+## Checks
+
+### install-present
+
+The installed tree exists and carries the subtrees a run reads: `commands/`,
+`multi-agent-refs/`, `scripts/`, `lib/`, `schemas/`. BLOCK when any is missing -
+a run cannot start without them.
+
+### install-version
+
+The installed `.pipeline-version` matches the package version resolved from the
+checkout or the published package. WARN on a mismatch: the run works, it just
+is not the version the user thinks they have.
+
+### script-surface
+
+Every script a shipped command names by path exists in the installed tree. BLOCK:
+the failure lands mid-run, at the call, with the phase already half done.
+
+### skill-siblings
+
+Every command has its copies in the host trees this machine installs. WARN, never
+BLOCK: an unsynced host is a fact about the machine, and `skill-siblings.mjs`
+itself reports the installed layout as "authored side not checked" rather than
+claiming a repo verdict it cannot reach.
+
+### state-writable
+
+`$HOME/.claude/logs/multi-agent` exists or can be created, and a file can be
+written there. BLOCK: a run that cannot record its state cannot be resumed,
+reported or priced, and it discovers this at Phase 0 after the pickers.
+
+### prefs-valid
+
+`multi-agent-preferences.json` parses and satisfies `schemas/prefs.schema.json`.
+BLOCK: Phase 0 reads it before anything else, and a malformed file fails the run
+after the user has already answered the pickers.
+
+### identity
+
+A git identity resolves for the account the run would commit as. WARN: the run
+reaches Phase 6 and stops there.
+
+### hook-coverage
+
+The blocking `PreToolUse` gates from `templates/claude-hooks.json` are present in
+`settings.json`. WARN. SKIP when the template is not installed - which was the
+permanent state until the installer began copying `templates/`, and is exactly
+the case this severity exists to make visible.
+
+### credential-mapping
+
+Which logical keys are mapped, and whether each mapped value is well formed.
+Unmapped is INFO. Malformed is WARN.
+
+### credential-liveness
+
+One cheap authenticated request per mapped credential. WARN on `auth-rejected`,
+`tier-1-no-grant` or `unreachable` - but with **different steps**, because a
+refused credential and a host that never answered need different actions.
+`credential-inventory.sh` already draws that line ("unreachable - no response at
+all - on a corporate host, almost always the VPN"), and telling someone to
+re-onboard a token that was never the problem is the exact failure the keychain
+rules warn about one layer up. **SKIP unless `--probe` is passed**, and the
+skip is printed, because a network check is the user's decision to spend.
+
+### embedded-credentials
+
+A token in a git remote URL or a tracked config file. BLOCK: this one leaks
+rather than fails.
+
+The report carries the repo path, the config key, the **host**, a shape label and
+a length bucket. Never the value, and not the prefix either: `ghp_` plus a length
+is already a fingerprint, and this line is printed to a terminal that is often
+shared, which is the whole reason the check exists. The URL is parsed inside a
+`python3` heredoc reading stdin, so no shell variable ever holds it.
+
+### task-tools
+
+Whether this session's model carries `TaskCreate` / `TaskUpdate`. Claude Code
+provides them by default only on Claude 3.x, Opus 4 through 4.7, Sonnet 4 through
+4.6 and Haiku 4.5; on any newer model they are absent unless the user opts in.
+INFO, with the opt-in as the step.
+
+A script cannot answer this - only the agent knows its own tool list - so the
+caller passes `--task-tools=yes|no` and the default is SKIP. Reporting "absent"
+from a script that never looked would be the same defect this check is about.
+
+### mcp-registration
+
+Whether `multi-agent-toolkit` is registered as an MCP server. INFO when it is
+not: the tools it provides are optional and a run without them is smaller, not
+wrong.
+
+**Registered is not the same as working.** With `--probe` the server is started
+and its tools counted; serving none is WARN. Without `--probe` this reports what
+is configured, and says so. The distinction is not theoretical: a half-extracted
+package in the npx cache left the server dying on `Cannot find module` at
+startup, which the client surfaces only as `CONNECTION_CLOSED`, and a check that
+read the registration and stopped would have called that healthy.
+
+### disk-space
+
+Free space on the volume holding `$HOME`. WARN under 2 GB: a worktree plus a
+build is the largest thing a run writes, and ENOSPC mid-run corrupts the state
+file it was writing at the time.

package/pipeline/multi-agent-refs/features/model-fallback.md

@@ -83,7 +83,7 @@ predate this field still get the second downgrade step):
   "premiumTierUntil": null,
   "fallbackModel": "sonnet",
   "floorModel": "haiku",
-  "fableEnabled": true,
+  "fableEnabled": false,
   "onDispatchError": true
 }
 ```
@@ -91,7 +91,7 @@ predate this field still get the second downgrade step):
 | Field | Meaning |
 |---|---|
 | `enabled` | Master switch. `false` = always dispatch the persona's `preferredModel`, fail loudly on error. |
-| `modelFallback.fableEnabled` | Whether the `fable` rung exists at all on Claude Code. `false` starts every `preferredModel: fable` persona on `opus`. See "Turning the fable rung off" below. |
+| `modelFallback.fableEnabled` | Whether the `fable` rung exists at all on Claude Code. **Ships `false`.** `false` starts every `preferredModel: fable` persona on `opus`; set it to `true` to opt the top rung back in. A cost control that defaults to on is not a control. See "Turning the fable rung off" below. |
 | `premiumTierUntil` | ISO date (`YYYY-MM-DD`) or `null`. When set and today is **after** this date, every `preferredModel` dispatch is downgraded to `fallbackModel` unless the user re-confirms (see Date gate). Use when the top tier is included in a plan only until a known date. |
 | `fallbackModel` | Target of the first downgrade step. Default `sonnet` (the next tier below opus). |
 | `modelFallback.floorModel` | Last-resort tier when `fallbackModel` also fails to dispatch. Default `haiku`. Set to the same value as `fallbackModel` (or `null`) to disable the second step and halt after one downgrade. |

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

@@ -275,11 +275,8 @@ Scan `$HOME` (maxdepth 2) for project markers (`.xcodeproj`, `Package.swift`, `b
      | grep -v -E '(feature/|bugfix/|fix/|hotfix/|chore/)'
    ```
 6. Sort: `develop*` first, then `release/*`, then `main`/`master`. Surface through the
-   **native picker** per `picker-contract.md` (`AskUserQuestion` on Claude Code,
-   `ask-choice.sh` on Copilot CLI) - `question` + `description` in `outputLanguage`,
-   `label` = the branch name verbatim (a proper noun, never translated) with the recent
-   branch first and marked `(Recommended)`. The ASCII sketch
-   below is what the options carry, not a menu to print:
+   **native picker** per `picker-contract.md`, recent branch first and marked
+   `(Recommended)`:
 
    ```
    header: "Base branch"
@@ -298,9 +295,14 @@ nothing surfaced it. `phase0-exit-gate.mjs` now refuses to close Phase 0 unless
 `agent-state.json` carries `baseBranch` and `baseFetchStatus`, so a skipped picker is a
 gate failure rather than a silent default.
 
+One row is a normal outcome of the rule-5 filter and is **still asked** - see
+`picker-contract.md` "A single candidate is still 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 to their defaults without prompting,
-which still writes the fields - it does not leave them unset.
+does not skip Phase 0's pickers. Autopilot resolves them without prompting, which still
+writes the fields. For the base branch it reads `recentBranches[{projectKey}]` (most
+recent inside the TTL, still on the remote) before the rule-6 order, recording which
+fired in `state.baseBranchSource`.
 
 **TTL filter for recent branches**:
 

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

@@ -75,10 +75,45 @@ identifies which option, not what the button said.
 The host injects its own **Other** free-text row in English on every run. Nothing in
 the pipeline can localize it, and no option may depend on its wording.
 
+## Order: project, then repo, then branch
+
+A picker may only be asked once everything it depends on is settled, and the
+dependency runs one way: a base branch is a property of a repo, and a repo is a
+property of a project. Asking for a branch before the dev-context repo set is
+known means the answer was given about a repo the run had not chosen yet, and
+nothing downstream can tell that apart from a correct answer.
+
+So: project selection, then `_dev-context.md`, then the base branch. A step whose
+input is not yet resolved waits; it does not guess and it does not resolve its own
+input with a second question.
+
+## A single candidate is still a question
+
+The number of options never authorises a skip. A filter that leaves one row has
+narrowed the world; it has not decided anything, and the host's **Other** row is a real
+choice on every picker - a branch the filter excluded, an account the probe missed, a
+repo git does not know about. "There was only one option, so I picked it" is a skipped
+picker, and announcing the pick in prose first is the same skip with a sentence in front
+of it.
+
+This is the failure that is hardest to see afterwards, because the transcript reads like
+a decision was made. Only the picker's absence records that the user was never asked.
+
 ## Autopilot / non-interactive contract
 
 In autopilot, `ask_choice` resolves to `default` (or the safe first option) without prompting - identical to how the native gates auto-proceed today. A picker is only surfaced for genuinely ambiguous or destructive decisions, matching the maturity-check model.
 
+**Memory outranks the default.** Where the pipeline has recorded what this user chose
+last time for this project - `prefs.global.recentBranches[{projectKey}]` is the one that
+exists today - autopilot resolves from that record first, and only falls back to the
+option order when the record is empty, stale past its TTL, or names something that no
+longer exists. A remembered choice is evidence about this user and this repo; an option
+order is a guess that happens to be sorted. Where the two agree nothing changes, and
+where they disagree the remembered one is the answer with a reason behind it.
+
+The run records which rule fired (`remembered` or `default`). An autopilot run cannot be
+asked anything, so the only thing that keeps it accountable is being readable afterwards.
+
 ## Deterministic gates note
 
 Claude Code's `PreToolUse` exit-2 hooks are the HARD blocking gates. Three ship, none needing run-specific arguments so they are naturally hookable: (1) `pre-commit-check.sh` scans the staged diff on every `git commit` and blocks on a detected secret; (2) `agent-guard.sh` runs on `git commit` + `git push` and blocks AI/assistant attribution in a commit message and force-push to a protected branch (main/master/develop); (3) `check-read-size.sh` runs on `Read` and on the shell commands that read a file whole, and routes an oversized read to a cheap worker (`bulk-read.sh`) instead of the caller's own rung. The first two inspect what a run WRITES; the third inspects what it pays to READ, and it is inert until `bulkRead.mode` is set to `observe` or `enforce`, so merging the block changes nothing until the user opts in. Its `observe` mode blocks nothing and only logs, which is how the baseline is measured before anything is routed. All three are self-contained, fail-open on internal error, and never execute the inspected command. Two capture hooks ship in the same block and block nothing: `SessionEnd` runs `capture-flush.sh --if-stale` (writing a killed run's findings into the per-repo stores, since every durable write used to live in Phase 7 - the phase a run is least likely to reach) plus `note-session.sh` (the mechanical shape of a non-pipeline session: tools used, commands that failed, calls the user refused - never an argument, never any output), and `SessionStart` runs `capture-resume.sh`, at most two lines about an unfinished run and a stale observation queue. Neither calls a model; both exit 0 on every path. The recommended hook block ships at `install/templates/claude-hooks.json`; `multi-agent:setup` offers to merge it into `~/.claude/settings.json`. The other deterministic gates (evidence, consensus, intent, learnings) are invoked by the pipeline phases with per-run arguments (a build-log path, the triage JSON, the free-text input), so they are phase-enforced by contract, not OS-hookable.

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

@@ -32,7 +32,7 @@ Visual mechanism per CLI:
 
 | CLI | What the agent calls at every phase boundary |
 |---|---|
-| **claude-code** | `TaskCreate({subject, activeForm})` then `TaskUpdate({status, activeForm})`. Native sticky widget; ⏺ tiles, spinner header. |
+| **claude-code** | `TaskCreate({subject, activeForm})` then `TaskUpdate({status, activeForm})`. Native sticky widget; ⏺ tiles, spinner header. **Not in every session** - see below. |
 | **copilot** | Inline call: `bash phase-tracker.sh render`. The bordered ANSI card lands as the last tool result in the chat. |
 | **codex** | The native `update_plan` tool: one plan step per phase, `status: pending \| in_progress \| completed`. Rewrite the whole step list on each boundary  -  the tool takes the full plan, not a delta. |
 | **generic** (plain shell, Git Bash, WSL, tmux) | Same bash render  -  the bordered ANSI card prints to terminal stdout in place. |
@@ -41,6 +41,10 @@ Visual mechanism per CLI:
 
 **Claude Code only**: in addition, `TaskCreate` / `TaskUpdate` native tool calls → the sticky widget pins the phase stack in the user's view.
 
+**The task tools depend on the MODEL, not the CLI version.** Claude Code provides `TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList` and `TodoWrite` by default only on Claude 3.x, Opus 4 through 4.7, Sonnet 4 through 4.6 and Haiku 4.5; on any newer model it leaves them out unless the user opts in. That default arrived in Claude Code v2.1.268, and this contract was written when the tools were universal, so nothing noticed the change: a run wrote its tracker state correctly, advanced every phase, and drew nothing for the whole run.
+
+So the branch is taken by the agent, which knows its own tool list, and never by the shell, which cannot see it. Without the tools the bordered card IS the widget and has to be reprinted inside the reply at every boundary, exactly as on Copilot CLI. Say once, in `outputLanguage`, that the native widget returns with `CLAUDE_CODE_ENABLE_TODO_TOOLS=1 claude` (or `claude --allowedTools TaskCreate`); a user staring at a missing widget needs the command, not the diagnosis. A subagent inherits the session's tool set even when it runs a different model, so this is a session-level fact and not a per-phase one.
+
 ### Codex specifics
 
 Two constraints on `update_plan`, both of which fail quietly if ignored:

package/pipeline/preferences-template.json

@@ -63,7 +63,7 @@
       "premiumTierUntil": null,
       "fallbackModel": "sonnet",
       "floorModel": "haiku",
-      "fableEnabled": true,
+      "fableEnabled": false,
       "onDispatchError": true
     },
     "costBudget": {

package/pipeline/schemas/agent-state.schema.json

@@ -76,6 +76,11 @@
       "type": "string",
       "description": "PR target branch (e.g. develop, main)."
     },
+    "baseBranchSource": {
+      "type": "string",
+      "enum": ["asked", "input", "remembered", "default"],
+      "description": "How baseBranch was decided. asked = the user answered the Step 3 picker; input = it arrived with the task reference; remembered = autopilot took the most recent entry in prefs.global.recentBranches still inside the TTL and still on the remote; default = autopilot fell back to the develop/release/main sort order. An autopilot run cannot be asked anything, so recording which rule fired is what keeps it readable afterwards."
+    },
     "remoteType": {
       "type": "string",
       "enum": ["github", "bitbucket"],