doctrina-cli 0.12.0 → 0.14.0

package/src/lib/gates.js

@@ -0,0 +1,123 @@
+// @ts-check
+import { getSection } from "./doc-model.js";
+import path from "node:path";
+import { appendFileSync, writeFileSync } from "node:fs";
+import { exists, isFile, mkdirp, read } from "./fs-ops.js";
+import { today } from "./dates.js";
+import { collectAnalysis } from "../commands/analyze.js";
+
+// The gate-to-transition map (audit item C6).
+//
+// Each command used to decide its own preconditions. `change archive` and
+// `close` checked theirs; `change apply` checked nothing. So `analyze`
+// could exit 1 on a change and `change apply` would mutate it anyway and
+// exit 0 — and the README flowchart tells agents to follow exactly that
+// analyze → apply path. An agent could reach, through one path, a state
+// another path forbids.
+//
+// The fix is not "add a check to apply" but "declare once which gates
+// guard which transition, and have every driver consult the declaration".
+// Which specific gate guards which transition matters less than the
+// guarantee that the answer does not depend on how you got there.
+
+// A gate is a named precondition returning human-readable blockers.
+export const GATES = {
+  // Structural validity: the change's own files parse and point at real
+  // targets. The same checks `doctrina analyze` reports.
+  structure: {
+    label: "structure",
+    rerun: (id) => `doctrina analyze ${id}`,
+    blockers(projectRoot, changeDir) {
+      return collectAnalysis(projectRoot, changeDir)
+        .filter((r) => r.kind === "fail")
+        .map((r) => stripAnsi(r.line).replace(/^✗\s*/, "").trim());
+    },
+  },
+
+  // Verification: the work is claimed complete. Every checkbox in
+  // tasks.md (closing steps included) and in the proposal's
+  // "## Verification" section.
+  verification: {
+    label: "verification",
+    rerun: (id) => `doctrina change tick ${id}`,
+    blockers(projectRoot, changeDir) {
+      const out = [];
+      const countUnchecked = (s) => (s.match(/^\s*-\s*\[ \]/gm) ?? []).length;
+
+      const tasksPath = path.join(changeDir, "tasks.md");
+      if (isFile(tasksPath)) {
+        const n = countUnchecked(read(tasksPath));
+        if (n > 0) out.push(`${n} unchecked task${n === 1 ? "" : "s"} in tasks.md (closing steps count)`);
+      }
+      const proposalPath = path.join(changeDir, "proposal.md");
+      if (isFile(proposalPath)) {
+        const n = countUnchecked(getSection(read(proposalPath), "Verification"));
+        if (n > 0) out.push(`${n} unmet verification item${n === 1 ? "" : "s"} in proposal.md (## Verification)`);
+      }
+      return out;
+    },
+  },
+};
+
+// Which gates guard each lifecycle transition. The single declaration.
+//
+// `apply` requires structure: mutating specs from a change whose deltas do
+// not parse is how a malformed delta reaches a spec file. This is the gate
+// `analyze` reports and that `apply` used to ignore entirely (C6).
+//
+// `archive` requires verification, and deliberately NOT structure. The
+// structure gate is a PRE-APPLY question — "is this safe to apply?" — and
+// one of its checks is that an ADDED delta's target does not already hold
+// real content. After a successful apply that target holds exactly the
+// content the delta just wrote, so re-asking at archive time reports a
+// conflict that is the proof the apply worked. A gate must be asked at the
+// point its question is meaningful.
+export const TRANSITIONS = {
+  apply: { label: "change apply", gates: ["structure"] },
+  archive: { label: "change archive", gates: ["verification"] },
+};
+
+// Evaluate a transition's gates. Returns { ok, blockers, gates } where
+// blockers is a flat list of human-readable reasons.
+export function checkTransition(projectRoot, changeDir, transition) {
+  const t = TRANSITIONS[transition];
+  if (!t) throw new Error(`unknown transition "${transition}"`);
+  const blockers = [];
+  for (const name of t.gates) {
+    for (const b of GATES[name].blockers(projectRoot, changeDir)) {
+      blockers.push({ gate: name, message: b });
+    }
+  }
+  return { ok: blockers.length === 0, blockers, gates: t.gates };
+}
+
+// Record a forced transition in the archive ledger, so a gap that was
+// waved through is part of the visible history rather than nothing at all
+// — the same posture `change archive --force` and `change abandon` take.
+export function recordForcedGap(projectRoot, id, transition, blockers) {
+  const archiveDir = path.join(projectRoot, ".doctrina", "changes", "archive");
+  const ledgerPath = path.join(archiveDir, "LEDGER.md");
+  // Create the ledger if this is the first entry. A forced transition can
+  // happen before any change has ever been archived, and a gap that goes
+  // unrecorded because the file did not exist yet is exactly the silence
+  // this is meant to break.
+  if (!exists(ledgerPath)) {
+    mkdirp(archiveDir);
+    writeFileSync(ledgerPath,
+      "# Change ledger\n\n" +
+      "One line per archived change, newest last. Appended by\n" +
+      "`doctrina change archive`; edit freely, the CLI only appends.\n\n");
+  }
+  const summary = blockers.map((b) => `${b.gate}: ${b.message}`).join("; ");
+  appendFileSync(
+    ledgerPath,
+    `  - ${today()} — ${id} — forced ${transition} past ${blockers.length} ` +
+    `blocker${blockers.length === 1 ? "" : "s"} (${summary})\n`,
+  );
+  return true;
+}
+
+function stripAnsi(s) {
+  // eslint-disable-next-line no-control-regex
+  return String(s).replace(/\[[0-9;]*m/g, "");
+}

package/src/lib/git.js

@@ -0,0 +1,97 @@
+// @ts-check
+import { spawnSync } from "node:child_process";
+
+// One place that knows how to ask git a question and how to interpret not
+// getting an answer (audit item C8).
+//
+// Nine call sites each ran `spawnSync("git", ...)` and decided for
+// themselves what a non-zero status meant. `metrics` decided it meant
+// failure, so on a brand-new project — the most common state in which
+// someone explores the CLI — it printed:
+//
+//   error: git log failed: fatal: your current branch 'master' does not
+//   have any commits yet
+//
+// A repository with no commits is a valid state, not an error. So is a
+// directory that is not a repository at all. What is genuinely an error
+// is git being absent when a command cannot work without it — and that is
+// an ENVIRONMENT condition (exit 4), not a gate failure.
+
+export const GIT_STATE = Object.freeze({
+  /** git ran and answered. */
+  OK: "ok",
+  /** A repository with no commits yet — a valid first-run state. */
+  EMPTY: "empty",
+  /** Not a git repository. */
+  NOT_A_REPO: "not-a-repo",
+  /** git is not installed or not on PATH. */
+  ABSENT: "absent",
+  /** git ran and refused, for a reason this module does not classify. */
+  FAILED: "failed",
+});
+
+// Run a git command. Never throws. Returns
+// { state, stdout, lines, stderr, code }.
+export function git(cwd, args) {
+  const r = spawnSync("git", args, { cwd, encoding: "utf8" });
+  if (r.error) {
+    // ENOENT here means the binary is missing, not that the command failed.
+    return { state: GIT_STATE.ABSENT, stdout: "", lines: [], stderr: String(r.error.message ?? ""), code: null };
+  }
+  const stderr = String(r.stderr ?? "");
+  if (r.status === 0) {
+    const stdout = String(r.stdout ?? "");
+    return { state: GIT_STATE.OK, stdout, lines: splitLines(stdout), stderr, code: 0 };
+  }
+  // git's own wording for the benign cases. Matched on the message because
+  // git reports them all with a generic non-zero status. "Needed a single
+  // revision" is what `rev-parse --verify HEAD` says on a repo with no
+  // commits, which is how the empty-history probe first fooled itself.
+  if (/does not have any commits yet|unknown revision or path not in the working tree|bad default revision|Needed a single revision|ambiguous argument 'HEAD'/i.test(stderr)) {
+    return { state: GIT_STATE.EMPTY, stdout: "", lines: [], stderr, code: r.status };
+  }
+  if (/not a git repository/i.test(stderr)) {
+    return { state: GIT_STATE.NOT_A_REPO, stdout: "", lines: [], stderr, code: r.status };
+  }
+  // Anything else that exited non-zero is a failure, NOT a success with an
+  // empty answer. Reporting it as OK is how a caller reads "no results"
+  // from a command that actually refused.
+  return { state: GIT_STATE.FAILED, stdout: "", lines: [], stderr, code: r.status };
+}
+
+// Is this a git repository at all?
+export function isRepo(cwd) {
+  return git(cwd, ["rev-parse", "--is-inside-work-tree"]).state === GIT_STATE.OK;
+}
+
+// Does it have at least one commit? False for a fresh `git init`.
+export function hasCommits(cwd) {
+  return git(cwd, ["rev-parse", "--verify", "HEAD"]).state === GIT_STATE.OK;
+}
+
+// The state a command should report before trying to read history:
+// { usable, state, reason } where `reason` is a sentence fit to print.
+export function historyState(cwd) {
+  const probe = git(cwd, ["rev-parse", "--is-inside-work-tree"]);
+  if (probe.state === GIT_STATE.ABSENT) {
+    return { usable: false, state: GIT_STATE.ABSENT, reason: "git is not installed or not on PATH" };
+  }
+  if (probe.state !== GIT_STATE.OK) {
+    return { usable: false, state: GIT_STATE.NOT_A_REPO, reason: "this is not a git repository" };
+  }
+  if (!hasCommits(cwd)) {
+    return { usable: false, state: GIT_STATE.EMPTY, reason: "this repository has no commits yet" };
+  }
+  return { usable: true, state: GIT_STATE.OK, reason: "" };
+}
+
+// Lines of output, trimmed and blank-filtered — what nearly every caller
+// actually wanted from stdout.
+export function gitLines(cwd, args) {
+  const r = git(cwd, args);
+  return r.state === GIT_STATE.OK ? r.lines : [];
+}
+
+function splitLines(s) {
+  return s.split(/\r?\n/).map((x) => x.trim()).filter(Boolean);
+}

package/src/lib/index-json.js

@@ -1,9 +1,22 @@
+// @ts-check
 import path from "node:path";
 import { read, write, exists } from "./fs-ops.js";
 import { cliVersion } from "./version.js";
 
 export const SCHEMA_VERSION = "0.1.0";
 
+// The artifact categories a well-formed index.json carries. ONE definition,
+// consumed by `blank()` (what `init` writes) and by `templates check` /
+// `templates update` (what a project is measured against).
+//
+// There used to be two: the shape `init` materialised from a template file
+// and the shape `templates check` required. Nothing compared them, so when
+// `contracts` was added to the expected shape and not to the template,
+// every project was born needing a scaffold update (audit item C5).
+export const ARTIFACT_CATEGORIES = Object.freeze([
+  "specs", "decisions", "changes", "changes_archive", "skills", "contracts",
+]);
+
 export function indexPath(projectRoot) {
   return path.join(projectRoot, ".doctrina", "index.json");
 }
@@ -46,12 +59,7 @@ export function blank(projectName, date) {
         version: "0.1.0",
         last_updated: date,
       },
-      specs: [],
-      decisions: [],
-      changes: [],
-      changes_archive: [],
-      skills: [],
-      contracts: [],
+      ...Object.fromEntries(ARTIFACT_CATEGORIES.map((cat) => [cat, []])),
     },
   };
 }

package/src/lib/json-out.js

@@ -0,0 +1,83 @@
+// @ts-check
+import process from "node:process";
+import { EXIT } from "./exit-codes.js";
+
+// `--json` on every command, with a versioned envelope (audit item M7).
+//
+// Five of thirty-five commands spoke JSON. Everything else emitted
+// ANSI-coloured prose, while the primary consumer is a machine. Paired with
+// the exit-code contract (ADR 0018), the two form the machine interface:
+// structured output plus a meaningful status. Without both, an autonomous
+// loop is parsing English.
+//
+// Two levels of support, and the difference is stated rather than hidden:
+//
+//   STRUCTURED — the command builds a payload describing its result. These
+//     are the read and report commands, where a result has real shape.
+//   ENVELOPE   — the command's human output is captured and returned inside
+//     a versioned envelope alongside `ok` and `exitCode`. Branch on those;
+//     the lines are there for completeness, not for parsing.
+//
+// A command with nothing better to say is still machine-consumable, which
+// is what makes "--json on every command" a claim rather than an intention.
+
+export const JSON_SCHEMA_VERSION = "1.0.0";
+
+export function wantsJson(flags) {
+  return flags?.get?.("json") === true;
+}
+
+// Print a structured payload. `command` is the invocation, `data` whatever
+// that command has to say.
+export function emitJson(command, data, { ok = true, exitCode = EXIT.OK } = {}) {
+  process.stdout.write(JSON.stringify({
+    $schema_version: JSON_SCHEMA_VERSION,
+    command,
+    ok,
+    exit_code: exitCode,
+    ...data,
+  }, null, 2) + "\n");
+}
+
+// Run `fn` with console output captured, so a command that has no
+// structured payload can still answer in JSON. Returns { code, stdout,
+// stderr } with the lines it would have printed.
+export async function captureOutput(fn) {
+  const stdout = [];
+  const stderr = [];
+  const origLog = console.log;
+  const origError = console.error;
+  const origWarn = console.warn;
+  // Some commands write to the stream directly rather than through console
+  // — `completion` emits a shell script meant for redirection. Capturing
+  // only console.* let that output escape the envelope and corrupt the
+  // JSON on stdout, so the raw stream is captured too.
+  const origWrite = process.stdout.write.bind(process.stdout);
+  const pushLines = (target, chunk) => {
+    for (const line of String(chunk).replace(/\n$/, "").split("\n")) target.push(line);
+  };
+  console.log = (...args) => stdout.push(args.map(String).join(" "));
+  console.error = (...args) => stderr.push(args.map(String).join(" "));
+  console.warn = (...args) => stderr.push(args.map(String).join(" "));
+  process.stdout.write = (chunk, ...rest) => {
+    pushLines(stdout, chunk);
+    const cb = rest.find((r) => typeof r === "function");
+    if (cb) cb();
+    return true;
+  };
+  try {
+    const code = await fn();
+    return { code: code ?? EXIT.OK, stdout, stderr };
+  } finally {
+    console.log = origLog;
+    console.error = origError;
+    console.warn = origWarn;
+    process.stdout.write = origWrite;
+  }
+}
+
+// Strip ANSI so captured lines are usable as data even when colour was on.
+export function stripAnsi(s) {
+  // eslint-disable-next-line no-control-regex
+  return String(s).replace(/\[[0-9;]*m/g, "");
+}

package/src/lib/prompt.js

@@ -1,4 +1,15 @@
+// @ts-check
 import readline from "node:readline";
+import process from "node:process";
+
+// Is there a real person on the other end? Every prompt must ask this
+// first. `init` checked it before the ADAPTER prompt but not before the
+// project-description prompt, so a non-interactive caller that forgot
+// --non-interactive got a project with a blank description and no warning
+// (audit item C9).
+export function isInteractive() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
 
 export async function ask(question, { defaultValue = "" } = {}) {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
@@ -11,7 +22,13 @@ export async function ask(question, { defaultValue = "" } = {}) {
   }
 }
 
-export async function confirm(question, { defaultYes = false } = {}) {
+// Ask for consent. Off a terminal there is nobody to ask, so the answer is
+// `whenNonInteractive` — which callers set to false for destructive
+// operations: silence is not consent.
+export async function confirm(question, { defaultYes = false, whenNonInteractive = null } = {}) {
+  if (!isInteractive()) {
+    return whenNonInteractive === null ? defaultYes : whenNonInteractive;
+  }
   const suffix = defaultYes ? "Y/n" : "y/N";
   const ans = await ask(`${question} (${suffix})`);
   if (!ans) return defaultYes;

package/src/lib/scan.js

@@ -1,3 +1,5 @@
+// @ts-check
+import { getHeader, getSection } from "./doc-model.js";
 import path from "node:path";
 import { readdirSync } from "node:fs";
 import { isDir, isFile, read, walk } from "./fs-ops.js";
@@ -5,29 +7,18 @@ import { today } from "./dates.js";
 import { parseFrontmatter } from "../commands/skill.js";
 import { parseOperation, parseCapabilityFromDelta } from "../commands/change.js";
 
-// Parse a metadata header line, tolerating BOTH conventions:
-//   **Name:** value        (spec style)
-//   - **Name:** value      (ADR / proposal / intake style)
-// The leading "- " is optional so a one-character convention slip (an
-// agent hand-authoring an ADR with the bare spec form, or vice versa)
-// still parses instead of silently falling back to a default value.
-const HEADER_PREFIX = "(?:-\\s+)?";
-
-// Parse a spec-style header line: **Name:** value (dash optional).
+// Header reading lives in ONE place now (lib/doc-model.js, audit item M3).
+// These two names survive because dozens of call sites use them and the
+// distinction they once encoded — spec style vs list style — is now the
+// document model's job, not the caller's.
 export function specHeader(text, name) {
-  const m = text.match(new RegExp(`^${HEADER_PREFIX}\\*\\*${name}:\\*\\*\\s+(.+)$`, "m"));
-  return m ? m[1].trim() : null;
+  return getHeader(text, name);
 }
 
-// Parse an ADR/proposal-style header line: - **Name:** value (dash optional).
 export function listHeader(text, name) {
-  const m = text.match(new RegExp(`^${HEADER_PREFIX}\\*\\*${name}:\\*\\*\\s+(.+)$`, "m"));
-  return m ? m[1].trim() : null;
+  return getHeader(text, name);
 }
 
-// The machine-readable "**Depends on:** defects, decisions" spec header: the
-// sibling capabilities this spec builds on. Returns [] when absent, "n/a", or
-// empty. One parser so index, why, context, and review agree.
 export function parseDependsOn(text) {
   const raw = specHeader(text, "Depends on");
   if (!raw || /^n\/a\b/i.test(raw.trim()) || raw.trim() === "—") return [];
@@ -39,6 +30,72 @@ function dirEntries(dir) {
   return readdirSync(dir).filter((e) => !e.startsWith(".")).sort();
 }
 
+
+// The capabilities an ADR governs, from its optional "Scope:" header
+// (M4). Returns [] when absent, "n/a", or "—" — an unscoped ADR is global
+// and belongs in every pack, which is what keeps this backward compatible.
+export function parseAdrScope(text) {
+  const raw = listHeader(text, "Scope");
+  if (!raw || /^n\/a\b/i.test(raw.trim()) || raw.trim() === "—") return [];
+  return raw.match(/[a-z][a-z0-9][a-z0-9-]*/g) ?? [];
+}
+
+// One sentence describing what an ADR decided, taken from its "## Decision"
+// section. This is what a budget-constrained pack falls back to before it
+// drops an ADR entirely: a title and a sentence still carry the decision,
+// where an omission carries nothing.
+export function adrSummary(text) {
+  const body = getSection(text, "Decision");
+  if (!body) return null;
+  for (const line of body.split("\n")) {
+    const s = line.trim();
+    if (!s || s.startsWith("<!--") || s.startsWith("#") || s.startsWith("|")) continue;
+    // Take the first sentence, capped so the index stays scannable.
+    const plain = s.replace(/^[-*\d.]+\s*/, "").replace(/\*\*/g, "");
+    const sentence = (plain.match(/^.*?[.!?](?=\s|$)/) ?? [plain])[0].trim();
+    if (sentence.length < 12) continue;
+    return sentence.length > 220 ? sentence.slice(0, 217).trimEnd() + "..." : sentence;
+  }
+  return null;
+}
+
+// The index entry for ONE decision, derived from its file. This is the
+// single definition of a decision record: `deriveIndex` builds the whole
+// list from it, and `doctrina decision new` registers a new ADR through it
+// rather than assembling a look-alike by hand. Two constructors for one
+// record shape is how a field added to the deriver (M4's `summary`) turns
+// every freshly created ADR into index drift the moment it is written.
+export function decisionEntry(text, basename, prev, date) {
+  const id = basename.match(/^(\d{4})-/)?.[1] ?? prev?.id ?? "0000";
+  const titleMatch = text.match(/^#\s+ADR\s+\d{4}\s*[—-]\s*(.+)$/m);
+  const entry = {
+    id,
+    path: `.doctrina/decisions/${basename}`,
+    title: titleMatch ? titleMatch[1].trim() : prev?.title ?? basename,
+    status: listHeader(text, "Status") ?? prev?.status ?? "proposed",
+    date: listHeader(text, "Date") ?? prev?.date ?? date,
+  };
+  const supersedes = listHeader(text, "Supersedes");
+  if (supersedes && supersedes !== "—") entry.supersedes = supersedes;
+  const supersededBy = listHeader(text, "Superseded by");
+  if (supersededBy && supersededBy !== "—") entry.superseded_by = supersededBy;
+  const landed = listHeader(text, "Landed");
+  if (landed && landed !== "—") entry.landed = landed;
+  // Scope (M4): the capabilities this decision governs. ADRs are immutable
+  // and never retire, so without a scope every accepted ADR loads into every
+  // context pack forever — the pack grows O(project age) with no decay. An
+  // ADR with no Scope: is GLOBAL by definition, the backward-compatible
+  // default.
+  const scope = parseAdrScope(text);
+  if (scope.length > 0) entry.scope = scope;
+  // Summary: one sentence from the Decision section, so a pack over budget
+  // can degrade an ADR to title + summary instead of dropping it outright.
+  const summary = adrSummary(text);
+  if (summary) entry.summary = summary;
+  return entry;
+}
+
+
 // Regenerate the index object from the artifacts on disk. The files are
 // the source of truth; fields with no on-disk source (project name,
 // framework_version, product metadata) are carried over from `current`.
@@ -52,6 +109,12 @@ export function deriveIndex(projectRoot, current) {
     project: current?.project ?? path.basename(projectRoot),
     framework_version: current?.framework_version ?? "0.0.0",
     last_updated: current?.last_updated ?? date,
+    // Project settings, carried over verbatim. `deriveIndex` rebuilds the
+    // artifact graph FROM DISK, so anything it does not explicitly carry is
+    // silently erased on the next `index rebuild` — config has no on-disk
+    // source to be rederived from, which is exactly why it must be listed
+    // here alongside project and framework_version. Absent means defaults.
+    ...(current?.config !== undefined ? { config: current.config } : {}),
     artifacts: {
       product: cur.product ?? {
         path: ".doctrina/product.md",
@@ -112,23 +175,8 @@ export function deriveIndex(projectRoot, current) {
     const base = path.basename(f);
     const m = base.match(/^(\d{4})-.*\.md$/);
     if (!m) continue;
-    const text = read(f);
     const prev = (cur.decisions ?? []).find((d) => d.id === m[1]);
-    const titleMatch = text.match(/^#\s+ADR\s+\d{4}\s*[—-]\s*(.+)$/m);
-    const entry = {
-      id: m[1],
-      path: `.doctrina/decisions/${base}`,
-      title: titleMatch ? titleMatch[1].trim() : prev?.title ?? base,
-      status: listHeader(text, "Status") ?? prev?.status ?? "proposed",
-      date: listHeader(text, "Date") ?? prev?.date ?? date,
-    };
-    const supersedes = listHeader(text, "Supersedes");
-    if (supersedes && supersedes !== "—") entry.supersedes = supersedes;
-    const supersededBy = listHeader(text, "Superseded by");
-    if (supersededBy && supersededBy !== "—") entry.superseded_by = supersededBy;
-    const landed = listHeader(text, "Landed");
-    if (landed && landed !== "—") entry.landed = landed;
-    out.artifacts.decisions.push(entry);
+    out.artifacts.decisions.push(decisionEntry(read(f), base, prev, date));
   }
 
   // Open changes — every directory except archive/.