@davidbalzan/groundwork 0.3.1

package/payload/doc-templates/templates/TECH_STACK_TEMPLATE.md

@@ -0,0 +1,199 @@
+---
+title: "Tech Stack Template"
+tags: [groundwork/template]
+aliases: []
+---
+
+# [Project Name] - Complete Tech Stack
+
+> Single source of truth for all technology choices, versions, and rationale. Referenced by AI agents when generating code, suggesting patterns, or debugging compatibility issues.
+
+---
+
+## 📋 Overview
+
+**Project Type**: [Web app / API / CLI / Library / Mobile — describe what this project is and what problem it solves]
+**Architecture**: [Monorepo / Monolith / Microservices — describe the high-level architectural approach and why it was chosen]
+**Primary Language**: [TypeScript / Python / Go / etc. — include version and strict mode configuration]
+
+---
+
+## 🏗️ Architecture
+
+### Project Structure
+
+```
+[project-name]/
+├── apps/
+│   ├── [app-1]/           # [Purpose: what this app does and who uses it]
+│   └── [app-2]/           # [Purpose: what this app does and who uses it]
+├── packages/
+│   ├── [package-1]/       # [Purpose: what shared functionality this provides]
+│   └── [package-2]/       # [Purpose: what shared functionality this provides]
+└── docs/                  # Project documentation and templates
+```
+
+### Data Flow
+
+```
+[Describe the primary data flow through the system, e.g.:]
+[User → Browser → Frontend (React) → API (Hono) → Database (PostgreSQL)]
+[                                   ← JSON Response ←                  ]
+```
+
+---
+
+## 🎨 Frontend Stack ([app location, e.g., apps/web/])
+
+### Core Framework & Build
+
+| Technology               | Version               | Purpose                                                                                         | Why This Choice                                                            |
+| ------------------------ | --------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| [Framework, e.g., React] | [version, e.g., 19.x] | [UI framework — describe rendering model, e.g., "Component-based UI with concurrent rendering"] | [Rationale: ecosystem size, team familiarity, performance characteristics] |
+| [Build Tool, e.g., Vite] | [version, e.g., 6.x]  | [Build & dev server — describe key features, e.g., "HMR, ESM-native, plugin ecosystem"]         | [Rationale: speed vs alternatives, plugin availability]                    |
+| TypeScript               | [version, e.g., 5.x]  | [Type safety — describe strictness level and key compiler options]                              | [Rationale: error prevention, DX, refactoring confidence]                  |
+
+### Styling & UI
+
+| Technology                          | Version              | Purpose                                                                         | Why This Choice                                             |
+| ----------------------------------- | -------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| [CSS Framework, e.g., Tailwind CSS] | [version, e.g., 4.x] | [Styling approach — describe methodology: utility-first, CSS-in-JS, BEM, etc.]  | [Rationale: bundle size, DX, design system alignment]       |
+| [UI Library, e.g., Lucide React]    | [version]            | [Icon/component library — describe what it provides and customization approach] | [Rationale: consistency, bundle size, tree-shaking support] |
+
+### State Management
+
+| Technology                                     | Version   | Purpose                                                                               | Why This Choice                                                    |
+| ---------------------------------------------- | --------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| [State Library, e.g., Zustand / React Context] | [version] | [State management scope — describe what state it manages: global, server, form, etc.] | [Rationale: complexity vs simplicity, bundle size, learning curve] |
+
+### Key Frontend Patterns
+
+- **Routing**: [Library and approach — file-based, config-based, or framework-native]
+- **Data Fetching**: [Library and strategy — SWR, React Query, fetch, or framework-native]
+- **Form Handling**: [Library or approach — controlled, uncontrolled, form library name]
+- **Error Boundaries**: [Strategy for handling runtime errors in the UI]
+
+---
+
+## ⚙️ Backend Stack ([app location, e.g., apps/api/])
+
+### Core Framework & Runtime
+
+| Technology               | Version               | Purpose                                                                                | Why This Choice                                                               |
+| ------------------------ | --------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| [Runtime, e.g., Node.js] | [version, e.g., 22.x] | [Server runtime — describe key features: event loop, worker threads, native ESM, etc.] | [Rationale: performance, ecosystem, deployment target compatibility]          |
+| [Framework, e.g., Hono]  | [version, e.g., 4.x]  | [Web framework — describe middleware model, routing, and key features]                 | [Rationale: performance benchmarks, type safety, portability across runtimes] |
+| TypeScript               | [version]             | [Shared with frontend — note any backend-specific compiler options]                    | [Rationale: end-to-end type safety with shared package]                       |
+
+### Database & ORM
+
+| Technology                   | Version               | Purpose                                                                           | Why This Choice                                                                 |
+| ---------------------------- | --------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| [Database, e.g., PostgreSQL] | [version, e.g., 17.x] | [Primary data store — describe data model: relational, document, key-value, etc.] | [Rationale: ACID compliance, scalability, feature set, managed hosting options] |
+| [ORM, e.g., Drizzle]         | [version]             | [Database toolkit — describe query approach: query builder, ORM, raw SQL, etc.]   | [Rationale: type safety, migration support, performance, learning curve]        |
+
+### Key Backend Patterns
+
+- **Authentication**: [Strategy and library — JWT, sessions, OAuth provider, etc.]
+- **Validation**: [Library and approach — Zod, Joi, class-validator, etc. and where validation occurs]
+- **Error Handling**: [Strategy — centralized error handler, error classes, HTTP status mapping]
+- **Logging**: [Library and format — structured JSON, log levels, correlation IDs]
+- **API Documentation**: [Approach — OpenAPI/Swagger, auto-generated, manual, etc.]
+
+---
+
+## 🔧 Infrastructure
+
+### Package Management & Monorepo
+
+| Technology                       | Version   | Purpose                                                                                         | Why This Choice                                        |
+| -------------------------------- | --------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| [Package Manager, e.g., pnpm]    | [version] | [Dependency management — describe key features: workspaces, hoisting strategy, lockfile format] | [Rationale: disk space, speed, monorepo support]       |
+| [Monorepo Tool, e.g., Turborepo] | [version] | [Build orchestration — describe key features: caching, parallel tasks, dependency graph]        | [Rationale: build speed, DX, configuration simplicity] |
+
+### Development Environment
+
+| Service                                             | URL                                 | Purpose                                                                         |
+| --------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------- |
+| Frontend                                            | http://localhost:[port, e.g., 5173] | [Dev server with HMR — describe proxy configuration if applicable]              |
+| Backend API                                         | http://localhost:[port, e.g., 3000] | [API server — describe auto-reload setup]                                       |
+| Database                                            | localhost:[port, e.g., 5432]        | [Local database — describe how it's provisioned: Docker, native install, cloud] |
+| [Additional services like Redis, mail server, etc.] | localhost:[port]                    | [Purpose and provisioning method]                                               |
+
+### Deployment & CI/CD
+
+- **Hosting**: [Platform and approach — Vercel, AWS, Docker, self-hosted, etc.]
+- **CI/CD**: [Pipeline tool — GitHub Actions, GitLab CI, etc. and key stages]
+- **Environments**: [List environments — dev, staging, production and how they differ]
+- **Containerization**: [Docker setup if applicable — base images, compose services]
+
+---
+
+## 📊 Dependency Summary
+
+### Production Dependencies (Critical Path)
+
+| Package        | Version                        | Location                    | Purpose                                      | Upgrade Risk                                      |
+| -------------- | ------------------------------ | --------------------------- | -------------------------------------------- | ------------------------------------------------- |
+| [Package name] | [Exact version, e.g., ^19.0.0] | [Which app/package uses it] | [What it does in this project — be specific] | [Low/Medium/High — describe breaking change risk] |
+| [Package name] | [version]                      | [location]                  | [purpose]                                    | [risk]                                            |
+| [Package name] | [version]                      | [location]                  | [purpose]                                    | [risk]                                            |
+
+### Development Dependencies (Tooling)
+
+| Package                     | Version   | Purpose                                                       |
+| --------------------------- | --------- | ------------------------------------------------------------- |
+| [Dev dep, e.g., typescript] | [version] | [Compiler/transpiler — describe configuration approach]       |
+| [Dev dep, e.g., eslint]     | [version] | [Linter — describe config format: flat config, extends, etc.] |
+| [Dev dep, e.g., prettier]   | [version] | [Formatter — describe key settings that differ from defaults] |
+
+---
+
+## 🚀 Development Commands
+
+```bash
+# Setup
+[package-manager] install              # Install all workspace dependencies
+
+# Development
+[package-manager] dev                  # Start all apps in development mode (parallel)
+[package-manager] dev --filter=[app]   # Start a specific app only
+
+# Quality
+[package-manager] build                # Build all packages and apps for production
+[package-manager] lint                 # Run linter across all workspaces
+[package-manager] typecheck            # TypeScript type checking (no emit)
+[package-manager] format               # Run code formatter
+[package-manager] test                 # Run test suite [describe framework: vitest, jest, etc.]
+
+# Database (if applicable)
+[package-manager] db:migrate           # Run pending database migrations
+[package-manager] db:seed              # Seed database with development data
+[package-manager] db:studio            # Open database GUI tool
+```
+
+---
+
+## ⚠️ Known Limitations & Future Upgrades
+
+| Current Limitation                                                                         | Impact                                                          | Planned Upgrade                                                       | When                                                      |
+| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------- |
+| [Limitation — describe what doesn't work or isn't ideal, e.g., "No server-side rendering"] | [Impact on users/DX — e.g., "Slower initial page load, no SEO"] | [Planned solution — e.g., "Migrate to Next.js or add SSR middleware"] | [Trigger condition — e.g., "When SEO becomes a priority"] |
+| [Limitation]                                                                               | [Impact]                                                        | [Planned upgrade]                                                     | [When to upgrade]                                         |
+
+---
+
+## 📝 Notes
+
+- [Version pinning strategy — describe whether you pin exact versions or use ranges and why]
+- [Browser support targets — describe minimum browser versions if applicable]
+- [Node.js version management — describe .nvmrc, volta, or other version management]
+- [Environment variables — reference .env.example and describe required vs optional vars]
+
+---
+
+## 🔗 Related Documents
+
+- **[[ARCHITECTURE_GUIDE|Architecture Guide]]** - Why these technologies work together
+- **[[DECISIONS|Decisions Log]]** - ADRs for each major technology choice
+- **[[DESIGN_SYSTEM|Design System]]** - Visual language built on this stack

package/payload/scripts/check-task.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * check-task — flip a task checkbox to done and recompute progress.
+ * Shipped into a Groundwork project at docs/.groundwork/scripts/.
+ * The /check-task skill calls this so checkbox math is deterministic.
+ *
+ * Usage:
+ *   node check-task.mjs <task-id|text> [path/to/PHASEN_TASKS.md]
+ *   node check-task.mjs 2.3
+ *   node check-task.mjs "implement auth middleware" docs/phases/phase2/PHASE2_TASKS.md
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+const [needle, explicitFile] = process.argv.slice(2);
+if (!needle) {
+  console.error("Usage: node check-task.mjs <task-id|text> [tasks-file]");
+  process.exit(1);
+}
+
+const file = explicitFile || findTasksFile();
+if (!file || !fs.existsSync(file)) {
+  console.error("✗ No phase tasks file found. Pass one explicitly.");
+  process.exit(1);
+}
+
+const lines = fs.readFileSync(file, "utf8").split("\n");
+const isId = /^\d+(\.\d+)*$/.test(needle);
+let hit = -1;
+
+for (let i = 0; i < lines.length; i++) {
+  if (!/^\s*-\s*\[ \]/.test(lines[i])) continue;
+  const text = lines[i].toLowerCase();
+  if (isId) {
+    // Match "2.3" as a token (start of task text or "N.M:")
+    if (new RegExp(`\\b${needle.replace(".", "\\.")}\\b`).test(lines[i])) {
+      hit = i;
+      break;
+    }
+  } else if (text.includes(needle.toLowerCase())) {
+    hit = i;
+    break;
+  }
+}
+
+if (hit === -1) {
+  console.error(`✗ No open task matching "${needle}" in ${file}`);
+  process.exit(1);
+}
+
+lines[hit] = lines[hit].replace(/\[ \]/, "[x]");
+const updated = recomputeProgress(lines.join("\n"));
+fs.writeFileSync(file, updated.text);
+
+console.log(`✓ Marked done: ${lines[hit].replace(/^\s*-\s*\[x\]\s*/, "").trim()}`);
+console.log(
+  `  Progress: ${updated.done}/${updated.total} (${updated.pct}%)  ${bar(updated.pct)}`
+);
+if (updated.done === updated.total)
+  console.log("  🎉 All tasks complete — consider updating the roadmap & QUEUE/DONE.");
+
+// ---------- helpers ----------
+function findTasksFile() {
+  const root = "docs/phases";
+  if (!fs.existsSync(root)) return null;
+  const found = [];
+  (function walk(d) {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (/PHASE.*TASKS\.md$/i.test(e.name)) found.push(p);
+    }
+  })(root);
+  // Prefer the file with the most open checkboxes (the active phase).
+  return found.sort((a, b) => openCount(b) - openCount(a))[0] || null;
+}
+function openCount(f) {
+  return (fs.readFileSync(f, "utf8").match(/^\s*-\s*\[ \]/gm) || []).length;
+}
+function recomputeProgress(text) {
+  let done = 0,
+    total = 0;
+  for (const l of text.split("\n")) {
+    if (/^\s*-\s*\[[xX]\]/.test(l)) (done++, total++);
+    else if (/^\s*-\s*\[ \]/.test(l)) total++;
+  }
+  const pct = total ? Math.round((done / total) * 100) : 0;
+  // Update an existing "Overall Progress" line if present.
+  text = text.replace(
+    /(\*\*Overall Progress\*\*:).*$/m,
+    `$1 ${done}/${total} tasks (${pct}%)`
+  );
+  return { text, done, total, pct };
+}
+function bar(pct, w = 20) {
+  const f = Math.round((pct / 100) * w);
+  return "█".repeat(f) + "░".repeat(Math.max(0, w - f));
+}

package/payload/scripts/check-versions.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * check-versions — compare the project's pinned dependencies against the latest
+ * stable on the npm registry, so docs/STACK_MAP.md never silently goes stale.
+ * Shipped into a Groundwork project at docs/.groundwork/scripts/.
+ *
+ * Usage:
+ *   node check-versions.mjs            # check the curated stack present in package.json(s)
+ *   node check-versions.mjs --all      # check every dependency
+ *   node check-versions.mjs react vite # check specific packages
+ *
+ * Exit code: 0 if all up to date, 1 if any are behind (useful in CI / bootstrap).
+ */
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+const args = process.argv.slice(2);
+const all = args.includes("--all");
+const explicit = args.filter((a) => !a.startsWith("--"));
+
+// Curated "this is the stack" list — only those actually present get checked.
+const CURATED = new Set([
+  "react", "react-dom", "vite", "@vitejs/plugin-react",
+  "hono", "@hono/node-server", "zod",
+  "tailwindcss", "typescript", "turbo", "vitest",
+  "eslint", "prettier",
+  "drizzle-orm", "drizzle-kit", "postgres", "mysql2", "better-sqlite3",
+  "zustand",
+]);
+
+const deps = collectDeps();
+const names = explicit.length
+  ? explicit
+  : Object.keys(deps).filter((n) => all || CURATED.has(n));
+
+if (names.length === 0) {
+  console.log("No matching dependencies found in package.json. Try --all.");
+  process.exit(0);
+}
+
+console.log("Checking latest stable versions on the npm registry…\n");
+const rows = [];
+let behind = 0;
+for (const name of names.sort()) {
+  const current = deps[name] || "(not installed)";
+  let latest = "?";
+  try {
+    latest = execFileSync("npm", ["view", name, "version"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    latest = "(lookup failed)";
+  }
+  const state = classify(current, latest);
+  if (state.behind) behind++;
+  rows.push({ name, current, latest, label: state.label });
+}
+
+const w = Math.max(...rows.map((r) => r.name.length), 7);
+console.log(`${"package".padEnd(w)}  ${"pinned".padEnd(12)} ${"latest".padEnd(12)} status`);
+console.log("─".repeat(w + 40));
+for (const r of rows) {
+  console.log(
+    `${r.name.padEnd(w)}  ${r.current.padEnd(12)} ${r.latest.padEnd(12)} ${r.label}`
+  );
+}
+
+console.log(
+  behind
+    ? `\n${behind} package(s) behind. Plan bumps as a dedicated workstream and update docs/STACK_MAP.md.`
+    : "\n✓ All checked packages are on the latest stable major."
+);
+process.exit(behind ? 1 : 0);
+
+// ---------- helpers ----------
+function collectDeps() {
+  const files = ["package.json"];
+  for (const dir of ["apps", "packages"]) {
+    if (fs.existsSync(dir)) {
+      for (const sub of fs.readdirSync(dir)) {
+        const p = path.join(dir, sub, "package.json");
+        if (fs.existsSync(p)) files.push(p);
+      }
+    }
+  }
+  const out = {};
+  for (const f of files) {
+    if (!fs.existsSync(f)) continue;
+    const pkg = JSON.parse(fs.readFileSync(f, "utf8"));
+    Object.assign(out, pkg.dependencies, pkg.devDependencies);
+  }
+  return out;
+}
+
+function major(v) {
+  const m = String(v).replace(/^[\^~>=<\s]+/, "").match(/^(\d+)/);
+  return m ? Number(m[1]) : null;
+}
+
+function classify(current, latest) {
+  const cM = major(current);
+  const lM = major(latest);
+  if (cM === null || lM === null) return { behind: false, label: "·" };
+  if (cM < lM) return { behind: true, label: `⬆ ${lM - cM} major behind` };
+  if (cM > lM) return { behind: false, label: "ahead?" };
+  // same major — compare full for a soft hint
+  const clean = (v) => String(v).replace(/^[\^~>=<\s]+/, "");
+  return clean(current) === latest
+    ? { behind: false, label: "✓ latest" }
+    : { behind: false, label: "✓ current major (minor/patch available)" };
+}

package/payload/scripts/phase-status.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * phase-status — deterministic phase progress report.
+ * Shipped into a Groundwork project at docs/.groundwork/scripts/.
+ * Run on demand (or via `groundwork status`) so percentages are computed, not guessed.
+ *
+ * Usage:
+ *   node phase-status.mjs            # all phases
+ *   node phase-status.mjs 2          # phase 2 only
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+const arg = process.argv[2];
+const root = "docs/phases";
+if (!fs.existsSync(root)) {
+  console.error("✗ docs/phases not found. Run /plan-phase first.");
+  process.exit(1);
+}
+
+const files = [];
+(function walk(d) {
+  for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+    const p = path.join(d, e.name);
+    if (e.isDirectory()) walk(p);
+    else if (/PHASE.*TASKS\.md$/i.test(e.name)) files.push(p);
+  }
+})(root);
+
+const filtered = arg
+  ? files.filter((f) => new RegExp(`phase0*${arg}\\b`, "i").test(f))
+  : files;
+
+if (filtered.length === 0) {
+  console.error(arg ? `✗ No tasks file for phase ${arg}.` : "✗ No PHASE*_TASKS.md files.");
+  process.exit(1);
+}
+
+let gDone = 0,
+  gTotal = 0;
+for (const f of filtered.sort()) {
+  const text = fs.readFileSync(f, "utf8");
+  const { done, total } = count(text);
+  gDone += done;
+  gTotal += total;
+  const pct = total ? Math.round((done / total) * 100) : 0;
+  const label = f.split(path.sep).slice(-2, -1)[0] || path.basename(f);
+  console.log(`${label}  ${bar(pct)} ${String(pct).padStart(3)}%  (${done}/${total})`);
+}
+
+if (filtered.length > 1) {
+  const pct = gTotal ? Math.round((gDone / gTotal) * 100) : 0;
+  console.log("─".repeat(40));
+  console.log(`TOTAL     ${bar(pct)} ${String(pct).padStart(3)}%  (${gDone}/${gTotal})`);
+}
+
+function count(text) {
+  let done = 0,
+    total = 0;
+  for (const l of text.split("\n")) {
+    if (/^\s*-\s*\[[xX]\]/.test(l)) (done++, total++);
+    else if (/^\s*-\s*\[ \]/.test(l)) total++;
+  }
+  return { done, total };
+}
+function bar(pct, w = 20) {
+  const f = Math.round((pct / 100) * w);
+  return "█".repeat(f) + "░".repeat(Math.max(0, w - f));
+}

package/payload/scripts/set-fact.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/*
+ * set-fact.mjs — deterministic upsert into docs/FACTS.md.
+ *
+ * Usage:
+ *   node docs/.groundwork/scripts/set-fact.mjs <fact-id> "<claim>" --by <agent> --method "<how>"
+ *
+ * Writes (or replaces, matched by id) one entry in the pinned FACTS grammar:
+ *   - `fact-id` — claim
+ *     verified: YYYY-MM-DDTHH:MMZ · by: agent · method: how
+ *
+ * Timestamp is stamped here (UTC, minute precision) so agents can't fabricate or forget it.
+ * Atomic write: temp file + rename. Exits non-zero on malformed input or missing FACTS.md.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+const args = process.argv.slice(2);
+const flags = {};
+const positional = [];
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "--by" || args[i] === "--method" || args[i] === "--file") {
+    flags[args[i].slice(2)] = args[++i];
+  } else positional.push(args[i]);
+}
+const [id, claim] = positional;
+
+const usage = () => {
+  console.error(
+    'usage: set-fact.mjs <fact-id> "<claim>" --by <agent> --method "<how>" [--file docs/FACTS.md]'
+  );
+  process.exit(1);
+};
+if (!id || !claim || !flags.by || !flags.method) usage();
+if (!/^[a-z0-9][a-z0-9-]*$/.test(id)) {
+  console.error(`fact id must be kebab-case (got \`${id}\`)`);
+  process.exit(1);
+}
+if (/\n/.test(claim) || /\n/.test(flags.method)) {
+  console.error("claim and method must be single-line");
+  process.exit(1);
+}
+
+const file = path.resolve(flags.file || "docs/FACTS.md");
+if (!fs.existsSync(file)) {
+  console.error(`${file} not found — run \`groundwork init\`/\`update --docs\` first`);
+  process.exit(1);
+}
+
+const ts = new Date().toISOString().slice(0, 16) + "Z"; // YYYY-MM-DDTHH:MMZ
+const entry = `- \`${id}\` — ${claim}\n  verified: ${ts} · by: ${flags.by} · method: ${flags.method}`;
+
+const text = fs.readFileSync(file, "utf8");
+const lines = text.split("\n");
+
+// Locate an existing entry with this id (entry line + its indented meta line, if any).
+const entryRe = new RegExp(`^- \`${id}\` — `);
+const start = lines.findIndex((l) => entryRe.test(l));
+let out;
+if (start >= 0) {
+  const hasMeta = /^ {2}verified:/.test(lines[start + 1] || "");
+  lines.splice(start, hasMeta ? 2 : 1, ...entry.split("\n"));
+  out = lines.join("\n");
+} else {
+  const facts = lines.findIndex((l) => /^## Facts\s*$/.test(l));
+  if (facts < 0) {
+    console.error("no `## Facts` section in FACTS.md — file is malformed");
+    process.exit(1);
+  }
+  // Append after the last existing content of the section (end of file or next heading).
+  let end = lines.length;
+  for (let i = facts + 1; i < lines.length; i++) {
+    if (/^## /.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  while (end > facts + 1 && lines[end - 1].trim() === "") end--;
+  lines.splice(end, 0, "", ...entry.split("\n"));
+  out = lines.join("\n");
+}
+
+const tmp = `${file}.${process.pid}.tmp`;
+fs.writeFileSync(tmp, out);
+fs.renameSync(tmp, file);
+console.log(`${start >= 0 ? "updated" : "added"} \`${id}\` (verified: ${ts})`);