@warren-dean/code-kit 0.3.4

package/hooks/lib/rules.mjs

@@ -0,0 +1,313 @@
+// Who may write where, from the project's config. Shared by every hook.
+//
+// Actors:
+// - a lane agent (its agent_type is a lane's "agent") writes only that lane's paths;
+// - any other subagent (research, planning, review) is read-only;
+// - the main session in a worktree with a .lane file acts as that lane (a person running a lane);
+// - the main session otherwise is the lead, who writes the lead's paths and delegates the rest.
+// Protected paths are recorded in the approval log whenever they are committed; only the lead may
+// write them without a person's approval.
+//
+// Approvals live in the project's main checkout, so a lane working in its own worktree sees the ones a
+// person gives at the lead's terminal. One for a lane (`<lane>/<name>`) serves that lane only; one
+// without a lane serves every actor.
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { dirname, join, relative, resolve } from 'node:path';
+import { DEPENDENCY_APPROVAL, isDependencyFile } from './dependencies.mjs';
+import { globToRegExp, matchesAny } from './glob.mjs';
+
+export const APPROVAL_LOG = '.claude/approval-log.jsonl';
+export const APPROVALS_DIR = '.claude/approvals';
+export const APPROVAL_MINUTES = 60;
+// Marks a worktree as a lane's, for a person running that lane; the lead creates it, and it is never work.
+export const LANE_FILE = '.lane';
+const NEVER_WRITABLE = [`${APPROVALS_DIR}/**`, APPROVAL_LOG];
+
+/**
+ * The commands a person runs to approve `names` for `actor`, and what that allows. For a lane the
+ * approval is that lane's; the folder is created here so the command works as written.
+ */
+export function approvalHowTo(names, actor, root, allows = 'these edits') {
+  const dir = approvalsDir(root);
+  const scoped = actor?.kind === 'lane' ? join(dir, actor.lane) : dir;
+  try {
+    mkdirSync(scoped, { recursive: true });
+  } catch {
+    // the command then fails visibly for the person, which says the same thing
+  }
+  const shown = relativeTo(projectDir(), scoped);
+  const where = shown.startsWith('..') ? scoped : shown;
+  const lines = [names].flat().map((n) => `  ! echo "<what you are approving>" > ${where}/${n}`);
+  const whom = actor?.kind === 'lane' ? `the ${actor.lane} lane` : 'any agent';
+  return (
+    `${lines.join('\n')}\n` +
+    `(a person runs it; the reason is recorded in ${APPROVAL_LOG}, and it allows ${allows} for ${whom}, for ${APPROVAL_MINUTES} minutes)`
+  );
+}
+
+/** `path` with symlinks resolved, even if it doesn't exist yet (macOS /var → /private/var). */
+export function realPath(path) {
+  let dir = resolve(path);
+  const rest = [];
+  while (!existsSync(dir)) {
+    rest.unshift(dir.slice(dirname(dir).length + 1));
+    dir = dirname(dir);
+  }
+  return join(realpathSync(dir), ...rest);
+}
+
+/** The session's project: the folder Claude Code was opened in. */
+export const projectDir = () => realPath(process.env.CLAUDE_PROJECT_DIR || process.cwd());
+
+/** The git worktree that contains `path` (walking up to an existing directory), or null. */
+export function worktreeRoot(path) {
+  let dir = resolve(path);
+  while (!existsSync(dir)) dir = dirname(dir);
+  if (statSync(dir).isFile()) dir = dirname(dir);
+  try {
+    const top = execFileSync('git', ['-C', dir, 'rev-parse', '--show-toplevel'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return realPath(top.trim());
+  } catch {
+    return null;
+  }
+}
+
+/** The project's worktrees: the main checkout plus any `git worktree add` or agent worktrees. */
+export function projectWorktrees(project = projectDir()) {
+  try {
+    return execFileSync('git', ['-C', project, 'worktree', 'list', '--porcelain'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+      .split('\n')
+      .filter((l) => l.startsWith('worktree '))
+      .map((l) => realPath(l.slice('worktree '.length)));
+  } catch {
+    return [project];
+  }
+}
+
+/** The worktree of this project that the session's cwd is in, or null when it is elsewhere. */
+export function sessionRoot(input, project = projectDir()) {
+  const root = worktreeRoot(input.cwd || project);
+  return root && projectWorktrees(project).includes(root) ? root : null;
+}
+
+/**
+ * The checkout whose changes are this actor's own. A subagent works where its cwd is (often its own
+ * worktree). The main session owns the checkout it was opened in, even when its shell has wandered
+ * into an agent's worktree, whose in-progress edits are that agent's, not the lead's.
+ */
+export function actorRoot(input, project = projectDir()) {
+  if (input.agent_type) return sessionRoot(input, project);
+  return worktreeRoot(project) ?? project;
+}
+
+export const relativeTo = (root, path) =>
+  relative(realPath(root), realPath(resolve(root, path)))
+    .split('\\')
+    .join('/');
+
+export function currentBranch(root) {
+  return execFileSync('git', ['-C', root, 'rev-parse', '--abbrev-ref', 'HEAD'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  }).trim();
+}
+
+/** Who is acting: { kind: 'lead' | 'lane' | 'readonly', lane?, label }. */
+export function actorFor(input, root, config) {
+  const agent = input.agent_type;
+  if (agent) {
+    const lane = Object.keys(config.lanes).find((l) => config.lanes[l].agent === agent);
+    return lane
+      ? { kind: 'lane', lane, label: `${agent} (${lane} lane)` }
+      : { kind: 'readonly', label: agent };
+  }
+  const laneFile = join(root, LANE_FILE);
+  if (existsSync(laneFile)) {
+    const lane = readFileSync(laneFile, 'utf8').trim();
+    return { kind: 'lane', lane, label: `${lane} lane worktree` };
+  }
+  return { kind: 'lead', label: 'lead session' };
+}
+
+/** Where approvals live: the main checkout's approvals folder, shared by all of its worktrees. */
+const approvalDirs = new Map();
+export function approvalsDir(root) {
+  if (!approvalDirs.has(root))
+    approvalDirs.set(root, join(projectWorktrees(root)[0] ?? root, APPROVALS_DIR));
+  return approvalDirs.get(root);
+}
+
+function ownedPaths(actor, config) {
+  if (actor.kind === 'lead') return config.lead.paths;
+  if (actor.kind === 'lane') return config.lanes[actor.lane]?.paths ?? [];
+  return [];
+}
+
+/** Whether `rel` is the actor's own to write: its paths, or the paths any actor may write. */
+export function owns(actor, rel, config) {
+  if (actor.kind === 'readonly') return false;
+  if (matchesAny(rel, config.anyActor)) return true;
+  const excluded = actor.kind === 'lane' ? config.lanes[actor.lane]?.exclude : [];
+  return matchesAny(rel, ownedPaths(actor, config)) && !matchesAny(rel, excluded);
+}
+
+/** An approval file's { reason, grantedAt } while fresh and explained, else null. */
+function inForce(file) {
+  if (!existsSync(file) || !statSync(file).isFile()) return null;
+  const { mtimeMs } = statSync(file);
+  if (Date.now() - mtimeMs >= APPROVAL_MINUTES * 60_000) return null;
+  const reason = readFileSync(file, 'utf8').trim();
+  return reason ? { reason, grantedAt: new Date(mtimeMs).toISOString() } : null;
+}
+
+/** The approval in force for `name` and `actor` (the actor's lane's own, or one for everyone), or null. */
+export function approval(root, name, actor) {
+  const dir = approvalsDir(root);
+  const lane = actor?.kind === 'lane' ? inForce(join(dir, actor.lane, name)) : null;
+  return lane ?? inForce(join(dir, name));
+}
+
+/** The dependency approvals in force for `actor`: [{ name, reason, grantedAt }]. */
+export function dependencyGrants(root, actor) {
+  if (actor?.kind === 'readonly') return [];
+  const dir = approvalsDir(root);
+  const names = (d) => {
+    try {
+      return readdirSync(d).filter((n) => n.startsWith(DEPENDENCY_APPROVAL));
+    } catch {
+      return [];
+    }
+  };
+  const scoped = actor?.kind === 'lane' ? names(join(dir, actor.lane)) : [];
+  return [...new Set([...scoped, ...names(dir)])]
+    .map((name) => ({ name, ...approval(root, name, actor) }))
+    .filter((g) => g.reason);
+}
+
+/**
+ * Whether a dependency approval lets `actor` change `rel`: a manifest or lockfile no other lane owns,
+ * changed while the actor has a dependency approval in force. Installing a package rewrites them.
+ */
+export function dependencyChange(actor, rel, root, config) {
+  if (!isDependencyFile(rel) || actor.kind === 'readonly') return false;
+  const owner = laneOf(rel, config);
+  if (owner && !(actor.kind === 'lane' && owner === actor.lane)) return false;
+  return dependencyGrants(root, actor).length > 0;
+}
+
+/** The protected entry a repo-relative path falls under, or undefined. The log and state are not. */
+export function protectedEntry(rel, config) {
+  if (rel === APPROVAL_LOG || matchesAny(rel, ['.claude/state/**'])) return undefined;
+  return config.protected.find((p) => globToRegExp(p.glob).test(rel));
+}
+
+export const SECRETS = (rel) =>
+  /(^|\/)\.env(\.|$)/.test(rel) ||
+  /(^|\/)secrets?\//.test(rel) ||
+  /\.(pem|p8|p12|keystore|jks)$/.test(rel);
+
+/** Why `actor` may not write `rel` (relative to worktree `root`), or null if allowed. */
+export function writeProblem(actor, rel, root, config) {
+  const approvals = approvalsDir(root);
+  const target = realPath(resolve(root, rel));
+  if (target === approvals || target.startsWith(`${approvals}/`))
+    return `${rel} is an approval. Only a person creates approvals, with a \`!\` shell command.`;
+  if (rel.startsWith('..'))
+    return outsideAllowed(actor, rel, root, config) ? null : `${rel} is outside the repository.`;
+  if (SECRETS(rel))
+    return `${rel} may hold secrets. Secrets never go in files an agent writes; use the secret store.`;
+  if (rel === APPROVAL_LOG)
+    return `${rel} is the approval audit log. Only the commit hook appends to it; nobody edits it.`;
+  if (matchesAny(rel, NEVER_WRITABLE))
+    return `${rel} is an approval. Only a person creates approvals, with a \`!\` shell command.`;
+  // A package a person approved may change the manifests and lockfiles its install rewrites.
+  if (dependencyChange(actor, rel, root, config)) return null;
+  const guarded = protectedEntry(rel, config);
+  // The lead writes protected files without an approval: the person reviews them in the pull request,
+  // and every committed change is in the audit log. Anyone else needs a person's approval as well.
+  if (guarded && actor.kind !== 'lead' && !approval(root, guarded.approval, actor)) {
+    return `${rel} is ${guarded.why} and needs a person's approval. Ask the lead (a person) to run\n${approvalHowTo(guarded.approval, actor, root)}`;
+  }
+  if (actor.kind === 'readonly') return `${actor.label} is read-only; it may not write ${rel}.`;
+  if (matchesAny(rel, config.anyActor)) return null;
+  if (!owns(actor, rel, config)) return ownershipProblem(actor, rel, config);
+  const specs = actor.kind === 'lane' && config.docs?.specs;
+  return (specs && specCheckProblem(rel, root)) || screenProblem(rel, root, config);
+}
+
+function outsideAllowed(actor, rel, root, config) {
+  if (actor.kind !== 'lead') return false;
+  const target = resolve(root, rel);
+  return config.lead.outside.some((g) =>
+    globToRegExp(resolve(root, g.replace(/^~(?=\/)/, homedir()))).test(target),
+  );
+}
+
+function ownershipProblem(actor, rel, config) {
+  const owner = ownerOf(rel, config);
+  const where = owner ? ` (owned by the ${owner}).` : '.';
+  const next =
+    actor.kind === 'lead'
+      ? `\nDelegate it: use the ${owner ?? 'matching'} agent, ideally in its own worktree.`
+      : `\nWrite a short change request for the lead instead, and stop.`;
+  return `The ${actor.label} may not write ${rel}${where}${next}`;
+}
+
+/** The lane whose paths hold `rel`, or null. */
+export function laneOf(rel, config) {
+  return (
+    Object.entries(config.lanes).find(
+      ([, { paths, exclude }]) => matchesAny(rel, paths) && !matchesAny(rel, exclude),
+    )?.[0] ?? null
+  );
+}
+
+export function ownerOf(rel, config) {
+  const lane = laneOf(rel, config);
+  if (lane) return `${lane} lane / ${config.lanes[lane].agent}`;
+  return matchesAny(rel, config.lead.paths) ? 'lead' : null;
+}
+
+// Lane work starts with the spec-check skill: its report for the branch must exist first.
+export function specCheckPath(root) {
+  return `.claude/state/spec-check/${currentBranch(root).replace(/[^\w.-]+/g, '_')}.md`;
+}
+
+function specCheckProblem(rel, root) {
+  let report;
+  try {
+    report = specCheckPath(root);
+  } catch {
+    return null; // not a git worktree: nothing to key the report on
+  }
+  if (rel === report) return null;
+  const file = join(root, report);
+  if (existsSync(file) && /\|\s*Requirement\s*\|/i.test(readFileSync(file, 'utf8'))) return null;
+  return `Run the spec-check skill before writing code on this branch. Save its report (the requirement table, questions and recommendation) to ${report}, then continue.`;
+}
+
+// Screens are designed first: a screen file can be written once the register lists it.
+export function screenProblem(rel, root, config) {
+  const gate = config.designGate;
+  if (!gate) return null;
+  const isScreen = gate.screens.some(
+    (s) => globToRegExp(s.glob).test(rel) && !(s.not && new RegExp(s.not).test(rel)),
+  );
+  if (!isScreen) return null;
+  let screens;
+  try {
+    screens = JSON.parse(readFileSync(join(root, gate.register), 'utf8')).screens ?? [];
+  } catch {
+    return `${gate.register} is missing or invalid, so no screen can be built yet.`;
+  }
+  if (screens.some((s) => s.file === rel)) return null;
+  return `${rel} is a screen, and its design is not approved yet.\n${gate.howTo}\nOnce a person approves it, the lead adds { "file": "${rel}", ... } to ${gate.register}.`;
+}

package/hooks/lib/trace.mjs

@@ -0,0 +1,69 @@
+// What a file is for, in the project's own terms: the requirements it delivers (from the stories that
+// changed it), the lane that owns it, and its layer with what that layer may import. This is the contract
+// other tools read (`code-kit trace <path> --json`); Context Graph's adapter uses it to anchor a file's
+// card in the spec and to show the layer rule before an agent drafts an edit.
+import { execFileSync } from 'node:child_process';
+import { matchesAny } from './glob.mjs';
+import { layerOf } from './layers.mjs';
+import { readRequirements, readStories } from './plan.mjs';
+import { ownerOf } from './rules.mjs';
+
+const git = (root, ...args) => {
+  try {
+    return execFileSync('git', ['-C', root, ...args], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      maxBuffer: 16 * 1024 * 1024,
+    });
+  } catch {
+    return '';
+  }
+};
+
+/** Story ids named by the commits that changed `rel`, and by the current branch if it is a story branch. */
+export function storiesOf(root, rel) {
+  const ids = new Set();
+  for (const m of git(root, 'log', '--format=%B', '--', rel).matchAll(/\bST-\d+\b/g)) ids.add(m[0]);
+  const branch = git(root, 'rev-parse', '--abbrev-ref', 'HEAD').trim();
+  const onBranch = /^[\w-]+\/(st-\d+)$/i.exec(branch)?.[1];
+  if (onBranch) ids.add(onBranch.toUpperCase());
+  return [...ids];
+}
+
+/** { path, owner, lane, layer, requirements: [{ id, title, spec, stories }] } for one repository path. */
+export function traceFile(root, rel, config) {
+  const laneName = Object.keys(config.lanes).find((l) => {
+    const { paths, exclude } = config.lanes[l];
+    return matchesAny(rel, paths) && !matchesAny(rel, exclude);
+  });
+  const layer = layerOf(rel, config.layers);
+  const out = {
+    path: rel,
+    owner: ownerOf(rel, config),
+    lane: laneName ? { name: laneName, agent: config.lanes[laneName].agent } : null,
+    layer: layer
+      ? { name: layer.name, mayImport: layer.mayImport, denyPackages: layer.denyPackages ?? [] }
+      : null,
+    requirements: [],
+  };
+  const { specs, plan } = config.docs ?? {};
+  if (!specs || !plan) return out;
+  const stories = readStories(root, plan);
+  const requirements = new Map(
+    readRequirements(root, specs)
+      .filter((r) => r.file !== plan && !r.removed)
+      .map((r) => [r.id, r]),
+  );
+  const byReq = new Map();
+  for (const id of storiesOf(root, rel)) {
+    const story = stories.find((s) => s.id === id);
+    for (const req of story?.requirements ?? []) {
+      const r = requirements.get(req);
+      if (!r) continue;
+      if (!byReq.has(req)) byReq.set(req, { id: req, title: r.title, spec: r.file, stories: [] });
+      byReq.get(req).stories.push(id);
+    }
+  }
+  out.requirements = [...byReq.values()];
+  return out;
+}

package/hooks/lib/verify.mjs

@@ -0,0 +1,146 @@
+// The rules for a branch's changes as a whole, for CI and the lead's review: the hooks only see work
+// done in Claude Code sessions, so a person's commits or another tool would otherwise go unchecked.
+// Everything is judged from git (base...HEAD), except the checks, which run in the checkout.
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { BASELINE_FILE, loadBaseline, newProblems } from './baseline.mjs';
+import { runChecks } from './checks.mjs';
+import { CONFIG_FILE } from './config.mjs';
+import { isDependencyFile } from './dependencies.mjs';
+import { matchesAny } from './glob.mjs';
+import { layerProblems } from './layers.mjs';
+import { APPROVAL_LOG, SECRETS, laneOf, ownerOf, protectedEntry, screenProblem } from './rules.mjs';
+
+const git = (root, ...args) =>
+  execFileSync('git', ['-C', root, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    maxBuffer: 64 * 1024 * 1024,
+  });
+
+/** A file's content at `ref`, or null when it doesn't exist there. */
+function showAt(root, ref, rel) {
+  try {
+    return git(root, 'show', `${ref}:${rel}`);
+  } catch {
+    return null;
+  }
+}
+
+/** The lane a branch belongs to by its name (`<lane>/<story>`), or null. */
+export function laneOfBranch(branch, config) {
+  const lane = branch?.split('/')[0];
+  return lane && config.lanes[lane] ? lane : null;
+}
+
+/** Files changed on this branch since it left `base`. */
+export function branchChanges(root, base) {
+  return git(root, 'diff', '--name-only', '--no-renames', `${base}...HEAD`)
+    .split('\n')
+    .filter(Boolean);
+}
+
+/** Entries appended to the approval log since commit `from`, plus problems if it was rewritten. */
+function logEntries(root, base) {
+  const before = showAt(root, base, APPROVAL_LOG) ?? '';
+  const after = showAt(root, 'HEAD', APPROVAL_LOG) ?? '';
+  if (!after.startsWith(before))
+    return {
+      entries: [],
+      problems: [`${APPROVAL_LOG} was edited, not appended to; it is append-only.`],
+    };
+  const entries = [];
+  const problems = [];
+  for (const line of after.slice(before.length).split('\n').filter(Boolean)) {
+    try {
+      entries.push(JSON.parse(line));
+    } catch {
+      problems.push(`${APPROVAL_LOG} has an entry that isn't valid JSON: ${line.slice(0, 80)}`);
+    }
+  }
+  return { entries, problems };
+}
+
+/**
+ * Every problem with the branch, grouped: { ownership, protected, layers, baseline, design, checks }.
+ * `lane` holds the branch to that lane's paths; `checks: false` leaves the project's checks to CI's
+ * own steps.
+ */
+export function verifyBranch({ root, base, config, lane = null, checks = true }) {
+  // Where the branch left the base: the base may have moved on since (new log entries, a smaller baseline).
+  const from = git(root, 'merge-base', base, 'HEAD').trim();
+  const changed = branchChanges(root, base);
+  const present = changed.filter((f) => existsSync(join(root, f)));
+  const found = { ownership: [], protected: [], layers: [], baseline: [], design: [], checks: [] };
+  const { entries, problems: logProblems } = logEntries(root, from);
+  found.protected.push(...logProblems);
+  const logged = new Map(entries.map((e) => [e.file, e]));
+
+  for (const f of changed) {
+    if (SECRETS(f))
+      found.ownership.push(`${f} may hold secrets; secrets never go in the repository.`);
+    if (f === APPROVAL_LOG) continue;
+    const guarded = protectedEntry(f, config);
+    if (guarded && !logged.has(f))
+      found.protected.push(
+        `${f} is ${guarded.why}, but no approval-log entry records this change. Protected files are committed through Claude Code with code-kit, which logs them.`,
+      );
+    if (matchesAny(f, config.anyActor)) continue;
+    if (lane) {
+      const { paths, exclude } = config.lanes[lane];
+      const own = matchesAny(f, paths) && !matchesAny(f, exclude);
+      const entry = logged.get(f);
+      // A manifest or lockfile no other lane owns, logged under a person's dependency approval.
+      const dependency =
+        isDependencyFile(f) &&
+        entry?.approval === 'dependency' &&
+        [null, lane].includes(laneOf(f, config));
+      const approved = (guarded && entry?.approval === guarded.approval) || dependency;
+      if (!own && !approved)
+        found.ownership.push(
+          `${f}: the ${lane} lane doesn't own it (owner: ${ownerOf(f, config) ?? 'nobody'}).`,
+        );
+    } else if (!ownerOf(f, config)) {
+      found.ownership.push(`${f}: nobody owns it, so nobody may change it.`);
+    }
+  }
+
+  const baseline = loadBaseline(root);
+  for (const f of present) {
+    found.layers.push(
+      ...newProblems(f, layerProblems(f, readFileSync(join(root, f), 'utf8'), config), baseline),
+    );
+    const screen = screenProblem(f, root, config);
+    if (screen) found.design.push(screen.split('\n')[0]);
+  }
+
+  // The baseline only shrinks once the kit is adopted (the adopting change may record it).
+  if (showAt(root, from, CONFIG_FILE) !== null) {
+    let before = {};
+    try {
+      before = JSON.parse(showAt(root, from, BASELINE_FILE) ?? '{}').layers ?? {};
+    } catch {
+      // an unreadable baseline excused nothing
+    }
+    for (const [f, problems] of Object.entries(baseline.layers))
+      for (const p of problems)
+        if (!(before[f] ?? []).includes(p))
+          found.baseline.push(`${BASELINE_FILE} gained ${p}; it only shrinks.`);
+  }
+
+  if (checks) {
+    const actor = lane
+      ? { kind: 'lane', lane, label: `${lane} lane branch` }
+      : { kind: 'lead', label: 'lead' };
+    const failure = runChecks(config, changed, root, actor);
+    if (failure)
+      found.checks.push(
+        `${failure.title}\n${String(failure.output ?? '')
+          .split('\n')
+          .slice(-40)
+          .join('\n')}`.trim(),
+      );
+  }
+  return { changed, found };
+}

package/hooks/post-edit-check.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// PostToolUse (Edit|MultiEdit|Write): the layer rules for the edited file, then the project's own
+// per-file checks (lint, format); failures are fed back to Claude.
+import { existsSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { matchesAny } from './lib/glob.mjs';
+import { loadBaseline, newProblems } from './lib/baseline.mjs';
+import { block, start } from './lib/hook.mjs';
+import { layerProblems } from './lib/layers.mjs';
+import { projectWorktrees, relativeTo, worktreeRoot } from './lib/rules.mjs';
+
+const { input, project, config, error } = start();
+const target = input.tool_input?.file_path;
+if (error || !target) process.exit(0);
+
+const found = worktreeRoot(target);
+const root = found && projectWorktrees(project).includes(found) ? found : null;
+if (!root) process.exit(0); // another repository, or Claude's memory: not this project's code
+const rel = relativeTo(root, target);
+if (!existsSync(join(root, rel))) process.exit(0);
+
+// Violations recorded in the baseline (brownfield code as it was adopted) don't block; new ones do.
+const layers = layerProblems(rel, readFileSync(join(root, rel), 'utf8'), config);
+const problems = newProblems(rel, layers, loadBaseline(project));
+const quoted = `'${rel.replace(/'/g, `'\\''`)}'`;
+for (const check of config.postEdit) {
+  if (!matchesAny(rel, check.files) || matchesAny(rel, check.exclude)) continue;
+  const res = spawnSync(check.run.replaceAll('{file}', quoted), {
+    cwd: root,
+    shell: true,
+    encoding: 'utf8',
+    timeout: 80_000,
+  });
+  if (res.status === 127) continue; // the tool isn't installed yet (fresh clone)
+  if (res.status !== 0)
+    problems.push(`${check.run.replaceAll('{file}', rel)}:\n${res.stdout}${res.stderr}`.trim());
+}
+if (problems.length) block(`Fix these before continuing:\n\n${problems.join('\n\n')}`);
+process.exit(0);

package/hooks/stop-check.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// Stop / SubagentStop: before an actor finishes, run the checks that prove the work rather than
+// asking it to. Read-only agents are skipped. Order: ownership audit, layer rules on changed files,
+// then each of the project's checks whose files changed; a lane finishes with its work committed.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadBaseline, newProblems } from './lib/baseline.mjs';
+import { runChecks } from './lib/checks.mjs';
+import { block, start } from './lib/hook.mjs';
+import { layerProblems } from './lib/layers.mjs';
+import { actorFor, actorRoot } from './lib/rules.mjs';
+import { auditProblems, changedFiles } from './lane-audit.mjs';
+
+const { input, project, config, error } = start();
+
+// Stop hooks share one `stop_hook_active` flag, so another plugin's block would make this check skip
+// itself. Instead this hook remembers its own last block per session and agent. The same problem
+// reported MAX_REPEATS times in a row means no progress: say so and let the finish through rather than
+// loop. A different problem means progress, and counts from one again.
+const MAX_REPEATS = 3;
+const memory = join(
+  project,
+  '.claude/state/stop-blocks',
+  `${input.session_id ?? 'session'}-${input.agent_id ?? 'main'}`.replace(/[^\w.-]+/g, '_'),
+);
+const lastBlock = () => {
+  try {
+    return JSON.parse(readFileSync(memory, 'utf8'));
+  } catch {
+    return { message: null, count: 0 };
+  }
+};
+const passed = () => {
+  rmSync(memory, { force: true });
+  process.exit(0);
+};
+const blockCounted = (message) => {
+  const last = lastBlock();
+  const count = last.message === message ? last.count + 1 : 1;
+  if (count > MAX_REPEATS) passed();
+  mkdirSync(join(memory, '..'), { recursive: true });
+  writeFileSync(memory, JSON.stringify({ message, count }));
+  const final =
+    count === MAX_REPEATS
+      ? `\n\n(code-kit has reported this ${count} times without progress; it won't block on it again. Tell the lead what is still failing.)`
+      : '';
+  block(`${message}${final}`);
+};
+
+if (error) blockCounted(error);
+
+const root = actorRoot(input, project);
+if (!root) passed();
+const actor = actorFor(input, root, config);
+if (actor.kind === 'readonly') passed();
+
+const fail = (title, out = '') =>
+  blockCounted(`${title}\n\n${String(out).split('\n').slice(-60).join('\n')}`.trim());
+
+const audit = auditProblems({ ...input, cwd: root }, config);
+if (audit.length)
+  fail('Uncommitted changes break the ownership rules; revert them:', audit.join('\n'));
+
+const changed = changedFiles(root);
+const baseline = loadBaseline(project);
+const layers = changed
+  .filter((f) => existsSync(join(root, f)))
+  .flatMap((f) =>
+    newProblems(f, layerProblems(f, readFileSync(join(root, f), 'utf8'), config), baseline),
+  );
+if (layers.length)
+  fail('Imports break the layer rules (.claude/code-kit.json › layers):', layers.join('\n'));
+
+const failure = runChecks(config, changed, root, actor);
+if (failure) fail(failure.title, failure.output);
+
+// A lane hands back committed work on its own branch; the lead reviews and merges it.
+if (actor.kind === 'lane' && changed.length) {
+  fail(
+    "Commit your work on your branch (stage only your lane's files; the message names the task, what changed and the proof), then finish:",
+    changed.join('\n'),
+  );
+}
+passed();