@nurix/etna 0.20.2 → 0.20.3

package/data/catalog/rules/testing.md

@@ -30,9 +30,10 @@ Rules for the plan regime between the plan gate and the verification gate:
 **A discrete, user-triggered step.** When implementation is complete, report it and offer the gate — never run it unbidden, and never flip `Status: Complete` without it. An explicit user acceptance of finished plan work — "ship it", "commit", "looks good" — counts as the trigger; open the gate without asking again. A plan with outstanding obligations stays open, whatever the code does. The procedure — checklist, drive-then-pin ladder, row discharge, what earns a durable test — is the `testing` skill (gate mode).
 
 - **Precondition: the ledger exists.** A plan with no Test Obligations section is blocked at the gate — run the `testing` skill (plan-gate mode) on it first; an empty ledger passes vacuously and the gap surfaces only after the file is frozen.
-- **The verdict is never delegated** (the root policy file § Delegation), and where browser work is main-session-only (its § Runtime Notes), the driving is too. Fan-out may prepare fixtures or draft test bodies; the driving and the verdict stay inline.
+- **The verdict is never delegated** (the root policy file § Delegation), and where browser work is main-session-only (its § Runtime Notes), the driving is too. **Authoring test files is dispatched fan-out by default** — at any nesting level, sub-agents on the cheapest capable tier write the pins from the checklist and ledger rows while the gating agent keeps the checklist, the driving, the cold-shell suite run, and every discharge: a sub-agent's green claim is a report, and the verdict is the re-run. Only a lone regression test riding a bug fix stays inline — briefing a sub-agent costs more than the test.
 - **The gate needs no stronger tier than the session default** — a standard-tier session suffices whatever tier built the plan; the plan and its ledger carry all the state the gate needs, so gating in a fresh session loses nothing.
-- **Browser driving is the gate's final rung.** Playwright / Chrome CDP drives run once, at the end, after suites and cheap oracles are green — never interleaved mid-loop; they are the most expensive oracle in time and tokens.
+- **On a rendered surface, browser driving LEADS the gate — it is not its final rung.** The order inverted deliberately: the defects that reach users through an interface are geometric and compositional, and a simulated DOM computes no layout, so a suite that is entirely green says nothing about whether anything is where it should be. **Reach the browser Chrome-CDP-first and Playwright second** — CDP drives a real browser interactively and needs no script written in advance, which is what discovery requires; Playwright is the fallback where CDP is unavailable and the tool of record for whatever must run unattended afterwards. Cheap oracles run in the same pass and are what the drive's findings get pinned into; they are no longer a gate to pass before looking. A surface with nothing rendered — a CLI, a service, a library — drives its own real binary or wire instead, and this clause does not apply.
+- **A judged drive discovers; a scripted assertion guards.** Only the first finds a defect nobody has seen — a script asserting a control's value passes over a control drawn on top of its own label. Scripts are written after a judged drive names the class of defect, never generated ahead of one, and **a red script is never regenerated** — regeneration re-derives the assertion from the surface as it currently is, which turns a defect into the asserted truth with everything green.
 - **Report what happened, including failures.** A gate that reports green while a suite is red is worse than no gate; state the failing test and its output.
 - **Abandonment does not erase debt.** Before `Status: Abandoned` freezes a plan whose code was committed, convert its undischarged rows into backlog items; uncommitted code owes nothing.
 
@@ -40,13 +41,15 @@ Rules for the plan regime between the plan gate and the verification gate:
 
 Framework choice is **never** ad hoc and never the user's problem mid-task: detect the stack, use its row; if the repo already has a runner, that runner wins — **never** introduce a second framework beside it.
 
-| Stack | Unit / integration | Component | E2E | HTTP mocking | Don't use |
-| --- | --- | --- | --- | --- | --- |
-| Node + Vite / React (web) | `vitest` | `@testing-library/react` (+ `@testing-library/user-event`, `happy-dom`) | `@playwright/test` | `msw` | `jest`, `mocha`, `jasmine`, `cypress`, `enzyme` |
-| Express APIs | `vitest` | — | `supertest` against the app instance | `msw` (outbound calls) | `jest`, `chai-http` |
-| React Native / Expo | `jest` via the `jest-expo` preset | `@testing-library/react-native` | `maestro` | `msw` | `detox`, `enzyme` |
-| Cloudflare Workers | `vitest` + `@cloudflare/vitest-pool-workers` | — | `@playwright/test` against `wrangler dev` | `msw` | `jest` |
-| Rust | `cargo test` (built-in) | — | — | — | — |
+| Stack | Unit / integration | Component | Rendered (7b) | Judged drive | E2E | HTTP mocking | Don't use |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| Node + Vite / React (web) | `vitest` | `@testing-library/react` (+ `@testing-library/user-event`, `happy-dom`) | `vitest` browser mode, Playwright provider | Chrome CDP, else `@playwright/test` headed | `@playwright/test` | `msw` | `jest`, `mocha`, `jasmine`, `cypress`, `enzyme` |
+| Express APIs | `vitest` | — | — (nothing rendered) | the real wire — `curl`/HTTP against the running app | `supertest` against the app instance | `msw` (outbound calls) | `jest`, `chai-http` |
+| React Native / Expo | `jest` via the `jest-expo` preset | `@testing-library/react-native` | `maestro` on a device/simulator | the simulator, watched | `maestro` | `msw` | `detox`, `enzyme` |
+| Cloudflare Workers | `vitest` + `@cloudflare/vitest-pool-workers` | — | — (nothing rendered) | the real wire against `wrangler dev` | `@playwright/test` against `wrangler dev` | `msw` | `jest` |
+| Rust | `cargo test` (built-in) | — | the app window, driven by the OS layer where one exists | the running binary, watched | — | — | — |
+
+**The two new columns are the inversion made concrete.** *Rendered (7b)* is the unattended real-engine runner — where geometry pins live, and `—` where a stack renders nothing. *Judged drive* is what a person or an agent looks at when a change is finished, and it leads the gate on any stack that renders: Chrome CDP first because it drives a real browser with no script written in advance, Playwright headed where CDP is unavailable. A stack whose judged drive is `—` has no interface to look at, not permission to skip looking.
 
 Test packages install at `latest` — outside the approved-packages pin set. Fake data comes from `@ngneat/falso` — **never** `@faker-js/faker` / `chance`.
 
@@ -55,6 +58,7 @@ Test packages install at `latest` — outside the approved-packages pin set. Fak
 - **Suite, not scripts.** Tests live in the canonical test tree — `tests/` mirroring `src/`, or the convention the repo already uses — named `<subject>.test.ts`; shared fixtures, factories, and helpers in `tests/helpers/` (or the suite's existing shared home).
 - **Wire the canonical command.** `"test"` in `package.json` runs the whole unit suite (`vitest run`); e2e under `"test:e2e"`. A repo where `pnpm test` / `npm test` doesn't run the suite is misconfigured — fix the wiring, **never** route around it.
 - **Unit and E2E trees stay separate.** Vitest/Jest suites in `tests/`; Playwright/Maestro suites in `e2e/` with their own config — **never** mixed into the unit runner's glob.
+- **The real-renderer stratum is a third tree** — `tests/rendered/` under the unit runner's *browser mode*, its own config, kept to geometry regressions that shipped and the composition assertions a component library cannot make alone. It is not a second component suite; anything a simulated DOM can prove stays in `tests/component/`.
 - **No test doubles for what you own.** Prefer real instances — in-memory SQLite for drizzle, the actual Express app via `supertest` — over mocks; mock **only** true externals (network via `msw`, time via the runner's fake timers).
 - **Determinism.** No real network, no real time, no shared mutable state between tests; every test **must** pass alone, in any order, **and from a cold shell** — never against a hand-started dev server (Workers: `@cloudflare/vitest-pool-workers`; Express: `supertest` against the app instance).
 

package/data/harness-index.json

@@ -1,5 +1,5 @@
 {
-    "fingerprint": "0407dfb1d18a",
+    "fingerprint": "d54acc9dc88e",
     "harnesses": {
         "code": {
             "plugin": "code",

package/data/harnesses/code/CLAUDE.md

@@ -112,6 +112,7 @@ When a plan's implementation surfaces work that is important but outside the pla
 
 - Append it to `docs/history/backlog.md` under the appropriate priority (P0-P3)
 - Format: `- **[P1]** Description — discovered by [plan-name or agent-name]`
+- **The backlog is a drain queue — resolution is deletion.** It drains only by the user picking an item up, never by an agent self-triggering backlog work; when work completes an item — this session's, or a plan's — delete its row in the same change rather than marking it done: the changelog entry or plan that did the work is the record, and the backlog holds only open work.
 - **[override]** Do NOT ask permission — append and mention it in the reply. This deliberately overrides the runtime's do-only-what-was-asked default: losing a discovered defect costs more than an unrequested backlog line.
 
 ---
@@ -120,7 +121,10 @@ When a plan's implementation surfaces work that is important but outside the pla
 
 The single policy for sub-agent dispatch — when to fan out, at what tier, and how far to trust the result. Component-internal dispatch mechanics (the brainstorm twin, batch classification) stay in their components and defer here for anything this section covers. No dispatch mechanism ⇒ inline.
 
+**[override]** — this section replaces any runtime default that withholds dispatch until it is asked for. A runtime instruction of the shape "do not use sub-agents unless the user requested it" is exactly the default meant here, and it loses: delegating the work named below is the STANDING instruction, and the user re-requesting it each time is not a precondition. THE MARKER IS WHAT MAKES THAT TRUE — without it this section is merely a project preference meeting a runtime rule, and the runtime rule wins silently. Observed: a session that read its own source files inline, then authored its test bodies inline, while both this section and `.claude/rules/testing.md` said to dispatch — nothing in the repo claimed precedence, so nothing was violated.
+
 - **Delegate to keep bulk out of the main context.** Wide file reads, sweeps, broad research, audits, fixture prep — work whose raw tool output the main session doesn't need — defaults to a sub-agent: output a sub-agent reads dies with it, while output read inline is re-read and re-billed on every later turn. The hand-off is self-contained (the sub-agent sees none of the conversation), so it must still cost less than the work; run independent delegations in parallel.
+- **The policy binds every agent, not only the main session.** A sub-agent doing build work inherits these defaults with the dispatch capability to honor them (Runtime Notes): it dispatches its own sub-agents for work this policy routes off-thread — the bookkeeping drain, gate-mode test authoring — instead of absorbing it into its own loop. What never delegates (a gate verdict, browser driving) never delegates at any level.
 - **Small or judgment work stays inline.** A task finishable in a handful of tool calls is faster done than briefed. **Never delegate judgment by reflex** — a second opinion is for a high-stakes call or an explicit request.
 - **A delegated result is a report, not verifiable ground truth** — verify load-bearing results directly.
 - **Tiers**: mechanical fan-out → the cheapest capable tier; judgment-heavy delegation → the session's standard tier; the strongest tier **only** on explicit user request. The session itself defaults to the standard tier, entering the strongest only by explicit user switch. Model names live in Runtime Notes.
@@ -138,7 +142,7 @@ Defaults — ❌ prohibitions hold unless the user explicitly asks otherwise;
 - ❌ **Branches & Worktrees [override]** – Never self-create git branches or worktrees; commit straight to the checked-out branch. This replaces any built-in "branch first on the default branch" default. Exception: when the user asks for a pull request, create the branch the PR requires before committing its changes.
 - ❌ **Protected Files** – Once per session, if `docs/operations/protected-files.md` exists, read it and never modify any path it lists; never modify `AGENTS.md` (harness-regenerated) or `protected-files.md` itself.
 - ✅ **Browser Automation** – If the runtime provides browser automation, use it freely; no need to ask first. If it doesn't — or the executing agent can't hold the browser connection (see Runtime Notes) — return a browser-verification checklist (URLs, actions, expected outcomes) for the orchestrating session or the user to run.
-- ✅ **Bookkeeping** — hooks append doc-debt rows to `docs/operations/bookkeeping.md`; three walls read it at three widths (Stop = your session's rows · commit = rows implicating staged files · CI = all), each re-verifying conditions at gate time. Dispatch the `bookkeeper` for your rows; a drained row is **deleted**. The full grammar arrives in the deny message when a wall fires.
+- ✅ **Bookkeeping [override]** — dispatching outranks a runtime default that reserves sub-agents for explicit requests (§ Delegation), and `hooks/compliance.mjs` enforces it: Stop is blocked on unresolved rows unless the transcript carries a real `subagent_type: bookkeeper` record. Hooks append doc-debt rows to `docs/operations/bookkeeping.md`; three walls read it at three widths (Stop = your session's rows · commit = rows implicating staged files · CI = all), each re-verifying conditions at gate time. Dispatch the `bookkeeper` for your rows — **never drain `auto:`/`note:` rows in your own loop**, whichever agent you are: the drain is dispatched work at every nesting level (a sub-agent dispatches its own `bookkeeper` — § Delegation), and only `needs-session:` rows are yours to resolve directly. A drained row is **deleted**. The full grammar arrives in the deny message when a wall fires.
 - ✅ **Session gate log** — a denial with no `resolved` line blocks Stop; resolution mechanics arrive in the block message. Never delete log lines.
 - ✅ **Cleanup removes the cause, not the record of it.** When the user asks for something to be deleted or cleaned up, the ask is for the underlying condition to be gone. Deleting the record while the condition survives is worse than doing nothing — it destroys the only evidence the debt exists. The order is fixed: **read what the record is masking** (a `waived:` row, an `UNBUILT:` marker, a `status:` flag, a lint suppression — each asserts something is fine; check whether that is still true), **fix the condition**, **then delete the record**. Reversing it backfires concretely: a deleted waiver's finding is re-appended by the detector as an `auto:` row, which *fails* the commit wall the `waived:` row passed.
 - ✅ **Delegation** — when to fan out, tiers, and trust are § Delegation.

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

@@ -1,6 +1,6 @@
 ---
 name: bookkeeper
-description: Drains docs/operations/bookkeeping.md — performs mechanical fixes (owns: globs, header comments, doc-lint findings, index rows), expands note: rows into doc edits, deletes each row it drains. Dispatched by the main session at turn end or commit time; never self-triggers. Triggers on "drain the bookkeeping queue", "dispatch the bookkeeper", "/bookkeeper".
+description: Drains docs/operations/bookkeeping.md — performs mechanical fixes (owns: globs, header comments, doc-lint findings, index rows), expands note: rows into doc edits, deletes each row it drains. Dispatched at turn end or commit time by whichever agent holds the rows — the main session or an executor sub-agent (nested dispatch); never self-triggers. Triggers on "drain the bookkeeping queue", "dispatch the bookkeeper", "/bookkeeper".
 tools: Read, Glob, Grep, Edit, Write, Bash, Skill
 model: sonnet
 ---

package/data/harnesses/code/agents/issue-bridge.md

@@ -0,0 +1,16 @@
+---
+name: issue-bridge
+description: The bulk-triage shell for the issue-bridge skill — dispatched when tracker work is too big for the main session (a triage sweep over many issues, a batch filing of harness findings). Thin by design; the method lives in the issue-bridge skill and the tracker access in its connector packs — this agent adds only isolation, batching, and the report contract. Triggers on "triage the backlog", "sweep the new issues", "file these findings", "/issue-bridge <batch>".
+tools: Read, Glob, Grep, Edit, Write, Bash
+model: sonnet
+---
+
+# Issue-Bridge Agent
+
+You are the execution shell for bulk tracker work. Your FIRST action: read the `issue-bridge` skill in `.claude/skills/issue-bridge/SKILL.md` — it is the method — then the connector pack for the tracker(s) in play under its `references/trackers/`. This file adds only what a batch needs beyond the skill:
+
+- **Batching.** Many items → triage each independently through the skill's method; one dossier per item, never a merged mega-dossier. Order by tractability (concrete symptoms first); if the batch is larger than the session can honestly cover, cover fewer items *fully* and name what you dropped — announced omission over silent thinning.
+- **Shared context once.** Load the ownership index, the owning-doc map, and the codegraph tier once at the start; reuse across items instead of re-deriving per issue.
+- **Approval aggregation.** Anything that would write to the tracker accumulates into one approval list presented at the end — never one ask per item, never a write without the ask.
+- **Report contract** (machine-read): per item — id · classification · verdict (one line) · confidence · dossier path; then the batch tail — items dropped (with reason), tracker writes awaiting approval, defects found in the skill or connector packs (a field run is always also a test of the method).
+- All the skill's boundaries bind you unchanged; a standing repo ruling (e.g. "never post to this upstream") overrides any approval you're offered.

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

@@ -1,6 +1,6 @@
 ---
 name: maintenance
-description: The single docs steward. Default behavior is the docs-vs-code coherence audit — detects and fixes docs drifting from code (stale docs, broken ownership, unowned source paths, architecture/backlog drift). An additive **baseline mode** layers structural reconcile on top: when the repo's `harness-version` marker is missing or behind, it converges `docs/` to the installed harness shape (scaffold the standard tree, fold dissolved-shape artifacts forward, stamp the version, propose modules) before running the audit. Mode is auto-selected from the marker. Run weekly, after major changes, or to baseline/upgrade a repo. Cross-cutting contract analysis is the `boundary` skill (`check` for plans, `scan` for diffs) — it derives contracts dynamically from source; there are no persisted boundary docs to audit. Triggers on "run maintenance", "docs health", "baseline this repo", "reconcile the harness", "upgrade the harness", "is this repo on the current harness", "/maintenance".
+description: The single docs steward. Default behavior is the docs-vs-code coherence audit — detects and fixes docs drifting from code (stale docs, broken ownership, unowned source paths, architecture/backlog drift). An additive **baseline mode** layers reconcile on top: when the repo's `harness-version` marker is missing or behind — **or its documents are behind their genre's current schema even though the folder tree is not** — it converges `docs/` to the installed harness (scaffold the standard tree, fold dissolved-shape artifacts forward, converge every truth document to its template's current schema while leaving frozen records alone, stamp the version, propose modules) before running the audit. Mode is auto-selected from the marker. Run weekly, after major changes, or to baseline/upgrade a repo. Cross-cutting contract analysis is the `boundary` skill (`check` for plans, `scan` for diffs) — it derives contracts dynamically from source; there are no persisted boundary docs to audit. Triggers on "run maintenance", "docs health", "baseline this repo", "reconcile the harness", "upgrade the harness", "is this repo on the current harness", "/maintenance".
 tools: Read, Glob, Grep, Edit, Write, Bash
 model: opus
 ---
@@ -28,7 +28,9 @@ Decide the mode once, up front, from the version marker — then run.
    | behind on minor/patch | **probe first**, below |
    | equal to installed | **audit only** (the default spine) |
 
-   **The probe.** Run the Step B2 detection pass read-only: if any `*.bkp.*` file sits under `docs/` (a fold awaiting its pass), **or** any **scaffolded file** in the target tree is missing (`docs/README.md`, `docs/structure.md`, `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/main.md`), the shape *did* change ⇒ **baseline mode**. Only when the probe finds nothing ⇒ re-stamp the version (no reshape), then audit.
+   **The probe.** Run the Step B2 **and B2b** detection passes read-only: if any `*.bkp.*` file sits under `docs/` (a fold awaiting its pass), **or** any **scaffolded file** in the target tree is missing (`docs/README.md`, `docs/structure.md`, `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/main.md`), **or B2b finds truth documents behind their genre's current schema**, the shape *did* change ⇒ **baseline mode**. Only when the probe finds nothing ⇒ re-stamp the version (no reshape), then audit.
+
+   **The third clause is not optional, and it is the one that used to be missing.** A repo can hold the current folder tree, every scaffold present, and still have every document in it written to a schema two minors old — because a genre's shape lives in its template, not in the directory layout. Probing only for absent scaffolds meant such a repo re-stamped its version and declared itself current, which is how a stamp comes to certify a tree nobody converged. **The version marker asserts the documents match the installed harness, not merely that the folders do.**
 
    > **Never probe on a missing folder.** Git does not track empty directories, so an unused folder is absent on every clone — reading that as drift puts the repo in baseline mode *forever*. Only the five scaffolded files above are shape signals; every folder in the target tree is created on first use.
 3. **Precondition for baseline mode:** a root `CLAUDE.md` must exist. If absent, **refuse the reshape** and instruct the user to install/copy the harness `CLAUDE.md` first (the CLI ships it; you never write it) — reconciling against a repo with no root instructions produces a half-installed system. Detect-and-instruct, not a hard gate on the audit.
@@ -60,6 +62,14 @@ For each `owns:` glob across the feature docs:
 - Flag **equal-specificity overlaps** — two feature docs whose `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.
 
+**Then validate the doc→doc edges — `owns:` is only half the graph.** `node .claude/hooks/check-ownership.mjs` and the session-injected **doc edge index** carry both directions; read the edge index and check three things:
+
+- **Dangling edges.** A `verifies:` or `applies:` naming a doc that does not exist is remediation, not a question — fix the path, or drop the edge when its target was deleted deliberately. The generated index marks these `← TARGET MISSING`.
+- **Checklists with no `verifies:`.** Every `docs/tests/` file names the doc whose promises it proves. A checklist without one is unreachable — nothing implicates it when its subject moves — so it is the single highest-value backfill in the tree, and it is mechanical wherever a same-named feature doc exists (`docs/tests/auth.md` → `docs/features/auth.md`). Where the name does not match, ask rather than guess.
+- **Architecture docs nothing declares.** An architecture doc named by no `applies:` is either genuinely unbound or a doctrine everyone obeys and nobody declares. Both are worth reporting; neither is auto-fixable, because `applies:` states an obligation only the consuming doc's author can assert. Report the list; backlog the judgement.
+
+**Never author an inverse to fix a gap.** A doc listing its own verifiers or consumers is a defect — the inverse is generated. If the index looks wrong, the frontmatter at the consuming end is what is wrong.
+
 For each code symbol or path a doc explicitly **names** (function/export/route/type):
 
 - Verify it resolves in the code, independent of git-churn — Step 3's churn gate is blind to churn-free false claims.
@@ -167,14 +177,33 @@ Detecting and folding old-shape artifacts is what makes a baseline more than a f
 | `*.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 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 |
+| feature / UX docs with no `applies:`, in a tree whose `docs/architecture/` is non-empty | **report, never invent.** `applies:` is an obligation the doc's author asserts, not a similarity a scan can infer; a guessed edge is worse than a missing one because it reads as declared. List the candidates (architecture docs the feature's prose already links) and backlog the confirmation |
 
 **The support window: three past minor versions.** The fold table covers shapes at most three minors behind the installed harness — which today means the rows above, because every older dissolved construct (`docs/routing.md`, `docs/modules/`, pillars, the Refinement Ledger, the ADR genre, legacy brainstorm folders, …) predates the window. An older shape is **reported, never improvised**: name what the probe found, point the user at etna's dated migration runbooks (`docs/history/migrations/` in the forge), and recommend a fresh baseline over an archaeological fold — a repo more than three minors behind re-baselines rather than migrates.
 
+### Step B2b — Converge documents to their genre's current schema
+
+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.
+
+**The two natures split the treatment, and the split is absolute.**
+
+| Nature | Genres | Treatment |
+| --- | --- | --- |
+| **Truth document** | features, ux, architecture, operations, `docs/tests/` checklists, `structure.md`, READMEs | **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) |
+
+**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.
+
+**Scale gate — confirm once, not per file.** Count the convergences first and fold them into B3's single reconcile table as `Fold` rows. Where the count is large (roughly **20+ files, or any change spanning more than one genre**), state the counts per genre in that table and take B3's one approval for the whole set — a per-file prompt turns a mechanical upgrade into an interrogation and gets abandoned halfway, which leaves a tree half-converged and a version marker that lies about it. Where a genre's convergence is judgement-heavy rather than mechanical, split it out as its own row so approval is informed rather than bundled.
+
 ### Step B3 — Present the reconcile plan, then execute
 
 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; add `Status:` to plan files; for each feature doc, derive and write its `owns:` globs (+ `module:` label + `keywords:`) from the source it describes 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 `owns:` globs (+ `module:` label + `keywords:`) 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.
 
 Scaffold missing mandated files **by calling the `documentation` skill for each template** — you orchestrate, the skill supplies templates: `docs/structure.md` (with `harness-version`), `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/main.md`, and the repo-root `README.md` (filled from the real lockfile/scripts/layout — **never overwrite an existing root README**).
 
@@ -182,6 +211,8 @@ Scaffold missing mandated files **by calling the `documentation` skill for each
 
 Write `harness-version: <installed version>` (the semver from `.claude/harness.json`) into `docs/structure.md` frontmatter. This single field is the repo's baseline-and-version sentinel — there is no second marker (no `epoch`, no `docs/memory/index.md` "is-baselined" check).
 
+**Stamp only what converged.** The marker asserts the repo's *documents* match the installed harness, not merely its folders — so it is written after B2b has run and its truth-document convergences have landed. Where B2b's set was too large to finish in one pass, stamp nothing and say what remains: a version marker ahead of the tree it describes is worse than an absent one, because every later probe trusts it and skips the work.
+
 ### Step B5 — Module proposal
 
 Modules are **labels, declared, never inferred from physical layout**. Derive the repo's candidate bounded contexts directly from the code and docs: distinct wire surfaces (who owns routes/handlers), schema/data-access ownership, entry points and process units, plus any contexts `docs/architecture/` already names.
@@ -206,6 +237,8 @@ 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: `owns:` · `module:` · `keywords:` · `status:` · `last-reviewed:` · `type: feature` · `derivation: "extracted (baseline YYYY-MM-DD, codegraph + source read)"`), plus the architecture, tests, and operations layers. Use the `codegraph` 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.
+- **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: codegraph 0.2.0`): use it — check `codegraph projects` for staleness, re-run `codegraph index` if HEAD has moved, then localize every question through the index before reading source. **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: codegraph 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.
 - **Modules are labels, layout-blind.** Seed from the code's bounded contexts; never from `pnpm-workspace.yaml`/workspace walls. Propose, don't force; acting is a `module:` tag, never a folder.
 - **You orchestrate docs; the `documentation` skill supplies templates.** It is a library — never expect it to baseline.

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

@@ -19,7 +19,7 @@ Technical documentation for this project.
 The records — everything dated, frozen, or append-only.
 
 - [CHANGELOG.md](history/CHANGELOG.md) - Master changelog index
-- [backlog.md](history/backlog.md) - Tracked work items and technical debt
+- [backlog.md](history/backlog.md) - Open work items and technical debt — a drain queue; done items are deleted
 
 ---
 

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

@@ -1,6 +1,6 @@
 # Backlog
 
-Tracked work items, technical debt, and planned improvements. Append new items under the appropriate priority.
+Open work items, technical debt, and planned improvements — a drain queue, not a ledger. Append new items under the appropriate priority; the queue drains only by the user picking an item up. When work completes an item, delete its row — never mark it done in place: the changelog entry or plan that did the work is the record, and this file holds only open work.
 
 ---
 

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

@@ -59,13 +59,13 @@ Every doc is a **truth document** (states current absolutes, topic-named, update
   states what a person *observes*, so a wire change lands, the interface absorbs it, and the
   absorption reads as maintenance. This document is what such a change contradicts. It **decides**
   behavior and is written before the code; the `docs/tests/` checklist only verifies it afterwards.
-- `docs/tests/`: Testing strategy and test docs. Present when the repo has a test posture worth documenting.
+- `docs/tests/`: Behavioral checklists — the verification gate's driving scripts, one per feature (`docs/tests/{feature}.md`). **Each carries `type: checklist` and `verifies:`** — the feature or UX doc whose promises it proves. That edge is what makes a checklist reachable: a same-named file is a coincidence a resolver cannot trust, so without `verifies:` nothing implicates the checklist when its subject changes and it rots undetected. The inverse — which checklists cover a feature — is generated and injected, never listed in the feature doc.
 - `docs/history/plans/`: Records. Must have `Status:` field. Never modify after completion.
 - `docs/history/changelog/`: Records. One entry per unit of work (`YYYY-MM-DD-{three-words}.md`), written by whoever does the work and frozen inside the commit it describes. Entries carry the refinement context a diff cannot show — the ask in the user's words, iterations and rejections, skill survived/overridden verdicts, discoveries, pins. Format is the `documentation` skill's `templates/changelog-entry.md`; trigger and lifecycle are the `changelog` rule; distillation is the `retro` agent. Immutability begins at commit — a draft in the working tree is mutable until then, never after. Every entry appends a row to `docs/history/CHANGELOG.md`.
 - `docs/history/migrations/`: Records. One-shot migration/upgrade runbooks — authored before execution, outcome-stamped and frozen after.
 - `docs/history/research/{topic}/`: Deep-research artifacts — the dumped output of a research pass, one folder per topic (conventionally `README.md` synthesis + `findings.md` verified claims & citations + `sources.md`). A point-in-time, cited record — **not** a living authority doc: it owns no code (no `owns:` frontmatter) and is never edited to "stay current." A spec/plan links to it for grounding; a new question gets a new topic folder.
 - `docs/research/{topic}-brainstorm/` → `docs/history/brainstorms/{topic}/`: Brainstorm design records — the Brainstorming-Mode session for a topic (working surface `thesis.md` + `forks.md` + `ledger.md` + `state.md` + `basis/` + `fragments/`, plus an untracked `ops/` capture layer deleted at stop), written by the `brainstorm` skill and its twin agent. An active session lives under `docs/research/` (legacy folders carry the older `-brainstorming/` suffix); on a **passed harvest** it **moves** to `docs/history/brainstorms/` — the completion marker — and the **user decides whether the moved folder is deleted or committed** as provenance. Each of the two folders carries a `Readme.md` index (the skill reads it at start instead of scanning). Author-created (never scaffolded empty), one folder per design conversation. Owns no code (no `owns:` frontmatter); the harvest routes its conclusions into `architecture/`/`features/`/`history/`. (Distinct from `docs/history/research/{topic}/` above — that is a frozen deep-research record, not a brainstorm session.)
-- `docs/history/backlog.md`: Tracked work items. Append new items under appropriate priority.
+- `docs/history/backlog.md`: Open work items — a drain queue: append on discovery, delete when done (the changelog entry or plan that did the work is the record).
 
 ## Health Log
 

package/data/harnesses/code/harness.json

@@ -1,7 +1,7 @@
 {
   "harness": "code",
   "name": "code",
-  "version": "3.11.1",
+  "version": "3.13.1",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
@@ -15,5 +15,15 @@
     "docs/memory/main.md",
     ".mcp.json"
   ],
-  "digest": "47ab9c67add4"
+  "tools": [
+    {
+      "name": "codegraph",
+      "probe": "codegraph --version",
+      "min": "0.2.1",
+      "install": "npm install -g @nurix/codegraph",
+      "skill": "codegraph"
+    }
+  ],
+  "docsRoot": "docs",
+  "digest": "af8ccf4c5383"
 }

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

@@ -12,6 +12,7 @@ import {
   readStdin,
   resolveProjectDir,
   buildIndex,
+  buildEdgeIndex,
   scanFeatureDocs,
   owningDocs,
   listRepoFiles,
@@ -29,8 +30,9 @@ import {
   waiverCovers,
   stateDir,
   recordTouched,
+  readDecision,
 } from "./lib/state.mjs";
-import { readSafe, relIfInside, today, SOURCE_EXT, commandRoot } from "./lib/repo.mjs";
+import { readSafe, relIfInside, today, SOURCE_EXT, commandRoot, docsRoot } from "./lib/repo.mjs";
 import { sweepResolvedRows, docLint, hasHeaderComment } from "./lib/sweep.mjs";
 import { listPlans } from "./lib/plans.mjs";
 import { frozenStatusAtHead } from "./lib/frozen.mjs";
@@ -64,6 +66,54 @@ function detectPackageManager(projectDir) {
   return null;
 }
 
+
+// Tools are the harness's EXECUTABLE dependencies (resolved from the manifest's `tools:` key into
+// .claude/harness.json at install): probed at SessionStart, never assumed, never required.
+//
+// TWO TIERS, deliberately — `present` and `absent`. An earlier draft reported `present-fresh`,
+// which the probe cannot actually know: `codegraph --version` proves a binary exists and says
+// nothing about whether THIS repo is indexed. A 22k-commit repo indexed at 23% once reported
+// present-fresh, and a probe that over-claims is worse than an absent tool, because absence
+// degrades honestly. Index freshness is established by the skill on its first query, where the
+// tool answers for itself. The `min-version` check is a different claim — the binary's own
+// version, which the probe CAN verify — so it survives.
+//
+// A DECLINED tool prints nothing at all. Once the user has answered "not here", a standing notice
+// is nagging, not information; the decision lives in .claude/state/decisions.tsv and outlives the
+// session. Probe cost measured 2026-08-20: 2ms absent (ENOENT returns immediately), 82ms present —
+// absence is the cheap path, so nobody pays for a tool they do not have.
+function toolsLines(projectDir) {
+  let marker = null;
+  try {
+    marker = JSON.parse(readSafe(path.join(projectDir, ".claude", "harness.json")));
+  } catch (e) {
+    return [];
+  }
+  const tools = Array.isArray(marker && marker.tools) ? marker.tools : [];
+  const out = [];
+  for (const tool of tools.slice(0, 8)) {
+    if (!tool || !tool.name || !tool.probe) continue;
+    if (readDecision(projectDir, `tool.${tool.name}`) === "declined") continue;
+    const [cmd, ...args] = String(tool.probe).split(/\s+/);
+    const res = spawnSync(cmd, args, { cwd: projectDir, timeout: 3000, encoding: "utf8" });
+    if (res.status === 0) {
+      const version = (res.stdout || "").trim().split("\n")[0];
+      let extra = "";
+      if (tool.min && version) {
+        const v = (/(\d+[\d.]*)/.exec(version) || [])[1];
+        if (v && v.localeCompare(tool.min, undefined, { numeric: true }) < 0)
+          extra = ` — BELOW min ${tool.min}; update: ${tool.install || "see etna/tools/" + tool.name + ".md"}`;
+      }
+      out.push(`Tool: ${version}${extra}`);
+    } else {
+      out.push(
+        `Tool: ${tool.name} MISSING — agents fall back to cold reads; install: ${tool.install || "see etna/tools/" + tool.name + ".md"}`,
+      );
+    }
+  }
+  return out;
+}
+
 function harnessLine(projectDir) {
   let marker = null;
   try {
@@ -72,7 +122,8 @@ function harnessLine(projectDir) {
     /* absent or unparseable — no line */
   }
   if (!marker || !marker.version) return null;
-  const structure = readSafe(path.join(projectDir, "docs", "structure.md"));
+  const root = docsRoot(projectDir);
+  const structure = readSafe(path.join(projectDir, root, "structure.md"));
   const stamped = (/harness-version:\s*([\w.-]+)/.exec(frontmatter(structure) || structure) || [])[1];
   const state =
     stamped === marker.version
@@ -80,18 +131,19 @@ function harnessLine(projectDir) {
       : stamped
         ? `stamped ${stamped} — behind: run maintenance`
         : "unstamped — run maintenance";
-  return `Harness: installed ${marker.version} · docs/structure.md ${state}`;
+  return `Harness: installed ${marker.version} · ${root}/structure.md ${state}`;
 }
 
 function memoryLine(projectDir) {
-  const dir = path.join(projectDir, "docs", "memory");
+  const root = docsRoot(projectDir);
+  const dir = path.join(projectDir, root, "memory");
   let entries;
   try {
     entries = fs.readdirSync(dir).filter((f) => f.endsWith(".md"));
   } catch (e) {
     return null;
   }
-  return entries.length ? `Memory: ${entries.map((f) => `docs/memory/${f}`).join(", ")}` : null;
+  return entries.length ? `Memory: ${entries.map((f) => `${root}/memory/${f}`).join(", ")}` : null;
 }
 
 function openPlanLines(projectDir) {
@@ -193,6 +245,10 @@ function sessionStart(projectDir, payload = {}) {
   if (pm) lines.push(`Package manager: ${pm}`);
   const harness = harnessLine(projectDir);
   if (harness) lines.push(harness);
+  // Always emitted, harness marker or not — the authoritative declaration a zero-context agent
+  // reads before it guesses "docs/" for a repo that renamed the tree (e.g. docs-nurix/).
+  lines.push(`Docs root: ${docsRoot(projectDir)}/`);
+  lines.push(...toolsLines(projectDir));
   const memory = memoryLine(projectDir);
   if (memory) lines.push(memory);
   lines.push(...openPlanLines(projectDir).slice(0, 4));
@@ -214,7 +270,10 @@ function sessionStart(projectDir, payload = {}) {
     ? "# Session context (generated — a convenience, never a gate)\n" + lines.slice(0, 12).join("\n")
     : "";
   const index = buildIndex(projectDir);
-  const context = [block, index].filter(Boolean).join("\n\n");
+  // The doc→code index answers "which doc owns this file"; the edge index answers "which docs does
+  // this doc implicate" — both directions of the same graph, and neither is hand-maintained.
+  const edges = buildEdgeIndex(projectDir);
+  const context = [block, index, edges].filter(Boolean).join("\n\n");
   if (!context) return;
   process.stdout.write(
     JSON.stringify({
@@ -230,6 +289,7 @@ function sessionStart(projectDir, payload = {}) {
 function detectorForFile(projectDir, rel, meta, rows) {
   const owners = owningDocs(projectDir, rel);
   recordTouched(projectDir, rel, owners.map((o) => o.doc), meta.sessionId);
+  const root = docsRoot(projectDir);
 
   if (rel.endsWith(".md")) {
     // An edited doc resolves any doc-implicated row that pointed at it.
@@ -241,7 +301,7 @@ function detectorForFile(projectDir, rel, meta, rows) {
     // would tick without reading the code. Raising it here rather than walling it at Stop is what
     // gives it the queue's three existing walls (Stop, commit, CI) instead of a fourth special case.
     // Resolve-then-append keeps exactly one row per plan, so re-editing never stacks duplicates.
-    if (rel.startsWith("docs/history/plans/")) {
+    if (rel.startsWith(`${root}/history/plans/`)) {
       const planText = readSafe(path.join(projectDir, rel));
       resolveRows(projectDir, (row) => row.kind === "needs-session" && row.body.includes(rel));
       if (/^\*\*Status:\*\*\s*Complete\b/m.test(planText) && undischargedDocRows(planText).length > 0) {
@@ -254,7 +314,7 @@ function detectorForFile(projectDir, rel, meta, rows) {
         );
       }
     }
-    if (rel.startsWith("docs/")) {
+    if (rel.startsWith(`${root}/`)) {
       const findings = docLint(projectDir, rel);
       if (findings.length) {
         rows.push(
@@ -267,12 +327,12 @@ function detectorForFile(projectDir, rel, meta, rows) {
         );
       }
     }
-    if (rel.startsWith("docs/features/") && !readSafe(path.join(projectDir, "docs", "README.md")).includes(path.basename(rel))) {
+    if (rel.startsWith(`${root}/features/`) && !readSafe(path.join(projectDir, root, "README.md")).includes(path.basename(rel))) {
       rows.push(
         formatAutoRow({
           ...meta,
           kind: "index-row-missing",
-          description: `${rel} is not linked from docs/README.md`,
+          description: `${rel} is not linked from ${root}/README.md`,
           action: "add its row to the Features index",
         })
       );
@@ -369,7 +429,7 @@ function mtimeFallbackPaths(projectDir) {
     }
   };
   walk("", 3, (name) => name === "package.json");
-  walk("docs/history", 4, (name) => name.endsWith(".md"));
+  walk(`${docsRoot(projectDir)}/history`, 4, (name) => name.endsWith(".md"));
   return out;
 }
 
@@ -413,7 +473,7 @@ function detectOutcomes(projectDir, meta, rows) {
         );
       }
     }
-    if (rel.startsWith("docs/history/")) {
+    if (rel.startsWith(`${docsRoot(projectDir)}/history/`)) {
       // Frozen AT HEAD, not in the worktree: the completion flip makes a plan dirty+Complete in
       // one edit, and the worktree predicate walled the very commit that ceremony requires.
       const frozen = frozenStatusAtHead(projectDir, rel);
@@ -458,10 +518,11 @@ function postToolUse(projectDir, payload) {
   } else {
     const rel = relIfInside(projectDir, input.file_path || input.notebook_path);
     if (rel) detectorForFile(projectDir, rel, meta, rows);
+    const root = docsRoot(projectDir);
     // Editing a feature doc's frontmatter can orphan globs the same way a rename can.
-    if (rel && rel.startsWith("docs/features/")) detectRenames(projectDir, "git mv", meta, rows);
+    if (rel && rel.startsWith(`${root}/features/`)) detectRenames(projectDir, "git mv", meta, rows);
     // A manifest or history file written by a non-Bash tool is the same evasion surface.
-    if (rel && (path.posix.basename(rel) === "package.json" || rel.startsWith("docs/history/"))) {
+    if (rel && (path.posix.basename(rel) === "package.json" || rel.startsWith(`${root}/history/`))) {
       detectOutcomes(projectDir, meta, rows);
     }
   }