@nurix/etna 0.20.35 → 0.20.37

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

@@ -1,11 +1,16 @@
-# Non-Goals (docs/architecture/non-goals.md)
+# Non-goals (docs/architecture/non-goals.md)
 
 Truth document. Use for: what the system deliberately does **not** do. A non-goal is a decision, not an omission — each entry carries the why and what would reopen it. Readers (and agents) use this to stop re-proposing settled exclusions.
 
-```
+```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/delivery/skills/documentation/templates/operations-procedure.md

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

@@ -1,4 +1,4 @@
-# Package Documentation (docs/architecture/packages/{package}.md)
+# Package documentation (docs/architecture/packages/{package}.md)
 
 Truth document. Use for: **one workspace package** — one unit of distribution: a manifest, a build, a binary, a bundle, a Worker. One file per package, named for its folder.
 
@@ -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/delivery/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/delivery/skills/documentation/templates/protected-files.md

@@ -1,10 +1,15 @@
-# Protected Files
+# Protected files
 
 Truth document. Use for: documenting critical files that need approval before modification.
 
 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/delivery/skills/documentation/templates/root-readme.md

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

@@ -1,10 +1,15 @@
-# Security Overview (docs/architecture/security.md)
+# Security overview (docs/architecture/security.md)
 
 Truth document. Use for: the single place the system's security posture is stated — assets, trust boundaries, controls, and accepted risks. Controls link to the code that implements them; this doc asserts, the code proves.
 
 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/delivery/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/delivery/skills/documentation/templates/system-overview.md

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

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

@@ -1,9 +1,20 @@
-# UX Behavior — template
+# UX behavior (docs/features/{surface}-ux.md)
 
 **Truth document.** States what a person sees and can do on a surface, and what the surface promises never to do. Present tense, like every truth document.
 
 **`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,7 @@
 | 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.
-
-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.
+**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, its header names this one; prefer that header pointer, because the See also line is the weaker binding. A document nothing implicates rots, and a surface rewritten under an unimplicated document is the failure this genre exists to prevent.
 
 ---
 
@@ -56,7 +65,7 @@ What moves the surface between states, and who causes each move — the person,
 
 ## Optional sections
 
-**Copy** — the exact words, where the wording is load-bearing (a refusal, an irreversible confirmation). **Density and rhythm** — where a surface deliberately differs from the design system's default. **Open questions** — decisions deliberately not yet made, so an implementer knows what to ask rather than guessing.
+**Copy** — the exact words, where the wording is load-bearing (a refusal, an irreversible confirmation). **Density and rhythm** — where a surface deliberately differs from the design system's default. **Open questions** — decisions deliberately left open, so an implementer knows what to ask rather than guessing.
 
 ## Rules
 

package/data/harnesses/delivery/skills/escalate/SKILL.md

@@ -5,21 +5,21 @@ description: Use when a task's routed tier isn't good enough — a prompt keeps
 
 # Escalate — evidence-gated tier promotion
 
-Promotion is earned by a failing eval, never by intuition. This skill is the only legitimate path to running a task above its routed tier — and it is deliberately fast: one eval run of evidence, one entry, done. No approvals theater.
+Promotion is earned by a failing eval, never by intuition. This skill is the **only** path to running a task above its routed tier. The gate is one eval run and one entry — ask for no further approval.
 
 ## Procedure
 
-1. **Demand the evidence.** A completed `prompt-eval` run at the currently routed tier, failing the family threshold. No run ⇒ run it now (that is the whole gate). An old run doesn't count — the evidence is for the current prompt version.
-2. **Write the escalation entry** — this skill owns the format; `cost-report` parses these entries, so the shape is a contract:
-   - File: `docs/history/changelog/YYYY-MM-DD-{three-words}.md`, standard changelog-entry template, plus its `docs/history/CHANGELOG.md` row.
-   - **`Class: escalation`** — the fixed rendezvous keyword. Exactly this word; `cost-report` and `retro` match on it.
-   - `Change:` names the task type, the family, the failing score vs. threshold, and the tier movement (`standard → frontier`).
-   - `Discovered:` what the failure teaches about the tier's capability ceiling — this is the routing table's tuning signal.
-3. **Record the promotion scope**: one-off (this task runs high once) or standing (the routing row itself is wrong). A standing promotion also appends an out-of-scope discovery proposing the routing-table row change — the table is policy and moves by its own edit, not silently.
+1. **Demand the evidence**: a completed `prompt-eval` run at the routed tier, failing the family threshold, against the current prompt version — a run against an earlier version **never** counts. No such run ⇒ run it now.
+2. **Write the escalation entry.** This skill owns its shape, and `cost-report` and `retro` parse it, so the shape is a contract:
+   - File: `docs/history/changelog/YYYY-MM-DD-{three-words}.md`, on the standard changelog-entry template.
+   - `Class:` carries `escalation`, spelled exactly — the keyword `cost-report` and `retro` match on.
+   - `Change:` names the task type, the family, the failing score vs. the threshold, and the tier movement (`standard → frontier`).
+   - `Discovered:` states what the failure teaches about the tier's capability ceiling — the routing table's tuning signal.
+3. **Record the promotion scope**: one-off (this task runs high once) or standing (the routing row itself is wrong). For a standing promotion, also append an out-of-scope discovery proposing the routing-row change — **never** edit the routing table here; it is policy and moves by its own reviewed edit.
 4. **Dispatch at the new tier** and finish the work.
 
 ## Rules
 
-- **The entry precedes the dispatch.** An escalation with no entry is an unevidenced promotion — the routing guardrails prohibit it.
-- **Escalation is symmetric.** When `regression-runner`'s demotion experiment passes a tier down, that result is recorded the same way (`Class: escalation`, direction down) — the table tunes on both signals.
-- **Frequency is signal, not failure.** Many escalations from one row mean the row is wrong; that is `retro`'s finding to make, from these entries. Never suppress one to keep the table looking right.
+- **The entry precedes the dispatch.** A dispatch with no entry is an unevidenced promotion, which `CLAUDE.md`'s routing guardrails prohibit.
+- **Escalation is symmetric.** A `regression-runner` demotion experiment that passes a tier down is recorded on the same format — `Class: escalation`, direction down.
+- **Frequency is signal, not failure.** Many escalations from one row mean the row is wrong — `retro`'s finding to make from these entries. **Never** suppress an escalation to keep the table looking right.

package/data/harnesses/delivery/skills/prompt-eval/SKILL.md

@@ -5,18 +5,18 @@ description: Use when a prompt needs its quality measured — after drafting or
 
 # Prompt Eval — the golden-set loop
 
-A prompt's quality claim is its eval result, nothing else. This skill runs the loop; conventions for golden sets, rubrics, and thresholds are `.claude/rules/evals.md`.
+A prompt's quality claim is its eval result, nothing else. This skill runs the loop; golden-set, rubric, and threshold conventions are `.claude/rules/evals.md`.
 
 ## Procedure
 
-1. **Locate the family's golden set** at `evals/{family}/` — the owning feature doc names the family. A prompt with no golden set gets one *first* (eval-first: the set ships with the prompt, and `data-generator` drafts edge-case items for human review).
-2. **Run the set** against the prompt via `eval-runner` — every item, not a sample. Batch variants in one run so scores are comparable.
-3. **Grade with the family's rubric.** Mechanical checks (format, required fields, refusal correctness) grade in code; judgment dimensions grade against the rubric's anchors. Report per-dimension scores and the delta against the incumbent prompt's certified score.
-4. **Gate:** meeting the family's threshold on iteration is a *candidate*; certification for the library additionally requires the `judge` ship gate (frontier, one dispatch — the only frontier call in the loop).
-5. **Record:** the winning variant's scores go into its `prompt-library` entry; the losing variants' deltas belong in the changelog entry's refinement context.
+1. **Locate the family's golden set** at `evals/{family}/` — the owning feature doc names the family. A prompt with no golden set gets one **first**: dispatch `data-generator` to draft edge-case items, and have a human review them before they join the set.
+2. **Run the full set** against the prompt via `eval-runner` — every item, never a sample. Batch all variants into one run so their scores are comparable.
+3. **Grade with the family's rubric.** Mechanical checks grade in code; judgment dimensions grade against the rubric's anchors. Report per-dimension scores and the delta against the incumbent prompt's certified score.
+4. **Gate.** A variant meeting the family threshold is a candidate, not certified. Certification for the library also requires one `judge` dispatch — the loop's only frontier-tier call.
+5. **Record.** Write the certified variant's scores into its `prompt-library` entry; put the losing variants' deltas in the changelog entry's refinement context.
 
 ## Rules
 
-- **Iteration stays cheap.** The draft → eval → revise loop runs on economy (`eval-runner`) and standard (`prompt-iterator`) tiers; the frontier judge appears once, at the gate — never inside the loop.
+- **Iteration stays off the frontier tier.** The draft → eval → revise loop runs on economy (`eval-runner`) and standard (`prompt-iterator`); **never** dispatch `judge` inside the loop.
 - **Never weaken a rubric to pass a prompt.** A rubric change is a design change to the family's eval suite: it goes through the owning feature doc, re-runs the whole family, and re-certifies every entry.
-- **A failing eval is a result, not an obstacle.** Report it honestly; if the family genuinely needs a stronger tier, that is the `escalate` skill's evidence.
+- **A failing eval is a result, not an obstacle.** Report it as it stands. When the family needs a stronger tier, that failing run is the `escalate` skill's evidence.

package/data/harnesses/delivery/skills/prompt-library/SKILL.md

@@ -5,11 +5,11 @@ description: Use when creating, versioning, retrieving, or auditing a production
 
 # Prompt Library — versioned, certified entries
 
-`prompts/{family}/` is a library of certified production artifacts, not a scratchpad. Every entry is versioned, eval-scored, and tier-certified; scratch iterations live outside until they pass.
+`prompts/{family}/` holds certified production prompts only. Every entry is versioned, eval-scored and tier-certified; scratch iterations stay outside `prompts/**` until they pass their family's evals.
 
 ## The entry format
 
-Each prompt is one file at `prompts/{family}/{name}.md` with frontmatter:
+Each prompt is one file at `prompts/{family}/{name}.md` with this frontmatter:
 
 ```yaml
 ---
@@ -21,16 +21,37 @@ status: active        # active | candidate | retired
 ---
 ```
 
-The body is the prompt itself, verbatim — no narration, no history (the journey lives in changelog entries). A `candidate` has passed its family threshold but not the `judge` gate; `retired` entries stay in place for provenance (consumers must never load them — status is the filter).
+| `status` | Meaning |
+| --- | --- |
+| `active` | Certified — the only status a consumer loads |
+| `candidate` | Met the family threshold in `prompt-eval`; not yet through the `judge` gate |
+| `retired` | Kept in place for provenance; **never** loaded |
+
+The body is the prompt verbatim — no narration, no history; the journey lives in changelog entries.
 
 ## Procedure
 
-- **Create / update**: a content change bumps `version`, resets `status` to `candidate`, and goes through `prompt-eval` → `judge` before flipping back to `active` with fresh `eval-score` and `certified` values. The owning feature doc's `owns:` glob covers the family — read it first.
-- **Retrieve**: match by family + status `active`; the entry's `tier` names the tier it runs on — dispatch accordingly, never stronger (that is an unevidenced promotion).
-- **Audit** (on demand, and by `regression-runner` after a model-generation change): every `active` entry whose `certified` date precedes the current `model-tiers` mapping is stale — re-certify or flag.
+Before any write, read the family's owning feature doc — its `owns:` glob covers the family.
+
+**Create or update:**
+
+1. Iterate outside `prompts/**` with `prompt-eval` until the variant meets the family threshold.
+2. Write the entry with `version` bumped and `status: candidate`.
+3. Run the `judge` gate.
+4. On a pass, set `status: active` with the certifying run's `eval-score` and `certified` date.
+
+**Retrieve:**
+
+1. Match by family and `status: active`.
+2. Dispatch at the entry's `tier` — **never** stronger; running above the certified tier is an unevidenced promotion.
+
+**Audit** — on demand, and by `regression-runner` after every model-generation change:
+
+1. List every `active` entry whose `certified` date precedes the latest change to the `model-tiers` rule — each is stale.
+2. Re-certify each stale entry, or flag it.
 
 ## Rules
 
-- **Certification is per tier.** A prompt certified on standard says nothing about economy; a demotion experiment that passes produces a *new* certification at the lower tier.
-- **One prompt, one entry.** Variants under comparison are `candidate` siblings; only one `active` per name.
-- **Never hand-edit `eval-score`** — it is written by the certifying run or not at all.
+- **Certification is per tier.** A prompt certified on standard says nothing about economy; a passing demotion experiment produces a *new* certification at the lower tier.
+- **One prompt, one entry.** Variants under comparison are `candidate` siblings; only one is `active` per name.
+- **Never hand-edit `eval-score`** — only the certifying run writes it.

package/data/harnesses/delivery/skills/route/SKILL.md

@@ -5,17 +5,17 @@ description: Use when starting any piece of prompt work — drafting, evaluating
 
 # Route — classify, look up, dispatch
 
-The model decision belongs to the routing table in `CLAUDE.md` § The Routing Policy, not to you and not to the user. This skill is the single entry point that applies it.
+The model decision belongs to the routing table in `CLAUDE.md` § The Routing Policy — not to you and not to the user. This skill is the single entry point that applies it.
 
 ## Procedure
 
-1. **Classify the task into exactly one task type** from the routing table's rows. Classification is mechanical work — do it inline at the cheapest capable tier, never by dispatching a frontier agent to think about it. When a task spans types (e.g. "draft a prompt and evaluate it"), decompose: each leg routes separately.
-2. **Read the row**: task type → tier → executing agent.
-3. **Dispatch the named agent.** The agent's own pin enforces the tier — never override the model at dispatch time. Work with no matching row is new: route it provisionally to the standard tier, do the work, and record the missing row as an out-of-scope discovery so the table gains it.
-4. **Never route around a failing eval.** If the routed tier's output fails its evals, the answer is the `escalate` skill (evidence-gated promotion), not a quiet re-dispatch on a stronger agent.
+1. **Classify the task into exactly one task type** from the routing table's rows. Classify inline — it is mechanical work, never worth a dispatch. When a task spans types ("draft a prompt and evaluate it"), decompose it and route each leg separately.
+2. **Read the row**: task type → tier → executing agent. When no row matches, the task type is new: do the work provisionally at the standard tier and record the missing row as an out-of-scope discovery, so the table gains it.
+3. **Dispatch the named agent.** Its `model:` pin enforces the tier — **never** override the model at dispatch time.
+4. **Never route around a failing eval.** When the routed tier's output fails its evals, run the `escalate` skill (evidence-gated promotion) — never a quiet re-dispatch on a stronger agent.
 
 ## What this skill refuses
 
-- Naming a model. Tiers only; the mapping lives in `.claude/rules/model-tiers.md` and the agents' pins.
-- Frontier dispatch for mechanical work (eval runs, data generation, classification) — the routing guardrails in `CLAUDE.md` prohibit it regardless of who asks.
-- Skipping the table because the task "obviously" needs the strongest model — that intuition is exactly what the escalation ladder exists to test.
+- ❌ Naming a model — tiers only; the mapping lives in `.claude/rules/model-tiers.md` and the agents' `model:` pins.
+- ❌ Frontier dispatch for mechanical work (eval runs, data generation, classification) — the routing guardrails in `CLAUDE.md` § The Routing Policy prohibit it whoever asks.
+- ❌ Skipping the table because the task "obviously" needs the strongest model — that intuition is what the escalation ladder exists to test.

package/data/harnesses/etna/CLAUDE.md

@@ -105,7 +105,7 @@ Invoke the `boundary` skill after a plan is approved and before its first implem
 - **Everything written in this repo follows [`docs/writing-style.md`](docs/writing-style.md) — no exceptions.** It is the single style authority for both genres: instruction files (`CLAUDE.md`, rules, agents, skill prose) and documents. Read it before writing prose here, not after. Its load-bearing rule is the Two Natures — truth documents state the present and narrate no history; records are dated and never edited to match the present.
 - **Every markdown document also goes through the `documentation` skill** for its *genre* — invoke it before creating or substantively editing any `.md` file and apply the matching template. The skill supplies structure; `writing-style.md` supplies the prose.
 - **[override]** Keep `docs/` updated when a change alters documented behaviour — creating and updating docs is part of the work.
-- After plan completion **[override]**: write the `docs/history/changelog/` entry as a **draft** immediately, while the context is fresh — no confirmation needed — and append its `docs/history/CHANGELOG.md` row; the commit fills what the draft left open and freezes it. Non-plan work needs no separate prompt: every non-exempt commit carries its own entry (the `changelog` rule).
+- After plan completion **[override]**: write the `docs/history/changelog/` entry as a **draft** immediately, while the context is fresh — no confirmation needed; the commit fills what the draft left open and freezes it. Non-plan work needs no separate prompt: every non-exempt commit carries its own entry (the `changelog` rule).
 - When moving or renaming a component: update the `owns:` globs of the doc that owns it so the ownership index stays accurate. A new doc that owns code declares its paths in its own `owns:` frontmatter.
 - `docs/structure.md` is the authority on what belongs where — read it before adding or moving a doc; one canonical source per topic, link don't copy. Only `CLAUDE.md`, `AGENTS.md`, and `README.md` live at the repo root.
 
@@ -117,7 +117,7 @@ Invoke the `boundary` skill after a plan is approved and before its first implem
 
 A commit marks the user's behavioral verification of the work, and the working session is the last holder of the refinement context that produced it — asks, iterations, rejections, skill outcomes, discoveries. That context is captured in the changelog and distilled on demand. The `changelog` rule carries the trigger and the lifecycle; this is the policy:
 
-- **Every non-mechanical commit is covered by an entry** at `docs/history/changelog/YYYY-MM-DD-{three-words}.md`, staged inside the commit it describes — whatever tool or session performs the commit — plus a row in `docs/history/CHANGELOG.md`. Format, required fields, and the closed exemption list are the `documentation` skill's `templates/changelog-entry.md`; the failure fields (rejected attempts, overridden skill output) and verbatim taste quotes are required, not optional — the entry's value concentrates there.
+- **Every non-mechanical commit is covered by an entry** at `docs/history/changelog/YYYY-MM-DD-{three-words}.md`, staged inside the commit it describes — whatever tool or session performs the commit. `docs/history/CHANGELOG.md` is the folder's guide and takes no row per entry. Format, required fields, and the closed exemption list are the `documentation` skill's `templates/changelog-entry.md`; the failure fields (rejected attempts, overridden skill output) and verbatim taste quotes are required, not optional — the entry's value concentrates there.
 - **An entry may exist before its commit.** A plan reaching `Status: Complete` writes its entry as a **draft** immediately, while the context is fresh; the commit fills what the draft left open. **Immutability begins at commit, not creation** — a draft is mutable, a committed entry never is, and a correction is a new entry that links back. Doc-health passes skip the genre.
 - **A commit is the smallest unit an entry may describe**; above that the mapping is judgment. Work exceeding a draft's scope gets a *second* entry rather than stretching the first.
 - **Distillation is the `retro` agent** — run on demand (before a brainstorm or LLD, before a new project, after a refinement arc), it converts accumulated entries into a typed punch list (doc content, doc structure, skill evolution, pins, harness rules), appends actionable items to the backlog, and proposes only — application runs through the normal documentation loop.