@davidbalzan/groundwork 0.3.3 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidbalzan/groundwork",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "Groundwork — an installable AI development workflow (skills + doc methodology) you bolt onto any repo.",
   "type": "module",
   "bin": {
@@ -28,11 +28,11 @@
   "author": "David Balzan",
   "license": "MIT",
   "dependencies": {
-    "@davidbalzan/groundwork-seam": "0.1.2"
+    "@davidbalzan/groundwork-seam": "0.1.3"
   },
   "scripts": {
     "groundwork": "node src/cli.mjs",
-    "test": "node --test test/*.test.mjs",
+    "test": "node ../../scripts/assert-tests-exist.mjs test/*.test.mjs && node --test test/*.test.mjs",
     "test:init": "node src/cli.mjs init /tmp/groundwork-smoke --force && node src/cli.mjs list /tmp/groundwork-smoke && node src/cli.mjs status /tmp/groundwork-smoke"
   }
 }

package/src/cli.mjs

@@ -39,7 +39,7 @@ function help() {
       "",
       bold("Commands:"),
       `  ${cyan("init")} [dir]        Install skills + IDE mirrors + docs into a repo (default: .)`,
-      `  ${cyan("update")} [dir]      Upgrade skills + scripts in place (keeps your docs); ${dim("--all")} adds new skills, ${dim("--docs")} refreshes generic reference docs`,
+      `  ${cyan("update")} [dir]      Upgrade skills + scripts in place (keeps your docs AND your local edits); ${dim("--all")} adds new skills, ${dim("--docs")} refreshes generic reference docs`,
       `  ${cyan("add")} <skill> [dir] Add one optional skill (e.g. add-data-layer)`,
       `  ${cyan("list")} [dir]        List available skills and install state`,
       `  ${cyan("status")} [dir]      Show live workstreams, next backlog item, phase progress`,
@@ -51,6 +51,9 @@ function help() {
       "",
       bold("Flags:"),
       `  --minimal          init only the core 5 skills`,
+      `  --dry-run          update: report what would change, write nothing`,
+      `  --force-skills     update: overwrite locally-modified SKILL.md files`,
+      `  --force-docs       update: overwrite locally-modified reference docs`,
       `  --force            overwrite files that already exist`,
       `  --json             machine-readable output (doctor / status / list)`,
       "",

package/src/commands/doctor.mjs

@@ -26,8 +26,26 @@ export function collectDoctor(targetDir) {
 
   const checks = [];
   const push = (check, level, items) => checks.push({ check, level, items });
+  // A broken check degrades to a named skip instead of taking the whole doctor
+  // down (field crash 2026-08-21: a TypeError from one check aborted the run
+  // and every later check with it, including the pure-fs ones). Doctor never
+  // writes anything — a skipped check must not tempt anyone to "fix" a target
+  // into existence.
+  const skipped = [];
+  const guard = (name, fn) => {
+    try {
+      fn();
+    } catch (e) {
+      skipped.push(name);
+      push(name, "info", [
+        `check skipped — ${String(e?.message ?? e).split("\n")[0]} (doctor kept going; other checks are unaffected)`,
+      ]);
+    }
+  };
   const mdFiles = [...walk(docs)].filter((f) => f.endsWith(".md"));
+  const phaseDir = path.join(docs, "phases");
 
+  guard("orphan-wikilinks", () => {
   const valid = validLinkTargets(docs, mdFiles);
   const orphanItems = [];
   const seen = new Set();
@@ -42,8 +60,9 @@ export function collectDoctor(targetDir) {
     }
   }
   push("orphan-wikilinks", orphanItems.length ? "warn" : "ok", orphanItems.length ? orphanItems : ["all wikilinks resolve"]);
+  });
 
-  const phaseDir = path.join(docs, "phases");
+guard("phase-progress", () => {
   const roadmapText = exists(path.join(docs, "PRODUCTION_ROADMAP.md"))
     ? readText(path.join(docs, "PRODUCTION_ROADMAP.md"))
     : "";
@@ -71,7 +90,10 @@ export function collectDoctor(targetDir) {
   }
   if (!phaseItems.length) push("phase-progress", "ok", ["no phase task files yet (run /plan-phase)"]);
   else push("phase-progress", phaseWarn ? "warn" : "ok", phaseItems);
+  });
+
 
+guard("spec-coverage", () => {
   const coverageItems = [];
   if (exists(phaseDir)) {
     for (const dir of listDirs(phaseDir)) {
@@ -100,7 +122,10 @@ export function collectDoctor(targetDir) {
   const coverageInfoOnly = coverageItems.length === 1 && coverageItems[0].startsWith("no PRD");
   if (!coverageItems.length) push("spec-coverage", "ok", ["phase structure + PRD sections look complete"]);
   else push("spec-coverage", coverageInfoOnly ? "info" : "warn", coverageItems);
+  });
+
 
+guard("version-marker", () => {
   const marker = path.join(docs, ".groundwork", "VERSION");
   const cliV = pkgVersion();
   if (exists(marker)) {
@@ -109,7 +134,10 @@ export function collectDoctor(targetDir) {
       push("version-marker", "warn", [`installed v${got}, CLI is v${cliV} — run \`groundwork update --all --docs\``]);
     else push("version-marker", "ok", [`up to date (v${got})`]);
   } else push("version-marker", "warn", ["no VERSION marker — re-run `groundwork init`/`update`"]);
+  });
 
+
+guard("stack-map-freshness", () => {
   const sm = path.join(docs, "STACK_MAP.md");
   if (exists(sm)) {
     const m = readText(sm).match(/Last audited[^\d]*(\d{4})-(\d{2})-(\d{2})/);
@@ -120,7 +148,10 @@ export function collectDoctor(targetDir) {
       else push("stack-map-freshness", "ok", [`STACK_MAP audited ${days} days ago`]);
     }
   } else push("stack-map-freshness", "info", ["no STACK_MAP.md yet (run /kickstart)"]);
+  });
+
 
+guard("workstreams", () => {
   const wsFile = path.join(docs, "WORKSTREAMS.md");
   if (exists(wsFile)) {
     const wsDoc = parseWorkDoc(readText(wsFile));
@@ -128,15 +159,21 @@ export function collectDoctor(targetDir) {
     if (wsIssues.length) push("workstreams", "warn", wsIssues);
     else push("workstreams", "ok", ["write grammar is workstreams.v1"]);
   } else push("workstreams", "info", ["no WORKSTREAMS.md yet (run `groundwork update --docs`)"]);
+  });
+
 
+guard("queue", () => {
   const qFile = path.join(docs, "QUEUE.md");
   if (exists(qFile)) {
     const qIssues = workDocIssues(parseWorkDoc(readText(qFile)));
     if (qIssues.length) push("queue", "warn", qIssues);
     else push("queue", "ok", ["queue.v1 — one line per item"]);
   }
+  });
 
-  const factsFile = path.join(docs, "FACTS.md");
+
+const factsFile = path.join(docs, "FACTS.md");
+guard("facts-freshness", () => {
   if (exists(factsFile)) {
     const { entries, issues } = parseFactsDoc(readText(factsFile));
     if (issues.length) push("facts-freshness", "warn", issues);
@@ -147,7 +184,10 @@ export function collectDoctor(targetDir) {
         [entries.length ? `${entries.length} fact(s), all verified and fresh` : "no facts recorded yet"],
       );
   } else push("facts-freshness", "info", ["no FACTS.md yet (run `groundwork update --docs`)"]);
+  });
+
 
+guard("adr-tripwire", () => {
   const decisions = path.join(docs, "DECISIONS.md");
   if (exists(decisions)) {
     const acceptedIds = new Set();
@@ -169,9 +209,11 @@ export function collectDoctor(targetDir) {
     if (adrItems.length) push("adr-tripwire", "warn", adrItems);
     else push("adr-tripwire", "ok", ["no Accepted ADR contradicted by dependencies/paths"]);
   } else push("adr-tripwire", "info", ["no DECISIONS.md yet (run /kickstart)"]);
+  });
+
 
   const warnCount = checks.filter((c) => c.level === "warn").length;
-  return { ok: warnCount === 0, exit: warnCount === 0 ? 0 : 1, checks };
+  return { ok: warnCount === 0, exit: warnCount === 0 ? 0 : 1, checks, ...(skipped.length ? { skipped } : {}) };
 }
 
 export function doctor(targetDir, opts = {}) {
@@ -207,6 +249,8 @@ export function doctor(targetDir, opts = {}) {
     }
   }
   log.heading("Summary");
+  if (report.skipped?.length)
+    console.log(`  ${yellow("⚠")} ${report.skipped.length} check(s) skipped (${report.skipped.join(", ")}) — see above; fs-only checks still ran.`);
   if (report.ok) log.ok("No drift detected — docs match reality.");
   else console.log(`  ${yellow(String(report.checks.filter((c) => c.level === "warn").length))} issue(s) to look at.`);
   process.exitCode = report.exit;

package/src/commands/init.mjs

@@ -10,6 +10,7 @@ import {
 import { copyFileSafe, walk, exists } from "../lib/fs.mjs";
 import { loadSkills, mirrorFiles } from "../lib/skills.mjs";
 import { writeArtifacts } from "./artifacts.mjs";
+import { hashFile, readBaseline, writeBaseline } from "../lib/baseline.mjs";
 import { log, bold, cyan, dim } from "../lib/log.mjs";
 
 /** Docs that are about Groundwork-the-product, not a per-project doc. */
@@ -36,6 +37,9 @@ export function init(targetDir, flags) {
   if (minimal) log.info(dim(`  (minimal: ${MINIMAL_SKILLS.join(", ")})`));
 
   const counts = { added: 0, skipped: 0 };
+  // Hashes of everything this install writes — the baseline `update` compares
+  // against before overwriting anything.
+  const baselineFiles = {};
   const bump = (r) => counts[r]++;
 
   // 1. Skills → .claude/skills
@@ -46,6 +50,9 @@ export function init(targetDir, flags) {
     const dest = path.join(root, TARGET.skills, name, "SKILL.md");
     const r = copyFileSafe(src, dest, { force });
     bump(r);
+    // Record what we wrote, so a later `update` can tell a local edit from an
+    // upstream change and refuse to clobber the former.
+    if (r === "added") baselineFiles[path.join(TARGET.skills, name, "SKILL.md")] = hashFile(src);
     r === "added" ? log.added(`${TARGET.skills}/${name}/SKILL.md`) : null;
   }
 
@@ -70,12 +77,10 @@ export function init(targetDir, flags) {
   log.step("Docs (methodology, templates, phases, WORKSTREAMS)");
   for (const rel of walk(PAYLOAD_DOCS)) {
     if (DOC_EXCLUDE.has(rel)) continue;
-    const r = copyFileSafe(
-      path.join(PAYLOAD_DOCS, rel),
-      path.join(root, TARGET.docs, rel),
-      { force }
-    );
+    const src = path.join(PAYLOAD_DOCS, rel);
+    const r = copyFileSafe(src, path.join(root, TARGET.docs, rel), { force });
     bump(r);
+    if (r === "added") baselineFiles[path.join(TARGET.docs, rel)] = hashFile(src);
   }
   // ARTIFACTS.md is generated from the manifest (single source), not copied.
   if (!exists(path.join(root, TARGET.docs, "ARTIFACTS.md")) || force) {
@@ -102,6 +107,9 @@ export function init(targetDir, flags) {
     fs.mkdirSync(path.dirname(marker), { recursive: true });
     fs.writeFileSync(marker, readPkgVersion() + "\n");
   }
+  // Merge rather than replace: re-running init over an existing project must not
+  // discard baselines for files it skipped this time.
+  writeBaseline(root, { ...readBaseline(root), ...baselineFiles });
 
   log.heading("Done");
   log.ok(`${counts.added} files written, ${counts.skipped} skipped (already present)`);

package/src/commands/update.mjs

@@ -11,17 +11,33 @@ import { copyFileSafe, listDirs, exists, walk } from "../lib/fs.mjs";
 import { loadSkills, mirrorFiles } from "../lib/skills.mjs";
 import { writeArtifacts } from "./artifacts.mjs";
 import { refreshableDocs } from "../lib/artifacts.mjs";
-import { log, cyan, dim, green, bold } from "../lib/log.mjs";
+import {
+  classify,
+  hashFile,
+  isProtected,
+  readBaseline,
+  writeBaseline,
+} from "../lib/baseline.mjs";
+import { log, cyan, dim, green, bold, yellow } from "../lib/log.mjs";
 
 /**
  * Upgrade the workflow layer in an existing project, in place, WITHOUT touching
- * project-authored docs. Refreshes installed skills + their mirrors + the helper
- * scripts + the version marker. New skills introduced upstream are reported (and
- * installed too when `--all` is passed) — never silently added by default.
+ * project-authored docs OR locally-customised skills. Refreshes installed
+ * skills + their mirrors + the helper scripts + the version marker. New skills
+ * introduced upstream are reported (and installed too when `--all` is passed) —
+ * never silently added by default.
+ *
+ * Anything edited locally is KEPT and named in the summary. `docs/.groundwork/
+ * baseline.json` records the hash of what we last installed, which is what lets
+ * "the project edited this" be told apart from "upstream changed this"; a file
+ * with no baseline entry is kept too, because absence of a record is not
+ * evidence that a file is untouched. `--force-skills` / `--force-docs` override,
+ * and `--dry-run` reports the plan without writing anything.
  */
 export function update(targetDir, flags = {}) {
   const root = path.resolve(targetDir || ".");
-  log.heading(`Updating Groundwork → ${cyan(root)}`);
+  const dry = flags["dry-run"] === true || flags.dryRun === true;
+  log.heading(`${dry ? "Update plan (dry run)" : "Updating Groundwork"} → ${cyan(root)}`);
 
   const installed = listDirs(path.join(root, TARGET.skills));
   if (installed.length === 0) {
@@ -34,77 +50,161 @@ export function update(targetDir, flags = {}) {
   // With --all, also install skills added upstream since this project's init.
   const toRefresh = flags.all ? [...installed, ...newSkills] : installed;
 
-  // 1. Skills (force-refresh)
+  const baseline = readBaseline(root);
+  const nextBaseline = { ...baseline };
+  // Files we declined to overwrite, with why — reported at the end, never
+  // buried. A silent skip and a silent clobber are the same failure: the user
+  // cannot tell what happened to their file.
+  const kept = [];
+
+  // 1. Skills — refresh, EXCEPT where the project has edited the SKILL.md.
   let refreshed = 0;
   let added = 0;
+  let unchanged = 0;
   for (const name of toRefresh) {
     const src = path.join(PAYLOAD_SKILLS, name, "SKILL.md");
     if (!exists(src)) {
       log.warn(`${name}: not in payload (kept as-is)`);
       continue;
     }
-    copyFileSafe(src, path.join(root, TARGET.skills, name, "SKILL.md"), {
-      force: true,
-    });
+    const rel = path.join(TARGET.skills, name, "SKILL.md");
+    const dest = path.join(root, rel);
+    const verdict = classify(dest, src, baseline[rel]);
+
+    if (verdict === "current") {
+      unchanged++;
+      nextBaseline[rel] = hashFile(src);
+      continue;
+    }
+    if (isProtected(verdict) && !flags["force-skills"]) {
+      kept.push({ rel, verdict, kind: "skill" });
+      continue;
+    }
+    if (!dry) {
+      copyFileSafe(src, dest, { force: true });
+      nextBaseline[rel] = hashFile(src);
+    }
     installed.includes(name) ? refreshed++ : added++;
   }
 
-  // 2. Regenerate mirrors for the resulting skill set
+  // 2. Regenerate mirrors for the resulting skill set. Mirrors are DERIVED from
+  // the installed skills, so a kept customisation propagates into them — the
+  // mirror must never contradict the SKILL.md it came from.
   const skillSet = flags.all ? toRefresh : installed;
-  for (const f of mirrorFiles(loadSkills(skillSet), {
-    cursorDir: path.join(root, TARGET.cursor),
-    vscodeDir: path.join(root, TARGET.vscode),
-  })) {
-    fs.mkdirSync(path.dirname(f.rel), { recursive: true });
-    fs.writeFileSync(f.rel, f.content);
+  if (!dry) {
+    for (const f of mirrorFiles(loadSkills(skillSet), {
+      cursorDir: path.join(root, TARGET.cursor),
+      vscodeDir: path.join(root, TARGET.vscode),
+    })) {
+      fs.mkdirSync(path.dirname(f.rel), { recursive: true });
+      fs.writeFileSync(f.rel, f.content);
+    }
   }
 
   // 3. Refresh helper scripts (safe — tooling, not your docs)
   let scripts = 0;
   if (exists(PAYLOAD_SCRIPTS)) {
     for (const rel of walk(PAYLOAD_SCRIPTS)) {
-      copyFileSafe(
-        path.join(PAYLOAD_SCRIPTS, rel),
-        path.join(root, TARGET.scripts, rel),
-        { force: true }
-      );
+      if (!dry) {
+        copyFileSafe(
+          path.join(PAYLOAD_SCRIPTS, rel),
+          path.join(root, TARGET.scripts, rel),
+          { force: true }
+        );
+      }
       scripts++;
     }
   }
 
   // 4. Regenerate the generated reference doc (ARTIFACTS.md) — not project-authored
-  writeArtifacts(root);
+  if (!dry) writeArtifacts(root);
 
-  // 4b. With --docs, refresh the generic reference docs (methodology, COMMANDS, _INDEX).
-  // These are the same across projects; project-authored docs are NEVER touched.
+  // 4b. With --docs, refresh the generic reference docs (methodology, COMMANDS).
+  // Generic across projects — but still skipped when this project has edited
+  // one, on the same rule as skills: we refresh what we wrote, not what you did.
   let docs = 0;
   if (flags.docs) {
     for (const rel of refreshableDocs()) {
       const src = path.join(PAYLOAD_DOCS, rel.replace(/^docs\//, ""));
       if (!exists(src)) continue; // ARTIFACTS.md is generated, not in payload — skip
-      copyFileSafe(src, path.join(root, rel), { force: true });
+      const dest = path.join(root, rel);
+      const verdict = classify(dest, src, baseline[rel]);
+      if (verdict === "current") {
+        nextBaseline[rel] = hashFile(src);
+        continue;
+      }
+      if (isProtected(verdict) && !flags["force-docs"]) {
+        kept.push({ rel, verdict, kind: "doc" });
+        continue;
+      }
+      if (!dry) {
+        copyFileSafe(src, dest, { force: true });
+        nextBaseline[rel] = hashFile(src);
+      }
       docs++;
     }
   }
 
-  // 5. Stamp the version marker
+  // 5. Stamp the version marker + the baseline of what we just installed
   const version = pkgVersion();
-  fs.mkdirSync(path.join(root, TARGET.docs, ".groundwork"), { recursive: true });
-  fs.writeFileSync(
-    path.join(root, TARGET.docs, ".groundwork", "VERSION"),
-    version + "\n"
-  );
+  if (!dry) {
+    fs.mkdirSync(path.join(root, TARGET.docs, ".groundwork"), { recursive: true });
+    fs.writeFileSync(
+      path.join(root, TARGET.docs, ".groundwork", "VERSION"),
+      version + "\n"
+    );
+    writeBaseline(root, nextBaseline);
+  }
+
+  if (dry) {
+    log.ok(
+      `Would refresh ${refreshed} skills${added ? `, add ${added}` : ""}, ${scripts} scripts${docs ? `, ${docs} reference docs` : ""} → v${version}`
+    );
+  } else {
+    log.ok(
+      `Refreshed ${refreshed} skills${added ? `, added ${added}` : ""}, ${scripts} scripts${docs ? `, ${docs} reference docs` : ""} → v${version}`
+    );
+  }
+  if (unchanged) log.info(dim(`  ${unchanged} skill(s) already current.`));
+
+  // 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.
+  if (kept.length) {
+    const skills = kept.filter((k) => k.kind === "skill");
+    log.heading(`Kept ${kept.length} locally-modified file(s) — NOT overwritten`);
+    for (const k of kept) {
+      const why =
+        k.verdict === "modified"
+          ? "edited since Groundwork installed it"
+          : "differs from the payload, and predates the install baseline — cannot verify it is unedited";
+      console.log(`  ${yellow("~")} ${k.rel}  ${dim(`(${why})`)}`);
+    }
+    console.log(
+      dim(
+        `  Review with \`git diff\`, then overwrite deliberately: ${bold(
+          skills.length ? "--force-skills" : "--force-docs"
+        )}.`
+      )
+    );
+    if (skills.length) {
+      console.log(
+        dim(
+          "  A reverted SKILL.md changes agent behaviour silently — the next agent to run it\n" +
+            "  does the wrong thing while looking correct. That is why these are kept by default."
+        )
+      );
+    }
+  }
 
-  log.ok(
-    `Refreshed ${refreshed} skills${added ? `, added ${added}` : ""}, ${scripts} scripts${docs ? `, ${docs} reference docs` : ""} → v${version}`
-  );
   log.info(
     dim(
       flags.docs
-        ? "  Generic reference docs refreshed; your project-authored docs were left untouched."
-        : "  Project docs left untouched. Use --docs to also refresh the generic reference docs (methodology, COMMANDS, _INDEX)."
+        ? "  Generic reference docs refreshed; project-authored docs and local edits were left untouched."
+        : "  Project docs left untouched. Use --docs to also refresh the generic reference docs (methodology, COMMANDS)."
     )
   );
+  if (dry) log.info(dim("  Dry run — nothing was written."));
 
   if (!flags.all && newSkills.length) {
     log.heading("New skills available upstream (not installed)");

package/src/lib/artifacts.mjs

@@ -26,11 +26,11 @@ export const ARTIFACTS = [
   { path: "docs/DONE.md", 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" },
   { path: "docs/DESIGN_SYSTEM.md", scope: "project", purpose: "Visual language (optional)", writtenBy: "/kickstart", readBy: "frontend work", rules: "Only when there's a UI" },
   { path: "docs/FACTS.md", scope: "project", purpose: "Verified project facts (settled world-model)", writtenBy: "whoever verified (or set-fact.mjs)", readBy: "everyone, groundwork doctor", rules: "One writer per fact; entries carry verified/by/method; doctor flags stale (>14d)" },
+  { path: "docs/_INDEX.md", scope: "project", purpose: "Obsidian Map of Content (human navigation)", writtenBy: "/kickstart (scaffold), then you", readBy: "humans, agents navigating docs", rules: "Curated per project — installed once, never auto-refreshed" },
 
   // --- reference (shipped, generic, same across projects → refreshable by `update --docs`) ---
   { path: "docs/GROUNDWORK_METHODOLOGY.md", scope: "reference", purpose: "The full methodology" },
   { path: "docs/COMMANDS.md", scope: "reference", purpose: "Command/skill guide" },
-  { path: "docs/_INDEX.md", scope: "reference", purpose: "Obsidian Map of Content (human navigation)" },
   { path: "docs/ARTIFACTS.md", scope: "reference", purpose: "This file (generated from the manifest)" },
   { path: "docs/.groundwork/scripts/", scope: "reference", purpose: "Deterministic helpers: check-task.mjs (/check-task), phase-status.mjs (groundwork status), check-versions.mjs (/check-versions), set-fact.mjs (FACTS upsert)" },
   { path: "docs/.groundwork/VERSION", scope: "reference", purpose: "Installed Groundwork version" },

package/src/lib/baseline.mjs

@@ -0,0 +1,91 @@
+/*
+ * Install baseline: what Groundwork last WROTE to this project, by content hash.
+ *
+ * Why this file exists. `update` force-refreshes skills and reference docs, and
+ * before this it did so unconditionally — so a project that had customised an
+ * installed SKILL.md lost the customisation on the next `groundwork update`,
+ * with no flag involved and a summary line that said "your project-authored docs
+ * were left untouched". Overwriting a *skill* is worse than overwriting a doc:
+ * it silently changes agent BEHAVIOUR, and the next agent to run the reverted
+ * skill does the wrong thing while looking correct.
+ *
+ * Comparing the project file against the payload cannot tell the two cases
+ * apart — "the project edited it" and "upstream changed it" both read as
+ * different. So we record the hash of what we installed. Then:
+ *
+ *   project == baseline   → untouched since we wrote it   → safe to refresh
+ *   project != baseline   → someone edited it locally     → keep, and say so
+ *   no baseline entry     → we cannot know                → keep, and say so
+ *
+ * The no-baseline case matters: every project installed before this existed has
+ * no entries, so `update` must fail SAFE there — keep the file, name it, and let
+ * the user pass --force-skills / --force-docs once they have looked. A missing
+ * record is not evidence of an unmodified file.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { TARGET } from "./paths.mjs";
+import { exists } from "./fs.mjs";
+
+const BASELINE_REL = path.join(".groundwork", "baseline.json");
+
+/** Absolute path to a project's baseline file. */
+export function baselinePath(root) {
+  return path.join(root, TARGET.docs, BASELINE_REL);
+}
+
+export function hashText(text) {
+  // Normalize line endings so a CRLF checkout is not reported as edited.
+  return createHash("sha256").update(String(text).replace(/\r\n/g, "\n")).digest("hex");
+}
+
+export function hashFile(p) {
+  try {
+    return hashText(fs.readFileSync(p, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+/** Read the baseline map ({ "<rel>": "<sha256>" }). Missing/corrupt → empty. */
+export function readBaseline(root) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(baselinePath(root), "utf8"));
+    return raw && typeof raw === "object" && raw.files && typeof raw.files === "object"
+      ? raw.files
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+export function writeBaseline(root, files) {
+  const p = baselinePath(root);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  // Sorted keys so the file is diff-stable across runs.
+  const sorted = {};
+  for (const k of Object.keys(files).sort()) sorted[k] = files[k];
+  fs.writeFileSync(p, JSON.stringify({ version: 1, files: sorted }, null, 2) + "\n");
+}
+
+/**
+ * What `update` should do with one managed file.
+ *
+ * "absent"   — not installed here; copying it adds a file, destroys nothing.
+ * "clean"    — matches what we installed; refreshing is lossless.
+ * "current"  — already identical to the payload; nothing to do.
+ * "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) {
+  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";
+  return now === baselineHash ? "clean" : "modified";
+}
+
+/** True when a classification means "do not overwrite without an explicit flag". */
+export const isProtected = (verdict) => verdict === "modified" || verdict === "unknown";