@nurix/etna 0.20.9 → 0.20.10

package/data/harness-index.json

@@ -1,5 +1,5 @@
 {
-    "fingerprint": "7d1e7785bd0c",
+    "fingerprint": "0fa183cce9ee",
     "harnesses": {
         "code": {
             "plugin": "code",

package/data/harnesses/code/harness.json

@@ -1,7 +1,7 @@
 {
   "harness": "code",
   "name": "code",
-  "version": "3.14.7",
+  "version": "3.14.8",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
@@ -25,5 +25,5 @@
     }
   ],
   "docsRoot": "docs",
-  "digest": "80ccc743454e"
+  "digest": "5de54f6b1a71"
 }

package/data/harnesses/code/hooks/awareness.mjs

@@ -13,7 +13,8 @@ import {
   resolveProjectDir,
   buildIndex,
   buildEdgeIndex,
-  scanFeatureDocs,
+  scanOwningDocs,
+  isOwningDocPath,
   owningDocs,
   owningDoc,
   listRepoFiles,
@@ -164,7 +165,7 @@ function driftBanner(projectDir) {
   // Re-verify before counting: the walls must act on conditions that are live NOW, not on rows
   // that happen to still be written down.
   const swept = sweepResolvedRows(projectDir, repoFiles);
-  const docs = scanFeatureDocs(projectDir);
+  const docs = scanOwningDocs(projectDir);
   const dead = deadGlobs(projectDir, repoFiles, docs);
   const queueRows = readQueue(projectDir);
   const counts = countRows(queueRows);
@@ -534,8 +535,10 @@ function postToolUse(projectDir, payload) {
     const rel = relIfInside(projectDir, input.file_path || input.notebook_path);
     if (rel) detectorForFile(projectDir, rel, meta, rows);
     const root = docsRoot(projectDir);
-    // Editing a feature doc's frontmatter can orphan globs the same way a rename can.
-    if (rel && rel.startsWith(`${root}/features/`)) detectRenames(projectDir, "git mv", meta, rows);
+    // Editing an owning doc's frontmatter can orphan globs the same way a rename can. The test is
+    // the scan's own predicate, not a `features/` prefix — a package or system doc owns code too,
+    // and a folder guess here silently stops checking the moment a genre lands somewhere else.
+    if (rel && isOwningDocPath(projectDir, rel)) detectRenames(projectDir, "git mv", meta, rows);
     // A manifest or history file written by a non-Bash tool is the same evasion surface.
     if (rel && (path.posix.basename(rel) === "package.json" || rel.startsWith(`${root}/history/`))) {
       detectOutcomes(projectDir, meta, rows);

package/data/harnesses/code/hooks/lib/ownership.mjs

@@ -1,6 +1,6 @@
 // harness/code/hooks/lib/ownership.mjs — frontmatter scan + owns:-glob resolution, shared by the
 // hook entrypoints (awareness, compliance) and the CI checks so gates and pipeline cannot disagree.
-// Everything here is read-only over docs/features/ and the source tree; no network, no deps.
+// Everything here is read-only over the docs tree and the source tree; no network, no deps.
 
 import fs from "node:fs";
 import path from "node:path";
@@ -81,7 +81,7 @@ export function field(block, key) {
       // A bare key may continue as an indented inline array on the next line, or a `- item` block.
       // The array may span several lines, so join through the closing bracket before parsing —
       // reading only the first line yields a bare "[", which parses to [] and makes the whole doc
-      // look like it owns nothing. `scanFeatureDocs` skips such docs, so the failure is invisible:
+      // look like it owns nothing. `scanOwningDocs` skips such docs, so the failure is invisible:
       // the doc drops out of the ownership index and out of every dead-glob count.
       const next = (lines[i + 1] || "").trim();
       if (next.startsWith("[")) {
@@ -114,13 +114,38 @@ export function asList(v) {
   return (Array.isArray(v) ? v : [v]).map((s) => String(s).trim()).filter(Boolean);
 }
 
-// Scan docs/features/**/*.md and return one entry per feature doc that declares owns:.
+// Folders under the docs root that never hold an owning document, whatever their frontmatter says.
+// `history/` is frozen records — a completed plan's frontmatter is history, not a live claim on code;
+// `research/` is working material that has not been folded into the truth tree yet.
+const NON_OWNING_DIRS = new Set(["history", "research"]);
+
+// True when a repo-relative docs path is one the ownership scan reads — the same predicate
+// `scanOwningDocs` filters by, exported so callers cannot drift from it. A hook asking "could
+// editing this file have orphaned a glob?" must ask exactly this question, not a folder guess.
+export function isOwningDocPath(projectDir, relPath) {
+  const rel = String(relPath).split(path.sep).join("/");
+  const root = docsRoot(projectDir);
+  if (!rel.startsWith(`${root}/`) || !rel.endsWith(".md") || rel.includes(".bkp.")) return false;
+  return !NON_OWNING_DIRS.has(rel.slice(root.length + 1).split("/")[0]);
+}
+
+// Scan the docs tree and return one entry per document that declares owns:.
 // Shape: { doc (repo-relative, /-separated), owns[], module, keywords[], status }.
-export function scanFeatureDocs(projectDir) {
-  const featuresDir = path.join(projectDir, docsRoot(projectDir), "features");
-  // *.bkp.* files are install-time backups awaiting the maintenance fold — a backed-up feature
-  // doc still carries owns: frontmatter, and scanning it would double-own every path it names.
-  const files = listMarkdown(featuresDir).filter((f) => !f.includes(".bkp."));
+//
+// OWNERSHIP IS A FRONTMATTER FACT, NOT A FOLDER FACT. This scanned `docs/features/` alone, which
+// silently un-owned every path claimed by a genre living elsewhere — a `type: package` doc under
+// `docs/architecture/packages/`, a `type: system` doc under `docs/architecture/systems/`. Their
+// globs parsed fine and matched real files; nothing failed, the paths simply read as unowned in
+// the generated index and in the drift report, which is the one failure mode neither surfaces.
+export function scanOwningDocs(projectDir) {
+  const root = path.join(projectDir, docsRoot(projectDir));
+  // *.bkp.* files are install-time backups awaiting the maintenance fold — a backed-up doc
+  // still carries owns: frontmatter, and scanning it would double-own every path it names.
+  const files = listMarkdown(root).filter((f) => {
+    if (f.includes(".bkp.")) return false;
+    const rel = path.relative(root, f).split(path.sep);
+    return !NON_OWNING_DIRS.has(rel[0]);
+  });
   const docs = [];
   for (const file of files) {
     let text;
@@ -146,10 +171,17 @@ export function scanFeatureDocs(projectDir) {
 
 // Build the ownership index text from every feature doc's frontmatter.
 export function buildIndex(projectDir) {
-  // Total markdown under docs/features/, counted independently of scanFeatureDocs — which
-  // drops a doc carrying no owns:, making a parse failure and a doc that owns nothing look alike.
-  const total = listMarkdown(path.join(projectDir, docsRoot(projectDir), "features")).length;
-  const docs = scanFeatureDocs(projectDir);
+  // Every document eligible to own, counted independently of scanOwningDocs — which drops a doc
+  // carrying no owns:, making a parse failure and a doc that owns nothing look alike. Genres that
+  // never own (checklists, operations notes) sit in this total, so `skipped` is a ceiling on the
+  // parse failures rather than a count of them; it is a smell to look at, not a gate.
+  const root = path.join(projectDir, docsRoot(projectDir));
+  const total = listMarkdown(root).filter((f) => {
+    if (f.includes(".bkp.")) return false;
+    const rel = path.relative(root, f).split(path.sep);
+    return !NON_OWNING_DIRS.has(rel[0]);
+  }).length;
+  const docs = scanOwningDocs(projectDir);
   const lines = [];
   let deprecated = 0;
   for (const entry of docs) {
@@ -171,7 +203,7 @@ export function buildIndex(projectDir) {
   if (lines.length === 0) return "";
   lines.sort();
   const header =
-    "# Ownership index (generated) — owning feature doc · module · status, then the code regions it governs.\n" +
+    "# Ownership index (generated) — owning doc · module · status, then the code regions it governs.\n" +
     "# Match the file or topic you're about to touch, then read the owning doc before changing it.\n";
   const indexed = docs.length - deprecated;
   const skipped = total - docs.length;
@@ -179,7 +211,7 @@ export function buildIndex(projectDir) {
   if (deprecated > 0) notes.push(`${deprecated} deprecated`);
   if (skipped > 0) notes.push(`${skipped} with no owns:`);
   const footer = notes.length
-    ? `\n# (${indexed}/${total} feature doc(s) indexed - ${notes.join(", ")})`
+    ? `\n# (${indexed}/${total} doc(s) indexed - ${notes.join(", ")})`
     : "";
   return header + lines.join("\n") + footer;
 }
@@ -270,11 +302,11 @@ export function globToRegExp(glob) {
   return new RegExp(`^${re}$`);
 }
 
-// Feature docs owning the given repo-relative path (deprecated docs excluded).
+// Documents owning the given repo-relative path (deprecated docs excluded).
 export function owningDocs(projectDir, relPath, docs) {
   const rel = relPath.split(path.sep).join("/");
   const out = [];
-  for (const entry of docs || scanFeatureDocs(projectDir)) {
+  for (const entry of docs || scanOwningDocs(projectDir)) {
     if (entry.status === "deprecated") continue;
     if (entry.owns.some((g) => globToRegExp(g).test(rel))) out.push(entry);
   }
@@ -305,12 +337,12 @@ export function listRepoFiles(projectDir) {
   return out;
 }
 
-// Globs across all feature docs that match zero files on disk.
+// Globs across all owning docs that match zero files on disk.
 // Returns [{ glob, doc }]; pass precomputed file/doc lists to amortize the walks.
 export function deadGlobs(projectDir, repoFiles, docs) {
   const files = repoFiles || listRepoFiles(projectDir);
   const dead = [];
-  for (const entry of docs || scanFeatureDocs(projectDir)) {
+  for (const entry of docs || scanOwningDocs(projectDir)) {
     if (entry.status === "deprecated") continue;
     for (const glob of entry.owns) {
       const re = globToRegExp(glob);
@@ -376,7 +408,7 @@ export function owningDoc(projectDir, relPath, docs) {
 export function overlaps(projectDir, repoFiles, docs) {
   const files = repoFiles || listRepoFiles(projectDir);
   const owners = [];
-  for (const entry of docs || scanFeatureDocs(projectDir)) {
+  for (const entry of docs || scanOwningDocs(projectDir)) {
     if (entry.status === "deprecated") continue;
     for (const glob of entry.owns) {
       const s = specificity(glob);

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/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/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.