@nurix/etna 0.18.10 → 0.18.12

package/data/harnesses/code/skills/brainstorm/README.md

@@ -2,7 +2,7 @@
 
 A Claude Code skill that is a **thinking partner for designing software** — not a form to fill in. It runs one constant loop (distill → abstract → sync → record) over a conversation, files the thinking into a small set of substance-first pillars, and treats _coherence_ as a measurable target rather than a vibe.
 
-The point of v2 is a single inversion over v1: **the conversation is the work; the artifacts serve it.** v1 had grown into elaborate bookkeeping (a tentative/committed decision state machine, background cascade locks and queues, a 10-pillar eager bootstrap, an unconditional greenfield doctrine) wrapped around thinking that never had to happen. v2 deletes that machinery and keeps the loop.
+The single principle: **the conversation is the work; the artifacts serve it.**
 
 ---
 
@@ -67,7 +67,7 @@ coherent ⇔ open_questions == 0 ∧ last sync ran after the last pillar write
 
 ## The sync agent
 
-The background reconciler that replaces v1's cascade apparatus. One sync in flight at a time; at most one queued behind it. It runs after substantive writes, mandatorily on entering converge and at `stop`, and on demand. It audits exactly four sources:
+The background reconciler. One sync in flight at a time; at most one queued behind it. It runs after substantive writes, mandatorily on entering converge and at `stop`, and on demand. It audits exactly four sources:
 
 1. **Cross-pillar contradiction** — thesis vs domain model vs decisions vs doctrine vs build.
 2. **Aspect coverage** — any mapped aspect with no content → a question.
@@ -96,9 +96,9 @@ The complexity dial sets _defaults_, not a cage — any lazy pillar materializes
 
 ---
 
-## Build modes (replacing the greenfield doctrine)
+## Build modes
 
-v1 applied a present-tense "greenfield" writing doctrine unconditionally — which was a bug for brownfield work, where migration vocabulary is load-bearing. v2 folds this into `build.md` as a **mode** chosen at intake:
+The writing posture is a **mode** chosen at intake, folded into `build.md`:
 
 - **greenfield** (default) — present-tense everywhere, no phantom history. Execution sections closed.
 - **brownfield** — migration vocabulary is legitimate in `build.md`; other pillars still describe the target.
@@ -108,9 +108,9 @@ v1 applied a present-tense "greenfield" writing doctrine unconditionally — whi
 
 ---
 
-## Harvest (optional)
+## Harvest
 
-By default the session folder _is_ the product — self-contained, resumed by the next `/brainstorm start`. When the repo is v9-harnessed (`docs/architecture/` + `docs/modules/` exist) the skill _offers_ the harvest adapter at `stop`, which routes pillars into the doc tree (ADRs, module pillars, plans, the `boundary` skill). See `harvest.md`. The adapter is never assumed.
+The session writes a **kept** design record at `docs/brainstorm/{topic}/` (one subfolder per topic). At `stop` the skill _offers_ the harvest adapter, which distils the pillars' conclusions into the doc tree (ADRs, module pillars, plans, the `boundary` skill reads contracts from source). The `docs/brainstorm/{topic}/` record is **kept** as the provenance — never deleted. See `harvest.md`.
 
 ---
 
@@ -128,9 +128,11 @@ By default the session folder _is_ the product — self-contained, resumed by th
 ## Files
 
 ```
-brainstorm/
+brainstorm/                  # the skill (in .claude/skills/)
 ├── SKILL.md      # the skill definition Claude Code loads (~1.8k words)
 ├── README.md     # this file
-├── harvest.md    # optional v9 doc-tree adapter
-└── templates/    # pillar templates copied into the session folder on first use
+├── harvest.md    # doc-tree harvest adapter (record kept at docs/brainstorm/{topic}/)
+└── templates/    # pillar templates copied into the session record on first use
 ```
+
+The session itself is written to `docs/brainstorm/{topic}/` (kept, committed) — not here.

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

@@ -50,7 +50,7 @@ Then propose the **aspect map**: the thinking dimensions for _this specific idea
 
 ### 3. Bootstrap
 
-Session folder: `./brainstorm/` by default (or `./plan/`, `./design/`, custom — reuse any folder containing `state.md`; confirm in one line). Create only the pillars the complexity calls for, from `templates/` (never overwrite existing files; if a template is missing, create the file from the field lists in **Pillars**). Write top-level `state.md`:
+Session folder: `docs/brainstorm/{topic}/` — a **committed, kept** design record, one subfolder per design topic (slug the topic; confirm it in one line). Resume an existing topic by reusing its folder if it already holds a `state.md`. The record stays in the repo after harvest (it is the provenance the steering pillars distil from — see `harvest.md`), so it lives under `docs/` like any other durable project knowledge, not at the repo root. Create only the pillars the complexity calls for, from `templates/` (never overwrite existing files; if a template is missing, create the file from the field lists in **Pillars**). Write top-level `state.md`:
 
 ```
 STATE: open
@@ -121,7 +121,7 @@ Zero means _"audited against the four sources and clean"_ — never _"nothing ca
 
 1. Run a final sync (wait for any in-flight sync first).
 2. **Coherent** → say so and proceed. **Questions open** → list them plainly (English first, codes in parentheses) and offer per question: resolve now (mini-converge) / park explicitly (backlog or non-goals, with reason) / leave open and stop anyway — the folder keeps full state and resumes exactly where it left off.
-3. **Harvest** — see `harvest.md`. Standalone by default: the session folder _is_ the product. If the repo is v9-harnessed (`docs/architecture/` + `docs/modules/` exist), offer the adapter routing; never assume it.
+3. **Harvest** — see `harvest.md`. The harvest distils the pillars' conclusions into the live steering docs by scope (`docs/architecture/`, `docs/architecture/adr/`, `docs/history/backlog.md`); the `docs/brainstorm/{topic}/` record itself is **kept** (committed), never deleted — it is the provenance the harvested headlines trace back to and the seed the next session resumes from.
 4. Write `STATE: closed` + one-line reason. Print: _"Run `/brainstorm start` to resume."_
 
 ## Conduct — holds for the whole session

package/data/harnesses/code/skills/brainstorm/harvest.md

@@ -1,18 +1,17 @@
 # Harvest adapter
 
-Harvest is **optional and offered, never assumed**. By default the session folder is the product: a self-contained registry the next `/brainstorm start` resumes from. Run this adapter only when (a) the repo is v9-harnessed — `docs/architecture/` and `docs/modules/` exist — and (b) the user accepts the offer at `stop`.
+Harvest distils a closed session's **conclusions** into the live steering docs. It is **offered at `stop`, never forced** — but the `docs/brainstorm/{topic}/` record is **kept either way**: it is a committed design record, not a scratchpad, so harvest copies its conclusions outward and leaves the record in place as their provenance. (In a code-harnessed repo `docs/architecture/` and its `adr/` already exist, so the routing below always applies.)
 
 ## Routing
 
-The harvest is a structured diff between the session pillars and the live docs, routed by scope: module-local findings → `docs/modules/{m}/pillars/`, cross-module + IA/contract changes → `docs/architecture/`, backlog → `docs/history/`.
+The harvest is a structured diff between the session pillars and the live docs, routed by scope: doctrine / glossary / non-goals / IA / contract changes → `docs/architecture/`, decisions → `docs/architecture/adr/`, backlog → `docs/history/backlog.md`. Modules are labels, not folders — a finding scoped to one module's context still lands in `docs/architecture/` and names the module in prose; there is no module-local doc home.
 
 | Session source | Destination |
 | --- | --- |
 | `thesis.md` narrative | `docs/history/plans/YYYY-MM-DD-{slug}.md` (Status: Draft, `documentation` skill §8 Plan template) |
 | `domain-model.md` | `docs/architecture/domain-model.md`; if it changes the IA or a cross-cutting contract, note the contract change there — the `boundary` skill will pick it up from source at the next plan check |
-| Decisions spanning 2+ modules | one ADR per cohesive theme → `docs/history/adr/ADR-NNN-{slug}.md` (a historical decision record, not the deployed-design SOT in `docs/architecture/`), authored to the **`documentation` skill §10 ADR template** (frontmatter `status:` is the lifecycle source of truth — no body Status line; required sections Decision/Context/Consequences); rejected alternatives → the ADR's **Options Considered** table |
-| Module-local decisions / doctrine / glossary / rejected | `docs/modules/{m}/pillars/{decisions,doctrine,glossary,rejected}.md` |
-| Cross-module doctrine / glossary | `docs/architecture/domain-model.md` / `docs/architecture/glossary.md` |
+| Decisions (any scope) | one ADR per cohesive theme → `docs/architecture/adr/NNN-{slug}.md`, authored to the **`documentation` skill ADR template** (frontmatter `status:` is the lifecycle source of truth — no body Status line; required sections Decision/Context/Consequences); rejected alternatives → the ADR's **Options Considered** table |
+| Doctrine / glossary / rejected | `docs/architecture/domain-model.md` / `docs/architecture/glossary.md`, or the relevant ADR |
 | `tech.md` deviations | `docs/architecture/references.md` or the relevant ADR |
 | `non-goals.md` / `references.md` | `docs/architecture/{non-goals,references}.md` |
 | `backlog.md` | `docs/history/backlog.md` (P0–P3) |
@@ -23,4 +22,4 @@ Append a changelog entry at `docs/history/changelog/YYYY-MM-DD-brainstorm-harves
 
 ## After harvest
 
-Offer to delete the session folder (the dispersed homes now carry the content; the next session primes from them by copying relevant docs into `basis/`). Default to **keep** if the user is unsure — a kept folder simply resumes.
+**Keep the `docs/brainstorm/{topic}/` record — never delete it.** The dispersed homes now carry the distilled conclusions, but the record stays committed as their provenance: a traceable source for every harvested headline, the seed the next `/brainstorm start` on this topic resumes from, and a high-surprisal input the `distiller` ingests. Retire a topic's folder by hand only when the design line is truly dead.

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

@@ -38,13 +38,13 @@ Distill the inbox's undigested entries into fact-cards. The algorithm is in [`re
 
    **Thin or empty inbox ⇒ not a NOOP — distill the decision record.** A project whose sessions produced no reflected lessons is **not** a project with nothing to distill. Architecture decisions and reversals are high-surprisal by nature — they exist precisely because they were _not_ predictable. So when the inbox is thin/empty, also ingest, as surprisal sources for steps 2–5:
    - `docs/architecture/adr/**` — each accepted ADR is a surprising decision (its `Decision` + **Options Considered** — the rejected-alternatives section in the `documentation` §10 ADR template — carry the prediction error).
-   - `docs/memory/brainstorm.md` — owner pronouncements, reversals, and discovered constraints recorded outside the inbox. Provenance points at the ADR file / brainstorm section, not a session id. These sources are **never consumed** — reconciliation (step 4) is what keeps a re-run over them idempotent.
+   - `docs/brainstorm/{topic}/` — the kept Brainstorming-Mode design records (`pillars/decisions.md`, `rejected.md`, etc.): the reasoning, reversals, and roads-not-taken behind each design call, retained as committed provenance. The richest surprisal source the harness produces. (Where a repo keeps no brainstorm record in `docs/` — e.g. an older transient-workspace harness — fall back to `docs/memory/brainstorm.md`, the owner pronouncements recorded outside the inbox.) Provenance points at the ADR file / brainstorm pillar, not a session id. These sources are **never consumed** — reconciliation (step 4) is what keeps a re-run over them idempotent.
 
 2. **Surprisal filter → survivors** (method §1). Present the LLM with (a) a summary of the _current_ fact-set, (b) the undigested entries. Keep only what is **surprising** relative to (a). Predictable ⇒ dropped — no importance scores, no templates, prediction error is the only retention signal. Inbox entries arrive semi-distilled (the reflection hook already dropped routine work), so the filter's job here is narrower: drop what the existing fact-set already predicts. (First run, empty fact-set: keep decisions, reversals, discovered constraints, and failures with a cause worth remembering.)
 
 3. **Decompose survivors → EDU candidates** (method §2). Each survivor becomes **one** atomic, self-contained statement — entity names normalized, minimal context baked into the sentence — with `provenance` pointing at the session ids and commits its inbox entry names. Decomposition, **not** summarization: one survivor may yield several cards; no information is destroyed; everything stays auditable back to its session and commits.
 
-4. **Reconcile each candidate against existing cards** (method §3). Query the existing facts for semantic neighbors, then decide **ADD / UPDATE / SUPERSEDE / NOOP** for each. Gate on the **facts collection holding cards**, not on the binary and not on the collection merely being registered — a present qmd whose `{repo}-facts` collection is _registered but empty_ (the common first run: harness-manager's baseline registers + embeds `{repo}-facts` over a freshly-scaffolded `docs/memory/facts/` that has zero cards) returns nothing useful, exactly like an unregistered collection.
+4. **Reconcile each candidate against existing cards** (method §3). Query the existing facts for semantic neighbors, then decide **ADD / UPDATE / SUPERSEDE / NOOP** for each. Gate on the **facts collection holding cards**, not on the binary and not on the collection merely being registered — a present qmd whose `{repo}-facts` collection is _registered but empty_ (the common first run: the `maintenance` agent's baseline mode registers + embeds `{repo}-facts` over a freshly-scaffolded `docs/memory/facts/` that has zero cards) returns nothing useful, exactly like an unregistered collection.
    - **Cards present** — `command -v qmd` succeeds **and** `docs/memory/facts/` holds at least one card (`docs/memory/facts/*.md` is non-empty): query scoped to the collection — `qmd query --format json -c {repo}-facts "<the candidate statement>"`. `{repo}` = the repo's directory name. Scope with `-c` always. (If the query returns nothing on a non-empty card set, the collection is registered-but- unbuilt — treat that as the fallback trigger below, not as "no neighbors.")
    - **No cards to query** (qmd absent, **or** `docs/memory/facts/*.md` empty — the common first-run case where the facts dir was scaffolded but never distilled into): fall back to filename/grep similarity over `docs/memory/facts/*.md` (slug overlap + entity-name grep), and **note in the report** that reconciliation ran without semantic retrieval. Step 7 builds/refreshes the collection at the end of the run, so the _next_ run — with cards now present — reconciles semantically.
 
@@ -82,7 +82,7 @@ Distill fact-cards into proposed edits to `docs/` (the cold, human-owned SSoT)
 - **Supersede ≠ delete.** Bi-temporal only: set `invalid_from:` + `superseded_by:` on the old card and leave the file in place. Nothing is ever removed from `docs/memory/facts/`.
 - **Findings are questions, not verdicts.** When a candidate appears to contradict an existing card, phrase it as a question (is X now superseded by Y?) — never assert staleness or falsity.
 - **Never auto-runs.** Invoked by the user, by the Completion flow (kit `CLAUDE.md`), or by accepting the maintenance proposal. No cron, no daemon, no hook self-trigger — a workflow step the agent runs is not a self-trigger.
-- **qmd is strictly optional.** Guard every qmd call on `command -v qmd`; absent ⇒ silent skip. Reconciliation additionally needs the `{repo}-facts` collection to hold **cards** — not merely to be registered. "Unbuilt" here means **no cards** (`docs/memory/facts/*.md` empty), not "unregistered": harness-manager's baseline registers + embeds `{repo}-facts` over an empty scaffolded facts dir, so on a qmd-equipped, freshly-baselined repo the collection _appears in_ `qmd collection list` yet indexes zero cards. Binary present but collection cardless (first run) falls back to filename/grep too, same as qmd being absent.
+- **qmd is strictly optional.** Guard every qmd call on `command -v qmd`; absent ⇒ silent skip. Reconciliation additionally needs the `{repo}-facts` collection to hold **cards** — not merely to be registered. "Unbuilt" here means **no cards** (`docs/memory/facts/*.md` empty), not "unregistered": the `maintenance` agent's baseline mode registers + embeds `{repo}-facts` over an empty scaffolded facts dir, so on a qmd-equipped, freshly-baselined repo the collection _appears in_ `qmd collection list` yet indexes zero cards. Binary present but collection cardless (first run) falls back to filename/grep too, same as qmd being absent.
 
 ## Output locations
 

package/data/harnesses/code/skills/distiller/references/docs-mode.md

@@ -66,16 +66,16 @@ Read [`method.md`](method.md) (surprisal / EDU / reconciliation / bi-temporal vo
 ### 1. Resolve the target doc, read the three roots in order
 
 1. `method.md` (algorithm vocabulary).
-2. The **target doc** — full current prose + the `docs/routing.md` patterns that map to it (the paths it owns). This is the SSoT you are proposing to revise; you read it before you draft so conflicts surface as questions, not silent overwrites.
+2. The **target doc** — full current prose + the doc's `owns:` globs (the paths it owns). This is the SSoT you are proposing to revise; you read it before you draft so conflicts surface as questions, not silent overwrites.
    - `--doc <path>` → that doc.
-   - `--feature <slug>` / bare → the spec that just flipped to `Active` (Completion names it), or the feature doc whose `docs/routing.md` pattern covers the plan's Proposed-Changes paths. Match the routing patterns against changed paths. Architecture/operations docs own no paths in routing — for those, fall to entity/semantic match.
+   - `--feature <slug>` / bare → the spec that just flipped to `Active` (Completion names it), or the feature doc whose `owns:` glob covers the plan's Proposed-Changes paths. Match the `owns:` globs against changed paths. Architecture/operations docs declare no `owns:` — for those, fall to entity/semantic match.
    - No doc resolves → Edge Case A.
 3. The **pillar headlines** — the doctrine pillar (`## Pn —` headlines) and the decisions pillar (`## Dn —` headlines) plus each one's one-line Principle/Decision statement. Read **every** decision headline except those marked superseded: a decision carrying a `Reversed by D-M` marker (or a legacy `Status: tentative`) is NOT a binding pillar headline and is skipped; absence of any status marker means the decision is live (the new append-only model has no `Status: committed` field — a live decision is simply one nothing has reversed). Headlines only, never the bodies — this is the conservative contradiction-check substrate (Resolution 4).
 
 ### 2. INPUT SELECTION — gather the cards "touching" the target (Resolution 1) — _closes F2, F3, F5_
 
-1. **Structural retriever (always runs, qmd-independent).** Read every card in `docs/memory/facts/*.md`. A card _structurally touches_ the target when its `provenance` paths or `entities` intersect the target's `docs/routing.md` patterns — match defined precisely in Resolution 1.
-2. **Semantic retriever (qmd, optional).** If `command -v qmd` succeeds, for the target's identity (title + each routing-pattern stem + any `anchors:` query) run `qmd query --format json -c {repo}-facts "<the doc's subject>"`. `{repo}` = repo dir name; scope with `-c` always; repeat `-c` per relevant `{repo}-*` facts collection (the set `qmd collection list` names). qmd absent ⇒ skip silently, note in the report that selection ran structural-only (changes recall, not correctness).
+1. **Structural retriever (always runs, qmd-independent).** Read every card in `docs/memory/facts/*.md`. A card _structurally touches_ the target when its `provenance` paths or `entities` intersect the target's `owns:` globs — match defined precisely in Resolution 1.
+2. **Semantic retriever (qmd, optional).** If `command -v qmd` succeeds, for the target's identity (title + each `owns:`-glob stem + any `anchors:` query) run `qmd query --format json -c {repo}-facts "<the doc's subject>"`. `{repo}` = repo dir name; scope with `-c` always; repeat `-c` per relevant `{repo}-*` facts collection (the set `qmd collection list` names). qmd absent ⇒ skip silently, note in the report that selection ran structural-only (changes recall, not correctness).
 3. **Bi-temporal + digestion gate (F2, F3).** From the union, drop:
    - any card with `invalid_from` ≠ `null` (superseded — list as "skipped: superseded");
    - any card whose `digested_into:` already lists the target doc path (already consumed here);
@@ -169,8 +169,8 @@ A card **touches** the target doc iff it satisfies **either** retriever, and is
 
 **(a) Structural intersection (exact, always evaluated).** True when ANY of:
 
-1. **Provenance match (STRONG signal).** A `commit <sha>` entry in the card's `provenance` resolves to changed files (`git show --name-only <sha>` when the commit is local); a changed file under the target's `docs/routing.md` patterns is a match. (`session <id>` entries carry no paths and do not participate; an ADR/brainstorm path matches the patterns directly.) This is strong because the card derives from a commit that edited code the doc owns.
-2. **Entity match (SUPPORTING signal).** A normalized name in the card's `entities` equals (case-insensitively, after kebab/camel normalization) a module/feature stem in one of the target's `docs/routing.md` patterns, the doc title, or a symbol the doc explicitly names. **Bare prose mentions do NOT count** — only declared ownership (its routing patterns), so "touching" can't be triggered by a doc that merely discusses an entity it doesn't own.
+1. **Provenance match (STRONG signal).** A `commit <sha>` entry in the card's `provenance` resolves to changed files (`git show --name-only <sha>` when the commit is local); a changed file under the target's `owns:` globs is a match. (`session <id>` entries carry no paths and do not participate; an ADR/brainstorm path matches the globs directly.) This is strong because the card derives from a commit that edited code the doc owns.
+2. **Entity match (SUPPORTING signal).** A normalized name in the card's `entities` equals (case-insensitively, after kebab/camel normalization) a module/feature stem in one of the target's `owns:` globs, the doc title, or a symbol the doc explicitly names. **Bare prose mentions do NOT count** — only declared ownership (its `owns:` globs), so "touching" can't be triggered by a doc that merely discusses an entity it doesn't own.
 
 **(b) Semantic neighborhood (qmd, optional, recall-only).** A card returned by `qmd query -c {repo}-facts "<doc subject>"` within qmd's default result window. Semantic hits with **no** structural intersection are still candidates but flagged `[semantic-only]` in the delta — the link is associative, not provenance-grounded, so the reviewer treats it as lower-trust and may reject on link-strength alone.
 
@@ -189,7 +189,7 @@ A card may touch **several** docs (its entities span modules) — expected, hand
 | **`## Architecture` / `## Key Functions`** (feature doc) | Additive correction only when a card names a concrete, code-anchored fact (a new function, a moved file). Prefer Current Behavior unless the card is structural. | Code-anchored structure, not prose. |
 | **A new changelog entry** in `docs/history/changelog/` (via `documentation` skill's Changelog template, `### Added`/`### Modified`/`### Removed`) | Draft a changelog line for a code change a card witnesses, when a plan just completed. | Append-only history; a _new_ file, never an edit. |
 
-**Never writable by distill②** (hard stops): `## Goal`, `## Goals & Non-Goals`, `## Approach`, `## Open Questions`, `## State`, the optional `anchors:` frontmatter (the only frontmatter a doc carries; ownership lives in `docs/routing.md` — maintenance/spec axis — P19), any **pillar** file, any **plan** (frozen), any **existing** changelog entry (frozen history), any **boundary** file. A card implying one of these needs a change becomes a **question** (below) or, for pillars, an **escape item** (Resolution 4).
+**Never writable by distill②** (hard stops): `## Goal`, `## Goals & Non-Goals`, `## Approach`, `## Open Questions`, `## State`, the focal frontmatter (`owns`/`module`/`keywords`/`status`) and the optional `anchors:` block (ownership and discovery live there, on the spec/maintenance axis, not the distiller's — P19), any **pillar** file, any **plan** (frozen), any **existing** changelog entry (frozen history), any **boundary** file. A card implying one of these needs a change becomes a **question** (below) or, for pillars, an **escape item** (Resolution 4).
 
 **Per-line provenance (the invariant, mechanized).** Every drafted line carries `[from: fact-<slug>]` for each contributing card. A line with no such tag is a **defect** — not presented (Acceptance A2). On accept the tag is stripped from the final doc prose (it was review scaffolding); the durable forward-link survives as `digested_into:` (Resolution 3) — so traceability is preserved without polluting human-owned prose.
 

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

@@ -1,15 +1,15 @@
 ---
 name: documentation
-description: Template & generator library for technical docs — the skill agents call to produce a doc from a template. Use to (1) document a feature or module, (2) create or update a changelog entry, (3) document data flows or Redux state, (4) add to protected files, (5) record an architecture decision (ADR), (6) create or update the project root README, (7) create or update a plan, (8) derive the routing map (code path → canonical doc + module) for `docs/routing.md` from code, (9) scaffold a standard doc (README, structure.md, routing.md, CHANGELOG, backlog, memory) from its template, or (10) co-author any technical doc. Baselining / reconciling a repo's docs to the installed harness version is the **`harness-manager` agent** (which calls this skill for each template) — this skill does not orchestrate baseline. Triggers on "document this", "create docs", "update changelog", "add to protected files", "ADR", "architecture decision", "root README", "plan", "feature doc".
+description: Template & generator library for technical docs — the skill agents call to produce a doc from a template. Use to (1) document a feature or module, (2) create or update a changelog entry, (3) document data flows or Redux state, (4) add to protected files, (5) record an architecture decision (ADR), (6) create or update the project root README, (7) create or update a plan, (8) derive a feature doc's `owns:` frontmatter (the code-path globs it owns) from code, (9) scaffold a standard doc (README, structure.md, CHANGELOG, backlog, memory) from its template, or (10) co-author any technical doc. Baselining / reconciling a repo's docs to the installed harness version is the **`maintenance` agent (baseline mode)** (which calls this skill for each template) — this skill does not orchestrate baseline. Triggers on "document this", "create docs", "update changelog", "add to protected files", "ADR", "architecture decision", "root README", "plan", "feature doc".
 ---
 
 # Technical Documentation Skill
 
-**This skill is a template & generator library, not an orchestrator.** It supplies the templates, the routing-map-derivation generator, and the co-authoring workflow that _agents_ call to produce individual docs. It does **not** baseline, audit, or reconcile a repo's doc tree — that is the **`harness-manager` agent**, which calls this skill for each template it scaffolds. Reach here to generate _one_ doc from a template; reach for `harness-manager` to bring a whole repo into shape.
+**This skill is a template & generator library, not an orchestrator.** It supplies the templates, the frontmatter-derivation generator, and the co-authoring workflow that _agents_ call to produce individual docs. It does **not** baseline, audit, or reconcile a repo's doc tree — that is the **`maintenance` agent (baseline mode)**, which calls this skill for each template it scaffolds. Reach here to generate _one_ doc from a template; reach for the `maintenance` agent (baseline mode) to bring a whole repo into shape.
 
 Document contracts and architecture, not implementation details. Show function signatures and API shapes — never paste full implementations (they rot fast). Use ASCII diagrams over prose for flows. Only document state at persistence boundaries (Redux persistence, DB schemas, API shapes), not component-level or transient state. Mark deprecated fields with `// UNUSED:` comments. Breaking changes belong in changelogs only, not module docs.
 
-**No redirect docs.** When moving a doc to a new location, delete the old file entirely. Update all references (`docs/routing.md`, memory files, cross-doc links) to point to the new path. Never leave a stub file that says "Moved to X" — redirect docs rot, clutter the repo, and create false search hits.
+**No redirect docs.** When moving a doc to a new location, delete the old file entirely. Update all references (cross-doc links, memory files) to point to the new path. Never leave a stub file that says "Moved to X" — redirect docs rot, clutter the repo, and create false search hits.
 
 **Present tense, current state only.** Active docs (everything outside `docs/history/`) describe the system _as it is now_ — what exists and how it works today. They never narrate how it got there: no migration/fold history, no dated "shipped/verified/built on YYYY-MM-DD" markers, no "ex-`@nurix/X`, folded 2026-06-12" provenance, no "was X → now Y" change journeys, no "removed/deleted in the <date> fold". The historical record — when and how things changed — lives **only** in `docs/history/` (changelog, plans, ADRs); `docs/memory/` is the agent's dated log and is likewise exempt. A doc may cite an ADR for the _why_ (the decision rationale), but must not narrate the _when/how it changed_. Routing/index docs point only to current authority docs — never to a historical plan or changelog as the "read first" source. When you find historical narration in an active doc, rewrite it to the present-tense fact and let `docs/history/` carry the story.
 
@@ -20,7 +20,7 @@ Document contracts and architecture, not implementation details. Show function s
 ```
 User request
     │
-    ├─ "Baseline/reconcile docs" ──────▶ harness-manager agent (it calls this skill per template)
+    ├─ "Baseline/reconcile docs" ──────▶ maintenance agent (baseline mode) (it calls this skill per template)
     │
     ├─ "Document feature/module" ──────▶ Module Template
     │
@@ -54,25 +54,25 @@ User request
 
 ---
 
-## Routing-Map Derivation
+## Frontmatter Derivation
 
-When creating or updating a feature doc, derive its **`docs/routing.md` File-Pattern Routes row(s)** — the code paths it is canonical for — from the source the doc describes. Code ownership lives in `routing.md`, never in feature-doc frontmatter.
+When creating or updating a feature doc, derive its **`owns:` frontmatter** — the code-path globs it is canonical for — from the source the doc describes. Code ownership lives in each feature doc's `owns:` frontmatter (the SessionStart hook unions them into the injected ownership index); there is no hand-maintained ownership map.
 
 ### When to run
 
-- **Baseline / reconcile** — for every feature doc whose code paths aren't yet mapped in `routing.md` (the `harness-manager` agent calls this)
-- **New feature doc** — when creating a doc via the Feature/Module template, add its routing row(s)
-- **Doc update** — when the documented scope changes, update the doc's routing row(s)
+- **Baseline / reconcile** — for every feature doc whose code paths aren't yet declared in its `owns:` frontmatter (the `maintenance` agent (baseline mode) calls this)
+- **New feature doc** — when creating a doc via the Feature/Module template, project its `owns:` globs
+- **Doc update** — when the documented scope changes, update the doc's `owns:` globs
 
-### How to derive a row
+### How to derive the frontmatter
 
-A routing row is `| Pattern | Module | Canonical Doc | Memory |`.
+A feature doc's launch-map frontmatter is `owns:` (required), `module:` (optional), `keywords:` (required), and `status:` (required).
 
-**1. Pattern** (the path scope — the old `owns`)
+**1. `owns:`** (the path scope)
 
-Read the doc's content. Extract every source file path it references (file listings, function locations, component paths). Group them into the narrowest glob patterns that cover all referenced files without overlapping another doc's pattern at equal specificity. A doc may need several rows.
+Read the doc's content. Extract every source file path it references (file listings, function locations, component paths). Group them into the narrowest glob patterns that cover all referenced files without overlapping another doc's `owns:` globs at equal specificity. A doc may own several globs.
 
-| Doc references                       | Pattern                   |
+| Doc references                       | Glob                      |
 | ------------------------------------ | ------------------------- |
 | Multiple files under one directory   | `src/feature/**`          |
 | Specific files in a shared directory | List each file explicitly |
@@ -80,22 +80,22 @@ Read the doc's content. Extract every source file path it references (file listi
 
 Glob each pattern against the codebase; drop any that match nothing.
 
-**2. Module**
+**2. `module:`**
 
-The declared module the pattern belongs to (the `docs/modules/{m}/` it lives under), or `—` if the repo is flat. Rows sharing a Module value are what ties that module to code.
+The single bounded-context label this feature belongs to, or omit it for a cross-cutting feature that belongs to no single context. A module is a label, not a folder — features sharing a `module:` value are what ties that module to code (a filter over the generated ownership index).
 
-**3. Canonical Doc & Memory**
+**3. `keywords:` & `status:`**
 
-Canonical Doc = this doc's path (`features/…` when flat, `modules/{m}/features/…` when the module is declared). Memory = the `docs/memory/` file for the area, or `—`.
+`keywords:` are the discovery terms topic→doc lookup rides. `status:` is `active`, `draft`, or `deprecated` — it steers the model toward live docs and away from draft/deprecated ones.
 
-> The old `touches`/`depends_on` relationships are no longer recorded as ownership. A doc's dependencies on other docs are expressed inline in its prose (links); cross-cutting contracts are diagnosed by the `boundary` skill from source, not persisted.
+A doc's dependencies on other docs are expressed inline in its prose (links); cross-cutting contracts are diagnosed by the `boundary` skill from source, not persisted.
 
 ### Rules
 
-- One canonical doc per path. A pattern must not overlap another row at equal specificity — the narrower pattern wins; equal-specificity overlap is a conflict to resolve.
+- One canonical doc per path. A doc's `owns:` globs must not overlap another doc's at equal specificity — the narrower glob wins; equal-specificity overlap is an ownership conflict to resolve.
 - Use glob patterns for directories, explicit paths for individual files. Don't list paths that don't exist in the codebase.
-- When a doc covers a deep feature with sub-specs (e.g., `editor/`), each sub-spec gets its own row(s) — don't duplicate a path across siblings.
-- For baseline/reconcile with many docs, use parallel sub-agents to read source and propose rows.
+- When a doc covers a deep feature with sub-specs (e.g., `editor/`), each sub-spec owns its own globs — don't duplicate a path across siblings.
+- For baseline/reconcile with many docs, use parallel sub-agents to read source and propose `owns:` globs.
 
 ---
 
@@ -119,6 +119,6 @@ For docs that don't match templates:
 
 | File | Use For |
 | --- | --- |
-| `references/templates.md` | docs/README.md, structure.md, routing.md, scaffolds (CHANGELOG, backlog, memory), feature, changelog, plan, protected files, ADR, project root README templates |
+| `references/templates.md` | docs/README.md, structure.md, the feature-frontmatter contract, scaffolds (CHANGELOG, backlog, memory), feature, changelog, plan, protected files, ADR, project root README templates |
 | `references/style-guide.md` | Writing rules, formatting conventions |
 | `references/examples.md` | Good vs bad documentation examples |

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

@@ -60,6 +60,7 @@ Everything frozen or append-only.
 - [CHANGELOG.md](history/CHANGELOG.md) - Master changelog index
 - [changelog/](history/changelog/) - Individual changelog entries
 - [plans/](history/plans/) - Historical implementation plans
+- [research/](history/research/) - Deep-research artifacts (one folder per topic)
 - [backlog.md](history/backlog.md) - Tracked work items and technical debt
 
 ---
@@ -83,7 +84,7 @@ harness-version: 1.0.0
 # Documentation Structure
 
 > This file is the entry point for understanding the docs folder.
-> `harness-version` above is the repo's single baseline/version sentinel — the `harness-manager` agent owns it and stamps the installed harness version (semver) on every reconcile.
+> `harness-version` above is the repo's single baseline/version sentinel — the `maintenance` agent (baseline mode) owns it and stamps the installed harness version (semver) on every reconcile.
 
 ## Authority Map
 
@@ -91,13 +92,14 @@ Each topic has one canonical location. Read from here, not from plans or changel
 
 | Topic | Authority | Key Files |
 | ----- | --------- | --------- |
-| Code-path ownership (path → doc + module) | `docs/routing.md` | File-Pattern Routes |
+| Code-path ownership (path → doc + module) | feature `owns:` frontmatter | the generated ownership index |
 | System architecture + steering | `docs/architecture/` | domain-model, glossary, non-goals, references, adr/ |
-| Feature behavior | `docs/features/` (or `docs/modules/{m}/features/`) | {key files} |
-| Declared modules (bounded contexts) | `docs/modules/{m}/` | `features/` + `pillars/` |
+| Feature behavior | `docs/features/` | {key files} |
 | Setup & development | `docs/operations/` | {key files} |
 | Historical plans | `docs/history/plans/` | YYYY-MM-DD-name.md |
 | Change records | `docs/history/changelog/` | Individual entries |
+| Deep-research artifacts | `docs/history/research/{topic}/` | README.md + findings.md + sources.md |
+| Brainstorm design records | `docs/brainstorm/{topic}/` | state.md + pillars/ |
 | Backlog | `docs/history/` | backlog.md |
 
 ## Document Lifecycle
@@ -110,13 +112,13 @@ Plan (Status: Draft) → Implementation → Feature Doc or Architecture Update
 
 ## Folder Rules
 
-- `docs/routing.md`: The single hand-maintained map from code paths (and keywords) to the canonical doc and module for each. Code ownership lives here, not in feature-doc frontmatter. Update it whenever you add/move/delete a doc or move/rename owned source.
-- `docs/features/`: Living reference for implemented features. Carry **no** ownership frontmatter — a feature doc's code paths are declared by its row(s) in `docs/routing.md`. (An optional `anchors:` block — a qmd drift tripwire, see §3 — is the only frontmatter a doc may carry.)
-- `docs/architecture/`: System-wide patterns and the cross-module steering layer (domain model, glossary, non-goals, references, ADRs). Update when cross-cutting concerns change.
-- `docs/modules/{m}/`: Vertical bounded contexts, **declared** (not inferred from layout) and tied to code by their `docs/routing.md` patterns (the Module column groups routes into modules). Each owns `features/` + module-local `pillars/` (doctrine, lazy). There is no repo-wide `docs/pillars/`. Worth declaring at ≥2 genuine bounded contexts; a single-context app stays flat under `docs/features/`.
+- `docs/features/`: Living reference for implemented features. Each feature doc **carries** the `owns:` / `module:` / `keywords:` / `status:` frontmatter — `owns:` declares the code-path globs it owns (the only ownership key), `module:` is an optional bounded-context label, `keywords:` are discovery terms, `status:` is `active`/`draft`/`deprecated`. The SessionStart hook unions every feature's `owns:` globs into the injected ownership index. (An optional `anchors:` block — a qmd drift tripwire, see §3 — is a separate tooling key a doc may additionally carry.)
+- `docs/architecture/`: System-wide patterns and the cross-module steering layer (domain model, glossary, non-goals, references, ADRs). A module's cross-cutting prose lives here (or in a browse-folder `Readme.md`). Update when cross-cutting concerns change.
 - `docs/operations/`: How-to procedures for setup, development, and deployment. Update when workflows change.
 - `docs/history/plans/`: Historical. Must have `Status:` field. Never modify after completion.
 - `docs/history/changelog/`: Historical. Append-only.
+- `docs/history/research/{topic}/`: Deep-research artifacts — the dumped output of a research pass, one folder per topic (conventionally `README.md` synthesis + `findings.md` verified claims & citations + `sources.md`). A point-in-time, cited record — **not** a living authority doc: it owns no code (no `owns:` frontmatter) and is never edited to "stay current." A spec/plan links to it for grounding; a new question gets a new topic folder.
+- `docs/brainstorm/{topic}/`: Kept design records — the committed Brainstorming-Mode session for a topic (`state.md` + `pillars/`), written by the `brainstorm` skill and **kept** after harvest as the provenance the steering pillars distil from. Author-created (never scaffolded empty), one subfolder per design conversation. Owns no code (no `owns:` frontmatter); the harvest copies its conclusions into `architecture/`/`history/` while the record stays in place. Retire a topic's folder by hand only when the design line is dead.
 - `docs/history/backlog.md`: Tracked work items. Append new items under appropriate priority.
 
 ## Health Log
@@ -129,55 +131,11 @@ Plan (Status: Draft) → Implementation → Feature Doc or Architecture Update
 
 ---
 
-## 2.5 docs/routing.md (Code-Path Ownership Map)
-
-Use for: the single hand-maintained map from code paths (and keywords) to the canonical doc + module. This is the source of truth for code ownership — feature docs carry no ownership frontmatter. Scaffold it once any feature doc owns code.
-
-```
-# Routing
-
-The single map from code paths (and keywords) to the doc that is canonical for them, and the module each belongs to. The source of truth for code-path ownership — feature docs carry no ownership frontmatter. Read this before touching unfamiliar code, then read the mapped doc.
-
-> **One canonical doc per path.** When two patterns match the same path, the **narrower** pattern wins; an equal-specificity overlap is a conflict — resolve it before merging. Hand-maintained — there is no generator. Keep it in sync when you add/move/delete a doc or move/rename owned source.
-
-## File-Pattern Routes
-
-| Pattern | Module | Canonical Doc | Memory |
-| ------- | ------ | ------------- | ------ |
-| `src/auth/**` | auth | features/login.md | memory/main.md |
-| `src/billing/**` | billing | modules/billing/features/invoicing.md | — |
-
-- **Pattern** — the narrowest glob covering the files the doc is canonical for. A doc may have several rows.
-- **Module** — the declared module the pattern belongs to, or `—` if the repo is flat (no module declared). Grouping rows by this column is how a module is tied to code.
-- **Canonical Doc** — the one doc to read before changing matching files (`features/…` when flat, `modules/{m}/features/…` when the module is declared).
-- **Memory** — the `docs/memory/` file with domain knowledge for this area, or `—`.
-
-## Keyword Routes
-
-| Keyword / topic | Canonical Doc |
-| --------------- | ------------- |
-| auth, login, SSO, refresh | features/login.md |
-
-## Top-Level Folders
-
-| Folder | Purpose | Doc |
-| ------ | ------- | --- |
-| `src/` | {what lives here} | {doc} |
-
-## How to Add a Route
-
-1. Add/extend a **File-Pattern Routes** row — narrowest pattern that doesn't overlap an existing row at equal specificity; set its Module (or `—`).
-2. Add keyword row(s) for discoverability.
-3. When you move/rename owned source, update the matching pattern(s) here — this map is hand-maintained.
-```
-
----
-
 ## 3. Code-Path Ownership & Anchors
 
-**Ownership.** A feature doc is the canonical reference for the code paths mapped to it in `docs/routing.md` (File-Pattern Routes). Feature docs declare ownership through their routing row(s), **not** through frontmatter. To find what a doc owns, read its rows in `routing.md`; to find the doc for a path, match the path against the patterns there (narrower wins). See the **routing-map derivation** in `SKILL.md` for turning code into routing rows.
+**Ownership.** A feature doc is the canonical reference for the code paths in its **`owns:` frontmatter** — the only ownership key. To find what a doc owns, read its `owns:` globs; to find the doc for a path, match the path against the injected ownership index (the union of every feature's `owns:` globs), narrower glob wins. See **Frontmatter Derivation** in `SKILL.md` for turning code into `owns:` globs.
 
-**Anchors (optional — the only frontmatter a living doc may carry).** A doc may carry an `anchors:` block — a qmd drift tripwire, orthogonal to ownership:
+**Anchors (optional tooling key).** A doc may additionally carry an `anchors:` block — a qmd drift tripwire, orthogonal to ownership:
 
 ```yaml
 ---
@@ -186,7 +144,7 @@ anchors:
 ---
 ```
 
-`anchors` is a list of qmd queries (or `#docid`s) that re-resolve to the code/facts this doc abstracts as they move; anchors are retrieval context plus a drift tripwire, never a contract — an anchor that returns nothing IS the drift signal, nothing auto-rewrites from an anchor result, and the doc's prose stays the human-owned abstraction. They detect **doc-area drift** (the subject moving or vanishing from the corpus), not a pure code rename — the query also matches the doc's own prose, so a rename that leaves the text unchanged won't shift the result; code-symbol drift is the maintenance named-referent check's job, and anchors complement it rather than replace it. Resolved via `qmd query --format json -c <collection>` against this repo's collections; absent qmd ⇒ anchors are inert (no error). Never required on any doc. `anchors:` may appear on any living doc the maintenance anchor-drift check globs — `docs/features/`, `docs/architecture/`, and `docs/operations/`.
+`anchors` is an optional list of qmd queries (or `#docid`s) that re-resolve to the code a doc abstracts as it moves. It is a drift tripwire, never a contract — an anchor that returns nothing IS the drift signal, and nothing auto-rewrites from an anchor result. It is read on demand by the maintenance anchor-drift check, never injected, and inert when qmd is absent.
 
 ---
 
@@ -279,7 +237,7 @@ description: Shared knowledge accumulated across agent sessions. All agents shou
 ## Documentation Baseline
 
 - **Baselined:** {today}
-- **Structure:** v{harness-version} (architecture, features, operations, history, memory; + modules/, tests/ when present)
+- **Structure:** v{harness-version} (architecture, features, operations, history, memory; + tests/ when present)
 - **Spec version:** v{harness-version}
 <!-- v{harness-version} resolves to the installed harness version — read it from `.claude/harness.json` (`version`) / `docs/structure.md` frontmatter (`harness-version`); never hardcode a literal version here. -->
 
@@ -332,17 +290,21 @@ The four research-derived sections (**Affected Modules**, **Conventions to Follo
 
 ```yaml
 ---
-anchors: # optional — the only frontmatter a feature doc may carry; see §3
+owns: ["src/feature/**", "src/other/file.ts"]   # required — code-path globs this doc owns (the only ownership key)
+module: billing                                  # optional — single bounded-context label; omit if cross-cutting
+keywords: [invoice, pdf]                         # required — discovery terms
+status: active                                   # required — active | draft | deprecated
+anchors:                                         # optional extra — a qmd drift tripwire; see §3
   - "qmd query: wire envelope invariants"
 ---
 ```
 
-> This doc carries **no** ownership frontmatter. Declare the code paths it owns as File-Pattern Routes row(s) in `docs/routing.md` (§2.5) — projected at Draft, confirmed at Active.
+> Declare the code paths it owns in its `owns:` frontmatter — projected at Draft, confirmed against real code at Active.
 
 ```
 # {Feature Name}
 
-**Status:** Draft | Active   <!-- Draft: in design or in flight. Active: implemented and maintained. -->
+<!-- Lifecycle lives in the frontmatter `status:` key (active | draft | deprecated) — the single source of truth. Don't restate it in the body. -->
 **Plan:** [history/plans/YYYY-MM-DD-feature-name.md](../history/plans/YYYY-MM-DD-feature-name.md)   <!-- added once a plan exists -->
 
 ## Goal
@@ -385,7 +347,7 @@ High-level shape of the solution. ASCII diagram if it helps. Implementation spec
 
 ## Ownership Conflicts
 
-(From spec-mode research) Existing feature docs whose `docs/routing.md` patterns overlap with the projected scope. Resolve per row before the plan starts — leave nothing unresolved.
+(From spec-mode research) Existing feature docs whose `owns:` globs overlap with the projected scope. Resolve before the plan starts — leave nothing unresolved.
 
 | Conflicting doc | Overlapping path(s) | Resolution |
 |-----------------|---------------------|------------|
@@ -465,7 +427,7 @@ Sections fill in across the feature's lifecycle. No template swap — they accum
 | --- | --- | --- |
 | Status: Draft (design) | Goal, Goals & Non-Goals, Background, Approach, Open Questions, Risks | User interview |
 | Status: Draft (research) | Affected Modules, Conventions to Follow, Current Behavior, Ownership Conflicts | spec-mode agent |
-| Status: Draft → Active (implementation lands) | Architecture, Key Functions, State, Redux, Files; `docs/routing.md` row(s) confirmed against real code | Main agent (from actual code) |
+| Status: Draft → Active (implementation lands) | Architecture, Key Functions, State, Redux, Files; `owns:` globs confirmed against real code | Main agent (from actual code) |
 
 Resolved Open Questions can be summarized into Background; unresolved ones stay visible.
 
@@ -560,7 +522,7 @@ Why this work is happening *now*. Link to the spec for *what* we're building; th
 
 ### Cross-Module Contracts Affected
 
-- List which cross-cutting contracts this plan touches (db schema, wire envelope, auth, events, env/config, …)
+- List which cross-cutting contracts this plan affects (db schema, wire envelope, auth, events, env/config, …)
 - "None" is a valid answer and means the `boundary` check will pass cleanly
 
 ## Implementation Steps
@@ -572,7 +534,7 @@ Why this work is happening *now*. Link to the spec for *what* we're building; th
 ## Done Criteria
 
 - [ ] Implementation complete and verified
-- [ ] Affected docs updated (use `docs/routing.md` to find them)
+- [ ] Affected docs updated (use the injected ownership index to find them)
 - [ ] Changelog entry created in `docs/history/changelog/`
 - [ ] Plan marked `Status: Complete`, **Completed:** date filled
 
@@ -634,7 +596,7 @@ path/to/another/file.js
 
 ## 9. Architecture Decision Record (ADR)
 
-Use for: capturing a single, point-in-time architectural decision with its context, alternatives considered, and consequences. Lives in `docs/history/adr/` — an ADR is a **historical decision record**, not the deployed-design source of truth (which lives in `docs/architecture/`). When the design later changes, update `docs/architecture/` and write a new superseding ADR; never rewrite a shipped ADR.
+Use for: capturing a single, point-in-time architectural decision with its context, alternatives considered, and consequences. Lives in `docs/architecture/adr/` — co-located with the architecture it decides. An ADR is **immutable** once shipped: it records the decision as made, not the deployed-design source of truth (the living prose in `docs/architecture/`). When the design later changes, update `docs/architecture/` and write a new superseding ADR; never rewrite a shipped ADR.
 
 ### When to write an ADR
 

package/data/harnesses/etna/.prettierignore

@@ -0,0 +1,12 @@
+# Dependencies & build output
+node_modules
+dist
+build
+
+# Lockfiles
+pnpm-lock.yaml
+package-lock.json
+yarn.lock
+
+# Harness-managed agent/skill definitions (installed under .claude/)
+.claude

package/data/harnesses/etna/.prettierrc.json

@@ -0,0 +1,3 @@
+{
+  "proseWrap": "never"
+}

package/data/harnesses/etna/.vscode/settings.json

@@ -0,0 +1,10 @@
+{
+  // Markdown: Prettier unwraps prose to one logical line per paragraph
+  // (see .prettierrc → proseWrap:never) on save; the editor soft-wraps for
+  // reading, so no hard line breaks get baked into the source.
+  "[markdown]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true,
+    "editor.wordWrap": "on"
+  }
+}