@nurix/etna 0.18.10 → 0.18.12

package/data/harnesses/code/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/code/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/code/harness.json

@@ -1,11 +1,11 @@
 {
   "harness": "code",
   "name": "code",
-  "version": "2.0.0",
+  "version": "3.0.1",
   "files": [
     ".prettierrc.json",
     ".prettierignore",
     ".vscode/settings.json"
   ],
-  "digest": "3d1464ab6963"
+  "digest": "f301f7867e2e"
 }

package/data/harnesses/code/hooks/generate-ownership-index.mjs

@@ -0,0 +1,148 @@
+// plugins/code/hooks/generate-ownership-index.mjs — SessionStart hook: scan docs/features/**/*.md,
+// extract the focal frontmatter (owns / module / keywords / status), and inject a compact
+// code-path → owning-doc index via additionalContext. Fires on startup/resume/clear/compact so the
+// map survives /clear and /compact and is regenerated fresh every time. Writes no file.
+
+import fs from "node:fs";
+import path from "node:path";
+
+// Read all of stdin synchronously; returns "" if nothing is piped.
+function readStdin() {
+  try {
+    return fs.readFileSync(0, "utf8");
+  } catch (e) {
+    return "";
+  }
+}
+
+// Resolve the project root: CLAUDE_PROJECT_DIR env, else payload cwd, else process cwd.
+function resolveProjectDir(payload) {
+  return process.env.CLAUDE_PROJECT_DIR || (payload && payload.cwd) || process.cwd();
+}
+
+// Recursively collect every .md file under dir (returns [] if the dir is absent).
+function listMarkdown(dir) {
+  const out = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (e) {
+    return out;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...listMarkdown(full));
+    else if (entry.isFile() && entry.name.endsWith(".md")) out.push(full);
+  }
+  return out;
+}
+
+// Pull the leading `--- … ---` frontmatter block; "" if the file has none.
+function frontmatter(text) {
+  const m = /^?---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  return m ? m[1] : "";
+}
+
+// Trim surrounding whitespace, then strip one layer of matching quotes.
+function unquote(s) {
+  return String(s).trim().replace(/^["']|["']$/g, "").trim();
+}
+
+// Read one frontmatter key: scalar (`k: v`), inline array (`k: [a, b]`), or a following `- item` block.
+// Returns a string for scalars, an array for lists, or undefined when the key is absent.
+function field(block, key) {
+  const lines = block.split(/\r?\n/);
+  const head = new RegExp(`^${key}\\s*:\\s*(.*)$`);
+  for (let i = 0; i < lines.length; i++) {
+    const m = head.exec(lines[i]);
+    if (!m) continue;
+    const raw = m[1].trim();
+    if (raw === "") {
+      const items = [];
+      for (let j = i + 1; j < lines.length; j++) {
+        const li = /^\s*-\s+(.*)$/.exec(lines[j]);
+        if (!li) break;
+        items.push(unquote(li[1]));
+      }
+      return items;
+    }
+    if (raw.startsWith("[")) {
+      return raw.replace(/^\[|\]$/g, "").split(",").map((s) => unquote(s)).filter(Boolean);
+    }
+    return unquote(raw);
+  }
+  return undefined;
+}
+
+// Coerce a field that may be scalar/array/undefined into a clean string array.
+function asList(v) {
+  if (v == null) return [];
+  return (Array.isArray(v) ? v : [v]).map((s) => String(s).trim()).filter(Boolean);
+}
+
+// Build the ownership index text from every feature doc's frontmatter.
+function buildIndex(projectDir) {
+  const featuresDir = path.join(projectDir, "docs", "features");
+  const files = listMarkdown(featuresDir);
+  const lines = [];
+  let deprecated = 0;
+  for (const file of files) {
+    let text;
+    try {
+      text = fs.readFileSync(file, "utf8");
+    } catch (e) {
+      continue;
+    }
+    const block = frontmatter(text);
+    if (!block) continue;
+    const owns = asList(field(block, "owns"));
+    if (owns.length === 0) continue;
+    const status = (field(block, "status") || "active").toString().toLowerCase();
+    if (status === "deprecated") {
+      deprecated += 1;
+      continue; // keep deprecated docs out of the routing lines
+    }
+    const moduleLabel = (field(block, "module") || "—").toString();
+    const keywords = asList(field(block, "keywords"));
+    const doc = path.relative(projectDir, file).split(path.sep).join("/");
+    const kw = keywords.length ? `[${keywords.join(", ")}]` : "[]";
+    for (const glob of owns) {
+      lines.push(`${glob} → ${doc} · ${moduleLabel} · ${kw} · ${status}`);
+    }
+  }
+  if (lines.length === 0) return "";
+  lines.sort();
+  const header =
+    "# Ownership index (generated) — code-path glob → owning feature doc · module · keywords · status\n" +
+    "# Match the file or topic you're about to touch, then read the owning doc before changing it.\n";
+  const footer = deprecated > 0 ? `\n# (${deprecated} deprecated feature doc(s) omitted)` : "";
+  return header + lines.join("\n") + footer;
+}
+
+function main() {
+  const raw = readStdin();
+  let payload = {};
+  try {
+    payload = raw ? JSON.parse(raw) : {};
+  } catch (e) {
+    payload = {};
+  }
+  const index = buildIndex(resolveProjectDir(payload));
+  if (!index) return; // no feature docs yet → inject nothing
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: index,
+      },
+    })
+  );
+}
+
+try {
+  main();
+} catch (e) {
+  // Best-effort: a routing index is a convenience, never a gate. Inject nothing on failure.
+} finally {
+  process.exit(0);
+}

package/data/harnesses/code/hooks/hooks.json

@@ -1,5 +1,17 @@
 {
   "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/generate-ownership-index.mjs\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
     "SessionEnd": [
       {
         "matcher": "",

package/data/harnesses/code/skills/boundary/references/boundary-taxonomy.md

@@ -86,7 +86,7 @@ Below the table, three standing blocks:
 
 If any boundary is pre-code (`point*`/`transcribe*`), add the footnote: _"\* point-mode boundary whose pointer lands at implementation — converts to (or gains) a `file:line` pointer when the module lands."_
 
-**Name the bounding code units** (paths / package names) in every `Bounds` line — the distinct vertices named across all `Bounds` lines are the **module-discovery feed** `harness-manager` reads to propose modules, so name them precisely. A `Bounds` line is not restricted to two modules: it may name two **layers** within one module (app↔DB, render↔hydrate, producer↔consumer) or a module and an **external system** — so a flat / single-module repo still has real boundaries to file (as the intro states).
+**Name the bounding code units** (paths / package names) in every `Bounds` line — the distinct vertices named across all `Bounds` lines are the **module-discovery feed** the `maintenance` agent (baseline mode) reads to propose modules, so name them precisely. A `Bounds` line is not restricted to two modules: it may name two **layers** within one module (app↔DB, render↔hydrate, producer↔consumer) or a module and an **external system** — so a flat / single-module repo still has real boundaries to file (as the intro states).
 
 **The clustering key — a convergence heuristic, not a hard count:** _one boundary file per (source-of-truth × doc-mode)_. Types that point at the same source-of-truth in the same doc-mode collapse into one file — all persistence types reading one relational schema fold into the `db-schema` file; split only where the source-of-truth or the doc-mode differs (a `transcribe` shape over the same schema, or a different store). Each catalog entry below carries a fold note: **Folds into `x`** (this type lands in `x`'s file), **Canonical home** (this type _is_ the file others fold into), or **Own home** (a standalone source-of-truth × doc-mode). Two `generate` runs converge on the same file set only where this fold-map names the home — where it doesn't, the count is a judgment call, not a guarantee.
 
@@ -108,7 +108,7 @@ Organized by the seven boundary categories. Each entry: **type-name — SEVERITY
 
 #### `information-architecture` — CRITICAL · transcribe
 
-The entity model + topology (e.g. Brief→Plan→Persona→Audience→Match→Campaign→Run; service planes). **Where:** synthesized from ADRs / module pillars / a `@org/contracts` package — never `package.json`. **Breaks:** re-relating or renaming an entity ripples across _every_ module, migration, and wire type. **Detect:** `docs/architecture/` (domain-model, ADRs), `docs/modules/*/pillars/`, a contracts package, `schema.ts`/`models.py` entity defs. **Safe-change:** map every consumer before re-relating; coordinate migrations + wire types + selectors in one change. _(Own home — the IA model is its own transcribed source-of-truth; never folds into a technology file.)_ _The flagship domain boundary._
+The entity model + topology (e.g. Brief→Plan→Persona→Audience→Match→Campaign→Run; service planes). **Where:** synthesized from ADRs / the domain model / a `@org/contracts` package — never `package.json`. **Breaks:** re-relating or renaming an entity ripples across _every_ module, migration, and wire type. **Detect:** `docs/architecture/` (domain-model, `adr/`), a contracts package, `schema.ts`/`models.py` entity defs. **Safe-change:** map every consumer before re-relating; coordinate migrations + wire types + selectors in one change. _(Own home — the IA model is its own transcribed source-of-truth; never folds into a technology file.)_ _The flagship domain boundary._
 
 #### `tenancy` — CRITICAL · transcribe
 
@@ -608,7 +608,7 @@ The agreement on a flag's key, default value, and the off=legacy/on=new conventi
 
 #### `workspace-package-graph` — HIGH · point
 
-The contract that a monorepo package may only import siblings it explicitly declares as workspace deps — no phantom/hoisted imports. **Where:** pnpm workspaces (`pnpm-workspace.yaml`, `workspace:*`, strict `node_modules`), npm/yarn/Bun workspaces, Nx, Turborepo. **Breaks:** under hoisting a package can import an undeclared dep hoisted to root (works locally, breaks on publish or layout change); pnpm's strict layout forbids it; removing/renaming a workspace package breaks every undeclared importer silently. **Detect:** `pnpm-workspace.yaml`/root `workspaces`, `workspace:*` deps, imports of package names not in that package's `dependencies`, `nx graph`/`turbo` graph. **Safe-change:** declare every cross-package import as a `workspace:` dep; on rename/remove update all dependents + lockfile; pin internal deps `workspace:*`; CI dependency-graph check for undeclared imports. _(Own home — the workspace dependency graph is its own source-of-truth.)_ _(A workspace is NOT a module — see how `harness-manager` reads boundary `Bounds` vertices.)_
+The contract that a monorepo package may only import siblings it explicitly declares as workspace deps — no phantom/hoisted imports. **Where:** pnpm workspaces (`pnpm-workspace.yaml`, `workspace:*`, strict `node_modules`), npm/yarn/Bun workspaces, Nx, Turborepo. **Breaks:** under hoisting a package can import an undeclared dep hoisted to root (works locally, breaks on publish or layout change); pnpm's strict layout forbids it; removing/renaming a workspace package breaks every undeclared importer silently. **Detect:** `pnpm-workspace.yaml`/root `workspaces`, `workspace:*` deps, imports of package names not in that package's `dependencies`, `nx graph`/`turbo` graph. **Safe-change:** declare every cross-package import as a `workspace:` dep; on rename/remove update all dependents + lockfile; pin internal deps `workspace:*`; CI dependency-graph check for undeclared imports. _(Own home — the workspace dependency graph is its own source-of-truth.)_ _(A workspace is NOT a module — see how the `maintenance` agent reads boundary `Bounds` vertices.)_
 
 #### `import-layering-rule` — MED · point