@davidbalzan/groundwork 0.4.2 → 0.4.4

package/package.json

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

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 } from "@davidbalzan/groundwork-seam";
+import { parseFactsDoc, parseWorkDoc, workDocIssues, workDocLegacyWriteIssues, workDocIssuesDetailed, queueItemsOf, doneEntriesOf, workstreamsV1RowsOf, sweepTagOf, sweepTagCensus } from "@davidbalzan/groundwork-seam";
 
 /**
  * `groundwork doctor` — flag drift between the docs and reality. Offline + deterministic.
@@ -871,6 +871,86 @@ guard("version-truth", () => {
   }
 });
 
+// A sweep census nobody has to grep for.
+//
+// MATCH A TAG BY ITS POSITION, NOT BY ITS OCCURRENCE. A corpus that documents its
+// own tags guarantees the tag string appears in items that do not carry it — items
+// cite other sweeps by name, and every `<!-- queue-prune: -->` receipt quotes the
+// lines it removed. **The trail that makes a move checkable is the trail that makes
+// a naive scan wrong**, and it worsens as the trail grows.
+//
+// Measured on the live corpus: grep 14 · parser-by-occurrence 14 · parser-by-
+// position 13. Using the parser was NECESSARY AND NOT SUFFICIENT. This check exists
+// so the correct number is available without anyone reaching for `grep -c`, because
+// the reaching is the defect and it happened three times in twenty minutes.
+//
+// It reports rather than judges: a tag count is not a problem, and the only failure
+// it can name is a MENTION that outnumbers the CARRIERS, which is the shape that
+// misleads.
+guard("sweep-census", () => {
+  if (!queueDocs.length) return;
+  const items = queueDocs.flatMap((rel) => queueItemsOf(parseWorkDoc(readText(path.join(docs, rel)))));
+  if (!items.length) return;
+  const census = sweepTagCensus(items);
+  const tags = Object.keys(census).sort();
+  if (!tags.length) {
+    push("sweep-census", "ok", [`${items.length} item(s), none carrying a sweep tag`]);
+    return;
+  }
+  const lines = tags.map((t) => {
+    const carried = census[t];
+    // Mentions across ALL item text, the number a grep would return.
+    const mentioned = items.filter((i) => new RegExp(`\\[SWEEP:${t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\]`, "i").test(i.text)).length;
+    const gap = mentioned - carried;
+    return `${t}: ${carried} carried` + (gap > 0 ? ` · ${mentioned} mentioned — a naive scan over-counts by ${gap}` : "");
+  });
+  push("sweep-census", "ok", [
+    `${items.length} item(s) across ${queueDocs.length} work-doc(s), tags matched at POSITION not occurrence`,
+    ...lines,
+  ]);
+});
+
+// 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)) {