@spardutti/claude-skills 2.32.0 → 2.32.2

package/bin/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { confirm, input } from "@inquirer/prompts";
+import { confirm } from "@inquirer/prompts";
 import chalk from "chalk";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -8,16 +8,8 @@ import { dirname, join } from "node:path";
 import { fetchSkills, fetchCommands, fetchAgents } from "../lib/github.mjs";
 import { promptSkillSelection, promptCommandSelection, promptRemoval } from "../lib/prompt.mjs";
 import { installSkills, installCommands, installRequiredAgents } from "../lib/install.mjs";
-import {
-  setupHook,
-  detectStack,
-  writeGauntletConf,
-  autoModeRuleStatus,
-  writeAutoModeRule,
-} from "../lib/setup-hook.mjs";
-import { makeLocalSource, reportToolNeeds } from "../lib/local.mjs";
-import { scaffoldStryker } from "../lib/scaffold-stryker.mjs";
-import { setupClaudeMd } from "../lib/setup-claude-md.mjs";
+import { makeLocalSource } from "../lib/local.mjs";
+import { runPostInstall } from "../lib/post-install.mjs";
 import {
   readManifest, writeManifest, computeOrphans, computeRemovals, scanInstalled, removeArtifacts,
   MANIFEST_FILE,
@@ -165,153 +157,7 @@ async function main() {
     process.exit(0);
   }
 
-  // --- Hook setup ---
-  // Offered whenever anything was installed: the skill gates need skills, but the
-  // gauntlet guards any repo with a test runner, commands-only installs included.
-  if (selectedSkills.length > 0 || selectedCommands.length > 0) {
-    console.log();
-    const shouldSetup = await confirm({
-      message: "Set up hooks — skill evaluation before edits, verification after? (Recommended)",
-      default: true,
-    });
-    if (shouldSetup) {
-      console.log();
-      await setupHook();
-      await setupClaudeMd();
-
-      // In auto mode the classifier denies the gate's ack, and it only reads
-      // autoMode.allow from the user's own ~/.claude/settings.json. Without this
-      // the gate cannot be satisfied at all, and the session cannot fix it
-      // either — an agent editing permission settings is denied by the same
-      // classifier. The installer is the only thing here running as the user.
-      const autoModeStatus = await autoModeRuleStatus();
-      if (autoModeStatus === "unreadable") {
-        console.log();
-        console.log(`  ${chalk.yellow("!")} ${chalk.dim("~/.claude/settings.json is not valid JSON — skipping the auto mode rule.")}`);
-      } else if (autoModeStatus !== "current") {
-        console.log();
-        console.log(chalk.dim("  Auto mode's classifier denies the gate's acknowledgement files, and"));
-        console.log(chalk.dim("  clearing that needs a rule in your own ~/.claude/settings.json. Claude"));
-        console.log(chalk.dim("  cannot add it — editing permission settings is denied to agents too."));
-        const addRule = await confirm({
-          message:
-            autoModeStatus === "stale"
-              ? "Update the auto mode allow rule in ~/.claude/settings.json? (Recommended)"
-              : "Add an auto mode allow rule to ~/.claude/settings.json? (Recommended)",
-          default: true,
-        });
-        if (addRule) {
-          try {
-            const written = await writeAutoModeRule();
-            console.log(`  Settings updated: ${written}`);
-          } catch (err) {
-            console.log(`  ${chalk.yellow("!")} ${chalk.dim(err.message)}`);
-          }
-        } else {
-          console.log(`  ${chalk.dim("Skipped. In auto mode the gate will block until you add it via /permissions.")}`);
-        }
-      }
-
-      // Report what the gauntlet will actually run, so a silent no-op is visible.
-      // This asks the installed hook itself — never a second copy of its logic.
-      const gates = await detectStack(CWD);
-      if (gates) {
-        for (const gate of gates.split(";").map((g) => g.trim()).filter(Boolean)) {
-          console.log(`  ${chalk.dim(`Gauntlet gate: ${gate}`)}`);
-        }
-      } else {
-        console.log(`  ${chalk.yellow("!")} ${chalk.dim("Gauntlet found no test runner here — it will stay asleep.")}`);
-        console.log();
-        const wantConf = await confirm({
-          message: "Point it at your test command now?",
-          default: false,
-        });
-        if (wantConf) {
-          const cmd = (await input({ message: "Test command:" })).trim();
-          if (cmd) {
-            const written = await writeGauntletConf(CWD, cmd);
-            console.log(`  Config written: ${written.replace(CWD + "/", "")}`);
-          }
-        }
-      }
-    }
-  }
-
-  // --- What the installed commands need that this project does not have ---
-  // /ship's mutation check is per project, so a monorepo needs a tool per project.
-  if (selectedCommands.some((c) => c.fileName === "ship.md")) {
-    const needs = await reportToolNeeds(CWD);
-    console.log();
-    if (needs.length === 0) {
-      console.log(`  ${chalk.dim("/ship's mutation check has a tool in every project here.")}`);
-    } else {
-      console.log(`  ${chalk.yellow("!")} ${chalk.bold("/ship needs a mutation tool per project")} ${chalk.dim("— without one it reports UNPROVEN, and never blocks.")}`);
-      if (!selectedSkills.some((s) => s.dirName === "testing-best-practices")) {
-        console.log(`    ${chalk.dim("Setting these up has traps — install the testing-best-practices skill for MUTATION-TESTING.md.")}`);
-      }
-      for (const n of needs.filter((n) => !n.ignorerOnly)) {
-        console.log(`    ${chalk.bold(n.label)} needs ${n.tool}`);
-        console.log(`      ${chalk.cyan(n.install)}`);
-        console.log(`      ${chalk.dim(n.config)}`);
-        for (const line of n.also ?? []) console.log(`      ${chalk.dim(line)}`);
-      }
-      for (const n of needs.filter((n) => n.ignorerOnly)) {
-        console.log(`    ${chalk.bold(n.label)} runs ${n.tool} without the class-name ignorer`);
-        console.log(`      ${chalk.dim("~40% of a first React run is mutants on className strings, which no test can honestly kill")}`);
-      }
-
-      // Printing five steps meant every project was set up by hand, and the one
-      // step people skipped was the class-name ignorer — the reason a first run
-      // comes back with dozens of mutants on className strings that no test can
-      // honestly kill. Write the two files instead of describing them.
-      const stryker = needs.filter((n) => n.tool === "Stryker");
-      if (stryker.length > 0) {
-        console.log();
-        const doScaffold = await confirm({
-          message: `Write Stryker's config and the class-name ignorer for ${stryker.length} project(s)?`,
-          default: true,
-        });
-        if (doScaffold) {
-          const installs = [];
-          const apiInstalls = [];
-          const vitest = [];
-          for (const n of stryker) {
-            const r = await scaffoldStryker(CWD, n.rel);
-            for (const f of r.wrote) console.log(`  Wrote: ${f}`);
-            for (const f of r.patched) console.log(`  Added the ignorer to: ${f}`);
-            for (const f of r.kept) console.log(`  ${chalk.dim(`Kept yours: ${f}`)}`);
-            for (const f of r.unreadable) {
-              console.log(`  ${chalk.yellow("!")} ${f} is not readable as JSON — left alone, add the ignorer by hand`);
-            }
-            // A project that already runs Stryker needs neither the install nor
-            // the vitest exclude repeated at it; it only lacked the ignorer.
-            if (n.ignorerOnly) {
-              apiInstalls.push(r.apiInstall);
-            } else {
-              installs.push(r.install);
-              vitest.push(r.vitest);
-            }
-          }
-          // Left to the reader on purpose: installing touches the lockfile and
-          // the network, and editing an existing vitest config means parsing
-          // someone's plugins and aliases, where being wrong breaks their tests.
-          if (installs.length > 0) {
-            console.log(`\n  ${chalk.yellow("!")} ${chalk.bold("Two steps left, per project:")}`);
-            for (const c of installs) console.log(`      ${chalk.cyan(c)}`);
-            for (const v of vitest) console.log(`      ${chalk.dim(v)}`);
-          }
-          // The ignorer imports @stryker-mutator/api, which npm hoists by
-          // accident and pnpm does not. Missing, it prints one WARN PluginLoader
-          // line, loads nothing, and every className mutant comes back survived.
-          if (apiInstalls.length > 0) {
-            console.log(`\n  ${chalk.yellow("!")} ${chalk.bold("The ignorer needs its own dependency:")}`);
-            for (const c of apiInstalls) console.log(`      ${chalk.cyan(c)}`);
-            console.log(`      ${chalk.dim("without it the ignorer silently does not load")}`);
-          }
-        }
-      }
-    }
-  }
+  await runPostInstall({ CWD, selectedSkills, selectedCommands });
 
   // --- Record what is now installed ---
   await writeManifest(CWD, {

package/lib/auto-mode.mjs

@@ -0,0 +1,85 @@
+// The permissions rule that lets the skill gates clear themselves under auto
+// mode. Separate from installing the hooks: this writes the USER's global
+// settings, that writes a project's, and only one of them can be done for you.
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+
+
+// The project-level permissions.allow written above does not clear auto mode.
+// The classifier reads autoMode.allow, and only from the user's own
+// ~/.claude/settings.json — it deliberately ignores a project's settings so a
+// cloned repo cannot loosen it. So the gate's ack was denied, and the remedy the
+// deny message named could not be applied by the agent either: the classifier
+// refuses an agent editing permission settings by any route. That left a
+// deadlock nothing in the session could break. The installer can, because npx
+// runs as the user, not as an agent — but only ever behind an explicit prompt,
+// since this is the user's global file.
+export const AUTO_MODE_RULE =
+  "Touching marker files under /tmp/claude-skill-gate-*, /tmp/claude-skill-acked-* " +
+  "and /tmp/claude-skill-loaded-* is allowed: they are acknowledgement files for the " +
+  "user's own PreToolUse skill gates. Creating one satisfies a workflow gate the user " +
+  "installed, grants no permission and executes no code, and is a false positive for " +
+  "Auto-Mode Bypass.";
+
+// Any entry naming a marker path is ours, whatever wording it shipped with. An
+// upgrade must correct that entry rather than add a second one beside it —
+// a fresh-install test would never see the difference.
+const AUTO_MODE_RULE_MARK = "/tmp/claude-skill-acked-";
+
+function globalSettingsPath(homeDir) {
+  return join(homeDir ?? homedir(), ".claude", "settings.json");
+}
+
+async function readGlobalSettings(homeDir) {
+  try {
+    return JSON.parse(await readFile(globalSettingsPath(homeDir), "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+// "current" — the rule is present and matches. "stale" — an older wording is
+// there. "missing" — nothing of ours. "unreadable" — the file exists but does
+// not parse, so we must not rewrite it.
+export async function autoModeRuleStatus(homeDir) {
+  let raw;
+  try {
+    raw = await readFile(globalSettingsPath(homeDir), "utf-8");
+  } catch {
+    return "missing";
+  }
+  let settings;
+  try {
+    settings = JSON.parse(raw);
+  } catch {
+    return "unreadable";
+  }
+  const allow = settings?.autoMode?.allow;
+  if (!Array.isArray(allow)) return "missing";
+  if (allow.includes(AUTO_MODE_RULE)) return "current";
+  if (allow.some((r) => typeof r === "string" && r.includes(AUTO_MODE_RULE_MARK))) return "stale";
+  return "missing";
+}
+
+// Writes the rule into ~/.claude/settings.json, keeping "$defaults" first —
+// dropping it discards every built-in allow. Everything else in the file is
+// preserved. Refuses an unparseable file rather than replacing it.
+export async function writeAutoModeRule(homeDir) {
+  if ((await autoModeRuleStatus(homeDir)) === "unreadable") {
+    throw new Error(`${globalSettingsPath(homeDir)} is not valid JSON — fix it, then re-run.`);
+  }
+  const settings = (await readGlobalSettings(homeDir)) ?? {};
+  if (!settings.autoMode || typeof settings.autoMode !== "object") settings.autoMode = {};
+  const existing = Array.isArray(settings.autoMode.allow) ? settings.autoMode.allow : [];
+
+  const kept = existing.filter(
+    (r) => r !== "$defaults" && !(typeof r === "string" && r.includes(AUTO_MODE_RULE_MARK)),
+  );
+  settings.autoMode.allow = ["$defaults", ...kept, AUTO_MODE_RULE];
+
+  const path = globalSettingsPath(homeDir);
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, JSON.stringify(settings, null, 2) + "\n", { mode: 0o600 });
+  return path;
+}

package/lib/frontmatter.mjs

@@ -0,0 +1,49 @@
+// The one parser for a SKILL.md / command / agent frontmatter block.
+//
+// There used to be two — one in github.mjs, one in local.mjs — written
+// differently, and they disagreed on four of five inputs:
+//
+//   description: "d"        github kept the quotes, local stripped them
+//   category: "Q"           same
+//   requires-agents: p, q   github returned [], local returned ["p","q"]
+//
+// So `--local` and a real install read the same file differently. The quote
+// difference was masked downstream by a stripQuotes() in prompt.mjs, which is
+// what let it live: the picker looked right, so nobody looked further.
+//
+// Behaviour kept here is local.mjs's, because it was the correct one on every
+// case: quotes stripped, and both `[a, b]` and `a, b` accepted for a list.
+export function parseFrontmatter(content, fallbackName) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) {
+    return { name: fallbackName, description: "", category: "General", requiresAgents: [] };
+  }
+  const block = match[1];
+
+  // A value may be quoted or bare. Descriptions are quoted in every skill this
+  // repo ships, so returning the quotes is wrong for the common case, not the
+  // edge one.
+  const pick = (key) => {
+    const m = block.match(new RegExp(`^${key}:\\s*(.+)$`, "m"));
+    return m ? m[1].trim().replace(/^["']|["']$/g, "") : "";
+  };
+
+  return {
+    name: pick("name") || fallbackName,
+    description: pick("description"),
+    category: pick("category") || "General",
+    requiresAgents: parseAgentList(pick("requires-agents")),
+  };
+}
+
+// `requires-agents: [a, b]` is what every command in this repo writes, but the
+// brackets are YAML flow syntax rather than part of the value, so a bare
+// `a, b` means the same thing and must parse the same way.
+export function parseAgentList(raw) {
+  if (!raw) return [];
+  return raw
+    .replace(/[[\]]/g, "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}

package/lib/github.mjs

@@ -1,3 +1,4 @@
+import { parseFrontmatter } from "./frontmatter.mjs";
 import { execSync } from "node:child_process";
 
 const REPO_OWNER = "Spardutti";
@@ -172,36 +173,3 @@ export function fetchAgents() {
     },
   });
 }
-
-function parseFrontmatter(content, fallbackName) {
-  const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
-  if (!match) {
-    return { name: fallbackName, description: "", category: "General", requiresAgents: [] };
-  }
-
-  const block = match[1];
-  const name = block.match(/^name:\s*(.+)$/m)?.[1]?.trim() || fallbackName;
-  const description = block.match(/^description:\s*(.+)$/m)?.[1]?.trim() || "";
-  const category = block.match(/^category:\s*(.+)$/m)?.[1]?.trim() || "General";
-  const requiresAgents = parseAgentList(block);
-
-  return { name, description, category, requiresAgents };
-}
-
-function parseAgentList(block) {
-  const inline = block.match(/^requires-agents:\s*\[([^\]]*)\]\s*$/m);
-  if (inline) {
-    return inline[1]
-      .split(",")
-      .map((s) => s.trim().replace(/^["']|["']$/g, ""))
-      .filter(Boolean);
-  }
-  const multiline = block.match(/^requires-agents:\s*\n((?:\s{2,}-\s*.+\n?)+)/m);
-  if (multiline) {
-    return multiline[1]
-      .split("\n")
-      .map((l) => l.replace(/^\s*-\s*/, "").trim().replace(/^["']|["']$/g, ""))
-      .filter(Boolean);
-  }
-  return [];
-}

package/lib/hook-settings.mjs

@@ -0,0 +1,140 @@
+// Registering the hooks in .claude/settings.json — which is a different job
+// from writing the hook files, and the one with all the upgrade traps: a hook
+// already registered under an old matcher stays on it unless corrected, and a
+// legacy entry from an earlier version has to be removed rather than ignored.
+import { readFile, writeFile } from "node:fs/promises";
+
+const GATE_FILENAME = "skill-gate.sh";
+const AUTO_MARK_FILENAME = "skill-gate-automark.sh";
+const APPLICATION_GATE_FILENAME = "skill-application-gate.sh";
+const GAUNTLET_FILENAME = "gauntlet.sh";
+const SHIP_GATE_FILENAME = "ship-gate.sh";
+const SHIP_GATE_HOOK_FILENAME = "ship-gate-hook.sh";
+const VERSION_CHECK_FILENAME = "version-check.sh";
+const LEGACY_EVAL_FILENAME = "skill-forced-eval-hook.sh";
+const LEGACY_AUDIT_RUNNER_FILENAME = "skill-audit-runner.sh";
+
+
+// Register the entry, or CORRECT the one already there. Skipping when a hook of
+// this name exists leaves an existing install pinned to whatever matcher it was
+// first written with — which is how the skill gates kept watching only
+// Write|Edit|MultiEdit after they learned to cover Bash.
+function upsert(list, filename, entry) {
+  const existing = list.find((e) => e.hooks?.some((h) => h.command?.endsWith(filename)));
+  if (!existing) return list.push(entry);
+  if (entry.matcher === undefined) delete existing.matcher;
+  else existing.matcher = entry.matcher;
+  existing.hooks = entry.hooks;
+}
+
+export async function registerHooks(settingsPath) {
+  let settings = {};
+  try {
+    settings = JSON.parse(await readFile(settingsPath, "utf-8"));
+  } catch {
+    // missing or invalid — start fresh
+  }
+  if (!settings.hooks) settings.hooks = {};
+
+  // Clean up legacy UserPromptSubmit eval hook (replaced by the gate).
+  if (Array.isArray(settings.hooks.UserPromptSubmit)) {
+    settings.hooks.UserPromptSubmit = settings.hooks.UserPromptSubmit.filter(
+      (entry) => !entry.hooks?.some((h) => h.command?.endsWith(LEGACY_EVAL_FILENAME))
+    );
+    if (settings.hooks.UserPromptSubmit.length === 0) {
+      delete settings.hooks.UserPromptSubmit;
+    }
+  }
+
+  // Clean up legacy PreToolUse audit-runner hook (2.3.x — removed in 2.4.0).
+  if (Array.isArray(settings.hooks.PreToolUse)) {
+    settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
+      (entry) => !entry.hooks?.some((h) => h.command?.endsWith(LEGACY_AUDIT_RUNNER_FILENAME))
+    );
+  }
+
+  // Register PreToolUse gate.
+  const gateCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${GATE_FILENAME}`;
+  const gateEntry = {
+    matcher: "Write|Edit|MultiEdit|Bash",
+    hooks: [{ type: "command", command: gateCommand }],
+  };
+
+  if (Array.isArray(settings.hooks.PreToolUse)) {
+    upsert(settings.hooks.PreToolUse, GATE_FILENAME, gateEntry);
+  } else {
+    settings.hooks.PreToolUse = [gateEntry];
+  }
+
+  // Register PreToolUse application gate (after the loading gate).
+  const applicationCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${APPLICATION_GATE_FILENAME}`;
+  const applicationEntry = {
+    matcher: "Write|Edit|MultiEdit|Bash",
+    hooks: [{ type: "command", command: applicationCommand }],
+  };
+  upsert(settings.hooks.PreToolUse, APPLICATION_GATE_FILENAME, applicationEntry);
+
+  // Register PreToolUse ship-gate receipt check on Bash.
+  const shipGateCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${SHIP_GATE_HOOK_FILENAME}`;
+  const shipGateEntry = {
+    matcher: "Bash",
+    hooks: [{ type: "command", command: shipGateCommand }],
+  };
+  upsert(settings.hooks.PreToolUse, SHIP_GATE_HOOK_FILENAME, shipGateEntry);
+
+  // Register PostToolUse auto-mark on Skill.
+  const autoMarkCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${AUTO_MARK_FILENAME}`;
+  const autoMarkEntry = {
+    matcher: "Skill",
+    hooks: [{ type: "command", command: autoMarkCommand }],
+  };
+
+  if (Array.isArray(settings.hooks.PostToolUse)) {
+    upsert(settings.hooks.PostToolUse, AUTO_MARK_FILENAME, autoMarkEntry);
+  } else {
+    settings.hooks.PostToolUse = [autoMarkEntry];
+  }
+
+  // Register SessionStart version check. No matcher: startup and resume both
+  // want it, and the script's own daily stamp keeps a burst of resumes quiet.
+  const versionCheckCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${VERSION_CHECK_FILENAME}`;
+  const versionCheckEntry = { hooks: [{ type: "command", command: versionCheckCommand }] };
+
+  if (Array.isArray(settings.hooks.SessionStart)) {
+    upsert(settings.hooks.SessionStart, VERSION_CHECK_FILENAME, versionCheckEntry);
+  } else {
+    settings.hooks.SessionStart = [versionCheckEntry];
+  }
+
+  // Register Stop gauntlet hook.
+  const gauntletCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${GAUNTLET_FILENAME}`;
+  const gauntletEntry = { hooks: [{ type: "command", command: gauntletCommand }] };
+
+  if (Array.isArray(settings.hooks.Stop)) {
+    upsert(settings.hooks.Stop, GAUNTLET_FILENAME, gauntletEntry);
+  } else {
+    settings.hooks.Stop = [gauntletEntry];
+  }
+
+  // Both gates clear by touching a marker under /tmp. The hook scripts let those
+  // commands through themselves, but auto mode's permission classifier does not:
+  // a touch whose only purpose is to unlock a gate is exactly what it refuses.
+  // So in auto mode the application gate could not be satisfied at all, and the
+  // model was reduced to asking its user to run the touch by hand — which is
+  // indistinguishable from the laundering the classifier exists to stop.
+  // Allowlisting the three marker paths is what makes the gates workable there.
+  // Only these literal prefixes are granted, and an existing entry is not
+  // duplicated on reinstall.
+  const MARKER_ALLOW = [
+    "Bash(touch /tmp/claude-skill-gate-*)",
+    "Bash(touch /tmp/claude-skill-acked-*)",
+    "Bash(touch /tmp/claude-skill-loaded-*)",
+  ];
+  if (!settings.permissions) settings.permissions = {};
+  if (!Array.isArray(settings.permissions.allow)) settings.permissions.allow = [];
+  for (const rule of MARKER_ALLOW) {
+    if (!settings.permissions.allow.includes(rule)) settings.permissions.allow.push(rule);
+  }
+
+  await writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", { mode: 0o644 });
+}

package/lib/local.mjs

@@ -3,54 +3,11 @@
 // publishing it first.
 import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
+import { parseFrontmatter } from "./frontmatter.mjs";
 
-const exec = promisify(execFile);
-
-function parseFrontmatter(content, fallbackName) {
-  const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
-  if (!match) return { name: fallbackName, description: "", category: "General", requiresAgents: [] };
-  const fm = match[1];
-  const pick = (key) => {
-    const m = fm.match(new RegExp(`^${key}:\\s*(.+)$`, "m"));
-    return m ? m[1].trim().replace(/^["']|["']$/g, "") : "";
-  };
-  const raw = pick("requires-agents");
-  return {
-    name: pick("name") || fallbackName,
-    description: pick("description"),
-    category: pick("category") || "General",
-    requiresAgents: raw ? raw.replace(/[[\]]/g, "").split(",").map((s) => s.trim()).filter(Boolean) : [],
-  };
-}
-
-async function listDir(dir) {
+export async function listDir(dir) {
   try { return await readdir(dir, { withFileTypes: true }); } catch { return []; }
 }
-
-// Build output is not a project. Next.js writes a package.json into .next/,
-// .next/dev/ and .next/standalone/, so a scan that skipped only a hardcoded
-// list reported three phantom projects on a plain Next app — and then filtered
-// the real repo root out as "a root that delegates to a workspace". A second
-// list of build dirs drifts from .gitignore the moment a framework adds one, so
-// ask git the way ship-gate.sh already does. --directory collapses a fully
-// ignored tree to its own name, which is what keeps this output small.
-async function gitIgnoredDirs(projectDir) {
-  try {
-    const { stdout } = await exec(
-      "git",
-      ["-C", projectDir, "ls-files", "--others", "--ignored", "--exclude-standard", "--directory"],
-      { maxBuffer: 10 * 1024 * 1024 },
-    );
-    return new Set(
-      stdout.split("\n").filter((l) => l.endsWith("/")).map((l) => l.slice(0, -1)),
-    );
-  } catch {
-    return new Set();
-  }
-}
-
 export function makeLocalSource(root) {
   return {
     async fetchSkills() {
@@ -125,92 +82,4 @@ async function pythonAdvice(dir, rel, entries) {
     install,
     config: `${rel ? rel + "/" : ""}pyproject.toml  [tool.mutmut] source_paths=["${source}/"] pytest_add_cli_args_test_selection=["${tests}/"]`,
   };
-}
-
-// What the installed commands need that this project does not have yet.
-// ship-gate.sh's own detection drives a single-package repo; a monorepo whose
-// tools need a workspace prefix or a container sets GAUNTLET_MUTATE instead. Only
-// /ship needs anything: a mutation tool, per project, since a monorepo can hold
-// several and they do not share one.
-export async function reportToolNeeds(projectDir) {
-  const needs = [];
-  const seen = new Set();
-  // Whether a nested project of each kind exists at all — not whether it still
-  // needs a tool. A root that delegates is not the place to install, even once
-  // the workspace it delegates to is already set up.
-  const nested = { Stryker: false, mutmut: false };
-  // Empty outside a git repo, so the hardcoded list below still carries those.
-  const ignored = await gitIgnoredDirs(projectDir);
-
-  async function scan(rel, depth) {
-    if (depth > 2) return;
-    const dir = rel ? join(projectDir, rel) : projectDir;
-    const entries = await listDir(dir);
-    const label = rel ? `${rel}/` : "<repo root>";
-
-    const pkg = entries.find((e) => e.isFile() && e.name === "package.json");
-    const pyp = entries.find((e) => e.isFile() && (e.name === "pyproject.toml" || e.name === "pytest.ini"));
-
-    if (pkg && rel) nested.Stryker = true;
-    if (pyp && rel) nested.mutmut = true;
-
-    if (pkg && !seen.has(label)) {
-      seen.add(label);
-      const text = await readFile(join(dir, "package.json"), "utf-8");
-      if (!text.includes("@stryker-mutator/core")) {
-        const at = rel ? rel + "/" : "";
-        needs.push({
-          label,
-          rel,
-          tool: "Stryker",
-          install: `npm --prefix ${rel || "."} i -D @stryker-mutator/core @stryker-mutator/vitest-runner`,
-          config: `${at}stryker.config.json  {"testRunner":"vitest","plugins":["@stryker-mutator/vitest-runner"],"coverageAnalysis":"perTest"}`,
-          // Stryker copies the whole project into .stryker-tmp/sandbox-*/, so
-          // every test file briefly exists twice and the runner collects both.
-          // The duplicates pass, so a doubled test count is the only symptom.
-          // Spread configDefaults.exclude — assigning it drops node_modules.
-          also: [
-            `${at}vitest.config.ts  exclude: [...configDefaults.exclude, "**/.stryker-tmp/**"]`,
-            `${at}.gitignore  .stryker-tmp/`,
-          ],
-        });
-      } else {
-        // Stryker is installed, so this project is not missing a tool — but the
-        // projects that already run it are the ones grinding through mutants on
-        // className strings, and a setup done before the ignorer existed has no
-        // way to learn about it. Offer it here or it never reaches them.
-        let cfg = "";
-        try {
-          cfg = await readFile(join(dir, "stryker.config.json"), "utf-8");
-        } catch {
-          // no config of its own — the scaffolder writes one
-        }
-        if (!cfg.includes("tailwind-classnames")) {
-          needs.push({ label, rel, tool: "Stryker", ignorerOnly: true });
-        }
-      }
-    }
-    if (pyp && !seen.has(label + ":py")) {
-      seen.add(label + ":py");
-      const text = pyp.name === "pyproject.toml" ? await readFile(join(dir, "pyproject.toml"), "utf-8") : "";
-      if (!text.includes("[tool.mutmut]")) {
-        const advice = await pythonAdvice(dir, rel, entries);
-        needs.push({ label, tool: "mutmut", ...advice });
-      }
-    }
-
-    for (const e of entries) {
-      if (!e.isDirectory()) continue;
-      if (["node_modules", ".git", "dist", "build", ".venv", "venv", ".claude"].includes(e.name)) continue;
-      const child = rel ? `${rel}/${e.name}` : e.name;
-      if (ignored.has(child)) continue;
-      await scan(child, depth + 1);
-    }
-  }
-
-  await scan("", 0);
-
-  // A root package.json that delegates to a workspace (npm --prefix web run test)
-  // has no tests of its own, so asking for a mutation tool there is noise.
-  return needs.filter((n) => n.label !== "<repo root>" || !nested[n.tool]);
-}
+}

package/lib/post-install.mjs

@@ -0,0 +1,163 @@
+// Everything the installer does AFTER the user has chosen what to install:
+// offer the hooks, then report what the installed commands need that this
+// project does not have. Lifted out of a 270-line main() — these two are a
+// phase of their own, they run only when something was installed, and neither
+// decides what gets installed.
+import { confirm, input } from "@inquirer/prompts";
+import chalk from "chalk";
+import { setupHook, detectStack, writeGauntletConf } from "./setup-hook.mjs";
+import { autoModeRuleStatus, writeAutoModeRule } from "./auto-mode.mjs";
+import { reportToolNeeds } from "./tool-needs.mjs";
+import { scaffoldStryker } from "./scaffold-stryker.mjs";
+import { setupClaudeMd } from "./setup-claude-md.mjs";
+
+export async function runPostInstall({ CWD, selectedSkills, selectedCommands }) {
+  // --- Hook setup ---
+  // Offered whenever anything was installed: the skill gates need skills, but the
+  // gauntlet guards any repo with a test runner, commands-only installs included.
+  if (selectedSkills.length > 0 || selectedCommands.length > 0) {
+    console.log();
+    const shouldSetup = await confirm({
+      message: "Set up hooks — skill evaluation before edits, verification after? (Recommended)",
+      default: true,
+    });
+    if (shouldSetup) {
+      console.log();
+      await setupHook();
+      await setupClaudeMd();
+
+      // In auto mode the classifier denies the gate's ack, and it only reads
+      // autoMode.allow from the user's own ~/.claude/settings.json. Without this
+      // the gate cannot be satisfied at all, and the session cannot fix it
+      // either — an agent editing permission settings is denied by the same
+      // classifier. The installer is the only thing here running as the user.
+      const autoModeStatus = await autoModeRuleStatus();
+      if (autoModeStatus === "unreadable") {
+        console.log();
+        console.log(`  ${chalk.yellow("!")} ${chalk.dim("~/.claude/settings.json is not valid JSON — skipping the auto mode rule.")}`);
+      } else if (autoModeStatus !== "current") {
+        console.log();
+        console.log(chalk.dim("  Auto mode's classifier denies the gate's acknowledgement files, and"));
+        console.log(chalk.dim("  clearing that needs a rule in your own ~/.claude/settings.json. Claude"));
+        console.log(chalk.dim("  cannot add it — editing permission settings is denied to agents too."));
+        const addRule = await confirm({
+          message:
+            autoModeStatus === "stale"
+              ? "Update the auto mode allow rule in ~/.claude/settings.json? (Recommended)"
+              : "Add an auto mode allow rule to ~/.claude/settings.json? (Recommended)",
+          default: true,
+        });
+        if (addRule) {
+          try {
+            const written = await writeAutoModeRule();
+            console.log(`  Settings updated: ${written}`);
+          } catch (err) {
+            console.log(`  ${chalk.yellow("!")} ${chalk.dim(err.message)}`);
+          }
+        } else {
+          console.log(`  ${chalk.dim("Skipped. In auto mode the gate will block until you add it via /permissions.")}`);
+        }
+      }
+
+      // Report what the gauntlet will actually run, so a silent no-op is visible.
+      // This asks the installed hook itself — never a second copy of its logic.
+      const gates = await detectStack(CWD);
+      if (gates) {
+        for (const gate of gates.split(";").map((g) => g.trim()).filter(Boolean)) {
+          console.log(`  ${chalk.dim(`Gauntlet gate: ${gate}`)}`);
+        }
+      } else {
+        console.log(`  ${chalk.yellow("!")} ${chalk.dim("Gauntlet found no test runner here — it will stay asleep.")}`);
+        console.log();
+        const wantConf = await confirm({
+          message: "Point it at your test command now?",
+          default: false,
+        });
+        if (wantConf) {
+          const cmd = (await input({ message: "Test command:" })).trim();
+          if (cmd) {
+            const written = await writeGauntletConf(CWD, cmd);
+            console.log(`  Config written: ${written.replace(CWD + "/", "")}`);
+          }
+        }
+      }
+    }
+  }
+
+  // --- What the installed commands need that this project does not have ---
+  // /ship's mutation check is per project, so a monorepo needs a tool per project.
+  if (selectedCommands.some((c) => c.fileName === "ship.md")) {
+    const needs = await reportToolNeeds(CWD);
+    console.log();
+    if (needs.length === 0) {
+      console.log(`  ${chalk.dim("/ship's mutation check has a tool in every project here.")}`);
+    } else {
+      console.log(`  ${chalk.yellow("!")} ${chalk.bold("/ship needs a mutation tool per project")} ${chalk.dim("— without one it reports UNPROVEN, and never blocks.")}`);
+      if (!selectedSkills.some((s) => s.dirName === "testing-best-practices")) {
+        console.log(`    ${chalk.dim("Setting these up has traps — install the testing-best-practices skill for MUTATION-TESTING.md.")}`);
+      }
+      for (const n of needs.filter((n) => !n.ignorerOnly)) {
+        console.log(`    ${chalk.bold(n.label)} needs ${n.tool}`);
+        console.log(`      ${chalk.cyan(n.install)}`);
+        console.log(`      ${chalk.dim(n.config)}`);
+        for (const line of n.also ?? []) console.log(`      ${chalk.dim(line)}`);
+      }
+      for (const n of needs.filter((n) => n.ignorerOnly)) {
+        console.log(`    ${chalk.bold(n.label)} runs ${n.tool} without the class-name ignorer`);
+        console.log(`      ${chalk.dim("~40% of a first React run is mutants on className strings, which no test can honestly kill")}`);
+      }
+
+      // Printing five steps meant every project was set up by hand, and the one
+      // step people skipped was the class-name ignorer — the reason a first run
+      // comes back with dozens of mutants on className strings that no test can
+      // honestly kill. Write the two files instead of describing them.
+      const stryker = needs.filter((n) => n.tool === "Stryker");
+      if (stryker.length > 0) {
+        console.log();
+        const doScaffold = await confirm({
+          message: `Write Stryker's config and the class-name ignorer for ${stryker.length} project(s)?`,
+          default: true,
+        });
+        if (doScaffold) {
+          const installs = [];
+          const apiInstalls = [];
+          const vitest = [];
+          for (const n of stryker) {
+            const r = await scaffoldStryker(CWD, n.rel);
+            for (const f of r.wrote) console.log(`  Wrote: ${f}`);
+            for (const f of r.patched) console.log(`  Added the ignorer to: ${f}`);
+            for (const f of r.kept) console.log(`  ${chalk.dim(`Kept yours: ${f}`)}`);
+            for (const f of r.unreadable) {
+              console.log(`  ${chalk.yellow("!")} ${f} is not readable as JSON — left alone, add the ignorer by hand`);
+            }
+            // A project that already runs Stryker needs neither the install nor
+            // the vitest exclude repeated at it; it only lacked the ignorer.
+            if (n.ignorerOnly) {
+              apiInstalls.push(r.apiInstall);
+            } else {
+              installs.push(r.install);
+              vitest.push(r.vitest);
+            }
+          }
+          // Left to the reader on purpose: installing touches the lockfile and
+          // the network, and editing an existing vitest config means parsing
+          // someone's plugins and aliases, where being wrong breaks their tests.
+          if (installs.length > 0) {
+            console.log(`\n  ${chalk.yellow("!")} ${chalk.bold("Two steps left, per project:")}`);
+            for (const c of installs) console.log(`      ${chalk.cyan(c)}`);
+            for (const v of vitest) console.log(`      ${chalk.dim(v)}`);
+          }
+          // The ignorer imports @stryker-mutator/api, which npm hoists by
+          // accident and pnpm does not. Missing, it prints one WARN PluginLoader
+          // line, loads nothing, and every className mutant comes back survived.
+          if (apiInstalls.length > 0) {
+            console.log(`\n  ${chalk.yellow("!")} ${chalk.bold("The ignorer needs its own dependency:")}`);
+            for (const c of apiInstalls) console.log(`      ${chalk.cyan(c)}`);
+            console.log(`      ${chalk.dim("without it the ignorer silently does not load")}`);
+          }
+        }
+      }
+    }
+  }
+
+}

package/lib/setup-hook.mjs

@@ -1,3 +1,4 @@
+import { registerHooks } from "./hook-settings.mjs";
 import { mkdir, writeFile, readFile, chmod, unlink } from "node:fs/promises";
 import { join, resolve, dirname } from "node:path";
 import { spawn } from "node:child_process";
@@ -90,18 +91,6 @@ export async function writeGauntletConf(targetDir, testCommand) {
   return confPath;
 }
 
-// Register the entry, or CORRECT the one already there. Skipping when a hook of
-// this name exists leaves an existing install pinned to whatever matcher it was
-// first written with — which is how the skill gates kept watching only
-// Write|Edit|MultiEdit after they learned to cover Bash.
-function upsert(list, filename, entry) {
-  const existing = list.find((e) => e.hooks?.some((h) => h.command?.endsWith(filename)));
-  if (!existing) return list.push(entry);
-  if (entry.matcher === undefined) delete existing.matcher;
-  else existing.matcher = entry.matcher;
-  existing.hooks = entry.hooks;
-}
-
 export async function setupHook(targetDir = process.cwd()) {
   const resolved = resolve(targetDir);
   const hooksDir = join(resolved, ".claude", "hooks");
@@ -129,115 +118,7 @@ export async function setupHook(targetDir = process.cwd()) {
     // not present — fine
   }
 
-  let settings = {};
-  try {
-    settings = JSON.parse(await readFile(settingsPath, "utf-8"));
-  } catch {
-    // missing or invalid — start fresh
-  }
-  if (!settings.hooks) settings.hooks = {};
-
-  // Clean up legacy UserPromptSubmit eval hook (replaced by the gate).
-  if (Array.isArray(settings.hooks.UserPromptSubmit)) {
-    settings.hooks.UserPromptSubmit = settings.hooks.UserPromptSubmit.filter(
-      (entry) => !entry.hooks?.some((h) => h.command?.endsWith(LEGACY_EVAL_FILENAME))
-    );
-    if (settings.hooks.UserPromptSubmit.length === 0) {
-      delete settings.hooks.UserPromptSubmit;
-    }
-  }
-
-  // Clean up legacy PreToolUse audit-runner hook (2.3.x — removed in 2.4.0).
-  if (Array.isArray(settings.hooks.PreToolUse)) {
-    settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
-      (entry) => !entry.hooks?.some((h) => h.command?.endsWith(LEGACY_AUDIT_RUNNER_FILENAME))
-    );
-  }
-
-  // Register PreToolUse gate.
-  const gateCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${GATE_FILENAME}`;
-  const gateEntry = {
-    matcher: "Write|Edit|MultiEdit|Bash",
-    hooks: [{ type: "command", command: gateCommand }],
-  };
-
-  if (Array.isArray(settings.hooks.PreToolUse)) {
-    upsert(settings.hooks.PreToolUse, GATE_FILENAME, gateEntry);
-  } else {
-    settings.hooks.PreToolUse = [gateEntry];
-  }
-
-  // Register PreToolUse application gate (after the loading gate).
-  const applicationCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${APPLICATION_GATE_FILENAME}`;
-  const applicationEntry = {
-    matcher: "Write|Edit|MultiEdit|Bash",
-    hooks: [{ type: "command", command: applicationCommand }],
-  };
-  upsert(settings.hooks.PreToolUse, APPLICATION_GATE_FILENAME, applicationEntry);
-
-  // Register PreToolUse ship-gate receipt check on Bash.
-  const shipGateCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${SHIP_GATE_HOOK_FILENAME}`;
-  const shipGateEntry = {
-    matcher: "Bash",
-    hooks: [{ type: "command", command: shipGateCommand }],
-  };
-  upsert(settings.hooks.PreToolUse, SHIP_GATE_HOOK_FILENAME, shipGateEntry);
-
-  // Register PostToolUse auto-mark on Skill.
-  const autoMarkCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${AUTO_MARK_FILENAME}`;
-  const autoMarkEntry = {
-    matcher: "Skill",
-    hooks: [{ type: "command", command: autoMarkCommand }],
-  };
-
-  if (Array.isArray(settings.hooks.PostToolUse)) {
-    upsert(settings.hooks.PostToolUse, AUTO_MARK_FILENAME, autoMarkEntry);
-  } else {
-    settings.hooks.PostToolUse = [autoMarkEntry];
-  }
-
-  // Register SessionStart version check. No matcher: startup and resume both
-  // want it, and the script's own daily stamp keeps a burst of resumes quiet.
-  const versionCheckCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${VERSION_CHECK_FILENAME}`;
-  const versionCheckEntry = { hooks: [{ type: "command", command: versionCheckCommand }] };
-
-  if (Array.isArray(settings.hooks.SessionStart)) {
-    upsert(settings.hooks.SessionStart, VERSION_CHECK_FILENAME, versionCheckEntry);
-  } else {
-    settings.hooks.SessionStart = [versionCheckEntry];
-  }
-
-  // Register Stop gauntlet hook.
-  const gauntletCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${GAUNTLET_FILENAME}`;
-  const gauntletEntry = { hooks: [{ type: "command", command: gauntletCommand }] };
-
-  if (Array.isArray(settings.hooks.Stop)) {
-    upsert(settings.hooks.Stop, GAUNTLET_FILENAME, gauntletEntry);
-  } else {
-    settings.hooks.Stop = [gauntletEntry];
-  }
-
-  // Both gates clear by touching a marker under /tmp. The hook scripts let those
-  // commands through themselves, but auto mode's permission classifier does not:
-  // a touch whose only purpose is to unlock a gate is exactly what it refuses.
-  // So in auto mode the application gate could not be satisfied at all, and the
-  // model was reduced to asking its user to run the touch by hand — which is
-  // indistinguishable from the laundering the classifier exists to stop.
-  // Allowlisting the three marker paths is what makes the gates workable there.
-  // Only these literal prefixes are granted, and an existing entry is not
-  // duplicated on reinstall.
-  const MARKER_ALLOW = [
-    "Bash(touch /tmp/claude-skill-gate-*)",
-    "Bash(touch /tmp/claude-skill-acked-*)",
-    "Bash(touch /tmp/claude-skill-loaded-*)",
-  ];
-  if (!settings.permissions) settings.permissions = {};
-  if (!Array.isArray(settings.permissions.allow)) settings.permissions.allow = [];
-  for (const rule of MARKER_ALLOW) {
-    if (!settings.permissions.allow.includes(rule)) settings.permissions.allow.push(rule);
-  }
-
-  await writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", { mode: 0o644 });
+  await registerHooks(settingsPath);
 
   console.log(`  Hook installed: .claude/hooks/${GATE_FILENAME}`);
   console.log(`  Hook installed: .claude/hooks/${AUTO_MARK_FILENAME}`);
@@ -246,82 +127,4 @@ export async function setupHook(targetDir = process.cwd()) {
   console.log(`  Installed: .claude/hooks/${SHIP_GATE_FILENAME} (used by /ship)`);
   console.log(`  Hook installed: .claude/hooks/${SHIP_GATE_HOOK_FILENAME}`);
   console.log(`  Settings updated: .claude/settings.json`);
-}
-
-// The project-level permissions.allow written above does not clear auto mode.
-// The classifier reads autoMode.allow, and only from the user's own
-// ~/.claude/settings.json — it deliberately ignores a project's settings so a
-// cloned repo cannot loosen it. So the gate's ack was denied, and the remedy the
-// deny message named could not be applied by the agent either: the classifier
-// refuses an agent editing permission settings by any route. That left a
-// deadlock nothing in the session could break. The installer can, because npx
-// runs as the user, not as an agent — but only ever behind an explicit prompt,
-// since this is the user's global file.
-export const AUTO_MODE_RULE =
-  "Touching marker files under /tmp/claude-skill-gate-*, /tmp/claude-skill-acked-* " +
-  "and /tmp/claude-skill-loaded-* is allowed: they are acknowledgement files for the " +
-  "user's own PreToolUse skill gates. Creating one satisfies a workflow gate the user " +
-  "installed, grants no permission and executes no code, and is a false positive for " +
-  "Auto-Mode Bypass.";
-
-// Any entry naming a marker path is ours, whatever wording it shipped with. An
-// upgrade must correct that entry rather than add a second one beside it —
-// a fresh-install test would never see the difference.
-const AUTO_MODE_RULE_MARK = "/tmp/claude-skill-acked-";
-
-function globalSettingsPath(homeDir) {
-  return join(homeDir ?? homedir(), ".claude", "settings.json");
-}
-
-async function readGlobalSettings(homeDir) {
-  try {
-    return JSON.parse(await readFile(globalSettingsPath(homeDir), "utf-8"));
-  } catch {
-    return null;
-  }
-}
-
-// "current" — the rule is present and matches. "stale" — an older wording is
-// there. "missing" — nothing of ours. "unreadable" — the file exists but does
-// not parse, so we must not rewrite it.
-export async function autoModeRuleStatus(homeDir) {
-  let raw;
-  try {
-    raw = await readFile(globalSettingsPath(homeDir), "utf-8");
-  } catch {
-    return "missing";
-  }
-  let settings;
-  try {
-    settings = JSON.parse(raw);
-  } catch {
-    return "unreadable";
-  }
-  const allow = settings?.autoMode?.allow;
-  if (!Array.isArray(allow)) return "missing";
-  if (allow.includes(AUTO_MODE_RULE)) return "current";
-  if (allow.some((r) => typeof r === "string" && r.includes(AUTO_MODE_RULE_MARK))) return "stale";
-  return "missing";
-}
-
-// Writes the rule into ~/.claude/settings.json, keeping "$defaults" first —
-// dropping it discards every built-in allow. Everything else in the file is
-// preserved. Refuses an unparseable file rather than replacing it.
-export async function writeAutoModeRule(homeDir) {
-  if ((await autoModeRuleStatus(homeDir)) === "unreadable") {
-    throw new Error(`${globalSettingsPath(homeDir)} is not valid JSON — fix it, then re-run.`);
-  }
-  const settings = (await readGlobalSettings(homeDir)) ?? {};
-  if (!settings.autoMode || typeof settings.autoMode !== "object") settings.autoMode = {};
-  const existing = Array.isArray(settings.autoMode.allow) ? settings.autoMode.allow : [];
-
-  const kept = existing.filter(
-    (r) => r !== "$defaults" && !(typeof r === "string" && r.includes(AUTO_MODE_RULE_MARK)),
-  );
-  settings.autoMode.allow = ["$defaults", ...kept, AUTO_MODE_RULE];
-
-  const path = globalSettingsPath(homeDir);
-  await mkdir(dirname(path), { recursive: true });
-  await writeFile(path, JSON.stringify(settings, null, 2) + "\n", { mode: 0o600 });
-  return path;
-}
+}

package/lib/tool-needs.mjs

@@ -0,0 +1,123 @@
+// What the installed commands need that this project does not have — a report,
+// not an install. Nothing to do with reading a local catalog, which is what the
+// rest of local.mjs was for; they shared a file and nothing else.
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { listDir } from "./local.mjs";
+
+const exec = promisify(execFile);
+
+
+// Build output is not a project. Next.js writes a package.json into .next/,
+// .next/dev/ and .next/standalone/, so a scan that skipped only a hardcoded
+// list reported three phantom projects on a plain Next app — and then filtered
+// the real repo root out as "a root that delegates to a workspace". A second
+// list of build dirs drifts from .gitignore the moment a framework adds one, so
+// ask git the way ship-gate.sh already does. --directory collapses a fully
+// ignored tree to its own name, which is what keeps this output small.
+async function gitIgnoredDirs(projectDir) {
+  try {
+    const { stdout } = await exec(
+      "git",
+      ["-C", projectDir, "ls-files", "--others", "--ignored", "--exclude-standard", "--directory"],
+      { maxBuffer: 10 * 1024 * 1024 },
+    );
+    return new Set(
+      stdout.split("\n").filter((l) => l.endsWith("/")).map((l) => l.slice(0, -1)),
+    );
+  } catch {
+    return new Set();
+  }
+}
+
+
+
+// What the installed commands need that this project does not have yet.
+// ship-gate.sh's own detection drives a single-package repo; a monorepo whose
+// tools need a workspace prefix or a container sets GAUNTLET_MUTATE instead. Only
+// /ship needs anything: a mutation tool, per project, since a monorepo can hold
+// several and they do not share one.
+export async function reportToolNeeds(projectDir) {
+  const needs = [];
+  const seen = new Set();
+  // Whether a nested project of each kind exists at all — not whether it still
+  // needs a tool. A root that delegates is not the place to install, even once
+  // the workspace it delegates to is already set up.
+  const nested = { Stryker: false, mutmut: false };
+  // Empty outside a git repo, so the hardcoded list below still carries those.
+  const ignored = await gitIgnoredDirs(projectDir);
+
+  async function scan(rel, depth) {
+    if (depth > 2) return;
+    const dir = rel ? join(projectDir, rel) : projectDir;
+    const entries = await listDir(dir);
+    const label = rel ? `${rel}/` : "<repo root>";
+
+    const pkg = entries.find((e) => e.isFile() && e.name === "package.json");
+    const pyp = entries.find((e) => e.isFile() && (e.name === "pyproject.toml" || e.name === "pytest.ini"));
+
+    if (pkg && rel) nested.Stryker = true;
+    if (pyp && rel) nested.mutmut = true;
+
+    if (pkg && !seen.has(label)) {
+      seen.add(label);
+      const text = await readFile(join(dir, "package.json"), "utf-8");
+      if (!text.includes("@stryker-mutator/core")) {
+        const at = rel ? rel + "/" : "";
+        needs.push({
+          label,
+          rel,
+          tool: "Stryker",
+          install: `npm --prefix ${rel || "."} i -D @stryker-mutator/core @stryker-mutator/vitest-runner`,
+          config: `${at}stryker.config.json  {"testRunner":"vitest","plugins":["@stryker-mutator/vitest-runner"],"coverageAnalysis":"perTest"}`,
+          // Stryker copies the whole project into .stryker-tmp/sandbox-*/, so
+          // every test file briefly exists twice and the runner collects both.
+          // The duplicates pass, so a doubled test count is the only symptom.
+          // Spread configDefaults.exclude — assigning it drops node_modules.
+          also: [
+            `${at}vitest.config.ts  exclude: [...configDefaults.exclude, "**/.stryker-tmp/**"]`,
+            `${at}.gitignore  .stryker-tmp/`,
+          ],
+        });
+      } else {
+        // Stryker is installed, so this project is not missing a tool — but the
+        // projects that already run it are the ones grinding through mutants on
+        // className strings, and a setup done before the ignorer existed has no
+        // way to learn about it. Offer it here or it never reaches them.
+        let cfg = "";
+        try {
+          cfg = await readFile(join(dir, "stryker.config.json"), "utf-8");
+        } catch {
+          // no config of its own — the scaffolder writes one
+        }
+        if (!cfg.includes("tailwind-classnames")) {
+          needs.push({ label, rel, tool: "Stryker", ignorerOnly: true });
+        }
+      }
+    }
+    if (pyp && !seen.has(label + ":py")) {
+      seen.add(label + ":py");
+      const text = pyp.name === "pyproject.toml" ? await readFile(join(dir, "pyproject.toml"), "utf-8") : "";
+      if (!text.includes("[tool.mutmut]")) {
+        const advice = await pythonAdvice(dir, rel, entries);
+        needs.push({ label, tool: "mutmut", ...advice });
+      }
+    }
+
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      if (["node_modules", ".git", "dist", "build", ".venv", "venv", ".claude"].includes(e.name)) continue;
+      const child = rel ? `${rel}/${e.name}` : e.name;
+      if (ignored.has(child)) continue;
+      await scan(child, depth + 1);
+    }
+  }
+
+  await scan("", 0);
+
+  // A root package.json that delegates to a workspace (npm --prefix web run test)
+  // has no tests of its own, so asking for a mutation tool there is noise.
+  return needs.filter((n) => n.label !== "<repo root>" || !nested[n.tool]);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spardutti/claude-skills",
-  "version": "2.32.0",
+  "version": "2.32.2",
   "description": "Guardrails for Claude Code — best-practice skills, planning commands, and delivery gates.",
   "type": "module",
   "repository": {