@thedecipherist/claude-packs 0.0.0-stage → 1.1.0

package/packs/base/hooks/once-only.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+// once-only: code that exists once is called, never copied (claude-packs 0.9.0 item 9; KWB-1). Before a source write
+// lands (C++, Python, JS), the lines it adds are compared with the whole repo through an index kept between calls
+// (lib/dup-index.mjs, KWB-24: jscpd's whole-repo scan on every write was too slow; only files that changed are read again),
+// at jscpd's thresholds (lib/dup.mjs: 50 tokens and 6 lines, a gap of up to 2 lines, so a copy with one line changed is
+// still a copy). doctor's count and `claude-packs dup scan` still run jscpd over the whole repo. A near-duplicate is refused with the
+// existing location and the fix: call it, or extract one function that both call, parameterized over what differs.
+// Generated files, resources, vendored and built code, copy trees and design/shape.json "exclude" are never judged.
+// Every write route (lib/writes.mjs): Write, Edit, MultiEdit, NotebookEdit and the shell's >, >>, tee, sed -i, cp, mv,
+// a heredoc. The file is judged as it would be after the write, its old text left out, so editing a file never
+// matches its own old lines.
+//   node once-only.mjs --selftest
+import { readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { changedLines, copyGlobs, excludeGlobs, FIX, findJscpd, isGenerated, isSource, real } from './lib/dup.mjs';
+import { judgeWrites } from './lib/dup-index.mjs';
+import { matchesAny } from './lib/glob.mjs';
+import { readLayout } from './lib/layout.mjs';
+import { checkoutRoot, claudeRoot, insideProject } from './lib/project.mjs';
+import { bashOf, editOf, runHook, scratchProject, verdicts, writeOf } from './lib/selftest.mjs';
+import { readShape } from './lib/shape.mjs';
+import { readPayload, writesOf } from './lib/writes.mjs';
+import { isContent } from './lib/content.mjs';
+import { asHook, isMain } from './lib/hook-log.mjs';
+
+const HOW = `Code that exists once is called, never copied: ${FIX}. A function written for a many concept takes the instance as a parameter.\n` +
+  'Moving or extracting code: take the old copy out in the same write (one Write or MultiEdit), or take it out first.';
+
+// [{ root, layout, shape, w, range }] for every source write the call makes that once-only judges.
+function judged(payload) {
+  const out = [];
+  const gone = [];
+  for (const w of writesOf(payload, payload.cwd ?? process.cwd())) {
+    if (!insideProject(w.path)) continue;
+    if (w.op === 'delete') { gone.push(w.path); continue; }
+    if (w.after === null || w.after === undefined || !isSource(w.path) || isGenerated(w.after)) continue;
+    const root = checkoutRoot(w.path);
+    const rel = relative(root, w.path).replace(/\\/g, '/');
+    const layout = readLayout(claudeRoot(w.path));
+    const shape = readShape(root);
+    if (matchesAny(rel, [...excludeGlobs(layout, shape), ...copyGlobs(layout)]) || isContent(rel, layout)) continue;
+    const range = changedLines(w.before, w.after);
+    if (range) out.push({ root, layout, shape, w, rel, range });
+  }
+  return { list: out, gone };
+}
+
+export function judge(payload) {
+  const { list, gone } = judged(payload);
+  if (!list.length) return { code: 0 };
+  const found = [];
+  // each checkout written to: its index finds the candidates (built once, then only changed files are read again), jscpd
+  // confirms on those files alone (lib/dup-index.mjs judgeWrites)
+  for (const root of new Set(list.map((j) => j.root))) {
+    const mine = list.filter((j) => j.root === root);
+    const r = judgeWrites(root, mine.map((j) => ({ path: j.w.path, after: j.w.after, range: j.range })), { layout: mine[0].layout, shape: mine[0].shape, ignore: gone });
+    if (r.error) return { code: 0, note: `once-only could not judge: ${r.error}` }; // doctor shows a missing detector
+    const base = real(root);
+    const show = (s) => `${relative(base, s.file)}:${s.start}-${s.end}`;
+    for (const c of r.clones) found.push(`${show(c.at)} repeats ${show(c.other)} (${c.lines} lines, ${c.tokens} tokens)`);
+  }
+  if (!found.length) return { code: 0 };
+  const listed = [...new Set(found)];
+  return { code: 2, message: `BLOCKED by once-only: this write repeats code the repo already has.\n${listed.slice(0, 6).map((f) => `  ${f}`).join('\n')}${listed.length > 6 ? `\n  ... and ${listed.length - 6} more` : ''}\n${HOW}` };
+}
+
+const FN = (name, k = '2.0f') => `float ${name}::process (float x) noexcept
+{
+    const float g = std::tan (kPi * cutoff / sampleRate);
+    const float k = ${k} - 2.0f * resonance;
+    const float a1 = 1.0f / (1.0f + g * (g + k));
+    const float a2 = g * a1;
+    const float a3 = g * a2;
+    const float v3 = x - ic2eq;
+    const float v1 = a1 * ic1eq + a2 * v3;
+    const float v2 = ic2eq + a2 * ic1eq + a3 * v3;
+    ic1eq = 2.0f * v1 - ic1eq;
+    ic2eq = 2.0f * v2 - ic2eq;
+    return mode == 0 ? v2 : mode == 1 ? v1 : x - k * v1 - v2;
+}
+`;
+const PY = (name, scale = '0.5') => `def ${name}(frames, rate):
+    out = []
+    for i, f in enumerate(frames):
+        level = sum(abs(s) for s in f) / max(len(f), 1)
+        peak = max((abs(s) for s in f), default=0.0)
+        crest = peak / level if level > 0 else 0.0
+        out.append({"i": i, "t": i / rate, "level": level * ${scale}, "peak": peak, "crest": crest})
+    return [o for o in out if o["level"] > 0.001 and o["crest"] < 30.0]
+`;
+const JS = (name, pad = 2) => `export function ${name}(rows, widths) {
+  const cells = rows.map((r) => r.map((c, i) => String(c).padEnd(widths[i] ?? 0)));
+  const lines = cells.map((r) => r.join(' | ').trimEnd());
+  const rule = widths.map((w) => '-'.repeat(Math.max(w, 3))).join('-|-');
+  const head = lines.shift() ?? '';
+  const body = lines.filter((l) => l.length > 0).map((l) => \`  \${l}\`);
+  return [head, rule, ...body].join('\\n').padEnd(${pad});
+}
+`;
+
+function selftest() {
+  const hook = fileURLToPath(import.meta.url);
+  if (!findJscpd([process.cwd()])) {
+    console.error('once-only selftest FAILED: jscpd not found (npm install the kit with its optional dependency, or set CLAUDE_PACKS_JSCPD)');
+    return 1;
+  }
+  const dir = scratchProject({
+    'src/core/Filter.cpp': `#include "Filter.h"\n\n${FN('Filter')}`,
+    'tools/meter.py': `import math\n\n${PY('meter')}`,
+    'tools/table.mjs': `// table\n${JS('table')}`,
+    'design/shape.json': JSON.stringify({ concepts: {}, exclude: ['src/gen/**'] }),
+  });
+  const at = (f) => join(dir, f);
+  const w = (f, text) => runHook(hook, dir, writeOf(at(f), text));
+  const sh = (cmd) => runHook(hook, dir, bashOf(cmd, dir));
+  const filter = readFileSync(at('src/core/Filter.cpp'), 'utf8');
+  return verdicts('once-only', [
+    ['a copy of a function with one line changed, in a new file (Write)', w('src/core/Filter2.cpp', `#include "Filter2.h"\n\n${FN('Filter2', '1.5f')}`), 2],
+    ['a copy with its middle line changed (the two halves are one near-miss clone)', w('src/core/Mid.cpp', FN('Mid').replace('const float a2 = g * a1;', 'const float a2 = 0.5f * g * a1;')), 2],
+    ['a copy put into a header (.h and .cpp are one language)', w('src/core/Inline.h', `#pragma once\n\n${FN('Inline', '1.7f')}`), 2],
+    ['the same code calling the function instead', w('src/core/Mixer.cpp', '#include "Filter.h"\n\nfloat Mixer::render (float x) noexcept { return filter.process (x) * gain; }\n'), 0],
+    ['a near-copy added to the same file (Edit)', runHook(hook, dir, editOf(at('src/core/Filter.cpp'), '#include "Filter.h"\n', `#include "Filter.h"\n\n${FN('Shelf', '1.0f')}`)), 2],
+    ['a heredoc that writes a copy (Bash)', sh(`cat > src/core/Copy.cpp <<'EOF'\n${FN('Copy', '0.5f')}EOF`), 2],
+    ['cp of a source file (Bash)', sh('cp src/core/Filter.cpp src/core/Again.cpp'), 2],
+    ['mv of a source file: its old place is gone, nothing is repeated', sh('mv src/core/Filter.cpp src/core/Moved.cpp'), 0],
+    ['a Python copy with one value changed', w('tools/meter2.py', `import math\n\n${PY('meter2', '0.25')}`), 2],
+    ['a JS copy with one value changed', w('tools/table2.mjs', `// table 2\n${JS('table2', 4)}`), 2],
+    ['editing a function in place (its own old text is not a match)', w('src/core/Filter.cpp', filter.replace('2.0f - 2.0f * resonance', '1.8f - 2.0f * resonance')), 0],
+    ['two sed -i edits of one file in one command (KWB-13: each was read against the disk, two versions judged as copies)', sh("sed -i 's/2.0f - 2.0f/1.9f - 2.0f/' src/core/Filter.cpp && sed -i '1a // tuned' src/core/Filter.cpp"), 0],
+    ['moving a function within its file in one write', w('src/core/Filter.cpp', `${FN('Filter')}\n#include "Filter.h"\n`), 0],
+    ['a shape.json "exclude" path', w('src/gen/Filter3.cpp', FN('Filter3', '1.1f')), 0],
+    ['a generated file', w('src/core/Tables.cpp', `// generated by tools/make_tables.py: do not edit\n${FN('Tables', '1.2f')}`), 0],
+    ['resources', w('src/Resources/Filter4.cpp', FN('Filter4', '1.3f')), 0],
+    ['a short block of under 6 lines repeated', w('src/core/Small.cpp', 'float Small::process (float x) noexcept\n{\n    return x * gain;\n}\n'), 0],
+    ['a file outside the project', runHook(hook, dir, writeOf(join(tmpdir(), 'other-project-x', 'Filter5.cpp'), FN('Filter5', '1.4f'))), 0],
+  ]);
+}
+
+function main(text) {
+  const payload = readPayload(text);
+  if (!payload) return 0;
+  const r = judge(payload);
+  if (r.code === 2) process.stderr.write(`${r.message}\n`);
+  return r.code;
+}
+
+export const hook = main; // run-hooks.mjs calls it with the event's text (KWB-24)
+if (isMain(import.meta.url)) process.exit(process.argv.includes('--selftest') ? selftest() : await asHook('once-only', main));

package/packs/base/hooks/placement-law.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// PreToolUse (Write|Edit|MultiEdit|NotebookEdit|Bash; every route, lib/writes.mjs): every kind of thing goes in its one place, so the rules for
+// it load. layout.kinds says what goes where; a kind may name file patterns ("**/*.wgsl") and a
+// content pattern (processBlock, wgpu calls, paint(Graphics)). A file of that kind, or an edit that
+// ADDS that content, outside the kind's concept folders is refused. Content is read in C, C++ and shader files, or in the
+// kind's own "extensions" (a TypeScript kind: [".ts", ".tsx"]; KWB-36). `--selftest` proves it.
+import { readFileSync } from 'node:fs';
+import { extname, relative } from 'node:path';
+import { writesOf } from './lib/writes.mjs';
+import { matchesAny } from './lib/glob.mjs';
+import { conceptGlobs, readLayout } from './lib/layout.mjs';
+import { insideProject, checkoutRoot, claudeRoot } from './lib/project.mjs';
+import { verdicts } from './lib/selftest.mjs';
+import { asHook, isMain } from './lib/hook-log.mjs';
+
+const ROOT = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+const CODE = new Set(['.c', '.cc', '.cpp', '.cxx', '.h', '.hh', '.hpp', '.mm', '.m', '.wgsl', '.metal', '.hlsl']);
+
+const home = (layout, kind) => (kind.concepts ?? []).flatMap((c) => conceptGlobs(layout, c) ?? []);
+const where = (layout, kind) => layout.folders?.[kind.in]?.path ?? kind.in;
+
+export function misplaced(layout, rel, before, after) {
+  for (const [name, kind] of Object.entries(layout.kinds ?? {})) {
+    const globs = home(layout, kind);
+    if (globs.length === 0 || matchesAny(rel, globs)) continue;
+    const byName = kind.files && matchesAny(rel, kind.files) && before === '';
+    let byContent = false;
+    if (kind.content && (kind.extensions ? kind.extensions.includes(extname(rel)) : CODE.has(extname(rel)))) {
+      const re = new RegExp(kind.content);
+      byContent = re.test(after) && !re.test(before);
+    }
+    if (byName || byContent) return { name, kind, where: where(layout, kind), globs };
+  }
+  return null;
+}
+
+function main(text) {
+  let payload;
+  try { payload = JSON.parse(text); } catch { return 0; }
+  for (const w of writesOf(payload)) {
+    if (w.op === 'delete' || !insideProject(w.path)) continue;
+    const rel = relative(checkoutRoot(w.path), w.path).replace(/\\/g, '/');
+    // an unknown result (a program's output) is judged by name only
+    const hit = misplaced(readLayout(claudeRoot(w.path)), rel, w.before, w.after ?? w.before);
+    if (hit) return refuse(rel, hit);
+  }
+  return 0;
+}
+
+function refuse(rel, hit) {
+  process.stderr.write(
+    `BLOCKED by placement-law: ${rel} holds ${hit.kind.what} (kind "${hit.name}").\n` +
+      `That goes in ${hit.where}/, where its rules load (${hit.globs.join(', ')}).\n` +
+      'Put it there instead. If it truly belongs elsewhere, ask the user to change .claude/layout.json, then `npx --no-install @thedecipherist/claude-packs update`.\n',
+  );
+  return 2;
+}
+
+function selftest() {
+  const layout = {
+    folders: { audio: { path: 'src/audio' }, painter: { path: 'src/painter' }, tests: { path: 'tests' }, adapters: { path: 'api/adapters' } },
+    concepts: { audio: ['audio'], painter: ['painter'], tests: ['tests'], adapters: ['adapters'] },
+    kinds: {
+      'audio-entry': { what: 'processBlock', in: 'audio', concepts: ['audio', 'tests'], content: '\\bprocessBlock\\s*\\(' },
+      shader: { what: 'WGSL', in: 'painter', concepts: ['painter'], files: ['**/*.wgsl'] },
+      'db-gateway': { what: 'the database driver', in: 'adapters', concepts: ['adapters'], content: "from\\s+'mongodb'", extensions: ['.ts'] },
+    },
+  };
+  const cases = [
+    ['processBlock added outside audio', misplaced(layout, 'src/app/Helper.cpp', '', 'void processBlock (A& b) {}') !== null],
+    ['processBlock in audio is fine', misplaced(layout, 'src/audio/Engine.cpp', '', 'void processBlock (A& b) {}') === null],
+    ['processBlock already there is not re-judged', misplaced(layout, 'src/app/Old.cpp', 'processBlock (x);', 'processBlock (x); y();') === null],
+    ['a new shader outside painter', misplaced(layout, 'src/app/glow.wgsl', '', 'fn main() {}') !== null],
+    ['a shader in painter is fine', misplaced(layout, 'src/painter/glow.wgsl', '', 'fn main() {}') === null],
+    ['a comment in docs is not code', misplaced(layout, 'docs/notes.md', '', 'processBlock (x)') === null],
+    ['a kind with its own extensions: the driver in a handler (KWB-36)', misplaced(layout, 'api/handlers/user.ts', '', "import { MongoClient } from 'mongodb';") !== null],
+    ['the driver in the adapters is fine', misplaced(layout, 'api/adapters/db.ts', '', "import { MongoClient } from 'mongodb';") === null],
+    ['a kind with extensions leaves other files alone', misplaced(layout, 'api/handlers/notes.md', '', "from 'mongodb'") === null],
+  ];
+  return verdicts('placement-law', cases.map(([label, ok]) => [label, ok, true]));
+}
+
+export const hook = main; // run-hooks.mjs calls it with the event's text (KWB-24)
+if (isMain(import.meta.url)) process.exit(process.argv.includes('--selftest') ? selftest() : await asHook('placement-law', main));

package/packs/base/hooks/repo-litter.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// PreToolUse (Bash): what lands in git stays in its history for ever. `git add` of a file over the size limit, a working screenshot in the repo root or a debug
+// dump is refused. One real repo carried 991 MB, with 22 screenshots in its root and 64 MB files. Limits are in layout.json "guards": { "repoLitter": { "maxFileMb": 10,
+// "allow": ["<glob>"] } }. `--selftest` proves it.
+import { spawnSync } from 'node:child_process';
+import { statSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { gitAdds } from './lib/git-adds.mjs';
+import { matchesAny } from './lib/glob.mjs';
+import { readLayout } from './lib/layout.mjs';
+import { checkoutRoot, claudeRoot } from './lib/project.mjs';
+import { bashOf, git, put, runHook, scratchProject, verdicts } from './lib/selftest.mjs';
+import { judgeEvent } from './lib/writes.mjs';
+import { asHook, isMain } from './lib/hook-log.mjs';
+
+export const BIG_MB = 10;
+const MB = 1024 * 1024;
+const KEPT_IMAGE = /^(favicon|apple-touch-icon|logo|icon|og-image|social|android-chrome|mstile|safari-pinned)/i;
+const DUMP = /\.(har|heapsnapshot|dmp|core|log)$/i;
+
+export const isRootImage = (rel, allow) => /^[^/]+\.(png|jpe?g|gif|webp|bmp|mov|mp4)$/i.test(rel) && !KEPT_IMAGE.test(rel) && !matchesAny(rel, allow);
+
+function faultOf(rel, abs, cfg) {
+  if (matchesAny(rel, cfg.allow ?? [])) return null;
+  if (isRootImage(rel, [])) return `${rel} looks like a working screenshot in the repo root. Keep it out of git, or put an asset in its folder.`;
+  if (/:Zone\.Identifier$/.test(rel)) return `${rel} is a browser download marker. It is an invalid path on Windows and breaks checkout. Add *:Zone.Identifier to .gitignore.`;
+  if (DUMP.test(rel)) return `${rel} is a log or a debug dump. Add it to .gitignore.`;
+  let mb = 0;
+  try { mb = statSync(abs).size / MB; } catch { return null; }
+  const limit = cfg.maxFileMb ?? BIG_MB;
+  return mb > limit ? `${rel} is ${Math.round(mb)} MB (limit ${limit}). Git keeps it for ever: use object storage or a release.` : null;
+}
+
+// A named file, or what a folder would stage.
+function staged(dir, arg) {
+  const r = spawnSync('git', ['ls-files', '--others', '--modified', '--exclude-standard', '--', arg], { cwd: dir, encoding: 'utf8' });
+  return (r.stdout ?? '').split('\n').filter(Boolean).map((f) => resolve(dir, f));
+}
+
+function judgeAdd(command, cwd) {
+  for (const { dir, args } of gitAdds(command, cwd)) {
+    const root = checkoutRoot(join(dir, 'x'));
+    const cfg = readLayout(claudeRoot(join(dir, 'x'))).guards?.repoLitter ?? {};
+    for (const abs of args.filter((a) => !a.startsWith('-')).flatMap((a) => staged(dir, a))) {
+      const fault = faultOf(relative(root, abs).replace(/\\/g, '/'), abs, cfg);
+      if (fault) return `${fault}\nA real asset can be named in guards.repoLitter.allow.\n`;
+    }
+  }
+  return null;
+}
+
+const main = (text) => judgeEvent(text, { name: 'repo-litter', command: judgeAdd });
+
+function selftest() {
+  const hook = new URL(import.meta.url).pathname;
+  const dir = scratchProject({ 'src/a.pdf:Zone.Identifier': 'x', 'shot.png': 'x', 'favicon.png': 'x', 'src/a.ts': 'x', 'src/hero.png': 'x', 'trace.har': 'x', 'kept.png': 'x', '.claude/layout.json': JSON.stringify({ guards: { repoLitter: { maxFileMb: 1, allow: ['kept.png'] } } }) });
+  git(dir, 'init', '-q');
+  put(join(dir, 'media/big.bin'), 'x'.repeat(2 * MB));
+  const add = (paths) => runHook(hook, dir, bashOf(`git add ${paths}`, dir));
+  return verdicts('repo-litter', [
+    ['a screenshot in the root', add('shot.png'), 2],
+    ['a big file', add('media/big.bin'), 2],
+    ['a folder holding a big file', add('media'), 2],
+    ['a debug dump', add('trace.har'), 2],
+    ['a download marker', add('src/a.pdf:Zone.Identifier'), 2],
+    ['source', add('src/a.ts'), 0],
+    ['an image in its folder', add('src/hero.png'), 0],
+    ['a favicon in the root', add('favicon.png'), 0],
+    ['a file the layout allows', add('kept.png'), 0],
+    ['something else entirely', runHook(hook, dir, bashOf('git status', dir)), 0],
+  ]);
+}
+
+export const hook = main; // run-hooks.mjs calls it with the event's text (KWB-24)
+if (isMain(import.meta.url)) process.exit(process.argv.includes('--selftest') ? selftest() : await asHook('repo-litter', main));

package/packs/base/hooks/reuse-hint.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// UserPromptSubmit: repetition is cheapest to stop before a line is drafted. When a prompt's words name something the repo already has, what exists
+// goes in front of the prompt, so it is called and never written again. Only real matches, six at most; a prompt that matches nothing adds nothing.
+// `--selftest` proves it.
+import { TESTS, skippedBy } from './lib/elements.mjs';
+import { readLayout } from './lib/layout.mjs';
+import { checkoutRoot, claudeRoot } from './lib/project.mjs';
+import { repoIndex } from './lib/repo-index.mjs';
+import { scratchProject, verdicts } from './lib/selftest.mjs';
+import { asHook, isMain } from './lib/hook-log.mjs';
+
+const SHOWN = 6;
+const COMMON = new Set(`this that with from have make need want when what where which their there then them they will would should could into only also more
+  some just like been were does each every code file files function method class value data line test tests work works using used change update write read
+  please thing things sure right added adding`.split(/\s+/));
+
+const stem = (w) => w.toLowerCase().replace(/(?:ing|ers|er|es|ed|s)$/, '');
+const piecesOf = (name) => name.replace(/([a-z0-9])([A-Z])/g, '$1 $2').split(/[\s_-]+/).filter((w) => w.length >= 3).map(stem);
+const NEAR = 5;   // the pieces of a name lie within this many words of each other: scattered over a long prompt they are chance
+const LONG = 150; // words: past this a prompt is a document, and any name can be spelled out of it
+
+// { word: [its places in the prompt] }.
+function placesOf(prompt) {
+  const places = new Map();
+  (prompt.match(/[A-Za-z]+/g) ?? []).forEach((w, i) => {
+    if (w.length < 4 || COMMON.has(w.toLowerCase())) return;
+    const k = stem(w);
+    places.set(k, [...(places.get(k) ?? []), i]);
+  });
+  return places;
+}
+
+const closeTogether = (pieces, places) => pieces.some((p) => (places.get(p) ?? []).some((at) => pieces.every((q) => (places.get(q) ?? []).some((x) => Math.abs(x - at) <= NEAR))));
+
+// A compound name, with all its pieces in the prompt, close together. One word in common says nothing.
+export function matches(prompt, index) {
+  if (prompt.split(/\s+/).length > LONG) return [];
+  const places = placesOf(prompt);
+  const out = [];
+  for (const [file, e] of Object.entries(index)) {
+    for (const [name, line] of e.defs ?? []) {
+      const pieces = piecesOf(name);
+      if (pieces.length >= 2 && closeTogether(pieces, places)) out.push({ name, at: `${file}:${line}`, size: pieces.length });
+    }
+  }
+  return out.sort((a, b) => b.size - a.size).slice(0, SHOWN);
+}
+
+function main(text) {
+  const event = JSON.parse(text || '{}');
+  const at = `${event.cwd ?? process.cwd()}/x`;
+  const found = matches(event.prompt ?? '', repoIndex(checkoutRoot(at), [...TESTS, ...skippedBy(readLayout(claudeRoot(at)))], readLayout(claudeRoot(at))));
+  if (found.length) console.log(`Already in this repo, call it rather than write it again:\n${found.map((f) => `- ${f.name} (${f.at})`).join('\n')}`);
+  return 0;
+}
+
+function selftest() {
+  const dir = scratchProject({ 'src/dates.ts': 'export function formatDateRange(a, b) { return a + b; }\n', 'src/a.py': 'def parse_price_table(text):\n    return text\n', 'src/one.ts': 'export function render(a) { return a; }\n' });
+  const index = repoIndex(dir, []);
+  const named = (prompt) => matches(prompt, index).map((m) => m.name).join();
+  return verdicts('reuse-hint', [
+    ['a prompt naming what exists, camelCase', named('add a page that will format the date range of a booking'), 'formatDateRange'],
+    ['a prompt naming what exists, snake_case', named('parse the price table from the upload'), 'parse_price_table'],
+    ['it says where', matches('format the date range', index)[0]?.at, 'src/dates.ts:1'],
+    ['one word in common says nothing', named('the date of the last deploy'), ''],
+    ['a one-word name is never matched', named('render the render view'), ''],
+    ['an empty prompt', named(''), ''],
+    ['the pieces far apart', named('format the page first, then later on, much further down, show a date and a range'), ''],
+    ['a long document', named(`format the date range ${'and more words here '.repeat(40)}`), ''],
+    ['a prompt about nothing here', named('rename the settings page title'), ''],
+  ]);
+}
+
+export const hook = main; // run-hooks.mjs calls it with the event's text (KWB-24)
+if (isMain(import.meta.url)) process.exit(process.argv.includes('--selftest') ? selftest() : await asHook('reuse-hint', main));

package/packs/base/hooks/run-hooks.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+// run-hooks: one node process runs every kit hook of one settings entry, instead of one node process per hook (KWB-24:
+// The user saw 17 hooks take 48 s on one rm; each was its own node start, all at once, on a loaded machine). settings.json
+// names the runner and its hooks in one command: node ".../run-hooks.mjs" .claude/hooks/a.mjs .claude/hooks/b.mjs
+// Each hook module exports hook(text) (the event's JSON text, as stdin was) and returns its exit code; the runner calls
+// them in turn, catches each one's stdout and stderr, writes each one's timing line to .claude/hooks.log (lib/hook-log.mjs)
+// and its own (hook "run-hooks": the whole process, node's start-up included), and exits 2 if any hook refused. A hook that
+// throws, or exits with anything but 0 or 2, crashed, and lib/crash-policy.mjs decides what the call does (KF-18: a crash
+// on a tool call refuses once, and says so). lib/unread-writes.mjs says when no hook could read what a command writes (KF-40).
+// Every hook still runs on its own too (node .claude/hooks/a.mjs, its selftest, a project's hand-made entry).
+//   node run-hooks.mjs <hook path or name>...   (stdin: the event)
+//   node run-hooks.mjs --selftest
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, writeSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, isAbsolute, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { crashVerdict } from './lib/crash-policy.mjs';
+import { logCall } from './lib/event-log.mjs';
+import { appendRotated, isMain, logHook, projectRoot, readHookLog } from './lib/hook-log.mjs';
+import { unreadWrites } from './lib/unread-writes.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const RUNNER = 'run-hooks';
+export const nameOf = (arg) => basename(arg).replace(/\.mjs$/, '');
+const fileOf = (arg) => (isAbsolute(arg) ? arg : join(HERE, `${nameOf(arg)}.mjs`));
+
+// Several hooks' stdout: one is passed as it is; JSON objects are merged (their messages joined), anything else joined by lines.
+export function mergeOut(outs) {
+  const said = outs.filter((o) => o.trim());
+  if (said.length < 2) return said[0] ?? '';
+  const objs = said.map((o) => { try { const v = JSON.parse(o); return v && typeof v === 'object' && !Array.isArray(v) ? v : null; } catch { return null; } });
+  if (objs.some((o) => o === null)) return said.map((o) => o.replace(/\n$/, '')).join('\n') + '\n';
+  const out = {};
+  for (const o of objs) {
+    for (const [k, v] of Object.entries(o)) {
+      if (k === 'hookSpecificOutput' && out[k]) {
+        const ctx = [out[k].additionalContext, v.additionalContext].filter(Boolean).join('\n');
+        out[k] = { ...out[k], ...v, ...(ctx ? { additionalContext: ctx } : {}) };
+      } else if (typeof v === 'string' && typeof out[k] === 'string' && ['systemMessage', 'reason', 'stopReason'].includes(k)) out[k] = `${out[k]}\n${v}`;
+      else out[k] = v;
+    }
+  }
+  return JSON.stringify(out);
+}
+
+const capture = (stream, sink) => {
+  const write = stream.write;
+  stream.write = (chunk, ...rest) => { sink.push(String(chunk)); const cb = rest.find((r) => typeof r === 'function'); if (cb) cb(); return true; };
+  return () => { stream.write = write; };
+};
+
+// -> { code, stdout, stderr }. Each hook's own time is logged (its module's first import included).
+export async function runAll(args, text, root = projectRoot()) {
+  let ev = {};
+  try { ev = JSON.parse(text) ?? {}; } catch { /* the hooks read it themselves */ }
+  const outs = [];
+  const err = [];
+  const judged = [];
+  let code = 0;
+  for (const arg of args) {
+    const name = nameOf(arg);
+    const out = [];
+    const before = err.length;
+    const t0 = performance.now();
+    const undo = [capture(process.stdout, out), capture(process.stderr, err)];
+    let c;
+    try {
+      const mod = await import(pathToFileURL(fileOf(arg)).href);
+      if (typeof mod.hook !== 'function') throw new Error(`${name} exports no hook(text)`);
+      c = await mod.hook(text);
+    } catch (e) {
+      c = 1;
+      err.push(`run-hooks: ${name} failed: ${e?.stack ?? e}\n`);
+    } finally {
+      for (const u of undo) u();
+    }
+    c = Number.isInteger(c) ? c : 0;
+    outs.push(out.join(''));
+    const ms = performance.now() - t0;
+    logHook(root, { event: ev.hook_event_name, hook: name, ms, code: c, tool: ev.tool_name ?? ev.source });
+    judged.push({ hook: name, ms, code: c, reason: err.slice(before).join(''), out: out.join('') });
+    if (c === 2) code = 2;
+  }
+  logCall(root, text, judged, appendRotated, performance.now());
+  const crash = crashVerdict(root, ev, judged);
+  if (crash.stderr) err.push(crash.stderr);
+  if (crash.code === 2) code = 2;
+  outs.push(...[crash.stdout, code === 0 ? unreadWrites(ev, root) : ''].filter(Boolean));
+  return { code, stdout: mergeOut(outs), stderr: err.join('') };
+}
+
+async function selftest() {
+  const dir = mkdtempSync(join(process.env.TMPDIR ?? tmpdir(), 'run-hooks-'));
+  mkdirSync(join(dir, '.claude'));
+  const fake = (name, body) => { const f = join(dir, `${name}.mjs`); writeFileSync(f, `export function hook(text) {\n${body}\n}\n`); return f; };
+  const ok = fake('says-ok', "process.stdout.write('{\"systemMessage\":\"a\"}'); return 0;");
+  const no = fake('refuses', "process.stderr.write('BLOCKED by refuses\\n'); return JSON.parse(text).tool_name === 'Bash' ? 2 : 0;");
+  const also = fake('also-says', "console.log(JSON.stringify({ systemMessage: 'b' })); return 0;");
+  const boom = fake('throws', "throw new Error('planted');");
+  const bash = JSON.stringify({ hook_event_name: 'PreToolUse', tool_name: 'Bash', tool_input: { command: 'rm x' } });
+  const cases = [];
+  const r1 = await runAll([ok, no, also], bash, dir);
+  cases.push(['a refusal is the runner\'s exit 2', r1.code === 2]);
+  cases.push(['its message reaches stderr', r1.stderr.includes('BLOCKED by refuses')]);
+  cases.push(['two JSON outputs merge into one', JSON.parse(r1.stdout).systemMessage === 'a\nb']);
+  const r2 = await runAll([ok, no], JSON.stringify({ hook_event_name: 'PreToolUse', tool_name: 'Write' }), dir);
+  cases.push(['no refusal: exit 0', r2.code === 0 && r2.stdout === '{"systemMessage":"a"}']);
+  const r3 = await runAll([boom, ok], bash, dir);
+  cases.push(['a hook that throws refuses the call, says so, and the next still runs', r3.code === 2 && r3.stderr.includes('throws crashed') && r3.stdout.includes('"a"')]);
+  const r4 = await runAll([boom, ok], bash, dir);
+  cases.push(['the same call again goes through, and says so', r4.code === 0 && r4.stdout.includes('throws crashed')]);
+  const rows = readHookLog(dir);
+  cases.push(['one timing line per hook per call', rows.length === 9 && rows.filter((r) => r.hook === 'refuses').map((r) => r.code).join() === '2,0']);
+  cases.push(['the line names the event and the tool', rows[0].event === 'PreToolUse' && rows[0].tool === 'Bash']);
+  const lines = (f) => readFileSync(join(dir, '.claude/logs', f), 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l));
+  const refused = lines('refusals.jsonl');
+  cases.push(['every call is a line of events.jsonl', lines('events.jsonl').length === 4]);
+  cases.push(['a refusal keeps its reason and what was tried', refused[0].hook === 'refuses' && refused[0].reason.includes('BLOCKED by refuses') && refused[0].command === 'rm x']);
+  cases.push(['a crash is kept, in its own log', !refused.some((r) => r.hook === 'throws') && lines('crashes.jsonl').some((r) => r.hook === 'throws' && r.code === 1)]);
+  rmSync(dir, { recursive: true, force: true });
+  const bad = cases.filter(([, good]) => !good);
+  for (const [label] of bad) console.error(`run-hooks selftest FAILED: ${label}`);
+  if (!bad.length) console.log(`run-hooks selftest: OK (${cases.length} cases)`);
+  return bad.length ? 1 : 0;
+}
+
+if (isMain(import.meta.url)) {
+  const args = process.argv.slice(2);
+  if (args.includes('--selftest')) process.exit(await selftest());
+  let text = '';
+  try { text = readFileSync(0, 'utf8'); } catch { /* no stdin */ }
+  const root = projectRoot();
+  const r = await runAll(args, text, root);
+  let ev = {};
+  try { ev = JSON.parse(text) ?? {}; } catch { /* logged as '-' */ }
+  logHook(root, { event: ev.hook_event_name, hook: RUNNER, ms: performance.now(), code: r.code, tool: ev.tool_name ?? ev.source });
+  // written at once, then out: a hook may leave a timer or a child behind, and the event never waits on it
+  for (const [fd, s] of [[1, r.stdout], [2, r.stderr]]) if (s) try { writeSync(fd, s); } catch { /* a closed pipe */ }
+  process.exit(r.code);
+}

package/packs/base/hooks/secrets-guard.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// secrets-guard (PreToolUse, Write|Edit|MultiEdit|NotebookEdit|Bash): a secret never lands in git (KWB-33; STEP 3: ".env
+// never committed"). Refused, by every write route (lib/writes.mjs) and on `git add`:
+//   1. staging a secret file: `git add` (with -f too) of a .env (.env.example, .sample, .template and .dist are fine), a key
+//      file (*.pem, *.key, *.p12, *.pfx, *.jks, *.keystore, id_rsa and its kin) or credentials.json; and `git add -A` / `.` /
+//      `--all` / a folder while such a file in the checkout is not ignored;
+//   2. a write that ADDS a literal secret to any file but an ignored .env: a GitHub, Anthropic, OpenAI, AWS, Slack or Stripe
+//      key, a private key block, a connection string carrying its password (a ${VAR} or $VAR in its place is fine);
+//   3. writing a .env that git does not ignore (add `.env` to .gitignore first).
+// A token is named on the command that uses it ($PERSONAL_GITHUB_TOKEN), never written. Another project's files are not judged.
+//   node secrets-guard.mjs --selftest
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, join, relative, resolve } from 'node:path';
+import { judgeEvent } from './lib/writes.mjs';
+import { checkoutRoot } from './lib/project.mjs';
+import { bashOf, git, runHook, scratchProject, verdicts, writeOf } from './lib/selftest.mjs';
+import { gitAdds } from './lib/git-adds.mjs';
+import { SECRETS } from './lib/secret-patterns.mjs';
+import { asHook, isMain } from './lib/hook-log.mjs';
+
+const ENV = /^\.env(\..+)?$/;
+const ENV_OK = /\.(example|sample|template|dist)$/;
+const KEY = /\.(pem|key|private|p12|pfx|jks|keystore)$|^id_(rsa|dsa|ecdsa|ed25519)$|^credentials\.json$/;
+export const isSecretFile = (p) => { const b = basename(p); return (ENV.test(b) && !ENV_OK.test(b)) || KEY.test(b); };
+const isEnv = (p) => ENV.test(basename(p)) && !ENV_OK.test(basename(p));
+
+export { SECRETS };
+const count = (text, re) => (text.match(re) ?? []).length;
+export const addedSecret = (before, after) => SECRETS.find(([, re]) => count(after, re) > count(before ?? '', re))?.[0] ?? null;
+
+function ignored(root, path) {
+  const r = spawnSync('git', ['check-ignore', '-q', relative(root, path)], { cwd: root });
+  if (r.status === 0 || r.status === 1) return r.status === 0;
+  const gi = join(root, '.gitignore');   // not a git repo: read .gitignore
+  return existsSync(gi) && readFileSync(gi, 'utf8').split('\n').some((l) => /^\/?(\.env\*?|\.env\.\*|\*\.env|\.env\/?)\s*$/.test(l.trim()) && ENV.test(basename(path)));
+}
+
+function judgeWrite(w) {
+  const root = checkoutRoot(w.path);
+  if (isEnv(w.path)) return ignored(root, w.path) ? null : `${relative(root, w.path)} is a .env file git does not ignore. Add \`.env\` (and \`.env.*\`, with !.env.example) to .gitignore first; a .env is never committed.`;
+  if (w.after === null) return null;
+  const what = addedSecret(w.before, w.after);
+  return what ? `this write puts ${what} into ${relative(root, w.path)}. A secret lives in an ignored .env (or the machine's own store) and is read at run time; code reads it by name (process.env.X), a command names it ($X). Take the value out.` : null;
+}
+
+// `git add` of a secret file by name, or a sweep (-A, ., --all, a folder) while one is not ignored.
+function judgeAdd(command, cwd) {
+  for (const { dir, args: raw } of gitAdds(command, cwd)) {
+    const args = raw.filter((a) => !a.startsWith('-') || ['-A', '--all'].includes(a));
+    const named = args.find((a) => isSecretFile(a));
+    if (named) return `\`git add ${named}\`: a secret file is never staged (.env, keys, credentials). Keep it ignored; commit a .env.example with the names and no values.`;
+    if (args.some((a) => ['-A', '--all', '.', '*'].includes(a) || a.endsWith('/'))) {
+      const r = spawnSync('git', ['ls-files', '--others', '--exclude-standard'], { cwd: dir, encoding: 'utf8' });
+      const loose = (r.stdout ?? '').split('\n').filter((f) => f && isSecretFile(f));
+      if (loose.length) return `this \`git add\` would stage ${loose.join(', ')}, a secret file git does not ignore. Add it to .gitignore first, then stage by path.`;
+    }
+  }
+  return null;
+}
+
+const main = (text) => judgeEvent(text, {
+  name: 'secrets-guard',
+  command: judgeAdd,
+  write: (w) => (w.op === 'delete' ? null : judgeWrite(w)),
+});
+
+function selftest() {
+  const hook = new URL(import.meta.url).pathname;
+  const gh = `gh${'p'}_${'a1B2'.repeat(9)}`;   // built here, so this file holds no token
+  const pem = `-----BEGIN RSA ${'PRIVATE'} KEY-----`;
+  const dir = scratchProject({ '.gitignore': '.env\n', 'src/app.ts': 'export const x = 1;\n', 'src/old.ts': `const t = '${gh}';\nconst x = 1;\n` });
+  git(dir, 'init', '-q');
+  const open = scratchProject({ 'src/app.ts': '\n' });
+  git(open, 'init', '-q');
+  const run = (d, payload) => runHook(hook, d, payload);
+  const cases = [
+    ['a GitHub token written into source', run(dir, writeOf(join(dir, 'src/app.ts'), `const t = '${gh}';\n`)), 2],
+    ['a private key written into a doc', run(dir, writeOf(join(dir, 'docs/key.md'), `${pem}\n${'MIIEvQIBADANBgkqhkiG9w0BAQEFAASC'.repeat(3)}\n`)), 2],
+    ['a bare header in a doc is a placeholder', run(dir, writeOf(join(dir, 'docs/format.md'), `${pem}\n...\n`)), 0],
+    ['a connection string with its password', run(dir, writeOf(join(dir, 'src/db.ts'), "const u = 'mongodb+srv://user:hunter22@c0.x.net/db';\n")), 2],
+    ['a connection string that names its password ($VAR)', run(dir, writeOf(join(dir, 'src/db.ts'), 'const u = `mongodb+srv://user:${process.env.PW}@c0.x.net/db`;\n')), 0],
+    ['code that reads the token by name', run(dir, writeOf(join(dir, 'src/app.ts'), 'const t = process.env.GITHUB_TOKEN;\n')), 0],
+    ['the token into an ignored .env', run(dir, writeOf(join(dir, '.env'), `GITHUB_TOKEN=${gh}\n`)), 0],
+    ['a .env git does not ignore', run(open, writeOf(join(open, '.env'), 'A=1\n')), 2],
+    ['a .env.example with names only', run(open, writeOf(join(open, '.env.example'), 'GITHUB_TOKEN=\n')), 0],
+    ['git add .env', run(dir, bashOf('git add .env src/app.ts', dir)), 2],
+    ['git add -f of a key file', run(dir, bashOf('git add -f deploy/server.pem', dir)), 2],
+    ['git add by path, no secret', run(dir, bashOf('git add src/app.ts', dir)), 0],
+    ['git add -A while a .env is not ignored', (spawnSync('touch', [join(open, '.env')]), run(open, bashOf('git add -A', open))), 2],
+    ['git add -A while the .env is ignored', (spawnSync('touch', [join(dir, '.env')]), run(dir, bashOf('git add -A', dir))), 0],
+    ['an edit beside a token already there adds none', run(dir, { tool_name: 'Edit', tool_input: { file_path: join(dir, 'src/old.ts'), old_string: 'x = 1', new_string: 'x = 2' } }), 0],
+    ['git -C <dir> add of a .env', run(dir, bashOf(`git -C ${dir} add .env`, dir)), 2],
+  ];
+  return verdicts('secrets-guard', cases);
+}
+
+export const hook = main; // run-hooks.mjs calls it with the event's text (KWB-24)
+if (isMain(import.meta.url)) process.exit(process.argv.includes('--selftest') ? selftest() : await asHook('secrets-guard', main));