@mmerterden/multi-agent-pipeline 14.2.2 → 15.1.0

package/pipeline/schemas/token-budget.json

@@ -36,6 +36,6 @@
       "warn_tokens": 5600
     }
   },
-  "total_max_tokens": 52750,
-  "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. Recalibrated again at v13.6.0 after the install-relative path correction: an instruction that names `pipeline/scripts/x` resolves only from a repo checkout, and a run happens in the user's worktree, so 157 references across these docs moved to `$HOME/.claude/...` at +5 bytes each  -  196 tokens of pure correctness cost. Same discipline as before: prose was compressed FIRST (149 tokens reclaimed, by pointing Phase 1's Figma tier table at the Phase 0 probe that already resolved it and Phase 4's Codex constraints at the always-loaded AGENTS.md block), and only then were the budgets moved. Five warn lines had been permanently amber, which makes the amber tier useless as a signal, so every warn was reset to the documented current+10% and the four maxes that the new warn would have collided with were reset to current+25%. Aggregate 51000 -> 51500. Total bumped 51500 -> 52200 at v14.0.0 after Phase 4 Review entered the four --dev mode phase sets and the criteria-resolution contract (Step 1.78) landed. Same discipline as every prior bump: prose was compressed FIRST, 820 tokens reclaimed, before the number moved. Two of those compressions are structural rather than cosmetic - the hardcoded SwiftUI interaction list in Step 1.5 and the SwiftUI convention paragraph in Step 2.8 were transcriptions of rules that now live in a scoped registry, so keeping them here would have re-created the drift this release exists to remove, and the third moved the Step 1.78 full contract into refs/features/skill-conformance.md leaving a pointer. What remains is contract text that cannot be inferred: the manifest's four consumer-visible parts, the conformance checklist the reviewers must return, and the fail-closed semantics. Every per-phase max still passes (phase-4 12405/14750); only the aggregate needed room. Total bumped 52200 -> 52700 at v14.1.0 after two more contracts landed: stack skill routing (Phase 3 pre-flight step 9) and worktree finalize (Phase 6 step 9). Compression came first, as always, and twice: 224 tokens out of Phase 3 by pointing its criteria-ledger and routing steps at their feature files instead of restating them, and 190 out of Phase 6 by moving the finalize contract into refs/features/worktree-finalize.md and leaving the invocation plus the exit-3 semantics. Both new contracts follow the pattern the earlier ones set: the phase doc carries the call and the decision, the feature file carries the reasoning, and the feature files are outside this budget because it loops only the eight phase-N-* keys. Every per-phase max still passes (phase-3 7677/8950, phase-6 5223/6150 and both under warn); only the aggregate needed room. Total bumped 52700 -> 52750 for the Phase 0 Step 3 branch-persistence correction: the step wrote the legacy `projects[].branches` while the TTL filter two sections below read `global.recentBranches`, and both spots named a `{name, lastUsed}` shape the schema rejects (`branch` required, `additionalProperties: false`), so the recent-branch picker option could never populate and a literal implementation would have failed prefs validation. Naming the right target, the right key and the legacy field to avoid costs 41 tokens over the one line it replaces. Compression came first and was applied three times to the replacement text itself, from 120 tokens down to 66, by moving the rationale out of the phase doc entirely: the reasoning now lives where it is enforced, in the migrate-prefs carry-forward comment and the smoke-pref-migration f7 block, leaving the phase doc with only the instruction. 50 was the smallest step that clears it; phase-0-init sits at 10893/12400, far under its own max, so this is purely an aggregate ceiling."
+  "total_max_tokens": 53100,
+  "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. Recalibrated again at v13.6.0 after the install-relative path correction: an instruction that names `pipeline/scripts/x` resolves only from a repo checkout, and a run happens in the user's worktree, so 157 references across these docs moved to `$HOME/.claude/...` at +5 bytes each  -  196 tokens of pure correctness cost. Same discipline as before: prose was compressed FIRST (149 tokens reclaimed, by pointing Phase 1's Figma tier table at the Phase 0 probe that already resolved it and Phase 4's Codex constraints at the always-loaded AGENTS.md block), and only then were the budgets moved. Five warn lines had been permanently amber, which makes the amber tier useless as a signal, so every warn was reset to the documented current+10% and the four maxes that the new warn would have collided with were reset to current+25%. Aggregate 51000 -> 51500. Total bumped 51500 -> 52200 at v14.0.0 after Phase 4 Review entered the four --dev mode phase sets and the criteria-resolution contract (Step 1.78) landed. Same discipline as every prior bump: prose was compressed FIRST, 820 tokens reclaimed, before the number moved. Two of those compressions are structural rather than cosmetic - the hardcoded SwiftUI interaction list in Step 1.5 and the SwiftUI convention paragraph in Step 2.8 were transcriptions of rules that now live in a scoped registry, so keeping them here would have re-created the drift this release exists to remove, and the third moved the Step 1.78 full contract into refs/features/skill-conformance.md leaving a pointer. What remains is contract text that cannot be inferred: the manifest's four consumer-visible parts, the conformance checklist the reviewers must return, and the fail-closed semantics. Every per-phase max still passes (phase-4 12405/14750); only the aggregate needed room. Total bumped 52200 -> 52700 at v14.1.0 after two more contracts landed: stack skill routing (Phase 3 pre-flight step 9) and worktree finalize (Phase 6 step 9). Compression came first, as always, and twice: 224 tokens out of Phase 3 by pointing its criteria-ledger and routing steps at their feature files instead of restating them, and 190 out of Phase 6 by moving the finalize contract into refs/features/worktree-finalize.md and leaving the invocation plus the exit-3 semantics. Both new contracts follow the pattern the earlier ones set: the phase doc carries the call and the decision, the feature file carries the reasoning, and the feature files are outside this budget because it loops only the eight phase-N-* keys. Every per-phase max still passes (phase-3 7677/8950, phase-6 5223/6150 and both under warn); only the aggregate needed room. Total bumped 52700 -> 52750 for the Phase 0 Step 3 branch-persistence correction: the step wrote the legacy `projects[].branches` while the TTL filter two sections below read `global.recentBranches`, and both spots named a `{name, lastUsed}` shape the schema rejects (`branch` required, `additionalProperties: false`), so the recent-branch picker option could never populate and a literal implementation would have failed prefs validation. Naming the right target, the right key and the legacy field to avoid costs 41 tokens over the one line it replaces. Compression came first and was applied three times to the replacement text itself, from 120 tokens down to 66, by moving the rationale out of the phase doc entirely: the reasoning now lives where it is enforced, in the migrate-prefs carry-forward comment and the smoke-pref-migration f7 block, leaving the phase doc with only the instruction. 50 was the smallest step that clears it; phase-0-init sits at 10893/12400, far under its own max, so this is purely an aggregate ceiling. v15.0.0: total 52750 -> 53100, the stack-skill tables in phase-1/2/4 now carry plugin-namespaced names (ai-<stack>-toolkit:<skill>) - functional prefixes, ~170 tokens."
 }

package/pipeline/scripts/README.md

@@ -82,13 +82,14 @@ 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 (45 `.mjs` files)
+## Node.js helpers (54 `.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
+- `eval-triage.mjs`  -  runs the 11 triage eval fixtures
+- `eval-mine-corpus.mjs`  -  manual maintainer CLI: mines `~/.claude/memory/multi-agent/<repo-slug>/triage-corpus.jsonl` from real runs into new triage eval fixtures (dev-only, excluded from the npm package; not part of `npm test`)
 - `gen-skills-index.mjs`  -  regenerates `pipeline/skills/shared/README.md` skill catalog
-- `migrate-prefs.mjs`  -  preference migration driver (v2.0.0 through v2.4.0)
+- `migrate-prefs.mjs`  -  preference migration driver (v2.0.0 through v2.6.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/_stack-routing.mjs

@@ -0,0 +1,79 @@
+// _stack-routing.mjs
+//
+// Single source of truth for "which marketplace plugin carries this external
+// skill". Extracted from build-stack-plugins.mjs so the skills-index builder can
+// stamp a `plugin` field per entry without duplicating the routing table - a
+// second copy would drift the first time a pattern changed, and the index would
+// namespace skills into a plugin that no longer carries them.
+//
+// Routing order is load-bearing and mirrors build-stack-plugins step 2:
+// COMMON_SKILLS first (explicit allowlist, wins over any pattern), then
+// APPLE_ONLY (Apple/Xcode-only names no pattern catches), then STACK_PATTERNS.
+// A skill may match several stack patterns; build-stack-plugins ships it to all
+// of them and --check-routing polices accidental multi-routing. routeSkill()
+// returns the full match list so callers can decide.
+
+export const COMMON_PLUGIN = "ai-common-toolkit";
+
+export const COMMON_SKILLS = [
+  "accessibility-compliance-accessibility-audit",
+  "firebase",
+  "humanizer",
+  "council",
+  "search-first",
+  "agent-introspection-debugging",
+  "skill-creator",
+  "backlog",
+  "localization-reuse-map",
+];
+
+// Apple/Xcode-only skills that match no stack pattern → iOS plugin only.
+export 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",
+];
+
+// 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.
+export const STACK_PATTERNS = {
+  "ai-ios-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-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-toolkit":
+    /(react-|nextjs-|typescript-|tailwind-|vue-|web-accessibility|web-performance|css-modern|web-testing|html-semantic)/i,
+};
+
+/**
+ * Which plugins carry this external skill, in routing order.
+ * @param {string} name - skill directory name
+ * @returns {string[]} plugin names; empty when unrouted
+ */
+export function routeSkill(name) {
+  if (COMMON_SKILLS.includes(name)) return [COMMON_PLUGIN];
+  if (APPLE_ONLY.includes(name)) return ["ai-ios-toolkit"];
+  const hits = [];
+  for (const [plugin, re] of Object.entries(STACK_PATTERNS)) {
+    if (re.test(name)) hits.push(plugin);
+  }
+  return hits;
+}

package/pipeline/scripts/audit-log-rotate.sh

@@ -57,7 +57,10 @@ if [ -s "$AUDIT_FILE" ]; then
   # event appended between the copy and the truncate.
   SPOOL="$AUDIT_DIR/.audit.rotate.$$"
   mv "$AUDIT_FILE" "$SPOOL"
-  : > "$AUDIT_FILE"
+  # touch, not truncate: a writer appending between the mv and this line
+  # recreates the live file, and `: >` would destroy that event. touch keeps
+  # whatever a racing writer already appended.
+  touch "$AUDIT_FILE"
   chmod 600 "$AUDIT_FILE" 2>/dev/null || true
 
   # Don't clobber a rotated file from earlier today (multiple invocations).

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

@@ -26,6 +26,7 @@
 import { readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { routeSkill } from "./_stack-routing.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const repoRoot = resolve(here, "..", "..");
@@ -92,11 +93,21 @@ for (const full of walkSkills(root)) {
     .map((s) => s.trim())
     .filter(Boolean);
 
+  // External skills reach Claude Code only through the marketplace plugins, so
+  // the index carries which plugin owns each one. `invokeAs` is the name a
+  // consumer must use: plugin-namespaced on Claude Code, bare elsewhere (the
+  // Copilot/Codex copies keep bare directory names). Routing comes from
+  // _stack-routing.mjs - the same table build-stack-plugins ships with.
+  const plugins = group === "external" ? routeSkill(name) : [];
+  const plugin = plugins[0] || null;
+
   entries.push({
     name,
     description,
     platform,
     group,
+    plugin,
+    invokeAs: plugin ? `${plugin}:${name}` : name,
     triggerKeywords: kws,
     triggerPaths: paths,
     relativePath: rel,

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

@@ -14,7 +14,7 @@
  * knowledge entries are regenerated.
  *
  * Routing uses the per-stack skill patterns (formerly carried by stack-swap.sh). Genuinely cross-stack
- * skills go to ai-common-engineering-toolkit (not into each stack plugin). Apple/
+ * skills go to ai-common-toolkit (not into each stack plugin). Apple/
  * Xcode-only vendored skills that match no stack pattern belong to iOS only.
  *
  * Usage:
@@ -34,6 +34,7 @@ import {
 } from "node:fs";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 
 const args = process.argv.slice(2);
 // Accepts both `--key value` and `--key=value`. The `=` form used to fall through to
@@ -51,54 +52,12 @@ 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",
-  "localization-reuse-map",
-];
-
-// 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",
-];
-
-// 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,
-};
+import {
+  COMMON_PLUGIN,
+  COMMON_SKILLS,
+  APPLE_ONLY,
+  STACK_PATTERNS,
+} from "./_stack-routing.mjs";
 
 const isDir = (p) => {
   try {
@@ -110,18 +69,23 @@ const isDir = (p) => {
 const listDirs = (p) => (existsSync(p) ? readdirSync(p).filter((n) => isDir(join(p, n))) : []);
 
 /**
- * Cheap content fingerprint for a skill directory: every file's relative path and
- * size. Enough to notice an edit without hashing megabytes on every run, and it is
- * only used to decide whether a version bump is warranted.
+ * Content fingerprint for a skill directory: every file's relative path and a
+ * hash of its bytes. A size-only fingerprint missed same-length edits, so a
+ * content update could ship without a version bump. The whole authoring tree
+ * is a few MB of markdown; hashing it per run costs milliseconds and is only
+ * used to decide whether a copy + version bump is warranted.
  */
 function treeFingerprint(dir) {
   const parts = [];
   const walk = (d, rel) => {
-    for (const e of readdirSync(d, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    for (const e of readdirSync(d, { withFileTypes: true }).sort((a, b) =>
+      a.name.localeCompare(b.name),
+    )) {
       const full = join(d, e.name);
       const r = rel ? `${rel}/${e.name}` : e.name;
       if (e.isDirectory()) walk(full, r);
-      else if (e.isFile()) parts.push(`${r}:${statSync(full).size}`);
+      else if (e.isFile())
+        parts.push(`${r}:${createHash("sha1").update(readFileSync(full)).digest("hex")}`);
     }
   };
   try {
@@ -156,7 +120,7 @@ for (const skill of allSkills) {
     continue;
   }
   if (APPLE_ONLY.includes(skill)) {
-    desired["ai-ios-engineering-toolkit"].add(skill);
+    desired["ai-ios-toolkit"].add(skill);
     continue;
   }
   let matched = false;
@@ -218,7 +182,8 @@ for (const [plugin, want] of Object.entries(desired)) {
   const toRemove = [...have].filter((s) => !want.has(s)).sort();
   const setChanged = toAdd.length > 0 || toRemove.length > 0;
 
-  // Re-copy EVERY wanted skill, not just the newly added ones.
+  // Compare EVERY wanted skill against the source, not just the newly added
+  // ones, and replace (rm + copy) rather than overlay.
   //
   // This used to copy only on a set change, which quietly broke the single-source
   // claim: editing a skill in shared/external left the plugin serving the old text
@@ -226,17 +191,20 @@ for (const [plugin, want] of Object.entries(desired)) {
   // seeing the plugin copy stay stale while the generator reported "all plugins up
   // to date".
   //
-  // cpSync overwrites, so a full re-copy is idempotent and cheap relative to a
-  // publish. Removals still need the explicit delete.
+  // The rm-before-copy matters too: cpSync overlays and never deletes, so a file
+  // REMOVED inside a still-wanted skill survived in every plugin copy forever -
+  // and because the overlay kept the orphan on both sides of the fingerprint
+  // comparison, the version was not bumped either.
   let contentChanged = false;
   if (!DRY) {
     if (!existsSync(kdir)) mkdirSync(kdir, { recursive: true });
     for (const s of want) {
       const from = join(EXTERNAL, s);
       const to = join(kdir, s);
-      const before = existsSync(to) ? treeFingerprint(to) : "";
+      if (treeFingerprint(from) === (existsSync(to) ? treeFingerprint(to) : "")) continue;
+      rmSync(to, { recursive: true, force: true });
       cpSync(from, to, { recursive: true });
-      if (treeFingerprint(to) !== before) contentChanged = true;
+      contentChanged = true;
     }
     for (const s of toRemove) rmSync(join(kdir, s), { recursive: true, force: true });
   }

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

@@ -24,7 +24,7 @@
 
 import { Buffer } from "node:buffer";
 import { execFileSync } from "node:child_process";
-import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
@@ -72,29 +72,44 @@ function versionFrom(manifest, pluginName) {
 function fromLocalClone(entry) {
   if (!entry.upstreamLocalClone) return null;
   const root = expandHome(entry.upstreamLocalClone);
-  const file =
+  const relFile =
     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;
+      ? `plugins/${entry.upstreamPlugin}/.claude-plugin/plugin.json`
+      : ".claude-plugin/marketplace.json";
 
-  // 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;
+  // Read the manifest from origin/main, never the checked-out worktree: a
+  // clone parked on an old feature branch reported stale versions as current,
+  // flagging correctly-bumped derivations as drifted.
   try {
-    const out = execFileSync("git", ["-C", root, "rev-list", "--count", "HEAD..@{u}"], {
+    const raw = execFileSync("git", ["-C", root, "show", `origin/main:${relFile}`], {
       encoding: "utf-8",
       stdio: ["ignore", "pipe", "ignore"],
-    }).trim();
-    behind = Number(out) || 0;
+    });
+    const version = versionFrom(JSON.parse(raw), entry.upstreamPlugin);
+    if (version) {
+      // origin/main is only as fresh as the last fetch. Surface fetch age so a
+      // months-old ref is not silently trusted.
+      let fetchAgeDays = null;
+      try {
+        const fetchHead = join(root, ".git", "FETCH_HEAD");
+        if (existsSync(fetchHead)) {
+          fetchAgeDays = Math.floor((Date.now() - statSync(fetchHead).mtimeMs) / 86_400_000);
+        }
+      } catch {
+        fetchAgeDays = null;
+      }
+      return { version, source: "local clone origin/main", authoritative: true, fetchAgeDays };
+    }
   } catch {
-    // No upstream branch configured, or not a git checkout at all.
-    behind = null;
+    // No origin/main ref (not a git checkout, or unfetched): fall through to
+    // the worktree file, which is better than nothing but never fresher.
   }
 
-  return { version, source: "local clone", authoritative: true, behind };
+  const file = join(root, relFile);
+  if (!existsSync(file)) return null;
+  const version = versionFrom(readJson(file), entry.upstreamPlugin);
+  if (!version) return null;
+  return { version, source: "local clone worktree", authoritative: true, fetchAgeDays: null };
 }
 
 function fromRepoApi(entry) {
@@ -161,46 +176,58 @@ for (const entry of entries) {
     continue;
   }
   const drifted = resolved.version !== entry.derivedFromVersion;
-  const status = drifted
-    ? "drift"
-    : resolved.authoritative
-      ? "up to date"
-      : "unverified (cache only)";
+  // An acknowledged drift is a conscious "port pending" decision, pinned to the
+  // upstream version it was made against: it stays visible but does not fail
+  // the gate, and the moment upstream moves past the pin it is plain drift
+  // again. The pin only counts against an AUTHORITATIVE resolution - a cache
+  // that happens to hold the pinned version proves nothing about upstream and
+  // must not silence the unverified state.
+  const acknowledged =
+    drifted && resolved.authoritative && entry.driftAcknowledged === resolved.version;
+  const status = acknowledged
+    ? "drift (acknowledged)"
+    : 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,
+    fetchAgeDays: resolved.fetchAgeDays ?? null,
     status,
   });
 }
 
 const drifted = rows.filter((r) => r.status === "drift").length;
+const acknowledged = rows.filter((r) => r.status === "drift (acknowledged)").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 },
+      { configured: rows.length, drifted, acknowledged, unverified, unreachable, entries: rows },
       null,
       2,
     ),
   );
 } else {
   for (const r of rows) {
-    const behind = r.cloneBehind ? ` [clone ${r.cloneBehind} behind its remote]` : "";
+    const age =
+      r.fetchAgeDays != null && r.fetchAgeDays > 7 ? ` [last fetch ${r.fetchAgeDays}d ago]` : "";
     console.log(
-      `  ${r.status === "up to date" ? "✓" : "✗"} ${r.plugin}: recorded ${r.from}, ` +
-        `upstream ${r.upstream ?? "?"} (${r.source})${behind} -> ${r.status}`,
+      `  ${r.status === "up to date" ? "✓" : r.status === "drift (acknowledged)" ? "!" : "✗"} ${r.plugin}: recorded ${r.from}, ` +
+        `upstream ${r.upstream ?? "?"} (${r.source})${age} -> ${r.status}`,
     );
   }
   console.log("");
   console.log(
-    `══ check-derived-drift: ${rows.length - drifted - unverified - unreachable} passed, ` +
-      `${drifted + unverified + unreachable} failed ══`,
+    `══ check-derived-drift: ${rows.length - drifted - unverified - unreachable} passed ` +
+      `(${acknowledged} acknowledged), ${drifted + unverified + unreachable} failed ══`,
   );
 }
 

package/pipeline/scripts/gc-worktrees.sh

@@ -125,7 +125,10 @@ done
 
 # 3. Gitlink residue in the index ("Subproject commit" entries under
 #    .worktrees/ from a pre-guard `git add -A`).
-gitlinks=$(git -C "$REPO" ls-files -s -- .worktrees 2>/dev/null | awk '$1 == "160000" { print $4 }')
+# Path is the tab-separated second field ("mode sha stage\tpath"); splitting on
+# whitespace truncated any path containing a space and the follow-up
+# `git rm --ignore-unmatch` exited 0 on the phantom, reporting a false success.
+gitlinks=$(git -C "$REPO" ls-files -s -- .worktrees 2>/dev/null | awk -F'\t' '$1 ~ /^160000 / { print $2 }')
 if [ -n "$gitlinks" ]; then
   while IFS= read -r path; do
     [ -z "$path" ] && continue

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

@@ -82,7 +82,7 @@ md += `**Total:** ${total} skills (${breakdown}). Auto-generated by \`scripts/ge
 md += `## Directory layout\n\n`;
 md += `- **\`core/\`**  -  ${counts.core} \`multi-agent*\` orchestration skills that are pipeline-critical. Edits here are core-code changes.\n`;
 md += `- **\`external/\`**  -  ${counts.external} iOS / Android / generic skills imported from the upstream skill library. Mirrors of third-party guidance.\n`;
-md += `- Install destination stays flat: both trees flatten into \`~/.claude/skills/\` and \`~/.copilot/skills/\`. See ADR-0006 for the rationale.\n\n`;
+md += `- Install destinations (ADR-0009): Claude Code gets NO local copy of \`external/\` - it loads those skills from the \`multi-agent-plugins\` marketplace, namespaced (\`ai-<stack>-toolkit:<name>\`); only the two compliance catalogs from \`core/\` land in \`~/.claude/skills/\`. Copilot CLI and Codex CLI receive a flat copy filtered to the enabled stacks. \`external/\` remains the single authoring source that \`build-stack-plugins.mjs\` publishes from.\n\n`;
 md += `Source layout is logical grouping only  -  skill discovery at runtime is unchanged.\n\n`;
 md += `## Categories\n\n`;
 for (const k of order) {

package/pipeline/scripts/match-skills.mjs

@@ -52,6 +52,10 @@ function defaultIndexCandidates() {
   const repoRoot = resolve(here, "..", ".."); // <repo> when here is <repo>/pipeline/scripts
   return [
     join(installRoot, "skills", ".skills-index.json"),
+    // Codex CLI keeps skills under multi-agent-refs/skills (install/codex.mjs
+    // writes the index there); without this candidate every dynamic-skill
+    // dispatch on Codex exited 1 with "cannot read index".
+    join(installRoot, "multi-agent-refs", "skills", ".skills-index.json"),
     join(repoRoot, "pipeline", "skills", ".skills-index.json"),
   ];
 }
@@ -202,13 +206,19 @@ for (const entry of index.entries) {
 results.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
 const top = results.slice(0, opts.limit);
 
+// On Claude Code an external skill resolves only through its marketplace plugin,
+// so surface `invokeAs` (plugin-namespaced) as the primary name. Old indexes
+// without the field fall back to the bare name - same behaviour as before.
 if (opts.json) {
-  process.stdout.write(JSON.stringify({ task: taskText, matches: top }, null, 2) + "\n");
+  const matches = top.map((m) => ({ ...m, invokeAs: m.invokeAs || m.name }));
+  process.stdout.write(JSON.stringify({ task: taskText, matches }, null, 2) + "\n");
 } else {
   for (const m of top) {
     const tag = `[${m.group}${m.platform ? "/" + m.platform : ""}]`;
     const desc = (m.description || "").slice(0, 80);
-    console.log(`${String(m.score).padStart(3)} ${m.name.padEnd(32)} ${tag.padEnd(18)} ${desc}`);
+    console.log(
+      `${String(m.score).padStart(3)} ${(m.invokeAs || m.name).padEnd(46)} ${tag.padEnd(18)} ${desc}`,
+    );
   }
   if (top.length === 0) console.log("(no skills matched)");
 }

package/pipeline/scripts/migrate-prefs.mjs

@@ -13,12 +13,13 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
+import { fileURLToPath } from "node:url";
 
 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.5.0";
+const TARGET_VERSION = "2.6.0";
 
 const USAGE = "Usage: migrate-prefs.mjs [--dry-run] [--file <path>]";
 
@@ -75,7 +76,7 @@ function defaultSettings() {
  * @returns {Set<string>}
  */
 function readMigratableVersions(target) {
-  const here = path.dirname(new URL(import.meta.url).pathname);
+  const here = path.dirname(fileURLToPath(import.meta.url));
   const candidates = [
     path.join(here, "..", "schemas", "prefs.schema.json"),
     path.join(here, "..", "..", "pipeline", "schemas", "prefs.schema.json"),
@@ -93,7 +94,11 @@ function readMigratableVersions(target) {
   }
   // Schema unreadable: refusing to migrate would be worse than migrating from a
   // version this build cannot enumerate, so fall back to the known history.
-  return new Set(["2.0.0", "2.1.0", "2.2.0", "2.3.0", "2.4.0"]);
+  // Every released schemaVersion below TARGET_VERSION belongs here - the
+  // 2.4.0->2.5.0 and 2.5.0->2.6.0 bumps both shipped without extending it,
+  // which made a schema-less install throw "unknown schemaVersion" on a prefs
+  // file one version behind.
+  return new Set(["2.0.0", "2.1.0", "2.2.0", "2.3.0", "2.4.0", "2.5.0"]);
 }
 
 function defaultKeychainMapping() {
@@ -297,7 +302,9 @@ function migrate(prefs) {
       seeded += 1;
     }
     if (seeded > 0) {
-      changes.push(`seeded ${seeded} recentBranches entr${seeded === 1 ? "y" : "ies"} for ${projectKey} from legacy projects[].branches`);
+      changes.push(
+        `seeded ${seeded} recentBranches entr${seeded === 1 ? "y" : "ies"} for ${projectKey} from legacy projects[].branches`,
+      );
     }
   }
   if (!Array.isArray(out.global.recentGroups)) {
@@ -332,27 +339,32 @@ function migrate(prefs) {
     out.global.skillConformance.blockOnCoverageGap = false;
     changes.push("added skillConformance.blockOnCoverageGap=false (report, do not halt)");
   }
-  // v2.5.0: /multi-agent:finish became /multi-agent:ship, and its autoFix key -
-  // referenced by the command spec since it shipped but never declared in the
-  // schema - is declared here. Carry any value the user had rather than reset it.
-  if (!out.global.ship || typeof out.global.ship !== "object") {
-    out.global.ship = {};
-    changes.push("added ship (v2.5.0  -  /multi-agent:finish renamed to :ship)");
-  }
-  if (typeof out.global.ship.autoFix !== "boolean") {
-    const legacyAutoFix = out.global.finish?.autoFix;
-    out.global.ship.autoFix = typeof legacyAutoFix === "boolean" ? legacyAutoFix : false;
+  // Rename chain for the pipeline-tail command: /multi-agent:finish (pre-v2.5.0)
+  // -> :ship (v2.5.0) -> :resume-local (current). The autoFix value survives every
+  // hop - carry whichever legacy block still holds one rather than reset it.
+  if (!out.global.resumeLocal || typeof out.global.resumeLocal !== "object") {
+    out.global.resumeLocal = {};
+    changes.push("added resumeLocal (/multi-agent:ship renamed to :resume-local)");
+  }
+  if (typeof out.global.resumeLocal.autoFix !== "boolean") {
+    const legacyAutoFix =
+      typeof out.global.ship?.autoFix === "boolean"
+        ? out.global.ship.autoFix
+        : out.global.finish?.autoFix;
+    out.global.resumeLocal.autoFix = typeof legacyAutoFix === "boolean" ? legacyAutoFix : false;
     changes.push(
       typeof legacyAutoFix === "boolean"
-        ? "moved finish.autoFix -> ship.autoFix (value preserved)"
-        : "added ship.autoFix=false",
+        ? "moved ship/finish autoFix -> resumeLocal.autoFix (value preserved)"
+        : "added resumeLocal.autoFix=false",
     );
   }
-  if (out.global.finish && typeof out.global.finish === "object") {
-    delete out.global.finish.autoFix;
-    if (Object.keys(out.global.finish).length === 0) {
-      delete out.global.finish;
-      changes.push("removed obsolete finish block (renamed to ship)");
+  for (const legacy of ["ship", "finish"]) {
+    if (out.global[legacy] && typeof out.global[legacy] === "object") {
+      delete out.global[legacy].autoFix;
+      if (Object.keys(out.global[legacy]).length === 0) {
+        delete out.global[legacy];
+        changes.push(`removed obsolete ${legacy} block (renamed to resumeLocal)`);
+      }
     }
   }
   if (!out.global.serviceStatus) {