@nurix/etna 0.20.39 → 0.20.41

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,126 @@ 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$/;
+// 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 (/^##\s+For the agent\b/.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 }) => /^##\s+For the agent\b/.test(line));
+  const body = footerAt === -1 ? lines : lines.slice(0, footerAt);
+
+  // 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 body)
+      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 "For the agent"', excerpt: line.trim().slice(0, 90) });
+  }
+  // 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/doctrine.md

@@ -4,20 +4,23 @@ Truth document. Use for **one concern the platform handles everywhere**: authent
 
 **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 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 opening (the question, the boundary, and the specification 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:**
+**Optional, each only with something the principles do not already say:**
 
-- an `UNBUILT` block for decided-but-unbuilt intent
+- **The parts**: one table or diagram placing the parts in the model, where there are enough parts that a reader needs them placed, then **Relations** where two parts meet in a way no principle states
+- **The parts in depth**: one section per part that carries decisions of its own
 
-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.
+Nothing else: the neighbouring documents live in **For the agent**, the one closing link surface, and the body names them in plain words with no link (`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
 ---
@@ -33,7 +36,7 @@ objects: [principal, credential, device grant]   # required — the concepts thi
 
 {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 specification sentence, verbatim, with the scope named: "This document is the specification of its concern for every product on {the scope, e.g. the enterprise plane}. A product whose code differs from it has a gap to plan and build; a disagreement with a principle or its reason is raised against this document, never settled silently in code."}
 
 ## The model
 
@@ -51,26 +54,26 @@ objects: [principal, credential, device grant]   # required — the concepts thi
 
 ### 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.}
+{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. A rule another doctrine document owns is cited — "(auth service, principle 5)" — never restated as a principle here.}
 
-## {The parts, as a noun phrase — e.g. "Credential families"}
+## {The parts, as a noun phrase — e.g. "Credential families"} (optional)
 
-{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.}
+{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 "Relations": 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 in depth, as a noun phrase — e.g. "Families in depth"}
+## {The parts in depth, as a noun phrase — e.g. "Families in depth"} (optional)
 
 ### {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.}
+{The decisions this part rests on that no principle states, as bullets — a bold noun-phrase label, then the rule and its reason — citing principles by number. No opener saying the part exists or what it is for; the first bullet is its first decision. A part with nothing beyond its principles gets no section. A sequence diagram at role level where the part is a flow.}
 
 ## 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.}
+{Pointers, not an inventory: the objects with one line each; any cross-cutting seam by name; the neighbouring doctrine with a purpose each, linked. No code roots: the doctrine binds every product, and each product's code is found through the documents that name it.}
 ```
 
-### 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
 
@@ -80,3 +83,5 @@ Code cannot reveal what it does not yet do, so decided-but-unbuilt intent is one
 | 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 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nurix/etna",
-  "version": "0.20.39",
+  "version": "0.20.41",
   "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": "dffbc8593fdd"
+  "etnaFingerprint": "f22341cd281e"
 }