@nurix/etna 0.20.38 → 0.20.40

package/data/harnesses/etna/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nurix/etna",
-  "version": "0.20.38",
+  "version": "0.20.40",
   "description": "Bootstrap a project with a Nurix harness — writes the committed contract (CLAUDE.md, AGENTS.md, .claude/harness.json, settings.json, the mount hook) and mounts the harness itself, gitignored, from a bundled payload; sessions keep it current from the CDN.",
   "type": "module",
   "bin": {
@@ -46,5 +46,5 @@
     "agent",
     "plugin"
   ],
-  "etnaFingerprint": "666a16c2c2da"
+  "etnaFingerprint": "d4d71fdc192e"
 }