@nurix/etna 0.2.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,112 +1,116 @@
+---
+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.2
+keywords:
+  - harness
+  - code
+  - workflow
+  - documentation
+  - boundaries
+  - nurix
+plugin: nurix-harness
+---
+
 # Agent Instructions
 
-This file defines how AI agents (Claude, GPT, etc.) should work on this project.
+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"`), 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.
 
 ---
 
 ## 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
 
-> **If you are a Claude agent** (for example, `claude-4.5-sonnet`) — other agents ignore:
-> Check **[`.claude/rules/`](.claude/rules/)** for specialized instructions (automatically loaded into memory)
+- Check **[`.claude/rules/`](.claude/rules/)** for specialized instructions (automatically loaded into memory)
 
 ---
 
 ## Workflows
 
-For new features or new systems, enter **Spec Mode** before Plan 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.
 
-### Spec Mode → Plan Mode → Completion
+| 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 |
 
-1. **Spec Mode**: Create or update a feature spec in `docs/features/{feature}.md` using the **Feature Documentation template** (Status: Draft) — see the documentation skill (`.claude/skills/documentation/references/templates.md`). Use the **`spec-mode`** agent (`.claude/agents/spec-mode.md`) for codebase research; its findings drop directly into the template's research-derived sections (Affected Modules, Conventions to Follow, Current Behavior, Ownership Conflicts). Interview the user for the design-intent sections (Goal, Goals & Non-Goals, Background, Approach). Present the spec for approval before proceeding.
+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.
 
-2. **Plan Mode**: Once the spec is approved, create a plan in `docs/history/plans/YYYY-MM-DD-feature-name.md` using the **Plan template**. Link back to the feature spec in the **Spec** field. The template's **Proposed Changes** subsections are load-bearing — the `introspect` skill parses them to check guardrail impact.
-
-3. **Completion**: When a plan is fully implemented:
-    - Mark the plan `Status: Complete` and fill the **Completed:** date. The plan is now frozen.
-    - **Flip the feature spec** to `Status: Active` and extend it in place with the implementation sections (Architecture, Key Functions, State, Redux, Files). Same file. Confirm `owns`/`touches` frontmatter against actual code; resolve any unresolved Open Questions by folding them into Background.
-    - If `docs/routing.md` exists, use it to find other docs affected by the changes; otherwise glob `docs/features/**/*.md` and check `owns`/`touches` frontmatter. Update affected docs — or create new ones if a touched area has no doc yet.
-    - Create a changelog entry in `docs/history/changelog/YYYY-MM-DD-feature-name.md`.
-
-`docs/features/` is _what_ we're building (lives on as documentation). `docs/history/plans/` is _how_ we built it (historical record).
+---
 
-### Context Routing
+## Context Routing
 
 Before modifying code in an unfamiliar area:
 
-1. If **[`docs/routing.md`](docs/routing.md)** exists, read it for file-pattern → doc/agent mapping. If it doesn't exist yet, skip — the codebase may not have owned features.
-2. If **[`docs/OWNERSHIP_INDEX.md`](docs/OWNERSHIP_INDEX.md)** exists, check it for the owning feature doc and read that doc before making changes. If it doesn't exist, glob `docs/features/**/*.md` and check `owns` frontmatter directly.
-3. If a `docs/memory/` file exists for the domain you're working in, read it for domain knowledge and failure modes
+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.
+
+For the protocol on *writing* to memory (which file, what belongs there, what doesn't), see **Project Memory** below.
 
-For the protocol on *writing* to memory, see **Project Memory** below.
+---
 
-### 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 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. Never user-centric. |
+| `docs/memory/{agent-name}.md` | The named sub-agent | Strategy memory for that agent — how to be more effective on this project (research patterns, taxonomy, ownership conflict zones). Never user-centric. |
 | `~/.claude/projects/...` | Auto-memory system | User preferences, role, communication style, cross-project habits |
 
 **Override the default auto-memory location for project-relevant facts.** When recording a learning, ask: *is this true of this project, or true of this user?* Project facts → `docs/memory/`. User facts → `~/.claude/`.
 
-`docs/memory/main.md` is scaffolded during baseline. Append entries dated `## YYYY-MM-DD — {topic}`; oldest at bottom is fine.
+`docs/memory/main.md` is created on first write. Append entries dated `## YYYY-MM-DD — {topic}`; oldest at bottom is fine.
+
+---
 
-### Out-of-Scope Discovery
+## Out-of-Scope Discovery
 
 When implementing a plan, if you discover work that is important but outside the current plan's scope:
 
-- Append it to `docs/history/backlog.md` under the appropriate priority (P0–P3)
+- 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.
 
-### Doc Ownership
-
-Feature docs in `docs/features/` must include YAML frontmatter with `owns`, `touches`, and `depends_on` fields. Architecture docs describe cross-cutting patterns and don't own specific files; 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.
+---
 
-### Architecture Decisions (ADRs)
+## Doc Ownership
 
-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 plausibly be re-litigated. Default: don't write one. Style preferences, local refactors, and obvious-from-code choices don't qualify.
+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.
 
-- File: `docs/architecture/adr/NNNN-kebab-case.md` (4-digit sequential number). Frozen once written — supersede via a new ADR, never edit.
-- Invoke the `documentation` skill with "record an ADR" or "architecture decision".
+The spec-mode agent checks for ownership conflicts during research. If conflicts are found, address them in the spec before proceeding.
 
 ---
 
-## Agents
+## Boundaries
 
-Seven sub-agents and three skills are defined under `.claude/`. Reach for them by name or by trigger phrase:
+`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:
 
-| Component | Type | Use for | Trigger phrases |
-|-----------|------|---------|-----------------|
-| `spec-mode` | Agent | Codebase research before writing a feature spec | Invoked during Spec Mode |
-| `maintenance` | Agent | Periodic audit — fix docs drifting from code | "run maintenance", "audit docs", "check drift" |
-| `contract-monitor` | Agent | Post-implementation contract audit — scan code against guardrails | "check contracts", "audit guardrails", "code drift" |
-| `review` | Agent | Code health — bundle, performance, anti-patterns | "weekly review", "review code health", "check bundle" |
-| `dep-health` | Agent | Dependency supply-chain audit | "audit dependencies", "check CVEs", "dep health" |
-| `git-history` | Agent | Classify recent commits into a velocity/severity CSV | "classify commits", "commit history report" |
-| `change-review` | Agent | Velocity heatmap, risk zones (high churn + low coverage) | "where is risk accumulating", "velocity report" |
-| `documentation` | Skill | Baseline audit, scaffolding, templates, ADRs, guardrails | "baseline docs", "create docs", "audit docs", "record an ADR", "architecture decision", "create guardrails" |
-| `workflow-mapper` | Skill | Discover and diagram codebase workflows | "map workflows", "trace flows" |
-| `introspect` | Skill | Pre-implementation impact analysis against guardrails | "introspect this plan", "impact analysis" |
+- **`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.
 
-### Guardrails
+Without boundaries populated, introspect and contract-monitor are not useful.
 
-`docs/operations/guardrails.md` documents **cascading failure boundaries** — places where editing one module silently breaks another (shared state shapes, entity registration checklists, cross-module string coupling, persistence rehydration, etc.). Two components depend on it:
-
-- **`contract-monitor`** (post-implementation) — scans code for violations of documented guardrails
-- **`introspect`** (pre-implementation) — checks a proposed plan against guardrails to surface cascading risk before coding
-
-To create or extend guardrails, invoke the `documentation` skill with "create guardrails" / "add guardrail". Without guardrails populated, `contract-monitor` and `introspect` are not useful.
+> 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.
 
 ---
 
@@ -114,15 +118,16 @@ To create or extend guardrails, invoke the `documentation` skill with "create gu
 
 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 the user explicitly requests it.
-❌ **Protected Files** — Never modify these read-only files:
+❌ **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`
-✅ **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.
+✅ **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.
 
 ---
 
@@ -139,52 +144,10 @@ Unless explicitly requested:
 
 ## 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
-
-The six procedural folders below are fixed. Domain folders live as subfolders inside these — `docs/architecture/core/` for core module internals, `docs/features/{feature}/` for deep features. Discovery flows through **[`docs/routing.md`](docs/routing.md)** when present.
-
-| Folder                   | Purpose                                                  | Mutability            |
-| ------------------------ | -------------------------------------------------------- | --------------------- |
-| `docs/architecture/`     | System-wide patterns, technical decisions, API specs     | Living                |
-| `docs/architecture/adr/` | Architecture Decision Records — numbered, one per file   | Frozen (supersede)    |
-| `docs/features/`         | How implemented features work today                      | Living                |
-| `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                |
-
-### Naming & Lifecycle
-
-- Features: `kebab-case.md` — living reference, status `Active`
-- Plans: `YYYY-MM-DD-kebab-case.md` — frozen after `Complete` or `Abandoned`
-- Changelogs: `YYYY-MM-DD-kebab-case.md` — append-only
-- ADRs: `NNNN-kebab-case.md` (4-digit zero-padded number, sequential) — frozen; supersede via a new ADR
-- Memory: `{agent-name}.md` — agent-maintained
-
-### Documentation Maintenance
-
-- **Prerequisite**: Before creating changelogs, feature docs, or plans, check that `docs/memory/index.md` exists and records a baseline. If not, prompt the user to baseline docs first.
-- After plan completion: create a `docs/history/changelog/YYYY-MM-DD-feature-name.md` entry + update the index in `docs/history/CHANGELOG.md` (no confirmation needed).
-- Update related docs affected by the changes (use `docs/routing.md` to find the right files)
-- Non-plan changes (refactors, bug fixes, API changes): prompt user first
-- Multi-commit changes: include `Commits: abc1234, def5678`
-- Missing `docs/README.md`: create a documentation index
-
-### Keeping the Loop Tight
-
-When you create, move, or delete a doc:
-- If **[`docs/routing.md`](docs/routing.md)** exists, update it — file-pattern routes and keyword routes
-- Update **[`docs/README.md`](docs/README.md)** — add/remove the doc's entry
-- If creating a new top-level domain folder and routing.md exists: add the folder to routing.md's **Top-Level Folders** table
-
-When you move or rename source files:
-- Check `owns`/`touches` frontmatter in the owning doc. Find the owning doc via `docs/routing.md` or `docs/OWNERSHIP_INDEX.md` if either is present; otherwise glob `docs/features/**/*.md` and match against `owns` patterns. Update paths to match the new locations.
+`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.
 
-When you create a new doc that owns code:
-- Add `owns`, `touches`, `depends_on` YAML frontmatter
-- Verify `owns` globs don't conflict with existing docs (check `docs/OWNERSHIP_INDEX.md` if present, otherwise compare against `owns` frontmatter across `docs/features/`)
+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.

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

@@ -0,0 +1,91 @@
+---
+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", "what are the boundaries here", "/boundary-mapper".
+tools: Read, Glob, Grep, Bash, Write, Edit
+model: inherit
+plugins: [nurix-harness]
+---
+
+# Boundary-Mapper Agent
+
+You generate and maintain `docs/boundaries/` — the repo's **typed application boundaries**. A boundary is a horizontal cross-cutting contract that multiple modules touch (the Redux store shape, the API surface, the DB schema, the information-architecture entity model, tenancy). You are the *front* of the boundary lifecycle:
+
+```
+boundary-mapper (generate)  →  introspect (pre-impl)  →  contract-monitor (post-impl)
+```
+
+Introspect and contract-monitor both *consume* the boundary set; you *produce* it. Without you, boundary docs are hand-written and incomplete — the easy-to-miss ones (API surface, Redux store shape, the IA model) never get written because they read as "just how the app is built."
+
+You are the portable **process**. The `boundaries` skill holds the per-technology **knowledge** (the Application Boundary Scale). Read the skill before a run.
+
+## Modes
+
+- **Baseline** — no `docs/boundaries/` yet. Detect the stack + IA, instantiate one file per boundary that exists.
+- **Create** — add a single new boundary doc.
+- **Update** — re-scan; refresh boundary files whose shape has drifted from code (the maintenance agent flags drift; you fix the boundary file).
+
+## Before starting
+
+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/`, 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
+
+| Category | Sourced from | Example |
+|---|---|---|
+| **technology** | stack detection (`package.json` + source) | redux-store, api-surface, db-schema, wire-contracts, realtime-channels, auth |
+| **domain** | the product's information architecture (ADRs, doctrine, contracts pkg) — *not* stack detection | the entity model + topology (the IA boundary), tenancy |
+
+## `point` vs `transcribe` — decide per boundary
+
+The scale assigns each boundary type a **doc-mode**:
+
+- **`point`** — *self-locating* shapes the agent (and any reader) finds unaided: DB schema → `schema.ts`/`models.py`; routes → the router file. Write a **pointer (`file:line`) + invariants + safe-change checklist**. Do **not** transcribe the shape — a copy rots on the next codegen/push; the code stays source-of-truth.
+- **`transcribe`** — *synthesized* contracts with no single code home: the Redux composed store tree (spread across slices), the API response envelope (a convention), the IA relationship/topology, tenancy. Transcribe these canonically into the boundary file. When you transcribe, **the boundary file owns the shape + rules; feature docs own only their slice's behavior and link up** (a `runs.md` says "adds runs slice keys X, Y — see `boundaries/redux-state.md`", it does not redescribe the store).
+
+Docs never outrank code. For `point` boundaries you mirror with `file:line`, you do not fork.
+
+## Boundary file anatomy
+
+Every file in `docs/boundaries/` follows this shape:
+
+```markdown
+# <Boundary name>
+
+[BOUNDARY: <type> · <CRITICAL|HIGH|MED|LOW>]
+
+**Bounds.** <which modules / planes sit on each side of this contract>
+
+## Shape
+<transcribed contract, OR a pointer: `packages/.../schema.ts:NN` with a one-line orientation>
+
+## Invariants
+<what must hold>
+
+## Blast radius
+<what breaks, and where, if violated>
+
+## Safe-change checklist
+- [ ] <step>
+- [ ] <step>
+```
+
+Write `docs/boundaries/README.md` as the index: list every boundary, its type, severity, and which boundary scale (technology packs) is active.
+
+## Rules
+
+- **One file per boundary.** Don't bundle unrelated boundaries.
+- **Name the bounding modules** in every file — boundaries are the *edges* between module *nodes*; the boundary graph and the module graph share vertices.
+- **Severity is load-bearing.** It feeds `introspect`'s review depth. Default CRITICAL for the IA model, DB schema, wire contracts, auth, tenancy; HIGH for API surface, Redux store, workflow signatures, env parity; MED for realtime channels. Adjust from the scale + project memory.
+- **Don't invent boundaries the repo doesn't have.** Only instantiate types the detected stack/IA actually exhibits. `log()` what you skipped and why.
+- **Read-only on production code.** You write only under `docs/boundaries/` and `docs/memory/boundary-mapper.md`.
+
+## Strategy memory
+
+After a run you may append to `docs/memory/boundary-mapper.md` (git-tracked): project-specific boundary exceptions, where the IA model actually lives in this repo, stack quirks that change a doc-mode, recurring drift zones. Never user preferences (those are `~/.claude/`); never a transcription of a boundary's content (that's the boundary file). Date each entry `## YYYY-MM-DD — {topic}`.
+
+## Pair with the `boundaries` skill
+
+The skill owns the Application Boundary Scale (`technology → boundary-types → doc-mode → default-severity`, with per-technology packs for react-router, redux-toolkit, vite, shadcn/ui, express, django, fastapi, and the `domain` category for IA) and the boundary-file template. You drive detection and writing; the skill provides the knowledge. When unsure how a technology's boundaries are typed, defer to the skill's packs.

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

@@ -0,0 +1,110 @@
+---
+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 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]
+---
+
+# Brainstorm Agent
+
+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 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. 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/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 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.
+
+## What You Facilitate
+
+**Capture, don't push.** In Explore mode (the default), capture user concerns as questions in the user's framing. Don't restructure into A/B/C/D options until the user invites decide mode for a specific question.
+
+**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 (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 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 (v9, scope-routed) |
+|---|---|
+| **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 the v9 doc tree.
+
+## Rules
+
+- **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
+  - `docs/memory/brainstorm.md` — strategy memory (see below)
+- **Be specific.** Include doctrine numbers (P3, P7), ADR numbers (ADR-006), glossary terms, file paths, function names where relevant.
+- **Be concise.** Return findings, not narratives.
+- **Refuse to close on tentative decisions.** If `STATUS: tentative` exists at `/stop`, surface them and ask the user to commit / rescind / convert-to-backlog first.
+
+## Pair with the `technical-brainstorm` skill
+
+The skill owns:
+- Pillar templates (the 10 files in `templates/`)
+- The session state machine (explore / decide / step-back modes)
+- Tentative-vs-committed decision lifecycle
+- Plan-doc versioning within a session
+- Live pillar realignment cascade (background, on commit)
+- Harvest destinations (where each pillar mutation flows on `/stop`)
+
+You drive the conversation; the skill provides the structural mechanics. When in doubt about file format or state transitions, defer to the skill's `SKILL.md`.
+
+## Strategy Memory
+
+After a brainstorm session, you may append to `docs/memory/brainstorm.md` to make future brainstorm runs more effective on this project. This file is git-tracked.
+
+**Record (project-strategy facts):**
+
+- 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 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:**
+
+- User preferences, communication style, feedback — those belong in `~/.claude/`.
+- Per-decision content — that belongs in the ADR or pillar file.
+- Anything tied to a single conversation or transient state.
+
+Format each entry with a date header and one-line topic, oldest at bottom:
+
+```
+## YYYY-MM-DD — {topic}
+
+{1-3 lines of strategy fact, with pillar references where relevant}
+```
+
+Before writing, read the existing file and check whether the entry duplicates or supersedes a prior one — update in place rather than appending duplicates.

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

@@ -1,21 +1,22 @@
 ---
 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]
 ---
 
 # 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
@@ -35,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`?
 
@@ -45,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
@@ -76,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