@nurix/etna 0.20.2 → 0.20.4

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

@@ -8,12 +8,18 @@
 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 } from "./lib/repo.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";
-import { frozenStatus } from "./lib/frozen.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";
@@ -50,13 +56,14 @@ function autoResolve(projectDir, sessionId, gate, target) {
 let protectedCache = null;
 function protectedPaths(projectDir) {
   if (protectedCache) return protectedCache;
-  const text = readSafe(path.join(projectDir, "docs", "operations", "protected-files.md"));
-  protectedCache = ["AGENTS.md", "docs/operations/protected-files.md", ...backtickTokens(text)];
+  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;
 }
 
 function fileGate(projectDir, rel, sessionId) {
-  const frozen = frozenStatus(projectDir, rel);
+  const frozen = frozenStatusAtHead(projectDir, rel);
   if (frozen.frozen) {
     return deny(
       projectDir,
@@ -91,7 +98,7 @@ function fileGate(projectDir, rel, sessionId) {
     /* presence is a convenience — never let it block an edit on failure */
   }
 
-  const inDocs = rel.startsWith("docs/") || rel.startsWith(".claude/") || rel.endsWith(".md");
+  const inDocs = rel.startsWith(`${docsRoot(projectDir)}/`) || rel.startsWith(".claude/") || rel.endsWith(".md");
   if (!inDocs && SOURCE_EXT.test(rel)) {
     for (const plan of openGatedPlans(projectDir)) {
       // The gate binds the plan's own paths, so disjoint plans run in parallel.
@@ -159,14 +166,15 @@ function commitGate(projectDir, sessionId) {
     .map((s) => s.trim())
     .filter(Boolean);
   const allRenames = nameStatus.length > 0 && nameStatus.every((line) => line.startsWith("R"));
-  if (staged.length > 0 && !stagedExempt(staged) && !allRenames) {
-    if (!staged.some((f) => f.startsWith("docs/history/changelog/"))) {
+  const root = docsRoot(projectDir);
+  if (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 `docs/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)."
+        `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).`
       );
     }
   }
@@ -190,8 +198,8 @@ function commitGate(projectDir, sessionId) {
       sessionId,
       "bookkeeping",
       "git commit",
-      `BLOCKED — bookkeeping. ${blocking.length} unresolved row(s) in docs/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, resolve them, or convert to `waived:` with a reason and expiry; a successful retry re-tests everything again." +
+      `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.)`
           : "")
@@ -322,7 +330,7 @@ function bashGate(projectDir, command, sessionId) {
       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 docs/history/migrations/ first. Asked once per session."
+      `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.`
     );
   }
 
@@ -358,7 +366,7 @@ function bashWriteScreen(projectDir, command, sessionId) {
   for (const target of bashWriteTargets(command)) {
     const rel = relIfInside(projectDir, target);
     if (!rel) continue;
-    const frozen = frozenStatus(projectDir, rel);
+    const frozen = frozenStatusAtHead(projectDir, rel);
     if (frozen.frozen) {
       return deny(
         projectDir,
@@ -408,7 +416,7 @@ function plansCompletedThisSession(projectDir, sessionId) {
       // 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("docs/history/plans/"))
+      .filter((p) => p && p.startsWith(`${docsRoot(projectDir)}/history/plans/`))
   );
   const out = [];
   for (const rel of touchedPlans) {
@@ -425,7 +433,7 @@ function plansCompletedThisSession(projectDir, sessionId) {
 // for every plan at once.
 function planHasChangelogEntry(projectDir, planRel) {
   const slug = path.basename(planRel, ".md");
-  const dir = path.join(projectDir, "docs", "history", "changelog");
+  const dir = path.join(projectDir, docsRoot(projectDir), "history", "changelog");
   let names = [];
   try {
     names = fs.readdirSync(dir);
@@ -452,12 +460,12 @@ function stopGate(projectDir, payload) {
     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 docs/operations/bookkeeping.md. ` +
-        "Dispatch the `bookkeeper` agent to drain them, resolve them now, or convert to `waived:` rows with reason + expiry. " +
+        `${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 implementation of the open plan is complete, also report it and offer the verification gate — never run it unbidden.",
+        "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.",
     };
   }
 

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

@@ -4,6 +4,7 @@
 // whether the same commit owed an entry.
 
 import path from "node:path";
+import { docsRoot } from "./repo.mjs";
 
 const LOCKFILES = /^(pnpm-lock\.yaml|package-lock\.json|yarn\.lock|bun\.lockb?|Cargo\.lock)$/;
 const HARNESS_PREFIXES = [".claude/", ".agents/", ".codex/"];
@@ -16,17 +17,18 @@ const HARNESS_FILES = [
   ".prettierrc.json",
 ];
 
-export function changelogExemptFile(f) {
+export function changelogExemptFile(projectDir, f) {
+  const root = docsRoot(projectDir);
   return (
     LOCKFILES.test(path.basename(f)) ||
     HARNESS_PREFIXES.some((p) => f.startsWith(p)) ||
     HARNESS_FILES.includes(f) ||
-    f.startsWith("docs/history/changelog/") ||
+    f.startsWith(`${root}/history/changelog/`) ||
     f.includes(".bkp.") ||
-    f === "docs/history/CHANGELOG.md"
+    f === `${root}/history/CHANGELOG.md`
   );
 }
 
-export function stagedExempt(files) {
-  return files.every(changelogExemptFile);
+export function stagedExempt(projectDir, files) {
+  return files.every((f) => changelogExemptFile(projectDir, f));
 }

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

@@ -7,6 +7,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
+import { docsRoot } from "./repo.mjs";
 
 function relPosix(projectDir, filePath) {
   return path.relative(projectDir, path.resolve(projectDir, filePath)).split(path.sep).join("/");
@@ -30,23 +31,24 @@ function readSafe(projectDir, filePath) {
 // The predicate. Returns { frozen: boolean, reason?: string }.
 export function frozenStatus(projectDir, filePath) {
   const rel = relPosix(projectDir, filePath);
+  const root = docsRoot(projectDir);
   // *.bkp.* siblings are install-time backups, not records — the maintenance fold edits and
   // deletes them, which a frozen verdict would forbid.
   if (rel.includes(".bkp.")) return { frozen: false };
-  if (rel.startsWith("docs/history/changelog/") && rel.endsWith(".md")) {
+  if (rel.startsWith(`${root}/history/changelog/`) && rel.endsWith(".md")) {
     if (isCommitted(projectDir, rel)) {
       return { frozen: true, reason: "committed changelog entry — immutability begins at commit" };
     }
     return { frozen: false };
   }
-  if (rel.startsWith("docs/history/plans/") && rel.endsWith(".md")) {
+  if (rel.startsWith(`${root}/history/plans/`) && rel.endsWith(".md")) {
     const text = readSafe(projectDir, rel);
     if (/^\*\*Status:\*\*\s*(Complete|Abandoned)\b/m.test(text)) {
       return { frozen: true, reason: "plan with Status: Complete or Abandoned" };
     }
     return { frozen: false };
   }
-  if (rel.startsWith("docs/history/migrations/") && rel.endsWith(".md")) {
+  if (rel.startsWith(`${root}/history/migrations/`) && rel.endsWith(".md")) {
     const text = readSafe(projectDir, rel);
     if (/^\*\*Executed:\*\*\s*\d{4}-\d{2}-\d{2}/m.test(text)) {
       return { frozen: true, reason: "outcome-stamped migration runbook" };
@@ -62,8 +64,9 @@ export function frozenStatus(projectDir, filePath) {
 // Only an edit to something HEAD already froze is an evasion.
 export function frozenStatusAtHead(projectDir, filePath) {
   const rel = relPosix(projectDir, filePath);
+  const root = docsRoot(projectDir);
   if (rel.includes(".bkp.")) return { frozen: false };
-  if (rel.startsWith("docs/history/changelog/") && rel.endsWith(".md")) {
+  if (rel.startsWith(`${root}/history/changelog/`) && rel.endsWith(".md")) {
     return frozenStatus(projectDir, filePath); // already keyed on isCommitted
   }
   const inRepo = spawnSync("git", ["rev-parse", "--git-dir"], { cwd: projectDir, stdio: "ignore", timeout: 5000 });
@@ -71,10 +74,10 @@ export function frozenStatusAtHead(projectDir, filePath) {
   const res = spawnSync("git", ["show", `HEAD:${rel}`], { cwd: projectDir, encoding: "utf8", timeout: 5000 });
   const headText = res.status === 0 ? res.stdout || "" : "";
   if (!headText) return { frozen: false }; // never committed — a freeze born in this worktree is a ceremony, not an evasion
-  if (rel.startsWith("docs/history/plans/") && /^\*\*Status:\*\*\s*(Complete|Abandoned)\b/m.test(headText)) {
+  if (rel.startsWith(`${root}/history/plans/`) && /^\*\*Status:\*\*\s*(Complete|Abandoned)\b/m.test(headText)) {
     return { frozen: true, reason: "plan committed with Status: Complete or Abandoned" };
   }
-  if (rel.startsWith("docs/history/migrations/") && /^\*\*Executed:\*\*\s*\d{4}-\d{2}-\d{2}/m.test(headText)) {
+  if (rel.startsWith(`${root}/history/migrations/`) && /^\*\*Executed:\*\*\s*\d{4}-\d{2}-\d{2}/m.test(headText)) {
     return { frozen: true, reason: "outcome-stamped migration runbook" };
   }
   return { frozen: false };

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

@@ -8,6 +8,20 @@
 const OUTCOME = /^(satisfied|owes nothing|blocked)\b/i;
 const DOC_OUTCOME = /^(updated|owes nothing|blocked)\b/i;
 
+// Split one table row into trimmed cells, honouring GFM's escaped pipe.
+//
+// A THIRD TRAP OF THE SAME FAMILY, closed 2026-08-21. `\\|` is the only way to write a literal pipe
+// inside a table cell, and splitting on every `|` invents a column — every cell after it shifts
+// left, so the FIXED Outcome index lands on a neighbour and a row plainly reading `satisfied` is
+// reported undischarged. Unlike the two traps below it fails in the FALSE-POSITIVE direction: it
+// blocks a gate that is already satisfied, and the row renders and reads correctly to a human, so
+// the file looks right while the wall insists it is wrong. Split on unescaped pipes, then unescape.
+function splitRow(line) {
+  return line
+    .split(/(?<!\\)\|/)
+    .map((cell) => cell.replace(/\\\|/g, "|").trim());
+}
+
 // The table rows of one `## <heading>` section, split into trimmed cells, plus the Outcome column
 // index (null when the table predates the column — legacy, out of contract).
 function sectionTable(planText, heading) {
@@ -20,19 +34,27 @@ function sectionTable(planText, heading) {
   }
   const rows = body.filter((line) => /^\s*\|/.test(line));
   if (rows.length < 3) return null; // header + divider + at least one data row
-  const header = rows[0].split("|").map((cell) => cell.trim().toLowerCase());
+  const header = splitRow(rows[0]).map((cell) => cell.toLowerCase());
   const col = header.indexOf("outcome");
-  return { rows: rows.slice(2).map((line) => line.split("|").map((cell) => cell.trim())), col: col === -1 ? null : col };
+  return { rows: rows.slice(2).map(splitRow), col: col === -1 ? null : col };
 }
 
 // Row numbers (the `#` column) of every ledger row whose Outcome cell is empty or off-vocabulary.
+// Two traps this closed on 2026-08-20, both found by a real gate:
+//   - A row id may carry a suffix. Ledgers legitimately number an inserted row `12b`, and `^\d+$`
+//     skipped it — silently, and in the FALSE-NEGATIVE direction: an undischarged `12b` passed the
+//     wall unseen. A suffixed id is still a row.
+//   - Outcome cells arrive bolded (`**satisfied**`). undischargedDocRows already strips `*` and says
+//     so; this one did not, so the two ledgers in the same file disagreed about markdown. Nothing
+//     documented the asymmetry, and the vocabulary is about the WORD, not its emphasis.
 export function undischargedRows(planText) {
   const table = sectionTable(planText, "Test Obligations");
   if (!table || table.col === null) return [];
   const out = [];
   for (const cells of table.rows) {
-    if (!/^\d+$/.test(cells[1] || "")) continue;
-    if (!OUTCOME.test(cells[table.col] || "")) out.push(cells[1]);
+    if (!/^\d+[a-z]?$/i.test(cells[1] || "")) continue;
+    const outcome = (cells[table.col] || "").replace(/\*/g, "").trim();
+    if (!OUTCOME.test(outcome)) out.push(cells[1]);
   }
   return out;
 }

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

@@ -4,6 +4,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { docsRoot } from "./repo.mjs";
 
 // Read all of stdin synchronously; returns "" if nothing is piped.
 export function readStdin() {
@@ -116,7 +117,7 @@ export function asList(v) {
 // Scan docs/features/**/*.md and return one entry per feature doc that declares owns:.
 // Shape: { doc (repo-relative, /-separated), owns[], module, keywords[], status }.
 export function scanFeatureDocs(projectDir) {
-  const featuresDir = path.join(projectDir, "docs", "features");
+  const featuresDir = path.join(projectDir, docsRoot(projectDir), "features");
   // *.bkp.* files are install-time backups awaiting the maintenance fold — a backed-up feature
   // doc still carries owns: frontmatter, and scanning it would double-own every path it names.
   const files = listMarkdown(featuresDir).filter((f) => !f.includes(".bkp."));
@@ -147,7 +148,7 @@ export function scanFeatureDocs(projectDir) {
 export function buildIndex(projectDir) {
   // Total markdown under docs/features/, counted independently of scanFeatureDocs — which
   // drops a doc carrying no owns:, making a parse failure and a doc that owns nothing look alike.
-  const total = listMarkdown(path.join(projectDir, "docs", "features")).length;
+  const total = listMarkdown(path.join(projectDir, docsRoot(projectDir), "features")).length;
   const docs = scanFeatureDocs(projectDir);
   const lines = [];
   let deprecated = 0;
@@ -177,6 +178,76 @@ export function buildIndex(projectDir) {
   return header + lines.join("\n") + footer;
 }
 
+// Scan every doc that declares a doc→doc edge and return the edges, resolved.
+// Shape: { from, kind ("verifies"|"applies"), to, missing (the target file is absent) }.
+//
+// EVERY EDGE IS DECLARED AT THE CONSUMING END — a checklist names what it verifies, a feature names
+// the doctrine it obeys — so this walks the consumers and never looks for a hand-authored inverse.
+// A doc listing its own dependents is a defect the graph is built to make unnecessary.
+export function scanDocEdges(projectDir) {
+  const docsDir = path.join(projectDir, docsRoot(projectDir));
+  const files = listMarkdown(docsDir).filter((f) => !f.includes(".bkp."));
+  const edges = [];
+  for (const file of files) {
+    let text;
+    try {
+      text = fs.readFileSync(file, "utf8");
+    } catch (e) {
+      continue;
+    }
+    const block = frontmatter(text);
+    if (!block) continue;
+    const from = path.relative(projectDir, file).split(path.sep).join("/");
+    for (const kind of ["verifies", "applies"]) {
+      for (const to of asList(field(block, kind))) {
+        const target = to.toString().trim();
+        if (!target) continue;
+        edges.push({
+          from,
+          kind,
+          to: target,
+          missing: !fs.existsSync(path.join(projectDir, target)),
+        });
+      }
+    }
+  }
+  return edges;
+}
+
+// Build the inverse-edge index: what each doc is verified by, and what obeys it.
+//
+// THE INVERSE IS GENERATED, NEVER AUTHORED. Read this to answer "if I change this doctrine, what
+// is bound by it?" and "if I change this surface, which checklist proves it?" — the two questions
+// a prose link cannot answer, and the reason the edges are frontmatter rather than sentences.
+// A doc with no inbound edge is reachable by nothing: no change implicates it, so it rots without
+// the rot being detectable. The footer counts those, because that count IS the health metric.
+export function buildEdgeIndex(projectDir) {
+  const edges = scanDocEdges(projectDir);
+  if (edges.length === 0) return "";
+  const inverse = new Map();
+  for (const e of edges) {
+    if (!inverse.has(e.to)) inverse.set(e.to, []);
+    inverse.get(e.to).push(e);
+  }
+  const lines = [];
+  for (const [to, list] of [...inverse].sort((a, b) => a[0].localeCompare(b[0]))) {
+    const verifiedBy = list.filter((e) => e.kind === "verifies").map((e) => e.from);
+    const appliedBy = list.filter((e) => e.kind === "applies").map((e) => e.from);
+    const parts = [];
+    if (verifiedBy.length) parts.push(`verified by ${verifiedBy.sort().join(", ")}`);
+    if (appliedBy.length) parts.push(`applied by ${appliedBy.sort().join(", ")}`);
+    const absent = list.some((e) => e.missing) ? "  ← TARGET MISSING" : "";
+    lines.push(`${to} ← ${parts.join(" · ")}${absent}`);
+  }
+  const dangling = edges.filter((e) => e.missing).length;
+  const header =
+    "# Doc edge index (generated) — doc ← who verifies it · who is bound by it\n" +
+    "# Declared once at the consuming end (verifies:/applies: frontmatter); this inverse is derived.\n" +
+    "# Before changing a doc, read what points AT it — those are the docs the change implicates.\n";
+  const footer = dangling > 0 ? `\n# (${dangling} edge(s) name a doc that does not exist — fix the frontmatter)` : "";
+  return header + lines.join("\n") + footer;
+}
+
 // Compile one owns:-style glob (`**` any depth, `*` within a segment) to a RegExp
 // over /-separated repo-relative paths. `a/**` also matches `a` itself.
 export function globToRegExp(glob) {

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

@@ -4,7 +4,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import { readSafe, backtickTokens } from "./repo.mjs";
+import { readSafe, backtickTokens, docsRoot } from "./repo.mjs";
 import { globToRegExp } from "./ownership.mjs";
 
 // A plan's scope: path-shaped backticked tokens in its `## Proposed Changes` section.
@@ -31,7 +31,7 @@ export function inPlanScope(rel, scope) {
 // Every plan in the folder, parsed once: { file, status, gates, scope, hasLedger,
 // hasDocLedger, ledgerRows }. `gates` is null on legacy plans (pre-Gates format).
 export function listPlans(projectDir) {
-  const dir = path.join(projectDir, "docs", "history", "plans");
+  const dir = path.join(projectDir, docsRoot(projectDir), "history", "plans");
   let entries;
   try {
     entries = fs.readdirSync(dir).filter((f) => f.endsWith(".md"));

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

@@ -14,6 +14,28 @@ export function readSafe(file) {
   }
 }
 
+// The docs tree root for a project: <projectDir>/.claude/harness.json's `docsRoot` key when
+// present and non-empty, else "docs". A repo that already owns "docs/" upstream (the Superset
+// field trial) renames the harness's tree to "docs-nurix/" and declares it there — every hook
+// and CI check reads the root through here rather than hardcoding the segment. Tolerant: a
+// missing file, an unreadable one, or malformed JSON all fall through to the default.
+// Memoized per projectDir — hook processes are short-lived, so this only avoids re-reading the
+// marker file more than once within a single invocation, never caches across runs.
+const docsRootCache = new Map();
+export function docsRoot(projectDir) {
+  if (docsRootCache.has(projectDir)) return docsRootCache.get(projectDir);
+  let root = "docs";
+  try {
+    const marker = JSON.parse(readSafe(path.join(projectDir, ".claude", "harness.json")));
+    const declared = marker && typeof marker.docsRoot === "string" ? marker.docsRoot.trim().replace(/\/+$/, "") : "";
+    if (declared) root = declared;
+  } catch (e) {
+    /* missing, unreadable, or malformed marker — the default stands */
+  }
+  docsRootCache.set(projectDir, root);
+  return root;
+}
+
 // Repo-relative /-separated path, or null when the target lies outside the project.
 export function relIfInside(projectDir, filePath) {
   if (!filePath) return null;

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

@@ -17,8 +17,10 @@
 import fs from "node:fs";
 import path from "node:path";
 import { globToRegExp } from "./ownership.mjs";
+import { docsRoot } from "./repo.mjs";
 
-export const QUEUE_PATH = ["docs", "operations", "bookkeeping.md"];
+// Relative to the docs root (lib/repo.mjs#docsRoot) — never a bare "docs/..." literal.
+export const QUEUE_PATH = ["operations", "bookkeeping.md"];
 
 export const QUEUE_HEADER = `# Bookkeeping
 
@@ -26,7 +28,7 @@ The shared work queue keeping documentation and code in sync — a queue, never
 `;
 
 export function queueFile(projectDir) {
-  return path.join(projectDir, ...QUEUE_PATH);
+  return path.join(projectDir, docsRoot(projectDir), ...QUEUE_PATH);
 }
 
 // --- The write cell -------------------------------------------------------
@@ -351,6 +353,40 @@ export function recordAsked(projectDir, sessionId, key) {
   fs.appendFileSync(path.join(stateDir(projectDir), "asked.tsv"), `${sessionId}\t${key}\n`);
 }
 
+// Repo-scoped decision memory — the sibling of askedThisSession, and deliberately a different
+// LIFETIME. `askedThisSession` forgets at the session boundary, which is right for a gate that may
+// legitimately re-fire tomorrow; a decision like "do not install this tool here" must outlive the
+// session or the user is asked forever, which is the whole complaint the opt-in flow answers.
+// Records live in .claude/state/decisions.tsv (machine-local, self-ignored by stateDir) — whether a
+// binary is installed is a property of the MACHINE, not of the repo, so one developer's answer must
+// not bind a teammate on another box.
+//
+// FAIL OPEN TOWARD ASKING. Every unreadable path — no file, no key, malformed line, unrecognized
+// value — returns undefined, never "declined". The asymmetry is the point: a wrong "undecided"
+// costs one prompt, while a wrong "declined" silently disables a capability forever with no error
+// to observe and no way for the user to tell it apart from the tool simply never helping.
+const DECISIONS = ["accepted", "declined"];
+
+export function readDecision(projectDir, key) {
+  try {
+    const text = fs.readFileSync(path.join(projectDir, ".claude", "state", "decisions.tsv"), "utf8");
+    // Last write wins: the file is append-only, so a later answer supersedes an earlier one.
+    let found;
+    for (const line of text.split("\n")) {
+      const [k, v] = line.split("\t");
+      if (k === key && DECISIONS.includes(v)) found = v;
+    }
+    return found;
+  } catch (e) {
+    return undefined;
+  }
+}
+
+export function recordDecision(projectDir, key, value) {
+  if (!key || !DECISIONS.includes(value)) return;
+  fs.appendFileSync(path.join(stateDir(projectDir), "decisions.tsv"), `${key}\t${value}\n`);
+}
+
 // Append one tab-separated line to .claude/state/touched.tsv (file → owning doc map for the session).
 //
 // THE SESSION ID IS THE FOURTH COLUMN, and it is what lets a reader tell one session's edits from

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

@@ -20,7 +20,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { globToRegExp, listRepoFiles } from "./ownership.mjs";
-import { readSafe } from "./repo.mjs";
+import { readSafe, docsRoot } from "./repo.mjs";
 import { resolveRows } from "./state.mjs";
 import { rejectedPackages } from "./approved.mjs";
 
@@ -72,24 +72,46 @@ export const ROW_VERIFIERS = {
     return res.status === 0;
   },
 
-  // "<src> changed; owning doc <doc> may need an update" — dead once the doc is newer than the
-  // source that implicated it, which is the same freshness test the drift report already applies.
+  // "<src> changed; owning doc <doc> may need an update" — dead once the doc's PROSE has actually
+  // changed in a commit since the source's last one.
+  //
+  // NOT MTIME, WHICH IS NOT EVIDENCE OF ANYTHING. This compared `statSync().mtimeMs` and resolved
+  // the row whenever the doc's file was newer — so a formatting pass, a `git checkout`, a rebase, a
+  // stash pop, or a clone (which stamps every file at once, making the order arbitrary) all read as
+  // "the doc was updated". It fired for real: a one-line frontmatter addition across 33 owned docs
+  // silently swept a waived row whose plan was still open.
+  //
+  // NOT FRONTMATTER EITHER, and that follows from the harness's own doctrine rather than taste:
+  // `type:`/`owns:`/`applies:` and their siblings are tooling metadata, "preserved on edits, never
+  // narrated" — a key that by definition states nothing about behavior cannot answer a claim that
+  // documented behavior may have moved. So the bodies are compared with the frontmatter stripped.
+  //
+  // Unproven ⇒ the row stands. Every git failure returns false, per this file's rule that silence
+  // is its only acceptable failure mode.
   "doc-implicated": (projectDir, body) => {
     const m = /·\s+doc-implicated\s+·\s+(\S+)\s+changed;\s+owning doc\s+(\S+?)\s+may need/.exec(body);
     if (!m) return false;
     const [, src, doc] = m;
-    const mtime = (rel) => {
-      try {
-        return fs.statSync(path.join(projectDir, rel)).mtimeMs;
-      } catch (e) {
-        return null;
-      }
+    if (!fs.existsSync(path.join(projectDir, doc))) return false; // the doc is gone — a real finding
+    if (!fs.existsSync(path.join(projectDir, src))) return true; // the source is gone; nothing implicates it
+
+    const git = (...args) => spawnSync("git", args, { cwd: projectDir, timeout: 5000, encoding: "utf8" });
+    const lastCommit = git("log", "-1", "--format=%H", "--", src);
+    if (lastCommit.status !== 0) return false;
+    const since = lastCommit.stdout.trim();
+    if (!since) return false; // the source has never been committed — nothing to measure against
+
+    // Strip the leading `---` block so a metadata-only edit reads as no change at all.
+    const prose = (text) => (text.startsWith("---") ? text.slice(text.indexOf("\n---", 3) + 4) : text);
+    const at = (rev) => {
+      const res = git("show", `${rev}:${doc}`);
+      return res.status === 0 ? prose(res.stdout) : null;
     };
-    const docTime = mtime(doc);
-    const srcTime = mtime(src);
-    if (docTime === null) return false; // the doc is gone — a real finding, not a resolved one
-    if (srcTime === null) return true; // the source is gone; nothing implicates the doc any more
-    return docTime >= srcTime;
+    const then = at(since);
+    if (then === null) return true; // the doc did not exist at that commit — creating it IS the update
+    const now = at("HEAD");
+    if (now === null) return false;
+    return now !== then;
   },
 
   // "<rel> has N doc-lint finding(s)" — dead once a re-run comes back clean (or the doc is gone).
@@ -105,7 +127,7 @@ export const ROW_VERIFIERS = {
     const m = /·\s+index-row-missing\s+·\s+(\S+)\s+is not linked/.exec(body);
     if (!m) return false;
     if (!fs.existsSync(path.join(projectDir, m[1]))) return true;
-    return readSafe(path.join(projectDir, "docs", "README.md")).includes(path.basename(m[1]));
+    return readSafe(path.join(projectDir, docsRoot(projectDir), "README.md")).includes(path.basename(m[1]));
   },
 
   // "<rel> declares `<name>` (package-rejected)" — dead once the manifest drops the package