@mmerterden/multi-agent-pipeline 17.5.0 → 17.6.0

package/pipeline/commands/multi-agent/jira/SKILL.md

@@ -90,12 +90,24 @@ After issue selection, inspect `maturity` from `~/.claude/lib/issue-fetcher.sh`:
 
 | Outcome | Behavior |
 |---|---|
-| `blockers` non-empty | **Halt** (autopilot too): show summary, advise "fix the issue first" |
+| `blockers` non-empty | **Ask, then halt** - see "Blockers" below. Default is still the halt |
 | `warnings` contains `description_empty_parent_available` | Tailored parent-description question above (not the generic one) |
 | `warnings` contains `description_empty_sibling_available` | Same question, sibling key substituted for the parent's |
 | other `warnings` only | AskUserQuestion: show summary + "Continue?". Autopilot auto-continues; warnings logged to `agent-log.md` |
 | both empty (score ≥ 90) | Continue silently |
 
+**Blockers: ask, do not just stop.** `$HOME/.claude/multi-agent-refs/features/maturity-followup.md`
+owns this. In short: an interactive run asks at this step (open the item and fix it /
+continue without it, recording which gap was waved through / abort) instead of ending
+with a summary; an autopilot run with `prefs.global.maturityFollowup.autopilotCommentsOnIssue`
+on posts ONE comment on the item asking for what is missing, then halts on the circuit
+breaker with `state.waitingFor = "maturity"` so `resume` re-enters THIS step with the item
+re-fetched. Both defaults keep today's behaviour: the comment is off, the halt is the halt.
+An edit is a reason to re-check, never proof the gap closed - the check re-runs on the new
+content, and only a DIFFERENT gap set ever earns a second comment. Read the item's existing
+comments FIRST and derive the prior ask from the newest one of ours (`priorFromComments`):
+a scan is a new run with a fresh state file, so state alone would make every scan a first ask.
+
 > **Resolution check**: If Jira `resolution` is set (`Fixed`, `Done`, `Won't Do`, `Resolved`...), `already_resolved` is added  -  the issue was closed already. To reopen, clear `resolution` in Jira first.
 
 > **fixVersions**: When `descriptor.fixVersions` is non-empty (e.g. `["v1.48.0"]`) and a matching `release/v1.48.0` branch exists in `prefs.projects[*].branches`, suggest that branch. Otherwise fall back to `develop`/cwd current.

package/pipeline/commands/multi-agent/resume/SKILL.md

@@ -38,6 +38,21 @@ Resume a paused or failed task from the last successful phase.
    - Claude Code: `TaskCreate` every phase from the state file in phase order, then `TaskUpdate` each to its stored status, and replace every `tasklist_id` meta with the new IDs.
    - Other CLIs: a single `bash $HOME/.claude/scripts/phase-tracker.sh render`.
 
-5. **Continue the pipeline**  -  start from the next phase (same pipeline as the main multi-agent command).
+5. **Continue the pipeline.** Read `state.waitingFor` FIRST: when it names a step, the
+   run re-enters THAT step rather than the next phase. `currentPhase + 1` is the fallback,
+   not the rule - a run that stopped mid-phase to ask a human has `currentPhase` pointing at
+   the phase it is still inside, so resuming past it skips the question permanently. That
+   was already true of Phase 7's channels pause, which documented itself as resumable
+   through this field while this file never mentioned it.
+
+   | `waitingFor` | Re-entry |
+   |---|---|
+   | `maturity` | Phase 0, the maturity step, with the item **re-fetched** and re-scored - an edit is a reason to look again, never proof the gap closed (`$HOME/.claude/multi-agent-refs/features/maturity-followup.md`) |
+   | `user-channels-choice` | Phase 7, the channels multi-select, with the stored `channelsInput` |
+   | absent | `currentPhase + 1`, as before (same pipeline as the main multi-agent command) |
+
+   Clear `waitingFor` in the same write that records the answer, the moment the step is
+   re-entered. A field that outlives the question it asked sends every later resume back
+   to the step the user already answered.
 
 6. **Log**: `🔄 Resumed {JIRA-KEY}-{id} from Phase {N}`

package/pipeline/commands/multi-agent/setup/SKILL.md

@@ -209,9 +209,7 @@ Full key list and shape: `$HOME/.claude/multi-agent-refs/keychain.md`.
 
 `null` = not mapped (missing or skipped). Pipeline phases read this mapping to retrieve tokens dynamically  -  never hardcoded key names.
 
-### Step 2.7  -  Operational reporting token (optional, opt-in)
-
-Only relevant when the admin has issued this user a token. Since v15.8.0, `/multi-agent:update` self-registers a per-machine token automatically when none is onboarded (opt-out: `usageLog.optOut=true`), so Skip here is never a dead end; an admin-issued token pasted now simply takes precedence.
+### Step 2.7  -  Operational reporting
 
 Ask (in `outputLanguage`), and proceed only on an explicit yes:
 
@@ -220,27 +218,27 @@ Do you have an operational-reporting token from your admin?
 [ Paste token / Skip ]
 ```
 
-On paste, store the secret in the credential store ONLY - never in a file, prefs value, git, or any synced/published tree. Use the standard per-user key name so it is revocable independently and consistent across the user's machines:
+On paste, store it in the credential store ONLY - never in a file, prefs value,
+git or any synced tree - under the standard per-user name, so it is revocable on
+its own:
 
 ```bash
 ~/.claude/lib/credential-store.sh set "${USER}_Usage_Ingest_Token" "<pasted-token>"
 ```
 
-Then map it and enable logging (the token itself stays in the credential store; only the logical mapping + the on-switch land in prefs):
+Then, **whether they pasted or skipped**, run:
 
 ```bash
-node -e '
-  const fs=require("fs"),os=require("os"),p=os.homedir()+"/.claude/multi-agent-preferences.json";
-  const j=JSON.parse(fs.readFileSync(p,"utf8"));
-  j.global=j.global||{}; j.global.keychainMapping=j.global.keychainMapping||{};
-  j.global.keychainMapping.usage_ingest=process.argv[1];
-  j.global.usageLog=Object.assign({enabled:true},j.global.usageLog||{},{enabled:true});
-  fs.writeFileSync(p,JSON.stringify(j,null,2)+"\n");
-' "${USER}_Usage_Ingest_Token"
-echo "  -> operational reporting configured (token in credential store)"
+node "$HOME/.claude/scripts/usage-register.mjs"
 ```
 
-Security notes to surface to the user: the token is **write-only** (append-only to the endpoint - no read access, no other scope), stored **only in the OS credential store**, and **per-user** so the admin can revoke this one token without affecting anyone else. `usage-report.mjs` reads it from the credential store at runtime via the `usage_ingest` mapping; it is never written to a file or transmitted except over TLS to the ingest endpoint.
+It maps whatever token exists and switches reporting on, and requests a
+per-machine write-only one when none resolves. This call is why the step exists:
+registration used to happen only inside `/multi-agent:update`, so a user who
+installed, ran setup and never ran update never registered and never reported -
+which reads in the panel exactly like nobody using the pipeline. What is sent,
+what never is, and `usageLog.optOut`:
+`$HOME/.claude/multi-agent-refs/features/usage-reporting.md`.
 
 ### Auto-learned fields (no setup step needed)
 
@@ -802,7 +800,7 @@ All tokens are optional in the sense that every service can be answered with Ski
 
 ### Step 8  -  Enforcement hooks (optional, Claude Code)
 
-Offer to merge `$HOME/.claude/templates/claude-hooks.json`: three `PreToolUse` gates that block on a non-zero exit (secret scan, agent-guard, read-size) plus two capture hooks that block nothing (`SessionEnd`, `SessionStart`). What each does: `$HOME/.claude/multi-agent-refs/picker-contract.md`.
+Offer to merge `$HOME/.claude/templates/claude-hooks.json`: three `PreToolUse` gates that block on a non-zero exit (secret scan, agent-guard, read-size) plus three capture hooks that block nothing (`PreCompact`, `SessionEnd`, `SessionStart`). What each does: `$HOME/.claude/multi-agent-refs/picker-contract.md`.
 
 - Ask (picker): "Install the pipeline's hooks into `~/.claude/settings.json`?" Default Yes.
 - On Yes, deep-merge EVERY event in the template's `hooks` object, not `PreToolUse` alone - merging one event silently drops the capture hooks, and a run killed before Phase 7 then loses its findings exactly as it did before they existed. Preserve existing hooks; never duplicate a matcher already calling the same script.

package/pipeline/commands/multi-agent/update/SKILL.md

@@ -111,65 +111,22 @@ A git clone of the pipeline repo is a maintainer workspace, kept in sync by `/mu
    fi
    ```
 
-5b. **Auto-configure operational reporting.** Off means silent: the emitter still
-   no-ops unless `enabled` is true AND a token resolves. This step never SHIPS a
-   secret; when no token is onboarded it REQUESTS a per-machine write-only token
-   from the reporting endpoint's `/register` route (self-registration, v15.8.0+),
-   stores it only in the credential store, and flips `usageLog.enabled` on. It
-   reports coarse run metadata only - never prompts, code, diffs, or paths.
-   Resolution order: env `MULTI_AGENT_USAGE_TOKEN`, then `usageLog.token`, then
-   the Keychain item named by `keychainMapping.usage_ingest`, then
-   self-registration. Registration failing (offline, endpoint down, admin turned
-   ingest off) leaves reporting off with one status line - never an error.
-   **Opt-out is `usageLog.optOut: true`**: it blocks both the auto-enable and the
-   self-registration permanently; print the opt-out hint on first auto-enable.
+5b. **Auto-configure operational reporting.** One call, and it is the same call
+   `/multi-agent:setup` and a first run make - the registration used to live here
+   as forty lines of shell, so a user who installed, ran setup and never ran
+   update was never registered and never reported, which reads in the panel
+   exactly like nobody using the pipeline.
+
    ```bash
-   PREFS="$HOME/.claude/multi-agent-preferences.json"
-   # Reads go through node, not jq. node is a declared engine (>=20.11) so it
-   # is always there; jq is not, and gating this block on it meant a machine
-   # without jq silently never registered and never reported - which reads in
-   # the panel exactly like nobody using the pipeline.
-   if [ -f "$PREFS" ]; then
-     pref() { node -e 'const fs=require("fs");let v;try{v=process.argv[2].split(".").reduce((a,k)=>a?.[k],JSON.parse(fs.readFileSync(process.argv[1],"utf8")))}catch{};process.stdout.write(v==null?"":String(v))' "$PREFS" "$1" 2>/dev/null; }
-     ENABLED=$(pref global.usageLog.enabled)
-     OPTOUT=$(pref global.usageLog.optOut)
-     if [ "$ENABLED" != "true" ] && [ "$OPTOUT" != "true" ]; then
-       TOK="${MULTI_AGENT_USAGE_TOKEN:-}"
-       [ -z "$TOK" ] && TOK=$(pref global.usageLog.token)
-       if [ -z "$TOK" ]; then
-         KNAME=$(pref global.keychainMapping.usage_ingest)
-         [ -n "$KNAME" ] && TOK=$(bash "$HOME/.claude/lib/credential-store.sh" get "$KNAME" 2>/dev/null)
-       fi
-       if [ -z "$TOK" ]; then
-         EP=$(pref global.usageLog.endpoint); [ -z "$EP" ] && EP="https://mmerterden.vercel.app/api/usage/ingest"
-         REG_EP="${EP%/ingest}/register"
-         # Telemetry identity is the GitHub account name, never the git
-         # identity.name (which can carry a corporate title). username -> live
-         # gh login -> OS user.
-         RUSER=$(pref global.identities.0.username)
-         [ -z "$RUSER" ] && RUSER=$(gh api user --jq .login 2>/dev/null || echo "")
-         [ -z "$RUSER" ] && RUSER="$USER"
-         RESP=$(curl -sSL -m 10 -X POST -H "Content-Type: application/json" \
-           --data "{\"u\":\"$RUSER\",\"c\":\"$(hostname -s 2>/dev/null || echo unknown)\"}" \
-           "$REG_EP" 2>/dev/null)
-         TOK=$(printf '%s' "$RESP" | node -e 'let b="";process.stdin.on("data",d=>b+=d).on("end",()=>{try{process.stdout.write(String(JSON.parse(b).token||""))}catch{}})' 2>/dev/null)
-         if [ -n "$TOK" ]; then
-           printf '%s' "$TOK" | bash "$HOME/.claude/lib/credential-store.sh" set "${USER}_Usage_Ingest_Token" "$(cat)"
-           node -e 'const fs=require("fs"),p=process.argv[1];const j=JSON.parse(fs.readFileSync(p,"utf8"));j.global=j.global||{};j.global.keychainMapping=j.global.keychainMapping||{};j.global.keychainMapping.usage_ingest=process.argv[2];fs.writeFileSync(p,JSON.stringify(j,null,2)+"\n");' "$PREFS" "${USER}_Usage_Ingest_Token"
-           echo "  -> operational reporting: registered this machine (write-only token in credential store)"
-           echo "     opt out any time: set global.usageLog.optOut=true in multi-agent-preferences.json"
-         fi
-       fi
-       if [ -n "$TOK" ]; then
-         node -e 'const fs=require("fs"),p=process.argv[1];const j=JSON.parse(fs.readFileSync(p,"utf8"));j.global=j.global||{};j.global.usageLog=j.global.usageLog||{};j.global.usageLog.enabled=true;fs.writeFileSync(p,JSON.stringify(j,null,2)+"\n");' "$PREFS"
-         echo "  -> operational reporting configured"
-       else
-         echo "  -> operational reporting left off (no token; registration unreachable or disabled)"
-       fi
-     fi
-   fi
+   node "$HOME/.claude/scripts/usage-register.mjs"
    ```
 
+   It requests a per-machine **write-only** token when none resolves, stores it
+   only in the credential store, and flips `usageLog.enabled` on. `usageLog.optOut:
+   true` blocks it permanently. Offline, endpoint down or ingest disabled leaves
+   reporting off with one status line - never an error. Contract and the data it
+   sends: `$HOME/.claude/multi-agent-refs/features/usage-reporting.md`.
+
 6. **Show the new version and its changes** (from the packaged CHANGELOG - there is no git history on this channel):
    ```bash
    NEW=$(tr -d '[:space:]' < "$HOME/.claude/.pipeline-version" 2>/dev/null)

package/pipeline/multi-agent-refs/features/code-graph.md

@@ -3,6 +3,7 @@
 <!-- toc -->
 - [Phase 1 Step 2.6  -  query before dispatching Explore](#phase-1-step-26---query-before-dispatching-explore)
 - [Phase 7 Step 3  -  refresh after the branch changed code](#phase-7-step-3---refresh-after-the-branch-changed-code)
+- [What the report answers that a file-level view cannot](#what-the-report-answers-that-a-file-level-view-cannot)
 - [The graph is drawable, and one place already asks for it](#the-graph-is-drawable-and-one-place-already-asks-for-it)
 <!-- /toc -->
 
@@ -74,6 +75,25 @@ heuristic. A non-zero validator exit keeps the previous graph and logs
 `knowledge.graph_invalid`; it never fails the run  -  a stale graph is a degraded
 Phase 1, not a broken deliverable.
 
+### What the report answers that a file-level view cannot
+
+`GRAPH_REPORT.md` ends with **Symbols nothing else references**: symbols no other
+file in the repo names. The older "unconnected files" section only ever found
+files with NO edge at all, so a file imported for one symbol while three of its
+other exports were dead looked healthy.
+
+It is candidates, never verdicts, and it gates nothing. The extractor is regex
+over comment-stripped source, not a parser (ADR-0010), so dynamic dispatch,
+reflection, string-keyed lookup and a public API consumed outside this repo are
+indistinguishable from dead code here. Four classes are therefore excluded and
+COUNTED rather than listed, because they could not carry a reference edge however
+heavily they are used: a kind outside the stack's `referenceKinds`, a name
+declared in more than one place (the builder drops ambiguous tokens), a nested
+declaration, and anything declared in a test file. Symbols referenced ONLY from
+tests are listed separately - that is not dead code, it is code whose only
+consumer is its own test, which is worth knowing before a plan calls it
+load-bearing.
+
 ### The graph is drawable, and one place already asks for it
 
 The PR body's Impact Analysis, part 3, asks which symbols and files a change

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

@@ -212,6 +212,29 @@ package in the npx cache left the server dying on `Cannot find module` at
 startup, which the client surfaces only as `CONNECTION_CLOSED`, and a check that
 read the registration and stopped would have called that healthy.
 
+### mcp-surface
+
+How many MCP servers are charged in the project the caller is standing in,
+counted across three places that all cost the same: the global blocks in
+`~/.claude.json` and `~/.claude/settings.json`, the per-project block inside
+`~/.claude.json`, and a `.mcp.json` committed to the repo. INFO once the count
+exceeds `prefs.global.mcpSurface.infoAbove` (default 8); `--explain` lists the
+names with the scope each came from.
+
+Servers registered by a marketplace plugin are NOT counted: nothing in the
+config names them, and inventing a number is worse than reporting the one that
+is countable.
+
+The reason it exists: every registered server sends its tool list on every turn,
+the user adds them one at a time, and nobody ever sees the running total - our
+own toolkit contributes 99 tools by itself. This is the same argument that made
+the pre-run context budget a measured number rather than an intention.
+
+It only reports. It never disables a server, never blocks and never warns: how
+many servers are worth their context is the user's call, not a health failure.
+The threshold is judgement, which is why it is a pref instead of a constant in
+the script - a number nobody can see is a number nobody can argue with.
+
 ### disk-space
 
 Free space on the volume holding `$HOME`. WARN under 2 GB: a worktree plus a

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/phases/phase-0-init.md

@@ -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: