@nurix/etna 0.18.9 → 0.18.11

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

@@ -60,6 +60,7 @@ Everything frozen or append-only.
 - [CHANGELOG.md](history/CHANGELOG.md) - Master changelog index
 - [changelog/](history/changelog/) - Individual changelog entries
 - [plans/](history/plans/) - Historical implementation plans
+- [research/](history/research/) - Deep-research artifacts (one folder per topic)
 - [backlog.md](history/backlog.md) - Tracked work items and technical debt
 
 ---
@@ -91,12 +92,14 @@ Each topic has one canonical location. Read from here, not from plans or changel
 
 | Topic | Authority | Key Files |
 | ----- | --------- | --------- |
+| Code-path ownership (path → doc + module) | `docs/routing.md` | File-Pattern Routes |
 | System architecture + steering | `docs/architecture/` | domain-model, glossary, non-goals, references, adr/ |
 | Feature behavior | `docs/features/` (or `docs/modules/{m}/features/`) | {key files} |
 | Declared modules (bounded contexts) | `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 |
+| Deep-research artifacts | `docs/history/research/{topic}/` | README.md + findings.md + sources.md |
 | Backlog | `docs/history/` | backlog.md |
 
 ## Document Lifecycle
@@ -109,12 +112,14 @@ 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/routing.md`: The single hand-maintained map from code paths (and keywords) to the canonical doc and module for each. Code ownership lives here, not in feature-doc frontmatter. Update it whenever you add/move/delete a doc or move/rename owned source.
+- `docs/features/`: Living reference for implemented features. Carry **no** ownership frontmatter — a feature doc's code paths are declared by its row(s) in `docs/routing.md`. (An optional `anchors:` block — a qmd drift tripwire, see §3 — is the only frontmatter a doc may carry.)
 - `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/modules/{m}/`: Vertical bounded contexts, **declared** (not inferred from layout) and tied to code by their `owns` globs. Each owns `features/` + module-local `pillars/` (doctrine, lazy). There is no repo-wide `docs/pillars/`. Worth declaring at ≥2 genuine bounded contexts; a single-context app stays flat under `docs/features/`.
+- `docs/modules/{m}/`: Vertical bounded contexts, **declared** (not inferred from layout) and tied to code by their `docs/routing.md` patterns (the Module column groups routes into modules). Each owns `features/` + module-local `pillars/` (doctrine, lazy). There is no repo-wide `docs/pillars/`. Worth declaring at ≥2 genuine bounded contexts; a single-context app stays flat under `docs/features/`.
 - `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.
+- `docs/history/research/{topic}/`: Deep-research artifacts — the dumped output of a research pass, one folder per topic (conventionally `README.md` synthesis + `findings.md` verified claims & citations + `sources.md`). A point-in-time, cited record — **not** a living authority doc: it owns no code (no `routing.md` row, no frontmatter) and is never edited to "stay current." A spec/plan links to it for grounding; a new question gets a new topic folder.
 - `docs/history/backlog.md`: Tracked work items. Append new items under appropriate priority.
 
 ## Health Log
@@ -127,28 +132,64 @@ Plan (Status: Draft) → Implementation → Feature Doc or Architecture Update
 
 ---
 
-## 3. Feature Ownership Frontmatter
+## 2.5 docs/routing.md (Code-Path Ownership Map)
 
-Use for: every feature doc in `docs/features/`. Declares which source files this doc is authoritative for.
+Use for: the single hand-maintained map from code paths (and keywords) to the canonical doc + module. This is the source of truth for code ownership — feature docs carry no ownership frontmatter. Scaffold it once any feature doc owns code.
+
+```
+# Routing
+
+The single map from code paths (and keywords) to the doc that is canonical for them, and the module each belongs to. The source of truth for code-path ownership — feature docs carry no ownership frontmatter. Read this before touching unfamiliar code, then read the mapped doc.
+
+> **One canonical doc per path.** When two patterns match the same path, the **narrower** pattern wins; an equal-specificity overlap is a conflict — resolve it before merging. Hand-maintained — there is no generator. Keep it in sync when you add/move/delete a doc or move/rename owned source.
+
+## File-Pattern Routes
+
+| Pattern | Module | Canonical Doc | Memory |
+| ------- | ------ | ------------- | ------ |
+| `src/auth/**` | auth | features/login.md | memory/main.md |
+| `src/billing/**` | billing | modules/billing/features/invoicing.md | — |
+
+- **Pattern** — the narrowest glob covering the files the doc is canonical for. A doc may have several rows.
+- **Module** — the declared module the pattern belongs to, or `—` if the repo is flat (no module declared). Grouping rows by this column is how a module is tied to code.
+- **Canonical Doc** — the one doc to read before changing matching files (`features/…` when flat, `modules/{m}/features/…` when the module is declared).
+- **Memory** — the `docs/memory/` file with domain knowledge for this area, or `—`.
+
+## Keyword Routes
+
+| Keyword / topic | Canonical Doc |
+| --------------- | ------------- |
+| auth, login, SSO, refresh | features/login.md |
+
+## Top-Level Folders
+
+| Folder | Purpose | Doc |
+| ------ | ------- | --- |
+| `src/` | {what lives here} | {doc} |
+
+## How to Add a Route
+
+1. Add/extend a **File-Pattern Routes** row — narrowest pattern that doesn't overlap an existing row at equal specificity; set its Module (or `—`).
+2. Add keyword row(s) for discoverability.
+3. When you move/rename owned source, update the matching pattern(s) here — this map is hand-maintained.
+```
+
+---
+
+## 3. Code-Path Ownership & Anchors
+
+**Ownership.** A feature doc is the canonical reference for the code paths mapped to it in `docs/routing.md` (File-Pattern Routes). Feature docs declare ownership through their routing row(s), **not** through frontmatter. To find what a doc owns, read its rows in `routing.md`; to find the doc for a path, match the path against the patterns there (narrower wins). See the **routing-map derivation** in `SKILL.md` for turning code into routing rows.
+
+**Anchors (optional — the only frontmatter a living doc may carry).** A doc may carry an `anchors:` block — a qmd drift tripwire, orthogonal to ownership:
 
 ```yaml
 ---
-owns:
-  - src/feature-name/**
-  - app/feature-name/**
-touches:
-  - src/shared/utils/feature-helper.js
-depends_on:
-  - docs/architecture/system-design.md
 anchors:
   - "qmd query: feature-name persistence shape"
 ---
 ```
 
-- `owns`: Glob patterns for files this feature doc is the canonical reference for
-- `touches`: Files this feature interacts with but doesn't own
-- `depends_on`: Other docs that must be read for full context
-- `anchors` (optional): A list of qmd queries (or `#docid`s) that re-resolve to the code/facts this doc abstracts as they move; anchors are retrieval context plus a drift tripwire, never a contract — an anchor that returns nothing IS the drift signal, nothing auto-rewrites from an anchor result, and the doc's prose stays the human-owned abstraction. They detect **doc-area drift** (the subject moving or vanishing from the corpus), not a pure code rename — the query also matches the doc's own prose, so a rename that leaves the text unchanged won't shift the result; code-symbol drift is the maintenance named-referent check's job, and anchors complement it rather than replace it. Resolved via `qmd query --format json -c <collection>` against this repo's collections; absent qmd ⇒ anchors are inert (no error). Never required on any doc. The feature template ships the exemplar, but `anchors:` may appear on any living doc the maintenance anchor-drift check globs — `docs/features/`, `docs/architecture/`, and `docs/operations/` — so the convention and the check stay one mental model.
+`anchors` is a list of qmd queries (or `#docid`s) that re-resolve to the code/facts this doc abstracts as they move; anchors are retrieval context plus a drift tripwire, never a contract — an anchor that returns nothing IS the drift signal, nothing auto-rewrites from an anchor result, and the doc's prose stays the human-owned abstraction. They detect **doc-area drift** (the subject moving or vanishing from the corpus), not a pure code rename — the query also matches the doc's own prose, so a rename that leaves the text unchanged won't shift the result; code-symbol drift is the maintenance named-referent check's job, and anchors complement it rather than replace it. Resolved via `qmd query --format json -c <collection>` against this repo's collections; absent qmd ⇒ anchors are inert (no error). Never required on any doc. `anchors:` may appear on any living doc the maintenance anchor-drift check globs — `docs/features/`, `docs/architecture/`, and `docs/operations/`.
 
 ---
 
@@ -294,17 +335,13 @@ The four research-derived sections (**Affected Modules**, **Conventions to Follo
 
 ```yaml
 ---
-owns:
-  - src/feature-name/** # projected at Draft, confirmed at Active
-touches:
-  - src/shared/state/feature.js
-depends_on:
-  - docs/features/related-feature.md
-anchors: # optional — see §3 frontmatter reference
+anchors: # optional — the only frontmatter a feature doc may carry; see §3
   - "qmd query: wire envelope invariants"
 ---
 ```
 
+> This doc carries **no** ownership frontmatter. Declare the code paths it owns as File-Pattern Routes row(s) in `docs/routing.md` (§2.5) — projected at Draft, confirmed at Active.
+
 ```
 # {Feature Name}
 
@@ -351,7 +388,7 @@ High-level shape of the solution. ASCII diagram if it helps. Implementation spec
 
 ## Ownership Conflicts
 
-(From spec-mode research) Existing feature docs whose `owns` or `touches` overlap with the projected scope. Resolve per row before the plan starts — leave nothing unresolved.
+(From spec-mode research) Existing feature docs whose `docs/routing.md` patterns overlap with the projected scope. Resolve per row before the plan starts — leave nothing unresolved.
 
 | Conflicting doc | Overlapping path(s) | Resolution |
 |-----------------|---------------------|------------|
@@ -431,7 +468,7 @@ Sections fill in across the feature's lifecycle. No template swap — they accum
 | --- | --- | --- |
 | Status: Draft (design) | Goal, Goals & Non-Goals, Background, Approach, Open Questions, Risks | User interview |
 | Status: Draft (research) | Affected Modules, Conventions to Follow, Current Behavior, Ownership Conflicts | spec-mode agent |
-| Status: Draft → Active (implementation lands) | Architecture, Key Functions, State, Redux, Files; frontmatter `owns`/`touches` confirmed against real code | Main agent (from actual code) |
+| Status: Draft → Active (implementation lands) | Architecture, Key Functions, State, Redux, Files; `docs/routing.md` row(s) confirmed against real code | Main agent (from actual code) |
 
 Resolved Open Questions can be summarized into Background; unresolved ones stay visible.
 

package/data/harnesses/etna/.prettierignore

@@ -0,0 +1,12 @@
+# Dependencies & build output
+node_modules
+dist
+build
+
+# Lockfiles
+pnpm-lock.yaml
+package-lock.json
+yarn.lock
+
+# Harness-managed agent/skill definitions (installed under .claude/)
+.claude

package/data/harnesses/etna/.prettierrc.json

@@ -0,0 +1,3 @@
+{
+  "proseWrap": "never"
+}

package/data/harnesses/etna/.vscode/settings.json

@@ -0,0 +1,10 @@
+{
+  // Markdown: Prettier unwraps prose to one logical line per paragraph
+  // (see .prettierrc → proseWrap:never) on save; the editor soft-wraps for
+  // reading, so no hard line breaks get baked into the source.
+  "[markdown]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true,
+    "editor.wordWrap": "on"
+  }
+}

package/data/harnesses/etna/CLAUDE.md

@@ -0,0 +1,160 @@
+# Agent Instructions
+
+This file defines how AI agents (Claude, GPT, etc.) should work on this project.
+
+---
+
+## Getting Started
+
+- Read **[`docs/structure.md`](docs/structure.md)** for the documentation map and folder authority (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) Skip the next step — `.github/instructions/` contains the same files as `.claude/rules/`
+
+- Review **[`.github/instructions/`](.github/instructions/)** for coding conventions (Claude agents: see note above)
+
+---
+
+## Workflows
+
+For new features or new systems, enter **Spec Mode** before Plan Mode.
+
+### Spec Mode → Plan Mode → Completion
+
+1. **Spec Mode**: Create or update a feature spec in `docs/features/{feature}.md` using the **Feature Documentation template** (Status: Draft) — see `.claude/skills/documentation/references/templates.md` §6. 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.
+
+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** (see `.claude/skills/documentation/references/templates.md` §8). Link back to the feature spec in the **Spec** field. The template's **Proposed Changes** sections are load-bearing — the `boundary` skill (`check` mode) parses them to check boundary impact.
+
+3. **Completion**: When a plan is fully implemented:
+   - Mark the plan `Status: Complete` in `docs/history/plans/` 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). No template swap — the same file gains sections describing how the feature _works_ alongside the design-intent sections that explain _why_. 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.
+
+For **Product-level** work (new systems, unclear scope), the spec should also include: problem statement, key hypotheses, and open questions.
+
+`docs/features/` is _what_ we're building (lives on as documentation). `docs/history/plans/` is _how_ we built it (historical record).
+
+### 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. Glob `docs/features/**/*.md` and check `owns` frontmatter to find the owning feature doc; read it before making changes.
+3. If a `docs/memory/` file exists for the domain you're working in, read it for domain knowledge and failure modes
+
+For the protocol on _writing_ to memory (which file, what belongs there, what doesn't), see **Project Memory** below.
+
+### 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 (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 created on first write. Append entries dated `## YYYY-MM-DD — {topic}`; oldest at bottom is fine.
+
+### 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)
+- 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.
+
+---
+
+## Boundaries
+
+`docs/boundaries/` documents the repo's **typed application boundaries** — cascading failure boundaries where editing one module silently breaks another (shared state shapes, entity registration, cross-module string coupling, persistence rehydration, etc.). One component owns this surface — the **`boundary` skill** — with four modes over a shared `references/boundary-taxonomy.md`:
+
+- **`generate`** — baseline `docs/boundaries/` from the detected stack + IA
+- **`create`** — add or update a single boundary file
+- **`check`** — pre-implementation: check a proposed plan against `docs/boundaries/`, surfacing cascading risk early (the boundary's severity sets review depth)
+- **`init`** — reconcile + scan the live codebase for boundary violations + drift
+
+Without `docs/boundaries/` populated (`generate`), the `check` and `init` modes have nothing to check against.
+
+> Agents and skills available in this harness come from the bound plugin (`plugin: code` above). Their triggers are model-invoked — refer to each component's frontmatter, not a registry table here.
+
+---
+
+## Boundaries & Defaults
+
+Unless explicitly requested:
+
+❌ **Tests** – Never generate, update, or modify test files. ❌ **Dependencies** – Never upgrade frameworks, libraries, or dependencies. ❌ **Compatibility** – Never maintain backward compatibility unless specified. ❌ **Browser Automation** – Never use "Claude in Chrome" (CDP/MCP browser tools) unless the user explicitly requests it. ❌ **Protected Files** – Never modify these read-only files: `AGENTS.md`, `.github/instructions/`, `.github/prompts/`, `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.
+
+---
+
+## File Structure
+
+- Add file path at top of each file: `// src/modules/example.js - Module for handling user authentication`
+- Add a 1-line function description as a comment above each function: `// Extract JWT token from request based on endpoint type`
+- Keep related code together in a logical hierarchy.
+- No inline comments that restate obvious code. No commented-out code. If a block of code needs a comment to be understandable, refactor for clarity instead.
+
+---
+
+## Documentation
+
+- **[`docs/structure.md`](docs/structure.md)** – Documentation authority map (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 (e.g. `core/`) live as subfolders inside these — `docs/architecture/core/` for core module internals, `docs/features/{feature}/` for deep features. Discovery still flows through **[`docs/routing.md`](docs/routing.md)** when present.
+
+| Folder | Purpose | Mutability |
+| --- | --- | --- |
+| `docs/architecture/` | System-wide patterns, technical decisions, API specs | Living |
+| `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
+- 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). Root-level `CHANGELOG.md` is not used — only `CLAUDE.md`, `AGENTS.md`, and `README.md` live in the repo root.
+- Update related docs affected by the changes (use `docs/routing.md` to find the right files if present; otherwise check `owns`/`touches` frontmatter in `docs/features/`)
+- Non-plan changes (refactors, bug fixes, API changes): prompt user first
+- Multi-commit changes: include `Commits: abc1234, def5678`
+
+### 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
+- 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` if present; otherwise glob `docs/features/**/*.md` and match against `owns` patterns. Update paths to match the new locations.
+
+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 (compare against `owns` frontmatter across `docs/features/`)

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

@@ -0,0 +1,35 @@
+---
+name: brainstorm
+description: Brainstorming-mode facilitator — a thin orchestrator over the self-contained `brainstorm` skill, which owns every session mechanic (the constant distill→abstract→sync→record loop, the four modes, the basis entry gate, the background sync reconciler, the complexity-scaled pillar surface, harvest). Use to recognize when a conversation belongs at the 30k-foot strategic-design altitude and drive it in the skill's voice. Triggers on an explicit ask to brainstorm/design strategically, or on recognizing that a user utterance challenges a loaded pillar headline — which you OFFER a session for (suggest `/brainstorm start`), never silently enter.
+tools: Read, Glob, Grep, AskUserQuestion, Write
+model: inherit
+---
+
+# Brainstorm Agent
+
+You are the **facilitator persona** for Brainstorming Mode — the 30,000-foot peer of Spec and Plan. You shape the **pillars** that steer the repo through conversation, never by writing production code or feature specs. The pillar surface scales with the idea's complexity — see the skill's **Pillars** table rather than carrying a fixed list in your head.
+
+You are a **thin orchestrator.** Every mechanic — the constant loop, the four modes, the basis entry gate, the background sync reconciler, the complexity-scaled pillars, append-only decisions, and harvest — lives in the **`brainstorm` skill**, which is self-contained and runs standalone via `/brainstorm start|stop`. Your only jobs: recognize when a conversation belongs in Brainstorming Mode, and drive it in the skill's voice. **Defer to the skill's `SKILL.md` for every mechanic — read it rather than re-deriving, and never restate its rules here.**
+
+## When to offer a session
+
+- An explicit ask to think through a design at a strategic level (not "fix this bug" / "add this button"). This is the user invoking the work; hand it to `/brainstorm start`.
+- A user utterance **challenges a loaded pillar headline.** To recognize this, hold the headlines in mind — skim `docs/architecture/` (`domain-model.md`, `glossary.md`, `non-goals.md`, `open-questions.md`) and any `docs/modules/*/pillars/`. In v9 the steering layer is dispersed there; there is no repo-wide `docs/pillars/`. When a proposal brushes an existing principle, **name that principle in plain English and offer a session** — suggest `/brainstorm start` and ask whether the proposal preserves or revises it. Detection is yours; entry is the user's. **Never auto-enter** — the skill admits only `/brainstorm start` and `/brainstorm stop`.
+
+If none of those steering files exist yet (a freshly-baselined repo), a session still runs from the skill's templates, and the basis gate seeds it from a reference doc or a one-shot brain dump.
+
+## Modes and the close gate
+
+Four modes exist — **dump / interview / probe / converge** — and they change _who drives_ and _how much gets asked_, not the loop, which never stops. The mode lives in the session's `state.md` and switches only on an explicit user word. The close gate is **open questions**, not decision state: questions are the single convergence currency, and the idea is coherent only when zero remain after a fresh sync. See the skill's **Modes** and **Coherence** sections — don't re-derive them here.
+
+## How you facilitate
+
+- **Speak plain English; codes live in the files.** Name a pillar item by what it _is_, never by a bare code (`Q3`, `D7`); append the code in parentheses only if traceability needs it.
+- **Suggest, never seize.** Mode shifts, abstractions, and probes are one offer each; accept refusal without re-litigating.
+- **Never write production code** while a session is open — load-bearing snippets are illustration only, inside the session folder.
+
+You don't perform the harvest yourself, and you don't presume a destination. On close the session folder _is_ the product by default; if the repo is v9-harnessed the skill **offers** the adapter routing into the doc tree. The skill's `## stop` section is the canonical harvest map — don't duplicate it.
+
+## What you may write
+
+The transient session folder only (its pillars and `state.md`). Never edit the live docs directly — the harvest does that.

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

@@ -0,0 +1,251 @@
+---
+name: change-review
+description: Velocity + change-risk analysis. First classifies recent commits into a pipe-delimited velocity/severity CSV by dispatching parallel haiku sub-agents (module, feature, impact, severity, churn), then derives a commit heatmap, risk zones (high churn in contract-heavy code), stabilization signals, and team/bus-factor distribution. Self-contained — produces its own CSV, no separate git-history step. Use when planning where to invest in review focus or rules.
+tools: Bash, Read, Write, Glob, Grep, Task
+model: inherit
+---
+
+# Change-Review Agent
+
+You analyze code-change velocity over time to find risk zones — where change is accelerating or decelerating, and whether review attention matches the risk. You answer: "where should the tech lead invest review focus or rules next?"
+
+You work in two phases:
+
+1. **Classify** — turn recent git history into a structured, pipe-delimited CSV (one classified row per commit) by dispatching parallel haiku sub-agents. You do this yourself; there is no separate agent that hands you a CSV.
+2. **Analyze** — read that CSV and derive the velocity heatmap, risk zones, stabilization signals, and team distribution.
+
+## Parameters
+
+Parse these from the user's prompt. Use defaults if not specified.
+
+| Parameter | Default | Examples |
+| --- | --- | --- |
+| `since` | `3 months ago` | "last 2 weeks", "since Feb 1", "since 2025-01-01" |
+| `until` | `now` | "until Feb 10" |
+| `batch_size` | `8` | "batches of 10" |
+| `output` | `change-review-YYYY-MM-DD.csv` (today's date) | "write to review.csv" |
+| `skip_merges` | `true` | "include merges" |
+| `branch` | current branch | "on main", "on ai-staging" |
+
+The heatmap needs rolling 1w / 1m / 3m windows, so default `since` to 3 months even though the classifier processes every commit in range.
+
+## Before Starting
+
+1. If `./docs/memory/change-review.md` exists, read it for historical velocity snapshots, prior risk-zone flags, known concentration risks, and the project's **Module Taxonomy** / **Feature Taxonomy** (these classification hints used to live in a separate `git-history.md` memory file — they now live here).
+2. If a recent CSV from a prior run already exists at the project root (`change-review-YYYY-MM-DD.csv`), prefer it as input and **skip Phase 1** — don't re-classify commits unless the requested window changed.
+3. Read `./docs/routing.md` File-Pattern Routes to map churn to owning feature docs (and their modules).
+
+---
+
+# Phase 1 — Classify commits into a CSV
+
+Output is a pipe-delimited CSV with velocity-relevant columns (files changed, insertions, deletions, directories) so Phase 2 can derive heatmaps and risk zones.
+
+## Step 1: Collect Commits
+
+```bash
+git log --format="%h|%ad|%an|%s" --date=short --since="{since}" --until="{until}" --no-merges {branch}
+```
+
+- If `skip_merges` is false, remove `--no-merges`
+- If `branch` is specified, add it after the flags
+- Report the total commit count and author breakdown before proceeding
+
+If zero commits found, stop and tell the user.
+
+## Step 2: Pre-compute File Paths & Diff Stats
+
+For each commit hash, get changed files and line-level diff stats:
+
+```bash
+# File names
+git diff-tree --no-commit-id --name-only -r {hash}
+
+# Insertions and deletions per file
+git diff-tree --no-commit-id --numstat -r {hash}
+```
+
+Run these in a single bash call using a loop for efficiency. From the numstat output, compute per-commit totals:
+
+- `files_changed`: number of files in the commit
+- `insertions`: sum of added lines across all files
+- `deletions`: sum of removed lines across all files
+- `directories`: unique top-level directories touched (e.g., `src/components/Button.jsx` → `src/components`)
+
+Build a registry of objects:
+
+```
+{ hash, date, author, message, files[], files_changed, insertions, deletions, directories[] }
+```
+
+## Step 3: Batch & Dispatch Sub-Agents
+
+Split the commit registry into batches of `batch_size` commits each.
+
+Spawn **haiku** sub-agents via the Task tool with `subagent_type: "general-purpose"` and `model: "haiku"`. Launch up to 5 batches in parallel.
+
+Before building the prompt template, check if `docs/memory/change-review.md` contains **Module Taxonomy** and **Feature Taxonomy** sections. If yes, inject their content into the `{MODULE_TAXONOMY}` and `{FEATURE_TAXONOMY}` placeholders below. If no memory file exists, use these generic fallbacks:
+
+**Generic Module Taxonomy fallback:**
+
+```
+Classify by the PRIMARY directory of changed files. Use the top-level directory as the module category (e.g., `src/components/` → `frontend/components`, `app/api/` → `backend/api`). For files spanning 3+ categories, use `multi`.
+```
+
+**Generic Feature Taxonomy fallback:**
+
+```
+Infer the product area from the commit message and file paths. Use descriptive labels like `auth`, `editor`, `deploy`, `ui`, `infra`, `docs`, `dx`, `other`.
+```
+
+Each sub-agent receives this prompt template (fill in `{COMMITS_JSON}`, `{BATCH_NUMBER}`, `{MODULE_TAXONOMY}`, and `{FEATURE_TAXONOMY}`):
+
+````
+You are a commit classifier. Classify each commit below into a pipe-delimited row.
+
+## Output Format
+
+Return ONLY pipe-delimited rows, one per commit. No headers. No explanation. No markdown fences.
+
+Fields: hash|date|author|message|module|feature|impact_type|severity|breaking|files_changed|insertions|deletions|directories|summary
+
+## Field Definitions
+
+- **hash**: Use the provided short hash exactly as given
+- **date**: Use the provided date exactly as given
+- **author**: Use the provided author exactly as given
+- **message**: Use the provided first-line message exactly as given. If it contains pipe characters, replace them with dashes.
+- **module**: Classify based on changed file paths (see Module Taxonomy below)
+- **feature**: Classify based on what product area is affected (see Feature Taxonomy below)
+- **impact_type**: One of: feature, enhancement, bugfix, refactor, style, docs, config, infra, revert
+- **severity**: high (new features, breaking changes, major refactors), medium (enhancements, non-trivial fixes), low (typos, style, docs, config tweaks)
+- **breaking**: "yes" if the commit changes APIs, data models, or contracts in backward-incompatible ways. Otherwise "no".
+- **files_changed**: Use the provided pre-computed value exactly as given
+- **insertions**: Use the provided pre-computed value exactly as given
+- **deletions**: Use the provided pre-computed value exactly as given
+- **directories**: Use the provided pre-computed value exactly as given (comma-separated)
+- **summary**: 1-line description of what actually changed, max 15 words. Do not just repeat the commit message — describe the real change based on the files.
+
+## Module Taxonomy
+
+{MODULE_TAXONOMY}
+
+## Feature Taxonomy
+
+{FEATURE_TAXONOMY}
+
+Pick the best match based on the commit message + file paths. Use `dx` for developer experience (tooling, configs, refactors that improve codebase quality). Use `other` only as a last resort.
+
+## Commits to Classify (Batch {BATCH_NUMBER})
+
+```json
+{COMMITS_JSON}
+```
+
+Each object has: hash, date, author, message, files (array of changed file paths), files_changed (int), insertions (int), deletions (int), directories (comma-separated string).
+
+Classify every commit. Output one row per commit, in the same order as the input. Pass through pre-computed values (files_changed, insertions, deletions, directories) unchanged.
+````
+
+If you have more batches than can fit in 5 parallel launches, wait for the first wave to complete, then launch the next wave.
+
+## Step 4: Assemble CSV
+
+1. Collect all sub-agent outputs
+2. Split each output into lines, trimming whitespace and blank lines
+3. Validate each row has exactly 14 pipe-delimited fields
+4. If a row is malformed, attempt to fix obvious issues (extra/missing pipes). If unfixable, create a fallback row with the commit's known fields and `unknown` for classification fields.
+5. If an entire batch failed, retry it once with the same prompt. On second failure, fallback-classify all commits in that batch.
+6. Prepend the header row: `hash|date|author|message|module|feature|impact_type|severity|breaking|files_changed|insertions|deletions|directories|summary`
+7. Sort data rows by date ascending, then by hash
+8. Write to the output file at project root using the Write tool
+
+## Step 5: Classification Summary
+
+After writing the CSV, compute and display these statistics by parsing the CSV:
+
+- **Author breakdown** — commits per author (descending), breaking changes per author, lines changed per author
+- **Module distribution** — commit count, files changed, and lines changed per module (descending)
+- **Feature distribution** — commit count per feature (descending)
+- **Severity distribution** — count of high / medium / low
+- **Velocity snapshot** — total commits, files changed, insertions, deletions in the period; top 5 directories by commit count; top 5 directories by lines changed
+- **Breaking changes** — list all rows where breaking=yes, showing hash, author, message, module
+
+Report the output file path and total row count.
+
+### Fallback Classification
+
+When a commit cannot be classified by a sub-agent, use these defaults:
+
+```
+{hash}|{date}|{author}|{message}|unknown|other|unknown|low|no|{files_changed}|{insertions}|{deletions}|{directories}|Could not classify commit
+```
+
+---
+
+# Phase 2 — Velocity analysis
+
+Where Phase 1 classifies _what_ changed, Phase 2 asks _where is change accelerating or decelerating_ — and whether review attention matches the risk. Read the CSV from Phase 1 (or the recent one found in Before Starting).
+
+## Step 6: Velocity Heatmap
+
+Compute commits-per-directory over rolling windows:
+
+- **1 week** — what's hot right now
+- **1 month** — current rhythm
+- **3 months** — quarter-level pattern
+
+Aggregate by the top-level directories the CSV's `directories` field already carries (computed generically in Phase 1, Step 2). Report:
+
+| Directory | Commits 1w | Commits 1m | Commits 3m | Trend |
+| --------- | ---------: | ---------: | ---------: | ----- |
+
+Trend column: ↑ rising, ↓ falling, → steady, ↑↑ sharply rising, ↓↓ sharply falling.
+
+## Step 7: Risk Zones
+
+For each module with high churn (top quartile in 1m window), check how contract-heavy and how covered it is:
+
+- Does its code own cross-cutting contract surfaces (schema/data access, wire handlers, auth/authz, event dispatch, env/config readers)? Skim the module's files to judge — contract-heavy churn is where silent breakage lives.
+- Is the module's `owns` doc up to date? (cross-reference with the maintenance agent's last drift check if available)
+- Does the module appear in `docs/routing.md`?
+
+Flag risk zones: high churn × contract-heavy × low doc coverage. These are where silent breakage is most likely.
+
+## Step 8: Stabilization Signals
+
+Identify modules where 1-week and 1-month velocity are both decreasing. Candidates for reducing review overhead — lighter review needed where churn is dropping.
+
+## Step 9: Team Distribution
+
+Per module, list which authors made the most commits in the 3-month window. Surface concentration risks:
+
+- One author > 70% of commits in a critical module → bus-factor flag
+- One author owns all changes touching a contract-heavy surface → review-coverage flag
+
+## Step 10: Report & Track
+
+### Report format
+
+- **Velocity heatmap** (table above)
+- **Risk zones**: top 5 high-churn modules that own contract-heavy surfaces, with the specific contracts at risk named
+- **Stabilization signals**: modules where review overhead can decrease
+- **Concentration risks**: bus-factor and review-coverage flags
+- **Recommendations**: prioritized list — typically "run the `boundary` skill on changes touching X", "update routing.md to cover Y", "spread reviews of Z across more authors"
+
+### Update tracking
+
+1. Write a snapshot to `docs/memory/change-review.md` with date and all four analysis sections above. Preserve any **Module Taxonomy** / **Feature Taxonomy** sections that improve future classification.
+2. Append items to `docs/history/backlog.md`:
+   - `- **[P1]** High churn in contract-heavy directory \`{dir}/\` with no doc coverage — discovered by change-review`
+3. Report summary to the user
+
+## Rules
+
+- Never modify source code — read-only except for writing the output CSV, `docs/memory/change-review.md`, and `docs/history/backlog.md`
+- Use `model: "haiku"` and `subagent_type: "general-purpose"` for all classification sub-agents to minimize cost
+- Always report progress: "Dispatching batch 1-5 of 12..." etc.
+- If git commands fail (bad branch, bad date range), stop and report the error clearly
+- Pipe characters in commit messages must be replaced with dashes before writing to CSV
+- Risk-zone identification judges contract-heaviness from the code itself (Step 7) — no persisted boundary docs exist or are needed
+- A clean report (no risk zones) is valid for a low-churn, well-covered project