@davidbalzan/groundwork 0.3.1

package/src/commands/status.mjs

@@ -0,0 +1,96 @@
+import fs from "node:fs";
+import path from "node:path";
+import { TARGET } from "../lib/paths.mjs";
+import { exists, readText, walk } from "../lib/fs.mjs";
+import { log, bold, green, dim, yellow, cyan } from "../lib/log.mjs";
+import { countCheckboxes, progressBar } from "../lib/progress.mjs";
+import { boardRowsOf, parseWorkDoc, workstreamsV1RowsOf } from "@davidbalzan/groundwork-seam";
+
+export function collectStatus(targetDir) {
+  const root = path.resolve(targetDir || ".");
+  const docs = path.join(root, TARGET.docs);
+  if (!exists(docs)) return { ok: false, error: "No docs/ directory here. Run `groundwork init` first." };
+
+  const streams = [];
+  let legacyLanes = false;
+  const ws = path.join(docs, "WORKSTREAMS.md");
+  if (exists(ws)) {
+    const wsDoc = parseWorkDoc(readText(ws));
+    for (const r of workstreamsV1RowsOf(wsDoc)) {
+      streams.push({
+        stream: r.stream,
+        owner: r.owner,
+        branchWorktree: r.branchWorktree,
+        status: r.status,
+        blocker: r.blocker,
+        lastNote: r.lastNote,
+      });
+    }
+    legacyLanes = !streams.length && boardRowsOf(wsDoc).length > 0;
+  }
+
+  const queue = [path.join(docs, "QUEUE.md"), path.join(docs, "BACKLOG.md")].find(exists);
+  const next = queue ? firstUnchecked(readText(queue)) : null;
+  const queueFound = !!queue;
+
+  const phases = [];
+  const phasesDir = path.join(docs, "phases");
+  if (exists(phasesDir)) {
+    for (const rel of walk(phasesDir)) {
+      if (!/PHASE.*TASKS\.md$/i.test(rel)) continue;
+      const { done, total } = countCheckboxes(readText(path.join(phasesDir, rel)));
+      phases.push({
+        label: rel.split(path.sep)[0],
+        done,
+        total,
+        pct: total ? Math.round((done / total) * 100) : 0,
+      });
+    }
+  }
+
+  return { ok: true, streams, legacyLanes, next, queueFound, phases };
+}
+
+/** A read-only project dashboard: live streams + next backlog item + phase progress. */
+export function status(targetDir, opts = {}) {
+  const report = collectStatus(targetDir);
+  if (opts.json) {
+    console.log(JSON.stringify(report, null, 2));
+    if (!report.ok) process.exitCode = 1;
+    return;
+  }
+  if (!report.ok) {
+    log.warn(report.error);
+    return;
+  }
+
+  log.heading("Active streams");
+  if (report.streams.length)
+    report.streams.forEach((r) =>
+      console.log(`  ${r.stream}  ${dim(r.owner)}  ${r.status}${r.lastNote ? `  ${r.lastNote}` : ""}`),
+    );
+  else if (report.legacyLanes)
+    log.info(dim("  legacy lanes table present; not the Active Streams view"));
+  else log.info(dim("  none"));
+
+  log.heading("Next in queue");
+  if (!report.queueFound) log.info(dim("  QUEUE.md not found (run /plan-phase)"));
+  else console.log("  " + (report.next ? cyan(report.next) : dim("queue empty")));
+
+  log.heading("Phase progress");
+  if (!report.phases.length) log.info(dim("  no PHASE*_TASKS.md files yet (run /plan-phase)"));
+  else
+    for (const p of report.phases) {
+      console.log(
+        `  ${bold(p.label.padEnd(10))} ${progressBar(p.pct)} ${p.pct
+          .toString()
+          .padStart(3)}%  ${dim(`(${p.done}/${p.total})`)}`,
+      );
+    }
+}
+
+/** First unchecked `- [ ]` task line, trimmed. */
+function firstUnchecked(text) {
+  const m = text.split("\n").find((l) => /^\s*-\s*\[ \]/.test(l));
+  return m ? m.replace(/^\s*-\s*\[ \]\s*/, "").trim() : null;
+}

package/src/commands/update.mjs

@@ -0,0 +1,128 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  PAYLOAD_SKILLS,
+  PAYLOAD_SCRIPTS,
+  PAYLOAD_DOCS,
+  PKG_ROOT,
+  TARGET,
+} from "../lib/paths.mjs";
+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";
+
+/**
+ * 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.
+ */
+export function update(targetDir, flags = {}) {
+  const root = path.resolve(targetDir || ".");
+  log.heading(`Updating Groundwork → ${cyan(root)}`);
+
+  const installed = listDirs(path.join(root, TARGET.skills));
+  if (installed.length === 0) {
+    log.warn("No skills found here. Run `groundwork init` first.");
+    return;
+  }
+
+  const payloadSkills = listDirs(PAYLOAD_SKILLS);
+  const newSkills = payloadSkills.filter((s) => !installed.includes(s));
+  // With --all, also install skills added upstream since this project's init.
+  const toRefresh = flags.all ? [...installed, ...newSkills] : installed;
+
+  // 1. Skills (force-refresh)
+  let refreshed = 0;
+  let added = 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,
+    });
+    installed.includes(name) ? refreshed++ : added++;
+  }
+
+  // 2. Regenerate mirrors for the resulting skill set
+  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);
+  }
+
+  // 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 }
+      );
+      scripts++;
+    }
+  }
+
+  // 4. Regenerate the generated reference doc (ARTIFACTS.md) — not project-authored
+  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.
+  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 });
+      docs++;
+    }
+  }
+
+  // 5. Stamp the version marker
+  const version = pkgVersion();
+  fs.mkdirSync(path.join(root, TARGET.docs, ".groundwork"), { recursive: true });
+  fs.writeFileSync(
+    path.join(root, TARGET.docs, ".groundwork", "VERSION"),
+    version + "\n"
+  );
+
+  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)."
+    )
+  );
+
+  if (!flags.all && newSkills.length) {
+    log.heading("New skills available upstream (not installed)");
+    for (const s of newSkills) console.log(`  ${green("+")} ${s}`);
+    console.log(
+      dim(
+        `  Add one: ${bold("groundwork add <name>")}   ·   or all: ${bold("groundwork update --all")}`
+      )
+    );
+  }
+}
+
+function pkgVersion() {
+  try {
+    return JSON.parse(
+      fs.readFileSync(path.join(PKG_ROOT, "package.json"), "utf8")
+    ).version;
+  } catch {
+    return "0.0.0";
+  }
+}

package/src/lib/adr-tripwire.mjs

@@ -0,0 +1,171 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * ADR tripwire — deterministic, offline. For every *Accepted* ADR in DECISIONS.md, take the
+ * rows of its "Alternatives Considered" table (the things the ADR REJECTED) and look for them
+ * in reality: dependency names across every package.json in the repo, and top-level /
+ * workspace directory names. A hit means the tree now contains what the ADR said it wouldn't —
+ * either the ADR was silently reversed (supersede it) or the deviation is accepted (record a
+ * FACT `adr-NNN-accepted-deviation`, which suppresses the warning). A status of "Superseded by"
+ * or "amended by ADR-NNN" also suppresses — the newer ADR carries the live claim.
+ *
+ * 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.
+ */
+
+/** Alternative-name → package/dir tokens it usually shows up as. Extend freely; lowercase. */
+export const ALIASES = {
+  "react native": ["react-native", "expo", "@react-navigation/native", "eas.json"],
+  "native ios + android": ["ios", "android", "expo", "react-native", "podfile"],
+  "native ios": ["ios", "podfile"],
+  "native android": ["android"],
+  "native app": ["expo", "react-native", "ios", "android"],
+  "capacitor/ionic": ["@capacitor/core", "@ionic/react", "@ionic/core"],
+  capacitor: ["@capacitor/core"],
+  ionic: ["@ionic/react", "@ionic/core"],
+  flutter: ["pubspec.yaml"],
+  express: ["express"],
+  fastify: ["fastify"],
+  koa: ["koa"],
+  nestjs: ["@nestjs/core"],
+  "next.js": ["next"],
+  nuxt: ["nuxt"],
+  "email + password": ["bcrypt", "bcryptjs", "argon2", "@node-rs/argon2", "@node-rs/bcrypt"],
+  password: ["bcrypt", "bcryptjs", "argon2", "@node-rs/argon2"],
+  "oauth (google/apple)": ["passport", "passport-google-oauth20", "arctic", "next-auth", "@auth/core", "google-auth-library"],
+  oauth: ["passport", "arctic", "next-auth", "@auth/core", "google-auth-library"],
+  "passkeys/webauthn": ["@simplewebauthn/server", "@simplewebauthn/browser"],
+  "openai only": ["openai"],
+  openai: ["openai"],
+  "self-hosted llm": ["ollama", "@lmstudio/sdk", "node-llama-cpp"],
+  mongodb: ["mongodb", "mongoose"],
+  mysql: ["mysql2", "mysql"],
+  sqlite: ["better-sqlite3", "sqlite3", "@libsql/client"],
+  prisma: ["prisma", "@prisma/client"],
+  typeorm: ["typeorm"],
+  sequelize: ["sequelize"],
+  knex: ["knex"],
+  "swagger ui": ["swagger-ui-express", "swagger-ui-dist"],
+  redoc: ["redoc"],
+  "pg-boss": ["pg-boss"],
+  agenda: ["agenda"],
+  "bull (v3)": ["bull"],
+  bull: ["bull"],
+  celery: ["celery"],
+  "npm workspaces": [],
+  "yarn workspaces": ["yarn.lock"],
+  turborepo: ["turbo"],
+  nx: ["nx"],
+  lerna: ["lerna"],
+  firebase: ["firebase", "firebase-admin"],
+  supabase: ["@supabase/supabase-js"],
+  graphql: ["graphql", "@apollo/server", "@apollo/client"],
+  trpc: ["@trpc/server"],
+  redux: ["@reduxjs/toolkit", "redux"],
+  mobx: ["mobx"],
+  jotai: ["jotai"],
+  "styled-components": ["styled-components"],
+  emotion: ["@emotion/react"],
+  "material ui": ["@mui/material"],
+  bootstrap: ["bootstrap"],
+  webpack: ["webpack"],
+  jest: ["jest"],
+  mocha: ["mocha"],
+  cypress: ["cypress"],
+  playwright: ["@playwright/test"],
+};
+
+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[]}. */
+export function parseAdrs(text) {
+  const out = [];
+  const parts = text.split(/^(?=## ADR-\d+)/m);
+  for (const p of parts) {
+    const h = p.match(/^## (ADR-\d+):\s*(.+)$/m);
+    if (!h) continue;
+    const status = (p.match(/\*\*Status\*\*:\s*(.+)/) || [])[1]?.trim() || "";
+    const alternatives = [];
+    const alt = p.split(/###\s*Alternatives Considered/i)[1];
+    if (alt) {
+      for (const line of alt.split("\n")) {
+        const m = line.match(/^\|\s*([^|]+?)\s*\|/);
+        if (!m) continue;
+        const name = m[1].trim();
+        if (!name || /^-+$/.test(name) || /^alternative$/i.test(name) || /^option [a-z]$/i.test(name) || name === "...") continue;
+        alternatives.push(name);
+      }
+    }
+    out.push({ id: h[1], title: h[2].trim(), status, alternatives });
+  }
+  return out;
+}
+
+/** Tokens to look for, for one alternative name. */
+export function tokensFor(alternative) {
+  const key = alternative.toLowerCase().replace(/\*+/g, "").replace(/\s+/g, " ").trim();
+  if (key in ALIASES) return ALIASES[key];
+  // generic: the full slug, plus meaningful single words (>=4 chars, not stopwords)
+  const words = key.replace(/[()]/g, " ").split(/[\s/+,]+/).filter(Boolean);
+  const set = new Set();
+  if (words.length > 1) set.add(words.join("-"));
+  for (const w of words) {
+    if (w.length >= 4 && !STOP.has(w) && !/^\d/.test(w)) set.add(w);
+    if (w in ALIASES) for (const t of ALIASES[w]) set.add(t);
+  }
+  return [...set];
+}
+
+/** Collect reality: dependency names (all package.json outside node_modules, depth<=4) + dir names (root + one level) + a few marker files. */
+export function collectReality(root) {
+  const deps = new Map(); // name -> where
+  const dirs = new Map(); // lowercased dir/file name -> relative path
+  const skip = new Set(["node_modules", ".git", "dist", "build", ".next", "coverage", ".turbo", ".expo"]);
+  const walk = (dir, depth) => {
+    let ents = [];
+    try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      if (skip.has(e.name)) continue;
+      const full = path.join(dir, e.name);
+      const rel = path.relative(root, full) || ".";
+      if (e.isDirectory()) {
+        if (depth <= 1) dirs.set(e.name.toLowerCase(), rel);
+        if (depth < 4) walk(full, depth + 1);
+      } else if (e.name === "package.json") {
+        try {
+          const pkg = JSON.parse(fs.readFileSync(full, "utf8"));
+          for (const k of ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"])
+            for (const name of Object.keys(pkg[k] || {})) if (!deps.has(name)) deps.set(name, rel);
+        } catch { /* ignore */ }
+      } else if (depth <= 2 && /^(podfile|pubspec\.yaml|eas\.json|yarn\.lock|app\.json)$/i.test(e.name)) {
+        dirs.set(e.name.toLowerCase(), rel);
+      }
+    }
+  };
+  walk(root, 0);
+  return { deps, dirs };
+}
+
+/** Run the tripwire. Returns [{adr, alternative, token, kind, where}]. */
+export function adrTripwire({ decisionsText, root, acceptedFactIds = new Set() }) {
+  const hits = [];
+  const { deps, dirs } = collectReality(root);
+  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));
+    const factId = `${adr.id.toLowerCase()}-accepted-deviation`;
+    if (acceptedFactIds.has(factId)) continue;
+    for (const alternative of adr.alternatives) {
+      for (const token of tokensFor(alternative)) {
+        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) });
+      }
+    }
+  }
+  return hits;
+}

package/src/lib/artifacts.mjs

@@ -0,0 +1,124 @@
+/*
+ * Single source of truth for Groundwork's doc artifacts.
+ * Everything that lists "which docs exist + who writes/reads them" derives from here:
+ * - docs/ARTIFACTS.md is GENERATED from this (see renderArtifactsDoc)
+ * - `scope` classifies each doc, which `update --docs` uses to know what is safe to refresh
+ *   ("reference" = generic, same across projects → refreshable; "project" = yours → never touched)
+ *
+ * Add a doc in ONE place: append an entry here, then `groundwork artifacts` regenerates the map.
+ */
+
+/** @typedef {"project"|"reference"|"external"} Scope */
+
+export const ARTIFACTS = [
+  // --- project artifacts (generated per project; vary; never auto-refreshed) ---
+  { path: "docs/PRD.md", scope: "project", purpose: "Product definition (problem, users, goals, scope, requirements)", writtenBy: "/create-prd", readBy: "/kickstart, /plan-phase", rules: "First artifact; the source for scaffolding" },
+  { path: "docs/CONTEXT.md (+ CONTEXT-MAP.md)", scope: "project", purpose: "Ubiquitous-language glossary / domain model", writtenBy: "/domain-model", readBy: "/start-session, /plan-phase", rules: "Glossary only — no implementation detail" },
+  { path: "docs/TECH_STACK.md", scope: "project", purpose: "Technology choices narrative", writtenBy: "/kickstart", readBy: "/plan-phase, /start-session", rules: "No version numbers here — link to STACK_MAP" },
+  { path: "docs/STACK_MAP.md", scope: "project", purpose: "Single source of truth for versions (pinned + latest)", writtenBy: "/kickstart, /check-versions", readBy: "anyone bumping deps", rules: "The only place a version appears" },
+  { path: "docs/ARCHITECTURE_GUIDE.md", scope: "project", purpose: "System design, patterns, the \"why\"", writtenBy: "/kickstart", readBy: "/plan-phase", rules: "—" },
+  { path: "docs/DECISIONS.md", scope: "project", purpose: "Project ADRs (decision log)", writtenBy: "/log-decision, /kickstart", readBy: "/start-session", rules: "ADRs are immutable; supersede, don't edit" },
+  { path: "docs/PRODUCTION_ROADMAP.md", scope: "project", purpose: "Phase roadmap + \"Current Status\" pointer", writtenBy: "/kickstart, /plan-phase", readBy: "/start-session, groundwork status", rules: "Current Status points at WORKSTREAMS" },
+  { path: "docs/phases/phaseN/README.md", scope: "project", purpose: "Phase overview", writtenBy: "/plan-phase", readBy: "/start-session", rules: "—" },
+  { path: "docs/phases/phaseN/PHASEN_TASKS.md", scope: "project", purpose: "Detailed checkbox tasks", writtenBy: "/plan-phase", readBy: "/check-task, /start-session, groundwork status", rules: "Progress recomputed by the helper script" },
+  { path: "docs/WORKSTREAMS.md", scope: "project", purpose: "Live state of parallel streams", writtenBy: "/update-workstreams + coordinator", readBy: "everyone, /start-session", rules: "One row per active stream" },
+  { path: "docs/QUEUE.md", scope: "project", purpose: "Inbound queue (phases + ad-hoc)", writtenBy: "/plan-phase + human", readBy: "/start-session, coordinator", rules: "Single writer per file: human/proxy only; executors never edit it" },
+  { 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)" },
+
+  // --- 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" },
+
+  // --- cross-project (external; lives in the central knowledge repo) ---
+  { path: "$GROUNDWORK_KNOWLEDGE/notes/lessons.md", scope: "external", purpose: "Raw cross-project lessons", writtenBy: "/remember" },
+  { path: "$GROUNDWORK_KNOWLEDGE/adr/NNNN-*.md", scope: "external", purpose: "Formal cross-project ADRs", writtenBy: "/remember --adr" },
+];
+
+/** Doc paths that `update --docs` may safely refresh (generic, not project-authored). */
+export function refreshableDocs() {
+  return ARTIFACTS.filter((a) => a.scope === "reference" && a.path.endsWith(".md")).map(
+    (a) => a.path
+  );
+}
+
+const esc = (s) => String(s ?? "—").replace(/\|/g, "\\|");
+
+/** Render docs/ARTIFACTS.md from the manifest. */
+export function renderArtifactsDoc() {
+  const project = ARTIFACTS.filter((a) => a.scope === "project");
+  const reference = ARTIFACTS.filter((a) => a.scope === "reference");
+  const external = ARTIFACTS.filter((a) => a.scope === "external");
+
+  const projRows = project
+    .map((a) => `| \`${esc(a.path)}\` | ${esc(a.purpose)} | ${esc(a.writtenBy)} | ${esc(a.readBy)} | ${esc(a.rules)} |`)
+    .join("\n");
+  const refRows = reference.map((a) => `| \`${esc(a.path)}\` | ${esc(a.purpose)} |`).join("\n");
+  const extRows = external
+    .map((a) => `| \`${esc(a.path)}\` | ${esc(a.purpose)} | ${esc(a.writtenBy)} |`)
+    .join("\n");
+
+  return `---
+title: "Artifact Map"
+tags: [groundwork/reference]
+aliases: ["Artifacts", "Artifact Map", "Where things live"]
+---
+
+<!-- GENERATED from the Groundwork artifact manifest. Do not edit by hand;
+     run \`groundwork artifacts\` after editing the manifest. -->
+
+# Artifact Map
+
+> **Agent reference.** Every Groundwork doc artifact: what it is, which skill **writes**
+> it, who **reads** it, and the rules for touching it. Consult this to know *where things
+> live* before reading or editing — especially when picking up a \`[[QUEUE]]\` item.
+
+## Project artifacts
+
+| Artifact | Purpose | Written by | Read by | Rules |
+| -------- | ------- | ---------- | ------- | ----- |
+${projRows}
+
+## Reference (shipped, generic — same across projects)
+
+| Artifact | Purpose |
+| -------- | ------- |
+${refRows}
+
+## Cross-project (external)
+
+| Artifact | Purpose | Written by |
+| -------- | ------- | ---------- |
+${extRows}
+
+Resolve the central knowledge repo with \`groundwork knowledge path\`. Project-specific
+decisions stay in \`docs/DECISIONS.md\`; cross-project lessons go to the central repo.
+
+## Terms (Groundwork's own vocabulary)
+
+- **ADR / decision** — a *formal, structured* record of a choice with rationale and
+  trade-offs. Lives in \`docs/DECISIONS.md\` (project, via \`/log-decision\`) or
+  \`$GROUNDWORK_KNOWLEDGE/adr/\` (cross-project, via \`/remember --adr\`). Has frontmatter + sections.
+- **Lesson / note** — a *raw, one-line, dated* capture via \`/remember\` to
+  \`$GROUNDWORK_KNOWLEDGE/notes/lessons.md\`. Unstructured; promote a keeper into an ADR
+  with \`/remember --adr\`.
+- **Decision vs lesson:** a decision is "we chose X over Y because…"; a lesson is "X is
+  worth remembering."
+
+When a project's *own* domain reuses these words, define how its model maps onto these
+source meanings in its \`docs/CONTEXT.md\`.
+
+## The swarm seam (optional)
+
+- **\`QUEUE.md\`** = what to do next (inbound). **\`WORKSTREAMS.md\`** = what's in flight (live). **\`DONE.md\`** = what shipped (completion log). **\`FACTS.md\`** = what's settled (verified world-model).
+- Split by writer so single-writer-per-*file* is filesystem-enforced: humans write QUEUE, the executor appends to DONE and never touches QUEUE; whoever verified a fact writes it.
+- An external coordinator reads QUEUE, opens a stream in WORKSTREAMS, and appends completions to DONE as work proceeds; agents cite FACTS ids instead of restating world-state.
+- Optional — Groundwork runs solo without it. The coordinator depends on this seam, not the
+  reverse. Reference implementation: **\`coord-mcp\`** (MCP-based, harness-agnostic).
+`;
+}

package/src/lib/config.mjs

@@ -0,0 +1,43 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** Per-user config dir (XDG-aware), e.g. ~/.config/groundwork/config.json */
+export function configDir() {
+  const base =
+    process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+  return path.join(base, "groundwork");
+}
+export function configFile() {
+  return path.join(configDir(), "config.json");
+}
+
+export function readConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(configFile(), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+export function writeConfig(patch) {
+  const dir = configDir();
+  fs.mkdirSync(dir, { recursive: true });
+  const merged = { ...readConfig(), ...patch };
+  fs.writeFileSync(configFile(), JSON.stringify(merged, null, 2) + "\n");
+  return merged;
+}
+
+/**
+ * Resolve the central knowledge-repo path for THIS user.
+ * Order: $GROUNDWORK_KNOWLEDGE env → user config `knowledgeRepo` → null.
+ * No personal/hardcoded defaults — varies per user by design.
+ */
+export function resolveKnowledgePath() {
+  const fromEnv = process.env.GROUNDWORK_KNOWLEDGE;
+  if (fromEnv) return { path: fromEnv, source: "env (GROUNDWORK_KNOWLEDGE)" };
+  const cfg = readConfig();
+  if (cfg.knowledgeRepo)
+    return { path: cfg.knowledgeRepo, source: `config (${configFile()})` };
+  return { path: null, source: null };
+}

package/src/lib/fs.mjs

@@ -0,0 +1,46 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const exists = (p) => fs.existsSync(p);
+
+export const readText = (p) => fs.readFileSync(p, "utf8");
+
+export function writeText(p, content) {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, content);
+}
+
+export function listDirs(p) {
+  if (!exists(p)) return [];
+  return fs
+    .readdirSync(p, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name)
+    .sort();
+}
+
+/**
+ * Recursively walk a directory, yielding paths relative to `root`.
+ */
+export function* walk(root, rel = "") {
+  const dir = path.join(root, rel);
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const childRel = path.join(rel, entry.name);
+    if (entry.isDirectory()) {
+      yield* walk(root, childRel);
+    } else {
+      yield childRel;
+    }
+  }
+}
+
+/**
+ * Copy a single file unless it exists (when `force` is false).
+ * Returns "added" | "skipped".
+ */
+export function copyFileSafe(src, dest, { force = false } = {}) {
+  if (exists(dest) && !force) return "skipped";
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+  return exists(dest) ? "added" : "skipped";
+}

package/src/lib/log.mjs

@@ -0,0 +1,22 @@
+/* Tiny dependency-free logger with consistent, scannable output. */
+
+const COLOR = process.stdout.isTTY && !process.env.NO_COLOR;
+const c = (code, s) => (COLOR ? `\x1b[${code}m${s}\x1b[0m` : s);
+
+export const dim = (s) => c("2", s);
+export const bold = (s) => c("1", s);
+export const green = (s) => c("32", s);
+export const yellow = (s) => c("33", s);
+export const red = (s) => c("31", s);
+export const cyan = (s) => c("36", s);
+
+export const log = {
+  info: (msg) => console.log(msg),
+  step: (msg) => console.log(`${cyan("›")} ${msg}`),
+  ok: (msg) => console.log(`${green("✓")} ${msg}`),
+  warn: (msg) => console.log(`${yellow("!")} ${msg}`),
+  err: (msg) => console.error(`${red("✗")} ${msg}`),
+  added: (p) => console.log(`  ${green("+")} ${dim(p)}`),
+  skipped: (p) => console.log(`  ${dim("·")} ${dim(p + " (exists, skipped)")}`),
+  heading: (msg) => console.log(`\n${bold(msg)}`),
+};

package/src/lib/paths.mjs

@@ -0,0 +1,36 @@
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/** Repo root of the groundwork package (one level above src/). */
+export const PKG_ROOT = path.resolve(__dirname, "..", "..");
+
+/** Source payload shipped with the package. */
+export const PAYLOAD = path.join(PKG_ROOT, "payload");
+export const PAYLOAD_SKILLS = path.join(PAYLOAD, "skills");
+export const PAYLOAD_DOCS = path.join(PAYLOAD, "doc-templates");
+export const PAYLOAD_SCRIPTS = path.join(PAYLOAD, "scripts");
+
+/** Where each artifact lands inside a TARGET project. */
+export const TARGET = {
+  skills: ".claude/skills",
+  cursor: ".cursor/commands",
+  vscode: ".vscode/prompts",
+  docs: "docs",
+  scripts: "docs/.groundwork/scripts",
+};
+
+/**
+ * The minimal skill set (mirrors the old "lite" repo). `init --minimal`
+ * installs only these; everything else is optional via `groundwork add`.
+ */
+export const MINIMAL_SKILLS = [
+  "check-task",
+  "kickstart",
+  "next",
+  "plan-phase",
+  "start-session",
+  "update-workstreams",
+];