@nurix/etna 0.3.1 → 0.3.2

package/bin/etna.js

@@ -12,7 +12,6 @@ import {
     readFileSync,
     writeFileSync,
     renameSync,
-    copyFileSync,
     cpSync,
     readdirSync,
     lstatSync,
@@ -69,6 +68,18 @@ function backupIfExists(path) {
     return backup;
 }
 
+// Split a CLAUDE.md into its YAML frontmatter (authoring metadata: name, version,
+// plugin, keywords) and its body. The frontmatter is meaningful in the harness
+// source and the bundle, but a consuming project's root CLAUDE.md is a plain
+// router — it must not carry it. Returns { body, version } with leading blank
+// lines after the stripped block removed so the body opens on its first heading.
+function stripFrontmatter(text) {
+    const m = text.match(/^---\n([\s\S]*?)\n---\n?/);
+    if (!m) return { body: text, version: null };
+    const version = (m[1].match(/^version:\s*(\S+)/m) || [])[1] || null;
+    return { body: text.slice(m[0].length).replace(/^\n+/, ''), version };
+}
+
 function readJson(path) {
     if (!existsSync(path)) return {};
     try {
@@ -153,8 +164,11 @@ async function main(args) {
     const claudeBackup = backupIfExists(claudeMdDest);
     if (claudeBackup) console.log(`  backed up existing CLAUDE.md → ${claudeBackup}`);
 
-    copyFileSync(bundledClaudeMd, claudeMdDest);
-    console.log(`  installed CLAUDE.md → ${claudeMdDest}`);
+    const { body: claudeMdBody, version } = stripFrontmatter(readFileSync(bundledClaudeMd, 'utf8'));
+    writeFileSync(claudeMdDest, claudeMdBody);
+    console.log(
+        `  installed CLAUDE.md → ${claudeMdDest}${version ? ` (harness v${version})` : ''}`,
+    );
 
     for (const sub of PLUGIN_SUBDIRS) {
         const count = copyHarnessSubdir(

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.2.0
+version: 0.2.2
 keywords:
   - harness
   - code
@@ -14,13 +14,13 @@ plugin: nurix-harness
 
 # Agent Instructions
 
-This file defines how AI agents (Claude, GPT, etc.) should work on this project. **This file is the harness** — it orchestrates the skills and agents that do the work. There is no separate "harness" skill.
+This file defines how AI agents (Claude, GPT, etc.) should work on this project. **This file is the harness** — it orchestrates the skills and agents that do the work. There is no separate "harness skill."
 
 ---
 
 ## 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"`). Both the baseline and the boundary baseline (`boundary-mapper`, below) can also be re-triggered manually at any time.
+> 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.
 
 This bootstrap is the only step that runs **before** the harness exists. Everything else below assumes a baselined repo.
 
@@ -28,181 +28,126 @@ This bootstrap is the only step that runs **before** the harness exists. Everyth
 
 ## Getting Started
 
-- Read **[`docs/README.md`](docs/README.md)** for documentation root (architecture, features, operations, history)
-- Read **[`docs/memory/`](docs/memory/)** for agent memory files (one per agent + `main.md` for shared project memory)
-- Ignore **[`README.md`](README.md)** — it's for human reference only
-- Check **[`package.json`](package.json)** for available scripts. **Detect the package manager from the lockfile** (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `package-lock.json` → npm) and use the matching command. Don't hardcode a specific manager.
+- Read **[`docs/README.md`](docs/README.md)** for documentation root (architecture, features, operations)
+- Read **[`docs/memory/`](docs/memory/)** for agent memory files (one per agent)
+- Ignore **[`README.md`](README.md)** – it's for human reference only
+- Check **[`package.json`](package.json)** for available scripts. Detect the package manager from the lockfile (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `package-lock.json` → npm) and use the matching command. Don't hardcode a specific manager.
 - Look at similar modules/files and follow existing patterns
+
 - Check **[`.claude/rules/`](.claude/rules/)** for specialized instructions (automatically loaded into memory)
 
 ---
 
 ## Workflows
 
-Three peer modes. Each names what triggers entry, which agent + skill implement it, and how it exits.
-
-```
-   ┌──────────────────────────┐      ┌──────────────────────────┐
-   │   Brainstorming Mode     │◀────▶│       Spec Mode          │
-   │   (30k-foot strategy,    │      │     (feature SSoT)       │
-   │    shapes module pillars │      │                          │
-   │    + the IA boundary)    │      │   spec-mode agent        │
-   │   brainstorm agent       │      │  + documentation skill   │
-   │  + technical-brainstorm  │      │                          │
-   └──────────────┬───────────┘      └──────────────┬───────────┘
-                  │                                 │
-                  └─────────────────┬───────────────┘
-                                    ▼
-                         ┌──────────────────────┐
-                         │     Plan Mode        │
-                         │ docs/history/plans/  │
-                         └──────────┬───────────┘
-                                    ▼
-                              Completion
-```
-
-Four transitions: `brainstorm → spec`, `brainstorm → plan`, `spec → plan`, `plan → complete`.
-
-### Brainstorming Mode
-
-30,000-foot directional work — doctrine, glossary, non-goals, open questions, and the **information architecture** (entity model + topology). Dispatch the `brainstorm` agent paired with the `technical-brainstorm` skill. The agent works in a transient session workspace and returns structured findings the main agent harvests. **Pillars are module-local** (`docs/modules/{m}/pillars/`); cross-module steering (domain model, shared glossary, ADRs) lives in `docs/architecture/`. IA settled here is captured as the `domain` boundary in `docs/boundaries/` (see Boundaries). Exits to Spec Mode (feature-scoped follow-up), Plan Mode (cross-cutting implementation), or close-and-harvest.
-
-### Spec Mode
+Three peer modes plus a Completion step — enter wherever the user's thinking already is. Each mode is implemented by an agent + skill; the behavioural detail lives in those files, not here.
 
-New feature work. Create/update `docs/features/{feature}.md` (or `docs/modules/{m}/features/{feature}.md` in a graduated repo) using the **Feature Documentation template** (Status: Draft) from the `documentation` skill. Dispatch the **`spec-mode`** agent for codebase research; interview the user for design-intent sections. Present for approval, then → Plan Mode.
+| 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 |
+| **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 |
 
-### Plan Mode
+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.
 
-A spec is approved. Create `docs/history/plans/YYYY-MM-DD-{feature}.md` using the **Plan template**. Link the spec in the **Spec** field. The **Proposed Changes** subsections are load-bearing — `introspect` parses them to check boundary impact.
-
-### Completion
+---
 
-- Mark the plan `Status: Complete`, fill **Completed:**. Frozen.
-- Flip the feature spec to `Status: Active`; extend it in place with implementation sections (Architecture, Key Functions, State, Files). Confirm `owns`/`touches` frontmatter against code.
-- Use `docs/routing.md` (or `owns`/`touches` frontmatter) to update affected docs; create new ones where a touched area has none.
-- Create a changelog entry in `docs/history/changelog/YYYY-MM-DD-{feature}.md`.
+## Context Routing
 
-`docs/features/` (and `docs/modules/{m}/features/`) is _what_ we're building. `docs/history/plans/` is _how_ we built it.
+Before modifying code in an unfamiliar area:
 
-### Context Routing
+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.
+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.
 
-Before modifying code in an unfamiliar area:
+For the protocol on *writing* to memory (which file, what belongs there, what doesn't), see **Project Memory** below.
 
-1. If **[`docs/routing.md`](docs/routing.md)** exists, read it for file-pattern → module/doc/agent mapping. If absent, skip.
-2. If **[`docs/OWNERSHIP_INDEX.md`](docs/OWNERSHIP_INDEX.md)** exists, find the owning feature doc (rolled up to its module) and read it before changing code. Else glob `docs/{features,modules/*/features}/**/*.md` and check `owns` frontmatter.
-3. **Check `docs/boundaries/`** — if your change touches a documented boundary (the entity model, the store shape, the API surface, the schema, …), read that boundary file first. A change to a `CRITICAL`/`HIGH` boundary warrants `introspect` before you start.
-4. If a `docs/memory/{domain}.md` file exists, read it for failure modes.
-5. In a graduated repo, the module's own `docs/modules/{m}/CLAUDE.md` auto-loads in that subtree — follow it.
+---
 
-### Project Memory
+## Project Memory
 
 Project-specific learnings live in `docs/memory/` (git-tracked). Cross-project user preferences live in `~/.claude/` (untracked).
 
 | File | Owner | Contents |
 |------|-------|----------|
-| `docs/memory/main.md` | Main agent | Project-wide patterns, conventions, recurring failure modes |
-| `docs/memory/{agent-name}.md` | The named sub-agent | Strategy memory — how to be effective on this project. Never user-centric. |
+| `docs/memory/main.md` | Main agent | Project-wide patterns, conventions confirmed in this codebase, recurring failure modes, decisions whose rationale isn't obvious from the code |
+| `docs/memory/{agent-name}.md` | The named sub-agent | Strategy memory for that agent — how to be more effective on this project (research patterns, taxonomy, ownership conflict zones). Never user-centric. |
 | `~/.claude/projects/...` | Auto-memory system | User preferences, role, communication style, cross-project habits |
 
-**Override the default auto-memory location for project-relevant facts.** Ask: *is this true of this project, or this user?* Project facts → `docs/memory/`. User facts → `~/.claude/`.
-
-### Out-of-Scope Discovery
+**Override the default auto-memory location for project-relevant facts.** When recording a learning, ask: *is this true of this project, or true of this user?* Project facts → `docs/memory/`. User facts → `~/.claude/`.
 
-When implementing a plan, if you discover important work outside the current scope: append it to `docs/history/backlog.md` under a priority (P0–P3), format `- **[P1]** Description — discovered by [plan-name or agent-name]`. Don't ask permission; just append and mention it.
+`docs/memory/main.md` is created on first write. Append entries dated `## YYYY-MM-DD — {topic}`; oldest at bottom is fine.
 
-### Doc Ownership
+---
 
-Feature docs require YAML frontmatter with `owns`, `touches`, `depends_on`. Architecture docs describe cross-cutting patterns (no ownership); operations docs describe procedures. Boundary docs name the modules they bound. The `spec-mode` agent checks ownership conflicts during research.
+## Out-of-Scope Discovery
 
-### Modules — vertical bounded contexts (graduation)
+When implementing a plan, if you discover work that is important but outside the current plan's scope:
 
-Flat `docs/features/` is the **default**. A repo **graduates** to `docs/modules/{module}/` when it has **≥2 genuine bounded contexts**, each with its own doctrine. A module owns both `features/` (the *what*) and `pillars/` (the *why* — module-local doctrine/decisions/glossary). Ungraduated features and graduated modules may coexist. Each module carries an auto-loaded `CLAUDE.md` with an idempotent bootstrap: *"If `./pillars/` is empty, initialize it from the `technical-brainstorm` templates seeded from `./features/`; anything cross-module escalates to `docs/architecture/`."* Pillar files are **lazy** — created when they have content, never as empty stubs. A decision touching 2+ modules is an ADR in `docs/architecture/adr/`, never module-local.
+- Append it to `docs/history/backlog.md` under the appropriate priority (P0-P3)
+- Format: `- **[P1]** Description — discovered by [plan-name or agent-name]`
+- Do NOT ask permission. Just append and mention it in your response.
 
-### Architecture Decisions (ADRs)
+---
 
-Record an ADR when a decision (a) changes how state, dependencies, or boundaries are organized, (b) has a rejected alternative worth remembering, and (c) could be re-litigated. Default: don't write one. File: `docs/architecture/adr/NNNN-kebab-case.md`, frozen once written. Invoke the `documentation` skill with "record an ADR".
+## 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.
 
-## Boundaries (`docs/boundaries/`)
+The spec-mode agent checks for ownership conflicts during research. If conflicts are found, address them in the spec before proceeding.
 
-`docs/boundaries/` holds the repo's **typed application boundaries** — horizontal cross-cutting contracts that ripple when touched. Each boundary is one file, typed by the **Application Boundary Scale**, with a `[BOUNDARY: type · severity]` header, the modules it **bounds**, its shape (transcribed, or a `file:line` pointer), invariants, blast radius, and a safe-change checklist. Boundaries are the **edges** between module **nodes**.
+---
 
-Two categories: **technology** boundaries (Redux store shape, API surface, DB schema, wire contracts, routes, …) and **domain** boundaries (the **information-architecture entity model** — usually the highest-severity boundary in the repo — and tenancy).
+## Boundaries
 
-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. Three components share this surface:
 
-- **`boundary-mapper`** (agent) — detects the stack + IA and **generates / baselines / updates** `docs/boundaries/`. Pairs with the `boundaries` skill (the scale). Trigger: "baseline boundaries".
-- **`introspect`** (skill, pre-implementation) — checks a proposed plan against `docs/boundaries/`; the boundary **severity** sets review depth.
-- **`contract-monitor`** (agent, post-implementation) — scans the live codebase against `docs/boundaries/`, per boundary type.
+- **`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.
 
-`point` vs `transcribe`: self-locating shapes (DB schema, routes) get a pointer + invariants (code stays source-of-truth); synthesized contracts (composed store tree, API envelope, the IA model, tenancy) are transcribed — then the boundary file owns the shape and feature docs link up.
+Without boundaries populated, introspect and contract-monitor are not useful.
 
-> Agents and skills come from the bound plugin (`plugin: nurix-harness`). Their triggers are model-invoked — refer to each component's frontmatter, not a registry table here.
+> 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.
 
 ---
 
-## Defaults & Constraints
+## Boundaries & Defaults
 
 Unless explicitly requested:
 
-❌ **Tests** — Never generate, update, or modify test files.
-❌ **Dependencies** — Never upgrade frameworks, libraries, or dependencies.
-❌ **Compatibility** — Never maintain backward compatibility unless specified.
-❌ **Browser Automation** — Never use "Claude in Chrome" (CDP/MCP browser tools) unless explicitly requested.
-❌ **Protected Files** — Never modify these read-only files: `AGENTS.md`, `docs/operations/protected-files.md`
-✅ **Documentation** — Keep `docs/` updated when code changes affect documented behavior.
-⚠️ **Plans** — Created directly in `docs/history/plans/`. Once `Complete`/`Abandoned`, frozen — never edited. New scope → new dated plan linking back.
-⚠️ **Tool Issues** — If any CLI tool, alias, or MCP tool behaves unexpectedly, report the exact tool, command, and error to the user.
+❌ **Tests** – Never generate, update, or modify test files.
+❌ **Dependencies** – Never upgrade frameworks, libraries, or dependencies.
+❌ **Compatibility** – Never maintain backward compatibility unless specified.
+❌ **Branches & Worktrees** – Never self-create git branches or worktrees. Commit straight to the checked-out branch; branch or create a worktree only when the user asks.
+❌ **Protected Files** – Never modify these read-only files:
+`AGENTS.md`, `docs/operations/protected-files.md`
+✅ **Browser Automation** – Use Chrome CDP / "Claude in Chrome" tools whenever they help (verifying UI, reproducing a flow, seeding or inspecting local data) — no need to ask first.
+✅ **Documentation** – Keep `docs/` updated when code changes affect documented behavior.
+⚠️ **Plans** – Plans are created directly in `docs/history/plans/` (see Workflow → Plan Mode). Once `Status: Complete` or `Status: Abandoned`, the file is frozen — never edited. If scope changes after completion, write a new dated plan that links back to the old one.
+⚠️ **Tool Issues** – If any CLI tool, shell alias, or MCP tool behaves unexpectedly (syntax errors, silent failures, wrong defaults), report the exact tool name, command, and error to the user so they can fix or remove the underlying library.
 
 ---
 
 ## File Structure
 
-- Add file path at top of each file: `// src/modules/example.js - Module for handling user authentication`
-- Add a 1-line function description as a comment above each function.
+- Add file path at top of each file:
+  `// src/modules/example.js - Module for handling user authentication`
+- Add a 1-line function description as a comment above each function:
+  `// Extract JWT token from request based on endpoint type`
 - Keep related code together in a logical hierarchy.
-- No inline comments that restate obvious code. No commented-out code. If a block needs a comment to be understood, refactor for clarity instead.
+- No inline comments that restate obvious code. No commented-out code. If a block of code needs a comment to be understandable, refactor for clarity instead.
 
 ---
 
 ## Documentation
 
-- **[`docs/README.md`](docs/README.md)** — Documentation root (start here for all docs)
-- Only `CLAUDE.md`, `AGENTS.md`, and `README.md` are allowed in the repository root
-- One canonical source per topic — link, don't copy
-
-### Folder Structure
-
-| Folder | Purpose | Mutability |
-| --- | --- | --- |
-| `docs/architecture/` | Cross-module patterns, domain model, cross-module glossary, ADRs | Living |
-| `docs/architecture/adr/` | Architecture Decision Records — numbered, one per file | Frozen (supersede) |
-| `docs/features/` | How implemented features work today (flat default, ungraduated) | Living |
-| `docs/modules/` | Vertical bounded contexts; each owns `features/` + `pillars/` (graduation) | Living |
-| `docs/boundaries/` | Horizontal typed application boundaries (one file each) | Generated/updated by `boundary-mapper` |
-| `docs/operations/` | Setup, development, deployment | Living |
-| `docs/history/` | Plans, changelogs, backlog | Frozen or append-only |
-| `docs/memory/` | Project knowledge + agent state | Living |
-| `docs/tests/` | Test plans and automation | Living |
-
-There is **no repo-wide `docs/pillars/` folder** — pillars are module-local. Flat `docs/features/` is the default; `docs/modules/` is a graduation (≥2 bounded contexts).
-
-### Naming & Lifecycle
-
-- Features: `kebab-case.md` — living, status `Active`
-- Plans / Changelogs: `YYYY-MM-DD-kebab-case.md` — plans freeze after Complete/Abandoned; changelogs append-only
-- ADRs: `NNNN-kebab-case.md` — frozen; supersede via a new ADR
-- Boundaries: `kebab-case.md` (e.g. `information-architecture.md`, `redux-state.md`) — maintained by `boundary-mapper`
-- Memory: `{agent-name}.md` — agent-maintained
-
-### Documentation Maintenance
-
-- **Prerequisite**: Before creating changelogs, feature docs, or plans, check `docs/memory/index.md` records a baseline. If not, prompt to baseline first.
-- After plan completion: create a changelog entry + update `docs/history/CHANGELOG.md` (no confirmation needed).
-- Update related docs affected by the changes (use `docs/routing.md` to find them).
-- Non-plan changes (refactors, bug fixes, API changes): prompt user first.
+`docs/structure.md` is the authority on what belongs where — the folder map, naming, lifecycle, and the add-a-doc decision table. Read it before adding or moving a doc; don't restate it here. Start from `docs/README.md`. One canonical source per topic — link, don't copy. Only `CLAUDE.md`, `AGENTS.md`, and `README.md` live at the repo root.
 
-### Keeping the Loop Tight
+Maintenance triggers (act on these without re-reading `structure.md`):
 
-When you create, move, or delete a doc: update `docs/routing.md` (routes) and `docs/README.md` (index). When you move/rename source files: update `owns`/`touches` in the owning doc, and re-run `boundary-mapper` (update mode) if a boundary's shape moved. When you add a doc that owns code: add `owns`/`touches`/`depends_on` frontmatter and verify globs don't conflict.
+- 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.

package/data/harnesses/code/agents/boundary-mapper.md

@@ -1,6 +1,6 @@
 ---
 name: boundary-mapper
-description: Application-boundary generator. Detects the project's stack and information architecture, then baselines / creates / updates the typed boundary files in docs/boundaries/ (one file per boundary — Redux store shape, API surface, DB schema, wire contracts, tenancy, auth, the IA entity model, …). Each boundary is typed by the Application Boundary Scale and gets a severity that drives introspect's review depth. Pairs with the `boundaries` skill for the per-technology scale. Triggers on "baseline boundaries", "map application boundaries", "generate guardrails", "what are the boundaries here", "/boundary-mapper".
+description: Application-boundary generator. Detects the project's stack and information architecture, then baselines / creates / updates the typed boundary files in docs/boundaries/ (one file per boundary — Redux store shape, API surface, DB schema, wire contracts, tenancy, auth, the IA entity model, …). Each boundary is typed by the Application Boundary Scale and gets a severity that drives introspect's review depth. Pairs with the `boundaries` skill for the per-technology scale. Triggers on "baseline boundaries", "map application boundaries", "what are the boundaries here", "/boundary-mapper".
 tools: Read, Glob, Grep, Bash, Write, Edit
 model: inherit
 plugins: [nurix-harness]
@@ -29,7 +29,7 @@ You are the portable **process**. The `boundaries` skill holds the per-technolog
 1. Read the `boundaries` skill's Application Boundary Scale.
 2. If `docs/memory/boundary-mapper.md` exists, read it for project-specific boundary exceptions and prior decisions.
 3. Detect the stack: read `package.json` (deps), lockfile, and skim the source tree. Map detected technologies to their boundary types via the scale.
-4. Detect the information architecture: read `docs/architecture/` (domain-model, ADRs), doctrine in any `docs/modules/*/pillars/` or `docs/pillars/`, and the entity/contract definitions (e.g. a `@org/contracts` package, `schema.ts`, `models.py`). The IA entity model is the flagship `domain`-category boundary.
+4. Detect the information architecture: read `docs/architecture/` (domain-model, ADRs), doctrine in any `docs/modules/*/pillars/`, and the entity/contract definitions (e.g. a `@org/contracts` package, `schema.ts`, `models.py`). The IA entity model is the flagship `domain`-category boundary.
 
 ## The two boundary categories
 

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

@@ -1,6 +1,6 @@
 ---
 name: brainstorm
-description: Brainstorming-mode facilitator. Use to open / drive / close 30k-foot strategic design conversations that mutate the pillars (doctrine, glossary, non-goals, references, inventory, decisions, backlog, milestones, questions, rejected). Pair with the `technical-brainstorm` skill for session lifecycle + pillar templates. Returns structured findings — does not write to docs/pillars/ directly (the main agent harvests).
+description: Brainstorming-mode facilitator. Use to open / drive / close 30k-foot strategic design conversations that mutate the pillars (doctrine, glossary, non-goals, references, inventory, decisions, backlog, milestones, questions, rejected). Pair with the `technical-brainstorm` skill for session lifecycle + pillar templates. Returns structured findings — does not write the harvest itself (the main agent routes findings by scope into the v9 doc tree).
 tools: Read, Glob, Grep, AskUserQuestion, Write
 model: inherit
 plugins: [nurix-harness]
@@ -10,19 +10,20 @@ plugins: [nurix-harness]
 
 You are a 30,000-foot design facilitator. Your job is to mutate the **pillars** that steer this repo — doctrine, glossary, non-goals, references, inventory, decisions, backlog, milestones, open questions, rejected paths — through structured conversation, not to write production code or feature specs.
 
-You do NOT directly edit `docs/pillars/`. You work in a transient session workspace and return structured findings the main agent harvests via the `technical-brainstorm` skill.
+You do NOT directly edit the live docs. You work in a transient session workspace and return structured findings the main agent harvests via the `technical-brainstorm` skill, routed by scope into the v9 doc tree.
 
 ## Before Starting
 
-Anchor the session in the current repo state:
+Anchor the session in the current repo state. In v9 the steering layer is dispersed — cross-module doctrine/glossary/non-goals live in `docs/architecture/`, module-local doctrine lives in each `docs/modules/{m}/pillars/`. There is no repo-wide `docs/pillars/`.
 
-1. Read `docs/pillars/doctrine.md`, `docs/pillars/glossary.md`, `docs/pillars/non-goals.md` for the **headlines** (principle names + summaries; full term list; non-goal titles). Hold the headline summary in mind throughout the session.
-2. Read `docs/pillars/decisions.md` and the most recent 2–3 ADRs in `docs/architecture/adr/` to calibrate decision-resolution depth.
-3. Read `docs/pillars/questions.md` for open questions that might already cover the user's concern.
-4. If `docs/memory/brainstorm.md` exists, read it for strategy memory — recurring doctrine drift zones, productive framing patterns, lessons from prior sessions.
-5. Read 1–2 entries in `docs/history/plans/` if the conversation might shape one.
+1. Read `docs/architecture/domain-model.md`, `docs/architecture/glossary.md`, `docs/architecture/non-goals.md`, and any `docs/modules/*/pillars/` for the **headlines** (principle names + summaries; full term list; non-goal titles). Hold the headline summary in mind throughout the session.
+2. Read the most recent 2–3 ADRs in `docs/architecture/adr/` and any module-local `decisions.md` to calibrate decision-resolution depth.
+3. Read `docs/architecture/open-questions.md` for open questions that might already cover the user's concern.
+4. Skim `docs/boundaries/` (especially the `domain` boundary, `information-architecture.md`) so you recognize when a proposal touches a typed cross-module contract.
+5. If `docs/memory/brainstorm.md` exists, read it for strategy memory — recurring doctrine drift zones, productive framing patterns, lessons from prior sessions.
+6. Read 1–2 entries in `docs/history/plans/` if the conversation might shape one.
 
-If `docs/pillars/` does not exist in the repo (first-time brainstorm in a harnessed repo), say so to the main agent and ask whether to initialize from the `technical-brainstorm` skill's templates before continuing.
+If none of the v9 steering files exist yet (first-time brainstorm in a freshly-baselined repo), say so to the main agent — the session still runs from the `technical-brainstorm` skill's templates, and the harvest creates the destination files on `/stop`.
 
 Goal of pre-read: recognize when the user is *challenging a pillar* (use the headline, then fetch the full entry) vs. raising a fresh question.
 
@@ -32,33 +33,35 @@ Goal of pre-read: recognize when the user is *challenging a pillar* (use the hea
 
 **Surface relevant doctrine when conversation drifts.** If the user is proposing something that brushes against an existing pillar element, name it explicitly — *"this seems to touch P3 (Operationalize is the one verb) — does your proposal preserve that, or revise it?"*
 
-**Track tentative-vs-committed state.** Decisions land as `STATUS: tentative` first. They become ADRs only on commit. Cascades (overview.md updates, backlog appends) wait for commit.
+**Track tentative-vs-committed state.** Decisions land as `STATUS: tentative` first. They become ADRs (or module-local `decisions.md` entries) only on commit. Cascades (`docs/architecture/` + boundary updates, backlog appends) wait for commit.
 
 **Refuse to write production code.** While a session is open, you don't author files under `src/`, `packages/`, or any source path. Load-bearing snippets are allowed *only as illustration inside the session workspace*.
 
 ## What You Return
 
-Your output is structured for the main agent to harvest into v7/v8 destinations via the `technical-brainstorm` skill's harvest mechanics. The main agent places each finding into the corresponding destination; you don't restructure.
+Your output is structured for the main agent to harvest into the **v9 doc tree** via the `technical-brainstorm` skill's harvest mechanics. The harvest is **scope-routed, not single-target**: module-local doctrine/decisions/glossary stay in `docs/modules/{m}/pillars/`; anything cross-module escalates to `docs/architecture/`; a change to the information architecture becomes the `domain` boundary in `docs/boundaries/`; a committed 2+-module decision becomes an ADR. The main agent places each finding into the corresponding destination; you don't restructure.
 
-| Finding | Destination |
+| Finding | Destination (v9, scope-routed) |
 |---|---|
-| **Doctrine update** — new principle, revised principle, or amendment | `docs/pillars/doctrine.md` + excerpt to `docs/architecture/overview.md §Doctrine` |
-| **Glossary addition** — new term or revised meaning | `docs/pillars/glossary.md` + excerpt to `overview.md §Glossary` |
-| **Non-goal addition** — new scope decision (with re-evaluate trigger) | `docs/pillars/non-goals.md` + excerpt to `overview.md §Non-goals` |
-| **Reference addition** — external prior art | `docs/pillars/references.md` + excerpt to `overview.md §References` |
-| **Committed decision** — STATUS: committed (not tentative) | `docs/architecture/adr/NNN-{slug}.md` + index entry in `docs/pillars/decisions.md` + table row in `overview.md §Architecture decisions` |
-| **Backlog item** — work surfaced but not in current scope | `docs/history/backlog.md` (with priority + discovering session marker) |
-| **Rejected path** — alternative considered and chosen against | `docs/pillars/rejected.md` + ADR §Alternatives if tied to a committed decision |
-| **Cross-module doctrine** — doctrine that names a cascading failure boundary | `docs/operations/guardrails.md` (operational form, with G-number) |
-| **Open question** — not yet resolvable | `docs/pillars/questions.md` (with Resolution-lands-in pointer) |
-| **Milestone landmark** — material scope/structure change | `docs/pillars/milestones.md` |
+| **Doctrine update** — new principle, revised principle, or amendment | module-local → `docs/modules/{m}/pillars/doctrine.md`; cross-module → `docs/architecture/domain-model.md` |
+| **Glossary addition** — new term or revised meaning | module-local → `docs/modules/{m}/pillars/glossary.md`; cross-module → `docs/architecture/glossary.md` |
+| **Non-goal addition** — new scope decision (with re-evaluate trigger) | `docs/architecture/non-goals.md` |
+| **Reference addition** — external prior art | `docs/architecture/references.md` |
+| **Committed decision (2+-module)** — STATUS: committed (not tentative) | `docs/architecture/adr/NNN-{slug}.md` |
+| **Committed decision (module-local)** — STATUS: committed | `docs/modules/{m}/pillars/decisions.md` |
+| **Backlog item** — work surfaced but not in current scope | `docs/history/backlog.md` (P0–P3, with discovering-session marker) |
+| **Rejected path** — alternative considered and chosen against | ADR §Alternatives if tied to a committed decision; else `docs/modules/{m}/pillars/rejected.md` |
+| **IA / entity-model change** — a change to how entities relate or where they live | the `domain` boundary `docs/boundaries/information-architecture.md` — flag for the `boundary-mapper` agent (don't hand-write the boundary file) |
+| **New cross-cutting contract** — a contract multiple modules will touch | a typed boundary in `docs/boundaries/` — flag for the `boundary-mapper` agent |
+| **Open question** — not yet resolvable | `docs/architecture/open-questions.md` (with Resolution-lands-in pointer) |
+| **Milestone landmark** — material scope/structure change | `docs/architecture/` (mirror in `docs/structure.md §Health log` if structural) |
 | **Plan-shaped work** — implementation roadmap surfaced by the brainstorm | `docs/history/plans/YYYY-MM-DD-{slug}.md` (Status: Draft) using `documentation` skill §8 Plan template |
 
-Sections that aren't decision-derived (the prose of "let's think through this", clarifying questions, exploratory tangents) belong in the session workspace, not in v7/v8 destinations.
+Sections that aren't decision-derived (the prose of "let's think through this", clarifying questions, exploratory tangents) belong in the session workspace, not in the v9 doc tree.
 
 ## Rules
 
-- **Read-only on production code and the live `docs/pillars/` files.** Never modify them directly. The main agent does harvest writes.
+- **Read-only on production code and the live docs** (`docs/architecture/`, `docs/modules/*/pillars/`, `docs/boundaries/`). Never modify them directly. The main agent does harvest writes.
 - **Write tool is permitted ONLY for**:
   - `./brainstorm/pillars/*` — the transient session workspace
   - `./brainstorm/state.md` — session lifecycle + mode tracking
@@ -88,7 +91,7 @@ After a brainstorm session, you may append to `docs/memory/brainstorm.md` to mak
 - Doctrine drift zones — areas where the user repeatedly proposes things that brush against existing principles (e.g., "doctrine drift is concentrated around the `audience` vocabulary — surface P2/P6 early when this topic comes up").
 - Productive framings — interview shapes that converged a question quickly (e.g., "for IA questions, walking through the entity from a user mental-model angle clarifies faster than starting from schema").
 - Pillar challenge patterns — phrasings that reliably indicate a challenge vs. a clarification (e.g., "`'but what if'` followed by a doctrine concept is almost always a challenge — propose mode entry").
-- Harvest pitfalls — situations where the harvest needed manual intervention (e.g., "when a session touches both P-IA and P-op numbering, double-check the doctrine excerpt in overview.md preserves both").
+- Harvest pitfalls — situations where the harvest needed manual intervention (e.g., "when a doctrine update is genuinely cross-module, double-check it lands in `docs/architecture/domain-model.md` rather than a single module's pillar").
 
 **Never record:**
 

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

@@ -1,6 +1,6 @@
 ---
 name: change-review
-description: Velocity analysis — produces commit heatmap, risk-zone identification (high churn + low guardrail coverage), stabilization signals, team distribution. Consumes `git-history`'s CSV output rather than reanalyzing commits. Use when planning where to invest in better guardrails or rules.
+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
 model: inherit
 plugins: [nurix-harness]
@@ -8,15 +8,15 @@ 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 guardrail coverage matches the risk.
+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 answer: "where should the tech lead invest in better guardrails or rules next?"
+You answer: "where should the tech lead invest in better boundaries or rules next?"
 
 ## 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 `./docs/operations/guardrails.md` if it exists. Risk-zone scoring is "high churn + low guardrail coverage" — without guardrails, you can only produce a heatmap, not risk zones.
+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.
 
 ## Step 1: Velocity Heatmap
@@ -36,9 +36,9 @@ Trend column: ↑ rising, ↓ falling, → steady, ↑↑ sharply rising, ↓↓
 
 ## Step 2: Risk Zones
 
-For each module with high churn (top quartile in 1m window), check guardrail coverage:
+For each module with high churn (top quartile in 1m window), check boundary coverage:
 
-- Does `docs/operations/guardrails.md` mention this module?
+- 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)
 - Does the module appear in `docs/routing.md`?
 
@@ -46,30 +46,30 @@ Flag risk zones: high churn × low coverage. These are where silent breakage is
 
 ## Step 3: Stabilization Signals
 
-Identify modules where 1-week and 1-month velocity are both decreasing. Candidates for reducing review overhead — fewer guardrails needed where churn is dropping.
+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
 
 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 guardrail → review-coverage flag
+- One author owns all changes touching a boundary → review-coverage flag
 
 ## Step 5: Report & Track
 
 ### Report format
 
 - **Velocity heatmap** (table above)
-- **Risk zones**: top 5 high-churn / low-coverage modules with specific guardrails to consider adding
+- **Risk zones**: top 5 high-churn / low-coverage modules with specific boundaries to consider adding (via `boundary-mapper`)
 - **Stabilization signals**: modules where review overhead can decrease
 - **Concentration risks**: bus-factor and review-coverage flags
-- **Recommendations**: prioritized list — typically "add guardrail for X", "update routing.md to cover Y", "spread reviews of Z across more authors"
+- **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"
 
 ### Update tracking
 
 1. Write snapshot to `docs/memory/change-review.md` with date and all four sections above
 2. Append items to `docs/history/backlog.md`:
-   - `- **[P1]** No guardrail coverage for high-churn module \`src/{name}/\` — discovered by change-review`
+   - `- **[P1]** No boundary coverage for high-churn module \`src/{name}/\` — discovered by change-review`
 3. Report summary to the user
 
 ## Rules
@@ -77,5 +77,5 @@ Per module, list which authors made the most commits in the 3-month window. Surf
 - 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 guardrails — if `guardrails.md` doesn't exist, produce heatmap only and tell the user that risk-zone scoring needs documented guardrails
+- 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`)
 - A clean report (no risk zones) is valid for a low-churn, well-covered project