@nurix/etna 0.19.57 → 0.19.58

package/data/harness-index.json

@@ -1,5 +1,5 @@
 {
-    "fingerprint": "73e48dd4eae4",
+    "fingerprint": "411f905588e3",
     "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/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/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": "6c0123cfa9ee"
 }

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.`
+        );
+      }
     }
   }
 
@@ -301,6 +308,15 @@ 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
@@ -381,9 +397,19 @@ function stopGate(projectDir, payload) {
     };
   }
 
-  const undocumented = plansCompletedThisSession(projectDir, payload.session_id).filter(
-    (rel) => !planHasChangelogEntry(projectDir, rel)
+  const completed = plansCompletedThisSession(projectDir, payload.session_id);
+
+  const docsOpen = completed.filter((rel) =>
+    docLedgerUndischarged(readSafe(path.join(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/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/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/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/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": "ecbd84f05b8e"
 }

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.`
+        );
+      }
     }
   }
 
@@ -301,6 +308,15 @@ 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
@@ -381,9 +397,19 @@ function stopGate(projectDir, payload) {
     };
   }
 
-  const undocumented = plansCompletedThisSession(projectDir, payload.session_id).filter(
-    (rel) => !planHasChangelogEntry(projectDir, rel)
+  const completed = plansCompletedThisSession(projectDir, payload.session_id);
+
+  const docsOpen = completed.filter((rel) =>
+    docLedgerUndischarged(readSafe(path.join(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/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/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": "a2c8df3022bd"
 }

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": "171db7dbad6a"
 }

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/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.58",
     "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": "411f905588e3"
 }