@nurix/etna 0.20.2 → 0.20.3

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,8 +460,8 @@ 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. "
           : "") +

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

package/data/harnesses/code/rules/testing.md

@@ -30,9 +30,10 @@ Rules for the plan regime between the plan gate and the verification gate:
 **A discrete, user-triggered step.** When implementation is complete, report it and offer the gate — never run it unbidden, and never flip `Status: Complete` without it. An explicit user acceptance of finished plan work — "ship it", "commit", "looks good" — counts as the trigger; open the gate without asking again. A plan with outstanding obligations stays open, whatever the code does. The procedure — checklist, drive-then-pin ladder, row discharge, what earns a durable test — is the `testing` skill (gate mode).
 
 - **Precondition: the ledger exists.** A plan with no Test Obligations section is blocked at the gate — run the `testing` skill (plan-gate mode) on it first; an empty ledger passes vacuously and the gap surfaces only after the file is frozen.
-- **The verdict is never delegated** (the root policy file § Delegation), and where browser work is main-session-only (its § Runtime Notes), the driving is too. Fan-out may prepare fixtures or draft test bodies; the driving and the verdict stay inline.
+- **The verdict is never delegated** (the root policy file § Delegation), and where browser work is main-session-only (its § Runtime Notes), the driving is too. **Authoring test files is dispatched fan-out by default** — at any nesting level, sub-agents on the cheapest capable tier write the pins from the checklist and ledger rows while the gating agent keeps the checklist, the driving, the cold-shell suite run, and every discharge: a sub-agent's green claim is a report, and the verdict is the re-run. Only a lone regression test riding a bug fix stays inline — briefing a sub-agent costs more than the test.
 - **The gate needs no stronger tier than the session default** — a standard-tier session suffices whatever tier built the plan; the plan and its ledger carry all the state the gate needs, so gating in a fresh session loses nothing.
-- **Browser driving is the gate's final rung.** Playwright / Chrome CDP drives run once, at the end, after suites and cheap oracles are green — never interleaved mid-loop; they are the most expensive oracle in time and tokens.
+- **On a rendered surface, browser driving LEADS the gate — it is not its final rung.** The order inverted deliberately: the defects that reach users through an interface are geometric and compositional, and a simulated DOM computes no layout, so a suite that is entirely green says nothing about whether anything is where it should be. **Reach the browser Chrome-CDP-first and Playwright second** — CDP drives a real browser interactively and needs no script written in advance, which is what discovery requires; Playwright is the fallback where CDP is unavailable and the tool of record for whatever must run unattended afterwards. Cheap oracles run in the same pass and are what the drive's findings get pinned into; they are no longer a gate to pass before looking. A surface with nothing rendered — a CLI, a service, a library — drives its own real binary or wire instead, and this clause does not apply.
+- **A judged drive discovers; a scripted assertion guards.** Only the first finds a defect nobody has seen — a script asserting a control's value passes over a control drawn on top of its own label. Scripts are written after a judged drive names the class of defect, never generated ahead of one, and **a red script is never regenerated** — regeneration re-derives the assertion from the surface as it currently is, which turns a defect into the asserted truth with everything green.
 - **Report what happened, including failures.** A gate that reports green while a suite is red is worse than no gate; state the failing test and its output.
 - **Abandonment does not erase debt.** Before `Status: Abandoned` freezes a plan whose code was committed, convert its undischarged rows into backlog items; uncommitted code owes nothing.
 
@@ -40,13 +41,15 @@ Rules for the plan regime between the plan gate and the verification gate:
 
 Framework choice is **never** ad hoc and never the user's problem mid-task: detect the stack, use its row; if the repo already has a runner, that runner wins — **never** introduce a second framework beside it.
 
-| Stack | Unit / integration | Component | E2E | HTTP mocking | Don't use |
-| --- | --- | --- | --- | --- | --- |
-| Node + Vite / React (web) | `vitest` | `@testing-library/react` (+ `@testing-library/user-event`, `happy-dom`) | `@playwright/test` | `msw` | `jest`, `mocha`, `jasmine`, `cypress`, `enzyme` |
-| Express APIs | `vitest` | — | `supertest` against the app instance | `msw` (outbound calls) | `jest`, `chai-http` |
-| React Native / Expo | `jest` via the `jest-expo` preset | `@testing-library/react-native` | `maestro` | `msw` | `detox`, `enzyme` |
-| Cloudflare Workers | `vitest` + `@cloudflare/vitest-pool-workers` | — | `@playwright/test` against `wrangler dev` | `msw` | `jest` |
-| Rust | `cargo test` (built-in) | — | — | — | — |
+| Stack | Unit / integration | Component | Rendered (7b) | Judged drive | E2E | HTTP mocking | Don't use |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| Node + Vite / React (web) | `vitest` | `@testing-library/react` (+ `@testing-library/user-event`, `happy-dom`) | `vitest` browser mode, Playwright provider | Chrome CDP, else `@playwright/test` headed | `@playwright/test` | `msw` | `jest`, `mocha`, `jasmine`, `cypress`, `enzyme` |
+| Express APIs | `vitest` | — | — (nothing rendered) | the real wire — `curl`/HTTP against the running app | `supertest` against the app instance | `msw` (outbound calls) | `jest`, `chai-http` |
+| React Native / Expo | `jest` via the `jest-expo` preset | `@testing-library/react-native` | `maestro` on a device/simulator | the simulator, watched | `maestro` | `msw` | `detox`, `enzyme` |
+| Cloudflare Workers | `vitest` + `@cloudflare/vitest-pool-workers` | — | — (nothing rendered) | the real wire against `wrangler dev` | `@playwright/test` against `wrangler dev` | `msw` | `jest` |
+| Rust | `cargo test` (built-in) | — | the app window, driven by the OS layer where one exists | the running binary, watched | — | — | — |
+
+**The two new columns are the inversion made concrete.** *Rendered (7b)* is the unattended real-engine runner — where geometry pins live, and `—` where a stack renders nothing. *Judged drive* is what a person or an agent looks at when a change is finished, and it leads the gate on any stack that renders: Chrome CDP first because it drives a real browser with no script written in advance, Playwright headed where CDP is unavailable. A stack whose judged drive is `—` has no interface to look at, not permission to skip looking.
 
 Test packages install at `latest` — outside the approved-packages pin set. Fake data comes from `@ngneat/falso` — **never** `@faker-js/faker` / `chance`.
 
@@ -55,6 +58,7 @@ Test packages install at `latest` — outside the approved-packages pin set. Fak
 - **Suite, not scripts.** Tests live in the canonical test tree — `tests/` mirroring `src/`, or the convention the repo already uses — named `<subject>.test.ts`; shared fixtures, factories, and helpers in `tests/helpers/` (or the suite's existing shared home).
 - **Wire the canonical command.** `"test"` in `package.json` runs the whole unit suite (`vitest run`); e2e under `"test:e2e"`. A repo where `pnpm test` / `npm test` doesn't run the suite is misconfigured — fix the wiring, **never** route around it.
 - **Unit and E2E trees stay separate.** Vitest/Jest suites in `tests/`; Playwright/Maestro suites in `e2e/` with their own config — **never** mixed into the unit runner's glob.
+- **The real-renderer stratum is a third tree** — `tests/rendered/` under the unit runner's *browser mode*, its own config, kept to geometry regressions that shipped and the composition assertions a component library cannot make alone. It is not a second component suite; anything a simulated DOM can prove stays in `tests/component/`.
 - **No test doubles for what you own.** Prefer real instances — in-memory SQLite for drizzle, the actual Express app via `supertest` — over mocks; mock **only** true externals (network via `msw`, time via the runner's fake timers).
 - **Determinism.** No real network, no real time, no shared mutable state between tests; every test **must** pass alone, in any order, **and from a cold shell** — never against a hand-started dev server (Workers: `@cloudflare/vitest-pool-workers`; Express: `supertest` against the app instance).