@nurix/etna 0.19.24 → 0.19.26

package/README.md

@@ -20,7 +20,7 @@ npx --yes @nurix/etna --name=code
 
 The `--yes` flag skips npx's install confirmation, so the command runs unattended. On startup the CLI also **self-updates**: it checks the registry and, if the copy npx resolved is behind the latest published version, re-execs the latest before installing — so `npx --yes @nurix/etna` always runs the newest harness, even when npx has an older copy cached. The check is quick but synchronous; set `ETNA_NO_SELFUPDATE=1` to skip it (CI, offline, or a pinned local build).
 
-After this completes:
+After this completes (the `code` harness shown — the component folders differ per harness, and one a harness ships nothing for is simply absent):
 
 ```
 your-project/
@@ -30,17 +30,17 @@ your-project/
 ├── .prettierignore
 ├── .vscode/settings.json  ← editor settings (markdown formatter on save)
 └── .claude/
-    ├── 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, testing.md, pnpm.md
-    ├── hooks/             ← generate-ownership-index (SessionStart)
+    ├── skills/            ← boundary, brainstorm, design, documentation, test-plan, workflow-mapper
+    ├── agents/            ← brainstorm, change-review, lld-mode, maintenance, performance-review, retro
+    ├── rules/             ← database.md, express.md, frontend.md, general.md, nomenclature.md, pnpm.md, testing.md
+    ├── hooks/             ← generate-ownership-index (SessionStart) + hooks.json
     ├── settings.json      ← the hook is deep-merged in here (your existing keys preserved)
-    └── harness.json       ← {version, digest, owned} — the installed-harness sentinel
+    └── harness.json       ← {harness, name, version, files, digest, owned} — the installed-harness sentinel
 ```
 
-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`.
+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) — each surface written only when the harness ships that component kind. 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.
+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, and a component the harness used to own but no longer ships is pruned; files you've added that aren't part of the harness are left alone. In a git repo the previous `CLAUDE.md` and `.claude/` are overwritten and refreshed in place (recover them with `git checkout`); outside a git repo `CLAUDE.md` is backed up to `CLAUDE.md.bak.<ISO-timestamp>` and the whole `.claude/` tree is snapshotted to `.claude.bak.<ISO-timestamp>` first. 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.
 
 ## After install: bootstrap the harness
 
@@ -53,7 +53,7 @@ Then work normally. Boundaries aren't generated as files — the `boundary` skil
 
 One thing worth knowing on an existing repo:
 
-- **Your root `CLAUDE.md` is replaced** with the harness policy file (the old one is saved to `CLAUDE.md.bak.<ISO>`). If it held project-specific instructions, fold them back in after install — the harness file is the policy skeleton; your domain specifics sit alongside it.
+- **Your root `CLAUDE.md` is replaced** with the harness policy file (recoverable from git, or from `CLAUDE.md.bak.<ISO>` outside a git repo). If it held project-specific instructions, fold them back in after install — the harness file is the policy skeleton; your domain specifics sit alongside it.
 
 ## Migrating from 0.1.x
 
@@ -67,8 +67,12 @@ Listed by `npx --yes @nurix/etna` (no args) using the bundled `data/harness-inde
 
 | Harness | Source in etna | What it ships |
 | --- | --- | --- |
-| `code` | [`harness/code/`](../../harness/code/) | Governance + session agents, baseline workflow skills, the ownership-index hook (merged single-folder layout) |
-| `kb-agi` | [`harness/kb-agi/`](../../harness/kb-agi/) | Knowledge-vault scaffolding |
+| `code` | [`harness/code/`](../../harness/code/) | The canonical Nurix code-project harness — 6 governance/session agents, 6 workflow skills, 7 stack rules, the ownership-index `SessionStart` hook |
+| `discover` | [`harness/discover/`](../../harness/discover/) | The product-discovery harness — 11 owned dimension-collector agents and 9 owned method rules, plus a `tooling-recommendations.md` at the project root. No skills, no hooks |
+| `discussion` | [`harness/discussion/`](../../harness/discussion/) | The deliberation-workspace harness — 2 owned agents, 2 owned rules, and the `update-topics` hook that keeps the topic index current. No skills |
+| `etna` | [`harness/etna/`](../../harness/etna/) | The forge's own governance harness — a deliberate fork of `code` reframed for authoring artifacts: 5 agents, 4 skills, 4 rules, the ownership-index hook |
+| `hr` | [`harness/hr/`](../../harness/hr/) | The hiring / AI-steering evaluation harness — the `interview-eval` and `evaluator` skills plus one batching rule. No agents, no hooks |
+| `kb-agi` | [`harness/kb-agi/`](../../harness/kb-agi/) | The self-improving knowledge-base harness — 3 owned vault agents (`kb-init`, `kb-audit`, `kb-apply`) and the owned `kb-export.mjs` script. No skills, no rules |
 
 ## How it works
 
@@ -88,15 +92,17 @@ Two kinds of membership:
 # harness/code/readme.md
 ---
 name: code
-skills: [boundary, brainstorm, documentation, workflow-mapper, design]
+skills:
+  [boundary, test-plan, brainstorm, documentation, workflow-mapper, design]
 rules: [general, frontend, express, nomenclature, database, testing, pnpm]
-agents: [brainstorm, change-review, lld-mode, maintenance, performance-review]
+agents:
+  [brainstorm, change-review, lld-mode, maintenance, performance-review, retro]
 ---
 ```
 
 - **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 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.
+`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>/`, adds the `harness/common/` root files and each bundled agent's `*.codex.toml` twin, and writes the `harness.json` marker (version, `files` list, kit digest); 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
 
@@ -111,4 +117,4 @@ npm run build:data
 
 ## Publishing
 
-CI auto-publishes on push to `dev` when `packages/cli/**` or `harness/**` change — see [`.github/workflows/publish-etna-to-npm.yml`](../../.github/workflows/publish-etna-to-npm.yml). The `publishConfig.access` is `restricted` so the scoped package is private by default. The `NPM_PUBLISH_TOKEN` GitHub Actions secret must be a granular access token with **Bypass 2FA** enabled — classic automation tokens are rejected by the npmjs.com 2FA policy on the `nurix-tools` account.
+CI auto-publishes on push to `dev` when `packages/cli/**` or `harness/**` change — see [`.github/workflows/publish-etna-to-npm.yml`](../../.github/workflows/publish-etna-to-npm.yml). The `publishConfig.access` is `public`, so `npx @nurix/etna` installs and self-updates without any npm token. Publishing still requires auth: the `NPM_PUBLISH_TOKEN` GitHub Actions secret must be a granular access token with **Bypass 2FA** enabled — classic automation tokens are rejected by the npmjs.com 2FA policy on the `nurix-tools` account.

package/bin/etna.js

@@ -484,9 +484,9 @@ function parseArgs(args) {
 //
 // Guards: ETNA_SELFUPDATED=1 is set on the child to stop an infinite re-exec loop;
 // ETNA_NO_SELFUPDATE lets a caller opt out (CI, offline, or running an intentionally
-// pinned/local-dev build). Degrades gracefully — any failure (offline, unauthed, npm/
-// npx missing) falls through to running THIS copy. @nurix/etna is restricted, so the
-// `npm view` reuses the caller's existing npm auth — the same auth that installed it.
+// pinned/local-dev build). Degrades gracefully — any failure (offline, npm/npx missing)
+// falls through to running THIS copy. @nurix/etna publishes with public access, so the
+// `npm view` and the re-exec `npx` both resolve unauthenticated — no npm token needed.
 function selfUpdateOrReexec() {
     if (process.env.ETNA_SELFUPDATED || process.env.ETNA_NO_SELFUPDATE) return;
     const here = readJson(join(pkgRoot, 'package.json')).version;

package/data/harness-index.json

@@ -1,5 +1,5 @@
 {
-    "fingerprint": "a528a3d692b9",
+    "fingerprint": "e89ab23a69ca",
     "harnesses": {
         "code": {
             "plugin": "code",

package/data/harnesses/code/CLAUDE.md

@@ -71,7 +71,7 @@ Boundaries are **diagnosed, not documented** — the `boundary` skill derives th
 
 - **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.
 - **[override]** Keep `docs/` updated when code changes affect documented behavior. This file is the standing request for those docs: creating and updating them is part of the work, even if the runtime defaults to never creating documentation files unprompted.
-- After plan completion **[override]**: add a `docs/history/changelog/` entry + update `docs/history/CHANGELOG.md` — no confirmation needed. Include `Commits:` if multi-commit. Non-plan changes (refactors, fixes, API changes): prompt first.
+- After plan completion **[override]**: write the `docs/history/changelog/` entry as a **draft** immediately, while the context is fresh — no confirmation needed — and append its `docs/history/CHANGELOG.md` row; the commit fills what the draft left open and freezes it. Non-plan work needs no separate prompt: every non-exempt commit carries its own entry (the `changelog` rule).
 - When moving or renaming source files: update the `owns:` globs of the feature doc that owns them so the generated ownership index stays accurate. A new doc that owns code declares its paths in its own `owns:` frontmatter — there is no separate map to update.
 - `docs/structure.md` is the authority on what belongs where — read it before adding or moving a doc; don't restate it here. One canonical source per topic — link, don't copy. Only `CLAUDE.md`, `AGENTS.md`, and `README.md` live at the repo root.
 
@@ -93,13 +93,14 @@ When recording a learning, ask: _is this true of this project, or true of this u
 
 ---
 
-## Refinement Ledger
+## Changelog
 
-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:
+A commit marks the user's behavioral verification of the work, and the working session is the last holder of the refinement context that produced it — asks, iterations, rejections, skill outcomes, discoveries. That context is captured in the changelog and distilled on demand. The `changelog` rule carries the trigger and the lifecycle; this is the policy:
 
-- **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.
+- **Every non-mechanical commit is covered by an entry** at `docs/history/changelog/YYYY-MM-DD-{three-words}.md`, staged inside the commit it describes — whatever tool or session performs the commit — plus a row in `docs/history/CHANGELOG.md`. Format, required fields, and the closed exemption list are the `documentation` skill's `templates/changelog-entry.md`; the failure fields (rejected attempts, overridden skill output) and verbatim taste quotes are required, not optional — the entry's value concentrates there.
+- **An entry may exist before its commit.** A plan reaching `Status: Complete` writes its entry as a **draft** immediately, while the context is fresh; the commit fills what the draft left open. **Immutability begins at commit, not creation** — a draft is mutable, a committed entry never is, and a correction is a new entry that links back. Doc-health passes skip the genre.
+- **A commit is the smallest unit an entry may describe**; above that the mapping is judgment. Work exceeding a draft's scope gets a *second* entry rather than stretching the first.
+- **Distillation is the `retro` agent** — run on demand (before a brainstorm or LLD, before a new project, after a refinement arc), it converts accumulated entries 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.
 
 ---
 

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

@@ -137,8 +137,7 @@ docs/
 │   └── {topic}-brainstorm/     #   created by the `brainstorm` skill; NOT scaffolded empty; moves to history/brainstorms/ on a passed harvest
 ├── 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)
+│   ├── changelog/         # Individual entries (YYYY-MM-DD-{three-words}.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)
@@ -168,6 +167,7 @@ This is what makes baseline more than a fresh scaffold. Detect old-shape artifac
 | repo-wide `docs/pillars/` | cross-module doctrine → `docs/architecture/`; delete the folder |
 | `docs/boundaries/` (legacy persisted boundaries) | delete — boundary analysis is a plan-time diagnostic (the `boundary` skill reads contracts fresh from source); fold any human-authored knowledge (external consumers, intent, accepted exceptions) into `docs/architecture/` |
 | `docs/OWNERSHIP_INDEX.md` (legacy derived ownership index) | delete — ownership is the union of feature `owns:` frontmatter, surfaced by the generated index |
+| `docs/history/ledger/YYYY-MM.md` (the Refinement Ledger, now merged into the changelog) | split each `### ` block into its own `docs/history/changelog/YYYY-MM-DD-{three-words}.md` entry — content preserved **verbatim**, heading promoted to `#`, three words naming the work; append one row per entry to `docs/history/CHANGELOG.md`; delete the `docs/history/ledger/` folder. Records are moved, never rewritten |
 | `docs/operations/guardrails.md` | fold durable contract notes into `docs/architecture/` |
 | `docs/architecture/overview.md` | split into `domain-model.md` / `glossary.md` / `non-goals.md` / `references.md` / `open-questions.md` |
 | a legacy `docs/brainstorm/{topic}/`, or a root `brainstorm/`/`brainstorming/` folder | move each **active** record to `docs/research/{topic}-brainstorm/` and each **harvested** one to `docs/history/brainstorms/{topic}/` (dropping the suffix); create/refresh both `Readme.md` indexes; delete the emptied folder |
@@ -201,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/`, `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).
+- **Never modify `docs/history/plans/` or `docs/history/changelog/`** (frozen records — changelog entries 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

@@ -1,45 +1,46 @@
 ---
 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".
+description: Session-distillation agent for the changelog. Reads the per-unit-of-work entries under `docs/history/changelog/` 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 changelog", "refinement retro", "/retro".
 tools: Read, Glob, Grep, Bash, Write, Edit
 model: inherit
 ---
 
-# Retro — Refinement Ledger distillation
+# Retro — changelog 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.
+You distill refinement history into documentation and harness feedback. Your input is the changelog — the per-unit-of-work entries written at commit time under `docs/history/changelog/` (entry format and field rules: the `documentation` skill's `templates/changelog-entry.md`). Your output is a short, typed punch list; every finding cites the entries 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.
+1. Read `docs/memory/retro.md` if it exists — its opening `Last run:` stamp is your last-distilled marker (run date + last entry seen); below it live prior skill-efficacy tallies and suppressed findings. No file ⇒ first run ⇒ distill everything. **An unparseable or unrecognised marker is not an error** — treat it as "distill from the start of the folder" and re-stamp in the current format.
+2. Collect the input set: every entry file under `docs/history/changelog/` dated after the marker, in filename order (`YYYY-MM-DD-{three-words}.md` sorts chronologically). Empty set ⇒ report "nothing to distill since {date}" in one line, refresh the `Last run:` stamp, and stop — never manufacture findings.
+3. **Skip entries carrying no field block.** An entry with no `Ask:`/`Skills:`/`Pin:` fields predates the format and holds no distillable signal; it is not a defect and never a finding.
+4. Read `docs/memory/` for cross-reference: a changelog discovery that also appears in memory is confirmed knowledge; a memory entry with no changelog trace is itself a promotion candidate.
 
 ## Distill
 
-Classify every finding into exactly one bucket. Work from the blocks — recurrence and explicit fields, never vibes.
+Classify every finding into exactly one bucket. Work from the entries — 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.
+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 entries.
+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 entries' `surface` values against the union of feature-doc `owns:` globs (glob `docs/features/`).
+3. **Skill evolution** — tally each skill's `Skills:` verdicts across the entries: 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 entry 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.
+1. Report in chat, ≤2 pages: a four-line scoreboard (entries distilled · discoveries pinned vs unpinned · skill table: invoked/survived · dominant refinement class), then the punch list — each item `bucket · finding (one sentence) · evidence (entry 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
-   ```
+    ```
+    Last run: {YYYY-MM-DD} · {N} entries distilled (through {last entry filename}) · {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}`.
+    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.
+- **Evidence or silence** — no finding without entry citations; a clean report is valid.
+- **Propose, never apply** — you never edit truth docs, skills, rules, code, or changelog entries; application runs through the normal documentation loop in the main session.
+- **Committed entries are immutable input** — never rewrite, renumber, or "clean up" an entry, whatever its quality; a malformed entry 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/maintenance.toml

@@ -2,6 +2,7 @@
 name = "maintenance"
 description = "The single docs steward. Default behavior is the docs-vs-code coherence audit — detects and fixes docs drifting from code (stale docs, broken ownership, unowned source paths, architecture/backlog drift). An additive **baseline mode** layers structural reconcile on top: when the repo's `harness-version` marker is missing or behind, it converges `docs/` to the installed harness shape (scaffold the standard tree, fold dissolved-shape artifacts forward, stamp the version, propose modules) before running the audit. Mode is auto-selected from the marker. Run weekly, after major changes, or to baseline/upgrade a repo. Cross-cutting contract analysis is the `boundary` skill (`check` for plans, `scan` for diffs) — it derives contracts dynamically from source; there are no persisted boundary docs to audit. Triggers on \"run maintenance\", \"docs health\", \"baseline this repo\", \"reconcile the harness\", \"upgrade the harness\", \"is this repo on the current harness\", \"/maintenance\"."
 developer_instructions = '''
+
 # Maintenance Agent
 
 You are the **single docs steward**. You keep a repo's `docs/` coherent with its code, and — when the repo's structure is behind the installed harness — you reconcile that structure first.
@@ -134,13 +135,12 @@ docs/
 │   └── {topic}-brainstorm/     #   created by the `brainstorm` skill; NOT scaffolded empty; moves to history/brainstorms/ on a passed harvest
 ├── 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)
+│   ├── changelog/         # Individual entries (YYYY-MM-DD-{three-words}.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).
@@ -149,7 +149,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.
 
@@ -198,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/`, `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).
+- **Never modify `docs/history/plans/` or `docs/history/changelog/`** (frozen records — changelog entries 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

@@ -1,43 +1,45 @@
 # 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\"."
+description = "Session-distillation agent for the changelog. Reads the per-unit-of-work entries under `docs/history/changelog/` 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 changelog\", \"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.
+# Retro — changelog distillation
+
+You distill refinement history into documentation and harness feedback. Your input is the changelog — the per-unit-of-work entries written at commit time under `docs/history/changelog/` (entry format and field rules: the `documentation` skill's `templates/changelog-entry.md`). Your output is a short, typed punch list; every finding cites the entries 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.
+1. Read `docs/memory/retro.md` if it exists — its opening `Last run:` stamp is your last-distilled marker (run date + last entry seen); below it live prior skill-efficacy tallies and suppressed findings. No file ⇒ first run ⇒ distill everything. **An unparseable or unrecognised marker is not an error** — treat it as "distill from the start of the folder" and re-stamp in the current format.
+2. Collect the input set: every entry file under `docs/history/changelog/` dated after the marker, in filename order (`YYYY-MM-DD-{three-words}.md` sorts chronologically). Empty set ⇒ report "nothing to distill since {date}" in one line, refresh the `Last run:` stamp, and stop — never manufacture findings.
+3. **Skip entries carrying no field block.** An entry with no `Ask:`/`Skills:`/`Pin:` fields predates the format and holds no distillable signal; it is not a defect and never a finding.
+4. Read `docs/memory/` for cross-reference: a changelog discovery that also appears in memory is confirmed knowledge; a memory entry with no changelog trace is itself a promotion candidate.
 
 ## Distill
 
-Classify every finding into exactly one bucket. Work from the blocks — recurrence and explicit fields, never vibes.
+Classify every finding into exactly one bucket. Work from the entries — 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.
+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 entries.
+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 entries' `surface` values against the union of feature-doc `owns:` globs (glob `docs/features/`).
+3. **Skill evolution** — tally each skill's `Skills:` verdicts across the entries: 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 entry 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.
+1. Report in chat, ≤2 pages: a four-line scoreboard (entries distilled · discoveries pinned vs unpinned · skill table: invoked/survived · dominant refinement class), then the punch list — each item `bucket · finding (one sentence) · evidence (entry 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
-   ```
+    ```
+    Last run: {YYYY-MM-DD} · {N} entries distilled (through {last entry filename}) · {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}`.
+    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.
+- **Evidence or silence** — no finding without entry citations; a clean report is valid.
+- **Propose, never apply** — you never edit truth docs, skills, rules, code, or changelog entries; application runs through the normal documentation loop in the main session.
+- **Committed entries are immutable input** — never rewrite, renumber, or "clean up" an entry, whatever its quality; a malformed entry 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.3.0",
+  "version": "3.4.0",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
-  "digest": "4774021cf9d8"
+  "digest": "a4d40ec74a5d"
 }

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

@@ -0,0 +1,37 @@
+# Changelog
+
+Every unit of work leaves one record: `docs/history/changelog/YYYY-MM-DD-{three-words}.md`. The three words name the work, not the commit. Format, field rules, and the closed exemption list are the `documentation` skill's `templates/changelog-entry.md`.
+
+An entry is not a summary line. It carries the refinement context only the working session holds — the ask in the user's own words, what was rejected, which skills survived or were overridden, what running the thing taught, what now guards it.
+
+## When an entry is owed
+
+| Trigger | What to write |
+| --- | --- |
+| A plan reaches `Status: Complete` | A draft entry for that plan, linked to it — written now, while the session still holds the context |
+| The user asks for a changelog | The entry for the work in hand. No commit required |
+| A commit is made | Every non-exempt commit is covered by an entry — the commit skill writes or completes it |
+
+**Exempt** (closed list): release and bot commits, harness installs and bumps, lockfile-only changes, pure renames and moves, and changelog housekeeping itself.
+
+## The entry's life
+
+| State | Meaning |
+| --- | --- |
+| **Draft** | Created before its commit exists. Mutable — fields filled as far as the session can |
+| **Complete** | Missing fields filled in from the diff and the session |
+| **Frozen** | The moment it rides in a commit. Never edited again |
+
+**Immutability begins at commit, not at creation.** A draft in the working tree is meant to be edited — that is what lets a completed plan record its context before anything is committed. Once an entry is committed it is history: a correction is a new entry linking back, never an edit.
+
+## Granularity
+
+A commit is the smallest unit an entry may describe. Above that the mapping is judgment — four commits may be four entries or one, whichever reads better as history.
+
+An entry spanning several commits rides in the **last** of them and names the earlier ones in `Commits:`. An entry can never carry its own commit's SHA, so that field lists predecessors only and is omitted when one entry maps to one commit.
+
+When the work done exceeds what a draft describes, do not stretch the draft — write a second entry. The first stays an honest account of the plan; the second records the work beyond it.
+
+## The index
+
+Every entry appends one row to `docs/history/CHANGELOG.md` — date, link, one-line summary — in the same pass that writes the entry, so the table never trails the folder.

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

@@ -1,6 +1,6 @@
 ---
 name: boundary
-description: "Boundary diagnostic for implementation plans. Reads the source a plan touches, finds the cross-cutting contracts it joins (db schema, wire envelope, auth, events), and reports violations with a pass/block verdict. Read-only; also runs on a diff. Triggers on 'boundary check', 'what could break'."
+description: "Use when a plan or diff might break a cross-cutting contract. Boundary diagnostic: reads the source a plan touches — db schema, wire envelope, auth, events — and reports violations with a pass/block verdict. Read-only; also runs on a diff. Triggers on 'boundary check', 'what could break'."
 ---
 
 # Boundary Diagnostic

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

@@ -1,7 +1,6 @@
 ---
 name: brainstorm
-description: "Thinking-partner session for designing large-scale software changes. Invoked ONLY by `/brainstorm start` and `/brainstorm stop` — never on phrases like 'let's plan' or 'let's design'. Entry needs a basis (a reference doc, prior session folder, or brain dump); drip-sized asks are redirected."
-argument-hint: "start | stop"
+description: "Use when starting or stopping a large-scale design brainstorm via `/brainstorm start | stop` — never on phrases like 'let's plan' or 'let's design'. Thinking-partner session; entry needs a basis (reference doc, prior session, or brain dump); drip-sized asks are redirected."
 ---
 
 # Brainstorm

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

@@ -1,6 +1,6 @@
 ---
 name: design
-description: 'Design operator web UIs — build, improve, judge, or extract: dashboards, CRMs, work queues, admin panels, internal tools. Also the @nurix/components reference — forms, data tables, modals, side panels, any @nurix/components import. Any web stack. Not marketing sites, storefronts, or mobile-native.'
+description: "Use when building, improving, judging, or extracting operator web UIs — dashboards, CRMs, work queues, admin panels, internal tools. Also the @nurix/components reference: forms, data tables, modals, side panels, any import. Any web stack. Not marketing sites, storefronts, or mobile-native."
 ---
 
 # design

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

@@ -1,6 +1,6 @@
 ---
 name: documentation
-description: Invoke BEFORE creating or substantively editing ANY markdown doc. Templates + style authority for technical docs — LLDs, ADs, plans, changelogs, READMEs, runbooks. Owns the tense rule: truth docs state the present; history only in dated records. Baselining is the maintenance agent.
+description: "Use when creating or substantively editing ANY markdown doc — invoke BEFORE writing. Templates + style authority for technical docs: LLDs, ADs, plans, changelogs, READMEs, runbooks. Owns the tense rule: truth docs state the present; history only in dated records. Baselining is the maintenance agent."
 ---
 
 # Technical Documentation Skill
@@ -60,8 +60,7 @@ The two guarantees are complementary and both break on mixing: a reader holding
 | Baseline / reconcile docs | `maintenance` agent (baseline mode) — it calls this skill per template |
 | 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 changelog entry | [`templates/changelog-entry.md`](templates/changelog-entry.md) (record — one per unit of work; carries the refinement fields, frozen inside its commit, 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) |