@nurix/etna 0.18.11 → 0.18.12

package/README.md

@@ -28,9 +28,9 @@ your-project/
 ├── .vscode/settings.json  ← editor settings (markdown formatter on save)
 └── .claude/
     ├── skills/            ← documentation, boundary, distiller, brainstorm, workflow-mapper
-    ├── agents/            ← harness-manager, spec-mode, brainstorm, maintenance, change-review, performance-review
+    ├── agents/            ← 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)
+    ├── hooks/             ← generate-ownership-index (SessionStart), session-reflect (SessionEnd), prompt-recall (UserPromptSubmit) + lib/redact
     ├── settings.json      ← the hooks are deep-merged in here (your existing keys preserved)
     └── harness.json       ← {version, digest} — the installed-harness sentinel
 ```
@@ -43,20 +43,19 @@ Re-run `npx @nurix/etna --name=code` anytime to refresh the harness content with
 
 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.
+1. **"baseline this repo"** (or "reconcile the harness") — runs the **`maintenance`** agent, which auto-selects **baseline mode** from the missing/behind `harness-version`. It builds the `docs/` tree to the harness shape, stamps `docs/structure.md` with the installed `harness-version`, proposes **modules** (as `module:` labels, derived from your code's bounded contexts), then hands back.
+2. If it hands back with a follow-up (typically the module proposal), re-invoke it to finish.
 
-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.
+Then work normally. Boundaries aren't generated as files — the `boundary` skill diagnoses cross-cutting contracts from source at plan time. 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.
+- **Memory capture starts on your next session.** The `session-reflect` hook (SessionEnd) distils each session's lessons into the per-actor inbox `docs/memory/inbox/`; once enough entries accrue, the `maintenance` agent _proposes_ a `distiller` run that distils them into provenance-linked fact-cards under `docs/memory/facts/` 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.
+If the [`qmd`](https://www.npmjs.com/package/@tobilu/qmd) binary is on your `PATH`, the `maintenance` agent (baseline mode) registers per-subtree search collections so the distiller and the doc anchors get semantic retrieval. It's strictly optional — absent, discovery rides the generated ownership index + `keywords:` frontmatter and everything still works on a filename/grep fallback. Install it whenever.
 
 ## Migrating from 0.1.x
 
@@ -90,7 +89,7 @@ Two kinds of membership:
 name: code
 skills: [boundary, brainstorm, distiller, documentation, workflow-mapper]
 rules: [general, nomenclature, typescript]
-agents: [brainstorm, change-review, harness-manager, maintenance, performance-review, spec-mode]
+agents: [brainstorm, change-review, maintenance, performance-review, spec-mode]
 ---
 ```
 

package/bin/etna.js

@@ -5,6 +5,10 @@
 // prompts you to pick one. Drops the harness's CLAUDE.md + project-root config
 // files (.prettierrc.json, .vscode/settings.json, …) at the project root, and
 // copies its skills, agents, rules, scripts, and hooks into <project>/.claude/.
+// Agents — the brainstorm facilitator plus the generic governance agents
+// (spec-mode, maintenance, change-review, performance-review) —
+// are vendored per-project into <project>/.claude/agents/, the same lifecycle as
+// skills and rules. The CLI writes only inside the target folder; nothing global.
 // No marketplace, no plugin enablement — files live in the project,
 // version-controlled and editable per project. Re-run `etna` to refresh.
 // Harnesses are addressed by their harness/<folder> name; several harnesses may
@@ -181,6 +185,51 @@ function retireOldHooks(targetDir) {
     return removed;
 }
 
+// Component subdirs whose membership is tracked so a removed-from-the-harness component
+// can be pruned on refresh. Hooks are excluded — retireOldHooks owns them (it must also
+// prune the matching settings.json entry, which a name-only diff can't reach).
+const PRUNABLE_SUBDIRS = ['skills', 'agents', 'rules', 'scripts'];
+
+// The set of component names the bundle ships, per prunable subdir — the manifest of what
+// THIS harness owns. Written into the installed harness.json so the next refresh can diff.
+function bundledOwned(bundledHarnessDir) {
+    const owned = {};
+    for (const sub of PRUNABLE_SUBDIRS) {
+        const dir = join(bundledHarnessDir, sub);
+        owned[sub] = existsSync(dir) ? readdirSync(dir).sort() : [];
+    }
+    return owned;
+}
+
+// Read the `owned` manifest the PREVIOUS install recorded in the project's harness.json.
+// Absent (first install, or pre-pruning version) ⇒ {} ⇒ nothing is pruned this round.
+function readInstalledOwned(targetDir) {
+    const path = join(targetDir, '.claude', 'harness.json');
+    if (!existsSync(path)) return {};
+    const owned = readJson(path).owned;
+    return owned && typeof owned === 'object' ? owned : {};
+}
+
+// Remove vendored components a prior harness version owned but this one no longer ships
+// (e.g. a retired agent like harness-manager). Only names present in the PRIOR `owned`
+// manifest are eligible, so a project's own components — never in that manifest — survive.
+function pruneOrphanedComponents(targetDir, priorOwned, newOwned) {
+    const removed = [];
+    for (const sub of PRUNABLE_SUBDIRS) {
+        const had = priorOwned[sub] || [];
+        const has = new Set(newOwned[sub] || []);
+        for (const name of had) {
+            if (has.has(name)) continue;
+            const target = join(targetDir, '.claude', sub, name);
+            if (existsSync(target)) {
+                rmSync(target, { recursive: true, force: true });
+                removed.push(`orphaned ${sub.replace(/s$/, '')} ${name}`);
+            }
+        }
+    }
+    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);
@@ -300,16 +349,28 @@ async function installHarness(harnessName, harnesses) {
     cpSync(bundledClaudeMd, claudeMdDest, { force: true });
     installed.push('CLAUDE.md → ./');
 
+    // What a prior install recorded as harness-owned — read before we overwrite the marker,
+    // so we can prune anything this bundle has since dropped.
+    const priorOwned = readInstalledOwned(targetDir);
+
     for (const sub of PLUGIN_SUBDIRS) {
         const count = copyHarnessSubdir(join(bundledHarnessDir, sub), join(targetDir, '.claude', sub));
         if (count > 0) installed.push(`${count} ${sub} → .claude/${sub}/`);
     }
 
-    // Copy the harness marker so harness-manager can resolve the installed version.
+    // Prune components a prior harness version owned but this bundle no longer ships (e.g. a
+    // retired agent). Only prior-owned names are eligible, so the user's own files survive.
+    const newOwned = bundledOwned(bundledHarnessDir);
+    for (const r of pruneOrphanedComponents(targetDir, priorOwned, newOwned)) notices.push(`removed ${r}`);
+
+    // Write the harness marker — plus the `owned` manifest the next refresh diffs against —
+    // so the maintenance agent (baseline mode) can resolve the installed version.
     if (existsSync(bundledHarnessJson)) {
         const harnessJsonDest = join(targetDir, '.claude', 'harness.json');
         mkdirSync(dirname(harnessJsonDest), { recursive: true });
-        cpSync(bundledHarnessJson, harnessJsonDest, { force: true });
+        const marker = readJson(bundledHarnessJson);
+        marker.owned = newOwned;
+        writeJson(harnessJsonDest, marker);
     }
 
     // Verbatim project-root files bundled outside the plugin route (.prettierrc.json,

package/data/harness-index.json

@@ -1,5 +1,5 @@
 {
-    "fingerprint": "e369db06df16",
+    "fingerprint": "acbb6d687e95",
     "harnesses": {
         "code": {
             "plugin": "code",

package/data/harnesses/code/CLAUDE.md

@@ -6,9 +6,9 @@ This file defines how AI agents (Claude, GPT, etc.) should work on this project.
 
 ## Bootstrap
 
-> A missing `docs/structure.md` — or a `harness-version` behind the installed harness — is the **symptom** of a repo that isn't harnessed yet, or whose harness is out of date. Don't reconcile it by hand. Drive the **reconcile chain** — you (the main session) own it, because `harness-manager` is a sub-agent that can't run skills or spawn sub-agents:
+> A missing `docs/structure.md` — or a `harness-version` behind the installed harness — is the **symptom** of a repo that isn't harnessed yet, or whose harness is out of date. Don't reconcile it by hand. Drive the **reconcile chain** — you (the main session) own it, because `maintenance` is a sub-agent that can't run skills or spawn sub-agents:
 >
-> 1. Invoke **`harness-manager`** (`"baseline this repo"` / `"reconcile the harness"`). It reconciles `docs/`, stamps the version, then hands back.
+> 1. Invoke **`maintenance`** (`"baseline this repo"` / `"reconcile the harness"`). It auto-selects **baseline mode** from the missing/behind `harness-version`, reconciles `docs/`, stamps the version, then hands back.
 > 2. If it hands back with a follow-up (typically the module proposal), re-invoke it to finish.
 >
 > Then continue. Each component's internals live in the component, not here.
@@ -36,7 +36,7 @@ Three peer modes plus a Completion step — enter wherever the user's thinking a
 | **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; then distil the plan's trail — if the memory inbox (`docs/memory/inbox/`) holds entries, run `distiller facts` (inbox→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 gates every approved plan before coding — it reads the source the plan touches and reports what would break (see **Boundaries** below); on brainstorm close, harvest by scope — module pillars → `docs/modules/{m}/pillars/`, cross-module doctrine + contract changes (the deployed-design SOT) → `docs/architecture/` with its decision record → `docs/history/adr/`, backlog → `docs/history/`. Open questions block close.
+On **Completion**: freeze the plan (`Status: Complete`) and flip the feature spec to `status: active`, extending it with how-it-works sections and confirming its `owns:` globs against the actual code; then distil the plan's trail — if the memory inbox (`docs/memory/inbox/`) holds entries, run `distiller facts` (inbox→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 gates every approved plan before coding — it reads the source the plan touches and reports what would break (see **Boundaries** below); a brainstorm session is written to a **kept** record at `docs/brainstorm/{topic}/` (committed, one subfolder per topic), and on close harvest distils its conclusions by scope — doctrine, glossary, non-goals, and information-architecture changes → `docs/architecture/`, decisions → `docs/architecture/adr/`, backlog → `docs/history/backlog.md` — leaving the `docs/brainstorm/{topic}/` record in place as the provenance. Open questions block close.
 
 ---
 
@@ -44,11 +44,10 @@ On **Completion**: freeze the plan (`Status: Complete`) and flip the feature spe
 
 Before modifying code in an unfamiliar area:
 
-1. Read **[`docs/routing.md`](docs/routing.md)** — the single map of file-pattern/keyword → canonical doc + module. Match your path or topic to find the owning feature doc and its module; read that doc — and, if its row names a declared module, that module's `CLAUDE.md` + `pillars/` — before changes. (If `routing.md` doesn't exist yet, the repo isn't reconciled — see Bootstrap.)
-2. 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.
+1. Consult the **injected ownership index** — the generated `glob → doc · module · keywords · status` map, surfaced into context at session start (the union of every feature doc's `owns:` frontmatter). Match your path or topic (its `keywords:`) to the owning feature doc and read it before changes. (If no ownership index appears in context, the repo isn't reconciled — see Bootstrap.)
+2. If `qmd` is installed, run `qmd query --format json -c <collection> "<topic>"` (repeat `-c` to span this repo's collections; `qmd collection list` names them) for semantic recall over the indexed docs — prefer it when entering an unfamiliar area; absent ⇒ skip.
 3. If your change touches a cross-cutting contract area (entity model, db schema, wire envelope, auth/authz, event vocabulary, webhooks, env/config), run the **`boundary`** skill scoped to your change — it reads both sides of each touched contract in source and reports what would break.
-4. If a `docs/memory/` file exists for the domain you're working in, read it for domain knowledge and failure modes
-5. 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 1.
+4. If a `docs/memory/` file exists for the domain you're working in, read it for domain knowledge and failure modes.
 
 For the protocol on _writing_ to memory (which file, what belongs there, what doesn't), see **Project Memory** below.
 
@@ -82,9 +81,9 @@ When implementing a plan, if you discover work that is important but outside the
 
 ## Doc Ownership
 
-Which doc is canonical for which code paths — and which module each path belongs to — is recorded in **[`docs/routing.md`](docs/routing.md)** (File-Pattern Routes), the single hand-maintained map. Feature docs (in `docs/modules/{m}/features/`, or flat `docs/features/` if the module isn't declared) carry **no** ownership frontmatter; their code paths are their routing row(s). A module is tied to code by its routing patterns (the Module column), not by aggregated globs. Architecture docs describe cross-cutting patterns and don't own specific files; operations docs describe procedures. The only frontmatter a living doc may carry is an optional `anchors:` block (a qmd drift tripwire, not ownership).
+Which doc is canonical for which code paths is the **feature doc's own frontmatter**. A feature doc (flat in `docs/features/`) carries `owns:` (code-path globs — the only ownership key), `module:` (a bounded-context label, omitted when cross-cutting), `keywords:` (discovery), and `status:`. Code → doc ownership is the union of every feature doc's `owns:` globs, surfaced as the generated ownership index at session start. A module is tied to code by the `owns:` globs of the docs carrying its `module:` label — not a folder, not a separate map. Architecture docs describe cross-cutting patterns and don't own specific files; operations docs describe procedures. A living doc may additionally carry an optional `anchors:` block (a qmd drift tripwire, not ownership).
 
-The spec-mode agent checks `routing.md` for ownership conflicts during research (overlapping patterns). If conflicts are found, address them in the spec before proceeding.
+The spec-mode agent checks for ownership conflicts during research — feature docs whose `owns:` globs overlap at equal specificity. If conflicts are found, address them in the spec before proceeding.
 
 ---
 
@@ -120,4 +119,4 @@ Unless explicitly requested:
 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` to match. When you move or rename source files: update the matching File-Pattern Route(s) in `docs/routing.md`; a new doc that owns code gets its row(s) there (no frontmatter).
+- When you move or rename source files: update the `owns:` globs of the feature doc that owns them so the generated ownership index stays accurate. A new doc that owns code declares its paths in its own `owns:` frontmatter — there is no separate map to update.

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

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

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

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