@davidbalzan/groundwork 0.4.0 → 0.4.2

package/LICENSE

@@ -1,16 +1,14 @@
-MIT License
-
 Copyright (c) 2026 David Balzan
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+All rights reserved.
+
+This software and its accompanying files are proprietary. No licence is
+granted to use, copy, modify, merge, publish, distribute, sublicense, or sell
+copies of this software, in whole or in part, except by a separate written
+agreement signed by the copyright holder.
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+Possession of these files — including by download from a public package
+registry — does not constitute such an agreement and grants no rights.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidbalzan/groundwork",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Groundwork — an installable AI development workflow (skills + doc methodology) you bolt onto any repo.",
   "type": "module",
   "bin": {
@@ -13,7 +13,8 @@
     "src",
     "payload",
     "docs",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "keywords": [
     "ai",
@@ -26,9 +27,9 @@
     "methodology"
   ],
   "author": "David Balzan",
-  "license": "MIT",
+  "license": "UNLICENSED",
   "dependencies": {
-    "@davidbalzan/groundwork-seam": "0.1.3"
+    "@davidbalzan/groundwork-seam": "0.1.6"
   },
   "scripts": {
     "groundwork": "node src/cli.mjs",

package/payload/doc-templates/FACTS.md

@@ -38,6 +38,6 @@ glyphs, not ASCII. Parsers (doctor, `set-fact.mjs`, UIs) split on those glyphs.
 ## Facts
 
 <!-- add entries in the pinned format above, e.g.:
-     - `auto-disavow-flag` — does NOT exist anywhere in the codebase
-       verified: 2026-07-02T14:30Z · by: disavow-worker-1 · method: git grep + gh api origin/main
+     - `nightly-export-job` — does NOT exist anywhere in the codebase
+       verified: 2026-07-02T14:30Z · by: <project>-worker-1 · method: git grep + gh api origin/main
 -->

package/payload/doc-templates/WORKSTREAMS.md

@@ -25,7 +25,13 @@ Update with `/update-workstreams`.
 | ------ | ------------- | ----------------- | ------ | ------- | --------- |
 | —      | —             | —                 | ⏳ Queued | —    | Run `/kickstart`, then `/plan-phase` to populate the backlog |
 
-Status: 🚧 In Progress · 🔍 In Review · ⏳ Queued · ⛔ Blocked · ✅ Done
+Status: 🚧 In Progress · 🔍 In Review · ⏳ Queued · ⛔ Blocked · 🚫 Unstaffable · ✅ Done
+
+⛔ **Blocked** promises a future in which the work resumes, so the `Blocker` column must name
+what would unblock it. 🚫 **Unstaffable** denies that future: the work will not be staffed at
+all (out of scope, superseded, a policy removal). A row read as *resume when the base settles*
+when it was never going to be staffed has already produced a GO against a standing ruling — the
+two states are not a nuance.
 
 ---
 

package/payload/doc-templates/templates/QUEUE_TEMPLATE.md

@@ -5,12 +5,12 @@ referencing the full task breakdown. Ad-hoc tasks (bug fixes, improvements) are
 the human. This file is intake only: live in-flight state lives in [[WORKSTREAMS]], completions
 are recorded in `docs/DONE.md`.
 
-**Write rule (single writer per file):** the human (or their planning proxy) writes here — add /
-reorder / remove / edit items, set priority (`P1`/`P2`/`P3`; top-to-bottom breaks ties), add
-constraints, acceptance criteria, or refs inline. Whoever executes work never edits this file — it
-reads the top unblocked item fresh and appends the completion to `docs/DONE.md` instead. Pruning
-satisfied items is the writer's job. No compare-and-swap ceremony needed: the filesystem enforces
-the boundary.
+**Write rule — ownership splits by ACTION, not by file.** The human (or their planning proxy)
+CURATES: add / reorder / remove / edit items, set priority (`P1`/`P2`/`P3`; top-to-bottom breaks
+ties), add constraints, acceptance criteria, refs. Whoever COORDINATES closes: it sets item status
+and moves what a merge satisfied to `docs/DONE.md`, and pruning it here is its obligation, not its
+permission. Solo, or with no coordinator, you do both. Whoever executes work reads the top unblocked
+item fresh and edits neither. Assigning the FILE to one role is what once left `prune` unowned.
 
 ## Queue
 

package/payload/skills/update-workstreams/SKILL.md

@@ -53,8 +53,11 @@ parse-only.
 - ✅ Phase 1 · Foundation — agent-api · `feat/phase1` · merged YYYY-MM-DD
 ```
 
-Guidelines: status = 🚧 In Progress · 🔍 In Review · ⏳ Queued · ⛔ Blocked · ✅ Done. Record
-branch + worktree so any agent can resume the exact context. `Blocker` names the dependency
-(another stream, a decision, a person), not just "yes". Dates `YYYY-MM-DD`.
+Guidelines: status = 🚧 In Progress · 🔍 In Review · ⏳ Queued · ⛔ Blocked · 🚫 Unstaffable · ✅ Done.
+Record branch + worktree so any agent can resume the exact context. `Blocker` names the
+dependency (another stream, a decision, a person), not just "yes" — ⛔ Blocked promises the work
+resumes, so it must say what would end the block. Use 🚫 Unstaffable when it will not be
+staffed at all; expressing that as ⛔ Blocked has been read as *resume later* and scoped into a
+GO. Dates `YYYY-MM-DD`.
 
 Progress to record: $ARGUMENTS

package/src/commands/doctor.mjs

@@ -1,12 +1,13 @@
 import fs from "node:fs";
 import path from "node:path";
+import { execFileSync } from "node:child_process";
 import { TARGET, PKG_ROOT } from "../lib/paths.mjs";
 import { exists, readText, walk, listDirs } from "../lib/fs.mjs";
 import { countCheckboxes, progressBar } from "../lib/progress.mjs";
-import { ARTIFACTS } from "../lib/artifacts.mjs";
+import { ARTIFACTS, workDocPaths } from "../lib/artifacts.mjs";
 import { log, bold, green, yellow, dim, cyan } from "../lib/log.mjs";
 import { adrTripwire } from "../lib/adr-tripwire.mjs";
-import { parseFactsDoc, parseWorkDoc, workDocIssues, workDocLegacyWriteIssues } from "@davidbalzan/groundwork-seam";
+import { parseFactsDoc, parseWorkDoc, workDocIssues, workDocLegacyWriteIssues, workDocIssuesDetailed, queueItemsOf, doneEntriesOf, workstreamsV1RowsOf } from "@davidbalzan/groundwork-seam";
 
 /**
  * `groundwork doctor` — flag drift between the docs and reality. Offline + deterministic.
@@ -45,6 +46,36 @@ export function collectDoctor(targetDir) {
   const mdFiles = [...walk(docs)].filter((f) => f.endsWith(".md"));
   const phaseDir = path.join(docs, "phases");
 
+  // THE POPULATION COMES FROM THE MANIFEST, never from a filename in a checker.
+  //
+  // Three checks shipped on 2026-08-28 reading `docs/QUEUE.md` and nothing else.
+  // Four hours later 31 of 52 items were moved, deliberately and correctly, into
+  // `docs/phases/phase4/ITEMS.md` — and every one of those checks kept reporting
+  // green about a file that no longer held most of the work. Nothing broke; the
+  // population narrowed underneath a check trusted for the whole of it. Same
+  // shape as a hand-typed path list, which is the defect `doc-registration`
+  // already exists to catch, arriving from the other direction.
+  //
+  // `phaseN` in a manifest path is a placeholder, expanded against the phase
+  // directories that actually exist.
+  const declaredDocs = (grammar) => {
+    const out = [];
+    for (const decl of workDocPaths(grammar)) {
+      const rel = decl.replace(/^docs\//, "");
+      if (!rel.includes("phaseN")) {
+        if (exists(path.join(docs, rel))) out.push(rel);
+        continue;
+      }
+      if (!exists(phaseDir)) continue;
+      for (const dir of listDirs(phaseDir)) {
+        const candidate = rel.replace("phaseN", dir);
+        if (exists(path.join(docs, candidate))) out.push(candidate);
+      }
+    }
+    return out;
+  };
+  const queueDocs = declaredDocs("queue.v1");
+
   guard("orphan-wikilinks", () => {
   const valid = validLinkTargets(docs, mdFiles);
   const orphanItems = [];
@@ -155,23 +186,691 @@ guard("workstreams", () => {
   const wsFile = path.join(docs, "WORKSTREAMS.md");
   if (exists(wsFile)) {
     const wsDoc = parseWorkDoc(readText(wsFile));
-    const wsIssues = [...workDocIssues(wsDoc), ...workDocLegacyWriteIssues(wsDoc)];
-    if (wsIssues.length) push("workstreams", "warn", wsIssues);
+    const found = [
+      ...workDocIssuesDetailed(wsDoc),
+      ...workDocLegacyWriteIssues(wsDoc).map((message) => ({ level: "warn", message })),
+    ];
+    const hard = found.filter((i) => i.level === "warn");
+    // Hard failures first, always — a board that does not parse must not sit
+    // below advisories about style.
+    const wsIssues = [...hard, ...found.filter((i) => i.level !== "warn")].map((i) => i.message);
+    if (hard.length) push("workstreams", "warn", wsIssues);
+    else if (wsIssues.length) push("workstreams", "info", wsIssues);
     else push("workstreams", "ok", ["write grammar is workstreams.v1"]);
   } else push("workstreams", "info", ["no WORKSTREAMS.md yet (run `groundwork update --docs`)"]);
   });
 
 
+// Severity here means ONE thing: is anyone expected to act?
+//
+// This check pushed every finding at `warn`, and a fleet's deliberate
+// headline+body items produced 17 benign warnings in a single run — "the heading
+// is already good", David. A GENUINE `workstreams.v1` parse failure appeared in
+// that same run and was harder to see for it, and was found by David looking at
+// his console rather than by anyone reading the report. Seventeen unactionable
+// warnings trained the reader to skim, which is what let the real one through.
+//
+// So the one-line rule is DEMOTED, not deleted: when the item's first line parses
+// the contract is satisfied and the body below it is a style choice. The token
+// cost of continuation lines is real for every agent reading the file, which is
+// why the advisory stays. A count is always reported — a checker that says only
+// "ok" tells you nothing about whether it looked at anything.
 guard("queue", () => {
-  const qFile = path.join(docs, "QUEUE.md");
-  if (exists(qFile)) {
-    const qIssues = workDocIssues(parseWorkDoc(readText(qFile)));
-    if (qIssues.length) push("queue", "warn", qIssues);
-    else push("queue", "ok", ["queue.v1 — one line per item"]);
+  if (!queueDocs.length) return;
+  const lines = [];
+  let hardCount = 0;
+  let softCount = 0;
+  for (const rel of queueDocs) {
+    const qDoc = parseWorkDoc(readText(path.join(docs, rel)));
+    const items = queueItemsOf(qDoc);
+    const open = items.filter((i) => !i.done).length;
+    // A declared queue doc parsing to ZERO items is not a clean queue, it is a
+    // file the grammar does not recognise. `ITEMS.md` held 31 byte-identical
+    // `- [ ] (P2) …` lines and yielded nothing, because queue.v1 reads items only
+    // under a `## Queue` h2 — the manifest pointed at something the seam will not
+    // read, which is worse than not declaring it at all.
+    if (items.length === 0) {
+      hardCount++;
+      lines.push(
+        `docs/${rel} is declared queue.v1 and parsed to ZERO items — the grammar does not recognise it (items live under a \`## Queue\` h2), so every queue check is silently blind to this file`,
+      );
+      continue;
+    }
+    const found = workDocIssuesDetailed(qDoc);
+    const hard = found.filter((i) => i.level === "warn");
+    hardCount += hard.length;
+    softCount += found.length - hard.length;
+    lines.push(`docs/${rel}: ${items.length} item(s), ${open} open — queue.v1`);
+    for (const i of hard) lines.push(`  ${i.message}`);
+    for (const i of found) if (i.level !== "warn") lines.push(`  ${i.message}`);
   }
+  if (hardCount) push("queue", "warn", lines);
+  else if (softCount) push("queue", "info", lines);
+  else push("queue", "ok", lines.map((l) => `${l} — one line per item`));
   });
 
 
+// A queue item ticked `[x]` with no matching entry in DONE.md.
+//
+// This replaces a discipline that failed THREE TIMES on 2026-08-27 with the rule
+// visible: twelve unmoved items in the morning, two in the afternoon after David
+// ruled on it in writing, and three more whose fixes had shipped and were never
+// closed. A reminder was already tried and did not hold — which is why this is a
+// check and not another note.
+//
+// The tie is the PR REFERENCE, not text similarity: a closed item cites the PR that
+// closed it and a DONE entry records the same ref, so matching them is mechanical
+// rather than a guess about wording. A closed item citing NO ref at all is its own
+// finding — it cannot be tied to anything, by anyone, ever.
+guard("queue-done-loop", () => {
+  const dFile = path.join(docs, "DONE.md");
+  if (!queueDocs.length || !exists(dFile)) return;
+  const closed = queueDocs.flatMap((rel) =>
+    queueItemsOf(parseWorkDoc(readText(path.join(docs, rel))))
+      .filter((i) => i.done)
+      .map((i) => ({ ...i, where: `docs/${rel}` })),
+  );
+  if (closed.length === 0) {
+    push("queue-done-loop", "ok", ["no closed items sitting in the queue"]);
+    return;
+  }
+  const REF = /(?:[\w.-]+\/[\w.-]+)?#(\d+)/g;
+  const doneDoc = parseWorkDoc(readText(dFile));
+  const doneEntries = doneEntriesOf(doneDoc);
+  // A DONE.md that does not PARSE yields zero entries, and every closed item would
+  // then read as unclosed — the check would blame the queue for a defect in the log.
+  // "No matching entry" and "nothing parsed" are different answers, and conflating
+  // them is the failure this whole check exists to catch, one file over.
+  if (doneEntries.length === 0 && readText(dFile).trim().length > 0) {
+    push("queue-done-loop", "warn", [
+      "DONE.md has content but parsed to ZERO entries — the loop cannot be checked, and this is not the same as clean",
+      "entries must read `- [x] <task> — owner/repo#N · YYYY-MM-DD` (done.v1); a `- ` bullet without `[x]` is prose to the parser",
+    ]);
+    return;
+  }
+  const doneRefs = new Set(
+    doneEntries.map((e) => String(e.ref ?? "").match(/#(\d+)/)?.[1]).filter(Boolean),
+  );
+  const problems = [];
+  for (const item of closed) {
+    const cited = [...String(item.text).matchAll(REF)].map((m) => m[1]);
+    const short = String(item.text).replace(/\s+/g, " ").slice(0, 70);
+    if (cited.length === 0) {
+      problems.push(`${item.where}: [x] item cites no PR, so nothing can tie it to DONE.md — "${short}…"`);
+    } else if (!cited.some((n) => doneRefs.has(n))) {
+      problems.push(`${item.where}: [x] item cites #${cited.join(", #")} but DONE.md has no entry for any of them — "${short}…"`);
+    }
+  }
+  if (problems.length) {
+    push("queue-done-loop", "warn", [
+      ...problems,
+      "move the item's closure into DONE.md — the queue is inbound work, DONE.md is the completion log",
+    ]);
+  } else {
+    push("queue-done-loop", "ok", [`${closed.length} closed item(s), each matched to a DONE.md entry`]);
+  }
+});
+
+// A queue that lost items without anyone intending it.
+//
+// `queue.v1` validates SHAPE — one line per item — and a scripted edit that DELETED
+// an item passed every check green, because a file with one fewer correct line is
+// still correctly shaped. Measured 2026-08-27: a Python edit collapsed two items into
+// one, the replacement text was never written, and an item's entire content was lost
+// under a green `queue.v1 ✓`.
+//
+// The baseline is the committed version of the same file. Where there is no git
+// history to compare against, this says so OUT LOUD rather than passing: "could not
+// check" and "nothing wrong" are different answers and today cost a day proving it.
+//
+// A DELIBERATE prune must pass, or the check is a wall rather than a guard and the
+// first person to close an item correctly learns to ignore it. Two acknowledgements
+// are accepted, both mechanical and both already part of the work:
+//
+//   1. The item was CLOSED — one of the PR refs it cited has an entry in DONE.md.
+//      That is the loop `queue-done-loop` enforces, read from the other end.
+//   2. The item was RETIRED — a `<!-- queue-prune: <text> -->` comment in QUEUE.md
+//      quotes enough of it to name it. A policy removal is not a completion and has
+//      no PR; the aide had to carry exactly that in PROSE once because no field
+//      could hold it.
+//
+// Anything left is an unacknowledged disappearance, which is precisely what an
+// accidental drop looks like.
+// THE BASELINE IS THE MERGE TARGET, NOT THE BRANCH TIP.
+//
+// This check compared against `HEAD` — the branch's own last commit — and that is
+// blind to the loss that actually happens. Measured live on kit#102: a record PR
+// cut before three items were added to `main` would have deleted all three on
+// merge, and this check printed `16 item(s), none lost against the committed copy`.
+// Green. From the BRANCH's point of view nothing was lost, because those items had
+// never existed there.
+//
+// It is the population rule with the axis rotated: the earlier instance narrowed
+// the set of FILES and was fixed by deriving them from the manifest; this narrows
+// the baseline IN TIME. The first fix did not generalise, and a partial
+// generalisation is worse than none — it made the check look principled.
+//
+// AND IT NAMES THE REF IT USED. The old output said "the committed copy", which is
+// a phrase, not a baseline: it does not distinguish branch tip from merge target,
+// so a reader could not tell which question had been answered. Print the ref.
+function resolveBaseline() {
+  const git = (args) =>
+    execFileSync("git", args, { cwd: docs, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  // THE TARGET TIP, NOT THE MERGE BASE — and this correction came from the test
+  // rather than from reasoning. The merge base is the point the branch DIVERGED
+  // from, so an item added to `main` AFTER the cut is not there either: comparing
+  // against it is exactly as blind as comparing against HEAD, for exactly the same
+  // reason. The question is "what is on the thing I am about to merge INTO that my
+  // branch does not have", and only the target's tip can answer it.
+  //
+  // A branch that legitimately CLOSES items will now show them as gone, which is
+  // correct and is what the acknowledgement paths are for: a ticked item, a DONE
+  // entry for a PR it cites, or a quoting prune comment.
+  for (const target of ["origin/main", "origin/master", "main", "master"]) {
+    try {
+      const sha = git(["rev-parse", "--verify", `${target}^{commit}`]);
+      return { ref: sha, label: `${target} (${sha.slice(0, 8)})` };
+    } catch {
+      /* not this one */
+    }
+  }
+  try {
+    const head = git(["rev-parse", "HEAD"]);
+    return {
+      ref: head,
+      label: `HEAD (${head.slice(0, 8)}) — NO INTEGRATION BRANCH FOUND, so this cannot see items lost to a stale base`,
+      degraded: true,
+    };
+  } catch {
+    return null;
+  }
+}
+
+guard("queue-item-loss", () => {
+  if (!queueDocs.length) return;
+  const baseline = resolveBaseline();
+  if (!baseline) {
+    push("queue-item-loss", "info", [
+      "not a git repository — item loss NOT checked against any baseline, which is different from checked and clean",
+    ]);
+    return;
+  }
+  const okLines = [];
+  const warnLines = [];
+  const infoLines = [];
+  for (const rel of queueDocs) lossOf(rel);
+  // A degraded baseline is a WARNING, not a footnote under a clean verdict: with no
+  // integration branch the check cannot answer the question it is trusted for, and
+  // "could not check" must never render as "checked and clean".
+  const degraded = baseline.degraded
+    ? [`baseline DEGRADED — comparing against ${baseline.label}`]
+    : [];
+  if (warnLines.length || degraded.length) {
+    push("queue-item-loss", "warn", [...degraded, ...warnLines, ...infoLines, ...okLines]);
+  } else if (infoLines.length) {
+    push("queue-item-loss", "info", [...infoLines, ...okLines]);
+  } else {
+    push("queue-item-loss", "ok", okLines);
+  }
+
+  function lossOf(rel) {
+  const qFile = path.join(docs, rel);
+  let committed;
+  try {
+    committed = execFileSync("git", ["show", `${baseline.ref}:./${rel}`], {
+      cwd: docs, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+    });
+  } catch {
+    infoLines.push(
+      `docs/${rel}: not present at ${baseline.label} — item loss NOT checked for this file, which is different from checked and clean`,
+    );
+    return;
+  }
+  const now = queueItemsOf(parseWorkDoc(readText(qFile)));
+  const before = queueItemsOf(parseWorkDoc(committed));
+  const key = (i) => String(i.text).replace(/\s+/g, " ").slice(0, 60);
+  const nowKeys = new Set(now.map(key));
+  const lost = before.filter((i) => !nowKeys.has(key(i)));
+  if (!lost.length) {
+    okLines.push(`docs/${rel}: ${now.length} item(s), none lost against ${baseline.label}`);
+    return;
+  }
+
+  const qText = readText(qFile);
+  const dFile = path.join(docs, "DONE.md");
+  const doneRefs = new Set();
+  if (exists(dFile)) {
+    for (const e of doneEntriesOf(parseWorkDoc(readText(dFile)))) {
+      const n = String(e.ref ?? "").match(/#(\d+)/)?.[1];
+      if (n) doneRefs.add(n);
+    }
+  }
+  const prunes = [...qText.matchAll(/<!--\s*queue-prune:([\s\S]*?)-->/g)].map((m) =>
+    String(m[1]).replace(/\s+/g, " ").trim(),
+  );
+  const acknowledged = (item) => {
+    // The item was already ticked in the committed copy. Moving a `[x]` item out is
+    // the intended prune — the tick IS the acknowledgement, and it is set-based
+    // rather than a count. Requiring ceremony for the ordinary closure is how a
+    // guard becomes a wall and then gets ignored.
+    if (item.done) return "closed";
+    const cited = [...String(item.text).matchAll(/(?:[\w.-]+\/[\w.-]+)?#(\d+)/g)].map((m) => m[1]);
+    if (cited.some((n) => doneRefs.has(n))) return "closed";
+    // The comment must QUOTE the item — its first 20 characters at least — not merely
+    // exist. A bare `<!-- queue-prune: tidied up -->` would acknowledge every future
+    // deletion in the file, forever. Twenty characters is the item's opening words and
+    // stops short of the trailing refs, which a policy retirement has no reason to copy.
+    const k = key(item).slice(0, 20);
+    if (k.length >= 8 && prunes.some((p) => p.includes(k))) return "retired";
+    return null;
+  };
+  const unexplained = [];
+  const explained = [];
+  for (const i of lost) {
+    const how = acknowledged(i);
+    if (how) explained.push(`${how}: "${key(i)}…"`);
+    else unexplained.push(`  "${key(i)}…"`);
+  }
+  const tally = `docs/${rel}: ${before.length} → ${now.length} item(s) (${lost.length} gone, ${explained.length} acknowledged)`;
+  if (unexplained.length) {
+    warnLines.push(
+      `${tally} — ${unexplained.length} disappearance(s) nobody accounted for:`,
+      ...unexplained.slice(0, 5),
+      "a shape check cannot see this: a file with one fewer correct line is still correctly shaped",
+      "close it (a DONE.md entry for a PR the item cites) or retire it (`<!-- queue-prune: <quote the item> -->`)",
+    );
+  } else {
+    okLines.push(tally, ...explained.map((e) => `  ${e}`));
+  }
+  }
+});
+
+// A work-doc on disk that the manifest does not declare.
+//
+// THE OTHER HALF OF DERIVING THE POPULATION, and without it the derivation is
+// worth nothing: a manifest-derived set finds exactly what the manifest names, so
+// a file nobody declared is invisible to it by construction. That is not a
+// smaller version of the old bug, it is the same bug — a check whose population
+// is narrower than the thing it is trusted for — reported green with more
+// machinery behind it.
+//
+// The shape is the signal: a file carrying `- [ ] (P1|P2|P3)` lines IS a queue,
+// whatever it is called and wherever it sits. `docs/phases/phase4/ITEMS.md` held
+// 31 of them four hours after three checks shipped watching one filename.
+guard("undeclared-work-docs", () => {
+  const declared = new Set(queueDocs);
+  const ITEM = /^- \[[ x]\] \((P1|P2|P3)\) /m;
+  // A TEMPLATE is not a queue, and this exclusion is not convenience — it is the
+  // over-reporting direction, which is the dangerous one. `QUEUE_TEMPLATE.md`
+  // holds an EXAMPLE item line. Declaring it to silence the warning would make
+  // every queue check read a specimen row as real work, so a false positive here
+  // manufactures exactly the defect the check exists to find.
+  const isTemplate = (rel) => /(^|\/)templates\//.test(rel) || /_TEMPLATE\.md$/i.test(rel);
+  const rogue = [];
+  for (const rel of mdFiles) {
+    if (declared.has(rel) || isTemplate(rel)) continue;
+    const text = readText(path.join(docs, rel));
+    const count = (text.match(/^- \[[ x]\] \((?:P1|P2|P3)\) /gm) ?? []).length;
+    if (count > 0 && ITEM.test(text)) rogue.push({ rel, count });
+  }
+  // Population size beside the verdict, always. "none undeclared" and "none
+  // undeclared out of 61 docs scanned" are different claims and only one of them
+  // is checkable — a scan that found nothing is a broken scan until it says how
+  // much it looked at.
+  const scanned = `${mdFiles.filter((r) => !isTemplate(r)).length} doc(s) scanned (templates excluded), ${declared.size} declared queue.v1`;
+  if (rogue.length) {
+    push("undeclared-work-docs", "warn", [
+      scanned,
+      ...rogue.map(
+        (r) => `docs/${r.rel} holds ${r.count} queue item(s) and is NOT declared queue.v1 in the manifest — no queue check reads it`,
+      ),
+      "declare it in src/lib/artifacts.mjs with `grammar: \"queue.v1\"` and re-run `groundwork artifacts` — a manifest-derived population cannot find what the manifest does not name",
+    ]);
+  } else {
+    push("undeclared-work-docs", "ok", [`${scanned}, no undeclared queue-shaped doc`]);
+  }
+});
+
+// A doc on disk that the artifact manifest does not know about.
+//
+// Doctor already reads ARTIFACTS to decide which links may resolve; nothing checks the
+// inverse — a doc that EXISTS and is registered nowhere. A hand-typed coverage list is
+// itself an instance of the duplication it is meant to catch (gate-inventory F4, which
+// this repo shipped twice today), and the cost was measured elsewhere: a drift guard
+// whose path list omitted a second queue file hid a WRONG CLOSURE, reporting clean
+// while DONE.md claimed a PR had closed an item it never delivered.
+//
+// Registered-ness is the property being checked, not correctness: an unregistered doc
+// is not wrong, it is UNGOVERNED — no writer, no reader, and no check knows to look at
+// it. That is exactly how a second queue file goes unnoticed.
+guard("doc-registration", () => {
+  if (!exists(docs)) return;
+  const known = new Set();
+  for (const a of ARTIFACTS) {
+    const p = String(a.path ?? "").replace(/\s*\(.*\)\s*/g, "").trim();
+    if (p) known.add(p.replace(/^docs\//, "").replace(/\/$/, ""));
+  }
+  let onDisk;
+  try {
+    onDisk = fs.readdirSync(docs).filter((f) => f.endsWith(".md"));
+  } catch {
+    return;
+  }
+  // A scan that found nothing is a broken scan, not a clean one (gate-inventory F1).
+  if (onDisk.length === 0) {
+    push("doc-registration", "info", ["no .md files directly under docs/ — nothing to check"]);
+    return;
+  }
+  const unregistered = onDisk.filter((f) => !known.has(f));
+  if (unregistered.length) {
+    push("doc-registration", "warn", [
+      ...unregistered.map((f) => `docs/${f} is not in the artifact manifest — no stated writer, reader, or purpose`),
+      "add it to src/lib/artifacts.mjs and re-run `groundwork artifacts`, or delete it — an unregistered doc is ungoverned, not merely undocumented",
+    ]);
+  } else {
+    push("doc-registration", "ok", [`${onDisk.length} doc(s) under docs/, all registered in the manifest`]);
+  }
+});
+
+// A merge and its phase checkbox, which nothing ties together.
+//
+// Measured elsewhere: a phase read 15 done / 13 open before FIVE component tasks were
+// merged and 15 done / 16 open after — real completion ~20 of 31, reported as 15. A
+// fleet-wide "tick your own checkbox" reminder was already tried and five more boxes
+// accumulated after it, which is why this is a guard and not another note.
+//
+// THE CITATION IS THE TIE, and it has to be: there is no other mechanical link between
+// a merge and a checkbox. A DONE.md entry or a commit subject naming `Phase <N> Task
+// <X.Y>` claims that box. Several tasks per line and per PR are normal (one PR closes
+// 1.1 and 1.2), so every id on the line is read, not just the first.
+//
+// BOTH DIRECTIONS, and the second is the worse error — a ticked box nobody merged
+// anything for reports progress that does not exist. It is enforced PER PHASE and only
+// once that phase cites at least one task, because zero of 67 DONE entries cited a task
+// id when this was written: enforcing it retroactively would flood every phase with
+// findings about a convention that did not exist yet, and a check whose first run
+// prints a hundred lines gets muted rather than read. A phase that has not adopted it
+// says so, at info — silence would read as compliance.
+guard("phase-checkbox", () => {
+  if (!exists(phaseDir)) return;
+
+  // `- [x] 1.1 <text>` inside docs/phases/phase<N>/PHASE*_TASKS.md.
+  const TASK_LINE = /^\s*-\s*\[( |x)\]\s*\*{0,2}(\d+\.\d+)\b/i;
+  const boxes = new Map(); // "4:1.1" -> { ticked, phase, id, file }
+  for (const rel of walk(phaseDir)) {
+    if (!/PHASE.*TASKS\.md$/i.test(rel)) continue;
+    const n = phaseNumberFromDir(rel.split(path.sep)[0]);
+    if (n == null) continue;
+    for (const line of readText(path.join(phaseDir, rel)).split("\n")) {
+      const m = TASK_LINE.exec(line);
+      if (!m) continue;
+      boxes.set(`${n}:${m[2]}`, { ticked: m[1] === "x", phase: n, id: m[2], file: rel });
+    }
+  }
+  if (boxes.size === 0) {
+    push("phase-checkbox", "info", ["no `N.M` task checkboxes in docs/phases — nothing to tie merges to"]);
+    return;
+  }
+
+  const claims = new Map(); // "4:1.1" -> where it was claimed
+  const CITE = /\bPhase\s+(\d+)\s+Tasks?\s+((?:\d+\.\d+)(?:\s*(?:,|and|&|\+|\/|·)\s*\d+\.\d+)*)/gi;
+  const harvest = (text, where) => {
+    for (const m of String(text).matchAll(CITE)) {
+      for (const id of String(m[2]).match(/\d+\.\d+/g) ?? []) {
+        const k = `${Number(m[1])}:${id}`;
+        if (!claims.has(k)) claims.set(k, where);
+      }
+    }
+  };
+  const dFile = path.join(docs, "DONE.md");
+  if (exists(dFile)) harvest(readText(dFile), "DONE.md");
+  // Merged PR subjects, as the item specifies. Offline and bounded; a shallow clone or
+  // a non-repo simply contributes no subjects, and DONE.md still carries the claims.
+  try {
+    const subjects = execFileSync("git", ["log", "-n", "500", "--format=%s"], {
+      cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+    });
+    harvest(subjects, "a merged PR subject");
+  } catch {
+    /* no git history — DONE.md remains the only claim source */
+  }
+
+  const adopted = new Set([...claims.keys()].map((k) => k.split(":")[0]));
+  const problems = [];
+  for (const [k, box] of boxes) {
+    const claimed = claims.get(k);
+    if (claimed && !box.ticked) {
+      problems.push(
+        `Phase ${box.phase} Task ${box.id} is claimed in ${claimed} but its checkbox is unticked (${box.file}) — the record says done, the file says open`,
+      );
+    } else if (!claimed && box.ticked && adopted.has(String(box.phase))) {
+      problems.push(
+        `Phase ${box.phase} Task ${box.id} is ticked but nothing cites it (${box.file}) — no DONE.md entry and no merged PR subject names it, so the progress it reports is unevidenced`,
+      );
+    }
+  }
+  const unadopted = [...new Set([...boxes.values()].map((b) => b.phase))].filter((n) => !adopted.has(String(n)));
+  if (problems.length) {
+    push("phase-checkbox", "warn", [
+      ...problems,
+      "cite the box in the DONE.md entry or the PR subject as `Phase <N> Task <X.Y>` — that citation is the only mechanical tie between a merge and its checkbox",
+    ]);
+  } else {
+    push("phase-checkbox", "ok", [
+      `${boxes.size} task checkbox(es), ${claims.size} cited, none contradicting`,
+      ...unadopted.map(
+        (n) =>
+          `phase${n} cites no task ids yet — a ticked box there is NOT checked against a merge (cite "Phase ${n} Task <X.Y>" in the DONE entry or PR subject)`,
+      ),
+    ]);
+  }
+});
+
+// A board that describes work older than the last thing that finished.
+//
+// The queue and DONE.md are written BY the work — a merge touches both as part of
+// itself. The board is written ABOUT it, only if someone remembers, which is why it is
+// the one live doc that goes stale. Confirmed here: the kit's own board sat at zero rows
+// with two lanes live while the roadmap asserted "Steady state (queue empty)" against 28
+// open items.
+//
+// AN EMPTY BOARD IS NOT A STALE BOARD, and that distinction is the whole difficulty —
+// the same one that produced the UNKNOWN badge (ADR-013). No rows means no work in
+// flight, which is a legitimate state and reports as such. Staleness is only meaningful
+// about rows that CLAIM to be live.
+guard("board-freshness", () => {
+  const wsFile = path.join(docs, "WORKSTREAMS.md");
+  const dFile = path.join(docs, "DONE.md");
+  if (!exists(wsFile) || !exists(dFile)) return;
+  const rows = workstreamsV1RowsOf(parseWorkDoc(readText(wsFile)));
+  if (rows.length === 0) {
+    push("board-freshness", "ok", ["board has no in-flight rows — an empty board is not a stale board"]);
+    return;
+  }
+  const dates = doneEntriesOf(parseWorkDoc(readText(dFile)))
+    .map((e) => e.date)
+    .filter((d) => /^\d{4}-\d{2}-\d{2}$/.test(String(d)))
+    .sort();
+  const newestDone = dates[dates.length - 1];
+  if (!newestDone) {
+    push("board-freshness", "info", ["no dated DONE.md entry to compare the board against"]);
+    return;
+  }
+  let boardWritten;
+  try {
+    boardWritten = execFileSync("git", ["log", "-1", "--format=%cs", "--", "WORKSTREAMS.md"], {
+      cwd: docs, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    boardWritten = "";
+  }
+  if (!boardWritten) {
+    push("board-freshness", "info", [
+      "no commit date for WORKSTREAMS.md (not a git repo, or the board is untracked) — freshness NOT checked, which is different from fresh",
+    ]);
+    return;
+  }
+  if (boardWritten < newestDone) {
+    push("board-freshness", "warn", [
+      `board last written ${boardWritten}, newest DONE.md entry ${newestDone} — ${rows.length} row(s) claim to be live and predate the last completion`,
+      "a merge writes DONE.md as part of the work and the board only if someone remembers; re-derive the rows or close them",
+    ]);
+  } else {
+    push("board-freshness", "ok", [`board written ${boardWritten}, newest completion ${newestDone} — not behind`]);
+  }
+});
+
+// A citation whose ADDRESS is dead while its CLAIM is still live.
+//
+// A caveat is an assertion with a shelf life and nothing expires it, so it outlives
+// its subject and becomes evidence for something no longer true. Only one half of
+// that is mechanizable, and the line is where a consumer fleet drew it and we agree:
+// **a citation can be checked for whether it still RESOLVES. Whether the text it
+// points at still MEANS what the citer claimed cannot be checked, only stated.**
+// This check does the first and says so about the second.
+//
+// IT UNDER-REPORTS ON PURPOSE, and that is the whole design. A naive resolver keyed
+// on the repo root was run over this corpus first: 52 citations → 34 "target not
+// found" + 5 "line out of range". Nearly all of it was the resolver being wrong —
+// citations here are written against an IMPLIED PACKAGE ROOT (`roles.ts:60` means
+// `packages/coord-mcp/src/roles.ts`), and a monorepo has 12 files called README.md.
+// A confident 39 findings would have sent someone to "fix" citations that were
+// correct, which is the same defect the check exists to catch, reproduced inside it.
+// So: a citation is reported ONLY when its file resolves to exactly ONE candidate and
+// the line is past that file's end. Ambiguous and unresolved ones are COUNTED and
+// named as a limit, never as findings.
+guard("citation-rot", () => {
+  const CITE = /`([A-Za-z0-9_./-]+\.(?:md|mjs|ts|tsx|json|sh)):(\d+)`/g;
+  const roots = [root, docs];
+  const pkgDir = path.join(root, "packages");
+  if (exists(pkgDir)) for (const d of listDirs(pkgDir)) roots.push(path.join(pkgDir, d), path.join(pkgDir, d, "src"));
+  const lineCount = (f) => {
+    // A trailing newline is a terminator, not a line — counting it lets a citation
+    // one past the end resolve as in-range, which is the only off-by-one that
+    // matters here because it under-reports.
+    try { const t = readText(f).replace(/\n$/, ""); return t === "" ? 0 : t.split("\n").length; } catch { return null; }
+  };
+  // WORK-DOCS ARE EXCLUDED, and this was measured rather than assumed: the first run
+  // flagged `DONE.md:343` twice, cited in a queue item — a citation belonging to
+  // ANOTHER FLEET's repo, quoted here as evidence in a report about dead citations.
+  // It resolved against our `docs/DONE.md` and was confidently wrong about a file it
+  // was never pointing at. A queue item is a REPORT containing quoted evidence; its
+  // citations belong to whoever reported them. Ours are the ones in our own docs.
+  const workDocs = new Set([...queueDocs, ...declaredDocs("done.v1")]);
+  const dead = [];
+  let checked = 0, ambiguous = 0, unresolved = 0, quoted = 0;
+  for (const rel of mdFiles) {
+    if (workDocs.has(rel)) {
+      quoted += [...readText(path.join(docs, rel)).matchAll(CITE)].length;
+      continue;
+    }
+    const text = readText(path.join(docs, rel));
+    for (const m of text.matchAll(CITE)) {
+      const [, cited, lineStr] = m;
+      const hits = roots.map((r) => path.join(r, cited)).filter((f) => exists(f));
+      const uniq = [...new Set(hits)];
+      if (uniq.length === 0) { unresolved++; continue; }
+      if (uniq.length > 1) { ambiguous++; continue; }
+      checked++;
+      const n = lineCount(uniq[0]);
+      if (n !== null && Number(lineStr) > n) {
+        dead.push(`docs/${rel} cites \`${cited}:${lineStr}\` but ${path.relative(root, uniq[0])} has ${n} line(s) — the address is dead, the claim may not be`);
+      }
+    }
+  }
+  const limit =
+    `${checked} citation(s) resolved and checked · ${ambiguous} ambiguous (a monorepo has many files of the same name) · ${unresolved} unresolved (written against an implied package root) · ` +
+    `${quoted} skipped in work-docs (quoted evidence, often another repo's) — ` +
+    "and this check verifies only that a citation RESOLVES, never that the cited text still says what the citer claimed";
+  if (dead.length) push("citation-rot", "warn", [...dead, limit]);
+  else push("citation-rot", "ok", [limit]);
+});
+
+// A document asserting a version, checked for TRUTH rather than freshness.
+//
+// `facts-freshness` already chases entries older than 14 days. Nothing compared a
+// claim against the mechanically-available source, so **a fact can be recently
+// verified and false** — five version facts were wrong at once, four of them in the
+// direction that reads healthier than reality.
+//
+// THE TWO CHECKS STAY SEPARATE, deliberately: a truth failure must not be reportable
+// as a freshness pass or vice versa, or one's green gets read as the other's. Same
+// reason the publish-path guards stay split (staleness vs inertness).
+//
+// SCOPE IS ANY DOCUMENT, not just FACTS.md — the wrong versions were in a version
+// table, which is precisely the document a reader trusts most.
+//
+// IT CHECKS ROWS, NOT PROSE, and that is a deliberate under-reach. Prose legitimately
+// discusses old versions ("0.5.10 shipped that defect") and flagging those would bury
+// the real finding under history. A markdown table row naming a package is making a
+// present-tense claim about it; if the authoritative version appears nowhere in that
+// row, the row is asserting something else.
+guard("version-truth", () => {
+  const kitFile = path.join(root, "kit.json");
+  if (!exists(kitFile)) return;
+  let pkgs;
+  try {
+    const kit = JSON.parse(readText(kitFile));
+    pkgs = Object.values(kit.packages ?? {}).filter((p) => p?.name && p?.version);
+  } catch (e) {
+    push("version-truth", "warn", [`kit.json is unreadable (${e.message}) — version claims NOT checked, which is not the same as true`]);
+    return;
+  }
+  if (!pkgs.length) {
+    push("version-truth", "info", ["kit.json declares no packages — nothing to check against"]);
+    return;
+  }
+  const stale = [];
+  let rows = 0;
+  let scanned = 0;
+  for (const rel of mdFiles) {
+    const text = readText(path.join(docs, rel));
+    // ONLY DOCUMENTS THAT CLAIM CURRENCY, detected by their own freshness marker
+    // rather than by a filename list. A dated design document stating the versions
+    // current when it was written is CORRECT, and the first run flagged nine such
+    // rows in `DESIGN.md`, a 2026-08-16 snapshot. Reporting those buries the real
+    // finding under history and teaches the reader to skim it.
+    // The marker must be in the HEADER, not anywhere in the prose: `DESIGN.md`
+    // contains the string `verified:` inside a CODE BLOCK 762 lines down, which is
+    // a type definition and not a currency claim about the document. A freshness
+    // stamp lives at the top or it is not a stamp.
+    if (!/Last audited|verified:/i.test(text.split("\n").slice(0, 15).join("\n"))) continue;
+    scanned++;
+    const lines = text.split("\n");
+    lines.forEach((line, i) => {
+      if (!line.startsWith("|")) return;
+      for (const p of pkgs) {
+        // Whole-name match. `@davidbalzan/groundwork-seam` CONTAINS
+        // `@davidbalzan/groundwork`, so `includes` reported the seam row as a
+        // groundwork row and named the wrong expected version — a substring match
+        // presented as a structural fact, in the check, one commit after that rule
+        // went into the canon.
+        if (!new RegExp(`${p.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?![\\w./-])`).test(line)) continue;
+        const seen = [...line.matchAll(/\b\d+\.\d+\.\d+\b/g)].map((m) => m[0]);
+        // A row naming a package but asserting NO version is not making a claim
+        // this check can contradict — a file map, a path table, an ownership row.
+        // The first run flagged eight of those, which is the over-report direction:
+        // it would send someone to add version numbers to a directory listing.
+        if (!seen.length) continue;
+        rows++;
+        if (seen.includes(p.version)) continue;
+        stale.push(
+          `docs/${rel}:${i + 1} states ${p.name} at ${seen.join(", ")} — kit.json says ${p.version}`,
+        );
+      }
+    });
+  }
+  const tally = `${rows} version-asserting row(s) in ${scanned} doc(s) that claim currency (a dated snapshot is not checked — it was true when written), against kit.json`;
+  if (stale.length) {
+    push("version-truth", "warn", [
+      ...stale,
+      `${tally} — a recently-verified fact can still be false, which is why this is not the freshness check`,
+    ]);
+  } else {
+    push("version-truth", "ok", [`${tally}, all current — and this checks TRUTH only; freshness is a separate check for a separate failure`]);
+  }
+});
+
 const factsFile = path.join(docs, "FACTS.md");
 guard("facts-freshness", () => {
   if (exists(factsFile)) {
@@ -238,7 +937,13 @@ export function doctor(targetDir, opts = {}) {
     "facts-freshness": "Facts",
     "adr-tripwire": "ADR tripwire",
   };
-  for (const c of report.checks) {
+  // WARNINGS FIRST in the human report. The same reason the queue advisory was
+  // demoted: a hard failure printed below a pile of advisories is a hard failure
+  // nobody reads. `--json` keeps registration order — a programmatic consumer
+  // sorts for itself and should not have its shape changed underneath it.
+  const rank = (c) => (c.level === "warn" ? 0 : c.level === "info" ? 2 : 1);
+  const ordered = [...report.checks].sort((a, b) => rank(a) - rank(b));
+  for (const c of ordered) {
     log.heading(titles[c.check] ?? c.check);
     for (const item of c.items) {
       if (c.level === "warn") console.log(`  ${yellow("⚠")} ${item}`);

package/src/lib/adr-tripwire.mjs

@@ -15,7 +15,7 @@ import path from "node:path";
  *
  * Shared-token suppression: tokens that also appear in the ADR title / Decision / Context
  * (alias-expanded) are the accepted path, not evidence of the reject. Generic project-wide
- * paths (`docs`, `templates`, `readme`, `wiki`) are not hits. Cass burned an audit cycle on
+ * paths (`docs`, `templates`, `readme`, `wiki`) are not hits. A consumer fleet burned an audit cycle on
  * `next` (accepted Next.js), top-level `docs/`, and `docs/templates`.
  */
 
@@ -85,7 +85,7 @@ const STOP = new Set(["the", "and", "with", "only", "over", "for", "app", "api",
 
 /**
  * Top-level / workspace path tokens that every repo tends to have. A hit on these is
- * project-wide, not evidence of a rejected alternative (cass: `docs/`, `docs/templates`).
+ * project-wide, not evidence of a rejected alternative (field report: `docs/`, `docs/templates`).
  * Dependency names are not filtered here — `next` still fires unless it is in `own`.
  */
 export const GENERIC_PATHS = new Set(["docs", "templates", "readme", "wiki"]);

package/src/lib/artifacts.mjs

@@ -6,14 +6,40 @@
  *   ("reference" = generic, same across projects → refreshable; "project" = yours → never touched)
  *
  * Add a doc in ONE place: append an entry here, then `groundwork artifacts` regenerates the map.
+ *
+ * `writtenBy` HOLDS TWO KINDS OF VALUE and the column says which by its shape:
+ *   - COMMAND-shaped (`/kickstart`, `/plan-phase`) — a skill generates the doc.
+ *   - ROLE-shaped (`aide`, `coordinator`, `David`) — a person or agent owns it,
+ *     and ownership means keeping it HONEST, not licence to rewrite what it records.
+ * Stated here rather than inferred, because a column quietly meaning two things is
+ * exactly how `(+ CONTEXT-MAP.md)` came to read as a registration to a human and as
+ * prose to every parser.
  */
 
 /** @typedef {"project"|"reference"|"external"} Scope */
+/**
+ * The write grammar a doc is parsed under, when it has one. This is what makes
+ * the manifest the SOURCE OF THE POPULATION for every work-doc check instead of
+ * a hardcoded filename, and it exists because the population moved: 31 items were
+ * moved out of `docs/QUEUE.md` into a phase file four hours after three checks
+ * shipped watching `QUEUE.md` and nothing else. Every check reported green about
+ * a file holding two thirds of the work.
+ *
+ * A `phaseN` segment is a placeholder — a consumer expands it against the phase
+ * directories that exist.
+ * @typedef {"queue.v1"|"done.v1"|"workstreams.v1"} Grammar
+ */
 
 export const ARTIFACTS = [
   // --- project artifacts (generated per project; vary; never auto-refreshed) ---
   { path: "docs/PRD.md", scope: "project", purpose: "Product definition (problem, users, goals, scope, requirements)", writtenBy: "/create-prd", readBy: "/kickstart, /plan-phase", rules: "First artifact; the source for scaffolding" },
-  { path: "docs/CONTEXT.md (+ CONTEXT-MAP.md)", scope: "project", purpose: "Ubiquitous-language glossary / domain model", writtenBy: "/domain-model", readBy: "/start-session, /plan-phase", rules: "Glossary only — no implementation detail" },
+  { path: "docs/CONTEXT.md", scope: "project", purpose: "Ubiquitous-language glossary / domain model", writtenBy: "/domain-model", readBy: "/start-session, /plan-phase", rules: "Glossary only — no implementation detail" },
+  // Declared on its OWN LINE, not as "(+ CONTEXT-MAP.md)" inside another path.
+  // A parenthetical reads as registration to a human and as prose to every
+  // checker: `doc-registration` strips it, so the file was ungoverned while a
+  // grep for its name in this file returned a hit. A carrier that satisfies a
+  // reader and not a parser is the same trap as the PR-title citation.
+  { path: "docs/CONTEXT-MAP.md", scope: "project", purpose: "Generated map of the domain model (companion to CONTEXT.md)", writtenBy: "aide (generated by /domain-model)", readBy: "/start-session, /plan-phase", rules: "David 2026-08-28: the aide owns it. Regenerated with CONTEXT.md; ownership is keeping it honest, not hand-editing the generator's output" },
   { path: "docs/TECH_STACK.md", scope: "project", purpose: "Technology choices narrative", writtenBy: "/kickstart", readBy: "/plan-phase, /start-session", rules: "No version numbers here — link to STACK_MAP" },
   { path: "docs/STACK_MAP.md", scope: "project", purpose: "Single source of truth for versions (pinned + latest)", writtenBy: "/kickstart, /check-versions", readBy: "anyone bumping deps", rules: "The only place a version appears" },
   { path: "docs/ARCHITECTURE_GUIDE.md", scope: "project", purpose: "System design, patterns, the \"why\"", writtenBy: "/kickstart", readBy: "/plan-phase", rules: "—" },
@@ -21,11 +47,14 @@ export const ARTIFACTS = [
   { path: "docs/PRODUCTION_ROADMAP.md", scope: "project", purpose: "Phase roadmap + \"Current Status\" pointer", writtenBy: "/kickstart, /plan-phase", readBy: "/start-session, groundwork status", rules: "Current Status points at WORKSTREAMS" },
   { path: "docs/phases/phaseN/README.md", scope: "project", purpose: "Phase overview", writtenBy: "/plan-phase", readBy: "/start-session", rules: "—" },
   { path: "docs/phases/phaseN/PHASEN_TASKS.md", scope: "project", purpose: "Detailed checkbox tasks", writtenBy: "/plan-phase", readBy: "/check-task, /start-session, groundwork status", rules: "Progress recomputed by the helper script" },
-  { path: "docs/WORKSTREAMS.md", scope: "project", purpose: "Live state of parallel streams", writtenBy: "/update-workstreams + coordinator", readBy: "everyone, /start-session", rules: "One row per active stream" },
-  { path: "docs/QUEUE.md", scope: "project", purpose: "Inbound queue (phases + ad-hoc)", writtenBy: "/plan-phase + human", readBy: "/start-session, coordinator", rules: "Single writer per file: human/proxy only; executors never edit it" },
-  { path: "docs/DONE.md", scope: "project", purpose: "Completion log", writtenBy: "executor (solo you or coordinator)", readBy: "/start-session, humans", rules: "Append-only; sole executor write in the queue seam; pinned em-dash+middot line format" },
+  { path: "docs/phases/phaseN/ITEMS.md", grammar: "queue.v1", scope: "project", purpose: "Queue items pulled into a phase, verbatim (the phase's working set)", writtenBy: "aide curates; coordinator sets status", readBy: "groundwork doctor, whoever executes the phase", rules: "queue.v1 — items live under a `## Queue` h2; `### Task N` groups them. Watched by the same checks as QUEUE.md" },
+  { path: "docs/WORKSTREAMS.md", grammar: "workstreams.v1", scope: "project", purpose: "Live state of parallel streams", writtenBy: "/update-workstreams + coordinator", readBy: "everyone, /start-session", rules: "One row per active stream" },
+  { path: "docs/QUEUE.md", grammar: "queue.v1", scope: "project", purpose: "Inbound queue (phases + ad-hoc)", writtenBy: "/plan-phase + human", readBy: "/start-session, coordinator", rules: "Single writer per file: human/proxy only; executors never edit it" },
+  { path: "docs/DONE.md", grammar: "done.v1", scope: "project", purpose: "Completion log", writtenBy: "executor (solo you or coordinator)", readBy: "/start-session, humans", rules: "Append-only; sole executor write in the queue seam; pinned em-dash+middot line format" },
   { path: "docs/DESIGN_SYSTEM.md", scope: "project", purpose: "Visual language (optional)", writtenBy: "/kickstart", readBy: "frontend work", rules: "Only when there's a UI" },
   { path: "docs/FACTS.md", scope: "project", purpose: "Verified project facts (settled world-model)", writtenBy: "whoever verified (or set-fact.mjs)", readBy: "everyone, groundwork doctor", rules: "One writer per fact; entries carry verified/by/method; doctor flags stale (>14d)" },
+  { path: "docs/DESIGN.md", scope: "project", purpose: "Monorepo structure + seam-extraction design (organization, package seams, file map, PR sequence)", writtenBy: "aide", readBy: "anyone touching package boundaries", rules: "David 2026-08-28: the aide owns it. ADR-governed (ADR-010) — ownership means keeping it HONEST, not licence to rewrite the spec" },
+  { path: "docs/NAMES.md", scope: "project", purpose: "Locked names — repo, packages, publish names, directories", writtenBy: "aide", readBy: "everyone", rules: "David 2026-08-28: the aide owns it. Names LOCKED by David 2026-08-16 — do not reopen in implementation PRs; a rename is David's call" },
   { path: "docs/_INDEX.md", scope: "project", purpose: "Obsidian Map of Content (human navigation)", writtenBy: "/kickstart (scaffold), then you", readBy: "humans, agents navigating docs", rules: "Curated per project — installed once, never auto-refreshed" },
 
   // --- reference (shipped, generic, same across projects → refreshable by `update --docs`) ---
@@ -40,6 +69,16 @@ export const ARTIFACTS = [
   { path: "$GROUNDWORK_KNOWLEDGE/adr/NNNN-*.md", scope: "external", purpose: "Formal cross-project ADRs", writtenBy: "/remember --adr" },
 ];
 
+/**
+ * Every path the manifest DECLARES under a given write grammar, `phaseN`
+ * placeholders included. The point is that no checker names a file: adding a
+ * fifth work-doc is a manifest entry, and forgetting to add one is what the
+ * undeclared-work-doc control catches from the other side.
+ */
+export function workDocPaths(grammar) {
+  return ARTIFACTS.filter((a) => a.grammar === grammar).map((a) => a.path);
+}
+
 /** Doc paths that `update --docs` may safely refresh (generic, not project-authored). */
 export function refreshableDocs() {
   return ARTIFACTS.filter((a) => a.scope === "reference" && a.path.endsWith(".md")).map(