@mmerterden/multi-agent-pipeline 18.0.0 → 19.1.0

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,280 @@
+#!/usr/bin/env node
+/**
+ * @file gen-facts.mjs  -  the numbers the website is allowed to state, derived.
+ *
+ * A consumer that keeps its own copy of these numbers has nothing guarding it:
+ * a count typed into a page or a README is right on the day it is typed and
+ * silent afterwards. `smoke-phase-contract.sh` enforces the same shape inside
+ * the pipeline - 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
+ *   skillCountAll every SKILL.md under pipeline/skills, at any depth
+ *   agentCount    a count of pipeline/agents/*.md
+ *   hosts         the CLIs install/ has an adapter for
+ *   toolCount     the toolkit's own tools/list response, when reachable
+ *   toolCategories that same response, grouped by the prefix in each tool name
+ *   pluginSkillCount every SKILL.md in the plugin marketplace, when checked out
+ *   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);
+}
+
+// Every SKILL.md under a tree, at any depth. `countSkillDirs` only sees the
+// immediate children of one directory, which is the right shape for the
+// external set and the wrong one for the whole tree: the shared/core and
+// per-host mirrors sit a level deeper and were invisible to it.
+function countSkillsDeep(rel) {
+  const dir = join(ROOT, rel);
+  if (!existsSync(dir)) die(`missing directory: ${rel}`);
+  let n = 0;
+  const walk = (d) => {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      if (e.isDirectory()) walk(join(d, e.name));
+      else if (e.name === "SKILL.md") n += 1;
+    }
+  };
+  walk(dir);
+  return n;
+}
+
+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 toolCategories = 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;
+        // Grouped by the prefix every tool name carries, from the same
+        // response the count comes from. Counting families out of the source
+        // gives a different and wrong answer for the reason above, and the
+        // site shows the per-family breakdown next to the total, so the two
+        // have to come from one place or they will disagree.
+        const byFamily = {};
+        for (const t of msg.result.tools) {
+          const family = String(t.name || "").split("_")[0];
+          if (family) byFamily[family] = (byFamily[family] || 0) + 1;
+        }
+        toolCategories = Object.fromEntries(
+          Object.entries(byFamily).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])),
+        );
+      }
+    }
+  } catch {
+    toolCount = null;
+    toolCategories = null;
+  }
+}
+
+// The plugin marketplace is a third repo, probed the same way and reported as
+// null when it is not checked out beside this one. The site states this number
+// next to the pipeline's own skill counts, and three different skill
+// populations on one page is exactly the shape that drifts.
+let pluginSkillCount = null;
+const pluginsDir = join(ROOT, "..", "multi-agent-plugins", "plugins");
+if (existsSync(pluginsDir)) {
+  let n = 0;
+  const walk = (d) => {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      if (e.isDirectory()) walk(join(d, e.name));
+      else if (e.name === "SKILL.md") n += 1;
+    }
+  };
+  try {
+    walk(pluginsDir);
+    pluginSkillCount = n;
+  } catch {
+    pluginSkillCount = 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"),
+  // Two populations, and conflating them is how the site came to show a stale
+  // "212 Skills" chip next to a correct "216 skills" sentence. `skillCount` is
+  // the external set a user installs; `skillCountAll` is every SKILL.md the
+  // repo ships, mirrors included. Both are stated on the site, so both are
+  // generated here rather than counted by hand at the other end.
+  skillCount: countSkillDirs("pipeline/skills/shared/external"),
+  skillCountAll: countSkillsDeep("pipeline/skills"),
+  // The site shows both of these as headline figures and had typed both by
+  // hand: a "9 Sub-agents" that happened to be right and a host list that had
+  // gone stale, naming Claude Code and Copilot CLI while install/codex.mjs had
+  // been shipping a third target for releases.
+  agentCount: readdirSync(join(ROOT, "pipeline", "agents")).filter((f) => f.endsWith(".md")).length,
+  hosts: readdirSync(join(ROOT, "install"))
+    .filter((f) => f.endsWith(".mjs") && !f.startsWith("_") && f !== "index.mjs")
+    .map(
+      (f) =>
+        ({ claude: "Claude Code", copilot: "Copilot CLI", codex: "Codex CLI" })[
+          f.replace(".mjs", "")
+        ],
+    )
+    .filter(Boolean)
+    .sort(),
+  toolCount,
+  toolCategories,
+  pluginSkillCount,
+  toolkitVersion,
+};
+
+// JSON.stringify and prettier disagree about short arrays: stringify puts each
+// phase id on its own line, prettier collapses a run that fits. That left this
+// file failing `format:check` after every regeneration, held together only by
+// someone remembering to run prettier by hand - and a generated file that needs
+// a manual step to pass the gate is a generated file that will fail the gate.
+//
+// Importing prettier here is not the fix: this script ships in the published
+// package, where a devDependency is not installed (`n/no-unpublished-import`
+// says so). Collapsing the number runs directly costs nothing and leaves the
+// script dependency-free.
+const collapseShortArrays = (json) =>
+  json.replace(
+    /\[\n\s+((?:-?\d+|"[^"\n]*")(?:,\n\s+(?:-?\d+|"[^"\n]*"))*)\n\s+\]/g,
+    (whole, inner) => {
+      const one = `[${inner.split(/,\n\s*/).join(", ")}]`;
+      // Prettier only collapses what fits the print width; leave the rest alone
+      // rather than guess, so the two can never disagree in the other direction.
+      return one.length <= 72 ? one : whole;
+    },
+  );
+
+const body = collapseShortArrays(`${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`;
 

package/pipeline/scripts/gen-ref-toc.mjs

@@ -13,7 +13,7 @@
 //
 // Section level is DERIVED, not assumed. These files are not consistent: some
 // open at `##` and section at `###` (keychain.md), others open at `###` and
-// section at `##` (phases/phase-3-dev.md). The rule is the shallowest heading
+// section at `##` (phases/phase-2-dev.md). The rule is the shallowest heading
 // depth that occurs more than once - a depth used exactly once is a title, not
 // a section level.
 //

package/pipeline/scripts/graph-report.mjs

@@ -3,7 +3,7 @@
 /**
  * @file graph-report.mjs  -  GRAPH_REPORT.md, the human-and-model readable summary.
  *
- * Phase 1 reads this before deciding how wide to explore, and Phase 7 ships it
+ * Phase 1 reads this before deciding how wide to explore, and Phase 5 ships it
  * next to the knowledge base. Sections are ordered by how much they narrow a
  * search: hubs first (the types everything touches), then the module map, then
  * the long tail that is usually safe to ignore.

package/pipeline/scripts/jira-attach.sh

@@ -5,7 +5,7 @@
 #
 # Two callers need this and they used to carry their own curl: the issue
 # generator (`generate-issue.md` step 12) and visual evidence (Phase 3 / Phase 5
-# captures rendered into the Phase 7 Jira comment). Two copies of an upload is
+# captures rendered into the Phase 5 Jira comment). Two copies of an upload is
 # two places for the `X-Atlassian-Token: no-check` header to go missing, which
 # fails as a 403 that reads like an auth problem.
 #

package/pipeline/scripts/learn-from-transcripts.mjs

@@ -4,7 +4,7 @@
  *
  * WHY THIS EXISTS
  *
- * Phase 7 asks a subagent to read the run log and propose a few memory entries.
+ * Phase 5 asks a subagent to read the run log and propose a few memory entries.
  * That works for what the model noticed, and it is structurally blind to what it
  * did not: the same wrong path tried in three sessions, the command that fails
  * every time until its `--flag` variant is used, the directory that never has

package/pipeline/scripts/learning-curve.mjs

@@ -87,9 +87,9 @@ for (const e of events) {
   }
   if (e.ts && (!t.firstTs || e.ts < t.firstTs)) t.firstTs = e.ts;
   const d = e.details || {};
-  // phase-4-review.md's actual review.completed emission (raw_count=/
+  // phase-3-review.md's actual review.completed emission (raw_count=/
   // accepted=/deferred=/rejected=/approved=/duration_ms=) carries no
-  // review_cycles field - that name only appears on Phase 7's task.completed
+  // review_cycles field - that name only appears on Phase 5's task.completed
   // summary event, which this never matched. Phase 4 re-runs (and logs its
   // own review.completed) once per rework cycle, so the cycle count for a
   // task is how many review.completed events share its task_id - the same

package/pipeline/scripts/log-metric.sh

@@ -6,11 +6,19 @@
 #   {
 #     "ts":      "<ISO 8601 timestamp>",
 #     "task_id": "<jira id, github issue, or run id>",
-#     "phase":   "<0..7>",
+#     "phase":   "<0..5>",
 #     "event":   "<event name>",
-#     "details": { ...arbitrary key/value pairs... }
+#     "details": { ...arbitrary key/value pairs... },
+#     "phaseSchema": 2
 #   }
 #
+# phaseSchema names the phase vocabulary the line was written under, because
+# this file is append-only and v19.0.0 renumbered the phases. A line with
+# phase 3 means Dev under schema 1 and Review under schema 2. Lines with no
+# phaseSchema field predate v19.0.0 and are schema 1. Aggregators pick their
+# name table from this field; without it the two vocabularies are
+# indistinguishable and every historical roll-up is quietly wrong.
+#
 # Usage:
 #   log-metric.sh <task_id> <phase> <event> [key=value ...]
 #
@@ -18,7 +26,7 @@
 #   log-metric.sh PROJ-1234 4 review.completed raw_count=8 accepted=3 deferred=2 rejected=3 approved=true duration_ms=42000
 #   log-metric.sh PROJ-1234 4 triage.edge_case case=high-rejection-rate
 #   log-metric.sh PROJ-1234 3 rework.started iteration=2 accepted_blocking=2
-#   log-metric.sh #316 7 task.completed phases=8 review_cycles=2 lang=tr
+#   log-metric.sh #316 5 task.completed phases=6 review_cycles=2 lang=tr
 #
 # Atomic append: each call uses `>> "$file"` which the kernel guarantees
 # atomic for writes ≤ PIPE_BUF (4 KB on macOS/Linux). One JSONL line is well
@@ -64,8 +72,13 @@ for kv in "$@"; do
 done
 DETAILS="${DETAILS}}"
 
+# Read from the phase contract rather than hardcoding: the next renumbering
+# bumps one JSON field instead of hunting for a literal in a shell script.
+PHASE_SCHEMA="$(node -e 'const c=require("'"$(cd "$(dirname "$0")" && pwd)"'/../schemas/phases.json"); process.stdout.write(String(c.phaseSchema))' 2>/dev/null)"
+[ -n "$PHASE_SCHEMA" ] || PHASE_SCHEMA=2
+
 TS="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
-LINE="{\"ts\":\"${TS}\",\"task_id\":\"${TASK_ID}\",\"phase\":\"${PHASE}\",\"event\":\"${EVENT}\",\"details\":${DETAILS}}"
+LINE="{\"ts\":\"${TS}\",\"task_id\":\"${TASK_ID}\",\"phase\":\"${PHASE}\",\"event\":\"${EVENT}\",\"details\":${DETAILS},\"phaseSchema\":${PHASE_SCHEMA}}"
 
 # Atomic append (one line, well under PIPE_BUF).
 echo "$LINE" >> "$METRICS_FILE" 2>/dev/null || {

package/pipeline/scripts/memory-save.sh

@@ -2,7 +2,7 @@
 # memory-save.sh  -  v6.2.E
 #
 # Writes a single per-repo memory file and updates the MEMORY.md index.
-# Called by Phase 7's synthesis step (or any user skill that wants to
+# Called by Phase 5's synthesis step (or any user skill that wants to
 # persist a finding). Opt-in via prefs.global.perRepoMemory.
 #
 # Usage:

package/pipeline/scripts/migrate-prefs.mjs

@@ -18,9 +18,26 @@ import { runMain } from "../lib/fatal.mjs";
 
 const DEFAULT_FILE = path.join(os.homedir(), ".claude", "multi-agent-preferences.json");
 
-// Single source of truth for the migration target version. Referenced by the
-// migrate() bump chain AND every user-facing message, so they cannot drift.
-const TARGET_VERSION = "2.6.0";
+// The migration target, read from the schema rather than written here. It was
+// a literal, and a literal is how it came to say 2.6.0 while the schema had
+// moved to 2.7.0 - the runner then reported every current file as needing a
+// migration it had already had. Referenced by the migrate() bump chain AND
+// every user-facing message, so they cannot drift from each other either.
+const TARGET_VERSION = (() => {
+  const schemaPath = path.join(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "schemas",
+    "prefs.schema.json",
+  );
+  const sv = JSON.parse(fs.readFileSync(schemaPath, "utf-8"))?.properties?.schemaVersion;
+  const v = sv?.const ?? sv?.enum?.at(-1);
+  if (!v) {
+    console.error("migrate-prefs: prefs.schema.json declares no schemaVersion");
+    process.exit(1);
+  }
+  return v;
+})();
 
 const USAGE = "Usage: migrate-prefs.mjs [--dry-run] [--file <path>]";
 
@@ -327,7 +344,7 @@ function migrate(prefs) {
     out.global.routines = [];
     changes.push("added empty routines (v2.4.0 user-defined /multi-agent:save routines)");
   }
-  // v2.5.0 / v14.0.0: Phase 4 Review entered the --dev phase sets and Step 1.78
+  // v2.5.0 / v14.0.0: Phase 3 Review entered the --dev phase sets and Step 1.78
   // (criteria resolution) landed. Default false because only Swift plus the two
   // store-compliance catalogs ship a scoped registry today, so blocking on a
   // coverage gap would stop every Kotlin/Python/Node/ObjC run from day one. The
@@ -488,7 +505,7 @@ function migrateReportChannels(out, changes) {
   if (typeof g.autopilotReportTimeoutSeconds !== "number") {
     g.autopilotReportTimeoutSeconds = 1800;
     changes.push(
-      "added autopilotReportTimeoutSeconds: 1800 (30 min)  -  Phase 7 always-pause timeout",
+      "added autopilotReportTimeoutSeconds: 1800 (30 min)  -  Phase 5 always-pause timeout",
     );
   }
 

package/pipeline/scripts/phase-banner.sh

@@ -12,9 +12,9 @@
 #   phase-banner.sh label <phase>                               (print canonical name)
 #
 # Examples:
-#   phase-banner.sh start 4 "Review" "deterministic gates + parallel + triage"
-#   phase-banner.sh start 4 auto                   # resolves to "Review" (en) or "İnceleme" (tr)
-#   PHASE_LANG=tr phase-banner.sh start 4 auto     # "Faz 4: İnceleme"
+#   phase-banner.sh start 3 "Review" "parallel + triage + user test"
+#   phase-banner.sh start 3 auto                   # resolves to "Review" (en) or "İnceleme" (tr)
+#   PHASE_LANG=tr phase-banner.sh start 3 auto     # "Faz 3: İnceleme"
 #
 # Status values for `end`: done | failed | skipped
 #
@@ -32,28 +32,28 @@ set -uo pipefail
 
 PHASE_LANG="${PHASE_LANG:-en}"
 
-# Canonical phase label table. Keep synced with
-# pipeline/multi-agent-refs/phases.md and the table in
-# pipeline/skills/shared/multi-agent/SKILL.md.
+# Canonical phase label table. The English half is checked against
+# pipeline/schemas/phases.json by smoke-phase-contract.sh, so it cannot drift
+# from the contract in silence the way it did through the eight-phase era. It
+# stays a case statement rather than a jq read because this runs on every
+# banner and the pipeline's zero-dependency rule (ADR-0004) applies to the hot
+# path. The Turkish half has no contract entry - labels are translations, not
+# identifiers - and is kept beside it.
 phase_label() {
   local phase="$1" lang="${2:-en}"
   case "$lang:$phase" in
     en:0) echo "Init" ;;
-    en:1) echo "Analysis" ;;
-    en:2) echo "Planning" ;;
-    en:3) echo "Dev" ;;
-    en:4) echo "Review" ;;
-    en:5) echo "Test" ;;
-    en:6) echo "Commit & PR" ;;
-    en:7) echo "Report" ;;
+    en:1) echo "Plan" ;;
+    en:2) echo "Dev" ;;
+    en:3) echo "Review" ;;
+    en:4) echo "Commit & PR" ;;
+    en:5) echo "Report" ;;
     tr:0) echo "Başlangıç" ;;
-    tr:1) echo "Analiz" ;;
-    tr:2) echo "Planlama" ;;
-    tr:3) echo "Geliştirme" ;;
-    tr:4) echo "İnceleme" ;;
-    tr:5) echo "Kullanıcı Testi" ;;
-    tr:6) echo "Commit & PR" ;;
-    tr:7) echo "Rapor" ;;
+    tr:1) echo "Plan" ;;
+    tr:2) echo "Geliştirme" ;;
+    tr:3) echo "İnceleme" ;;
+    tr:4) echo "Commit & PR" ;;
+    tr:5) echo "Rapor" ;;
     *) echo "" ;;
   esac
 }