@nurix/etna 0.20.35 → 0.20.37

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
 
@@ -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. -->
 
@@ -110,12 +110,8 @@ tags: [ad]
 
 ### 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/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

@@ -1,8 +1,8 @@
-# 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`).
 
-**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

@@ -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.
 
@@ -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 closed exemption list is the `documentation` skill's `templates/changelog-entry.md`).
 
-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

@@ -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 — 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. 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.
 
@@ -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

@@ -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.
 
@@ -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

@@ -1,10 +1,15 @@
-# 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.
 
 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

@@ -1,10 +1,15 @@
-# 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.
 
 **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

@@ -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 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, 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:**
 
@@ -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 |

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**, **Decide today**, **Live-world ledger** (even when empty), **See it work**, **Decided for you**, **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).
 
@@ -31,17 +31,17 @@ prs:
 | Built | {N} units · {N} plans · ledger rows {N}, discharged {N}, blocked {N} |
 | Proof | {N} tests pass / {N} fail — on `{sha}`, verified {HH:MM} |
 | Decide today | **{N}** — § 1 |
-| Touched the live world | **{N}** acts, **{N}** you cannot undo — § 2 |
+| Touched the live world | **{N}** acts, **{N}** irreversible — § 2 |
 | Red | {N} mine · {N} pre-existing · {N} environment — § 5 |
 | See it work | {N} min — § 3 |
 | Taken alone | {N} decisions, {N} stops filed of {N} — § 4 |
 
 **Start here:** `{the one command that brings the reader's machine to the state everything below describes}`
-**If you only act on one thing:** {act} — by {YYYY-MM-DD}, or {consequence}.
+**Single most urgent act:** {act} — by {YYYY-MM-DD}, or {consequence}.
 
-## 1. Decide today
+## 1. Owner decisions due
 
-| # | Decision or act | Why today | If you say nothing | Decide by | Do it (exact) | Evidence |
+| # | Decision or act | Why today | Default on silence | Decide by | Do it (exact) | Evidence |
 | --- | --- | --- | --- | --- | --- | --- |
 | 1 | {one line, no mechanism} | {what a week costs} | {the outcome silence produces} | {date} | `{command}` / {PR link} / {UI path} | `{path:line · sha · PR}` |
 
@@ -55,19 +55,19 @@ Everything that left the repository, hardest to undo first. Verified {HH:MM}.
 
 **Did not happen, and the proof:** {claim} — `{command}`.
 
-## 3. See it work in ten minutes
+## 3. Ten-minute walkthrough
 
-**Before you start:** `{command}` · **Sign in as:** {who} · **Total:** {N} min
+**Prerequisite:** `{command}` · **Sign in as:** {who} · **Total:** {N} min
 
-| # | Do (URL → click) | You should see | It proves | If not |
+| # | Do (URL → click) | Expected result | It proves | If not |
 | --- | --- | --- | --- | --- |
 | 1 | {url} → {action} | {an observable a person can be wrong about} | {unit from § 6} | {§ 5 row, or "file it — new"} |
 
-## 4. Decided for you
+## 4. Rulings on the owner's behalf
 
 Each was taken because waiting would have stopped the run. Sorted by cost to reverse.
 
-| # | I decided | Instead of | Why | Authority | Landed at | Overturn — exact | If you say nothing | Hardens when |
+| # | Ruling | Instead of | Why | Authority | Landed at | Overturn — exact | Default on silence | Hardens when |
 | --- | --- | --- | --- | --- | --- | --- | --- | --- |
 | D-1 | {the ruling} | {the alternative, fairly} | {the constraint} | {owner said so HH:MM "…" / auto-ruled as recommended / taken alone — by {agent · model}} | `{file:line}` | `{edit or command}` | {default} | {event} |
 
@@ -85,7 +85,7 @@ Each was taken because waiting would have stopped the run. Sorted by cost to rev
 | --- | --- | --- | --- |
 | {name} | {one clause, behaviour before mechanism} | {branch · PR · release} | {suite + counts, or "driven only", or empty} |
 
-## 7. Left alone
+## 7. Untouched scope
 
 | Thing | State | Why untouched |
 | --- | --- | --- |
@@ -126,13 +126,13 @@ Present tense; every row true of `as_of_commit`, and every row re-provable by it
 | --- | --- | --- | --- | --- | --- |
 | L-1 | {present tense} | {session / owner / external} | `{command}` or {the question, with the default in force} | {id / —} | `{path:line}` |
 
-## 11. Discoveries — do not pay for these twice
+## 11. Discoveries
 
 | # | Trap | The truth | Cost paid | Guard |
 | --- | --- | --- | --- | --- |
 | X-1 | {what it looks like from outside} | {present-tense fact} | {hours / runs} | `{command}` or `none — {what would hold it}` |
 
-## 12. Debt and can wait
+## 12. Deferrable debt
 
 | # | What | Why not now | Re-open when | Parked at |
 | --- | --- | --- | --- | --- |
@@ -160,15 +160,15 @@ Present tense; every row true of `as_of_commit`, and every row re-provable by it
 ## Field rules
 
 - **Verdict (≤14 lines).** One token from the closed set — `DONE` · `DONE, NEEDS YOUR CALLS` · `PARTIAL` · `STOPPED AT BUDGET` · `FAILED` — first in the body; a paragraph before it is a format violation. The scoreboard is always the same seven rows in that order, and a zero is written `0` — `Touched the live world: 0` is one of the most valuable lines the file can carry. `Start here` is exactly one command.
-- **§ 1 Decide today (≤7 rows).** Owner-only acts, sorted by cost of deferral descending. `Do it (exact)` is a command, a link or a literal UI path — `git revert -m 1 {sha}`, never "revert the merge". `If you say nothing` is mandatory and honest. **A decision has an alternative and belongs in § 4; an act outside the repository with no alternative is a chore and belongs here.**
+- **§ 1 Owner decisions due (≤7 rows).** Owner-only acts, sorted by cost of deferral descending. `Do it (exact)` is a command, a link or a literal UI path — `git revert -m 1 {sha}`, never "revert the merge". `Default on silence` is mandatory and honest. **A decision has an alternative and belongs in § 4; an act outside the repository with no alternative is a chore and belongs here.**
 - **§ 2 Live-world ledger.** Required even when empty — `none — nothing left the repository`, with the command that proves it. Sorted hardest-to-undo first, never chronologically. `Reversible` takes three values: `no` states what now exists in the world, `with loss` names what is lost, `yes` carries the command. An act reversible only forward (redeploy, reseed, a superseding publish) is `no`, and the forward path goes in `Undo`. A backup states its expiry; copying a volatile backup somewhere durable is row 1 of § 1.
-- **§ 3 See it work (≤6 steps, ≤10 min).** Every `You should see` is an observable a person can be wrong about — a number, a named control, a status code — never "the page loads". It is the only check the owner performs with his own eyes rather than on the build's word.
-- **§ 4 Decided for you (≤10 rows).** Sorted by cost to reverse. `Authority` takes exactly three values — the owner said so (with the words and the time) · auto-ruled as recommended · taken alone — recorded per decision, never per run: it is the distinction an unattended run exists to preserve. `Overturn` is an edit or a command. `Hardens when` names the event after which reversal stops being cheap. A ruling with no reversal path is a constraint, not a decision — it moves to § 12.
+- **§ 3 Ten-minute walkthrough (≤6 steps, ≤10 min).** Every `Expected result` is an observable a person can be wrong about — a number, a named control, a status code — never "the page loads". It is the only check the owner performs with his own eyes rather than on the build's word.
+- **§ 4 Rulings on the owner's behalf (≤10 rows).** Sorted by cost to reverse. `Authority` takes exactly three values — the owner said so (with the words and the time) · auto-ruled as recommended · taken alone — recorded per decision, never per run: it is the distinction an unattended run exists to preserve. `Overturn` is an edit or a command. `Hardens when` names the event after which reversal stops being cheap. A ruling with no reversal path is a constraint, not a decision — it moves to § 12.
 - **§ 5–7.** One home per fact: a red appears in § 5 even when a decision caused it, and the decision cites the row. `Mine?` is proved by the command or stash in `Proof`; `mine` is the default when no proof is offered. § 6 leads with behaviour, not plan slugs. § 7 exists so an owner scanning the repository does not mistake somebody else's branch for the run's debris.
 - **§ 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*.
 
@@ -8,9 +8,14 @@ Truth document. Use for: **the cold-start execution contract of a project being
 - **A wave's done criterion is observable** — its plans' verification gates passed, the suite green, a named surface driveable. Never "feels complete".
 - **Authority order names this repo's own docs, most specific wins.** A contradiction between documents is repaired in the owning truth doc *before* code — never reinterpreted while planning.
 - **Plans are records, not an execution queue.** The map points at the active wave's dated plan; historical plans are read only when a truth doc cites them as provenance.
-- **Update in place as waves complete** — the map states the current build position in present tense; the journey lives in the plans and changelog entries.
+- **Update in place as waves complete** — the map names the active wave and links its plan; which waves are finished is read from their plans' `Status:`, the progress record, never restated here.
+
+```markdown
+---
+type: implementation-map
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
+---
 
-```
 # {Project} implementation map
 
 ## Cold-start contract
@@ -36,7 +41,7 @@ When documents disagree:
 | 1 | {docs/features/x.md, docs/features/y.md} | — | {observable criterion} |
 | 2 | {…} | 1 | {…} |
 
-## Current position
+## Active wave
 
-{One line per wave: complete · in progress ([plan](../history/plans/YYYY-MM-DD-slug.md)) · pending.}
+{The wave being built, linked to its open plan ([plan](../history/plans/YYYY-MM-DD-slug.md)).}
 ```

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

@@ -1,13 +1,13 @@
 # Journal (docs/history/journal.md)
 
-Record — append-only. Use for: durable mid-execution knowledge — a fact discovered while building that some owning doc will eventually carry, captured the moment it exists so it survives the session. A row is resolved by landing in its owning doc: the row is deleted and the changelog entry cites it. The file stays short by construction; a journal that only grows is a queue nobody drains.
+Queue: rows are appended, never rewritten, and deleted once resolved. Use for: durable mid-execution knowledge — a fact discovered while building that some owning doc will eventually carry, captured the moment it exists so it survives the session. A row is resolved by landing in its owning doc: the row is deleted and the changelog entry cites it. The file stays short by construction; a journal that only grows is a queue nobody drains.
 
 One line per fact. Never narrative, never progress notes (progress lives in the plan), never user preferences (those go to the runtime's memory store).
 
 ```
 # Journal
 
-Append-only capture of mid-execution knowledge — one line per fact, written the moment it exists, resolved by landing in its owning doc (delete the row, cite it in the changelog entry). Format: `YYYY-MM-DD · <area> · <one-line fact> → lands-in: <owning doc | backlog | memory>`
+Capture of mid-execution knowledge — one line per fact, written the moment it exists, resolved by landing in its owning doc (delete the row, cite it in the changelog entry). Format: `YYYY-MM-DD · <area> · <one-line fact> → lands-in: <owning doc | backlog | memory>`
 
 - YYYY-MM-DD · {area} · {one-line fact} → lands-in: {owning doc | backlog | memory}
 ```

package/data/harnesses/code/skills/documentation/templates/memory-main.md

@@ -1,6 +1,6 @@
 # Scaffold: docs/memory/main.md
 
-Baseline scaffold — created if missing (the `maintenance` agent's baseline calls this). Target file: `docs/memory/main.md`.
+Queue. Baseline scaffold, created if missing by the `maintenance` agent's baseline. Target file: `docs/memory/main.md`. Entries are appended, and retired by deletion when a document or the code comes to say the same thing, or a later entry replaces them; an entry is never edited to stay current.
 
 ```
 ---
@@ -11,7 +11,7 @@ description: Project-wide patterns and conventions confirmed in this codebase. P
 
 # Main Agent — Project Memory
 
-Append entries below, oldest at bottom. Format:
+Append entries below, newest at the bottom. Format:
 
 ## YYYY-MM-DD — {topic}
 

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}/`).