@nurix/etna 0.20.30 → 0.20.32

package/data/harness-index.json

@@ -1,5 +1,5 @@
 {
-    "fingerprint": "687486a21483",
+    "fingerprint": "1b90a96b3812",
     "harnesses": {
         "code": {
             "plugin": "code",

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

@@ -64,6 +64,7 @@ Across the header pointers and the transitional globs:
 - **Retired keys:** `applies:` and `keywords:` are removed wherever found (remediation); a doctrine the removed `applies:` named stays named in the document's Scope section.
 - Flag **equal-specificity overlaps** — two feature docs whose transitional `owns:` globs claim the same paths at the same specificity (an ambiguous owner). `node .claude/hooks/check-ownership.mjs` reports these mechanically alongside dead globs (`overlaps()` in `lib/ownership.mjs`); a glob at strictly higher specificity carving out of a broader `**` is the designed layering and is never flagged. Surface a real overlap as a question — narrowing someone's glob is an author's call, not remediation.
 - **Stamp `type:` where missing.** Every doc carries a `type:` genre key (enum = the `documentation` skill's template names); docs predating the key are stamped mechanically — the genre is readable from placement and shape (a `docs/features/` doc is `type: feature`, an AD is `type: architecture-decision`). Stamping is remediation, not a question; an ambiguous genre is backlogged instead.
+- **Write `description:` where missing.** Every truth document and folder index carries a `description:` of at most 300 characters saying what it settles and where its boundary sits (`documentation` skill, `references/frontmatter.md` § `description:`). Each one is written from a read of the document, never from its filename — many documents ⇒ parallel sub-agents on the cheapest capable tier, one batch each. A folder index that names its files or records is rewritten to describe the folder, after confirming every per-file fact it carried lives in that file.
 
 **Then validate the doc→doc edge.** `node .claude/hooks/check-ownership.mjs` and the session-injected **doc edge index** carry `verifies:` and its generated inverse; read the edge index and check two things:
 

package/data/harnesses/code/harness.json

@@ -1,7 +1,7 @@
 {
   "harness": "code",
   "name": "code",
-  "version": "3.20.1",
+  "version": "3.20.3",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
@@ -29,5 +29,5 @@
     "origin": "https://cdn.nustack.io",
     "track": "latest"
   },
-  "digest": "f52d24285ab6"
+  "digest": "0bde4238378a"
 }

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

@@ -206,7 +206,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);
@@ -218,14 +218,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/data/harnesses/code/skills/documentation/SKILL.md

@@ -72,6 +72,7 @@ The two guarantees are complementary and both break on mixing: a reader holding
 - **Records are never edited to match the present.** A completed plan stays wrong-in-hindsight; a changelog entry describes close-time state; a scope change gets a *new* dated record that links back, never an edit to a frozen one.
 - **Two sanctioned bridges — head is truth, tail is provenance.** An **Architecture Decision (AD)** ends with a **Decision Changelog** (for a decision, the journey — what each revision reversed and what triggered it — is part of the reasoning), and the `maintenance` agent's **Health Log** lives in `docs/history/health-log.md`, an append-only record. The AD body stays current-truth-only; the tail carries the dates. No other truth document carries dated history. `docs/structure.md` is harness-owned — written whole by the installer, never edited by hand or by a skill; only its `harness-version` frontmatter is stamped, by the `maintenance` agent.
 - **Indexes describe directories, never files.** `docs/README.md` — the top-level index of the documentation folder — is a description of its directories: one entry per folder saying what the folder holds, who reads it and how its files are named. It carries no file list and no file tree: not a per-file row, not a `├──` tree of files, not a tree at all — `docs/structure.md` is the one place the tree lives, as the authority on placement. The same holds for a `README.md` / `Readme.md` at any level of `docs/`. `ls` is the roster, and the ownership index is how a document is found for a path. A per-file row has to be edited on every add, rename and retirement, so the index's history records roster churn instead of what the index said, and a reader cannot tell when the index itself changed. The only files an index may link are the mandated scaffolds (`structure.md`, `operations/setup.md`, `history/CHANGELOG.md`, `history/backlog.md`, `memory/main.md`) and a sibling folder's own `Readme.md`. `scripts/doc-lint.mjs` blocks the rest as `index-lists-files`, and blocks a tree drawn in a folder index as `index-file-tree`. An inverse (which checklists verify a feature, which docs a folder holds) is generated, never written.
+- **Every document describes itself.** Its frontmatter carries `description:` — at most 300 characters, one or two present-tense sentences saying what the document settles and where its boundary sits (`references/frontmatter.md` § `description:`). That is the per-file account an index would otherwise keep, so an index names no file and no record: not a link, not a filename, not an ID row such as `AD-010`. A folder is browsed with `grep -m1 '^description:' <folder>/*.md`. `doc-lint` blocks a truth document or folder index without one (`description-missing`), one over 300 characters (`description-length`), and an index row that names a file or record (`index-names-records`).
 - **Truth documents cite records for the _why_, never the _when_.** `Provenance: AD-002` is good; "decided in AD-002 and shipped 2026-06-13" is not. Routing/index docs point only to truth documents as a topic's authority — never a plan or changelog entry as the "read first" source. (An index _of the records themselves_ — a History section listing `plans/`, `changelog/` — is sanctioned.)
 
 **A document is intent and promises; facts are the graph's.** An owning document (feature, package, system) answers why the product is shaped this way and what it promises, and names the objects it designs in `objects:`. Every computable fact — a table's columns and vocabularies, a foreign key and its delete rule, which function writes which column, which route sits behind which guard, which code a refusal answers, which file holds what — is the code graph's to compute (`docs/architecture/systems/knowledge-layer.md`), and a hand-typed copy of it is the defect this rule removes: it reads as authoritative and is wrong the day the code moves. Mechanism stays in the code, reasons stay in the document, and the document points by object and symbol name, never by line number. `doc-lint` blocks the retired mechanism sections in an owning document (`mechanism-section`) and an owning document without `objects:`. `keywords:` is not a key: an object's name is its discovery term. **The body is scanned by people** — sharp bullets under noun-phrase headings, each a bold noun-phrase label, a colon, then one or two plain sentences; code named only where a person types or sees it, or at a cross-cutting seam the graph would not lead a reader to (a middleware, a gate, a hook, a shared store); every other pointer in the closing **For the agent** footer. The owning genres read Scope · Flows (Flow for a system, Usage for a package) · Decisions · Promises · Gaps · For the agent (`references/style-guide.md` § Labels, § Owning documents — the body and the footer; `doc-lint` warns `body-identifier`, `clause-label` and `second-person`).

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

@@ -15,24 +15,32 @@ A document names the product objects it designs. Every other edge between a docu
 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.
+6. **The description as the per-file account:** every document states what it is about in its own `description:`. A folder is browsed by reading its files' descriptions, so no index keeps a row per file.
 
 ## Keys by genre
 
 | 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 |
+| Feature | `type`, `description`, `status`, `objects`, `module` (optional) · transitional `owns` |
+| System | `type`, `description`, `status`, `objects` · transitional `owns` |
+| Package | `type`, `description`, `status`, `objects` · transitional `owns` |
+| Doctrine | `type`, `description`, `status`, `objects` |
+| UX | `type`, `description`, `status`, `objects` · transitional `owns` when it speaks for a surface's components |
+| Behavioral checklist | `type: checklist`, `description`, `verifies` |
+| Acceptance criteria | `type`, `description`, `status` |
+| Every other genre | `type`, `description`, plus its template's own keys |
 
 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.
 
 ## Keys
 
+### `description:`
+
+- **Values:** one plain string of at most 300 characters on one line: what the document settles and where its boundary sits, in one or two third-person, present-tense sentences. "How a person signs in to NuStack — the web, command-line and desktop doors, the session each mints, and what a refused sign-in shows; enterprise single sign-on is its own document." The description does not open with "This document"; it carries no file list, no date and no status.
+- **Required on:** every truth document and every folder index; a record carries it wherever its template has frontmatter (a changelog entry's one-line summary is its row in `CHANGELOG.md`). A frozen record that predates the key is never edited to add it. Exempt: `docs/structure.md`, which the installer writes whole, and a tree a generator owns (`docs/dna/`, the product-dna skill's).
+- **Reading:** it is how a folder is browsed without an index row per file: `grep -m1 '^description:' docs/features/*.md`. Tooling that lists documents shows it beside the path.
+- **Upkeep:** an edit that changes what a document settles updates its description in the same edit.
+
 ### `objects:`
 
 - **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.
@@ -81,4 +89,5 @@ An edit to a document that carries a retired key removes the key in the same edi
 - **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.
+- **Indexes name no files:** a folder index describes what its folder holds and how its files are named; the per-file account is each file's `description:`. A row per file, record or ID (`AD-010`) in an index is a defect.
+- **Baseline and reconcile:** the `maintenance` agent stamps `type:`, `description:` 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/code/skills/documentation/references/style-guide.md

@@ -37,7 +37,7 @@ Every genre takes the same shape (principle 2) and the same labels (principle 5)
 - **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.
+- **Indexes:** a folder's `Readme.md` describes directories, never files — no link, filename or record ID per file; each file's own `description:` frontmatter is its account. The root README follows `templates/root-readme.md`. Both take § Labels.
 
 ## Shape — the model first, the detail after
 

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

@@ -149,6 +149,37 @@ function lintFile(path, findings) {
     const tree = rawLines.find(({ line }) => /^\s*[│├└]/.test(line));
     if (tree) findings.push({ path, n: tree.n, severity: 'block', id: 'index-file-tree', message: 'a tree drawn in a folder index — describe each directory in a sentence; the tree is docs/structure.md\'s', excerpt: tree.line.trim().slice(0, 90) });
   }
+  // A file or record named without a link is the same per-file row as a link (SKILL.md § Every document describes itself).
+  // docs/dna/ is the product-dna skill's generated tree, laid out by that skill's own schema.
+  const isGeneratedTree = /(^|\/)docs\/dna\//.test(path);
+  if (scope === 'truth' && isFolderIndex && /(^|\/)docs\//.test(path) && !isGeneratedTree && !disabled.has('index-names-records')) {
+    const SCAFFOLD_NAME = /^(readme|structure|changelog|backlog|main|health-log|journal|claude|agents|setup)\.md$/i;
+    for (const { n, line } of lines) {
+      if (line.includes('doc-lint-disable: index-names-records')) continue;
+      const named = [...line.matchAll(/(?<![\w/{}-])([\w.-]+\.md)\b/g)].map((m) => m[1]).find((f) => !SCAFFOLD_NAME.test(f) && !/YYYY|NNN|[A-Z]\.[A-Z]/.test(f));
+      const recordRow = /^\|\s*\[?`?[A-Z]{2,}-\d+/.test(line.trim());
+      if (named || recordRow) findings.push({ path, n, severity: 'block', id: 'index-names-records', message: `index names an individual ${recordRow ? 'record' : `file (\`${named}\`)`} — describe the folder; each file's \`description:\` frontmatter is its account`, excerpt: line.trim().slice(0, 90) });
+    }
+  }
+  // Every truth document and folder index under docs/ describes itself in at most 300 characters (references/frontmatter.md § description:).
+  if (scope === 'truth' && /(^|\/)docs\//.test(path) && !isGeneratedTree && !isAuthorityMap && !disabled.has('description-missing')) {
+    const fmEnd = text.startsWith('---') ? text.indexOf('\n---', 3) : -1;
+    const fmText = fmEnd === -1 ? '' : text.slice(0, fmEnd);
+    const m = /^description:[ \t]*(.*)$/m.exec(fmText);
+    if (!m) findings.push({ path, n: 1, severity: 'block', id: 'description-missing', message: 'no `description:` in the frontmatter — at most 300 characters saying what this document settles and where its boundary sits' });
+    else {
+      let value = m[1].trim();
+      if (/^[>|][-+]?$/.test(value)) {
+        const rest = fmText.slice(m.index + m[0].length).split('\n').slice(1);
+        const block = [];
+        for (const l of rest) { if (/^\s+\S/.test(l)) block.push(l.trim()); else break; }
+        value = block.join(' ');
+      }
+      value = value.replace(/^(["'])(.*)\1$/, '$2');
+      if (!value) findings.push({ path, n: 1, severity: 'block', id: 'description-missing', message: '`description:` is empty — at most 300 characters saying what this document settles and where its boundary sits' });
+      else if (value.length > 300 && !disabled.has('description-length')) findings.push({ path, n: 1, severity: 'block', id: 'description-length', message: `\`description:\` is ${value.length} characters — at most 300` });
+    }
+  }
   // The repo-root README is an orientation page with a budget (templates/root-readme.md): up to about 140 non-blank lines, plain Markdown, no chrome.
   if (scope === 'truth' && isRootReadme) {
     const raw = text.split('\n');

package/data/harnesses/code/skills/documentation/templates/acceptance-criteria.md

@@ -24,6 +24,7 @@ a claim to grade the built product against.
 ```markdown
 ---
 type: acceptance-criteria
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
 status: draft
 ---
 

package/data/harnesses/code/skills/documentation/templates/behavioral-checklist.md

@@ -7,6 +7,7 @@ Truth document. Use for: **how to verify one feature's promised behavior by driv
 ```yaml
 ---
 type: checklist                            # required tooling key — genre stamp
+description: "{at most 300 characters: what this document settles and where its boundary sits}" # required — the per-file account a folder is browsed by (references/frontmatter.md)
 verifies: [docs/features/auth.md]          # required — the doc(s) whose promises this proves
 ---
 ```

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

@@ -2,11 +2,16 @@
 
 Truth document. Use for: the entry point for all documentation in a repo. Created during baseline audit.
 
-**This file describes directories, never files.** Each section names one folder under `docs/` and says what the folder holds, who reads it and how its files are named — a description of the directory, not of its contents. No per-file rows, no file tree, no `├──` block: the tree is `structure.md`'s, as the authority on placement, and `ls` is the roster. A row per file forces an index edit on every file added, renamed or retired, and the index's own history then records roster churn instead of what the index said — a repo carried 103 commits on `docs/README.md` before this rule, most of them row edits. Each section below names a folder and says what the folder holds and how its files are named; the only files an index may name are the mandated scaffolds (`structure.md`, `operations/setup.md`, `history/CHANGELOG.md`, `history/backlog.md`) and the root `CLAUDE.md`. The repo-root `README.md` routes the team and agents in by intent; this file describes the folders of the docs tree — each links the other once and neither restates the other. `doc-lint` blocks a folder index that links an individual document (`index-lists-files`) or draws a tree (`index-file-tree`).
+**This file describes directories, never files.** Each section names one folder under `docs/` and says what the folder holds, who reads it and how its files are named — a description of the directory, not of its contents. No per-file rows, no file tree, no `├──` block: the tree is `structure.md`'s, as the authority on placement, and `ls` is the roster. A row per file forces an index edit on every file added, renamed or retired, and the index's own history then records roster churn instead of what the index said — a repo carried 103 commits on `docs/README.md` before this rule, most of them row edits. Each section below names a folder and says what the folder holds and how its files are named; the only files an index may name are the mandated scaffolds (`structure.md`, `operations/setup.md`, `history/CHANGELOG.md`, `history/backlog.md`) and the root `CLAUDE.md`. The repo-root `README.md` routes the team and agents in by intent; this file describes the folders of the docs tree — each links the other once and neither restates the other. Naming a file without a link is the same row: no filename, no record ID (`AD-010`), no per-record table. Each file's own `description:` frontmatter is its account, read with `grep -m1 '^description:' <folder>/*.md`. `doc-lint` blocks a folder index that links an individual document (`index-lists-files`), names one (`index-names-records`) or draws a tree (`index-file-tree`).
 
 **Link only what exists.** Every row below is a placeholder — drop any whose target the repo does not have. Most `history/` and `architecture/` folders are created on first use, so linking them unconditionally ships a docs index with dead links on day one. An index is a browse page: a link that resolves to nothing is worse than an absent row.
 
 ```
+---
+type: docs-readme
+description: "{at most 300 characters: what the documentation tree holds and how it is organised}"
+---
+
 # {Project Name} Documentation
 
 Technical documentation for {project description}. {Two or three sentences: what the product is, its planes or packages, who the docs are for.}

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

@@ -22,6 +22,7 @@ Nothing else: the neighbouring documents live in **For the agent**, the one clos
 ```yaml
 ---
 type: doctrine                                   # required tooling key
+description: "{at most 300 characters: what this document settles and where its boundary sits}" # required — the per-file account a folder is browsed by (references/frontmatter.md)
 status: active                                   # required — active | draft
 objects: [principal, credential, device grant]   # recommended — the concepts this doctrine governs, by their graph names
 ---

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

@@ -30,6 +30,7 @@ Nothing else. `doc-lint` blocks the retired mechanism sections (`mechanism-secti
 ```yaml
 ---
 type: feature                                    # required tooling key — preserve, never narrate
+description: "{at most 300 characters: what this document settles and where its boundary sits}" # required — the per-file account a folder is browsed by (references/frontmatter.md)
 status: active                                   # required — active | draft | deprecated
 objects: [device, credential grant]              # required — the product objects this document designs, by their graph names
 module: identity                                 # optional — one bounded-context label

package/data/harnesses/code/skills/documentation/templates/handover.md

@@ -9,6 +9,7 @@ Required: **Verdict**, **Decide today**, **Live-world ledger** (even when empty)
 ````markdown
 ---
 type: handover
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
 status: {open | accepted}
 date: {YYYY-MM-DD}
 as_of: {YYYY-MM-DDTHH:MM±TZ}

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

@@ -27,6 +27,7 @@ Nothing else. The feature template's lint rules apply. Forty to a hundred and tw
 ```yaml
 ---
 type: package
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
 status: active
 objects: [nustack cli, device credential]        # required — the objects this package designs or ships
 owns: ["packages/{name}/**"]                     # transitional — the residual region glob, read only by the ownership scan until it switches to header pointers

package/data/harnesses/code/skills/documentation/templates/setup.md

@@ -25,6 +25,7 @@ Required: **Goal**, **Stack**, **Prerequisites**, **Install**, **First run**, **
 ```markdown
 ---
 type: operations
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
 ---
 
 # Setup

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

@@ -26,6 +26,7 @@ Nothing else. The lint rules of the feature template apply. Sixty to a hundred a
 ```yaml
 ---
 type: system                                     # required tooling key
+description: "{at most 300 characters: what this document settles and where its boundary sits}" # required — the per-file account a folder is browsed by (references/frontmatter.md)
 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:                                            # transitional — region globs, one per subtree; read only by the ownership scan until it switches to header pointers (references/frontmatter.md)

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

@@ -64,6 +64,7 @@ Across the header pointers and the transitional globs:
 - **Retired keys:** `applies:` and `keywords:` are removed wherever found (remediation); a doctrine the removed `applies:` named stays named in the document's Scope section.
 - Flag **equal-specificity overlaps** — two feature docs whose transitional `owns:` globs claim the same paths at the same specificity (an ambiguous owner). `node .claude/hooks/check-ownership.mjs` reports these mechanically alongside dead globs (`overlaps()` in `lib/ownership.mjs`); a glob at strictly higher specificity carving out of a broader `**` is the designed layering and is never flagged. Surface a real overlap as a question — narrowing someone's glob is an author's call, not remediation.
 - **Stamp `type:` where missing.** Every doc carries a `type:` genre key (enum = the `documentation` skill's template names); docs predating the key are stamped mechanically — the genre is readable from placement and shape (a `docs/features/` doc is `type: feature`, an AD is `type: architecture-decision`). Stamping is remediation, not a question; an ambiguous genre is backlogged instead.
+- **Write `description:` where missing.** Every truth document and folder index carries a `description:` of at most 300 characters saying what it settles and where its boundary sits (`documentation` skill, `references/frontmatter.md` § `description:`). Each one is written from a read of the document, never from its filename — many documents ⇒ parallel sub-agents on the cheapest capable tier, one batch each. A folder index that names its files or records is rewritten to describe the folder, after confirming every per-file fact it carried lives in that file.
 
 **Then validate the doc→doc edge.** `node .claude/hooks/check-ownership.mjs` and the session-injected **doc edge index** carry `verifies:` and its generated inverse; read the edge index and check two things:
 

package/data/harnesses/delivery/harness.json

@@ -1,7 +1,7 @@
 {
   "harness": "delivery",
   "name": "delivery",
-  "version": "0.2.39",
+  "version": "0.2.40",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
@@ -14,5 +14,5 @@
     "origin": "https://cdn.nustack.io",
     "track": "latest"
   },
-  "digest": "7837822ea61e"
+  "digest": "5a9f81fff98a"
 }

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

@@ -72,6 +72,7 @@ The two guarantees are complementary and both break on mixing: a reader holding
 - **Records are never edited to match the present.** A completed plan stays wrong-in-hindsight; a changelog entry describes close-time state; a scope change gets a *new* dated record that links back, never an edit to a frozen one.
 - **Two sanctioned bridges — head is truth, tail is provenance.** An **Architecture Decision (AD)** ends with a **Decision Changelog** (for a decision, the journey — what each revision reversed and what triggered it — is part of the reasoning), and the `maintenance` agent's **Health Log** lives in `docs/history/health-log.md`, an append-only record. The AD body stays current-truth-only; the tail carries the dates. No other truth document carries dated history. `docs/structure.md` is harness-owned — written whole by the installer, never edited by hand or by a skill; only its `harness-version` frontmatter is stamped, by the `maintenance` agent.
 - **Indexes describe directories, never files.** `docs/README.md` — the top-level index of the documentation folder — is a description of its directories: one entry per folder saying what the folder holds, who reads it and how its files are named. It carries no file list and no file tree: not a per-file row, not a `├──` tree of files, not a tree at all — `docs/structure.md` is the one place the tree lives, as the authority on placement. The same holds for a `README.md` / `Readme.md` at any level of `docs/`. `ls` is the roster, and the ownership index is how a document is found for a path. A per-file row has to be edited on every add, rename and retirement, so the index's history records roster churn instead of what the index said, and a reader cannot tell when the index itself changed. The only files an index may link are the mandated scaffolds (`structure.md`, `operations/setup.md`, `history/CHANGELOG.md`, `history/backlog.md`, `memory/main.md`) and a sibling folder's own `Readme.md`. `scripts/doc-lint.mjs` blocks the rest as `index-lists-files`, and blocks a tree drawn in a folder index as `index-file-tree`. An inverse (which checklists verify a feature, which docs a folder holds) is generated, never written.
+- **Every document describes itself.** Its frontmatter carries `description:` — at most 300 characters, one or two present-tense sentences saying what the document settles and where its boundary sits (`references/frontmatter.md` § `description:`). That is the per-file account an index would otherwise keep, so an index names no file and no record: not a link, not a filename, not an ID row such as `AD-010`. A folder is browsed with `grep -m1 '^description:' <folder>/*.md`. `doc-lint` blocks a truth document or folder index without one (`description-missing`), one over 300 characters (`description-length`), and an index row that names a file or record (`index-names-records`).
 - **Truth documents cite records for the _why_, never the _when_.** `Provenance: AD-002` is good; "decided in AD-002 and shipped 2026-06-13" is not. Routing/index docs point only to truth documents as a topic's authority — never a plan or changelog entry as the "read first" source. (An index _of the records themselves_ — a History section listing `plans/`, `changelog/` — is sanctioned.)
 
 **A document is intent and promises; facts are the graph's.** An owning document (feature, package, system) answers why the product is shaped this way and what it promises, and names the objects it designs in `objects:`. Every computable fact — a table's columns and vocabularies, a foreign key and its delete rule, which function writes which column, which route sits behind which guard, which code a refusal answers, which file holds what — is the code graph's to compute (`docs/architecture/systems/knowledge-layer.md`), and a hand-typed copy of it is the defect this rule removes: it reads as authoritative and is wrong the day the code moves. Mechanism stays in the code, reasons stay in the document, and the document points by object and symbol name, never by line number. `doc-lint` blocks the retired mechanism sections in an owning document (`mechanism-section`) and an owning document without `objects:`. `keywords:` is not a key: an object's name is its discovery term. **The body is scanned by people** — sharp bullets under noun-phrase headings, each a bold noun-phrase label, a colon, then one or two plain sentences; code named only where a person types or sees it, or at a cross-cutting seam the graph would not lead a reader to (a middleware, a gate, a hook, a shared store); every other pointer in the closing **For the agent** footer. The owning genres read Scope · Flows (Flow for a system, Usage for a package) · Decisions · Promises · Gaps · For the agent (`references/style-guide.md` § Labels, § Owning documents — the body and the footer; `doc-lint` warns `body-identifier`, `clause-label` and `second-person`).

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

@@ -15,24 +15,32 @@ A document names the product objects it designs. Every other edge between a docu
 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.
+6. **The description as the per-file account:** every document states what it is about in its own `description:`. A folder is browsed by reading its files' descriptions, so no index keeps a row per file.
 
 ## Keys by genre
 
 | 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 |
+| Feature | `type`, `description`, `status`, `objects`, `module` (optional) · transitional `owns` |
+| System | `type`, `description`, `status`, `objects` · transitional `owns` |
+| Package | `type`, `description`, `status`, `objects` · transitional `owns` |
+| Doctrine | `type`, `description`, `status`, `objects` |
+| UX | `type`, `description`, `status`, `objects` · transitional `owns` when it speaks for a surface's components |
+| Behavioral checklist | `type: checklist`, `description`, `verifies` |
+| Acceptance criteria | `type`, `description`, `status` |
+| Every other genre | `type`, `description`, plus its template's own keys |
 
 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.
 
 ## Keys
 
+### `description:`
+
+- **Values:** one plain string of at most 300 characters on one line: what the document settles and where its boundary sits, in one or two third-person, present-tense sentences. "How a person signs in to NuStack — the web, command-line and desktop doors, the session each mints, and what a refused sign-in shows; enterprise single sign-on is its own document." The description does not open with "This document"; it carries no file list, no date and no status.
+- **Required on:** every truth document and every folder index; a record carries it wherever its template has frontmatter (a changelog entry's one-line summary is its row in `CHANGELOG.md`). A frozen record that predates the key is never edited to add it. Exempt: `docs/structure.md`, which the installer writes whole, and a tree a generator owns (`docs/dna/`, the product-dna skill's).
+- **Reading:** it is how a folder is browsed without an index row per file: `grep -m1 '^description:' docs/features/*.md`. Tooling that lists documents shows it beside the path.
+- **Upkeep:** an edit that changes what a document settles updates its description in the same edit.
+
 ### `objects:`
 
 - **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.
@@ -81,4 +89,5 @@ An edit to a document that carries a retired key removes the key in the same edi
 - **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.
+- **Indexes name no files:** a folder index describes what its folder holds and how its files are named; the per-file account is each file's `description:`. A row per file, record or ID (`AD-010`) in an index is a defect.
+- **Baseline and reconcile:** the `maintenance` agent stamps `type:`, `description:` 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/delivery/skills/documentation/references/style-guide.md

@@ -37,7 +37,7 @@ Every genre takes the same shape (principle 2) and the same labels (principle 5)
 - **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.
+- **Indexes:** a folder's `Readme.md` describes directories, never files — no link, filename or record ID per file; each file's own `description:` frontmatter is its account. The root README follows `templates/root-readme.md`. Both take § Labels.
 
 ## Shape — the model first, the detail after
 

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

@@ -149,6 +149,37 @@ function lintFile(path, findings) {
     const tree = rawLines.find(({ line }) => /^\s*[│├└]/.test(line));
     if (tree) findings.push({ path, n: tree.n, severity: 'block', id: 'index-file-tree', message: 'a tree drawn in a folder index — describe each directory in a sentence; the tree is docs/structure.md\'s', excerpt: tree.line.trim().slice(0, 90) });
   }
+  // A file or record named without a link is the same per-file row as a link (SKILL.md § Every document describes itself).
+  // docs/dna/ is the product-dna skill's generated tree, laid out by that skill's own schema.
+  const isGeneratedTree = /(^|\/)docs\/dna\//.test(path);
+  if (scope === 'truth' && isFolderIndex && /(^|\/)docs\//.test(path) && !isGeneratedTree && !disabled.has('index-names-records')) {
+    const SCAFFOLD_NAME = /^(readme|structure|changelog|backlog|main|health-log|journal|claude|agents|setup)\.md$/i;
+    for (const { n, line } of lines) {
+      if (line.includes('doc-lint-disable: index-names-records')) continue;
+      const named = [...line.matchAll(/(?<![\w/{}-])([\w.-]+\.md)\b/g)].map((m) => m[1]).find((f) => !SCAFFOLD_NAME.test(f) && !/YYYY|NNN|[A-Z]\.[A-Z]/.test(f));
+      const recordRow = /^\|\s*\[?`?[A-Z]{2,}-\d+/.test(line.trim());
+      if (named || recordRow) findings.push({ path, n, severity: 'block', id: 'index-names-records', message: `index names an individual ${recordRow ? 'record' : `file (\`${named}\`)`} — describe the folder; each file's \`description:\` frontmatter is its account`, excerpt: line.trim().slice(0, 90) });
+    }
+  }
+  // Every truth document and folder index under docs/ describes itself in at most 300 characters (references/frontmatter.md § description:).
+  if (scope === 'truth' && /(^|\/)docs\//.test(path) && !isGeneratedTree && !isAuthorityMap && !disabled.has('description-missing')) {
+    const fmEnd = text.startsWith('---') ? text.indexOf('\n---', 3) : -1;
+    const fmText = fmEnd === -1 ? '' : text.slice(0, fmEnd);
+    const m = /^description:[ \t]*(.*)$/m.exec(fmText);
+    if (!m) findings.push({ path, n: 1, severity: 'block', id: 'description-missing', message: 'no `description:` in the frontmatter — at most 300 characters saying what this document settles and where its boundary sits' });
+    else {
+      let value = m[1].trim();
+      if (/^[>|][-+]?$/.test(value)) {
+        const rest = fmText.slice(m.index + m[0].length).split('\n').slice(1);
+        const block = [];
+        for (const l of rest) { if (/^\s+\S/.test(l)) block.push(l.trim()); else break; }
+        value = block.join(' ');
+      }
+      value = value.replace(/^(["'])(.*)\1$/, '$2');
+      if (!value) findings.push({ path, n: 1, severity: 'block', id: 'description-missing', message: '`description:` is empty — at most 300 characters saying what this document settles and where its boundary sits' });
+      else if (value.length > 300 && !disabled.has('description-length')) findings.push({ path, n: 1, severity: 'block', id: 'description-length', message: `\`description:\` is ${value.length} characters — at most 300` });
+    }
+  }
   // The repo-root README is an orientation page with a budget (templates/root-readme.md): up to about 140 non-blank lines, plain Markdown, no chrome.
   if (scope === 'truth' && isRootReadme) {
     const raw = text.split('\n');

package/data/harnesses/delivery/skills/documentation/templates/acceptance-criteria.md

@@ -24,6 +24,7 @@ a claim to grade the built product against.
 ```markdown
 ---
 type: acceptance-criteria
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
 status: draft
 ---
 

package/data/harnesses/delivery/skills/documentation/templates/behavioral-checklist.md

@@ -7,6 +7,7 @@ Truth document. Use for: **how to verify one feature's promised behavior by driv
 ```yaml
 ---
 type: checklist                            # required tooling key — genre stamp
+description: "{at most 300 characters: what this document settles and where its boundary sits}" # required — the per-file account a folder is browsed by (references/frontmatter.md)
 verifies: [docs/features/auth.md]          # required — the doc(s) whose promises this proves
 ---
 ```

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

@@ -2,11 +2,16 @@
 
 Truth document. Use for: the entry point for all documentation in a repo. Created during baseline audit.
 
-**This file describes directories, never files.** Each section names one folder under `docs/` and says what the folder holds, who reads it and how its files are named — a description of the directory, not of its contents. No per-file rows, no file tree, no `├──` block: the tree is `structure.md`'s, as the authority on placement, and `ls` is the roster. A row per file forces an index edit on every file added, renamed or retired, and the index's own history then records roster churn instead of what the index said — a repo carried 103 commits on `docs/README.md` before this rule, most of them row edits. Each section below names a folder and says what the folder holds and how its files are named; the only files an index may name are the mandated scaffolds (`structure.md`, `operations/setup.md`, `history/CHANGELOG.md`, `history/backlog.md`) and the root `CLAUDE.md`. The repo-root `README.md` routes the team and agents in by intent; this file describes the folders of the docs tree — each links the other once and neither restates the other. `doc-lint` blocks a folder index that links an individual document (`index-lists-files`) or draws a tree (`index-file-tree`).
+**This file describes directories, never files.** Each section names one folder under `docs/` and says what the folder holds, who reads it and how its files are named — a description of the directory, not of its contents. No per-file rows, no file tree, no `├──` block: the tree is `structure.md`'s, as the authority on placement, and `ls` is the roster. A row per file forces an index edit on every file added, renamed or retired, and the index's own history then records roster churn instead of what the index said — a repo carried 103 commits on `docs/README.md` before this rule, most of them row edits. Each section below names a folder and says what the folder holds and how its files are named; the only files an index may name are the mandated scaffolds (`structure.md`, `operations/setup.md`, `history/CHANGELOG.md`, `history/backlog.md`) and the root `CLAUDE.md`. The repo-root `README.md` routes the team and agents in by intent; this file describes the folders of the docs tree — each links the other once and neither restates the other. Naming a file without a link is the same row: no filename, no record ID (`AD-010`), no per-record table. Each file's own `description:` frontmatter is its account, read with `grep -m1 '^description:' <folder>/*.md`. `doc-lint` blocks a folder index that links an individual document (`index-lists-files`), names one (`index-names-records`) or draws a tree (`index-file-tree`).
 
 **Link only what exists.** Every row below is a placeholder — drop any whose target the repo does not have. Most `history/` and `architecture/` folders are created on first use, so linking them unconditionally ships a docs index with dead links on day one. An index is a browse page: a link that resolves to nothing is worse than an absent row.
 
 ```
+---
+type: docs-readme
+description: "{at most 300 characters: what the documentation tree holds and how it is organised}"
+---
+
 # {Project Name} Documentation
 
 Technical documentation for {project description}. {Two or three sentences: what the product is, its planes or packages, who the docs are for.}

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

@@ -22,6 +22,7 @@ Nothing else: the neighbouring documents live in **For the agent**, the one clos
 ```yaml
 ---
 type: doctrine                                   # required tooling key
+description: "{at most 300 characters: what this document settles and where its boundary sits}" # required — the per-file account a folder is browsed by (references/frontmatter.md)
 status: active                                   # required — active | draft
 objects: [principal, credential, device grant]   # recommended — the concepts this doctrine governs, by their graph names
 ---

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

@@ -30,6 +30,7 @@ Nothing else. `doc-lint` blocks the retired mechanism sections (`mechanism-secti
 ```yaml
 ---
 type: feature                                    # required tooling key — preserve, never narrate
+description: "{at most 300 characters: what this document settles and where its boundary sits}" # required — the per-file account a folder is browsed by (references/frontmatter.md)
 status: active                                   # required — active | draft | deprecated
 objects: [device, credential grant]              # required — the product objects this document designs, by their graph names
 module: identity                                 # optional — one bounded-context label

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

@@ -9,6 +9,7 @@ Required: **Verdict**, **Decide today**, **Live-world ledger** (even when empty)
 ````markdown
 ---
 type: handover
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
 status: {open | accepted}
 date: {YYYY-MM-DD}
 as_of: {YYYY-MM-DDTHH:MM±TZ}

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

@@ -27,6 +27,7 @@ Nothing else. The feature template's lint rules apply. Forty to a hundred and tw
 ```yaml
 ---
 type: package
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
 status: active
 objects: [nustack cli, device credential]        # required — the objects this package designs or ships
 owns: ["packages/{name}/**"]                     # transitional — the residual region glob, read only by the ownership scan until it switches to header pointers

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

@@ -25,6 +25,7 @@ Required: **Goal**, **Stack**, **Prerequisites**, **Install**, **First run**, **
 ```markdown
 ---
 type: operations
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
 ---
 
 # Setup

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

@@ -26,6 +26,7 @@ Nothing else. The lint rules of the feature template apply. Sixty to a hundred a
 ```yaml
 ---
 type: system                                     # required tooling key
+description: "{at most 300 characters: what this document settles and where its boundary sits}" # required — the per-file account a folder is browsed by (references/frontmatter.md)
 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:                                            # transitional — region globs, one per subtree; read only by the ownership scan until it switches to header pointers (references/frontmatter.md)

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

@@ -64,6 +64,7 @@ Across the header pointers and the transitional globs:
 - **Retired keys:** `applies:` and `keywords:` are removed wherever found (remediation); a doctrine the removed `applies:` named stays named in the document's Scope section.
 - Flag **equal-specificity overlaps** — two feature docs whose transitional `owns:` globs claim the same paths at the same specificity (an ambiguous owner). `node .claude/hooks/check-ownership.mjs` reports these mechanically alongside dead globs (`overlaps()` in `lib/ownership.mjs`); a glob at strictly higher specificity carving out of a broader `**` is the designed layering and is never flagged. Surface a real overlap as a question — narrowing someone's glob is an author's call, not remediation.
 - **Stamp `type:` where missing.** Every doc carries a `type:` genre key (enum = the `documentation` skill's template names); docs predating the key are stamped mechanically — the genre is readable from placement and shape (a `docs/features/` doc is `type: feature`, an AD is `type: architecture-decision`). Stamping is remediation, not a question; an ambiguous genre is backlogged instead.
+- **Write `description:` where missing.** Every truth document and folder index carries a `description:` of at most 300 characters saying what it settles and where its boundary sits (`documentation` skill, `references/frontmatter.md` § `description:`). Each one is written from a read of the document, never from its filename — many documents ⇒ parallel sub-agents on the cheapest capable tier, one batch each. A folder index that names its files or records is rewritten to describe the folder, after confirming every per-file fact it carried lives in that file.
 
 **Then validate the doc→doc edge.** `node .claude/hooks/check-ownership.mjs` and the session-injected **doc edge index** carry `verifies:` and its generated inverse; read the edge index and check two things:
 

package/data/harnesses/etna/harness.json

@@ -1,7 +1,7 @@
 {
   "harness": "etna",
   "name": "etna",
-  "version": "1.5.29",
+  "version": "1.5.30",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
@@ -14,5 +14,5 @@
     "origin": "https://cdn.nustack.io",
     "track": "latest"
   },
-  "digest": "26630babb6e4"
+  "digest": "02bf4a5e9588"
 }

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

@@ -72,6 +72,7 @@ The two guarantees are complementary and both break on mixing: a reader holding
 - **Records are never edited to match the present.** A completed plan stays wrong-in-hindsight; a changelog entry describes close-time state; a scope change gets a *new* dated record that links back, never an edit to a frozen one.
 - **Two sanctioned bridges — head is truth, tail is provenance.** An **Architecture Decision (AD)** ends with a **Decision Changelog** (for a decision, the journey — what each revision reversed and what triggered it — is part of the reasoning), and the `maintenance` agent's **Health Log** lives in `docs/history/health-log.md`, an append-only record. The AD body stays current-truth-only; the tail carries the dates. No other truth document carries dated history. `docs/structure.md` is harness-owned — written whole by the installer, never edited by hand or by a skill; only its `harness-version` frontmatter is stamped, by the `maintenance` agent.
 - **Indexes describe directories, never files.** `docs/README.md` — the top-level index of the documentation folder — is a description of its directories: one entry per folder saying what the folder holds, who reads it and how its files are named. It carries no file list and no file tree: not a per-file row, not a `├──` tree of files, not a tree at all — `docs/structure.md` is the one place the tree lives, as the authority on placement. The same holds for a `README.md` / `Readme.md` at any level of `docs/`. `ls` is the roster, and the ownership index is how a document is found for a path. A per-file row has to be edited on every add, rename and retirement, so the index's history records roster churn instead of what the index said, and a reader cannot tell when the index itself changed. The only files an index may link are the mandated scaffolds (`structure.md`, `operations/setup.md`, `history/CHANGELOG.md`, `history/backlog.md`, `memory/main.md`) and a sibling folder's own `Readme.md`. `scripts/doc-lint.mjs` blocks the rest as `index-lists-files`, and blocks a tree drawn in a folder index as `index-file-tree`. An inverse (which checklists verify a feature, which docs a folder holds) is generated, never written.
+- **Every document describes itself.** Its frontmatter carries `description:` — at most 300 characters, one or two present-tense sentences saying what the document settles and where its boundary sits (`references/frontmatter.md` § `description:`). That is the per-file account an index would otherwise keep, so an index names no file and no record: not a link, not a filename, not an ID row such as `AD-010`. A folder is browsed with `grep -m1 '^description:' <folder>/*.md`. `doc-lint` blocks a truth document or folder index without one (`description-missing`), one over 300 characters (`description-length`), and an index row that names a file or record (`index-names-records`).
 - **Truth documents cite records for the _why_, never the _when_.** `Provenance: AD-002` is good; "decided in AD-002 and shipped 2026-06-13" is not. Routing/index docs point only to truth documents as a topic's authority — never a plan or changelog entry as the "read first" source. (An index _of the records themselves_ — a History section listing `plans/`, `changelog/` — is sanctioned.)
 
 **A document is intent and promises; facts are the graph's.** An owning document (feature, package, system) answers why the product is shaped this way and what it promises, and names the objects it designs in `objects:`. Every computable fact — a table's columns and vocabularies, a foreign key and its delete rule, which function writes which column, which route sits behind which guard, which code a refusal answers, which file holds what — is the code graph's to compute (`docs/architecture/systems/knowledge-layer.md`), and a hand-typed copy of it is the defect this rule removes: it reads as authoritative and is wrong the day the code moves. Mechanism stays in the code, reasons stay in the document, and the document points by object and symbol name, never by line number. `doc-lint` blocks the retired mechanism sections in an owning document (`mechanism-section`) and an owning document without `objects:`. `keywords:` is not a key: an object's name is its discovery term. **The body is scanned by people** — sharp bullets under noun-phrase headings, each a bold noun-phrase label, a colon, then one or two plain sentences; code named only where a person types or sees it, or at a cross-cutting seam the graph would not lead a reader to (a middleware, a gate, a hook, a shared store); every other pointer in the closing **For the agent** footer. The owning genres read Scope · Flows (Flow for a system, Usage for a package) · Decisions · Promises · Gaps · For the agent (`references/style-guide.md` § Labels, § Owning documents — the body and the footer; `doc-lint` warns `body-identifier`, `clause-label` and `second-person`).

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

@@ -15,24 +15,32 @@ A document names the product objects it designs. Every other edge between a docu
 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.
+6. **The description as the per-file account:** every document states what it is about in its own `description:`. A folder is browsed by reading its files' descriptions, so no index keeps a row per file.
 
 ## Keys by genre
 
 | 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 |
+| Feature | `type`, `description`, `status`, `objects`, `module` (optional) · transitional `owns` |
+| System | `type`, `description`, `status`, `objects` · transitional `owns` |
+| Package | `type`, `description`, `status`, `objects` · transitional `owns` |
+| Doctrine | `type`, `description`, `status`, `objects` |
+| UX | `type`, `description`, `status`, `objects` · transitional `owns` when it speaks for a surface's components |
+| Behavioral checklist | `type: checklist`, `description`, `verifies` |
+| Acceptance criteria | `type`, `description`, `status` |
+| Every other genre | `type`, `description`, plus its template's own keys |
 
 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.
 
 ## Keys
 
+### `description:`
+
+- **Values:** one plain string of at most 300 characters on one line: what the document settles and where its boundary sits, in one or two third-person, present-tense sentences. "How a person signs in to NuStack — the web, command-line and desktop doors, the session each mints, and what a refused sign-in shows; enterprise single sign-on is its own document." The description does not open with "This document"; it carries no file list, no date and no status.
+- **Required on:** every truth document and every folder index; a record carries it wherever its template has frontmatter (a changelog entry's one-line summary is its row in `CHANGELOG.md`). A frozen record that predates the key is never edited to add it. Exempt: `docs/structure.md`, which the installer writes whole, and a tree a generator owns (`docs/dna/`, the product-dna skill's).
+- **Reading:** it is how a folder is browsed without an index row per file: `grep -m1 '^description:' docs/features/*.md`. Tooling that lists documents shows it beside the path.
+- **Upkeep:** an edit that changes what a document settles updates its description in the same edit.
+
 ### `objects:`
 
 - **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.
@@ -81,4 +89,5 @@ An edit to a document that carries a retired key removes the key in the same edi
 - **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.
+- **Indexes name no files:** a folder index describes what its folder holds and how its files are named; the per-file account is each file's `description:`. A row per file, record or ID (`AD-010`) in an index is a defect.
+- **Baseline and reconcile:** the `maintenance` agent stamps `type:`, `description:` 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

@@ -37,7 +37,7 @@ Every genre takes the same shape (principle 2) and the same labels (principle 5)
 - **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.
+- **Indexes:** a folder's `Readme.md` describes directories, never files — no link, filename or record ID per file; each file's own `description:` frontmatter is its account. The root README follows `templates/root-readme.md`. Both take § Labels.
 
 ## Shape — the model first, the detail after
 

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

@@ -149,6 +149,37 @@ function lintFile(path, findings) {
     const tree = rawLines.find(({ line }) => /^\s*[│├└]/.test(line));
     if (tree) findings.push({ path, n: tree.n, severity: 'block', id: 'index-file-tree', message: 'a tree drawn in a folder index — describe each directory in a sentence; the tree is docs/structure.md\'s', excerpt: tree.line.trim().slice(0, 90) });
   }
+  // A file or record named without a link is the same per-file row as a link (SKILL.md § Every document describes itself).
+  // docs/dna/ is the product-dna skill's generated tree, laid out by that skill's own schema.
+  const isGeneratedTree = /(^|\/)docs\/dna\//.test(path);
+  if (scope === 'truth' && isFolderIndex && /(^|\/)docs\//.test(path) && !isGeneratedTree && !disabled.has('index-names-records')) {
+    const SCAFFOLD_NAME = /^(readme|structure|changelog|backlog|main|health-log|journal|claude|agents|setup)\.md$/i;
+    for (const { n, line } of lines) {
+      if (line.includes('doc-lint-disable: index-names-records')) continue;
+      const named = [...line.matchAll(/(?<![\w/{}-])([\w.-]+\.md)\b/g)].map((m) => m[1]).find((f) => !SCAFFOLD_NAME.test(f) && !/YYYY|NNN|[A-Z]\.[A-Z]/.test(f));
+      const recordRow = /^\|\s*\[?`?[A-Z]{2,}-\d+/.test(line.trim());
+      if (named || recordRow) findings.push({ path, n, severity: 'block', id: 'index-names-records', message: `index names an individual ${recordRow ? 'record' : `file (\`${named}\`)`} — describe the folder; each file's \`description:\` frontmatter is its account`, excerpt: line.trim().slice(0, 90) });
+    }
+  }
+  // Every truth document and folder index under docs/ describes itself in at most 300 characters (references/frontmatter.md § description:).
+  if (scope === 'truth' && /(^|\/)docs\//.test(path) && !isGeneratedTree && !isAuthorityMap && !disabled.has('description-missing')) {
+    const fmEnd = text.startsWith('---') ? text.indexOf('\n---', 3) : -1;
+    const fmText = fmEnd === -1 ? '' : text.slice(0, fmEnd);
+    const m = /^description:[ \t]*(.*)$/m.exec(fmText);
+    if (!m) findings.push({ path, n: 1, severity: 'block', id: 'description-missing', message: 'no `description:` in the frontmatter — at most 300 characters saying what this document settles and where its boundary sits' });
+    else {
+      let value = m[1].trim();
+      if (/^[>|][-+]?$/.test(value)) {
+        const rest = fmText.slice(m.index + m[0].length).split('\n').slice(1);
+        const block = [];
+        for (const l of rest) { if (/^\s+\S/.test(l)) block.push(l.trim()); else break; }
+        value = block.join(' ');
+      }
+      value = value.replace(/^(["'])(.*)\1$/, '$2');
+      if (!value) findings.push({ path, n: 1, severity: 'block', id: 'description-missing', message: '`description:` is empty — at most 300 characters saying what this document settles and where its boundary sits' });
+      else if (value.length > 300 && !disabled.has('description-length')) findings.push({ path, n: 1, severity: 'block', id: 'description-length', message: `\`description:\` is ${value.length} characters — at most 300` });
+    }
+  }
   // The repo-root README is an orientation page with a budget (templates/root-readme.md): up to about 140 non-blank lines, plain Markdown, no chrome.
   if (scope === 'truth' && isRootReadme) {
     const raw = text.split('\n');

package/data/harnesses/etna/skills/documentation/templates/acceptance-criteria.md

@@ -24,6 +24,7 @@ a claim to grade the built product against.
 ```markdown
 ---
 type: acceptance-criteria
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
 status: draft
 ---
 

package/data/harnesses/etna/skills/documentation/templates/behavioral-checklist.md

@@ -7,6 +7,7 @@ Truth document. Use for: **how to verify one feature's promised behavior by driv
 ```yaml
 ---
 type: checklist                            # required tooling key — genre stamp
+description: "{at most 300 characters: what this document settles and where its boundary sits}" # required — the per-file account a folder is browsed by (references/frontmatter.md)
 verifies: [docs/features/auth.md]          # required — the doc(s) whose promises this proves
 ---
 ```

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

@@ -2,11 +2,16 @@
 
 Truth document. Use for: the entry point for all documentation in a repo. Created during baseline audit.
 
-**This file describes directories, never files.** Each section names one folder under `docs/` and says what the folder holds, who reads it and how its files are named — a description of the directory, not of its contents. No per-file rows, no file tree, no `├──` block: the tree is `structure.md`'s, as the authority on placement, and `ls` is the roster. A row per file forces an index edit on every file added, renamed or retired, and the index's own history then records roster churn instead of what the index said — a repo carried 103 commits on `docs/README.md` before this rule, most of them row edits. Each section below names a folder and says what the folder holds and how its files are named; the only files an index may name are the mandated scaffolds (`structure.md`, `operations/setup.md`, `history/CHANGELOG.md`, `history/backlog.md`) and the root `CLAUDE.md`. The repo-root `README.md` routes the team and agents in by intent; this file describes the folders of the docs tree — each links the other once and neither restates the other. `doc-lint` blocks a folder index that links an individual document (`index-lists-files`) or draws a tree (`index-file-tree`).
+**This file describes directories, never files.** Each section names one folder under `docs/` and says what the folder holds, who reads it and how its files are named — a description of the directory, not of its contents. No per-file rows, no file tree, no `├──` block: the tree is `structure.md`'s, as the authority on placement, and `ls` is the roster. A row per file forces an index edit on every file added, renamed or retired, and the index's own history then records roster churn instead of what the index said — a repo carried 103 commits on `docs/README.md` before this rule, most of them row edits. Each section below names a folder and says what the folder holds and how its files are named; the only files an index may name are the mandated scaffolds (`structure.md`, `operations/setup.md`, `history/CHANGELOG.md`, `history/backlog.md`) and the root `CLAUDE.md`. The repo-root `README.md` routes the team and agents in by intent; this file describes the folders of the docs tree — each links the other once and neither restates the other. Naming a file without a link is the same row: no filename, no record ID (`AD-010`), no per-record table. Each file's own `description:` frontmatter is its account, read with `grep -m1 '^description:' <folder>/*.md`. `doc-lint` blocks a folder index that links an individual document (`index-lists-files`), names one (`index-names-records`) or draws a tree (`index-file-tree`).
 
 **Link only what exists.** Every row below is a placeholder — drop any whose target the repo does not have. Most `history/` and `architecture/` folders are created on first use, so linking them unconditionally ships a docs index with dead links on day one. An index is a browse page: a link that resolves to nothing is worse than an absent row.
 
 ```
+---
+type: docs-readme
+description: "{at most 300 characters: what the documentation tree holds and how it is organised}"
+---
+
 # {Project Name} Documentation
 
 Technical documentation for {project description}. {Two or three sentences: what the product is, its planes or packages, who the docs are for.}

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

@@ -22,6 +22,7 @@ Nothing else: the neighbouring documents live in **For the agent**, the one clos
 ```yaml
 ---
 type: doctrine                                   # required tooling key
+description: "{at most 300 characters: what this document settles and where its boundary sits}" # required — the per-file account a folder is browsed by (references/frontmatter.md)
 status: active                                   # required — active | draft
 objects: [principal, credential, device grant]   # recommended — the concepts this doctrine governs, by their graph names
 ---

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

@@ -30,6 +30,7 @@ Nothing else. `doc-lint` blocks the retired mechanism sections (`mechanism-secti
 ```yaml
 ---
 type: feature                                    # required tooling key — preserve, never narrate
+description: "{at most 300 characters: what this document settles and where its boundary sits}" # required — the per-file account a folder is browsed by (references/frontmatter.md)
 status: active                                   # required — active | draft | deprecated
 objects: [device, credential grant]              # required — the product objects this document designs, by their graph names
 module: identity                                 # optional — one bounded-context label

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

@@ -9,6 +9,7 @@ Required: **Verdict**, **Decide today**, **Live-world ledger** (even when empty)
 ````markdown
 ---
 type: handover
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
 status: {open | accepted}
 date: {YYYY-MM-DD}
 as_of: {YYYY-MM-DDTHH:MM±TZ}

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

@@ -27,6 +27,7 @@ Nothing else. The feature template's lint rules apply. Forty to a hundred and tw
 ```yaml
 ---
 type: package
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
 status: active
 objects: [nustack cli, device credential]        # required — the objects this package designs or ships
 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/setup.md

@@ -25,6 +25,7 @@ Required: **Goal**, **Stack**, **Prerequisites**, **Install**, **First run**, **
 ```markdown
 ---
 type: operations
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
 ---
 
 # Setup

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

@@ -26,6 +26,7 @@ Nothing else. The lint rules of the feature template apply. Sixty to a hundred a
 ```yaml
 ---
 type: system                                     # required tooling key
+description: "{at most 300 characters: what this document settles and where its boundary sits}" # required — the per-file account a folder is browsed by (references/frontmatter.md)
 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:                                            # transitional — region globs, one per subtree; read only by the ownership scan until it switches to header pointers (references/frontmatter.md)

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.30",
+  "version": "0.20.32",
   "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": "687486a21483"
+  "etnaFingerprint": "1b90a96b3812"
 }