@nurix/etna 0.20.25 → 0.20.27

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

@@ -22,14 +22,16 @@ When a draft wants to be both — the current state *and* the story of getting t
 ## 3. Shape it
 
 - **Open with the goal.** The first line under the H1 states what the document is for and who reads it — a reader (or agent) landing here cold decides in one sentence whether to keep reading.
+- **Headings are noun phrases** — no verb, no tense, no person (`references/style-guide.md` § Labels).
 - **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
 
-`references/style-guide.md` carries the rules: present tense with no history narration, progress markers, or stale-reference tripwires (§ The Two Natures); imperative/active voice; code examples under 15 lines showing contracts, not implementations; ASCII diagrams in docs only; inline-code every identifier, filename, command, and config key.
+`references/style-guide.md` carries the rules: present tense with no history narration, progress markers, or stale-reference tripwires (§ The Two Natures); third-person, present-tense, active sentences after noun-phrase labels (§ Voice, § Labels); diagrams in documents only, beside the prose and never in its place (§ Diagrams); signatures, state shapes and code examples under 15 lines in reference documents only (§ Reference documents).
 
 ## 5. With a human in the loop — the co-authoring workflow
 

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

@@ -17,7 +17,7 @@ const RULES = [
   { id: 'status-glyph', severity: 'warn', scope: 'truth', exempt: /(^|\/)docs\/(tests|operations)\//, pattern: /(^|\s)(✅|⏳|- \[[ x]\])/u, message: 'status glyph / checklist in a truth doc — tracking belongs in a record' },
   // Truth docs are supposed to cite records, and record filenames are dated — so a date inside a link
   // target or a code span is a path, not narration. Strip those before matching.
-  { id: 'date-in-truth-doc', severity: 'block', scope: 'truth', strip: /\[[^\]]*\]\([^)]*\)|`[^`]*`|^(last-reviewed|last-updated|rev|harness-version):.*$/gm, pattern: /\b20\d{2}-\d{2}-\d{2}\b/, message: 'date in a truth doc — cite the record by name and link; the closed exceptions are the frontmatter tooling keys, an AD Decision Changelog tail and structure.md\'s Health Log tail' },
+  { id: 'date-in-truth-doc', severity: 'block', scope: 'truth', strip: /\[[^\]]*\]\([^)]*\)|`[^`]*`|^(last-reviewed|last-updated|rev|harness-version):.*$/gm, pattern: /\b20\d{2}-\d{2}-\d{2}\b/, message: 'date in a truth doc — cite the record by name and link; the closed exceptions are the frontmatter tooling keys, an AD Decision Changelog tail and a dated path inside a link or code span' },
 ];
 
 // Sections inside a truth doc where dated history is sanctioned (the two bridges).
@@ -119,11 +119,113 @@ 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 Destinations 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 scanned by people; its "For the agent" footer holds the pointers
+  // (style-guide § Owning documents — the body and the footer). Body identifiers 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 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)) {
+        section = { n, title: line.replace(/^##\s+/, '').trim(), ids: 0 };
+        sections.push(section);
+        continue;
+      }
+      if (!section) continue;
+      for (const m of line.matchAll(/`([^`]+)`/g)) {
+        const t = m[1];
+        // What a person types or sees is the feature's surface, not code: a page path, a flag, an environment variable, a command.
+        if (/^\/[a-z]|^--?[a-z]|^[A-Z][A-Z0-9_]+(=\S*)?$|^[a-z][\w-]* [a-z-]/.test(t)) continue;
+        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|Gaps|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 where a person types or sees it, or at a cross-cutting seam (a middleware, gate, hook, store); the rest is plain names, with pointers in "For the agent"`, excerpt: s.title });
+    }
+  }
+
+  // A heading or a bold bullet label names; it never says. A label with a finite verb drags in a tense,
+  // a person and a voice ("What was decided", "You already belong to…"), so a label opening with a
+  // wh-word or a personal pronoun, or ending in a full stop, is a clause (style-guide § Labels).
+  const isLabelledDoc = isOwningDoc || (scope === 'truth' && !isFolderIndex && /(^|\/)docs\/architecture\/common\/[^/]+\.md$/.test(path));
+  if (isLabelledDoc && !disabled.has('clause-label')) {
+    const CLAUSE = /^(how|what|why|where|when|who|which|whose|you|your|we|our|i|it)\b|\b(you|your)\b|\.$/i;
+    for (const { n, line } of lines) {
+      const heading = /^#{2,4}\s+(.+?)\s*$/.exec(line);
+      const bold = /^\s*[-*]\s+\*\*(.+?)\*\*/.exec(line);
+      const label = heading ? heading[1] : bold ? bold[1].replace(/:$/, '').trim() : null;
+      if (!label || /^For the agent$/i.test(label)) continue;
+      if (CLAUSE.test(label.replace(/`[^`]*`/g, 'X'))) findings.push({ path, n, severity: 'warn', id: 'clause-label', message: 'a heading or bold label written as a clause — a label is a noun phrase with no verb, tense or person ("Decisions", not "What was decided"; "Organization member:", not "You already belong to an organization:")', excerpt: label.slice(0, 90) });
+    }
+    // The sentences after a label describe the product in the third person; quoted interface copy keeps its own "you".
+    if (!disabled.has('second-person')) {
+      for (const { n, line } of lines) {
+        const bare = line.replace(/`[^`]*`/g, '').replace(/\*\*[^*]+\*\*/g, 'X').replace(/\*"[^"]*"\*|\*[^*]+\*|"[^"]*"/g, '');
+        if (/\b(you|your|yours|yourself)\b/i.test(bare)) findings.push({ path, n, severity: 'warn', id: 'second-person', message: 'second person in a truth document — the sentence after a label is third person ("user lands…", never "you land…"); quoted interface copy is exempt', excerpt: line.trim().slice(0, 90) });
+      }
+    }
+  }
 }
 
 // A changed plan whose committed version is already frozen must not be edited.

package/data/harnesses/code/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/code/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/code/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/code/skills/documentation/templates/doctrine.md

@@ -0,0 +1,81 @@
+# 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 their relations
+- **one section per part**
+- **For the agent**
+
+**Optional:**
+
+- an `UNBUILT` block for decided-but-unbuilt intent
+
+Nothing else: the neighbouring documents live in **For the agent**, the one closing link surface (`references/style-guide.md` § Self-contained documents and the link surface). 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
+
+### {The ownership boundary, as a noun phrase — e.g. "Identity: checked, not owned"}
+
+{The one framing fact a reader needs before anything else. Plain words, no addresses.}
+
+### {The participants, as a noun phrase — e.g. "Callers"}
+
+{Who or what participates: one bullet each, a bold noun-phrase label in plain words, its term of art in parentheses, then one line.}
+
+### {The organizing axis, as a noun phrase — e.g. "Proof checking"}
+
+{The one or two dimensions every part is placed on. A small table is right here.}
+
+### Principles
+
+{Numbered invariants that hold across every part, each a bold noun-phrase label, then the rule and its reason in a sentence or two. Later sections cite them by number.}
+
+## {The parts, as a noun phrase — e.g. "Credential families"}
+
+{One table: each part placed on the model's axes. Then a "Relations" subsection: what they share, where they meet, what keeps them apart, and the order in which they are tried — each a bullet with a bold noun-phrase label and its reason. A role-level diagram (mermaid) where the relationships are a flow.}
+
+## {The parts in depth, as a noun phrase — e.g. "Families in depth"}
+
+### {One part, named for who meets it — e.g. "Browser person", "Trusted system"}
+
+{One line on why the part exists, then the decisions it rests on as bullets — a bold noun-phrase label, then the 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 |

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

@@ -1,151 +1,95 @@
-# Feature Documentation — the LLD (docs/features/{feature}.md)
+# Feature Documentation (docs/features/{feature}.md)
 
-Truth document. Use for: every feature in `docs/features/`. The feature doc is the feature's **LLD (low-level design)**: the same file persists from design (Status: Draft, written in LLD Mode) through implementation to live reference (Status: Active). Sections fill in as the feature matures — no template swap. The body always describes the feature as it currently is; the journey lives in the linked plan and changelog entries.
+Truth document. Use for every feature in `docs/features/`: something a person points at, such as an address, a command family or a named control. One file per feature, cut by the objects it designs, never by the code's routers, tables, plans or packages. The file persists from design (`status: draft`) to live reference (`status: active`).
 
-**Required vs optional.** Required in every feature doc: the frontmatter, **Goal**, and **Background** — plus **Files** once implementation exists (a Draft for unbuilt code has no real paths to list) and **Current Behavior** once research or implementation exists (at Draft it's the pre-feature baseline; at Active it's how the feature works today). Every other section is optional: include it only when the feature has something real to put in it (no Redux → no Redux section; no risks worth naming → no Risks section). A **minimal form** is sanctioned for small features: frontmatter + Goal + a short how-it-works section + Files. A two-screen doc that is accurate beats a full-template doc with empty sections.
+**A feature document is sharp, bulleted and actionable** (`references/style-guide.md` § Labels; § Shape — the model first, the detail after). A reader scans it rather than reads it:
 
-The four research-derived sections (**Affected Modules**, **Conventions to Follow**, **Current Behavior**, **Ownership Conflicts**) map 1:1 to the `lld-mode` agent's return shape. The orchestrator drops its findings into those slots without restructuring.
+- **Headings and bullet labels are noun phrases.** For example `Flows`, `Organization member`, `Dead grant` — never a clause like "How it works" or "You already belong to an organization".
+- **Each bullet is a bold label, then one or two third-person sentences** saying what happens: "**Organization user:** user lands in their existing organization", never "you land…".
+- **Flows carry the journey; Decisions carry the reasons; Promises run deepest.**
+
+Every computable fact (columns, vocabularies, foreign keys, writers, routes, guards, files) is the code graph's (`docs/architecture/systems/knowledge-layer.md`), and a hand-typed copy is the defect this genre removes. Code is named only where a person types or sees it (a page, a command, a flag, an environment variable) or at a cross-cutting seam the graph would not lead a reader to.
+
+**A feature document runs deepest toward its end.** Scope and Flows are the model and the journey. **Promises** goes as deep as the behaviour does: every state the surface can be in, every edge case, what a refusal tells the person, and the exact wording wherever the wording itself is promised. That depth is earned because a person or a test checks it and the code cannot state it as intent. It still stops before mechanism. A promise reads "a removed membership shows a panel, not a redirect", never which route answers it.
+
+**Sections:**
+
+| Section | When |
+| --- | --- |
+| Frontmatter | required |
+| Goal line | required |
+| `Scope` | required |
+| `Flows` | required |
+| `Decisions` | once any choice was made that the code cannot explain |
+| `Promises` | required |
+| `Gaps` | only when there is one |
+| `For the agent` | required |
+
+Nothing else. `doc-lint` blocks the retired mechanism sections (`mechanism-section`), and warns on code identifiers in the body (`body-identifier`), on a heading or bullet label written as a clause (`clause-label`), and on "you" outside quoted copy (`second-person`).
 
 ```yaml
 ---
-owns: ["src/feature/**", "src/other/file.ts"]   # required — code-path globs this doc owns (the only ownership key)
-module: billing                                  # optional — single bounded-context label; omit if cross-cutting
-keywords: [invoice, pdf]                         # required — discovery terms
+type: feature                                    # required tooling key — preserve, never narrate
 status: active                                   # required — active | draft | deprecated
-applies: [docs/architecture/common/security.md]  # optional — architecture docs this surface is BOUND by (obligation, not a bibliography); omit when none
-last-reviewed: YYYY-MM-DD                        # optional tooling key — stamped on substantive review/update; the maintenance agent ranks audit priority by it (metadata, never narrated in the body)
-type: feature                                    # required tooling key — genre stamp (generator-written or authored; enum = the template names), read by tooling (UI grouping, protected-file mapping); preserve on edits, never narrate
+objects: [device, credential grant]              # required — the product objects this document designs, by their graph names
+owns: ["packages/studio/src/server/routes/devices.ts"]  # required until the graph computes ownership — the code this document speaks for; narrower glob wins
+module: identity                                 # optional — one bounded-context label
+applies: [docs/architecture/common/security.md]  # optional — doctrine this surface is BOUND by
 ---
 ```
 
-> Declare the code paths it owns in its `owns:` frontmatter — projected at Draft, confirmed against real code at Active.
-
 ```
-# {Feature Name}
-
-<!-- Lifecycle lives in the frontmatter `status:` key (active | draft | deprecated) — the single source of truth. Don't restate it in the body. -->
-**Plan:** [history/plans/YYYY-MM-DD-feature-name.md](../history/plans/YYYY-MM-DD-feature-name.md)   <!-- added once a plan exists -->
-
-## Goal
-
-One sentence. What this feature accomplishes, in user-facing terms.
-
-## Goals & Non-Goals
-
-**In scope**
-- Bullet 1
-- Bullet 2
-
-**Out of scope**
-- Bullet 1
-
-## Background
-
-Why this feature exists. The user need, the business trigger, the constraint that pushed it above the line. One paragraph.
-
-(For Product-level work, also include: problem statement, key hypotheses, open questions.)
-
-## Approach
+# {Feature name}
 
-High-level shape of the solution. ASCII diagram if it helps. Implementation specifics belong in the plan.
+{One sentence: what this lets a person do.}
 
-## Affected Modules
+## Scope
 
-(From lld-mode research) Files, routes, components, slices this feature involves. Group by module.
+- **Covers:** {the surfaces, commands and journeys this document owns}
+- **Bound by:** {the doctrine documents it applies, each with what it settles}
+- **Not here:** {the neighbouring features a reader might expect here, each linked}
 
-| Module | Path | Role in this feature |
-|--------|------|----------------------|
+## Flows
 
-## Conventions to Follow
+### {Entry point or situation, as a noun phrase — e.g. "Browser", "Terminal", "Landing", "Sign-out"}
 
-(From lld-mode research) Naming patterns, structural patterns, doc-fit heuristics confirmed for the area being touched. Cite the source file(s) where the convention is established.
+- **{Noun-phrase label — e.g. "Signed-out visitor", "Claimed domain", "`nustack login`"}:** {what the user does or meets, and what happens. One or two sentences, third person, present tense — "user lands…", never "you land…".}
+  - {a sub-case, only where the parent genuinely branches}
 
-## Current Behavior
+## Decisions
 
-(From lld-mode research) How the relevant part of the system works *today*, before this feature lands. Without this baseline the design intent is hard to evaluate.
+- **{The decision as a noun phrase — e.g. "Single entry, no sign-up", "Unsigned organization cookie"}:** {why, in one or two sentences, and the alternative a reader would reach for if it matters.}
 
-## Ownership Conflicts
+## Promises
 
-(From lld-mode research) Existing feature docs whose `owns:` globs overlap with the projected scope. Resolve before the plan starts — leave nothing unresolved.
+### {Theme as a noun phrase — e.g. "Sign-in failures", "Gate outcomes", "Terminal grant states"}
 
-| Conflicting doc | Overlapping path(s) | Resolution |
-|-----------------|---------------------|------------|
+{A table where the cases are parallel states — | Situation | What the person sees | — carrying the exact wording where the wording is promised. Bullets otherwise:}
 
-## Architecture
+- **{Noun-phrase label}:** {the guarantee or refusal, checkable by a person or a test.}
 
-[ASCII diagram. Fill once implementation lands. See style-guide.md for box-drawing patterns.]
+## Gaps
 
-## Key Functions
+- **{Noun-phrase label}:** {what the code does not keep, and what closing it would take. The backlog row carries the rest.}
 
-### `functionName(param1, param2)`
-**Goal:** What it accomplishes
-**Input:**
-- `param1` (type) - Description
-- `param2` (type) - Description
-**Output:** Return type and shape
-**Side Effects:** DB writes, API calls, state updates
+## For the agent
 
-### `hookName(config)`
-**Goal:** What it provides
-**Returns:** `{ data, loading, error }`
-**Triggers:** On mount, on change, manual
+- **Objects:** {object}: {one plain line}; {object}: {…}
+- **Pages:** {`/…`}
+- **Commands:** {`nustack …`}
+- **Code roots:** {`packages/…/src/…/`}, directories where the graph should start
+- **Seams:** {`name`}, only where the roots would not lead to them
+- **Checklist:** `tests/{feature}.md`
+- **See also:** {neighbour}: {why}
 
-## State
-
-**Frontend (at persistence):**
-{
-  "data": [],
-  "changes": { "added": [], "updated": [], "removed": [] }
-  // "cache": {}  // UNUSED: dead key; kept so old persisted state rehydrates
-}
-
-**Storage:** localStorage `app_state`
-
-**Backend:**
-export const resources = pgTable('resources', {
-  id: text('id').primaryKey(),
-  data: jsonb('data'),
-  // oldField: text('old_field'),  // UNUSED: dead column; nothing reads it
-});
-
-**API Shape:**
-{ "status": 1, "data": {...} }
-
-## Redux (if applicable)
-
-**Slice:** `sliceName`
-
-**Actions:**
-- `setData(payload)` - Replace all data
-- `upsertItem(item)` - Add or update single item
-
-**Selectors:**
-- `selectAll(state)` → `Array<Item>`
-- `selectById(state, id)` → `Item | undefined`
-
-## Files
-
-- `src/path/to/main.js` - Core logic
-- `src/path/to/hooks.js` - React hooks
-
-## Open Questions
-
-- Question — who decides, by when
-- (Resolved questions: fold the resolution into Background.)
-
-## Risks
-
-- Risk — likelihood / impact / mitigation
+No tables, routes or symbol rosters — those are the graph's.
 ```
 
-### Section evolution
-
-Sections fill in across the feature's lifecycle. No template swap — they accumulate in place.
+### Lifecycle
 
-| When | Sections written | Source |
-| --- | --- | --- |
-| Status: Draft (design) | Goal, Goals & Non-Goals, Background, Approach, Open Questions, Risks | User interview |
-| Status: Draft (research) | Affected Modules, Conventions to Follow, Current Behavior, Ownership Conflicts | lld-mode agent |
-| Status: Draft → Active (implementation lands) | Architecture, Key Functions, State, Redux, Files; `owns:` globs confirmed against real code | Main agent (from actual code) |
+| When | What is written |
+| --- | --- |
+| `status: draft` (design) | goal, Scope, Decisions, Promises (with gaps named), For the agent; the LLD research goes to the plan |
+| `status: active` | Flows written from the shipped surface; `owns:` confirmed against real code |
 
-Resolved Open Questions can be summarized into Background; unresolved ones stay visible.
+A feature whose code is gone is deleted, or `status: deprecated` with its footer pointing at what replaced it.