@mmerterden/multi-agent-pipeline 20.24.0 → 20.25.0

package/pipeline/multi-agent-refs/features/dep-bump.md

@@ -0,0 +1,176 @@
+# Feature: Dependency Bump and Fix
+
+<!-- toc -->
+- [1. Shape of a run](#1-shape-of-a-run)
+- [2. The script](#2-the-script)
+- [3. What each phase does](#3-what-each-phase-does)
+- [4. Scope of a fix round](#4-scope-of-a-fix-round)
+- [5. Rollback](#5-rollback)
+- [6. Settings](#6-settings)
+- [7. Never](#7-never)
+<!-- /toc -->
+
+**Pattern**: bump one dependency, build and test, and when the bump breaks
+something, fix only that breakage. A bump PR that also refactors, reformats or
+"while I was here" fixes unrelated code cannot be reviewed as a bump, and a fix
+loop with no cap turns a version bump into an open-ended rewrite.
+
+Entry: `/multi-agent:deps [package[@version]] [--major]`. It is the normal
+pipeline with a fixed task, not a second flow: same Phase 0 intake, worktree,
+branch rules, Phase 2 dev agent and exit gate, Phase 3 review gates, Phase 4
+commit and PR rules, Phase 5 channels.
+
+## 1. Shape of a run
+
+| Field | Value |
+|---|---|
+| `state.mode` | `"deps"` |
+| `state.taskType` | `chore` |
+| Branch | `chore/deps-{kebab(name)}-{kebab(to)}`, kebab and collision rules from Phase 0 Step 4 |
+| Commit | `chore(deps): bump {name} from {from} to {to}`, taken verbatim from `dep-bump.mjs apply` (`commitMessage`), plus ` [{jiraId}]` when the run carries one |
+| PR body | the bump, its risk, the lockfile command, `alsoMoves`, the changelog excerpt, each fix and the error line it answers; `Ref:` / `Related:`, never `Closes` / `Fixes` / `Resolves` |
+| `state.depBump` | the apply output plus `rounds`, `scope` and, on rollback, `rolledBack` and `stillFailing` |
+
+## 2. The script
+
+`$HOME/.claude/scripts/dep-bump.mjs` owns every deterministic step; the model
+never edits a version string by hand. JSON on stdout.
+
+| Command | Does |
+|---|---|
+| `detect --dir D` | Ecosystems and manifests: SwiftPM `Package.swift`, Gradle `gradle/*.versions.toml`, npm `package.json`, pip `requirements*.txt` / `pyproject.toml`, each with its lockfile |
+| `list --dir D [--registry]` | Candidates: `current` (lockfile, else declared), `latest`, `latestInMajor` (highest non-breaking), `risk`, `riskInMajor`, `source` |
+| `apply --dir D --ecosystem E --name N --to V [--allow-major]` | One bump: manifest edit plus the lockfile through the ecosystem tool; writes `.pipeline/dep-bump.json` |
+| `surface --dir D --ecosystem E --name N` | Files that import or reference the dependency |
+| `scope --dir D [--log L]` | Files changed since the recorded base, split into `inScope` (manifest, lockfile and the surface recorded at apply), `newImporters` and `outOfScope`; exit 1 when anything is out of scope or a new importer has no cited error line |
+| `notes --dir D --ecosystem E --name N --from A --to B` | The local changelog sections between the two versions, else the repository URL to read release notes from |
+| `rollback --dir D` | Restores what the bump owns (manifest, lockfile, the files `scope` saw the fix touch in scope) from the recorded base and removes those the base lacks; every other change is left in place and listed under `kept` |
+| `config` | The resolved `depBump.*` settings |
+
+SwiftPM identities compare case-insensitively (`--name Alamofire` and
+`alamofire` are one package). The surface covers every module name the package
+is imported under: the identity, the repository name in the url, the products
+named by `.product(name:package:)` and by-name target dependencies in the
+package manifests. Packages an Xcode project adds through File > Packages keep
+their pins in `*.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved`
+or `*.xcworkspace/xcshareddata/swiftpm/Package.resolved` and their requirement
+in `project.pbxproj`. `detect` and `list` report them with `readOnly: true` and
+a note; `apply` refuses them (exit 1), because dep-bump does not edit
+`project.pbxproj`. Such a bump is made in Xcode.
+
+For Gradle the surface is the build scripts that name the catalog alias and
+the Kotlin and Java files whose imports start at the Maven group
+(`com.google.code.gson`), the artifact id or the alias stem, each with an
+optional major suffix (`okhttp3` for `com.squareup.okhttp3:okhttp`, `retrofit2`
+for `retrofit`). A library whose package root is none of these (Gson's
+`com.google.gson`) is not found by `surface`, so a fix in such a file is out of
+scope and needs the error line that names it, cited per file (section 4).
+
+Offline listing reads what is already on disk: the lockfile for the current
+version, SwiftPM `.build/checkouts/<id>` tags and the Gradle module cache for
+newer ones. `--registry` asks the ecosystem's own tool (`npm view`,
+`git ls-remote --tags`, Maven or PyPI metadata over `curl`); a failed query is
+a `note` on that package, never a failed listing. Registry and lockfile tools
+run in the manifest's directory (a workspace member's lockfile tool in the
+workspace root), so the repo's own `.npmrc` registries and scopes apply. A
+name or url that does not fit its ecosystem's grammar (a url that is not
+http(s), ssh, git, file or `git@host:`, a name starting with `-`) is never
+passed to a tool; the package gets a `registry query skipped` note.
+
+Risk follows semver: a major step is breaking, and so is a minor step under
+`0.x` and any step under `0.0.x`. `+build` metadata is ignored, and for Gradle
+a Maven release qualifier (`-jre`, `-android`, `.Final`, `-RELEASE`, `.GA`,
+`.SP1`) is part of a stable version, not a prerelease. A version that does not
+parse is `unknown` and is treated as major, and so is a prerelease target.
+`apply` exits 3 on a major, unknown or prerelease bump without `--allow-major`,
+and touches nothing.
+
+A pip requirement with several clauses (`foo>=1.0,<2.0`) is bumped on its
+primary clause, the first `==`, `===`, `~=`, `>=` or `>`; `<`, `<=` and `!=`
+are never primary, and a requirement made only of them is not listed. When
+another clause would exclude the target (`<2.0` against `2.1`), `apply` exits 1
+and changes nothing: rewriting a bound the repo set is a decision, not part of
+the bump.
+
+`apply` refuses a worktree with uncommitted changes to tracked files (exit 1,
+`dirty` lists them), so the base it records holds no work of anyone else's.
+
+`apply` is atomic. When the lockfile tool fails, the manifest and the lockfile
+are restored byte for byte and the tool's output tail is in `lock.output`.
+Lockfile tools: `swift package resolve`, `./gradlew dependencies --write-locks`
+(only with a `gradle.lockfile`), the resolved npm-family manager with scripts
+disabled (`package-manager.mjs`; yarn 2 and later take `--mode=skip-build`, yarn
+1 `--ignore-scripts`), `poetry lock` on Poetry 2 and `poetry lock --no-update`
+before it, `uv lock --upgrade-package`. A workspace member's lockfile is the
+workspace root's (the nearest directory above it with a lockfile and a
+`workspaces` field or `pnpm-workspace.yaml`), and the tool runs there; a
+lockfile above the manifest in a directory that declares no workspaces fails
+the bump rather than letting it go ahead with no lockfile. Membership is not
+matched against the `workspaces` globs. A shared Gradle `version.ref` moves every module bound to
+it; `alsoMoves` names them and they join the surface.
+
+## 3. What each phase does
+
+| Phase | In a deps run |
+|---|---|
+| 0 Init | Candidate pick and the major gate happen in the command before Phase 0. Then the normal intake (account, repo, base branch, workspace) with the free-text task `chore(deps): bump {name} from {from} to {to}`, `taskType` `chore`, branch from section 1 |
+| 1 Plan | No analysis document (`chore`). The plan is fixed: one todo, "apply the bump", plus one per failing area once Phase 2 has a red run. `notes` output and the `list` record are the plan's evidence. The approval gate shows the bump, its risk and `alsoMoves` |
+| 2 Dev | `apply` in the worktree first, before any agent runs. Then the Phase 2 exit gate as written (build, lint, tests, evidence gates). Green: straight to Phase 3 with no dev agent. Red: fix rounds (section 4) |
+| 3 Review | The standard gates and reviewers over the whole diff. `scope` runs first; every `outOfScope` file is a blocking finding unless the round's report ties it to a build or test error line |
+| 4 Commit | `commitMessage` from `apply`, the PR body from section 1. Never auto-close an issue |
+| 5 Report | Channels as in every mode |
+
+## 4. Scope of a fix round
+
+A round is one Phase 2 dev dispatch, given exactly this:
+
+- the failing build or test log tail, from the exit gate;
+- `surface` output: the files that use the dependency;
+- the `notes` excerpt (breaking changes, migration notes). With no local
+  changelog, read the release notes for the versions in between from the
+  repository URL it returns (`gh release view`, the releases page) when
+  reachable, and say when they were not;
+- the rule: change only what the bump broke. A file outside the surface may be
+  touched only when a compile or test error names it, and the report cites that
+  error line per file.
+
+The surface is the one `apply` recorded. A file that starts importing the
+dependency during a fix round does not join it: `scope` reports it under
+`newImporters`, and each one passes only when the build or test log handed to
+`scope --log` has an error line naming that file. The line is returned as
+`cited`; a new importer with `cited: null` fails scope like an out-of-scope
+file.
+
+After each round: `scope --log <exit-gate log>`, then the exit gate again. Out-of-scope files with no
+cited error are reverted before the next round. Green ends the loop. Every round
+is recorded in `state.depBump.rounds[]` with the files it touched and the
+errors it answered.
+
+## 5. Rollback
+
+A run still red after `depBump.maxFixRounds` rounds (default 2), or out of
+scope after its last round, is not committed: `dep-bump.mjs rollback` returns
+the manifest, the lockfile and the files the fix rounds touched to the recorded
+base, removes the ones the base did not have, and leaves every other change in
+place (`kept`); the run ends with a report instead of a PR. The report names the bump, each round, the errors still failing with their
+log lines, the files that would need to change and the changelog section that
+explains it. `state.depBump.rolledBack` is `true`. The branch is left with no
+commit; nothing is pushed.
+
+## 6. Settings
+
+| Key | Default | Effect |
+|---|---|---|
+| `depBump.maxFixRounds` | 2 | Fix rounds before rollback; 0 rolls back any bump that is not green as-is |
+| `depBump.queryRegistry` | true | `list` gets `--registry`; false lists offline only |
+
+Read through `node "$HOME/.claude/scripts/dep-bump.mjs" config`. Asserted by
+`test/dep-bump.test.mjs` and `smoke-dep-bump.sh`.
+
+## 7. Never
+
+- A major, unparseable or prerelease bump without `--major` or an explicit confirmation.
+- A version edit by hand, or a lockfile edited as text.
+- More than one dependency per run (a shared `version.ref` is one bump).
+- A fix outside the bump's surface with no error line behind it.
+- A commit after the round cap is reached red.

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

@@ -11,17 +11,17 @@
 - [Codex CLI](#codex-cli)
 <!-- /toc -->
 
-> Contract last revised in **v10.6.0** (Fable 5 restored as top tier). The version tag here tracks the last substantive change to this contract, not the pipeline release.
+> Contract last revised in **v20.25.0** (current Claude generation; Copilot CLI model ids per rung). The version tag here tracks the last substantive change to this contract, not the pipeline release.
 
 Personas route to the top available intelligence tier they declare in
 `preferredModel`. That tier can be quota-limited or temporarily unavailable.
 This contract defines when and how the orchestrator falls back, deterministically,
 without ever editing persona files at runtime.
 
-> **Fable 5 available again (2026-07).** `claude-fable-5` is the top tier once
-> more. Architect (`ios/android/backend-architect`), Reviewer-1 (`code-reviewer`),
+> **Fable is the top tier.** The `fable` rung resolves to `claude-fable-5-1`.
+> Architect (`ios/android/backend-architect`), Reviewer-1 (`code-reviewer`),
 > and triage personas declare `preferredModel: fable` - the deepest-reasoning
-> roles. **If Fable 5 is unavailable, the first fallback is opus (`claude-opus-5`).**
+> roles. **If Fable is unavailable, the first fallback is opus (`claude-opus-5-5`).**
 > Security and other `preferredModel: opus` personas keep opus as their top tier.
 > The `premiumTierUntil` date gate stays in the contract as a generic mechanism
 > for any plan-window-limited premium tier.
@@ -35,7 +35,7 @@ fable -> opus -> sonnet -> haiku
 The orchestrator walks **one step down per trigger** from whichever tier a
 persona prefers: a `fable` persona degrades `fable -> opus` first, then
 `opus -> sonnet`, then `sonnet -> haiku`; an `opus` persona starts at
-`opus -> sonnet`. So a Fable 5 outage transparently promotes Opus 5 into the
+`opus -> sonnet`. So a Fable outage transparently promotes Opus into the
 architect/reviewer roles with no file edits.
 
 ### Rung names are the contract; model IDs are not
@@ -46,11 +46,16 @@ model ID each rung resolves to lives in exactly two places: `scripts/cost-table.
 `phases/phase-3-review.md`. A generation move edits those; it never renames a rung and
 never touches a persona file.
 
-Current resolution: `fable` -> `claude-fable-5`, `opus` -> `claude-opus-5`,
-`sonnet` -> `claude-sonnet-5`, `haiku` -> `claude-haiku-4-5`.
+Current resolution: `fable` -> `claude-fable-5-1`, `opus` -> `claude-opus-5-5`,
+`sonnet` -> `claude-sonnet-5-5`, `haiku` -> `claude-haiku-5-5`. These are the Claude Code
+wire IDs. Copilot CLI dispatches only the models `copilot help config` lists, with dotted
+names, so its column in the reviewer table names those (`claude-opus-4.7`,
+`claude-sonnet-4.6`), recorded per rung as `copilotModelId` in the cost table (haiku:
+`claude-haiku-4.5`). The fable rung has none and is not offered on Copilot CLI; a persona
+that prefers it dispatches the opus rung there.
 
-**Rate limits do not follow the rung.** Claude Opus 5 draws on a pool separate from
-the combined Opus 4.x pool, so a generation move does not inherit the previous
+**Rate limits do not follow the rung.** A new generation can draw on a rate-limit pool
+separate from the previous one, so a generation move does not inherit the previous
 generation's headroom. Budget-ceiling downgrades below are unaffected - they read the
 cost ledger, not the provider's quota - but a 429 on the opus rung after a generation
 move is a limits question, not a fallback-contract question.
@@ -119,8 +124,8 @@ Scope is Claude Code only, and the reason differs per host:
 
 | Host | Effect of `fableEnabled: false` | Why |
 |---|---|---|
-| Claude Code | Every `preferredModel: fable` persona (`ios/android/backend-architect`, `code-reviewer`, triage) starts on `opus` | This is the only host where the rung means Fable 5 |
-| Copilot CLI | none | Fable 5 is not offered there; its personas never sat on this rung |
+| Claude Code | Every `preferredModel: fable` persona (`ios/android/backend-architect`, `code-reviewer`, triage) starts on `opus` | This is the only host where the rung means Fable 5.1 |
+| Copilot CLI | none | Fable is not offered there; its personas never sat on this rung |
 | Codex CLI | none, deliberately | The `fable` rung there means `gpt-5.6 @ xhigh`, a different model on a different account. Switching it off from a knob named after an Anthropic model would surprise a Codex user, so it does not |
 
 **Phase 4 loses a reviewer, and says so.** Reviewer 1 lands on `opus`, which
@@ -250,7 +255,7 @@ better internals.
 - No edits to `pipeline/agents/*.md` at runtime; frontmatter is install-time
   configuration only.
 - Copilot CLI reviewer set is out of scope: Copilot CLI pins its own three
-  reviewer models (GPT-5.4 + Opus + Sonnet - Fable 5 is not offered there) and
+  reviewer models (GPT-5.4 + Opus + Sonnet - Fable is not offered there) and
   does not use this persona ladder. Only Claude Code dispatches Reviewer-1 on
   Fable.
 

package/pipeline/multi-agent-refs/help/en.md

@@ -61,6 +61,7 @@ Pipeline entries:
 
   /multi-agent "task"                  Worktree
   /multi-agent:autopilot "task"        Worktree, no questions
+  /multi-agent:deps [pkg[@ver]] [--major]  Bump one dependency, fix only what the bump broke, review, PR; rolls back past depBump.maxFixRounds
 
   Phase 0 Step 5b asks where the branch lives; there is no flag for it.
   autopilot skips every confirmation INCLUDING the plan gate and the workspace

package/pipeline/multi-agent-refs/help/tr.md

@@ -61,6 +61,7 @@ Pipeline girişleri:
 
   /multi-agent "task"                  Worktree var
   /multi-agent:autopilot "task"        Worktree var, soru yok
+  /multi-agent:deps [paket[@sürüm]] [--major]  Tek bağımlılığı yükselt, yalnızca yükseltmenin kırdığını düzelt, review, PR; depBump.maxFixRounds aşılınca geri alır
 
   Faz 0 Adım 5b branch'in nerede yaşayacağını sorar; bayrağı yok.
   autopilot plan kapısı ve çalışma alanı sorusu dahil her onayı atlar, otomatik

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

@@ -652,7 +652,7 @@ Log: `Phase 0 Step 7.7: testDepth = {unit|unit+ui|unit+mcp} (source {user|autopi
 
 5. Phase 1 Analysis reads `state.clarification.userAnswers` (when present) as additional context  -  fold answers into the Explore prompt so downstream phases inherit the resolution.
 
-**Reference:** `$HOME/.claude/agents/task-clarifier.md`  -  scoring rubric, question-quality rules and the ~$0.0025-per-call cost note.
+**Reference:** `$HOME/.claude/agents/task-clarifier.md`  -  scoring rubric, question-quality rules and the ~$0.0004-per-call cost note.
 
 #### Telemetry
 

package/pipeline/multi-agent-refs/phases/phase-2-dev.md

@@ -57,6 +57,8 @@ Phase 2 consumes the Phase 1 output object conforming to `$HOME/.claude/schemas/
 
 **Shadow-Git checkpoints (opt-in)**: gated by `prefs.global.shadowGit.enabled` (default: `false`). When enabled, the orchestrator snapshots the worktree via `$HOME/.claude/lib/shadow-git.sh` so sub-phase rollback is possible without touching the project's real `.git` history. Lifecycle: `shadow-git.sh init` (Phase 0 baseline), `shadow-git.sh snapshot` (per step after `plan-todos complete`), `shadow-git.sh restore <sha> --files` (rollback). Modes: `per-todo-step` (default) or `per-tool-call`. Full wiring + storage cap: `$HOME/.claude/multi-agent-refs/features/shadow-git.md`.
 
+**Dependency bump** (`state.mode == "deps"`): `dep-bump.mjs apply` first, then capped fix rounds: `$HOME/.claude/multi-agent-refs/features/dep-bump.md`.
+
 #### Component tasks  -  delegated dispatch (taskType === "component")
 
 When Phase 0 Step 7 classified the task as `component`, Phase 2 delegates the entire phase to the enabled `ai-<platform>-toolkit` marketplace plugin's component skill (`create-component`, fallback `create-ui-component`) via the Skill tool and does NOT run the TDD loop below. The dispatch layer passes the plugin skill the analysis Section 6 (Bileşen Envanteri) entry + Section 13.1 conventions for the named component as context. Because plugin skills do not write pipeline state, the **dispatch layer** (not the skill) owns `state.phases["2"].subphases[]`, recording a coarse component-build row - multi-agent's `phase-tracker` reads that array with no special case. Plugin resolution (dual-name), dispatch call, failure/resume, multi-repo, and the intentional cross-CLI divergence live in `$HOME/.claude/multi-agent-refs/component-dispatch.md` - read it before editing component-task behaviour here. Phase 2 still owns: progress line `-> dispatching create-component <name>`, `retryCount` cap at 3, and fallthrough to the TDD path when dispatch prerequisites are missing (`taskType` absent OR the plugin is not enabled in this repo -> log anomaly, halt or run TDD per component-dispatch.md).

package/pipeline/multi-agent-refs/phases/phase-3-review.md

@@ -237,10 +237,10 @@ Launch Agent instances **in parallel** using the shared `code-reviewer` subagent
 
 | Reviewer   | subagent_type   | Claude Code | Copilot CLI | Codex CLI | Focus | Skills Referenced |
 | ---------- | --------------- | --- | --- | --- | --- | --- |
-| Reviewer 1 | `code-reviewer` | `claude-fable-5` | `claude-opus-5` | `gpt-5.6` @ `xhigh` | Deep security + architecture | `api-security-best-practices`, `architecture` |
-| Reviewer 2 | `code-reviewer` | `claude-opus-5` | `gpt-5.4` | `gpt-5.4` @ `high` | Edge cases, different perspective | cross-model diversity |
-| Reviewer 3 | `code-reviewer` | `claude-sonnet-5` | `claude-sonnet-5` | `gpt-5.6` @ `medium` | Quality + correctness + naming | `ai-backend-toolkit:clean-code`, stack-specific skill |
-| Triage     | triage persona  | `claude-fable-5` | `claude-opus-5` | `gpt-5.6` @ `max` | Filter false positives + out-of-scope | - |
+| Reviewer 1 | `code-reviewer` | `claude-fable-5-1` | `claude-opus-4.7` | `gpt-5.6` @ `xhigh` | Deep security + architecture | `api-security-best-practices`, `architecture` |
+| Reviewer 2 | `code-reviewer` | `claude-opus-5-5` | `gpt-5.4` | `gpt-5.4` @ `high` | Edge cases, different perspective | cross-model diversity |
+| Reviewer 3 | `code-reviewer` | `claude-sonnet-5-5` | `claude-sonnet-4.6` | `gpt-5.6` @ `medium` | Quality + correctness + naming | `ai-backend-toolkit:clean-code`, stack-specific skill |
+| Triage     | triage persona  | `claude-fable-5-1` | `claude-opus-4.7` | `gpt-5.6` @ `max` | Filter false positives + out-of-scope | - |
 
 Reviewer count per host: **Claude Code 3, Copilot CLI 3, Codex CLI 3**  -  **2** on Claude Code with the fable rung off, per `$HOME/.claude/multi-agent-refs/features/model-fallback.md`.
 
@@ -265,7 +265,7 @@ borderline finding. Where the diversity budget goes instead:
 
 Each reviewer inherits the `code-reviewer` agent's focus areas (Security, Architecture, Quality, Performance) and output contract. The orchestrator overrides only the model and the stack-specific skill per-reviewer  -  no prompt duplication.
 
-**Model override wiring:** `code-reviewer.md` declares `preferredModel: fable`, so Reviewer 1 uses the persona default (Fable 5). Reviewer 2 (`claude-opus-5` on Claude Code, `gpt-5.4` elsewhere) and Reviewer 3 (`claude-sonnet-5`) set `PHASE_MODEL_OVERRIDE=<model>` before dispatch  -  the orchestrator exports `CLAUDE_CODE_SUBAGENT_MODEL` on Claude Code, or passes `--model` on Copilot CLI. Full precedence rule: `skills/shared/core/multi-agent/SKILL.md#agent-dispatch--per-persona-model-routing`. Fable dispatches are subject to the fallback contract (`$HOME/.claude/multi-agent-refs/features/model-fallback.md`): dispatch-error retry walks `fable -> opus -> sonnet` and budget-ceiling downgrade.
+**Model override wiring:** `code-reviewer.md` declares `preferredModel: fable`, so Reviewer 1 uses the persona default (Fable 5.1). Reviewer 2 (`claude-opus-5-5` on Claude Code, `gpt-5.4` elsewhere) and Reviewer 3 (sonnet rung, per host above) set `PHASE_MODEL_OVERRIDE=<model>` before dispatch  -  the orchestrator exports `CLAUDE_CODE_SUBAGENT_MODEL` on Claude Code, or passes `--model` on Copilot CLI. Full precedence rule: `skills/shared/core/multi-agent/SKILL.md#agent-dispatch--per-persona-model-routing`. Fable dispatches are subject to the fallback contract (`$HOME/.claude/multi-agent-refs/features/model-fallback.md`): dispatch-error retry walks `fable -> opus -> sonnet` and budget-ceiling downgrade.
 
 **Stack-specific skills loaded per reviewer** (from Phase 1 `detectedStack`). All three columns are used on every host; Reviewer 2 reads them as Opus on Claude Code and as GPT-5.4 elsewhere.
 

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

@@ -190,6 +190,6 @@ park it writes `agent-state.json` beside its tracker with `taskId`,
 
 ## 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 and never execute the inspected command. On an internal error they let the call through in an attended session; `agent-guard.sh` blocks instead under `MULTI_AGENT_UNATTENDED=1`, where nobody is watching to notice a gap. Three 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, so they do not depend on the run reaching Phase 5) 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), `PreCompact` runs `capture-flush.sh` without `--if-stale` (a compaction summarizes a long phase mid-flight, so it is the moment unflushed findings are at risk; the staleness test exists only so a session exit does not re-flush a finished run, and both store writes are idempotent), and `SessionStart` runs `capture-resume.sh`, at most two lines about an unfinished run and a stale observation queue. None of them calls a model; all exit 0 on every path. One `PostToolUse` hook ships in the same block and blocks nothing either: `edit-syntax-gate.sh` on `Edit|Write|MultiEdit` parses the file the edit just wrote (`swiftc -parse`, `node --check`, `py_compile` into a temp dir, `JSON.parse`, `bash -n`; Kotlin is skipped, no parser answers inside its 2 s deadline) and hands a syntax error to the model as `additionalContext`; it is silent when a parser is missing or slow, and inert until `editSyntaxGate.enabled` is true. Every registration here is Claude Code's: Codex has a `PostToolUse` event and Copilot CLI a `postToolUse` one, but the installer registers none of the pipeline's hooks on either host, so this gate is Claude Code only for now. 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.
+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 and never execute the inspected command. On an internal error they let the call through in an attended session; `agent-guard.sh` blocks instead under `MULTI_AGENT_UNATTENDED=1`, where nobody is watching to notice a gap. Three 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, so they do not depend on the run reaching Phase 5) 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), `PreCompact` runs `capture-flush.sh` without `--if-stale` (a compaction summarizes a long phase mid-flight, so it is the moment unflushed findings are at risk; the staleness test exists only so a session exit does not re-flush a finished run, and both store writes are idempotent), and `SessionStart` runs `capture-resume.sh`, at most two lines about an unfinished run and a stale observation queue. None of them calls a model; all exit 0 on every path. One `PostToolUse` hook ships in the same block and blocks nothing either: `edit-syntax-gate.sh` on `Edit|Write|MultiEdit` parses the file the edit just wrote (`swiftc -parse`, `node --check`, `py_compile` into a temp dir, `JSON.parse`, `bash -n`; Kotlin is skipped, no parser answers inside its 2 s deadline) and hands a syntax error to the model as `additionalContext`; it is silent when a parser is missing or slow, and inert until `editSyntaxGate.enabled` is true. The syntax gate also runs on Codex, on `PostToolUse` for `apply_patch` (every file the patch adds, updates or moves to). `multi-agent:setup` Step 8 asks once and registers it there with `host-hooks.mjs install --host codex` from `install/templates/codex-hooks.json`: idempotent, leaving every other hook alone, `status` reports it and uninstall removes it. Codex runs it only after the user trusts it in `/hooks`, which the helper says. Copilot CLI gets no registration: as of 1.0.45 it discards a `postToolUse` hook's output and applies no matcher, so the gate would cost a spawn per tool call and say nothing. Every other registration here is Claude Code's. 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.
 
 Copilot CLI has no `PreToolUse` equivalent, so the secret scan there is workflow-enforced (run as a phase step, not OS-blocked) plus a CI smoke-gate step.

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

@@ -146,11 +146,11 @@ acted on, not read.
 #### Accounting is a gate, not a request
 
 `update <N> completed` exits **3** for phases 1-4 when nothing was recorded via
-`tokens`. The alternative is what shipped for months: the docs asked for the
-call, `smoke-tracker-tokens-invocation.sh` linted that the docs *mention* the
-call, and no run made it  -  every phase priced at `-`, every completion line
-printed without numbers, and every gate green. A lint over prose cannot observe
-a runtime omission; the tool that would have received the call can.
+`tokens`. A doc that asks for the call, and a lint
+(`smoke-tracker-tokens-invocation.sh`) that checks the doc *mentions* it, cannot
+see a run that skips it: every phase would price at `-` and every completion line
+would print without numbers while every gate passes. A lint over prose cannot
+observe a runtime omission; the tool that would have received the call can.
 
 The refusal is recoverable and loses no work:
 
@@ -160,7 +160,7 @@ phase-tracker.sh tokens <N> <in> <out> [cached]
 phase-tracker.sh update <N> completed
 ```
 
-`model` resolves a full model id to its cost-table family (`claude-opus-5` →
+`model` resolves a full model id to its cost-table family (`claude-opus-5-5` →
 `opus`) and says so out loud when it cannot, because an unpriced name is the
 other way a phase silently costs nothing. A phase that truly ran no LLM call
 completes with `--no-llm`, which is recorded and keeps it out of the run

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

@@ -782,6 +782,11 @@
       "enum": ["component", "bugfix", "feature", "refactor", "chore"],
       "description": "Phase 0 Step 7 classification. Phase 2 branches on it, and phase0-exit-gate.mjs fails a run that reaches Phase 1 without it. A Figma reference forces component."
     },
+    "depBump": {
+      "type": ["object", "null"],
+      "additionalProperties": true,
+      "description": "A /multi-agent:deps run (state.mode \"deps\"): the bump dep-bump.mjs applied (ecosystem, name, manifest, from, to, risk, lock, alsoMoves, commitMessage), the fix rounds taken against depBump.maxFixRounds, the scope verdict and, when the cap was reached, rolledBack plus what still failed. Contract: multi-agent-refs/features/dep-bump.md."
+    },
     "plan": {
       "type": ["object", "null"],
       "description": "The Phase 1 plan as a Todo list, written by plan-todos.sh when prefs.global.planTodos.enabled is true. Shape: plan-todos.schema.json, which plan-todos.sh validates on write, including the optional todos[].type, the todos[].tdd evidence record, the drift record (the todo ended off-plan) and the needsReplan flag (a step it depends on drifted; it does not start until confirm-replan); absent when the opt-in is off."

package/pipeline/schemas/phases.json

@@ -73,6 +73,10 @@
     "analysis": {
       "phases": [0, 1, 3, 4, 5],
       "autopilot": false
+    },
+    "deps": {
+      "phases": [0, 1, 2, 3, 4, 5],
+      "autopilot": false
     }
   },
   "thresholds": {

package/pipeline/schemas/plan-todos.schema.json

@@ -27,8 +27,8 @@
         "properties": {
           "id": {
             "type": "string",
-            "pattern": "^t[0-9]+$",
-            "description": "Stable identifier (t1, t2, ...). Used in dependency edges + progress lines."
+            "pattern": "^[tT][0-9]+$",
+            "description": "Stable identifier: t1, t2 when written directly, T1, T2 when converted from a planning-output document. Used in dependency edges and progress lines."
           },
           "task": {
             "type": "string",
@@ -43,7 +43,7 @@
             "type": "array",
             "default": [],
             "description": "Array of todo IDs that must reach `completed` (or `skipped`) before this one can move to `in_progress`. Empty for parallelizable steps.",
-            "items": { "type": "string", "pattern": "^t[0-9]+$" }
+            "items": { "type": "string", "pattern": "^[tT][0-9]+$" }
           },
           "startedAt": { "type": "string", "format": "date-time" },
           "completedAt": { "type": "string", "format": "date-time" },
@@ -148,7 +148,7 @@
             "properties": {
               "because": {
                 "type": "string",
-                "pattern": "^t[0-9]+$",
+                "pattern": "^[tT][0-9]+$",
                 "description": "The step that drifted."
               },
               "at": { "type": "string", "format": "date-time" },

package/pipeline/schemas/prefs.schema.json

@@ -568,7 +568,7 @@
             "fableEnabled": {
               "type": "boolean",
               "default": false,
-              "description": "Whether the fable rung is available at all on Claude Code. Ships OFF: the top rung is the most expensive thing a run can reach, and a cost control that is on by default is not a control. false makes every persona that declares preferredModel: fable dispatch on opus from the first call, with no dispatch attempt on fable and no error to recover from  -  a cost control, not a fallback. Claude Code only: Copilot CLI does not offer Fable 5, and on Codex CLI the fable rung means gpt-5.6 @ xhigh, which this switch deliberately does not touch. Turning it off also collapses the Phase 3 Claude Code reviewer panel from three to two (Reviewer 1 lands on opus, which Reviewer 2 already holds), and consensus.reviewerCount records 2."
+              "description": "Whether the fable rung is available at all on Claude Code. Ships OFF: the top rung is the most expensive thing a run can reach, and a cost control that is on by default is not a control. false makes every persona that declares preferredModel: fable dispatch on opus from the first call, with no dispatch attempt on fable and no error to recover from  -  a cost control, not a fallback. Claude Code only: Copilot CLI does not offer Fable, and on Codex CLI the fable rung means gpt-5.6 @ xhigh, which this switch deliberately does not touch. Turning it off also collapses the Phase 3 Claude Code reviewer panel from three to two (Reviewer 1 lands on opus, which Reviewer 2 already holds), and consensus.reviewerCount records 2."
             },
             "onDispatchError": {
               "type": "boolean",
@@ -1211,7 +1211,7 @@
         "clarifyAmbiguous": {
           "type": "object",
           "additionalProperties": false,
-          "description": "v8.6+  -  Phase 0 Step 9 clarifying-question loop. Before Phase 1 starts, a cheap Haiku classifier scores task ambiguity (0-10) and emits up to N questions if score < threshold. Cost: ~$0.0025 per Haiku call. Off by default  -  flip on for teams burned by ambiguity-driven rework or when working on cross-team issues where the spec lives in someone else's head.",
+          "description": "v8.6+  -  Phase 0 Step 9 clarifying-question loop. Before Phase 1 starts, a cheap Haiku classifier scores task ambiguity (0-10) and emits up to N questions if score < threshold. Cost: ~$0.0004 per Haiku call. Off by default  -  flip on for teams burned by ambiguity-driven rework or when working on cross-team issues where the spec lives in someone else's head.",
           "properties": {
             "enabled": {
               "type": "boolean",
@@ -1841,7 +1841,7 @@
         "editSyntaxGate": {
           "type": "object",
           "additionalProperties": false,
-          "description": "Parse the file an Edit / Write / MultiEdit just wrote and tell the model when it no longer parses: swiftc -parse, node --check, python3 py_compile (bytecode to a temp dir), JSON.parse, bash -n, chosen by extension, each under a 2 s deadline. Kotlin and every other extension are skipped. The hook is pipeline/scripts/edit-syntax-gate.sh (PostToolUse, Claude Code, installed from install/templates/claude-hooks.json). It never blocks: the message arrives as PostToolUse context and the hook exits 0. A parser that is not installed or runs past the deadline means no message.",
+          "description": "Parse the file an edit just wrote and tell the model when it no longer parses: swiftc -parse, node --check, python3 py_compile (bytecode to a temp dir), JSON.parse, bash -n, chosen by extension, each under a 2 s deadline. Kotlin and every other extension are skipped. The hook is pipeline/scripts/edit-syntax-gate.sh: PostToolUse on Claude Code (install/templates/claude-hooks.json) and on Codex apply_patch (codex-hooks.json, registered by host-hooks.mjs). Copilot CLI is not registered: as of 1.0.45 it discards postToolUse output. It never blocks: the message arrives as PostToolUse context and the hook exits 0. A parser that is not installed or runs past the deadline means no message.",
           "properties": {
             "enabled": {
               "type": "boolean",
@@ -1884,6 +1884,29 @@
             "timeoutSec": 120
           }
         },
+        "depBump": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "/multi-agent:deps (multi-agent-refs/features/dep-bump.md): bump one dependency, build and test, fix only the breakage the bump caused, review and open a PR. pipeline/scripts/dep-bump.mjs applies the bump and reads these settings through its config command.",
+          "properties": {
+            "maxFixRounds": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 5,
+              "default": 2,
+              "description": "Fix rounds a red build or test run may take after the bump. When the cap is reached and the run is still red, the worktree is rolled back to the recorded base and the run reports what broke instead of committing. 0 means a bump that does not pass as-is is rolled back at once."
+            },
+            "queryRegistry": {
+              "type": "boolean",
+              "default": true,
+              "description": "true = the candidate list asks the package registry for newer versions through the ecosystem's own tool (npm view, git ls-remote, Maven or PyPI metadata). A failed query is noted per package and the list falls back to the manifests, lockfiles and local caches. false = offline listing only."
+            }
+          },
+          "default": {
+            "maxFixRounds": 2,
+            "queryRegistry": true
+          }
+        },
         "bulkRead": {
           "type": "object",
           "additionalProperties": false,
@@ -2006,7 +2029,7 @@
               },
               "localRepo": {
                 "type": "string",
-                "description": "Repo that localPath is relative to, e.g. $HOME/multi-agent-plugins. Without it localPath reads as relative to the current repo, which is how both entries came to point at the UPSTREAM tree and stayed wrong through a rename: nothing in the config said which checkout held the derived copies."
+                "description": "Repo that localPath is relative to, e.g. $HOME/multi-agent-plugins. Without it localPath reads as relative to the current repo, so an entry can silently point at the UPSTREAM tree: nothing else in the config says which checkout holds the derived copies."
               },
               "upstreamMarketplace": {
                 "type": "string",

package/pipeline/scripts/_code-graph.mjs

@@ -212,8 +212,8 @@ const IMPORT_LINE_RE = /^[ \t]*import[ \t].*$/gm;
  *
  * Swift's submodule form - `import class DesignKit.PrimaryButton` - otherwise
  * feeds the `class` definition pattern, which registers the MODULE name as a
- * declared type. On a large Swift app that alone lifted two module names into
- * the top ten god-nodes, which is how the bug surfaced. Imports are extracted
+ * declared type. On a large Swift app that alone lifts module names into the
+ * top ten god-nodes. Imports are extracted
  * before this runs, so nothing is lost.
  *
  * @param {string} stripped - output of stripCode