@nurix/etna 0.19.57 → 0.19.59

package/data/harness-index.json

@@ -1,5 +1,5 @@
 {
-    "fingerprint": "73e48dd4eae4",
+    "fingerprint": "44a8ddcfae78",
     "harnesses": {
         "apollo": {
             "plugin": "apollo",

package/data/harnesses/apollo/CLAUDE.md

@@ -39,7 +39,7 @@ Three peer modes, then a verification gate and a Completion step — enter where
 
 1. **The verification gate passes first** — user-triggered: when implementation completes, report it and offer the gate; never run it unbidden. It requires the plan's Test Obligations ledger to exist (proof the plan gates ran) and discharges every row, driving the real surface before pinning tests — `.claude/rules/testing.md`. A plan with outstanding obligations stays open, whatever the code does.
 2. Freeze the plan — `Status: Complete`, fill the Completed date. The file is now frozen.
-3. Flip the feature LLD to `status: active`; extend it in place with the how-it-works sections; confirm its `owns:` globs against the actual code.
+3. **Discharge the plan's Doc Obligations ledger — every row, into exactly one outcome**: **updated** (the doc now states what the code does), **owes nothing** (with the reason), or **blocked** (→ a backlog item, so the debt outlives the frozen plan). For each row's doc: flip `status: active` if it was `draft`, extend it in place with the how-it-works sections, and confirm its `owns:` globs against the actual code. A plan spanning three features discharges three rows — the ledger, not memory, says how many.
 4. Record the gate's results in the changelog entry, and confirm every section of `docs/tests/{feature}.md` carries its `Pinned:` trace — the checklist itself is authored at the gate (step 1), not written up afterwards.
 
 **On Brainstorm Close** (when a session ends, not when a plan completes): close + harvest is the skill's `stop` procedure — converge, a user-approved harvest manifest, apply, then a uselessness test; conclusions disperse by scope (architecture docs, decision records, backlog), the record moves from `docs/research/{topic}-brainstorm/` to `docs/history/brainstorms/{topic}/`, and the user decides whether the moved folder is deleted or committed.

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/agents/lld-mode.md

@@ -33,6 +33,7 @@ This tells you what already exists, what's adjacent, how detailed the LLD should
 4. **Current state** — Understand how the system works today in the area being specified
 5. **Dependencies** — Map what this feature touches and what depends on it
 6. **Ownership conflicts** — Compare the new feature's intended code paths against existing feature docs' `owns:` globs. Report overlaps (two docs claiming the same paths at equal specificity).
+7. **Invalidation** — a different question from conflict, and the one that gets missed. A conflict is two docs claiming one glob; an invalidation is **one existing doc whose stated behavior this feature makes false** — it may own entirely different paths and still be wrong once this ships. For every doc whose territory this feature touches or whose described flow it changes, name the specific claim that stops being true.
 
 ## What You Return
 
@@ -44,6 +45,7 @@ Structure your findings as:
 - **Current behavior**: How the relevant part of the system works today
 - **Conventions**: Naming, structure, and patterns to follow based on existing code
 - **Ownership conflicts**: Existing feature docs whose `owns:` globs overlap with the proposed feature. Include the conflicting paths and the owning doc name.
+- **Invalidated claims**: One row per existing doc this feature makes wrong — doc path, the claim, why it stops being true. This list seeds the plan's **Doc Obligations** ledger, so it is the research finding most likely to survive into an artifact; "none" is a real answer and says the feature is genuinely additive.
 - **Risks or concerns**: Anything the LLD should address or call out
 
 Use the documentation skill's style guide and conventions when structuring your findings — imperative voice, ASCII diagrams for flows, function signatures over implementations, concise.

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

@@ -1,7 +1,7 @@
 {
   "harness": "apollo",
   "name": "apollo",
-  "version": "1.1.6",
+  "version": "1.2.1",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
@@ -15,5 +15,5 @@
     "docs/memory/main.md",
     ".mcp.json"
   ],
-  "digest": "8e61d4b9ddcf"
+  "digest": "56f71396cdcf"
 }

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-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

@@ -75,6 +75,7 @@ function openGatedPlans(projectDir) {
       status,
       gates,
       hasLedger: /^##\s+Test Obligations\b/m.test(text),
+      hasDocLedger: /^##\s+Doc Obligations\b/m.test(text),
     });
   }
   return plans;
@@ -110,6 +111,12 @@ function fileGate(projectDir, rel, toolName) {
           `BLOCKED — plan gate. \`${plan.file}\` has no \`## Test Obligations\` section. Run the \`testing\` skill (plan-gate mode); its ledger is what the verification gate discharges.`
         );
       }
+      if (!plan.hasDocLedger) {
+        return decision(
+          "deny",
+          `BLOCKED — plan gate. \`${plan.file}\` has no \`## Doc Obligations\` section. Resolve the Proposed Changes paths against the ownership index and fill the table yourself — it is a lookup, not a skill run. "None" is a valid row when the plan touches only unowned paths.`
+        );
+      }
     }
   }
 
@@ -381,6 +388,10 @@ function stopGate(projectDir, payload) {
     };
   }
 
+  // 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)
   );

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/boundary/SKILL.md

@@ -57,8 +57,12 @@ The packs are a floor, not a fence: report any contract that passes the ships-gr
 
    ## Suggested plan amendments
    ## Missing plan subsections
+   ## Docs the plan's ledger missed
+   | Feature doc | Owned path in the touch list | In Doc Obligations? |
    ```
 
+   **The doc cross-check is free and you are the only one who can make it.** You already hold the touch list; resolving those paths against the ownership index and comparing the result to the plan's **Doc Obligations** rows costs one lookup. The plan's author wrote that ledger, so it is the one gate artifact nobody independently checked — a `None` that contradicts your touch list is the failure this section exists to catch. Report the gap; never edit the ledger yourself.
+
    **BLOCK** = any CRITICAL. HIGH findings yield **PASS WITH AMENDMENTS** — fold the amendments into the plan before coding. Order amendments sequencing-first: many violations dissolve by reordering steps (expand-then-contract, migrate-before-code) rather than changing what ships — prefer that fix, drawn from the entry's safe-change sequence.
 
 6. **Record the verdict in the plan's `Gates:` line.** Rewrite only your own segment, to exactly `Boundary: passed YYYY-MM-DD` (PASS, or PASS WITH AMENDMENTS once the amendments are folded) or `Boundary: blocked YYYY-MM-DD` (BLOCK). The compliance hook greps these exact forms — implementation edits stay blocked while the segment reads `pending`. A plan with no `Gates:` line predates the format; add the line rather than skipping the write-back.

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/apollo/skills/documentation/templates/plan.md

@@ -4,14 +4,16 @@ Record. Use for: every implementation plan. Plans are created here directly with
 
 The `boundary` skill parses the **Proposed Changes** sections to check boundary impact before execution, and the `testing` skill (plan-gate mode) writes a **Test Obligations** section into the plan at the same gate. Keep that structure stable — section headings and bullet shape are load-bearing for the parsers, and the Test Obligations table is the ledger the verification gate discharges before the plan may reach `Status: Complete`.
 
-The **`Gates:`** line is machine-read: the compliance hook greps exactly the forms below, and implementation edits are blocked while a segment reads `pending`. Each gate skill rewrites only its own segment when it runs — `boundary` to `Boundary: passed YYYY-MM-DD` or `Boundary: blocked YYYY-MM-DD`; `testing` (plan-gate mode) to `Test-plan: written YYYY-MM-DD (N rows)` — the segment label stays `Test-plan`, greppable. Never hand-edit the line to skip a gate.
+**Doc Obligations is the one ledger the plan's author writes.** Deriving tests from behavior is judgment, which is why `testing` owns that section and it is marked never-hand-author; resolving Proposed Changes' file paths to the feature docs that own them is a **lookup** against the ownership index already injected at session start. Different work, different rule — fill it yourself, while the touch list is fresh.
+
+The **`Gates:`** line is machine-read: the compliance hook greps exactly the forms below, and implementation edits are blocked while a segment reads `pending`. Each gate skill rewrites only its own segment when it runs — `boundary` to `Boundary: passed YYYY-MM-DD` or `Boundary: blocked YYYY-MM-DD`; `testing` (plan-gate mode) to `Test-plan: written YYYY-MM-DD (N rows)` — the segment label stays `Test-plan`, greppable. The author writes `Docs: mapped YYYY-MM-DD (N docs)` when the Doc Obligations table is filled. Never hand-edit the line to skip a gate.
 
 ```
 # {Feature Name}
 
 **Status:** Draft | In Progress | Complete | Abandoned
-**Gates:** Boundary: pending · Test-plan: pending
-**Spec:** [docs/features/{feature}.md](../../features/{feature}.md)
+**Gates:** Boundary: pending · Test-plan: pending · Docs: pending
+**Spec:** [docs/features/{feature}.md](../../features/{feature}.md)   <!-- one line per feature doc this plan implements against; a plan spanning three features names three -->
 **Started:** YYYY-MM-DD
 **Completed:** YYYY-MM-DD   <!-- fill when status flips to Complete -->
 
@@ -44,6 +46,18 @@ Why this work is happening *now*. Link to the spec for *what* we're building; th
 - List which cross-cutting contracts this plan affects (db schema, wire envelope, auth, events, env/config, …)
 - "None" is a valid answer and means the `boundary` check will pass cleanly
 
+## Doc Obligations
+
+<!-- One row per feature doc whose `owns:` globs intersect the Proposed Changes above — resolve
+     them against the injected ownership index. Hand-authored: this is a lookup, not research.
+     Amendable while the plan is open; discharged at Completion. -->
+
+| Doc | Claim that changes | `owns:` still accurate? |
+| --- | --- | --- |
+| `docs/features/{feature}.md` | what it says today that this plan makes false | yes / no — new paths to add |
+
+**"None" is valid** — a plan touching only unowned paths owes no doc update, and says so explicitly. It is not a free pass: `boundary` builds its own touch list from the same Proposed Changes and reports docs this table missed.
+
 ## Implementation Steps
 
 1. Concrete, ordered, testable
@@ -60,7 +74,7 @@ Why this work is happening *now*. Link to the spec for *what* we're building; th
 
 - [ ] Implementation complete
 - [ ] Verification gate passed — every Test Obligations row discharged (satisfied / owes nothing / blocked → backlog), gate run date and results noted here
-- [ ] Affected docs updated (use the injected ownership index to find them)
+- [ ] Every Doc Obligations row discharged — **updated** / **owes nothing** (with the reason) / **blocked** (→ backlog item, so the debt outlives the frozen plan)
 - [ ] Changelog entry created in `docs/history/changelog/`, carrying the gate's results
 - [ ] Plan marked `Status: Complete`, **Completed:** date filled
 

package/data/harnesses/code/CLAUDE.md

@@ -37,7 +37,7 @@ Three peer modes, then a verification gate and a Completion step — enter where
 
 1. **The verification gate passes first** — user-triggered: when implementation completes, report it and offer the gate; never run it unbidden. It requires the plan's Test Obligations ledger to exist (proof the plan gates ran) and discharges every row, driving the real surface before pinning tests — `.claude/rules/testing.md`. A plan with outstanding obligations stays open, whatever the code does.
 2. Freeze the plan — `Status: Complete`, fill the Completed date. The file is now frozen.
-3. Flip the feature LLD to `status: active`; extend it in place with the how-it-works sections; confirm its `owns:` globs against the actual code.
+3. **Discharge the plan's Doc Obligations ledger — every row, into exactly one outcome**: **updated** (the doc now states what the code does), **owes nothing** (with the reason), or **blocked** (→ a backlog item, so the debt outlives the frozen plan). For each row's doc: flip `status: active` if it was `draft`, extend it in place with the how-it-works sections, and confirm its `owns:` globs against the actual code. A plan spanning three features discharges three rows — the ledger, not memory, says how many.
 4. Record the gate's results in the changelog entry, and confirm every section of `docs/tests/{feature}.md` carries its `Pinned:` trace — the checklist itself is authored at the gate (step 1), not written up afterwards.
 
 **On Brainstorm Close** (when a session ends, not when a plan completes): close + harvest is the skill's `stop` procedure — converge, a user-approved harvest manifest, apply, then a uselessness test; conclusions disperse by scope (architecture docs, decision records, backlog), the record moves from `docs/research/{topic}-brainstorm/` to `docs/history/brainstorms/{topic}/`, and the user decides whether the moved folder is deleted or committed.

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/agents/lld-mode.md

@@ -33,6 +33,7 @@ This tells you what already exists, what's adjacent, how detailed the LLD should
 4. **Current state** — Understand how the system works today in the area being specified
 5. **Dependencies** — Map what this feature touches and what depends on it
 6. **Ownership conflicts** — Compare the new feature's intended code paths against existing feature docs' `owns:` globs. Report overlaps (two docs claiming the same paths at equal specificity).
+7. **Invalidation** — a different question from conflict, and the one that gets missed. A conflict is two docs claiming one glob; an invalidation is **one existing doc whose stated behavior this feature makes false** — it may own entirely different paths and still be wrong once this ships. For every doc whose territory this feature touches or whose described flow it changes, name the specific claim that stops being true.
 
 ## What You Return
 
@@ -44,6 +45,7 @@ Structure your findings as:
 - **Current behavior**: How the relevant part of the system works today
 - **Conventions**: Naming, structure, and patterns to follow based on existing code
 - **Ownership conflicts**: Existing feature docs whose `owns:` globs overlap with the proposed feature. Include the conflicting paths and the owning doc name.
+- **Invalidated claims**: One row per existing doc this feature makes wrong — doc path, the claim, why it stops being true. This list seeds the plan's **Doc Obligations** ledger, so it is the research finding most likely to survive into an artifact; "none" is a real answer and says the feature is genuinely additive.
 - **Risks or concerns**: Anything the LLD should address or call out
 
 Use the documentation skill's style guide and conventions when structuring your findings — imperative voice, ASCII diagrams for flows, function signatures over implementations, concise.

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

@@ -1,7 +1,7 @@
 {
   "harness": "code",
   "name": "code",
-  "version": "3.6.6",
+  "version": "3.7.1",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
@@ -10,5 +10,5 @@
   "seeds": [
     ".mcp.json"
   ],
-  "digest": "47f4949ced4c"
+  "digest": "35d9ca37898e"
 }

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-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

@@ -75,6 +75,7 @@ function openGatedPlans(projectDir) {
       status,
       gates,
       hasLedger: /^##\s+Test Obligations\b/m.test(text),
+      hasDocLedger: /^##\s+Doc Obligations\b/m.test(text),
     });
   }
   return plans;
@@ -110,6 +111,12 @@ function fileGate(projectDir, rel, toolName) {
           `BLOCKED — plan gate. \`${plan.file}\` has no \`## Test Obligations\` section. Run the \`testing\` skill (plan-gate mode); its ledger is what the verification gate discharges.`
         );
       }
+      if (!plan.hasDocLedger) {
+        return decision(
+          "deny",
+          `BLOCKED — plan gate. \`${plan.file}\` has no \`## Doc Obligations\` section. Resolve the Proposed Changes paths against the ownership index and fill the table yourself — it is a lookup, not a skill run. "None" is a valid row when the plan touches only unowned paths.`
+        );
+      }
     }
   }
 
@@ -381,6 +388,10 @@ function stopGate(projectDir, payload) {
     };
   }
 
+  // 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)
   );

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/boundary/SKILL.md

@@ -57,8 +57,12 @@ The packs are a floor, not a fence: report any contract that passes the ships-gr
 
    ## Suggested plan amendments
    ## Missing plan subsections
+   ## Docs the plan's ledger missed
+   | Feature doc | Owned path in the touch list | In Doc Obligations? |
    ```
 
+   **The doc cross-check is free and you are the only one who can make it.** You already hold the touch list; resolving those paths against the ownership index and comparing the result to the plan's **Doc Obligations** rows costs one lookup. The plan's author wrote that ledger, so it is the one gate artifact nobody independently checked — a `None` that contradicts your touch list is the failure this section exists to catch. Report the gap; never edit the ledger yourself.
+
    **BLOCK** = any CRITICAL. HIGH findings yield **PASS WITH AMENDMENTS** — fold the amendments into the plan before coding. Order amendments sequencing-first: many violations dissolve by reordering steps (expand-then-contract, migrate-before-code) rather than changing what ships — prefer that fix, drawn from the entry's safe-change sequence.
 
 6. **Record the verdict in the plan's `Gates:` line.** Rewrite only your own segment, to exactly `Boundary: passed YYYY-MM-DD` (PASS, or PASS WITH AMENDMENTS once the amendments are folded) or `Boundary: blocked YYYY-MM-DD` (BLOCK). The compliance hook greps these exact forms — implementation edits stay blocked while the segment reads `pending`. A plan with no `Gates:` line predates the format; add the line rather than skipping the write-back.

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/code/skills/documentation/templates/plan.md

@@ -4,14 +4,16 @@ Record. Use for: every implementation plan. Plans are created here directly with
 
 The `boundary` skill parses the **Proposed Changes** sections to check boundary impact before execution, and the `testing` skill (plan-gate mode) writes a **Test Obligations** section into the plan at the same gate. Keep that structure stable — section headings and bullet shape are load-bearing for the parsers, and the Test Obligations table is the ledger the verification gate discharges before the plan may reach `Status: Complete`.
 
-The **`Gates:`** line is machine-read: the compliance hook greps exactly the forms below, and implementation edits are blocked while a segment reads `pending`. Each gate skill rewrites only its own segment when it runs — `boundary` to `Boundary: passed YYYY-MM-DD` or `Boundary: blocked YYYY-MM-DD`; `testing` (plan-gate mode) to `Test-plan: written YYYY-MM-DD (N rows)` — the segment label stays `Test-plan`, greppable. Never hand-edit the line to skip a gate.
+**Doc Obligations is the one ledger the plan's author writes.** Deriving tests from behavior is judgment, which is why `testing` owns that section and it is marked never-hand-author; resolving Proposed Changes' file paths to the feature docs that own them is a **lookup** against the ownership index already injected at session start. Different work, different rule — fill it yourself, while the touch list is fresh.
+
+The **`Gates:`** line is machine-read: the compliance hook greps exactly the forms below, and implementation edits are blocked while a segment reads `pending`. Each gate skill rewrites only its own segment when it runs — `boundary` to `Boundary: passed YYYY-MM-DD` or `Boundary: blocked YYYY-MM-DD`; `testing` (plan-gate mode) to `Test-plan: written YYYY-MM-DD (N rows)` — the segment label stays `Test-plan`, greppable. The author writes `Docs: mapped YYYY-MM-DD (N docs)` when the Doc Obligations table is filled. Never hand-edit the line to skip a gate.
 
 ```
 # {Feature Name}
 
 **Status:** Draft | In Progress | Complete | Abandoned
-**Gates:** Boundary: pending · Test-plan: pending
-**Spec:** [docs/features/{feature}.md](../../features/{feature}.md)
+**Gates:** Boundary: pending · Test-plan: pending · Docs: pending
+**Spec:** [docs/features/{feature}.md](../../features/{feature}.md)   <!-- one line per feature doc this plan implements against; a plan spanning three features names three -->
 **Started:** YYYY-MM-DD
 **Completed:** YYYY-MM-DD   <!-- fill when status flips to Complete -->
 
@@ -44,6 +46,18 @@ Why this work is happening *now*. Link to the spec for *what* we're building; th
 - List which cross-cutting contracts this plan affects (db schema, wire envelope, auth, events, env/config, …)
 - "None" is a valid answer and means the `boundary` check will pass cleanly
 
+## Doc Obligations
+
+<!-- One row per feature doc whose `owns:` globs intersect the Proposed Changes above — resolve
+     them against the injected ownership index. Hand-authored: this is a lookup, not research.
+     Amendable while the plan is open; discharged at Completion. -->
+
+| Doc | Claim that changes | `owns:` still accurate? |
+| --- | --- | --- |
+| `docs/features/{feature}.md` | what it says today that this plan makes false | yes / no — new paths to add |
+
+**"None" is valid** — a plan touching only unowned paths owes no doc update, and says so explicitly. It is not a free pass: `boundary` builds its own touch list from the same Proposed Changes and reports docs this table missed.
+
 ## Implementation Steps
 
 1. Concrete, ordered, testable
@@ -60,7 +74,7 @@ Why this work is happening *now*. Link to the spec for *what* we're building; th
 
 - [ ] Implementation complete
 - [ ] Verification gate passed — every Test Obligations row discharged (satisfied / owes nothing / blocked → backlog), gate run date and results noted here
-- [ ] Affected docs updated (use the injected ownership index to find them)
+- [ ] Every Doc Obligations row discharged — **updated** / **owes nothing** (with the reason) / **blocked** (→ backlog item, so the debt outlives the frozen plan)
 - [ ] Changelog entry created in `docs/history/changelog/`, carrying the gate's results
 - [ ] Plan marked `Status: Complete`, **Completed:** date filled
 

package/data/harnesses/delivery/CLAUDE.md

@@ -55,7 +55,7 @@ Three peer modes plus a Completion step — enter wherever the user's thinking a
 | **LLD** (low-level design) | a new prompt family, task type, or eval suite | `lld-mode` agent + `documentation` skill | Plan |
 | **Plan** | an LLD is approved | `documentation` skill → `docs/history/plans/YYYY-MM-DD-{slug}.md` | Completion |
 
-**On Plan Completion:** freeze the plan (`Status: Complete`, Completed date); flip the feature LLD to `status: active` and extend it in place; confirm its `owns:` globs against the actual prompt files; write the changelog entry as a draft immediately.
+**On Plan Completion:** freeze the plan (`Status: Complete`, Completed date); discharge every Doc Obligations row into **updated**, **owes nothing** (with the reason), or **blocked** (→ backlog) — for each row's doc, flip `status: active`, extend it in place, and confirm its `owns:` globs against the actual prompt files; write the changelog entry as a draft immediately.
 
 **On Brainstorm Close:** the skill's `stop` procedure — converge, a user-approved harvest manifest, apply, uselessness test; the record moves to `docs/history/brainstorms/{topic}/`.
 

package/data/harnesses/delivery/agents/lld-mode.md

@@ -33,6 +33,7 @@ This tells you what already exists, what's adjacent, how detailed the LLD should
 4. **Current state** — Understand how the system works today in the area being specified
 5. **Dependencies** — Map what this feature touches and what depends on it
 6. **Ownership conflicts** — Compare the new feature's intended code paths against existing feature docs' `owns:` globs. Report overlaps (two docs claiming the same paths at equal specificity).
+7. **Invalidation** — a different question from conflict, and the one that gets missed. A conflict is two docs claiming one glob; an invalidation is **one existing doc whose stated behavior this feature makes false** — it may own entirely different paths and still be wrong once this ships. For every doc whose territory this feature touches or whose described flow it changes, name the specific claim that stops being true.
 
 ## What You Return
 
@@ -44,6 +45,7 @@ Structure your findings as:
 - **Current behavior**: How the relevant part of the system works today
 - **Conventions**: Naming, structure, and patterns to follow based on existing code
 - **Ownership conflicts**: Existing feature docs whose `owns:` globs overlap with the proposed feature. Include the conflicting paths and the owning doc name.
+- **Invalidated claims**: One row per existing doc this feature makes wrong — doc path, the claim, why it stops being true. This list seeds the plan's **Doc Obligations** ledger, so it is the research finding most likely to survive into an artifact; "none" is a real answer and says the feature is genuinely additive.
 - **Risks or concerns**: Anything the LLD should address or call out
 
 Use the documentation skill's style guide and conventions when structuring your findings — imperative voice, ASCII diagrams for flows, function signatures over implementations, concise.

package/data/harnesses/delivery/harness.json

@@ -1,12 +1,12 @@
 {
   "harness": "delivery",
   "name": "delivery",
-  "version": "0.1.7",
+  "version": "0.2.1",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
   "seeds": [],
-  "digest": "49197cb78351"
+  "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/delivery/skills/documentation/templates/plan.md

@@ -4,14 +4,16 @@ Record. Use for: every implementation plan. Plans are created here directly with
 
 The `boundary` skill parses the **Proposed Changes** sections to check boundary impact before execution, and the `testing` skill (plan-gate mode) writes a **Test Obligations** section into the plan at the same gate. Keep that structure stable — section headings and bullet shape are load-bearing for the parsers, and the Test Obligations table is the ledger the verification gate discharges before the plan may reach `Status: Complete`.
 
-The **`Gates:`** line is machine-read: the compliance hook greps exactly the forms below, and implementation edits are blocked while a segment reads `pending`. Each gate skill rewrites only its own segment when it runs — `boundary` to `Boundary: passed YYYY-MM-DD` or `Boundary: blocked YYYY-MM-DD`; `testing` (plan-gate mode) to `Test-plan: written YYYY-MM-DD (N rows)` — the segment label stays `Test-plan`, greppable. Never hand-edit the line to skip a gate.
+**Doc Obligations is the one ledger the plan's author writes.** Deriving tests from behavior is judgment, which is why `testing` owns that section and it is marked never-hand-author; resolving Proposed Changes' file paths to the feature docs that own them is a **lookup** against the ownership index already injected at session start. Different work, different rule — fill it yourself, while the touch list is fresh.
+
+The **`Gates:`** line is machine-read: the compliance hook greps exactly the forms below, and implementation edits are blocked while a segment reads `pending`. Each gate skill rewrites only its own segment when it runs — `boundary` to `Boundary: passed YYYY-MM-DD` or `Boundary: blocked YYYY-MM-DD`; `testing` (plan-gate mode) to `Test-plan: written YYYY-MM-DD (N rows)` — the segment label stays `Test-plan`, greppable. The author writes `Docs: mapped YYYY-MM-DD (N docs)` when the Doc Obligations table is filled. Never hand-edit the line to skip a gate.
 
 ```
 # {Feature Name}
 
 **Status:** Draft | In Progress | Complete | Abandoned
-**Gates:** Boundary: pending · Test-plan: pending
-**Spec:** [docs/features/{feature}.md](../../features/{feature}.md)
+**Gates:** Boundary: pending · Test-plan: pending · Docs: pending
+**Spec:** [docs/features/{feature}.md](../../features/{feature}.md)   <!-- one line per feature doc this plan implements against; a plan spanning three features names three -->
 **Started:** YYYY-MM-DD
 **Completed:** YYYY-MM-DD   <!-- fill when status flips to Complete -->
 
@@ -44,6 +46,18 @@ Why this work is happening *now*. Link to the spec for *what* we're building; th
 - List which cross-cutting contracts this plan affects (db schema, wire envelope, auth, events, env/config, …)
 - "None" is a valid answer and means the `boundary` check will pass cleanly
 
+## Doc Obligations
+
+<!-- One row per feature doc whose `owns:` globs intersect the Proposed Changes above — resolve
+     them against the injected ownership index. Hand-authored: this is a lookup, not research.
+     Amendable while the plan is open; discharged at Completion. -->
+
+| Doc | Claim that changes | `owns:` still accurate? |
+| --- | --- | --- |
+| `docs/features/{feature}.md` | what it says today that this plan makes false | yes / no — new paths to add |
+
+**"None" is valid** — a plan touching only unowned paths owes no doc update, and says so explicitly. It is not a free pass: `boundary` builds its own touch list from the same Proposed Changes and reports docs this table missed.
+
 ## Implementation Steps
 
 1. Concrete, ordered, testable
@@ -60,7 +74,7 @@ Why this work is happening *now*. Link to the spec for *what* we're building; th
 
 - [ ] Implementation complete
 - [ ] Verification gate passed — every Test Obligations row discharged (satisfied / owes nothing / blocked → backlog), gate run date and results noted here
-- [ ] Affected docs updated (use the injected ownership index to find them)
+- [ ] Every Doc Obligations row discharged — **updated** / **owes nothing** (with the reason) / **blocked** (→ backlog item, so the debt outlives the frozen plan)
 - [ ] Changelog entry created in `docs/history/changelog/`, carrying the gate's results
 - [ ] Plan marked `Status: Complete`, **Completed:** date filled
 

package/data/harnesses/etna/CLAUDE.md

@@ -66,7 +66,7 @@ Three peer modes plus a Completion step — enter wherever the user's thinking a
 **On Plan Completion:**
 
 1. Freeze the plan — `Status: Complete`, fill the Completed date. The file is now frozen.
-2. Flip the feature LLD to `status: active`; extend it in place with the how-it-works sections; confirm its `owns:` globs against the actual components.
+2. **Discharge the plan's Doc Obligations ledger — every row, into exactly one outcome**: **updated**, **owes nothing** (with the reason), or **blocked** (→ backlog). For each row's doc: flip `status: active` if it was `draft`, extend it in place with the how-it-works sections, confirm its `owns:` globs against the actual components. The ledger, not memory, says how many docs this plan owes.
 3. The `boundary` skill must already have gated this plan before its first implementation step — see Ownership, Boundaries & Documentation.
 
 **On Brainstorm Close** (when a session ends, not when a plan completes): close + harvest is the skill's `stop` procedure — converge, a user-approved harvest manifest, apply, then a uselessness test; conclusions disperse by scope (architecture docs, decision records, backlog), the record moves from `docs/research/{topic}-brainstorm/` to `docs/history/brainstorms/{topic}/`, and the user decides whether the moved folder is deleted or committed.

package/data/harnesses/etna/agents/lld-mode.md

@@ -33,6 +33,7 @@ This tells you what already exists, what's adjacent, how detailed the LLD should
 4. **Current state** — Understand how the system works today in the area being specified
 5. **Dependencies** — Map what this feature touches and what depends on it
 6. **Ownership conflicts** — Compare the new feature's intended code paths against existing feature docs' `owns:` globs. Report overlaps (two docs claiming the same paths at equal specificity).
+7. **Invalidation** — a different question from conflict, and the one that gets missed. A conflict is two docs claiming one glob; an invalidation is **one existing doc whose stated behavior this feature makes false** — it may own entirely different paths and still be wrong once this ships. For every doc whose territory this feature touches or whose described flow it changes, name the specific claim that stops being true.
 
 ## What You Return
 
@@ -44,6 +45,7 @@ Structure your findings as:
 - **Current behavior**: How the relevant part of the system works today
 - **Conventions**: Naming, structure, and patterns to follow based on existing code
 - **Ownership conflicts**: Existing feature docs whose `owns:` globs overlap with the proposed feature. Include the conflicting paths and the owning doc name.
+- **Invalidated claims**: One row per existing doc this feature makes wrong — doc path, the claim, why it stops being true. This list seeds the plan's **Doc Obligations** ledger, so it is the research finding most likely to survive into an artifact; "none" is a real answer and says the feature is genuinely additive.
 - **Risks or concerns**: Anything the LLD should address or call out
 
 Use the documentation skill's style guide and conventions when structuring your findings — imperative voice, ASCII diagrams for flows, function signatures over implementations, concise.

package/data/harnesses/etna/harness.json

@@ -1,12 +1,12 @@
 {
   "harness": "etna",
   "name": "etna",
-  "version": "1.3.10",
+  "version": "1.4.1",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
   "seeds": [],
-  "digest": "e9751a673dc0"
+  "digest": "dbb7424aa7c7"
 }

package/data/harnesses/etna/skills/boundary/SKILL.md

@@ -57,8 +57,12 @@ The packs are a floor, not a fence: report any contract that passes the ships-gr
 
    ## Suggested plan amendments
    ## Missing plan subsections
+   ## Docs the plan's ledger missed
+   | Feature doc | Owned path in the touch list | In Doc Obligations? |
    ```
 
+   **The doc cross-check is free and you are the only one who can make it.** You already hold the touch list; resolving those paths against the ownership index and comparing the result to the plan's **Doc Obligations** rows costs one lookup. The plan's author wrote that ledger, so it is the one gate artifact nobody independently checked — a `None` that contradicts your touch list is the failure this section exists to catch. Report the gap; never edit the ledger yourself.
+
    **BLOCK** = any CRITICAL. HIGH findings yield **PASS WITH AMENDMENTS** — fold the amendments into the plan before coding. Order amendments sequencing-first: many violations dissolve by reordering steps (expand-then-contract, migrate-before-code) rather than changing what ships — prefer that fix, drawn from the entry's safe-change sequence.
 
 6. **Record the verdict in the plan's `Gates:` line.** Rewrite only your own segment, to exactly `Boundary: passed YYYY-MM-DD` (PASS, or PASS WITH AMENDMENTS once the amendments are folded) or `Boundary: blocked YYYY-MM-DD` (BLOCK). The compliance hook greps these exact forms — implementation edits stay blocked while the segment reads `pending`. A plan with no `Gates:` line predates the format; add the line rather than skipping the write-back.

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/data/harnesses/etna/skills/documentation/templates/plan.md

@@ -4,14 +4,16 @@ Record. Use for: every implementation plan. Plans are created here directly with
 
 The `boundary` skill parses the **Proposed Changes** sections to check boundary impact before execution, and the `testing` skill (plan-gate mode) writes a **Test Obligations** section into the plan at the same gate. Keep that structure stable — section headings and bullet shape are load-bearing for the parsers, and the Test Obligations table is the ledger the verification gate discharges before the plan may reach `Status: Complete`.
 
-The **`Gates:`** line is machine-read: the compliance hook greps exactly the forms below, and implementation edits are blocked while a segment reads `pending`. Each gate skill rewrites only its own segment when it runs — `boundary` to `Boundary: passed YYYY-MM-DD` or `Boundary: blocked YYYY-MM-DD`; `testing` (plan-gate mode) to `Test-plan: written YYYY-MM-DD (N rows)` — the segment label stays `Test-plan`, greppable. Never hand-edit the line to skip a gate.
+**Doc Obligations is the one ledger the plan's author writes.** Deriving tests from behavior is judgment, which is why `testing` owns that section and it is marked never-hand-author; resolving Proposed Changes' file paths to the feature docs that own them is a **lookup** against the ownership index already injected at session start. Different work, different rule — fill it yourself, while the touch list is fresh.
+
+The **`Gates:`** line is machine-read: the compliance hook greps exactly the forms below, and implementation edits are blocked while a segment reads `pending`. Each gate skill rewrites only its own segment when it runs — `boundary` to `Boundary: passed YYYY-MM-DD` or `Boundary: blocked YYYY-MM-DD`; `testing` (plan-gate mode) to `Test-plan: written YYYY-MM-DD (N rows)` — the segment label stays `Test-plan`, greppable. The author writes `Docs: mapped YYYY-MM-DD (N docs)` when the Doc Obligations table is filled. Never hand-edit the line to skip a gate.
 
 ```
 # {Feature Name}
 
 **Status:** Draft | In Progress | Complete | Abandoned
-**Gates:** Boundary: pending · Test-plan: pending
-**Spec:** [docs/features/{feature}.md](../../features/{feature}.md)
+**Gates:** Boundary: pending · Test-plan: pending · Docs: pending
+**Spec:** [docs/features/{feature}.md](../../features/{feature}.md)   <!-- one line per feature doc this plan implements against; a plan spanning three features names three -->
 **Started:** YYYY-MM-DD
 **Completed:** YYYY-MM-DD   <!-- fill when status flips to Complete -->
 
@@ -44,6 +46,18 @@ Why this work is happening *now*. Link to the spec for *what* we're building; th
 - List which cross-cutting contracts this plan affects (db schema, wire envelope, auth, events, env/config, …)
 - "None" is a valid answer and means the `boundary` check will pass cleanly
 
+## Doc Obligations
+
+<!-- One row per feature doc whose `owns:` globs intersect the Proposed Changes above — resolve
+     them against the injected ownership index. Hand-authored: this is a lookup, not research.
+     Amendable while the plan is open; discharged at Completion. -->
+
+| Doc | Claim that changes | `owns:` still accurate? |
+| --- | --- | --- |
+| `docs/features/{feature}.md` | what it says today that this plan makes false | yes / no — new paths to add |
+
+**"None" is valid** — a plan touching only unowned paths owes no doc update, and says so explicitly. It is not a free pass: `boundary` builds its own touch list from the same Proposed Changes and reports docs this table missed.
+
 ## Implementation Steps
 
 1. Concrete, ordered, testable
@@ -60,7 +74,7 @@ Why this work is happening *now*. Link to the spec for *what* we're building; th
 
 - [ ] Implementation complete
 - [ ] Verification gate passed — every Test Obligations row discharged (satisfied / owes nothing / blocked → backlog), gate run date and results noted here
-- [ ] Affected docs updated (use the injected ownership index to find them)
+- [ ] Every Doc Obligations row discharged — **updated** / **owes nothing** (with the reason) / **blocked** (→ backlog item, so the debt outlives the frozen plan)
 - [ ] Changelog entry created in `docs/history/changelog/`, carrying the gate's results
 - [ ] Plan marked `Status: Complete`, **Completed:** date filled
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nurix/etna",
-    "version": "0.19.57",
+    "version": "0.19.59",
     "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": "73e48dd4eae4"
+    "etnaFingerprint": "44a8ddcfae78"
 }