@nurix/etna 0.20.47 → 0.20.48

package/data/harnesses/code/hooks/compliance.mjs

@@ -1,712 +1,33 @@
-// harness/code/hooks/compliance.mjs — the gate-always-waivable hook module.
-// PreToolUse (Edit|Write|MultiEdit|Bash): deny what is never legitimate (frozen records, protected
-// files, plan-gate skips, changelog-less commits, off-catalog packages), ask where intent matters
-// (branches, live commands). Stop: block an arc that tries
-// to end with unresolved bookkeeping or an unrecorded plan completion. Every gate fails open — a
-// crash or unreadable repo allows the action; enforcement is never allowed to become an outage.
+// harness/code/hooks/compliance.mjs — the gate-always-waivable hook module: the thin entry over
+// lib/gates.mjs. PreToolUse (Edit|Write|MultiEdit|Bash) and Stop: read the payload, dispatch, write the
+// decision. Every gate fails open — a crash or unreadable repo allows the action; enforcement is never
+// allowed to become an outage. The one fail-closed exception is Protection (frozen records, protected
+// files), which runs as its own hook, protection.mjs; this module defers to it where it is handled.
 
 import fs from "node:fs";
 import path from "node:path";
-import { readStdin, resolveProjectDir } from "./lib/ownership.mjs";
-import { readSafe, relIfInside, git, commandRoot, backtickTokens, SOURCE_EXT, docsRoot } from "./lib/repo.mjs";
-import { openGatedPlans, inPlanScope } from "./lib/plans.mjs";
-import { stagedExempt } from "./lib/exempt.mjs";
-import { readQueue, countRows, rowsBlockingCommit, askedThisSession, recordAsked } from "./lib/state.mjs";
-import { liveRows } from "./lib/sweep.mjs";
-// frozenStatusAtHead, not frozenStatus: a record frozen only in the WORKTREE is a freeze born in the
-// current edit — a plan legitimately flipping to Complete — and denying that walls the completion
-// ceremony itself, stranding the `Completed:` field the very same edit was meant to fill. Only an edit
-// to something HEAD already froze is an evasion. frozen.mjs says exactly this above frozenStatusAtHead;
-// this call site disagreed with it until 2026-08-20, when a verification gate flipped Status, was frozen
-// mid-ceremony, and could not write its own completion date.
-import { frozenStatusAtHead } from "./lib/frozen.mjs";
-import { undischargedRows } from "./lib/ledger.mjs";
-import { appendEvent, unresolvedDenials, sessionLogPath, malformedEventLines } from "./lib/session-log.mjs";
-import { approvedPackages, rejectedPackages } from "./lib/approved.mjs";
-import { claimActivity, releaseActivity, recentForeignTouches } from "./lib/claims.mjs";
-import { atStop, graphDenial, wallsAllowlist } from "./lib/graph-store.mjs";
-import { exitAtStop, exitWallsAllowlist, recordUnreadable } from "./lib/exit-store.mjs";
-import { WALLS, wallEnabled } from "./lib/walls.mjs";
 
-// --- the build graph's switch ------------------------------------------------------------
-// A run handed a build graph (docs/harness/code/build-graph.md) may declare `mode.walls`, an
-// allowlist over lib/walls.mjs. Every wall it does not name is off for that session — because
-// the compliance set assumes a session that can dispatch a bookkeeper and a user who can answer
-// an ask, and a generation box has neither: its walls would be unresolvable blocks, not guard
-// rails. No graph, or a graph with no `mode` block, leaves every wall exactly as it was. With no graph
-// declaring one, an exit set (docs/harness/code/exit-check.md) may carry the same block.
-let allowlistCache;
-function wallOn(projectDir, name) {
-  if (allowlistCache === undefined) {
-    try {
-      allowlistCache = wallsAllowlist(projectDir) ?? exitWallsAllowlist(projectDir);
-    } catch (e) {
-      allowlistCache = null; // a broken graph never switches a wall off
-    }
-  }
-  return wallEnabled(allowlistCache, name);
-}
-
-// The graph's own wall: a landed node is written once, and the graph and its state are machinery.
-// It answers with decision("deny", …) and NEVER deny() — a steer is not a failure, and a logged
-// denial in a generation box would need a `resolved` line nobody is there to write.
-function graphGate(projectDir, rel) {
+// The library loads inside the trap, so a gate module that cannot load fails open like any crash.
+async function main() {
+  const { compliancePreToolUse, complianceStop } = await import("./lib/gates.mjs");
+  let raw = "";
   try {
-    const reason = graphDenial(projectDir, rel);
-    return reason ? decision("deny", reason) : null;
+    raw = fs.readFileSync(0, "utf8");
   } catch (e) {
-    return null; // the walker never becomes an outage
-  }
-}
-
-function decision(permissionDecision, reason) {
-  return {
-    hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision, permissionDecisionReason: reason },
-  };
-}
-
-// A deny is also an event in the session gate log — the record that makes going silent after a
-// block impossible. The log is a dated per-session record (never drained; bookkeeping stays a
-// queue); the Stop and commit walls block on `denied` lines with no later `resolved` pair.
-function deny(projectDir, sessionId, gate, target, reason) {
-  appendEvent(projectDir, sessionId, "denied", gate, target);
-  return decision("deny", reason);
-}
-
-// The mechanical half of resolution: when the once-denied operation later succeeds through the
-// gate, machinery writes `retried-ok` itself — the session hand-writes only the judgment claims
-// (`waived → {ref}`, `disclosed → {entry}`).
-function autoResolve(projectDir, sessionId, gate, target) {
-  if (unresolvedDenials(projectDir, sessionId).includes(`${gate} · ${target}`)) {
-    appendEvent(projectDir, sessionId, "resolved", gate, target, "retried-ok");
-  }
-}
-
-// ---------------------------------------------------------------------------
-// PreToolUse — file gates
-// ---------------------------------------------------------------------------
-
-// Re-read at most once per hook process — the list is consulted per gated path.
-let protectedCache = null;
-function protectedPaths(projectDir) {
-  if (protectedCache) return protectedCache;
-  const root = docsRoot(projectDir);
-  const text = readSafe(path.join(projectDir, root, "operations", "protected-files.md"));
-  protectedCache = ["AGENTS.md", `${root}/operations/protected-files.md`, ...backtickTokens(text)];
-  return protectedCache;
-}
-
-// Names the genre of a file the write would create in a standards folder, or null.
-function newStandardDoc(projectDir, rel) {
-  const match = new RegExp(`^${docsRoot(projectDir)}/architecture/(doctrine|playbooks)/[^/]+\\.md$`).exec(rel);
-  if (!match || /\/Readme\.md$/i.test(rel) || fs.existsSync(path.join(projectDir, rel))) return null;
-  return match[1] === "doctrine" ? "doctrine" : "playbook";
-}
-
-function fileGate(projectDir, rel, sessionId) {
-  const frozen = wallOn(projectDir, "frozen-record") ? frozenStatusAtHead(projectDir, rel) : { frozen: false };
-  if (frozen.frozen) {
-    return deny(
-      projectDir,
-      sessionId,
-      "frozen-record",
-      rel,
-      `BLOCKED — frozen record. \`${rel}\` is committed history and is never edited (${frozen.reason}). A correction is a new dated entry that links back.`
-    );
-  }
-
-  if (wallOn(projectDir, "protected-file") && protectedPaths(projectDir).includes(rel)) {
-    return deny(projectDir, sessionId, "protected-file", rel, `BLOCKED — protected file. \`${rel}\` is on the protected list.`);
-  }
-
-  // A doctrine or playbook document is a standard every product reads, so a new one waits for the
-  // user (the documentation skill § Doctrine and playbooks); an edit to an existing one passes.
-  const standard = newStandardDoc(projectDir, rel);
-  if (standard && wallOn(projectDir, "new-standard-doc")) {
-    const asked = askOnce(
-      projectDir,
-      sessionId,
-      "new-standard-doc:" + rel,
-      `\`${rel}\` would be a new ${standard} document. A ${standard} is created only with the user's approval, after extending an existing one is ruled out: name the existing documents it was checked against and the distinction (the documentation skill § Doctrine and playbooks). Create it?`
-    );
-    if (asked) return asked;
-  }
-
-  // Before the claim ask and outside the plan gate's `inDocs` skip — the graph's own files live
-  // under .claude/, which that branch deliberately excludes.
-  const graphWall = graphGate(projectDir, rel);
-  if (graphWall) return graphWall;
-
-  // The file half of the claim board: a path another LIVE session touched minutes ago belongs to
-  // someone else right now. Advisory by design — one ask per sibling per session, never a wall —
-  // this is the presence protocol ("git status archaeology") moved into the gate that fires anyway.
-  try {
-    const holder = wallOn(projectDir, "foreign-claim")
-      ? recentForeignTouches(projectDir, sessionId).find((f) => f.paths.some((p) => p.rel === rel))
-      : null;
-    if (holder) {
-      const recent = holder.paths.find((p) => p.rel === rel);
-      appendEvent(projectDir, sessionId, "coord", "file-claim", rel, `touched ${recent.ageMin}m ago by sid=${holder.sid8}`);
-      const asked = askOnce(
-        projectDir,
-        sessionId,
-        `foreign-claim:${holder.sid8}`,
-        `Another live session (sid=${holder.sid8}, active ${holder.lastActiveMin}m ago) touched \`${rel}\` ${recent.ageMin}m ago and may still be working there. Edit anyway? (Asked once per session for that sibling; scope commits with explicit pathspecs either way.)`
-      );
-      if (asked) return asked;
-    }
-  } catch (e) {
-    /* presence is a convenience — never let it block an edit on failure */
-  }
-
-  const inDocs = rel.startsWith(`${docsRoot(projectDir)}/`) || rel.startsWith(".claude/") || rel.endsWith(".md");
-  if (!inDocs && SOURCE_EXT.test(rel) && wallOn(projectDir, "plan-gate")) {
-    for (const plan of openGatedPlans(projectDir)) {
-      // The gate binds the plan's own paths, so disjoint plans run in parallel.
-      // A scopeless plan stays repo-wide — fail closed.
-      if (plan.scope.length && !inPlanScope(rel, plan.scope)) continue;
-      // Only a passed verdict opens the gate: `pending` has no verdict yet, and `blocked` is a verdict against coding.
-      const boundary = /Boundary:\s*(\w+)/i.exec(plan.gates);
-      if (boundary && !/^passed$/i.test(boundary[1])) {
-        return deny(
-          projectDir,
-          sessionId,
-          "plan-gate",
-          plan.file,
-          `BLOCKED — plan gate. \`${plan.file}\` is open but its Gates line reads 'Boundary: ${boundary[1]}'. ${
-            /^blocked$/i.test(boundary[1])
-              ? "Fold the `boundary` skill's amendments into the plan and re-run it until it records `passed`."
-              : "Run the `boundary` skill and record its verdict in the plan before implementation edits."
-          }`
-        );
-      }
-      if (!plan.hasLedger) {
-        return deny(
-          projectDir,
-          sessionId,
-          "plan-gate",
-          plan.file,
-          `BLOCKED — plan gate. \`${plan.file}\` has no \`## Test Obligations\` section. Run the \`testing\` skill (plan-gate mode); its ledger is what the verification gate discharges.`
-        );
-      }
-      if (!plan.hasDocLedger) {
-        return deny(
-          projectDir,
-          sessionId,
-          "plan-gate",
-          plan.file,
-          `BLOCKED — plan gate. \`${plan.file}\` has no \`## Doc Obligations\` section. Resolve the Proposed Changes paths against the ownership index and fill the table yourself — it is a lookup, not a skill run. "None" is a valid row when the plan touches only unowned paths.`
-        );
-      }
-      // The gates pass now — a plan-gate denial recorded earlier is a successful retry.
-      autoResolve(projectDir, sessionId, "plan-gate", plan.file);
-    }
-  }
-
-  // Writing a test file is never an interruption. Deferring tests to the verification gate stays
-  // doctrine (`testing.md` § During the loop), but it needs no gate here: what the ledger
-  // actually guarantees is enforced at both ends already — a plan may not take implementation
-  // edits until its `## Test Obligations` section exists (above), and it may not reach
-  // `Status: Complete` until the gate discharges every row (the Stop gate). Policing the *moment*
-  // a file appears adds no guarantee those two do not, and it fires hardest at the gate itself,
-  // where the ledger's tests are precisely what should be getting written.
-
-  // Doc placement is never an interruption: docs/structure.md is the authority a session
-  // consults; no hook polices it.
-  return null;
-}
-
-// ---------------------------------------------------------------------------
-// PreToolUse — Bash gates
-// ---------------------------------------------------------------------------
-
-function commitGate(projectDir, sessionId) {
-  const staged = (git(projectDir, ["diff", "--cached", "--name-only"]) || "")
-    .split("\n")
-    .map((s) => s.trim())
-    .filter(Boolean);
-  // A rename-only staged set is on the changelog rule's exemption list; the gate can now honor it
-  // the way CI's caller already does. At least one line, and every line a rename — one edit joins
-  // the set and the wall returns.
-  const nameStatus = (git(projectDir, ["diff", "--cached", "--name-status", "-M"]) || "")
-    .split("\n")
-    .map((s) => s.trim())
-    .filter(Boolean);
-  const allRenames = nameStatus.length > 0 && nameStatus.every((line) => line.startsWith("R"));
-  const root = docsRoot(projectDir);
-  if (wallOn(projectDir, "changelog") && staged.length > 0 && !stagedExempt(projectDir, staged) && !allRenames) {
-    if (!staged.some((f) => f.startsWith(`${root}/history/changelog/`))) {
-      return deny(
-        projectDir,
-        sessionId,
-        "changelog",
-        "git commit",
-        `BLOCKED — changelog. This commit stages no \`${root}/history/changelog/\` entry. Every non-exempt commit carries its entry inside it (exempt: release/bot, harness installs and bumps, lockfile-only, pure renames, changelog housekeeping — state which if claiming one, then stage accordingly or re-run).`
-      );
-    }
-  }
-  // The bookkeeping wall is scoped to the staged set — the grammar and its fail-closed cases are
-  // `lib/state.mjs` § What a row implicates. Rows about files this commit does not touch are
-  // somebody else's, and holding a commit behind rows its session may not drain is a wait with no
-  // action that clears it. The read goes through `liveRows` first: a gate tests conditions at gate
-  // time, never a cached record of them — a row whose condition died since the last sweep must not
-  // wall anything. Pure by design; the detector's next sweep deletes what this filtered out.
-  const { blocking, unrelated } = wallOn(projectDir, "bookkeeping")
-    ? rowsBlockingCommit(liveRows(projectDir, readQueue(projectDir)), staged)
-    : { blocking: [], unrelated: [] };
-  if (blocking.length > 0) {
-    const shown = blocking.slice(0, 8);
-    const lines = shown.map(({ row, hits }) =>
-      hits.length > 0
-        ? `  - ${row.kind}: ${row.body}\n    ↳ implicates staged ${hits.join(", ")}`
-        : `  - ${row.kind}: ${row.body}\n    ↳ names no staged path — a row like this blocks every commit`
-    );
-    if (blocking.length > shown.length) lines.push(`  - …and ${blocking.length - shown.length} more`);
-    return deny(
-      projectDir,
-      sessionId,
-      "bookkeeping",
-      "git commit",
-      `BLOCKED — bookkeeping. ${blocking.length} unresolved row(s) in ${root}/operations/bookkeeping.md implicate this commit (each re-verified against the repo just now — these are live):\n${lines.join("\n")}\n` +
-        "Dispatch the bookkeeper to drain them (never drain auto:/note: rows in your own loop; needs-session: rows are yours), or convert to `waived:` with a reason and expiry; a successful retry re-tests everything again." +
-        (unrelated > 0
-          ? ` (${unrelated} further unresolved row(s) implicate nothing staged here — another session's work, and not yours to drain.)`
-          : "")
-    );
-  }
-
-  // All commit gates pass — a changelog/bookkeeping denial recorded earlier is a successful retry.
-  autoResolve(projectDir, sessionId, "changelog", "git commit");
-  autoResolve(projectDir, sessionId, "bookkeeping", "git commit");
-  return null;
-}
-
-
-// A token must parse as an npm package spec — name or @scope/name, optional @range tail —
-// before it may be judged against the table. Everything else on an install line (redirections
-// like 2>&1, chained commands, flags, paths, URLs) is shell, not a package. A non-candidate is
-// skipped, never blocked: a miss is caught downstream by the lockfile, while a false deny
-// teaches the session the gate is noise exactly where the gate matters most.
-const PKG_SPEC = /^(@[a-z0-9~-][\w.-]*\/)?[a-z0-9~-][\w.-]*(@[\w.^~*<>=|x-]+)?$/;
-
-function packageGate(projectDir, command, sessionId) {
-  if (!wallOn(projectDir, "package-table")) return null;
-  const m = new RegExp(
-    String.raw`(?:^|\n|&&|;|\|)\s*(?:sudo\s+)?(?:pnpm|npm|yarn|bun)\s+(?:add|install|i)(?=\s|$)([^&;|\n]*)`
-  ).exec(command);
-  if (!m) return null;
-  const approved = approvedPackages(projectDir);
-  if (approved.size === 0) return null; // no rules file installed — nothing to enforce
-  const rejected = rejectedPackages(projectDir);
-  const raw = m[1] || "";
-  // Test packages install at `latest`, outside the table's pin set (.claude/rules/testing.md).
-  // Two dev-only installs are a decision already taken rather than a new one: a companion in an
-  // approved scope (`@testing-library/react` is approved, so `-D @testing-library/user-event` is
-  // not a fresh choice), and `@types/*`, which is the typing of a package already decided. Scoped
-  // and dev only — an unscoped or runtime install is still judged against the table.
-  const isDev = /(?:^|\s)(?:-D|--save-dev|--dev)(?:\s|$)/.test(raw);
-  const approvedScopes = new Set(
-    [...approved].filter((n) => n.startsWith("@")).map((n) => n.split("/")[0])
-  );
-  approvedScopes.add("@types");
-  const pkgs = raw
-    .split(/\s+/)
-    .filter((a) => a && !a.startsWith("-") && PKG_SPEC.test(a))
-    .map((arg) => (arg.startsWith("@") ? arg.split("@").slice(0, 2).join("@") : arg.split("@")[0]));
-  for (const pkg of pkgs) {
-    if (approved.has(pkg)) continue;
-    if (isDev && pkg.startsWith("@") && approvedScopes.has(pkg.split("/")[0])) continue;
-    // Approved wins over rejected: `jest` is banned for web and Express and prescribed for Expo,
-    // so a name in both is a prescription somewhere and must not be denied.
-    const no = rejected.get(pkg);
-    if (no) {
-      const instead = no.use
-        ? `Use \`${no.use}\`${no.version ? ` ${no.version}` : ""}${no.purpose ? ` — ${no.purpose}` : ""}.`
-        : `The prescribed choice for your stack is in ${no.rule}.`;
-      return deny(
-        projectDir,
-        sessionId,
-        "package-table",
-        pkg,
-        `BLOCKED — \`${pkg}\` is rejected here. ${instead} Rejections are recorded in .claude/hooks/approved-packages.md; changing one is an explicit user decision.`
-      );
-    }
-    // No decision exists for this package — not approved, not rejected. Allowed, and harvested
-    // centrally by the fleet package census rather than blocked here.
-  }
-  // Every named package passed — a package-table denial for one of them is a successful retry.
-  for (const pkg of pkgs) autoResolve(projectDir, sessionId, "package-table", pkg);
-  return null;
-}
-
-// An ask class fires once per session: the first occurrence asks, later ones pass silently —
-// the user has already exercised judgment on this class this session.
-function askOnce(projectDir, sessionId, key, message) {
-  if (askedThisSession(projectDir, sessionId, key)) return null;
-  recordAsked(projectDir, sessionId, key);
-  return decision("ask", message);
-}
-
-// Command matchers anchor at statement boundaries (start, newline, &&, ;, |) so quoted text — an
-// echoed payload, a commit message naming a command — can never trigger a gate, while a command
-// on its own line cannot slip past one. (Heredoc bodies still look like statements; that false
-// positive is accepted over the false negative.)
-const AT_STATEMENT = String.raw`(?:^|\n|&&|;|\|)\s*(?:sudo\s+)?(?:npx\s+(?:--yes\s+)?)?`;
-const statement = (body) => new RegExp(AT_STATEMENT + body);
-
-function bashGate(projectDir, command, sessionId) {
-  if (!command) return null;
-
-  if (statement(String.raw`git\s+commit\b`).test(command)) {
-    if (!wallOn(projectDir, "commit-claim")) return commitGate(projectDir, sessionId);
-    // The claim board serializes the commit sequence: disjoint files do not make disjoint
-    // commits — every session writes the same branch through the same index, so one committer
-    // at a time. A held claim is a plain wait (no denied/resolved pair to resolve — the retry
-    // clears it); a stale claim (holder dead or past TTL) is stolen loudly on the record.
-    const claim = claimActivity(projectDir, "commit", sessionId);
-    if (claim.held) {
-      appendEvent(projectDir, sessionId, "coord", "commit-claim", `waited — held by sid=${claim.held.sid8}`, `${claim.held.ageMin}m old`);
-      return decision(
-        "deny",
-        `WAIT — another session (sid=${claim.held.sid8}, claimed ${claim.held.ageMin}m ago) is mid-commit in this checkout. Re-run the commit in a moment; its completion (or staleness) releases the claim automatically. Do not delete .git/index.lock.`
-      );
-    }
-    if (claim.stole) {
-      appendEvent(projectDir, sessionId, "coord", "commit-claim", `stale claim by sid=${claim.stole.sid8} evicted`);
-    }
-    const gate = commitGate(projectDir, sessionId);
-    if (gate) {
-      // The commit is not happening — release immediately so a walled commit never holds the board.
-      releaseActivity(projectDir, "commit", sessionId);
-      return gate;
-    }
-    return null; // allowed — the awareness PostToolUse releases the claim when the command completes
-  }
-
-  // `git branch <name>` creates; flag-led forms (--show-current, --list, -d, -vv) query or manage
-  if (wallOn(projectDir, "branch-worktree") && statement(String.raw`git\s+(checkout\s+-b|switch\s+-c|branch\s+(?!-)\S+|worktree\s+add)`).test(command)) {
-    return askOnce(
-      projectDir,
-      sessionId,
-      "branch-worktree",
-      "Create a branch/worktree? Policy allows this only when you asked for a PR or branch."
-    );
+    raw = "";
   }
-
-  if (
-    wallOn(projectDir, "live-command") &&
-    statement(String.raw`wrangler(?:@\S+)?\b.*(\bd1\s+execute\b.*--remote|\bsecret\s+(put|bulk)\b|\bdeploy\b)`).test(command) &&
-    !/--dry-run\b|--local\b/.test(command)
-  ) {
-    return askOnce(
-      projectDir,
-      sessionId,
-      "live-command",
-      `Run this live-system command (deploy / remote DB / secrets)? If it's a one-shot migration, its runbook should exist in ${docsRoot(projectDir)}/history/migrations/ first. Asked once per session.`
-    );
-  }
-
-  const shellWrite = bashWriteScreen(projectDir, command, sessionId);
-  if (shellWrite) return shellWrite;
-
-  return packageGate(projectDir, command, sessionId);
-}
-
-// A file write arriving by shell hits the same wall the Edit tool does. Only tokens in a
-// WRITING position count — redirect targets, `tee`/`mv`/`cp` destinations, and any path on an
-// in-place editor line (`sed -i`, `perl -i`) — so reading a frozen record into a pipe stays
-// legal. A token that isn't an existing repo path falls through frozenStatus/protected as a
-// no-op, which keeps sed expressions and flags harmless without shell-parsing them.
-function bashWriteTargets(command) {
-  const targets = [];
-  let m;
-  const redirect = />{1,2}\s*([^\s;|&<>]+)/g;
-  while ((m = redirect.exec(command))) targets.push(m[1]);
-  const tee = /\btee\s+(?:-\S+\s+)*([^\s;|&<>]+)/g;
-  while ((m = tee.exec(command))) targets.push(m[1]);
-  const moveCopy = /\b(?:mv|cp)\s+(?:-\S+\s+)*\S+\s+([^\s;|&<>]+)/g;
-  while ((m = moveCopy.exec(command))) targets.push(m[1]);
-  if (/\b(?:sed|perl)\s+(?:-\S*\s+)*-\S*i/.test(command) || /\bsed\s+--in-place\b/.test(command)) {
-    for (const t of command.split(/[\s"']+/)) {
-      if (t && !t.startsWith("-") && /[/.]/.test(t)) targets.push(t);
-    }
-  }
-  return targets;
-}
-
-function bashWriteScreen(projectDir, command, sessionId) {
-  for (const target of bashWriteTargets(command)) {
-    const rel = relIfInside(projectDir, target);
-    if (!rel) continue;
-    // A shell write is still a write: the build graph's wall runs here too, or `cat > docs/prd.md`
-    // over a landed node ships green while the Edit tool is refused.
-    const graphWall = graphGate(projectDir, rel);
-    if (graphWall) return graphWall;
-    const frozen = wallOn(projectDir, "frozen-record") ? frozenStatusAtHead(projectDir, rel) : { frozen: false };
-    if (frozen.frozen) {
-      return deny(
-        projectDir,
-        sessionId,
-        "frozen-record",
-        rel,
-        `BLOCKED — frozen record. \`${rel}\` is committed history and is never edited (${frozen.reason}) — a shell write is still a write. A correction is a new dated entry that links back.`
-      );
-    }
-    if (wallOn(projectDir, "protected-file") && protectedPaths(projectDir).includes(rel)) {
-      return deny(
-        projectDir,
-        sessionId,
-        "protected-file",
-        rel,
-        `BLOCKED — protected file. \`${rel}\` is on the protected list — a shell write is still a write.`
-      );
-    }
-  }
-  return null;
-}
-
-// ---------------------------------------------------------------------------
-// Stop
-// ---------------------------------------------------------------------------
-
-// True when the transcript's recent tail shows a REAL bookkeeper dispatch — a tool record naming
-// the agent type, not the word appearing in prose (policy text quoting "bookkeeper" rides in most
-// transcripts, and a prose match silently suppressed this wall). Best-effort: absent or
-// unreadable transcript reads as "not dispatched".
-function bookkeeperDispatched(transcriptPath) {
-  const tail = readSafe(transcriptPath || "").slice(-200000);
-  return /"subagent_type"\s*:\s*"bookkeeper"/.test(tail);
-}
-
-// Plans this session flipped to Complete: Status is Complete AND the file appears in this
-// machine's touched.tsv (written by the awareness detector as edits happen).
-function plansCompletedThisSession(projectDir, sessionId) {
-  const touched = readSafe(path.join(projectDir, ".claude", "state", "touched.tsv"));
-  const touchedPlans = new Set(
-    touched
-      .split("\n")
-      .map((line) => line.split("\t"))
-      // THIS session's rows only. touched.tsv is shared by every session in the checkout, so an
-      // unfiltered read blocks one session's Stop for a plan another session completed — whose Ask
-      // quotes and iterations it does not have and cannot invent. Rows written before the id column
-      // existed carry no session and belong to none, so they are skipped rather than assumed.
-      .filter((cols) => sessionId && cols[3] === sessionId)
-      .map((cols) => cols[1])
-      .filter((p) => p && p.startsWith(`${docsRoot(projectDir)}/history/plans/`))
-  );
-  const out = [];
-  for (const rel of touchedPlans) {
-    const text = readSafe(path.join(projectDir, rel));
-    if (/^\*\*Status:\*\*\s*Complete\b/m.test(text)) out.push(rel);
-  }
-  return out;
-}
-
-// Whether some changelog entry already accounts for this plan. An entry names its plan by slug
-// (the template links `../plans/<slug>.md`), so the slug is what is searched for — over every
-// entry on disk, committed or draft. A dirty-but-unrelated file in the changelog directory does
-// NOT count: that shortcut made the wall satisfiable by `touch docs/history/changelog/x.md`,
-// for every plan at once.
-function planHasChangelogEntry(projectDir, planRel) {
-  const slug = path.basename(planRel, ".md");
-  const dir = path.join(projectDir, docsRoot(projectDir), "history", "changelog");
-  let names = [];
-  try {
-    names = fs.readdirSync(dir);
-  } catch {
-    return false;
-  }
-  return names.some((name) => name.endsWith(".md") && readSafe(path.join(dir, name)).includes(slug));
-}
-
-// The Stop half of the build-graph walker. Blocks with the next injection line while the graph
-// can still advance, allows the moment it is terminal, and answers null when no graph exists —
-// which is every session in every repo that was never handed one.
-function graphStop(projectDir, stopHookActive) {
-  let step;
-  try {
-    step = atStop(projectDir);
-  } catch (e) {
-    return null; // the walker never becomes an outage
-  }
-  if (!step) return null;
-  if (step.refusal) {
-    // A refusal the model cannot repair (the wall denies writes to the graph) must not become an
-    // unbreakable Stop loop: say it once, loudly, and let the second Stop through. Fixing the
-    // graph is the run owner's job, not the model's — so this branch, alone in this function,
-    // honours the runtime's loop guard.
-    if (stopHookActive) return null;
-    return {
-      decision: "block",
-      reason:
-        `BUILD GRAPH REFUSED — \`.claude/state/graph.json\` exists but ${step.refusal}. Nothing is being steered. ` +
-        "Fix the graph or remove it: the walker is dormant only when that file is ABSENT, never when it is wrong. (Said once — the next Stop passes.)",
-    };
-  }
-  if (!step.line) return null;
-  return {
-    decision: "block",
-    reason:
-      `${step.line} The build graph decides this run's order and completion — ${step.terminal.summary} ` +
-      "Write the file the line names; the run ends by itself when the graph is complete, blocked, or out of attempts.",
-  };
-}
-
-// The exit check (docs/harness/code/exit-check.md): authority, so a crash blocks rather than passes. It
-// blocks once — the box walls `.claude/state`, so the model cannot repair the file — and the second stop
-// records `blocked`, so the node still ends failed instead of met.
-function exitStop(projectDir, stopHookActive) {
-  let step;
-  try {
-    step = exitAtStop(projectDir);
-  } catch (e) {
-    const reason = `EXIT CHECK FAILED — ${e?.message || e}`;
-    if (!stopHookActive) {
-      return { decision: "block", reason: `${reason}. This node's exit set cannot be read, so it is not finished. (Said once — the next Stop ends the node blocked.)` };
-    }
-    try {
-      recordUnreadable(projectDir, reason);
-    } catch (e2) {
-      /* nowhere to record it; the box seals without a verdict and the run owner's own check decides */
-    }
-    return null;
-  }
-  if (!step || step.allow) return null;
-  return { decision: "block", reason: step.block };
-}
-
-function stopGate(projectDir, payload) {
-  // The build graph is asked BEFORE the runtime's loop guard, and deliberately ignores it. The
-  // guard exists because an unbounded Stop hook is a hang; the walker is bounded instead — every
-  // block charges an attempt on the node it names, so a model that answers "done" spends that
-  // node's budget and the run ends `exhausted`. Honouring the flag would leave the walker able to
-  // steer exactly once per turn chain and then go quiet with documents still owed, which is the
-  // liveness hole the whole design exists to close.
-  //
-  // Consequence, and it is deliberate: while a graph is live the first block flips
-  // `stop_hook_active` for the rest of the chain, so the four sub-walls below are suspended until
-  // the graph is terminal. A generation box wants exactly that; a human session running a
-  // hand-written graph should know it.
-  const graph = graphStop(projectDir, payload.stop_hook_active);
-  if (graph) return graph;
-  // The exit check is asked before the loop guard for the walker's reason: it is bounded by its own attempts.
-  const exit = exitStop(projectDir, payload.stop_hook_active);
-  if (exit) return exit;
-
-  if (payload.stop_hook_active) return null; // the runtime's infinite-loop guard — never re-block
-
-  // The Stop wall is scoped to this session's own rows (plus sid-less ones) — a concurrent
-  // session's open work must not block this one's stop. End-of-session accountability is per
-  // session and stays that way; the commit wall scopes by staged path instead, and CI by nothing.
-  // Filtered through `liveRows` (sid first — fewer verifier runs): the wall blocks on conditions
-  // that hold NOW, not on rows the last sweep happened to leave written down.
-  const mine = liveRows(
-    projectDir,
-    readQueue(projectDir).filter((row) => !/\bsid=/.test(row.body) || row.body.includes(`sid=${payload.session_id}`))
-  );
-  const counts = countRows(mine);
-  if (wallOn(projectDir, "queue") && counts.unresolved > 0 && !bookkeeperDispatched(payload.transcript_path)) {
-    return {
-      decision: "block",
-      reason:
-        `${counts.unresolved} unresolved bookkeeping rows from this session (${counts.auto} auto, ${counts.note} note, ${counts.needsSession} needs-session, ${counts.expiredWaived} expired-waived) in ${docsRoot(projectDir)}/operations/bookkeeping.md. ` +
-        "Dispatch the `bookkeeper` agent to drain them — inline resolution is for needs-session: rows only — or convert to `waived:` rows with reason + expiry. " +
-        (counts.expiredWaived > 0
-          ? "An expired waiver is a deferral that ran out — re-judge whether its reason still holds rather than re-waiving by default. "
-          : "") +
-        "If the open plan's code is written, its gate is the build's tail — drive, fix, pin, discharge before stopping; the freeze and the commit are the user's.",
-    };
-  }
-
-  // Open gate denials wall the stop: silence after a block is the one ending the log exists to
-  // make impossible. Resolution appends to the log — retried-ok is machinery-written on a
-  // successful retry; waived/disclosed are the session's hand-written, auditable claims.
-  const openDenials = wallOn(projectDir, "open-denials") ? unresolvedDenials(projectDir, payload.session_id) : [];
-  if (openDenials.length > 0) {
-    const rel = path.relative(projectDir, sessionLogPath(projectDir, payload.session_id));
-    // A resolution that doesn't parse reads to the session as "my resolution didn't count"
-    // with no explanation — name the offending lines and the grammar instead of staying mute.
-    const bad = malformedEventLines(projectDir, payload.session_id);
-    const badNote =
-      bad.length > 0
-        ? ` NOTE: ${bad.length} line(s) look like events but don't parse — the grammar is \`- HH:MM:SS denied|resolved · gate · target[ · detail]\` (a resolved line missing its timestamp is invisible to the wall): ${bad.join(" | ")}.`
-        : "";
-    return {
-      decision: "block",
-      reason:
-        `${openDenials.length} gate denial(s) this session have no resolved line in ${rel}: ${openDenials.join("; ")}. ` +
-        "For each, either retry the operation properly (a success appends `retried-ok` automatically), convert it to a waiver and append " +
-        "`resolved · {gate} · {target} · waived → {ref}`, or record the failure honestly in the changelog entry and append " +
-        "`resolved · {gate} · {target} · disclosed → {entry file}`. Never delete log lines — the log is a record, not a queue." +
-        badNote,
-    };
-  }
-
-  // An undischarged Doc Obligations ledger is not walled here — the detector raises it as a
-  // `needs-session:` row, which the queue wall above already blocks on, and which outlives this
-  // stop through the commit gate and CI. A second wall keyed to one checkbox would add a special
-  // case beside a general rule that already covers it.
-  const completed = plansCompletedThisSession(projectDir, payload.session_id);
-
-  // The Test Obligations ledger IS walled per row: the Outcome cell lives in the plan file, so the
-  // only way past this block is reading the file — a context-held copy of the ledger is exactly
-  // how rows get missed. (Tables without an Outcome column are legacy and pass; see lib/ledger.)
-  for (const rel of wallOn(projectDir, "ledger") ? completed : []) {
-    const rows = undischargedRows(readSafe(path.join(projectDir, rel)));
-    if (rows.length > 0) {
-      return {
-        decision: "block",
-        reason:
-          `Plan \`${rel}\` is Status: Complete with ${rows.length} Test Obligations row(s) missing a discharge outcome (#${rows.join(", #")}). ` +
-          "Re-read the ledger from the plan file and discharge every row at the verification gate — satisfied, owes nothing (reason), or blocked → backlog — before completing.",
-      };
-    }
-  }
-
-  const undocumented = wallOn(projectDir, "changelog-entry")
-    ? completed.filter((rel) => !planHasChangelogEntry(projectDir, rel))
-    : [];
-  if (undocumented.length > 0) {
-    return {
-      decision: "block",
-      reason: `Plan \`${undocumented[0]}\` reached Status: Complete this session with no changelog entry drafted. Write the draft now (documentation skill → templates/changelog-entry.md) — the Ask quotes, rejected iterations, and skill verdicts that fill it exist only in this session and die with it.`,
-    };
-  }
-
-  return null;
-}
-
-// ---------------------------------------------------------------------------
-
-function main() {
-  const raw = readStdin();
   let payload = {};
   try {
     payload = raw ? JSON.parse(raw) : {};
   } catch (e) {
     payload = {};
   }
-  const projectDir = resolveProjectDir(payload);
-  const event = payload.hook_event_name;
-
-  let out = null;
-  if (event === "PreToolUse") {
-    const input = payload.tool_input || {};
-    if (payload.tool_name === "Bash") {
-      out = bashGate(commandRoot(projectDir, payload, input.command), input.command, payload.session_id);
-    } else {
-      const rel = relIfInside(projectDir, input.file_path);
-      if (rel) out = fileGate(projectDir, rel, payload.session_id);
-    }
-  } else if (event === "Stop") {
-    out = stopGate(projectDir, payload);
-  }
-
+  const out = payload.hook_event_name === "Stop" ? complianceStop(payload) : compliancePreToolUse(payload);
   if (out) process.stdout.write(JSON.stringify(out));
 }
 
 try {
-  main();
+  await main();
 } catch (e) {
   // Fail open: a broken gate must never become an outage. But a gate that crashes silently is a
   // gate nobody knows stopped guarding — leave a trace where the next SessionStart can find it.