@mmerterden/multi-agent-pipeline 12.3.0 → 12.5.0

package/pipeline/scripts/gc-worktrees.sh

@@ -64,6 +64,13 @@ if ! git -C "$REPO" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
   exit 0
 fi
 REPO="$(cd "$REPO" && pwd -P)"
+# Anchor on the MAIN worktree (first porcelain entry) so a run started from a
+# subdirectory OR from inside a linked worktree still targets
+# <main-repo>/.worktrees/ rather than a bogus <subdir>/.worktrees/ (which
+# silently found nothing and left residue behind).
+MAIN_WT="$(git -C "$REPO" worktree list --porcelain 2>/dev/null | sed -n 's/^worktree //p' | head -1)"
+MAIN_WT="$(cd "$MAIN_WT" 2>/dev/null && pwd -P)" || MAIN_WT=""
+[ -n "$MAIN_WT" ] && REPO="$MAIN_WT"
 WT_ROOT="$REPO/.worktrees"
 
 changed=0
@@ -76,9 +83,24 @@ pruned=$(git -C "$REPO" worktree prune -v 2>&1 | grep -c . || true)
 # 2. Orphan dirs: present under .worktrees/ but not registered as worktrees.
 orphans=()
 if [ -d "$WT_ROOT" ]; then
-  registered=$(git -C "$REPO" worktree list --porcelain 2>/dev/null | sed -n 's/^worktree //p')
+  # Resolve every registered worktree path to its physical form so the
+  # orphan test below compares like-for-like against `pwd -P`-resolved dirs.
+  # A raw (unresolved) registered path with a symlinked component would fail
+  # the match and get a HEALTHY worktree misclassified as an orphan and
+  # deleted under --yes; resolving both sides removes that risk (this mirrors
+  # purge.sh, which resolves both sides).
+  registered=""
+  while IFS= read -r regpath; do
+    [ -n "$regpath" ] || continue
+    regphys="$(cd "$regpath" 2>/dev/null && pwd -P)" || regphys=""
+    [ -n "$regphys" ] && registered="$registered$regphys
+"
+  done <<EOF
+$(git -C "$REPO" worktree list --porcelain 2>/dev/null | sed -n 's/^worktree //p')
+EOF
   for d in "$WT_ROOT"/*/; do
     [ -d "$d" ] || continue
+    [ -L "${d%/}" ] && continue  # never follow a symlinked entry out of the tree
     dir="$(cd "$d" && pwd -P)"
     # Path guard: only ever consider dirs strictly inside <repo>/.worktrees/.
     case "$dir" in "$WT_ROOT"/*) ;; *) continue ;; esac

package/pipeline/scripts/learning-curve.mjs

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+// learning-curve.mjs  -  time-bucketed TREND over metrics.jsonl.
+//
+// aggregate-metrics.mjs reports lifetime totals; this reports the CURVE: how
+// the pipeline's per-task quality/cost move over time as it accumulates
+// learnings on a repo. Without a trend you cannot tell whether "it gets better
+// over time" is real - this is the measurement layer for the learning loop.
+//
+// Buckets tasks by the timestamp of their first event, then per bucket reports:
+//   tasks, first-pass-clean rate, avg review cycles, rework/task,
+//   tokens/task, cache-reuse ratio. Prints a first->last trend for the
+//   headline KPIs. Read-only, zero deps, no API/model calls.
+//
+// Usage:
+//   learning-curve.mjs [--bucket=<days>] [--since=ISO] [--json|--markdown]
+// Env: METRICS_FILE overrides the default ~/.claude/logs/multi-agent/metrics.jsonl
+//
+// Exit: 0 always (advisory; empty/missing metrics -> friendly note).
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const args = process.argv.slice(2);
+const opts = { json: false, markdown: false, since: null, bucketDays: 7 };
+for (const a of args) {
+  if (a === "--json") opts.json = true;
+  else if (a === "--markdown" || a === "--md") opts.markdown = true;
+  else if (a.startsWith("--since=")) opts.since = a.slice(8);
+  else if (a.startsWith("--bucket=")) opts.bucketDays = Math.max(1, parseInt(a.slice(9), 10) || 7);
+  else if (a === "--help" || a === "-h") {
+    console.log("Usage: learning-curve.mjs [--bucket=<days>] [--since=ISO] [--json|--markdown]");
+    process.exit(0);
+  }
+}
+
+const METRICS_FILE =
+  process.env.METRICS_FILE || join(homedir(), ".claude", "logs", "multi-agent", "metrics.jsonl");
+
+function emitEmpty(reason) {
+  if (opts.json) console.log(JSON.stringify({ ok: false, reason, buckets: [] }));
+  else console.error(`learning-curve: ${reason}`);
+  process.exit(0);
+}
+
+if (!existsSync(METRICS_FILE)) emitEmpty(`no metrics file at ${METRICS_FILE}`);
+
+const events = [];
+for (const line of readFileSync(METRICS_FILE, "utf-8").split("\n")) {
+  if (!line.trim()) continue;
+  try {
+    const e = JSON.parse(line);
+    if (opts.since && e.ts && e.ts < opts.since) continue;
+    events.push(e);
+  } catch {
+    /* skip corrupted line */
+  }
+}
+if (events.length === 0) emitEmpty("no metrics events in range");
+
+// Fold events into per-task aggregates.
+const num = (v) => (typeof v === "number" ? v : Number(v)) || 0;
+const tasks = new Map();
+for (const e of events) {
+  const id = e.task_id;
+  if (!id) continue;
+  let t = tasks.get(id);
+  if (!t) {
+    t = { firstTs: e.ts, reviewCycles: null, rework: 0, tokensIn: 0, tokensOut: 0, tokensCached: 0 };
+    tasks.set(id, t);
+  }
+  if (e.ts && (!t.firstTs || e.ts < t.firstTs)) t.firstTs = e.ts;
+  const d = e.details || {};
+  if (e.event === "review.completed" && d.review_cycles != null) t.reviewCycles = num(d.review_cycles);
+  if (e.event === "rework.started") t.rework += 1;
+  t.tokensIn += num(d.tokens_in);
+  t.tokensOut += num(d.tokens_out);
+  t.tokensCached += num(d.tokens_cached);
+}
+
+// Bucket tasks by first-seen day / bucketDays window (UTC).
+const DAY = 86400000;
+const bucketOf = (ts) => {
+  const ms = Date.parse(ts);
+  if (Number.isNaN(ms)) return null;
+  const dayIndex = Math.floor(ms / DAY);
+  const b = Math.floor(dayIndex / opts.bucketDays) * opts.bucketDays;
+  return new Date(b * DAY).toISOString().slice(0, 10);
+};
+
+const byBucket = new Map();
+for (const t of tasks.values()) {
+  const key = bucketOf(t.firstTs);
+  if (!key) continue;
+  if (!byBucket.has(key)) byBucket.set(key, []);
+  byBucket.get(key).push(t);
+}
+
+const round = (n, p = 2) => Math.round(n * 10 ** p) / 10 ** p;
+const buckets = [...byBucket.keys()].sort().map((start) => {
+  const list = byBucket.get(start);
+  const n = list.length;
+  const withReview = list.filter((t) => t.reviewCycles != null);
+  const firstPassClean = withReview.filter((t) => t.reviewCycles <= 1).length;
+  const totIn = list.reduce((s, t) => s + t.tokensIn, 0);
+  const totOut = list.reduce((s, t) => s + t.tokensOut, 0);
+  const totCached = list.reduce((s, t) => s + t.tokensCached, 0);
+  return {
+    bucketStart: start,
+    tasks: n,
+    firstPassCleanRate: withReview.length ? round(firstPassClean / withReview.length) : null,
+    avgReviewCycles: withReview.length
+      ? round(withReview.reduce((s, t) => s + t.reviewCycles, 0) / withReview.length)
+      : null,
+    reworkPerTask: round(list.reduce((s, t) => s + t.rework, 0) / n),
+    tokensPerTask: Math.round((totIn + totOut) / n),
+    cacheRatio: totIn ? round(totCached / totIn) : null,
+  };
+});
+
+// first->last trend for the headline KPIs (only when >=2 buckets).
+let trend = null;
+if (buckets.length >= 2) {
+  const a = buckets[0];
+  const z = buckets[buckets.length - 1];
+  const delta = (x, y) => (x == null || y == null ? null : round(y - x));
+  trend = {
+    from: a.bucketStart,
+    to: z.bucketStart,
+    firstPassCleanRate: delta(a.firstPassCleanRate, z.firstPassCleanRate),
+    avgReviewCycles: delta(a.avgReviewCycles, z.avgReviewCycles),
+    tokensPerTask: a.tokensPerTask && z.tokensPerTask ? z.tokensPerTask - a.tokensPerTask : null,
+    cacheRatio: delta(a.cacheRatio, z.cacheRatio),
+  };
+}
+
+const out = { ok: true, bucketDays: opts.bucketDays, buckets, trend };
+
+if (opts.json) {
+  console.log(JSON.stringify(out, null, 2));
+  process.exit(0);
+}
+
+// Markdown / text (default)
+const arrow = (v, goodIsUp) => {
+  if (v == null || v === 0) return "-";
+  const up = v > 0;
+  const good = up === goodIsUp;
+  return `${up ? "+" : ""}${v} ${good ? "(better)" : "(worse)"}`;
+};
+console.log(`# Learning curve (${opts.bucketDays}-day buckets)\n`);
+console.log("| Bucket | Tasks | First-pass clean | Avg review cycles | Rework/task | Tokens/task | Cache ratio |");
+console.log("|---|---|---|---|---|---|---|");
+for (const b of buckets) {
+  console.log(
+    `| ${b.bucketStart} | ${b.tasks} | ${b.firstPassCleanRate ?? "-"} | ${b.avgReviewCycles ?? "-"} | ${b.reworkPerTask} | ${b.tokensPerTask} | ${b.cacheRatio ?? "-"} |`,
+  );
+}
+if (trend) {
+  console.log(`\n**Trend ${trend.from} -> ${trend.to}:**`);
+  console.log(`- First-pass clean: ${arrow(trend.firstPassCleanRate, true)}`);
+  console.log(`- Avg review cycles: ${arrow(trend.avgReviewCycles, false)}`);
+  console.log(`- Tokens/task: ${arrow(trend.tokensPerTask, false)}`);
+  console.log(`- Cache ratio: ${arrow(trend.cacheRatio, true)}`);
+} else {
+  console.log("\n(need >= 2 buckets for a trend; keep running the pipeline)");
+}

package/pipeline/scripts/learnings-ledger.mjs

@@ -120,7 +120,7 @@ function writeRow(slug, row) {
 
 /** Append one entry unless an entry with the same kind + normalized statement
  *  already exists (idempotent). Returns true when written. */
-function addEntry(slug, { kind, statement, scope, task, confidence }, existing) {
+function addEntry(slug, { kind, statement, scope, task, confidence, diagnosis }, existing) {
   const stmt = String(statement || "").trim();
   if (!stmt) return false;
   const seenKey = `${kind}::${normStatement(stmt)}`;
@@ -135,6 +135,11 @@ function addEntry(slug, { kind, statement, scope, task, confidence }, existing)
     source_task: task || null,
     confidence: CONFIDENCES.has(confidence) ? confidence : "medium",
   };
+  // Optional causal diagnosis (Reflexion P5): the "why it failed" behind a
+  // lesson. Verbal diagnosis is what turns a detected error into a prevented
+  // one; a bare outcome does not. Stored only when supplied.
+  const diag = String(diagnosis || "").trim();
+  if (diag) row.diagnosis = diag;
   writeRow(slug, row);
   existing.add(seenKey);
   return true;
@@ -152,6 +157,7 @@ function cmdAdd() {
     scope: flags.scope && flags.scope !== true ? String(flags.scope) : "global",
     task: flags.task && flags.task !== true ? String(flags.task) : null,
     confidence: flags.confidence && flags.confidence !== true ? String(flags.confidence) : "medium",
+    diagnosis: flags.diagnosis && flags.diagnosis !== true ? String(flags.diagnosis) : null,
   }, existing);
   process.stdout.write(JSON.stringify({ ok: true, slug, added: wrote ? 1 : 0, deduped: wrote ? 0 : 1 }) + "\n");
   process.exit(wrote ? 0 : 2);
@@ -247,7 +253,8 @@ function cmdBrief() {
     lines.push("", `## ${labels[kind]}`);
     for (const r of items) {
       const scope = r.scope && r.scope !== "global" ? ` [${r.scope}]` : "";
-      lines.push(`- ${r.statement}${scope}`);
+      const why = r.diagnosis ? ` (why: ${r.diagnosis})` : "";
+      lines.push(`- ${r.statement}${scope}${why}`);
     }
   }
   lines.push("</repo-learnings>");

package/pipeline/scripts/migrate-prefs.mjs

@@ -18,7 +18,7 @@ const DEFAULT_FILE = path.join(os.homedir(), ".claude", "multi-agent-preferences
 
 // 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.3.0";
+const TARGET_VERSION = "2.4.0";
 
 const USAGE = "Usage: migrate-prefs.mjs [--dry-run] [--file <path>]";
 
@@ -164,6 +164,9 @@ function migrate(prefs) {
   const TARGET = TARGET_VERSION;
   if (out.schemaVersion === TARGET) {
     // already on target  -  skip version bump, but still run sub-migrations below
+  } else if (out.schemaVersion === "2.3.0") {
+    out.schemaVersion = TARGET;
+    changes.push(`schemaVersion: 2.3.0 → ${TARGET}`);
   } else if (out.schemaVersion === "2.2.0") {
     out.schemaVersion = TARGET;
     changes.push(`schemaVersion: 2.2.0 → ${TARGET}`);
@@ -241,6 +244,10 @@ function migrate(prefs) {
     out.global.accounts = [];
     changes.push("added empty accounts (v7.4.0 per-account host overrides)");
   }
+  if (!Array.isArray(out.global.routines)) {
+    out.global.routines = [];
+    changes.push("added empty routines (v2.4.0 user-defined /multi-agent:save routines)");
+  }
   if (!out.global.serviceStatus) {
     out.global.serviceStatus = {};
     changes.push("added empty serviceStatus");

package/pipeline/scripts/repo-map.mjs

@@ -82,7 +82,7 @@ function parseArgs(argv) {
 // ---- File walking ----------------------------------------------------------
 
 const DEFAULT_IGNORE = new Set([
-  '.git', 'node_modules', 'Pods', '.build', 'DerivedData', '.next',
+  '.git', '.worktrees', 'node_modules', 'Pods', '.build', 'DerivedData', '.next',
   'dist', 'build', '__pycache__', '.venv', 'venv', '.cache',
   '.gradle', '.idea', '.vscode', 'target',
 ]);

package/pipeline/scripts/routine-registry.mjs

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+// routine-registry.mjs  -  backend for the user-defined routine commands
+// (/multi-agent:save, :routines, :forget).
+//
+// A "routine" is a saved, reusable procedure the user binds to its own
+// /multi-agent:<name> slash command. Each routine is TWO artifacts:
+//   1. a local-only command dir  ~/.claude/commands/multi-agent/<name>/SKILL.md
+//      (frontmatter `local-only: true` -> the installer preserves it across
+//       updates and /multi-agent:sync refuses to leak it into the public repo)
+//   2. a registry entry in       ~/.claude/multi-agent-preferences.json
+//      at global.routines[]  (name, description, createdAt, source)
+//
+// This tool is the mechanical half; the save/routines/forget SKILLs drive the
+// UX (candidate discovery, pickers, confirmation) and call these subcommands.
+//
+// Zero deps. Never writes under a repo `pipeline/` tree; only ever under
+// <home>/.claude/. Refuses to touch a shipped (non-local-only) command dir.
+//
+// Usage:
+//   node routine-registry.mjs list [--json] [--home <dir>]
+//   node routine-registry.mjs get    --name <n> [--home <dir>]
+//   node routine-registry.mjs add     --name <n> --description <d>
+//        [--description-tr <t>] [--argument-hint <h>] --source <s> --body-file <f> [--home <dir>]
+//   node routine-registry.mjs remove  --name <n> [--home <dir>]
+//
+// Exit: 0 ok, 1 error (validation / collision / not-found), 64 usage.
+
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  rmSync,
+  renameSync,
+} from "node:fs";
+import { join, dirname } from "node:path";
+
+const NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+const MAX_NAME = 40;
+const MAX_ROUTINES = 100;
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith("--")) {
+        out[key] = true;
+      } else {
+        out[key] = next;
+        i++;
+      }
+    } else {
+      out._.push(a);
+    }
+  }
+  return out;
+}
+
+function fail(msg) {
+  console.error(`routine-registry: ${msg}`);
+  process.exit(1);
+}
+
+function homeDir(args) {
+  return args.home || process.env.HOME || process.env.USERPROFILE || "";
+}
+function prefsPath(home) {
+  return join(home, ".claude", "multi-agent-preferences.json");
+}
+function routineDir(home, name) {
+  return join(home, ".claude", "commands", "multi-agent", name);
+}
+
+function readPrefs(home) {
+  const p = prefsPath(home);
+  if (!existsSync(p)) return { global: {} };
+  try {
+    const prefs = JSON.parse(readFileSync(p, "utf-8"));
+    if (!prefs.global) prefs.global = {};
+    return prefs;
+  } catch {
+    fail(`could not parse ${p}`);
+  }
+}
+
+function writePrefs(home, prefs) {
+  const p = prefsPath(home);
+  mkdirSync(dirname(p), { recursive: true });
+  const tmp = `${p}.tmp.${process.pid}`;
+  writeFileSync(tmp, `${JSON.stringify(prefs, null, 2)}\n`);
+  renameSync(tmp, p);
+}
+
+function getRoutines(prefs) {
+  return Array.isArray(prefs.global.routines) ? prefs.global.routines : [];
+}
+
+// A dir is a shipped (non-routine) command when it exists and its SKILL.md is
+// NOT marked local-only. Those must never be overwritten or removed.
+function isLocalOnlyDir(dir) {
+  const skill = join(dir, "SKILL.md");
+  if (!existsSync(skill)) return false;
+  return /^local-only:\s*true\s*$/m.test(readFileSync(skill, "utf-8"));
+}
+
+function cmdList(home, json) {
+  const routines = getRoutines(readPrefs(home));
+  if (json) {
+    process.stdout.write(`${JSON.stringify(routines, null, 2)}\n`);
+    return;
+  }
+  if (routines.length === 0) {
+    console.log("(no routines saved)");
+    return;
+  }
+  for (const r of routines) {
+    console.log(`${r.name}\t${r.description || ""}\t${r.createdAt || ""}`);
+  }
+}
+
+function cmdGet(home, name) {
+  const r = getRoutines(readPrefs(home)).find((x) => x.name === name);
+  if (!r) fail(`no routine named "${name}"`);
+  process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
+}
+
+function buildSkill(args) {
+  const desc = args.description;
+  const descTr = args["description-tr"];
+  const hint = args["argument-hint"] || "[optional args]";
+  const body = readFileSync(args["body-file"], "utf-8").trimEnd();
+  const fm = [
+    "---",
+    `description: ${JSON.stringify(desc)}`,
+    descTr ? `description-tr: ${JSON.stringify(descTr)}` : null,
+    `argument-hint: ${JSON.stringify(hint)}`,
+    "allowed-tools: Skill, Bash, Read, Edit, Write, AskUserQuestion",
+    "local-only: true",
+    "---",
+  ].filter(Boolean);
+  return `${fm.join("\n")}\n\n# multi-agent ${args.name}  -  saved routine\n\n**Input**: $ARGUMENTS\n\n${body}\n`;
+}
+
+function cmdAdd(home, args) {
+  const name = args.name;
+  if (!name || !NAME_RE.test(name) || name.length > MAX_NAME) {
+    fail(`invalid --name (need ${NAME_RE} , <= ${MAX_NAME} chars): ${name}`);
+  }
+  if (!args.description) fail("--description is required");
+  if (!args["body-file"] || !existsSync(args["body-file"])) {
+    fail("--body-file is required and must exist");
+  }
+  const dir = routineDir(home, name);
+  // Collision: an existing non-local-only dir is a shipped command - never touch.
+  if (existsSync(dir) && !isLocalOnlyDir(dir)) {
+    fail(`"${name}" collides with a shipped command; pick another name`);
+  }
+  const prefs = readPrefs(home);
+  const routines = getRoutines(prefs);
+  if (routines.some((r) => r.name === name)) {
+    fail(`a routine named "${name}" already exists; forget it first or pick another name`);
+  }
+  if (routines.length >= MAX_ROUTINES) fail(`routine cap (${MAX_ROUTINES}) reached`);
+
+  mkdirSync(dir, { recursive: true });
+  const skill = buildSkill(args);
+  // Safety: the generated file MUST be local-only so it never syncs to the repo.
+  if (!/^local-only:\s*true\s*$/m.test(skill)) fail("internal: generated SKILL missing local-only");
+  writeFileSync(join(dir, "SKILL.md"), skill);
+
+  routines.push({
+    name,
+    description: args.description,
+    createdAt: new Date().toISOString(),
+    source: args.source || "user",
+  });
+  prefs.global.routines = routines;
+  writePrefs(home, prefs);
+  console.log(`routine-registry: saved "${name}" -> ${join(dir, "SKILL.md")}`);
+  console.log("routine-registry: available as /multi-agent:" + name + " after a session reload");
+}
+
+function cmdRemove(home, name) {
+  if (!name) fail("--name is required");
+  const prefs = readPrefs(home);
+  const routines = getRoutines(prefs);
+  const idx = routines.findIndex((r) => r.name === name);
+  const dir = routineDir(home, name);
+  // Guard: only remove a dir that is BOTH registered AND local-only.
+  if (existsSync(dir) && !isLocalOnlyDir(dir)) {
+    fail(`"${name}" is a shipped command, not a routine; refusing to remove`);
+  }
+  if (idx < 0 && !existsSync(dir)) fail(`no routine named "${name}"`);
+  if (existsSync(dir) && isLocalOnlyDir(dir)) rmSync(dir, { recursive: true, force: true });
+  if (idx >= 0) {
+    routines.splice(idx, 1);
+    prefs.global.routines = routines;
+    writePrefs(home, prefs);
+  }
+  console.log(`routine-registry: removed "${name}" (clears from autocomplete on next session reload)`);
+}
+
+function main() {
+  const [, , sub, ...rest] = process.argv;
+  const args = parseArgs(rest);
+  const home = homeDir(args);
+  if (!home) fail("cannot resolve home dir");
+  switch (sub) {
+    case "list":
+      return cmdList(home, Boolean(args.json));
+    case "get":
+      return cmdGet(home, args.name);
+    case "add":
+      return cmdAdd(home, args);
+    case "remove":
+      return cmdRemove(home, args.name);
+    default:
+      console.error("usage: routine-registry.mjs <list|get|add|remove> [flags]  (see header)");
+      process.exit(64);
+  }
+}
+
+main();

package/pipeline/scripts/smoke-generate-issue.sh

@@ -91,11 +91,11 @@ echo ""
 echo "→ 8. registration + count consistency (36)"
 grep -Fq '| `create-jira ' "$DISPATCHER" && pass "dispatcher routing: create-jira" || fail "dispatcher routing missing: generate"
 grep -Fq "create-jira/SKILL.md" "$DISPATCHER" && pass "dispatcher loading row" || fail "dispatcher loading row missing"
-grep -Fq "## 1. Command Inventory (38 commands)" "$CONTRACT" && pass "contract count = 38" || fail "contract count wrong"
+grep -Fq "## 1. Command Inventory (41 commands)" "$CONTRACT" && pass "contract count = 41" || fail "contract count wrong"
 grep -Eq '(^|[ ,])create-jira([ ,]|$)' "$CONTRACT" && pass "contract list has create-jira" || fail "contract list missing generate"
-grep -Fq "**38 commands are synced**" "$SYNC" && pass "sync count = 38" || fail "sync count wrong"
+grep -Fq "**41 commands are synced**" "$SYNC" && pass "sync count = 41" || fail "sync count wrong"
 SYNC_SKILL="$ROOT/pipeline/skills/shared/core/multi-agent-sync/SKILL.md"
-grep -Fq "**38 commands are synced**" "$SYNC_SKILL" && pass "sync SKILL count = 38" || fail "sync SKILL count wrong (Copilot parity)"
+grep -Fq "**41 commands are synced**" "$SYNC_SKILL" && pass "sync SKILL count = 41" || fail "sync SKILL count wrong (Copilot parity)"
 grep -Fq "create-jira" "$ROOT/pipeline/skills/shared/core/multi-agent-help/SKILL.md" && pass "help SKILL lists create-jira" || fail "help SKILL missing create-jira (Copilot parity)"
 grep -c "multi-agent:create-jira" "$HELP" | awk '{exit !($1>=2)}' && pass "help.md has EN + TR entries" || fail "help.md entries incomplete"
 # no stale split-command references anywhere in the synced surfaces

package/pipeline/scripts/smoke-learning-curve.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# smoke-learning-curve.sh  -  contract for learning-curve.mjs (time-bucketed
+# trend over metrics.jsonl).
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+LC="$SCRIPT_DIR/learning-curve.mjs"
+
+PASS=0
+FAIL=0
+record_pass() { PASS=$((PASS + 1)); printf '  \342\234\223 %s\n' "$1"; }
+record_fail() { FAIL=$((FAIL + 1)); printf '  \342\234\227 %s\n' "$1"; }
+
+printf '\342\206\222 smoke-learning-curve: metrics trend contract\n'
+
+tmp=$(mktemp -d "${TMPDIR:-/tmp}/lc.XXXXXX")
+trap 'rm -rf "$tmp"' EXIT
+M="$tmp/metrics.jsonl"
+
+# Two early tasks (noisy: 3/2 review cycles, low cache) + two later tasks
+# (clean: 1 cycle, high cache) -> the curve should improve.
+cat > "$M" <<'EOF'
+{"ts":"2026-06-02T10:00:00Z","task_id":"t1","phase":"4","event":"review.completed","details":{"review_cycles":3,"tokens_in":100000,"tokens_out":8000,"tokens_cached":10000}}
+{"ts":"2026-06-02T10:05:00Z","task_id":"t1","phase":"3","event":"rework.started","details":{}}
+{"ts":"2026-06-03T09:00:00Z","task_id":"t2","phase":"4","event":"review.completed","details":{"review_cycles":2,"tokens_in":90000,"tokens_out":7000,"tokens_cached":20000}}
+{"ts":"2026-06-24T09:00:00Z","task_id":"t3","phase":"4","event":"review.completed","details":{"review_cycles":1,"tokens_in":40000,"tokens_out":4000,"tokens_cached":30000}}
+{"ts":"2026-06-25T09:00:00Z","task_id":"t4","phase":"4","event":"review.completed","details":{"review_cycles":1,"tokens_in":38000,"tokens_out":3500,"tokens_cached":32000}}
+EOF
+
+# 1. parses
+bash -n "$SCRIPT_DIR/smoke-learning-curve.sh" >/dev/null 2>&1 || true
+if node --check "$LC" 2>/dev/null; then record_pass "learning-curve.mjs parses"; else record_fail "syntax error"; fi
+
+# 2. JSON: buckets + improving trend
+out=$(METRICS_FILE="$M" node "$LC" --json 2>/dev/null)
+nbuckets=$(printf '%s' "$out" | python3 -c "import json,sys;print(len(json.load(sys.stdin)['buckets']))")
+[ "$nbuckets" -ge 2 ] && record_pass "produces >=2 time buckets" || record_fail "expected >=2 buckets, got $nbuckets"
+
+tokens_delta=$(printf '%s' "$out" | python3 -c "import json,sys;print(json.load(sys.stdin)['trend']['tokensPerTask'])")
+case "$tokens_delta" in
+  -*) record_pass "tokens/task trend is negative (improving)" ;;
+  *) record_fail "tokens/task trend should drop, got $tokens_delta" ;;
+esac
+cache_delta=$(printf '%s' "$out" | python3 -c "import json,sys;print(json.load(sys.stdin)['trend']['cacheRatio'])")
+case "$cache_delta" in
+  -*|0|0.0) record_fail "cache ratio should rise, got $cache_delta" ;;
+  *) record_pass "cache ratio trend rises (improving)" ;;
+esac
+
+# 3. markdown renders a table + trend
+md=$(METRICS_FILE="$M" node "$LC" 2>/dev/null)
+printf '%s' "$md" | grep -q "Learning curve" && record_pass "markdown has a header" || record_fail "no markdown header"
+printf '%s' "$md" | grep -q "Trend" && record_pass "markdown shows a trend block" || record_fail "no trend block"
+
+# 4. missing metrics -> graceful, exit 0
+METRICS_FILE="/nope/none.jsonl" node "$LC" --json >/dev/null 2>&1
+[ "$?" -eq 0 ] && record_pass "missing metrics is a graceful no-op (exit 0)" || record_fail "missing metrics should exit 0"
+
+printf '\n\342\225\220\342\225\220 smoke-learning-curve: %d passed, %d failed \342\225\220\342\225\220\n' "$PASS" "$FAIL"
+[ "$FAIL" -eq 0 ]

package/pipeline/scripts/smoke-migrate-state.sh

@@ -75,12 +75,12 @@ else
   fail "unknown flag did not exit 1"
 fi
 
-# Test 7  -  type auto-detection works
+# Test 7  -  type auto-detection works (feed a doc already at the latest version)
 cat > "$TMPDIR/multi-agent-preferences.json" <<'EOF'
-{"schemaVersion":"2.3.0","global":{"identities":[],"keychainMapping":{},"recentAccounts":[],"accounts":[]},"projects":{}}
+{"schemaVersion":"2.4.0","global":{"identities":[],"keychainMapping":{},"recentAccounts":[],"accounts":[],"routines":[]},"projects":{}}
 EOF
 OUT=$(node "$RUNNER" "$TMPDIR/multi-agent-preferences.json" 2>&1)
-if echo "$OUT" | grep -q "already at schemaVersion 2.3.0"; then
+if echo "$OUT" | grep -q "already at schemaVersion 2.4.0"; then
   pass "prefs type auto-detected from filename"
 else
   fail "prefs auto-detection failed (got: $OUT)"

package/pipeline/scripts/smoke-pref-migration.sh

@@ -64,7 +64,7 @@ F1=$(run_fixture "f1-v2.0.0-legacy" '{
   },
   "projects": {}
 }')
-assert_json_has "f1" "$F1" ".schemaVersion" "2.3.0"
+assert_json_has "f1" "$F1" ".schemaVersion" "2.4.0"
 assert_json_has "f1" "$F1" ".global.identities" "array:1"
 assert_json_has "f1" "$F1" ".global.gitIdentities" "undefined"
 assert_json_has "f1" "$F1" ".global.settings" "object:8"
@@ -73,6 +73,7 @@ assert_json_has "f1" "$F1" ".global.platformIdentityRouting" "object:0"
 assert_json_has "f1" "$F1" ".global.recentGroups" "array:0"
 assert_json_has "f1" "$F1" ".global.recentAccounts" "array:0"
 assert_json_has "f1" "$F1" ".global.accounts" "array:0"
+assert_json_has "f1" "$F1" ".global.routines" "array:0"
 
 echo ""
 echo "→ Fixture 2: no schemaVersion (pre-2.0.0 fossil)"
@@ -80,15 +81,15 @@ F2=$(run_fixture "f2-no-version" '{
   "global": {"gitIdentities": []},
   "projects": {}
 }')
-assert_json_has "f2" "$F2" ".schemaVersion" "2.3.0"
+assert_json_has "f2" "$F2" ".schemaVersion" "2.4.0"
 assert_json_has "f2" "$F2" ".global.identities" "array:0"
 
 echo ""
-echo "→ Fixture 3: v2.3.0 already (no-op)"
-F3_FILE="$TMP/f3-v2.3.0.json"
+echo "→ Fixture 3: v2.4.0 already (no-op)"
+F3_FILE="$TMP/f3-v2.4.0.json"
 cat > "$F3_FILE" <<'EOF'
 {
-  "schemaVersion": "2.3.0",
+  "schemaVersion": "2.4.0",
   "global": {
     "identities": [],
     "keychainMapping": {
@@ -117,7 +118,8 @@ cat > "$F3_FILE" <<'EOF'
     "wikiScope": ["main", "ios", "screenshots", "index"],
     "autopilotReportTimeoutSeconds": 1800,
     "recentAccounts": [],
-    "accounts": []
+    "accounts": [],
+    "routines": []
   },
   "projects": {}
 }

package/pipeline/scripts/smoke-review-readiness.sh

@@ -66,7 +66,7 @@ grep -Fq '| `review-jira ' "$DISPATCHER" && pass "dispatcher desc: review-jira"
 grep -Fq '| `review-issue ' "$DISPATCHER" && pass "dispatcher desc: review-issue" || fail "dispatcher desc missing review-issue"
 grep -Fq "review-jira/SKILL.md" "$DISPATCHER" && pass "dispatcher routing: review-jira" || fail "dispatcher routing missing review-jira"
 grep -Fq "review-issue/SKILL.md" "$DISPATCHER" && pass "dispatcher routing: review-issue" || fail "dispatcher routing missing review-issue"
-grep -Fq "## 1. Command Inventory (38 commands)" "$CONTRACT" && pass "contract count = 38" || fail "contract count wrong"
+grep -Fq "## 1. Command Inventory (41 commands)" "$CONTRACT" && pass "contract count = 41" || fail "contract count wrong"
 grep -Eq '(^|[ ,])review-jira([ ,]|$)' "$CONTRACT" && pass "contract inventory has review-jira" || fail "contract missing review-jira"
 grep -Eq '(^|[ ,])review-issue([ ,]|$)' "$CONTRACT" && pass "contract inventory has review-issue" || fail "contract missing review-issue"
 grep -Fq "multi-agent:review-jira" "$HELP" && pass "help lists review-jira" || fail "help missing review-jira"