@nurix/etna 0.3.1 → 0.3.6

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

package/data/harnesses/code/agents/contract-monitor.md

@@ -1,6 +1,6 @@
 ---
 name: contract-monitor
-description: Post-implementation contract auditor. Scans the live codebase for violations of cross-module contracts documented in `docs/operations/guardrails.md` — unregistered entity types, string-coupled constants, cross-entity references without propagation, schema mismatches, undocumented endpoints. Run on request after significant merges. Pairs with the `introspect` skill (which runs pre-implementation).
+description: Post-implementation contract auditor. Scans the live codebase for violations of the typed cross-module boundaries documented in `docs/boundaries/` — unregistered entity types, string-coupled constants, cross-entity references without propagation, schema mismatches, undocumented endpoints. Run on request after significant merges. Pairs with the `introspect` skill (which runs pre-implementation).
 tools: Read, Glob, Grep, Edit, Write, Bash
 model: inherit
 plugins: [nurix-harness]
@@ -12,21 +12,21 @@ You scan the codebase for cross-module contract violations. Where the `introspec
 
 ## Before Starting
 
-1. Read `./docs/operations/guardrails.md` — this is your source of truth for which contracts exist. If it doesn't exist, stop and tell the user a guardrails doc is required.
+1. Read every file in `./docs/boundaries/` — this is your source of truth for which contracts exist. If the folder is missing or empty, stop and tell the user to baseline boundaries first via the `boundary-mapper` agent.
 2. If `./docs/memory/contract-monitor.md` exists, read it for known exceptions, historical violation counts, and patterns the user has chosen not to fix.
 3. If `./docs/routing.md` exists, read it for module ownership context.
 
 ## Scan
 
-For each guardrail section in `guardrails.md`:
+For each boundary file in `docs/boundaries/`:
 
-1. Parse the section — extract contract name, canonical source location, consumer paths, violation description, checklist (if any)
-2. Scan the codebase for violations of that specific contract. Categories to check:
+1. Parse the file — extract the `[BOUNDARY: type · severity]` header, the **Bounds** (modules on each side), the **Shape** (transcribed contract or `file:line` pointer), the **Invariants**, the **Blast radius**, and the **Safe-change checklist**
+2. Scan the codebase for violations of that specific boundary. Categories to check:
    - **Unregistered entity types** — strings used as entity-type identifiers that aren't in the canonical array
    - **String-coupled constants** — raw string literals used where shared constant imports are required
    - **Cross-entity references without propagation** — storing entity A's slug/name/id by value in entity B without documented propagation
    - **Schema mismatches** — selectors accessing persisted fields without fallback defaults
-   - **Undocumented API endpoints** — routes in code with no corresponding feature doc or guardrail entry
+   - **Undocumented API endpoints** — routes in code with no corresponding feature doc or `api`/`wire-contracts` boundary entry
 3. Verify by reading actual source files — never guess.
 
 ## Act
@@ -34,29 +34,29 @@ For each guardrail section in `guardrails.md`:
 For each violation:
 
 - **Mechanical fix** (missing constant import, missing fallback default, missing entry in canonical array) → fix it directly with an Edit
-- **Design-decision fix** (new entity type registration, new cross-entity propagation mechanism, schema migration) → append to `docs/history/backlog.md` as P0 or P1 with the specific guardrail and consumer paths
+- **Design-decision fix** (new entity type registration, new cross-entity propagation mechanism, schema migration) → append to `docs/history/backlog.md` as P0 or P1 with the specific boundary and bounded modules
 - **Pre-existing exception** (recorded in `docs/memory/contract-monitor.md`) → skip silently; don't re-flag
 
 ## Report
 
 Present a structured report:
 
-| # | Guardrail | Violation | Location | Action taken |
-|---|-----------|-----------|----------|--------------|
+| # | Boundary | Violation | Location | Action taken |
+|---|----------|-----------|----------|--------------|
 
 Then update `docs/memory/contract-monitor.md` with:
 - Scan date
-- Violation counts per guardrail
+- Violation counts per boundary
 - Items fixed mechanically (with file paths)
 - Items backlogged (with P-level and rationale)
 - New exceptions added (if any)
 
-## Optional: extend guardrails
+## Optional: suggest a new boundary
 
-If you discover patterns in code that should be guardrails but aren't yet documented:
+If you discover patterns in code that should be a typed boundary but aren't yet documented:
 
-1. Surface the candidate guardrail to the user with a draft entry
-2. Wait for approval before writing to `guardrails.md` — never add a guardrail unilaterally
+1. Surface the candidate boundary to the user with a draft (type, Bounds, Shape, suggested severity)
+2. Recommend running the `boundary-mapper` agent to formalize it — never write to `docs/boundaries/` yourself
 
 ## Rules
 

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

@@ -11,18 +11,18 @@ 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** (contract/guardrail violations in live code) → `contract-monitor` agent
-- **Pre-implementation impact analysis** (checking a plan against guardrails before coding) → `introspect` skill
+- **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
 
 ## Before Starting
 
 1. If `./docs/memory/maintenance.md` exists, read it for last review state, ownership snapshots, high-churn paths, and known failure modes.
-2. If `./docs/operations/guardrails.md` exists, read it for context on cross-module contracts the docs should reflect.
+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 `./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.
+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:
 

package/data/harnesses/code/scripts/build-ownership-index.sh

@@ -4,7 +4,16 @@
 
 set -euo pipefail
 
-REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+# Resolve the repo root from this script's own location — it lives at either
+# <root>/scripts/ (kit source) or <root>/.claude/scripts/ (installed into a
+# project). Strip whichever suffix applies; works regardless of git or cwd,
+# and stays correct when the harness sits in a monorepo subdirectory.
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+case "$SCRIPT_DIR" in
+    */.claude/scripts) REPO_ROOT="${SCRIPT_DIR%/.claude/scripts}" ;;
+    */scripts) REPO_ROOT="${SCRIPT_DIR%/scripts}" ;;
+    *) REPO_ROOT="$(dirname "$SCRIPT_DIR")" ;;
+esac
 OUTPUT="$REPO_ROOT/docs/OWNERSHIP_INDEX.md"
 FEATURES_DIR="$REPO_ROOT/docs/features"
 TMP_OWNS=$(mktemp)
@@ -81,7 +90,7 @@ cat > "$OUTPUT" << 'HEADER'
 # Ownership Index
 
 > **Generated file** — do not edit manually.
-> Regenerate with: `bash scripts/build-ownership-index.sh`
+> Regenerate with the `build-ownership-index.sh` script (the maintenance agent runs it).
 
 Machine-readable lookup table generated from feature doc frontmatter.
 

package/data/harnesses/code/scripts/check-doc-drift.sh

@@ -5,7 +5,16 @@
 set -euo pipefail
 
 DAYS="${1:-14}"
-REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+# Resolve the repo root from this script's own location — it lives at either
+# <root>/scripts/ (kit source) or <root>/.claude/scripts/ (installed into a
+# project). Strip whichever suffix applies; works regardless of git or cwd,
+# and stays correct when the harness sits in a monorepo subdirectory.
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+case "$SCRIPT_DIR" in
+    */.claude/scripts) REPO_ROOT="${SCRIPT_DIR%/.claude/scripts}" ;;
+    */scripts) REPO_ROOT="${SCRIPT_DIR%/scripts}" ;;
+    *) REPO_ROOT="$(dirname "$SCRIPT_DIR")" ;;
+esac
 FEATURES_DIR="$REPO_ROOT/docs/features"
 TMP_OWNS=$(mktemp)
 TMP_STALE=$(mktemp)

package/data/harnesses/code/skills/documentation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: documentation
-description: Create and maintain technical documentation. Use when the user asks to (1) baseline, audit, or reorganize docs — enforces an opinionated 6-folder structure (architecture, features, operations, history, memory, tests) with ownership frontmatter and scaffold files, (2) document a feature or module, (3) create or update a changelog entry, (4) document data flows or Redux state, (5) add to protected files, (6) create or update guardrails (cascading failure boundaries), (7) record an architecture decision (ADR), (8) create or update the project root README, (9) create or update a plan, or (10) co-author any technical doc. Triggers on "document this", "create docs", "update changelog", "baseline docs", "audit docs", "add to protected files", "guardrails", "ADR", "architecture decision", "root README", "plan".
+description: Create and maintain technical documentation. Use when the user asks to (1) baseline, audit, or reorganize docs — enforces the opinionated v9 structure (architecture, features, operations, history, memory; + boundaries/, modules/, tests/ as the repo grows) with ownership frontmatter and scaffold files, (2) document a feature or module, (3) create or update a changelog entry, (4) document data flows or Redux state, (5) add to protected files, (6) provide the generic boundary-file template (typed-boundary *generation* is the `boundary-mapper` agent, not this skill), (7) record an architecture decision (ADR), (8) create or update the project root README, (9) create or update a plan, or (10) co-author any technical doc. Triggers on "document this", "create docs", "update changelog", "baseline docs", "audit docs", "add to protected files", "ADR", "architecture decision", "root README", "plan".
 plugins: [nurix-harness]
 ---
 
@@ -29,7 +29,7 @@ User request
     │
     ├─ "Add to protected files" ───────▶ Protected Files Template
     │
-    ├─ "Create/update guardrails" ─────▶ Guardrails Template
+    ├─ "Create/update a boundary" ─────▶ boundary-mapper agent (this skill holds only the boundary-file template)
     │
     ├─ "Record architecture decision" ─▶ ADR Template
     │
@@ -46,7 +46,7 @@ User request
 
 ## Baseline Audit
 
-When asked to "baseline", "audit", or "review" docs, enforce the canonical 6-folder documentation structure. This is an opinionated reorganization — the target structure is non-negotiable.
+When asked to "baseline", "audit", or "review" docs, enforce the canonical v9 documentation structure. This is an opinionated reorganization — the target structure is non-negotiable.
 
 ### Target Structure
 
@@ -54,24 +54,28 @@ When asked to "baseline", "audit", or "review" docs, enforce the canonical 6-fol
 docs/
 ├── README.md              # Documentation root — quick links table, section index
 ├── structure.md           # Authority map, folder rules, health log
-├── CODEBASE_MAP.md        # Auto-generated directory map (optional)
-├── faq.md                 # Common issues (optional)
-├── architecture/          # System-wide decisions, patterns, technical references
-│   ├── adr/               # Architecture Decision Records (numbered, immutable)
-│   └── core/              # Core module internals (auth, state, routing)
-├── features/              # Living feature specs with ownership frontmatter
+├── routing.md             # File-pattern → module/doc/agent map (scaled — see CLAUDE.md)
+├── OWNERSHIP_INDEX.md      # Generated: code path → owning feature doc
+├── architecture/          # Cross-module design + the steering layer
+│   │                      #   domain-model, glossary, non-goals, references, open-questions
+│   └── adr/               # Architecture Decision Records (numbered, immutable)
+├── features/              # Flat default — feature specs with ownership frontmatter
 │   └── {feature}/         # Subfolder for deep features (e.g., editor/)
+├── modules/               # Graduation (≥2 bounded contexts) — NOT scaffolded at baseline
+│   └── {module}/          #   CLAUDE.md + features/ + pillars/ (module-local doctrine, lazy)
+├── boundaries/            # Typed application boundaries — generated by boundary-mapper
 ├── operations/            # Setup, development, deployment, CI/CD
-│   └── guardrails.md      # Cascading failure boundaries (cross-module contracts)
 ├── history/               # Frozen/append-only records
 │   ├── CHANGELOG.md       # Master changelog index
 │   ├── changelog/         # Individual changelog entries
 │   ├── plans/             # Historical implementation plans (Status field required)
 │   └── backlog.md         # Tracked work items by priority (P0-P3)
-├── memory/                # Agent memory files
+├── memory/                # Agent memory files (index.md = baseline record)
 └── tests/                 # Test plans and automation docs (optional)
 ```
 
+There is **no repo-wide `docs/pillars/`** (dissolved in v9 — pillars are module-local). `docs/boundaries/` is populated by the `boundary-mapper` agent (which the bootstrap runs immediately after this baseline), and `docs/modules/` appears only when the repo graduates to ≥2 bounded contexts — neither is scaffolded here. `docs/tests/` is optional and **author-maintained**: no agent, skill, or script owns it — create it only if test-plan or test-automation docs already exist, and never scaffold it empty.
+
 ### Workflow
 
 **Step 1: Inventory existing docs**
@@ -126,7 +130,6 @@ After approval:
 8. Scaffold standard files if missing:
    - `docs/README.md` — from template (see `references/templates.md`)
    - `docs/structure.md` — from template (see `references/templates.md`)
-   - `docs/operations/guardrails.md` — cascading failure boundaries (see `references/templates.md` for what to include/exclude)
    - `docs/history/CHANGELOG.md` — master changelog index (header + table linking to entries)
    - `docs/history/backlog.md` — work items by priority (P0-P3 sections, empty if nothing to merge)
    - `docs/memory/index.md` — agent memory index (empty scaffold with section headers)
@@ -138,19 +141,19 @@ After approval:
 
 **Step 5: Verify**
 
-1. Confirm all standard files exist: `docs/README.md`, `docs/structure.md`, `docs/operations/guardrails.md`, `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/index.md`, `docs/memory/main.md`, `docs/OWNERSHIP_INDEX.md`, `README.md` (repo root — must exist; either pre-existing untouched or freshly scaffolded)
+1. Confirm all standard files exist: `docs/README.md`, `docs/structure.md`, `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/index.md`, `docs/memory/main.md`, `docs/OWNERSHIP_INDEX.md`, `README.md` (repo root — must exist; either pre-existing untouched or freshly scaffolded). `docs/boundaries/` is the `boundary-mapper` agent's responsibility (the bootstrap runs it right after this baseline), not a scaffold target here.
 2. Confirm no dead links in `docs/README.md`
 3. Confirm every plan file has a `Status:` field
 4. Confirm feature docs have ownership frontmatter
 5. Confirm `docs/OWNERSHIP_INDEX.md` rows match the frontmatter on disk (no orphans, no missing entries)
-6. Confirm no docs remain outside the 6-folder structure (except `README.md`, `structure.md`, `CODEBASE_MAP.md`, `faq.md`)
+6. Confirm no docs remain outside the v9 structure (except the docs-root files `README.md`, `structure.md`, `routing.md`, `OWNERSHIP_INDEX.md`)
 7. Confirm duplicates are eliminated — each topic has one canonical source
 
 ### Rules
 
-- The 6-folder structure is mandatory. No `docs/guides/`, `docs/core/`, `docs/editor/`, `docs/pt/`, or any other top-level folder
+- The v9 structure is mandatory. No `docs/guides/`, `docs/core/`, `docs/editor/`, `docs/pt/`, no repo-wide `docs/pillars/` (dissolved in v9 — pillars are module-local under `docs/modules/{m}/pillars/`), or any other top-level folder beyond the v9 set
 - Guides about how-to-run → `operations/`. Guides about a feature → `features/`
-- Core module docs → `docs/architecture/core/`. Editor module docs → `docs/features/editor/`
+- A genuine bounded context graduates to `docs/modules/{m}/` (owning `features/` + `pillars/`); ungraduated feature docs stay flat under `docs/features/` (deep features may nest, e.g. `docs/features/editor/`)
 - Only `CLAUDE.md`, `AGENTS.md`, and `README.md` are allowed in the repository root (not inside `docs/`)
 - Root-level `README.md` is for humans. `docs/README.md` is the agent/doc entry point
 - One canonical source per topic — link, don't copy
@@ -234,6 +237,6 @@ For docs that don't match templates:
 
 | File | Use For |
 |------|---------|
-| `references/templates.md` | docs/README.md, structure.md, frontmatter, scaffolds (CHANGELOG, backlog, memory, OWNERSHIP_INDEX), guardrails, feature, changelog, plan, protected files, ADR, project root README templates |
+| `references/templates.md` | docs/README.md, structure.md, frontmatter, scaffolds (CHANGELOG, backlog, memory, OWNERSHIP_INDEX), boundary-file, feature, changelog, plan, protected files, ADR, project root README templates |
 | `references/style-guide.md` | Writing rules, formatting conventions |
 | `references/examples.md` | Good vs bad documentation examples |

package/data/harnesses/code/skills/documentation/references/templates.md

@@ -86,8 +86,10 @@ Each topic has one canonical location. Read from here, not from plans or changel
 
 | Topic | Authority | Key Files |
 | ----- | --------- | --------- |
-| System architecture | `docs/architecture/` | {key files} |
-| Feature behavior | `docs/features/` | {key files} |
+| System architecture + steering | `docs/architecture/` | domain-model, glossary, non-goals, references, adr/ |
+| Feature behavior | `docs/features/` (or `docs/modules/{m}/features/`) | {key files} |
+| Cross-module contracts | `docs/boundaries/` | one file per boundary (maintained by `boundary-mapper`) |
+| Bounded contexts (graduated) | `docs/modules/{m}/` | `features/` + `pillars/` |
 | Setup & development | `docs/operations/` | {key files} |
 | Historical plans | `docs/history/plans/` | YYYY-MM-DD-name.md |
 | Change records | `docs/history/changelog/` | Individual entries |
@@ -104,7 +106,9 @@ Plan (Status: Draft) → Implementation → Feature Doc or Architecture Update
 ## Folder Rules
 
 - `docs/features/`: Living reference for implemented features. Each spec includes YAML frontmatter with `owns`, `touches`, `depends_on` fields declaring code ownership.
-- `docs/architecture/`: System-wide patterns and technical decisions. Update when cross-cutting concerns change.
+- `docs/architecture/`: System-wide patterns and the cross-module steering layer (domain model, glossary, non-goals, references, ADRs). Update when cross-cutting concerns change.
+- `docs/boundaries/`: Horizontal typed application boundaries — one file per cross-module contract. Generated/maintained by the `boundary-mapper` agent; read before touching a shape it defines.
+- `docs/modules/{m}/`: Vertical bounded contexts (a graduation at ≥2 contexts). Each owns `features/` + module-local `pillars/` (doctrine, lazy). There is no repo-wide `docs/pillars/`.
 - `docs/operations/`: How-to procedures for setup, development, and deployment. Update when workflows change.
 - `docs/history/plans/`: Historical. Must have `Status:` field. Never modify after completion.
 - `docs/history/changelog/`: Historical. Append-only.
@@ -115,7 +119,7 @@ Plan (Status: Draft) → Implementation → Feature Doc or Architecture Update
 <!-- Updated by maintenance agent -->
 | Date | Review Summary |
 | ---- | -------------- |
-| {today} | Initial baseline — 6-folder structure established |
+| {today} | Initial baseline — v9 structure established |
 ```
 
 ---
@@ -231,7 +235,8 @@ description: Shared knowledge accumulated across agent sessions. All agents shou
 ## Documentation Baseline
 
 - **Baselined:** {today}
-- **Structure:** 6-folder (architecture, features, operations, history, memory, tests)
+- **Structure:** v9 (architecture, features, operations, history, memory; + boundaries/, modules/, tests/ when present)
+- **Spec version:** v9
 
 ## Learnings
 
@@ -282,15 +287,15 @@ Auto-generated by the maintenance agent (Step 0). Do not edit by hand.
 
 ---
 
-## 5. docs/operations/guardrails.md (Cascading Failure Boundaries)
+## 5. Boundary File (docs/boundaries/{boundary}.md)
 
-Use for: documenting contracts, shapes, and coupling points where a change in one module silently breaks another. Created during baseline audit. Updated when new cross-module contracts are discovered.
+> **This skill does not generate boundaries.** Typed-boundary generation is owned by the **`boundary-mapper`** agent, which detects the stack + IA and applies its built-in Application Boundary Scale to emit typed files. The baseline does **not** scaffold `docs/boundaries/` — `boundary-mapper` runs right after the baseline ("baseline boundaries"). This section is the generic **boundary-file template** plus the guidance for *recognizing* what deserves a boundary.
 
-### What belongs in guardrails
+### What deserves a boundary
 
-A guardrail is something where **the failure is silent and crosses module boundaries**. The developer working in module A has no reason to know that module B will break. No import error, no runtime exception — just wrong behavior.
+A boundary is a **horizontal, cross-module contract** where the failure is silent and crosses module boundaries — the developer in module A has no reason to know module B will break. No import error, no runtime exception — just wrong behavior.
 
-Test: "If an agent edits this while working on a single feature, could it silently break something in a different feature?" If yes, it's a guardrail.
+Test: "If an agent edits this while working on a single feature, could it silently break something in a different feature?" If yes, it's a boundary.
 
 **Include:**
 
@@ -308,14 +313,14 @@ Test: "If an agent edits this while working on a single feature, could it silent
 
 - Module-internal architecture (well-encapsulated, no cross-module blast radius)
 - Authentication/authorization flows (behind adapters, feature code doesn't touch them)
-- Hook taxonomies and API reference (useful docs, but not guardrails — they don't cause cascading failures)
+- Hook taxonomies and API reference (useful docs, but not boundaries — they don't cause cascading failures)
 - Networking details (WebSocket, HTTP client setup) — unless the event routing has cross-module string coupling
 - Feature folder conventions and code style (conventions, not breakage vectors)
-- Anything where failure produces an import error, a clear runtime exception, or a visible UI error — those are self-diagnosing and don't need guardrails
+- Anything where failure produces an import error, a clear runtime exception, or a visible UI error — those are self-diagnosing and don't need a boundary
 
-### How to research guardrails
+### How to research a boundary
 
-When creating or updating `docs/operations/guardrails.md`, use sub-agents to investigate:
+When mapping a boundary (the `boundary-mapper` agent's job — this guidance is shared), use sub-agents to investigate:
 
 1. **Shared state consumers** — For each Redux slice/context, find all files that read from it. Flag any file reading a slice it doesn't own (cross-module dependency).
 2. **String-coupled actions** — Grep for Redux action type strings referenced as raw strings rather than imported constants. These are invisible breakage points.
@@ -324,46 +329,29 @@ When creating or updating `docs/operations/guardrails.md`, use sub-agents to inv
 5. **Pipeline data dependencies** — For multi-step processes, check what each step reads from shared state and what previous step wrote it. Test: "If I reorder these steps, does it fail loudly or silently?"
 6. **Persistence rehydration** — Check what reconciler is used, whether transforms exist, and what happens to existing users when a persisted shape changes.
 
-### Template
-
-```markdown
-# Guardrails
-
-Things that silently break across modules if touched wrong. Each section explains what the contract is, where it's consumed, and what goes wrong if violated.
-
----
-
-## 1. [Contract Name]
-
-[One-line description of what this contract governs.]
-
-### The contract
+### Generic boundary-file template
 
-[Describe the shape, format, or protocol. Show code if it's a data shape.]
+One file per boundary in `docs/boundaries/`. `boundary-mapper` emits typed files using the Application Boundary Scale; this is the generic fallback shape.
 
-### Where it's consumed
-
-[Table or list of every file/module that depends on this contract.]
-
-### What breaks if violated
-
-[Specific failure modes. "Silent data loss", "lookup returns undefined", "pipeline hangs", etc.]
-
-### Checklist (if applicable)
-
-[Step-by-step list of files to touch when extending this contract. Mark which steps cause silent failures if skipped.]
+```markdown
+# {Boundary Name}
 
----
+[BOUNDARY: {type} · {severity}]   <!-- type from the Application Boundary Scale; severity CRITICAL | HIGH | MED | LOW -->
 
-## N. [Next Contract]
+**Bounds:** {module A} ↔ {module B}   <!-- which modules sit on each side -->
 
-...
+## Shape
+<!-- `transcribe`: a synthesized contract with no single code home (composed store tree, API envelope, the IA entity model, tenancy) — written inline, canonical here.
+     `point`: a self-locating shape (DB schema, route table) — a `file:line` pointer + invariants. Never copy a self-locating shape; it rots on the next change. -->
 
----
+## Invariants
+<!-- The rules that must hold across the boundary. -->
 
-## Reference: [Shapes / Enums / Defaults]
+## Blast radius
+<!-- What breaks, and where, if an invariant is violated. -->
 
-[Put stable reference material (store shapes, entity defaults, API envelopes) at the bottom. These support the guardrails above but aren't guardrails themselves.]
+## Safe-change checklist
+<!-- Ordered steps to change this contract without silent breakage. Mark steps that fail silently if skipped. -->
 ```
 
 ---
@@ -570,7 +558,7 @@ Brief description of what changed and why.
 
 Use for: every implementation plan. Plans are created here directly with `Status: Draft`, flip to `Status: In Progress` when work starts, and freeze at `Status: Complete` or `Status: Abandoned`. Once frozen, never edit — write a new dated plan if scope changes.
 
-The `introspect` skill parses the **Proposed Changes** sections to check guardrail impact. Keep that structure stable — section headings and bullet shape are load-bearing for the parser.
+The `introspect` skill parses the **Proposed Changes** sections to check boundary impact. Keep that structure stable — section headings and bullet shape are load-bearing for the parser.
 
 ```
 # {Feature Name}
@@ -606,7 +594,7 @@ Why this work is happening *now*. Link to the spec for *what* we're building; th
 
 ### Cross-Module Contracts Affected
 
-- List which guardrails (from `docs/operations/guardrails.md`) this plan touches by name
+- List which boundaries (from `docs/boundaries/`) this plan touches by name
 - "None" is a valid answer and means introspect will pass cleanly
 
 ## Implementation Steps