@davidbalzan/groundwork 0.4.8 → 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.8",
+  "version": "0.4.9",
   "description": "Groundwork — an installable AI development workflow (skills + doc methodology) you bolt onto any repo.",
   "type": "module",
   "bin": {

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, withoutCodeContext } 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,6 +299,14 @@ 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
@@ -318,18 +326,23 @@ guard("queue-done-loop", () => {
   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, { contextRepo }))) {
+    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}…"`,
       );
     }

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";