@nurix/etna 0.20.8 → 0.20.10

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

@@ -0,0 +1,143 @@
+# System Documentation (docs/architecture/systems/{system}.md)
+
+Truth document. Use for: **one machine that spans packages** — exactly how it works, end to end, in one place. One file per machine, named for the machine (`docs/architecture/systems/update-engine.md`). It states the machine's model and its whole path: what enters it, every stage it passes through, what it writes, what re-drives it when it stalls, and what a reader sees at the far end.
+
+**A system document's globs win by specificity.** Its `owns:` names the subtrees and exact files the machine is made of — `packages/studio/src/server/execution/**`, `packages/ui/src/shared/harnessVocabulary.ts` — and those are narrower than the package document's `packages/studio/**`, so the system takes them and the package keeps the residue. That is the whole mechanism: **the package document is the residual owner and the system document is the specific one**, and nothing needs to be subtracted by hand. A machine confined to one package still gets a system document if the machine is the thing worth stating; it is the *narrower glob* that makes it a system, not the package count.
+
+**Two rules bind the globs.** Neither genre may claim a path another document claims at **equal specificity** — equal-specificity overlap is an ownership conflict to resolve before either document ships. And every glob **matches at least one file on disk** at `status: active`; projected globs are permitted only at `draft` and are confirmed when the document flips. Because a system's `owns:` list is long and hand-assembled, re-glob it whenever the machine's code moves — a stale entry here silently un-owns real code back to the package document, which does not describe it.
+
+**How this differs from its neighbours — and the mistake this template exists to prevent.** A **feature** document covers one capability or one page a person names and owns that surface's globs. A **package** document covers one unit of distribution and owns what is left of its tree. A **system** document covers a *machine*: something with an entry, stages, state and an outcome, which a person does not open and cannot point at. **The failure mode is a system document written as a giant feature document** — a tour of screens and what each button does, at ten times a feature doc's length. The test is mechanical: if the subject can be named by an address a person navigates to, it is a feature; if it can be named only as a verb over the product's own nouns — the walk, the egress, the ingest, the settlement — it is a system. A system document says what a surface *renders from* and links to the feature document for what the surface looks like; it never describes the surface.
+
+**Required vs optional.** Required in every system document: the **frontmatter**, the **opening statement** (what the machine is, then what this document states end to end), the **boundary paragraph** (what this document does not restate, and which document holds each part), the **machine diagram**, at least one **stage section**, **Files**, and **Related**. Everything else is optional. Do not add a section because it seems owed — a stage the machine does not have is a section that will be filled with something untrue.
+
+System documents are long by nature, because the point is that the whole machine is in one place — roughly 300 to 1000 lines. Length is earned by stages, never by restating a neighbour: every paragraph that could have been a link to the document that owns it is the genre's characteristic waste.
+
+```yaml
+---
+owns:                                              # required — the machine's subtrees and exact files; narrower than the package glob
+  - packages/{pkg}/src/{machine}/**
+  - packages/{pkg}/src/routes/{machine}.ts
+  - packages/{other}/src/shared/{machine}Vocabulary.ts
+keywords: [machine name, its nouns, its verbs]     # required — discovery terms: the machine's own vocabulary, the table and route names
+status: active                                     # required — active | draft | deprecated
+applies:                                           # optional — the decisions and doctrine this machine is BOUND by (obligation, not a bibliography)
+  - docs/architecture/decisions/AD-0NN-{slug}.md
+  - docs/architecture/common/{doctrine}.md
+type: system                                       # required tooling key — genre stamp; preserve on edits, never narrate
+---
+```
+
+> A system document carries no `module:` — a machine that spans packages belongs to no single
+> bounded context, and labelling it with one asserts a boundary it crosses by definition.
+> `last-reviewed:` is optional tooling metadata: preserve it, never narrate it.
+
+```
+# {The machine}
+
+{One paragraph that defines the machine in its own first sentence — bold the term being defined —
+then says what this document states, in the order the body states it. The enumeration is the
+contract: a reader who wants one stage finds it by reading this sentence. Where the machine's
+purpose is easier stated as an outcome, lead with `**Goal:**` and one sentence instead.}
+
+{One paragraph: the boundary. What this document does **not** restate, and which document holds
+each part — the neighbouring systems, the package documents whose residue this sits inside, the
+feature documents that render from it, the common-plane doctrine it obeys, the decision records
+behind its shape. Name each with a link and the subject it holds. This paragraph is what keeps the
+document from growing into its neighbours.}
+
+```text
+{The machine diagram. One fenced block, drawn as the thing flows — entry at the top or left,
+each stage a box or a labelled arrow, the durable writes named, the re-drive path shown returning.
+Label the arrows with what crosses them, not with verbs. This is the picture a reader holds while
+reading the rest, so it carries the machine's real names — routes, tables, classes, files — and
+not generic boxes.}
+```
+
+{Optional, and worth its line whenever the body names paths: "Every path below is relative to
+`packages/{pkg}/src/{dir}/` unless it names another package."}
+
+{Optional: a reading order for a long document — "§ X is the data; § Y is the code that reads it;
+§ Z is what re-drives it" — where the section list is not self-evidently a sequence.}
+
+## The shape
+
+{Optional. Where the machine has parts a reader must hold at once before any stage makes sense,
+name them in one table before the stages begin.}
+
+| Part | Where | What it holds |
+| --- | --- | --- |
+| {Entry} | `routes/{x}.ts` | {thin, tenancy first} |
+| {Ledger} | `{machine}/ledger.ts` | {the durable row} |
+
+## {Stage sections — one per stage, in the order the machine runs them}
+
+{The body, and the only genre where the section order is decided for you: the machine's own order.
+Entry, then each stage, then what is written durably, then what re-drives a stalled one, then what
+reads the result. Name each section for its stage in the product's own vocabulary. Within a
+section, state the mechanism and its reason: what the code does, what it refuses, and why it
+refuses that rather than something else. Tables for rosters (routes, columns, frames, states,
+bindings); prose for a rule and the defect it prevents. Never paste an implementation — a
+signature, a state list, a wire shape, a table's columns.}
+
+## Tests
+
+{Optional. What proves this machine, and what each suite pins — a `Suite | Pins` table. Include it
+where the machine has a suite of its own; omit the heading where the coverage lives in the package
+documents' suites.}
+
+## Files
+
+| Path | Role |
+| --- | --- |
+| `packages/{pkg}/src/{machine}/{file}.ts` | {what it holds, by name — the exports a reader is looking for} |
+
+{One row per file this document owns — the roster is the `owns:` list, made readable. Close with
+the inverse: "Read here, owned elsewhere:" naming the paths the body describes but another document
+claims, each with the document that claims it. That closing line is what stops a system document
+from quietly annexing the code it reads.}
+
+## Related
+
+- [AD-0NN — {the ruling}](../decisions/AD-0NN-{slug}.md) — {the decision behind this shape, the options weighed}
+- [`{neighbour}.md`]({neighbour}.md) — {the machine on the other side of this seam}
+- [`{feature}.md`](../../features/{feature}.md) — {what a person sees of this machine}
+- [`{doctrine}.md`](../common/{doctrine}.md) — {the cross-cutting contract this machine answers to}
+```
+
+### The boundary paragraph is the genre's load-bearing section
+
+Systems overlap: they share tables, call each other, and render into the same surfaces. Without a
+paragraph that names the seams, two system documents describe the same stage from two angles and
+drift apart on the first change — and a reader has no way to tell which is authoritative. So the
+boundary paragraph is not a courtesy list of related reading; it is the statement of what this
+document is *not*, written specifically enough that a later editor can tell where to put a fact.
+Write it as a list of subjects with their owners — "the coordinator's tables, alarm and drive claim
+are `harness.md`; a run's ledger row and settlement are `generation-runs.md`" — never as bare
+links.
+
+### Marking what is decided and unbuilt
+
+Where the machine has a stage that is decided and not built — a predicate that selects but never
+acts, a column that is written and never read, a door with no caller — wrap the prose in a marker
+so the gap is machine-findable and its evidence travels with it:
+
+```
+<!-- UNBUILT:START — {what is decided, where it is decided (an AD § or an owner ruling), and the
+source evidence that it is not built: the function with no caller, the route that is not mounted,
+the value written and never read} -->
+{the prose describing the unbuilt stage, and what runs in its place}
+<!-- UNBUILT:END -->
+```
+
+**State what runs instead.** A machine with a hole in it still works somehow, and the workaround is
+the fact a reader needs. **A design decided *against* carries no marker** — a marker means the work
+is owed and absent, so using one for a rejected design turns the register of debt into a register
+of opinions.
+
+### `status: draft` on a system
+
+A system document is `draft` when the **machine as a whole** does not run — the code is on disk and
+nothing reaches it. Say so in the first section, in plain words, with the evidence: which halves
+exist, which do not, and what a reader who invokes it actually observes. A scoped gap in a working
+machine is not a draft: the document stays `active` and takes an UNBUILT marker at the stage that
+has the hole.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nurix/etna",
-  "version": "0.20.8",
+  "version": "0.20.10",
   "description": "Bootstrap a project with a Nurix harness — copies the harness's CLAUDE.md, skills, agents, rules, and hooks directly into the project from a bundled payload (no marketplace fetch, no network).",
   "type": "module",
   "bin": {
@@ -42,5 +42,5 @@
     "agent",
     "plugin"
   ],
-  "etnaFingerprint": "bcf04d8d525c"
+  "etnaFingerprint": "0fa183cce9ee"
 }