@nurix/etna 0.18.14 → 0.18.15

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

@@ -2,7 +2,9 @@
 
 A Claude Code skill that is a **thinking partner for designing software** — not a form to fill in. It runs one constant loop (distill → abstract → sync → record) over a conversation, files the thinking into a small set of substance-first pillars, and treats _coherence_ as a measurable target rather than a vibe.
 
-The single principle: **the conversation is the work; the artifacts serve it.**
+Two principles: **the conversation is the work; the artifacts serve it.** And — because conversations are mortal (context compacts, sessions end) — **the session folder is the only memory**: everything the session produces is captured there, distilled, or it doesn't survive.
+
+> Spec (single source of truth): `docs/features/brainstorm-skill.md` 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.
 
 ---
 
@@ -13,12 +15,26 @@ Every turn, in every mode:
 1. **Distill** — fold what the user said into the pillars, in their framing, this turn.
 2. **Abstract** — name the latent structure they implied but didn't state (an entity relationship, an invariant, a principle). One offer per exchange.
 3. **Sync** — keep the pillars consistent with each other and with the basis (the sync agent, below).
-4. **Record** — writes happen in the turn that produced the information; nothing is hoarded for a session-end dump.
+4. **Record** — the user's words land the turn they arrive; the facilitator's substance (analyses, diagnoses, reasoning, definitions, rejections) is on disk by the next sync dispatch at the latest. Nothing is hoarded for a session-end dump.
 
 Everything else — pillar count, ceremony, harvest — scales with the idea. The loop does not.
 
 ---
 
+## The memory contract
+
+v1's leak, measured in a full-session audit (2026-07-03): conclusions survived in the folder, but the facilitator's reasoning — causal diagnoses, informed rejections, definitions of cited terms — lived only in the transcript, and transcripts die at compaction. v2 plugs it with five rules and a recovery rule:
+
+1. **Both-sides capture** — facilitator substance is on disk by the next sync dispatch at the latest (that is the batch point; there is no other). Every dispatch begins with a filing checklist: list substantive contributions since the last sync, file anything unfiled. Knowledge still living only in chat when a sync dispatches is a violation.
+2. **Distilled, never verbatim** — capture is interpretation: the claim, the reasoning, the implication. General point recorded; examples cited as examples. (Integrity copies — printed enumerations, cited excerpts — are fine; the ban is transcript-pasting.)
+3. **Evidence notes** — session-produced research lands as dated files in `<session>/evidence/`, each stating what it examined, what it found, and which question or decision it feeds. `basis/` holds frozen inputs only.
+4. **No naked pointers** — enumerations printed once, terms glossed, external citations excerpted. A reader never needs the transcript or an external file to parse a pillar.
+5. **Eager rejections** — a knowingly-declined option materializes `rejected.md` immediately, with the evidence it was declined against.
+
+**Recovery:** after any compaction, re-enter from the folder alone; anything still "remembered" but not on disk is a leak — file it immediately.
+
+---
+
 ## Lifecycle
 
 Two subcommands, nothing else. The skill never auto-invokes on natural language.
@@ -61,26 +77,27 @@ Mode switches on an explicit user word. On a strong signal the skill _offers_ a
 coherent ⇔ open_questions == 0 ∧ last sync ran after the last pillar write
 ```
 
-`questions.md` is the **single convergence currency**: flaws, gaps, contradictions, and uncovered aspects all funnel into it, whoever raised them. Convergence is one number going to zero. Zero means _"audited against the four sources and clean,"_ never _"nothing came to mind"_ — which is why the sync agent's audit contract is mandatory.
+`questions.md` is the **single convergence currency**: flaws, gaps, contradictions, and uncovered aspects all funnel into it, whoever raised them. Convergence is one number going to zero. Zero means _"audited against the five sources and clean,"_ never _"nothing came to mind"_ — which is why the sync agent's audit contract is mandatory.
 
 ---
 
 ## The sync agent
 
-The background reconciler. One sync in flight at a time; at most one queued behind it. It runs after substantive writes, mandatorily on entering converge and at `stop`, and on demand. It audits exactly four sources:
+The background reconciler. One sync in flight at a time; at most one queued behind it. It runs after substantive writes, mandatorily on entering converge and at `stop`, and on demand. Every dispatch begins transcript-side: the orchestrator lists its substantive contributions since the last sync and files anything unfiled — the sync agent can't see the conversation, so this checklist is the only bridge. Then it audits exactly five sources:
 
 1. **Cross-pillar contradiction** — thesis vs domain model vs decisions vs doctrine vs build.
 2. **Aspect coverage** — any mapped aspect with no content → a question.
 3. **Basis drift** — does the thesis still agree with the basis? Accidental divergence → a question.
 4. **Tech conflicts** — anything violating `tech.md` without a recorded deviation.
+5. **Self-containment** — the cold-reader pass: undefined terms, pointer-only references, unprinted enumerations, decided-vs-open ambiguity, stale citations. The sync agent runs context-free, so it *is* the zero-context reader the memory contract writes for.
 
-It applies **scribe-calls** (edits that don't change the design) directly and notes them; it files **design-calls** (edits that change the idea) as questions and moves on — never interrupting to ask "apply now or defer?" Its one-line report ("4 edits · 2 new questions · 6 open · untouched: risks") is the only ambient convergence pressure the skill applies.
+It applies **scribe-calls** (edits that don't change the design — including printing a missing enumeration or glossing a term) directly and notes them; it files **design-calls** (edits that change the idea) as questions and moves on — never interrupting to ask "apply now or defer?" Its one-line report ("4 edits · 2 new questions · 6 open · untouched: risks") is the only ambient convergence pressure the skill applies.
 
 ---
 
 ## Pillars (substance first, lazy by default)
 
-Always present: `thesis.md`, `questions.md`, `decisions.md`, `build.md`. Materialized at medium+ complexity: `domain-model.md`, `tech.md`. Lazy (materialize on first real content at any complexity): `doctrine`, `glossary`, `non-goals`, `backlog`, `rejected`, `references`, `milestones`.
+Always present: `thesis.md`, `questions.md`, `decisions.md`, `build.md`. Materialized at medium+ complexity: `domain-model.md`, `tech.md`. Lazy (materialize on first real content at any complexity): `doctrine`, `glossary`, `non-goals`, `backlog`, `references`, `milestones` — and `rejected`, which is **eager**: it materializes the moment an option is knowingly declined.
 
 | File | Role |
 | --- | --- |
@@ -90,6 +107,7 @@ Always present: `thesis.md`, `questions.md`, `decisions.md`, `build.md`. Materia
 | `build.md` | How the work executes: build mode, migration strategy, gotchas, rollout. |
 | `domain-model.md` | Information architecture — entities, relationships, cardinalities, state ownership. |
 | `tech.md` | Stack choices, seeded from harness rules; deviations recorded with whys. |
+| `evidence/` | Session-produced analyses as dated notes (`templates/evidence.md`) — each states what it examined and which question/decision it feeds. |
 | `doctrine` / `glossary` / `non-goals` / `backlog` / `rejected` / `references` / `milestones` | As their templates describe. |
 
 The complexity dial sets _defaults_, not a cage — any lazy pillar materializes the moment the conversation produces content for it.
@@ -110,7 +128,7 @@ The writing posture is a **mode** chosen at intake, folded into `build.md`:
 
 ## Exit artifacts
 
-The session writes a **kept** design record at `docs/brainstorm/{topic}/` (one subfolder per topic). At `stop`, after the final sync, the skill _offers_ what to **publish** from it (`AskUserQuestion`, multi-select — a session can emit more than one):
+The session writes a **kept** design record at `docs/brainstorm/{topic}/` (one subfolder per topic). At `stop`, after the final five-source sync (self-containment included — the record is verified standalone-readable exactly when it's about to become the only survivor of the session), the skill _offers_ what to **publish** from it (`AskUserQuestion`, multi-select — a session can emit more than one):
 
 - **Source of truth** — one consolidated, README-style canonical doc for the thing designed (`templates/source-of-truth.md`); lands in the repo's feature/architecture doc home, else a topic `Readme.md`.
 - **Plans** — one or more executable plan docs → `docs/history/plans/` (Status: Draft).
@@ -126,7 +144,7 @@ The `docs/brainstorm/{topic}/` record is **kept** whichever you pick — never d
 2. **Speak English to the user; codes (`Q3`, `D7`) live in the files.**
 3. **`AskUserQuestion` appears in exactly four places:** the intake frame, interview mode, converge picks, the `stop` exit-artifact pick.
 4. **Suggested, never seized** — mode shifts, abstractions, probes are offered once.
-5. **Questions are the only convergence currency** — nothing pending may live only in the transcript.
+5. **Nothing lives only in the transcript** — questions carry everything pending; the memory contract carries everything known.
 6. **No auto-invocation** — only `/brainstorm start` and `/brainstorm stop`.
 
 ---
@@ -135,10 +153,10 @@ The `docs/brainstorm/{topic}/` record is **kept** whichever you pick — never d
 
 ```
 brainstorm/                  # the skill (in .claude/skills/)
-├── SKILL.md          # the skill definition Claude Code loads (~1.8k words)
+├── SKILL.md          # the skill definition Claude Code loads (~2.2k words)
 ├── README.md         # this file
 ├── exit-artifacts.md # what /brainstorm stop publishes: source-of-truth / plans / harvest
-└── templates/        # pillar templates + source-of-truth.md, used in the record and at stop
+└── templates/        # pillar templates + evidence.md + source-of-truth.md, used in the record and at stop
 ```
 
 The session itself is written to `docs/brainstorm/{topic}/` (kept, committed) — not here.

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

@@ -1,22 +1,34 @@
 ---
 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). 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 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.
 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. The constant across every scale of idea is **the loop**; everything else — pillar count, ceremony, exit artifacts — scales with complexity.
+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.** Writes happen in the turn that produced the information — never accumulated for a session-end dump.
+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 |
@@ -50,7 +62,7 @@ Then propose the **aspect map**: the thinking dimensions for _this specific idea
 
 ### 3. Bootstrap
 
-Session folder: `docs/brainstorm/{topic}/` — a **committed, kept** design record, one subfolder per design topic (slug the topic; confirm it in one line). Resume an existing topic by reusing its folder if it already holds a `state.md`. The record stays in the repo after the exit artifacts publish (it is the provenance they distil from — see `exit-artifacts.md`), so it lives under `docs/` like any other durable project knowledge, not at the repo root. 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**). Write top-level `state.md`:
+Session folder: `docs/brainstorm/{topic}/` — a **committed, kept** design record, one subfolder per design topic (slug the topic; confirm it in one line). Resume an existing topic by reusing its folder if it already holds a `state.md`. The record stays in the repo after the exit artifacts publish (it is the provenance they distil from — see `exit-artifacts.md`), so it lives under `docs/` like any other durable project knowledge, not at the repo root. 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
@@ -74,7 +86,7 @@ Initial questions come from the basis distillation **only** — contradictions i
 | `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 |
+| `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.
 
@@ -90,18 +102,21 @@ The complexity dial sets _defaults_, not a cage: any lazy pillar materializes mi
 
 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 (read/write access to the session folder only).
+**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 (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 four sources:**
+**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. 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 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:
 
@@ -115,12 +130,12 @@ There is no separate dashboard, no scheduled checkpoint. This line is the only a
 coherent ⇔ open_questions == 0 ∧ last sync ran after the last pillar write
 ```
 
-Zero means _"audited against the four 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."
+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).
-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.
+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 ADRs, the domain model, the backlog). The `docs/brainstorm/{topic}/` 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. Print: _"Run `/brainstorm start` to resume."_
 
@@ -131,5 +146,5 @@ Zero means _"audited against the four sources and clean"_ — never _"nothing ca
 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. **Questions are the only convergence currency.** Flaws, gaps, contradictions, uncovered aspects — everything unresolved funnels into `questions.md` or it doesn't exist. Nothing pending may live only in the conversation transcript.
+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.

package/data/harnesses/code/skills/brainstorm/templates/evidence.md

@@ -0,0 +1,24 @@
+# Evidence — [what was examined]
+
+This file is a **session-produced analysis** — research, an audit, a study, a comparison — captured under the memory contract: distilled findings, not a log. One file per analysis, dated, in `<session>/evidence/`. (`basis/` is for frozen *inputs* the session started from; evidence is what the session itself produced.)
+
+Every evidence note should **feed** something — a question it informs, a decision it grounds, or, for free-floating insight, the thesis aspect it belongs to. The sync agent notes unconsumed evidence in its report as a scribe-note, never a question — filing an insight must never push the session away from coherent.
+
+Write for a reader with zero context: define terms, print the numbers, excerpt sources. Distill — name the claim, the reasoning, the implication; never paste transcripts or raw tool output.
+
+---
+
+**Date.** YYYY-MM-DD
+
+**Examined.** [What was analyzed and how — the sources, the method, one or two lines.]
+
+**Feeds.** [Q-N / D-N — or `aspect: <name>` from the thesis map when no specific question or decision consumes it yet.]
+
+## Findings
+
+- [Distilled finding 1 — the claim, with the number/citation that carries it.]
+- [Distilled finding 2.]
+
+## Implication
+
+[What this means for the design — one short paragraph. If it changes a lean or closes an option, say so and point at the question/decision entry that records it.]

package/data/harnesses/code/skills/brainstorm/templates/rejected.md

@@ -2,7 +2,9 @@
 
 This file captures **paths that were considered and rejected**, with the reason for rejection. Its purpose is to prevent re-litigation: when someone proposes the same alternative six weeks later, this file answers "we already looked at that; here's why we didn't go that way."
 
-Each entry needs three load-bearing parts: **Considered** (what was proposed, in concrete terms), **Rejected because** (the specific reason — "didn't fit" is useless to future-you; name the constraint, the cost, the risk), and **Re-evaluate if** (what would need to change for the rejected path to become viable again). The re-evaluate field stops the rejection from looking permanent when it isn't — most rejections are scope-conditional, not absolute.
+Each entry needs four load-bearing parts: **Considered** (what was proposed, in concrete terms), **Evidence on the table** (what prior art, findings, or arguments were in front of the decider when they declined — this is what separates an informed rejection from an unexamined one), **Rejected because** (the specific reason — "didn't fit" is useless to future-you; name the constraint, the cost, the risk), and **Re-evaluate if** (what would need to change for the rejected path to become viable again). The re-evaluate field stops the rejection from looking permanent when it isn't — most rejections are scope-conditional, not absolute.
+
+This file is **eager**, not lazy (the memory contract): it materializes the moment the user knowingly declines a presented option, in the same turn — an informed rejection that lives only in the transcript is a leak.
 
 This is one of the four places inside the brainstorm folder where past tense and "we considered X" framing is permitted (the others: `decisions.md`, `references.md`, git history). The whole point of this file is to capture the path-not-taken so future architects don't have to re-discover it.
 
@@ -14,6 +16,8 @@ If circumstances change and a rejected path becomes attractive again, **do not s
 
 **Considered.** [What was proposed.]
 
+**Evidence on the table.** [The prior art, findings, or arguments in front of the decider at the moment of declining — cite the evidence note or basis file if one carries it.]
+
 **Rejected because.** [The reason. Be specific.]
 
 **Re-evaluate if.** [What would change to make this viable.]

package/data/harnesses/etna/harness.json

@@ -1,11 +1,11 @@
 {
   "harness": "etna",
   "name": "etna",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "files": [
     ".prettierrc.json",
     ".prettierignore",
     ".vscode/settings.json"
   ],
-  "digest": "9447b8703853"
+  "digest": "8adc30cd7fa2"
 }

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

@@ -1,49 +1,69 @@
 ---
 name: boundary
-description: Boundary diagnostic for implementation plans. Given a plan file, reads the source files the plan touches, identifies the application boundaries they participate in — the cross-cutting contracts (db schema, wire envelope, auth, events, env/config, …) where editing one side silently breaks the other — and reports whether the planned changes would violate any of them, severity-ranked, with suggested plan amendments. Read-only; the report lands in chat. Can also run against a diff or named code area instead of a plan. Triggers on "boundary check", "check this plan", "what could break", "impact analysis", "/boundary".
+description: Boundary diagnostic for implementation plans. Given a plan file, reads the source the plan touches, identifies the cross-cutting contracts it participates in — db schema, wire envelope, auth, events, env/config, … — where editing one side silently breaks the other, and reports whether the planned changes would violate any of them, severity-ranked, with suggested amendments and a pass/block verdict. Read-only; the report lands in chat. Also runs against a diff or named code area. Triggers on "boundary check", "check this plan", "what could break", "will this break anything", "is it safe to rename this column/endpoint/event", "who uses this", "impact analysis", "/boundary".
 ---
 
 # Boundary Diagnostic
 
 You diagnose whether a plan's changes would break an application boundary.
 
-A boundary is a contract between two pieces of code (or code and infra) that share an assumption with **no compile-time link** between them: the column a raw SQL string names, the JSON envelope a client unwraps, the event string a dispatcher parses, the env var a deploy script writes. Changing one side ships green and breaks the other silently. Your job is to find those edges in the plan's path _before_ execution.
+A boundary is a contract between two pieces of code (or code and infra) that share an assumption with **no static link** between them: the column a raw SQL string names, the JSON envelope a client unwraps, the event string a dispatcher parses, the env var a deploy script writes. Changing one side ships green — compiles, lints, tests pass — and breaks the other at runtime. Your job is to find those edges in the plan's path _before_ execution.
 
-[`references/boundary-taxonomy.md`](references/boundary-taxonomy.md) is the catalog of boundary types (~170 across persistence, wire/API, frontend, auth/tenancy, async/messaging, config/build, runtime/infra), with per-type severities and safe-change checklists. Read it first — it tells you what to look for; the code tells you what exists.
+**The litmus is "would it ship green?"** An edge the compiler or an existing test already guards is not a boundary — a change that fails the build loudly needs no diagnostic. Spend your reading on the edges with no static link.
+
+## Contract sources
+
+Three layers tell you what to look for; the code tells you what exists.
+
+- **The mechanisms** — [`references/mechanisms.md`](references/mechanisms.md) defines the seven failure mechanisms every boundary instantiates (rendezvous-string, serialized-shape, generated-artifact, dual-authority, config-elsewhere, trust-invariant, lifecycle-protocol), each with its trace strategy, universal safe-change pattern, and severity heuristic, plus the two stack-independent domain contracts (entity-model, tenancy). Load it on every check.
+- **The technology packs** — [`references/index.md`](references/index.md) routes to the packs under `references/packs/` by the signals in the touched code. Each pack carries the non-derivable payload for one technology area: exact detect patterns, expensive-to-learn gotchas, and safe-change sequences. Load **only the packs the touch list exhibits**; a technology no pack covers is still in scope — diagnose it from its mechanism.
+- **Repo doctrine** — `.claude/rules/`, `docs/architecture/` (including `adr/`), and any contracts package name the repo's bespoke contracts (a documented response envelope, a schema-parity rule, an entity model). A documented contract is a real side of a boundary: a plan that contradicts one is a finding **even when no code consumer exists yet** — this is how greenfield plans, whose modules have no code to trace, still get checked.
+
+The packs are a floor, not a fence: report any contract that passes the ships-green litmus, pack entry or not.
 
 ## Run
 
 **Input:** a plan path (given, or the newest in `docs/history/plans/`) — or a diff / named code area for non-plan work. Everything below is identical either way; a diff's hunks stand in for the plan's steps.
 
-1. **Build the touch list.** Parse the plan's Proposed Changes: files to be created or modified, entities/state added or changed, API changes, anything the author flags as a cross-module contract. Note missing subsections.
+1. **Build the touch list.** Parse the plan's Proposed Changes: files created or modified, entities/state added or changed, API changes, anything the author flags as a cross-module contract. Note missing subsections.
 
-2. **Identify the boundaries in the touched code.** Read each touched file (and its immediate imports). Against the taxonomy, list the contracts this code participates in — the schema it queries, the envelope it emits, the events it publishes or parses, the auth checks it sits behind, the env it reads.
+2. **Identify the contracts.** Read each touched file (and its immediate imports). Against the mechanisms, the routed packs, and the repo doctrine, list the contracts this code participates in — the schema it queries, the envelope it emits, the events it publishes or parses, the auth checks it sits behind, the env it reads.
 
-3. **Trace the other side.** A boundary has two sides; the danger lives on the one the plan _doesn't_ mention. For each contract, grep the shared name or shape across the repo — the column name in other SQL strings, the response field in client unwrappers, the event kind in subscribers, the route in fetch calls and scripts, the env key in deploy tooling. Record consumers as `file:line`.
+3. **Trace the other side.** A boundary has two sides; the danger lives on the one the plan _doesn't_ mention. For each contract, grep the shared name or shape across the repo — the column name in other SQL strings, the response field in client unwrappers, the event kind in subscribers, the route in fetch calls and scripts, the env key in deploy tooling. Record consumers as `file:line`; record doctrine as the doc path. When the touch list is large (≳10 contracts), fan the tracing out to parallel sub-agents — one per pack area, each with a self-contained prompt naming its contracts and grep targets — and judge the returned evidence yourself; a small diff traces inline.
 
-4. **Judge each intersection.** Does the planned change alter a shape a traced consumer depends on, break an invariant the code establishes (append-only vocabularies, idempotency keys, fail-closed checks, ordering guarantees), or add a new cross-module edge? Severity:
+4. **Judge each intersection.** Does the planned change alter a shape a traced consumer depends on, break an invariant the code or doctrine establishes (append-only vocabularies, idempotency keys, fail-closed checks, ordering guarantees), or introduce a new cross-module edge? Severity:
    - **CRITICAL** — can corrupt persisted data, or open an auth/money path.
    - **HIGH** — silent cross-module breakage that would ship green.
    - **MEDIUM** — drift-prone coupling (string-matched, duplicated constants).
-   - **LOW** — smell. Loud, immediately-visible breakage caps at HIGH.
+   - **LOW** — smell. Loud, immediately-visible runtime breakage caps at HIGH.
 
 5. **Report in chat:**
 
    ```
    # Boundary check — {plan}
 
-   Touched files read: {N} · Boundaries identified: {N}
-   Violations: {N} ({critical}/{high}/{medium}/{low})
+   **Verdict: PASS | PASS WITH AMENDMENTS | BLOCK**
 
-   | # | Boundary | Planned change | Other side (file:line) | Severity |
+   Touched files read: {N} · Contracts identified: {N} · Consumers traced: {N}
+
+   ## Violations
+   | # | Boundary | Mechanism | Planned change | Other side (file:line or doc) | Severity |
+
+   ## New edges the plan introduces
+   | # | Contract | Sides | Hardening to fold into the plan |
+
+   ## Coverage
+   | Area touched | Contracts checked | Result |
 
    ## Suggested plan amendments
    ## Missing plan subsections
    ```
 
+   **BLOCK** = any CRITICAL. HIGH findings yield **PASS WITH AMENDMENTS** — fold the amendments into the plan before coding. Order amendments sequencing-first: many violations dissolve by reordering steps (expand-then-contract, migrate-before-code) rather than changing what ships — prefer that fix, drawn from the entry's safe-change sequence.
+
 ## Rules
 
 - **Read-only.** You never edit the plan, the code, or any doc. The user folds your amendments into the plan.
-- **Verify in source.** Never flag from plan text alone — read both sides of every boundary you report, and cite both as `file:line`.
-- **No consumer, no finding.** An intersection with no traced other side isn't a violation; at most note it as a new edge the plan introduces.
-- **A clean report is valid.** Zero violations means say so — don't pad.
+- **Verify in source.** Never flag from plan text alone — read both sides of every finding and cite them: code as `file:line`, doctrine as the doc path.
+- **No other side, no violation.** An intersection with no traced consumer and no doctrine behind it isn't a violation — it's a **new edge**: report it in its own section with the hardening its mechanism prescribes (version the cache key now, make the enum append-only now), so the fragile edge is born safe.
+- **A clean report is valid.** Zero violations means say so — the coverage table is the evidence it was checked, not skipped. Don't pad findings.

package/data/harnesses/etna/skills/boundary/references/index.md

@@ -0,0 +1,16 @@
+# Pack routing index
+
+Load when: every boundary check, right after `mechanisms.md`. Match the touch list against the signals below and load **only** the packs whose signals appear in the touched files or the plan's Proposed Changes. Several packs matching is normal (a full-stack feature typically routes 2–4). A technology matching nothing here is still in scope — diagnose it from its mechanism, and check `packs/generic-tail.md` for a thin entry.
+
+| Pack | Load when the touch list shows |
+| --- | --- |
+| `packs/persistence.md` | `schema.ts`, `init.sql`, `sqliteTable(`, `drizzle-kit`, `pgTable`, migrations, `*.seed.sql`, seed generators, JSON columns, `pgEnum`, pgvector, Redis `get`/`set` caching |
+| `packs/wire-api.md` | Express routes/middleware (`app.use(`, `router.`), `res.json({ status`, zod schemas on requests, axios clients/interceptors, `cors(`, inbound webhooks, `rateLimit(` |
+| `packs/frontend.md` | `createSlice`/`configureStore`, RTK Query (`tagTypes`), react-router tables/`useParams`, Tailwind CSS (`@theme`, `personality.css`, `globals.css`), `vite.config.*` (alias, env), `@nurix/components`, localforage/redux-persist, date formatting |
+| `packs/auth.md` | `jwtVerify(`/jose, `betterAuth(`/`auth.api.`, session cookies, CSRF, OAuth callbacks/`redirect_uri`, `tenantId`/`organizationId` scoping, password hashing, auth middleware mounts |
+| `packs/cloudflare.md` | `wrangler.jsonc`/`wrangler.toml`, `env.X` bindings, `extends DurableObject`/`[[migrations]]`, KV/R2/D1/Queues, `scheduled(`/crons, `WorkerEntrypoint`, `compatibility_date`, static assets config |
+| `packs/async-messaging.md` | BullMQ (`new Queue(`/`new Worker(`), Redis pub/sub or Streams, WebSockets/socket.io, SSE (`text/event-stream`), channel-name templates, outbound webhook senders |
+| `packs/build-config-runtime.md` | `package.json` (deps/`exports`/scripts/`packageManager`), lockfiles, `.env*`, tsconfig `paths`, Dockerfiles/compose, `.github/workflows/`, pino config, `trust proxy`, ports/healthchecks |
+| `packs/generic-tail.md` | GraphQL, gRPC/protobuf, tRPC, OpenAPI codegen, Kafka/schema registry/CDC, workflow engines, event sourcing, Postgres RLS/pooling/collation, SSR/hydration, module federation, i18n, analytics plans, hosted feature flags, K8s probes/shutdown/limits, service mesh, IaC outputs, SAML, Lambda, IPC |
+
+Two files never route — they always load: `mechanisms.md` (the seven failure mechanisms + domain contracts) and this index.

package/data/harnesses/etna/skills/boundary/references/mechanisms.md

@@ -0,0 +1,99 @@
+# Boundary Mechanisms
+
+Load when: every boundary check — this is the core reference. The technology packs under `packs/` instantiate these mechanisms with exact detect signals and gotchas; `index.md` routes to the packs the touched code exhibits.
+
+A boundary is a contract between two pieces of code (or code and infra) that share an assumption with **no static link** between them. The litmus is **"would it ship green?"** — change one side, everything compiles, lints, and tests pass, and the other side breaks at runtime. An edge the compiler or an existing test already guards is not a boundary.
+
+Every boundary instantiates one of seven mechanisms. The mechanism tells you what to grep for, what the universal fix is, and how bad a break is — including for technologies no pack covers. When touched code exhibits a contract that matches no pack entry, diagnose it from its mechanism.
+
+---
+
+## 1 · rendezvous-string
+
+Two sides meet on a literal identifier: a column name in raw SQL, an event/job/topic name, a route path, an env key, a cache key, a channel template, a DI token, a flag key, a metric name, a port number, a binding name. The compiler sees two unrelated literals.
+
+- **Ask:** where else does this exact string (or its template) appear — including config, IaC, CI, dashboards, and other repos?
+- **Failure:** the sides silently stop meeting — publishes into the void, reads `undefined`, routes 404, handler never fires, alert goes quiet.
+- **Trace:** grep the literal and its prefix/template variants repo-wide; the other side is often not code (a deploy manifest, a saved dashboard query, a provider allowlist).
+- **Universal fix:** centralize the identifier in one shared constant or module. On rename, serve both old and new until the old side drains — in-flight jobs, cached entries, sent emails, deployed clients.
+- **Severity:** HIGH by default; CRITICAL when the string scopes trust (a tenant segment in a channel name, a redirect-URI allowlist entry).
+
+## 2 · serialized-shape
+
+A payload crosses a gap in space or time — a process boundary, a deploy window, persistence — and the reader is not the writer. Old data and mixed-version peers must still parse. The defining sub-case is the **mixed-version window**: rolling deploys, in-flight queue items, long-lived clients, persisted events, browser storage — the old shape exists somewhere and outlives the change.
+
+- **Ask:** who reads this shape that doesn't build from this commit — old rows, queued messages, deployed clients, replayed histories?
+- **Failure:** the reader crashes or misreads with no error at the writer; persisted old shapes fail **forever**, not just during the deploy.
+- **Trace:** find every deserializer of the shape (parsers, `JSON.parse` + property reads, ORM rehydration, client unwrappers) and every store where old instances persist.
+- **Universal fix:** additive-only changes (add optional fields, never rename/retype/remove); carry an explicit version and read all live versions; readers tolerate unknown fields and ignore unknown discriminators.
+- **Severity:** CRITICAL when the shape is persisted or replayed (the break is historical, not just live); HIGH for live-traffic shapes.
+
+## 3 · generated-artifact
+
+A derived artifact must stay in sync with its source: ORM client from schema, types from codegen, lockfile from package.json, bundler aliases from tsconfig, seed SQL from a CSV. The artifact is trusted as if it were the source — when they drift, the artifact **lies** to everything that consumes it.
+
+- **Ask:** what generates this, what does it generate, and would CI notice if they drifted?
+- **Failure:** code compiles against stale types and mismatches at runtime; installs resolve a tree nobody tested; hand-edits are clobbered on the next generation.
+- **Trace:** find the generator invocation (scripts, `prepack`, CI steps) and every consumer of the output; check whether generation is enforced or manual.
+- **Universal fix:** regenerate in the same commit as the source change; CI-gate drift (`git diff --exit-code` after generate); never hand-edit generated output.
+- **Severity:** HIGH by default; CRITICAL when the artifact governs installs or schema (lockfile, migrations).
+
+## 4 · dual-authority
+
+Two independent writers own the same state: two migration tools targeting one database, a framework that owns its own tables, an app route table and an ingress rule, hand-written DDL and an ORM mirror. Each authority is internally consistent; the state they share is not.
+
+- **Ask:** who else writes this — and does either writer know the other exists?
+- **Failure:** one authority clobbers or drifts from the other; the loser's consumers break with no signal on the winner's side (a schema push drops the auth library's tables; login breaks).
+- **Trace:** list every tool/config with write authority over the state (migration runners, CLIs, IaC, admin dashboards) and what each believes the state is.
+- **Universal fix:** designate one canonical authority and make the others read-only mirrors reconciled from it — or byte-align them and CI-check the parity.
+- **Severity:** CRITICAL when the shared state is persisted data or auth; HIGH otherwise.
+
+## 5 · config-elsewhere
+
+A value is declared in one place and consumed in another — env vars, platform bindings, secret paths, ports, build-time defines. Reader and provider never reference each other statically, and the provider is often per-environment, so the break can exist in exactly one environment.
+
+- **Ask:** for each value this code reads, where is it declared — in **every** environment, not just the one you can see?
+- **Failure:** `undefined` at request time, boot failure in one env only, a stale build-time literal where a runtime value was expected, a secret baked into a public artifact.
+- **Trace:** map each read (`process.env.X`, `env.BINDING`, `import.meta.env.Y`) to its declaration in every env file, deploy manifest, CI secret store, and dashboard.
+- **Universal fix:** validate the full key set at boot and fail fast; keep a tracked example/contract file (`.env.example`); change reader and every provider in one commit.
+- **Severity:** HIGH by default; CRITICAL when the flow direction is wrong (a secret reaching a client bundle) — that is also a trust-invariant break.
+
+## 6 · trust-invariant
+
+An auth or isolation guarantee that **fails open**: tenancy scoping, RLS policies, cookie flags, CSRF defenses, redirect-URI allowlists, JWT audience checks, public-env prefixes. Unlike the other mechanisms, breaking it doesn't stop the system — everything keeps working, plus an attacker path or a cross-tenant leak.
+
+- **Ask:** if this check were deleted, would anything visibly fail — or would the system happily serve data it shouldn't?
+- **Failure:** silent grant or disclosure. There is no error to observe; tests that only exercise the happy path stay green by construction.
+- **Trace:** find every enforcement point of the invariant and every path that bypasses it (new endpoints, new tables, raw queries, `SECURITY DEFINER`-style escape hatches, spoofable inputs like `req.body.tenantId`).
+- **Universal fix:** enforce centrally (middleware, policy, schema default) so a new code path inherits the invariant instead of having to remember it; default-deny on any missing input.
+- **Severity:** CRITICAL, categorically. Loud auth failures (everyone locked out) cap at HIGH; it's the quiet successes that are CRITICAL.
+
+## 7 · lifecycle-protocol
+
+An ordering or sequencing agreement with a platform or across deploys: expand-then-contract migrations, deploy order between producer and consumer, graceful-shutdown draining, replay determinism, retry/idempotency budgets, timezone/DST assumptions, append-only version tags.
+
+- **Ask:** does correctness depend on *when* or *in what order* this runs — and who else assumes that order?
+- **Failure:** correct code applied in the wrong order: a migration that strands a rolling deploy, a retry that double-charges, a rename that orphans live stateful objects, a cron that fires on the wrong day twice a year.
+- **Trace:** reconstruct the sequence the change requires (what must exist before what) and compare against how deploys actually roll out — including crash/retry paths.
+- **Universal fix:** make each step independently safe (idempotent handlers, additive-first migrations, append-only version markers); many boundary violations dissolve by **reordering the plan**, not changing what ships.
+- **Severity:** CRITICAL when a wrong order corrupts persisted state or duplicates money-adjacent side effects; HIGH otherwise.
+
+---
+
+## Domain contracts — stack-independent, always checked
+
+Two contracts come from the product's information architecture, not from any technology, and are checked on every run:
+
+- **entity-model — CRITICAL.** The entity vocabulary and topology (what the entities are, how they relate) that every module, migration, wire type, and doc agrees on. Re-relating or renaming an entity is a change to *every* mechanism at once. Sourced from `docs/architecture/` (domain model, ADRs), a contracts package, and the schema — never from a single module's view of it. Safe change: map every consumer before re-relating; coordinate schema + wire + client in one planned sequence.
+- **tenancy — CRITICAL · trust-invariant.** The invariant that every request carries a non-spoofable tenant identity and all data access is scoped by it, at every layer. Its enforcement points are technology-specific (a JWT claim, a channel-name segment, an RLS policy, a scoped query helper) but the invariant is one contract — a single unscoped path anywhere breaks it.
+
+---
+
+## Severity recap
+
+- **CRITICAL** — can corrupt persisted data, or open an auth/money path. Trust-invariants and persisted/replayed shapes live here.
+- **HIGH** — silent cross-module breakage that ships green.
+- **MEDIUM** — drift-prone coupling (string-matched, duplicated constants) not yet broken.
+- **LOW** — smell. Loud, immediately-visible runtime breakage caps at HIGH; statically-guarded edges are out of scope entirely.
+
+Severity is intrinsic to the finding, not curved: three genuine CRITICALs in a small repo is correct signal, not inflation.