@mmerterden/multi-agent-pipeline 19.1.3 → 20.0.0

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

@@ -66,7 +66,7 @@
     },
     "worktreePath": {
       "type": ["string", "null"],
-      "description": "Absolute path to the task worktree. Null in --local mode."
+      "description": "Absolute path to the task worktree. Null when the Step 5b picker answered local."
     },
     "branch": {
       "type": "string",
@@ -274,7 +274,7 @@
     "workspaceSource": {
       "type": "string",
       "enum": ["asked", "command", "autopilot"],
-      "description": "Who decided where the branch lives. asked = the user answered the Step 5b workspace picker; command = :local / --local / :local-autopilot stated it up front, or a flow that only ever builds worktrees; autopilot = resolved to a worktree without asking, because an unattended commit in the user's own checkout is what worktrees prevent. localMode alone cannot say: false is both a chosen worktree and one nothing asked about."
+      "description": "Who decided where the branch lives. asked = the user answered the Step 5b workspace picker; command = a flow that only ever builds worktrees stated it up front; autopilot = resolved to a worktree without asking, because an unattended commit in the user's own checkout is what worktrees prevent. localMode alone cannot say: false is both a chosen worktree and one nothing asked about."
     },
     "remoteType": {
       "type": "string",
@@ -476,15 +476,10 @@
       "type": "boolean",
       "default": false
     },
-    "onlyDevelop": {
-      "type": "boolean",
-      "default": false,
-      "description": "Short pipeline  -  phases 1 and 2 are skipped. Set by the Phase 0 Step 7.5 depth picker as of v16.0.0; the key and every reader of it are unchanged. Phase 3 Review still runs (v14.0.0+). Always false in an autopilot run, which never asks the depth question."
-    },
     "localMode": {
       "type": "boolean",
       "default": false,
-      "description": "--local flag  -  no worktree, direct branch in projectRoot."
+      "description": "Step 5b answered local  -  no worktree, direct branch in projectRoot."
     },
     "instructionDriven": {
       "type": "boolean",
@@ -498,7 +493,7 @@
     "analysis": {
       "type": ["object", "null"],
       "additionalProperties": true,
-      "description": "Phase 1 analysis-document outcome. Absent in Short runs, which produce no document by design.",
+      "description": "Phase 1 analysis-document outcome. Phase 1 runs in every mode, so a document is always produced; what varies is how many of its sections the evidence supported.",
       "properties": {
         "docStatus": {
           "type": "string",
@@ -1530,7 +1525,7 @@
               }
             }
           },
-          "description": "Captured in Phase 2 after the build+test gate, because the user test is dropped by every autopilot and --local entry."
+          "description": "Captured in Phase 2 after the build+test gate, because the user test is dropped by every autopilot entry and by any run whose workspace is local."
         },
         "host": {
           "type": ["string", "null"],

package/pipeline/schemas/migrations/prefs-2.7.0-to-2.8.0.mjs

@@ -0,0 +1,33 @@
+/**
+ * prefs-2.7.0-to-2.8.0.mjs  -  preferences migration
+ *
+ * v20.0.0 folds `/multi-agent:resume-local` into `/multi-agent:resume`. One
+ * command now asks which unfinished work to pick up: a run that stopped
+ * mid-phase, or a branch carrying work no run ever produced. The preference
+ * that decides whether triage-accepted findings are auto-fixed applies to the
+ * second path, so it moves with it: `global.resumeLocal` -> `global.resume`.
+ *
+ * The value is carried, never reset. Someone who turned auto-fix on for the
+ * tail meant it for exactly the work this path still handles.
+ *
+ * @param {object} data  -  parsed multi-agent-preferences.json
+ * @returns {object}     -  migrated data with schemaVersion "2.8.0"
+ */
+export default function migrate(data) {
+  const out = JSON.parse(JSON.stringify(data));
+
+  out.schemaVersion = "2.8.0";
+
+  if (!out.global || typeof out.global !== "object") return out;
+
+  const legacy = out.global.resumeLocal;
+  if (!out.global.resume || typeof out.global.resume !== "object") {
+    out.global.resume = {};
+  }
+  if (typeof out.global.resume.autoFix !== "boolean") {
+    out.global.resume.autoFix = typeof legacy?.autoFix === "boolean" ? legacy.autoFix : false;
+  }
+  delete out.global.resumeLocal;
+
+  return out;
+}

package/pipeline/schemas/phases.json

@@ -6,7 +6,6 @@
   "phaseSchema": 2,
   "phaseSchemaNote": "The phase vocabulary generation. metrics.jsonl is append-only and v19.0.0 renumbered the phases, so every line written from v19.0.0 on carries this number and a line without the field is generation 1. Aggregators pick their name table from it; without it phase 3 means Dev in old rows and Review in new ones and no reader can tell them apart.",
   "legacyPhaseNames": {
-    "note": "Generation 1 phase names, kept so an aggregator can label a historical metrics.jsonl row correctly instead of printing the current name for a number that meant something else. Read-only history: nothing emits these any more. The generation 1 -> 2 number map is not repeated here, it is the `was` array on each phase above.",
     "0": "Init",
     "1": "Analysis",
     "2": "Planning",
@@ -14,7 +13,8 @@
     "4": "Review",
     "5": "Test",
     "6": "Commit",
-    "7": "Report"
+    "7": "Report",
+    "note": "Generation 1 phase names, kept so an aggregator can label a historical metrics.jsonl row correctly instead of printing the current name for a number that meant something else. Read-only history: nothing emits these any more. The generation 1 -> 2 number map is not repeated here, it is the `was` array on each phase above."
   },
   "phases": [
     {
@@ -64,35 +64,14 @@
   "modes": {
     "full": {
       "phases": [0, 1, 2, 3, 4, 5],
-      "local": false,
-      "autopilot": false,
-      "depth": true
+      "autopilot": false
     },
     "autopilot": {
       "phases": [0, 1, 2, 3, 4, 5],
-      "local": false,
-      "autopilot": true
-    },
-    "local": {
-      "phases": [0, 1, 2, 3, 4, 5],
-      "local": true,
-      "autopilot": false,
-      "depth": true
-    },
-    "local-autopilot": {
-      "phases": [0, 1, 2, 3, 4, 5],
-      "local": true,
       "autopilot": true
     },
-    "full-local": {
-      "phases": [0, 1, 2, 3, 4, 5],
-      "local": true,
-      "autopilot": false,
-      "depth": true
-    },
     "analysis": {
       "phases": [0, 1, 3, 4, 5],
-      "local": false,
       "autopilot": false
     }
   },

package/pipeline/schemas/prefs.schema.json

@@ -14,8 +14,8 @@
   "properties": {
     "schemaVersion": {
       "type": "string",
-      "enum": ["2.0.0", "2.1.0", "2.2.0", "2.3.0", "2.4.0", "2.5.0", "2.6.0", "2.7.0"],
-      "description": "v2.0.0: pre-v3.7. v2.1.0: v3.7+ adds identities[].servicePatMap, platformIdentityRouting, recentGroups, recentBranches, serviceStatus, settings, expanded keychainMapping. v2.2.0: v6.0.0 formalizes v5.7 / v5.8 additions (reportChannels, reportContent with technicalAnalysis, wikiScope, autopilotReportTimeoutSeconds) that had been running as 2.1.0 sub-migrations without a proper version bump. v2.5.0: v14.0.0 adds global.skillConformance (Phase 4 criteria resolution) and declares global.ship.autoFix, which the tail command's spec had referenced as global.finish.autoFix without ever declaring it. v2.6.0: v15.0.0 renames global.ship to global.resumeLocal (/multi-agent:ship -> :resume-local). v2.7.0: v19.0.0 drops the analysis Lite mode (global.analysisPhase.mode keeps a single value 'full') and adds global.modelRouting, which ships disabled."
+      "enum": ["2.0.0", "2.1.0", "2.2.0", "2.3.0", "2.4.0", "2.5.0", "2.6.0", "2.7.0", "2.8.0"],
+      "description": "v2.0.0: pre-v3.7. v2.1.0: v3.7+ adds identities[].servicePatMap, platformIdentityRouting, recentGroups, recentBranches, serviceStatus, settings, expanded keychainMapping. v2.2.0: v6.0.0 formalizes v5.7 / v5.8 additions (reportChannels, reportContent with technicalAnalysis, wikiScope, autopilotReportTimeoutSeconds) that had been running as 2.1.0 sub-migrations without a proper version bump. v2.5.0: v14.0.0 adds global.skillConformance (Phase 4 criteria resolution) and declares global.ship.autoFix, which the tail command's spec had referenced as global.finish.autoFix without ever declaring it. v2.6.0: v15.0.0 renames global.ship to global.resumeLocal (/multi-agent:ship -> :resume-local). v2.7.0: v19.0.0 drops the analysis Lite mode (global.analysisPhase.mode keeps a single value 'full') and adds global.modelRouting, which ships disabled. v2.8.0: v20.0.0 folds :resume-local into :resume and renames global.resumeLocal to global.resume."
     },
     "global": {
       "type": "object",
@@ -1923,15 +1923,15 @@
             }
           }
         },
-        "resumeLocal": {
+        "resume": {
           "type": "object",
           "additionalProperties": false,
-          "description": "/multi-agent:resume-local (formerly :ship, :finish) - the tail that runs review + build/test + PR + report over work already on the branch.",
+          "description": "/multi-agent:resume - picking up unfinished work, either a run that stopped mid-phase or a branch carrying work no run produced. These keys apply to the second path, which runs review + build/test + PR + report over the branch diff.",
           "properties": {
             "autoFix": {
               "type": "boolean",
               "default": false,
-              "description": "When true, resume-local auto-fixes triage-accepted blocking/important findings and re-reviews instead of asking. Equivalent to passing `autopilot` on every run. Default false: resume-local operates on work the user wrote by hand, so silently rewriting it is the surprising option."
+              "description": "When true, the tail path auto-fixes triage-accepted blocking/important findings and re-reviews instead of asking. Equivalent to passing `autopilot` on every run. Default false: this path operates on work the user wrote by hand, so silently rewriting it is the surprising option."
             }
           }
         },

package/pipeline/scripts/autopilot-runner.mjs

@@ -587,13 +587,12 @@ function main() {
   const attempts = readAttempted();
   const breaker = consecutiveFailures(attempts);
   if (BREAKER_LIMIT > 0 && breaker.count >= BREAKER_LIMIT) {
-    // HALF-OPEN, not latched. The first version of this returned here on every
-    // tick, and the only writer of attempted.jsonl is downstream of this
-    // return - so once it opened, no new attempt could ever be recorded, the
-    // consecutive count could never fall, and the runner was stopped for good.
-    // The log line said "until an attempt succeeds" and the feature doc said
-    // "one successful attempt clears it": both described a state the code made
-    // unreachable.
+    // HALF-OPEN, not latched. The only writer of attempted.jsonl is downstream
+    // of this return, so returning on every tick would mean that once the
+    // breaker opened no new attempt could be recorded, the consecutive count
+    // could never fall, and the runner would be stopped for good - while the
+    // log line promises "until an attempt succeeds" and the feature doc
+    // promises "one successful attempt clears it".
     //
     // A breaker that cannot re-close is not a breaker, it is an off switch with
     // a misleading label. So after a cooldown one probe is let through: if the

package/pipeline/scripts/build-references.mjs

@@ -2,9 +2,9 @@
 // build-references.mjs  -  deterministic Section 21 References table for an
 // /multi-agent:analysis document (Locked 33).
 //
-// The references table used to be prose the model filled in. That lists what an
-// author remembers consulting, which is a different set from what the run
-// actually fetched: sources that failed to load vanish silently, scope decisions
+// The references table is built, not written as prose the model fills in. Prose
+// lists what an author remembers consulting, which is a different set from what
+// the run actually fetched: sources that failed to load vanish silently, scope decisions
 // made in conversation never appear, and a Figma link with no node id points at
 // whatever the file looks like today. This turns the table into a projection of
 // `state.analysisSpec.evidence.*` so the two cannot disagree.

package/pipeline/scripts/build-stack-plugins.mjs

@@ -72,7 +72,7 @@ const PLUGINS_REPO = getArg("--plugins-repo", join(HOME, "multi-agent-plugins"))
 // nowhere else: on a CI runner the checkout is under the workspace directory,
 // so --check-routing reported "source not found" and three tests failed on
 // every clean host while passing locally. That is the whole class of bug CI
-// exists to catch, and it survived because CI was asleep.
+// exists to catch, which is why this path is not left to CI alone.
 const PIPE_ROOT = getArg("--pipeline", join(dirname(fileURLToPath(import.meta.url)), "..", ".."));
 const EXTERNAL = join(PIPE_ROOT, "pipeline/skills/shared/external");
 const DRY = args.includes("--dry-run");

package/pipeline/scripts/bulk-read.sh

@@ -91,10 +91,12 @@ if command -v jq >/dev/null 2>&1; then
 fi
 [ -n "$MODEL" ] || MODEL="${PREF_MODEL:-haiku}"
 
-# bulk-read is one of the two call sites the pipeline makes itself, so routing
-# may send it outside the Anthropic ladder - unlike a subagent, nothing here
-# belongs to the host. An explicit --model still wins: a caller that named a
-# rung asked for that rung.
+# Routing picks the rung INSIDE the Anthropic ladder. The worker below is the
+# `claude` CLI, which speaks that ladder and nothing else, so a rung on another
+# provider is refused at dispatch rather than returned and failed. Sending this
+# read to a third-party provider would put the file's full text outside the
+# account that owns it, and that is a decision a user makes, not a default.
+# An explicit --model still wins: a caller that named a rung asked for that rung.
 if [ -z "${MODEL_EXPLICIT:-}" ] && [ -x "$HERE/../lib/model-dispatch.sh" ]; then
   MODEL=$("$HERE/../lib/model-dispatch.sh" bulk-read \
             --phase "$PHASE" --default "$MODEL" 2>/dev/null) || MODEL="${PREF_MODEL:-haiku}"

package/pipeline/scripts/cost-table.json

@@ -16,7 +16,7 @@
       "cacheReadPerMtok": 0.5,
       "modelId": "claude-opus-5",
       "provider": "anthropic",
-      "note": "Second tier - dev phase on a Short run, Reviewer 1 and triage on Copilot CLI, and the opus rung of the fable -> opus -> sonnet fallback ladder. Same rate as the Opus 4.8 it replaces, so the ledger needed no reprice on the generation move. Claude Opus 5 draws on a rate-limit pool SEPARATE from the combined Opus 4.x pool - moving traffic here neither frees headroom on the old bucket nor inherits it."
+      "note": "Second tier - Reviewer 1 and triage on Copilot CLI, and the opus rung of the fable -> opus -> sonnet fallback ladder. Same rate as the Opus 4.8 it replaces, so the ledger needed no reprice on the generation move. Claude Opus 5 draws on a rate-limit pool SEPARATE from the combined Opus 4.x pool - moving traffic here neither frees headroom on the old bucket nor inherits it."
     },
     "sonnet": {
       "inPerMtok": 3.0,

package/pipeline/scripts/doctor.mjs

@@ -1051,10 +1051,10 @@ function main() {
   process.exitCode = code;
 }
 
-// Exported so the gate can DRIVE the engine instead of reading it. The BLOCK
-// downgrade used to be asserted with a regex over this file's own source, which
-// a comment carrying the same two substrings satisfied just as well as the code
-// did - the enforcement could be deleted outright and the gate stayed green.
+// Exported so the gate can DRIVE the engine instead of reading it. Asserting the
+// BLOCK downgrade with a regex over this file's own source proves nothing: a
+// comment carrying the same two substrings satisfies it as well as the code does,
+// so the enforcement could be deleted outright and the gate would stay green.
 export { report, results as __results, MAY_BLOCK as __mayBlock };
 
 // realpath on both sides: `import.meta.url` is already resolved, while argv[1]

package/pipeline/scripts/gc-refs.sh

@@ -4,7 +4,7 @@
 # `offload-ref.sh` parks build logs, diffs and test output under
 # <root>/.multi-agent/refs/<node_id>.md so a phase prompt can carry a pointer
 # instead of the whole log. In worktree modes that directory dies with the
-# worktree. In the --local modes there is no worktree: the refs land in the
+# worktree. With a local workspace there is no worktree: the refs land in the
 # real checkout and nothing ever removes them. They are gitignored, so they are
 # invisible to `git status` and grow without bound.
 #

package/pipeline/scripts/gen-mode-dispatch.mjs

@@ -16,12 +16,9 @@ import { readFileSync } from "node:fs";
  *   node pipeline/scripts/gen-mode-dispatch.mjs --mode=autopilot    # 0..5
  *   node pipeline/scripts/gen-mode-dispatch.mjs --mode=analysis     # 0/1/3/4/5 (no Dev)
  *
- * v16.0.0 removed the four dev-* modes. Depth is no longer a command name: the
- * Phase 0 Step 7.5 picker asks Full or Short and sets `state.onlyDevelop`. That
- * answer arrives long after the tracker boots at Step -1, so v17.5.0 splits
- * registration for the two modes that ask it (`full`, `local`): Phase 0 at Step -1,
- * the rest once depth has named them. Everything else still registers its whole
- * set up front, and a generated phase set is per-COMMAND, never per-depth.
+ * There is one pipeline. A mode's phase set is a property of the COMMAND and is
+ * known before the tracker boots, so every mode registers its whole set at
+ * Step -1 and no registration is deferred.
  *
  * Companion smoke `smoke-mode-dispatch-drift.sh` regenerates the section for
  * each mode file, diffs against the on-disk content, and fails on drift.
@@ -63,9 +60,7 @@ const MODES = Object.fromEntries(
     name,
     {
       phases: modePhases(name),
-      local: m.local,
       autopilot: m.autopilot,
-      ...(m.depth ? { depth: true } : {}),
     },
   ]),
 );
@@ -86,9 +81,6 @@ const phaseSequence = activeIds.map((id) => `Phase ${id}`).join(" → ");
 const MODE_LABELS = {
   autopilot: "`autopilot`",
   full: "full-pipeline",
-  local: "`--local`",
-  "local-autopilot": "`--local autopilot`",
-  "full-local": "full-pipeline + `--local`",
 };
 const modeLabel = MODE_LABELS[MODE] ?? `\`${MODE}\``;
 
@@ -98,46 +90,24 @@ const skipNote =
     ? `${modeLabel} mode does NOT TaskCreate phases ${skippedIds.join("/")}  -  those are not part of the ${modeLabel} phase set (\`${spec.phases.join(" ")}\`). Only register tiles for the active set.`
     : `${modeLabel} mode TaskCreates all ${PHASES.length} phases (no phase is skipped).`;
 
-const orderingNote = `**All TaskCreate calls in a batch fire in strict phase-number order BEFORE any TaskUpdate is applied.** For ${modeLabel} that means: ${spec.depth ? `Phase 0 at Step -1, then the rest in ascending order at Step 7.5 (${phaseSequence} minus whatever the depth answer drops)` : phaseSequence}. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks. Full ordering contract in \`$HOME/.claude/multi-agent-refs/tracker-contract.md\` section "TaskCreate ordering (strict)".`;
-
-const localCaveat = spec.local
-  ? `\n> **Local mode:** no worktree is created, work happens on the current branch. Phase 0 Init still calls \`init\`  -  the \`--local\` flag is stored in tracker-state.json, and \`:resume\` restores the correct CWD.\n`
-  : "";
+const orderingNote = `**All TaskCreate calls in a batch fire in strict phase-number order BEFORE any TaskUpdate is applied.** For ${modeLabel} that means: ${phaseSequence}. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks. Full ordering contract in \`$HOME/.claude/multi-agent-refs/tracker-contract.md\` section "TaskCreate ordering (strict)".`;
 
 const banner = spec.autopilot
   ? `\n> **Autopilot mode:** user confirmations are skipped. The tracker is still mandatory  -  autopilot agent calls cannot skip it; skipping breaks \`smoke-tracker-contract.sh\`.\n`
   : "";
 
-// Registration shape. A mode that asks the depth question does not know its phase
-// set at Step -1 (the answer needs taskType, which needs the fetched issue and the
-// branch), so it registers Phase 0 there and the rest at Step 7.5. Drawing eight
-// tiles beside the question that decides whether two of them run is the failure this
-// split exists to remove.
-const fullSet = spec.phases.filter((p) => p !== "0:Init");
-const shortSet = fullSet.filter((p) => Number(p.split(":")[0]) >= 2);
+// Registration shape. Every mode knows its whole phase set at Step -1, so every
+// tile is created there and nothing is appended later.
 const loopFor = (list) =>
   `for p in ${list.map((x) => `"${x}"`).join(" ")}; do\n  bash $HOME/.claude/scripts/phase-tracker.sh add "\${p%%:*}" "\${p#*:}"\ndone`;
 
-const initLoop = spec.depth
-  ? 'bash $HOME/.claude/scripts/phase-tracker.sh add 0 "Init"\nbash $HOME/.claude/scripts/phase-tracker.sh tiles'
-  : `${loopFor(spec.phases)}`;
-
-const deferredBlock = spec.depth
-  ? `
-# Phase 0 Step 7.5, immediately after the depth answer - the first moment this
-# mode knows its phase set. Full:
-${loopFor(fullSet)}
-# Short (Analysis and Planning are not run, so they get no tile at all):
-${loopFor(shortSet)}
-# Then the widget, narrowed to the phases that do not have a tile yet:
-bash $HOME/.claude/scripts/phase-tracker.sh tiles --new
-`
-  : "";
+const initLoop = loopFor(spec.phases);
+const deferredBlock = "";
 
 const out = `## Required: Phase Tracker Contract
 
 **The phase tracker is mandatory**  -  the agent cannot skip it. Full spec: [\`$HOME/.claude/multi-agent-refs/tracker-contract.md\`]($HOME/.claude/multi-agent-refs/tracker-contract.md).
-${banner}${localCaveat}
+${banner}
 Two channels run in parallel at every phase boundary:
 
 1. **State channel** (every CLI, identical): \`phase-tracker.sh\` writes to \`tracker-state.json\`. Drives \`:resume\`, \`:log\`, \`:status\`.
@@ -160,11 +130,11 @@ bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out> [cached]
 
 In Claude Code the agent MUST also drive the native TaskList widget so the user sees a sticky phase tile stack  -  this is the only progress signal Claude Code surfaces. Skipping these calls is the #1 source of "I don't see any phases" complaints.
 
-**TaskCreate ordering (strict)**: All TaskCreate calls in a registration batch fire in strict phase-number order BEFORE any TaskUpdate in that batch, and a later batch only ever appends phases numbered above everything already registered.${spec.depth ? " This mode registers in two batches (Step -1, then Step 7.5), so `tiles --new` narrows the second one and the Phase 0 tile is never created twice." : ""} The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks (e.g. \`1 ✓ · 2 ✓ · 4 ✓ · 0 ▶ · 3 ☐\`) even when the underlying state is correct. Pre-marking phases as completed/skipped before Phase 0 starts is FORBIDDEN  -  register the tile in order, then flip status via TaskUpdate when the phase actually short-circuits. Full contract in \`$HOME/.claude/multi-agent-refs/tracker-contract.md\` section "TaskCreate ordering (strict)".
+**TaskCreate ordering (strict)**: All TaskCreate calls in a registration batch fire in strict phase-number order BEFORE any TaskUpdate in that batch, and a later batch only ever appends phases numbered above everything already registered. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks (e.g. \`1 ✓ · 2 ✓ · 4 ✓ · 0 ▶ · 3 ☐\`) even when the underlying state is correct. Pre-marking phases as completed/skipped before Phase 0 starts is FORBIDDEN  -  register the tile in order, then flip status via TaskUpdate when the phase actually short-circuits. Full contract in \`$HOME/.claude/multi-agent-refs/tracker-contract.md\` section "TaskCreate ordering (strict)".
 
 \`\`\`text
 # Register one tile per phase, capture the taskId, persist it:
-for each phase in ${spec.depth ? `0:Init at Step -1, then ${fullSet.join(", ")} (Full) or ${shortSet.join(", ")} (Short) at Step 7.5` : spec.phases.join(", ")}:
+for each phase in ${spec.phases.join(", ")}:
   TaskCreate({ subject: "Phase <N>: <Name>", activeForm: "<doing-form>" })
     -> returns taskId
   bash $HOME/.claude/scripts/phase-tracker.sh meta <N> tasklist_id "<taskId>"

package/pipeline/scripts/learnings-ledger.mjs

@@ -475,7 +475,7 @@ function cmdBrief() {
     );
     ordered = fused.slice(0, max).map((x) => pool[x.index]);
     // A task whose words match nothing in the ledger must not silently inject an
-    // empty block where the newest entries used to be: fall back to recency.
+    // empty block in place of the newest entries: fall back to recency.
     if (ordered.length === 0) ordered = pool.slice().reverse().slice(0, max);
   }
 

package/pipeline/scripts/match-skills.mjs

@@ -40,10 +40,10 @@ const here = dirname(fileURLToPath(import.meta.url));
  *
  * This script lives in two shapes: `<repo>/pipeline/scripts/` in a checkout, and
  * `~/.claude/scripts/` (or `~/.copilot`, `~/.codex`) once installed. The default
- * used to be `resolve(here, "..", "..") + "/pipeline/skills/.skills-index.json"`,
- * which is right in a checkout and resolves to `$HOME/pipeline/skills/...` from an
- * installed tree - a path that has never existed. So dynamic skill loading exited 1
- * on every real install while passing its own smoke, which runs from the repo.
+ * is NOT `resolve(here, "..", "..") + "/pipeline/skills/.skills-index.json"`.
+ * That is right in a checkout and resolves to `$HOME/pipeline/skills/...` from an
+ * installed tree - a path that does not exist. Dynamic skill loading would exit 1
+ * on every real install while passing a smoke that runs from the repo.
  *
  * Installed layout is tried first: that is where a user's run happens.
  */

package/pipeline/scripts/memory-load.sh

@@ -11,9 +11,9 @@
 # scripts/_retrieval.mjs) and the most relevant are printed. Without it the
 # index order is kept, which is what every existing caller gets.
 #
-# The cap used to be a bare `head -30`. That is a truncation, not a summary: the
-# thirty-first pointer was invisible however precisely it matched the task, and
-# the block got less useful the longer a repo was worked on - the opposite of
+# The cap is not a bare `head -30`. That is a truncation, not a summary: the
+# thirty-first pointer stays invisible however precisely it matches the task, and
+# the block gets less useful the longer a repo is worked on - the opposite of
 # what accumulated memory is for.
 #
 # Honors `prefs.global.perRepoMemory`. When the pref is off OR the prefs file

package/pipeline/scripts/migrate-prefs.mjs

@@ -357,31 +357,32 @@ function migrate(prefs) {
     out.global.skillConformance.blockOnCoverageGap = false;
     changes.push("added skillConformance.blockOnCoverageGap=false (report, do not halt)");
   }
-  // Rename chain for the pipeline-tail command: /multi-agent:finish (pre-v2.5.0)
-  // -> :ship (v2.5.0) -> :resume-local (current). The autoFix value survives every
-  // hop - carry whichever legacy block still holds one rather than reset it.
-  if (!out.global.resumeLocal || typeof out.global.resumeLocal !== "object") {
-    out.global.resumeLocal = {};
-    changes.push("added resumeLocal (/multi-agent:ship renamed to :resume-local)");
-  }
-  if (typeof out.global.resumeLocal.autoFix !== "boolean") {
-    const legacyAutoFix =
-      typeof out.global.ship?.autoFix === "boolean"
-        ? out.global.ship.autoFix
-        : out.global.finish?.autoFix;
-    out.global.resumeLocal.autoFix = typeof legacyAutoFix === "boolean" ? legacyAutoFix : false;
+  // Rename chain for the tail that runs over work already on the branch:
+  // global.finish -> global.ship -> global.resumeLocal -> global.resume, the
+  // last hop following the command itself into /multi-agent:resume. The
+  // autoFix value survives every hop - carry whichever legacy block still
+  // holds one rather than reset it.
+  if (!out.global.resume || typeof out.global.resume !== "object") {
+    out.global.resume = {};
+    changes.push("added resume (:resume-local folded into :resume)");
+  }
+  if (typeof out.global.resume.autoFix !== "boolean") {
+    const legacyAutoFix = ["resumeLocal", "ship", "finish"]
+      .map((k) => out.global[k]?.autoFix)
+      .find((v) => typeof v === "boolean");
+    out.global.resume.autoFix = typeof legacyAutoFix === "boolean" ? legacyAutoFix : false;
     changes.push(
       typeof legacyAutoFix === "boolean"
-        ? "moved ship/finish autoFix -> resumeLocal.autoFix (value preserved)"
-        : "added resumeLocal.autoFix=false",
+        ? "moved tail autoFix -> resume.autoFix (value preserved)"
+        : "added resume.autoFix=false",
     );
   }
-  for (const legacy of ["ship", "finish"]) {
+  for (const legacy of ["resumeLocal", "ship", "finish"]) {
     if (out.global[legacy] && typeof out.global[legacy] === "object") {
       delete out.global[legacy].autoFix;
       if (Object.keys(out.global[legacy]).length === 0) {
         delete out.global[legacy];
-        changes.push(`removed obsolete ${legacy} block (renamed to resumeLocal)`);
+        changes.push(`removed obsolete ${legacy} block (renamed to resume)`);
       }
     }
   }

package/pipeline/scripts/phase-tracker.sh

@@ -1132,7 +1132,7 @@ case "$ACTION" in
     state=$(load_state)
     # Idempotent: a phase id that already exists is a no-op (name, status, and
     # token history are preserved). This is what lets continuation commands
-    # (/multi-agent:resume-local, resume) re-declare their phase set against a
+    # (/multi-agent:resume, /multi-agent:manual-test) re-declare their phase set against a
     # pre-existing tracker without duplicating or resetting tiles.
     new=$(echo "$state" | jq --arg id "$PID" --arg name "$PNAME" '
       if any(.phases[]?; .id == $id) then .
@@ -1167,7 +1167,7 @@ case "$ACTION" in
     # completion is recoverable (record, then re-run) and loses no work; a
     # phase that genuinely made no LLM call says so with --no-llm.
     if [ "$STATUS" = "completed" ] && [ "$NO_LLM" -eq 0 ]; then
-      case " ${TRACKER_LLM_PHASES:-1 2 3 4} " in
+      case " ${TRACKER_LLM_PHASES:-1 2 3 4 5} " in
         *" $PID "*)
           RECORDED=$(load_state | jq -r --arg id "$PID" \
             '(.phases[] | select(.id == $id) | (.tokens_in // 0) + (.tokens_out // 0)) // 0')

package/pipeline/scripts/phase0-exit-gate.mjs

@@ -270,7 +270,7 @@ export function evaluate(state, extraInput = "") {
     failures.push(
       `workspaceSource="autopilot" on an interactive run. Autopilot resolves the workspace ` +
         `to a worktree because an unattended commit in the user's own checkout is what ` +
-        `worktrees prevent; an interactive run asks (Step 5b) or is told by :local / --local.`,
+        `worktrees prevent; an interactive run asks at Step 5b, and the multi-repo bridge records "command".`,
     );
   }
 

package/pipeline/scripts/plan-coverage-gate.mjs

@@ -77,9 +77,9 @@ export function filesToAdd(markdown) {
     if (!path || /^-+$/.test(path)) continue;
     if (path.includes("<") || tag.includes("<")) continue;
     // No header-row filter: the tag column of the header reads "Etiket / Tag",
-    // which the `Add new` test below already rejects. The filter that used to be
-    // here matched on the PATH column instead and would have skipped a real row
-    // whose path begins with a `File/` directory.
+    // which the `Add new` test below already rejects. A filter here would have to
+    // match on the PATH column instead, and would skip a real row whose path
+    // begins with a `File/` directory.
     if (!/^add new$/i.test(tag)) continue;
     rows.push(path);
   }
@@ -150,9 +150,9 @@ if (isMain) {
 
   // No plan at all is not a pass, and neither is an empty one: a Phase 2 that
   // produced no steps, or a state whose todos got cleared, would otherwise read
-  // as "0/0 accounted for" and let the commit through. A Short run has no Phase
-  // 2, and the caller is expected to skip this gate for those modes rather than
-  // let it report clean.
+  // as "0/0 accounted for" and let the commit through. A mode with no Phase 2
+  // (analysis) is expected to skip this gate explicitly rather than let it
+  // report clean.
   if (!Array.isArray(todos) || todos.length === 0) {
     const msg = Array.isArray(todos)
       ? "the plan has zero steps - that is an unusable plan, not a clean one; skip this gate explicitly for modes with no Phase 2"

package/pipeline/scripts/run-aggregator.mjs

@@ -87,8 +87,8 @@ function die(msg) {
 // Path resolution lives in _run-paths.mjs: tracker-state.json is written to
 // the flat <root>/<task-id>/ while agent-state.json documents the nested
 // <root>/<project>/<task-id>/, and both layouts are populated in practice.
-// This used to be a hand-rolled candidate list here, a second one in
-// render-cost-summary.sh and a third in render-agent-log-cost.sh.
+// Resolved once here rather than as a hand-rolled candidate list in each of
+// render-cost-summary.sh and render-agent-log-cost.sh as well.
 function resolveTrackerCandidates() {
   const candidates = [];
   if (flags["task-dir"]) {
@@ -159,7 +159,7 @@ function computeCost(modelKey, tokensIn, tokensOut, costTable) {
 
 /**
  * Heuristic: Plan (1) uses Opus per personas + dev-mode docs; Dev (2) uses
- * Sonnet by default unless the run is a Short pipeline (Opus); Review (3)
+ * Sonnet by default unless routing names another rung; Review (3)
  * triage is Opus and the reviewer breakdown comes from spans.
  *
  * This is a fallback when phase-tracker doesn't record the model used. Live

package/pipeline/scripts/runs-index.mjs

@@ -44,9 +44,9 @@ import { invokedDirectly } from "../lib/invoked-directly.mjs";
 
 /**
  * The phase from which a run counts as "waiting on you", read from the phase
- * contract rather than written here. This threshold moved once already (it was
- * 6 under the eight-phase contract, it is 4 under six) and nothing connected it
- * to the renumbering, so it would have silently regrouped every run.
+ * contract rather than written here. The threshold follows the phase count (6
+ * under an eight-phase contract, 4 under six), so a literal would survive a
+ * renumbering unchanged and silently regroup every run.
  */
 const PHASE_WAITING_FROM = JSON.parse(
   readFileSync(new URL("../schemas/phases.json", import.meta.url), "utf8"),
@@ -203,10 +203,10 @@ export function buildIndex() {
       salvaged: Boolean(statePath && statePath.includes(`${run.dir}/artifacts/`)),
       // What KIND of record this is, before asking whether it is healthy.
       //
-      // 74 of the 103 runs on this machine have a tracker file and no agent
-      // state, and the first version of this index called every one of them
-      // `stateReadable: false` - so a panel built on it announced "74 runs
-      // could not be read" about records that are not damaged and never had
+      // A run with a tracker file and no agent state is the common case, not
+      // damage: most runs on a machine are shaped that way. Calling them
+      // `stateReadable: false` makes a panel announce "N runs could not be
+      // read" about records that are intact and never had
       // agent state to begin with. `/multi-agent:analysis` says so in its own
       // description ("no worktree, no commits, no dev chain"), and design-check
       // is the same shape.

package/pipeline/scripts/scope-check-gate.mjs

@@ -4,7 +4,7 @@
  *
  * Phase 3 writes `.pipeline/scope-check.json` before the handoff: one reason
  * per touched file, the things it deliberately did not do, and the simplifier
- * rationales that used to be discarded. This gate compares that record with
+ * rationales that are otherwise discarded. This gate compares that record with
  * the real diff so an unjustified file cannot ride into review unnoticed.
  *
  * Usage: