doctrina-cli 0.15.1 → 0.16.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.15.1 — current release. Zero runtime dependencies
+**Status:** v0.16.0 — current release. Zero runtime dependencies
 (Node.js standard library only).
 
 ## Install

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doctrina-cli",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "description": "Doctrina CLI — spec-driven, AGENTS.md-native framework for multi-agent AI development.",
   "license": "MIT",
   "keywords": [

package/src/commands/adapter.js

@@ -1,7 +1,7 @@
 // @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 { exists, isFile, mkdirp, pruneEmptyDirs, read, relPath, remove, write } from "../lib/fs-ops.js";
 import {
   ADAPTER_STATES, adapterFiles, describeAdapter, listAdapterNames, renderAdapterFile,
 } from "../lib/adapters.js";
@@ -148,6 +148,10 @@ function adapterRemove(projectRoot, name, cmdFlags) {
   const tokens = { PROJECT_NAME: path.basename(projectRoot), PROJECT_DESCRIPTION: "", DATE: today() };
   let removed = 0;
   let kept = 0;
+  // Directories a removed file lived in, innermost first. Only these are
+  // considered for pruning: a directory the adapter never wrote into is not
+  // this command's to tidy.
+  const vacated = new Set();
   for (const file of spec.files) {
     const dest = path.join(projectRoot, file.relativePath);
     if (!isFile(dest)) continue;
@@ -160,9 +164,28 @@ function adapterRemove(projectRoot, name, cmdFlags) {
     remove(dest);
     console.log(c.green("removed") + ` ${file.relativePath}`);
     removed += 1;
+    vacated.add(path.dirname(dest));
   }
+
+  // `add` calls mkdirp on the way in, so `remove` unmakes what it made on
+  // the way out. Without this the six files went and `.claude/` plus
+  // `.claude/commands/` stayed — and an empty `.claude/` is not neutral: it
+  // is a configuration root the next agent finds and treats as present.
+  // Only EMPTY directories are pruned, walking up and stopping at the first
+  // one that still holds anything, so a kept (edited) file or anything of
+  // the user's keeps its whole directory chain alive.
+  const pruned = [];
+  for (const dir of [...vacated].sort((a, b) => b.length - a.length)) {
+    for (const gone of pruneEmptyDirs(dir, projectRoot)) {
+      pruned.push(relPath(projectRoot, gone).replaceAll("\\", "/"));
+      console.log(c.green("removed") + ` ${relPath(projectRoot, gone).replaceAll("\\", "/")}/ ` +
+        c.gray("(empty)"));
+    }
+  }
+
   console.log("");
   console.log(`${c.bold("Adapter " + name)} — ${removed} file${removed === 1 ? "" : "s"} removed` +
+    (pruned.length > 0 ? `, ${pruned.length} empty director${pruned.length === 1 ? "y" : "ies"} pruned` : "") +
     (kept > 0 ? `, ${kept} kept (edited)` : ""));
   return 0;
 }

package/src/commands/analyze.js

@@ -1,10 +1,14 @@
 // @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 { isDir, relPath } from "../lib/fs-ops.js";
 import { c } from "../lib/colors.js";
-import { isUntouchedScaffold } from "./change.js";
-import { collectBudgets } from "../lib/runtime.js";
+import { collectAnalysis } from "../lib/analysis.js";
+import { EXIT } from "../lib/exit-codes.js";
+
+// The findings themselves live in lib/analysis.js, where the gate map reads
+// them; this command is their renderer (audit finding F7).
+export { collectAnalysis } from "../lib/analysis.js";
 
 // Flags this command accepts. Declared HERE, with the command, so
 // adding a command never requires editing the entrypoint — the gap that
@@ -22,7 +26,7 @@ export async function run(positional, _flags) {
   const changeDir = path.join(projectRoot, ".doctrina", "changes", id);
   if (!isDir(changeDir)) {
     console.error(c.red("error:") + ` change "${id}" not found at ${relPath(projectRoot, changeDir)}`);
-    return 1;
+    return EXIT.USAGE;
   }
 
   console.log(`analyzing ${relPath(projectRoot, changeDir)}/`);
@@ -41,214 +45,6 @@ export async function run(positional, _flags) {
   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
-  const proposalPath = path.join(changeDir, "proposal.md");
-  if (!isFile(proposalPath)) {
-    results.push(fail("proposal.md missing"));
-  } else {
-    results.push(pass("proposal.md present"));
-    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
-  const tasksPath = path.join(changeDir, "tasks.md");
-  if (!isFile(tasksPath)) {
-    results.push(fail("tasks.md missing"));
-  } 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?)"));
-  }
-
-  // design.md (optional)
-  const designPath = path.join(changeDir, "design.md");
-  if (isFile(designPath)) results.push(info("design.md present"));
-  else results.push(info("design.md absent (optional)"));
-
-  // Spec deltas
-  const deltaFiles = walk(path.join(changeDir, "specs")).filter((p) => p.endsWith("delta.md"));
-  if (deltaFiles.length === 0) {
-    results.push(info("0 spec deltas (metadata-only change)"));
-  } else {
-    results.push(pass(`${deltaFiles.length} spec delta${deltaFiles.length === 1 ? "" : "s"}:`));
-    for (const deltaPath of deltaFiles) {
-      const rel = relPath(projectRoot, deltaPath);
-      const text = read(deltaPath);
-      const opMatch = text.match(/^\*\*Operation:\*\*\s*([A-Z]+)/m);
-      const op = opMatch ? opMatch[1] : null;
-      const capMatch = text.match(/^#\s+Spec Delta\s*[—-]\s*capability:\s*([a-z][a-z0-9-]*)/m);
-      const cap = capMatch ? capMatch[1] : path.basename(path.dirname(deltaPath));
-
-      if (!op) {
-        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`));
-        continue;
-      }
-      const targetSpec = path.join(projectRoot, ".doctrina", "specs", cap, "spec.md");
-      const targetRel = relPath(projectRoot, targetSpec);
-      if (op === "ADDED") {
-        // Mirrors `change apply`: an existing target that is still the
-        // 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`, "pre-apply"));
-        } else if (exists(targetSpec)) {
-          results.push(pass(`  ${cap} (ADDED) → ${targetRel} (replaces the untouched scaffold)`));
-        } else {
-          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`, "pre-apply"));
-        } else {
-          results.push(pass(`  ${cap} (MODIFIED) → ${targetRel}`));
-        }
-      } else {
-        if (!exists(targetSpec)) {
-          results.push(fail(`  ${cap} (REMOVED) but target ${targetRel} does not exist`, "pre-apply"));
-        } else {
-          results.push(pass(`  ${cap} (REMOVED) → ${targetRel}`));
-        }
-      }
-    }
-  }
-
-  // BUDGET DISCIPLINE (change 0029). A declared ceiling is a contract, not
-  // a preference — and the tempting fix for "the output blew the limit" is
-  // to raise the limit. That buys headroom by truncating what mattered
-  // instead of sending less, and it is the discussion that comes back every
-  // quarter because nothing ever recorded that it had been settled. Raising
-  // an INPUT ceiling is a normal trade-off; raising an OUTPUT ceiling to
-  // resolve an overflow is the move this refuses.
-  for (const r of checkBudgetRaises(projectRoot, changeDir)) results.push(r);
-
-  return results;
-}
-
-// Compare the ceilings a change's proposal/deltas propose against the ones
-// the contracts declare today. Text-scanned: a change states a new value in
-// prose long before any code moves, which is exactly when it should be
-// argued about.
-function checkBudgetRaises(projectRoot, changeDir) {
-  const results = [];
-  let declared;
-  try {
-    declared = collectBudgets(projectRoot);
-  } catch {
-    return results;
-  }
-  if (declared.size === 0) return results;
-
-  const texts = [];
-  for (const f of walk(changeDir)) {
-    if (f.endsWith(".md")) texts.push({ rel: relPath(projectRoot, f), text: read(f) });
-  }
-
-  for (const [name, budget] of declared) {
-    if (budget.direction !== "output") continue;
-    for (const { rel, text } of texts) {
-      // "<limit> ... <number>" on one line: the shape a proposal uses when
-      // it restates a ceiling ("raise ai-summary to 2000").
-      const re = new RegExp(`${escapeRe(name)}[^\\n]{0,60}?(\\d{2,})`, "gi");
-      for (const m of text.matchAll(re)) {
-        const proposed = Number.parseInt(m[1], 10);
-        if (!Number.isFinite(proposed) || proposed <= budget.value) continue;
-        results.push(fail(
-          `${rel} raises the OUTPUT ceiling "${name}" from ${budget.value} to ${proposed} ` +
-          `(declared in ${budget.contract}) — raising an output budget buys headroom by ` +
-          `truncating what mattered. Send less, or supersede the budget deliberately in the contract`,
-        ));
-        break;
-      }
-    }
-  }
-  return results;
-}
-
-// A limit name comes from a contract table cell, so it is user text and
-// must not be spliced into a pattern unescaped.
-function escapeRe(s) {
-  return String(s).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-function pass(msg) {
-  return { kind: "pass", line: c.green("✓ ") + msg };
-}
-// `scope` says WHEN a failure is a real answer.
-//
-// Most of these questions are true at every point in a change's life: a
-// proposal with an unwritten `## What` is hollow before an apply and just as
-// hollow after one. A few are only meaningful BEFORE the apply — "an ADDED
-// delta's target must not already hold real content" is proof of a problem
-// beforehand and proof the apply WORKED afterwards.
-//
-// The gate map used to exclude the whole structure gate from `archive` to
-// dodge that handful, which also dropped the hollow-proposal check — the
-// exact defect this repository's own history records as having "shipped six
-// hollow proposals past every gate". Tagging the pre-apply ones lets
-// `archive` keep the rest.
-function fail(msg, scope = "always") {
-  return { kind: "fail", scope, line: c.red("✗ ") + msg };
-}
-function info(msg) {
-  return { kind: "info", line: c.gray("- ") + msg };
-}
-
 export const help = `
 Usage: doctrina analyze <change-id>