@davidbalzan/groundwork 0.4.1 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidbalzan/groundwork",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Groundwork — an installable AI development workflow (skills + doc methodology) you bolt onto any repo.",
   "type": "module",
   "bin": {
@@ -29,7 +29,7 @@
   "author": "David Balzan",
   "license": "UNLICENSED",
   "dependencies": {
-    "@davidbalzan/groundwork-seam": "0.1.5"
+    "@davidbalzan/groundwork-seam": "0.1.6"
   },
   "scripts": {
     "groundwork": "node src/cli.mjs",

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