@nurix/etna 0.18.13 → 0.18.15

package/data/harnesses/code/skills/boundary/references/packs/wire-api.md

@@ -0,0 +1,87 @@
+# Pack: HTTP wire / API
+
+Load when: the touch list exhibits Express routes/middleware (`app.use(`, `router.get(`), the response envelope (`res.json({ status`), zod request validation, axios clients/interceptors, CORS config, webhooks received, or rate limiting.
+
+## express5-route-string-syntax — HIGH · rendezvous-string
+**Contract:** Express route strings are compiled by path-to-regexp v8 in Express 5; route authors and every URL caller meet on a path-string dialect that changed from Express 4.
+**Detect:** `app\.(get|post|put|patch|delete|all|use)\(['"]`, `['"]\*['"]`, `:[a-zA-Z]+\?`, `:\w+\(`, `/\*splat`, `\{/:`, `req\.params\[0\]`, `req\.params\.splat`
+**Ships green, breaks:** Old syntax `*`, `:id?`, `:id(\d+)` throws `TypeError: Missing parameter name` at boot — but the silent ones: `/*splat` no longer matches the mount root (`/files/*splat` misses `GET /files/`; only `/{*splat}` matches root); wildcard params are now ARRAYS of segments (`req.params.splat === ['a','b']`, not the string `'a/b'`; `req.params[0]` is gone → undefined); unmatched optional params are OMITTED from `req.params` instead of present-as-undefined; regex sub-patterns are unsupported, so numeric-only constraints once enforced by `(\d+)` silently stop filtering if approximated wrong.
+**Safe change:** Use `/{*splat}` when root must match; treat splat as array (`req.params.splat.join('/')` where a string was expected); `:p?` → `{/:p}`, `:file.:ext?` → `/:file{.:ext}`; move regex constraints into handler/zod validation; run the Express v5 migration codemod and re-test every wildcard/optional route with real URLs.
+
+## express5-query-parser-flip — HIGH · serialized-shape
+**Contract:** Clients serialize query strings (qs brackets, axios `params`) and the server parses them per `app.set('query parser', ...)` — Express 5 flipped the default from `'extended'` to `'simple'`.
+**Detect:** `app.set('query parser'`, `req\.query`, `\[\w+\]=` in client URL builders, `qs.stringify`, `paramsSerializer`, `express.urlencoded()`
+**Ships green, breaks:** `?filter[status]=open` now parses to the flat key `"filter[status]"` instead of `{filter:{status:'open'}}` — loose schemas pass it through and filters silently no-op (endpoint returns unfiltered data); strict schemas start 400ing only for clients that send brackets. `req.query` is now a getter: sanitizer middleware doing `req.query = cleaned` silently no-ops (sloppy mode) or throws TypeError (strict). `express.urlencoded()` `extended` also now defaults to `false`.
+**Safe change:** Pin `app.set('query parser', 'extended')` on migration (or convert clients to flat params); mutate `req.query` properties in place, never reassign; validate `req.query` with a strict zod schema so shape drift fails loudly.
+
+## express5-removed-response-apis — HIGH · rendezvous-string
+**Contract:** Handler code meets the Express request/response API by literal method name at runtime — nothing static links plain-JS call sites to Express 5's removed/changed methods.
+**Detect:** `res.sendfile(`, `app.del(`, `res.redirect('back')`, `res.location('back')`, `req.param(`, `res\.(send|json|jsonp)\([^)]+,\s*\d{3}\)`, `res\.send\(\d{3}\)`, `clearCookie\(.+maxAge|expires`
+**Ships green, breaks:** `res.redirect('back')` no longer resolves the Referrer — it redirects to the literal relative URL `back` (no error; users land on a 404). `res.clearCookie(name, {maxAge, expires})` silently ignores those options. `res.sendfile`, `app.del`, `req.param()`, `res.send(body, status)`, `res.send(404)` are removed → per-request TypeError → 500s only when the route is exercised. `res.status()` now throws for non-integers outside 100–999. `req.body` is `undefined` (not `{}`) when no parser ran, so `req.body.x` throws where v4 returned undefined.
+**Safe change:** Replace `'back'` with `req.get('Referrer') || '/'`; `res.sendStatus(n)` / `res.status(n).json(obj)`; guard trust edges with `req.body ?? {}`; grep the whole detect list before touching any Express-4-era file.
+
+## express-error-handler-arity — HIGH · lifecycle-protocol
+**Contract:** Express identifies an error handler SOLELY by `fn.length === 4`; Express 5 additionally forwards every rejected async handler/middleware promise to that chain as `next(err)`.
+**Detect:** `app.use((err,`, `(err, req, res, next)`, `express-async-errors`, `.catch(next)`, `next(err)`
+**Ships green, breaks:** Deleting the "unused" fourth `next` param (a common lint autofix) silently turns the centralized error handler into ordinary middleware — it now runs on EVERY request and never on errors; errors fall through to Express's default handler, which emits HTML instead of the JSON envelope, and envelope-unwrapping clients break. With Express 5's native rejection forwarding, legacy `catch (e) { next(e) }` plus a rethrow (or a lingering `express-async-errors` shim) double-invokes the error chain → `Cannot set headers after they are sent`. Throws inside `setTimeout`/event callbacks are NOT forwarded and still crash the process.
+**Safe change:** Always declare 4 params on error middleware (void the unused one); one terminal error handler emitting the envelope; in async handlers throw OR `next(e)`, never both; keep non-request-path callbacks in their own try/catch.
+
+## api-response-envelope — HIGH · serialized-shape
+**Contract:** Every response body is `{"status": 1, "message": "...", "data": {...}}` (errors: `{"status": 0, "message": "...", "data": null}`); axios interceptors unwrap `response.data.data` and branch on NUMERIC `status`.
+**Detect:** `status: 1`, `status: 0`, `"status": 1`, `.data.data`, `interceptors.response.use`, `res.json({ status`, `data: null`
+**Ships green, breaks:** Server emitting `status: true` breaks client `=== 1` / `=== 0` strict checks — responses classify as neither success nor error and fall through silently. A new endpoint returning a bare payload makes the unwrapper's `.data.data` yield `undefined` — spreads/destructures render empty state, no error thrown. If error envelopes move to non-2xx HTTP codes, axios's default `validateStatus` routes them into the REJECTED interceptor arm where the success unwrapper never runs — code must read `err.response.data.message`, not `res.data.message`. `data: null` on errors breaks optimistic `data.items.map`.
+**Safe change:** Emit the envelope only via one `sendSuccess`/`sendError` helper (no inline literals); unwrap in one axios interceptor handling BOTH fulfilled and rejected arms; zod-parse the envelope at the client edge (`z.union([z.literal(0), z.literal(1)])` for `status`) so drift throws instead of undefined-ing.
+
+## http-status-code-convention — HIGH · rendezvous-string
+**Contract:** Server code choices and client interceptor branching meet on exact numeric codes: 200, 201 created, 400, 401 not-authenticated, 403 not-authorized, 404, 500 (plus 429/503 for backoff) — literals on both sides, no static link.
+**Detect:** `res.status(4`, `sendStatus(`, `err.response?.status`, `=== 401`, `=== 403`, `Retry-After`, `status === 429`
+**Ships green, breaks:** Returning 403 (or 200 + envelope `status: 0`) for an EXPIRED token means the client's 401→refresh-token interceptor never fires — sessions die silently or error-toast forever. Returning 401 for a pure permissions failure triggers refresh→retry loops that hammer the auth service and can force logouts. Backoff interceptors keyed to 429/503 don't engage if throttling ships as 400/500. 201-vs-200 breaks clients that branch on `status === 201` to read a created id.
+**Safe change:** 401 strictly = not authenticated (bad/expired credential), 403 strictly = authenticated but not allowed; auth failures always ride HTTP codes, never 200+envelope-0; grep client interceptors for the exact literal before changing any handler's code; include `Retry-After` with 429.
+
+## middleware-mount-order — HIGH · lifecycle-protocol
+**Contract:** The `app.use` sequence is the contract: security/CORS → body parsers → auth/rate-limit middleware → routes → 404 → 4-arg error handler LAST.
+**Detect:** ordering in `server.js`/`app.js`/`index.js`, `app.use(express.json`, `app.use(router`, `app.use(errorHandler`, `express.json({ limit`
+**Ships green, breaks:** A router mounted above `express.json()` sees `req.body === undefined` in Express 5 → every POST 500s, or `req.body?.flag` goes falsy and the default branch runs for all users with no error. Routes registered AFTER the error handler still serve, but their errors bypass it → default HTML error responses that envelope clients can't parse. Auth or rate-limit mounted after routes is fail-open — unit tests that call handlers directly stay green. `express.json` only parses `Content-Type: application/json` — `navigator.sendBeacon` (text/plain) and pre-stringified axios posts arrive with `req.body` undefined.
+**Safe change:** Keep one composition file owning the order above; never register routes in two places; when adding a parser-dependent route, confirm it's below the parser; smoke-test one POST through real HTTP per deploy, not just handler units.
+
+## webhook-hmac-raw-body — CRITICAL · trust-invariant
+**Contract:** The provider signs the exact raw request bytes; the server must verify the HMAC over those SAME bytes before trusting the event (often payment/provisioning events).
+**Detect:** `express.raw(`, `rawBody`, `createHmac`, `timingSafeEqual`, `verify: (req, res, buf`, headers `stripe-signature`/`x-hub-signature-256`/`x-signature`
+**Ships green, breaks:** Computing the HMAC over `JSON.stringify(req.body)` after `express.json()` produces different bytes (whitespace, unicode escaping, number formatting) → every signature mismatches → all deliveries rejected; the provider retries, then disables the endpoint — events silently lost. The common "fix" (skipping verification) fails OPEN to forged payment events. If `app.use(express.json())` runs globally, a route-level `express.raw()` gets an already-consumed stream → empty buffer → same permanent mismatch. `crypto.timingSafeEqual` THROWS RangeError on unequal lengths (length-check first), and `sig === expected` is a timing oracle. Providers redeliver on timeout/non-2xx → duplicate side effects.
+**Safe change:** Mount `express.raw({ type: 'application/json' })` for the webhook path (or global `express.json({ verify: (req, res, buf) => { req.rawBody = buf } })`); length-check then `timingSafeEqual` on hex-digest Buffers; respond 2xx fast and process async; dedupe on the provider's delivery-id header persisted atomically with the side effect.
+
+## zod4-silent-semantics — HIGH · serialized-shape
+**Contract:** Request-validation schemas written with zod 3 idioms meet the zod 4 runtime, which silently ignores or re-interprets several idioms instead of erroring.
+**Detect:** `required_error`, `invalid_type_error`, `errorMap`, `z.record(` with one arg, `.default(`, `.errors`, `.flatten()`, `.format()`, `.strict()`, `.passthrough()`
+**Ships green, breaks:** `required_error`/`invalid_type_error` params were DROPPED — plain-JS call sites are silently ignored, custom messages vanish and clients string-matching them break (`errorMap` is renamed to the unified `error` param). Single-arg `z.record(z.string())` constructs fine and parses EMPTY objects fine, then throws on the first non-empty input; `z.record(z.enum([...]), v)` is now EXHAUSTIVE (missing enum keys fail — v3 was partial; use `z.partialRecord`). `.default(v)` now short-circuits on undefined and returns `v` as-is WITHOUT running transforms/coercions — use `.prefault()` for v3 behavior. `ZodError.errors` alias is removed → `err.errors.map` TypeErrors inside catch blocks (use `.issues`); `.format()`/`.flatten()` are deprecated for `z.treeifyError()`/`z.flattenError()`.
+**Safe change:** On any zod-touching edit, grep for dropped params and one-arg `z.record`; audit enum-keyed records for intended partiality; re-test every `.default()` whose value relied on transforms (switch to `.prefault()`); replace `.errors` with `.issues` in all error handlers.
+
+## zod-query-param-coercion — HIGH · serialized-shape
+**Contract:** Query and path params arrive as strings (or string arrays); the schema's coercion layer is where wire strings become the types handlers assume.
+**Detect:** `safeParse(req.query`, `parse(req.query`, `z.coerce.`, `z.coerce.boolean`, `req.query.` feeding numeric/boolean logic
+**Ships green, breaks:** `z.coerce.boolean()` is `Boolean(x)` — `?active=false` and `?active=0` coerce to TRUE (any non-empty string is truthy). `z.coerce.number()` turns `?page=` (empty string) into `0`. Duplicate keys `?id=1&id=2` arrive as `string[]` and fail `z.string()` only for requests that actually send duplicates. Uncoerced `z.number()`/`z.boolean()` on query rejects every real request while handler unit tests (fed real numbers/booleans) stay green. Combined with Express 5's `'simple'` parser, nested-object query schemas never match at all.
+**Safe change:** Use `z.stringbool()` (zod 4) or an explicit `z.enum(['true','false']).transform(...)` for flags — never `z.coerce.boolean()` on query strings; wrap repeatable params in `z.union([T, z.array(T)])`; design query schemas so their INPUT type is string, and test through real URLs.
+
+## axios-error-and-timeout-contract — HIGH · rendezvous-string
+**Contract:** Client catch-blocks and retry logic branch on axios 1.x's error taxonomy — `err.response` vs `err.request` vs config error, and literal `err.code` strings — plus its `validateStatus`/`timeout` defaults.
+**Detect:** `err.response`, `err.request`, `err.code ===`, `'ECONNABORTED'`, `'ETIMEDOUT'`, `validateStatus`, `timeout:`, `transitional`, `isAxiosError`
+**Ships green, breaks:** Default `timeout: 0` — axios NEVER times out; a hung upstream pins the request forever and retry logic never fires. When a timeout is set, it rejects with `code: 'ECONNABORTED'` (not ETIMEDOUT) unless `transitional: { clarifyTimeoutError: true }` flips it to `'ETIMEDOUT'` — retry code matching the other literal silently never retries. The timeout is socket-inactivity based, NOT a whole-request deadline: a slowly trickling response can run far past it. Default `validateStatus` rejects 3xx/304 as errors, and overriding it to `() => true` reroutes 4xx/5xx into the SUCCESS interceptor, bypassing envelope error handling. Response headers are lowercase-normalized: `err.response.headers['Retry-After']` is undefined; use `'retry-after'`.
+**Safe change:** Set an explicit `timeout` and decide the code literal via `transitional.clarifyTimeoutError`, matching retry logic to it; use `signal: AbortSignal.timeout(ms)` for a hard deadline; branch `err.response` → server replied, `err.request` → no reply, else config bug; never touch `validateStatus` without auditing both interceptor arms.
+
+## cors-allowlist-mirror — HIGH · config-elsewhere
+**Contract:** `cors({ origin: process.env.FRONTEND_URL, credentials, allowedHeaders, exposedHeaders })` must mirror exactly what browser code sends and reads — enforcement happens only in the browser, never in server tests.
+**Detect:** `cors({`, `FRONTEND_URL`, `allowedHeaders`, `exposedHeaders`, `credentials: true`, `withCredentials`, `Access-Control-`
+**Ships green, breaks:** `FRONTEND_URL` unset → `origin: undefined` → the cors package falls back to `*`: silently allows EVERY origin AND breaks all credentialed requests (browsers reject `Access-Control-Allow-Origin: *` with credentials). A comma-joined multi-origin string matches nothing — must be an array or function. If `allowedHeaders` is omitted, cors reflects the request's headers (permissive); once it's explicitly set, adding a new client header without updating it fails ONLY the browser preflight — curl, Postman, and server-to-server all pass. Custom response headers are invisible to client JS without `exposedHeaders`. Errors thrown before the cors middleware produce responses without CORS headers — the browser shows "CORS error", masking the real 500. Cookies need BOTH server `credentials: true` and axios `withCredentials: true`; each alone ships green.
+**Safe change:** Fail boot if `FRONTEND_URL` is unset; origins as array/function; treat `allowedHeaders`/`exposedHeaders` as part of every header-adding change on either side; mount cors first; verify with a real browser preflight, not curl.
+
+## rate-limit-trust-proxy — HIGH · trust-invariant
+**Contract:** express-rate-limit buckets by `req.ip`, which Express computes from `X-Forwarded-For` according to `app.set('trust proxy', ...)` — the limiter key is only as honest as the declared proxy-hop count.
+**Detect:** `app.set('trust proxy'`, `rateLimit(`, `keyGenerator`, `X-Forwarded-For`, `ipKeyGenerator`
+**Ships green, breaks:** `trust proxy: true` → `req.ip` is the LEFTMOST `X-Forwarded-For` entry, fully attacker-controlled — every request can present a fresh IP, bypassing the limiter (fail-open on login brute force); express-rate-limit v7 only console-logs `ERR_ERL_PERMISSIVE_TRUST_PROXY` and keeps serving. Unset behind nginx/Cloudflare → `req.ip` is the proxy's IP → the entire userbase shares ONE bucket → production-wide 429s that dev never reproduces (`ERR_ERL_UNEXPECTED_X_FORWARDED_FOR`). A custom `keyGenerator: (req) => req.ip` without IPv6 masking lets one user rotate a /64 for fresh buckets (use the exported `ipKeyGenerator` helper).
+**Safe change:** Set `app.set('trust proxy', 1)` with the exact hop count — never `true`; re-count hops whenever proxy topology changes; treat ERL console errors as failures, not noise; smoke-test `req.ip` from outside the proxy after deploy.
+
+## route-path-client-rendezvous — MED · rendezvous-string
+**Contract:** axios/fetch URL strings in the client and Express mount + route strings on the server meet only at runtime — no compiler or test links them.
+**Detect:** `axios.(get|post|put|delete)('/`, `baseURL`, `fetch('/api`, `app.use('/api`, `router.(get|post)('/`, SPA catch-all `app.get('/{*splat}'`
+**Ships green, breaks:** Renaming a mount (`/api/v1` → `/api/v2`) or route segment 404s every call site — and when an envelope-unwrapping interceptor swallows instead of rethrowing, callers get `undefined` and render empty states with no error. An SPA catch-all serving index.html turns API-path typos into 200 `text/html` responses that fail JSON parsing far from the cause. Express defaults are case-insensitive and trailing-slash-tolerant — enabling `strict routing`/`case sensitive routing` changes which existing client strings still match.
+**Safe change:** Centralize client paths in one api module (no inline URL literals); grep both repos for the old path before any rename; mount an API-scoped 404 (JSON envelope) before the SPA catch-all so `/api/*` never falls into index.html; prefer additive versioned mounts over in-place renames.

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.