@nurix/etna 0.19.56 → 0.19.58

package/data/harness-index.json

@@ -1,5 +1,5 @@
 {
-    "fingerprint": "e7493c40d358",
+    "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/bookkeeper.md

@@ -2,7 +2,7 @@
 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".
 tools: Read, Glob, Grep, Edit, Write, Bash, Skill
-model: inherit
+model: sonnet
 ---
 
 # Bookkeeper Agent

package/data/harnesses/apollo/agents/change-review.md

@@ -2,7 +2,7 @@
 name: change-review
 description: Velocity + change-risk analysis. First classifies recent commits into a pipe-delimited velocity/severity CSV by dispatching parallel low-cost subagents (module, feature, impact, severity, churn), then derives a commit heatmap, risk zones (high churn in contract-heavy code), stabilization signals, and team/bus-factor distribution. Self-contained — produces its own CSV, no separate git-history step. Use when planning where to invest in review focus or rules.
 tools: Bash, Read, Write, Glob, Grep, Task
-model: inherit
+model: sonnet
 ---
 
 # Change-Review Agent

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

@@ -2,7 +2,7 @@
 name: lld-mode
 description: LLD researcher for Feature and Product workflows. Use to explore the codebase and gather the context needed for writing a feature LLD (low-level design — the feature doc in docs/features/). Returns research findings — does not write files.
 tools: Read, Glob, Grep, WebSearch, WebFetch
-model: inherit
+model: opus
 skills:
   - documentation
 ---
@@ -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/agents/maintenance.md

@@ -2,7 +2,7 @@
 name: maintenance
 description: The single docs steward. Default behavior is the docs-vs-code coherence audit — detects and fixes docs drifting from code (stale docs, broken ownership, unowned source paths, architecture/backlog drift). An additive **baseline mode** layers structural reconcile on top: when the repo's `harness-version` marker is missing or behind, it converges `docs/` to the installed harness shape (scaffold the standard tree, fold dissolved-shape artifacts forward, stamp the version, propose modules) before running the audit. Mode is auto-selected from the marker. Run weekly, after major changes, or to baseline/upgrade a repo. Cross-cutting contract analysis is the `boundary` skill (`check` for plans, `scan` for diffs) — it derives contracts dynamically from source; there are no persisted boundary docs to audit. Triggers on "run maintenance", "docs health", "baseline this repo", "reconcile the harness", "upgrade the harness", "is this repo on the current harness", "/maintenance".
 tools: Read, Glob, Grep, Edit, Write, Bash
-model: inherit
+model: opus
 ---
 
 # Maintenance Agent

package/data/harnesses/apollo/agents/performance-review.md

@@ -2,7 +2,7 @@
 name: performance-review
 description: Combined dependency + code health audit. Part A audits the dependency supply chain — security CVEs, outdated packages, license compliance, abandoned packages, unwanted transitive dependencies, install size. Part B audits code-level health — bundle size, tree-shaking issues, performance anti-patterns, code-quality flags. Run weekly or before releases. Merges the former `dep-health` and `review` agents so the package tree and the code that uses it are audited together.
 tools: Read, Glob, Grep, Bash
-model: inherit
+model: opus
 ---
 
 # Performance-Review Agent

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

@@ -2,7 +2,7 @@
 name: retro
 description: Session-distillation agent for the changelog. Reads the per-unit-of-work entries under `docs/history/changelog/` accumulated since its last run and distills the refinement delta — what user-driven iteration added that the one-shot build lacked — into a typed punch list of doc-content gaps, doc-structure moves (missing doc / mothership split / merge), skill-evolution findings backed by survived-vs-overridden counts, unpinned discoveries needing an enforced artifact (test, token, guardrail, schema), and cross-project harness rules. Proposes only — actionable items land in the backlog, never applied directly. Run on demand: before a brainstorm or LLD session, before starting a new project, or after a refinement arc. Triggers on "run retro", "distill the changelog", "refinement retro", "/retro".
 tools: Read, Glob, Grep, Bash, Write, Edit
-model: inherit
+model: opus
 ---
 
 # Retro — changelog distillation

package/data/harnesses/apollo/harness.json

@@ -1,7 +1,7 @@
 {
   "harness": "apollo",
   "name": "apollo",
-  "version": "1.1.5",
+  "version": "1.2.1",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
@@ -15,5 +15,5 @@
     "docs/memory/main.md",
     ".mcp.json"
   ],
-  "digest": "47955a71244a"
+  "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
@@ -325,6 +341,43 @@ function planHasChangelogEntry(projectDir, planRel) {
   return names.some((name) => name.endsWith(".md") && readSafe(path.join(dir, name)).includes(slug));
 }
 
+// Approximate the context the next turn will re-read, from the transcript's last recorded usage.
+// Best-effort: an absent or unparseable transcript reports nothing.
+function sessionContextTokens(transcriptPath) {
+  const text = readSafe(transcriptPath || "");
+  if (!text) return 0;
+  const lines = text.slice(-400000).split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (!lines[i].includes('"usage"')) continue;
+    try {
+      const u = JSON.parse(lines[i]).message.usage;
+      return (
+        (u.input_tokens || 0) + (u.cache_read_input_tokens || 0) + (u.cache_creation_input_tokens || 0)
+      );
+    } catch (e) {
+      // the slice cut this line in half — keep scanning upward
+    }
+  }
+  return 0;
+}
+
+// Context re-reads in full on every turn, so its size IS the standing per-turn floor — the one
+// number that argues for ending a session rather than carrying it into unrelated work. The agent
+// cannot act on this (it can neither end a session nor start one), so it is addressed to the user
+// as a systemMessage and never blocks. Kept out of the model's context deliberately: a running
+// token count in-context produces context anxiety, not shorter sessions.
+const CONTEXT_ADVISORY_TOKENS = 250000;
+
+function sessionSizeNote(payload) {
+  const tokens = sessionContextTokens(payload.transcript_path);
+  if (tokens < CONTEXT_ADVISORY_TOKENS) return null;
+  return (
+    `Session context is roughly ${Math.round(tokens / 1000)}K tokens, and every turn re-reads all of it — ` +
+    "that is the per-turn floor before anything new is produced. A fresh session starts near zero; " +
+    "worth ending this one if the next task is unrelated."
+  );
+}
+
 function stopGate(projectDir, payload) {
   if (payload.stop_hook_active) return null; // the runtime's infinite-loop guard — never re-block
 
@@ -344,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",
@@ -381,6 +444,11 @@ function main() {
     }
   } else if (event === "Stop") {
     out = stopGate(projectDir, payload);
+    // Advisory rides alongside a block rather than replacing it — both are true at once.
+    if (!payload.stop_hook_active) {
+      const note = sessionSizeNote(payload);
+      if (note) out = { ...(out || {}), systemMessage: note };
+    }
   }
 
   if (out) process.stdout.write(JSON.stringify(out));

package/data/harnesses/apollo/rules/database.md

@@ -7,7 +7,7 @@ Naming and the fixed column vocabulary for relational schemas in **every** Nurix
 Three column roles are fixed across every table and every project:
 
 - **`id`** — the primary key, **always a UUID** (`TEXT PRIMARY KEY` on D1, `uuid` on Postgres), never a synthetic or natural key (❌ `type_page_button`, `human:default`). Runtime rows mint a UUIDv7; seed rows derive a deterministic UUIDv5 of the natural key so re-seeds stay stable. **Never** mix synthetic and UUID ids in one table. The single exemption is a log whose **composite key is its ordering** (`PRIMARY KEY (<entity>_id, sequence)`), declared at the table that uses it — everything else, logs included, takes a UUIDv7.
-- **`slug`** — the **stable key rows in another scope reference**: `UNIQUE`, lowercase `snake_case`. A slug means the same thing in every scope, so a slug reference survives a copy with no remapping (§ Copying rows between scopes). ❌ Never rename this role `handle`, `key`, `code`, or `name` in another project.
+- **`slug`** — the **stable key rows in another scope reference**: `UNIQUE`, lowercase `snake_case`. A slug means the same thing in every scope, so a slug reference survives a copy with no remapping — copying between scopes is the `schema-design` skill. ❌ Never rename this role `handle`, `key`, `code`, or `name` in another project.
 - **`label`** — the **human display name** — ❌ never `name`, `title`, or `display_name`.
 
 Reference columns name what they point at: `<entity>_id` for a UUID-PK reference (`user_id`, `app_id`), `<entity>_slug` for a slug reference (`source_slug`).
@@ -21,7 +21,7 @@ Reference columns name what they point at: `<entity>_id` for a UUID-PK reference
 ## Naming
 
 - **Tables** — `snake_case`, plural noun for what they hold (`users`, `apps`, `devices`).
-- **Junction (M:N) tables** — `<entityA>_<entityB>_map`, **always**, even when the join carries its own columns; singular stems, owning/anchor entity first (`app_user_map`, `app_device_map`). ❌ Never a "nice" noun (`members`, `installs`, `memberships`, `enrolments`) — the name must read as a join, and a reviewer should know both sides from it. The `_map` suffix is reserved for genuine M:N (§ A junction spells many-to-many).
+- **Junction (M:N) tables** — `<entityA>_<entityB>_map`, **always**, even when the join carries its own columns; singular stems, owning/anchor entity first (`app_user_map`, `app_device_map`). ❌ Never a "nice" noun (`members`, `installs`, `memberships`, `enrolments`) — the name must read as a join, and a reviewer should know both sides from it. The `_map` suffix is reserved for genuine M:N — the cardinality test that decides junction vs. column is the `schema-design` skill.
 - **Columns** — `snake_case`; booleans `is_*` / `has_*`; timestamps `created_at` / `updated_at`; foreign keys `<entity>_id`.
 - **Indexes** — `<table>_<col(s)>_idx`; unique `<table>_<col(s)>_unique`; a junction's composite unique reads `<table>_<colA>_<colB>_unique` (`app_user_map_app_user_unique`).
 - **Drizzle mirror** — the exported object is the camelCase table name (`app_user_map` → `appUserMap`); column props are the camelCase of the column (`created_at` → `createdAt`). The `sqliteTable("…")` string and every index name must match the DDL (`init.sql`) exactly — the schema-parity boundary.

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/apollo/skills/schema-design/SKILL.md

@@ -85,22 +85,6 @@ One entity that exists at several scopes is **one table with a nullable scope co
 - **Store the source's version at copy time** — `version` + `source_version` make "is an upgrade available" a comparison of two stored values, not a content diff.
 - **A copy is a row, never a live read.** Nothing at the child scope reads the parent's row at runtime; propagation happens only through an explicit re-copy, so a local edit is never silently overwritten.
 
-## Keys & the shared vocabulary
-
-Three column roles are fixed across every table and every project:
-
-- **`id`** — the primary key, **always a UUID** (`TEXT PRIMARY KEY` on D1, `uuid` on Postgres), never a synthetic or natural key (❌ `type_page_button`, `human:default`). Runtime rows mint a UUIDv7; seed rows derive a deterministic UUIDv5 of the natural key so re-seeds stay stable. **Never** mix synthetic and UUID ids in one table. The single exemption is a log whose **composite key is its ordering** (`PRIMARY KEY (<entity>_id, sequence)`), declared at the table that uses it — everything else, logs included, takes a UUIDv7.
-- **`slug`** — the **stable key rows in another scope reference**: `UNIQUE`, lowercase `snake_case`. A slug means the same thing in every scope, so a slug reference survives a copy with no remapping (§ Copying rows between scopes). ❌ Never rename this role `handle`, `key`, `code`, or `name` in another project.
-- **`label`** — the **human display name** — ❌ never `name`, `title`, or `display_name`.
-
-Reference columns name what they point at: `<entity>_id` for a UUID-PK reference (`user_id`, `app_id`), `<entity>_slug` for a slug reference (`source_slug`).
-
-- **Enforced, same scope** (the referenced row must exist) → a real `FOREIGN KEY (<x>_id) REFERENCES <table>(id)`.
-- **Cross-scope** (the reference must survive being copied) → `<x>_slug` as a plain column, **no** FK — an FK would bind the row to one scope's copy of the target, which is the remapping the slug exists to avoid.
-- **Drift-tolerant** (a controlled-vocabulary value that may fall off-list) → a plain value column, **no** FK, paired with an `is_*` boolean recording whether the value is in the canonical set.
-
-**Every inbound FK to a hub table declares a deliberate `ON DELETE`.** A hub (`users`, `devices`, anything several modules point at) collects edges from teams that never meet, and a single `NO ACTION` among them turns deleting the parent into a constraint error naming neither table. Decide per edge: the child dies with the row (`CASCADE`) or survives it (`SET NULL`, which needs a nullable column) — `NO ACTION` on a hub is a deferred outage, not a default.
-
 ## A junction spells many-to-many — nothing else
 
 **A `_map` table is the schema's notation for M:N. Using it for 1:M is a category error** — the junction's own uniqueness admits many parents per child, so the "one parent" rule stops being enforced the moment it is written this way. Cardinality decides between the only two shapes:
@@ -131,14 +115,6 @@ Reference columns name what they point at: `<entity>_id` for a UUID-PK reference
 - **`CASCADE` from the append-only side's own parent is still fine** — a cascade is a DELETE, so a `BEFORE UPDATE` trigger never sees it: an App's log dying with the App is legitimate, distinct from erasing a log to delete a person.
 - **State the exemption where it exists.** A catalog whose rows must not disappear under a referencing row (a service definition, a vocabulary) keeps `NO ACTION` deliberately — that guarantee is worth one line saying so.
 
-## Naming
-
-- **Tables** — `snake_case`, plural noun for what they hold (`users`, `apps`, `devices`).
-- **Junction (M:N) tables** — `<entityA>_<entityB>_map`, **always**, even when the join carries its own columns; singular stems, owning/anchor entity first (`app_user_map`, `app_device_map`). ❌ Never a "nice" noun (`members`, `installs`, `memberships`, `enrolments`) — the name must read as a join, and a reviewer should know both sides from it. The `_map` suffix is reserved for genuine M:N (§ A junction spells many-to-many).
-- **Columns** — `snake_case`; booleans `is_*` / `has_*`; timestamps `created_at` / `updated_at`; foreign keys `<entity>_id`.
-- **Indexes** — `<table>_<col(s)>_idx`; unique `<table>_<col(s)>_unique`; a junction's composite unique reads `<table>_<colA>_<colB>_unique` (`app_user_map_app_user_unique`).
-- **Drizzle mirror** — the exported object is the camelCase table name (`app_user_map` → `appUserMap`); column props are the camelCase of the column (`created_at` → `createdAt`). The `sqliteTable("…")` string and every index name must match the DDL (`init.sql`) exactly — the schema-parity boundary.
-
 ## Uniqueness with a nullable column
 
 **`UNIQUE (a, b)` does not constrain rows where `b` is `NULL`** — SQL treats every `NULL` as distinct, so a composite unique over a nullable discriminator silently permits exactly the duplicates it was introduced to keep apart. Write one partial index per scope instead:
@@ -150,12 +126,6 @@ CREATE UNIQUE INDEX <t>_child_slug_unique  ON <t> (child_id, slug)  WHERE child_
 
 **Prove a uniqueness claim by inserting the duplicate it forbids** — a schema review cannot tell a firing index from a silent one by reading.
 
-## Column types (SQLite / D1)
-
-- **Timestamps** — `created_at` + `updated_at`, both `TEXT NOT NULL DEFAULT (datetime('now'))`, on **every** table — except append-only logs, which carry only `created_at`.
-- **Booleans** — `INTEGER` (Drizzle `integer(…, { mode: "boolean" })`); the `is_*` / `has_*` names are § Naming.
-- **JSON** — `TEXT` (Drizzle `text(…, { mode: "json" })`).
-
 ## Vocabulary / lookup tables
 
 A controlled vocabulary earns a **table** only when a user row FKs into it and reads its `label` / `description` at runtime — a service catalog rendered in a picker; static dev-authored config nobody references by FK stays **config** (§ What earns a table) — a `doc_type` value list. Enumerable is not tabular, and a `type`-style column validated against the constants file beats an FK to a seeded mirror. An earned table has a fixed shape: `id` (UUID) · `slug` (UNIQUE) · `label` · optional `description` · `status` · timestamps.

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

@@ -2,7 +2,7 @@
 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".
 tools: Read, Glob, Grep, Edit, Write, Bash, Skill
-model: inherit
+model: sonnet
 ---
 
 # Bookkeeper Agent

package/data/harnesses/code/agents/change-review.md

@@ -2,7 +2,7 @@
 name: change-review
 description: Velocity + change-risk analysis. First classifies recent commits into a pipe-delimited velocity/severity CSV by dispatching parallel low-cost subagents (module, feature, impact, severity, churn), then derives a commit heatmap, risk zones (high churn in contract-heavy code), stabilization signals, and team/bus-factor distribution. Self-contained — produces its own CSV, no separate git-history step. Use when planning where to invest in review focus or rules.
 tools: Bash, Read, Write, Glob, Grep, Task
-model: inherit
+model: sonnet
 ---
 
 # Change-Review Agent

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

@@ -2,7 +2,7 @@
 name: lld-mode
 description: LLD researcher for Feature and Product workflows. Use to explore the codebase and gather the context needed for writing a feature LLD (low-level design — the feature doc in docs/features/). Returns research findings — does not write files.
 tools: Read, Glob, Grep, WebSearch, WebFetch
-model: inherit
+model: opus
 skills:
   - documentation
 ---
@@ -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/agents/maintenance.md

@@ -2,7 +2,7 @@
 name: maintenance
 description: The single docs steward. Default behavior is the docs-vs-code coherence audit — detects and fixes docs drifting from code (stale docs, broken ownership, unowned source paths, architecture/backlog drift). An additive **baseline mode** layers structural reconcile on top: when the repo's `harness-version` marker is missing or behind, it converges `docs/` to the installed harness shape (scaffold the standard tree, fold dissolved-shape artifacts forward, stamp the version, propose modules) before running the audit. Mode is auto-selected from the marker. Run weekly, after major changes, or to baseline/upgrade a repo. Cross-cutting contract analysis is the `boundary` skill (`check` for plans, `scan` for diffs) — it derives contracts dynamically from source; there are no persisted boundary docs to audit. Triggers on "run maintenance", "docs health", "baseline this repo", "reconcile the harness", "upgrade the harness", "is this repo on the current harness", "/maintenance".
 tools: Read, Glob, Grep, Edit, Write, Bash
-model: inherit
+model: opus
 ---
 
 # Maintenance Agent

package/data/harnesses/code/agents/performance-review.md

@@ -2,7 +2,7 @@
 name: performance-review
 description: Combined dependency + code health audit. Part A audits the dependency supply chain — security CVEs, outdated packages, license compliance, abandoned packages, unwanted transitive dependencies, install size. Part B audits code-level health — bundle size, tree-shaking issues, performance anti-patterns, code-quality flags. Run weekly or before releases. Merges the former `dep-health` and `review` agents so the package tree and the code that uses it are audited together.
 tools: Read, Glob, Grep, Bash
-model: inherit
+model: opus
 ---
 
 # Performance-Review Agent

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

@@ -2,7 +2,7 @@
 name: retro
 description: Session-distillation agent for the changelog. Reads the per-unit-of-work entries under `docs/history/changelog/` accumulated since its last run and distills the refinement delta — what user-driven iteration added that the one-shot build lacked — into a typed punch list of doc-content gaps, doc-structure moves (missing doc / mothership split / merge), skill-evolution findings backed by survived-vs-overridden counts, unpinned discoveries needing an enforced artifact (test, token, guardrail, schema), and cross-project harness rules. Proposes only — actionable items land in the backlog, never applied directly. Run on demand: before a brainstorm or LLD session, before starting a new project, or after a refinement arc. Triggers on "run retro", "distill the changelog", "refinement retro", "/retro".
 tools: Read, Glob, Grep, Bash, Write, Edit
-model: inherit
+model: opus
 ---
 
 # Retro — changelog distillation

package/data/harnesses/code/harness.json

@@ -1,7 +1,7 @@
 {
   "harness": "code",
   "name": "code",
-  "version": "3.6.5",
+  "version": "3.7.1",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
@@ -10,5 +10,5 @@
   "seeds": [
     ".mcp.json"
   ],
-  "digest": "a3c50783b9c0"
+  "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
@@ -325,6 +341,43 @@ function planHasChangelogEntry(projectDir, planRel) {
   return names.some((name) => name.endsWith(".md") && readSafe(path.join(dir, name)).includes(slug));
 }
 
+// Approximate the context the next turn will re-read, from the transcript's last recorded usage.
+// Best-effort: an absent or unparseable transcript reports nothing.
+function sessionContextTokens(transcriptPath) {
+  const text = readSafe(transcriptPath || "");
+  if (!text) return 0;
+  const lines = text.slice(-400000).split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (!lines[i].includes('"usage"')) continue;
+    try {
+      const u = JSON.parse(lines[i]).message.usage;
+      return (
+        (u.input_tokens || 0) + (u.cache_read_input_tokens || 0) + (u.cache_creation_input_tokens || 0)
+      );
+    } catch (e) {
+      // the slice cut this line in half — keep scanning upward
+    }
+  }
+  return 0;
+}
+
+// Context re-reads in full on every turn, so its size IS the standing per-turn floor — the one
+// number that argues for ending a session rather than carrying it into unrelated work. The agent
+// cannot act on this (it can neither end a session nor start one), so it is addressed to the user
+// as a systemMessage and never blocks. Kept out of the model's context deliberately: a running
+// token count in-context produces context anxiety, not shorter sessions.
+const CONTEXT_ADVISORY_TOKENS = 250000;
+
+function sessionSizeNote(payload) {
+  const tokens = sessionContextTokens(payload.transcript_path);
+  if (tokens < CONTEXT_ADVISORY_TOKENS) return null;
+  return (
+    `Session context is roughly ${Math.round(tokens / 1000)}K tokens, and every turn re-reads all of it — ` +
+    "that is the per-turn floor before anything new is produced. A fresh session starts near zero; " +
+    "worth ending this one if the next task is unrelated."
+  );
+}
+
 function stopGate(projectDir, payload) {
   if (payload.stop_hook_active) return null; // the runtime's infinite-loop guard — never re-block
 
@@ -344,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",
@@ -381,6 +444,11 @@ function main() {
     }
   } else if (event === "Stop") {
     out = stopGate(projectDir, payload);
+    // Advisory rides alongside a block rather than replacing it — both are true at once.
+    if (!payload.stop_hook_active) {
+      const note = sessionSizeNote(payload);
+      if (note) out = { ...(out || {}), systemMessage: note };
+    }
   }
 
   if (out) process.stdout.write(JSON.stringify(out));

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

@@ -7,7 +7,7 @@ Naming and the fixed column vocabulary for relational schemas in **every** Nurix
 Three column roles are fixed across every table and every project:
 
 - **`id`** — the primary key, **always a UUID** (`TEXT PRIMARY KEY` on D1, `uuid` on Postgres), never a synthetic or natural key (❌ `type_page_button`, `human:default`). Runtime rows mint a UUIDv7; seed rows derive a deterministic UUIDv5 of the natural key so re-seeds stay stable. **Never** mix synthetic and UUID ids in one table. The single exemption is a log whose **composite key is its ordering** (`PRIMARY KEY (<entity>_id, sequence)`), declared at the table that uses it — everything else, logs included, takes a UUIDv7.
-- **`slug`** — the **stable key rows in another scope reference**: `UNIQUE`, lowercase `snake_case`. A slug means the same thing in every scope, so a slug reference survives a copy with no remapping (§ Copying rows between scopes). ❌ Never rename this role `handle`, `key`, `code`, or `name` in another project.
+- **`slug`** — the **stable key rows in another scope reference**: `UNIQUE`, lowercase `snake_case`. A slug means the same thing in every scope, so a slug reference survives a copy with no remapping — copying between scopes is the `schema-design` skill. ❌ Never rename this role `handle`, `key`, `code`, or `name` in another project.
 - **`label`** — the **human display name** — ❌ never `name`, `title`, or `display_name`.
 
 Reference columns name what they point at: `<entity>_id` for a UUID-PK reference (`user_id`, `app_id`), `<entity>_slug` for a slug reference (`source_slug`).
@@ -21,7 +21,7 @@ Reference columns name what they point at: `<entity>_id` for a UUID-PK reference
 ## Naming
 
 - **Tables** — `snake_case`, plural noun for what they hold (`users`, `apps`, `devices`).
-- **Junction (M:N) tables** — `<entityA>_<entityB>_map`, **always**, even when the join carries its own columns; singular stems, owning/anchor entity first (`app_user_map`, `app_device_map`). ❌ Never a "nice" noun (`members`, `installs`, `memberships`, `enrolments`) — the name must read as a join, and a reviewer should know both sides from it. The `_map` suffix is reserved for genuine M:N (§ A junction spells many-to-many).
+- **Junction (M:N) tables** — `<entityA>_<entityB>_map`, **always**, even when the join carries its own columns; singular stems, owning/anchor entity first (`app_user_map`, `app_device_map`). ❌ Never a "nice" noun (`members`, `installs`, `memberships`, `enrolments`) — the name must read as a join, and a reviewer should know both sides from it. The `_map` suffix is reserved for genuine M:N — the cardinality test that decides junction vs. column is the `schema-design` skill.
 - **Columns** — `snake_case`; booleans `is_*` / `has_*`; timestamps `created_at` / `updated_at`; foreign keys `<entity>_id`.
 - **Indexes** — `<table>_<col(s)>_idx`; unique `<table>_<col(s)>_unique`; a junction's composite unique reads `<table>_<colA>_<colB>_unique` (`app_user_map_app_user_unique`).
 - **Drizzle mirror** — the exported object is the camelCase table name (`app_user_map` → `appUserMap`); column props are the camelCase of the column (`created_at` → `createdAt`). The `sqliteTable("…")` string and every index name must match the DDL (`init.sql`) exactly — the schema-parity boundary.

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/code/skills/schema-design/SKILL.md

@@ -85,22 +85,6 @@ One entity that exists at several scopes is **one table with a nullable scope co
 - **Store the source's version at copy time** — `version` + `source_version` make "is an upgrade available" a comparison of two stored values, not a content diff.
 - **A copy is a row, never a live read.** Nothing at the child scope reads the parent's row at runtime; propagation happens only through an explicit re-copy, so a local edit is never silently overwritten.
 
-## Keys & the shared vocabulary
-
-Three column roles are fixed across every table and every project:
-
-- **`id`** — the primary key, **always a UUID** (`TEXT PRIMARY KEY` on D1, `uuid` on Postgres), never a synthetic or natural key (❌ `type_page_button`, `human:default`). Runtime rows mint a UUIDv7; seed rows derive a deterministic UUIDv5 of the natural key so re-seeds stay stable. **Never** mix synthetic and UUID ids in one table. The single exemption is a log whose **composite key is its ordering** (`PRIMARY KEY (<entity>_id, sequence)`), declared at the table that uses it — everything else, logs included, takes a UUIDv7.
-- **`slug`** — the **stable key rows in another scope reference**: `UNIQUE`, lowercase `snake_case`. A slug means the same thing in every scope, so a slug reference survives a copy with no remapping (§ Copying rows between scopes). ❌ Never rename this role `handle`, `key`, `code`, or `name` in another project.
-- **`label`** — the **human display name** — ❌ never `name`, `title`, or `display_name`.
-
-Reference columns name what they point at: `<entity>_id` for a UUID-PK reference (`user_id`, `app_id`), `<entity>_slug` for a slug reference (`source_slug`).
-
-- **Enforced, same scope** (the referenced row must exist) → a real `FOREIGN KEY (<x>_id) REFERENCES <table>(id)`.
-- **Cross-scope** (the reference must survive being copied) → `<x>_slug` as a plain column, **no** FK — an FK would bind the row to one scope's copy of the target, which is the remapping the slug exists to avoid.
-- **Drift-tolerant** (a controlled-vocabulary value that may fall off-list) → a plain value column, **no** FK, paired with an `is_*` boolean recording whether the value is in the canonical set.
-
-**Every inbound FK to a hub table declares a deliberate `ON DELETE`.** A hub (`users`, `devices`, anything several modules point at) collects edges from teams that never meet, and a single `NO ACTION` among them turns deleting the parent into a constraint error naming neither table. Decide per edge: the child dies with the row (`CASCADE`) or survives it (`SET NULL`, which needs a nullable column) — `NO ACTION` on a hub is a deferred outage, not a default.
-
 ## A junction spells many-to-many — nothing else
 
 **A `_map` table is the schema's notation for M:N. Using it for 1:M is a category error** — the junction's own uniqueness admits many parents per child, so the "one parent" rule stops being enforced the moment it is written this way. Cardinality decides between the only two shapes:
@@ -131,14 +115,6 @@ Reference columns name what they point at: `<entity>_id` for a UUID-PK reference
 - **`CASCADE` from the append-only side's own parent is still fine** — a cascade is a DELETE, so a `BEFORE UPDATE` trigger never sees it: an App's log dying with the App is legitimate, distinct from erasing a log to delete a person.
 - **State the exemption where it exists.** A catalog whose rows must not disappear under a referencing row (a service definition, a vocabulary) keeps `NO ACTION` deliberately — that guarantee is worth one line saying so.
 
-## Naming
-
-- **Tables** — `snake_case`, plural noun for what they hold (`users`, `apps`, `devices`).
-- **Junction (M:N) tables** — `<entityA>_<entityB>_map`, **always**, even when the join carries its own columns; singular stems, owning/anchor entity first (`app_user_map`, `app_device_map`). ❌ Never a "nice" noun (`members`, `installs`, `memberships`, `enrolments`) — the name must read as a join, and a reviewer should know both sides from it. The `_map` suffix is reserved for genuine M:N (§ A junction spells many-to-many).
-- **Columns** — `snake_case`; booleans `is_*` / `has_*`; timestamps `created_at` / `updated_at`; foreign keys `<entity>_id`.
-- **Indexes** — `<table>_<col(s)>_idx`; unique `<table>_<col(s)>_unique`; a junction's composite unique reads `<table>_<colA>_<colB>_unique` (`app_user_map_app_user_unique`).
-- **Drizzle mirror** — the exported object is the camelCase table name (`app_user_map` → `appUserMap`); column props are the camelCase of the column (`created_at` → `createdAt`). The `sqliteTable("…")` string and every index name must match the DDL (`init.sql`) exactly — the schema-parity boundary.
-
 ## Uniqueness with a nullable column
 
 **`UNIQUE (a, b)` does not constrain rows where `b` is `NULL`** — SQL treats every `NULL` as distinct, so a composite unique over a nullable discriminator silently permits exactly the duplicates it was introduced to keep apart. Write one partial index per scope instead:
@@ -150,12 +126,6 @@ CREATE UNIQUE INDEX <t>_child_slug_unique  ON <t> (child_id, slug)  WHERE child_
 
 **Prove a uniqueness claim by inserting the duplicate it forbids** — a schema review cannot tell a firing index from a silent one by reading.
 
-## Column types (SQLite / D1)
-
-- **Timestamps** — `created_at` + `updated_at`, both `TEXT NOT NULL DEFAULT (datetime('now'))`, on **every** table — except append-only logs, which carry only `created_at`.
-- **Booleans** — `INTEGER` (Drizzle `integer(…, { mode: "boolean" })`); the `is_*` / `has_*` names are § Naming.
-- **JSON** — `TEXT` (Drizzle `text(…, { mode: "json" })`).
-
 ## Vocabulary / lookup tables
 
 A controlled vocabulary earns a **table** only when a user row FKs into it and reads its `label` / `description` at runtime — a service catalog rendered in a picker; static dev-authored config nobody references by FK stays **config** (§ What earns a table) — a `doc_type` value list. Enumerable is not tabular, and a `type`-style column validated against the constants file beats an FK to a seeded mirror. An earned table has a fixed shape: `id` (UUID) · `slug` (UNIQUE) · `label` · optional `description` · `status` · timestamps.

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

@@ -2,7 +2,7 @@
 name: lld-mode
 description: LLD researcher for Feature and Product workflows. Use to explore the codebase and gather the context needed for writing a feature LLD (low-level design — the feature doc in docs/features/). Returns research findings — does not write files.
 tools: Read, Glob, Grep, WebSearch, WebFetch
-model: inherit
+model: opus
 skills:
   - documentation
 ---
@@ -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/agents/maintenance.md

@@ -2,7 +2,7 @@
 name: maintenance
 description: The single docs steward. Default behavior is the docs-vs-code coherence audit — detects and fixes docs drifting from code (stale docs, broken ownership, unowned source paths, architecture/backlog drift). An additive **baseline mode** layers structural reconcile on top: when the repo's `harness-version` marker is missing or behind, it converges `docs/` to the installed harness shape (scaffold the standard tree, fold dissolved-shape artifacts forward, stamp the version, propose modules) before running the audit. Mode is auto-selected from the marker. Run weekly, after major changes, or to baseline/upgrade a repo. Cross-cutting contract analysis is the `boundary` skill (`check` for plans, `scan` for diffs) — it derives contracts dynamically from source; there are no persisted boundary docs to audit. Triggers on "run maintenance", "docs health", "baseline this repo", "reconcile the harness", "upgrade the harness", "is this repo on the current harness", "/maintenance".
 tools: Read, Glob, Grep, Edit, Write, Bash
-model: inherit
+model: opus
 ---
 
 # Maintenance Agent

package/data/harnesses/delivery/agents/retro.md

@@ -2,7 +2,7 @@
 name: retro
 description: Session-distillation agent for the changelog. Reads the per-unit-of-work entries under `docs/history/changelog/` accumulated since its last run and distills the refinement delta — what user-driven iteration added that the one-shot build lacked — into a typed punch list of doc-content gaps, doc-structure moves (missing doc / mothership split / merge), skill-evolution findings backed by survived-vs-overridden counts, unpinned discoveries needing an enforced artifact (test, token, guardrail, schema), and cross-project harness rules. Proposes only — actionable items land in the backlog, never applied directly. Run on demand: before a brainstorm or LLD session, before starting a new project, or after a refinement arc. Triggers on "run retro", "distill the changelog", "refinement retro", "/retro".
 tools: Read, Glob, Grep, Bash, Write, Edit
-model: inherit
+model: opus
 ---
 
 # Retro — changelog distillation

package/data/harnesses/delivery/harness.json

@@ -1,12 +1,12 @@
 {
   "harness": "delivery",
   "name": "delivery",
-  "version": "0.1.6",
+  "version": "0.2.1",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
   "seeds": [],
-  "digest": "0480314707cd"
+  "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/change-review.md

@@ -2,7 +2,7 @@
 name: change-review
 description: Velocity + change-risk analysis. First classifies recent commits into a pipe-delimited velocity/severity CSV by dispatching parallel low-cost subagents (module, feature, impact, severity, churn), then derives a commit heatmap, risk zones (high churn in contract-heavy code), stabilization signals, and team/bus-factor distribution. Self-contained — produces its own CSV, no separate git-history step. Use when planning where to invest in review focus or rules.
 tools: Bash, Read, Write, Glob, Grep, Task
-model: inherit
+model: sonnet
 ---
 
 # Change-Review Agent

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

@@ -2,7 +2,7 @@
 name: lld-mode
 description: LLD researcher for Feature and Product workflows. Use to explore the codebase and gather the context needed for writing a feature LLD (low-level design — the feature doc in docs/features/). Returns research findings — does not write files.
 tools: Read, Glob, Grep, WebSearch, WebFetch
-model: inherit
+model: opus
 skills:
   - documentation
 ---
@@ -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/agents/maintenance.md

@@ -2,7 +2,7 @@
 name: maintenance
 description: The single docs steward. Default behavior is the docs-vs-code coherence audit — detects and fixes docs drifting from code (stale docs, broken ownership, unowned source paths, architecture/backlog drift). An additive **baseline mode** layers structural reconcile on top: when the repo's `harness-version` marker is missing or behind, it converges `docs/` to the installed harness shape (scaffold the standard tree, fold dissolved-shape artifacts forward, stamp the version, propose modules) before running the audit. Mode is auto-selected from the marker. Run weekly, after major changes, or to baseline/upgrade a repo. Cross-cutting contract analysis is the `boundary` skill (`check` for plans, `scan` for diffs) — it derives contracts dynamically from source; there are no persisted boundary docs to audit. Triggers on "run maintenance", "docs health", "baseline this repo", "reconcile the harness", "upgrade the harness", "is this repo on the current harness", "/maintenance".
 tools: Read, Glob, Grep, Edit, Write, Bash
-model: inherit
+model: opus
 ---
 
 # Maintenance Agent

package/data/harnesses/etna/agents/performance-review.md

@@ -2,7 +2,7 @@
 name: performance-review
 description: Combined dependency + code health audit. Part A audits the dependency supply chain — security CVEs, outdated packages, license compliance, abandoned packages, unwanted transitive dependencies, install size. Part B audits code-level health — bundle size, tree-shaking issues, performance anti-patterns, code-quality flags. Run weekly or before releases. Merges the former `dep-health` and `review` agents so the package tree and the code that uses it are audited together.
 tools: Read, Glob, Grep, Bash
-model: inherit
+model: opus
 ---
 
 # Performance-Review Agent

package/data/harnesses/etna/agents/retro.md

@@ -2,7 +2,7 @@
 name: retro
 description: Session-distillation agent for the changelog. Reads the per-unit-of-work entries under `docs/history/changelog/` accumulated since its last run and distills the refinement delta — what user-driven iteration added that the one-shot build lacked — into a typed punch list of doc-content gaps, doc-structure moves (missing doc / mothership split / merge), skill-evolution findings backed by survived-vs-overridden counts, unpinned discoveries needing an enforced artifact (test, token, guardrail, schema), and cross-project harness rules. Proposes only — actionable items land in the backlog, never applied directly. Run on demand: before a brainstorm or LLD session, before starting a new project, or after a refinement arc. Triggers on "run retro", "distill the changelog", "refinement retro", "/retro".
 tools: Read, Glob, Grep, Bash, Write, Edit
-model: inherit
+model: opus
 ---
 
 # Retro — changelog distillation

package/data/harnesses/etna/harness.json

@@ -1,12 +1,12 @@
 {
   "harness": "etna",
   "name": "etna",
-  "version": "1.3.9",
+  "version": "1.4.1",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
   "seeds": [],
-  "digest": "96095ea9c98e"
+  "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.56",
+    "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": "e7493c40d358"
+    "etnaFingerprint": "411f905588e3"
 }