@nurix/etna 0.20.35 → 0.20.37

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

@@ -6,27 +6,26 @@ 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).
+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 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.
+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 |
 | --- | --- | --- |
@@ -36,7 +35,7 @@ contract, not a blank page.
 | **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 |
+| **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:
 
@@ -47,13 +46,12 @@ contract, not a blank page.
 
 **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).
+**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 may never be deleted
-into a knowledge loss.
+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
 
@@ -68,49 +66,53 @@ The deletion-safety gate: after the apply, the post-harvest living docs alone mu
 - **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.
+  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: 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
+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 residual is accepted by design.
+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.
 
 ## Field lessons — apply
 
-Measured on live harvests; each is the rule, distilled.
+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/`, both index rows,
-  `check-links` clean. And **distil the process record into `state.md` before the move** — the
-  sync log dies with `ops/`, and a ten-line dispatch summary is what separates a record that shows
-  its workings from one that asserts its commitments from nowhere.
+  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.
-- **Audit the *other* decision records for impact at manifest time** — the manifest routes
-  through the docs the commitments name and will not think of the neighbours. The test is
-  commitment-level, not textual (grep finds nothing); read each AD's Decision and Open Questions
-  against the new commitments, and report the unimpacted verdicts with evidence too.
-- **A manifest enumerates sites; the file you open contains more of them.** 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.
-  Say which you did, per row, in the application record.
+- **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
+- **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.
@@ -135,14 +137,6 @@ Measured on live harvests; each is the rule, distilled.
   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.
-- **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 grep finds
-  nothing because the ledger never names the others; report the unimpacted verdicts with their
-  evidence too.
-- **A manifest row names one site; the file you open holds more.** Fix the same-doctrine sites
-  inside a file the manifest already opens, 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.
 - **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.

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

@@ -2,35 +2,36 @@
 
 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.
+contract: every rule below carrying 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
+An open session is `docs/research/{topic}-brainstorm/` (kebab-case topic slug):
+
+| 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 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.
+**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
 
@@ -50,8 +51,8 @@ own last compose before rewriting and folds foreign edits as first-class user si
 - 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]
+- `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
@@ -70,8 +71,8 @@ Current as of: 2026-07-08T14:30Z
 ## 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`
+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].
 
@@ -89,8 +90,8 @@ Full self-contained prose in the user's framing.
 - 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`
+- **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].
@@ -115,10 +116,10 @@ Full self-contained prose in the user's framing.
 
 ## 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:
+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:
 
 ```markdown
 ---
@@ -127,8 +128,8 @@ worth pillar filing. Format:
 <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.
+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
 
@@ -140,7 +141,7 @@ S4 → reconciled | 2026-07-08T14:29Z | 4 edits · 2 new forks · 6 open · unto
 ```
 
 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 (`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.
 
@@ -181,8 +182,13 @@ the move to history requires a recorded passing uselessness test [BS-USELESS-01]
 - `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. 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** and is a failure, never a pass. 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.
+| 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.

package/data/harnesses/delivery/skills/cost-report/SKILL.md

@@ -5,20 +5,20 @@ description: Use when the organization wants to see or tune spend - "what are we
 
 # Cost Report — aggregate, flag, propose
 
-The spend policy's audit surface. Reads only in-repo records — escalation entries and the changelog; it queries no billing API and parses no session logs.
+The spend policy's audit surface. It reads only in-repo records — the changelog and the escalation entries in it. **Never** query a billing API or parse session logs; a question only those could answer (raw token counts, per-session spend) is out of scope — say so rather than estimate.
 
 ## Procedure
 
-1. **Collect** every entry in `docs/history/changelog/` carrying `Class: escalation` since the last report (the `escalate` skill owns that format — match its keyword, don't restate its shape).
-2. **Aggregate by routing row**: per task type — escalations up, demotions passed, one-off vs. standing promotions.
+1. **Collect** every entry in `docs/history/changelog/` carrying `Class: escalation` since the last report, plus the tier usage the other entries record. Match on the keyword only — the `escalate` skill owns the entry's shape.
+2. **Aggregate by routing row**: per task type, count escalations up, demotions passed, and one-off vs. standing promotions.
 3. **Flag drift**:
-   - A row with repeated upward escalations ⇒ the tier is under-provisioned; propose moving the row up.
-   - A row whose demotion experiments keep passing ⇒ over-provisioned; propose moving it down.
-   - Frontier dispatches with no matching row or escalation entry ⇒ a routing-guardrail violation to surface, not to normalize.
-4. **Report in chat**: a short table — row · tier · escalations · demotions · proposal — followed by the proposed routing-table edits. **Propose, never apply**: the routing table is `CLAUDE.md` policy and moves by its own reviewed edit; standing proposals also land in `docs/history/backlog.md`.
+   - Repeated upward escalations on a row ⇒ the tier is under-provisioned; propose moving the row up.
+   - Demotion experiments that keep passing on a row ⇒ over-provisioned; propose moving it down.
+   - A frontier dispatch with no matching row or escalation entry ⇒ a routing-guardrail violation. Surface it; never fold it into the row's normal usage.
+4. **Report in chat**: a table — row · tier · escalations · demotions · proposal — then the proposed routing-table edits. Append each standing proposal to `docs/history/backlog.md`.
 
 ## Rules
 
-- **Evidence or silence** — every proposal cites its entries by filename; no vibes-based rebalancing.
-- **This skill measures the policy, not the people.** Escalation counts tune the table; they are never framed as individual performance data.
-- Tier-usage questions the changelog cannot answer (raw token counts, per-session spend) are out of scope by design — recorded as a deferral in the harness doc, re-evaluated when a consumer actually needs them.
+- **Propose, never apply.** The routing table is `CLAUDE.md` policy and moves only by its own reviewed edit.
+- **Evidence or silence** — every proposal cites its entries by filename.
+- **Measure the policy, never the people.** Escalation counts tune the table; never frame them as individual performance data.