@nurix/etna 0.20.9 → 0.20.11

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

@@ -1,7 +1,7 @@
 {
   "harness": "etna",
   "name": "etna",
-  "version": "1.5.17",
+  "version": "1.5.19",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
@@ -10,5 +10,5 @@
   "seeds": [],
   "tools": [],
   "docsRoot": "docs",
-  "digest": "24530584ce9d"
+  "digest": "4cf950471dd8"
 }

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

@@ -60,6 +60,8 @@ The two guarantees are complementary and both break on mixing: a reader holding
 | Baseline / reconcile docs | `maintenance` agent (baseline mode) — it calls this skill per template |
 | 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 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) |
 | Record/revise architecture decision | [`templates/architecture-decision.md`](templates/architecture-decision.md) — one AD per subject; revisions update it in place |
@@ -82,7 +84,7 @@ The two guarantees are complementary and both break on mixing: a reader holding
 | 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 |
-| Derive/update a feature doc's `owns:` | [`references/frontmatter.md`](references/frontmatter.md) |
+| 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 |
 | Author or restructure a **skill** (fit, triggers, shape, anatomy, shipping) | The skill-authoring field guide — the `etna` repo (`nurixlabs/etna`), folder `docs/playbooks/skills/`, chapters `00`–`10`. **No etna checkout available ⇒ ask the user for access to the etna repo, or proceed from first principles** with [`references/instruction-style.md`](references/instruction-style.md) governing the prose. This row is the only place the playbook is referenced |
@@ -105,6 +107,8 @@ The two guarantees are complementary and both break on mixing: a reader holding
 | Document | Nature | Name | Lifecycle |
 | --- | --- | --- | --- |
 | 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 |
 | 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 |
@@ -125,8 +129,11 @@ doc, plus the genre's own keys beside it; a document without its frontmatter fai
 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),
 `applies:` (the architecture docs it obeys; omitted when none), optional `last-reviewed:`. 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:`.
+**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
+`type: checklist` and `verifies:` — the doc whose promises it proves. An acceptance-criteria doc
+(`docs/acceptance/`) carries `type:` and `status:`.
 
 **The frontmatter is where the docs tree's edges live**, and a doc that declares none is a node
 nothing can reach: no change implicates it, so it rots without the rot being detectable. Deriving

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

@@ -1,6 +1,6 @@
 # Frontmatter Derivation — the doc graph
 
-Load when: creating a doc that declares an edge (a feature doc, a UX doc, a behavioral checklist), updating one whose scope moved, or running a baseline/reconcile pass over many docs.
+Load when: creating a doc that declares an edge (a feature, package or system doc, a UX doc, a behavioral checklist), updating one whose scope moved, or running a baseline/reconcile pass over many docs.
 
 **A docs tree is a graph, and every edge in it is declared in frontmatter.** Two kinds of edge exist: **doc → code** (`owns:`), and **doc → doc** (`verifies:`, `applies:`). The SessionStart hook reads them all and injects the generated indexes; there is no hand-maintained map of either kind.
 
@@ -14,13 +14,25 @@ The consuming end is also the end that **knows**. A checklist author knows what
 
 ## When to run
 
-- **Baseline / reconcile** — for every feature doc whose code paths aren't yet declared in its `owns:` frontmatter (the `maintenance` agent (baseline mode) calls this)
-- **New feature doc** — when creating a doc via the [Feature template](../templates/feature.md), project its `owns:` globs
+- **Baseline / reconcile** — for every owning doc whose code paths aren't yet declared in its `owns:` frontmatter (the `maintenance` agent (baseline mode) calls this)
+- **New owning doc** — when creating one via the [Feature](../templates/feature.md), [Package](../templates/package.md) or [System](../templates/system.md) template, project its `owns:` globs
 - **Doc update** — when the documented scope changes, update the doc's `owns:` globs
 
+## Which genres own code
+
+**Three do, and no others: `feature`, `package`, `system`.** They layer by glob specificity over the same tree, which is what lets a repo be documented at three altitudes without subtracting anything by hand:
+
+| Genre | Claims | Wins because |
+| --- | --- | --- |
+| `package` (`docs/architecture/packages/`) | `packages/{name}/**` — the whole tree, one glob | Nothing; it is the **residual** owner and loses every narrower claim, keeping what no one else takes |
+| `system` (`docs/architecture/systems/`) | the subtrees and exact files one machine is made of | Its globs are narrower than the package glob — specificity |
+| `feature` (`docs/features/`) | one capability's or one surface's globs | Same — specificity over the package glob |
+
+Every other genre owns no code and carries no `owns:`. That includes the cross-cutting doctrine in `docs/architecture/` (and `docs/architecture/common/`), which describes patterns rather than regions — a surface declares it is bound by one through `applies:`, and the doctrine never claims the surface back. Checklists, acceptance docs, ADs, operations procedures, research and brainstorm records own nothing.
+
 ## How to derive the frontmatter
 
-A feature doc's ownership frontmatter is `owns:` (required), `module:` (optional), `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 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.
 
 **1. `owns:`** (the path scope)
 
@@ -35,15 +47,17 @@ Prefer one region glob over many file globs. Ten paths say nothing about which i
 | A feature's own directory                     | `src/feature/**`                     |
 | A feature split across two directories        | One glob each                        |
 | A single entry-point file, and nothing beside it | The exact file path                  |
+| A whole workspace package, residually          | `packages/{name}/**` — one glob, on the package doc |
+| A machine spanning packages                    | One glob or exact path per subtree it is made of, on the system doc |
 | A shared file several features import         | **Nothing — leave it unowned**       |
 
 **An unowned shared file is the system working, not a gap.** A shared module's authority is the contract it exposes, not any one consumer, so a library-references file or a common utility legitimately has no owning doc. Claiming it would make the index bigger and the routing less certain at once.
 
 Glob each pattern against the codebase. At `status: active`, drop any that match nothing; at `status: draft`, projected globs may match nothing yet — confirm them against real code when the doc flips to `active`.
 
-**2. `module:`**
+**2. `module:`** (feature docs only)
 
-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).
+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:`**
 
@@ -67,7 +81,7 @@ That edge has a property the others lack, and it is worth naming: **a `Pinned:`
 
 ## Rules
 
-- One canonical doc per path. A doc's `owns:` globs must not overlap another doc's at equal specificity — the narrower glob wins; equal-specificity overlap is an ownership conflict to resolve.
+- One canonical doc per path. A doc's `owns:` globs must not overlap another doc's at equal specificity — the narrower glob wins; equal-specificity overlap is an ownership conflict to resolve. Overlap at **unequal** specificity is the layering working as designed: a package doc's `packages/{name}/**` is meant to be outranked, and what survives every narrower claim is exactly what that doc describes.
 - Use glob patterns for directories, explicit paths for individual files. At `active`, never list paths that don't exist in the codebase; a `draft`'s projected paths are confirmed at `active`.
 - When a doc covers a deep feature with sub-specs (e.g., `editor/`), each sub-spec owns its own globs — don't duplicate a path across siblings.
 - For baseline/reconcile with many docs, use parallel sub-agents to read source and propose `owns:` globs.

package/data/harnesses/etna/skills/documentation/references/instruction-style.md

@@ -4,7 +4,7 @@ The shared style for every file an agent obeys — a `CLAUDE.md`, a rule, an age
 
 ## The test for every line
 
-An instruction file is paid for whenever it loads, scaled by its load class: `CLAUDE.md` and rules load on **every turn of every session** — the most expensive prose in a repo per word; an agent definition loads per dispatch, a skill per invocation. The bar is not "is this true?" but **"must this be in front of the agent whenever this file loads?"** Measure weight in tokens, not lines; trim biggest-first on every edit.
+An instruction file is paid for whenever it loads, scaled by its load class: `CLAUDE.md` and unscoped rules load on **every turn of every session** — the most expensive prose in a repo per word; a `paths:`-scoped rule loads on those same terms from its first matching file read on; an agent definition loads per dispatch, a skill per invocation. The bar is not "is this true?" but **"must this be in front of the agent whenever this file loads?"** Measure weight in tokens, not lines; trim biggest-first on every edit.
 
 **Rewriting, the test is armor vs. narration.** A reason clause either blocks a move an agent would otherwise make — the failure is counter-intuitive, the wrong fix looks correct, or the rule reads as arbitrary tidiness and gets "improved away" — or it explains the self-evident. Ask of each: *does the forbidden move look correct to an agent mid-task?* Keep the first kind, cut the second. **A constraint may lose its explanation; it may never lose its existence** — compression is fewer words for the same constraints, so a passage that cannot shrink without dropping one stays long.
 

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

@@ -5,6 +5,8 @@ One file per template. Every template is either a **truth document** (states cur
 | Template | File | Nature |
 | --- | --- | --- |
 | Feature (LLD) | [feature.md](feature.md) | Truth |
+| Package (one workspace package) | [package.md](package.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 |
 | Domain model | [domain-model.md](domain-model.md) | Truth |
@@ -35,4 +37,4 @@ One file per template. Every template is either a **truth document** (states cur
 
 **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).
 
-**Ownership.** A feature doc 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 feature's `owns:` globs), narrower glob wins. See [`../references/frontmatter.md`](../references/frontmatter.md) for turning code into `owns:` globs.
+**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/etna/skills/documentation/templates/package.md

@@ -0,0 +1,131 @@
+# Package Documentation (docs/architecture/packages/{package}.md)
+
+Truth document. Use for: **one workspace package — what it is and how it behaves**. One file per package, named for the package's folder (`packages/cli/` → `docs/architecture/packages/cli.md`). It states the package's own machinery: its manifest and published identity, its build and entry point, its source layout, and every behavior of its tree that no system or feature document claims.
+
+**A package document is the residual owner of its own tree.** Its `owns:` is the whole package glob — `["packages/{name}/**"]` — and that glob is the *broadest* claim anything makes on those paths, so it loses to every narrower one. A system document naming `packages/{name}/src/server/runs/**` wins those files by specificity; a feature document naming `packages/{name}/src/surfaces/apps/**` wins those. What is left after every narrower claim is what this document describes, and it describes that exhaustively. **The residual claim is a promise of completeness, not of scope**: a package document with nothing left after the systems and features have claimed their subtrees is still owed — the manifest, the build, the entry, the layout, the test wiring and the deploy shape are always residual.
+
+**Two rules bind the glob.** 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, not a duplication to live with. And every glob **matches at least one file on disk** at `status: active`; a projected glob is permitted only at `draft`, and is confirmed when the document flips.
+
+**How this differs from its neighbours.** A **feature** document covers one capability or one page a person names, and owns that surface's globs. A **system** document covers one machine that spans packages, and owns the subtrees that machine is made of. A **package** document covers one unit of distribution — a manifest, a build, a binary or a bundle — and owns what is left of it. The unit is the package boundary, so if the subject you are writing about does not stop at a `package.json`, it is not this genre. Route it: one screen → feature; one machine crossing two packages → [system](system.md).
+
+**Required vs optional.** Required in every package document: the **frontmatter**, the **opening** (title, identity line, what the package is), the **ownership boundary** (what this document does not describe and which document does), at least one **behavior section**, **Files**, and **Related**. Everything else is optional — include a section only when the package has something real to put in it. A package with no test wiring of its own gets no verification section; a package that nothing else in the repo consumes says so in one line rather than growing a Consumers section. A short accurate document beats a full skeleton with empty headings.
+
+Package documents run long because they are exhaustive over their residue — roughly 150 to 600 lines is the working range, and the top of that range is a package holding an application, not a document that has lost discipline.
+
+```yaml
+---
+owns: ["packages/{name}/**"]                      # required — the whole package tree, one glob; the residual claim
+keywords: [package-name, binary, build, entry]    # required — discovery terms: the npm name, the binary, the surfaces
+status: active                                    # required — active | draft | deprecated
+applies: [docs/architecture/common/api.md]         # optional — cross-cutting doctrine this package is BOUND by (obligation, not a bibliography); omit when none
+type: package                                     # required tooling key — genre stamp; preserve on edits, never narrate
+---
+```
+
+> A package document carries no `module:` — a package is already a bounded unit, and a second label
+> for the same boundary is a thing to keep in sync for nothing. `last-reviewed:` is optional and,
+> like `type:`, is tooling metadata: preserve it, never narrate it.
+
+```
+# {package-path} — {the one-line role}
+
+**Package:** `@scope/name` · **Ships as:** {a public npm package with one binary `x` / a private
+source-first workspace package / a Worker on {domain}} · **Source:** `packages/{name}`
+
+{One paragraph: what this package is and the job it does in the product. Name what it holds that
+nothing else does, and what it deliberately does not hold. Written for someone who has not opened
+the folder.}
+
+{One paragraph: the ownership boundary. This document is the residual owner of `packages/{name}/**`;
+these subtrees are claimed at higher specificity by these documents and are pointed at, not
+restated. Where the routing is more than a sentence, make it the table below instead.}
+
+{Optional, and worth its line whenever the body names paths: "Paths below are relative to
+`packages/{name}/` unless they name another package."}
+
+## What is built and what is not
+
+{Optional — required in substance whenever some of the tree does not run. State plainly which
+halves exist and which do not, with the source evidence for each claim, and say what a reader who
+runs the unbuilt half will actually observe. A package whose subject as a whole does not run is
+`status: draft` and says so here; a scoped gap in a working package stays `active` and takes an
+UNBUILT marker at the section that describes the gap.}
+
+## Ownership — packages/{name}
+
+{Optional — use the table form when more than two documents claim subtrees of this package.}
+
+**The package glob is the residual claim.** A system or feature document's `owns:` is more specific
+and wins by specificity, so this document describes only what none of them claims, and points to
+each for the rest.
+
+| Path | What it is |
+| --- | --- |
+| `src/index.ts` | {the residue: the entry, the dispatch, the layout} |
+
+| Subtree | Stated and owned by |
+| --- | --- |
+| `src/{machine}/**` | [{system}](../systems/{system}.md) |
+| `src/surfaces/{x}/**` | [{feature}](../../features/{feature}.md) |
+
+## {Behavior sections — named for this package's own machinery}
+
+{The body. There is no fixed section list, and inventing one would be a lie: what a CLI owes
+(commands, the store, the on-ramp) and what a UI package owes (the host port, the frame, the route
+zones, the component pool) share no headings. Name each section for the thing it describes and
+order them the way a reader meets them — identity and build first, then the surface, then what it
+writes, then how it is verified. Prefer a table wherever the content is a roster (commands, routes,
+exports, bindings, environment variables); prefer prose wherever the content is a rule and its
+reason. State mechanisms and contracts, never pasted implementations.}
+
+## Tests
+
+{Optional. What proves this package, and what each suite pins — a `Suite | Pins` table, or the
+commands a reader runs. A package whose verification is a build check names the check instead
+(`## Checks`, `## Build and test`); a package with no suite of its own says so in one line in the
+build section and carries no heading here.}
+
+## Files
+
+| Path | Role |
+| --- | --- |
+| `packages/{name}/package.json` | {the manifest: the bin, the exports, the scripts} |
+| `packages/{name}/src/index.ts` | {the entry} |
+
+{One row or bullet per file this document owns, with what it holds — the roster a reader uses to go
+from the document to the code. Close with the inverse where it helps: "Read here, owned elsewhere:"
+naming the paths the body describes but another document claims.}
+
+## Related
+
+- [`{system}.md`](../systems/{system}.md) — {why a reader of this document would open that one}
+- [`{other-package}.md`]({other-package}.md) — {the seam between the two}
+- [`{doctrine}.md`](../common/{doctrine}.md) — {the cross-cutting contract this package answers to}
+```
+
+### The identity line
+
+The bolded `·`-separated run under the title is what a reader checks first, and it answers three
+questions no body section should have to: **what is this called** on the registry or in the
+workspace, **how does it ship** (a public tarball, a private source-first package, a deployed
+Worker, a signed installer), and **where is its source**. A package that ships two artifacts names
+both. Add a `**Crate:**` or `**Deploys as:**` term where the package has one; drop any term that
+would restate the title.
+
+### Marking what is decided and unbuilt
+
+Where the package holds code for a design that is decided and not built — or a surface whose other
+half does not exist — 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 file that does not exist, the route that is not mounted,
+the binding that is not declared} -->
+{the prose describing the unbuilt half}
+<!-- UNBUILT:END -->
+```
+
+**A design that was decided *against* carries no marker.** A marker means the work is owed and
+absent; using one for a rejected design turns the register of debt into a register of opinions.
+Say in prose that it is not built and not owed, and name the decision that settled it.

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

@@ -8,13 +8,13 @@ The `boundary` skill parses the **Proposed Changes** sections to check boundary
 
 **Doc Obligations is the one ledger the plan's author writes.** Deriving tests from behavior is judgment, which is why `testing` owns that section and it is marked never-hand-author; resolving Proposed Changes' file paths to the feature docs that own them is a **lookup** against the ownership index already injected at session start. Different work, different rule — fill it yourself, while the touch list is fresh.
 
-The **`Gates:`** line carries one machine-read segment. The compliance hook greps **`Boundary:`** — implementation edits inside the plan's scope are blocked while it reads `Boundary: pending`; the `boundary` skill rewrites it to `Boundary: passed YYYY-MM-DD` or `Boundary: blocked YYYY-MM-DD`. The other two gates are enforced by **section presence**: a plan with no `## Test Obligations` or no `## Doc Obligations` section blocks the same edits — the sections are the artifacts, and the gate derives from them, not from a claim about them. Never hand-edit the line to skip a gate.
+The **`Gates:`** line carries two machine-read segments. The compliance hook greps **`Boundary:`** — implementation edits inside the plan's scope are blocked while it reads `Boundary: pending`; the `boundary` skill rewrites it to `Boundary: passed YYYY-MM-DD` or `Boundary: blocked YYYY-MM-DD`. The other two plan gates are enforced by **section presence**: a plan with no `## Test Obligations` or no `## Doc Obligations` section blocks the same edits — the sections are the artifacts, and the gate derives from them, not from a claim about them. **`Polygraph:`** is the completion gate's trace: it reads `Polygraph: pending` from the first draft until the `polygraph` skill (gate mode) certifies the plan's documents — every Doc Obligations row discharged **updated** plus every `Spec:` doc — and rewrites it to `Polygraph: passed YYYY-MM-DD (N docs · N claims · N corrected · N registered)`. A plan that touched no document writes `Polygraph: owes nothing — {reason}` by hand; nothing else on this segment is ever hand-written. A Complete plan still reading `pending` raises a `needs-session:` queue row and fails CI. Never hand-edit the line to skip a gate.
 
 ```
 # {Feature Name}
 
 **Status:** Draft | In Progress | Complete | Abandoned
-**Gates:** Boundary: pending
+**Gates:** Boundary: pending · Polygraph: pending
 **Spec:** [docs/features/{feature}.md](../../features/{feature}.md)   <!-- one line per feature doc this plan implements against; a plan spanning three features names three -->
 **Started:** YYYY-MM-DD
 **Completed:** YYYY-MM-DD   <!-- fill in the SAME edit that flips Status to Complete — along with every ledger Outcome cell: the flip freezes the file instantly, so anything left for a second edit is unreachable (the frozen-record gate rightly blocks it) -->

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

@@ -18,8 +18,10 @@ Each topic has one canonical location. Read from here, not from plans or changel
 
 | Topic | Authority | Key Files |
 | ----- | --------- | --------- |
-| Code-path ownership (path → doc + module) | feature `owns:` frontmatter | the generated ownership index |
+| Code-path ownership (path → doc + module) | `owns:` frontmatter on features, packages and systems | the generated ownership index |
 | System overview | `docs/architecture/` | system-design.md |
+| One workspace package | `docs/architecture/packages/` | {package-folder}.md |
+| One machine spanning packages | `docs/architecture/systems/` | {machine}.md |
 | Steering (domain model, glossary, non-goals) | `docs/architecture/` | domain-model.md, glossary.md, non-goals.md |
 | Architecture decisions (ADs) | `docs/architecture/decisions/` | AD-NNN-*.md |
 | API surface | `docs/architecture/` | api.md |
@@ -45,8 +47,12 @@ Every doc is a **truth document** (states current absolutes, topic-named, update
 
 ## Folder Rules
 
-- `docs/features/`: Living reference for implemented features. Each feature doc **carries** the `owns:` / `module:` / `keywords:` / `status:` frontmatter — `owns:` declares the code-path globs it owns (the only ownership key), `module:` is an optional bounded-context label, `keywords:` are discovery terms, `status:` is `active`/`draft`/`deprecated`. The SessionStart hook unions every feature's `owns:` globs into the injected ownership index.
-- `docs/architecture/`: The truth layer for system-wide shape: overview, domain model, glossary, non-goals, API surface, security, and `decisions/` (ADs — one per subject, updated in place, journey in each AD's Decision Changelog). Update when cross-cutting reality changes.
+- `docs/features/`: Living reference for implemented features. Each feature doc **carries** the `owns:` / `module:` / `keywords:` / `status:` frontmatter — `owns:` declares the code-path globs it owns (the only ownership key), `module:` is an optional bounded-context label, `keywords:` are discovery terms, `status:` is `active`/`draft`/`deprecated`. The SessionStart hook unions every owning doc's `owns:` globs into the injected ownership index.
+- `docs/architecture/`: The truth layer for system-wide shape: overview, domain model, glossary, non-goals, API surface, security, and `decisions/` (ADs — one per subject, updated in place, journey in each AD's Decision Changelog). Update when cross-cutting reality changes. The cross-cutting doctrine directly under `architecture/` (and under `architecture/common/` where a repo separates it) **owns no code** — it describes patterns every surface obeys, and `applies:` is how a surface declares it is bound.
+- `docs/architecture/packages/`: One doc per workspace package (`{package-folder}.md`), present in a workspace repo. Each is the **residual owner** of its tree — `owns: ["packages/{name}/**"]` — describing the manifest, build, entry, layout and every behavior no system or feature doc claims at higher specificity. Template: the `documentation` skill's `templates/package.md`.
+- `docs/architecture/systems/`: One doc per machine that spans packages (`{machine}.md`) — the walk, the egress, the ingest. Its `owns:` names the machine's own subtrees and files, narrower than the package glob, so it wins those paths by specificity and the package doc keeps the rest. Not a surface doc: what a person sees stays in `docs/features/`. Template: the `documentation` skill's `templates/system.md`.
+
+**Three genres carry `owns:`** — features, packages, systems — and no others. Their globs layer by specificity (package `**` residual, system and feature narrower), and two docs may never claim a path at **equal** specificity: that is an ownership conflict to resolve, not a duplication to live with. Every glob matches at least one file on disk at `status: active`.
 - `docs/operations/`: How-to procedures for setup, development, and deployment, plus the environment registry. Update when workflows change. One-shot migrations do NOT live here — they are records (`docs/history/migrations/`).
 - `docs/tests/`: Testing strategy and test docs. Present when the repo has a test posture worth documenting.
 - `docs/history/plans/`: Records. Must have `Status:` field. Never modify after completion.