@thedecipherist/claude-packs 1.0.0 → 1.1.0

package/configurations/full-stack/config.json

@@ -23,6 +23,7 @@
       "ci",
       "dynamic-data",
       "mongo",
+      "postgres",
       "ai",
       "nginx",
       "content-site"
@@ -139,7 +140,7 @@
       "Ask the user before inventing a new folder. A new folder goes into `.claude/layout.json` first.",
       "When a hook, check or guard blocks work that is correct, stop and report its exact message. A blocking hook is a red check: fix the hook first, with a selftest, then continue.",
       "When a command is refused or fails, the step fails loudly. Never report a refused write or a failed command as done.",
-      "claude-packs (`~/projects/claude-packs`) is the source of truth for every rule, check, hook and skill this project's configuration installs. A fix to one of them is made there with its test, committed, pushed and released as a new version, then taken in with `npx --no-install @thedecipherist/claude-packs update`. A project edits its installed copy only to try a fix before it goes into the kit."
+      "claude-packs (`@thedecipherist/claude-packs`) is the source of truth for every rule, check, hook and skill this project's configuration installs. A fix to one of them is made in the kit, with its test, and comes here with `npx --no-install @thedecipherist/claude-packs update`. A project edits its installed copy only to try a fix before it goes into the kit."
     ],
     "never": [
       "Create source files outside these folders, or put a kind of thing anywhere but its place. The folder-law and placement-law hooks refuse both.",

package/configurations/go/config.json

@@ -9,8 +9,10 @@
     ],
     "choose": [
       "go",
+      "rust",
       "shell",
       "docker",
+      "postgres",
       "http-api",
       "multi-tenant",
       "websocket",
@@ -83,7 +85,7 @@
       "Ask the user before inventing a new folder. A new folder goes into `.claude/layout.json` first.",
       "When a hook, check or guard blocks work that is correct, stop and report its exact message. A blocking hook is a red check: fix the hook first, with a selftest, then continue.",
       "When a command is refused or fails, the step fails loudly. Never report a refused write or a failed command as done.",
-      "claude-packs (`~/projects/claude-packs`) is the source of truth for every rule, check, hook and skill this project's configuration installs. A fix to one of them is made there with its test, committed, pushed and released as a new version, then taken in with `npx --no-install @thedecipherist/claude-packs update`. A project edits its installed copy only to try a fix before it goes into the kit."
+      "claude-packs (`@thedecipherist/claude-packs`) is the source of truth for every rule, check, hook and skill this project's configuration installs. A fix to one of them is made in the kit, with its test, and comes here with `npx --no-install @thedecipherist/claude-packs update`. A project edits its installed copy only to try a fix before it goes into the kit."
     ],
     "never": [
       "Create source files outside these folders, or put a kind of thing anywhere but its place. The folder-law and placement-law hooks refuse both.",

package/configurations/node/config.json

@@ -10,6 +10,7 @@
     "choose": [
       "js-ts",
       "mongo",
+      "postgres",
       "fastify",
       "ai",
       "docker",
@@ -29,6 +30,7 @@
       "websocket",
       "host-agent",
       "go",
+      "rust",
       "ci",
       "dynamic-data",
       "zod",
@@ -88,7 +90,7 @@
       "Ask the user before inventing a new folder. A new folder goes into `.claude/layout.json` first.",
       "When a hook, check or guard blocks work that is correct, stop and report its exact message. A blocking hook is a red check: fix the hook first, with a selftest, then continue.",
       "When a command is refused or fails, the step fails loudly. Never report a refused write or a failed command as done.",
-      "claude-packs (`~/projects/claude-packs`) is the source of truth for every rule, check, hook and skill this project's configuration installs. A fix to one of them is made there with its test, committed, pushed and released as a new version, then taken in with `npx --no-install @thedecipherist/claude-packs update`. A project edits its installed copy only to try a fix before it goes into the kit."
+      "claude-packs (`@thedecipherist/claude-packs`) is the source of truth for every rule, check, hook and skill this project's configuration installs. A fix to one of them is made in the kit, with its test, and comes here with `npx --no-install @thedecipherist/claude-packs update`. A project edits its installed copy only to try a fix before it goes into the kit."
     ],
     "never": [
       "Create source files outside these folders, or put a kind of thing anywhere but its place. The folder-law and placement-law hooks refuse both.",

package/configurations/python/config.json

@@ -13,12 +13,14 @@
       "docker",
       "ai",
       "mongo",
+      "postgres",
       "js-ts",
       "cpp",
       "http-api",
       "multi-tenant",
       "ci",
       "go",
+      "rust",
       "dynamic-data",
       "web",
       "ui-craft",
@@ -84,7 +86,7 @@
       "Ask the user before inventing a new folder. A new folder goes into `.claude/layout.json` first.",
       "When a hook, check or guard blocks work that is correct, stop and report its exact message. A blocking hook is a red check: fix the hook first, with a selftest, then continue.",
       "When a command is refused or fails, the step fails loudly. Never report a refused write or a failed command as done.",
-      "claude-packs (`~/projects/claude-packs`) is the source of truth for every rule, check, hook and skill this project's configuration installs. A fix to one of them is made there with its test, committed, pushed and released as a new version, then taken in with `npx --no-install @thedecipherist/claude-packs update`. A project edits its installed copy only to try a fix before it goes into the kit."
+      "claude-packs (`@thedecipherist/claude-packs`) is the source of truth for every rule, check, hook and skill this project's configuration installs. A fix to one of them is made in the kit, with its test, and comes here with `npx --no-install @thedecipherist/claude-packs update`. A project edits its installed copy only to try a fix before it goes into the kit."
     ],
     "never": [
       "Create source files outside these folders, or put a kind of thing anywhere but its place. The folder-law and placement-law hooks refuse both.",

package/configurations/rust/config.json

@@ -0,0 +1,106 @@
+{
+  "name": "rust",
+  "description": "Rust projects: universal engineering and the rust pack.",
+  "packs": {
+    "always": [
+      "base",
+      "writing",
+      "hook-proof"
+    ],
+    "choose": [
+      "rust",
+      "go",
+      "shell",
+      "docker",
+      "postgres",
+      "http-api",
+      "multi-tenant",
+      "websocket",
+      "host-agent",
+      "ci",
+      "js-ts",
+      "python",
+      "dynamic-data",
+      "web",
+      "ui-craft",
+      "content-site"
+    ],
+    "default": [
+      "rust"
+    ]
+  },
+  "layout": {
+    "folders": {
+      "docs": {
+        "path": "docs",
+        "purpose": "spec, laws, licences, work orders, decisions"
+      },
+      "src": {
+        "path": "src",
+        "purpose": "the source of a single crate"
+      },
+      "tests": {
+        "path": "tests",
+        "purpose": "integration tests (unit tests live beside their code, in a #[cfg(test)] module)"
+      },
+      "tools": {
+        "path": "tools",
+        "purpose": "scripts and research tooling (not shipped)"
+      },
+      "crates": {
+        "path": "crates",
+        "purpose": "the crates of a workspace, each with its own src/ and tests/",
+        "planned": true
+      },
+      "benches": {
+        "path": "benches",
+        "purpose": "benchmarks",
+        "planned": true
+      },
+      "examples": {
+        "path": "examples",
+        "purpose": "runnable examples",
+        "planned": true
+      }
+    },
+    "kinds": {
+      "tests": {
+        "what": "integration tests",
+        "in": "tests",
+        "concepts": [
+          "tests"
+        ]
+      },
+      "docs": {
+        "what": "the spec, laws.md, decisions, research, work orders",
+        "in": "docs",
+        "concepts": [
+          "docs-folder"
+        ],
+        "files": [
+          "**/laws.md",
+          "**/*-spec.md"
+        ]
+      },
+      "tools": {
+        "what": "scripts and research tools that never ship",
+        "in": "tools"
+      }
+    }
+  },
+  "preamble": {
+    "always": [
+      "Ask the user before inventing a new folder. A new folder goes into `.claude/layout.json` first.",
+      "When a hook, check or guard blocks work that is correct, stop and report its exact message. A blocking hook is a red check: fix the hook first, with a selftest, then continue.",
+      "When a command is refused or fails, the step fails loudly. Never report a refused write or a failed command as done.",
+      "claude-packs (`@thedecipherist/claude-packs`) is the source of truth for every rule, check, hook and skill this project's configuration installs. A fix to one of them is made in the kit, with its test, and comes here with `npx --no-install @thedecipherist/claude-packs update`. A project edits its installed copy only to try a fix before it goes into the kit."
+    ],
+    "never": [
+      "Create source files outside these folders, or put a kind of thing anywhere but its place. The folder-law and placement-law hooks refuse both.",
+      "Edit files in `.claude/rules`, `.claude/checks` or `.claude/hooks` to get past a block. Fix the code, or ask the user to change the law.",
+      "Route around a block: no override variables, no writing through the shell after a refusal, no parking files in a scratchpad, no putting new code into an unrelated existing file.",
+      "Point at a document by line number. Cite a fixed anchor (`{#id}`) or a symbol name; lines move."
+    ]
+  },
+  "sourceFiles": "(?<!/build)\\.rs$"
+}

package/configurations/synth-creator/config.json

@@ -135,7 +135,7 @@
       "Ask the user before inventing a new folder. A new folder goes into `.claude/layout.json` first.",
       "When a hook, check or guard blocks work that is correct, stop and report its exact message. A blocking hook is a red check: fix the hook first, with a selftest, then continue.",
       "When a command is refused or fails, the step fails loudly. Never report a refused write or a failed command as done.",
-      "claude-packs (`~/projects/claude-packs`) is the source of truth for every rule, check, hook and skill used to build synths. A fix to one of them, or a lesson that should hold in every synth, is made there with its test, committed, pushed and released as a new version, then taken in with `npx --no-install @thedecipherist/claude-packs update`, so every synth gets it. A project edits its installed copy only to try a fix before it goes into the kit."
+      "claude-packs (`@thedecipherist/claude-packs`) is the source of truth for every rule, check, hook and skill used to build synths. A fix to one of them, or a lesson that should hold in every synth, is made in the kit, with its test, and comes here with `npx --no-install @thedecipherist/claude-packs update`, so every synth gets it. A project edits its installed copy only to try a fix before it goes into the kit."
     ],
     "never": [
       "Create source files outside these folders, or put a kind of thing anywhere but its place. The folder-law and placement-law hooks refuse both.",

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

@@ -1,293 +1,2 @@
-// 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));
-  });
-}
+// The one shell reader is base's. This line lets the global hooks run from the kit's own folder; `global add` installs the reader itself (lib/global.mjs).
+export * from '../../../packs/base/hooks/lib/shell-writes.mjs';

package/lib/build-queue.mjs

@@ -0,0 +1,22 @@
+// KF-1: build-guard named a queue no pack shipped, and took any file called build.sh as a queue. doctor checks both ways it fails open: the tool is gone, or the project's
+// wrapper queues nothing. A wrapper that holds the law itself says so: layout.json "guards": { "build": { "queue": "none: <reason>" } }.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const TOOL = '.claude/tools/buildq.mjs';
+
+const wrappersOf = (commands) => [...new Set(Object.values(commands ?? {}).flatMap((c) => String(c).split(/\s+/)).filter((w) => /(^|\/)build\.sh$/.test(w)))];
+
+export function buildQueueProblems(projectDir, layout) {
+  if (!existsSync(join(projectDir, '.claude/hooks/build-guard.mjs'))) return [];
+  const problems = [];
+  if (!existsSync(join(projectDir, TOOL))) problems.push(`build-guard sends every build to ${TOOL}, which is missing: run update`);
+  if (/^none:\s*\S/.test(layout.guards?.build?.queue ?? '')) return problems;
+  for (const rel of wrappersOf(layout.commands)) {
+    const file = join(projectDir, rel);
+    if (existsSync(file) && !readFileSync(file, 'utf8').includes('buildq')) {
+      problems.push(`${rel} does not call the queue, so build-guard passes it and no job waits. Call ${TOOL} in it, or set layout.json "guards": { "build": { "queue": "none: <reason>" } }`);
+    }
+  }
+  return problems;
+}

package/lib/claude-md.mjs

@@ -2,12 +2,13 @@
 // Everything outside the markers is the user's and is never touched.
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { noPackageLine } from './kit-command.mjs';
 
 const START = '<!-- claude-packs:start -->';
 const END = '<!-- claude-packs:end -->';
 
 // The house rules after the folders are the configuration's preamble (configurations/<name>/config.json, 0.10.0).
-function section(layout, packNames, preamble) {
+function section(layout, packNames, preamble, notes = []) {
   // Folders no kind points at are listed by purpose; the rest appear once, in the kinds list.
   const used = new Set(Object.values(layout.kinds ?? {}).map((k) => k.in));
   const folders = Object.entries(layout.folders)
@@ -31,6 +32,7 @@ function section(layout, packNames, preamble) {
     '</constraints>',
     '',
     ...commandLines(layout),
+    ...notes,
     `Installed packs: ${packNames.join(', ')}.`,
     END,
   ].join('\n');
@@ -48,7 +50,7 @@ function commandLines(layout) {
 
 export function writeClaudeMd(projectDir, layout, packNames, preamble) {
   const file = join(projectDir, 'CLAUDE.md');
-  const block = section(layout, packNames, preamble);
+  const block = section(layout, packNames, preamble, noPackageLine(projectDir));
   let text = existsSync(file) ? readFileSync(file, 'utf8') : '';
   const s = text.indexOf(START);
   const e = text.indexOf(END);

package/lib/config-cli.mjs

@@ -32,5 +32,5 @@ export async function switchConfig(dir, name, installed, { force = false, dryRun
   if (dryRun) { log('dry run: nothing changed'); return 0; }
   if (lines.at(-1) === '  no change' && layout.configuration === to.name) return 0;
   await sync(dir, chosen, { force, mkdirs: true, config: name, log });
-  return doctor(dir, log);
+  return doctor(dir, log, { installing: true });
 }

package/lib/coverage.mjs

@@ -79,8 +79,16 @@ export async function coverage(projectDir, source = SOURCE) {
   const all = projectFiles(projectDir);
   const rules = rulePaths(claudeDir);
   const reachable = [...all, ...claudeFiles(projectDir)];
-  const deadRules = rules.filter((r) => r.globs.length && !reachable.some((f) => matchesAny(f, r.globs))).map((r) => r.rule);
+  const matchesNothing = (r) => r.globs.length && !reachable.some((f) => matchesAny(f, r.globs));
+  // A rule whose folder holds nothing yet waits for its first file; only one whose folder holds other files disagrees with the structure (KF-9: a new unit's
+  // empty src/dsp made `doctor --strict` impossible). A glob with no folder of its own (**/*.py) says nothing about the structure either.
+  const folderOf = (glob) => glob.split(/[*?{[]/)[0].replace(/\/?[^/]*$/, '');
+  const holdsFiles = (folder) => Boolean(folder) && reachable.some((f) => f.startsWith(`${folder}/`));
+  const waiting = (r) => !r.globs.some((g) => holdsFiles(folderOf(g)));
+  const deadRules = rules.filter((r) => matchesNothing(r) && !waiting(r)).map((r) => r.rule);
+  const waitingRules = rules.filter((r) => matchesNothing(r) && waiting(r)).map((r) => r.rule);
+  const liveRules = rules.filter((r) => all.some((f) => source.test(f) && matchesAny(f, r.globs))).map((r) => r.rule); // it governs source the project wrote
   const protectedGlobs = readLayout(projectDir).protected ?? [];
   const uncovered = all.filter((f) => source.test(f) && !matchesAny(f, protectedGlobs) && !rules.some((r) => matchesAny(f, r.globs)));
-  return { deadRules, uncovered, sourceCount: all.filter((f) => source.test(f)).length };
+  return { deadRules, waitingRules, liveRules, uncovered, files: all, sourceCount: all.filter((f) => source.test(f)).length };
 }

package/lib/doctor.mjs

@@ -13,7 +13,9 @@ import { onceOnlyDoctor, useJscpd } from './once-only-report.mjs';
 import { proved, remember, selftestKey, sharedHash } from './selftest-cache.mjs';
 import { timingProblems } from './hook-timing.mjs';
 import { configProblems, sourceFilesOf } from './configs.mjs';
-import { hookProofProblems } from './hook-proof.mjs';
+import { hookProofProblems, paramLockProblems } from './hook-proof.mjs';
+import { ruleTestProblems } from './rule-tests.mjs';
+import { buildQueueProblems } from './build-queue.mjs';
 import { manifestProblems } from './pack-manifest.mjs';
 import { readPack } from './packs.mjs';
 import { hoverGateProblems, pageGateProblems } from './hover-gate.mjs';
@@ -21,7 +23,9 @@ import { hoverGateProblems, pageGateProblems } from './hover-gate.mjs';
 const SELFTEST_JOBS = Number(process.env.CLAUDE_PACKS_SELFTEST_JOBS ?? 4);
 const SELFTEST_S = Number(process.env.CLAUDE_PACKS_SELFTEST_S ?? 180);
 
-export async function doctor(projectDir, log = console.log, { strict = false, fresh = false } = {}) {
+// installing: doctor run at the end of an install. What the project has yet to do (a rule's test, a parameter lock) is a note there: an install on
+// a project with code has not failed. The `doctor` command is red for it.
+export async function doctor(projectDir, log = console.log, { strict = false, fresh = false, installing = false } = {}) {
   const claudeDir = join(projectDir, '.claude');
   const lock = readLock(claudeDir);
   const problems = [];
@@ -37,7 +41,7 @@ export async function doctor(projectDir, log = console.log, { strict = false, fr
   if (stale) problems.push(`${stale} rule(s) have paths out of date with layout.json (run update)`);
 
   const layout = JSON.parse(readFileSync(join(claudeDir, 'layout.json'), 'utf8'));
-  for (const f of Object.values(layout.folders)) if (!existsSync(join(projectDir, f.path))) problems.push(`layout folder missing: ${f.path}/`);
+  for (const f of Object.values(layout.folders)) if (!f.planned && !existsSync(join(projectDir, f.path))) problems.push(`layout folder missing: ${f.path}/`);
 
   const settings = existsSync(join(claudeDir, 'settings.json')) ? readFileSync(join(claudeDir, 'settings.json'), 'utf8') : '';
   if (!settings.includes('.claude/hooks/lesson-checks.mjs')) problems.push('hooks not registered in .claude/settings.json');
@@ -93,6 +97,9 @@ export async function doctor(projectDir, log = console.log, { strict = false, fr
 
   for (const name of lock.packs) problems.push(...manifestProblems(readPack(name), name));
   problems.push(...await hookProofProblems(projectDir, settings)); // a guard that fails open fails silently (0.18.0)
+  const toDo = (found) => (installing ? found.forEach((f) => log(`  note: ${f}`)) : problems.push(...found));
+  toDo(paramLockProblems(projectDir)); // a lock holding no ids protects nothing, and says nothing (KF-15)
+  toDo(buildQueueProblems(projectDir, layout)); // a queue that is not there queues nothing (KF-1)
   problems.push(...await pageGateProblems(projectDir, layout)); // UI code is proved rendered (0.17.0)
   problems.push(...await hoverGateProblems(projectDir, layout)); // UI code needs a declared hover gate (0.10.1, Stellix B-261)
   problems.push(...tokenProblems(projectDir, layout.siblings ?? []));
@@ -101,9 +108,13 @@ export async function doctor(projectDir, log = console.log, { strict = false, fr
   problems.push(...timingProblems(projectDir, log)); // each hook's median and worst from .claude/hooks.log; a median over 500 ms is red (KWB-24)
 
   const cov = await coverage(projectDir, sourceFilesOf(projectDir, lock.packs)); // the configuration says what is source (KWB-32)
+  const ruleTests = ruleTestProblems(projectDir, layout, cov); // a rule's own test can be missing for a whole build (KF-31)
+  if (layout.ruleTests) toDo(ruleTests); // a new law never turns an installed project red: the key in layout.json is the choice
+  else ruleTests.forEach((f) => log(`  note: ${f}\n    To be held to this, add "ruleTests": {} to .claude/layout.json.`));
   if (cov.sourceCount > 0) {
     const say = (msg) => (strict ? problems.push(msg) : log(`  note: ${msg}`));
     if (cov.deadRules.length) say(`${cov.deadRules.length} rule(s) match no file yet, so they never fire: ${cov.deadRules.slice(0, 8).join(', ')}${cov.deadRules.length > 8 ? ', …' : ''}`);
+    if (cov.waitingRules.length) log(`  note: ${cov.waitingRules.length} rule(s) wait for their first file: their folders hold nothing yet`);
     if (cov.uncovered.length) say(`${cov.uncovered.length} source file(s) no rule covers (outside the structure?): ${cov.uncovered.slice(0, 8).join(', ')}${cov.uncovered.length > 8 ? ', …' : ''}`);
   }