@mmerterden/multi-agent-pipeline 17.5.1 → 18.0.0

package/pipeline/multi-agent-refs/features/maturity-followup.md

@@ -0,0 +1,166 @@
+# Feature: Maturity Follow-Up
+
+<!-- toc -->
+- [1. The rule everything else follows](#1-the-rule-everything-else-follows)
+- [2. Interactive: ask at the step, do not halt at it](#2-interactive-ask-at-the-step-do-not-halt-at-it)
+- [3. Autopilot: ask on the item, then stop](#3-autopilot-ask-on-the-item-then-stop)
+- [4. Resuming into the step, not past it](#4-resuming-into-the-step-not-past-it)
+- [5. State](#5-state)
+<!-- /toc -->
+
+**Pattern**: the maturity check has always produced a machine-readable gap list -
+stable codes in `blockers[]` and `warnings[]` - and then thrown most of it away.
+A blocker halted the run, an autopilot queue moved to the next item, and the
+issue stayed exactly as immature as it was found. Nobody was told, so nothing
+changed, so the next scan halted on the same issue for the same reason. The
+check was doing its job and producing no effect.
+
+Three behaviours, one decision function
+(`$HOME/.claude/scripts/maturity-followup.mjs`, pure - no network, no issue API,
+no clock unless handed one). Asserted by `smoke-maturity-followup.sh` and
+`test/maturity-followup.test.mjs`.
+
+## 1. The rule everything else follows
+
+**An edit is a reason to look again. It is never proof that the gap closed.**
+
+A reply reading "will do later" moves the artifact's timestamp and fixes
+nothing. So a changed artifact re-runs the maturity check against the new
+content and the CHECK decides. Nothing in this feature infers maturity from the
+fact that something moved, and the decision function is handed a freshly scored
+`maturity` on every pass for exactly that reason.
+
+The corollary is the second comment. A run that re-comments on every scan turns
+an issue into a wall of identical bot text, so:
+
+| Situation | What happens |
+|---|---|
+| First pass, gaps present | comment once |
+| Same gaps, artifact untouched | say nothing |
+| Same gaps, artifact edited | say nothing - the re-check already ran and they survived |
+| **Different** gaps | comment - a different question is new information |
+| No gaps | proceed; development starts |
+
+**Where "have we already asked" comes from.** The item, not our state file. An
+autopilot scan is a NEW run with a fresh `agent-state.json`, so deriving it from
+state alone would make every scan a first ask - the wall of identical bot
+comments this table exists to prevent. So the comment carries its own gap set on
+a last line, `multi-agent gaps: code,code`, and the next pass reads the item's
+comments and takes the newest one of ours (`priorFromComments`). `state.maturityFollowup`
+is a cache of the same answer for the run that wrote it, never the source.
+
+A comment of ours carrying no gap line - written before v17.6.0, or edited by
+hand - reads as "asked, about something we can no longer name": an empty gap set,
+which never equals a live one, so the next scan asks again WITH the codes instead
+of staying silent forever on an unreadable record.
+
+"Cannot tell whether it moved" (a tracker whose API omits the timestamp, an
+unparseable value) resolves to *re-check*, never to *wait*. Folding unknown into
+"nothing changed" parks a run forever on a host that never told us anything.
+
+## 2. Interactive: ask at the step, do not halt at it
+
+A blocker used to end the run with a summary. It now asks, at the maturity step,
+with the gap as the question. The options are real choices and meet the
+two-option floor on their own (`picker-contract.md`, "Two options or it is not a
+question"):
+
+| Option | What it does |
+|---|---|
+| Open the item and fix it | halts, prints the item URL, resumes into this same step |
+| Continue without it | proceeds, and records WHICH gap was accepted in `state.maturity.accepted[]` |
+| Abort | no worktree, no branch, no state file |
+
+`prefs.global.maturityFollowup.askInteractively` (default `true`) turns this back into
+the old halt.
+
+**What an answer here does not do.** An answer typed into a picker improves this
+run and leaves the item as immature as it was for the next person. That is a
+real cost, not an oversight, and the step says so: after an answer that supplies
+missing content, it offers to write that content back to the item - as a
+separate, individually approved write, per the standing rule that every Jira
+write is approved on its own.
+
+## 3. Autopilot: ask on the item, then stop
+
+`autopilotCommentsOnIssue` (**default `false`**) lets an autopilot run post one
+comment on the item asking for what is missing. It is an outward-facing write,
+so it carries the same fence as every other one in this pipeline:
+
+- **Off by default.** Nothing posts unless the user turned it on.
+- **A question, never a state change.** No transition, no resolution, no
+  assignee, no label, no close - ever. The standing rule that this pipeline
+  never auto-closes an issue is not relaxed by a feature that writes comments.
+- **One comment.** The marker line makes the next scan able to recognise its own
+  prior comment; matching on the marker rather than on authorship is what keeps
+  that working when the token belongs to a shared service account.
+- **No square brackets in the marker or the gap line.** `[text]` is a LINK in
+  Jira wiki markup, and this comment is most likely to be posted exactly there,
+  so a bracketed marker renders as a broken link to a page nobody created.
+- **`Ref:`, never `Closes:`/`Fixes:`/`Resolves:`**, so no platform-side
+  automation reads a question as an instruction.
+- **Human-facing copy follows `outputLanguage`**, and the gap wording is the
+  fetcher's own `maturity.summary` verbatim. Re-deriving those labels here would
+  give the project two copies of one table and only one would be maintained.
+- **Then it stops.** The run halts on the circuit breaker (`features/autopilot-circuit-breaker.md`),
+  which is the sanctioned autopilot pause: state recorded, one actionable line
+  printed, waiting for `resume`. Posting a question and continuing on a guess is
+  worse than not asking - the guess lands in a branch while the question sits
+  unanswered.
+
+**Not a second readiness reviewer.** `/multi-agent:review-jira` and
+`/multi-agent:review-issue` also post a gap list, and they are a different thing: a
+human invokes them ON PURPOSE to review an item, with the full readiness rubric
+(`readiness-review.md`) behind the verdict. This comment is a side effect of a
+development run that could not start, carries only the fetcher's own blocker codes,
+and posts at most once. Both obey the same tone contract (`channels/issue-comment.md`):
+no AI attribution, `Ref:` never a closing keyword, copy in `outputLanguage`.
+
+**Warnings still auto-continue.** Converting every warning into a halt would
+stall queues overnight on items that ran fine yesterday, so blockers are
+actionable by default and `prefs.global.maturityFollowup.commentOnWarnings` raises
+warnings to the same treatment. Either way the gaps are recorded, so the next pass can compare.
+
+## 4. Resuming into the step, not past it
+
+`/multi-agent:resume` starts from `currentPhase + 1`. A run that halted at the
+maturity step has `currentPhase: 0`, so resuming would start at Phase 1 and skip
+the check - the halt would be permanent in the one direction that matters.
+
+So resume reads `state.waitingFor` first: when it names a step, the run re-enters
+THAT step rather than the next phase. `waitingFor` already existed and Phase 7's
+channels pause already documented itself as resumable through it
+(`phases/phase-7-report.md`), while `resume/SKILL.md` never mentioned the field -
+so that pause had the same gap and this fixes both.
+
+| `waitingFor` | Re-entry |
+|---|---|
+| `maturity` | Phase 0, the maturity step, with the item re-fetched |
+| `user-channels-choice` | Phase 7, the channels menu |
+| absent | `currentPhase + 1`, as before |
+
+`waitingFor` is cleared by the write that records the answer. A field that
+outlives its question sends every later resume back to the step the user already
+answered.
+
+## 5. State
+
+```jsonc
+"maturity": {
+  "score": 60,                       // null for free-text: nothing to score
+  "blockers": ["description_empty"],
+  "warnings": [],
+  "summary": "...",                  // localized by the fetcher, used verbatim
+  "accepted": ["short_description"]  // gaps a human waved through, interactive only
+},
+"maturityFollowup": {
+  "gaps": ["description_empty"],     // sorted + deduplicated, so comparison is stable
+  "askedAt": "2026-09-15T11:00:00Z",
+  "target": { "kind": "jira", "key": "PROJ-1234", "url": "..." },
+  "commentUrl": "..."
+}
+```
+
+`maturityFollowup` exists only after a comment was posted, and it is a cache: the
+authoritative record of what was asked is the comment on the item itself, because
+that is the only store the next run can see.

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

@@ -0,0 +1,80 @@
+# Feature: Package Manager Resolution
+
+**Pattern**: the node-shaped arms of Phase 3 and the verify-by-test loop typed
+`npm` into the command line. A repo on pnpm, yarn or bun then gets one of two
+outcomes, both bad: the command fails outright, or npm resolves against a lock
+file it does not own and the run continues on a tree the repo's own tooling
+would never have produced. Either way it happens in Phase 3, with a worktree and
+a branch already created - the failure shape `docs/adr/0012-macos-only.md`
+rejected for platforms.
+
+`$HOME/.claude/scripts/package-manager.mjs` resolves it from the repo. Node core
+only (ADR-0004): no corepack call, no spawn, no network - a resolver that shelled
+out would need a working install of the very tool it is identifying. Asserted by
+`smoke-package-manager.sh` and `test/package-manager.test.mjs`.
+
+## 1. Resolution order
+
+| # | Evidence | Reported `source` |
+|---|---|---|
+| 1 | `$MA_PACKAGE_MANAGER` | `env` |
+| 2 | `package.json` `"packageManager"` (corepack's own field) | `packageManager-field` |
+| 3 | a lock file (`pnpm-lock.yaml`, `yarn.lock`, `bun.lockb`/`bun.lock`, `package-lock.json`, `npm-shrinkwrap.json`) | `lockfile` |
+| 4 | npm | `default` |
+
+What the repo **said** outranks what the repo **left behind**: a stale lock file
+outlives a migration and a declaration does not. The default is reported AS a
+default, never as evidence - "npm because nothing said otherwise" and "npm
+because the repo committed a package-lock" are different answers to the same
+question, and only one of them is safe to act on twice.
+
+The walk goes upward from the given directory and stops after the directory
+holding `.git`. A monorepo keeps its lock file at the root while the task edits a
+package three levels down, so stopping at the starting directory would resolve to
+the default for most real repos; going past the repo root would let a stray
+`yarn.lock` in a home directory decide how somebody's project builds.
+
+**Two lock files** means a migration left one behind. The newest wins and BOTH
+are reported (`source: lockfile-newest`, `ambiguous: [...]`): silently picking one
+of two committed lock files is how a repo ends up building with the manager it
+migrated away from.
+
+## 2. The command lines
+
+- **`run` for every manager**, always: `pnpm build` and `yarn build` work only
+  until a script shares a name with a builtin (`test`, `add`, `install`), and
+  then the builtin wins and the repo's own script never runs.
+- **Only npm needs `--`** before pass-through arguments. Adding it for the others
+  hands the test runner a literal `--` to ignore.
+- **`bun run test`, never `bun test`**: the latter is bun's own runner and would
+  ignore the script the repo declared.
+- **No `--frozen-lockfile` / `--immutable`**: that is a CI decision, not ours.
+- **Never `eval "$(pm ...)"` on its own.** Exit 3 empties the command
+  substitution, and `eval ""` SUCCEEDS - so a repo with no build script would
+  report a build that never ran, which is the failure this feature exists to
+  stop, wearing different clothes. Capture first, then eval on success:
+  `CMD=$(... ) && eval "$CMD" || echo "no build script"`.
+- **Exit 3 means the repo declares no such script.** That is the `--if-present`
+  case, answered by an exit code rather than by a flag whose support differs per
+  manager. The caller skips the step and says so; it never substitutes a
+  different command.
+
+## 3. The resolved name goes through `eval`
+
+The phase runs the printed line through `eval`, so the name is held to the shape
+a manager's binary actually has (`^[a-z][a-z0-9-]*$`). A `packageManager` field
+or an `MA_PACKAGE_MANAGER` value that does not match is dropped with a warning
+and the resolution continues from the repo's own evidence. `smoke-package-manager.sh`
+proves this the only way that counts: it evals the produced line with every real
+manager stubbed out and asserts the crafted payload did not run.
+
+An unknown but well-formed name (`deno`, say) resolves and is reported with
+`known: false`, so the caller can say WHICH unrecognised manager it saw instead
+of quietly falling back to npm.
+
+## 4. What is out of scope
+
+iOS and Android are untouched: `xcodebuild` and `./gradlew` are not package
+managers and nothing about this changes them. Installing dependencies is not
+automated either - `installCommand()` exists for a caller that has decided to
+install, and no phase calls it today.

package/pipeline/multi-agent-refs/features/usage-reporting.md

@@ -0,0 +1,79 @@
+# Feature: Operational Reporting
+
+**Pattern**: reporting needs two things - `usageLog.enabled` true AND a token
+that resolves - and both were arranged automatically in exactly one place:
+`/multi-agent:update`, as forty lines of shell embedded in the skill. A user who
+installed the package, ran `/multi-agent:setup` and worked for weeks never ran
+update, so they never registered, never reported, and the panel could not tell
+them apart from nobody using the pipeline at all.
+
+Registration is now one call (`$HOME/.claude/scripts/usage-register.mjs`) made
+from the three places a machine can first become real: **setup**, **update**, and
+**the Phase 0 exit gate** of a run on a machine that reached neither. Asserted by
+`smoke-usage-register.sh`.
+
+## 1. What is sent, and what never is
+
+`usage-report.mjs` emits coarse run metadata: task id, phase, status, durations,
+token counts, the credential-health summary. Never prompts, never code, never
+diffs, never absolute paths. The registration call sends two fields: the
+reporting user and the short hostname.
+
+The reporting user is the **GitHub login** - `identities[0].username`, then
+`gh api user`, then the OS user. Never `identity.name`, which carries a person's
+real name and sometimes a corporate title.
+
+## 2. The token
+
+Requested, never shipped. `/register` mints a per-machine **write-only** token:
+append-only to the ingest endpoint, no read access, no other scope. Only its
+sha256 hash is stored server-side, so a database leak exposes no usable
+credential, and the owner can revoke one row without touching anyone else.
+
+It lands in the OS credential store under `<user>_Usage_Ingest_Token`. Prefs hold
+the NAME of that entry (`keychainMapping.usage_ingest`) and the on-switch, never
+the secret. Resolution order at emit time: `$MULTI_AGENT_USAGE_TOKEN`, then
+`usageLog.token`, then the credential-store entry.
+
+## 3. Opting out, and the two silences
+
+`usageLog.optOut: true` blocks registration permanently and is checked before
+anything else - before the network call, before the credential store.
+
+The other silence is not a choice: offline, endpoint down, ingest disabled by the
+admin, or a credential store that refuses the write. That leaves reporting off
+with one status line and exit 0. **A caller is never failed over bookkeeping**,
+which is the same rule the capture hooks follow.
+
+Both are reported distinguishably (`--json` gives `status`: `skipped` with the
+reason, `unavailable` with the cause, `registered`, `enabled`, `dry-run`) because
+"you turned it off" and "we could not reach the endpoint" are different facts
+about the same empty panel.
+
+`prefs.global.usageLog.endpoint` overrides where both calls go - the register URL
+is derived from it, so a self-hosted ingest gets its own registration rather than
+this one's. Absent means the shipped default, and every shipped default names the
+same host on purpose: a machine that registers against one host and reports to
+another shows up as a token that never sends anything.
+
+## 3b. Feedback is not telemetry
+
+`/multi-agent:feedback` rides the same token, and `optOut` does not silence it:
+passive collection is a choice, a message somebody typed to be read is not. So a
+feedback run may register (`--feedback`) on a machine that opted out - and when it
+does, it writes the credential-store entry and **leaves `usageLog.enabled` alone**.
+The opt-out still holds for everything it was about; the person just gets their
+message delivered.
+
+## 4. The half-configured case
+
+A token in the credential store with `enabled: false` produces exactly the same
+silence as no token at all, and it happens whenever a run is interrupted between
+the two writes. The call repairs it: when a token already resolves but the switch
+is off, it turns the switch on and says so rather than reporting "unchanged".
+
+## 5. Where it is NOT called
+
+The installer. `install.js` lays down files and nothing else; seeding state is the
+one thing the install contract forbids, and a fresh machine has no preferences
+file for the registration to write into. Setup creates it; registration follows.

package/pipeline/multi-agent-refs/features/verify-by-test.md

@@ -5,7 +5,7 @@
 **Gated by `prefs.global.verifyByTest.enabled`** (default: `false`). When enabled, after triage 3.6 and before Step 4, IF the validated triage output contains at least one `accepted` blocking finding:
 
 1. Dispatch ONE verifier sub-agent for the iteration (model: `verifyByTest.model`, default `sonnet`)  -  never one dispatch per finding. Input: up to `verifyByTest.maxFindings` (default 3) accepted blocking findings, the diff hunks for their files, and the Phase 1 test conventions.
-2. Per finding, the verifier writes ONE minimal repro test asserting the correct behavior the finding claims is broken, then runs ONLY that test via the Phase 3 single-test invocation (`xcodebuild test -only-testing:`, `pytest {file}::{name}`, `npm test -- --testPathPattern=`, `./gradlew test --tests`) under `acquire_build_lock`/`release_build_lock`. One green run is not trusted: the same single-test invocation runs `verifyByTest.repeatCount` times (default 3; value 1 disables the repeat) as a shell loop, each run's log tee'd to `$WORKTREE/.pipeline/verify-<i>-<k>.test.log` for `k` in `1..repeatCount`. ALL runs must pass, and each log must clear `evidence-gate.mjs --claim test --status passed`, before the outcome counts as "passes". A first run that fails as predicted ends the loop early (`confirmed` needs no repeat).
+2. Per finding, the verifier writes ONE minimal repro test asserting the correct behavior the finding claims is broken, then runs ONLY that test via the Phase 3 single-test invocation (`xcodebuild test -only-testing:`, `pytest {file}::{name}`, the resolved node command from `scripts/package-manager.mjs test` (npm/pnpm/yarn/bun, never assumed), `./gradlew test --tests`) under `acquire_build_lock`/`release_build_lock`. One green run is not trusted: the same single-test invocation runs `verifyByTest.repeatCount` times (default 3; value 1 disables the repeat) as a shell loop, each run's log tee'd to `$WORKTREE/.pipeline/verify-<i>-<k>.test.log` for `k` in `1..repeatCount`. ALL runs must pass, and each log must clear `evidence-gate.mjs --claim test --status passed`, before the outcome counts as "passes". A first run that fails as predicted ends the loop early (`confirmed` needs no repeat).
 3. Stamp each processed finding with a `verification` object (triage-output schema v3.2.0) and re-run `validate-triage.mjs` on the mutated triage file under the standard 3.2.1 gate protocol.
 4. Findings beyond `maxFindings` keep their judgment-only verdict (log `verify_by_test=cap-exceeded`).
 5. The whole step is bounded by `verifyByTest.stepTimeoutSec` (default 600); on breach or verifier crash, remaining findings keep judgment-only verdicts and the pipeline proceeds. Never blocks.

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

@@ -0,0 +1,83 @@
+# verify - is this install the thing that was published
+
+The install is a COPY. `install.js` writes the pipeline tree into `~/.claude`,
+`~/.copilot` and `~/.codex`, and from that moment the two halves drift
+independently. Both directions produce bugs that are hard to name:
+
+- an edit made in the installed copy is a behaviour with no source, and the next
+  update silently reverts it;
+- a file the installer failed to write is a script the docs describe and nobody
+  has, which reads as a documentation error.
+
+`multi-agent-pipeline verify` answers both mechanically.
+
+```bash
+npx @mmerterden/multi-agent-pipeline verify              # package + install
+npx @mmerterden/multi-agent-pipeline verify --package    # package integrity only
+npx @mmerterden/multi-agent-pipeline verify --install    # install drift only
+npx @mmerterden/multi-agent-pipeline verify --json
+```
+
+| Code | Meaning |
+|---|---|
+| 0 | everything matches |
+| 1 | a difference was found, named file by file |
+| 2 | nothing to verify - a source checkout, or a version published before manifests existed |
+
+Exit 2 is not a pass and not a failure. A dev checkout has no manifest by
+design, and reporting that as either would be a lie in one direction or the
+other.
+
+## The manifest
+
+`manifest.json` is written at pack time by `prepack`, never committed. A
+manifest in git is stale one commit after it is written, and a stale manifest
+reports honest edits as tampering - which is worse than having none, because
+people learn to ignore it.
+
+The file list is not guessed. It comes from `npm pack --dry-run --json`, so by
+construction it is the same set npm publishes, `files` globs and all. The gate
+asserts the two counts agree, which is what catches a `files` entry and a
+manifest that have stopped describing the same package.
+
+Two things it cannot cover, said here rather than discovered later: it cannot
+hash itself, and a signature over it does not authenticate the tarball.
+
+## What a green result proves, and what it does not
+
+It proves the bytes match what the publisher recorded. It is not proof of WHO
+published them. The manifest, the signature and the verifier all travel inside
+the same tarball, so anyone able to rewrite one can rewrite the others.
+Provenance belongs to npm's own integrity field.
+
+What this does catch is the set of failures that actually happen: a damaged or
+partial install, a file edited after install, and an update that did not land.
+
+Signing is optional. `make-manifest.mjs --sign` reads an ed25519 private key
+from the credential store (or `MULTI_AGENT_SIGNING_KEY` on a build host with no
+store) and writes `manifest.sig`; `verify` checks it against
+`MULTI_AGENT_SIGNING_PUBKEY` when one is pinned. Without a key it says "signed,
+no public key to check it against" rather than claiming valid - a signature
+nobody can check is not a signature that passed.
+
+## How each tree is compared
+
+| Tree | Mode | Why |
+|---|---|---|
+| `scripts` | bytes | verbatim copy, minus the dev-only set |
+| `lib` | bytes | verbatim copy |
+| `multi-agent-refs` | bytes | verbatim copy |
+| `agents` | bytes | verbatim copy |
+| `commands/multi-agent` | presence | `install.js` rewrites each SKILL.md `description` into the user's `outputLanguage` |
+
+Byte-comparing `commands/` reports every command as drift on a perfectly
+healthy machine. Measured here: all 57 command files differ, and 56 of them
+differ by nothing except the translated description. A report that is wrong by
+default is a report nobody reads.
+
+The dev-only filter matters just as much: smokes, linters and fixtures ship in
+the package and are deliberately NOT installed. Without excluding them, `verify`
+would report 252 files as "the installer skipped this".
+
+`~/.copilot` and `~/.codex` are reported as present, not compared: the installer
+rewrites paths for both on purpose, so a byte difference there is the design.

package/pipeline/multi-agent-refs/phases/operations.md

@@ -78,8 +78,9 @@ Update `agent-state.json` at EVERY phase transition.
 
 ### Writing `agent-state.json` (required mechanism)
 
-Every state update goes through `write-state.mjs`. Never write the file with a
-plain read-modify-write (`jq ... > tmp && mv`, an editor tool, `cat >`):
+Every state write goes through `write-state.mjs`, **including the first one in
+Phase 0**. Never write the file with a plain read-modify-write (`jq ... > tmp &&
+mv`, an editor tool, `cat >`):
 
 ```bash
 # Merge a patch into the current state (the normal case).
@@ -97,6 +98,16 @@ the first landed. `write-state.mjs` does tmpfile + rename (atomic on POSIX) unde
 an advisory `.lock`, reclaims a lock whose holder PID is dead, and releases the
 lock on every error path.
 
+Why the CREATE matters as much as the updates: the writer stamps `rev` on every
+write and `schemaVersion` on the first one. A document written by hand in Phase 0
+starts with neither, so every later writer compares against an absent revision
+and `migrate-state.mjs` can never place the file on a migration path. Measured on
+a real install before this was fixed: 39 of 43 `agent-state.json` files carried no
+`rev` and 43 of 43 carried no `schemaVersion`, which is the whole of
+`$HOME/.claude/schemas/migrations/` sitting unreachable. `migrate-state.mjs --all`
+reports the legacy ones; it does not stamp them, because a stamp would assert a
+conformance nothing checked.
+
 Exit codes the caller must handle: `0` written, `1` invalid JSON on stdin, `2`
 lock timeout (another writer held it past the acquire window  -  retry once, then
 halt per the halt-visibility rule), `3` I/O error.

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

@@ -514,7 +514,7 @@ done
 
 State file in multi-repo mode:
 - Single shared `agent-state.json` lives at `$HOME/.claude/logs/multi-agent/{first-project}/{task-id}/agent-state.json` (anchored on the first repo for back-compat with `multi-agent log`/`status` commands)
-- Every update to it, here and in every later phase, goes through `node $HOME/.claude/scripts/write-state.mjs`  -  the required mechanism in `operations.md` "Writing `agent-state.json`", and the race a per-repo read-modify-write loses `projects[]` entries to.
+- Every write to it, creation included, goes through `node $HOME/.claude/scripts/write-state.mjs`  -  the required mechanism in `operations.md` "Writing `agent-state.json`", and the race a per-repo read-modify-write loses `projects[]` entries to.
 - `state.projects[]` holds per-repo `{name, root, worktreePath, branch, baseBranch, identity, platform, baseFetchStatus, commit, pr, pushAttempts, buildStatus}`  -  see `agent-state.schema.json`
 - Scalar fields (`project`, `projectRoot`, `worktreePath`, `branch`, `baseBranch`, `identity`) mirror `projects[0]` so legacy phases that read scalars keep working
 - Atomicity: if any repo's worktree creation fails (collision aborted, fetch aborted, disk full), roll back already-created worktrees: `git -C $proj worktree remove --force $WT_PATH; git -C $proj branch -D $BRANCH`. Never leave a partial multi-repo state.
@@ -706,11 +706,14 @@ Phase 0 owns `agent-state.json`. Do not call
 
 ```bash
 node "$HOME/.claude/scripts/phase0-exit-gate.mjs" "$TASK_ID" --input "$ORIGINAL_INPUT"
+node "$HOME/.claude/scripts/usage-register.mjs" --quiet >/dev/null 2>&1 || true
 node "$HOME/.claude/scripts/usage-report.mjs" --task-id "$TASK_ID" >/dev/null 2>&1 || true
 ```
 
-The second line reports the run as started: reporting only from Phase 7 reported
-only runs that finish, and few do. Phase 7 upserts the same key over it.
+The third line reports the run as started: reporting only from Phase 7 reported
+only runs that finish, and few do. Phase 7 upserts the same key over it. The
+second is the backstop for a machine that reached neither setup nor update - it
+is a no-op once a token resolves, and permanently so under `usageLog.optOut`.
 
 It asserts five things, each of which has failed silently in a real run:
 

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

@@ -133,9 +133,15 @@ For each task (respecting dependency order):
                 release_build_lock ;;
        android) ./gradlew test --tests "{testClass}.{testMethod}" 2>&1 | tail -5 ;;
        backend) pytest "{test_file}::{test_name}" 2>&1 | tail -5 ;;
-       web) npm test -- --testPathPattern="{file}" 2>&1 | tail -5 ;;
+       web) CMD=$(node $HOME/.claude/scripts/package-manager.mjs test \
+              --dir "{worktreePath}" --pattern "--testPathPattern={file}") \
+            && eval "$CMD" 2>&1 | tail -5 || echo "no test script declared" ;;
      esac
      ```
+   - The node arm resolves the manager instead of typing `npm`; exit 3 means the repo
+     declares no such script - say so, never substitute one, and never let the empty
+     command substitution pass for a pass (`features/package-manager.md`).
+
    - Must fail for the RIGHT reason (expected assertion, not compilation error)
 
    **GREEN  -  Minimal code to pass:**
@@ -172,7 +178,7 @@ For each task (respecting dependency order):
    - **ios, preferred (MCP, multi-agent-toolkit >= 3.0.0)**: `acquire_build_lock` → `mcp__multi-agent-toolkit__ios_xcodebuild({project|workspace, scheme, configuration: "Release", destination: "generic/platform=iOS", derived_data_path: "{worktreePath}/.DerivedData"})` → `release_build_lock`. Returns one line `Build: SUCCESS|FAILURE (E errors, W warnings) [xcresult-<id>]`; on failure drill in via `mcp__multi-agent-toolkit__ios_xcresult({id, mode: "errors"})`, never dump the full log.
    - **ios, fallback (raw)**: same lock pair around `xcodebuild build -scheme "{scheme}" -destination "generic/platform=iOS" -derivedDataPath "{worktreePath}/.DerivedData" 2>&1 | tail -5`.
    - **android**: lock pair around `./gradlew assembleDebug 2>&1 | tail -5` (the Gradle daemon and `build/` outputs contend across parallel worktrees exactly as DerivedData does  -  the lock applies).
-   - **backend / web**: `python -m compileall .` / `npm run build --if-present 2>&1 | tail -5`; no lock.
+   - **backend / web**: `python -m compileall .` / `CMD=$(node $HOME/.claude/scripts/package-manager.mjs run --dir "{worktreePath}" --script build) && eval "$CMD" 2>&1 | tail -5 || echo "no build script"`; no lock.
 5. If build fails → fix → rebuild (max 3 attempts, track `retryCount` in state).
 6. **Intermediate commit** (after each completed task in the plan):
    ```bash

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

@@ -19,7 +19,7 @@ If any gate fails → fix first, don't waste AI tokens reviewing broken code.
 # Gate 1: Build (xcodebuild/gradle assemble/tsc/py compile  -  stack-dependent; Xcode uses the build queue lock, see Phase 3)  -  tee output to a log
 <build-command> 2>&1 | tee "$WORKTREE/.build.log"
 # Gate 2: Lint (swiftlint/ktlint/ruff/eslint  -  stack-dependent)
-# Gate 3: Tests pass (xcodebuild test/gradle test/pytest/npm test)  -  tee output to a log
+# Gate 3: Tests pass (xcodebuild/gradle/pytest/the resolved node command)  -  tee output to a log
 <test-command> 2>&1 | tee "$WORKTREE/.test.log"
 # Gate 4: Secrets  -  run the scanner against the staged diff
 bash $HOME/.claude/scripts/pre-commit-check.sh

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

@@ -160,6 +160,6 @@ asked anything, so the only thing that keeps it accountable is being readable af
 
 ## 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.
+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. 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, 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), `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. 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.