@nurix/etna 0.19.22 → 0.19.24

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": "72062264cf08",
+    "fingerprint": "a528a3d692b9",
     "harnesses": {
         "code": {
             "plugin": "code",

package/data/harnesses/code/.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/code/CLAUDE.md

@@ -35,7 +35,8 @@ Three peer modes plus a Completion step — enter wherever the user's thinking a
 
 1. Freeze the plan — `Status: Complete`, fill the Completed date. The file is now frozen.
 2. Flip the feature LLD to `status: active`; extend it in place with the how-it-works sections; confirm its `owns:` globs against the actual code.
-3. The `boundary` skill must already have gated this plan before its first implementation step — see Ownership, Boundaries & Documentation.
+3. The `boundary` and `test-plan` skills must already have gated this plan before its first implementation step — see Ownership, Boundaries & Documentation.
+4. Derive/update the behavioral checklist at `docs/tests/{feature}.md` via the `documentation` skill (a truth document — present-tense, referencing the LLD's promises, restating no intent), then run the affected test suite + the project's e2e smoke gate and record the results in the changelog entry.
 
 **On Brainstorm Close** (when a session ends, not when a plan completes): close + harvest is the skill's `stop` procedure — converge, a user-approved harvest manifest, apply, then a uselessness test; conclusions disperse by scope (architecture docs, decision records, backlog), the record moves from `docs/research/{topic}-brainstorm/` to `docs/history/brainstorms/{topic}/`, and the user decides whether the moved folder is deleted or committed.
 
@@ -62,6 +63,10 @@ Boundaries are **diagnosed, not documented** — the `boundary` skill derives th
 
 **Invoke the `boundary` skill after a plan is approved and before its first implementation step.** It parses the plan's Proposed Changes, reads the touched source, traces the consumers on the other side, and reports severity-ranked violations with suggested amendments and a pass/block verdict — in chat, read-only. Fold the amendments into the plan before coding. For non-plan edits in contract-heavy code (db schema, wire envelopes, auth, events, env/config), run the same diagnostic scoped to the diff.
 
+### Test obligations — specify before implementing
+
+**After `boundary` passes and its amendments are folded, invoke the `test-plan` skill** — same plan gate, ordered second. It derives the tests the plan owes from its Proposed Changes and the owning LLD, and writes a **Test Obligations** section into the plan (one row per promised behavior: layer · target file · oracle · fixtures). It writes no test files — the tests land *with* the code at implementation time (the suite-first guardrail), and the manifest is the checklist that work satisfies. This makes obligations survive dispatch to an executor that sees only the plan file, and lets a later doc-health pass prove the tests match the promises. On a boundary **BLOCK** it does not run — re-plan first. The three-moment split (gate → implementation → Completion checklist), the layer rules, and the e2e altitude gate live in the skill.
+
 ### Documentation — close the loop
 
 - **Every markdown document goes through the `documentation` skill.** Before creating or substantively editing any `.md` document — a doc, a README, an index, a record — invoke the `documentation` skill and apply its templates and `references/style-guide.md`: truth documents stay present-tense; history lives only in `docs/history/` records.
@@ -88,6 +93,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,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/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.3.0",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
-  "digest": "01d8bfddebb8"
+  "digest": "4774021cf9d8"
 }

package/data/harnesses/code/rules/database.md

@@ -4,6 +4,34 @@ Fixed conventions for relational schemas — table/column/index **names**, the *
 
 Written for SQLite / Cloudflare D1 + Drizzle (the concrete types below). The **names and key vocabulary are engine-agnostic** — a Postgres project keeps the same column names and semantics with native types (`uuid`, `timestamptz`, `boolean`).
 
+## What earns a table
+
+A table is the most expensive home for data — it costs a migration to change its shape, a join to read, and a mirror to keep in sync. Default to **not** a table. A concept earns its own table only when it needs at least one property in the left column; lacking all of them, the data belongs in the cheaper home on the right.
+
+| A table is earned by…                                                      | Lacking all of these, the data belongs in…              |
+| -------------------------------------------------------------------------- | ------------------------------------------------------- |
+| identity minted at **runtime**                                             | —                                                       |
+| variation **per tenant / user**                                            | —                                                       |
+| **independent addressing** — queried, indexed, or FK'd in isolation        | a **JSON column** on its parent row                     |
+| **concurrency-safe** writes — racing writers must not clobber a shared blob | —                                                       |
+| a **DB-enforced invariant** — immutability trigger, unique, atomic boundary | —                                                       |
+| dev-authored, published on deploy, identical for every tenant              | **config / a constants file**, validated at build       |
+| exactly recomputable from other rows                                       | a **cache** (KV / edge), recomputed on demand           |
+| process state that is dead once the request completes                      | a **log or workflow engine**, never the domain DB       |
+| owned by another system-of-record                                          | a **reference column** — store the id, not the data     |
+
+Each routing rule is one question:
+
+- **Static vocabulary or a fixed graph → config, not a table.** Dev-authored, same for every tenant, never FK'd at runtime ⇒ a constants file validated at build, surfaced in code as a constant/type. Reifying it into tables plus a seed makes the file and the tables a two-copy sync problem. The refined boundary is § Vocabulary / lookup tables.
+- **History → one immutable log + a mutable head.** Never shatter versioning into per-entity `*_revisions` / `*_revision_sections` tables. Snapshot the coherent set once into an append-only versions table; current state is a derived projection of the newest entry. _Test: is this table just "old rows of that table"? → collapse it into the snapshot._
+- **Process state is not domain state.** _Test: if it were deleted the instant the request finished, would a product feature break? No ⇒ it is a log line or a workflow-engine concern._
+- **Derived output is a cache, not truth.** _Test: is it exactly recomputable from other rows + code? Yes ⇒ recompute and cache; never persist as first-class state._
+- **Un-addressed detail is a column.** _Test: is this row ever SELECTed / JOINed / FK'd alone? No ⇒ it is a JSON field on its parent._
+- **Another system's record → keep the pointer.** _Test: does a specialized service already own this — chat, telemetry, object store? ⇒ store its id, not a copy._
+- **A surviving table names the invariant it buys.** Each kept structure pays for one guarantee — content-addressed immutable rows buy reproducibility, a monotonic sequence buys ordering/sync, an atomic write boundary buys multi-row atomicity. Drop the requirement and the table drops with it; keep the requirement and the structure is the price a blob cannot pay.
+
+Table count tracks **requirements, not domain richness** — a rich domain does not entitle a schema to a table per noun.
+
 ## Keys & the shared vocabulary
 
 Three column roles are fixed across every table and every project:
@@ -33,6 +61,6 @@ Reference columns name what they point at: `<entity>_id` for a UUID-PK reference
 
 ## Vocabulary / lookup tables
 
-A controlled-vocabulary table (statuses, kinds, categories) follows a fixed shape: `id` (UUID) · `slug` (UNIQUE) · `label` · optional `description` · `status` · timestamps.
+A controlled vocabulary earns a **table** only when a user row FKs into it and reads its `label` / `description` at runtime; a controlled vocabulary that is static, dev-authored config nobody references by FK stays **config** (§ What earns a table) — enumerable is not the same as tabular, and a `type`-style column validated against the constants file is preferred over an FK to a seeded mirror. When a table is earned, it follows a fixed shape: `id` (UUID) · `slug` (UNIQUE) · `label` · optional `description` · `status` · timestamps.
 
 - **Seeds are generated, never hand-written** — the source of truth is a CSV or a shared package; a generator emits the `*.seed.sql` with UUIDv5 ids and an idempotent `ON CONFLICT(slug)` upsert that preserves live counts / admin-tuned columns. Hand-editing seed SQL is ❌ — regenerate it.

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/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/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.)