ronce-racine 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -7,6 +7,56 @@ Hooks are authored in TypeScript but SHIP BUILT: the installer copies `.mjs` fil
7
7
  > **Note** - the `install.ts` installer copies the selected hooks and automatically composes the merged `settings.json` snippet - the manual wiring below is only useful for a hand install.
8
8
 
9
9
 
10
+ ## Wiring rule: exec form, always
11
+
12
+ Every snippet below uses the **exec form** - `"command"` holds the executable,
13
+ `"args"` holds the arguments:
14
+
15
+ ```json
16
+ { "type": "command", "command": "node", "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/skill-reminder.mjs"] }
17
+ ```
18
+
19
+ Not the shell form (`"command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/x.mjs"`),
20
+ which shipped until 0.7.0 and broke for every adopter whose project path
21
+ contained a space - the shell split the expanded path at the space, and on a
22
+ Windows box without Git Bash the unbraced `$CLAUDE_PROJECT_DIR` was never
23
+ expanded at all. Exec form spawns with no shell: each argument is passed exactly
24
+ as written, and `${CLAUDE_PROJECT_DIR}` braced is substituted by Claude Code
25
+ itself rather than by whichever shell happens to be there.
26
+
27
+ Two constraints worth knowing:
28
+
29
+ - **`node` plus a script path, never the script as the executable.** On Windows
30
+ exec form needs `command` to resolve to a real binary; `node.exe` is one
31
+ everywhere. The `.cmd` shims in `node_modules/.bin` are not.
32
+ - **A hook needing shell syntax stays in shell form** - a pipe, `&&`, `|| true`.
33
+ Then every placeholder must be wrapped in double quotes (see the
34
+ `precommit-scan` snippet below), because the shell does the tokenizing.
35
+
36
+ `ronce-racine install` writes the exec form and repairs a pre-0.8 shell-form
37
+ wiring in place, so re-running the installer is enough to pick this up.
38
+
39
+ ---
40
+
41
+ ## Permission gate: the rewriting hooks answer `allow`
42
+
43
+ `bash-npm-silent` and `truncate-output` change the command that runs. Claude Code
44
+ only applies an `updatedInput` when the hook answers
45
+ `permissionDecision: "allow"`, so **every command these two rewrite is
46
+ auto-approved and skips the permission prompt you would otherwise see.**
47
+
48
+ Concretely, with both installed, these no longer prompt: `npm install`, `npm ci`
49
+ (which run `postinstall` scripts), `cargo build/test/clippy`, `curl …`,
50
+ `docker build/logs`, `rustup …`, and unbounded `git log`/`git diff`. Commands
51
+ they do not match are unaffected.
52
+
53
+ This is a real widening of what runs without asking. If that trade is not one you
54
+ want, do not install these two hooks - or wire them under an `if` rule narrowing
55
+ them to the command classes you accept. The other hooks in this directory observe
56
+ without rewriting and do not answer `allow`.
57
+
58
+ ---
59
+
10
60
  ## Composition rule: a hook is never alone on its event
11
61
 
12
62
  Several plugins can observe the same Claude Code event, and `PreToolUse`
@@ -40,7 +90,7 @@ Locates skills in this order: `$CLAUDE_PROJECT_DIR/.claude/skills`, `./.claude/s
40
90
  {
41
91
  "hooks": {
42
92
  "UserPromptSubmit": [
43
- { "hooks": [{ "type": "command", "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/skill-reminder.mjs" }] }
93
+ { "hooks": [{ "type": "command", "command": "node", "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/skill-reminder.mjs"] }] }
44
94
  ]
45
95
  }
46
96
  }
@@ -64,7 +114,7 @@ Leaves interactive `npm install <pkg>` calls (adding a dependency) untouched.
64
114
  "PreToolUse": [
65
115
  { "matcher": "Bash",
66
116
  "hooks": [{ "type": "command",
67
- "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/bash-npm-silent.mjs" }] }
117
+ "command": "node", "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/bash-npm-silent.mjs"] }] }
68
118
  ]
69
119
  }
70
120
  }
@@ -88,7 +138,7 @@ Leaves interactive `npm install <pkg>` calls (adding a dependency) untouched.
88
138
  "PreToolUse": [
89
139
  { "matcher": "Bash",
90
140
  "hooks": [{ "type": "command",
91
- "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/truncate-output.mjs" }] }
141
+ "command": "node", "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/truncate-output.mjs"] }] }
92
142
  ]
93
143
  }
94
144
  }
@@ -111,7 +161,7 @@ Writes a session memo to `~/.claude/projects/<repo-slug>/sessions/<branch>.md` (
111
161
  "hooks": {
112
162
  "Stop": [
113
163
  { "hooks": [{ "type": "command",
114
- "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/session-writer.mjs" }] }
164
+ "command": "node", "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/session-writer.mjs"] }] }
115
165
  ]
116
166
  }
117
167
  }
@@ -129,7 +179,7 @@ Re-reads the memo (written by `session-writer`) and injects it as `additionalCon
129
179
  "SessionStart": [
130
180
  { "matcher": "compact",
131
181
  "hooks": [{ "type": "command",
132
- "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/session-inject.mjs" }] }
182
+ "command": "node", "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/session-inject.mjs"] }] }
133
183
  ]
134
184
  }
135
185
  }
@@ -146,7 +196,7 @@ Injects the memo as `systemMessage` into the compaction prompt, so the generated
146
196
  "hooks": {
147
197
  "PreCompact": [
148
198
  { "hooks": [{ "type": "command",
149
- "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/session-precompact.mjs" }] }
199
+ "command": "node", "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/session-precompact.mjs"] }] }
150
200
  ]
151
201
  }
152
202
  }
@@ -165,7 +215,7 @@ If the session starts in a linked git worktree (not the main worktree) and the m
165
215
  "hooks": {
166
216
  "SessionStart": [
167
217
  { "hooks": [{ "type": "command",
168
- "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/worktree-env-setup.mjs" }] }
218
+ "command": "node", "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/worktree-env-setup.mjs"] }] }
169
219
  ]
170
220
  }
171
221
  }
@@ -205,7 +255,7 @@ terminal does not go through it - keep a CI job for that guarantee.
205
255
  "hooks": {
206
256
  "PreToolUse": [
207
257
  { "matcher": "Bash", "hooks": [{ "type": "command",
208
- "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/readme-freshness.mjs" }] }
258
+ "command": "node", "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/readme-freshness.mjs"] }] }
209
259
  ]
210
260
  }
211
261
  }
@@ -229,7 +279,7 @@ exec npx tsx "$CLAUDE_PROJECT_DIR/.claude/skills/commit-readiness-review/scripts
229
279
  "PreToolUse": [
230
280
  { "matcher": "Bash",
231
281
  "hooks": [{ "type": "command",
232
- "command": "npx tsx $CLAUDE_PROJECT_DIR/.claude/skills/commit-readiness-review/scripts/precommit-scan.ts || true" }] }
282
+ "command": "npx tsx \"${CLAUDE_PROJECT_DIR}/.claude/skills/commit-readiness-review/scripts/precommit-scan.ts\" || true" }] }
233
283
  ]
234
284
  }
235
285
  }
@@ -241,4 +291,4 @@ exec npx tsx "$CLAUDE_PROJECT_DIR/.claude/skills/commit-readiness-review/scripts
241
291
 
242
292
  The `install.ts` installer copies the selected hooks and automatically composes the merged `settings.json` snippet - this is the recommended method.
243
293
 
244
- For a manual install: copy the desired `.ts` files into `<repo>/.claude/hooks/`, then add the corresponding wiring to `<repo>/.claude/settings.json`. Paths use `$CLAUDE_PROJECT_DIR` (resolved by Claude Code) - no hardcoded absolute path.
294
+ For a manual install: copy the desired `.mjs` files into `<repo>/.claude/hooks/`, then add the corresponding wiring to `<repo>/.claude/settings.json`. Paths use `${CLAUDE_PROJECT_DIR}` (substituted by Claude Code itself) - no hardcoded absolute path, and no reliance on a shell to expand it.
@@ -21,12 +21,13 @@
21
21
  * `git push` in their own terminal does not go through it - use the CI job for
22
22
  * that guarantee.
23
23
  *
24
- * @version 1.0.0
25
- * @last-reviewed 2026-08-08
24
+ * @version 1.1.0
25
+ * @last-reviewed 2026-08-24
26
26
  */
27
27
  import { readFileSync, existsSync } from 'node:fs';
28
28
  import { spawnSync } from 'node:child_process';
29
29
  import { join } from 'node:path';
30
+ import { pathToFileURL } from 'node:url';
30
31
  /** Paths whose change can invalidate a README claim. Docs alone cannot. */
31
32
  const STRUCTURAL = /^(install\.ts|package\.json|skills\/|rules\/|hooks\/|agents\/|scripts\/|templates\/|\.claude-plugin\/)/;
32
33
  const VERDICT_OK = 'README_OK';
@@ -151,9 +152,10 @@ function main() {
151
152
  else
152
153
  emit('allow', message);
153
154
  }
154
- // Entry guard by BASENAME, never by extension: this file is authored as .ts and
155
- // ships as .mjs, and an extension-bound guard silently disables main() in the
156
- // built copy - the hook then exits 0 doing nothing, with no signal at all.
157
- const invoked = (process.argv[1] ?? '').split('/').pop()?.replace(/\.(ts|mjs|js)$/, '');
158
- if (invoked === 'readme-freshness')
155
+ // Compare URLs, never parse the path: pathToFileURL normalizes the separator,
156
+ // so this holds on win32 where a basename split on "/" never matches, and it is
157
+ // blind to the .ts -> .mjs rename the build performs. Both traps cost us a
158
+ // silently dead hook once each (see docs/postmortems/2026-08-24-hook-portability.md).
159
+ const isMain = import.meta.url === pathToFileURL(process.argv[1] ?? '').href;
160
+ if (isMain)
159
161
  main();
@@ -6,12 +6,12 @@
6
6
  * quoted triggers + the words of the name against the prompt.
7
7
  * NEVER blocks (exit 0 no matter what); emits nothing if there is no match.
8
8
  *
9
- * settings.json wiring (see hooks/README.md):
10
- * "UserPromptSubmit": [{ "hooks": [{ "type": "command",
11
- * "command": "npx tsx $CLAUDE_PROJECT_DIR/.claude/hooks/skill-reminder.ts" }] }]
9
+ * settings.json wiring (see hooks/README.md) - exec form, no shell involved:
10
+ * "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "node",
11
+ * "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/skill-reminder.mjs"] }] }]
12
12
  *
13
- * @version 1.0.0
14
- * @last-reviewed 2026-06-25
13
+ * @version 1.1.0
14
+ * @last-reviewed 2026-08-24
15
15
  */
16
16
  import { readFileSync, readdirSync, existsSync } from "node:fs";
17
17
  import { join, dirname } from "node:path";
@@ -50,8 +50,13 @@ function loadSkills(dir) {
50
50
  if (!existsSync(p))
51
51
  continue;
52
52
  const raw = readFileSync(p, "utf8");
53
- const fm = /^---\n([\s\S]*?)\n---/.exec(raw);
54
- const desc = fm && /description:\s*(.*)/.exec(fm[1]);
53
+ // \r?\n, not \n: with core.autocrlf=true (the Git default on Windows) a
54
+ // checkout materializes SKILL.md as CRLF, and an LF-only delimiter matched
55
+ // none of them - the hook then suggested only the skills that happened to
56
+ // stay LF. Same reason the capture is bounded to the line rather than `.*`,
57
+ // which would keep a trailing \r.
58
+ const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(raw);
59
+ const desc = fm && /description:\s*([^\r\n]*)/.exec(fm[1]);
55
60
  if (desc)
56
61
  out.push({ name, triggers: triggers(name, desc[1]) });
57
62
  }
@@ -6,10 +6,11 @@
6
6
  * exceeds the character threshold.
7
7
  * On error (exit ≠ 0), the full output is preserved for debugging.
8
8
  *
9
- * @version 1.0.0
10
- * @last-reviewed 2026-06-25
9
+ * @version 1.1.0
10
+ * @last-reviewed 2026-08-24
11
11
  */
12
12
  import { spawnSync } from 'node:child_process';
13
+ import { pathToFileURL } from 'node:url';
13
14
  export const THRESHOLD = 4000;
14
15
  export const HEAD_LINES = 20;
15
16
  export const TAIL_LINES = 20;
@@ -34,6 +35,14 @@ function main() {
34
35
  maxBuffer: 50 * 1024 * 1024,
35
36
  stdio: ['inherit', 'pipe', 'inherit'],
36
37
  });
38
+ // A wrapper that cannot spawn must SAY so. Returning stdout ?? '' with exit 0
39
+ // reported the user's command as a silent success and swallowed its output
40
+ // whole - the worst outcome available, and the one a missing `bash` produces
41
+ // (Git for Windows is optional; Claude Code then falls back to PowerShell).
42
+ if (result.error) {
43
+ process.stderr.write(`truncate-bash-output: cannot run the wrapped command (${result.error.message})\n`);
44
+ process.exit(1);
45
+ }
37
46
  const output = result.stdout ?? '';
38
47
  const exitCode = result.status ?? 1;
39
48
  if (exitCode !== 0) {
@@ -42,9 +51,10 @@ function main() {
42
51
  }
43
52
  process.stdout.write(truncateOutput(output));
44
53
  }
45
- // Entry guard by BASENAME, never by extension: this file is authored as .ts and
46
- // ships as .mjs, and an extension-bound guard silently disables main() in the
47
- // built copy - the hook then exits 0 doing nothing, with no signal at all.
48
- const invoked = (process.argv[1] ?? "").split("/").pop()?.replace(/\.(ts|mjs|js)$/, "");
49
- if (invoked === 'truncate-bash-output')
54
+ // Compare URLs, never parse the path: pathToFileURL normalizes the separator,
55
+ // so this holds on win32 where a basename split on "/" never matches, and it is
56
+ // blind to the .ts -> .mjs rename the build performs. Both traps cost us a
57
+ // silently dead hook once each (see docs/postmortems/2026-08-24-hook-portability.md).
58
+ const isMain = import.meta.url === pathToFileURL(process.argv[1] ?? '').href;
59
+ if (isMain)
50
60
  main();
@@ -10,10 +10,12 @@
10
10
  *
11
11
  * Bypass strategy: if the command contains `# no-truncate`, we leave it untouched.
12
12
  *
13
- * @version 2.0.0
14
- * @last-reviewed 2026-07-10
13
+ * @version 2.1.0
14
+ * @last-reviewed 2026-08-24
15
15
  */
16
16
  import { readFileSync } from 'node:fs';
17
+ import { join } from 'node:path';
18
+ import { fileURLToPath, pathToFileURL } from 'node:url';
17
19
  const VERBOSE_PATTERNS = [
18
20
  /^\s*cargo\s+(build|test|clippy|check|fmt|doc|run)/,
19
21
  // `npm install`/`npm ci` are handled by the bash-npm-silent hook (avoid a
@@ -49,7 +51,16 @@ export function wrapCommand(cmd, hookDir) {
49
51
  // `: 'cmd';` prefix does not (it breaks on `echo it's fine`).
50
52
  // Newlines are flattened, otherwise the comment would swallow the next line.
51
53
  const readable = cmd.replace(/\s*\n\s*/g, ' ').trim();
52
- return `TRUNCATE_CMD_B64=${encoded} node '${hookDir}/truncate-bash-output.mjs' # ${readable}`;
54
+ // Single quotes keep spaces and backslashes literal (a Windows hookDir is full
55
+ // of both), but they do not survive an apostrophe in the path: `'` has to be
56
+ // closed, escaped and reopened. `/home/o'brien/...` is rarer than a space, not
57
+ // rarer than never.
58
+ const helper = quoteForShell(join(hookDir, 'truncate-bash-output.mjs'));
59
+ return `TRUNCATE_CMD_B64=${encoded} node ${helper} # ${readable}`;
60
+ }
61
+ /** POSIX single-quoting: the only form that is literal for every other character. */
62
+ export function quoteForShell(value) {
63
+ return `'${value.replace(/'/g, `'\\''`)}'`;
53
64
  }
54
65
  function readStdin() {
55
66
  try {
@@ -76,10 +87,12 @@ function main() {
76
87
  if (!cmd || !isVerboseCommand(cmd))
77
88
  return;
78
89
  // Resolving the hooks directory: the CLAUDE_PROJECT_DIR variable takes priority,
79
- // otherwise a path relative to this file (for local execution / tests)
90
+ // otherwise a path relative to this file (for local execution / tests).
91
+ // fileURLToPath, never URL.pathname: on win32 the latter yields a percent-encoded
92
+ // "/C:/Users/First%20LAST/..." that no shell and no runtime can resolve.
80
93
  const hookDir = process.env.CLAUDE_PROJECT_DIR
81
- ? `${process.env.CLAUDE_PROJECT_DIR}/.claude/hooks`
82
- : new URL('.', import.meta.url).pathname.replace(/\/$/, '');
94
+ ? join(process.env.CLAUDE_PROJECT_DIR, '.claude', 'hooks')
95
+ : fileURLToPath(new URL('.', import.meta.url)).replace(/[\\/]$/, '');
83
96
  const output = {
84
97
  hookSpecificOutput: {
85
98
  hookEventName: 'PreToolUse',
@@ -92,9 +105,10 @@ function main() {
92
105
  };
93
106
  process.stdout.write(JSON.stringify(output));
94
107
  }
95
- // Entry guard by BASENAME, never by extension: this file is authored as .ts and
96
- // ships as .mjs, and an extension-bound guard silently disables main() in the
97
- // built copy - the hook then exits 0 doing nothing, with no signal at all.
98
- const invoked = (process.argv[1] ?? "").split("/").pop()?.replace(/\.(ts|mjs|js)$/, "");
99
- if (invoked === 'truncate-output')
108
+ // Compare URLs, never parse the path: pathToFileURL normalizes the separator,
109
+ // so this holds on win32 where a basename split on "/" never matches, and it is
110
+ // blind to the .ts -> .mjs rename the build performs. Both traps cost us a
111
+ // silently dead hook once each (see docs/postmortems/2026-08-24-hook-portability.md).
112
+ const isMain = import.meta.url === pathToFileURL(process.argv[1] ?? '').href;
113
+ if (isMain)
100
114
  main();
package/dist/install.js CHANGED
@@ -30,6 +30,7 @@ import { interactiveSelect } from "./src/selector.js";
30
30
  // Re-exported so importers (and the test suite) keep a single entry point.
31
31
  export { canonicalHash, copyPath, describeSource, isStale } from "./src/lock.js";
32
32
  export { CATALOG } from "./src/catalog.js";
33
+ export { hookCommand, wiredHookName } from "./src/settings.js";
33
34
  export { applySelectorKey } from "./src/selector.js";
34
35
  /**
35
36
  * Reads the lockfile, or exits 2 saying why.
@@ -209,12 +210,23 @@ async function doInstall(repo, opts) {
209
210
  // announces itself as healthy, and stays that way (issue #1).
210
211
  if (collectedWirings.length > 0) {
211
212
  const settingsPath = join(dotclaude, "settings.json");
212
- const { added, backedUp, malformed } = mergeHookSettings(dotclaude, collectedWirings);
213
+ // The lockfile's hooks, so a legacy wiring is repaired even when this run's
214
+ // detection no longer selects that hook (installed once with --all, signal
215
+ // since gone). Without it, "re-run the installer" only fixes what is picked.
216
+ const installedHookFiles = (prevLock?.installed ?? [])
217
+ .filter((t) => t.startsWith("hook:"))
218
+ .map((t) => t.slice("hook:".length));
219
+ const { added, rewired, backedUp, malformed } = mergeHookSettings(dotclaude, collectedWirings, installedHookFiles);
220
+ const backupNote = backedUp && !malformed ? " (backup: settings.json.bak)" : "";
213
221
  if (malformed)
214
222
  console.log(`\n⚠ ${settingsPath} was not valid JSON (or its hooks section had an unexpected shape) - backed up to settings.json.bak and rewritten.`);
215
223
  if (added > 0)
216
- console.log(`${malformed ? "" : "\n"}Wired ${added} hook(s) into ${settingsPath}${backedUp && !malformed ? " (backup: settings.json.bak)" : ""}.`);
217
- else if (!malformed)
224
+ console.log(`${malformed ? "" : "\n"}Wired ${added} hook(s) into ${settingsPath}${backupNote}.`);
225
+ // Worth its own line: it means the wirings that were there did not work, or
226
+ // were duplicated. Folding it into "no change" would hide a repair.
227
+ if (rewired > 0)
228
+ console.log(`${added > 0 || malformed ? "" : "\n"}Repaired ${rewired} pre-existing wiring(s) to the exec form${added > 0 ? "" : backupNote}.`);
229
+ if (added === 0 && rewired === 0 && !malformed)
218
230
  console.log(`\nHooks already wired in ${settingsPath} - no change.`);
219
231
  console.log(`(details: .claude/hooks/README.md)`);
220
232
  }
@@ -5,7 +5,113 @@ import { readFileSync, existsSync, writeFileSync } from "node:fs";
5
5
  import { join } from "node:path";
6
6
  import { shippedHookName } from "./paths.js";
7
7
  import { copyPath } from "./lock.js";
8
- export function mergeHookSettings(dotclaude, wirings) {
8
+ /**
9
+ * The wiring the installer writes: EXEC FORM, spawned with no shell at all.
10
+ *
11
+ * The shell form (`node $CLAUDE_PROJECT_DIR/.claude/hooks/x.mjs`) shipped until
12
+ * 0.7.0 and broke on any project path containing a space - the shell split the
13
+ * expanded path, and on a Windows box without Git Bash the unbraced variable was
14
+ * never expanded to begin with. Exec form passes each argument verbatim, and
15
+ * `${CLAUDE_PROJECT_DIR}` braced is substituted by Claude Code itself rather
16
+ * than by whatever shell happens to be there.
17
+ *
18
+ * `node` + a script path, never the script as the executable: on Windows exec
19
+ * form needs a real binary, and node.exe is one on every platform.
20
+ */
21
+ export function hookCommand(commandFile) {
22
+ return {
23
+ type: "command",
24
+ command: "node",
25
+ args: [`\${CLAUDE_PROJECT_DIR}/.claude/hooks/${shippedHookName(commandFile)}`],
26
+ };
27
+ }
28
+ /**
29
+ * Any reference to a shipped hook, whatever shape it takes.
30
+ *
31
+ * The leading separator is optional so a relative `node .claude/hooks/x.mjs`
32
+ * counts, but the character before `.claude` is still constrained, so
33
+ * `/opt/my.claude/hooks/x.mjs` does not. The extension is captured loosely
34
+ * because the same hook has been wired as `.ts` (pre-0.5, run through tsx) and
35
+ * as `.mjs` (since): both name the same hook, and an installer that only
36
+ * recognizes today's spelling appends a duplicate beside yesterday's.
37
+ */
38
+ const HOOK_REF = /(?:^|[\\/\s"'=])\.claude[\\/]hooks[\\/]([\w.-]+?)\.(?:mjs|js|ts)(?=$|[\s"'])/;
39
+ /**
40
+ * Which shipped hook an entry launches - its LOGICAL identity - or null.
41
+ * Returns the name WITHOUT extension, because the extension is spelling, not
42
+ * identity: `skill-reminder.ts` and `skill-reminder.mjs` are the same wiring.
43
+ *
44
+ * Install and uninstall both need to answer "is this entry mine?", and they used
45
+ * to answer it differently: exact string equality on one side, basename of
46
+ * `command` on the other. Neither survived a wiring rewritten into another valid
47
+ * form, so install appended a duplicate beside the working entry and uninstall
48
+ * walked past it, leaving a wiring that errors on every event. One predicate,
49
+ * used by both, is the fix - anything else drifts apart again.
50
+ */
51
+ export function wiredHookName(hook) {
52
+ if (!hook || typeof hook !== "object")
53
+ return null;
54
+ for (const token of [hook.command, ...(Array.isArray(hook.args) ? hook.args : [])]) {
55
+ if (typeof token !== "string")
56
+ continue;
57
+ const m = HOOK_REF.exec(token);
58
+ if (m)
59
+ return m[1];
60
+ }
61
+ return null;
62
+ }
63
+ /** The identity of a catalog hook file, in the same space wiredHookName returns. */
64
+ export const hookNameOf = (commandFile) => commandFile.replace(/\.(ts|mjs|js)$/, "");
65
+ /** Whether an entry already IS what hookCommand would write, down to the args. */
66
+ function isCurrentForm(hook, wanted) {
67
+ return hook.command === wanted.command
68
+ && Array.isArray(hook.args)
69
+ && hook.args.length === wanted.args?.length
70
+ && hook.args.every((a, i) => a === wanted.args?.[i]);
71
+ }
72
+ /**
73
+ * Rewrites a legacy wiring for a hook that is installed but NOT part of this
74
+ * run's selection, and returns how many it repaired.
75
+ *
76
+ * Without this, "re-run the installer to get the fix" is only true for the
77
+ * hooks the current detection happens to select. A hook installed once with
78
+ * --all, or one whose signal has since disappeared from the repo, keeps its
79
+ * broken pre-0.8 wiring while its file sits right there in .claude/hooks.
80
+ *
81
+ * Bounded by `installedFiles`, which comes from the lockfile: hooks WE put
82
+ * there. A hook the user wrote and wired themselves is never touched, even if
83
+ * it lives in the same directory - their shell form may carry a pipe or a
84
+ * `|| true` that exec form cannot express.
85
+ */
86
+ function repairUnselected(hooks, installedFiles, selected) {
87
+ const repairable = new Map(installedFiles
88
+ .map((f) => hookNameOf(f))
89
+ .filter((name) => !selected.has(name))
90
+ .map((name) => [name, hookCommand(`${name}.ts`)]));
91
+ if (repairable.size === 0)
92
+ return 0;
93
+ let repaired = 0;
94
+ for (const entries of Object.values(hooks)) {
95
+ if (!Array.isArray(entries))
96
+ continue;
97
+ for (const entry of entries) {
98
+ if (!entry || !Array.isArray(entry.hooks))
99
+ continue;
100
+ entry.hooks = entry.hooks.map((h) => {
101
+ const name = wiredHookName(h);
102
+ const wanted = name === null ? undefined : repairable.get(name);
103
+ if (!wanted || isCurrentForm(h, wanted))
104
+ return h;
105
+ repaired++;
106
+ return wanted;
107
+ });
108
+ }
109
+ }
110
+ return repaired;
111
+ }
112
+ export function mergeHookSettings(dotclaude, wirings,
113
+ /** Hook files the lockfile says are installed. Enables the sweep above. */
114
+ installedFiles = []) {
9
115
  const settingsPath = join(dotclaude, "settings.json");
10
116
  const existed = existsSync(settingsPath);
11
117
  let settings = {};
@@ -27,8 +133,10 @@ export function mergeHookSettings(dotclaude, wirings) {
27
133
  settings.hooks ??= {};
28
134
  const hooks = settings.hooks;
29
135
  let added = 0;
136
+ let rewired = 0;
30
137
  for (const w of wirings) {
31
- const command = `node $CLAUDE_PROJECT_DIR/.claude/hooks/${shippedHookName(w.commandFile)}`;
138
+ const wanted = hookCommand(w.commandFile);
139
+ const shipped = hookNameOf(w.commandFile);
32
140
  if (!Array.isArray(hooks[w.event])) {
33
141
  if (hooks[w.event] !== undefined)
34
142
  malformed = true;
@@ -40,16 +148,35 @@ export function mergeHookSettings(dotclaude, wirings) {
40
148
  entry = { ...(w.matcher ? { matcher: w.matcher } : {}), hooks: [] };
41
149
  entries.push(entry);
42
150
  }
43
- if (!entry.hooks.some((h) => h.command === command)) {
44
- entry.hooks.push({ type: "command", command });
151
+ const mine = entry.hooks.filter((h) => wiredHookName(h) === shipped);
152
+ if (mine.length === 0) {
153
+ entry.hooks.push(wanted);
45
154
  added++;
155
+ continue;
46
156
  }
157
+ // Already wired, possibly several times and possibly in the fragile pre-0.8
158
+ // shell form. Re-installing is how a user gets the fix, so this repairs in
159
+ // place: one entry, current form. Duplicates are collapsed, not tolerated.
160
+ const stale = mine.filter((h) => !isCurrentForm(h, wanted));
161
+ if (stale.length === 0 && mine.length === 1)
162
+ continue;
163
+ // In place, at the position it already held - never dropped and re-pushed.
164
+ // Order inside an event is semantic: this repo's own hooks README says
165
+ // PreToolUse `updatedInput` is last-wins, so appending our repaired entry
166
+ // after a hook the user wired themselves would silently flip which rewrite
167
+ // wins. A repair must not change anything but the entry it repairs.
168
+ const first = entry.hooks.findIndex((h) => wiredHookName(h) === shipped);
169
+ entry.hooks = entry.hooks.filter((h, i) => i === first || wiredHookName(h) !== shipped);
170
+ entry.hooks[first] = wanted;
171
+ rewired++;
47
172
  }
48
- const backedUp = existed && (added > 0 || malformed);
49
- if (added > 0 || malformed) {
173
+ rewired += repairUnselected(hooks, installedFiles, new Set(wirings.map((w) => hookNameOf(w.commandFile))));
174
+ const changed = added > 0 || rewired > 0 || malformed;
175
+ const backedUp = existed && changed;
176
+ if (changed) {
50
177
  if (backedUp)
51
178
  copyPath(settingsPath, `${settingsPath}.bak`);
52
179
  writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
53
180
  }
54
- return { added, backedUp, malformed };
181
+ return { added, rewired, backedUp, malformed };
55
182
  }
@@ -13,7 +13,8 @@
13
13
  import { existsSync, readFileSync, writeFileSync, rmSync, rmdirSync, readdirSync, renameSync } from "node:fs";
14
14
  import { join, resolve, sep } from "node:path";
15
15
  import { tokenPaths, compareToken } from "./lock.js";
16
- import { shippedHookName, ADOPTED_HEADER } from "./paths.js";
16
+ import { ADOPTED_HEADER } from "./paths.js";
17
+ import { wiredHookName, hookNameOf } from "./settings.js";
17
18
  /** Directories the installer creates, deepest first so a parent empties before it is tested. */
18
19
  const OWNED_DIRS = ["rules/shared", "rules", "skills", "hooks", "agents", "scripts"];
19
20
  /** Errors that mean "this directory is simply not removable", as opposed to a bug. */
@@ -41,10 +42,14 @@ export function unwireHookSettings(dotclaude, hookFiles) {
41
42
  const hooks = settings.hooks;
42
43
  if (!hooks || typeof hooks !== "object" || Array.isArray(hooks))
43
44
  return { removed: 0, unreadable: false };
44
- const ours = new Set(hookFiles.map((f) => shippedHookName(f)));
45
- const isOurs = (command) => {
46
- const file = command.split(/[/\\]/).pop() ?? "";
47
- return command.includes(".claude") && ours.has(file);
45
+ // The SAME predicate the installer writes with. Reading only `command` made
46
+ // every exec-form entry invisible here (its command is just "node"), so
47
+ // uninstall deleted the .mjs files and left the wirings behind - the dangling
48
+ // state the docblock above says it exists to prevent.
49
+ const ours = new Set(hookFiles.map((f) => hookNameOf(f)));
50
+ const isOurs = (hook) => {
51
+ const file = wiredHookName(hook);
52
+ return file !== null && ours.has(file);
48
53
  };
49
54
  let removed = 0;
50
55
  for (const event of Object.keys(hooks)) {
@@ -55,7 +60,7 @@ export function unwireHookSettings(dotclaude, hookFiles) {
55
60
  if (!entry || !Array.isArray(entry.hooks))
56
61
  continue;
57
62
  const before = entry.hooks.length;
58
- entry.hooks = entry.hooks.filter((h) => !(h && typeof h.command === "string" && isOurs(h.command)));
63
+ entry.hooks = entry.hooks.filter((h) => !isOurs(h));
59
64
  removed += before - entry.hooks.length;
60
65
  }
61
66
  // An entry we emptied was ours; one that was already empty is not our business.
package/docs/decisions.md CHANGED
@@ -88,3 +88,43 @@ To reassess if: the genericity scope changes, or an infra constraint requires ke
88
88
  **Consequences**: the open items from those entries are the ones not listed here, chiefly the reassessment of whether the audit suite deserves its own release cadence.
89
89
 
90
90
  **Status**: Done.
91
+
92
+ ## 2026-08-24 - Hook wiring moves to the exec form (issue #2)
93
+
94
+ **Context**: an external adopter running Windows with a space in the project path reported that the hooks failed in every session. The installer wrote each wiring as a single shell string (`"command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/x.mjs"`), which the shell split at the space - and which a Windows box without Git Bash never expanded at all. Five sibling defects were hiding behind that first one. Full analysis in [`postmortems/2026-08-24-hook-portability.md`](postmortems/2026-08-24-hook-portability.md).
95
+
96
+ **Options**: *(a)* keep the shell form and double-quote the placeholder, as Claude Code's docs allow; *(b)* move to the exec form (`"command": "node"`, `"args": [...]`), which the same docs recommend for any hook referencing a path placeholder.
97
+
98
+ **Decision**: **the exec form**, plus a single shared identity predicate (`wiredHookFile`) used by both install and uninstall.
99
+
100
+ Rationale: quoting is a property you have to get right at every site and re-check on every edit; the exec form removes the shell entirely, so there is nothing to quote and nothing to tokenize on any platform. `node` plus a script path rather than the script as the executable, because Windows exec form needs `command` to resolve to a real binary. The shared predicate exists because install and uninstall each answered "is this entry mine?" differently, and the two answers had already drifted apart into two separate defects.
101
+
102
+ **Consequences**: install **rewrites** a pre-0.8 shell-form wiring in place rather than appending beside it, so re-running the installer is how an affected user recovers; the repair is reported on its own line rather than folded into "no change". A hook needing genuine shell syntax (a pipe, `|| true`) stays in shell form with quoted placeholders - the `precommit-scan` snippet in `hooks/README.md` is the one such case. `hooks/README.md` and the CI grew a `windows-latest` leg and a `tools/portability.ts` gate so the class cannot return silently.
103
+
104
+ **Status**: Done.
105
+
106
+ ## 2026-08-24 - No `.gitattributes` forcing LF
107
+
108
+ **Context**: the CRLF defect (a frontmatter parser blind to `\r\n`) came from `core.autocrlf=true`, the Git default on Windows. The obvious reflex is to add a `.gitattributes` normalizing the repository to LF.
109
+
110
+ **Decision**: **do not add one.**
111
+
112
+ Rationale: it would fix our own checkout and nothing else. `skill-reminder` reads the `SKILL.md` files of the *adopting* repository, whose line endings we do not control, so the hook has to be CRLF-tolerant on its own merits. Worse, normalizing this repo would make the Windows CI job - which checks out with `autocrlf=true` precisely to reproduce the adopter's tree - vacuous, removing the only mechanical check that the tolerance still holds.
113
+
114
+ **Consequences**: contributors on Windows get a CRLF working tree, and that is intentional. Any parser reading repository files must handle both; `tools/portability.ts` fails the build on an LF-only frontmatter delimiter.
115
+
116
+ **Status**: Done.
117
+
118
+ ## 2026-08-24 - Transient CI branches may reach the public remote
119
+
120
+ **Context**: the 2026-08-08 entry locks the public GitHub history to one squashed commit per release, and states that the private history never reaches the public remote. Validating the issue #2 fixes needs the new `windows-latest` job to actually run, and GitHub Actions is the only place a Windows runner exists for this project. The workflow triggers on a push to `master`/`main` or on a pull request - both of which mean publishing work commits.
121
+
122
+ **Options**: *(a)* a throwaway private GitHub repository used only as a CI runner; *(b)* a transient branch or PR on the public repository, deleted afterwards; *(c)* no CI validation, rely on a local Windows VM only.
123
+
124
+ **Decision**: **(b)** - the "one commit per release" rule governs the **main history**, not every ref that transits the remote. A branch pushed to run CI and deleted afterwards is explicitly out of that rule's scope.
125
+
126
+ Rationale: the intent of the 2026-08-08 entry is that `git log main` reads as a release history, and a transient branch does not change that. Option (a) preserves the letter of the rule but needs a second repository whose CI configuration would drift from the real one - a validation of something slightly other than what ships. Option (c) trades a three-minute check for an hour of VM setup, and cannot cover the GitHub-hosted runner at all.
127
+
128
+ **Consequences**: work commits pushed on such a branch stay reachable through the pull request even after the branch is deleted - that is accepted, not overlooked. The rule stands unchanged for `main`: releases keep going through `git commit-tree`. A local Windows VM is being set up in parallel, because CI cannot cover the one thing that matters most here - Claude Code's own `${CLAUDE_PROJECT_DIR}` substitution in exec form, which only a real session on Windows exercises.
129
+
130
+ **Status**: Accepted.
@@ -0,0 +1,216 @@
1
+ # Postmortem - hooks silently dead off Linux (issue #2)
2
+
3
+ **Date**: 2026-08-24 · **Reported by**: an external adopter (issue #2, 2026-08-14)
4
+ **Affected versions**: up to and including 0.7.0 · **Severity**: high, silent
5
+ **Class**: portability of what ships - path semantics, launch contract, line endings
6
+
7
+ An adopter running Windows 11 with the project under `C:\Users\First LAST\...`
8
+ (a space in the username) and `core.autocrlf=true` reported that the hooks were
9
+ broken in every session. Six technical defects, all reproduced. None of them
10
+ could have been observed on our CI, which ran only on Linux.
11
+
12
+ This is the **third** occurrence of the same class: two prior `fix(hooks):`
13
+ commits already corrected an entry guard. That is what makes this a recurrence
14
+ postmortem rather than a bug report.
15
+
16
+ ---
17
+
18
+ ## 1. Timeline
19
+
20
+ | Date | Event |
21
+ |---|---|
22
+ | 2026-06-25 | `eacb52e` *fix(hooks): guard point d'entrée robuste* - the entry-guard problem is solved **correctly** for the session trio, using `pathToFileURL`. |
23
+ | 2026-07-10 | `6c6f34f` *perf(hooks): ship built JS* - hooks move from `.ts` to a built `.mjs`. Every guard bound to an extension becomes a latent bomb. |
24
+ | 2026-07-21 | `523edf8` *two shipped hooks were silently dead after the build* - occurrence #2. Fixed by **inventing a new idiom** (`argv[1].split("/")`) instead of reusing the June one. Adds `builtHook()`, a genuinely good harness - which runs on Linux. |
25
+ | 2026-08-14 | Issue #2 filed. Occurrence #3 of the guard, plus five sibling defects. |
26
+ | 2026-08-24 | This postmortem, the fixes, and the tooled guardrails. |
27
+
28
+ ---
29
+
30
+ ## 2. What was actually wrong
31
+
32
+ Seven findings, all confirmed against the code. The reporter's analysis was
33
+ accurate throughout; the numbering is theirs.
34
+
35
+ | # | Defect | Site |
36
+ |---|---|---|
37
+ | 1 | Wiring written as a shell string - dies on any path with a space | `src/settings.ts:40` |
38
+ | 2 | Install dedupes by exact string equality → duplicates after any rewrite | `src/settings.ts:51` |
39
+ | 3 | Uninstall reads `command` only → blind to exec form, leaves dangling wirings | `src/uninstall.ts:47` |
40
+ | 4 | Entry guard splits on `/` → never fires on win32, hook silently does nothing | `truncate-output`, `truncate-bash-output`, **and `readme-freshness`** |
41
+ | 5 | Frontmatter regex LF-only → blind to CRLF skills | `hooks/skill-reminder.ts:56` |
42
+ | 6 | `URL.pathname` → percent-encoded, unresolvable path | `hooks/truncate-output.ts:91` |
43
+ | 7 | `permissionDecision: "allow"` bypasses the permission prompt (design) | `bash-npm-silent`, `truncate-output` |
44
+
45
+ Found during the sweep, beyond the report:
46
+
47
+ - **A third occurrence of (4)** in `readme-freshness.ts:165`. The report listed two.
48
+ - **`hooks/README.md` had 9 fragile wirings, not 3.** Documentation that ships to
49
+ an adopter's machine is code (`rules/doc-code-parity.md`).
50
+ - **`tools/skills.ts` had the CRLF blind spot of (5)** in its frontmatter lint. On
51
+ a Windows checkout the lint would pass by seeing no frontmatter at all.
52
+ - **`truncate-bash-output` swallowed a spawn failure**: `result.stdout ?? ''` with
53
+ exit 0 reported the user's command as a silent success and discarded its
54
+ output entirely. Platform-independent, and the worst outcome available.
55
+
56
+ ---
57
+
58
+ ## 3. Root cause
59
+
60
+ > **The execution contract of a shipped hook exists nowhere as code.**
61
+
62
+ A hook must satisfy five clauses: *(a)* it is launched by an unknown runner
63
+ (POSIX shell? `cmd.exe`? direct spawn?), *(b)* from an arbitrary path that may
64
+ contain spaces and backslashes, *(c)* under a `.mjs` name its `.ts` source never
65
+ had, *(d)* over files whose line endings depend on the adopter's `core.autocrlf`,
66
+ *(e)* and it must never break the session.
67
+
68
+ No module, type, or test embodied that contract. Nine hooks re-implemented it
69
+ from memory, and produced **three competing idioms for the single question "am I
70
+ being run directly?"**:
71
+
72
+ ```
73
+ main() nu → session-inject, session-precompact, bash-npm-silent
74
+ pathToFileURL(argv[1]).href === … → session-writer, worktree-env-setup ✅ correct
75
+ argv[1].split("/").pop() → truncate-output, truncate-bash-output,
76
+ readme-freshness ❌ dead on win32
77
+ ```
78
+
79
+ The correct idiom **already existed in the repository, forty lines away**, when
80
+ the broken one was invented. Nothing designated it as *the* answer, so the next
81
+ person to face the problem solved it again, worse. The comment added in
82
+ `523edf8` - *"Entry guard by BASENAME, never by extension"* - is a **documentary**
83
+ guardrail: it protected against the previous regression and did not see the next
84
+ one coming.
85
+
86
+ ### Two amplifiers
87
+
88
+ **A. The CI tested one world.** Every job ran `ubuntu-latest`. The matrix
89
+ existed, but its axis was the **Node version**, not the operating system. The
90
+ most recent commit before the report (`c4a9828`, *"the Node 18 leg tested the
91
+ toolchain, not the product"*) shows that matrix being actively refined - without
92
+ anyone questioning the axis that was missing. All six technical defects are
93
+ invisible on Linux.
94
+
95
+ **B. The default failure mode is silence.** The issue title says it: *silently*.
96
+ A `PreToolUse` hook exiting 0 with empty stdout is **indistinguishable** from one
97
+ that decided there was nothing to do. Combined with `catch { /* a hook must never
98
+ break the session */ }`, this yields a system where total failure and nominal
99
+ operation produce the same observable. That is why *"three follow-up defects were
100
+ hiding behind it"* - not a coincidence, but the designed behavior.
101
+
102
+ ---
103
+
104
+ ## 4. Detection gap
105
+
106
+ Required by `rules/detection-gap-protocol.md`: a defect a **user** found is a
107
+ detection failure before it is anything else, because the user must never be the
108
+ safety net. Six defects reached an adopter past a green pipeline, a 35-mutant
109
+ harness, and a suite that deliberately exercises the built artifacts.
110
+
111
+ | Level | Should it have caught this? | Why it did not |
112
+ |---|---|---|
113
+ | Typecheck | No | Every defect is type-correct. `split("/")` on a win32 path, `URL.pathname`, an LF-only regex: all well-typed, all wrong. |
114
+ | Lint (biome) | **Yes, for the idioms** | No rule expressed "this construct is POSIX-only". Now `tools/portability.ts`, which found three live hits the moment it existed. |
115
+ | Unit tests | **Yes, for (2) and (3)** | Install and uninstall were each tested against their *own* notion of identity. Nothing tested them **against each other**, so two predicates drifted apart unobserved. Now one shared predicate plus a round-trip test. |
116
+ | Behavioral tests on the built artifacts | **Yes, for (4), (5), (6)** | `builtHook()` runs the real shipped `.mjs`, which is right, and runs it on ubuntu-latest, which is why it saw nothing. The harness was sound; its single environment was the gap. |
117
+ | CI matrix | **Yes, the primary gap** | The matrix axis was the Node version. No OS axis, so the only environment where any of the six can appear was never entered. |
118
+ | Mutation testing | No | It mutates our source, not the platform. No mutant expresses "run this on win32". |
119
+ | Release / smoke | No such stage | The package ships hooks that run on someone else's machine; nothing exercised them off Linux before publishing. The Windows job now does, on every push. |
120
+
121
+ Two gaps stand out because neither is about missing tests:
122
+
123
+ - **The suite tested one world.** Coverage was good and evidence was narrow. More
124
+ tests on Linux would have added nothing; one job on another OS added everything.
125
+ - **Two components were never tested against each other.** Install and uninstall
126
+ each passed alone. The contract *between* them was the thing nobody asserted,
127
+ and it is where (2) and (3) lived.
128
+
129
+ ## 5. Hypotheses tested
130
+
131
+ | Hypothesis | Verdict | Evidence |
132
+ |---|---|---|
133
+ | Isolated lapse of attention | **Refuted** | Three occurrences of the same construct across three months, two already carrying their own `fix(hooks):` commit. |
134
+ | Purely a Windows problem | **Refuted** | Defect (1) breaks on any path containing a space, including `/Users/Jean Dupont/`. Windows made it *systematic* (space in the username is near-default, `autocrlf=true` is the Git default), not *existent*. |
135
+ | The existing tooling should have caught it | **Refuted** | It structurally could not. `builtHook()` runs the real shipped `.mjs` - on Linux. Mutation testing does not mutate platform behavior. |
136
+ | The correct solution was unknown at the time | **Refuted** | `eacb52e` had shipped it a month earlier, in the same directory. |
137
+ | No shared runtime contract → each hook reinvents it | **Confirmed** | Three idioms for one question; two independent frontmatter parsers, one CRLF-tolerant by luck (`src/selector.ts`) and one not (`skill-reminder`). |
138
+
139
+ The luck in `src/selector.ts` is worth naming: `indexOf("\n---")` happens to
140
+ match inside `"\r\n---"`, and the stray `\r` happens to be eaten by a later
141
+ `.trim()`. Nobody decided that. It is the same parsing problem solved twice
142
+ independently, once fortunate and once not - which is the root cause restated.
143
+
144
+ ---
145
+
146
+ ## 6. Fixes
147
+
148
+ | # | Fix |
149
+ |---|---|
150
+ | 1 | `settings.ts` writes **exec form** (`command: "node"`, `args: ["${CLAUDE_PROJECT_DIR}/…"]`). No shell, and the braced placeholder is substituted by Claude Code itself. |
151
+ | 2, 3 | One shared predicate, `wiredHookFile()`, used by **both** install and uninstall. Install now also **repairs** a pre-0.8 shell-form wiring in place and collapses duplicates, so re-running the installer is how an affected user recovers. |
152
+ | 4 | The three divergent guards unified onto the June idiom. |
153
+ | 5 | `\r?\n` delimiter, description bounded to the line. Same fix in `tools/skills.ts`. |
154
+ | 6 | `fileURLToPath()`, and the helper path is shell-quoted with apostrophe escaping. |
155
+ | 7 | Documented in `hooks/README.md` - which commands stop prompting, and how to decline the trade. Not silently fixed: the behavior is required for `updatedInput` to apply. |
156
+ | + | `truncate-bash-output` now fails loudly on a spawn error instead of reporting empty success. |
157
+
158
+ ---
159
+
160
+ ## 7. Guardrails - tooled, not documentary
161
+
162
+ Each one sweeps **existing** code, per the anti-recurrence rule: a rule that only
163
+ applies to future code leaves the live bombs in place.
164
+
165
+ 1. **`windows-latest` CI job** (`.github/workflows/ci.yml`). The missing matrix
166
+ axis. Checks out with `core.autocrlf=true`, runs the portability gate, asserts
167
+ `skill-reminder` parses the CRLF tree, asserts `truncate-output` fires and
168
+ yields a resolvable helper, and installs/uninstalls into a path containing a
169
+ space. Deliberately **not** the full vitest suite: it shells out to `ln -s`,
170
+ `bash` stubs and `git worktree`, so a failure there would report on the test
171
+ harness rather than the product. Widening it means porting those helpers first.
172
+
173
+ 2. **`tools/portability.ts`**, wired into `npm test`. Two passes:
174
+ - *static* - forbids `split("/")` on a path, `URL.pathname` on a file URL, an
175
+ `argv[1]`-parsing entry guard, and LF-only frontmatter delimiters. It found
176
+ three real hits on first run.
177
+ - *smoke* - copies every built hook into a directory whose name contains a
178
+ space, runs it, and fails if it produces nothing. On the Windows runner the
179
+ same pass also covers the backslash separator.
180
+
181
+ Escape hatch: `// portability:allow <reason>` on the line, mirroring the
182
+ `gitleaks:allow` convention the repo's rules already use. Never disable the check.
183
+
184
+ 3. **A test pinning the positive form** - every guarded hook must use the one
185
+ idiom. The static gate forbids the known-bad shapes; this makes a *fourth*
186
+ invention a failing test rather than a discovery from a user.
187
+
188
+ 4. **Five new mutants** in `tools/mutations.ts`, one per fixed defect, each
189
+ verified to be killed. 38/38 mutations killed.
190
+
191
+ ### Deliberately not done: adding `.gitattributes`
192
+
193
+ Forcing LF in this repo would make our own checkout clean and the Windows CRLF
194
+ job **vacuous**, while doing nothing for adopters - `skill-reminder` reads the
195
+ `SKILL.md` files of *their* repository, whose line endings we do not control. The
196
+ hook has to be CRLF-tolerant on its own; keeping this repo CRLF-able on Windows
197
+ is what keeps the CI leg honest.
198
+
199
+ ---
200
+
201
+ ## 8. What this cost, and what to carry forward
202
+
203
+ Six defects reached users. All six were invisible to a green CI, a 38-mutant
204
+ harness, and a test suite that deliberately exercises the built artifacts. The
205
+ gap was never rigor - it was that **every check ran in the one environment where
206
+ none of the defects can appear.**
207
+
208
+ Two lessons worth generalizing beyond hooks:
209
+
210
+ - **When a fix invents a new way to do something the repo already does, that is
211
+ the defect.** The reviewable moment was `523edf8`, where a second idiom
212
+ appeared next to a working first one. Divergence is cheaper to catch than its
213
+ consequences.
214
+ - **A guardrail that cannot fail is not a guardrail.** "Entry guard by BASENAME,
215
+ never by extension" was true, prominent, and useless, because nothing executed
216
+ it. Prefer the check that runs.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ronce-racine",
3
- "version": "0.7.0",
3
+ "version": "0.8.0",
4
4
  "type": "module",
5
5
  "description": "Ronce Racine - generic Claude Code config (always-on rules + on-demand skills) with a distribution CLI",
6
6
  "license": "MIT",
@@ -44,7 +44,7 @@
44
44
  "lint": "biome check .",
45
45
  "lint:fix": "biome check --write .",
46
46
  "verify": "npm run typecheck && npm run lint && npm test",
47
- "test": "tsx tools/skills.ts validate && tsx tools/skills.ts triggers && tsx tools/skills.ts routing && tsx tools/skills.ts rules && tsx tools/skills.ts scripts && tsx tools/skills.ts hooks && tsx tools/skills.ts agents && tsx tools/skills.ts templates && tsx tools/skills.ts docs && vitest run",
47
+ "test": "tsx tools/skills.ts validate && tsx tools/skills.ts triggers && tsx tools/skills.ts routing && tsx tools/skills.ts rules && tsx tools/skills.ts scripts && tsx tools/skills.ts hooks && tsx tools/skills.ts agents && tsx tools/skills.ts templates && tsx tools/skills.ts docs && tsx tools/portability.ts && vitest run",
48
48
  "test:mutation": "tsx tools/mutations.ts",
49
49
  "eval:dry": "tsx playground/setup.ts >/dev/null && tsx tools/eval.ts run --dry-run",
50
50
  "skills:list": "tsx tools/skills.ts list",
@@ -54,7 +54,8 @@
54
54
  "prepublishOnly": "tsx tools/build.ts && npm test",
55
55
  "test:watch": "vitest",
56
56
  "coverage": "vitest run --coverage",
57
- "test:mutation:inprocess": "stryker run"
57
+ "test:mutation:inprocess": "stryker run",
58
+ "portability": "tsx tools/portability.ts"
58
59
  },
59
60
  "devDependencies": {
60
61
  "@biomejs/biome": "^2.5.7",