@nurix/etna 0.19.33 → 0.19.35

package/data/harnesses/delivery/hooks/generate-ownership-index.mjs

@@ -0,0 +1,148 @@
+// harness/code/hooks/generate-ownership-index.mjs — SessionStart hook: scan docs/features/**/*.md,
+// extract the focal frontmatter (owns / module / keywords / status), and inject a compact
+// code-path → owning-doc index via additionalContext. Fires on startup/resume/clear/compact so the
+// map survives /clear and /compact and is regenerated fresh every time. Writes no file.
+
+import fs from "node:fs";
+import path from "node:path";
+
+// Read all of stdin synchronously; returns "" if nothing is piped.
+function readStdin() {
+  try {
+    return fs.readFileSync(0, "utf8");
+  } catch (e) {
+    return "";
+  }
+}
+
+// Resolve the project root: CLAUDE_PROJECT_DIR env, else payload cwd, else process cwd.
+function resolveProjectDir(payload) {
+  return process.env.CLAUDE_PROJECT_DIR || (payload && payload.cwd) || process.cwd();
+}
+
+// Recursively collect every .md file under dir (returns [] if the dir is absent).
+function listMarkdown(dir) {
+  const out = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (e) {
+    return out;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...listMarkdown(full));
+    else if (entry.isFile() && entry.name.endsWith(".md")) out.push(full);
+  }
+  return out;
+}
+
+// Pull the leading `--- … ---` frontmatter block; "" if the file has none.
+function frontmatter(text) {
+  const m = /^?---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  return m ? m[1] : "";
+}
+
+// Trim surrounding whitespace, then strip one layer of matching quotes.
+function unquote(s) {
+  return String(s).trim().replace(/^["']|["']$/g, "").trim();
+}
+
+// Read one frontmatter key: scalar (`k: v`), inline array (`k: [a, b]`), or a following `- item` block.
+// Returns a string for scalars, an array for lists, or undefined when the key is absent.
+function field(block, key) {
+  const lines = block.split(/\r?\n/);
+  const head = new RegExp(`^${key}\\s*:\\s*(.*)$`);
+  for (let i = 0; i < lines.length; i++) {
+    const m = head.exec(lines[i]);
+    if (!m) continue;
+    const raw = m[1].trim();
+    if (raw === "") {
+      const items = [];
+      for (let j = i + 1; j < lines.length; j++) {
+        const li = /^\s*-\s+(.*)$/.exec(lines[j]);
+        if (!li) break;
+        items.push(unquote(li[1]));
+      }
+      return items;
+    }
+    if (raw.startsWith("[")) {
+      return raw.replace(/^\[|\]$/g, "").split(",").map((s) => unquote(s)).filter(Boolean);
+    }
+    return unquote(raw);
+  }
+  return undefined;
+}
+
+// Coerce a field that may be scalar/array/undefined into a clean string array.
+function asList(v) {
+  if (v == null) return [];
+  return (Array.isArray(v) ? v : [v]).map((s) => String(s).trim()).filter(Boolean);
+}
+
+// Build the ownership index text from every feature doc's frontmatter.
+function buildIndex(projectDir) {
+  const featuresDir = path.join(projectDir, "docs", "features");
+  const files = listMarkdown(featuresDir);
+  const lines = [];
+  let deprecated = 0;
+  for (const file of files) {
+    let text;
+    try {
+      text = fs.readFileSync(file, "utf8");
+    } catch (e) {
+      continue;
+    }
+    const block = frontmatter(text);
+    if (!block) continue;
+    const owns = asList(field(block, "owns"));
+    if (owns.length === 0) continue;
+    const status = (field(block, "status") || "active").toString().toLowerCase();
+    if (status === "deprecated") {
+      deprecated += 1;
+      continue; // keep deprecated docs out of the routing lines
+    }
+    const moduleLabel = (field(block, "module") || "—").toString();
+    const keywords = asList(field(block, "keywords"));
+    const doc = path.relative(projectDir, file).split(path.sep).join("/");
+    const kw = keywords.length ? `[${keywords.join(", ")}]` : "[]";
+    for (const glob of owns) {
+      lines.push(`${glob} → ${doc} · ${moduleLabel} · ${kw} · ${status}`);
+    }
+  }
+  if (lines.length === 0) return "";
+  lines.sort();
+  const header =
+    "# Ownership index (generated) — code-path glob → owning feature doc · module · keywords · status\n" +
+    "# Match the file or topic you're about to touch, then read the owning doc before changing it.\n";
+  const footer = deprecated > 0 ? `\n# (${deprecated} deprecated feature doc(s) omitted)` : "";
+  return header + lines.join("\n") + footer;
+}
+
+function main() {
+  const raw = readStdin();
+  let payload = {};
+  try {
+    payload = raw ? JSON.parse(raw) : {};
+  } catch (e) {
+    payload = {};
+  }
+  const index = buildIndex(resolveProjectDir(payload));
+  if (!index) return; // no feature docs yet → inject nothing
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: index,
+      },
+    })
+  );
+}
+
+try {
+  main();
+} catch (e) {
+  // Best-effort: a routing index is a convenience, never a gate. Inject nothing on failure.
+} finally {
+  process.exit(0);
+}

package/data/harnesses/delivery/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/generate-ownership-index.mjs\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,19 @@
+# Changelog
+
+Every unit of work leaves one record — `docs/history/changelog/YYYY-MM-DD-{three-words}.md` (the three words name the work, not the commit) — plus its row in `docs/history/CHANGELOG.md`, appended in the same pass so the index never trails the folder. Entry format, field rules, and the closed exemption list are the `documentation` skill's `templates/changelog-entry.md`; this rule owns when an entry is owed and how it lives. An entry is never a commit summary — it carries the refinement context only the working session holds, which no diff reconstructs.
+
+## When an entry is owed
+
+| Trigger | What to write |
+| --- | --- |
+| A plan reaches `Status: Complete` | A draft entry for that plan, linked to it — written now, while the session still holds the context |
+| The user asks for a changelog | The entry for the work in hand. No commit required |
+| A commit is made | Every non-exempt commit is covered by an entry — the `commit` skill writes or completes it |
+
+## Lifecycle
+
+Draft (created before its commit exists) → complete (missing fields filled from the diff and the session) → frozen the moment it rides in a commit. **Immutability begins at commit, not at creation** — a draft is meant to be edited, which is what lets a completed plan record its context before anything is committed; a committed entry is history, and a correction is a new entry linking back, **never** an edit.
+
+## Granularity
+
+A commit is the smallest unit an entry may describe; above that the mapping is judgment — four commits may be four entries or one, whichever reads better as history. An entry spanning several commits rides in the **last** of them, naming the predecessors in `Commits:`. When work exceeds what a draft describes, write a second entry rather than stretching the draft — the first stays an honest account of the plan.

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.