@thedecipherist/claude-packs 0.0.0-stage → 1.0.0

package/packs/base/checks/stub-reports-success.json

@@ -0,0 +1,31 @@
+{
+  "id": "stub-reports-success",
+  "why": "A control that reports success and does nothing is worse than none, because the team stops looking.",
+  "rule": ".claude/rules/a-control-is-seen-to-fire.md",
+  "globs": [
+    "**/*.ts",
+    "**/*.tsx",
+    "**/*.js",
+    "**/*.mjs",
+    "**/*.cjs",
+    "**/*.py",
+    "**/*.go",
+    "**/*.cpp",
+    "**/*.h"
+  ],
+  "exclude": [
+    "**/tests/**",
+    "**/test/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/e2e/**",
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**"
+  ],
+  "pattern": "(?://|\\*)\\s*(?:for now|stub|placeholder|would (?:decrypt|connect|send|call))[^\\n]*(?:\\n[^\\n]*){0,2}?\\b(?:success:\\s*true|return\\s+true|connected:\\s*true|ok:\\s*true)",
+  "bad": "// For now, return success\nres.json({ success: true, data: { connected: true } });",
+  "good": "await probe(uri);\nres.json({ success: true, data: { connected: true } });",
+  "flags": "i"
+}

package/packs/base/checks/test-skip-on-failed-setup.json

@@ -0,0 +1,17 @@
+{
+  "id": "test-skip-on-failed-setup",
+  "why": "A skip that hides a failed setup reports green on a broken product.",
+  "rule": ".claude/rules/a-control-is-seen-to-fire.md",
+  "globs": [
+    "**/tests/**/*.ts",
+    "**/test/**/*.ts",
+    "**/e2e/**/*.ts",
+    "**/*.spec.ts"
+  ],
+  "exclude": [
+    "**/node_modules/**"
+  ],
+  "pattern": "test\\.skip\\(\\s*!(?![A-Z_]+\\b)\\w+",
+  "bad": "test.skip(!wsId, 'No WS created');",
+  "good": "expect(wsId).toBeTruthy();"
+}

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

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// PreToolUse (Agent|Task, and Write|Edit|MultiEdit|NotebookEdit|Bash): a brief, a spec or a recipe names an instance of a
+// concept only as the example. KWB-1: one spec sentence ("PIANO in slot 1 and PAD in slot 2") and the recipes' "Slot 1 /
+// Slot 2" headings went into nine agent briefs, and every brief got work built and proved on slot 2 alone.
+// Judged: an agent's prompt, and what a write ADDS to docs/** or inbox/** (by every write route, lib/writes.mjs). An
+// instance of a concept in design/shape.json (lib/shape.mjs: a number, an ordinal, a role name before a concept word, a
+// pattern, an array index) is allowed only on a "seen in:" or "example:" line, or as a declared constant read by name (the
+// number rule's third form; KWB-4); a selector does not excuse
+// it here (a brief says "initSlot", not "slot 1"). The refusal quotes the manifest row and the fix: name the shape and
+// the generator; the instance is the example. Every refusal is counted per concept in .claude/usage.log. `--selftest`.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { checkoutRoot, insideProject, relInCheckout, ROOT } from './lib/project.mjs';
+import { addedFindings, ASK, findInstanceLiterals, isExcluded, logRefusal, quoteRow, readShape } from './lib/shape.mjs';
+import { bashOf, runHook, scratchProject, verdicts, writeOf } from './lib/selftest.mjs';
+import { writesOf } from './lib/writes.mjs';
+import { asHook, isMain } from './lib/hook-log.mjs';
+
+const BRIEFS = /^(docs|inbox)\//;
+const find = (shape) => (t) => findInstanceLiterals(t, 'brief.md', shape, { only: 'brief' });
+
+function refuse(where, findings, shape) {
+  const lines = findings.slice(0, 8).map((f) => `  ${where}:${f.line}: "${f.text.length > 140 ? `${f.text.slice(0, 137)}...` : f.text}" names ${f.concept} instance ${f.instance} (${f.why})`);
+  const rows = [...new Set(findings.map((f) => f.concept))].map((c) => {
+    const k = shape.concepts[c];
+    const how = k.shape === 'many' ? `many${k.count ? `(${k.count})` : ''}, made by ${k.row.generator}` : `one, id ${k.id}`;
+    return `  ${quoteRow(c, shape)}\n    fix: name the shape and the generator (every ${c}: ${how}); the instance is the example, on its own "seen in:" or "example:" line`;
+  });
+  logRefusal(ROOT, 'brief-guard', findings.map((f) => f.concept));
+  process.stderr.write(`BLOCKED by brief-guard: ${where} names one instance of a concept outside a "seen in:" or "example:" line — ${ASK}\n${lines.join('\n')}${findings.length > 8 ? `\n  ... and ${findings.length - 8} more` : ''}\n${rows.join('\n')}\n`);
+  return 2;
+}
+
+function main(text) {
+  let payload;
+  try { payload = JSON.parse(text); } catch { return 0; }
+  const tool = payload.tool_name;
+  if (tool === 'Agent' || tool === 'Task') {
+    const shape = readShape(ROOT);
+    if (!shape || shape.error) return 0;
+    const text = [payload.tool_input?.description, payload.tool_input?.prompt].filter((t) => typeof t === 'string').join('\n');
+    const hits = find(shape)(text);
+    return hits.length ? refuse('the agent brief', hits, shape) : 0;
+  }
+  for (const w of writesOf(payload, payload.cwd ?? process.cwd())) {
+    if (w.after === null || w.op === 'delete' || !insideProject(w.path)) continue;
+    const rel = relInCheckout(w.path);
+    if (!BRIEFS.test(rel)) continue;
+    const shape = readShape(checkoutRoot(w.path)) ?? readShape(ROOT);
+    if (!shape || shape.error || isExcluded(rel, shape)) continue;
+    const hits = addedFindings(w.before, w.after, find(shape));
+    if (hits.length) return refuse(rel, hits, shape);
+  }
+  return 0;
+}
+
+const SHAPE = {
+  concepts: {
+    slot: { shape: 'many', count: 4, generator: 'slotId(i, field)', words: ['slot', 'slots'], selectors: { selectedSlot: 'the slot the player has open' }, constants: { initSlot: { instance: 1, reason: 'INIT plays one saw in slot 1' } } },
+    layer: { shape: 'many', generator: 'layerId(i)', words: ['layer', 'layers'] },
+  },
+  exclude: [],
+};
+
+function selftest() {
+  const hook = fileURLToPath(import.meta.url);
+  const dir = scratchProject({ 'design/shape.json': JSON.stringify(SHAPE), 'docs/recipes.md': '# Recipes\nPLACE\n' });
+  const bare = scratchProject({});
+  const agent = (prompt, at = dir) => runHook(hook, at, { tool_name: 'Agent', tool_input: { description: 'build', prompt } });
+  const doc = (rel, text) => runHook(hook, dir, writeOf(join(dir, rel), text));
+  const n = () => { try { return readFileSync(join(dir, '.claude/usage.log'), 'utf8').split('\n').filter((l) => /\tbrief-guard\tslot$/.test(l)).length; } catch { return 0; } };
+  const cases = [
+    ['agent: "drive slot 2"', agent('Build the delay. Drive slot 2 and check it works.'), 2],
+    ['agent: "the PAD slot"', agent('Give the PAD slot its reverb.'), 2],
+    ['agent: "the second slot"', agent('Wire the second slot.'), 2],
+    ['agent: a declared constant read by name passes (the number rule\'s third form)', agent('Start in slot 1 (initSlot).'), 0],
+    ['doc: the INIT line naming its declared constant passes', doc('docs/recipes.md', '**INIT** (the declared constant initSlot): one saw in slot 1.\n'), 0],
+    ['agent: a selector is still no excuse in a brief', agent('Use selectedSlot: drive slot 2.'), 2],
+    ['agent: "seen in: slot 2, build for all slots"', agent('Fix the missing delay.\nseen in: slot 2, build for all slots'), 0],
+    ['agent: quotes the manifest row (its reason names slot 1)', agent(`The slot row: INIT plays one saw in slot 1. Build for every slot with slotId(i, field).`), 0],
+    ['agent: names the shape and the generator', agent('Every slot (many(4), slotId(i, field)) gets the delay; loop over all slots.'), 0],
+    ['agent: no design/shape.json', agent('Drive slot 2.', bare), 0],
+    ['recipe heading "Slot 1, the lead"', doc('docs/recipes.md', '# Recipes\n## Slot 1, the lead\n'), 2],
+    ['recipe heading "Layer lead"', doc('docs/recipes.md', '# Recipes\n## Layer lead\n'), 0],
+    ['inbox brief "drive slot 2"', doc('inbox/brief-7.md', 'Drive slot 2 until it works.\n'), 2],
+    ['inbox brief "example: slot 2"', doc('inbox/brief-7.md', 'Build the swap for all slots.\nexample: slot 2 lost its delay\n'), 0],
+    ['bash heredoc into docs/', runHook(hook, dir, bashOf("cat >> docs/recipes.md <<'EOF'\n## Slot 2, the pad\nEOF", dir)), 2],
+    ['not a brief: src/ is shape-law\'s', doc('src/world/x.md', 'slot 2\n'), 0],
+  ];
+  cases.push(['usage.log counts each refusal per concept', n(), 7]);
+  return verdicts('brief-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('brief-guard', main));

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

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// PreToolUse (Write|Edit|MultiEdit|NotebookEdit|Bash): code stays small in every direction, not only in lines per file. Measured on a real repo: 21% of
+// code lines held two or more statements, so a file "under 300 lines" was 500, and one function held 140 statements in 70 lines. A write is refused when it adds
+// a line too wide or packed, a function too long, or a function with too many parameters. What already stands is judged only if it gets worse.
+// `layout.json` "guards": { "codeShape": { "maxLineChars", "maxStatementsPerLine", "maxFunctionStatements", "maxParameters" } } changes a limit.
+// `--selftest` proves it.
+import { extname } from 'node:path';
+import { statementsOf } from './lib/code-shapes.mjs';
+import { isContent } from './lib/content.mjs';
+import { TESTS } from './lib/elements.mjs';
+import { functionsOf } from './lib/function-shapes.mjs';
+import { matchesAny } from './lib/glob.mjs';
+import { languageOf } from './lib/languages.mjs';
+import { readLayout } from './lib/layout.mjs';
+import { claudeRoot } from './lib/project.mjs';
+import { oneOffLines } from './lib/repo-index.mjs';
+import { bashOf, editOf, runHook, scratchProject, verdicts, writeOf } from './lib/selftest.mjs';
+import { judgeEvent } from './lib/writes.mjs';
+import { asHook, isMain } from './lib/hook-log.mjs';
+
+const LIMITS = { maxLineChars: 120, maxStatementsPerLine: 2, maxFunctionStatements: 50, maxParameters: 6 };
+const GENERATED = /\b(?:auto-?generated|generated by|do not edit|@generated)\b/i;
+
+// Lines this write adds, by number: a line that was already there is not its fault.
+function addedLines(before, after) {
+  const left = before.split('\n').reduce((m, l) => m.set(l, (m.get(l) ?? 0) + 1), new Map());
+  return after.split('\n').flatMap((l, i) => { const n = left.get(l) ?? 0; left.set(l, n - 1); return n > 0 ? [] : [i + 1]; });
+}
+
+function lineFault(lang, text, added, off, limits) {
+  const code = lang.blank(text).split('\n');
+  const perLine = statementsOf(text, lang).reduce((m, s) => m.set(s.line, (m.get(s.line) ?? 0) + 1), new Map());
+  for (const n of added.filter((x) => !off.has(x))) {
+    const width = code[n - 1]?.trimEnd().length ?? 0;
+    if (width > limits.maxLineChars) return `line ${n} is ${width} columns of code (limit ${limits.maxLineChars}). Break it where it reads.`;
+    if ((perLine.get(n) ?? 0) > limits.maxStatementsPerLine) return `line ${n} holds ${perLine.get(n)} statements. One statement a line: a diff, a breakpoint and a coverage line then mean something, and the file's size is true.`;
+  }
+  return null;
+}
+
+function functionFault(before, after, off, limits) {
+  const was = new Map(before.map((f) => [f.name, f]));
+  for (const f of after.filter((x) => !off.has(x.line))) {
+    const old = was.get(f.name);
+    if (f.statements > limits.maxFunctionStatements && f.statements > (old?.statements ?? 0)) return `${f.name} (line ${f.line}) holds ${f.statements} statements (limit ${limits.maxFunctionStatements}). A function that does many things cannot be tested in parts: split it by what it does.`;
+    if (f.params > limits.maxParameters && f.params > (old?.params ?? 0)) return `${f.name} (line ${f.line}) takes ${f.params} parameters (limit ${limits.maxParameters}). Pass one struct or object: positional arguments of one type get swapped and still compile.`;
+  }
+  return null;
+}
+
+function judgeWrite(w, rel) {
+  const ext = extname(w.path);
+  const lang = languageOf(ext);
+  if (!lang || w.op === 'delete' || w.after === null || w.after === undefined || matchesAny(rel, TESTS) || GENERATED.test(w.after.slice(0, 400))) return null;
+  const layout = readLayout(claudeRoot(w.path));
+  const limits = { ...LIMITS, ...(layout.guards?.codeShape ?? {}) };
+  if (matchesAny(rel, layout.guards?.codeShape?.exclude ?? []) || isContent(rel, layout)) return null;
+  const before = w.before ?? '';
+  const off = oneOffLines(w.after);
+  const fault = lineFault(lang, w.after, addedLines(before, w.after), off, limits) ?? functionFault(functionsOf(before, ext), functionsOf(w.after, ext), off, limits);
+  return fault ? `${fault}\nIf this one truly must stay, say so above it: \`one-off: <reason>\`.\n` : null;
+}
+
+const main = (text) => judgeEvent(text, { name: 'code-shape', write: judgeWrite });
+
+function selftest() {
+  const hook = new URL(import.meta.url).pathname;
+  const body = (n) => Array.from({ length: n }, (_, i) => `  total = total + step(${i});\n`).join('');
+  const long = `void big() {\n${body(60)}}\n`;
+  const dir = scratchProject({ 'src/old.cpp': `void old() {\n${body(55)}}\n`, 'src/packed.h': 'void p() { a(); b(); c(); d(); }\n', 'kept/x.cpp': '// x\n', '.claude/layout.json': JSON.stringify({ guards: { codeShape: { exclude: ['kept/**'] } } }) });
+  const w = (file, content) => runHook(hook, dir, writeOf(`${dir}/${file}`, content));
+  const wide = `int x = ${'a + '.repeat(40)}b;\n`;
+  return verdicts('code-shape', [
+    ['a function over the limit', w('src/a.cpp', long), 2],
+    ['the same in python', w('src/a.py', `def big(rows):\n${Array.from({ length: 60 }, (_, i) => `    total = step(${i})\n`).join('')}`), 2],
+    ['too many parameters', w('src/b.cpp', 'void f(int a, int b, int c, int d, int e, int f, int g) {\n  run(a);\n}\n'), 2],
+    ['a self parameter is not counted', w('src/b.py', 'def f(self, a, b, c, d, e, g):\n    run(a)\n'), 0],
+    ['packed statements', w('src/c.cpp', 'void f() {\n  a(); b(); c();\n}\n'), 2],
+    ['a for header is one statement', w('src/d.cpp', 'void f() {\n  for (int i = 0; i < n; i++) total += v(i);\n}\n'), 0],
+    ['a wide line', w('src/e.cpp', wide), 2],
+    ['a wide comment is no code', w('src/f.cpp', `// ${'word '.repeat(50)}\nint x = 1;\n`), 0],
+    ['an old long function, edited without growing', runHook(hook, dir, editOf(`${dir}/src/old.cpp`, 'step(3)', 'step(4)')), 0],
+    ['an old long function that grows', runHook(hook, dir, editOf(`${dir}/src/old.cpp`, '  total = total + step(3);\n', '  total = total + step(3);\n  total = total + step(99);\n')), 2],
+    ['an old packed line that is edited', runHook(hook, dir, editOf(`${dir}/src/packed.h`, 'void p()', 'void q()')), 2],
+    ['a marked one-off', w('src/g.cpp', `// one-off: the table is generated by hand\n${wide}`), 0],
+    ['a test file', w('tests/x_test.cpp', long), 0],
+    ['an excluded folder', w('kept/y.cpp', long), 0],
+    ['a tutorial sample in a content folder', w('articles/guide/y.cpp', long), 0],
+    ['a blog route is code', w('src/app/blog/page.cpp', long), 2],
+    ['a heredoc that adds a packed line', runHook(hook, dir, bashOf("cat > src/h.cpp <<'EOF'\nvoid f() { a(); b(); c(); }\nEOF", dir)), 2],
+  ]);
+}
+
+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('code-shape', main));

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

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// PreToolUse (Write|Edit|MultiEdit|NotebookEdit|Bash): a kind is dispatched in ONE place (v7 additions, 0.11.0).
+// When a write ADDS a `switch` on some kind (mode, type, action, format…) and another code file of the same checkout already
+// switches on that kind, the kind's behaviour is being spread out: the next new kind then needs an edit in every one of those
+// places. Refused: the kind's behaviour belongs in one object, table or class (rule: behaviour-lives-with-its-kind).
+// Every write route (lib/writes.mjs judgeEvent); a file is judged against its own checkout (a worktree against the worktree);
+// tests, `protected` globs, vendored and built folders are never scanned. `--selftest` proves it.
+import { readFileSync } from 'node:fs';
+import { extname, join } from 'node:path';
+import { blankCode } from './lib/cpp-scan.mjs';
+import { CODE, TESTS, codeFiles } from './lib/elements.mjs';
+import { matchesAny } from './lib/glob.mjs';
+import { readLayout } from './lib/layout.mjs';
+import { checkoutRoot, claudeRoot } from './lib/project.mjs';
+import { bashOf, editOf, runHook, scratchProject, verdicts, writeOf } from './lib/selftest.mjs';
+import { judgeEvent } from './lib/writes.mjs';
+import { asHook, isMain } from './lib/hook-log.mjs';
+
+const SWITCH = /\bswitch\s*\(\s*([^()]*?(?:\([^()]*\))?)\s*\)\s*\{/g;
+
+// The kind a switch dispatches on: the last name in its expression (args.kind -> kind, p->mode() -> mode).
+export function kindsSwitched(text) {
+  const out = [];
+  for (const m of blankCode(text).matchAll(SWITCH)) {
+    const name = m[1].replace(/\(\s*\)$/, '').split(/\?\.|\.|->|::/).pop().trim();
+    if (/^[A-Za-z_$][\w$]{2,}$/.test(name)) out.push(name);
+  }
+  return out;
+}
+
+const count = (list) => list.reduce((m, k) => m.set(k, (m.get(k) ?? 0) + 1), new Map());
+
+// The kinds a write switches on more often than before.
+export function newKinds(before, after) {
+  const was = count(kindsSwitched(before));
+  return [...count(kindsSwitched(after))].filter(([k, n]) => n > (was.get(k) ?? 0)).map(([k]) => k);
+}
+
+// { kind -> [files] }: the other code files of the checkout that already switch on each kind.
+export function elsewhere(root, selfRel, kinds, layout = readLayout(root)) {
+  const skip = [...TESTS, ...(layout.protected ?? [])];
+  const found = new Map();
+  for (const rel of codeFiles(root, skip)) {
+    if (rel === selfRel) continue;
+    const there = new Set(kindsSwitched(readFileSync(join(root, rel), 'utf8')));
+    for (const k of kinds) if (there.has(k)) found.set(k, [...(found.get(k) ?? []), rel]);
+  }
+  return found;
+}
+
+// One write: null when it adds no second place for a kind; else the refusal.
+function judgeWrite(w, rel) {
+  if (w.op === 'delete' || w.after === null || w.after === undefined || !CODE.has(extname(w.path)) || matchesAny(rel, TESTS)) return null;
+  const kinds = newKinds(w.before ?? '', w.after);
+  if (kinds.length === 0) return null;
+  const found = elsewhere(checkoutRoot(w.path), rel, kinds, readLayout(claudeRoot(w.path)));
+  if (found.size === 0) return null;
+  const lines = [...found].map(([k, files]) => `  "${k}" is already switched on in: ${files.slice(0, 5).join(', ')}`).join('\n');
+  return `${rel} adds a second place that branches on the same kind.\n${lines}\n` +
+    'Give each kind its own object, table entry or class (rule: behaviour-lives-with-its-kind), and call it from both places,\n' +
+    'so a new kind is one new entry instead of an edit in every switch.\n';
+}
+
+const main = (text) => judgeEvent(text, { name: 'dispatch-once', write: judgeWrite });
+
+function selftest() {
+  const hook = new URL(import.meta.url).pathname;
+  const dir = scratchProject({
+    'src/render.cpp': 'float draw (Shape& s) { switch (s.mode) { case Mode::line: return 1.0f; default: return 0.0f; } }\n',
+    'tests/render_test.cpp': 'void t (Shape& s) { switch (s.format) { default: break; } }\n',
+  });
+  const w = (file, content) => runHook(hook, dir, writeOf(join(dir, file), content));
+  return verdicts('dispatch-once', [
+    ['a new switch on a kind switched in another file', w('src/label.cpp', 'void label (Shape& s) { switch (s.mode) { default: break; } }\n'), 2],
+    ['a switch on a kind switched nowhere else', w('src/order.cpp', 'void order (Row& r) { switch (r.direction) { default: break; } }\n'), 0],
+    ['the same file is not "elsewhere"', runHook(hook, dir, editOf(join(dir, 'src/render.cpp'), 'return 1.0f;', 'return 2.0f;')), 0],
+    ['a kind switched only in a test is not dispatch', w('src/save.cpp', 'void save (Shape& s) { switch (s.format) { default: break; } }\n'), 0],
+    ['a test file may switch on any kind', w('tests/label_test.cpp', 'void t (Shape& s) { switch (s.mode) { default: break; } }\n'), 0],
+    ['a switch in a comment or string is not a switch', w('src/note.ts', '// switch (x.mode) {\nconst s = "switch (x.mode) {";\n'), 0],
+    ['the kind is the last name in the expression', w('src/args.ts', 'function f(args) { switch (args?.shape.mode) { default: } }\n'), 2],
+    ['a heredoc that adds a second switch', runHook(hook, dir, bashOf("cat > src/b.cpp <<'EOF'\nvoid b (Shape& s) { switch (s.mode) { default: break; } }\nEOF", dir)), 2],
+    ['another project is not ours', runHook(hook, dir, writeOf(join(dir, '..', 'elsewhere', 'x.cpp'), 'void x (S& s) { switch (s.mode) {} }\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('dispatch-once', main));

package/packs/base/hooks/file-size-guard.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// PreToolUse (Write|Edit|MultiEdit|NotebookEdit|Bash): no source file grows past the line limit, by any route
+// (a tool, or the shell's >, >>, tee, sed -i, cp, mv, a heredoc; lib/writes.mjs).
+// A PostToolUse warning comes too late (the file has already grown and the extraction is rework),
+// so this refuses the edit before it lands. Shrinking or keeping an already-long file is allowed,
+// so splitting a big file is never blocked. Limit: layout.maxFileLines, default 300.
+// `--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 { checkoutRoot, claudeRoot } from './lib/project.mjs';
+import { readLayout } from './lib/layout.mjs';
+import { verdicts } from './lib/selftest.mjs';
+import { isContent } from './lib/content.mjs';
+import { asHook, isMain } from './lib/hook-log.mjs';
+
+const ROOT = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+// Code, scripts, shaders and CMake files (Stellix's source rule counted scripts and CMake too); docs and data are not code.
+const SOURCE = new Set(['.c', '.cc', '.cpp', '.cxx', '.h', '.hh', '.hpp', '.mm', '.m', '.inc', '.inl', '.ipp', '.tpp', '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.py', '.wgsl', '.metal', '.hlsl', '.glsl', '.vert', '.frag', '.sh', '.bash', '.cmake']);
+const isSource = (rel) => SOURCE.has(extname(rel)) || /(^|\/)CMakeLists\.txt$/.test(rel);
+const EXEMPT = ['**/*.generated.*', '**/generated/**', 'build/**', '_deps/**'];
+
+const lines = (text) => (text === '' ? 0 : text.split('\n').length - (text.endsWith('\n') ? 1 : 0));
+
+export function verdict(rel, before, after, limit) {
+  if (!isSource(rel) || matchesAny(rel, EXEMPT) || isContent(rel)) return null;
+  const n = lines(after);
+  if (n <= limit || n <= lines(before)) return null;
+  return `BLOCKED by file-size-guard: ${rel} would be ${n} lines (limit ${limit}).\n` +
+    'Split it before adding more: move a cohesive part (a class, a group of pure functions, a table) into its own file in the same folder, then make this edit.\n';
+}
+
+function main(text) {
+  let payload;
+  try { payload = JSON.parse(text); } catch { return 0; }
+  for (const w of writesOf(payload)) {
+    if (w.after === null || relative(ROOT, w.path).startsWith('..')) continue;
+    const rel = relative(checkoutRoot(w.path), w.path);
+    const msg = verdict(rel, w.before, w.after, readLayout(claudeRoot(w.path)).maxFileLines ?? 300);
+    if (msg) { process.stderr.write(msg); return 2; }
+  }
+  return 0;
+}
+
+function selftest() {
+  const big = 'x\n'.repeat(300);
+  const cases = [
+    ['grows past the limit', verdict('src/core/Svf.cpp', big, `${big}y\n`, 300) !== null],
+    ['at the limit is fine', verdict('src/core/Svf.cpp', '', big, 300) === null],
+    ['shrinking a long file is allowed', verdict('src/core/Old.cpp', 'x\n'.repeat(500), 'x\n'.repeat(400), 300) === null],
+    ['docs are not source', verdict('docs/spec.md', '', 'x\n'.repeat(900), 300) === null],
+    ['generated code is exempt', verdict('src/gen/Tables.generated.h', '', 'x\n'.repeat(900), 300) === null],
+    ['a shell script is code', verdict('tools/plants.sh', '', 'x\n'.repeat(301), 300) !== null],
+    ['a CMakeLists.txt is code', verdict('lib/app/CMakeLists.txt', '', 'x\n'.repeat(301), 300) !== null],
+  ];
+  return verdicts('file-size-guard', 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('file-size-guard', main));

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

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// PreToolUse (Write|Edit|MultiEdit|NotebookEdit|Bash): a NEW source file may only be created inside a layout folder,
+// by any route that creates a file: the Write tool, or the shell (>, >>, tee, cp, mv, touch, a heredoc into a file;
+// lib/writes.mjs). An Edit, MultiEdit, NotebookEdit or sed -i never creates a file, so it is never judged here.
+// The layout lives in .claude/layout.json and is summarised in CLAUDE.md; this makes it structural.
+// Existing files can always be edited; moving them is a separate, deliberate job. `--selftest` proves it.
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { checkoutRoot, claudeRoot } from './lib/project.mjs';
+import { codeFolders, readLayout } from './lib/layout.mjs';
+import { bashOf, editOf, runHook, scratchProject, verdicts, writeOf } from './lib/selftest.mjs';
+import { judgeEvent } from './lib/writes.mjs';
+import { asHook, isMain } from './lib/hook-log.mjs';
+
+const ROOT = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+const SOURCE = /\.(c|cc|cpp|cxx|h|hh|hpp|mm|m|wgsl|metal|glsl|hlsl|slang)$/i;
+
+// What is source: layout.json "sourceFiles" (a regex the configuration writes, e.g. full-stack's TypeScript; KWB-37), else SOURCE.
+export const isSource = (file) => { const re = readLayout(claudeRoot(file)).sourceFiles; return (re ? new RegExp(re, 'i') : SOURCE).test(file); };
+
+const main = (text) => judgeEvent(text, {
+  name: 'folder-law',
+  write: (w) => (w.op === 'delete' || w.op === 'edit' || existsSync(w.path) || !isSource(w.path) ? null : judge(w.path)),
+});
+
+function judge(file) {
+  if (relative(ROOT, file).startsWith('..')) return null;
+  const root = checkoutRoot(file);
+  const rel = relative(root, file).replace(/\\/g, '/');
+  if (rel.startsWith('..')) return null;
+
+  const layout = readLayout(claudeRoot(file));
+  const folders = codeFolders(layout);
+  if (folders.length === 0) return null;
+  if (folders.some((f) => rel.startsWith(`${f}/`))) {
+    // Inside src/, the file must be in one of the named subfolders, not loose in src/ itself.
+    return null;
+  }
+
+  const list = Object.values(layout.folders)
+    .filter((f) => folders.includes(f.path))
+    .map((f) => `  ${f.path}/  ${f.purpose}`)
+    .join('\n');
+  return `BLOCKED by folder-law: ${rel} is outside the project layout.\nNew source files go in one of:\n${list}\n` +
+    'If none fits, ask the user; a new folder is added to .claude/layout.json, then `npx --no-install @thedecipherist/claude-packs update`.\n';
+}
+
+function selftest() {
+  const hook = fileURLToPath(import.meta.url);
+  const dir = scratchProject({ 'stray/Old.cpp': '// old\n', 'x.txt': 'int x;\n' }, { folders: { core: { path: 'src/core', purpose: 'core code' }, docs: { path: 'docs', purpose: 'docs' } }, concepts: {} });
+  const w = (file) => runHook(hook, dir, writeOf(join(dir, file)));
+  const sh = (cmd) => runHook(hook, dir, bashOf(cmd, dir));
+  const ts = scratchProject({}, { folders: { api: { path: 'api/src', purpose: 'the API' } }, concepts: {}, sourceFiles: '\\.(ts|tsx)$' });
+  return verdicts('folder-law', [
+    ['TypeScript is not source where the layout does not say so', w('stray/x.ts'), 0],
+    ['a layout whose sourceFiles name TypeScript: a new .ts outside its folders (KWB-37)', runHook(hook, ts, writeOf(join(ts, 'stray/x.ts'))), 2],
+    ['and inside them', runHook(hook, ts, writeOf(join(ts, 'api/src/x.ts'))), 0],
+    ['a new file in a layout folder', w('src/core/Svf.cpp'), 0],
+    ['a new file outside the layout', w('stray/New.cpp'), 2],
+    ['a new file loose in src/', w('src/Loose.cpp'), 2],
+    ['an existing file outside the layout', w('stray/Old.cpp'), 0],
+    ['an edit is never a new file', runHook(hook, dir, editOf(join(dir, 'stray/New.cpp'))), 0],
+    ['a doc is not source', w('stray/notes.md'), 0],
+    ['another project is not ours', runHook(hook, dir, writeOf(join(dirname(dir), 'elsewhere/x.cpp'))), 0],
+    ['a heredoc into a new file outside the layout', sh("cat > stray/B.cpp <<'EOF'\nint b;\nEOF"), 2],
+    ['a copy into a layout folder', sh('cp x.txt src/core/C.cpp'), 0],
+    ['a move outside the layout', sh('mv x.txt stray/D.cpp'), 2],
+    ['words about a file are no write', sh("echo 'cat > stray/E.cpp'"), 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('folder-law', main));