@nurix/etna 0.19.32 → 0.19.34

package/data/harnesses/delivery/rules/evals.md

@@ -0,0 +1,23 @@
+# Evals
+
+Golden-set conventions, rubric design, and pass thresholds — the measurement half of eval-first. The loop that applies them is the `prompt-eval` skill; the certification they produce is recorded per the `prompt-library` skill.
+
+## Golden sets
+
+- One set per prompt family at `evals/{family}/` — items in `cases.md` (or `cases/*.md` when large), the rubric in `rubric.md`, the threshold declared at the top of the rubric.
+- **An item is input + expected properties**, not input + one blessed output — score what must be true of the answer (fields present, grounded in the supplied context, refusal when the input demands one), never string equality on prose.
+- **Edge cases are the set's value**: adversarial inputs, missing-information inputs, inputs that *should* trigger the fallback. `data-generator` drafts them; a human reviews before they join the set — a wrong expected property poisons every future run.
+- Sets are append-mostly: production failures become new items the same week they're found. Removing an item is a design change to the family and is recorded like one.
+
+## Rubrics
+
+- Every dimension gets **anchors** — a written example of a 1, a 3, and a 5 — or graders drift; a bare "score helpfulness 1–5" is not a rubric.
+- **Mechanical before judgment**: anything checkable in code (format validity, required fields, length bounds, banned content) is checked in code and gates before any graded dimension spends a model call.
+- Judgment dimensions are graded at the economy tier against the anchors; grader-vs-human disagreement above ~1 anchor step, recurring, is a rubric defect — fix the anchors, then re-run.
+- **Rubric changes re-certify the family.** A rubric edit invalidates every score produced under the old rubric; never tune a rubric and a prompt in the same change.
+
+## Thresholds & determinism
+
+- Each family declares one pass threshold (house default: **0.90** weighted across dimensions; safety-critical dimensions are pass/fail gates, not weighted terms).
+- Runs are reproducible: fixed item order, temperature 0 where the task allows, the full set every time — a sampled run is a smoke check, never a certification.
+- A certified score always names its context: prompt version, tier, rubric version, date. Scores without all four are not comparable and never quoted.

package/data/harnesses/delivery/rules/model-tiers.md

@@ -0,0 +1,18 @@
+# Model Tiers
+
+The tier → model mapping — **the only file in this harness that names a model.** Policy, skills, and agent bodies speak in tier labels; when a model generation changes, this file and the owned agents' frontmatter `model:` pins are the two surfaces to edit, and nothing else moves.
+
+## The mapping
+
+| Tier | Model | Frontmatter pin | Character |
+| --- | --- | --- | --- |
+| **economy** | Claude Haiku 4.5 (`claude-haiku-4-5`) | `model: haiku` | Mechanical throughput: eval execution, data generation, regression sweeps |
+| **standard** | Claude Sonnet 5 (`claude-sonnet-5`) | `model: sonnet` | The iteration workhorse: drafting, revising, comparing |
+| **frontier** | Claude Opus 5 (`claude-opus-5`) | `model: opus` | Judgment: the ship gate, adversarial probing, second opinions |
+
+## Updating the mapping
+
+1. Edit the table above to the new generation.
+2. Update the six owned agents' `model:` pins in `.claude/agents/` to match (`eval-runner`, `data-generator`, `regression-runner` → economy; `prompt-iterator` → standard; `judge`, `red-team` → frontier).
+3. A generation change invalidates prompt certifications — `regression-runner` re-certifies the library and runs fresh demotion experiments (cheaper generations routinely absorb work from the tier above; the experiments are how the routing table finds out).
+4. The `maintenance` audit checks the three-way parity — this table ↔ the pins ↔ the routing table's tiers — and flags any mismatch as drift.

package/data/harnesses/delivery/rules/nomenclature.md

@@ -0,0 +1,34 @@
+# Nomenclature
+
+Naming and casing for code — identifiers, files, folders. The rationale throughout is consistency: one concept, one name, one casing shape, in every repo that loads this rule. Database naming is not here — see § Database.
+
+Names state intent in full words — clarity over brevity; no abbreviations unless universally understood (`id`, `url` ✅ · `cfg`, `btn`, `idx` ❌).
+
+## Casing
+
+| Casing | Used for | Example |
+| --- | --- | --- |
+| `camelCase` | variables, functions, methods, properties; a module file exporting no component | `calculateTotal`, `sessionClient.ts` |
+| `PascalCase` | classes, type definitions, components; the file exporting one | `PaymentProcessor`, `AppsListPage.tsx` |
+| `UPPER_SNAKE_CASE` | constants, environment variables | `MAX_RETRY_COUNT` |
+| `kebab-case` | URLs, CSS class names, HTML IDs, multi-word folders | `user-profile`, `workspace-provisioning/` |
+| `snake_case` | database tables, columns, indexes — § Database | `created_at` |
+
+**A file exporting one component carries that component's name exactly**, so an import names the file it came from; a single-word folder is plain lowercase (`lib`, `surfaces`). ❌ Never `snake_case` a file or folder — that casing belongs to the database.
+
+## Identifier shape
+
+| Identifier | Shape | Example |
+| --- | --- | --- |
+| Variable | noun phrase | `paymentStatus` |
+| Function / method | verb phrase naming the action | `validateInput` |
+| Boolean | `is` / `has` / `can` / `should` prefix — **never** a bare adjective | `hasPermission` |
+| Array / collection | plural noun | `errorMessages` |
+| Class / component | singular noun phrase | `RequestHandler` |
+| Event handler | `handle` or `on` prefix | `handleSubmit`, `onPageLoad` |
+| Interface | `I` prefix acceptable; type aliases stay plain | `IConfigOptions`, `AuthResponse` |
+| Async function | verb phrase; `Async` suffix acceptable | `loadConfigAsync` |
+
+## Database
+
+Table, column, index, and key naming for relational schemas — the `id` / `slug` / `label` vocabulary, junction `_map` tables, and Drizzle mirrors — lives in [`database.md`](database.md), which routes general code naming back here.

package/data/harnesses/delivery/rules/prompting.md

@@ -0,0 +1,23 @@
+# Prompting
+
+House prompt style — how production prompts in this repo are written. The library format is the `prompt-library` skill; quality measurement is the `evals` rule; this file is the craft.
+
+## Structure
+
+- **Be explicit, and say why.** State the task, the audience, the constraints, and the motivation — models generalize better from a stated *why* than from a pile of dos and don'ts.
+- **Structure beats prose.** Separate instructions, context, examples, and output format with clear delimiters (XML-style tags are the house default: `<instructions>`, `<context>`, `<examples>`, `<output_format>`). Never interleave data with instructions.
+- **Examples are load-bearing.** Two or three diverse, realistic examples beat ten repetitive ones; every example must be one the golden set would score as passing.
+- **Permit uncertainty.** Tell the model what to do when it can't comply — a stated fallback ("say 'insufficient information'") beats a hallucinated answer, and rubrics score the fallback as correct.
+- **Untrusted input stays untrusted.** Anything user- or document-supplied renders inside its own delimited block; instructions never come from inside it.
+
+## Economy
+
+- **Don't ask the model for what code can do.** Formatting, counting, filtering, deterministic transforms — do them in code around the prompt, not in the prompt.
+- **Every token in a production prompt is a per-call cost.** Cut preamble, restated context, and defensive repetition; if a clause never changes an output (the evals will tell you), it goes.
+- **One prompt, one job.** A prompt accreting second and third jobs gets split into family siblings — chaining certified prompts beats one uncertifiable mega-prompt.
+
+## Iteration discipline
+
+- The first draft rarely survives; iterate against the golden set (`prompt-eval`), not against one hand-picked example.
+- Read failing outputs closely before editing — the fix for a reasoning failure (add motivation, add an example) differs from the fix for a format failure (tighten the output block).
+- Record rejected variants and their eval deltas in the changelog entry; the next session inherits why the current wording won.

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

@@ -0,0 +1,56 @@
+# Brainstorm — process, not archive
+
+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.
+
+> Spec (single source of truth): `docs/architecture/skills/brainstorm/` 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:
+
+| 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 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.
+
+## The session lifecycle
+
+```
+/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 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
+
+- `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)

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

@@ -0,0 +1,173 @@
+---
+name: brainstorm
+description: "Use when starting or stopping a large-scale design brainstorm via `/brainstorm start | stop` — never on phrases like 'let's plan' or 'let's design'. Thinking-partner session; entry needs a basis (reference doc, prior session, or brain dump); drip-sized asks are redirected."
+---
+
+# Brainstorm
+
+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`
+
+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 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/delivery/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/delivery/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.