@thedecipherist/claude-packs 0.0.0-stage → 1.1.0

package/packs/base/hooks/lib/turn.mjs

@@ -0,0 +1,86 @@
+// turn: what the session did since the user's last prompt, read from the session's transcript (a JSONL file: one entry
+// per line; an assistant entry's content holds text and tool_use blocks, a user entry's holds the prompt or tool results).
+//   lastTurn(path) -> { text, uses: [{ name, input, cwd }] }   uses: every tool call of the turn that was not refused
+//   writesOfTurn(turn) -> [{ path, text, tool }]                  every file a call wrote and the text it put there
+//       (Write's content, Edit's and MultiEdit's new strings, NotebookEdit's source, the shell's known content; null
+//       when it cannot be known, e.g. a sed -i), by the shared write reader for the shell.
+// A prompt starts a turn; tool results, hook feedback, task notifications and the system's own lines do not, so a turn
+// sent back by a Stop hook is judged again with everything it wrote before.
+import { closeSync, fstatSync, openSync, readSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { shellWrites } from './shell-writes.mjs';
+
+const NOT_A_PROMPT = /^\s*(?:<|\[|Stop hook feedback|SubagentStop hook feedback|making-check|Caveat:|This session is being continued)/;
+
+function promptText(e) {
+  if (e.type !== 'user' || e.isMeta || e.isSidechain) return null;
+  const c = e.message?.content;
+  if (typeof c === 'string') return c;
+  if (!Array.isArray(c) || c.some((b) => b?.type === 'tool_result')) return null;
+  const t = c.filter((b) => b?.type === 'text').map((b) => b.text ?? '').join('\n');
+  return t || null;
+}
+
+// The transcript's last entries, read from its end: the last TAIL bytes, doubled until they hold the turn's prompt (KWB-24: a
+// long session's transcript is hundreds of MB, and reading all of it at every Stop took seconds). -> { entries, start }
+const TAIL = 1 << 20;
+function tailEntries(path) {
+  let fd;
+  try { fd = openSync(path, 'r'); } catch { return { entries: [], start: 0 }; }
+  try {
+    const size = fstatSync(fd).size;
+    for (let want = TAIL; ; want *= 4) {
+      const from = Math.max(0, size - want);
+      const buf = Buffer.alloc(size - from);
+      readSync(fd, buf, 0, buf.length, from);
+      const lines = buf.toString('utf8').split('\n');
+      if (from > 0) lines.shift(); // a line cut by the start of the window
+      const entries = [];
+      for (const l of lines) { if (!l.trim()) continue; try { entries.push(JSON.parse(l)); } catch { /* a torn last line */ } }
+      for (let i = entries.length - 1; i >= 0; i -= 1) {
+        const t = promptText(entries[i]);
+        if (t !== null && !NOT_A_PROMPT.test(t)) return { entries, start: i + 1 };
+      }
+      if (from === 0) return { entries, start: 0 };
+    }
+  } finally {
+    closeSync(fd);
+  }
+}
+
+export function lastTurn(path) {
+  const { entries, start } = tailEntries(path);
+  const refused = new Set();
+  const uses = [];
+  const text = [];
+  for (const e of entries.slice(start)) {
+    if (e.isSidechain) continue;
+    const content = Array.isArray(e.message?.content) ? e.message.content : [];
+    if (e.type === 'user') for (const b of content) if (b?.type === 'tool_result' && b.is_error) refused.add(b.tool_use_id);
+    if (e.type !== 'assistant') continue;
+    for (const b of content) {
+      if (b?.type === 'text' && b.text) text.push(b.text);
+      if (b?.type === 'tool_use') uses.push({ id: b.id, name: b.name, input: b.input ?? {}, cwd: e.cwd });
+    }
+  }
+  return { text: text.join('\n'), uses: uses.filter((u) => !refused.has(u.id)) };
+}
+
+// A landing ends a step. Compaction is no prompt, so one turn can hold a whole run, and its last step's making line says nothing of the steps before: the
+// MPX 500 was sent back for files written hours earlier, at a landing (KF-34). What a turn landed is over; only the writes after its last landing are judged.
+const LANDING = /(?:^|[;&|\n])\s*git\s+(?:-C\s+\S+\s+)?merge\s+(?:\S+\s+)*?--ff-only\b/;
+const sinceLanding = (uses) => uses.slice(uses.findLastIndex((u) => u.name === 'Bash' && LANDING.test(u.input.command ?? '')) + 1);
+
+export function writesOfTurn(turn, cwd = process.cwd()) {
+  const out = [];
+  for (const u of sinceLanding(turn.uses)) {
+    const i = u.input;
+    const at = (p) => resolve(u.cwd ?? cwd, p);
+    if (u.name === 'Write' && i.file_path) out.push({ path: at(i.file_path), text: i.content ?? '', tool: u.name });
+    else if (u.name === 'Edit' && i.file_path) out.push({ path: at(i.file_path), text: i.new_string ?? '', tool: u.name });
+    else if (u.name === 'MultiEdit' && i.file_path) out.push({ path: at(i.file_path), text: (i.edits ?? []).map((e) => e.new_string ?? '').join('\n'), tool: u.name });
+    else if (u.name === 'NotebookEdit' && i.notebook_path) out.push({ path: at(i.notebook_path), text: i.new_source ?? '', tool: u.name });
+    else if (u.name === 'Bash') for (const w of shellWrites(i.command ?? '', u.cwd ?? cwd)) if (w.op !== 'delete') out.push({ path: w.path, text: w.content ?? (w.sed ? w.sed.scripts.join('\n') : null), tool: 'Bash' });
+  }
+  return out;
+}

package/packs/base/hooks/lib/unread-writes.mjs

@@ -0,0 +1,24 @@
+// unread-writes: an inline program can write a source file in a way no hook can read, and every content law lets an unknown text through.
+// The MPX 500's edits through a local helper passed no law, and nothing said so (KF-40). When a command passed, this names what it wrote
+// unread, where the author sees it, so a pass is never taken for a judgement.
+//   unreadWrites(ev, root) -> '' | JSON for the hook's stdout
+import { extname, relative } from 'node:path';
+import { languageOf } from './languages.mjs';
+import { insideProject } from './project.mjs';
+import { writesOf } from './writes.mjs';
+
+const INLINE = /\b(?:python[\d.]*|pypy3?|node|nodejs|bun|perl|ruby)\b[^\n|;&]*(?:\s-[A-Za-z]*[ceE]\s|\s-\s|<<)/;
+const CONTENT_OPS = new Set(['write', 'edit', 'append']);
+
+export function unreadWrites(ev, root) {
+  const command = ev.tool_input?.command;
+  if (ev.tool_name !== 'Bash' || ev.hook_event_name !== 'PreToolUse' || !INLINE.test(command ?? '')) return '';
+  const cwd = ev.cwd ?? root;
+  const unread = writesOf(ev, cwd).filter((w) => w.after === null && CONTENT_OPS.has(w.op) && languageOf(extname(w.path)) && insideProject(w.path, cwd)).map((w) => relative(cwd, w.path));
+  if (!unread.length) return '';
+  const files = unread.join(', ');
+  return JSON.stringify({
+    systemMessage: `not judged: this command writes ${files} in a way the hooks could not read`,
+    hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: `The hooks could not read what this command writes to ${files}, so no content law judged it. Use the Edit or Write tool for source files, where every law applies.` },
+  });
+}

package/packs/base/hooks/lib/writes.mjs

@@ -0,0 +1,71 @@
+// writes: every file one tool call writes, whichever tool it is (WB-69: close the route, not just the
+// brief). A guard that refuses a write judges these, so Write, Edit, MultiEdit, NotebookEdit and the
+// shell (>, >>, tee, sed -i, cp, mv, a heredoc into a file, an inline program's own writes (KWB-8), ...) are one route each into the same check.
+//   writesOf(payload, base) -> [{ path, op, before, after }]
+//     path: absolute; op: write, edit, append, copy, move, link, truncate, touch, delete (see shell-writes.mjs)
+//     before: the file's text now ('' when it does not exist); after: its text once the call has run, or null
+//     when that cannot be known (a perl -i, an inline program's write of text it builds). A guard that judges paths needs only path;
+//     one that judges content judges after, and lets an unknown after through.
+import { relative, resolve } from 'node:path';
+import { checkoutRoot, commandLeavesProject, insideProject } from './project.mjs';
+import { computeEdit } from './apply-edit.mjs';
+import { afterText, readText, shellWrites } from './shell-writes.mjs';
+
+export const WRITE_TOOLS = ['Write', 'Edit', 'MultiEdit', 'NotebookEdit', 'Bash'];
+
+export function writesOf(payload, base = process.cwd()) {
+  const input = payload.tool_input ?? {};
+  const tool = payload.tool_name;
+  if (tool === 'Write' || tool === 'Edit' || tool === 'MultiEdit') {
+    if (!input.file_path) return [];
+    const path = resolve(base, input.file_path);
+    const r = computeEdit(tool, { ...input, file_path: path });
+    return [{ path, op: tool === 'Write' ? 'write' : 'edit', before: r?.before ?? readText(path) ?? '', after: r?.after ?? null }];
+  }
+  if (tool === 'NotebookEdit') {
+    if (!input.notebook_path) return [];
+    const path = resolve(base, input.notebook_path);
+    const before = readText(path) ?? '';
+    const src = input.new_source ?? '';
+    const after = input.edit_mode === 'delete' ? before : `${before}${before && !before.endsWith('\n') ? '\n' : ''}${src}${src.endsWith('\n') ? '' : '\n'}`;
+    return [{ path, op: 'edit', before, after }];
+  }
+  if (tool === 'Bash') {
+    // several writes to one file in one command (`sed -i A f && sed -i B f`) are one change: each reads what the one before it left,
+    // and the file is judged once, from what it was to what the last one leaves (KWB-13: each was read against the file on disk, and
+    // the two different results were judged as two copies of the file)
+    const byPath = new Map();
+    for (const w of shellWrites(input.command ?? '', payload.cwd ?? base)) {
+      const prev = byPath.get(w.path);
+      const r = prev ? (prev.after === null ? { after: null } : afterText(w, prev.after)) : afterText(w);
+      byPath.set(w.path, prev ? { ...prev, op: w.op === 'delete' ? 'delete' : prev.op, after: r.after } : { path: w.path, op: w.op, ...r });
+    }
+    return [...byPath.values()];
+  }
+  return [];
+}
+
+export function readPayload(text) {
+  try { return JSON.parse(text); } catch { return null; }
+}
+
+// One guard's frame (0.10.0): read the event, judge its shell command (`command(text, cwd)`, unless it leaves the project) and
+// every write inside the project (`write(w, rel)`, rel from the file's own checkout); the first finding refuses, exit 2.
+// A finding that starts with "BLOCKED" is written as it is, any other as "BLOCKED by <name>: <finding>".
+export function judgeEvent(text, { name, command = null, write = null }) {
+  const payload = readPayload(text);
+  if (!payload) return 0;
+  const cwd = payload.cwd ?? process.cwd();
+  const refuse = (msg) => { process.stderr.write(msg.startsWith('BLOCKED') ? msg : `BLOCKED by ${name}: ${msg}\n`); return 2; };
+  const cmd = payload.tool_input?.command ?? '';
+  if (command && payload.tool_name === 'Bash' && !commandLeavesProject(cmd)) {
+    const msg = command(cmd, cwd);
+    if (msg) return refuse(msg);
+  }
+  if (write) for (const w of writesOf(payload, cwd)) {
+    if (!insideProject(w.path, cwd)) continue;
+    const msg = write(w, relative(checkoutRoot(w.path), w.path));
+    if (msg) return refuse(msg);
+  }
+  return 0;
+}

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

@@ -0,0 +1,248 @@
+#!/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, claudeRoot, 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;
+const NOT_CONCEPTS = new Set(['none', 'no', '-', 'n/a', 'one', 'many', 'ids']);
+// 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);
+// each identifier's parts, and the identifier whole: a concept named editPage is the word editpage, not the words edit and page (KF-19, KF-39)
+const partsOf = (text) => new Set((text.match(/[A-Za-z_][A-Za-z0-9_]*/g) ?? []).flatMap((w) => [...splitName(w), w.toLowerCase()]));
+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, ' '); }
+  // the list runs to `reuse:` or the line's end, and a shape word after a concept ("editKnob, many") is what the rule asks for (KF-24)
+  for (const m of flat.matchAll(/\bconcepts?\s*:\s*(.*?)(?=\breuse\s*:|\||$)/gim)) {
+    for (const item of m[1].split(/[,;]/)) {
+      const w = item.trim().split(/\s+/)[0]?.toLowerCase().replace(/[^a-z0-9_-]/g, '');
+      if (w && !NOT_CONCEPTS.has(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. The tools' writes passed once-only itself when it is installed; running its detector again on them at
+  // every Stop cost over the kit's own 500 ms line (KF-33). The shell's writes stay: much of what they write is unknown at write time.
+  const atWrite = existsSync(join(claudeRoot(join(cwd, 'x')), '.claude/hooks/once-only.mjs'));
+  const sources = [...new Set(judged.filter((w) => isSource(w.path) && existsSync(w.path) && !(atWrite && w.tool !== 'Bash')).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));
+}