@thedecipherist/claude-packs 0.0.0-stage → 1.0.0

package/packs/base/hooks/lib/function-shapes.mjs

@@ -0,0 +1,90 @@
+// Every named function in a text, with how much it holds (0.25.0). A line limit cannot see a 140-statement function written 70 lines long, or a
+// function that takes nine positional arguments.
+//   functionsOf(text, ext) -> [{ name, line, end, statements, params }]
+import { statementsOf } from './code-shapes.mjs';
+import { languageOf } from './languages.mjs';
+
+const CONTROL = new Set(['if', 'for', 'while', 'switch', 'catch', 'return', 'sizeof', 'function', 'with', 'elif', 'do', 'foreach', 'until', 'unless']);
+const BY_INDENT = new Set(['python', 'ruby', 'lua']);
+
+// Index of the bracket that opens the one closing at `close`, or -1.
+function openerOf(code, close) {
+  let depth = 0;
+  for (let i = close; i >= 0; i -= 1) {
+    if (code[i] === ')') depth += 1;
+    else if (code[i] === '(' && (depth -= 1) === 0) return i;
+  }
+  return -1;
+}
+
+function paramsIn(inner) {
+  let depth = 0;
+  let commas = 0;
+  for (const c of inner) {
+    if ('(<[{'.includes(c)) depth += 1;
+    else if (')>]}'.includes(c)) depth -= 1;
+    else if (c === ',' && depth === 0) commas += 1;
+  }
+  const self = /^\s*(?:self|cls|&?(?:mut\s+)?self)\s*(?:,|$)/.test(inner) ? 1 : 0;
+  return inner.trim() ? commas + 1 - self : 0;
+}
+
+// `name (params) ... {`: the head before a body's brace, or null when it is a block, a call or a type.
+function headOf(code, brace) {
+  const head = code.slice(Math.max(0, brace - 400), brace);
+  const close = head.search(/\)(?:\s*(?:const|noexcept|override|final|mutable|throws\s+[\w, ]+|->\s*[^{;]+|:\s*[\w<>[\]., |?]+))*\s*$/);
+  if (close < 0) return null;
+  const at = brace - head.length + close;
+  const open = openerOf(code, at);
+  if (open < 0) return null;
+  const arrow = code.slice(0, open).match(/(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?$/);
+  const name = arrow?.[1] ?? code.slice(Math.max(0, open - 80), open).match(/([A-Za-z_$][\w$]*)\s*(?:<[^<>()]*>)?\s*$/)?.[1];
+  return !name || CONTROL.has(name) ? null : { name, open, params: paramsIn(code.slice(open + 1, at)) };
+}
+
+function byBraces(code) {
+  const out = [];
+  const stack = [];
+  for (let i = 0; i < code.length; i += 1) {
+    if (code[i] === '{') stack.push(i);
+    else if (code[i] === '}' && stack.length) {
+      const a = stack.pop();
+      const head = headOf(code, a);
+      if (head) out.push({ ...head, from: a, to: i });
+    }
+  }
+  return out;
+}
+
+function byIndent(code, starts) {
+  const lines = code.split('\n');
+  const out = [];
+  lines.forEach((l, i) => {
+    const m = l.match(/^(\s*)(?:async\s+)?(?:local\s+)?(?:def|function)\s+([A-Za-z_][\w.:?!]*)\s*(?:\(([^)]*)\)?)?/);
+    if (!m) return;
+    let end = i;
+    for (let j = i + 1; j < lines.length; j += 1) {
+      if (!lines[j].trim()) continue;
+      if (lines[j].match(/^\s*/)[0].length <= m[1].length) break;
+      end = j;
+    }
+    out.push({ name: m[2], from: starts[i], to: starts[end], params: paramsIn(m[3] ?? '') });
+  });
+  return out;
+}
+
+export function functionsOf(text, ext) {
+  const lang = languageOf(ext);
+  if (!lang) return [];
+  const code = lang.blank(text);
+  const starts = [0];
+  for (let i = code.indexOf('\n'); i !== -1; i = code.indexOf('\n', i + 1)) starts.push(i + 1);
+  const lineOf = (offset) => { let n = 0; while (n + 1 < starts.length && starts[n + 1] <= offset) n += 1; return n + 1; };
+  const list = statementsOf(text, lang);
+  const found = BY_INDENT.has(lang.name) ? byIndent(code, starts) : byBraces(code);
+  return found.map((f) => {
+    const line = lineOf(f.from);
+    const end = lineOf(f.to);
+    return { name: f.name, line, end, params: f.params, statements: list.filter((s) => s.line >= line && s.line <= end).length };
+  });
+}

package/packs/base/hooks/lib/git-adds.mjs

@@ -0,0 +1,20 @@
+// The `git add` calls in a shell command, with the folder each runs in and its arguments. secrets-guard and repo-litter both judge these.
+//   gitAdds(command, cwd) -> [{ dir, args }]
+import { resolve } from 'node:path';
+
+export function gitAdds(command, cwd) {
+  const body = command.replace(/<<-?\s*['"]?(\w+)['"]?[\s\S]*?\n\1\b/g, '');
+  const out = [];
+  for (const part of body.split(/&&|\|\||;|\|/)) {
+    const w = part.trim().split(/\s+/);
+    if (w[0] !== 'git') continue;
+    let at = 1;
+    let dir = cwd;
+    while (at < w.length && w[at].startsWith('-')) {
+      if (w[at] === '-C') dir = resolve(dir, w[at + 1] ?? '.');
+      at += ['-C', '-c'].includes(w[at]) ? 2 : 1;
+    }
+    if (w[at] === 'add') out.push({ dir, args: w.slice(at + 1) });
+  }
+  return out;
+}

package/packs/base/hooks/lib/git-guard-selftest.mjs

@@ -0,0 +1,99 @@
+// git-guard's selftest for the pushed laws (KWB-26), on a real repo whose "GitHub" is a bare repo beside it. The hook runs
+// the way Claude Code runs it (through run-hooks.mjs, the event on stdin, CLAUDE_PROJECT_DIR set):
+//   a commit on a branch whose earlier commits are not on the remote is refused; pushed, it passes; a branch's first
+//   commit passes; a push earlier in the same command counts; the remote out of reach lets it through with a warning;
+//   Stop is refused while a local branch is ahead of the remote or missing there, and passes once all are pushed;
+//   the refusals name the push and never offer deleting a branch; three identical Stop refusals end the session.
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { git, put } from './selftest.mjs';
+import { remoteHeads } from './pushed.mjs';
+
+const RUNNER = fileURLToPath(new URL('../run-hooks.mjs', import.meta.url));
+
+export function pushedCases(hookFile) {
+  const top = realpathSync(mkdtempSync(join(process.env.TMPDIR ?? tmpdir(), 'git-guard-pushed-')));
+  const dir = join(top, 'repo');
+  const hub = join(top, 'hub.git');
+  const session = `selftest-${process.pid}-${Date.now()}`;
+  put(join(dir, '.claude/layout.json'), JSON.stringify({ folders: {}, guards: { git: { house: true } } }));
+  git(top, 'init', '-q', '--bare', '-b', 'main', hub);
+  git(top, 'init', '-q', '-b', 'main', dir);
+  git(dir, 'remote', 'add', 'origin', hub);
+  const commit = (msg) => { writeFileSync(join(dir, `${msg}.txt`), msg); git(dir, 'add', `${msg}.txt`); git(dir, 'commit', '-q', '-m', msg); };
+  const push = (...b) => git(dir, 'push', '-q', 'origin', ...b);
+  const run = (payload) => spawnSync(process.execPath, [RUNNER, hookFile], {
+    cwd: dir, encoding: 'utf8', input: JSON.stringify({ session_id: session, cwd: dir, ...payload }),
+    env: { ...process.env, CLAUDE_PROJECT_DIR: dir },
+  });
+  const bash = (command) => run({ hook_event_name: 'PreToolUse', tool_name: 'Bash', tool_input: { command } });
+  const stop = () => run({ hook_event_name: 'Stop', stop_hook_active: false });
+  const cases = [];
+  const C = "git commit -m 'next' -- a.txt";
+
+  commit('first');
+  push('main');
+  git(dir, 'switch', '-q', '-c', 'work/x');
+  cases.push(['a new branch\'s first commit passes', bash(C).status, 0]);
+  commit('one');
+  const r1 = bash(C);
+  cases.push(['an earlier commit never pushed: the next commit is refused', r1.status, 2]);
+  cases.push(['the refusal names the commit and the push with the token named', /\bone\b/.test(r1.stderr) && /git push https:\/\/x-access-token:\$PERSONAL_GITHUB_TOKEN@github\.com\/\S+ work\/x/.test(r1.stderr), true]);
+  cases.push(['the refusal never offers deleting a branch', /branch -[dD]|--delete|delete the branch/.test(r1.stderr), false]);
+  cases.push(['a push earlier in the same command counts', bash(`source ~/.env && git push https://x-access-token:$PERSONAL_GITHUB_TOKEN@github.com/HouseOwner/repo.git work/x && ${C}`).status, 0]);
+  push('work/x');
+  cases.push(['pushed seconds after a refusal (the cache is fresh): the commit passes', bash(C).status, 0]);
+  commit('two');
+  cases.push(['a pushed branch one commit ahead: refused', bash(`cd ${dir} && ${C}`).status, 2]);
+  cases.push(['git -C into the repo is judged there', bash(`git -C ${dir} commit -m x -- a.txt`).status, 2]);
+  const lone = join(top, 'lone');
+  git(top, 'init', '-q', '-b', 'work/z', lone);
+  git(lone, 'commit', '-q', '--allow-empty', '-m', 'a');
+  git(lone, 'commit', '-q', '--allow-empty', '-m', 'b');
+  cases.push(['a repo with no remote has nothing to push to: passes', bash(`git -C ${lone} commit --allow-empty -m c`).status, 0]);
+  // a repo that pushes by URL only names its GitHub repo in the layout (guards.git.repo): judged against it
+  put(join(lone, '.claude/layout.json'), JSON.stringify({ folders: {}, guards: { git: { house: true, repo: hub } } }));
+  const byUrl = spawnSync(process.execPath, [RUNNER, hookFile], { cwd: lone, encoding: 'utf8', input: JSON.stringify({ session_id: session, cwd: lone, hook_event_name: 'PreToolUse', tool_name: 'Bash', tool_input: { command: 'git commit --allow-empty -m c' } }), env: { ...process.env, CLAUDE_PROJECT_DIR: lone } });
+  cases.push(['no remote, guards.git.repo named: its unpushed commits refuse the next commit', byUrl.status, 2]);
+
+  // KWB-48: another repo with no remote, the project's layout naming the project's own repo: nothing to compare with
+  const other = join(top, 'other');
+  git(top, 'init', '-q', '-b', 'work/o', other);
+  git(other, 'commit', '-q', '--allow-empty', '-m', 'a');
+  git(other, 'commit', '-q', '--allow-empty', '-m', 'b');
+  const foreign = spawnSync(process.execPath, [RUNNER, hookFile], { cwd: other, encoding: 'utf8', input: JSON.stringify({ session_id: session, cwd: other, hook_event_name: 'PreToolUse', tool_name: 'Bash', tool_input: { command: 'git commit --allow-empty -m c' } }), env: { ...process.env, CLAUDE_PROJECT_DIR: lone } });
+  cases.push(["a repo with no remote is not judged against the project's guards.git.repo", foreign.status, 0]);
+  // Stop: work/x is ahead, work/y was never pushed
+  git(dir, 'switch', '-q', '-c', 'work/y');
+  const s1 = stop();
+  cases.push(['Stop with a branch ahead and one missing: refused', s1.status, 2]);
+  cases.push(['the Stop refusal lists both with the push', /work\/x.*1 commit/.test(s1.stderr) && /work\/y.*not on/.test(s1.stderr) && /git push https:\/\/x-access-token:\$PERSONAL_GITHUB_TOKEN@\S+ work\/x work\/y/.test(s1.stderr), true]);
+  cases.push(['the Stop refusal never offers deleting a branch', /branch -[dD]|--delete|delete the branch/.test(s1.stderr), false]);
+  cases.push(['the same refusal again: still refused', stop().status, 2]);
+  stop();
+  const s4 = stop();
+  cases.push(['the fourth identical refusal ends the session, the list goes to the user', s4.status === 0 && /work\/y/.test(s4.stdout), true]);
+  push('work/x', 'work/y');
+  cases.push(['every branch pushed: Stop passes', stop().status, 0]);
+  const h = remoteHeads(dir, 'origin');
+  cases.push(['a look the last one clears makes no network call (the cache)', h.cached === true && h.heads.get('work/y') !== undefined, true]);
+
+  // the remote out of reach: the work goes ahead with a warning
+  commit('three');
+  git(dir, 'remote', 'set-url', 'origin', join(top, 'gone.git'));
+  const off = bash(C);
+  cases.push(['GitHub out of reach: the commit goes ahead', off.status, 0]);
+  cases.push(['and the user is told it was not checked', /could not be reached/.test(off.stdout), true]);
+  cases.push(['GitHub out of reach: Stop goes ahead with a warning', stop().status, 0]);
+
+  // the house laws off: nothing judged
+  git(dir, 'remote', 'set-url', 'origin', hub);
+  put(join(dir, '.claude/layout.json'), JSON.stringify({ folders: {} }));
+  cases.push(['house laws off: an unpushed commit is not judged', bash(C).status, 0]);
+  cases.push(['house laws off: Stop is not judged', stop().status, 0]);
+  rmSync(top, { recursive: true, force: true });
+  return cases;
+}

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

@@ -0,0 +1,33 @@
+// Tiny glob matcher (no dependencies): supports **, *, ? and {a,b}. Paths use "/".
+const cache = new Map();
+const ONE_CHAR = { '*': '[^/]*', '?': '[^/]' }; // a lone * stays inside one folder; ? is one character
+
+export function globToRegExp(glob) {
+  if (cache.has(glob)) return cache.get(glob);
+  let re = '';
+  for (let i = 0; i < glob.length; i += 1) {
+    const c = glob[i];
+    if (c === '*' && glob[i + 1] === '*') {
+      const slash = glob[i + 2] === '/';
+      re += slash ? '(?:.*/)?' : '.*';
+      i += slash ? 2 : 1;
+    } else if (c === '{') {
+      const end = glob.indexOf('}', i);
+      re += `(?:${glob.slice(i + 1, end).split(',').map(escape).join('|')})`;
+      i = end;
+    } else re += Object.hasOwn(ONE_CHAR, c) ? ONE_CHAR[c] : escape(c);
+  }
+  const compiled = new RegExp(`^${re}$`);
+  cache.set(glob, compiled);
+  return compiled;
+}
+
+function escape(s) {
+  return s.replace(/[.+^$()|[\]\\]/g, '\\$&');
+}
+
+// Match against a project-relative path; a leading "**/" also matches files at the root.
+export function matchesAny(relPath, globs) {
+  const p = relPath.replace(/\\/g, '/').replace(/^\.\//, '');
+  return globs.some((g) => globToRegExp(g).test(p));
+}

package/packs/base/hooks/lib/hook-log.mjs

@@ -0,0 +1,100 @@
+// hook-log: every hook's run time, one line per call in the project's .claude/hooks.log (KWB-24: The user saw 17 hooks take 48 s on
+// one rm and nothing said which). A line: ISO time, event, hook, ms, exit code, tool, tab-separated. The node hooks write it
+// through this file (the runner for the hooks it runs, asHook for a hook run on its own); the python ones through
+// lib/house.py's log_hook, the same line. doctor reads it (median and worst per hook over its last 100 calls).
+// Nothing is ever cleared. Past LOG_MAX_BYTES a log moves whole to .claude/logs/ under a dated name and a new one starts (appendRotated).
+// Until a project knows which hooks earn their place it needs all of its history, so no rotated file is deleted.
+// lib/event-log.mjs keeps the detail: every call, and every refusal with its reason.
+//   asHook(name, fn): a hook run as its own process: stdin to fn(text), the time since the process began, logged; the exit code
+//   isMain(import.meta.url): true when this module is the program node was started with (never when the runner imports it)
+//   logHook(root, { event, hook, ms, code, tool })    readHookLog(root) -> [{ time, event, hook, ms, code, tool }]
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, statSync } from 'node:fs';
+import { basename, extname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { logCall } from './event-log.mjs';
+import { readLayout } from './layout.mjs';
+
+export const LOG = join('.claude', 'hooks.log');
+export const LOG_MAX_BYTES = 1024 * 1024;
+export const LOGS = join('.claude', 'logs');
+
+const limits = new Map();
+const maxBytes = (root) => {
+  if (!limits.has(root)) limits.set(root, (readLayout(root).guards?.logs?.maxKb ?? LOG_MAX_BYTES / 1024) * 1024);
+  return limits.get(root);
+};
+const stamp = () => new Date().toISOString().replace(/[-:]/g, '').replace('T', '-').slice(0, 15);
+
+// Moves a full log to .claude/logs/<name>-<time><ext>. A second writer finding it gone just carries on: nothing is lost.
+function rotate(root, file) {
+  const ext = extname(file);
+  const name = basename(file, ext);
+  const dir = join(root, LOGS);
+  mkdirSync(dir, { recursive: true });
+  let to = join(dir, `${name}-${stamp()}${ext}`);
+  for (let n = 1; existsSync(to); n += 1) to = join(dir, `${name}-${stamp()}-${n}${ext}`);
+  renameSync(file, to);
+}
+
+// One or more lines onto a log, rotating it when full. Never throws, never creates .claude: a hook is never stopped by its own log.
+export function appendRotated(root, rel, text) {
+  try {
+    if (!existsSync(join(root, '.claude'))) return;
+    const file = join(root, rel);
+    mkdirSync(join(file, '..'), { recursive: true });
+    appendFileSync(file, text);
+    if (statSync(file).size > maxBytes(root)) rotate(root, file);
+  } catch { /* the log never stops a hook */ }
+}
+
+const real = (p) => { try { return realpathSync(p); } catch { return resolve(p); } };
+export const isMain = (url) => Boolean(process.argv[1]) && real(process.argv[1]) === real(fileURLToPath(url));
+export const projectRoot = () => resolve(process.env.CLAUDE_PROJECT_DIR ?? process.cwd());
+
+export function logHook(root, { event = '-', hook, ms, code, tool = '-' }) {
+  const clean = (v) => String(v ?? '-').replace(/[\t\n]/g, ' ') || '-';
+  appendRotated(root, LOG, `${new Date().toISOString()}\t${clean(event)}\t${clean(hook)}\t${Math.round(ms)}\t${code ?? '-'}\t${clean(tool)}\n`);
+}
+
+// One line per refused concept in .claude/usage.log: time, hook, concept (the shape hooks count what they refuse).
+export function logRefusal(root, hook, concepts) {
+  try {
+    mkdirSync(join(root, '.claude'), { recursive: true });
+    const t = new Date().toISOString();
+    appendRotated(root, join('.claude', 'usage.log'), [...new Set(concepts)].map((c) => `${t}\t${hook}\t${c}\n`).join(''));
+  } catch { /* the count is a report, never a reason to fail the hook */ }
+}
+
+// The live log, or with `{ rotated: true }` every line it ever held (doctor's crash report: a crash is not over because its line moved).
+export function readHookLog(root, { rotated = false } = {}) {
+  const old = rotated ? rotatedHookLogs(root) : [];
+  const text = [...old, join(root, LOG)].map((f) => { try { return readFileSync(f, 'utf8'); } catch { return ''; } }).join('\n');
+  return text.split('\n').filter(Boolean).map((l) => l.split('\t')).filter((c) => c.length >= 5 && /^\d+$/.test(c[3]))
+    .map(([time, event, hook, ms, code, tool]) => ({ time, event, hook, ms: Number(ms), code, tool: tool ?? '-' }));
+}
+
+function rotatedHookLogs(root) {
+  try { return readdirSync(join(root, LOGS)).filter((f) => /^hooks-.*\.log$/.test(f)).sort().map((f) => join(root, LOGS, f)); } catch { return []; }
+}
+
+const eventOf = (text) => { try { const p = JSON.parse(text); return { event: p.hook_event_name, tool: p.tool_name ?? p.source }; } catch { return {}; } };
+
+// A hook run on its own: the time is from the process's start (node's own start-up included, which is what a hook costs).
+export async function asHook(name, fn) {
+  let text = '';
+  try { text = readFileSync(0, 'utf8'); } catch { /* no stdin */ }
+  const said = [];
+  const write = process.stderr.write.bind(process.stderr);
+  process.stderr.write = (chunk, ...rest) => { said.push(String(chunk)); return write(chunk, ...rest); };
+  let code;
+  try {
+    code = await fn(text);
+  } finally {
+    process.stderr.write = write;
+    const hook = name ?? basename(process.argv[1] ?? '-').replace(/\.\w+$/, '');
+    const root = projectRoot();
+    logHook(root, { ...eventOf(text), hook, ms: performance.now(), code: code ?? 1 });
+    logCall(root, text, [{ hook, ms: performance.now(), code: code ?? 1, reason: said.join('') }], appendRotated);
+  }
+  return code ?? 0;
+}

package/packs/base/hooks/lib/house.py

@@ -0,0 +1,77 @@
+"""house: what the python hooks share: the project root, its .claude/layout.json and a guard's settings.
+
+A hook imports it with its own folder's lib/ on sys.path and byte-code writing off, so no __pycache__ appears in a project:
+
+    sys.dont_write_bytecode = True; sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "lib"))
+    import house
+
+A project's values for a guard live in layout.json under "guards": { "<guard>": { ... } }; a key it does not set takes the
+hook's default, so a project with no "guards" gets the house defaults.
+"""
+import json, os, re, time
+
+LOG = os.path.join(".claude", "hooks.log")
+LOG_MAX_BYTES = 1024 * 1024
+
+
+def project_root():
+    """The project the session runs in (CLAUDE_PROJECT_DIR), else the current folder."""
+    return os.path.abspath(os.environ.get("CLAUDE_PROJECT_DIR") or os.getcwd())
+
+
+def main_root(path):
+    """A path inside <project>/.claude/worktrees/<name>/ belongs to <project>; any other path is returned as it is."""
+    m = re.match(r"^(.*?)/\.claude/worktrees/[^/]+(?:/|$)", path.replace(os.sep, "/"))
+    return m.group(1) if m else path
+
+
+def layout(root=None):
+    try:
+        with open(os.path.join(root or project_root(), ".claude", "layout.json"), encoding="utf-8") as f:
+            return json.load(f)
+    except (OSError, ValueError):
+        return {}
+
+
+def guard(name, defaults, root=None):
+    """The guard's settings: its defaults, overridden key by key by layout.json's guards.<name>."""
+    got = (layout(root).get("guards") or {}).get(name) or {}
+    return {**defaults, **got}
+
+
+def shell_writes(command, cwd):
+    """The files a shell command writes, with their text before and after: [{path, op, before, after}] (after None when it
+    cannot be known). One reader of the shell for every hook: lib/shell-writes.mjs, run by node (WB-69)."""
+    import subprocess
+    lib = os.path.join(os.path.dirname(os.path.abspath(__file__)), "shell-writes.mjs")
+    try:
+        r = subprocess.run(["node", lib, "--json"], input=json.dumps({"command": command, "cwd": cwd}), capture_output=True, text=True, timeout=15)
+        return json.loads(r.stdout) if r.returncode == 0 and r.stdout.strip() else []
+    except Exception:
+        return []
+
+
+def folders_of_kind(lay, kind):
+    """The paths of every layout folder of one kind ("copy": a read-only copy of another project's code)."""
+    return [f["path"].rstrip("/") for f in (lay.get("folders") or {}).values() if isinstance(f, dict) and f.get("kind") == kind]
+
+
+def log_hook(hook, event, ms, code, tool="-", root=None):
+    """One timing line per call in <project>/.claude/hooks.log, the same line lib/hook-log.mjs writes (KWB-24): ISO time,
+    event, hook, ms, exit code, tool, tab-separated; past LOG_MAX_BYTES it moves whole to .claude/logs/, never cut. Never raises,
+    never creates .claude. ms is from the hook's own start (python's start-up before it is not counted)."""
+    try:
+        base = root or project_root()
+        if not os.path.isdir(os.path.join(base, ".claude")):
+            return
+        path = os.path.join(base, LOG)
+        clean = lambda v: (str(v if v is not None else "-").replace("\t", " ").replace("\n", " ") or "-")
+        now = time.strftime("%Y-%m-%dT%H:%M:%S", time.gmtime()) + ".%03dZ" % int((time.time() % 1) * 1000)
+        with open(path, "a", encoding="utf-8") as f:
+            f.write(f"{now}\t{clean(event)}\t{clean(hook)}\t{round(ms)}\t{code}\t{clean(tool)}\n")
+        if os.path.getsize(path) > LOG_MAX_BYTES:
+            logs = os.path.join(base, ".claude", "logs")
+            os.makedirs(logs, exist_ok=True)
+            os.rename(path, os.path.join(logs, "hooks-" + time.strftime("%Y%m%d-%H%M%S", time.gmtime()) + ".log"))
+    except Exception:
+        pass

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

@@ -0,0 +1,66 @@
+// One row per language, for the statement reader (0.25.0: every language, because AI writes the same thing over and over). A row says how
+// to blank a file's comments and strings, where a statement ends, what is not code, and how a function is defined. A new language is one row.
+//   languageOf(ext) -> the row, or null                 ALL_CODE: every extension the table reads
+import { blankCode } from './cpp-scan.mjs';
+
+const spaces = (s) => s.replace(/[^\n]/g, ' ');
+
+// A blanker for a language with no blanker of its own: comments go, strings keep their quotes so they stay one token, at the same offsets.
+function blanker({ line = [], block = [], quotes = ['"', "'"], raw = [], hashWord = false, heredoc = false }) {
+  const opener = (src, i) => raw.find((q) => src.startsWith(q, i));
+  return (src) => {
+    let out = '';
+    let i = 0;
+    const skipTo = (stop, keepQuotes) => {
+      const body = src.slice(i, stop);
+      out += keepQuotes && body.length >= 2 ? `"${spaces(body.slice(1, -1))}"` : spaces(body);
+      i = stop;
+    };
+    while (i < src.length) {
+      const here = src[i];
+      const pair = block.find(([a]) => src.startsWith(a, i));
+      const atWord = !hashWord || i === 0 || /\s/.test(src[i - 1]);
+      const q = opener(src, i);
+      const doc = heredoc && src.startsWith('<<', i) ? src.slice(i).match(/^<<-?\s*['"]?([A-Za-z_]\w*)['"]?[^\n]*\n/) : null;
+      if (pair) { const e = src.indexOf(pair[1], i + pair[0].length); skipTo(e === -1 ? src.length : e + pair[1].length, false); }
+      else if (line.some((c) => src.startsWith(c, i)) && atWord) { const e = src.indexOf('\n', i); skipTo(e === -1 ? src.length : e, false); }
+      else if (q) { const e = src.indexOf(q, i + q.length); skipTo(e === -1 ? src.length : e + q.length, true); }
+      else if (doc) {
+        const end = src.slice(i).search(new RegExp(`\\n[ \\t]*${doc[1]}[ \\t]*(?:\\n|$)`));
+        out += src.slice(i, i + doc[0].length); i += doc[0].length;
+        skipTo(end === -1 ? src.length : src.indexOf('\n', i + end - doc[0].length + 1), false);
+      } else if (quotes.includes(here)) {
+        let j = i + 1;
+        while (j < src.length && src[j] !== here && (src[j] !== '\n' || heredoc)) j += src[j] === '\\' ? 2 : 1;
+        skipTo(Math.min(j + 1, src.length), true);
+      } else { out += here; i += 1; }
+    }
+    return out;
+  };
+}
+
+const SLASHES = { line: ['//'], block: [['/*', '*/']] };
+const lineStart = (words) => new RegExp(`^[ \\t]*(?:${words})\\b.*$`, 'gm');
+
+export const LANGUAGES = [
+  { name: 'c', exts: ['.c', '.cc', '.cpp', '.cxx', '.h', '.hh', '.hpp', '.mm'], blank: blankCode, notCode: /^[ \t]*(?:#(?:.*\\\n)*.*|using\b.*)$/gm, minTokens: 60,
+    define: /^(?:[A-Za-z_][\w:<>,*& ]*[\s*&])?([A-Za-z_]\w*)\s*\([^;{}]*\)\s*(?:const\s*)?(?:noexcept\s*)?\{/gm },
+  { name: 'js', exts: ['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.mts', '.cts'], blank: blankCode, lines: true, notCode: /^[ \t]*import\b[^;]*;?$/gm, minTokens: 60,
+    define: /^(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function\*?\s+([A-Za-z_$][\w$]*)|(?:const|let)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>|class\s+([A-Za-z_$][\w$]*))/gm },
+  { name: 'python', exts: ['.py', '.pyi'], blank: blanker({ line: ['#'], raw: ['"""', "'''"] }), lines: true, notCode: /^[ \t]*(?:from\s+\S+\s+)?import\b.*$/gm, minTokens: 45,
+    define: /^(?:async\s+)?(?:def|class)\s+([A-Za-z_]\w*)/gm },
+  { name: 'shell', exts: ['.sh', '.bash', '.zsh', '.ksh'], blank: blanker({ line: ['#'], hashWord: true, heredoc: true }), lines: true, commands: true, minTokens: 30,
+    token: /"\s*"|'\s*'|[^\s;|&()<>{}]+|[;|&()<>{}]/g, notCode: /^[ \t]*(?:\.|source|set|shopt|trap|cd)\s.*$/gm, define: /^(?:function\s+)?([A-Za-z_][\w-]*)\s*(?:\(\s*\))?\s*\{/gm },
+  { name: 'go', exts: ['.go'], blank: blanker({ ...SLASHES, raw: ['`'] }), lines: true, notCode: /^(?:package\b.*|import\s*\([^)]*\)|import\b.*)$/gm, minTokens: 50, define: /^func\s+([A-Za-z_]\w*)/gm },
+  { name: 'rust', exts: ['.rs'], blank: blanker({ ...SLASHES, quotes: ['"'] }), notCode: lineStart('use|mod|extern|pub use'), minTokens: 60, define: /^(?:pub(?:\([a-z]+\))?\s+)?(?:async\s+)?fn\s+([A-Za-z_]\w*)/gm },
+  { name: 'java', exts: ['.java', '.cs', '.scala', '.dart'], blank: blanker(SLASHES), notCode: lineStart('import|package|using|namespace'), minTokens: 60,
+    define: /^[ \t]*(?:public|private|protected|internal|static|final|async|override|virtual|\s)+[\w<>[\],\s]+\s([A-Za-z_]\w*)\s*\([^;{}]*\)\s*(?:throws [\w, ]+)?\s*\{/gm },
+  { name: 'kotlin', exts: ['.kt', '.kts', '.swift'], blank: blanker({ ...SLASHES, raw: ['"""'] }), lines: true, notCode: lineStart('import|package'), minTokens: 50, define: /^(?:(?:public|private|internal)\s+)?(?:fun|func)\s+([A-Za-z_]\w*)/gm },
+  { name: 'ruby', exts: ['.rb', '.rake'], blank: blanker({ line: ['#'], block: [['=begin', '=end']] }), lines: true, notCode: lineStart('require|require_relative|include'), minTokens: 45, define: /^\s*def\s+(?:self\.)?([A-Za-z_]\w*[?!]?)/gm },
+  { name: 'php', exts: ['.php'], blank: blanker({ line: ['//', '#'], block: [['/*', '*/']] }), notCode: lineStart('use|namespace|require|include'), minTokens: 60, define: /^\s*(?:public\s+|private\s+|protected\s+|static\s+)*function\s+([A-Za-z_]\w*)/gm },
+  { name: 'lua', exts: ['.lua'], blank: blanker({ line: ['--'], block: [['--[[', ']]']] }), lines: true, notCode: /^$^/gm, minTokens: 45, define: /^(?:local\s+)?function\s+([A-Za-z_][\w.:]*)/gm },
+];
+
+const BY_EXT = new Map(LANGUAGES.flatMap((l) => l.exts.map((e) => [e, l])));
+export const languageOf = (ext) => BY_EXT.get(ext) ?? null;
+export const ALL_CODE = new Set(BY_EXT.keys());

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

@@ -0,0 +1,54 @@
+// .claude/layout.json is the one source of truth for where things live:
+//   { "folders": { name: { "path", "purpose" } }, "concepts": { concept: [folderName | glob, ...] } }
+// Rules, lesson checks, the folder-law hook and the CLAUDE.md layout section all read it.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function readLayout(root) {
+  try {
+    return JSON.parse(readFileSync(join(root, '.claude', 'layout.json'), 'utf8'));
+  } catch {
+    return { folders: {}, concepts: {} };
+  }
+}
+
+// A concept entry is a folder name (expands to "<path>/**"), "kind:<k>" (every folder whose
+// "kind" is k, e.g. "kind:copy" for the copy trees; none is no glob), or a raw glob.
+export function conceptGlobs(layout, concept) {
+  const entries = layout.concepts?.[concept];
+  if (!entries) return null;
+  const out = [];
+  for (const e of entries) {
+    const folder = layout.folders?.[e];
+    const globs = folder ? [`${folder.path}/**`] : e.startsWith('kind:') ? foldersOfKind(layout, e.slice(5)).map((p) => `${p}/**`) : [e];
+    for (const glob of globs) if (!out.includes(glob)) out.push(glob);
+  }
+  return out;
+}
+
+// The paths of every layout folder of one kind ("copy": read-only copies of another project's code).
+export function foldersOfKind(layout, kind) {
+  return Object.values(layout.folders ?? {}).filter((f) => f.kind === kind).map((f) => f.path.replace(/\/+$/, ''));
+}
+
+// Concepts from packs that aren't installed (e.g. "world" in a project without the stellix pack)
+// are skipped; a rule must still resolve to at least one glob.
+export function globsForConcepts(layout, concepts) {
+  const out = [];
+  for (const c of concepts) for (const g of conceptGlobs(layout, c) ?? []) if (!out.includes(g)) out.push(g);
+  if (out.length === 0) throw new Error(`none of the concepts [${concepts.join(', ')}] exist in .claude/layout.json`);
+  return out;
+}
+
+// Folders that may hold source code: every folder except docs/tools, deepest first.
+export function codeFolders(layout) {
+  return Object.entries(layout.folders ?? {})
+    .filter(([name]) => !['docs', 'tools', 'src'].includes(name))
+    .map(([, f]) => f.path)
+    .sort((a, b) => b.length - a.length);
+}
+
+// "@alias" entries in a check's exclude/globs resolve to layout.files[alias]; other entries pass through.
+export function resolveAliases(layout, entries = []) {
+  return entries.map((e) => (e.startsWith('@') ? layout.files?.[e.slice(1)] ?? `__missing_alias_${e.slice(1)}__` : e));
+}