@nurix/etna 0.19.1 → 0.19.2

package/data/harnesses/etna/CLAUDE.md

@@ -54,7 +54,7 @@ Three peer modes plus a Completion step — enter wherever the user's thinking a
 2. Flip the feature LLD to `status: active`; extend it in place with the how-it-works sections; confirm its `owns:` globs against the actual components.
 3. The `boundary` skill must already have gated this plan before its first implementation step — see Ownership, Boundaries & Documentation.
 
-**On Brainstorm Close** (when a session ends, not when a plan completes): close + harvest is the skill's `stop` procedure — the record moves from `docs/research/{topic}-brainstorming/` to `docs/history/brainstorms/{topic}/` as provenance, and conclusions disperse by scope (architecture docs, ADs, backlog).
+**On Brainstorm Close** (when a session ends, not when a plan completes): close + harvest is the skill's `stop` procedure — converge, a user-approved harvest manifest, apply, then a uselessness test; conclusions disperse by scope (architecture docs, decision records, backlog), the record moves from `docs/research/{topic}-brainstorm/` to `docs/history/brainstorms/{topic}/`, and the user decides whether the moved folder is deleted or committed.
 
 ---
 
@@ -129,7 +129,7 @@ When implementing a plan, if you discover work that is important but outside the
 - ❌ **Branches & Worktrees [override]** — never self-create git branches or worktrees; commit straight to the checked-out branch. This replaces any built-in "branch first on the default branch" default. Exception: when the user asks for a pull request, create the branch the PR requires before committing its changes.
 - ❌ **Protected Files** — before editing, if `docs/operations/protected-files.md` exists, read it and never modify any path it lists; never modify `AGENTS.md` or that file itself.
 - ✅ **Browser Automation** — Claude in Chrome / CDP browser tools only when the user explicitly asks.
-- ✅ **Delegate at scale** — offload large, independent, or parallelizable work (broad research, audits, multi-file sweeps) to sub-agents with self-contained prompts; keep small, well-understood edits inline. Sub-agents can't run skills or spawn sub-agents — do that work in the main session.
+- ✅ **Delegate at scale** — offload large, independent, or parallelizable work (broad research, audits, multi-file sweeps) to sub-agents with self-contained prompts; keep small, well-understood edits inline. Sub-agents can run skills and spawn their own sub-agents; keep work that needs the user's voice or the browser in the main session.
 - ⚠️ **Plans** — created directly in `docs/history/plans/` (see Workflows). Once `Status: Complete` or `Abandoned`, frozen — never edited. If scope changes after completion, write a new dated plan linking back.
 - ⚠️ **Tool Issues** — if any CLI tool, shell alias, or MCP tool behaves unexpectedly (syntax errors, silent failures, wrong defaults), report the exact tool, command, and error to the user so they can fix the underlying library.
 
@@ -148,4 +148,4 @@ For real code (the CLI under `packages/`, hook scripts):
 
 ## Runtime Notes
 
-etna runs in Claude Code. Sub-agent dispatch is the Agent tool; sub-agents can't run skills, spawn sub-agents, or hold the browser connection (browser work is Claude in Chrome, main session only). The user-level memory store is `~/.claude/` (auto-memory under `~/.claude/projects/...`). The ownership index and skill/agent descriptions are injected at session start; skills are invoked as slash commands (e.g. `/brainstorm start`). If pinning dispatch tiers: strong tier (opus-class) for judgment-heavy work, fast tier (sonnet-class) for mechanical fan-out — tier names go stale, re-check on model releases.
+etna runs in Claude Code. Sub-agent dispatch is the Agent tool; sub-agents can run skills and spawn their own sub-agents (probe-verified; re-verify on runtime updates), but cannot hold the browser connection (browser work is Claude in Chrome, main session only). The user-level memory store is `~/.claude/` (auto-memory under `~/.claude/projects/...`). The ownership index and skill/agent descriptions are injected at session start; skills are invoked as slash commands (e.g. `/brainstorm start`). If pinning dispatch tiers: strong tier (opus-class) for judgment-heavy work, fast tier (sonnet-class) for mechanical fan-out — tier names go stale, re-check on model releases.

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

@@ -1,35 +1,144 @@
 ---
 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
+description: The brainstorm twin — the paper-owning half of the brainstorm capability. Dispatched at session gates (start, on demand, pause, stop) by the `brainstorm` skill, never self-triggered and never conversing with the user. Scribe (distills the ops capture ledger into the working surface), editor (recomposes the thesis whole, diffs surfaced), harvester (drives the stop pipeline — manifest, apply, uselessness test, move), blindspot analyst (cold-reads the surface for unknown unknowns behind a four-test quality gate — grounded, material, new, answerable). Consumes the detector script for mechanical integrity and audits the five semantic sources the detector cannot judge. Writes every working-surface file; the facilitator writes only ops/capture.md and sync-log dispatch lines.
+tools: Read, Glob, Grep, Write, Edit, Bash, Task, Skill
+model: opus
 ---
 
-# Brainstorm Agent
+# Brainstorm Twin
 
-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 own the **paper** of a brainstorm session; the facilitator (the main loop running the
+`brainstorm` skill) owns the conversation. You are dispatched at gates with a session-folder path,
+a gate name, and a scope. You never talk to the user — anything needing their judgment goes back
+in your final report for the facilitator to relay.
 
-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.**
+The format contract is the skill's `references/session-schema.md` (resolve it beside this harness:
+`.claude/skills/brainstorm/references/` in a consumer repo, `skills/brainstorm/references/` in
+etna; also read `references/doctrine.md` for the epistemics). The mechanical half is the detector:
 
-## When to offer a session
+```
+node <skill>/scripts/detector.mjs <session-folder> [--gate=manifest|move] [--json]
+```
 
-- 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 its `decisions/` AD titles. The steering layer lives there; there are no `docs/modules/` or `docs/pillars/` folders. 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`.
+Run it at the start of every dispatch and again before you return. If node or the script is
+unavailable, say so loudly in your report and run the checks by hand from the schema — a missing
+detector is a flagged fact, never a silent skip.
 
-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.
+## The write protocol you enforce
 
-## Modes and the close gate
+One writer per file. You write `state.md`, `thesis.md`, `forks.md`, `ledger.md`, `fragments/`,
+manifest, and your own sync-log **result** lines. You never write `ops/capture.md` (the
+facilitator's) or sync-log dispatch lines. The user may hand-edit anything: before rewriting any
+file, read its current state in full and treat content you did not write as **first-class user
+signal — fold it forward, never clobber it**. A hand-edit that contradicts the ledger is a design
+question: file a fork, don't "fix" the file.
 
-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.
+## Every dispatch, in order
 
-## How you facilitate
+1. **Detector first** — `--gate=session`. Fix what is yours to fix (scribe-calls, below); report
+   what isn't.
+2. **Read the whole surface** plus every `ops/capture.md` entry since the last reconciled sync.
+3. **Scribe pass** — distill new capture into the surface, per the doctrine's epistemic rules
+   (distilled never verbatim; examples as examples; no naked pointers; both sides captured).
+   Residue that doesn't warrant filing stays in ops — that is what ops is for.
+4. **Semantic audit** — the five sources the detector cannot judge:
+   - **Cross-pillar contradiction** — across any two session files, `state.md` included (a state
+     file describing a session the pillars contradict is the historically strongest signal).
+   - **Aspect adequacy** — the detector checks that every mapped aspect *links* to content; you judge
+     whether the content actually covers it. Covered-in-name-only → a fork.
+   - **Basis drift** — decided divergence from `basis/` is fine; accidental divergence → a fork.
+   - **Tech conflicts** — anything violating the tech fragment (or the repo's `.claude/rules/`)
+     without a recorded deviation → a fork.
+   - **Self-containment** — read as the stranger you are (you were dispatched context-free; use
+     that): undefined terms, naked pointers, enumerations cited but never printed.
+5. **The scribe-call / design-call line** — an edit whose resolution doesn't change the design
+   (wording, bookkeeping, printing an enumeration, glossing a term) you apply directly and list.
+   An edit whose resolution changes the idea becomes a fork (`Raised by: twin (S#)` — cite your
+   own sync id). Never route a design question through a direct edit.
+6. **Editor pass** — recompose `thesis.md` whole (claim → argument → what changed), stamp
+   `Current as of:`, mirror the stamp into state.md `Last compose`, update the posture line.
+   Filing an insight must never push the session away from coherent: orphan evidence is a
+   scribe-note in your report, never a fork; free-floating insight may feed a thesis aspect.
+7. **Close the log** — append your result line to `ops/sync-log.md`:
+   `S# → reconciled | <ISO datetime> | N edits · M new forks · K open · untouched: <aspects>`
+   (or `S# → failed | <ts> | <reason>` — never omit the line; an unlogged dispatch reads as a
+   fabricated one). The one-line report is also the last line of your reply, plus anything the
+   facilitator must relay (design questions raised, what the recompose changed). When several
+   audit sources fire at once, rank integrity findings (attribution without evidence, files
+   contradicting the state) above coverage and staleness — a record that lies about its own
+   process is worse than one that merely stalled.
 
-- **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.
+## The blindspot pass (gate: on demand, scope: blindspot)
 
-You don't perform the harvest yourself, and you don't presume a destination. On close the skill **offers** the harvest, distilling the pillars' conclusions into wherever the harness routes them. The session folder — where it lives, and whether it is kept or transient — is whatever the `brainstorm` skill defines for this harness; the skill's `## stop` section is the canonical harvest map, so don't duplicate it.
+Dispatched when the user asks what they're missing, when the facilitator self-initiates at a
+frame-settling moment (usually widening a reconcile dispatch's scope), or on the accepted
+pre-converge offer. Run the standard dispatch order first so the surface is current, then
+re-read the whole surface plus `basis/` cold, measured against the thesis's claim — the stated goal — never against
+a generic checklist. The species that pay: an assumption the design rests on but never states; a
+concern no aspect owns; two required properties that pull against each other with nothing
+designing for either; a rule or path that can never fire; an ambiguity two files resolve
+differently; a shape matching a failure already recorded in the basis or ledger.
 
-## What you may write
+**The quality gate — a candidate passes all four tests or dies unsurfaced.** The gate exists so
+the user never over-replies to noise:
 
-The session folder only (its pillars and `state.md`), wherever the `brainstorm` skill places it for this harness. Never edit the live docs directly — the harvest does that.
+1. **Grounded** — it cites the specific surface or basis content that creates it. Raisable
+   against any project of this type without reading this folder → generic → dead.
+2. **Material** — some plausible answer changes the thesis, a commitment, or the aspect map.
+   Every answer leaves the design unchanged → dead.
+3. **New** — not a restatement of an open fork, a ledger decision or Declined line, or an
+   explicit park.
+4. **Answerable** — resolvable by a decision or a named investigation, not "think harder
+   about X".
+
+File each survivor as a fork (`Raised by: twin (S#)`, body opening `Blindspot:`) with a close
+condition — at most five per pass, ranked by materiality; fewer survivors means surface fewer,
+never pad. End your report with the survivors in relay shape (finding → why it's material here,
+citing the creating content → what answering it would change) plus the kill line — e.g.
+"killed 6: 4 generic, 1 restates F3, 1 immaterial" — so gate discipline stays auditable; the
+facilitator's capture persists it. A killed candidate re-raised unchanged in a later pass stays
+dead; new surface content that changes its gate verdict reopens it.
+
+## The stop pipeline (gate: stop — multiple dispatches)
+
+Stop is facilitator-orchestrated because approval belongs to the user; you execute each leg:
+
+1. **Converge support + manifest build.** Final scribe/audit/compose as above, then run
+   `--gate=manifest`. While it fails (open forks, uncovered aspects, stale compose), report what
+   blocks — you do not build a manifest over a failing gate. When clean, write `ops/manifest.md`
+   (`Status: proposed`): route by scope per the skill's `references/harvest.md` — every parked
+   fork, every fragment, the consolidated source of truth. Return the manifest body for approval.
+2. **Apply** (only after the facilitator reports approval; set `Status: approved` then work).
+   Read **both sides** of every destination before writing — the destination's current content is
+   a contract, not a blank page. Format each artifact via the `documentation` skill (Skill tool);
+   where unavailable, fall back to your own formatting **and record which path ran in the
+   manifest**. Set `Status: applied`. The apply is all-or-nothing and loud: if you cannot finish,
+   report exactly what applied and stop — the folder stays visibly unfinished and the user
+   restarts; never resume silently from a half-applied state.
+3. **Uselessness test.** Spawn a **fresh, context-free cold reader** (Task tool) whose prompt
+   contains only the allowed-path list (the manifest's destinations — never the session folder)
+   and the instruction to reconstruct the design: thesis, commitments, reasoning, declined
+   branches. Grade its reconstruction against the ledger and thesis. Gaps → record them in the
+   manifest (`Result: fail`, named gaps), and the fixes re-enter as a new manifest `Round`
+   requiring fresh approval. Pass → record it. If the Task tool is unavailable, report that the
+   facilitator must dispatch the cold reader — you, having read the folder, can no longer
+   cold-read.
+4. **Move.** Run `--gate=move`. When clean: delete `ops/` entirely, `git mv` the folder to
+   `docs/history/brainstorms/{topic}/`, set state `Status: harvested`, update both indexes
+   (`docs/research/Readme.md` row out, `docs/history/brainstorms/Readme.md` row in). End your
+   report with the offer the facilitator relays: **delete the moved folder, or commit it** — the
+   user decides; the design assumes deletion.
+
+## Strategy memory
+
+`docs/memory/brainstorm.md` (create on first write, entries dated `## YYYY-MM-DD — {topic}`):
+how to facilitate *this repo* better — recurring audit findings, harvest destinations that keep
+appearing, aspect-map patterns. Never session content, never user preferences.
+
+## Degradations — flagged, never silent
+
+- Detector unavailable → manual checks from the schema, loudly noted.
+- `documentation` skill unavailable → own-format harvest, recorded in the manifest.
+- Cold-reader spawn unavailable → hand the uselessness test back to the facilitator.
+- Anything else broken → `S# → failed` in the log with the reason, and say so in your report.
+  A loud early failure the user fixes beats silent damage discovered after the folder is gone.

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

@@ -92,6 +92,8 @@ For each changed file:
 
 **Backlog health.** Read `docs/history/backlog.md`. Report items older than 30 days. Count pending by priority.
 
+**Brainstorm session census.** A session folder still under `docs/research/` (`*-brainstorm/`, legacy `*-brainstorming/`) is by definition unfinished — the `brainstorm` skill moves folders to `docs/history/brainstorms/` only on a passed harvest. Read each one's state file and flag rot-open abandonment — derive last activity from the state's compose/sync stamps, falling back to file mtimes when the state file lacks activity timestamps (legacy formats do; git may be absent): a single-sitting session started more than 2 days ago, or any session whose last activity is stale past 14 days, gets a backlog item (`- **[P2]** Brainstorm session docs/research/{folder} appears abandoned (started {date}, last compose {date}) — resume it or run /brainstorm stop — discovered by maintenance`). Where the installed skill ships its detector (v3+), run `node .claude/skills/brainstorm/scripts/detector.mjs <folder>` and include failing rule IDs in the finding. Never remediate a session folder yourself — census findings are always report + backlog.
+
 ### Step 5: Remediate
 
 For each stale doc:
@@ -131,13 +133,13 @@ docs/
 ├── features/              # Feature specs — the only first-class doc unit (flat; ownership in each doc's `owns:` frontmatter)
 │   └── {group}/           #   browse-only subfolder for grouping; NEVER a module; may carry a Readme.md
 ├── operations/            # Setup, development, deployment, CI/CD
-├── research/              # Optional — in-progress brainstorm sessions ({topic}-brainstorming/) + standing research; Readme.md is the index
-│   └── {topic}-brainstorming/  #   created by the `brainstorm` skill; NOT scaffolded empty; moves to history/brainstorms/ on harvest
+├── research/              # Optional — in-progress brainstorm sessions ({topic}-brainstorm/; legacy -brainstorming/) + standing research; Readme.md is the index
+│   └── {topic}-brainstorm/     #   created by the `brainstorm` skill; NOT scaffolded empty; moves to history/brainstorms/ on a passed harvest
 ├── history/
 │   ├── CHANGELOG.md       # Master changelog index
 │   ├── changelog/         # Individual entries
 │   ├── plans/             # Implementation plans (Status field required)
-│   ├── brainstorms/       # Harvested brainstorm sessions ({topic}/), kept as provenance; Readme.md is the index
+│   ├── brainstorms/       # Harvested brainstorm sessions ({topic}/) — user decides kept (committed) or deleted; Readme.md is the index
 │   └── backlog.md         # Tracked work items by priority (P0-P3)
 ├── memory/                # index.md, main.md, {agent}.md — project knowledge + per-agent strategy memory
 └── tests/                 # Optional, author-maintained — create only if test docs exist
@@ -145,11 +147,11 @@ docs/
 
 There is **no `docs/routing.md`**, **no `docs/modules/{m}/`**, **no `docs/pillars/`**, **no `docs/boundaries/`**. Code ownership lives in feature `owns:` frontmatter; a module is a `module:` label, not a folder; boundaries are diagnosed from source; brainstorm records live in `docs/research/` (active) and `docs/history/brainstorms/` (harvested).
 
-> Brainstorm records are **author-created, never scaffolded** — the `brainstorm` skill writes an active session at `docs/research/{topic}-brainstorming/` and moves it to `docs/history/brainstorms/{topic}/` on harvest, kept (committed) as the provenance the steering pillars distil from. Recognize both as canonical: never flag them as docs "outside the structure" and never delete them during reconcile. Each folder carries a `Readme.md` index — keep it in sync with the folders it lists (every session has a row; no stale or missing rows), since the `brainstorm` skill reads the indexes instead of scanning.
+> Brainstorm records are **author-created, never scaffolded** — the `brainstorm` skill writes an active session at `docs/research/{topic}-brainstorm/` (legacy folders carry the older `-brainstorming/` suffix; treat both as canonical) and moves it to `docs/history/brainstorms/{topic}/` on a **passed harvest** — the move is the completion marker, and the moved folder's fate is the **user's decision: delete or commit**. Never flag either location as docs "outside the structure" and never delete a session folder during reconcile; a history folder present last pass and absent now is user-sanctioned deletion, never drift. Each folder carries a `Readme.md` index — keep it in sync with the folders it lists (every session has a row; a deleted folder's row is removed or annotated), since the `brainstorm` skill reads the indexes instead of scanning.
 
 ### Step B1 — Inventory and classify
 
-Glob every markdown file. Classify each: Architecture, Features, Operations, Plans, Changelogs, Backlog, Brainstorm records (stay), Stale/Deprecated (delete), Root docs (stay). For each topic keep the most complete version as canonical; extract unique content from the rest before deleting. **No redirect stubs** — when you move a file, delete the original and fix every reference (cross-doc links, memory files). Anything already under `docs/research/{topic}-brainstorming/` or `docs/history/brainstorms/{topic}/` is a **kept design record** — leave it in place untouched; never reclassify its pillars as Architecture/Stale or relocate them.
+Glob every markdown file. Classify each: Architecture, Features, Operations, Plans, Changelogs, Backlog, Brainstorm records (stay), Stale/Deprecated (delete), Root docs (stay). For each topic keep the most complete version as canonical; extract unique content from the rest before deleting. **No redirect stubs** — when you move a file, delete the original and fix every reference (cross-doc links, memory files). Anything already under `docs/research/{topic}-brainstorm/` (or legacy `-brainstorming/`) or `docs/history/brainstorms/{topic}/` is a **design record** — leave it in place untouched; never reclassify its contents as Architecture/Stale or relocate them.
 
 While reading each markdown doc to classify it, if the doc names a code symbol it asserts exists that **statically resolves to nothing**, note it as an observation for the Part A audit — **only** on stacks where static resolution is reliable (stay silent on codegen/reflection/DI/barrel stacks); scoped to docs already being read here, never a whole-repo prose sweep; **docs only**, never code-file comments.
 
@@ -167,7 +169,7 @@ This is what makes baseline more than a fresh scaffold. Detect old-shape artifac
 | `docs/OWNERSHIP_INDEX.md` (legacy derived ownership index) | delete — ownership is the union of feature `owns:` frontmatter, surfaced by the generated index |
 | `docs/operations/guardrails.md` | fold durable contract notes into `docs/architecture/` |
 | `docs/architecture/overview.md` | split into `domain-model.md` / `glossary.md` / `non-goals.md` / `references.md` / `open-questions.md` |
-| a legacy `docs/brainstorm/{topic}/`, or a root `brainstorm/`/`brainstorming/` folder | move each **active** record to `docs/research/{topic}-brainstorming/` and each **harvested** one to `docs/history/brainstorms/{topic}/` (dropping the suffix); create/refresh both `Readme.md` indexes; delete the emptied folder |
+| a legacy `docs/brainstorm/{topic}/`, or a root `brainstorm/`/`brainstorming/` folder | move each **active** record to `docs/research/{topic}-brainstorm/` and each **harvested** one to `docs/history/brainstorms/{topic}/` (dropping the suffix); create/refresh both `Readme.md` indexes; delete the emptied folder |
 | no `harness-version` in `structure.md` | stamp it (Step B4) |
 
 ### Step B3 — Present the reconcile plan, then execute

package/data/harnesses/etna/harness.json

@@ -1,11 +1,11 @@
 {
   "harness": "etna",
   "name": "etna",
-  "version": "1.1.6",
+  "version": "1.1.7",
   "files": [
     ".prettierrc.json",
     ".prettierignore",
     ".vscode/settings.json"
   ],
-  "digest": "d36860d99131"
+  "digest": "142ff7b5b3ab"
 }

package/data/harnesses/etna/skills/brainstorm/README.md

@@ -1,162 +1,56 @@
-# brainstorm
+# Brainstorm — process, not archive
 
-A Claude Code skill that is a **thinking partner for designing software** — not a form to fill in. It runs one constant loop (distill → abstract → sync → record) over a conversation, files the thinking into a small set of substance-first pillars, and treats _coherence_ as a measurable target rather than a vibe.
+A Claude Code skill that is a **thinking partner for designing large-scale software changes**.
+The session's product is the repo's living documentation: the conversation helps the user think
+correctly, the record stays readable at any pause, and the session ends with a harvest so
+complete that the session folder is useless — it moves to history and the user deletes or
+commits it.
 
-Two principles: **the conversation is the work; the artifacts serve it.** And — because conversations are mortal (context compacts, sessions end) — **the session folder is the only memory**: everything the session produces is captured there, distilled, or it doesn't survive.
+> Spec (single source of truth): `docs/features/brainstorm-skill/` in the etna repo. The etna
+> copy of this skill (`skills/brainstorm/`) is canonical; the user-level path
+> `~/.claude/skills/brainstorm/` is a symlink to it.
 
-> Spec (single source of truth): `docs/features/brainstorm-skill/` in the etna repo. The etna copy of this skill (`skills/brainstorm/`) is canonical; the user-level path `~/.claude/skills/brainstorm/` is a symlink to it.
+## The architecture — one capability, two seats
 
----
+Prose obligations decay in the conversing seat: the fleet audit behind v3 found the same rules
+dying in every real session, even the successful ones. So the capability is split:
 
-## The loop (the only constant)
+| Seat | Component | Owns |
+| --- | --- | --- |
+| Conversation (main loop) | `SKILL.md` — the facilitator | The dialogue, the basis gate, the moves, one write: appending everything to `ops/capture.md` |
+| Paper (dispatched agent) | `agents/brainstorm.md` — the twin, pinned strong tier | Every working-surface file: distilling ops into pillars, recomposing the thesis whole, the semantic audits, the harvest |
+| Integrity (script) | `scripts/detector.mjs` | Mechanical checks with stable rule IDs; blocks the manifest and the move while gates fail |
+| Quality (authoring-time) | `evals/` (never ships) | Session-replay scenarios, the two-agent audit, contrastive facilitation |
 
-Every turn, in every mode:
+Every twin dispatch is paired-logged in `ops/sync-log.md` — the facilitator writes the dispatch
+line, the twin writes the result — so reconciliation is observable, never asserted.
 
-1. **Distill** — fold what the user said into the pillars, in their framing, this turn.
-2. **Abstract** — name the latent structure they implied but didn't state (an entity relationship, an invariant, a principle). One offer per exchange.
-3. **Sync** — keep the pillars consistent with each other and with the basis (the sync agent, below).
-4. **Record** — the user's words land the turn they arrive; the facilitator's substance (analyses, diagnoses, reasoning, definitions, rejections) is on disk by the next sync dispatch at the latest. Nothing is hoarded for a session-end dump.
-
-Everything else — pillar count, ceremony, harvest — scales with the idea. The loop does not.
-
----
-
-## The memory contract
-
-v1's leak, measured in a full-session audit (2026-07-03): conclusions survived in the folder, but the facilitator's reasoning — causal diagnoses, informed rejections, definitions of cited terms — lived only in the transcript, and transcripts die at compaction. v2 plugs it with five rules and a recovery rule:
-
-1. **Both-sides capture** — facilitator substance is on disk by the next sync dispatch at the latest (that is the batch point; there is no other). Every dispatch begins with a filing checklist: list substantive contributions since the last sync, file anything unfiled. Knowledge still living only in chat when a sync dispatches is a violation.
-2. **Distilled, never verbatim** — capture is interpretation: the claim, the reasoning, the implication. General point recorded; examples cited as examples. (Integrity copies — printed enumerations, cited excerpts — are fine; the ban is transcript-pasting.)
-3. **Evidence notes** — session-produced research lands as dated files in `<session>/evidence/`, each stating what it examined, what it found, and which question or decision it feeds. `basis/` holds frozen inputs only.
-4. **No naked pointers** — enumerations printed once, terms glossed, external citations excerpted. A reader never needs the transcript or an external file to parse a pillar.
-5. **Eager rejections** — a knowingly-declined option materializes `rejected.md` immediately, with the evidence it was declined against.
-
-**Recovery:** after any compaction, re-enter from the folder alone; anything still "remembered" but not on disk is a leak — file it immediately.
-
----
-
-## Lifecycle
-
-Two subcommands, nothing else. The skill never auto-invokes on natural language.
+## The session lifecycle
 
 ```
-/brainstorm start    # open a session (requires a basis)
-/brainstorm stop     # close a session
+/brainstorm start
+  → basis gate (a document, an old session folder of any format, or a brain dump)
+  → bootstrap docs/research/{topic}-brainstorm/ (ops/ untracked; twin writes the surface)
+  → converse: dump / interview / probe / blindspot / converge — steerable in plain language
+  → "let me read" anytime: compose on demand, read the thesis, come back
+/brainstorm stop
+  → converge → manifest → ONE user approval → apply → uselessness test
+  → folder moves to docs/history/brainstorms/{topic}/ (the completion marker)
+  → the user decides: delete or commit
 ```
 
-### The entry gate
-
-A session needs substance before it opens. `start` asks for a **basis**: a reference document, or a one-shot brain dump of the whole idea. If the user drip-feeds small action items (a bug fix, a single button), the skill says it's the wrong tool and **does not open** unless overridden. The basis _is_ the first dump — the skill distills it into the initial thesis and questions, so the first questions come from the user's own material, never from an empty template.
-
-### Intake frame
-
-After distilling the basis, one `AskUserQuestion` batch sets three dials:
-
-- **Complexity** (low / medium / high) — sets the default pillar surface.
-- **Build mode** (greenfield / brownfield / hybrid) — lands in `build.md`; opens or closes the execution sections and sets the writing posture.
-- **Mode** — where the idea lives right now (see below).
-
-Then the skill proposes an **aspect map** — the thinking dimensions for _this_ idea — which the user edits. The map drives the sync's coverage audit.
-
-### Modes (who drives)
-
-| Mode | Driver | When | Behavior |
-| --- | --- | --- | --- |
-| **dump** | user | idea is in their head | No questions mid-stream. Distill live, reflect back shape + contradictions + implications. |
-| **interview** | skill | idea is fuzzy | Question batches of 2–3, one aspect at a time, each answer distilled immediately. |
-| **probe** | skill | idea is drafted | Adversarial pass — flaws, edge cases, conflicts. Each finding becomes a question. |
-| **converge** | shared | closing | Burn down open questions into decisions or explicit parks; ends with a mandatory sync. |
-
-Mode switches on an explicit user word. On a strong signal the skill _offers_ a switch in one line; it never seizes it.
-
----
-
-## Coherence (the doneness function)
-
-```
-coherent ⇔ open_questions == 0 ∧ last sync ran after the last pillar write
-```
-
-`questions.md` is the **single convergence currency**: flaws, gaps, contradictions, and uncovered aspects all funnel into it, whoever raised them. Convergence is one number going to zero. Zero means _"audited against the five sources and clean,"_ never _"nothing came to mind"_ — which is why the sync agent's audit contract is mandatory.
-
----
-
-## The sync agent
-
-The background reconciler. One sync in flight at a time; at most one queued behind it. It runs after substantive writes, mandatorily on entering converge and at `stop`, and on demand. Every dispatch begins transcript-side: the orchestrator lists its substantive contributions since the last sync and files anything unfiled — the sync agent can't see the conversation, so this checklist is the only bridge. Then it audits exactly five sources:
-
-1. **Cross-pillar contradiction** — thesis vs domain model vs decisions vs doctrine vs build.
-2. **Aspect coverage** — any mapped aspect with no content → a question.
-3. **Basis drift** — does the thesis still agree with the basis? Accidental divergence → a question.
-4. **Tech conflicts** — anything violating `tech.md` without a recorded deviation.
-5. **Self-containment** — the cold-reader pass: undefined terms, pointer-only references, unprinted enumerations, decided-vs-open ambiguity, stale citations. The sync agent runs context-free, so it *is* the zero-context reader the memory contract writes for.
-
-It applies **scribe-calls** (edits that don't change the design — including printing a missing enumeration or glossing a term) directly and notes them; it files **design-calls** (edits that change the idea) as questions and moves on — never interrupting to ask "apply now or defer?" Its one-line report ("4 edits · 2 new questions · 6 open · untouched: risks") is the only ambient convergence pressure the skill applies.
-
----
-
-## Pillars (substance first, lazy by default)
-
-Always present: `thesis.md`, `questions.md`, `decisions.md`, `build.md`. Materialized at medium+ complexity: `domain-model.md`, `tech.md`. Lazy (materialize on first real content at any complexity): `doctrine`, `glossary`, `non-goals`, `backlog`, `references`, `milestones` — and `rejected`, which is **eager**: it materializes the moment an option is knowingly declined.
-
-| File | Role |
-| --- | --- |
-| `thesis.md` | Running narrative of what we're designing + the aspect map. |
-| `questions.md` | Single convergence currency — every unresolved design call. |
-| `decisions.md` | Resolved calls with **Why** + **How to apply**. Append-only, no state machine. |
-| `build.md` | How the work executes: build mode, migration strategy, gotchas, rollout. |
-| `domain-model.md` | Information architecture — entities, relationships, cardinalities, state ownership. |
-| `tech.md` | Stack choices, seeded from harness rules; deviations recorded with whys. |
-| `evidence/` | Session-produced analyses as dated notes (`templates/evidence.md`) — each states what it examined and which question/decision it feeds. |
-| `doctrine` / `glossary` / `non-goals` / `backlog` / `rejected` / `references` / `milestones` | As their templates describe. |
-
-The complexity dial sets _defaults_, not a cage — any lazy pillar materializes the moment the conversation produces content for it.
-
----
-
-## Build modes
-
-The writing posture is a **mode** chosen at intake, folded into `build.md`:
-
-- **greenfield** (default) — present-tense everywhere, no phantom history. Execution sections closed.
-- **brownfield** — migration vocabulary is legitimate in `build.md`; other pillars still describe the target.
-- **hybrid** — new surface on a live system; execution sections apply to the seams only.
-
-`build.md` also captures **gotchas** — execution hazards known now, before plan mode, because surfacing them in plan mode is too late.
-
----
-
-## Exit artifacts
-
-The session writes a design record at `docs/research/{topic}-brainstorming/` (one folder per topic), moved to `docs/history/brainstorms/{topic}/` on harvest. At `stop`, after the final five-source sync (self-containment included — the record is verified standalone-readable exactly when it's about to become the only survivor of the session), the skill _offers_ what to **publish** from it (`AskUserQuestion`, multi-select — a session can emit more than one):
-
-- **Source of truth** — one consolidated, README-style canonical doc for the thing designed (`templates/source-of-truth.md`); lands in the repo's feature/architecture doc home, else a topic `Readme.md`.
-- **Plans** — one or more executable plan docs → `docs/history/plans/` (Status: Draft).
-- **Harvest into the living docs** — conclusions dispersed by scope into ADs (architecture decisions), the domain model, and the backlog.
-
-The session record is **kept** whichever you pick — never deleted; on harvest it moves to `docs/history/brainstorms/{topic}/` as the provenance every artifact traces back to. See `exit-artifacts.md`.
-
----
-
-## Hard rules
-
-1. **No production code outside the session folder.** Illustrative snippets are fine inside it.
-2. **Speak English to the user; codes (`Q3`, `D7`) live in the files.**
-3. **`AskUserQuestion` appears in exactly four places:** the intake frame, interview mode, converge picks, the `stop` exit-artifact pick.
-4. **Suggested, never seized** — mode shifts, abstractions, probes are offered once.
-5. **Nothing lives only in the transcript** — questions carry everything pending; the memory contract carries everything known.
-6. **No auto-invocation** — only `/brainstorm start` and `/brainstorm stop`.
-
----
+The working surface: `thesis.md` (claim → argument → what changed, recomposed whole, stamped),
+`forks.md` (open questions with close conditions — the only convergence currency), `ledger.md`
+(commitments: Decision / Why / How to apply / Resolves, declined options inline with re-evaluate
+conditions), `state.md` (anchor + the aspect map), `basis/`, `fragments/` (harvest-native,
+drafted in destination format), and untracked `ops/` (raw capture + sync log; deleted at stop).
 
 ## Files
 
-```
-brainstorm/                  # the skill (in .claude/skills/)
-├── SKILL.md          # the skill definition Claude Code loads (~2.2k words)
-├── README.md         # this file
-├── exit-artifacts.md # what /brainstorm stop publishes: source-of-truth / plans / harvest
-└── templates/        # pillar templates + evidence.md + source-of-truth.md, used in the record and at stop
-```
-
-The session itself is written to `docs/research/{topic}-brainstorming/` (committed; moved to `docs/history/brainstorms/{topic}/` on harvest) — not here.
+- `SKILL.md` — the facilitator hub
+- `references/doctrine.md` — thesis / forces / forks / commitments / consequences epistemics
+- `references/session-schema.md` — the single format authority (what the detector enforces)
+- `references/harvest.md` — the stop pipeline and routing map
+- `scripts/detector.mjs` — the rule registry (`node detector.mjs <folder> [--gate=…] [--json]`)
+- `scripts/fixtures/` — contrastive fixtures + runner (authoring-time; never ships)
+- `evals/` — session-replay + audit harness (authoring-time; never ships)