@nurix/etna 0.19.21 → 0.19.23

package/README.md

@@ -25,19 +25,20 @@ After this completes:
 ```
 your-project/
 ├── CLAUDE.md              ← harness policy (non-git repo: existing file → CLAUDE.md.bak.<ISO>)
+├── AGENTS.md              ← Codex: CLAUDE.md byte-for-byte + a generated Codex runtime adapter
 ├── .prettierrc.json       ← markdown formatting (proseWrap: never)
 ├── .prettierignore
 ├── .vscode/settings.json  ← editor settings (markdown formatter on save)
 └── .claude/
-    ├── skills/            ← documentation, boundary, brainstorm, workflow-mapper
+    ├── skills/            ← documentation, boundary, brainstorm, workflow-mapper, design
     ├── agents/            ← lld-mode, brainstorm, maintenance, change-review, performance-review
-    ├── rules/             ← general.md, frontend.md, express.md, nomenclature.md, database.md, typescript.md, testing.md
+    ├── rules/             ← general.md, frontend.md, express.md, nomenclature.md, database.md, testing.md, pnpm.md
     ├── hooks/             ← generate-ownership-index (SessionStart)
     ├── settings.json      ← the hook is deep-merged in here (your existing keys preserved)
-    └── harness.json       ← {version, digest} — the installed-harness sentinel
+    └── harness.json       ← {version, digest, owned} — the installed-harness sentinel
 ```
 
-That's the entire footprint. Nothing is written outside the project. No marketplace registration, no `enabledPlugins` entry, no global cache dependency — Claude Code picks up the project-scoped agents/skills/rules on its next session start, and the hooks wire in through `.claude/settings.json`.
+Alongside the Claude tree, the installer projects the **Codex** artifacts so the repo also works under OpenAI Codex: `AGENTS.md` (above), `.agents/skills/` (a mirror of `.claude/skills/`, Codex's skill-scan path), and `.codex/agents/*.toml` + `.codex/hooks.json` (its subagents and SessionStart hook). Nothing is written outside the project. No marketplace registration, no `enabledPlugins` entry, no global cache dependency — Claude Code picks up the project-scoped agents/skills/rules on its next session start (and Codex reads `AGENTS.md` + `.agents/` + `.codex/`), and the hooks wire in through `.claude/settings.json`.
 
 Re-run `npx --yes @nurix/etna --name=code` anytime to refresh the harness content with what the latest published package ships. Existing same-named files are overwritten; files you've added that aren't part of the harness are left alone. In a git repo the previous `CLAUDE.md` is overwritten in place (recover it with `git checkout CLAUDE.md`); outside a git repo it's backed up to `CLAUDE.md.bak.<ISO-timestamp>`. Because the new `harness.json` carries the installed `{version, digest}`, a re-run whose **major** version is ahead of your repo's stamped `harness-version` is what the reconcile (below) detects as a structural upgrade.
 
@@ -95,7 +96,7 @@ agents: [brainstorm, change-review, lld-mode, maintenance, performance-review]
 
 - **Owned, by location** — hooks, scripts (and any unlisted, harness-specific agents) live inside the harness folder (`harness/<name>/{agents,hooks,scripts}/`). No list — membership is presence in the folder, exactly how a Claude Code plugin ships them. Shared governance agents are listed instead (above) and resolved from the `agents/` catalog, local-first; a harness can still drop its own copy beside it to override one by name.
 
-`scripts/build-data.js` (run by `prepack`) resolves the listed skills/rules/agents from the catalogs (local-first), copies any unlisted harness-owned agents plus the harness's `hooks/` and `scripts/` wholesale into `data/harnesses/<folder>/`; a listed skill/rule/agent that doesn't exist is a hard error. The marketplace channel (`.github/scripts/publish.mjs`) reads the same harness folder, so both channels resolve identical membership — and both ship the harness's hooks and scripts. The installer (`bin/etna.js`) reads from the bundle at install time; no GitHub fetch at runtime.
+`scripts/build-data.js` (run by `prepack`) resolves the listed skills/rules/agents from the catalogs (local-first), copies any unlisted harness-owned agents plus the harness's `hooks/` and `scripts/` wholesale into `data/harnesses/<folder>/`; a listed skill/rule/agent that doesn't exist is a hard error. The marketplace channel (`.github/scripts/publish.mjs`) reads the same harness folder and resolves the listed skills/rules/agents the same local-first way — but the two channels' **footprints differ**: the marketplace plugin carries no root policy, and its Codex surface is skills + hooks only (Codex custom agents ship through this CLI). The installer (`bin/etna.js`) reads from the bundle at install time; no GitHub fetch at runtime.
 
 ## Building / contributing
 

package/data/harness-index.json

@@ -1,5 +1,5 @@
 {
-    "fingerprint": "2329fc4f3594",
+    "fingerprint": "5a7e414ba0b5",
     "harnesses": {
         "code": {
             "plugin": "code",

package/data/harnesses/code/CLAUDE.md

@@ -88,6 +88,16 @@ When recording a learning, ask: _is this true of this project, or true of this u
 
 ---
 
+## Refinement Ledger
+
+A commit marks the user's behavioral verification of the work, and the committing session is the last holder of the refinement context that produced it — asks, iterations, rejections, skill outcomes, discoveries. That context is captured at commit time and distilled on demand:
+
+- **Every non-mechanical commit appends one ledger block** to `docs/history/ledger/YYYY-MM.md`, staged inside the commit it describes — whatever tool or session performs the commit. Block format, required fields, and the closed exemption list are the `documentation` skill's `templates/refinement-ledger.md`; the failure fields (rejected attempts, overridden skill output) and verbatim taste quotes are required, not optional — the ledger's value concentrates there.
+- **Append-only journal, never a truth doc** — blocks are immutable once committed; a correction is a new block. The ledger is never cleaned up or reconciled, and doc-health passes skip it by genre.
+- **Distillation is the `retro` agent** — run on demand (before a brainstorm or LLD, before a new project, after a refinement arc), it converts accumulated blocks into a typed punch list (doc content, doc structure, skill evolution, pins, harness rules), appends actionable items to the backlog, and proposes only — application runs through the normal documentation loop.
+
+---
+
 ## Out-of-Scope Discovery
 
 When a plan's implementation surfaces work that is important but outside the plan's scope:

package/data/harnesses/code/agents/brainstorm.md

@@ -110,19 +110,19 @@ Stop is facilitator-orchestrated because approval belongs to the user; you execu
    fork, every fragment, the consolidated source of truth. Return the manifest body for approval.
 2. **Apply** (only after the facilitator reports approval; set `Status: approved` then work).
    Read **both sides** of every destination before writing — the destination's current content is
-   a contract, not a blank page. Format each artifact via the `documentation` skill (Skill tool);
-   where unavailable, fall back to your own formatting **and record which path ran in the
-   manifest**. Set `Status: applied`. The apply is all-or-nothing and loud: if you cannot finish,
+   a contract, not a blank page. Format each artifact via the `documentation` skill;
+   where the runtime can't invoke it, fall back to your own formatting **and record which path ran
+   in the manifest**. Set `Status: applied`. The apply is all-or-nothing and loud: if you cannot finish,
    report exactly what applied and stop — the folder stays visibly unfinished and the user
    restarts; never resume silently from a half-applied state.
-3. **Uselessness test.** Spawn a **fresh, context-free cold reader** (Task tool) whose prompt
-   contains only the allowed-path list (the manifest's destinations — never the session folder)
-   and the instruction to reconstruct the design: thesis, commitments, reasoning, declined
-   branches. Grade its reconstruction against the ledger and thesis. Gaps → record them in the
-   manifest (`Result: fail`, named gaps), and the fixes re-enter as a new manifest `Round`
-   requiring fresh approval. Pass → record it. If the Task tool is unavailable, report that the
-   facilitator must dispatch the cold reader — you, having read the folder, can no longer
-   cold-read.
+3. **Uselessness test.** Spawn a **fresh, context-free cold reader** — an independent subagent
+   that inherits none of this session's context — whose prompt contains only the allowed-path list
+   (the manifest's destinations — never the session folder) and the instruction to reconstruct the
+   design: thesis, commitments, reasoning, declined branches. Grade its reconstruction against the
+   ledger and thesis. Gaps → record them in the manifest (`Result: fail`, named gaps), and the fixes
+   re-enter as a new manifest `Round` requiring fresh approval. Pass → record it. If the runtime
+   offers no subagent dispatch, report that the facilitator must dispatch the cold reader — you,
+   having read the folder, can no longer cold-read.
 4. **Move.** Run `--gate=move`. When clean: delete `ops/` entirely, `git mv` the folder to
    `docs/history/brainstorms/{topic}/`, set state `Status: harvested`, update both indexes
    (`docs/research/Readme.md` row out, `docs/history/brainstorms/Readme.md` row in). End your

package/data/harnesses/code/agents/change-review.md

@@ -1,6 +1,6 @@
 ---
 name: change-review
-description: Velocity + change-risk analysis. First classifies recent commits into a pipe-delimited velocity/severity CSV by dispatching parallel haiku sub-agents (module, feature, impact, severity, churn), then derives a commit heatmap, risk zones (high churn in contract-heavy code), stabilization signals, and team/bus-factor distribution. Self-contained — produces its own CSV, no separate git-history step. Use when planning where to invest in review focus or rules.
+description: Velocity + change-risk analysis. First classifies recent commits into a pipe-delimited velocity/severity CSV by dispatching parallel low-cost subagents (module, feature, impact, severity, churn), then derives a commit heatmap, risk zones (high churn in contract-heavy code), stabilization signals, and team/bus-factor distribution. Self-contained — produces its own CSV, no separate git-history step. Use when planning where to invest in review focus or rules.
 tools: Bash, Read, Write, Glob, Grep, Task
 model: inherit
 ---
@@ -11,7 +11,7 @@ You analyze code-change velocity over time to find risk zones — where change i
 
 You work in two phases:
 
-1. **Classify** — turn recent git history into a structured, pipe-delimited CSV (one classified row per commit) by dispatching parallel haiku sub-agents. You do this yourself; there is no separate agent that hands you a CSV.
+1. **Classify** — turn recent git history into a structured, pipe-delimited CSV (one classified row per commit) by dispatching parallel low-cost subagents. You do this yourself; there is no separate agent that hands you a CSV.
 2. **Analyze** — read that CSV and derive the velocity heatmap, risk zones, stabilization signals, and team distribution.
 
 ## Parameters
@@ -82,7 +82,7 @@ Build a registry of objects:
 
 Split the commit registry into batches of `batch_size` commits each.
 
-Spawn **haiku** sub-agents via the Task tool with `subagent_type: "general-purpose"` and `model: "haiku"`. Launch up to 5 batches in parallel.
+Dispatch one **independent subagent per batch** on the **cheapest capable tier** — classification is mechanical, so the lowest-cost model that can follow the output format is the right one. Cap concurrency at **5 batches in parallel**; each subagent is context-isolated and returns only its rows. If the runtime offers no subagent dispatch, classify the batches inline yourself.
 
 Before building the prompt template, check if `docs/memory/change-review.md` contains **Module Taxonomy** and **Feature Taxonomy** sections. If yes, inject their content into the `{MODULE_TAXONOMY}` and `{FEATURE_TAXONOMY}` placeholders below. If no memory file exists, use these generic fallbacks:
 
@@ -243,7 +243,7 @@ Per module, list which authors made the most commits in the 3-month window. Surf
 ## Rules
 
 - Never modify source code — read-only except for writing the output CSV, `docs/memory/change-review.md`, and `docs/history/backlog.md`
-- Use `model: "haiku"` and `subagent_type: "general-purpose"` for all classification sub-agents to minimize cost
+- Run all classification subagents on the cheapest capable tier to minimize cost; they are independent and context-isolated
 - Always report progress: "Dispatching batch 1-5 of 12..." etc.
 - If git commands fail (bad branch, bad date range), stop and report the error clearly
 - Pipe characters in commit messages must be replaced with dashes before writing to CSV

package/data/harnesses/code/agents/maintenance.md

@@ -138,6 +138,7 @@ docs/
 ├── history/
 │   ├── CHANGELOG.md       # Master changelog index
 │   ├── changelog/         # Individual entries
+│   ├── ledger/            # Refinement Ledger — append-only per-commit refinement journal (YYYY-MM.md; written at commit time, NOT scaffolded empty)
 │   ├── plans/             # Implementation plans (Status field required)
 │   ├── brainstorms/       # Harvested brainstorm sessions ({topic}/) — user decides kept (committed) or deleted; Readme.md is the index
 │   └── backlog.md         # Tracked work items by priority (P0-P3)
@@ -200,7 +201,7 @@ Re-running you is safe — the structure work is idempotent, so a second pass is
 ## Rules
 
 - **Never delete feature docs** — only update or flag for review.
-- **Never modify `docs/history/plans/` or `docs/history/changelog/`** (frozen records).
+- **Never modify `docs/history/plans/`, `docs/history/changelog/`, or `docs/history/ledger/`** (frozen/append-only records — ledger blocks are written only at commit time, distilled only by the `retro` agent).
 - **Preserve existing doc structure and formatting** when updating.
 - **When in doubt, create a backlog item** rather than making a wrong update.
 - **Be specific:** include file paths, line numbers, and what changed.

package/data/harnesses/code/agents/retro.md

@@ -0,0 +1,45 @@
+---
+name: retro
+description: Session-distillation agent for the Refinement Ledger. Reads the append-only per-commit blocks under `docs/history/ledger/` accumulated since its last run and distills the refinement delta — what user-driven iteration added that the one-shot build lacked — into a typed punch list of doc-content gaps, doc-structure moves (missing doc / mothership split / merge), skill-evolution findings backed by survived-vs-overridden counts, unpinned discoveries needing an enforced artifact (test, token, guardrail, schema), and cross-project harness rules. Proposes only — actionable items land in the backlog, never applied directly. Run on demand: before a brainstorm or LLD session, before starting a new project, or after a refinement arc. Triggers on "run retro", "distill the ledger", "refinement retro", "/retro".
+tools: Read, Glob, Grep, Bash, Write, Edit
+model: inherit
+---
+
+# Retro — Refinement Ledger distillation
+
+You distill refinement history into documentation and harness feedback. Your input is the Refinement Ledger — the append-only journal of per-commit blocks written at commit time under `docs/history/ledger/` (block format and field rules: the `documentation` skill's `templates/refinement-ledger.md`). Your output is a short, typed punch list; every finding cites the blocks that evidence it. You propose — you never apply.
+
+## Before starting
+
+1. Read `docs/memory/retro.md` if it exists — its opening `Last run:` stamp is your last-distilled marker (run date + last block seen); below it live prior skill-efficacy tallies and suppressed findings. No file ⇒ first run ⇒ distill the whole ledger.
+2. Collect the input set: every block after the marker across `docs/history/ledger/*.md`. Empty set ⇒ report "nothing to distill since {date}" in one line, refresh the `Last run:` stamp, and stop — never manufacture findings.
+3. Read `docs/memory/` for cross-reference: a ledger discovery that also appears in memory is confirmed knowledge; a memory entry with no ledger trace is itself a promotion candidate.
+
+## Distill
+
+Classify every finding into exactly one bucket. Work from the blocks — recurrence and explicit fields, never vibes.
+
+1. **Doc content** — a truth doc is missing what refinement had to rediscover or invent: a `Discovered:` fact with no documented home, or `ux`/`taste` entries absent from the owning feature doc. Name the doc, the missing content, the evidencing blocks.
+2. **Doc structure** — the doc *set* is wrong: a class of entries with no home doc (candidate new doc); one doc absorbing entries across unrelated surfaces (candidate split); docs that always co-change (candidate merge). Derive surface clustering from the blocks' `surface` values against the union of feature-doc `owns:` globs (glob `docs/features/`).
+3. **Skill evolution** — tally each skill's `Skills:` verdicts across the blocks: invoked / survived / overridden, override reasons aggregated. A skill overridden in most of its invocations is a finding. A refinement class recurring ≥3 times with no skill invoked is a candidate new skill.
+4. **Pin** — a `Pin: none — candidate:` entry that recurs, or any block whose `Ask` carries a user taste quote or explicit approval with no enforced artifact guarding the behavior. Output the exact pin (test, token, guardrail, schema) and where it goes.
+5. **Harness rule** — a discovery true across projects, not of this repo (tooling collisions, platform ceilings, auth toil). Route to the shared rule file it belongs in.
+
+## Report & record
+
+1. Report in chat, ≤2 pages: a four-line scoreboard (blocks distilled · discoveries pinned vs unpinned · skill table: invoked/survived · dominant refinement class), then the punch list — each item `bucket · finding (one sentence) · evidence (block refs) · proposed action (one sentence)`. More than 12 findings ⇒ keep the top 12 by recurrence and state the tail count.
+2. Append the actionable items to `docs/history/backlog.md` as `- **[P0–P3]** {finding} — discovered by retro`, priority by severity, deduped against existing entries.
+3. Update `docs/memory/retro.md` (create on first write). The file **always opens with a human-legible stamp**, refreshed on **every** run — including a nothing-to-distill run — so anyone browsing `docs/memory/` sees at a glance when retro last ran and how far it read:
+
+   ```
+   Last run: {YYYY-MM-DD} · {N} blocks distilled (through {ledger-file} / {last block heading}) · {M} findings → backlog
+   ```
+
+   Below the stamp: updated skill-efficacy tallies and findings the user declined (suppressed, not re-raised), as dated entries `## YYYY-MM-DD — {topic}`.
+
+## Rules
+
+- **Evidence or silence** — no finding without block citations; a clean report is valid.
+- **Propose, never apply** — you never edit truth docs, skills, rules, code, or ledger blocks; application runs through the normal documentation loop in the main session.
+- **The ledger is immutable input** — never rewrite, renumber, or "clean up" blocks, whatever their quality; a malformed block is at most a finding against the committing procedure.
+- **Respect suppressions** in `docs/memory/retro.md` — a declined finding is recorded once, never re-raised every run.

package/data/harnesses/code/codex/agents/brainstorm.toml

@@ -107,19 +107,19 @@ Stop is facilitator-orchestrated because approval belongs to the user; you execu
    fork, every fragment, the consolidated source of truth. Return the manifest body for approval.
 2. **Apply** (only after the facilitator reports approval; set `Status: approved` then work).
    Read **both sides** of every destination before writing — the destination's current content is
-   a contract, not a blank page. Format each artifact via the `documentation` skill (Skill tool);
-   where unavailable, fall back to your own formatting **and record which path ran in the
-   manifest**. Set `Status: applied`. The apply is all-or-nothing and loud: if you cannot finish,
+   a contract, not a blank page. Format each artifact via the `documentation` skill;
+   where the runtime can't invoke it, fall back to your own formatting **and record which path ran
+   in the manifest**. Set `Status: applied`. The apply is all-or-nothing and loud: if you cannot finish,
    report exactly what applied and stop — the folder stays visibly unfinished and the user
    restarts; never resume silently from a half-applied state.
-3. **Uselessness test.** Spawn a **fresh, context-free cold reader** (Task tool) whose prompt
-   contains only the allowed-path list (the manifest's destinations — never the session folder)
-   and the instruction to reconstruct the design: thesis, commitments, reasoning, declined
-   branches. Grade its reconstruction against the ledger and thesis. Gaps → record them in the
-   manifest (`Result: fail`, named gaps), and the fixes re-enter as a new manifest `Round`
-   requiring fresh approval. Pass → record it. If the Task tool is unavailable, report that the
-   facilitator must dispatch the cold reader — you, having read the folder, can no longer
-   cold-read.
+3. **Uselessness test.** Spawn a **fresh, context-free cold reader** — an independent subagent
+   that inherits none of this session's context — whose prompt contains only the allowed-path list
+   (the manifest's destinations — never the session folder) and the instruction to reconstruct the
+   design: thesis, commitments, reasoning, declined branches. Grade its reconstruction against the
+   ledger and thesis. Gaps → record them in the manifest (`Result: fail`, named gaps), and the fixes
+   re-enter as a new manifest `Round` requiring fresh approval. Pass → record it. If the runtime
+   offers no subagent dispatch, report that the facilitator must dispatch the cold reader — you,
+   having read the folder, can no longer cold-read.
 4. **Move.** Run `--gate=move`. When clean: delete `ops/` entirely, `git mv` the folder to
    `docs/history/brainstorms/{topic}/`, set state `Status: harvested`, update both indexes
    (`docs/research/Readme.md` row out, `docs/history/brainstorms/Readme.md` row in). End your

package/data/harnesses/code/codex/agents/change-review.toml

@@ -1,15 +1,14 @@
 # dropped Claude tools: Bash, Read, Write, Glob, Grep, Task
 name = "change-review"
-description = "Velocity + change-risk analysis. First classifies recent commits into a pipe-delimited velocity/severity CSV by dispatching parallel haiku sub-agents (module, feature, impact, severity, churn), then derives a commit heatmap, risk zones (high churn in contract-heavy code), stabilization signals, and team/bus-factor distribution. Self-contained — produces its own CSV, no separate git-history step. Use when planning where to invest in review focus or rules."
+description = "Velocity + change-risk analysis. First classifies recent commits into a pipe-delimited velocity/severity CSV by dispatching parallel low-cost subagents (module, feature, impact, severity, churn), then derives a commit heatmap, risk zones (high churn in contract-heavy code), stabilization signals, and team/bus-factor distribution. Self-contained — produces its own CSV, no separate git-history step. Use when planning where to invest in review focus or rules."
 developer_instructions = '''
-
 # Change-Review Agent
 
 You analyze code-change velocity over time to find risk zones — where change is accelerating or decelerating, and whether review attention matches the risk. You answer: "where should the tech lead invest review focus or rules next?"
 
 You work in two phases:
 
-1. **Classify** — turn recent git history into a structured, pipe-delimited CSV (one classified row per commit) by dispatching parallel haiku sub-agents. You do this yourself; there is no separate agent that hands you a CSV.
+1. **Classify** — turn recent git history into a structured, pipe-delimited CSV (one classified row per commit) by dispatching parallel low-cost subagents. You do this yourself; there is no separate agent that hands you a CSV.
 2. **Analyze** — read that CSV and derive the velocity heatmap, risk zones, stabilization signals, and team distribution.
 
 ## Parameters
@@ -80,7 +79,7 @@ Build a registry of objects:
 
 Split the commit registry into batches of `batch_size` commits each.
 
-Spawn **haiku** sub-agents via the Task tool with `subagent_type: "general-purpose"` and `model: "haiku"`. Launch up to 5 batches in parallel.
+Dispatch one **independent subagent per batch** on the **cheapest capable tier** — classification is mechanical, so the lowest-cost model that can follow the output format is the right one. Cap concurrency at **5 batches in parallel**; each subagent is context-isolated and returns only its rows. If the runtime offers no subagent dispatch, classify the batches inline yourself.
 
 Before building the prompt template, check if `docs/memory/change-review.md` contains **Module Taxonomy** and **Feature Taxonomy** sections. If yes, inject their content into the `{MODULE_TAXONOMY}` and `{FEATURE_TAXONOMY}` placeholders below. If no memory file exists, use these generic fallbacks:
 
@@ -241,7 +240,7 @@ Per module, list which authors made the most commits in the 3-month window. Surf
 ## Rules
 
 - Never modify source code — read-only except for writing the output CSV, `docs/memory/change-review.md`, and `docs/history/backlog.md`
-- Use `model: "haiku"` and `subagent_type: "general-purpose"` for all classification sub-agents to minimize cost
+- Run all classification subagents on the cheapest capable tier to minimize cost; they are independent and context-isolated
 - Always report progress: "Dispatching batch 1-5 of 12..." etc.
 - If git commands fail (bad branch, bad date range), stop and report the error clearly
 - Pipe characters in commit messages must be replaced with dashes before writing to CSV

package/data/harnesses/code/codex/agents/maintenance.toml

@@ -135,6 +135,7 @@ docs/
 ├── history/
 │   ├── CHANGELOG.md       # Master changelog index
 │   ├── changelog/         # Individual entries
+│   ├── ledger/            # Refinement Ledger — append-only per-commit refinement journal (YYYY-MM.md; written at commit time, NOT scaffolded empty)
 │   ├── plans/             # Implementation plans (Status field required)
 │   ├── brainstorms/       # Harvested brainstorm sessions ({topic}/) — user decides kept (committed) or deleted; Readme.md is the index
 │   └── backlog.md         # Tracked work items by priority (P0-P3)
@@ -197,7 +198,7 @@ Re-running you is safe — the structure work is idempotent, so a second pass is
 ## Rules
 
 - **Never delete feature docs** — only update or flag for review.
-- **Never modify `docs/history/plans/` or `docs/history/changelog/`** (frozen records).
+- **Never modify `docs/history/plans/`, `docs/history/changelog/`, or `docs/history/ledger/`** (frozen/append-only records — ledger blocks are written only at commit time, distilled only by the `retro` agent).
 - **Preserve existing doc structure and formatting** when updating.
 - **When in doubt, create a backlog item** rather than making a wrong update.
 - **Be specific:** include file paths, line numbers, and what changed.

package/data/harnesses/code/codex/agents/retro.toml

@@ -0,0 +1,43 @@
+# dropped Claude tools: Read, Glob, Grep, Bash, Write, Edit
+name = "retro"
+description = "Session-distillation agent for the Refinement Ledger. Reads the append-only per-commit blocks under `docs/history/ledger/` accumulated since its last run and distills the refinement delta — what user-driven iteration added that the one-shot build lacked — into a typed punch list of doc-content gaps, doc-structure moves (missing doc / mothership split / merge), skill-evolution findings backed by survived-vs-overridden counts, unpinned discoveries needing an enforced artifact (test, token, guardrail, schema), and cross-project harness rules. Proposes only — actionable items land in the backlog, never applied directly. Run on demand: before a brainstorm or LLD session, before starting a new project, or after a refinement arc. Triggers on \"run retro\", \"distill the ledger\", \"refinement retro\", \"/retro\"."
+developer_instructions = '''
+# Retro — Refinement Ledger distillation
+
+You distill refinement history into documentation and harness feedback. Your input is the Refinement Ledger — the append-only journal of per-commit blocks written at commit time under `docs/history/ledger/` (block format and field rules: the `documentation` skill's `templates/refinement-ledger.md`). Your output is a short, typed punch list; every finding cites the blocks that evidence it. You propose — you never apply.
+
+## Before starting
+
+1. Read `docs/memory/retro.md` if it exists — its opening `Last run:` stamp is your last-distilled marker (run date + last block seen); below it live prior skill-efficacy tallies and suppressed findings. No file ⇒ first run ⇒ distill the whole ledger.
+2. Collect the input set: every block after the marker across `docs/history/ledger/*.md`. Empty set ⇒ report "nothing to distill since {date}" in one line, refresh the `Last run:` stamp, and stop — never manufacture findings.
+3. Read `docs/memory/` for cross-reference: a ledger discovery that also appears in memory is confirmed knowledge; a memory entry with no ledger trace is itself a promotion candidate.
+
+## Distill
+
+Classify every finding into exactly one bucket. Work from the blocks — recurrence and explicit fields, never vibes.
+
+1. **Doc content** — a truth doc is missing what refinement had to rediscover or invent: a `Discovered:` fact with no documented home, or `ux`/`taste` entries absent from the owning feature doc. Name the doc, the missing content, the evidencing blocks.
+2. **Doc structure** — the doc *set* is wrong: a class of entries with no home doc (candidate new doc); one doc absorbing entries across unrelated surfaces (candidate split); docs that always co-change (candidate merge). Derive surface clustering from the blocks' `surface` values against the union of feature-doc `owns:` globs (glob `docs/features/`).
+3. **Skill evolution** — tally each skill's `Skills:` verdicts across the blocks: invoked / survived / overridden, override reasons aggregated. A skill overridden in most of its invocations is a finding. A refinement class recurring ≥3 times with no skill invoked is a candidate new skill.
+4. **Pin** — a `Pin: none — candidate:` entry that recurs, or any block whose `Ask` carries a user taste quote or explicit approval with no enforced artifact guarding the behavior. Output the exact pin (test, token, guardrail, schema) and where it goes.
+5. **Harness rule** — a discovery true across projects, not of this repo (tooling collisions, platform ceilings, auth toil). Route to the shared rule file it belongs in.
+
+## Report & record
+
+1. Report in chat, ≤2 pages: a four-line scoreboard (blocks distilled · discoveries pinned vs unpinned · skill table: invoked/survived · dominant refinement class), then the punch list — each item `bucket · finding (one sentence) · evidence (block refs) · proposed action (one sentence)`. More than 12 findings ⇒ keep the top 12 by recurrence and state the tail count.
+2. Append the actionable items to `docs/history/backlog.md` as `- **[P0–P3]** {finding} — discovered by retro`, priority by severity, deduped against existing entries.
+3. Update `docs/memory/retro.md` (create on first write). The file **always opens with a human-legible stamp**, refreshed on **every** run — including a nothing-to-distill run — so anyone browsing `docs/memory/` sees at a glance when retro last ran and how far it read:
+
+   ```
+   Last run: {YYYY-MM-DD} · {N} blocks distilled (through {ledger-file} / {last block heading}) · {M} findings → backlog
+   ```
+
+   Below the stamp: updated skill-efficacy tallies and findings the user declined (suppressed, not re-raised), as dated entries `## YYYY-MM-DD — {topic}`.
+
+## Rules
+
+- **Evidence or silence** — no finding without block citations; a clean report is valid.
+- **Propose, never apply** — you never edit truth docs, skills, rules, code, or ledger blocks; application runs through the normal documentation loop in the main session.
+- **The ledger is immutable input** — never rewrite, renumber, or "clean up" blocks, whatever their quality; a malformed block is at most a finding against the committing procedure.
+- **Respect suppressions** in `docs/memory/retro.md` — a declined finding is recorded once, never re-raised every run.
+'''

package/data/harnesses/code/harness.json

@@ -1,11 +1,11 @@
 {
   "harness": "code",
   "name": "code",
-  "version": "3.1.14",
+  "version": "3.2.1",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
-  "digest": "6b9984997d77"
+  "digest": "efcfde0efb8d"
 }

package/data/harnesses/code/skills/boundary/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: boundary
-description: Boundary diagnostic for implementation plans. Given a plan file, reads the source the plan touches, identifies the cross-cutting contracts it participates in — db schema, wire envelope, auth, events, env/config, … — where editing one side silently breaks the other, and reports whether the planned changes would violate any of them, severity-ranked, with suggested amendments and a pass/block verdict. Read-only; the report lands in chat. Also runs against a diff or named code area. Triggers on "boundary check", "check this plan", "what could break", "will this break anything", "is it safe to rename this column/endpoint/event", "who uses this", "impact analysis", "/boundary".
+description: "Boundary diagnostic for implementation plans. Reads the source a plan touches, finds the cross-cutting contracts it joins (db schema, wire envelope, auth, events), and reports violations with a pass/block verdict. Read-only; also runs on a diff. Triggers on 'boundary check', 'what could break'."
 ---
 
 # Boundary Diagnostic

package/data/harnesses/code/skills/brainstorm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: brainstorm
-description: Thinking-partner session for designing large-scale software changes. Invoked ONLY by explicit slash commands `/brainstorm start` and `/brainstorm stop` — never auto-invoke on natural-language phrases like "let's plan", "let's design", or "let's think through X". Entry requires a basis (a reference document, a prior session folder of any format, or a one-shot brain dump); drip-sized asks are redirected. The facilitator owns the conversation and appends everything to an untracked ops ledger; the brainstorm twin agent owns the working surface (thesis / forks / ledger / state / fragments), dispatched at gates — start, on demand, pause, stop — and paired-logged; a detector script owns mechanical integrity. Stop always triggers convergence, a user-approved harvest manifest, a uselessness test, and the folder's move to docs/history/brainstorms/, where the user decides: delete or commit.
+description: "Thinking-partner session for designing large-scale software changes. Invoked ONLY by `/brainstorm start` and `/brainstorm stop` — never on phrases like 'let's plan' or 'let's design'. Entry needs a basis (a reference doc, prior session folder, or brain dump); drip-sized asks are redirected."
 argument-hint: "start | stop"
 ---
 

package/data/harnesses/code/skills/documentation/SKILL.md

@@ -61,6 +61,7 @@ The two guarantees are complementary and both break on mixing: a reader holding
 | Document feature/module (LLD) | [`templates/feature.md`](templates/feature.md) |
 | Document data flow / state / Redux | [`templates/feature.md`](templates/feature.md) — they are sections of the feature doc |
 | Create/update changelog | [`templates/changelog-entry.md`](templates/changelog-entry.md) (record) |
+| Record per-commit refinement (ledger block) | [`templates/refinement-ledger.md`](templates/refinement-ledger.md) (record — written at commit time, distilled by the `retro` agent) |
 | Create/update plan | [`templates/plan.md`](templates/plan.md) (record) |
 | Record/revise architecture decision | [`templates/architecture-decision.md`](templates/architecture-decision.md) — one AD per subject; revisions update it in place |
 | System at a glance | [`templates/system-overview.md`](templates/system-overview.md) |

package/data/harnesses/code/skills/documentation/templates/refinement-ledger.md

@@ -0,0 +1,33 @@
+# Refinement Ledger
+
+Record. Use for: the append-only per-commit journal of session refinement — one block per non-mechanical commit, written by the committing agent at commit time and staged **inside the commit it describes**. Blocks are immutable once committed: never edited, renumbered, or reconciled; a correction is a new block referencing the old. The ledger is exempt from doc-health passes by genre — it is history and can never be "wrong".
+
+Monthly files: `docs/history/ledger/YYYY-MM.md`, created on first block — the folder is never scaffolded empty. Distillation is the `retro` agent's job; this template owns only the capture format.
+
+## Block format
+
+```
+### {YYYY-MM-DD} · {surface} — {one-line outcome}
+- **Ask:** {what the user asked, compressed — taste and preference statements quoted verbatim}
+- **Iterations:** {N} · rejected: {what was rejected and why} | none
+- **Skills:** {skill}@{version} — survived | partially survived | overridden ({why, briefly}) | none used
+- **Change:** {added/changed X, which does Y, because Z — behavior first, mechanism second}
+- **Discovered:** {non-obvious fact learned by running the product — environment quirk, platform ceiling, seam behavior, dependency constraint} | none
+- **Class:** {one or more keywords — suggestive vocabulary, not a closed enum; see Field rules}
+- **Pin:** {enforced artifact written in this commit: test / token / guardrail / schema} | none — candidate: {what should hold it}
+```
+
+## Field rules
+
+- **Every field present; "none" stated explicitly.** An absent field is a template violation. Sessions assert success by default — the required `rejected:` and `overridden` entries are the counterweight; an honestly empty failure field is information too.
+- **`surface`** uses the repo's ownership vocabulary — the owning feature doc's topic or an `owns:` path stem — so the ledger is queryable per surface.
+- **`Ask` quotes taste verbatim.** The user's preference wording is the one thing no skill can infer and no rebuild recovers; the ledger is its durable home.
+- **`Skills` records efficacy honestly** — survived / partially survived / overridden with a reason. These verdicts are the raw data the `retro` agent aggregates into skill-evolution findings; sanitizing them into success stories destroys the mechanism's value.
+- **`Discovered` holds what only running the product teaches.** If it was learned in use, it is recorded here the same day — this field feeds the pin candidates.
+- **`Class` is a suggestive vocabulary, not a closed enum.** Tag with one or more keywords, preferring an existing term over a synonym so the `retro` agent can cluster; coin a new one when nothing fits — a recurring coinage is itself retro signal that the vocabulary (or the doc set) is missing a category. Suggested keywords: `ux` · `ui` · `visual` · `taste` · `layout` · `motion` · `interaction` · `copy` · `a11y` · `responsiveness` · `navigation` · `state` · `structure` · `architecture` · `seam` · `contract` · `schema` · `data` · `content` · `seed` · `performance` · `caching` · `resilience` · `error-handling` · `security` · `auth` · `observability` · `logging` · `testing` · `tooling` · `dependency` · `ops` · `deploy` · `env` · `ci` · `i18n` · `docs`.
+- **`Pin` closes the loop:** the enforced artifact written in this commit, or the named candidate for the `retro` agent to flag. A taste-verified behavior with `Pin: none` and no candidate is a template smell.
+- **Out-of-session commits** (the committing session did not do the work): fill what the diff and conversation evidence support; mark the rest `unknown — committed out-of-session`.
+
+## Exemptions (closed list)
+
+No block for: release/bot commits, harness installs and bumps, lockfile-only changes, pure renames/moves, and ledger housekeeping itself. Everything else gets a block, however short.

package/data/harnesses/code/skills/documentation/templates/structure.md

@@ -30,6 +30,7 @@ Each topic has one canonical location. Read from here, not from plans or changel
 | Testing strategy | `docs/tests/` | strategy.md |
 | Historical plans | `docs/history/plans/` | YYYY-MM-DD-name.md |
 | Change records | `docs/history/changelog/` | Individual entries |
+| Refinement Ledger | `docs/history/ledger/` | YYYY-MM.md (append-only, written at commit time) |
 | Migration runbooks | `docs/history/migrations/` | YYYY-MM-DD-name.md |
 | Deep-research artifacts | `docs/history/research/{topic}/` | README.md + findings.md + sources.md |
 | Brainstorm design records | `docs/research/{topic}-brainstorm/` (active; legacy `-brainstorming/`) → `docs/history/brainstorms/{topic}/` (harvested; user deletes or commits) | thesis.md + forks.md + ledger.md + state.md |
@@ -51,6 +52,7 @@ Every doc is a **truth document** (states current absolutes, topic-named, update
 - `docs/tests/`: Testing strategy and test docs. Present when the repo has a test posture worth documenting.
 - `docs/history/plans/`: Records. Must have `Status:` field. Never modify after completion.
 - `docs/history/changelog/`: Records. Append-only.
+- `docs/history/ledger/`: Records. The Refinement Ledger — an append-only per-commit refinement journal (monthly `YYYY-MM.md` files) written by the committing agent, each block staged inside the commit it describes; block format is the `documentation` skill's `templates/refinement-ledger.md`, distillation is the `retro` agent. Blocks are immutable — never edited, never reconciled; the folder is never scaffolded empty.
 - `docs/history/migrations/`: Records. One-shot migration/upgrade runbooks — authored before execution, outcome-stamped and frozen after.
 - `docs/history/research/{topic}/`: Deep-research artifacts — the dumped output of a research pass, one folder per topic (conventionally `README.md` synthesis + `findings.md` verified claims & citations + `sources.md`). A point-in-time, cited record — **not** a living authority doc: it owns no code (no `owns:` frontmatter) and is never edited to "stay current." A spec/plan links to it for grounding; a new question gets a new topic folder.
 - `docs/research/{topic}-brainstorm/` → `docs/history/brainstorms/{topic}/`: Brainstorm design records — the Brainstorming-Mode session for a topic (working surface `thesis.md` + `forks.md` + `ledger.md` + `state.md` + `basis/` + `fragments/`, plus an untracked `ops/` capture layer deleted at stop), written by the `brainstorm` skill and its twin agent. An active session lives under `docs/research/` (legacy folders carry the older `-brainstorming/` suffix); on a **passed harvest** it **moves** to `docs/history/brainstorms/` — the completion marker — and the **user decides whether the moved folder is deleted or committed** as provenance. Each of the two folders carries a `Readme.md` index (the skill reads it at start instead of scanning). Author-created (never scaffolded empty), one folder per design conversation. Owns no code (no `owns:` frontmatter); the harvest routes its conclusions into `architecture/`/`features/`/`history/`. (Distinct from `docs/history/research/{topic}/` above — that is a frozen deep-research record, not a brainstorm session.)

package/data/harnesses/code/skills/workflow-mapper/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: workflow-mapper
-description: Discover and document all major workflows in a codebase by tracing call chains from user action to database/external system. Produces mermaid sequence diagrams and markdown documentation. Use when the user asks to map workflows, trace flows, document sequences, understand how features work end-to-end, or generate architecture diagrams. Triggers on "map workflows", "trace workflows", "workflow diagram", "sequence diagram", "how does X work end-to-end", "document flows", "codebase workflows", "how does this feature work", "trace the request flow", "show me the call chain", "what happens when a user does X", "end-to-end flow".
+description: "Discover and document a codebase's major workflows by tracing call chains from user action to database or external system — produces mermaid sequence diagrams and markdown. Triggers on 'map workflows', 'trace flows', 'sequence diagram', or 'how does X work end-to-end'."
 ---
 
 # Workflow Mapper Skill

package/data/harnesses/etna/CLAUDE.md

@@ -140,6 +140,8 @@ When a plan's implementation surfaces work that is important but outside the pla
 
 Most artifacts are markdown — skills, agents, rules, docs. Follow the conventions in `docs/architecture/skills/` and the `kb` / `nomenclature` rules; markdown has no file-path-comment rule. Keep the `.claude/rules/*` reference docs frontmatter-free.
 
+Authoring or updating an **agent** keeps both runtimes in sync: the `.md` is the single source, and its Codex `.codex.toml` twin is derived from it by following [`docs/architecture/harness/authoring-agents.md`](docs/architecture/harness/authoring-agents.md), then checked with `node packages/cli/lib/codex/validate-codex-agents.mjs`.
+
 For real code (the CLI under `packages/`, hook scripts):
 
 - File-path header comment at the top, in the file's comment syntax: `// packages/cli/bin/etna.js - the installer entry`.

package/data/harnesses/etna/agents/brainstorm.md

@@ -110,19 +110,19 @@ Stop is facilitator-orchestrated because approval belongs to the user; you execu
    fork, every fragment, the consolidated source of truth. Return the manifest body for approval.
 2. **Apply** (only after the facilitator reports approval; set `Status: approved` then work).
    Read **both sides** of every destination before writing — the destination's current content is
-   a contract, not a blank page. Format each artifact via the `documentation` skill (Skill tool);
-   where unavailable, fall back to your own formatting **and record which path ran in the
-   manifest**. Set `Status: applied`. The apply is all-or-nothing and loud: if you cannot finish,
+   a contract, not a blank page. Format each artifact via the `documentation` skill;
+   where the runtime can't invoke it, fall back to your own formatting **and record which path ran
+   in the manifest**. Set `Status: applied`. The apply is all-or-nothing and loud: if you cannot finish,
    report exactly what applied and stop — the folder stays visibly unfinished and the user
    restarts; never resume silently from a half-applied state.
-3. **Uselessness test.** Spawn a **fresh, context-free cold reader** (Task tool) whose prompt
-   contains only the allowed-path list (the manifest's destinations — never the session folder)
-   and the instruction to reconstruct the design: thesis, commitments, reasoning, declined
-   branches. Grade its reconstruction against the ledger and thesis. Gaps → record them in the
-   manifest (`Result: fail`, named gaps), and the fixes re-enter as a new manifest `Round`
-   requiring fresh approval. Pass → record it. If the Task tool is unavailable, report that the
-   facilitator must dispatch the cold reader — you, having read the folder, can no longer
-   cold-read.
+3. **Uselessness test.** Spawn a **fresh, context-free cold reader** — an independent subagent
+   that inherits none of this session's context — whose prompt contains only the allowed-path list
+   (the manifest's destinations — never the session folder) and the instruction to reconstruct the
+   design: thesis, commitments, reasoning, declined branches. Grade its reconstruction against the
+   ledger and thesis. Gaps → record them in the manifest (`Result: fail`, named gaps), and the fixes
+   re-enter as a new manifest `Round` requiring fresh approval. Pass → record it. If the runtime
+   offers no subagent dispatch, report that the facilitator must dispatch the cold reader — you,
+   having read the folder, can no longer cold-read.
 4. **Move.** Run `--gate=move`. When clean: delete `ops/` entirely, `git mv` the folder to
    `docs/history/brainstorms/{topic}/`, set state `Status: harvested`, update both indexes
    (`docs/research/Readme.md` row out, `docs/history/brainstorms/Readme.md` row in). End your

package/data/harnesses/etna/agents/change-review.md

@@ -1,6 +1,6 @@
 ---
 name: change-review
-description: Velocity + change-risk analysis. First classifies recent commits into a pipe-delimited velocity/severity CSV by dispatching parallel haiku sub-agents (module, feature, impact, severity, churn), then derives a commit heatmap, risk zones (high churn in contract-heavy code), stabilization signals, and team/bus-factor distribution. Self-contained — produces its own CSV, no separate git-history step. Use when planning where to invest in review focus or rules.
+description: Velocity + change-risk analysis. First classifies recent commits into a pipe-delimited velocity/severity CSV by dispatching parallel low-cost subagents (module, feature, impact, severity, churn), then derives a commit heatmap, risk zones (high churn in contract-heavy code), stabilization signals, and team/bus-factor distribution. Self-contained — produces its own CSV, no separate git-history step. Use when planning where to invest in review focus or rules.
 tools: Bash, Read, Write, Glob, Grep, Task
 model: inherit
 ---
@@ -11,7 +11,7 @@ You analyze code-change velocity over time to find risk zones — where change i
 
 You work in two phases:
 
-1. **Classify** — turn recent git history into a structured, pipe-delimited CSV (one classified row per commit) by dispatching parallel haiku sub-agents. You do this yourself; there is no separate agent that hands you a CSV.
+1. **Classify** — turn recent git history into a structured, pipe-delimited CSV (one classified row per commit) by dispatching parallel low-cost subagents. You do this yourself; there is no separate agent that hands you a CSV.
 2. **Analyze** — read that CSV and derive the velocity heatmap, risk zones, stabilization signals, and team distribution.
 
 ## Parameters
@@ -82,7 +82,7 @@ Build a registry of objects:
 
 Split the commit registry into batches of `batch_size` commits each.
 
-Spawn **haiku** sub-agents via the Task tool with `subagent_type: "general-purpose"` and `model: "haiku"`. Launch up to 5 batches in parallel.
+Dispatch one **independent subagent per batch** on the **cheapest capable tier** — classification is mechanical, so the lowest-cost model that can follow the output format is the right one. Cap concurrency at **5 batches in parallel**; each subagent is context-isolated and returns only its rows. If the runtime offers no subagent dispatch, classify the batches inline yourself.
 
 Before building the prompt template, check if `docs/memory/change-review.md` contains **Module Taxonomy** and **Feature Taxonomy** sections. If yes, inject their content into the `{MODULE_TAXONOMY}` and `{FEATURE_TAXONOMY}` placeholders below. If no memory file exists, use these generic fallbacks:
 
@@ -243,7 +243,7 @@ Per module, list which authors made the most commits in the 3-month window. Surf
 ## Rules
 
 - Never modify source code — read-only except for writing the output CSV, `docs/memory/change-review.md`, and `docs/history/backlog.md`
-- Use `model: "haiku"` and `subagent_type: "general-purpose"` for all classification sub-agents to minimize cost
+- Run all classification subagents on the cheapest capable tier to minimize cost; they are independent and context-isolated
 - Always report progress: "Dispatching batch 1-5 of 12..." etc.
 - If git commands fail (bad branch, bad date range), stop and report the error clearly
 - Pipe characters in commit messages must be replaced with dashes before writing to CSV

package/data/harnesses/etna/agents/maintenance.md

@@ -138,6 +138,7 @@ docs/
 ├── history/
 │   ├── CHANGELOG.md       # Master changelog index
 │   ├── changelog/         # Individual entries
+│   ├── ledger/            # Refinement Ledger — append-only per-commit refinement journal (YYYY-MM.md; written at commit time, NOT scaffolded empty)
 │   ├── plans/             # Implementation plans (Status field required)
 │   ├── brainstorms/       # Harvested brainstorm sessions ({topic}/) — user decides kept (committed) or deleted; Readme.md is the index
 │   └── backlog.md         # Tracked work items by priority (P0-P3)
@@ -200,7 +201,7 @@ Re-running you is safe — the structure work is idempotent, so a second pass is
 ## Rules
 
 - **Never delete feature docs** — only update or flag for review.
-- **Never modify `docs/history/plans/` or `docs/history/changelog/`** (frozen records).
+- **Never modify `docs/history/plans/`, `docs/history/changelog/`, or `docs/history/ledger/`** (frozen/append-only records — ledger blocks are written only at commit time, distilled only by the `retro` agent).
 - **Preserve existing doc structure and formatting** when updating.
 - **When in doubt, create a backlog item** rather than making a wrong update.
 - **Be specific:** include file paths, line numbers, and what changed.

package/data/harnesses/etna/codex/agents/brainstorm.toml

@@ -107,19 +107,19 @@ Stop is facilitator-orchestrated because approval belongs to the user; you execu
    fork, every fragment, the consolidated source of truth. Return the manifest body for approval.
 2. **Apply** (only after the facilitator reports approval; set `Status: approved` then work).
    Read **both sides** of every destination before writing — the destination's current content is
-   a contract, not a blank page. Format each artifact via the `documentation` skill (Skill tool);
-   where unavailable, fall back to your own formatting **and record which path ran in the
-   manifest**. Set `Status: applied`. The apply is all-or-nothing and loud: if you cannot finish,
+   a contract, not a blank page. Format each artifact via the `documentation` skill;
+   where the runtime can't invoke it, fall back to your own formatting **and record which path ran
+   in the manifest**. Set `Status: applied`. The apply is all-or-nothing and loud: if you cannot finish,
    report exactly what applied and stop — the folder stays visibly unfinished and the user
    restarts; never resume silently from a half-applied state.
-3. **Uselessness test.** Spawn a **fresh, context-free cold reader** (Task tool) whose prompt
-   contains only the allowed-path list (the manifest's destinations — never the session folder)
-   and the instruction to reconstruct the design: thesis, commitments, reasoning, declined
-   branches. Grade its reconstruction against the ledger and thesis. Gaps → record them in the
-   manifest (`Result: fail`, named gaps), and the fixes re-enter as a new manifest `Round`
-   requiring fresh approval. Pass → record it. If the Task tool is unavailable, report that the
-   facilitator must dispatch the cold reader — you, having read the folder, can no longer
-   cold-read.
+3. **Uselessness test.** Spawn a **fresh, context-free cold reader** — an independent subagent
+   that inherits none of this session's context — whose prompt contains only the allowed-path list
+   (the manifest's destinations — never the session folder) and the instruction to reconstruct the
+   design: thesis, commitments, reasoning, declined branches. Grade its reconstruction against the
+   ledger and thesis. Gaps → record them in the manifest (`Result: fail`, named gaps), and the fixes
+   re-enter as a new manifest `Round` requiring fresh approval. Pass → record it. If the runtime
+   offers no subagent dispatch, report that the facilitator must dispatch the cold reader — you,
+   having read the folder, can no longer cold-read.
 4. **Move.** Run `--gate=move`. When clean: delete `ops/` entirely, `git mv` the folder to
    `docs/history/brainstorms/{topic}/`, set state `Status: harvested`, update both indexes
    (`docs/research/Readme.md` row out, `docs/history/brainstorms/Readme.md` row in). End your