@nurix/etna 0.19.33 → 0.19.35

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

@@ -0,0 +1,86 @@
+# 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.

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

@@ -0,0 +1,186 @@
+# Session schema — the single format authority
+
+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 that carries a rule ID is machine-checked; everything else is the
+twin's semantic judgment.
+
+## Folder layout
+
+```
+docs/research/{topic}-brainstorm/     ← open session (kebab-case topic slug)
+├── state.md                          ← anchor + aspect map (twin-written)
+├── thesis.md                         ← composed claim → argument → what changed (twin-written)
+├── forks.md                          ← open questions with close conditions (twin-written)
+├── ledger.md                         ← commitments (twin-written)
+├── basis/                            ← frozen entry material (facilitator-written once, at intake)
+├── fragments/                        ← harvest-native fragments (twin-written; materialize on
+│                                        first real content, drafted in destination format)
+└── ops/                              ← untracked capture layer (deleted at stop)
+    ├── .gitignore                    ← contains `*` — ops/ never enters git      [BS-OPS-01/02]
+    ├── capture.md                    ← facilitator's raw append ledger (its ONLY write)
+    ├── sync-log.md                   ← paired twin-dispatch log
+    └── manifest.md                   ← harvest manifest (created by 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 it. A folder still
+under `docs/research/` is by definition unfinished.
+
+**Write protocol (one writer per file):** the facilitator 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 as first-class user signal.
+
+## state.md
+
+```markdown
+# State
+
+- Status: open | stopping | harvested
+- Posture: mid-probe on the sync-layer aspect, three forks open
+- Started: 2026-07-08
+- Sitting: single | multi
+- Last compose: 2026-07-08T14:30Z | never
+
+## Aspect map
+
+- persistence — how session state survives restarts → F1, D3
+- onboarding — the first-run experience → thesis
+- risks — failure modes and mitigations → none yet
+```
+
+- `Status` transitions only forward: `open → stopping → harvested` (the twin flips `stopping` when
+  the stop pipeline begins, `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
+
+```markdown
+# {Topic} — thesis
+
+Current as of: 2026-07-08T14:30Z
+
+## Claim
+## Argument
+## What changed
+```
+
+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
+
+```markdown
+## F3 — Should reads wait for a compose? [open]
+
+Full self-contained prose in the user's framing.
+
+- Raised by: user | twin (S4) | probe | harvest
+- Closes when: a pick between wait-for-fresh and read-stale-with-warning
+```
+
+- 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].
+- **A resolved fork's entry is deleted** by the twin — 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].
+
+## 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
+```
+
+- 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
+
+The facilitator's per-turn append — its one write duty. 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:
+
+```markdown
+---
+### T14 · 2026-07-08T14:22Z
+
+<raw notes for this turn>
+```
+
+Turn IDs `T#` ascending with an ISO timestamp — the timestamp is what compose-freshness checks
+against [BS-COMPOSE-02]. Never distill here; distillation is the twin's job.
+
+## ops/sync-log.md
+
+Paired-written, one pair per twin dispatch:
+
+```
+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
+```
+
+The **facilitator** writes the dispatch line as it dispatches; the **twin** appends the result
+line (`reconciled` or `failed`) on return — no single author holds 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.
+
+## ops/manifest.md
+
+Created by the stop pipeline; gates the harvest apply:
+
+```markdown
+# Harvest manifest — {topic}
+
+Round: 1
+Status: proposed | approved | applied
+
+| # | 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 |
+
+## Uselessness test
+
+- Result: pass | fail
+- Cold-reader allowed paths: <the destination docs above>
+- Gaps: none | <named gaps → next Round>
+```
+
+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
+
+`node scripts/detector.mjs <session-folder> [--gate=session|manifest|move] [--json]`
+
+- `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.
+
+Exit code 0 = clean, 1 = violations (listed with rule IDs), 2 = unusable input. Rules degrade
+gracefully: no git context ⇒ BS-OPS-02 reports `skipped`, never blocks. Rule IDs are stable —
+consumers (the twin, the evals, the maintenance census) key on them.