@nurix/etna 0.20.40 → 0.20.42

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

@@ -1,4 +1,4 @@
-// skills/documentation/scripts/doc-lint.mjs - mechanical checks over markdown docs (tense and history narration, dates, redirect stubs, frontmatter, index shape, owning-document body)
+// skills/documentation/scripts/doc-lint.mjs - mechanical checks over markdown docs (tense and history narration, dates, redirect stubs, frontmatter, index shape, owning-document body, doctrine sets)
 // Usage: node doc-lint.mjs <file.md ...> | node doc-lint.mjs --changed   (git-changed + untracked .md)
 // Exit 1 when any block-severity finding survives. Escape hatch: <!-- doc-lint-disable: id[, id] --> alone on its
 // own line (file-wide, with a reason comment beside it) or at the end of the offending line (that line only).
@@ -392,6 +392,13 @@ function lintFile(path, findings) {
       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) });
     }
+    // "X exists so that…" restates the subject its heading already named; the purpose belongs in the rule it implies.
+    if (!disabled.has('purpose-opener')) {
+      for (const { n, line } of lines) {
+        const bare = line.replace(/`[^`]*`/g, 'X').replace(/^\s*[-*]\s+(\*\*[^*]+\*\*:?\s*)?/, '');
+        if (/^(the |an? )?[\w' -]{1,40}? exists (so that|to |because|in order)/i.test(bare)) findings.push({ path, n, severity: 'warn', id: 'purpose-opener', message: '"X exists so that…" — state the rule the purpose implies ("An unvetted organization signs in and reads, and creates nothing"), not that the thing has a purpose', excerpt: line.trim().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) {
@@ -400,6 +407,170 @@ function lintFile(path, findings) {
       }
     }
   }
+
+  if (scope === 'truth' && !isFolderIndex && (declared === 'doctrine' || DOCTRINE_LOCATION.test(path))) lintDoctrine(path, text, lines, disabled, findings);
+}
+
+// A doctrine folder is read as a set: its documents cite each other's principles by number and must not restate each
+// other (templates/doctrine.md, references/document-sets.md), so these checks read the siblings beside the linted file.
+const DOCTRINE_LOCATION = /(^|\/)docs\/architecture\/common\/[^/]+\.md$/;
+// A doctrine document closes on Terms and Related documents; an older one on "For the agent". The body ends at the first.
+const DOCTRINE_CLOSING = /^##\s+(For the agent|Terms|Related documents)\s*$/;
+// The words a doctrine document replaces with the term engineers use (references/style-guide.md § Vocabulary).
+const VAGUE_TERMS = [[/\bdoors?\b/i, 'route or endpoint'], [/\bgates?\b/i, 'route, check or permission check'], [/\brefus(e|es|ed|ing|als?)\b/i, 'reject, rejection'], [/\bpowers?\b/i, 'permission or role'], [/\bprov(e|ing) it again\b/i, 'step-up verification']];
+// The specification sentence every doctrine document carries verbatim is the template's, not a duplicated rule.
+const SPEC_SENTENCE = /specification of its concern|has a gap to plan and build|never settled silently in code/i;
+const STOPWORDS = new Set('the and for that this with from are its their them they into onto than then when where which while who whom whose what each every any all one its not nor but was were has have had been being does did can may must will would should could only also more most other such same own per via out off over under about after before between both either neither those these there here because so as at by in of on or to an a is be it no'.split(' '));
+const siblingCache = new Map();
+
+// The doctrine documents in a folder, each with its title, objects, principle numbers, headings and sentences.
+function doctrineSiblings(dir) {
+  if (siblingCache.has(dir)) return siblingCache.get(dir);
+  const docs = [];
+  for (const name of existsSync(dir) ? readdirSync(dir) : []) {
+    if (!name.endsWith('.md') || /^readme\.md$/i.test(name)) continue;
+    const path = join(dir, name);
+    const text = readFileSync(path, 'utf8');
+    const lines = proseLines(text);
+    const title = (lines.find(({ line }) => /^#\s+/.test(line))?.line || '').replace(/^#\s+/, '').trim().toLowerCase();
+    docs.push({ path, name, title, text, lines, objects: listValue((frontmatter(text) || new Map()).get('objects')).map((o) => o.toLowerCase()), principles: principleNumbers(lines), headings: new Set(lines.map(({ line }) => /^#{2,4}\s+(.+?)\s*$/.exec(line)?.[1].toLowerCase()).filter(Boolean)), sentences: sentencesOf(lines) });
+  }
+  siblingCache.set(dir, docs);
+  return docs;
+}
+
+// The numbers of a document's principles: the numbered items under its Principles heading.
+function principleNumbers(lines) {
+  const out = new Set();
+  let level = 0;
+  for (const { line } of lines) {
+    const heading = /^(#{2,4})\s+(.+?)\s*$/.exec(line);
+    if (heading) { level = /^principles$/i.test(heading[2]) ? heading[1].length : level && heading[1].length <= level ? 0 : level; continue; }
+    const item = level && /^(\d+)\.\s/.exec(line);
+    if (item) out.add(Number(item[1]));
+  }
+  return out;
+}
+
+// The body's sentences long enough to state a rule, as content-word sets; headings, tables and the footer drop out.
+function sentencesOf(lines) {
+  const out = [];
+  for (const { n, line } of lines) {
+    if (DOCTRINE_CLOSING.test(line)) break;
+    if (/^\s*(#|\|)/.test(line) || !line.trim()) continue;
+    const plain = line.replace(/^\s*([-*]|\d+\.)\s+/, '').replace(/\*\*[^*]+\*\*:?/g, '').replace(/\[([^\]]+)\]\([^)]*\)/g, '$1').replace(/`/g, '');
+    for (const sentence of plain.split(/(?<=[.;])\s+(?=[A-Z(])/)) {
+      if (SPEC_SENTENCE.test(sentence)) continue;
+      const words = new Set((sentence.toLowerCase().match(/[a-z][a-z'-]+/g) || []).filter((w) => w.length > 2 && !STOPWORDS.has(w)));
+      if (words.size >= 9) out.push({ n, text: sentence.trim(), words });
+    }
+  }
+  return out;
+}
+
+const slugOf = (name) => name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+
+function lintDoctrine(path, text, lines, disabled, findings) {
+  const siblings = doctrineSiblings(dirname(path));
+  const self = siblings.find((d) => d.name === path.split('/').pop()) || { path, objects: [], principles: principleNumbers(lines), headings: new Set(), sentences: sentencesOf(lines) };
+  const byName = (name) => siblings.find((d) => d.title === name.toLowerCase() || d.name === `${slugOf(name)}.md`);
+  const footerAt = lines.findIndex(({ line }) => DOCTRINE_CLOSING.test(line));
+  const body = footerAt === -1 ? lines : lines.slice(0, footerAt);
+  // The opening runs to the first section; its out-of-scope bullets are the one place in the body a link belongs.
+  const openingEnd = lines.findIndex(({ line }) => /^##\s+/.test(line));
+  const sections = body.slice(openingEnd === -1 ? body.length : openingEnd);
+
+  // A citation names a principle by number or a section by heading, in parentheses: "(principle 4)", "(auth, principle 3)", "(API protocol § Idempotency)".
+  if (!disabled.has('citation-unresolved')) {
+    for (const { n, line } of lines) {
+      for (const group of line.replace(/`[^`]*`/g, '').matchAll(/\(([^()]+)\)/g)) {
+        for (const part of group[1].split(';').map((p) => p.trim())) {
+          const principle = /^(?:(.+?),\s*)?principles?\s+(\d+(?:\s*(?:,|and)\s*\d+)*)$/i.exec(part);
+          const section = /^(.+?)\s+§\s+(.+)$/.exec(part);
+          if (!principle && !section) continue;
+          const name = principle ? principle[1] : section[1];
+          const target = name ? byName(name) : self;
+          if (!target) { findings.push({ path, n, severity: 'warn', id: 'citation-unresolved', message: `"${name}" names no doctrine document in this folder — cite a sibling by its title`, excerpt: part }); continue; }
+          const where = target === self ? 'this document' : target.name;
+          if (principle) for (const num of principle[2].split(/\s*(?:,|and)\s*/).map(Number))
+            if (!target.principles.has(num)) findings.push({ path, n, severity: 'block', id: 'citation-unresolved', message: `principle ${num} does not exist in ${where} (it numbers ${[...target.principles].join(', ') || 'none'})`, excerpt: part });
+          if (section && !target.headings.has(section[2].trim().toLowerCase())) findings.push({ path, n, severity: 'block', id: 'citation-unresolved', message: `${where} has no heading "${section[2].trim()}"`, excerpt: part });
+        }
+      }
+    }
+  }
+  // One concept has one home: an object two doctrine documents both govern is a boundary the set has not drawn.
+  if (!disabled.has('objects-shared')) {
+    for (const object of self.objects) {
+      const other = siblings.find((d) => d !== self && d.objects.includes(object));
+      if (other) findings.push({ path, n: 1, severity: 'warn', id: 'objects-shared', message: `\`${object}\` is also in ${other.name}'s objects — one concept, one governing document; the other cites it` });
+    }
+  }
+  // The body names its neighbours in plain words; links live in "For the agent" (references/style-guide.md § Self-contained documents).
+  if (!disabled.has('doctrine-body-link')) {
+    for (const { n, line } of sections)
+      if (/\]\([^)]+\)/.test(line.replace(/`[^`]*`/g, '')) && !line.includes('doc-lint-disable: doctrine-body-link')) findings.push({ path, n, severity: 'warn', id: 'doctrine-body-link', message: 'a link in a doctrine body — name the neighbour in plain words; its link belongs in Related documents, or in the opening\'s out-of-scope bullets', excerpt: line.trim().slice(0, 90) });
+  }
+  // The sentence rules of references/style-guide.md § Sentences and § Vocabulary, on the body's prose: headings, tables
+  // and quotations drop out, and the genre's name is checked to the end of the file.
+  const prose = (line) => line.replace(/`[^`]*`/g, 'X').replace(/\[([^\]]+)\]\([^)]*\)/g, '$1').replace(/\*"[^"]*"\*|"[^"]*"|“[^”]*”/g, 'Q').replace(/<!--.*?-->/g, '');
+  const proseLinesOf = (from) => from.filter(({ line }) => line.trim() && !/^\s*(#|\|)/.test(line));
+  for (const { n, line } of proseLinesOf(body)) {
+    const bare = prose(line);
+    const words = bare.replace(/\*\*/g, '').replace(/^\s*([-*]|\d+\.)\s+/, '');
+    if (!disabled.has('modal-verb') && /\b(must|should|shall)\b/i.test(words)) findings.push({ path, n, severity: 'warn', id: 'modal-verb', message: 'a modal in a specification — state what happens ("the request is rejected"); being in this document makes it a requirement', excerpt: line.trim().slice(0, 90) });
+    if (!disabled.has('question') && /\?(\s|$)/.test(words)) findings.push({ path, n, severity: 'warn', id: 'question', message: 'a question in prose — state the rule declaratively', excerpt: line.trim().slice(0, 90) });
+    if (!disabled.has('vague-term')) for (const [pattern, use] of VAGUE_TERMS) {
+      const m = pattern.exec(words);
+      if (m) { findings.push({ path, n, severity: 'warn', id: 'vague-term', message: `"${m[0]}" — use the standard term: ${use} (references/style-guide.md § Vocabulary)`, excerpt: line.trim().slice(0, 90) }); break; }
+    }
+    if (!disabled.has('long-sentence')) {
+      for (const sentence of words.split(/(?<=[.;!])\s+(?=[A-Z(])/)) {
+        const list = /:\s/.test(sentence) && (sentence.split(/:\s/).slice(1).join(' ').match(/[,;]/g) || []).length >= 2;
+        const count = (sentence.match(/[\w'’-]+/g) || []).length;
+        if (count > 25 && !list) { findings.push({ path, n, severity: 'warn', id: 'long-sentence', message: `${count} words in one sentence — about twenty-five at most, one idea each; a colon list is exempt`, excerpt: sentence.trim().slice(0, 90) }); break; }
+      }
+    }
+  }
+  if (!disabled.has('doctrine-word')) {
+    for (const { n, line } of proseLinesOf(lines))
+      if (/\bdoctrines?\b/i.test(prose(line).replace(/^#+\s+/, ''))) findings.push({ path, n, severity: 'warn', id: 'doctrine-word', message: '"doctrine" in prose — the genre\'s tooling name; the document is "this document" or "this specification", its neighbours "related documents"', excerpt: line.trim().slice(0, 90) });
+  }
+  // Every object the document governs is defined once, in its Terms table.
+  const termsAt = lines.findIndex(({ line }) => /^##\s+Terms\s*$/.test(line));
+  if (termsAt !== -1 && !disabled.has('terms-missing')) {
+    const defined = new Set();
+    for (const { line } of lines.slice(termsAt + 1)) {
+      if (/^##\s+/.test(line)) break;
+      const cell = /^\|\s*([^|]+?)\s*\|/.exec(line);
+      if (cell && !/^(-{3,}|term)$/i.test(cell[1])) defined.add(cell[1].replace(/\*|`/g, '').toLowerCase());
+    }
+    for (const object of self.objects.length ? self.objects : listValue((frontmatter(text) || new Map()).get('objects')).map((o) => o.toLowerCase()))
+      if (!defined.has(object)) findings.push({ path, n: lines[termsAt].n, severity: 'warn', id: 'terms-missing', message: `\`${object}\` is in objects: but not in the Terms table — define every governed term once, there` });
+  }
+  // A doctrine document specifies; what one product has not built is that product's plan or backlog, never a marker here.
+  if (!disabled.has('doctrine-unbuilt')) {
+    const at = text.split('\n').findIndex((l) => /<!--\s*UNBUILT/.test(l));
+    if (at !== -1) findings.push({ path, n: at + 1, severity: 'warn', id: 'doctrine-unbuilt', message: 'an UNBUILT marker in a doctrine document — doctrine is the specification; a product that lacks a part has a gap to plan and build in its own repo' });
+  }
+  // A rule stated twice drifts; the second statement is a citation. Sentences sharing most of their content words are flagged once per pair.
+  if (!disabled.has('sibling-duplicate')) {
+    for (const s of self.sentences) {
+      for (const d of siblings) {
+        const match = d.sentences.find((t) => (d !== self || t.n !== s.n) && overlap(s.words, t.words) >= 0.7 && (d !== self || t.n > s.n));
+        if (!match) continue;
+        findings.push({ path, n: s.n, severity: 'warn', id: 'sibling-duplicate', message: `restates ${d === self ? 'this document' : d.name}:${match.n} — keep the rule in one home and cite it there`, excerpt: s.text.slice(0, 90) });
+        break;
+      }
+    }
+  }
+}
+
+// Shared content words over the smaller sentence's, so a sentence quoted inside a longer one still counts.
+function overlap(a, b) {
+  let shared = 0;
+  for (const w of a) if (b.has(w)) shared++;
+  return shared / Math.min(a.size, b.size);
 }
 
 // A changed plan whose committed version is already frozen must not be edited.

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

@@ -17,7 +17,7 @@ Every fact about a genre lives in one row of the table below: its template, its
 | Feature | [feature.md](feature.md) | truth | `feature` | `docs/features/{feature}.md` | `type` `description` `status` `objects` | Scope · Promises · For the agent |
 | Package | [package.md](package.md) | truth | `package` | `docs/architecture/packages/{package}.md` | `type` `description` `status` `objects` | Scope · Ownership · Usage · Promises · For the agent |
 | System | [system.md](system.md) | truth | `system` | `docs/architecture/systems/{system}.md` | `type` `description` `status` `objects` | Scope · Flow · Promises · For the agent |
-| Doctrine | [doctrine.md](doctrine.md) | truth | `doctrine` | `docs/architecture/common/{concern}.md` | `type` `description` `status` `objects` | The model · For the agent |
+| Doctrine | [doctrine.md](doctrine.md) | truth | `doctrine` | `docs/architecture/common/{concern}.md` | `type` `description` `status` `objects` | Principles · Terms · Related documents |
 | Architecture decision | [architecture-decision.md](architecture-decision.md) | truth | `architecture-decision` | `docs/architecture/decisions/AD-NNN-{subject}.md` | `type` `title` `description` `status` `last-updated` | Decision · Context · Consequences |
 | UX behavior | [ux-behavior.md](ux-behavior.md) | truth | `ux` | `docs/features/{surface}-ux.md` | `type` `description` `status` `objects` | Purpose · Anatomy · States · Affordances · Promises · Transitions |
 | System overview | [system-overview.md](system-overview.md) | truth | `system-overview` | `docs/architecture/system-design.md` | `type` `description` | — |

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

@@ -2,75 +2,79 @@
 
 Truth document. Use for **one concern the platform handles everywhere**: authentication, authorization, storage, the API protocol, credentials, telemetry. One file per concern, named for the concern. A doctrine document speaks for no code: no source header names it, and it carries no `owns:`. The surfaces bound by it are the documents that design or touch the objects it governs, computed through those objects, and each names it in its Scope.
 
-**A doctrine document states the design and nothing beneath it** (`references/style-guide.md` § Shape — the model first, the detail after). It is the most stable document in the tree, because it says why the platform is shaped the way it is, and that changes far less often than the code. It explains no mechanism: no function, file, column, cookie attribute, header value or per-route error code, since each of those fails the stability test. The code graph answers what the code does. This document answers why, and which principles any new code in the concern must keep.
+**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 keeps.
+
+**A doctrine document is a specification, not a description.** It states how every product handles the concern, so a product whose code differs has a gap to plan and build, and the document never records which product has built what: no `UNBUILT` marker, no "today the product…", no product's name, setting value or code root. When one product's posture against the doctrine matters, it is that product's own security overview, plan or backlog.
+
+**Earn the document before writing it.** List the decisions only this document would own, each checked against the documents that exist: a decision another document already states is a citation, not an owned decision. Fewer than about six owned decisions means the concern is a section of a neighbour, not a document (`references/document-sets.md` § Usefulness test).
 
 **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**
+- the opening: the definition sentence, the scope bullets, and the specification sentence
+- **Principles**: numbered, each a noun-phrase label and its rule, with its reason as a separate sentence wherever the rule meets a trigger of `references/style-guide.md` § Sentences
+- **Terms**: one row per term the document uses, covering every name in `objects:`
+- **Related documents**
 
-**Optional:**
+**Optional, each only with something the principles do not already say:**
 
-- an `UNBUILT` block for decided-but-unbuilt intent
+- **A participant section** (e.g. "Callers") before Principles: who or what takes part, as a table where they share attributes
+- **A parts section** (e.g. "Credential families"): one table placing the parts, where there are enough parts that a reader needs them placed, then its relations where two parts meet in a way no principle states
+- **One section per part** that carries decisions of its own (e.g. "Capability links")
 
-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.
+Sections run in that order: opening, participants, Principles, the parts, each part, Terms, Related documents. Each is named for its concept, never for its layer ("The model", "In depth"). Links live in the opening's out-of-scope bullets and in Related documents; the body names a neighbour in plain words (`references/style-guide.md` § Self-contained documents and the link surface). Expect eighty to two hundred and fifty lines; past that, mechanism or restatement has usually crept in.
 
 ```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]   # required — the concepts this doctrine governs, by their graph names
+objects: [principal, credential, device grant]   # required — the concepts this document 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.}
+This document defines {what, for every product}: {the specifics it covers, in parallel form}.
 
-## The model
+- **In scope:** {each item a noun phrase}
+- **Out of scope:** {each item a noun phrase, then a colon and the linked document that owns it}
 
-### {The ownership boundary, as a noun phrase — e.g. "Identity: checked, not owned"}
+{Optional: one sentence of rationale, where the boundary with a neighbour needs justifying.}
 
-{The one framing fact a reader needs before anything else. Plain words, no addresses.}
+{The specification sentence, with the scope named: "Every product on {the scope, e.g. the enterprise plane} implements this document; a product whose code differs from it has a gap to plan and build."}
 
-### {The participants, as a noun phrase — e.g. "Callers"}
+## {The participants, as a noun phrase — e.g. "Callers"} (optional)
 
-{Who or what participates: one bullet each, a bold noun-phrase label in plain words, its term of art in parentheses, then one line.}
+{One row or bullet per participant: its name, its definition, and the attribute the parts are placed on. A table where the participants share attributes.}
 
-### {The organizing axis, as a noun phrase — e.g. "Proof checking"}
+## Principles
 
-{The one or two dimensions every part is placed on. A small table is right here.}
+{Numbered rules that hold across every part. Each item: a bold noun-phrase label and a colon, then the rule as one sentence, then its reason as a separate sentence wherever the rule meets a trigger of the style guide's § Sentences: a tempting alternative, a cost, an arbitrary value, an invisible failure. Later sections cite them by number. A rule another document owns is cited — "(auth service, principle 5)" — never restated here.}
 
-### Principles
+## {The parts, as a noun phrase — e.g. "Credential families"} (optional)
 
-{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.}
+{One table: each part placed on the model's axes. A row whose only content is "see principle N" is not placing anything; drop the table when every row would be one. Then the relations, as bullets: only where two parts meet in a way no principle states — what they share, what keeps them apart, the order in which they are tried. A role-level diagram (mermaid) where the relationships are a flow.}
 
-## {The parts, as a noun phrase — e.g. "Credential families"}
+## {One part, as a noun phrase — e.g. "Capability links", "Trusted systems"} (optional, one per part)
 
-{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 part's definition in one sentence, where its name does not already give it. Then the decisions this part rests on that no principle states, as bullets — a bold noun-phrase label, the rule, then its reason where earned — citing principles by number. A part with nothing beyond its principles gets no section. A sequence diagram at role level where the part is a flow.}
 
-## {The parts in depth, as a noun phrase — e.g. "Families in depth"}
+## Terms
 
-### {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.}
+| Term | Definition |
+| --- | --- |
+| {every name in `objects:`, and every other term a reader could misread} | {one line} |
 
-## For the agent
+## Related documents
 
-{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.}
+- [{Neighbour}]({neighbour}.md): {what it settles that this document does not}
 ```
 
-### Marking what is decided and unbuilt
+### Citations
 
-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.
+Principles are cited by number, sections by heading, always in parentheses: "(principle 4)" in the document itself, "(auth, principle 3)" or "(API protocol § Rate limits)" for a sibling, by its title. `doc-lint` resolves each against the folder and blocks a number or heading that does not exist, so a renumbering is caught at the next lint, not by a reader.
 
 ### What a doctrine document is not
 
@@ -78,5 +82,7 @@ Code cannot reveal what it does not yet do, so decided-but-unbuilt intent is one
 | --- | --- |
 | A tour of the code that implements the concern | The code graph |
 | The catalog of routes, error codes or variables | An API reference or environment registry |
-| The one feature that happens to use the concern most | That feature's own document, which names this doctrine in its Scope |
+| The one feature that happens to use the concern most | That feature's own document, which names this document in its Scope |
 | The story of how the concern got this way | The subject's architecture decision (`decisions/`), whose Decision Changelog tail carries how it moved, and the changelog for the when |
+| A record of which product has built which part | That product's plan, backlog, or security overview |
+| A restatement of a sibling's rule for completeness | A citation of the sibling's principle, with the one clause of context the sentence needs |

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

@@ -45,9 +45,9 @@ owns: ["packages/studio/src/server/devices/**"]   # transitional — one region
 
 ## Scope
 
-- **Covers:** {the surfaces, commands and journeys this document owns}
+- **In scope:** {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}
+- **Out of scope:** {the neighbouring features a reader might expect here, each linked}
 
 ## Flows
 

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

@@ -45,7 +45,7 @@ owns: ["packages/{name}/**"]                     # transitional — the residual
 
 - **Role:** {what it holds that nothing else does}
 - **Consumers:** {who consumes it, and how and when it ships}
-- **Not here:** {what it deliberately does not hold, and where that lives}
+- **Out of scope:** {what it deliberately does not hold, and where that lives}
 
 ## Ownership
 

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

@@ -41,8 +41,8 @@ owns:                                            # transitional — region globs
 
 ## Scope
 
-- **Covers:** {what this machine decides}
-- **Not here:** {subject} — {owning document}; {subject} — {owning document}
+- **In scope:** {what this machine decides}
+- **Out of scope:** {subject} — {owning document}; {subject} — {owning document}
 
 ## Flow
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nurix/etna",
-  "version": "0.20.40",
+  "version": "0.20.42",
   "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": "d4d71fdc192e"
+  "etnaFingerprint": "bd1f2b63adef"
 }