@nurix/etna 0.20.34 → 0.20.36

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: Left alone, Discoveries, 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,10 +160,10 @@ 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.

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

@@ -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/non-goals.md

@@ -2,10 +2,15 @@
 
 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.
 
-```
+```markdown
+---
+type: non-goals
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
+---
+
 # Non-Goals
 
 Things this system deliberately does not do. Each is a decision — don't re-propose one without new information of the kind its "revisit if" names.
 
-- **{Non-goal}** — {why it's excluded}. Revisit if: {the trigger that would reopen it}.
+- **{Non-goal}:** {why it's excluded}. Revisit if: {the trigger that would reopen it}.
 ```

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

@@ -8,7 +8,12 @@ Required: **Goal**, **Steps**, **Verification**. Optional: Preconditions, Troubl
 
 If a procedure is a deterministic command list run frequently, script it and have the doc point at the script — a doc should carry judgment (when, why, what to check), not replace automation.
 
-```
+```markdown
+---
+type: operations
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
+---
+
 # {Procedure Name}
 
 **Goal:** What this procedure accomplishes, one line.

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

@@ -6,7 +6,7 @@ Truth document. Use for: **one workspace package** — one unit of distribution:
 
 **A package document's deepest layer is its public contract** (`references/style-guide.md` § Shape — the model first, the detail after): the commands and flags a person types, the exports another package imports, what is installed and where. For a CLI the flags *are* the promise, so they belong in Usage. It stops before internal layout, build steps and which file holds what.
 
-**A package document is the residual owner of its own tree.** Every file in the package whose header names no narrower document is its to speak for, so it loses to every system or feature document a header names. Until the ownership scan switches to header pointers, its transitional `owns:` is the whole package glob. The one enumerable fact it declares is the ownership table: which subtrees other documents speak for.
+**A package document is the residual owner of its own tree.** Every file in the package whose header names no narrower document is its to speak for, so it loses to every system or feature document a header names. Until the ownership scan switches to header pointers, its transitional `owns:` is the whole package glob. Which subtrees narrower documents speak for is computed from their headers, never tabled here.
 
 **Sharp, bulleted, labelled with noun phrases** (`references/style-guide.md` § Labels). Every section after the goal line is bullets under a noun-phrase heading, each bullet a bold noun-phrase label followed by one or two sentences.
 
@@ -15,7 +15,7 @@ Truth document. Use for: **one workspace package** — one unit of distribution:
 | Section | When |
 | --- | --- |
 | `Scope` | required. Why the package is its own unit, who consumes it, and what it deliberately does not hold |
-| `Ownership` | required, as one line or a table |
+| `Ownership` | required, as one line |
 | `Usage` | required |
 | `Decisions` | once any choice was made that the code cannot explain |
 | `Promises` | required |
@@ -49,11 +49,7 @@ owns: ["packages/{name}/**"]                     # transitional — the residual
 
 ## Ownership
 
-This document is the residual owner of `packages/{name}/**`. Claimed at higher specificity:
-
-| Subtree | Stated and owned by |
-| --- | --- |
-| `src/{machine}/**` | [{system}](../systems/{system}.md) |
+This document is the residual owner of `packages/{name}/**`; a subtree whose files' headers name a system or feature document is that document's.
 
 ## Usage
 
@@ -77,7 +73,7 @@ This document is the residual owner of `packages/{name}/**`. Claimed at higher s
 - **Commands and exports:** {…} — the public contract
 - **Code root:** `packages/{name}/`
 - **Seams:** {…} by name
-- **Checklist:** `tests/{package}.md`
+- **Checklist:** `docs/tests/{package}.md`
 - **See also:** {neighbour}: {why}
 
 No file lists or symbol rosters — those are the graph's.

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

@@ -8,7 +8,7 @@ The `boundary` skill parses the **Proposed Changes** sections to check boundary
 
 **Doc Obligations is the one ledger the plan's author writes.** Deriving tests from behavior is judgment, which is why `testing` owns that section and it is marked never-hand-author; resolving Proposed Changes' file paths to the feature docs that own them is a **lookup** against the ownership index already injected at session start. Different work, different rule — fill it yourself, while the touch list is fresh.
 
-The **`Gates:`** line carries two machine-read segments. The compliance hook greps **`Boundary:`** — implementation edits inside the plan's scope are blocked while it reads `Boundary: pending`; the `boundary` skill rewrites it to `Boundary: passed YYYY-MM-DD` or `Boundary: blocked YYYY-MM-DD`. The other two plan gates are enforced by **section presence**: a plan with no `## Test Obligations` or no `## Doc Obligations` section blocks the same edits — the sections are the artifacts, and the gate derives from them, not from a claim about them. A **`Polygraph:`** segment appears only when the user has the `polygraph` agent audit the plan's documents — it appends `Polygraph: passed YYYY-MM-DD (N docs · N claims · N corrected · N registered)`, or `Polygraph: pending` while an owner question is open. It is a trace for readers, never an obligation: a plan carries none by default, no hook or CI check reads it, and it is never hand-written. Never hand-edit the line to skip a gate.
+The **`Gates:`** line carries one machine-read segment. The compliance hook greps **`Boundary:`** and blocks implementation edits inside the plan's scope until it reads `passed`: `Boundary: pending` has no verdict yet and `Boundary: blocked` is a verdict against coding, so both wall. The `boundary` skill rewrites it to `Boundary: passed YYYY-MM-DD` or `Boundary: blocked YYYY-MM-DD`; a blocked plan folds the amendments and re-runs the skill. The other two plan gates are enforced by **section presence**: a plan with no `## Test Obligations` or no `## Doc Obligations` section blocks the same edits — the sections are the artifacts, and the gate derives from them, not from a claim about them. A **`Polygraph:`** segment appears only when the user has the `polygraph` agent audit the plan's documents — it appends `Polygraph: passed YYYY-MM-DD (N docs · N claims · N corrected · N registered)`, or `Polygraph: pending` while an owner question is open. It is a trace for readers, never an obligation: a plan carries none by default, no hook or CI check reads it, and it is never hand-written. Never hand-edit the line to skip a gate.
 
 ```
 # {Feature Name}
@@ -51,12 +51,11 @@ Why this work is happening *now*. Link to the spec for *what* we're building; th
 ## Doc Obligations
 
 <!-- One row per feature doc whose `owns:` globs intersect the Proposed Changes above — resolve
-     them against the injected ownership index. Hand-authored: this is a lookup, not research.
-     Amendable while the plan is open; discharged at Completion. -->
+     them against the injected ownership index. Hand-authored: this is a lookup, not research. Amendable while the plan is open; discharged at Completion. -->
 
-| Doc | Claim that changes | `owns:` still accurate? | Outcome |
+| Doc | Claim that changes | Still the owning doc? | Outcome |
 | --- | --- | --- | --- |
-| `docs/features/{feature}.md` | what it says today that this plan makes false | yes / no — new paths to add | written empty; discharged at Completion — **updated** / **owes nothing** (with the reason) / **blocked** (→ backlog) |
+| `docs/features/{feature}.md` | what it says today that this plan makes false | yes / no — the document the changed files' headers should name | written empty; discharged at Completion — **updated** / **owes nothing** (with the reason) / **blocked** (→ backlog) |
 
 **"None" is valid** — a plan touching only unowned paths owes no doc update, and says so explicitly. It is not a free pass: `boundary` builds its own touch list from the same Proposed Changes and reports docs this table missed.
 
@@ -69,12 +68,7 @@ Why this work is happening *now*. Link to the spec for *what* we're building; th
 ## Test Obligations
 
 <!-- Written by the `testing` skill (plan-gate mode) at the plan gate (after `boundary`). One row per
-     promised behavior: layer · target file · oracle · fixtures · an empty Outcome cell the
-     verification gate fills (satisfied / owes nothing / blocked → backlog). Amendable while the
-     plan is open. Do not hand-author. NEVER put a pipe in a ledger cell, escaped or not — the
-     compliance hook splits rows on `|` at a fixed column index with no unescaping, so a
-     markdown-legal `\|` shifts every later cell and the wall blocks a row that is in fact
-     discharged. Write "`install` or `update`", not "`install \| update`". -->
+     promised behavior: layer · target file · oracle · fixtures · an empty Outcome cell the verification gate fills (satisfied / owes nothing / blocked → backlog). Amendable while the plan is open. Do not hand-author. A literal pipe in a cell is written `\|`; an unescaped one adds a column and shifts every later cell. Prefer "`install` or `update`" to escaping. -->
 
 ## Open Questions
 

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

@@ -4,7 +4,12 @@ Truth document. Use for: documenting critical files that need approval before mo
 
 This doc answers *what is protected and why breaking it hurts* — nothing more. Don't duplicate function-level detail here (signatures, inputs/outputs): it drifts from both the code and the owning feature doc. The owning feature doc is the canonical reference for how the code works; link to it.
 
-```
+```markdown
+---
+type: protected-files
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
+---
+
 # Protected Files
 
 Critical files requiring approval before modification.

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

@@ -13,7 +13,7 @@ Sections come in this order; 1 to 3 are the outward-facing first screen, 4 onwar
 5. **State.** Optional: a one-line blockquote, present only while something repo-wide is true that a newcomer must know (frozen, mid-migration, mid-breaking-change on `dev`). It links the plan or runbook that owns the change. Say here which units publish and where, if any do.
 6. **The main path.** Three to six short paragraphs, or numbered stages, along the main request or data path: who arrives, what is built, where state lives, how the result leaves. Name a technology only where it explains a stage. End with a link to the system overview.
 7. **Repository map.** A sentence on how the tree is organised, then one table row per top-level unit (package, app, service), giving its path, what it is in one line, and its owning doc; the top folders that are not packages get a sentence each. This replaces the tree.
-8. **Rules that bite.** Optional. At most five one-line invariants, public/internal boundaries, never-edit paths (generated, protected) or non-goals, each linked to the doc that argues it.
+8. **Load-bearing rules.** Optional. At most five one-line invariants, public/internal boundaries, never-edit paths (generated, protected) or non-goals, each linked to the doc that argues it.
 9. **Destinations.** An intent-to-destination table. Its last row is the one for agents.
 10. **Everyday commands.** Optional. At most four commands run on every change, ending at the gate a push must pass. First-run commands are never here.
 
@@ -31,11 +31,11 @@ Sections come in this order; 1 to 3 are the outward-facing first screen, 4 onwar
 
 ### Writing rules
 
-- **Budget: between 60 and 140 non-blank lines, the outward part under a third of it.** Prose is welcome — The main path and Rules that bite read better as paragraphs than as rows — but past the ceiling a section is hosting content that belongs in a doc. Move it and leave the link.
+- **Budget: between 60 and 140 non-blank lines, the outward part under a third of it.** Prose is welcome — The main path and Load-bearing rules read better as paragraphs than as rows — but past the ceiling a section is hosting content that belongs in a doc. Move it and leave the link.
 - **Every section is either a fact the reader acts on or a link.** If a section needs a paragraph, it needs a doc.
 - **One H1, then H2 sections, in plain Markdown.** Sentence-case headings, no emoji, no HTML layout, and no `#` comment lines inside code blocks (they parse as H1s).
 - **Relative links into the repo only.** Never an absolute repo URL. Never an external site as the home of a canonical doc.
-- **Link folders and mandated scaffolds, never rosters.** The allowed targets are folders, `docs/README.md`, `docs/structure.md`, `docs/operations/setup.md`, `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `CLAUDE.md` and the owning docs in the Map. A procedure is named only where a Destinations row needs it. Every heading and table header is a noun phrase (`../references/style-guide.md` § Labels). Never list individual feature docs: the ownership index finds them.
+- **Link folders and mandated scaffolds, never rosters.** The allowed targets are folders, `docs/README.md`, `docs/structure.md`, `docs/operations/setup.md`, `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `CLAUDE.md`, `AGENTS.md` and the owning docs in the Map. A procedure is named only where a Destinations row needs it. Every heading and table header is a noun phrase (`../references/style-guide.md` § Labels). Never list individual feature docs: the ownership index finds them.
 - **No tree.** The Map stops at top-level units and never lists files. Mark paths that look primary but are not, for example "`legacy/`: reference only, never edited".
 - **The Map is a coarse view of the ownership index, not a rival to it.** The Owning doc column names the doc the index resolves for that path. When the two disagree the index wins, and the Map row is fixed in the same change.
 - **No version numbers and no dates.** Name the file that pins a version (`.nvmrc`, `packageManager`, `rust-toolchain.toml`). Write in the present tense, with no "coming soon" and no "as of".
@@ -90,7 +90,7 @@ The rest of this page is for the team and for coding agents working in this repo
 
 {One sentence each for the top folders that are not packages — `registry/`, `scripts/`, `docs/` — with their owning doc.} Where every doc lives: [docs/structure.md](docs/structure.md).
 
-## Rules that bite
+## Load-bearing rules
 
 {One sentence saying these are stated here and argued in the documents they point at.}
 

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

@@ -4,7 +4,12 @@ Truth document. Use for: the single place the system's security posture is state
 
 Required: **Trust boundaries**, **Controls**. Optional: Assets, Accepted risks.
 
-```
+```markdown
+---
+type: security-overview
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
+---
+
 # Security Overview
 
 ## Assets
@@ -13,7 +18,7 @@ Required: **Trust boundaries**, **Controls**. Optional: Assets, Accepted risks.
 
 ## Trust boundaries
 
-- {Boundary} — {what crosses it, and what checks the crossing} 
+- **{Boundary}:** {what crosses it, and what checks the crossing} 
 
 ## Controls
 
@@ -23,5 +28,5 @@ Required: **Trust boundaries**, **Controls**. Optional: Assets, Accepted risks.
 
 ## Accepted risks
 
-- {Risk knowingly carried} — accepted because {reason}; owner: {who}. Revisit if: {trigger}.
+- **{Risk knowingly carried}:** accepted because {reason}; owner: {who}. Revisit if: {trigger}.
 ```

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

@@ -4,7 +4,7 @@ Truth document, operations genre (`type: operations`). Use for: **the one-time p
 
 It is distinct from `local-development.md`, the daily loop: watch modes, resetting state, per-package traps, the inner test cycle. Setup runs once per machine. Local development runs every session. Setup ends by handing off to it, and neither copies the other. Deploying is `deployment.md`.
 
-Required: **Goal**, **Stack**, **Prerequisites**, **Install**, **First run**, **Verify**. Optional, included only with real content: the audience fork, **Before cloning**, **Environment files**, **Local services**, **Reset**, **Common failures**.
+Required: **Goal**, **Stack**, **Prerequisites**, **Installation**, **First run**, **Verification**. Optional, included only with real content: the audience fork, **Before cloning**, **Environment files**, **Local services**, **Reset**, **Common failures**.
 
 ### Writing rules
 
@@ -32,7 +32,7 @@ description: "{at most 300 characters: what this document settles and where its
 
 **Goal:** take a fresh machine from clone to a verified first run of {what runs: e.g. "the product Worker on :{port} and the web shell on :{port}, signed in as the dev fixture"}. Done once per machine; the daily loop is [`local-development.md`]({local-development}.md).
 
-{Optional audience fork: "Only running {the CLI / one package}? Stop after Install and see [`{procedure}`]({path})."}
+{Optional audience fork: "Only running {the CLI / one package}? Stop after Installation and see [`{procedure}`]({path})."}
 
 ## Stack
 
@@ -59,7 +59,7 @@ Why these were chosen: [{system overview}](../architecture/{overview}.md).
 
 - **{Trap}:** {what a fresh clone hits and the one command that clears it, e.g. `git lfs install`, `git submodule update --init`}.
 
-## Install
+## Installation
 
 \`\`\`bash
 git clone {url} && cd {repo}
@@ -103,7 +103,7 @@ The contract is [`{example file or typed Env}`](../../{path}). Read it before co
 
 4. Open `{http://localhost:port}` and {sign in as `{seeded user}` / reach `{first screen}`}.
 
-## Verify
+## Verification
 
 - `{curl -fsS http://localhost:{port}/{health}}` returns `200` {and `{body}`}.
 - `{doctor or status command}` reports {expected}. ← keep whichever exists
@@ -130,9 +130,9 @@ The baseline scaffolds `docs/operations/setup.md` when it is missing and the rep
 
 - **Stack:** from the workspace manifests, one row per layer.
 - **Prerequisites:** from the pinning files.
-- **Install and First run:** from the root README's getting-started block (if one exists) and the root scripts.
+- **Installation and First run:** from the root README's getting-started block (if one exists) and the root scripts.
 - **Environment files:** from every `*.example` / `.dev.vars.example` in the workspace.
-- **Verify:** from a health route, a doctor command or the test script.
+- **Verification:** from a health route, a doctor command or the test script.
 
 It leaves Common failures empty until a failure is root-caused, and it drops every section it cannot fill concretely.
 

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

@@ -2,12 +2,17 @@
 
 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.
 
-Required: **What this is**, **Subsystem map**. Optional: Key flows, Where the truth lives.
+Required: **Purpose**, **Subsystem map**. Optional: Key flows, Sources of truth.
+
+```markdown
+---
+type: system-overview
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
+---
 
-```
 # System Overview
 
-## What this is
+## Purpose
 
 {Two or three sentences: what the system does, for whom, in what environment it runs.}
 
@@ -18,13 +23,13 @@ Required: **What this is**, **Subsystem map**. Optional: Key flows, Where the tr
 └──────────┘     └──────────┘     └──────────┘
 {One box per subsystem; label the arrows with the contract that crosses them.}
 
-- **{Subsystem}** — one line: what it owns. → [owning doc](../features/{feature}.md)
+- **{Subsystem}:** what it owns, in one line. → [owning doc](../features/{feature}.md)
 
 ## Key flows
 
-{At most two or three ASCII flow diagrams for the flows everything else hangs off — request lifecycle, auth, the core domain operation.}
+{At most two or three mermaid flow diagrams, at role level, for the flows everything else hangs off: request lifecycle, auth, the core domain operation.}
 
-## Where the truth lives
+## Sources of truth
 
 | Area | Canonical doc |
 | ---- | ------------- |

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

@@ -69,7 +69,7 @@ owns:                                            # transitional — region globs
 - **Objects:** {…}
 - **Code roots:** {…} — directories, one per package the machine spans
 - **Seams:** {…} by name
-- **Checklist:** `tests/{system}.md`
+- **Checklist:** `docs/tests/{system}.md`
 - **See also:** {neighbour}: {why}
 
 No tables, routes or symbol rosters — those are the graph's.

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

@@ -1,10 +1,15 @@
-# Testing Strategy (docs/tests/strategy.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.
 
-Required: **Levels**, **Running**. Optional: Deliberately untested, Adding a test.
+Required: **Levels**, **Commands**. Optional: Deliberately untested, New tests.
+
+```markdown
+---
+type: testing-strategy
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
+---
 
-```
 # Testing Strategy
 
 ## Levels
@@ -14,7 +19,7 @@ Required: **Levels**, **Running**. Optional: Deliberately untested, Adding a tes
 | Unit / integration | {runner} | `tests/` | {what} |
 | E2E | {runner} | `e2e/` | {what} |
 
-## Running
+## Commands
 
 - `{pm} test` — the whole unit suite (CI gate)
 - `{pm} run test:e2e` — {when to run}
@@ -23,7 +28,7 @@ Required: **Levels**, **Running**. Optional: Deliberately untested, Adding a tes
 
 - {Area} — {why, and what verifies it instead (typecheck, boot check, manual journey)}
 
-## Adding a test
+## New tests
 
 1. {Where the file goes, what it's named, where fixtures live}
 ```

package/data/harnesses/code/skills/documentation/templates/ux-behavior.md

@@ -4,6 +4,17 @@
 
 **`type: ux`**, plus `status:` and `objects:` — the objects the surface presents (`references/frontmatter.md`). The doctrine it answers to (the state vocabulary, the routing doctrine, the information architecture) is named in its Purpose for people and computed through shared objects for tooling.
 
+```yaml
+---
+type: ux
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
+status: active                    # draft until the surface it decides is built
+objects: [workspace, run]         # the objects the surface presents
+owns:                             # transitional, only when this document speaks for the surface's components (references/frontmatter.md)
+  - packages/{pkg}/src/{surface}/**
+---
+```
+
 **Why this genre exists.** A feature doc (LLD) states what a feature is, how its data flows, and which contracts it honours — all of which stay plausibly true through a rewrite of the surface. Nothing else in the repo states what a person *observes*. So a change to the wire lands, the interface absorbs it, and the absorption reads as maintenance: no test fails, no lint fires, no document is contradicted. This document is the thing a silent change contradicts.
 
 **Not a test plan.** `docs/tests/{feature}.md` records that behavior was driven and holds `Pinned:` traces; this document *decides* the behavior it later verifies. Written after the code, it is a transcript. Write it first.
@@ -15,9 +26,9 @@
 | One surface's — a panel, an editor, a dialog | `docs/features/{surface}-ux.md`; its component files' headers name it |
 | Cross-cutting — routing, information architecture, the state vocabulary every surface obeys, presentation of streams | `docs/architecture/` — owns no code, like every architecture doc |
 
-**Ownership: a component file names one document in its header.** A surface's components are frequently already spoken for — by the page's feature document, by the feature behind one panel — and a file's header names exactly one document. Where the header already names the feature document, this document is named in that feature document's **coordinated edits** row instead, phrased as *different promises over the same files*, and the object closure links the two through the objects both name. Where no document speaks for the component yet, its header names this one.
+**Ownership: a component file names one document in its header.** A surface's components are frequently already spoken for — by the page's feature document, by the feature behind one panel — and a file's header names exactly one document. Where the header already names the feature document, this document is named in that feature document's **See also** line under For the agent instead, phrased as *different promises over the same files*, and the object closure links the two through the objects both name. Where no document speaks for the component yet, its header names this one.
 
-That matters because a doc nothing implicates is a doc that rots, and a surface rewritten under an unimplicated document is the failure this genre exists to prevent. The coordinated-edit row is the weaker of the two bindings; prefer the header pointer wherever no document speaks for the component yet.
+That matters because a doc nothing implicates is a doc that rots, and a surface rewritten under an unimplicated document is the failure this genre exists to prevent. The See also line is the weaker of the two bindings; prefer the header pointer wherever no document speaks for the component yet.
 
 ---
 

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

@@ -183,6 +183,6 @@ Runs as the tail of every build pass — the session opens it the moment the uni
 5. **Discharge every ledger row into exactly one outcome**: **satisfied** (test green, or driven check passed), **owes nothing** (with the reason — compiler-guarded, covered elsewhere), or **blocked** (missing infrastructure named, row converted to a backlog item). **Open by re-reading the ledger from the plan file on disk, never from conversation memory** — a context-held copy is how rows get missed. **Write each row's outcome into its `Outcome` cell in the plan file** — exactly `satisfied`, `owes nothing — {reason}`, or `blocked → backlog` — because the Stop wall and CI read that cell, and a row left unexamined blocks completion.
 6. **Report results honestly, including failures**; record which test now guards each checklist section (`Pinned:` traces) and each section's `AC:` line where the repo carries a keyed acceptance-criteria source, closing with the coverage count — `AC coverage: {n}/{m}; uncovered: {keys} → backlog`.
 
-   **Record every section you drove — in the changelog entry, not in the checklist.** One line per section: what was driven, PASS or FAIL, the environment, and the evidence the assertion turned on (the literal observed, the row version, the request body). It goes in the entry because it is a dated event, and the checklist is a truth document that carries no dates (the `documentation` skill § Present tense, always). **A `FAIL` is recorded as a `FAIL` and stays** — with the backlog item it raised — because a corpus of driven records that has never recorded a failure is either describing a flawless product or being written by someone who already knew the answer, and a reader cannot tell which. In the checklist itself, the section's `Pinned:` trace is what distinguishes a verified promise from a typed one; a section the drive could not reach says `not reachable — {what blocks it}` there, so an unexamined section and a guarded one never look alike.
+   **Record every section you drove — in the changelog entry, not in the checklist.** One line per section: what was driven, PASS or FAIL, the environment, and the evidence the assertion turned on (the literal observed, the row version, the request body). It goes in the entry because it is a dated event, and the checklist is a truth document that carries no dates (the `documentation` skill § The three natures). **A `FAIL` is recorded as a `FAIL` and stays** — with the backlog item it raised — because a corpus of driven records that has never recorded a failure is either describing a flawless product or being written by someone who already knew the answer, and a reader cannot tell which. In the checklist itself, the section's `Pinned:` trace is what distinguishes a verified promise from a typed one; a section the drive could not reach says `not reachable — {what blocks it}` there, so an unexamined section and a guarded one never look alike.
 
    Completion steps — freezing the plan, the changelog entry — are the root policy file's, not yours.

package/data/harnesses/delivery/CLAUDE.md

@@ -83,7 +83,7 @@ Three peer modes plus a Completion step — enter wherever the user's thinking a
 
 ## Changelog
 
-The working session is the last holder of the refinement context that produced a prompt: the variants rejected, the eval deltas, the escalations and why. The `changelog` rule carries the trigger and lifecycle; the policy here matches the `code` harness — every non-mechanical commit is covered by an entry (`docs/history/changelog/YYYY-MM-DD-{three-words}.md` + a `docs/history/CHANGELOG.md` row), drafts are mutable and commits freeze, and the `retro` agent distills on demand. Two genres are load-bearing for this harness:
+The working session is the last holder of the refinement context that produced a prompt: the variants rejected, the eval deltas, the escalations and why. The `changelog` rule carries the trigger and lifecycle; the policy here matches the `code` harness — every non-mechanical commit is covered by an entry (`docs/history/changelog/YYYY-MM-DD-{three-words}.md`; `docs/history/CHANGELOG.md` is the guide and takes no row), drafts are mutable and commits freeze, and the `retro` agent distills on demand. Two genres are load-bearing for this harness:
 
 - **Escalation entries** (`Class: escalation`, written by the `escalate` skill) — the raw data for routing-table tuning.
 - **Prompt refinement entries** — rejected variants and eval deltas quoted with the same discipline the template's failure fields demand.

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

@@ -122,8 +122,8 @@ Stop is facilitator-orchestrated because approval belongs to the user; you execu
    ledger and thesis. Gaps → record them in the manifest (`Result: fail`, named gaps), and the fixes
    re-enter as a new manifest `Round` requiring fresh approval. Pass → record it.
 4. **Move.** Run `--gate=move`. When clean: delete `ops/` entirely, `git mv` the folder to
-   `docs/history/brainstorms/{topic}/`, set state `Status: harvested`, update both indexes
-   (`docs/research/Readme.md` row out, `docs/history/brainstorms/Readme.md` row in). End your
+   `docs/history/brainstorms/{topic}/`, set state `Status: harvested` (no index row to move: the folder is
+   the record). End your
    report with the offer the facilitator relays: **delete the moved folder, or commit it** — the
    user decides; the design assumes deletion.
 

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

@@ -21,7 +21,7 @@ Map the documentation landscape — what exists, what is adjacent, how detailed
 2. Locate the repo's feature-doc layer from `structure.md` — the standard shape is `./docs/features/`, but a repo may document components under their own subject folders. Read that layer's index if it has one; otherwise glob for docs carrying `owns:` frontmatter
 3. If `./docs/memory/lld-mode.md` exists (or the legacy `./docs/memory/spec-mode.md`), read it for feature doc inventory, ownership conflict zones, and lessons from previous research
 4. Read 1-2 existing feature LLDs from that layer to calibrate format and depth
-5. Consult the **injected ownership index** (the generated `glob → doc · module · objects · status` map — computed from source headers and the transitional `owns:` region globs) to build the ownership map. It is the source of truth for what code paths are already spoken for; a source file's path header names its document directly. If the index isn't present in context, glob the docs tree (excluding `docs/history/`) and read the `owns:` frontmatter of every doc that declares it.
+5. Consult the **injected ownership index** (the generated `glob → doc · module · objects · status` map, built from the transitional `owns:` region globs; a source file's path header names its document directly) to build the ownership map. It is the source of truth for what code paths are already spoken for; a source file's path header names its document directly. If the index isn't present in context, glob the docs tree (excluding `docs/history/`) and read the `owns:` frontmatter of every doc that declares it.
 
 ## What You Research
 
@@ -46,7 +46,7 @@ Structure your findings as:
 - **Invalidated claims**: One row per existing doc this feature makes wrong — doc path, the claim, why it stops being true. This list seeds the plan's **Doc Obligations** ledger, so it is the research finding most likely to survive into an artifact; "none" is a real answer and says the feature is genuinely additive.
 - **Risks or concerns**: Anything the LLD should address or call out
 
-Structure your findings by the `documentation` skill's style guide — imperative voice, function signatures over implementations, mermaid for flows.
+Write each finding as a bold noun-phrase label and one or two third-person sentences (the `documentation` skill's `references/style-guide.md` § Labels, § Voice); mermaid for a flow worth drawing. Paths, symbols and routes belong in these findings because the author needs them, but these fields are research, not the LLD's sections: the feature doc takes its template's sections and names objects and promises, never the functions listed here.
 
 ## Rules