@nurix/etna 0.20.9 → 0.20.11

package/data/harnesses/code/skills/polygraph/references/dispatch.md

@@ -0,0 +1,80 @@
+# Dispatch — packs, roles, packets, recovery, price
+
+Load when: composing a context pack, dispatching any role, packeting rows, recovering a dead or turn-capped agent, or pricing a run.
+
+## The run folder
+
+`.claude/state/polygraph/{YYYY-MM-DD-slug}/` — machine-local, never tracked, deleted when the run closes:
+
+```
+partials/{doc}.psv      one per finder — its whole output, no header
+findings.psv            the merge, header first — the working copy
+malformed.txt           quarantined lines, kept
+packets/{doc}.txt       one per applier: `doc: {path}` then row ids and bounce notes
+verify-{group}.psv      id|check|confidence|citations|note
+apply-{doc}.psv         id|outcome|note
+packs/{doc}.md          the context pack each finder and applier reads
+```
+
+Work items pass through files, never through a dispatch call's arguments — a resumed agent may not carry arguments, and one that dies on a missing argument dies before it reads anything.
+
+## The context pack — the agent's whole reading list
+
+One page per target document, written by you before the first dispatch. A brief that sends an agent to the charter, the backlog, the ownership index, or the findings file hands it a 500 KB read to extract 2 KB of fact — and hands the same read to every other agent in the wave. The pack carries the 2 KB:
+
+| Section | Content |
+| --- | --- |
+| Target | the doc path; in gate mode, the plan path and the Proposed Changes paths that intersect this doc's `owns:` |
+| Code | the doc's `owns:` globs, resolved to the files that exist today |
+| Precedent | the quotations from guardrails, accepted decisions, and doctrine that **name** a subject this doc covers — the naming words only, with `path:line` |
+| Already tracked | backlog and register rows that name a subject this doc covers, as `path:line` |
+| Rulings | owner answers that bind this subject, verbatim |
+| Read budget | the two clauses below, verbatim |
+
+The two clauses every pack carries:
+
+> Tree state: re-check every citation against today's tree before acting; a claim that fails to reproduce dies as *did not reproduce* — never becomes an edit. READ-ONLY everywhere except your one output file.
+
+> Read budget: the pack is your reading list — read nothing outside it without naming in your return why the pack was insufficient. Grep before you read; never read a file over 20 KB without a line range; read a file once. Compose one shell block per question, not one call per file.
+
+## The roles
+
+| Role | Agent | Receives | Writes | Returns |
+| --- | --- | --- | --- | --- |
+| Finder | `polygraph-finder` | the pack path, the partial path | `partials/{doc}.psv` — one row per claim, ten fields, no header | ≤ 120 words: the file path, row count, up to three findings, limitations |
+| Verifier | `polygraph-verifier` | a queue of `id`, `subject`, `claim` — no evidence, no verdict | `verify-{group}.psv` | ≤ 120 words: the file path and counts per check |
+| Applier | `polygraph-applier` | the packet path, the pack path | the packet's docs; `apply-{doc}.psv` | ≤ 120 words: counts per outcome, docs touched, lint result, anything for the register |
+
+Each agent definition carries its role's doctrine and its turn cap; a dispatch names the target and the paths and nothing else. **Findings go in the file, never in the return** — every word returned is re-billed on every later turn of the session.
+
+Where the runtime has no such agent installed, dispatch an independent subagent on the cheapest capable tier with the agent file's body pasted in as its brief, and say so in the report.
+
+## Packets — one doc, one applier
+
+Routing is judgment, so you compose packets by hand; `audit.mjs` asserts the one mechanical invariant: **no document appears in two packets** — appliers run in parallel, and two agents in one file silently lose each other's edits.
+
+**Packet by the doc the fix belongs in, not the doc a row's evidence cites.** A row's citations say where the *evidence* lives; the fix usually belongs elsewhere, and a bounced row's `needs-cross-doc` note says exactly where. A row with no derivable doc goes to the owner — never into a packet "to see what the agent makes of it".
+
+By verdict: QUESTION and `depends_on` rows → the owner, inline. CONTESTED → you, with both sets of evidence. RESIDUE, and any row whose subject is a source file — a stale comment included — → the register. Everything else → the owning doc's packet.
+
+## Verification — budgeted by what it caught
+
+- **The applier re-check is the law.** In the proving run it killed more false positives than every other mechanism combined.
+- **Blind re-derivation is discretionary.** Send a row *you* doubt — claim and subject only. As a mandatory stage it refuted nothing: finders' self-doubt is conservative, and the errors live in the confident pile, which is where your own read of the evidence looks. Disagreement makes the row CONTESTED; a verification never overwrites a verdict.
+
+## Fold-back
+
+After each applier returns, its outcomes become row state by your own edit, then `audit.mjs` checks the arithmetic:
+
+- `applied` · `registered` · `exempt-frozen` → `resolved`, the resolution stamped with how.
+- `refuted-on-apply` → `resolved`, resolution `did not reproduce`. A legitimate death; its count is the quality signal you report.
+- `needs-cross-doc` · `blocked-on-question` · `skipped` → stays open — repacket, or hold for the answer.
+- COHERENT rows close when recorded; they carry no work.
+
+## Recovery
+
+**The file on disk is the recovery unit, never the wave.** A dead agent costs its remainder; read what landed and relaunch only that. A finder that returns **partial** at its turn cap is resumed once from its partial — a second partial is accepted as that doc's sweep and named as such in the report. Every dispatch names its output file and a time bound; an agent past its bound with no file is dead — relaunch it, never wait on it, and never let one runaway agent hold the run. Gates — lint, links, ownership — run in your own seat.
+
+## Price
+
+State before dispatching, whenever a run exceeds ten documents or an owner directive names a tier: the per-doc cost at the pinned tier, the wave count under the concurrency ceiling, and the total; for a stronger tier, the multiplier and both totals. The directive and the estimate go in the changelog entry.

package/data/harnesses/code/skills/polygraph/references/rows.md

@@ -0,0 +1,57 @@
+# Rows — the row, the verdicts, the residue guard
+
+Load when: writing or reading any row, judging a CONTESTED or QUESTION row, deciding whether a subject is residue, or ruling on a document's right to exist.
+
+## The row
+
+Pipe-delimited, one row per claim, **ten fields**, header line first. A literal `|` inside text is written `¦`; a newline becomes `; `.
+
+```
+id|subject|claim|evidence|counter_evidence|verdict|confidence|depends_on|status|resolution
+```
+
+| Field | Content |
+| --- | --- |
+| `id` | `{DOC}-{NNN}` — the target document's stem and a running number, unique within the run |
+| `subject` | the stable key — a file, table, route, command, or surface |
+| `claim` | one sentence: what is asserted true or false |
+| `evidence` | verbose support — `file:line` citations or the exact command and its result. **No citation, no row.** A verdict leaning on a precedent quotes the precedent's naming words here |
+| `counter_evidence` | what cuts the other way, including `already-registered: path:line` for a known item |
+| `verdict` | one of the seven below |
+| `confidence` | 0.0–1.0, honest — a signal that tells the primary where to look, never a routing key |
+| `depends_on` | empty, or the owner question the row waits on, as the question's own words in brief |
+| `status` | `open` · `resolved` · `reopened` |
+| `resolution` | how it closed — `applied` · `registered` · `did not reproduce` · `answered` · `exempt-frozen` — empty while open |
+
+**A negative claim about a long document quotes the passage read** — the sentence believed wrong, or the section where the missing statement should live. Unsupported negative claims are the dominant false-positive class, and they concentrate in the longest documents.
+
+## The seven verdicts
+
+| Verdict | Meaning | Disposition |
+| --- | --- | --- |
+| `COHERENT` | doc and code agree — emitted at the audited unit so coverage is countable; closed when recorded | none |
+| `MISDESCRIBED` | the doc is wrong about built behaviour | an applier fixes the doc |
+| `UNDOCUMENTED` | code no doc claims — judged against the precedent pack **first**: condemned code is RESIDUE, never a documentation gap | an applier documents it in the owning doc |
+| `UNBUILT` | a documented design with no code behind it — decided-unbuilt (the repo's marker convention), abandoned, or a document that should die; only the owner distinguishes the last two, so suspecting either makes the row a QUESTION | the marker |
+| `RESIDUE` | code a standing decision condemns by name — running, even load-bearing, and still retiring | a register row, never a doc edit |
+| `CONTESTED` | the evidence conflicts — a verifier and a finder disagree, or a claim has no code to arbitrate and a sibling document says otherwise | the primary judges with both sets of evidence in hand |
+| `QUESTION` | only the owner can resolve it — intent, not evidence, is what is missing | asked inline, answered in the same pass |
+
+A disposition is the verdict's default; where the primary overrides it, the resolution says so. **A verification never overwrites a verdict** — disagreement makes the row CONTESTED.
+
+## The residue guard
+
+Before an UNDOCUMENTED row becomes a doc edit, its subject is tested against the precedent pack — the one place the audit can silently undo the repo's own decisions. The test is **naming**: a precedent matches only when it names the subject — the file, table, route, command, or surface by the product's own name for it — and the row quotes the naming words into `evidence`. A precedent describing a *resembling* thing is not a match; shared adjectives ("legacy", "old export lane") are not a match; a misread pronoun is not a match. Unsure → QUESTION, never a silent RESIDUE.
+
+The asymmetry runs both ways. A missed match resurfaces: the register is owner-read, and an UNDOCUMENTED row that should have been RESIDUE is caught when the owner reads the doc it produced. A false match does not: it retires code the product still ships and withholds its documentation — worse than the disease. When in doubt, ask.
+
+## Frozen records and code
+
+- **Frozen records are exempt** — a completed plan, a changelog entry, an archived document resolves `exempt-frozen`; its claims were true when frozen and the tree does not correct history.
+- **The audit never edits code.** A code-side finding — a bug, a stale source comment, the unbuilt, residue — exits as a register row for the planning workflow, however small the edit and however directly it is asked for. **Markdown is not source**: every document read may be edited under the applier discipline, package and root READMEs included; the line is doc versus code, not proximity to `src/`.
+
+## A document's right to exist
+
+A wholly stale document passes a sentence-by-sentence audit one true sentence at a time, so a finder that reads a document whose subject is gone, whose authority another doc has absorbed, or whose content belongs inside a sibling emits **one QUESTION row proposing deletion or merge**, carrying the inbound-reference count (who links here, which index rows list it, which ownership globs it claims). Deletion is owner-approved, always. An approved deletion removes the file, repoints every inbound reference to the surviving authority, and leaves **no redirect stub** — an annotation, a banner, or a status flag left in the reading path is not a source of truth however carefully the surviving sentences are hedged. A document whose subject survives but whose content is wrong is MISDESCRIBED, not a deletion candidate.
+
+**Abandonment has no marker.** A design decided against is not owed: its claims come **out** of every marker that carried them rather than being reworded inside one, and the document survives as the record of a decision not to build, its status saying so. The tell that this went wrong: a reader finishes the paragraph still expecting the feature.

package/data/harnesses/code/skills/polygraph/scripts/audit.mjs

@@ -0,0 +1,113 @@
+// skills/polygraph/scripts/audit.mjs - The audit's one script, and it is READ-ONLY: it validates
+// the run's findings file, cross-checks verifier and applier outcome files against the rows, and
+// asserts the packet-collision invariant. It never writes a byte — the primary holds the pen;
+// this holds the arithmetic. A checker that is wrong emits a wrong warning; a script that acted
+// on its own verdicts could destroy a refutation with no tally, which is the defect class this
+// replaces.
+//
+// Usage: node audit.mjs <run-dir>     (the run folder holding findings.psv)
+// Exit:  0 clean · 1 findings to read · 2 unusable input
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const HEADER = 'id|subject|claim|evidence|counter_evidence|verdict|confidence|depends_on|status|resolution';
+const FIELDS = HEADER.split('|').length; // 10
+const VERDICTS = new Set(['COHERENT', 'MISDESCRIBED', 'UNDOCUMENTED', 'UNBUILT', 'RESIDUE', 'CONTESTED', 'QUESTION']);
+const STATUSES = new Set(['open', 'resolved', 'reopened']);
+const RESOLVING = new Set(['applied', 'exempt-frozen', 'refuted-on-apply']);
+const STAYING = new Set(['needs-cross-doc', 'blocked-on-question', 'skipped']);
+const CHECKS = new Set(['CONFIRMED', 'REFUTED', 'ADJUSTED']);
+
+const run = process.argv[2];
+if (!run || !existsSync(run) || !statSync(run).isDirectory()) { console.error('usage: node audit.mjs <run-dir>'); process.exit(2); }
+const findingsPath = join(run, 'findings.psv');
+if (!existsSync(findingsPath)) { console.error(`no findings file at ${findingsPath}`); process.exit(2); }
+
+const problems = [];   // schema violations and cross-check disagreements → exit 1
+const notes = [];      // informational — never fails the run
+
+// ---- parse + validate the working file -------------------------------------------------------
+const lines = readFileSync(findingsPath, 'utf8').split('\n');
+if (lines[0].trim() !== HEADER) { console.error(`bad or missing header line in ${findingsPath}`); process.exit(2); }
+
+const rows = new Map(); // id → { verdict, status, resolution, line }
+for (let n = 1; n < lines.length; n++) {
+  const line = lines[n];
+  if (!line.trim()) continue;
+  const p = line.split('|');
+  const at = `line ${n + 1}`;
+  if (p.length !== FIELDS) { problems.push(`${at}: ${p.length} fields, expected ${FIELDS}`); continue; }
+  const [id, , claim, evidence, , verdict, confidence, , status, resolution] = p;
+  if (!id.trim()) { problems.push(`${at}: empty id`); continue; }
+  if (rows.has(id)) problems.push(`${at} (${id}): duplicate id — first seen at line ${rows.get(id).line}`);
+  if (!VERDICTS.has(verdict)) problems.push(`${at} (${id}): unknown verdict "${verdict}"`);
+  const conf = Number(confidence);
+  if (!(conf >= 0 && conf <= 1)) problems.push(`${at} (${id}): confidence "${confidence}" outside 0..1`);
+  if (!STATUSES.has(status)) problems.push(`${at} (${id}): unknown status "${status}"`);
+  if (status === 'resolved' && !resolution.trim())
+    problems.push(`${at} (${id}): resolved with an empty resolution — how did it close?`);
+  if (!claim.trim() || !evidence.trim())
+    problems.push(`${at} (${id}): empty ${!claim.trim() ? 'claim' : 'evidence'} — no citation, no row`);
+  rows.set(id, { verdict, status, resolution, line: n + 1 });
+}
+
+// ---- cross-check outcome files against row status --------------------------------------------
+const files = readdirSync(run).filter((f) => f.endsWith('.psv'));
+
+// apply-*.psv → id|outcome|note
+for (const f of files.filter((f) => f.startsWith('apply-'))) {
+  for (const line of readFileSync(join(run, f), 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    const [id, outcome] = line.split('|').map((s) => (s ?? '').trim());
+    const row = rows.get(id);
+    if (!row) { problems.push(`${f}: outcome for unknown row "${id}"`); continue; }
+    if (!RESOLVING.has(outcome) && !STAYING.has(outcome)) { problems.push(`${f} (${id}): unknown outcome "${outcome}"`); continue; }
+    if (RESOLVING.has(outcome) && row.status === 'open')
+      problems.push(`${f} (${id}): outcome "${outcome}" but the row is still open — the fold missed it`);
+  }
+}
+
+// verify-*.psv → id|check|confidence|citations|note ; disagreement across files is a finding
+const seenChecks = new Map(); // id → { check, file }
+for (const f of files.filter((f) => f.startsWith('verify-'))) {
+  for (const line of readFileSync(join(run, f), 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    const [id, check] = line.split('|').map((s) => (s ?? '').trim());
+    const row = rows.get(id);
+    if (!row) { problems.push(`${f}: verification of unknown row "${id}"`); continue; }
+    if (!CHECKS.has(check)) { problems.push(`${f} (${id}): unknown check "${check}" — CONFIRMED/REFUTED/ADJUSTED only`); continue; }
+    const earlier = seenChecks.get(id);
+    if (earlier && earlier.check !== check)
+      problems.push(`${id}: two verifiers disagree — ${earlier.check} in ${earlier.file}, ${check} in ${f} → the row is CONTESTED, judge it`);
+    else seenChecks.set(id, { check, file: f });
+    if (check === 'REFUTED' && row.verdict !== 'CONTESTED' && row.status !== 'reopened')
+      notes.push(`${id}: a verifier REFUTED this row and it is neither CONTESTED nor reopened — judged already, or missed?`);
+  }
+}
+
+// packets/*.txt → `doc: path` lines; no doc in two packets
+const packetsDir = join(run, 'packets');
+if (existsSync(packetsDir)) {
+  const claims = new Map(); // doc → packet file
+  for (const f of readdirSync(packetsDir).filter((f) => f.endsWith('.txt'))) {
+    for (const line of readFileSync(join(packetsDir, f), 'utf8').split('\n')) {
+      const m = /^doc:\s*(.+)$/.exec(line.trim());
+      if (!m) continue;
+      const doc = m[1].trim();
+      if (claims.has(doc)) problems.push(`packets: "${doc}" claimed by both ${claims.get(doc)} and ${f} — two appliers in one file lose edits`);
+      else claims.set(doc, f);
+    }
+  }
+}
+
+// ---- report -----------------------------------------------------------------------------------
+const total = rows.size;
+const resolved = [...rows.values()].filter((r) => r.status === 'resolved').length;
+const hist = {};
+for (const r of rows.values()) hist[r.verdict] = (hist[r.verdict] || 0) + 1;
+console.log(`rows: ${total} · resolved: ${resolved} · open: ${total - resolved}`);
+console.log(`verdicts: ${Object.entries(hist).map(([k, v]) => `${k} ${v}`).join(' · ') || 'none'}`);
+for (const n of notes) console.log(`~ ${n}`);
+for (const p of problems) console.log(`✗ ${p}`);
+console.log(problems.length ? `${problems.length} finding(s) to read` : 'clean');
+process.exit(problems.length ? 1 : 0);

package/data/harnesses/delivery/harness.json

@@ -1,7 +1,7 @@
 {
   "harness": "delivery",
   "name": "delivery",
-  "version": "0.2.28",
+  "version": "0.2.30",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
@@ -10,5 +10,5 @@
   "seeds": [],
   "tools": [],
   "docsRoot": "docs",
-  "digest": "432c8344e384"
+  "digest": "688776066c84"
 }

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