@thedecipherist/claude-packs 0.0.0-stage → 1.0.0

package/global/hooks/lib/shell-writes.mjs

@@ -0,0 +1,293 @@
+// shell-writes: the files a shell command writes, and what it writes into them where that can be known.
+// Every guard that refuses a write judges the shell's writes through this, so no guard has a route the
+// Write tool lacks (WB-69: a guard covered Write and Edit while `cat > file <<EOF` walked past it).
+//
+//   shellWrites(command, cwd) -> [{ path, op, content, from?, sed? }]
+//     op: write (>, >|, &>, tee), append (>>, &>>, tee -a), copy (cp, install, rsync), move (mv; its source
+//         is a delete), link (ln), edit (sed -i, perl -i, ruby -i), truncate, touch, delete (rm, unlink, shred, mv's source)
+//     and an inline program's own writes (python -c / python - <<EOF, node -e, perl -e, ruby -e: program-writes.mjs,
+//         KWB-8); a script file run by an interpreter (python3 tools/x.py) is the project's own tool, not a write.
+//     content: the text written (an echo or printf, a heredoc or here-string, a cat of known files, what a pipe
+//         carries into tee, the source of a cp or mv), or null when it cannot be known.
+//   afterText(write) -> { before, after }   after is null when it cannot be known; sed -i is run for real on a
+//         copy of the text, in GNU sed's --sandbox (no e, r or w commands), so its result is exact.
+//   `node shell-writes.mjs --json` reads { command, cwd } on stdin and prints the writes with before and after
+//   (the python hooks use this, so there is one reader of the shell). `--selftest`: each route and program form.
+// Text inside quotes, and a heredoc's body, is never read as a command.
+import { spawnSync } from 'node:child_process';
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { programOf, programWrites } from './program-writes.mjs';
+
+const HOME = process.env.HOME ?? '';
+// A path that starts with a variable is where that variable points, never a folder of this name in the project (KWB-44). One not set is somewhere unknown.
+const expand = (p) => p.replace(/^(~|\$HOME|\$\{HOME\})(?=\/|$)/, HOME).replace(/^\$\{?([A-Za-z_]\w*)\}?(?=\/|$)/, (_, name) => process.env[name] ?? `/unresolved-${name}`);
+const NOT_FILES = new Set(['/dev/null', '/dev/stdout', '/dev/stderr', '/dev/tty']);
+
+export function readText(path) {
+  try {
+    const st = statSync(path);
+    if (!st.isFile() || st.size > 8 * 1024 * 1024) return null;
+    return readFileSync(path, 'utf8');
+  } catch {
+    return null;
+  }
+}
+const isDir = (p) => { try { return statSync(p).isDirectory(); } catch { return false; } };
+
+// Heredoc bodies are cut out of the command and kept, in order, for the command that reads them.
+function cutHeredocs(command) {
+  const lines = command.split('\n');
+  const out = [];
+  const bodies = [];
+  const MARK = /(?<!<)<<(?!<)(-?)\s*(['"]?)([A-Za-z_][\w-]*)\2/g;
+  for (let i = 0; i < lines.length; i += 1) {
+    const marks = [...lines[i].matchAll(MARK)];
+    let n = bodies.length;
+    out.push(lines[i].replace(MARK, () => ` <<HEREDOC${n++} `));
+    for (const m of marks) {
+      const body = [];
+      const end = (l) => (m[1] ? l.replace(/^\t+/, '') : l) === m[3];
+      while (i + 1 < lines.length && !end(lines[i + 1])) body.push(m[1] ? lines[++i].replace(/^\t+/, '') : lines[++i]);
+      i += 1;
+      bodies.push(body.length ? `${body.join('\n')}\n` : '');
+    }
+  }
+  return { text: out.join('\n'), bodies };
+}
+
+// Words and operators, quotes removed from words; a heredoc is its marker word.
+function lex(text) {
+  const tokens = [];
+  let cur = null;
+  let i = 0;
+  const push = () => { if (cur !== null) tokens.push({ w: cur }); cur = null; };
+  while (i < text.length) {
+    const c = text[i];
+    if (c === "'") {
+      const j = text.indexOf("'", i + 1);
+      cur = (cur ?? '') + text.slice(i + 1, j < 0 ? text.length : j);
+      i = j < 0 ? text.length : j + 1;
+      continue;
+    }
+    if (c === '"') {
+      let j = i + 1;
+      let s = '';
+      while (j < text.length && text[j] !== '"') {
+        if (text[j] === '\\' && j + 1 < text.length && '"\\$`'.includes(text[j + 1])) { s += text[j + 1]; j += 2; } else s += text[j++];
+      }
+      cur = (cur ?? '') + s;
+      i = j + 1;
+      continue;
+    }
+    if (c === '\\' && i + 1 < text.length) {
+      if (text[i + 1] !== '\n') cur = (cur ?? '') + text[i + 1];
+      i += 2;
+      continue;
+    }
+    if (c === '\n') { push(); tokens.push({ op: ';' }); i += 1; continue; }
+    if (/\s/.test(c)) { push(); i += 1; continue; }
+    if (c === '#' && cur === null) { while (i < text.length && text[i] !== '\n') i += 1; continue; }
+    const rest = text.slice(i);
+    const redir = rest.match(/^(&>>|&>|>>|>\||>&\d*-?|>|<<<|<<HEREDOC(\d+)|<)/);
+    if (redir && (cur === null || /^\d+$/.test(cur))) {
+      const fd = cur ?? '';
+      cur = null;
+      tokens.push({ op: redir[2] !== undefined ? '<<' : redir[1].startsWith('>&') ? '>&' : redir[1], fd, doc: redir[2] !== undefined ? Number(redir[2]) : undefined });
+      i += redir[0].length;
+      continue;
+    }
+    const ctl = rest.match(/^(&&|\|\||\|&|\||;|&|\(|\)|`|\$\()/);
+    if (ctl) { push(); tokens.push({ op: ctl[1] === '|&' ? '|' : ctl[1] }); i += ctl[1].length; continue; }
+    cur = (cur ?? '') + c;
+    i += 1;
+  }
+  push();
+  return tokens;
+}
+
+const PREFIX = new Set(['sudo', 'env', 'command', 'builtin', 'nohup', 'time', 'exec', 'nice']);
+
+function printf(args) {
+  if (!args.length) return '';
+  const esc = (s) => s.replace(/\\n/g, '\n').replace(/\\t/g, '\t').replace(/\\\\/g, '\\');
+  const [fmt, ...vals] = args;
+  const slots = (fmt.match(/%[sdbq]/g) ?? []).length;
+  if (!slots) return esc(fmt);
+  let out = '';
+  let k = 0;
+  do {
+    out += esc(fmt).replace(/%[sdbq]/g, () => vals[k++] ?? '');
+  } while (k < vals.length);
+  return out;
+}
+
+// One simple command: its words, redirections and stdin, and what it writes.
+function judge(cmd, cwd, stdin, writes, bodies) {
+  let words = [...cmd.words];
+  while (words.length && (PREFIX.has(words[0]) || /^[A-Za-z_]\w*=/.test(words[0]) || (words[0] === 'timeout' && words.length > 1))) words = words[0] === 'timeout' ? words.slice(2) : words.slice(1);
+  const at = (p) => resolve(cwd, expand(p));
+  let input = stdin;
+  for (const r of cmd.redirs) {
+    if (r.op === '<<') input = bodies[r.doc] ?? null;
+    else if (r.op === '<<<') input = `${r.target}\n`;
+    else if (r.op === '<') input = readText(at(r.target));
+  }
+  const exe = words.length ? basename(words[0]) : '';
+  const args = words.slice(1);
+  const flags = args.filter((a) => a.startsWith('-'));
+  const plain = args.filter((a) => !a.startsWith('-'));
+  let stdout = null;
+  if (exe === 'echo') {
+    const n = args[0] === '-n' || args[0] === '-ne' || args[0] === '-en';
+    const e = /^-[ne]*e/.test(args[0] ?? '');
+    const text = args.filter((a, k) => !(k === 0 && /^-[neE]+$/.test(a))).join(' ');
+    stdout = (e ? text.replace(/\\n/g, '\n').replace(/\\t/g, '\t') : text) + (n ? '' : '\n');
+  } else if (exe === 'printf') stdout = printf(args);
+  else if (exe === 'cat') stdout = plain.length ? plain.map((f) => readText(at(f))).reduce((a, b) => (a === null || b === null ? null : a + b), '') : input;
+  else if (exe === 'tee') stdout = input;
+  else if (exe === '' && cmd.redirs.some((r) => r.op === '<<' || r.op === '<<<')) stdout = input;
+  else if (exe === ':' || exe === 'true') stdout = '';
+
+  const add = (path, op, content, extra = {}) => { if (!NOT_FILES.has(path)) writes.push({ path, op, content, ...extra }); };
+  for (const r of cmd.redirs) {
+    if (!['>', '>>', '>|', '&>', '&>>'].includes(r.op) || !r.target) continue;
+    const toStdout = r.fd === '' || r.fd === '1' || r.op.startsWith('&');
+    add(at(r.target), r.op.includes('>>') ? 'append' : 'write', toStdout ? stdout : null);
+  }
+  if (exe === 'tee') for (const f of plain) add(at(f), flags.some((x) => /^-\w*a/.test(x) || x === '--append') ? 'append' : 'write', input);
+  if (['cp', 'mv', 'install', 'rsync', 'ln'].includes(exe)) {
+    const t = args.findIndex((a) => a === '-t' || a === '--target-directory');
+    const dirArg = t >= 0 ? args[t + 1] : null;
+    const files = plain.filter((a) => a !== dirArg && !(['install'].includes(exe) && /^\d{3,4}$/.test(a)));
+    const srcs = dirArg ? files : files.slice(0, -1);
+    const dest = dirArg ?? files.at(-1);
+    if (dest && srcs.length) {
+      for (const s of srcs) {
+        const into = dirArg || srcs.length > 1 || dest.endsWith('/') || isDir(at(dest));
+        const target = into ? join(at(dest), basename(s)) : at(dest);
+        const op = exe === 'mv' ? 'move' : exe === 'ln' ? 'link' : 'copy';
+        add(target, op, exe === 'ln' ? null : readText(at(s)), { from: at(s) });
+        if (exe === 'mv') add(at(s), 'delete', null);
+      }
+    }
+  }
+  if (exe === 'sed' && args.some((a) => a === '-i' || a.startsWith('-i') || a.startsWith('--in-place'))) {
+    const scripts = [];
+    const keep = [];
+    const files = [];
+    for (let k = 0; k < args.length; k += 1) {
+      const a = args[k];
+      if (a === '-i' && args[k + 1] === '') { k += 1; continue; } // BSD: -i ''
+      if (a === '-e' || a === '--expression') { scripts.push(args[++k]); continue; }
+      if (a.startsWith('--expression=')) { scripts.push(a.slice(13)); continue; }
+      if (a === '-f' || a === '--file') { scripts.push(null); k += 1; continue; }
+      if (/^-[^-]/.test(a)) { for (const f of a.slice(1).replace(/i.*$/, '')) if ('Ernsz'.includes(f)) keep.push(`-${f}`); continue; }
+      if (a.startsWith('--')) { if (['--regexp-extended', '--quiet', '--silent', '--separate', '--null-data'].includes(a)) keep.push(a); continue; }
+      if (!scripts.length) scripts.push(a); else files.push(a);
+    }
+    for (const f of files) add(at(f), 'edit', null, { sed: scripts.includes(null) ? null : { flags: keep, scripts } });
+  }
+  if ((exe === 'perl' || exe === 'ruby') && args.some((a) => /^-\w*i/.test(a))) {
+    const files = [];
+    for (let k = 0; k < args.length; k += 1) {
+      if (/^-\w*[eE]$/.test(args[k])) { k += 1; continue; } // -e, -pe, -ne: the next word is the program
+      if (!args[k].startsWith('-')) files.push(args[k]);
+    }
+    for (const f of files) add(at(f), 'edit', null);
+  }
+  const program = programOf(exe, args, input);
+  if (program) for (const w of programWrites(program, at, readText)) add(w.path, w.op, w.content, w.from ? { from: w.from } : {});
+  if (exe === 'dd') for (const a of args) if (a.startsWith('of=')) add(at(a.slice(3)), 'write', null);
+  if (exe === 'truncate') {
+    const k = args.findIndex((a) => a === '-s' || a.startsWith('--size'));
+    const size = k >= 0 ? (args[k].includes('=') ? args[k].split('=')[1] : args[k + 1]) : null;
+    for (const f of plain.filter((a) => a !== size)) add(at(f), 'truncate', size === '0' ? '' : null);
+  }
+  if (exe === 'touch') for (const f of plain) add(at(f), 'touch', null);
+  if (['rm', 'unlink', 'shred'].includes(exe)) for (const f of plain) add(at(f), 'delete', null);
+  return { stdout, cd: exe === 'cd' && plain[0] ? at(plain[0]) : null };
+}
+
+export function shellWrites(command = '', cwd = process.cwd()) {
+  const { text, bodies } = cutHeredocs(command);
+  const writes = [];
+  let here = cwd;
+  let cmd = { words: [], redirs: [] };
+  let pipeIn = null;
+  const tokens = lex(text);
+  // a variable set earlier in the command ("S=/tmp/x; cat > $S/a.md") names that folder, not "<cwd>/$S" (KWB-18); one never set
+  // stays as written
+  const vars = {};
+  const sub = (w) => w.replace(/\$(?:\{(\w+)\}|(\w+))/g, (m, a, b) => vars[a ?? b] ?? m);
+  const flush = () => {
+    if (cmd.words.length && !cmd.redirs.length && cmd.words.every((w) => /^[A-Za-z_]\w*=/.test(w))) {
+      for (const w of cmd.words) { const i = w.indexOf('='); vars[w.slice(0, i)] = sub(w.slice(i + 1)); }
+      cmd = { words: [], redirs: [] };
+      pipeIn = null;
+      return;
+    }
+    cmd = { words: cmd.words.map(sub), redirs: cmd.redirs.map((r) => (r.target === undefined ? r : { ...r, target: sub(r.target) })) };
+    if (cmd.words.length || cmd.redirs.length) {
+      const r = judge(cmd, here, pipeIn, writes, bodies);
+      if (r.cd) here = r.cd;
+      pipeIn = r.stdout;
+    } else pipeIn = null;
+    cmd = { words: [], redirs: [] };
+  };
+  for (let k = 0; k < tokens.length; k += 1) {
+    const t = tokens[k];
+    if (t.w !== undefined) { cmd.words.push(t.w); continue; }
+    if (['>', '>>', '>|', '&>', '&>>', '<', '<<<'].includes(t.op)) {
+      const next = tokens[k + 1];
+      if (next?.w !== undefined) { cmd.redirs.push({ op: t.op, fd: t.fd, target: next.w }); k += 1; }
+      continue;
+    }
+    if (t.op === '<<') { cmd.redirs.push({ op: '<<', doc: t.doc }); continue; }
+    if (t.op === '>&') continue;
+    if (t.op === '|') { flush(); continue; } // the next command reads this one's output
+    flush();
+    pipeIn = null;
+  }
+  flush();
+  return writes;
+}
+
+let gnuSed;
+function findGnuSed() {
+  if (gnuSed !== undefined) return gnuSed;
+  for (const s of ['/opt/homebrew/opt/gnu-sed/libexec/gnubin/sed', '/usr/local/opt/gnu-sed/libexec/gnubin/sed', 'gsed', 'sed']) {
+    const r = spawnSync(s, ['--version'], { encoding: 'utf8', timeout: 2000 });
+    if (r.status === 0 && /GNU sed/.test(r.stdout)) return (gnuSed = s);
+  }
+  return (gnuSed = null);
+}
+
+export function afterText(w, before = readText(w.path) ?? '') {
+  switch (w.op) {
+    case 'write': case 'copy': case 'move': case 'truncate': return { before, after: w.content };
+    case 'append': return { before, after: w.content === null ? null : before + w.content };
+    case 'touch': return { before, after: before };
+    case 'edit': {
+      const sed = w.sed && findGnuSed();
+      if (!sed) return { before, after: null };
+      const r = spawnSync(sed, ['--sandbox', ...w.sed.flags, ...w.sed.scripts.flatMap((s) => ['-e', s])], { input: before, encoding: 'utf8', timeout: 3000 });
+      return { before, after: r.status === 0 ? r.stdout : null };
+    }
+    default: return { before, after: null };
+  }
+}
+
+const direct = process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+if (direct && process.argv.includes('--selftest')) import('./shell-writes-selftest.mjs').then((m) => { process.exitCode = m.selftest(); });
+if (process.argv[1] && process.argv.includes('--json') && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+  let raw = '';
+  process.stdin.on('data', (c) => { raw += c; });
+  process.stdin.on('end', () => {
+    let q = {};
+    try { q = JSON.parse(raw || '{}'); } catch { /* nothing to read */ }
+    const out = shellWrites(q.command ?? '', q.cwd ?? process.cwd()).map((w) => ({ path: w.path, op: w.op, ...afterText(w) }));
+    process.stdout.write(JSON.stringify(out));
+  });
+}

package/global/hooks/shell-traps.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// shell-traps (PreToolUse, Bash; global by design): refuses the shell traps that cost time on this Mac, with the right form.
+//
+// "make a skill that triggers the moment you touch bash" (the skill: shell-rules). A skill is read only
+// when remembered; this hook sees every command. It refuses (exit 2):
+//   - BSD flags on the GNU tools first on PATH: `date -r <seconds>`, `stat -f`, `sed -i ''` (WB-23);
+//   - an in-place perl edit of a code file (apprack B-135: twice it wrote its text at the top of the file);
+//   - a `for` loop over an unquoted variable while the session runs zsh (the words are not split there, WB-41);
+//   - `;` chaining a destructive step (checkout --detach, rm -rf, kill) after another command (WB-19).
+// Text inside heredoc bodies and quoted strings is ignored.
+//   node shell-traps.mjs --selftest
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+
+export function noHeredocs(cmd) {
+  const out = [];
+  const lines = cmd.split('\n');
+  for (let i = 0; i < lines.length; i += 1) {
+    out.push(lines[i]);
+    const m = lines[i].match(/<<-?\s*['"]?(\w+)['"]?/);
+    if (m) { i += 1; while (i < lines.length && lines[i].trim() !== m[1]) i += 1; }
+  }
+  return out.join('\n');
+}
+
+const bodyOf = (cmd) => noHeredocs(cmd).replace(/'[^']*'|"(?:\\.|[^"\\])*"/g, "''");
+const zshSession = () => basename(process.env.SHELL ?? '').includes('zsh') && !(process.env.CLAUDE_CODE_SHELL ?? '').includes('bash');
+
+export function verdict(cmd, zsh = zshSession()) {
+  const b = bodyOf(cmd);
+  if (/(^|[\s;&|(])date\s+(-\w*\s+)*-r\s+\$?\(?[\d@$]/.test(b)) {
+    return "`date -r <seconds>` is the BSD form; here date is GNU (-r means a FILE's time). Use: date -d @<seconds> '+%Y-%m-%d %H:%M %Z'";
+  }
+  if (/(^|[\s;&|(])stat\s+(-\w+\s+)*-f\s/.test(b)) {
+    return '`stat -f` is the BSD form; here stat is GNU (-f is file-SYSTEM info). Use `stat -c %Y file`, or better Python os.stat for a measurement (WB-23).';
+  }
+  if (/(^|[\s;&|(])sed\s+-i\s+(''|"")(\s|$)/.test(noHeredocs(cmd))) return "`sed -i ''` is the BSD form; here sed is GNU: `sed -i 's/a/b/' file`."; // the real quotes
+  if (/(^|[\s;&|(])perl\s+(-\w+\s+)*-\w*i\w*\b[^;&|]*\.(ts|tsx|js|mjs|cpp|cc|c|h|hpp|py|cmake)\b/.test(b)) {
+    return 'an in-place perl edit of a code file: twice it wrote its text at the top of the file instead of in place (apprack B-135). Change code with the Edit tool; perl -pi stays for data files.';
+  }
+  if (zsh && /\bfor\s+\w+\s+in\s+\$\w+\s*;/.test(b)) {
+    return 'this session runs zsh: `for x in $VAR` does not split words. Use `${=VAR}`, an explicit list, or a script file run with bash. Restart Claude Code to get bash 5 (WB-41).';
+  }
+  if (/;\s*(GUARD_OK=1\s+)?git\s+checkout\s+-q?\s*--detach|;\s*rm\s+-rf\s|;\s*kill\s/.test(b)) {
+    return 'a destructive step chained with `;` runs even when the step before it failed (WB-19). Chain with `&&`, or run it as its own command after checking the first.';
+  }
+  return null;
+}
+
+function selftest() {
+  const cases = [
+    ["TZ=America/New_York date -r 1797000000 '+%F'", false, true], ["date -d @1797000000 '+%F'", false, false],
+    ["stat -f '%m %N' x", false, true], ['stat -c %Y x', false, false], ["sed -i '' 's/a/b/' f", false, true],
+    ["sed -i 's/a/b/' f", false, false], ['for t in $LIST; do echo $t; done', true, true],
+    ['for t in $LIST; do echo $t; done', false, false], ['for t in a b; do echo $t; done', true, false],
+    ['python3 x.py; GUARD_OK=1 git checkout -q --detach', false, true], ['python3 x.py && git checkout -q --detach', false, false],
+    ["echo 'date -r 5 and stat -f'", false, false], ["cat <<'EOF'\nsed -i '' x\nEOF", false, false],
+    ["perl -0pi -e 's|a|b|' src/readonly.ts", false, true], ["cd x && perl -pi -e 's/a/b/' lib/a.cpp", false, true],
+    ["perl -pi -e 's/a/b/' docs/not-carried.md", false, false], ["perl -0pi -e 's/a/b/' build.json", false, false],
+    ["perl -ne 'print' src/a.ts", false, false],
+  ];
+  const bad = cases.filter(([cmd, zsh, want]) => (verdict(cmd, zsh) !== null) !== want);
+  for (const [cmd, zsh, want] of bad) console.error(`shell-traps selftest FAILED: ${want ? 'not refused' : 'wrongly refused'}: ${cmd.replace(/\n/g, ' / ')}${zsh ? ' (zsh)' : ''}`);
+  if (!bad.length) console.log(`shell-traps selftest: OK (${cases.length} cases)`);
+  return bad.length ? 1 : 0;
+}
+
+function main() {
+  if (process.argv.includes('--selftest')) return selftest();
+  let ev;
+  try { ev = JSON.parse(readFileSync(0, 'utf8')); } catch { return 0; }
+  if (ev.tool_name !== 'Bash') return 0;
+  const v = verdict(String(ev.tool_input?.command ?? ''));
+  if (!v) return 0;
+  process.stderr.write(`shell-traps: ${v}\n`);
+  return 2;
+}
+
+process.exit(main());

package/global/hooks/version-pin-guard.mjs

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+// version-pin-guard: refuses a new or changed version pin unless docs/versions.md has a row
+// for that dependency checked within MAX_AGE days. Pairs with the latest-versions skill.
+// PreToolUse on Write|Edit|MultiEdit|Bash. Exit 2 blocks; stderr goes back to Claude. Every route that writes a
+// dependency file is judged (WB-69): the Write tool, an Edit or MultiEdit (its new_string taken literally), an install
+// command, and the shell writing the file (>, >>, tee, sed -i, cp, mv, a heredoc; lib/shell-writes.mjs).
+// `node version-pin-guard.mjs --selftest` proves every extractor and the age check.
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { afterText, shellWrites } from './lib/shell-writes.mjs';
+
+const MAX_AGE = Number(process.env.VERSION_GUARD_DAYS ?? 14);
+const DAY = 86_400_000;
+
+// ---------- extractors: text -> Map(name -> version) ----------
+function fromPackageJson(text) {
+  const out = new Map();
+  let json;
+  try { json = JSON.parse(text); } catch { return out; }
+  for (const key of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
+    for (const [n, v] of Object.entries(json[key] ?? {})) out.set(n, String(v));
+  }
+  if (json.packageManager) out.set(json.packageManager.split('@')[0], json.packageManager);
+  return out;
+}
+
+function fromCmake(text) {
+  const out = new Map();
+  for (const m of text.matchAll(/FetchContent_Declare\s*\(\s*([\w.-]+)([^)]*)\)/gi)) {
+    const v = m[2].match(/\b(?:GIT_TAG|URL)\s+("?)([^\s")]+)\1/i);
+    if (v) out.set(m[1], v[2]);
+  }
+  for (const m of text.matchAll(/CPMAddPackage\s*\(\s*"(?:gh:)?([\w./-]+)@([\w.+-]+)"/gi)) out.set(m[1].split('/').pop(), m[2]);
+  for (const m of text.matchAll(/ExternalProject_Add\s*\(\s*([\w.-]+)[^)]*?\bGIT_TAG\s+([^\s)]+)/gi)) out.set(m[1], m[2]);
+  return out;
+}
+
+function fromRequirements(text) {
+  const out = new Map();
+  for (const line of text.split('\n')) {
+    const m = line.replace(/#.*/, '').trim().match(/^([A-Za-z0-9_.\-\[\]]+)\s*(==|>=|~=|<=|>|<|===)\s*([^\s;,]+)/);
+    if (m) out.set(m[1].replace(/\[.*\]/, ''), `${m[2]}${m[3]}`);
+  }
+  return out;
+}
+
+function fromPyproject(text) {
+  const out = new Map();
+  for (const m of text.matchAll(/["']([A-Za-z0-9_.-]+)(?:\[[^\]]*\])?\s*(==|>=|~=|<=|>|<)\s*([^"',;\s]+)/g)) out.set(m[1], `${m[2]}${m[3]}`);
+  return out;
+}
+
+function fromCargo(text) {
+  const out = new Map();
+  let inDeps = false;
+  for (const line of text.split('\n')) {
+    const h = line.match(/^\s*\[([^\]]+)\]/);
+    if (h) { inDeps = /dependencies/.test(h[1]); continue; }
+    if (!inDeps) continue;
+    const m = line.match(/^\s*([\w-]+)\s*=\s*(?:"([^"]+)"|\{[^}]*version\s*=\s*"([^"]+)")/);
+    if (m) out.set(m[1], m[2] ?? m[3]);
+  }
+  return out;
+}
+
+function fromGoMod(text) {
+  const out = new Map();
+  for (const m of text.matchAll(/^\s*(?:require\s+)?([\w.\-/]+\.[\w.\-/]+)\s+(v[\w.+-]+)/gm)) out.set(m[1], m[2]);
+  return out;
+}
+
+function fromDockerfile(text) {
+  const out = new Map();
+  for (const m of text.matchAll(/^\s*FROM\s+(?:--platform=\S+\s+)?([^\s:@]+)[:@](\S+)/gim)) out.set(m[1].split('/').pop(), m[2]);
+  return out;
+}
+
+function fromWorkflow(text) {
+  const out = new Map();
+  for (const m of text.matchAll(/uses:\s*["']?([\w.-]+\/[\w.-]+)(?:\/[\w./-]+)?@([\w.-]+)/g)) out.set(m[1], m[2]);
+  return out;
+}
+
+// The parser for each manifest: by exact file name, else by the first name pattern that fits, else a workflow by its path.
+const BY_NAME = { 'package.json': fromPackageJson, 'CMakeLists.txt': fromCmake, 'pyproject.toml': fromPyproject, 'Cargo.toml': fromCargo, 'go.mod': fromGoMod };
+const BY_PATTERN = [
+  [/\.cmake$/, fromCmake],
+  [/^requirements.*\.(txt|in)$/, fromRequirements],
+  [/^(Dockerfile|Containerfile)(\..+)?$|\.dockerfile$/i, fromDockerfile],
+];
+
+export function extractorFor(file) {
+  const name = basename(file);
+  if (Object.hasOwn(BY_NAME, name)) return BY_NAME[name];
+  const hit = BY_PATTERN.find(([re]) => re.test(name));
+  if (hit) return hit[1];
+  return /\.github[\\/]workflows[\\/].+\.ya?ml$/.test(file) ? fromWorkflow : null;
+}
+
+// Pins in `after` that are new or different from `before`.
+export function changedPins(extract, before, after) {
+  const old = extract(before);
+  return [...extract(after)].filter(([n, v]) => old.get(n) !== v).map(([n, v]) => ({ name: n, version: v }));
+}
+
+// A shell redirection is never a package: `2>&1`, `&>log`, `>/dev/null`, `> out.txt`, `< in`, and a
+// trailing `&` (0.5.x read `2>&1` as a package named "2" at version "&1" and refused the command).
+const REDIRECT = /(?:^|\s)(?:\d*|&)(?:>>?|<)(?:&\d+|&-|\s*[^\s&|;<>]+)?|\s&(?=\s|$)/g;
+
+// A heredoc's body is text, never a command (KWB-3: a script fed to python3 <<'EOF' that held the words
+// "npm install x" in a comment was read as forty installs).
+const HEREDOC = /<<-?\s*(['"]?)([A-Za-z_][\w-]*)\1[^\n]*\n[\s\S]*?\n\s*\2\s*(?=\n|$)/g;
+const PREFIX = /^(sudo|env|command|time|nohup|npx|[A-Za-z_]\w*=\S*)$/;
+
+// Package names added by an install command (the install is the command itself, never a word an echo prints).
+export function pinsFromCommand(cmd) {
+  const found = [];
+  for (const seg of cmd.replace(HEREDOC, ' ').split(/&&|\|\||;|\||\n/)) {
+    const words = seg.replace(REDIRECT, ' ').trim().split(/\s+/);
+    let lead = 0;
+    while (lead < words.length && PREFIX.test(words[lead])) lead += 1;
+    const w0 = words[lead] ?? '', w1 = words[lead + 1] ?? '';
+    const at = (/^(npm|pnpm|yarn|bun)$/.test(w0) && /^(i|install|add)$/.test(w1)) || (/^(pip|pip3|uv|poetry)$/.test(w0) && /^(install|add)$/.test(w1)) || (w0 === 'cargo' && w1 === 'add') || (w0 === 'go' && w1 === 'get') ? lead : -1;
+    if (at === -1) continue;
+    for (const w of words.slice(at + 2)) {
+      if (w.startsWith('-') || w === 'pip' || w.startsWith('.') || w.startsWith('/')) continue;
+      const m = w.match(/^(@?[^@=<>~\s]+)(?:[@=<>~]=?(.+))?$/);
+      if (m && !/^(-r|requirements)/.test(m[1])) found.push({ name: m[1], version: m[2] ?? '(unpinned)' });
+    }
+  }
+  return found;
+}
+
+// The folder an install in `cmd` runs in: a `cd <dir>` before it moves it (KWB-3: `cd <scratch repo> && npm install x`
+// was judged by the session folder's docs/versions.md, so a pin in a repo that had its row was refused).
+export function installDir(cmd, cwd) {
+  let here = cwd;
+  for (const seg of cmd.replace(HEREDOC, ' ').split(/&&|\|\||;|\||\n/)) {
+    const m = seg.trim().match(/^(?:cd|pushd)\s+(['"]?)([^'"\s]+)\1$/);
+    if (m) { here = resolve(here, m[2].replace(/^(~|\$HOME|\$\{HOME\})(?=\/|$)/, process.env.HOME ?? '~')); continue; }
+    if (pinsFromCommand(seg).length) return here;
+  }
+  return here;
+}
+
+// ---------- docs/versions.md ----------
+export function checkedDates(versionsText) {
+  const dates = new Map();
+  for (const line of versionsText.split('\n')) {
+    if (!line.trim().startsWith('|')) continue;
+    const cells = line.split('|').map((c) => c.trim().replace(/`/g, '')).filter(Boolean);
+    const date = line.match(/\b(\d{4}-\d{2}-\d{2})\b/);
+    if (!cells.length || !date) continue;
+    const key = cells[0].toLowerCase();
+    const t = Date.parse(date[1]);
+    if (!dates.has(key) || dates.get(key) < t) dates.set(key, t);
+  }
+  return dates;
+}
+
+function lookup(dates, name) {
+  const n = name.toLowerCase();
+  for (const k of [n, n.split('/').pop(), n.replace(/^@[^/]+\//, '')]) if (dates.has(k)) return dates.get(k);
+  return undefined;
+}
+
+export function verdict(pins, dates, now = Date.now()) {
+  const problems = [];
+  for (const p of pins) {
+    const t = lookup(dates, p.name);
+    if (t === undefined) problems.push(`${p.name} ${p.version}: no row in docs/versions.md`);
+    else if (now - t > MAX_AGE * DAY) problems.push(`${p.name} ${p.version}: last checked ${new Date(t).toISOString().slice(0, 10)}, over ${MAX_AGE} days ago`);
+  }
+  return problems;
+}
+
+// The project the pin is written in: the nearest folder above it with docs/versions.md or .git
+// (a file in a git worktree), so an agent worktree and a sibling project read their own table.
+// CLAUDE_PROJECT_DIR is only the fallback, and for a worktree that carries no versions.md.
+export function projectRoot(start, env = process.env.CLAUDE_PROJECT_DIR) {
+  let d = resolve(start);
+  let found = null;
+  for (;;) {
+    if (existsSync(join(d, '.git')) || existsSync(join(d, 'docs', 'versions.md'))) { found = d; break; }
+    const up = dirname(d);
+    if (up === d) break;
+    d = up;
+  }
+  if (!found) return env ?? resolve(start);
+  const has = (root) => existsSync(join(root, 'docs', 'versions.md'));
+  if (!has(found) && env && has(env) && !relative(resolve(env), found).startsWith('..')) return env;
+  return found;
+}
+
+// ---------- hook ----------
+function newText(input, current) {
+  if (typeof input.content === 'string') return input.content;
+  const edits = input.edits ?? (input.old_string !== undefined ? [input] : []);
+  let text = current;
+  // literally: a new_string holding `$&` or `$1` was read as a replacement pattern (the Edit gap, WB-69)
+  for (const e of edits) text = e.replace_all ? text.split(e.old_string).join(e.new_string ?? '') : text.replace(e.old_string, () => e.new_string ?? '');
+  return text;
+}
+
+function main(payload) {
+  const input = payload.tool_input ?? {};
+  let pins = [];
+  let where;
+  if (payload.tool_name === 'Bash') {
+    pins = pinsFromCommand(input.command ?? '');
+    where = installDir(input.command ?? '', payload.cwd ?? process.cwd());
+    for (const w of shellWrites(input.command ?? '', where)) {
+      const extract = extractorFor(w.path);
+      if (!extract) continue;
+      const { before, after } = afterText(w);
+      if (after !== null) pins.push(...changedPins(extract, before, after));
+      where = dirname(w.path);
+    }
+  } else {
+    const file = input.file_path;
+    const extract = file && extractorFor(file);
+    if (!extract) return 0;
+    const before = existsSync(file) ? readFileSync(file, 'utf8') : '';
+    pins = changedPins(extract, before, newText(input, before));
+    where = dirname(file);
+  }
+  if (pins.length === 0) return 0;
+  const vfile = join(projectRoot(where), 'docs', 'versions.md');
+  const dates = existsSync(vfile) ? checkedDates(readFileSync(vfile, 'utf8')) : new Map();
+  const problems = verdict(pins, dates);
+  if (problems.length === 0) return 0;
+  process.stderr.write(`version-pin-guard: look up the newest release first (latest-versions skill).\n${problems.map((p) => `- ${p}`).join('\n')}\nAdd or refresh each row in ${vfile} (name | latest stable | YYYY-MM-DD | source URL | used | decision), then pin.\n`);
+  return 2;
+}
+
+function selftest() {
+  const eq = (a, b, what) => { if (JSON.stringify(a) !== JSON.stringify(b)) throw new Error(`${what}: got ${JSON.stringify(a)}`); };
+  const names = (pins) => pins.map((p) => p.name);
+  eq(names(changedPins(fromPackageJson, '{"dependencies":{"a":"1"}}', '{"dependencies":{"a":"1","fastify":"^5.6.0"}}')), ['fastify'], 'package.json add');
+  eq(names(changedPins(fromPackageJson, '{"dependencies":{"a":"1"}}', '{"dependencies":{"a":"1"},"x":2}')), [], 'package.json unchanged');
+  eq([...fromCmake('FetchContent_Declare(JUCE\n  GIT_REPOSITORY https://github.com/juce-framework/JUCE\n  GIT_TAG 9.0.4)')], [['JUCE', '9.0.4']], 'cmake GIT_TAG');
+  eq([...fromCmake('CPMAddPackage("gh:fmtlib/fmt@11.2.0")')], [['fmt', '11.2.0']], 'cmake CPM');
+  eq([...fromRequirements('numpy==2.3.1  # x\n-r base.txt\n')], [['numpy', '==2.3.1']], 'requirements');
+  eq([...fromPyproject('dependencies = ["httpx>=0.28", "rich"]')], [['httpx', '>=0.28']], 'pyproject');
+  eq([...fromCargo('[package]\nversion = "0.1.0"\n[dependencies]\nserde = { version = "1.0.219", features = ["derive"] }\n')], [['serde', '1.0.219']], 'cargo');
+  eq([...fromGoMod('module x\nrequire (\n  github.com/spf13/cobra v1.9.1\n)\n')], [['github.com/spf13/cobra', 'v1.9.1']], 'go.mod');
+  eq([...fromDockerfile('FROM --platform=linux/amd64 node:24-slim AS build\n')], [['node', '24-slim']], 'dockerfile');
+  eq([...fromWorkflow('- uses: actions/checkout@v5\n- uses: github/codeql-action/init@v3')], [['actions/checkout', 'v5'], ['github/codeql-action', 'v3']], 'workflow');
+  eq(names(pinsFromCommand('cd x && npm install -D typescript@5.9.3 zod')), ['typescript', 'zod'], 'npm install');
+  eq(names(pinsFromCommand('pip install --break-system-packages requests==2.32.5')), ['requests'], 'pip install');
+  eq(pinsFromCommand('npm install'), [], 'bare npm install');
+  eq(names(pinsFromCommand('npm install fastify 2>&1 | tail -5')), ['fastify'], 'install with 2>&1');
+  eq(names(pinsFromCommand('npm i zod > /tmp/npm.log 2>&1')), ['zod'], 'install with > log 2>&1');
+  eq(names(pinsFromCommand('pip install requests==2.32.5 &>/dev/null &')), ['requests'], 'install with &>/dev/null &');
+  eq(pinsFromCommand('npm install 2>&1'), [], 'bare install with 2>&1');
+  eq(pinsFromCommand("python3 - <<'EOF'\n# then npm install zod and pip install rich\nEOF"), [], 'a heredoc body is text');
+  eq(pinsFromCommand('echo run npm install zod first'), [], 'an echo that names an install');
+  eq(names(pinsFromCommand('sudo npm install -g zod@4')), ['zod'], 'install after a prefix');
+  eq(installDir('cd /p/other && npm install zod@4', '/p/here'), '/p/other', 'an install after cd runs there');
+  eq(installDir('npm install zod@4 && cd /p/other', '/p/here'), '/p/here', 'a cd after the install does not move it');
+  const now = Date.parse('2026-10-26');
+  const dates = checkedDates('| name | latest |\n|---|---|\n| fastify | 5.6.1 | 2026-10-20 | https://github.com/fastify/fastify/releases | 5.6.1 | use |\n| `JUCE` | 9.0.4 | 2026-09-01 | url | 8.0.4 | F4 |\n');
+  eq(verdict([{ name: 'fastify', version: '5.6.1' }], dates, now), [], 'fresh row passes');
+  eq(verdict([{ name: 'JUCE', version: '9.0.4' }], dates, now).length, 1, 'stale row blocks');
+  eq(verdict([{ name: 'zod', version: '4' }], dates, now).length, 1, 'missing row blocks');
+  eq(verdict([{ name: 'github.com/fastify', version: 'v1' }], dates, now), [], 'last path segment matches');
+  console.log('version-pin-guard selftest: OK (26 cases)');
+  return 0;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname)) {
+  if (process.argv.includes('--selftest')) process.exit(selftest());
+  let raw = '';
+  process.stdin.on('data', (c) => { raw += c; });
+  process.stdin.on('end', () => {
+    let payload;
+    try { payload = JSON.parse(raw || '{}'); } catch { process.exit(0); }
+    process.exit(main(payload));
+  });
+}