@nurix/etna 0.20.25 → 0.20.26

package/data/harnesses/delivery/agents/maintenance.md

@@ -95,8 +95,6 @@ Run `git log --since="2 weeks ago" --name-only --pretty=format:"%h %s"` to find
 
 **Unowned paths.** Compare the repo's actual top-level source directories (derive them — the top-level dirs that contain code, or the roots named across the `owns:` globs; do not assume `src/`) against the `owns:` map. Report directories no `owns:` glob covers.
 
-**Stale greenfield self-label.** If `structure.md` asserts the repo is greenfield — _"No source code or feature docs exist yet"_ or similar — **but a real source tree exists** (the derived source roots above are non-empty, e.g. a populated `packages/` of real workspaces), the self-label has gone stale. Raise it as a question (e.g. `structure.md says "No source code exists yet" but packages/ holds 5 workspaces — confirm the greenfield label should be retired`).
-
 **Architecture drift.** Grep `docs/architecture/` for file-path references. Verify referenced paths still exist. Remove or update stale references.
 
 **Backlog health.** Read `docs/history/backlog.md`. Report items older than 30 days. Count pending by priority.
@@ -117,7 +115,7 @@ For an unowned code **region**, append: `- **[P2]** No feature doc owns \`{dir}/
 
 ### Step 6: Report & update tracking
 
-1. Update `docs/structure.md` Health Log with today's date and summary — **append to the end**, never date-sorted into the middle. Rows are positional: one may say "the row above is…", and an inserted row silently breaks that reference. A Health Log entry is a **generated row, not a narrative essay**: one line — date · counts (stale docs fixed, dead globs, unowned paths, backlog items created) · links to anything that needs a human.
+1. Append today's row to `docs/history/health-log.md` — **append to the end**, never date-sorted into the middle. Rows are positional: one may say "the row above is…", and an inserted row silently breaks that reference. A Health Log entry is a **generated row, not a narrative essay**: one line — date · counts (stale docs fixed, dead globs, unowned paths, backlog items created) · links to anything that needs a human.
 2. Update `docs/memory/maintenance.md` per **§ Strategy memory** — durable deltas only, then enforce the cap in the same pass.
 3. Report findings: stale docs, broken ownership, unowned code, architecture drift, backlog health.
 
@@ -132,7 +130,7 @@ Baseline mode converges the repo's `docs/` to the **installed** harness shape, t
 ```
 docs/
 ├── README.md            ✱ # Documentation root — quick links, section index
-├── structure.md         ✱ # Authority map + frontmatter `harness-version` (you own this field)
+├── structure.md           # Harness-owned authority map — the installer writes it on every refresh; you stamp only `harness-version`
 ├── architecture/          # Cross-module design + steering layer
 │   │                      #   domain-model, glossary, non-goals, references, open-questions
 │   └── decisions/         # Architecture Decisions (ADs — one per subject, updated in place; journey in each AD's Decision Changelog)
@@ -156,7 +154,7 @@ docs/
 └── tests/                 # Behavioral test checklists ({feature}.md, step → **Assert**), derived at plan Completion via the `documentation` skill; author-maintained
 ```
 
-**✱ marks the five scaffolded files — the only paths a baseline creates, and the only shape signals.** Every **folder** in this tree is created on first use and is simply absent until it holds a file; git cannot track an empty directory, so a missing folder is never evidence of drift and is never scaffolded to satisfy the shape. Record its role in `docs/structure.md` instead.
+**✱ marks the scaffolded files — the only paths a baseline creates, and the only shape signals.** `docs/structure.md` is not one of them: the installer owns it and rewrites it on every install or refresh, so a missing or hand-edited `structure.md` means the harness needs refreshing (`npx @nurix/etna`), never a scaffold from a template — and its body is never converged, only its `harness-version` field stamped. Every **folder** in this tree is created on first use and is simply absent until it holds a file; git cannot track an empty directory, so a missing folder is never evidence of drift and is never scaffolded to satisfy the shape. Its role is already in `docs/structure.md`; a repo's own notes about legacy folders go in `docs/README.md` § Notes for this repository.
 
 There is **no `docs/routing.md`**, **no `docs/modules/{m}/`**, **no `docs/pillars/`**, **no `docs/boundaries/`**. Code ownership lives in feature `owns:` frontmatter; a module is a `module:` label, not a folder; boundaries are diagnosed from source; brainstorm records live in `docs/research/` (active) and `docs/history/brainstorms/` (harvested).
 
@@ -192,7 +190,7 @@ B2 folds artifacts whose **shape dissolved** — a file in the wrong place or th
 
 | Nature | Genres | Treatment |
 | --- | --- | --- |
-| **Truth document** | features, ux, architecture, operations, `docs/tests/` checklists, `structure.md`, READMEs | **Converge in place.** These state what is true now, so rewriting them to the current schema is not revision, it is the genre working as designed. Add missing frontmatter keys, add missing required sections, rename keys the template renamed |
+| **Truth document** | features, ux, architecture, operations, `docs/tests/` checklists, READMEs (never `structure.md`, which the installer owns) | **Converge in place.** These state what is true now, so rewriting them to the current schema is not revision, it is the genre working as designed. Add missing frontmatter keys, add missing required sections, rename keys the template renamed |
 | **Record** | plans, changelog entries, migration runbooks, brainstorm records | **Never rewritten.** A completed plan and a committed entry are frozen — immutability begins at commit, and a record edited to match a newer schema stops being evidence of what happened. Report non-conformance; repair only the **living index** that points at the record (an absent `docs/history/CHANGELOG.md` row is an index defect, not a record defect, and is backfilled with a note saying so) |
 
 **Never invent content to satisfy a field.** A frozen changelog entry missing `Skills:` is missing the *judgement* that field carries, and no later session holds it — writing one is fabrication wearing a schema's clothes. Report it, backlog the pattern if it recurs, and leave the entry alone. The same restraint applies to a truth document: a genre's new section that needs knowledge the repo does not contain is raised as a question, not filled with plausible prose.
@@ -203,9 +201,9 @@ B2 folds artifacts whose **shape dissolved** — a file in the wrong place or th
 
 Table: `| File | Action | From | To | Reason |` (actions: `Move`, `Merge into {target}`, `Delete`, `Keep`, `Create`, `Fold`). For a fresh baseline this is mostly `Create`; for an upgrade it is mostly `Fold`/`Move`. Ask once: **"Approve this reconcile?"** — you own this interaction (the `documentation` skill is a library and has none).
 
-On approval, execute: create the folder structure; move/fold/merge/delete per the plan; apply B2b's schema convergences to the truth documents (records are reported, never rewritten); add `Status:` to plan files; for each feature doc, derive and write its `owns:` globs (+ `module:` label + `keywords:`) from the source it describes, and each checklist's `verifies:` edge, by calling the `documentation` skill's **frontmatter derivation**; merge scattered backlogs into `docs/history/backlog.md`; fix links broken by moves.
+On approval, execute: create the folder structure; move/fold/merge/delete per the plan; apply B2b's schema convergences to the truth documents (records are reported, never rewritten); add `Status:` to plan files; for each feature doc, derive and write its `owns:` globs (+ `module:` label + `objects:`) from the source it describes, and each checklist's `verifies:` edge, by calling the `documentation` skill's **frontmatter derivation**; merge scattered backlogs into `docs/history/backlog.md`; fix links broken by moves.
 
-Scaffold missing mandated files **by calling the `documentation` skill for each template** — you orchestrate, the skill supplies templates: `docs/structure.md` (with `harness-version`), `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/main.md`, and the repo-root `README.md` (filled from the real lockfile/scripts/layout — **never overwrite an existing root README**).
+Scaffold missing mandated files **by calling the `documentation` skill for each template** — you orchestrate, the skill supplies templates: `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/main.md`, `docs/operations/setup.md` (when the repo has a lockfile and a runnable root script; **never a second first-run doc** — propose a rename with a `note:` row if one exists under another name), and the repo-root `README.md` (an outward opening in a user's terms from the charter and vision documents, then orientation and routing filled from the manifests, the ownership index and the root scripts — **never overwrite an existing root README**).
 
 ### Step B4 — Stamp the version
 
@@ -237,7 +235,7 @@ Apply the **§ Strategy memory** retirement procedure to `docs/memory/maintenanc
 - **Enforce the memory cap on every run** (§ Strategy memory) — you are its only writer, so no one else can do it.
 - **A clean report is valid** — do not invent issues.
 - **Declarative, idempotent.** Re-running baseline mode on a current repo reshapes nothing — a second pass is just the audit plus the module proposal. Converge to the current shape; never replay a version ladder; never reconstruct a past shape.
-- **Brownfield extraction (operator-ruled 2026-08-19).** When baseline mode meets a repo with a real source tree and few or no feature docs, the module *proposal* is not enough — run the extraction pass: produce feature docs for the recognized modules (docs/features/, full frontmatter: `owns:` · `module:` · `keywords:` · `status:` · `last-reviewed:` · `type: feature` · `derivation: "extracted (baseline YYYY-MM-DD, nustack graph + source read)"`), plus the architecture, tests, and operations layers. Use the `nustack-graph` skill where installed — localize through the index before reading; the docs record intent, the index answers facts. **Every extracted feature doc carries a `## History & Ownership` section** — top contributors with recency, churn posture, and bus-factor notes, dated "as of YYYY-MM-DD" (operator ruling: this section is mandatory in extraction output even though doc-lint flags dated narrative in truth docs; the findings are accepted for now, and a future harness version may retire the section in favor of live index pointers). `status:` is evidence-graded: `deprecated` only when history shows the area dead, never by guess. Scale by fan-out (one extraction lane per module, a completeness critic over the result) rather than one long cold read.
+- **Brownfield extraction (operator-ruled 2026-08-19).** When baseline mode meets a repo with a real source tree and few or no feature docs, the module *proposal* is not enough — run the extraction pass: produce feature docs for the recognized modules (docs/features/, full frontmatter: `objects:` · `owns:` · `module:` · `status:` · `last-reviewed:` · `type: feature` · `derivation: "extracted (baseline YYYY-MM-DD, nustack graph + source read)"`), plus the architecture, tests, and operations layers. Use the `nustack-graph` skill where installed — localize through the index before reading; the docs record intent, the index answers facts. **Every extracted feature doc carries a `## History & Ownership` section** — top contributors with recency, churn posture, and bus-factor notes, dated "as of YYYY-MM-DD" (operator ruling: this section is mandatory in extraction output even though doc-lint flags dated narrative in truth docs; the findings are accepted for now, and a future harness version may retire the section in favor of live index pointers). `status:` is evidence-graded: `deprecated` only when history shows the area dead, never by guess. Scale by fan-out (one extraction lane per module, a completeness critic over the result) rather than one long cold read.
 - **Diagrams ride the baseline (operator-ruled 2026-08-24).** Whenever baseline mode produces or converges the architecture layer, draw two ASCII diagrams from the real source, each in its own fenced code block: (1) an **architecture diagram** in the system-design/architecture doc — the actual processes, entry points, and wire surfaces as boxes, the calls/queues/files between them as labelled arrows; (2) a **DB ER diagram** wherever the repo declares a relational schema (DDL, migrations, an ORM schema) — one box per table listing its key columns, FK edges drawn to the table they reference, cardinality on the edge; it lands in the domain-model doc, or `docs/architecture/data-model.md` when none exists. Box-drawing characters (`┌─┐│└┘├┤`), width ≤ 100 columns. Derived only from what the code declares — a diagram never invents a component the source does not show, and a repo with no relational schema gets **no** ER diagram rather than an imagined one. Diagrams are truth-document sections: later baselines and audits converge them in place like any other section.
 - **Tool tiers.** The SessionStart context names each manifest-declared tool with its tier; calibrate the run to it, never stall on it. **Present-fresh** (`Tool: nustack 0.9.0`): use it — localize every question through `nustack graph` before reading source, and never run an index step first: the family re-indexes a stale store before it answers, so the only freshness decision left is the deliberate `--no-refresh`. **Present-stale** (below the catalog minimum): still use it, but note the version gap and the upgrade command in the run report — a stale contract may lack answer shapes the skill assumes. **Absent** (`Tool: nustack MISSING`): fall back to the cold method (Glob/Grep/read), state in the run report that the tool was absent and give the install command — degraded output is acceptable, silent degradation is not.
 - **One sentinel.** `docs/structure.md` `harness-version` is the only baseline/version marker.

package/data/harnesses/delivery/harness.json

@@ -1,7 +1,7 @@
 {
   "harness": "delivery",
   "name": "delivery",
-  "version": "0.2.36",
+  "version": "0.2.37",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
@@ -10,5 +10,5 @@
   "seeds": [],
   "tools": [],
   "docsRoot": "docs",
-  "digest": "c2d4fb33502b"
+  "digest": "89536cdaf008"
 }

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

@@ -7,7 +7,7 @@ description: "Use when creating or substantively editing ANY markdown doc — in
 
 **This skill is a template & generator library, not an orchestrator.** It supplies the templates, the frontmatter-derivation generator, and the co-authoring workflow that _agents_ call to produce individual docs. It does **not** baseline, audit, or reconcile a repo's doc tree — that is the **`maintenance` agent (baseline mode)**, which calls this skill for each template it scaffolds. Reach here to generate _one_ doc from a template; reach for the `maintenance` agent (baseline mode) to bring a whole repo into shape.
 
-Document contracts and architecture, not implementation details. Show function signatures and API shapes — never paste full implementations (they rot fast). Use ASCII diagrams over prose for flows. Only document state at persistence boundaries (Redux persistence, DB schemas, API shapes), not component-level or transient state. Mark deprecated fields with `// UNUSED:` comments stating why the field is dead now — never where it went or when it dies. Breaking changes belong in changelogs only, not module docs.
+Document contracts and architecture, not implementation details. Signatures and API shapes belong in a reference document (an API reference, an environment registry); every other genre states design and promises and leaves mechanism to the code — never paste full implementations (they rot fast). Use ASCII diagrams over prose for flows. Only document state at persistence boundaries (Redux persistence, DB schemas, API shapes), not component-level or transient state. Mark deprecated fields with `// UNUSED:` comments stating why the field is dead now — never where it went or when it dies. Breaking changes belong in changelogs only, not module docs.
 
 ---
 
@@ -70,9 +70,14 @@ The two guarantees are complementary and both break on mixing: a reader holding
 
 - **Truth documents never narrate history** — the § Present tense, always rule above, applied to this nature. When the system changes, the change-story goes to `docs/history/` (a changelog entry) and the truth document simply becomes correct in present tense. When you find historical narration in a truth document, rewrite it to the present-tense fact and let the record carry the story.
 - **Records are never edited to match the present.** A completed plan stays wrong-in-hindsight; a changelog entry describes close-time state; a scope change gets a *new* dated record that links back, never an edit to a frozen one.
-- **Two sanctioned bridges — head is truth, tail is provenance.** An **Architecture Decision (AD)** ends with a **Decision Changelog** (for a decision, the journey — what each revision reversed and what triggered it — is part of the reasoning), and `docs/structure.md` ends with the maintenance agent's **Health Log** (tooling-stamped audit rows, the structural cousin of `last-reviewed:`). In both, the body stays current-truth-only; the tail carries the dates. No other truth document carries dated history.
+- **Two sanctioned bridges — head is truth, tail is provenance.** An **Architecture Decision (AD)** ends with a **Decision Changelog** (for a decision, the journey — what each revision reversed and what triggered it — is part of the reasoning), and the `maintenance` agent's **Health Log** lives in `docs/history/health-log.md`, an append-only record. The AD body stays current-truth-only; the tail carries the dates. No other truth document carries dated history. `docs/structure.md` is harness-owned — written whole by the installer, never edited by hand or by a skill; only its `harness-version` frontmatter is stamped, by the `maintenance` agent.
+- **Indexes describe directories, never files.** `docs/README.md` — the top-level index of the documentation folder — is a description of its directories: one entry per folder saying what the folder holds, who reads it and how its files are named. It carries no file list and no file tree: not a per-file row, not a `├──` tree of files, not a tree at all — `docs/structure.md` is the one place the tree lives, as the authority on placement. The same holds for a `README.md` / `Readme.md` at any level of `docs/`. `ls` is the roster, and the ownership index is how a document is found for a path. A per-file row has to be edited on every add, rename and retirement, so the index's history records roster churn instead of what the index said, and a reader cannot tell when the index itself changed. The only files an index may link are the mandated scaffolds (`structure.md`, `operations/setup.md`, `history/CHANGELOG.md`, `history/backlog.md`, `memory/main.md`) and a sibling folder's own `Readme.md`. `scripts/doc-lint.mjs` blocks the rest as `index-lists-files`, and blocks a tree drawn in a folder index as `index-file-tree`. An inverse (which checklists verify a feature, which docs a folder holds) is generated, never written.
 - **Truth documents cite records for the _why_, never the _when_.** `Provenance: AD-002` is good; "decided in AD-002 and shipped 2026-06-13" is not. Routing/index docs point only to truth documents as a topic's authority — never a plan or changelog entry as the "read first" source. (An index _of the records themselves_ — a History section listing `plans/`, `changelog/` — is sanctioned.)
 
+**A document is intent and promises; facts are the graph's.** An owning document (feature, package, system) answers 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 and vocabularies, a foreign key and its delete rule, which function writes which column, which route sits behind which guard, which code a refusal answers, which file holds what — is the code graph's to compute (`docs/architecture/systems/knowledge-layer.md`), and a hand-typed copy of it is the defect this rule removes: it reads as authoritative and is wrong the day the code moves. Mechanism stays in the code, reasons stay in the document, and the document points by object and symbol name, never by line number. `doc-lint` blocks the retired mechanism sections in an owning document (`mechanism-section`) and an owning document without `objects:`. `keywords:` is not a key: an object's name is its discovery term. **The body is read by people** — plain English a newcomer reads top to bottom, with code named only 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 shared store) and every other identifier in the closing **For the agent** footer; the owning genres read Why it exists · How it works · What was decided · What it promises · Known gaps · For the agent (`references/style-guide.md` § Documents are read by people; `doc-lint` warns `body-identifier`, `list-not-prose`, `formula-run`).
+
+**Every document that explains is written from the outside in, and every sentence passes the stability test.** Open on the question and its boundary, then the model with its numbered principles, then the parts and how they relate, then each part's decisions — and stop at the genre's deepest layer: decisions for doctrine, cross-package behaviour for a system, the public contract for a package, the full user-facing behaviour for a feature. A sentence that would have to 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 is the authority on *why*, and a disagreement on *why* is a defect to raise. The layers, the test and the per-genre depth table are [`references/style-guide.md`](references/style-guide.md) § Shape — the model first, the detail after.
+
 **No empty stubs.** Never leave a template section as an empty placeholder — omit any section with nothing real to say (each template declares its required core; everything else is optional). Write an explicit "None" only where the absence itself is information (e.g., a plan's Cross-Module Contracts Affected, an LLD's Ownership Conflicts). An empty table stub reads as "not yet researched"; an omitted section reads as "doesn't apply" — keep those meanings distinct.
 
 **No redirect docs.** When moving a doc to a new location, delete the old file entirely. Update all references (cross-doc links, memory files) to point to the new path. Never leave a stub file that says "Moved to X" — redirect docs rot, clutter the repo, and create false search hits.
@@ -87,6 +92,7 @@ The two guarantees are complementary and both break on mixing: a reader holding
 | Document feature/module (LLD) | [`templates/feature.md`](templates/feature.md) |
 | Document data flow / state / Redux | [`templates/feature.md`](templates/feature.md) — they are sections of the feature doc |
 | Document a workspace package (`docs/architecture/packages/{package}.md`) | [`templates/package.md`](templates/package.md) — the **residual** owner of `packages/{name}/**`: its manifest, build, entry, layout and every behavior no system or feature doc claims at higher specificity |
+| Document one concern the platform handles everywhere (`docs/architecture/common/{concern}.md`) — authentication, storage, the API protocol | [`templates/doctrine.md`](templates/doctrine.md) — the design and its principles, no mechanism; owns no code, and surfaces bind to it through `applies:` |
 | Document one system spanning packages (`docs/architecture/systems/{system}.md`) | [`templates/system.md`](templates/system.md) — one machine end to end; its `owns:` names the machine's subtrees, narrower than the package glob, so it wins by specificity. Not a screen — a system doc written as a giant feature doc is the mistake it prevents |
 | Create/update changelog entry | [`templates/changelog-entry.md`](templates/changelog-entry.md) (record — one per unit of work; carries the refinement fields, frozen inside its commit, distilled by the `retro` agent) |
 | Create/update plan | [`templates/plan.md`](templates/plan.md) (record) |
@@ -102,14 +108,16 @@ The two guarantees are complementary and both break on mixing: a reader holding
 | What a person sees and can do on a surface (UX behavior) | [`templates/ux-behavior.md`](templates/ux-behavior.md) — decides observable behavior BEFORE the code; per-surface in `docs/features/{surface}-ux.md` owning the component globs, cross-cutting in `docs/architecture/`. Not the checklist, which only verifies it |
 | Behavioral checklist for one feature (`docs/tests/{feature}.md`) | [`templates/behavioral-checklist.md`](templates/behavioral-checklist.md) — the verification gate's driving script, and the source its suite tests are drawn from |
 | Acceptance criteria for one capability (`docs/acceptance/{capability}.md`) | [`templates/acceptance-criteria.md`](templates/acceptance-criteria.md) — the promises the built product must keep, as stable `AC-n` keyed assert lines verification surfaces parse as claims |
-| Recurring procedure/setup | [`templates/operations-procedure.md`](templates/operations-procedure.md) |
+| Machine setup / first run / stack (one per repo, `docs/operations/setup.md`) | [`templates/setup.md`](templates/setup.md) |
+| Recurring procedure (develop, deploy, rotate, diagnose) | [`templates/operations-procedure.md`](templates/operations-procedure.md) |
 | Cold-start build order (implementation map) | [`templates/implementation-map.md`](templates/implementation-map.md) — authored by the executing session at build start, updated in place as waves complete |
 | Capture mid-execution knowledge (`docs/history/journal.md`) | [`templates/journal.md`](templates/journal.md) (record — append-only; a row resolves by landing in its owning doc) |
 | Bookkeeping work queue (`docs/operations/bookkeeping.md`) | [`templates/bookkeeping.md`](templates/bookkeeping.md) — machine-read row grammar; appended by hooks and sessions, drained by the `bookkeeper` agent, walled at Stop and commit |
 | One-shot migration/upgrade | [`templates/migration-runbook.md`](templates/migration-runbook.md) (record) |
+| Hand-over at the end of an unattended or multi-session build (`docs/history/handovers/YYYY-MM-DD-{slug}.md`) | [`templates/handover.md`](templates/handover.md) (record) — a decision queue, an undo manual and a resume file: a verdict token and scoreboard, the acts only the owner can take today, everything that left the repository with its exact undo, a ten-minute path to seeing it work, every ruling taken on the owner's behalf with its authority and how to overturn it; then the successor half — proof, state re-provable by command, open loops, discoveries |
 | Add to protected files | [`templates/protected-files.md`](templates/protected-files.md) |
-| Create/update root README | [`templates/root-readme.md`](templates/root-readme.md) |
-| Scaffold a standard doc (docs index, `structure.md`, CHANGELOG, backlog, memory) | [`templates/Readme.md`](templates/Readme.md) — the index names each scaffold file |
+| Create/update root README (outward opening in a user's terms, then orientation and routing for the team and agents — no install, stack, tree or chrome) | [`templates/root-readme.md`](templates/root-readme.md) |
+| Scaffold a standard doc (docs index, CHANGELOG, backlog, memory) | [`templates/Readme.md`](templates/Readme.md) — the index names each scaffold file; `structure.md` is the installer's, never scaffolded |
 | Derive/update an owning doc's `owns:` (feature, package, system) | [`references/frontmatter.md`](references/frontmatter.md) |
 | Update existing doc | § Editing an existing doc (below) |
 | Instruction file (`CLAUDE.md`, a rule, an agent, skill prose) | [`references/instruction-style.md`](references/instruction-style.md) — not these templates; every-load prose stays lean, and the present-tense rule still applies |
@@ -135,6 +143,7 @@ The two guarantees are complementary and both break on mixing: a reader holding
 | Feature (LLD) | Truth | `kebab-case.md` | Living; `status:` `draft` → `active` → `deprecated` |
 | Package | Truth | `{package-folder}.md` | Living; `status:` as the feature doc |
 | System | Truth | `{machine}.md` | Living; `status:` as the feature doc |
+| Doctrine | Truth | `{concern}.md` | Living; `status:` `draft` → `active` |
 | Architecture Decision | Truth | `AD-NNN-kebab-case.md` | Living; `Proposed` → `Accepted` → `Deprecated`; revisions rewrite the body + append to its Decision Changelog |
 | Steering docs (overview, domain model, glossary, non-goals, security, testing strategy) | Truth | fixed names | Living |
 | API reference / environment registry | Truth | fixed names | Living |
@@ -153,11 +162,13 @@ The two guarantees are complementary and both break on mixing: a reader holding
 **Frontmatter is compulsory on every document this skill authors** — `type:` (the genre) on every
 doc, plus the genre's own keys beside it; a document without its frontmatter fails the skill's
 contract and is not done. **There is no frontmatter-less genre.** A feature or UX doc carries the
-full set — `owns:` (required), `module:` (optional), `keywords:` (required), `status:` (required),
+full set — `objects:` (required — the product objects the document designs), `owns:` (required until the graph computes ownership), `module:` (optional), `status:` (required),
 `applies:` (the architecture docs it obeys; omitted when none), optional `last-reviewed:`. A
 **package** doc (`docs/architecture/packages/`) and a **system** doc (`docs/architecture/systems/`)
 carry the same set minus `module:` — a package is already a bounded unit and a machine spanning
-packages belongs to no single context. A behavioral checklist (`docs/tests/`) carries
+packages belongs to no single context. A **doctrine** doc (`docs/architecture/common/`)
+carries `type: doctrine`, `status:` and `objects:` — no `owns:`, because doctrine governs code
+without claiming it. A behavioral checklist (`docs/tests/`) carries
 `type: checklist` and `verifies:` — the doc whose promises it proves. An acceptance-criteria doc
 (`docs/acceptance/`) carries `type:` and `status:`.
 
@@ -177,7 +188,7 @@ update, and the `maintenance` agent's baseline pass, route there.
 | `templates/` | One file per template, indexed by [`Readme.md`](templates/Readme.md) — feature (LLD), changelog, plan, AD, steering docs, API reference, environment registry, operations procedure, migration runbook, protected files, READMEs, and the baseline scaffolds |
 | `references/style-guide.md` | Writing rules, formatting conventions, the two-natures tense rules |
 | `references/instruction-style.md` | The style for instruction files (`CLAUDE.md`, rules, agents, skill prose) — the every-line test, armor vs. narration, voice, negative space |
-| `references/frontmatter.md` | Deriving a feature doc's `owns:` / `module:` / `keywords:` / `status:` from code |
+| `references/frontmatter.md` | Deriving a feature doc's `objects:` / `owns:` / `module:` / `status:` from code |
 | `references/untemplated.md` | How to write a document no template covers (nature, placement, shape) + the co-authoring workflow |
 | `references/examples.md` | Good vs bad documentation examples |
 | `scripts/doc-lint.mjs` | Mechanical checks over written docs (tense narration, dates, stubs, redirects) — run over changed docs before finishing |

package/data/harnesses/delivery/skills/documentation/references/frontmatter.md

@@ -32,7 +32,7 @@ Every other genre owns no code and carries no `owns:`. That includes the cross-c
 
 ## How to derive the frontmatter
 
-An owning doc's ownership frontmatter is `owns:` (required), `module:` (optional — feature docs only; a package is already a bounded unit and a system spans contexts by definition), `keywords:` (required), and `status:` (required). An optional `last-reviewed:` date (stamped whenever the doc is substantively reviewed or updated) gives the `maintenance` agent a staleness signal to rank its audits by — it is tooling metadata, never narrated in the body. `type:` (required — the genre, enum = the template names) and `rev:` (generator-written generation stamp) are the same class: external tooling reads them, sessions **preserve them on edits** and never narrate or inject them. The `maintenance` agent stamps `type:` on docs that predate the key. `slug:` completes the set on generated docs: the identity key, minted once at creation and never re-derived from a display name — in the repo the filename is the slug, and the `maintenance` agent re-aligns the two when they diverge.
+An owning doc's frontmatter is `objects:` (required — the product objects it designs, by their graph names; its discovery terms and its traced edge into the knowledge graph), `owns:` (required until the graph computes ownership from traces), `module:` (optional — feature docs only; a package is already a bounded unit and a system spans contexts by definition), and `status:` (required). An optional `last-reviewed:` date (stamped whenever the doc is substantively reviewed or updated) gives the `maintenance` agent a staleness signal to rank its audits by — it is tooling metadata, never narrated in the body. `type:` (required — the genre, enum = the template names) and `rev:` (generator-written generation stamp) are the same class: external tooling reads them, sessions **preserve them on edits** and never narrate or inject them. The `maintenance` agent stamps `type:` on docs that predate the key. `slug:` completes the set on generated docs: the identity key, minted once at creation and never re-derived from a display name — in the repo the filename is the slug, and the `maintenance` agent re-aligns the two when they diverge.
 
 **1. `owns:`** (the path scope)
 
@@ -59,9 +59,9 @@ Glob each pattern against the codebase. At `status: active`, drop any that match
 
 The single bounded-context label this feature belongs to, or omit it for a cross-cutting feature that belongs to no single context. A module is a label, not a folder — features sharing a `module:` value are what ties that module to code (a filter over the generated ownership index). Package and system docs omit it entirely.
 
-**3. `keywords:` & `status:`**
+**3. `objects:` & `status:`**
 
-`keywords:` are the discovery terms topic→doc lookup rides. `status:` is `active`, `draft`, or `deprecated` — it steers the model toward live docs and away from draft/deprecated ones.
+`objects:` names the product objects the document designs — the discovery terms topic→doc lookup rides, and the edge the knowledge graph renders each object's documents from. There is no `keywords:` key: an object's name is its discovery term. `status:` is `active`, `draft`, or `deprecated` — it steers the model toward live docs and away from draft/deprecated ones.
 
 ## The doc → doc edges
 

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

@@ -271,6 +271,67 @@ Two verbosity regimes, split by who pays for the words. **Instruction files** (`
 - **Inline links are the minimum that action requires.** Link mid-prose only where the reader must go there to act on this page. Every other sister document — everything the topic touches — belongs in one **Related** (or **References**) section at the document's end.
 - **The Related tail is the document's entire link surface.** Deep relative paths (`../../../../…`) are fragile — a folder move breaks every one — so they are confined to that one block, where a path change touches one place; body mentions use the plain name (`the boundary skill`, `structure.md`) instead of a link.
 
+## Shape — the model first, the detail after
+
+Every truth document a person reads to understand something — doctrine, system, package, feature — is written **from the outside in**. It opens on the model and adds detail in layers, so a reader who stops at any layer holds a picture that is coarse but true, never a teaser that only the next section makes sense of. The failure this prevents is a document written at one density from its first word: an inventory table before the reader knows what is being inventoried, and the principles that summarize it arriving last, where nobody reads them.
+
+**The layers, in order:**
+
+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 can cite them ("principle 3").
+3. **The parts.** One table or diagram that places every part in the model, then how the parts relate: what they share, where they meet, and what keeps them apart.
+4. **Each part in turn.** For each part, the decisions it rests on and why. Each section opens with why the part exists, not with how it is built.
+5. **The genre's deepest layer**, from the table below, and nothing deeper.
+
+**The stability test decides what a sentence may say.** Ask whether the sentence would have to change if a function were renamed, a file moved, a route, column, cookie attribute or error code changed, or a constant was retuned without the design changing. If it would, it fails. The fact belongs to the code, and the code graph computes it on demand (`docs/architecture/systems/knowledge-layer.md`). A copy typed here is at best a duplicate of the code and at worst a stale one, which misleads the next agent more than no document would. It also has to be found and re-edited on every change to the code beneath it.
+
+These survive the test:
+
+- **Reasons.** Why the design is this way, and what would break otherwise.
+- **Invariants.** What must hold everywhere.
+- **Decisions and the alternatives a reader would reach for.**
+- **Promises a person or a test can check.**
+- **Contracts that span components no single file shows.** For example, two clients that must classify the same answer identically.
+- **Decided-but-unbuilt intent.** The code cannot reveal what it does not yet do.
+
+**The code is the authority on *what*; the document is the authority on *why*.** A document that disagrees with the code about what happens is simply stale, and the code wins. A disagreement about why, or about an invariant, is a defect to raise with the owner, because one of the two is wrong on purpose. State this in the opening of any document whose readers include agents.
+
+**Each genre has its own deepest layer.** The shape above is common to every genre; how far down a genre may go differs:
+
+| Genre | Deepest layer | Stops before |
+| --- | --- | --- |
+| Doctrine (`architecture/common/`) | The decisions behind each part, and the reasons for them | Any mechanism. A doctrine document describes no code |
+| System (`architecture/systems/`) | How the machine behaves across packages: sequence and state diagrams, the invariants 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 (`architecture/packages/`) | 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 (`features/`) | The behaviour a person meets, in full: each state the surface can be in, each edge case, what a refusal tells them, wording where the wording is promised. **This genre runs deepest toward its end**, because a promise is checked by a person or a test, not computed from code | Columns, routes, guards, functions, files |
+| Reference (API reference, environment registry) | The contract itself: signatures, shapes, variables | Nothing. The detail is the point |
+| Operations procedure, runbook | The exact commands, in order | Nothing. The detail is the point |
+
+**A diagram belongs to a layer.** At the model and parts layers it 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 is a signal, not a target.** 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.
+
+## Documents are read by people; the footer is for the agent
+
+A document that explains something — a doctrine, an owning document (feature, package, system) — is prose a person reads top to bottom. It takes the shape above (§ Shape — the model first, the detail after). The rules:
+
+- **The body is plain English.** It says what the thing is, why it is shaped that way, how a person meets it, and what it promises. Bullets and tables are for enumerable facts only — never for an argument, a decision or a promise. No sentence shape repeats down a list; a section whose entries share one shape is rewritten as paragraphs.
+- **Name code only where the graph would not lead a reader there.** The code graph answers what a feature's own files call, so those names add nothing. What it cannot answer from the feature's files is the seam that runs the other way: a middleware, a gate, a hook, a scheduler tick, a shared store holding part of the feature's logic because that logic is global. Write that reference by name, once, where the narrative leaves the feature. Everything else is a plain name — "the device registry", "the sign-off page", "the mirror".
+- **A term of art is introduced in plain words the first time it appears.**
+- **Bold marks a defined term's first appearance at most** — never a noun mid-sentence. An em-dash is a budget, one per paragraph, not a joint between clauses.
+- **A gap the code does not close is one Known gaps paragraph, or a backlog row.** Never a ledger row inside the body, never a temporal hedge.
+- **The first line under the title is the goal.** No plan link, no routing line above it.
+- **The footer, "For the agent", is a set of pointers, not an inventory.** It holds four things:
+  1. The objects, with a one-line definition each.
+  2. The code roots, as directories, where the graph should start.
+  3. The cross-cutting seams, by name.
+  4. The checklist, and the neighbouring documents with a purpose for each.
+
+  A feature adds its pages, because an address is what a person points at. A package adds its commands, because those are its public contract. Tables, routes, symbol rosters and file lists do not belong in the footer any more than in the body. The footer obeys the stability test (§ Shape) like every other line, and a footer that grows with every function is the inventory moved down the page.
+- **"How it works" is narrative, not mechanism.** It says that a forgotten machine comes back on its next call, not which function re-mints the row. Behaviour in plain words is intent made legible; columns, routes, guards and signatures are the graph's.
+
+The Mechanics rules below ("inline-code every identifier", "bold assertion — explanation") bind instruction files and operations procedures, not doctrine or the owning genres.
+
 ---
 
 ## The Two Natures — Tense & History
@@ -334,38 +395,19 @@ Worked example of the strip-and-relocate move: [`examples.md`](examples.md) Exam
 
 ### Standard Layout
 
+An owning document (feature, system, package) takes its shape from its template — Goal · Why it exists · How it works · What was decided · What it promises · Known gaps · For the agent — and a doctrine document from `templates/doctrine.md` — the question · The model · The parts · one section per part · For the agent. Neither is ever a code tour: no Architecture, Key Functions, State or Files section (§ Shape — the model first, the detail after; § Documents are read by people). The layout below is for a **reference document** that is not an owning genre — an API reference, an environment registry, a procedure's appendix — where a signature or a file list is the content itself:
+
 ```markdown
 # [Title]
 
 **Goal:** One-line purpose
 
-## Architecture
-
-[Diagram + explanation]
-
-## Key Functions
-
-[Signatures and contracts]
-
-## State
+## [Contract or procedure sections]
 
-[Persistence shapes]
-
-## Files
-
-[Source file list]
+[Signatures, shapes, steps — the content the reader came for]
 ```
 
-### File References
-
-Always end with:
-
-```markdown
-## Files
-
-- `src/path/main.js` - Core logic
-- `src/path/hooks.js` - React hooks
-```
+A file roster belongs in no document: the ownership index and the code graph answer "which file" for every genre.
 
 ---
 
@@ -373,12 +415,13 @@ Always end with:
 
 | Aspect     | Rule                            |
 | ---------- | ------------------------------- |
-| Functions  | Always include signatures       |
+| Functions  | Signatures in reference docs only — an owning document names a symbol in its footer |
 | Parameters | Type + purpose                  |
 | Returns    | Type + shape                    |
 | State      | Persistence points only         |
 | Diagrams   | ASCII for structure at rest, mermaid for behaviour over time — docs only, never instruction files |
 | Code       | Under 15 lines, contracts only  |
 | Voice      | Imperative/active               |
-| Mechanics  | Inline-code identifiers; bold-assertion bullets |
-| Length     | Concise, one line when possible |
+| Mechanics  | Instruction files and procedures: inline-code identifiers, bold-assertion bullets. Doctrine and owning documents: plain prose, pointers in the footer |
+| Shape      | The model first, the detail after; every sentence passes the stability test; each genre stops at its deepest layer (§ Shape) |
+| Length     | Concise; a paragraph is one line — never hard-wrap prose (`.prettierrc.json` keeps `proseWrap: never`) |

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

@@ -25,7 +25,8 @@ When a draft wants to be both — the current state *and* the story of getting t
 - **Headings are retrieval keys.** Sections get pulled out of context by search and agents; qualify generic headings with the topic (`## Merge rules — data sync`, not `## Rules`) so each stands alone.
 - **Tables for enumerable facts, prose for judgment.** One row per item; anything needing a *because* lives in prose around the table, never inside a cell.
 - **Every section earns its place.** No empty stubs — omit what has nothing real to say; write an explicit "None" only where the absence itself is information.
-- **Cite sources and link neighbours.** If the document mentions a concept another document owns, link it; if it draws on code, name the files.
+- **Build from the outside in.** The question and its boundary, then the model, then the parts, then the detail — and nothing that fails the stability test (`references/style-guide.md` § Shape — the model first, the detail after). An explanation of a concern the whole platform handles is not untemplated: it is `templates/doctrine.md`.
+- **Cite sources and link neighbours.** If the document mentions a concept another document owns, link it; if it draws on code, name the directory it lives in — the code graph finds the files, and a file list goes stale.
 
 ## 4. Write it in the house style
 

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

@@ -119,11 +119,97 @@ function lintFile(path, findings) {
 
   // A folder index (Readme.md/README.md) is a browse page, not a feature doc — it owns no code.
   const isFolderIndex = /(^|\/)(readme)\.md$/i.test(path);
+
+  // An index names folders, never files (SKILL.md § The Two Natures). A link from a folder index or
+  // the authority map to an individual document is a row that must be edited on every add, rename
+  // and retirement; the only files an index may link are the mandated scaffolds and a sibling
+  // folder's own Readme.
+  const isAuthorityMap = /(^|\/)docs\/structure\.md$/.test(path);
+  const isRootReadme = /^(\.\/)?README\.md$/i.test(path.replace(process.cwd() + '/', ''));
+  if (scope === 'truth' && (isFolderIndex || isAuthorityMap) && !disabled.has('index-lists-files')) {
+    const SCAFFOLD = /(^|\/)(readme|structure|changelog|backlog|main|health-log|journal|claude|agents)\.md$|(^|\/)operations\/setup\.md$/i;
+    for (const { n, line } of lines) {
+      if (line.includes('doc-lint-disable: index-lists-files')) continue;
+      for (const m of line.matchAll(/\]\(([^)\s#]+\.md)(#[^)]*)?\)/g)) {
+        const target = m[1];
+        if (/^[a-z]+:\/\//.test(target) || SCAFFOLD.test(target)) continue;
+        // The repo-root README routes by intent (templates/root-readme.md): its Map names owning package and system
+        // docs, its Where-to-go rows name procedures and rules. Individual feature docs stay off it — the ownership index finds them.
+        if (isRootReadme && /(^|\/)docs\/(architecture\/(packages|systems|common)\/|operations\/)[^/]+\.md$|(^|\/)\.claude\/rules\/[^/]+\.md$/.test(target)) continue;
+        if (isRootReadme && /(^|\/)docs\/features\/[^/]+\.md$/.test(target)) { findings.push({ path, n, severity: 'warn', id: 'root-readme-feature-link', message: `root README links an individual feature doc (\`${target}\`) — point at docs/features/ and let the ownership index find it`, excerpt: line.trim().slice(0, 90) }); continue; }
+        findings.push({ path, n, severity: 'block', id: 'index-lists-files', message: `index links an individual document (\`${target}\`) — name the folder and how its files are named; \`ls\` is the roster`, excerpt: line.trim().slice(0, 90) });
+      }
+    }
+  }
+  // A folder index describes directories; a drawn tree is a file roster in another costume
+  // (SKILL.md § Indexes describe directories, never files). structure.md is the authority map and keeps its tree.
+  if (scope === 'truth' && isFolderIndex && (isRootReadme || /(^|\/)docs\//.test(path)) && !disabled.has('index-file-tree')) {
+    // Raw lines, not proseLines: a tree is drawn inside a code fence, which proseLines drops. The repo-root README routes by a Map table; its tree is docs/structure.md's too (templates/root-readme.md).
+    const rawLines = text.split('\n').map((line, i) => ({ n: i + 1, line }));
+    const tree = rawLines.find(({ line }) => /^\s*[│├└]/.test(line));
+    if (tree) findings.push({ path, n: tree.n, severity: 'block', id: 'index-file-tree', message: 'a tree drawn in a folder index — describe each directory in a sentence; the tree is docs/structure.md\'s', excerpt: tree.line.trim().slice(0, 90) });
+  }
+  // The repo-root README is an orientation page with a budget (templates/root-readme.md): up to about 140 non-blank lines, plain Markdown, no chrome.
+  if (scope === 'truth' && isRootReadme) {
+    const raw = text.split('\n');
+    const nonBlank = raw.filter((l) => l.trim()).length;
+    if (!disabled.has('root-readme-budget') && nonBlank > 140) findings.push({ path, n: 1, severity: 'warn', id: 'root-readme-budget', message: `${nonBlank} non-blank lines — the root README orients and routes; a section that needs a paragraph needs a doc (templates/root-readme.md)` });
+    const chrome = raw.findIndex((l) => /shields\.io|<img\b|<div\b|<p align|^!\[/.test(l));
+    if (!disabled.has('root-readme-chrome') && chrome !== -1) findings.push({ path, n: chrome + 1, severity: 'block', id: 'root-readme-chrome', message: 'badge, image or HTML layout in the root README — agents cannot read it and the team does not need it', excerpt: raw[chrome].trim().slice(0, 90) });
+  }
   if (scope === 'truth' && !isFolderIndex && /(^|\/)docs\/features\/[^/]+\.md$/.test(path)) {
     const fm = text.startsWith('---') ? text.slice(0, text.indexOf('\n---', 3)) : '';
-    for (const key of ['owns:', 'keywords:', 'status:', 'type:'])
+    for (const key of ['owns:', 'status:', 'type:'])
       if (!fm.includes(key)) findings.push({ path, n: 1, severity: 'block', id: 'feature-frontmatter', message: `feature doc missing \`${key}\` frontmatter` });
   }
+
+  // An owning document (feature, package, system) is intent and promises; the sections that narrate
+  // mechanism — a file roster, a walk through the code, a schema or route table — are the graph's
+  // to compute and are retired from the genre (SKILL.md § A document is intent and promises).
+  const isOwningDoc = scope === 'truth' && !isFolderIndex && /(^|\/)docs\/(features|architecture\/(packages|systems))\/[^/]+\.md$/.test(path);
+  if (isOwningDoc && !disabled.has('mechanism-section')) {
+    const RETIRED = /^#{2,4}\s+(Files|Current Behavior|Key Functions|Data|API|Refusals?|Architecture|State|Redux|Affected Modules|Conventions to Follow|Ownership Conflicts|Tests|The shape|Layout|Build and test|Commands|Routes|Schema|Wire)\b/i;
+    for (const { n, line } of lines) {
+      if (!RETIRED.test(line) || line.includes('doc-lint-disable: mechanism-section')) continue;
+      findings.push({ path, n, severity: 'block', id: 'mechanism-section', message: 'mechanism section in an owning document — columns, routes, guards, functions and files are the graph\'s to compute; keep the decision or the promise, point by name, cut the rest', excerpt: line.trim().slice(0, 90) });
+    }
+    const fm = text.startsWith('---') ? text.slice(0, text.indexOf('\n---', 3)) : '';
+    if (!/^objects:/m.test(fm)) findings.push({ path, n: 1, severity: 'block', id: 'objects-missing', message: 'owning document names no `objects:` — the product objects it designs are its edge into the graph and its discovery terms' });
+  }
+
+  // The body of an owning document is read by people; its "For the agent" footer is the reference
+  // surface (style-guide § Documents are read by people). These three warn, never block: a seam
+  // reference is allowed in the body, and the judgment of which identifier is a seam is the author's.
+  if (isOwningDoc) {
+    const OLD_SHAPE = /^##\s+(Background|Decisions|Promises|Objects|Related)\s*$/;
+    const footerAt = lines.findIndex(({ line }) => /^##\s+For the agent\b/.test(line));
+    const body = footerAt === -1 ? lines : lines.slice(0, footerAt);
+    let section = null; // proseLines already dropped the frontmatter and the fences
+    const sections = [];
+    for (const { n, line } of body) {
+      if (/^##\s+/.test(line)) {
+        if (!disabled.has('old-shape-section') && OLD_SHAPE.test(line)) findings.push({ path, n, severity: 'warn', id: 'old-shape-section', message: 'second-shape heading — the owning genres now read Why it exists · How it works · What was decided · What it promises · Known gaps · For the agent', excerpt: line.trim() });
+        section = { n, title: line.replace(/^##\s+/, '').trim(), bullets: 0, lines: 0, ids: 0, boldRun: 0, maxRun: 0 };
+        sections.push(section);
+        continue;
+      }
+      if (!section || !line.trim()) { if (section) section.boldRun = 0; continue; }
+      section.lines++;
+      const isBullet = /^\s*[-*]\s+/.test(line);
+      if (isBullet) section.bullets++;
+      if (/^\s*[-*]\s+\*\*/.test(line)) { section.boldRun++; section.maxRun = Math.max(section.maxRun, section.boldRun); } else section.boldRun = 0;
+      for (const m of line.matchAll(/`([^`]+)`/g)) {
+        const t = m[1];
+        if (/[\/]|\.(ts|tsx|mjs|js|md|json|sql)$|_|\(|^[a-z]+[A-Z]|^[A-Z][a-z]+[A-Z]|^(GET|POST|PUT|PATCH|DELETE) /.test(t)) section.ids++;
+      }
+    }
+    for (const s of sections) {
+      if (/^(Ownership|Known gaps)$/.test(s.title)) continue;
+      if (!disabled.has('body-identifier') && s.ids > 3) findings.push({ path, n: s.n, severity: 'warn', id: 'body-identifier', message: `${s.ids} code identifiers in a body section — the body names code only at a cross-cutting seam (a middleware, gate, hook, store); the rest is plain names in prose, with identifiers in "For the agent"`, excerpt: s.title });
+      if (!disabled.has('list-not-prose') && s.bullets >= 4 && s.bullets / s.lines > 0.6) findings.push({ path, n: s.n, severity: 'warn', id: 'list-not-prose', message: 'a body section that is a list — a decision, a promise or an explanation is prose; a list is for genuinely parallel one-liners', excerpt: s.title });
+      if (!disabled.has('formula-run') && s.maxRun >= 3) findings.push({ path, n: s.n, severity: 'warn', id: 'formula-run', message: 'three or more bold-led bullets in a row — the "**X** — over Y, because Z" formula reads as a ledger; write the decisions as themed paragraphs', excerpt: s.title });
+    }
+  }
 }
 
 // A changed plan whose committed version is already frozen must not be edited.

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

@@ -6,6 +6,7 @@ One file per template. Every template is either a **truth document** (states cur
 | --- | --- | --- |
 | Feature (LLD) | [feature.md](feature.md) | Truth |
 | Package (one workspace package) | [package.md](package.md) | Truth |
+| Doctrine (one concern the platform handles everywhere) | [doctrine.md](doctrine.md) | Truth |
 | System (one machine spanning packages) | [system.md](system.md) | Truth |
 | Architecture Decision (AD) | [architecture-decision.md](architecture-decision.md) | Truth (Decision Changelog tail sanctioned) |
 | System overview | [system-overview.md](system-overview.md) | Truth |
@@ -18,13 +19,13 @@ One file per template. Every template is either a **truth document** (states cur
 | Testing strategy | [testing-strategy.md](testing-strategy.md) | Truth |
 | Behavioral checklist | [behavioral-checklist.md](behavioral-checklist.md) | Truth |
 | UX behavior | [ux-behavior.md](ux-behavior.md) | Truth |
+| Setup (first run, one per repo) | [setup.md](setup.md) | Truth |
 | Operations procedure | [operations-procedure.md](operations-procedure.md) | Truth |
 | Implementation map | [implementation-map.md](implementation-map.md) | Truth |
 | Bookkeeping ledger | [bookkeeping.md](bookkeeping.md) | Truth (work queue) |
 | Protected files | [protected-files.md](protected-files.md) | Truth |
-| Project root README | [root-readme.md](root-readme.md) | Truth |
+| Project root README (outward opening, then orientation and routing) | [root-readme.md](root-readme.md) | Truth |
 | docs/README.md (doc index) | [docs-readme.md](docs-readme.md) | Truth |
-| docs/structure.md (authority map) | [structure.md](structure.md) | Truth (Health Log tail sanctioned) |
 | Plan | [plan.md](plan.md) | Record |
 | Changelog entry | [changelog-entry.md](changelog-entry.md) | Record |
 | Migration runbook | [migration-runbook.md](migration-runbook.md) | Record |
@@ -35,6 +36,6 @@ One file per template. Every template is either a **truth document** (states cur
 
 **The `type:` enum lives here.** A doc's `type:` frontmatter takes its value from this table — one genre per template (`feature`, `architecture-decision`, `non-goals`, …). External generators consume this list rather than defining their own; a type this table does not name defaults to `docs/architecture/` placement and is never added to the protected-files list.
 
-**Baseline scaffolds** — files that must exist after every baseline; the `maintenance` agent (baseline mode) creates any that are missing: [docs-readme.md](docs-readme.md), [structure.md](structure.md), [changelog-index.md](changelog-index.md), [backlog.md](backlog.md), [memory-main.md](memory-main.md), and [root-readme.md](root-readme.md) (never overwriting an existing root README).
+**Baseline scaffolds** — files that must exist after every baseline (`docs/structure.md` is not among them: it is harness-owned, shipped whole by the installer and overwritten on every refresh, and has no template); the `maintenance` agent (baseline mode) creates any that are missing: [docs-readme.md](docs-readme.md), [changelog-index.md](changelog-index.md), [backlog.md](backlog.md), [memory-main.md](memory-main.md), [setup.md](setup.md) (when the repo has a lockfile and a runnable root script; never overwriting an existing first-run procedure), and [root-readme.md](root-readme.md) (never overwriting an existing root README).
 
 **Ownership.** Three genres carry code — **feature**, **package**, **system** — and each is the canonical reference for the code paths in its **`owns:` frontmatter**, the only ownership key. To find what a doc owns, read its `owns:` globs; to find the doc for a path, match the path against the injected ownership index (the union of every owning doc's globs), narrower glob wins. That is what layers them: a package doc claims `packages/{name}/**` and is the tree's **residual** owner, while a system doc claims the narrower subtrees of one machine and a feature doc claims one surface — both win those paths by specificity, and the package doc keeps everything neither claims. Two docs may never claim a path at **equal** specificity. Every other genre here owns no code, including the cross-cutting doctrine in `docs/architecture/common/`. See [`../references/frontmatter.md`](../references/frontmatter.md) for turning code into `owns:` globs.

package/data/harnesses/delivery/skills/documentation/templates/bookkeeping.md

@@ -21,4 +21,4 @@ The shared work queue keeping documentation and code in sync — a queue, never
 
 **A waiver covers a finding only when it names the finding's kind and its subject in backticks** — the matcher (`waiverCovers`) tests the backticked subject exactly, so a waiver written without them silences nothing and the wall stands. A `waived:` row's `expires=` date is enforced: CI honors the waiver until the date, then fails. `dead-glob` waivers double as the dead-glob allowlist; `ownership-overlap` waivers cover the CI ownership check the same way.
 
-Finding kinds for `auto:`: `dead-glob` · `doc-implicated` · `doc-lint` · `header-missing` · `index-row-missing` · `package-rejected` · `frozen-record-edited` · `source-lint`. The CI ownership check additionally accepts `waived:` rows of kind `ownership-overlap`.
+Finding kinds for `auto:`: `dead-glob` · `doc-implicated` · `doc-lint` · `header-missing` · `package-rejected` · `frozen-record-edited` · `source-lint`. The CI ownership check additionally accepts `waived:` rows of kind `ownership-overlap`.