@thedecipherist/claude-packs 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,109 @@
+// making-check's planted faults: each a transcript of one turn in a throwaway git project, judged as Claude Code runs the
+// Stop hook. Kept beside the hook so the hook itself stays short.
+import { readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findJscpd } from './dup.mjs';
+import { git, put, runHook, scratchProject, verdicts } from './selftest.mjs';
+
+const FN = (name, k = '2.0f') => `float ${name} (float x, int slot) noexcept\n{\n    const float g = std::tan (kPi * cutoff[slot] / sampleRate);\n    const float k = ${k} - 2.0f * resonance[slot];\n` +
+  '    const float a1 = 1.0f / (1.0f + g * (g + k));\n    const float a2 = g * a1;\n    const float a3 = g * a2;\n    const float v3 = x - ic2eq[slot];\n' +
+  '    const float v1 = a1 * ic1eq[slot] + a2 * v3;\n    const float v2 = ic2eq[slot] + a2 * ic1eq[slot] + a3 * v3;\n    ic1eq[slot] = 2.0f * v1 - ic1eq[slot];\n' +
+  '    ic2eq[slot] = 2.0f * v2 - ic2eq[slot];\n    return v2;\n}\n';
+const SHAPE = { concepts: { slot: { shape: 'many', count: 4, generator: 'slotId(i, field)', words: ['slot', 'slots'], selectors: { selectedSlot: 'the open slot' } }, mixer: { shape: 'one', id: 'mixer', words: ['mixer'] } }, exclude: ['src/gen/**'] };
+const BUILD = (making) => `# x: the build\n\n## In progress\n\n| Started | Step | Task | State |\n|---|---|---|---|\n| 2026-11-01 10:00 EST | work/s1 | Slot filter${making ? `; ${making}` : ''} | started |\n\n## Steps\n`;
+
+export function selftest(hookUrl) {
+  const hook = fileURLToPath(hookUrl);
+  if (!findJscpd([process.cwd()])) { console.error('making-check selftest FAILED: jscpd not found (once-only\'s detector)'); return 1; }
+  const dir = scratchProject({ 'design/shape.json': JSON.stringify(SHAPE), 'src/slot/filter.cpp': `#include "filter.h"\n\n${FN('slotFilter')}`, 'build.md': BUILD('') });
+  git(dir, 'init', '-q', '-b', 'work/s1');
+  git(dir, 'add', '-A');
+  git(dir, 'commit', '-qm', 'start');
+  const good = 'making: one filter per slot; concepts: slot (many, 4); reuse: slotFilter in src/slot/filter.cpp';
+  let n = 0;
+  const T = join(dir, 'transcript.jsonl');
+  const user = (text) => ({ type: 'user', message: { role: 'user', content: text } });
+  const use = (name, input, refused = false) => {
+    const id = `t${n += 1}`;
+    return [{ type: 'assistant', cwd: dir, message: { role: 'assistant', content: [{ type: 'tool_use', id, name, input }] } },
+      { type: 'user', message: { content: [{ type: 'tool_result', tool_use_id: id, is_error: refused, content: refused ? 'BLOCKED' : 'ok' }] } }];
+  };
+  const say = (text) => ({ type: 'assistant', message: { content: [{ type: 'text', text }] } });
+  // every selftest run names its own sessions: the send-back counter lives in the temp folder, and a second run with the same names
+  // added to the first run's counts (0.9.3, KWB-7: the counter no longer resets between turns)
+  const run = `${process.pid}-${Date.now()}`;
+  const turn = (entries, { making = good, last = '', active = false, session = `s${n += 1}` } = {}) => {
+    session = `${run}-${session}`;
+    writeFileSync(join(dir, 'build.md'), BUILD(making));
+    writeFileSync(T, [user('build the slot filter'), ...entries.flat()].map((e) => JSON.stringify(e)).join('\n'));
+    return runHook(hook, dir, { hook_event_name: 'Stop', transcript_path: T, cwd: dir, session_id: session, stop_hook_active: active, last_assistant_message: last });
+  };
+  const at = (f) => join(dir, f);
+  const W = (f, content) => use('Write', { file_path: at(f), content });
+  // Three more turns of one session, each sent back: the last says what the limit did.
+  const sendBacks = (session, opts = {}) => { let got; for (let i = 0; i < 3; i += 1) got = turn([W('src/slot/gain.cpp', slotCode)], { making: '', session, ...opts }); return got; };
+  const slotCode = 'float slotGain (int slot) { return gains[slot]; }\n';
+  const mixerCode = 'float mixerLevel() { return mixer.level; }\n';
+  const landed = (f, text, fn) => { put(at(f), text); try { return fn(); } finally { rmSync(at(f), { force: true }); } };
+  const copy = `#include "filter.h"\n\n${FN('slotFilterB', '1.5f')}`;
+
+  const cases = [
+    ['slot code with a making line that names slot', turn([W('src/slot/gain.cpp', slotCode)]), 0],
+    ['slot code, no making line', turn([W('src/slot/gain.cpp', slotCode)], { making: '' }), 2],
+    ['the making line names mixer, the turn wrote slot', turn([W('src/slot/gain.cpp', slotCode)], { making: 'making: mixer meter; concepts: mixer (one)' }), 2],
+    ['the making line names lane, which has no manifest row', turn([W('src/slot/gain.cpp', slotCode)], { making: 'making: one filter per slot; concepts: slot (many, 4), lane (many); reuse: slotFilter in src/slot/filter.cpp' }), 2],
+    ['slot written by Edit, no making line', turn([use('Edit', { file_path: at('src/slot/filter.cpp'), old_string: 'x', new_string: slotCode })], { making: '' }), 2],
+    ['slot written by MultiEdit, no making line', turn([use('MultiEdit', { file_path: at('src/slot/filter.cpp'), edits: [{ old_string: 'x', new_string: slotCode }] })], { making: '' }), 2],
+    ['slot written by NotebookEdit, no making line', turn([use('NotebookEdit', { notebook_path: at('tools/look.ipynb'), new_source: 'slots = load()' })], { making: '' }), 2],
+    ['slot written by a shell heredoc, no making line', turn([use('Bash', { command: `cat > src/slot/gain.cpp <<'EOF'\n${slotCode}EOF` })], { making: '' }), 2],
+    ['slot written by sed -i, no making line', turn([use('Bash', { command: 'sed -i s/gain/slotGain/ src/slot/filter.cpp' })], { making: '' }), 2],
+    ['a refused write is not counted', turn([use('Write', { file_path: at('src/slot/gain.cpp'), content: slotCode }, true)], { making: '' }), 0],
+    ['a doc naming the mixer, no making line: docs are not judged (KWB-19)', turn([W('docs/mixer.md', 'The mixer sums the four buses.\n')], { making: '' }), 0],
+    ['plan and log files are not concepts written', turn([W('bugs.md', '| B-1 | slot 2 silent |\n')], { making: '' }), 0],
+    ['a turn that wrote nothing and claims nothing', turn([say('All green.')]), 0],
+    ['a write in another project is not judged', turn([use('Write', { file_path: join(tmpdir(), 'other-project-y', 'slot.cpp'), content: slotCode })], { making: '' }), 0],
+    ['source with no design/shape.json', (() => { rmSync(at('design/shape.json')); try { return turn([W('src/slot/gain.cpp', slotCode)]); } finally { put(at('design/shape.json'), JSON.stringify(SHAPE)); } })(), 2],
+    ['the turn wrote a copy of slotFilter with one line changed (once-only)', landed('src/slot/filter_b.cpp', copy, () => turn([W('src/slot/filter_b.cpp', copy)])), 2],
+    // a tracked file the turn added a copy to: its added lines come from one git diff of the checkout (KWB-24), the old lines
+    // never match themselves; the same file edited in place is no copy
+    ['the turn added a copy of slotFilter to a tracked file (Edit; git diff)', (() => {
+      const before = readFileSync(at('src/slot/filter.cpp'), 'utf8');
+      const add = `${before}\n${FN('slotFilterC', '1.25f')}`;
+      try { put(at('src/slot/filter.cpp'), add); return turn([use('Edit', { file_path: at('src/slot/filter.cpp'), old_string: 'x', new_string: FN('slotFilterC', '1.25f') })]); } finally { put(at('src/slot/filter.cpp'), before); }
+    })(), 2],
+    ['the turn changed one value of a tracked file in place', (() => {
+      const before = readFileSync(at('src/slot/filter.cpp'), 'utf8');
+      try { put(at('src/slot/filter.cpp'), before.replace('2.0f - 2.0f', '1.9f - 2.0f')); return turn([use('Edit', { file_path: at('src/slot/filter.cpp'), old_string: '2.0f', new_string: '1.9f' })]); } finally { put(at('src/slot/filter.cpp'), before); }
+    })(), 0],
+    ['the turn wrote code that calls slotFilter', landed('src/slot/level.cpp', 'float level (float x, int slot) { return slotFilter (x, slot); }\n', () => turn([W('src/slot/level.cpp', 'float level (float x, int slot) { return slotFilter (x, slot); }\n')])), 0],
+    ['a view is no override: an estimate that differs from the user\'s', turn([W('src/slot/gain.cpp', slotCode)], { last: 'You said it is small, but I would plan for hours. It is built as you asked.' }), 0],
+    ['a view is no override, in the short form', turn([W('src/slot/gain.cpp', slotCode)], { last: 'You said it is small, but I\'d plan for hours.' }), 0],
+    ['a quotation is no claim', turn([W('src/slot/gain.cpp', slotCode)], { last: 'The hook matched "you said it is small, but I built something else" in a log.' }), 0],
+    ['an override with no citation', turn([W('src/slot/gain.cpp', slotCode)], { last: 'The brief said to drive slot 2, but I built it for every slot instead.' }), 2],
+    ['an override citing docs/laws.md and logging the brief as the bug', turn([W('src/slot/gain.cpp', slotCode), W('bugs.md', '| B-9 | the brief named slot 2 |\n')], { last: 'The brief said to drive slot 2, but docs/laws.md L8 says every slot is one shape, so I built it for all; B-9 logs the brief.' }), 0],
+    ['an override citing design/shape.json without logging the brief', turn([W('src/slot/gain.cpp', slotCode)], { last: 'You asked for slot 2 only, but I built every slot instead: design/shape.json row "slot" is many(4).' }), 2],
+    ['an override decided overnight under Decisions', turn([W('src/slot/gain.cpp', slotCode), W('docs/decisions.md', '## Decisions\n\n- D-3: no law covered the fade; chose 20 ms.\n')], { last: 'Overnight: the order did not name a fade, but no law covers it, so I decided it under Decisions (D-3) rather than what the brief said.' }), 0],
+    ['the third send-back with the same findings ends the turn', (() => {
+      const s = 'loop';
+      turn([W('src/slot/gain.cpp', slotCode)], { making: '', session: s });
+      return sendBacks(s, { active: true });
+    })(), 0],
+    ['the limit holds when each send-back comes as a new turn (no stop_hook_active; KWB-7)', (() => {
+      const s = 'loop-new-turns';
+      turn([W('src/slot/gain.cpp', slotCode)], { making: '', session: s });
+      return sendBacks(s);
+    })(), 0],
+    ['a turn sent back is judged with what it wrote before the feedback', (() => {
+      const fb = { type: 'user', isMeta: true, message: { content: 'Stop hook feedback: making-check sent this turn back' } };
+      return turn([W('src/slot/gain.cpp', slotCode), [fb], [say('Done.')]], { making: '' });
+    })(), 2],
+    ['a ";" inside the brackets of a shape ("slot (many, 4; slotId(i, field))", KWB-17)', turn([W('src/slot/gain.cpp', slotCode)], { making: 'making: one filter per slot; concepts: slot (many, 4; slotId(i, field)), mixer (one); reuse: slotFilter in src/slot/filter.cpp' }), 0],
+    ['a note naming a concept the making line does not name (KWB-19)', turn([W('docs/notes.md', 'The mixer meter and its Status line.\n')]), 0],
+    ['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],
+  ];
+  return verdicts('making-check', cases);
+}

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

@@ -0,0 +1,76 @@
+// What a write repeats when no stretch of it is an exact copy (0.25.0). AI rarely copies exactly: it writes the same thing again with a line
+// changed here and there, or makes a function the repo already has. Both are judged from each file's statements and definitions:
+//   fingerprint(text, ext) -> [[hash, line]]    the statements long enough to mean something
+//   definesOf(text, ext)   -> [[name, line]]    the functions and classes defined at the top level
+//   nearCopy(added, others) -> { file, from, to, line, matched, of } | null: the place holding most of `added`, in order
+import { createHash } from 'node:crypto';
+import { statementsOf } from './code-shapes.mjs';
+import { languageOf } from './languages.mjs';
+
+const MIN_STATEMENT = 8;   // tokens: a shorter statement has one shape in any file
+const MIN_MATCHED = 8;     // statements in order, in one place
+const MIN_SHARE = 0.7;     // of the statements in that stretch of the write
+const COMMON = 0.04;       // of the files: a statement this common says nothing
+const CANDIDATES = 3;
+
+const hashOf = (s) => createHash('sha1').update(s).digest('hex').slice(0, 10);
+
+export function fingerprint(text, ext) {
+  const lang = languageOf(ext);
+  if (!lang) return [];
+  return statementsOf(text, lang).filter((s) => s.tokens.length >= MIN_STATEMENT).map((s) => [hashOf(s.shape), s.line]);
+}
+
+export function definesOf(text, ext) {
+  const lang = languageOf(ext);
+  if (!lang?.define) return [];
+  const code = 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);
+}
+
+// The longest common subsequence of two lists of hashes, as pairs of indexes.
+function matchedPairs(a, b) {
+  const w = b.length + 1;
+  const t = new Uint16Array((a.length + 1) * w);
+  for (let i = a.length - 1; i >= 0; i -= 1) {
+    for (let j = b.length - 1; j >= 0; j -= 1) t[i * w + j] = a[i] === b[j] ? t[(i + 1) * w + j + 1] + 1 : Math.max(t[(i + 1) * w + j], t[i * w + j + 1]);
+  }
+  const out = [];
+  for (let i = 0, j = 0; i < a.length && j < b.length;) {
+    if (a[i] === b[j]) { out.push([i, j]); i += 1; j += 1; } else if (t[(i + 1) * w + j] >= t[i * w + j + 1]) i += 1; else j += 1;
+  }
+  return out;
+}
+
+// The densest stretch of pairs: most of the statements on both sides are matched.
+function densest(pairs) {
+  let best = null;
+  for (let s = 0; s < pairs.length; s += 1) {
+    for (let e = pairs.length - 1; e >= s + MIN_MATCHED - 1; e -= 1) {
+      const n = e - s + 1;
+      const spanA = pairs[e][0] - pairs[s][0] + 1;
+      const spanB = pairs[e][1] - pairs[s][1] + 1;
+      if (n / spanA >= MIN_SHARE && n / spanB >= MIN_SHARE) { if (!best || n > best.n) best = { s, e, n, spanA }; break; }
+    }
+  }
+  return best;
+}
+
+// others: [{ file, st: [[hash, line]] }]. `added`: the statements this write adds, in order.
+export function nearCopy(added, others) {
+  if (added.length < MIN_MATCHED) return null;
+  const seen = new Map();
+  for (const o of others) for (const h of new Set(o.st.map(([x]) => x))) seen.set(h, (seen.get(h) ?? 0) + 1);
+  const limit = Math.max(4, others.length * COMMON);
+  const rare = (list) => list.filter(([h]) => (seen.get(h) ?? 0) <= limit);
+  const mine = rare(added);
+  const wanted = new Set(mine.map(([h]) => h));
+  const ranked = others.map((o) => ({ o, hits: new Set(o.st.map(([h]) => h).filter((h) => wanted.has(h))).size })).filter((c) => c.hits >= MIN_MATCHED).sort((a, b) => b.hits - a.hits).slice(0, CANDIDATES);
+  for (const { o } of ranked) {
+    const theirs = rare(o.st);
+    const pairs = matchedPairs(mine.map(([h]) => h), theirs.map(([h]) => h));
+    const d = densest(pairs);
+    if (d) return { file: o.file, from: theirs[pairs[d.s][1]][1], to: theirs[pairs[d.e][1]][1], line: mine[pairs[d.s][0]][1], matched: d.n, of: d.spanA };
+  }
+  return null;
+}

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

@@ -0,0 +1,196 @@
+// program-read: a small reader of an inline program (python, node, perl, ruby) for program-writes.mjs (KWB-8). It never
+// runs the program; it reads string literals, splits statements, and evaluates the simple expressions a file-writing
+// program uses (a literal, a variable, Path(...) and joins, a file's text read, .replace chains, + of strings).
+//   scan(code, lang) -> { code, lits }   code: the program with every literal replaced by \x01n\x02 and comments blanked;
+//                                        lits[n]: its text, or null when it interpolates (f-string, ${}, "$x")
+//   statements(code) -> [string]         split at newlines and ; outside brackets
+//   splitArgs(text) -> [string]          top-level comma split of a call's arguments
+//   closeOf(text, open) -> index         the bracket that closes text[open]
+//   evaluate(expr, ctx) -> value | null  value: { t: 'str'|'path', v }; ctx: { env, lang, at, readText }
+const PAIRS = { '(': ')', '[': ']', '{': '}' };
+
+function unescape(s, lang) {
+  return s.replace(/\\(\n|x[0-9a-fA-F]{2}|u[0-9a-fA-F]{4}|.)/gs, (m, e) => {
+    if (e === '\n') return '';
+    if (e[0] === 'x' && e.length === 3) return String.fromCharCode(parseInt(e.slice(1), 16));
+    if (e[0] === 'u' && e.length === 5) return String.fromCharCode(parseInt(e.slice(1), 16));
+    const map = { n: '\n', t: '\t', r: '\r', 0: '\0', '\\': '\\', "'": "'", '"': '"', '`': '`', $: '$' };
+    if (e in map) return map[e];
+    return lang === 'python' ? m : e;
+  });
+}
+
+export function scan(src, lang) {
+  const lits = [];
+  let out = '';
+  let i = 0;
+  const hash = lang !== 'node';
+  while (i < src.length) {
+    const c = src[i];
+    if ((hash && c === '#') || (!hash && c === '/' && src[i + 1] === '/')) {
+      while (i < src.length && src[i] !== '\n') i += 1;
+      continue;
+    }
+    if (!hash && c === '/' && src[i + 1] === '*') { const j = src.indexOf('*/', i + 2); i = j < 0 ? src.length : j + 2; continue; }
+    let pre = '';
+    if (lang === 'python') pre = src.slice(i).match(/^[rRbBuUfF]{0,2}(?=['"])/)?.[0] ?? '';
+    if (pre && /\w/.test(src[i - 1] ?? '')) pre = '';
+    const q0 = src[i + pre.length];
+    const quote = q0 === "'" || q0 === '"' || (q0 === '`' && lang === 'node') ? q0 : null;
+    if (!quote || (pre === '' && /\w/.test(src[i - 1] ?? '') && lang === 'python')) { out += c; i += 1; continue; }
+    const start = i + pre.length;
+    const triple = lang === 'python' && src.startsWith(quote.repeat(3), start);
+    const open = triple ? 3 : 1;
+    let j = start + open;
+    while (j < src.length && !(triple ? src.startsWith(quote.repeat(3), j) : src[j] === quote) && (triple || quote === '`' || src[j] !== '\n')) j += src[j] === '\\' ? 2 : 1;
+    const raw = src.slice(start + open, j);
+    i = Math.min(src.length, j + open);
+    const rawFlag = /[rR]/.test(pre);
+    let v;
+    if (/[fF]/.test(pre) && /[{}]/.test(raw)) v = null;
+    else if (quote === '`' && raw.includes('${')) v = null;
+    else if ((lang === 'perl' || lang === 'ruby') && quote === '"' && /[$@]|#\{/.test(raw)) v = null;
+    else if ((lang === 'perl' || lang === 'ruby') && quote === "'") v = raw.replace(/\\([\\'])/g, '$1');
+    else v = rawFlag ? raw : unescape(raw, lang);
+    out += `\x01${lits.length}\x02`;
+    lits.push(v);
+  }
+  return { code: out, lits };
+}
+
+export function closeOf(text, open) {
+  const want = PAIRS[text[open]];
+  let depth = 0;
+  for (let k = open; k < text.length; k += 1) {
+    if (PAIRS[text[k]]) depth += 1;
+    else if (')]}'.includes(text[k])) { depth -= 1; if (depth === 0) return text[k] === want ? k : -1; }
+  }
+  return -1;
+}
+
+function splitTop(text, seps) {
+  const out = [];
+  let depth = 0;
+  let cur = '';
+  for (const c of text) {
+    if (PAIRS[c]) depth += 1;
+    else if (')]}'.includes(c)) depth -= 1;
+    if (depth <= 0 && seps.includes(c)) { out.push(cur); cur = ''; } else cur += c;
+  }
+  out.push(cur);
+  return out;
+}
+
+export const statements = (code) => splitTop(code, '\n;').map((s) => s.trim()).filter(Boolean);
+export const splitArgs = (text) => (text.trim() ? splitTop(text, ',').map((s) => s.trim()) : []);
+
+// A postfix chain: a primary (a literal, a name, a parenthesised expression) and its .name, (args) and [index] steps.
+function chain(expr) {
+  let k = 0;
+  let primary;
+  const lit = expr.match(/^\x01(\d+)\x02/);
+  const name = expr.match(/^[A-Za-z_$][\w$]*/);
+  if (lit) { primary = { lit: Number(lit[1]) }; k = lit[0].length; }
+  else if (expr[0] === '(') { const e = closeOf(expr, 0); if (e < 0) return null; primary = { group: expr.slice(1, e) }; k = e + 1; }
+  else if (name) { primary = { name: name[0] }; k = name[0].length; }
+  else return null;
+  const steps = [];
+  while (k < expr.length) {
+    const rest = expr.slice(k);
+    const dot = rest.match(/^\s*(?:\.|->|::)\s*([A-Za-z_$][\w$]*)/);
+    if (dot) { steps.push({ name: dot[1] }); k += dot[0].length; continue; }
+    const ws = rest.match(/^\s*/)[0].length;
+    if (rest[ws] === '(' || rest[ws] === '[') {
+      const e = closeOf(expr, k + ws);
+      if (e < 0) return null;
+      steps.push(rest[ws] === '(' ? { args: splitArgs(expr.slice(k + ws + 1, e)) } : { index: expr.slice(k + ws + 1, e) });
+      k = e + 1;
+      continue;
+    }
+    return null;
+  }
+  return { primary, steps };
+}
+
+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), ''));
+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$/;
+
+export function evaluate(expr, ctx) {
+  const e = expr.trim().replace(/^await\s+/, '');
+  if (!e) return null;
+  const plus = splitTop(e, '+');
+  if (plus.length > 1 && ctx.lang !== 'perl') {
+    const vs = plus.map((p) => str(evaluate(p, ctx)));
+    return vs.some((v) => v === null) ? null : { t: 'str', v: vs.join('') };
+  }
+  if (ctx.lang === 'python') {
+    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;
+    }
+  }
+  const c = chain(e);
+  if (!c) return null;
+  // callee: the dotted name while the chain is still a plain name (os.path.join, p.read_text); recv: the value before its last dot
+  let cur = null;
+  let callee = null;
+  let recv = null;
+  let method = null;
+  if (c.primary.lit !== undefined) cur = ctx.lits[c.primary.lit] === null ? null : { t: 'str', v: ctx.lits[c.primary.lit] };
+  else if (c.primary.group !== undefined) cur = evaluate(c.primary.group, ctx);
+  else { callee = c.primary.name; cur = ctx.env.get(callee) ?? null; }
+  for (const s of c.steps) {
+    if (s.name !== undefined) {
+      if (callee !== null) { recv = cur; callee = `${callee}.${s.name}`; cur = ctx.env.get(callee) ?? null; } else { method = s.name; }
+      continue;
+    }
+    if (s.args) {
+      if (callee !== null) {
+        const last = callee.split('.').pop();
+        cur = callFn(callee, s.args, ctx) ?? (recv && callee.includes('.') ? callMethod(recv, last, s.args, ctx) : null);
+        callee = null;
+      } else cur = method && cur ? callMethod(cur, method, s.args, ctx) : null;
+      method = null;
+      recv = null;
+      continue;
+    }
+    cur = null; callee = null; method = null;
+  }
+  return method ? null : cur;
+}
+
+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 (READS.test(name) || /^(?:io\.|codecs\.)?open$/.test(name)) {
+    const p = str(vs[0]);
+    if (p === null) return null;
+    ctx.reads?.add(ctx.at(p));
+    return READS.test(name) ? { t: 'str', v: ctx.readText(ctx.at(p)) ?? '' } : { t: 'file', v: p };
+  }
+  return null;
+}
+
+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 === '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)) ?? '' };
+  }
+  if ((m === 'replace' || m === 'replaceAll') && base.t === 'str') {
+    const [a, b] = vs.map(str);
+    if (a === null || b === null || /^\//.test(args[0] ?? '')) return null;
+    if (m === 'replace' && ctx.lang === 'node') return { t: 'str', v: base.v.replace(a, () => b) };
+    const n = vs[2] ? Number(str(vs[2]) ?? args[2]) : -1;
+    if (!(n < 0)) { let out = base.v; for (let k = 0; k < n && out.includes(a); k += 1) out = out.replace(a, () => b); return { t: 'str', v: out }; }
+    return { t: 'str', v: base.v.split(a).join(b) };
+  }
+  return null;
+}

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

@@ -0,0 +1,177 @@
+// program-writes: the files an inline program writes (KWB-8: `python3 - <<EOF ... open(p,'w').write(...)` got past every
+// write-time hook; the shell reader saw redirects, tee, sed -i, cp and heredocs, not a program's own writes).
+//   programOf(exe, args, stdin) -> { lang, code } | null
+//     an interpreter given its program inline: python -c / python - or python with a heredoc on stdin; node -e / -p /
+//     node - or a heredoc; perl -e / -E (or a heredoc); ruby -e (or a heredoc). A script file (python3 tools/x.py,
+//     node tools/x.mjs, python3 -m mod) is null: it is the project's own tool, reviewed like code, not judged as a write.
+//   programWrites(program, at, readText) -> [{ path, op, content, from? }]   (op and content as in shell-writes.mjs)
+//     a write is a call that opens or makes a file for writing: python open(p, 'w'|'a'|'x'|'r+'), Path.write_text /
+//     write_bytes / touch / unlink, shutil.copy* / move / copytree / rmtree, os.remove / rename / replace; node
+//     fs.writeFileSync / appendFileSync / copyFileSync / cpSync / renameSync / rmSync / unlinkSync / createWriteStream;
+//     perl open(FH, '>' ...), rename, unlink, File::Copy; ruby File.write / File.open(p, 'w') / FileUtils.*.
+//     A read (open(p), open(p, 'r'), read_text, readFileSync) is never a write. content is the new text where the
+//     program says it (a literal, or a file's text read and .replace'd, in a program with no loop or branch), else null.
+//     A write whose path the reader cannot work out makes every path the program names (its path-like literals, less
+//     the ones it only reads) a write of unknown content, so the path-based hooks still judge it.
+import { basename, join } from 'node:path';
+import { statSync } from 'node:fs';
+import { closeOf, evaluate, scan, splitArgs, statements } from './program-read.mjs';
+
+const isDir = (p) => { try { return statSync(p).isDirectory(); } catch { return false; } };
+
+export function programOf(exe, args, stdin) {
+  const lang = /^python(\d+(\.\d+)*)?$|^pypy3?$/.test(exe) ? 'python' : /^(node|nodejs|bun)$/.test(exe) ? 'node' : exe === 'perl' ? 'perl' : exe === 'ruby' ? 'ruby' : null;
+  if (!lang) return null;
+  const inline = { python: /^-[A-Za-z]*c$/, node: /^(-e|--eval|-p|--print|-pe)$/, perl: /^-[A-Za-z]*[eE]$/, ruby: /^-[A-Za-z]*e$/ }[lang];
+  const takesValue = { python: /^-[WXQ]$/, node: /^(-r|--require|--import|--loader|--experimental-loader|-C|--conditions)$/, perl: /^-[IMx]$/, ruby: /^-[Ir]$/ }[lang];
+  const code = [];
+  for (let k = 0; k < args.length; k += 1) {
+    const a = args[k];
+    if (inline.test(a)) { if (args[k + 1] !== undefined) code.push(args[k + 1]); k += 1; if (lang === 'python') break; continue; }
+    if (lang === 'node' && /^--(eval|print)=/.test(a)) { code.push(a.slice(a.indexOf('=') + 1)); continue; }
+    if (lang === 'python' && /^-[A-Za-z]*m$/.test(a)) return null;
+    if (takesValue.test(a)) { k += 1; continue; }
+    if (a.startsWith('-') && a !== '-') continue;
+    if (code.length) break;
+    return a === '-' && stdin !== null ? { lang, code: stdin } : null;
+  }
+  if (code.length) return { lang, code: code.join('\n') };
+  return stdin !== null && stdin !== undefined ? { lang, code: stdin } : null;
+}
+
+// The receiver of a method call: the postfix expression that ends just before text[dot].
+function receiverBefore(text, dot) {
+  let k = dot - 1;
+  while (k >= 0) {
+    const c = text[k];
+    if (c === ')' || c === ']') {
+      const open = c === ')' ? '(' : '[';
+      let depth = 0;
+      for (; k >= 0; k -= 1) { if (text[k] === c) depth += 1; else if (text[k] === open && --depth === 0) break; }
+      k -= 1;
+    } else if (c === '\x02') k = text.lastIndexOf('\x01', k) - 1;
+    else if (/[\w$.]/.test(c)) k -= 1;
+    else break;
+  }
+  return text.slice(k + 1, dot);
+}
+
+const modeOp = (m) => (m === null ? 'write' : /^\+?>>|a/.test(m) ? 'append' : /^\+</.test(m) || /r\+/.test(m) ? 'edit' : /[wx>]|\+/.test(m) ? 'write' : null);
+
+const SITES = {
+  python: /(?<![\w.])(?:io\.|codecs\.)?open\s*\(|\.(open|write_text|write_bytes|touch|unlink|rmdir)\s*\(|\bshutil\.(copy|copy2|copyfile|move|copytree|rmtree)\s*\(|\bos\.(remove|unlink|rename|replace)\s*\(/g,
+  node: /\b(writeFileSync|writeFile|appendFileSync|appendFile|copyFileSync|copyFile|cpSync|renameSync|rmSync|unlinkSync|createWriteStream|truncateSync|openSync|outputFileSync)\s*\(|\bBun\.(write)\s*\(/g,
+  perl: /\bopen\s*(?=[\s(])|\b(rename|unlink|copy|move)\s*\(/g,
+  ruby: /\b(?:File|IO)\.(write|binwrite|open|rename|delete|unlink)\s*\(|\bFileUtils\.(cp|copy|mv|move|rm|rm_f|rm_rf|touch|install)\s*\(/g,
+};
+
+const COPY = /^(copy|copy2|copyfile|copyFileSync|copyFile|cp|install)$/;
+const MOVE = /^(move|rename|replace|renameSync|mv)$/;
+const DELETE = /^(rmtree|remove|unlink|rmdir|rmSync|unlinkSync|delete|rm|rm_f|rm_rf)$/;
+
+export function programWrites({ lang, code: src }, at, readText) {
+  const { code, lits } = scan(src, lang);
+  const stmts = statements(code);
+  const branchy = /\b(for|while|foreach|until|unless|lambda|function|each|map|if|elif|else|try|switch|case|def)\b|=>|\bdo\b/.test(code);
+  const ASSIGN = /^(?:(?:const|let|var|my|our)\s+)?([$@%]?[A-Za-z_][\w.]*)\s*(\+?)=(?!=)\s*([\s\S]+)$/;
+  const count = new Map();
+  for (const s of stmts) { const m = s.match(ASSIGN); if (m) count.set(m[1], (count.get(m[1]) ?? 0) + 1); }
+  const env = new Map();
+  const reads = new Set();
+  const ctx = { env, lits, lang, at, readText, reads };
+  const val = (e) => (e === undefined ? null : evaluate(e, ctx));
+  const pathOf = (e) => { const v = val(e); return v && (v.t === 'str' || v.t === 'path') && v.v ? at(v.v) : null; };
+  const textOf = (e) => { const v = val(e); return !branchy && v && v.t === 'str' ? v.v : null; };
+  const out = [];
+  const handles = new Map();
+  let unresolved = false;
+  const add = (path, op, content, extra = {}) => { if (path === null) unresolved = true; else out.push({ path, op, content, ...extra }); return out.at(-1); };
+  const kw = (args, name) => args.find((a) => new RegExp(`^${name}\\s*=`).test(a))?.replace(/^\w+\s*=\s*/, '');
+  const modeArg = (e) => (e === undefined ? undefined : val(e)?.t === 'str' ? val(e).v : null);
+
+  for (const s of stmts) {
+    for (const m of s.matchAll(SITES[lang])) {
+      const name = m.slice(1).find(Boolean) ?? 'open';
+      const paren = s.indexOf('(', m.index + m[0].length - 1);
+      let args;
+      let end;
+      if (lang === 'perl' && name === 'open' && s[paren] !== '(' ) {
+        const rest = s.slice(m.index + m[0].length).split(/\s+(?:or|\|\|)\s+|\s+or$/)[0];
+        args = splitArgs(rest.replace(/^\s*\(|\)\s*$/g, ''));
+        end = s.length;
+      } else {
+        end = closeOf(s, paren);
+        if (end < 0) continue;
+        args = splitArgs(s.slice(paren + 1, end));
+      }
+      const pos = args.filter((a) => !/^\w+\s*=[^=]/.test(a));
+      const method = m[0].startsWith('.');
+      const recv = method ? receiverBefore(s, m.index) : null;
+      let site = null;
+      if (lang === 'perl' && name === 'open') {
+        const mode = pos.length >= 3 ? modeArg(pos[1]) : modeArg(pos[1]);
+        if (pos.length >= 3) { const op = modeOp(mode); if (op) site = add(pathOf(pos[2]), op, null); } else if (mode !== null && mode !== undefined) {
+          const two = mode.match(/^\s*(\+?[<>]{1,2}|\|)?\s*(.*)$/);
+          const op = two[1] && two[1] !== '|' ? modeOp(two[1]) : null;
+          if (op) site = add(two[2] ? at(two[2]) : null, op, null);
+        } else if (pos[1] !== undefined) site = add(null, 'write', null);
+      } else if (name === 'open' || name === 'openSync') {
+        if (method && val(recv)?.t !== 'path') continue;
+        const target = method ? recv : pos[0];
+        const mode = modeArg(method ? pos[0] ?? kw(args, 'mode') : pos[1] ?? kw(args, 'mode'));
+        const op = mode === undefined ? null : modeOp(mode);
+        if (!op) { const p = pathOf(target); if (p) reads.add(p); continue; }
+        site = add(pathOf(target), op, op === 'edit' ? null : '');
+        const after = s.slice(end + 1);
+        const chained = after.match(/^\s*\.\s*write\s*\(/);
+        const as = after.match(/^\s*as\s+([A-Za-z_]\w*)/) ?? s.slice(0, m.index).match(/^([A-Za-z_]\w*)\s*=\s*$/);
+        if (site && chained) { const e = closeOf(after, after.indexOf('(')); site.content = e < 0 ? null : textOf(after.slice(after.indexOf('(') + 1, e)); }
+        else if (site && as) handles.set(as[1], { site, parts: [], ok: !branchy && site.content !== null, uses: 0 });
+        else if (site) site.content = null;
+      } else if (name === 'write_text' || name === 'write' || name === 'binwrite' || /^(writeFile|outputFile)/.test(name) || /^appendFile/.test(name)) {
+        const target = method ? recv : pos[0];
+        site = add(pathOf(target), /^append/.test(name) ? 'append' : 'write', name === 'binwrite' ? null : textOf(method ? pos[0] : pos[1]));
+      } else if (name === 'write_bytes' || name === 'createWriteStream' || name === 'truncateSync') site = add(pathOf(method ? recv : pos[0]), name === 'truncateSync' ? 'truncate' : 'write', null);
+      else if (name === 'touch') site = add(pathOf(method ? recv : pos[0]), 'touch', null);
+      else if (DELETE.test(name)) { if (method && val(recv)?.t !== 'path') continue; for (const a of method ? [recv] : pos.slice(0, lang === 'ruby' ? pos.length : 1)) add(pathOf(a), 'delete', null); }
+      else if (COPY.test(name) || MOVE.test(name) || /^(copytree|cpSync)$/.test(name)) {
+        if (method) continue;
+        const from = pathOf(pos[0]);
+        let to = pathOf(pos[1]);
+        if (to && from && isDir(to) && !/^(copytree|cpSync)$/.test(name)) to = join(to, basename(from));
+        const tree = /^(copytree|cpSync)$/.test(name);
+        add(to, MOVE.test(name) ? 'move' : 'copy', tree || !from ? null : readText(from), from ? { from } : {});
+        if (MOVE.test(name)) add(from, 'delete', null);
+      }
+    }
+    for (const [h, rec] of handles) {
+      for (const m of s.matchAll(new RegExp(`(?<![\\w.])${h.replace(/\$/g, '\\$')}\\b`, 'g'))) {
+        rec.uses += 1;
+        const after = s.slice(m.index + h.length);
+        const w = after.match(/^\s*\.\s*(write|close)\s*\(/);
+        if (!w) continue;
+        rec.uses -= 1;
+        if (w[1] === 'close') continue;
+        const open = m.index + h.length + after.indexOf('(');
+        const e = closeOf(s, open);
+        const t = e < 0 ? null : textOf(s.slice(open + 1, e));
+        if (t === null) rec.ok = false; else rec.parts.push(t);
+      }
+    }
+    const a = s.match(ASSIGN);
+    if (a) {
+      const v = branchy && count.get(a[1]) > 1 ? null : a[2] ? ((x, y) => (x?.t === 'str' && y?.t === 'str' ? { t: 'str', v: x.v + y.v } : null))(env.get(a[1]), val(a[3])) : val(a[3]);
+      if (v) env.set(a[1], v); else env.delete(a[1]);
+    }
+  }
+  for (const rec of handles.values()) rec.site.content = rec.ok && rec.uses <= 1 ? rec.parts.join('') : null;
+  if (unresolved) {
+    const named = new Set(out.map((w) => w.path));
+    for (const l of lits) {
+      if (l === null || l.length > 300 || !/^[~\w.@+\-/]+$/.test(l) || /^[-.]+$|^-|^\d+(\.\d+)*$/.test(l) || !(l.includes('/') || /\.[A-Za-z][A-Za-z0-9]{0,7}$/.test(l))) continue;
+      const p = at(l);
+      if (!named.has(p) && !reads.has(p)) { named.add(p); out.push({ path: p, op: 'write', content: null, named: true }); }
+    }
+  }
+  return out;
+}

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

@@ -0,0 +1,81 @@
+// Every project hook judges only this project's own files. Claude regularly edits sibling
+// projects from one session (rolling a lesson out to every project), and those edits must never be
+// blocked by this project's laws; the other project's own hooks govern it there.
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+
+export const ROOT = resolve(process.env.CLAUDE_PROJECT_DIR ?? process.cwd());
+
+export function insideProject(path, base = process.cwd()) {
+  if (!path) return false;
+  const rel = relative(ROOT, resolve(base, path));
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+
+// True when a shell command moves to another folder outside this project (cd, pushd, git -C,
+// make -C), so its relative paths are not ours to judge.
+export function commandLeavesProject(command = '') {
+  for (const m of command.matchAll(/(?:^|[;&|]\s*|\s)(?:cd|pushd)\s+(['"]?)([^\s;&|'"]+)\1/g)) if (!insideProject(m[2].replace(/^~(?=\/)/, process.env.HOME ?? '~'))) return true;
+  for (const m of command.matchAll(/\b(?:git|make|ninja|cmake)\s+(?:--build\s+)?-C\s+(['"]?)([^\s;&|'"]+)\1/g)) if (!insideProject(m[2])) return true;
+  return false;
+}
+
+// The checkout a file belongs to: the project itself, or a git worktree of it. Agents work in
+// worktrees under .claude/worktrees/, and CLAUDE_PROJECT_DIR still points at the main checkout there,
+// so judging a worktree file against ROOT made every path look misplaced (Stellix WB-41 and WB-55:
+// agents routed new code into unrelated files for days). Every hook measures paths and reads
+// layout.json from this root.
+// Only a worktree of THIS repo counts: a `.git` file whose gitdir lies in this repo's worktrees/.
+// Any other nested `.git` (FetchContent's JUCE clone under build/_deps, a vendored repo, a
+// submodule) is part of the project and judged by it; stopping there let an edit inside
+// build/_deps/juce-src escape protect-vendor (Sub37 WB-2).
+const real = (p) => { try { return realpathSync(p); } catch { return resolve(p); } };
+
+function commonGitDir(root) {
+  const dotGit = resolve(root, '.git');
+  try {
+    if (statSync(dotGit).isDirectory()) return real(dotGit);
+    const gitdir = resolve(root, readFileSync(dotGit, 'utf8').match(/^gitdir:\s*(.+)$/m)[1].trim());
+    const common = resolve(gitdir, existsSync(resolve(gitdir, 'commondir')) ? readFileSync(resolve(gitdir, 'commondir'), 'utf8').trim() : '.');
+    return real(common);
+  } catch {
+    return null;
+  }
+}
+
+export function isWorktreeOfProject(dir) {
+  const dotGit = resolve(dir, '.git');
+  try {
+    if (!statSync(dotGit).isFile()) return false;
+    const gitdir = real(resolve(dir, readFileSync(dotGit, 'utf8').match(/^gitdir:\s*(.+)$/m)[1].trim()));
+    const common = commonGitDir(ROOT);
+    return common !== null && gitdir.startsWith(`${common}/worktrees/`);
+  } catch {
+    return false;
+  }
+}
+
+export function checkoutRoot(file) {
+  if (!file) return ROOT;
+  let dir = dirname(resolve(process.cwd(), file));
+  for (;;) {
+    if (dir === ROOT) return ROOT; // a project that is not a git repo is never judged from a parent repo
+    if (isWorktreeOfProject(dir)) return dir;
+    const up = dirname(dir);
+    if (up === dir) return ROOT;
+    dir = up;
+  }
+}
+
+// The folder whose .claude/ (layout.json, checks, locks) governs a file: its own checkout when that
+// checkout carries a layout.json, else the main project. A worktree branch that moved a folder or
+// added a check is judged by its own copy; a worktree without one still gets the main laws.
+export function claudeRoot(file) {
+  const root = checkoutRoot(file);
+  return existsSync(resolve(root, '.claude', 'layout.json')) ? root : ROOT;
+}
+
+// A path relative to its own checkout, with forward slashes.
+export function relInCheckout(file) {
+  return relative(checkoutRoot(file), resolve(process.cwd(), file)).replace(/\\/g, '/');
+}