@mmerterden/multi-agent-pipeline 12.5.0 → 12.7.0

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

@@ -19,14 +19,14 @@
       "required": ["sourcesScanned", "testsScanned", "gapCount", "gapBySeverity"],
       "properties": {
         "sourcesScanned": { "type": "integer", "minimum": 0 },
-        "testsScanned":   { "type": "integer", "minimum": 0 },
-        "gapCount":       { "type": "integer", "minimum": 0 },
+        "testsScanned": { "type": "integer", "minimum": 0 },
+        "gapCount": { "type": "integer", "minimum": 0 },
         "gapBySeverity": {
           "type": "object",
           "additionalProperties": false,
           "properties": {
-            "blocking":   { "type": "integer", "minimum": 0 },
-            "important":  { "type": "integer", "minimum": 0 },
+            "blocking": { "type": "integer", "minimum": 0 },
+            "important": { "type": "integer", "minimum": 0 },
             "suggestion": { "type": "integer", "minimum": 0 }
           },
           "required": ["blocking", "important", "suggestion"]
@@ -41,7 +41,7 @@
         "required": ["sourcePath", "symbol", "kind", "severity", "expectedTestPaths", "hint"],
         "properties": {
           "sourcePath": { "type": "string", "minLength": 1 },
-          "symbol":     { "type": "string", "minLength": 1 },
+          "symbol": { "type": "string", "minLength": 1 },
           "kind": {
             "type": "string",
             "description": "Pattern id from the rules file (e.g. public_func, composable_fun, named_export)."

package/pipeline/schemas/token-budget.json

@@ -3,14 +3,14 @@
   "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/token-budget.json",
   "description": "Per-phase token budget for lazy-loaded pipeline docs. Enforced by smoke-token-budget.sh.",
   "phases": {
-    "phase-0-init":      { "max_tokens": 12400, "warn_tokens": 10900 },
-    "phase-1-analysis":  { "max_tokens": 3750, "warn_tokens": 3300 },
-    "phase-2-planning":  { "max_tokens": 6500, "warn_tokens": 5750 },
-    "phase-3-dev":       { "max_tokens": 7900, "warn_tokens": 6950 },
-    "phase-4-review":    { "max_tokens": 13250, "warn_tokens": 11650 },
-    "phase-5-test":      { "max_tokens": 2550, "warn_tokens": 2250 },
-    "phase-6-commit":    { "max_tokens": 6150, "warn_tokens": 5400 },
-    "phase-7-report":    { "max_tokens": 5600, "warn_tokens": 4950 }
+    "phase-0-init": { "max_tokens": 12400, "warn_tokens": 10900 },
+    "phase-1-analysis": { "max_tokens": 3750, "warn_tokens": 3300 },
+    "phase-2-planning": { "max_tokens": 6500, "warn_tokens": 5750 },
+    "phase-3-dev": { "max_tokens": 7900, "warn_tokens": 6950 },
+    "phase-4-review": { "max_tokens": 13250, "warn_tokens": 11650 },
+    "phase-5-test": { "max_tokens": 2550, "warn_tokens": 2250 },
+    "phase-6-commit": { "max_tokens": 6150, "warn_tokens": 5400 },
+    "phase-7-report": { "max_tokens": 5600, "warn_tokens": 4950 }
   },
   "total_max_tokens": 51000,
   "note": "Token estimate = ceil(chars / 4). Per-phase budget rule: warn = current+10% (rounded to nearest 50), max = current+25%. Gives ~6 edit cycles of headroom before warn trips  -  intentionally quiet under normal maintenance, loud when a phase grows unusually. Only the active phase is loaded (lazy). Recalibrated at v10.0.0 after the validator/consistency/simplifier/lesson gate contracts landed in phases 1-4. Recalibrated again at v10.9.0 after the verify-by-test (Phase 4 Step 3.7), update-check (Phase 0 Step 0.6), immutable-test (Phase 3 GREEN) and redTests re-entry contracts landed  -  Step 3.7 prose was compressed to a pointer into refs/features/verify-by-test.md before the recalibration. Total bumped 50000 -> 51000 at v12.5.0 after the worktree residue/traversal-prune contract (Phase 0 + Phase 5 heal) and the Reflexion causal-diagnosis contract (Phase 4 lesson memory) landed; the prose was compressed first (161 tokens reclaimed) and every per-phase max still passes  -  only the aggregate needed room."

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

@@ -24,7 +24,7 @@
     "file": { "type": "string" },
     "line": { "type": ["integer", "null"] },
     "issue": { "type": "string", "minLength": 1 },
-    "fix":  { "type": ["string", "null"] },
+    "fix": { "type": ["string", "null"] },
     "reason": { "type": ["string", "null"] },
     "reviewer": { "type": ["string", "null"] },
     "file_sha": {

package/pipeline/scripts/README.md

@@ -1,10 +1,10 @@
 # Pipeline Scripts  -  Category Index
 
-The `pipeline/scripts/` directory holds 59 shell scripts + 12 Node.js `.mjs` scripts in a flat layout. v6.0.0 evaluated moving them into `smoke/`, `hooks/`, `runtime/` subdirs and decided against it: each path change would need to propagate through `package.json` globs, `install.js` deploy logic, npm scripts, sibling script calls, and CI workflow references  -  a 40+ file touch radius with high regression risk for minor polish value.
+The `pipeline/scripts/` directory holds 148 shell scripts + 45 Node.js `.mjs` scripts in a flat layout. v6.0.0 evaluated moving them into `smoke/`, `hooks/`, `runtime/` subdirs and decided against it: each path change would need to propagate through `package.json` globs, `install.js` deploy logic, npm scripts, sibling script calls, and CI workflow references  -  a 40+ file touch radius with high regression risk for minor polish value.
 
-Instead, this README is the category index. Use it to navigate.
+Instead, this README is a curated category index of the key scripts, not an exhaustive listing. Use it to navigate.
 
-## Smoke scripts (42 files  -  `smoke-*.sh`)
+## Smoke scripts (118 files  -  `smoke-*.sh`)
 
 Validate contracts. Each emits `══ <name> smoke: N passed, M failed ══` on completion (the `smoke-personal-data.sh` + `smoke-token-budget.sh` suites use `PASS:` / `warnings:` variants). Run via `npm test` (chained) or individually.
 
@@ -57,6 +57,7 @@ Validate contracts. Each emits `══ <name> smoke: N passed, M failed ══`
 - `smoke-search.sh`  -  `/multi-agent:search` log search + smart ranking
 - `smoke-subagent-validators.sh`  -  Phase 1/2 validator schemas
 - `smoke-telemetry.sh`  -  opt-in telemetry contract
+- `smoke-learning-curve.sh`  -  `learning-curve.mjs` metrics-trend contract
 - `smoke-validator-contradiction.sh`  -  Phase 4 approved/blocking contradiction detection
 - `smoke-pre-commit.sh`  -  pre-commit hook integration
 
@@ -81,12 +82,13 @@ Shell scripts invoked during pipeline execution.
 - `github-ssh-setup.sh`  -  first-run SSH key setup helper
 - `sync-parity-check.sh`  -  manual parity verification helper
 
-## Node.js helpers (12 `.mjs` files)
+## Node.js helpers (45 `.mjs` files)
 
 - `aggregate-metrics.mjs`  -  collects telemetry aggregates
+- `learning-curve.mjs`  -  time-bucketed trend over `metrics.jsonl` (first-pass clean rate, review cycles, rework/task, tokens/task, cache ratio); `--bucket`, `--since`, `--json`, `--markdown`
 - `eval-triage.mjs`  -  runs the 10 triage eval fixtures
 - `gen-skills-index.mjs`  -  regenerates `pipeline/skills/shared/README.md` skill catalog
-- `migrate-prefs.mjs`  -  preference migration driver (v2.0.0 → v2.1.0 → v2.2.0)
+- `migrate-prefs.mjs`  -  preference migration driver (v2.0.0 through v2.4.0)
 - `migrate-state.mjs`  -  generic migration runner (reads `schemas/migrations/`)
 - `token-budget-report.mjs`  -  per-phase token usage report
 - `validate-analysis.mjs`, `validate-planning.mjs`, `validate-reviewer.mjs`, `validate-triage.mjs`  -  per-phase output validators

package/pipeline/scripts/aggregate-metrics.mjs

@@ -230,7 +230,9 @@ if (opts.markdown) {
   const lines = [];
   lines.push(`# Pipeline Metrics Summary`);
   lines.push(``);
-  lines.push(`_Source: \`${summary.source}\` · Events: ${summary.total_events} (${summary.parse_errors} parse errors) · Unique tasks: ${summary.unique_tasks}_`);
+  lines.push(
+    `_Source: \`${summary.source}\` · Events: ${summary.total_events} (${summary.parse_errors} parse errors) · Unique tasks: ${summary.unique_tasks}_`,
+  );
   lines.push(``);
   lines.push(`## Reviews`);
   lines.push(``);
@@ -245,9 +247,13 @@ if (opts.markdown) {
   lines.push(`| Category | Count | Rate |`);
   lines.push(`|----------|-------|------|`);
   lines.push(`| Raw findings | ${summary.triage_totals.raw} |  -  |`);
-  lines.push(`| Accepted | ${summary.triage_totals.accepted} | ${summary.triage_totals.accept_rate ?? " - "} |`);
+  lines.push(
+    `| Accepted | ${summary.triage_totals.accepted} | ${summary.triage_totals.accept_rate ?? " - "} |`,
+  );
   lines.push(`| Deferred | ${summary.triage_totals.deferred} |  -  |`);
-  lines.push(`| Rejected | ${summary.triage_totals.rejected} | ${summary.triage_totals.reject_rate ?? " - "} |`);
+  lines.push(
+    `| Rejected | ${summary.triage_totals.rejected} | ${summary.triage_totals.reject_rate ?? " - "} |`,
+  );
 
   if (Object.keys(summary.edge_cases).length) {
     lines.push(``);
@@ -266,14 +272,20 @@ if (opts.markdown) {
     lines.push(``);
     lines.push(`| Model | Calls | Duration (ms) | Tokens In | Tokens Out | Cached | Cache % |`);
     lines.push(`|-------|-------|---------------|-----------|------------|--------|---------|`);
-    for (const [m, t] of Object.entries(summary.cost_per_model).sort((a, b) => b[1].calls - a[1].calls)) {
+    for (const [m, t] of Object.entries(summary.cost_per_model).sort(
+      (a, b) => b[1].calls - a[1].calls,
+    )) {
       const pct = t.cache_ratio === null ? " - " : `${Math.round(t.cache_ratio * 100)}%`;
-      lines.push(`| \`${m}\` | ${t.calls} | ${t.duration_ms} | ${t.tokens_in} | ${t.tokens_out} | ${t.tokens_cached} | ${pct} |`);
+      lines.push(
+        `| \`${m}\` | ${t.calls} | ${t.duration_ms} | ${t.tokens_in} | ${t.tokens_out} | ${t.tokens_cached} | ${pct} |`,
+      );
     }
     const oc = summary.cache_reuse;
     const ocPct = oc.cache_ratio === null ? " - " : `${Math.round(oc.cache_ratio * 100)}%`;
     lines.push(``);
-    lines.push(`_Overall prompt-cache reuse: ${oc.tokens_cached.toLocaleString()} cached / ${(oc.tokens_in + oc.tokens_cached).toLocaleString()} total input tokens = **${ocPct}**._`);
+    lines.push(
+      `_Overall prompt-cache reuse: ${oc.tokens_cached.toLocaleString()} cached / ${(oc.tokens_in + oc.tokens_cached).toLocaleString()} total input tokens = **${ocPct}**._`,
+    );
   }
   console.log(lines.join("\n"));
   process.exit(0);

package/pipeline/scripts/build-skills-index.mjs

@@ -40,7 +40,11 @@ function* walkSkills(dir) {
   for (const entry of readdirSync(dir)) {
     const full = join(dir, entry);
     let st;
-    try { st = statSync(full); } catch { continue; }
+    try {
+      st = statSync(full);
+    } catch {
+      continue;
+    }
     if (st.isDirectory()) yield* walkSkills(full);
     else if (entry === "SKILL.md") yield full;
   }
@@ -56,7 +60,7 @@ function parseFrontmatter(raw) {
     const m = line.match(/^([\w-]+):\s*(.*)$/);
     if (!m) continue;
     let value = m[2].trim();
-    if (value.startsWith("\"") && value.endsWith("\"")) value = value.slice(1, -1);
+    if (value.startsWith('"') && value.endsWith('"')) value = value.slice(1, -1);
     out[m[1]] = value;
   }
   return out;

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

@@ -10,7 +10,7 @@
  * publish artifact.
  *
  * The authored lifecycle skills (index / reference / workflow / tools) live in the
- * plugin repo and are NEVER touched here — only the `knowledge/` layer + plugin.json
+ * plugin repo and are NEVER touched here - only the `knowledge/` layer + plugin.json
  * knowledge entries are regenerated.
  *
  * Routing uses the per-stack skill patterns (formerly carried by stack-swap.sh). Genuinely cross-stack
@@ -23,37 +23,83 @@
  * Exit code 0 always (report-only); prints a JSON-ish summary + per-plugin diff.
  */
 import {
-  readdirSync, existsSync, rmSync, cpSync, readFileSync, writeFileSync, mkdirSync, statSync,
-} from 'node:fs';
-import { join } from 'node:path';
+  readdirSync,
+  existsSync,
+  rmSync,
+  cpSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  statSync,
+} from "node:fs";
+import { join } from "node:path";
 
 const args = process.argv.slice(2);
-const getArg = (k, d) => { const i = args.indexOf(k); return i >= 0 ? args[i + 1] : d; };
+const getArg = (k, d) => {
+  const i = args.indexOf(k);
+  return i >= 0 ? args[i + 1] : d;
+};
 const HOME = process.env.HOME;
-const PLUGINS_REPO = getArg('--plugins-repo', join(HOME, 'multi-agent-plugins'));
-const PIPE_ROOT = getArg('--pipeline', join(HOME, 'multi-agent-pipeline'));
-const EXTERNAL = join(PIPE_ROOT, 'pipeline/skills/shared/external');
-const DRY = args.includes('--dry-run');
+const PLUGINS_REPO = getArg("--plugins-repo", join(HOME, "multi-agent-plugins"));
+const PIPE_ROOT = getArg("--pipeline", join(HOME, "multi-agent-pipeline"));
+const EXTERNAL = join(PIPE_ROOT, "pipeline/skills/shared/external");
+const DRY = args.includes("--dry-run");
 
-const COMMON_PLUGIN = 'ai-common-engineering-toolkit';
-const COMMON_SKILLS = ['accessibility-compliance-accessibility-audit', 'firebase', 'humanizer', 'council', 'search-first', 'agent-introspection-debugging', 'skill-creator', 'backlog'];
+const COMMON_PLUGIN = "ai-common-engineering-toolkit";
+const COMMON_SKILLS = [
+  "accessibility-compliance-accessibility-audit",
+  "firebase",
+  "humanizer",
+  "council",
+  "search-first",
+  "agent-introspection-debugging",
+  "skill-creator",
+  "backlog",
+];
 
 // Apple/Xcode-only skills that match no stack pattern → iOS plugin only.
 const APPLE_ONLY = [
-  'avkit', 'cryptokit', 'metrickit-diagnostics', 'pdfkit', 'spm-build-analysis',
-  'swiftlint', 'xcode-build-benchmark', 'xcode-build-fixer', 'xcode-build-orchestrator',
-  'xcode-compilation-analyzer', 'xcode-project-analyzer',
+  "avkit",
+  "cryptokit",
+  "metrickit-diagnostics",
+  "pdfkit",
+  "spm-build-analysis",
+  "swiftlint",
+  "xcode-build-benchmark",
+  "xcode-build-fixer",
+  "xcode-build-orchestrator",
+  "xcode-compilation-analyzer",
+  "xcode-project-analyzer",
 ];
 
 // stack → matching pattern (per-stack routing patterns (formerly in stack-swap.sh))
+//
+// A skill lands in every plugin whose pattern it matches, so a bare substring
+// alternative that is also a suffix of another stack's skill name silently ships
+// that skill twice. `architecture` did exactly that: it pulled
+// `android-architecture` and `swift-architecture` into ai-backend-toolkit
+// alongside their correct plugins, so a backend project loading the toolkit got
+// Compose and SwiftUI architecture skills. It is anchored to the exact name now.
+// Keep any new single-word alternative anchored unless it genuinely reads as a
+// substring across stacks.
 const STACK_PATTERNS = {
-  'ai-ios-engineering-toolkit': /(swiftui|swift-|ios-|hig-|apple-|storekit|widgetkit|healthkit|homekit|mapkit|musickit|passkit|pencilkit|realitykit|weatherkit|alarmkit|callkit|cloudkit|coreml|core-|eventkit|energykit|permissionkit|tipkit|shareplay|live-activities|background-processing|app-store|app-clips|app-intents|authentication|contacts-framework|device-integrity|macos-|natural-language|photos-camera|push-notifications|speech-recognition|swiftdata|vision-framework|debugging-instruments|help-skills)/i,
-  'ai-android-engineering-toolkit': /(android|compose-|kotlin-|room-database|retrofit-|gradle-|play-store)/i,
-  'ai-backend-toolkit': /(fastapi|nodejs|docker|api-pattern|api-security|github-actions|observability|architecture|monorepo|clean-code|debugging-strategies|agentflow|closed-loop|context-compression|python-patterns|database-patterns|rest-api-design|testing-backend|ci-cd-pipelines)/i,
-  'ai-frontend-engineering-toolkit': /(react-|nextjs-|typescript-|tailwind-|vue-|web-accessibility|web-performance|css-modern|web-testing|html-semantic)/i,
+  "ai-ios-engineering-toolkit":
+    /(swiftui|swift-|ios-|hig-|apple-|storekit|widgetkit|healthkit|homekit|mapkit|musickit|passkit|pencilkit|realitykit|weatherkit|alarmkit|callkit|cloudkit|coreml|core-|eventkit|energykit|permissionkit|tipkit|shareplay|live-activities|background-processing|app-store|app-clips|app-intents|authentication|contacts-framework|device-integrity|macos-|natural-language|photos-camera|push-notifications|speech-recognition|swiftdata|vision-framework|debugging-instruments|help-skills)/i,
+  "ai-android-engineering-toolkit":
+    /(android|compose-|kotlin-|room-database|retrofit-|gradle-|play-store)/i,
+  "ai-backend-toolkit":
+    /(fastapi|nodejs|docker|api-pattern|api-security|github-actions|observability|^architecture$|monorepo|clean-code|debugging-strategies|agentflow|closed-loop|context-compression|python-patterns|database-patterns|rest-api-design|testing-backend|ci-cd-pipelines)/i,
+  "ai-frontend-engineering-toolkit":
+    /(react-|nextjs-|typescript-|tailwind-|vue-|web-accessibility|web-performance|css-modern|web-testing|html-semantic)/i,
 };
 
-const isDir = (p) => { try { return statSync(p).isDirectory(); } catch { return false; } };
+const isDir = (p) => {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+};
 const listDirs = (p) => (existsSync(p) ? readdirSync(p).filter((n) => isDir(join(p, n))) : []);
 
 // --- 1. enumerate authoring source ---------------------------------------
@@ -69,22 +115,67 @@ for (const p of Object.keys(STACK_PATTERNS)) desired[p] = new Set();
 
 const unrouted = [];
 for (const skill of allSkills) {
-  if (COMMON_SKILLS.includes(skill)) { desired[COMMON_PLUGIN].add(skill); continue; }
-  if (APPLE_ONLY.includes(skill)) { desired['ai-ios-engineering-toolkit'].add(skill); continue; }
+  if (COMMON_SKILLS.includes(skill)) {
+    desired[COMMON_PLUGIN].add(skill);
+    continue;
+  }
+  if (APPLE_ONLY.includes(skill)) {
+    desired["ai-ios-engineering-toolkit"].add(skill);
+    continue;
+  }
   let matched = false;
   for (const [plugin, re] of Object.entries(STACK_PATTERNS)) {
-    if (re.test(skill)) { desired[plugin].add(skill); matched = true; }
+    if (re.test(skill)) {
+      desired[plugin].add(skill);
+      matched = true;
+    }
   }
   if (!matched) unrouted.push(skill);
 }
 
+// --- 2b. routing audit ---------------------------------------------------
+// The loop above adds a skill to EVERY plugin whose pattern matches, so a bare
+// substring alternative that also reads as a suffix of another stack's skill
+// name ships that skill into two plugins. `architecture` did that to
+// android-architecture and swift-architecture, which is how ai-backend-toolkit
+// came to carry Compose and SwiftUI guidance.
+//
+// --check-routing runs this audit alone. It reads nothing but the authoring
+// source in this repo, so CI can gate it without a checkout of the plugins repo.
+const multiRouted = [];
+for (const skill of allSkills) {
+  if (COMMON_SKILLS.includes(skill) || APPLE_ONLY.includes(skill)) continue;
+  const owners = Object.entries(STACK_PATTERNS)
+    .filter(([, re]) => re.test(skill))
+    .map(([p]) => p);
+  if (owners.length > 1) multiRouted.push(`${skill} -> ${owners.join(" + ")}`);
+}
+
+if (args.includes("--check-routing")) {
+  if (multiRouted.length) {
+    console.error(
+      `check-routing: ${multiRouted.length} skill(s) routed to more than one stack plugin`,
+    );
+    for (const m of multiRouted) console.error(`  FAIL ${m}`);
+    console.error("fix: anchor the offending STACK_PATTERNS alternative to the exact skill name");
+    process.exit(1);
+  }
+  console.log(
+    `check-routing: clean (${allSkills.length} skills, ${unrouted.length} unrouted, 0 multi-routed)`,
+  );
+  process.exit(0);
+}
+
 // --- 3. sync each plugin's knowledge/ + regenerate plugin.json -----------
 const report = [];
 for (const [plugin, want] of Object.entries(desired)) {
-  const pdir = join(PLUGINS_REPO, 'plugins', plugin);
-  const kdir = join(pdir, 'skills', 'knowledge');
-  const pjPath = join(pdir, '.claude-plugin', 'plugin.json');
-  if (!existsSync(pjPath)) { report.push({ plugin, error: 'plugin.json missing' }); continue; }
+  const pdir = join(PLUGINS_REPO, "plugins", plugin);
+  const kdir = join(pdir, "skills", "knowledge");
+  const pjPath = join(pdir, ".claude-plugin", "plugin.json");
+  if (!existsSync(pjPath)) {
+    report.push({ plugin, error: "plugin.json missing" });
+    continue;
+  }
 
   const have = new Set(listDirs(kdir));
   const toAdd = [...want].filter((s) => !have.has(s)).sort();
@@ -98,16 +189,16 @@ for (const [plugin, want] of Object.entries(desired)) {
   }
 
   // regenerate plugin.json skills[]: keep non-knowledge entries, rebuild knowledge set
-  const pj = JSON.parse(readFileSync(pjPath, 'utf8'));
-  const nonKnowledge = (pj.skills || []).filter((s) => !s.startsWith('./skills/knowledge/'));
+  const pj = JSON.parse(readFileSync(pjPath, "utf8"));
+  const nonKnowledge = (pj.skills || []).filter((s) => !s.startsWith("./skills/knowledge/"));
   const finalKnowledge = (DRY ? [...want] : listDirs(kdir)).map((s) => `./skills/knowledge/${s}`);
   const newSkills = [...new Set([...nonKnowledge, ...finalKnowledge])].sort();
   const skillsChanged = JSON.stringify(pj.skills) !== JSON.stringify(newSkills);
 
-  const oldV = pj.version || '0.1.0';
+  const oldV = pj.version || "0.1.0";
   let newV = oldV;
   if (changed || skillsChanged) {
-    const [maj, min, patch] = oldV.split('.').map((n) => parseInt(n, 10) || 0);
+    const [maj, min, patch] = oldV.split(".").map((n) => parseInt(n, 10) || 0);
     newV = `${maj}.${min}.${patch + 1}`;
   }
   if (!DRY && (changed || skillsChanged)) {
@@ -115,23 +206,35 @@ for (const [plugin, want] of Object.entries(desired)) {
     pj.version = newV;
     writeFileSync(pjPath, `${JSON.stringify(pj, null, 2)}\n`);
   }
-  report.push({ plugin, added: toAdd, removed: toRemove, skillCount: newSkills.length, version: oldV === newV ? oldV : `${oldV} → ${newV}`, bumped: oldV !== newV });
+  report.push({
+    plugin,
+    added: toAdd,
+    removed: toRemove,
+    skillCount: newSkills.length,
+    version: oldV === newV ? oldV : `${oldV} → ${newV}`,
+    bumped: oldV !== newV,
+  });
 }
 
 // --- 4. report ------------------------------------------------------------
-console.log(`build-stack-plugins ${DRY ? '(dry-run)' : ''}`);
+console.log(`build-stack-plugins ${DRY ? "(dry-run)" : ""}`);
 console.log(`source: ${EXTERNAL} (${allSkills.length} skills)`);
 console.log(`target: ${PLUGINS_REPO}`);
 for (const r of report) {
-  if (r.error) { console.log(`  ✗ ${r.plugin}: ${r.error}`); continue; }
-  const flag = r.bumped ? 'BUMPED' : 'unchanged';
+  if (r.error) {
+    console.log(`  ✗ ${r.plugin}: ${r.error}`);
+    continue;
+  }
+  const flag = r.bumped ? "BUMPED" : "unchanged";
   console.log(`  ${r.plugin}: skills=${r.skillCount} version=${r.version} [${flag}]`);
-  if (r.added.length) console.log(`      + ${r.added.join(', ')}`);
-  if (r.removed.length) console.log(`      - ${r.removed.join(', ')}`);
+  if (r.added.length) console.log(`      + ${r.added.join(", ")}`);
+  if (r.removed.length) console.log(`      - ${r.removed.join(", ")}`);
 }
 if (unrouted.length) {
-  console.log(`  ⚠ unrouted (matched no stack, not common/apple-only) — NOT copied anywhere:`);
-  console.log(`      ${unrouted.join(', ')}`);
+  console.log(`  ⚠ unrouted (matched no stack, not common/apple-only) - NOT copied anywhere:`);
+  console.log(`      ${unrouted.join(", ")}`);
 }
 const anyBump = report.some((r) => r.bumped);
-console.log(anyBump ? 'result: changes detected (versions bumped)' : 'result: all plugins up to date');
+console.log(
+  anyBump ? "result: changes detected (versions bumped)" : "result: all plugins up to date",
+);

package/pipeline/scripts/check-derived-drift.mjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+// check-derived-drift.mjs - resolve the upstream version for every entry in
+// prefs `global.derivedSkillSources[]` and report drift.
+//
+// This exists because the resolution order is the whole correctness question,
+// and prose in a skill file cannot be tested. The step used to read the
+// installed plugin cache and call the answer authoritative. A cache is only as
+// fresh as the last `claude marketplace update`, so it reported "up to date"
+// for a derivation that was four releases behind, and the version it had been
+// recorded from was the wrong manifest besides.
+//
+// Resolution order, first source that answers wins:
+//   1. upstreamLocalClone   a working copy of the upstream repo
+//   2. upstreamRepoUrl      the same manifest over `gh api`
+//   3. the plugin cache     a mirror; can only ever yield "unverified"
+//
+// Which manifest carries the version is `upstreamVersionSource`, default
+// marketplace.json, because that is what a marketplace consumer resolves.
+//
+// Exit codes: 0 = no drift (or not configured), 1 = drift or unverified,
+//             2 = a configured entry could not be resolved at all.
+//
+// Flags: --json  machine-readable output for the scorecard gate.
+
+import { Buffer } from "node:buffer";
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const asJson = process.argv.includes("--json");
+// Overridable so the gate can be driven against fixtures. Real runs read the
+// user's prefs; a test that had to write into $HOME to exercise this would be
+// a test nobody runs.
+const PREFS =
+  process.env.DERIVED_DRIFT_PREFS || join(homedir(), ".claude", "multi-agent-preferences.json");
+const CACHE = process.env.DERIVED_DRIFT_CACHE || join(homedir(), ".claude", "plugins", "cache");
+
+const expandHome = (p) => p.replace(/^\$HOME\b|^~/, homedir());
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+// A manifest names its version either directly (plugin.json) or inside a
+// plugins[] entry keyed by name (marketplace.json).
+function versionFrom(manifest, pluginName) {
+  if (!manifest) return null;
+  if (Array.isArray(manifest.plugins)) {
+    const hit = manifest.plugins.find((p) => p.name === pluginName);
+    return hit?.version ?? null;
+  }
+  return manifest.version ?? null;
+}
+
+function fromLocalClone(entry) {
+  if (!entry.upstreamLocalClone) return null;
+  const root = expandHome(entry.upstreamLocalClone);
+  const file =
+    entry.upstreamVersionSource === "plugin.json"
+      ? join(root, "plugins", entry.upstreamPlugin, ".claude-plugin", "plugin.json")
+      : join(root, ".claude-plugin", "marketplace.json");
+  if (!existsSync(file)) return null;
+  const version = versionFrom(readJson(file), entry.upstreamPlugin);
+  if (!version) return null;
+
+  // A clone behind its own remote is still a stale answer, just a less stale
+  // one than the cache. Say so rather than presenting it as current.
+  let behind;
+  try {
+    const out = execFileSync("git", ["-C", root, "rev-list", "--count", "HEAD..@{u}"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    behind = Number(out) || 0;
+  } catch {
+    // No upstream branch configured, or not a git checkout at all.
+    behind = null;
+  }
+
+  return { version, source: "local clone", authoritative: true, behind };
+}
+
+function fromRepoApi(entry) {
+  if (!entry.upstreamRepoUrl) return null;
+  const m = entry.upstreamRepoUrl.match(/github\.com\/([^/]+)\/([^/.]+)/);
+  if (!m) return null;
+  const path =
+    entry.upstreamVersionSource === "plugin.json"
+      ? `plugins/${entry.upstreamPlugin}/.claude-plugin/plugin.json`
+      : ".claude-plugin/marketplace.json";
+  try {
+    const raw = execFileSync(
+      "gh",
+      ["api", `repos/${m[1]}/${m[2]}/contents/${path}`, "--jq", ".content"],
+      { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] },
+    ).trim();
+    const version = versionFrom(
+      JSON.parse(Buffer.from(raw, "base64").toString("utf-8")),
+      entry.upstreamPlugin,
+    );
+    return version ? { version, source: "repo api", authoritative: true, behind: 0 } : null;
+  } catch {
+    // 404 here means unreachable for the active account, not "no drift".
+    return null;
+  }
+}
+
+function fromCache(entry) {
+  if (!entry.upstreamMarketplace) return null;
+  const dir = join(CACHE, entry.upstreamMarketplace, entry.upstreamPlugin);
+  if (!existsSync(dir)) return null;
+  const versions = readdirSync(dir)
+    .filter((d) => /^\d+\.\d+\.\d+$/.test(d))
+    .sort();
+  const newest = versions[versions.length - 1];
+  return newest
+    ? { version: newest, source: "plugin cache", authoritative: false, behind: null }
+    : null;
+}
+
+const prefs = readJson(PREFS);
+const entries = prefs?.global?.derivedSkillSources ?? [];
+
+if (entries.length === 0) {
+  const msg = "check-derived-drift: no derived-skill sources configured";
+  console.log(
+    asJson ? JSON.stringify({ configured: 0, drifted: 0, unverified: 0, entries: [] }) : msg,
+  );
+  process.exit(0);
+}
+
+const rows = [];
+for (const entry of entries) {
+  const resolved = fromLocalClone(entry) || fromRepoApi(entry) || fromCache(entry);
+  if (!resolved) {
+    rows.push({
+      label: entry.label,
+      plugin: entry.upstreamPlugin,
+      from: entry.derivedFromVersion,
+      upstream: null,
+      source: "unreachable",
+      status: "unreachable",
+    });
+    continue;
+  }
+  const drifted = resolved.version !== entry.derivedFromVersion;
+  const status = drifted
+    ? "drift"
+    : resolved.authoritative
+      ? "up to date"
+      : "unverified (cache only)";
+  rows.push({
+    label: entry.label,
+    plugin: entry.upstreamPlugin,
+    from: entry.derivedFromVersion,
+    upstream: resolved.version,
+    source: resolved.source,
+    cloneBehind: resolved.behind,
+    status,
+  });
+}
+
+const drifted = rows.filter((r) => r.status === "drift").length;
+const unverified = rows.filter((r) => r.status.startsWith("unverified")).length;
+const unreachable = rows.filter((r) => r.status === "unreachable").length;
+
+if (asJson) {
+  console.log(
+    JSON.stringify(
+      { configured: rows.length, drifted, unverified, unreachable, entries: rows },
+      null,
+      2,
+    ),
+  );
+} else {
+  for (const r of rows) {
+    const behind = r.cloneBehind ? ` [clone ${r.cloneBehind} behind its remote]` : "";
+    console.log(
+      `  ${r.status === "up to date" ? "✓" : "✗"} ${r.plugin}: recorded ${r.from}, ` +
+        `upstream ${r.upstream ?? "?"} (${r.source})${behind} -> ${r.status}`,
+    );
+  }
+  console.log("");
+  console.log(
+    `══ check-derived-drift: ${rows.length - drifted - unverified - unreachable} passed, ` +
+      `${drifted + unverified + unreachable} failed ══`,
+  );
+}
+
+if (unreachable > 0) process.exit(2);
+process.exit(drifted + unverified > 0 ? 1 : 0);

package/pipeline/scripts/check-md-links.mjs

@@ -33,8 +33,12 @@ function mdFiles(dir, acc = []) {
 }
 
 const targets = [
-  ...readdirSync(repoRoot).filter((f) => f.endsWith(".md")).map((f) => join(repoRoot, f)),
-  ...["docs", "examples", "pipeline"].filter((d) => existsSync(join(repoRoot, d))).flatMap((d) => mdFiles(join(repoRoot, d))),
+  ...readdirSync(repoRoot)
+    .filter((f) => f.endsWith(".md"))
+    .map((f) => join(repoRoot, f)),
+  ...["docs", "examples", "pipeline"]
+    .filter((d) => existsSync(join(repoRoot, d)))
+    .flatMap((d) => mdFiles(join(repoRoot, d))),
   // CHANGELOG-archive.md is frozen history - it legitimately references docs
   // that were deleted in later releases.
 ]