@nurix/etna 0.19.20 → 0.19.21

package/data/harness-index.json

@@ -1,5 +1,5 @@
 {
-    "fingerprint": "2e71b9321651",
+    "fingerprint": "2329fc4f3594",
     "harnesses": {
         "code": {
             "plugin": "code",

package/data/harnesses/code/.prettierignore

@@ -10,3 +10,9 @@ yarn.lock
 
 # Harness-managed agent/skill definitions (installed under .claude/)
 .claude
+
+# Source catalogs — authored markdown; prettier collapses template/example blocks
+skills
+rules
+agents
+harness

package/data/harnesses/code/CLAUDE.md

@@ -1,12 +1,12 @@
 # Agent Instructions
 
-This file defines how AI coding agents — any vendor, any runtime — should work on this project. Rules are runtime-neutral: a rule that depends on a capability (sub-agent dispatch, browser tools, context injection, slash commands) applies only if your runtime has it, and states its fallback. Rules marked **[override]** deliberately replace a default your runtime may have built in — in a conflict, the rule here wins.
+This file defines how AI coding agents — any vendor, any runtime — should work on this project. Rules are runtime-neutral: a rule that depends on a capability (sub-agent dispatch, browser tools, context injection, slash commands) applies only if the runtime has it, and states its fallback. Rules marked **[override]** deliberately replace a default the runtime may have built in — in a conflict, the rule here wins.
 
 ---
 
 ## Maintenance
 
-Invoke the `maintenance` agent whenever you judge the docs need it — not just at first setup: a missing `docs/structure.md` (the repo isn't reconciled — baseline before applying anything below), a `harness-version` marker behind the installed version, docs contradicting code, unowned source paths, or drift you notice while working. Never reconcile these by hand — the agent auto-selects its mode (baseline when the marker is missing or behind, coherence audit otherwise) and hands back; if it returns a follow-up (typically the module proposal), re-invoke it to finish. Each component's internals live in the component, not here.
+Invoke the `maintenance` agent whenever the docs look like they need it — not just at first setup: a missing `docs/structure.md` (the repo isn't reconciled — baseline before applying anything below), a `harness-version` marker behind the installed version, docs contradicting code, unowned source paths, or drift noticed while working. Never reconcile these by hand — the agent auto-selects its mode (baseline when the marker is missing or behind, coherence audit otherwise) and hands back; if it returns a follow-up (typically the module proposal), re-invoke it to finish. Each component's internals live in the component, not here.
 
 ---
 
@@ -43,30 +43,31 @@ Three peer modes plus a Completion step — enter wherever the user's thinking a
 
 ## Ownership, Boundaries & Documentation
 
-These three mechanisms work in tandem to keep the repo self-updating and to prevent half-finished changes: **ownership** routes you to the canonical doc before you touch code, the **boundary** check reads both sides of every contract your change participates in so you can't ship one side of it, and **documentation** updates close the loop so the next session inherits the truth. Skipping any leg breaks the other two.
+These three mechanisms work in tandem to keep the repo self-updating and to prevent half-finished changes: **ownership** routes an edit to the canonical doc before the code is touched, the **boundary** check reads both sides of every contract a change participates in so one side never ships alone, and **documentation** updates close the loop so the next session inherits the truth. Skipping any leg breaks the other two.
 
-### Ownership — route before you edit
+### Ownership — route before editing
 
 Which doc is canonical for which code paths is the **feature doc's own frontmatter**. A feature doc (flat in `docs/features/`) carries `owns:` (code-path globs — the only ownership key), `module:` (a bounded-context label, omitted when cross-cutting), `keywords:` (discovery), and `status:`. Code → doc ownership is the union of every feature doc's `owns:` globs, surfaced as the generated ownership index at session start. A module is tied to code by the `owns:` globs of the docs carrying its `module:` label — not a folder, not a separate map. Architecture docs describe cross-cutting patterns and don't own specific files; operations docs describe procedures.
 
 Before modifying code in an unfamiliar area:
 
-1. Consult the **injected ownership index** (`glob → doc · module · keywords · status`). Match your path or topic to the owning feature doc and read it before changes. (No index in context ⇒ either the repo isn't reconciled — see Maintenance — or your runtime doesn't inject it — see Runtime Notes.)
-2. If a `docs/memory/` file exists for the domain you're working in, read it for domain knowledge and failure modes.
+1. Consult the **injected ownership index** (`glob → doc · module · keywords · status`). Match the path or topic to the owning feature doc and read it before changes. (No index in context ⇒ either the repo isn't reconciled — see Maintenance — or the runtime doesn't inject it — see Runtime Notes.)
+2. If a `docs/memory/` file exists for the domain, read it for domain knowledge and failure modes.
 
 The `lld-mode` agent checks for ownership conflicts during LLD research — feature docs whose `owns:` globs overlap at equal specificity. If conflicts are found, address them in the LLD before proceeding.
 
-### Boundaries — check while you change
+### Boundaries — check while changing
 
-A boundary is a contract between two pieces of code (or code and infra) that share an assumption with **no static link** between them — the column a raw SQL string names, the env var a deploy script reads. Changing one side ships green — compiles, lints, tests pass — and breaks the other at runtime. Boundaries are **diagnosed, not documented**: the `boundary` skill reads them fresh from source on every run, so nothing is persisted that could go stale.
+Boundaries are **diagnosed, not documented** — the `boundary` skill derives them fresh from source on every run (the definition and mechanism catalog live in the skill), so nothing is persisted that could go stale.
 
 **Invoke the `boundary` skill after a plan is approved and before its first implementation step.** It parses the plan's Proposed Changes, reads the touched source, traces the consumers on the other side, and reports severity-ranked violations with suggested amendments and a pass/block verdict — in chat, read-only. Fold the amendments into the plan before coding. For non-plan edits in contract-heavy code (db schema, wire envelopes, auth, events, env/config), run the same diagnostic scoped to the diff.
 
 ### Documentation — close the loop
 
-- **[override]** Keep `docs/` updated when code changes affect documented behavior. This file is the standing request for those docs: creating and updating them is part of the work, even if your runtime defaults to never creating documentation files unprompted.
+- **Every markdown document goes through the `documentation` skill.** Before creating or substantively editing any `.md` document — a doc, a README, an index, a record — invoke the `documentation` skill and apply its templates and `references/style-guide.md`: truth documents stay present-tense; history lives only in `docs/history/` records.
+- **[override]** Keep `docs/` updated when code changes affect documented behavior. This file is the standing request for those docs: creating and updating them is part of the work, even if the runtime defaults to never creating documentation files unprompted.
 - After plan completion **[override]**: add a `docs/history/changelog/` entry + update `docs/history/CHANGELOG.md` — no confirmation needed. Include `Commits:` if multi-commit. Non-plan changes (refactors, fixes, API changes): prompt first.
-- When you move or rename source files: update the `owns:` globs of the feature doc that owns them so the generated ownership index stays accurate. A new doc that owns code declares its paths in its own `owns:` frontmatter — there is no separate map to update.
+- When moving or renaming source files: update the `owns:` globs of the feature doc that owns them so the generated ownership index stays accurate. A new doc that owns code declares its paths in its own `owns:` frontmatter — there is no separate map to update.
 - `docs/structure.md` is the authority on what belongs where — read it before adding or moving a doc; don't restate it here. One canonical source per topic — link, don't copy. Only `CLAUDE.md`, `AGENTS.md`, and `README.md` live at the repo root.
 
 > Agents and skills live under `.claude/agents/` and `.claude/skills/`. Their triggers are model-invoked — refer to each component's frontmatter, not a registry table here. Runtimes that can't invoke them natively: see Runtime Notes.
@@ -89,11 +90,11 @@ When recording a learning, ask: _is this true of this project, or true of this u
 
 ## Out-of-Scope Discovery
 
-When implementing a plan, if you discover work that is important but outside the current plan's scope:
+When a plan's implementation surfaces work that is important but outside the plan's scope:
 
 - Append it to `docs/history/backlog.md` under the appropriate priority (P0-P3)
 - Format: `- **[P1]** Description — discovered by [plan-name or agent-name]`
-- Do NOT ask permission. Just append and mention it in your response.
+- Do NOT ask permission. Just append and mention it in the reply.
 
 ---
 
@@ -103,13 +104,13 @@ Defaults — ❌ prohibitions hold unless the user explicitly asks otherwise;
 
 - ✅ **Tests — suite-first.** Tests ship with every change to product code or behavior, built as one maintained suite, never as one-off scripts. Framework choice, test-tree placement, and shared fixtures/helpers are `.claude/rules/testing.md` — the repo's existing runner and layout always win.
   - **What gets tests**: a new feature ships with tests for the behavior its LLD promises; a bug fix ships with a regression test that fails before the fix and passes after.
-  - **Discipline**: run the affected part of the suite before declaring work complete and report results honestly. When an LLD or plan intentionally changes behavior, updating the affected tests to the new contract is part of the change — the ban is on weakening, skipping, or deleting a test to mask a failure you can't explain.
+  - **Discipline**: run the affected part of the suite before declaring work complete and report results honestly. When an LLD or plan intentionally changes behavior, updating the affected tests to the new contract is part of the change — the ban is on weakening, skipping, or deleting a test to mask an unexplained failure.
   - **Throwaway checks are not tests**: temporary verification scripts go to scratch space and are deleted, never committed into the test tree.
 - ❌ **Dependencies** – Never upgrade frameworks, libraries, or dependencies.
 - ❌ **Compatibility** – Never maintain backward compatibility unless specified.
 - ❌ **Branches & Worktrees [override]** – Never self-create git branches or worktrees; commit straight to the checked-out branch. This replaces any built-in "branch first on the default branch" default. Exception: when the user asks for a pull request, create the branch the PR requires before committing its changes.
 - ❌ **Protected Files** – Before editing, if `docs/operations/protected-files.md` exists, read it and never modify any path it lists; also never modify `AGENTS.md` or the `protected-files.md` file itself.
-- ✅ **Browser Automation** – If your runtime provides browser automation, use it freely; no need to ask first. If it doesn't — or you are an agent that can't hold the browser connection (see Runtime Notes) — return a browser-verification checklist (URLs, actions, expected outcomes) for the orchestrating session or the user to run.
+- ✅ **Browser Automation** – If the runtime provides browser automation, use it freely; no need to ask first. If it doesn't — or the executing agent can't hold the browser connection (see Runtime Notes) — return a browser-verification checklist (URLs, actions, expected outcomes) for the orchestrating session or the user to run.
 - ✅ **Fan-out is a tool, not a default** — the main session does the work and its own reasoning; a delegated result comes back as a summary, not verifiable ground truth. Delegate **only when** the work is large, independent, or repetitive enough that a self-contained hand-off (the sub-agent sees none of the conversation) costs less than the work — broad research, wide sweeps, audits — and run independent delegations in parallel. **Never delegate judgment by reflex**: a second opinion is for a high-stakes call or an explicit request. No dispatch mechanism ⇒ inline.
 - ⚠️ **Plans** – Plans are created directly in `docs/history/plans/` (see Workflows). Once `Status: Complete` or `Status: Abandoned`, the file is frozen — never edited. If scope changes after completion, write a new dated plan that links back to the old one.
 - ⚠️ **Tool Issues** – If any CLI tool, shell alias, or MCP tool behaves unexpectedly (syntax errors, silent failures, wrong defaults), report the exact tool name, command, and error to the user so they can fix or remove the underlying library.

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

@@ -180,7 +180,7 @@ On approval, execute: create the folder structure; move/fold/merge/delete per th
 
 Scaffold missing mandated files **by calling the `documentation` skill for each template** — you orchestrate, the skill supplies templates:
 
-- `docs/structure.md` (with `harness-version`), `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/index.md`, `docs/memory/main.md`, and the repo-root `README.md` (filled from the real lockfile/scripts/layout — **never overwrite an existing root README**).
+- `docs/structure.md` (with `harness-version`), `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/main.md`, and the repo-root `README.md` (filled from the real lockfile/scripts/layout — **never overwrite an existing root README**).
 
 ### Step B4 — Stamp the version
 

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

@@ -177,7 +177,7 @@ On approval, execute: create the folder structure; move/fold/merge/delete per th
 
 Scaffold missing mandated files **by calling the `documentation` skill for each template** — you orchestrate, the skill supplies templates:
 
-- `docs/structure.md` (with `harness-version`), `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/index.md`, `docs/memory/main.md`, and the repo-root `README.md` (filled from the real lockfile/scripts/layout — **never overwrite an existing root README**).
+- `docs/structure.md` (with `harness-version`), `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/main.md`, and the repo-root `README.md` (filled from the real lockfile/scripts/layout — **never overwrite an existing root README**).
 
 ### Step B4 — Stamp the version
 

package/data/harnesses/code/harness.json

@@ -1,11 +1,11 @@
 {
   "harness": "code",
   "name": "code",
-  "version": "3.1.13",
+  "version": "3.1.14",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
-  "digest": "c1f024029b4d"
+  "digest": "6b9984997d77"
 }

package/data/harnesses/code/skills/documentation/SKILL.md

@@ -1,13 +1,30 @@
 ---
 name: documentation
-description: Template & generator library for technical docs — the skill agents call to produce a doc from a template. Use to (1) document a feature or module (the feature doc is the feature's LLD — low-level design — written in LLD Mode), (2) create or update a changelog entry, (3) document data flows or Redux state, (4) add to protected files, (5) record or revise an architecture decision (an AD), (6) create or update the project root README, (7) create or update a plan, (8) derive a feature doc's `owns:` frontmatter (the code-path globs it owns) from code, (9) scaffold a standard doc (README, structure.md, CHANGELOG, backlog, memory) from its template, (10) document an operations procedure (setup, deployment, maintenance) or a one-shot migration runbook, (11) write a steering doc (system overview, domain model, glossary, non-goals, security overview, testing strategy), (12) catalog the API surface or the environment/config registry, or (13) co-author any technical doc. Baselining / reconciling a repo's docs to the installed harness version is the **`maintenance` agent (baseline mode)** (which calls this skill for each template) — this skill does not orchestrate baseline. Triggers on "document this", "create docs", "update changelog", "add to protected files", "AD", "ADR", "architecture decision", "root README", "plan", "feature doc", "LLD", "glossary", "domain model", "runbook", "API reference".
+description: Invoke BEFORE creating or substantively editing ANY markdown doc. Templates + style authority for technical docs — LLDs, ADs, plans, changelogs, READMEs, runbooks. Owns the tense rule: truth docs state the present; history only in dated records. Baselining is the maintenance agent.
 ---
 
 # Technical Documentation Skill
 
 **This skill is a template & generator library, not an orchestrator.** It supplies the templates, the frontmatter-derivation generator, and the co-authoring workflow that _agents_ call to produce individual docs. It does **not** baseline, audit, or reconcile a repo's doc tree — that is the **`maintenance` agent (baseline mode)**, which calls this skill for each template it scaffolds. Reach here to generate _one_ doc from a template; reach for the `maintenance` agent (baseline mode) to bring a whole repo into shape.
 
-Document contracts and architecture, not implementation details. Show function signatures and API shapes — never paste full implementations (they rot fast). Use ASCII diagrams over prose for flows. Only document state at persistence boundaries (Redux persistence, DB schemas, API shapes), not component-level or transient state. Mark deprecated fields with `// UNUSED:` comments. Breaking changes belong in changelogs only, not module docs.
+Document contracts and architecture, not implementation details. Show function signatures and API shapes — never paste full implementations (they rot fast). Use ASCII diagrams over prose for flows. Only document state at persistence boundaries (Redux persistence, DB schemas, API shapes), not component-level or transient state. Mark deprecated fields with `// UNUSED:` comments stating why the field is dead now — never where it went or when it dies. Breaking changes belong in changelogs only, not module docs.
+
+---
+
+## Present tense, always
+
+**A document states what is — never how it got there, and never how far along it is.** Write as if the current design had always been the plan. This is the most-violated rule in the skill, so it sits at the top; it applies to every document written or edited through this skill, whatever the template.
+
+| ❌ Strip this | ✅ Write this |
+| --- | --- |
+| "Build Sequence phases 0–4 are complete." | Nothing — progress lives in the plan/backlog record |
+| "There is no standalone `skills/components/` — treat any reference to it as stale." | Nothing — fix the references; state only the present design |
+| "Folded in from the `NuStack-X` repo (2026-06-12)." | "Vendor-connector catalogue; one subpath per vendor." |
+| "was X, now Y", "the old worker", "Phase 2 softened this", "v1 → v2" | The current fact, with no predecessor named |
+
+The journey — dates, migrations, progress, supersessions — lives only in records (`docs/history/`); when reality changes, a truth document simply becomes correct. The full strip-list and the record-side rules: [`references/style-guide.md`](references/style-guide.md) § The Two Natures — Tense & History.
+
+The mechanical subset of these rules is checked by [`scripts/doc-lint.mjs`](scripts/doc-lint.mjs) — run it over changed docs before finishing. Block-severity findings must be fixed; `<!-- doc-lint-disable: <id> -->` with a reason beside it is the escape hatch.
 
 ---
 
@@ -25,10 +42,10 @@ Every document is exactly one of two things. Decide which before writing a word
 
 The two guarantees are complementary and both break on mixing: a reader holding a **truth document** must never need history to interpret it; a reader holding a **record** must be able to trust it was never rewritten. So the natures never share a document body.
 
-- **Truth documents never narrate history.** No migration/fold stories, no dated "shipped/verified on YYYY-MM-DD" markers, no "was X → now Y" journeys, no provenance asides ("ex-`@nurix/X`, folded 2026-06-12"). When the system changes, the change-story goes to `docs/history/` (a changelog entry) and the truth document simply becomes correct in present tense. When you find historical narration in a truth document, rewrite it to the present-tense fact and let the record carry the story.
+- **Truth documents never narrate history** — the § Present tense, always rule above, applied to this nature. When the system changes, the change-story goes to `docs/history/` (a changelog entry) and the truth document simply becomes correct in present tense. When you find historical narration in a truth document, rewrite it to the present-tense fact and let the record carry the story.
 - **Records are never edited to match the present.** A completed plan stays wrong-in-hindsight; a changelog entry describes close-time state; a scope change gets a *new* dated record that links back, never an edit to a frozen one.
-- **The one bridge — head is truth, tail is provenance.** An **Architecture Decision (AD)** ends with a **Decision Changelog**: the single sanctioned dated-history section inside a truth document, because for a decision the journey (what each revision reversed, and what triggered it) is part of the reasoning. The AD body stays current-truth-only; the tail carries the dates and links to the plans that implemented each revision. No other truth document carries dated history.
-- **Truth documents cite records for the _why_, never the _when_.** `Provenance: AD-002` is good; "decided in AD-002 and shipped 2026-06-13" is not. Routing/index docs point only to truth documents — never to a plan or changelog entry as the "read first" source.
+- **Two sanctioned bridges — head is truth, tail is provenance.** An **Architecture Decision (AD)** ends with a **Decision Changelog** (for a decision, the journey — what each revision reversed and what triggered it — is part of the reasoning), and `docs/structure.md` ends with the maintenance agent's **Health Log** (tooling-stamped audit rows, the structural cousin of `last-reviewed:`). In both, the body stays current-truth-only; the tail carries the dates. No other truth document carries dated history.
+- **Truth documents cite records for the _why_, never the _when_.** `Provenance: AD-002` is good; "decided in AD-002 and shipped 2026-06-13" is not. Routing/index docs point only to truth documents as a topic's authority — never a plan or changelog entry as the "read first" source. (An index _of the records themselves_ — a History section listing `plans/`, `changelog/` — is sanctioned.)
 
 **No empty stubs.** Never leave a template section as an empty placeholder — omit any section with nothing real to say (each template declares its required core; everything else is optional). Write an explicit "None" only where the absence itself is information (e.g., a plan's Cross-Module Contracts Affected, an LLD's Ownership Conflicts). An empty table stub reads as "not yet researched"; an omitted section reads as "doesn't apply" — keep those meanings distinct.
 
@@ -36,51 +53,43 @@ The two guarantees are complementary and both break on mixing: a reader holding
 
 ---
 
-## Decision Tree
-
-```
-User request
-    │
-    ├─ "Baseline/reconcile docs" ──────▶ maintenance agent (baseline mode) (it calls this skill per template)
-    │
-    ├─ "Document feature/module (LLD)" ▶ Feature (LLD) Template
-    │
-    ├─ "Create/update changelog" ──────▶ Changelog Template (record)
-    │
-    ├─ "Document data flow" ───────────▶ Feature Template (Architecture section)
-    │
-    ├─ "Document Redux/state" ─────────▶ Feature Template (State section)
-    │
-    ├─ "Add to protected files" ───────▶ Protected Files Template
-    │
-    ├─ "Record/revise architecture
-    │    decision" ────────────────────▶ AD Template (one per subject; revisions update it in place)
-    │
-    ├─ "System at a glance" ───────────▶ System Overview Template
-    │
-    ├─ "Domain model / glossary /
-    │    non-goals" ───────────────────▶ Steering Templates
-    │
-    ├─ "Catalog the API surface" ──────▶ API Reference Template
-    │
-    ├─ "Document env vars / config" ───▶ Environment Registry Template
-    │
-    ├─ "Security / threat model" ──────▶ Security Overview Template
-    │
-    ├─ "Testing strategy" ─────────────▶ Testing Strategy Template
-    │
-    ├─ "Recurring procedure/setup" ────▶ Operations Procedure Template
-    │
-    ├─ "One-shot migration/upgrade" ───▶ Migration Runbook Template (record)
-    │
-    ├─ "Create/update root README" ────▶ Project Root README Template
-    │
-    ├─ "Create/update plan" ───────────▶ Plan Template (record)
-    │
-    ├─ "Update existing doc" ──────────▶ Preserve existing structure
-    │
-    └─ No template matches ────────────▶ Co-Authoring Workflow (below)
-```
+## Routing
+
+| Request | Route |
+| --- | --- |
+| Baseline / reconcile docs | `maintenance` agent (baseline mode) — it calls this skill per template |
+| Document feature/module (LLD) | [`templates/feature.md`](templates/feature.md) |
+| Document data flow / state / Redux | [`templates/feature.md`](templates/feature.md) — they are sections of the feature doc |
+| Create/update changelog | [`templates/changelog-entry.md`](templates/changelog-entry.md) (record) |
+| Create/update plan | [`templates/plan.md`](templates/plan.md) (record) |
+| Record/revise architecture decision | [`templates/architecture-decision.md`](templates/architecture-decision.md) — one AD per subject; revisions update it in place |
+| System at a glance | [`templates/system-overview.md`](templates/system-overview.md) |
+| Domain model | [`templates/domain-model.md`](templates/domain-model.md) |
+| Glossary | [`templates/glossary.md`](templates/glossary.md) |
+| Non-goals | [`templates/non-goals.md`](templates/non-goals.md) |
+| Catalog the API surface | [`templates/api-reference.md`](templates/api-reference.md) |
+| Document env vars / config | [`templates/environment-registry.md`](templates/environment-registry.md) |
+| Security / threat model | [`templates/security-overview.md`](templates/security-overview.md) |
+| Testing strategy | [`templates/testing-strategy.md`](templates/testing-strategy.md) |
+| Recurring procedure/setup | [`templates/operations-procedure.md`](templates/operations-procedure.md) |
+| One-shot migration/upgrade | [`templates/migration-runbook.md`](templates/migration-runbook.md) (record) |
+| Add to protected files | [`templates/protected-files.md`](templates/protected-files.md) |
+| Create/update root README | [`templates/root-readme.md`](templates/root-readme.md) |
+| Scaffold a standard doc (docs index, `structure.md`, CHANGELOG, backlog, memory) | [`templates/Readme.md`](templates/Readme.md) — the index names each scaffold file |
+| Derive/update a feature doc's `owns:` | [`references/frontmatter.md`](references/frontmatter.md) |
+| Update existing doc | § Editing an existing doc (below) |
+| Instruction file (`CLAUDE.md`, a rule, an agent, skill prose) | Not these templates — every-load prose stays lean: assertion—reason bullets, tables over diagrams, no ASCII; the present-tense rule still applies |
+| **No template matches** | [`references/untemplated.md`](references/untemplated.md) — shape decisions + the co-authoring workflow |
+
+---
+
+## Editing an existing doc
+
+"Substantive" = anything beyond typo, link, or formatting fixes. On a substantive edit:
+
+1. **Determine the nature first.** A frozen record (a `Status: Complete`/`Abandoned` plan, a changelog entry, an executed runbook) is never edited — write a new dated record that links back.
+2. **Preserve structure, not violations.** Keep the doc's existing section shape, but every section touched sheds history narration, progress markers, and stale tripwires on the way through (§ Present tense, always).
+3. **Stamp and re-derive.** A substantive feature-doc update bumps `last-reviewed:`; if the documented scope moved, update `owns:` ([`references/frontmatter.md`](references/frontmatter.md)).
 
 ---
 
@@ -104,62 +113,7 @@ User request
 
 ## Frontmatter Derivation
 
-When creating or updating a feature doc, derive its **`owns:` frontmatter** — the code-path globs it is canonical for — from the source the doc describes. Code ownership lives in each feature doc's `owns:` frontmatter (the SessionStart hook unions them into the injected ownership index); there is no hand-maintained ownership map.
-
-### When to run
-
-- **Baseline / reconcile** — for every feature doc whose code paths aren't yet declared in its `owns:` frontmatter (the `maintenance` agent (baseline mode) calls this)
-- **New feature doc** — when creating a doc via the Feature template, project its `owns:` globs
-- **Doc update** — when the documented scope changes, update the doc's `owns:` globs
-
-### How to derive the frontmatter
-
-A feature doc's launch-map frontmatter is `owns:` (required), `module:` (optional), `keywords:` (required), and `status:` (required). An optional `last-reviewed:` date (stamped whenever the doc is substantively reviewed or updated) gives the `maintenance` agent a staleness signal to rank its audits by — it is tooling metadata, never narrated in the body.
-
-**1. `owns:`** (the path scope)
-
-Read the doc's content. Extract every source file path it references (file listings, function locations, component paths). Group them into the narrowest glob patterns that cover all referenced files without overlapping another doc's `owns:` globs at equal specificity. A doc may own several globs.
-
-| Doc references                       | Glob                      |
-| ------------------------------------ | ------------------------- |
-| Multiple files under one directory   | `src/feature/**`          |
-| Specific files in a shared directory | List each file explicitly |
-| A single entry-point file            | The exact file path       |
-
-Glob each pattern against the codebase; drop any that match nothing.
-
-**2. `module:`**
-
-The single bounded-context label this feature belongs to, or omit it for a cross-cutting feature that belongs to no single context. A module is a label, not a folder — features sharing a `module:` value are what ties that module to code (a filter over the generated ownership index).
-
-**3. `keywords:` & `status:`**
-
-`keywords:` are the discovery terms topic→doc lookup rides. `status:` is `active`, `draft`, or `deprecated` — it steers the model toward live docs and away from draft/deprecated ones.
-
-A doc's dependencies on other docs are expressed inline in its prose (links); cross-cutting contracts are diagnosed by the `boundary` skill from source, not persisted.
-
-### Rules
-
-- One canonical doc per path. A doc's `owns:` globs must not overlap another doc's at equal specificity — the narrower glob wins; equal-specificity overlap is an ownership conflict to resolve.
-- Use glob patterns for directories, explicit paths for individual files. Don't list paths that don't exist in the codebase.
-- When a doc covers a deep feature with sub-specs (e.g., `editor/`), each sub-spec owns its own globs — don't duplicate a path across siblings.
-- For baseline/reconcile with many docs, use parallel sub-agents to read source and propose `owns:` globs.
-
----
-
-## Co-Authoring Workflow
-
-For docs that don't match templates:
-
-**Stage 1: Context Gathering**
-
-- Ask: Audience? Purpose? Existing format?
-- Have user dump all context, then ask 5-10 clarifying questions
-
-**Stage 2: Structure & Draft**
-
-- Propose section structure, draft section by section
-- User indicates changes (don't edit directly — learn their style)
+A feature doc carries ownership frontmatter — `owns:` (required), `module:` (optional), `keywords:` (required), `status:` (required), optional `last-reviewed:`. Deriving it from code and keeping it accurate is [`references/frontmatter.md`](references/frontmatter.md) — every feature-doc create or update, and the `maintenance` agent's baseline pass, route there.
 
 ---
 
@@ -167,6 +121,9 @@ For docs that don't match templates:
 
 | File | Use For |
 | --- | --- |
-| `references/templates.md` | docs/README.md, structure.md, the feature-frontmatter contract, scaffolds (CHANGELOG, backlog, memory), feature, changelog, plan, operations procedure, migration runbook, protected files, AD, steering docs (system overview, domain model, glossary, non-goals, security, testing strategy), API reference, environment registry, project root README templates |
+| `templates/` | One file per template, indexed by [`Readme.md`](templates/Readme.md) — feature (LLD), changelog, plan, AD, steering docs, API reference, environment registry, operations procedure, migration runbook, protected files, READMEs, and the baseline scaffolds |
 | `references/style-guide.md` | Writing rules, formatting conventions, the two-natures tense rules |
+| `references/frontmatter.md` | Deriving a feature doc's `owns:` / `module:` / `keywords:` / `status:` from code |
+| `references/untemplated.md` | How to write a document no template covers (nature, placement, shape) + the co-authoring workflow |
 | `references/examples.md` | Good vs bad documentation examples |
+| `scripts/doc-lint.mjs` | Mechanical checks over written docs (tense narration, dates, stubs, redirects) — run over changed docs before finishing |

package/data/harnesses/code/skills/documentation/references/examples.md

@@ -21,11 +21,15 @@ function mergeData(server, local, changes) { const result = {}; const serverMap
 ```markdown
 ### `mergeData(serverData, localData, changes)`
 
-**Goal:** Merge server data with local changes **Input:**
+**Goal:** Merge server data with local changes
+
+**Input:**
 
 - `serverData` (array) - Fresh from API
 - `localData` (array) - Current state
-- `changes` (object) - `{ added, updated, removed }` **Output:** `{ merged: array, conflicts: array }`
+- `changes` (object) - `{ added, updated, removed }`
+
+**Output:** `{ merged: array, conflicts: array }`
 
 **Merge Rules:**
 
@@ -61,11 +65,22 @@ const [items, setItems] = useState([]);
 ```markdown
 ## State
 
-**Frontend (at persistence):** { "data": [], "changes": { "added": [], "updated": [], "removed": [] } // "cache": {} // UNUSED: Deprecated }
+**Frontend (at persistence):**
+
+{
+  "data": [],
+  "changes": { "added": [], "updated": [], "removed": [] }
+  // "cache": {}  // UNUSED: dead key; kept so old persisted state rehydrates
+}
 
 **Storage:** localStorage `app_state`
 
-**Backend:** model Item { id String @id data Json }
+**Backend:**
+
+export const items = pgTable('items', {
+  id: text('id').primaryKey(),
+  data: jsonb('data'),
+});
 ```
 
 ---
@@ -144,9 +159,23 @@ When the page loads, the useAppInit hook calls the syncData function. This funct
 ```markdown
 ## Data Flow
 
-┌─────────────────────────────────────────┐ │ DATA SYNC │ ├─────────────────────────────────────────┤ │ │ │ ┌──────┐ ┌──────┐ ┌──────┐ │ │ │Server│────▶│Merge │────▶│Redux │ │ │ │ API │ │ │ │Store │ │ │ └──────┘ └──────┘ └──────┘ │ │ │ │ │ ▼ │ │ Version Check │ │ │ └─────────────────────────────────────────┘
-
-**Trigger:** `useAppInit()` on page load **Version Rule:** Match → local wins, Mismatch → server wins
+┌─────────────────────────────────────────┐
+│               DATA SYNC                 │
+├─────────────────────────────────────────┤
+│                                         │
+│   ┌──────┐     ┌──────┐     ┌──────┐    │
+│   │Server│────▶│Merge │────▶│Redux │    │
+│   │ API  │     │      │     │Store │    │
+│   └──────┘     └──────┘     └──────┘    │
+│        │                                │
+│        ▼                                │
+│   Version Check                         │
+│                                         │
+└─────────────────────────────────────────┘
+
+**Trigger:** `useAppInit()` on page load
+
+**Version Rule:** Match → local wins, Mismatch → server wins
 ```
 
 ---
@@ -191,6 +220,52 @@ We use Better Auth with one-shot credential issuance…   ← current truth, no
 
 ---
 
+## Example 6: Stripping history from a truth doc
+
+The move agents fumble: deleting narration is only half the job — the story must land in a record.
+
+### ❌ Bad: The journey narrated in place
+
+```markdown
+## Export Pipeline
+
+The exporter was extracted from the legacy `reports` worker (2026-06-02) and
+now lives in `src/export/`. Phases 0–2 of the rewrite are complete; streaming
+output is not yet implemented. Treat any reference to `reports/export.js` as
+stale — it was superseded by `src/export/run.js`.
+```
+
+### ✅ Good: Present-tense truth doc + a dated record carrying the story
+
+The feature doc states only what is:
+
+```markdown
+## Export Pipeline
+
+`src/export/run.js` renders every export format from one job queue. Output is
+buffered per job (streaming is out of scope — see `docs/history/backlog.md`).
+```
+
+And the change-story goes to `docs/history/changelog/2026-06-02-export-extraction.md`:
+
+```markdown
+# 2026-06-02 — Export pipeline extracted
+
+## Summary
+
+Extracted export logic from the `reports` worker into `src/export/`.
+
+## Changes
+
+### Removed
+
+- `reports/export.js` — replaced by `src/export/run.js`; all callers repointed.
+```
+
+**Why it works:** the truth doc needs no archaeology to act on; the dates, the predecessor, and the supersession live in a frozen record; the unbuilt part is a backlog pointer, not a "not yet" hedge; and no stale-reference tripwire survives because the references themselves were fixed.
+
+---
+
 ## Quick Comparison
 
 | Aspect     | Bad                  | Good                        |
@@ -200,4 +275,5 @@ We use Better Auth with one-shot credential issuance…   ← current truth, no
 | Flows      | Prose paragraphs     | ASCII diagrams              |
 | Changelogs | "Updated X"          | Function names + migrations |
 | Decisions  | New doc per revision | One AD per subject, updated in place |
+| History    | Narrated in the doc  | Present-tense doc + dated record |
 | Length     | 100+ lines           | 20-40 lines                 |

package/data/harnesses/code/skills/documentation/references/frontmatter.md

@@ -0,0 +1,44 @@
+# Frontmatter Derivation — feature-doc ownership
+
+Load when: creating a feature doc, updating one whose documented scope moved, or running a baseline/reconcile pass over many docs.
+
+When creating or updating a feature doc, derive its **`owns:` frontmatter** — the code-path globs it is canonical for — from the source the doc describes. Code ownership lives in each feature doc's `owns:` frontmatter (the SessionStart hook unions them into the injected ownership index); there is no hand-maintained ownership map.
+
+## When to run
+
+- **Baseline / reconcile** — for every feature doc whose code paths aren't yet declared in its `owns:` frontmatter (the `maintenance` agent (baseline mode) calls this)
+- **New feature doc** — when creating a doc via the [Feature template](../templates/feature.md), project its `owns:` globs
+- **Doc update** — when the documented scope changes, update the doc's `owns:` globs
+
+## How to derive the frontmatter
+
+A feature doc's ownership frontmatter is `owns:` (required), `module:` (optional), `keywords:` (required), and `status:` (required). An optional `last-reviewed:` date (stamped whenever the doc is substantively reviewed or updated) gives the `maintenance` agent a staleness signal to rank its audits by — it is tooling metadata, never narrated in the body.
+
+**1. `owns:`** (the path scope)
+
+Read the doc's content. Extract every source file path it references (file listings, function locations, component paths). Group them into the narrowest glob patterns that cover all referenced files without overlapping another doc's `owns:` globs at equal specificity. A doc may own several globs.
+
+| Doc references                       | Glob                      |
+| ------------------------------------ | ------------------------- |
+| Multiple files under one directory   | `src/feature/**`          |
+| Specific files in a shared directory | List each file explicitly |
+| A single entry-point file            | The exact file path       |
+
+Glob each pattern against the codebase. At `status: active`, drop any that match nothing; at `status: draft`, projected globs may match nothing yet — confirm them against real code when the doc flips to `active`.
+
+**2. `module:`**
+
+The single bounded-context label this feature belongs to, or omit it for a cross-cutting feature that belongs to no single context. A module is a label, not a folder — features sharing a `module:` value are what ties that module to code (a filter over the generated ownership index).
+
+**3. `keywords:` & `status:`**
+
+`keywords:` are the discovery terms topic→doc lookup rides. `status:` is `active`, `draft`, or `deprecated` — it steers the model toward live docs and away from draft/deprecated ones.
+
+A doc's dependencies on other docs are expressed inline in its prose (links); cross-cutting contracts are diagnosed by the `boundary` skill from source, not persisted.
+
+## Rules
+
+- One canonical doc per path. A doc's `owns:` globs must not overlap another doc's at equal specificity — the narrower glob wins; equal-specificity overlap is an ownership conflict to resolve.
+- Use glob patterns for directories, explicit paths for individual files. At `active`, never list paths that don't exist in the codebase; a `draft`'s projected paths are confirmed at `active`.
+- When a doc covers a deep feature with sub-specs (e.g., `editor/`), each sub-spec owns its own globs — don't duplicate a path across siblings.
+- For baseline/reconcile with many docs, use parallel sub-agents to read source and propose `owns:` globs.