@thedecipherist/claude-packs 0.0.0-stage → 1.0.0

package/packs/base/hooks/making-check.mjs

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+// making-check: a turn ends only when what it wrote is what it said it was making (claude-packs 0.9.0 item 7; KWB-1).
+// A Stop hook. It reads the turn from the transcript (lib/turn.mjs: every file written by Write, Edit, MultiEdit,
+// NotebookEdit or the shell, refused calls left out) and sends the turn back (exit 2) naming what is missing when:
+//   - the turn wrote code or docs that touch a concept of design/shape.json and build.md's In progress entry for this
+//     step has no `making:` line, or the line does not name that concept;
+//   - the making line names a concept that has no row in design/shape.json, or the turn wrote source with no manifest;
+//   - a source file the turn wrote repeats code the repo already has (once-only's detector, lib/dup.mjs, on the lines
+//     the working tree adds against HEAD);
+//   - THE OVERRIDE RULE: the turn's text says it did something other than what it was told, and cites no law. Told X
+//     and a law file (design/shape.json, docs/*-spec.md, docs/laws.md) says Y: do Y, log the brief as the bug, cite the
+//     line. No law covers it: ask; overnight, decide and write it under Decisions, and cite that entry. There is no
+//     third case where Claude's own judgement overrides an instruction.
+// After three send-backs with the same findings the turn ends and the findings go to the user (no endless loop).
+//   node making-check.mjs --selftest
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, relative, resolve } from 'node:path';
+import { copyGlobs, excludeGlobs, FIX, 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, insideProject, ROOT } from './lib/project.mjs';
+import { readShape } from './lib/shape.mjs';
+import { lastTurn, writesOfTurn } from './lib/turn.mjs';
+import { asHook, isMain } from './lib/hook-log.mjs';
+
+const MAX_SENDS = 3;
+// the folder kinds a layout marks as code; a layout that marks none: any source file outside its docs folders
+const CODE_KINDS = new Set(['code', 'engine', 'ui', 'params', 'tests']);
+const NOT_CODE = ['build/**', 'inbox/**', 'docs/**', '**/*.md', '**/*.txt', '**/*.json'];
+function isCode(relPath, layout) {
+  if (!(isSource(relPath) || /\.ipynb$/i.test(relPath)) || matchesAny(relPath, NOT_CODE)) return false;
+  const folders = Object.values(layout?.folders ?? {});
+  const docs = folders.filter((f) => f.kind === 'docs' || /^docs?\b/i.test(f.purpose ?? '')).map((f) => `${f.path}/**`);
+  if (matchesAny(relPath, docs)) return false;
+  const code = folders.filter((f) => CODE_KINDS.has(f.kind)).map((f) => `${f.path}/**`);
+  return !code.length || matchesAny(relPath, code);
+}
+const PLAN = ['build.md', '**/build.md', 'bugs.md', 'workflow-bugs.md', 'CHANGELOG.md', 'design/shape.json', '.claude/**'];
+const LAW = /(?:design\/)?shape\.json|(?:docs\/)?[\w.-]*-spec\.md|(?:docs\/)?laws\.md/g;
+const LOCATOR = /:\d+\b|#[\w-]+|\{#[\w-]+\}|§\s*\d[\d.]*|\bL-?\d+\b|\b(?:section|line|row|rule|law)\s+["'`]?[\w.-]+|"[\w -]{2,40}"\s+row/i;
+// The turn says it did something other than it was told.
+const OVERRIDE = [
+  /\b(?:instead of|rather than|not)\s+(?:what\s+)?(?:the\s+)?(?:brief|prompt|order|instruction|request|work ?order|lead|you)\s+(?:asked|said|told|wanted|named|specified)/i,
+  /\b(?:the\s+)?(?:brief|prompt|order|instruction|request|work ?order|lead)\s+(?:said|asked|told|wanted|named|specified)\b[^.\n]{0,160}\b(?:but|however|instead)\b/i,
+  /\byou\s+(?:said|asked|told me|wanted)\b[^.\n]{0,160}\b(?:but I|however I|instead I|I instead)\b(?!['’]d\b|\s+(?:would|think|recommend|suggest|expect|believe)\b)/i, // a view is not an action (KWB-47)
+  /\bI\s+(?:deviated|departed|diverged)\s+from\b/i,
+  /\b(?:overrode|overriding|override[sd]?)\s+(?:the\s+|your\s+)?(?:brief|instruction|order|prompt|request|work ?order)/i,
+  /\bcontrary\s+to\s+(?:the\s+|your\s+)?(?:brief|instruction|order|prompt|request|work ?order)/i,
+  /\b(?:did\s+not|didn't)\s+(?:follow|do\s+what)\s+(?:the\s+|your\s+)?(?:brief|instruction|order|prompt|request|work ?order|you)/i,
+];
+
+const splitName = (name) => name.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2').replace(/([A-Za-z])(\d)/g, '$1 $2').toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+const partsOf = (text) => new Set((text.match(/[A-Za-z_][A-Za-z0-9_]*/g) ?? []).flatMap(splitName));
+const rowOf = (c) => c?.row ?? c ?? {};
+const wordsOf = (name, c) => [name.toLowerCase(), ...(c?.words ?? rowOf(c).words ?? []).map((w) => String(w).toLowerCase())];
+
+// The concepts a text touches: a word of the concept as a word or a part of an identifier, a code pattern, a per-instance
+// array, the generator.
+export function conceptsIn(text, shape) {
+  const parts = partsOf(text);
+  const out = new Set();
+  for (const [name, c] of Object.entries(shape?.concepts ?? {})) {
+    const row = rowOf(c);
+    const gen = String(row.generator ?? '').match(/^\s*([A-Za-z_]\w*)\s*\(/)?.[1];
+    const hit = wordsOf(name, c).some((w) => parts.has(w))
+      || (row.patterns ?? []).some((p) => { try { return new RegExp(p).test(text); } catch { return false; } })
+      || (row.arrays ?? []).some((a) => new RegExp(`\\b${a}\\b`).test(text))
+      || (gen && new RegExp(`\\b${gen}\\s*\\(`).test(text));
+    if (hit) out.add(name);
+  }
+  return out;
+}
+
+// The concepts listed after "concepts:" on a making line that the manifest does not know.
+export function unknownConcepts(making, shape) {
+  const known = new Set(Object.entries(shape?.concepts ?? {}).flatMap(([n, c]) => wordsOf(n, c)));
+  const out = [];
+  // bracketed text goes first, nested brackets too, so a ";" inside a shape ("slot (many, 4; slotId(i, field))") does not end the list (KWB-17)
+  let flat = making;
+  for (let prev; prev !== flat;) { prev = flat; flat = flat.replace(/\([^()]*\)/g, ' '); }
+  for (const m of flat.matchAll(/\bconcepts?\s*:\s*([^;|]+)/gi)) {
+    for (const item of m[1].split(',')) {
+      const w = item.trim().split(/\s+/)[0]?.toLowerCase().replace(/[^a-z0-9_-]/g, '');
+      if (w && !['none', 'no', '-', 'n/a'].includes(w) && !known.has(w)) out.push(w);
+    }
+  }
+  return out;
+}
+
+// The checkout's branch from its HEAD file (a worktree's .git file names its git dir): no git process (KWB-24: on a loaded
+// machine each one took half a second)
+function branchOf(root) {
+  try {
+    let dir = join(root, '.git');
+    const dotGit = readFileSync(dir, 'utf8').match(/^gitdir:\s*(.+)$/m); // a worktree; a folder throws and is read below
+    if (dotGit) dir = resolve(root, dotGit[1].trim());
+    return headBranch(dir);
+  } catch { return headBranch(join(root, '.git')); }
+}
+const headBranch = (gitDir) => { try { return readFileSync(join(gitDir, 'HEAD'), 'utf8').match(/^ref:\s*refs\/heads\/(.+)$/m)?.[1].trim() ?? 'HEAD'; } catch { return ''; } };
+
+// The making lines of build.md's In progress section: those on this branch's entry, else every one there.
+export function makingLines(root) {
+  const file = [join(root, 'build.md'), join(ROOT, 'build.md')].find((f) => existsSync(f));
+  if (!file) return [];
+  const text = readFileSync(file, 'utf8');
+  const at = text.search(/^##\s+In progress\b/im);
+  if (at < 0) return [];
+  const rest = text.slice(at).split('\n');
+  const section = [];
+  for (const l of rest.slice(1)) { if (/^##\s/.test(l)) break; section.push(l); }
+  const lines = section.filter((l) => /\bmaking:/i.test(l)).map((l) => l.slice(l.search(/\bmaking:/i)));
+  const branch = branchOf(root);
+  const mine = branch && branch !== 'HEAD' ? section.filter((l) => /\bmaking:/i.test(l) && (l.includes(branch) || l.includes(branch.split('/').pop()))).map((l) => l.slice(l.search(/\bmaking:/i))) : [];
+  return mine.length ? mine : lines;
+}
+
+// Added line ranges of each file against HEAD (the whole file when it is new or there is no git): two git processes for all
+// the files of a checkout, not two per file. -> Map(file -> [[lo, hi]])
+function addedRanges(root, files) {
+  const rels = files.map((f) => relative(root, f));
+  const out = new Map();
+  const tracked = new Set((spawnSync('git', ['-C', root, 'ls-files', '--', ...rels], { encoding: 'utf8' }).stdout ?? '').split('\n').filter(Boolean));
+  const diff = tracked.size ? spawnSync('git', ['-C', root, 'diff', '--relative', '-U0', 'HEAD', '--', ...rels.filter((r) => tracked.has(r))], { encoding: 'utf8' }).stdout ?? '' : '';
+  let cur = null;
+  for (const line of diff.split('\n')) {
+    const f = line.match(/^\+\+\+ b\/(.+)$/);
+    if (f) { cur = f[1]; continue; }
+    const h = line.match(/^@@ -\S+ \+(\d+)(?:,(\d+))? @@/);
+    if (h && cur) { const r = [Number(h[1]), Number(h[1]) + Number(h[2] ?? 1) - 1]; if (r[1] >= r[0]) out.set(cur, [...(out.get(cur) ?? []), r]); }
+  }
+  const lines = (f) => { try { return readFileSync(f, 'utf8').split('\n').length; } catch { return 0; } };
+  return new Map(files.map((f, i) => [f, tracked.has(rels[i]) ? out.get(rels[i]) ?? [] : lines(f) ? [[1, lines(f)]] : []]));
+}
+
+export function check(event, cwd = event.cwd ?? process.cwd()) {
+  const path = event.hook_event_name === 'SubagentStop' ? event.agent_transcript_path ?? event.transcript_path : event.transcript_path;
+  const turn = lastTurn(path ?? '');
+  const text = `${turn.text}\n${event.last_assistant_message ?? ''}`;
+  const writes = writesOfTurn(turn, cwd).filter((w) => insideProject(w.path));
+  const problems = [];
+  const rel = (p) => relative(checkoutRoot(p), p).replace(/\\/g, '/');
+  // Each write is judged against its own checkout (a worktree's own build.md, manifest and layout), never the session's folder:
+  // a lead in the main checkout writing in a worktree has its making line in that worktree's build.md (Stellix WB-86).
+  const byRoot = new Map();
+  for (const w of writes) { const r = checkoutRoot(w.path); if (!byRoot.has(r)) byRoot.set(r, []); byRoot.get(r).push(w); }
+  if (!byRoot.size) byRoot.set(checkoutRoot(join(cwd, 'x')), []);
+  const judged = [];
+  let shape = null, root = null, layout = null;
+  for (const [r, ws] of byRoot) {
+    const lay = readLayout(r);
+    const sh = readShape(r) ?? readShape(ROOT);
+    const mine = ws.filter((w) => !matchesAny(rel(w.path), [...PLAN, ...excludeGlobs(lay, sh)]));
+    // once-only (below) judges the checkout the source went to: the first checkout that holds a judged source
+    if (!root || (mine.some((w) => isSource(w.path)) && !judged.some((w) => isSource(w.path)))) { root = r; layout = lay; shape = sh; }
+    judged.push(...mine);
+
+    // 1. the concepts written, the making line, the manifest
+    if (!sh && mine.some((w) => isSource(w.path))) {
+      problems.push(`no design/shape.json, and this turn wrote source (${[...new Set(mine.filter((w) => isSource(w.path)).map((w) => rel(w.path)))].slice(0, 4).join(', ')}): write the manifest first, every concept one or many, its generator, its selectors`);
+    }
+    if (sh && !sh.error && mine.length) {
+      const written = new Map();
+      // only code is judged for its concepts: a note, a brief, a doc or a log names concepts in words ("Status line"), and that is no
+      // undeclared use (KWB-19)
+      for (const w of mine) if (isCode(rel(w.path), lay)) for (const c of conceptsIn(w.text ?? '', sh)) if (!written.has(c)) written.set(c, rel(w.path));
+      const making = makingLines(r).join('\n');
+      const wroteSource = mine.filter((w) => isSource(w.path)).map((w) => rel(w.path));
+      // a turn that writes source answers "what are you making" first, even before the manifest knows the concept
+      if (!making && (written.size || wroteSource.length)) problems.push(`build.md's In progress entry for this step has no "making:" line, and this turn wrote ${written.size ? [...written].map(([c, f]) => `${c} (${f})`).join(', ') : [...new Set(wroteSource)].slice(0, 4).join(', ')}: write the line (what you are making; concepts: each with its shape; reuse: the one function, where it lives)`);
+      else if (making) {
+        const named = conceptsIn(making, sh);
+        for (const [c, f] of written) if (!named.has(c)) problems.push(`the making line does not name ${c}, which this turn wrote (${f}): add it with its shape from design/shape.json, or take the write back`);
+        for (const u of unknownConcepts(making, sh)) problems.push(`the making line names "${u}", which has no row in design/shape.json: add the row first (one or many, its generator, its selectors)`);
+      }
+    }
+  }
+
+  // 2. once-only on the source the turn wrote
+  const sources = [...new Set(judged.filter((w) => isSource(w.path) && existsSync(w.path)).map((w) => w.path))]
+    .filter((p) => !matchesAny(rel(p), copyGlobs(layout)) && !isGenerated(readFileSync(p, 'utf8')));
+  if (sources.length) {
+    // once-only's index finds the candidates, jscpd confirms on those files alone (lib/dup-index.mjs; KWB-24: no whole-repo scan)
+    const added = addedRanges(root, sources);
+    const writes = sources.map((p) => ({ path: p, after: readFileSync(p, 'utf8'), ranges: added.get(p) })).filter((w) => w.ranges.length);
+    const r = writes.length ? judgeWrites(root, writes, { layout, shape }) : { clones: [] };
+    if (r.error) problems.push(`once-only could not judge this turn's writes: ${r.error}`);
+    const base = real(root);
+    const show = (s) => `${relative(base, s.file)}:${s.start}-${s.end}`;
+    const found = new Set();
+    for (const c of r.clones) found.add(`${show(c.at)} repeats ${show(c.other)} (${c.lines} lines)`);
+    if (found.size) problems.push(`this turn's writes did not pass once-only: ${[...found].slice(0, 5).join('; ')}. ${FIX}`);
+  }
+
+  // 3. the override rule
+  const claims = text.replace(/"[^"\n]*"|`[^`\n]*`/g, '""'); // a quotation reports words, it claims nothing (KWB-47)
+  const said = OVERRIDE.map((re) => claims.match(re)).find(Boolean);
+  if (said) {
+    const cites = text.split('\n').some((l) => [...l.matchAll(LAW)].some((m) => LOCATOR.test(l.slice(Math.max(0, m.index - 60), m.index + m[0].length + 60))));
+    const decided = /\bDecisions?\b/.test(text) && writes.some((w) => /decisions/i.test(w.path) || (existsSync(w.path) && /^#+\s*Decisions\b/im.test(readFileSync(w.path, 'utf8'))));
+    const logged = writes.some((w) => /(?:^|\/)(?:workflow-)?bugs\.md$/.test(w.path)) || /\b(?:K?WB|B)-\d+\b/.test(text);
+    const quote = `"${said[0].slice(0, 120)}"`;
+    if (!cites && !decided) problems.push(`the turn says it did something other than it was told (${quote}) and cites no law. Told X and a law file says Y: do Y, log the brief as the bug, cite the line (design/shape.json "<concept>", docs/<name>-spec.md {#anchor}, docs/laws.md L<n>). No law covers it: ask; overnight, decide and write it under Decisions and cite that entry. Claude's own judgement never overrides an instruction`);
+    else if (cites && !decided && !logged) problems.push(`the turn overrode what it was told by a law (${quote}) but did not log the brief as the bug: log it in bugs.md or workflow-bugs.md and name its number`);
+  }
+  return problems;
+}
+
+// Three send-backs with the same findings end the turn: the findings go to the user instead of looping.
+function guard(event, problems) {
+  const file = join(process.env.TMPDIR ?? tmpdir(), `making-check-${String(event.session_id ?? 'session').replace(/[^\w-]/g, '')}.json`);
+  let st = {};
+  try { st = JSON.parse(readFileSync(file, 'utf8')); } catch { /* first */ }
+  const hash = createHash('sha1').update(problems.join('\n')).digest('hex');
+  // consecutive stops with the same findings count whether or not the host marks them as a continuation (stop_hook_active):
+  // a host that delivers each send-back as a new turn reset the count to 1 every time, and the limit was never reached (KWB-7)
+  const count = problems.length && st.hash === hash ? (st.count ?? 0) + 1 : problems.length ? 1 : 0;
+  try { writeFileSync(file, JSON.stringify({ hash, count })); } catch { /* the check still runs */ }
+  return count > MAX_SENDS;
+}
+
+async function main(text) {
+  let event;
+  try { event = JSON.parse(text); } catch { return 0; }
+  if (event.hook_event_name && !['Stop', 'SubagentStop'].includes(event.hook_event_name)) return 0;
+  const problems = check(event);
+  if (!problems.length) { guard(event, []); return 0; }
+  if (guard(event, problems)) {
+    process.stdout.write(JSON.stringify({ systemMessage: `making-check sent this turn back ${MAX_SENDS} times with the same findings; it ends here for you to decide:\n- ${problems.join('\n- ')}` }));
+    return 0;
+  }
+  process.stderr.write(`making-check sent this turn back:\n- ${problems.join('\n- ')}\n`);
+  return 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') ? await (await import('./lib/making-check-selftest.mjs')).selftest(import.meta.url) : await asHook('making-check', main));
+}

package/packs/base/hooks/making.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+// making: before anything is built, what is being made and the shape of every concept it touches (claude-packs 0.9.0
+// item 6; KWB-1). A UserPromptSubmit hook: the same short text goes in front of every prompt, under 80 words, exactly
+// The user's content: what are you making; each concept you touch and its shape from design/shape.json; a new concept gets its
+// row first; a brief naming an instance is wrong by definition; used more than once, one function, parameterized, and
+// where it lives. The answer is a `making:` line in the step's In progress entry in build.md (making-check reads it).
+// When the prompt itself names an instance of a many concept, one line more: "you named X: building for all <shape>, X
+// is the reproduction". Nothing else is added.
+//   node making.mjs --cost       the text's size per turn (doctor prints it)
+//   node making.mjs --selftest
+import { readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { checkoutRoot, ROOT } from './lib/project.mjs';
+import { scratchProject } from './lib/selftest.mjs';
+import { findInstanceLiterals, readShape } from './lib/shape.mjs';
+import { asHook, isMain } from './lib/hook-log.mjs';
+
+export const TEXT = "making: before the first write, answer in build.md's In progress entry for this step, one line: " +
+  '`making: <what you are making>; concepts: <each you touch, its shape from design/shape.json>; reuse: <function, where it lives>`. ' +
+  'A new concept gets its shape.json row first. A brief naming an instance is wrong by definition. Used more than once? ' +
+  'One function, parameterized; cite where it lives.';
+export const MAX_WORDS = 80;
+
+export const words = (t) => t.split(/\s+/).filter(Boolean).length;
+
+// A token estimate, stated as one: word pieces of up to 6 letters, each digit run of up to 3 and each mark one token
+// each (English in a BPE tokenizer runs about 1.3 tokens a word); never the model's own count.
+export function tokens(t) {
+  let n = 0;
+  for (const p of t.match(/[A-Za-z]+|\d+|[^\sA-Za-z\d]/g) ?? []) n += /^[A-Za-z]/.test(p) ? Math.ceil(p.length / 6) : /^\d/.test(p) ? Math.ceil(p.length / 3) : 1;
+  return n;
+}
+
+const plural = (c, name) => (c?.plural instanceof Set && c.plural.size ? [...c.plural][0] : (c?.words ?? []).find((w) => w === `${name}s` || w === `${name}es`)) ?? `${name}s`;
+
+// The echo line, or '' when the prompt names no instance of a many concept. One line, whatever the prompt holds.
+export function echo(prompt, shape) {
+  if (!shape || !prompt) return '';
+  const named = [];
+  const seen = new Set();
+  for (const f of findInstanceLiterals(prompt, 'prompt.md', shape)) {
+    const c = shape.concepts?.[f.concept];
+    if ((c?.shape ?? c?.row?.shape) !== 'many' || seen.has(f.concept) || f.instance === 'each') continue;
+    seen.add(f.concept);
+    const x = /^\d+$/.test(f.instance) ? `${f.concept} ${f.instance}` : `${f.instance} ${f.concept}`;
+    const n = c.count ?? c.row?.count;
+    named.push(`${x}: building for all ${plural(c, f.concept)} (many${n ? `, ${n}` : ''}), ${x} is the reproduction`);
+  }
+  return named.length ? `you named ${named.slice(0, 2).join('; ')}` : '';
+}
+
+export function inject(prompt, shape) {
+  const line = echo(prompt, shape);
+  return line && words(`${TEXT} ${line}`) <= MAX_WORDS ? `${TEXT}\n${line}` : line ? `${TEXT}\n${line.split('; ')[0]}` : TEXT;
+}
+
+export const cost = () => {
+  const one = `${TEXT}\nyou named slot 2: building for all slots (many, 4), slot 2 is the reproduction`;
+  return `making: ${words(TEXT)} words, about ${tokens(TEXT)} tokens added to every prompt (${words(one)} words, about ${tokens(one)} tokens when it echoes a named instance); ` +
+    'an estimate (word pieces of up to 6 letters, each mark one token), not the model\'s tokenizer';
+};
+
+function selftest() {
+  const dir = scratchProject({ 'design/shape.json': JSON.stringify({
+    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' } } },
+      mixer: { shape: 'one', id: 'mixer', words: ['mixer'] },
+    },
+    exclude: [],
+  }) });
+  const shape = readShape(dir);
+  rmSync(dir, { recursive: true, force: true });
+  const cases = [
+    ['the text is under 80 words', words(TEXT) < MAX_WORDS],
+    ['the text with one echo line is still under 80 words', words(inject('drive slot 2 louder', shape)) <= MAX_WORDS],
+    ['the text asks every item of the order', ['making:', 'concept', 'shape', 'design/shape.json', 'row first', 'brief naming an instance', 'wrong by definition', 'more than once', 'one function', 'parameterized', 'where it lives', 'In progress', 'build.md'].every((k) => TEXT.toLowerCase().includes(k.toLowerCase()))],
+    ['a prompt naming slot 2 gets the echo', inject('the PAD in slot 2 is too quiet, fix it', shape).endsWith('you named slot 2: building for all slots (many, 4), slot 2 is the reproduction')],
+    ['a prompt naming no instance gets the text alone', inject('make the reverb darker on every slot', shape) === TEXT],
+    ['an example line is not an echo', inject('seen in: slot 3, build it for all slots', shape) === TEXT],
+    ['a selector is not an echo', inject('the selectedSlot loses its state after a load', shape) === TEXT],
+    ['a one concept is never echoed as many', inject('the mixer 1 meter', shape).split('\n').length <= 2 && !inject('the mixer 1 meter', shape).includes('all mixers')],
+    ['no manifest: the text alone', inject('drive slot 2', null) === TEXT],
+    ['the cost is measured and stated as an estimate', /\d+ words, about \d+ tokens/.test(cost()) && cost().includes('estimate')],
+  ];
+  for (const [name, ok] of cases) if (!ok) console.error(`making selftest FAILED: ${name}`);
+  const bad = cases.filter(([, ok]) => !ok).length;
+  if (!bad) console.log(`making selftest: OK (${cases.length} cases)`);
+  return bad ? 1 : 0;
+}
+
+function main(text) {
+  let event = {};
+  try { event = JSON.parse(text || '{}'); } catch { /* the text still goes */ }
+  if (event.hook_event_name && event.hook_event_name !== 'UserPromptSubmit') return 0;
+  const root = event.cwd ? checkoutRoot(join(event.cwd, 'prompt')) : ROOT;
+  let shape = null;
+  try { shape = readShape(root) ?? readShape(ROOT); } catch { /* the text still goes */ }
+  process.stdout.write(`${inject(event.prompt ?? '', shape)}\n`);
+  return 0;
+}
+
+export const hook = main; // run-hooks.mjs calls it with the event's text (KWB-24)
+if (isMain(import.meta.url)) {
+  if (process.argv.includes('--cost')) { console.log(cost()); process.exit(0); }
+  process.exit(process.argv.includes('--selftest') ? selftest() : await asHook('making', main));
+}

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));