@nurix/etna 0.20.36 → 0.20.38

package/data/harnesses/etna/skills/brainstorm/references/harvest.md

@@ -6,27 +6,26 @@ this reference carries the routing judgment.
 
 The pipeline, end to end:
 
-```
-converge → final sync/compose → manifest (Status: proposed)
-  → ONE user approval (Status: approved)
-  → apply, reading both sides of every destination (Status: applied)
-  → uselessness test → gaps? new Round, back to approval
-  → move to docs/history/brainstorms/{topic}/  ← the completion marker
-  → offer: delete or commit — the user decides
-```
-
-**Harvest fails loud, never silent.** The move happens only after the full apply passes the
-uselessness test. A partial apply — twin death, session kill, anything — leaves the folder
-visibly unfinished in `docs/research/` and the user restarts the stop. The pipeline never resumes
-silently from a half-applied state, and canonical docs are never written without an approved
-manifest (gap-round fixes included).
+1. Converge.
+2. Final sync and compose → manifest (`Status: proposed`).
+3. **One** user approval (`Status: approved`).
+4. Apply, reading both sides of every destination (`Status: applied`).
+5. Uselessness test — gaps open a new `Round` and return to step 3.
+6. Move to `docs/history/brainstorms/{topic}/` — the completion marker.
+7. Offer: delete or commit — the user decides.
+
+**Harvest fails loud, never silent.** The move happens **only** after the full apply passes the
+uselessness test. A partial apply — twin death, session kill, anything — leaves the folder visibly
+unfinished in `docs/research/`, and the user restarts the stop. The pipeline **never** resumes
+silently from a half-applied state, and **never** writes a canonical doc without an approved
+manifest, gap-round fixes included.
 
 ## The routing map
 
-Route each piece of the surface by scope. Format every artifact via the `documentation` skill;
-where it is unavailable, fall back to own formatting and record which path ran in the manifest.
-Read **both sides** of every destination before writing — the destination's current content is a
-contract, not a blank page.
+Route each piece of the surface by scope. Format every artifact through the `documentation` skill;
+where it is unavailable, format it yourself and record in the manifest which path ran. Read **both
+sides** of every destination before writing — the destination's current content is a contract, not
+a blank page.
 
 | What | Goes to | Shape |
 | --- | --- | --- |
@@ -36,7 +35,7 @@ contract, not a blank page.
 | **Domain-model changes** | The living domain-model doc | The information-architecture contract the `boundary` skill reads at the next plan check |
 | **Still-open (parked) forks** | The repo's open-questions home | Each with a *resolution-lands-in* pointer |
 | **Backlog items** | The repo backlog | See the scope-guard trio below |
-| **Fragments** | Their destinations — they were drafted in destination format precisely so this is a move, not a translation | Merge per the destination's existing structure |
+| **Fragments** | Their destinations — drafted in destination format, so this is a move, not a translation | Merge per the destination's existing structure |
 
 **The scope-guard trio** disambiguates everything that isn't a commitment:
 
@@ -47,13 +46,12 @@ contract, not a blank page.
 
 **Directional steering is not feature truth.** A harvested principle informs many decisions and
 changes slowly; a feature fact belongs to its feature doc and changes at code speed. The harvest
-**links** between the steering layer and feature docs — it never duplicates prose across them,
-and it never invents a new top-level home for principles (they land in the *existing* living
-docs).
+**links** between the steering layer and feature docs — **never** duplicates prose across them, and
+**never** invents a new top-level home for principles; they land in the *existing* living docs.
 
-Rejection rationale and reasoning chains must have explicit destinations — options-considered
-sections, decision changelogs — or the uselessness test fails: the folder may never be deleted
-into a knowledge loss.
+Rejection rationale and reasoning chains **must** have explicit destinations — options-considered
+sections, decision changelogs — or the uselessness test fails: the folder is **never** deleted into
+a knowledge loss.
 
 ## The uselessness test
 
@@ -68,48 +66,53 @@ The deletion-safety gate: after the apply, the post-harvest living docs alone mu
 - **The task:** reconstruct the design — thesis, commitments, reasoning, declined branches — from
   the allowed paths only.
 - **Grading:** the twin diffs the reconstruction against the ledger and thesis and names every
-  gap; the session-replay evals audit the grading itself. Anything unrecoverable is a named
-  harvest gap → recorded in the manifest (`Result: fail`), fixes enter a new manifest `Round`,
-  approved like the first. Iterate until the folder is redundant.
+  gap; the session-replay evals audit the grading itself. Anything unrecoverable is a named harvest
+  gap, recorded in the manifest (`Result: fail`); its fixes enter a new manifest `Round`, approved
+  like the first. Iterate until the folder is redundant.
 
 ## The move, and the offer
 
-When the detector's move gate is clean: delete `ops/` entirely (transcript-grade residue never
-enters git), `git mv` the folder to `docs/history/brainstorms/{topic}/`, set
-and `Status: harvested`; no index is updated, because none keeps a row per session. The move is the completion marker — a folder still under
+When the detector's move gate is clean:
+
+1. Delete `ops/` entirely — transcript-grade residue **never** enters git.
+2. `git mv` the folder to `docs/history/brainstorms/{topic}/`.
+3. Set `Status: harvested` in `state.md`.
+
+Update no index — none keeps a row per session. The move is the completion marker: a folder under
 `docs/research/` is by definition unfinished, which is exactly what the maintenance census reads.
 
 Then the offer, relayed by the facilitator: **delete the moved folder, or commit it.** The user
-decides; the design assumes deletion — nothing anywhere may depend on the folder surviving.
-Committing is the explicit way to keep git-history forensics; an uncommitted folder deleted here
-is gone, and that residual is accepted by design.
+decides; the design assumes deletion — **nothing** anywhere may depend on the folder surviving.
+Committing is the explicit way to keep git-history forensics; an uncommitted folder deleted here is
+gone, and that loss is accepted by design.
 
 ## Field lessons — apply
 
-Measured on live harvests; each is the rule, distilled.
+Each is a rule measured on live harvests.
 
 - **Run the move gate clean immediately before the move and treat that as the verdict** — the
   gate's checks read `ops/`, which the move deletes, so a post-move re-run fails by construction.
-  Verify the post-move state by hand: `Status: harvested`, no `ops/`, both index rows,
-  `check-links` clean. And **distil the process record into `state.md` before the move** — the
-  sync log dies with `ops/`, and a ten-line dispatch summary is what separates a record that shows
-  its workings from one that asserts its commitments from nowhere.
+  Verify the post-move state by hand: `Status: harvested`, no `ops/`, `check-links` clean.
+- **Distil the process record into `state.md` before the move** — the sync log dies with `ops/`,
+  and a ten-line dispatch summary separates a record that shows its workings from one that asserts
+  its commitments from nowhere.
 - **Uncommitted harvest artifacts are deleted, not deprecated** — deprecate-in-place protects
   readers holding a pointer, and a never-committed file has none; a tombstone for a
   twenty-minute-old file is ceremony.
-- **Audit the *other* decision records for impact at manifest time** — the manifest routes
-  through the docs the commitments name and will not think of the neighbours. The test is
-  commitment-level, not textual (grep finds nothing); read each AD's Decision and Open Questions
-  against the new commitments, and report the unimpacted verdicts with evidence too.
-- **A manifest enumerates sites; the file you open contains more of them.** Fix every
-  same-doctrine site inside a file the manifest already opens — a self-contradicting document is
-  worse than a wider diff — but never wander into an unnamed file: that becomes a backlog row.
-  Say which you did, per row, in the application record.
+- **At manifest time, read every existing AD's Decision and Open Questions against the new
+  commitments.** A harvest routes only through the docs its commitments name, and the test is
+  commitment-level, not textual — grep finds nothing, because the ledger never names the
+  neighbours. Report the unimpacted verdicts with their evidence too.
+- **A manifest row names one site; the file you open holds more.** Fix every same-doctrine site
+  inside a file the manifest already opens — a self-contradicting document is worse than a wider
+  diff — but **never** wander into an unnamed file: that becomes a backlog row, because a canonical
+  doc is not rewritten outside an approved scope. Say which you did, per row, in the application
+  record.
 - **Re-run the uselessness test when the destination *set* changes**, not only when content does —
   a consolidation that moves referrers produces a document set no cold reader has graded. The
   recurring find: a truth doc stating a decided-but-unbuilt mechanism in the present tense; the
   fix is one clause naming the unbuilt prerequisite.
-- **Retirement wording beats suppression.** doc-lint's heuristics block the honest retirement
+- **Retirement wording beats suppression.** `doc-lint`'s heuristics block the honest retirement
   sentence (`superseded by`, `no longer`); rephrase with no loss of meaning — "retired by
   AD-00N", "is not the product's position", "lives in a package that is gone" — and reach for
   `doc-lint-disable` only when the banned phrase is itself the claim.
@@ -134,14 +137,6 @@ Measured on live harvests; each is the rule, distilled.
   keeping its Decision, Why and Declined table — and a separate AD only for a genuinely different
   subject. Link with section anchors where a bare pointer loses precision, and verify anchors by
   hand: the link checker strips them before resolving.
-- **At manifest time, read every existing AD's Decision and Open Questions against the new
-  commitments.** A harvest routes only through the docs its commitments name, and grep finds
-  nothing because the ledger never names the others; report the unimpacted verdicts with their
-  evidence too.
-- **A manifest row names one site; the file you open holds more.** Fix the same-doctrine sites
-  inside a file the manifest already opens, but never wander into an unnamed file — that becomes a
-  backlog row, because a canonical doc is not rewritten outside an approved scope. Say which you did,
-  per row, in the application record.
 - **The per-file lint hook reads intermediate states.** It appends queue rows from mid-edit files;
   run the linter over the whole edited set before declaring the apply done, and leave the stale
   rows for the facilitator rather than draining them.

package/data/harnesses/etna/skills/brainstorm/references/session-schema.md

@@ -2,35 +2,36 @@
 
 Load when: bootstrapping a session, writing any working-surface file, dispatching the twin, or
 interpreting detector output. The detector (`scripts/detector.mjs`) is the mechanical half of this
-contract — every rule below that carries a rule ID is machine-checked; everything else is the
-twin's semantic judgment.
+contract: every rule below carrying a rule ID is machine-checked; everything else is the twin's
+semantic judgment.
 
 ## Folder layout
 
-```
-docs/research/{topic}-brainstorm/     ← open session (kebab-case topic slug)
-├── state.md                          ← anchor + aspect map (twin-written)
-├── thesis.md                         ← composed claim → argument → what changed (twin-written)
-├── forks.md                          ← open questions with close conditions (twin-written)
-├── ledger.md                         ← commitments (twin-written)
-├── basis/                            ← frozen entry material (facilitator-written once, at intake)
-├── fragments/                        ← harvest-native fragments (twin-written; materialize on
-│                                        first real content, drafted in destination format)
-└── ops/                              ← untracked capture layer (deleted at stop)
-    ├── .gitignore                    ← contains `*` — ops/ never enters git      [BS-OPS-01/02]
-    ├── capture.md                    ← facilitator's raw append ledger (its ONLY write)
-    ├── sync-log.md                   ← paired twin-dispatch log
-    └── manifest.md                   ← harvest manifest (created by the stop pipeline)
-```
-
-On a passed harvest the folder **moves** to `docs/history/brainstorms/{topic}/` (ops/ deleted
-first) — the move is the completion marker; the user then deletes or commits it. A folder still
+An open session is `docs/research/{topic}-brainstorm/` (kebab-case topic slug):
+
+| Path | Holds | Writer |
+| --- | --- | --- |
+| `state.md` | anchor + aspect map | twin |
+| `thesis.md` | composed claim → argument → what changed | twin |
+| `forks.md` | open questions with close conditions | twin |
+| `ledger.md` | commitments | twin |
+| `basis/` | frozen entry material | facilitator, once, at intake |
+| `fragments/` | harvest-native fragments, drafted in destination format; created on first real content | twin |
+| `ops/` | the untracked capture layer, deleted at stop | — |
+| `ops/.gitignore` | `*` — `ops/` **never** enters git [BS-OPS-01/02] | facilitator |
+| `ops/capture.md` | the facilitator's raw append ledger | facilitator |
+| `ops/sync-log.md` | the paired twin-dispatch log | both (see below) |
+| `ops/manifest.md` | the harvest manifest | twin, in the stop pipeline |
+
+On a passed harvest the folder **moves** to `docs/history/brainstorms/{topic}/`, `ops/` deleted
+first. The move is the completion marker; the user then deletes or commits the folder. A folder
 under `docs/research/` is by definition unfinished.
 
-**Write protocol (one writer per file):** the facilitator appends to `ops/capture.md` and writes
-the initial `basis/` copy plus the sync-log *dispatch* lines — nothing else, ever. The twin writes
-every other file, at gates. The user may hand-edit anything; the twin diffs each file against its
-own last compose before rewriting and folds foreign edits as first-class user signal.
+**Write protocol (one writer per file; the sync log is paired):** the facilitator bootstraps `ops/` at intake, appends to
+`ops/capture.md`, and writes the initial `basis/` copy plus the sync-log *dispatch* lines —
+**nothing else, ever**. The twin writes every other file, at gates. The user may hand-edit anything;
+the twin diffs each file against its own last compose before rewriting and folds foreign edits in
+as first-class user signal.
 
 ## state.md
 
@@ -50,8 +51,8 @@ own last compose before rewriting and folds foreign edits as first-class user si
 - risks — failure modes and mitigations → none yet
 ```
 
-- `Status` transitions only forward: `open → stopping → harvested` (the twin flips `stopping` when
-  the stop pipeline begins, `harvested` at the move). [BS-STATE-01]
+- `Status` moves **only** forward: `open → stopping → harvested` — the twin sets `stopping` when the
+  stop pipeline begins and `harvested` at the move [BS-STATE-01].
 - The aspect map is derived per idea from the basis and edited by the user. Each aspect carries
   `→` refs to the content covering it: fork IDs (`F#`), ledger IDs (`D#`), `thesis`,
   `fragment:{name}`, or `none yet` (an open coverage gap — informational mid-session
@@ -70,8 +71,8 @@ Current as of: 2026-07-08T14:30Z
 ## What changed
 ```
 
-Composed prose, rewritten whole at every compose, never appended. The three sections and the
-stamp are mandatory [BS-THESIS-01]; the stamp must equal state.md's `Last compose`
+Composed prose, rewritten whole at every compose, **never** appended. The three sections and the
+stamp are mandatory [BS-THESIS-01]; the stamp must equal `state.md`'s `Last compose`
 [BS-COMPOSE-01]. At the manifest gate, `Last compose` must be later than the newest
 `ops/capture.md` entry — a compose over unsynced capture is stale [BS-COMPOSE-02].
 
@@ -89,8 +90,8 @@ Full self-contained prose in the user's framing.
 - IDs `F1, F2, …` unique, never reused [BS-FORK-01]. Status marker: `[open]` or
   `[parked → {destination}]`. Every fork carries `Closes when:` [BS-FORK-01].
 - `Raised by: twin (S#)` must cite a reconciled sync-log entry [BS-SYNC-02].
-- **A resolved fork's entry is deleted** by the twin — the resolving ledger entry's `Resolves:`
-  field is the record. forks.md holds only open and parked forks; a ledger `Resolves: F3`
+- **The twin deletes a resolved fork's entry** — the resolving ledger entry's `Resolves:` field is
+  the record. `forks.md` holds only open and parked forks; a ledger `Resolves: F3`
   coexisting with an open F3 is an inconsistency [BS-FORK-02]. Parked forks survive to the
   manifest, which must route each one [BS-MANIFEST-01].
 - The manifest gate requires zero `[open]` forks [BS-FORK-03].
@@ -115,10 +116,10 @@ Full self-contained prose in the user's framing.
 
 ## ops/capture.md
 
-The facilitator's per-turn append — its one write duty. Lowest possible bar: raw, unpolished,
-everything session-relevant from *both* sides (user substance and facilitator substance —
-diagnoses, informed rejections, definitions, reasoning chains), including residue judged not
-worth pillar filing. Format:
+The facilitator's per-turn append. Lowest possible bar: raw, unpolished, everything
+session-relevant from *both* sides (user substance and facilitator substance — diagnoses, informed
+rejections, definitions, reasoning chains), including residue judged not worth pillar filing.
+Format:
 
 ```markdown
 ---
@@ -127,8 +128,8 @@ worth pillar filing. Format:
 <raw notes for this turn>
 ```
 
-Turn IDs `T#` ascending with an ISO timestamp — the timestamp is what compose-freshness checks
-against [BS-COMPOSE-02]. Never distill here; distillation is the twin's job.
+Turn IDs `T#` ascend, each with an ISO timestamp — the timestamp compose-freshness checks against
+[BS-COMPOSE-02]. **Never** distill here; distillation is the twin's.
 
 ## ops/sync-log.md
 
@@ -140,7 +141,7 @@ S4 → reconciled | 2026-07-08T14:29Z | 4 edits · 2 new forks · 6 open · unto
 ```
 
 The **facilitator** writes the dispatch line as it dispatches; the **twin** appends the result
-line (`reconciled` or `failed`) on return — no single author holds both sides. Every dispatch
+line (`reconciled` or `failed`) on return — **never** one author for both sides. Every dispatch
 line must acquire a result line; only the newest entry may be unpaired (in flight) [BS-SYNC-01].
 A `failed` result is surfaced to the user at the next turn break and re-run at the next gate.
 
@@ -181,8 +182,13 @@ the move to history requires a recorded passing uselessness test [BS-USELESS-01]
 - `move` — adds the post-apply gates (manifest applied, uselessness pass recorded, no links into
   scaffolding); the folder may not move while any fail.
 
-Exit code 0 = clean, 1 = violations (listed with rule IDs), 2 = unusable input. A run always
-prints output — per-rule lines plus a `clean`/`failing` summary (or a usage/error message);
-**exit 0 with empty output means the detector never executed** and is a failure, never a pass. Rules degrade
-gracefully: no git context ⇒ BS-OPS-02 reports `skipped`, never blocks. Rule IDs are stable —
-consumers (the twin, the evals, the maintenance census) key on them.
+| Exit | Meaning |
+| --- | --- |
+| `0` | clean |
+| `1` | violations, listed with rule IDs |
+| `2` | unusable input |
+
+A run always prints output — per-rule lines plus a `clean`/`failing` summary, or a usage/error
+message. **Exit 0 with empty output means the detector never executed** — a failure, **never** a
+pass. Rules degrade gracefully: with no git context, `BS-OPS-02` reports `skipped` and never blocks.
+Rule IDs are stable — the twin, the evals, and the maintenance census key on them.

package/data/harnesses/etna/skills/documentation/SKILL.md

@@ -3,7 +3,7 @@ name: documentation
 description: "Use when creating or substantively editing ANY markdown doc — invoke BEFORE writing. Genre registry, templates and style authority for technical docs: LLDs, ADs, plans, changelogs, READMEs, runbooks. Owns the tense rule: truth docs state the present; history only in dated records. Baselining is the maintenance agent."
 ---
 
-# Technical Documentation Skill
+# Technical documentation skill
 
 This skill writes one document at a time: the genre registry says what kind of document it is, a template gives its shape, the style guide its prose, and `doc-lint` checks the mechanical half. It does not baseline, audit or reconcile a repo's doc tree; that is the `maintenance` agent, which calls this skill once per document it scaffolds.
 
@@ -67,7 +67,7 @@ The full strip-list and the record-side rules: `references/style-guide.md` § Th
 - **Intent and promises; facts are the graph's.** An owning document (feature, package, system) says why the product is shaped this way and what it promises, and names the objects it designs in `objects:`. Every computable fact (a table's columns, which function writes which column, which route sits behind which guard, which file holds what) is the code's, and a hand-typed copy is wrong the day the code moves. `doc-lint` blocks the retired mechanism sections (`mechanism-section`) and an owning document with no `objects:`.
 - **Read by people, pointed at by the footer.** Sharp bullets under noun-phrase headings, each a bold label, a colon, one or two plain sentences; code named only where a person types or sees it, or at a cross-cutting seam; every other pointer in the closing **For the agent** footer (style guide § Owning documents — the body and the footer).
 - **The stability test.** A sentence that would change when a function is renamed, a file moves, or a route, column or error code changes is the code's, not the document's. The code is the authority on *what*; the document on *why* (style guide § Shape).
-- **Unbuilt work has one home per kind.** Decided design the code does not yet do sits in the body, wrapped in an `UNBUILT` marker; a shortfall in what is built is one bullet under Gaps; the work that would close either is a backlog row, which the document never tracks (style guide § The stability test).
+- **Unbuilt work has one home per kind.** Decided, unbuilt design sits in the body, wrapped in an `UNBUILT` marker; a shortfall in what is built is one bullet under Gaps; the work that would close either is a backlog row, which the document never tracks (style guide § The stability test).
 - **No empty stubs.** Omit a section with nothing real to say. Write "None" only where the absence is itself information, such as a plan's Cross-Module Contracts Affected.
 - **No redirect documents.** Moving a document deletes the old file and repoints every inbound link; a "Moved to X" stub rots and creates false search hits.
 
@@ -78,9 +78,9 @@ The full strip-list and the record-side rules: `references/style-guide.md` § Th
 - **The links an index may carry:** a sibling folder's `Readme.md`, the mandated scaffolds (`structure.md`, `operations/setup.md`, `history/CHANGELOG.md`, `history/backlog.md`, `history/journal.md`, `history/health-log.md`, `memory/main.md`), and the root `CLAUDE.md` and `AGENTS.md`. `doc-lint` blocks the rest under `docs/` as `index-lists-files`, a drawn tree as `index-file-tree`, a named file or record as `index-names-records`.
 - **Routing documents point at truth.** A "read first" row names the topic's truth document, never a plan or changelog entry. An index of the records themselves (a History section naming `plans/` and `changelog/`) is sanctioned.
 
-### Ownership today
+### Ownership edges
 
-A document names the objects it designs in `objects:`, and a source file names the document that speaks for it in its path header. The harness's ownership scan reads one edge today: the transitional `owns:` region glob on each feature, package, system and surface-owning UX document, the narrower glob winning. Write the header pointer anyway, so the scan can switch to it and to the object closure without a second pass over the code. Where a repository has no `docs/architecture/systems/knowledge-layer.md`, this skill and `references/frontmatter.md` are the whole authority on document–code edges. `docs/structure.md` is harness-owned: the installer writes it, and the `maintenance` agent stamps only its `harness-version`.
+A document names the objects it designs in `objects:`, and a source file names the document that speaks for it in its path header. The harness's ownership scan reads one edge: the transitional `owns:` region glob on each feature, package, system and surface-owning UX document, the narrower glob winning. **Always write the header pointer as well** — the scan switches to it and to the object closure, and pointers already in place spare that switch a second pass over the code. Where a repository has no `docs/architecture/systems/knowledge-layer.md`, this skill and `references/frontmatter.md` are the whole authority on document–code edges. `docs/structure.md` is harness-owned: the installer writes it, and the `maintenance` agent stamps only its `harness-version`.
 
 ---
 
@@ -113,7 +113,7 @@ A document names the objects it designs in `objects:`, and a source file names t
 | Scaffold a standard doc (docs index, changelog guide, backlog, memory) | The registry's § Baseline scaffolds |
 | Frontmatter keys (`objects:`, `verifies:`, the transitional `owns:`) | [`references/frontmatter.md`](references/frontmatter.md) |
 | Source-file comments: what stays, what moves to a doc, proving a sweep | [`references/source-comments.md`](references/source-comments.md) |
-| Instruction file (`CLAUDE.md`, a rule, an agent, skill prose) | [`references/instruction-style.md`](references/instruction-style.md): every-load prose stays lean; the present-tense rule still applies |
+| Instruction file (`CLAUDE.md`, a rule, an agent, skill prose) | [`references/instruction-style.md`](references/instruction-style.md): every-load prose stays lean; the present-tense rule applies too |
 | Author or restructure a skill | The skill-authoring field guide in the etna repo (`nurixlabs/etna`), `docs/playbooks/skills/`. No etna checkout ⇒ ask the user for access, or proceed from first principles with `references/instruction-style.md` governing the prose |
 | No template matches | [`references/untemplated.md`](references/untemplated.md) |
 

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

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

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

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

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

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

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

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