@spardutti/claude-skills 2.11.0 → 2.12.0

package/README.md

@@ -88,7 +88,7 @@ Cross-cutting craft — applies to any stack, any language.
 | `code-structure` 📦 | Single Responsibility (when to split) + Avoid Hasty Abstractions (when *not* to extract) — hard size limits, separation of concerns, the Rule of Three |
 | `debugging` | Root cause before patching — reproduce, trace the failure backward to its origin, one hypothesis at a time, the 3-attempts-then-question-the-design rule |
 | `typescript-best-practices` | TypeScript 7.x — type design, generics, type guards, `satisfies`, `using`, error handling, `tsconfig` |
-| `testing-best-practices` | Arrange-Act-Assert, factory-based test data, isolation, mocking boundaries, a pyramid-balanced suite |
+| `testing-best-practices` 📦 | Arrange-Act-Assert, factory-based test data, isolation, mocking boundaries, a pyramid-balanced suite; bundle covers mutation testing — Stryker and mutmut setup, diff-scoped runs, the traps, and working score thresholds |
 | `security-practices` | OWASP Top 10 prevention, input validation, auth, SQL injection, XSS, CSRF, secure defaults |
 
 ## Commands
@@ -97,7 +97,7 @@ Portable slash commands installed to `.claude/commands/`. Some orchestrate paral
 
 | Command | What it does |
 |---------|--------------|
-| `/ship` | Unified delivery pipeline — commit → PR → merge → release. No argument steps through interactively; `/ship pr` runs through PR creation; `/ship release` runs the full pipeline |
+| `/ship` | Unified delivery pipeline — gate → commit → PR → merge → release. The gate is the one enforcement moment: it checks the diff's file lengths, audits it against the skills installed in the project, and mutation-tests the changed lines to prove the tests would catch a break — **fixing what it finds** rather than handing you a list. `--force` skips it. No argument steps through interactively; `/ship pr` runs through PR creation; `/ship release` runs the full pipeline |
 | `/discover` | Find the right problem before deciding what to build — diverges first: names competing interpretations of what you said, stress-tests the framing with a blind critic subagent, then converges on a mental model. Run before `/preplan` |
 | `/preplan` | Resolve a fuzzy feature idea into concrete decisions — 6 fixed phases, one question at a time, ends with a decision log. Run before `/plan-feature` |
 | `/plan-feature` | Integration-first feature planning — 3 parallel subagents scan for reusable code, patterns, and touch points before producing a short plan |
@@ -126,6 +126,13 @@ Every install writes a manifest at `.claude/.claude-skills.json` recording what
 npx @spardutti/claude-skills --sync
 ```
 
+`--local[=path]` reads the catalog from a working copy instead of GitHub, so an unreleased
+change can be installed and tried without publishing it first:
+
+```bash
+node ~/projects/claude-skills/cli/bin/cli.mjs --local
+```
+
 `--sync` refreshes every tracked item to the latest catalog and prunes stale ones in one shot — no menu. For a project that predates the manifest, the first normal run offers a one-time cleanup of `.claude/` content no longer in the catalog.
 
 ### Automatic Skill Evaluation
@@ -139,9 +146,10 @@ It installs four hooks and appends a rule to your `CLAUDE.md`. Three guard the
 - `skill-application-gate.sh` — a second `PreToolUse` gate requiring each loaded skill to be applied, not just read
 - `skill-gate-automark.sh` — a `PostToolUse` hook on `Skill` that clears the gate
 
-The fourth guards the **back** — nothing finishes until the code passes:
+The last two guard the **back** — nothing finishes or ships until the code passes:
 
 - `gauntlet.sh` — a `Stop` hook running the fast gates on your changed files (see [Automatic Verification](#automatic-verification-gauntlet))
+- `ship-gate-hook.sh` — a `PreToolUse` gate on `Bash` that refuses `git commit` and `git push` without a receipt from `ship-gate.sh`
 
 <details>
 <summary>How the gate works</summary>
@@ -174,9 +182,12 @@ It registers in `.claude/settings.json`:
 ### Automatic Verification (Gauntlet)
 
 The same install adds `gauntlet.sh` — a `Stop` hook that runs the cheap, deterministic
-gates on your changed files every time Claude finishes a turn. Green is silent; red returns
-`{"decision":"continue"}` so the turn doesn't end, handing the failure back to Claude to
-fix before you ever see it.
+gates on your changed files every time Claude finishes a turn. Green is silent; red exits 2,
+which keeps the turn from ending, shows you the failure, and hands it to Claude to fix.
+
+Exit 2 matters: `{"decision":"continue"}` also keeps the turn going, but its reason reaches
+Claude alone. A failing gate was then invisible from the outside — indistinguishable from a
+gauntlet that does nothing.
 
 Keep the gates fast for a reason beyond patience: a `command` hook that reaches its timeout
 (600s by default) is cancelled and its **output discarded**, so the turn ends as if the hook
@@ -207,6 +218,12 @@ It runs a skip ladder first, cheapest check first, and quits at the first "no":
 
 Rule 3 is what makes repeated `/ship` runs free: the gates run once per distinct diff.
 
+To confirm it is alive when everything is green — green prints nothing, by design:
+
+```bash
+ls -t /tmp/claude-gauntlet-*.why | head -1 | xargs cat
+```
+
 Every run records why it ended in `/tmp/claude-gauntlet-<session>.why`, so a green run
 and a skipped one are told apart without re-running the hook. `GAUNTLET_DEBUG=1` prints
 the same line to stderr:
@@ -257,11 +274,20 @@ a config file — two are read, in this order, and the project's wins key by key
 GAUNTLET_OFF=1                       # disable entirely
 GAUNTLET_TYPECHECK='npm run check'   # "" to skip the gate
 GAUNTLET_TEST='npm test -- $FILES'   # $FILES = changed code files
-GAUNTLET_CODE_EXT='ts|tsx|py'        # what counts as code
+GAUNTLET_CODE_EXT='ts|tsx|py'        # what counts as a change worth checking
 GAUNTLET_DEBUG=1                     # print the outcome to stderr every run
 GAUNTLET_REQUIRE_TESTS=1             # block when the runner matched 0 test files
+
+# /ship's gate reads its own keys from the same file
+GAUNTLET_MAX_LINES=200               # per-file limit; 0 turns the check off
+GAUNTLET_SOURCE_EXT='ts|tsx|py'      # what counts as SOURCE — not the same question
+GAUNTLET_MUTATE='bash mutate.sh'     # replace per-project mutation detection
 ```
 
+`GAUNTLET_SOURCE_EXT` is separate from `GAUNTLET_CODE_EXT` on purpose. The Stop hook asks
+"did anything worth checking change", so a docs repo sets `CODE_EXT` to include `.md`. The
+line limit and mutation ask about source code, where that answer is wrong.
+
 Set your house rules once in `~/.claude/gauntlet.conf`; only reach for the project file
 where a repo does something unusual (or set `GAUNTLET_OFF=1` there to opt one out).
 
@@ -304,6 +330,8 @@ commands/      Slash commands installed to .claude/commands/
 agents/        Subagent definitions — commands declare which they need via requires-agents
 scripts/       validate-skills.mjs — checks skill length caps and reference integrity
                gauntlet.sh — the Stop-hook verification gates, embedded by the CLI
+               ship-gate.sh — /ship's file-length and mutation checks, behind an exit code
+               ship-gate-hook.sh — refuses git commit/push without a ship-gate receipt
                gauntlet-selftest.sh — 15 behavioural tests for the hook (runs on pre-push)
                gauntlet-survey.sh — what the hook would do in every repo under a directory
 cli/           The npm installer (npx @spardutti/claude-skills); version in cli/package.json

package/bin/cli.mjs

@@ -9,6 +9,7 @@ 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 } from "../lib/setup-hook.mjs";
+import { makeLocalSource, reportToolNeeds } from "../lib/local.mjs";
 import { setupClaudeMd } from "../lib/setup-claude-md.mjs";
 import {
   readManifest, writeManifest, computeOrphans, computeRemovals, scanInstalled, removeArtifacts,
@@ -50,10 +51,24 @@ async function runSync(manifest, catalog) {
 
 async function main() {
   const isSync = process.argv.includes("--sync");
+
+  // --local[=path] reads the catalog from a working copy instead of GitHub, so an
+  // unreleased change can be installed and tried without publishing it first.
+  const localArg = process.argv.find((a) => a === "--local" || a.startsWith("--local="));
+  const localRoot = localArg ? (localArg.split("=")[1] || join(__dirname, "..", "..")) : null;
+
   console.log(`\n  ${chalk.bold.cyan("Claude Skills Installer")} ${chalk.dim(`v${pkg.version}`)}\n`);
 
-  console.log(chalk.dim("  Fetching available skills, commands, and agents...\n"));
-  const [skills, commands, agents] = await Promise.all([fetchSkills(), fetchCommands(), fetchAgents()]);
+  let fetchers = { fetchSkills, fetchCommands, fetchAgents };
+  if (localRoot) {
+    fetchers = makeLocalSource(localRoot);
+    console.log(`  ${chalk.yellow("LOCAL")} ${chalk.dim(`reading the catalog from ${localRoot}`)}\n`);
+  } else {
+    console.log(chalk.dim("  Fetching available skills, commands, and agents...\n"));
+  }
+  const [skills, commands, agents] = await Promise.all([
+    fetchers.fetchSkills(), fetchers.fetchCommands(), fetchers.fetchAgents(),
+  ]);
   const catalog = { skills, commands, agents };
   const manifest = await readManifest(CWD);
 
@@ -158,10 +173,12 @@ async function main() {
       await setupClaudeMd();
 
       // Report what the gauntlet will actually run, so a silent no-op is visible.
-      const { test, typecheck } = await detectStack(CWD);
-      if (test) {
-        const found = [typecheck, test].filter(Boolean).join(" + ");
-        console.log(`  ${chalk.dim(`Gauntlet detected ${found} — it will run those on changed files.`)}`);
+      // 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();
@@ -180,6 +197,27 @@ async function main() {
     }
   }
 
+  // --- 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) {
+        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)}`);
+      }
+    }
+  }
+
   // --- Record what is now installed ---
   await writeManifest(CWD, {
     catalogVersion: pkg.version,

package/lib/local.mjs

@@ -0,0 +1,171 @@
+// Local catalog source — the same shape github.mjs returns, read from a working
+// copy instead of GitHub. Testing an unreleased change should not require
+// publishing it first.
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+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) {
+  try { return await readdir(dir, { withFileTypes: true }); } catch { return []; }
+}
+
+export function makeLocalSource(root) {
+  return {
+    async fetchSkills() {
+      const out = [];
+      for (const d of await listDir(join(root, "skills"))) {
+        if (!d.isDirectory()) continue;
+        const dirPath = join(root, "skills", d.name);
+        const files = (await listDir(dirPath)).filter((f) => f.isFile());
+        const skillFile = files.find((f) => f.name === "SKILL.md");
+        if (!skillFile) continue;
+        const content = await readFile(join(dirPath, "SKILL.md"), "utf-8");
+        const peerFiles = [];
+        for (const f of files) {
+          if (f.name === "SKILL.md") continue;
+          peerFiles.push({
+            name: f.name,
+            content: await readFile(join(dirPath, f.name), "utf-8"),
+            executable: f.name.endsWith(".sh"),
+          });
+        }
+        const { name, description, category } = parseFrontmatter(content, d.name);
+        out.push({ dirName: d.name, name, description, category, content, peerFiles });
+      }
+      return out;
+    },
+
+    async fetchCommands() {
+      const out = [];
+      for (const f of await listDir(join(root, "commands"))) {
+        if (!f.isFile() || !f.name.endsWith(".md")) continue;
+        const content = await readFile(join(root, "commands", f.name), "utf-8");
+        const { name, description, category, requiresAgents } = parseFrontmatter(content, f.name.replace(/\.md$/, ""));
+        out.push({ fileName: f.name, name, description, category, requiresAgents, content });
+      }
+      return out;
+    },
+
+    async fetchAgents() {
+      const out = [];
+      for (const f of await listDir(join(root, "agents"))) {
+        if (!f.isFile() || !f.name.endsWith(".md")) continue;
+        const content = await readFile(join(root, "agents", f.name), "utf-8");
+        const { name } = parseFrontmatter(content, f.name.replace(/\.md$/, ""));
+        out.push({ fileName: f.name, name, content });
+      }
+      return out;
+    },
+  };
+}
+
+// mutmut's config has to name the real source and test directories, and the
+// install command has to match how the project actually manages dependencies —
+// `pip install` into a uv project puts it somewhere the container rebuild loses.
+async function pythonAdvice(dir, rel, entries) {
+  const has = (n) => entries.some((e) => e.name === n);
+  const pyproject = has("pyproject.toml") ? await readFile(join(dir, "pyproject.toml"), "utf-8") : "";
+
+  let install = "pip install mutmut";
+  if (has("uv.lock") || /^\[tool\.uv\]/m.test(pyproject)) install = "uv add --dev mutmut";
+  else if (has("poetry.lock")) install = "poetry add --group dev mutmut";
+
+  // Source: the package directory, not a guess. Skip the ones that are never it.
+  const ignore = ["tests", "test", "alembic", "migrations", "db", "e2e", "__pycache__", ".venv", "venv", "scripts"];
+  const dirs = entries.filter((e) => e.isDirectory() && !e.name.startsWith(".") && !ignore.includes(e.name));
+  const source = (dirs.find((d) => d.name === "src") || dirs.find((d) => d.name === "app") || dirs[0])?.name || "src";
+
+  // Tests: pytest already knows where they are.
+  const testpaths = pyproject.match(/testpaths\s*=\s*\[([^\]]*)\]/);
+  const tests = testpaths ? testpaths[1].replace(/["'\s]/g, "").split(",")[0] : "tests";
+
+  return {
+    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 };
+
+  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,
+          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/`,
+          ],
+        });
+      }
+    }
+    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;
+      await scan(rel ? `${rel}/${e.name}` : e.name, 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/setup-hook.mjs

@@ -1,5 +1,6 @@
 import { mkdir, writeFile, readFile, chmod, unlink } from "node:fs/promises";
 import { join, resolve, dirname } from "node:path";
+import { spawn } from "node:child_process";
 
 // PreToolUse gate on Write|Edit|MultiEdit. Blocks the tool call unless
 // a per-session marker file exists at /tmp/claude-skill-gate-<SESSION_ID>.
@@ -161,9 +162,8 @@ exit 0
 const GAUNTLET_SCRIPT = `#!/usr/bin/env bash
 # gauntlet.sh — Stop hook: fast deterministic gates on the changed diff.
 #
-# Runs when Claude finishes a turn. Silent when green. On a red gate it returns
-# {"decision":"continue"} so the turn does not end, handing the failure back to
-# Claude to fix before the user sees it.
+# Runs when Claude finishes a turn. Silent when green. On a red gate it exits 2:
+# the turn keeps going, the user is shown why, and Claude is handed the failure.
 #
 # Two things the hook contract makes non-negotiable:
 #   - stop_hook_active must short-circuit, or a red gate loops forever.
@@ -239,7 +239,10 @@ CHANGED=$( { git diff --name-only HEAD 2>/dev/null; \\
 if [ -z "$CHANGED" ] && [ -z "\${GAUNTLET_DRYRUN:-}" ]; then quit "skipped: no changed files"; fi
 
 # ---------------------------------------------------------------- skip rule 2
-FILES_NL=$(printf '%s\\n' "$CHANGED" | grep -E "\\.($GAUNTLET_CODE_EXT)$" || true)
+# .stryker-tmp holds Stryker's sandbox — a full copy of the project. A crashed
+# run leaves it behind, and then every file in it looks like a changed file.
+FILES_NL=$(printf '%s\\n' "$CHANGED" | grep -E "\\.($GAUNTLET_CODE_EXT)$" \\
+           | grep -vE '(^|/)\\.stryker-tmp/' || true)
 if [ -z "$FILES_NL" ] && [ -z "\${GAUNTLET_DRYRUN:-}" ]; then
   quit "skipped: no changed code files (docs/config only)"
 fi
@@ -444,6 +447,325 @@ $FILES
 --- $FAILED output (last 60 lines) ---
 $TAIL"
 
+printf '%s\\n' "red: the $FAILED gate failed" > "$WHY" 2>/dev/null
+
+# Exit 2 is the only path where a red is visible to the user: its stderr is shown
+# to them as the reason the turn is continuing. Exit 0 with {"decision":"continue"}
+# also keeps the turn going, but the reason reaches Claude alone — so a failing
+# gate looked, from the outside, exactly like a gauntlet that does nothing.
+printf '%s\\n' "$MSG" >&2
+exit 2
+`;
+
+// The deterministic half of /ship's quality gate: file length and mutation,
+// behind an exit code rather than in prose a model can talk past.
+// Canonical source: scripts/ship-gate.sh.
+const SHIP_GATE_SCRIPT = `#!/usr/bin/env bash
+# ship-gate.sh — the deterministic half of /ship's quality gate.
+#
+# File length and mutation are not judgement calls, so they do not live in prose
+# where a model can decide they are not worth it. They live here, behind an exit
+# code. /ship runs this and obeys the result; the skills audit stays in the
+# command, because that one genuinely needs a model.
+#
+#   bash .claude/hooks/ship-gate.sh [base-ref]
+#   bash .claude/hooks/ship-gate.sh --key      print the receipt key and stop
+#   bash .claude/hooks/ship-gate.sh --force    write a FORCED receipt, run nothing
+#
+# On completion it writes a RECEIPT at /tmp/claude-shipgate-<key>, and the
+# PreToolUse hook refuses \`git commit\` / \`git push\` without a matching one. The
+# point is that a gate has to be evidence rather than an instruction: a sentence
+# saying "run this first" is a sentence an agent can decide is not worth it, and
+# then report a pass it never earned. A receipt cannot be reported, only produced.
+#
+# The key is the content of everything about to ship, so it is the same before
+# and after \`git commit\` — and it changes the moment anything is edited, which is
+# what makes a fix re-gate itself instead of riding on the previous verdict.
+#
+# Exit codes:
+#   0  clean — nothing over the line limit, no surviving mutants
+#   1  findings that must be dealt with before shipping
+#   2  ran, but could not prove the tests (a mutation tool is missing) — report,
+#      don't block; the output names exactly what to install and where
+#
+# Config: the same .claude/gauntlet.conf as the Stop hook.
+#   GAUNTLET_MAX_LINES=200   the per-file limit; 0 turns the check off
+#   GAUNTLET_SOURCE_EXT=...  which extensions count as source. Deliberately NOT
+#                            GAUNTLET_CODE_EXT: the Stop hook's key answers a
+#                            different question, and a docs repo sets it to .md
+#   GAUNTLET_MUTATE="cmd"    one explicit mutation command for the whole repo,
+#                            replacing per-project detection. $MUTATE_FLAGS holds
+#                            the --mutate flags, $FILES the changed files.
+
+set -uo pipefail
+
+MODE=""
+case "\${1:-}" in --key) MODE=key; shift ;; --force) MODE=force; shift ;; esac
+
+PROJECT_DIR="\${CLAUDE_PROJECT_DIR:-$PWD}"
+cd "$PROJECT_DIR" 2>/dev/null || { echo "ship-gate: cannot read $PROJECT_DIR"; exit 1; }
+git rev-parse --git-dir >/dev/null 2>&1 || { echo "ship-gate: not a git repo"; exit 1; }
+
+GAUNTLET_MAX_LINES=200
+GAUNTLET_MUTATE=""
+GAUNTLET_SOURCE_EXT="ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|c|h|cpp|hpp|cs|swift"
+[ -n "\${HOME:-}" ] && [ -f "$HOME/.claude/gauntlet.conf" ] && . "$HOME/.claude/gauntlet.conf"
+[ -f ".claude/gauntlet.conf" ] && . ".claude/gauntlet.conf"
+
+# ------------------------------------------------------------------- the scope
+BASE="\${1:-}"
+if [ -z "$BASE" ]; then
+  BASE=$(git merge-base HEAD develop 2>/dev/null \\
+         || git merge-base HEAD main 2>/dev/null \\
+         || git rev-list --max-parents=0 HEAD | head -1)
+fi
+
+CHANGED=$( { git diff "$BASE"...HEAD --name-only 2>/dev/null
+             git diff HEAD --name-only 2>/dev/null
+             git ls-files --others --exclude-standard 2>/dev/null; } | sort -u )
+
+# The repo path plus the names and contents of the changed files, in a fixed
+# order. The path is in there because the key is otherwise pure content: two
+# repos holding the same file would share a receipt, and one would be waved
+# through on the other's verdict. Deliberately not a diff: a file moves from "untracked" to "in the diff" at commit time, so a
+# diff-based key changes when the content did not, and the receipt would go stale
+# the moment it was committed. This is identical either side of a commit, and
+# changes the instant any of those files is edited.
+RECEIPT_KEY=$( { printf '%s\\n' "$PROJECT_DIR"
+                 printf '%s\\n' "$CHANGED" | while IFS= read -r f; do
+                   [ -n "$f" ] || continue
+                   printf '%s\\n' "$f"
+                   [ -f "$f" ] && cat "$f"
+                 done; } | git hash-object --stdin )
+RECEIPT="/tmp/claude-shipgate-$RECEIPT_KEY"
+
+if [ "$MODE" = key ]; then printf '%s\\n' "$RECEIPT_KEY"; exit 0; fi
+if [ "$MODE" = force ]; then
+  printf 'FORCED %s\\n' "$(date -u +%FT%TZ)" > "$RECEIPT"
+  echo "ship-gate: FORCED — receipt written without running any check."
+  exit 0
+fi
+FILES=$(printf '%s\\n' "$CHANGED" | grep -E "\\.($GAUNTLET_SOURCE_EXT)$" \\
+        | grep -vE '(\\.|_)(test|spec)\\.[^.]+$|(^|/)tests?/|(^|/)\\.stryker-tmp/' | while read -r f; do
+          [ -f "$f" ] && printf '%s\\n' "$f"
+        done)
+
+if [ -z "$FILES" ]; then
+  echo "ship-gate: no changed code files — nothing to check"
+  printf 'PASS %s no-code-changes\\n' "$(date -u +%FT%TZ)" > "$RECEIPT"
+  exit 0
+fi
+
+echo "ship-gate: $(printf '%s\\n' "$FILES" | wc -l) changed code file(s), base $(git rev-parse --short "$BASE")"
+echo
+STATUS=0
+
+# ------------------------------------------------- check 1: file length (hard)
+OVER=""
+LARGEST=0
+if [ "$GAUNTLET_MAX_LINES" -gt 0 ]; then
+  while IFS= read -r f; do
+    n=$(wc -l < "$f")
+    [ "$n" -gt "$LARGEST" ] && LARGEST=$n
+    [ "$n" -gt "$GAUNTLET_MAX_LINES" ] && OVER="$OVER  $f — $n lines (limit $GAUNTLET_MAX_LINES)
+"
+  done <<< "$FILES"
+fi
+
+if [ "$GAUNTLET_MAX_LINES" -le 0 ]; then
+  echo "FILE LENGTH — off (GAUNTLET_MAX_LINES=0)"
+elif [ -n "$OVER" ]; then
+  echo "FILE LENGTH — over the limit:"
+  printf '%s' "$OVER"
+  echo "  Splitting a file is a design decision. Do it deliberately, or ship with --force."
+  STATUS=1
+else
+  echo "FILE LENGTH — ok, largest is $LARGEST lines"
+fi
+
+# ---------------------------------------------------------- which project owns
+# A monorepo holds several projects, each with its own runner and its own
+# mutation tool. Walk up from each changed file to the nearest manifest.
+owner_of() {
+  d=$(dirname "$1")
+  while :; do
+    if [ -f "$d/package.json" ] || [ -f "$d/pyproject.toml" ] \\
+       || [ -f "$d/pytest.ini" ] || [ -f "$d/setup.cfg" ]; then
+      printf '%s\\n' "\${d#./}"; return
+    fi
+    [ "$d" = "." ] || [ "$d" = "/" ] && { printf '.\\n'; return; }
+    d=$(dirname "$d")
+  done
+}
+
+OWNERS=$(while IFS= read -r f; do owner_of "$f"; done <<< "$FILES" | sort -u)
+
+# --------------------------------------------- check 2: mutation, per project
+echo
+echo "MUTATION — $(printf '%s\\n' "$OWNERS" | wc -l) project(s) in this diff"
+MISSING=""
+
+for owner in $OWNERS; do
+  [ "$owner" = "." ] && label="<repo root>" || label="$owner/"
+  OWNED=$(while IFS= read -r f; do
+            [ "$(owner_of "$f")" = "$owner" ] && printf '%s\\n' "$f"
+          done <<< "$FILES")
+  [ -z "$OWNED" ] && continue
+
+  # --mutate flags, one per changed hunk. Ranges inside a file are already
+  # comma-separated, so they cannot share a comma-joined list across files.
+  FLAGS=""
+  while IFS= read -r f; do
+    hunks=$(git diff -U0 "$BASE" -- "$f" 2>/dev/null \\
+            | grep -oE '^@@ -[0-9,]+ \\+[0-9]+(,[0-9]+)?' | sed 's/.*+//' \\
+            | while IFS=, read -r s l; do l=\${l:-1}; [ "$l" -gt 0 ] && echo "$s-$((s+l-1))"; done)
+    [ -z "$hunks" ] && hunks="1-$(wc -l < "$f")"
+    rel=\${f#$owner/}
+    for r in $hunks; do FLAGS="$FLAGS --mutate '$rel:$r'"; done
+  done <<< "$OWNED"
+
+  base=""; RUN=""
+  if [ "$owner" != "." ]; then base="$owner/"; RUN="cd '$owner' && "; fi
+  if [ -n "$GAUNTLET_MUTATE" ]; then
+    CMD="$GAUNTLET_MUTATE"; TOOL="config"
+  elif [ -f "$base"package.json ] && grep -qs '@stryker-mutator/core' "$base"package.json; then
+    TOOL="stryker"
+    # From inside the owning package: npx resolves against ITS node_modules, and
+    # stryker.config.json lives there too. A monorepo root usually has neither.
+    CMD="\${RUN}npx --no-install stryker run --incremental --force $FLAGS"
+  elif [ -f "$base"package.json ]; then
+    MISSING="$MISSING  $label needs Stryker:
+      npm --prefix \${owner} i -D @stryker-mutator/core @stryker-mutator/vitest-runner
+      then \${base}stryker.config.json:
+        {\\"testRunner\\":\\"vitest\\",\\"plugins\\":[\\"@stryker-mutator/vitest-runner\\"],\\"coverageAnalysis\\":\\"perTest\\"}
+"
+    continue
+  elif command -v mutmut >/dev/null 2>&1; then
+    TOOL="mutmut"
+    # mutmut takes its scope from [tool.mutmut] in pyproject, not from a flag:
+    # --paths-to-mutate was 2.x, and 3.x filters by fnmatch globs over mutant
+    # NAMES (app.balance.reserve.*). There is no per-line scoping at all.
+    CMD="\${RUN}mutmut run"
+  else
+    MISSING="$MISSING  $label needs mutmut:
+      pip install mutmut
+      then \${base}pyproject.toml:
+        [tool.mutmut]
+        source_paths = [\\"src/\\"]
+        pytest_add_cli_args_test_selection = [\\"tests/\\"]
+      (mutmut 3 renamed these — paths_to_mutate/tests_dir are 2.x and are ignored)
+"
+    continue
+  fi
+
+  OUT=$(eval "$CMD" 2>&1); RC=$?
+  # Match a finding, never a summary row. Stryker prints a \`# survived\` COLUMN
+  # HEADER every run and repeats the word in its table, so a bare grep reports
+  # survivors on a clean run — worse than not running at all. Stryker marks each
+  # real finding \`[Survived]\`; table and border lines are excluded outright.
+  case "$TOOL" in
+    stryker) PATTERN='\\[Survived\\]' ;;
+    *)       PATTERN='[Ss]urvived' ;;
+  esac
+  SURVIVED=$(printf '%s\\n' "$OUT" | grep -E "$PATTERN" \\
+             | grep -vE '^[[:space:]]*[#│|+-]|# *surviv' | head -20)
+  if [ -n "$SURVIVED" ]; then
+    echo "  $label $TOOL — surviving mutants; these lines can break and no test notices:"
+    printf '%s\\n' "$SURVIVED" | sed 's/^/      /'
+    STATUS=1
+  elif [ $RC -ne 0 ]; then
+    echo "  $label $TOOL — the run failed:"
+    printf '%s\\n' "$OUT" | tail -12 | sed 's/^/      /'
+    [ "$STATUS" = 0 ] && STATUS=2
+  else
+    echo "  $label $TOOL — ok, no surviving mutants in the changed lines"
+  fi
+done
+
+if [ -n "$MISSING" ]; then
+  echo "  UNPROVEN — no mutation tool for these, so their tests were never shown"
+  echo "  to catch a break. Install per project:"
+  printf '%s' "$MISSING"
+  [ "$STATUS" = 0 ] && STATUS=2
+fi
+
+# The receipt is written by this script and nothing else. A hand-rolled check
+# produces no receipt, which is the whole point: substituting a weaker check is
+# a choice that can be argued for, but it cannot be passed off as this one.
+echo
+case $STATUS in
+  0) echo "ship-gate: PASS"
+     printf 'PASS %s\\n' "$(date -u +%FT%TZ)" > "$RECEIPT" ;;
+  1) echo "ship-gate: FAIL — deal with the findings above, then run this again."
+     echo "           To ship anyway: bash .claude/hooks/ship-gate.sh --force"
+     rm -f "$RECEIPT" ;;
+  2) echo "ship-gate: UNPROVEN — nothing is wrong, but nothing was proven either"
+     printf 'UNPROVEN %s\\n' "$(date -u +%FT%TZ)" > "$RECEIPT" ;;
+esac
+exit $STATUS
+`;
+
+// PreToolUse on Bash: refuses git commit/push without a ship-gate receipt.
+// Canonical source: scripts/ship-gate-hook.sh.
+const SHIP_GATE_HOOK_SCRIPT = `#!/usr/bin/env bash
+# ship-gate-hook.sh — PreToolUse on Bash. Refuses \`git commit\` and \`git push\`
+# unless ship-gate.sh has left a receipt for exactly these changes.
+#
+# A gate written as an instruction is a gate an agent can decide is not worth the
+# time — and then report a pass it never earned, which is the part you cannot see
+# from the outside. This removes the claim entirely: either the receipt exists for
+# this exact content, or git does not run.
+#
+# The receipt key covers everything about to ship, so it survives \`git commit\`
+# and still matches at push time, and it changes the moment any file is edited —
+# a fix has to be re-gated instead of riding on the previous verdict.
+
+INPUT=$(cat)
+
+CMD=$(printf '%s' "$INPUT" | grep -o '"command"[[:space:]]*:[[:space:]]*"[^"]*"' \\
+      | head -1 | sed 's/.*:[[:space:]]*"//; s/"$//')
+
+# Only the two commands that publish work. Everything else passes untouched.
+case "$CMD" in
+  *"git commit"*|*"git push"*) ;;
+  *) exit 0 ;;
+esac
+
+PROJECT_DIR="\${CLAUDE_PROJECT_DIR:-$PWD}"
+cd "$PROJECT_DIR" 2>/dev/null || exit 0
+
+GATE="$PROJECT_DIR/.claude/hooks/ship-gate.sh"
+[ -x "$GATE" ] || exit 0
+git rev-parse --git-dir >/dev/null 2>&1 || exit 0
+
+# Ask the gate for the key rather than recomputing it here. Two implementations
+# of the same rule drift, and the drift is silent.
+KEY=$(bash "$GATE" --key 2>/dev/null)
+[ -z "$KEY" ] && exit 0
+
+RECEIPT="/tmp/claude-shipgate-$KEY"
+if [ -f "$RECEIPT" ]; then
+  exit 0
+fi
+
+MSG="BLOCKED: no ship-gate receipt for these changes.
+
+The quality gate has not run against the code you are about to publish, or the
+code changed since it last did. Run it:
+
+  bash .claude/hooks/ship-gate.sh
+
+It checks file length and mutation-tests the changed lines, and writes a receipt
+this hook can see. Fix what it reports and run it again — a fix invalidates the
+previous receipt on purpose.
+
+Do NOT hand-roll a substitute check: only ship-gate.sh writes a receipt, so a
+weaker check you designed yourself cannot be passed off as this one.
+
+To publish without the gate, say so out loud and run:
+
+  bash .claude/hooks/ship-gate.sh --force"
+
 json_escape() {
   local s="$1"
   s="\${s//\\\\/\\\\\\\\}"
@@ -454,11 +776,7 @@ json_escape() {
   printf '"%s"' "$s"
 }
 
-printf '%s\\n' "red: the $FAILED gate failed" > "$WHY" 2>/dev/null
-if [ -n "\${GAUNTLET_DEBUG:-}" ]; then printf 'gauntlet: red: the %s gate failed\\n' "$FAILED" >&2; fi
-# A Stop hook's decision is "continue" / "stop" / "escalate" — "block" is not a
-# valid value and would be ignored, letting the turn end on a red gate.
-printf '{"decision":"continue","reason":%s}\\n' "$(json_escape "$MSG")"
+printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":%s}}\\n' "$(json_escape "$MSG")"
 exit 0
 `;
 
@@ -466,40 +784,33 @@ 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 LEGACY_EVAL_FILENAME = "skill-forced-eval-hook.sh";
 const LEGACY_AUDIT_RUNNER_FILENAME = "skill-audit-runner.sh";
 
-// Mirrors the detect() in scripts/gauntlet.sh. Kept in sync by hand: this one
-// only reports what the hook will find, it never decides anything.
+// Asks the installed hook what it would run, rather than reimplementing its
+// detection here. A second copy drifts: the JS one reported "no test runner"
+// for repos the shell script had already learned to handle.
 export async function detectStack(targetDir = process.cwd()) {
   const dir = resolve(targetDir);
-  const has = async (f) => {
-    try { await readFile(join(dir, f), "utf-8"); return true; } catch { return false; }
-  };
-  const read = async (f) => {
-    try { return await readFile(join(dir, f), "utf-8"); } catch { return ""; }
-  };
-
-  let test = null;
-  let typecheck = null;
-
-  const pkg = await read("package.json");
-  if (pkg) {
-    if (pkg.includes('"vitest"')) test = "vitest";
-    else if (pkg.includes('"jest"')) test = "jest";
-    // A delegating monorepo root has no runner as a direct dependency, but its
-    // own `test` script still runs the right thing.
-    else if (/"test"\s*:/.test(pkg)) test = "npm test";
-    if (/"typecheck"\s*:/.test(pkg)) typecheck = "npm run typecheck";
-    else if (await has("tsconfig.json")) typecheck = "tsc";
-  }
-  if (!test && (await has("pyproject.toml") || await has("pytest.ini") || await has("setup.cfg"))) {
-    test = "pytest";
-    if (await has("mypy.ini") || (await read("pyproject.toml")).includes("tool.mypy")) {
-      typecheck = "mypy";
-    }
-  }
-  return { test, typecheck };
+  const hook = join(dir, ".claude", "hooks", GAUNTLET_FILENAME);
+  return new Promise((done) => {
+    const child = spawn("bash", [hook], {
+      cwd: dir,
+      env: { ...process.env, CLAUDE_PROJECT_DIR: dir, GAUNTLET_DEBUG: "1", GAUNTLET_DRYRUN: "1" },
+    });
+    let err = "";
+    child.stderr.on("data", (c) => { err += c; });
+    child.on("error", () => done(null));
+    child.on("close", () => {
+      const line = err.split("\n").find((l) => l.startsWith("gauntlet: would run:"));
+      if (!line) return done(null);
+      const gates = line.slice("gauntlet: would run:".length).trim();
+      done(gates && !gates.startsWith("nothing") ? gates : null);
+    });
+    child.stdin.end('{"session_id":"install"}');
+  });
 }
 
 // Written only when detection finds nothing — otherwise the hook auto-detects and
@@ -525,6 +836,8 @@ export async function setupHook(targetDir = process.cwd()) {
   const autoMarkPath = join(hooksDir, AUTO_MARK_FILENAME);
   const applicationGatePath = join(hooksDir, APPLICATION_GATE_FILENAME);
   const gauntletPath = join(hooksDir, GAUNTLET_FILENAME);
+  const shipGatePath = join(hooksDir, SHIP_GATE_FILENAME);
+  const shipGateHookPath = join(hooksDir, SHIP_GATE_HOOK_FILENAME);
   const settingsPath = join(resolved, ".claude", "settings.json");
 
   await mkdir(hooksDir, { recursive: true });
@@ -536,6 +849,10 @@ export async function setupHook(targetDir = process.cwd()) {
   await chmod(applicationGatePath, 0o755);
   await writeFile(gauntletPath, GAUNTLET_SCRIPT, { mode: 0o755 });
   await chmod(gauntletPath, 0o755);
+  await writeFile(shipGatePath, SHIP_GATE_SCRIPT, { mode: 0o755 });
+  await chmod(shipGatePath, 0o755);
+  await writeFile(shipGateHookPath, SHIP_GATE_HOOK_SCRIPT, { mode: 0o755 });
+  await chmod(shipGateHookPath, 0o755);
 
   // Remove the legacy audit-runner hook file from prior installs (2.3.x).
   try {
@@ -596,6 +913,17 @@ export async function setupHook(targetDir = process.cwd()) {
   );
   if (!applicationAlreadyRegistered) settings.hooks.PreToolUse.push(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 }],
+  };
+  const shipGateRegistered = settings.hooks.PreToolUse.some((entry) =>
+    entry.hooks?.some((h) => h.command?.endsWith(SHIP_GATE_HOOK_FILENAME))
+  );
+  if (!shipGateRegistered) settings.hooks.PreToolUse.push(shipGateEntry);
+
   // Register PostToolUse auto-mark on Skill.
   const autoMarkCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${AUTO_MARK_FILENAME}`;
   const autoMarkEntry = {
@@ -631,5 +959,7 @@ export async function setupHook(targetDir = process.cwd()) {
   console.log(`  Hook installed: .claude/hooks/${AUTO_MARK_FILENAME}`);
   console.log(`  Hook installed: .claude/hooks/${APPLICATION_GATE_FILENAME}`);
   console.log(`  Hook installed: .claude/hooks/${GAUNTLET_FILENAME}`);
+  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`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spardutti/claude-skills",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "CLI to install Claude Code skills from the claude-skills collection",
   "type": "module",
   "bin": {