doctrina-cli 0.15.1 → 0.17.0

package/src/lib/analysis.js

@@ -0,0 +1,264 @@
+// @ts-check
+import path from "node:path";
+import { exists, isDir, isFile, read, relPath, walk } from "./fs-ops.js";
+import { c } from "./colors.js";
+import { checklistProgress, isUntouchedScaffold } from "./doc-model.js";
+import { collectBudgets } from "./runtime.js";
+import { extractOps, applyOps } from "./spec-ops.js";
+
+// The structural ANALYSIS of a change folder, as data.
+//
+// `lib/gates.js` enforces these findings on every lifecycle transition, so
+// the library depended on a command module to compute them — a lib->command
+// edge that made the dependency graph a cycle waiting to happen (audit
+// finding F7). The findings are what the gate map is built on; they belong
+// here, and `commands/analyze.js` is the renderer that prints them.
+
+// 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 = checklistProgress(text).placeholders;
+    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}`));
+          // THE OPS, EXECUTED (third audit, finding 2). Until now this said
+          // "ready to apply" for a delta whose ops block `apply` then refused:
+          // the pre-flight inspected everything about the delta except the one
+          // part that does the work. `change check` already ran this dry-run,
+          // so the answer existed — the gate `close` and `apply` consult was
+          // simply not the one asking.
+          //
+          // Scoped pre-apply: after a successful apply the target holds what
+          // these ops just wrote, and re-running them against it is a question
+          // with no meaning. `archive`'s integrity gate excludes this scope for
+          // exactly that reason.
+          for (const line of opsFindings(read(targetSpec), text, rel)) results.push(line);
+        }
+      } 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, "\\$&");
+}
+
+/**
+ * Run a MODIFIED delta's ops block against its target spec IN MEMORY and
+ * report what `apply` would report.
+ *
+ * The whole finding behind this: `apply` executes these ops all-or-none and
+ * refuses on the first error, so an unappliable block is knowable before
+ * anything is touched — and the pre-flight was not looking. A delta with no
+ * ops block is not a failure: `apply` prints a manual-merge pointer for it,
+ * and saying so here is what lets a close be planned around it rather than
+ * surprised by it.
+ *
+ * @returns {Array<{kind: string, line: string, scope?: string}>}
+ */
+function opsFindings(specText, deltaText, rel) {
+  const ops = extractOps(deltaText);
+  if (ops.length === 0) {
+    return [info(`  ${rel}: no ops block — apply will print a manual-merge pointer`)];
+  }
+  const result = applyOps(specText, ops);
+  if (result.errors.length === 0) {
+    const n = result.applied.length;
+    return [pass(`  ${rel}: ${n} op${n === 1 ? "" : "s"} would apply cleanly`)];
+  }
+  return [
+    fail(`  ${rel}: ${result.errors.length} op error${result.errors.length === 1 ? "" : "s"} ` +
+      `(apply would refuse): ${result.errors.join("; ")}`, "pre-apply"),
+  ];
+}
+
+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 };
+}

package/src/lib/args.js

@@ -74,9 +74,23 @@ export function parseArgs(argv, opts = {}) {
 function isNextTokenFlag(token) {
   if (token === undefined) return true;
   if (typeof token !== "string") return true;
+  // `--budget -5` is a value, not a flag named "5": no flag name starts with
+  // a digit, and reading it as one answered "unknown flag --5, did you mean
+  // --h?" instead of letting the command say the number is out of range.
+  if (/^-\d/.test(token)) return false;
   return token.startsWith("-");
 }
 
+// A count read off a flag: digits only, above zero, or null. `parseInt`
+// reads "7x" as 7 and "1.5" as 1, so a typo became a different request that
+// ran without a word.
+export function parsePositiveInt(raw) {
+  const s = String(raw ?? "").trim();
+  if (!/^\d+$/.test(s)) return null;
+  const n = Number(s);
+  return Number.isSafeInteger(n) && n > 0 ? n : null;
+}
+
 export function flagString(flags, name, fallback = undefined) {
   const v = flags.get(name);
   if (v === undefined || v === true) return fallback;

package/src/lib/change-ops.js

@@ -0,0 +1,133 @@
+// @ts-check
+// Scaffolding a change folder.
+//
+// `work` opens a change as its first act and called into `commands/change.js`
+// to do it (audit finding F7). Creating the folder is an OPERATION over the
+// tree, not a rendering of the `change` command, so both entry points perform
+// it from here.
+import path from "node:path";
+import process from "node:process";
+import { exists, isDir, isFile, lineCount, mkdirp, move, read, relPath, remove, walk, write } from "./fs-ops.js";
+import { locateTemplatesDir, loadTemplateTree, materialiseEntry } from "./templates.js";
+import * as idx from "./index-json.js";
+import { today } from "./dates.js";
+import { flagBool, flagString } from "./args.js";
+import { c } from "./colors.js";
+import { ensureDoctrinaProject, isChangeId, resolveWithinProject } from "./project.js";
+import { changeEntry } from "./scan.js";
+export function changeNew(args, flags) {
+  const id = args[0];
+  const title = args.slice(1).join(" ").trim();
+  if (!id) {
+    console.error(c.red("error:") + " change new requires <id> and \"<title>\"");
+    return 2;
+  }
+  if (!title) {
+    console.error(c.red("error:") + " change new requires a title (quote it if it contains spaces)");
+    return 2;
+  }
+  // The id names a DIRECTORY, so it obeys the same grammar every other
+  // authoring command enforces on its argument (third audit, finding 1).
+  // Without this `change new ../../../elsewhere/evil` scaffolded outside the
+  // project, and `0003-com espaco` was accepted here and then carried by
+  // `validate`, `index rebuild` and `next` as a legitimate id.
+  if (!isChangeId(id)) {
+    console.error(c.red("error:") + ` invalid change id "${id}" (lowercase letters, digits, hyphens)`);
+    console.error(c.gray("hint: ") + "ids look like `0042-short-slug`; `doctrina work \"<prompt>\"` derives one for you");
+    return 2;
+  }
+
+  const force = flagBool(flags, "force", false);
+  // A chore is a spec-less change (infra / docs / build / migration) — review
+  // G9. It runs the full proposal → apply → archive → ledger lifecycle (so the
+  // history shows it) without forcing a fake spec delta. The empty specs/ dir
+  // is kept so `change apply`'s zero-delta path flips it to applied unchanged.
+  const chore = flagBool(flags, "chore", false) || flagBool(flags, "no-spec", false);
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+
+  // Belt and braces: the grammar above already refuses a traversing id, and
+  // this holds if a future caller reaches this line another way.
+  const changeDir = resolveWithinProject(projectRoot, ".doctrina", "changes", id);
+  if (exists(changeDir) && !force) {
+    console.error(c.red("error:") + ` change "${id}" already exists at ${relPath(projectRoot, changeDir)}`);
+    return 1;
+  }
+
+  const templatesDir = locateTemplatesDir();
+  const date = today();
+  const tokens = { CHANGE_ID: id, CHANGE_TITLE: title, DATE: date, CAPABILITY: "" };
+
+  // design.md is opt-in (--design): in practice it scaffolded on every change
+  // and stayed empty — nine changes out of nine in the 0.11.0 field review. A
+  // change that needs a design doc asks for one; the rest stop carrying a
+  // blank file through apply/archive/ledger.
+  const wantDesign = flagBool(flags, "design", false);
+  const tree = loadTemplateTree(templatesDir, "change");
+  for (const entry of tree) {
+    if (entry.relativePath === "spec-delta.md.template") continue;
+    if (entry.relativePath === "design.md.template" && !wantDesign) continue;
+    const written = materialiseEntry(entry, changeDir, tokens, { force });
+    console.log(c.green("created") + ` ${relPath(projectRoot, written)}`);
+  }
+  // No empty `specs/` here (change 0081). The directory used to be created
+  // unconditionally as somewhere "ready" for deltas, and when the CLI could
+  // not name a capability — a new prompt, a project whose specs do not match
+  // — nothing was ever written into it. An empty directory is not an absence:
+  // it says deltas live here, or lived here, and the next reader spends
+  // attention checking. The delta writer creates its own path when there is
+  // a delta to put in it.
+
+  // Stamp the proposal so a chore is honest in the artifact, not just the CLI.
+  if (chore) {
+    const proposalPath = path.join(changeDir, "proposal.md");
+    if (exists(proposalPath)) {
+      const txt = read(proposalPath);
+      const updated = txt.replace(/^(-\s+\*\*Affects specs:\*\*).*$/m, "$1 (none — chore)");
+      if (updated !== txt) write(proposalPath, updated, { force: true });
+    }
+  }
+
+  // Derive the entry from the proposal on disk rather than assembling one
+  // here: a field the deriver knows about and this writer does not is index
+  // drift the moment the change is opened (change 0076 — that is exactly what
+  // `lane` did). One constructor, in `scan.js`, for one record shape.
+  reindexChange(projectRoot, id, date);
+
+  console.log("");
+  if (chore) {
+    // A chore is still a change: it closes through the one definition of
+    // done, not a hand-run apply and archive (change 0180).
+    console.log(c.bold("Chore opened.") + " No spec deltas expected — implement, check the tasks, then " +
+      c.cyan(`doctrina close ${id}`) + ".");
+  } else {
+    console.log(c.bold("Change opened.") + " Add spec deltas under " +
+      c.cyan(`.doctrina/changes/${id}/specs/<capability>/delta.md`));
+  }
+  return 0;
+}
+
+/**
+ * Register — or re-derive — one open change's index entry from its proposal.
+ *
+ * `work` writes the proposal in two passes: `changeNew` scaffolds it, then the
+ * command stamps the lane it classified and the specs it pinned. Indexing at
+ * the end of the FIRST pass reads a proposal that is not finished yet, which
+ * is why every `doctrina work` used to be followed by a `validate` error and
+ * an `index rebuild` nobody asked for. Calling this again after the stamping
+ * costs one file write and makes the tree honest on the next command.
+ *
+ * @param {string} projectRoot
+ * @param {string} id    The change id (its directory name).
+ * @param {string} [date] Fallback for a proposal carrying no Date header.
+ */
+export function reindexChange(projectRoot, id, date = today()) {
+  const proposalPath = path.join(projectRoot, ".doctrina", "changes", id, "proposal.md");
+  const proposal = isFile(proposalPath) ? read(proposalPath) : "";
+  const index = idx.load(projectRoot);
+  const prev = index.artifacts.changes.find((ch) => ch.id === id) ?? null;
+  index.artifacts.changes = index.artifacts.changes.filter((ch) => ch.id !== id);
+  index.artifacts.changes.push(changeEntry(proposal, id, prev, date));
+  idx.touch(index, date);
+  idx.save(projectRoot, index);
+}