@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.
- package/data/harness-index.json +1 -1
- package/data/harnesses/code/agents/brainstorm.md +5 -3
- package/data/harnesses/code/codex/agents/brainstorm.toml +5 -3
- package/data/harnesses/code/harness.json +2 -2
- package/data/harnesses/code/skills/brainstorm/README.md +18 -45
- package/data/harnesses/code/skills/brainstorm/SKILL.md +105 -173
- package/data/harnesses/code/skills/brainstorm/references/doctrine.md +70 -141
- package/data/harnesses/code/skills/brainstorm/references/entry.md +70 -0
- package/data/harnesses/code/skills/brainstorm/references/harvest.md +85 -137
- package/data/harnesses/code/skills/brainstorm/references/session-schema.md +98 -135
- package/data/harnesses/delivery/agents/brainstorm.md +5 -3
- package/data/harnesses/delivery/codex/agents/brainstorm.toml +5 -3
- package/data/harnesses/delivery/harness.json +2 -2
- package/data/harnesses/delivery/skills/brainstorm/README.md +18 -45
- package/data/harnesses/delivery/skills/brainstorm/SKILL.md +105 -173
- package/data/harnesses/delivery/skills/brainstorm/references/doctrine.md +70 -141
- package/data/harnesses/delivery/skills/brainstorm/references/entry.md +70 -0
- package/data/harnesses/delivery/skills/brainstorm/references/harvest.md +85 -137
- package/data/harnesses/delivery/skills/brainstorm/references/session-schema.md +98 -135
- package/data/harnesses/etna/agents/brainstorm.md +5 -3
- package/data/harnesses/etna/codex/agents/brainstorm.toml +5 -3
- package/data/harnesses/etna/harness.json +2 -2
- package/data/harnesses/etna/skills/brainstorm/README.md +18 -45
- package/data/harnesses/etna/skills/brainstorm/SKILL.md +105 -173
- package/data/harnesses/etna/skills/brainstorm/references/doctrine.md +70 -141
- package/data/harnesses/etna/skills/brainstorm/references/entry.md +70 -0
- package/data/harnesses/etna/skills/brainstorm/references/harvest.md +85 -137
- package/data/harnesses/etna/skills/brainstorm/references/session-schema.md +98 -135
- package/package.json +2 -2
|
@@ -1,194 +1,157 @@
|
|
|
1
|
-
# Session schema — the
|
|
1
|
+
# Session schema — the on-disk contract
|
|
2
2
|
|
|
3
|
-
Load when:
|
|
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
|
-
|
|
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
|
-
|
|
7
|
+
## Layout
|
|
11
8
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
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
|
|
42
|
-
- Posture: mid-probe on the
|
|
31
|
+
- Status: open
|
|
32
|
+
- Posture: mid-probe on the persistence aspect, two forks open
|
|
43
33
|
- Started: 2026-07-08
|
|
44
|
-
- Sitting: single
|
|
45
|
-
- Last compose: 2026-07-08T14:30Z
|
|
34
|
+
- Sitting: single
|
|
35
|
+
- Last compose: 2026-07-08T14:30Z
|
|
46
36
|
|
|
47
37
|
## Aspect map
|
|
48
38
|
|
|
49
|
-
- persistence — how
|
|
39
|
+
- persistence — how cache state survives restarts → F1, D1
|
|
50
40
|
- onboarding — the first-run experience → thesis
|
|
51
|
-
- risks — failure modes and mitigations →
|
|
41
|
+
- risks — failure modes and mitigations → F2, fragment:domain-model
|
|
52
42
|
```
|
|
53
43
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
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
|
-
|
|
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
|
-
|
|
54
|
+
## `thesis.md`
|
|
68
55
|
|
|
69
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
61
|
+
## F2 — What happens on catalog API timeout? [open]
|
|
83
62
|
|
|
84
|
-
|
|
63
|
+
The cache can serve stale on timeout or propagate the error; the basis is silent on it.
|
|
85
64
|
|
|
86
|
-
- Raised by:
|
|
87
|
-
- Closes when:
|
|
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
|
-
|
|
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
|
-
##
|
|
103
|
-
|
|
104
|
-
- Decision: every
|
|
105
|
-
- Why:
|
|
106
|
-
Declined:
|
|
107
|
-
|
|
108
|
-
- How to apply: the
|
|
109
|
-
- Resolves:
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
###
|
|
92
|
+
### T2 · 2026-07-08T14:20Z
|
|
127
93
|
|
|
128
|
-
|
|
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
|
-
|
|
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
|
-
|
|
101
|
+
## `ops/sync-log.md`
|
|
137
102
|
|
|
138
103
|
```
|
|
139
|
-
|
|
140
|
-
|
|
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
|
|
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
|
|
116
|
+
Status: proposed
|
|
157
117
|
|
|
158
118
|
| # | What | Source | Destination | Action |
|
|
159
119
|
|---|------|--------|-------------|--------|
|
|
160
|
-
| 1 | consolidated source of truth | thesis +
|
|
161
|
-
|
|
|
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
|
|
166
|
-
- Cold-reader allowed paths:
|
|
167
|
-
- Gaps: none
|
|
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
|
|
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
|
-
|
|
132
|
+
## The detector
|
|
178
133
|
|
|
179
|
-
-
|
|
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
|
-
|
|
|
186
|
-
| --- | --- |
|
|
187
|
-
| `
|
|
188
|
-
| `
|
|
189
|
-
| `
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
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
|
|
32
|
-
|
|
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
|
-
|
|
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
|
|
30
|
-
|
|
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
|
-
|
|
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.
|
|
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": "
|
|
17
|
+
"digest": "4a50adb2ac40"
|
|
18
18
|
}
|
|
@@ -1,54 +1,27 @@
|
|
|
1
|
-
# Brainstorm
|
|
1
|
+
# Brainstorm
|
|
2
2
|
|
|
3
|
-
A
|
|
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
|
-
|
|
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
|
-
##
|
|
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
|
|
21
|
-
| Paper (dispatched agent) | `
|
|
22
|
-
| Integrity (script) | `scripts/detector.mjs` |
|
|
23
|
-
| Quality (authoring
|
|
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
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
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 |
|