@nurix/etna 0.19.22 → 0.19.24

package/data/harnesses/code/skills/test-plan/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: test-plan
+description: "Test-obligation diagnostic for implementation plans. Runs at the plan gate after boundary, derives the tests a plan owes from its Proposed Changes + the owning LLD, and writes a Test Obligations section into the plan — one row per promised behavior: layer, target file, oracle, fixtures. Advisory + plan-mutating; writes no test files. Triggers on 'test plan', 'what needs tests', 'test obligations'."
+---
+
+# Test-Obligation Diagnostic
+
+You derive the tests an implementation plan owes, and pin them into the plan as an explicit, reviewable manifest — at the same gate `boundary` runs, ordered second. You never write a test file; you make the standing "tests ship with the change" guardrail *concrete* for this plan, so the implementer satisfies a checklist instead of a vibe, and so a later doc-health pass can prove the tests match the promises.
+
+**The litmus is "which promise, at which altitude, proven by what?"** A plan promises behavior (an LLD's `owns:` surface does X); each promise earns exactly one test at the cheapest layer that can actually prove it. Spend your reading deciding the *layer* and the *oracle*, not on prose.
+
+## The three-moment split
+
+Testing spans three moments in the plan lifecycle. This skill owns **only the first** — it is why "write the tests at plan time" is wrong: at the gate the code does not exist yet, so the only coherent artifact is the manifest.
+
+| Moment | Artifact | Owner |
+| --- | --- | --- |
+| **Plan gate** (here, after boundary) | Test Obligations section written into the plan | this skill |
+| **Implementation** | the obligated tests, green in the same commits as the code | the implementer (standing guardrail — this skill never pre-empts it) |
+| **Completion** | behavioral checklist at `docs/tests/{feature}.md`; run affected suite + the project's e2e smoke gate; note in changelog | the `documentation` skill + Completion steps |
+
+Writing tests *before* the code they cover either fabricates implementation coupling (labels/routes/copy the plan hasn't fixed) or leaves the suite red on the shared branch for the plan's whole duration. Neither is acceptable — so the gate emits obligations, and the tests land *with* the code.
+
+## Contract sources
+
+- **The plan's Proposed Changes** — files created/modified, entities/state, API changes, cross-module contracts. Each is a behavior that may owe a test.
+- **The owning LLD** (`docs/features/{feature}.md`, matched via the ownership index) — the canonical statement of *what the feature does*. Every obligation names the LLD promise it proves; the LLD is never restated, only referenced. This one-directional chain (LLD → manifest → tests + Completion checklist) is what stops the three artifacts drifting into three contradictory truths.
+- **`.claude/rules/testing.md`** — the frameworks and canonical placement per stack. The manifest's target paths and runners come from here, never invented. The repo's existing runner always wins.
+- **`boundary`'s output** — a HIGH/CRITICAL finding it surfaced is itself a behavior owed a regression test (the failure mode, asserted). Fold boundary's amendments first, then read the amended plan.
+
+## Layer assignment
+
+Assign each behavior the **cheapest layer that can prove it**, then name the oracle (the concrete thing that shows pass/fail):
+
+- **unit** — a pure function / reducer / validator. Oracle: return value, thrown error.
+- **component** — a UI unit's behavior in isolation (a widget, form, panel). Oracle: rendered role/text, emitted event. Runner: the stack's component runner per `testing.md`.
+- **integration** — a route/handler against a real in-memory datastore via the app instance (not a mock of what you own). Oracle: response envelope shape, status code, the row actually written. **This is the default for server behavior** — most obligations land here, and this layer is the one the unit gate (`test` script / CI) runs.
+- **e2e** — see the altitude gate below.
+
+Error paths, races, and idempotency are obligations too, and they belong at **integration** with injected faults (network mock, the runner's fake timers, a forced constraint) — a process driving a live product cannot reliably *produce* them, so they are never an e2e obligation.
+
+### The e2e altitude gate
+
+An e2e obligation (a scenario in the project's e2e tree per `testing.md`) is earned **only** when the behavior genuinely spans processes/services that no single-process test can exercise together. A single-process behavior, however important, is an integration obligation, never e2e.
+
+- Density is **one scenario per cross-process journey, not one per feature** — the project's existing scenarios are the reference density. Mark each e2e obligation **"extend scenario `<name>`"** in preference to **"new scenario"**; a new scenario needs a genuinely new journey.
+- **Refuse to emit any e2e obligation while the project's e2e smoke gate is not wired.** A generated spec fed to a suite nothing runs is a rot accelerator. The gate is a capped, tagged smoke subset run in CI (not the full e2e suite — an oversized always-on e2e suite is what gets evicted from CI, taking all enforcement with it). If no such CI gate exists, emit the e2e obligation as a **blocked** row naming the missing gate, not as work to do.
+
+## Run
+
+**Input:** a plan path (given, or the newest in `docs/history/plans/`), already boundary-checked with amendments folded. For a non-plan diff in test-worthy code, the hunks stand in for Proposed Changes.
+
+1. **Build the behavior list.** From the plan's Proposed Changes + the owning LLD's promised behavior, list the behaviors this plan introduces or changes. Fold in each HIGH/CRITICAL boundary finding as a regression obligation. Note behaviors a type or the compiler already guards — those owe **no** test (the boundary litmus, inverted: if it can't ship green-but-broken, it needs no test).
+
+2. **Assign a layer + oracle** to each behavior (rules above). Prefer the cheapest layer that can actually prove the promise.
+
+3. **Map to a target file** per `testing.md` — the stack's unit/integration path for most, the e2e scenario tree for a program scenario. Name fixtures/factories (existing helper, or new) and the fault-injection needed (network mock, fake timers, forced constraint). Use the repo-standard fake-data source.
+
+4. **Apply the e2e altitude gate** to any cross-process obligation; downgrade everything else to integration.
+
+5. **Emit the Test Obligations section into the plan**, plus a one-line chat summary. Write it as a subsection of the plan (an executor dispatched with only the plan file sees nothing else — an obligation that lives only in chat is lost at dispatch):
+
+   ```
+   ## Test Obligations
+
+   | # | Behavior (LLD promise) | Layer | Target file | Oracle | Fixtures / faults |
+   | - | ---------------------- | ----- | ----------- | ------ | ----------------- |
+
+   Coverage: {N} behaviors · {N} integration · {N} component · {N} unit · {N} e2e ({N} extend, {N} new)
+   Completion checklist: docs/tests/{feature}.md  (derived at Completion, not now)
+   ```
+
+   A behavior with no obligation is stated too, with the reason (compiler-guarded, covered by an existing test) — an empty cell reads as "not yet analyzed"; an explicit "none — compiler-guarded" reads as "checked."
+
+## Rules
+
+- **Manifest only.** You write the Test Obligations section into the plan and a chat summary. You write **no** test files and **no** `docs/tests/` checklist — those are implementation-time and Completion-time, owned by others.
+- **Every obligation names its LLD promise.** No promise, no obligation source — trace it or drop it. This is the anti-drift pin.
+- **Cheapest proving layer wins.** Do not obligate an e2e scenario for what an integration test proves, or an integration test for what a unit test proves.
+- **e2e only above the cross-process bar, and only while the smoke gate runs.** Otherwise the obligation is a blocked row naming the missing gate.
+- **Runs after boundary; skipped on BLOCK.** A blocked plan is re-planned first; there is nothing stable to obligate tests against.
+- **A short manifest is valid.** A plan that owes three integration tests owes three rows — do not pad. The coverage line is the evidence it was analyzed, not skipped.

package/data/harnesses/discover/.vscode/settings.json

@@ -6,5 +6,14 @@
     "editor.defaultFormatter": "esbenp.prettier-vscode",
     "editor.formatOnSave": true,
     "editor.wordWrap": "on"
+  },
+  // Hide harness-authoring scaffolding from the file explorer
+  "files.exclude": {
+    ".claude": true,
+    ".vscode": true,
+    ".agents": true,
+    ".codex": true,
+    "**/node_modules": true,
+    "**/apollo.service.json": true
   }
 }

package/data/harnesses/discover/harness.json

@@ -8,5 +8,5 @@
     ".vscode/settings.json",
     "tooling-recommendations.md"
   ],
-  "digest": "3b747e869c3a"
+  "digest": "43b78e58bf42"
 }

package/data/harnesses/discussion/.vscode/settings.json

@@ -6,5 +6,14 @@
     "editor.defaultFormatter": "esbenp.prettier-vscode",
     "editor.formatOnSave": true,
     "editor.wordWrap": "on"
+  },
+  // Hide harness-authoring scaffolding from the file explorer
+  "files.exclude": {
+    ".claude": true,
+    ".vscode": true,
+    ".agents": true,
+    ".codex": true,
+    "**/node_modules": true,
+    "**/apollo.service.json": true
   }
 }

package/data/harnesses/discussion/harness.json

@@ -1,11 +1,11 @@
 {
   "harness": "discussion",
   "name": "discussion",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
-  "digest": "fa5d8b4fa816"
+  "digest": "3f0234327768"
 }

package/data/harnesses/discussion/rules/artifacts.md

@@ -18,7 +18,7 @@ A ratified class-3 doc **is** the goal-track canon — never double-book it unde
 
 **Status vocabulary**: `**DRAFT — not yet ratified**` / `Not yet user-ratified` · `(ratified YYYY-MM-DD)` — at doc, section, or extract granularity · `**Superseded note (YYYY-MM-DD):** … kept as record` · `deferred — blocked on <gate>` vs the exclusion grades.
 
-**Immutability**: raw dumps immutable once filed (corrections land in critic or synthesis) · unratified syntheses may be rewritten in place as v2, recorded in provenance · ratified material changes by dated append or supersession only · nothing valuable is deleted — superseded → banner + keep; broken → flagged; closed threads → struck through. Every lifecycle event carries an ISO date.
+**Immutability**: raw dumps immutable once filed (corrections land in critic or synthesis) · unratified syntheses may be rewritten in place as v2, recorded in provenance · ratified material changes by dated append or supersession only · nothing valuable is deleted — superseded → banner + keep; a retired topic → `git mv` to `archived/`, dated archive banner, kept frozen as record; broken → flagged; closed threads → struck through. Every lifecycle event carries an ISO date.
 
 ## The topic README
 

package/data/harnesses/discussion/rules/method.md

@@ -9,6 +9,7 @@ How sessions run in this workspace. What gets written is [artifacts.md](artifact
 - **External instruments** — code/data a topic depends on (scraper, corpus, pipeline) lives **outside the workspace**, never at the root: this folder holds only topics and the harness. Record the dependency on the depending topic's README (external path + ratification status); exclusions are recorded on the excluder's side.
 - **Git** — the workspace **is a git repository** (the `discussion-baseline` agent initializes one). The SessionEnd hook auto-commits each session's changes as one `📝 session close` batch — never per-file commits. Milestone commits by hand are still welcome: `✨` content, `🔧` workspace/method. Root `.gitignore` stays minimal.
 - **Grandfathering** — when the method changes, never reshuffle existing artifacts to match. New artifacts follow current rules; old layouts stay, flagged where confusing.
+- **Archiving** — a topic whose inquiry is *closed by outside reality* — its design **realized**, its understanding **superseded** — is retired, not deleted: `git mv` its folder into `archived/<topic>/` (history preserved; the folder frozen, kept as record), add a dated archive banner to its README (`📦 ARCHIVED (YYYY-MM-DD) — realized/superseded`: state · reason · pointer to the live source of truth), and move its `TOPICS.md` entry into the **Archived topics** section. Archiving records that a topic is done; live work stops there and nothing valuable is lost.
 
 ## Session protocol
 
@@ -61,6 +62,7 @@ Method lives in the rules (timeless); state lives in `metadata/` (current); topi
 - Per topic: `` ## `topic-folder/` — <state phrase> `` — the suffix encodes **who it's waiting on** ("synthesis filed, awaiting user reaction").
 - One dense routing paragraph: what it is, which artifacts exist (files, dates), headline findings — enough to route without opening the folder.
 - Bullets: `**Open:**` (typically "user disposition on the N questions closing `<file>`") · exclusion grades, dated when user rulings · `**Note:**` caveats.
+- Retired topics move to an `## Archived topics` section at the bottom — one condensed entry each (why archived: realized/superseded · the live source of truth); a one-line archiving note sits in the preamble. The active list holds only live topics.
 
 ### `SESSIONS.md` — session ledger
 

package/data/harnesses/etna/.vscode/settings.json

@@ -6,5 +6,14 @@
     "editor.defaultFormatter": "esbenp.prettier-vscode",
     "editor.formatOnSave": true,
     "editor.wordWrap": "on"
+  },
+  // Hide harness-authoring scaffolding from the file explorer
+  "files.exclude": {
+    ".claude": true,
+    ".vscode": true,
+    ".agents": true,
+    ".codex": true,
+    "**/node_modules": true,
+    "**/apollo.service.json": true
   }
 }

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,11 +138,12 @@ 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)
 ├── memory/                # index.md, main.md, {agent}.md — project knowledge + per-agent strategy memory
-└── tests/                 # Optional, author-maintained — create only if test docs exist
+└── tests/                 # Behavioral test checklists ({feature}.md, step → **Assert**), derived at plan Completion via the `documentation` skill; author-maintained, present only when test docs exist
 ```
 
 There is **no `docs/routing.md`**, **no `docs/modules/{m}/`**, **no `docs/pillars/`**, **no `docs/boundaries/`**. Code ownership lives in feature `owns:` frontmatter; a module is a `module:` label, not a folder; boundaries are diagnosed from source; brainstorm records live in `docs/research/` (active) and `docs/history/brainstorms/` (harvested).
@@ -151,7 +152,7 @@ There is **no `docs/routing.md`**, **no `docs/modules/{m}/`**, **no `docs/pillar
 
 ### Step B1 — Inventory and classify
 
-Glob every markdown file. Classify each: Architecture, Features, Operations, Plans, Changelogs, Backlog, Brainstorm records (stay), Stale/Deprecated (delete), Root docs (stay). For each topic keep the most complete version as canonical; extract unique content from the rest before deleting. **No redirect stubs** — when you move a file, delete the original and fix every reference (cross-doc links, memory files). Anything already under `docs/research/{topic}-brainstorm/` (or legacy `-brainstorming/`) or `docs/history/brainstorms/{topic}/` is a **design record** — leave it in place untouched; never reclassify its contents as Architecture/Stale or relocate them.
+Glob every markdown file. Classify each: Architecture, Features, Operations, Tests (behavioral checklists — stay), Plans, Changelogs, Backlog, Brainstorm records (stay), Stale/Deprecated (delete), Root docs (stay). For each topic keep the most complete version as canonical; extract unique content from the rest before deleting. **No redirect stubs** — when you move a file, delete the original and fix every reference (cross-doc links, memory files). Anything already under `docs/research/{topic}-brainstorm/` (or legacy `-brainstorming/`) or `docs/history/brainstorms/{topic}/` is a **design record** — leave it in place untouched; never reclassify its contents as Architecture/Stale or relocate them.
 
 While reading each markdown doc to classify it, if the doc names a code symbol it asserts exists that **statically resolves to nothing**, note it as an observation for the Part A audit — **only** on stacks where static resolution is reliable (stay silent on codegen/reflection/DI/barrel stacks); scoped to docs already being read here, never a whole-repo prose sweep; **docs only**, never code-file comments.
 
@@ -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

package/data/harnesses/etna/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/etna/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/etna/harness.json

@@ -1,11 +1,11 @@
 {
   "harness": "etna",
   "name": "etna",
-  "version": "1.1.11",
+  "version": "1.1.13",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
-  "digest": "3e3243936008"
+  "digest": "54e064e0d96d"
 }

package/data/harnesses/etna/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/etna/skills/documentation/scripts/doc-lint.mjs

@@ -11,7 +11,8 @@ const RULES = [
   { id: 'progress-marker', severity: 'block', scope: 'truth', pattern: /\bphases?\s+\d[^.\n]{0,40}\b(complete|done)\b|\b(build|implementation) (is )?(\d+%|partially) (complete|done)\b/i, message: 'progress marker — progress lives in the plan/backlog record' },
   { id: 'temporal-hedge', severity: 'warn', scope: 'truth', pattern: /\bnot yet\b|\bfor now\b|\bcurrently\b|\bstill (unsupported|missing|pending|unimplemented|in progress)\b/i, message: 'temporal hedge — state the fact without "currently / not yet / for now"' },
   { id: 'predecessor-frame', severity: 'warn', scope: 'truth', pattern: /\bpreviously\b|\bthe old \w+\b|\blegacy \w+ (was|is)\b/i, message: 'predecessor framing — describe the one current design' },
-  { id: 'status-glyph', severity: 'warn', scope: 'truth', pattern: /(^|\s)(✅|⏳|- \[[ x]\])/u, message: 'status glyph / checklist in a truth doc — tracking belongs in a record' },
+  // docs/tests/ behavioral checklists use `- [ ]` as test-step notation (step → **Assert**), not progress tracking — exempt that one folder from this rule; every other truth doc still bans checkboxes.
+  { id: 'status-glyph', severity: 'warn', scope: 'truth', exempt: /(^|\/)docs\/tests\//, pattern: /(^|\s)(✅|⏳|- \[[ x]\])/u, message: 'status glyph / checklist in a truth doc — tracking belongs in a record' },
   { id: 'date-in-truth-doc', severity: 'warn', scope: 'truth', pattern: /\b20\d{2}-\d{2}-\d{2}\b/, message: 'date in a truth doc — only the AD Decision Changelog and structure.md Health Log tails carry dates' },
 ];
 
@@ -71,6 +72,7 @@ function lintFile(path, findings) {
 
   for (const rule of RULES) {
     if (rule.scope !== scope || disabled.has(rule.id)) continue;
+    if (rule.exempt && rule.exempt.test(path)) continue;
     for (const { n, line } of lines) {
       if (!rule.pattern.test(line)) continue;
       if (line.includes(`doc-lint-disable: ${rule.id}`) || new RegExp(`doc-lint-disable:[^>]*\\b${rule.id}\\b`).test(line)) continue;

package/data/harnesses/etna/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/etna/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/hr/.vscode/settings.json

@@ -6,5 +6,14 @@
     "editor.defaultFormatter": "esbenp.prettier-vscode",
     "editor.formatOnSave": true,
     "editor.wordWrap": "on"
+  },
+  // Hide harness-authoring scaffolding from the file explorer
+  "files.exclude": {
+    ".claude": true,
+    ".vscode": true,
+    ".agents": true,
+    ".codex": true,
+    "**/node_modules": true,
+    "**/apollo.service.json": true
   }
 }

package/data/harnesses/hr/harness.json

@@ -1,11 +1,11 @@
 {
   "harness": "hr",
   "name": "hr",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
-  "digest": "b547d3ca2c1b"
+  "digest": "ddd603da8a04"
 }

package/data/harnesses/kb-agi/.vscode/settings.json

@@ -6,5 +6,14 @@
     "editor.defaultFormatter": "esbenp.prettier-vscode",
     "editor.formatOnSave": true,
     "editor.wordWrap": "on"
+  },
+  // Hide harness-authoring scaffolding from the file explorer
+  "files.exclude": {
+    ".claude": true,
+    ".vscode": true,
+    ".agents": true,
+    ".codex": true,
+    "**/node_modules": true,
+    "**/apollo.service.json": true
   }
 }

package/data/harnesses/kb-agi/harness.json

@@ -7,5 +7,5 @@
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
-  "digest": "4d6027a2ef49"
+  "digest": "d2b1e92990e9"
 }

package/lib/codex/README.md

@@ -8,24 +8,34 @@ Owning doc: [`docs/features/codex-support.md`](../../../../docs/features/codex-s
 
 | Source | Target | File |
 | --- | --- | --- |
-| `CLAUDE.md` | `AGENTS.md` (exact copy) | `agents-md.mjs` |
+| `CLAUDE.md` | `AGENTS.md` (byte-for-byte copy + generated adapter) | `agents-md.mjs` |
 | `.claude/skills/` | `.agents/skills/` (mirror) | `skills.mjs` |
 | bundle `codex/agents/*.toml` | `.codex/agents/*.toml` (copy) | `subagents.mjs` |
-| `hooks.json` | `.codex/hooks.json` (`type:"command"` only) | `hooks.mjs` |
+| `hooks.json` | `.codex/hooks.json` (`type:"command"`, command translated) | `hooks.mjs` |
 | `.claude-plugin/*` | `.codex-plugin/plugin.json` + `.agents/plugins/marketplace.json` | `plugin-manifest.mjs` |
 
 `index.mjs` orchestrates the install-time projectors and returns `{installed, notices, warnings, owned}`; `owned` is recorded in `.claude/harness.json` → `owned.codex` for prune-on-refresh.
 
 **Out of scope (owner decision 2026-07-13):** MCP projection and any Codex `settings.json`/`config.toml` equivalent. There is no user-editable Codex file the harness co-owns, so every Codex path is a clean full-overwrite — no managed-block merge.
 
+## Runtime adaptation the projection performs
+
+The Claude source is runtime-neutral in intent, but three edges do not survive a mechanical copy — the projectors adapt them so a Codex install works out of the box:
+
+- **Policy adapter (`agents-md.mjs`).** `AGENTS.md` is the `CLAUDE.md` policy copied byte-for-byte, then a compact **generated Codex runtime adapter** appended: it names the native skill (`.agents/skills/`) and agent (`.codex/agents/`) locations and, crucially, routes Codex to the `.claude/rules/*.md` files Codex does **not** auto-load. The list is derived from the bundled harness inventory (`bundledHarnessDir`), carries no user state, and is replaced whole on reinstall. It stays well under Codex's 32 KiB combined-instruction cap.
+- **Hook-path translation (`hooks.mjs`, install) & (`publish.mjs`, plugin).** A hook command locating its script via `$CLAUDE_PROJECT_DIR` fails under Codex (Codex sets no such variable). For a **CLI install**, `toCodexCommand` prefixes a runtime-neutral root resolution (`git rev-parse --show-toplevel`, `pwd` fallback) and re-exports `CLAUDE_PROJECT_DIR`, so the hook resolves from the project root or any nested dir. For a **marketplace plugin**, `publish.mjs` rewrites the prefix to `$CLAUDE_PLUGIN_ROOT/hooks/` — the plugin-root variable both runtimes export.
+- **Agent validation (`validate-codex-agents.mjs`).** A committed twin must be valid TOML with the required keys and carry no Claude-only primitive (`Task tool`, `subagent_type`, or a fixed model tier). Because a twin ships to consumers unparsed, this standalone validator is the gate — the authoring procedure mandates it.
+
+## CLI vs plugin capability surface
+
+The two channels do not install the same set. The **CLI** writes the full Codex footprint — `AGENTS.md`, `.agents/skills/`, `.codex/agents/*.toml`, `.codex/hooks.json`. The **marketplace plugin** carries only what `.codex-plugin/plugin.json` supports — **skills + hooks**; it exposes no project custom agents (Codex custom agents are a CLI-only feature) and no root policy. See [`codex-support.md`](../../../../docs/features/codex-support.md) → _Supported Codex plugin surface_.
+
 ## Subagents are authored, not derived at install
 
-`.claude/agents/*.md → .codex/agents/*.toml` is lossy/semantic, so it is done by the **real Codex CLI** at authoring time, not a parser at install:
+`.claude/agents/*.md → .codex/agents/*.toml` is a semantic conversion, so the twin is **authored from the `.md` by following** [`docs/architecture/harness/authoring-agents.md`](../../../../docs/architecture/harness/authoring-agents.md) — the model that writes or edits the agent produces the twin inline (frontmatter → `name`/`description`, body verbatim → `developer_instructions`, `tools:` dropped to a comment, Claude model aliases omitted), with **no external CLI**. The committed `agents/<name>.codex.toml` is checked by the validation gate:
 
 ```bash
-node packages/cli/lib/codex/gen-agents.mjs                 # shared catalog (agents/*.md), stale/missing only
-node packages/cli/lib/codex/gen-agents.mjs --force          # regenerate all shared agents
-node packages/cli/lib/codex/gen-agents.mjs --include-harness # + harness/*/agents/*.md
+node packages/cli/lib/codex/validate-codex-agents.mjs   # or: npm run validate:codex-agents
 ```
 
-`gen-agents.mjs` runs `codex exec` per agent and writes a committed `agents/<name>.codex.toml` sibling. It runs **only on a laptop with `codex` installed + authenticated — never in CI**. `build-data.js` and `publish.mjs` then ship those committed TOML; the installer copies them, so **consumers need no Codex CLI**. Regenerate an agent's TOML in the same change that edits its `.md` (source↔generated parity).
+`build-data.js` and `publish.mjs` then ship the committed TOML; the installer copies it, so **consumers need no Codex CLI**. Re-author an agent's TOML in the same change that edits its `.md` (source↔twin parity).