doctrina-cli 0.13.0 → 0.14.0

package/src/lib/docs-impact.js

@@ -0,0 +1,167 @@
+// @ts-check
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { isFile, read, walk } from "./fs-ops.js";
+import { COMMAND_NAMES } from "./commands.js";
+import { locateTemplatesDir } from "./templates.js";
+
+// "Docs ship inside the change, never after it" (audit item D2).
+//
+// A docs phase scheduled AFTER the work never happens. So a change that
+// alters a documented surface — a command, a flag, an exit code — must also
+// carry the documentation for it, checked at close time and refusable with
+// --force exactly like the archive verification gate.
+//
+// Both halves are deterministic: what the change says it touches is read
+// from its own artifacts, and whether docs moved is read from git. No
+// language understanding (ADR 0005).
+
+const DOC_PATHS = [/^docs\//, /^README\.md$/, /^README\.pt\.md$/];
+
+// Non-empty lines of the shipped change templates, so authored content can
+// be told apart from scaffold. Computed once; falls back to an empty set
+// when the templates cannot be located (unusual installs), which only makes
+// the gate more eager, never wrong about a real signal.
+// Ticking a scaffold checkbox rewrites "- [ ] ..." to "- [x] ...", which
+// would otherwise stop the line matching its own template and make every
+// completed change look authored. Compare with the box state normalised.
+function normaliseScaffoldLine(line) {
+  return line.trim().replace(/^-\s*\[[ xX]\]/, "- [ ]");
+}
+
+let scaffoldCache = null;
+function scaffoldLines() {
+  if (scaffoldCache) return scaffoldCache;
+  const lines = new Set();
+  try {
+    const changeTemplates = path.join(locateTemplatesDir(), "change");
+    for (const f of walk(changeTemplates)) {
+      for (const line of read(f).split(/\r?\n/)) {
+        const trimmed = normaliseScaffoldLine(line);
+        if (trimmed) lines.add(trimmed);
+      }
+    }
+  } catch { /* no templates dir — treat everything as authored */ }
+  scaffoldCache = lines;
+  return lines;
+}
+
+// Does this change alter something the documentation makes promises about?
+// Read from the change's own artifacts — the deltas it will merge into
+// specs, plus the proposal that states its shape. Returns the list of
+// signals found (empty when the change touches no documented surface).
+export function documentedSurfaceSignals(changeDir) {
+  const signals = [];
+  const known = new Set(COMMAND_NAMES);
+
+  // Read only what the AUTHOR wrote. The scaffold's own boilerplate names
+  // commands — the proposal's Verification checklist cites `doctrina verify`
+  // and `doctrina coverage` — so scanning the raw file made every change look
+  // like it touched a documented surface. A gate that fires on everything is
+  // a gate that gets ignored, so the template's lines are subtracted first.
+  const boilerplate = scaffoldLines();
+  const authored = (text) => text
+    .split(/\r?\n/)
+    .filter((line) => !boilerplate.has(normaliseScaffoldLine(line)))
+    .join("\n");
+
+  const sources = [];
+  const proposal = path.join(changeDir, "proposal.md");
+  if (isFile(proposal)) sources.push(authored(read(proposal)));
+  for (const p of walk(path.join(changeDir, "specs"))) {
+    if (p.endsWith("delta.md")) sources.push(authored(read(p)));
+  }
+  const text = sources.join("\n");
+  if (!text.trim()) return signals;
+
+  // Command references, from code context only, so prose about "the
+  // doctrina framework" is not a signal.
+  const chunks = [];
+  const outside = text.replace(/```[\s\S]*?```/g, (b) => { chunks.push(b); return "\n"; });
+  for (const m of outside.matchAll(/`[^`]+`/g)) chunks.push(m[0]);
+  const code = chunks.join("\n");
+
+  const commands = new Set();
+  for (const m of code.matchAll(/(?:npx\s+doctrina-cli|doctrina)\s+([a-z][a-z-]+)/g)) {
+    if (known.has(m[1])) commands.add(m[1]);
+  }
+  if (commands.size > 0) {
+    signals.push(`commands: ${[...commands].sort().join(", ")}`);
+  }
+
+  const flags = new Set();
+  for (const m of code.matchAll(/--([a-z][a-z0-9-]{2,})/g)) flags.add(`--${m[1]}`);
+  if (flags.size > 0) {
+    signals.push(`flags: ${[...flags].sort().slice(0, 8).join(", ")}`);
+  }
+
+  if (/\bexit\s+code|\bexits?\s+(?:with\s+)?[0-4]\b/i.test(text)) {
+    signals.push("exit codes");
+  }
+
+  return signals;
+}
+
+// Documentation paths touched by the work in flight. Union of the working
+// tree (uncommitted, the common agent case) and this branch's commits
+// against the default branch (the case where the agent already committed).
+// Returns [] outside a git repository — where the gate cannot see, it does
+// not accuse.
+//
+// KNOWN COARSENESS: this answers "did documentation move in this work?",
+// not "did documentation move FOR THIS CHANGE?". Closing several changes
+// from one uncommitted working tree, docs written for an earlier change
+// satisfy the gate for a later one. The gate is deliberately permissive
+// here — its job is to stop a change shipping with NO documentation at
+// all, and attributing a hunk to a change would need guesswork the rest of
+// the framework refuses to do (ADR 0005).
+export function docsTouched(projectRoot) {
+  const git = (args) => {
+    const r = spawnSync("git", args, { cwd: projectRoot, encoding: "utf8" });
+    if (r.error || r.status !== 0) return [];
+    return r.stdout.split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
+  };
+  const set = new Set();
+  for (const f of git(["diff", "--name-only", "HEAD"])) set.add(f);
+  for (const f of git(["ls-files", "--others", "--exclude-standard"])) set.add(f);
+  for (const base of ["main", "master"]) {
+    const mb = git(["merge-base", "HEAD", base]);
+    if (mb.length > 0) {
+      for (const f of git(["diff", "--name-only", `${mb[0]}..HEAD`])) set.add(f);
+      break;
+    }
+  }
+  return [...set]
+    .map((f) => f.replace(/\\/g, "/"))
+    .filter((f) => DOC_PATHS.some((re) => re.test(f)));
+}
+
+export function isGitRepo(projectRoot) {
+  const r = spawnSync("git", ["rev-parse", "--is-inside-work-tree"], {
+    cwd: projectRoot, encoding: "utf8",
+  });
+  return !r.error && r.status === 0;
+}
+
+// The gate itself: { ok, signals, touched, reason }. `ok` is true when the
+// change touches no documented surface, when documentation moved with it,
+// or when git cannot answer.
+export function checkDocsImpact(projectRoot, changeDir) {
+  const signals = documentedSurfaceSignals(changeDir);
+  if (signals.length === 0) {
+    return { ok: true, signals, touched: [], reason: "touches no documented surface" };
+  }
+  if (!isGitRepo(projectRoot)) {
+    return { ok: true, signals, touched: [], reason: "not a git repository — cannot tell what moved" };
+  }
+  const touched = docsTouched(projectRoot);
+  if (touched.length > 0) {
+    return { ok: true, signals, touched, reason: `documentation moved with it (${touched.length} file${touched.length === 1 ? "" : "s"})` };
+  }
+  return {
+    ok: false,
+    signals,
+    touched,
+    reason: "alters a documented surface but no docs/ or README change accompanies it",
+  };
+}

package/src/lib/ears.js

@@ -1,3 +1,4 @@
+// @ts-check
 // Structural EARS checks for capability specs. The clarify command catches
 // word-level smells; this catches grammar-shape problems per EARS section.
 // All findings are warnings: specs evolve, validation should not block.

package/src/lib/exit-codes.js

@@ -0,0 +1,103 @@
+// @ts-check
+// The exit-code contract (audit item C7).
+//
+// Code 1 used to mean three different things, and an agent driving the
+// loop could not tell them apart:
+//
+//   "your change is not ready"       -> iterate and retry
+//   "this project is not configured" -> run a setup command first
+//   "this machine cannot run this"   -> stop
+//
+// All three returned 1. The first means keep working, the second means do
+// something else first, the third means give up — and an autonomous loop
+// that cannot distinguish them either spins on an unfixable failure or
+// abandons a fixable one.
+//
+// This is the smallest module in the CLI and the one a machine consumer
+// depends on most. Every command's exit path maps to a member here.
+
+export const EXIT = Object.freeze({
+  /** The command did what it was asked. Warnings are allowed. */
+  OK: 0,
+  /** A gate failed: the WORK is not ready. Fix the work and retry. */
+  GATE: 1,
+  /** The INVOCATION is wrong: unknown command, missing/malformed argument.
+   *  Do not retry unchanged. */
+  USAGE: 2,
+  /** A PRECONDITION is missing: the project is not set up for this yet.
+   *  Run the named setup command, then retry. */
+  PRECONDITION: 3,
+  /** The ENVIRONMENT cannot run this: git absent, unreadable tree, and
+   *  other conditions no amount of retrying fixes. Stop. */
+  ENVIRONMENT: 4,
+});
+
+// What each code means, for `--help`, the docs, and the tests that assert
+// the mapping. Keyed by numeric code so a consumer can look one up.
+export const EXIT_MEANINGS = Object.freeze({
+  [EXIT.OK]: {
+    name: "OK",
+    summary: "success (warnings allowed)",
+    agentAction: "continue",
+  },
+  [EXIT.GATE]: {
+    name: "GATE",
+    summary: "a gate failed — the work is not ready",
+    agentAction: "fix the work, then retry the same command",
+  },
+  [EXIT.USAGE]: {
+    name: "USAGE",
+    summary: "the invocation is wrong — unknown command or bad argument",
+    agentAction: "do not retry unchanged; correct the invocation",
+  },
+  [EXIT.PRECONDITION]: {
+    name: "PRECONDITION",
+    summary: "a precondition is missing — the project is not set up for this",
+    agentAction: "run the setup command named in the error, then retry",
+  },
+  [EXIT.ENVIRONMENT]: {
+    name: "ENVIRONMENT",
+    summary: "the environment cannot run this command",
+    agentAction: "stop; retrying will not help",
+  },
+});
+
+// The block `doctrina --help` prints, generated so help and contract
+// cannot drift.
+export function exitCodeHelp() {
+  return Object.entries(EXIT_MEANINGS)
+    .map(([code, m]) => `  ${code}  ${m.summary}`)
+    .join("\n");
+}
+
+// A precondition failure, thrown by a command whose project/config is not
+// ready. The entrypoint maps it to EXIT.PRECONDITION and prints the setup
+// command, so every "you need to run X first" path reports the same code.
+export class PreconditionError extends Error {
+  constructor(message, remedy) {
+    super(message);
+    this.name = "PreconditionError";
+    this.exitCode = EXIT.PRECONDITION;
+    this.remedy = remedy ?? null;
+  }
+}
+
+// An environment failure: the machine, not the project, is the problem.
+export class EnvironmentError extends Error {
+  constructor(message, remedy) {
+    super(message);
+    this.name = "EnvironmentError";
+    this.exitCode = EXIT.ENVIRONMENT;
+    this.remedy = remedy ?? null;
+  }
+}
+
+// "Not a Doctrina project" is the single most common precondition, raised
+// by nearly every command. One constructor so the message and the code
+// stay identical everywhere.
+export function notADoctrinaProject() {
+  return new PreconditionError(
+    "not a Doctrina project (no .doctrina/ in cwd)",
+    "doctrina init",
+  );
+}

package/src/lib/flag-catalog.js

@@ -0,0 +1,106 @@
+// @ts-check
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { COMMAND_NAMES } from "./commands.js";
+
+// One catalog of "which flags does command X accept", with two consumers:
+//
+//   - the static undeclared-flag test (C3), which asserts every flag a
+//     command READS is declared, so `parseArgs` never swallows a positional
+//     as an undeclared flag's value again; and
+//   - the docs accuracy gate (D1, `scripts/check-docs.js`), which asserts
+//     every flag the DOCS document against a command is declared.
+//
+// One invariant, two checks: source and prose are held to the same list, so
+// a renamed flag cannot stay green in either place. Both read a command
+// module's exported `flags` — the declaration lives WITH the command, not in
+// the entrypoint, which is why an added command no longer requires editing
+// `src/index.js` to make its flags parse (the structural half of C3).
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const commandsDir = path.join(here, "..", "commands");
+
+// Flags the entrypoint owns for every command; a command never redeclares them.
+export const GLOBAL_FLAGS = Object.freeze({
+  boolean: ["help", "h", "v", "debug"],
+  string: [],
+});
+
+// Command name -> module filename. Every command's module is `<name>.js`
+// except where this map says otherwise.
+const MODULE_OVERRIDES = { index: "index-rebuild.js" };
+
+export function moduleFileFor(commandName) {
+  return MODULE_OVERRIDES[commandName] ?? `${commandName}.js`;
+}
+
+export function modulePathFor(commandName) {
+  return path.join(commandsDir, moduleFileFor(commandName));
+}
+
+// The flag spec a command module exports, normalised to
+// { boolean: string[], string: string[] }. Returns null when the module
+// declares none — which the C3 test treats as a failure and the docs gate
+// treats as "not checkable yet", so the two can land independently.
+export async function loadFlagSpec(commandName) {
+  const mod = await import(pathToUrl(modulePathFor(commandName)));
+  const spec = mod.flags;
+  if (!spec) return null;
+  return {
+    boolean: [...(spec.boolean ?? [])],
+    string: [...(spec.string ?? [])],
+  };
+}
+
+// Every flag name a command accepts (own + global), as a Set. null when the
+// command declares no spec.
+export async function declaredFlags(commandName) {
+  const spec = await loadFlagSpec(commandName);
+  if (!spec) return null;
+  return new Set([
+    ...spec.boolean, ...spec.string,
+    ...GLOBAL_FLAGS.boolean, ...GLOBAL_FLAGS.string,
+  ]);
+}
+
+export async function loadAllFlagSpecs() {
+  const out = new Map();
+  for (const name of COMMAND_NAMES) out.set(name, await loadFlagSpec(name));
+  return out;
+}
+
+// Flag names a source file READS, by scanning its call sites:
+//   flagBool(flags, "x")  flagString(flags, "x")  flags.has("x")  flags.get("x")
+// Deterministic text scan, not execution — it sees every branch, including
+// the ones a given run never takes.
+export function scanFlagUsage(sourceText) {
+  const used = new Set();
+  const patterns = [
+    /flagBool\(\s*flags\s*,\s*["']([^"']+)["']/g,
+    /flagString\(\s*flags\s*,\s*["']([^"']+)["']/g,
+    /flags\.has\(\s*["']([^"']+)["']/g,
+    /flags\.get\(\s*["']([^"']+)["']/g,
+  ];
+  for (const re of patterns) {
+    for (const m of sourceText.matchAll(re)) used.add(m[1]);
+  }
+  return used;
+}
+
+export function readCommandSource(commandName) {
+  return readFileSync(modulePathFor(commandName), "utf8");
+}
+
+// Flags a command's `help` string documents: every `--flag` token in it.
+// The docs gate compares prose against this too, so help and reference
+// cannot drift apart from the declaration.
+export function scanHelpFlags(helpText) {
+  const out = new Set();
+  for (const m of String(helpText ?? "").matchAll(/--([a-z][a-z0-9-]*)/g)) out.add(m[1]);
+  return out;
+}
+
+function pathToUrl(p) {
+  return "file:///" + p.replace(/\\/g, "/");
+}

package/src/lib/fs-ops.js

@@ -1,3 +1,4 @@
+// @ts-check
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync, renameSync, unlinkSync, rmdirSync } from "node:fs";
 import path from "node:path";
 

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, []])),
     },
   };
 }