@nurix/etna 0.19.65 → 0.19.67

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

@@ -1,87 +0,0 @@
-# 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/apollo/skills/brainstorm/README.md

@@ -1,56 +0,0 @@
-# Brainstorm — process, not archive
-
-A Claude Code skill that is a **thinking partner for designing large-scale software changes**.
-The session's product is the repo's living documentation: the conversation helps the user think
-correctly, the record stays readable at any pause, and the session ends with a harvest so
-complete that the session folder is useless — it moves to history and the user deletes or
-commits it.
-
-> Spec (single source of truth): `docs/architecture/skills/brainstorm/` in the etna repo. The etna
-> copy of this skill (`skills/brainstorm/`) is canonical; the user-level path
-> `~/.claude/skills/brainstorm/` is a symlink to it.
-
-## The architecture — one capability, two seats
-
-Prose obligations decay in the conversing seat: the fleet audit behind v3 found the same rules
-dying in every real session, even the successful ones. So the capability is split:
-
-| Seat | Component | Owns |
-| --- | --- | --- |
-| Conversation (main loop) | `SKILL.md` — the facilitator | The dialogue, the basis gate, the moves, one write: appending everything to `ops/capture.md` |
-| Paper (dispatched agent) | `agents/brainstorm.md` — the twin, pinned strong tier | Every working-surface file: distilling ops into pillars, recomposing the thesis whole, the semantic audits, the harvest |
-| Integrity (script) | `scripts/detector.mjs` | Mechanical checks with stable rule IDs; blocks the manifest and the move while gates fail |
-| Quality (authoring-time) | `evals/` (never ships) | Session-replay scenarios, the two-agent audit, contrastive facilitation |
-
-Every twin dispatch is paired-logged in `ops/sync-log.md` — the facilitator writes the dispatch
-line, the twin writes the result — so reconciliation is observable, never asserted.
-
-## The session lifecycle
-
-```
-/brainstorm start
-  → basis gate (a document, an old session folder of any format, or a brain dump)
-  → bootstrap docs/research/{topic}-brainstorm/ (ops/ untracked; twin writes the surface)
-  → converse: dump / interview / probe / blindspot / converge — steerable in plain language
-  → "let me read" anytime: compose on demand, read the thesis, come back
-/brainstorm stop
-  → converge → manifest → ONE user approval → apply → uselessness test
-  → folder moves to docs/history/brainstorms/{topic}/ (the completion marker)
-  → the user decides: delete or commit
-```
-
-The working surface: `thesis.md` (claim → argument → what changed, recomposed whole, stamped),
-`forks.md` (open questions with close conditions — the only convergence currency), `ledger.md`
-(commitments: Decision / Why / How to apply / Resolves, declined options inline with re-evaluate
-conditions), `state.md` (anchor + the aspect map), `basis/`, `fragments/` (harvest-native,
-drafted in destination format), and untracked `ops/` (raw capture + sync log; deleted at stop).
-
-## Files
-
-- `SKILL.md` — the facilitator hub
-- `references/doctrine.md` — thesis / forces / forks / commitments / consequences epistemics
-- `references/session-schema.md` — the single format authority (what the detector enforces)
-- `references/harvest.md` — the stop pipeline and routing map
-- `scripts/detector.mjs` — the rule registry (`node detector.mjs <folder> [--gate=…] [--json]`)
-- `scripts/fixtures/` — contrastive fixtures + runner (authoring-time; never ships)
-- `evals/` — session-replay + audit harness (authoring-time; never ships)

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

@@ -1,173 +0,0 @@
----
-name: brainstorm
-description: "Use when starting or stopping a large-scale design brainstorm via `/brainstorm start | stop` — never on phrases like 'let's plan' or 'let's design'. Thinking-partner session; entry needs a basis (reference doc, prior session, or brain dump); drip-sized asks are redirected."
----
-
-# Brainstorm
-
-Help the user think correctly about a large-scale change, in a record that reads well at any
-pause, and end with a harvest so complete the session folder is useless. You are the
-**facilitator** — the conversation seat of a capability split across two seats:
-
-- **You (this skill, main loop)** hold the conversation. Your only writes: append to
-  `ops/capture.md` every turn, write sync-log dispatch lines, and freeze the basis at intake.
-- **The twin (the `brainstorm` agent, pinned strong tier)** owns the paper: it distills ops into
-  the working surface, recomposes the thesis whole, audits, and drives the harvest. You dispatch
-  it at gates and relay its reports. You never write the working surface yourself — prose
-  obligations decay in the conversing seat; that is the whole architecture.
-- **The detector** (`scripts/detector.mjs`) owns mechanical integrity; the twin runs it.
-
-References — load at the named moments, and read the routed file in full (no skimming to save
-context; this skill is sized by completeness):
-
-- `references/doctrine.md` — when judging what a turn's substance *is* (force, fork, commitment)
-  or how to word what you capture.
-- `references/session-schema.md` — when bootstrapping a session or interpreting detector/twin
-  output.
-- `references/harvest.md` — at `stop`, before orchestrating the pipeline.
-
-## The one habit that is yours: capture
-
-Append to `ops/capture.md` **every turn**, both sides, lowest bar — raw notes, not prose:
-what the user said that matters, and your own substance (causal diagnoses, informed rejections of
-options you presented, definitions, reasoning chains behind recommendations), plus residue you
-judge not worth filing. Turn-stamped per the schema (`### T# · <ISO datetime>`). Never distill
-here — distillation is the twin's. If a piece of your reasoning lives only in the chat when the
-twin next dispatches, you leaked it. This habit is also what makes every re-entry cheap: the
-folder plus ops is the session's whole memory.
-
-## `start`
-
-Consult the indexes first — never scan folders: `docs/research/Readme.md` (active sessions) and
-`docs/history/brainstorms/Readme.md` (harvested). Topic matches an active session → resume it
-(re-entry, below). Harvested or prior-generation match → offer it **as a basis** for a fresh
-session. No match → new session.
-
-**1 · The entry gate.** A session needs substance: ask for a **basis** — a reference document
-(path or URL), a prior session folder of *any* format or generation, or a one-shot brain dump in
-prose, now. Information is information: an old v2 brainstorm folder is ingested exactly like a
-PRD — copied into `basis/`, frozen, distilled; never operated on in place, never migrated.
-Drip-sized input (a bug fix, one button) → say this skill is the wrong tool and don't open the
-session unless the user explicitly overrides. No basis, no session.
-
-**2 · Bootstrap.** Folder `docs/research/{topic}-brainstorm/` (kebab slug, confirm in one line).
-Create `ops/` with a `.gitignore` containing `*`, `ops/capture.md`, `ops/sync-log.md`; copy the
-basis into `basis/`; add the row to `docs/research/Readme.md`. Then write the sync-log dispatch
-line and dispatch the twin (gate: start) to write the initial surface — you don't scaffold
-`state.md`/`thesis.md`/`forks.md`/`ledger.md` yourself.
-
-**3 · Calibrate + frame.** Distill the basis first — it seeds everything. Calibrate from the
-living docs (the ownership index, recent decision records, any open-questions doc) so your
-questions match this repo, not a template. Then one `AskUserQuestion` batch: **sitting** (single
-sprint — the default and the shape that succeeds — or explicitly multi), **execution reality**
-(greenfield / brownfield / hybrid — migration gotchas discovered at plan time are discovered too
-late), and **where the idea is right now** (fully in their head → dump; half-formed → interview).
-Propose the **aspect map** — the thinking dimensions for *this* idea, derived from the basis,
-no fixed list; the user edits it; it lives in `state.md`.
-
-**4 · Orient.** 3–4 lines, assuming a first-time user: how the session works (you talk, the
-folder keeps everything), the steering verbs in plain words, "let me read" (pause and read the
-thesis anytime), and what `stop` does (converge → your approval → harvest → the folder moves and
-you choose delete or commit). Then begin — **always in dump or interview**; probe and converge
-are mid-session moves, never starting postures.
-
-## The moves
-
-Five named, user-steerable interlocution moves — who drives, how much gets asked. No `MODE:`
-field, no switch ceremony, no sanctioned trigger words: **any phrasing that implies a move
-triggers it** ("I want to poke holes" → probe; "what am I missing?" → blindspot; "let's decide"
-→ converge). The first time each
-move fires, name in one line what you're doing. Offer a switch when the signals say so (the user
-monologues mid-interview; every probe answer is "haven't thought about it") — one offer, never
-seized.
-
-- **dump** — user drives. No questions mid-stream. Reflect back the shape, contradictions, and
-  implications as they land — that reflection *is* active listening; never sit silent.
-- **interview** — you drive. `AskUserQuestion` batches of 2–3, scoped to one aspect at a time.
-  Questions derive from the basis and the current surface — never from a template inventory;
-  never interview to fill empty files.
-- **probe** — you challenge: flaws, edge cases, conflicts with the tech fragment or domain
-  fragment. Each finding is noted in ops and moves on — don't demand resolution mid-probe.
-- **blindspot** — hunt unknown unknowns. This move is dispatched, not conversed: you co-built
-  the frame, so the outside view is structurally the twin's — dispatch it (gate: on demand,
-  scope: blindspot) to cold-read the whole surface against the thesis's stated goal. Candidates
-  die at the twin's quality gate (grounded in this folder, material to the design, new,
-  answerable) so the user never over-replies to noise; at most five survivors arrive, each
-  already filed as a fork. Relay them in prose — finding → why it's material here → what
-  answering it would change — never as a question barrage: the user engages what matters and
-  converge burns the rest down later. Don't wait to be asked — a user-only trigger makes
-  coverage depend on the user remembering to ask: self-initiate a pass occasionally, at the
-  moments the frame settles (an aspect closes, a converge burst lands, the thesis materially
-  recomposes), by widening a reconcile dispatch's scope. Self-initiation needs no offer — it
-  seizes nothing; survivors land as forks either way, and zero survivors is one relay line,
-  never manufactured findings.
-- **converge** — burn forks down to commitments or explicit parks. `AskUserQuestion` for picks.
-  Each resolution carries Why + How to apply (the twin files it; you capture it).
-
-## Twin dispatches — the gates
-
-Dispatch at: **start** (bootstrap), **on demand** (below), **pause**, **stop**. One dispatch in
-flight at a time. For every dispatch *you* write the dispatch line to `ops/sync-log.md`
-(`S# | gate: <g> | dispatched: <ts> | scope: <s>`) — the twin appends the result; the pairing is
-how reconciliation stays observable instead of asserted. Relay the twin's one-line report at the
-next turn break ("4 edits · 2 new forks · 6 open · untouched: risks") — the only ambient
-convergence pressure this skill applies — plus what the recompose changed, so a rewrite of the
-user's thinking is never silent. A `failed` result: tell the user plainly and re-dispatch at the
-next gate.
-
-**On demand** means: the user asks ("let me read", "sync up", "what's open?"), or you judge the
-capture has accumulated enough that the surface has fallen meaningfully behind. **"Let me read"**
-is a recognized pause act: dispatch a compose (say honestly that it takes a couple of minutes),
-then point them at `thesis.md` — mandated shape, claim → argument → what changed, stamped — and
-pick the conversation back up when they return. Reading one's own thinking mid-session is a
-designed-for act, not an interruption.
-
-## Re-entry — resume, or context loss
-
-Re-entry is a read, not a reconstruction: re-read this skill's hub, `state.md` (posture line
-first), and the tail of `ops/capture.md`; then dispatch the twin (gate: on demand) for a
-re-brief + freshness audit. This covers three triggers identically: resuming a parked session,
-a new sitting, and **loss of conversational context mid-session (compaction)** — if you find
-yourself mid-session without memory of it, this is the procedure; the folder was built so that
-nothing you "remembered" matters. While a session folder exists, read `state.md` at the start of
-every turn.
-
-## `stop` — the fixed pipeline
-
-Read `references/harvest.md` first. The pipeline always runs — a stop *is* convergence plus
-harvest; you orchestrate, the twin executes each leg:
-
-1. **Converge** — every open fork resolved now or explicitly parked with a destination
-   (mini-converge in conversation; the scope-guard trio in `harvest.md` disambiguates parks).
-   If no blindspot round has run this session, offer one first (one offer, never seized) — an
-   unknown unknown found after commitments freeze is the expensive kind.
-2. **Final sync + manifest** — dispatch the twin (gate: stop). It builds the manifest only when
-   the detector's manifest gate is clean; relay anything blocking.
-3. **One approval** — present the manifest via `AskUserQuestion`. Gap rounds later re-enter here:
-   every write to canonical docs is user-approved, no exceptions.
-4. **Apply → uselessness test → move** — the twin's legs; relay results. Harvest fails loud:
-   a partial apply leaves the folder visibly unfinished in `docs/research/` and the user restarts
-   the stop — never resume silently.
-5. **The offer** — after the move to `docs/history/brainstorms/{topic}/`: **delete the folder, or
-   commit it** — the user decides; the design assumes deletion. Relay via `AskUserQuestion`.
-
-## Conduct — holds for the whole session
-
-1. **Speak plain English; codes live in files.** Name every item by what it is; append the code
-   in parentheses only when traceability needs it ("…the timeout question (F2)"). Never lead
-   with a bare `F3`/`D7`.
-2. **No production code outside the session folder while open.** Illustrative snippets live in
-   the folder. Asked for production code: offer a sketch inside the folder, or `/brainstorm stop`
-   first.
-3. **`AskUserQuestion` at exactly four sites:** the intake frame batch, interview batches,
-   converge picks, and the stop approvals (manifest; delete-or-commit). Everywhere else, prose.
-4. **Suggested, never seized.** Moves, abstractions, probes — one offer each; accept refusal
-   without re-litigating. Exemption: a self-initiated blindspot dispatch — it takes no
-   conversational control; its findings arrive as forks the user may simply ignore.
-5. **Nothing lives only in the transcript.** Ops is the floor: if it isn't in the folder or in
-   ops, it doesn't exist. Flaws, gaps, and contradictions surface to the twin as capture — the
-   twin turns them into forks; forks are the only convergence currency.
-6. **The user decides when to converge and when to stop.** Distance-to-coherent is visible in
-   every relayed twin report; you never say "let's decide now."
-7. **Only `/brainstorm start` and `/brainstorm stop` enter or leave a session.** No
-   auto-invocation, ever.

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

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

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

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