@thedecipherist/claude-packs 0.0.0-stage → 1.0.0

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,132 @@
+#!/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 with the worst code: 2 if any
+// hook refused, else the first other non-zero. A hook that throws counts as exit 1 (a non-blocking error), as it would alone.
+// 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 { logCall } from './lib/event-log.mjs';
+import { appendRotated, isMain, logHook, projectRoot, readHookLog } from './lib/hook-log.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;
+    else if (c !== 0 && code === 0) code = c;
+  }
+  logCall(root, text, judged, appendRotated, performance.now());
+  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 is exit 1 and the next still runs', r3.code === 1 && r3.stderr.includes('throws failed') && r3.stdout.includes('"a"')]);
+  const rows = readHookLog(dir);
+  cases.push(['one timing line per hook per call', rows.length === 7 && 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 === 3]);
+  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 too', refused.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));

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

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+// PreToolUse (Write|Edit|MultiEdit|NotebookEdit|Bash): the shape law at write time, by every write route (lib/writes.mjs),
+// in every folder; only design/shape.json "exclude" (generated files, vendored code) is left out. KWB-1: a hard-coded
+// "slot 2" got past checks scoped to the engine folders. What a write may not ADD (what was there before is scan's job):
+//   - an instance literal of a concept (lib/shape.mjs, the number rule): a pattern hit, a concept word with a number or an
+//     ordinal, [N] on a per-instance array, `x == N` / `case N:` on a concept-named expression, a call that drives one
+//     instance by number, a hand-listed set (one line per instance), a role name before a concept word ("the PAD slot");
+//     allowed only as an example ("seen in:"), a listed selector, or a declared constant: "example, rule, or constant?";
+//   - in a test (under test/, tests/, probes/, or named *test* / *_probe*): the same, read as a test that drives one
+//     instance; the test loops over every instance or takes the instance as a parameter;
+//   - a selector for a concept (pickSlot, slotFor, firstSlot, ownerSlot) not listed in the manifest;
+//   - a new type that holds instances (an index member, or made N times in an array) whose concept has no row.
+// No design/shape.json: nothing is declared, so nothing is judged (doctor fails a project of a configuration that needs one). `--selftest`.
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { checkoutRoot, insideProject, relInCheckout, ROOT } from './lib/project.mjs';
+import { addedFindings, findInstanceLiterals, formatFinding, isExcluded, isTestFile, logRefusal, readShape } from './lib/shape.mjs';
+import { addedDefs, findSelectorDefs, findUnknownTypes } from './lib/shape-code.mjs';
+import { bashOf, editOf, runHook, scratchProject, verdicts, writeOf } from './lib/selftest.mjs';
+import { writesOf } from './lib/writes.mjs';
+import { asHook, isMain } from './lib/hook-log.mjs';
+
+const TEST_NOTE = 'a test that drives one instance proves that instance only: loop over every instance, or take the instance as a parameter';
+
+function judgeText(rel, before, after, shape) {
+  const lits = addedFindings(before, after, (t) => findInstanceLiterals(t, rel, shape));
+  const test = isTestFile(rel);
+  const out = lits.map((f) => `${formatFinding(f, rel)}${test ? `\n      ${TEST_NOTE}` : ''}`);
+  const concepts = lits.map((f) => f.concept);
+  for (const d of [...addedDefs(before, after, (t) => findSelectorDefs(t, rel, shape)), ...addedDefs(before, after, (t) => findUnknownTypes(t, rel, shape))]) {
+    out.push(formatFinding(d, rel));
+    concepts.push(d.concept ?? 'new-type');
+  }
+  return { out, concepts };
+}
+
+function main(text) {
+  let payload;
+  try { payload = JSON.parse(text); } catch { return 0; }
+  for (const w of writesOf(payload, payload.cwd ?? process.cwd())) {
+    if (w.after === null || w.op === 'delete' || !insideProject(w.path) || w.after.includes('\0')) continue;
+    const root = checkoutRoot(w.path);
+    const shape = readShape(root) ?? readShape(ROOT);
+    if (!shape || shape.error) continue;
+    const rel = relInCheckout(w.path);
+    if (rel.startsWith('..') || isExcluded(rel, shape)) continue;
+    const { out, concepts } = judgeText(rel, w.before, w.after, shape);
+    if (!out.length) continue;
+    logRefusal(ROOT, 'shape-law', concepts);
+    process.stderr.write(`BLOCKED by shape-law: this write names one instance of a concept that design/shape.json declares (KWB-1).\n${out.slice(0, 10).map((l) => `  ${l}`).join('\n')}${out.length > 10 ? `\n  ... and ${out.length - 10} more` : ''}\n` +
+      'Build for the shape: a loop over every instance or the generator; an instance seen in a bug goes on a "seen in:" line.\n');
+    return 2;
+  }
+  return 0;
+}
+
+const SELFTEST_SHAPE = {
+  concepts: {
+    slot: {
+      shape: 'many', count: 4, generator: 'slotId(i, field)', words: ['slot', 'slots'], patterns: ['\\bSlot::(amber|cyan|violet|green)\\b'],
+      arrays: ['kSlotNames'], selectors: { selectedSlot: 'the slot the player has open', firstEmpty: 'the first slot with nothing in it' },
+      constants: { initSlot: { instance: 1, reason: 'INIT plays one saw in slot 1' } },
+    },
+    mixer: { shape: 'one', id: 'mixer', words: ['mixer'] },
+    planet: { shape: 'many', generator: 'planetId(kind, field)', words: ['planet', 'planets'], names: ['DELAY', 'FILTER'] },
+  },
+  exclude: ['build/**', 'third_party/**'],
+  values: ['Cell'],
+};
+
+function selftest() {
+  const hook = fileURLToPath(import.meta.url);
+  const layout = { folders: { engines: { path: 'src/engines', purpose: 'engines' }, world: { path: 'src/world', purpose: 'world' }, ui: { path: 'src/ui', purpose: 'ui' }, tests: { path: 'tests', purpose: 'tests' }, docs: { path: 'docs', purpose: 'docs' } }, concepts: {} };
+  const dir = scratchProject({ 'design/shape.json': JSON.stringify(SELFTEST_SHAPE), 'src/world/Old.cpp': 'void f() { if (slot == 2) g(); }\n// PLACE\n' }, layout);
+  const bare = scratchProject({}, layout);
+  const w = (rel, text, at = dir) => runHook(hook, at, writeOf(join(at, rel), text));
+  const sh = (cmd) => runHook(hook, dir, bashOf(cmd, dir));
+  const loop = 'for (int slot = 0; slot < kSlots; ++slot) set(slotId(slot, "reverb.mix"), v);\n';
+  return verdicts('shape-law', [
+    // planted: an engine file
+    ['engine: slotIx == 1', w('src/engines/Engine.cpp', 'void f() { if (slotIx == 1) startCrew(); }\n'), 2],
+    ['engine: slots[1]', w('src/engines/Engine.cpp', 'auto& s = slots[1];\n'), 2],
+    ['engine: "slot2.reverb.mix"', w('src/engines/Bank.cpp', 'void f() { set("slot2.reverb.mix", v); }\n'), 2],
+    ['engine: Slot::cyan (a manifest pattern)', w('src/engines/Bank.cpp', 'auto c = Slot::cyan;\n'), 2],
+    ['engine: the one concept by number ("mixer2.bus")', w('src/engines/Bus.cpp', 'route("mixer2.bus");\n'), 2],
+    // planted: a world file and a UI file
+    ['world: s == 2 inside a loop over the slots', w('src/world/Space.cpp', 'for (int s = 0; s < kSlots; ++s) if (s == 2) addDelay(s);\n'), 2],
+    ['world: case 2 in a switch on the slot', w('src/world/Space.cpp', 'switch (slot) {\ncase 2: addDelay(); break;\n}\n'), 2],
+    ['ui: a hand-listed set, one line per slot', w('src/ui/View.cpp', 'slotGain.set(0, g);\nslotGain.set(1, g);\nslotGain.set(2, g);\nslotGain.set(3, g);\n'), 2],
+    ['ui: "the PAD slot"', w('src/ui/View.cpp', '// the PAD slot gets the arp\n'), 2],
+    ['ui: an unlisted name before a concept word ("the PAD planet", KWB-12)', w('src/ui/View.cpp', '// the PAD planet gets the arp\n'), 2],
+    ['ui: a caps concept word with no label before it, by number ("SLOTS 2", KWB-22)', w('src/ui/View.cpp', '// SLOTS 2 gets the arp\n'), 2],
+    ['ui: kSlotNames[2]', w('src/ui/View.cpp', 'draw(kSlotNames[2]);\n'), 2],
+    ['world: a selector not in the manifest', w('src/world/Pick.cpp', 'int pickSlot(int pad) {\n  return pad % 4;\n}\n'), 2],
+    ['world: a new instance type with no row', w('src/world/Lane.h', 'struct Lane { int index; float gain; };\n'), 2],
+    ['world: a value-like type not in "values" (KWB-10)', w('src/world/Tex.h', 'struct Tex { int index; float u; };\n'), 2],
+    // planted: a test
+    ['test: drives slot 2 only', w('tests/slot_test.cpp', 'TEST(Slots, Plays) { Engine e; e.playSlot(2); EXPECT_TRUE(e.sounding()); }\n'), 2],
+    ['test: named for one instance', w('tests/play_test.cpp', 'TEST(Play, Slot2Sounds) { run(); }\n'), 2],
+    // planted: a doc
+    ['doc: "Drive slot 2"', w('docs/notes.md', 'Drive slot 2 with the pad.\n'), 2],
+    ['doc: "the second slot"', w('docs/notes.md', 'The second slot holds the pad.\n'), 2],
+    // a shell route
+    ['bash heredoc: slotIx == 1', sh("cat > src/engines/Engine.cpp <<'EOF'\nif (slotIx == 1) go();\nEOF"), 2],
+    ['bash sed -i adds a literal', sh("sed -i 's|// PLACE|if (slot == 3) h();|' src/world/Old.cpp"), 2],
+    // the allowed forms
+    ['allowed: the generator in a loop', w('src/engines/Bank.cpp', loop), 0],
+    ['allowed: a test that loops over every slot', w('tests/slot_test.cpp', `TEST(Slots, Plays) {\n  ${loop}}\n`), 0],
+    ['allowed: a gate verdict before the word ("FAIL slot", KWB-15)', w('tools/gates/look.sh', 'for i in 0 1 2 3; do run "$i" || echo "FAIL slot $i"; done\n'), 0],
+    ['allowed: a seen in: line (doc)', w('docs/notes.md', 'seen in: slot 2, build for all slots\n'), 0],
+    ['allowed: a seen in: comment (code)', w('src/world/Space.cpp', '// seen in: slot 3 had no delay (B-1); every slot gets one\nfor (int s = 0; s < kSlots; ++s) addDelay(s);\n'), 0],
+    ['allowed: a listed selector', w('src/world/Pick.cpp', 'int selectedSlot() const {\n  return open;\n}\nif (selectedSlot == 1) x();\n'), 0],
+    ['allowed: a declared constant', w('src/engines/Init.cpp', 'play(slotId(initSlot, "osc.wave")); // INIT: slot 1\n'), 0],
+    ['allowed: a type listed in "values" (KWB-10)', w('src/world/Cell.h', 'struct Cell { int index; float x; };\n'), 0],
+    ['allowed: a listed identity name ("the DELAY planet", KWB-12)', w('src/ui/Space.cpp', '// the DELAY planet sits by the FILTER planet\n'), 0],
+    ['allowed: a type of a known concept', w('src/world/Card.h', 'struct SlotCard { int index; };\n'), 0],
+    ['allowed: not instances (buffer[1], channel == 1)', w('src/engines/Mix.cpp', 'float s = buffer[1]; if (channel == 1) s = pos[0];\nif (slots == kSlots) full = true;\n'), 0],
+    ['allowed: a multi-word caps label\'s value ("AIM PLANETS 100", KWB-22)', w('src/ui/View.cpp', '// every planet off, AIM PLANETS 100: nothing heard\n'), 0],
+    ['allowed: a multi-word caps label before the word ("a NOTES MONO slot", KWB-22)', w('src/engines/Engine.cpp', '// a NOTES MONO slot plays only its newest note\n'), 0],
+    ['allowed: a number past the count is a value ("slot 40 ms", KWB-22)', w('docs/notes.md', 'Each slot 40 ms later than the last.\n'), 0],
+    ['allowed: the whole range "slots 1-4"', w('docs/notes.md', 'Slots 1-4 all play every note.\n'), 0],
+    ['allowed: a line already there, edited and moved (KWB-23)', runHook(hook, dir, editOf(join(dir, 'src/world/Old.cpp'), 'void f() { if (slot == 2) g(); }\n// PLACE', '// PLACE\nvoid f() { if (slot == 2) g(); } // closed: B-1')), 0],
+    ['an edit adding a second copy of a literal already there (KWB-23)', runHook(hook, dir, editOf(join(dir, 'src/world/Old.cpp'), '// PLACE', 'void h() { if (slot == 2) g(); }')), 2],
+    ['allowed: a literal already there, untouched', runHook(hook, dir, editOf(join(dir, 'src/world/Old.cpp'), '// PLACE', '// nothing')), 0],
+    ['allowed: excluded (build/)', w('build/gen/Table.cpp', 'auto& s = slots[1];\n'), 0],
+    ['allowed: no design/shape.json', w('src/engines/Engine.cpp', 'if (slotIx == 1) go();\n', bare), 0],
+    ['allowed: another project', runHook(hook, dir, writeOf(join(dirname(dir), 'elsewhere/src/x.cpp'), 'if (slotIx == 1) go();\n')), 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('shape-law', main));

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

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// suite-once (PreToolUse, Bash): the whole test suite runs once, as the gate before landing, never while working (one
+// agent ran all 425 tests on 1 core; KWB-41: a session ran the kit's suite again and again, 12 minutes each, on code that had not
+// changed). A whole-suite command (`npm test`, `pnpm|yarn|bun test`, a bare `ctest`, the project's "commands".test in layout.json) is
+// refused while the checkout it runs in has uncommitted tracked changes: uncommitted means still working, and working runs only the
+// tests the change reaches (rule: test-only-what-changed; skill: pick-tests). Once the work is committed the gate passes. Named tests
+// (`npm test -- a.test.mjs`, `ctest -R x`) are always allowed. `--selftest` proves it.
+import { execFileSync } from 'node:child_process';
+import { resolve } from 'node:path';
+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';
+
+const WHOLE = /^(?:(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?test|ctest(?:\s+(?!-R\b|--tests-regex\b|-L\b|-I\b)\S+)*)$/;
+const PREFIX = /^(?:[A-Za-z_]\w*=\S*\s+|(?:env|command|nohup|time|exec)\s+|timeout\s+\S+\s+)+/;
+const REDIRECT = /\s*(?:\d?>>?|&>)&?\s*\S+/g;
+
+const clean = (part) => part.trim().replace(PREFIX, '').replace(REDIRECT, '').trim();
+
+function uncommitted(dir) {
+  try {
+    return execFileSync('git', ['-C', dir, '--no-optional-locks', 'status', '--porcelain', '--untracked-files=no'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).split('\n').filter((l) => l.trim());
+  } catch {
+    return []; // not a repository: nothing says the work is unfinished
+  }
+}
+
+export function refusal(command, cwd) {
+  const body = command.replace(/<<-?\s*['"]?(\w+)['"]?[\s\S]*?\n\1\b/g, '').replace(/'[^']*'|"(?:\\.|[^"\\])*"/g, "''");
+  let here = cwd;
+  for (const part of body.split(/&&|\|\||;|\||\n/)) {
+    const cd = part.trim().match(/^cd\s+(\S+)$/);
+    if (cd) { here = resolve(here, cd[1]); continue; }
+    const words = clean(part);
+    const { commands = {} } = readLayout(claudeRoot(here));
+    if (!WHOLE.test(words) && words !== commands.test) continue;
+    const dirty = uncommitted(checkoutRoot(resolve(here, 'x')));
+    if (!dirty.length) continue;
+    return `\`${words}\` runs the whole suite, and this checkout has uncommitted work:\n    ${dirty.slice(0, 8).join('\n    ')}\n` +
+      `The whole suite runs once, as the gate before landing, never while working. Run the tests this change reaches${commands['test-changed'] ? ` (\`${commands['test-changed']}\`)` : ' (the pick-tests skill)'}; commit; then run the whole suite once.\n`;
+  }
+  return null;
+}
+
+const main = (text) => judgeEvent(text, { name: 'suite-once', command: refusal });
+
+function selftest() {
+  const hook = new URL(import.meta.url).pathname;
+  const dir = scratchProject({ 'a.txt': 'one\n', '.claude/layout.json': JSON.stringify({ commands: { test: 'bash tools/all.sh', 'test-changed': 'npm run test:changed' } }) });
+  git(dir, 'init', '-q');
+  git(dir, 'add', 'a.txt', '.claude/layout.json');
+  git(dir, 'commit', '-qm', 'x');
+  const sh = (cmd) => runHook(hook, dir, bashOf(cmd, dir));
+  const committed = [
+    ['the gate, every change committed', sh('npm test'), 0],
+    ['the project\'s own whole-suite command, committed', sh('bash tools/all.sh'), 0],
+  ];
+  put(`${dir}/a.txt`, 'two\n');
+  const said = runHook(hook, dir, bashOf('npm test', dir));
+  return verdicts('suite-once', [
+    ...committed,
+    ['npm test on uncommitted work', said, 2],
+    ['pnpm, a run form and a prefix', sh('CI=1 timeout 300 pnpm run test'), 2],
+    ['a redirect and a pipe change nothing', sh('npm test > /tmp/log 2>&1 | tail -3'), 2],
+    ['a bare ctest', sh('ctest --output-on-failure'), 2],
+    ['the project\'s own whole-suite command', sh('bash tools/all.sh'), 2],
+    ['after other steps', sh('git status && npm test'), 2],
+    ['named tests', sh('npm test -- a.test.mjs'), 0],
+    ['the changed-only run', sh('npm run test:changed'), 0],
+    ['ctest of one pattern', sh("ctest -R 'svf'"), 0],
+    ['words about the suite', sh("echo 'npm test'"), 0],
+    ['a heredoc body', sh("cat <<'EOF'\nnpm test\nEOF"), 0],
+    ['another project', sh('cd /tmp && npm test'), 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('suite-once', main));