@nurix/etna 0.20.24 → 0.20.26

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

@@ -271,6 +271,67 @@ Two verbosity regimes, split by who pays for the words. **Instruction files** (`
 - **Inline links are the minimum that action requires.** Link mid-prose only where the reader must go there to act on this page. Every other sister document — everything the topic touches — belongs in one **Related** (or **References**) section at the document's end.
 - **The Related tail is the document's entire link surface.** Deep relative paths (`../../../../…`) are fragile — a folder move breaks every one — so they are confined to that one block, where a path change touches one place; body mentions use the plain name (`the boundary skill`, `structure.md`) instead of a link.
 
+## Shape — the model first, the detail after
+
+Every truth document a person reads to understand something — doctrine, system, package, feature — is written **from the outside in**. It opens on the model and adds detail in layers, so a reader who stops at any layer holds a picture that is coarse but true, never a teaser that only the next section makes sense of. The failure this prevents is a document written at one density from its first word: an inventory table before the reader knows what is being inventoried, and the principles that summarize it arriving last, where nobody reads them.
+
+**The layers, in order:**
+
+1. **The question and its boundary.** The first paragraph says what question this document answers, and which neighbouring documents answer the questions next to it. No addresses, file paths or configuration in it.
+2. **The model.** What the thing is in a page: the parties or parts, the one or two axes that organize them, and the invariants that hold everywhere — numbered, each with its reason, so later sections can cite them ("principle 3").
+3. **The parts.** One table or diagram that places every part in the model, then how the parts relate: what they share, where they meet, and what keeps them apart.
+4. **Each part in turn.** For each part, the decisions it rests on and why. Each section opens with why the part exists, not with how it is built.
+5. **The genre's deepest layer**, from the table below, and nothing deeper.
+
+**The stability test decides what a sentence may say.** Ask whether the sentence would have to change if a function were renamed, a file moved, a route, column, cookie attribute or error code changed, or a constant was retuned without the design changing. If it would, it fails. The fact belongs to the code, and the code graph computes it on demand (`docs/architecture/systems/knowledge-layer.md`). A copy typed here is at best a duplicate of the code and at worst a stale one, which misleads the next agent more than no document would. It also has to be found and re-edited on every change to the code beneath it.
+
+These survive the test:
+
+- **Reasons.** Why the design is this way, and what would break otherwise.
+- **Invariants.** What must hold everywhere.
+- **Decisions and the alternatives a reader would reach for.**
+- **Promises a person or a test can check.**
+- **Contracts that span components no single file shows.** For example, two clients that must classify the same answer identically.
+- **Decided-but-unbuilt intent.** The code cannot reveal what it does not yet do.
+
+**The code is the authority on *what*; the document is the authority on *why*.** A document that disagrees with the code about what happens is simply stale, and the code wins. A disagreement about why, or about an invariant, is a defect to raise with the owner, because one of the two is wrong on purpose. State this in the opening of any document whose readers include agents.
+
+**Each genre has its own deepest layer.** The shape above is common to every genre; how far down a genre may go differs:
+
+| Genre | Deepest layer | Stops before |
+| --- | --- | --- |
+| Doctrine (`architecture/common/`) | The decisions behind each part, and the reasons for them | Any mechanism. A doctrine document describes no code |
+| System (`architecture/systems/`) | How the machine behaves across packages: sequence and state diagrams, the invariants at each place where parts meet, what re-drives a stall. No single file shows a cross-package flow, so this layer earns its place | Per-function steps; tables and columns; routes |
+| Package (`architecture/packages/`) | The public contract a consumer touches: commands and their flags, exports, what is installed and where. For a CLI the flags *are* the promise | Internal layout; the build's steps; which file holds what |
+| Feature (`features/`) | The behaviour a person meets, in full: each state the surface can be in, each edge case, what a refusal tells them, wording where the wording is promised. **This genre runs deepest toward its end**, because a promise is checked by a person or a test, not computed from code | Columns, routes, guards, functions, files |
+| Reference (API reference, environment registry) | The contract itself: signatures, shapes, variables | Nothing. The detail is the point |
+| Operations procedure, runbook | The exact commands, in order | Nothing. The detail is the point |
+
+**A diagram belongs to a layer.** At the model and parts layers it names roles ("the browser", "the auth service"), never a URL, a header or a file. A diagram drawn from the code's names belongs to the code graph.
+
+**Length is a signal, not a target.** A document whose reference tail is longer than its body is an inventory with an introduction. A doctrine document past about three hundred lines has usually let mechanism in.
+
+## Documents are read by people; the footer is for the agent
+
+A document that explains something — a doctrine, an owning document (feature, package, system) — is prose a person reads top to bottom. It takes the shape above (§ Shape — the model first, the detail after). The rules:
+
+- **The body is plain English.** It says what the thing is, why it is shaped that way, how a person meets it, and what it promises. Bullets and tables are for enumerable facts only — never for an argument, a decision or a promise. No sentence shape repeats down a list; a section whose entries share one shape is rewritten as paragraphs.
+- **Name code only where the graph would not lead a reader there.** The code graph answers what a feature's own files call, so those names add nothing. What it cannot answer from the feature's files is the seam that runs the other way: a middleware, a gate, a hook, a scheduler tick, a shared store holding part of the feature's logic because that logic is global. Write that reference by name, once, where the narrative leaves the feature. Everything else is a plain name — "the device registry", "the sign-off page", "the mirror".
+- **A term of art is introduced in plain words the first time it appears.**
+- **Bold marks a defined term's first appearance at most** — never a noun mid-sentence. An em-dash is a budget, one per paragraph, not a joint between clauses.
+- **A gap the code does not close is one Known gaps paragraph, or a backlog row.** Never a ledger row inside the body, never a temporal hedge.
+- **The first line under the title is the goal.** No plan link, no routing line above it.
+- **The footer, "For the agent", is a set of pointers, not an inventory.** It holds four things:
+  1. The objects, with a one-line definition each.
+  2. The code roots, as directories, where the graph should start.
+  3. The cross-cutting seams, by name.
+  4. The checklist, and the neighbouring documents with a purpose for each.
+
+  A feature adds its pages, because an address is what a person points at. A package adds its commands, because those are its public contract. Tables, routes, symbol rosters and file lists do not belong in the footer any more than in the body. The footer obeys the stability test (§ Shape) like every other line, and a footer that grows with every function is the inventory moved down the page.
+- **"How it works" is narrative, not mechanism.** It says that a forgotten machine comes back on its next call, not which function re-mints the row. Behaviour in plain words is intent made legible; columns, routes, guards and signatures are the graph's.
+
+The Mechanics rules below ("inline-code every identifier", "bold assertion — explanation") bind instruction files and operations procedures, not doctrine or the owning genres.
+
 ---
 
 ## The Two Natures — Tense & History
@@ -334,38 +395,19 @@ Worked example of the strip-and-relocate move: [`examples.md`](examples.md) Exam
 
 ### Standard Layout
 
+An owning document (feature, system, package) takes its shape from its template — Goal · Why it exists · How it works · What was decided · What it promises · Known gaps · For the agent — and a doctrine document from `templates/doctrine.md` — the question · The model · The parts · one section per part · For the agent. Neither is ever a code tour: no Architecture, Key Functions, State or Files section (§ Shape — the model first, the detail after; § Documents are read by people). The layout below is for a **reference document** that is not an owning genre — an API reference, an environment registry, a procedure's appendix — where a signature or a file list is the content itself:
+
 ```markdown
 # [Title]
 
 **Goal:** One-line purpose
 
-## Architecture
-
-[Diagram + explanation]
-
-## Key Functions
-
-[Signatures and contracts]
-
-## State
+## [Contract or procedure sections]
 
-[Persistence shapes]
-
-## Files
-
-[Source file list]
+[Signatures, shapes, steps — the content the reader came for]
 ```
 
-### File References
-
-Always end with:
-
-```markdown
-## Files
-
-- `src/path/main.js` - Core logic
-- `src/path/hooks.js` - React hooks
-```
+A file roster belongs in no document: the ownership index and the code graph answer "which file" for every genre.
 
 ---
 
@@ -373,12 +415,13 @@ Always end with:
 
 | Aspect     | Rule                            |
 | ---------- | ------------------------------- |
-| Functions  | Always include signatures       |
+| Functions  | Signatures in reference docs only — an owning document names a symbol in its footer |
 | Parameters | Type + purpose                  |
 | Returns    | Type + shape                    |
 | State      | Persistence points only         |
 | Diagrams   | ASCII for structure at rest, mermaid for behaviour over time — docs only, never instruction files |
 | Code       | Under 15 lines, contracts only  |
 | Voice      | Imperative/active               |
-| Mechanics  | Inline-code identifiers; bold-assertion bullets |
-| Length     | Concise, one line when possible |
+| Mechanics  | Instruction files and procedures: inline-code identifiers, bold-assertion bullets. Doctrine and owning documents: plain prose, pointers in the footer |
+| Shape      | The model first, the detail after; every sentence passes the stability test; each genre stops at its deepest layer (§ Shape) |
+| Length     | Concise; a paragraph is one line — never hard-wrap prose (`.prettierrc.json` keeps `proseWrap: never`) |

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

@@ -25,7 +25,8 @@ When a draft wants to be both — the current state *and* the story of getting t
 - **Headings are retrieval keys.** Sections get pulled out of context by search and agents; qualify generic headings with the topic (`## Merge rules — data sync`, not `## Rules`) so each stands alone.
 - **Tables for enumerable facts, prose for judgment.** One row per item; anything needing a *because* lives in prose around the table, never inside a cell.
 - **Every section earns its place.** No empty stubs — omit what has nothing real to say; write an explicit "None" only where the absence itself is information.
-- **Cite sources and link neighbours.** If the document mentions a concept another document owns, link it; if it draws on code, name the files.
+- **Build from the outside in.** The question and its boundary, then the model, then the parts, then the detail — and nothing that fails the stability test (`references/style-guide.md` § Shape — the model first, the detail after). An explanation of a concern the whole platform handles is not untemplated: it is `templates/doctrine.md`.
+- **Cite sources and link neighbours.** If the document mentions a concept another document owns, link it; if it draws on code, name the directory it lives in — the code graph finds the files, and a file list goes stale.
 
 ## 4. Write it in the house style
 

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

@@ -119,11 +119,97 @@ function lintFile(path, findings) {
 
   // A folder index (Readme.md/README.md) is a browse page, not a feature doc — it owns no code.
   const isFolderIndex = /(^|\/)(readme)\.md$/i.test(path);
+
+  // An index names folders, never files (SKILL.md § The Two Natures). A link from a folder index or
+  // the authority map to an individual document is a row that must be edited on every add, rename
+  // and retirement; the only files an index may link are the mandated scaffolds and a sibling
+  // folder's own Readme.
+  const isAuthorityMap = /(^|\/)docs\/structure\.md$/.test(path);
+  const isRootReadme = /^(\.\/)?README\.md$/i.test(path.replace(process.cwd() + '/', ''));
+  if (scope === 'truth' && (isFolderIndex || isAuthorityMap) && !disabled.has('index-lists-files')) {
+    const SCAFFOLD = /(^|\/)(readme|structure|changelog|backlog|main|health-log|journal|claude|agents)\.md$|(^|\/)operations\/setup\.md$/i;
+    for (const { n, line } of lines) {
+      if (line.includes('doc-lint-disable: index-lists-files')) continue;
+      for (const m of line.matchAll(/\]\(([^)\s#]+\.md)(#[^)]*)?\)/g)) {
+        const target = m[1];
+        if (/^[a-z]+:\/\//.test(target) || SCAFFOLD.test(target)) continue;
+        // The repo-root README routes by intent (templates/root-readme.md): its Map names owning package and system
+        // docs, its Where-to-go rows name procedures and rules. Individual feature docs stay off it — the ownership index finds them.
+        if (isRootReadme && /(^|\/)docs\/(architecture\/(packages|systems|common)\/|operations\/)[^/]+\.md$|(^|\/)\.claude\/rules\/[^/]+\.md$/.test(target)) continue;
+        if (isRootReadme && /(^|\/)docs\/features\/[^/]+\.md$/.test(target)) { findings.push({ path, n, severity: 'warn', id: 'root-readme-feature-link', message: `root README links an individual feature doc (\`${target}\`) — point at docs/features/ and let the ownership index find it`, excerpt: line.trim().slice(0, 90) }); continue; }
+        findings.push({ path, n, severity: 'block', id: 'index-lists-files', message: `index links an individual document (\`${target}\`) — name the folder and how its files are named; \`ls\` is the roster`, excerpt: line.trim().slice(0, 90) });
+      }
+    }
+  }
+  // A folder index describes directories; a drawn tree is a file roster in another costume
+  // (SKILL.md § Indexes describe directories, never files). structure.md is the authority map and keeps its tree.
+  if (scope === 'truth' && isFolderIndex && (isRootReadme || /(^|\/)docs\//.test(path)) && !disabled.has('index-file-tree')) {
+    // Raw lines, not proseLines: a tree is drawn inside a code fence, which proseLines drops. The repo-root README routes by a Map table; its tree is docs/structure.md's too (templates/root-readme.md).
+    const rawLines = text.split('\n').map((line, i) => ({ n: i + 1, line }));
+    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) });
+  }
+  // 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');
+    const nonBlank = raw.filter((l) => l.trim()).length;
+    if (!disabled.has('root-readme-budget') && nonBlank > 140) findings.push({ path, n: 1, severity: 'warn', id: 'root-readme-budget', message: `${nonBlank} non-blank lines — the root README orients and routes; a section that needs a paragraph needs a doc (templates/root-readme.md)` });
+    const chrome = raw.findIndex((l) => /shields\.io|<img\b|<div\b|<p align|^!\[/.test(l));
+    if (!disabled.has('root-readme-chrome') && chrome !== -1) findings.push({ path, n: chrome + 1, severity: 'block', id: 'root-readme-chrome', message: 'badge, image or HTML layout in the root README — agents cannot read it and the team does not need it', excerpt: raw[chrome].trim().slice(0, 90) });
+  }
   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:', 'keywords:', 'status:', 'type:'])
+    for (const key of ['owns:', 'status:', 'type:'])
       if (!fm.includes(key)) findings.push({ path, n: 1, severity: 'block', id: 'feature-frontmatter', message: `feature doc missing \`${key}\` frontmatter` });
   }
+
+  // An owning document (feature, package, system) is intent and promises; the sections that narrate
+  // mechanism — a file roster, a walk through the code, a schema or route table — are the graph's
+  // to compute and are retired from the genre (SKILL.md § A document is intent and promises).
+  const isOwningDoc = scope === 'truth' && !isFolderIndex && /(^|\/)docs\/(features|architecture\/(packages|systems))\/[^/]+\.md$/.test(path);
+  if (isOwningDoc && !disabled.has('mechanism-section')) {
+    const RETIRED = /^#{2,4}\s+(Files|Current Behavior|Key Functions|Data|API|Refusals?|Architecture|State|Redux|Affected Modules|Conventions to Follow|Ownership Conflicts|Tests|The shape|Layout|Build and test|Commands|Routes|Schema|Wire)\b/i;
+    for (const { n, line } of lines) {
+      if (!RETIRED.test(line) || line.includes('doc-lint-disable: mechanism-section')) continue;
+      findings.push({ path, n, severity: 'block', id: 'mechanism-section', message: 'mechanism section in an owning document — columns, routes, guards, functions and files are the graph\'s to compute; keep the decision or the promise, point by name, cut the rest', excerpt: line.trim().slice(0, 90) });
+    }
+    const fm = text.startsWith('---') ? text.slice(0, text.indexOf('\n---', 3)) : '';
+    if (!/^objects:/m.test(fm)) findings.push({ path, n: 1, severity: 'block', id: 'objects-missing', message: 'owning document names no `objects:` — the product objects it designs are its edge into the graph and its discovery terms' });
+  }
+
+  // The body of an owning document is read by people; its "For the agent" footer is the reference
+  // surface (style-guide § Documents are read by people). These three warn, never block: a seam
+  // reference is allowed in the body, and the judgment of which identifier is a seam is the author's.
+  if (isOwningDoc) {
+    const OLD_SHAPE = /^##\s+(Background|Decisions|Promises|Objects|Related)\s*$/;
+    const footerAt = lines.findIndex(({ line }) => /^##\s+For the agent\b/.test(line));
+    const body = footerAt === -1 ? lines : lines.slice(0, footerAt);
+    let section = null; // proseLines already dropped the frontmatter and the fences
+    const sections = [];
+    for (const { n, line } of body) {
+      if (/^##\s+/.test(line)) {
+        if (!disabled.has('old-shape-section') && OLD_SHAPE.test(line)) findings.push({ path, n, severity: 'warn', id: 'old-shape-section', message: 'second-shape heading — the owning genres now read Why it exists · How it works · What was decided · What it promises · Known gaps · For the agent', excerpt: line.trim() });
+        section = { n, title: line.replace(/^##\s+/, '').trim(), bullets: 0, lines: 0, ids: 0, boldRun: 0, maxRun: 0 };
+        sections.push(section);
+        continue;
+      }
+      if (!section || !line.trim()) { if (section) section.boldRun = 0; continue; }
+      section.lines++;
+      const isBullet = /^\s*[-*]\s+/.test(line);
+      if (isBullet) section.bullets++;
+      if (/^\s*[-*]\s+\*\*/.test(line)) { section.boldRun++; section.maxRun = Math.max(section.maxRun, section.boldRun); } else section.boldRun = 0;
+      for (const m of line.matchAll(/`([^`]+)`/g)) {
+        const t = m[1];
+        if (/[\/]|\.(ts|tsx|mjs|js|md|json|sql)$|_|\(|^[a-z]+[A-Z]|^[A-Z][a-z]+[A-Z]|^(GET|POST|PUT|PATCH|DELETE) /.test(t)) section.ids++;
+      }
+    }
+    for (const s of sections) {
+      if (/^(Ownership|Known gaps)$/.test(s.title)) continue;
+      if (!disabled.has('body-identifier') && s.ids > 3) findings.push({ path, n: s.n, severity: 'warn', id: 'body-identifier', message: `${s.ids} code identifiers in a body section — the body names code only at a cross-cutting seam (a middleware, gate, hook, store); the rest is plain names in prose, with identifiers in "For the agent"`, excerpt: s.title });
+      if (!disabled.has('list-not-prose') && s.bullets >= 4 && s.bullets / s.lines > 0.6) findings.push({ path, n: s.n, severity: 'warn', id: 'list-not-prose', message: 'a body section that is a list — a decision, a promise or an explanation is prose; a list is for genuinely parallel one-liners', excerpt: s.title });
+      if (!disabled.has('formula-run') && s.maxRun >= 3) findings.push({ path, n: s.n, severity: 'warn', id: 'formula-run', message: 'three or more bold-led bullets in a row — the "**X** — over Y, because Z" formula reads as a ledger; write the decisions as themed paragraphs', excerpt: s.title });
+    }
+  }
 }
 
 // A changed plan whose committed version is already frozen must not be edited.

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

@@ -6,6 +6,7 @@ One file per template. Every template is either a **truth document** (states cur
 | --- | --- | --- |
 | Feature (LLD) | [feature.md](feature.md) | Truth |
 | Package (one workspace package) | [package.md](package.md) | Truth |
+| Doctrine (one concern the platform handles everywhere) | [doctrine.md](doctrine.md) | Truth |
 | System (one machine spanning packages) | [system.md](system.md) | Truth |
 | Architecture Decision (AD) | [architecture-decision.md](architecture-decision.md) | Truth (Decision Changelog tail sanctioned) |
 | System overview | [system-overview.md](system-overview.md) | Truth |
@@ -18,13 +19,13 @@ One file per template. Every template is either a **truth document** (states cur
 | Testing strategy | [testing-strategy.md](testing-strategy.md) | Truth |
 | Behavioral checklist | [behavioral-checklist.md](behavioral-checklist.md) | Truth |
 | UX behavior | [ux-behavior.md](ux-behavior.md) | Truth |
+| Setup (first run, one per repo) | [setup.md](setup.md) | Truth |
 | Operations procedure | [operations-procedure.md](operations-procedure.md) | Truth |
 | Implementation map | [implementation-map.md](implementation-map.md) | Truth |
 | Bookkeeping ledger | [bookkeeping.md](bookkeeping.md) | Truth (work queue) |
 | Protected files | [protected-files.md](protected-files.md) | Truth |
-| Project root README | [root-readme.md](root-readme.md) | Truth |
+| Project root README (outward opening, then orientation and routing) | [root-readme.md](root-readme.md) | Truth |
 | docs/README.md (doc index) | [docs-readme.md](docs-readme.md) | Truth |
-| docs/structure.md (authority map) | [structure.md](structure.md) | Truth (Health Log tail sanctioned) |
 | Plan | [plan.md](plan.md) | Record |
 | Changelog entry | [changelog-entry.md](changelog-entry.md) | Record |
 | Migration runbook | [migration-runbook.md](migration-runbook.md) | Record |
@@ -35,6 +36,6 @@ One file per template. Every template is either a **truth document** (states cur
 
 **The `type:` enum lives here.** A doc's `type:` frontmatter takes its value from this table — one genre per template (`feature`, `architecture-decision`, `non-goals`, …). External generators consume this list rather than defining their own; a type this table does not name defaults to `docs/architecture/` placement and is never added to the protected-files list.
 
-**Baseline scaffolds** — files that must exist after every baseline; the `maintenance` agent (baseline mode) creates any that are missing: [docs-readme.md](docs-readme.md), [structure.md](structure.md), [changelog-index.md](changelog-index.md), [backlog.md](backlog.md), [memory-main.md](memory-main.md), and [root-readme.md](root-readme.md) (never overwriting an existing root README).
+**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.

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

@@ -21,4 +21,4 @@ The shared work queue keeping documentation and code in sync — a queue, never
 
 **A waiver covers a finding only when it names the finding's kind and its subject in backticks** — the matcher (`waiverCovers`) tests the backticked subject exactly, so a waiver written without them silences nothing and the wall stands. A `waived:` row's `expires=` date is enforced: CI honors the waiver until the date, then fails. `dead-glob` waivers double as the dead-glob allowlist; `ownership-overlap` waivers cover the CI ownership check the same way.
 
-Finding kinds for `auto:`: `dead-glob` · `doc-implicated` · `doc-lint` · `header-missing` · `index-row-missing` · `package-rejected` · `frozen-record-edited` · `source-lint`. The CI ownership check additionally accepts `waived:` rows of kind `ownership-overlap`.
+Finding kinds for `auto:`: `dead-glob` · `doc-implicated` · `doc-lint` · `header-missing` · `package-rejected` · `frozen-record-edited` · `source-lint`. The CI ownership check additionally accepts `waived:` rows of kind `ownership-overlap`.

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

@@ -2,67 +2,46 @@
 
 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`).
+
 **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.
 
 ```
 # {Project Name} Documentation
 
-Technical documentation for {project description}.
+Technical documentation for {project description}. {Two or three sentences: what the product is, its planes or packages, who the docs are for.}
 
 > For documentation organization, authority map, and folder rules, see **[structure.md](structure.md)**.
 
 ---
 
-## Quick Links
-
-| Document                          | Description                          |
-| --------------------------------- | ------------------------------------ |
-| [Structure](structure.md)         | Documentation entry point and rules  |
-| [Setup](operations/setup.md)      | Installation and configuration guide |
-
----
-
 ## Architecture
 
-System design, steering docs, and standing decisions — the truth layer.
-
-- [system-design.md](architecture/system-design.md) - System overview: subsystems and key flows
-- [domain-model.md](architecture/domain-model.md) - Entities, relationships, state ownership
-- [glossary.md](architecture/glossary.md) - Project vocabulary
-- [non-goals.md](architecture/non-goals.md) - What this system deliberately does not do
-- [decisions/](architecture/decisions/Readme.md) - Architecture Decisions (ADs)
-{list other architecture docs — api.md, security.md — when present}
-
----
+The design layer — [architecture/](architecture/): {what the folder holds — the system overview, steering docs, cross-cutting doctrine, the per-package and per-system documents, and `decisions/` (one Architecture Decision per subject, `AD-NNN-{slug}.md`, status in each file's frontmatter)}.
 
 ## Features
 
-Living reference docs for implemented features (how things currently work).
+[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.
 
-- [feature-name.md](features/feature-name.md) - Feature description
-{list all feature docs}
+## Tests
 
----
+[tests/](tests/) — one behavioral checklist per documented surface, `{feature}.md`, `verifies:` naming the document whose promises it proves.
 
 ## Operations
 
-How to run, develop, and deploy.
+[operations/](operations/) — how to set up, run, develop, deploy and recover. Start at [`setup.md`](operations/setup.md) on a new machine; every other procedure is named for its task.
+
+## History
 
-- [setup.md](operations/setup.md) - Installation and configuration guide
-{list all operations docs — environment.md when present}
+[history/](history/) — the records: `plans/` (one dated plan per unit of work, frozen at completion), `changelog/` (one entry per unit of work, indexed by [CHANGELOG.md](history/CHANGELOG.md)), `migrations/` (one-shot runbooks), `brainstorms/`, `research/`, and [backlog.md](history/backlog.md).
 
----
+## Research and memory
 
-## History
+[research/](research/) — in-progress brainstorm sessions and standing research. [memory/](memory/) — project memory, one file per agent.
 
-The records — everything dated, frozen, or append-only.
+## Notes for this repository
 
-- [CHANGELOG.md](history/CHANGELOG.md) - Master changelog index
-- [changelog/](history/changelog/) - Individual changelog entries
-- [plans/](history/plans/) - Implementation plans (frozen at completion)
-- [migrations/](history/migrations/) - One-shot migration runbooks (frozen once executed)
-- [research/](history/research/) - Deep-research artifacts (one folder per topic)
-- [backlog.md](history/backlog.md) - Tracked work items and technical debt
+{The one place project-specific placement facts live, because `structure.md` is the harness's and is overwritten on every refresh: legacy folders kept as frozen provenance, a retired genre whose residue is still on disk, a local exception to a folder rule. One bullet each; delete the section when there are none.}
 
 ---
 

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

@@ -0,0 +1,82 @@
+# 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:`.
+
+**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.
+
+**Required:**
+
+- the frontmatter
+- the opening (the question, the boundary, and the authority sentence)
+- **The model**, ending in numbered principles, each with its reason
+- **The parts**: one table or diagram placing every part in the model, then how the parts relate
+- **one section per part**
+- **For the agent**
+
+**Optional:**
+
+- an `UNBUILT` block for decided-but-unbuilt intent
+- **Related**
+
+Nothing else. Expect one hundred and fifty to three hundred lines; past that, mechanism has usually crept in.
+
+```yaml
+---
+type: doctrine                                   # required tooling key
+status: active                                   # required — active | draft
+objects: [principal, credential, device grant]   # recommended — the concepts this doctrine governs, by their graph names
+---
+```
+
+```
+# {Concern}
+
+{The question this concern answers for every request, row or run, in one sentence, bolded — then what it does not answer and which document does. One paragraph.}
+
+{The authority sentence: this document states the design, not the code; for what does what, read the code roots in the footer or ask the code graph; where this document and the code disagree on *what*, the code is right; on *why* or a principle, the disagreement is a defect to raise.}
+
+## The model
+
+### {What the platform owns here, and what it delegates}
+
+{The one framing fact a reader needs before anything else — e.g. "NuStack checks identity; it does not own it". Plain words, no addresses.}
+
+### {The parties or parts}
+
+{Who or what participates, in a short list of one-liners — each named in plain words first, its term of art in parentheses.}
+
+### {The axis that organizes them}
+
+{The one or two dimensions every part is placed on — e.g. "who issued the proof decides how it is checked". A small table is right here.}
+
+### The principles
+
+{Numbered invariants that hold across every part. Each one sentence of rule plus its reason. Later sections cite them by number.}
+
+## {The parts} — e.g. "The credential families"
+
+{One table: each part placed on the model's axes. Then "How the parts relate": what they share, where they meet, what keeps them apart, and the order in which they are tried — each as a bold-led paragraph with its reason. A role-level diagram (mermaid) where the relationships are a flow.}
+
+## {Each part, one section per part} — e.g. "How each family works"
+
+### {A part, named for who meets it} — e.g. "A person in a browser"
+
+{Why the part exists, then the decisions it rests on, each with its reason, citing principles by number. A sequence diagram at role level where the part is a flow. Detail that a person or test can check is welcome; detail that only restates the code is not.}
+
+## For the agent
+
+{Pointers, not an inventory: the objects with one line each; the code roots as directories; any cross-cutting seam by name; the neighbouring doctrine with a purpose each.}
+```
+
+### Marking what is decided and unbuilt
+
+Code cannot reveal what it does not yet do, so decided-but-unbuilt intent is one of the few places a doctrine document records something the code does not. Wrap it in `<!-- UNBUILT:START — {what, and the evidence it is not built} -->` … `<!-- UNBUILT:END -->`, in plain words. A design decided *against* carries no marker.
+
+### What a doctrine document is not
+
+| It is not | That is |
+| --- | --- |
+| 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 story of how the concern got this way | A decision record (`decisions/`) for the why, and the changelog for the when |