doctrina-cli 0.12.0 → 0.14.0

package/src/commands/close.js

@@ -1,15 +1,21 @@
+// @ts-check
 import path from "node:path";
 import process from "node:process";
+import { appendFileSync } from "node:fs";
 import { exists, isFile, read, walk } from "../lib/fs-ops.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { parseCapabilityFromDelta } from "./change.js";
+import { printAdrCheckpoint } from "../lib/adr-guard.js";
+import { checkDocsImpact } from "../lib/docs-impact.js";
+import { notADoctrinaProject } from "../lib/exit-codes.js";
 import * as analyze from "./analyze.js";
 import * as change from "./change.js";
 import * as verify from "./verify.js";
 import * as coverage from "./coverage.js";
 import * as trace from "./trace.js";
 import * as validate from "./validate.js";
+import * as skill from "./skill.js";
 
 // One-command close (review 2026-06-27 passive-user feature #2). The work
 // playbook lists the closing sequence — analyze → apply → verify → coverage →
@@ -19,19 +25,48 @@ import * as validate from "./validate.js";
 // rerun, so the agent makes one call and the human approves once. It is a
 // driver over the existing commands; it adds no new checks of its own.
 
+// 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", "force"], string: [] };
+
 export async function run(positional, flags) {
-  const id = positional[0];
-  if (!id) {
+  if (positional.length === 0) {
     console.error(c.red("error:") + " close requires a change <id> (e.g. doctrina close 0001-add-login)");
     return 2;
   }
   const projectRoot = process.cwd();
   if (!exists(path.join(projectRoot, ".doctrina"))) {
-    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+    throw notADoctrinaProject();
   }
 
+  // Batch close (operator review 2026-07-19 §4.5): each id closes
+  // independently, worst exit code wins, so a 9-change implementation lot is
+  // one command, not nine.
+  let worst = 0;
+  for (const id of positional) {
+    if (positional.length > 1) {
+      console.log("");
+      console.log(c.bold(`════ close ${id}`));
+    }
+    worst = Math.max(worst, await closeOne(projectRoot, id, flags));
+  }
+  if (positional.length > 1) {
+    console.log("");
+    console.log(worst === 0
+      ? c.green("ok") + ` all ${positional.length} changes closed`
+      : c.red("fail") + " at least one close stopped — see above");
+  }
+  return worst;
+}
+
+async function closeOne(projectRoot, id, flags) {
   const force = flagBool(flags, "force", false);
   const archiveFlags = force ? new Map([["force", true]]) : new Map();
+  // Set by the docs gate when it fails, so a --force close can record the
+  // gap in the ledger after the archive lands.
+  /** @type {{ signals: string[] } | null} */
+  let docsGap = null;
 
   // Scope the coverage gate to the capabilities THIS change touches (its
   // deltas), so one deliberately deferred spec elsewhere in the tree cannot
@@ -39,6 +74,7 @@ export async function run(positional, flags) {
   // item 4). A change with no deltas (chore / metadata-only) falls back to
   // the whole-tree gate — there is no narrower honest scope for it.
   const touched = touchedCapabilities(projectRoot, id);
+  /** @type {FlagMap} */
   const coverageFlags = new Map([["strict", true]]);
   let coverageRerun = "doctrina coverage --strict";
   if (touched.length > 0) {
@@ -52,6 +88,20 @@ export async function run(positional, flags) {
   const verifyConfigured = isFile(path.join(projectRoot, ".doctrina", "verify.json"));
   const steps = [
     { label: "analyze", rerun: `doctrina analyze ${id}`, run: () => analyze.run([id], new Map()) },
+    // ADR checkpoint (operator review §4.6): the playbook's "record an ADR"
+    // step was skippable in silence. Advisory — it names the accepted ADRs
+    // whose text cites the touched capabilities and the amend commands, but
+    // an ADR merely mentioning a capability is normal, so it never blocks.
+    {
+      label: "ADR checkpoint (advisory)",
+      rerun: "doctrina decision list",
+      run: async () => {
+        if (printAdrCheckpoint(projectRoot, touched, { c }) === 0) {
+          console.log(c.green("ok") + " no accepted ADR cites the touched capabilities");
+        }
+        return 0;
+      },
+    },
     { label: "apply", rerun: `doctrina change apply ${id}`, run: () => change.run(["apply", id], new Map()) },
     verifyConfigured
       ? { label: "verify", rerun: "doctrina verify", run: () => verify.run([], new Map()) }
@@ -64,11 +114,35 @@ export async function run(positional, flags) {
     // trace is advisory (provenance is a warning, not a hard gate): report it,
     // never let it block the close.
     { label: "trace", rerun: "doctrina trace", run: async () => { await trace.run([], new Map()); return 0; } },
+    // Docs ship inside the change (D2): a change that alters a documented
+    // surface — a command, a flag, an exit code — closes only with the
+    // documentation that describes it. A blocking gate, because a docs
+    // phase scheduled after the work never happens; --force is the same
+    // escape hatch archive offers, and records the gap in the ledger.
+    {
+      label: "docs",
+      forceable: true,
+      rerun: "edit docs/ (EN + PT), then rerun",
+      run: async () => {
+        const r = checkDocsImpact(projectRoot, path.join(projectRoot, ".doctrina", "changes", id));
+        if (r.ok) {
+          console.log(c.green("ok") + ` ${r.reason}`);
+          return 0;
+        }
+        console.error(c.red("error:") + ` this change ${r.reason}:`);
+        for (const s of r.signals) console.error(`  - ${s}`);
+        console.error(c.gray("hint: ") +
+          "document it in docs/en/ AND docs/pt/ (the `keep-docs-en-pt-parity` skill), " +
+          "or pass --force to close anyway (records the gap)");
+        docsGap = r;
+        return 1;
+      },
+    },
     { label: "archive", rerun: `doctrina change archive ${id}${force ? " --force" : ""}`, run: () => change.run(["archive", id], archiveFlags) },
     { label: "validate", rerun: "doctrina validate", run: () => validate.run([], new Map()) },
   ];
 
-  console.log(c.bold(`Closing change ${id}`) + c.gray(" — analyze → apply → verify → coverage → trace → archive → validate"));
+  console.log(c.bold(`Closing change ${id}`) + c.gray(" — analyze → ADR checkpoint → apply → verify → coverage → trace → docs → archive → validate"));
 
   for (let i = 0; i < steps.length; i++) {
     const step = steps[i];
@@ -86,6 +160,13 @@ export async function run(positional, flags) {
       console.error(c.red("error:") + ` ${err.message}`);
     }
     if (code !== 0) {
+      // A forceable gate under --force warns and continues, matching how
+      // `change archive --force` handles incomplete verification: the gap
+      // is recorded, not hidden.
+      if (code !== 0 && step.forceable && force) {
+        console.log(c.yellow("warn:") + ` proceeding past "${step.label}" (--force) — the gap is recorded in the ledger`);
+        continue;
+      }
       console.log("");
       console.log(c.red(`✗ close stopped at "${step.label}"`) + c.gray(` (step ${i + 1}/${steps.length})`));
       console.log(c.gray("Fix it, then rerun the step or the whole close:"));
@@ -95,6 +176,26 @@ export async function run(positional, flags) {
     }
   }
 
+  // Record a forced docs gap in the ledger, so history shows the change
+  // shipped without its documentation rather than showing nothing.
+  if (docsGap) {
+    const ledgerPath = path.join(projectRoot, ".doctrina", "changes", "archive", "LEDGER.md");
+    if (isFile(ledgerPath)) {
+      appendFileSync(ledgerPath, `  - docs gap: ${id} closed with --force; ${docsGap.signals.join("; ")} documented nowhere\n`);
+      console.log(c.yellow("ledger") + " recorded the docs gap");
+    }
+  }
+
+  // Capture the lesson while it is fresh (operator review §4.7): surface the
+  // fix-shaped lessons not yet written as skills, right where the operator
+  // just proved they finish what they start. Advisory — a listing, never a
+  // gate, and a suggest failure never un-closes the change.
+  console.log("");
+  console.log(c.gray("──── skills (advisory)"));
+  try {
+    await skill.run(["suggest"], new Map());
+  } catch { /* advisory only */ }
+
   console.log("");
   console.log(c.green(`✓ change ${id} closed`) + c.gray(" — verified, archived, and validated."));
   console.log(c.gray("Next: ") + c.cyan("doctrina next"));
@@ -115,21 +216,28 @@ function touchedCapabilities(projectRoot, id) {
 }
 
 export const help = `
-Usage: doctrina close <id> [--force]
+Usage: doctrina close <id...> [--force]
 
 Run the whole closing sequence for a change in one pass, stopping at the
 first failure with the exact command to rerun:
 
-  analyze → change apply → verify → coverage --strict (scoped to the
-  change's touched capabilities) → trace → change archive → validate
+  analyze → ADR checkpoint (advisory) → change apply → verify → coverage
+  --strict (scoped to the change's touched capabilities) → trace → change
+  archive → validate → skill suggest (advisory)
 
 The coverage gate is scoped to the capabilities the change's deltas touch,
 so a deliberately deferred spec elsewhere cannot block an unrelated close;
 a change with no deltas gates on the whole tree. verify is skipped (with a
-note) when no .doctrina/verify.json is declared; trace is advisory (a
-report, never a blocker). This is a driver over the existing commands — it
-adds no checks of its own — so the agent makes one call instead of seven
-and the human approves once.
+note) when no .doctrina/verify.json is declared; trace, the ADR checkpoint
+(accepted ADRs citing the touched capabilities — amend via \`decision
+supersede\`, not silence), and the closing skill-suggest listing are
+advisory (reports, never blockers). This is a driver over the existing
+commands so the agent makes one call instead of nine and the human
+approves once.
+
+Multiple ids close in sequence, each independently; the exit code is the
+worst per-id result. Preview what close would refuse: \`doctrina change
+check <id>\`.
 
 Options:
   --force    Pass through to \`change archive\` (archive even if verification

package/src/commands/completion.js

@@ -1,3 +1,4 @@
+// @ts-check
 import { OPERATIONS, COMMAND_NAMES } from "../lib/commands.js";
 import { c } from "../lib/colors.js";
 
@@ -90,6 +91,11 @@ Register-ArgumentCompleter -Native -CommandName doctrina -ScriptBlock {
 `;
 }
 
+// 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 shell = positional[0];
   const generators = { bash: bashScript, zsh: zshScript, pwsh: pwshScript, powershell: pwshScript };

package/src/commands/constitution.js

@@ -1,9 +1,11 @@
+// @ts-check
 import path from "node:path";
 import process from "node:process";
 import { readdirSync } from "node:fs";
 import { exists, isDir, isFile, read } from "../lib/fs-ops.js";
 import { listHeader } from "../lib/scan.js";
 import { c } from "../lib/colors.js";
+import { notADoctrinaProject } from "../lib/exit-codes.js";
 
 // The project's standing rules in one read — Spec Kit parity for its
 // `constitution.md`, but ASSEMBLED, not a new home for facts. Doctrina's
@@ -16,10 +18,15 @@ import { c } from "../lib/colors.js";
 // To change a principle, supersede its ADR; to change a non-goal, edit
 // product.md. The command never writes — it has nothing of its own to own.
 
+// 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 projectRoot = process.cwd();
   if (!exists(path.join(projectRoot, ".doctrina"))) {
-    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+    throw notADoctrinaProject();
   }
 
   const project = projectName(projectRoot);