@nurix/etna 0.20.9 → 0.20.11

package/data/harnesses/code/rules/pnpm.md

@@ -1,3 +1,12 @@
+---
+paths:
+  - "**/package.json"
+  - "**/pnpm-workspace.yaml"
+  - "**/pnpm-lock.yaml"
+  - "**/.npmrc"
+  - "**/tsconfig*.json"
+  - "**/turbo.json"
+---
 # pnpm — `@nurix/*` Workspaces: naming, boundaries, and consuming
 
 How a `@nurix/*` repo is **named**, **structured**, and how its packages are **consumed** — every repo takes the workspace shape, single-package frontends included. Publishing and CLI design live in the `nustack` skill, not here — no `nustack` skill in the runtime ⇒ ask before crossing the publish boundary.

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

package/data/harnesses/code/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/code/skills/polygraph/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: polygraph
+description: "Use when a document's truth is in question — audit a named doc, feature, folder, or code path against the code — and at every plan completion, where gate mode certifies the plan's docs before the freeze. Never the whole tree by reflex; not docs health, boundary, or the verification gate."
+---
+
+# Polygraph — two witnesses, one verdict
+
+Code and docs are two witnesses to the same product, and each lies in its own direction: documents describe designs the code never built, code runs behaviour no document learned. The audit checks a document's claims against the code, presumes the code correct unless a standing decision names it for retirement, corrects the document, registers the code-side findings, and puts to the owner what evidence cannot settle. It runs at two moments and nowhere else:
+
+| Moment | Mode | Ends with |
+| --- | --- | --- |
+| Any time, on a named target — a doc, a feature, a folder of docs, or a code path resolved to its owning docs | **Audit** | the target corrected, code-side rows registered, verdict counts reported |
+| Plan completion — after the verification gate has discharged and the Doc Obligations rows read **updated**, before the freeze | **Gate** | the same, over the plan's docs, plus the plan's `Polygraph:` segment |
+
+You are the **primary**: you hold the conversation, compose every context pack and packet, judge every contested verdict, and write the segment. Agents sweep and apply; a verdict is never delegated, and neither is a word said to the owner.
+
+References — read the routed file in full at the named moment:
+
+| Reference | Load when |
+| --- | --- |
+| `references/rows.md` | writing or reading any row; judging CONTESTED, QUESTION, residue, or a document's right to exist |
+| `references/dispatch.md` | composing a context pack, dispatching any role, packeting, recovering a dead or capped agent, pricing a run |
+
+## Standing rules
+
+1. **Code is presumed correct — unless a standing decision names it.** The precedent pack decides by **naming**: a decision condemns code only when it names the file, table, route, command, or surface by the product's own name for it, and the row quotes the naming words. A resembling thing is not a match; arguable → QUESTION. Documenting undocumented code is the mechanically easiest resolution and quietly canonizes a retiring lane; condemning on a resemblance retires code the product still ships. The full test is `references/rows.md` § The residue guard.
+2. **No citation, no row** — `file:line`, or the exact command and its result. Prove or refute, never confirm by plausibility.
+   **A documented behaviour the code lacks is UNBUILT, never MISDESCRIBED.** The document may be stating the target design; rewriting it to match the code silently abandons that design. Without the repo's unbuilt marker on the passage or a precedent naming the subject, the row is a QUESTION for the owner, and the passage stands until the answer.
+3. **Finders never edit; appliers never judge; the audit never edits code.** A code-side finding leaves as a register row for the planning workflow, however small and however directly it is asked for; a source fix asked for *inside* the audit is refused, registered, and answered with the one thing that would let it happen — a separate ask outside the audit. **Markdown is not source**: every document read may be edited under the applier discipline; frozen records are exempt.
+4. **The applier re-check is the gate.** Every row is re-derived against today's tree before its doc is touched; a claim that fails to reproduce dies as *did not reproduce* and never becomes an edit. This is what lets a row be applied by an agent that never saw the finder's reasoning.
+5. **Rows live on disk, never in your context.** Partials, packets, and outcomes land under `.claude/state/polygraph/{run}/`; you re-read files. The folder is machine-local and you delete it when the run closes — in the same turn as the report, **whatever is still open**: the reply carries every open row in full, an owner's answer starts a new run over those rows only, and the changelog entry of the commit is the record. Nothing under `.claude/state/polygraph/` outlives the reply.
+6. **The owner's answer is applied in the same pass** — verbatim in the doc it settles, quoted in the changelog entry's Ask line. There is no question ledger to park it in.
+
+## The run
+
+Both modes run the same sequence; the modes differ only in how the target list and the closing write are derived.
+
+1. **Resolve the targets.** A doc path is a target; a feature name resolves to `docs/features/{feature}.md`; a folder yields every doc in it; a code path resolves through the injected ownership index to the docs whose `owns:` globs match — or, when no index is in context, by scanning the `owns:` frontmatter under the docs root. A code path with no owner is **reported, never refused** — say which paths are unowned and go on with the rest. A target with no document at all is the one refusal: there is nothing to audit.
+2. **Price it and say so** before dispatching when the target list exceeds ten documents: per-doc cost at the pinned tier, the wave count under the runtime's concurrency ceiling, and the total. An owner directive to run on a stronger tier is priced the same way — state the multiplier and record the directive in the changelog entry.
+3. **Write one context pack per doc** (`references/dispatch.md` § The context pack) — the doc's `owns:` globs, the code paths in question, the precedent quotations that name this subject, the register rows already tracking it, and the owner rulings that bind. The pack is the agent's whole reading list.
+4. **Dispatch one `polygraph-finder` per doc**, in waves under the concurrency ceiling. Each writes its partial to the run folder and returns at most 120 words. A finder that returns **partial** at its turn cap is resumed once from its partial on disk; a second partial is accepted as that doc's sweep and reported as such.
+5. **Merge and check.** Concatenate the partials into `findings.psv`, quarantine malformed lines into `malformed.txt` (kept, never silently repaired), run `scripts/audit.mjs {run}` and fix what it reports by hand.
+6. **Judge.** Read every non-COHERENT row's evidence yourself. CONTESTED rows you judge with both sets of evidence in hand; a row you doubt goes to a `polygraph-verifier` (claim and subject only) and comes back CONTESTED if the two disagree. QUESTION rows — and every proposed deletion, with its inbound count — go to the owner **now, inline**, batched and ranked by how many rows each answer unblocks; work proceeds on everything else while they are open.
+7. **Packet and apply.** One doc, one `polygraph-applier`, always — `audit.mjs` asserts no collision. MISDESCRIBED rows and in-scope UNDOCUMENTED rows that passed the residue guard go to the owning doc's packet; RESIDUE, UNBUILT-abandoned, and every code-side row go to the register (the backlog, in its existing grammar, deduped against what is already there); frozen records resolve `exempt-frozen`. Fold each applier's outcome file into row status by hand, then run `audit.mjs` again.
+8. **Run the repo's doc gates in your own seat** — lint, links, ownership — over every doc touched; a delegated gate that dies reports nothing, which reads exactly like a pass.
+9. **Report** in prose: docs audited, claims checked, corrected, registered, contested-and-judged, questions answered; the refuted-on-apply count is the quality signal, stated every time. Then delete the run folder — also when rows are still open for the owner; they are in the reply.
+
+## Gate mode — the closing write
+
+Gate mode's target list is **every Doc Obligations row discharged as `updated` plus every `Spec:` doc**, and its code scope is the plan's Proposed Changes paths together with those docs' `owns:` globs. It runs after the verification gate and the Doc Obligations discharge, before `Status: Complete` is written — the freeze waits for it, and the harness's completion policy says so. The skill writes the `Polygraph:` segment and nothing else on the plan: the status flip is the author's, in the discharge-then-freeze edit.
+
+Ends by rewriting your own segment of the plan's **`Gates:`** line, exactly:
+
+- `Polygraph: passed YYYY-MM-DD (N docs · N claims · N corrected · N registered)` — every target swept, every non-QUESTION row resolved.
+- `Polygraph: owes nothing — {reason}` — written by the plan's **author**, not by you, when the plan has no `Spec:` doc and its Doc Obligations row is `None`, or when the repo's harness ships no polygraph.
+
+A QUESTION the owner has not answered leaves the segment at `pending`; the plan stays open, and the completion machinery says why. Never write `passed` over an open question.
+
+## Economy
+
+The tier is pinned in the three agent definitions — the cheapest capable tier, low to medium effort, a turn cap — never chosen at dispatch. The strong tier's value concentrates in judgment, and every judgment in this skill is yours. Where a role agent is not installed (a runtime whose plugin channel carries skills only), dispatch an independent subagent on the cheapest capable tier with the role's body inline, and say so in the report.
+
+## What this skill is NOT
+
+- **Routine docs health** — stale globs, broken links, structural drift: the `maintenance` agent.
+- **A plan's contract check** — both sides of a boundary for a diff or plan: the `boundary` skill.
+- **Test verification** — proving built behaviour: the `testing` skill.
+- **A whole-tree audit by reflex.** The tree is audited one target at a time, and every plan certifies its own docs; a full sweep is an explicit ask, priced before it runs.
+- **A code editor** — code-side findings exit as register rows (standing rule 3).
+
+If the request is one of these, say so and redirect — don't adapt.