@thedecipherist/claude-packs 1.0.0 → 1.1.0

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

@@ -104,6 +104,9 @@ export function selftest(hookUrl) {
     ['a brief in a notes folder naming a concept (KWB-19)', turn([W('notes/brief.md', '# Brief: the mixer, every slot\n')]), 0],
     ['source using a concept the making line does not name (KWB-19)', turn([W('src/mix/level.cpp', mixerCode)]), 2],
     ['mixer code with a making line naming the mixer', turn([W('src/mix/level.cpp', mixerCode)], { making: 'making: the mixer level; concepts: mixer (one); reuse: none' }), 0],
+    ['what a turn landed is over (KF-34)', turn([W('src/mix/level.cpp', mixerCode), use('Bash', { command: 'git merge --ff-only work/s1' })]), 0],
+    ['a write after the landing is judged (KF-34)', turn([use('Bash', { command: 'git merge --ff-only work/s1' }), W('src/mix/level.cpp', mixerCode)]), 2],
+    ['the shape word the rule asks for is no concept (KF-24)', turn([W('src/mix/level.cpp', mixerCode)], { making: 'making: x; concepts: slot, many; mixer, one; reuse: none' }), 0],
   ];
   return verdicts('making-check', cases);
 }

package/packs/base/hooks/lib/near-copies.mjs

@@ -24,7 +24,7 @@ export function fingerprint(text, ext) {
 export function definesOf(text, ext) {
   const lang = languageOf(ext);
   if (!lang?.define) return [];
-  const code = lang.blank(text);
+  const code = (lang.ownDefinitions ?? ((c) => c))(lang.blank(text));
   return [...code.matchAll(lang.define)].map((m) => [m.slice(1).find(Boolean), code.slice(0, m.index).split('\n').length]).filter(([name]) => name);
 }
 

package/packs/base/hooks/lib/program-read.mjs

@@ -114,6 +114,9 @@ function chain(expr) {
 
 const str = (v) => (v && (v.t === 'str' || v.t === 'path') ? v.v : null);
 const joinPaths = (parts) => (parts.some((p) => p === null) ? null : parts.reduce((a, b) => (b.startsWith('/') ? b : a ? `${a.replace(/\/$/, '')}/${b}` : b), ''));
+// A path made of a part the reader cannot work out (a helper's own parameter) is unknown, never a path of null (KF-40: read_text on one
+// crashed sixteen hooks).
+const pathOf = (v) => (v === null ? null : { t: 'path', v });
 const PATH_FNS = /^(?:(?:pathlib\.)?(?:Pure)?(?:Posix)?Path|os\.path\.join|path\.join|path\.resolve|join|resolve|File\.join|os\.path\.expanduser|os\.path\.abspath|path\.normalize)$/;
 const READS = /^(?:(?:fs|fsp|fs\.promises)\.)?readFileSync$|^File\.read$|^IO\.read$/;
 
@@ -129,7 +132,7 @@ export function evaluate(expr, ctx) {
     const slash = splitTop(e, '/');
     if (slash.length > 1) {
       const vs = slash.map((p) => evaluate(p, ctx));
-      return vs[0]?.t === 'path' ? { t: 'path', v: joinPaths(vs.map(str)) } : null;
+      return vs[0]?.t === 'path' ? pathOf(joinPaths(vs.map(str))) : null;
     }
   }
   const c = chain(e);
@@ -166,7 +169,7 @@ function callFn(name, args, ctx) {
   const vs = args.filter((a) => !/^\w+\s*=[^=]/.test(a)).map((a) => evaluate(a, ctx));
   if (/(?:^|\.)Path\.home$/.test(name)) return process.env.HOME ? { t: 'path', v: process.env.HOME } : null;
   if (/(?:^|\.)Path\.cwd$|^process\.cwd$|^os\.getcwd$/.test(name)) return { t: 'path', v: ctx.at('.') };
-  if (PATH_FNS.test(name)) return vs.length ? { t: 'path', v: joinPaths(vs.map(str)) } : null;
+  if (PATH_FNS.test(name)) return vs.length ? pathOf(joinPaths(vs.map(str))) : null;
   if (READS.test(name) || /^(?:io\.|codecs\.)?open$/.test(name)) {
     const p = str(vs[0]);
     if (p === null) return null;
@@ -179,7 +182,7 @@ function callFn(name, args, ctx) {
 function callMethod(base, m, args, ctx) {
   const vs = args.map((a) => evaluate(a, ctx));
   if (['expanduser', 'resolve', 'absolute'].includes(m)) return base.t === 'path' ? base : null;
-  if (m === 'joinpath') return { t: 'path', v: joinPaths([base.v, ...vs.map(str)]) };
+  if (m === 'joinpath') return pathOf(joinPaths([base.v, ...vs.map(str)]));
   if ((m === 'read_text' && base.t === 'path') || (m === 'read' && base.t === 'file')) {
     ctx.reads?.add(ctx.at(base.v));
     return { t: 'str', v: ctx.readText(ctx.at(base.v)) ?? '' };

package/packs/base/hooks/lib/rust-scan.mjs

@@ -0,0 +1,139 @@
+// Rust's own reading (KWB-75). C's blanker takes a lifetime for a char literal and blanks the rest of its line, and a generic blanker takes '"' for a
+// string opening. Nested block comments and raw strings have no form in either. Offsets are kept, so a match's line is the file's line.
+//   blankRust(src)      comments go; a string or char literal keeps two quotes, so it stays one token
+//   withoutTests(code)  on blanked code: what `#[cfg(test)]` or a `#[test]` attribute marks goes too, since Rust's unit tests live in the file they test
+//   ownDefinitions(code)  on blanked code: tests, impls and traits go, leaving the free functions
+//   lookupMatches(text)  every `match` that is a table of literals on one enum, for dispatch-once
+const spaces = (s) => s.replace(/[^\n]/g, ' ');
+const quoted = (s) => (s.length >= 2 ? `"${spaces(s.slice(1, -1))}"` : spaces(s));
+
+function commentEnd(src, start) {
+  let depth = 1;
+  let i = start + 2;
+  while (i < src.length && depth > 0) {
+    if (src.startsWith('/*', i)) { depth += 1; i += 2; }
+    else if (src.startsWith('*/', i)) { depth -= 1; i += 2; }
+    else i += 1;
+  }
+  return i;
+}
+
+function stringEnd(src, start) {
+  let i = start + 1;
+  while (i < src.length && src[i] !== '"') i += src[i] === '\\' ? 2 : 1;
+  return Math.min(i + 1, src.length);
+}
+
+// r"..", r#".."#, br#".."#, cr#".."#: nothing inside escapes, and the hashes close it. Returns where the opening quote is, and the end, or null.
+function rawString(src, i) {
+  if (/\w/.test(src[i - 1] ?? '')) return null;
+  const open = src.slice(i, i + 80).match(/^(?:b|c)?r(#*)"/);
+  if (!open) return null;
+  const close = src.indexOf(`"${open[1]}`, i + open[0].length);
+  return { quote: i + open[0].length - 1, end: close === -1 ? src.length : close + 1 + open[1].length };
+}
+
+// A quote opens a char literal only when one character, or one escape, then closes it; otherwise it is a lifetime or a label.
+function charEnd(src, i) {
+  if (src[i + 1] === '\\') { const e = src.indexOf("'", i + 3); return e === -1 ? null : e + 1; }
+  const one = String.fromCodePoint(src.codePointAt(i + 1) ?? 32);
+  return src[i + 1 + one.length] === "'" ? i + 2 + one.length : null;
+}
+
+export function blankRust(src) {
+  let out = '';
+  let i = 0;
+  const take = (end, shown) => { out += shown(src.slice(i, end)); i = end; };
+  while (i < src.length) {
+    const raw = src[i] === 'r' || src[i] === 'b' || src[i] === 'c' ? rawString(src, i) : null;
+    const char = src[i] === "'" ? charEnd(src, i) : null;
+    if (src.startsWith('//', i)) { const e = src.indexOf('\n', i); take(e === -1 ? src.length : e, spaces); }
+    else if (src.startsWith('/*', i)) take(commentEnd(src, i), spaces);
+    else if (raw) { out += spaces(src.slice(i, raw.quote)); i = raw.quote; take(raw.end, quoted); }
+    else if (src[i] === '"') take(stringEnd(src, i), quoted);
+    else if (char) take(char, quoted);
+    else { out += src[i]; i += 1; }
+  }
+  return out;
+}
+
+const TEST_MARK = /#\[\s*(?:cfg\s*\(\s*(?:all\s*\(\s*)?test\b[^\]]*\)|(?:\w+::)*test\b[^\]]*)\s*\]/g;
+
+// The end of the item an attribute marks: its closing brace, or the `;` of an item with no body.
+function itemEnd(code, start) {
+  let round = 0;
+  for (let i = start; i < code.length; i += 1) {
+    const c = code[i];
+    if (c === '(' || c === '[') round += 1;
+    else if (c === ')' || c === ']') round -= 1;
+    else if (c === ';' && round === 0) return i + 1;
+    else if (c === '{' && round === 0) {
+      let depth = 0;
+      for (let j = i; j < code.length; j += 1) {
+        if (code[j] === '{') depth += 1;
+        else if (code[j] === '}' && --depth === 0) return j + 1;
+      }
+      return code.length;
+    }
+  }
+  return code.length;
+}
+
+function blankItems(code, mark) {
+  let out = '';
+  let at = 0;
+  for (const m of code.matchAll(mark)) {
+    if (m.index < at) continue;
+    const end = itemEnd(code, m.index + m[0].length);
+    out += code.slice(at, m.index) + spaces(code.slice(m.index, end));
+    at = end;
+  }
+  return out + code.slice(at);
+}
+
+export const withoutTests = (code) => blankItems(code, TEST_MARK);
+
+// A method lives in its type's namespace: `from_str` on a second type is the trait doing its job, and `is_none` on two types is two methods (KWB-81).
+// Only a free function can be made again by name. A method copied is caught by its statements, whatever it is called.
+const TYPE_ITEM = /^[ \t]*(?:pub(?:\([^)]*\))?\s+)?(?:unsafe\s+)?(?:impl|trait)\b[^{;]*(?=\{)/gm;
+export const ownDefinitions = (code) => blankItems(withoutTests(code), TYPE_ITEM);
+
+// What a `match` body holds, arm by arm: the patterns, and what the arm gives.
+function armsOf(body) {
+  const arms = [];
+  let depth = 0;
+  let from = 0;
+  let head = null;
+  for (let i = 0; i < body.length; i += 1) {
+    const c = body[i];
+    if ('({['.includes(c)) depth += 1;
+    else if (')}]'.includes(c)) depth -= 1;
+    else if (depth === 0 && head === null && body.startsWith('=>', i)) { head = body.slice(from, i); from = i + 2; i += 1; }
+    else if (depth === 0 && head !== null && c === ',') { arms.push({ head, value: body.slice(from, i).trim() }); head = null; from = i + 1; }
+  }
+  if (head !== null) arms.push({ head, value: body.slice(from).trim() });
+  return arms;
+}
+
+const LITERAL = /^(?:"\s*"|-?\d[\w.]*)$/; // a table of true and false is a predicate, not data about the kind
+const MIN_VARIANTS = 3;
+const NOT_A_KIND = new Set(['Self', 'Option', 'Result', 'Ordering']); // the standard library's own enums, and an enum inside its own impl
+
+// Every `match` that is only a lookup table: each variant of one enum to a plain value. `owned`: this file declares the enum or has its impl.
+// A match that does real work on an enum is good Rust, in any number of files: the compiler holds every one to every variant. A lookup table is
+// data about the kind, and belongs with the kind. Measured on eight crates: a rule on every match would have refused 7 to 12 in 100 of them.
+export function lookupMatches(text) {
+  const code = withoutTests(blankRust(text));
+  const owns = new Set([...code.matchAll(/\b(?:enum|impl(?:<[^>{]*>)?)\s+([A-Z]\w*)/g)].map((m) => m[1]));
+  const found = [];
+  for (const m of code.matchAll(/\bmatch\s[^{;]+?(?=\{)/g)) {
+    const open = m.index + m[0].length;
+    const arms = armsOf(code.slice(open + 1, itemEnd(code, open) - 1));
+    if (!arms.length || !arms.every((a) => LITERAL.test(a.value))) continue;
+    const paths = arms.flatMap((a) => [...a.head.matchAll(/\b([A-Z]\w*)::([A-Z]\w*)/g)]);
+    const kind = paths[0]?.[1];
+    const labels = new Set(paths.filter((p) => p[1] === kind).map((p) => p[2]));
+    if (kind && labels.size >= MIN_VARIANTS && !NOT_A_KIND.has(kind)) found.push({ kind, labels, owned: owns.has(kind) });
+  }
+  return found;
+}

package/packs/base/hooks/lib/shape-lists.mjs

@@ -0,0 +1,31 @@
+// shape-lists: consecutive lines (or ;/, separated pieces of one line) that differ only in one number running over every instance: a hand-listed set, one line
+// per instance. Split out of shape.mjs at its line limit.
+//   handLists(lines, c, out, seen): adds a finding to out for each such set of the concept c
+import { classify, isExampleLine, named, parts } from './shape.mjs';
+
+const templatesOf = (t) => [...t.matchAll(/(?<![\w.])\d+(?![\w.])/g)].map((m) => ({ tpl: t.slice(0, m.index) + '#' + t.slice(m.index + m[0].length), v: Number(m[0]) }));
+
+export function handLists(lines, c, out, seen) {
+  if (!c.count || c.count < 2 || c.shape !== 'many') return;
+  const mentions = (t) => parts(t).some((p) => c.words.includes(p)) || c.arrays.some((a) => named(t, a));
+  const runOver = (pieces, at, whole = null) => {
+    for (let i = 0; i + c.count <= pieces.length; i += 1) {
+      for (const first of templatesOf(pieces[i].trim())) {
+        if (first.v > 1 || !mentions(whole ?? first.tpl)) continue;
+        let ok = true;
+        for (let k = 1; k < c.count && ok; k += 1) ok = templatesOf(pieces[i + k].trim()).some((t) => t.tpl === first.tpl && t.v === first.v + k);
+        if (ok) return at(i);
+      }
+    }
+    return null;
+  };
+  const lineNo = runOver(lines, (i) => i);
+  if (lineNo !== null && !isExampleLine(lines[lineNo]) && !seen.has(`${lineNo}|${c.name}`)) {
+    out.push({ line: lineNo + 1, text: lines[lineNo].trim(), concept: c.name, instance: 'each', why: `a hand-listed set, one line per ${c.name}: write one loop over every ${c.name}, or the generator` });
+  }
+  lines.forEach((l, i) => {
+    if (seen.has(`${i}|${c.name}`) || isExampleLine(l) || classify(l, c, null)) return;
+    const pieces = l.split(/[;,]/);
+    if (pieces.length >= c.count && runOver(pieces, () => true, l)) out.push({ line: i + 1, text: l.trim(), concept: c.name, instance: 'each', why: `a hand-listed set, one piece per ${c.name}: write one loop over every ${c.name}, or the generator` });
+  });
+}

package/packs/base/hooks/lib/shape-prose.mjs

@@ -0,0 +1,78 @@
+// shape-prose: what in a line is English, arithmetic or a name, and so names no instance (KF-13, KF-17, KF-20, KF-28, KF-36: 14 of shape-law's 25 refusals on the
+// MPX 500 were wrong, on words like these). Each test is narrow on purpose: the same line with the bare form stays refused (test/kf-refusals.test.mjs holds both).
+//   blankMessages(line, file) -> line with a sentence in a double-quoted string blanked, same length; a short key ("knob 1") stays
+//   isFirstMatch(line, m)    "the first program with this name", "each bank's first program", the words "first program" in quotes
+//   isSourceRole(line, m)    a comment quoting a role a source gives: "[MAN] Edit knob 1 selects"
+//   isKnownName(role, word, shape)   "EDIT knob", when editKnob is a concept or a listed selector
+//   isLongerName(line, end)  "MIDI Program Change": the word starts a longer proper name
+//   isSum(before)            "x + 1 == program": the number is an operand, not what is compared
+//   isLibraryCall(line, at, shape)   juce::MidiMessage::programChange (1, ...): a library's call, or one on a listed value type
+//   declaredAmount(root, name, text) a call whose declared first parameter is an amount: turnProgram (int steps, ...)
+import { execFileSync } from 'node:child_process';
+import { extname } from 'node:path';
+import { languageOf } from './languages.mjs';
+
+const SENTENCE_WORDS = 3;
+const LIBRARIES = new Set(['juce', 'std', 'boost', 'absl', 'Qt']);
+const AMOUNT = /^(?:steps?|detents?|clicks?|notches|ticks?|amount|delta|by|count|n|offset|increment|distance)$/i;
+const SOURCE_FILES = ['*.h', '*.hh', '*.hpp', '*.c', '*.cc', '*.cpp', '*.mm', '*.js', '*.mjs', '*.ts', '*.tsx', '*.py', '*.go', '*.rs', '*.java', '*.cs', '*.swift', '*.kt'];
+
+export function blankMessages(line, file) {
+  if (!languageOf(extname(file ?? ''))) return line;
+  return line.replace(/"(?:[^"\\]|\\.)*"/g, (s) => (s.trim().split(/\s+/).length >= SENTENCE_WORDS ? ' '.repeat(s.length) : s));
+}
+
+export function isFirstMatch(line, m) {
+  if (!/^first\b/i.test(m[0])) return false;
+  const before = line.slice(0, m.index);
+  const after = line.slice(m.index + m[0].length);
+  if (before.endsWith('"') && after.startsWith('"')) return true;
+  return /(?:'s|\b[Aa]|\b[Ee]ach|\b[Ee]very|\b[Aa]ny)\s+$/.test(before) || /^(?:'s)?\s+(?:with|that|which|whose|where|matching|found|a|an)\b/.test(after);
+}
+
+export function isSourceRole(line, m) {
+  const isComment = /^\s*(?:\/\/|\/\*|\*|#)/.test(line);
+  return isComment && /\[[A-Z]{2,6}\]/.test(line.slice(0, m.index)) && /^\s+[a-z]+s\b/.test(line.slice(m.index + m[0].length));
+}
+
+const named = new WeakMap();
+function namesOf(shape) {
+  if (!named.has(shape)) {
+    const rows = Object.values(shape.concepts);
+    named.set(shape, new Set(rows.flatMap((c) => [c.name, ...c.selectors, ...c.constants]).map((n) => n.toLowerCase())));
+  }
+  return named.get(shape);
+}
+export const isKnownName = (role, word, shape) => namesOf(shape).has(`${role}${word}`.toLowerCase());
+
+export const isLongerName = (line, end) => /^\s+[A-Z][a-z]/.test(line.slice(end));
+export const isSum = (before) => /[+\-*/%]\s*$/.test(before);
+
+export function isLibraryCall(line, at, shape) {
+  const path = line.slice(0, at).match(/([A-Za-z_]\w*)::(?:[A-Za-z_]\w*::)*$/);
+  if (!path) return false;
+  const last = line.slice(0, at).match(/([A-Za-z_]\w*)::$/)?.[1];
+  return LIBRARIES.has(path[1]) || shape.values?.has(last);
+}
+
+// The first parameter of each declaration of `name`, from the text being written and the project's files.
+function firstParameters(root, name, text) {
+  const shape = new RegExp(`\\b${name}\\s*\\(\\s*(?:const\\s+)?(?:[\\w:<>]+[\\s&*]+)+(\\w+)\\s*[,)=]`, 'g');
+  let found = '';
+  try {
+    found = execFileSync('git', ['-C', root, 'grep', '--untracked', '-hE', `\\b${name}[[:space:]]*\\(`, '--', ...SOURCE_FILES], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 });
+  } catch {
+    found = ''; // no match, or no repository: nothing declares it, so the call stays an instance
+  }
+  return [...`${text}\n${found}`.matchAll(shape)].map((m) => m[1]);
+}
+
+const amounts = new Map();
+export function declaredAmount(root, name, text) {
+  const key = `${root}\0${name}`;
+  if (!amounts.has(key)) {
+    const params = firstParameters(root, name, text);
+    amounts.set(key, params.length > 0 && params.every((p) => AMOUNT.test(p)));
+  }
+  return amounts.get(key);
+}

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

@@ -22,6 +22,8 @@ import { logRefusal } from './hook-log.mjs';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { matchesAny } from './glob.mjs';
+import { blankMessages, isFirstMatch, isKnownName, isLibraryCall, isLongerName, isSourceRole, isSum } from './shape-prose.mjs';
+import { handLists } from './shape-lists.mjs';
 
 export const SHAPE_FILE = 'design/shape.json';
 export const ASK = 'example, rule, or constant?';
@@ -113,7 +115,7 @@ export function isExampleLine(line) {
   return OPENS.test(rest) || EXAMPLE_CELL.test(line);
 }
 
-const named = (line, name) => new RegExp(`(?<![\\w])${esc(name)}(?![\\w])`).test(line);
+export const named = (line, name) => new RegExp(`(?<![\\w])${esc(name)}(?![\\w])`).test(line);
 export function classify(line, concept, shape) {
   const c = typeof concept === 'string' ? shape?.concepts?.[concept] : concept;
   if (isExampleLine(line)) return 'example';
@@ -165,15 +167,17 @@ const ORDINALS = ['first', 'second', 'third', 'fourth', 'fifth', 'sixth', 'seven
 const NOT_ROLES = new Set(['ALL', 'EACH', 'EVERY', 'ANY', 'ONE', 'NEW', 'THE', 'NO', 'THIS', 'THAT', 'SAME', 'OTHER', 'OWN', 'NEXT', 'MANY', 'NOT', 'AND', 'OR', 'TODO', 'NOTE', 'FIXME', 'IN', 'ON', 'OF', 'TO', 'A', 'AN', 'EMPTY', 'SELECTED', 'OPEN', 'CURRENT',
   'PASS', 'FAIL', 'FAILED', 'RED', 'GREEN', 'OK', 'SKIP', 'WARN', 'ERROR']); // a gate's verdict before the word ("FAIL slot 2"; KWB-15)
 
-function lineHits(line, c, shape, aliases, inSwitch) {
+function lineHits(line, c, shape, aliases, inSwitch, file) {
   const hits = [];
-  const add = (instance, why) => hits.push({ instance: String(instance), why });
+  const add = (instance, why, call) => hits.push({ instance: String(instance), why, call });
+  const words = blankMessages(line, file); // what is read as words: a sentence in a string is text (KF-17)
   for (const re of c.patterns) for (const m of line.matchAll(re)) add(m[1] ?? m[0], `matches the pattern ${re.source}`);
   const W = c.words.map(esc).sort((a, b) => b.length - a.length).join('|');
-  const num = new RegExp(`(?<![A-Za-z0-9])(${W})(?:[ _#-]|\\s+(?:no\\.?|number|#)\\s*)?(\\d+)(?!\\d)((?:\\s*(?:-|–|\\.\\.|to|through)\\s*)(\\d+))?`, 'gi');
+  const num = new RegExp(`(?<![A-Za-z0-9])(${W})(?:[ _#-]|\\s+(?:no\\.?|number|#)\\s*)?(\\d+)(?![\\dxX])((?:\\s*(?:-|–|\\.\\.|to|through)\\s*)(\\d+))?`, 'gi'); // 0x18000 is an address (KF-13)
   // A multi-word all-caps label ("AIM EFFECTS", "NOTES MONO") names a control, not an instance (KWB-22): the caps word before it.
   const labelBefore = (at) => { const w = /([A-Z][A-Z0-9]+)\s+$/.exec(line.slice(0, at)); return w !== null && !NOT_ROLES.has(w[1]); };
-  for (const m of line.matchAll(num)) {
+  for (const m of words.matchAll(num)) {
+    if (isSourceRole(line, m)) continue; // KF-28
     if (c.count !== null && !m[3] && Number(m[2]) > c.count) continue; // past the count: a value, not an instance (KWB-22)
     if (m[1] === m[1].toUpperCase() && labelBefore(m.index)) continue; // AIM EFFECTS 100: a control's value
     if (m[3] && c.count !== null) {
@@ -186,13 +190,15 @@ function lineHits(line, c, shape, aliases, inSwitch) {
   for (const m of line.matchAll(camel)) add(m[2], `names it by number in an identifier ("${m[0]}")`);
   const S = c.single.map(esc).join('|');
   const ord = new RegExp(`(?<![A-Za-z0-9])(${ORDINALS.join('|')}|\\d+(?:st|nd|rd|th))[\\s_-]*(${S})(?![a-z])`, 'gi');
-  for (const m of line.matchAll(ord)) {
+  for (const m of words.matchAll(ord)) {
+    if (isFirstMatch(words, m)) continue; // KF-17
     const o = m[1].toLowerCase();
     add(ORDINALS.includes(o) ? ORDINALS.indexOf(o) + 1 : parseInt(o, 10), `names it by ordinal ("${m[0].trim()}")`);
   }
   if (c.shape === 'many') {
     const role = new RegExp(`(?<![A-Za-z0-9_])([A-Z][A-Z0-9]+)\\s+(${c.single.flatMap((w) => [esc(w), esc(cap(w))]).join('|')})(?![A-Za-z0-9_])`, 'g');
-    for (const m of line.matchAll(role)) if (!NOT_ROLES.has(m[1]) && !c.words.includes(m[1].toLowerCase()) && !c.names.has(m[1]) && !labelBefore(m.index)) add(m[1], `names it by a role ("${m[0]}"): the instance is a job or a value, not a ${c.name}`);
+    const notARole = (m) => NOT_ROLES.has(m[1]) || c.words.includes(m[1].toLowerCase()) || c.names.has(m[1]) || labelBefore(m.index) || isKnownName(m[1], m[2], shape) || isLongerName(words, m.index + m[0].length);
+    for (const m of words.matchAll(role)) if (!notARole(m)) add(m[1], `names it by a role ("${m[0]}"): the instance is a job or a value, not a ${c.name}`);
   }
   for (const m of line.matchAll(/([A-Za-z_]\w*)\s*(?:\[\s*(\d+)\s*\]|\.at\(\s*(\d+)\s*\))/g)) {
     const lead = line.slice(0, m.index).trimEnd();
@@ -203,43 +209,16 @@ function lineHits(line, c, shape, aliases, inSwitch) {
   }
   const EXPR = '[A-Za-z_]\\w*(?:(?:\\.|->|::)[A-Za-z_]\\w*|\\(\\)|\\[\\w*\\])*';
   for (const m of line.matchAll(new RegExp(`(${EXPR})\\s*(?:===?|!==?)\\s*(\\d+)(?![\\w.])`, 'g'))) if (conceptOfExpr(m[1], shape, aliases) === c.name) add(m[2], `compares a ${c.name} with a number ("${m[0]}")`);
-  for (const m of line.matchAll(new RegExp(`(?<![\\w.])(\\d+)\\s*(?:===?|!==?)\\s*(${EXPR})`, 'g'))) if (conceptOfExpr(m[2], shape, aliases) === c.name) add(m[1], `compares a ${c.name} with a number ("${m[0]}")`);
+  for (const m of line.matchAll(new RegExp(`(?<![\\w.])(\\d+)\\s*(?:===?|!==?)\\s*(${EXPR})`, 'g'))) if (conceptOfExpr(m[2], shape, aliases) === c.name && !isSum(line.slice(0, m.index))) add(m[1], `compares a ${c.name} with a number ("${m[0]}")`);
   if (inSwitch === c.name) for (const m of line.matchAll(/\bcase\s+(\d+)\s*:/g)) add(m[1], `a case for one ${c.name} ("${m[0]}")`);
   for (const m of line.matchAll(/(?<![\w])([A-Za-z_]\w*)\s*\(\s*(\d+)\s*[,)]/g)) {
     const ps = parts(m[1]);
-    if (ps.some((p) => c.single.includes(p)) && !ps.some((p) => c.plural.has(p) || COUNTISH.has(p))) add(m[2], `drives one ${c.name} by number ("${m[0].replace(/[,)]$/, '')}")`);
+    if (isLibraryCall(line, m.index, shape)) continue; // KF-20
+    if (ps.some((p) => c.single.includes(p)) && !ps.some((p) => c.plural.has(p) || COUNTISH.has(p))) add(m[2], `drives one ${c.name} by number ("${m[0].replace(/[,)]$/, '')}")`, m[1]);
   }
   return hits;
 }
 
-// Consecutive lines (or ;/, separated pieces of one line) that differ only in one number running over every instance:
-// a hand-listed set, one line per instance.
-function handLists(lines, c, out, seen) {
-  if (!c.count || c.count < 2 || c.shape !== 'many') return;
-  const mentions = (t) => parts(t).some((p) => c.words.includes(p)) || c.arrays.some((a) => named(t, a));
-  const templates = (t) => [...t.matchAll(/(?<![\w.])\d+(?![\w.])/g)].map((m) => ({ tpl: t.slice(0, m.index) + '#' + t.slice(m.index + m[0].length), v: Number(m[0]) }));
-  const runOver = (pieces, at, whole = null) => {
-    for (let i = 0; i + c.count <= pieces.length; i += 1) {
-      for (const first of templates(pieces[i].trim())) {
-        if (first.v > 1 || !mentions(whole ?? first.tpl)) continue;
-        let ok = true;
-        for (let k = 1; k < c.count && ok; k += 1) ok = templates(pieces[i + k].trim()).some((t) => t.tpl === first.tpl && t.v === first.v + k);
-        if (ok) return at(i);
-      }
-    }
-    return null;
-  };
-  const lineNo = runOver(lines, (i) => i);
-  if (lineNo !== null && !isExampleLine(lines[lineNo]) && !seen.has(`${lineNo}|${c.name}`)) {
-    out.push({ line: lineNo + 1, text: lines[lineNo].trim(), concept: c.name, instance: 'each', why: `a hand-listed set, one line per ${c.name}: write one loop over every ${c.name}, or the generator` });
-  }
-  lines.forEach((l, i) => {
-    if (seen.has(`${i}|${c.name}`) || isExampleLine(l) || classify(l, c, null)) return;
-    const pieces = l.split(/[;,]/);
-    if (pieces.length >= c.count && runOver(pieces, () => true, l)) out.push({ line: i + 1, text: l.trim(), concept: c.name, instance: 'each', why: `a hand-listed set, one piece per ${c.name}: write one loop over every ${c.name}, or the generator` });
-  });
-}
-
 export function findInstanceLiterals(text, file, shape, { only = null } = {}) {
   if (!shape || !text) return [];
   const concepts = Object.values(shape.concepts).filter((c) => c.shape === 'many' || (c.shape === 'one' && c.id));
@@ -259,11 +238,11 @@ export function findInstanceLiterals(text, file, shape, { only = null } = {}) {
       // only 'brief': an example or a declared constant read by name excuses it (the number rule's third form), a selector does not
       if (cls === 'example' || (cls === 'constant' && only === 'brief') || (cls && only !== 'example' && only !== 'brief')) continue;
       const once = new Set();
-      for (const h of lineHits(line, c, shape, aliases, inSwitch)) {
+      for (const h of lineHits(line, c, shape, aliases, inSwitch, file)) {
         if (once.has(h.instance)) continue;
         once.add(h.instance);
         seen.add(`${i}|${c.name}`);
-        out.push({ line: i + 1, text: shown[i].trim(), concept: c.name, instance: h.instance, why: h.why });
+        out.push({ line: i + 1, text: shown[i].trim(), concept: c.name, instance: h.instance, why: h.why, call: h.call });
       }
     }
   });

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

@@ -66,9 +66,14 @@ export function lastTurn(path) {
   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 turn.uses) {
+  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 });

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/making-check.mjs

@@ -22,12 +22,13 @@ import { copyGlobs, excludeGlobs, FIX, isGenerated, isSource, real } from './lib
 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 { 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'];
@@ -54,7 +55,8 @@ const OVERRIDE = [
 ];
 
 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));
+// 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())];
 
@@ -82,10 +84,11 @@ export function unknownConcepts(making, shape) {
   // 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(',')) {
+  // 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 && !['none', 'no', '-', 'n/a'].includes(w) && !known.has(w)) out.push(w);
+      if (w && !NOT_CONCEPTS.has(w) && !known.has(w)) out.push(w);
     }
   }
   return out;
@@ -180,8 +183,10 @@ export function check(event, cwd = event.cwd ?? process.cwd()) {
     }
   }
 
-  // 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))]
+  // 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)

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

@@ -4,8 +4,9 @@
 // names the runner and its hooks in one command: node ".../run-hooks.mjs" .claude/hooks/a.mjs .claude/hooks/b.mjs
 // Each hook module exports hook(text) (the event's JSON text, as stdin was) and returns its exit code; the runner calls
 // them in turn, catches each one's stdout and stderr, writes each one's timing line to .claude/hooks.log (lib/hook-log.mjs)
-// and its own (hook "run-hooks": the whole process, node's start-up included), and exits with the worst code: 2 if any
-// hook refused, else the first other non-zero. A hook that throws counts as exit 1 (a non-blocking error), as it would alone.
+// and its own (hook "run-hooks": the whole process, node's start-up included), and exits 2 if any hook refused. A hook that
+// throws, or exits with anything but 0 or 2, crashed, and lib/crash-policy.mjs decides what the call does (KF-18: a crash
+// on a tool call refuses once, and says so). lib/unread-writes.mjs says when no hook could read what a command writes (KF-40).
 // Every hook still runs on its own too (node .claude/hooks/a.mjs, its selftest, a project's hand-made entry).
 //   node run-hooks.mjs <hook path or name>...   (stdin: the event)
 //   node run-hooks.mjs --selftest
@@ -13,8 +14,10 @@ import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, writeSync
 import { tmpdir } from 'node:os';
 import { basename, dirname, isAbsolute, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { crashVerdict } from './lib/crash-policy.mjs';
 import { logCall } from './lib/event-log.mjs';
 import { appendRotated, isMain, logHook, projectRoot, readHookLog } from './lib/hook-log.mjs';
+import { unreadWrites } from './lib/unread-writes.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 export const RUNNER = 'run-hooks';
@@ -77,9 +80,12 @@ export async function runAll(args, text, root = projectRoot()) {
     logHook(root, { event: ev.hook_event_name, hook: name, ms, code: c, tool: ev.tool_name ?? ev.source });
     judged.push({ hook: name, ms, code: c, reason: err.slice(before).join(''), out: out.join('') });
     if (c === 2) code = 2;
-    else if (c !== 0 && code === 0) code = c;
   }
   logCall(root, text, judged, appendRotated, performance.now());
+  const crash = crashVerdict(root, ev, judged);
+  if (crash.stderr) err.push(crash.stderr);
+  if (crash.code === 2) code = 2;
+  outs.push(...[crash.stdout, code === 0 ? unreadWrites(ev, root) : ''].filter(Boolean));
   return { code, stdout: mergeOut(outs), stderr: err.join('') };
 }
 
@@ -100,15 +106,17 @@ async function selftest() {
   const r2 = await runAll([ok, no], JSON.stringify({ hook_event_name: 'PreToolUse', tool_name: 'Write' }), dir);
   cases.push(['no refusal: exit 0', r2.code === 0 && r2.stdout === '{"systemMessage":"a"}']);
   const r3 = await runAll([boom, ok], bash, dir);
-  cases.push(['a hook that throws is exit 1 and the next still runs', r3.code === 1 && r3.stderr.includes('throws failed') && r3.stdout.includes('"a"')]);
+  cases.push(['a hook that throws refuses the call, says so, and the next still runs', r3.code === 2 && r3.stderr.includes('throws crashed') && r3.stdout.includes('"a"')]);
+  const r4 = await runAll([boom, ok], bash, dir);
+  cases.push(['the same call again goes through, and says so', r4.code === 0 && r4.stdout.includes('throws crashed')]);
   const rows = readHookLog(dir);
-  cases.push(['one timing line per hook per call', rows.length === 7 && rows.filter((r) => r.hook === 'refuses').map((r) => r.code).join() === '2,0']);
+  cases.push(['one timing line per hook per call', rows.length === 9 && rows.filter((r) => r.hook === 'refuses').map((r) => r.code).join() === '2,0']);
   cases.push(['the line names the event and the tool', rows[0].event === 'PreToolUse' && rows[0].tool === 'Bash']);
   const lines = (f) => readFileSync(join(dir, '.claude/logs', f), 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l));
   const refused = lines('refusals.jsonl');
-  cases.push(['every call is a line of events.jsonl', lines('events.jsonl').length === 3]);
+  cases.push(['every call is a line of events.jsonl', lines('events.jsonl').length === 4]);
   cases.push(['a refusal keeps its reason and what was tried', refused[0].hook === 'refuses' && refused[0].reason.includes('BLOCKED by refuses') && refused[0].command === 'rm x']);
-  cases.push(['a crash is kept too', refused.some((r) => r.hook === 'throws' && r.code === 1)]);
+  cases.push(['a crash is kept, in its own log', !refused.some((r) => r.hook === 'throws') && lines('crashes.jsonl').some((r) => r.hook === 'throws' && r.code === 1)]);
   rmSync(dir, { recursive: true, force: true });
   const bad = cases.filter(([, good]) => !good);
   for (const [label] of bad) console.error(`run-hooks selftest FAILED: ${label}`);