@nurix/etna 0.20.6 → 0.20.8

package/data/harnesses/delivery/hooks/generate-ownership-index.mjs

@@ -142,15 +142,18 @@ function buildIndex(projectDir) {
     const keywords = asList(field(block, "keywords"));
     indexed += 1;
     const doc = path.relative(projectDir, file).split(path.sep).join("/");
+    // METADATA ONCE PER DOC, NOT ONCE PER GLOB — kept in step with lib/ownership.mjs buildIndex(),
+    // which the parity suite pins. Re-emitting the keyword array beside every glob made the index
+    // grow with the dependency graph rather than the doc count.
     const kw = keywords.length ? `[${keywords.join(", ")}]` : "[]";
-    for (const glob of owns) {
-      lines.push(`${glob} → ${doc} · ${moduleLabel} · ${kw} · ${status}`);
-    }
+    lines.push(
+      `${doc} · ${moduleLabel} · ${status}\n  ${kw}\n` + owns.map((glob) => `  ${glob}`).join("\n")
+    );
   }
   if (lines.length === 0) return "";
   lines.sort();
   const header =
-    "# Ownership index (generated) — code-path glob → owning feature doc · module · keywords · status\n" +
+    "# Ownership index (generated) — owning feature doc · module · status, then the code regions it governs.\n" +
     "# Match the file or topic you're about to touch, then read the owning doc before changing it.\n";
   // A doc dropped by a parse failure is indistinguishable from one that owns nothing,
   // so report the tally: seen vs indexed is the only signal a silent skip leaves.

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

@@ -6,7 +6,7 @@ correctly, the record stays readable at any pause, and the session ends with a h
 complete that the session folder is useless — it moves to history and the user deletes or
 commits it.
 
-> Spec (single source of truth): `docs/architecture/skills/brainstorm/` in the etna repo. The etna
+> Spec (single source of truth): `docs/skills/brainstorm/` in the etna repo. The etna
 > copy of this skill (`skills/brainstorm/`) is canonical; the user-level path
 > `~/.claude/skills/brainstorm/` is a symlink to it.
 

package/data/harnesses/delivery/skills/brainstorm/references/doctrine.md

@@ -96,3 +96,25 @@ These bind every writer of the working surface — facilitator (ops), twin (ever
 5. **Directional steering is not feature truth.** A harvested principle informs many decisions
    and changes slowly; a feature fact belongs to its feature doc and changes at code speed. The
    harvest links between the two layers, never duplicates prose across them.
+
+## Field lessons — capture and converge
+
+Measured on live sessions; each is the rule, distilled.
+
+- **Separate user voice from facilitator re-derivation before ledgering** when both arrive in one
+  turn. Only the user's half is ledgerable; a re-derivation that quietly re-reads an existing
+  commitment into a new shape is caught as a fork with a named amendment to the affected `D#`,
+  never as an edit — a commitment recorded in the user's words is amended only by the user.
+- **Stamp in UTC, always** — take the stamp from `date -u`, never from the runtime's injected
+  local date; the two disagree for part of every working day in some offsets, and a local-date
+  stamp runs the ledger a day ahead of capture.
+- **Run the blindspot pass immediately after a converge burst, before the manifest gate.** When
+  several picks land in one sitting the strain migrates *between* them — collisions between
+  commitments taken within the same hour, found only by reading two together. The burst is the
+  cheapest moment to catch them and the last before they freeze.
+- **When a pick answers three of a fork's four close-condition clauses, close it and file the
+  residue as a new fork in the same pass** — closing silently and leaving it open both lose
+  information; name the unanswered clause in the resolving entry and carry it under a new `F#`.
+- **When a ledger entry's `Why` contains "already", verify it before the manifest.** A commitment
+  that declines to build something because it already exists rests on a fact, not a judgment, and
+  the stop gate is the last place that fact is checkable — after the folder moves it is not.

package/data/harnesses/delivery/skills/brainstorm/references/harvest.md

@@ -84,3 +84,37 @@ Then the offer, relayed by the facilitator: **delete the moved folder, or commit
 decides; the design assumes deletion — nothing anywhere may depend on the folder surviving.
 Committing is the explicit way to keep git-history forensics; an uncommitted folder deleted here
 is gone, and that residual is accepted by design.
+
+## Field lessons — apply
+
+Measured on live harvests; each is the rule, distilled.
+
+- **Run the move gate clean immediately before the move and treat that as the verdict** — the
+  gate's checks read `ops/`, which the move deletes, so a post-move re-run fails by construction.
+  Verify the post-move state by hand: `Status: harvested`, no `ops/`, both index rows,
+  `check-links` clean. And **distil the process record into `state.md` before the move** — the
+  sync log dies with `ops/`, and a ten-line dispatch summary is what separates a record that shows
+  its workings from one that asserts its commitments from nowhere.
+- **Uncommitted harvest artifacts are deleted, not deprecated** — deprecate-in-place protects
+  readers holding a pointer, and a never-committed file has none; a tombstone for a
+  twenty-minute-old file is ceremony.
+- **Audit the *other* decision records for impact at manifest time** — the manifest routes
+  through the docs the commitments name and will not think of the neighbours. The test is
+  commitment-level, not textual (grep finds nothing); read each AD's Decision and Open Questions
+  against the new commitments, and report the unimpacted verdicts with evidence too.
+- **A manifest enumerates sites; the file you open contains more of them.** Fix every
+  same-doctrine site inside a file the manifest already opens — a self-contradicting document is
+  worse than a wider diff — but never wander into an unnamed file: that becomes a backlog row.
+  Say which you did, per row, in the application record.
+- **Re-run the uselessness test when the destination *set* changes**, not only when content does —
+  a consolidation that moves referrers produces a document set no cold reader has graded. The
+  recurring find: a truth doc stating a decided-but-unbuilt mechanism in the present tense; the
+  fix is one clause naming the unbuilt prerequisite.
+- **Retirement wording beats suppression.** doc-lint's heuristics block the honest retirement
+  sentence (`superseded by`, `no longer`); rephrase with no loss of meaning — "retired by
+  AD-00N", "is not the product's position", "lives in a package that is gone" — and reach for
+  `doc-lint-disable` only when the banned phrase is itself the claim.
+- **Amending another session's draft: change the contradicting claim everywhere it is asserted,
+  and nothing else** — a claim stated in nine places and fixed in three leaves the doc worse; a
+  one-paragraph note saying what moved and what did not keeps the amendment legible to the doc's
+  author.

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

@@ -24,7 +24,7 @@ Document contracts and architecture, not implementation details. Show function s
 
 The journey — dates, migrations, progress, supersessions — lives only in records (`docs/history/`); when reality changes, a truth document simply becomes correct. The full strip-list and the record-side rules: [`references/style-guide.md`](references/style-guide.md) § The Two Natures — Tense & History.
 
-The mechanical subset of these rules is checked by [`scripts/doc-lint.mjs`](scripts/doc-lint.mjs) — run it over changed docs before finishing. Block-severity findings must be fixed; `<!-- doc-lint-disable: <id> -->` with a reason beside it is the escape hatch.
+The mechanical subset of these rules is checked by [`scripts/doc-lint.mjs`](scripts/doc-lint.mjs) — run it over changed docs before finishing. Block-severity findings must be fixed; `<!-- doc-lint-disable: <id> -->` with a reason beside it is the escape hatch. Two invocation traps: the disable comment takes **bare rule ids only** — prose inside the comment silently breaks the parse, so put the reason in a second comment beside it — and the script grades truth-vs-record scope by matching `docs/(history|research|memory)/` against **the path string it is given**, so always hand it a repo-root-relative path; linting a record from inside its own folder grades it as a truth document.
 
 ---
 
@@ -85,7 +85,7 @@ The two guarantees are complementary and both break on mixing: a reader holding
 | Derive/update a feature doc's `owns:` | [`references/frontmatter.md`](references/frontmatter.md) |
 | Update existing doc | § Editing an existing doc (below) |
 | Instruction file (`CLAUDE.md`, a rule, an agent, skill prose) | [`references/instruction-style.md`](references/instruction-style.md) — not these templates; every-load prose stays lean, and the present-tense rule still applies |
-| Author or restructure a **skill** (fit, triggers, shape, anatomy, shipping) | The skill-authoring field guide — the `etna` repo (`nurixlabs/etna`), folder `docs/architecture/skills/playbook/`, chapters `00`–`10`. **No etna checkout available ⇒ ask the user for access to the etna repo, or proceed from first principles** with [`references/instruction-style.md`](references/instruction-style.md) governing the prose. This row is the only place the playbook is referenced |
+| Author or restructure a **skill** (fit, triggers, shape, anatomy, shipping) | The skill-authoring field guide — the `etna` repo (`nurixlabs/etna`), folder `docs/playbooks/skills/`, chapters `00`–`10`. **No etna checkout available ⇒ ask the user for access to the etna repo, or proceed from first principles** with [`references/instruction-style.md`](references/instruction-style.md) governing the prose. This row is the only place the playbook is referenced |
 | **No template matches** | [`references/untemplated.md`](references/untemplated.md) — shape decisions + the co-authoring workflow |
 
 ---

package/data/harnesses/delivery/skills/documentation/references/frontmatter.md

@@ -24,13 +24,20 @@ A feature doc's ownership frontmatter is `owns:` (required), `module:` (optional
 
 **1. `owns:`** (the path scope)
 
-Read the doc's content. Extract every source file path it references (file listings, function locations, component paths). Group them into the narrowest glob patterns that cover all referenced files without overlapping another doc's `owns:` globs at equal specificity. A doc may own several globs.
+`owns:` names the **regions whose truth this doc holds** — the directories where a change must be reconciled against this document before it ships. It is an authority claim a human makes, not an inventory of what the feature touches.
 
-| Doc references                       | Glob                      |
-| ------------------------------------ | ------------------------- |
-| Multiple files under one directory   | `src/feature/**`          |
-| Specific files in a shared directory | List each file explicitly |
-| A single entry-point file            | The exact file path       |
+**A file the doc merely references is not a file the doc owns.** Reaching across a boundary into a shared module is a fact about the code, and it belongs to whoever owns that module's region. Transcribing those reach edges as `owns:` entries is how an index stops being a routing table and becomes a hand-maintained import graph: rows then track the dependency graph rather than the feature count, and the shared upstream file ends up filed under whichever downstream feature happened to name it first — a consumer recorded as the authority.
+
+Prefer one region glob over many file globs. Ten paths say nothing about which is the entry point; one region says where the doc's writ runs.
+
+| The doc governs                              | Glob                                 |
+| -------------------------------------------- | ------------------------------------ |
+| A feature's own directory                     | `src/feature/**`                     |
+| A feature split across two directories        | One glob each                        |
+| A single entry-point file, and nothing beside it | The exact file path                  |
+| A shared file several features import         | **Nothing — leave it unowned**       |
+
+**An unowned shared file is the system working, not a gap.** A shared module's authority is the contract it exposes, not any one consumer, so a library-references file or a common utility legitimately has no owning doc. Claiming it would make the index bigger and the routing less certain at once.
 
 Glob each pattern against the codebase. At `status: active`, drop any that match nothing; at `status: draft`, projected globs may match nothing yet — confirm them against real code when the doc flips to `active`.
 

package/data/harnesses/delivery/skills/documentation/templates/plan.md

@@ -71,7 +71,10 @@ Why this work is happening *now*. Link to the spec for *what* we're building; th
 <!-- Written by the `testing` skill (plan-gate mode) at the plan gate (after `boundary`). One row per
      promised behavior: layer · target file · oracle · fixtures · an empty Outcome cell the
      verification gate fills (satisfied / owes nothing / blocked → backlog). Amendable while the
-     plan is open. Do not hand-author. -->
+     plan is open. Do not hand-author. NEVER put a pipe in a ledger cell, escaped or not — the
+     compliance hook splits rows on `|` at a fixed column index with no unescaping, so a
+     markdown-legal `\|` shifts every later cell and the wall blocks a row that is in fact
+     discharged. Write "`install` or `update`", not "`install \| update`". -->
 
 ## Open Questions
 

package/data/harnesses/discover/harness.json

@@ -1,7 +1,7 @@
 {
   "harness": "discover",
   "name": "discover",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "files": [
     ".prettierignore",
     ".prettierrc.json",

package/data/harnesses/discussion/CLAUDE.md

@@ -18,7 +18,7 @@ Strictly separated — never mix them:
 
 **The operator layer**: `metadata/lessons/` — read `DIGEST.md` at session start alongside the routing files; it is **prior, not canon** (its reading-protocol block governs). Everything else under `lessons/` (append-only `log/`, `forecasts.md`) loads on demand only. The `lessons-maintenance` agent (instruction set: `metadata/lessons/distillation.md`) runs **only during user sessions** — spawn it in the background when the `metadata/ops/` cursor falls a session behind.
 
-The rules are the method — portable, abstract, generic examples; nothing depends on any local topic. Live exemplars are reached through `metadata/TOPICS.md`. Workspace-local method notes go to `metadata/method-changelog.md`; the harness itself is versioned by `.claude/harness.json` and documented in the etna forge (`docs/architecture/harness/discussion/`).
+The rules are the method — portable, abstract, generic examples; nothing depends on any local topic. Live exemplars are reached through `metadata/TOPICS.md`. Workspace-local method notes go to `metadata/method-changelog.md`; the harness itself is versioned by `.claude/harness.json` and documented in the etna forge (`docs/harness/discussion/`).
 
 ## Delegation
 

package/data/harnesses/discussion/harness.json

@@ -1,7 +1,7 @@
 {
   "harness": "discussion",
   "name": "discussion",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
@@ -10,5 +10,5 @@
   "seeds": [],
   "tools": [],
   "docsRoot": "docs",
-  "digest": "f1c6d3f61e3e"
+  "digest": "a3de25b70367"
 }

package/data/harnesses/etna/CLAUDE.md

@@ -29,7 +29,8 @@ Invoke the `maintenance` agent whenever the docs look like they need it — not
 
 ## Getting Started
 
-- Read **[`docs/structure.md`](docs/structure.md)** — the documentation authority map (what belongs in `architecture/`, `features/`, `operations/`, `skills/`, `history/`, `memory/`). Don't restate it here.
+- Read **[`docs/structure.md`](docs/structure.md)** — the documentation authority map. The top level mirrors the source roots the forge ships from (`skills/`, `harness/`, `rules/`, `packages/`), plus `playbooks/` for the craft guides and `architecture/` for truth spanning two or more subjects. Don't restate it here.
+- Read **[`docs/writing-style.md`](docs/writing-style.md)** before writing anything — the single style authority for this repo.
 - Read **[`docs/memory/`](docs/memory/)** for agent memory files (one per agent).
 - Prefer `docs/` over `README.md` — `docs/` is canonical for agents.
 - The CLI and hooks are the only real code — detect the package manager from the lockfile (see `.claude/rules/general.md`) for anything under `packages/`.
@@ -61,7 +62,7 @@ Three peer modes plus a Completion step — enter wherever the user's thinking a
 | **LLD** (low-level design) | new component/feature work | `lld-mode` agent + `documentation` skill | Plan |
 | **Plan** | an LLD is approved | `documentation` skill → `docs/history/plans/YYYY-MM-DD-{slug}.md` | Completion |
 
-> Brainstorm entry needs a **basis** — a reference document or a one-shot brain dump; drip-sized asks (a one-line fix) are too small and get redirected. A **pillar** is a recorded strategic principle from a past brainstorm: in-progress sessions under `docs/research/`, harvested ones under `docs/history/brainstorms/`, harvested doctrine under `docs/architecture/`. The LLD is the feature doc itself — `docs/features/{feature}.md`, design intent first, extended in place at Completion.
+> Brainstorm entry needs a **basis** — a reference document or a one-shot brain dump; drip-sized asks (a one-line fix) are too small and get redirected. A **pillar** is a recorded strategic principle from a past brainstorm: in-progress sessions under `docs/research/`, harvested ones under `docs/history/brainstorms/`, harvested doctrine under `docs/architecture/`. The LLD is the component's own doc — `docs/skills/{name}/`, `docs/harness/{name}/`, or `docs/packages/{name}.md` — design intent first, extended in place at Completion.
 
 **On Plan Completion:**
 
@@ -79,14 +80,14 @@ These three mechanisms keep the repo self-updating: **ownership** routes an edit
 
 ### Ownership — route before editing
 
-Which doc is canonical for which paths is the **feature doc's own frontmatter**. A feature doc (flat in `docs/features/`) carries `owns:` (path globs — the only ownership key, pointing at `skills/**`, `harness/**`, `packages/cli/**`, …), an optional `module:` label, `keywords:`, and `status:`. Path → doc ownership is the union of every feature doc's `owns:` globs, surfaced as the generated ownership index at session start. A module is tied to its components by the `owns:` globs of the docs carrying its `module:` label — not a folder, not a separate map. Architecture docs describe cross-cutting patterns and own nothing; operations docs describe procedures.
+**Ownership is declared, not positional.** Any document under `docs/` carrying `owns:` frontmatter claims those code paths — path globs pointing at `skills/**`, `harness/**`, `packages/**`, … — plus an optional `module:` label, `keywords:`, and `status:`. The SessionStart hook scans the whole tree and builds the injected index from the union, so a component's own record claims its path directly and a doc's location is a browsing decision, never an ownership one. Where two docs overlap, the **narrower glob wins**. A module is tied to its components by the `owns:` globs of the docs carrying its `module:` label — not a folder, not a separate map. Indexes, chapters, and explainers carry no `owns:`, so a subject claims its path exactly once.
 
 Before modifying a component in an unfamiliar area:
 
-1. Consult the **injected ownership index** — the `glob → doc · module · keywords · status` map. Match the path or topic to the owning feature doc and read it first. (No index in context ⇒ the repo isn't reconciled — see Maintenance.)
+1. Consult the **injected ownership index** — the `glob → doc · module · keywords · status` map. Match the path or topic to the owning doc and read it first. (No index in context ⇒ the repo isn't reconciled — see Maintenance.)
 2. If a `docs/memory/` file exists for the area, read it for domain knowledge and failure modes.
 
-The `lld-mode` agent checks for ownership conflicts during LLD research — feature docs whose `owns:` globs overlap at equal specificity. Resolve them in the LLD before proceeding.
+The `lld-mode` agent checks for ownership conflicts during LLD research — docs whose `owns:` globs overlap at equal specificity. Resolve them in the LLD before proceeding.
 
 ### Boundaries — check while changing
 
@@ -101,10 +102,11 @@ Invoke the `boundary` skill after a plan is approved and before its first implem
 
 ### Documentation — close the loop
 
-- **Every markdown document goes through the `documentation` skill.** Before creating or substantively editing any `.md` document — a doc, a README, an index, a record — invoke the `documentation` skill and apply its templates and `references/style-guide.md` (truth documents present-tense; history only in records). Instruction files — `CLAUDE.md`, rules, agents, skills — follow the skill's [`references/instruction-style.md`](skills/documentation/references/instruction-style.md) instead.
+- **Everything written in this repo follows [`docs/writing-style.md`](docs/writing-style.md) — no exceptions.** It is the single style authority for both genres: instruction files (`CLAUDE.md`, rules, agents, skill prose) and documents. Read it before writing prose here, not after. Its load-bearing rule is the Two Natures — truth documents state the present and narrate no history; records are dated and never edited to match the present.
+- **Every markdown document also goes through the `documentation` skill** for its *genre* — invoke it before creating or substantively editing any `.md` file and apply the matching template. The skill supplies structure; `writing-style.md` supplies the prose.
 - **[override]** Keep `docs/` updated when a change alters documented behaviour — creating and updating docs is part of the work.
 - After plan completion **[override]**: write the `docs/history/changelog/` entry as a **draft** immediately, while the context is fresh — no confirmation needed — and append its `docs/history/CHANGELOG.md` row; the commit fills what the draft left open and freezes it. Non-plan work needs no separate prompt: every non-exempt commit carries its own entry (the `changelog` rule).
-- When moving or renaming a component: update the `owns:` globs of the feature doc that owns it so the ownership index stays accurate. A new doc that owns code declares its paths in its own `owns:` frontmatter.
+- When moving or renaming a component: update the `owns:` globs of the doc that owns it so the ownership index stays accurate. A new doc that owns code declares its paths in its own `owns:` frontmatter.
 - `docs/structure.md` is the authority on what belongs where — read it before adding or moving a doc; one canonical source per topic, link don't copy. Only `CLAUDE.md`, `AGENTS.md`, and `README.md` live at the repo root.
 
 > Agents and skills live under `.claude/agents/` and `.claude/skills/`. Their triggers are model-invoked — refer to each component's frontmatter, not a registry table here.
@@ -120,7 +122,7 @@ A commit marks the user's behavioral verification of the work, and the working s
 - **A commit is the smallest unit an entry may describe**; above that the mapping is judgment. Work exceeding a draft's scope gets a *second* entry rather than stretching the first.
 - **Distillation is the `retro` agent** — run on demand (before a brainstorm or LLD, before a new project, after a refinement arc), it converts accumulated entries into a typed punch list (doc content, doc structure, skill evolution, pins, harness rules), appends actionable items to the backlog, and proposes only — application runs through the normal documentation loop.
 
-**One-shot migrations are a different genre.** Work that runs **once** against a live system — a harness rollout across consumer repos, a catalog-wide cutover, a data backfill — is a **migration runbook** at `docs/history/migrations/YYYY-MM-DD-{slug}.md` (template: the `documentation` skill's `templates/migration-runbook.md`), authored **before** execution and outcome-stamped after. A changelog entry says what changed in this repo; a runbook says what was executed against the world and how to verify or undo it. A repeatable procedure is neither — that is `docs/operations/`. When a runbook defers targets, it records **why** and the **trigger to re-evaluate them**, so the next run re-checks rather than inheriting the skip.
+**One-shot migrations are a different genre.** Work that runs **once** against a live system — a harness rollout across consumer repos, a catalog-wide cutover, a data backfill — is a **migration runbook** at `docs/history/migrations/YYYY-MM-DD-{slug}.md` (template: the `documentation` skill's `templates/migration-runbook.md`), authored **before** execution and outcome-stamped after. A changelog entry says what changed in this repo; a runbook says what was executed against the world and how to verify or undo it. A repeatable procedure is neither — that belongs with the component it operates. When a runbook defers targets, it records **why** and the **trigger to re-evaluate them**, so the next run re-checks rather than inheriting the skip.
 
 ---
 
@@ -164,12 +166,10 @@ The single policy for sub-agent dispatch — when to fan out, at what tier, and
 
 ❌ prohibitions hold unless the user explicitly asks otherwise; ✅ and ⚠️ items are standing policy:
 
-- ❌ **Tests** — etna is a markdown-authoring repo plus a small CLI with no test suite; never generate, update, or modify test files unless the user explicitly asks. (The `code` harness ships a gated-verification posture for the projects it governs — that is a shipped rule, not etna's own.)
+- ❌ **Tests** — etna authors markdown; the only suite is the CLI's, under `packages/cli/`. Never generate, update, or modify test files unless the user explicitly asks. (The `code` harness ships a gated-verification posture for the projects it governs — that is a shipped rule, not etna's own.)
 - ❌ **Dependencies** — never upgrade frameworks, libraries, or dependencies.
-- ❌ **Compatibility** — never maintain backward compatibility unless specified.
 - ❌ **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** — before editing, if `docs/operations/protected-files.md` exists, read it and never modify any path it lists; never modify `AGENTS.md` or that file itself.
-- ✅ **Browser Automation** — Claude in Chrome / CDP browser tools: use freely when useful, no need to ask first.
+- ❌ **Protected Files** — never modify `AGENTS.md`.
 - ✅ **Delegation** — when to fan out, tiers, and trust are § Delegation.
 - ⚠️ **Plans** — created directly in `docs/history/plans/` (see Workflows). Once `Status: Complete` or `Abandoned`, frozen — never edited. If scope changes after completion, write a new dated plan linking back.
 - ⚠️ **Tool Issues** — if any CLI tool, shell alias, or MCP tool behaves unexpectedly (syntax errors, silent failures, wrong defaults), report the exact tool, command, and error to the user so they can fix the underlying library.
@@ -178,15 +178,15 @@ The single policy for sub-agent dispatch — when to fan out, at what tier, and
 
 ## Authoring Conventions
 
-Most artifacts are markdown — skills, agents, rules, docs. Follow the `kb` / `nomenclature` rules; markdown has no file-path-comment rule. Keep the `.claude/rules/*` reference docs frontmatter-free.
+Almost everything here is markdown — skills, agents, rules, harness policies, docs. **The prose style for all of it is [`docs/writing-style.md`](docs/writing-style.md)**; the guides below add what is specific to each artifact class. Follow the `kb` / `nomenclature` rules; markdown has no file-path-comment rule. Keep the `.claude/rules/*` reference docs frontmatter-free.
 
 **Each artifact class has an authoring guide — read the one you are editing, before you edit it.** The forge is the only repo that authors these, so the guides live here and ship nowhere:
 
 | Editing | Guide |
 | --- | --- |
-| A **rule** (`rules/*.md`) | [`docs/architecture/rules.md`](docs/architecture/rules.md) — the catalog, the conventions, and the whole-file audit |
-| A **skill** (`skills/*/`) | [`docs/architecture/skills/playbook/`](docs/architecture/skills/playbook/Readme.md) — fit and scope through shipping and maintenance |
-| An **agent** (`agents/*.md`) | [`docs/architecture/harness/authoring-agents.md`](docs/architecture/harness/authoring-agents.md) |
+| A **rule** (`rules/*.md`) | [`docs/rules/Readme.md`](docs/rules/Readme.md) — the catalog, the conventions, and the whole-file audit |
+| A **skill** (`skills/*/`) | [`docs/playbooks/skills/`](docs/playbooks/skills/Readme.md) — fit and scope through shipping and maintenance |
+| An **agent** (`agents/*.md`) | [`docs/playbooks/agents.md`](docs/playbooks/agents.md) |
 
 Authoring or updating an **agent** keeps both runtimes in sync: the `.md` is the single source, and its Codex `.codex.toml` twin is derived from it by the guide above, then checked with `node packages/cli/lib/codex/validate-codex-agents.mjs`.
 

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

@@ -18,10 +18,10 @@ You do NOT write the LLD — you return structured research that the main agent
 Map the documentation landscape — what exists, what is adjacent, how detailed the LLD should be, and what code paths are already owned:
 
 1. Read `./docs/structure.md` to understand the documentation structure
-2. If `./docs/features/README.md` exists, read it to see existing feature LLDs and where the new one fits; otherwise glob the feature docs directly
+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 in `./docs/features/` to calibrate format and depth
-5. Consult the **injected ownership index** (the generated `glob → doc · module · keywords · status` map — the union of every feature doc's `owns:` frontmatter) to build the ownership map. It is the source of truth for what code paths are already owned. If the index isn't present in context, glob `docs/features/**/*.md` and read each doc's `owns:` frontmatter directly.
+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 · keywords · status` map — the union of every feature doc's `owns:` frontmatter) to build the ownership map. It is the source of truth for what code paths are already owned. 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
 

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

@@ -44,15 +44,15 @@ Decide the mode once, up front, from the version marker — then run.
 
 ## Part A — Coherence audit (always runs)
 
-The ownership source of truth is the **union of every feature doc's `owns:` frontmatter** — the same source the SessionStart ownership index derives from. There is no `docs/routing.md` and no precomputed file to regenerate; you rebuild the map by globbing `docs/features/`.
+The ownership source of truth is the **union of every doc's `owns:` frontmatter** — the same source the SessionStart ownership index derives from. There is no `docs/routing.md` and no precomputed file to regenerate; you rebuild the map by globbing the docs tree for docs that declare `owns:`.
 
 ### Step 1: Build the ownership map
 
 1. Read `docs/structure.md` for the authority map.
-2. Glob `docs/features/**/*.md`, ignoring `*.bkp.*` files (installer backups awaiting the fold); for each, parse the frontmatter `owns:` globs and `module:` label.
+2. Glob the docs tree for markdown carrying `owns:` frontmatter, ignoring `*.bkp.*` files (installer backups awaiting the fold) and anything under `docs/history/` (frozen records quote retired globs as provenance). **Ownership is declared, not positional** — the standard shape files these docs under `docs/features/`, but a repo may declare ownership on any doc, and the index reads them all. For each, parse the `owns:` globs and `module:` label.
 3. Build a map: glob → owning doc + module. Narrower glob wins on overlap. **This IS the source of truth.**
 
-**Architecture-first fallback.** If no feature doc carries `owns:` yet (a fresh-baseline repo can carry thousands of LOC and zero feature docs), drive this pass's ownership/drift surface off `docs/architecture/**` file-references instead — they become the **primary** ownership map for Steps 2–5. The `owns:` map becomes primary the moment any feature doc declares ownership — this is a fallback, not a replacement.
+**Architecture-first fallback.** If no doc carries `owns:` yet (a fresh-baseline repo can carry thousands of LOC and zero feature docs), drive this pass's ownership/drift surface off `docs/architecture/**` file-references instead — they become the **primary** ownership map for Steps 2–5. The `owns:` map becomes primary the moment any feature doc declares ownership — this is a fallback, not a replacement.
 
 ### Step 2: Validate ownership
 
@@ -109,7 +109,7 @@ For each stale doc: update the doc directly when the drift is clear (renamed fun
 
 For each feature doc you verified accurate or updated this pass, stamp `last-reviewed:` in its frontmatter with today's date (add the key if absent). Never write review dates into the body — it's frontmatter metadata only.
 
-For unowned code paths, append: `- **[P2]** No feature doc owns \`{dir}/\` — discovered by maintenance` (`{dir}` = the actual unowned source directory).
+For an unowned code **region**, append: `- **[P2]** No feature doc owns \`{dir}/\` — discovered by maintenance` (`{dir}` = the actual unowned source directory). The target is **every region has an owner**, never every file: an individual shared file that several features import is expected to be unowned, because its authority is the contract it exposes rather than any one consumer. Report a directory that no doc's region covers; never mint a row for a shared file, and never propose closing a gap by adding a file glob to whichever doc happens to import it.
 
 **Declined realignment.** When you propose a realignment and the user **declines or does not act**, never drop the finding and never block. Append it to `docs/history/backlog.md` as `- **[P0–P3]** <finding> — discovered by maintenance`, priority = the finding's own severity **on the same P0–P3 scale as code items** — never a segregated "compliance" section, never auto-relegated to the lowest tier. Record once: dedupe against existing entries; if already present, leave it.
 
@@ -238,6 +238,7 @@ Apply the **§ Strategy memory** retirement procedure to `docs/memory/maintenanc
 - **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.
+- **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: 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.

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

@@ -14,9 +14,9 @@ You do NOT write the LLD — you return structured research that the main agent
 Map the documentation landscape — what exists, what is adjacent, how detailed the LLD should be, and what code paths are already owned:
 
 1. Read `./docs/structure.md` to understand the documentation structure
-2. If `./docs/features/README.md` exists, read it to see existing feature LLDs and where the new one fits; otherwise glob the feature docs directly
+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 in `./docs/features/` to calibrate format and depth
+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 · keywords · status` map — the union of every feature doc's `owns:` frontmatter) to build the ownership map. It is the source of truth for what code paths are already owned. If the index isn't present in context, glob `docs/features/**/*.md` and read each doc's `owns:` frontmatter directly.
 
 ## What You Research

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

@@ -42,15 +42,15 @@ Decide the mode once, up front, from the version marker — then run.
 
 ## Part A — Coherence audit (always runs)
 
-The ownership source of truth is the **union of every feature doc's `owns:` frontmatter** — the same source the SessionStart ownership index derives from. There is no `docs/routing.md` and no precomputed file to regenerate; you rebuild the map by globbing `docs/features/`.
+The ownership source of truth is the **union of every doc's `owns:` frontmatter** — the same source the SessionStart ownership index derives from. There is no `docs/routing.md` and no precomputed file to regenerate; you rebuild the map by globbing `docs/features/`.
 
 ### Step 1: Build the ownership map
 
 1. Read `docs/structure.md` for the authority map.
-2. Glob `docs/features/**/*.md`, ignoring `*.bkp.*` files (installer backups awaiting the fold); for each, parse the frontmatter `owns:` globs and `module:` label.
+2. Glob the docs tree for markdown carrying `owns:` frontmatter, ignoring `*.bkp.*` files and anything under `docs/history/`. **Ownership is declared, not positional** — the standard shape files these under `docs/features/`, but a repo may declare ownership on any doc. For each, parse the `owns:` globs and `module:` label.
 3. Build a map: glob → owning doc + module. Narrower glob wins on overlap. **This IS the source of truth.**
 
-**Architecture-first fallback.** If no feature doc carries `owns:` yet (a fresh-baseline repo can carry thousands of LOC and zero feature docs), drive this pass's ownership/drift surface off `docs/architecture/**` file-references instead — they become the **primary** ownership map for Steps 2–5. The `owns:` map becomes primary the moment any feature doc declares ownership — this is a fallback, not a replacement.
+**Architecture-first fallback.** If no doc carries `owns:` yet (a fresh-baseline repo can carry thousands of LOC and zero feature docs), drive this pass's ownership/drift surface off `docs/architecture/**` file-references instead — they become the **primary** ownership map for Steps 2–5. The `owns:` map becomes primary the moment any feature doc declares ownership — this is a fallback, not a replacement.
 
 ### Step 2: Validate ownership
 

package/data/harnesses/etna/harness.json

@@ -1,7 +1,7 @@
 {
   "harness": "etna",
   "name": "etna",
-  "version": "1.5.12",
+  "version": "1.5.16",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
@@ -10,5 +10,5 @@
   "seeds": [],
   "tools": [],
   "docsRoot": "docs",
-  "digest": "b9aaab03fa33"
+  "digest": "f836486a6ca4"
 }

package/data/harnesses/etna/hooks/generate-ownership-index.mjs

@@ -1,4 +1,4 @@
-// harness/etna/hooks/generate-ownership-index.mjs — SessionStart hook: scan docs/features/**/*.md,
+// harness/etna/hooks/generate-ownership-index.mjs — SessionStart hook: scan docs/**/*.md,
 // extract the focal frontmatter (owns / module / keywords / status), and inject a compact
 // code-path → owning-doc index via additionalContext. Fires on startup/resume/clear/compact so the
 // map survives /clear and /compact and is regenerated fresh every time. Writes no file.
@@ -115,10 +115,16 @@ function asList(v) {
 
 // Build the ownership index text from every feature doc's frontmatter.
 function buildIndex(projectDir) {
-  const featuresDir = path.join(projectDir, "docs", "features");
-  // *.bkp.* files are install-time backups awaiting the maintenance fold — a backed-up feature
+  // Ownership is DECLARED, not positional: any doc anywhere under docs/ that carries owns:
+  // claims those paths, so a component's record claims its own path instead of a stub doing it
+  // by proxy. docs/history/ is skipped — frozen plans and records quote old globs as provenance,
+  // and indexing them would resurrect retired ownership.
+  const docsDir = path.join(projectDir, "docs");
+  // *.bkp.* files are install-time backups awaiting the maintenance fold — a backed-up
   // doc double-owning every path it names is the drift this filter prevents (parity: lib/ownership.mjs).
-  const files = listMarkdown(featuresDir).filter((f) => !f.includes(".bkp."));
+  const files = listMarkdown(docsDir)
+    .filter((f) => !f.includes(".bkp."))
+    .filter((f) => !f.split(path.sep).includes("history"));
   const lines = [];
   let deprecated = 0;
   let indexed = 0;
@@ -142,15 +148,18 @@ function buildIndex(projectDir) {
     const keywords = asList(field(block, "keywords"));
     indexed += 1;
     const doc = path.relative(projectDir, file).split(path.sep).join("/");
+    // METADATA ONCE PER DOC, NOT ONCE PER GLOB — kept in step with lib/ownership.mjs buildIndex(),
+    // which the parity suite pins. Re-emitting the keyword array beside every glob made the index
+    // grow with the dependency graph rather than the doc count.
     const kw = keywords.length ? `[${keywords.join(", ")}]` : "[]";
-    for (const glob of owns) {
-      lines.push(`${glob} → ${doc} · ${moduleLabel} · ${kw} · ${status}`);
-    }
+    lines.push(
+      `${doc} · ${moduleLabel} · ${status}\n  ${kw}\n` + owns.map((glob) => `  ${glob}`).join("\n")
+    );
   }
   if (lines.length === 0) return "";
   lines.sort();
   const header =
-    "# Ownership index (generated) — code-path glob → owning feature doc · module · keywords · status\n" +
+    "# Ownership index (generated) — owning feature doc · module · status, then the code regions it governs.\n" +
     "# Match the file or topic you're about to touch, then read the owning doc before changing it.\n";
   // A doc dropped by a parse failure is indistinguishable from one that owns nothing,
   // so report the tally: seen vs indexed is the only signal a silent skip leaves.
@@ -159,7 +168,7 @@ function buildIndex(projectDir) {
   if (deprecated > 0) notes.push(`${deprecated} deprecated`);
   if (skipped > 0) notes.push(`${skipped} with no owns:`);
   const footer = notes.length
-    ? `\n# (${indexed}/${files.length} feature doc(s) indexed - ${notes.join(", ")})`
+    ? `\n# (${indexed}/${files.length} doc(s) claim ownership - ${notes.join(", ")})`
     : "";
   return header + lines.join("\n") + footer;
 }

package/data/harnesses/etna/rules/testing.md

@@ -37,6 +37,7 @@ Rules for the plan regime between the plan gate and the verification gate:
 - **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.
+- **`cmd > log; echo "EXIT=$?"` reports the echo's status, never the command's** — a SIGTERM'd suite surfaces as "exit code 0", which is the worst direction for a gate to be wrong in. Read the real status from the log, or drop the trailing echo. Adjacent trap: a runner that never emits a summary is a dying **worker**, not a slow test — `--testTimeout` bounds neither, so bound the run and read the log.
 - **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.
 
 ## Frameworks by stack

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

@@ -6,7 +6,7 @@ correctly, the record stays readable at any pause, and the session ends with a h
 complete that the session folder is useless — it moves to history and the user deletes or
 commits it.
 
-> Spec (single source of truth): `docs/architecture/skills/brainstorm/` in the etna repo. The etna
+> Spec (single source of truth): `docs/skills/brainstorm/` in the etna repo. The etna
 > copy of this skill (`skills/brainstorm/`) is canonical; the user-level path
 > `~/.claude/skills/brainstorm/` is a symlink to it.
 

package/data/harnesses/etna/skills/brainstorm/references/doctrine.md

@@ -96,3 +96,25 @@ These bind every writer of the working surface — facilitator (ops), twin (ever
 5. **Directional steering is not feature truth.** A harvested principle informs many decisions
    and changes slowly; a feature fact belongs to its feature doc and changes at code speed. The
    harvest links between the two layers, never duplicates prose across them.
+
+## Field lessons — capture and converge
+
+Measured on live sessions; each is the rule, distilled.
+
+- **Separate user voice from facilitator re-derivation before ledgering** when both arrive in one
+  turn. Only the user's half is ledgerable; a re-derivation that quietly re-reads an existing
+  commitment into a new shape is caught as a fork with a named amendment to the affected `D#`,
+  never as an edit — a commitment recorded in the user's words is amended only by the user.
+- **Stamp in UTC, always** — take the stamp from `date -u`, never from the runtime's injected
+  local date; the two disagree for part of every working day in some offsets, and a local-date
+  stamp runs the ledger a day ahead of capture.
+- **Run the blindspot pass immediately after a converge burst, before the manifest gate.** When
+  several picks land in one sitting the strain migrates *between* them — collisions between
+  commitments taken within the same hour, found only by reading two together. The burst is the
+  cheapest moment to catch them and the last before they freeze.
+- **When a pick answers three of a fork's four close-condition clauses, close it and file the
+  residue as a new fork in the same pass** — closing silently and leaving it open both lose
+  information; name the unanswered clause in the resolving entry and carry it under a new `F#`.
+- **When a ledger entry's `Why` contains "already", verify it before the manifest.** A commitment
+  that declines to build something because it already exists rests on a fact, not a judgment, and
+  the stop gate is the last place that fact is checkable — after the folder moves it is not.

package/data/harnesses/etna/skills/brainstorm/references/harvest.md

@@ -84,3 +84,37 @@ Then the offer, relayed by the facilitator: **delete the moved folder, or commit
 decides; the design assumes deletion — nothing anywhere may depend on the folder surviving.
 Committing is the explicit way to keep git-history forensics; an uncommitted folder deleted here
 is gone, and that residual is accepted by design.
+
+## Field lessons — apply
+
+Measured on live harvests; each is the rule, distilled.
+
+- **Run the move gate clean immediately before the move and treat that as the verdict** — the
+  gate's checks read `ops/`, which the move deletes, so a post-move re-run fails by construction.
+  Verify the post-move state by hand: `Status: harvested`, no `ops/`, both index rows,
+  `check-links` clean. And **distil the process record into `state.md` before the move** — the
+  sync log dies with `ops/`, and a ten-line dispatch summary is what separates a record that shows
+  its workings from one that asserts its commitments from nowhere.
+- **Uncommitted harvest artifacts are deleted, not deprecated** — deprecate-in-place protects
+  readers holding a pointer, and a never-committed file has none; a tombstone for a
+  twenty-minute-old file is ceremony.
+- **Audit the *other* decision records for impact at manifest time** — the manifest routes
+  through the docs the commitments name and will not think of the neighbours. The test is
+  commitment-level, not textual (grep finds nothing); read each AD's Decision and Open Questions
+  against the new commitments, and report the unimpacted verdicts with evidence too.
+- **A manifest enumerates sites; the file you open contains more of them.** Fix every
+  same-doctrine site inside a file the manifest already opens — a self-contradicting document is
+  worse than a wider diff — but never wander into an unnamed file: that becomes a backlog row.
+  Say which you did, per row, in the application record.
+- **Re-run the uselessness test when the destination *set* changes**, not only when content does —
+  a consolidation that moves referrers produces a document set no cold reader has graded. The
+  recurring find: a truth doc stating a decided-but-unbuilt mechanism in the present tense; the
+  fix is one clause naming the unbuilt prerequisite.
+- **Retirement wording beats suppression.** doc-lint's heuristics block the honest retirement
+  sentence (`superseded by`, `no longer`); rephrase with no loss of meaning — "retired by
+  AD-00N", "is not the product's position", "lives in a package that is gone" — and reach for
+  `doc-lint-disable` only when the banned phrase is itself the claim.
+- **Amending another session's draft: change the contradicting claim everywhere it is asserted,
+  and nothing else** — a claim stated in nine places and fixed in three leaves the doc worse; a
+  one-paragraph note saying what moved and what did not keeps the amendment legible to the doc's
+  author.