@nurix/etna 0.18.1 → 0.18.3

package/data/harnesses/discover/rules/ingestion.md

@@ -358,7 +358,7 @@ Under `research/<target>/dimensions/session/`:
 - **`captures/p*.md`** — per-phase narrative for the human: frontmatter (title, summary, scope, status), **Method** (taps run, actions taken), **Findings** (concrete values — URLs, fields, status codes), **Inferences**, **Diff vs reference**, **Open questions**. Decoded, opinionated; don't paste raw bodies here.
 - **`raw/*.json`** — verbatim endpoint captures for the reproducer: a `_meta` header (endpoint, auth-shape, captured_at, status, byte_length, redactions) + `body` (PII + secrets redacted) + `_decoded_fields`. Digest bodies > 50 KB into a structured summary.
 - **`curls.md`** — reproducible curl per endpoint, the auth model documented, a variables block, and an endpoint-catalog table.
-- **Visual / surface map** — `captures/screens/` (**preferred when available**): one annotated screenshot per primary surface (each major nav section), redact visible PII before saving. **When screenshot capture is unavailable** (e.g. the runtime lacks an image tool, or the app holds a persistent connection that never reaches page-idle), a **textual `captures/surface-map.md` is the accepted substitute** and satisfies this visual-map requirement — and the **visual-coverage gap is recorded in the `gaps:` frontmatter** so Evaluation reads a _known constraint_, not a silent miss.
+- **Visual / surface map** — `captures/screens/` (**preferred when available**): one annotated screenshot per primary surface (each major nav section), redact visible PII before saving. **When screenshot capture is unavailable** (e.g. the runtime lacks an image tool, or the app holds a persistent connection that never reaches page-idle), a **textual `captures/surface-map.md` is the accepted substitute** and satisfies this visual-map requirement — and the **visual-coverage gap is recorded in the `gaps:` frontmatter** so Evaluation reads a _known constraint_, not a silent miss. (The per-surface screenshot set is then **completed in Mode 4 — Cartography** (`cartography.md` §D), which re-enters the live product to capture each surface alongside its IA depth; the session-pass surface-map is the seed, the Cartography screens are the finished deliverable, and `screenshot_coverage` is the measured gap.)
 - **`captures/pass2-followup.md`** (optional, when Pass 2 is deferred/declined and it would help a later run resume) — the exact cheapest-mode write/generate actions + estimated cost that would close the write-side gap (§9.2). The `write_side_observed`/`pass2` frontmatter flags are mandatory; this file is the convenience.
 - **`_summary.md`** — the standard dimension bridge file (provenance frontmatter per §2) pointing into the above, so Evaluation treats session like any other dimension. `method: session-playbook`, `confidence: low` for Pass-1-only/inferred. **Session frontmatter additionally carries `write_side_observed: <true|false>` and `pass2: <not-applicable | offered-pending | declined-by-user | deferred | done>`** (§9.2) so Evaluation renders the write-side gap once, machine-readably.
 

package/data/harnesses/discover/rules/self-correction.md

@@ -1,6 +1,6 @@
 # Self-Correction — Defect Inspection · Run Measurement · Iterate-or-Propose
 
-The reference for **Mode 4** (`discover` harness). After a run finishes (Discovery → Ingestion → Evaluation), the self-correcting step does THREE things, in order:
+The reference for **Mode 5** (`discover` harness). After a run finishes (Discovery → Ingestion → Evaluation → Cartography), the self-correcting step does THREE things, in order:
 
 - **A. Inspect** the finished run against a built-in **defect checklist** → a concrete list of _behavioral defects_ in the prior steps (a list, never a vibe).
 - **B. Measure** the run against a fixed **rubric** → a score + vibe band. This runs **every iteration, including the final one** — the self-correcting step ALWAYS evaluates the current run.
@@ -8,7 +8,7 @@ The reference for **Mode 4** (`discover` harness). After a run finishes (Discove
 
 > **The two gates that bind this step (both unchanged):**
 >
-> 1. **Harness changes are approval-gated.** The main session presents `04-self-correction-proposal.md` and STOPS; nothing is applied until the user accepts per-item. Structural edits are flagged and never auto-applied.
+> 1. **Harness changes are approval-gated.** The main session presents `05-self-correction-proposal.md` and STOPS; nothing is applied until the user accepts per-item. Structural edits are flagged and never auto-applied.
 > 2. **Cost/state/credential actions are confirmation-gated.** The within-run iterate loop is **read-only / no-cost only.** Any fix needing a Pass-2 / credit-spend / state-change / credential action routes through the explicit-confirmation gate (ingestion §7 rule 4, §9.2) — never the auto-loop. The loop can never silently spend money or mutate an app to chase a score.
 
 ---
@@ -48,6 +48,17 @@ Inspect the run and emit **every** defect that fired, each as: `{mode, defect, s
 - **A gap not surfaced**, or a count-divergence rendered as a conflict instead of a range. _(low)_
 - **The published-vs-app-own API diff omitted** where a published API exists. _(med)_
 
+### Cartography defects (Mode 4 — the experiential / coverage layer)
+
+- **Marketed feature not located and not dispositioned** — a website/docs/changelog feature with no in-product route AND no `edition-gated | roadmap-not-shipped | over-claim | deeper-than-looked` disposition in `feature-coverage.md`. _(med — an unfilled coverage hole masquerading as "covered")_
+- **Located-but-not-walked not queued** — a feature found in the nav but never navigated, absent from the within-run re-walk queue (so Mode 5 never closes it). _(med)_
+- **Nav destination unmapped** — a top-level nav destination with no surface card in `information-architecture.md` (`ia_nav_complete:false` with no recorded reason). _(med)_
+- **Primary flow not diagrammed** — an identified core journey (a captured write/auth/realtime/AI wire) with no `ux-flows.md` sequence diagram. _(med)_
+- **Buried flagship not surfaced** — a marketing-promoted feature sitting at ≥D3 that the IA doc didn't flag as a positioning-vs-product gap. _(low)_
+- **Depth not recorded** — surface cards missing the numeric `Dn` depth measure (so promoted-vs-buried can't be reconciled). _(low)_
+- **Screenshot gap unrecorded** — primary surfaces without a screenshot AND no `screenshot_coverage` gap recorded (a silent visual-coverage miss vs an honest one). _(low)_
+- **Write flow drawn as observed on a `write_side_observed:false` run** — a generate/submit journey diagrammed solid (observed) when it was only inferred. _(med — same family as the evaluation write-side cap)_
+
 ### Cross-cutting defects
 
 - **Provenance frontmatter incomplete or dishonest** — `status`/`confidence` not matching reality. _(high)_
@@ -59,24 +70,25 @@ Inspect the run and emit **every** defect that fired, each as: `{mode, defect, s
 
 ## B. The measurement rubric (the score — always computed)
 
-Five axes, 0–20 each → **/100**, so iterations are comparable and "deteriorating" is a real drop, not noise. The score is a **heuristic to catch regression and give the loop direction** — not a precise grade.
+**Six axes → /100** (re-weighted from the prior five to give the experiential layer first-class weight), so iterations are comparable and "deteriorating" is a real drop, not noise. The score is a **heuristic to catch regression and give the loop direction** — not a precise grade.
 
-| # | Axis (0–20) | How to score |
+| # | Axis (max) | How to score |
 | --- | --- | --- |
-| 1 | **Coverage** | `20 × (dimensions captured 'complete' ÷ dimensions reachable per the access vector)`; **−4** per dimension blocked where Discovery predicted available. |
-| 2 | **Provenance integrity** | `10 × (captures with complete honest frontmatter ÷ all captures)` + `10 × (evaluation claims anchored+provenance-tagged ÷ all claims)`. |
-| 3 | **Reconciliation correctness** | start 20; **−3** per weighting violation (over-promotion, tiebreaker skipped, single-source-as-fact, count-divergence-as-conflict, published-vs-app diff missing where a public API exists). |
-| 4 | **Calibration & safety** | gaps/absences recorded honestly + confidence bands honest, scaled to 20. **A redaction miss hard-zeros this axis** and flags the run `unsafe` regardless of the others. |
-| 5 | **Defect load** | `20 − Σ(severity weight)` over stage-A defects (high=3, med=2, low=1), floored at 0. |
+| 1 | **Dimensional coverage** (15) | `15 × (dimensions captured 'complete' ÷ dimensions reachable per the access vector)`; **−3** per dimension blocked where Discovery predicted available. |
+| 2 | **Experiential / IA coverage** (20) | the Cartography scorecard, fed in: `8 × feature_location_rate/100` + `6 × flow_coverage/100` + `4 × screenshot_coverage/100` + `2 ×` (`ia_nav_complete` ? 1 : surface-cards ÷ top-level-destinations); **−2** per _claimed-but-not-located_ feature left **un-dispositioned**. Floored at 0. _(the heavily-weighted axis: a run that collects feature pages but never locates / walks / diagrams / screenshots them scores low here.)_ |
+| 3 | **Provenance integrity** (15) | `7.5 × (captures with complete honest frontmatter ÷ all captures)` + `7.5 × (evaluation claims anchored+provenance-tagged ÷ all claims)`. |
+| 4 | **Reconciliation correctness** (20) | start 20; **−3** per weighting violation (over-promotion, tiebreaker skipped, single-source-as-fact, count-divergence-as-conflict, published-vs-app diff missing where a public API exists, a UX-flow drawn observed on a `write_side_observed:false` run). |
+| 5 | **Calibration & safety** (15) | gaps/absences recorded honestly + confidence bands honest, scaled to 15. **A redaction miss hard-zeros this axis** and flags the run `unsafe` regardless of the others. |
+| 6 | **Defect load** (15) | `15 − Σ(severity weight)` over stage-A defects (high=3, med=2, low=1), floored at 0. |
 
-**Rollup:** sum the five → `score/100`. **Vibe band:** ≥85 strong · 70–84 solid · 50–69 thin · <50 weak. Plus a one-line gestalt (e.g. "solid coverage, but evaluation over-promoted two single-source claims").
+**Rollup:** sum the six → `score/100` (max 15+20+15+20+15+15). **Vibe band:** ≥85 strong · 70–84 solid · 50–69 thin · <50 weak. Plus a one-line gestalt (e.g. "solid wire capture, but cartography located only 9 of 17 marketed features and screenshotted none").
 
-**The iteration ledger** (written into `04-self-correction-proposal.md`):
+**The iteration ledger** (written into `05-self-correction-proposal.md`):
 
-| iter | score | Δ | cover | prov | recon | calib | defects | within-run fixes applied | remaining |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| 0 | … | — | … | … | … | … | … | (baseline) | … |
-| 1 | … | +n | … | … | … | … | … | re-mined entitlements; appended seam | … |
+| iter | score | Δ | dim | **ia** | prov | recon | calib | defects | within-run fixes applied | remaining |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| 0 | … | — | … | … | … | … | … | … | (baseline) | … |
+| 1 | … | +n | … | … | … | … | … | … | re-walked 4 surfaces; captured screenshots; located Rules engine | … |
 
 ---
 
@@ -84,8 +96,8 @@ Five axes, 0–20 each → **/100**, so iterations are comparable and "deteriora
 
 **Classify every stage-A defect by one test:** _does fixing it require editing a rule or an agent file?_
 
-- **No → within-run.** Fixable by re-running a Mode 1–3 step on THIS target, better (re-collect a dimension deeper, re-run a reconciliation pass, do a missed entitlements mine, run the §7-rule-10 second probe, append a forked catalog into `_shared/`, recover a blocked dimension after a trivial fix). **The main session auto-iterates these — no approval** (within the read-only/no-cost boundary).
-- **Yes → harness-changing.** A generic methodology fix the NEXT different target would also hit → accumulate into `04-self-correction-proposal.md`, **approval-gated** (present + STOP).
+- **No → within-run.** Fixable by re-running a Mode 1–4 step on THIS target, better (re-collect a dimension deeper, re-run a reconciliation pass, do a missed entitlements mine, run the §7-rule-10 second probe, append a forked catalog into `_shared/`, recover a blocked dimension after a trivial fix). **For Cartography defects this is the live re-walk:** re-enter the product (read-only nav) and walk the `feature-coverage.md` _located-but-not-walked_ queue, capture the missed screenshots, and locate any _deeper-than-looked_ marketed feature — then re-run Mode 4 and re-score. (A _claimed-but-not-located_ feature that is **edition-gated** / **roadmap-only** is _dispositioned_, not re-walked — re-walking can't find what isn't shipped.) **The main session auto-iterates these — no approval** (within the read-only/no-cost boundary; the live re-walk is pure navigation + screenshots, so it stays inside it — a feature is never _triggered_ to be located).
+- **Yes → harness-changing.** A generic methodology fix the NEXT different target would also hit → accumulate into `05-self-correction-proposal.md`, **approval-gated** (present + STOP).
 - A single defect may be **both**: fix it within-run now AND propose the rule so it never recurs.
 
 ### The loop (driven by the main session, not a sub-agent)
@@ -97,13 +109,13 @@ loop:
   within    = defects.where(within-run AND read-only/no-cost)
   harness   = defects.where(harness-changing)
   if within is empty:                  break     # CONVERGED
-  apply within-run fixes → run'                  # re-run the cheapest affected Mode 1–3 steps
+  apply within-run fixes → run'                  # re-run cheapest affected Mode 1–4 steps (incl. live re-walk)
   iter += 1; score[iter] = measure(run')         # stage B — ALWAYS measure
   if score[iter] < score[iter-1] - TOL:          # REGRESSION (clear drop, not noise)
       run = best; break                          #   revert to the best prior run, stop
   best = run = run'
   if iter >= CAP:                      break      # CAP ≥ 5
-present(harness) as 04-self-correction-proposal.md + the iteration ledger    # approval gate
+present(harness) as 05-self-correction-proposal.md + the iteration ledger    # approval gate
 ```
 
 **Stop conditions** (any one ends the loop):
@@ -114,7 +126,7 @@ present(harness) as 04-self-correction-proposal.md + the iteration ledger    # a
 
 ---
 
-## Output — `04-self-correction-proposal.md`
+## Output — `05-self-correction-proposal.md`
 
 ```markdown
 ---
@@ -128,7 +140,7 @@ iterations: <n>
 stopped_on: converged | regression | cap
 ---
 
-# <Target> — Self-Correction (Mode 4)
+# <Target> — Self-Correction (Mode 5)
 
 ## Run measurement (the final score + per-axis breakdown + the one-line vibe gestalt)
 
@@ -147,6 +159,6 @@ A **thin harness-change table with a high `run_score` and `stopped_on: converged
 
 ---
 
-## How Mode 4 uses this reference
+## How Mode 5 uses this reference
 
-Stage A — inspect against the checklist, emit the defect list. Stage B — score the run (always). Stage C — split within-run vs harness-changing; **auto-iterate** the within-run set (read-only/no-cost, ≥5 iterations capable, stop on regression/convergence/cap), re-measuring each round; **accumulate** the harness-changing set into the approval-gated proposal. Present the proposal + ledger and STOP. The main session applies accepted harness rows, flips them to APPLIED, logs the change, and (per ingestion / the orchestrator) mirrors to the harness home. Promote only what the next, different target would hit; prefer additive edits; structural edits are flagged, never auto-applied.
+Stage A — inspect against the checklist (now including the **Cartography** category), emit the defect list. Stage B — score the run (always), the **experiential / IA coverage** axis fed by the Cartography scorecard. Stage C — split within-run vs harness-changing; **auto-iterate** the within-run set (read-only/no-cost, ≥5 iterations capable, stop on regression/convergence/cap), re-measuring each round — Cartography defects iterate as the **live read-only re-walk** of the located-but-not-walked queue; **accumulate** the harness-changing set into the approval-gated proposal. Present the proposal + ledger and STOP. The main session applies accepted harness rows, flips them to APPLIED, logs the change, and (per ingestion / the orchestrator) mirrors to the harness home. Promote only what the next, different target would hit; prefer additive edits; structural edits are flagged, never auto-applied.

package/data/harnesses/hr/harness.json

@@ -1,7 +1,7 @@
 {
   "harness": "hr",
   "name": "hr",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "epoch": null,
   "files": [
     ".prettierrc.json",

package/data/harnesses/kb-agi/harness.json

@@ -1,7 +1,7 @@
 {
   "harness": "kb-agi",
   "name": "kb-agi",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "epoch": null,
   "files": [
     ".prettierrc.json",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nurix/etna",
-    "version": "0.18.1",
+    "version": "0.18.3",
     "description": "Bootstrap a project with a Nurix harness — copies the harness's CLAUDE.md, skills, agents, rules, and hooks directly into the project from a bundled payload (no marketplace fetch, no network).",
     "type": "module",
     "bin": {

package/data/harnesses/code-fable/.prettierignore

@@ -1,12 +0,0 @@
-# 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/code-fable/.prettierrc.json

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

package/data/harnesses/code-fable/.vscode/settings.json

@@ -1,10 +0,0 @@
-{
-  // 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/code-fable/CLAUDE.md

@@ -1,124 +0,0 @@
-# Agent Instructions
-
-This file defines how AI agents (Claude, GPT, etc.) should work on this project. **This file is the harness** — it orchestrates the skills and agents that do the work. There is no separate "harness skill."
-
----
-
-## Bootstrap
-
-> A missing `docs/structure.md` — or a `harness-version` behind the installed harness — is the **symptom** of a repo that isn't harnessed yet, or whose harness is out of date. Don't reconcile it by hand. Drive the **reconcile chain** — you (the main session) own it, because `harness-manager` is a sub-agent that can't run skills or spawn sub-agents:
->
-> 1. Invoke **`harness-manager`** (`"baseline this repo"` / `"reconcile the harness"`). It reconciles `docs/`, stamps the version, then hands back.
-> 2. If it hands back with a follow-up (typically the module proposal), re-invoke it to finish.
->
-> Then continue. Each component's internals live in the component, not here.
-
-This is the only step that runs **before** the harness exists; everything below assumes a reconciled repo.
-
----
-
-## 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.
-
----
-
-## Workflows
-
-Three peer modes plus a Completion step — enter wherever the user's thinking already is. Each mode is implemented by an agent + skill; the behavioural detail lives in those files, not here.
-
-| Mode | Enter when | Implemented by | Exits to |
-| --- | --- | --- | --- |
-| **Brainstorming** | explicit ask; or a user utterance challenges a loaded pillar headline → name the brushed principle and offer `/brainstorm start` (no auto-entry) | `brainstorm` agent + skill | Spec, Plan, or close + harvest |
-| **Spec** | new feature work | `spec-mode` agent + `documentation` skill | Plan |
-| **Plan** | a spec is approved | `documentation` skill → `docs/history/plans/YYYY-MM-DD-{slug}.md` | Completion |
-
-On **Completion**: freeze the plan (`Status: Complete`) and flip the feature spec to `Status: Active`, extending it with how-it-works sections; then distil the plan's trail — if the memory inbox (`docs/memory/inbox/`) holds entries, run `distiller facts` (inbox→fact-cards), then `distiller docs` for the just-completed feature's doc drafts any pending deltas for approval (presented, never auto-written). The `boundary` skill gates every approved plan before coding — it reads the source the plan touches and reports what would break (see **Boundaries** below); on brainstorm close, harvest by scope — module pillars → `docs/modules/{m}/pillars/`, cross-module doctrine + contract changes → `docs/architecture/` / ADRs, backlog → `docs/history/`. Open questions block close.
-
----
-
-## Context Routing
-
-Before modifying code in an unfamiliar area:
-
-1. If **[`docs/routing.md`](docs/routing.md)** exists, read it for file-pattern → module/doc/agent mapping. If it doesn't exist yet, skip.
-2. Glob `docs/{features,modules/*/features}/**/*.md` and check `owns` frontmatter to find the owning feature doc (rolled up to its module); read it — and, if it rolled up to a declared module, that module's `CLAUDE.md` + `pillars/` — before changes.
-3. If `qmd` is installed, `qmd query --format json -c <collection> "<topic>"` (repeat `-c` to span this repo's collections; `qmd collection list` names them) searches the indexed docs with their context attached — prefer it when entering an unfamiliar area; absent ⇒ skip.
-4. If your change touches a cross-cutting contract area (entity model, db schema, wire envelope, auth/authz, event vocabulary, webhooks, env/config), run the **`boundary`** skill scoped to your change — it reads both sides of each touched contract in source and reports what would break.
-5. If a `docs/memory/` file exists for the domain you're working in, read it for domain knowledge and failure modes
-6. When you author a declared module's docs, its `docs/modules/{m}/CLAUDE.md` auto-loads (the pillar bootstrap) — follow it. For code work it's surfaced via step 2.
-
-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/modules/{m}/features/`, or flat `docs/features/` if the module isn't declared) must include YAML frontmatter with `owns`, `touches`, and `depends_on` fields. Architecture docs describe cross-cutting patterns and don't own specific files; boundary docs own cross-cutting shapes, not file paths; operations docs describe procedures. Only feature docs need frontmatter.
-
-The spec-mode agent checks for ownership conflicts during research. If conflicts are found, address them in the spec before proceeding.
-
----
-
-## Boundaries
-
-A boundary is a horizontal cross-cutting contract — entity model, db schema, wire envelope, auth/authz, event vocabulary, webhooks, env/config — where editing one side silently breaks the other. Boundaries are **diagnosed, not documented**: the `boundary` skill reads them fresh from source whenever a check runs, so they are never persisted as docs and can never go stale.
-
-**Invoke the `boundary` skill after a plan is approved and before its first implementation step.** It parses the plan's Proposed Changes, reads the touched source files, identifies the contracts they participate in (its `references/boundary-taxonomy.md` is the catalog), traces the consumers on the other side, and reports severity-ranked violations with suggested plan amendments — in chat, read-only. Fold the amendments into the plan before coding. For non-plan edits in contract-heavy code, run the same diagnostic scoped to the diff.
-
-> Agents and skills live under `.claude/agents/` and `.claude/skills/`. Their triggers are model-invoked — refer to each component's frontmatter, not a registry table here.
-
----
-
-## 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. ❌ **Branches & Worktrees** – Never self-create git branches or worktrees. Commit straight to the checked-out branch; branch or create a worktree only when the user asks. ❌ **Protected Files** – Before editing, if `docs/operations/protected-files.md` exists, read it and never modify any path it lists; also never modify `AGENTS.md` or the `protected-files.md` file itself. ✅ **Browser Automation** – Use Chrome CDP / "Claude in Chrome" tools whenever they help (verifying UI, reproducing a flow, seeding or inspecting local data) — no need to ask first. **Main session only:** never drive the browser from a sub-agent or workflow executor — the session-bound Chrome connection destabilizes the sub-agent. A sub-agent that needs browser verification instead returns an explicit CDP checklist (exact URLs, actions, expected outcomes) for the orchestrator to execute in the main session. ✅ **Orchestrate via Sub-agents** – Run the main session as an orchestrator: delegate substantive work (research, implementation, audits) to sub-agents spawned via the Agent/Task tool with `model: opus` (Claude Opus), keeping the main context for dispatch, coordination, and synthesis. Give each sub-agent a self-contained prompt; parallelize independent dispatches. ✅ **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`
-
----
-
-## Documentation
-
-`docs/structure.md` is the authority on what belongs where — the folder map, naming, lifecycle, and the add-a-doc decision table. Read it before adding or moving a doc; don't restate it here. One canonical source per topic — link, don't copy. Only `CLAUDE.md`, `AGENTS.md`, and `README.md` live at the repo root.
-
-Maintenance triggers (act on these without re-reading `structure.md`):
-
-- After plan completion: add a `docs/history/changelog/` entry + update `docs/history/CHANGELOG.md` (no confirmation; include `Commits:` if multi-commit). Non-plan changes (refactors, fixes, API changes): prompt first.
-- When you add, move, or delete a doc: update `docs/routing.md` to match. When you move or rename source files: fix the `owns`/`touches` frontmatter in the owning doc; new docs that own code need `owns`/`touches`/`depends_on`.

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

@@ -1,35 +0,0 @@
----
-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/code-fable/agents/change-review.md

@@ -1,251 +0,0 @@
----
-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. Glob `./docs/{features,modules/*/features}/**/*.md` and read `owns` frontmatter to map churn to owning feature docs.
-
----
-
-# 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