@davidbalzan/groundwork 0.4.3 → 0.4.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidbalzan/groundwork",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "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.7"
+    "@davidbalzan/groundwork-seam": "0.1.8"
   },
   "scripts": {
     "groundwork": "node src/cli.mjs",

package/payload/doc-templates/DAVID_TASKS.md

@@ -0,0 +1,43 @@
+# Needs David
+
+Work the fleet **cannot do for itself**: things requiring David's hands, his
+accounts, his money, or his ruling.
+
+> **This file is not a queue, and the distinction is the reason it exists.**
+> Without it, David-blocked items sit in `QUEUE.md` at P1 looking exactly like
+> work the fleet can pick up — which is how a licence item read as actionable
+> for two days while nobody could have actioned it.
+>
+> So entries here carry **no `- [ ] (Pn)` checkbox lines**. That is deliberate
+> and load-bearing: a David-blocked list that parses as a queue *is* a queue,
+> and every queue check would start reading it as available work. If you find
+> yourself wanting a priority marker here, the item probably belongs in
+> `QUEUE.md` with a note that it is blocked.
+
+## How this differs from its neighbours
+
+- **`QUEUE.md`** — work the fleet can do. Prioritised, claimable, closeable.
+- **`WORKSTREAMS.md` § Needs David** — decisions in flight *right now*, with a
+  recommendation attached. Cleared within a session.
+- **this file** — the standing list of what is blocked ON DAVID and stays
+  blocked until he acts. It outlives any one session.
+
+## Blocked on David
+
+*One `###` block per item. Delete this heading's examples when the first real
+one lands.*
+
+### <short title>
+
+- **Needs:** what only David can do (publish · pay · approve · decide · access)
+- **Why it cannot be delegated:** the specific thing an agent lacks — a
+  credential, an account, an authority. "It is important" is not a reason.
+- **Blocked since:** YYYY-MM-DD
+- **Blocking:** what is waiting on it, or `nothing — it is just owed`
+- **If David does nothing:** the actual consequence, written plainly. An item
+  with no consequence for inaction is a preference, not a blocker.
+
+## Cleared
+
+*Move items here with the date and what David decided. Kept because "we asked
+and he said no" is a fact worth not re-litigating in three weeks.*

package/src/commands/doctor.mjs

@@ -7,7 +7,7 @@ import { countCheckboxes, progressBar } from "../lib/progress.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, workDocIssuesDetailed, queueItemsOf, doneEntriesOf, workstreamsV1RowsOf, sweepTagOf, sweepTagCensus } from "@davidbalzan/groundwork-seam";
+import { phaseCitationsIn, parseFactsDoc, parseWorkDoc, workDocIssues, workDocLegacyWriteIssues, workDocIssuesDetailed, queueItemsOf, doneEntriesOf, workstreamsV1RowsOf, sweepTagOf, sweepTagCensus, refsIn, refIn } from "@davidbalzan/groundwork-seam";
 
 /**
  * `groundwork doctor` — flag drift between the docs and reality. Offline + deterministic.
@@ -288,23 +288,40 @@ guard("queue-done-loop", () => {
     ]);
     return;
   }
-  const doneRefs = new Set(
-    doneEntries.map((e) => String(e.ref ?? "").match(/#(\d+)/)?.[1]).filter(Boolean),
-  );
+  // REFS ARE COMPARED WITH THE SHARED PRIMITIVE, not by number.
+  //
+  // This matched on the bare NUMBER, so an item whose body cited `console#39`
+  // tied to a `DONE.md` entry for `groundwork-kit#39` — two repositories, one
+  // number — and the check reported GREEN over the exact gap it exists to find.
+  // Measured live: `q-142d95da` was closed by #119 with no #119 entry in DONE.md,
+  // and this printed "1 closed item(s), each matched to a DONE.md entry".
+  //
+  // Fourth matcher in one day to re-derive ref/tag matching and get it wrong. The
+  // primitive lives in the seam now so the fifth one written cannot.
+  const doneRefs = doneEntries.flatMap((e) => refsIn(String(e.ref ?? "")));
   const problems = [];
   for (const item of closed) {
-    const cited = [...String(item.text).matchAll(REF)].map((m) => m[1]);
+    const cited = refsIn(String(item.text));
     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}…"`);
+    } else if (!cited.some((r) => refIn(r, doneRefs))) {
+      // NOT "this closure is unlogged" — the check cannot know that. The citation
+      // is the only tie it has, and an item whose body never names the PR that
+      // closed it is UNTIEABLE, even when DONE.md records the closure perfectly.
+      // Measured live: an item citing `kit#84` and `console#39` was closed by
+      // #119, and #119 IS in DONE.md — the item simply never mentions it.
+      // Reporting that as "no entry" would send someone to add a duplicate.
+      problems.push(
+        `${item.where}: [x] item cites ${cited.map((r) => r.raw).join(", ")}, none of which DONE.md records — so this closure CANNOT BE TIED by citation. ` +
+          `It may still be logged under a ref the item does not name; the tie, not the log, is what is missing — "${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",
+      "either DONE.md is missing the entry, or the item does not cite the PR that closed it — those are different fixes, and the citation is the only thing that distinguishes them",
     ]);
   } else {
     push("queue-done-loop", "ok", [`${closed.length} closed item(s), each matched to a DONE.md entry`]);
@@ -595,7 +612,9 @@ 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;
+  // A TASK ID MAY CARRY A LETTER SUFFIX — `3.3b` is a disposition clause, and this
+  // convention adds them constantly.
+  const TASK_LINE = /^\s*-\s*\[( |x)\]\s*\*{0,2}(\d+\.\d+[a-z]?)\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;
@@ -613,14 +632,33 @@ guard("phase-checkbox", () => {
   }
 
   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;
+  // B-CLAUSES BROKE THIS TWO WAYS, AND THE SECOND IS WORSE THAN THE TRUNCATION.
+  //
+  // The id pattern was `\d+\.\d+`, so `3.3b` matched as `3.3`:
+  //   `Phase 5 Task 3.1, 3.2, 3.3b, 3.4, 3.5` captured 3.1, 3.2, 3.3 — the list
+  //   SILENTLY TRUNCATED at the b-clause and 3.4/3.5 went from cited to
+  //   unevidenced with no warning.
+  //   `Phase 5 Task 3.3b` credited `3.3` — a MISATTRIBUTION, ticking a different
+  //   box than the one cited. The right answer arrived for the wrong reason once
+  //   today and would have credited a false claim just as readily.
+  //
+  // A GRAMMAR THAT DEGRADES IN PROPORTION TO BEING USED is worse than one that
+  // fails randomly, because adoption looks like decay — and every disposition
+  // clause this convention adds is a b-clause.
+  //
+  // GRANULARITY THIS FIX COVERS: the ID TOKEN — `3.3` and `3.3b` are now distinct
+  // ids, in both the citation and the checkbox.
+  // THE NEXT ONE DOWN, STATED RATHER THAN DISCOVERED: a deeper id (`3.3b.i`, or a
+  // two-letter `3.3ab`) still truncates the list at that point. Nothing in the
+  // corpus uses one today; if that changes, this is the line that needs widening,
+  // and the same silent-truncation failure returns until it is.
+  // ONE GRAMMAR, SHARED THROUGH SEAM. This was a local regex until the bus's
+  // `merge` verb needed the same answer at merge time; ADR-004 forbids a
+  // groundwork↔mcp edge, so a copy in each package was the obvious route — and
+  // a copied grammar is two grammars the moment one is fixed. This very token
+  // was widened for b-clauses today, which a second copy would have missed.
   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);
-      }
-    }
+    for (const k of phaseCitationsIn(text)) if (!claims.has(k)) claims.set(k, where);
   };
   const dFile = path.join(docs, "DONE.md");
   if (exists(dFile)) harvest(readText(dFile), "DONE.md");
@@ -860,7 +898,48 @@ guard("version-truth", () => {
       }
     });
   }
-  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`;
+  // THE PUBLISHED COLUMN IS A CLAIM TOO, and it is checked BY COLUMN.
+  //
+  // My first attempt at this compared every version in the ROW and passed as soon
+  // as one matched — which is the occurrence-not-position error at column
+  // granularity, in the check I wrote after landing that rule. It false-positived
+  // on a workspace-deps table and MISSED the live case: `STACK_MAP` stated
+  // playbook pinned 0.5.17 and published 0.5.16, and the row contained 0.5.17 so
+  // it passed. Second time in one day a bump left that table behind.
+  //
+  // So the header decides which cell is which. A table without a `Latest
+  // published` column makes no published claim and is not checked — absence of a
+  // claim is not a wrong claim.
+  for (const rel of mdFiles) {
+    const text = readText(path.join(docs, rel));
+    if (!/Last audited|verified:/i.test(text.split("\n").slice(0, 15).join("\n"))) continue;
+    const lines = text.split("\n");
+    let col = -1;
+    lines.forEach((line, i) => {
+      if (!line.startsWith("|")) {
+        col = -1;
+        return;
+      }
+      const cells = line.split("|").slice(1, -1).map((c) => c.trim());
+      if (/latest published/i.test(line)) {
+        col = cells.findIndex((c) => /latest published/i.test(c));
+        return;
+      }
+      if (col < 0 || col >= cells.length) return;
+      const named = pkgs.find((p) =>
+        p.published && new RegExp(`${p.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?![\\w./-])`).test(line),
+      );
+      if (!named) return;
+      const claim = (cells[col].match(/\b\d+\.\d+\.\d+\b/) ?? [])[0];
+      if (!claim || claim === named.published) return;
+      stale.push(
+        `docs/${rel}:${i + 1} states ${named.name} PUBLISHED at ${claim} — kit.json records ${named.published}. ` +
+          `Checked by COLUMN: a row can carry the right pinned version and a stale published one, and comparing the whole row passes on the pinned half.`,
+      );
+    });
+  }
+
+  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's version AND published records`;
   if (stale.length) {
     push("version-truth", "warn", [
       ...stale,
@@ -910,6 +989,47 @@ guard("sweep-census", () => {
   ]);
 });
 
+// A pin that states a count and cannot reproduce it.
+//
+// A STATED METHOD THAT CONTRADICTS ITS OWN PUBLISHED RESULT IS WORSE THAN NO
+// METHOD: it looks auditable, so it invites exactly the trust it cannot bear. The
+// board's `[SWEEP:canon.2]` pin says "13 members" and carries a predicate that
+// returns 9 — the four delivered members were closed and the prose count was not.
+// A reader who runs the predicate finds the discrepancy; a reader who trusts the
+// number does not, and the number is the part that looks like a fact.
+//
+// So a pin asserting a subset must be RE-DERIVABLE, and this re-derives it. The
+// predicate is the pin's own: position-matched sweep tags over parsed queue items,
+// which is the only method of the three that was ever right.
+guard("pin-reproducibility", () => {
+  const board = path.join(docs, "WORKSTREAMS.md");
+  if (!exists(board) || !queueDocs.length) return;
+  const text = readText(board);
+  // `### \`[SWEEP:<tag>]\` — pinned at <sha>, <n> members`
+  const pins = [...text.matchAll(/^###\s+`\[SWEEP:([a-z0-9._-]+)\]`[^\n]*?(\d+)\s+members/gim)];
+  if (!pins.length) {
+    push("pin-reproducibility", "info", ["no pinned sweeps on the board — nothing to re-derive"]);
+    return;
+  }
+  const items = queueDocs.flatMap((rel) => queueItemsOf(parseWorkDoc(readText(path.join(docs, rel)))));
+  const problems = [];
+  const okLines = [];
+  for (const [, tag, claimed] of pins) {
+    const actual = items.filter((i) => sweepTagOf(i) === tag.toLowerCase()).length;
+    if (Number(claimed) !== actual) {
+      problems.push(
+        `[SWEEP:${tag}] pin claims ${claimed} members; its own predicate returns ${actual}. ` +
+          `A stated count that the stated method contradicts is worse than no count — it looks auditable. ` +
+          `Re-derive the pin, or record why the difference is expected.`,
+      );
+    } else {
+      okLines.push(`[SWEEP:${tag}]: ${actual} members, predicate reproduces the count`);
+    }
+  }
+  if (problems.length) push("pin-reproducibility", "warn", [...problems, ...okLines]);
+  else push("pin-reproducibility", "ok", okLines);
+});
+
 const factsFile = path.join(docs, "FACTS.md");
 guard("facts-freshness", () => {
   if (exists(factsFile)) {

package/src/lib/artifacts.mjs

@@ -48,6 +48,12 @@ export const ARTIFACTS = [
   { 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/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" },
+  // DELIBERATELY NO `grammar`. This doc is registered so `doc-registration`
+  // can see it, but it is NOT a work-doc grammar: a David-blocked list that
+  // parses as a queue IS a queue, and every queue check would begin reading
+  // it as claimable work. The whole point of the file is that its contents
+  // are the items the fleet CANNOT pick up.
+  { path: "docs/DAVID_TASKS.md", scope: "project", purpose: "Standing list of what is blocked on David — his hands, accounts, money, or ruling", writtenBy: "aide (coordinator may append)", readBy: "David, /start-session", rules: "Not a queue: no `- [ ] (Pn)` lines. Items the fleet can do belong in 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" },