@nurix/etna 0.13.0 → 0.15.1

package/README.md

@@ -9,24 +9,45 @@ A second install path also exists and is fully supported: `/plugin install <plug
 From the root of the project you want to bootstrap:
 
 ```sh
-npx @nurix/etna nurix-harness
+npx @nurix/etna code
 ```
 
 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 nurix-harness` 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
 
@@ -40,7 +61,7 @@ Listed by `npx @nurix/etna` (no args) using the bundled `data/harness-index.json
 
 | Plugin name | Source in etna | What it ships |
 |---|---|---|
-| `nurix-harness` | [`plugins/nurix-harness.md`](../../plugins/nurix-harness.md) → top-level catalogs | Governance agents, baseline workflow skills, ownership/drift scripts |
+| `code` | [`plugins/code.md`](../../plugins/code.md) → top-level catalogs | Governance agents, baseline workflow skills, ownership/drift scripts |
 | `kb-agi` | [`plugins/kb-agi.md`](../../plugins/kb-agi.md) → top-level catalogs | Knowledge-vault scaffolding |
 
 ## How it works
@@ -53,7 +74,7 @@ The plugin manifest's YAML frontmatter declares which top-level `agents/`, `skil
 
 ```yaml
 ---
-name: nurix-harness
+name: code
 skills: [documentation, introspect, workflow-mapper]
 agents: [spec-mode, maintenance, contract-monitor, …]
 scripts: [build-ownership-index, check-doc-drift]

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/harness-index.json

@@ -1,6 +1,6 @@
 {
     "plugins": {
-        "nurix-harness": "code",
+        "code": "code",
         "kb-agi": "kb-agi"
     }
 }

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.12.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.1
 keywords:
   - harness
   - code
@@ -9,7 +9,7 @@ keywords:
   - documentation
   - boundaries
   - nurix
-plugin: nurix-harness
+plugin: code
 ---
 
 # Agent Instructions
@@ -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 consult `distiller docs` for the just-completed feature's doc — it drafts any pending fact-card 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.
@@ -159,4 +154,3 @@ Maintenance triggers (act on these without re-reading `structure.md`):
 
 - After plan completion: add a `docs/history/changelog/` entry + update `docs/history/CHANGELOG.md` (no confirmation; include `Commits:` if multi-commit). Non-plan changes (refactors, fixes, API changes): prompt first.
 - When you add, move, or delete a doc: update `docs/routing.md` and `docs/README.md` to match. When you move or rename source files: fix the `owns`/`touches` frontmatter in the owning doc; new docs that own code need `owns`/`touches`/`depends_on`.
-- Before creating changelogs, feature docs, or plans: ensure the repo is reconciled (`docs/structure.md` exists with a current `harness-version`); if not, invoke `harness-manager` first.

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

@@ -1,43 +1,36 @@
 ---
 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: [nurix-harness]
+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

@@ -3,7 +3,7 @@ name: change-review
 description: Velocity + change-risk analysis. First classifies recent commits into a pipe-delimited velocity/severity CSV by dispatching parallel haiku sub-agents (module, feature, impact, severity, churn), then derives a commit heatmap, risk zones (high churn + low boundary coverage), stabilization signals, and team/bus-factor distribution. Self-contained — produces its own CSV, no separate git-history step. Use when planning where to invest in better boundaries or rules.
 tools: Bash, Read, Write, Glob, Grep, Task
 model: inherit
-plugins: [nurix-harness]
+plugins: [code]
 ---
 
 # Change-Review Agent
@@ -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

@@ -3,20 +3,20 @@ name: harness-manager
 description: The harness's own migrator and structural-health auditor. Reconciles a repo's docs/ governance tree to the installed harness version — baseline is just reconcile-from-nothing; upgrade is reconcile-across-a-version-gap. Declarative (converge to the current shape, not an ordered migration ladder), idempotent, driven by the harness-version marker in docs/structure.md. Owns the Bootstrap. On demand, audits structural conformance to the harness spec. Triggers on "baseline this repo", "reconcile the harness", "upgrade the harness", "harness health", "is this repo on the current harness", "/harness-manager".
 tools: Read, Glob, Grep, Bash, Write, Edit
 model: inherit
-plugins: [nurix-harness]
+plugins: [code]
 ---
 
 # Harness-Manager Agent
 
 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)
 
-- The **CLI** (`npx @nurix/etna nurix-harness`) refreshes the *engine* — `CLAUDE.md` + `.claude/{agents,skills,rules,scripts}/`. That is not your job; the install does it.
+- The **CLI** (`npx @nurix/etna code`) refreshes the *engine* — `CLAUDE.md` + `.claude/{agents,skills,rules,scripts}/`. That is not your job; the install does it.
 - **You** reconcile the *repo's authored data* — the `docs/` tree — to match that engine.
 
 The upgrade story is the two run back-to-back: install refreshes the engine → you reconcile the docs to it.
@@ -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