@davidbalzan/groundwork 0.4.7 → 0.4.9

package/README.md

@@ -158,6 +158,35 @@ Shipped to `docs/.groundwork/scripts/` and preferred by the matching skills:
 
 ---
 
+## Upgrading: nothing migrates your content
+
+**`groundwork update` never rewrites your work.** It refreshes the files Groundwork
+installed and leaves everything else alone. There is no auto-migration, and that is a
+decision rather than a gap — an auto-migrating skill was considered and rejected, because
+the failure mode is silent data loss in the one place you would not look for it.
+
+What that means in practice:
+
+- **A doc you edited is KEPT and named in the summary**, not overwritten. Taking an
+  upstream version is a deliberate act: `--force-skills` or `--force-docs`.
+- **An older board grammar keeps parsing as itself.** A 5-column Active Streams table is
+  read as `workstreams.lanes-v0` — it is not upgraded, not rewritten, and not treated as
+  broken. You move to the 6-column `workstreams.v1` grammar when you choose to, by
+  editing the table.
+- **Nothing reformats a file to normalise it.** If a table renders, it stays as written.
+
+One honest exception, and it is narrow. A file installed **before Groundwork recorded
+install baselines** has no recorded hash to compare against, so `update` cannot tell an
+edited file from an untouched one. Those used to be kept forever — which quietly meant a
+card could stay two weeks stale while `update` reported success. Now, **if git says the
+file is tracked and has no uncommitted changes, it is refreshed and listed under
+"Refreshed N pre-baseline file(s)"** — because git can give it back (`git checkout --
+<path>`), so the refresh costs a command rather than a fact. If the file is untracked,
+uncommitted, or the project is not a git repo, it is still kept.
+
+If you want to see what would change before it does, `groundwork update --dry-run` reports
+the same decisions without writing.
+
 ## Versions stay honest
 
 Two mechanisms keep dependency versions from rotting:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidbalzan/groundwork",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "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.10"
+    "@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, commitRefsIn, commitRefMatches, withoutCodeContext } from "@davidbalzan/groundwork-seam";
 
 /**
  * `groundwork doctor` — flag drift between the docs and reality. Offline + deterministic.
@@ -299,21 +299,50 @@ 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 ?? "")));
+  // A CLOSURE CAN BE TIED BY COMMIT, NOT ONLY BY PR — `land` requires a PR by
+  // rule, but a `.md`-direct workflow with no PR (this repo's own aide pushes
+  // docs straight to `main` all day) still closes an item, and its only
+  // citable evidence is `owner/repo@sha`. Before this, a genuinely-closed
+  // item with no PR read as "cites no PR, so nothing can tie it to DONE.md" —
+  // its ONLY remedies were to fabricate a PR reference or to prune delivered
+  // work, and both falsify the record. Surfaced 2026-08-31.
+  const doneCommits = doneEntries.flatMap((e) => commitRefsIn(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 citedCommits = commitRefsIn(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))) {
+    if (cited.length === 0 && citedCommits.length === 0) {
+      problems.push(`${item.where}: [x] item cites neither a PR nor a commit, so nothing can tie it to DONE.md — "${short}…"`);
+    } else if (
+      !cited.some((r) => refIn(r, doneRefs, { contextRepo })) &&
+      !citedCommits.some((c) => doneCommits.some((d) => commitRefMatches(c, d)))
+    ) {
       // 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.
+      // is the only tie it has, and an item whose body never names the PR or
+      // commit 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. ` +
+        `${item.where}: [x] item cites ${[...cited.map((r) => r.raw), ...citedCommits.map((c) => `@${c}`)].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}…"`,
       );
     }
@@ -526,7 +555,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 +570,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 +642,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`]);
@@ -1151,9 +1214,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/commands/update.mjs

@@ -13,6 +13,8 @@ import { writeArtifacts } from "./artifacts.mjs";
 import { refreshableDocs } from "../lib/artifacts.mjs";
 import {
   classify,
+  gitVerdictFor,
+  isRecoverableRefresh,
   hashFile,
   isProtected,
   readBaseline,
@@ -61,6 +63,8 @@ export function update(targetDir, flags = {}) {
   let refreshed = 0;
   let added = 0;
   let unchanged = 0;
+  /** Pre-baseline files refreshed only because git can restore them. */
+  const recovered = [];
   for (const name of toRefresh) {
     const src = path.join(PAYLOAD_SKILLS, name, "SKILL.md");
     if (!exists(src)) {
@@ -69,7 +73,7 @@ export function update(targetDir, flags = {}) {
     }
     const rel = path.join(TARGET.skills, name, "SKILL.md");
     const dest = path.join(root, rel);
-    const verdict = classify(dest, src, baseline[rel]);
+    const verdict = classify(dest, src, baseline[rel], gitVerdictFor(root, rel));
 
     if (verdict === "current") {
       unchanged++;
@@ -80,6 +84,7 @@ export function update(targetDir, flags = {}) {
       kept.push({ rel, verdict, kind: "skill" });
       continue;
     }
+    if (isRecoverableRefresh(verdict)) recovered.push(rel);
     if (!dry) {
       copyFileSafe(src, dest, { force: true });
       nextBaseline[rel] = hashFile(src);
@@ -128,7 +133,7 @@ export function update(targetDir, flags = {}) {
       const src = path.join(PAYLOAD_DOCS, rel.replace(/^docs\//, ""));
       if (!exists(src)) continue; // ARTIFACTS.md is generated, not in payload — skip
       const dest = path.join(root, rel);
-      const verdict = classify(dest, src, baseline[rel]);
+      const verdict = classify(dest, src, baseline[rel], gitVerdictFor(root, rel));
       if (verdict === "current") {
         nextBaseline[rel] = hashFile(src);
         continue;
@@ -167,6 +172,21 @@ export function update(targetDir, flags = {}) {
   }
   if (unchanged) log.info(dim(`  ${unchanged} skill(s) already current.`));
 
+  // REFRESHING A PRE-BASELINE FILE IS A CHOICE, SO IT IS REPORTED.
+  //
+  // These had no baseline to judge by and were previously kept forever on the
+  // assumption they had been edited. They are refreshed now because git says
+  // they are tracked and clean — recoverable, not unexamined — and saying so is
+  // what keeps that from being a silent overwrite.
+  if (recovered.length) {
+    log.heading(`Refreshed ${recovered.length} pre-baseline file(s) — git shows them tracked and unmodified`);
+    for (const rel of recovered) console.log(`  ${dim(rel)}`);
+    console.log(
+      dim("  No baseline existed for these, so they were previously kept indefinitely.\n" +
+          "  Recover any of them with `git checkout -- <path>`; review with `git diff`.")
+    );
+  }
+
   // Report what we did NOT overwrite. This block is the whole point of the
   // change: the previous version force-copied these and then printed that your
   // docs had been left untouched.

package/src/lib/baseline.mjs

@@ -24,6 +24,7 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { TARGET } from "./paths.mjs";
 import { exists } from "./fs.mjs";
@@ -78,14 +79,59 @@ export function writeBaseline(root, files) {
  * "modified" — differs from the recorded baseline: a local edit. KEEP.
  * "unknown"  — installed, differs from payload, no baseline to judge by. KEEP.
  */
-export function classify(projectFile, payloadFile, baselineHash) {
+export function classify(projectFile, payloadFile, baselineHash, gitVerdict) {
   if (!exists(projectFile)) return "absent";
   const now = hashFile(projectFile);
   const payload = hashFile(payloadFile);
   if (now !== undefined && now === payload) return "current";
-  if (baselineHash === undefined) return "unknown";
+  if (baselineHash === undefined) {
+    // ASK GIT BEFORE ASSUMING AN EDIT.
+    //
+    // A file installed before baselines existed has no hash to judge by, and
+    // the safe answer was to assume it had been edited and keep it. Safe, and
+    // permanent: it kept a two-week-stale card while reporting success, because
+    // "no baseline" never becomes "baseline" for a file that is never
+    // overwritten. The protection outlived the uncertainty that justified it.
+    //
+    // What the protection is actually FOR is preventing IRRECOVERABLE loss — a
+    // reverted SKILL.md changes agent behaviour silently. Git recoverability
+    // removes exactly that: a tracked file with no uncommitted changes can be
+    // restored with `git checkout`, so refreshing it costs a command and never
+    // a fact. Untracked or dirty, the old assumption still holds, because there
+    // the overwrite really is unrecoverable.
+    return gitVerdict === "tracked-clean" ? "stale-recoverable" : "unknown";
+  }
   return now === baselineHash ? "clean" : "modified";
 }
 
+/**
+ * What git knows about one path: "tracked-clean" | "tracked-dirty" |
+ * "untracked" | "unknown".
+ *
+ * "unknown" for a non-repo or a failed call, and that default is the
+ * conservative one — an unanswerable question must not read as a clean answer.
+ */
+export function gitVerdictFor(root, rel) {
+  try {
+    const tracked = execFileSync("git", ["ls-files", "--error-unmatch", "--", rel], {
+      cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (!tracked) return "untracked";
+  } catch {
+    return "untracked";
+  }
+  try {
+    const dirty = execFileSync("git", ["status", "--porcelain", "--", rel], {
+      cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    return dirty ? "tracked-dirty" : "tracked-clean";
+  } catch {
+    return "unknown";
+  }
+}
+
 /** True when a classification means "do not overwrite without an explicit flag". */
 export const isProtected = (verdict) => verdict === "modified" || verdict === "unknown";
+
+/** True when the file was refreshed only because git can restore it. */
+export const isRecoverableRefresh = (verdict) => verdict === "stale-recoverable";