@nurix/etna 0.10.1 → 0.13.0

package/data/harnesses/code/CLAUDE.md

@@ -1,7 +1,7 @@
 ---
 name: code
-description: Canonical Nurix code-project harness (spec v10) — three peer authoring modes (Brainstorming / Spec / Plan), modules as bounded contexts, typed application boundaries, a self-migrating harness-manager, ownership rules. The reference CLAUDE.md every Nurix codebase starts with.
-version: 0.10.0
+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 — or its `harness-version` frontmatter is behind the installed harness — invoke the **`harness-manager`** agent (`"baseline this repo"` / `"reconcile the harness"`). It reconciles `docs/` to the installed version (baseline is just reconcile-from-nothing), calling the `documentation` skill for each template, then runs `boundary-mapper` to populate `docs/boundaries/` and proposes modules from the boundaries it finds. Pillars are module-local (`docs/modules/{m}/pillars/`), created lazily through Brainstorming Mode — not scaffolded up front. Re-trigger `harness-manager` 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 reconciled 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,8 +63,8 @@ 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 declared module, its `docs/modules/{m}/CLAUDE.md` auto-loads in that subtree — follow it.
 
@@ -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.
 

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

@@ -21,6 +21,10 @@ 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.
@@ -54,7 +58,6 @@ 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
-├── OWNERSHIP_INDEX.md      # Generated: code path → owning feature doc
 ├── architecture/          # Cross-module design + steering layer
 │   │                      #   domain-model, glossary, non-goals, references, open-questions
 │   └── adr/               # Architecture Decision Records (numbered, immutable)
@@ -62,7 +65,7 @@ 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 boundary-mapper
+├── boundaries/            # Typed application boundaries — generated by the boundary skill
 ├── operations/            # Setup, development, deployment, CI/CD
 ├── history/
 │   ├── CHANGELOG.md       # Master changelog index
@@ -75,7 +78,7 @@ docs/
 
 ### 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, ownership index, memory, frontmatter `depends_on`, cross-doc links).
+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)
 
@@ -83,7 +86,7 @@ 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-mapper`) |
+| `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/` |
@@ -99,23 +102,29 @@ Table: `| File | Action | From | To | Reason |` (actions: `Move`, `Merge into {t
 
 Create the folder structure; move/fold/merge/delete per the plan; add `Status:` to plan files; add ownership frontmatter to feature docs (call the `documentation` skill's **frontmatter derivation** for `owns`/`touches`/`depends_on`); merge scattered backlogs into `docs/history/backlog.md`; fix links broken by moves. Scaffold missing mandated files **by calling the `documentation` skill for each template** — you orchestrate, the skill supplies templates:
 
-- `docs/README.md`, `docs/structure.md` (with `harness-version`), `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/index.md`, `docs/memory/main.md`, `docs/OWNERSHIP_INDEX.md`, and the repo-root `README.md` (filled from the real lockfile/scripts/layout — **never overwrite an existing root README**).
+- `docs/README.md`, `docs/structure.md` (with `harness-version`), `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/index.md`, `docs/memory/main.md`, 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 — Seed modules from boundaries, then run boundary-mapper
+### 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:
 
-Invoke **`boundary-mapper`** to populate `docs/boundaries/` (it detects the stack + IA). Then **propose modules from the boundaries** — modules are *declared*, never inferred from physical layout:
+- **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).
 
-- 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; `OWNERSHIP_INDEX.md` rows match frontmatter on disk; no dissolved-version artifacts remain; no docs outside the canonical structure.
+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.
 
 ---
 
@@ -134,7 +143,8 @@ Conformance, not fidelity. Report a table; fix nothing destructively without ask
 - **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; the `documentation` skill supplies templates.** It is a library — you never expect it to baseline.
+- **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.

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