@nurix/etna 0.20.40 → 0.20.42

package/data/harnesses/code/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/code/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/code/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/code/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/code/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/code/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/data/harnesses/delivery/harness.json

@@ -1,7 +1,7 @@
 {
   "harness": "delivery",
   "name": "delivery",
-  "version": "0.2.45",
+  "version": "0.2.47",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
@@ -14,5 +14,5 @@
     "origin": "https://cdn.nustack.io",
     "track": "latest"
   },
-  "digest": "f02364026d17"
+  "digest": "0e79c085c86d"
 }

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

@@ -11,9 +11,9 @@ This skill writes one document at a time: the genre registry says what kind of d
 
 1. This file.
 2. Your genre's row in [`templates/Readme.md`](templates/Readme.md) § Registry, then the template that row names.
-3. [`references/style-guide.md`](references/style-guide.md) § The model and § Labels before writing prose; the rest of it only for the section you are writing.
+3. [`references/style-guide.md`](references/style-guide.md) § The model, § Labels, § Sentences and § Vocabulary before writing prose; the rest of it only for the section you are writing.
 4. [`references/frontmatter.md`](references/frontmatter.md) when you write or change frontmatter keys beyond `type:` and `description:`.
-5. Only for their own tasks: [`references/untemplated.md`](references/untemplated.md) (no registry row fits), [`references/instruction-style.md`](references/instruction-style.md) (instruction files), [`references/source-comments.md`](references/source-comments.md) (source-file comments), [`references/examples.md`](references/examples.md) (worked good and bad examples).
+5. Only for their own tasks: [`references/document-sets.md`](references/document-sets.md) (more than one sibling document, or a doctrine document), [`references/untemplated.md`](references/untemplated.md) (no registry row fits), [`references/instruction-style.md`](references/instruction-style.md) (instruction files), [`references/source-comments.md`](references/source-comments.md) (source-file comments), [`references/examples.md`](references/examples.md) (worked good and bad examples).
 
 ---
 
@@ -21,11 +21,12 @@ This skill writes one document at a time: the genre registry says what kind of d
 
 1. **Find the genre.** Match the request against § Routing, then read that genre's registry row: nature, `type:`, location, required keys, required sections. No row fits ⇒ `references/untemplated.md`.
 2. **Find the existing document.** If a document on the topic already exists, extend it; a second document on one topic is drift. If the file is a frozen record (a plan at `Complete` or `Abandoned`, a committed changelog entry, an executed runbook), never edit it: write a new dated record that links back.
-3. **Place and name it** at the registry's location. `docs/structure.md` is the placement authority for anything the registry leaves open.
-4. **Write it from the template.** Keep the template's section names exactly; omit optional sections with nothing real to say. Write the body from the outside in (style guide § Shape), every heading and bold label a noun phrase, every sentence after a label third person. In a truth document, every sentence is present tense (§ The three natures).
-5. **Write the frontmatter.** `type:` from the registry, `description:` in at most 300 characters saying what the document settles and where its boundary sits, then the genre's required keys (`references/frontmatter.md` for each key's rules).
-6. **Run the lint** from the repo root on the repo-relative path: `node <skill>/scripts/doc-lint.mjs docs/features/sign-in.md` (or `--changed`). Fix every `[block]` finding; read every `[warn]` and fix it unless the judgment it flags is genuinely yours. A disable takes bare rule ids, `<!-- doc-lint-disable: id -->`, alone on its own line for the whole file with the reason in a second comment on the next line, or at the end of one line for that line only.
-7. **Edit, don't append, on a substantive change to an existing truth document.** Keep its section shape, shed any history narration, progress marker or stale tripwire in the sections you touch, bump `last-reviewed:`, update `objects:` if what it designs changed, and remove any retired key on the way through.
+3. **Earn it, and route a set.** A new truth document that states rules (doctrine, a system, an architecture decision) first lists the decisions only it would own, each checked against the documents that exist; under about six, its rules go to their homes and the document is not written. More than one sibling document, or any doctrine document, follows `references/document-sets.md` from here: a term table and a rule ledger before prose, rendered from the ledger, one cold read.
+4. **Place and name it** at the registry's location. `docs/structure.md` is the placement authority for anything the registry leaves open.
+5. **Write it from the template.** Keep the template's section names exactly; omit optional sections with nothing real to say. Write the body from the outside in (style guide § Shape), every heading and bold label a noun phrase, every sentence after a label third person, one rule per sentence in the term engineers use (style guide § Sentences, § Vocabulary). In a truth document, every sentence is present tense (§ The three natures). Every line owns a decision: before stating a rule, search the neighbours for it, and cite the one found rather than restating it (style guide § Net-net).
+6. **Write the frontmatter.** `type:` from the registry, `description:` in at most 300 characters saying what the document settles and where its boundary sits, then the genre's required keys (`references/frontmatter.md` for each key's rules).
+7. **Run the lint** from the repo root on the repo-relative path: `node <skill>/scripts/doc-lint.mjs docs/features/sign-in.md` (or `--changed`). Fix every `[block]` finding; read every `[warn]` and fix it unless the judgment it flags is genuinely yours. A disable takes bare rule ids, `<!-- doc-lint-disable: id -->`, alone on its own line for the whole file with the reason in a second comment on the next line, or at the end of one line for that line only.
+8. **Edit, don't append, on a substantive change to an existing truth document.** Keep its section shape, shed any history narration, progress marker or stale tripwire in the sections you touch, bump `last-reviewed:`, update `objects:` if what it designs changed, and remove any retired key on the way through.
 
 ---
 
@@ -67,7 +68,7 @@ The full strip-list and the record-side rules: `references/style-guide.md` § Th
 - **Intent and promises; facts are the graph's.** An owning document (feature, package, system) says why the product is shaped this way and what it promises, and names the objects it designs in `objects:`. Every computable fact (a table's columns, which function writes which column, which route sits behind which guard, which file holds what) is the code's, and a hand-typed copy is wrong the day the code moves. `doc-lint` blocks the retired mechanism sections (`mechanism-section`) and an owning document with no `objects:`.
 - **Read by people, pointed at by the footer.** Sharp bullets under noun-phrase headings, each a bold label, a colon, one or two plain sentences; code named only where a person types or sees it, or at a cross-cutting seam; every other pointer in the closing **For the agent** footer (style guide § Owning documents — the body and the footer).
 - **The stability test.** A sentence that would change when a function is renamed, a file moves, or a route, column or error code changes is the code's, not the document's. The code is the authority on *what*; the document on *why* (style guide § Shape).
-- **Unbuilt work has one home per kind.** Decided, unbuilt design sits in the body, wrapped in an `UNBUILT` marker; a shortfall in what is built is one bullet under Gaps; the work that would close either is a backlog row, which the document never tracks (style guide § The stability test).
+- **Unbuilt work has one home per kind, outside doctrine.** A doctrine document is a specification and records no product's build state. Elsewhere, decided, unbuilt design sits in the body, wrapped in an `UNBUILT` marker; a shortfall in what is built is one bullet under Gaps; the work that would close either is a backlog row, which the document never tracks (style guide § The stability test).
 - **No empty stubs.** Omit a section with nothing real to say. Write "None" only where the absence is itself information, such as a plan's Cross-Module Contracts Affected.
 - **No redirect documents.** Moving a document deletes the old file and repoints every inbound link; a "Moved to X" stub rots and creates false search hits.
 
@@ -92,7 +93,8 @@ A document names the objects it designs in `objects:`, and a source file names t
 | Document a feature (LLD) | [`templates/feature.md`](templates/feature.md) |
 | Document a feature's data flow or state | The feature doc's Flows (behaviour) and Promises (guarantees); a persisted shape belongs in the API reference (style guide § State at persistence points); component and transient state are not documented |
 | Document a workspace package | [`templates/package.md`](templates/package.md), the residual owner of `packages/{name}/**` |
-| Document one concern the platform handles everywhere (authentication, storage, the API protocol) | [`templates/doctrine.md`](templates/doctrine.md): design and principles, no mechanism, owns no code |
+| Document one concern the platform handles everywhere (authentication, storage, the API protocol) | [`templates/doctrine.md`](templates/doctrine.md): design and principles, no mechanism, owns no code; written through [`references/document-sets.md`](references/document-sets.md) |
+| Write or rework several sibling documents at once (a doctrine folder, a family of features) | [`references/document-sets.md`](references/document-sets.md): usefulness test, term table, rule ledger, render, one cold read |
 | Document one system spanning packages | [`templates/system.md`](templates/system.md): one machine end to end, never a giant feature doc |
 | Record or revise an architecture decision | [`templates/architecture-decision.md`](templates/architecture-decision.md): one AD per subject, revised in place |
 | Create or update a changelog entry | [`templates/changelog-entry.md`](templates/changelog-entry.md) (record; frozen inside its commit; no row in `CHANGELOG.md`) |
@@ -125,12 +127,13 @@ A document names the objects it designs in `objects:`, and a source file names t
 | --- | --- |
 | `templates/Readme.md` | The genre registry: every genre's nature, `type:`, location, required keys and sections; `doc-lint` reads it |
 | `templates/` | One template per genre the registry names |
-| `references/style-guide.md` | The prose authority: the eight principles, depth per genre, the outside-in shape and stability test, labels and voice, owning documents, tense, diagrams, reference documents |
+| `references/document-sets.md` | Writing several sibling documents as one design: the usefulness test, term table, rule ledger, render, and the review rubric the `doc-reviewer` agent reads |
+| `references/style-guide.md` | The prose authority: the nine principles, what earns a line, depth per genre, the outside-in shape and stability test, labels and voice, owning documents, tense, diagrams, reference documents |
 | `references/frontmatter.md` | Each frontmatter key's rules, the transitional `owns:`, the retired keys |
 | `references/instruction-style.md` | The style for instruction files |
 | `references/untemplated.md` | Writing a document no template covers, and co-authoring one with a person |
 | `references/source-comments.md` | Source-file comments, and the scripts that check them |
 | `references/examples.md` | Good and bad documentation, side by side |
-| `scripts/doc-lint.mjs` | Mechanical checks over written docs: tense and history, dates, redirect stubs, frontmatter, the registry's keys and sections, index shape, owning-document body |
+| `scripts/doc-lint.mjs` | Mechanical checks over written docs: tense and history, dates, redirect stubs, frontmatter, the registry's keys and sections, index shape, owning-document body, and a doctrine folder read as a set (citations resolve; no shared objects, restated sentences, body links or `UNBUILT` markers) |
 | `scripts/source-lint.mjs` | Mechanical checks over source comments; run `--changed` before finishing any change that writes source |
 | `scripts/comment-strip.mjs` | Proof that a comment sweep changed no executable code |

package/data/harnesses/delivery/skills/documentation/references/document-sets.md

@@ -0,0 +1,95 @@
+# Writing a set of documents
+
+Load when writing or reworking more than one sibling document at once (a doctrine folder, a family of feature documents), or one doctrine document whose rules meet its siblings'. A single feature or package document needs only the steps in `SKILL.md`. One document joining an existing set runs every step below, with the existing documents as the rest of the set (§ One document into an existing set).
+
+A set written one document at a time restates itself. Each document is made self-contained, so the same rule lands in four documents in four wordings, two of them contradict, and the defects surface only on rereading, which costs more than the writing did. So the set is designed once, as data, before any prose: every rule gets one home, every concept one name, and the review reads a table, where a fix is one edit, instead of twenty documents, where a fix is a reread of every one that states the rule.
+
+## 1. Usefulness test
+
+For each proposed document, list the decisions only it would own: rules a reader would get wrong without it, each checked against the documents that exist, by a search for its distinctive phrase. A decision another document already states belongs to that document.
+
+- **Fewer than about six owned decisions:** the document is a section of a neighbour, or its rules belong in several neighbours. Fold them and drop the document.
+- **Two documents owning overlapping lists:** the boundary between them is not drawn. Redraw it or merge them.
+- **The output:** the document list, each with its owned decisions and its boundary sentence (the questions next to it, and which document answers each).
+
+## 2. Term table
+
+One row per concept: its name, a one-line definition, the one document that governs it (which lists it in `objects:`), and the synonyms it bans. The table comes before the ledger, because a rule written with two names for one concept becomes two rules.
+
+The table starts from what the existing documents already name: every sibling's `objects:` and the definitions in its Terms table (an owning document's "For the agent" objects line). A new term is checked against them before it is used, because the collision a writer cannot see is with a name a sibling already gave another concept ("consent" for a client's scope, beside a sibling's consent of a data subject).
+
+| Term | Means | Governed by | Not |
+| --- | --- | --- | --- |
+| operator | a person on the platform's own staff | authorization service | admin, staff account |
+
+## 3. Rule ledger
+
+One row per rule, from the user's rulings, the documents that exist, and the code where it states a design:
+
+| Id | Rule | Reason | Source | Home | As | Stated in | Cited by |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| R12 | A change that narrows access ends the sessions it affects | a narrowed role must not outlive its token | owner ruling 6 | auth service | principle 5 | auth service | authorization service, security |
+
+- **A source for every row:** an owner's ruling, a sibling's statement, or the code where it states a design. A rule with no source (a case the rulings leave open, a consequence the writer finds plausible) is not a row: it is a question for the user, with a recommendation, and the documents say nothing on the case until it is answered. Rules a writer supplies itself are where a written set's own defects concentrate, because no one has decided them.
+
+- **Stated in, searched, not remembered:** each row's distinctive phrase is searched across the existing documents, and every document already stating the rule is listed. The ledger's defects are mostly here: a rule the writer homes in a new document while a sibling still states it is a double home on the first read.
+- **One home per rule:** the document whose question the rule answers. A rule that seems to need two homes is resolved here, by picking one and adding the other to "Cited by". A rule a sibling already states keeps that home unless the same change edits the sibling to cite the new one; a home moves only with both edits.
+- **Contradictions resolved here:** two rows that cannot both hold are settled before any prose exists. Where one source plainly outranks the other (the owner's latest ruling over an older sibling sentence), the ledger follows it and the losing statement is a sibling edit owed; the rest go to the user in one batch with the open cases, a recommendation first for each.
+- **As:** a principle where the rule holds across the document's parts, a part's decision where it holds for one part only.
+- **Scratch, never committed:** the documents are the record, and a committed ledger would be a second copy to drift from them.
+
+## 4. Ledger review
+
+One reviewer reads the ledger and the term table, not prose: the `doc-reviewer` agent in ledger mode, with § Rubric. Without the agent, a context-free sub-agent briefed with § Rubric and the paths, never the writer itself: a writer reviewing its own ledger passes its own blind spots, and in this skill's eval a self-reviewed ledger reached the cold read carrying seven blocking findings. Fixes land in the ledger, so every document rendered after them inherits them.
+
+## 5. Render
+
+Each document is written from its ledger rows and nothing else:
+
+- **Principles and part decisions:** each rule one sentence, and its reason the next wherever the rule meets a trigger of the style guide's § Sentences.
+- **Part sections:** the rows homed as part decisions. A part with no such row gets no section.
+- **Rules homed elsewhere:** a citation with the one clause of context the sentence needs (style guide principle 7), never the rule in new words.
+- **A sentence with no row:** filler, which is cut. A rule the writer finds missing is a question for the user (§ 3), never a row the writer adds for itself.
+
+Writers may run in parallel, one sub-agent per document or per few documents. Each brief carries the ledger, the term table, the template, the style guide's § Labels, § Voice (with § Sentences and § Vocabulary) and § Net-net, the rows homed in its documents, and the instruction to write only its own files. Each writer returns paths, not prose.
+
+## 6. Lint
+
+`doc-lint` over the folder. Block findings are fixed. Each `sibling-duplicate` warning is a restatement the ledger did not ask for, or a row the ledger missed; fix it in the document.
+
+## 7. Review
+
+One cold read of the set by the `doc-reviewer` agent in docs mode, with § Rubric. Its brief carries the paths and nothing of the session, because a reader who saw the session already knows every undefined term. Without the agent, a context-free sub-agent briefed with § Rubric does the read.
+
+- **BLOCKING findings:** fixed.
+- **NITs:** reported to the user as one list, never looped on.
+- **After the fixes:** the changed lines only are verified: re-lint, and re-read each citation a fix touched. A fix never adds an unsourced rule: a finding that needs a decision the sources do not make (a Two readings the rulings left open) narrows the sentence to what the sources say and goes to the user as a question. There is no second full cold read: a review that keeps finding new BLOCKING items is reading prose the ledger never governed, so the fix is to the ledger and a re-render of the documents it touches.
+
+## One document into an existing set
+
+- **The siblings are the set:** the term table and the ledger are built against them (§ 2, § 3), and the cold read reads the new document against them.
+- **A fix that belongs in a sibling is made in the sibling,** in the same change: a rule whose home moved, a term renamed, a principle that now has an exception. Where the sibling is outside the change's scope, the fix is reported to the user as a sibling edit owed, never absorbed by restating the rule in the new document.
+- **A contradiction with a sibling's principle** is never settled by the new document alone: it is an exception the sibling's principle must cite, or a question for the user.
+
+## Rubric
+
+A finding names the file and line, quotes the text, names its class, and proposes the fix. "Could be clearer" with no fix is not a finding.
+
+**BLOCKING:** the set is wrong, or unreadable as a set, until fixed.
+
+| Class | The defect |
+| --- | --- |
+| Contradiction | Two statements that cannot both hold, in one document or across two |
+| Double home | A rule stated, not cited, in two documents, or twice in one |
+| Wrong citation | A citation whose target does not say what the citing sentence claims (the lint checks that it exists; the reader checks what it says) |
+| Split term | Two names for one concept, or one name for two |
+| No decision of its own | A document under about six owned decisions; a section, table or bullet that states nothing the principles do not |
+| Missing reason | A rule that meets a trigger of the style guide's § Sentences (a tempting alternative, a cost, an arbitrary value, an invisible failure) and carries no reason |
+| Filler | A sentence carrying no fact, rule, boundary or reason: a scene-setting opener, a generic truth used as framing, a metaphor or slogan standing in for a rule, a question |
+| Wrong layer | Mechanism, a product's specifics or build state in doctrine; history in a truth document |
+| Fused reason | A rule and its reason joined into one sentence, so a reader cannot tell which half binds |
+| Two readings | A rule a reader could act on in two incompatible ways |
+
+**NIT:** wording, order, a label, a sentence that could be shorter, a plainer synonym for a standard term, a cross-reference that would help. NITs never block.
+
+In ledger mode the same classes apply to rows: two rows that contradict, a rule homed twice, a term used in two senses, a document left with fewer than about six rows, a row without its reason or without its source, a rule homed in a document whose question it does not answer.