@nurix/etna 0.2.1 → 0.3.2

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

@@ -1,8 +1,9 @@
 ---
 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]
 ---
 
 # Contract Monitor
@@ -11,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
@@ -33,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/dep-health.md

@@ -3,6 +3,7 @@ name: dep-health
 description: Dependency supply-chain audit — security CVEs, outdated packages, license compliance, abandoned packages, unwanted transitive dependencies, install size. Run before releases or monthly. Pairs with `review` (which audits code, not deps).
 tools: Read, Glob, Grep, Bash
 model: inherit
+plugins: [nurix-harness]
 ---
 
 # Dependency Health Agent

package/data/harnesses/code/agents/git-history.md

@@ -3,6 +3,7 @@ name: git-history
 description: Analyze git history by dispatching parallel sub-agents to classify commits into a pipe-delimited CSV with module, feature, impact, severity, and velocity dimensions.
 tools: Bash, Read, Write, Glob, Grep, Task
 model: sonnet
+plugins: [nurix-harness]
 ---
 
 # Git History Agent

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

@@ -3,6 +3,7 @@ name: maintenance
 description: Docs-vs-code coherence audit. Detects and fixes docs drifting from code — stale docs, broken ownership, routing table drift, unowned source paths. Run weekly or after major changes. Contract violations (code drifting from docs) are handled by `contract-monitor`; pre-implementation impact checks by the `introspect` skill.
 tools: Read, Glob, Grep, Edit, Write, Bash
 model: inherit
+plugins: [nurix-harness]
 ---
 
 # Maintenance Agent
@@ -10,13 +11,13 @@ model: inherit
 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

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

@@ -3,6 +3,7 @@ name: review
 description: Code-level health audit — bundle size, tree-shaking issues, performance anti-patterns, code-quality flags. Run weekly or after major code changes. Pairs with `dep-health` (which audits dependencies, not code that uses them).
 tools: Read, Glob, Grep, Bash
 model: inherit
+plugins: [nurix-harness]
 ---
 
 # Review Agent

package/data/harnesses/code/agents/spec-mode.md

@@ -5,6 +5,7 @@ tools: Read, Glob, Grep, WebSearch, WebFetch
 model: inherit
 skills:
   - documentation
+plugins: [nurix-harness]
 ---
 
 # Spec Mode Agent

package/data/harnesses/code/rules/general.md

@@ -1,5 +1,6 @@
 ---
 applyTo: "**"
+plugins: [nurix-harness]
 ---
 
 # Technology Choices & Standards

package/data/harnesses/code/rules/nomenclature.md

@@ -1,5 +1,6 @@
 ---
 applyTo: "**"
+plugins: [nurix-harness]
 ---
 
 # Nomenclature Guidelines

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

@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 # scripts/build-ownership-index.sh - Generate docs/OWNERSHIP_INDEX.md from feature doc frontmatter
+# plugins: [nurix-harness]
 
 set -euo pipefail
 

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

@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 # scripts/check-doc-drift.sh - Detect potentially stale docs based on recent code changes
+# plugins: [nurix-harness]
 
 set -euo pipefail
 

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

@@ -0,0 +1,86 @@
+---
+name: boundaries
+description: The technology-aware Application Boundary Scale — the knowledge the boundary-mapper agent applies when generating docs/boundaries/. Maps each technology to its application boundaries (what ripples when touched), a doc-mode (point vs transcribe), and a default severity that drives introspect's review depth. Seeded for react-router, redux-toolkit, vite, shadcn/ui, express, django, fastapi, plus the stack-independent `domain` category (the information-architecture entity model). Use when baselining or extending a repo's boundary set, or when deciding whether a change touches a protected boundary.
+plugins: [nurix-harness]
+---
+
+# Boundaries — the Application Boundary Scale
+
+A **boundary** is a horizontal cross-cutting contract that multiple modules touch. Touching it ripples outward, so it must be documented and protected. This skill is the *knowledge*; the `boundary-mapper` agent is the *process* that applies it to a repo, writing one file per boundary into `docs/boundaries/`.
+
+This skill exists because the dangerous boundaries are the invisible ones. A team writes a guardrail for "auth" but never for "the Redux store shape" or "the entity model" — because those read as *just how the app is built*. The scale names them so they can't hide.
+
+## Two categories
+
+| Category | Determined by | How `boundary-mapper` finds it |
+|---|---|---|
+| **technology** | the stack | detect from `package.json` + source tree |
+| **domain** | the product's information architecture, independent of stack | read ADRs, doctrine, the entity/contracts definitions — **not** stack detection |
+
+The **domain** boundary (the IA entity model) is usually the *highest-severity boundary in the whole repo* and is the cleanest bridge from Brainstorming Mode (which shapes the IA) to the boundary set (which `introspect`/`contract-monitor` enforce).
+
+## doc-mode: `point` vs `transcribe`
+
+- **`point`** — *self-locating* shapes a reader finds unaided (DB schema → `schema.ts`/`models.py`; routes → the router file). The boundary file is **pointer (`file:line`) + invariants + checklist**. Never transcribe — the code is source-of-truth and a copy rots on the next push/codegen.
+- **`transcribe`** — *synthesized* contracts with no single code home (the composed Redux store tree, the API response envelope, the IA relationship/topology, tenancy). Transcribe canonically; the boundary file then owns the shape and feature docs link up.
+
+## The scale
+
+Each entry: boundary type(s) · where it lives · doc-mode · default severity · what a change triggers.
+
+### domain (stack-independent)
+
+| Boundary | Lives in | doc-mode | Severity | A change triggers |
+|---|---|---|---|---|
+| **information architecture** — entity model + topology (e.g. Brief→Plan→Persona→Audience→Match→Campaign→Run; service planes) | synthesized — ADRs / doctrine / contracts pkg | `transcribe` | **CRITICAL** | re-relating or renaming an entity ripples across *every* module; check all consumers, migrations, wire types |
+| **tenancy** — the workspace/tenant scoping invariant | query layer (a rule, not a file) | `transcribe` | **CRITICAL** | a missing scope = cross-tenant leak; audit every read/write path |
+
+### technology
+
+| Tech | Boundary | Lives in | doc-mode | Severity | A change triggers |
+|---|---|---|---|---|---|
+| `react-router` | route tree | router config (self-locating) | `point` | MED | deep-linking, auth guards, redirects, lazy boundaries |
+| `redux-toolkit` | composed store shape + **persisted keys** + selectors | spread across `store/` slices (no single file) | `transcribe` | HIGH | renamed/removed key breaks selectors + rehydration; persisted keys = CRITICAL |
+| `vite` | dev proxy list, `VITE_` env prefix, path aliases | `vite.config` (self-locating) | HIGH | `point` | a new backend mount must be added to the proxy list; env prefix governs what reaches the client |
+| `shadcn/ui` | `components.json`, generated `ui/` primitives, theme tokens | self-locating | LOW | `point` | `ui/` is generated — don't hand-edit, re-run the CLI; tokens in `:root`/`.dark` are the contract |
+| `express` | middleware order, error-handler position, response envelope, route surface | order/envelope = convention; routes self-locating | `transcribe` (order+envelope) / `point` (routes) | HIGH | order is parsers→custom→routes→error-handler-**last**; envelope `{status,message,data}` is the contract |
+| `django` | `settings.py` MIDDLEWARE order + INSTALLED_APPS, models, URLconf, DRF serializers | models/urls self-locating; middleware = convention | `point` + `transcribe` | HIGH (serializers/models CRITICAL) | serializer = wire contract; migration forward-only; middleware order changes request handling globally |
+| `fastapi` | Pydantic request/response models, APIRouter surface, `Depends` graph | schemas/routers self-locating | `point` | HIGH | a response-model change = wire-contract change; the dependency-injection graph shifts auth/session resolution |
+| `temporal` | workflow/activity signatures, signal/query names, task queues | workflow defs (self-locating) | `point` | HIGH | the starter references by name; a signature mismatch = stuck runs |
+| `@org/contracts` (shared wire types) | persisted shapes + envelopes shared across SPA/BFF/worker | the contracts package (self-locating) | `point` | CRITICAL | 3-way drift; update the package first, then consumers |
+
+Extend the scale by adding a row (and, for a new technology, a short pack describing where its boundaries live and the safe-change checklist). The instructions must be **technology-specific, never vague** — "middleware order is parsers→custom→routes→error-handler-last" beats "be careful with middleware."
+
+## Boundary file template
+
+`boundary-mapper` writes one file per boundary using this shape:
+
+```markdown
+# <Boundary name>
+
+[BOUNDARY: <type> · <CRITICAL|HIGH|MED|LOW>]
+
+**Bounds.** <which modules / planes sit on each side>
+
+## Shape
+<transcribed contract, OR a `file:line` pointer with one-line orientation>
+
+## Invariants
+<what must hold>
+
+## Blast radius
+<what breaks, and where, if violated>
+
+## Safe-change checklist
+- [ ] <step>
+- [ ] <step>
+```
+
+`docs/boundaries/README.md` indexes every boundary (name · type · severity) and records which technology packs are active.
+
+## How the pieces connect
+
+- `boundary-mapper` (agent) detects the stack + IA and applies this scale to write `docs/boundaries/`.
+- `introspect` (skill) reads `docs/boundaries/` before implementation; the boundary **severity** sets its review depth.
+- `contract-monitor` (agent) scans the live codebase against `docs/boundaries/` after changes land, per boundary type.
+- The **maintenance** agent flags when a boundary file drifts from code; `boundary-mapper` update-mode fixes it.

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

@@ -1,6 +1,7 @@
 ---
 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 + `boundaries` skill, 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]
 ---
 
 # Technical Documentation Skill
@@ -28,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
     │
@@ -45,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
 
@@ -53,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**
@@ -125,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)
@@ -137,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
@@ -233,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 (detects the stack + IA, emits typed files) and the **`boundaries`** skill (the per-technology Application Boundary Scale). 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