@nurix/etna 0.19.58 → 0.19.60

package/data/harness-index.json

@@ -1,5 +1,5 @@
 {
-    "fingerprint": "411f905588e3",
+    "fingerprint": "2d248a0cd94a",
     "harnesses": {
         "apollo": {
             "plugin": "apollo",

package/data/harnesses/apollo/agents/bookkeeper.md

@@ -1,6 +1,6 @@
 ---
 name: bookkeeper
-description: Drains docs/operations/bookkeeping.md — performs mechanical fixes (owns: globs, header comments, doc-lint findings, index rows), expands note: rows into doc edits, marks rows resolved. Dispatched by the main session at turn end or commit time; never self-triggers. Triggers on "drain the bookkeeping queue", "dispatch the bookkeeper", "/bookkeeper".
+description: Drains docs/operations/bookkeeping.md — performs mechanical fixes (owns: globs, header comments, doc-lint findings, index rows), expands note: rows into doc edits, deletes each row it drains. Dispatched by the main session at turn end or commit time; never self-triggers. Triggers on "drain the bookkeeping queue", "dispatch the bookkeeper", "/bookkeeper".
 tools: Read, Glob, Grep, Edit, Write, Bash, Skill
 model: sonnet
 ---

package/data/harnesses/apollo/codex/agents/bookkeeper.toml

@@ -1,6 +1,6 @@
 # dropped Claude tools: Read, Glob, Grep, Edit, Write, Bash, Skill
 name = "bookkeeper"
-description = "Drains docs/operations/bookkeeping.md — performs mechanical fixes (owns: globs, header comments, doc-lint findings, index rows), expands note: rows into doc edits, marks rows resolved. Dispatched by the main session at turn end or commit time; never self-triggers. Triggers on \"drain the bookkeeping queue\", \"dispatch the bookkeeper\", \"/bookkeeper\"."
+description = "Drains docs/operations/bookkeeping.md — performs mechanical fixes (owns: globs, header comments, doc-lint findings, index rows), expands note: rows into doc edits, deletes each row it drains. Dispatched by the main session at turn end or commit time; never self-triggers. Triggers on \"drain the bookkeeping queue\", \"dispatch the bookkeeper\", \"/bookkeeper\"."
 developer_instructions = '''
 
 # Bookkeeper Agent

package/data/harnesses/apollo/harness.json

@@ -15,5 +15,5 @@
     "docs/memory/main.md",
     ".mcp.json"
   ],
-  "digest": "6c0123cfa9ee"
+  "digest": "91d17fd2366f"
 }

package/data/harnesses/apollo/hooks/awareness.mjs

@@ -23,6 +23,7 @@ import {
   readQueue,
   countRows,
   formatAutoRow,
+  formatNeedsSessionRow,
   appendRows,
   resolveRows,
   unexpiredWaivers,
@@ -245,6 +246,30 @@ function detectorForFile(projectDir, rel, meta, rows) {
   if (rel.endsWith(".md")) {
     // An edited doc resolves any doc-implicated row that pointed at it.
     resolveRows(projectDir, (row) => row.kind === "auto" && row.body.includes("doc-implicated") && row.body.includes(rel));
+
+    // A plan's Doc Obligations ledger names docs whose stated behavior the plan falsifies. Whether
+    // one is discharged is a judgment, never a mechanical fix — so it becomes a `needs-session:`
+    // row, the one kind the bookkeeper leaves untouched, rather than an `auto:` row a sub-agent
+    // would tick without reading the code. Raising it here rather than walling it at Stop is what
+    // gives it the queue's three existing walls (Stop, commit, CI) instead of a fourth special case.
+    // Resolve-then-append keeps exactly one row per plan, so re-editing never stacks duplicates.
+    if (rel.startsWith("docs/history/plans/")) {
+      const planText = readSafe(path.join(projectDir, rel));
+      resolveRows(projectDir, (row) => row.kind === "needs-session" && row.body.includes(rel));
+      if (
+        /^\*\*Status:\*\*\s*Complete\b/m.test(planText) &&
+        /^##\s+Doc Obligations\b/m.test(planText) &&
+        /^\s*-\s*\[ \]\s*Every Doc Obligations row discharged/m.test(planText)
+      ) {
+        rows.push(
+          formatNeedsSessionRow({
+            date: meta.date,
+            description: `${rel} reached Status: Complete with its Doc Obligations rows undischarged`,
+            refs: rel,
+          })
+        );
+      }
+    }
     if (rel.startsWith("docs/")) {
       const findings = docLint(projectDir, rel);
       if (findings.length) {

package/data/harnesses/apollo/hooks/check-changelog-presence.mjs

@@ -23,11 +23,20 @@ const entries = nameStatus
   });
 
 const LOCKFILES = /^(pnpm-lock\.yaml|package-lock\.json|yarn\.lock|bun\.lockb?|Cargo\.lock)$/;
+const HARNESS_PREFIXES = [".claude/", ".agents/", ".codex/"];
+const HARNESS_FILES = [
+  "AGENTS.md",
+  "CLAUDE.md",
+  ".mcp.json",
+  ".vscode/settings.json",
+  ".prettierignore",
+  ".prettierrc.json",
+];
+
 const exemptFile = (f) =>
   LOCKFILES.test(path.basename(f)) ||
-  f.startsWith(".claude/") ||
-  f === "AGENTS.md" ||
-  f === "CLAUDE.md" ||
+  HARNESS_PREFIXES.some((p) => f.startsWith(p)) ||
+  HARNESS_FILES.includes(f) ||
   f.startsWith("docs/history/changelog/") ||
   f === "docs/history/CHANGELOG.md";
 
@@ -43,6 +52,6 @@ if (isBot || allRenames || allExempt || hasEntry) {
 }
 console.error(
   "check-changelog-presence: HEAD is a non-exempt commit carrying no docs/history/changelog/ entry. " +
-    "Every non-exempt commit ships its entry inside it (exempt: release/bot, lockfile-only, pure renames, changelog housekeeping)."
+    "Every non-exempt commit ships its entry inside it (exempt: release/bot, harness installs and bumps, lockfile-only, pure renames, changelog housekeeping)."
 );
 process.exit(1);

package/data/harnesses/apollo/hooks/check-completion-integrity.mjs

@@ -41,13 +41,16 @@ for (const file of plans) {
     const unchecked = (text.match(/^- \[ \]/gm) || []).length;
     if (unchecked > 0) fail(`${file} is Complete with ${unchecked} unchecked Done Criteria box(es)`);
 
-    const spec = (/^\*\*Spec:\*\*\s*\[[^\]]*\]\(([^)]+)\)/m.exec(text) || [])[1];
-    if (spec) {
+    // EVERY Spec line, not the first. A plan may implement against several feature docs, and a
+    // single-match parse silently exempts all but one — the same singular assumption the Doc
+    // Obligations ledger exists to break, reintroduced here where nothing would surface it.
+    const specs = [...text.matchAll(/^\*\*Spec:\*\*\s*\[[^\]]*\]\(([^)]+)\)/gm)].map((m) => m[1]);
+    for (const spec of specs) {
       const specPath = path.resolve(plansDir, spec);
       const specText = readSafe(specPath);
       const specStatus = (field(frontmatter(specText), "status") || "").toString();
       if (specText && specStatus !== "active") {
-        fail(`${file} is Complete but its Spec LLD is status: ${specStatus || "unknown"} (expected active)`);
+        fail(`${file} is Complete but its Spec LLD ${spec} is status: ${specStatus || "unknown"} (expected active)`);
       }
       const feature = path.basename(specPath, ".md");
       if (!fs.existsSync(path.join(projectDir, "docs", "tests", `${feature}.md`))) {

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

@@ -141,13 +141,22 @@ const LOCKFILES = /^(pnpm-lock\.yaml|package-lock\.json|yarn\.lock|bun\.lockb?|C
 
 // Exempt per the changelog rule's closed list, judged mechanically: lockfile-only,
 // harness-file-only (.claude/, AGENTS.md, CLAUDE.md), or changelog housekeeping.
+const HARNESS_PREFIXES = [".claude/", ".agents/", ".codex/"];
+const HARNESS_FILES = [
+  "AGENTS.md",
+  "CLAUDE.md",
+  ".mcp.json",
+  ".vscode/settings.json",
+  ".prettierignore",
+  ".prettierrc.json",
+];
+
 function stagedExempt(files) {
   return files.every(
     (f) =>
       LOCKFILES.test(path.basename(f)) ||
-      f.startsWith(".claude/") ||
-      f === "AGENTS.md" ||
-      f === "CLAUDE.md" ||
+      HARNESS_PREFIXES.some((p) => f.startsWith(p)) ||
+      HARNESS_FILES.includes(f) ||
       f.startsWith("docs/history/changelog/") ||
       f === "docs/history/CHANGELOG.md"
   );
@@ -162,7 +171,7 @@ function commitGate(projectDir) {
     if (!staged.some((f) => f.startsWith("docs/history/changelog/"))) {
       return decision(
         "deny",
-        "BLOCKED — changelog. This commit stages no `docs/history/changelog/` entry. Every non-exempt commit carries its entry inside it (exempt: release/bot, lockfile-only, pure renames, changelog housekeeping — state which if claiming one, then stage accordingly or re-run)."
+        "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)."
       );
     }
   }
@@ -308,15 +317,6 @@ function plansCompletedThisSession(projectDir, sessionId) {
   return out;
 }
 
-// A completed plan whose Doc Obligations ledger was never discharged. Discharge is a judgment the
-// hook cannot make — whether a doc was actually updated well is a human read — so what it checks is
-// the one mechanical trace the act leaves: the Done Criteria checkbox that says every row was
-// examined. Presence of the section is gated at the implementation-edit wall; this is the other end.
-function docLedgerUndischarged(text) {
-  if (!/^##\s+Doc Obligations\b/m.test(text)) return false;
-  return /^\s*-\s*\[ \]\s*Every Doc Obligations row discharged/m.test(text);
-}
-
 // Whether some changelog entry already accounts for this plan.
 //
 // COMMITTED COUNTS. The test used to be `git status --porcelain docs/history/changelog/` — i.e. "is
@@ -397,19 +397,13 @@ function stopGate(projectDir, payload) {
     };
   }
 
-  const completed = plansCompletedThisSession(projectDir, payload.session_id);
-
-  const docsOpen = completed.filter((rel) =>
-    docLedgerUndischarged(readSafe(path.join(projectDir, rel)))
+  // 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 undocumented = plansCompletedThisSession(projectDir, payload.session_id).filter(
+    (rel) => !planHasChangelogEntry(projectDir, rel)
   );
-  if (docsOpen.length > 0) {
-    return {
-      decision: "block",
-      reason: `Plan \`${docsOpen[0]}\` reached Status: Complete with its Doc Obligations rows undischarged. Walk each row — update the doc, or mark it owes nothing with the reason, or send it to the backlog as blocked — then tick the Done Criteria line. The feature docs are the only artifact the next session inherits.`,
-    };
-  }
-
-  const undocumented = completed.filter((rel) => !planHasChangelogEntry(projectDir, rel));
   if (undocumented.length > 0) {
     return {
       decision: "block",

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

@@ -14,7 +14,7 @@ export const QUEUE_PATH = ["docs", "operations", "bookkeeping.md"];
 
 export const QUEUE_HEADER = `# Bookkeeping
 
-The shared work queue keeping documentation and code in sync — rows are appended mechanically (auto:) and by working sessions (note:), drained by the bookkeeper agent, and walled at commit: a commit is possible only when every row is resolved or waived. Row grammar and lifecycle: the behavioral-hooks feature doc. A \`waived:\` row carries \`expires=\` and is PR-reviewable history.
+The shared work queue keeping documentation and code in sync — a queue, never an archive. Rows are appended mechanically (auto:) and by working sessions (note:), drained by the bookkeeper agent, and walled at commit: a commit is possible only when every row is either **resolved, which deletes it**, or converted to \`waived:\`. A drained row leaves no trace here; what it closed is recorded in the doc it corrected, and git history holds the row itself. Row grammar and lifecycle: the \`documentation\` skill's \`templates/bookkeeping.md\`. A \`waived:\` row carries \`expires=\` and is PR-reviewable history.
 `;
 
 export function queueFile(projectDir) {
@@ -63,6 +63,13 @@ export function formatAutoRow({ date, kind, description, action, sessionId }) {
   return `- auto: ${date} · ${kind} · ${description} → ${action} | sid=${sessionId || "-"}`;
 }
 
+// Format one needs-session: row — a finding detected mechanically that only a session can resolve.
+// It carries no `sid=`: unlike an auto: row it is never drained by the bookkeeper, so the session
+// that raised it is not the one that must answer it.
+export function formatNeedsSessionRow({ date, description, refs }) {
+  return `- needs-session: ${date} · ${description} → main session resolves | refs=${refs}`;
+}
+
 // Append rows to the queue, creating the file with its genre header when absent.
 // Dedupes on the row text before the `| sid=` tail, so a re-fired detector never stacks duplicates.
 export function appendRows(projectDir, rowLines) {

package/data/harnesses/apollo/skills/documentation/templates/bookkeeping.md

@@ -7,7 +7,7 @@ The row grammar is machine-read by the hooks and CI; keep it exact. A `waived:`
 ```
 # Bookkeeping
 
-The shared work queue keeping documentation and code in sync — rows are appended mechanically (auto:) and by working sessions (note:), drained by the bookkeeper agent, and walled at commit: a commit is possible only when every row is resolved or waived. Row grammar and lifecycle: the behavioral-hooks feature doc. A `waived:` row carries `expires=` and is PR-reviewable history.
+The shared work queue keeping documentation and code in sync — a queue, never an archive. Rows are appended mechanically (auto:) and by working sessions (note:), drained by the bookkeeper agent, and walled at commit: a commit is possible only when every row is either **resolved, which deletes it**, or converted to `waived:`. A drained row leaves no trace here; what it closed is recorded in the doc it corrected, and git history holds the row itself. Row grammar and lifecycle: the `documentation` skill's `templates/bookkeeping.md`. A `waived:` row carries `expires=` and is PR-reviewable history.
 
 - auto: YYYY-MM-DD · {finding-kind} · {description} → {action} | sid={session_id} tp={transcript_path} ts={ISO}
 - note: YYYY-MM-DD · {area} · {one-line context only the session holds} → lands-in: {owning doc | backlog | memory} | sid=… tp=… ts=…

package/data/harnesses/code/agents/bookkeeper.md

@@ -1,6 +1,6 @@
 ---
 name: bookkeeper
-description: Drains docs/operations/bookkeeping.md — performs mechanical fixes (owns: globs, header comments, doc-lint findings, index rows), expands note: rows into doc edits, marks rows resolved. Dispatched by the main session at turn end or commit time; never self-triggers. Triggers on "drain the bookkeeping queue", "dispatch the bookkeeper", "/bookkeeper".
+description: Drains docs/operations/bookkeeping.md — performs mechanical fixes (owns: globs, header comments, doc-lint findings, index rows), expands note: rows into doc edits, deletes each row it drains. Dispatched by the main session at turn end or commit time; never self-triggers. Triggers on "drain the bookkeeping queue", "dispatch the bookkeeper", "/bookkeeper".
 tools: Read, Glob, Grep, Edit, Write, Bash, Skill
 model: sonnet
 ---

package/data/harnesses/code/codex/agents/bookkeeper.toml

@@ -1,6 +1,6 @@
 # dropped Claude tools: Read, Glob, Grep, Edit, Write, Bash, Skill
 name = "bookkeeper"
-description = "Drains docs/operations/bookkeeping.md — performs mechanical fixes (owns: globs, header comments, doc-lint findings, index rows), expands note: rows into doc edits, marks rows resolved. Dispatched by the main session at turn end or commit time; never self-triggers. Triggers on \"drain the bookkeeping queue\", \"dispatch the bookkeeper\", \"/bookkeeper\"."
+description = "Drains docs/operations/bookkeeping.md — performs mechanical fixes (owns: globs, header comments, doc-lint findings, index rows), expands note: rows into doc edits, deletes each row it drains. Dispatched by the main session at turn end or commit time; never self-triggers. Triggers on \"drain the bookkeeping queue\", \"dispatch the bookkeeper\", \"/bookkeeper\"."
 developer_instructions = '''
 
 # Bookkeeper Agent

package/data/harnesses/code/harness.json

@@ -10,5 +10,5 @@
   "seeds": [
     ".mcp.json"
   ],
-  "digest": "ecbd84f05b8e"
+  "digest": "77f419c9b4da"
 }

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

@@ -23,6 +23,7 @@ import {
   readQueue,
   countRows,
   formatAutoRow,
+  formatNeedsSessionRow,
   appendRows,
   resolveRows,
   unexpiredWaivers,
@@ -245,6 +246,30 @@ function detectorForFile(projectDir, rel, meta, rows) {
   if (rel.endsWith(".md")) {
     // An edited doc resolves any doc-implicated row that pointed at it.
     resolveRows(projectDir, (row) => row.kind === "auto" && row.body.includes("doc-implicated") && row.body.includes(rel));
+
+    // A plan's Doc Obligations ledger names docs whose stated behavior the plan falsifies. Whether
+    // one is discharged is a judgment, never a mechanical fix — so it becomes a `needs-session:`
+    // row, the one kind the bookkeeper leaves untouched, rather than an `auto:` row a sub-agent
+    // would tick without reading the code. Raising it here rather than walling it at Stop is what
+    // gives it the queue's three existing walls (Stop, commit, CI) instead of a fourth special case.
+    // Resolve-then-append keeps exactly one row per plan, so re-editing never stacks duplicates.
+    if (rel.startsWith("docs/history/plans/")) {
+      const planText = readSafe(path.join(projectDir, rel));
+      resolveRows(projectDir, (row) => row.kind === "needs-session" && row.body.includes(rel));
+      if (
+        /^\*\*Status:\*\*\s*Complete\b/m.test(planText) &&
+        /^##\s+Doc Obligations\b/m.test(planText) &&
+        /^\s*-\s*\[ \]\s*Every Doc Obligations row discharged/m.test(planText)
+      ) {
+        rows.push(
+          formatNeedsSessionRow({
+            date: meta.date,
+            description: `${rel} reached Status: Complete with its Doc Obligations rows undischarged`,
+            refs: rel,
+          })
+        );
+      }
+    }
     if (rel.startsWith("docs/")) {
       const findings = docLint(projectDir, rel);
       if (findings.length) {

package/data/harnesses/code/hooks/check-changelog-presence.mjs

@@ -23,11 +23,20 @@ const entries = nameStatus
   });
 
 const LOCKFILES = /^(pnpm-lock\.yaml|package-lock\.json|yarn\.lock|bun\.lockb?|Cargo\.lock)$/;
+const HARNESS_PREFIXES = [".claude/", ".agents/", ".codex/"];
+const HARNESS_FILES = [
+  "AGENTS.md",
+  "CLAUDE.md",
+  ".mcp.json",
+  ".vscode/settings.json",
+  ".prettierignore",
+  ".prettierrc.json",
+];
+
 const exemptFile = (f) =>
   LOCKFILES.test(path.basename(f)) ||
-  f.startsWith(".claude/") ||
-  f === "AGENTS.md" ||
-  f === "CLAUDE.md" ||
+  HARNESS_PREFIXES.some((p) => f.startsWith(p)) ||
+  HARNESS_FILES.includes(f) ||
   f.startsWith("docs/history/changelog/") ||
   f === "docs/history/CHANGELOG.md";
 
@@ -43,6 +52,6 @@ if (isBot || allRenames || allExempt || hasEntry) {
 }
 console.error(
   "check-changelog-presence: HEAD is a non-exempt commit carrying no docs/history/changelog/ entry. " +
-    "Every non-exempt commit ships its entry inside it (exempt: release/bot, lockfile-only, pure renames, changelog housekeeping)."
+    "Every non-exempt commit ships its entry inside it (exempt: release/bot, harness installs and bumps, lockfile-only, pure renames, changelog housekeeping)."
 );
 process.exit(1);

package/data/harnesses/code/hooks/check-completion-integrity.mjs

@@ -41,13 +41,16 @@ for (const file of plans) {
     const unchecked = (text.match(/^- \[ \]/gm) || []).length;
     if (unchecked > 0) fail(`${file} is Complete with ${unchecked} unchecked Done Criteria box(es)`);
 
-    const spec = (/^\*\*Spec:\*\*\s*\[[^\]]*\]\(([^)]+)\)/m.exec(text) || [])[1];
-    if (spec) {
+    // EVERY Spec line, not the first. A plan may implement against several feature docs, and a
+    // single-match parse silently exempts all but one — the same singular assumption the Doc
+    // Obligations ledger exists to break, reintroduced here where nothing would surface it.
+    const specs = [...text.matchAll(/^\*\*Spec:\*\*\s*\[[^\]]*\]\(([^)]+)\)/gm)].map((m) => m[1]);
+    for (const spec of specs) {
       const specPath = path.resolve(plansDir, spec);
       const specText = readSafe(specPath);
       const specStatus = (field(frontmatter(specText), "status") || "").toString();
       if (specText && specStatus !== "active") {
-        fail(`${file} is Complete but its Spec LLD is status: ${specStatus || "unknown"} (expected active)`);
+        fail(`${file} is Complete but its Spec LLD ${spec} is status: ${specStatus || "unknown"} (expected active)`);
       }
       const feature = path.basename(specPath, ".md");
       if (!fs.existsSync(path.join(projectDir, "docs", "tests", `${feature}.md`))) {

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

@@ -141,13 +141,22 @@ const LOCKFILES = /^(pnpm-lock\.yaml|package-lock\.json|yarn\.lock|bun\.lockb?|C
 
 // Exempt per the changelog rule's closed list, judged mechanically: lockfile-only,
 // harness-file-only (.claude/, AGENTS.md, CLAUDE.md), or changelog housekeeping.
+const HARNESS_PREFIXES = [".claude/", ".agents/", ".codex/"];
+const HARNESS_FILES = [
+  "AGENTS.md",
+  "CLAUDE.md",
+  ".mcp.json",
+  ".vscode/settings.json",
+  ".prettierignore",
+  ".prettierrc.json",
+];
+
 function stagedExempt(files) {
   return files.every(
     (f) =>
       LOCKFILES.test(path.basename(f)) ||
-      f.startsWith(".claude/") ||
-      f === "AGENTS.md" ||
-      f === "CLAUDE.md" ||
+      HARNESS_PREFIXES.some((p) => f.startsWith(p)) ||
+      HARNESS_FILES.includes(f) ||
       f.startsWith("docs/history/changelog/") ||
       f === "docs/history/CHANGELOG.md"
   );
@@ -162,7 +171,7 @@ function commitGate(projectDir) {
     if (!staged.some((f) => f.startsWith("docs/history/changelog/"))) {
       return decision(
         "deny",
-        "BLOCKED — changelog. This commit stages no `docs/history/changelog/` entry. Every non-exempt commit carries its entry inside it (exempt: release/bot, lockfile-only, pure renames, changelog housekeeping — state which if claiming one, then stage accordingly or re-run)."
+        "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)."
       );
     }
   }
@@ -308,15 +317,6 @@ function plansCompletedThisSession(projectDir, sessionId) {
   return out;
 }
 
-// A completed plan whose Doc Obligations ledger was never discharged. Discharge is a judgment the
-// hook cannot make — whether a doc was actually updated well is a human read — so what it checks is
-// the one mechanical trace the act leaves: the Done Criteria checkbox that says every row was
-// examined. Presence of the section is gated at the implementation-edit wall; this is the other end.
-function docLedgerUndischarged(text) {
-  if (!/^##\s+Doc Obligations\b/m.test(text)) return false;
-  return /^\s*-\s*\[ \]\s*Every Doc Obligations row discharged/m.test(text);
-}
-
 // Whether some changelog entry already accounts for this plan.
 //
 // COMMITTED COUNTS. The test used to be `git status --porcelain docs/history/changelog/` — i.e. "is
@@ -397,19 +397,13 @@ function stopGate(projectDir, payload) {
     };
   }
 
-  const completed = plansCompletedThisSession(projectDir, payload.session_id);
-
-  const docsOpen = completed.filter((rel) =>
-    docLedgerUndischarged(readSafe(path.join(projectDir, rel)))
+  // 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 undocumented = plansCompletedThisSession(projectDir, payload.session_id).filter(
+    (rel) => !planHasChangelogEntry(projectDir, rel)
   );
-  if (docsOpen.length > 0) {
-    return {
-      decision: "block",
-      reason: `Plan \`${docsOpen[0]}\` reached Status: Complete with its Doc Obligations rows undischarged. Walk each row — update the doc, or mark it owes nothing with the reason, or send it to the backlog as blocked — then tick the Done Criteria line. The feature docs are the only artifact the next session inherits.`,
-    };
-  }
-
-  const undocumented = completed.filter((rel) => !planHasChangelogEntry(projectDir, rel));
   if (undocumented.length > 0) {
     return {
       decision: "block",

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

@@ -14,7 +14,7 @@ export const QUEUE_PATH = ["docs", "operations", "bookkeeping.md"];
 
 export const QUEUE_HEADER = `# Bookkeeping
 
-The shared work queue keeping documentation and code in sync — rows are appended mechanically (auto:) and by working sessions (note:), drained by the bookkeeper agent, and walled at commit: a commit is possible only when every row is resolved or waived. Row grammar and lifecycle: the behavioral-hooks feature doc. A \`waived:\` row carries \`expires=\` and is PR-reviewable history.
+The shared work queue keeping documentation and code in sync — a queue, never an archive. Rows are appended mechanically (auto:) and by working sessions (note:), drained by the bookkeeper agent, and walled at commit: a commit is possible only when every row is either **resolved, which deletes it**, or converted to \`waived:\`. A drained row leaves no trace here; what it closed is recorded in the doc it corrected, and git history holds the row itself. Row grammar and lifecycle: the \`documentation\` skill's \`templates/bookkeeping.md\`. A \`waived:\` row carries \`expires=\` and is PR-reviewable history.
 `;
 
 export function queueFile(projectDir) {
@@ -63,6 +63,13 @@ export function formatAutoRow({ date, kind, description, action, sessionId }) {
   return `- auto: ${date} · ${kind} · ${description} → ${action} | sid=${sessionId || "-"}`;
 }
 
+// Format one needs-session: row — a finding detected mechanically that only a session can resolve.
+// It carries no `sid=`: unlike an auto: row it is never drained by the bookkeeper, so the session
+// that raised it is not the one that must answer it.
+export function formatNeedsSessionRow({ date, description, refs }) {
+  return `- needs-session: ${date} · ${description} → main session resolves | refs=${refs}`;
+}
+
 // Append rows to the queue, creating the file with its genre header when absent.
 // Dedupes on the row text before the `| sid=` tail, so a re-fired detector never stacks duplicates.
 export function appendRows(projectDir, rowLines) {

package/data/harnesses/code/skills/documentation/templates/bookkeeping.md

@@ -7,7 +7,7 @@ The row grammar is machine-read by the hooks and CI; keep it exact. A `waived:`
 ```
 # Bookkeeping
 
-The shared work queue keeping documentation and code in sync — rows are appended mechanically (auto:) and by working sessions (note:), drained by the bookkeeper agent, and walled at commit: a commit is possible only when every row is resolved or waived. Row grammar and lifecycle: the behavioral-hooks feature doc. A `waived:` row carries `expires=` and is PR-reviewable history.
+The shared work queue keeping documentation and code in sync — a queue, never an archive. Rows are appended mechanically (auto:) and by working sessions (note:), drained by the bookkeeper agent, and walled at commit: a commit is possible only when every row is either **resolved, which deletes it**, or converted to `waived:`. A drained row leaves no trace here; what it closed is recorded in the doc it corrected, and git history holds the row itself. Row grammar and lifecycle: the `documentation` skill's `templates/bookkeeping.md`. A `waived:` row carries `expires=` and is PR-reviewable history.
 
 - auto: YYYY-MM-DD · {finding-kind} · {description} → {action} | sid={session_id} tp={transcript_path} ts={ISO}
 - note: YYYY-MM-DD · {area} · {one-line context only the session holds} → lands-in: {owning doc | backlog | memory} | sid=… tp=… ts=…

package/data/harnesses/delivery/harness.json

@@ -8,5 +8,5 @@
     ".vscode/settings.json"
   ],
   "seeds": [],
-  "digest": "a2c8df3022bd"
+  "digest": "9200d5f0c074"
 }

package/data/harnesses/delivery/skills/documentation/templates/bookkeeping.md

@@ -7,7 +7,7 @@ The row grammar is machine-read by the hooks and CI; keep it exact. A `waived:`
 ```
 # Bookkeeping
 
-The shared work queue keeping documentation and code in sync — rows are appended mechanically (auto:) and by working sessions (note:), drained by the bookkeeper agent, and walled at commit: a commit is possible only when every row is resolved or waived. Row grammar and lifecycle: the behavioral-hooks feature doc. A `waived:` row carries `expires=` and is PR-reviewable history.
+The shared work queue keeping documentation and code in sync — a queue, never an archive. Rows are appended mechanically (auto:) and by working sessions (note:), drained by the bookkeeper agent, and walled at commit: a commit is possible only when every row is either **resolved, which deletes it**, or converted to `waived:`. A drained row leaves no trace here; what it closed is recorded in the doc it corrected, and git history holds the row itself. Row grammar and lifecycle: the `documentation` skill's `templates/bookkeeping.md`. A `waived:` row carries `expires=` and is PR-reviewable history.
 
 - auto: YYYY-MM-DD · {finding-kind} · {description} → {action} | sid={session_id} tp={transcript_path} ts={ISO}
 - note: YYYY-MM-DD · {area} · {one-line context only the session holds} → lands-in: {owning doc | backlog | memory} | sid=… tp=… ts=…

package/data/harnesses/etna/harness.json

@@ -8,5 +8,5 @@
     ".vscode/settings.json"
   ],
   "seeds": [],
-  "digest": "171db7dbad6a"
+  "digest": "dbb7424aa7c7"
 }

package/data/harnesses/etna/skills/documentation/templates/bookkeeping.md

@@ -7,7 +7,7 @@ The row grammar is machine-read by the hooks and CI; keep it exact. A `waived:`
 ```
 # Bookkeeping
 
-The shared work queue keeping documentation and code in sync — rows are appended mechanically (auto:) and by working sessions (note:), drained by the bookkeeper agent, and walled at commit: a commit is possible only when every row is resolved or waived. Row grammar and lifecycle: the behavioral-hooks feature doc. A `waived:` row carries `expires=` and is PR-reviewable history.
+The shared work queue keeping documentation and code in sync — a queue, never an archive. Rows are appended mechanically (auto:) and by working sessions (note:), drained by the bookkeeper agent, and walled at commit: a commit is possible only when every row is either **resolved, which deletes it**, or converted to `waived:`. A drained row leaves no trace here; what it closed is recorded in the doc it corrected, and git history holds the row itself. Row grammar and lifecycle: the `documentation` skill's `templates/bookkeeping.md`. A `waived:` row carries `expires=` and is PR-reviewable history.
 
 - auto: YYYY-MM-DD · {finding-kind} · {description} → {action} | sid={session_id} tp={transcript_path} ts={ISO}
 - note: YYYY-MM-DD · {area} · {one-line context only the session holds} → lands-in: {owning doc | backlog | memory} | sid=… tp=… ts=…

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nurix/etna",
-    "version": "0.19.58",
+    "version": "0.19.60",
     "description": "Bootstrap a project with a Nurix harness — copies the harness's CLAUDE.md, skills, agents, rules, and hooks directly into the project from a bundled payload (no marketplace fetch, no network).",
     "type": "module",
     "bin": {
@@ -42,5 +42,5 @@
         "agent",
         "plugin"
     ],
-    "etnaFingerprint": "411f905588e3"
+    "etnaFingerprint": "2d248a0cd94a"
 }