@spardutti/claude-skills 2.20.2 → 2.23.0

package/README.md

@@ -88,6 +88,8 @@ 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 |
+| `git-merge-conflicts` | Resolve a merge/rebase conflict by intent, not by side — `zdiff3` to see the merge base, the inverted meaning of `ours`/`theirs` during a rebase, the semantic and tree conflicts git never marks, lockfiles and migrations you regenerate instead of merging |
+| `research` | Open the source, don't recall it — route to the tool that owns the answer, primary sources only, pin the version you're actually on, run the validator instead of guessing, and mark every claim VERIFIED / INFERRED / UNVERIFIED |
 | `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; 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 |
@@ -98,14 +100,15 @@ 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 |
 | `/deep-review` | Multi-agent deep code review — 5 parallel subagents catch guard bypasses, lost async state, wrong-table queries, dead references, protocol violations |
 | `/test-review` | Write-then-verify test review — scopes to the diff, runs red-green + mutation gates, then an isolated read-only subagent proves each test would catch a regression instead of rubber-stamping it |
 | `/lockdown` | Per-repo supply-chain hardening — detects the package managers, Dockerfiles, and CI in use, then guides you through and applies install-time, deploy, and pipeline hardening for npm/pnpm, pip/uv, Docker, and GitHub Actions |
+| `/handoff` | Write a handoff doc so a fresh session picks the work up — captures what auto-compaction loses: decisions made and rejected, dead ends already ruled out, why the tree is dirty, and the one next step. Links to specs, commits, and PRs instead of restating them |
 
 ## How It Works
 

package/bin/cli.mjs

@@ -8,8 +8,15 @@ 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";
 import {
   readManifest, writeManifest, computeOrphans, computeRemovals, scanInstalled, removeArtifacts,
@@ -172,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);
@@ -209,12 +249,63 @@ async function main() {
       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) {
+      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 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) {
+              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 (stryker.some((n) => n.ignorerOnly)) {
+            console.log(`\n  ${chalk.yellow("!")} ${chalk.bold("The ignorer needs its own dependency:")}`);
+            console.log(`      ${chalk.cyan("add @stryker-mutator/api as a dev dependency")} ${chalk.dim("— pnpm does not hoist it, and without it the ignorer silently does not load")}`);
+          }
+        }
+      }
     }
   }
 

package/lib/local.mjs

@@ -161,6 +161,7 @@ export async function reportToolNeeds(projectDir) {
         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"}`,
@@ -173,6 +174,20 @@ export async function reportToolNeeds(projectDir) {
             `${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")) {

package/lib/scaffold-stryker.mjs

@@ -0,0 +1,193 @@
+// Stryker setup, written rather than printed.
+//
+// The CLI used to print five steps and leave them to the reader. Every project
+// then started with the same 40% of a first React run being class-name noise —
+// mutants on `className` strings and `cn()` ternaries that cannot be killed
+// without asserting on the stylesheet. Un-closeable findings are what teach
+// people to --force, so the ignorer is not an optional extra; it is the
+// difference between a gate that gets used and one that gets bypassed.
+//
+// Two things stay printed, deliberately. Installing the packages touches the
+// lockfile and the network. Editing an existing vitest config means parsing
+// someone's plugins, aliases and projects array, and getting it wrong breaks
+// their test run rather than ours.
+import { readFile, writeFile, access } from "node:fs/promises";
+import { join } from "node:path";
+
+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",
+  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 = "v2";
+
+// Exported and then serialised into the generated ignorer below, rather than
+// written twice. A copy in the template and a copy under test would agree with
+// each other and disagree with the shipped file.
+export function inDataTable(path) {
+  let found = false;
+  for (let p = path; p; p = p.parentPath) {
+    if (p.isFunction()) return false;
+    if (!found && p.isVariableDeclarator()) {
+      const init = p.node.init;
+      if (!init) return false;
+      if (init.type !== "ArrayExpression" && init.type !== "ObjectExpression") return false;
+      found = true;
+    }
+  }
+  return found;
+}
+
+// .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 = `// 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.
+import { PluginKind, declareValuePlugin } from "@stryker-mutator/api/plugin";
+
+// A string in a module-level array or object literal is copy: a heading, a
+// label, a term row. Mutating it produces 'Pizzas' -> 'Stryker was here!',
+// which can only be killed by asserting the table against a copy of itself —
+// the tautology the testing skill exists to stop. One table of 11 headings and
+// 16 rows produced 57 such survivors and a fifteen-minute gate.
+//
+// Any function between the string and the top disqualifies it: that is code
+// building a value, not a table of content. A non-string mutant in the same
+// table is left alone, because a number or a flag in a config object is
+// behaviour even when it sits in data.
+${inDataTable.toString()}
+
+export const strykerPlugins = [
+  declareValuePlugin(PluginKind.Ignore, "tailwind-classnames", {
+    shouldIgnore(path) {
+      if (path.find((p) => p.isJSXAttribute() && p.node.name.name === "className"))
+        return "styling, not behaviour";
+      if (path.find((p) => p.isCallExpression() && p.node.callee.name === "cn"))
+        return "styling, not behaviour";
+      if (path.isStringLiteral() && inDataTable(path))
+        return "copy in a data table, not behaviour";
+    },
+  }),
+];
+`;
+
+async function exists(p) {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// The ignorer imports @stryker-mutator/api, but nothing depends on it directly:
+// npm's flat node_modules hoists it so the import resolves by accident, and
+// pnpm's isolated store does not. The failure is one WARN PluginLoader line and
+// an ignorer that never loads, so every class-name mutant comes back survived.
+async function installCommand(dir, rel) {
+  const pnpm = await exists(join(dir, "pnpm-lock.yaml"));
+  const pkgs = "@stryker-mutator/core @stryker-mutator/vitest-runner @stryker-mutator/api";
+  return pnpm
+    ? `pnpm --dir ${rel || "."} add -D ${pkgs}`
+    : `npm --prefix ${rel || "."} i -D ${pkgs}`;
+}
+
+// Writes only what is absent. A project that already configured Stryker its own
+// way keeps it — reporting the skip is the point, so nobody thinks a file they
+// are looking at came from here.
+export async function scaffoldStryker(projectDir, rel) {
+  const dir = rel ? join(projectDir, rel) : projectDir;
+  const at = rel ? `${rel}/` : "";
+  const wrote = [];
+  const kept = [];
+  const patched = [];
+  const unreadable = [];
+
+  // A project that already runs Stryker keeps every setting it chose. The two
+  // entries that wire the ignorer in are added, because a config written before
+  // the ignorer existed has no other way to learn about it — and that project is
+  // the one grinding through className mutants. A config this cannot parse is
+  // reported and left alone rather than rewritten from a guess.
+  const configPath = join(dir, "stryker.config.json");
+  if (await exists(configPath)) {
+    let cfg = null;
+    try {
+      cfg = JSON.parse(await readFile(configPath, "utf-8"));
+    } catch {
+      cfg = null;
+    }
+    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`);
+    }
+  } 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");
+  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);
+    patched.push(`${at}stryker-classname-ignorer.mjs`);
+  }
+
+  // A crashed run leaves a full second copy of the project behind, so this one
+  // matters even though it is one line.
+  const gitignorePath = join(dir, ".gitignore");
+  let gitignore = "";
+  try {
+    gitignore = await readFile(gitignorePath, "utf-8");
+  } catch {
+    // no .gitignore yet — one gets written below
+  }
+  if (/^\.stryker-tmp\/?$/m.test(gitignore)) {
+    kept.push(`${at}.gitignore`);
+  } else {
+    const sep = gitignore === "" || gitignore.endsWith("\n") ? "" : "\n";
+    await writeFile(gitignorePath, `${gitignore}${sep}.stryker-tmp/\n`);
+    wrote.push(`${at}.gitignore`);
+  }
+
+  return {
+    wrote,
+    kept,
+    patched,
+    unreadable,
+    install: await installCommand(dir, rel),
+    // Stryker copies the whole project into .stryker-tmp/sandbox-*/, so every
+    // test file briefly exists twice and the runner collects both. They pass,
+    // so a doubled test count is the only symptom. Spread configDefaults.exclude
+    // rather than assigning it, or node_modules stops being excluded.
+    vitest: `${at}vitest.config.ts  exclude: [...configDefaults.exclude, "**/.stryker-tmp/**"]`,
+  };
+}

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\\",
@@ -1035,7 +1049,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 +1060,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 +1445,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.20.2",
+  "version": "2.23.0",
   "description": "CLI to install Claude Code skills from the claude-skills collection",
   "type": "module",
   "repository": {