@spardutti/claude-skills 2.22.0 → 2.24.0

package/README.md

@@ -100,8 +100,8 @@ Portable slash commands installed to `.claude/commands/`. Some orchestrate paral
 
 | Command | What it does |
 |---------|--------------|
-| `/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` |
+| `/ship` | Unified delivery pipeline — commit → gate → 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. It runs before the **PR**, not before every commit: its scope is the whole branch, so gating each commit re-mutated every file the branch had ever touched. `--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: generates competing framings through blind subagents under forced constraints, stress-tests the winner with a blind critic, and refuses to converge until every open question is answered or deferred. 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 |
 | `/refactor` | Detect size / complexity / duplication / coupling issues via 4 parallel subagents, then refactor |

package/bin/cli.mjs

@@ -8,7 +8,13 @@ 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 } from "../lib/setup-hook.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";
@@ -173,6 +179,39 @@ async function main() {
       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);

package/lib/scaffold-stryker.mjs

@@ -14,20 +14,43 @@
 import { readFile, writeFile, access } from "node:fs/promises";
 import { join } from "node:path";
 
+// ignoreStatic is the whole reason a first run is survivable. A string in a
+// module-level array or object is a static mutant, evaluated once at file load,
+// and Stryker's docs say testing one "often requires running all tests". A table
+// of 11 headings and 16 term rows produced 57 survivors and a gate that timed
+// out past 600s; with this set the same gate ran in 1m33s and the survivors were
+// gone without a single test written for them. It requires perTest coverage
+// analysis, which is why the two belong together.
+//
+// A shipped attempt to solve this in the ignorer — skip string mutants inside a
+// module-level array or object literal — was exactly the definition of a static
+// mutant, so it did the same job worse. It is gone; this option replaces it.
 const CONFIG = {
   $schema: "./node_modules/@stryker-mutator/core/schema/stryker-schema.json",
   testRunner: "vitest",
   plugins: ["@stryker-mutator/vitest-runner", "./stryker-classname-ignorer.mjs"],
   ignorers: ["tailwind-classnames"],
   coverageAnalysis: "perTest",
+  ignoreStatic: true,
   tempDirName: ".stryker-tmp",
 };
 
+// Bumped whenever IGNORER changes. A project scaffolded before a rule existed
+// has no other way to learn about it, and the file is generated, not authored —
+// so a missing marker means overwrite, not keep.
+const IGNORER_VERSION = "v3";
+
 // .mjs, not .js: an app without "type": "module" in its package.json cannot
 // load ESM from a .js file, and the plugin is ESM.
-const IGNORER = `// Ignore by WHERE the mutant sits, not by what kind it is. Disabling the
+const IGNORER = `// Generated by @spardutti/claude-skills — ignorer ${IGNORER_VERSION}. Edits are
+// overwritten when the rules change.
+//
+// Ignore by WHERE the mutant sits, not by what kind it is. Disabling the
 // StringLiteral mutator globally would also stop mutating labels, keys and
 // separators — strings whose value is behaviour.
+//
+// Content in a module-level table is NOT handled here. Those are static mutants,
+// and \`ignoreStatic\` in stryker.config.json covers them for less.
 import { PluginKind, declareValuePlugin } from "@stryker-mutator/api/plugin";
 
 export const strykerPlugins = [
@@ -89,25 +112,55 @@ export async function scaffoldStryker(projectDir, rel) {
     }
     if (cfg === null) {
       unreadable.push(`${at}stryker.config.json`);
-    } else if ((cfg.ignorers ?? []).includes("tailwind-classnames")) {
-      kept.push(`${at}stryker.config.json`);
     } else {
-      cfg.plugins = [...new Set([...(cfg.plugins ?? []), "./stryker-classname-ignorer.mjs"])];
-      cfg.ignorers = [...new Set([...(cfg.ignorers ?? []), "tailwind-classnames"])];
-      await writeFile(configPath, JSON.stringify(cfg, null, 2) + "\n");
-      patched.push(`${at}stryker.config.json`);
+      const needsIgnorer = !(cfg.ignorers ?? []).includes("tailwind-classnames");
+
+      // ignoreStatic is only correct under perTest coverage analysis. Absent, we
+      // set both. Already perTest, we add the flag. Anything else was a
+      // deliberate choice and stays — silently switching it would change which
+      // mutants the project reports, which is not ours to decide.
+      const coverage = cfg.coverageAnalysis;
+      const canSetStatic = coverage === undefined || coverage === "perTest";
+      const needsStatic = cfg.ignoreStatic !== true && canSetStatic;
+
+      if (!needsIgnorer && !needsStatic) {
+        kept.push(`${at}stryker.config.json`);
+      } else {
+        if (needsIgnorer) {
+          cfg.plugins = [...new Set([...(cfg.plugins ?? []), "./stryker-classname-ignorer.mjs"])];
+          cfg.ignorers = [...new Set([...(cfg.ignorers ?? []), "tailwind-classnames"])];
+        }
+        if (needsStatic) {
+          cfg.coverageAnalysis = "perTest";
+          cfg.ignoreStatic = true;
+        }
+        await writeFile(configPath, JSON.stringify(cfg, null, 2) + "\n");
+        patched.push(`${at}stryker.config.json`);
+      }
     }
   } else {
     await writeFile(configPath, JSON.stringify(CONFIG, null, 2) + "\n");
     wrote.push(`${at}stryker.config.json`);
   }
 
+  // Testing the fresh install here would have missed the whole point: a project
+  // that already had the v1 ignorer would have kept it forever and never gained
+  // the data-table rule, which is the rule this release exists for.
   const ignorerPath = join(dir, "stryker-classname-ignorer.mjs");
-  if (await exists(ignorerPath)) {
+  let existingIgnorer = null;
+  try {
+    existingIgnorer = await readFile(ignorerPath, "utf-8");
+  } catch {
+    // not scaffolded yet
+  }
+  if (existingIgnorer === null) {
+    await writeFile(ignorerPath, IGNORER);
+    wrote.push(`${at}stryker-classname-ignorer.mjs`);
+  } else if (existingIgnorer.includes(`ignorer ${IGNORER_VERSION}`)) {
     kept.push(`${at}stryker-classname-ignorer.mjs`);
   } else {
     await writeFile(ignorerPath, IGNORER);
-    wrote.push(`${at}stryker-classname-ignorer.mjs`);
+    patched.push(`${at}stryker-classname-ignorer.mjs`);
   }
 
   // A crashed run leaves a full second copy of the project behind, so this one

package/lib/setup-hook.mjs

@@ -1,6 +1,7 @@
 import { mkdir, writeFile, readFile, chmod, unlink } from "node:fs/promises";
 import { join, resolve, dirname } from "node:path";
 import { spawn } from "node:child_process";
+import { homedir } from "node:os";
 
 // PreToolUse gate on Write|Edit|MultiEdit. Blocks the tool call unless
 // a per-session marker file exists at /tmp/claude-skill-gate-<SESSION_ID>.
@@ -52,6 +53,9 @@ if [ "$TOOL" != "Bash" ]; then
   # The structured tools name their target outright.
   TARGET=$(printf '%s' "$INPUT" | grep -o '"file_path":[[:space:]]*"[^"]*"' | head -1 | sed 's/.*:[[:space:]]*"//; s/"$//')
   case "$TARGET" in
+    # The settings file that configures the escape hatch cannot sit behind the
+    # gate, or a denied ack has no way to be un-denied.
+    */.claude/settings.json|*/.claude/settings.local.json) exit 0 ;;
     *.*) printf '%s' "$TARGET" | grep -qiE "\.($PROSE_EXT)$" && exit 0 ;;
   esac
 fi
@@ -61,6 +65,7 @@ if [ "$TOOL" = "Bash" ]; then
   # Never gate the command that clears the gate, or this deadlocks.
   case "$CMD" in
     *claude-skill-gate-*|*claude-skill-acked-*|*claude-skill-loaded-*) exit 0 ;;
+    *.claude/settings.json*|*.claude/settings.local.json*) exit 0 ;;
   esac
 
   # /dev/null redirects are not file writes; drop them before looking for one.
@@ -155,6 +160,9 @@ if [ "$TOOL" != "Bash" ]; then
   # The structured tools name their target outright.
   TARGET=$(printf '%s' "$INPUT" | grep -o '"file_path":[[:space:]]*"[^"]*"' | head -1 | sed 's/.*:[[:space:]]*"//; s/"$//')
   case "$TARGET" in
+    # The settings file that configures the escape hatch cannot sit behind the
+    # gate, or a denied ack has no way to be un-denied.
+    */.claude/settings.json|*/.claude/settings.local.json) exit 0 ;;
     *.*) printf '%s' "$TARGET" | grep -qiE "\.($PROSE_EXT)$" && exit 0 ;;
   esac
 fi
@@ -162,6 +170,7 @@ if [ "$TOOL" = "Bash" ]; then
   CMD=$(printf '%s' "$INPUT" | grep -o '"command":[[:space:]]*"[^"]*"' | head -1 | sed 's/.*:[[:space:]]*"//; s/"$//')
   case "$CMD" in
     *claude-skill-gate-*|*claude-skill-acked-*|*claude-skill-loaded-*) exit 0 ;;
+    *.claude/settings.json*|*.claude/settings.local.json*) exit 0 ;;
   esac
 
   # A command that names a prose file and no code file is writing prose.
@@ -235,15 +244,20 @@ Before this Write/Edit, you must:
 One ack per skill per session. After acking, retry the Write/Edit.
 
 If that Bash call is denied by the auto mode classifier, STOP. Do not ask your
-user to run it for you, and do not look for another route to create the files.
-Both are what the classifier is there to stop, and asking a human to run a
-command you were just denied makes them the tool that performs it. Report this
-to them instead and let them decide:
+user to run it for you, do not look for another route to create the files, and
+do not try to add the allow rule yourself — an agent editing permission settings
+is denied by the same classifier, so that attempt fails too and costs a round
+trip that ends in the same place. All three are what the classifier is there to
+stop, and asking a human to run a command you were just denied makes them the
+tool that performs it. Report this to them instead and let them decide:
 
   Auto mode's built-in Auto-Mode Bypass rule counts a hook's ack file as working
   around the permission system. It is a soft rule, so an allow entry clears it.
-  It has to go in ~/.claude/settings.json — the classifier does not read a
-  project's .claude/settings.json — or in /permissions, Auto mode tab. Keep the
+  The user has to add it — you cannot. The shortest route is for them to re-run
+  npx @spardutti/claude-skills and accept the auto mode prompt, which writes it.
+  Otherwise /permissions, Auto mode tab. Editing the file by hand works too, and
+  it has to be ~/.claude/settings.json — the classifier does not read a
+  project's .claude/settings.json. Keep the
   \\\$defaults line or every built-in allow rule is discarded:
 
   \\"autoMode\\": { \\"allow\\": [ \\"\\\$defaults\\",
@@ -649,6 +663,13 @@ GAUNTLET_MUTATE=""
 GAUNTLET_SOURCE_EXT="ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|c|h|cpp|hpp|cs|swift|gd"
 GAUNTLET_IGNORE_EXT="md|mdx|txt|rst|adoc|json|ya?ml|toml|lock|cfg|ini|env|csv|tsv|sql|html|css|scss|svg|png|jpg|jpeg|gif|webp|ico|pdf|woff2?|ttf|otf|mp3|mp4|wav|zip|gz|tres|tscn|import|godot"
 GAUNTLET_IGNORE_FILES="*.gen.ts *.gen.tsx *.generated.* */migrations/*.py */alembic/versions/*.py */components/ui/*.tsx */*.config.*"
+# Length-checked and skill-audited like everything else, but not mutated.
+# Mutation pays on logic and burns time on presentation: a component's mutants
+# are class names, copy and JSX shape, none of which is behaviour, and one
+# session spent an evening killing them. Logic that lives inside a component is
+# logic that wants extracting — which the 200-line rule already pushes toward.
+# Override in .claude/gauntlet.conf to mutate components too.
+GAUNTLET_NO_MUTATE='\\.(tsx|jsx)$'
 [ -n "\${HOME:-}" ] && [ -f "$HOME/.claude/gauntlet.conf" ] && . "$HOME/.claude/gauntlet.conf"
 [ -f ".claude/gauntlet.conf" ] && . ".claude/gauntlet.conf"
 
@@ -811,7 +832,7 @@ 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")
+          done <<< "$FILES" | grep -vE "$GAUNTLET_NO_MUTATE" || true)
   [ -z "$OWNED" ] && continue
 
   # ONE comma-joined --mutate value, never a flag per range. Stryker's CLI
@@ -1035,7 +1056,7 @@ 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\`
+# ship-gate-hook.sh — PreToolUse on Bash. Refuses the commands that publish work
 # 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
@@ -1046,21 +1067,38 @@ const SHIP_GATE_HOOK_SCRIPT = `#!/usr/bin/env bash
 # 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.
+#
+# It gated \`git commit\` and \`git push\` until 2.23.0, and that was the wrong
+# moment. The gate's scope is merge-base..HEAD — the whole branch, because the
+# whole branch is what a PR ships — so a branch touching 46 files re-mutated all
+# 46 on every commit. Fifteen minutes, twenty times, for one branch. Neither a
+# commit nor a push to a feature branch publishes anything, so neither is gated
+# now: the cost is paid once, at the point work actually ships.
 
 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.
+PROJECT_DIR="\${CLAUDE_PROJECT_DIR:-$PWD}"
+cd "$PROJECT_DIR" 2>/dev/null || exit 0
+
+# Opening or merging a PR publishes. So does pushing while standing on a
+# protected branch — that is a direct ship with no PR in front of it. The branch
+# is read from git rather than parsed out of the command, because \`git push\` with
+# no arguments names no branch at all.
 case "$CMD" in
-  *"git commit"*|*"git push"*) ;;
+  *"gh pr create"*|*"gh pr merge"*) ;;
+  *"git push"*)
+    BRANCH=$(git branch --show-current 2>/dev/null)
+    case "$BRANCH" in
+      main|master|develop|development|dev) ;;
+      *) exit 0 ;;
+    esac
+    ;;
   *) 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
@@ -1414,3 +1452,81 @@ export async function setupHook(targetDir = process.cwd()) {
   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/package.json

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