@nurix/etna 0.20.34 → 0.20.36

package/data/catalog/rules/changelog.md

@@ -1,6 +1,6 @@
 # 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) — plus its row in `docs/history/CHANGELOG.md`, appended in the same pass so the index never trails the folder. Entry format, field rules, and the closed exemption list are the `documentation` skill's `templates/changelog-entry.md`; this rule owns when an entry is owed and how it lives. An entry is never a commit summary — it carries the refinement context only the working session holds, which no diff reconstructs.
+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). `docs/history/CHANGELOG.md` is the folder's guide, never appended to: the entry's own first line is its summary, and listing the folder is the index. Entry format, field rules, and the closed exemption list are the `documentation` skill's `templates/changelog-entry.md`; this rule owns when an entry is owed and how it lives. An entry is never a commit summary — it carries the refinement context only the working session holds, which no diff reconstructs.
 
 ## When an entry is owed
 

package/data/harness-index.json

@@ -1,5 +1,5 @@
 {
-    "fingerprint": "748e1019e5d8",
+    "fingerprint": "e13062907688",
     "harnesses": {
         "code": {
             "plugin": "code",

package/data/harnesses/code/CLAUDE.md

@@ -37,7 +37,7 @@ Three peer modes, then a verification gate and a Completion step — enter where
 
 > **A build graph overrides all of this, and most sessions never see one.** When `.claude/state/graph.json` exists, a walker decides which document is produced next and when the run is finished: a write reconciles it, an injected line names the next node, and the turn cannot end while the graph can still advance. Produce the file the line names. Never edit the graph or its state — both are refused — and never rewrite a node that has already landed. No such file ⇒ nothing in this paragraph is running.
 
-> **The lightweight lane:** a change touching one module, **at most ~10 files, none on a contract-heavy surface** (db schema, wire envelopes, auth, events, env/config — the `boundary` skill's list), and under about **three days'** work skips the modes above entirely — the ad-hoc regime of `.claude/rules/testing.md` applies: make the change, drive it, then pin it in the same unit of work if it alters promised behavior, cover it with a changelog row. The predicate is mechanical; when in doubt, the `boundary` diff scan is the tiebreak, not self-assessment.
+> **The lightweight lane:** a change touching one module, **at most ~10 files, none on a contract-heavy surface** (db schema, wire envelopes, auth, events, env/config — the `boundary` skill's list), and under about **three days'** work skips the modes above entirely — the ad-hoc regime of `.claude/rules/testing.md` applies: make the change, drive it, then pin it in the same unit of work if it alters promised behavior, cover it with a changelog entry. The predicate is mechanical; when in doubt, the `boundary` diff scan is the tiebreak, not self-assessment.
 
 **On Plan Completion:**
 
@@ -80,7 +80,7 @@ The `lld-mode` agent checks for ownership conflicts during LLD research — two
 
 Boundaries are **diagnosed, not documented** — the `boundary` skill derives them fresh from source on every run (the definition and mechanism catalog live in the skill), so nothing is persisted that could go stale.
 
-**Invoke the `boundary` skill while the plan is being written — a plan is not finished until it carries the verdict.** 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 except its one write: its own segment of the plan's **`Gates:`** line. That line is machine-read — the compliance hook blocks implementation edits inside the plan's scope while it reads `Boundary: pending` — so this gate is enforced, not ceremony. The session folds the amendments into the plan in the same pass, then writes the segment to `passed`; the plan the user reads already carries it. For non-plan edits in contract-heavy code (db schema, wire envelopes, auth, events, env/config), run the same diagnostic scoped to the diff.
+**Invoke the `boundary` skill while the plan is being written — a plan is not finished until it carries the verdict.** 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 except its one write: its own segment of the plan's **`Gates:`** line. That line is machine-read — the compliance hook blocks implementation edits inside the plan's scope until it reads `Boundary: passed`, so a `pending` or `blocked` verdict walls them alike — and this gate is enforced, not ceremony. The session folds the amendments into the plan in the same pass, then writes the segment to `passed`; the plan the user reads already carries it. 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
 
@@ -95,7 +95,7 @@ Boundaries are **diagnosed, not documented** — the `boundary` skill derives th
 - **When a document's truth is in question — "is this doc still right?", a feature that drifted from its doc, a folder nobody has audited — the `polygraph` agent is the instrument, and only the user starts it.** It costs one finder per document, so it is never dispatched unasked: name the target, state the price (documents × the pinned tier), and dispatch on the user's yes or on `/polygraph <target>` — one doc, feature, folder, code path, or plan, never the whole tree by reflex. Relay its report and put its open questions to the user; an answer goes back as a further dispatch. Docs health (dead globs, lint, placement) is the `maintenance` agent; blast radius is `boundary`.
 - **Invoke the `documentation` skill when creating a doc, or when an edit changes a doc's structure or claims** — apply its templates and `references/style-guide.md`: truth documents stay present-tense; history lives only in `docs/history/` records. Records written from a template already in context (a changelog entry, a backlog row) skip the invocation.
 - **[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]**: 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).
+- After plan completion **[override]**: write the `docs/history/changelog/` entry as a **draft** immediately, while the context is fresh — no confirmation needed; 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: the file's path header moves with it and is corrected to its new path; a region glob in a transitional `owns:` follows the region if the region itself moved. A new source file's header names the document that speaks for it — 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 — and the root `README.md` orients and routes (identity, how it works, a Map of units, rules that bite, where to go); install, stack and first run are `docs/operations/setup.md`, the tree is `docs/structure.md`'s.
 
@@ -176,7 +176,7 @@ A file's documentation lives in `docs/`. Its comments carry only what a reader n
 - Add a file-path header comment at the top of each source file, in the file's native comment syntax — `// src/modules/example.js - Module for handling user authentication`. Place it below any shebang line; skip formats with no comment syntax (JSON, lockfiles) and generated files. **The path is repo-relative and names the file's own path**: a header a move left behind is worse than no header, because it reads as current.
 - **Two or three present-tense sentences, six lines at the ceiling** — what the file is, the invariant a reader must not break, and where the fuller account lives, as a `docs/…` path.
 - Add a 1-line description above each function whose purpose isn't fully evident from its name and signature: `// Extract JWT token from request based on endpoint type`. **One sentence, third-person indicative** — `Installs the package`, never `Install the package` — and a second sentence only to carry a named invariant. A field, type member, or constant earns a sentence only where its name and type do not already say it; a member of an enum or a constant map earns none. No commented-out code — refactor for clarity instead.
-- **Design rationale, alternatives weighed, history, ticket and decision-record references, and dated notes are not comments.** They belong to the owning feature doc, and moving the claim there is part of the same change — cutting one out of a comment without landing it is a deletion, not a cleanup (the `documentation` skill § Where a file's documentation lives).
+- **Design rationale, alternatives weighed, history, ticket and decision-record references, and dated notes are not comments.** They belong to the owning feature doc, and moving the claim there is part of the same change — cutting one out of a comment without landing it is a deletion, not a cleanup (the `documentation` skill's `references/source-comments.md`).
 - **The ceiling is on what a change adds, not on what it inherits: under a quarter of the lines a change adds are comments.** The measured regression that set this number ran at 28% on new files while the tree it joined sat at 14%, so a whole-file average is the wrong instrument — it grades the density somebody else wrote and passes the prose being added right now. `.claude/skills/documentation/scripts/source-lint.mjs --changed` reports it and the detector raises one row per offending file; a comments-only sweep proves itself with `comment-strip.mjs`, which strips both revisions and diffs what is left, so a code change hiding inside a cleanup cannot pass as one.
 - **The one comment that earns a paragraph is a booby trap** — an edit that looks obviously safe and is not. It names the version or the measurement that makes it true and the condition under which it stops being true, so the next reader can retire it instead of trusting it. Everything else that wants a paragraph wants a doc.
 

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

@@ -122,8 +122,8 @@ Stop is facilitator-orchestrated because approval belongs to the user; you execu
    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.
 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
+   `docs/history/brainstorms/{topic}/`, set state `Status: harvested` (no index row to move: the folder is
+   the record). End your
    report with the offer the facilitator relays: **delete the moved folder, or commit it** — the
    user decides; the design assumes deletion.
 

package/data/harnesses/code/agents/lld-mode.md

@@ -21,7 +21,7 @@ Map the documentation landscape — what exists, what is adjacent, how detailed
 2. Locate the repo's feature-doc layer from `structure.md` — the standard shape is `./docs/features/`, but a repo may document components under their own subject folders. Read that layer's index if it has one; otherwise glob for docs carrying `owns:` frontmatter
 3. If `./docs/memory/lld-mode.md` exists (or the legacy `./docs/memory/spec-mode.md`), read it for feature doc inventory, ownership conflict zones, and lessons from previous research
 4. Read 1-2 existing feature LLDs from that layer to calibrate format and depth
-5. Consult the **injected ownership index** (the generated `glob → doc · module · objects · status` map — computed from source headers and the transitional `owns:` region globs) to build the ownership map. It is the source of truth for what code paths are already spoken for; a source file's path header names its document directly. If the index isn't present in context, glob the docs tree (excluding `docs/history/`) and read the `owns:` frontmatter of every doc that declares it.
+5. Consult the **injected ownership index** (the generated `glob → doc · module · objects · status` map, built from the transitional `owns:` region globs; a source file's path header names its document directly) to build the ownership map. It is the source of truth for what code paths are already spoken for; a source file's path header names its document directly. If the index isn't present in context, glob the docs tree (excluding `docs/history/`) and read the `owns:` frontmatter of every doc that declares it.
 
 ## What You Research
 
@@ -46,7 +46,7 @@ Structure your findings as:
 - **Invalidated claims**: One row per existing doc this feature makes wrong — doc path, the claim, why it stops being true. This list seeds the plan's **Doc Obligations** ledger, so it is the research finding most likely to survive into an artifact; "none" is a real answer and says the feature is genuinely additive.
 - **Risks or concerns**: Anything the LLD should address or call out
 
-Structure your findings by the `documentation` skill's style guide — imperative voice, function signatures over implementations, mermaid for flows.
+Write each finding as a bold noun-phrase label and one or two third-person sentences (the `documentation` skill's `references/style-guide.md` § Labels, § Voice); mermaid for a flow worth drawing. Paths, symbols and routes belong in these findings because the author needs them, but these fields are research, not the LLD's sections: the feature doc takes its template's sections and names objects and promises, never the functions listed here.
 
 ## Rules
 

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

@@ -63,7 +63,7 @@ Across the header pointers and the transitional globs:
 - **Transitional globs:** verify each matches existing files; report globs matching nothing, deleted paths, and orphaned docs. A file-level `owns:` list is reduced to its region globs (remediation, not a question); the files it dropped are reported where their headers name no document.
 - **Retired keys:** `applies:` and `keywords:` are removed wherever found (remediation); a doctrine the removed `applies:` named stays named in the document's Scope section.
 - Flag **equal-specificity overlaps** — two feature docs whose transitional `owns:` globs claim the same paths at the same specificity (an ambiguous owner). `node .claude/hooks/check-ownership.mjs` reports these mechanically alongside dead globs (`overlaps()` in `lib/ownership.mjs`); a glob at strictly higher specificity carving out of a broader `**` is the designed layering and is never flagged. Surface a real overlap as a question — narrowing someone's glob is an author's call, not remediation.
-- **Stamp `type:` where missing.** Every doc carries a `type:` genre key (enum = the `documentation` skill's template names); docs predating the key are stamped mechanically — the genre is readable from placement and shape (a `docs/features/` doc is `type: feature`, an AD is `type: architecture-decision`). Stamping is remediation, not a question; an ambiguous genre is backlogged instead.
+- **Stamp `type:` where missing.** Every doc carries a `type:` genre key (values = the `type:` column of the `documentation` skill's genre registry, `templates/Readme.md`); docs predating the key are stamped mechanically — the genre is readable from placement and shape (a `docs/features/` doc is `type: feature`, an AD is `type: architecture-decision`). Stamping is remediation, not a question; an ambiguous genre is backlogged instead.
 - **Write `description:` where missing.** Every truth document and folder index carries a `description:` of at most 300 characters saying what it settles and where its boundary sits (`documentation` skill, `references/frontmatter.md` § `description:`). Each one is written from a read of the document, never from its filename — many documents ⇒ parallel sub-agents on the cheapest capable tier, one batch each. A folder index that names its files or records is rewritten to describe the folder, after confirming every per-file fact it carried lives in that file.
 
 **Then validate the doc→doc edge.** `node .claude/hooks/check-ownership.mjs` and the session-injected **doc edge index** carry `verifies:` and its generated inverse; read the edge index and check two things:
@@ -101,7 +101,7 @@ Run `git log --since="2 weeks ago" --name-only --pretty=format:"%h %s"` to find
 
 **Architecture drift.** Grep `docs/architecture/` for file-path references. Verify referenced paths still exist. Remove or update stale references.
 
-**Backlog health.** Read `docs/history/backlog.md`. Report items older than 30 days. Count pending by priority.
+**Backlog health.** Read `docs/history/backlog.md`, a queue whose rows carry no dates. Count pending by priority, and report items that name a path, plan or document that no longer exists — their work landed or their subject left, and the row is the user's to delete.
 
 **Brainstorm session census.** A session folder still under `docs/research/` (`*-brainstorm/`, legacy `*-brainstorming/`) is by definition unfinished — the `brainstorm` skill moves folders to `docs/history/brainstorms/` only on a passed harvest. Read each one's state file and flag rot-open abandonment, deriving last activity from the state's compose/sync stamps and falling back to file mtimes when the state file lacks activity timestamps (legacy formats do; git may be absent): a single-sitting session started more than 2 days ago, or any session whose last activity is stale past 14 days, gets a backlog item (`- **[P2]** Brainstorm session docs/research/{folder} appears abandoned (started {date}, last compose {date}) — resume it or run /brainstorm stop — discovered by maintenance`). Where the installed skill ships its detector (v3+), run `node .claude/skills/brainstorm/scripts/detector.mjs <folder>` and include failing rule IDs in the finding. **Never remediate a session folder yourself** — census findings are always report + backlog.
 
@@ -138,31 +138,30 @@ docs/
 ├── architecture/          # Cross-module design + steering layer
 │   │                      #   domain-model, glossary, non-goals, references, open-questions
 │   └── decisions/         # Architecture Decisions (ADs — one per subject, updated in place; journey in each AD's Decision Changelog)
-├── features/              # Feature specs — the only first-class doc unit (flat; ownership computed from each doc's `objects:` and the source headers)
-│   └── {group}/           #   browse-only subfolder for grouping; NEVER a module; may carry a Readme.md
+├── features/              # Feature specs — flat, no subfolders; ownership computed from each doc's `objects:` and the source headers
 ├── operations/            # Setup, development, deployment, CI/CD
 │   └── bookkeeping.md     #   the shared doc-sync work queue (hook-appended, bookkeeper-drained, walled at commit) — author-created, never scaffolded; treat rows as live work, never as drift
-├── research/              # In-progress brainstorm sessions ({topic}-brainstorm/; legacy -brainstorming/) + standing research; Readme.md is the index
+├── research/              # In-progress brainstorm sessions ({topic}-brainstorm/; legacy -brainstorming/) + standing research; the folder name is the topic
 │   └── {topic}-brainstorm/     #   created by the `brainstorm` skill; moves to history/brainstorms/ on a passed harvest
 ├── history/
-│   ├── CHANGELOG.md     ✱ # Master changelog index
+│   ├── CHANGELOG.md     ✱ # The changelog guide — never appended to; listing changelog/ is the index
 │   ├── changelog/         # Individual entries (YYYY-MM-DD-{three-words}.md; written at commit time)
 │   ├── plans/             # Implementation plans (Status field required)
 │   ├── migrations/        # One-shot migration/upgrade runbooks (YYYY-MM-DD-{slug}.md; outcome-stamped then frozen)
-│   ├── journal.md         # Append-only mid-execution knowledge capture (one line per fact; resolves by landing in its owning doc) — author-created, never scaffolded
-│   ├── brainstorms/       # Harvested brainstorm sessions ({topic}/) — user decides kept (committed) or deleted; Readme.md is the index
+│   ├── journal.md         # Queue — mid-execution facts, one line each; a row resolves by landing in its owning doc — author-created, never scaffolded
+│   ├── brainstorms/       # Harvested brainstorm sessions ({topic}/) — user decides kept (committed) or deleted; the folder name is the topic
 │   ├── research/          # Deep-research records ({topic}/ — README.md synthesis + findings.md + sources.md); frozen, cited, owns no code
-│   └── backlog.md       ✱ # Tracked work items by priority (P0-P3)
+│   └── backlog.md       ✱ # Queue — open work by priority (P0-P3); a finished item is deleted
 ├── memory/
 │   └── main.md          ✱ #   plus {agent}.md — project knowledge + per-agent strategy memory
-└── tests/                 # Behavioral test checklists ({feature}.md, step → **Assert**), derived at plan Completion via the `documentation` skill; author-maintained
+└── tests/                 # Behavioral test checklists ({feature}.md, step → **Assert**), written at the verification gate before the driving; the gate that drives one maintains it
 ```
 
 **✱ marks the scaffolded files — the only paths a baseline creates, and the only shape signals.** `docs/structure.md` is not one of them: the installer owns it and rewrites it on every install or refresh, so a missing or hand-edited `structure.md` means the harness needs refreshing (`npx @nurix/etna`), never a scaffold from a template — and its body is never converged, only its `harness-version` field stamped. Every **folder** in this tree is created on first use and is simply absent until it holds a file; git cannot track an empty directory, so a missing folder is never evidence of drift and is never scaffolded to satisfy the shape. Its role is already in `docs/structure.md`; a repo's own notes about legacy folders go in `docs/README.md` § Notes for this repository.
 
 There is **no `docs/routing.md`**, **no `docs/modules/{m}/`**, **no `docs/pillars/`**, **no `docs/boundaries/`**. Code ownership is computed from `objects:` and source headers, with a transitional `owns:` region glob; 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).
 
-> Brainstorm records are **author-created, never scaffolded**; legacy active folders carry the older `-brainstorming/` suffix — treat both spellings as canonical. **Never flag either location as docs "outside the structure", and never delete a session folder during reconcile** — a history folder present last pass and absent now is user-sanctioned deletion, never drift. Keep each folder's `Readme.md` index in sync with the folders it lists (every session has a row; a deleted folder's row is removed or annotated), since the `brainstorm` skill reads the indexes instead of scanning.
+> Brainstorm records are **author-created, never scaffolded**; legacy active folders carry the older `-brainstorming/` suffix — treat both spellings as canonical. **Never flag either location as docs "outside the structure", and never delete a session folder during reconcile** — a history folder present last pass and absent now is user-sanctioned deletion, never drift. No index keeps a row per session: the `brainstorm` skill finds sessions by their folders, so a folder `Readme.md` describes the folder and never needs syncing.
 
 ### Step B1 — Inventory and classify
 
@@ -176,7 +175,7 @@ Detecting and folding old-shape artifacts is what makes a baseline more than a f
 
 | If you find (old shape) | Fold to (current shape) |
 | --- | --- |
-| `*.bkp.*` files under `docs/` (the installer's first-contact backups of the project's pre-existing files) | **fold the content, then delete the backup.** Classify each backup's content by nature and land it in the current shape — a backed-up changelog's rows into `docs/history/CHANGELOG.md` and per-entry files, a backed-up structure/readme's real claims into the scaffolded truth doc, a backed-up feature doc's content merged into its sibling (or adopted whole if the sibling is a pristine seed). Content is folded, never discarded silently; what cannot be classified goes to the backlog with the backup kept. When the fold lands, delete the `.bkp` file |
+| `*.bkp.*` files under `docs/` (the installer's first-contact backups of the project's pre-existing files) | **fold the content, then delete the backup.** Classify each backup's content by nature and land it in the current shape — a backed-up changelog's rows into per-entry files (the changelog guide takes no rows), a backed-up structure/readme's real claims into the scaffolded truth doc, a backed-up feature doc's content merged into its sibling (or adopted whole if the sibling is a pristine seed). Content is folded, never discarded silently; what cannot be classified goes to the backlog with the backup kept. When the fold lands, delete the `.bkp` file |
 | `*.bkp.*` files at the repo root or in config (`CLAUDE.bkp.md`, `.prettierrc.bkp.json`, …) | **never merge these.** Top-level config is harness-owned by design; list each one to the user as their call, and leave the file in place |
 | no `harness-version` in `structure.md` | stamp it (Step B4) |
 | `docs/tests/` checklists carrying **no frontmatter** (the shape before the graph — the genre was exempt) | **backfill `type: checklist` + `verifies:`.** Mechanical where a same-named feature or UX doc exists; where the name does not match, list the checklist to the user with your best candidate and let them confirm. This is the row that upgrades a repo from a tree of files to a graph — without it every checklist in an older repo stays unreachable, and nothing detects that |
@@ -188,14 +187,15 @@ Detecting and folding old-shape artifacts is what makes a baseline more than a f
 
 B2 folds artifacts whose **shape dissolved** — a file in the wrong place or the wrong genre. This step handles the other axis, and it is the one that silently rots a repo that otherwise looks current: a document in the **right folder with the right name** whose *internal* schema is behind. A changelog entry missing three of its seven required fields, a checklist with no `verifies:` edge, a feature doc predating `applies:`, an AD on the old key vocabulary — none of these move a folder, so nothing structural detects them, and a repo can pass every scaffold check while no document in it matches the installed harness.
 
-**Read the schema from the `documentation` skill's templates, never from memory.** The template is the contract; your recollection of it is a version of unknown age. For each genre, take the required frontmatter keys and required sections from the template file itself, then check the repo's documents of that genre against them.
+**Read the schema from the `documentation` skill's genre registry and templates, never from memory.** The registry (`templates/Readme.md`) is the contract for each genre's nature, `type:`, location, required keys and required sections, and the template for everything else; your recollection of either is a version of unknown age. Run `doc-lint` over the tree for the mechanical half — its `required-key`, `section-missing` and `type-unknown` findings are this step's worklist.
 
-**The two natures split the treatment, and the split is absolute.**
+**The three natures split the treatment, and the split is absolute.**
 
 | Nature | Genres | Treatment |
 | --- | --- | --- |
 | **Truth document** | features, ux, architecture, operations, `docs/tests/` checklists, READMEs (never `structure.md`, which the installer owns) | **Converge in place.** These state what is true now, so rewriting them to the current schema is not revision, it is the genre working as designed. Add missing frontmatter keys, add missing required sections, rename keys the template renamed |
-| **Record** | plans, changelog entries, migration runbooks, brainstorm records | **Never rewritten.** A completed plan and a committed entry are frozen — immutability begins at commit, and a record edited to match a newer schema stops being evidence of what happened. Report non-conformance; repair only the **living index** that points at the record (an absent `docs/history/CHANGELOG.md` row is an index defect, not a record defect, and is backfilled with a note saying so) |
+| **Record** | plans, changelog entries, migration runbooks, brainstorm records | **Never rewritten.** A completed plan and a committed entry are frozen — immutability begins at commit, and a record edited to match a newer schema stops being evidence of what happened. Report non-conformance and leave the record alone |
+| **Queue** | backlog, journal, bookkeeping, memory | **Rows are never rewritten to a schema.** A queue changes only by appending a row and deleting a resolved one; converge its header and frontmatter, and leave each row as its writer wrote it |
 
 **Never invent content to satisfy a field.** A frozen changelog entry missing `Skills:` is missing the *judgement* that field carries, and no later session holds it — writing one is fabrication wearing a schema's clothes. Report it, backlog the pattern if it recurs, and leave the entry alone. The same restraint applies to a truth document: a genre's new section that needs knowledge the repo does not contain is raised as a question, not filled with plausible prose.
 
@@ -205,7 +205,7 @@ B2 folds artifacts whose **shape dissolved** — a file in the wrong place or th
 
 Table: `| File | Action | From | To | Reason |` (actions: `Move`, `Merge into {target}`, `Delete`, `Keep`, `Create`, `Fold`). For a fresh baseline this is mostly `Create`; for an upgrade it is mostly `Fold`/`Move`. Ask once: **"Approve this reconcile?"** — you own this interaction (the `documentation` skill is a library and has none).
 
-On approval, execute: create the folder structure; move/fold/merge/delete per the plan; apply B2b's schema convergences to the truth documents (records are reported, never rewritten); add `Status:` to plan files; for each feature doc, derive and write its `owns:` globs (+ `module:` label + `objects:`) from the source it describes, and each checklist's `verifies:` edge, by calling the `documentation` skill's **frontmatter derivation**; merge scattered backlogs into `docs/history/backlog.md`; fix links broken by moves.
+On approval, execute: create the folder structure; move/fold/merge/delete per the plan; apply B2b's schema convergences to the truth documents (records are reported, never rewritten); add `Status:` to plan files; for each feature doc, derive and write its transitional `owns:` region glob (+ `module:` label + `objects:`) from the source it describes, and each checklist's `verifies:` edge, following the `documentation` skill's `references/frontmatter.md`; merge scattered backlogs into `docs/history/backlog.md`; fix links broken by moves.
 
 Scaffold missing mandated files **by calling the `documentation` skill for each template** — you orchestrate, the skill supplies templates: `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/main.md`, `docs/operations/setup.md` (when the repo has a lockfile and a runnable root script; **never a second first-run doc** — propose a rename with a `note:` row if one exists under another name), and the repo-root `README.md` (an outward opening in a user's terms from the charter and vision documents, then orientation and routing filled from the manifests, the ownership index and the root scripts — **never overwrite an existing root README**).
 
@@ -239,7 +239,7 @@ Apply the **§ Strategy memory** retirement procedure to `docs/memory/maintenanc
 - **Enforce the memory cap on every run** (§ Strategy memory) — you are its only writer, so no one else can do it.
 - **A clean report is valid** — do not invent issues.
 - **Declarative, idempotent.** Re-running baseline mode on a current repo reshapes nothing — a second pass is just the audit plus the module proposal. Converge to the current shape; never replay a version ladder; never reconstruct a past shape.
-- **Brownfield extraction (operator-ruled 2026-08-19).** When baseline mode meets a repo with a real source tree and few or no feature docs, the module *proposal* is not enough — run the extraction pass: produce feature docs for the recognized modules (docs/features/, full frontmatter: `objects:` · a transitional `owns:` region glob · `module:` · `status:` · `last-reviewed:` · `type: feature` · `derivation: "extracted (baseline YYYY-MM-DD, nustack graph + source read)"`), plus the architecture, tests, and operations layers. Use the `nustack-graph` skill where installed — localize through the index before reading; the docs record intent, the index answers facts. **Every extracted feature doc carries a `## History & Ownership` section** — top contributors with recency, churn posture, and bus-factor notes, dated "as of YYYY-MM-DD" (operator ruling: this section is mandatory in extraction output even though doc-lint flags dated narrative in truth docs; the findings are accepted for now, and a future harness version may retire the section in favor of live index pointers). `status:` is evidence-graded: `deprecated` only when history shows the area dead, never by guess. Scale by fan-out (one extraction lane per module, a completeness critic over the result) rather than one long cold read.
+- **Brownfield extraction.** When baseline mode meets a repo with a real source tree and few or no feature docs, the module *proposal* is not enough — run the extraction pass: produce feature docs for the recognized modules (`docs/features/`, the feature row of the genre registry: `type: feature` · `description:` · `status:` · `objects:` · `module:` · a transitional `owns:` region glob), plus the architecture, tests, and operations layers. Use the `nustack-graph` skill where installed — localize through the index before reading; the docs record intent, the index answers facts. **Contributors, churn and bus-factor are run-report findings, never document sections**: a dated "as of" section is history in a truth document, and `doc-lint` blocks it. Put them in the run report and, where one needs action, a backlog row. `status:` is evidence-graded: `deprecated` only when history shows the area dead, never by guess. Scale by fan-out (one extraction lane per module, a completeness critic over the result) rather than one long cold read.
 - **Diagrams ride the baseline (operator-ruled 2026-08-24).** Whenever baseline mode produces or converges the architecture layer, draw two ASCII diagrams from the real source, each in its own fenced code block: (1) an **architecture diagram** in the system-design/architecture doc — the actual processes, entry points, and wire surfaces as boxes, the calls/queues/files between them as labelled arrows; (2) a **DB ER diagram** wherever the repo declares a relational schema (DDL, migrations, an ORM schema) — one box per table listing its key columns, FK edges drawn to the table they reference, cardinality on the edge; it lands in the domain-model doc, or `docs/architecture/data-model.md` when none exists. Box-drawing characters (`┌─┐│└┘├┤`), width ≤ 100 columns. Derived only from what the code declares — a diagram never invents a component the source does not show, and a repo with no relational schema gets **no** ER diagram rather than an imagined one. Diagrams are truth-document sections: later baselines and audits converge them in place like any other section.
 - **Tool tiers.** The SessionStart context names each manifest-declared tool with its tier; calibrate the run to it, never stall on it. **Present-fresh** (`Tool: nustack 0.9.0`): use it — localize every question through `nustack graph` before reading source, and never run an index step first: the family re-indexes a stale store before it answers, so the only freshness decision left is the deliberate `--no-refresh`. **Present-stale** (below the catalog minimum): still use it, but note the version gap and the upgrade command in the run report — a stale contract may lack answer shapes the skill assumes. **Absent** (`Tool: nustack MISSING`): fall back to the cold method (Glob/Grep/read), state in the run report that the tool was absent and give the install command — degraded output is acceptable, silent degradation is not.
 - **One sentinel.** `docs/structure.md` `harness-version` is the only baseline/version marker.

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

@@ -19,6 +19,10 @@ run at the start of every dispatch and again before you return:
 node <skill>/scripts/detector.mjs <session-folder> [--gate=manifest|move] [--json]
 ```
 
+A real run always prints per-rule lines and a `clean`/`failing` summary (or a usage/error
+message). **Empty output is not a clean run — it means the detector never executed**; treat it
+as a failed gate and report it, never as a pass.
+
 ## The write protocol you enforce
 
 One writer per file. You write `state.md`, `thesis.md`, `forks.md`, `ledger.md`, `fragments/`,
@@ -116,8 +120,8 @@ Stop is facilitator-orchestrated because approval belongs to the user; you execu
    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.
 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
+   `docs/history/brainstorms/{topic}/`, set state `Status: harvested` (no index row to move: the folder is
+   the record). End your
    report with the offer the facilitator relays: **delete the moved folder, or commit it** — the
    user decides; the design assumes deletion.
 

package/data/harnesses/code/codex/agents/lld-mode.toml

@@ -17,7 +17,7 @@ Map the documentation landscape — what exists, what is adjacent, how detailed
 2. Locate the repo's feature-doc layer from `structure.md` — the standard shape is `./docs/features/`, but a repo may document components under their own subject folders. Read that layer's index if it has one; otherwise glob for docs carrying `owns:` frontmatter
 3. If `./docs/memory/lld-mode.md` exists (or the legacy `./docs/memory/spec-mode.md`), read it for feature doc inventory, ownership conflict zones, and lessons from previous research
 4. Read 1-2 existing feature LLDs from that layer to calibrate format and depth
-5. Consult the **injected ownership index** (the generated `glob → doc · module · objects · status` map — computed from source headers and the transitional `owns:` region globs) to build the ownership map. It is the source of truth for what code paths are already spoken for; a source file's path header names its document directly. If the index isn't present in context, glob the docs tree (excluding `docs/history/`) and read the `owns:` frontmatter of every doc that declares it.
+5. Consult the **injected ownership index** (the generated `glob → doc · module · objects · status` map, built from the transitional `owns:` region globs; a source file's path header names its document directly) to build the ownership map. It is the source of truth for what code paths are already spoken for; a source file's path header names its document directly. If the index isn't present in context, glob the docs tree (excluding `docs/history/`) and read the `owns:` frontmatter of every doc that declares it.
 
 ## What You Research
 
@@ -42,7 +42,7 @@ Structure your findings as:
 - **Invalidated claims**: One row per existing doc this feature makes wrong — doc path, the claim, why it stops being true. This list seeds the plan's **Doc Obligations** ledger, so it is the research finding most likely to survive into an artifact; "none" is a real answer and says the feature is genuinely additive.
 - **Risks or concerns**: Anything the LLD should address or call out
 
-Structure your findings by the `documentation` skill's style guide — imperative voice, function signatures over implementations, mermaid for flows.
+Write each finding as a bold noun-phrase label and one or two third-person sentences (the `documentation` skill's `references/style-guide.md` § Labels, § Voice); mermaid for a flow worth drawing. Paths, symbols and routes belong in these findings because the author needs them, but these fields are research, not the LLD's sections: the feature doc takes its template's sections and names objects and promises, never the functions listed here.
 
 ## Rules
 

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

@@ -61,7 +61,8 @@ Across the header pointers and the transitional globs:
 - **Transitional globs:** verify each matches existing files; report globs matching nothing, deleted paths, and orphaned docs. A file-level `owns:` list is reduced to its region globs (remediation, not a question); the files it dropped are reported where their headers name no document.
 - **Retired keys:** `applies:` and `keywords:` are removed wherever found (remediation); a doctrine the removed `applies:` named stays named in the document's Scope section.
 - Flag **equal-specificity overlaps** — two feature docs whose transitional `owns:` globs claim the same paths at the same specificity (an ambiguous owner). `node .claude/hooks/check-ownership.mjs` reports these mechanically alongside dead globs (`overlaps()` in `lib/ownership.mjs`); a glob at strictly higher specificity carving out of a broader `**` is the designed layering and is never flagged. Surface a real overlap as a question — narrowing someone's glob is an author's call, not remediation.
-- **Stamp `type:` where missing.** Every doc carries a `type:` genre key (enum = the `documentation` skill's template names); docs predating the key are stamped mechanically — the genre is readable from placement and shape (a `docs/features/` doc is `type: feature`, an AD is `type: architecture-decision`). Stamping is remediation, not a question; an ambiguous genre is backlogged instead.
+- **Stamp `type:` where missing.** Every doc carries a `type:` genre key (values = the `type:` column of the `documentation` skill's genre registry, `templates/Readme.md`); docs predating the key are stamped mechanically — the genre is readable from placement and shape (a `docs/features/` doc is `type: feature`, an AD is `type: architecture-decision`). Stamping is remediation, not a question; an ambiguous genre is backlogged instead.
+- **Write `description:` where missing.** Every truth document and folder index carries a `description:` of at most 300 characters saying what it settles and where its boundary sits (`documentation` skill, `references/frontmatter.md` § `description:`). Each one is written from a read of the document, never from its filename — many documents ⇒ parallel sub-agents on the cheapest capable tier, one batch each. A folder index that names its files or records is rewritten to describe the folder, after confirming every per-file fact it carried lives in that file.
 
 **Then validate the doc→doc edge.** `node .claude/hooks/check-ownership.mjs` and the session-injected **doc edge index** carry `verifies:` and its generated inverse; read the edge index and check two things:
 
@@ -98,7 +99,7 @@ Run `git log --since="2 weeks ago" --name-only --pretty=format:"%h %s"` to find
 
 **Architecture drift.** Grep `docs/architecture/` for file-path references. Verify referenced paths still exist. Remove or update stale references.
 
-**Backlog health.** Read `docs/history/backlog.md`. Report items older than 30 days. Count pending by priority.
+**Backlog health.** Read `docs/history/backlog.md`, a queue whose rows carry no dates. Count pending by priority, and report items that name a path, plan or document that no longer exists — their work landed or their subject left, and the row is the user's to delete.
 
 **Brainstorm session census.** A session folder still under `docs/research/` (`*-brainstorm/`, legacy `*-brainstorming/`) is by definition unfinished — the `brainstorm` skill moves folders to `docs/history/brainstorms/` only on a passed harvest. Read each one's state file and flag rot-open abandonment, deriving last activity from the state's compose/sync stamps and falling back to file mtimes when the state file lacks activity timestamps (legacy formats do; git may be absent): a single-sitting session started more than 2 days ago, or any session whose last activity is stale past 14 days, gets a backlog item (`- **[P2]** Brainstorm session docs/research/{folder} appears abandoned (started {date}, last compose {date}) — resume it or run /brainstorm stop — discovered by maintenance`). Where the installed skill ships its detector (v3+), run `node .claude/skills/brainstorm/scripts/detector.mjs <folder>` and include failing rule IDs in the finding. **Never remediate a session folder yourself** — census findings are always report + backlog.
 
@@ -135,31 +136,30 @@ docs/
 ├── architecture/          # Cross-module design + steering layer
 │   │                      #   domain-model, glossary, non-goals, references, open-questions
 │   └── decisions/         # Architecture Decisions (ADs — one per subject, updated in place; journey in each AD's Decision Changelog)
-├── features/              # Feature specs — the only first-class doc unit (flat; ownership computed from each doc's `objects:` and the source headers)
-│   └── {group}/           #   browse-only subfolder for grouping; NEVER a module; may carry a Readme.md
+├── features/              # Feature specs — flat, no subfolders; ownership computed from each doc's `objects:` and the source headers
 ├── operations/            # Setup, development, deployment, CI/CD
 │   └── bookkeeping.md     #   the shared doc-sync work queue (hook-appended, bookkeeper-drained, walled at commit) — author-created, never scaffolded; treat rows as live work, never as drift
-├── research/              # In-progress brainstorm sessions ({topic}-brainstorm/; legacy -brainstorming/) + standing research; Readme.md is the index
+├── research/              # In-progress brainstorm sessions ({topic}-brainstorm/; legacy -brainstorming/) + standing research; the folder name is the topic
 │   └── {topic}-brainstorm/     #   created by the `brainstorm` skill; moves to history/brainstorms/ on a passed harvest
 ├── history/
-│   ├── CHANGELOG.md     ✱ # Master changelog index
+│   ├── CHANGELOG.md     ✱ # The changelog guide — never appended to; listing changelog/ is the index
 │   ├── changelog/         # Individual entries (YYYY-MM-DD-{three-words}.md; written at commit time)
 │   ├── plans/             # Implementation plans (Status field required)
 │   ├── migrations/        # One-shot migration/upgrade runbooks (YYYY-MM-DD-{slug}.md; outcome-stamped then frozen)
-│   ├── journal.md         # Append-only mid-execution knowledge capture (one line per fact; resolves by landing in its owning doc) — author-created, never scaffolded
-│   ├── brainstorms/       # Harvested brainstorm sessions ({topic}/) — user decides kept (committed) or deleted; Readme.md is the index
+│   ├── journal.md         # Queue — mid-execution facts, one line each; a row resolves by landing in its owning doc — author-created, never scaffolded
+│   ├── brainstorms/       # Harvested brainstorm sessions ({topic}/) — user decides kept (committed) or deleted; the folder name is the topic
 │   ├── research/          # Deep-research records ({topic}/ — README.md synthesis + findings.md + sources.md); frozen, cited, owns no code
-│   └── backlog.md       ✱ # Tracked work items by priority (P0-P3)
+│   └── backlog.md       ✱ # Queue — open work by priority (P0-P3); a finished item is deleted
 ├── memory/
 │   └── main.md          ✱ #   plus {agent}.md — project knowledge + per-agent strategy memory
-└── tests/                 # Behavioral test checklists ({feature}.md, step → **Assert**), derived at plan Completion via the `documentation` skill; author-maintained
+└── tests/                 # Behavioral test checklists ({feature}.md, step → **Assert**), written at the verification gate before the driving; the gate that drives one maintains it
 ```
 
 **✱ marks the scaffolded files — the only paths a baseline creates, and the only shape signals.** `docs/structure.md` is not one of them: the installer owns it and rewrites it on every install or refresh, so a missing or hand-edited `structure.md` means the harness needs refreshing (`npx @nurix/etna`), never a scaffold from a template — and its body is never converged, only its `harness-version` field stamped. Every **folder** in this tree is created on first use and is simply absent until it holds a file; git cannot track an empty directory, so a missing folder is never evidence of drift and is never scaffolded to satisfy the shape. Its role is already in `docs/structure.md`; a repo's own notes about legacy folders go in `docs/README.md` § Notes for this repository.
 
 There is **no `docs/routing.md`**, **no `docs/modules/{m}/`**, **no `docs/pillars/`**, **no `docs/boundaries/`**. Code ownership is computed from `objects:` and source headers, with a transitional `owns:` region glob; 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).
 
-> Brainstorm records are **author-created, never scaffolded**; legacy active folders carry the older `-brainstorming/` suffix — treat both spellings as canonical. **Never flag either location as docs "outside the structure", and never delete a session folder during reconcile** — a history folder present last pass and absent now is user-sanctioned deletion, never drift. Keep each folder's `Readme.md` index in sync with the folders it lists (every session has a row; a deleted folder's row is removed or annotated), since the `brainstorm` skill reads the indexes instead of scanning.
+> Brainstorm records are **author-created, never scaffolded**; legacy active folders carry the older `-brainstorming/` suffix — treat both spellings as canonical. **Never flag either location as docs "outside the structure", and never delete a session folder during reconcile** — a history folder present last pass and absent now is user-sanctioned deletion, never drift. No index keeps a row per session: the `brainstorm` skill finds sessions by their folders, so a folder `Readme.md` describes the folder and never needs syncing.
 
 ### Step B1 — Inventory and classify
 
@@ -173,7 +173,7 @@ Detecting and folding old-shape artifacts is what makes a baseline more than a f
 
 | If you find (old shape) | Fold to (current shape) |
 | --- | --- |
-| `*.bkp.*` files under `docs/` (the installer's first-contact backups of the project's pre-existing files) | **fold the content, then delete the backup.** Classify each backup's content by nature and land it in the current shape — a backed-up changelog's rows into `docs/history/CHANGELOG.md` and per-entry files, a backed-up structure/readme's real claims into the scaffolded truth doc, a backed-up feature doc's content merged into its sibling (or adopted whole if the sibling is a pristine seed). Content is folded, never discarded silently; what cannot be classified goes to the backlog with the backup kept. When the fold lands, delete the `.bkp` file |
+| `*.bkp.*` files under `docs/` (the installer's first-contact backups of the project's pre-existing files) | **fold the content, then delete the backup.** Classify each backup's content by nature and land it in the current shape — a backed-up changelog's rows into per-entry files (the changelog guide takes no rows), a backed-up structure/readme's real claims into the scaffolded truth doc, a backed-up feature doc's content merged into its sibling (or adopted whole if the sibling is a pristine seed). Content is folded, never discarded silently; what cannot be classified goes to the backlog with the backup kept. When the fold lands, delete the `.bkp` file |
 | `*.bkp.*` files at the repo root or in config (`CLAUDE.bkp.md`, `.prettierrc.bkp.json`, …) | **never merge these.** Top-level config is harness-owned by design; list each one to the user as their call, and leave the file in place |
 | no `harness-version` in `structure.md` | stamp it (Step B4) |
 | `docs/tests/` checklists carrying **no frontmatter** (the shape before the graph — the genre was exempt) | **backfill `type: checklist` + `verifies:`.** Mechanical where a same-named feature or UX doc exists; where the name does not match, list the checklist to the user with your best candidate and let them confirm. This is the row that upgrades a repo from a tree of files to a graph — without it every checklist in an older repo stays unreachable, and nothing detects that |
@@ -185,14 +185,15 @@ Detecting and folding old-shape artifacts is what makes a baseline more than a f
 
 B2 folds artifacts whose **shape dissolved** — a file in the wrong place or the wrong genre. This step handles the other axis, and it is the one that silently rots a repo that otherwise looks current: a document in the **right folder with the right name** whose *internal* schema is behind. A changelog entry missing three of its seven required fields, a checklist with no `verifies:` edge, a feature doc predating `applies:`, an AD on the old key vocabulary — none of these move a folder, so nothing structural detects them, and a repo can pass every scaffold check while no document in it matches the installed harness.
 
-**Read the schema from the `documentation` skill's templates, never from memory.** The template is the contract; your recollection of it is a version of unknown age. For each genre, take the required frontmatter keys and required sections from the template file itself, then check the repo's documents of that genre against them.
+**Read the schema from the `documentation` skill's genre registry and templates, never from memory.** The registry (`templates/Readme.md`) is the contract for each genre's nature, `type:`, location, required keys and required sections, and the template for everything else; your recollection of either is a version of unknown age. Run `doc-lint` over the tree for the mechanical half — its `required-key`, `section-missing` and `type-unknown` findings are this step's worklist.
 
-**The two natures split the treatment, and the split is absolute.**
+**The three natures split the treatment, and the split is absolute.**
 
 | Nature | Genres | Treatment |
 | --- | --- | --- |
 | **Truth document** | features, ux, architecture, operations, `docs/tests/` checklists, READMEs (never `structure.md`, which the installer owns) | **Converge in place.** These state what is true now, so rewriting them to the current schema is not revision, it is the genre working as designed. Add missing frontmatter keys, add missing required sections, rename keys the template renamed |
-| **Record** | plans, changelog entries, migration runbooks, brainstorm records | **Never rewritten.** A completed plan and a committed entry are frozen — immutability begins at commit, and a record edited to match a newer schema stops being evidence of what happened. Report non-conformance; repair only the **living index** that points at the record (an absent `docs/history/CHANGELOG.md` row is an index defect, not a record defect, and is backfilled with a note saying so) |
+| **Record** | plans, changelog entries, migration runbooks, brainstorm records | **Never rewritten.** A completed plan and a committed entry are frozen — immutability begins at commit, and a record edited to match a newer schema stops being evidence of what happened. Report non-conformance and leave the record alone |
+| **Queue** | backlog, journal, bookkeeping, memory | **Rows are never rewritten to a schema.** A queue changes only by appending a row and deleting a resolved one; converge its header and frontmatter, and leave each row as its writer wrote it |
 
 **Never invent content to satisfy a field.** A frozen changelog entry missing `Skills:` is missing the *judgement* that field carries, and no later session holds it — writing one is fabrication wearing a schema's clothes. Report it, backlog the pattern if it recurs, and leave the entry alone. The same restraint applies to a truth document: a genre's new section that needs knowledge the repo does not contain is raised as a question, not filled with plausible prose.
 
@@ -202,7 +203,7 @@ B2 folds artifacts whose **shape dissolved** — a file in the wrong place or th
 
 Table: `| File | Action | From | To | Reason |` (actions: `Move`, `Merge into {target}`, `Delete`, `Keep`, `Create`, `Fold`). For a fresh baseline this is mostly `Create`; for an upgrade it is mostly `Fold`/`Move`. Ask once: **"Approve this reconcile?"** — you own this interaction (the `documentation` skill is a library and has none).
 
-On approval, execute: create the folder structure; move/fold/merge/delete per the plan; apply B2b's schema convergences to the truth documents (records are reported, never rewritten); add `Status:` to plan files; for each feature doc, derive and write its `owns:` globs (+ `module:` label + `objects:`) from the source it describes, and each checklist's `verifies:` edge, by calling the `documentation` skill's **frontmatter derivation**; merge scattered backlogs into `docs/history/backlog.md`; fix links broken by moves.
+On approval, execute: create the folder structure; move/fold/merge/delete per the plan; apply B2b's schema convergences to the truth documents (records are reported, never rewritten); add `Status:` to plan files; for each feature doc, derive and write its transitional `owns:` region glob (+ `module:` label + `objects:`) from the source it describes, and each checklist's `verifies:` edge, following the `documentation` skill's `references/frontmatter.md`; merge scattered backlogs into `docs/history/backlog.md`; fix links broken by moves.
 
 Scaffold missing mandated files **by calling the `documentation` skill for each template** — you orchestrate, the skill supplies templates: `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/main.md`, `docs/operations/setup.md` (when the repo has a lockfile and a runnable root script; **never a second first-run doc** — propose a rename with a `note:` row if one exists under another name), and the repo-root `README.md` (an outward opening in a user's terms from the charter and vision documents, then orientation and routing filled from the manifests, the ownership index and the root scripts — **never overwrite an existing root README**).
 
@@ -236,7 +237,7 @@ Apply the **§ Strategy memory** retirement procedure to `docs/memory/maintenanc
 - **Enforce the memory cap on every run** (§ Strategy memory) — you are its only writer, so no one else can do it.
 - **A clean report is valid** — do not invent issues.
 - **Declarative, idempotent.** Re-running baseline mode on a current repo reshapes nothing — a second pass is just the audit plus the module proposal. Converge to the current shape; never replay a version ladder; never reconstruct a past shape.
-- **Brownfield extraction (operator-ruled 2026-08-19).** When baseline mode meets a repo with a real source tree and few or no feature docs, the module *proposal* is not enough — run the extraction pass: produce feature docs for the recognized modules (docs/features/, full frontmatter: `objects:` · a transitional `owns:` region glob · `module:` · `status:` · `last-reviewed:` · `type: feature` · `derivation: "extracted (baseline YYYY-MM-DD, nustack graph + source read)"`), plus the architecture, tests, and operations layers. Use the `nustack-graph` skill where installed — localize through the index before reading; the docs record intent, the index answers facts. **Every extracted feature doc carries a `## History & Ownership` section** — top contributors with recency, churn posture, and bus-factor notes, dated "as of YYYY-MM-DD" (operator ruling: this section is mandatory in extraction output even though doc-lint flags dated narrative in truth docs; the findings are accepted for now, and a future harness version may retire the section in favor of live index pointers). `status:` is evidence-graded: `deprecated` only when history shows the area dead, never by guess. Scale by fan-out (one extraction lane per module, a completeness critic over the result) rather than one long cold read.
+- **Brownfield extraction.** When baseline mode meets a repo with a real source tree and few or no feature docs, the module *proposal* is not enough — run the extraction pass: produce feature docs for the recognized modules (`docs/features/`, the feature row of the genre registry: `type: feature` · `description:` · `status:` · `objects:` · `module:` · a transitional `owns:` region glob), plus the architecture, tests, and operations layers. Use the `nustack-graph` skill where installed — localize through the index before reading; the docs record intent, the index answers facts. **Contributors, churn and bus-factor are run-report findings, never document sections**: a dated "as of" section is history in a truth document, and `doc-lint` blocks it. Put them in the run report and, where one needs action, a backlog row. `status:` is evidence-graded: `deprecated` only when history shows the area dead, never by guess. Scale by fan-out (one extraction lane per module, a completeness critic over the result) rather than one long cold read.
 - **Diagrams ride the baseline (operator-ruled 2026-08-24).** Whenever baseline mode produces or converges the architecture layer, draw two ASCII diagrams from the real source, each in its own fenced code block: (1) an **architecture diagram** in the system-design/architecture doc — the actual processes, entry points, and wire surfaces as boxes, the calls/queues/files between them as labelled arrows; (2) a **DB ER diagram** wherever the repo declares a relational schema (DDL, migrations, an ORM schema) — one box per table listing its key columns, FK edges drawn to the table they reference, cardinality on the edge; it lands in the domain-model doc, or `docs/architecture/data-model.md` when none exists. Box-drawing characters (`┌─┐│└┘├┤`), width ≤ 100 columns. Derived only from what the code declares — a diagram never invents a component the source does not show, and a repo with no relational schema gets **no** ER diagram rather than an imagined one. Diagrams are truth-document sections: later baselines and audits converge them in place like any other section.
 - **Tool tiers.** The SessionStart context names each manifest-declared tool with its tier; calibrate the run to it, never stall on it. **Present-fresh** (`Tool: nustack 0.9.0`): use it — localize every question through `nustack graph` before reading source, and never run an index step first: the family re-indexes a stale store before it answers, so the only freshness decision left is the deliberate `--no-refresh`. **Present-stale** (below the catalog minimum): still use it, but note the version gap and the upgrade command in the run report — a stale contract may lack answer shapes the skill assumes. **Absent** (`Tool: nustack MISSING`): fall back to the cold method (Glob/Grep/read), state in the run report that the tool was absent and give the install command — degraded output is acceptable, silent degradation is not.
 - **One sentinel.** `docs/structure.md` `harness-version` is the only baseline/version marker.

package/data/harnesses/code/docs/README.md

@@ -1,28 +1,20 @@
-# Project Documentation
-
-Technical documentation for this project.
-
-> For documentation organization, authority map, and folder rules, see **[structure.md](structure.md)**.
-
+---
+type: docs-readme
+description: "The documentation tree: what each folder under docs/ holds, who reads it and how its files are named. structure.md is the placement authority."
 ---
 
-## Quick Links
-
-| Document                  | Description                         |
-| ------------------------- | ----------------------------------- |
-| [Structure](structure.md) | Documentation entry point and rules |
+# Project Documentation
 
----
+**Goal:** where to look in `docs/`, folder by folder. Placement rules and the full folder map are [structure.md](structure.md).
 
 ## History
 
-The records — everything dated, frozen, or append-only.
+[history/](history/) holds the records and queues: `plans/` (one dated plan per unit of work, frozen at completion), `changelog/` (one entry per unit of work; [CHANGELOG.md](history/CHANGELOG.md) explains how to read it), and [backlog.md](history/backlog.md), the queue of open work, where a finished item is deleted.
 
-- [CHANGELOG.md](history/CHANGELOG.md) - Master changelog index
-- [backlog.md](history/backlog.md) - Open work items and technical debt — a drain queue; done items are deleted
+## Memory
 
----
+[memory/](memory/) holds project memory in `main.md` and one strategy file per agent that keeps one.
 
 ## Contributing
 
-See [CLAUDE.md](../CLAUDE.md) for documentation guidelines.
+[CLAUDE.md](../CLAUDE.md) carries the documentation workflow.

package/data/harnesses/code/docs/history/CHANGELOG.md

@@ -1,26 +1,27 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
+---
+type: changelog-guide
+description: "How this project's changelog works: one entry per unit of work under changelog/, what each entry records, when one is owed, and how to read the folder."
+---
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+# Changelog
 
----
+**Goal:** what changed in this project, and how it was refined, one entry per unit of work.
 
-## [Unreleased]
+## Entries
 
----
+- **Location:** `changelog/YYYY-MM-DD-{three-words}.md`, one file per unit of work; the three words name the work, not the commit.
+- **Summary line:** each entry opens `# {date} · {surface} — {one-line outcome}`, the line a reader scans.
+- **Content:** the ask in the user's words, what was rejected, which skills held, what changed and what running it taught (the `documentation` skill's `templates/changelog-entry.md`).
+- **Lifecycle:** a draft until its commit; frozen from then on. A correction is a new entry that links back.
 
-## How to Update This Changelog
+## Owed entries
 
-1. Create a dated change file in `docs/history/changelog/`:
-   `docs/history/changelog/YYYY-MM-DD-feature-name.md`
+- **Plan completion:** a draft entry, written when the plan reaches `Status: Complete`.
+- **Commit:** every non-exempt commit carries its entry inside it (the `changelog` rule lists the exemptions).
 
-2. Update this CHANGELOG.md with a high-level summary linking to the detail file
+## Reading the changelog
 
-3. Follow Keep a Changelog categories:
-   - **Added** for new features
-   - **Changed** for changes in existing functionality
-   - **Deprecated** for soon-to-be removed features
-   - **Removed** for now removed features
-   - **Fixed** for bug fixes
-   - **Security** for security improvements
+- **Newest first:** `ls -r changelog/`
+- **One line per entry:** `grep -m1 -H '^# ' changelog/*.md`
+- **One surface:** `grep -l '· {surface} —' changelog/*.md`
+- **Distilled lessons:** the `retro` agent turns accumulated entries into a punch list on demand.