ronce-racine 0.5.3 → 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 (63) hide show
  1. package/AGENTS.md +4 -2
  2. package/README.md +213 -207
  3. package/agents/code-reviewer.md +1 -1
  4. package/dist/hooks/README.md +40 -0
  5. package/dist/hooks/readme-freshness.mjs +159 -0
  6. package/dist/install.js +114 -711
  7. package/dist/src/catalog.js +80 -0
  8. package/dist/src/detect.js +140 -0
  9. package/dist/src/lock.js +200 -0
  10. package/dist/src/paths.js +25 -0
  11. package/dist/src/selector.js +324 -0
  12. package/dist/src/settings.js +55 -0
  13. package/dist/src/uninstall.js +170 -0
  14. package/docs/adopting-a-repo.md +29 -22
  15. package/docs/architecture.md +9 -10
  16. package/docs/catalog.md +86 -0
  17. package/docs/decisions.md +31 -13
  18. package/docs/developing.md +69 -29
  19. package/docs/distribution-model.md +130 -0
  20. package/docs/evaluating-skills.md +42 -2
  21. package/docs/git-worktrees.md +2 -2
  22. package/docs/quality-bar.md +55 -0
  23. package/docs/templates/rule.template.md +2 -1
  24. package/docs/writing-a-rule.md +13 -3
  25. package/docs/writing-a-skill.md +16 -7
  26. package/package.json +17 -4
  27. package/skills/adversarial-feature-challenge/SKILL.md +5 -3
  28. package/skills/api-contract-versioning/SKILL.md +6 -4
  29. package/skills/bug-ticket-root-cause/SKILL.md +5 -3
  30. package/skills/bug-triage-structured/SKILL.md +5 -3
  31. package/skills/ci-pipeline-orchestration/SKILL.md +5 -3
  32. package/skills/commit-readiness-review/SKILL.md +7 -3
  33. package/skills/commit-readiness-review/scripts/precommit-scan.ts +3 -3
  34. package/skills/comprehensive-test-strategy/SKILL.md +5 -3
  35. package/skills/daily-workflow-optimization/SKILL.md +6 -4
  36. package/skills/database-schema-evolution/SKILL.md +6 -4
  37. package/skills/ddd-backend-implementation/SKILL.md +5 -3
  38. package/skills/design-system-component-lifecycle/SKILL.md +6 -4
  39. package/skills/detection-sweep/SKILL.md +7 -3
  40. package/skills/detection-sweep/scripts/sweep.ts +3 -3
  41. package/skills/domain-glossary/README.md +44 -0
  42. package/skills/domain-glossary/SKILL.md +166 -0
  43. package/skills/frontend-fullstack-implementation/SKILL.md +6 -4
  44. package/skills/frontend-spec-call-site-audit/SKILL.md +7 -3
  45. package/skills/frontend-spec-call-site-audit/scripts/audit-entry-points.ts +4 -1
  46. package/skills/merge-request-review/SKILL.md +5 -3
  47. package/skills/performance-profiling/README.md +69 -0
  48. package/skills/performance-profiling/SKILL.md +223 -0
  49. package/skills/performance-profiling/reference/go.md +235 -0
  50. package/skills/performance-profiling/reference/native.md +148 -0
  51. package/skills/performance-profiling/reference/node-web.md +157 -0
  52. package/skills/performance-profiling/reference/statistics.md +181 -0
  53. package/skills/performance-profiling/reference/tracy.md +137 -0
  54. package/skills/production-incident-diagnostic/SKILL.md +5 -3
  55. package/skills/qa-session-intake/SKILL.md +5 -3
  56. package/skills/recording-decisions/SKILL.md +5 -3
  57. package/skills/recurring-bug-root-cause/SKILL.md +5 -3
  58. package/skills/recurring-bug-root-cause/scripts/detect-recurring-fixes.ts +1 -1
  59. package/skills/refactoring-shared-component-api/SKILL.md +7 -3
  60. package/skills/refactoring-shared-component-api/scripts/sweep-call-sites.ts +10 -3
  61. package/skills/validating-features-end-to-end/SKILL.md +5 -3
  62. package/skills/visual-regression-check/SKILL.md +6 -4
  63. package/skills/writing-robust-tests/SKILL.md +8 -4
@@ -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();