@nurix/etna 0.20.34 → 0.20.36

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

@@ -1,41 +1,68 @@
-# Documentation Templates
-
-One file per template. Every template is either a **truth document** (states current absolutes, updated in place) or a **record** (dated account of activity, frozen or append-only) — the split is defined in `SKILL.md` § The Two Natures, and each template names its nature in its opening line.
-
-| Template | File | Nature |
-| --- | --- | --- |
-| Feature (LLD) | [feature.md](feature.md) | Truth |
-| Package (one workspace package) | [package.md](package.md) | Truth |
-| Doctrine (one concern the platform handles everywhere) | [doctrine.md](doctrine.md) | Truth |
-| System (one machine spanning packages) | [system.md](system.md) | Truth |
-| Architecture Decision (AD) | [architecture-decision.md](architecture-decision.md) | Truth (Decision Changelog tail sanctioned) |
-| System overview | [system-overview.md](system-overview.md) | Truth |
-| Domain model | [domain-model.md](domain-model.md) | Truth |
-| Glossary | [glossary.md](glossary.md) | Truth |
-| Non-goals | [non-goals.md](non-goals.md) | Truth |
-| API reference | [api-reference.md](api-reference.md) | Truth |
-| Environment registry | [environment-registry.md](environment-registry.md) | Truth |
-| Security overview | [security-overview.md](security-overview.md) | Truth |
-| Testing strategy | [testing-strategy.md](testing-strategy.md) | Truth |
-| Behavioral checklist | [behavioral-checklist.md](behavioral-checklist.md) | Truth |
-| UX behavior | [ux-behavior.md](ux-behavior.md) | Truth |
-| Setup (first run, one per repo) | [setup.md](setup.md) | Truth |
-| Operations procedure | [operations-procedure.md](operations-procedure.md) | Truth |
-| Implementation map | [implementation-map.md](implementation-map.md) | Truth |
-| Bookkeeping ledger | [bookkeeping.md](bookkeeping.md) | Truth (work queue) |
-| Protected files | [protected-files.md](protected-files.md) | Truth |
-| Project root README (outward opening, then orientation and routing) | [root-readme.md](root-readme.md) | Truth |
-| docs/README.md (doc index) | [docs-readme.md](docs-readme.md) | Truth |
-| Plan | [plan.md](plan.md) | Record |
-| Changelog entry | [changelog-entry.md](changelog-entry.md) | Record |
-| Migration runbook | [migration-runbook.md](migration-runbook.md) | Record |
-| Journal | [journal.md](journal.md) | Record (append-only) |
-| CHANGELOG master index | [changelog-index.md](changelog-index.md) | Record index (append-only) |
-| Backlog | [backlog.md](backlog.md) | Record (append-only) |
-| Memory (main agent) | [memory-main.md](memory-main.md) | Record (append-only ledger) |
-
-**The `type:` enum lives here.** A doc's `type:` frontmatter takes its value from this table — one genre per template (`feature`, `architecture-decision`, `non-goals`, …). External generators consume this list rather than defining their own; a type this table does not name defaults to `docs/architecture/` placement and is never added to the protected-files list.
-
-**Baseline scaffolds** — files that must exist after every baseline (`docs/structure.md` is not among them: it is harness-owned, shipped whole by the installer and overwritten on every refresh, and has no template); the `maintenance` agent (baseline mode) creates any that are missing: [docs-readme.md](docs-readme.md), [changelog-index.md](changelog-index.md), [backlog.md](backlog.md), [memory-main.md](memory-main.md), [setup.md](setup.md) (when the repo has a lockfile and a runnable root script; never overwriting an existing first-run procedure), and [root-readme.md](root-readme.md) (never overwriting an existing root README).
-
-**Ownership.** Three genres speak for code — **feature**, **package**, **system**. A document names the objects it designs in `objects:`; a source file names the document that speaks for it in its path header; which document speaks for a path is computed from those headers and the object closure, and answered per path by the ownership index (`references/frontmatter.md`). Until the harness's ownership scan switches to that computation, it reads a transitional `owns:` region glob on each of the three genres: `packages/{name}/**` on a package document (the residual owner), a machine's subtrees on a system document, a feature's own directory on a feature document; the narrower glob wins.
+# Genre registry
+
+Every fact about a genre lives in one row of the table below: its template, its nature, its `type:` value, where it lives, the frontmatter keys it must carry and the sections it must have. `SKILL.md`, the `maintenance` agent and the shipped `docs/structure.md` name genres and defer here for these facts, and `scripts/doc-lint.mjs` reads this table to check them. The column order is a contract: the lint parses the table, and `packages/cli/tests/scripts/genreRegistry.test.mjs` in the forge fails when a row stops parsing or a template stops agreeing with it.
+
+## The three natures
+
+| Nature | Holds | Changes by | Dates | Ends |
+| --- | --- | --- | --- | --- |
+| `truth` | What is true now | Rewritten in place, present tense; no history in the body (an AD's Decision Changelog tail is the one bridge) | Frontmatter tooling keys only | Deleted, or `status: deprecated`, when its subject is gone |
+| `record` | What happened | Written while live, then frozen at its terminal status; never edited after | In the filename or header | Never; it is the archive |
+| `queue` | Work not done yet | Rows appended at the end and deleted when resolved, drained or promoted; nothing else is edited | Per row, as row metadata | Never; an empty queue is the healthy state |
+
+## Registry
+
+| Genre | Template | Nature | `type:` | Location | Required keys | Required sections |
+| --- | --- | --- | --- | --- | --- | --- |
+| Feature | [feature.md](feature.md) | truth | `feature` | `docs/features/{feature}.md` | `type` `description` `status` `objects` | Scope · Promises · For the agent |
+| Package | [package.md](package.md) | truth | `package` | `docs/architecture/packages/{package}.md` | `type` `description` `status` `objects` | Scope · Ownership · Usage · Promises · For the agent |
+| System | [system.md](system.md) | truth | `system` | `docs/architecture/systems/{system}.md` | `type` `description` `status` `objects` | Scope · Flow · Promises · For the agent |
+| Doctrine | [doctrine.md](doctrine.md) | truth | `doctrine` | `docs/architecture/common/{concern}.md` | `type` `description` `status` `objects` | The model · For the agent |
+| Architecture decision | [architecture-decision.md](architecture-decision.md) | truth | `architecture-decision` | `docs/architecture/decisions/AD-NNN-{subject}.md` | `type` `title` `description` `status` `last-updated` | Decision · Context · Consequences |
+| UX behavior | [ux-behavior.md](ux-behavior.md) | truth | `ux` | `docs/features/{surface}-ux.md` | `type` `description` `status` `objects` | Purpose · Anatomy · States · Affordances · Promises · Transitions |
+| System overview | [system-overview.md](system-overview.md) | truth | `system-overview` | `docs/architecture/system-design.md` | `type` `description` | — |
+| Domain model | [domain-model.md](domain-model.md) | truth | `domain-model` | `docs/architecture/domain-model.md` | `type` `description` | — |
+| Glossary | [glossary.md](glossary.md) | truth | `glossary` | `docs/architecture/glossary.md` | `type` `description` | — |
+| Non-goals | [non-goals.md](non-goals.md) | truth | `non-goals` | `docs/architecture/non-goals.md` | `type` `description` | — |
+| Security overview | [security-overview.md](security-overview.md) | truth | `security-overview` | `docs/architecture/security.md` | `type` `description` | — |
+| Testing strategy | [testing-strategy.md](testing-strategy.md) | truth | `testing-strategy` | `docs/architecture/common/testing.md` | `type` `description` | — |
+| API reference | [api-reference.md](api-reference.md) | truth | `api-reference` | `docs/architecture/api.md` | `type` `description` | — |
+| Environment registry | [environment-registry.md](environment-registry.md) | truth | `environment-registry` | `docs/operations/environment.md` | `type` `description` | — |
+| Behavioral checklist | [behavioral-checklist.md](behavioral-checklist.md) | truth | `checklist` | `docs/tests/{feature}.md` | `type` `description` `verifies` | — |
+| Acceptance criteria | [acceptance-criteria.md](acceptance-criteria.md) | truth | `acceptance-criteria` | `docs/acceptance/{capability}.md` | `type` `description` `status` | — |
+| Setup | [setup.md](setup.md) | truth | `operations` | `docs/operations/setup.md` | `type` `description` | Installation · First run · Verification |
+| Operations procedure | [operations-procedure.md](operations-procedure.md) | truth | `operations` | `docs/operations/{procedure}.md` | `type` `description` | Steps · Verification |
+| Implementation map | [implementation-map.md](implementation-map.md) | truth | `implementation-map` | `docs/operations/implementation-map.md` | `type` `description` | Waves · Active wave |
+| Protected files | [protected-files.md](protected-files.md) | truth | `protected-files` | `docs/operations/protected-files.md` | `type` `description` | — |
+| Docs index | [docs-readme.md](docs-readme.md) | truth | `docs-readme` | `docs/README.md` | `type` `description` | — |
+| Folder index | — | truth | `folder-index` | `docs/{folder}/Readme.md` | `type` `description` | — |
+| Changelog guide | [changelog-index.md](changelog-index.md) | truth | `changelog-guide` | `docs/history/CHANGELOG.md` | `type` `description` | — |
+| Root README | [root-readme.md](root-readme.md) | truth | — | `README.md` | — | — |
+| Plan | [plan.md](plan.md) | record | — | `docs/history/plans/YYYY-MM-DD-{slug}.md` | — | Background · Proposed Changes · Doc Obligations · Implementation Steps · Test Obligations |
+| Changelog entry | [changelog-entry.md](changelog-entry.md) | record | — | `docs/history/changelog/YYYY-MM-DD-{three-words}.md` | — | — |
+| Migration runbook | [migration-runbook.md](migration-runbook.md) | record | — | `docs/history/migrations/YYYY-MM-DD-{slug}.md` | — | — |
+| Hand-over | [handover.md](handover.md) | record | `handover` | `docs/history/handovers/YYYY-MM-DD-{slug}.md` | `type` `description` `status` | — |
+| Health log | — | record | — | `docs/history/health-log.md` | — | — |
+| Deep research | — | record | `research` | `docs/history/research/{topic}/` | — | — |
+| Brainstorm session | — | record | `brainstorm` | `docs/research/{topic}-brainstorm/` | — | — |
+| Issue | — | record | `issue` | `docs/operations/issues/YYYY-MM-DD-{slug}.md` | — | — |
+| Triage dossier | — | record | `triage` | `docs/operations/triage/YYYY-MM-DD-{slug}.md` | — | — |
+| Release note | — | record | — | `docs/operations/release-notes/YYYY-MM-DD-vX.Y.Z.md` | — | — |
+| Backlog | [backlog.md](backlog.md) | queue | — | `docs/history/backlog.md` | — | — |
+| Journal | [journal.md](journal.md) | queue | — | `docs/history/journal.md` | — | — |
+| Bookkeeping | [bookkeeping.md](bookkeeping.md) | queue | — | `docs/operations/bookkeeping.md` | — | — |
+| Project memory | [memory-main.md](memory-main.md) | queue | `project-memory` | `docs/memory/main.md` | `type` `description` | — |
+| Agent memory | — | queue | `agent-memory` | `docs/memory/{agent}.md` | — | — |
+
+- **`type:` values:** a genre's `type:` value is the one its template's skeleton carries, and two genres may share one (setup and operations procedure are both `operations`). A dash means the genre carries no frontmatter, or carries none it must have. A value this table does not name is reported by the lint as `type-unknown`.
+- **Locations:** `{name}` is one kebab-case path segment, `YYYY-MM-DD` a date, `AD-NNN` a zero-padded number. A location is where the genre lives in a repository that uses it; a folder nothing uses is absent.
+- **Required sections:** the `##` headings every document of the genre carries, by name; the template states the optional ones and when each is written. A dash means the template's sections are guidance, not a fixed set. The lint checks them on truth documents; a plan's are checked by the hooks that read it.
+- **Rows without a template:** each is written by its own tool (the `maintenance` agent's Health Log, the `brainstorm` skill, the deep-research and `issue-bridge` packs, a release pipeline) and is listed so its nature and place are settled here too.
+
+## 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`).
+
+## Baseline scaffolds
+
+The `maintenance` agent's baseline creates these when missing, from their templates: the docs index, the changelog guide, the backlog, project memory, setup (when the repo has a lockfile and a runnable root script; never a second first-run document) and the root README (never overwriting one). `docs/structure.md` is not among them: the installer ships it whole and overwrites it on every refresh.

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

@@ -1,23 +1,13 @@
 # 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.
+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.
 
 ### Rules
 
-- **Frontmatter is required**: `type: acceptance-criteria`, `status:` (`draft` → `active` →
-  `deprecated`). No `owns:` — acceptance criteria own no code.
-- **One `AC-n` key per criterion, stable forever.** Keys are never renumbered and never reused: a
-  criterion that no longer applies is marked retired in place, so every claim a past verification
-  graded still resolves.
-- **Each criterion is one observable assert**, phrased as a checkable statement about the running
-  product — never about the code's internals. If it cannot be observed from outside, it is a
-  design note, not a criterion.
-- **The `AC-n:` line grammar is load-bearing** — verification parses these lines. Keep the key at
-  line start, exactly `AC-<number>:`, followed by the assert sentence. Formatting that buries the
-  key (tables, emphasis-wrapped keys, nested bullets) breaks the parse.
+- **Frontmatter is required**: `type: acceptance-criteria`, `status:` (`draft` → `active` → `deprecated`). No `owns:` — acceptance criteria own no code.
+- **One `AC-n` key per criterion, stable forever.** Keys are never renumbered and never reused: a criterion that no longer applies is marked retired in place, so every claim a past verification graded still resolves.
+- **Each criterion is one observable assert**, phrased as a checkable statement about the running product — never about the code's internals. If it cannot be observed from outside, it is a design note, not a criterion.
+- **The `AC-n:` line grammar is load-bearing** — verification parses these lines. Keep the key at line start, exactly `AC-<number>:`, followed by the assert sentence. Formatting that buries the key (tables, emphasis-wrapped keys, nested bullets) breaks the parse.
 
 ### Template
 
@@ -32,7 +22,9 @@ status: draft
 
 Scope: {one line — what part of the product these criteria bind}.
 
-- AC-1: {observable assert about the running product}.
-- AC-2: {observable assert}.
-- AC-3 (retired): {kept verbatim, marked retired — never renumbered}.
+AC-1: {observable assert about the running product}.
+
+AC-2: {observable assert}.
+
+AC-3: (retired) {kept verbatim, marked retired — never renumbered}.
 ```

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

@@ -1,10 +1,15 @@
 # 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 **index**: request/response shapes stay in the owning feature docs; this doc answers "what exists and where is it documented." 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).
+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).
 
 Required: **Conventions**, the **route tables**. One row per live route; a route that isn't here doesn't exist.
 
-```
+```markdown
+---
+type: api-reference
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
+---
+
 # API Reference
 
 ## Conventions

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

@@ -38,20 +38,20 @@ Three sections are required: **Decision**, **Context**, **Consequences** — plu
 
 ```markdown
 ---
+type: architecture-decision
 title: "AD-NNN: Short title in sentence case"
+description: "{at most 300 characters: what this decision settles and where its boundary sits}"
 status: Accepted # Proposed | Accepted | Deprecated
-created: YYYY-MM-DD
 last-updated: YYYY-MM-DD # bump on every revision
 decision-owner: Name
 reviewers: [] # optional
-tags: [ad]
 ---
 
 # AD-NNN: Short Title
 
 ## Decision
 
-[One paragraph, active voice. "We will…" Lead with the answer — the current answer, whatever the journey was.]
+[One paragraph, third person, active voice: "The platform stores…". Lead with the answer — the current answer, whatever the journey was.]
 
 ## Context
 
@@ -65,11 +65,11 @@ tags: [ad]
 
 **Negative:**
 
-- [What becomes harder, what we accept reluctantly]
+- [What becomes harder, what is accepted reluctantly]
 
 **Risks:**
 
-- [Second-order effects you can already see, with mitigations if known]
+- [Second-order effects already visible, with mitigations if known]
 
 <!-- Optional sections below. Include only when warranted by the decision's weight. -->
 

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

@@ -1,11 +1,11 @@
 # Scaffold: docs/history/backlog.md
 
-Baseline scaffold — created if missing (the `maintenance` agent's baseline calls this). Target file: `docs/history/backlog.md`.
+Queue. Baseline scaffold, created if missing by the `maintenance` agent's baseline. Target file: `docs/history/backlog.md`. A row is appended when work is discovered and deleted when the work lands; it is never marked done in place, because the plan or changelog entry that did the work is the record.
 
 ```
 # Backlog
 
-Tracked work items, technical debt, and planned improvements. Append new items under the appropriate priority.
+Open work items, technical debt, and planned improvements — a queue. Append new items under the appropriate priority; delete an item's row when its work lands.
 
 ---
 

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

@@ -2,7 +2,7 @@
 
 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`).
 
-**Frontmatter is two keys, and `verifies:` is the load-bearing one:**
+**Frontmatter is three keys, and `verifies:` is the load-bearing one:**
 
 ```yaml
 ---
@@ -12,13 +12,7 @@ verifies: [docs/features/auth.md]          # required — the doc(s) whose promi
 ---
 ```
 
-A checklist owns no code, so it carries no `owns:`. What it carries instead is the edge back to
-its subject. **The filename convention is not the edge** — a same-named file is a coincidence a
-resolver cannot trust, it breaks the moment a checklist spans two docs or a feature is renamed, and
-it leaves nothing to implicate this file when its subject changes. Without `verifies:` a checklist
-is unreachable: no change reaches it, so it goes stale and the staleness is undetectable. Several
-values are correct where one checklist proves promises two docs decide; the inverse — which
-checklists cover a feature — is generated, never listed in the feature doc.
+A checklist owns no code, so it carries no `owns:`. What it carries instead is the edge back to its subject. **The filename convention is not the edge** — a same-named file is a coincidence a resolver cannot trust, it breaks the moment a checklist spans two docs or a feature is renamed, and it leaves nothing to implicate this file when its subject changes. Without `verifies:` a checklist is unreachable: no change reaches it, so it goes stale and the staleness is undetectable. Several values are correct where one checklist proves promises two docs decide; the inverse — which checklists cover a feature — is generated, never listed in the feature doc.
 
 **This is the driving script, and it is the source the suite is drawn from.** At the verification gate it does double duty: rung 1 drives the real surface *against these steps*, and rung 2 pins the durable subset *of these assertions* as suite tests. Writing it is therefore not a report written afterwards — it is authored or updated **before** the driving, so the gate has something to execute and the tests have something to be derived from. Which assertions earn a permanent test is decided by the `testing` skill (gate mode) § What earns a suite test, and each section records the answer on its `Pinned:` line.
 
@@ -43,18 +37,18 @@ Required: **Conventions**, at least one numbered behavior section, **Failure Rep
 # {Feature} Test Plan
 
 {What this covers, and what neighbouring checklists cover instead, with links. Close with:}
+
 Each step is an action; each **Assert** is the observable it must produce.
 
 ## Test Inputs
 
-- **URL / entry point** — where the run starts
-- **Identity** — the account or role required, and how it is obtained
-- **State** — the fixture or seeded state the run assumes, stated as counts a reader can check
+- **URL / entry point:** where the run starts
+- **Identity:** the account or role required, and how it is obtained
+- **State:** the fixture or seeded state the run assumes, stated as counts a reader can check
 
 ## Conventions
 
-- {The invariants a reader needs to interpret the assertions — the vocabulary, the scoping rule,
-  the guarantee that makes a surprising assertion correct. Not a restatement of the LLD.}
+- {The invariants a reader needs to interpret the assertions — the vocabulary, the scoping rule, the guarantee that makes a surprising assertion correct. Not a restatement of the LLD.}
 
 ---
 
@@ -80,14 +74,13 @@ Each step is an action; each **Assert** is the observable it must produce.
 
 State-based signals, never fixed sleeps:
 
-- **{Milestone}** — {the signal that proves it, as a selector or an observable}
+- **{Milestone}:** {the signal that proves it, as a selector or an observable}
 
 Timeouts: {operation} **{n}s**.
 
 ## Driving notes
 
-- {Hard-won facts about driving this surface that cost someone an hour — an environment trap, a
-  harness quirk, a signal that lies. Not general advice.}
+- {Hard-won facts about driving this surface that cost someone an hour — an environment trap, a harness quirk, a signal that lies. Not general advice.}
 
 ## Failure Report
 

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

@@ -1,6 +1,6 @@
 # Bookkeeping ledger (docs/operations/bookkeeping.md)
 
-Truth document with an unusual lifecycle: a **work queue**, not an archive. Rows are appended mechanically by the awareness hook (`auto:`) and deliberately by working sessions (`note:`), drained by the `bookkeeper` agent, and walled at Stop, at commit, and in CI. What survives in git — `waived:` and `needs-session:` rows — is exactly what a PR reviewer should see.
+Queue (`templates/Readme.md` § The three natures): a **work queue**, not an archive. Rows are appended mechanically by the awareness hook (`auto:`) and deliberately by working sessions (`note:`), drained by the `bookkeeper` agent, and walled at Stop, at commit, and in CI. What survives in git — `waived:` and `needs-session:` rows — is exactly what a PR reviewer should see.
 
 **Each wall reads the queue at its own width, and re-verifies conditions at gate time.** Stop takes the ending session's own rows, because accountability for an arc is per session. The commit gate takes only the rows **implicating that commit's staged files** — a row names the file its finding is about, and holding a commit behind rows raised by somebody else's edits is a wait nothing the committer may do can clear. CI takes every row on the branch, where there is no staged set to scope by. All three re-test each row against the repo before blocking, so a row whose condition has died walls nothing. Fail-closed cases stay repo-wide at the commit gate: a row whose grammar names no path, a `needs-session:` row, an expired waiver, and a commit staging nothing at all.
 
@@ -21,4 +21,4 @@ The shared work queue keeping documentation and code in sync — a queue, never
 
 **A waiver covers a finding only when it names the finding's kind and its subject in backticks** — the matcher (`waiverCovers`) tests the backticked subject exactly, so a waiver written without them silences nothing and the wall stands. A `waived:` row's `expires=` date is enforced: CI honors the waiver until the date, then fails. `dead-glob` waivers double as the dead-glob allowlist; `ownership-overlap` waivers cover the CI ownership check the same way.
 
-Finding kinds for `auto:`: `dead-glob` · `doc-implicated` · `doc-lint` · `header-missing` · `package-rejected` · `frozen-record-edited` · `source-lint`. The CI ownership check additionally accepts `waived:` rows of kind `ownership-overlap`.
+Finding kinds for `auto:`: `dead-glob` · `doc-implicated` · `doc-lint` · `header-missing` · `package-rejected` · `frozen-record-edited` · `source-lint`. The CI ownership check additionally accepts `waived:` rows of kind `ownership-overlap` and `dangling-edge` (a `verifies:` target that does not exist, the subject being that target's path).

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

@@ -50,7 +50,7 @@ A commit is the smallest unit an entry may describe. Above that the mapping is j
 
 ## The index
 
-Every entry appends one row to `docs/history/CHANGELOG.md` — date, link, one-line summary — in the same pass that writes the entry.
+The heading line is the entry's one-line summary, and the only one: `docs/history/CHANGELOG.md` is the folder's guide and takes no row per entry, so `grep -m1 -H '^# ' docs/history/changelog/*.md` is the index.
 
 ## Exemptions (closed list)
 

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

@@ -1,41 +1,33 @@
-# Scaffold: docs/history/CHANGELOG.md
+# Changelog guide (docs/history/CHANGELOG.md)
 
-Baseline scaffold — created if missing (the `maintenance` agent's baseline calls this). Target file: `docs/history/CHANGELOG.md`.
-
-```
-# Changelog
-
-All notable changes to {Project Name} will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+Truth document. Baseline scaffold, created if missing by the `maintenance` agent's baseline. It explains the changelog folder beside it and is never appended to: an entry is found by listing `docs/history/changelog/`, and each entry's first line is its one-line summary, so a row per entry here would be a second copy of that line that someone has to keep in step. The guide is rewritten only when the changelog's rules change.
 
+```markdown
 ---
-
-## [Unreleased]
-
-{entries added here as work proceeds; promoting them under a release heading is the one sanctioned edit to this index — the dated entry files themselves stay frozen}
-
+type: changelog-guide
+description: "How {Project Name}'s changelog works: one entry per unit of work under changelog/, what each entry records, when one is owed, and how to read the folder."
 ---
 
-## Links
+# Changelog
 
-- [Setup Guide](../operations/setup.md)
-- [Architecture](../architecture/)
+**Goal:** what changed in {Project Name}, and how it was refined, one entry per unit of work.
 
----
+## Entries
+
+- **Location:** `changelog/YYYY-MM-DD-{three-words}.md`, one file per unit of work; the three words name the work, not the commit.
+- **Summary line:** each entry opens `# {date} · {surface} — {one-line outcome}`, the line a reader scans.
+- **Content:** the ask in the user's words, what was rejected, which skills held, what changed and what running it taught (the `documentation` skill's `templates/changelog-entry.md`).
+- **Lifecycle:** a draft until its commit; frozen from then on. A correction is a new entry that links back.
 
-## How to Update This Changelog
+## Owed entries
 
-1. Create a dated change file in `docs/history/changelog/`:
-   `docs/history/changelog/YYYY-MM-DD-feature-name.md`
+- **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).
 
-2. Update this CHANGELOG.md with a high-level summary linking to the detail file
+## Reading the changelog
 
-3. Follow Keep a Changelog categories:
-   - **Added** for new features
-   - **Changed** for changes in existing functionality
-   - **Deprecated** for soon-to-be removed features
-   - **Removed** for now removed features
-   - **Fixed** for bug fixes
-   - **Security** for security improvements
+- **Newest first:** `ls -r changelog/`
+- **One line per entry:** `grep -m1 -H '^# ' changelog/*.md`
+- **One surface:** `grep -l '· {surface} —' changelog/*.md`
+- **Distilled lessons:** the `retro` agent turns accumulated entries into a punch list on demand.
 ```

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

@@ -2,7 +2,7 @@
 
 Truth document. Use for: the entry point for all documentation in a repo. Created during baseline audit.
 
-**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 — a repo carried 103 commits on `docs/README.md` before this rule, most of them row edits. 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 (`structure.md`, `operations/setup.md`, `history/CHANGELOG.md`, `history/backlog.md`) and the root `CLAUDE.md`. 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 — 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`).
 
 **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.
 
@@ -38,7 +38,7 @@ The design layer — [architecture/](architecture/): {what the folder holds —
 
 ## History
 
-[history/](history/) — the records: `plans/` (one dated plan per unit of work, frozen at completion), `changelog/` (one entry per unit of work, indexed by [CHANGELOG.md](history/CHANGELOG.md)), `migrations/` (one-shot runbooks), `brainstorms/`, `research/`, and [backlog.md](history/backlog.md).
+[history/](history/) — the records, and two queues: `plans/` (one dated plan per unit of work, frozen at completion), `changelog/` (one entry per unit of work; [CHANGELOG.md](history/CHANGELOG.md) explains how to read it), `migrations/` (one-shot runbooks), `brainstorms/`, `research/`, [backlog.md](history/backlog.md) (open work; a finished item is deleted) and `journal.md` (mid-execution facts awaiting their owning doc).
 
 ## Research and memory
 

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

@@ -24,7 +24,7 @@ Nothing else: the neighbouring documents live in **For the agent**, the one clos
 type: doctrine                                   # required tooling key
 description: "{at most 300 characters: what this document settles and where its boundary sits}" # required — the per-file account a folder is browsed by (references/frontmatter.md)
 status: active                                   # required — active | draft
-objects: [principal, credential, device grant]   # recommended — the concepts this doctrine governs, by their graph names
+objects: [principal, credential, device grant]   # required — the concepts this doctrine governs, by their graph names
 ---
 ```
 
@@ -79,4 +79,4 @@ Code cannot reveal what it does not yet do, so decided-but-unbuilt intent is one
 | A tour of the code that implements the concern | The code graph |
 | The catalog of routes, error codes or variables | An API reference or environment registry |
 | The one feature that happens to use the concern most | That feature's own document, which names this doctrine in its Scope |
-| The story of how the concern got this way | A decision record (`decisions/`) for the why, and the changelog for the when |
+| The story of how the concern got this way | The subject's architecture decision (`decisions/`), whose Decision Changelog tail carries how it moved, and the changelog for the when |

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

@@ -4,7 +4,12 @@ Truth document. Use for: the entities the system is about — what they are, how
 
 Required: **Entities**, **Relationships**. Optional: Lifecycle states, Invariants.
 
-```
+```markdown
+---
+type: domain-model
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
+---
+
 # Domain Model
 
 ## Entities
@@ -15,14 +20,14 @@ Required: **Entities**, **Relationships**. Optional: Lifecycle states, Invariant
 
 ## Relationships
 
-- {EntityA} 1—N {EntityB} — {the meaning of the link}
-- {EntityB} N—N {EntityC} via {join} — {meaning}
+- **{EntityA} 1—N {EntityB}:** {the meaning of the link}
+- **{EntityB} N—N {EntityC} via {join}:** {meaning}
 
 ## Lifecycle states
 
 {Only for entities with real state machines.}
 
-- **{Entity}**: draft → active → archived — {what moves it between states}
+- **{Entity}:** draft → active → archived, moved by {what moves it between states}
 
 ## Invariants
 

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

@@ -4,7 +4,12 @@ Truth document. Use for: the config surface — every variable the code reads, i
 
 **Placeholders only, never real values.** A real-looking password, account ID, or personal profile name in a doc is a leak, and one developer's local setup written as the canonical value is a trap for everyone else. Values in this doc are `{placeholder}` descriptions.
 
-```
+```markdown
+---
+type: environment-registry
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
+---
+
 # Environment Registry
 
 Every variable the code reads. `.env.example` mirrors this list.

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

@@ -8,7 +8,7 @@ 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 computed from the source headers and the object closure, never listed (`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 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.
 
 **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.
 
@@ -19,7 +19,7 @@ The frontmatter names the objects the feature designs; which files it speaks for
 | Frontmatter | required |
 | Goal line | required |
 | `Scope` | required |
-| `Flows` | required |
+| `Flows` | required once `status: active`; omitted at `draft`, before there is a shipped surface to describe |
 | `Decisions` | once any choice was made that the code cannot explain |
 | `Promises` | required |
 | `Gaps` | only when there is one |
@@ -64,7 +64,7 @@ owns: ["packages/studio/src/server/devices/**"]   # transitional — one region
 
 ### {Theme as a noun phrase — e.g. "Sign-in failures", "Gate outcomes", "Terminal grant states"}
 
-{A table where the cases are parallel states — | Situation | What the person sees | — carrying the exact wording where the wording is promised. Bullets otherwise:}
+{A table where the cases are parallel states — | Situation | Outcome | — carrying the exact wording where the wording is promised. Bullets otherwise:}
 
 - **{Noun-phrase label}:** {the guarantee or refusal, checkable by a person or a test.}
 
@@ -79,7 +79,7 @@ owns: ["packages/studio/src/server/devices/**"]   # transitional — one region
 - **Commands:** {`nustack …`}
 - **Code roots:** {`packages/…/src/…/`}, directories where the graph should start
 - **Seams:** {`name`}, only where the roots would not lead to them
-- **Checklist:** `tests/{feature}.md`
+- **Checklist:** `docs/tests/{feature}.md`, once the verification gate has written it
 - **See also:** {neighbour}: {why}
 
 No tables, routes or symbol rosters — those are the graph's.

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

@@ -2,7 +2,12 @@
 
 Truth document. Use for: the project's vocabulary — one name per concept, one line per name. Alphabetical. When the code uses a different name than the docs, record it in **In code** so readers can bridge; one concept never gets two doc names.
 
-```
+```markdown
+---
+type: glossary
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
+---
+
 # Glossary
 
 | Term | Meaning | In code |