@mmerterden/multi-agent-pipeline 18.0.0 → 19.0.0

package/pipeline/schemas/scope-check.schema.json

@@ -3,7 +3,7 @@
   "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/scope-check.schema.json",
   "version": "1.0.0",
   "title": "Multi-Agent Pipeline  -  Phase 3 scope self-check",
-  "description": "Written by Phase 3 Step 3.7 to $WORKTREE/.pipeline/scope-check.json before the Phase 4 handoff: one stated reason per file in the diff, the changes deliberately not made, and the code-simplifier rationales. scope-check-gate.mjs compares files[] with the real diff; Phase 4 injects the record as <scope-self-check>; Phase 6 builds the PR Changes bullets and the follow-up list from it.",
+  "description": "Written by Phase 2 Step 3.7 to $WORKTREE/.pipeline/scope-check.json before the Phase 4 handoff: one stated reason per file in the diff, the changes deliberately not made, and the code-simplifier rationales. scope-check-gate.mjs compares files[] with the real diff; Phase 4 injects the record as <scope-self-check>; Phase 4 builds the PR Changes bullets and the follow-up list from it.",
   "type": "object",
   "additionalProperties": false,
   "required": ["version", "taskId", "files"],

package/pipeline/schemas/test-gap.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/test-gap.schema.json",
   "version": "1.0.0",
-  "title": "Multi-Agent Pipeline  -  Phase 5 test gap report",
+  "title": "Multi-Agent Pipeline  -  Phase 3 test gap report",
   "description": "Output of test-gap-scan.mjs. Lists symbols added/changed in the diff that have no paired test file or no matching test method. Advisory in default mode; opt-in blocking via prefs.testGap.blockingThreshold.",
   "type": "object",
   "additionalProperties": false,

package/pipeline/schemas/token-budget.json

@@ -1,32 +1,26 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/token-budget.json",
-  "description": "Per-phase token ceilings for the lazy-loaded pipeline docs, enforced by smoke-token-budget.sh. Only the ACTIVE phase is loaded at run time and nothing truncates a phase document, so these numbers govern what may be written, not what a run receives. Two rules, and the split is the point. `max_tokens` and `total_max_tokens` are committed constants a human owns: computing them would end the gate, because a ceiling that is always current x k can never fail. The warn tier is NOT stored - the gate derives it per phase from that phase's own git history (median + 3*MAD of its historical per-commit deltas, which is robust to the one 980-token release that makes sigma meaningless on phase-4), because a soft line maintained by hand rots, and this one rotted twice: it was reset at v13.6.0 when five lines had gone permanently amber, and six of eight were amber again by v17.1.0. A ceiling more than 25% above the measurement is stale and fails, which is the 'only ratchets down' rule the SKILL.md grace list always had and this budget never did. Change history: docs/token-budget-history.md.",
+  "description": "Per-phase token ceilings for the lazy-loaded pipeline docs, enforced by smoke-token-budget.sh. Only the ACTIVE phase is loaded at run time and nothing truncates a phase document, so these numbers govern what may be written, not what a run receives. Two rules, and the split is the point. `max_tokens` and `total_max_tokens` are committed constants a human owns: computing them would end the gate, because a ceiling that is always current x k can never fail. The warn tier is NOT stored - the gate derives it per phase from that phase's own git history (median + 3*MAD of its historical per-commit deltas, which is robust to the one 980-token release that makes sigma meaningless on phase-4), because a soft line maintained by hand rots, and this one rotted twice: it was reset at v13.6.0 when five lines had gone permanently amber, and six of eight were amber again by v17.1.0. A ceiling more than 25% above the measurement is stale and fails, which is the 'only ratchets down' rule the SKILL.md grace list always had and this budget never did. Ceilings are DERIVED from schemas/phases.json and re-measured after the v19.0.0 six-phase merge, not summed from the eight old ones: the two-sided rule fails a ceiling more than 25% above the measurement, so a sum would have shipped stale by construction. Change history: docs/token-budget-history.md.",
   "phases": {
     "phase-0-init": {
       "max_tokens": 13400
     },
-    "phase-1-analysis": {
-      "max_tokens": 4600
+    "phase-1-plan": {
+      "max_tokens": 10000
     },
-    "phase-2-planning": {
-      "max_tokens": 6500
-    },
-    "phase-3-dev": {
-      "max_tokens": 9450
+    "phase-2-dev": {
+      "max_tokens": 10650
     },
-    "phase-4-review": {
-      "max_tokens": 15150
+    "phase-3-review": {
+      "max_tokens": 17200
     },
-    "phase-5-test": {
-      "max_tokens": 3050
-    },
-    "phase-6-commit": {
-      "max_tokens": 6550
+    "phase-4-commit": {
+      "max_tokens": 6500
     },
-    "phase-7-report": {
-      "max_tokens": 6350
+    "phase-5-report": {
+      "max_tokens": 5550
     }
   },
-  "total_max_tokens": 63150
+  "total_max_tokens": 63300
 }

package/pipeline/schemas/triage-output.schema.json

@@ -2,8 +2,8 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/triage-output.schema.json",
   "version": "3.4.0",
-  "title": "Multi-Agent Pipeline  -  Phase 4 triage output",
-  "description": "Contract for the Opus triage agent's JSON output in Phase 4 Step 3. Triage consumes merged reviewer findings and splits them into accepted/deferred/rejected. Only `accepted` blocking/important items trigger Phase 3 rework. v3.1.0 adds the optional `consensus` block so triage can surface reviewer-agreement risk (false consensus among same-base-model reviewers) instead of silently merging. v3.2.0 adds the optional per-finding `verification` block written by Phase 4 Step 3.7 (verify-by-test): the empirical repro-test outcome for accepted blocking findings. v3.3.0 carries ruleId + criteriaSource through triage so a finding that cites a stable rule ID keeps that citation into Phase 6 and Phase 7, and the lesson loop can key durable learnings by rule. v3.4.0 adds the optional per-finding fingerprint (finding-fingerprint.mjs) so review-delta.mjs can tell still-present, resolved and new findings apart between rounds.",
+  "title": "Multi-Agent Pipeline  -  Phase 3 triage output",
+  "description": "Contract for the Opus triage agent's JSON output in Phase 4 Step 3. Triage consumes merged reviewer findings and splits them into accepted/deferred/rejected. Only `accepted` blocking/important items trigger Phase 3 rework. v3.1.0 adds the optional `consensus` block so triage can surface reviewer-agreement risk (false consensus among same-base-model reviewers) instead of silently merging. v3.2.0 adds the optional per-finding `verification` block written by Phase 3 Step 3.7 (verify-by-test): the empirical repro-test outcome for accepted blocking findings. v3.3.0 carries ruleId + criteriaSource through triage so a finding that cites a stable rule ID keeps that citation into Phase 4 and Phase 5, and the lesson loop can key durable learnings by rule. v3.4.0 adds the optional per-finding fingerprint (finding-fingerprint.mjs) so review-delta.mjs can tell still-present, resolved and new findings apart between rounds.",
   "type": "object",
   "additionalProperties": false,
   "required": ["accepted", "deferred", "rejected", "approved"],
@@ -17,7 +17,7 @@
     },
     "deferred": {
       "type": "array",
-      "description": "Findings that are real but out of current task scope. Surfaced in Phase 7 report; not actioned.",
+      "description": "Findings that are real but out of current task scope. Surfaced in Phase 5 report; not actioned.",
       "items": {
         "type": "object",
         "additionalProperties": false,
@@ -55,7 +55,7 @@
     },
     "approved": {
       "type": "boolean",
-      "description": "True if no accepted BLOCKING items remain. The pipeline uses this to gate Phase 5 / Phase 6 entry."
+      "description": "True if no accepted BLOCKING items remain. The pipeline uses this to gate Phase 5 / Phase 4 entry."
     },
     "consensus": {
       "$ref": "#/$defs/consensus"
@@ -111,7 +111,7 @@
         },
         "disagreements": {
           "type": "array",
-          "description": "Findings where reviewers split (existence or severity). Surfaced verbatim in the Phase 7 report and at the Step 4 user checkpoint.",
+          "description": "Findings where reviewers split (existence or severity). Surfaced verbatim in the Phase 5 report and at the Step 4 user checkpoint.",
           "items": {
             "type": "object",
             "additionalProperties": false,
@@ -142,7 +142,7 @@
     "verification": {
       "type": "object",
       "additionalProperties": false,
-      "description": "v3.2.0 verify-by-test outcome (Phase 4 Step 3.7, opt-in via prefs.global.verifyByTest). confirmed = repro test failed as the finding predicts (finding stands, test kept as the Phase 3 RED test); not-reproduced = repro test passed under evidence-gate (finding downgraded to deferred); inconclusive = compile error / timeout / not unit-testable (judgment verdict stands).",
+      "description": "v3.2.0 verify-by-test outcome (Phase 3 Step 3.7, opt-in via prefs.global.verifyByTest). confirmed = repro test failed as the finding predicts (finding stands, test kept as the Phase 3 RED test); not-reproduced = repro test passed under evidence-gate (finding downgraded to deferred); inconclusive = compile error / timeout / not unit-testable (judgment verdict stands).",
       "required": ["result"],
       "properties": {
         "result": {

package/pipeline/scripts/README.md

@@ -19,10 +19,10 @@ Validate contracts. Each emits `══ <name> smoke: N passed, M failed ══`
 
 ### Phase contracts
 - `smoke-phase-0-multi-repo.sh`  -  Phase 0 multi-repo mode fetch + worktree atomicity
-- `smoke-phase-6-multi.sh`  -  Phase 6 multi-repo commit/PR cross-linking
+- `smoke-phase-6-multi.sh`  -  Phase 4 multi-repo commit/PR cross-linking
 - `smoke-phase-banner.sh` + `smoke-phase-tracker.sh`  -  Phase UI output contracts
-- `smoke-phase4-triage.sh`  -  Phase 4 reviewer → triage flow
-- `smoke-verify-by-test.sh`  -  Phase 4 Step 3.7 verify-by-test contract (v10.8.0)
+- `smoke-phase4-triage.sh`  -  Phase 3 reviewer → triage flow
+- `smoke-verify-by-test.sh`  -  Phase 3 Step 3.7 verify-by-test contract (v10.8.0)
 - `smoke-handoff-contract.sh`  -  phase-boundary structured handoff + handoff-first resume (v10.8.0)
 - `smoke-update-check.sh`  -  Phase 0 Step 0.6 update-check + required-floor contract (v10.9.0, floor v15.14.0)
 - `smoke-context-links.sh`  -  context-link-extractor classification contract, all types (v15.14.0)

package/pipeline/scripts/_code-graph.mjs

@@ -1,7 +1,7 @@
 /**
- * @file _code-graph.mjs  -  deterministic, LLM-free code graph for Phase 1 and Phase 7.
+ * @file _code-graph.mjs  -  deterministic, LLM-free code graph for Phase 1 and Phase 5.
  *
- * Phase 1 narrows its Explore fan-out with this graph, and Phase 7 refreshes it
+ * Phase 1 narrows its Explore fan-out with this graph, and Phase 5 refreshes it
  * instead of hand-writing architecture.md from a single task's window. The
  * design follows graphify (Graphify-Labs/graphify): AST-quality extraction with
  * zero LLM cost, one graph file, an incremental manifest gate, god-node hubs,

package/pipeline/scripts/_run-paths.mjs

@@ -76,7 +76,7 @@ export function canonicalRunDir(taskId, project) {
 }
 
 /**
- * Phase 6 removes the worktree and salvages the run's files into an
+ * Phase 4 removes the worktree and salvages the run's files into an
  * `artifacts/` subdirectory of the same run directory. A finished run therefore
  * keeps its state one level deeper, and a reader that only looks at the top
  * level reports a shipped task as having no state at all.
@@ -232,7 +232,7 @@ export function resolveRunFile(taskId, filename, project) {
   for (const v of taskIdVariants(taskId)) {
     const dir = resolveRunDir(v, project);
     if (!dir) continue;
-    // Top level first, then the salvaged copy Phase 6 leaves behind.
+    // Top level first, then the salvaged copy Phase 4 leaves behind.
     for (const base of [dir, join(dir, ARTIFACTS_SUBDIR)]) {
       const p = join(base, filename);
       if (existsSync(p)) return p;

package/pipeline/scripts/_smoke-root.sh

@@ -20,7 +20,7 @@
 #
 # Usage (from any script in pipeline/scripts/):
 #   . "$(dirname "${BASH_SOURCE[0]}")/_smoke-root.sh"
-#   grep -q needle "$MA_REFS/phases/phase-4-review.md"
+#   grep -q needle "$MA_REFS/phases/phase-3-review.md"
 #
 # Exports:
 #   MA_LAYOUT     "repo" | "install"

package/pipeline/scripts/aggregate-metrics.mjs

@@ -6,7 +6,7 @@
 // by --since=<ISO date> / --task-id=<id> / --phase=<N>.
 //
 // Output is plain-text by default; pass --json for machine-readable output
-// (used by Phase 7 to embed a metrics block in the run report).
+// (used by Phase 5 to embed a metrics block in the run report).
 //
 // Aggregations:
 //   - Tasks completed

package/pipeline/scripts/capture-flush.sh

@@ -5,14 +5,14 @@
 #
 # WHY THIS EXISTS
 #
-# Every persistent write used to live in Phase 7: triage ingest, the learnings
-# ledger distill, the knowledge-base append, the code-graph refresh. And Phase 7
+# Every persistent write used to live in Phase 5: triage ingest, the learnings
+# ledger distill, the knowledge-base append, the code-graph refresh. And Phase 5
 # is, by the pipeline's own admission in features/code-graph.md, the phase a run
 # is LEAST likely to reach. A run killed in Phase 3, a session that hits its
 # context ceiling, a crash after review - each one threw away everything it had
 # established, and the next run on the same repo rediscovered it from scratch.
 #
-# So the writes move here, and Phase 7 becomes the LAST flush rather than the
+# So the writes move here, and Phase 5 becomes the LAST flush rather than the
 # only one. Phase boundaries call this, and so does SessionEnd. Nothing about
 # the trigger depends on a model noticing that a moment qualifies: it hangs on
 # a phase transition and on process exit, both objectively visible without any
@@ -20,15 +20,15 @@
 #
 # What it does NOT do: call a model. Everything here is derived from artefacts
 # already on disk (triage-output.json) plus agent-state.json. The parts of
-# Phase 7 that genuinely need a model - the knowledge-base extraction, the
-# per-repo memory synthesis - stay in Phase 7, because a hook cannot think.
+# Phase 5 that genuinely need a model - the knowledge-base extraction, the
+# per-repo memory synthesis - stay in Phase 5, because a hook cannot think.
 #
 # Usage:
 #   ./capture-flush.sh [--state <agent-state.json>] [--if-stale] [--json] [--quiet]
 #
 #   --state     the run to flush. Default: resolved from the newest task dir
 #               under $HOME/.claude/logs/multi-agent (see resolve_state).
-#   --if-stale  flush only when the run did NOT complete Phase 7 - the
+#   --if-stale  flush only when the run did NOT complete Phase 5 - the
 #               SessionEnd case. A finished run has already flushed.
 #   --json      machine-readable result for a caller that wants to count rows.
 #   --quiet     no stdout. Exit status still distinguishes the outcomes.
@@ -101,13 +101,13 @@ WORKTREE=$(jq -r '.worktreePath // empty' "$STATE" 2>/dev/null)
 PHASE7=$(jq -r '[.phases[]? | select((.id // "") == "7") | .status] | first // ""' "$STATE" 2>/dev/null)
 
 if [ "$IF_STALE" -eq 1 ] && [ "$PHASE7" = "completed" ]; then
-  say "capture-flush: ${TASK_ID:-run} already completed Phase 7 - nothing stale"
+  say "capture-flush: ${TASK_ID:-run} already completed Phase 5 - nothing stale"
   [ "$JSON" -eq 1 ] && printf '{"status":"noop","reason":"already-flushed","taskId":"%s"}\n' "$TASK_ID"
   exit 0
 fi
 
 # The triage artefact is the only input either store needs, and it has two homes:
-# Phase 6 removes the worktree once the PR is open, so the salvaged copy under
+# Phase 4 removes the worktree once the PR is open, so the salvaged copy under
 # artifactsPath is tried FIRST. Reading the worktree path first would degrade
 # silently for exactly the runs this script exists to rescue.
 TRIAGE=""

package/pipeline/scripts/capture-resume.sh

@@ -11,7 +11,7 @@
 #      the user learns to skip, which costs more than it saves.
 #
 # It answers two questions:
-#   - Is there a pipeline run that stopped before Phase 7? Name it and the resume
+#   - Is there a pipeline run that stopped before Phase 5? Name it and the resume
 #     command, because that run's work is recoverable and its findings are not
 #     yet in the durable stores until it flushes.
 #   - Is the pipeline's own observation queue stale? (>= REVIEW_DAYS since the
@@ -32,7 +32,7 @@ REVIEW_DAYS=7
 # Three buckets, not one line. Measured on the development machine: 22 runs read
 # `in_progress` and every one was over a day old, but they are not one failure.
 # 13 stopped at Phase 0, which is almost entirely questions - those runs never
-# started. 3 had their PR already open and were waiting at Phase 6/7, where the
+# started. 3 had their PR already open and were waiting at Phase 4/7, where the
 # pipeline pauses ON PURPOSE for channel selection. 4 died mid-development.
 #
 # Reporting the newest one of those as "stopped at Phase N" told the truth about
@@ -71,7 +71,7 @@ if [ -d "$LOGS" ] && command -v jq >/dev/null 2>&1; then
     PR=$(jq -r 'if (.pr|type)=="string" then .pr elif (.pr|type)=="object" then (.pr.url // .pr.number // "") else "" end | tostring' "$f" 2>/dev/null)
 
     # Waiting for you, not broken: an open PR means the work landed, and
-    # Phase 7 pauses for channel selection by design (modes.md).
+    # Phase 5 pauses for channel selection by design (modes.md).
     if [ "$STATUS" = "awaiting_input" ] || [ -n "$PR" ] ||
       [ "$PHASE" = "6" ] || [ "$PHASE" = "7" ]; then
       AWAITING_N=$((AWAITING_N + 1))

package/pipeline/scripts/classify-plan-safety.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // classify-plan-safety.mjs  -  v7.0.G
 //
-// Heuristic safety classifier for a Phase 2 plan. Autopilot's "zero user
+// Heuristic safety classifier for a Phase 1 plan. Autopilot's "zero user
 // interaction" contract is fine for small, predictable tasks but dangerous
 // when a plan touches the security path, deletes files without paired
 // tests, or sprawls across many files. This script inspects the plan and

package/pipeline/scripts/diff-explain.mjs

@@ -3,7 +3,7 @@
 /**
  * @file diff-explain.mjs  -  v7.8.0 Paket B
  *
- * Bridges Phase 4 triage output to the actual git diff. For each accepted /
+ * Bridges Phase 3 triage output to the actual git diff. For each accepted /
  * deferred / rejected finding, locates the corresponding hunk in the branch's
  * diff against base and renders an annotated markdown report.
  *

package/pipeline/scripts/doctor.mjs

@@ -744,7 +744,7 @@ function checkDiskSpace() {
 }
 
 // A finished task removes its own worktree at PR time, but a run that dies
-// before Phase 6 never reaches that step and nothing else collects it: the
+// before Phase 4 never reaches that step and nothing else collects it: the
 // finalizer only runs on success and gc-worktrees only sweeps entries git no
 // longer knows about. So worktrees accumulate silently, and each one is a full
 // second checkout. Measured on one real iOS repo: 15 left behind, 11 GB.
@@ -788,7 +788,7 @@ function checkWorktreeResidue() {
     report(
       "worktree-residue",
       "WARN",
-      `${entries.length} worktree(s) left under ${wt}${size}; runs that stopped before Phase 6 are never collected`,
+      `${entries.length} worktree(s) left under ${wt}${size}; runs that stopped before Phase 4 are never collected`,
       "run /multi-agent:garbage-collect, or /multi-agent:kill for a task you know is dead",
     );
     return;

package/pipeline/scripts/gc-abandoned.sh

@@ -11,7 +11,7 @@
 # Three things keep this from being a foot-gun, and each is a rule rather than a
 # heuristic:
 #
-#   1. A run WAITING FOR YOU is never reaped. An open PR, Phase 6 or 7, or
+#   1. A run WAITING FOR YOU is never reaped. An open PR, Phase 4 or 7, or
 #      `status: awaiting_input` means the work landed and the pipeline is
 #      holding for an answer by design. That is finished work, not residue.
 #   2. A path that is not strictly inside `<repo>/.worktrees/` is never removed.
@@ -49,7 +49,7 @@
 #
 # State is moved to `<run-dir>/artifacts/` before the worktree goes, so the log,
 # the findings and the phase history survive the sweep. The same recovery
-# contract Phase 6 uses when it removes a finished worktree.
+# contract Phase 4 uses when it removes a finished worktree.
 #
 # SAFE BY DEFAULT: dry-run. Removes nothing until you pass --yes.
 #
@@ -271,7 +271,7 @@ if [ "$STATE_ONLY" -eq 0 ] && [ -d "$REPOS" ]; then
       ph=$(printf '%s' "$row" | cut -f5)
 
       # Rule 1 again: landed work is not residue, whichever pass finds it. Order
-      # matters here - the phase-6/7 test is a proxy for "still waiting", and a
+      # matters here - the phase-4/5 test is a proxy for "still waiting", and a
       # run whose status already says it FINISHED is not waiting for anyone. A
       # complete run sitting at phase 7 was read as waiting and never reaped,
       # which is how three finished worktrees held 5.1 GB indefinitely.

package/pipeline/scripts/gc-tmp.sh

@@ -107,7 +107,7 @@ NAME_ARGS=(
 # `complaint-analysis-*` needs its own entry: find matches the basename against
 # the whole glob, so `analysis-*` never matched it. Same for the other three,
 # which were writing into $ROOT with nothing sweeping them (phase-0-init.md,
-# phase-6-commit.md, generate-issue.md).
+# phase-4-commit.md, generate-issue.md).
 #
 # `*-wiki` is the one loose pattern here, and a suffix glob over $ROOT could
 # name something a person created. It is narrowed twice: `-type d` above, and

package/pipeline/scripts/gc-worktrees.sh

@@ -21,7 +21,7 @@
 #      `.pipeline/` left behind by a finished run stops reading as residue.
 #
 # Registered, healthy worktrees are NEVER touched. Finishing a task removes its
-# own worktree in Phase 6 (worktree-finalize, v14.1.0+); killing one is
+# own worktree in Phase 4 (worktree-finalize, v14.1.0+); killing one is
 # /multi-agent:kill. This sweep only reaps orphans neither of those left behind.
 #
 # SAFE BY DEFAULT: dry-run. Deletes nothing until you pass --yes.

package/pipeline/scripts/gen-facts.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+/**
+ * @file gen-facts.mjs  -  the numbers the website is allowed to state, derived.
+ *
+ * The site carried its own copies: `ArchitectureContent.tsx` said "6 faz + 51
+ * komut" while the repo had six phases and sixty commands. Nobody noticed,
+ * because a number written into a React component is guarded by nothing. This
+ * is the same defect `smoke-phase-contract.sh` fixes inside the pipeline, and
+ * the fix is the same shape: one producer, everything else reads it.
+ *
+ * Source of truth per field:
+ *   phases        pipeline/schemas/phases.json  -  the phase contract itself
+ *   commandCount  a count of pipeline/commands/multi-agent/<name>/SKILL.md
+ *   skillCount    a count of pipeline/skills/shared/external/<name>/SKILL.md
+ *   toolCount     the toolkit's own tools/list response, when reachable
+ *   version       package.json
+ *
+ * Counts come from the filesystem at the moment of writing, never from a README
+ * or a previous version of this file.
+ *
+ * Usage:
+ *   node gen-facts.mjs                 write docs/facts.json
+ *   node gen-facts.mjs --check         exit 1 if the file on disk is stale
+ *   node gen-facts.mjs --stdout        print, write nothing
+ *
+ * Exit codes:
+ *   0  -  written, or up to date
+ *   1  -  --check found drift
+ *   2  -  a source could not be read (nothing is written)
+ */
+
+import { readFileSync, writeFileSync, readdirSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(HERE, "..", "..");
+const OUT = join(ROOT, "docs", "facts.json");
+
+function die(msg) {
+  console.error(`gen-facts: ${msg}`);
+  process.exit(2);
+}
+
+function countSkillDirs(rel) {
+  const dir = join(ROOT, rel);
+  if (!existsSync(dir)) die(`missing directory: ${rel}`);
+  return readdirSync(dir, { withFileTypes: true }).filter(
+    (e) => e.isDirectory() && existsSync(join(dir, e.name, "SKILL.md")),
+  ).length;
+}
+
+let contract;
+try {
+  contract = JSON.parse(readFileSync(join(ROOT, "pipeline", "schemas", "phases.json"), "utf8"));
+} catch (err) {
+  die(`cannot read the phase contract  -  ${err.message}`);
+}
+
+let pkg;
+try {
+  pkg = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8"));
+} catch (err) {
+  die(`cannot read package.json  -  ${err.message}`);
+}
+
+// The toolkit is a separate repo and may not be checked out beside this one.
+// Absent is reported as null rather than as a guess: a site that prints a stale
+// tool count is the problem this file exists to remove, and a made-up one is
+// worse than none.
+let toolCount = null;
+let toolkitVersion = null;
+const toolkitDir = join(ROOT, "..", "multi-agent-toolkit-mcp");
+if (existsSync(join(toolkitDir, "package.json"))) {
+  try {
+    toolkitVersion =
+      JSON.parse(readFileSync(join(toolkitDir, "package.json"), "utf8")).version ?? null;
+  } catch {
+    toolkitVersion = null;
+  }
+  // Asked of the server, not counted out of its source. Three tool families
+  // are defined in modules the main file only spreads in, so a regex over
+  // index.js returns a number that looks plausible and is wrong - the first
+  // version of this script said 2 when the answer was 99. tools/list is what
+  // a client actually receives, which is the number the site should print.
+  try {
+    const req =
+      [
+        JSON.stringify({
+          jsonrpc: "2.0",
+          id: 1,
+          method: "initialize",
+          params: {
+            protocolVersion: "2024-11-05",
+            capabilities: {},
+            clientInfo: { name: "gen-facts", version: "1" },
+          },
+        }),
+        JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }),
+        JSON.stringify({ jsonrpc: "2.0", id: 2, method: "tools/list", params: {} }),
+      ].join("\n") + "\n";
+    const res = spawnSync(process.execPath, [join(toolkitDir, "index.js")], {
+      input: req,
+      encoding: "utf8",
+      timeout: 30000,
+    });
+    for (const line of (res.stdout || "").split("\n")) {
+      if (!line.trim()) continue;
+      let msg;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (msg.id === 2 && Array.isArray(msg.result?.tools)) toolCount = msg.result.tools.length;
+    }
+  } catch {
+    toolCount = null;
+  }
+}
+
+const facts = {
+  $comment:
+    "Generated by pipeline/scripts/gen-facts.mjs. Do not hand-edit: the site reads this, and a number edited here instead of at its source is the drift this file removes.",
+  generatedAt: new Date().toISOString().slice(0, 10),
+  version: pkg.version,
+  phaseSchema: contract.phaseSchema,
+  phases: contract.phases.map((p) => ({ id: p.id, name: p.name })),
+  phaseCount: contract.phases.length,
+  modes: Object.fromEntries(Object.entries(contract.modes).map(([k, v]) => [k, v.phases])),
+  commandCount: countSkillDirs("pipeline/commands/multi-agent"),
+  skillCount: countSkillDirs("pipeline/skills/shared/external"),
+  toolCount,
+  toolkitVersion,
+};
+
+const body = `${JSON.stringify(facts, null, 2)}\n`;
+
+if (process.argv.includes("--stdout")) {
+  process.stdout.write(body);
+  process.exit(0);
+}
+
+if (process.argv.includes("--check")) {
+  if (!existsSync(OUT)) {
+    console.error("gen-facts: docs/facts.json does not exist  -  run without --check");
+    process.exit(1);
+  }
+  const onDisk = JSON.parse(readFileSync(OUT, "utf8"));
+  const fresh = JSON.parse(body);
+  // generatedAt is a timestamp, not a fact: comparing it would fail every day.
+  delete onDisk.generatedAt;
+  delete fresh.generatedAt;
+  if (JSON.stringify(onDisk) !== JSON.stringify(fresh)) {
+    console.error(
+      "gen-facts: docs/facts.json is stale  -  run: node pipeline/scripts/gen-facts.mjs",
+    );
+    for (const k of Object.keys(fresh)) {
+      if (JSON.stringify(onDisk[k]) !== JSON.stringify(fresh[k])) {
+        console.error(
+          `  ${k}: on disk ${JSON.stringify(onDisk[k])}, derived ${JSON.stringify(fresh[k])}`,
+        );
+      }
+    }
+    process.exit(1);
+  }
+  console.log("gen-facts: docs/facts.json is current");
+  process.exit(0);
+}
+
+writeFileSync(OUT, body);
+console.log(
+  `gen-facts: wrote docs/facts.json (${facts.phaseCount} phases, ${facts.commandCount} commands, ${facts.skillCount} skills, ${facts.toolCount ?? "?"} tools)`,
+);

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

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { readFileSync } from "node:fs";
 /**
  * gen-mode-dispatch.mjs  -  emit the canonical Phase Tracker Contract block
  * for a given mode dispatch file (full / local / autopilot / analysis).
@@ -10,10 +11,10 @@
  * call, anti-pattern warning, and ref link are identical.
  *
  * Usage:
- *   node pipeline/scripts/gen-mode-dispatch.mjs --mode=full         # 0..7
- *   node pipeline/scripts/gen-mode-dispatch.mjs --mode=local        # 0/1/2/3/4/6/7 + local-mode caveat
- *   node pipeline/scripts/gen-mode-dispatch.mjs --mode=autopilot    # 0/1/2/3/4/6/7
- *   node pipeline/scripts/gen-mode-dispatch.mjs --mode=analysis     # 0/1/2/4/6/7 (no Dev, no Test)
+ *   node pipeline/scripts/gen-mode-dispatch.mjs --mode=full         # 0..5
+ *   node pipeline/scripts/gen-mode-dispatch.mjs --mode=local        # 0..5 + local-mode caveat
+ *   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
@@ -35,22 +36,20 @@ const args = Object.fromEntries(
 
 const MODE = args.mode;
 
-const PHASE_NAMES = [
-  "0:Init",
-  "1:Analysis",
-  "2:Planning",
-  "3:Dev",
-  "4:Review",
-  "5:Test",
-  "6:Commit",
-  "7:Report",
-];
-
-// Phase 5 (User Test) checks out the change from the git worktree and hands it
-// to the user interactively. It therefore only runs when the mode is BOTH
-// interactive (not autopilot) AND worktree-backed (not local), which since
-// v16.0.0 leaves exactly one command: `/multi-agent` itself.
-const PHASE_NAMES_NO_TEST = PHASE_NAMES.filter((p) => p !== "5:Test");
+// The phase list has one owner: schemas/phases.json. This file used to restate
+// it, which is how eight independent copies came to exist. smoke-phase-contract.sh
+// holds every remaining copy to the same file.
+const CONTRACT = JSON.parse(
+  readFileSync(new URL("../schemas/phases.json", import.meta.url), "utf8"),
+);
+const PHASES = CONTRACT.phases;
+const modePhases = (name) =>
+  CONTRACT.modes[name].phases.map((id) => {
+    const p = PHASES.find((x) => x.id === id);
+    return `${p.id}:${p.name}`;
+  });
+
+const PHASE_NAMES = PHASES.map((p) => `${p.id}:${p.name}`);
 
 /**
  * Mode → phases + flag descriptor. The descriptor controls the autopilot /
@@ -59,21 +58,17 @@ const PHASE_NAMES_NO_TEST = PHASE_NAMES.filter((p) => p !== "5:Test");
  * `smoke-mode-dispatch-drift.sh` can byte-equal-diff each on-disk section
  * against its generator output.
  */
-const MODES = {
-  autopilot: { phases: PHASE_NAMES_NO_TEST, local: false, autopilot: true },
-  full: { phases: PHASE_NAMES, local: false, autopilot: false, depth: true },
-  local: { phases: PHASE_NAMES_NO_TEST, local: true, autopilot: false, depth: true },
-  "local-autopilot": { phases: PHASE_NAMES_NO_TEST, local: true, autopilot: true },
-  "full-local": { phases: PHASE_NAMES_NO_TEST, local: true, autopilot: false, depth: true },
-  // Analysis produces a document, not code: no Dev, no Test, and Phase 6
-  // publishes instead of committing. Same 8-phase contract, four of them
-  // reinterpreted.
-  analysis: {
-    phases: ["0:Init", "1:Analysis", "2:Planning", "4:Review", "6:Commit", "7:Report"],
-    local: false,
-    autopilot: false,
-  },
-};
+const MODES = Object.fromEntries(
+  Object.entries(CONTRACT.modes).map(([name, m]) => [
+    name,
+    {
+      phases: modePhases(name),
+      local: m.local,
+      autopilot: m.autopilot,
+      ...(m.depth ? { depth: true } : {}),
+    },
+  ]),
+);
 
 const spec = MODE ? MODES[MODE] : null;
 if (!spec) {
@@ -101,7 +96,7 @@ const modeLabel = MODE_LABELS[MODE] ?? `\`${MODE}\``;
 const skipNote =
   skippedIds.length > 0
     ? `${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 8 phases (no phase is skipped).`;
+    : `${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)".`;
 
@@ -119,7 +114,7 @@ const banner = spec.autopilot
 // 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]) >= 3);
+const shortSet = fullSet.filter((p) => Number(p.split(":")[0]) >= 2);
 const loopFor = (list) =>
   `for p in ${list.map((x) => `"${x}"`).join(" ")}; do\n  bash $HOME/.claude/scripts/phase-tracker.sh add "\${p%%:*}" "\${p#*:}"\ndone`;