@davidbalzan/groundwork 0.3.4 → 0.4.1

package/LICENSE

@@ -1,16 +1,14 @@
-MIT License
-
 Copyright (c) 2026 David Balzan
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+All rights reserved.
+
+This software and its accompanying files are proprietary. No licence is
+granted to use, copy, modify, merge, publish, distribute, sublicense, or sell
+copies of this software, in whole or in part, except by a separate written
+agreement signed by the copyright holder.
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+Possession of these files — including by download from a public package
+registry — does not constitute such an agreement and grants no rights.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidbalzan/groundwork",
-  "version": "0.3.4",
+  "version": "0.4.1",
   "description": "Groundwork — an installable AI development workflow (skills + doc methodology) you bolt onto any repo.",
   "type": "module",
   "bin": {
@@ -13,7 +13,8 @@
     "src",
     "payload",
     "docs",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "keywords": [
     "ai",
@@ -26,13 +27,13 @@
     "methodology"
   ],
   "author": "David Balzan",
-  "license": "MIT",
+  "license": "UNLICENSED",
   "dependencies": {
-    "@davidbalzan/groundwork-seam": "0.1.2"
+    "@davidbalzan/groundwork-seam": "0.1.5"
   },
   "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/payload/doc-templates/FACTS.md

@@ -38,6 +38,6 @@ glyphs, not ASCII. Parsers (doctor, `set-fact.mjs`, UIs) split on those glyphs.
 ## Facts
 
 <!-- add entries in the pinned format above, e.g.:
-     - `auto-disavow-flag` — does NOT exist anywhere in the codebase
-       verified: 2026-07-02T14:30Z · by: disavow-worker-1 · method: git grep + gh api origin/main
+     - `nightly-export-job` — does NOT exist anywhere in the codebase
+       verified: 2026-07-02T14:30Z · by: <project>-worker-1 · method: git grep + gh api origin/main
 -->

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/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/adr-tripwire.mjs

@@ -15,7 +15,7 @@ import path from "node:path";
  *
  * Shared-token suppression: tokens that also appear in the ADR title / Decision / Context
  * (alias-expanded) are the accepted path, not evidence of the reject. Generic project-wide
- * paths (`docs`, `templates`, `readme`, `wiki`) are not hits. Cass burned an audit cycle on
+ * paths (`docs`, `templates`, `readme`, `wiki`) are not hits. A consumer fleet burned an audit cycle on
  * `next` (accepted Next.js), top-level `docs/`, and `docs/templates`.
  */
 
@@ -85,7 +85,7 @@ const STOP = new Set(["the", "and", "with", "only", "over", "for", "app", "api",
 
 /**
  * Top-level / workspace path tokens that every repo tends to have. A hit on these is
- * project-wide, not evidence of a rejected alternative (cass: `docs/`, `docs/templates`).
+ * project-wide, not evidence of a rejected alternative (field report: `docs/`, `docs/templates`).
  * Dependency names are not filtered here — `next` still fires unless it is in `own`.
  */
 export const GENERIC_PATHS = new Set(["docs", "templates", "readme", "wiki"]);

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