@davidbalzan/groundwork 0.4.6 → 0.4.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidbalzan/groundwork",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "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.9"
+    "@davidbalzan/groundwork-seam": "^0.1.0"
   },
   "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 { phaseCitationsIn, parseFactsDoc, parseWorkDoc, workDocIssues, workDocLegacyWriteIssues, workDocIssuesDetailed, queueItemsOf, doneEntriesOf, workstreamsV1RowsOf, sweepTagOf, sweepTagCensus, refsIn, refIn } from "@davidbalzan/groundwork-seam";
+import { phaseCitationsIn, parseFactsDoc, parseWorkDoc, workDocIssues, workDocLegacyWriteIssues, workDocIssuesDetailed, queueItemsOf, doneEntriesOf, workstreamsV1RowsOf, sweepTagOf, sweepTagCensus, refsIn, refIn, withoutCodeContext } from "@davidbalzan/groundwork-seam";
 
 /**
  * `groundwork doctor` — flag drift between the docs and reality. Offline + deterministic.
@@ -299,13 +299,29 @@ guard("queue-done-loop", () => {
   // 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 ?? "")));
+  // THE REPO BEING CHECKED, so a BARE `#170` resolves instead of being unknown.
+  //
+  // The seam's primitive refuses a bare-vs-qualified tie by design, and doctor
+  // deliberately passed nothing on the premise that "the corpus writes
+  // `kit#94`/`console#38`, so the tie is recoverable". MEASURED ON THIS REPO:
+  // it does not. Queue items cite bare `#170, #173` while DONE.md qualifies
+  // them, and six correctly-logged closures were reported as untieable — a
+  // warning ON CORRECT CONTENT, which is the whole subject of this task and
+  // reached David twice as a suspected data problem.
+  //
+  // This NARROWS the check, so it ships with the case where it still fires:
+  // `console#39` still does not match `groundwork-kit#39`, because the primitive
+  // compares repository leaves rather than numbers. Unknown becomes known only
+  // where the repo actually answers it; a doc outside a git repo passes null and
+  // gets exactly today's behaviour.
+  const contextRepo = originRepoOf(docs);
   const problems = [];
   for (const item of closed) {
     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((r) => refIn(r, doneRefs))) {
+    } else if (!cited.some((r) => refIn(r, doneRefs, { contextRepo }))) {
       // 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.
@@ -526,7 +542,12 @@ guard("undeclared-work-docs", () => {
   const rogue = [];
   for (const rel of mdFiles) {
     if (declared.has(rel) || isTemplate(rel)) continue;
-    const text = readText(path.join(docs, rel));
+    // Same root cause as the wikilink resolver, and the same fix: an example
+    // item line inside a fence is a SPECIMEN, not work. A doc explaining
+    // `- [ ] (P1) …` must not be reported as an undeclared queue — declaring it
+    // to silence the warning would make every queue check read specimens as
+    // real items, which is the defect this check exists to find.
+    const text = withoutCodeContext(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 });
   }
@@ -536,12 +557,38 @@ guard("undeclared-work-docs", () => {
   // 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) {
+    // AN ARCHIVE MUST NOT BE TOLD TO DECLARE `queue.v1`. Declaring it is what
+    // the remedy says, and it would make every archived row parse as OPEN work —
+    // the check would resurrect the rows someone archived on purpose. A consumer
+    // fleet already ships `QUEUE_PARKED_ARCHIVE` (58 rows) and
+    // `QUEUE_ITEMS_ARCHIVE` (48); following this advice there would revive 106
+    // closed items. The archive GRAMMAR itself is a separate item; what belongs
+    // here is not handing out a remedy that breaks the thing it is aimed at.
+    const isArchive = (rel) => /archive/i.test(rel);
+    const archives = rogue.filter((r) => isArchive(r.rel));
+    const live = rogue.filter((r) => !isArchive(r.rel));
+    // A REMEDY MUST NAME A PATH THAT EXISTS IN THE REPO BEING CHECKED.
+    // `src/lib/artifacts.mjs` is correct only inside the kit, and it survived
+    // review because its authors live in the one repo where it works. A consumer
+    // reading it goes looking for a file it does not have, which is worse than
+    // no remedy: it reads as "your repo is broken" rather than "this advice is
+    // not for you".
+    const manifestPath = path.join(root, "src/lib/artifacts.mjs");
+    const where = exists(manifestPath)
+      ? "`src/lib/artifacts.mjs`"
+      : "your artifact manifest (this repo has no `src/lib/artifacts.mjs` — that path exists only in the groundwork kit itself)";
     push("undeclared-work-docs", "warn", [
       scanned,
-      ...rogue.map(
+      ...live.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",
+      ...archives.map(
+        (r) =>
+          `docs/${r.rel} looks like an ARCHIVE holding ${r.count} archived item(s) — it is NOT declared, and it must NOT be declared queue.v1: that would make every archived row parse as open work`,
+      ),
+      ...(live.length
+        ? [`declare it in ${where} 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`]);
@@ -582,7 +629,10 @@ guard("doc-registration", () => {
   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",
+      // SAME REMEDY DEFECT AS undeclared-work-docs, and the same fix: name a
+      // path the CHECKED repo has. This line is the one a consumer sees most,
+      // because an unregistered doc is the most common finding in a fresh repo.
+      `add it to ${exists(path.join(root, "src/lib/artifacts.mjs")) ? "src/lib/artifacts.mjs" : "your artifact manifest (this repo has no src/lib/artifacts.mjs — that path exists only in the groundwork kit itself)"} 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`]);
@@ -1123,8 +1173,21 @@ export function doctor(targetDir, opts = {}) {
 
 // ---------- helpers ----------
 function phaseNumberFromDir(label) {
-  const m = String(label).match(/^phase(\d+)/i);
-  return m ? Number(m[1]) : null;
+  // THE PHASE TOKEN CAN HAVE A MINOR PART, and truncating it is the b-clause
+  // defect at a second granularity. There the ID token was too narrow — `3.3b`
+  // matched as `3.3`. Here the PHASE token is: `phase5.1` matched as `5`, so
+  // every box in phase 5.1 was keyed under phase 5 and the citation that names
+  // the phase correctly — `Phase 5.1 Task 7.1` — parsed as nothing at all.
+  //
+  // The consequence was worse than a miss: the citation that LOOKS right is the
+  // one that does not tie, so a correct-looking record reports unevidenced
+  // ticks. Every 5.1 citation had to be written in a form contradicting the
+  // phase's own name.
+  //
+  // Returned as a STRING, because "5.1" is not a number and Number("5.1")
+  // silently collides `phase5.1` with any future `phase5.10`.
+  const m = String(label).match(/^phase(\d+(?:\.\d+)?)/i);
+  return m ? m[1] : null;
 }
 
 function roadmapPhaseComplete(roadmapText, n) {
@@ -1138,9 +1201,36 @@ function doneLineNamesPhase(doneText, n) {
   return String(doneText).split("\n").some((line) => re.test(line));
 }
 
+/**
+ * `owner/repo` for the repository being checked, or null.
+ *
+ * Read from the git remote rather than from package.json: the remote is what
+ * the refs in these documents actually name, and a package can be published
+ * under a name that differs from its repository.
+ */
+function originRepoOf(dir) {
+  try {
+    const url = execFileSync("git", ["remote", "get-url", "origin"], {
+      cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    const m = /[:/]([\w.-]+\/[\w.-]+?)(?:\.git)?$/.exec(url);
+    return m ? m[1] : null;
+  } catch {
+    // No remote, or not a repo. Null is today's behaviour exactly — an unknown
+    // context must not become a guessed one.
+    return null;
+  }
+}
+
 function wikilinks(text) {
   const out = [];
-  for (const m of text.matchAll(/\[\[([^\]]+)\]\]/g)) {
+  // A WIKILINK IN A CODE SPAN IS NOT A LINK. Documentation contains examples of
+  // what it documents, and this check flagged 15/15 quoted specimens — one of
+  // them a deliberately planted `[[orphan]]` control, which means the check
+  // reported a failure ON THE EVIDENCE THAT IT WORKS. Stripping preserves line
+  // structure, so every location this function's callers report still points at
+  // the same place (§withoutCodeContext).
+  for (const m of withoutCodeContext(text).matchAll(/\[\[([^\]]+)\]\]/g)) {
     let t = m[1].split("|")[0].split("#")[0].trim(); // strip alias + heading
     if (!t) continue; // intra-doc heading link
     out.push(t);

package/src/lib/artifacts.mjs

@@ -54,6 +54,7 @@ export const ARTIFACTS = [
   // 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/improvements.md", scope: "project", purpose: "Improvements found by USING the kit, not by reviewing it — each entry records how it was hit", writtenBy: "aide (any agent may append an encounter)", readBy: "David (walkthrough), /plan-phase", rules: "An entry requires an ENCOUNTER: how it was hit, in the tool, by whom. A proposal with no encounter belongs in QUEUE.md. Entries keep their line after the fix lands and gain a reference, so the record of what using it felt like survives the repair. Includes a do-not-improve section: surfaces measured as working, which an in-flight phase must not regress." },
   { 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" },