@nurix/etna 0.17.1 → 0.18.1

package/README.md

@@ -6,17 +6,26 @@ A second install path also exists and is fully supported: `/plugin install <plug
 
 ## Usage
 
-From the root of the project you want to bootstrap:
+From the root of the project you want to bootstrap, pick a harness from the interactive menu:
 
 ```sh
-npx @nurix/etna code
+npx @nurix/etna
+```
+
+…or install one directly by name:
+
+```sh
+npx @nurix/etna --name=code
 ```
 
 After this completes:
 
 ```
 your-project/
-├── CLAUDE.md              ← harness policy (your existing file → CLAUDE.md.bak.<ISO>)
+├── CLAUDE.md              ← harness policy (non-git repo: existing file → CLAUDE.md.bak.<ISO>)
+├── .prettierrc.json       ← markdown formatting (proseWrap: never)
+├── .prettierignore
+├── .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
@@ -28,22 +37,22 @@ your-project/
 
 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>`. 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.
+Re-run `npx @nurix/etna --name=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. In a git repo the previous `CLAUDE.md` is overwritten in place (recover it with `git checkout CLAUDE.md`); outside a git repo it's 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):
+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.
+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.
+- **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)
 
@@ -60,13 +69,14 @@ The `nurixlabs` marketplace entry in `~/.claude/settings.json` is harmless to le
 Listed by `npx @nurix/etna` (no args) using the bundled `data/harness-index.json`.
 
 | Plugin name | Source in etna | What it ships |
-|---|---|---|
+| --- | --- | --- |
 | `code` | [`plugins/code/`](../../plugins/code/) | Governance + session agents, baseline workflow skills, knowledge-ledger hooks |
 | `kb-agi` | [`plugins/kb-agi/`](../../plugins/kb-agi/) | Knowledge-vault scaffolding |
 
 ## How it works
 
 Each harness has two halves in the etna repo:
+
 - `plugins/<name>/` — the **plugin** (what a Claude Code plugin natively bundles): `definition.md` (manifest — identity + `skills:`/`rules:` lists), `agents/`, `hooks/`.
 - `harness/<name>/` — the **policy**: `CLAUDE.md` (pure policy, no frontmatter — installed as a verbatim copy) plus `index.md`, whose `plugin:` key names the plugin this harness pairs with. All harness-folder frontmatter lives in `index.md` alone.
 
@@ -79,7 +89,7 @@ Two kinds of membership:
 ---
 name: code
 skills: [boundary, brainstorm, distiller, documentation, workflow-mapper]
-rules:  [general, nomenclature]
+rules: [general, nomenclature]
 ---
 ```
 

package/bin/etna.js

@@ -43,15 +43,16 @@ function isInteractive() {
     return Boolean(process.stdin.isTTY && process.stdout.isTTY);
 }
 
-// Boxed list of installable harnesses, for --help and the non-interactive no-arg path.
+// Boxed list of installable harnesses (name + description), for --help and error paths.
 function printHarnessList(harnesses) {
     const entries = Object.entries(harnesses);
     if (!entries.length) {
         p.log.warn('No harnesses are bundled. Run `npm run build:data` from the package root.');
         return;
     }
+    const width = Math.max(...entries.map(([folder]) => folder.length));
     const lines = entries.map(
-        ([folder, plugin]) => `${folder}${plugin && plugin !== folder ? `  (plugin: ${plugin})` : ''}`,
+        ([folder, meta]) => `${folder.padEnd(width)}${meta?.description ? `  ${meta.description}` : ''}`,
     );
     p.note(lines.join('\n'), 'Available harnesses');
 }
@@ -216,35 +217,32 @@ function mergeHooks(targetDir, bundledHooksJson) {
     return added;
 }
 
-// Resolve the harness to install: the positional arg, or — in a TTY — an interactive
-// pick. Returns the chosen folder name, or null if the user cancels / can't be prompted.
-async function resolveHarnessName(positional, harnesses) {
+// Resolve the harness to install: the --name value, or — in a TTY — an interactive pick
+// showing each harness's description. Returns the chosen folder, or null on cancel.
+async function resolveHarnessName(name, harnesses) {
     const names = Object.keys(harnesses);
-    if (positional) {
-        if (!harnesses[positional]) {
-            p.log.error(`Unknown harness '${positional}'.`);
+    if (name !== null) {
+        if (!name || !harnesses[name]) {
+            p.log.error(name ? `Unknown harness '${name}'.` : 'Empty --name value.');
             printHarnessList(harnesses);
-            p.outro('Pick one of the harnesses above.');
+            p.outro('Pass --name=<harness> with one of the names above.');
             process.exit(1);
         }
-        return positional;
+        return name;
     }
     if (!isInteractive()) {
-        p.log.error('No harness specified, and not running in an interactive terminal.');
+        p.log.error('No --name given, and not running in an interactive terminal.');
         printHarnessList(harnesses);
-        p.outro('Re-run as `npx @nurix/etna <harness-name>`.');
+        p.outro('Re-run as `npx @nurix/etna --name=<harness>`.');
         process.exit(1);
     }
     const choice = await p.select({
         message: 'Which harness do you want to install here?',
-        options: names.map((folder) => {
-            const plugin = harnesses[folder];
-            return {
-                value: folder,
-                label: folder,
-                hint: plugin && plugin !== folder ? `plugin: ${plugin}` : undefined,
-            };
-        }),
+        options: names.map((folder) => ({
+            value: folder,
+            label: folder,
+            hint: harnesses[folder]?.description || undefined,
+        })),
     });
     if (p.isCancel(choice)) {
         p.cancel('Cancelled — nothing installed.');
@@ -273,7 +271,7 @@ async function installHarness(harnessName, harnesses) {
     const versionTag = harnessMeta.version ? ` v${harnessMeta.version}` : '';
     // The underlying plugin's name — may differ from the harness name, and several
     // harnesses may share it. Used only for legacy marketplace-entry cleanup.
-    const pluginName = harnessMeta.name || harnesses[harnessName] || harnessName;
+    const pluginName = harnessMeta.name || harnesses[harnessName]?.plugin || harnessName;
 
     const spin = p.spinner();
     spin.start(`Installing ${harnessName}${versionTag} into ${targetDir}`);
@@ -346,32 +344,62 @@ async function installHarness(harnessName, harnesses) {
 
     p.outro(
         `${harnessName}${versionTag} ready in ${targetDir}. ` +
-            `Re-run \`npx @nurix/etna ${harnessName}\` anytime to refresh harness content.`,
+            `Re-run \`npx @nurix/etna --name=${harnessName}\` anytime to refresh harness content.`,
     );
 }
 
+// Parse argv. `--name=<harness>` / `--name <harness>` selects a harness; -h/--help shows
+// help; any other bare token is the dropped positional form (a breaking change in 0.18.0).
+function parseArgs(args) {
+    let name = null;
+    let help = false;
+    let positional = null;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '-h' || a === '--help') help = true;
+        else if (a.startsWith('--name=')) name = a.slice('--name='.length);
+        else if (a === '--name') name = args[++i] ?? '';
+        else if (!a.startsWith('-') && positional === null) positional = a;
+    }
+    return { name, help, positional };
+}
+
 async function main(args) {
     const idx = loadHarnessIndex();
     const harnesses = idx.harnesses || {};
+    const { name, help, positional } = parseArgs(args);
 
-    if (args.includes('-h') || args.includes('--help')) {
+    if (help) {
         p.intro('@nurix/etna — Nurix harness installer');
-        p.log.message('Usage: npx @nurix/etna [harness-name]');
+        p.log.message(
+            'Usage:\n' +
+                '  npx @nurix/etna                   pick a harness from the menu\n' +
+                '  npx @nurix/etna --name=<harness>  install that harness directly',
+        );
         printHarnessList(harnesses);
-        p.outro('Run with a name to install, or with no name to pick interactively.');
+        p.outro('No args → interactive menu. --name=<harness> → direct install.');
         return;
     }
 
-    const positional = args.find((a) => !a.startsWith('-'));
-
     p.intro('@nurix/etna — Nurix harness installer');
 
+    // Breaking change (0.18.0): the positional form `etna <harness>` was replaced by
+    // `--name=<harness>`. Fail loudly with the new syntax rather than silently misfiring.
+    if (positional && name === null) {
+        p.log.error(
+            `Positional arguments are no longer supported. Install with \`npx @nurix/etna --name=${positional}\`.`,
+        );
+        printHarnessList(harnesses);
+        p.outro('Use --name=<harness> to install, or no args to pick from the menu.');
+        process.exit(1);
+    }
+
     const boot = p.spinner();
     boot.start('Starting up');
     await sleep(2000);
     boot.stop('Ready');
 
-    const harnessName = await resolveHarnessName(positional, harnesses);
+    const harnessName = await resolveHarnessName(name, harnesses);
     if (!harnessName) return; // user cancelled the interactive pick
 
     await installHarness(harnessName, harnesses);

package/data/harness-index.json

@@ -1,10 +1,25 @@
 {
-    "fingerprint": "50dc8734b7ee",
+    "fingerprint": "5749d4f02de6",
     "harnesses": {
-        "code": "code-fable",
-        "code-fable": "code-fable",
-        "discover": "discover",
-        "hr": "hr",
-        "kb-agi": "kb-agi"
+        "code": {
+            "plugin": "code-fable",
+            "description": "Nurix code-project harness"
+        },
+        "code-fable": {
+            "plugin": "code-fable",
+            "description": "Nurix code-project harness"
+        },
+        "discover": {
+            "plugin": "discover",
+            "description": "Product Discovery harness"
+        },
+        "hr": {
+            "plugin": "hr",
+            "description": "Hiring / AI-Steering Evaluation harness"
+        },
+        "kb-agi": {
+            "plugin": "kb-agi",
+            "description": "self-improving knowledge-base harness"
+        }
     }
 }

package/data/harnesses/code/CLAUDE.md

@@ -31,7 +31,7 @@ This is the only step that runs **before** the harness exists; everything below
 Three peer modes plus a Completion step — enter wherever the user's thinking already is. Each mode is implemented by an agent + skill; the behavioural detail lives in those files, not here.
 
 | Mode | Enter when | Implemented by | Exits to |
-|------|-----------|----------------|----------|
+| --- | --- | --- | --- |
 | **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 |
@@ -51,7 +51,7 @@ Before modifying code in an unfamiliar area:
 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.
+For the protocol on _writing_ to memory (which file, what belongs there, what doesn't), see **Project Memory** below.
 
 ---
 
@@ -60,12 +60,12 @@ For the protocol on *writing* to memory (which file, what belongs there, what do
 Project-specific learnings live in `docs/memory/` (git-tracked). Cross-project user preferences live in `~/.claude/` (untracked).
 
 | File | Owner | Contents |
-|------|-------|----------|
+| --- | --- | --- |
 | `docs/memory/main.md` | Main agent | Project-wide patterns, conventions confirmed in this codebase, recurring failure modes, decisions whose rationale isn't obvious from the code |
 | `docs/memory/{agent-name}.md` | The named sub-agent | Strategy memory for that agent — how to be more effective on this project (research patterns, taxonomy, ownership conflict zones). Never user-centric. |
 | `~/.claude/projects/...` | Auto-memory system | User preferences, role, communication style, cross-project habits |
 
-**Override the default auto-memory location for project-relevant facts.** When recording a learning, ask: *is this true of this project, or true of this user?* Project facts → `docs/memory/`. User facts → `~/.claude/`.
+**Override the default auto-memory location for project-relevant facts.** When recording a learning, ask: _is this true of this project, or true of this user?_ Project facts → `docs/memory/`. User facts → `~/.claude/`.
 
 `docs/memory/main.md` is created on first write. Append entries dated `## YYYY-MM-DD — {topic}`; oldest at bottom is fine.
 
@@ -103,25 +103,14 @@ A boundary is a horizontal cross-cutting contract — entity model, db schema, w
 
 Unless explicitly requested:
 
-❌ **Tests** – Never generate, update, or modify test files.
-❌ **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** – 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. **Main session only:** never drive the browser from a sub-agent or workflow executor — the session-bound Chrome connection destabilizes the sub-agent. A sub-agent that needs browser verification instead returns an explicit CDP checklist (exact URLs, actions, expected outcomes) for the orchestrator to execute in the main session.
-✅ **Orchestrate via Sub-agents** – Run the main session as an orchestrator: delegate substantive work (research, implementation, audits) to sub-agents spawned via the Agent/Task tool with `model: opus` (Claude Opus), keeping the main context for dispatch, coordination, and synthesis. Give each sub-agent a self-contained prompt; parallelize independent dispatches.
-✅ **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.
-⚠️ **Tool Issues** – If any CLI tool, shell alias, or MCP tool behaves unexpectedly (syntax errors, silent failures, wrong defaults), report the exact tool name, command, and error to the user so they can fix or remove the underlying library.
+❌ **Tests** – Never generate, update, or modify test files. ❌ **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** – 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. **Main session only:** never drive the browser from a sub-agent or workflow executor — the session-bound Chrome connection destabilizes the sub-agent. A sub-agent that needs browser verification instead returns an explicit CDP checklist (exact URLs, actions, expected outcomes) for the orchestrator to execute in the main session. ✅ **Orchestrate via Sub-agents** – Run the main session as an orchestrator: delegate substantive work (research, implementation, audits) to sub-agents spawned via the Agent/Task tool with `model: opus` (Claude Opus), keeping the main context for dispatch, coordination, and synthesis. Give each sub-agent a self-contained prompt; parallelize independent dispatches. ✅ **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. ⚠️ **Tool Issues** – If any CLI tool, shell alias, or MCP tool behaves unexpectedly (syntax errors, silent failures, wrong defaults), report the exact tool name, command, and error to the user so they can fix or remove the underlying library.
 
 ---
 
 ## File Structure
 
-- Add file path at top of each file:
-  `// src/modules/example.js - Module for handling user authentication`
-- Add a 1-line function description as a comment above each function:
-  `// Extract JWT token from request based on endpoint type`
+- Add file path at top of each file: `// src/modules/example.js - Module for handling user authentication`
+- Add a 1-line function description as a comment above each function: `// Extract JWT token from request based on endpoint type`
 
 ---
 

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

@@ -20,15 +20,15 @@ If none of those steering files exist yet (a freshly-baselined repo), a session
 
 ## Modes and the close gate
 
-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.
+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.
+- **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.
 - **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 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
 

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

@@ -18,14 +18,14 @@ You work in two phases:
 
 Parse these from the user's prompt. Use defaults if not specified.
 
-| Parameter     | Default                                        | Examples                                          |
-| ------------- | ---------------------------------------------- | ------------------------------------------------- |
-| `since`       | `3 months ago`                                 | "last 2 weeks", "since Feb 1", "since 2025-01-01" |
-| `until`       | `now`                                          | "until Feb 10"                                    |
-| `batch_size`  | `8`                                            | "batches of 10"                                   |
-| `output`      | `change-review-YYYY-MM-DD.csv` (today's date)  | "write to review.csv"                             |
-| `skip_merges` | `true`                                         | "include merges"                                  |
-| `branch`      | current branch                                 | "on main", "on ai-staging"                        |
+| Parameter | Default | Examples |
+| --- | --- | --- |
+| `since` | `3 months ago` | "last 2 weeks", "since Feb 1", "since 2025-01-01" |
+| `until` | `now` | "until Feb 10" |
+| `batch_size` | `8` | "batches of 10" |
+| `output` | `change-review-YYYY-MM-DD.csv` (today's date) | "write to review.csv" |
+| `skip_merges` | `true` | "include merges" |
+| `branch` | current branch | "on main", "on ai-staging" |
 
 The heatmap needs rolling 1w / 1m / 3m windows, so default `since` to 3 months even though the classifier processes every commit in range.
 
@@ -66,6 +66,7 @@ git diff-tree --no-commit-id --numstat -r {hash}
 ```
 
 Run these in a single bash call using a loop for efficiency. From the numstat output, compute per-commit totals:
+
 - `files_changed`: number of files in the commit
 - `insertions`: sum of added lines across all files
 - `deletions`: sum of removed lines across all files
@@ -86,11 +87,13 @@ Spawn **haiku** sub-agents via the Task tool with `subagent_type: "general-purpo
 Before building the prompt template, check if `docs/memory/change-review.md` contains **Module Taxonomy** and **Feature Taxonomy** sections. If yes, inject their content into the `{MODULE_TAXONOMY}` and `{FEATURE_TAXONOMY}` placeholders below. If no memory file exists, use these generic fallbacks:
 
 **Generic Module Taxonomy fallback:**
+
 ```
 Classify by the PRIMARY directory of changed files. Use the top-level directory as the module category (e.g., `src/components/` → `frontend/components`, `app/api/` → `backend/api`). For files spanning 3+ categories, use `multi`.
 ```
 
 **Generic Feature Taxonomy fallback:**
+
 ```
 Infer the product area from the commit message and file paths. Use descriptive labels like `auth`, `editor`, `deploy`, `ui`, `infra`, `docs`, `dx`, `other`.
 ```
@@ -182,7 +185,7 @@ When a commit cannot be classified by a sub-agent, use these defaults:
 
 # Phase 2 — Velocity analysis
 
-Where Phase 1 classifies *what* changed, Phase 2 asks *where is change accelerating or decelerating* — and whether review attention matches the risk. Read the CSV from Phase 1 (or the recent one found in Before Starting).
+Where Phase 1 classifies _what_ changed, Phase 2 asks _where is change accelerating or decelerating_ — and whether review attention matches the risk. Read the CSV from Phase 1 (or the recent one found in Before Starting).
 
 ## Step 6: Velocity Heatmap
 
@@ -195,7 +198,7 @@ Compute commits-per-directory over rolling windows:
 Aggregate by the top-level directories the CSV's `directories` field already carries (computed generically in Phase 1, Step 2). Report:
 
 | Directory | Commits 1w | Commits 1m | Commits 3m | Trend |
-|-----------|-----------:|-----------:|-----------:|-------|
+| --------- | ---------: | ---------: | ---------: | ----- |
 
 Trend column: ↑ rising, ↓ falling, → steady, ↑↑ sharply rising, ↓↓ sharply falling.
 

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

@@ -9,14 +9,14 @@ model: inherit
 
 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, …); 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 — "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.)
+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 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 **CLI** (`npx @nurix/etna --name=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.
 
@@ -29,15 +29,15 @@ The upgrade story is the two run back-to-back: install refreshes the engine →
 
 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). 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 code's bounded contexts imply them).
+- **`maintenance` audits docs-vs-code _fidelity_** — is the documented behavior _true_ of the code? (stale docs, broken `owns` globs, routing drift). 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 code's bounded contexts imply them).
 
-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.
+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. 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.
+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 --name=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 for the Step 6 module proposal: the version is already current from your first pass, so skip the stop and go straight to Step 6. (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.
 
@@ -82,7 +82,7 @@ While reading each markdown doc to classify it, if the doc names a code symbol i
 This is what makes reconcile more than a fresh scaffold. Detect old-shape artifacts and fold them forward:
 
 | If you find (old shape) | Fold to (current shape) |
-|---|---|
+| --- | --- |
 | `docs/operations/guardrails.md` | fold durable contract notes into `docs/architecture/` |
 | `docs/boundaries/` (legacy persisted boundaries) | delete — boundary analysis is a plan-time diagnostic (the `boundary` skill reads contracts fresh from source); fold any human-authored knowledge (external consumers, intent, accepted exceptions) into `docs/architecture/` |
 | repo-wide `docs/pillars/` | module-local `docs/modules/{m}/pillars/`; cross-module doctrine → `docs/architecture/` |
@@ -110,7 +110,7 @@ Write `harness-version: <installed epoch>` into `docs/structure.md` frontmatter.
 
 ### 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).
+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 consumable inbox queue at `docs/memory/inbox/` into the index. The inbox is **not** in scope (it is distilled into `memory/facts`, which is — and its entries are deleted on digestion, which would leave dangling index entries). Register one collection **per indexable subtree** instead — never `docs/memory` as a whole, only `docs/memory/facts` — so the inbox is excluded by construction:
 
@@ -130,12 +130,12 @@ This augments routing; it never supersedes the Step 6 ownership resolution.
 
 ### Step 6 — Module proposal
 
-Modules are *declared*, never inferred from physical layout. Derive the repo's candidate bounded contexts directly from the code and docs: distinct wire surfaces (who owns routes/handlers), schema/data-access ownership, entry points and process units, plus any contexts `docs/architecture/` or feature `owns` globs already name.
+Modules are _declared_, never inferred from physical layout. Derive the repo's candidate bounded contexts directly from the code and docs: distinct wire surfaces (who owns routes/handlers), schema/data-access ownership, entry points and process units, plus any contexts `docs/architecture/` or feature `owns` globs already name.
 
 - Propose the derived contexts as candidate modules. For each, partition existing flat feature docs by `owns`-glob overlap.
 - **Propose — don't force.** Declaration is opt-in: a single-context app stays flat (so does a monolith whose contexts all share one kernel); declare `docs/modules/{m}/` only when the author accepts a context as a module. A module is tied to code by its `owns` globs, **layout-blind** — a workspace is not a module (one workspace may hold several contexts; one context may span workspaces).
 
-If Step 5b skipped because `qmd` was absent, carry its one advisory line into the hand-back — *"qmd not installed — semantic retrieval unavailable; glob routing active."* — advisory, never an error, never a gate.
+If Step 5b skipped because `qmd` was absent, carry its one advisory line into the hand-back — _"qmd not installed — semantic retrieval unavailable; glob routing active."_ — advisory, never an error, never a gate.
 
 Re-running you is safe — the structure work is already done (idempotent), so a second pass is just the module proposal.
 
@@ -143,7 +143,7 @@ Re-running you is safe — the structure work is already done (idempotent), so a
 
 > - `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).
+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.
 
@@ -157,9 +157,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. (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.
+- **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 --name=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`, a persisted `docs/boundaries/` tree, or other old-shape artifact lingering.
 - **Module declaration coverage** — do the repo's bounded contexts have declared module homes where the author intended them? (Surface gaps; never auto-declare.)

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

@@ -10,6 +10,7 @@ model: inherit
 You maintain codebase coherence by detecting drift between docs and code, and fixing it. Scope: stale feature docs, broken ownership, routing table drift, architecture drift, unowned source paths, backlog health.
 
 Out of scope (handled by the `boundary` skill, which derives contracts dynamically from source):
+
 - **Pre-implementation impact analysis** (checking a plan against cross-cutting contracts before coding) → `boundary` skill, `check` mode
 - **Diff-scoped contract analysis** (what could a change break across module edges) → `boundary` skill, `scan` mode
 
@@ -30,15 +31,18 @@ Out of scope (handled by the `boundary` skill, which derives contracts dynamical
 ## 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 check the **env contract** when the repo declares a canonical `.env.example` (or equivalent). The named-referent check above covers code symbols and paths but not env vars, which live in a separate canonical file:
+
 - Extract the `UPPER_SNAKE` env keys the code reads (`process.env.X` and the deploy scripts' generated env). Grep each against the canonical `.env.example`.
 - Raise any absence as a question (e.g. `server reads MASTER_KEK but no MASTER_KEK appears in .env.example — confirm the contract still holds`). Skip when no canonical file exists.
 
@@ -47,6 +51,7 @@ Also check the **env contract** when the repo declares a canonical `.env.example
 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 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)
@@ -61,7 +66,7 @@ If `./docs/routing.md` exists:
 
 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`).
+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
 
@@ -74,10 +79,12 @@ Also catch a **stale greenfield self-label.** If `routing.md` (or `structure.md`
 ## Step 6: Remediate
 
 For each stale doc:
+
 - If drift is clear (renamed function, new export, changed props) → update the doc directly
 - If drift is ambiguous (major refactor, unclear intent) → backlog it
 
 For unowned code paths:
+
 - 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.)
@@ -87,8 +94,8 @@ For unowned code paths:
 1. Update `docs/structure.md` Health Log with today's date and summary
 2. Update `docs/memory/maintenance.md` with last review date, stale docs fixed, unowned paths, backlog items created
 3. Report findings: stale docs, broken ownership, unowned code, architecture drift, backlog health
-4. **Inbox-distillation threshold.** Count undigested inbox entries — `## ` entry blocks across `docs/memory/inbox/*.md` (the inbox is consume-on-digest, so every block present is undigested). If the count is **≥5**, add one line to the report **proposing** a `distiller` `facts` run — propose only, never auto-run, no cron. If the user declines or ignores it, do nothing: the count keeps growing and the proposal reappears next pass — that recurrence *is* the dedupe, so never backlog it.
-5. **Docs-distillation threshold.** Per target doc, count undigested fact-cards (`invalid_from: null`, the doc's path not in their `digested_into:`) that **touch** it by the structural intersection in `skills/distiller/references/docs-mode.md` Resolution 1 (provenance∩`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.
+4. **Inbox-distillation threshold.** Count undigested inbox entries — `## ` entry blocks across `docs/memory/inbox/*.md` (the inbox is consume-on-digest, so every block present is undigested). If the count is **≥5**, add one line to the report **proposing** a `distiller` `facts` run — propose only, never auto-run, no cron. If the user declines or ignores it, do nothing: the count keeps growing and the proposal reappears next pass — that recurrence _is_ the dedupe, so never backlog it.
+5. **Docs-distillation threshold.** Per target doc, count undigested fact-cards (`invalid_from: null`, the doc's path not in their `digested_into:`) that **touch** it by the structural intersection in `skills/distiller/references/docs-mode.md` Resolution 1 (provenance∩`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)