@nurix/etna 0.20.35 → 0.20.37

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

@@ -4,7 +4,7 @@ This file is the authority on **what belongs where** in `docs/`: the folder map,
 
 **This file is the harness's, not the project's.** The installer writes it on every install and refresh, so nothing in it describes one repository: a folder a repo does not use is simply absent on disk, and a repo's own notes — legacy folders kept as provenance, retired genres, local exceptions — live in [`README.md`](README.md) § Notes for this repository, never here. Hand edits are overwritten on the next refresh. The one field written in place is `harness-version` in the frontmatter, stamped by the `maintenance` agent after its baseline reconcile; its absence is what tells a session the repo has not been baselined against the installed harness.
 
-One canonical source per topic — link, don't copy. Only `CLAUDE.md`, `AGENTS.md`, and `README.md` live at the repo root.
+One canonical source per topic — link, don't copy. Only `CLAUDE.md`, `AGENTS.md`, and `README.md` live at the repo root. Every per-genre fact this file does not need for placement — a genre's nature, its `type:` value, its required keys and sections — is the `documentation` skill's genre registry (`templates/Readme.md`), and `doc-lint` checks documents against it.
 
 ---
 
@@ -23,8 +23,8 @@ docs/
 │   ├── common/            # The enterprise plane — one `{concern}.md` per concern the platform handles
 │   │                      #   the same way everywhere. Owns no code
 │   └── decisions/         # ADs — `AD-NNN-{slug}.md`, one per subject, updated in place; the journey lives in
-│                          #   each file's Decision Changelog tail. Readme.md is the register: the current
-│                          #   decision per subject and whether it is built
+│                          #   each file's Decision Changelog tail. Each AD's `description:` and `status:` say
+│                          #   what it decides and whether it stands; Readme.md describes the folder, never a row per AD
 ├── features/              # Feature docs — `{feature}.md`, one per thing a person points at (an address, a command
 │                          #   family, a named control), cut by its objects (flat, no subfolders). One of three owning genres, beside
 │                          #   `architecture/packages/` and `architecture/systems/`; ownership is computed from `objects:` and source headers
@@ -32,7 +32,7 @@ docs/
 ├── operations/            # Procedures — `setup.md` (the one-time first run, incl. the stack), then development, deployment, signing, rotation, diagnostics;
 │   │                      #   one topic-named `{procedure}.md` each. Also holds bookkeeping.md, the shared
 │   │                      #   doc-sync work queue (hook-appended, bookkeeper-drained, a drained row deleted)
-│   ├── release-notes/     # One operator-facing note per release (`YYYY-MM-DD-vX.Y.Z.md`); its README.md indexes them
+│   ├── release-notes/     # One operator-facing note per release (`YYYY-MM-DD-vX.Y.Z.md`); listing the folder is the index
 │   ├── issues/            # Local-tracker issue records (`type: issue`, `YYYY-MM-DD-{slug}.md`) — the
 │   │                      #   `issue-bridge` skill's local pack; `status:` is the lifecycle
 │   └── triage/            # Triage dossiers (`type: triage`, `YYYY-MM-DD-{slug}.md`) — one per investigated
@@ -40,41 +40,42 @@ docs/
 ├── tests/                 # Behavioral test checklists (truth docs) — `{feature}.md`, step → **Assert**, named for
 │                          #   the doc whose promises it proves. `ls docs/tests/` is the roster
 ├── research/              # Records — in-progress brainstorm sessions (`{topic}-brainstorm/`), standing-research
-│                          #   folders (`{topic}/`) and loose standing-research notes (`{topic}.md`). Readme.md is the index
+│                          #   folders (`{topic}/`) and loose standing-research notes (`{topic}.md`). The folder name is the topic
 ├── history/
-│   ├── CHANGELOG.md       # Master changelog index
+│   ├── CHANGELOG.md       # The changelog guide: how entries are named, owed and read. Never appended to
 │   ├── changelog/         # Individual changelog entries, `YYYY-MM-DD-{three-words}.md` (frozen at commit)
 │   ├── plans/             # Dated implementation plans, `YYYY-MM-DD-{slug}.md` (Status: field; Complete/Abandoned = frozen)
 │   ├── migrations/        # One-shot migration runbooks, `YYYY-MM-DD-{slug}.md` — authored ahead, outcome-stamped, frozen
-│   ├── brainstorms/       # Harvested brainstorm sessions (`{topic}/`), kept as provenance; Readme.md is the index
+│   ├── brainstorms/       # Harvested brainstorm sessions (`{topic}/`), kept as provenance; the folder name is the topic
 │   ├── research/          # Deep-research records (`{topic}/` — README.md synthesis + findings.md + sources.md).
 │   │                      #   Frozen, cited, owns no code. Distinct from research/ at the docs root
 │   ├── health-log.md      # The maintenance agent's append-only pass record, one generated row per pass
-│   ├── journal.md         # Append-only mid-execution knowledge capture, one line per fact; a line resolves by
-│   │                      #   landing in its owning doc (delete the row, cite it in the changelog entry)
-│   └── backlog.md         # Tracked work items by priority (P0–P3)
-└── memory/                # Project knowledge + per-agent strategy memory
+│   ├── journal.md         # Queue — mid-execution facts, one line each; a line resolves by landing in its owning
+│   │                      #   doc (delete the row, cite it in the changelog entry)
+│   └── backlog.md         # Queue — open work by priority (P0–P3); a finished item is deleted
+└── memory/                # Queues — project knowledge + per-agent strategy memory, compacted by their writers
     ├── main.md            # Main-agent project memory
     └── {agent}.md         # One strategy-memory file per sub-agent that keeps one
 ```
 
 ## Doctrine every genre follows
 
+- **Every document has one of three natures.** A **truth** document states what is true now and is rewritten in place, present tense, with no history in its body. A **record** states what happened, is dated, and is frozen at its terminal status. A **queue** holds work not done yet: rows are appended and deleted when resolved, and nothing else is edited — the backlog, the journal, the bookkeeping queue and `memory/`. Which genre has which nature is the genre registry's; the folders below follow it, with `history/` holding records and two queues.
+- **No index keeps a row per file.** A folder's `Readme.md` describes what the folder holds and how its files are named; each file's `description:` is its own account, and listing the folder is the roster. Nothing appends to an index when a sibling file is added — not the changelog guide, not a decisions, research, brainstorms or release-notes folder.
 - **`docs/architecture/`** is the design layer in four folders: **`packages/`** (one per project package — what it is and how it behaves), **`systems/`** (one per machine spanning packages), **`common/`** (the enterprise plane) and **`decisions/`** (the ADs, one per subject, updated in place, each journey confined to that file's Decision Changelog tail).
   **`common/` and `decisions/` own no code; `packages/` and `systems/` do.** Ownership is computed, not positional and not typed: a document names the objects it designs in `objects:`, each source file's path header names the document that speaks for it, and the object closure links the two; the more specific claim wins — a feature's beats a system's, a system's beats a package's. Until the ownership scan switches to those edges it reads a transitional `owns:` region glob on each of the three owning genres (the `documentation` skill's `references/frontmatter.md`). **A package document is the residual owner of its tree**, so a package's exhaustive behavior spec is that document, not a feature doc.
   **What earns which genre.** A project package earns a `packages/` document — one, always. A machine whose parts sit in several packages, which a reader asks about as one thing, earns a `systems/` document. A **feature** document exists for something a person points at — an address, a command family, a named control — and is cut by the objects it designs, never by the code's routers, tables, plans or packages; a machine nobody navigates to is a `systems/` document even when it owns tables, and a fragment whose central object is declared in a sibling merges into it. A concern handled the same way everywhere is `common/` and owns nothing — including the governing-decisions register (fixed product decisions `F-###`, baseline defaults `B-###`, external boundaries, out-of-scope), which is authored doctrine the `boundary` skill never persists to.
 - **`history/research/` is not legacy — it is the installed deep-research genre**, one `{topic}/` folder per research pass in the three-file shape. A record is frozen and cited, owns no code, and is never edited to stay current; a new question gets a new topic folder. Entries that predate the three-file convention — a single file or a single-report folder — are kept as authored.
 - **`docs/features/` is flat — every feature authority is a file, and no subfolder exists.** A subject too large for one file is two files, not a folder: `objects:` and the source headers already state authority, and a nested doc is one the ownership scan and the index rows reach last.
-- **`docs/research/`** holds records, not authorities: its standing-research folders and loose notes ground plans and decisions, and its `Readme.md` lists every folder so the `brainstorm` skill reads it instead of scanning.
+- **`docs/research/`** holds records, not authorities: its standing-research folders and loose notes ground plans and decisions. The `brainstorm` skill finds a session by its folder name.
 - **`docs/tests/`** holds behavioral test checklists — one `{feature}.md` per surface, written as `- [ ] step` → `- [ ] **Assert**` (how to verify a feature's promised behavior). A checklist is written or updated **at the verification gate, before the driving** — it is the script the real surface is driven against and the menu the pinned suite tests are drawn from, so each behavior section closes with a `> Pinned:` line naming the test that guards it, `driven only` with the reason, or `none yet` with the test it owes. **No section carries a date** — the *event* of driving (its date, environment, evidence, a `FAIL` and the backlog item it raised) belongs to the changelog entry of the unit that drove it. A section a drive cannot reach says `not reachable — {what blocks it}` on its trace line until the blocker is gone. **The gate that drives a checklist maintains it** — retiring dead sections and repairing traces is part of the run, because a checklist owns no code and no ownership glob implicates it. The cross-system testing strategy is doctrine in `architecture/common/`. A checklist carries `type: checklist` plus `verifies:`, the doc(s) whose promises it proves; a target is legitimately a feature, a package or a system document, and several values are correct where one checklist proves promises two docs decide.
   **`verifies:` is the load-bearing key, and the filename convention is not a substitute for it.** A same-named file is a coincidence no resolver can trust — it breaks the moment a checklist spans two docs or a feature is renamed. The inverse — which checklists cover a feature — is **generated, never listed in the feature doc**.
 - **`docs/operations/bookkeeping.md`** is the shared doc-sync work queue — hooks append rows, the `bookkeeper` agent drains them, and the commit wall blocks while rows remain. It is **author-created, never scaffolded**, and its rows are **live work, never drift**: a drained row is deleted, so a fully drained file holds no rows at all. Read a waiver's referent before deleting it; deleting the record while the condition survives re-appends the finding as an `auto:` row that fails the wall the waiver passed.
-- **`type:` is a required frontmatter key** on every doc that carries frontmatter — the genre stamp, its enum being the `documentation` skill's template names (`feature`, `architecture-decision`, `project-memory`, `ux`, `acceptance-criteria`, …). It is tooling metadata like `last-reviewed:` and `status:`: external tooling reads it, sessions **preserve it on edits** and never narrate it in the body. The `maintenance` agent stamps it on docs that lack it.
-  **No genre is frontmatter-less by policy; the gaps are the templates.** `architecture/common/**` carries `type: doctrine` with `status:` and `objects:` and no `owns:`, from the documentation skill's doctrine template. `architecture/Readme.md` carries no block, because its template ships none and a block is never manufactured on a doc whose template has none. `architecture/packages/**` and `architecture/systems/**` carry `type: package` / `type: system` with `objects:` and `status:`, plus the transitional `owns:` region glob the ownership scan reads until it switches to source headers. The `operations/` procedures carry a hand-authored `type: operations` block; the bookkeeping queue carries none. Docs written by a skill that ships a block (`issue-bridge`'s `type: issue` / `type: triage`) carry it.
+- **`type:` is a required frontmatter key** on every doc that carries frontmatter — the genre stamp, its values the genre registry's `type:` column (`feature`, `architecture-decision`, `project-memory`, `ux`, `acceptance-criteria`, …). It is tooling metadata like `last-reviewed:` and `status:`: external tooling reads it, sessions **preserve it on edits** and never narrate it in the body. The `maintenance` agent stamps it on docs that lack it. The owning genres (`type: feature`, `type: package`, `type: system`) carry the transitional `owns:` region glob the ownership scan reads until it switches to source headers; `type: doctrine` carries `objects:` and owns no code; the bookkeeping queue carries no block. Docs written by a skill that ships a block (`issue-bridge`'s `type: issue` / `type: triage`) carry it.
 - **The docs tree is a graph, and nothing in it that can be computed is typed.** A document names the objects it designs (`objects:`); a source file names the document that speaks for it in its path header; the object closure computes the rest — which files a document speaks for, and which surfaces a doctrine governs. One doc → doc edge is authored, because nothing computes it: **`verifies:`** (checklist → the doc whose promises it proves). Its inverse is **generated** — `buildEdgeIndex()` in `.claude/hooks/lib/ownership.mjs`, injected at SessionStart beside the ownership index — and authoring an inverse by hand is a defect. `applies:` is retired; `owns:` is a transitional region glob (the `documentation` skill's `references/frontmatter.md`).
 - **`docs/acceptance/` holds the acceptance-criteria genre** — one `kebab-case.md` per capability, written at specification time, before implementation, holding stable `AC-n` assert lines that verification surfaces parse as claims to grade the built product against; each file is keyed to the checklist sections that grade it. The folder is created on first use and never scaffolded. The `AC-n:` line grammar is load-bearing: the key sits at line start, exactly `AC-<number>:`, followed by the assert sentence — tables, emphasis-wrapped keys, and nested bullets break the parse.
-- **The `ux` genre decides observable behavior; `docs/tests/` only verifies it.** A feature doc states what a feature is and which contracts it honours — all of which stay plausibly true through a rewrite of the surface — so a UX-behavior doc states what a person *observes*, and is written **before** the code. This repo holds no standalone `ux` document: what a person observes on a surface is a section of the feature doc that owns that surface's components and wire. A surface needing the genre gets `features/{surface}-ux.md`, named in the headers of the component files no other document speaks for; where a feature document already speaks for them, the UX document is named in its coordinated-edits row.
-- **`docs/history/journal.md` is the temporary lane, and `docs/memory/` is not.** The journal holds mid-execution facts one line each, each resolved by landing in its owning doc; memory holds only per-agent strategy and project knowledge no single doc owns. A fact an owning doc will eventually carry goes to the journal, never to memory — memory has no drain, so what lands there stays until somebody distils it.
+- **The `ux` genre decides observable behavior; `docs/tests/` only verifies it.** A feature doc states what a feature is and which contracts it honours — all of which stay plausibly true through a rewrite of the surface — so a UX-behavior doc states what a person *observes*, and is written **before** the code. A surface needing the genre gets `features/{surface}-ux.md`, named in the headers of the component files no other document speaks for; where a feature document already speaks for them, the UX document is named in its For the agent **See also** line.
+- **`docs/history/journal.md` drains into documents, and `docs/memory/` does not.** Both are queues. The journal holds mid-execution facts one line each, each resolved by landing in its owning doc; memory holds only per-agent strategy and project knowledge no single doc owns, compacted by its writer. A fact an owning doc will eventually carry goes to the journal, never to memory — nothing drains memory into a document, so what lands there stays until its writer retires it.
 - **There is no `docs/history/sessions/`.** Per-session gate logs are machine-local, written by `.claude/hooks/lib/session-log.mjs` into `.claude/state/sessions/` (self-ignored), so they never enter `docs/` or git. A `docs/history/sessions/` folder is residue, not shape.
 - **The repo-root `README.md` opens outward and turns inward.** What the product does, for whom and where it runs, in a user's terms; then, for the team and agents, how it works, a Map of top-level units with their owning doc, the rules that bite, where to go by intent, and at most four everyday commands. It carries no install, stack or tree — install and stack are `operations/setup.md`, the tree is this file's. Template: the `documentation` skill's `templates/root-readme.md`.
 - **`docs/README.md` describes directories, never files.** One entry per folder: what it holds, who reads it, how its files are named — no per-file rows, no tree. It closes with the repository's own notes, the one place project-specific placement facts live.
@@ -84,12 +85,12 @@ docs/
 
 ## Lifecycle
 
-- **Plans** (`history/plans/YYYY-MM-DD-{slug}.md`) carry a `Status:` field (`Draft` / `Ready` / `Active` / `Executed` / `Complete` / `Abandoned`). Once `Complete`/`Abandoned`, a plan is frozen — never edited; scope changes get a new dated plan that links back.
+- **Plans** (`history/plans/YYYY-MM-DD-{slug}.md`) carry a `Status:` field (`Draft` / `In Progress` / `Complete` / `Abandoned`). Once `Complete`/`Abandoned`, a plan is frozen — never edited; scope changes get a new dated plan that links back.
 - **Migration runbooks** (`history/migrations/YYYY-MM-DD-{slug}.md`) are authored ahead of execution and record a one-shot infra/cutover procedure; once executed, the outcome is stamped into the file and it is frozen — a re-run gets a new dated runbook.
-- **Changelog** entries land in `history/changelog/` and are indexed in `history/CHANGELOG.md`.
-- **Backlog** items live in `history/backlog.md` under P0–P3 priorities (living, append-only).
-- **Brainstorm sessions** are author-created by the `brainstorm` skill: an active session at `docs/research/{topic}-brainstorm/` (older folders carry the legacy `-brainstorming/` suffix; both are canonical), moved to `docs/history/brainstorms/{topic}/` on a passed harvest — the move is the completion marker, and the moved folder's fate (delete or commit) is the author's call. Never scaffolded empty; each folder carries a `Readme.md` index.
-- **Source-of-truth audits** write nothing to `docs/`. The `polygraph` skill runs in two modes — **audit** on a named target (a doc, a feature, a folder, a code path) and **gate** at plan completion — and both keep their rows under `.claude/state/polygraph/{run}/`, machine-local, never tracked, deleted in the same turn as the report. What survives a run is the corrected document itself, the backlog rows it registered, and the plan's `Polygraph:` segment. Folders an earlier audit mode left behind are provenance a repo lists in its `README.md` notes, never a place anything writes.
+- **Changelog** entries land in `history/changelog/`, one per unit of work, each opening on its one-line summary. `history/CHANGELOG.md` is the folder's guide and takes no row per entry; listing the folder is the index.
+- **Backlog** items live in `history/backlog.md` under P0–P3 priorities — a queue: appended, and deleted when the work lands.
+- **Brainstorm sessions** are author-created by the `brainstorm` skill: an active session at `docs/research/{topic}-brainstorm/` (older folders carry the legacy `-brainstorming/` suffix; both are canonical), moved to `docs/history/brainstorms/{topic}/` on a passed harvest — the move is the completion marker, and the moved folder's fate (delete or commit) is the author's call. Never scaffolded empty; no index keeps a row per session.
+- **Source-of-truth audits** write nothing to `docs/`. The `polygraph` agent runs only when the user asks, on a named target (a doc, a feature, a folder, a code path or a plan), and keeps its rows under `.claude/state/polygraph/{run}/`, machine-local, never tracked, deleted in the same turn as the report. What survives a run is the corrected document itself and the backlog rows it registered; a run against a plan also leaves a `Polygraph:` segment on its `Gates:` line, which nothing reads.
 - **Boundaries** are a plan-time diagnostic — the `boundary` skill reads contracts fresh from source; there is no persisted `boundaries/` tree.
 - **Modules** are _declared labels_ (a `module:` key on a feature doc), never inferred from physical layout and never a folder. A feature always lives flat in `features/`.
 
@@ -97,31 +98,45 @@ docs/
 
 ## Add-a-doc decision table
 
-| You are adding… | It goes in… | Needs frontmatter? |
+The `type:` column is the value the document carries; its required keys and sections are the genre registry's row for that type.
+
+| You are adding… | It goes in… | `type:` |
 | --- | --- | --- |
-| A feature document — something a person points at (an address, a command family, a named control), cut by the objects it designs | `features/` (flat) | Yes — `type: feature`, `objects:`, `status:` (+ optional `module:`, `last-reviewed:`; a transitional `owns:` region glob) |
-| A package's behavior document | `architecture/packages/<package>.md`, one per package | Yes — `type: package`, `objects:`, `status:` (+ the transitional `owns:` over its tree, residually) |
-| A system's behavior document | `architecture/systems/{system}.md`, one per machine | Yes — `type: system`, `objects:`, `status:` (+ the transitional `owns:` over the machine's subtrees) |
-| Cross-cutting design / steering (doctrine) | `architecture/common/` | Yes — `type: doctrine`, `objects:`, `status:` |
-| An Architecture Decision (AD) | `architecture/decisions/` — one file per subject, updated in place; the journey lives in that file's Decision Changelog | Yes — `type: architecture-decision` (+ `title:`, `status:`, `created:`, `last-updated:`, `decision-owner:`, `tags:`) |
-| One-time machine setup, first run, stack, prerequisites, env files | `operations/setup.md` — fixed name, one per repo, linked from the root README; a diverging package gets a `### {unit}` subsection, never a second first-run doc | Yes — `type: operations` |
-| A recurring procedure (develop, deploy, rotate, diagnose, CI) | `operations/{procedure}.md` | Yes — `type: operations` |
-| A tracker issue held in the repo | `operations/issues/YYYY-MM-DD-{slug}.md` (via the `issue-bridge` skill's local pack) | Yes — `type: issue`, `id:`, `status:`, `labels:`, `author:`, `created:`, `github:` |
-| A triage dossier for an investigated issue | `operations/triage/YYYY-MM-DD-{slug}.md` (via the `issue-bridge` skill) | Yes — `type: triage`, `tracker:`, `issue:`, `date:`, `confidence:`. A dated working artifact: it never claims `owns:` and never masquerades as a feature doc |
-| A behavioral test checklist | `tests/{feature}.md` | Yes — `type: checklist`, `verifies:` (the doc(s) whose promises it proves; several values are legitimate). No `owns:` — it owns no code. Truth doc, present-tense; written at the verification gate before the driving, each section carrying a `Pinned:` trace |
-| What a person sees and can do on a surface (UX behavior) | `features/{surface}-ux.md`, named in the headers of the component files no other document speaks for; a section of the owning feature doc where the surface has one owner; `architecture/common/` when it is cross-cutting | Yes — `type: ux` (+ the feature-doc keys when it lives in `features/`) |
-| Acceptance criteria for one capability | `acceptance/{capability}.md` — stable `AC-n` assert lines verification surfaces parse as claims; keys are never renumbered or reused, a retired criterion is marked retired in place | Yes — `type: acceptance-criteria`, `status:`; no `owns:` (owns no code) |
-| An in-progress brainstorm session | `research/{topic}-brainstorm/` (via the `brainstorm` skill) | No |
-| A source-of-truth audit | Nowhere in `docs/` — the `polygraph` skill (audit mode) corrects the target doc in place and keeps its rows under `.claude/state/polygraph/{run}/`, deleted with the report | No |
-| An implementation plan | `history/plans/YYYY-MM-DD-{slug}.md` | No (but `Status:` required) |
-| A one-shot migration runbook | `history/migrations/YYYY-MM-DD-{slug}.md` | No (authored ahead; outcome-stamped and frozen once executed) |
-| A deep-research record | `history/research/{topic}/` — `README.md` synthesis + `findings.md` + `sources.md`; frozen and cited, owns no code, never edited to stay current (a new question gets a new topic folder) | No |
-| A harvested brainstorm session | `history/brainstorms/{topic}/` (via the `brainstorm` skill's harvest) | No |
-| A changelog entry | `history/changelog/` + index in `CHANGELOG.md` | No |
-| A tracked work item | `history/backlog.md` | No |
-| A doc-sync debt row | `operations/bookkeeping.md` (hook-appended; drained by the `bookkeeper` agent, deleted on drain) | No |
-| A mid-execution fact worth keeping | `history/journal.md` (append-only; resolves by landing in its owning doc) | No |
-| Agent strategy / project memory | `memory/` | Yes — `type: project-memory` on `main.md` |
+| A feature document — something a person points at (an address, a command family, a named control), cut by the objects it designs | `features/{feature}.md` (flat) | `type: feature` |
+| What a person sees and can do on a surface (UX behavior) | `features/{surface}-ux.md`, named in the headers of the component files no other document speaks for; `architecture/common/` when it is cross-cutting | `type: ux` |
+| A package's behavior document | `architecture/packages/{package}.md`, one per package | `type: package` |
+| A system's behavior document | `architecture/systems/{system}.md`, one per machine | `type: system` |
+| Cross-cutting design (doctrine) | `architecture/common/{concern}.md` | `type: doctrine` |
+| The testing strategy | `architecture/common/testing.md` | `type: testing-strategy` |
+| An Architecture Decision (AD) | `architecture/decisions/AD-NNN-{subject}.md` — one file per subject, updated in place; the journey lives in its Decision Changelog | `type: architecture-decision` |
+| The system at a glance | `architecture/system-design.md` | `type: system-overview` |
+| The domain model | `architecture/domain-model.md` | `type: domain-model` |
+| The glossary | `architecture/glossary.md` | `type: glossary` |
+| The non-goals | `architecture/non-goals.md` | `type: non-goals` |
+| The security overview | `architecture/security.md` | `type: security-overview` |
+| The API surface | `architecture/api.md` | `type: api-reference` |
+| The environment variables | `operations/environment.md` | `type: environment-registry` |
+| One-time machine setup, first run, stack, prerequisites, env files | `operations/setup.md` — fixed name, one per repo, linked from the root README; a diverging package gets a `### {unit}` subsection, never a second first-run doc | `type: operations` |
+| A recurring procedure (develop, deploy, rotate, diagnose, CI) | `operations/{procedure}.md` | `type: operations` |
+| The build order of a project built from its design | `operations/implementation-map.md` | `type: implementation-map` |
+| The protected-files list | `operations/protected-files.md` | `type: protected-files` |
+| A tracker issue held in the repo | `operations/issues/YYYY-MM-DD-{slug}.md` (via the `issue-bridge` skill's local pack) | `type: issue` |
+| A triage dossier for an investigated issue | `operations/triage/YYYY-MM-DD-{slug}.md` (via the `issue-bridge` skill) — a dated working artifact that never claims `owns:` | `type: triage` |
+| A behavioral test checklist | `tests/{feature}.md` — written at the verification gate before the driving, each section carrying a `Pinned:` trace; owns no code | `type: checklist` |
+| Acceptance criteria for one capability | `acceptance/{capability}.md` — stable `AC-n` assert lines; keys are never renumbered or reused, a retired criterion is marked retired in place | `type: acceptance-criteria` |
+| A folder's landing page | `{folder}/Readme.md` — describes the folder, never a row per file | `type: folder-index` |
+| An in-progress brainstorm session | `research/{topic}-brainstorm/` (via the `brainstorm` skill) | none |
+| A source-of-truth audit | Nowhere in `docs/` — the `polygraph` agent corrects the target doc in place | none |
+| An implementation plan | `history/plans/YYYY-MM-DD-{slug}.md` (a `Status:` line is required) | none |
+| A one-shot migration runbook | `history/migrations/YYYY-MM-DD-{slug}.md` (authored ahead; outcome-stamped and frozen once executed) | none |
+| A hand-over at the end of an unattended or multi-session build | `history/handovers/YYYY-MM-DD-{slug}.md` | `type: handover` |
+| A deep-research record | `history/research/{topic}/` — `README.md` synthesis + `findings.md` + `sources.md`; frozen and cited, a new question gets a new topic folder | none |
+| A harvested brainstorm session | `history/brainstorms/{topic}/` (via the `brainstorm` skill's harvest) | none |
+| A changelog entry | `history/changelog/YYYY-MM-DD-{three-words}.md`; `CHANGELOG.md` takes no row | none |
+| A tracked work item | a row in `history/backlog.md` | none |
+| A doc-sync debt row | a row in `operations/bookkeeping.md` (hook-appended; drained by the `bookkeeper` agent, deleted on drain) | none |
+| A mid-execution fact worth keeping | a row in `history/journal.md` (resolves by landing in its owning doc) | none |
+| Agent strategy / project memory | `memory/main.md`, `memory/{agent}.md` | `type: project-memory` on `main.md` |
 
 ---
 

package/data/harnesses/code/harness.json

@@ -1,7 +1,7 @@
 {
   "harness": "code",
   "name": "code",
-  "version": "3.20.6",
+  "version": "3.20.7",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
@@ -29,5 +29,5 @@
     "origin": "https://cdn.nustack.io",
     "track": "latest"
   },
-  "digest": "8aae863291c5"
+  "digest": "068ff439e1f9"
 }

package/data/harnesses/code/hooks/compliance.mjs

@@ -145,13 +145,19 @@ function fileGate(projectDir, rel, sessionId) {
       // The gate binds the plan's own paths, so disjoint plans run in parallel.
       // A scopeless plan stays repo-wide — fail closed.
       if (plan.scope.length && !inPlanScope(rel, plan.scope)) continue;
-      if (/Boundary:\s*pending/i.test(plan.gates)) {
+      // Only a passed verdict opens the gate: `pending` has no verdict yet, and `blocked` is a verdict against coding.
+      const boundary = /Boundary:\s*(\w+)/i.exec(plan.gates);
+      if (boundary && !/^passed$/i.test(boundary[1])) {
         return deny(
           projectDir,
           sessionId,
           "plan-gate",
           plan.file,
-          `BLOCKED — plan gate. \`${plan.file}\` is open but its Gates line reads 'Boundary: pending'. Run the \`boundary\` skill and record its verdict in the plan before implementation edits.`
+          `BLOCKED — plan gate. \`${plan.file}\` is open but its Gates line reads 'Boundary: ${boundary[1]}'. ${
+            /^blocked$/i.test(boundary[1])
+              ? "Fold the `boundary` skill's amendments into the plan and re-run it until it records `passed`."
+              : "Run the `boundary` skill and record its verdict in the plan before implementation edits."
+          }`
         );
       }
       if (!plan.hasLedger) {

package/data/harnesses/code/hooks/lib/sweep.mjs

@@ -24,13 +24,14 @@ import { readSafe, docsRoot } from "./repo.mjs";
 import { resolveRows } from "./state.mjs";
 import { rejectedPackages } from "./approved.mjs";
 
-// Spawn the installed doc-lint over one file; returns finding lines (empty when absent/clean).
+// Spawn the installed doc-lint over one file; returns its block-severity finding lines (empty when absent/clean),
+// so a warning advises and only a blocking rule raises a row that walls the commit — as sourceLint() below.
 export function docLint(projectDir, rel) {
   const script = path.join(projectDir, ".claude", "skills", "documentation", "scripts", "doc-lint.mjs");
   if (!fs.existsSync(script)) return [];
   const res = spawnSync("node", [script, rel], { cwd: projectDir, encoding: "utf8", timeout: 5000 });
   const out = `${res.stdout || ""}`;
-  return out.split("\n").filter((line) => /:\d+ \[(block|warn)\]/.test(line));
+  return out.split("\n").filter((line) => /:\d+ \[block\]/.test(line));
 }
 
 // True when the first path-shaped token in a source file's opening lines IS its repo-relative path.

package/data/harnesses/code/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/harnesses/code/skills/boundary/SKILL.md

@@ -7,35 +7,38 @@ description: "Use when a plan or diff might break a cross-cutting contract. Boun
 
 You diagnose whether a plan's changes would break an application boundary.
 
-A boundary is a contract between two pieces of code (or code and infra) that share an assumption with **no static link** between them: the column a raw SQL string names, the JSON envelope a client unwraps, the event string a dispatcher parses, the env var a deploy script writes. Changing one side ships green — compiles, lints, tests pass — and breaks the other at runtime. Your job is to find those edges in the plan's path _before_ execution.
+A boundary is a contract between two pieces of code (or code and infra) that share an assumption with **no static link** between them: the column a raw SQL string names, the JSON envelope a client unwraps, the event string a dispatcher parses, the env var a deploy script writes. Changing one side ships green — compiles, lints, tests pass — and breaks the other at runtime. Find those edges in the plan's path _before_ execution.
 
-**The litmus is "would it ship green?"** An edge the compiler or an existing test already guards is not a boundary — a change that fails the build loudly needs no diagnostic. Spend your reading on the edges with no static link.
+**The litmus is "would it ship green?"** An edge the compiler or an existing test already guards is not a boundary — spend your reading on the edges with no static link.
 
 ## Contract sources
 
 Three layers tell you what to look for; the code tells you what exists.
 
-- **The mechanisms** — [`references/mechanisms.md`](references/mechanisms.md) defines the seven failure mechanisms every boundary instantiates (rendezvous-string, serialized-shape, generated-artifact, dual-authority, config-elsewhere, trust-invariant, lifecycle-protocol), each with its trace strategy, universal safe-change pattern, and severity heuristic, plus the two stack-independent domain contracts (entity-model, tenancy). Load it on every check.
-- **The technology packs** — [`references/index.md`](references/index.md) routes to the packs under `references/packs/` by the signals in the touched code. Each pack carries the non-derivable payload for one technology area: exact detect patterns, expensive-to-learn gotchas, and safe-change sequences. Load **only the packs the touch list exhibits**; a technology no pack covers is still in scope — diagnose it from its mechanism.
-- **Repo doctrine** — `.claude/rules/`, `docs/architecture/` (including `decisions/`), and any contracts package name the repo's bespoke contracts (a documented response envelope, a schema-parity rule, an entity model). A documented contract is a real side of a boundary: a plan that contradicts one is a finding **even when no code consumer exists yet** — this is how greenfield plans, whose modules have no code to trace, still get checked.
-
-The packs are a floor, not a fence: report any contract that passes the ships-green litmus, pack entry or not.
+- **The mechanisms** — [`references/mechanisms.md`](references/mechanisms.md): the seven failure mechanisms every boundary instantiates (rendezvous-string, serialized-shape, generated-artifact, dual-authority, config-elsewhere, trust-invariant, lifecycle-protocol), each with its trace strategy, universal fix, and severity, plus the two stack-independent domain contracts (entity-model, tenancy). Load it on every check.
+- **The technology packs** — [`references/index.md`](references/index.md) routes to the packs under `references/packs/` by the signals in the touched code; each pack carries one technology area's detect patterns, gotchas, and safe-change sequences. Load **only** the packs the touch list exhibits. The packs are a floor, not a fence: a contract no pack covers is still in scope — diagnose it from its mechanism and report it if it passes the litmus.
+- **Repo doctrine** — `.claude/rules/`, `docs/architecture/` (including `decisions/`), and any contracts package name the repo's bespoke contracts (a documented response envelope, a schema-parity rule, an entity model). A documented contract is a real side of a boundary: a plan that contradicts one is a finding **even when no code consumer exists yet** — this is how a greenfield plan, with no code to trace, still gets checked.
 
 ## Run
 
-**Input:** a plan path (given, or the newest in `docs/history/plans/`) — or a diff / named code area for non-plan work. Everything below is identical either way; a diff's hunks stand in for the plan's steps.
+**Input:** a plan path (given, or the newest in `docs/history/plans/`) — or a diff or named code area for non-plan work, where the diff's hunks stand in for the plan's steps. Steps 1–5 are identical either way; the report's **Missing plan subsections** and **Docs the plan's ledger missed** sections, and step 6, apply only to a plan.
+
+1. **Build the touch list.** Parse the plan's Proposed Changes: files created or modified, entities or state added or changed, API changes, anything the author flags as a cross-module contract. Note missing subsections.
+
+2. **Identify the contracts.** Read each touched file and its immediate imports. Against the mechanisms, the routed packs, and the repo doctrine, list the contracts this code participates in — the schema it queries, the envelope it emits, the events it publishes or parses, the auth checks it sits behind, the env it reads.
 
-1. **Build the touch list.** Parse the plan's Proposed Changes: files created or modified, entities/state added or changed, API changes, anything the author flags as a cross-module contract. Note missing subsections.
+3. **Trace the other side.** The danger lives on the side the plan _doesn't_ mention. For each contract, grep the shared name or shape across the repo — the column name in other SQL strings, the response field in client unwrappers, the event kind in subscribers, the route in fetch calls and scripts, the env key in deploy tooling. Record consumers as `file:line`, doctrine as the doc path. At ≳10 contracts, fan the tracing out to parallel sub-agents — one per pack area, each prompt self-contained with its contracts and grep targets — and judge the returned evidence yourself; a small diff traces inline.
 
-2. **Identify the contracts.** Read each touched file (and its immediate imports). Against the mechanisms, the routed packs, and the repo doctrine, list the contracts this code participates in — the schema it queries, the envelope it emits, the events it publishes or parses, the auth checks it sits behind, the env it reads.
+4. **Judge each intersection.** Does the planned change alter a shape a traced consumer depends on, break an invariant the code or doctrine establishes (append-only vocabularies, idempotency keys, fail-closed checks, ordering guarantees), or introduce a new cross-module edge? Grade it:
 
-3. **Trace the other side.** A boundary has two sides; the danger lives on the one the plan _doesn't_ mention. For each contract, grep the shared name or shape across the repo — the column name in other SQL strings, the response field in client unwrappers, the event kind in subscribers, the route in fetch calls and scripts, the env key in deploy tooling. Record consumers as `file:line`; record doctrine as the doc path. When the touch list is large (≳10 contracts), fan the tracing out to parallel sub-agents — one per pack area, each with a self-contained prompt naming its contracts and grep targets — and judge the returned evidence yourself; a small diff traces inline.
+   | Severity | Meaning |
+   | --- | --- |
+   | **CRITICAL** | Can corrupt persisted data, or open an auth/money path — trust-invariants and persisted or replayed shapes live here |
+   | **HIGH** | Silent cross-module breakage that ships green |
+   | **MEDIUM** | Drift-prone coupling not yet broken (string-matched, duplicated constants) |
+   | **LOW** | Smell |
 
-4. **Judge each intersection.** Does the planned change alter a shape a traced consumer depends on, break an invariant the code or doctrine establishes (append-only vocabularies, idempotency keys, fail-closed checks, ordering guarantees), or introduce a new cross-module edge? Severity:
-   - **CRITICAL** — can corrupt persisted data, or open an auth/money path.
-   - **HIGH** — silent cross-module breakage that would ship green.
-   - **MEDIUM** — drift-prone coupling (string-matched, duplicated constants).
-   - **LOW** — smell. Loud, immediately-visible runtime breakage caps at HIGH.
+   Loud, immediately visible runtime breakage caps at HIGH. Severity is intrinsic to the finding, never curved — three genuine CRITICALs in a small repo is signal, not inflation.
 
 5. **Report in chat:**
 
@@ -61,15 +64,23 @@ The packs are a floor, not a fence: report any contract that passes the ships-gr
    | Feature doc | Owned path in the touch list | In Doc Obligations? |
    ```
 
-   **The doc cross-check is free and you are the only one who can make it.** You already hold the touch list; resolving those paths against the ownership index and comparing the result to the plan's **Doc Obligations** rows costs one lookup. The plan's author wrote that ledger, so it is the one gate artifact nobody independently checked — a `None` that contradicts your touch list is the failure this section exists to catch. Report the gap; never edit the ledger yourself.
+   **Fill the doc cross-check from the touch list you already hold:** resolve its paths against the ownership index and compare the result to the plan's **Doc Obligations** rows. The plan's author wrote that ledger and nobody else checks it — a `None` that contradicts your touch list is the failure this section catches. Report the gap; **never** edit the ledger yourself.
+
+   **BLOCK** = any CRITICAL; a blocked plan folds the amendments and re-runs the check. HIGH findings yield **PASS WITH AMENDMENTS** — the invoking session folds the amendments into the plan in the same pass, before the plan is shown as finished. Order amendments sequencing-first: many violations dissolve by reordering steps (expand-then-contract, migrate-before-code) rather than changing what ships — prefer that fix, drawn from the pack entry's **Safe change** or the mechanism's **Universal fix**.
+
+6. **Record the verdict in the plan's `Gates:` line.** Rewrite only your own segment, to exactly one of:
 
-   **BLOCK** = any CRITICAL. HIGH findings yield **PASS WITH AMENDMENTS** — the invoking session folds the amendments into the plan in the same pass, before the plan is shown as finished. Order amendments sequencing-first: many violations dissolve by reordering steps (expand-then-contract, migrate-before-code) rather than changing what ships — prefer that fix, drawn from the entry's safe-change sequence.
+   | Verdict | Segment |
+   | --- | --- |
+   | PASS | `Boundary: passed YYYY-MM-DD` |
+   | PASS WITH AMENDMENTS | `Boundary: passed YYYY-MM-DD` — written only once the amendments are folded |
+   | BLOCK | `Boundary: blocked YYYY-MM-DD` |
 
-6. **Record the verdict in the plan's `Gates:` line.** Rewrite only your own segment, to exactly `Boundary: passed YYYY-MM-DD` (PASS, or PASS WITH AMENDMENTS once the amendments are folded) or `Boundary: blocked YYYY-MM-DD` (BLOCK). The compliance hook greps exactly this segment — implementation edits inside the plan's scope stay blocked while it reads `Boundary: pending` (the other gates are enforced by section presence, not segment text). A plan with no `Gates:` line predates the format; add the line rather than skipping the write-back.
+   The compliance hook greps exactly this segment and blocks implementation edits inside the plan's scope until it reads `passed` — `pending` and `blocked` wall alike (the other gates are enforced by section presence, not segment text). A plan with no `Gates:` line gets one added; never skip the write-back.
 
 ## Rules
 
-- **Read-only, one exception.** You never edit the plan's content, the code, or any doc — the invoking session folds your amendments into the plan in the same pass, then writes the segment to `passed`; a plan is not finished until it does. The single write you own is the plan's `Gates:` line (step 6), your segment only.
-- **Verify in source.** Never flag from plan text alone — read both sides of every finding and cite them: code as `file:line`, doctrine as the doc path.
-- **No other side, no violation.** An intersection with no traced consumer and no doctrine behind it isn't a violation — it's a **new edge**: report it in its own section with the hardening its mechanism prescribes (version the cache key now, make the enum append-only now), so the fragile edge is born safe.
+- **Read-only, one exception.** You never edit the plan's content, the code, or any doc — the invoking session folds your amendments into the plan; a plan is not finished until its segment reads `passed`. The single write you own is the plan's `Gates:` line (step 6), your segment only.
+- **Verify in source.** **Never** flag from plan text alone — read both sides of every finding and cite them: code as `file:line`, doctrine as the doc path.
+- **No other side, no violation.** An intersection with no traced consumer and no doctrine behind it is a **new edge**, not a violation: report it in its own section with the hardening its mechanism prescribes (version the cache key now, make the enum append-only now), so the fragile edge is born safe.
 - **A clean report is valid.** Zero violations means say so — the coverage table is the evidence it was checked, not skipped. Don't pad findings.

package/data/harnesses/code/skills/boundary/references/index.md

@@ -1,16 +1,14 @@
 # Pack routing index
 
-Load when: every boundary check, right after `mechanisms.md`. Match the touch list against the signals below and load **only** the packs whose signals appear in the touched files or the plan's Proposed Changes. Several packs matching is normal (a full-stack feature typically routes 2–4). A technology matching nothing here is still in scope — diagnose it from its mechanism, and check `packs/generic-tail.md` for a thin entry.
+Load when: every boundary check, right after `mechanisms.md`. Match the touch list against the signals below and load **only** the packs whose signals appear in the touched files or the plan's Proposed Changes — a full-stack feature typically routes 2–4. A technology matching no row has a thin entry in `packs/generic-tail.md` or none; either way, diagnose it from its mechanism.
 
 | Pack | Load when the touch list shows |
 | --- | --- |
 | `packs/persistence.md` | `schema.ts`, `init.sql`, `sqliteTable(`, `drizzle-kit`, `pgTable`, migrations, `*.seed.sql`, seed generators, JSON columns, `pgEnum`, pgvector, Redis `get`/`set` caching |
 | `packs/wire-api.md` | Express routes/middleware (`app.use(`, `router.`), `res.json({ status`, zod schemas on requests, axios clients/interceptors, `cors(`, inbound webhooks, `rateLimit(` |
-| `packs/frontend.md` | `createSlice`/`configureStore`, RTK Query (`tagTypes`), react-router tables/`useParams`, Tailwind CSS (`@theme`, `personality.css`, `globals.css`), `vite.config.*` (alias, env), `@nurix/components`, localforage/redux-persist, date formatting |
+| `packs/frontend.md` | `createSlice`/`configureStore`, RTK Query (`tagTypes`), react-router tables/`useParams`, Tailwind CSS (`@theme`, `personality.css`, `design.tokens.css`, `globals.css`), `vite.config.*` (alias, env), `@nurix/components`, localforage/redux-persist, date formatting |
 | `packs/auth.md` | `jwtVerify(`/jose, `betterAuth(`/`auth.api.`, session cookies, CSRF, OAuth callbacks/`redirect_uri`, `tenantId`/`organizationId` scoping, password hashing, auth middleware mounts |
 | `packs/cloudflare.md` | `wrangler.jsonc`/`wrangler.toml`, `env.X` bindings, `extends DurableObject`/`[[migrations]]`, KV/R2/D1/Queues, `scheduled(`/crons, `WorkerEntrypoint`, `compatibility_date`, static assets config |
 | `packs/async-messaging.md` | BullMQ (`new Queue(`/`new Worker(`), Redis pub/sub or Streams, WebSockets/socket.io, SSE (`text/event-stream`), channel-name templates, outbound webhook senders |
 | `packs/build-config-runtime.md` | `package.json` (deps/`exports`/scripts/`packageManager`), lockfiles, `.env*`, tsconfig `paths`, Dockerfiles/compose, `.github/workflows/`, pino config, `trust proxy`, ports/healthchecks |
 | `packs/generic-tail.md` | GraphQL, gRPC/protobuf, tRPC, OpenAPI codegen, Kafka/schema registry/CDC, workflow engines, event sourcing, Postgres RLS/pooling/collation, SSR/hydration, module federation, i18n, analytics plans, hosted feature flags, K8s probes/shutdown/limits, service mesh, IaC outputs, SAML, Lambda, IPC |
-
-Two files never route — they always load: `mechanisms.md` (the seven failure mechanisms + domain contracts) and this index.

package/data/harnesses/code/skills/boundary/references/mechanisms.md

@@ -1,10 +1,8 @@
 # Boundary Mechanisms
 
-Load when: every boundary check — this is the core reference. The technology packs under `packs/` instantiate these mechanisms with exact detect signals and gotchas; `index.md` routes to the packs the touched code exhibits.
+Load when: every boundary check — this is the core reference. The packs under `packs/` instantiate these mechanisms with exact detect signals and gotchas.
 
-A boundary is a contract between two pieces of code (or code and infra) that share an assumption with **no static link** between them. The litmus is **"would it ship green?"** — change one side, everything compiles, lints, and tests pass, and the other side breaks at runtime. An edge the compiler or an existing test already guards is not a boundary.
-
-Every boundary instantiates one of seven mechanisms. The mechanism tells you what to grep for, what the universal fix is, and how bad a break is — including for technologies no pack covers. When touched code exhibits a contract that matches no pack entry, diagnose it from its mechanism.
+Every boundary instantiates one of seven mechanisms. The mechanism tells you what to grep for, what the universal fix is, and how bad a break is — which is how you diagnose a technology no pack covers.
 
 ---
 
@@ -91,9 +89,4 @@ Two contracts come from the product's information architecture, not from any tec
 
 ## Severity recap
 
-- **CRITICAL** — can corrupt persisted data, or open an auth/money path. Trust-invariants and persisted/replayed shapes live here.
-- **HIGH** — silent cross-module breakage that ships green.
-- **MEDIUM** — drift-prone coupling (string-matched, duplicated constants) not yet broken.
-- **LOW** — smell. Loud, immediately-visible runtime breakage caps at HIGH; statically-guarded edges are out of scope entirely.
-
-Severity is intrinsic to the finding, not curved: three genuine CRITICALs in a small repo is correct signal, not inflation.
+The scale is `SKILL.md` step 4; each mechanism's **Severity** line above places a finding on it.

package/data/harnesses/code/skills/boundary/references/packs/frontend.md

@@ -1,6 +1,6 @@
 # Pack: frontend / client state / UI build
 
-Load when: the touch list exhibits Redux Toolkit (`createSlice`, `configureStore`), RTK Query tags, react-router route tables, Tailwind 4 CSS (`@theme`, `personality.css`, `globals.css`), Vite config (`resolve.alias`, env), `@nurix/components` imports, localforage/redux-persist, or date handling crossing the wire.
+Load when: the touch list exhibits Redux Toolkit (`createSlice`, `configureStore`), RTK Query tags, react-router route tables, Tailwind 4 CSS (`@theme`, `personality.css`, `design.tokens.css`, `globals.css`), Vite config (`resolve.alias`, env), `@nurix/components` imports, localforage/redux-persist, or date handling crossing the wire.
 
 ## redux-persist-shape-migration — CRITICAL · serialized-shape
 **Contract:** State shapes frozen in the user's browser storage by redux-persist must be readable by the *current* reducers' `initialState` — `version`/`migrate` is the only bridge, and `whitelist`/`blacklist` reference reducer-map keys by literal string.
@@ -51,10 +51,10 @@ Load when: the touch list exhibits Redux Toolkit (`createSlice`, `configureStore
 **Safe change:** Grep both consumer forms — utility stems (`bg-old`, `text-old`) and `var(--…-old)` including `node_modules/@nurix/components` dist CSS; keep the old token as an alias for one release; visually diff themed screens after the rename.
 
 ## tailwind-theme-inline-indirection — HIGH · config-elsewhere
-**Contract:** `@theme inline { --color-primary: var(--primary) }` makes utilities emit the *referenced* variable (`background-color: var(--primary)`), resolved per-element at runtime — the org's theming (personality.css vars swapped under `[data-theme]`/`[data-style]`) only flows through utilities via the `inline` form.
-**Detect:** `@theme inline`, plain `@theme {`, token values that are `var(--…)`, `[data-theme=`/`[data-style=` blocks in `personality.css`
-**Ships green, breaks:** Adding a var-referencing token to a plain (non-`inline`) `@theme` block compiles and looks correct in the default theme; switching `data-theme`/`data-style` then silently fails to restyle those utilities, because the theme variable captured the referenced var's value as resolved at `:root` — subtree/attribute-scoped overrides never reach it. No warning, no error; only the alternate theme is wrong.
-**Safe change:** Any token whose value is `var(--app-var)` goes in the `@theme inline` block, raw literal values in plain `@theme`; after adding tokens, toggle `data-theme` and `data-style` in devtools and confirm the new utilities respond in both states.
+**Contract:** `@theme inline { --color-primary: var(--primary) }` makes utilities emit the *referenced* variable (`background-color: var(--primary)`), resolved per-element at runtime — the org's theming (token values swapped under `.dark`, and the personality.css `:root`/`.dark` overrides) only flows through utilities via the `inline` form.
+**Detect:** `@theme inline`, plain `@theme {`, token values that are `var(--…)`, `:root:not(.dark)`/`:root.dark` blocks in `design.tokens.css`, `:root`/`.dark` blocks in `personality.css`
+**Ships green, breaks:** Adding a var-referencing token to a plain (non-`inline`) `@theme` block compiles and looks correct in light mode; toggling `.dark` or recompiling the personality then silently fails to restyle those utilities, because the theme variable captured the referenced var's value as resolved at `:root` — mode-scoped and subtree overrides never reach it. No warning, no error; only the alternate mode is wrong.
+**Safe change:** Any token whose value is `var(--app-var)` goes in the `@theme inline` block, raw literal values in plain `@theme`; after adding tokens, toggle the `.dark` class on the root element in devtools and confirm the new utilities respond in both modes.
 
 ## tailwind-source-detection — HIGH · generated-artifact
 **Contract:** The generated stylesheet contains only class names that appear as complete, unbroken literal strings in scanned source files — the build-time scanner vs class names assembled at runtime; the default scan set skips `.gitignore`d paths and `node_modules`.
@@ -62,16 +62,16 @@ Load when: the touch list exhibits Redux Toolkit (`createSlice`, `configureStore
 **Ships green, breaks:** `bg-${color}-500` builds and renders unstyled — the utility is simply absent from the CSS. Class names stored in data or composed in unscanned code work only as long as some scanned file coincidentally contains the same literal — deleting that last literal usage breaks a "different" feature. Gitignored source directories are silently excluded from scanning.
 **Safe change:** Always write full class literals and select via lookup maps (`{primary: 'bg-blue-600'}[variant]`); safelist genuinely dynamic sets with `@source inline("…")` (v4.1+); add explicit `@source "…"` for out-of-tree or ignored directories.
 
-## dark-variant-data-attributes — HIGH · rendezvous-string
-**Contract:** `@custom-variant dark (&:where([data-theme=dark] *))` and the personality selectors `[data-theme="…"]`/`[data-style="…"]` rendezvous on the exact attribute name+value that runtime JS stamps on `<html>` (`document.documentElement.dataset.theme/style`).
-**Detect:** `@custom-variant dark`, `[data-theme=`, `[data-style=`, `dataset.theme`, `setAttribute('data-theme'`, `classList.add('dark')`
-**Ships green, breaks:** Without the `@custom-variant dark` override, Tailwind's default `dark:` variant is the `prefers-color-scheme: dark` media query — every `dark:` class silently follows the OS setting and ignores the app's toggle entirely. A value or mechanism mismatch (JS writes `class="dark"` while CSS expects `[data-theme=dark]`, or a casing typo) leaves the alternate theme unreachable with zero errors. Org default is light: base tokens must stay scoped `:root, :root[data-theme="light"]` or unstamped pages render the wrong theme.
-**Safe change:** Define attribute name and values as one exported constant consumed by the toggle code; add `@custom-variant dark` the moment any `dark:` utility pairs with an attribute toggle; flip the attribute in devtools and verify both directions plus the no-attribute default.
+## dark-variant-class — HIGH · rendezvous-string
+**Contract:** `@nurix/components` declares `@custom-variant dark (&:is(.dark *))` and ships its dark values compiled as `.dark { … }`; the app's toggle, its own `dark:` utilities and its token blocks (`:root.dark`) rendezvous on the exact class `dark` stamped on the root element (`document.documentElement.classList`).
+**Detect:** `@custom-variant dark`, `classList.add('dark')`/`classList.toggle('dark'`, `:root.dark`, `.dark {`, and the mismatch signals `[data-theme=`, `dataset.theme`, `setAttribute('data-theme'`
+**Ships green, breaks:** A toggle that stamps `data-theme="dark"` instead of the class renders half-flipped with zero errors: the app's own attribute-keyed tokens invert while every library surface — its `dark:` variants, its compiled `.dark { … }` values, its theme toggle and toaster — stays light, because the library's selectors are compiled into distributed CSS and cannot be re-keyed. Without `@custom-variant dark` in the CSS entry, the app's own `dark:` classes fall back to Tailwind's default `prefers-color-scheme: dark` media query and follow the OS setting instead of the toggle. Light is the org default: light values sit on `:root:not(.dark)`, so a page with no class renders light.
+**Safe change:** Toggle only the `dark` class on the root element, from a pre-paint inline script plus the persisted-preference module; bind `@custom-variant dark (&:is(.dark *))` in the CSS entry; flip the class in devtools and verify both directions, plus the no-class default, on an app surface and a library component side by side.
 
 ## nurix-components-styles-tokens — HIGH · rendezvous-string
-**Contract:** `@nurix/components` is imported by subpath (`@nurix/components/button`) but styled through two separate channels — its own pre-built `styles.css` (imported in `globals.css`) and the app's semantic CSS variables (personality tokens like `--radius-*`, `--color-*`) that its rules read.
-**Detect:** `from '@nurix/components/`, the library `styles.css` `@import` line in `globals.css`, grep `var(--` in `node_modules/@nurix/components/**/styles.css`
-**Ships green, breaks:** Omitting the `styles.css` import renders every component fully functional but unstyled — no JS error, no build warning, no missing-module failure. Renaming or dropping a personality token the library reads silently degrades components to fallback/`initial` values (e.g. a flat archetype's `--radius-*: 0` re-assertion lost in a token refactor). The library is pre-built, so the app's Tailwind scanner never generates utilities for markup inside it — its shipped CSS is the only style source.
+**Contract:** `@nurix/components` is imported by layered subpath (`@nurix/components/element/button`) but styled through two separate channels — its `styles.css` (CSS-`@import`ed in `globals.css`) and the CSS variables its rules read: the app's theme colors and `--radius`, the `--intent-*` family, and the personality layer (`--radius-scale`, `--density-*`, `--edge-*`, `--ring-*`, `--elevation-*`).
+**Detect:** `from '@nurix/components/`, the library `styles.css` `@import` line in `globals.css`, grep `var(--` in `node_modules/@nurix/components/dist/styles.css`
+**Ships green, breaks:** Omitting the `styles.css` import renders every component fully functional but unstyled — no JS error, no build warning, no missing-module failure. Renaming or dropping a token the library reads silently degrades components to fallback/`initial` values (e.g. a sharp-edge personality's `--radius-scale` override lost in a token refactor). The app's Tailwind compiles the library's utilities: `styles.css` omits `@import "tailwindcss"` and carries an `@source` over the compiled JS, so its classes resolve against the app's theme — a JS `import` of `styles.css` (in `main.tsx`) compiles it standalone with no theme loaded and fails the build.
 **Safe change:** Keep the `styles.css` import at its mandated position in `globals.css`; before touching any personality token, grep the library's dist CSS for `var(--that-token)`; smoke-render a themed library component after every `@nurix/components` upgrade.
 
 ## vite-alias-tsconfig-paths — MED · dual-authority
@@ -81,10 +81,10 @@ Load when: the touch list exhibits Redux Toolkit (`createSlice`, `configureStore
 **Safe change:** Single-source the mapping (`vite-tsconfig-paths`, or generate both from one constant); update both files in the same commit on any directory move; when suspicious, log `import.meta.url` from the module in dev to see which file actually loaded.
 
 ## css-import-order — MED · lifecycle-protocol
-**Contract:** `globals.css` must import in the fixed sequence `@import "./personality.css"` → `@import "tailwindcss"` → the library's `styles.css` → `@theme inline {…}` — cascade-layer order is fixed at first appearance of each `@layer` name, so file position *is* the styling contract between Tailwind, the component library, and the personality tokens.
-**Detect:** first ~10 lines of `globals.css`, `@import "tailwindcss"`, `@import` of `@nurix/components` styles, `@layer` declarations inside the library CSS
-**Ships green, breaks:** Any reorder compiles and mostly renders — the breakage is visual-only and theme/element-specific: importing the library's `styles.css` before `@import "tailwindcss"` lets preflight's `@layer base` resets land after (and wipe) library button/form styling at equal specificity, and flips which side wins app-utility-vs-library override wars. Nothing logs; a form-heavy screen just looks subtly wrong.
-**Safe change:** Treat the four-line header as frozen; insert new global stylesheets at a deliberate position relative to `tailwindcss` and the library import, never appended blindly; after any reorder, visual-diff a form-heavy screen in every `data-theme`/`data-style` combination.
+**Contract:** The CSS entry (`globals.css`, or whatever the manifest names) must import in the fixed sequence `@import "./fonts.css"` → the project's `design.tokens.css` → `@import "tailwindcss"` → the library's `styles.css` → the project's `personality.css` → `@theme inline {…}` — cascade-layer order is fixed at first appearance of each `@layer` name, and `personality.css` is bare `:root`/`.dark` blocks that only *tie* the library's unlayered `:root`/`.dark` (0,1,0), so it wins only by following `styles.css`. File position *is* the styling contract between Tailwind, the component library, and the personality tokens.
+**Detect:** first ~10 lines of the CSS entry, `@import "tailwindcss"`, `@import` of `@nurix/components` styles, the `personality.css` `@import`, `@layer` declarations inside the library CSS
+**Ships green, breaks:** Any reorder compiles and mostly renders — the breakage is visual-only and theme/element-specific: importing the library's `styles.css` before `@import "tailwindcss"` lets preflight's `@layer base` resets land after (and wipe) library button/form styling at equal specificity, and flips which side wins app-utility-vs-library override wars; importing `personality.css` before `styles.css` lets the library's neutral personality defaults win the tie, so the product's density, motion, radius and depth silently revert to neutral. Nothing logs; a form-heavy screen just looks subtly wrong. (`design.tokens.css` writes `:root:not(.dark)`/`:root.dark` at (0,2,0) and wins wherever it sits.)
+**Safe change:** Treat the header as frozen; insert new global stylesheets at a deliberate position relative to `tailwindcss` and the library import, never appended blindly; after any reorder, visual-diff a form-heavy screen in light and dark (`.dark`).
 
 ## date-fns-local-tz — HIGH · serialized-shape
 **Contract:** Datetimes cross the wire as UTC ISO strings or date-only `YYYY-MM-DD`, but date-fns `format()` and accessors operate in the runtime's local timezone — serializer and formatter must agree on the zone, and nothing checks that they do.

package/data/harnesses/code/skills/boundary/references/packs/generic-tail.md

@@ -1,6 +1,6 @@
 # Generic tail — technologies outside the mandated stack
 
-Load when: the touched code exhibits one of these technologies and no dedicated pack covers it. Entries here are deliberately thin — one gotcha and the safe-change essence each; diagnose the rest from the mechanism (see `../mechanisms.md`). When the org adopts one of these seriously, promote its section into a full pack.
+Load when: the touched code exhibits one of these technologies and no dedicated pack covers it. Each entry is one gotcha and the safe-change essence; diagnose the rest from its mechanism in `mechanisms.md`. A technology the org adopts seriously gets its section promoted into a full pack.
 
 ## API styles
 

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

@@ -12,8 +12,8 @@ commits it.
 
 ## The architecture — one capability, two seats
 
-Prose obligations decay in the conversing seat: the fleet audit behind v3 found the same rules
-dying in every real session, even the successful ones. So the capability is split:
+Prose obligations decay in the conversing seat: an audit of real sessions finds the same rules
+dying in every one, the successful ones included. So the capability is split:
 
 | Seat | Component | Owns |
 | --- | --- | --- |
@@ -27,17 +27,15 @@ line, the twin writes the result — so reconciliation is observable, never asse
 
 ## The session lifecycle
 
-```
-/brainstorm start
-  → basis gate (a document, an old session folder of any format, or a brain dump)
-  → bootstrap docs/research/{topic}-brainstorm/ (ops/ untracked; twin writes the surface)
-  → converse: dump / interview / probe / blindspot / converge — steerable in plain language
-  → "let me read" anytime: compose on demand, read the thesis, come back
-/brainstorm stop
-  → converge → manifest → ONE user approval → apply → uselessness test
-  → folder moves to docs/history/brainstorms/{topic}/ (the completion marker)
-  → the user decides: delete or commit
-```
+- **`/brainstorm start`**
+  1. Basis gate — a document, a prior session folder in any format, or a brain dump.
+  2. Bootstrap `docs/research/{topic}-brainstorm/` — `ops/` untracked; the twin writes the surface.
+  3. Converse — dump, interview, probe, blindspot, converge — steerable in plain language.
+  4. "Let me read" anytime — compose on demand, read the thesis, come back.
+- **`/brainstorm stop`**
+  1. Converge → manifest → **one** user approval → apply → uselessness test.
+  2. The folder moves to `docs/history/brainstorms/{topic}/` — the completion marker.
+  3. The user decides: delete or commit.
 
 The working surface: `thesis.md` (claim → argument → what changed, recomposed whole, stamped),
 `forks.md` (open questions with close conditions — the only convergence currency), `ledger.md`