@mmerterden/multi-agent-pipeline 14.2.1 → 15.0.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/_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).
@@ -80,6 +83,16 @@ if [ -s "$AUDIT_FILE" ]; then
   if [ -f "$ROTATED" ] && command -v gzip >/dev/null 2>&1; then
     gzip -f "$ROTATED" 2>/dev/null || true
   fi
+
+  # gzip preserves the source file's mtime by default, so an archive rotated
+  # from log content already older than KEEP_DAYS would carry that same old
+  # mtime - and the retention sweep below deletes anything past KEEP_DAYS,
+  # so a just-created archive could be purged in this very run before ever
+  # being read. Retention has to count from rotation time, not from the age
+  # of the content it archived. gzip -f removes the plain file on success, so
+  # only touch whichever of the two actually exists.
+  [ -f "$ROTATED.gz" ] && touch "$ROTATED.gz"
+  [ -f "$ROTATED" ] && touch "$ROTATED"
 fi
 
 # Drop archives older than KEEP_DAYS

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,53 +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",
-];
-
-// 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 {
@@ -109,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 {
@@ -134,7 +99,13 @@ function treeFingerprint(dir) {
 // --- 1. enumerate authoring source ---------------------------------------
 if (!existsSync(EXTERNAL)) {
   console.error(`source not found: ${EXTERNAL}`);
-  process.exit(0);
+  // --check-routing exists so CI can gate routing correctness without a
+  // checkout of the plugins repo, reading only this authoring source. Exiting
+  // 0 here regardless of --check-routing meant a misconfigured/missing
+  // source (wrong --pipeline path, an incomplete CI checkout) reported the
+  // gate as passing having audited nothing - the exact silent-green failure
+  // the gate exists to prevent elsewhere.
+  process.exit(args.includes("--check-routing") ? 1 : 0);
 }
 const allSkills = listDirs(EXTERNAL);
 
@@ -149,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;
@@ -211,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
@@ -219,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";
 
@@ -38,6 +38,18 @@ const CACHE = process.env.DERIVED_DRIFT_CACHE || join(homedir(), ".claude", "plu
 
 const expandHome = (p) => p.replace(/^\$HOME\b|^~/, homedir());
 
+// Array.prototype.sort() with no comparator sorts these lexicographically
+// ("10.0.0" < "9.0.0" as strings), so a directory listing with both would
+// treat 9.0.0 as newer.
+function semverCompare(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] !== pb[i]) return pa[i] - pb[i];
+  }
+  return 0;
+}
+
 function readJson(path) {
   try {
     return JSON.parse(readFileSync(path, "utf-8"));
@@ -60,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) {
@@ -116,7 +143,7 @@ function fromCache(entry) {
   if (!existsSync(dir)) return null;
   const versions = readdirSync(dir)
     .filter((d) => /^\d+\.\d+\.\d+$/.test(d))
-    .sort();
+    .sort(semverCompare);
   const newest = versions[versions.length - 1];
   return newest
     ? { version: newest, source: "plugin cache", authoritative: false, behind: null }
@@ -149,46 +176,55 @@ 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.
+  const acknowledged = drifted && 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/diff-explain.mjs

@@ -117,6 +117,44 @@ function resolveBase() {
   die("no base ref found (tried origin/main, main, origin/master, master)  -  pass --base");
 }
 
+// git quotes a `diff --git` path (core.quotePath, on by default) whenever it
+// has a non-ASCII byte or other unusual character - e.g. a Turkish filename
+// renders as `diff --git "a/\303\226deme.swift" "b/\303\226deme.swift"`, not
+// the bare a/...b/... form. The plain regex this replaced never matched that
+// line at all, so every non-ASCII-named file dropped out of the explanation.
+const DIFF_GIT_QUOTED_RE = /^diff --git "a\/((?:[^"\\]|\\.)*)" "b\/((?:[^"\\]|\\.)*)"$/;
+const DIFF_GIT_UNQUOTED_RE = /^diff --git a\/(.+?) b\/(.+)$/;
+
+function unquoteGitPath(s) {
+  const bytes = [];
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === "\\") {
+      const octal = s.slice(i + 1, i + 4);
+      if (/^[0-7]{3}$/.test(octal)) {
+        bytes.push(parseInt(octal, 8));
+        i += 3;
+        continue;
+      }
+      const simple = { "\\": 92, '"': 34, t: 9, n: 10, r: 13 };
+      const next = s[i + 1];
+      if (next in simple) {
+        bytes.push(simple[next]);
+        i += 1;
+        continue;
+      }
+    }
+    bytes.push(s.charCodeAt(i));
+  }
+  return Buffer.from(bytes).toString("utf-8");
+}
+
+function matchDiffGitHeader(line) {
+  const q = line.match(DIFF_GIT_QUOTED_RE);
+  if (q) return unquoteGitPath(q[2]);
+  const u = line.match(DIFF_GIT_UNQUOTED_RE);
+  return u ? u[2] : null;
+}
+
 /**
  * Parse unified diff into a map of {path: [{ oldStart, newStart, lines: [...] }]}
  * Each hunk's `lines` retains the leading +/- /space prefix.
@@ -127,9 +165,9 @@ function parseDiff(raw) {
   let currentHunks = null;
   let currentHunk = null;
   for (const line of raw.split("\n")) {
-    const fileMatch = /^diff --git a\/(.+?) b\/(.+)$/.exec(line);
-    if (fileMatch) {
-      currentPath = fileMatch[2];
+    const fileMatch = matchDiffGitHeader(line);
+    if (fileMatch !== null) {
+      currentPath = fileMatch;
       currentHunks = [];
       files[currentPath] = currentHunks;
       currentHunk = null;