@nurix/etna 0.18.10 → 0.18.11

package/README.md

@@ -77,25 +77,26 @@ Listed by `npx @nurix/etna` (no args) using the bundled `data/harness-index.json
 
 Each harness has two halves in the etna repo:
 
-- `plugins/<name>/` — the **plugin** (what a Claude Code plugin natively bundles): `definition.md` (manifest — identity + `skills:`/`rules:` lists), `agents/`, `hooks/`.
+- `plugins/<name>/` — the **plugin** (what a Claude Code plugin natively bundles): `definition.md` (manifest — identity + `skills:`/`rules:`/`agents:` lists), `hooks/`, and any unlisted, harness-specific `agents/`.
 - `harness/<name>/` — the **policy**: `CLAUDE.md` (pure policy, no frontmatter — installed as a verbatim copy) plus `index.md`, whose `plugin:` key names the plugin this harness pairs with. All harness-folder frontmatter lives in `index.md` alone.
 
 Two kinds of membership:
 
-- **Shared, listed** — skills and rules live in the flat top-level `skills/`/`rules/` catalogs, reusable across plugins. The manifest names the ones it pulls in:
+- **Shared, listed** — skills, rules, and agents live in the flat top-level `skills/`/`rules/`/`agents/` catalogs, reusable across plugins. The manifest names the ones it pulls in:
 
 ```yaml
 # plugins/code/definition.md
 ---
 name: code
 skills: [boundary, brainstorm, distiller, documentation, workflow-mapper]
-rules: [general, nomenclature]
+rules: [general, nomenclature, typescript]
+agents: [brainstorm, change-review, harness-manager, maintenance, performance-review, spec-mode]
 ---
 ```
 
-- **Owned, by location** — agents and hooks live inside the plugin (`plugins/<name>/{agents,hooks}/`). No list — membership is presence in the folder, exactly how a Claude Code plugin ships them.
+- **Owned, by location** — hooks (and any unlisted, harness-specific agents) live inside the plugin (`plugins/<name>/{agents,hooks}/`). No list — membership is presence in the folder, exactly how a Claude Code plugin ships them. Shared governance agents are listed instead (above) and resolved from the `agents/` catalog, local-first; a plugin can still drop its own copy beside it to override one by name.
 
-`scripts/build-data.js` (run by `prepack`) resolves the listed skills/rules from the catalogs and copies the plugin's `agents/` + `hooks/` wholesale into `data/harnesses/<folder>/`; a listed skill/rule that doesn't exist is a hard error. The marketplace channel (`.github/scripts/publish.mjs`) reads the same plugin folder, so both channels resolve identical membership — and both ship the plugin's hooks. The installer (`bin/etna.js`) reads from the bundle at install time; no GitHub fetch at runtime.
+`scripts/build-data.js` (run by `prepack`) resolves the listed skills/rules/agents from the catalogs (local-first), copies any unlisted plugin-owned agents plus the plugin's `hooks/` wholesale into `data/harnesses/<folder>/`; a listed skill/rule/agent that doesn't exist is a hard error. The marketplace channel (`.github/scripts/publish.mjs`) reads the same plugin folder, so both channels resolve identical membership — and both ship the plugin's hooks. The installer (`bin/etna.js`) reads from the bundle at install time; no GitHub fetch at runtime.
 
 ## Building / contributing
 

package/bin/etna.js

@@ -23,6 +23,7 @@ import {
 } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
 import * as p from '@clack/prompts';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -364,6 +365,36 @@ function parseArgs(args) {
     return { name, help, positional };
 }
 
+// npx caches aggressively: a bare `npx @nurix/etna` can re-run a STALE cached copy
+// long after a newer version is published (npm's packument cache resolves an old
+// `latest`, and npx reuses the matching unpacked install). To make `npx @nurix/etna`
+// always run the latest WITHOUT the caller remembering flags, check the registry on
+// startup and, if this copy is behind, re-exec the latest — `--prefer-online` defeats
+// the metadata cache and npx fetches the fresh tarball.
+//
+// Guards: ETNA_SELFUPDATED=1 is set on the child to stop an infinite re-exec loop;
+// ETNA_NO_SELFUPDATE lets a caller opt out (CI, offline, or running an intentionally
+// pinned/local-dev build). Degrades gracefully — any failure (offline, unauthed, npm/
+// npx missing) falls through to running THIS copy. @nurix/etna is restricted, so the
+// `npm view` reuses the caller's existing npm auth — the same auth that installed it.
+function selfUpdateOrReexec() {
+    if (process.env.ETNA_SELFUPDATED || process.env.ETNA_NO_SELFUPDATE) return;
+    const here = readJson(join(pkgRoot, 'package.json')).version;
+    if (!here) return;
+    const view = spawnSync('npm', ['view', '@nurix/etna', 'version', '--prefer-online'], {
+        encoding: 'utf8',
+    });
+    const latest = view.status === 0 ? (view.stdout || '').trim() : null;
+    if (!latest || latest === here) return; // current, offline, or unauthed → run this copy
+    const child = spawnSync(
+        'npx',
+        ['-y', '--prefer-online', `@nurix/etna@${latest}`, ...process.argv.slice(2)],
+        { stdio: 'inherit', env: { ...process.env, ETNA_SELFUPDATED: '1' } },
+    );
+    if (!child.error) process.exit(child.status ?? 0); // re-exec ran → hand off complete
+    // npx unavailable (child.error) → fall through and run this (older) copy.
+}
+
 async function main(args) {
     const idx = loadHarnessIndex();
     const harnesses = idx.harnesses || {};
@@ -405,6 +436,10 @@ async function main(args) {
     await installHarness(harnessName, harnesses);
 }
 
+// Before anything else: if a newer @nurix/etna is published, re-exec it (so a stale
+// npx-cached run still installs the latest harness). No-op when already current.
+selfUpdateOrReexec();
+
 main(process.argv.slice(2)).catch((e) => {
     p.log.error(e?.stack || String(e));
     process.exit(1);

package/data/harness-index.json

@@ -1,5 +1,5 @@
 {
-    "fingerprint": "4ab2f1f94f95",
+    "fingerprint": "e369db06df16",
     "harnesses": {
         "code": {
             "plugin": "code",
@@ -9,6 +9,10 @@
             "plugin": "discover",
             "description": "Product Discovery harness"
         },
+        "etna": {
+            "plugin": "etna",
+            "description": "the master store's own harness"
+        },
         "hr": {
             "plugin": "hr",
             "description": "Hiring / AI-Steering Evaluation harness"
@@ -16,6 +20,10 @@
         "kb-agi": {
             "plugin": "kb-agi",
             "description": "self-improving knowledge-base harness"
+        },
+        "mobile": {
+            "plugin": "mobile",
+            "description": "Nurix React Native + Expo harness"
         }
     }
 }

package/data/harnesses/code/harness.json

@@ -1,11 +1,11 @@
 {
   "harness": "code",
   "name": "code",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "files": [
     ".prettierrc.json",
     ".prettierignore",
     ".vscode/settings.json"
   ],
-  "digest": "3d1464ab6963"
+  "digest": "4c6c980d60f7"
 }

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
 
 ---
@@ -98,6 +99,7 @@ Each topic has one canonical location. Read from here, not from plans or changel
 | 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
@@ -117,6 +119,7 @@ Plan (Status: Draft) → Implementation → Feature Doc or Architecture Update
 - `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

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