@nurix/etna 0.20.38 → 0.20.39

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (29) hide show
  1. package/data/harness-index.json +1 -1
  2. package/data/harnesses/code/agents/brainstorm.md +5 -3
  3. package/data/harnesses/code/codex/agents/brainstorm.toml +5 -3
  4. package/data/harnesses/code/harness.json +2 -2
  5. package/data/harnesses/code/skills/brainstorm/README.md +18 -45
  6. package/data/harnesses/code/skills/brainstorm/SKILL.md +105 -173
  7. package/data/harnesses/code/skills/brainstorm/references/doctrine.md +70 -141
  8. package/data/harnesses/code/skills/brainstorm/references/entry.md +70 -0
  9. package/data/harnesses/code/skills/brainstorm/references/harvest.md +85 -137
  10. package/data/harnesses/code/skills/brainstorm/references/session-schema.md +98 -135
  11. package/data/harnesses/delivery/agents/brainstorm.md +5 -3
  12. package/data/harnesses/delivery/codex/agents/brainstorm.toml +5 -3
  13. package/data/harnesses/delivery/harness.json +2 -2
  14. package/data/harnesses/delivery/skills/brainstorm/README.md +18 -45
  15. package/data/harnesses/delivery/skills/brainstorm/SKILL.md +105 -173
  16. package/data/harnesses/delivery/skills/brainstorm/references/doctrine.md +70 -141
  17. package/data/harnesses/delivery/skills/brainstorm/references/entry.md +70 -0
  18. package/data/harnesses/delivery/skills/brainstorm/references/harvest.md +85 -137
  19. package/data/harnesses/delivery/skills/brainstorm/references/session-schema.md +98 -135
  20. package/data/harnesses/etna/agents/brainstorm.md +5 -3
  21. package/data/harnesses/etna/codex/agents/brainstorm.toml +5 -3
  22. package/data/harnesses/etna/harness.json +2 -2
  23. package/data/harnesses/etna/skills/brainstorm/README.md +18 -45
  24. package/data/harnesses/etna/skills/brainstorm/SKILL.md +105 -173
  25. package/data/harnesses/etna/skills/brainstorm/references/doctrine.md +70 -141
  26. package/data/harnesses/etna/skills/brainstorm/references/entry.md +70 -0
  27. package/data/harnesses/etna/skills/brainstorm/references/harvest.md +85 -137
  28. package/data/harnesses/etna/skills/brainstorm/references/session-schema.md +98 -135
  29. package/package.json +2 -2
@@ -1,194 +1,157 @@
1
- # Session schema — the single format authority
1
+ # Session schema — the on-disk contract
2
2
 
3
- Load when: bootstrapping a session, writing any working-surface file, dispatching the twin, or
4
- interpreting detector output. The detector (`scripts/detector.mjs`) is the mechanical half of this
5
- contract: every rule below carrying a rule ID is machine-checked; everything else is the twin's
6
- semantic judgment.
3
+ 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.
7
4
 
8
- ## Folder layout
5
+ 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.
9
6
 
10
- An open session is `docs/research/{topic}-brainstorm/` (kebab-case topic slug):
7
+ ## Layout
11
8
 
12
- | Path | Holds | Writer |
13
- | --- | --- | --- |
14
- | `state.md` | anchor + aspect map | twin |
15
- | `thesis.md` | composed claim → argument → what changed | twin |
16
- | `forks.md` | open questions with close conditions | twin |
17
- | `ledger.md` | commitments | twin |
18
- | `basis/` | frozen entry material | facilitator, once, at intake |
19
- | `fragments/` | harvest-native fragments, drafted in destination format; created on first real content | twin |
20
- | `ops/` | the untracked capture layer, deleted at stop | — |
21
- | `ops/.gitignore` | `*` — `ops/` **never** enters git [BS-OPS-01/02] | facilitator |
22
- | `ops/capture.md` | the facilitator's raw append ledger | facilitator |
23
- | `ops/sync-log.md` | the paired twin-dispatch log | both (see below) |
24
- | `ops/manifest.md` | the harvest manifest | twin, in the stop pipeline |
25
-
26
- On a passed harvest the folder **moves** to `docs/history/brainstorms/{topic}/`, `ops/` deleted
27
- first. The move is the completion marker; the user then deletes or commits the folder. A folder
28
- under `docs/research/` is by definition unfinished.
29
-
30
- **Write protocol (one writer per file; the sync log is paired):** the facilitator bootstraps `ops/` at intake, appends to
31
- `ops/capture.md`, and writes the initial `basis/` copy plus the sync-log *dispatch* lines —
32
- **nothing else, ever**. The twin writes every other file, at gates. The user may hand-edit anything;
33
- the twin diffs each file against its own last compose before rewriting and folds foreign edits in
34
- as first-class user signal.
35
-
36
- ## state.md
9
+ ```
10
+ docs/research/{topic}-brainstorm/
11
+ ├── state.md twin
12
+ ├── thesis.md twin
13
+ ├── forks.md twin
14
+ ├── ledger.md twin
15
+ ├── fragments/{name}.md twin, created on first real content
16
+ ├── basis/ facilitator, at intake; frozen
17
+ └── ops/ untracked; deleted at the move
18
+ ├── .gitignore facilitator, at bootstrap: the single line *
19
+ ├── capture.md facilitator, every turn
20
+ ├── sync-log.md dispatch lines: facilitator · result lines: twin
21
+ └── manifest.md twin, at stop
22
+ ```
23
+
24
+ On a passing harvest the folder moves to `docs/history/brainstorms/{topic}/` without `ops/`, and `state.md` reads `Status: harvested`.
25
+
26
+ ## `state.md`
37
27
 
38
28
  ```markdown
39
29
  # State
40
30
 
41
- - Status: open | stopping | harvested
42
- - Posture: mid-probe on the sync-layer aspect, three forks open
31
+ - Status: open
32
+ - Posture: mid-probe on the persistence aspect, two forks open
43
33
  - Started: 2026-07-08
44
- - Sitting: single | multi
45
- - Last compose: 2026-07-08T14:30Z | never
34
+ - Sitting: single
35
+ - Last compose: 2026-07-08T14:30Z
46
36
 
47
37
  ## Aspect map
48
38
 
49
- - persistence — how session state survives restarts → F1, D3
39
+ - persistence — how cache state survives restarts → F1, D1
50
40
  - onboarding — the first-run experience → thesis
51
- - risks — failure modes and mitigations → none yet
41
+ - risks — failure modes and mitigations → F2, fragment:domain-model
52
42
  ```
53
43
 
54
- - `Status` moves **only** forward: `open → stopping → harvested` — the twin sets `stopping` when the
55
- stop pipeline begins and `harvested` at the move [BS-STATE-01].
56
- - The aspect map is derived per idea from the basis and edited by the user. Each aspect carries
57
- `→` refs to the content covering it: fork IDs (`F#`), ledger IDs (`D#`), `thesis`,
58
- `fragment:{name}`, or `none yet` (an open coverage gap — informational mid-session
59
- [BS-ASPECT-01], blocking at the manifest gate [BS-ASPECT-02]). Ref *presence* is the detector's
60
- half; whether the content actually covers the aspect is the twin's.
61
-
62
- ## thesis.md
44
+ | Field | Values |
45
+ | --- | --- |
46
+ | `Status` | `open` → `stopping` → `harvested`, forward only: the twin sets `stopping` when the stop pipeline begins and `harvested` at the move |
47
+ | `Posture` | one line a resuming reader can act on: where the conversation is and what is next; a parked session says so here |
48
+ | `Started` | ISO date |
49
+ | `Sitting` | `single` · `multi` |
50
+ | `Last compose` | the ISO datetime of the last thesis compose, equal to the thesis stamp; `never` before the first |
63
51
 
64
- ```markdown
65
- # {Topic} — thesis
52
+ 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`.
66
53
 
67
- Current as of: 2026-07-08T14:30Z
54
+ ## `thesis.md`
68
55
 
69
- ## Claim
70
- ## Argument
71
- ## What changed
72
- ```
56
+ A title, then `Current as of: <ISO datetime>`, then the sections `## Claim`, `## Argument`, `## What changed`, in that order.
73
57
 
74
- Composed prose, rewritten whole at every compose, **never** appended. The three sections and the
75
- stamp are mandatory [BS-THESIS-01]; the stamp must equal `state.md`'s `Last compose`
76
- [BS-COMPOSE-01]. At the manifest gate, `Last compose` must be later than the newest
77
- `ops/capture.md` entry — a compose over unsynced capture is stale [BS-COMPOSE-02].
78
-
79
- ## forks.md
58
+ ## `forks.md`
80
59
 
81
60
  ```markdown
82
- ## F3 — Should reads wait for a compose? [open]
61
+ ## F2 — What happens on catalog API timeout? [open]
83
62
 
84
- Full self-contained prose in the user's framing.
63
+ The cache can serve stale on timeout or propagate the error; the basis is silent on it.
85
64
 
86
- - Raised by: user | twin (S4) | probe | harvest
87
- - Closes when: a pick between wait-for-fresh and read-stale-with-warning
65
+ - Raised by: twin (S1)
66
+ - Closes when: an accepted failure behavior — stale-serve with a warning, or error propagation
88
67
  ```
89
68
 
90
- - IDs `F1, F2, …` unique, never reused [BS-FORK-01]. Status marker: `[open]` or
91
- `[parked → {destination}]`. Every fork carries `Closes when:` [BS-FORK-01].
92
- - `Raised by: twin (S#)` must cite a reconciled sync-log entry [BS-SYNC-02].
93
- - **The twin deletes a resolved fork's entry** — the resolving ledger entry's `Resolves:` field is
94
- the record. `forks.md` holds only open and parked forks; a ledger `Resolves: F3`
95
- coexisting with an open F3 is an inconsistency [BS-FORK-02]. Parked forks survive to the
96
- manifest, which must route each one [BS-MANIFEST-01].
97
- - The manifest gate requires zero `[open]` forks [BS-FORK-03].
69
+ 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.
98
70
 
99
- ## ledger.md
71
+ ## `ledger.md`
100
72
 
101
73
  ```markdown
102
- ## D4 — Sessions initialize in dump or interview
103
-
104
- - Decision: every session opens in dump or interview; probe and converge are mid-session moves.
105
- - Why: a first-time user cannot be asked to pick a posture they have no vocabulary for.
106
- Declined: free initial posture — observed cold-starts stall in probe; re-evaluate if
107
- session-replay evals show experienced users fighting the default.
108
- - How to apply: the facilitator's start calibration offers only the two entry moves.
109
- - Resolves: F2
74
+ ## D1 — Cache keys are per-tenant
75
+
76
+ - Decision: every cache key embeds the tenant id; no shared entries.
77
+ - Why: cross-tenant reads are a trust break, and memory cost is acceptable at current tenant
78
+ counts. Declined: shared keys with tenant checks at read time — a single missed check leaks
79
+ data; re-evaluate if memory pressure forces it.
80
+ - How to apply: the cache module's key builder prefixes the tenant slug.
81
+ - Resolves: F3
110
82
  ```
111
83
 
112
- - IDs `D1, D2, …` unique, append-only [BS-LEDGER-01]. `Decision`, `Why`, `How to apply` are
113
- mandatory; `Resolves:` when the commitment closes forks. Amendments and reversals are
114
- annotations plus a new entry ("Reversed by D9" on the old; D9 names what it reverses) — never a
115
- rewrite. Declined options live inside `Why` per [doctrine.md](doctrine.md).
116
-
117
- ## ops/capture.md
84
+ `Decision`, `Why` and `How to apply` are required and non-empty; `Resolves` is optional. Ids are unique and never reused.
118
85
 
119
- The facilitator's per-turn append. Lowest possible bar: raw, unpolished, everything
120
- session-relevant from *both* sides (user substance and facilitator substance — diagnoses, informed
121
- rejections, definitions, reasoning chains), including residue judged not worth pillar filing.
122
- Format:
86
+ ## `ops/capture.md`
123
87
 
124
88
  ```markdown
89
+ # Capture
90
+
125
91
  ---
126
- ### T14 · 2026-07-08T14:22Z
92
+ ### T2 · 2026-07-08T14:20Z
127
93
 
128
- <raw notes for this turn>
94
+ facilitator: flagged the trust concern on shared entries — a missed tenant check at read time is
95
+ a leak, not a bug. recommended per-tenant keys; user accepted (→ D1). residue: user mentioned a
96
+ "warm-on-deploy" idea in passing, not pursued.
129
97
  ```
130
98
 
131
- Turn IDs `T#` ascend, each with an ISO timestamp — the timestamp compose-freshness checks against
132
- [BS-COMPOSE-02]. **Never** distill here; distillation is the twin's.
133
-
134
- ## ops/sync-log.md
99
+ 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.
135
100
 
136
- Paired-written, one pair per twin dispatch:
101
+ ## `ops/sync-log.md`
137
102
 
138
103
  ```
139
- S4 | gate: on-demand | dispatched: 2026-07-08T14:25Z | scope: full reconcile + compose
140
- S4 → reconciled | 2026-07-08T14:29Z | 4 edits · 2 new forks · 6 open · untouched: risks
104
+ S1 | gate: start | dispatched: 2026-07-08T14:05Z | scope: bootstrap reconcile
105
+ S1 → reconciled | 2026-07-08T14:08Z | 2 edits · 1 new fork · 2 open · untouched: risks
141
106
  ```
142
107
 
143
- The **facilitator** writes the dispatch line as it dispatches; the **twin** appends the result
144
- line (`reconciled` or `failed`) on return — **never** one author for both sides. Every dispatch
145
- line must acquire a result line; only the newest entry may be unpaired (in flight) [BS-SYNC-01].
146
- A `failed` result is surfaced to the user at the next turn break and re-run at the next gate.
108
+ 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.
147
109
 
148
- ## ops/manifest.md
149
-
150
- Created by the stop pipeline; gates the harvest apply:
110
+ ## `ops/manifest.md`
151
111
 
152
112
  ```markdown
153
113
  # Harvest manifest — {topic}
154
114
 
155
115
  Round: 1
156
- Status: proposed | approved | applied
116
+ Status: proposed
157
117
 
158
118
  | # | What | Source | Destination | Action |
159
119
  |---|------|--------|-------------|--------|
160
- | 1 | consolidated source of truth | thesis + fragments + ledger | docs/features/{x}.md | create |
161
- | 2 | parked fork F7 | forks.md | docs/architecture/open-questions.md | append |
120
+ | 1 | consolidated source of truth | thesis + ledger | docs/features/widget-cache.md | create |
121
+ | 3 | parked fork F2 | forks.md | docs/architecture/open-questions.md | append |
162
122
 
163
123
  ## Uselessness test
164
124
 
165
- - Result: pass | fail
166
- - Cold-reader allowed paths: <the destination docs above>
167
- - Gaps: none | <named gaps → next Round>
125
+ - Result: pass
126
+ - Cold-reader allowed paths: docs/features/widget-cache.md, docs/architecture/open-questions.md
127
+ - Gaps: none
168
128
  ```
169
129
 
170
- Every parked fork and every fragment must have a row [BS-MANIFEST-01]. `Status: approved` is set
171
- only after the user approves; gap fixes re-enter as a new `Round` with the same approval
172
- requirement. After apply, no destination doc may link into the session folder [BS-HARVEST-01];
173
- the move to history requires a recorded passing uselessness test [BS-USELESS-01].
174
-
175
- ## Detector
130
+ `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`.
176
131
 
177
- `node scripts/detector.mjs <session-folder> [--gate=session|manifest|move] [--json]`
132
+ ## The detector
178
133
 
179
- - `session` (default) — the always-on integrity rules; run at any gate.
180
- - `manifest` — adds the convergence gates (zero open forks, full aspect coverage, fresh compose);
181
- the twin may not construct a manifest while any of these fail.
182
- - `move` — adds the post-apply gates (manifest applied, uselessness pass recorded, no links into
183
- scaffolding); the folder may not move while any fail.
134
+ `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.
184
135
 
185
- | Exit | Meaning |
186
- | --- | --- |
187
- | `0` | clean |
188
- | `1` | violations, listed with rule IDs |
189
- | `2` | unusable input |
190
-
191
- A run always prints output — per-rule lines plus a `clean`/`failing` summary, or a usage/error
192
- message. **Exit 0 with empty output means the detector never executed** — a failure, **never** a
193
- pass. Rules degrade gracefully: with no git context, `BS-OPS-02` reports `skipped` and never blocks.
194
- Rule IDs are stable — the twin, the evals, and the maintenance census key on them.
136
+ | Rule | Gate | Fails when |
137
+ | --- | --- | --- |
138
+ | `BS-STATE-01` | session | `state.md` missing, or a field absent or invalid |
139
+ | `BS-STATE-02` | session | no `## Aspect map`, or no parseable aspect |
140
+ | `BS-ASPECT-01` | session | an aspect ref names no such fork, decision or fragment |
141
+ | `BS-THESIS-01` | session | the thesis lacks its stamp or a mandated section |
142
+ | `BS-COMPOSE-01` | session | the thesis stamp differs from `Last compose` |
143
+ | `BS-FORK-01` | session | duplicate fork id, no `Closes when:`, or a park without destination |
144
+ | `BS-FORK-02` | session | a decision resolves a fork still open |
145
+ | `BS-LEDGER-01` | session | duplicate decision id, or Decision, Why or How to apply empty |
146
+ | `BS-OPS-01` | session | `ops/.gitignore` missing or not `*` |
147
+ | `BS-OPS-02` | session | any `ops/` file tracked by git (skipped outside git) |
148
+ | `BS-SYNC-01` | session | a dispatch other than the newest has no result line |
149
+ | `BS-SYNC-02` | session | a `twin (S<n>)` attribution cites a sync that never reconciled |
150
+ | `BS-ASPECT-02` | manifest | an aspect has no content (`none yet`) |
151
+ | `BS-COMPOSE-02` | manifest | the newest capture entry is newer than the last compose |
152
+ | `BS-FORK-03` | manifest | any fork is open |
153
+ | `BS-MANIFEST-01` | manifest | a parked fork or a fragment has no manifest row |
154
+ | `BS-HARVEST-01` | move | a destination is missing, or links into the session folder |
155
+ | `BS-USELESS-01` | move | no passing uselessness test with `Gaps: none`, or the manifest is not `applied` |
156
+
157
+ 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".
@@ -28,8 +28,9 @@ as a failed gate and report it, never as a pass.
28
28
  ## The write protocol you enforce
29
29
 
30
30
  One writer per file. You write `state.md`, `thesis.md`, `forks.md`, `ledger.md`, `fragments/`,
31
- manifest, and your own sync-log **result** lines. You never write `ops/capture.md` (the
32
- facilitator's) or sync-log dispatch lines. The user may hand-edit anything: before rewriting any
31
+ manifest, and your own sync-log **result** lines. You never write the facilitator's files — the
32
+ folder, `ops/` and `ops/.gitignore` at bootstrap, `basis/` at intake, `ops/capture.md` — or
33
+ sync-log dispatch lines. The user may hand-edit anything: before rewriting any
33
34
  file, read its current state in full and treat content you did not write as **first-class user
34
35
  signal — fold it forward, never clobber it**. A hand-edit that contradicts the ledger is a design
35
36
  question: file a fork, don't "fix" the file.
@@ -116,7 +117,8 @@ Stop is facilitator-orchestrated because approval belongs to the user; you execu
116
117
  what applied and stop — the folder stays visibly unfinished and the user restarts; never
117
118
  resume silently from a half-applied state.
118
119
  3. **Uselessness test.** Spawn a **fresh, context-free cold reader** — an independent subagent
119
- that inherits none of this session's context — whose prompt contains only the allowed-path list
120
+ on the standard tier (`model: sonnet`, named on the dispatch so it never inherits yours) that
121
+ inherits none of this session's context — whose prompt contains only the allowed-path list
120
122
  (the manifest's destinations — never the session folder) and the instruction to reconstruct the
121
123
  design: thesis, commitments, reasoning, declined branches. Grade its reconstruction against the
122
124
  ledger and thesis. Gaps → record them in the manifest (`Result: fail`, named gaps), and the fixes
@@ -26,8 +26,9 @@ as a failed gate and report it, never as a pass.
26
26
  ## The write protocol you enforce
27
27
 
28
28
  One writer per file. You write `state.md`, `thesis.md`, `forks.md`, `ledger.md`, `fragments/`,
29
- manifest, and your own sync-log **result** lines. You never write `ops/capture.md` (the
30
- facilitator's) or sync-log dispatch lines. The user may hand-edit anything: before rewriting any
29
+ manifest, and your own sync-log **result** lines. You never write the facilitator's files — the
30
+ folder, `ops/` and `ops/.gitignore` at bootstrap, `basis/` at intake, `ops/capture.md` — or
31
+ sync-log dispatch lines. The user may hand-edit anything: before rewriting any
31
32
  file, read its current state in full and treat content you did not write as **first-class user
32
33
  signal — fold it forward, never clobber it**. A hand-edit that contradicts the ledger is a design
33
34
  question: file a fork, don't "fix" the file.
@@ -114,7 +115,8 @@ Stop is facilitator-orchestrated because approval belongs to the user; you execu
114
115
  what applied and stop — the folder stays visibly unfinished and the user restarts; never
115
116
  resume silently from a half-applied state.
116
117
  3. **Uselessness test.** Spawn a **fresh, context-free cold reader** — an independent subagent
117
- that inherits none of this session's context — whose prompt contains only the allowed-path list
118
+ on the standard tier (named on the dispatch so it never inherits yours) that
119
+ inherits none of this session's context — whose prompt contains only the allowed-path list
118
120
  (the manifest's destinations — never the session folder) and the instruction to reconstruct the
119
121
  design: thesis, commitments, reasoning, declined branches. Grade its reconstruction against the
120
122
  ledger and thesis. Gaps → record them in the manifest (`Result: fail`, named gaps), and the fixes
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "harness": "delivery",
3
3
  "name": "delivery",
4
- "version": "0.2.43",
4
+ "version": "0.2.44",
5
5
  "files": [
6
6
  ".prettierignore",
7
7
  ".prettierrc.json",
@@ -14,5 +14,5 @@
14
14
  "origin": "https://cdn.nustack.io",
15
15
  "track": "latest"
16
16
  },
17
- "digest": "be27590dbe5b"
17
+ "digest": "4a50adb2ac40"
18
18
  }
@@ -1,54 +1,27 @@
1
- # Brainstorm — process, not archive
1
+ # Brainstorm
2
2
 
3
- A Claude Code skill that is a **thinking partner for designing large-scale software changes**.
4
- The session's product is the repo's living documentation: the conversation helps the user think
5
- correctly, the record stays readable at any pause, and the session ends with a harvest so
6
- complete that the session folder is useless — it moves to history and the user deletes or
7
- commits it.
3
+ A thinking partner for a large-scale software change. The session's product is the repository's living documentation: the conversation helps the user think correctly, the working surface reads well at any pause, and the stop pipeline harvests the session so completely that its folder is redundant. The folder then moves to history, and the user deletes or commits it.
8
4
 
9
- > Spec (single source of truth): `docs/skills/brainstorm/` in the etna repo. The etna
10
- > copy of this skill (`skills/brainstorm/`) is canonical; the user-level path
11
- > `~/.claude/skills/brainstorm/` is a symlink to it.
5
+ The design, its reasons and its evidence live in `docs/skills/brainstorm/` in the etna repo.
12
6
 
13
- ## The architecture — one capability, two seats
14
-
15
- Prose obligations decay in the conversing seat: an audit of real sessions finds the same rules
16
- dying in every one, the successful ones included. So the capability is split:
7
+ ## One capability, two seats
17
8
 
18
9
  | Seat | Component | Owns |
19
10
  | --- | --- | --- |
20
- | Conversation (main loop) | `SKILL.md` — the facilitator | The dialogue, the basis gate, the moves, one write: appending everything to `ops/capture.md` |
21
- | 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 |
22
- | Integrity (script) | `scripts/detector.mjs` | Mechanical checks with stable rule IDs; blocks the manifest and the move while gates fail |
23
- | Quality (authoring-time) | `evals/` (never ships) | Session-replay scenarios, the two-agent audit, contrastive facilitation |
24
-
25
- Every twin dispatch is paired-logged in `ops/sync-log.md` — the facilitator writes the dispatch
26
- line, the twin writes the result — so reconciliation is observable, never asserted.
27
-
28
- ## The session lifecycle
29
-
30
- - **`/brainstorm start`**
31
- 1. Basis gate — a document, a prior session folder in any format, or a brain dump.
32
- 2. Bootstrap `docs/research/{topic}-brainstorm/` — `ops/` untracked; the twin writes the surface.
33
- 3. Converse — dump, interview, probe, blindspot, converge — steerable in plain language.
34
- 4. "Let me read" anytime — compose on demand, read the thesis, come back.
35
- - **`/brainstorm stop`**
36
- 1. Converge → manifest → **one** user approval → apply → uselessness test.
37
- 2. The folder moves to `docs/history/brainstorms/{topic}/` — the completion marker.
38
- 3. The user decides: delete or commit.
39
-
40
- The working surface: `thesis.md` (claim → argument → what changed, recomposed whole, stamped),
41
- `forks.md` (open questions with close conditions — the only convergence currency), `ledger.md`
42
- (commitments: Decision / Why / How to apply / Resolves, declined options inline with re-evaluate
43
- conditions), `state.md` (anchor + the aspect map), `basis/`, `fragments/` (harvest-native,
44
- drafted in destination format), and untracked `ops/` (raw capture + sync log; deleted at stop).
11
+ | Conversation (main loop) | `SKILL.md`, the facilitator | the dialogue, the basis gate, the moves, the per-turn capture into `ops/capture.md`, the sync-log dispatch lines |
12
+ | Paper (dispatched agent) | the `brainstorm` agent, the twin, pinned to a strong tier | every working-surface file: distillation, the whole-thesis recompose, the semantic audits, the harvest |
13
+ | Integrity (script) | `scripts/detector.mjs` | mechanical checks with stable rule ids, blocking the manifest and the move while they fail |
14
+ | Quality (authoring time) | `evals/`, never shipped | activation and behaviour cases, session-replay scenarios, the two-agent audit |
45
15
 
46
16
  ## Files
47
17
 
48
- - `SKILL.md` — the facilitator hub
49
- - `references/doctrine.md` — thesis / forces / forks / commitments / consequences epistemics
50
- - `references/session-schema.md` — the single format authority (what the detector enforces)
51
- - `references/harvest.md` — the stop pipeline and routing map
52
- - `scripts/detector.mjs` — the rule registry (`node detector.mjs <folder> [--gate=…] [--json]`)
53
- - `scripts/fixtures/` — contrastive fixtures + runner (authoring-time; never ships)
54
- - `evals/` — session-replay + audit harness (authoring-time; never ships)
18
+ | Path | Holds |
19
+ | --- | --- |
20
+ | `SKILL.md` | the facilitator hub: re-anchor, commands, write ownership, capture, moves, dispatch, questions, promises |
21
+ | `references/entry.md` | `/brainstorm start`: lookup, basis gate, bootstrap, intake, aspect map, orientation |
22
+ | `references/doctrine.md` | the epistemics of the surface, shared by both seats, with the capture-and-converge field lessons |
23
+ | `references/session-schema.md` | the on-disk contract the detector parses, and its rule table |
24
+ | `references/harvest.md` | `/brainstorm stop`: the pipeline, the routing map, the apply field lessons |
25
+ | `scripts/detector.mjs` | the rule registry: `node detector.mjs <folder> [--gate=session\|manifest\|move] [--json]` |
26
+ | `scripts/fixtures/` | contrastive fixtures and their runner, `node scripts/fixtures/run-fixtures.mjs` |
27
+ | `evals/` | `activation.json`, `evals.json`, the replay driver and its scenarios |