@nurix/etna 0.16.0 → 0.17.1

package/bin/etna.js

@@ -1,11 +1,14 @@
 #!/usr/bin/env node
 // packages/cli/bin/etna.js
-// `npx @nurix/etna <harness-name>` — copy a Nurix harness into the current
-// directory. Drops the harness's CLAUDE.md at the project root and copies its
-// skills, agents, rules, and scripts into <project>/.claude/. 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 share one plugin.
+// `npx @nurix/etna [harness-name]` — copy a Nurix harness into the current
+// directory. Given a name it installs straight away; with no name (in a TTY) it
+// 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/.
+// 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
+// share one plugin.
 
 import {
     existsSync,
@@ -20,6 +23,7 @@ import {
 } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import * as p from '@clack/prompts';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkgRoot = resolve(__dirname, '..');
@@ -31,29 +35,37 @@ const dataDir = join(pkgRoot, 'data');
 // 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();
-    console.log(`\nUsage: npx @nurix/etna <harness-name>\n`);
-    const entries = Object.entries(idx.harnesses || {});
-    if (entries.length) {
-        console.log(`Available harnesses:`);
-        for (const [folder, plugin] of entries) {
-            console.log(`  ${folder}${plugin && plugin !== folder ? ` (plugin: ${plugin})` : ''}`);
-        }
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// True when both stdin and stdout are a terminal — clack prompts can't resolve
+// otherwise (CI, piped stdin), so the no-arg pick must fall back to an error.
+function isInteractive() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+// Boxed list of installable harnesses, for --help and the non-interactive no-arg path.
+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;
     }
-    console.log();
+    const lines = entries.map(
+        ([folder, plugin]) => `${folder}${plugin && plugin !== folder ? `  (plugin: ${plugin})` : ''}`,
+    );
+    p.note(lines.join('\n'), 'Available harnesses');
 }
 
 function loadHarnessIndex() {
     const path = join(dataDir, 'harness-index.json');
     if (!existsSync(path)) {
-        die(`harness-index.json missing — run \`npm run build:data\` from the package root.`);
+        die('harness-index.json missing — run `npm run build:data` from the package root.');
     }
     return JSON.parse(readFileSync(path, 'utf8'));
 }
 
 function die(msg, code = 1) {
-    console.error(`error: ${msg}`);
+    p.log.error(msg);
     process.exit(code);
 }
 
@@ -204,22 +216,47 @@ function mergeHooks(targetDir, bundledHooksJson) {
     return added;
 }
 
-async function main(args) {
-    if (args.includes('-h') || args.includes('--help') || args.length === 0) {
-        usage();
-        process.exit(args.length === 0 ? 1 : 0);
+// 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) {
+    const names = Object.keys(harnesses);
+    if (positional) {
+        if (!harnesses[positional]) {
+            p.log.error(`Unknown harness '${positional}'.`);
+            printHarnessList(harnesses);
+            p.outro('Pick one of the harnesses above.');
+            process.exit(1);
+        }
+        return positional;
     }
-
-    const harnessName = args[0];
-    const idx = loadHarnessIndex();
-    const harnesses = idx.harnesses || {};
-    if (!harnesses[harnessName]) {
-        die(
-            `Unknown harness '${harnessName}'. Available: ${Object.keys(harnesses).join(', ') || '(none)'}`,
-        );
+    if (!isInteractive()) {
+        p.log.error('No harness specified, and not running in an interactive terminal.');
+        printHarnessList(harnesses);
+        p.outro('Re-run as `npx @nurix/etna <harness-name>`.');
+        process.exit(1);
     }
-    const harnessFolder = harnessName;
+    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,
+            };
+        }),
+    });
+    if (p.isCancel(choice)) {
+        p.cancel('Cancelled — nothing installed.');
+        return null;
+    }
+    return choice;
+}
 
+// Copy one harness's bundled payload into the current directory. All file ops run
+// inside a spinner; the per-item detail + any warnings are emitted after it stops.
+async function installHarness(harnessName, harnesses) {
+    const harnessFolder = harnessName;
     const bundledHarnessDir = join(dataDir, 'harnesses', harnessFolder);
     const bundledClaudeMd = join(bundledHarnessDir, 'CLAUDE.md');
     if (!existsSync(bundledClaudeMd)) {
@@ -229,8 +266,8 @@ async function main(args) {
     const targetDir = process.cwd();
     const claudeMdDest = join(targetDir, 'CLAUDE.md');
 
-    // Read the bundled epoch marker up front so the install banner can name the
-    // harness version; the file itself is copied into the project further down.
+    // Bundled epoch marker — names the version for the banner and carries the
+    // `files` list (project-root config shipped outside the plugin route).
     const bundledHarnessJson = join(bundledHarnessDir, 'harness.json');
     const harnessMeta = existsSync(bundledHarnessJson) ? readJson(bundledHarnessJson) : {};
     const versionTag = harnessMeta.version ? ` v${harnessMeta.version}` : '';
@@ -238,31 +275,35 @@ async function main(args) {
     // harnesses may share it. Used only for legacy marketplace-entry cleanup.
     const pluginName = harnessMeta.name || harnesses[harnessName] || harnessName;
 
-    console.log(`\nInstalling ${harnessName}${versionTag} into ${targetDir}`);
+    const spin = p.spinner();
+    spin.start(`Installing ${harnessName}${versionTag} into ${targetDir}`);
 
-    const claudeBackup = backupIfExists(claudeMdDest);
-    if (claudeBackup) console.log(`  backed up existing CLAUDE.md → ${claudeBackup}`);
-
-    // CLAUDE.md ships frontmatter-free (the harness's metadata lives in its index.md and the
-    // plugin's definition.md), so it installs as a verbatim copy — no stripping.
-    // Tracks the categories actually present in this harness, for the closing
-    // summary — so a harness that ships no skills or hooks reads as an explicit,
-    // honest list rather than a silently missing line.
     const installed = [];
-
+    const notices = [];
+    const warnings = [];
+
+    // CLAUDE.md ships frontmatter-free, so it installs as a verbatim copy — no stripping.
+    // It's harness-owned and overwritten in place. If the project is a git repo the old copy
+    // is recoverable from history, so we skip the backup; if it isn't, there's no safety net,
+    // so we back it up and tell the user. (Backup applies to CLAUDE.md only.)
+    const claudeExisted = existsSync(claudeMdDest) || isSymlink(claudeMdDest);
+    const projectHasGit = existsSync(join(targetDir, '.git'));
+    if (claudeExisted) {
+        if (projectHasGit) {
+            notices.push('Overwrote existing CLAUDE.md (tracked by git — `git checkout CLAUDE.md` to restore).');
+        } else {
+            const claudeBackup = backupIfExists(claudeMdDest);
+            warnings.push(
+                `No .git here, so no version-control safety net — backed up existing CLAUDE.md → ${claudeBackup}`,
+            );
+        }
+    }
     cpSync(bundledClaudeMd, claudeMdDest, { force: true });
-    console.log(`  installed CLAUDE.md → ${claudeMdDest}`);
-    installed.push('CLAUDE.md');
+    installed.push('CLAUDE.md → ./');
 
     for (const sub of PLUGIN_SUBDIRS) {
-        const count = copyHarnessSubdir(
-            join(bundledHarnessDir, sub),
-            join(targetDir, '.claude', sub),
-        );
-        if (count > 0) {
-            console.log(`  copied ${count} ${sub} → ${targetDir}/.claude/${sub}/`);
-            installed.push(`${count} ${sub}`);
-        }
+        const count = copyHarnessSubdir(join(bundledHarnessDir, sub), join(targetDir, '.claude', sub));
+        if (count > 0) installed.push(`${count} ${sub} → .claude/${sub}/`);
     }
 
     // Copy the epoch marker so harness-manager can resolve the installed epoch.
@@ -270,33 +311,73 @@ async function main(args) {
         const harnessJsonDest = join(targetDir, '.claude', 'harness.json');
         mkdirSync(dirname(harnessJsonDest), { recursive: true });
         cpSync(bundledHarnessJson, harnessJsonDest, { force: true });
-        const tag = [harnessMeta.version && `v${harnessMeta.version}`, harnessMeta.epoch && `epoch ${harnessMeta.epoch}`]
-            .filter(Boolean)
-            .join(', ');
-        console.log(`  installed harness.json → ${harnessJsonDest}${tag ? ` (${tag})` : ''}`);
+    }
+
+    // Verbatim project-root files bundled outside the plugin route (.prettierrc.json,
+    // .vscode/settings.json, …), listed in harness.json's `files`. They land at the project
+    // root at their relative path — NOT under .claude/ — and overwrite unconditionally with no
+    // backup: the harness owns this config, and re-running etna refreshes it.
+    for (const rel of harnessMeta.files || []) {
+        const src = join(bundledHarnessDir, rel);
+        if (!existsSync(src)) continue;
+        const dest = join(targetDir, rel);
+        mkdirSync(dirname(dest), { recursive: true });
+        cpSync(src, dest, { recursive: true, force: true });
+        installed.push(`${rel} → ./${rel}`);
     }
 
     // Retire hooks earlier epochs shipped before merging, so the additive merge
     // never resurrects an entry pointing at a script this bundle no longer carries.
-    const retiredHooks = retireOldHooks(targetDir);
-    for (const r of retiredHooks) console.log(`  removed ${r}`);
+    for (const r of retireOldHooks(targetDir)) notices.push(`removed ${r}`);
 
     // 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`);
+    if (added > 0) installed.push(`${added} hook(s) → .claude/settings.json`);
+
+    for (const entry of migrateFromPluginInstall(targetDir, pluginName)) {
+        notices.push(`removed stale ${entry}`);
     }
 
-    const migrated = migrateFromPluginInstall(targetDir, pluginName);
-    for (const entry of migrated) console.log(`  removed stale ${entry}`);
+    spin.stop(`Installed ${harnessName}${versionTag}`);
+
+    p.note(installed.join('\n'), 'Written');
+    for (const notice of notices) p.log.info(notice);
+    for (const warning of warnings) p.log.warn(warning);
 
-    console.log(`\nDone — ${harnessName}${versionTag} installed: ${installed.join(', ')}.`);
-    console.log(
-        `Open Claude Code in ${targetDir}. Re-run \`npx @nurix/etna ${harnessName}\` anytime to refresh harness content.\n`,
+    p.outro(
+        `${harnessName}${versionTag} ready in ${targetDir}. ` +
+            `Re-run \`npx @nurix/etna ${harnessName}\` anytime to refresh harness content.`,
     );
 }
 
+async function main(args) {
+    const idx = loadHarnessIndex();
+    const harnesses = idx.harnesses || {};
+
+    if (args.includes('-h') || args.includes('--help')) {
+        p.intro('@nurix/etna — Nurix harness installer');
+        p.log.message('Usage: npx @nurix/etna [harness-name]');
+        printHarnessList(harnesses);
+        p.outro('Run with a name to install, or with no name to pick interactively.');
+        return;
+    }
+
+    const positional = args.find((a) => !a.startsWith('-'));
+
+    p.intro('@nurix/etna — Nurix harness installer');
+
+    const boot = p.spinner();
+    boot.start('Starting up');
+    await sleep(2000);
+    boot.stop('Ready');
+
+    const harnessName = await resolveHarnessName(positional, harnesses);
+    if (!harnessName) return; // user cancelled the interactive pick
+
+    await installHarness(harnessName, harnesses);
+}
+
 main(process.argv.slice(2)).catch((e) => {
-    console.error(e?.stack || e);
+    p.log.error(e?.stack || String(e));
     process.exit(1);
 });

package/data/harness-index.json

@@ -1,5 +1,5 @@
 {
-    "fingerprint": "19ff4c6bce0e",
+    "fingerprint": "50dc8734b7ee",
     "harnesses": {
         "code": "code-fable",
         "code-fable": "code-fable",

package/data/harnesses/code/.prettierignore

@@ -0,0 +1,12 @@
+# Dependencies & build output
+node_modules
+dist
+build
+
+# Lockfiles
+pnpm-lock.yaml
+package-lock.json
+yarn.lock
+
+# Harness-managed agent/skill definitions (installed under .claude/)
+.claude

package/data/harnesses/code/.prettierrc.json

@@ -0,0 +1,3 @@
+{
+  "proseWrap": "never"
+}

package/data/harnesses/code/.vscode/settings.json

@@ -0,0 +1,10 @@
+{
+  // Markdown: Prettier unwraps prose to one logical line per paragraph
+  // (see .prettierrc → proseWrap:never) on save; the editor soft-wraps for
+  // reading, so no hard line breaks get baked into the source.
+  "[markdown]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true,
+    "editor.wordWrap": "on"
+  }
+}

package/data/harnesses/code/CLAUDE.md

@@ -9,8 +9,7 @@ This file defines how AI agents (Claude, GPT, etc.) should work on this project.
 > 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:
 >
 > 1. Invoke **`harness-manager`** (`"baseline this repo"` / `"reconcile the harness"`). It reconciles `docs/`, stamps the version, then hands back.
-> 2. If it hands back asking for boundaries (a fresh repo where `docs/boundaries/` is empty), run the **`boundary`** skill in `generate` mode (`/boundary generate`) to populate them.
-> 3. Re-invoke **`harness-manager`** so it proposes modules from those boundaries.
+> 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.
 
@@ -37,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 (`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.
+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 → `docs/architecture/` / ADRs, backlog → `docs/history/`. Open questions block close.
 
 ---
 
@@ -48,7 +47,7 @@ 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 — 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.
+4. 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.
 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.
 
@@ -92,11 +91,9 @@ The spec-mode agent checks for ownership conflicts during research. If conflicts
 
 ## Boundaries
 
-`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.
+A boundary is a horizontal cross-cutting contract — entity model, db schema, wire envelope, auth/authz, event vocabulary, webhooks, env/config — where editing one side silently breaks the other. Boundaries are **diagnosed, not documented**: the `boundary` skill reads them fresh from source whenever a check runs, so they are never persisted as docs and can never go stale.
 
-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.
+**Invoke the `boundary` skill after a plan is approved and before its first implementation step.** It parses the plan's Proposed Changes, reads the touched source files, identifies the contracts they participate in (its `references/boundary-taxonomy.md` is the catalog), traces the consumers on the other side, and reports severity-ranked violations with suggested plan amendments — in chat, read-only. Fold the amendments into the plan before coding. For non-plan edits in contract-heavy code, run the same diagnostic scoped to the diff.
 
 > Agents and skills live under `.claude/agents/` and `.claude/skills/`. Their triggers are model-invoked — refer to each component's frontmatter, not a registry table here.
 

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

@@ -1,13 +1,13 @@
 ---
 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.
+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 in contract-heavy code), 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 review focus or rules.
 tools: Bash, Read, Write, Glob, Grep, Task
 model: inherit
 ---
 
 # Change-Review Agent
 
-You analyze code-change velocity over time to find risk zones — where change is accelerating or decelerating, and whether boundary coverage matches the risk. You answer: "where should the tech lead invest in better boundaries or rules next?"
+You analyze code-change velocity over time to find risk zones — where change is accelerating or decelerating, and whether review attention matches the risk. You answer: "where should the tech lead invest review focus or rules next?"
 
 You work in two phases:
 
@@ -33,8 +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 every file in `./docs/boundaries/` if the folder exists. Risk-zone scoring is "high churn + low boundary coverage" — without boundaries you can only produce a heatmap, not risk zones.
-4. Glob `./docs/{features,modules/*/features}/**/*.md` and read `owns` frontmatter to map churn to owning feature docs.
+3. Glob `./docs/{features,modules/*/features}/**/*.md` and read `owns` frontmatter to map churn to owning feature docs.
 
 ---
 
@@ -183,7 +182,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 boundary coverage 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
 
@@ -202,40 +201,40 @@ Trend column: ↑ rising, ↓ falling, → steady, ↑↑ sharply rising, ↓↓
 
 ## Step 7: Risk Zones
 
-For each module with high churn (top quartile in 1m window), check boundary coverage:
+For each module with high churn (top quartile in 1m window), check how contract-heavy and how covered it is:
 
-- Does any `docs/boundaries/` file **Bound** this module (name it in its **Bounds** line)?
+- 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`?
 
-Flag risk zones: high churn × low coverage. These are where silent breakage is most likely.
+Flag risk zones: high churn × contract-heavy × low doc coverage. These are where silent breakage is most likely.
 
 ## Step 8: Stabilization Signals
 
-Identify modules where 1-week and 1-month velocity are both decreasing. Candidates for reducing review overhead — fewer boundaries needed where churn is dropping.
+Identify modules where 1-week and 1-month velocity are both decreasing. Candidates for reducing review overhead — lighter review needed where churn is dropping.
 
 ## Step 9: Team Distribution
 
 Per module, list which authors made the most commits in the 3-month window. Surface concentration risks:
 
 - One author > 70% of commits in a critical module → bus-factor flag
-- One author owns all changes touching a boundary → review-coverage flag
+- One author owns all changes touching a contract-heavy surface → review-coverage flag
 
 ## Step 10: Report & Track
 
 ### Report format
 
 - **Velocity heatmap** (table above)
-- **Risk zones**: top 5 high-churn / low-coverage modules with specific boundaries to consider adding (via the `boundary` skill, `create` mode)
+- **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 "add a boundary for X (run the `boundary` skill, `create` mode)", "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", "update routing.md to cover Y", "spread reviews of Z across more authors"
 
 ### Update tracking
 
 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 directory \`{dir}/\` — discovered by change-review`
+   - `- **[P1]** High churn in contract-heavy directory \`{dir}/\` with no doc coverage — discovered by change-review`
 3. Report summary to the user
 
 ## Rules
@@ -245,5 +244,5 @@ Per module, list which authors made the most commits in the 3-month window. Surf
 - Always report progress: "Dispatching batch 1-5 of 12..." etc.
 - If git commands fail (bad branch, bad date range), stop and report the error clearly
 - Pipe characters in commit messages must be replaced with dashes before writing to CSV
-- Risk-zone identification requires boundaries — if `docs/boundaries/` is missing or empty, produce the heatmap only and tell the user that risk-zone scoring needs typed boundaries (run the `boundary` skill, `generate` mode)
+- Risk-zone identification judges contract-heaviness from the code itself (Step 7) — no persisted boundary docs exist or are needed
 - A clean report (no risk zones) is valid for a low-churn, well-covered project

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

@@ -20,10 +20,6 @@ Reconcile is **declarative, not a migration ladder.** You converge to the *curre
 
 The upgrade story is the two run back-to-back: install refreshes the engine → you reconcile the docs to it.
 
-## You hand back — the boundary work is a main-session skill
-
-Generating the typed boundaries is the **`boundary` skill** (`generate` mode), and a skill runs in the *main session* — you are a sub-agent without the Skill tool, so you do **not** run it yourself. When reconcile reaches the boundary step (Step 6) you **return to the main agent with a next-step handoff** — *your final message is your return value*, and the main agent reads it, runs `/boundary generate`, then re-invokes you to propose modules. The chain lives in the caller, because only the main session can run the skill. (Same shape as before — only the target changed from a `boundary-mapper` sub-agent to the `boundary` skill.)
-
 ## Modes
 
 - **Reconcile** (incl. **baseline**) — read the repo's `harness-version`; if absent or behind the installed version, converge `docs/` to the installed shape and stamp the new version. The Bootstrap invokes this.
@@ -33,8 +29,8 @@ Generating the typed boundaries is the **`boundary` skill** (`generate` mode), a
 
 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).
+- **`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.
 
@@ -42,7 +38,7 @@ You never edit a doc for content fidelity (that is `maintenance`); `maintenance`
 
 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.
+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.
 
 ---
@@ -65,7 +61,6 @@ docs/
 │   └── {feature}/         #   subfolder for deep features
 ├── modules/               # Declared bounded contexts — NOT scaffolded empty; appear by declaration
 │   └── {module}/          #   CLAUDE.md + features/ + pillars/ (module-local doctrine, lazy)
-├── boundaries/            # Typed application boundaries — generated by the boundary skill
 ├── operations/            # Setup, development, deployment, CI/CD
 ├── history/
 │   ├── CHANGELOG.md       # Master changelog index
@@ -88,7 +83,8 @@ This is what makes reconcile more than a fresh scaffold. Detect old-shape artifa
 
 | If you find (old shape) | Fold to (current shape) |
 |---|---|
-| `docs/operations/guardrails.md` | one file per boundary under `docs/boundaries/` (then run `/boundary generate`) |
+| `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/` |
 | `docs/architecture/overview.md` | split into `domain-model.md` / `glossary.md` / `non-goals.md` / `references.md` / `open-questions.md` |
 | flat feature docs that belong to a declared module | `docs/modules/{m}/features/` |
@@ -120,35 +116,28 @@ If the binary exists, register the docs subtrees once the tree is scaffolded. **
 
 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 inbox; 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.
+### Step 6 — Module proposal
 
-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.
+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.
 
-Branch on whether `docs/boundaries/` is already populated:
+- 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).
 
-- **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.
-  - **Propose — don't force.** Declaration is opt-in: a single-context app stays flat; 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.
 
-Re-running you after the skill is safe — the structure work is already done (idempotent), so the second pass is just the module proposal.
+Re-running you is safe — the structure work is already done (idempotent), so a 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:
 
@@ -172,17 +161,16 @@ Conformance, not fidelity. Report a table; fix nothing destructively without ask
 - **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.)
+- **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.)
 - **`docs/tests/` ownership** — present-with-content, or absent. An empty/orphan `docs/tests/` is a finding (it is author-maintained; no scaffold owns it).
 
 ## Rules
 
 - **Declarative, idempotent.** Re-running on a current repo is a no-op. Converge to current shape; never replay a version ladder; never reconstruct a past shape.
 - **One sentinel.** `docs/structure.md` `harness-version` is the only baseline/version marker. Do not reintroduce a `docs/memory/index.md` "is-baselined" check.
-- **Modules are declared, layout-blind.** Seed from boundary vertices + `owns` globs; never from `pnpm-workspace.yaml`/workspace walls. Propose, don't force.
+- **Modules are declared, layout-blind.** Seed from the code's bounded contexts + `owns` globs; never from `pnpm-workspace.yaml`/workspace walls. Propose, don't force.
 - **You orchestrate docs; the `documentation` skill supplies templates.** It is a library — you never expect it to baseline.
-- **Hand back for boundaries.** Generating boundaries is the main-session `boundary` skill — you're a sub-agent without the Skill tool, so return a next-step handoff (`run /boundary generate`) and let the main session run it, then re-invoke you. Never transcribe the boundary-generation process inline.
 - **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.