@davidbalzan/groundwork 0.3.1 → 0.3.2

package/README.md

@@ -9,12 +9,12 @@ It's a small CLI that installs the workflow into any repo — new or existing
 in place as it improves. (A bolt-on, not a template you fork.)
 
 ```bash
-npx github:davidbalzan/groundwork init        # full workflow into the current repo
-npx github:davidbalzan/groundwork init . --minimal   # just the core 6 skills
+npm i -g @davidbalzan/groundwork
+groundwork init                 # full workflow into the current repo
+groundwork init . --minimal     # just the core 6 skills
 ```
 
-> **Private repo:** `npx github:...` needs GitHub auth (the `gh` CLI login is enough).
-> Make it public with `gh repo edit davidbalzan/groundwork --visibility public`.
+> Source lives in the [groundwork-kit](https://github.com/davidbalzan/groundwork-kit) monorepo (`packages/groundwork`); the old `davidbalzan/groundwork` remote is frozen.
 
 > **One-time per machine** (only if you use `/remember`): point Groundwork at your central
 > knowledge repo — `groundwork knowledge link <path>` (or `export GROUNDWORK_KNOWLEDGE=<path>`
@@ -196,7 +196,9 @@ Honest boundary: `doctor` catches *structural / consistency* drift, **not** whet
 matches the running code — that still needs you or the agent (or the optional test tripwire).
 The ADR tripwire is keyword-based (`src/lib/adr-tripwire.mjs` `ALIASES` maps alternative names
 to package/dir tokens — extend it); it catches the reversal that shows up as a dependency or a
-folder, not one that is pure code.
+folder, not one that is pure code. Tokens that also appear in the ADR title / Decision / Context
+(alias-expanded) are the accepted path and are not hits; generic project-wide paths (`docs/`,
+`templates/`) are not hits.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidbalzan/groundwork",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Groundwork — an installable AI development workflow (skills + doc methodology) you bolt onto any repo.",
   "type": "module",
   "bin": {
@@ -28,7 +28,7 @@
   "author": "David Balzan",
   "license": "MIT",
   "dependencies": {
-    "@davidbalzan/groundwork-seam": "0.1.0"
+    "@davidbalzan/groundwork-seam": "0.1.1"
   },
   "scripts": {
     "groundwork": "node src/cli.mjs",

package/src/cli.mjs

@@ -66,7 +66,11 @@ function help() {
 const [cmd, ...rest] = argv;
 const { flags, pos } = parse(rest);
 
-try {
+// `--*` are flags; `-h` is positional. Either form after a command must print
+// usage and not run the command (`init --help` / `init -h` used to init cwd).
+if (flags.help || flags.h || pos.includes("-h") || pos.includes("--help")) {
+  help();
+} else try {
   switch (cmd) {
     case "init":
       init(pos[0], flags);

package/src/commands/doctor.mjs

@@ -44,6 +44,10 @@ export function collectDoctor(targetDir) {
   push("orphan-wikilinks", orphanItems.length ? "warn" : "ok", orphanItems.length ? orphanItems : ["all wikilinks resolve"]);
 
   const phaseDir = path.join(docs, "phases");
+  const roadmapText = exists(path.join(docs, "PRODUCTION_ROADMAP.md"))
+    ? readText(path.join(docs, "PRODUCTION_ROADMAP.md"))
+    : "";
+  const doneText = exists(path.join(docs, "DONE.md")) ? readText(path.join(docs, "DONE.md")) : "";
   const phaseItems = [];
   let phaseWarn = false;
   if (exists(phaseDir)) {
@@ -54,8 +58,14 @@ export function collectDoctor(targetDir) {
       const label = rel.split(path.sep)[0];
       const line = `${label}  ${progressBar(pct)} ${pct}% (${done}/${total})`;
       if (total > 0 && done === total) {
-        phaseWarn = true;
-        phaseItems.push(`${line} — 100% done; mark it complete in the roadmap & record it in DONE.md`);
+        const n = phaseNumberFromDir(label);
+        const closed = n != null && (roadmapPhaseComplete(roadmapText, n) || doneLineNamesPhase(doneText, n));
+        if (closed) {
+          phaseItems.push(`${line} — 100% done; recorded complete`);
+        } else {
+          phaseWarn = true;
+          phaseItems.push(`${line} — 100% done; mark it complete in the roadmap & record it in DONE.md`);
+        }
       } else phaseItems.push(line);
     }
   }
@@ -119,6 +129,13 @@ export function collectDoctor(targetDir) {
     else push("workstreams", "ok", ["write grammar is workstreams.v1"]);
   } else push("workstreams", "info", ["no WORKSTREAMS.md yet (run `groundwork update --docs`)"]);
 
+  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");
   if (exists(factsFile)) {
     const { entries, issues } = parseFactsDoc(readText(factsFile));
@@ -197,6 +214,22 @@ export function doctor(targetDir, opts = {}) {
 }
 
 // ---------- helpers ----------
+function phaseNumberFromDir(label) {
+  const m = String(label).match(/^phase(\d+)/i);
+  return m ? Number(m[1]) : null;
+}
+
+function roadmapPhaseComplete(roadmapText, n) {
+  const parts = String(roadmapText).split(/^(?=###\s*Phase\s+\d+)/im);
+  const block = parts.find((p) => new RegExp(`^###\\s*Phase\\s+${n}\\b`, "i").test(p)) ?? "";
+  return /\*\*Status\*\*:\s*🟢\s*Complete\b/i.test(block);
+}
+
+function doneLineNamesPhase(doneText, n) {
+  const re = new RegExp(`\\bPhase\\s+${n}\\b`, "i");
+  return String(doneText).split("\n").some((line) => re.test(line));
+}
+
 function wikilinks(text) {
   const out = [];
   for (const m of text.matchAll(/\[\[([^\]]+)\]\]/g)) {

package/src/lib/adr-tripwire.mjs

@@ -12,6 +12,11 @@ import path from "node:path";
  *
  * Field case: two ADRs (PWA-not-native, magic-link-not-password) reversed in the same week
  * and stayed ✅ Accepted for five months; the docs agents read every session were wrong.
+ *
+ * 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
+ * `next` (accepted Next.js), top-level `docs/`, and `docs/templates`.
  */
 
 /** Alternative-name → package/dir tokens it usually shows up as. Extend freely; lowercase. */
@@ -78,7 +83,26 @@ export const ALIASES = {
 
 const STOP = new Set(["the", "and", "with", "only", "over", "for", "app", "api", "via", "using", "based", "plain", "custom", "own", "direct", "integration", "hosted", "self", "native", "web", "server", "client", "service", "services", "library", "libraries", "framework", "solution", "approach", "option", "none", "n/a"]);
 
-/** Parse DECISIONS.md into ADR blocks: {id, title, status, alternatives[]}. */
+/**
+ * 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`).
+ * Dependency names are not filtered here — `next` still fires unless it is in `own`.
+ */
+export const GENERIC_PATHS = new Set(["docs", "templates", "readme", "wiki"]);
+
+/** Pull a `### Heading` body from an ADR block. Stops at the next `###`. */
+export function sectionBody(block, heading) {
+  const parts = block.split(/^###\s+/m);
+  const want = heading.toLowerCase();
+  for (const part of parts) {
+    const nl = part.indexOf("\n");
+    const h = (nl === -1 ? part : part.slice(0, nl)).trim();
+    if (h.toLowerCase() === want) return (nl === -1 ? "" : part.slice(nl + 1)).trim();
+  }
+  return "";
+}
+
+/** Parse DECISIONS.md into ADR blocks: {id, title, status, decision, context, alternatives[]}. */
 export function parseAdrs(text) {
   const out = [];
   const parts = text.split(/^(?=## ADR-\d+)/m);
@@ -97,11 +121,38 @@ export function parseAdrs(text) {
         alternatives.push(name);
       }
     }
-    out.push({ id: h[1], title: h[2].trim(), status, alternatives });
+    out.push({
+      id: h[1],
+      title: h[2].trim(),
+      status,
+      decision: sectionBody(p, "Decision"),
+      context: sectionBody(p, "Context"),
+      alternatives,
+    });
   }
   return out;
 }
 
+/**
+ * Tokens that name the ADR's accepted path. Title + Decision + Context (not Alternatives),
+ * plus ALIASES expansion (`next.js` → `next`) so a shared dep is not evidence of the reject.
+ */
+export function ownTokens(adr) {
+  const own = new Set();
+  const absorb = (text) => {
+    if (!text) return;
+    for (const w of text.toLowerCase().replace(/[^a-z0-9@/.-]+/g, " ").split(" ").filter(Boolean)) {
+      own.add(w);
+      if (w in ALIASES) for (const t of ALIASES[w]) own.add(t.toLowerCase());
+    }
+    for (const t of tokensFor(text)) own.add(t.toLowerCase());
+  };
+  absorb(adr.title);
+  absorb(adr.decision);
+  absorb(adr.context);
+  return own;
+}
+
 /** Tokens to look for, for one alternative name. */
 export function tokensFor(alternative) {
   const key = alternative.toLowerCase().replace(/\*+/g, "").replace(/\s+/g, " ").trim();
@@ -154,8 +205,9 @@ export function adrTripwire({ decisionsText, root, acceptedFactIds = new Set() }
   for (const adr of parseAdrs(decisionsText)) {
     if (!/accepted/i.test(adr.status)) continue; // proposed / superseded / rejected are not live claims
     if (/superseded|amended by/i.test(adr.status)) continue; // the newer ADR carries the live claim
-    // tokens that name the ADR's own choice are not evidence of the alternative (e.g. "BullMQ repeatable jobs only" vs "BullMQ …")
-    const own = new Set(adr.title.toLowerCase().replace(/[^a-z0-9@/.-]+/g, " ").split(" ").filter(Boolean));
+    // tokens that name the ADR's own choice are not evidence of the alternative
+    // (title + Decision + Context; e.g. Decision names Next.js → do not flag `next`)
+    const own = ownTokens(adr);
     const factId = `${adr.id.toLowerCase()}-accepted-deviation`;
     if (acceptedFactIds.has(factId)) continue;
     for (const alternative of adr.alternatives) {
@@ -163,7 +215,7 @@ export function adrTripwire({ decisionsText, root, acceptedFactIds = new Set() }
         const t = token.toLowerCase();
         if (own.has(t)) continue;
         if (deps.has(t)) hits.push({ adr: adr.id, title: adr.title, alternative, token: t, kind: "dependency", where: deps.get(t) });
-        else if (dirs.has(t)) hits.push({ adr: adr.id, title: adr.title, alternative, token: t, kind: "path", where: dirs.get(t) });
+        else if (dirs.has(t) && !GENERIC_PATHS.has(t)) hits.push({ adr: adr.id, title: adr.title, alternative, token: t, kind: "path", where: dirs.get(t) });
       }
     }
   }