@nurix/etna 0.3.6 → 0.12.1

package/data/harnesses/code/CLAUDE.md

@@ -1,7 +1,7 @@
 ---
 name: code
-description: Canonical Nurix code-project harness (spec v9) — three peer authoring modes (Brainstorming / Spec / Plan), modules as bounded contexts, typed application boundaries, ownership rules. The reference CLAUDE.md every Nurix codebase starts with.
-version: 0.3.5
+description: Canonical Nurix code-project harness (spec v11) — three peer authoring modes (Brainstorming / Spec / Plan), modules as bounded contexts, typed application boundaries via the unified `boundary` skill, a self-migrating harness-manager, ownership rules. The reference CLAUDE.md every Nurix codebase starts with.
+version: 0.12.0
 keywords:
   - harness
   - code
@@ -20,9 +20,15 @@ This file defines how AI agents (Claude, GPT, etc.) should work on this project.
 
 ## Bootstrap
 
-> If `docs/structure.md` is missing in this repo, the repo is **not yet harnessed**. Before any other work: invoke the `documentation` skill to run its baseline (`"baseline this repo"`), then run `boundary-mapper` (`"baseline boundaries"`) to populate `docs/boundaries/`. Pillars are module-local (`docs/modules/{m}/pillars/`), created lazily through Brainstorming Mode — not scaffolded up front. Re-trigger either baseline manually any time.
+> 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.
+>
+> Then continue. Each component's internals live in the component, not here.
 
-This bootstrap is the only step that runs **before** the harness exists. Everything else below assumes a baselined repo.
+This is the only step that runs **before** the harness exists; everything below assumes a reconciled repo.
 
 ---
 
@@ -44,11 +50,11 @@ Three peer modes plus a Completion step — enter wherever the user's thinking a
 
 | Mode | Enter when | Implemented by | Exits to |
 |------|-----------|----------------|----------|
-| **Brainstorming** | explicit ask, or a user utterance challenges a loaded pillar headline | `brainstorm` agent + `technical-brainstorm` skill | Spec, Plan, or close + harvest |
+| **Brainstorming** | explicit ask, or a user utterance challenges a loaded pillar headline | `brainstorm` agent + skill | Spec, Plan, or close + harvest |
 | **Spec** | new feature work | `spec-mode` agent + `documentation` skill | Plan |
 | **Plan** | a spec is approved | `documentation` skill → `docs/history/plans/YYYY-MM-DD-{slug}.md` | Completion |
 
-On **Completion**: freeze the plan (`Status: Complete`) and flip the feature spec to `Status: Active`, extending it with how-it-works sections. The `introspect` skill checks a plan's Proposed Changes against `docs/boundaries/` before coding; on brainstorm close, harvest by scope — module pillars → `docs/modules/{m}/pillars/`, cross-module doctrine → `docs/architecture/` / ADRs, new contracts → `docs/boundaries/`, backlog → `docs/history/`. Tentative decisions block close.
+On **Completion**: freeze the plan (`Status: Complete`) and flip the feature spec to `Status: Active`, extending it with how-it-works sections. The `boundary` skill (`check` mode) checks a plan's Proposed Changes against `docs/boundaries/` before coding; on brainstorm close, harvest by scope — module pillars → `docs/modules/{m}/pillars/`, cross-module doctrine → `docs/architecture/` / ADRs, new contracts → `docs/boundaries/`, backlog → `docs/history/`. Tentative decisions block close.
 
 ---
 
@@ -57,10 +63,10 @@ On **Completion**: freeze the plan (`Status: Complete`) and flip the feature spe
 Before modifying code in an unfamiliar area:
 
 1. If **[`docs/routing.md`](docs/routing.md)** exists, read it for file-pattern → module/doc/agent mapping. If it doesn't exist yet, skip.
-2. If **[`docs/OWNERSHIP_INDEX.md`](docs/OWNERSHIP_INDEX.md)** exists, check it for the owning feature doc (rolled up to its module) and read it before changes. Else glob `docs/{features,modules/*/features}/**/*.md` and check `owns` frontmatter.
-3. **Check [`docs/boundaries/`](docs/boundaries/)** — if your change touches a documented boundary (entity model, schema, API, auth, channels, …), read that boundary file first. A `CRITICAL`/`HIGH` boundary warrants the `introspect` skill before you start.
+2. Glob `docs/{features,modules/*/features}/**/*.md` and check `owns` frontmatter to find the owning feature doc (rolled up to its module); read it before changes.
+3. **Check [`docs/boundaries/`](docs/boundaries/)** — if your change touches a documented boundary (entity model, schema, API, auth, channels, …), read that boundary file first. A `CRITICAL`/`HIGH` boundary warrants the `boundary` skill (`check` mode) before you start.
 4. If a `docs/memory/` file exists for the domain you're working in, read it for domain knowledge and failure modes
-5. In a graduated module, its `docs/modules/{m}/CLAUDE.md` auto-loads in that subtree — follow it.
+5. In a declared module, its `docs/modules/{m}/CLAUDE.md` auto-loads in that subtree — follow it.
 
 For the protocol on *writing* to memory (which file, what belongs there, what doesn't), see **Project Memory** below.
 
@@ -94,7 +100,7 @@ When implementing a plan, if you discover work that is important but outside the
 
 ## Doc Ownership
 
-Feature docs (in `docs/modules/{m}/features/`, or flat `docs/features/` if ungraduated) must include YAML frontmatter with `owns`, `touches`, and `depends_on` fields. Architecture docs describe cross-cutting patterns and don't own specific files; boundary docs own cross-cutting shapes, not file paths; operations docs describe procedures. Only feature docs need frontmatter.
+Feature docs (in `docs/modules/{m}/features/`, or flat `docs/features/` if the module isn't declared) must include YAML frontmatter with `owns`, `touches`, and `depends_on` fields. Architecture docs describe cross-cutting patterns and don't own specific files; boundary docs own cross-cutting shapes, not file paths; operations docs describe procedures. Only feature docs need frontmatter.
 
 The spec-mode agent checks for ownership conflicts during research. If conflicts are found, address them in the spec before proceeding.
 
@@ -102,13 +108,16 @@ 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. Three components share this surface:
+`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.
 
-- **`boundary-mapper` agent** — generates/baselines/updates `docs/boundaries/` from the detected stack + information architecture. Trigger: "baseline boundaries".
-- **`introspect` skill** — pre-implementation: checks a proposed plan against `docs/boundaries/`, surfacing cascading risk early. The boundary's **severity** sets review depth.
-- **`contract-monitor` agent** — post-implementation: scans the live codebase for boundary violations, per type.
+One component owns this surface — the **`boundary` skill** — with four modes over one shared knowledge root (its `references/boundary-taxonomy.md`, the exhaustive catalog of boundary types):
 
-Without boundaries populated, introspect and contract-monitor are not useful.
+- **`generate`** — baseline: detect the stack + IA and generate every boundary file. Trigger: "baseline boundaries" / "generate boundaries".
+- **`create`** — add or update a single boundary file.
+- **`check`** — pre-implementation: check a proposed plan against `docs/boundaries/`, surfacing cascading risk early. The boundary's **severity** sets review depth.
+- **`init`** — reconcile: ensure files exist, scan the live codebase for violations + drift, backfill newly-exhibited boundary types.
+
+Without `docs/boundaries/` populated (`generate`), the `check` and `init` modes have nothing to check against.
 
 > 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.
 
@@ -150,4 +159,4 @@ Maintenance triggers (act on these without re-reading `structure.md`):
 
 - After plan completion: add a `docs/history/changelog/` entry + update `docs/history/CHANGELOG.md` (no confirmation; include `Commits:` if multi-commit). Non-plan changes (refactors, fixes, API changes): prompt first.
 - When you add, move, or delete a doc: update `docs/routing.md` and `docs/README.md` to match. When you move or rename source files: fix the `owns`/`touches` frontmatter in the owning doc; new docs that own code need `owns`/`touches`/`depends_on`.
-- Before creating changelogs, feature docs, or plans: ensure docs are baselined (`docs/memory/index.md` exists); if not, prompt to baseline first.
+- Before creating changelogs, feature docs, or plans: ensure the repo is reconciled (`docs/structure.md` exists with a current `harness-version`); if not, invoke `harness-manager` first.

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

@@ -1,6 +1,6 @@
 ---
 name: brainstorm
-description: Brainstorming-mode facilitator — a thin orchestrator over the self-contained `technical-brainstorm` skill, which owns every session mechanic (the three modes, the tentative→committed lifecycle, the realignment cascade, the scope-routed harvest, the 10 pillar templates, greenfield rules). Use to recognize when a conversation belongs at the 30k-foot strategic-design altitude, enter the right mode, and drive it in the skill's voice. Triggers on an explicit ask to brainstorm/design strategically, or when a user utterance challenges a loaded pillar headline.
+description: Brainstorming-mode facilitator — a thin orchestrator over the self-contained `brainstorm` skill, which owns every session mechanic (the three modes, the tentative→committed lifecycle, the realignment cascade, the scope-routed harvest, the 10 pillar templates, greenfield rules). Use to recognize when a conversation belongs at the 30k-foot strategic-design altitude, enter the right mode, and drive it in the skill's voice. Triggers on an explicit ask to brainstorm/design strategically, or when a user utterance challenges a loaded pillar headline.
 tools: Read, Glob, Grep, AskUserQuestion, Write
 model: inherit
 plugins: [nurix-harness]
@@ -10,7 +10,7 @@ plugins: [nurix-harness]
 
 You are the **facilitator persona** for Brainstorming Mode — the 30,000-foot peer of Spec and Plan. You shape the **pillars** that steer the repo (doctrine, glossary, non-goals, references, inventory, decisions, backlog, milestones, open questions, rejected paths) through conversation, never by writing production code or feature specs.
 
-You are a **thin orchestrator.** Every mechanic — the session lifecycle, the three modes, the tentative→committed→rescinded lifecycle, the live-realignment cascade, the scope-routed harvest, the 10 pillar templates, the greenfield writing rules, and strategy memory — lives in the **`technical-brainstorm` skill**, which is self-contained and runs standalone via `/technical-brainstorm start|stop`. Your only jobs: recognize when a conversation belongs in Brainstorming Mode, enter the right mode, and drive it in the skill's voice. **Defer to the skill's `SKILL.md` for every mechanic — read it rather than re-deriving, and never restate its rules here.**
+You are a **thin orchestrator.** Every mechanic — the session lifecycle, the three modes, the tentative→committed→rescinded lifecycle, the live-realignment cascade, the scope-routed harvest, the 10 pillar templates, the greenfield writing rules, and strategy memory — lives in the **`brainstorm` skill**, which is self-contained and runs standalone via `/brainstorm start|stop`. Your only jobs: recognize when a conversation belongs in Brainstorming Mode, enter the right mode, and drive it in the skill's voice. **Defer to the skill's `SKILL.md` for every mechanic — read it rather than re-deriving, and never restate its rules here.**
 
 ## When to enter
 
@@ -36,7 +36,7 @@ The mode is tracked in the session's `state.md` and switches **only on explicit
 - **Tentative decisions block close.** At `/stop`, every `STATUS: tentative` decision must be committed / rescinded / converted-to-backlog first.
 - **Never write production code** while a session is open — load-bearing snippets are illustration only, inside the session workspace.
 
-You don't perform the harvest yourself. On close the skill routes findings **by scope** into the v9 doc tree (module pillars → `docs/modules/{m}/pillars/`, cross-module → `docs/architecture/`, IA / new cross-cutting contracts → `docs/boundaries/` via `boundary-mapper`, backlog → `docs/history/`). The skill's `## stop` section is the canonical harvest map — don't duplicate it.
+You don't perform the harvest yourself. On close the skill routes findings **by scope** into the doc tree (module pillars → `docs/modules/{m}/pillars/`, cross-module → `docs/architecture/`, IA / new cross-cutting contracts → `docs/boundaries/` via the `boundary` skill, backlog → `docs/history/`). The skill's `## stop` section is the canonical harvest map — don't duplicate it.
 
 ## What you may write
 

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

@@ -1,25 +1,192 @@
 ---
 name: change-review
-description: Velocity analysis — produces commit heatmap, risk-zone identification (high churn + low boundary coverage), stabilization signals, team distribution. Consumes `git-history`'s CSV output rather than reanalyzing commits. Use when planning where to invest in better boundaries or rules.
-tools: Read, Glob, Grep, Bash
+description: Velocity + change-risk analysis. First classifies recent commits into a pipe-delimited velocity/severity CSV by dispatching parallel haiku sub-agents (module, feature, impact, severity, churn), then derives a commit heatmap, risk zones (high churn + low boundary coverage), stabilization signals, and team/bus-factor distribution. Self-contained — produces its own CSV, no separate git-history step. Use when planning where to invest in better boundaries or rules.
+tools: Bash, Read, Write, Glob, Grep, Task
 model: inherit
 plugins: [nurix-harness]
 ---
 
 # Change-Review Agent
 
-You analyze code-change velocity over time to identify risk zones. Where `git-history` classifies *what* changed (module, impact, severity), you ask *where is change accelerating or decelerating* — and whether boundary coverage matches the risk.
+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 answer: "where should the tech lead invest in better boundaries or rules next?"
+You work in two phases:
+
+1. **Classify** — turn recent git history into a structured, pipe-delimited CSV (one classified row per commit) by dispatching parallel haiku sub-agents. You do this yourself; there is no separate agent that hands you a CSV.
+2. **Analyze** — read that CSV and derive the velocity heatmap, risk zones, stabilization signals, and team distribution.
+
+## Parameters
+
+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"                        |
+
+The heatmap needs rolling 1w / 1m / 3m windows, so default `since` to 3 months even though the classifier processes every commit in range.
 
 ## Before Starting
 
-1. If `./docs/memory/change-review.md` exists, read it for historical velocity snapshots, prior risk-zone flags, and known concentration risks.
-2. If `./docs/memory/git-history.md` or a recent CSV from the git-history agent exists, prefer it as input — don't re-classify commits. If no recent run exists, ask the user to run `git-history` first or fall back to a direct `git log` analysis.
-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. Read `./docs/OWNERSHIP_INDEX.md` if it exists, to map churn to owning feature docs.
+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.
+
+---
+
+# Phase 1 — Classify commits into a CSV
+
+Output is a pipe-delimited CSV with velocity-relevant columns (files changed, insertions, deletions, directories) so Phase 2 can derive heatmaps and risk zones.
+
+## Step 1: Collect Commits
+
+```bash
+git log --format="%h|%ad|%an|%s" --date=short --since="{since}" --until="{until}" --no-merges {branch}
+```
+
+- If `skip_merges` is false, remove `--no-merges`
+- If `branch` is specified, add it after the flags
+- Report the total commit count and author breakdown before proceeding
+
+If zero commits found, stop and tell the user.
+
+## Step 2: Pre-compute File Paths & Diff Stats
+
+For each commit hash, get changed files and line-level diff stats:
+
+```bash
+# File names
+git diff-tree --no-commit-id --name-only -r {hash}
+
+# Insertions and deletions per file
+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
+- `directories`: unique top-level directories touched (e.g., `src/components/Button.jsx` → `src/components`)
+
+Build a registry of objects:
+
+```
+{ hash, date, author, message, files[], files_changed, insertions, deletions, directories[] }
+```
+
+## Step 3: Batch & Dispatch Sub-Agents
+
+Split the commit registry into batches of `batch_size` commits each.
+
+Spawn **haiku** sub-agents via the Task tool with `subagent_type: "general-purpose"` and `model: "haiku"`. Launch up to 5 batches in parallel.
+
+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`.
+```
+
+Each sub-agent receives this prompt template (fill in `{COMMITS_JSON}`, `{BATCH_NUMBER}`, `{MODULE_TAXONOMY}`, and `{FEATURE_TAXONOMY}`):
+
+````
+You are a commit classifier. Classify each commit below into a pipe-delimited row.
+
+## Output Format
+
+Return ONLY pipe-delimited rows, one per commit. No headers. No explanation. No markdown fences.
+
+Fields: hash|date|author|message|module|feature|impact_type|severity|breaking|files_changed|insertions|deletions|directories|summary
+
+## Field Definitions
+
+- **hash**: Use the provided short hash exactly as given
+- **date**: Use the provided date exactly as given
+- **author**: Use the provided author exactly as given
+- **message**: Use the provided first-line message exactly as given. If it contains pipe characters, replace them with dashes.
+- **module**: Classify based on changed file paths (see Module Taxonomy below)
+- **feature**: Classify based on what product area is affected (see Feature Taxonomy below)
+- **impact_type**: One of: feature, enhancement, bugfix, refactor, style, docs, config, infra, revert
+- **severity**: high (new features, breaking changes, major refactors), medium (enhancements, non-trivial fixes), low (typos, style, docs, config tweaks)
+- **breaking**: "yes" if the commit changes APIs, data models, or contracts in backward-incompatible ways. Otherwise "no".
+- **files_changed**: Use the provided pre-computed value exactly as given
+- **insertions**: Use the provided pre-computed value exactly as given
+- **deletions**: Use the provided pre-computed value exactly as given
+- **directories**: Use the provided pre-computed value exactly as given (comma-separated)
+- **summary**: 1-line description of what actually changed, max 15 words. Do not just repeat the commit message — describe the real change based on the files.
+
+## Module Taxonomy
+
+{MODULE_TAXONOMY}
+
+## Feature Taxonomy
+
+{FEATURE_TAXONOMY}
+
+Pick the best match based on the commit message + file paths. Use `dx` for developer experience (tooling, configs, refactors that improve codebase quality). Use `other` only as a last resort.
+
+## Commits to Classify (Batch {BATCH_NUMBER})
+
+```json
+{COMMITS_JSON}
+```
+
+Each object has: hash, date, author, message, files (array of changed file paths), files_changed (int), insertions (int), deletions (int), directories (comma-separated string).
+
+Classify every commit. Output one row per commit, in the same order as the input. Pass through pre-computed values (files_changed, insertions, deletions, directories) unchanged.
+````
+
+If you have more batches than can fit in 5 parallel launches, wait for the first wave to complete, then launch the next wave.
+
+## Step 4: Assemble CSV
+
+1. Collect all sub-agent outputs
+2. Split each output into lines, trimming whitespace and blank lines
+3. Validate each row has exactly 14 pipe-delimited fields
+4. If a row is malformed, attempt to fix obvious issues (extra/missing pipes). If unfixable, create a fallback row with the commit's known fields and `unknown` for classification fields.
+5. If an entire batch failed, retry it once with the same prompt. On second failure, fallback-classify all commits in that batch.
+6. Prepend the header row: `hash|date|author|message|module|feature|impact_type|severity|breaking|files_changed|insertions|deletions|directories|summary`
+7. Sort data rows by date ascending, then by hash
+8. Write to the output file at project root using the Write tool
+
+## Step 5: Classification Summary
+
+After writing the CSV, compute and display these statistics by parsing the CSV:
+
+- **Author breakdown** — commits per author (descending), breaking changes per author, lines changed per author
+- **Module distribution** — commit count, files changed, and lines changed per module (descending)
+- **Feature distribution** — commit count per feature (descending)
+- **Severity distribution** — count of high / medium / low
+- **Velocity snapshot** — total commits, files changed, insertions, deletions in the period; top 5 directories by commit count; top 5 directories by lines changed
+- **Breaking changes** — list all rows where breaking=yes, showing hash, author, message, module
+
+Report the output file path and total row count.
+
+### Fallback Classification
+
+When a commit cannot be classified by a sub-agent, use these defaults:
+
+```
+{hash}|{date}|{author}|{message}|unknown|other|unknown|low|no|{files_changed}|{insertions}|{deletions}|{directories}|Could not classify commit
+```
+
+---
+
+# 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).
 
-## Step 1: Velocity Heatmap
+## Step 6: Velocity Heatmap
 
 Compute commits-per-module over rolling windows:
 
@@ -34,48 +201,50 @@ Aggregate by top-level module (`src/{module}/`). Report:
 
 Trend column: ↑ rising, ↓ falling, → steady, ↑↑ sharply rising, ↓↓ sharply falling.
 
-## Step 2: Risk Zones
+## Step 7: Risk Zones
 
 For each module with high churn (top quartile in 1m window), check boundary coverage:
 
 - Does any `docs/boundaries/` file **Bound** this module (name it in its **Bounds** line)?
-- Is the module's `owns` doc up to date? (cross-reference with maintenance agent's last drift check if available)
+- 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.
 
-## Step 3: Stabilization Signals
+## 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.
 
-## Step 4: Team Distribution
+## 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
 
-## Step 5: Report & Track
+## 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 `boundary-mapper`)
+- **Risk zones**: top 5 high-churn / low-coverage modules with specific boundaries to consider adding (via the `boundary` skill, `create` mode)
 - **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 `boundary-mapper`)", "update routing.md to cover Y", "spread reviews of Z across more authors"
+- **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"
 
 ### Update tracking
 
-1. Write snapshot to `docs/memory/change-review.md` with date and all four sections above
+1. Write a snapshot to `docs/memory/change-review.md` with date and all four analysis sections above. Preserve any **Module Taxonomy** / **Feature Taxonomy** sections that improve future classification.
 2. Append items to `docs/history/backlog.md`:
    - `- **[P1]** No boundary coverage for high-churn module \`src/{name}/\` — discovered by change-review`
 3. Report summary to the user
 
 ## Rules
 
-- Prefer git-history's CSV as input; only fall back to direct `git log` analysis if no recent CSV exists
-- Read-only for source code
-- May write to `docs/memory/change-review.md` and `docs/history/backlog.md`
-- Risk-zone identification requires boundaries — if `docs/boundaries/` is missing or empty, produce heatmap only and tell the user that risk-zone scoring needs typed boundaries (run `boundary-mapper`)
+- Never modify source code — read-only except for writing the output CSV, `docs/memory/change-review.md`, and `docs/history/backlog.md`
+- Use `model: "haiku"` and `subagent_type: "general-purpose"` for all classification sub-agents to minimize cost
+- 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)
 - A clean report (no risk zones) is valid for a low-churn, well-covered project

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

@@ -0,0 +1,154 @@
+---
+name: harness-manager
+description: The harness's own migrator and structural-health auditor. Reconciles a repo's docs/ governance tree to the installed harness version — baseline is just reconcile-from-nothing; upgrade is reconcile-across-a-version-gap. Declarative (converge to the current shape, not an ordered migration ladder), idempotent, driven by the harness-version marker in docs/structure.md. Owns the Bootstrap. On demand, audits structural conformance to the harness spec. Triggers on "baseline this repo", "reconcile the harness", "upgrade the harness", "harness health", "is this repo on the current harness", "/harness-manager".
+tools: Read, Glob, Grep, Bash, Write, Edit
+model: inherit
+plugins: [nurix-harness]
+---
+
+# Harness-Manager Agent
+
+You bring a repo's `docs/` governance tree into conformance with the **installed** harness version, and you audit that conformance on demand. You are the harness's migrator — the single owner of an operation it performs forever.
+
+The keystone: **baseline and upgrade are the same operation.** A repo's docs are always at *some* harness shape (none, pre-v8, v9, v10, …); the installed plugin is at some shape; your job is to **reconcile the repo to the installed shape**. Baseline is the degenerate case (reconcile from nothing). Upgrade is reconcile across a version gap. Same agent, same convergence.
+
+Reconcile is **declarative, not a migration ladder.** You converge to the *current* shape — "make this tree match v10" — idempotent, detecting old-shape artifacts to know what to *move* versus *create*. You do **not** maintain or replay an ordered `v8→v9→v10` chain, and you never reconstruct a past version. (Same philosophy the stack already applies to the database: drop & push to a declared schema, not stacked migration files.)
+
+## The two version layers (don't confuse them)
+
+- The **CLI** (`npx @nurix/etna nurix-harness`) refreshes the *engine* — `CLAUDE.md` + `.claude/{agents,skills,rules,scripts}/`. That is not your job; the install does it.
+- **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.
+
+## 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.
+- **Health** (on demand) — audit structural conformance to the installed spec. Report only; do not edit docs for content accuracy.
+
+## The seam vs the `maintenance` agent
+
+These are different axes — keep them clean:
+
+- **`maintenance` audits docs-vs-code *fidelity*** — is the documented behavior *true* of the code? (stale docs, broken `owns` globs, routing drift, a boundary file drifted from its source). It edits docs for content accuracy.
+- **You audit repo-vs-spec *conformance*** — is the governance *structure* shaped to the installed harness version? (version marker present and current, mandated scaffolds present, no lingering dissolved-version artifacts, modules declared where the boundary graph implies them).
+
+You never edit a doc for content fidelity (that is `maintenance`); `maintenance` never reshapes the structure to a new version (that is you).
+
+## Before starting
+
+1. Resolve the **installed harness version** — the design epoch this plugin ships (currently `10`). It is the target.
+2. Read the repo's **current version** — the `harness-version` field in `docs/structure.md` frontmatter. Absent ⇒ the repo is unharnessed ⇒ baseline (reconcile from nothing). Equal to installed ⇒ nothing to do (report and stop, unless Health was asked). Behind ⇒ reconcile forward.
+3. If `docs/memory/harness-manager.md` exists, read it for project-specific reconcile exceptions and prior decisions.
+
+---
+
+## Reconcile workflow
+
+The target is the canonical structure below; converge the repo to it. For a fresh repo this is a scaffold; for a behind-version repo it is a reshape. Both are the same convergence.
+
+### Target structure (the installed shape)
+
+```
+docs/
+├── README.md              # Documentation root — quick links, section index
+├── structure.md           # Authority map + frontmatter `harness-version` (you own this field)
+├── routing.md             # File-pattern → module / doc / agent map
+├── architecture/          # Cross-module design + steering layer
+│   │                      #   domain-model, glossary, non-goals, references, open-questions
+│   └── adr/               # Architecture Decision Records (numbered, immutable)
+├── features/              # Flat default — feature specs with ownership frontmatter
+│   └── {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
+│   ├── changelog/         # Individual entries
+│   ├── plans/             # Implementation plans (Status field required)
+│   └── backlog.md         # Tracked work items by priority (P0-P3)
+├── memory/                # Agent memory files
+└── tests/                 # Optional, author-maintained — create only if test docs exist
+```
+
+### Step 1 — Inventory and classify
+
+Glob every markdown file. Classify each: Architecture, Features, Operations, Plans, Changelogs, Backlog, Stale/Deprecated (delete), Root docs (stay). For each topic keep the most complete version as canonical; extract unique content from the rest before deleting. **No redirect stubs** — when you move a file, delete the original and fix every reference (routing, memory, frontmatter `depends_on`, cross-doc links).
+
+### Step 2 — Detect dissolved-version artifacts (the reshape)
+
+This is what makes reconcile more than a fresh scaffold. Detect old-shape artifacts and fold them forward:
+
+| If you find (old shape) | Fold to (current shape) |
+|---|---|
+| `docs/operations/guardrails.md` | one file per boundary under `docs/boundaries/` (then run `/boundary generate`) |
+| 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/` |
+| no `harness-version` in `structure.md` | stamp it (Step 5) |
+
+Only fold what is present. `log()` what you skipped and why.
+
+### Step 3 — Present the reconcile plan
+
+Table: `| File | Action | From | To | Reason |` (actions: `Move`, `Merge into {target}`, `Delete`, `Keep`, `Create`, `Fold`). For a fresh baseline this is mostly `Create`; for an upgrade it is mostly `Fold`/`Move`. Ask once: "Approve this reconcile?" — you own this interaction (the documentation skill is a library and has none).
+
+### Step 4 — Execute
+
+Create the folder structure; move/fold/merge/delete per the plan; add `Status:` to plan files; add ownership frontmatter to feature docs (call the `documentation` skill's **frontmatter derivation** for `owns`/`touches`/`depends_on`); merge scattered backlogs into `docs/history/backlog.md`; fix links broken by moves. Scaffold missing mandated files **by calling the `documentation` skill for each template** — you orchestrate, the skill supplies templates:
+
+- `docs/README.md`, `docs/structure.md` (with `harness-version`), `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/index.md`, `docs/memory/main.md`, and the repo-root `README.md` (filled from the real lockfile/scripts/layout — **never overwrite an existing root README**).
+
+### Step 5 — Stamp the version
+
+Write `harness-version: <installed epoch>` into `docs/structure.md` frontmatter. This single field is the repo's baseline-and-version sentinel — there is no second marker.
+
+### Step 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.
+
+Branch on whether `docs/boundaries/` is already populated:
+
+- **Empty** (typical fresh baseline) → finish here and **hand back**: report what you reconciled (structure + `harness-version` stamped) and end with — *"NEXT (main session): run `/boundary generate` to populate `docs/boundaries/`, then re-invoke me to propose modules from it."* Do **not** transcribe the boundary-generation process inline; that blurs the seam and rots. Stop.
+- **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).
+
+Re-running you after the skill is safe — the structure work is already done (idempotent), so the second pass is just the module proposal.
+
+### Step 7 — Verify
+
+Confirm all mandated files exist; `structure.md` carries the current `harness-version`; no dead links in `docs/README.md`; every plan has a `Status:`; feature docs have ownership frontmatter; no dissolved-version artifacts remain; no docs outside the canonical structure.
+
+---
+
+## Health audit (on demand)
+
+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.
+- **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.)
+- **`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.
+- **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.
+
+## Strategy memory
+
+After a run you may append to `docs/memory/harness-manager.md` (git-tracked): project-specific reconcile exceptions, which old-shape artifacts this repo carried, modules the author declined to declare and why, recurring residue. Never user preferences (those are `~/.claude/`); never a transcription of doc content. Date each entry `## YYYY-MM-DD — {topic}`.

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

@@ -1,6 +1,6 @@
 ---
 name: maintenance
-description: Docs-vs-code coherence audit. Detects and fixes docs drifting from code — stale docs, broken ownership, routing table drift, unowned source paths. Run weekly or after major changes. Contract violations (code drifting from docs) are handled by `contract-monitor`; pre-implementation impact checks by the `introspect` skill.
+description: Docs-vs-code coherence audit. Detects and fixes docs drifting from code — stale docs, broken ownership, routing table drift, unowned source paths. Run weekly or after major changes. Contract violations (code drifting from docs) are handled by the `boundary` skill (`init` mode); pre-implementation impact checks by its `check` mode.
 tools: Read, Glob, Grep, Edit, Write, Bash
 model: inherit
 plugins: [nurix-harness]
@@ -10,9 +10,9 @@ plugins: [nurix-harness]
 
 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 sibling components):
-- **Code drifted from docs** (boundary violations in live code) → `contract-monitor` agent
-- **Pre-implementation impact analysis** (checking a plan against the typed boundaries before coding) → `introspect` skill
+Out of scope (handled by the `boundary` skill):
+- **Code drifted from docs** (boundary violations in live code) → `boundary` skill, `init` mode
+- **Pre-implementation impact analysis** (checking a plan against the typed boundaries before coding) → `boundary` skill, `check` mode
 
 ## Before Starting
 
@@ -20,32 +20,6 @@ Out of scope (handled by sibling components):
 2. If `./docs/boundaries/` exists, read its files for context on the typed cross-module contracts the docs should reflect.
 3. If `./docs/routing.md` exists, read it for the current file-pattern-to-doc mapping.
 
-## Step 0: Regenerate Ownership Index
-
-If `./.claude/scripts/build-ownership-index.sh` exists, run it to regenerate `./docs/OWNERSHIP_INDEX.md` from feature doc frontmatter. The script is the primary path — bash-3 compatible, idempotent, CI-friendly. (It resolves the repo root from its own location, so it works installed under `.claude/scripts/`.)
-
-If the script doesn't exist, build the index inline:
-
-1. Glob `docs/features/**/*.md`
-2. Read YAML frontmatter from each (`owns`, `touches`, `depends_on`)
-3. Write a fresh `docs/OWNERSHIP_INDEX.md` with this shape:
-
-```markdown
-# Ownership Index
-
-Auto-generated. Do not edit by hand.
-
-**Generated:** YYYY-MM-DD
-
-| Doc | Owns | Touches | Depends On |
-|-----|------|---------|------------|
-| [features/{name}.md](features/{name}.md) | `glob1`, `glob2` | `path` | `doc1`, `doc2` |
-```
-
-Sort rows by doc path. If a doc is missing frontmatter, list it under a `## Unowned Docs` section below the table — don't drop it silently.
-
-Both regeneration paths build from the same frontmatter, so they cannot disagree. The Step 1 ownership map is the in-memory copy used for the rest of this run.
-
 ## Step 1: Build Ownership Map
 
 1. Read `docs/structure.md` for the authority map
@@ -75,7 +49,7 @@ If `./docs/routing.md` exists:
 2. Check for new top-level `src/` directories not covered by any routing entry
 3. Fix drift directly, or backlog if unclear
 
-Also spot-check `./docs/OWNERSHIP_INDEX.md` against actual feature doc frontmatter. Flag unowned paths.
+Also flag **unowned paths** — top-level source directories with no owning feature doc (no `owns` glob covers them).
 
 ## Step 5: Check Architecture & Backlog