@nurix/etna 0.20.36 → 0.20.37

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

@@ -1,12 +1,12 @@
-# Documentation Examples
+# Documentation examples
 
-Good vs bad examples showing the key differences.
+Good and bad documentation side by side; `style-guide.md` cites each example by number.
 
 ---
 
-## Example 1: Function Documentation
+## Example 1: Function documentation
 
-### Bad: Full Implementation
+### Bad: full implementation
 
 ```markdown
 ### mergeData
@@ -14,9 +14,9 @@ Good vs bad examples showing the key differences.
 function mergeData(server, local, changes) { const result = {}; const serverMap = new Map(server.map((i) => [i.id, i])); // ... 30 more lines return result; }
 ```
 
-**Problems:** Will become obsolete, focuses on HOW not WHAT.
+**Problems:** goes stale with the first refactor; shows *how* instead of *what*.
 
-### Good: Contract Only
+### Good: contract only
 
 ```markdown
 ### `mergeData(serverData, localData, changes)`
@@ -40,9 +40,9 @@ function mergeData(server, local, changes) { const result = {}; const serverMap
 
 ---
 
-## Example 2: State Documentation
+## Example 2: State documentation
 
-### Bad: State Everywhere
+### Bad: state everywhere
 
 ```markdown
 ## Component State
@@ -58,9 +58,9 @@ const [items, setItems] = useState([]);
 { items: [], loading: false, error: null }
 ```
 
-**Problems:** Documents transient state, repeats shapes.
+**Problems:** documents transient state and repeats shapes.
 
-### Good: Persistence Points Only, in the API reference
+### Good: persistence points only, in the API reference
 
 Persisted shapes live in the API reference (`docs/architecture/api.md`), never in a feature document, where `## State` is a retired mechanism section.
 
@@ -89,7 +89,7 @@ export const items = pgTable('items', {
 
 ## Example 3: Changelog
 
-### Bad: Vague
+### Bad: vague
 
 ```markdown
 # 2025-01-05 - Updates
@@ -105,7 +105,7 @@ export const items = pgTable('items', {
 - Various files in src/
 ```
 
-### Good: Behavior First, Refinement Context Kept
+### Good: behavior first, refinement context kept
 
 ```markdown
 # 2025-01-05 · data-sync — Local edits survive a sync only when versions match
@@ -123,7 +123,7 @@ export const items = pgTable('items', {
 
 ## Example 4: Flow
 
-### Bad: Mechanism narrated in a paragraph
+### Bad: mechanism narrated in a paragraph
 
 ```markdown
 ## Data Flow
@@ -133,7 +133,7 @@ When the page loads, the useAppInit hook calls the syncData function. This funct
 
 **Problems:** names a hook, a function and a store that a rename would invalidate (the stability test); runs parallel cases together in one paragraph; gives a scanning reader no label to land on; "Data Flow" is a retired mechanism section.
 
-### Good: Labelled bullets, a role-level diagram beside them
+### Good: labelled bullets, a role-level diagram beside them
 
 ````markdown
 ## Flows
@@ -161,7 +161,7 @@ sequenceDiagram
 
 ## Example 5: Architecture Decision revision
 
-### Bad: Supersession chain
+### Bad: supersession chain
 
 ```
 docs/architecture/decisions/
@@ -170,9 +170,9 @@ docs/architecture/decisions/
 └── AD-011-auth-better-auth-v2.md  (status: Accepted, "supersedes AD-006")
 ```
 
-**Problems:** Three files hold one subject; the reader must diff a chain to learn the current truth; two of the three are wrong-but-present (the same pathology as keeping `report_v1.sql` beside the live `report_v2.sql`); the reasoning that killed Keycloak is stranded in a dead file nobody opens.
+**Problems:** three files hold one subject; the reader must diff a chain to learn the current truth; two of the three are wrong-but-present (the same pathology as keeping `report_v1.sql` beside the live `report_v2.sql`); the reasoning that killed Keycloak is stranded in a dead file nobody opens.
 
-### Good: One subject, updated in place
+### Good: one subject, updated in place
 
 ```
 docs/architecture/decisions/
@@ -195,15 +195,15 @@ We use Better Auth with one-shot credential issuance…   ← current truth, no
 - 2026-01-10 — Initial decision accepted. Implemented by [plan](…).
 ```
 
-**Why it works:** The body answers "how does auth work and why" without archaeology; the tail preserves every reversal with its trigger; the rejected alternatives stay findable in the one file a reader actually opens.
+**Why it works:** the body answers "how does auth work and why" without archaeology; the tail preserves every reversal with its trigger; the rejected alternatives stay findable in the one file a reader actually opens.
 
 ---
 
 ## 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.
+Deleting narration is only half the move; the story **must** land in a record.
 
-### Bad: The journey narrated in place
+### Bad: the journey narrated in place
 
 ```markdown
 ## Export Pipeline
@@ -214,7 +214,7 @@ 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
+### Good: present-tense truth doc + a dated record carrying the story
 
 The feature doc states only what is:
 
@@ -243,7 +243,7 @@ And the change-story goes to `docs/history/changelog/2026-06-02-export-extractio
 
 ---
 
-## Quick Comparison
+## Quick comparison
 
 | Aspect     | Bad                  | Good                        |
 | ---------- | -------------------- | --------------------------- |

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

@@ -6,7 +6,7 @@ This reference states how a document joins the knowledge graph, and it is kept i
 
 ## The model
 
-A document names the product objects it designs. Every other edge between a document and the code is either authored on the code's side or computed, never typed into the document. The harness's ownership scan reads one edge today, the transitional `owns:` region glob (§ `owns:`); principles 2 and 3 are the edges it switches to, and the header pointer is written now so the switch needs no second pass over the code.
+A document names the product objects it designs. Every other edge between a document and the code is either authored on the code's side or computed, never typed into the document. The harness's ownership scan reads one edge, the transitional `owns:` region glob (§ `owns:` — transitional); principles 2 and 3 are the edges it switches to, and the header pointer is written alongside it so the switch needs no second pass over the code.
 
 ### Principles
 
@@ -63,7 +63,7 @@ Tooling keys sit beside these on any genre: `rev:` (a generator's generation sta
 
 ### `owns:` — transitional
 
-- **Reason for the key:** the harness's ownership scan (`.claude/hooks/lib/ownership.mjs`) keys on `owns:` until it switches to the header pointers and the object closure, which is the knowledge layer's recorded gap. Until then the key keeps the session's ownership index and the doc-debt detectors working.
+- **Reason for the key:** the harness's ownership scan (`.claude/hooks/lib/ownership.mjs`) keys on `owns:` until it switches to the header pointers and the object closure, which is the knowledge layer's recorded gap. The key is what keeps the session's ownership index and the doc-debt detectors working.
 - **Form:** region globs only, one per region the document speaks for: `packages/{name}/**` on a package document, the machine's subtrees on a system document, a feature's own directory on a feature document. Never a list of individual files, and never a shared file several features import.
 - **Growth:** none. A new document carries the region glob its genre needs and nothing more; an edit never adds file-level entries.
 - **Retirement:** removed from every document in the same change that switches the scan, and this section with it.
@@ -73,7 +73,7 @@ Tooling keys sit beside these on any genre: `rev:` (a generator's generation sta
 | Key | Retired because | What replaces it |
 | --- | --- | --- |
 | `applies:` | A list of governing documents is a hand-kept copy of a relationship the graph computes through the objects both documents name, and it drifts the way any copy does | The objects the doctrine and the surface share, computed; for people, the document's Scope section (a UX document's Purpose) names its governing doctrine and what each settles |
-| `keywords:` | An object's name and aliases are its discovery terms | `objects:`. The ownership scan still shows a document's `keywords:` in the index when it names no `objects:`, so removing the key without adding `objects:` empties that entry |
+| `keywords:` | An object's name and aliases are its discovery terms | `objects:`. The ownership scan shows a document's `keywords:` in the index when it names no `objects:`, so removing the key without adding `objects:` empties that entry |
 | A file-level `owns:` list | The header pointers and the object closure compute it | Region globs only, until the scan switches (above) |
 
 An edit to a document that carries a retired key removes the key in the same edit.

package/data/harnesses/code/skills/documentation/references/instruction-style.md

@@ -1,4 +1,4 @@
-# Instruction-File Style
+# Instruction-file style
 
 The shared style for every file an agent obeys — a `CLAUDE.md`, a rule, an agent definition, skill prose. Prose style only: frontmatter is metadata, not style. Docs-tree documents follow the skill's templates and [`style-guide.md`](style-guide.md) instead.
 
@@ -6,11 +6,11 @@ The shared style for every file an agent obeys — a `CLAUDE.md`, a rule, an age
 
 An instruction file is paid for whenever it loads, scaled by its load class: `CLAUDE.md` and unscoped rules load on **every turn of every session** — the most expensive prose in a repo per word; a `paths:`-scoped rule loads on those same terms from its first matching file read on; an agent definition loads per dispatch, a skill per invocation. The bar is not "is this true?" but **"must this be in front of the agent whenever this file loads?"** Measure weight in tokens, not lines; trim biggest-first on every edit.
 
-**Rewriting, the test is armor vs. narration.** A reason clause either blocks a move an agent would otherwise make — the failure is counter-intuitive, the wrong fix looks correct, or the rule reads as arbitrary tidiness and gets "improved away" — or it explains the self-evident. Ask of each: *does the forbidden move look correct to an agent mid-task?* Keep the first kind, cut the second. **A constraint may lose its explanation; it may never lose its existence** — compression is fewer words for the same constraints, so a passage that cannot shrink without dropping one stays long.
+**On a rewrite, the test is armor vs. narration.** A reason clause either blocks a move an agent would otherwise make — the failure is counter-intuitive, the wrong fix looks correct, or the rule reads as arbitrary tidiness and gets "improved away" — or it explains the self-evident. Ask of each: *does the forbidden move look correct to an agent mid-task?* Keep the first kind, cut the second. **A constraint may lose its explanation; it may never lose its existence** — compression is fewer words for the same constraints, so a passage that cannot shrink without dropping one stays long.
 
 ## Coherence
 
-A rewrite is not only a trim — read the file as one artifact and fix what disagrees or is missing:
+A rewrite is not only a trim. Read the file as one artifact and fix what disagrees or is missing:
 
 - **Two statements of one fact agree, or become one.** A defaults block vs. the worked example beside it, a table row vs. a bullet — reconcile against the code the rule governs and keep one canonical statement; a silent disagreement is worse than either version alone, because each reader picks a different one.
 - **Every cross-reference resolves** — the cited `§`, sibling file, or command exists and still says what the citation claims. Section numbers are a public surface other files cite: append, never reshuffle.

package/data/harnesses/code/skills/documentation/references/source-comments.md

@@ -2,17 +2,17 @@
 
 Load when: writing or sweeping source-file comments, or cutting a comment whose claim belongs in a document. Not needed to write a document.
 
-**In `docs/`, never in the file's comments** — and this skill is the half of that rule that makes it safe. A source file carries a repo-relative path header of two or three present-tense sentences and one third-person sentence above each non-obvious function; the shape is the harness's `CLAUDE.md` § File Structure, which is canonical and is not restated here. That header's `docs/…` path is also the file's edge into the knowledge graph: the header pointer names the document that speaks for the file, which is how ownership is computed ([`frontmatter.md`](frontmatter.md)). What lands **here** is everything that shape displaces: design rationale, the alternatives weighed, the measurement behind a constant, the reason an obvious-looking change is wrong.
+**In `docs/`, never in the file's comments** — and this skill is the half of that rule that makes it safe. A source file carries a repo-relative path header of two or three present-tense sentences and one third-person sentence above each non-obvious function; the canonical shape is the harness's `CLAUDE.md` § File Structure. That header's `docs/…` path is also the file's edge into the knowledge graph: the header pointer names the document that speaks for the file, which is how ownership is computed ([`frontmatter.md`](frontmatter.md)). What lands **here** is everything that shape displaces: design rationale, the alternatives weighed, the measurement behind a constant, the reason an obvious-looking change is wrong.
 
 **Cutting a comment is a move, not a deletion.** A claim taken out of a source file is owed one of two things before the cut is done, and the choice is per claim, not per file:
 
 | The claim is | What it earns |
 | --- | --- |
 | Worth keeping, and its doc does not state it | A section in the **owning feature doc** (the ownership index resolves which), carrying the claim and the argument for why the codebase is worse without it — never the comment's wording, which was written for a reader holding the code |
-| Already stated in its doc | Nothing — but you **open that doc and find the sentence** before saying so. An assumed duplicate is how a claim is lost |
+| Already stated in its doc | Nothing, once you **open that doc and find the sentence**. An assumed duplicate is how a claim is lost |
 | History, a ticket or decision-record reference, a dated note, a divider, or narration of code that no longer exists | Nothing, and no record. A record lives in `docs/history/`; these are not claims about the present |
 
-**Count what you cut, and prove the cut was only comments.** A comment sweep states comment lines before and after per file, so a drop nobody accounted for is visible as a number rather than as a feeling. [`scripts/comment-strip.mjs`](../scripts/comment-strip.mjs) turns that from a claim into a check: it strips comments from both revisions — honouring strings, template and character literals, regex literals, raw strings and JSX comment braces — and diffs what is left, so a sweep that quietly changed executable code cannot pass as a cleanup. `comment-strip.mjs --rev <before> --to <after> <paths…>` exits 0 for "no executable code changed" and 1 naming the file and the first diverging line. Run it over any pass that touches more than a handful of files; a sweep without it is an assertion.
+**Count what you cut, and prove the cut was only comments.** A comment sweep states comment lines before and after per file, so an unaccounted drop shows as a number. [`scripts/comment-strip.mjs`](../scripts/comment-strip.mjs) turns that from a claim into a check: it strips comments from both revisions — honouring strings, template and character literals, regex literals, raw strings and JSX comment braces — and diffs what is left, so a sweep that quietly changed executable code cannot pass as a cleanup. `comment-strip.mjs --rev <before> --to <after> <paths…>` exits 0 for "no executable code changed" and 1 naming the file and the first diverging line. Run it over any pass that touches more than a handful of files; a sweep without it is an assertion.
 
 **The mechanical half of the shape is checked, not remembered.** [`scripts/source-lint.mjs`](../scripts/source-lint.mjs) `--changed` reports a header that names another path or none, a change whose added lines are over a quarter comments, and the four shapes the convention deletes outright — narration, ALL-CAPS emphasis, an over-long header, a comment block that has become a document. Block-severity findings must be fixed; the escape hatch is a `source-lint-disable: <id>` comment with the reason in a second comment beside it, and the only finding that legitimately takes one is a booby trap. The harness detector raises a bookkeeping row for the same condition, so an unfixed breach outlives the session that wrote it.
 

package/data/harnesses/code/skills/documentation/references/style-guide.md

@@ -1,9 +1,9 @@
 <!-- doc-lint-disable: date-in-truth-doc, history-narration, stale-tripwire, progress-marker, temporal-hedge, predecessor-frame, status-glyph -->
 <!-- reason: the style authority quotes the forbidden constructions verbatim in its ❌ columns; each match is an example of what not to write. -->
 
-# Documentation Style Guide
+# Documentation style guide
 
-This guide states how a document is written: every file under `docs/` and every README the `documentation` skill authors or edits. Two neighbouring authorities answer the questions beside it. [`instruction-style.md`](instruction-style.md) governs the files an agent obeys (`CLAUDE.md`, rules, agents, skill prose), which are paid for on every load and written lean; each template in [`templates/`](../templates/Readme.md) governs its genre's sections and fields. The first two sections of this guide are enough to write a correct document; the sections after them are the detail each principle unfolds into, and a reader who stops early holds a coarse picture that is still true.
+This guide states how a document is written: every file under `docs/` and every README the `documentation` skill authors or edits. Two neighbouring authorities answer the questions beside it: [`instruction-style.md`](instruction-style.md) governs the files an agent obeys (`CLAUDE.md`, rules, agents, skill prose), which are paid for on every load and written lean, and each template in [`templates/`](../templates/Readme.md) governs its genre's sections and fields. The first two sections are enough to write a correct document; the sections after them are the detail each principle unfolds into, so a reader who stops early holds a coarse picture that is true.
 
 ## The model
 
@@ -75,7 +75,7 @@ The test (principle 3) decides what a sentence may say. These survive it:
 
 Unbuilt work has one home per kind. Decided design the code does not do yet is an `UNBUILT` block where the design is stated; a shortfall in what is built (a promise the code does not keep, a case it mishandles) is one bullet under Gaps; the work that would close either is a backlog row, and the document never tracks that work's progress.
 
-The authority split (principle 4) is stated once, where agents enter the docs (the root instruction file or `docs/README.md`), so a reader who finds the code and the document disagreeing knows which way to resolve it. A doctrine document restates it in its model where its readers would otherwise not know; a feature, package or system document never does, because its opening is fixed to its goal.
+The authority split (principle 4) is stated once, where agents enter the docs (the root instruction file or `docs/README.md`), so a reader who finds the code and the document disagreeing knows which way to resolve it. A doctrine document restates it in its opening, as the authority sentence (`templates/doctrine.md`), where its readers would otherwise not know; a feature, package or system document never does, because its opening is fixed to its goal.
 
 ### Diagrams and length by layer
 
@@ -131,7 +131,7 @@ A feature, package or system document is scanned more than read (principle 6). I
 | System | Opening paragraph (the machine defined) · Scope · Flow · Decisions · Promises · Gaps · For the agent |
 | Package | Identity line · Goal line · Scope · Ownership · Usage · Decisions · Promises · Gaps · For the agent |
 
-Nothing else. "Why it exists" is retired; its content is Scope or Decisions. Mechanism sections (Architecture, Key Functions, State, Files, Schema, Routes, Wire, and their kin) are the graph's, and `doc-lint` blocks them as `mechanism-section`. The templates say when each section is required and how long each genre runs.
+Nothing else. A "Why it exists" section has no place; its content is Scope or Decisions. Mechanism sections (Architecture, Key Functions, State, Files, Schema, Routes, Wire, and their kin) are the graph's, and `doc-lint` blocks them as `mechanism-section`. The templates say when each section is required and how long each genre runs.
 
 ### The body
 
@@ -269,7 +269,7 @@ flowchart LR
 
 ## Reference documents
 
-A reference document is the deepest genre: signatures, shapes and variables are its content, so the stability test does not apply to it (§ The genres). These rules bind only there, and in a procedure's appendix; an owning document names a symbol nowhere but its footer, and then only as a seam.
+A reference document is the deepest genre: signatures, shapes and variables are its content, so the stability test does not apply to it (§ The genres). These rules bind only there, and in a procedure's appendix; an owning document names a symbol only as a seam (§ Owning documents — the body and the footer).
 
 ### Function signatures
 

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

@@ -1,28 +1,28 @@
-# Writing an Untemplated Document
+# Writing an untemplated document
 
 Load when: no template in [`templates/`](../templates/Readme.md) matches the document being written — a design note, a comparison, an investigation writeup, an index, a reference sheet, anything the Routing table sends to "no template matches".
 
 A template is a pre-made set of shape decisions. With no template, make the same decisions explicitly, in this order.
 
-## 1. Decide the nature — truth or record
+## 1. Decide the nature — truth, record or queue
 
-Every document is exactly one (`SKILL.md` § The three natures). Ask: *when reality changes, is this file rewritten, frozen, or does it lose a row?*
+Every document is exactly one of the three (`SKILL.md` § The three natures). Ask: *when reality changes, is this file rewritten, frozen, or does it lose a row?*
 
-- Rewritten in place → **truth document**. Topic-named (`kebab-case.md`), lives outside `docs/history/`, present tense throughout — the iron rule in `SKILL.md` § The three natures.
-- A list of open work whose rows are added and deleted → **queue**. A fixed name, one row per item; extend an existing queue before inventing one.
+- Rewritten in place → **truth document**. Topic-named (`kebab-case.md`), lives outside `docs/history/`, present tense throughout.
 - Frozen → **record**. Date-named (`YYYY-MM-DD-slug.md`), lives in `docs/history/` — inside an existing subfolder where it fits (an investigation or research writeup → `history/research/{topic}/`); a genuinely new category of record needs a `docs/structure.md` folder-rule row in the same change, never an invented folder.
+- Loses a row when work is resolved → **queue**. A fixed name, one row per item; extend an existing queue before inventing one.
 
 When a draft wants to be both — the current state *and* the story of getting there — split it: the state becomes a truth document, the story becomes a record that links to it. Never mix the natures in one body.
 
 ## 2. Place and name it
 
 - `docs/structure.md` is the placement authority — match the document's topic to its folder map before inventing a location.
-- **One canonical home per topic.** If a document on the topic already exists, extend it; a second document on the same topic is drift waiting to happen. Link, don't copy.
+- **One canonical home per topic.** If a document on the topic already exists, extend it; a second document on the same topic is drift. Link, don't copy.
 - A new topic *folder* gets a `Readme.md` landing page that describes what the folder holds and how its files are named, never a row per file (`type: folder-index`).
 
 ## 3. Shape it
 
-- **Open with the goal.** The first line under the H1 states what the document is for and who reads it — a reader (or agent) landing here cold decides in one sentence whether to keep reading.
+- **Open with the goal.** The first line under the H1 states what the document is for and who reads it, so a reader landing cold decides in one sentence whether to keep reading.
 - **Headings are noun phrases** — no verb, no tense, no person (`references/style-guide.md` § Labels).
 - **Headings are retrieval keys.** Sections get pulled out of context by search and agents; qualify generic headings with the topic (`## Merge rules — data sync`, not `## Rules`) so each stands alone.
 - **Tables for enumerable facts, prose for judgment.** One row per item; anything needing a *because* lives in prose around the table, never inside a cell.
@@ -38,4 +38,4 @@ When a draft wants to be both — the current state *and* the story of getting t
 
 **Stage 1 — context gathering.** Read what already exists on the topic, then draft the structure from §1–3 with sensible defaults for audience, purpose and format. Ask only the questions whose answer the repository cannot give and a default would get wrong (usually one to three), each with your recommended answer, in one message.
 
-**Stage 2 — draft.** Show the structure with the questions, then draft the whole document on the answers or the defaults. The user indicates changes — learn their style from their edits; don't silently rewrite them.
+**Stage 2 — draft.** Show the structure with the questions, then draft the whole document on the answers or the defaults. Learn the user's style from the changes they make, and **never** silently rewrite their edits.

package/data/harnesses/code/skills/documentation/scripts/doc-lint.mjs

@@ -234,8 +234,9 @@ function lintFile(path, findings) {
       findings.push({ path, n: 1, severity: 'block', id: 'record-type-in-truth-location', message: `\`type: ${declared}\` is a record genre declared in a truth location — move the file to \`docs/history/\` if it is a record, or give it its location's genre` });
   }
 
-  // A folder index (Readme.md/README.md) is a browse page, not a feature doc — it owns no code.
-  const isFolderIndex = /(^|\/)(readme)\.md$/i.test(path);
+  // A folder index (Readme.md/README.md) is a browse page that owns no code; a Readme declaring an owning genre is
+  // that folder's landing document and is graded as its genre instead.
+  const isFolderIndex = /(^|\/)(readme)\.md$/i.test(path) && !['feature', 'package', 'system'].includes(declaredType(text));
 
   // An index names folders, never files (SKILL.md § Indexes and descriptions). A link from a folder index or
   // the authority map to an individual document is a row that must be edited on every add, rename

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

@@ -61,7 +61,7 @@ Every fact about a genre lives in one row of the table below: its template, its
 
 ## Ownership
 
-Three genres speak for code — **feature**, **package**, **system** — and a **UX** document speaks for a surface's components where none of them does (`ux-behavior.md`). A document names the objects it designs in `objects:`; a source file names the document that speaks for it in its path header. The harness's ownership scan reads one edge today, the transitional `owns:` region glob on each owning document (`packages/{name}/**` on a package, a machine's subtrees on a system, a feature's own directory on a feature), and the narrower glob wins. The header pointer is written now so the scan can switch to it and the object closure without a second pass over the code (`references/frontmatter.md`).
+Three genres speak for code — **feature**, **package**, **system** — and a **UX** document speaks for a surface's components where none of them does (`ux-behavior.md`). A document names the objects it designs in `objects:`; a source file names the document that speaks for it in its path header. The harness's ownership scan reads one edge, the transitional `owns:` region glob on each owning document (`packages/{name}/**` on a package, a machine's subtrees on a system, a feature's own directory on a feature), and the narrower glob wins. The header pointer is written alongside it so the scan can switch to it and the object closure without a second pass over the code (`references/frontmatter.md`).
 
 ## Baseline scaffolds
 

package/data/harnesses/code/skills/documentation/templates/acceptance-criteria.md

@@ -1,4 +1,4 @@
-# Acceptance Criteria
+# Acceptance criteria
 
 Truth document. Use for: the promises one capability must keep, stated as machine-parseable claims. Lives in `docs/acceptance/`, one `kebab-case.md` per capability. Written at specification time — before implementation — and read by verification surfaces, which parse each `AC-n` line as a claim to grade the built product against.
 

package/data/harnesses/code/skills/documentation/templates/api-reference.md

@@ -1,4 +1,4 @@
-# API Reference (docs/architecture/api.md)
+# API reference (docs/architecture/api.md)
 
 Truth document. Use for: the consolidated catalog of the system's HTTP surface — every live route in one place. This is the **reference document** for the API surface: a route's shape lives here or in the generated spec, never in a feature doc, which states what the route promises and leaves its shape to this catalog. If the repo generates an OpenAPI spec, this doc points at it and carries only what the spec can't (auth model, conventions, ownership links).
 

package/data/harnesses/code/skills/documentation/templates/architecture-decision.md

@@ -24,7 +24,7 @@ Don't write an AD for:
 
 `Proposed` → `Accepted` → `Deprecated`
 
-Frontmatter `status:` is the single lifecycle source of truth. An AD stays `Accepted` for as long as its subject is live — revisions rewrite the body and never change the status, and there is **no `Superseded` state**: supersession is an edit plus a changelog entry, not a new document. Set `Deprecated` only when the subject itself is retired (the component is gone, the contract no longer exists); state where the replacement lives, if any.
+Frontmatter `status:` is the single lifecycle source of truth; **never** also write "Status: Accepted" in the body. An AD stays `Accepted` for as long as its subject is live — revisions rewrite the body and never change the status, and there is **no `Superseded` state**: supersession is an edit plus a changelog entry, not a new document. Set `Deprecated` only when the subject itself is retired (the component is gone, the contract no longer exists); state where the replacement lives, if any.
 
 ### Naming
 
@@ -110,12 +110,8 @@ reviewers: [] # optional
 
 ### Rules
 
-- **One subject per AD; all its revisions stay inside it.** Two genuinely different subjects means two ADs — a revision of an existing subject never does.
-- **The body is always the current truth.** Rewrite affected sections on every revision; never leave a superseded choice narrated in the body — the Decision Changelog carries the journey, with each entry naming the old choice and the trigger.
-- Decision-first. The first paragraph after the heading is the answer; readers should not need to scroll.
 - **Consequences lists positives, negatives, AND risks.** Pros-only Consequences is the genre's classic failure — one AD's honest resulting context is the input context for the next.
 - **Options Considered keeps every genuinely rejected alternative with the real reason.** Informed rejections are the most expensive knowledge to lose; a rejection made with strong prior art in view says so explicitly.
 - **Keep it short — one to two pages.** Long decision docs don't get updated. How-it-works detail belongs in the owning feature doc; execution in a plan. Link, don't embed.
-- No section numbering (`§5.1.1`). Use markdown headings only — inserting a section shouldn't renumber everything.
-- Frontmatter `status` is the single source of truth for lifecycle. Don't also write "Status: Accepted" in the body.
-- The Decision Changelog is append-only, newest first. Typo and formatting fixes don't get entries.
+- **No section numbering** (`§5.1.1`); markdown headings only, so inserting a section renumbers nothing.
+- **The Decision Changelog is append-only, newest first**, one entry per revision naming the old choice and the trigger. Typo and formatting fixes get no entry.

package/data/harnesses/code/skills/documentation/templates/behavioral-checklist.md

@@ -1,4 +1,4 @@
-# Behavioral Checklist (docs/tests/{feature}.md)
+# Behavioral checklist (docs/tests/{feature}.md)
 
 Truth document. Use for: **how to verify one feature's promised behavior by driving the real product** — the browser, the CLI binary, HTTP against the running service. One file per feature, named for the feature doc that owns the code (`docs/features/auth.md` → `docs/tests/auth.md`).
 

package/data/harnesses/code/skills/documentation/templates/changelog-entry.md

@@ -1,4 +1,4 @@
-# Changelog Entry
+# Changelog entry
 
 Record. Use for: the per-unit-of-work journal of what changed and how it was refined — one file per entry under `docs/history/changelog/YYYY-MM-DD-{three-words}.md`, written by whoever does the work and frozen inside the commit it describes. The three words name the work, not the commit. Trigger and lifecycle policy: the `changelog` rule; distillation is the `retro` agent.
 

package/data/harnesses/code/skills/documentation/templates/changelog-index.md

@@ -22,7 +22,7 @@ description: "How {Project Name}'s changelog works: one entry per unit of work u
 ## Owed entries
 
 - **Plan completion:** a draft entry, written when the plan reaches `Status: Complete`.
-- **Commit:** every non-exempt commit carries its entry inside it (the `changelog` rule lists the exemptions).
+- **Commit:** every non-exempt commit carries its entry inside it (the closed exemption list is the `documentation` skill's `templates/changelog-entry.md`).
 
 ## Reading the changelog
 

package/data/harnesses/code/skills/documentation/templates/docs-readme.md

@@ -1,8 +1,8 @@
-# docs/README.md (Documentation Root)
+# docs/README.md (documentation root)
 
-Truth document. Use for: the entry point for all documentation in a repo. Created during baseline audit.
+Truth document. Use for: the entry point for all documentation in a repo, created by the `maintenance` agent's baseline.
 
-**This file describes directories, never files.** Each section names one folder under `docs/` and says what the folder holds, who reads it and how its files are named — a description of the directory, not of its contents. No per-file rows, no file tree, no `├──` block: the tree is `structure.md`'s, as the authority on placement, and `ls` is the roster. A row per file forces an index edit on every file added, renamed or retired, and the index's own history then records roster churn instead of what the index said. Each section below names a folder and says what the folder holds and how its files are named; the only files an index may name are the mandated scaffolds and the root instruction files, listed in `SKILL.md` § The three natures. The repo-root `README.md` routes the team and agents in by intent; this file describes the folders of the docs tree — each links the other once and neither restates the other. Naming a file without a link is the same row: no filename, no record ID (`AD-010`), no per-record table. Each file's own `description:` frontmatter is its account, read with `grep -m1 '^description:' <folder>/*.md`. `doc-lint` blocks a folder index that links an individual document (`index-lists-files`), names one (`index-names-records`) or draws a tree (`index-file-tree`).
+**This file describes directories, never files.** Each section names one folder under `docs/` and says what the folder holds, who reads it and how its files are named. No per-file rows, no file tree, no `├──` block: the tree is `structure.md`'s, as the authority on placement, and `ls` is the roster. A row per file forces an index edit on every file added, renamed or retired, so the index's history records roster churn instead of what the index said. Naming a file without a link is the same row: no filename, no record ID (`AD-010`), no per-record table. The only files an index may name are the mandated scaffolds and the root instruction files (`SKILL.md` § Indexes and descriptions). Each file's own `description:` frontmatter is its account, read with `grep -m1 '^description:' <folder>/*.md`. `doc-lint` blocks a folder index that links an individual document (`index-lists-files`), names one (`index-names-records`) or draws a tree (`index-file-tree`). The repo-root `README.md` routes the team and agents in by intent and this file describes the folders of the docs tree; each links the other once and neither restates the other.
 
 **Link only what exists.** Every row below is a placeholder — drop any whose target the repo does not have. Most `history/` and `architecture/` folders are created on first use, so linking them unconditionally ships a docs index with dead links on day one. An index is a browse page: a link that resolves to nothing is worse than an absent row.
 

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

@@ -1,4 +1,4 @@
-# Doctrine Documentation (docs/architecture/common/{concern}.md)
+# Doctrine documentation (docs/architecture/common/{concern}.md)
 
 Truth document. Use for **one concern the platform handles everywhere**: authentication, authorization, storage, the API protocol, credentials, telemetry. One file per concern, named for the concern. A doctrine document speaks for no code: no source header names it, and it carries no `owns:`. The surfaces bound by it are the documents that design or touch the objects it governs, computed through those objects, and each names it in its Scope.
 

package/data/harnesses/code/skills/documentation/templates/domain-model.md

@@ -1,4 +1,4 @@
-# Domain Model (docs/architecture/domain-model.md)
+# Domain model (docs/architecture/domain-model.md)
 
 Truth document. Use for: the entities the system is about — what they are, how they relate, and who owns their state. The vocabulary here must match the glossary and the code; when they disagree, fix the disagreement, don't document around it.
 

package/data/harnesses/code/skills/documentation/templates/environment-registry.md

@@ -1,4 +1,4 @@
-# Environment Registry (docs/operations/environment.md)
+# Environment registry (docs/operations/environment.md)
 
 Truth document. Use for: the config surface — every variable the code reads, in one table. `.env.example` mirrors this doc's variable list.
 

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

@@ -1,4 +1,4 @@
-# Feature Documentation (docs/features/{feature}.md)
+# Feature documentation (docs/features/{feature}.md)
 
 Truth document. Use for every feature in `docs/features/`: something a person points at, such as an address, a command family or a named control. One file per feature, cut by the objects it designs, never by the code's routers, tables, plans or packages. The file persists from design (`status: draft`) to live reference (`status: active`).
 
@@ -8,9 +8,9 @@ Truth document. Use for every feature in `docs/features/`: something a person po
 - **Each bullet is a bold label, then one or two third-person sentences** saying what happens: "**Organization user:** user lands in their existing organization", never "you land…".
 - **Flows carry the journey; Decisions carry the reasons; Promises run deepest.**
 
-The frontmatter names the objects the feature designs; which files it speaks for is never listed in the body. The ownership scan reads its transitional `owns:` region glob today, and each owned source file's header names this document for when the scan switches (`references/frontmatter.md`). Every computable fact (columns, vocabularies, foreign keys, writers, routes, guards, files) is the code graph's (`docs/architecture/systems/knowledge-layer.md`), and a hand-typed copy is the defect this genre removes. Code is named only where a person types or sees it (a page, a command, a flag, an environment variable) or at a cross-cutting seam the graph would not lead a reader to.
+The frontmatter names the objects the feature designs; which files it speaks for is never listed in the body. The ownership scan reads its transitional `owns:` region glob, and each owned source file's header names this document, ready for when the scan switches (`references/frontmatter.md`). Every computable fact (columns, vocabularies, foreign keys, writers, routes, guards, files) is the code graph's (`docs/architecture/systems/knowledge-layer.md`), and a hand-typed copy is the defect this genre removes. Code is named only where a person types or sees it (a page, a command, a flag, an environment variable) or at a cross-cutting seam the graph would not lead a reader to.
 
-**A feature document runs deepest toward its end.** Scope and Flows are the model and the journey. **Promises** goes as deep as the behaviour does: every state the surface can be in, every edge case, what a refusal tells the person, and the exact wording wherever the wording itself is promised. That depth is earned because a person or a test checks it and the code cannot state it as intent. It still stops before mechanism. A promise reads "a removed membership shows a panel, not a redirect", never which route answers it.
+**A feature document runs deepest toward its end.** Scope and Flows are the model and the journey. **Promises** goes as deep as the behaviour does: every state the surface can be in, every edge case, what a refusal tells the person, and the exact wording wherever the wording itself is promised. That depth is earned because a person or a test checks it and the code cannot state it as intent. It stops before mechanism. A promise reads "a removed membership shows a panel, not a redirect", never which route answers it.
 
 **Sections:**
 

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

@@ -2,7 +2,7 @@
 
 Record. Use for: the account an **unattended or multi-session build** leaves the person who owns it — written by the orchestrating session as its last act, before the owner's first decision, read in one sitting. It is a **decision queue, an undo manual and a resume file**, in that order: is it done · what must I decide today · what escaped the repository and how do I undo it · can I see it working · what was decided for me and how do I overturn it · what is red and whose it is. Everything below the divider is for the next session, not the owner. It is not a pull-request description (which argues for a diff), not a changelog entry (which carries refinement context) and not a plan (which is frozen). It is mutable while `status: open` — a successor that re-proves a state line corrects it in place and appends one Timeline row — and **freezes when the owner has acted on § 1 (`status: accepted`)**; a correction after that is a new dated hand-over linking back. Raw artefacts (plans, hand-offs, notes) live in a same-named folder beside it.
 
-Required: **Verdict**, **Owner decisions due**, **Live-world ledger** (even when empty), **Ten-minute walkthrough**, **Rulings on the owner's behalf**, **Red board**, **What was built**, **Proof**, **State**, **Open loops**, **Artefacts & mandate**. Optional: Left alone, Discoveries, Debt, Cost, Timeline.
+Required: **Verdict**, **Owner decisions due**, **Live-world ledger** (even when empty), **Ten-minute walkthrough**, **Rulings on the owner's behalf**, **Red board**, **What was built**, **Proof**, **State**, **Open loops**, **Artefacts & mandate**. Optional: Untouched scope, Discoveries, Deferrable debt, Cost, Timeline.
 
 **Reading order is act → verify → understand.** Owner half, ~20 minutes: Verdict (1) · § 1 (2) · § 2 (2) · § 3 (10, at the product) · § 4 (3) · § 5–6 (2). Successor half, read when the job arrives: § 8–14 (~10).
 
@@ -168,7 +168,7 @@ Present tense; every row true of `as_of_commit`, and every row re-provable by it
 - **§ 8 Proof.** **An unproven claim is an empty cell, never a sentence** — prose has no empty cell to scan for. `Independent?` reads `no` whenever one agent authored both the code and its pin, or found, fixed and pinned the same defect, and names who. Ledger counts are parsed from the plan, never quoted from an agent's summary, so `blocked` cannot hide inside "discharged". Every `G-n` names the command that would close it.
 - **§ 9 State.** Present tense; a claim that cannot be re-proved by its `Re-prove` command does not belong here — it moves to § 15 as a dated event. Volatile things (`/tmp`, pid files, ports, tokens, browser connections) declare a lifetime and the command that makes them durable.
 - **§ 10–12.** A loop is a runnable command or a named question, never a noun phrase and never "investigate"; one needing a person's judgment states the question and the default in force. A discovery is a present-tense fact with a guard — "Workers Builds does not fire on a `dev` merge", not "we found that it didn't"; `none — {what would hold it}` is an honest guard that feeds the backlog. Debt names where it now lives, so this file can be deleted without losing it.
-- **§ 13–14.** Every uninstrumented number reads `unmeasured — {what would have measured it}`; a blank reports a cheaper run than the one that happened. **State whether the run's own corpus is version-controlled** — an untracked corpus is one `rm -rf` from being three PR descriptions, and archiving it is a § 1 row.
+- **§ 13–14.** Every uninstrumented number reads `unmeasured — {what would measure it}`; a blank reports a cheaper run than the one that happened. **State whether the run's own corpus is version-controlled** — an untracked corpus is one `rm -rf` from being three PR descriptions, and archiving it is a § 1 row.
 - **Ids are stable and run-global** — `D-`, `G-`, `L-`, `X-`, `T-` — so a PR comment or a successor cites a row instead of re-describing it. A withdrawn row keeps its id and states what disproved it.
 - **Evidence is an address that outlives the run** — `path:line`, a 7-char sha, a PR number, a URL, or a command. A branch name is not a pointer; a `/tmp` log is not evidence — copy it into the record folder first.
 - **Blanket claims are banned.** "All suites green", "every ledger discharged", "nothing was deployed" carry a count and the sha they are true of, or they become a `G-n` row.

package/data/harnesses/code/skills/documentation/templates/implementation-map.md

@@ -1,4 +1,4 @@
-# Implementation Map (docs/operations/implementation-map.md)
+# Implementation map (docs/operations/implementation-map.md)
 
 Truth document. Use for: **the cold-start execution contract of a project being built from its documented design** — one per repo, at `docs/operations/implementation-map.md`. It is authored by the **executing session at build start**, never generated at design time: build order is derived from the repo's actual feature docs and their stated dependencies, and a design-time prediction of it goes stale the day reality disagrees. It lives in operations because it says *how to proceed*, not *what is true of the design*.
 

package/data/harnesses/code/skills/documentation/templates/migration-runbook.md

@@ -1,4 +1,4 @@
-# Migration Runbook (docs/history/migrations/YYYY-MM-DD-{slug}.md)
+# Migration runbook (docs/history/migrations/YYYY-MM-DD-{slug}.md)
 
 Record. Use for: a **one-shot** migration, upgrade, or data operation — authored before execution, executed once, then outcome-stamped and frozen. Supporting scripts live beside it in a same-named folder when needed (`YYYY-MM-DD-{slug}/`).
 

package/data/harnesses/code/skills/documentation/templates/non-goals.md

@@ -1,4 +1,4 @@
-# Non-Goals (docs/architecture/non-goals.md)
+# Non-goals (docs/architecture/non-goals.md)
 
 Truth document. Use for: what the system deliberately does **not** do. A non-goal is a decision, not an omission — each entry carries the why and what would reopen it. Readers (and agents) use this to stop re-proposing settled exclusions.
 

package/data/harnesses/code/skills/documentation/templates/operations-procedure.md

@@ -1,8 +1,8 @@
-# Operations Procedure (docs/operations/{procedure}.md)
+# Operations procedure (docs/operations/{procedure}.md)
 
 Truth document. Use for: any **recurring** procedure — development, deployment, maintenance. The one-time first run (prerequisites, install, env files, first commands, the stack) is not one of these: it has its own template and a fixed name, `templates/setup.md` → `docs/operations/setup.md`, one per repo. A procedure is consulted mid-task, not read: exact commands, copy-paste runnable, no narrative. Updated in place whenever the workflow changes.
 
-A **one-shot** procedure (a migration, an upgrade, an incident response executed once) is not an operations doc — it is a **Migration Runbook** (record, below). The test: will someone run this again next month? Yes → operations. No → runbook.
+A **one-shot** procedure (a migration, an upgrade, an incident response executed once) is not an operations doc — it is a **migration runbook** (record, `templates/migration-runbook.md`). The test: will someone run this again next month? Yes → operations. No → runbook.
 
 Required: **Goal**, **Steps**, **Verification**. Optional: Preconditions, Troubleshooting, Rollback — include only when they carry real content.
 

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

@@ -1,4 +1,4 @@
-# Package Documentation (docs/architecture/packages/{package}.md)
+# Package documentation (docs/architecture/packages/{package}.md)
 
 Truth document. Use for: **one workspace package** — one unit of distribution: a manifest, a build, a binary, a bundle, a Worker. One file per package, named for its folder.
 

package/data/harnesses/code/skills/documentation/templates/protected-files.md

@@ -1,4 +1,4 @@
-# Protected Files
+# Protected files
 
 Truth document. Use for: documenting critical files that need approval before modification.
 

package/data/harnesses/code/skills/documentation/templates/root-readme.md

@@ -1,4 +1,4 @@
-# Project Root README (/README.md)
+# Project root README (/README.md)
 
 Truth document. Use for: the repository root `/README.md`. It opens outward — what the product does, for whom, and where it runs, in a user's terms — then turns inward for the team and coding agents: what state the repo is in, how it works, what its parts are and what must not break, then routes every other question into `docs/`. The outward part comes first because it is what a stranger reads; the inward part is longer because it is what the team uses. **It hosts nothing it can link to.** It is distinct from `docs/README.md`, which describes the folders of the docs tree, and from `CLAUDE.md` / `AGENTS.md`, the standing rules an agent loads. It points at both and restates neither.
 

package/data/harnesses/code/skills/documentation/templates/security-overview.md

@@ -1,4 +1,4 @@
-# Security Overview (docs/architecture/security.md)
+# Security overview (docs/architecture/security.md)
 
 Truth document. Use for: the single place the system's security posture is stated — assets, trust boundaries, controls, and accepted risks. Controls link to the code that implements them; this doc asserts, the code proves.
 

package/data/harnesses/code/skills/documentation/templates/system-overview.md

@@ -1,4 +1,4 @@
-# System Overview (docs/architecture/system-design.md)
+# System overview (docs/architecture/system-design.md)
 
 Truth document. Use for: the bird's-eye view — what the system is, its subsystems, and how they connect. The first doc a new reader opens after the README; austere and short (two screens max). Depth lives in feature docs — this doc maps, it doesn't explain.
 

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

@@ -1,4 +1,4 @@
-# System Documentation (docs/architecture/systems/{system}.md)
+# System documentation (docs/architecture/systems/{system}.md)
 
 Truth document. Use for: **one machine that spans packages**, which a person cannot point at — the walk, the egress, the ingest, the settlement, a gate, a sweep, a door an agent calls. One file per machine, named for the machine. A thing a person navigates to is a feature document, even when it owns tables; a unit of distribution is a package document.
 

package/data/harnesses/code/skills/documentation/templates/testing-strategy.md

@@ -1,4 +1,4 @@
-# Testing Strategy (docs/architecture/common/testing.md)
+# Testing strategy (docs/architecture/common/testing.md)
 
 Truth document. Use for: the repo's test posture — what is tested at which level, how to run it, and what is deliberately untested. The framework choices come from the harness testing rule; this doc records how *this repo* applies them.