@nurix/etna 0.20.29 → 0.20.31

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

@@ -1,90 +1,84 @@
-# Frontmatter Derivation — the doc graph
+# Frontmatter — documents in the knowledge graph
 
-Load when: creating a doc that declares an edge (a feature, package or system doc, a UX doc, a behavioral checklist), updating one whose scope moved, or running a baseline/reconcile pass over many docs.
+Load when: creating a document that carries frontmatter, updating one whose subject moved, or running a baseline or reconcile pass over many documents.
 
-**A docs tree is a graph, and every edge in it is declared in frontmatter.** Two kinds of edge exist: **doc → code** (`owns:`), and **doc → doc** (`verifies:`, `applies:`). The SessionStart hook reads them all and injects the generated indexes; there is no hand-maintained map of either kind.
+This reference states how a document joins the knowledge graph, and it is kept in step with the machine that reads it: the knowledge layer (`docs/architecture/systems/knowledge-layer.md` in a repository that carries it; § Documents and code). Where this reference and that design disagree, the design is the authority and this file is the defect.
 
-## The one rule that keeps the graph honest
+## The model
 
-**An edge is declared once, at the consuming end. Every inverse is generated, never authored.**
+A document names the product objects it designs. Every other edge between a document and the code is either authored on the code's side or computed, never typed into the document.
 
-A parent that hand-lists its children is a second thing to forget, and the moment the two directions can disagree nothing says which is right — you have doubled the staleness surface rather than halving it. So a checklist names the feature it verifies; the feature never lists its checklists. A feature names the architecture doc it obeys; the architecture doc never lists its consumers. Both inverses are derived on demand and injected, exactly as the ownership index already is.
+### Principles
 
-The consuming end is also the end that **knows**. A checklist author knows what they are verifying; an architecture doc has no idea who will obey it next year.
+1. **Objects as the document's edge:** a document's frontmatter carries `objects:`, the product objects it designs, by their register names. That is its one edge into the graph and its discovery terms.
+2. **The header pointer as the code's edge:** a source file's path header names the document that holds its fuller account (the root instruction file's § File Structure). The pointer is authored on the code's side, a move carries it, and a new file without one is a lint.
+3. **Computed ownership:** the object closure (document → objects → tables → their write, read and refusal sites → files) reaches files nobody listed. Where the header pointer and the closure disagree, the graph prints both. Which document speaks for a path is a query, answered per path on demand.
+4. **Nothing recomputable stored:** a list of files, a list of consumers, or a list of governing documents typed into frontmatter is a copy of something the graph computes. It is stale the day the code moves, and it fails the stability test (`style-guide.md` § Shape — the model first, the detail after).
+5. **One declaration, at the consuming end:** the edges a person must author (`objects:`, `verifies:`) are declared once, by the document that knows. Every inverse is generated, never authored.
 
-## When to run
+## Keys by genre
 
-- **Baseline / reconcile** — for every owning doc whose code paths aren't yet declared in its `owns:` frontmatter (the `maintenance` agent (baseline mode) calls this)
-- **New owning doc** — when creating one via the [Feature](../templates/feature.md), [Package](../templates/package.md) or [System](../templates/system.md) template, project its `owns:` globs
-- **Doc update** — when the documented scope changes, update the doc's `owns:` globs
+| Genre | Keys |
+| --- | --- |
+| Feature | `type`, `status`, `objects`, `module` (optional) · transitional `owns` |
+| System | `type`, `status`, `objects` · transitional `owns` |
+| Package | `type`, `status`, `objects` · transitional `owns` |
+| Doctrine | `type`, `status`, `objects` |
+| UX | `type`, `status`, `objects` · transitional `owns` when it speaks for a surface's components |
+| Behavioral checklist | `type: checklist`, `verifies` |
+| Acceptance criteria | `type`, `status` |
+| Every other genre | `type`, plus its template's own keys |
 
-## Which genres own code
+Tooling keys sit beside these on any genre: `rev:` (a generator's generation stamp), `slug:` (the identity key on generated documents, minted once, and in the repository the filename), and `last-reviewed:` (stamped on a substantive review, the `maintenance` agent's staleness signal). Sessions preserve them on edits and never narrate or inject them. The `maintenance` agent stamps `type:` where it is missing.
 
-**Three do, and no others: `feature`, `package`, `system`.** They layer by glob specificity over the same tree, which is what lets a repo be documented at three altitudes without subtracting anything by hand:
+## Keys
 
-| Genre | Claims | Wins because |
-| --- | --- | --- |
-| `package` (`docs/architecture/packages/`) | `packages/{name}/**` — the whole tree, one glob | Nothing; it is the **residual** owner and loses every narrower claim, keeping what no one else takes |
-| `system` (`docs/architecture/systems/`) | the subtrees and exact files one machine is made of | Its globs are narrower than the package glob — specificity |
-| `feature` (`docs/features/`) | one capability's or one surface's globs | Same — specificity over the package glob |
-
-Every other genre owns no code and carries no `owns:`. That includes the cross-cutting doctrine in `docs/architecture/` (and `docs/architecture/common/`), which describes patterns rather than regions — a surface declares it is bound by one through `applies:`, and the doctrine never claims the surface back. Checklists, acceptance docs, ADs, operations procedures, research and brainstorm records own nothing.
-
-## How to derive the frontmatter
-
-An owning doc's frontmatter is `objects:` (required — the product objects it designs, by their graph names; its discovery terms and its traced edge into the knowledge graph), `owns:` (required until the graph computes ownership from traces), `module:` (optional — feature docs only; a package is already a bounded unit and a system spans contexts by definition), and `status:` (required). An optional `last-reviewed:` date (stamped whenever the doc is substantively reviewed or updated) gives the `maintenance` agent a staleness signal to rank its audits by — it is tooling metadata, never narrated in the body. `type:` (required — the genre, enum = the template names) and `rev:` (generator-written generation stamp) are the same class: external tooling reads them, sessions **preserve them on edits** and never narrate or inject them. The `maintenance` agent stamps `type:` on docs that predate the key. `slug:` completes the set on generated docs: the identity key, minted once at creation and never re-derived from a display name — in the repo the filename is the slug, and the `maintenance` agent re-aligns the two when they diverge.
-
-**1. `owns:`** (the path scope)
+### `objects:`
 
-`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.
+- **Values:** the product objects the document designs, by the names the object register uses (`docs/dna/objects/<group>.yaml`, the product-dna skill's). Where a repository has no register yet, the names its product model and its documents already use.
+- **Meaning:** designs, not mentions. A feature that reads a session designs no session; the document that decides what a session is does.
+- **Discovery:** there is no `keywords:` key. An object's name and its register aliases are its discovery terms.
+- **Doctrine:** a doctrine document names the cross-cutting objects it governs (principal, credential, session). The surfaces bound by it are the documents that design or touch the same objects, which the closure computes.
 
-**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.
+### `status:`
 
-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.
+- **Values:** `active`, `draft` or `deprecated`. It steers a reader toward live documents.
 
-| 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 whole workspace package, residually          | `packages/{name}/**` — one glob, on the package doc |
-| A machine spanning packages                    | One glob or exact path per subtree it is made of, on the system doc |
-| A shared file several features import         | **Nothing — leave it unowned**       |
+### `module:`
 
-**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.
+- **Values:** one bounded-context label on a feature document, or omitted for a cross-cutting feature. A label, not a folder. Package and system documents omit it.
 
-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`.
+### `verifies:`
 
-**2. `module:`** (feature docs only)
+- **Values:** on a behavioral checklist, the repo-relative path of the feature or UX document whose promises it proves. One is the norm.
+- **Authorship:** a checklist knows what it proves, and nothing in the code says so. A checklist with no `verifies:` is an orphan: nothing implicates it when its subject changes.
 
-The single bounded-context label this feature belongs to, or omit it for a cross-cutting feature that belongs to no single context. A module is a label, not a folder — features sharing a `module:` value are what ties that module to code (a filter over the generated ownership index). Package and system docs omit it entirely.
+### `owns:` — transitional
 
-**3. `objects:` & `status:`**
+- **Reason for the key:** the harness's ownership scan (`.claude/hooks/lib/ownership.mjs`) keys on `owns:` until it switches to the header pointers and the object closure, which is the knowledge layer's recorded gap. Until then the key keeps the session's ownership index and the doc-debt detectors working.
+- **Form:** region globs only, one per region the document speaks for: `packages/{name}/**` on a package document, the machine's subtrees on a system document, a feature's own directory on a feature document. Never a list of individual files, and never a shared file several features import.
+- **Growth:** none. A new document carries the region glob its genre needs and nothing more; an edit never adds file-level entries.
+- **Retirement:** removed from every document in the same change that switches the scan, and this section with it.
 
-`objects:` names the product objects the document designs — the discovery terms topic→doc lookup rides, and the edge the knowledge graph renders each object's documents from. There is no `keywords:` key: an object's name is its discovery term. `status:` is `active`, `draft`, or `deprecated` — it steers the model toward live docs and away from draft/deprecated ones.
+## Retired keys
 
-## The doc → doc edges
-
-A prose link is not an edge. It states that one doc mentions another; it never states **why**, so nothing can be derived from it — not who consumes a doctrine, not what to re-read before an edit, not what falls stale when a surface moves. A tree can carry hundreds of prose links and still have no graph. These two keys carry the relationships that matter; everything else stays prose.
-
-**`verifies:`** — on a behavioral checklist (`docs/tests/{feature}.md`), the feature or UX doc(s) whose promises it proves. One value is the norm; several when a checklist spans a capability that two docs decide. A checklist carrying no `verifies:` is an orphan by construction: nothing implicates it when its subject changes, so it rots silently and the rot is undetectable.
-
-**`applies:`** — on a feature or UX doc, the architecture docs it obeys. Not "docs I read" and not "docs I mention" — **obligation**: a doctrine this surface is bound by, such that a change to the doctrine implicates this doc. The narrow reading is the load-bearing one; a key that collects everything consulted degrades into a bibliography and stops meaning anything. A feature bound by nothing cross-cutting omits the key.
-
-Cross-cutting *contracts* remain diagnosed by the `boundary` skill from source, never persisted — `applies:` records which doctrine a surface answers to, not which code it touches.
+| Key | Retired because | What replaces it |
+| --- | --- | --- |
+| `applies:` | A list of governing documents is a hand-kept copy of a relationship the graph computes through the objects both documents name, and it drifts the way any copy does | The objects the doctrine and the surface share, computed; for people, the document's Scope section names its governing doctrine and what each settles |
+| `keywords:` | An object's name and aliases are its discovery terms | `objects:` |
+| A file-level `owns:` list | The header pointers and the object closure compute it | Region globs only, until the scan switches (above) |
 
-## What is not frontmatter, deliberately
+An edit to a document that carries a retired key removes the key in the same edit.
 
-**`Pinned:` stays a section-level line inside a checklist**, naming the suite tests that guard that section. It is already typed and already resolved mechanically by the `maintenance` agent. Hoisting it into frontmatter would flatten per-section detail into a doc-level list and duplicate what the sections already say — the exact double-declaration the one rule above forbids.
+## Not frontmatter, deliberately
 
-That edge has a property the others lack, and it is worth naming: **a `Pinned:` reference terminates.** A test file exists or it does not, so the edge is falsifiable by a resolver sweep with no judgement. An `owns:` glob is only falsifiable at the dangling end — a glob that resolves says nothing about whether the doc still describes what the code does. Terminal edges get resolver sweeps; non-terminal edges need a human or an agent to read both ends. Do not build a checker that pretends otherwise.
+- **`Pinned:`** stays a section-level line inside a checklist, naming the suite tests that guard that section. It is typed and resolved mechanically; hoisting it would flatten per-section detail into a document-level list.
+- **Terminal and non-terminal edges:** a `Pinned:` reference terminates (a test file exists or it does not), so a resolver sweep checks it with no judgment. An `objects:` value is checked against the register by the graph's index-time lints. Whether a document still describes what its objects do needs a person or an agent to read both ends; no checker pretends otherwise.
 
 ## Rules
 
-- One canonical doc per path. A doc's `owns:` globs must not overlap another doc's at equal specificity — the narrower glob wins; equal-specificity overlap is an ownership conflict to resolve. Overlap at **unequal** specificity is the layering working as designed: a package doc's `packages/{name}/**` is meant to be outranked, and what survives every narrower claim is exactly what that doc describes.
-- Use glob patterns for directories, explicit paths for individual files. At `active`, never list paths that don't exist in the codebase; a `draft`'s projected paths are confirmed at `active`.
-- When a doc covers a deep feature with sub-specs (e.g., `editor/`), each sub-spec owns its own globs — don't duplicate a path across siblings.
-- For baseline/reconcile with many docs, use parallel sub-agents to read source and propose `owns:` globs.
-- **Never author an inverse.** No doc lists its verifiers, its consumers, or its dependents — those are generated. A hand-written "consumed by" table is a defect to delete, not a convention to follow.
-- **Every edge value is a repo-relative doc path** (`docs/architecture/common/security.md`), never a bare filename and never a display title — the resolver is a path lookup, and a title changes without the file moving.
-- **A dangling edge is a block, not a warning.** `verifies:` or `applies:` naming a doc that does not exist is a typo or a deletion; either way the graph is lying. Resolve at authoring time.
+- **Inverses never authored:** no document lists its verifiers, its consumers, its governing doctrine's other surfaces, or the files that point at it. A hand-written "consumed by" table is a defect to delete.
+- **Edge values:** `verifies:` values are repo-relative document paths, never a bare filename or a display title.
+- **Dangling edges block:** a `verifies:` naming a document that does not exist, or an `objects:` value no register or product model knows, is a typo or a deletion. Resolve it at authoring time.
+- **Index-time lints the graph prints:** a header pointing at a document that does not exist, a document no file points at, an object no document designs. They never fail a refresh; a session that sees one resolves it or files it.
+- **Baseline and reconcile:** the `maintenance` agent stamps `type:` and `objects:`, reduces any file-level `owns:` list to its region globs, removes retired keys, and reports source files whose header names no document. Many documents ⇒ parallel sub-agents, one document each.

package/data/harnesses/etna/skills/documentation/references/style-guide.md

@@ -34,8 +34,8 @@ Every genre takes the same shape (principle 2) and the same labels (principle 5)
 | Operations procedure, migration runbook | Truth, record | The exact commands, in order, with their expected output | Nothing. The detail is the point |
 | Record (plan, changelog entry, journal, memory) | Record | Its template's fields, as of the moment it describes | Nothing. Its prose follows § Voice and § Labels; the dates and the journey are its own |
 
-- **Owning documents:** feature, package and system are the three genres that carry `owns:`. They take principles 5 and 6 in full, their sections are fixed (§ Owning documents — the body and the footer), and `doc-lint` reads them.
-- **Doctrine:** the same shape and labels as an owning document, with no `owns:` and no mechanism. Its model layer may argue in paragraphs; below the model it is bullets like every other explaining document.
+- **Owning documents:** feature, package and system are the three genres that speak for code: source files name them in their headers, and the ownership scan resolves paths to them (`frontmatter.md`). They take principles 5 and 6 in full, their sections are fixed (§ Owning documents — the body and the footer), and `doc-lint` reads them.
+- **Doctrine:** the same shape and labels as an owning document, speaking for no code and describing no mechanism. Its model layer may argue in paragraphs; below the model it is bullets like every other explaining document.
 - **Reference documents and procedures:** the one place a signature, a shape, a variable table, a command list or a file path is the content. They keep the detail the owning genres hand to the graph (§ Reference documents).
 - **Indexes:** a folder's `Readme.md` describes directories, never files; the root README follows `templates/root-readme.md`. Both take § Labels.
 

package/data/harnesses/etna/skills/documentation/scripts/doc-lint.mjs

@@ -159,7 +159,7 @@ function lintFile(path, findings) {
   }
   if (scope === 'truth' && !isFolderIndex && /(^|\/)docs\/features\/[^/]+\.md$/.test(path)) {
     const fm = text.startsWith('---') ? text.slice(0, text.indexOf('\n---', 3)) : '';
-    for (const key of ['owns:', 'status:', 'type:'])
+    for (const key of ['objects:', 'status:', 'type:'])
       if (!fm.includes(key)) findings.push({ path, n: 1, severity: 'block', id: 'feature-frontmatter', message: `feature doc missing \`${key}\` frontmatter` });
   }
 

package/data/harnesses/etna/skills/documentation/templates/Readme.md

@@ -38,4 +38,4 @@ One file per template. Every template is either a **truth document** (states cur
 
 **Baseline scaffolds** — files that must exist after every baseline (`docs/structure.md` is not among them: it is harness-owned, shipped whole by the installer and overwritten on every refresh, and has no template); the `maintenance` agent (baseline mode) creates any that are missing: [docs-readme.md](docs-readme.md), [changelog-index.md](changelog-index.md), [backlog.md](backlog.md), [memory-main.md](memory-main.md), [setup.md](setup.md) (when the repo has a lockfile and a runnable root script; never overwriting an existing first-run procedure), and [root-readme.md](root-readme.md) (never overwriting an existing root README).
 
-**Ownership.** Three genres carry code — **feature**, **package**, **system** — and each is the canonical reference for the code paths in its **`owns:` frontmatter**, the only ownership key. To find what a doc owns, read its `owns:` globs; to find the doc for a path, match the path against the injected ownership index (the union of every owning doc's globs), narrower glob wins. That is what layers them: a package doc claims `packages/{name}/**` and is the tree's **residual** owner, while a system doc claims the narrower subtrees of one machine and a feature doc claims one surface — both win those paths by specificity, and the package doc keeps everything neither claims. Two docs may never claim a path at **equal** specificity. Every other genre here owns no code, including the cross-cutting doctrine in `docs/architecture/common/`. See [`../references/frontmatter.md`](../references/frontmatter.md) for turning code into `owns:` globs.
+**Ownership.** Three genres speak for code — **feature**, **package**, **system**. A document names the objects it designs in `objects:`; a source file names the document that speaks for it in its path header; which document speaks for a path is computed from those headers and the object closure, and answered per path by the ownership index (`references/frontmatter.md`). Until the harness's ownership scan switches to that computation, it reads a transitional `owns:` region glob on each of the three genres: `packages/{name}/**` on a package document (the residual owner), a machine's subtrees on a system document, a feature's own directory on a feature document; the narrower glob wins.

package/data/harnesses/etna/skills/documentation/templates/docs-readme.md

@@ -21,7 +21,7 @@ The design layer — [architecture/](architecture/): {what the folder holds —
 
 ## Features
 
-[features/](features/) — one living reference per feature (how it works today), flat, named `{feature}.md`; each carries `owns:` for the code it speaks for. Find a feature by its name or by the ownership index, never by a row here.
+[features/](features/) — one living reference per feature (how it works today), flat, named `{feature}.md`; each names the objects it designs in `objects:`, and the source files it speaks for name it in their headers. Find a feature by its name or by the ownership index, never by a row here.
 
 ## Tests
 

package/data/harnesses/etna/skills/documentation/templates/doctrine.md

@@ -1,6 +1,6 @@
 # Doctrine Documentation (docs/architecture/common/{concern}.md)
 
-Truth document. Use for **one concern the platform handles everywhere**: authentication, authorization, storage, the API protocol, credentials, telemetry. One file per concern, named for the concern. A doctrine document owns no code and carries no `owns:`. A surface declares that it is bound by one through its own `applies:`.
+Truth document. Use for **one concern the platform handles everywhere**: authentication, authorization, storage, the API protocol, credentials, telemetry. One file per concern, named for the concern. A doctrine document speaks for no code: no source header names it, and it carries no `owns:`. The surfaces bound by it are the documents that design or touch the objects it governs, computed through those objects, and each names it in its Scope.
 
 **A doctrine document states the design and nothing beneath it** (`references/style-guide.md` § Shape — the model first, the detail after). It is the most stable document in the tree, because it says why the platform is shaped the way it is, and that changes far less often than the code. It explains no mechanism: no function, file, column, cookie attribute, header value or per-route error code, since each of those fails the stability test. The code graph answers what the code does. This document answers why, and which principles any new code in the concern must keep.
 
@@ -77,5 +77,5 @@ Code cannot reveal what it does not yet do, so decided-but-unbuilt intent is one
 | --- | --- |
 | A tour of the code that implements the concern | The code graph |
 | The catalog of routes, error codes or variables | An API reference or environment registry |
-| The one feature that happens to use the concern most | That feature's own document, which `applies:` this one |
+| The one feature that happens to use the concern most | That feature's own document, which names this doctrine in its Scope |
 | The story of how the concern got this way | A decision record (`decisions/`) for the why, and the changelog for the when |

package/data/harnesses/etna/skills/documentation/templates/feature.md

@@ -8,7 +8,7 @@ Truth document. Use for every feature in `docs/features/`: something a person po
 - **Each bullet is a bold label, then one or two third-person sentences** saying what happens: "**Organization user:** user lands in their existing organization", never "you land…".
 - **Flows carry the journey; Decisions carry the reasons; Promises run deepest.**
 
-Every computable fact (columns, vocabularies, foreign keys, writers, routes, guards, files) is the code graph's (`docs/architecture/systems/knowledge-layer.md`), and a hand-typed copy is the defect this genre removes. Code is named only where a person types or sees it (a page, a command, a flag, an environment variable) or at a cross-cutting seam the graph would not lead a reader to.
+The frontmatter names the objects the feature designs; which files it speaks for is computed from the source headers and the object closure, never listed (`references/frontmatter.md`). Every computable fact (columns, vocabularies, foreign keys, writers, routes, guards, files) is the code graph's (`docs/architecture/systems/knowledge-layer.md`), and a hand-typed copy is the defect this genre removes. Code is named only where a person types or sees it (a page, a command, a flag, an environment variable) or at a cross-cutting seam the graph would not lead a reader to.
 
 **A feature document runs deepest toward its end.** Scope and Flows are the model and the journey. **Promises** goes as deep as the behaviour does: every state the surface can be in, every edge case, what a refusal tells the person, and the exact wording wherever the wording itself is promised. That depth is earned because a person or a test checks it and the code cannot state it as intent. It still stops before mechanism. A promise reads "a removed membership shows a panel, not a redirect", never which route answers it.
 
@@ -32,9 +32,8 @@ Nothing else. `doc-lint` blocks the retired mechanism sections (`mechanism-secti
 type: feature                                    # required tooling key — preserve, never narrate
 status: active                                   # required — active | draft | deprecated
 objects: [device, credential grant]              # required — the product objects this document designs, by their graph names
-owns: ["packages/studio/src/server/routes/devices.ts"]  # required until the graph computes ownership — the code this document speaks for; narrower glob wins
 module: identity                                 # optional — one bounded-context label
-applies: [docs/architecture/common/security.md]  # optional — doctrine this surface is BOUND by
+owns: ["packages/studio/src/server/devices/**"]   # transitional — one region glob, read only by the ownership scan until it switches to header pointers (references/frontmatter.md)
 ---
 ```
 
@@ -90,6 +89,6 @@ No tables, routes or symbol rosters — those are the graph's.
 | When | What is written |
 | --- | --- |
 | `status: draft` (design) | goal, Scope, Decisions, Promises (with gaps named), For the agent; the LLD research goes to the plan |
-| `status: active` | Flows written from the shipped surface; `owns:` confirmed against real code |
+| `status: active` | Flows written from the shipped surface; `objects:` confirmed against the register, and each owned source file's header names this document |
 
 A feature whose code is gone is deleted, or `status: deprecated` with its footer pointing at what replaced it.

package/data/harnesses/etna/skills/documentation/templates/package.md

@@ -6,7 +6,7 @@ Truth document. Use for: **one workspace package** — one unit of distribution:
 
 **A package document's deepest layer is its public contract** (`references/style-guide.md` § Shape — the model first, the detail after): the commands and flags a person types, the exports another package imports, what is installed and where. For a CLI the flags *are* the promise, so they belong in Usage. It stops before internal layout, build steps and which file holds what.
 
-**A package document is the residual owner of its own tree.** Its `owns:` is the whole package glob — the broadest claim on those paths, so it loses to every narrower system or feature claim. The one enumerable fact it declares is the ownership table: which subtrees other documents claim.
+**A package document is the residual owner of its own tree.** Every file in the package whose header names no narrower document is its to speak for, so it loses to every system or feature document a header names. Until the ownership scan switches to header pointers, its transitional `owns:` is the whole package glob. The one enumerable fact it declares is the ownership table: which subtrees other documents speak for.
 
 **Sharp, bulleted, labelled with noun phrases** (`references/style-guide.md` § Labels). Every section after the goal line is bullets under a noun-phrase heading, each bullet a bold noun-phrase label followed by one or two sentences.
 
@@ -29,8 +29,7 @@ Nothing else. The feature template's lint rules apply. Forty to a hundred and tw
 type: package
 status: active
 objects: [nustack cli, device credential]        # required — the objects this package designs or ships
-owns: ["packages/{name}/**"]                     # required until the graph computes ownership — the residual claim
-applies: [docs/architecture/common/api.md]       # optional
+owns: ["packages/{name}/**"]                     # transitional — the residual region glob, read only by the ownership scan until it switches to header pointers
 ---
 ```
 

package/data/harnesses/etna/skills/documentation/templates/root-readme.md

@@ -37,7 +37,7 @@ Sections come in this order; 1 to 3 are the outward-facing first screen, 4 onwar
 - **Relative links into the repo only.** Never an absolute repo URL. Never an external site as the home of a canonical doc.
 - **Link folders and mandated scaffolds, never rosters.** The allowed targets are folders, `docs/README.md`, `docs/structure.md`, `docs/operations/setup.md`, `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `CLAUDE.md` and the owning docs in the Map. A procedure is named only where a Destinations row needs it. Every heading and table header is a noun phrase (`../references/style-guide.md` § Labels). Never list individual feature docs: the ownership index finds them.
 - **No tree.** The Map stops at top-level units and never lists files. Mark paths that look primary but are not, for example "`legacy/`: reference only, never edited".
-- **The Map is a coarse view of the ownership index, not a rival to it.** The Owning doc column names the doc that the index's `owns:` globs resolve to. When the two disagree the index wins, and the Map row is fixed in the same change.
+- **The Map is a coarse view of the ownership index, not a rival to it.** The Owning doc column names the doc the index resolves for that path. When the two disagree the index wins, and the Map row is fixed in the same change.
 - **No version numbers and no dates.** Name the file that pins a version (`.nvmrc`, `packageManager`, `rust-toolchain.toml`). Write in the present tense, with no "coming soon" and no "as of".
 - **State rules, don't argue them.** One line each. The reasoning lives in the linked doc, and agent process rules stay in `CLAUDE.md`.
 - **Commands come from the repo.** Detect the package manager from the lockfile (`pnpm-lock.yaml` gives pnpm, `yarn.lock` gives yarn, otherwise npm). Use only scripts that exist, each with a trailing comment saying what it does.

package/data/harnesses/etna/skills/documentation/templates/system.md

@@ -6,7 +6,7 @@ Truth document. Use for: **one machine that spans packages**, which a person can
 
 **A system document's deepest layer is the machine's behaviour across packages** (`references/style-guide.md` § Shape — the model first, the detail after): the order it runs in, the sequence and state diagrams at role level, the invariant that holds at each place where parts meet, and what re-drives a stall. That layer is earned because no single file shows a cross-package flow. It stops before per-function steps, tables, columns and routes.
 
-**A system document's globs win by specificity.** Its `owns:` names the subtrees and exact files the machine is made of, narrower than the package glob. Two documents never claim a path at equal specificity; every glob matches a file on disk at `status: active`.
+**A system document speaks for the files the machine is made of.** Their headers name it, which outranks the package document's residual claim. Until the ownership scan switches to header pointers, its transitional `owns:` names the machine's subtrees as region globs, narrower than the package glob; every glob matches a file on disk at `status: active`.
 
 **Sharp, bulleted, labelled with noun phrases** (`references/style-guide.md` § Labels). The opening paragraph defines the machine; everything after it is bullets under noun-phrase headings, each bullet a bold noun-phrase label followed by one or two sentences.
 
@@ -28,10 +28,8 @@ Nothing else. The lint rules of the feature template apply. Sixty to a hundred a
 type: system                                     # required tooling key
 status: active                                   # required — draft = the machine as a whole does not run
 objects: [run, run ledger, settlement]           # required — the objects this machine owns or moves
-owns:                                            # required until the graph computes ownership — narrower than the package glob
+owns:                                            # transitional — region globs, one per subtree; read only by the ownership scan until it switches to header pointers (references/frontmatter.md)
   - packages/{pkg}/src/{machine}/**
-applies:                                         # optional — decisions and doctrine this machine is BOUND by
-  - docs/architecture/decisions/AD-0NN-{slug}.md
 ---
 ```
 

package/data/harnesses/etna/skills/documentation/templates/ux-behavior.md

@@ -2,7 +2,7 @@
 
 **Truth document.** States what a person sees and can do on a surface, and what the surface promises never to do. Present tense, like every truth document.
 
-**`type: ux`**, plus `applies:` — the architecture docs this surface is bound by (the state vocabulary, the routing doctrine, the information architecture it answers to). Same key and same narrow reading as a feature doc's: obligation, not a reading list.
+**`type: ux`**, plus `status:` and `objects:` — the objects the surface presents (`references/frontmatter.md`). The doctrine it answers to (the state vocabulary, the routing doctrine, the information architecture) is named in its Purpose for people and computed through shared objects for tooling.
 
 **Why this genre exists.** A feature doc (LLD) states what a feature is, how its data flows, and which contracts it honours — all of which stay plausibly true through a rewrite of the surface. Nothing else in the repo states what a person *observes*. So a change to the wire lands, the interface absorbs it, and the absorption reads as maintenance: no test fails, no lint fires, no document is contradicted. This document is the thing a silent change contradicts.
 
@@ -12,12 +12,12 @@
 
 | The behavior is… | Where it lives |
 | --- | --- |
-| One surface's — a panel, an editor, a dialog | `docs/features/{surface}-ux.md`, with `owns:` over that surface's component paths |
+| One surface's — a panel, an editor, a dialog | `docs/features/{surface}-ux.md`; its component files' headers name it |
 | Cross-cutting — routing, information architecture, the state vocabulary every surface obeys, presentation of streams | `docs/architecture/` — owns no code, like every architecture doc |
 
-**Ownership: take the component globs only where they are unclaimed.** A surface's components are frequently already owned — by the page's LLD, by the feature behind one panel — and claiming them again is an ownership conflict, not protection. So: unclaimed globs go in `owns:`; otherwise the doc declares `owns: []` and is named in each owning LLD's **coordinated edits** row, phrased as *different axes, not a conflict* — the LLD owns the code, this document owns what a person observes.
+**Ownership: a component file names one document in its header.** A surface's components are frequently already spoken for — by the page's feature document, by the feature behind one panel — and a file's header names exactly one document. Where the header already names the feature document, this document is named in that feature document's **coordinated edits** row instead, phrased as *different promises over the same files*, and the object closure links the two through the objects both name. Where no document speaks for the component yet, its header names this one.
 
-That matters because a doc nothing implicates is a doc that rots, and a surface rewritten under an unimplicated document is the failure this genre exists to prevent. The coordinated-edit row is the weaker of the two bindings; prefer real ownership wherever the globs are free.
+That matters because a doc nothing implicates is a doc that rots, and a surface rewritten under an unimplicated document is the failure this genre exists to prevent. The coordinated-edit row is the weaker of the two bindings; prefer the header pointer wherever no document speaks for the component yet.
 
 ---
 

package/lib/install/mount.mjs

@@ -204,7 +204,7 @@ function removeEmptyParents(projectDir, rel) {
   }
 }
 
-// Writes the manifest's mounted files that differ on disk, then deletes owned names the manifest omits.
+// Fetches the manifest's mounted files that differ on disk, writes them deepest path first, then deletes owned names the manifest omits.
 async function mountFromManifest({ projectDir, manifest, origin, cacheDir, fetchImpl, timeoutMs, priorOwned }) {
   const all = mountedEntries(manifest);
   const entries = admittedEntries(projectDir, all);
@@ -216,14 +216,28 @@ async function mountFromManifest({ projectDir, manifest, origin, cacheDir, fetch
     const dest = join(projectDir, entry.path);
     return !(existsSync(dest) && sha256Of(readFileSync(dest)) === entry.sha256);
   });
+  // Booby trap: every live session in the checkout runs these hooks while the mount rewrites them.
+  // Writing as each fetch lands let `hooks/compliance.mjs` arrive seconds before a new `hooks/lib/`
+  // module it imports, and every hook call in that window died with ERR_MODULE_NOT_FOUND (3.20.1
+  // rollout, 2026-10-05). Fetch everything, then write locally, imports (deeper paths) before importers.
+  const fetched = [];
   await eachLimited(stale, async (entry) => {
     try {
-      writeAtomic(join(projectDir, entry.path), await readObject({ origin, entry, cacheDir, fetchImpl, timeoutMs }));
-      written.push(entry.path);
+      fetched.push({ entry, bytes: await readObject({ origin, entry, cacheDir, fetchImpl, timeoutMs }) });
     } catch {
       failed.push(entry.path);
     }
   });
+  const depth = (path) => path.split('/').length;
+  fetched.sort((a, b) => depth(b.entry.path) - depth(a.entry.path) || a.entry.path.localeCompare(b.entry.path));
+  for (const { entry, bytes } of fetched) {
+    try {
+      writeAtomic(join(projectDir, entry.path), bytes);
+      written.push(entry.path);
+    } catch {
+      failed.push(entry.path);
+    }
+  }
   for (const rel of prunableFiles(projectDir, unionOwned(manifest.owned, priorOwned))) {
     if (listed.has(rel)) continue;
     rmSync(join(projectDir, rel), { force: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nurix/etna",
-  "version": "0.20.29",
+  "version": "0.20.31",
   "description": "Bootstrap a project with a Nurix harness — writes the committed contract (CLAUDE.md, AGENTS.md, .claude/harness.json, settings.json, the mount hook) and mounts the harness itself, gitignored, from a bundled payload; sessions keep it current from the CDN.",
   "type": "module",
   "bin": {
@@ -46,5 +46,5 @@
     "agent",
     "plugin"
   ],
-  "etnaFingerprint": "46abe9f3c2dd"
+  "etnaFingerprint": "1ced34191650"
 }