@warren-dean/code-kit 0.3.4

package/bin/code-kit.mjs

@@ -0,0 +1,398 @@
+#!/usr/bin/env node
+// Run from the project root: node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" <command>
+//   check                 validate the config and summarise it
+//   who <path>...         who may write each path, and its layer
+//   unowned               tracked files nobody may write
+//   diff                  what a draft changes against the live config, and whose files move
+//   baseline [--write]    layer violations in the code as it is (brownfield adoption); --write records them
+//   graph [--depth N]     which folders import which (to find the layers in existing code)
+//   verify [--base ref] [--branch name] [--no-checks]
+//                         the rules for everything this branch changed since base (for CI and review)
+//   status [--base ref] [--json]
+//                         each story and requirement in the plan: built, in review, ready, blocked, tested
+//   adapters              other tools detected in the project, what each adds to the rules, and its setup
+//   trace <path> [--json] what a file is for: the requirements it delivers, its lane, its layer rules
+//   next [--base ref] [--json]
+//                         the step to take now (spec-design, init, dispatch, review…), from the project's state
+// --config <file> reads a draft (.claude/code-kit.draft.json) instead of .claude/code-kit.json.
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { posix, resolve } from 'node:path';
+import { BASELINE_FILE, loadBaseline } from '../hooks/lib/baseline.mjs';
+import { CONFIG_FILE, effectiveConfig, validate } from '../hooks/lib/config.mjs';
+import { diffConfigs, ownershipMoves } from '../hooks/lib/diff.mjs';
+import { CODE, importsOf, layerOf, layerProblems, targetOf } from '../hooks/lib/layers.mjs';
+import { ADAPTERS, activeAdapters } from '../hooks/lib/adapters/index.mjs';
+import { nextStep } from '../hooks/lib/next.mjs';
+import { traceFile } from '../hooks/lib/trace.mjs';
+import { buildStatus } from '../hooks/lib/plan.mjs';
+import { currentBranch, ownerOf } from '../hooks/lib/rules.mjs';
+import { laneOfBranch, verifyBranch } from '../hooks/lib/verify.mjs';
+
+const out = (s) => process.stdout.write(`${s}\n`);
+const die = (s) => {
+  process.stderr.write(`${s}\n`);
+  process.exit(1);
+};
+
+const args = process.argv.slice(2);
+const option = (name) => {
+  const at = args.indexOf(name);
+  return at >= 0 ? args.splice(at, 2)[1] : undefined;
+};
+const file = option('--config') ?? CONFIG_FILE;
+const depth = Number(option('--depth') ?? 2);
+const baseRef = option('--base');
+const branchName = option('--branch');
+const FLAGS = ['--write', '--no-checks', '--json'];
+const flag = (name) => args.includes(name);
+const writeBaseline = flag('--write');
+const [command, ...rest] = args.filter((a) => !FLAGS.includes(a));
+
+const tracked = () =>
+  execFileSync('git', ['ls-files'], { encoding: 'utf8' }).split('\n').filter(Boolean);
+const read = (path) => readFileSync(resolve(path), 'utf8');
+
+function load(path = file) {
+  let raw;
+  try {
+    raw = JSON.parse(read(path));
+  } catch (e) {
+    die(`${path}: ${e.message}`);
+  }
+  const problems = validate(raw);
+  if (problems.length) die(`${path} is invalid:\n  ${problems.join('\n  ')}`);
+  return { raw, config: effectiveConfig(raw, '.') };
+}
+
+function check() {
+  const { raw } = load();
+  out(`${file} is valid.`);
+  out(`Lead: ${raw.lead.paths.join(', ')}`);
+  for (const [name, lane] of Object.entries(raw.lanes))
+    out(`Lane ${name} (${lane.agent}): ${lane.paths.join(', ')}`);
+  for (const l of raw.layers ?? []) out(`Layer ${l.name} → ${l.mayImport.join(', ') || 'nothing'}`);
+  for (const c of raw.checks ?? []) out(`Check ${c.name}: ${c.run.join(' && ')}`);
+  if (!raw.docs?.specs) out('No docs.specs: lanes are not held to a spec-check report.');
+  for (const name of load().config.adapters) out(`Adapter ${name}: active (see \`adapters\`)`);
+}
+
+function who(paths) {
+  const { config } = load();
+  for (const p of paths) {
+    const layer = layerOf(p, config.layers);
+    out(`${p}: ${ownerOf(p, config) ?? 'nobody'}${layer ? ` · layer ${layer.name}` : ''}`);
+  }
+}
+
+function unowned() {
+  const { config } = load();
+  const files = tracked();
+  const nobody = files.filter((p) => !ownerOf(p, config) && !p.startsWith('.claude/'));
+  nobody.forEach(out);
+  out(`${nobody.length} of ${files.length} tracked files have no owner.`);
+}
+
+function diff() {
+  if (file === CONFIG_FILE)
+    die('Pass the draft to compare: diff --config .claude/code-kit.draft.json');
+  const live = load(CONFIG_FILE);
+  const draft = load(file);
+  const lines = diffConfigs(live.raw, draft.raw);
+  const moves = ownershipMoves(tracked(), live.config, draft.config);
+  if (lines.length === 0 && moves.length === 0) return out('No changes.');
+  lines.forEach(out);
+  const byRoute = Map.groupBy(moves, (m) => `${m.from} → ${m.to}`);
+  for (const [route, files] of byRoute) {
+    out(
+      `Owner ${route}: ${files.length} file(s), e.g. ${files
+        .slice(0, 3)
+        .map((m) => m.file)
+        .join(', ')}`,
+    );
+  }
+}
+
+/** Every layer violation in tracked code, by file. */
+function violations(config) {
+  const found = {};
+  for (const rel of tracked().filter((f) => CODE.test(f) && existsSync(f))) {
+    const problems = layerProblems(rel, read(rel), config);
+    if (problems.length) found[rel] = problems;
+  }
+  return found;
+}
+
+/** What to record: everything at adoption; afterwards only what was already recorded (it only shrinks). */
+function toRecord(found) {
+  if (!existsSync(BASELINE_FILE)) return { keep: found, refused: [] };
+  const before = loadBaseline('.').layers;
+  const keep = {};
+  const refused = [];
+  for (const [rel, problems] of Object.entries(found)) {
+    const known = problems.filter((p) => (before[rel] ?? []).includes(p));
+    if (known.length) keep[rel] = known;
+    refused.push(...problems.filter((p) => !known.includes(p)));
+  }
+  return { keep, refused };
+}
+
+function baseline() {
+  const { config } = load();
+  const found = violations(config);
+  const count = Object.values(found).flat().length;
+  Object.values(found).flat().forEach(out);
+  out(`${count} violation(s) in ${Object.keys(found).length} file(s).`);
+  if (!writeBaseline) return;
+  const { keep, refused } = toRecord(found);
+  const body = { recordedAt: new Date().toISOString(), layers: keep };
+  writeFileSync(BASELINE_FILE, `${JSON.stringify(body, null, 2)}\n`);
+  out(
+    `Recorded ${Object.values(keep).flat().length} in ${BASELINE_FILE}: these don't block; new ones do.`,
+  );
+  if (refused.length) {
+    die(`Not recorded (the baseline only shrinks); fix these instead:\n  ${refused.join('\n  ')}`);
+  }
+}
+
+/** Workspace packages by name (package.json "name" → its folder), plus the config's aliases. */
+function aliases() {
+  const found = {};
+  for (const p of tracked().filter((f) => f.endsWith('/package.json'))) {
+    try {
+      const name = JSON.parse(read(p)).name;
+      if (name) found[name] = posix.dirname(p);
+    } catch {
+      // not a readable manifest
+    }
+  }
+  const configured = existsSync(file) ? (JSON.parse(read(file)).importAliases ?? {}) : {};
+  return { ...found, ...configured };
+}
+
+function graph() {
+  const known = aliases();
+  const files = tracked();
+  // An import names a file without its extension, or a folder (its index): group files by their folder.
+  const stems = new Set(files.map((f) => f.replace(/\.[^./]+$/, '')));
+  const folderOf = (p) => (stems.has(p) || files.includes(p) ? posix.dirname(p) : p);
+  const folder = (p) => folderOf(p).split('/').slice(0, depth).join('/');
+  const edges = new Map();
+  for (const rel of files.filter((f) => CODE.test(f) && existsSync(f))) {
+    for (const spec of importsOf(read(rel))) {
+      const target = targetOf(spec, rel, known);
+      const real =
+        target &&
+        (stems.has(target) || files.some((f) => f === target || f.startsWith(`${target}/`)));
+      if (!real) continue; // a package, or a path that doesn't exist (e.g. text inside a test fixture)
+      const edge = `${folder(rel)} → ${folder(target)}`;
+      if (folder(rel) !== folder(target)) edges.set(edge, (edges.get(edge) ?? 0) + 1);
+    }
+  }
+  [...edges]
+    .sort((a, b) => b[1] - a[1])
+    .forEach(([edge, n]) => out(`${String(n).padStart(5)}  ${edge}`));
+  out(`${edges.size} folder-to-folder dependencies at depth ${depth}.`);
+}
+
+const refExists = (ref) => {
+  try {
+    execFileSync('git', ['rev-parse', '--verify', '--quiet', ref], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/** The branch work merges into: --base, else the first protected branch (on origin first when `remote`); null if none exists. */
+function findBase(config, remote) {
+  if (baseRef) return refExists(baseRef) ? baseRef : die(`--base ${baseRef} is not a known ref.`);
+  const name = config.branches.protected[0];
+  const order = remote ? [`origin/${name}`, name] : [name, `origin/${name}`];
+  return order.find(refExists) ?? null;
+}
+
+function base(config, remote) {
+  const name = config.branches.protected[0];
+  return (
+    findBase(config, remote) ?? die(`Neither ${name} nor origin/${name} exists; pass --base <ref>.`)
+  );
+}
+
+const VERIFY_GROUPS = {
+  ownership: 'Ownership',
+  protected: 'Protected paths and the approval log',
+  layers: 'Layer rules',
+  baseline: 'Baseline',
+  design: 'Designs before screens',
+  checks: 'Checks',
+};
+
+function verify() {
+  const { config } = load();
+  const from = base(config, true);
+  let branch = branchName;
+  if (!branch) {
+    try {
+      branch = currentBranch('.');
+    } catch {
+      branch = null;
+    }
+  }
+  const lane = laneOfBranch(branch, config);
+  const { changed, found } = verifyBranch({
+    root: resolve('.'),
+    base: from,
+    config,
+    lane,
+    checks: !flag('--no-checks'),
+  });
+  out(
+    `${changed.length} file(s) changed since ${from}${lane ? `, held to the ${lane} lane (branch ${branch})` : ''}.`,
+  );
+  let count = 0;
+  for (const [key, title] of Object.entries(VERIFY_GROUPS)) {
+    if (!found[key].length) continue;
+    count += found[key].length;
+    out(`\n${title}:`);
+    for (const p of found[key]) out(`  ${p.split('\n').join('\n    ')}`);
+  }
+  if (count) die(`\n${count} problem(s). Fix them on this branch.`);
+  out('No problems.');
+}
+
+const pad = (s, n) => String(s).padEnd(n);
+
+function status() {
+  const { config } = load();
+  const { specs, plan } = config.docs ?? {};
+  if (!specs || !plan)
+    die('status needs docs.specs and docs.plan in the config. The spec-design skill writes both.');
+  const from = base(config, false);
+  const {
+    stories,
+    requirements: byRequirement,
+    problems,
+    drift,
+  } = buildStatus('.', config, from, tracked());
+
+  if (flag('--json')) {
+    out(
+      JSON.stringify(
+        { base: from, stories, requirements: byRequirement, problems, drift },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+  out(`Stories (against ${from}):`);
+  for (const s of stories) {
+    const detail =
+      s.state === 'blocked'
+        ? `waits on ${s.waitingOn.join(', ')}`
+        : s.state === 'review'
+          ? `${s.ahead} commit(s) on ${s.branch}${s.worktree ? ` · ${s.worktree}` : ''}`
+          : s.branchExists
+            ? s.branch
+            : '';
+    out(
+      `  ${pad(s.id, 7)} ${pad(s.state, 12)} ${pad(s.lane || '-', 10)} ${pad(s.requirements.join(', '), 24)} ${detail}`.trimEnd(),
+    );
+  }
+  out('\nRequirements:');
+  for (const r of byRequirement) {
+    const tests = r.tests.length ? `tested (${r.tests.join(', ')})` : 'no test names it';
+    out(
+      `  ${pad(r.id, 10)} ${pad(r.state, 12)} ${pad(r.stories.join(', ') || '-', 14)} ${r.removed ? '' : tests}`.trimEnd(),
+    );
+  }
+  const counts = Map.groupBy(byRequirement, (r) => r.state);
+  const live = byRequirement.filter((r) => !r.removed);
+  out(
+    `\n${live.length} requirement(s): ${[...counts]
+      .filter(([k]) => k !== 'removed')
+      .map(([k, v]) => `${v.length} ${k}`)
+      .join(', ')}; ${live.filter((r) => r.tests.length).length} named by a test.`,
+  );
+  const ready = stories.filter((s) => s.state === 'ready').map((s) => s.id);
+  if (ready.length) out(`Ready to dispatch: ${ready.join(', ')}`);
+  if (drift.length) {
+    out('\nThe plan is out of date:');
+    for (const d of drift) out(`  ${d.story}: the plan says ${d.plan}, git says ${d.actual}`);
+  }
+  if (problems.length) {
+    out('\nGaps between the specs and the plan:');
+    problems.forEach((p) => out(`  ${p}`));
+  }
+}
+
+function next() {
+  const step = nextStep(resolve('.'), (config) => findBase(config, false));
+  if (flag('--json')) return out(JSON.stringify(step, null, 2));
+  const command = (s, args) => `/code-kit:${s}${args ? ` ${args}` : ''}`;
+  const actionable = !['wait', 'done'].includes(step.step);
+  out(actionable ? `Next: ${command(step.step, step.args)}` : `Next: ${step.step}`);
+  out(`Why: ${step.why}`);
+  for (const t of step.then) out(`Then: ${command(t.step, t.args)}`);
+  for (const a of step.attention) out(`Note: ${a}`);
+}
+
+function adapters() {
+  const { raw } = load();
+  const active = activeAdapters(raw, '.').map((a) => a.name);
+  for (const a of ADAPTERS) {
+    const off = raw.adapters?.[a.name] === false;
+    const state = active.includes(a.name)
+      ? 'active'
+      : off
+        ? 'switched off in the config'
+        : 'not detected';
+    out(`${a.name}: ${state}`);
+    if (!active.includes(a.name)) continue;
+    const c = a.config ?? {};
+    if (c.lead?.length) out(`  lead writes: ${c.lead.join(', ')}`);
+    if (c.anyActor?.length) out(`  anyone writes: ${c.anyActor.join(', ')}`);
+    for (const p of c.protected ?? [])
+      out(`  protected: ${p.glob} (approval "${p.approval}": ${p.why})`);
+    for (const b of a.shell?.block ?? []) out(`  blocked command: /${b.pattern}/ — ${b.why}`);
+    for (const s of a.setup ?? []) out(`  setup: ${s}`);
+  }
+}
+
+function trace(paths) {
+  const { config } = load();
+  const traces = paths.map((p) => traceFile(resolve('.'), p.replace(/^\.\//, ''), config));
+  if (flag('--json')) return out(JSON.stringify(traces.length === 1 ? traces[0] : traces, null, 2));
+  for (const t of traces) {
+    out(t.path);
+    out(
+      `  owner: ${t.owner ?? 'nobody'}${t.layer ? ` · layer ${t.layer.name} → ${t.layer.mayImport.join(', ') || 'only itself'}` : ''}`,
+    );
+    if (!t.requirements.length) out('  no requirements traced (no commit names a story)');
+    for (const r of t.requirements)
+      out(`  ${r.id} ${r.title}  (${r.spec}; ${r.stories.join(', ')})`);
+  }
+}
+
+const commands = {
+  check,
+  trace: () => (rest.length ? trace(rest) : usage()),
+  adapters,
+  next,
+  verify,
+  status,
+  unowned,
+  diff,
+  baseline,
+  graph,
+  who: () => (rest.length ? who(rest) : usage()),
+};
+function usage() {
+  die(
+    'Usage: code-kit check | who <path>... | unowned | diff | baseline [--write] | graph [--depth N]\n' +
+      '              | verify [--base ref] [--branch name] [--no-checks] | status [--base ref] [--json]\n' +
+      '              | next [--base ref] [--json] | adapters | trace <path>... [--json]   [--config file]',
+  );
+}
+(commands[command] ?? usage)();

package/hooks/guard-bash.mjs

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+// PreToolUse (Bash): blocks destructive and hook-skipping commands, work on protected branches, new
+// dependencies a person hasn't approved, approval forgery, kit edits through the shell by anyone but
+// the lead, the project's own blocked and lane-restricted commands; records protected files in the
+// approval log on commit and scans commits for secrets. Shell writes are also checked afterwards by
+// lane-audit.mjs.
+import { appendFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join, resolve } from 'node:path';
+import { addedPackages, dependencyApproval } from './lib/dependencies.mjs';
+import { block, start } from './lib/hook.mjs';
+import {
+  APPROVAL_LOG,
+  actorFor,
+  approval,
+  approvalHowTo,
+  currentBranch,
+  dependencyChange,
+  dependencyGrants,
+  owns,
+  protectedEntry,
+  sessionRoot,
+} from './lib/rules.mjs';
+
+const { input, project, config, error } = start();
+const cmd = String(input.tool_input?.command || '');
+
+const ALWAYS = [
+  [/\bgit\s+push\b.*(--force\b|\s-f\b|--force-with-lease\b)/, 'Force-push is not allowed.'],
+  [/--no-verify\b/, 'Skipping git hooks is not allowed.'],
+  [
+    /\brm\s+-rf?\s+(\/|~|\$HOME|\.\.?)(\s|$)/,
+    'Refusing a destructive delete of a root, home or parent directory.',
+  ],
+  [/\b(curl|wget)\b[^|]*\|\s*(sh|bash|zsh)\b/, 'Piping downloads into a shell is not allowed.'],
+  [/\.claude\/approvals/, 'Approvals are created only by a person, with a `!` shell command.'],
+  [
+    /approval-log\.jsonl/,
+    'The approval audit log is appended only by the commit hook; nobody edits it.',
+  ],
+];
+for (const [re, why] of ALWAYS) {
+  if (re.test(cmd)) block(`Blocked: ${why}\nCommand: ${cmd}`);
+}
+const packages = addedPackages(cmd);
+if (error) {
+  if (/\bgit\s+commit\b/.test(cmd)) block(`Blocked: ${error}\nFix the config before committing.`);
+  if (packages.length)
+    block(`Blocked: ${error}\nNew dependencies wait until the config is valid.\nCommand: ${cmd}`);
+  process.exit(0);
+}
+
+const branches = config.branches.protected
+  .map((b) => b.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+  .join('|');
+if (new RegExp(`\\bgit\\s+push\\b.*\\b(${branches})\\b`).test(cmd)) {
+  block(
+    `Blocked: push to your own branch; a person merges to ${config.branches.protected[0]} after review.\nCommand: ${cmd}`,
+  );
+}
+for (const { pattern, why } of config.shell.block) {
+  if (new RegExp(pattern).test(cmd)) block(`Blocked: ${why}\nCommand: ${cmd}`);
+}
+
+const sessionIn = sessionRoot(input, project);
+const actor = actorFor(input, sessionIn ?? project, config);
+
+// Each new package needs a person's approval, for this actor; it also covers the manifest and lockfile
+// changes the install makes (lib/rules.mjs › dependencyChange).
+if (packages.length) {
+  if (actor.kind === 'readonly')
+    block(`Blocked: ${actor.label} is read-only; it may not add dependencies.\nCommand: ${cmd}`);
+  const unapproved = packages.filter(
+    (p) => !approval(sessionIn ?? project, dependencyApproval(p), actor),
+  );
+  if (unapproved.length) {
+    const ask =
+      actor.kind === 'lead'
+        ? 'Ask the person to approve it by running'
+        : "Write a short change request for the lead (the package, why, and the lane's story), and stop. The lead asks the person to run";
+    block(
+      `Blocked: a new dependency (${unapproved.join(', ')}) needs a person's approval. ${ask}\n${approvalHowTo(
+        unapproved.map(dependencyApproval),
+        actor,
+        sessionIn ?? project,
+        'installing it, and the manifest and lockfile changes that makes,',
+      )}\nCommand: ${cmd}`,
+    );
+  }
+}
+for (const { pattern, lanes, why } of config.shell.restricted) {
+  const allowed = actor.kind === 'lead' || (actor.kind === 'lane' && lanes.includes(actor.lane));
+  if (!allowed && new RegExp(pattern).test(cmd))
+    block(`Blocked: the ${actor.label} may not run this. ${why}\nCommand: ${cmd}`);
+}
+
+// Git commands run against the repository they name (`git -C dir`) or the one the shell is in. Another
+// repository (not this project or one of its worktrees) follows its own rules.
+const gitDir = cmd.match(/\bgit\s+-C\s+("[^"]+"|'[^']+'|\S+)/)?.[1]?.replace(/^["']|["']$/g, '');
+const root = gitDir
+  ? sessionRoot({ cwd: resolve(input.cwd || project, gitDir) }, project)
+  : sessionIn;
+if (!root) process.exit(0);
+
+let branch = '';
+try {
+  branch = currentBranch(root);
+} catch {
+  // not a git repository yet
+}
+if (
+  /\bgit\s+(commit|merge|cherry-pick|rebase|revert)\b/.test(cmd) &&
+  config.branches.protected.includes(branch)
+) {
+  block(
+    `Blocked: never commit or merge on ${branch}. Work on a branch; a person merges after review.`,
+  );
+}
+
+// Kit files edited through the shell follow the same rule as edits through Write/Edit.
+const touchesKit =
+  /\.claude\/(hooks|agents|skills|settings[^/]*\.json|README\.md|code-kit\.json)/.test(cmd);
+// a real redirect into a file; `2>&1` and `>/dev/null` are not writes
+const writes =
+  /((?<![0-9&])>>?\s*(?!&|\/dev\/null)\S|\btee\b|\bsed\s+-i|\bperl\s+-i|\bmv\b|\bcp\b|\brm\b|\bpython3?\b|\bnode\s+-e|\btruncate\b|\bchmod\b|\bln\b)/.test(
+    cmd,
+  );
+if (touchesKit && writes && actor.kind !== 'lead' && !approval(root, 'kit', actor)) {
+  block(
+    `Blocked: the .claude kit is changed only by the lead or with a person's approval. Ask the lead to run\n${approvalHowTo('kit', actor, root)}`,
+  );
+}
+
+/** Files this commit will include: staged now, plus what the same command stages first. */
+function committedFiles() {
+  const git = (...args) =>
+    spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' }).stdout ?? '';
+  const names = (out) => out.split('\n').filter(Boolean);
+  const staged = names(git('diff', '--cached', '--name-only'));
+  // This hook runs before the command, so `git add … && git commit` and `git commit -a` have not staged yet.
+  const changed = names(git('status', '--porcelain', '-uall', '--no-renames')).map((l) =>
+    l.slice(3),
+  );
+  const commitAll = /\bgit\s+commit\b[^;&|]*\s(-a|--all|-[b-zB-Z]*a[a-zA-Z]*)(\s|$)/.test(cmd);
+  const addAll = /\bgit\s+add\b[^;&|]*\s(-A|--all|\.)(\s|$)/.test(cmd);
+  const addArgs = [...cmd.matchAll(/\bgit\s+add\s+([^;&|]+)/g)]
+    .flatMap((m) => m[1].trim().split(/\s+/))
+    .filter((a) => a && !a.startsWith('-'));
+  const added = changed.filter(
+    (f) =>
+      commitAll ||
+      addAll ||
+      addArgs.some((a) => f === a || f.startsWith(`${a.replace(/\/$/, '')}/`)),
+  );
+  return { files: [...new Set([...staged, ...added])], git };
+}
+
+// Every committed protected file is recorded in the audit log, with the person's reason when an
+// approval is in force. So is a lane's manifest or lockfile change, outside its own paths, made under a
+// dependency approval: that entry is how `code-kit verify` accepts it. The log is staged into the same
+// commit, so record and change land together.
+function recordApprovals() {
+  const { files, git } = committedFiles();
+  const lines = [];
+  const record = (file, fields) =>
+    lines.push(
+      JSON.stringify({
+        at: new Date().toISOString(),
+        ...fields,
+        file,
+        branch,
+        actor: actor.label,
+        session: input.session_id ?? null,
+      }),
+    );
+  for (const file of files) {
+    const entry = protectedEntry(file, config);
+    const granted = entry && approval(root, entry.approval, actor);
+    const byDependency = actor.kind === 'lane' && dependencyChange(actor, file, root, config);
+    if (entry && !granted && actor.kind !== 'lead' && !byDependency) {
+      block(
+        `Blocked: ${file} is ${entry.why}; committing it needs a person's approval in force. Ask the lead to run\n${approvalHowTo(entry.approval, actor, root)}`,
+      );
+    }
+    if (granted)
+      record(file, {
+        approval: entry.approval,
+        reason: granted.reason,
+        grantedAt: granted.grantedAt,
+      });
+    else if (byDependency && (entry || !owns(actor, file, config))) {
+      const grants = dependencyGrants(root, actor);
+      record(file, {
+        approval: 'dependency',
+        packages: grants.map((g) => g.name),
+        reason: grants.map((g) => g.reason).join('; '),
+        grantedAt: grants[0].grantedAt,
+      });
+    } else if (entry)
+      record(file, {
+        approval: 'lead',
+        reason: 'Lead change; reviewed in the pull request',
+        grantedAt: null,
+      });
+  }
+  if (lines.length === 0) return;
+  appendFileSync(join(root, APPROVAL_LOG), `${lines.join('\n')}\n`);
+  git('add', APPROVAL_LOG);
+}
+
+if (/\bgit\s+commit\b/.test(cmd)) {
+  recordApprovals();
+  const scan = spawnSync('gitleaks', ['protect', '--staged', '--redact', '--no-banner'], {
+    cwd: root,
+    encoding: 'utf8',
+  });
+  if (scan.error?.code !== 'ENOENT' && scan.status === 1) {
+    block(
+      `Blocked: gitleaks found possible secrets in staged changes.\n${scan.stdout}${scan.stderr}`,
+    );
+  }
+}
+process.exit(0);

package/hooks/guard-paths.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+// PreToolUse (Edit|MultiEdit|Write|NotebookEdit): who may write where, secret files, approvals,
+// spec-check before lane work, approved designs before screens (lib/rules.mjs), and the layer rules for
+// the file as it would be after the edit, so a layer is never broken on disk even for a moment.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadBaseline, newProblems } from './lib/baseline.mjs';
+import { CONFIG_FILE } from './lib/config.mjs';
+import { layerProblems } from './lib/layers.mjs';
+import { block, start } from './lib/hook.mjs';
+import {
+  actorFor,
+  projectWorktrees,
+  relativeTo,
+  worktreeRoot,
+  writeProblem,
+} from './lib/rules.mjs';
+
+const { input, project, config, error } = start();
+const target = input.tool_input?.file_path || input.tool_input?.notebook_path;
+if (!target) process.exit(0);
+
+const found = worktreeRoot(target);
+const root = found && projectWorktrees(project).includes(found) ? found : project;
+const rel = relativeTo(root, target);
+
+if (error) {
+  // The rules can't be read, so nothing is allowed except the lead repairing them.
+  if (rel === CONFIG_FILE && !input.agent_type) process.exit(0);
+  block(
+    `Blocked: ${error}\nThe lead fixes ${CONFIG_FILE} first; nothing else can be written until it is valid.`,
+  );
+}
+
+const problem = writeProblem(actorFor(input, root, config), rel, root, config);
+if (problem) block(`Blocked: ${problem}`);
+
+/** The file's text after this call, when the call carries enough to know it. */
+function textAfter(before) {
+  const ti = input.tool_input ?? {};
+  const apply = (text, edits) =>
+    edits.reduce((t, e) => {
+      if (!e.old_string) return t;
+      return e.replace_all
+        ? t.split(e.old_string).join(e.new_string ?? '')
+        : t.replace(e.old_string, () => e.new_string ?? '');
+    }, text);
+  if (input.tool_name === 'Write') return typeof ti.content === 'string' ? ti.content : null;
+  if (before === null) return null;
+  if (input.tool_name === 'Edit') return apply(before, [ti]);
+  if (input.tool_name === 'MultiEdit') return apply(before, ti.edits ?? []);
+  return null;
+}
+
+// Only what this edit introduces is refused: a file that already breaks a rule (the baseline, or older
+// code) can still be edited, as long as the edit adds no new violation.
+const file = join(root, rel);
+const before = existsSync(file) ? readFileSync(file, 'utf8') : null;
+const after = textAfter(before);
+if (after !== null) {
+  const existing = new Set(before === null ? [] : layerProblems(rel, before, config));
+  const added = newProblems(rel, layerProblems(rel, after, config), loadBaseline(project)).filter(
+    (p) => !existing.has(p),
+  );
+  if (added.length)
+    block(
+      `Blocked: this edit would break the layer rules (.claude/code-kit.json › layers):\n  ${added.join('\n  ')}\nDepend only on the layers listed, or ask the lead to change the rule.`,
+    );
+}
+process.exit(0);