@davidbalzan/groundwork 0.4.2 → 0.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidbalzan/groundwork",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "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,45 @@ 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,
+  ]);
+});
+
 const factsFile = path.join(docs, "FACTS.md");
 guard("facts-freshness", () => {
   if (exists(factsFile)) {