@mmerterden/multi-agent-pipeline 20.23.2 → 20.25.0

package/pipeline/multi-agent-refs/features/analysis-jira.md

@@ -10,6 +10,7 @@
 - [The story body is document text, escaped](#the-story-body-is-document-text-escaped)
 - [An existing epic, linked the way the site links](#an-existing-epic-linked-the-way-the-site-links)
 - [Channel clones are opt-in](#channel-clones-are-opt-in)
+- [Story dependencies come from the document](#story-dependencies-come-from-the-document)
 - [The document lists its tickets](#the-document-lists-its-tickets)
 - [Every site-specific name is a VALUE, never a schema key](#every-site-specific-name-is-a-value-never-a-schema-key)
 - [Auth](#auth)
@@ -152,6 +153,46 @@ gets one clone per channel: its own label (the story's identity plus
 the label search, and a link is checked before it is sent, so a re-run doubles
 neither.
 
+## Story dependencies come from the document
+
+A requirement row may carry `Depends on: <ids>` (an extra trailing column, or
+appended to any cell of that row): `| BR-pay-01 | ... | Depends on: BR-cart-01 |`.
+The row's own id is the dependent, the ids after the clause its prerequisites.
+The clause is machine syntax, so it stays English in a Turkish document, as
+`THE SYSTEM SHALL` and Given/When/Then do. Only clauses inside a table row are
+read, and a clause naming no requirement id is left as prose.
+
+The planner reads the clauses first and removes them before it looks for ids,
+because an id is defined by where it appears: a reference left in place would
+define the id it points at, and a dependency on a requirement nobody wrote would
+plan a story for it instead of being reported.
+
+| Clause | Plan |
+|---|---|
+| both ids in one story | no edge |
+| ids in two stories | the dependent story's `dependsOn` gets the prerequisite's label, and `dependencies.edges[]` names the pair of ids behind it |
+| prerequisite id in no story | `dependencies.missing[]`, coverage `incomplete` |
+| stories that wait for each other | `dependencies.cycles[]`, one per strongly connected component (from `lib/task-graph.mjs`); every edge inside one gets `onCycle: true`; coverage `incomplete` |
+
+The preview prints each edge, its requirement pair and each cycle
+prerequisite first, and the problems under the
+coverage line, as `coverage.dependencyProblems`; an incomplete verdict they
+cause carries them in `coverage.reason`. Its heading counts issues and links
+apart (`N issue(s) and M link(s)`); `writeCount` is their sum, without the
+edges on a cycle. A document with no clause plans
+exactly as it did before: no `dependsOn`, no `dependencies`, and
+`prefsUsed.dependencyLinkType` only when the site set it.
+
+The writer links the stories after all of them have keys, one link per edge, of
+`issueTree.dependencyLinkType` (default `Blocks`). The prerequisite is the
+link's source - the POST's `inwardIssue` - so the site reads "prerequisite
+blocks dependent" and lists the link on the prerequisite under `outwardIssue`.
+That entry, same type and same direction, is what the writer checks for before
+sending, so a re-run adds nothing; a link of another type between the same two
+stories does not count. A written link is a `dependency` line in the ledger
+(the dependent's label, the prerequisite's key). An edge with `onCycle` is not
+linked, and the writer says so.
+
 ## The document lists its tickets
 
 After the write, `analysis-tickets-writeback.mjs` puts a `## Tickets` table at
@@ -176,6 +217,7 @@ are values the site fills in:
   types (`analysis-jira-write.sh --subtask-types`), and saves the answer
   (`analysis-story-tree.mjs --save-subtasks`): each chosen type becomes a role
   mapped to itself, and "no sub-tasks" sets `subtaskRolesDeclined`
+- `cloneLinkType` and `dependencyLinkType` are the site's own link type names
 - `epicLinkFieldId`, when set, is the site's own field id; otherwise it is
   discovered
 - `subtaskIssueType: null` means discover it - `createmeta` returns whichever

package/pipeline/multi-agent-refs/features/autopilot-decisions.md

@@ -0,0 +1,34 @@
+# Feature: Decisions made on your behalf (autopilot)
+
+**Pattern**: an attended run asks; an autopilot run answers its own questions. Every such answer is one entry in `state.decisions[]`, so whoever reads the PR or the Phase 5 report sees each place the run chose for them, why, and what it costs if the choice was wrong:
+
+```json
+{ "what": "Took the default base branch develop", "why": "no remembered branch inside the TTL",
+  "costIfWrong": "the PR targets the wrong base and is retargeted", "at": "<ISO-8601>", "phase": 0 }
+```
+
+Written only while the quality gates are active (`lib/unattended.mjs` `gatesActive`: autopilot, or `MULTI_AGENT_UNATTENDED=1`). In an attended run the person answered, so nothing is recorded. Shape and rendering: `lib/decisions.mjs`; schema: `agent-state.schema.json` `decisions`.
+
+## Writers
+
+| Decision | Written by |
+|---|---|
+| Park (`awaiting-answer`, `verification-failed`) | `gate-ledger.mjs park`, in the same locked write as the park |
+| Blocker lowered to important (waived finding) | `review-decision-gate.mjs`, one entry per downgrade |
+| Rework dispatched one rung up | `rework-escalation.mjs --state` (`features/rework-escalation.md`) |
+| Picker resolved without asking (`remembered` / `default` / `derived`) | the picker step, through `decisions-log.mjs add` (`picker-contract.md`) |
+| Split / unverified consensus taken on the triage verdict | Phase 3 Step 4, through `decisions-log.mjs add` |
+| Date-gate model fallback taken without the question | Phase 0 Step 0, through `decisions-log.mjs add` (`features/model-fallback.md`) |
+
+```bash
+node $HOME/.claude/scripts/decisions-log.mjs add --state "$STATE_FILE" --phase <0-5> \
+  --what "<what was chosen>" --why "<the rule or evidence that chose it>" \
+  --cost-if-wrong "<what a person has to undo if it was the wrong call>"
+```
+
+Exit 0 written or skipped (attended), 2 a missing field, 3 no state. A failed add never stops the run; log `decisions.add_failed`.
+
+## Where it is shown
+
+- **Phase 5 report**: `decisions-log.mjs render --state "$STATE_FILE"` inlined verbatim in `agent-log.md`. It prints its own `## Decisions made on your behalf` heading, and nothing at all for an empty list.
+- **Autopilot PR body**: `autopilot-publish.mjs` appends the same section to the run's PR body before the outbound gate checks the title and body. The entries are passed through `lib/redact.mjs` when rendered, so a credential that reached a gate reason is replaced rather than published; the outbound gate still refuses a body that carries one anywhere else. A body that already holds the heading is not given a second one, and the section is trimmed to the 65536-character body limit with a pointer to the run report.

package/pipeline/multi-agent-refs/features/cost-analysis.md

@@ -46,6 +46,10 @@ discovered later:
 - A host with no such transcripts (Copilot, Codex) reports `UNMEASURED`, never
   zero. Zero would read as "you spent nothing" when it means "I could not see".
 
+A record is priced by its exact wire ID: a rung's `modelId`, a Copilot CLI
+`copilotModelId` at its own model's rate from the table's `models` map, or a
+previous-generation ID in the table's `legacy` map at that ID's own rate. A
+dated snapshot (`<id>-<date>`) prices as the longest known ID it extends.
 Records whose model is not in `cost-table.json` are COUNTED as unpriced and left
 out of the total. Folding them in at zero would make an unknown model look free,
 which is the direction that hurts.

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
@@ -174,7 +179,8 @@ prints it once instead:
    `WARN: premium tier plan window ended <date>; preferredModel personas will dispatch on <fallbackModel>. Set prefs.global.modelFallback.premiumTierUntil to null to keep the top tier on usage credits.`
    Then export the override for every `preferredModel` persona this run. Interactive modes
    may instead ask once (`Keep top tier (usage credits) / Fall back to <model>`);
-   autopilot never asks - it falls back and logs.
+   autopilot never asks - it falls back, logs, and lists the fallback in `state.decisions[]`
+   (`features/autopilot-decisions.md`).
 2. **Dispatch error (per dispatch).** On a model-unavailable / quota error from a
    top-tier dispatch and `onDispatchError: true`: retry the same persona once with
    `PHASE_MODEL_OVERRIDE=<fallbackModel>`. If that retry also fails with a dispatch
@@ -244,11 +250,12 @@ better internals.
 ## Non-goals
 
 - No automatic re-upgrade mid-run (a run that fell back stays fallen back -
-  deterministic over clever).
+  deterministic over clever). Rework escalation (`features/rework-escalation.md`)
+  moves one rework dispatch up a rung and refuses to on a run that fell back.
 - 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/features/mutation-probe.md

@@ -0,0 +1,58 @@
+# Mutation probe (Phase 3 Step 1.763, opt-in)
+
+A passing suite says the changed code runs, not that a test checks what it
+decides. `mutation-probe.mjs` inverts a few changed lines one at a time and
+reruns the tests; a mutant that still passes marks a line no test pins down.
+
+Runs only when `prefs.global.mutationProbe.enabled` is true, and only when the
+stack adapter names a test command.
+
+```bash
+MP_FILE="$WORKTREE/.pipeline/mutation-probe-$ITERATION.json"
+STACK=$(node $HOME/.claude/scripts/_stack-adapter.mjs resolve --dir "$WORKTREE" | cut -d' ' -f1)
+TEST_CMD=$(node $HOME/.claude/scripts/_stack-adapter.mjs command --dir "$WORKTREE" --stack "$STACK" --kind test)
+[ -n "$TEST_CMD" ] && node $HOME/.claude/scripts/mutation-probe.mjs --repo "$WORKTREE" \
+  --base "origin/$BASE_BRANCH" --head worktree --test-cmd "$TEST_CMD" --out "$MP_FILE"
+```
+
+`--max-mutants` and `--timeout-sec` default to `mutationProbe.maxMutants` (5)
+and `mutationProbe.timeoutSec` (120 per test run). Each mutant costs one full
+test run, so the bound is the cost bound.
+
+## Mutations
+
+Textual, single-site, and only on lines the diff added or changed (test files
+excluded). The operator needs whitespace on both sides, so generics, arrows and
+unary signs are left alone; comment lines and string contents are skipped.
+
+| Kind | Change |
+|---|---|
+| comparison | `==` `!=` `===` `!==` `<` `<=` `>` `>=` flipped to the opposite |
+| boolean | `true`/`false`, `True`/`False` negated |
+| arithmetic | binary `+` and `-` swapped |
+| return | `return <number>`: 0 becomes 1, anything else 0 |
+
+Mutants are spread across lines: one per changed line in diff order before any
+line gets a second.
+
+## Isolation
+
+`--head worktree` snapshots the uncommitted tree through a private index (the
+caller's index, HEAD and refs are untouched), and every mutant is applied in a
+detached worktree under the system temp directory, removed and pruned on exit,
+SIGINT/SIGTERM included. The checkout is never written.
+
+## Output and merge
+
+| Exit | Meaning | `$MP_FILE` |
+|---|---|---|
+| 0 | every mutant killed or timed out | `findings: []` |
+| 1 | at least one survivor | one finding per survivor |
+| 4 | nothing judged: no mutable changed line, or the tests fail before mutation | `findings: []`, `reason` set |
+| 2 | usage or setup error | not written; the step is skipped |
+
+A finding is reviewer-shaped (`severity: important`, `file`, `line`, `issue`,
+`fix`) plus `mutation`, `testCommand` and `tag: mutation_probe`. Step 3.0
+appends `$MP_FILE` with the other deterministic findings; triage keeps a
+survivor unless the line is genuinely untestable here (logging, a default no
+caller observes) and says so.

package/pipeline/multi-agent-refs/features/plan-checks.md

@@ -0,0 +1,67 @@
+# Feature: Plan checks (Phase 1, after the plan is written)
+
+Two deterministic checks run on `$WORKTREE/.pipeline/plan.json` before the approval gate: the overlap check inside `validate-planning.mjs`, and the complexity score from `plan-complexity.mjs`.
+
+## Overlap check
+
+**Pattern**: a plan contradicts itself at the seams between tasks, not inside one. Two tasks that both create the same file, a rename in one task while another still calls the old name, a consumer that can start before its producer: each task reads fine alone. The check is deterministic and runs inside `validate-planning.mjs`, so it fires on every plan with no extra step.
+
+### What a task may state
+
+Optional per-task lists in `planning-output.schema.json`, next to `files[]`:
+
+| Field | Holds | Role it gives the task |
+|-------|-------|------------------------|
+| `creates` | files the task brings into existence | `creates` |
+| `removes` | files or symbols deleted, or the old name of a rename (a file: a `/`, a known extension, a well-known name such as `Makefile`, or a dotfile; else a symbol, `UserService.fetch` included) | `removes` |
+| `produces` | interfaces / symbols introduced or reshaped | `produces` |
+| `consumes` | interfaces / symbols used unchanged | `consumes` |
+
+A file listed only in `files[]` gives the role `edits`. Fill the lists when Step 8 decided the approach (New file / Modify / Refactor): a New-file task lists its file under `creates`, a rename lists the old name under `removes` and the new one under `produces`, a task that calls an interface another task adds lists it under `consumes`. A plan without them still gets the shared-file rows below. `plan-todos.sh set` carries `creates` onto each todo next to `files[]`, and the per-step drift check (`features/plan-todos.md`, Drift propagation) counts both as planned, along with the test file named after a planned file (`a.test.ts` for `a.ts`, `FooTests.swift` for `Foo.swift`).
+
+### Output
+
+`validate-planning.mjs` adds two fields to its result: `overlaps[]`, one anchored row per pair of tasks naming the same file or symbol, and `warnings[]`, one sentence per suspicious row.
+
+```json
+{ "a": "T1", "b": "T3", "kind": "file", "name": "Sources/FareService.swift",
+  "aRole": "removes", "bRole": "edits", "order": "unordered", "finding": "removes-used" }
+```
+
+`order` comes from `dependsOn`, transitively: `a-first`, `b-first` or `unordered`.
+
+| Finding | When | Effect |
+|---------|------|--------|
+| `double-create` | both tasks create the same file (paths compared normalised, `./a` is `a`) | error, exit 1; unordered: make one depend on the other; ordered: drop it from one task's `creates` |
+| `removes-used` | one task removes what the other edits, consumes, creates or produces | warning |
+| `consumer-not-after-producer` | the user of a created file or produced symbol is not ordered after its producer | warning |
+| `unordered-edit` | both tasks edit one file with no `dependsOn` between them | warning |
+
+An error goes through the validator gate's single rework like any other. Warnings never change the exit code: render them in the Step 13 approval view under `⚠️ Plan overlaps` (autopilot: log `plan.overlaps={n} warnings={m}`), and fix the plan when the warning is real, usually by adding the missing `dependsOn` edge or merging the two tasks.
+
+## Complexity score
+
+**Pattern**: "is this task too big" answered from what the task touches, not from its title. The score is a sum of points over counted factors, so the same plan and graph always give the same score and each point traces to a number.
+
+| Factor | Counted as | Points |
+|--------|-----------|--------|
+| `files` | files in `files[]` | 1 → 0, 2-3 → 1, 4-5 → 2, 6-8 → 3, 9+ → 4 |
+| `fanIn` | non-test files depending on the task's declarations, one ring out in the code graph, the task's own files excluded | 0 → 0, 1-3 → 1, 4-10 → 2, 11+ → 3 |
+| `modules` | modules the task's non-test files span | one point per module past the first, at most 2 |
+| `crossModuleEdges` | fan-in files outside every module the task touches | 0 → 0, 1-3 → 1, 4+ → 2 |
+| `testSurface` | test files listed plus test files depending on the task's files | 0-2 → 0, 3-5 → 1, 6+ → 2 |
+
+`score = 1 + points`, capped at 10. A module is the SPM target (`Sources/<Target>/`, `Tests/<Target>Tests/`), else the directory above the first `src` / `test` / `tests` / `lib` segment (the Gradle module), else the first directory. Without a graph, `fanIn`, `crossModuleEdges` and `notIndexed` are `null` and score nothing, and the output says `graph: absent`. `notIndexed` counts listed files the graph does not know, usually the ones the task creates.
+
+`recommendSplit` is `score > prefs.global.planComplexity.splitAbove` (default 7; `--split-above N` overrides it). Splitting rules, applied before Step 13:
+
+- Split along the factor that scored: files by module first, then producer before consumer, tests with the code they test.
+- Traceability: every requirement id on the original appears on at least one child, and no child carries an id the original did not.
+- Ordering: a task that depended on the original depends on the child that completes the original's output; children chain through `dependsOn` where one consumes another.
+- One round. Re-run the validator and the scorer; a task still above the line is shown at Step 13 with its factors, not split again.
+
+Output: `{splitAbove, graph, split: [ids], tasks: [{id, score, recommendSplit, factors, points}]}`. `--write` stores `{score, recommendSplit, factors}` as each task's `complexity` in the plan file. Autopilot log: `plan.complexity split={ids} graph={used|absent}`.
+
+## Reference
+
+Overlap module: `$HOME/.claude/scripts/_plan-overlap.mjs` (`planOverlaps(tasks)`). Validator: `$HOME/.claude/scripts/validate-planning.mjs`. Unit: `test/plan-overlap.test.mjs`, fixtures under `test/fixtures/plan-overlap/`. Scorer: `$HOME/.claude/scripts/plan-complexity.mjs` (`planComplexity(tasks, {graph, splitAbove})`), reusing `graph-affected.mjs`'s reverse walk. Unit: `test/plan-complexity.test.mjs`, golden fixtures under `test/fixtures/plan-complexity/`.

package/pipeline/multi-agent-refs/features/plan-todos.md

@@ -7,9 +7,14 @@ while next=$(bash "$HOME/.claude/lib/plan-todos.sh" next "$TASK_ID"); [ -n "$nex
   id=$(printf '%s' "$next" | cut -f1)
   task=$(printf '%s' "$next" | cut -f2)
   bash "$HOME/.claude/lib/plan-todos.sh" start "$TASK_ID" "$id"
-  # ... TDD cycle for "$task" ...
+  # ... RED: write the failing test, run it, keep the JUnit XML / .xcresult / log ...
+  bash "$HOME/.claude/lib/plan-todos.sh" tdd-red "$TASK_ID" "$id" "$RED_RESULTS" --tests "$TEST_NAME"
+  # ... GREEN: implement, run the suite ...
+  bash "$HOME/.claude/lib/plan-todos.sh" tdd-green "$TASK_ID" "$id" "$GREEN_RESULTS"
   if build_passed; then
     bash "$HOME/.claude/lib/plan-todos.sh" complete "$TASK_ID" "$id" "${COMMIT_HASH} · tests:${TEST_COUNT}"
+    git -C "$WORKTREE" diff --name-only HEAD~1 HEAD \
+      | bash "$HOME/.claude/lib/plan-todos.sh" drift "$TASK_ID" "$id" --files - --not-done "$NOT_DONE"
   else
     bash "$HOME/.claude/lib/plan-todos.sh" fail "$TASK_ID" "$id" "build failed after 3 retries"
     break
@@ -18,3 +23,37 @@ done
 ```
 
 When disabled, the loop still walks `tasks[]` from `planning-output`  -  `plan-todos.sh` adds visibility (status, notes, deps-respecting `next`) but the underlying TDD contract is unchanged.
+
+## Drift propagation
+
+A step that ends off-plan invalidates the plan of every step built on it. `drift` takes the same two signals the scope self-check records for the whole run (`features/scope-check.md`), per step: files the step changed that its `files[]` does not list, and planned items it did not do (`--not-done N`, the entries that go to `scope-check.json` `notDone[]`). `--reason <text>` records drift the two counts do not show, such as an interface whose shape changed.
+
+On drift the step gets `drift: {outside, notDone, at}` and every **pending** step that depends on it, directly or transitively, gets `needsReplan: {because, at, reason}`; steps that already started or finished keep their state, and steps on other branches of the graph are untouched. Output: `{drifted, outside, notDone, flagged}`.
+
+A flagged step:
+
+- is reported by `next` as waiting (`task-graph.mjs` `reason: "needs-replan"`), and named on stderr when nothing else is ready;
+- is refused by `start` and `complete` (exit 2), which name the drifted step;
+- starts again after `plan-todos.sh confirm-replan "$TASK_ID" <todo-id> [note]`, run once its plan has been re-read against what the drifted step actually did (interactive: ask; autopilot: confirm when the drifted files are not in the flagged step's `files[]` and none of its `files[]` were deleted, otherwise stop the loop and log `plan.replan_needed={ids}`).
+
+A later drift replaces the flag and its confirmation. `files[]` and `creates[]` come from the planning-output task through `set`, and both count as planned; paths are normalised on both sides (`./a`, `a` and `a//b/..` compare equal). A changed test file is planned when its name covers the stem of a planned file: `a.test.ts`, `a.spec.ts`, `a_test.go`, `ATests.swift`, `ATest.kt` and `test_a.py` cover `a.ts` / `A.swift` / `a.py` in any directory. A step with neither list is judged on `--not-done` and `--reason` only.
+
+## TDD evidence
+
+`tdd-red` and `tdd-green` read the runner's own results (`lib/tdd-evidence.mjs`): JUnit XML file or directory (Gradle, Surefire, Jest/Vitest junit, `pytest --junitxml`), an `.xcresult` bundle via `xcrun xcresulttool`, that summary exported to JSON, or the xcodebuild / `swift test` log. They write `plan.todos[].tdd`.
+
+| Call | Holds when | Refused (exit 2) when |
+|------|-----------|------------------------|
+| `tdd-red <task> <todo> <results> [--tests a,b]` | at least one test fails; with `--tests`, one of the failing tests is a named one | nothing failed, nothing ran, or every failure is in another test; under `enforce`, `--tests` on results that name no failing test (use JUnit XML); `warn` records that run with `red.testsUnverifiable` and a warning |
+| `tdd-red ... --already-passing <reason>` | the run has no failure: the behaviour already exists; the run stands for RED and GREEN, the reason is kept | any test fails |
+| `tdd-green <task> <todo> <results>` | RED is recorded (not needed under test policy `tests-after`), the run has no failure, and it is the RED suite: RED's named tests pass in it, or, without names on either side, it ran at least as many tests | a test still fails, nothing ran, no RED, a RED test is missing, fewer tests than RED |
+
+Both refuse results written before the todo's `startedAt`.
+
+`complete` then reads `prefs.global.tddEvidence.mode`:
+
+- `off`: no check.
+- `warn` (default): a todo without both runs completes with a warning and `tdd.outcome: "unverified"`; Phase 3 notes it.
+- `enforce`: `complete` refuses (exit 2) and the todo stays open.
+
+Never blocking, always recorded with `tdd.outcome: "exempt"` and a reason: a `docs` or `chore` todo (type carried from `planning-output`), a `component` task (the component skill short-circuits the TDD path), project test policy `none`, and `complete ... --no-tests "<reason>"` for a repo with no test target. The last one is the todo's own claim, so it is stored with `tdd.selfDeclared: true` and Phase 3 notes it next to the unverified todos.

package/pipeline/multi-agent-refs/features/rework-escalation.md

@@ -0,0 +1,49 @@
+# Feature: Rework model escalation (Phase 2 re-entry, Phase 3 Step 4)
+
+**Pattern**: a rework round that dispatches the same model with the same findings tends to produce the same fix. Two signals say the current rung is not enough: the round is the **last** one the rework cap allows, or `review-delta.mjs` reported findings **still present** after the previous round's fix. On either, the fresh dev agent for the next round runs one rung up the model-fallback ladder (`fable -> opus -> sonnet -> haiku`, `features/model-fallback.md`), and only one. The decision is a pure function in `scripts/rework-escalation.mjs`, never a model's judgement.
+
+## Prefs
+
+`prefs.global.reworkEscalation`:
+
+| Field | Default | Meaning |
+|---|---|---|
+| `reworkEscalation.enabled` | `true` | Master switch. `false` keeps every rework round on the rung the dev dispatch resolved to. |
+| `reworkEscalation.maxTier` | `opus` | Highest rung an escalation may reach. `fable` additionally needs `modelFallback.fableEnabled: true`. |
+
+On by default because it fires at most on the rounds where a failure costs the most (the last one, or one that repeats the previous attempt), moves one rung, and stops at `opus`. Every existing cost control outranks it.
+
+## The call (before each rework dispatch)
+
+```bash
+node $HOME/.claude/scripts/cost-budget-check.mjs --task-id "$TASK_ID" --prefs "$PREFS_FILE" >/dev/null; BUDGET_RC=$?
+STILL=$(jq '.reviewIterations[-1].delta.counts.stillPresent // 0' "$STATE_FILE")
+ESC=$(node $HOME/.claude/scripts/rework-escalation.mjs --iteration "$ITERATION" --max-iterations 3 \
+  --still-present "$STILL" --current-tier "$DEV_TIER" --budget-exit "$BUDGET_RC" \
+  --prefs "$PREFS_FILE" --state "$STATE_FILE" ${FELL_BACK:+--fallen-back})
+```
+
+`ITERATION` is the rework round about to run (1-based, `retryCount + 1`); `DEV_TIER` is the rung the Phase 2 dev dispatch resolves to without this override (persona and routing, `skills/shared/core/multi-agent/SKILL.md`), so escalations never compound; `FELL_BACK` is set when this run emitted a `model_fallback` metric. Pass `BUDGET_RC` on every call: without `--budget-exit` the budget counts as disabled only when `costBudget.enabled` is not `true`, otherwise the rung holds with `budget-unchecked`. Prefs come from `--prefs`, then `$MULTI_AGENT_PREFS`, then `~/.claude/multi-agent-preferences.json`. `--state` records the result as `reviewIterations[-1].reworkEscalation`, including a refusal and its reason, and in an autopilot run lists an escalation in `decisions[]` (`features/autopilot-decisions.md`). Exit 2 or 3: log `rework.escalation_skipped`, dispatch on `DEV_TIER`; it never blocks the rework.
+
+| `reason` | Meaning |
+|---|---|
+| `escalated` | Dispatch on `toTier` |
+| `not-triggered` | Neither the last round nor a still-present finding |
+| `disabled` / `past-cap` | Switch off, or the cap has already stopped Phase 2 |
+| `run-fell-back` | The run degraded; it is never re-upgraded mid-run |
+| `budget-warn` / `budget-exceeded` / `budget-unknown` | `cost-budget-check.mjs` exit 10 / 11 / other |
+| `budget-unchecked` | No `--budget-exit` while `prefs.global.costBudget.enabled` is `true`: an unrun check is no evidence the budget has room |
+| `unknown-tier` / `top-of-ladder` | Not an Anthropic rung, or nothing above it |
+| `fable-off` / `at-ceiling` | The next rung is fable with the rung off, or above `maxTier` |
+
+Telemetry: `log-metric.sh "$TASK_ID" 2 rework.escalation escalate= from= to= reason=`.
+
+## The escalated dispatch
+
+`escalate: true` -> `PHASE_MODEL_OVERRIDE=<toTier>` for that one dev dispatch (the override outranks routing, so the fable and ceiling checks above are the only ones that apply). The agent is **fresh**: no forked history, no conversation. It gets files:
+
+- `$WORKTREE/.pipeline/triage-round-$ITERATION.json`: the persisted findings of the review that sent this round back (accepted, with fingerprints)
+- `$WORKTREE/.pipeline/rework-attempt-$((ITERATION-1)).diff`: the prior attempt's change, written by the orchestrator before the dispatch as `git diff <round start>..HEAD` (round 0 starts at the run's base), so the escalated agent sees what was tried without the conversation that tried it
+- `delta.stillPresent[]` quoted first, as Phase 2 re-entry item 7 already requires
+
+An escalation is per dispatch: the next round asks again from `DEV_TIER`, so the rework never sits more than one rung above the dev dispatch.

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

@@ -33,6 +33,7 @@ Output `{ok, justified, unjustified[], unlisted[], notDone}`. Exit 1 lists `unju
 
 ## Consumers
 
+- With plan todos on, Phase 2 applies the same two signals per step as it goes: `plan-todos.sh drift` compares each step's changed files with its planned `files[]` and counts its not-done items, and flags the steps built on a drifted one for re-plan (`features/plan-todos.md`).
 - Phase 3 Step 2.2 renders file reasons, unjustified files and `notDone[]` into the shared reviewer prefix (`features/review-delta.md`).
 - Phase 4 Step 3 builds the PR `## Changes` bullets from `files[].reason` and lists `notDone[]` under `## Related` as "Follow-ups not done in this PR", merged with the final triage `deferred[]` (`channels/pr.md`).