@mmerterden/multi-agent-pipeline 12.6.0 → 12.8.0

package/docs/recovery-guide.md

@@ -1,10 +1,10 @@
-# Recovery Guide — What to Do When Things Break
+# Recovery Guide - What to Do When Things Break
 
 Every failure mode in the pipeline has a deterministic recovery path. This
-guide is a single place to look up "X failed — now what?" instead of chasing
+guide is a single place to look up "X failed - now what?" instead of chasing
 the answer across `modes.md`, `operations.md`, and the individual phase specs.
 
-## Fast Triage — Which Path Do I Need?
+## Fast Triage - Which Path Do I Need?
 
 | Symptom                                                 | Jump to                                         |
 | ------------------------------------------------------- | ----------------------------------------------- |
@@ -49,15 +49,15 @@ so `resume` continues in autopilot.
 
 Phase 3 retries the build up to **3 times** on each TDD cycle's green step. On
 the 4th consecutive failure the pipeline **pauses** (even in autopilot) and
-surfaces the error. Autopilot does not loop infinitely — this is intentional.
+surfaces the error. Autopilot does not loop infinitely - this is intentional.
 
 Path forward:
 
-1. Read the last 20 lines of `agent-log.md` — the root cause is usually there.
+1. Read the last 20 lines of `agent-log.md` - the root cause is usually there.
 2. If the failure is environmental (missing Xcode sim, wrong JDK), fix the
-   environment and `resume` — the 3-retry counter resets.
+   environment and `resume` - the 3-retry counter resets.
 3. If the failure is logic (compile error in the generated code), edit the
-   offending file in the worktree, then `resume` — Phase 3 re-runs build.
+   offending file in the worktree, then `resume` - Phase 3 re-runs build.
 4. If the task itself is wrong-shaped (Phase 2 plan is infeasible), `kill` and
    restart with a better-scoped prompt.
 
@@ -76,14 +76,14 @@ Path forward:
 
 If exit 1 fires twice (fallback path):
 
-1. The pipeline logs `Phase 4: triage failed twice — fallback, all findings accepted as blocking`.
+1. The pipeline logs `Phase 4: triage failed twice - fallback, all findings accepted as blocking`.
 2. All raw findings loop back into Phase 3 as if they were all real blockers.
-3. This is intentionally conservative — we'd rather over-fix than skip
+3. This is intentionally conservative - we'd rather over-fix than skip
    something real. You can manually mark noise in the Phase 6 PR description.
 
 ## Over-Rejection Guard
 
-Exit code 2 means triage rejected >80% of findings, which is suspicious — it
+Exit code 2 means triage rejected >80% of findings, which is suspicious - it
 often indicates the triage prompt lost the task context. Pipeline halts and
 asks a human to look at the raw findings vs triage output.
 
@@ -92,9 +92,9 @@ asks a human to look at the raw findings vs triage output.
 - Open `agent-log.md`, find the triage invocation.
 - Compare raw findings (logged) with rejected items.
 - If the rejections are correct, run `resume` with `--accept-overrejection` (Phase 4 re-enters validation with the guard soft-failed).
-- If not, run `resume` — Phase 4 re-runs triage with the guard still active.
+- If not, run `resume` - Phase 4 re-runs triage with the guard still active.
 
-Autopilot behavior: logs the warning, accepts the triage output, continues —
+Autopilot behavior: logs the warning, accepts the triage output, continues -
 the autopilot contract values throughput over human-in-loop.
 
 ---
@@ -104,13 +104,13 @@ the autopilot contract values throughput over human-in-loop.
 Phase 0 creates `.worktrees/{jiraId}`. If that path already exists:
 
 ```bash
-# Option A — resume the previous run
+# Option A - resume the previous run
 /multi-agent:resume #N
 
-# Option B — delete the stale worktree
+# Option B - delete the stale worktree
 /multi-agent:kill #N        # asks to confirm, removes worktree + branch
 
-# Option C — manual cleanup
+# Option C - manual cleanup
 git worktree list                        # find stale entries
 git worktree remove .worktrees/{jiraId}  # safe if no uncommitted work
 git worktree prune                       # drop any dead refs
@@ -134,13 +134,13 @@ at Phase 0 load. If validation fails:
 1. Back up the file: `cp agent-state.json agent-state.json.bak`.
 2. Try `node pipeline/scripts/validate-schemas.mjs` to identify the violation.
 3. Common fixes:
-   - **Missing required field** — add the default per the schema description.
-   - **Bad enum value** — check `phase.status` and `taskType` enums.
-   - **`lastUpdated` not ISO-8601** — regenerate with `date -u +"%Y-%m-%dT%H:%M:%SZ"`.
+   - **Missing required field** - add the default per the schema description.
+   - **Bad enum value** - check `phase.status` and `taskType` enums.
+   - **`lastUpdated` not ISO-8601** - regenerate with `date -u +"%Y-%m-%dT%H:%M:%SZ"`.
 4. If the file is irrecoverable, `kill` the task and restart. State loss for
    a single task is recoverable; corruption bleeding into the next run is not.
 
-To prevent future corruption, use the atomic writer — never write state with
+To prevent future corruption, use the atomic writer - never write state with
 shell `echo > agent-state.json`:
 
 ```bash
@@ -177,7 +177,7 @@ files for hardcoded secrets and blocks the commit if any are found.
 
 If the hit is a **real secret**:
 
-1. `git reset HEAD {file}` — unstage.
+1. `git reset HEAD {file}` - unstage.
 2. Move the secret to env / keychain / secret manager.
 3. Re-stage the cleaned file and commit.
 
@@ -186,7 +186,7 @@ If the hit is a **false positive** (e.g. an example string in docs):
 1. Rename the variable so the pattern doesn't match
    (`EXAMPLE_API_KEY` not `api_key=`).
 2. Or, for documentation, break the pattern with a zero-width marker.
-3. Never `--no-verify` to bypass — that's how real secrets slip through.
+3. Never `--no-verify` to bypass - that's how real secrets slip through.
 
 ---
 
@@ -219,7 +219,7 @@ cat .worktrees/{id}/agent-state.json | grep status
 is missing on disk. Phase 6 logs an error, sets
 `state.instructionDrivenFallback=true`, and uses the standard commit path.
 
-This is rarely fatal — usually the instruction file was removed between
+This is rarely fatal - usually the instruction file was removed between
 sessions or the wrong path was cached. To recover cleanly:
 
 1. Check whether the intended instruction file still exists somewhere:
@@ -257,7 +257,7 @@ git push origin v{version} --force       # only if tag was never consumed
 ```
 
 If the tag has already been consumed (release CI ran), bump to the next patch
-version and tag fresh — never re-publish a consumed version.
+version and tag fresh - never re-publish a consumed version.
 
 ---
 
@@ -271,7 +271,7 @@ with `fatal: not a git repository`.
 Fix:
 
 ```bash
-# Inspect git's worktree registry — the source of truth
+# Inspect git's worktree registry - the source of truth
 git worktree list --porcelain | grep -A 2 "<task-id>"
 
 # If the path is missing but git still tracks it (common when a stale .git/worktrees/<id>/
@@ -301,8 +301,8 @@ safest path is `kill` the task (preserves logs + branch) and restart with
 
 ## Tracker State Corruption (v8.0.0)
 
-`phase-tracker.sh render` returns garbage — duplicate phases, missing
-elapsed/token fields, JSON parse errors — even though the task is healthy.
+`phase-tracker.sh render` returns garbage - duplicate phases, missing
+elapsed/token fields, JSON parse errors - even though the task is healthy.
 Usually caused by a manual edit to `tracker-state.json` or a partial write
 mid-update.
 
@@ -330,7 +330,7 @@ grep -E '^## Phase [0-9]+:' "$HOME/.claude/logs/multi-agent/<project>/<task-id>/
 done
 ```
 
-Token counts are not recoverable from the log — those start fresh after a
+Token counts are not recoverable from the log - those start fresh after a
 reinit. A footnote in `agent-log.md` documenting the rebuild is good practice.
 
 ---
@@ -362,7 +362,7 @@ echo "$NEW_TOKEN" | secret-tool store --label="$LABEL" account "$ACCOUNT" servic
 # 2. Sanity-check the doctor reports the new token's prefix
 bash pipeline/lib/credential-store.sh doctor
 
-# 3. Resume the pipeline — Phase 6/7 re-resolve the token on each invocation,
+# 3. Resume the pipeline - Phase 6/7 re-resolve the token on each invocation,
 #    so no state edit is required.
 /multi-agent:resume <task-id>
 ```
@@ -370,7 +370,7 @@ bash pipeline/lib/credential-store.sh doctor
 If the rotated token was Vercel, also run `bash pipeline/lib/vercel-deploy.sh
 doctor` to confirm the wrapper sees the new value before retrying any deploy.
 
-**Never** copy-paste the new token into a `--token=` argv to test it — see
+**Never** copy-paste the new token into a `--token=` argv to test it - see
 `pipeline/lib/vercel-deploy.sh` for why this is forbidden.
 
 ---
@@ -378,12 +378,12 @@ doctor` to confirm the wrapper sees the new value before retrying any deploy.
 ## Author Rewrite + Tag Re-Sync (v8.0.0)
 
 A series of commits (and any tags pointing at them) were authored under the
-wrong identity — typically because someone passed `git -c user.email=…` or
+wrong identity - typically because someone passed `git -c user.email=...` or
 the repo-local config drifted. Vercel / npm / GitHub team-membership gates
 then reject the push because the author email is not a recognized contributor.
 
 This is the v7.9.1 release-window incident verbatim: 7 commits across
-v7.7.0–v7.9.1 plus 4 annotated tags shipped with the wrong author. Recovery
+v7.7.0-v7.9.1 plus 4 annotated tags shipped with the wrong author. Recovery
 required a rebase + retag dance.
 
 ```bash
@@ -396,7 +396,7 @@ git config user.name  "You"
 
 # 2. Find the first wrong commit (the one BEFORE the rebase rewrites everything):
 git log --format='%h %ae %s' main..HEAD | grep -i "wrong-email-pattern" | tail -1
-# Grab its parent SHA — that's your --onto target.
+# Grab its parent SHA - that's your --onto target.
 PARENT_OF_FIRST_WRONG=<sha>
 
 # 3. Rebase with --reset-author to rewrite every commit since that point.
@@ -419,13 +419,13 @@ NEW_SHA=$(git log --format=%H --grep="<commit-subject-or-marker>" -1)
 git tag -d "$TAG"
 git tag -a "$TAG" "$NEW_SHA" -m "$(git tag -l --format='%(contents)' "$TAG-old" 2>/dev/null || echo "$TAG release")"
 
-# 6b. Remote tag — DELETE then PUSH (no atomic option for tag content rewrite):
+# 6b. Remote tag - DELETE then PUSH (no atomic option for tag content rewrite):
 git push origin :refs/tags/"$TAG"
 git push origin "$TAG"
 
 # 7. If a CI release pipeline already consumed the OLD tag SHA (npm publish,
 #    GitHub Release creation), the published artifact stays attached to the
-#    deleted SHA. You CANNOT rewrite published packages — bump the patch
+#    deleted SHA. You CANNOT rewrite published packages - bump the patch
 #    version and ship a fresh release instead. Document the orphan in the
 #    CHANGELOG with a "yanked" note.
 ```
@@ -438,7 +438,7 @@ new SHA, or accept the orphan and document it.
 **npm publish gotcha:** if `npm publish` ran against the wrong-author tag,
 the package is permanently anchored to that SHA on the registry. Bump the
 patch version (`npm version patch --no-git-tag-version`), commit, push,
-publish — never `npm unpublish` (registry blocks unpublish for stable
+publish - never `npm unpublish` (registry blocks unpublish for stable
 versions).
 
 ---
@@ -452,9 +452,9 @@ Decision tree:
 
 | Condition | Safe action |
 |---|---|
-| Remote ahead — someone pushed to the same branch | `git pull --rebase origin <branch>`, replay the commit, retry push |
-| Hook rejected (lint / signing / size) | Fix locally, amend or new commit, retry push — NEVER `--no-verify` |
-| Branch protection (review count) | Push to a new branch with `-u`, open PR — do NOT `--force` |
+| Remote ahead - someone pushed to the same branch | `git pull --rebase origin <branch>`, replay the commit, retry push |
+| Hook rejected (lint / signing / size) | Fix locally, amend or new commit, retry push - NEVER `--no-verify` |
+| Branch protection (review count) | Push to a new branch with `-u`, open PR - do NOT `--force` |
 | Author rewrite needed (wrong identity, see `feedback_git_author_repo_local.md`) | `git rebase --reset-author`, `git push --force-with-lease`, NOT `--force` |
 
 Force-with-lease is the only acceptable force variant: it refuses to push if
@@ -463,7 +463,7 @@ overwrites their work.
 
 Bitbucket-specific: a force-push wipes default reviewers if the PR description
 PUT happens before reviewers re-attach. The `channels.md` adapter's
-reviewer-preserving payload handles this — never `gh pr edit --body` on a
+reviewer-preserving payload handles this - never `gh pr edit --body` on a
 Bitbucket PR after a force-push without re-reading the reviewer list first.
 
 ---

package/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * multi-agent-pipeline — 8-phase AI development pipeline
+ * multi-agent-pipeline - 8-phase AI development pipeline
  *
  * Supports: Claude Code, Copilot CLI
  * Install: npx @mmerterden/multi-agent-pipeline install
@@ -45,7 +45,7 @@ if (command === "--version" || command === "-v" || command === "version") {
   });
 } else if (command === "help") {
   console.log(`
-  multi-agent-pipeline — 8-phase AI development pipeline
+  multi-agent-pipeline - 8-phase AI development pipeline
 
   Install:
     npx @mmerterden/multi-agent-pipeline install              Install for Claude Code (default)
@@ -53,7 +53,7 @@ if (command === "--version" || command === "-v" || command === "version") {
     npx @mmerterden/multi-agent-pipeline install --all        Both Claude + Copilot
     npx @mmerterden/multi-agent-pipeline install --link       Use symlinks (saves tokens, dev mode)
 
-  Uninstall (token-preserving — Keychain/Credential Manager untouched):
+  Uninstall (token-preserving - Keychain/Credential Manager untouched):
     npx @mmerterden/multi-agent-pipeline uninstall            Interactive: remove from all installed targets
     npx @mmerterden/multi-agent-pipeline uninstall --yes      Skip prompt
     npx @mmerterden/multi-agent-pipeline uninstall --dry-run  Report what would be removed
@@ -71,7 +71,7 @@ if (command === "--version" || command === "-v" || command === "version") {
 
   After installation:
     Claude Code:  /multi-agent "MOBILE-123"
-    Copilot CLI:  Describe your task naturally — pipeline instructions are loaded
+    Copilot CLI:  Describe your task naturally - pipeline instructions are loaded
 
   More info: https://github.com/mmerterden/multi-agent-pipeline
   `);

package/install/_common.mjs

@@ -2,7 +2,7 @@
  * Shared filesystem helpers for install/* modules.
  *
  * These primitives are 1:1 ports of the helpers that lived inline in the
- * pre-v8.0.0 monolithic install.js. Behaviour MUST stay byte-equivalent —
+ * pre-v8.0.0 monolithic install.js. Behaviour MUST stay byte-equivalent -
  * the install layout smoke test (smoke-install-layout.sh) compares before/after
  * trees and fails on any drift.
  *
@@ -166,15 +166,9 @@ export function copyDir(src, dest, opts = {}) {
     filter: (source) => {
       // Normalize to forward slashes so exclude patterns (written posix-style)
       // also match on win32, where cpSync hands back backslash paths.
-      const rel = source
-        .slice(src.length)
-        .split("\\")
-        .join("/")
-        .replace(/^\//, "");
+      const rel = source.slice(src.length).split("\\").join("/").replace(/^\//, "");
       return !exclude.some((pat) =>
-        typeof pat === "string"
-          ? rel === pat || rel.startsWith(pat + "/")
-          : pat.test(rel),
+        typeof pat === "string" ? rel === pat || rel.startsWith(pat + "/") : pat.test(rel),
       );
     },
   });
@@ -214,7 +208,7 @@ export function symlinkDir(src, dest) {
 /**
  * Remove `multi-agent-*` skill directories from the given skills root.
  *
- * Used on the Claude Code side only — these skills duplicate the
+ * Used on the Claude Code side only - these skills duplicate the
  * `/multi-agent:*` slash commands living under `~/.claude/commands/multi-agent/`,
  * causing the slash-command picker to show two identical entries per command.
  * Copilot CLI has no slash-command infrastructure, so these skills stay there.
@@ -245,6 +239,54 @@ export function pruneLegacyMultiAgentSkills(skillsDir) {
   return removed;
 }
 
+/**
+ * Trees an older installer created and no current one manages.
+ *
+ * A tree that stops being copied does NOT stop existing: the wipe-before-copy
+ * pattern only runs for trees the installer still writes, so dropping one from
+ * the installer leaves whatever it last wrote on every existing machine forever.
+ *
+ * `eval/` is the case that prompted this. An older version copied the eval
+ * corpora into `~/.claude/eval/`; the harnesses that read them are maintainer CI
+ * tooling and no longer ship, so neither installer references `eval` any more and
+ * neither did uninstall - 31 stale files sat there with nothing left that could
+ * ever read or remove them.
+ *
+ * @type {ReadonlyArray<{dir: string, reason: string}>}
+ */
+export const ABANDONED_TREES = Object.freeze([
+  {
+    dir: "eval",
+    reason: "eval corpora; the harnesses that read them are maintainer-only and no longer ship",
+  },
+]);
+
+/**
+ * Remove trees an older install left behind under `root`.
+ *
+ * @param {string} root e.g. `$HOME/.claude`
+ * @returns {number} directories removed
+ */
+export function pruneAbandonedTrees(root) {
+  let removed = 0;
+  for (const { dir, reason } of ABANDONED_TREES) {
+    const target = join(root, dir);
+    if (!existsSync(target)) continue;
+    if (dryRun) {
+      console.log(`    [dry-run] would remove abandoned tree ${target} (${reason})`);
+      removed++;
+      continue;
+    }
+    try {
+      rmSync(target, { recursive: true, force: true });
+      removed++;
+    } catch {
+      /* non-fatal - a leftover tree must never fail an install */
+    }
+  }
+  return removed;
+}
+
 /**
  * Copy a single file, honouring dry-run mode.
  * @param {string} src
@@ -303,7 +345,7 @@ export function countFiles(dir) {
 }
 
 /**
- * Wipe a managed directory tree before copy. Non-fatal on permission errors —
+ * Wipe a managed directory tree before copy. Non-fatal on permission errors -
  * surfaces as a follow-up copy-over with stale entries kept, which is still
  * better than a hard install failure.
  *

package/install/_copilot-instructions.mjs

@@ -1,5 +1,5 @@
 /**
- * Copilot CLI instructions block — read from a Markdown source file.
+ * Copilot CLI instructions block - read from a Markdown source file.
  *
  * Pre-v8.0.0 (and through the v8.0.0 initial split) this module was 224
  * lines of `content += "..."` string concatenation. v8.0.0 follow-up moved
@@ -8,7 +8,7 @@
  * prettier, diffs cleanly) instead of escaped JavaScript template literals.
  *
  * The smoke `smoke-multi-repo-integration.sh` greps this module's output
- * for canonical strings — that contract is preserved because we still
+ * for canonical strings - that contract is preserved because we still
  * expose `generateCopilotInstructions()` with the same return shape.
  *
  * @module install/_copilot-instructions

package/install/_dev-only-files.mjs

@@ -1,18 +1,138 @@
 /**
- * Dev-only files excluded from end-user installs.
+ * Dev-only files excluded from end-user installs and from the published tarball.
  *
- * These reference the maintainer's private upstream and contain personal data
- * (org names, hostnames, emails) on the `from:` side of substitution rules.
- * End users never run them, so we keep them out of `~/.claude/scripts/` and
- * `~/.copilot/scripts/`.
+ * Two separate reasons live here, and they must not be conflated:
+ *
+ *   1. LEAK: the file references the maintainer's private upstream or carries
+ *      personal data (org names, hostnames, emails) on the `from:` side of a
+ *      substitution rule. Shipping it is a disclosure, not just noise.
+ *
+ *   2. MAINTAINER CI: the file is a repository gate. It resolves the repo root
+ *      as `dirname($0)/../..` and reads `package.json` / `install.js` /
+ *      `node_modules` / the git tree. In an install layout that path is `$HOME`,
+ *      so the script reports things like `FAIL: install.js missing` - a green
+ *      repo check that reads as a broken installation to whoever ran it.
+ *      Measured before this list existed: of 117 installed smoke scripts, 100
+ *      failed that way and 17 passed only by accident of not needing the repo.
+ *
+ * Reason 2 is why the default for `smoke-*.sh` is EXCLUDE. A smoke ships only
+ * when a command actually tells a user to run it - that set is CONSUMER_SMOKES
+ * below, and `smoke-consumer-smoke-surface.sh` fails if the two drift apart.
  *
  * @module install/_dev-only-files
  */
 
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Smoke suites an end user is instructed to run, and which therefore must work
+ * from an installed layout (`~/.claude/scripts/`) as well as from the repo.
+ *
+ * `/multi-agent:update` runs both as its post-update verification. Anything
+ * added here MUST resolve its paths through `_smoke-root.sh`, never through a
+ * bare `dirname($0)/../..`.
+ */
+export const CONSUMER_SMOKES = Object.freeze([
+  "smoke-schema-validation.sh",
+  "smoke-cross-cli-behavior.sh",
+]);
+
+/**
+ * Every `smoke-*.sh` that is NOT in CONSUMER_SMOKES. Expressed as one regex so a
+ * newly added smoke is excluded by default rather than shipping until someone
+ * notices - the safe direction for reason 2 above.
+ */
+export const MAINTAINER_SMOKES = new RegExp(
+  `^smoke-(?!${CONSUMER_SMOKES.map((n) => n.replace(/^smoke-/, "").replace(/\./g, "\\.")).join(
+    "|",
+  )}$)`,
+);
+
+/**
+ * Repository tooling that is not a smoke: the smoke runner itself, the eval
+ * harnesses, the scorecard, and the linters. All of them need devDependencies
+ * (`ajv`, `c8`, `eslint`) or the repo tree, neither of which exists in an
+ * install.
+ */
+const DEV_ONLY_TOOLING = Object.freeze([
+  "run-smokes.mjs",
+  "scorecard.mjs",
+  "lint-skills.mjs",
+  "lint-mcp-refs.mjs",
+  "check-md-links.mjs",
+  "validate-schemas.mjs", // validates the repo's own schema files, needs ajv
+  "sync-parity-check.sh",
+  "benchmark-phase-0.sh",
+  "test-gap-rules", // rule corpus for the repo's own test-gap gate
+]);
+
+/** Eval harnesses (`eval-*.mjs`) read `pipeline/eval/**`, which never ships. */
+const EVAL_HARNESSES = /^eval-.*\.mjs$/;
+
 export const DEV_ONLY_SCRIPTS = Object.freeze([
+  // --- reason 1: leak ---
   "smoke-figma-config-schema.sh",
   "smoke-personal-data.sh", // scanner contains the patterns it detects
-  "smoke-install-leak-gate.sh", // same — scanner shadows the install pipeline
+  "smoke-install-leak-gate.sh", // same - scanner shadows the install pipeline
   "validate-prefs.mjs", // needs ajv (devDependency); end users have no node_modules here
   "fixtures", // smoke test fixtures live in the repo only, never ship to users
+  // --- reason 2: maintainer CI ---
+  ...DEV_ONLY_TOOLING,
+  EVAL_HARNESSES,
+  MAINTAINER_SMOKES,
 ]);
+
+/**
+ * True when `name` (a path relative to `pipeline/scripts/`) must not be
+ * installed. Shared by both installers' excluded-file counters and by
+ * `smoke-consumer-smoke-surface.sh`, so the count and the gate can never
+ * disagree with what `copyDir` actually filtered.
+ *
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function isDevOnlyScript(name) {
+  const rel = String(name).split("\\").join("/").replace(/^\//, "");
+  return DEV_ONLY_SCRIPTS.some((pat) =>
+    typeof pat === "string" ? rel === pat || rel.startsWith(pat + "/") : pat.test(rel),
+  );
+}
+
+/**
+ * How many files under `scriptsDir` `copyDir` will filter out.
+ *
+ * Walks the tree and applies `isDevOnlyScript` to the same relative paths
+ * `copyDir`'s filter sees, so the number printed by an install is the number
+ * actually withheld. The previous form summed `countFiles()` over the exclusion
+ * array, which silently returned 0 for every non-literal (regex) entry.
+ *
+ * @param {string} scriptsDir absolute path to `pipeline/scripts`
+ * @returns {number}
+ */
+export function countDevOnlyFiles(scriptsDir) {
+  let excluded = 0;
+  const walk = (abs, rel) => {
+    for (const entry of readdirSync(abs, { withFileTypes: true })) {
+      const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+      const childAbs = join(abs, entry.name);
+      if (entry.isDirectory()) {
+        // An excluded directory takes its whole subtree with it, exactly as
+        // cpSync's filter does when it returns false for the directory itself.
+        if (isDevOnlyScript(childRel)) excluded += countTree(childAbs);
+        else walk(childAbs, childRel);
+      } else if (isDevOnlyScript(childRel)) {
+        excluded++;
+      }
+    }
+  };
+  const countTree = (abs) => {
+    let n = 0;
+    for (const entry of readdirSync(abs, { withFileTypes: true })) {
+      n += entry.isDirectory() ? countTree(join(abs, entry.name)) : 1;
+    }
+    return n;
+  };
+  walk(scriptsDir, "");
+  return excluded;
+}

package/install/_platform-filter.mjs

@@ -12,7 +12,7 @@ import { join } from "path";
 import { copyDir, countFiles, ensureDir } from "./_common.mjs";
 
 /**
- * Heuristic prefix lists — intentionally loose so new skills added to
+ * Heuristic prefix lists - intentionally loose so new skills added to
  * `shared/external/` are classified by name (no manifest required). A skill
  * that doesn't match either list is treated as "generic" and copies for every
  * platform.

package/install/_telemetry.mjs

@@ -56,6 +56,6 @@ export async function sendInstallTelemetry(ctx) {
     });
     clearTimeout(timer);
   } catch {
-    // Silent fail — never break the install if telemetry is unreachable
+    // Silent fail - never break the install if telemetry is unreachable
   }
 }

package/install/claude.mjs

@@ -27,13 +27,14 @@ import {
   ensureDir,
   ensureRealDir,
   isDryRun,
+  pruneAbandonedTrees,
   pruneLegacyMultiAgentSkills,
   removePipelineAgentFiles,
   wipeDir,
   writeFile,
 } from "./_common.mjs";
 import { copyExternalSkillsFiltered } from "./_platform-filter.mjs";
-import { DEV_ONLY_SCRIPTS } from "./_dev-only-files.mjs";
+import { DEV_ONLY_SCRIPTS, countDevOnlyFiles } from "./_dev-only-files.mjs";
 
 /**
  * Dead matcher written by pre-v11.4.1 installs. Hook matchers only ever see
@@ -64,6 +65,14 @@ export function installClaude(ctx) {
   const CLAUDE_LIB = join(home, ".claude", "lib");
   const CLAUDE_MA_REFS = join(home, ".claude", "multi-agent-refs");
 
+  // Before laying anything down: drop trees an older install created that no
+  // current installer manages. Wipe-before-copy only protects trees still being
+  // written, so an abandoned one persists on every existing machine forever.
+  const prunedTrees = pruneAbandonedTrees(join(home, ".claude"));
+  if (prunedTrees > 0) {
+    console.log(`  [Claude Code] Removed ${prunedTrees} abandoned tree(s) from an older install`);
+  }
+
   installCommands(pipelineSrc, CLAUDE_COMMANDS, useSymlinks);
   installMultiAgentRefs(pipelineSrc, CLAUDE_MA_REFS, useSymlinks);
   installScripts(pipelineSrc, CLAUDE_SCRIPTS, useSymlinks);
@@ -196,19 +205,17 @@ function installScripts(pipelineSrc, dest, useSymlinks) {
   const scriptsSrc = join(pipelineSrc, "scripts");
   if (!existsSync(scriptsSrc)) return;
 
-  // Wipe-before-copy — scripts/ is a 100% pipeline-managed tree, so files
+  // Wipe-before-copy - scripts/ is a 100% pipeline-managed tree, so files
   // removed upstream should not linger.
   if (!useSymlinks) ensureRealDir(dest);
   wipeDir(dest);
   copyDir(scriptsSrc, dest, { exclude: DEV_ONLY_SCRIPTS, useSymlinks });
-  // Count files actually excluded, not the array length: DEV_ONLY_SCRIPTS mixes
-  // individual .sh files with the `fixtures` directory (many files), so the
-  // array length under-counts the real exclusion.
-  const excludedCount = DEV_ONLY_SCRIPTS.reduce((n, name) => n + countFiles(join(scriptsSrc, name)), 0);
+  // Count files actually excluded by walking the tree: DEV_ONLY_SCRIPTS mixes
+  // literal names, whole directories, and regexes (the maintainer-smoke rule),
+  // so summing countFiles() over the array reported 0 for every regex entry.
+  const excludedCount = countDevOnlyFiles(scriptsSrc);
   const scriptCount = countFiles(scriptsSrc) - excludedCount;
-  console.log(
-    `    -> ${scriptCount} files copied to ${dest} (${excludedCount} dev-only excluded)`,
-  );
+  console.log(`    -> ${scriptCount} files copied to ${dest} (${excludedCount} dev-only excluded)`);
 }
 
 function installAgents(pipelineSrc, dest, useSymlinks) {
@@ -249,7 +256,7 @@ function installSchemas(pipelineSrc, dest, useSymlinks) {
   console.log("  [Claude Code] Installing JSON schemas...");
   const schemasSrc = join(pipelineSrc, "schemas");
   if (!existsSync(schemasSrc)) return;
-  // Wipe-before-copy — schemas/ is a 100% pipeline-managed tree, so files
+  // Wipe-before-copy - schemas/ is a 100% pipeline-managed tree, so files
   // removed upstream should not linger.
   if (!useSymlinks) ensureRealDir(dest);
   wipeDir(dest);
@@ -261,7 +268,7 @@ function installLib(pipelineSrc, dest, useSymlinks) {
   console.log("  [Claude Code] Installing shell libraries...");
   const libSrc = join(pipelineSrc, "lib");
   if (!existsSync(libSrc)) return;
-  // Wipe-before-copy — lib/ is a 100% pipeline-managed tree.
+  // Wipe-before-copy - lib/ is a 100% pipeline-managed tree.
   if (!useSymlinks) ensureRealDir(dest);
   wipeDir(dest);
   copyDir(libSrc, dest, { useSymlinks });
@@ -269,7 +276,7 @@ function installLib(pipelineSrc, dest, useSymlinks) {
 }
 
 function runPreDeployScans(pipelineSrc) {
-  // Pre-deploy security scan — warn-only, never halts install on its own.
+  // Pre-deploy security scan - warn-only, never halts install on its own.
   const scanScript = join(pipelineSrc, "scripts", "scan-skills.sh");
   if (existsSync(scanScript)) {
     try {
@@ -286,7 +293,7 @@ function runPreDeployScans(pipelineSrc) {
     }
   }
 
-  // Pre-deploy manifest verify (v6.2.H) — warn-only.
+  // Pre-deploy manifest verify (v6.2.H) - warn-only.
   const verifyScript = join(pipelineSrc, "scripts", "verify-skills.sh");
   if (existsSync(verifyScript)) {
     try {