@nurix/etna 0.20.38 → 0.20.40

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

@@ -1,142 +1,90 @@
 # 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:
-
-1. Converge.
-2. Final sync and compose → manifest (`Status: proposed`).
-3. **One** user approval (`Status: approved`).
-4. Apply, reading both sides of every destination (`Status: applied`).
-5. Uselessness test — gaps open a new `Round` and return to step 3.
-6. Move to `docs/history/brainstorms/{topic}/` — the completion marker.
-7. 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 **never** writes a canonical doc without an approved
-manifest, gap-round fixes included.
-
-## The routing map
-
-Route each piece of the surface by scope. Format every artifact through the `documentation` skill;
-where it is unavailable, format it yourself and record in the manifest which path ran. 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 — drafted in destination format, 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 — **never** duplicates prose across them, and
-**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 is **never** 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`); its 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:
-
-1. Delete `ops/` entirely — transcript-grade residue **never** enters git.
-2. `git mv` the folder to `docs/history/brainstorms/{topic}/`.
-3. Set `Status: harvested` in `state.md`.
-
-Update no index — none keeps a row per session. The move is the completion marker: a folder 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 loss is accepted by design.
+Load when: `/brainstorm stop`; any question about where session content lands. The twin reads it to build the manifest.
+
+Stop is a fixed pipeline: converge, final sync, one approval, apply, the uselessness test, the move, the offer. You orchestrate it, because every approval belongs to the user; the twin executes each leg as a `stop` dispatch. The session's product is the mutated living docs, so the pipeline's exit condition is checkable: a context-free reader given only the harvested destinations reconstructs the design. Until that passes, the folder stays under `docs/research/`, visibly unfinished.
+
+## 1. Converge
+
+Every open fork is resolved into a decision or parked with a destination, now.
+
+- **Offer one blindspot pass first** if none has run this session: one line, yes or no. A yes dispatches it before the convergence.
+- Run the convergence as converge picks: one pick per fork, recommendation first, batched. A park names where its resolution will land.
+- The user may resolve or park; they may not leave a fork open. A fork the user will not decide is parked to the repository's open-questions home.
+
+## 2. Final sync and manifest
+
+Dispatch the twin, scope `final sync + compose + manifest`. It reconciles, composes, runs the detector at `--gate=manifest`, and builds `ops/manifest.md` (`Status: proposed`) only when that gate is clean. While the gate fails, relay what blocks in plain words and go back to step 1.
+
+## 3. One approval
+
+Show the manifest table and ask once: approve, or name the rows to change. This is the designed gate before the harvest writes into canonical documents; nothing is written until it is answered, and on silence the session stays open with the manifest proposed. Under standing approval ("don't seek any more approvals"), record the approval as standing and continue.
+
+## 4. Apply
+
+Dispatch the twin, scope `apply`. It sets `Status: approved`, reads **both sides** of every destination before writing (the destination's current content is a contract, not a blank page), formats each artifact through the `documentation` skill, and sets `Status: applied`.
+
+**The apply is all-or-nothing and loud.** If it cannot finish, the twin reports exactly what applied and stops; relay that verbatim. The folder stays under `docs/research/`, and the user restarts the stop. Never resume silently from a half-applied state: a bad harvest corrupting canonical docs is worse than a skipped one, and a loud early failure the user can fix beats damage discovered after the folder is gone.
+
+## 5. The uselessness test
+
+Dispatch the twin, scope `uselessness test`. It spawns a fresh, context-free cold reader whose brief holds only the allowed-path list (the manifest's destinations, never the session folder) and the task to reconstruct the design: the thesis, the commitments, the reasoning, the declined branches. It grades the reconstruction against the ledger and the thesis and records the result in the manifest.
+
+- **Pass** (`Result: pass`, `Gaps: none`) → step 6.
+- **Gaps** → each is a named piece of knowledge the destinations lost. The fix re-enters at step 3 as a delta manifest (`Round` incremented), approved like the first, then applied and retested.
+
+If the twin reports it cannot spawn a sub-agent, dispatch the cold reader yourself, on the **standard tier** (Sonnet on Anthropic; the flagship model at default reasoning effort on OpenAI): reconstruction from a short path list is synthesis, not frontier work. Its brief is the allowed-path list and the reconstruction task, nothing else; give the twin its reply to grade. Neither you nor the twin may be the reader: a reader that has seen the session already knows every undefined term.
+
+## 6. The move
+
+Dispatch the twin, scope `move`. It runs `--gate=move`, deletes `ops/`, moves the folder to `docs/history/brainstorms/{topic}/` (with `git mv` when any file in it is tracked, plain `mv` when none is, because `git mv` refuses a never-committed folder), and sets `Status: harvested`. The location is the completion marker: a folder still under `docs/research/` is unfinished by definition. Under standing approval, hold this step and step 7 for the end-of-session message, because deleting the untracked capture cannot be undone.
+
+## 7. The offer
+
+Relay the twin's offer as one question: **delete the moved folder, or commit it.** The design assumes deletion, since the uselessness test has made the folder redundant; committing keeps a git-history record the user chose. An uncommitted folder deleted at stop leaves no forensics, which the user accepts by choosing delete.
+
+## Where content lands
+
+The twin routes by scope, never by surface file:
+
+| Piece of the surface | Destination |
+| --- | --- |
+| The whole surface, distilled | one reader-first source-of-truth document at the repository's canonical home (`docs/features/`, `docs/architecture/`, else a topic `Readme.md`): the thesis as what it is, the domain fragment as how it works, the ledger as present-tense rationale with no `D`/`F` codes |
+| Executable work | plans, split by deliverable, never by surface file |
+| Decisions | one record per decision subject; a decision revising a recorded subject updates that record in place, its declined alternatives riding along |
+| Domain-model changes | the living domain-model document, which the `boundary` skill reads at the next plan check |
+| Parked forks | the repository's open-questions home, each pointing to where its resolution will land |
+| Will-build-later | the backlog |
+| Deliberately-not-building | the destination's non-goals |
+| Weighed and chose another | a **Declined:** line with its re-evaluate condition, in the decision record or the source-of-truth document's rationale |
+
+- **Rejection rationale and reasoning chains need an explicit destination**, or the uselessness test fails; they are what living docs lose first.
+- **No destination links back into the session folder.** The folder is about to be deleted; a link into it is a pointer to nothing, and the detector fails the move on one.
+- **Steering is not feature truth.** A harvested principle goes to the steering layer (`docs/architecture/`); a feature fact goes to its feature doc. The harvest links between them and never copies prose across them.
+- **Starting or harvesting a session edits no index.** The folder's location is the record.
+
+## Degradations — flagged, never silent
+
+| Missing | Then |
+| --- | --- |
+| The `documentation` skill | the twin formats the artifacts itself, and the manifest records which path ran |
+| Nested sub-agent dispatch | you dispatch the cold reader (step 5) |
+| The detector, or Node | the twin runs the schema's checks by hand and says so in its report; relay it as a flagged fact |
+| Any leg failing | the twin logs `S<n> → failed` with the reason; relay it and re-run that leg |
 
 ## Field lessons — apply
 
-Each is a rule measured on live harvests.
-
-- **Run the move gate clean immediately before the move and treat that as the verdict** — the
-  gate's checks read `ops/`, which the move deletes, so a post-move re-run fails by construction.
-  Verify the post-move state by hand: `Status: harvested`, no `ops/`, `check-links` clean.
-- **Distil the process record into `state.md` before the move** — the sync log dies with `ops/`,
-  and a ten-line dispatch summary separates a record that shows its workings from one that asserts
-  its commitments from nowhere.
-- **Uncommitted harvest artifacts are deleted, not deprecated** — deprecate-in-place protects
-  readers holding a pointer, and a never-committed file has none; a tombstone for a
-  twenty-minute-old file is ceremony.
-- **At manifest time, read every existing AD's Decision and Open Questions against the new
-  commitments.** A harvest routes only through the docs its commitments name, and the test is
-  commitment-level, not textual — grep finds nothing, because the ledger never names the
-  neighbours. Report the unimpacted verdicts with their evidence too.
-- **A manifest row names one site; the file you open holds more.** Fix every same-doctrine site
-  inside a file the manifest already opens — a self-contradicting document is worse than a wider
-  diff — but **never** wander into an unnamed file: that becomes a backlog row, because a canonical
-  doc is not rewritten outside an approved scope. Say which you did, per row, in the application
-  record.
-- **Re-run the uselessness test when the destination *set* changes**, not only when content does —
-  a consolidation that moves referrers produces a document set no cold reader has graded. The
-  recurring find: a truth doc stating a decided-but-unbuilt mechanism in the present tense; the
-  fix is one clause naming the unbuilt prerequisite.
-- **Retirement wording beats suppression.** `doc-lint`'s heuristics block the honest retirement
-  sentence (`superseded by`, `no longer`); rephrase with no loss of meaning — "retired by
-  AD-00N", "is not the product's position", "lives in a package that is gone" — and reach for
-  `doc-lint-disable` only when the banned phrase is itself the claim.
-- **Amending another session's draft: change the contradicting claim everywhere it is asserted,
-  and nothing else** — a claim stated in nine places and fixed in three leaves the doc worse; a
-  one-paragraph note saying what moved and what did not keeps the amendment legible to the doc's
-  author.
-- **A suppression marker is a dated assertion about code, and it decays faster than the docs
-  around it.** A harvest that deletes doctrine rows corrects their wrappers first — a false wrapper
-  is a correction row in the manifest, never collateral of a delete. A phantom guard propagates by
-  citation: grep the guard *path*, not its name, and count live docs separately from frozen ones,
-  which record what was believed and are not edited.
-- **Retiring a guardrail row edits three artifacts.** The row is cited by ID from feature docs and
-  frozen plans, wrapped in a marker asserting where its code lives, and restated in the
-  out-of-scope register at the foot of the same file: keep the ID and mark the row retired with a
-  pointer, correct the wrapper, and replace the register bullet with a pointer — otherwise the file
-  contradicts itself twenty lines apart.
-- **Size the decision records to the repo's AD doctrine before writing them.** One decision per
-  subject argued feels natural and produces micro-ADs where the rule is one overarching AD per
-  architectural subject; the test at manifest time is whether a reader would ever need one record
-  without the others. The safe shape is one AD per plane with a section per settled subject — each
-  keeping its Decision, Why and Declined table — and a separate AD only for a genuinely different
-  subject. Link with section anchors where a bare pointer loses precision, and verify anchors by
-  hand: the link checker strips them before resolving.
-- **The per-file lint hook reads intermediate states.** It appends queue rows from mid-edit files;
-  run the linter over the whole edited set before declaring the apply done, and leave the stale
-  rows for the facilitator rather than draining them.
+Each was measured on a live harvest; the twin applies them, and you relay where one changes what the user sees.
+
+- **The move gate run immediately before the move is the verdict.** Its checks read `ops/`, which the move deletes, so a re-run after the move fails by construction. Verify the post-move state by hand instead: `Status: harvested`, no `ops/`, links resolving.
+- **Distil the process record into `state.md` before the move.** The sync log dies with `ops/`; a ten-line dispatch summary separates a record that shows its workings from one that asserts its decisions from nowhere.
+- **A never-committed harvest artifact that turns out wrong is deleted, not deprecated.** Deprecating in place protects readers holding a pointer, and a file that was never committed has none.
+- **At manifest time, read every existing architecture decision's Decision and open questions against the new decisions.** A harvest routes only through the docs its decisions name, and the ledger never names the neighbours, so grep finds nothing: the test is decision against decision. Report the unaffected verdicts with their evidence too.
+- **A manifest row names one site; the file it opens holds more.** Fix every site of the same doctrine inside a file the manifest already opens, since a self-contradicting document is worse than a wider diff, but never wander into a file no row names: that becomes a backlog row, because a canonical doc is not rewritten outside an approved scope. Say per row which you did.
+- **Re-run the uselessness test when the destination set changes**, not only when content does: a consolidation that moves referrers produces a document set no cold reader has graded. The recurring find is a truth doc stating a decided-but-unbuilt mechanism in the present tense; the fix is one clause naming the unbuilt prerequisite.
+- **Rephrase a retirement rather than suppress the linter.** `doc-lint` blocks honest retirement sentences ("superseded by", "no longer"); say "retired by" the record, "is not the product's position", "lives in a package that is gone", and reach for `doc-lint-disable` only when the banned phrase is itself the claim.
+- **Amending another session's draft: change the contradicting claim everywhere it is asserted, and nothing else.** A claim stated in nine places and fixed in three leaves the doc worse; a one-paragraph note on what changed and what did not keeps the amendment legible to its author.
+- **A suppression marker is a dated claim about code and decays faster than the prose around it.** A harvest deleting doctrine rows corrects their wrappers first, as a manifest row of its own, never as collateral of a delete. A phantom guard spreads by citation: grep the guard's path, not its name, and count live docs apart from frozen ones, which record what was believed and are not edited.
+- **Retiring a guardrail row edits three artifacts.** The row is cited by id from feature docs and frozen plans, wrapped in a marker naming where its code lives, and restated in the out-of-scope register at the foot of the same file: keep the id and mark the row retired with a pointer, correct the wrapper, and replace the register bullet with a pointer, or the file contradicts itself twenty lines apart.
+- **Size decision records to the repository's own decision doctrine before writing them.** One record per argued subject feels natural and yields micro-records where the rule is one record per architectural subject; the test is whether a reader would ever need one without the others. The safe shape is one record per plane with a section per settled subject, each keeping its Decision, Why and Declined lines, and a separate record only for a genuinely different subject. Link with section anchors where a bare pointer loses precision, and check anchors by hand: the link checker strips them.
+- **A per-file lint hook reads intermediate states.** It queues rows from mid-edit files; run the linter over the whole edited set before calling the apply done, and leave its stale rows for the facilitator rather than draining them.

package/data/harnesses/delivery/skills/brainstorm/references/session-schema.md

@@ -1,194 +1,157 @@
-# Session schema — the single format authority
+# Session schema — the on-disk contract
 
-Load when: bootstrapping a session, writing any working-surface file, dispatching the twin, or
-interpreting detector output. The detector (`scripts/detector.mjs`) is the mechanical half of this
-contract: every rule below carrying a rule ID is machine-checked; everything else is the twin's
-semantic judgment.
+Load when: bootstrap; writing a capture entry or a dispatch line you are unsure of; relaying a detector finding. The twin reads it on every dispatch.
 
-## Folder layout
+This is the format `scripts/detector.mjs` parses, and the twin, the replay evals and the maintenance census all key on its rule ids. A line that drifts from it fails a rule or, worse, is silently not seen, so match the shapes below exactly: field names, the em dash ` — `, the arrow ` → `, the middle dot ` · `. **Every datetime is UTC in one shape, `YYYY-MM-DDTHH:MMZ`, taken from `date -u +%Y-%m-%dT%H:%MZ`:** the detector compares stamps as strings, so a local-time or differently shaped stamp makes a fresh compose read as stale, or a stale one as fresh.
 
-An open session is `docs/research/{topic}-brainstorm/` (kebab-case topic slug):
+## Layout
 
-| Path | Holds | Writer |
-| --- | --- | --- |
-| `state.md` | anchor + aspect map | twin |
-| `thesis.md` | composed claim → argument → what changed | twin |
-| `forks.md` | open questions with close conditions | twin |
-| `ledger.md` | commitments | twin |
-| `basis/` | frozen entry material | facilitator, once, at intake |
-| `fragments/` | harvest-native fragments, drafted in destination format; created on first real content | twin |
-| `ops/` | the untracked capture layer, deleted at stop | — |
-| `ops/.gitignore` | `*` — `ops/` **never** enters git [BS-OPS-01/02] | facilitator |
-| `ops/capture.md` | the facilitator's raw append ledger | facilitator |
-| `ops/sync-log.md` | the paired twin-dispatch log | both (see below) |
-| `ops/manifest.md` | the harvest manifest | twin, in the stop pipeline |
-
-On a passed harvest the folder **moves** to `docs/history/brainstorms/{topic}/`, `ops/` deleted
-first. The move is the completion marker; the user then deletes or commits the folder. A folder
-under `docs/research/` is by definition unfinished.
-
-**Write protocol (one writer per file; the sync log is paired):** the facilitator bootstraps `ops/` at intake, appends to
-`ops/capture.md`, and writes the initial `basis/` copy plus the sync-log *dispatch* lines —
-**nothing else, ever**. The twin writes every other file, at gates. The user may hand-edit anything;
-the twin diffs each file against its own last compose before rewriting and folds foreign edits in
-as first-class user signal.
-
-## state.md
+```
+docs/research/{topic}-brainstorm/
+├── state.md            twin
+├── thesis.md           twin
+├── forks.md            twin
+├── ledger.md           twin
+├── fragments/{name}.md twin, created on first real content
+├── basis/              facilitator, at intake; frozen
+└── ops/                untracked; deleted at the move
+    ├── .gitignore      facilitator, at bootstrap: the single line *
+    ├── capture.md      facilitator, every turn
+    ├── sync-log.md     dispatch lines: facilitator · result lines: twin
+    └── manifest.md     twin, at stop
+```
+
+On a passing harvest the folder moves to `docs/history/brainstorms/{topic}/` without `ops/`, and `state.md` reads `Status: harvested`.
+
+## `state.md`
 
 ```markdown
 # State
 
-- Status: open | stopping | harvested
-- Posture: mid-probe on the sync-layer aspect, three forks open
+- Status: open
+- Posture: mid-probe on the persistence aspect, two forks open
 - Started: 2026-07-08
-- Sitting: single | multi
-- Last compose: 2026-07-08T14:30Z | never
+- Sitting: single
+- Last compose: 2026-07-08T14:30Z
 
 ## Aspect map
 
-- persistence — how session state survives restarts → F1, D3
+- persistence — how cache state survives restarts → F1, D1
 - onboarding — the first-run experience → thesis
-- risks — failure modes and mitigations → none yet
+- risks — failure modes and mitigations → F2, fragment:domain-model
 ```
 
-- `Status` moves **only** forward: `open → stopping → harvested` — the twin sets `stopping` when the
-  stop pipeline begins and `harvested` at the move [BS-STATE-01].
-- The aspect map is derived per idea from the basis and edited by the user. Each aspect carries
-  `→` refs to the content covering it: fork IDs (`F#`), ledger IDs (`D#`), `thesis`,
-  `fragment:{name}`, or `none yet` (an open coverage gap — informational mid-session
-  [BS-ASPECT-01], blocking at the manifest gate [BS-ASPECT-02]). Ref *presence* is the detector's
-  half; whether the content actually covers the aspect is the twin's.
-
-## thesis.md
+| Field | Values |
+| --- | --- |
+| `Status` | `open` → `stopping` → `harvested`, forward only: the twin sets `stopping` when the stop pipeline begins and `harvested` at the move |
+| `Posture` | one line a resuming reader can act on: where the conversation is and what is next; a parked session says so here |
+| `Started` | ISO date |
+| `Sitting` | `single` · `multi` |
+| `Last compose` | the ISO datetime of the last thesis compose, equal to the thesis stamp; `never` before the first |
 
-```markdown
-# {Topic} — thesis
+Each aspect line is `- {name} — {gloss} → {refs}`, refs comma-separated: `F<n>` (a fork, open or resolved by a decision), `D<n>`, `fragment:{name}` (a file under `fragments/`), `thesis`, or `none yet`.
 
-Current as of: 2026-07-08T14:30Z
+## `thesis.md`
 
-## Claim
-## Argument
-## What changed
-```
+A title, then `Current as of: <ISO datetime>`, then the sections `## Claim`, `## Argument`, `## What changed`, in that order.
 
-Composed prose, rewritten whole at every compose, **never** appended. The three sections and the
-stamp are mandatory [BS-THESIS-01]; the stamp must equal `state.md`'s `Last compose`
-[BS-COMPOSE-01]. At the manifest gate, `Last compose` must be later than the newest
-`ops/capture.md` entry — a compose over unsynced capture is stale [BS-COMPOSE-02].
-
-## forks.md
+## `forks.md`
 
 ```markdown
-## F3 — Should reads wait for a compose? [open]
+## F2 — What happens on catalog API timeout? [open]
 
-Full self-contained prose in the user's framing.
+The cache can serve stale on timeout or propagate the error; the basis is silent on it.
 
-- Raised by: user | twin (S4) | probe | harvest
-- Closes when: a pick between wait-for-fresh and read-stale-with-warning
+- Raised by: twin (S1)
+- Closes when: an accepted failure behavior — stale-serve with a warning, or error propagation
 ```
 
-- IDs `F1, F2, …` unique, never reused [BS-FORK-01]. Status marker: `[open]` or
-  `[parked → {destination}]`. Every fork carries `Closes when:` [BS-FORK-01].
-- `Raised by: twin (S#)` must cite a reconciled sync-log entry [BS-SYNC-02].
-- **The twin deletes a resolved fork's entry** — the resolving ledger entry's `Resolves:` field is
-  the record. `forks.md` holds only open and parked forks; a ledger `Resolves: F3`
-  coexisting with an open F3 is an inconsistency [BS-FORK-02]. Parked forks survive to the
-  manifest, which must route each one [BS-MANIFEST-01].
-- The manifest gate requires zero `[open]` forks [BS-FORK-03].
+The heading's bracket is `[open]` or `[parked → {destination path}]`. `Raised by:` is `user`, `facilitator`, or `twin (S<n>)` citing the reconciled sync that raised it; a blindspot fork's body opens `Blindspot:`. A fork resolved by a decision leaves the file; the decision's `Resolves:` keeps its id.
 
-## ledger.md
+## `ledger.md`
 
 ```markdown
-## D4 — Sessions initialize in dump or interview
-
-- Decision: every session opens in dump or interview; probe and converge are mid-session moves.
-- Why: a first-time user cannot be asked to pick a posture they have no vocabulary for.
-  Declined: free initial posture — observed cold-starts stall in probe; re-evaluate if
-  session-replay evals show experienced users fighting the default.
-- How to apply: the facilitator's start calibration offers only the two entry moves.
-- Resolves: F2
+## D1 — Cache keys are per-tenant
+
+- Decision: every cache key embeds the tenant id; no shared entries.
+- Why: cross-tenant reads are a trust break, and memory cost is acceptable at current tenant
+  counts. Declined: shared keys with tenant checks at read time — a single missed check leaks
+  data; re-evaluate if memory pressure forces it.
+- How to apply: the cache module's key builder prefixes the tenant slug.
+- Resolves: F3
 ```
 
-- IDs `D1, D2, …` unique, append-only [BS-LEDGER-01]. `Decision`, `Why`, `How to apply` are
-  mandatory; `Resolves:` when the commitment closes forks. Amendments and reversals are
-  annotations plus a new entry ("Reversed by D9" on the old; D9 names what it reverses) — never a
-  rewrite. Declined options live inside `Why` per [doctrine.md](doctrine.md).
-
-## ops/capture.md
+`Decision`, `Why` and `How to apply` are required and non-empty; `Resolves` is optional. Ids are unique and never reused.
 
-The facilitator's per-turn append. Lowest possible bar: raw, unpolished, everything
-session-relevant from *both* sides (user substance and facilitator substance — diagnoses, informed
-rejections, definitions, reasoning chains), including residue judged not worth pillar filing.
-Format:
+## `ops/capture.md`
 
 ```markdown
+# Capture
+
 ---
-### T14 · 2026-07-08T14:22Z
+### T2 · 2026-07-08T14:20Z
 
-<raw notes for this turn>
+facilitator: flagged the trust concern on shared entries — a missed tenant check at read time is
+a leak, not a bug. recommended per-tenant keys; user accepted (→ D1). residue: user mentioned a
+"warm-on-deploy" idea in passing, not pursued.
 ```
 
-Turn IDs `T#` ascend, each with an ISO timestamp — the timestamp compose-freshness checks against
-[BS-COMPOSE-02]. **Never** distill here; distillation is the twin's.
-
-## ops/sync-log.md
+Entries are separated by `---`, headed `### T<n> · <ISO datetime>`, numbered in order, and labelled by speaker inside (`user (dump):`, `facilitator:`). The heading's datetime is what the manifest gate compares against the last compose.
 
-Paired-written, one pair per twin dispatch:
+## `ops/sync-log.md`
 
 ```
-S4 | gate: on-demand | dispatched: 2026-07-08T14:25Z | scope: full reconcile + compose
-S4 → reconciled | 2026-07-08T14:29Z | 4 edits · 2 new forks · 6 open · untouched: risks
+S1 | gate: start | dispatched: 2026-07-08T14:05Z | scope: bootstrap reconcile
+S1 → reconciled | 2026-07-08T14:08Z | 2 edits · 1 new fork · 2 open · untouched: risks
 ```
 
-The **facilitator** writes the dispatch line as it dispatches; the **twin** appends the result
-line (`reconciled` or `failed`) on return — **never** one author for both sides. Every dispatch
-line must acquire a result line; only the newest entry may be unpaired (in flight) [BS-SYNC-01].
-A `failed` result is surfaced to the user at the next turn break and re-run at the next gate.
+The facilitator writes the first line as it dispatches; the twin appends the second on return, `reconciled` or `failed | <ts> | <reason>`. Gates: `start` · `on-demand` · `pause` · `stop`. Ids run `S1, S2, …` across the session.
 
-## ops/manifest.md
-
-Created by the stop pipeline; gates the harvest apply:
+## `ops/manifest.md`
 
 ```markdown
 # Harvest manifest — {topic}
 
 Round: 1
-Status: proposed | approved | applied
+Status: proposed
 
 | # | What | Source | Destination | Action |
 |---|------|--------|-------------|--------|
-| 1 | consolidated source of truth | thesis + fragments + ledger | docs/features/{x}.md | create |
-| 2 | parked fork F7 | forks.md | docs/architecture/open-questions.md | append |
+| 1 | consolidated source of truth | thesis + ledger | docs/features/widget-cache.md | create |
+| 3 | parked fork F2 | forks.md | docs/architecture/open-questions.md | append |
 
 ## Uselessness test
 
-- Result: pass | fail
-- Cold-reader allowed paths: <the destination docs above>
-- Gaps: none | <named gaps → next Round>
+- Result: pass
+- Cold-reader allowed paths: docs/features/widget-cache.md, docs/architecture/open-questions.md
+- Gaps: none
 ```
 
-Every parked fork and every fragment must have a row [BS-MANIFEST-01]. `Status: approved` is set
-only after the user approves; gap fixes re-enter as a new `Round` with the same approval
-requirement. After apply, no destination doc may link into the session folder [BS-HARVEST-01];
-the move to history requires a recorded passing uselessness test [BS-USELESS-01].
-
-## Detector
+`Status` runs `proposed` → `approved` → `applied`. Every parked fork's id and every fragment's file name appear in a row's What or Source. Destinations are repository-relative paths. A gap round increments `Round`.
 
-`node scripts/detector.mjs <session-folder> [--gate=session|manifest|move] [--json]`
+## The detector
 
-- `session` (default) — the always-on integrity rules; run at any gate.
-- `manifest` — adds the convergence gates (zero open forks, full aspect coverage, fresh compose);
-  the twin may not construct a manifest while any of these fail.
-- `move` — adds the post-apply gates (manifest applied, uselessness pass recorded, no links into
-  scaffolding); the folder may not move while any fail.
+`node <skill>/scripts/detector.mjs <session-folder> [--gate=session|manifest|move] [--json]` exits `0` clean, `1` with violations listed by rule id, `2` on unusable input. Gates are cumulative: `manifest` runs the session rules too, `move` runs all. A real run always prints per-rule lines and a `clean` or `failing` summary; **empty output means the detector never ran**, which is a failed gate, never a pass.
 
-| Exit | Meaning |
-| --- | --- |
-| `0` | clean |
-| `1` | violations, listed with rule IDs |
-| `2` | unusable input |
-
-A run always prints output — per-rule lines plus a `clean`/`failing` summary, or a usage/error
-message. **Exit 0 with empty output means the detector never executed** — a failure, **never** a
-pass. Rules degrade gracefully: with no git context, `BS-OPS-02` reports `skipped` and never blocks.
-Rule IDs are stable — the twin, the evals, and the maintenance census key on them.
+| Rule | Gate | Fails when |
+| --- | --- | --- |
+| `BS-STATE-01` | session | `state.md` missing, or a field absent or invalid |
+| `BS-STATE-02` | session | no `## Aspect map`, or no parseable aspect |
+| `BS-ASPECT-01` | session | an aspect ref names no such fork, decision or fragment |
+| `BS-THESIS-01` | session | the thesis lacks its stamp or a mandated section |
+| `BS-COMPOSE-01` | session | the thesis stamp differs from `Last compose` |
+| `BS-FORK-01` | session | duplicate fork id, no `Closes when:`, or a park without destination |
+| `BS-FORK-02` | session | a decision resolves a fork still open |
+| `BS-LEDGER-01` | session | duplicate decision id, or Decision, Why or How to apply empty |
+| `BS-OPS-01` | session | `ops/.gitignore` missing or not `*` |
+| `BS-OPS-02` | session | any `ops/` file tracked by git (skipped outside git) |
+| `BS-SYNC-01` | session | a dispatch other than the newest has no result line |
+| `BS-SYNC-02` | session | a `twin (S<n>)` attribution cites a sync that never reconciled |
+| `BS-ASPECT-02` | manifest | an aspect has no content (`none yet`) |
+| `BS-COMPOSE-02` | manifest | the newest capture entry is newer than the last compose |
+| `BS-FORK-03` | manifest | any fork is open |
+| `BS-MANIFEST-01` | manifest | a parked fork or a fragment has no manifest row |
+| `BS-HARVEST-01` | move | a destination is missing, or links into the session folder |
+| `BS-USELESS-01` | move | no passing uselessness test with `Gaps: none`, or the manifest is not `applied` |
+
+When you relay a finding, name the rule id and what it means for the user, in plain words: "the last compose predates the newest capture (`BS-COMPOSE-02`), so the twin syncs before the manifest".

package/data/harnesses/etna/agents/brainstorm.md

@@ -28,8 +28,9 @@ as a failed gate and report it, never as a pass.
 ## The write protocol you enforce
 
 One writer per file. You write `state.md`, `thesis.md`, `forks.md`, `ledger.md`, `fragments/`,
-manifest, and your own sync-log **result** lines. You never write `ops/capture.md` (the
-facilitator's) or sync-log dispatch lines. The user may hand-edit anything: before rewriting any
+manifest, and your own sync-log **result** lines. You never write the facilitator's files — the
+folder, `ops/` and `ops/.gitignore` at bootstrap, `basis/` at intake, `ops/capture.md` — or
+sync-log dispatch lines. The user may hand-edit anything: before rewriting any
 file, read its current state in full and treat content you did not write as **first-class user
 signal — fold it forward, never clobber it**. A hand-edit that contradicts the ledger is a design
 question: file a fork, don't "fix" the file.
@@ -116,13 +117,16 @@ Stop is facilitator-orchestrated because approval belongs to the user; you execu
    what applied and stop — the folder stays visibly unfinished and the user restarts; never
    resume silently from a half-applied state.
 3. **Uselessness test.** Spawn a **fresh, context-free cold reader** — an independent subagent
-   that inherits none of this session's context — whose prompt contains only the allowed-path list
+   on the standard tier (`model: sonnet`, named on the dispatch so it never inherits yours) that
+   inherits none of this session's context — whose prompt contains only the allowed-path list
    (the manifest's destinations — never the session folder) and the instruction to reconstruct the
    design: thesis, commitments, reasoning, declined branches. Grade its reconstruction against the
    ledger and thesis. Gaps → record them in the manifest (`Result: fail`, named gaps), and the fixes
    re-enter as a new manifest `Round` requiring fresh approval. Pass → record it.
-4. **Move.** Run `--gate=move`. When clean: delete `ops/` entirely, `git mv` the folder to
-   `docs/history/brainstorms/{topic}/`, set state `Status: harvested` (no index row to move: the folder is
+4. **Move.** Run `--gate=move`. When clean: delete `ops/` entirely, then move the folder to
+   `docs/history/brainstorms/{topic}/`: `git mv` when `git ls-files <folder>` lists anything,
+   plain `mv` when it lists nothing — `git mv` refuses a folder git has never tracked, and a
+   session is often never committed before its stop. Then set state `Status: harvested` (no index row to move: the folder is
    the record). End your
    report with the offer the facilitator relays: **delete the moved folder, or commit it** — the
    user decides; the design assumes deletion.