@nurix/etna 0.18.11 → 0.18.13

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,15 @@ v1 applied a present-tense "greenfield" writing doctrine unconditionally — whi
 
 ---
 
-## Harvest (optional)
+## Exit artifacts
 
-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`, after the final sync, the skill _offers_ what to **publish** from it (`AskUserQuestion`, multi-select — a session can emit more than one):
+
+- **Source of truth** — one consolidated, README-style canonical doc for the thing designed (`templates/source-of-truth.md`); lands in the repo's feature/architecture doc home, else a topic `Readme.md`.
+- **Plans** — one or more executable plan docs → `docs/history/plans/` (Status: Draft).
+- **Harvest into the living docs** — conclusions dispersed by scope into ADRs, the domain model, and the backlog.
+
+The `docs/brainstorm/{topic}/` record is **kept** whichever you pick — never deleted; it is the provenance every artifact traces back to. See `exit-artifacts.md`.
 
 ---
 
@@ -118,7 +124,7 @@ By default the session folder _is_ the product — self-contained, resumed by th
 
 1. **No production code outside the session folder.** Illustrative snippets are fine inside it.
 2. **Speak English to the user; codes (`Q3`, `D7`) live in the files.**
-3. **`AskUserQuestion` appears in exactly three places:** the intake frame, interview mode, converge picks.
+3. **`AskUserQuestion` appears in exactly four places:** the intake frame, interview mode, converge picks, the `stop` exit-artifact pick.
 4. **Suggested, never seized** — mode shifts, abstractions, probes are offered once.
 5. **Questions are the only convergence currency** — nothing pending may live only in the transcript.
 6. **No auto-invocation** — only `/brainstorm start` and `/brainstorm stop`.
@@ -128,9 +134,11 @@ By default the session folder _is_ the product — self-contained, resumed by th
 ## Files
 
 ```
-brainstorm/
-├── 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
+brainstorm/                  # the skill (in .claude/skills/)
+├── SKILL.md          # the skill definition Claude Code loads (~1.8k words)
+├── README.md         # this file
+├── exit-artifacts.md # what /brainstorm stop publishes: source-of-truth / plans / harvest
+└── templates/        # pillar templates + source-of-truth.md, used in the record and at stop
 ```
+
+The session itself is written to `docs/brainstorm/{topic}/` (kept, committed) — not here.

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

@@ -6,7 +6,7 @@ argument-hint: "start | stop"
 
 # Brainstorm
 
-Think with the user, then file — never the reverse. The artifacts exist to serve the conversation; the conversation never exists to populate artifacts. The constant across every scale of idea is **the loop**; everything else — pillar count, ceremony, harvest — scales with complexity.
+Think with the user, then file — never the reverse. The artifacts exist to serve the conversation; the conversation never exists to populate artifacts. The constant across every scale of idea is **the loop**; everything else — pillar count, ceremony, exit artifacts — scales with complexity.
 
 ## The loop — every turn, every mode
 
@@ -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 the exit artifacts publish (it is the provenance they distil from — see `exit-artifacts.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. **Publish exit artifacts** — see `exit-artifacts.md`. Offer the choice (`AskUserQuestion`, multi-select): a **source of truth** (one consolidated README-style doc — the standing reference for the thing designed), **plans** (executable work → `docs/history/plans/`), and/or **harvest into the living docs** (conclusions dispersed by scope into ADRs, the domain model, the backlog). The `docs/brainstorm/{topic}/` record is **kept** (committed) whichever you pick — it is the provenance every artifact traces 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
@@ -129,7 +129,7 @@ Zero means _"audited against the four sources and clean"_ — never _"nothing ca
 1. **Speak English; codes live in files.** In conversation, name every pillar item by what it _is_ in plain words. Append the code in parentheses only when traceability needs it (_"…can a user change answer depth? (tracked as Q6)"_). Never lead with a bare `Q3`/`D7`. The user is not looking at the files.
 2. **No production code outside the session folder.** Illustrative load-bearing snippets are fine inside it (`samples/` or fenced in pillars). If asked for production code: offer a sketch inside the folder, or `/brainstorm stop` first.
 3. **The writing posture comes from `build.md`'s mode.** Greenfield: every pillar describes the system as it _will be_, present tense, as though the chosen design was always the plan — no migration vocabulary, no phantom history (banned list in `templates/build.md`). Brownfield/hybrid: migration vocabulary is legitimate, and `build.md` is its home; other pillars still describe the _target_ state.
-4. **`AskUserQuestion` appears in exactly three places:** the intake frame batch, interview mode, and converge picks. Everywhere else: prose.
+4. **`AskUserQuestion` appears in exactly four places:** the intake frame batch, interview mode, converge picks, and the `stop` exit-artifact pick. Everywhere else: prose.
 5. **Suggested, never seized.** Mode shifts, abstractions, probes — one offer each, accept refusal without re-litigating.
 6. **Questions are the only convergence currency.** Flaws, gaps, contradictions, uncovered aspects — everything unresolved funnels into `questions.md` or it doesn't exist. Nothing pending may live only in the conversation transcript.
 7. **No auto-invocation.** Only `/brainstorm start` and `/brainstorm stop` enter or leave a session. Read `state.md` at the start of every turn while a session folder exists.

package/data/harnesses/code/skills/brainstorm/exit-artifacts.md

@@ -0,0 +1,62 @@
+# Exit artifacts
+
+What `/brainstorm stop` publishes from a closed session. The `docs/brainstorm/{topic}/` record is **kept
+either way** — committed provenance, never a scratchpad. Exit artifacts copy the session's _conclusions_
+outward into the form the work needs; the record stays as the source they trace back to.
+
+At `stop`, after the final sync, **offer the artifact choice** (`AskUserQuestion`, multi-select — a session
+can publish more than one):
+
+| Artifact | Use when the outcome is… | Lands in | Voice |
+| --- | --- | --- | --- |
+| **Source of truth** | a standing reference — "what this thing **is**" | the repo's feature/architecture doc home, else a topic `Readme.md` | README — present tense, reader-first (`templates/source-of-truth.md`) |
+| **Plans** | work to execute — "what to **build**, in what order" | one or more `docs/history/plans/YYYY-MM-DD-{slug}.md` (Status: Draft) | plan — steps, sequencing, status |
+| **Harvest into living docs** | findings that belong inside an existing doc system | dispersed by scope (table below) | matches each destination |
+
+A session commonly emits a **source of truth** for the thing designed _and_ **plans** for building it.
+Picking "source of truth" does **not** also disperse headlines across the doc tree — that is what "harvest"
+does; pick it too if you want both the one-doc reference and the integrated headlines.
+
+## Source of truth
+
+One consolidated, README-style document — the canonical reference for the thing designed. Distil every
+pillar into it: `thesis.md` → what it is; `domain-model.md` → how it works + parts; `decisions.md` →
+present-tense rationale (no `D-N` codes, no options-considered — those stay in the record and ADRs);
+`non-goals.md` + accepted tradeoffs → constraints; still-open questions → a one-line pointer back to the
+record. Template: `templates/source-of-truth.md`.
+
+Place it at the repo's canonical home for that kind of knowledge: a feature/system → `docs/features/{slug}.md`
+(carry the doc system's `owns:` / `module:` / `keywords:` / `status:` frontmatter); cross-cutting →
+`docs/architecture/{slug}.md`; no doc taxonomy → a `Readme.md` at the topic's folder. One document — if a
+section outgrows it, link out rather than sprawl.
+
+## Plans
+
+One or more executable plan docs in `docs/history/plans/` (Status: Draft), authored to the `documentation`
+skill's §8 Plan template. Source: the `thesis.md` narrative for scope, `build.md` for migration strategy /
+gotchas / rollout (execution content is plan content, not architecture). Split by deliverable, not by pillar
+— one plan per cohesive unit of work.
+
+## Harvest into living docs
+
+A structured diff between the session pillars and the live docs, dispersed by scope. Modules are labels,
+not folders — a finding scoped to one module still lands in `docs/architecture/` and names the module in prose.
+
+| Session source | Destination |
+| --- | --- |
+| Decisions (any scope) | one ADR per cohesive theme → `docs/architecture/adr/NNN-{slug}.md` (`documentation` skill ADR template; `status:` frontmatter is the lifecycle source of truth; rejected alternatives → the ADR's Options Considered table) |
+| `domain-model.md` | `docs/architecture/domain-model.md`; note any IA / cross-cutting contract change there — the `boundary` skill reads it from source at the next plan check |
+| Doctrine / glossary / rejected | `docs/architecture/{domain-model,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) |
+| Still-open questions | `docs/architecture/open-questions.md`, each with a _Resolution lands in_ pointer |
+
+Append a changelog entry at `docs/history/changelog/YYYY-MM-DD-brainstorm-{slug}.md` listing what was published where.
+
+## After publishing — keep the record
+
+**Keep `docs/brainstorm/{topic}/` — never delete it.** The exit artifacts now carry the distilled
+conclusions, but the record stays committed as their provenance: a traceable source for every published
+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/brainstorm/templates/source-of-truth.md

@@ -0,0 +1,49 @@
+# [Thing] — source of truth
+
+> This is a **source-of-truth doc**: the standing, canonical reference for [thing]. Write it like a
+> README — present tense, reader-first, the thing described as it _is_. It is **not a plan** (no steps,
+> status, or sequencing — those go to `docs/history/plans/`) and **not the brainstorm record** (no
+> `Q-N`/`D-N` codes, no "Why / How to apply" ledger, no rejected alternatives — those stay in
+> `docs/brainstorm/{topic}/` and any ADRs). One document; if a section outgrows it, link out, don't sprawl.
+>
+> **Placement.** In a repo with a feature-doc system this lands as `docs/features/{slug}.md` and carries
+> that system's frontmatter (`owns:` / `module:` / `keywords:` / `status:`). Cross-cutting → `docs/architecture/{slug}.md`.
+> No doc taxonomy → a `Readme.md` at the topic's home.
+
+## What it is
+
+[One paragraph, present tense: what the thing is, what it does, who uses it. Distilled from `thesis.md`.]
+
+## How it works
+
+[The model — entities, relationships, the main flow — lifted from `domain-model.md` into plain,
+reader-first description. Prose and tables; a diagram only if it earns its tokens.]
+
+## Parts
+
+[One row per component / module / piece: name · role · what it owns · what it depends on.]
+
+| Part | Role | Owns | Depends on |
+| --- | --- | --- | --- |
+|  |  |  |  |
+
+## Why it's shaped this way
+
+[The load-bearing decisions, folded into present-tense rationale — "the index is single-writer because
+concurrent writes corrupted it," not "we decided X over Y." No decision codes, no options-considered
+table. The full rationale and the roads not taken live in the brainstorm record and ADRs — cite them,
+don't reproduce them.]
+
+## Constraints & non-goals
+
+[Accepted tradeoffs phrased as current fact ("a 5-second lag is accepted for predictable throughput")
+and what is explicitly out of scope.]
+
+## Open questions
+
+[One line pointing at `docs/brainstorm/{topic}/pillars/questions.md` if any remain open. Omit if none.]
+
+---
+
+_Distilled from `docs/brainstorm/{topic}/`. That record holds the rationale, the rejected alternatives,
+and the provenance for everything above._

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 |