ronce-racine 0.5.2 → 0.7.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.
Files changed (64) hide show
  1. package/AGENTS.md +7 -2
  2. package/README.md +213 -207
  3. package/agents/code-reviewer.md +1 -1
  4. package/dist/hooks/README.md +62 -0
  5. package/dist/hooks/readme-freshness.mjs +159 -0
  6. package/dist/hooks/truncate-output.mjs +13 -5
  7. package/dist/install.js +114 -711
  8. package/dist/src/catalog.js +80 -0
  9. package/dist/src/detect.js +140 -0
  10. package/dist/src/lock.js +200 -0
  11. package/dist/src/paths.js +25 -0
  12. package/dist/src/selector.js +324 -0
  13. package/dist/src/settings.js +55 -0
  14. package/dist/src/uninstall.js +170 -0
  15. package/docs/adopting-a-repo.md +29 -22
  16. package/docs/architecture.md +9 -10
  17. package/docs/catalog.md +86 -0
  18. package/docs/decisions.md +31 -13
  19. package/docs/developing.md +69 -29
  20. package/docs/distribution-model.md +130 -0
  21. package/docs/evaluating-skills.md +42 -2
  22. package/docs/git-worktrees.md +2 -2
  23. package/docs/quality-bar.md +55 -0
  24. package/docs/templates/rule.template.md +2 -1
  25. package/docs/writing-a-rule.md +13 -3
  26. package/docs/writing-a-skill.md +16 -7
  27. package/package.json +17 -4
  28. package/skills/adversarial-feature-challenge/SKILL.md +5 -3
  29. package/skills/api-contract-versioning/SKILL.md +6 -4
  30. package/skills/bug-ticket-root-cause/SKILL.md +5 -3
  31. package/skills/bug-triage-structured/SKILL.md +5 -3
  32. package/skills/ci-pipeline-orchestration/SKILL.md +5 -3
  33. package/skills/commit-readiness-review/SKILL.md +7 -3
  34. package/skills/commit-readiness-review/scripts/precommit-scan.ts +3 -3
  35. package/skills/comprehensive-test-strategy/SKILL.md +5 -3
  36. package/skills/daily-workflow-optimization/SKILL.md +6 -4
  37. package/skills/database-schema-evolution/SKILL.md +6 -4
  38. package/skills/ddd-backend-implementation/SKILL.md +5 -3
  39. package/skills/design-system-component-lifecycle/SKILL.md +6 -4
  40. package/skills/detection-sweep/SKILL.md +7 -3
  41. package/skills/detection-sweep/scripts/sweep.ts +3 -3
  42. package/skills/domain-glossary/README.md +44 -0
  43. package/skills/domain-glossary/SKILL.md +166 -0
  44. package/skills/frontend-fullstack-implementation/SKILL.md +6 -4
  45. package/skills/frontend-spec-call-site-audit/SKILL.md +7 -3
  46. package/skills/frontend-spec-call-site-audit/scripts/audit-entry-points.ts +4 -1
  47. package/skills/merge-request-review/SKILL.md +5 -3
  48. package/skills/performance-profiling/README.md +69 -0
  49. package/skills/performance-profiling/SKILL.md +223 -0
  50. package/skills/performance-profiling/reference/go.md +235 -0
  51. package/skills/performance-profiling/reference/native.md +148 -0
  52. package/skills/performance-profiling/reference/node-web.md +157 -0
  53. package/skills/performance-profiling/reference/statistics.md +181 -0
  54. package/skills/performance-profiling/reference/tracy.md +137 -0
  55. package/skills/production-incident-diagnostic/SKILL.md +5 -3
  56. package/skills/qa-session-intake/SKILL.md +5 -3
  57. package/skills/recording-decisions/SKILL.md +5 -3
  58. package/skills/recurring-bug-root-cause/SKILL.md +5 -3
  59. package/skills/recurring-bug-root-cause/scripts/detect-recurring-fixes.ts +1 -1
  60. package/skills/refactoring-shared-component-api/SKILL.md +7 -3
  61. package/skills/refactoring-shared-component-api/scripts/sweep-call-sites.ts +10 -3
  62. package/skills/validating-features-end-to-end/SKILL.md +5 -3
  63. package/skills/visual-regression-check/SKILL.md +6 -4
  64. package/skills/writing-robust-tests/SKILL.md +8 -4
@@ -6,6 +6,28 @@ Hooks are authored in TypeScript but SHIP BUILT: the installer copies `.mjs` fil
6
6
 
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
+
10
+ ## Composition rule: a hook is never alone on its event
11
+
12
+ Several plugins can observe the same Claude Code event, and `PreToolUse`
13
+ `updatedInput` is last-wins. A hook that rewrites a command therefore hands its
14
+ output to whatever runs next, plus the transcript and the logs.
15
+
16
+ **A hook that rewrites a command must preserve the original in readable form.**
17
+ `truncate-output` learned this the hard way: it replaced the command with an
18
+ opaque base64 blob, which broke every downstream consumer and made transcripts
19
+ unreadable. It now carries the original as a trailing shell comment, which runs
20
+ to end of line and swallows quotes and apostrophes without interpreting them.
21
+
22
+ Two corollaries:
23
+
24
+ - **Rewrite only when the rewrite earns its cost.** `truncate-output` used to
25
+ wrap `git log --oneline -5`, whose output never reaches the truncation
26
+ threshold: pure loss.
27
+ - **Never mask an exit code.** Piping through `head` or `tail` replaces the
28
+ command's status with the pipe's. `bash-npm-silent` adds a flag rather than a
29
+ pipe for exactly this reason.
30
+
9
31
  ---
10
32
 
11
33
  ## `skill-reminder.ts` - skill suggestion (UserPromptSubmit)
@@ -151,6 +173,46 @@ If the session starts in a linked git worktree (not the main worktree) and the m
151
173
 
152
174
  ---
153
175
 
176
+ ## `readme-freshness.ts` - re-reads the README before a push (PreToolUse/Bash)
177
+
178
+ **Event**: `PreToolUse` · **Matcher**: `Bash` · **Opt-in** (spends one API call per push)
179
+
180
+ Before a `git push` that carries structural changes (`install.ts`, `package.json`,
181
+ `skills/`, `rules/`, `hooks/`, `agents/`, `scripts/`, `templates/`), asks Claude to
182
+ read `README.md` against the diff being pushed and report the claims it
183
+ contradicts: a wrong count, a renamed command, a mechanism that changed, a
184
+ documented file that moved.
185
+
186
+ An LLM rather than a grep, because the drift that matters is semantic - "34
187
+ skills" or "validated by npm test" stays true-looking to any pattern you can
188
+ write, and stops being true the moment the number or the command changes.
189
+
190
+ **Warns, never blocks, by default.** It fails open on every failure mode: no
191
+ `claude` on PATH, not authenticated, timed out, rate-limited, no upstream to
192
+ diff against. A push is never held hostage by this check.
193
+
194
+ | Variable | Effect |
195
+ |---|---|
196
+ | `RONCE_README_CHECK=block` | a contradiction denies the push instead of warning |
197
+ | `RONCE_README_CHECK=off` | skips the check entirely |
198
+ | `RONCE_CLAUDE_BIN` | path to the `claude` binary (default: `claude` on PATH) |
199
+
200
+ Scope: this sees pushes made by Claude. A human typing `git push` in their own
201
+ terminal does not go through it - keep a CI job for that guarantee.
202
+
203
+ ```json
204
+ {
205
+ "hooks": {
206
+ "PreToolUse": [
207
+ { "matcher": "Bash", "hooks": [{ "type": "command",
208
+ "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/readme-freshness.mjs" }] }
209
+ ]
210
+ }
211
+ }
212
+ ```
213
+
214
+ ---
215
+
154
216
  ## `precommit-scan.ts` - secret/debug scan before commit
155
217
 
156
218
  Shipped with the `commit-readiness-review` skill (`skills/commit-readiness-review/scripts/precommit-scan.ts`). Read-only, exit 1 if a secret/sensitive file is staged. Two possible wirings:
@@ -0,0 +1,159 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * PreToolUse hook for Bash: before a `git push`, has Claude re-read README.md
4
+ * against what the push actually changes, and reports the claims the change
5
+ * contradicts.
6
+ *
7
+ * Why an LLM rather than a grep: the drift that matters is semantic. A README
8
+ * saying "34 skills", "validated by npm test" or "hooks ship as TypeScript"
9
+ * stays true-looking to any pattern you can write, and stops being true the
10
+ * moment a number, a command or a mechanism changes. That is exactly the class
11
+ * of defect the doc-code-parity rule targets, and the only reader able to spot
12
+ * it is one that understands both texts.
13
+ *
14
+ * WARNS, never blocks, by design: this repo's own rule is that a hook fires on
15
+ * every session of every repo that installed it, so it fails open - a flaky
16
+ * gate gets disabled, which is worse than no gate. Set
17
+ * RONCE_README_CHECK=block to make a contradiction deny the push instead.
18
+ * Set RONCE_README_CHECK=off to skip it entirely.
19
+ *
20
+ * Scope, stated plainly: this sees pushes made by Claude. A human typing
21
+ * `git push` in their own terminal does not go through it - use the CI job for
22
+ * that guarantee.
23
+ *
24
+ * @version 1.0.0
25
+ * @last-reviewed 2026-08-08
26
+ */
27
+ import { readFileSync, existsSync } from 'node:fs';
28
+ import { spawnSync } from 'node:child_process';
29
+ import { join } from 'node:path';
30
+ /** Paths whose change can invalidate a README claim. Docs alone cannot. */
31
+ const STRUCTURAL = /^(install\.ts|package\.json|skills\/|rules\/|hooks\/|agents\/|scripts\/|templates\/|\.claude-plugin\/)/;
32
+ const VERDICT_OK = 'README_OK';
33
+ const TIMEOUT_MS = 120_000;
34
+ const MAX_DIFF_CHARS = 60_000;
35
+ export function isGitPush(cmd) {
36
+ // A push hidden behind `&&` still pushes; a `--dry-run` does not.
37
+ if (/--dry-run\b/.test(cmd))
38
+ return false;
39
+ return cmd.split(/&&|\|\||;/).some((part) => /^\s*git\s+(-\S+\s+)*push\b/.test(part));
40
+ }
41
+ /** Files the push would send, i.e. local commits the upstream does not have. */
42
+ export function changedFiles(cwd) {
43
+ const git = (args) => {
44
+ const r = spawnSync('git', args, { cwd, encoding: 'utf8', timeout: 10_000 });
45
+ return r.status === 0 ? (r.stdout ?? '').trim() : null;
46
+ };
47
+ // `@{push}` is the tracking ref when configured; fall back to the remote HEAD,
48
+ // and give up rather than guess when neither resolves (a first push, a repo
49
+ // with no upstream) - a diff against nothing would flag the entire README.
50
+ const base = git(['rev-parse', '--abbrev-ref', '@{push}']) ?? git(['rev-parse', '--abbrev-ref', 'origin/HEAD']);
51
+ if (!base)
52
+ return [];
53
+ const out = git(['diff', '--name-only', `${base}...HEAD`]);
54
+ return out ? out.split('\n').filter(Boolean) : [];
55
+ }
56
+ export function buildPrompt(readme, files, diff) {
57
+ return [
58
+ 'You are checking a README against changes about to be pushed.',
59
+ '',
60
+ 'Report ONLY statements in the README that the changes make FALSE or misleading:',
61
+ 'a wrong count, a command that no longer exists or was renamed, a described',
62
+ 'mechanism that changed, a documented file that moved or disappeared.',
63
+ '',
64
+ 'Do NOT report: style, tone, wording, missing sections, things you would',
65
+ 'phrase differently, or anything you cannot check against the diff below.',
66
+ 'Absence of documentation for a new thing is only worth reporting when the',
67
+ 'README already claims to list every one of them (a table of all skills, all',
68
+ 'hooks, all rules).',
69
+ '',
70
+ `If nothing in the README is contradicted, reply with exactly: ${VERDICT_OK}`,
71
+ 'Otherwise reply with one line per problem: `<README quote>` -> <what is now true>',
72
+ '',
73
+ '=== FILES IN THIS PUSH ===',
74
+ files.join('\n'),
75
+ '',
76
+ '=== DIFF ===',
77
+ diff.length > MAX_DIFF_CHARS ? `${diff.slice(0, MAX_DIFF_CHARS)}\n[diff truncated]` : diff,
78
+ '',
79
+ '=== README.md ===',
80
+ readme,
81
+ ].join('\n');
82
+ }
83
+ /** `claude -p --output-format json` wraps the text in {"result": "..."}. */
84
+ export function unwrapEnvelope(raw) {
85
+ try {
86
+ const parsed = JSON.parse(raw);
87
+ if (typeof parsed.result === 'string')
88
+ return parsed.result;
89
+ }
90
+ catch {
91
+ // Plain-text output, or a stub: use it as-is.
92
+ }
93
+ return raw;
94
+ }
95
+ function emit(decision, reason) {
96
+ process.stdout.write(JSON.stringify({
97
+ hookSpecificOutput: {
98
+ hookEventName: 'PreToolUse',
99
+ permissionDecision: decision,
100
+ permissionDecisionReason: reason,
101
+ },
102
+ }));
103
+ }
104
+ function main() {
105
+ const mode = process.env.RONCE_README_CHECK ?? 'warn';
106
+ if (mode === 'off')
107
+ return;
108
+ let parsed;
109
+ try {
110
+ parsed = JSON.parse(readFileSync(0, 'utf-8'));
111
+ }
112
+ catch {
113
+ return; // No input, or not JSON: nothing to decide on.
114
+ }
115
+ if (parsed.tool_name !== 'Bash')
116
+ return;
117
+ const cmd = parsed.tool_input?.command ?? '';
118
+ if (!cmd || !isGitPush(cmd))
119
+ return;
120
+ const cwd = parsed.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
121
+ const readmePath = join(cwd, 'README.md');
122
+ if (!existsSync(readmePath))
123
+ return;
124
+ const files = changedFiles(cwd);
125
+ if (!files.some((f) => STRUCTURAL.test(f)))
126
+ return; // Nothing that can invalidate a claim.
127
+ const bin = process.env.RONCE_CLAUDE_BIN ?? 'claude';
128
+ const diff = spawnSync('git', ['diff', '--stat', '-p', '@{push}...HEAD'], {
129
+ cwd, encoding: 'utf8', timeout: 15_000, maxBuffer: 32 * 1024 * 1024,
130
+ });
131
+ let readme;
132
+ try {
133
+ readme = readFileSync(readmePath, 'utf-8');
134
+ }
135
+ catch {
136
+ return;
137
+ }
138
+ const run = spawnSync(bin, ['-p', buildPrompt(readme, files, diff.stdout ?? ''), '--output-format', 'json'], {
139
+ cwd, encoding: 'utf8', timeout: TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024,
140
+ });
141
+ // Fail open on every failure mode: claude absent, not authenticated, timed
142
+ // out, rate-limited. A push must never be held hostage by this check.
143
+ if (run.error || run.status !== 0)
144
+ return;
145
+ const verdict = unwrapEnvelope(run.stdout ?? '').trim();
146
+ if (!verdict || verdict.includes(VERDICT_OK))
147
+ return;
148
+ const message = `README may be out of date with this push:\n${verdict}`;
149
+ if (mode === 'block')
150
+ emit('deny', `${message}\n\nFix the README, or push with RONCE_README_CHECK=off.`);
151
+ else
152
+ emit('allow', message);
153
+ }
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')
159
+ main();
@@ -20,7 +20,10 @@ const VERBOSE_PATTERNS = [
20
20
  // two-hook conflict on the same command - PreToolUse updatedInput is last-wins).
21
21
  /^\s*npm\s+run\s+(build|test|typecheck|lint)\b/,
22
22
  /^\s*npx\s+(vitest|tsc|nuxi|tsx)\b/,
23
- /^\s*git\s+(log|diff)\b/,
23
+ // git log/diff are only voluminous UNBOUNDED: `--oneline`, `-n`, `-<count>`
24
+ // or a `--stat` summary stay short, and rewriting them costs readability for
25
+ // nothing since the 4000-char threshold would never fire anyway.
26
+ /^\s*git\s+(log|diff)\b(?!.*(--oneline|--stat|--name-only|--name-status|\s-\d+|\s-n\s))/,
24
27
  /^\s*curl\s/,
25
28
  /^\s*docker\s+(build|logs)\b/,
26
29
  /^\s*rustup\s/,
@@ -38,10 +41,15 @@ export function isVerboseCommand(cmd) {
38
41
  }
39
42
  export function wrapCommand(cmd, hookDir) {
40
43
  const encoded = Buffer.from(cmd).toString('base64');
41
- // Run the helper via `npx tsx` (works on any Node ≥ 18) rather than
42
- // `node --experimental-strip-types` (only Node ≥ 22.6), matching how the
43
- // hooks themselves are wired in settings.json.
44
- return `TRUNCATE_CMD_B64=${encoded} node '${hookDir}/truncate-bash-output.mjs'`;
44
+ // The command travels base64-encoded so no shell quoting can break it, but an
45
+ // opaque blob is hostile to anything downstream: other hooks observing the
46
+ // same event, a human reading the transcript, a log. So the original is kept
47
+ // in clear as a TRAILING COMMENT - a shell comment runs to end of line and
48
+ // swallows quotes and apostrophes without interpreting them, which a leading
49
+ // `: 'cmd';` prefix does not (it breaks on `echo it's fine`).
50
+ // Newlines are flattened, otherwise the comment would swallow the next line.
51
+ const readable = cmd.replace(/\s*\n\s*/g, ' ').trim();
52
+ return `TRUNCATE_CMD_B64=${encoded} node '${hookDir}/truncate-bash-output.mjs' # ${readable}`;
45
53
  }
46
54
  function readStdin() {
47
55
  try {