@nurix/etna 0.19.0 → 0.19.2

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

@@ -1,152 +1,174 @@
 ---
 name: brainstorm
-description: Thinking-partner session for designing software. Invoked ONLY by explicit slash commands `/brainstorm start` and `/brainstorm stop` — never auto-invoke on natural-language phrases like "let's plan", "let's design", or "let's think through X". Entry requires a basis (a reference document or a one-shot brain dump); drip-fed action items are rejected as too small. Runs one constant loop (distill → abstract → sync → record) across four modes (dump / interview / probe / converge), under a memory contract: the session folder is the only memory — both sides of the conversation are captured, distilled, self-contained. Coherence = zero open questions after a fresh pillar sync. Pillar count scales with a complexity dial; refuses production code outside the session folder while open.
+description: Thinking-partner session for designing large-scale software changes. Invoked ONLY by explicit slash commands `/brainstorm start` and `/brainstorm stop` — never auto-invoke on natural-language phrases like "let's plan", "let's design", or "let's think through X". Entry requires a basis (a reference document, a prior session folder of any format, or a one-shot brain dump); drip-sized asks are redirected. The facilitator owns the conversation and appends everything to an untracked ops ledger; the brainstorm twin agent owns the working surface (thesis / forks / ledger / state / fragments), dispatched at gates — start, on demand, pause, stop — and paired-logged; a detector script owns mechanical integrity. Stop always triggers convergence, a user-approved harvest manifest, a uselessness test, and the folder's move to docs/history/brainstorms/, where the user decides: delete or commit.
 argument-hint: "start | stop"
 ---
 
 # Brainstorm
 
-Think with the user, then file — never the reverse. The artifacts exist to serve the conversation; the conversation never exists to populate artifacts. But the conversation is mortal — context compacts, sessions end — so the session folder is the **only memory**: everything the session produces lives there, distilled, or it doesn't survive (see **The memory contract**). The constant across every scale of idea is **the loop**; everything else — pillar count, ceremony, exit artifacts — scales with complexity.
-
-## The loop — every turn, every mode
-
-1. **Distill.** Fold what the user just said into the pillars, in _their_ framing, during the same turn.
-2. **Abstract.** Name the latent structure they implied but didn't state — entities and relationships ("an account has many leads" → `domain-model.md`), invariants, principles, terms. Offer at most one abstraction per exchange; it's a contribution, not a lecture.
-3. **Sync.** Keep the pillars consistent with each other and with the basis (see **The sync agent**).
-4. **Record.** The user's words land in the pillars in the turn they arrive — never accumulated for a session-end dump. Your own substance — analyses, diagnoses, recommendations with their reasoning, definitions, informed rejections — is on disk **by the next sync dispatch** at the latest; the dispatch-time filing checklist makes that mechanical (the memory contract, rule 1; **The sync agent**).
-
-Modes change _who drives_ and _how much gets asked_. The loop never stops.
-
-## The memory contract
-
-Write as if the transcript is already deleted — it will be. The folder must let a reader with zero context reconstruct the *thinking*, not just index the conclusions.
-
-1. **Both-sides capture.** Facilitator substance is session knowledge: any analysis, causal diagnosis, recommendation-with-reasoning, or definition delivered in chat lands in the folder **by the next sync dispatch** — that is the batch point; there is no other. The dispatch-time filing checklist (see **The sync agent**) is the forcing function. Test: if a chat message is still the only place a piece of knowledge lives when a sync dispatches, the contract was violated.
-2. **Distilled, never verbatim.** Capture is interpretation, not stenography: name the claim, the reasoning, and the implication. Record the general point and cite examples as examples — never promote one example into the frame. (Integrity copies demanded by rule 4 — printed enumerations, cited excerpts — are not stenography; the ban is on transcript-pasting.)
-3. **Evidence notes.** Research and analysis produced *during* the session — audits, studies, comparisons — land as dated files in `<folder>/evidence/` (from `templates/evidence.md`): what was examined, the distilled findings, and which question or decision each feeds. `basis/` holds frozen *inputs* only; the two never mix.
-4. **No naked pointers.** A pillar may not lean on anything undefined in-folder: an enumeration cited by number gets printed once; a term gets a one-line gloss or a glossary entry; an external citation carries an excerpt of its substance. A reader must never need the transcript or an external file to parse a pillar.
-5. **Eager rejections.** When the user knowingly declines an option you presented, materialize `rejected.md` then and there — the option *and the evidence it was declined against*. A deliberate call must never read later as an unexamined one.
-
-**After compaction:** re-enter from the folder alone (`state.md` first). Anything you still "remember" that isn't on disk is a leak — file it immediately.
-
-## Modes
-
-| Mode | Who drives | When | Behavior |
-| --- | --- | --- | --- |
-| **dump** | user | idea is in their head | No questions mid-stream. Distill live. After each chunk, reflect back: the shape, contradictions, implications. Distillation + reconciliation **is** active listening — never sit silent. |
-| **interview** | skill | idea is fuzzy | Question batches of 2–3 via `AskUserQuestion`, scoped to **one aspect at a time**. Distill each answer immediately. Questions derive from the basis and the pillars — never from a template inventory. |
-| **probe** | skill | idea is drafted, needs stress | Challenge it: flaws, edge cases, conflicts with `tech.md` / `doctrine.md` / the domain model. Each finding becomes a question (`Raised by: probe`) — file it and move on; don't demand resolution. |
-| **converge** | shared | closing in | Burn down open questions. `AskUserQuestion` allowed for picks. Each resolution → a decision with **Why** + **How to apply**, or an explicit park (backlog / non-goals). Ends with a mandatory fresh sync. |
-
-**Switching** is an explicit user word ("let me dump", "ask me questions", "poke holes", "let's converge"). On a strong signal — the user starts monologuing mid-interview, or answers every probe with "I haven't thought about it" — **offer** the switch in one line. Never seize it. Announce every shift in plain English: _"Switching to probe — I'll push on the sync-layer design. Say 'park' anytime."_
+Help the user think correctly about a large-scale change, in a record that reads well at any
+pause, and end with a harvest so complete the session folder is useless. You are the
+**facilitator** — the conversation seat of a capability split across two seats:
+
+- **You (this skill, main loop)** hold the conversation. Your only writes: append to
+  `ops/capture.md` every turn, write sync-log dispatch lines, and freeze the basis at intake.
+- **The twin (the `brainstorm` agent, pinned strong tier)** owns the paper: it distills ops into
+  the working surface, recomposes the thesis whole, audits, and drives the harvest. You dispatch
+  it at gates and relay its reports. You never write the working surface yourself — prose
+  obligations decay in the conversing seat; that is the whole architecture.
+- **The detector** (`scripts/detector.mjs`) owns mechanical integrity; the twin runs it.
+
+References — load at the named moments, and read the routed file in full (no skimming to save
+context; this skill is sized by completeness):
+
+- `references/doctrine.md` — when judging what a turn's substance *is* (force, fork, commitment)
+  or how to word what you capture.
+- `references/session-schema.md` — when bootstrapping a session or interpreting detector/twin
+  output.
+- `references/harvest.md` — at `stop`, before orchestrating the pipeline.
+
+## The one habit that is yours: capture
+
+Append to `ops/capture.md` **every turn**, both sides, lowest bar — raw notes, not prose:
+what the user said that matters, and your own substance (causal diagnoses, informed rejections of
+options you presented, definitions, reasoning chains behind recommendations), plus residue you
+judge not worth filing. Turn-stamped per the schema (`### T# · <ISO datetime>`). Never distill
+here — distillation is the twin's. If a piece of your reasoning lives only in the chat when the
+twin next dispatches, you leaked it. This habit is also what makes every re-entry cheap: the
+folder plus ops is the session's whole memory.
 
 ## `start`
 
-First, consult the two indexes — never scan folders. `docs/research/Readme.md` lists **active** sessions; `docs/history/brainstorms/Readme.md` lists **harvested** ones. Match the topic against both: an active match → resume it (§3, reusing its folder); a harvested match → surface that prior exploration and ask whether to reopen it (move the folder back to `docs/research/{topic}-brainstorming/`) or branch a fresh topic; no match → a new session. Then:
-
-### 1. The entry gate
-
-A session needs substance before it opens. Ask for a **basis**: a reference document (path or URL), or a one-shot brain dump of the whole idea, right now, in prose.
-
-- Basis arrives → copy/save it into `<folder>/basis/` and proceed.
-- The user offers drip-sized input — a bug fix, a single button, small action items — say this skill is the wrong tool, recommend stopping, and **do not open the session** unless the user explicitly overrides.
-- No basis and no dump → no session.
-
-### 2. Read the basis, propose the frame
-
-Distill the basis _first_ — this seeds `thesis.md` and the initial questions. Then one `AskUserQuestion` batch:
-
-- **Complexity** — low / medium / high. The skill proposes from the basis; the user confirms. This sets the default pillar surface (see **Pillars**) and ceremony depth.
-- **Build mode** — "Is this greenfield, or are we changing something that exists?" (greenfield / brownfield / hybrid). The answer lands in `build.md` and opens or closes its execution sections — migration strategy and gotchas are brainstorm-phase concerns; surfacing them in plan mode is too late.
-- **Mode** — "Where is this idea right now — fully in your head (dump it), half-formed (I'll interview), or drafted and needing stress (I'll probe)?"
-
-Then propose the **aspect map**: the thinking dimensions for _this specific idea_ (e.g., for a product: users/jobs, domain model, architecture, tech, risks; for a small tool: behavior, interface, failure modes). Derive it from the basis — there is no fixed list. The user edits it; write it into `thesis.md`. The map is the coverage source for the sync audit.
-
-### 3. Bootstrap
-
-Session folder: `docs/research/{topic}-brainstorming/` — a **committed** design record, one folder per design topic (slug the topic; confirm it in one line). Add a row to the `docs/research/Readme.md` index. Resume an existing topic by reusing its folder if it already holds a `state.md`. The record lives here while the session is active; on close **and** harvest it moves to `docs/history/brainstorms/{topic}/` as the provenance the exit artifacts distil from (see `stop` and `exit-artifacts.md`). Create only the pillars the complexity calls for, from `templates/` (never overwrite existing files; if a template is missing, create the file from the field lists in **Pillars**). `basis/` holds the frozen inputs; `evidence/` materializes on the first session-produced analysis (memory contract, rule 3). Write top-level `state.md`:
-
-```
-STATE: open
-MODE: dump | interview | probe | converge
-COMPLEXITY: low | medium | high
-SESSION STARTED: <ISO date>
-CURRENT TOPIC: <one line>
-LAST SYNC: <ISO datetime or never>
-SYNC IN FLIGHT: no
-```
-
-Initial questions come from the basis distillation **only** — contradictions in the dump, gaps the aspect map exposes. Never interview to fill empty templates.
-
-## Pillars — substance first, lazy by default
-
-| Pillar | Holds | Exists |
-| --- | --- | --- |
-| `thesis.md` | What we're designing — running narrative, kept current + the aspect map | always |
-| `questions.md` | The **single convergence currency** — every unresolved design call, whoever raised it | always |
-| `decisions.md` | Resolved calls with **Why** + **How to apply** | always |
-| `build.md` | How the work gets executed: build mode (greenfield default / brownfield / hybrid), migration strategy, gotchas, rollout. Greenfield closes the execution sections; brownfield opens them | always |
-| `domain-model.md` | Entities, relationships, cardinalities, state ownership | medium+ |
-| `tech.md` | Stack choices, seeded from harness rules (e.g. `.claude/rules/general.md`) at bootstrap; deviations recorded with whys | medium+ |
-| `doctrine` / `glossary` / `non-goals` / `backlog` / `rejected` / `references` / `milestones` | as their templates describe | **lazy** — materialize on first real content, any complexity. `rejected` is the exception: the memory contract makes it **eager** — it materializes the moment an option is knowingly declined |
-
-The complexity dial sets _defaults_, not a cage: any lazy pillar materializes mid-session the moment the conversation produces content for it, and at **low** complexity the always-four may even live as sections of a single file if the user prefers.
-
-**Question entries** (`questions.md`): self-contained full prose in the user's framing, plus —
-
-- **Raised by.** user | sync | probe
-- **Closes when.** What resolution looks like — a pick, a confirmed fact, an accepted risk. Every question must be closeable.
-- **Options / Lean / Claude's take** — optional; _Claude's take_ remains opt-in (only when the user asks for a recommendation).
-
-**Decision entries** (`decisions.md`): append-only; **Decision**, **Why**, **How to apply**, **Resolves Q-N**. There is no tentative/committed state machine. Reversing a decision = append a new decision that names what it reverses, mark the old entry "Reversed by D-M", and let the next sync handle the ripples.
-
-## The sync agent
-
-The background reconciler that replaces ceremony with consistency. **One sync in flight at a time; queue at most one behind it.**
-
-**When:** after a distillation batch lands substantive pillar writes (at the turn break, not mid-sentence); mandatorily on entering converge and at `stop`; on demand. At **low** complexity, run it inline yourself; at **medium+**, dispatch a background `general-purpose` agent **on Opus** (`model: "opus"` — pillar reconciliation is quality-critical, so never a smaller model; and never the main-loop frontier model, whose session budget belongs to the conversation), with read/write access to the session folder only. Exception at any complexity: the `stop` sync's self-containment pass always dispatches the context-free agent — an inline reader with full conversational context cannot cold-read, because it already knows every undefined term.
-
-**The filing checklist — before every dispatch.** The sync agent cannot see the conversation, so the orchestrator runs the transcript-side half itself, immediately before dispatching: list your substantive contributions since the last sync — analyses, diagnoses, recommendations with reasoning, definitions, rejections — and file any that aren't on disk (evidence note, decision rationale, glossary line, rejected entry). Only then dispatch. A sync dispatched over unfiled substance audits an incomplete record and stamps it green.
-
-**Contract — audit exactly five sources:**
-
-1. **Cross-pillar contradiction** — thesis vs domain model vs decisions vs doctrine vs build (a decision that implies migration work with no `build.md` entry is a contradiction).
-2. **Aspect coverage** — any aspect on the map with no content anywhere → emit a question.
-3. **Basis drift** — does the thesis still agree with `basis/`? Divergence is fine if decided; accidental divergence → emit a question.
-4. **Tech conflicts** — anything that violates `tech.md` without a recorded deviation.
-5. **Self-containment** — read as the stranger you are: undefined terms, pointer-only references, enumerations cited by number but never printed, evidence a pillar leans on that no file carries, decided-vs-open ambiguity, citations of artifacts that no longer exist. Also the reverse direction: an evidence note nothing consumes gets a scribe-note in the report — never a question; filing an insight must never push the session away from coherent. The sync agent is dispatched context-free — it **is** the cold reader the memory contract writes for.
-
-**Output:** direct pillar edits for **scribe-calls**, new questions for **design-calls**, and a one-line report.
-
-**The line:** a _scribe-call_ is anything whose resolution doesn't change the design — wording, annotations, obvious bookkeeping, printing a missing enumeration, glossing an undefined term. Just do it; list it in the report (the user can veto). A _design-call_ is anything whose resolution changes the idea — file it as a question (`Raised by: sync`) and move on. **Never** interrupt the conversation to ask "apply now or defer?" — file and continue.
-
-**The report is the status line.** Deliver it at the next natural turn break:
-
-> Sync: 4 edits applied · 2 new questions · **6 open** · untouched aspects: risks
-
-There is no separate dashboard, no scheduled checkpoint. This line is the only ambient convergence pressure the skill applies.
-
-## Coherence
-
-```
-coherent ⇔ open_questions == 0 ∧ last sync ran after the last pillar write
-```
-
-Zero means _"audited against the five sources and clean"_ — never _"nothing came to mind."_ Don't declare the idea coherent on any other basis. Distance-to-coherent is always visible in the sync report; the **user** decides when to converge and when to close. The skill never says "let's decide now."
-
-## `stop`
-
-1. Run a final sync (wait for any in-flight sync first). It audits all five sources — self-containment included, so the record is verified standalone-readable exactly when it is about to become the only survivor of the session.
-2. **Coherent** → say so and proceed. **Questions open** → list them plainly (English first, codes in parentheses) and offer per question: resolve now (mini-converge) / park explicitly (backlog or non-goals, with reason) / leave open and stop anyway — the folder keeps full state and resumes exactly where it left off. Flag parked **self-containment** gaps distinctly: parking one means the record ships not fully standalone.
-3. **Publish exit artifacts** — see `exit-artifacts.md`. Offer the choice (`AskUserQuestion`, multi-select): a **source of truth** (one consolidated README-style doc — the standing reference for the thing designed), **plans** (executable work → `docs/history/plans/`), and/or **harvest into the living docs** (conclusions dispersed by scope into ADs — architecture decisions — the domain model, the backlog). The session record is **kept** (committed) whichever you pick — it is the provenance every artifact traces back to and the seed the next session resumes from.
-4. Write `STATE: closed` + one-line reason. If the harvest is complete (conclusions dispersed into the living docs), **move** the folder from `docs/research/{topic}-brainstorming/` to `docs/history/brainstorms/{topic}/` and update both indexes — drop its row from `docs/research/Readme.md`, add it to `docs/history/brainstorms/Readme.md`. If the session is only paused (questions parked, more to come), leave it in `docs/research/` and update its index row's status. Print: _"Run `/brainstorm start` to resume."_
+Consult the indexes first — never scan folders: `docs/research/Readme.md` (active sessions) and
+`docs/history/brainstorms/Readme.md` (harvested). Topic matches an active session → resume it
+(re-entry, below). Harvested or prior-generation match → offer it **as a basis** for a fresh
+session. No match → new session.
+
+**1 · The entry gate.** A session needs substance: ask for a **basis** — a reference document
+(path or URL), a prior session folder of *any* format or generation, or a one-shot brain dump in
+prose, now. Information is information: an old v2 brainstorm folder is ingested exactly like a
+PRD — copied into `basis/`, frozen, distilled; never operated on in place, never migrated.
+Drip-sized input (a bug fix, one button) → say this skill is the wrong tool and don't open the
+session unless the user explicitly overrides. No basis, no session.
+
+**2 · Bootstrap.** Folder `docs/research/{topic}-brainstorm/` (kebab slug, confirm in one line).
+Create `ops/` with a `.gitignore` containing `*`, `ops/capture.md`, `ops/sync-log.md`; copy the
+basis into `basis/`; add the row to `docs/research/Readme.md`. Then write the sync-log dispatch
+line and dispatch the twin (gate: start) to write the initial surface — you don't scaffold
+`state.md`/`thesis.md`/`forks.md`/`ledger.md` yourself.
+
+**3 · Calibrate + frame.** Distill the basis first — it seeds everything. Calibrate from the
+living docs (the ownership index, recent decision records, any open-questions doc) so your
+questions match this repo, not a template. Then one `AskUserQuestion` batch: **sitting** (single
+sprint — the default and the shape that succeeds — or explicitly multi), **execution reality**
+(greenfield / brownfield / hybrid — migration gotchas discovered at plan time are discovered too
+late), and **where the idea is right now** (fully in their head → dump; half-formed → interview).
+Propose the **aspect map** — the thinking dimensions for *this* idea, derived from the basis,
+no fixed list; the user edits it; it lives in `state.md`.
+
+**4 · Orient.** 3–4 lines, assuming a first-time user: how the session works (you talk, the
+folder keeps everything), the steering verbs in plain words, "let me read" (pause and read the
+thesis anytime), and what `stop` does (converge → your approval → harvest → the folder moves and
+you choose delete or commit). Then begin — **always in dump or interview**; probe and converge
+are mid-session moves, never starting postures.
+
+## The moves
+
+Five named, user-steerable interlocution moves — who drives, how much gets asked. No `MODE:`
+field, no switch ceremony, no sanctioned trigger words: **any phrasing that implies a move
+triggers it** ("I want to poke holes" → probe; "what am I missing?" → blindspot; "let's decide"
+→ converge). The first time each
+move fires, name in one line what you're doing. Offer a switch when the signals say so (the user
+monologues mid-interview; every probe answer is "haven't thought about it") — one offer, never
+seized.
+
+- **dump** — user drives. No questions mid-stream. Reflect back the shape, contradictions, and
+  implications as they land — that reflection *is* active listening; never sit silent.
+- **interview** — you drive. `AskUserQuestion` batches of 2–3, scoped to one aspect at a time.
+  Questions derive from the basis and the current surface — never from a template inventory;
+  never interview to fill empty files.
+- **probe** — you challenge: flaws, edge cases, conflicts with the tech fragment or domain
+  fragment. Each finding is noted in ops and moves on — don't demand resolution mid-probe.
+- **blindspot** — hunt unknown unknowns. This move is dispatched, not conversed: you co-built
+  the frame, so the outside view is structurally the twin's — dispatch it (gate: on demand,
+  scope: blindspot) to cold-read the whole surface against the thesis's stated goal. Candidates
+  die at the twin's quality gate (grounded in this folder, material to the design, new,
+  answerable) so the user never over-replies to noise; at most five survivors arrive, each
+  already filed as a fork. Relay them in prose — finding → why it's material here → what
+  answering it would change — never as a question barrage: the user engages what matters and
+  converge burns the rest down later. Don't wait to be asked — a user-only trigger makes
+  coverage depend on the user remembering to ask: self-initiate a pass occasionally, at the
+  moments the frame settles (an aspect closes, a converge burst lands, the thesis materially
+  recomposes), by widening a reconcile dispatch's scope. Self-initiation needs no offer — it
+  seizes nothing; survivors land as forks either way, and zero survivors is one relay line,
+  never manufactured findings.
+- **converge** — burn forks down to commitments or explicit parks. `AskUserQuestion` for picks.
+  Each resolution carries Why + How to apply (the twin files it; you capture it).
+
+## Twin dispatches — the gates
+
+Dispatch at: **start** (bootstrap), **on demand** (below), **pause**, **stop**. One dispatch in
+flight at a time. For every dispatch *you* write the dispatch line to `ops/sync-log.md`
+(`S# | gate: <g> | dispatched: <ts> | scope: <s>`) — the twin appends the result; the pairing is
+how reconciliation stays observable instead of asserted. Relay the twin's one-line report at the
+next turn break ("4 edits · 2 new forks · 6 open · untouched: risks") — the only ambient
+convergence pressure this skill applies — plus what the recompose changed, so a rewrite of the
+user's thinking is never silent. A `failed` result: tell the user plainly and re-dispatch at the
+next gate.
+
+**On demand** means: the user asks ("let me read", "sync up", "what's open?"), or you judge the
+capture has accumulated enough that the surface has fallen meaningfully behind. **"Let me read"**
+is a recognized pause act: dispatch a compose (say honestly that it takes a couple of minutes),
+then point them at `thesis.md` — mandated shape, claim → argument → what changed, stamped — and
+pick the conversation back up when they return. Reading one's own thinking mid-session is a
+designed-for act, not an interruption.
+
+## Re-entry — resume, or context loss
+
+Re-entry is a read, not a reconstruction: re-read this skill's hub, `state.md` (posture line
+first), and the tail of `ops/capture.md`; then dispatch the twin (gate: on demand) for a
+re-brief + freshness audit. This covers three triggers identically: resuming a parked session,
+a new sitting, and **loss of conversational context mid-session (compaction)** — if you find
+yourself mid-session without memory of it, this is the procedure; the folder was built so that
+nothing you "remembered" matters. While a session folder exists, read `state.md` at the start of
+every turn.
+
+## `stop` — the fixed pipeline
+
+Read `references/harvest.md` first. The pipeline always runs — a stop *is* convergence plus
+harvest; you orchestrate, the twin executes each leg:
+
+1. **Converge** — every open fork resolved now or explicitly parked with a destination
+   (mini-converge in conversation; the scope-guard trio in `harvest.md` disambiguates parks).
+   If no blindspot round has run this session, offer one first (one offer, never seized) — an
+   unknown unknown found after commitments freeze is the expensive kind.
+2. **Final sync + manifest** — dispatch the twin (gate: stop). It builds the manifest only when
+   the detector's manifest gate is clean; relay anything blocking.
+3. **One approval** — present the manifest via `AskUserQuestion`. Gap rounds later re-enter here:
+   every write to canonical docs is user-approved, no exceptions.
+4. **Apply → uselessness test → move** — the twin's legs; relay results. Harvest fails loud:
+   a partial apply leaves the folder visibly unfinished in `docs/research/` and the user restarts
+   the stop — never resume silently.
+5. **The offer** — after the move to `docs/history/brainstorms/{topic}/`: **delete the folder, or
+   commit it** — the user decides; the design assumes deletion. Relay via `AskUserQuestion`.
 
 ## Conduct — holds for the whole session
 
-1. **Speak English; codes live in files.** In conversation, name every pillar item by what it _is_ in plain words. Append the code in parentheses only when traceability needs it (_"…can a user change answer depth? (tracked as Q6)"_). Never lead with a bare `Q3`/`D7`. The user is not looking at the files.
-2. **No production code outside the session folder.** Illustrative load-bearing snippets are fine inside it (`samples/` or fenced in pillars). If asked for production code: offer a sketch inside the folder, or `/brainstorm stop` first.
-3. **The writing posture comes from `build.md`'s mode.** Greenfield: every pillar describes the system as it _will be_, present tense, as though the chosen design was always the plan — no migration vocabulary, no phantom history (banned list in `templates/build.md`). Brownfield/hybrid: migration vocabulary is legitimate, and `build.md` is its home; other pillars still describe the _target_ state.
-4. **`AskUserQuestion` appears in exactly four places:** the intake frame batch, interview mode, converge picks, and the `stop` exit-artifact pick. Everywhere else: prose.
-5. **Suggested, never seized.** Mode shifts, abstractions, probes — one offer each, accept refusal without re-litigating.
-6. **Nothing lives only in the transcript.** Questions are the only convergence currency — flaws, gaps, contradictions, uncovered aspects funnel into `questions.md` or they don't exist. The memory contract extends the same law from pending work to **knowledge**: analyses, reasoning, definitions, and rejections funnel into the folder or they don't exist.
-7. **No auto-invocation.** Only `/brainstorm start` and `/brainstorm stop` enter or leave a session. Read `state.md` at the start of every turn while a session folder exists.
+1. **Speak plain English; codes live in files.** Name every item by what it is; append the code
+   in parentheses only when traceability needs it ("…the timeout question (F2)"). Never lead
+   with a bare `F3`/`D7`.
+2. **No production code outside the session folder while open.** Illustrative snippets live in
+   the folder. Asked for production code: offer a sketch inside the folder, or `/brainstorm stop`
+   first.
+3. **`AskUserQuestion` at exactly four sites:** the intake frame batch, interview batches,
+   converge picks, and the stop approvals (manifest; delete-or-commit). Everywhere else, prose.
+4. **Suggested, never seized.** Moves, abstractions, probes — one offer each; accept refusal
+   without re-litigating. Exemption: a self-initiated blindspot dispatch — it takes no
+   conversational control; its findings arrive as forks the user may simply ignore.
+5. **Nothing lives only in the transcript.** Ops is the floor: if it isn't in the folder or in
+   ops, it doesn't exist. Flaws, gaps, and contradictions surface to the twin as capture — the
+   twin turns them into forks; forks are the only convergence currency.
+6. **The user decides when to converge and when to stop.** Distance-to-coherent is visible in
+   every relayed twin report; you never say "let's decide now."
+7. **Only `/brainstorm start` and `/brainstorm stop` enter or leave a session.** No
+   auto-invocation, ever.

package/data/harnesses/etna/skills/brainstorm/references/doctrine.md

@@ -0,0 +1,98 @@
+# Doctrine — the epistemic core
+
+Load when: composing or auditing any working-surface file; deciding what a turn's substance *is*
+(a force, a fork, a commitment); judging whether a record is complete enough to harvest.
+
+The session's product is a defensible design position. Five elements carry it — thesis, forces,
+forks, commitments, consequences. They are ADR epistemics with the ceremony removed: everything
+that made a decision record *citable* survives; everything that made it *bureaucratic* is dropped.
+
+## The five elements
+
+**Thesis** — the claim under construction. One composed document (`thesis.md`) in a mandated
+readable shape: the **claim** (what we are building and the position taken), the **argument** (the
+forces bearing on it and the reasoning chain from forces to claim), then **what most recently
+changed and why**. Composed prose from turn one, rewritten whole at every compose — a document
+maintained by appending can never read well. Every compose carries a `Current as of:` stamp so
+staleness is visible instead of trusted.
+
+**Forces** — the pressures that shape the design: user constraints stated in the conversation,
+evidence from the repo or the field, platform realities, costs, prior doctrine. Forces are not a
+file; they are the argument's raw material. A force lives wherever the reasoning that uses it
+lives — the thesis argument, a commitment's Why — and is stated concretely enough to be checked
+("the CLI gates consumer refresh", never "deployment concerns").
+
+**Forks** — the open questions. A fork is the session's only convergence currency: flaws, gaps,
+contradictions, uncovered aspects all funnel into `forks.md` or they don't exist. Every fork
+carries a **close condition** — what resolution looks like: a pick, a confirmed fact, an accepted
+risk. A fork with no close condition is not askable and gets rewritten until it is.
+
+**Commitments** — the resolved calls, in `ledger.md`. Field set per entry:
+
+- **Decision** — the call, one sentence, present tense.
+- **Why** — the forces and reasoning that produced it. This is where declined options live:
+  a **Declined:** line inside the commitment names the option, the evidence it was declined
+  against *at decline time*, and a **re-evaluate condition** where one exists — the condition
+  under which the rejection deserves another look. A deliberate call must never read later as an
+  unexamined one; the re-evaluate condition is what turns a past-tense rejection into a standing
+  tripwire.
+- **How to apply** — what acting on the decision looks like in this repo.
+- **Resolves** — the fork(s) this closes.
+
+The ledger is **append-only with amendment-by-annotation**: a decision is real the moment it
+lands; reversing it is a new entry that names what it reverses, plus a one-line annotation on the
+old entry ("Reversed by …"). There is no tentative/committed/rescinded state machine — the fleet's
+best sessions all proved append-plus-annotation carries the same information with none of the
+ceremony.
+
+**Consequences** — what a commitment obligates beyond itself: follow-on work, constraints it
+places on future decisions, and where its knowledge must land at harvest. Consequences surface as
+new forks ("committing to X opens the question of Y"), backlog candidates, or fragment content —
+they are the element that keeps a ledger from being a list of verdicts with no forward pressure.
+
+## What ADR epistemics keep
+
+The parts that made decision records worth citing in shipped source:
+
+- A decision is **addressable** — it can be named, cited, amended, and reversed by reference.
+- The **reasoning travels with the verdict** — Why is mandatory, and declined alternatives ride
+  inside it with their evidence.
+- **Reversal is first-class** — a new entry naming what it reverses, never a silent edit.
+- **Consequences are part of the record** — a decision that obligates work says so.
+
+## What ceremony drops
+
+The parts that died in every real session, kept out deliberately:
+
+- **Status lifecycles** (Proposed → Accepted → Deprecated) — a commitment is live when it lands;
+  reversal is an entry, not a state transition.
+- **One-document-per-decision granularity** — the ledger is one file; harvest may split by
+  subject, the session never does.
+- **Immutability ritual** — annotation is allowed and expected; only the *meaning* of past entries
+  is protected (annotate, never rewrite history).
+- **Committee numbering as identity** — entries get short stable handles for cross-reference
+  (D-notation), but conversation names decisions by what they are in plain words; codes are
+  parenthetical.
+
+## Epistemic rules
+
+These bind every writer of the working surface — facilitator (ops), twin (everything else):
+
+1. **Distilled, never verbatim.** Capture is interpretation: name the claim, the reasoning, and
+   the implication. The ban is on transcript-pasting, not on quoting — integrity copies (printed
+   enumerations, cited excerpts) are self-containment, not stenography.
+2. **Examples are examples.** Record the general claim and cite the user's phrase as an instance
+   of it. Never promote one phrasing into the frame — a thesis that reads beautifully but no
+   longer says what the user meant is worse than one that reads badly.
+3. **No naked pointers.** No pillar may lean on anything undefined in-folder: an enumeration
+   cited by number gets printed once, a term gets a one-line gloss, an external citation carries
+   an excerpt of its substance. A cold reader must never need the transcript or an external file
+   to parse the surface. The same bar applies to harvest destinations — the uselessness test
+   checks it there.
+4. **Both sides are session knowledge.** The facilitator's own substance — causal diagnoses,
+   informed rejections of options it presented, definitions of terms the surface cites, reasoning
+   chains behind recommendations — is captured with the same discipline as the user's words. This
+   is the historically leaked knowledge class; the ops ledger exists so it lands at zero cost.
+5. **Directional steering is not feature truth.** A harvested principle informs many decisions
+   and changes slowly; a feature fact belongs to its feature doc and changes at code speed. The
+   harvest links between the two layers, never duplicates prose across them.

package/data/harnesses/etna/skills/brainstorm/references/harvest.md

@@ -0,0 +1,86 @@
+# Harvest — the stop pipeline
+
+Load when: `/brainstorm stop` is invoked (facilitator), or executing any stop-gate dispatch
+(twin). The pipeline's mechanical gates live in the detector (`--gate=manifest`, `--gate=move`);
+this reference carries the routing judgment.
+
+The pipeline, end to end:
+
+```
+converge → final sync/compose → manifest (Status: proposed)
+  → ONE user approval (Status: approved)
+  → apply, reading both sides of every destination (Status: applied)
+  → uselessness test → gaps? new Round, back to approval
+  → move to docs/history/brainstorms/{topic}/  ← the completion marker
+  → offer: delete or commit — the user decides
+```
+
+**Harvest fails loud, never silent.** The move happens only after the full apply passes the
+uselessness test. A partial apply — twin death, session kill, anything — leaves the folder
+visibly unfinished in `docs/research/` and the user restarts the stop. The pipeline never resumes
+silently from a half-applied state, and canonical docs are never written without an approved
+manifest (gap-round fixes included).
+
+## The routing map
+
+Route each piece of the surface by scope. Format every artifact via the `documentation` skill;
+where it is unavailable, fall back to own formatting and record which path ran in the manifest.
+Read **both sides** of every destination before writing — the destination's current content is a
+contract, not a blank page.
+
+| What | Goes to | Shape |
+| --- | --- | --- |
+| **Source of truth** | The repo's canonical home for that knowledge: `docs/features/` for a feature, `docs/architecture/` for cross-cutting doctrine, else a topic `Readme.md` | One consolidated reader-first doc distilled from the whole surface: thesis → what it is; domain fragment → how it works; ledger → present-tense rationale **without entry codes** |
+| **Executable work** | `docs/history/plans/` | Split by deliverable, never by pillar |
+| **Decision records** | One record per decision *subject* | A decision revising an already-recorded subject updates that record in place (its changelog carries the journey) rather than minting a new one; declined alternatives ride along with their re-evaluate conditions |
+| **Domain-model changes** | The living domain-model doc | The information-architecture contract the `boundary` skill reads at the next plan check |
+| **Still-open (parked) forks** | The repo's open-questions home | Each with a *resolution-lands-in* pointer |
+| **Backlog items** | The repo backlog | See the scope-guard trio below |
+| **Fragments** | Their destinations — they were drafted in destination format precisely so this is a move, not a translation | Merge per the destination's existing structure |
+
+**The scope-guard trio** disambiguates everything that isn't a commitment:
+
+- *Will build later* → **backlog**.
+- *Deliberately not building* → **non-goals**.
+- *Weighed and chose another option* → a **Declined:** line inside the deciding ledger entry,
+  with its evidence and re-evaluate condition — carried into the harvested decision record.
+
+**Directional steering is not feature truth.** A harvested principle informs many decisions and
+changes slowly; a feature fact belongs to its feature doc and changes at code speed. The harvest
+**links** between the steering layer and feature docs — it never duplicates prose across them,
+and it never invents a new top-level home for principles (they land in the *existing* living
+docs).
+
+Rejection rationale and reasoning chains must have explicit destinations — options-considered
+sections, decision changelogs — or the uselessness test fails: the folder may never be deleted
+into a knowledge loss.
+
+## The uselessness test
+
+The deletion-safety gate: after the apply, the post-harvest living docs alone must be enough.
+
+- **The reader is always a freshly spawned, context-free agent** — a full-context reader cannot
+  cold-read; it already knows every undefined term.
+- **Isolation is enforced, not instructed:** the cold reader's prompt contains an explicit
+  allowed-path list (the manifest's destinations — never the session folder), and the detector
+  independently verifies no harvested doc links back into the session folder (BS-HARVEST-01) — a
+  link into scaffolding is itself a harvest defect.
+- **The task:** reconstruct the design — thesis, commitments, reasoning, declined branches — from
+  the allowed paths only.
+- **Grading:** the twin diffs the reconstruction against the ledger and thesis and names every
+  gap; the session-replay evals audit the grading itself. Anything unrecoverable is a named
+  harvest gap → recorded in the manifest (`Result: fail`), fixes enter a new manifest `Round`,
+  approved like the first. Iterate until the folder is redundant.
+
+## The move, and the offer
+
+When the detector's move gate is clean: delete `ops/` entirely (transcript-grade residue never
+enters git), `git mv` the folder to `docs/history/brainstorms/{topic}/`, set
+`Status: harvested`, and update both indexes (row out of `docs/research/Readme.md`, row into
+`docs/history/brainstorms/Readme.md`). The move is the completion marker — a folder still under
+`docs/research/` is by definition unfinished, which is exactly what the maintenance census reads.
+
+Then the offer, relayed by the facilitator: **delete the moved folder, or commit it.** The user
+decides; the design assumes deletion — nothing anywhere may depend on the folder surviving.
+Committing is the explicit way to keep git-history forensics; an uncommitted folder deleted here
+is gone, and that residual is accepted by design.