doctrina-cli 0.12.0 → 0.14.0

package/README.md

@@ -3,7 +3,7 @@
 > CLI for the Doctrina framework. The package is published as
 > `doctrina-cli`; the executable it installs is `doctrina`.
 
-**Status:** v0.11.0 — current release. Zero runtime dependencies
+**Status:** v0.14.0 — current release. Zero runtime dependencies
 (Node.js standard library only).
 
 ## Install

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doctrina-cli",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Doctrina CLI — spec-driven, AGENTS.md-native framework for multi-agent AI development.",
   "license": "MIT",
   "keywords": [
@@ -19,7 +19,8 @@
   },
   "scripts": {
     "test": "node --test",
-    "prepack": "node scripts/copy-templates.js"
+    "prepack": "node scripts/copy-templates.js",
+    "test:e2e": "node ../../scripts/e2e-packed.mjs"
   },
   "files": [
     "src",

package/src/commands/adapter.js

@@ -0,0 +1,205 @@
+// @ts-check
+import path from "node:path";
+import process from "node:process";
+import { exists, isFile, mkdirp, read, relPath, remove, write } from "../lib/fs-ops.js";
+import {
+  ADAPTER_STATES, adapterFiles, describeAdapter, listAdapterNames, renderAdapterFile,
+} from "../lib/adapters.js";
+import { flagBool } from "../lib/args.js";
+import { today } from "../lib/dates.js";
+import { c } from "../lib/colors.js";
+import { suggest } from "../lib/suggest.js";
+import { notADoctrinaProject } from "../lib/exit-codes.js";
+
+// `doctrina adapter` — add, remove, and inventory agent adapters (audit
+// item C1).
+//
+// Before this command the only way to add an adapter to an existing project
+// was `doctrina init --agent <name> --force`, because `init` refuses to run
+// twice. That path regenerated AGENTS.md and .doctrina/product.md from
+// blank templates, silently destroying every hand-authored rule and the
+// product definition. `adapter add` is strictly additive: it writes that
+// adapter's own files and never reads or writes AGENTS.md, product.md, or
+// any other project artifact.
+
+const SUBCOMMANDS = ["list", "add", "remove"];
+
+export const flags = { boolean: ["json", "force"], string: [] };
+
+export async function run(positional, cmdFlags) {
+  const sub = positional[0];
+  if (!SUBCOMMANDS.includes(sub)) {
+    console.error(c.red("error:") + ` unknown adapter subcommand "${sub ?? ""}"`);
+    const guess = suggest(sub, SUBCOMMANDS);
+    console.error(c.gray("hint: ") + (guess
+      ? `did you mean \`doctrina adapter ${guess}\`?`
+      : `available: ${SUBCOMMANDS.join(", ")}`));
+    return 2;
+  }
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+  if (sub === "list") return adapterList(projectRoot);
+  if (sub === "add") return adapterAdd(projectRoot, positional[1], cmdFlags);
+  return adapterRemove(projectRoot, positional[1], cmdFlags);
+}
+
+function adapterList(projectRoot) {
+  const names = listAdapterNames(projectRoot);
+  if (names.length === 0) {
+    console.log(c.gray("no adapters available (no templates/adapters directory found)"));
+    return 0;
+  }
+  const rows = names.map((n) => describeAdapter(projectRoot, n));
+  const label = {
+    [ADAPTER_STATES.INSTALLED]: c.green("installed"),
+    [ADAPTER_STATES.AVAILABLE]: c.gray("available"),
+    [ADAPTER_STATES.NATIVE]: c.cyan("native   "),
+  };
+
+  console.log(c.bold("Agent adapters:"));
+  console.log("");
+  for (const r of rows) {
+    const suffix = r.state === ADAPTER_STATES.NATIVE
+      ? c.gray("reads AGENTS.md directly — no file needed")
+      : c.gray(`${r.installed.length}/${r.files.length} file${r.files.length === 1 ? "" : "s"}` +
+        (r.source === "project" ? " · project template" : ""));
+    console.log(`  ${label[r.state]}  ${c.cyan(r.name.padEnd(10))}  ${suffix}`);
+  }
+  console.log("");
+  const installed = rows.filter((r) => r.state === ADAPTER_STATES.INSTALLED).length;
+  const native = rows.filter((r) => r.state === ADAPTER_STATES.NATIVE).length;
+  console.log(c.gray(
+    `${installed} installed · ${rows.length - installed - native} available · ${native} native. ` +
+    "Add one: ") + c.cyan("doctrina adapter add <name>"));
+  return 0;
+}
+
+function adapterAdd(projectRoot, name, cmdFlags) {
+  if (!name) {
+    console.error(c.red("error:") + " adapter add requires a name (see `doctrina adapter list`)");
+    return 2;
+  }
+  const spec = adapterFiles(projectRoot, name);
+  if (!spec) {
+    console.error(c.red("error:") + ` unknown adapter "${name}"`);
+    const guess = suggest(name, listAdapterNames(projectRoot));
+    console.error(c.gray("hint: ") + (guess
+      ? `did you mean \`doctrina adapter add ${guess}\`?`
+      : "run `doctrina adapter list` for the available adapters"));
+    return 2;
+  }
+  if (spec.files.length === 0) {
+    console.log(c.cyan("native  ") + ` ${name} reads AGENTS.md directly — nothing to install`);
+    console.log(c.gray("Its rules already reach the agent through the hub at AGENTS.md."));
+    return 0;
+  }
+
+  const force = flagBool(cmdFlags, "force", false);
+  const tokens = {
+    PROJECT_NAME: path.basename(projectRoot),
+    PROJECT_DESCRIPTION: "",
+    DATE: today(),
+  };
+
+  // Additive by construction: only this adapter's own files are touched,
+  // and an existing one is left alone unless --force is given. AGENTS.md
+  // and product.md are never read or written here.
+  let written = 0;
+  let skipped = 0;
+  for (const file of spec.files) {
+    const dest = path.join(projectRoot, file.relativePath);
+    if (exists(dest) && !force) {
+      console.log(c.yellow("skip   ") + ` ${file.relativePath} (already present; --force overwrites)`);
+      skipped += 1;
+      continue;
+    }
+    mkdirp(path.dirname(dest));
+    write(dest, renderAdapterFile(file, tokens), { force: true });
+    console.log(c.green("created") + ` ${relPath(projectRoot, dest)}`);
+    written += 1;
+  }
+
+  console.log("");
+  console.log(`${c.bold("Adapter " + name)} — ${written} file${written === 1 ? "" : "s"} written` +
+    (skipped > 0 ? `, ${skipped} left alone` : "") +
+    (spec.source === "project" ? c.gray(" (from .doctrina/templates/adapters/)") : ""));
+  console.log(c.gray("Additive only: AGENTS.md and .doctrina/product.md were not touched."));
+  return 0;
+}
+
+function adapterRemove(projectRoot, name, cmdFlags) {
+  if (!name) {
+    console.error(c.red("error:") + " adapter remove requires a name (see `doctrina adapter list`)");
+    return 2;
+  }
+  const spec = adapterFiles(projectRoot, name);
+  if (!spec) {
+    console.error(c.red("error:") + ` unknown adapter "${name}"`);
+    return 2;
+  }
+  if (spec.files.length === 0) {
+    console.log(c.cyan("native  ") + ` ${name} installs no files — nothing to remove`);
+    return 0;
+  }
+
+  // Only delete files this adapter created AND that still match what it
+  // would write. A file the user edited is theirs now; --force overrides.
+  const force = flagBool(cmdFlags, "force", false);
+  const tokens = { PROJECT_NAME: path.basename(projectRoot), PROJECT_DESCRIPTION: "", DATE: today() };
+  let removed = 0;
+  let kept = 0;
+  for (const file of spec.files) {
+    const dest = path.join(projectRoot, file.relativePath);
+    if (!isFile(dest)) continue;
+    const pristine = normalise(read(dest)) === normalise(renderAdapterFile(file, tokens));
+    if (!pristine && !force) {
+      console.log(c.yellow("kept   ") + ` ${file.relativePath} (edited since install; --force removes it)`);
+      kept += 1;
+      continue;
+    }
+    remove(dest);
+    console.log(c.green("removed") + ` ${file.relativePath}`);
+    removed += 1;
+  }
+  console.log("");
+  console.log(`${c.bold("Adapter " + name)} — ${removed} file${removed === 1 ? "" : "s"} removed` +
+    (kept > 0 ? `, ${kept} kept (edited)` : ""));
+  return 0;
+}
+
+function normalise(text) {
+  return text.replace(/\r\n/g, "\n").trim();
+}
+
+function ensureDoctrinaProject(projectRoot) {
+  if (!exists(path.join(projectRoot, ".doctrina"))) {
+    throw notADoctrinaProject();
+  }
+}
+
+export const help = `
+Usage: doctrina adapter <list|add|remove> [name] [--force]
+
+Add, remove, and inventory the per-agent adapter files that point at
+AGENTS.md. Adding an adapter is strictly additive: only that adapter's own
+files are written, and AGENTS.md / .doctrina/product.md are never touched.
+
+Subcommands:
+  list             Every adapter with its state:
+                     installed — its files are present
+                     available — it ships files and none are installed
+                     native    — the agent reads AGENTS.md directly and
+                                 needs no file at all
+  add <name>       Install one adapter's files. An existing file is left
+                   alone unless --force is given.
+  remove <name>    Delete the files this adapter created. A file edited
+                   since install is kept unless --force is given.
+
+Custom adapters: a directory at .doctrina/templates/adapters/<name>/ is
+installable by name and takes precedence over a bundled adapter of the
+same name.
+
+Options:
+  --force          With add, overwrite an existing file; with remove,
+                   delete a file that was edited after install.
+`;

package/src/commands/analyze.js

@@ -1,9 +1,15 @@
+// @ts-check
 import path from "node:path";
 import process from "node:process";
 import { exists, isDir, isFile, read, relPath, walk } from "../lib/fs-ops.js";
 import { c } from "../lib/colors.js";
 import { isUntouchedScaffold } from "./change.js";
 
+// Flags this command accepts. Declared HERE, with the command, so
+// adding a command never requires editing the entrypoint — the gap that
+// let six flags ship undeclared and silently swallow a positional (C3).
+export const flags = { boolean: ["json"], string: [] };
+
 export async function run(positional, _flags) {
   const id = positional[0];
   if (!id) {
@@ -21,6 +27,25 @@ export async function run(positional, _flags) {
   console.log(`analyzing ${relPath(projectRoot, changeDir)}/`);
   console.log("");
 
+  const results = collectAnalysis(projectRoot, changeDir);
+  for (const r of results) console.log(r.line);
+  console.log("");
+
+  const failed = results.filter((r) => r.kind === "fail").length;
+  if (failed === 0) {
+    console.log(c.green("ok") + ` ready to apply`);
+  } else {
+    console.log(c.red("fail") + ` ${failed} issue${failed === 1 ? "" : "s"}`);
+  }
+  return failed === 0 ? 0 : 1;
+}
+
+// The structural findings for a change, as data. Exported so the shared
+// gate map (`lib/gates.js`) can enforce the SAME checks on every
+// transition that needs them, instead of each command deciding for itself
+// — `change apply` used to mutate a change that `analyze` had just
+// refused (audit item C6).
+export function collectAnalysis(projectRoot, changeDir) {
   const results = [];
 
   // proposal.md
@@ -32,6 +57,37 @@ export async function run(positional, _flags) {
     const text = read(proposalPath);
     if (/^##\s+Why\b/m.test(text)) results.push(pass(`proposal.md has a "## Why" section`));
     else results.push(fail(`proposal.md missing "## Why" section`));
+
+    // A section that still holds only its scaffold comment was never
+    // written. The check above only proved the HEADING survived, which is
+    // why six changes closed in one session with every rationale section
+    // empty: the planning step wrote to the file with a pattern that did
+    // not match its line endings, and nothing downstream looked inside.
+    // For a framework whose whole premise is recoverable provenance, an
+    // archived change that cannot say why it happened is the defect.
+    // Only `Why` and `What` are required. They are what makes a change
+    // recoverable a year later — the reason it exists and the shape it
+    // took. `Scope boundaries` and `Open questions` are legitimately empty
+    // on a change that has neither, and demanding the word "None." there
+    // is friction that buys nothing.
+    const hollow = [];
+    for (const m of text.matchAll(/^##\s+(.+?)[ \t]*\r?$/gm)) {
+      const heading = m[1].trim();
+      if (!/^(Why|What)$/i.test(heading)) continue;
+      const start = m.index + m[0].length;
+      const next = text.slice(start).search(/^##\s+/m);
+      const body = (next < 0 ? text.slice(start) : text.slice(start, start + next));
+      // Strip comments; anything left that is not whitespace is real prose.
+      if (body.replace(/<!--[\s\S]*?-->/g, "").trim() === "") hollow.push(heading);
+    }
+    if (hollow.length > 0) {
+      results.push(fail(
+        `proposal.md has ${hollow.length} unwritten section${hollow.length === 1 ? "" : "s"} ` +
+        `(${hollow.join(", ")}) — a heading that survived is not a section that was written`,
+      ));
+    } else {
+      results.push(pass("proposal.md states why and what"));
+    }
   }
 
   // tasks.md
@@ -41,6 +97,16 @@ export async function run(positional, _flags) {
   } else {
     results.push(pass("tasks.md present"));
     const text = read(tasksPath);
+    // Scaffold placeholders never replaced ("- [ ]" with no text, checked or
+    // not) mean the change was OPENED but never PLANNED — the agent went
+    // straight to implementing on a hollow change and nothing barked
+    // (operator report 2026-07-19). A hard failure here blocks `change
+    // check` and `close` until the plan is real; ticking an empty box does
+    // not help, `change tick` refuses those too.
+    const placeholders = (text.match(/^\s*-\s*\[[ xX]\]\s*$/gm) ?? []).length;
+    if (placeholders > 0) {
+      results.push(fail(`tasks.md still carries ${placeholders} scaffold placeholder task${placeholders === 1 ? "" : "s"} ("- [ ]" with no text) — plan the change before implementing: replace them with real tasks (or delete the lines)`));
+    }
     if (/^\s*-\s*\[\s\]/m.test(text)) results.push(pass("tasks.md has at least one unchecked task"));
     else results.push(info("tasks.md has no unchecked tasks (already done?)"));
   }
@@ -65,11 +131,11 @@ export async function run(positional, _flags) {
       const cap = capMatch ? capMatch[1] : path.basename(path.dirname(deltaPath));
 
       if (!op) {
-        results.push(fail(`  ${rel}: Operation header missing or malformed`, "  "));
+        results.push(fail(`  ${rel}: Operation header missing or malformed`));
         continue;
       }
       if (!["ADDED", "MODIFIED", "REMOVED"].includes(op)) {
-        results.push(fail(`  ${rel}: Operation "${op}" is not one of ADDED|MODIFIED|REMOVED`, "  "));
+        results.push(fail(`  ${rel}: Operation "${op}" is not one of ADDED|MODIFIED|REMOVED`));
         continue;
       }
       const targetSpec = path.join(projectRoot, ".doctrina", "specs", cap, "spec.md");
@@ -79,38 +145,29 @@ export async function run(positional, _flags) {
         // untouched `spec new` scaffold is the canonical flow (spec new →
         // ADDED delta), so it passes as a replacement; only real content fails.
         if (exists(targetSpec) && !isUntouchedScaffold(read(targetSpec), cap)) {
-          results.push(fail(`  ${cap} (ADDED) but target ${targetRel} has real content — use MODIFIED or remove it first`, "  "));
+          results.push(fail(`  ${cap} (ADDED) but target ${targetRel} has real content — use MODIFIED or remove it first`));
         } else if (exists(targetSpec)) {
-          results.push(pass(`  ${cap} (ADDED) → ${targetRel} (replaces the untouched scaffold)`, "  "));
+          results.push(pass(`  ${cap} (ADDED) → ${targetRel} (replaces the untouched scaffold)`));
         } else {
-          results.push(pass(`  ${cap} (ADDED) → ${targetRel} (new)`, "  "));
+          results.push(pass(`  ${cap} (ADDED) → ${targetRel} (new)`));
         }
       } else if (op === "MODIFIED") {
         if (!exists(targetSpec)) {
-          results.push(fail(`  ${cap} (MODIFIED) but target ${targetRel} does not exist`, "  "));
+          results.push(fail(`  ${cap} (MODIFIED) but target ${targetRel} does not exist`));
         } else {
-          results.push(pass(`  ${cap} (MODIFIED) → ${targetRel}`, "  "));
+          results.push(pass(`  ${cap} (MODIFIED) → ${targetRel}`));
         }
       } else {
         if (!exists(targetSpec)) {
-          results.push(fail(`  ${cap} (REMOVED) but target ${targetRel} does not exist`, "  "));
+          results.push(fail(`  ${cap} (REMOVED) but target ${targetRel} does not exist`));
         } else {
-          results.push(pass(`  ${cap} (REMOVED) → ${targetRel}`, "  "));
+          results.push(pass(`  ${cap} (REMOVED) → ${targetRel}`));
         }
       }
     }
   }
 
-  for (const r of results) console.log(r.line);
-  console.log("");
-
-  const failed = results.filter((r) => r.kind === "fail").length;
-  if (failed === 0) {
-    console.log(c.green("ok") + ` ready to apply`);
-  } else {
-    console.log(c.red("fail") + ` ${failed} issue${failed === 1 ? "" : "s"}`);
-  }
-  return failed === 0 ? 0 : 1;
+  return results;
 }
 
 function pass(msg) {