@nurix/etna 0.20.40 → 0.20.42

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

@@ -7,18 +7,20 @@ This guide states how a document is written: every file under `docs/` and every
 
 ## The model
 
-A document is read by a person who wants to understand something or to act on it, and it is scanned more often than it is read. Every rule below follows from eight principles; later sections cite them by number.
+A document is read by a person who wants to understand something or to act on it, and it is scanned more often than it is read. Every rule below follows from ten principles; later sections cite them by number.
 
 ### Principles
 
 1. **Three natures:** every document is a truth document (what is, now, rewritten in place), a record (what happened, dated and frozen) or a queue (work not done yet, rows appended and deleted when resolved). A truth document never narrates history, a record is never edited to match the present, and a queue holds only open rows, because a reader must be able to trust each without the others.
-2. **The outside-in shape:** an explaining document opens on the question it answers and its boundary, then the model with its numbered principles, then the parts and their relations, then each part's decisions, and stops at its genre's deepest layer. Each layer is complete on its own, so a reader who stops at any layer holds a picture that is coarse but true, never a teaser the next section completes.
+2. **The outside-in shape:** an explaining document opens on what it defines and its boundary, then the model with its numbered principles, then the parts and their relations, then each part's decisions, and stops at its genre's deepest layer. Each layer is complete on its own, so a reader who stops at any layer holds a picture that is coarse but true. Headings name the concept a section covers, never the layer it sits in.
 3. **The stability test:** a sentence that would have to change when a function is renamed, a file moves, a route, column, error code or cookie attribute changes, or a constant is retuned without the design changing belongs to the code, which the code graph computes on demand (`docs/architecture/systems/knowledge-layer.md`), and not to the document. A copy typed into a document is at best a duplicate of the code and at worst a stale one.
-4. **The authority split:** the code is the authority on *what*; the document is the authority on *why*. A disagreement on *what* means the document is stale and the code wins; a disagreement on *why* or on an invariant is a defect to raise, because one side is wrong on purpose.
+4. **The authority split:** the code is the authority on *what*; the document is the authority on *why*. A disagreement on *what* means the document is stale and the code wins; a disagreement on *why* or on an invariant is a defect to raise, because one side is wrong on purpose. Doctrine is the one exception: it is a specification, so code that differs from it has a gap to plan and build (`templates/doctrine.md`).
 5. **Noun-phrase labels, third-person sentences:** every heading and every bold bullet label names something and contains no finite verb, so it carries no tense, person or voice. The sentence after a label is third person, present tense, active, with the actor as its subject.
-6. **A body scanned by people, a footer for the agent:** an owning document is bullets under noun-phrase headings, tables wherever the cases are parallel states, code named only where a person types or sees it or at a cross-cutting seam, and a closing "For the agent" footer that holds pointers, never an inventory.
+6. **A body scanned by people, a closing for the pointers:** an owning document is bullets under noun-phrase headings, tables wherever the cases are parallel states, code named only where a person types or sees it or at a cross-cutting seam, and a closing that holds pointers, never an inventory: "For the agent" in an owning document, Terms and Related documents in a doctrine document.
 7. **Self-contained, never padded:** the body reads whole without opening another file, restating the one sentence of context a borrowed concept needs and citing the authority for the rest. Length is a signal of a document that has let mechanism in, never a target.
 8. **Depth per genre:** doctrine stops at decisions and reasons, a system at behaviour across packages, a package at its public contract, a feature runs deepest at its end in Promises, and a reference document or runbook keeps full detail because the detail is its content.
+9. **Every line owns a decision:** a line earns its place by stating a rule, a reason, a boundary or a promise a reader would otherwise get wrong. A line restating a rule that has a home is a citation instead, and a line stating nothing is cut, because restatements drift apart and filler buries the rules a reader came for.
+10. **Standard terms, one rule per sentence:** a sentence uses the term engineers use for the thing, states one rule, and stops. Its reason, where the rule needs one (§ Sentences), is the next sentence. A plainer synonym reads as vague, and a rule fused with its reason hides which half binds.
 
 ## The genres
 
@@ -29,14 +31,14 @@ Every genre takes the same shape (principle 2) and the same labels (principle 5)
 | Doctrine (`docs/architecture/common/`) | Truth | The decisions behind each part and the reasons for them | Any mechanism. A doctrine document describes no code |
 | System (`docs/architecture/systems/`) | Truth | The machine's behaviour across packages: the order it runs in, sequence and state diagrams at role level, the invariant at each place where parts meet, what re-drives a stall. No single file shows a cross-package flow, so this layer earns its place | Per-function steps, tables and columns, routes |
 | Package (`docs/architecture/packages/`) | Truth | The public contract a consumer touches: commands and their flags, exports, what is installed and where. For a CLI the flags *are* the promise | Internal layout, the build's steps, which file holds what |
-| Feature (`docs/features/`) | Truth | The behaviour a person meets, in full: each state the surface can be in, each edge case, what a refusal tells them, the wording where the wording is promised. This genre runs deepest toward its end, in Promises, because a promise is checked by a person or a test and the code cannot state it as intent | Columns, routes, guards, functions, files |
+| Feature (`docs/features/`) | Truth | The behaviour a person meets, in full: each state the surface can be in, each edge case, what a rejection tells them, the wording where the wording is promised. This genre runs deepest toward its end, in Promises, because a promise is checked by a person or a test and the code cannot state it as intent | Columns, routes, guards, functions, files |
 | Reference (API reference, environment registry) | Truth | The contract itself: signatures, shapes, variables | Nothing. The detail is the point |
 | Operations procedure, migration runbook | Truth, record | The exact commands, in order, with their expected output | Nothing. The detail is the point |
 | Record (plan, changelog entry, runbook) | Record | Its template's fields, as of the moment it describes | Nothing. Its prose follows § Voice and § Labels; the dates and the journey are its own |
 | Queue (backlog, journal, bookkeeping, memory) | Queue | One row per open item, in its template's row grammar | Nothing. A row may carry its own date; a resolved row is deleted |
 
 - **Owning documents:** feature, package and system are the three genres that speak for code: source files name them in their headers, and the ownership scan resolves paths to them (`frontmatter.md`). They take principles 5 and 6 in full, their sections are fixed (§ Owning documents — the body and the footer), and `doc-lint` reads them. A UX document also speaks for a surface's components where none of the three does; its sections are its own genre's (`templates/ux-behavior.md`).
-- **Doctrine:** the same shape and labels as an owning document, speaking for no code and describing no mechanism. Its model layer may argue in paragraphs; below the model it is bullets like every other explaining document.
+- **Doctrine:** the same shape and labels as an owning document, speaking for no code and describing no mechanism. Each section opens with a definition or the governing rule, never a lead-in, and continues in bullets like every other explaining document.
 - **Reference documents and procedures:** the one place a signature, a shape, a variable table, a command list or a file path is the content. They keep the detail the owning genres hand to the graph (§ Reference documents).
 - **Indexes:** a folder's `Readme.md` describes directories, never files — no link, filename or record ID per file; each file's own `description:` frontmatter is its account. The root README follows `templates/root-readme.md`. Both take § Labels.
 
@@ -46,20 +48,22 @@ Every truth document a person reads to understand something is written from the
 
 ### The layers
 
-1. **The question and its boundary:** the first paragraph says what question this document answers, and which neighbouring documents answer the questions next to it. No addresses, file paths or configuration in it.
-2. **The model:** what the thing is, in a page: the parties or parts, the one or two axes that organize them, and the invariants that hold everywhere, numbered, each with its reason, so later sections cite them ("principle 3").
+1. **The definition and its boundary:** the opening states what the document defines, then what is in scope and what is out of scope, each out-of-scope item pointing to the document that owns it. No scene-setting before it, and no addresses, file paths or configuration in it.
+2. **The model:** what the thing is, in a page: the parties or parts, the one or two axes that organize them, and the invariants that hold everywhere, numbered so later sections cite them ("principle 3"), each with its reason where the rule needs one (§ Sentences).
 3. **The parts:** one table or diagram placing every part in the model, then how the parts relate: what they share, where they meet, what keeps them apart.
-4. **Each part in turn:** for each part, the decisions it rests on and why. A part's section opens with why the part exists, never with how it is built.
+4. **Each part in turn:** for each part, the decisions it rests on and why. A part's section opens with its definition or its governing rule, never with how it is built.
+
+Each layer is carried by sections named for their concepts: "Callers", "Principles", "Credential families", "Capability links". A heading never names the layer itself: no "The model", "The parts", "In depth" or "Overview".
 5. **The genre's deepest layer:** the row for the genre in § The genres, and nothing deeper.
 
 An owning or doctrine document's fixed sections carry these layers; nothing is added beside them to hold a layer:
 
 | Layer | Feature | System | Package | Doctrine |
 | --- | --- | --- | --- | --- |
-| The question and its boundary | Goal line, Scope | Opening paragraph, Scope | Identity and goal lines, Scope | Opening paragraph |
-| The model | Scope's Covers bullet | Flow's opening | Usage's opening | The model |
-| The parts | Flows | Flow | Ownership, Usage | The parts |
-| Each part's decisions | Decisions | Decisions | Decisions | The parts in depth |
+| The definition and its boundary | Goal line, Scope | Opening paragraph, Scope | Identity and goal lines, Scope | Opening sentence and scope bullets |
+| The model | Scope's In scope bullet | Flow's opening | Usage's opening | The participant sections, then Principles |
+| The parts | Flows | Flow | Ownership, Usage | The parts table and its relations |
+| Each part's decisions | Decisions | Decisions | Decisions | One section per part |
 | The deepest layer | Promises | Promises | Promises | — |
 
 ### The stability test
@@ -71,16 +75,16 @@ The test (principle 3) decides what a sentence may say. These survive it:
 - **Decisions:** the choice made, and the alternative a reader would reach for.
 - **Promises:** what a person or a test can check.
 - **Cross-component contracts:** what no single file shows, such as two clients that must classify the same answer identically.
-- **Decided-but-unbuilt intent:** what the code cannot reveal because it does not yet do it, wrapped in `<!-- UNBUILT:START — {what, and the evidence it is not built} -->` … `<!-- UNBUILT:END -->` in plain words. A design decided *against* carries no marker.
+- **Decided-but-unbuilt intent:** outside doctrine, what the code cannot reveal because it does not yet do it, wrapped in `<!-- UNBUILT:START — {what, and the evidence it is not built} -->` … `<!-- UNBUILT:END -->` in plain words. A design decided *against* carries no marker.
 
-Unbuilt work has one home per kind. Decided design the code does not do yet is an `UNBUILT` block where the design is stated; a shortfall in what is built (a promise the code does not keep, a case it mishandles) is one bullet under Gaps; the work that would close either is a backlog row, and the document never tracks that work's progress.
+Unbuilt work has one home per kind. A doctrine document carries none of it, because it specifies every product and records no product's build state. Elsewhere, decided design the code does not do yet is an `UNBUILT` block where the design is stated; a shortfall in what is built (a promise the code does not keep, a case it mishandles) is one bullet under Gaps; the work that would close either is a backlog row, and the document never tracks that work's progress.
 
-The authority split (principle 4) is stated once, where agents enter the docs (the root instruction file or `docs/README.md`), so a reader who finds the code and the document disagreeing knows which way to resolve it. A doctrine document restates it in its opening, as the authority sentence (`templates/doctrine.md`), where its readers would otherwise not know; a feature, package or system document never does, because its opening is fixed to its goal.
+The authority split (principle 4) is stated once, where agents enter the docs (the root instruction file or `docs/README.md`), so a reader who finds the code and the document disagreeing knows which way to resolve it. A doctrine document states its exception in its opening, as the specification sentence (`templates/doctrine.md`), where its readers would otherwise apply the default; a feature, package or system document never restates the split, because its opening is fixed to its goal.
 
 ### Diagrams and length by layer
 
 - **A diagram's layer:** at the model and parts layers a diagram names roles ("the browser", "the auth service"), never a URL, a header or a file. A diagram drawn from the code's names belongs to the code graph.
-- **Length as a signal:** a document whose reference tail is longer than its body is an inventory with an introduction. A doctrine document past about three hundred lines has usually let mechanism in; the per-genre expectations are each template's.
+- **Length as a signal:** a document whose reference tail is longer than its body is an inventory with an introduction. A doctrine document past about two hundred and fifty lines has usually let mechanism or restatement in; the per-genre expectations are each template's.
 
 ## Labels
 
@@ -115,10 +119,63 @@ The sentence after a label, and every sentence of running prose, describes the p
 - **Concision:** "Merges server data with local changes by version", never a sentence that restates its own subject twice. A function or a command is described by what it does ("Fetches data from the server", "Returns an array"), never by what it "is used to" do and never in the passive ("an array is returned").
 - **Bold:** marks a bullet's label or a defined term's first appearance, never a noun mid-sentence.
 - **Em-dash:** a budget of one per paragraph, never a joint between clauses.
-- **Terms of art:** introduced in plain words the first time they appear, the term itself in parentheses where a reader will meet it elsewhere.
 - **Inline code:** every identifier, filename, command, flag, environment variable and config key a document names is in backticks. Where a document may name code at all is § Owning documents — the body and the footer and § Reference documents.
 - **Decoration:** ❌ / ✅ only inside banned/blessed lists and comparison tables, never as general decoration; no emoji in headings.
 
+### Sentences
+
+The reader is an engineer deciding what to build or checking what was built, so a sentence earns its place by carrying a fact, a rule, a boundary or a reason (principle 9). The test for any sentence: deleted, does the reader lose one of those? If not, it is cut.
+
+- **One rule per sentence:** the rule is the sentence. Its reason, where it has one, is the next sentence, never joined to it by *so*, *so that*, *because* or *which means* (principle 10).
+- **Reasons where a rule needs one:** a rule takes a reason when any of four holds, because a rule with no reason reads as a preference and leaves a disagreement nothing to argue with:
+
+  | Trigger | Example |
+  | --- | --- |
+  | The alternative is tempting: an engineer would reasonably do otherwise | retrying a failed signed token as a lookup; adopting an account by an unverified email |
+  | The rule costs something: friction, or a feature someone will ask for | no password-only administrators; a step-up prompt; no forced rotation |
+  | The value looks arbitrary: a number or a cutoff | a fifteen-minute window; a twenty-four-hour overlap |
+  | The failure is invisible: an attack or a drift no user or test would notice | a timing leak; an account takeover; data crossing organizations |
+
+  No reason is owed by a definition, by a rule a cited principle already justifies (the citation is the reason), or where the only reason restates the rule ("this keeps things secure").
+- **The reason's size:** one sentence, after its rule, naming the concrete failure the rule prevents: "A cross-site page otherwise makes the browser send its cookie." Alternatives weighed and the argument behind a choice belong to an architecture decision (`decisions/`), which the document cites; the document carries the conclusion and its one line of why.
+- **Length:** about twenty-five words at most, one idea each. A sentence listing three or more items introduces them with a colon, in parallel form, and is the one exception.
+- **Statements, not modals:** a document states what happens ("the request is rejected"), never what must or should happen; its statements are requirements by being in it. "Never" marks a hard boundary, sparingly.
+- **Declaratives only:** no questions, rhetorical or otherwise, and no *imagine*, *consider* or *suppose*.
+- **Specific over general:** the concrete thing, never an abstract stand-in: role, credential, route, not power, proof, door.
+- **No rhetoric:** no scene-setting opener, no generic truth used as framing, no metaphor, aphorism, personification, or phrasing inverted or balanced for effect, and no hedging (*generally*, *typically*, *in most cases*). State the rule and list its exceptions.
+
+| ❌ Cut | Why | ✅ Keep |
+| --- | --- | --- |
+| "Every product on the enterprise plane must know exactly who is calling before it does anything else." | A truth no reader doubts, naming nothing, written to introduce the next sentence | "This document defines how a product identifies the caller of every request: one principal per request, step-up verification for sensitive actions, bounds on agent runs, and the credentials a product verifies itself." |
+| "A key that makes keys turns one leak into unlimited keys, so a person's API key cannot mint keys." | Reason and rule fused, the rule last | "A person's API key cannot list, mint or revoke API keys. A credential that can mint credentials turns one leak into an unbounded set." |
+| "the one caller whose next act nobody wrote down in advance" | Personification standing in for a definition | "An agent run is a job in which a model selects the next step." |
+| "Many proofs, one person" | A balanced slogan in place of the rule | "**One principal per person:** handlers see the same principal however the person authenticated." |
+
+### Vocabulary
+
+A document uses the term engineers use. A plainer synonym reads as vague and an elegant one as literary, and either one reads as a second concept (principle 10).
+
+| Use | Not |
+| --- | --- |
+| verify, validate | prove, check, where verification is meant |
+| reject, deny; rejection | refuse; refusal |
+| resolve (a principal) | turn into, become |
+| mint, issue (a credential) | create, make |
+| route, endpoint | door, gate, page |
+| permission, role | power, authority |
+| origin, same-origin | the product's own site or pages |
+| timestamp, recency | how recently, when it was last |
+| constant-time comparison | a compare that leaks nothing |
+| step-up verification | a fresh sign-in, proving it again |
+| revoke | withdraw, kill (a credential, session or link) |
+
+- **One term, defined once:** a term is defined once (in a doctrine document's Terms table, at its first appearance elsewhere) and used unchanged after; it is never varied for style.
+- **"Doctrine" in prose:** the word is the genre's tooling name (`type: doctrine`, the template, the folder). A doctrine document calls itself "this document" or "this specification", and its neighbours "related documents".
+
+### Reach and lint
+
+§ Sentences and § Vocabulary bind doctrine and owning documents; records and queues take § Vocabulary and the person and tense rules. On a doctrine document `doc-lint` warns `modal-verb` (*must*, *should*, *shall* outside a quotation), `question` (a question mark in prose), `long-sentence` (past twenty-five words, a colon list exempt), `vague-term` (a word in the Not column above) and `doctrine-word` (the genre name in prose). A fused reason and rhetoric are judgment, and they are the cold read's (`document-sets.md` § Rubric).
+
 ## Owning documents — the body and the footer
 
 A feature, package or system document is scanned more than read (principle 6). It takes the shape (§ Shape — the model first, the detail after) and the labels (§ Labels) above, and these rules.
@@ -137,11 +194,11 @@ Nothing else. A "Why it exists" section has no place; its content is Scope or De
 
 - **The opening:** the goal is the first paragraph under the title, after the one identity line a package carries. No plan link and no routing line above it.
 - **Bullets:** each section is bullets under a noun-phrase heading; each bullet is a bold noun-phrase label, a colon, then one or two plain sentences saying what happens, what is decided or what is promised.
-- **Tables:** a table replaces the bullets wherever the cases are parallel states, such as each refusal and the exact message it shows. Its header cells are noun phrases.
-- **Paragraphs:** right for the goal, for a system's opening definition, and for a doctrine's model that needs an argument. Everywhere else, a paragraph is bullets that have not been cut yet.
+- **Tables:** a table replaces the bullets wherever the cases are parallel states, such as each rejection and the exact message it shows. Its header cells are noun phrases.
+- **Paragraphs:** right for the goal, for a system's opening definition, and for the one- or two-sentence definition that opens a section. Everywhere else, a paragraph is bullets that have not been cut yet.
 - **Code in the body:** named only where a person types or sees it (a page, a command, a flag, an environment variable) or at a cross-cutting seam the graph would not lead a reader to from the feature's own files: a middleware, a gate, a hook, a scheduler tick, a shared store holding part of the feature's logic because that logic is global. Written once, by name, where the narrative leaves the feature. Everything else is a plain name: "the device registry", "the sign-off page", "the mirror". `doc-lint` warns `body-identifier` past three identifiers in a section.
 - **Flows:** describe behaviour, never mechanism. A flow bullet says that a forgotten machine comes back on its next call, never which function re-mints the row. Behaviour in plain words is intent made legible; columns, routes, guards and signatures are the graph's.
-- **Promises:** the deepest section of a feature document: every state, edge case and refusal, and the exact wording where the wording is promised, each checkable by a person or a test. A promise reads "a removed membership shows a panel, not a redirect", never which route answers it.
+- **Promises:** the deepest section of a feature document: every state, edge case and rejection, and the exact wording where the wording is promised, each checkable by a person or a test. A promise reads "a removed membership shows a panel, not a redirect", never which route answers it.
 - **Gaps:** a gap the code does not close is one bullet under Gaps, or a backlog row. It is never a ledger row inside another section, and never a temporal hedge.
 
 ### The footer
@@ -186,14 +243,45 @@ Every document is a truth document, a record or a queue (principle 1); `SKILL.md
 
 Worked example of the strip-and-relocate move: [`examples.md`](examples.md) Example 6.
 
+## Net-net — what earns a line
+
+A document fails its reader less often by being wrong than by burying its rules under what it repeats (principle 9). The failure arrives one reasonable sentence at a time: each restatement helps where it stands, and the set reads as noise.
+
+### The line test
+
+- **A decision of its own:** the line states a rule, its reason, a boundary or a promise, and a reader without it would act differently. Otherwise it is cut.
+- **One home:** before a rule is stated, the document and its neighbours are searched for it, by a distinctive phrase. Found, it is cited ("(auth, principle 3)") with the one clause of context the sentence needs (principle 7), never restated in new words.
+- **Once inside the document:** a part's section carries the decisions its principles do not state; a principle repeated as a bullet below it is a duplicate wearing a label.
+- **One name per concept:** a concept keeps the one name the document set gave it (the term table in `document-sets.md`, or the `objects:` list for a single document); a synonym reads as a second concept.
+
+### What fails it
+
+| ❌ | Why it fails | ✅ |
+| --- | --- | --- |
+| "The lock exists so that an unvetted organization can look around without creating anything." | Announces a purpose the next bullet states | "**Locked:** signs in and reads; creates and runs nothing." |
+| A parts table whose every row reads "see principle 4" | Places nothing | No table |
+| A Relations bullet restating principle 2 in other words | A second statement that will drift from the first | Cut, or cite principle 2 |
+| A doctrine document whose every rule had a home elsewhere: attribution, key custody, a budget rejection, outbound deadlines | Owns no decision of its own | Each rule moved to its home; the document deleted |
+| A rule stated in two sibling documents in different words | A reader cannot tell which binds, and the two drift | One home, one citation |
+| A table of states, then a bullet per state restating its row | Every rule is stated twice, a page apart | The table for what each state allows; bullets only for the reasons |
+| "Security matters at every layer." · "This section describes how…" | A truism and a ceremony: no decision | Cut; the heading already names the section |
+
+### Port hygiene
+
+A document that changes scope (one product's design lifted into platform doctrine, or doctrine applied to one product) has every product name, setting value, code root, build state and product-specific example rewritten for the new scope or cut. Left in place, the residue reads as a rule binding every reader.
+
+### Proof
+
+On a doctrine folder, `doc-lint` catches the mechanical half: a restated sentence (`sibling-duplicate`), a concept two documents govern (`objects-shared`), a citation to a principle or heading that does not exist (`citation-unresolved`), a purpose opener (`purpose-opener`). The rest is judgment, and it takes one cold read (`document-sets.md` § Review).
+
 ## Self-contained documents and the link surface
 
 Instruction files stay lean because an agent pays for them on every load (`instruction-style.md`); a document is read on demand, so it carries what its reader needs to understand the page (principle 7).
 
 - **Completeness:** the one or two sentences of context a borrowed concept needs are restated where it is used, because a reader forced mid-paragraph into a second document loses the thread of the first.
 - **Restatement and citation:** a changing detail (a version, a count, a path list) keeps one canonical home; the restatement carries what the page needs and points at the authority for the rest. Link-don't-copy governs where a fact is *owned*, not how readable the page that uses it must be.
-- **Inline links:** the minimum that action requires. A link mid-prose is right only where the reader must go there to act on this page, which includes a Scope section's "Not here" pointers.
-- **The closing link surface:** every other sister document belongs in the document's one closing section: "For the agent" (its neighbours line) in an owning or doctrine document, "Related" elsewhere. Deep relative paths (`../../../../…`) are fragile, since a folder move breaks every one, so they are confined to that block; body mentions use the plain name ("the boundary skill", "`structure.md`").
+- **Inline links:** the minimum that action requires. A link mid-prose is right only where the reader must go there to act on this page, which includes the out-of-scope pointers in a Scope section or a doctrine document's opening.
+- **The closing link surface:** every other sister document belongs in the document's one closing section: "For the agent" (its neighbours line) in an owning document, "Related documents" in a doctrine document, "Related" elsewhere. Deep relative paths (`../../../../…`) are fragile, since a folder move breaks every one, so they are confined to that block; body mentions use the plain name ("the boundary skill", "`structure.md`").
 
 ## Diagrams
 

package/data/harnesses/delivery/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/delivery/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/delivery/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/delivery/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