@nurix/etna 0.14.0 → 0.15.2

package/README.md

@@ -16,17 +16,38 @@ After this completes:
 
 ```
 your-project/
-├── CLAUDE.md             ← harness policy (backup of any existing file is kept)
+├── CLAUDE.md              ← harness policy (your existing file → CLAUDE.md.bak.<ISO>)
 └── .claude/
-    ├── skills/           ← documentation, introspect, workflow-mapper
-    ├── agents/           ← spec-mode, maintenance, contract-monitor, …
-    ├── rules/            ← general.md, nomenclature.md
-    └── scripts/          ← build-ownership-index.sh, check-doc-drift.sh
+    ├── skills/            ← documentation, boundary, distiller, brainstorm, workflow-mapper
+    ├── agents/            ← harness-manager, spec-mode, brainstorm, maintenance, change-review, performance-review
+    ├── rules/             ← general.md, nomenclature.md
+    ├── hooks/             ← post-commit, post-tool-failure, session-stop + lib/redact (knowledge-ledger capture)
+    ├── settings.json      ← the hooks are deep-merged in here (your existing keys preserved)
+    └── harness.json       ← {version, epoch, digest} — the installed-harness sentinel
 ```
 
-That's the entire footprint. Nothing is written outside the project. No marketplace registration, no `enabledPlugins` entry, no global cache dependency — Claude Code picks up project-scoped agents/skills/rules/scripts on its next session start.
+That's the entire footprint. Nothing is written outside the project. No marketplace registration, no `enabledPlugins` entry, no global cache dependency — Claude Code picks up the project-scoped agents/skills/rules on its next session start, and the hooks wire in through `.claude/settings.json`.
 
-Re-run `npx @nurix/etna code` anytime to refresh the harness content with what the latest published package ships. Existing same-named files are overwritten; files you've added that aren't part of the harness are left alone. The previous `CLAUDE.md` is backed up to `CLAUDE.md.bak.<ISO-timestamp>`.
+Re-run `npx @nurix/etna code` anytime to refresh the harness content with what the latest published package ships. Existing same-named files are overwritten; files you've added that aren't part of the harness are left alone. The previous `CLAUDE.md` is backed up to `CLAUDE.md.bak.<ISO-timestamp>`. Because the new `harness.json` carries the installed `{version, epoch, digest}`, a re-run that's ahead of your repo's stamped `harness-version` is what the reconcile (below) detects as an upgrade.
+
+## After install: bootstrap the harness
+
+Installing only *drops the files* — the harness isn't active for your repo until you **baseline** it. Open Claude Code in the project and drive the reconcile chain once (the installed `CLAUDE.md` carries the same steps under its `## Bootstrap` heading, for the agent):
+
+1. **"baseline this repo"** (or "reconcile the harness") — runs the **`harness-manager`** agent. It builds the `docs/` tree to the harness shape, stamps `docs/structure.md` with the installed `harness-version`, then hands back.
+2. If it asks for boundaries (a real codebase whose `docs/boundaries/` is still empty) — run **`/boundary generate`**. It detects your stack + information architecture and writes the typed boundary files.
+3. **"reconcile the harness"** again — `harness-manager` now proposes **modules** from those boundaries.
+
+Then work normally. This brownfield path reads your *actual* code, not a blank slate, so it's safe to run on an existing project with real history.
+
+Two things worth knowing on an existing repo:
+
+- **Your root `CLAUDE.md` is replaced** with the harness policy file (the old one is saved to `CLAUDE.md.bak.<ISO>`). If it held project-specific instructions, fold them back in after install — the harness file is the policy skeleton; your domain specifics sit alongside it.
+- **The ledger starts on your next commit.** The `post-commit` hook appends to `docs/memory/ledger/`; once enough entries accrue, the `maintenance` agent *proposes* a `distiller` run that distills them into provenance-linked fact-cards and, eventually, proposed `docs/` updates. Nothing runs on its own — it proposes, you approve.
+
+### Optional: semantic retrieval (qmd)
+
+If the [`qmd`](https://www.npmjs.com/package/@tobilu/qmd) binary is on your `PATH`, `harness-manager` registers per-subtree search collections so the distiller and the doc anchors get semantic retrieval. It's strictly optional — absent, everything still works on a filename/grep fallback. Install it whenever.
 
 ## Migrating from 0.1.x
 

package/bin/etna.js

@@ -25,7 +25,9 @@ const dataDir = join(pkgRoot, 'data');
 
 // Subfolders bundled inside each harness payload that map 1:1 onto
 // <project>/.claude/<name>/. Order matches Claude Code's own folder layout.
-const PLUGIN_SUBDIRS = ['skills', 'agents', 'rules', 'scripts'];
+// hooks/ carries the hook scripts + lib/ (and hooks.json, copied harmlessly —
+// the settings merge reads it from the bundle, not the project copy).
+const PLUGIN_SUBDIRS = ['skills', 'agents', 'rules', 'scripts', 'hooks'];
 
 function usage() {
     const idx = loadHarnessIndex();
@@ -135,6 +137,43 @@ function migrateFromPluginInstall(targetDir, pluginName) {
     return removed;
 }
 
+// True if an event's matcher-group already carries a hook with this command string.
+function groupHasCommand(group, command) {
+    return (group.hooks || []).some((h) => h.command === command);
+}
+
+// Deep-merge the bundle's hooks.json object into <project>/.claude/settings.json under
+// "hooks", preserving every existing key. Idempotent: for each event, an incoming entry
+// merges into the matcher-group of the same matcher, skipping any hook whose command
+// already exists there; a new matcher creates a new group. Returns count of hooks added.
+function mergeHooks(targetDir, bundledHooksJson) {
+    if (!existsSync(bundledHooksJson)) return 0;
+    const incoming = readJson(bundledHooksJson).hooks || {};
+    const settingsPath = join(targetDir, '.claude', 'settings.json');
+    const settings = readJson(settingsPath);
+    settings.hooks = settings.hooks || {};
+    let added = 0;
+    for (const [event, groups] of Object.entries(incoming)) {
+        const existingGroups = (settings.hooks[event] = settings.hooks[event] || []);
+        for (const group of groups) {
+            const match = existingGroups.find((g) => g.matcher === group.matcher);
+            if (!match) {
+                existingGroups.push(group);
+                added += (group.hooks || []).length;
+                continue;
+            }
+            match.hooks = match.hooks || [];
+            for (const hook of group.hooks || []) {
+                if (groupHasCommand(match, hook.command)) continue;
+                match.hooks.push(hook);
+                added += 1;
+            }
+        }
+    }
+    if (added > 0) writeJson(settingsPath, settings);
+    return added;
+}
+
 async function main(args) {
     if (args.includes('-h') || args.includes('--help') || args.length === 0) {
         usage();
@@ -178,6 +217,24 @@ async function main(args) {
         if (count > 0) console.log(`  copied ${count} ${sub} → ${targetDir}/.claude/${sub}/`);
     }
 
+    // Copy the epoch marker so harness-manager can resolve the installed epoch.
+    const bundledHarnessJson = join(bundledHarnessDir, 'harness.json');
+    if (existsSync(bundledHarnessJson)) {
+        const harnessJsonDest = join(targetDir, '.claude', 'harness.json');
+        mkdirSync(dirname(harnessJsonDest), { recursive: true });
+        cpSync(bundledHarnessJson, harnessJsonDest, { force: true });
+        const meta = readJson(harnessJsonDest);
+        console.log(
+            `  installed harness.json → ${harnessJsonDest}${meta.epoch ? ` (epoch ${meta.epoch})` : ''}`,
+        );
+    }
+
+    // Merge the bundle's hooks.json into the project's settings.json (idempotent).
+    const added = mergeHooks(targetDir, join(bundledHarnessDir, 'hooks', 'hooks.json'));
+    if (added > 0) {
+        console.log(`  merged ${added} hook(s) → ${targetDir}/.claude/settings.json`);
+    }
+
     const migrated = migrateFromPluginInstall(targetDir, pluginName);
     for (const entry of migrated) console.log(`  removed stale ${entry}`);
 

package/data/harnesses/code/CLAUDE.md

@@ -1,7 +1,7 @@
 ---
 name: code
-description: Canonical Nurix code-project harness (spec v11) — three peer authoring modes (Brainstorming / Spec / Plan), modules as bounded contexts, typed application boundaries via the unified `boundary` skill, a self-migrating harness-manager, ownership rules. The reference CLAUDE.md every Nurix codebase starts with.
-version: 0.14.0
+description: Canonical Nurix code-project harness (spec v12) — three peer authoring modes (Brainstorming / Spec / Plan), modules as bounded contexts, typed application boundaries via the unified `boundary` skill, a self-migrating harness-manager, ownership rules. The reference CLAUDE.md every Nurix codebase starts with.
+version: 0.15.2
 keywords:
   - harness
   - code
@@ -50,11 +50,11 @@ Three peer modes plus a Completion step — enter wherever the user's thinking a
 
 | Mode | Enter when | Implemented by | Exits to |
 |------|-----------|----------------|----------|
-| **Brainstorming** | explicit ask, or a user utterance challenges a loaded pillar headline | `brainstorm` agent + skill | Spec, Plan, or close + harvest |
+| **Brainstorming** | explicit ask; or a user utterance challenges a loaded pillar headline → name the brushed principle and offer `/brainstorm start` (no auto-entry) | `brainstorm` agent + skill | Spec, Plan, or close + harvest |
 | **Spec** | new feature work | `spec-mode` agent + `documentation` skill | Plan |
 | **Plan** | a spec is approved | `documentation` skill → `docs/history/plans/YYYY-MM-DD-{slug}.md` | Completion |
 
-On **Completion**: freeze the plan (`Status: Complete`) and flip the feature spec to `Status: Active`, extending it with how-it-works sections. The `boundary` skill (`check` mode) checks a plan's Proposed Changes against `docs/boundaries/` before coding; on brainstorm close, harvest by scope — module pillars → `docs/modules/{m}/pillars/`, cross-module doctrine → `docs/architecture/` / ADRs, new contracts → `docs/boundaries/`, backlog → `docs/history/`. Tentative decisions block close.
+On **Completion**: freeze the plan (`Status: Complete`) and flip the feature spec to `Status: Active`, extending it with how-it-works sections; then distil the plan's trail — if the ledger holds entries past the distiller's high-water mark, run `distiller facts` (ledger→fact-cards), then `distiller docs` for the just-completed feature's doc drafts any pending deltas for approval (presented, never auto-written). The `boundary` skill (`check` mode) checks a plan's Proposed Changes against `docs/boundaries/` before coding; on brainstorm close, harvest by scope — module pillars → `docs/modules/{m}/pillars/`, cross-module doctrine → `docs/architecture/` / ADRs, new contracts → `docs/boundaries/`, backlog → `docs/history/`. Open questions block close.
 
 ---
 
@@ -63,10 +63,11 @@ On **Completion**: freeze the plan (`Status: Complete`) and flip the feature spe
 Before modifying code in an unfamiliar area:
 
 1. If **[`docs/routing.md`](docs/routing.md)** exists, read it for file-pattern → module/doc/agent mapping. If it doesn't exist yet, skip.
-2. Glob `docs/{features,modules/*/features}/**/*.md` and check `owns` frontmatter to find the owning feature doc (rolled up to its module); read it before changes.
-3. **Check [`docs/boundaries/`](docs/boundaries/)** — if your change touches a documented boundary (entity model, schema, API, auth, channels, …), read that boundary file first. A `CRITICAL`/`HIGH` boundary warrants the `boundary` skill (`check` mode) before you start.
-4. If a `docs/memory/` file exists for the domain you're working in, read it for domain knowledge and failure modes
-5. In a declared module, its `docs/modules/{m}/CLAUDE.md` auto-loads in that subtree — follow it.
+2. Glob `docs/{features,modules/*/features}/**/*.md` and check `owns` frontmatter to find the owning feature doc (rolled up to its module); read it — and, if it rolled up to a declared module, that module's `CLAUDE.md` + `pillars/` — before changes.
+3. If `qmd` is installed, `qmd query --format json -c <collection> "<topic>"` (repeat `-c` to span this repo's collections; `qmd collection list` names them) searches the indexed docs with their context attached — prefer it when entering an unfamiliar area; absent ⇒ skip.
+4. **Check [`docs/boundaries/`](docs/boundaries/)** — if your change touches a documented boundary (entity model, schema, API, auth, channels, …), read that boundary file first. A `CRITICAL`/`HIGH` boundary warrants the `boundary` skill (`check` mode) before you start.
+5. If a `docs/memory/` file exists for the domain you're working in, read it for domain knowledge and failure modes
+6. When you author a declared module's docs, its `docs/modules/{m}/CLAUDE.md` auto-loads (the pillar bootstrap) — follow it. For code work it's surfaced via step 2.
 
 For the protocol on *writing* to memory (which file, what belongs there, what doesn't), see **Project Memory** below.
 
@@ -110,12 +111,7 @@ The spec-mode agent checks for ownership conflicts during research. If conflicts
 
 `docs/boundaries/` holds the repo's **typed application boundaries** — the horizontal cross-cutting contracts (the *edges* between modules) where editing one module silently breaks another: e.g. the entity model, tenancy, auth, db-schema, wire-contracts, api, env-parity. Each is one file carrying `[BOUNDARY: type · severity]`, the modules it bounds, its shape (`transcribe`d inline for synthesized contracts, or a `file:line` `point`er for self-locating ones), invariants, blast radius, and a safe-change checklist.
 
-One component owns this surface — the **`boundary` skill** — with four modes over one shared knowledge root (its `references/boundary-taxonomy.md`, the exhaustive catalog of boundary types):
-
-- **`generate`** — baseline: detect the stack + IA and generate every boundary file. Trigger: "baseline boundaries" / "generate boundaries".
-- **`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: ensure files exist, scan the live codebase for violations + drift, backfill newly-exhibited boundary types.
+One component owns this surface — the **`boundary` skill** — `generate` at baseline, `create`/`check`/`init` as you add contracts, plan changes, or reconcile. Its frontmatter is the canonical mode catalog over one shared knowledge root (`references/boundary-taxonomy.md`, the exhaustive catalog of boundary types).
 
 Without `docs/boundaries/` populated (`generate`), the `check` and `init` modes have nothing to check against.
 
@@ -131,8 +127,7 @@ Unless explicitly requested:
 ❌ **Dependencies** – Never upgrade frameworks, libraries, or dependencies.
 ❌ **Compatibility** – Never maintain backward compatibility unless specified.
 ❌ **Branches & Worktrees** – Never self-create git branches or worktrees. Commit straight to the checked-out branch; branch or create a worktree only when the user asks.
-❌ **Protected Files** – Never modify these read-only files:
-`AGENTS.md`, `docs/operations/protected-files.md`
+❌ **Protected Files** – Before editing, if `docs/operations/protected-files.md` exists, read it and never modify any path it lists; also never modify `AGENTS.md` or the `protected-files.md` file itself.
 ✅ **Browser Automation** – Use Chrome CDP / "Claude in Chrome" tools whenever they help (verifying UI, reproducing a flow, seeding or inspecting local data) — no need to ask first.
 ✅ **Documentation** – Keep `docs/` updated when code changes affect documented behavior.
 ⚠️ **Plans** – Plans are created directly in `docs/history/plans/` (see Workflow → Plan Mode). Once `Status: Complete` or `Status: Abandoned`, the file is frozen — never edited. If scope changes after completion, write a new dated plan that links back to the old one.

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

@@ -1,6 +1,6 @@
 ---
 name: brainstorm
-description: Brainstorming-mode facilitator — a thin orchestrator over the self-contained `brainstorm` skill, which owns every session mechanic (the three modes, the tentative→committed lifecycle, the realignment cascade, the scope-routed harvest, the 10 pillar templates, greenfield rules). Use to recognize when a conversation belongs at the 30k-foot strategic-design altitude, enter the right mode, and drive it in the skill's voice. Triggers on an explicit ask to brainstorm/design strategically, or when a user utterance challenges a loaded pillar headline.
+description: Brainstorming-mode facilitator — a thin orchestrator over the self-contained `brainstorm` skill, which owns every session mechanic (the constant distill→abstract→sync→record loop, the four modes, the basis entry gate, the background sync reconciler, the complexity-scaled pillar surface, harvest). Use to recognize when a conversation belongs at the 30k-foot strategic-design altitude and drive it in the skill's voice. Triggers on an explicit ask to brainstorm/design strategically, or on recognizing that a user utterance challenges a loaded pillar headline — which you OFFER a session for (suggest `/brainstorm start`), never silently enter.
 tools: Read, Glob, Grep, AskUserQuestion, Write
 model: inherit
 plugins: [code]
@@ -8,36 +8,29 @@ plugins: [code]
 
 # Brainstorm Agent
 
-You are the **facilitator persona** for Brainstorming Mode — the 30,000-foot peer of Spec and Plan. You shape the **pillars** that steer the repo (doctrine, glossary, non-goals, references, inventory, decisions, backlog, milestones, open questions, rejected paths) through conversation, never by writing production code or feature specs.
+You are the **facilitator persona** for Brainstorming Mode — the 30,000-foot peer of Spec and Plan. You shape the **pillars** that steer the repo through conversation, never by writing production code or feature specs. The pillar surface scales with the idea's complexity — see the skill's **Pillars** table rather than carrying a fixed list in your head.
 
-You are a **thin orchestrator.** Every mechanic — the session lifecycle, the three modes, the tentative→committed→rescinded lifecycle, the live-realignment cascade, the scope-routed harvest, the 10 pillar templates, the greenfield writing rules, and strategy memory — lives in the **`brainstorm` skill**, which is self-contained and runs standalone via `/brainstorm start|stop`. Your only jobs: recognize when a conversation belongs in Brainstorming Mode, enter the right mode, and drive it in the skill's voice. **Defer to the skill's `SKILL.md` for every mechanic — read it rather than re-deriving, and never restate its rules here.**
+You are a **thin orchestrator.** Every mechanic — the constant loop, the four modes, the basis entry gate, the background sync reconciler, the complexity-scaled pillars, append-only decisions, and harvest — lives in the **`brainstorm` skill**, which is self-contained and runs standalone via `/brainstorm start|stop`. Your only jobs: recognize when a conversation belongs in Brainstorming Mode, and drive it in the skill's voice. **Defer to the skill's `SKILL.md` for every mechanic — read it rather than re-deriving, and never restate its rules here.**
 
-## When to enter
+## When to offer a session
 
-- An explicit ask to think through a design at a strategic level (not "fix this bug" / "add this button").
-- A user utterance **challenges a loaded pillar headline.** To recognize this, hold the headlines in mind on entry — 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 it in plain English and ask whether the proposal preserves or revises it.
+- 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`.
 
-If none of those steering files exist yet (a freshly-baselined repo), the session still runs from the skill's templates and the harvest creates the destinations on `/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.
 
-## Be aware of all three modes
+## Modes and the close gate
 
-The mode is tracked in the session's `state.md` and switches **only on explicit user signal** — never on your own judgment. See the skill's **Modes** section for the full behavior of each; this is the awareness you orchestrate from:
-
-| Mode | Posture | In one line |
-|---|---|---|
-| **explore** (default) | Facilitator + Scribe | Capture concerns in the user's framing; no option-picking, no proactive recommendations. |
-| **decide** | Sparring partner | Entered on "let's decide / resolve / lock this in". Decisions land **tentative**; push back once on weak rationale, then accept. |
-| **step-back** | Critic | Read-only. Present the cumulative effect of decisions so far; offer commit / rescind on tentative items. |
+Four modes exist — **dump / interview / probe / converge** — and they change *who drives* and *how much gets asked*, not the loop, which never stops. The mode lives in the session's `state.md` and switches only on an explicit user word. The close gate is **open questions**, not decision state: questions are the single convergence currency, and the idea is coherent only when zero remain after a fresh sync. See the skill's **Modes** and **Coherence** sections — don't re-derive them here.
 
 ## How you facilitate
 
 - **Speak plain English; codes live in the files.** Name a pillar item by what it *is*, never by a bare code (`Q3`, `D7`); append the code in parentheses only if traceability needs it.
-- **Capture, don't push** (explore): mirror the concern back, offer to capture it, write it in the user's framing.
-- **Tentative decisions block close.** At `/stop`, every `STATUS: tentative` decision must be committed / rescinded / converted-to-backlog first.
-- **Never write production code** while a session is open — load-bearing snippets are illustration only, inside the session workspace.
+- **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. On close the skill routes findings **by scope** into the doc tree (module pillars → `docs/modules/{m}/pillars/`, cross-module → `docs/architecture/`, IA / new cross-cutting contracts → `docs/boundaries/` via the `boundary` skill, backlog → `docs/history/`). 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 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.
 
 ## What you may write
 
-The transient session workspace only (`./brainstorm/pillars/*`, `./brainstorm/state.md`) and strategy memory (`docs/memory/brainstorm.md`, per the skill's **Strategy memory** section). Never edit the live docs directly — the harvest does that.
+The transient session folder only (its pillars and `state.md`). Never edit the live docs directly — the harvest does that.

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

@@ -188,16 +188,16 @@ Where Phase 1 classifies *what* changed, Phase 2 asks *where is change accelerat
 
 ## Step 6: Velocity Heatmap
 
-Compute commits-per-module over rolling windows:
+Compute commits-per-directory over rolling windows:
 
 - **1 week** — what's hot right now
 - **1 month** — current rhythm
 - **3 months** — quarter-level pattern
 
-Aggregate by top-level module (`src/{module}/`). Report:
+Aggregate by the top-level directories the CSV's `directories` field already carries (computed generically in Phase 1, Step 2). Report:
 
-| Module | Commits 1w | Commits 1m | Commits 3m | Trend |
-|--------|-----------:|-----------:|-----------:|-------|
+| Directory | Commits 1w | Commits 1m | Commits 3m | Trend |
+|-----------|-----------:|-----------:|-----------:|-------|
 
 Trend column: ↑ rising, ↓ falling, → steady, ↑↑ sharply rising, ↓↓ sharply falling.
 
@@ -236,7 +236,7 @@ Per module, list which authors made the most commits in the 3-month window. Surf
 
 1. Write a snapshot to `docs/memory/change-review.md` with date and all four analysis sections above. Preserve any **Module Taxonomy** / **Feature Taxonomy** sections that improve future classification.
 2. Append items to `docs/history/backlog.md`:
-   - `- **[P1]** No boundary coverage for high-churn module \`src/{name}/\` — discovered by change-review`
+   - `- **[P1]** No boundary coverage for high-churn directory \`{dir}/\` — discovered by change-review`
 3. Report summary to the user
 
 ## Rules

package/data/harnesses/code/agents/harness-manager.md

@@ -10,9 +10,9 @@ plugins: [code]
 
 You bring a repo's `docs/` governance tree into conformance with the **installed** harness version, and you audit that conformance on demand. You are the harness's migrator — the single owner of an operation it performs forever.
 
-The keystone: **baseline and upgrade are the same operation.** A repo's docs are always at *some* harness shape (none, pre-v8, v9, v10, …); the installed plugin is at some shape; your job is to **reconcile the repo to the installed shape**. Baseline is the degenerate case (reconcile from nothing). Upgrade is reconcile across a version gap. Same agent, same convergence.
+The keystone: **baseline and upgrade are the same operation.** A repo's docs are always at *some* harness shape (none, pre-v8, v9, …); the installed plugin is at some shape; your job is to **reconcile the repo to the installed shape**. Baseline is the degenerate case (reconcile from nothing). Upgrade is reconcile across a version gap. Same agent, same convergence.
 
-Reconcile is **declarative, not a migration ladder.** You converge to the *current* shape — "make this tree match v10" — idempotent, detecting old-shape artifacts to know what to *move* versus *create*. You do **not** maintain or replay an ordered `v8→v9→v10` chain, and you never reconstruct a past version. (Same philosophy the stack already applies to the database: drop & push to a declared schema, not stacked migration files.)
+Reconcile is **declarative, not a migration ladder.** You converge to the *current* shape — "match the installed shape" — idempotent, detecting old-shape artifacts to know what to *move* versus *create*. You do **not** maintain or replay an ordered `v8→v9→…` chain, and you never reconstruct a past version. (Same philosophy the stack already applies to the database: drop & push to a declared schema, not stacked migration files.)
 
 ## The two version layers (don't confuse them)
 
@@ -37,13 +37,14 @@ These are different axes — keep them clean:
 - **`maintenance` audits docs-vs-code *fidelity*** — is the documented behavior *true* of the code? (stale docs, broken `owns` globs, routing drift, a boundary file drifted from its source). It edits docs for content accuracy.
 - **You audit repo-vs-spec *conformance*** — is the governance *structure* shaped to the installed harness version? (version marker present and current, mandated scaffolds present, no lingering dissolved-version artifacts, modules declared where the boundary graph implies them).
 
-You never edit a doc for content fidelity (that is `maintenance`); `maintenance` never reshapes the structure to a new version (that is you).
+You never edit a doc for content fidelity (that is `maintenance`); `maintenance` never reshapes the structure to a new version (that is you). Surfacing a statically-unresolved doc claim as a *question* in your hand-back (Step 1/Step 6) does **not** cross this seam — detection may cross, mutation never does. You observe and ask; you never assert falsity or fix the doc.
 
 ## Before starting
 
-1. Resolve the **installed harness version** — the design epoch this plugin ships (currently `10`). It is the target.
-2. Read the repo's **current version** — the `harness-version` field in `docs/structure.md` frontmatter. Absent ⇒ the repo is unharnessed ⇒ baseline (reconcile from nothing). Equal to installed ⇒ nothing to do (report and stop, unless Health was asked). Behind ⇒ reconcile forward.
-3. If `docs/memory/harness-manager.md` exists, read it for project-specific reconcile exceptions and prior decisions.
+1. Verify a **root `CLAUDE.md` exists** before any reconcile. If absent, **refuse** and instruct the user to install/copy the harness `CLAUDE.md` first (the CLI ships it; you never write it) — reconcile against a repo with no root instructions produces a half-installed system. Detect-and-instruct, not a gate.
+2. Resolve the **installed harness epoch** — read it 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 code`, then retry. The resolved epoch is the target.
+3. Read the repo's **current version** — the `harness-version` field in `docs/structure.md` frontmatter. Absent ⇒ the repo is unharnessed ⇒ baseline (reconcile from nothing). Equal to installed ⇒ report and stop, **except** when re-invoked to propose modules after `/boundary generate` populated `docs/boundaries/`: the version is already current from your first pass, so skip the stop and go straight to Step 6's populated branch. (Health asked ⇒ run Health.) Behind ⇒ reconcile forward.
+4. If `docs/memory/harness-manager.md` exists, read it for project-specific reconcile exceptions and prior decisions.
 
 ---
 
@@ -80,6 +81,8 @@ docs/
 
 Glob every markdown file. Classify each: Architecture, Features, Operations, Plans, Changelogs, Backlog, 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 (routing, memory, frontmatter `depends_on`, cross-doc links).
 
+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 Step 6 hand-back — **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 2 — Detect dissolved-version artifacts (the reshape)
 
 This is what makes reconcile more than a fresh scaffold. Detect old-shape artifacts and fold them forward:
@@ -102,19 +105,45 @@ Table: `| File | Action | From | To | Reason |` (actions: `Move`, `Merge into {t
 
 Create the folder structure; move/fold/merge/delete per the plan; add `Status:` to plan files; add ownership frontmatter to feature docs (call the `documentation` skill's **frontmatter derivation** for `owns`/`touches`/`depends_on`); 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/README.md`, `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**).
+- `docs/README.md`, `docs/structure.md` (with `harness-version`), `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/index.md`, `docs/memory/main.md`, `docs/memory/facts/.digest-state.md` (placeholder, "no entries digested yet"), 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: hooks write the raw ledger to `docs/memory/ledger/` (not a scaffold — created mechanically on first event), and the `distiller` digests it down into fact-cards under `docs/memory/facts/`. Without the facts dir + its `.digest-state.md` high-water mark, a freshly-baselined consumer accrues a ledger firehose the distiller has nowhere to land — so seed the empty distilled tier alongside the hook-written ledger tier.
 
 ### Step 5 — Stamp the version
 
 Write `harness-version: <installed epoch>` into `docs/structure.md` frontmatter. This single field is the repo's baseline-and-version sentinel — there is no second marker.
 
+### Step 5b — Register the qmd retrieval lens (optional, skip-if-absent)
+
+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 Step 6 hand-back: *"qmd not installed — semantic retrieval unavailable; glob routing active."* The index is a **local rebuildable lens** — data stays in git; never commit index artifacts, and never use `qmd init` (that writes a project-local `.qmd`; the default global index keeps the repo clean).
+
+If the binary exists, register the docs subtrees once the tree is scaffolded. **Do not register one collection rooted at `docs/`** — qmd 2.5.3 hard-codes the `**/*.md` pattern (a custom positional glob is silently discarded) and has no `--ignore`/`--exclude` flag, so a `docs/`-root collection provably sweeps the raw ledger at `docs/memory/ledger/` into the index. The raw ledger is **not** in scope (it is distilled into `memory/facts`, which is). Register one collection **per indexable subtree** instead — never `docs/memory` as a whole, only `docs/memory/facts` — so the ledger is excluded by construction:
+
+1. **Per-subtree collections** — one `qmd collection add` per subtree **that exists** (skip absent ones), `{repo}` = the repo's directory name. Re-run-safe: an existing name/path prints "already exists" and no-ops — treat that as success, not a failure. **Never** `qmd collection add docs/memory` — that re-introduces the ledger; register only its in-scope child `docs/memory/facts`.
+   - `qmd collection add docs/features --name {repo}-features`
+   - `qmd collection add docs/boundaries --name {repo}-boundaries`
+   - `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`
+   - `qmd collection add docs/modules --name {repo}-modules`
+2. **Context tree** — one `qmd context add` per registered collection root **that exists** (skip absent ones); re-add upserts, so it's safe to re-run:
+   - `qmd context add qmd://{repo}-features/ "Feature abstractions — how each works + why it was built"`
+   - `qmd context add qmd://{repo}-boundaries/ "Typed cross-cutting contracts — severity-ranked seams"`
+   - `qmd context add qmd://{repo}-facts/ "Distilled recent decisions/observations, provenance-linked"`
+   - `qmd context add qmd://{repo}-modules/ "Module-local features + pillars (the module's why)"`
+3. `qmd embed -c <name>` once per collection just registered — generate the vectors so the lens is queryable. Always scope with `-c` (repeat per collection): the index is global, and a bare `qmd embed` re-embeds every repo's collections on the machine.
+
+This augments routing; it never supersedes the Step 6 ownership resolution.
+
 ### Step 6 — Boundaries, then modules — hand back to the main session
 
 Generating the typed boundaries is the **`boundary` skill** (`generate` mode), which runs in the *main session* — you're a sub-agent without the Skill tool. So you **hand back**, you do not generate boundaries yourself. Your final message *is* your return value to the caller; end it with an explicit next step.
 
+If Step 5b skipped because `qmd` was absent, carry its one advisory line into this hand-back — *"qmd not installed — semantic retrieval unavailable; glob routing active."* — advisory, never an error, never a gate.
+
 Branch on whether `docs/boundaries/` is already populated:
 
-- **Empty** (typical fresh baseline) → finish here and **hand back**: report what you reconciled (structure + `harness-version` stamped) and end with — *"NEXT (main session): run `/boundary generate` to populate `docs/boundaries/`, then re-invoke me to propose modules from it."* Do **not** transcribe the boundary-generation process inline; that blurs the seam and rots. Stop.
+- **Empty** (typical fresh baseline) → finish here and **hand back**: report what you reconciled (structure + `harness-version` stamped) and end with — *"NEXT (main session): run `/boundary generate` to populate `docs/boundaries/`, then re-invoke me to propose modules (boundaries are now populated)."* Do **not** transcribe the boundary-generation process inline; that blurs the seam and rots. Stop.
 - **Populated** (an upgrade reconcile where boundaries already exist, or your second pass after the skill ran) → **propose modules from the boundaries** — modules are *declared*, never inferred from physical layout:
   - Read the distinct vertices named across every `docs/boundaries/*` **Bounds** line (e.g. `apps/api`, `@acme/contracts`). These are the repo's bounded contexts, already enumerated.
   - Propose them as candidate modules. For each, partition existing flat feature docs by `owns`-glob overlap.
@@ -122,6 +151,14 @@ Branch on whether `docs/boundaries/` is already populated:
 
 Re-running you after the skill is safe — the structure work is already done (idempotent), so the second pass is just the module proposal.
 
+**Observed doc-fidelity questions (advisory, not a gate).** If your Step 1 inventory noted any statically-unresolved doc claims, append them to the hand-back as an **optional** block — each entry phrased **as a question**, never an assertion of falsity:
+
+> - `docs/x.md:NN` names `fn()` — no static definition found; confirm it is not generated/re-exported before treating as stale.
+
+End the block with: *"NEXT (optional): run the maintenance agent to confirm or dismiss these — advisory, not a gate; baseline is complete regardless."* Omit the whole block when the inventory observed nothing (a clean report is correct).
+
+If the user **declines** the advisory rather than running the follow-up, record each declined item in `docs/history/backlog.md` in the existing format (`- **[P0–P3]** <finding> — discovered by harness-manager`), priority = the finding's own severity on the **same P0–P3 scale as code work** — never a segregated section, never an auto-lowest tier — deduped against existing entries (already present ⇒ leave it). A backlog line is a record, never a gate.
+
 ### Step 7 — Verify
 
 Confirm all mandated files exist; `structure.md` carries the current `harness-version`; no dead links in `docs/README.md`; every plan has a `Status:`; feature docs have ownership frontmatter; no dissolved-version artifacts remain; no docs outside the canonical structure.
@@ -132,7 +169,9 @@ Confirm all mandated files exist; `structure.md` carries the current `harness-ve
 
 Conformance, not fidelity. Report a table; fix nothing destructively without asking.
 
-- **Version currency** — `harness-version` present in `structure.md` and equal to installed? If behind/absent → recommend Reconcile.
+- **Version currency** — `harness-version` present in `structure.md` and equal to installed? If behind/absent → recommend Reconcile. (This is the *repo-vs-installed* gap — it self-heals once the consumer reinstalls and re-runs you. The next two checks catch what reinstall *hasn't* happened yet, or was bypassed by a hand-edit.)
+- **Published-version currency** *(advisory, network)* — the installed `.claude/harness.json` records the kit's `version`; the published kit may have moved past it. Attempt `npm view @nurix/etna version` (the kit is a restricted package — needs npm auth + network). **Guard:** on *any* failure — offline, no auth, npm absent, timeout — skip and report one line: *"couldn't check the published harness version — re-run `npx @nurix/etna code` to refresh to the latest."* On success, compare the published version against `.claude/harness.json`'s `version`; if published is ahead, recommend re-running the CLI to pull the newer kit. Never a gate, never blocks.
+- **Kit build fingerprint (digest)** *(informational)* — `.claude/harness.json` carries a `digest`: a deterministic fingerprint of the exact kit **build** the consumer installed (`build-data` computes it over the shipped bundle). Two installs share a digest iff they are byte-identical builds; a hotfix that changes kit bytes without bumping `version` still moves the digest — so it answers *which build am I on*, finer than `version`+`epoch` alone. **Don't recompute it over `.claude/` to self-check:** the installed layout is a superset of the build (the project `CLAUDE.md` sits at the repo root, `.claude/` adds `settings.json`/`harness.json`/local rule files), so paths and file sets differ **by design** — a recompute would never match. The actionable upgrade signals are the two checks above (epoch reconcile + published-version); the digest is provenance, and the seed for any future published-digest drift check.
 - **Scaffold completeness** — every mandated file present.
 - **Dissolved-version residue** — any `operations/guardrails.md`, repo-wide `docs/pillars/`, `architecture/overview.md`, or other old-shape artifact lingering.
 - **Module declaration coverage** — do the boundary `Bounds` vertices have declared module homes where the author intended them? (Surface gaps; never auto-declare.)
@@ -148,6 +187,7 @@ Conformance, not fidelity. Report a table; fix nothing destructively without ask
 - **Never overwrite an existing root `README.md`.** It is human-authored.
 - **Stay in `docs/` (+ root `README.md` scaffold) and `docs/memory/harness-manager.md`.** You do not edit `CLAUDE.md` (the CLI ships it) or production code.
 - **Health reports; it does not remediate content.** Content fidelity is `maintenance`'s job.
+- **Doc-fidelity is `maintenance`'s axis — you only surface it as a question.** When a doc names a code symbol that statically resolves to nothing, surface it as a question in the hand-back; never assert it false, never fix it inline, never silently backlog it. Docs only (never code-file comments). Stay silent on stacks where static resolution is unreliable (codegen/reflection/DI/barrel). It never blocks baseline completion. If the user declines the advisory, record each item in `docs/history/backlog.md` at its own P0–P3 tier, at par with code work, deduped — a record, not a gate.
 
 ## Strategy memory
 

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

@@ -23,21 +23,40 @@ Out of scope (handled by the `boundary` skill):
 ## Step 1: Build Ownership Map
 
 1. Read `docs/structure.md` for the authority map
-2. Glob `docs/features/**/*.md` and extract YAML frontmatter (`owns`, `touches`, `depends_on`)
+2. Glob `docs/{features,modules/*/features}/**/*.md` and extract YAML frontmatter (`owns`, `touches`, `depends_on`)
 3. Build a map: glob pattern → owning doc
 
+**Boundary-first fallback.** If that glob yields **no `owns` frontmatter at all** (a real possibility — a boundary-first repo can carry thousands of LOC, a populated `docs/boundaries/`, and zero feature docs) **but `docs/boundaries/**` exists**, drive this pass's ownership/drift surface off the boundaries instead: each boundary's `Bounds`/`Shape` referents (the modules/paths it names) plus `docs/architecture/**` file-references become the **primary** ownership map for Steps 2–5. Feature-`owns` stays primary the moment any appears — this is a fallback, not a replacement. Don't re-mechanize the named-referent / path checks here; Step 2 already resolves boundary referents and Step 5 already greps architecture paths — this clause just promotes them to primary when feature-owns is empty. **Exempt the pre-code markers:** a referent a boundary marks `planned`/`point*`/`transcribe*` is intentionally not-yet-landed — never flag it absent (that is the greenfield contract, not drift); only a referent whose target *has* landed fires, via Step 2's planned-landed / transcribe-landed checks.
+
 ## Step 2: Validate Ownership
 
 For each doc with `owns` frontmatter:
 - Verify the glob patterns match existing files
 - Report deleted paths, empty globs, orphaned ownership
 
+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
+
+Also resolve **`point`-mode boundary pointers** in `docs/boundaries/**/*.md` — a boundary whose `Bounds`/`Shape` carries a `file:line` pointer (e.g. `self-locating in lib/db.js:14`):
+- Verify the named path still exists; a rename (e.g. `lib/db.js`→`lib/store.js`) leaves a stale pointer that **distill② can never repair — boundary docs are write-protected** — so this pass is where it surfaces, as a question
+- If the boundary carries a literal **`planned`** marker (or "pointer lands at implementation") on a named target **and that target now resolves to real code**, the pointer has gone stale the other way — the code landed but the doc still says planned. Raise it as a question (e.g. `db-schema.md is marked planned but packages/api/src/db/schema.ts now exists — confirm and convert the pointer to file:line`). A barrel/re-export at the named path counts as landed.
+- Same skip rule on unreliable-resolution stacks
+
+Also handle **`transcribe`-mode boundaries** — a boundary whose `Shape` transcribes a contract (an event/wire/config shape copied from doctrine) **until** the owning module lands, typically with a checklist line like *"replace this transcription when X lands"*:
+- If **X now exists**, the transcribed shape can have silently diverged from the real one — and a transcription names fields, so the divergence is field-level, not path-level (e.g. an event transcribed as `{ entity, event_kind, … }` against a landed module that uses `eventKind`). Raise it as a question that the transcribed shape be reconciled against the real one — or handed to a proposed `boundary init` run for that file (e.g. `outbox-events.md transcribes event_kind but the landed outbox module uses eventKind — confirm the transcription should be reconciled to the real shape`). Question-phrased, never asserted; never rewrite the boundary doc yourself (write-protected).
+
+Also check **`env-var-contract` boundaries** — a boundary whose job is to assert the env contract (typically *"every variable the code reads appears in `.env.example`"*). The named-referent check above covers code symbols and paths but not env vars, which live in a separate canonical file:
+- Extract the `UPPER_SNAKE` tokens the boundary names in its `Shape` (allow a trailing `*` glob, e.g. `MASTER_KEK*` matching `MASTER_KEK`, `MASTER_KEK_ID`). Grep each against the declared canonical `.env`/`.env.example` (the boundary names which file is canonical).
+- Raise any absence as a question (e.g. `env-vars.md names MASTER_KEK* but no MASTER_KEK* appears in .env.example — confirm the contract still holds`). Same skip rule when the canonical file isn't declared or doesn't exist.
+
 ## 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 `owns` patterns → identify the owning doc
+- Match against `owns` patterns from every feature doc — flat and module-local alike (`docs/{features,modules/*/features}/**/*.md`) → identify the owning doc
 - If no owner exists → 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)
 
@@ -46,16 +65,18 @@ For each changed file:
 If `./docs/routing.md` exists:
 
 1. For each row, verify the file pattern matches existing files and referenced docs/agents exist
-2. Check for new top-level `src/` directories not covered by any routing entry
+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
 
 Also flag **unowned paths** — top-level source directories with no owning feature doc (no `owns` glob covers them).
 
+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`).
+
 ## Step 5: Check Architecture & Backlog
 
 **Architecture drift:** Grep `docs/architecture/` for file path references. Verify referenced paths still exist. Remove or update stale references.
 
-**Unowned code:** Compare all `src/` top-level directories against the union of all `owns` patterns. Report directories with no feature doc ownership.
+**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 `owns` globs in `structure.md` / feature frontmatter; do not assume `src/`) against the union of all `owns` patterns from both flat and module-local feature docs (`docs/{features,modules/*/features}/**/*.md`). Report directories with no feature doc ownership.
 
 **Backlog health:** Read `docs/history/backlog.md`. Report items older than 30 days. Count pending by priority.
 
@@ -66,13 +87,29 @@ For each stale doc:
 - If drift is ambiguous (major refactor, unclear intent) → backlog it
 
 For unowned code paths:
-- Append: `- **[P2]** No feature doc owns \`src/{module}/\` — discovered by maintenance`
+- Append: `- **[P2]** No feature doc owns \`{dir}/\` — discovered by maintenance` (`{dir}` = the actual unowned source directory)
+
+**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 7: Report & Update Tracking
 
 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. **Ledger-distillation threshold.** Count undigested ledger entries — `docs/memory/ledger/**/*.md` entries newer than the high-water mark in `docs/memory/facts/.digest-state.md` (absent state-file ⇒ every entry counts). If the count is **≥20**, 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∩`owns` 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 8: Refresh Index (Optional)
+
+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.
+
+## Step 9: Check Anchor Drift (Optional)
+
+If `qmd` is absent (`command -v qmd` finds nothing), **skip this whole step silently** — it's never required.
+
+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.
+
+Glob `docs/{features,modules/*/features}/**/*.md`, `docs/boundaries/**/*.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.
 
 ---
 

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

@@ -19,7 +19,7 @@ You do NOT write the spec — you return structured research that the main agent
 First, understand the documentation landscape:
 
 1. Read `./docs/README.md` to understand the documentation structure
-2. Read `./docs/features/README.md` to see existing feature specs and where the new spec fits
+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. Glob `./docs/{features,modules/*/features}/**/*.md` and read YAML frontmatter (`owns`, `touches`, `depends_on`) from each to build the ownership map.

package/data/harnesses/code/harness.json

@@ -0,0 +1,6 @@
+{
+  "name": "code",
+  "version": "0.15.2",
+  "epoch": 12,
+  "digest": "911060693b53"
+}

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

@@ -0,0 +1,41 @@
+{
+  "hooks": {
+    "SessionEnd": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/session-stop.js\"",
+            "async": true
+          }
+        ]
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/post-tool-failure.js\"",
+            "async": true
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "if": "Bash(git commit *)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/post-commit.js\"",
+            "async": true
+          }
+        ]
+      }
+    ]
+  }
+}