@nurix/etna 0.20.35 → 0.20.37

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

@@ -1,7 +1,7 @@
 {
   "harness": "etna",
   "name": "etna",
-  "version": "1.5.31",
+  "version": "1.5.32",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
@@ -14,5 +14,5 @@
     "origin": "https://cdn.nustack.io",
     "track": "latest"
   },
-  "digest": "2c3760e696b9"
+  "digest": "2e85809b94e3"
 }

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