@nurix/etna 0.20.47 → 0.20.49

package/data/harnesses/code/hooks/lib/gates.mjs

@@ -0,0 +1,633 @@
+// harness/code/hooks/lib/gates.mjs — the compliance gates as a library: every gate a named export,
+// nothing run on import. PreToolUse (Edit|Write|MultiEdit|Bash): deny what is never legitimate
+// (plan-gate skips, changelog-less commits, off-catalog packages), ask where intent matters
+// (branches, live commands, new standard documents, a sibling's files). Stop: block an arc that
+// tries to end with unresolved bookkeeping or an unrecorded plan completion. The Protection walls
+// (frozen records, protected files) live in lib/protection-gate.mjs, re-exported here; these gates
+// run its predicate first and defer to the Protection hook where it is handled.
+// compliance.mjs is the thin entry over compliancePreToolUse and complianceStop.
+
+import fs from "node:fs";
+import path from "node:path";
+import { readSafe, relIfInside, git, commandRoot, SOURCE_EXT, docsRoot, resolveProjectDir } from "./repo.mjs";
+import { openGatedPlans, inPlanScope } from "./plans.mjs";
+import { stagedExempt } from "./exempt.mjs";
+import { readQueue, countRows, rowsBlockingCommit, askedThisSession, recordAsked } from "./state.mjs";
+import { liveRows } from "./sweep.mjs";
+import { undischargedRows } from "./ledger.mjs";
+import { appendEvent, unresolvedDenials, sessionLogPath, malformedEventLines } from "./session-log.mjs";
+import { approvedPackages, rejectedPackages } from "./approved.mjs";
+import { claimActivity, releaseActivity, recentForeignTouches } from "./claims.mjs";
+import { atStop, graphDenial } from "./graph-store.mjs";
+import { exitAtStop, recordUnreadable } from "./exit-store.mjs";
+import {
+  decision,
+  deny,
+  wallOn,
+  pathVerdict,
+  shellVerdict,
+  bashWriteTargets,
+  protectionHandled,
+} from "./protection-gate.mjs";
+
+export { protectionVerdict, protectionGate, protectionPreToolUse } from "./protection-gate.mjs";
+
+// The build graph's switch (`mode.walls`) is read once per projectDir by lib/protection-gate.mjs#wallOn,
+// shared with the Protection hook so the two never disagree about which walls are on.
+
+// 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) {
+  try {
+    const reason = graphDenial(projectDir, rel);
+    return reason ? decision("deny", reason) : null;
+  } catch (e) {
+    return null; // the walker never becomes an outage
+  }
+}
+
+// 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
+// ---------------------------------------------------------------------------
+
+// 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";
+}
+
+export function fileGate(projectDir, rel, sessionId) {
+  // Protection's walls first, before any ask, claim or autoResolve: a call Protection denies must
+  // leave no side effect here (Claude Code runs both hooks in parallel and deny beats ask). With the
+  // Protection hook registered and present it owns the deny and its log line; without it, this gate
+  // holds both walls itself.
+  const walled = pathVerdict(projectDir, rel);
+  if (walled) return protectionHandled(projectDir) ? null : deny(projectDir, sessionId, walled.wall, rel, walled.message);
+
+  // 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
+// ---------------------------------------------------------------------------
+
+export 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-]+)?$/;
+
+export 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);
+
+// `projectDir` is the repo the command acts on (lib/repo.mjs#commandRoot); `hookDir` is the session's
+// project, whose settings say whether the Protection hook runs.
+export function bashGate(projectDir, command, sessionId, { hookDir = projectDir } = {}) {
+  if (!command) return null;
+
+  // Protection's walls first, before the commit claim, the asks and any autoResolve (see fileGate).
+  const walled = shellVerdict(projectDir, command);
+  if (walled) return protectionHandled(hookDir) ? null : deny(walled.projectDir, sessionId, walled.wall, walled.rel, walled.message);
+
+  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."
+    );
+  }
+
+  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.`
+    );
+  }
+
+  // The Protection walls already ran at the top; only the build graph's wall is left to screen.
+  const graphWall = graphScreen(projectDir, command);
+  if (graphWall) return graphWall;
+
+  return packageGate(projectDir, command, sessionId);
+}
+
+// A shell write is still a write: the build graph's wall runs on every write target too, or
+// `cat > docs/prd.md` over a landed node ships green while the Edit tool is refused.
+function graphScreen(projectDir, command) {
+  for (const target of bashWriteTargets(command)) {
+    const rel = relIfInside(projectDir, target);
+    if (!rel) continue;
+    const graphWall = graphGate(projectDir, rel);
+    if (graphWall) return graphWall;
+  }
+  return null;
+}
+
+// The whole shell write screen for one command: the build graph's wall, then the Protection walls
+// through the logged deny, per write target (lib/protection-gate.mjs § bashWriteTargets).
+export function bashWriteScreen(projectDir, command, sessionId) {
+  for (const target of bashWriteTargets(command || "")) {
+    const rel = relIfInside(projectDir, target);
+    if (!rel) continue;
+    const graphWall = graphGate(projectDir, rel);
+    if (graphWall) return graphWall;
+    const walled = pathVerdict(projectDir, rel, { shell: true });
+    if (walled) return deny(projectDir, sessionId, walled.wall, rel, walled.message);
+  }
+  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 };
+}
+
+export 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;
+}
+
+// ---------------------------------------------------------------------------
+// Dispatchers — the hook's output object for one payload, or null
+// ---------------------------------------------------------------------------
+
+export function compliancePreToolUse(payload) {
+  if (!payload || payload.hook_event_name !== "PreToolUse") return null;
+  const projectDir = resolveProjectDir(payload);
+  const input = payload.tool_input || {};
+  if (payload.tool_name === "Bash") {
+    return bashGate(commandRoot(projectDir, payload, input.command), input.command, payload.session_id, { hookDir: projectDir });
+  }
+  const rel = relIfInside(projectDir, input.file_path);
+  return rel ? fileGate(projectDir, rel, payload.session_id) : null;
+}
+
+export function complianceStop(payload) {
+  if (!payload || payload.hook_event_name !== "Stop") return null;
+  return stopGate(resolveProjectDir(payload), payload);
+}

package/data/harnesses/code/hooks/lib/ownership.mjs

@@ -4,21 +4,11 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import { docsRoot } from "./repo.mjs";
+import { docsRoot, readStdin, resolveProjectDir } from "./repo.mjs";
 
-// Read all of stdin synchronously; returns "" if nothing is piped.
-export function readStdin() {
-  try {
-    return fs.readFileSync(0, "utf8");
-  } catch (e) {
-    return "";
-  }
-}
-
-// Resolve the project root: CLAUDE_PROJECT_DIR env, else payload cwd, else process cwd.
-export function resolveProjectDir(payload) {
-  return process.env.CLAUDE_PROJECT_DIR || (payload && payload.cwd) || process.cwd();
-}
+// readStdin and resolveProjectDir live in lib/repo.mjs, so the Protection hook reaches them without
+// this module; re-exported for every existing importer.
+export { readStdin, resolveProjectDir };
 
 // Recursively collect every .md file under dir (returns [] if the dir is absent).
 export function listMarkdown(dir) {