@nurix/etna 0.18.11 → 0.18.12

package/data/harnesses/etna/CLAUDE.md

@@ -26,12 +26,12 @@ For new features or new systems, enter **Spec Mode** before Plan Mode.
 
 1. **Spec Mode**: Create or update a feature spec in `docs/features/{feature}.md` using the **Feature Documentation template** (Status: Draft) — see `.claude/skills/documentation/references/templates.md` §6. Use the **`spec-mode`** agent (`.claude/agents/spec-mode.md`) for codebase research; its findings drop directly into the template's research-derived sections (Affected Modules, Conventions to Follow, Current Behavior, Ownership Conflicts). Interview the user for the design-intent sections (Goal, Goals & Non-Goals, Background, Approach). Present the spec for approval before proceeding.
 
-2. **Plan Mode**: Once the spec is approved, create a plan in `docs/history/plans/YYYY-MM-DD-feature-name.md` using the **Plan template** (see `.claude/skills/documentation/references/templates.md` §8). Link back to the feature spec in the **Spec** field. The template's **Proposed Changes** sections are load-bearing — the `boundary` skill (`check` mode) parses them to check boundary impact.
+2. **Plan Mode**: Once the spec is approved, create a plan in `docs/history/plans/YYYY-MM-DD-feature-name.md` using the **Plan template** (see `.claude/skills/documentation/references/templates.md` §8). Link back to the feature spec in the **Spec** field. The template's **Proposed Changes** sections are load-bearing — the `boundary` skill parses them to check boundary impact.
 
 3. **Completion**: When a plan is fully implemented:
    - Mark the plan `Status: Complete` in `docs/history/plans/` and fill the **Completed:** date. The plan is now frozen.
-   - **Flip the feature spec** to `Status: Active` and extend it in place with the implementation sections (Architecture, Key Functions, State, Redux, Files). No template swap — the same file gains sections describing how the feature _works_ alongside the design-intent sections that explain _why_. Confirm `owns`/`touches` frontmatter against actual code; resolve any unresolved Open Questions by folding them into Background.
-   - If `docs/routing.md` exists, use it to find other docs affected by the changes; otherwise glob `docs/features/**/*.md` and check `owns`/`touches` frontmatter. Update affected docs — or create new ones if a touched area has no doc yet.
+   - **Flip the feature spec** to `status: active` and extend it in place with the implementation sections (Architecture, Key Functions, State, Redux, Files). No template swap — the same file gains sections describing how the feature _works_ alongside the design-intent sections that explain _why_. Confirm the feature's `owns:` globs against actual code; resolve any unresolved Open Questions by folding them into Background.
+   - Use the injected ownership index to find other docs affected by the changes (and update the `owns:` globs of any feature doc whose source you moved or added). Update affected docs — or create new ones if a touched area has no doc yet.
 
 For **Product-level** work (new systems, unclear scope), the spec should also include: problem statement, key hypotheses, and open questions.
 
@@ -41,9 +41,10 @@ For **Product-level** work (new systems, unclear scope), the spec should also in
 
 Before modifying code in an unfamiliar area:
 
-1. If **[`docs/routing.md`](docs/routing.md)** exists, read it for file-pattern → doc/agent mapping. If it doesn't exist yet, skip — the codebase may not have owned features.
-2. Glob `docs/features/**/*.md` and check `owns` frontmatter to find the owning feature doc; read it before making changes.
-3. If a `docs/memory/` file exists for the domain you're working in, read it for domain knowledge and failure modes
+1. Consult the **injected ownership index** — the generated `glob → doc · module · keywords · status` map, surfaced into context at session start (the union of every feature doc's `owns:` frontmatter). Match your path or topic (its `keywords:`) to the owning doc and read it before changes. (If no ownership index appears in context, the repo isn't reconciled — run `maintenance` in baseline mode to reconcile it.)
+2. If `qmd` is installed, run `qmd query --format json -c <collection> "<topic>"` for semantic recall over the indexed docs — prefer it when entering an unfamiliar area; absent ⇒ skip.
+3. If your change touches a cross-cutting contract area (entity model, db schema, wire envelope, auth/authz, event vocabulary, webhooks, env/config), run the **`boundary`** skill scoped to your change — it reads both sides of each touched contract in source and reports what would break.
+4. If a `docs/memory/` file exists for the domain you're working in, read it for domain knowledge and failure modes
 
 For the protocol on _writing_ to memory (which file, what belongs there, what doesn't), see **Project Memory** below.
 
@@ -71,24 +72,19 @@ When implementing a plan, if you discover work that is important but outside the
 
 ### Doc Ownership
 
-Feature docs in `docs/features/` must include YAML frontmatter with `owns`, `touches`, and `depends_on` fields. Architecture docs describe cross-cutting patterns and don't own specific files; operations docs describe procedures. Only feature docs need frontmatter.
+Which doc is canonical for which code paths is the **feature doc's own frontmatter**. A feature doc (flat in `docs/features/`) carries `owns:` (code-path globs — the only ownership key), `module:` (a bounded-context label, omitted when cross-cutting), `keywords:` (discovery), and `status:`. Code → doc ownership is the union of every feature doc's `owns:` globs, surfaced as the generated ownership index at session start. Architecture docs describe cross-cutting patterns and don't own specific files; operations docs describe procedures. A living doc may additionally carry an optional `anchors:` block (a qmd drift tripwire, not ownership).
 
-The spec-mode agent checks for ownership conflicts during research. If conflicts are found, address them in the spec before proceeding.
+The spec-mode agent checks for ownership conflicts during research — feature docs whose `owns:` globs overlap at equal specificity. If conflicts are found, address them in the spec before proceeding.
 
 ---
 
 ## Boundaries
 
-`docs/boundaries/` documents the repo's **typed application boundaries** — cascading failure boundaries where editing one module silently breaks another (shared state shapes, entity registration, cross-module string coupling, persistence rehydration, etc.). One component owns this surface — the **`boundary` skill** — with four modes over a shared `references/boundary-taxonomy.md`:
+A boundary is a horizontal cross-cutting contract — entity model, db schema, wire envelope, auth/authz, event vocabulary, webhooks, env/config — where editing one side silently breaks the other. Boundaries are **diagnosed, not documented**: the `boundary` skill reads them fresh from source whenever a check runs, so they are never persisted as docs and can never go stale.
 
-- **`generate`** — baseline `docs/boundaries/` from the detected stack + IA
-- **`create`** — add or update a single boundary file
-- **`check`** — pre-implementation: check a proposed plan against `docs/boundaries/`, surfacing cascading risk early (the boundary's severity sets review depth)
-- **`init`** — reconcile + scan the live codebase for boundary violations + drift
+**Invoke the `boundary` skill after a plan is approved and before its first implementation step.** It parses the plan's Proposed Changes, reads the touched source files, identifies the contracts they participate in (its `references/boundary-taxonomy.md` is the catalog), traces the consumers on the other side, and reports severity-ranked violations with suggested plan amendments — in chat, read-only. Fold the amendments into the plan before coding. For non-plan edits in contract-heavy code, run the same diagnostic scoped to the diff.
 
-Without `docs/boundaries/` populated (`generate`), the `check` and `init` modes have nothing to check against.
-
-> Agents and skills available in this harness come from the bound plugin (`plugin: code` above). Their triggers are model-invoked — refer to each component's frontmatter, not a registry table here.
+> Agents and skills live under `.claude/agents/` and `.claude/skills/`. Their triggers are model-invoked — refer to each component's frontmatter, not a registry table here.
 
 ---
 
@@ -117,7 +113,7 @@ Unless explicitly requested:
 
 ### Folder Structure
 
-The six procedural folders below are fixed. Domain folders (e.g. `core/`) live as subfolders inside these — `docs/architecture/core/` for core module internals, `docs/features/{feature}/` for deep features. Discovery still flows through **[`docs/routing.md`](docs/routing.md)** when present.
+The six procedural folders below are fixed. Domain folders (e.g. `core/`) live as subfolders inside these — `docs/architecture/core/` for core module internals, `docs/features/{group}/` as browse-only groupings (never modules). Discovery flows through the generated **ownership index** (from feature `owns:`/`keywords:` frontmatter), injected at session start.
 
 | Folder | Purpose | Mutability |
 | --- | --- | --- |
@@ -139,22 +135,17 @@ The six procedural folders below are fixed. Domain folders (e.g. `core/`) live a
 
 - **Prerequisite**: Before creating changelogs, feature docs, or plans, check that `docs/memory/index.md` exists and records a baseline. If not, prompt the user to baseline docs first.
 - After plan completion: create a `docs/history/changelog/YYYY-MM-DD-feature-name.md` entry + update the index in `docs/history/CHANGELOG.md` (no confirmation needed). Root-level `CHANGELOG.md` is not used — only `CLAUDE.md`, `AGENTS.md`, and `README.md` live in the repo root.
-- Update related docs affected by the changes (use `docs/routing.md` to find the right files if present; otherwise check `owns`/`touches` frontmatter in `docs/features/`)
+- Update related docs affected by the changes (use the injected ownership index — feature `owns:` globs — to find the right files)
 - Non-plan changes (refactors, bug fixes, API changes): prompt user first
 - Multi-commit changes: include `Commits: abc1234, def5678`
 
 ### Keeping the Loop Tight
 
-When you create, move, or delete a doc:
+When you create a new doc that owns code:
 
-- If **[`docs/routing.md`](docs/routing.md)** exists, update it — file-pattern routes and keyword routes
-- If creating a new top-level domain folder and routing.md exists: add the folder to routing.md's **Top-Level Folders** table
+- Declare the code paths it owns in its own `owns:` frontmatter (plus `module:`/`keywords:`/`status:`); the generated ownership index picks it up at the next session start.
+- Verify its `owns:` globs don't overlap another feature doc's at equal specificity.
 
 When you move or rename source files:
 
-- Check `owns`/`touches` frontmatter in the owning doc. Find the owning doc via `docs/routing.md` if present; otherwise glob `docs/features/**/*.md` and match against `owns` patterns. Update paths to match the new locations.
-
-When you create a new doc that owns code:
-
-- Add `owns`, `touches`, `depends_on` YAML frontmatter
-- Verify `owns` globs don't conflict with existing docs (compare against `owns` frontmatter across `docs/features/`)
+- Update the `owns:` globs of the feature doc that owns them to the new paths.

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

@@ -14,7 +14,7 @@ You are a **thin orchestrator.** Every mechanic — the constant loop, the four
 ## When to offer a session
 
 - An explicit ask to think through a design at a strategic level (not "fix this bug" / "add this button"). This is the user invoking the work; hand it to `/brainstorm start`.
-- A user utterance **challenges a loaded pillar headline.** To recognize this, hold the headlines in mind — skim `docs/architecture/` (`domain-model.md`, `glossary.md`, `non-goals.md`, `open-questions.md`) and any `docs/modules/*/pillars/`. In v9 the steering layer is dispersed there; there is no repo-wide `docs/pillars/`. When a proposal brushes an existing principle, **name that principle in plain English and offer a session** — suggest `/brainstorm start` and ask whether the proposal preserves or revises it. Detection is yours; entry is the user's. **Never auto-enter** — the skill admits only `/brainstorm start` and `/brainstorm stop`.
+- A user utterance **challenges a loaded pillar headline.** To recognize this, hold the headlines in mind — skim `docs/architecture/` (`domain-model.md`, `glossary.md`, `non-goals.md`, `open-questions.md`) and its `adr/` decision titles. The steering layer lives there; there are no `docs/modules/` or `docs/pillars/` folders. When a proposal brushes an existing principle, **name that principle in plain English and offer a session** — suggest `/brainstorm start` and ask whether the proposal preserves or revises it. Detection is yours; entry is the user's. **Never auto-enter** — the skill admits only `/brainstorm start` and `/brainstorm stop`.
 
 If none of those steering files exist yet (a freshly-baselined repo), a session still runs from the skill's templates, and the basis gate seeds it from a reference doc or a one-shot brain dump.
 
@@ -28,8 +28,8 @@ Four modes exist — **dump / interview / probe / converge** — and they change
 - **Suggest, never seize.** Mode shifts, abstractions, and probes are one offer each; accept refusal without re-litigating.
 - **Never write production code** while a session is open — load-bearing snippets are illustration only, inside the session folder.
 
-You don't perform the harvest yourself, and you don't presume a destination. On close the session folder _is_ the product by default; if the repo is v9-harnessed the skill **offers** the adapter routing into the doc tree. The skill's `## stop` section is the canonical harvest map — don't duplicate it.
+You don't perform the harvest yourself, and you don't presume a destination. On close the skill **offers** the harvest, distilling the pillars' conclusions into wherever the harness routes them. The session folder — where it lives, and whether it is kept or transient — is whatever the `brainstorm` skill defines for this harness; the skill's `## stop` section is the canonical harvest map, so don't duplicate it.
 
 ## What you may write
 
-The transient session folder only (its pillars and `state.md`). Never edit the live docs directly — the harvest does that.
+The session folder only (its pillars and `state.md`), wherever the `brainstorm` skill places it for this harness. Never edit the live docs directly — the harvest does that.

package/data/harnesses/etna/agents/change-review.md

@@ -33,7 +33,7 @@ The heatmap needs rolling 1w / 1m / 3m windows, so default `since` to 3 months e
 
 1. If `./docs/memory/change-review.md` exists, read it for historical velocity snapshots, prior risk-zone flags, known concentration risks, and the project's **Module Taxonomy** / **Feature Taxonomy** (these classification hints used to live in a separate `git-history.md` memory file — they now live here).
 2. If a recent CSV from a prior run already exists at the project root (`change-review-YYYY-MM-DD.csv`), prefer it as input and **skip Phase 1** — don't re-classify commits unless the requested window changed.
-3. Read `./docs/routing.md` File-Pattern Routes to map churn to owning feature docs (and their modules).
+3. Build the ownership map from feature `owns:` frontmatter — consult the injected ownership index (`glob → doc · module · keywords · status`), or glob `docs/features/**/*.md` and read each doc's `owns:` globs — to map churn to owning feature docs (and their `module:` labels).
 
 ---
 
@@ -207,8 +207,8 @@ Trend column: ↑ rising, ↓ falling, → steady, ↑↑ sharply rising, ↓↓
 For each module with high churn (top quartile in 1m window), check how contract-heavy and how covered it is:
 
 - Does its code own cross-cutting contract surfaces (schema/data access, wire handlers, auth/authz, event dispatch, env/config readers)? Skim the module's files to judge — contract-heavy churn is where silent breakage lives.
-- Is the module's `owns` doc up to date? (cross-reference with the maintenance agent's last drift check if available)
-- Does the module appear in `docs/routing.md`?
+- Is the module's owning feature doc up to date? (cross-reference with the maintenance agent's last drift check if available)
+- Do the module's code paths appear under any feature doc's `owns:` globs?
 
 Flag risk zones: high churn × contract-heavy × low doc coverage. These are where silent breakage is most likely.
 
@@ -231,7 +231,7 @@ Per module, list which authors made the most commits in the 3-month window. Surf
 - **Risk zones**: top 5 high-churn modules that own contract-heavy surfaces, with the specific contracts at risk named
 - **Stabilization signals**: modules where review overhead can decrease
 - **Concentration risks**: bus-factor and review-coverage flags
-- **Recommendations**: prioritized list — typically "run the `boundary` skill on changes touching X", "update routing.md to cover Y", "spread reviews of Z across more authors"
+- **Recommendations**: prioritized list — typically "run the `boundary` skill on changes touching X", "add `owns:` coverage for Y to a feature doc", "spread reviews of Z across more authors"
 
 ### Update tracking
 

package/data/harnesses/etna/agents/maintenance.md

@@ -1,122 +1,240 @@
 ---
 name: maintenance
-description: Docs-vs-code coherence audit. Detects and fixes docs drifting from code — stale docs, broken ownership, routing table drift, unowned source paths. Run weekly or after major changes. Cross-cutting contract analysis is the `boundary` skill (`check` for plans, `scan` for diffs) — it derives contracts dynamically from source; there are no persisted boundary docs to audit.
+description: The single docs steward. Default behavior is the docs-vs-code coherence audit — detects and fixes docs drifting from code (stale docs, broken ownership, unowned source paths, architecture/backlog drift). An additive **baseline mode** layers structural reconcile on top: when the repo's `harness-version` marker is missing or behind, it converges `docs/` to the installed harness shape (scaffold the standard tree, fold dissolved-shape artifacts forward, stamp the version, propose modules) before running the audit. Mode is auto-selected from the marker. Run weekly, after major changes, or to baseline/upgrade a repo. Cross-cutting contract analysis is the `boundary` skill (`check` for plans, `scan` for diffs) — it derives contracts dynamically from source; there are no persisted boundary docs to audit. Triggers on "run maintenance", "docs health", "baseline this repo", "reconcile the harness", "upgrade the harness", "is this repo on the current harness", "/maintenance".
 tools: Read, Glob, Grep, Edit, Write, Bash
 model: inherit
 ---
 
 # Maintenance Agent
 
-You maintain codebase coherence by detecting drift between docs and code, and fixing it. Scope: stale feature docs, broken ownership, routing table drift, architecture drift, unowned source paths, backlog health.
+You are the **single docs steward**. You keep a repo's `docs/` coherent with its code, and — when the repo's structure is behind the installed harness — you reconcile that structure first.
+
+Two layers, one agent:
+
+- **Coherence audit (default, the spine).** Is the documented behavior _true_ of the code? Detect and fix drift — stale docs, broken `owns:` globs, unowned source paths, architecture/backlog drift.
+- **Baseline mode (additive).** Is the governance _structure_ shaped to the installed harness version? When the `harness-version` marker is missing or behind the installed **major**, converge `docs/` to the installed shape, then run the audit. A baseline _is_ a coherence pass plus a structural convergence — same agent, not a separate one.
 
 Out of scope (handled by the `boundary` skill, which derives contracts dynamically from source):
 
 - **Pre-implementation impact analysis** (checking a plan against cross-cutting contracts before coding) → `boundary` skill, `check` mode
 - **Diff-scoped contract analysis** (what could a change break across module edges) → `boundary` skill, `scan` mode
 
-## Before Starting
+## Mode selection
+
+Decide the mode once, up front, from the version marker — then run.
+
+1. Resolve the **installed harness version** (semver): read `version` from `.claude/harness.json`, shipped by the CLI at install. Never a number baked into this file. If `.claude/harness.json` is absent, the install predates the marker ⇒ instruct the user to re-run `npx @nurix/etna --name=<harness>`, then retry. The resolved version's **major** is the structural-shape signal — a major bump means the mandated `docs/` shape changed.
+2. Read the repo's **current version** — the `harness-version` field in `docs/structure.md` frontmatter (a semver).
+   - **Absent** ⇒ the repo is unharnessed ⇒ **baseline mode** (reconcile from nothing), then audit.
+   - **Behind on major** ⇒ the mandated shape changed ⇒ **baseline mode** (reconcile across the gap), then audit.
+   - **Behind on only minor/patch** ⇒ the shape is unchanged ⇒ re-stamp the version (no reshape), then audit.
+   - **Equal to installed** ⇒ **audit only** (the default spine).
+3. **Precondition for baseline mode:** a root `CLAUDE.md` must exist. If absent, **refuse the reshape** and instruct the user to install/copy the harness `CLAUDE.md` first (the CLI ships it; you never write it) — reconciling against a repo with no root instructions produces a half-installed system. Detect-and-instruct, not a hard gate on the audit.
+
+You write only under `docs/` and `docs/memory/maintenance.md`. You never edit `CLAUDE.md` (the CLI ships it) or production code.
+
+## Before starting
 
-1. If `./docs/memory/maintenance.md` exists, read it for last review state, ownership snapshots, high-churn paths, and known failure modes.
+1. If `./docs/memory/maintenance.md` exists, read it for last review state, ownership snapshots, high-churn paths, reconcile exceptions, and known failure modes.
 2. If `./docs/memory/boundary.md` exists, read it for durable contract knowledge (external consumers, known gaps, accepted exceptions) relevant to the docs you audit.
-3. Read `./docs/routing.md` — the code-ownership map (file-pattern → canonical doc + module). It is the ownership source of truth for this audit.
 
-## Step 1: Build Ownership Map
+---
+
+## Part A — Coherence audit (always runs)
+
+The ownership source of truth is the **union of every feature doc's `owns:` frontmatter** — the same source the SessionStart ownership index derives from. There is no `docs/routing.md` and no precomputed file to regenerate; you rebuild the map by globbing `docs/features/`.
 
-1. Read `docs/structure.md` for the authority map
-2. Read `docs/routing.md` File-Pattern Routes
-3. Build a map: pattern → owning doc + module (this IS the source of truth — there is no frontmatter to glob)
+### Step 1: Build the ownership map
 
-**Architecture-first fallback.** If `docs/routing.md` is absent or has no File-Pattern rows (a fresh-baseline repo can carry thousands of LOC and zero feature docs), drive this pass's ownership/drift surface off `docs/architecture/**` file-references instead — they become the **primary** ownership map for Steps 2–5. The routing map stays primary the moment any row appears — this is a fallback, not a replacement.
+1. Read `docs/structure.md` for the authority map.
+2. Glob `docs/features/**/*.md`; for each, parse the frontmatter `owns:` globs and `module:` label.
+3. Build a map: glob → owning doc + module. Narrower glob wins on overlap. **This IS the source of truth.**
 
-## Step 2: Validate Ownership
+**Architecture-first fallback.** If no feature doc carries `owns:` yet (a fresh-baseline repo can carry thousands of LOC and zero feature docs), drive this pass's ownership/drift surface off `docs/architecture/**` file-references instead — they become the **primary** ownership map for Steps 2–5. The `owns:` map becomes primary the moment any feature doc declares ownership — this is a fallback, not a replacement.
 
-For each File-Pattern row in `docs/routing.md`:
+### Step 2: Validate ownership
 
-- Verify the pattern matches existing files
-- Report patterns matching nothing, deleted paths, orphaned rows (doc no longer exists)
+For each `owns:` glob across the feature docs:
+
+- Verify the glob matches existing files. Report globs matching nothing, deleted paths, and orphaned docs.
+- Flag **equal-specificity overlaps** — two feature docs whose `owns:` globs claim the same paths at the same specificity (an ambiguous owner). Surface as a question.
 
 For each code symbol or path a doc explicitly **names** (function/export/route/type):
 
-- Verify it resolves in the code, independent of git-churn — Step 3's churn gate is blind to churn-free false claims
-- Flag unresolved named referents as drift, phrased as a question (e.g. `docs/x.md:NN names fn() — no static definition found; confirm it is not generated/re-exported before treating as stale`)
-- On codegen/reflection/DI/barrel stacks where static resolution is unreliable, skip — yielding nothing is correct
+- Verify it resolves in the code, independent of git-churn — Step 3's churn gate is blind to churn-free false claims.
+- Flag unresolved named referents as drift, phrased as a question (e.g. `docs/x.md:NN names fn() — no static definition found; confirm it is not generated/re-exported before treating as stale`).
+- On codegen/reflection/DI/barrel stacks where static resolution is unreliable, skip — yielding nothing is correct.
 
-Also check the **env contract** when the repo declares a canonical `.env.example` (or equivalent). The named-referent check above covers code symbols and paths but not env vars, which live in a separate canonical file:
+Also check the **env contract** when the repo declares a canonical `.env.example` (or equivalent). The named-referent check covers code symbols and paths but not env vars, which live in a separate canonical file:
 
 - Extract the `UPPER_SNAKE` env keys the code reads (`process.env.X` and the deploy scripts' generated env). Grep each against the canonical `.env.example`.
 - Raise any absence as a question (e.g. `server reads MASTER_KEK but no MASTER_KEK appears in .env.example — confirm the contract still holds`). Skip when no canonical file exists.
 
-## Step 3: Detect Doc Drift
+### Step 3: Detect doc drift
 
 Run `git log --since="2 weeks ago" --name-only --pretty=format:"%h %s"` to find changed source files.
 
 For each changed file:
 
-- Match against the File-Pattern routes in `docs/routing.md` (narrower pattern wins) → identify the owning doc
-- If no route matches → flag as unowned
-- If owner exists → compare last modified dates (`git log -1 --format="%ci" -- <path>`), flag docs where code changed more recently (14-day threshold)
+- Match against the `owns:` map (narrower glob wins) → identify the owning doc.
+- If no glob matches → flag as **unowned**.
+- If an owner exists → compare last-modified dates (`git log -1 --format="%ci" -- <path>`), flag docs where code changed more recently (14-day threshold).
 
-## Step 4: Check Routing Table Drift
+### Step 4: Check architecture & backlog
 
-If `./docs/routing.md` exists:
+**Unowned paths.** Compare the repo's actual top-level source directories (derive them — the top-level dirs that contain code, or the roots named across the `owns:` globs; do not assume `src/`) against the `owns:` map. Report directories no `owns:` glob covers.
 
-1. For each row, verify the file pattern matches existing files and referenced docs/agents exist
-2. Check for new top-level source directories (the repo's actual source roots — derive them, never assume `src/`) not covered by any routing entry
-3. Fix drift directly, or backlog if unclear
+**Stale greenfield self-label.** If `structure.md` asserts the repo is greenfield — _"No source code or feature docs exist yet"_ or similar — **but a real source tree exists** (the derived source roots above are non-empty, e.g. a populated `packages/` of real workspaces), the self-label has gone stale. Raise it as a question (e.g. `structure.md says "No source code exists yet" but packages/ holds 5 workspaces — confirm the greenfield label should be retired`).
 
-Also flag **unowned paths** — top-level source directories with no owning feature doc (no `docs/routing.md` pattern covers them).
+**Architecture drift.** Grep `docs/architecture/` for file-path references. Verify referenced paths still exist. Remove or update stale references.
 
-Also catch a **stale greenfield self-label.** If `routing.md` (or `structure.md`) asserts the repo is greenfield — _"Greenfield. No source code or feature docs exist yet"_ or similar — **but a real source tree exists** (the derived source roots from this step's item 2 above, or Step 5's Unowned-code derivation, are non-empty, e.g. a populated `packages/` of real workspaces), the self-label has gone stale: the scaffold filled in but the doc still announces an empty repo. Raise it as a question (e.g. `routing.md says "No source code exists yet" but packages/ holds 5 workspaces — confirm the greenfield label should be retired`).
+**Backlog health.** Read `docs/history/backlog.md`. Report items older than 30 days. Count pending by priority.
 
-## Step 5: Check Architecture & Backlog
+### Step 5: Remediate
 
-**Architecture drift:** Grep `docs/architecture/` for file path references. Verify referenced paths still exist. Remove or update stale references.
+For each stale doc:
 
-**Unowned code:** Compare the repo's actual top-level source directories (derive them — the top-level dirs that contain code, or the roots named across `docs/routing.md` patterns; do not assume `src/`) against the File-Pattern routes in `docs/routing.md`. Report directories no routing pattern covers.
+- If drift is clear (renamed function, new export, changed props) → update the doc directly.
+- If drift is ambiguous (major refactor, unclear intent) → backlog it.
 
-**Backlog health:** Read `docs/history/backlog.md`. Report items older than 30 days. Count pending by priority.
+For unowned code paths:
 
-## Step 6: Remediate
+- Append: `- **[P2]** No feature doc owns \`{dir}/\` — discovered by maintenance` (`{dir}` = the actual unowned source directory).
 
-For each stale doc:
+**Declined realignment.** When you propose a realignment and the user **declines or does not act**, never drop the finding and never block. Append it to `docs/history/backlog.md` as `- **[P0–P3]** <finding> — discovered by maintenance`, priority = the finding's own severity **on the same P0–P3 scale as code items** — never a segregated "compliance" section, never auto-relegated to the lowest tier. Record once: dedupe against existing entries; if already present, leave it.
 
-- If drift is clear (renamed function, new export, changed props) → update the doc directly
-- If drift is ambiguous (major refactor, unclear intent) → backlog it
+### Step 6: Report & update tracking
 
-For unowned code paths:
+1. Update `docs/structure.md` Health Log with today's date and summary.
+2. Update `docs/memory/maintenance.md` with last review date, stale docs fixed, unowned paths, backlog items created.
+3. Report findings: stale docs, broken ownership, unowned code, architecture drift, backlog health.
+4. **Inbox-distillation threshold.** Count undigested inbox entries — `## ` entry blocks across `docs/memory/inbox/*.md` (the inbox is consume-on-digest, so every block present is undigested). If the count is **≥5**, add one line to the report **proposing** a `distiller facts` run — propose only, never auto-run, no cron. If the user declines or ignores it, do nothing: the count keeps growing and the proposal reappears next pass — that recurrence _is_ the dedupe, so never backlog it.
+5. **Docs-distillation threshold.** Per target doc, count undigested fact-cards (`invalid_from: null`, the doc's path not in their `digested_into:`) that **touch** it by the structural intersection in `skills/distiller/references/docs-mode.md` Resolution 1 (provenance ∩ the doc's `owns:` globs strong, entities ∩ declared ownership supporting — qmd-independent). If **≥10** map to **one** doc, add one line to the report **proposing** a `distiller docs --doc <path>` run on that doc — propose only, never auto-run, no cron. Declined or ignored ⇒ the count keeps growing and the proposal reappears next pass; that recurrence _is_ the dedupe, so never backlog the proposal.
+
+### Step 7: Refresh index (optional, skip-if-absent)
+
+If the `qmd` binary is available (`command -v qmd`), re-run `qmd embed -c <collection>` once per `{repo}-*` collection (`{repo}` = the repo's directory name; `qmd collection list` shows the registered set — skip any absent) so the local docs index reflects the files this pass touched. Scope every run with `-c` — the qmd index is global (`~/.cache/qmd/` holds every repo's collections), so a bare `qmd embed` would re-embed unrelated repos' collections. If `qmd` is absent, skip silently — it's never required.
+
+### Step 8: Check anchor drift (optional, skip-if-absent)
+
+If `qmd` is absent (`command -v qmd` finds nothing), **skip this whole step silently** — it's never required. `anchors:` is a qmd-only tooling key; with no qmd it is inert.
+
+This catches **doc-area drift** — the subject the doc abstracts moving or vanishing from the indexed corpus. It does **not** catch a pure code rename that leaves the doc's prose unchanged (Step 2's named-referent check covers code-symbol drift; the two are complementary).
+
+Glob `docs/features/**/*.md`, `docs/architecture/**/*.md`, and `docs/operations/**/*.md` for docs carrying `anchors:` frontmatter. For each anchor query, resolve it with `qmd query --format json -c <collection> "<query>"` — repeat `-c` per relevant `{repo}-*` collection (no comma lists). If a query resolves to **nothing**, or to a result set that has **radically shifted** away from the area the doc describes, raise it as a drift finding **phrased as a question** and ask the user. On **yes**, dispatch the remediation sub-agent (the same yes-branch as Step 5). On **decline or no action**, append it to `docs/history/backlog.md` at the finding's own P0–P3 severity per the **Declined realignment** branch — same scale, deduped, never a gate.
+
+---
+
+## Part B — Baseline mode (additive; runs before Part A when the marker is missing/behind)
+
+Baseline mode converges the repo's `docs/` to the **installed** harness shape, then hands off to the Part A audit. Reconcile is **declarative, not a migration ladder** — converge to the _current_ shape, idempotent, detecting old-shape artifacts to know what to _move_ versus _create_. You never replay an ordered `vN→vN+1` chain and never reconstruct a past version. (Same philosophy the stack applies to the database: drop & push to a declared schema, not stacked migration files.)
+
+### Target structure (the installed shape)
+
+```
+docs/
+├── README.md              # Documentation root — quick links, section index
+├── structure.md           # Authority map + frontmatter `harness-version` (you own this field)
+├── architecture/          # Cross-module design + steering layer
+│   │                      #   domain-model, glossary, non-goals, references, open-questions
+│   └── adr/               # Architecture Decision Records (numbered, immutable)
+├── features/              # Feature specs — the only first-class doc unit (flat; ownership in each doc's `owns:` frontmatter)
+│   └── {group}/           #   browse-only subfolder for grouping; NEVER a module; may carry a Readme.md
+├── operations/            # Setup, development, deployment, CI/CD
+├── brainstorm/            # Optional — kept design records, one {topic}/ subfolder per session (state.md + pillars/)
+│   └── {topic}/           #   created by the `brainstorm` skill; NOT scaffolded empty
+├── history/
+│   ├── CHANGELOG.md       # Master changelog index
+│   ├── changelog/         # Individual entries
+│   ├── plans/             # Implementation plans (Status field required)
+│   └── backlog.md         # Tracked work items by priority (P0-P3)
+├── memory/                # inbox/ (captured-lessons queue), facts/ (distilled cards), index.md, main.md, {agent}.md
+└── tests/                 # Optional, author-maintained — create only if test docs exist
+```
+
+There is **no `docs/routing.md`**, **no `docs/modules/{m}/`**, **no `docs/pillars/`**, **no `docs/boundaries/`**. Code ownership lives in feature `owns:` frontmatter; a module is a `module:` label, not a folder; boundaries are diagnosed from source; brainstorm records are kept design records.
+
+> `docs/brainstorm/{topic}/` is **author-created, never scaffolded** — the `brainstorm` skill writes it when a session opens, and it is **kept** (committed) as the provenance the steering pillars distil from. Recognize it as canonical: never flag it as a doc "outside the structure" and never delete it during reconcile.
+
+### Step B1 — Inventory and classify
+
+Glob every markdown file. Classify each: Architecture, Features, Operations, Plans, Changelogs, Backlog, Brainstorm records (stay), Stale/Deprecated (delete), Root docs (stay). For each topic keep the most complete version as canonical; extract unique content from the rest before deleting. **No redirect stubs** — when you move a file, delete the original and fix every reference (cross-doc links, memory files). Anything already under `docs/brainstorm/{topic}/` is a **kept design record** — leave it in place untouched; never reclassify its pillars as Architecture/Stale or relocate them.
+
+While reading each markdown doc to classify it, if the doc names a code symbol it asserts exists that **statically resolves to nothing**, note it as an observation for the Part A audit — **only** on stacks where static resolution is reliable (stay silent on codegen/reflection/DI/barrel stacks); scoped to docs already being read here, never a whole-repo prose sweep; **docs only**, never code-file comments.
+
+### Step B2 — Fold dissolved-shape artifacts forward
+
+This is what makes baseline more than a fresh scaffold. Detect old-shape artifacts and fold them forward. **Only fold what is present;** `log()` what you skipped and why.
+
+| If you find (old shape) | Fold to (current shape) |
+| --- | --- |
+| a persisted `docs/routing.md` ownership map | migrate each File-Pattern row's ownership into the owning feature doc's `owns:` frontmatter (Pattern → an `owns:` glob; Module column → the doc's `module:` label), then **delete `docs/routing.md`** |
+| feature docs carrying `owns`/`touches`/`depends_on` legacy frontmatter | collapse to the single `owns:` key (drop `touches`/`depends_on`; their paths fold into `owns:` if the doc genuinely owns them, else drop) |
+| a `docs/modules/{m}/` tree | move each module's `features/` flat into `docs/features/` with the module name as a `module:` tag on each doc; fold module-local `pillars/`/prose into `docs/architecture/`; delete the `docs/modules/` tree |
+| repo-wide `docs/pillars/` | cross-module doctrine → `docs/architecture/`; delete the folder |
+| `docs/boundaries/` (legacy persisted boundaries) | delete — boundary analysis is a plan-time diagnostic (the `boundary` skill reads contracts fresh from source); fold any human-authored knowledge (external consumers, intent, accepted exceptions) into `docs/architecture/` |
+| `docs/OWNERSHIP_INDEX.md` (legacy derived ownership index) | delete — ownership is the union of feature `owns:` frontmatter, surfaced by the generated index |
+| `docs/operations/guardrails.md` | fold durable contract notes into `docs/architecture/` |
+| `docs/architecture/overview.md` | split into `domain-model.md` / `glossary.md` / `non-goals.md` / `references.md` / `open-questions.md` |
+| a root `brainstorm/` or `brainstorming/` folder (legacy transient/per-harness location) | move each design record into `docs/brainstorm/{topic}/`, kept; delete the root folder |
+| no `harness-version` in `structure.md` | stamp it (Step B4) |
+
+### Step B3 — Present the reconcile plan, then execute
+
+Table: `| File | Action | From | To | Reason |` (actions: `Move`, `Merge into {target}`, `Delete`, `Keep`, `Create`, `Fold`). For a fresh baseline this is mostly `Create`; for an upgrade it is mostly `Fold`/`Move`. Ask once: **"Approve this reconcile?"** — you own this interaction (the `documentation` skill is a library and has none).
+
+On approval, execute: create the folder structure; move/fold/merge/delete per the plan; add `Status:` to plan files; for each feature doc, derive and write its `owns:` globs (+ `module:` label + `keywords:`) from the source it describes by calling the `documentation` skill's **frontmatter derivation**; merge scattered backlogs into `docs/history/backlog.md`; fix links broken by moves.
+
+Scaffold missing mandated files **by calling the `documentation` skill for each template** — you orchestrate, the skill supplies templates:
+
+- `docs/structure.md` (with `harness-version`), `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/index.md`, `docs/memory/main.md`, and the repo-root `README.md` (filled from the real lockfile/scripts/layout — **never overwrite an existing root README**).
+
+Scaffold `docs/memory/facts/` so the distilled tier has a home from day one: the `session-reflect` hook appends session lessons to the per-actor inbox at `docs/memory/inbox/{actor}.md` (not a scaffold — created mechanically on first reflection), and the `distiller` digests that queue down into fact-cards under `docs/memory/facts/`, consuming the entries it digests.
+
+### Step B4 — Stamp the version
 
-- Append: `- **[P2]** No feature doc owns \`{dir}/\` — discovered by maintenance` (`{dir}` = the actual unowned source directory)
+Write `harness-version: <installed version>` (the semver from `.claude/harness.json`) into `docs/structure.md` frontmatter. This single field is the repo's baseline-and-version sentinel — there is no second marker (no `epoch`, no `docs/memory/index.md` "is-baselined" check).
 
-**Declined realignment:** When you propose a realignment and the user **declines or does not act**, never drop the finding and never block. Append it to `docs/history/backlog.md` as `- **[P0–P3]** <finding> — discovered by maintenance`, with priority = the finding's own severity **on the same P0–P3 scale as code items** — never a segregated "compliance" section, never auto-relegated to the lowest tier. Record once: dedupe against existing entries; if already present, leave it. (This is the decline branch — it pairs with dispatching a remediation sub-agent on a yes.)
+### Step B5 — Register the qmd retrieval lens (optional, skip-if-absent)
 
-## Step 7: Report & Update Tracking
+Strictly optional and guarded on the binary — if `command -v qmd` finds nothing, **skip this entire step silently** (no error, no behavior change) and carry one advisory line into the hand-back: _"qmd not installed — semantic retrieval unavailable; the generated ownership index + `keywords:` discovery are active."_ The index is a **local rebuildable lens** — data stays in git; never commit index artifacts, and never use `qmd init` (the default global index keeps the repo clean).
 
-1. Update `docs/structure.md` Health Log with today's date and summary
-2. Update `docs/memory/maintenance.md` with last review date, stale docs fixed, unowned paths, backlog items created
-3. Report findings: stale docs, broken ownership, unowned code, architecture drift, backlog health
-4. **Inbox-distillation threshold.** Count undigested inbox entries — `## ` entry blocks across `docs/memory/inbox/*.md` (the inbox is consume-on-digest, so every block present is undigested). If the count is **≥5**, add one line to the report **proposing** a `distiller` `facts` run — propose only, never auto-run, no cron. If the user declines or ignores it, do nothing: the count keeps growing and the proposal reappears next pass — that recurrence _is_ the dedupe, so never backlog it.
-5. **Docs-distillation threshold.** Per target doc, count undigested fact-cards (`invalid_from: null`, the doc's path not in their `digested_into:`) that **touch** it by the structural intersection in `skills/distiller/references/docs-mode.md` Resolution 1 (provenance ∩ the doc's `routing.md` patterns strong, entities ∩ declared-ownership supporting — qmd-independent). If **≥10** map to **one** doc, add one line to the report **proposing** a `distiller docs --doc <path>` run on that doc — propose only, never auto-run, no cron. Declined or ignored ⇒ the count keeps growing and the proposal reappears next pass; that recurrence _is_ the dedupe, so never backlog the proposal.
+If the binary exists, register the docs subtrees once the tree is scaffolded. **Do not register one collection rooted at `docs/`** — qmd hard-codes the `**/*.md` pattern and has no exclude flag, so a `docs/`-root collection would sweep the consumable inbox queue at `docs/memory/inbox/` into the index (the inbox's entries are deleted on digestion, leaving dangling index entries). Register **per indexable subtree** (skip absent ones; `{repo}` = the repo's directory name; an existing name/path no-ops — treat as success):
 
-## Step 8: Refresh Index (Optional)
+- `qmd collection add docs/features --name {repo}-features`
+- `qmd collection add docs/architecture --name {repo}-architecture`
+- `qmd collection add docs/operations --name {repo}-operations`
+- `qmd collection add docs/memory/facts --name {repo}-facts` (never `docs/memory` as a whole)
 
-If the `qmd` binary is available (`command -v qmd`), re-run `qmd embed -c <collection>` once per `{repo}-*` collection (`{repo}` = the repo's directory name; `qmd collection list` shows the set harness-manager registered — skip any absent) so the local docs index reflects the files this pass touched. Scope every run with `-c` — the qmd index is global (`~/.cache/qmd/` holds every repo's collections), so a bare `qmd embed` would re-embed unrelated repos' collections. If `qmd` is absent, skip silently — it's never required.
+Then `qmd context add` per registered collection and `qmd embed -c <name>` per collection (always scope with `-c`; a bare `qmd embed` re-embeds every repo's collections). This augments discovery; it never supersedes the `owns:`-glob ownership resolution.
 
-## Step 9: Check Anchor Drift (Optional)
+### Step B6 — Module proposal
 
-If `qmd` is absent (`command -v qmd` finds nothing), **skip this whole step silently** — it's never required.
+Modules are **labels, declared, never inferred from physical layout**. Derive the repo's candidate bounded contexts directly from the code and docs: distinct wire surfaces (who owns routes/handlers), schema/data-access ownership, entry points and process units, plus any contexts `docs/architecture/` already names.
 
-This catches **doc-area drift** — the subject the doc abstracts moving or vanishing from the indexed corpus. It does **not** catch a pure code rename that leaves the doc's prose unchanged: the anchor query semantically matches the doc's own text, so the result set doesn't shift. Code-symbol drift is Step 2's named-referent check, not this one — the two are complementary, not redundant.
+- Propose the derived contexts as candidate `module:` labels. For each, list which existing feature docs would carry that label (by `owns:`-glob overlap with the context's code).
+- **Propose — don't force.** Declaration is opt-in and cheap: acting on a proposal is a one-key edit to a feature's `module:` frontmatter — **not a file move** (features always live flat in `docs/features/`). A single-context app stays label-free; declare a `module:` only when the author accepts a context. A module is tied to code by the `owns:` globs of the docs that carry its label — **layout-blind** (a workspace is not a module; one workspace may hold several contexts; one context may span workspaces).
 
-Glob `docs/{features,modules/*/features}/**/*.md`, `docs/architecture/**/*.md`, and `docs/operations/**/*.md` for docs carrying `anchors:` frontmatter. For each anchor query on such a doc, resolve it with `qmd query --format json -c <collection> "<query>"` — repeat `-c` per relevant `{repo}-*` collection (no comma lists; the collection set is what `qmd collection list` shows). If a query resolves to **nothing**, or to a result set that has **radically shifted** away from the area the doc describes, raise it as a drift finding **phrased as a question** — e.g. `docs/x.md anchors "<query>" — resolves to nothing; confirm the area moved before treating the doc as stale` — and ask the user. On **yes**, dispatch the remediation sub-agent (the same yes-branch as Step 6). On **decline or no action**, append it to `docs/history/backlog.md` at the finding's own P0–P3 severity per the **Declined realignment** branch in Step 6 — same scale, deduped, never a gate.
+Re-running you is safe — the structure work is idempotent, so a second pass is just the audit plus the module proposal.
 
 ---
 
 ## Rules
 
-- Never delete feature docs — only update or flag for review
-- Never modify `docs/history/plans/` or `docs/history/changelog/` (frozen records)
-- Preserve existing doc structure and formatting when updating
-- When in doubt, create a backlog item rather than making a wrong update
-- Be specific: include file paths, line numbers, and what changed
-- Respect known-exceptions in `docs/memory/maintenance.md` — don't re-flag suppressed findings
-- A clean report is valid — do not invent issues
+- **Never delete feature docs** — only update or flag for review.
+- **Never modify `docs/history/plans/` or `docs/history/changelog/`** (frozen records).
+- **Preserve existing doc structure and formatting** when updating.
+- **When in doubt, create a backlog item** rather than making a wrong update.
+- **Be specific:** include file paths, line numbers, and what changed.
+- **Respect known-exceptions** in `docs/memory/maintenance.md` — don't re-flag suppressed findings.
+- **A clean report is valid** — do not invent issues.
+- **Declarative, idempotent.** Re-running baseline mode on a current repo is a no-op. Converge to the current shape; never replay a version ladder; never reconstruct a past shape.
+- **One sentinel.** `docs/structure.md` `harness-version` is the only baseline/version marker.
+- **Modules are labels, layout-blind.** Seed from the code's bounded contexts; never from `pnpm-workspace.yaml`/workspace walls. Propose, don't force; acting is a `module:` tag, never a folder.
+- **You orchestrate docs; the `documentation` skill supplies templates.** It is a library — never expect it to baseline.
+- **Never overwrite an existing root `README.md`.** It is human-authored.
+- **Stay in `docs/` (+ the root `README.md` scaffold) and `docs/memory/maintenance.md`.** You never edit `CLAUDE.md` (the CLI ships it) or production code.
+
+## Strategy memory
+
+After a run you may append to `docs/memory/maintenance.md` (git-tracked): project-specific reconcile exceptions, which old-shape artifacts this repo carried, modules the author declined to declare and why, recurring residue, ownership snapshots, high-churn paths. Never user preferences (those are `~/.claude/`); never a transcription of doc content. Date each entry `## YYYY-MM-DD — {topic}`.

package/data/harnesses/etna/agents/spec-mode.md

@@ -21,7 +21,7 @@ First, understand the documentation landscape:
 2. If `./docs/features/README.md` exists, read it to see existing feature specs and where the new spec fits; otherwise glob the feature docs directly
 3. If `./docs/memory/spec-mode.md` exists, read it for feature doc inventory, ownership conflict zones, and lessons from previous research
 4. Read 1-2 existing specs in `./docs/features/` to calibrate format and depth
-5. Read `./docs/routing.md` (File-Pattern Routes) to build the ownership map — pattern → canonical doc + module. This is the source of truth for what code paths are already owned (feature docs carry no ownership frontmatter).
+5. Consult the **injected ownership index** (the generated `glob → doc · module · keywords · status` map — the union of every feature doc's `owns:` frontmatter) to build the ownership map. This is the source of truth for what code paths are already owned. If the index isn't present in context, glob `docs/features/**/*.md` and read each doc's `owns:` frontmatter directly.
 
 This tells you what already exists, what's adjacent, how detailed the spec should be, and what code paths are already owned.
 
@@ -32,7 +32,7 @@ This tells you what already exists, what's adjacent, how detailed the spec shoul
 3. **Affected modules** — Identify what files, routes, components, and data flows are relevant
 4. **Current state** — Understand how the system works today in the area being specified
 5. **Dependencies** — Map what this feature touches and what depends on it
-6. **Ownership conflicts** — Compare the new feature's intended code paths against existing `docs/routing.md` patterns. Report overlaps.
+6. **Ownership conflicts** — Compare the new feature's intended code paths against existing feature docs' `owns:` globs. Report overlaps (two docs claiming the same paths at equal specificity).
 
 ## What You Return
 
@@ -43,7 +43,7 @@ Structure your findings as:
 - **Affected modules**: Files, routes, components that will be involved
 - **Current behavior**: How the relevant part of the system works today
 - **Conventions**: Naming, structure, and patterns to follow based on existing code
-- **Ownership conflicts**: Existing feature docs whose `docs/routing.md` patterns overlap with the proposed feature. Include the conflicting paths and the owning doc name.
+- **Ownership conflicts**: Existing feature docs whose `owns:` globs overlap with the proposed feature. Include the conflicting paths and the owning doc name.
 - **Risks or concerns**: Anything the spec should address or call out
 
 Use the documentation skill's style guide and conventions when structuring your findings — imperative voice, ASCII diagrams for flows, function signatures over implementations, concise.

package/data/harnesses/etna/harness.json

@@ -1,11 +1,11 @@
 {
   "harness": "etna",
   "name": "etna",
-  "version": "0.1.1",
+  "version": "1.0.1",
   "files": [
     ".prettierrc.json",
     ".prettierignore",
     ".vscode/settings.json"
   ],
-  "digest": "085aa22986b2"
+  "digest": "5699e31e9981"
 }