doctrina-cli 0.12.0 → 0.14.0

package/src/commands/init.js

@@ -1,12 +1,18 @@
+// @ts-check
 import path from "node:path";
 import process from "node:process";
 import { exists, isDir, isFile, read, relPath, write } from "../lib/fs-ops.js";
 import { locateTemplatesDir, loadTemplateTree, materialiseEntry, substitute } from "../lib/templates.js";
+import {
+  surfaceBlock, findSurfaceBlock, agentChangelogBlock, findAgentChangelogBlock,
+} from "../lib/commands.js";
+import * as idx from "../lib/index-json.js";
 import { today } from "../lib/dates.js";
 import { cliVersion } from "../lib/version.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
-import { ask } from "../lib/prompt.js";
+import { EXIT } from "../lib/exit-codes.js";
+import { ask, isInteractive } from "../lib/prompt.js";
 import { writeIntakeFile, printBootstrapPlaybook, warnIfThinIntake } from "./intake.js";
 
 const SUPPORTED_AGENTS = [
@@ -24,6 +30,11 @@ const SUPPORTED_AGENTS = [
   "jules",
 ];
 
+export const flags = {
+  boolean: ["json", "force", "non-interactive", "overwrite-content"],
+  string: ["project-name", "project-description", "agent", "intake", "from", "date"],
+};
+
 export async function run(_positional, flags) {
   const force = flagBool(flags, "force", false);
   const nonInteractive = flagBool(flags, "non-interactive", false);
@@ -52,8 +63,21 @@ export async function run(_positional, flags) {
   if (!description && intakeBody) {
     description = firstLineSummary(intakeBody);
   }
+  // The description prompt used to run unconditionally, without the
+  // isTTY check the adapter prompt already had. A non-interactive caller
+  // that forgot --non-interactive read EOF, got an empty answer, and
+  // scaffolded a project with a blank description — silently (C9).
   if (!description && !nonInteractive) {
-    description = await ask("One-sentence project description:");
+    if (isInteractive()) {
+      description = await ask("One-sentence project description:");
+    }
+    if (!description) {
+      console.error(c.red("error:") + " no project description given and no terminal to ask on");
+      console.error(c.gray("hint: ") +
+        "pass --project-description \"<text>\" (or --intake <file>); " +
+        "--non-interactive alone still needs one of those");
+      return EXIT.USAGE;
+    }
   }
 
   let agentSelector = flagString(flags, "agent");
@@ -61,7 +85,7 @@ export async function run(_positional, flags) {
   // terminal, offer the adapter install instead of silently skipping it —
   // first-run users rarely know the flag exists. Never fires in pipes/CI
   // (no TTY) or under --non-interactive, so scripted init is unchanged.
-  if (agentSelector === undefined && !nonInteractive && process.stdin.isTTY && process.stdout.isTTY) {
+  if (agentSelector === undefined && !nonInteractive && isInteractive()) {
     const answer = await ask(
       `Install an agent adapter? (${SUPPORTED_AGENTS.join("/")}/all/none)`,
       { defaultValue: "none" },
@@ -74,7 +98,9 @@ export async function run(_positional, flags) {
 
   if (!force && (exists(agentsMdPath) || exists(doctrinaDir))) {
     console.error(c.red("error:") + " AGENTS.md or .doctrina/ already exists at this path");
-    console.error(c.gray("hint: ") + "pass --force to overwrite");
+    console.error(c.gray("hint: ") +
+      "to add an agent adapter use `doctrina adapter add <name>` (additive); " +
+      "to re-scaffold, pass --force");
     return 1;
   }
 
@@ -108,10 +134,46 @@ export async function run(_positional, flags) {
     FRAMEWORK_VERSION: cliVersion(),
   };
 
-  // Root AGENTS.md — with optional --from base content prepended.
+  // Root AGENTS.md — with optional --from base content prepended. The
+  // doctrina:surface block is regenerated from the installed catalog at init
+  // time, so a freshly scaffolded hub can never document a stale surface even
+  // if the static template lags a release (ADR 0015).
   const agentsTemplatePath = path.join(templatesDir, "AGENTS.md.template");
   const agentsTemplateBody = read(agentsTemplatePath);
-  const projectAgents = substitute(agentsTemplateBody, tokens);
+  const projectAgents = refreshSurfaceBlock(substitute(agentsTemplateBody, tokens));
+
+  // --force used to mean "overwrite everything", which made it a content
+  // shredder: the only way to add an adapter to an existing project was
+  // `init --agent X --force`, and that replaced AGENTS.md and product.md
+  // with blank templates — every hand-authored rule and the whole product
+  // definition, gone, exit 0, no warning (audit item C1).
+  //
+  // --force now re-scaffolds only what is still pristine. Overwriting
+  // AUTHORED content takes a second, explicit opt-in, because no flag whose
+  // documented meaning is "overwrite existing files" should be able to
+  // destroy the two documents the framework calls its sources of truth.
+  const overwriteContent = flagBool(flags, "overwrite-content", false);
+  if (force && !overwriteContent) {
+    const productTemplate = loadProductTemplate(templatesDir);
+    const authored = [];
+    if (isFile(agentsMdPath) && isAuthored(read(agentsMdPath), agentsTemplateBody)) {
+      authored.push("AGENTS.md");
+    }
+    const productPath = path.join(doctrinaDir, "product.md");
+    if (productTemplate !== null && isFile(productPath) && isAuthored(read(productPath), productTemplate)) {
+      authored.push(".doctrina/product.md");
+    }
+    if (authored.length > 0) {
+      console.error(c.red("error:") + " --force would overwrite content you wrote:");
+      for (const f of authored) console.error(`  - ${f}`);
+      console.error("");
+      console.error(c.gray("hint: ") + "to add an agent adapter, use the additive command instead:");
+      console.error(`    ${c.cyan("doctrina adapter add <name>")}`);
+      console.error(c.gray("If you really mean to discard the content above, re-run with ") +
+        c.cyan("--overwrite-content") + c.gray("."));
+      return 1;
+    }
+  }
   const finalAgents = fromAgentsContent
     ? fromAgentsContent.replace(/\n+$/, "") + "\n\n---\n\n## Project-specific\n\n" + projectAgents
     : projectAgents;
@@ -136,6 +198,18 @@ export async function run(_positional, flags) {
       console.log(c.green("created") + ` ${relPath(projectRoot, dest)} (with --from base)`);
       continue;
     }
+    // index.json is written from the ONE schema definition
+    // (`lib/index-json.js`), not from a template that could drift from it.
+    // A template copy is how a project came to be born already needing a
+    // scaffold update: `contracts` was added to what `templates check`
+    // requires and not to what `init` wrote (audit item C5).
+    if (entry.relativePath === "index.json.template") {
+      const dest = path.join(doctrinaDir, "index.json");
+      const fresh = idx.blank(projectName, date);
+      write(dest, JSON.stringify(fresh, null, 2) + "\n", { force });
+      console.log(c.green("created") + ` ${relPath(projectRoot, dest)}`);
+      continue;
+    }
     const written = materialiseEntry(entry, doctrinaDir, tokens, { force });
     console.log(c.green("created") + ` ${relPath(projectRoot, written)}`);
   }
@@ -178,6 +252,78 @@ export async function run(_positional, flags) {
   return 0;
 }
 
+// The RAW product.md template (tokens unsubstituted), or null when it
+// cannot be located — in which case the authored check errs toward
+// refusing nothing rather than guessing.
+function loadProductTemplate(templatesDir) {
+  const p = path.join(templatesDir, "doctrina", "product.md.template");
+  if (!isFile(p)) return null;
+  return read(p);
+}
+
+// Does this file carry content someone wrote, as opposed to the pristine
+// scaffold?
+//
+// Compared by SHAPE against the raw template, not against a rendered copy:
+// a re-init under a different --project-name substitutes different values
+// into the same scaffold, and comparing rendered text would read that as
+// authorship and refuse a legitimate re-scaffold. Each `{{TOKEN}}` becomes
+// a wildcard, so any project name matches while any added prose does not.
+// Volatile and CLI-owned regions are dropped from both sides first: the
+// date line changes on its own and the doctrina:surface block is
+// regenerated by `upgrade`, so neither is evidence of authorship.
+function isAuthored(existing, rawTemplate) {
+  const body = normaliseScaffold(existing);
+  const shape = normaliseScaffold(rawTemplate)
+    .split(/\{\{[A-Z0-9_]+\}\}/)
+    .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+    .join("[\\s\\S]*?");
+  return !new RegExp(`^${shape}$`).test(body);
+}
+
+function normaliseScaffold(text) {
+  return text
+    .replace(/\r\n/g, "\n")
+    // Both CLI-owned blocks are generated, not authored: the surface block
+    // is regenerated by `upgrade`, and the changed block is version-specific
+    // and written at init. Neither is evidence that a human touched the file.
+    .replace(/<!--\s*doctrina:surface:begin[\s\S]*?doctrina:surface:end\s*-->/g, "")
+    .replace(/<!--\s*doctrina:changed:begin[\s\S]*?doctrina:changed:end\s*-->/g, "")
+    .split("\n")
+    .filter((line) => !/^\*\*Last updated:\*\*|^-\s+\*\*Date:\*\*/.test(line.trim()))
+    .map((line) => line.replace(/\s+$/, ""))
+    .join("\n")
+    // Removing a generated block leaves the blank lines that surrounded it,
+    // and how many depends on where it was inserted. Collapse runs so the
+    // shape comparison is about CONTENT, not about spacing the CLI itself
+    // produced.
+    .replace(/\n{2,}/g, "\n\n")
+    .trim();
+}
+
+// Replace the template's doctrina:surface span with the one generated from
+// the running CLI's catalog; pass the text through untouched when the
+// template carries no markers (older custom templates).
+function refreshSurfaceBlock(text) {
+  const block = findSurfaceBlock(text);
+  if (!block) return text;
+  let out = text.slice(0, block.start) + surfaceBlock() + text.slice(block.end);
+
+  // The agent-facing changelog is version-specific, so it is GENERATED at
+  // init like the surface block — not carried in the template. Writing it
+  // here is what keeps a fresh project from being born already needing a
+  // `templates update`, the same invariant C5 established for index.json.
+  const changed = agentChangelogBlock(cliVersion());
+  const existing = findAgentChangelogBlock(out);
+  if (existing) {
+    out = out.slice(0, existing.start) + changed + out.slice(existing.end);
+  } else if (changed) {
+    const sb = findSurfaceBlock(out);
+    if (sb) out = out.slice(0, sb.end) + "\n\n" + changed + out.slice(sb.end);
+  }
+  return out;
+}
+
 // First non-empty line of the intake, stripped of Markdown heading marks
 // and clipped, as the one-line description token for the templates.
 function firstLineSummary(text) {

package/src/commands/intake.js

@@ -1,3 +1,4 @@
+// @ts-check
 import path from "node:path";
 import process from "node:process";
 import { exists, isFile, read, relPath, write } from "../lib/fs-ops.js";
@@ -7,6 +8,7 @@ import * as idx from "../lib/index-json.js";
 import { today } from "../lib/dates.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
+import { EXIT, notADoctrinaProject } from "../lib/exit-codes.js";
 
 // `intake` is the first half of the no-ceremony path (ADR 0005): store the
 // user's FULL project description verbatim, then print the bootstrap
@@ -14,10 +16,15 @@ import { c } from "../lib/colors.js";
 // and capability specs. The CLI does no interpretation — it scaffolds and
 // instructs; the agent thinks.
 
+// 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: ["text"] };
+
 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 force = flagBool(flags, "force", false);
@@ -30,7 +37,9 @@ export async function run(positional, flags) {
     if (!isFile(intakePath)) {
       console.error(c.red("error:") + " no intake found and no description given");
       console.error(c.gray("hint: ") + "run `doctrina intake <file>` or `doctrina intake --text \"<description>\"`");
-      return 1;
+      // PRECONDITION: nothing is wrong with the work; the project has no
+      // intake yet. The remedy is a setup command, not another attempt.
+      return EXIT.PRECONDITION;
     }
     const status = (listHeader(read(intakePath), "Status") ?? "pending").toLowerCase();
     if (status === "converted") {

package/src/commands/intent.js

@@ -1,8 +1,10 @@
+// @ts-check
 import path from "node:path";
 import process from "node:process";
 import { exists, isFile, read, relPath, write } from "../lib/fs-ops.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
+import { notADoctrinaProject } from "../lib/exit-codes.js";
 
 // Post-intake intent evolution (0.11.0 field review item 8). The intake is
 // converted once; capabilities born later — brainstorms, pivots, new asks —
@@ -17,6 +19,11 @@ import { suggest } from "../lib/suggest.js";
 
 const SUBCOMMANDS = ["add", "list"];
 
+// 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 sub = positional[0];
   if (!SUBCOMMANDS.includes(sub)) {
@@ -29,7 +36,7 @@ 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();
   }
   if (sub === "list") return intentList(projectRoot);
   return intentAdd(projectRoot, positional.slice(1).join(" ").trim());

package/src/commands/metrics.js

@@ -1,11 +1,17 @@
+// @ts-check
 import path from "node:path";
 import process from "node:process";
 import { spawnSync } from "node:child_process";
 import { readdirSync } from "node:fs";
-import { exists, isDir, read, relPath, write } from "../lib/fs-ops.js";
+import { exists, isDir, isFile, read, relPath, write } from "../lib/fs-ops.js";
 import { today } from "../lib/dates.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
+import { EXIT } from "../lib/exit-codes.js";
+import { GIT_STATE, historyState } from "../lib/git.js";
+import { notADoctrinaProject } from "../lib/exit-codes.js";
+import { USAGE_ENV, summarise } from "../lib/usage.js";
+import { OPERATIONS } from "../lib/commands.js";
 
 // Local-only adoption metrics derived from git history. No network calls,
 // no telemetry: the numbers stay in the repository, versioned like any
@@ -13,15 +19,36 @@ import { c } from "../lib/colors.js";
 
 const REEDIT_WINDOW_DAYS = 21;
 
+// 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", "save", "commands"], string: ["since"] };
+
 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();
   }
+  // --commands reads the usage log rather than git history: which parts of
+  // the command surface are actually reached for (M8). Separate report,
+  // separate source, so it never dilutes the adoption metrics.
+  if (flagBool(flags, "commands", false)) return commandUsage();
   const probe = git(projectRoot, ["rev-parse", "--is-inside-work-tree"]);
-  if (probe.status !== 0) {
-    console.error(c.red("error:") + " not a git repository (metrics are derived from local git history)");
-    return 1;
+  // "No history yet" is a VALID state, not a failure — a brand-new project
+  // is the most common state in which someone explores this command, and it
+  // used to answer with a raw git plumbing error (C8). git missing entirely
+  // is the one genuine ENVIRONMENT condition here.
+  const history = historyState(projectRoot);
+  if (!history.usable) {
+    if (history.state === GIT_STATE.ABSENT) {
+      console.error(c.red("error:") + ` ${history.reason} — metrics are derived from local git history`);
+      return EXIT.ENVIRONMENT;
+    }
+    console.log(c.bold("Doctrina metrics") + c.gray(" (local git history)"));
+    console.log("");
+    console.log(c.gray(`no history to measure yet — ${history.reason}.`));
+    console.log(c.gray("Commit some work and run this again."));
+    return EXIT.OK;
   }
 
   const sinceRaw = flagString(flags, "since", "90");
@@ -34,7 +61,7 @@ export async function run(_positional, flags) {
   ]);
   if (log.status !== 0) {
     console.error(c.red("error:") + ` git log failed: ${log.stderr.trim()}`);
-    return 1;
+    return EXIT.ENVIRONMENT;
   }
 
   const commits = parseLog(log.stdout);
@@ -171,14 +198,60 @@ function pct(x) {
   return `${(x * 100).toFixed(1)}%`;
 }
 
+// Which operations were actually invoked, from the opt-in usage log. The
+// surface is 36 commands and 59 operations; the audit's charge is that some
+// exist because they were easy to add rather than because anyone reaches for
+// them. This is the evidence for that argument — or against it. Zero samples
+// is a CANDIDATE for cutting, never a verdict: a command used once a quarter
+// and a command nobody wants look identical over one week.
+function commandUsage() {
+  const target = process.env[USAGE_ENV];
+  if (!target) {
+    console.log(c.bold("Command usage") + c.gray(" — not recording"));
+    console.log("");
+    console.log(c.gray("Instrumentation is off unless you ask for it. To start a sample:"));
+    console.log("  " + c.cyan(`export ${USAGE_ENV}=$PWD/.doctrina/usage.jsonl`));
+    console.log("");
+    console.log(c.gray("One local append-only file. The operation only — never arguments,"));
+    console.log(c.gray("paths, ids or prompts. No network calls, here or anywhere in the CLI."));
+    console.log(c.gray("Run three real changes through it, then come back."));
+    return 0;
+  }
+  if (!isFile(target)) {
+    console.log(c.bold("Command usage") + c.gray(` — ${USAGE_ENV} set, no samples yet`));
+    return 0;
+  }
+  const catalog = OPERATIONS.map((o) => o[0]);
+  const { samples, used, unused } = summarise(read(target), catalog);
+  console.log(c.bold("Command usage") + c.gray(` — ${samples} invocation${samples === 1 ? "" : "s"} recorded`));
+  console.log("");
+  for (const [op, n] of used) {
+    console.log(`  ${String(n).padStart(5)}  ${c.cyan(op)}`);
+  }
+  console.log("");
+  console.log(c.gray(`${unused.length} of ${catalog.length} operations never invoked in this sample:`));
+  for (let i = 0; i < unused.length; i += 4) {
+    console.log("  " + c.gray(unused.slice(i, i + 4).map((o) => o.padEnd(22)).join("")));
+  }
+  console.log("");
+  console.log(c.gray("Never-invoked is a question, not an answer. Before cutting one, ask"));
+  console.log(c.gray("whether it went unused because nobody wants it or because nobody"));
+  console.log(c.gray("could find it — the second is what AGENTS.md discovery fixed in 0.13."));
+  return 0;
+}
+
 export const help = `
-Usage: doctrina metrics [--since <days|date>] [--save]
+Usage: doctrina metrics [--since <days|date>] [--save] [--commands]
 
 Derive adoption metrics from LOCAL git history: commit count, revert
 count and rate, Conventional-Commit fix share, top-churn files, and a
 ${REEDIT_WINDOW_DAYS}-day re-edit proxy rate. No network calls; nothing leaves the repo.
 
 Flags:
+  --commands         Report which operations were actually invoked, from the
+                     opt-in usage log. Recording is OFF unless DOCTRINA_USAGE_LOG
+                     names a file; only the operation is recorded, never
+                     arguments, and nothing leaves the machine.
   --since <n|date>   Window: a day count (default 90) or any git-parseable
                      date ("2026-01-01", "3 months ago").
   --save             Write .doctrina/metrics/YYYY-MM-DD.json and print the

package/src/commands/next.js

@@ -1,3 +1,4 @@
+// @ts-check
 import path from "node:path";
 import process from "node:process";
 import { readdirSync } from "node:fs";
@@ -6,20 +7,31 @@ import * as idx from "../lib/index-json.js";
 import { deriveIndex, indexesMatch, listHeader } from "../lib/scan.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
+import { emitJson } from "../lib/json-out.js";
+
+// 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).
+// This command builds its own JSON payload; the entrypoint must not
+// wrap it in the generic envelope.
+export const jsonNative = true;
+
+export const flags = { boolean: ["json"], string: [] };
 
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
   const json = flagBool(flags, "json", false);
   if (!exists(path.join(projectRoot, ".doctrina"))) {
     const first = "doctrina init — this directory is not a Doctrina project yet";
-    console.log(json ? JSON.stringify({ actions: [first] }, null, 2) : `1. ${first}`);
+    if (json) emitJson("next", { actions: [first] });
+    else console.log(`1. ${first}`);
     return 0;
   }
 
   const actions = computeActions(projectRoot);
 
   if (json) {
-    console.log(JSON.stringify({ actions }, null, 2));
+    emitJson("next", { actions });
     return 0;
   }
 

package/src/commands/prime.js

@@ -1,3 +1,4 @@
+// @ts-check
 import path from "node:path";
 import process from "node:process";
 import { readdirSync } from "node:fs";
@@ -7,6 +8,7 @@ import { collectStatus } from "./status.js";
 import { computeActions } from "./next.js";
 import { acceptedDecisions, productSection } from "./constitution.js";
 import { c } from "../lib/colors.js";
+import { notADoctrinaProject } from "../lib/exit-codes.js";
 
 // Session primer: the ~40-line read that orients an agent at the start of a
 // session — where things stand, what the standing rules are, what work is
@@ -15,10 +17,15 @@ import { c } from "../lib/colors.js";
 // enough to act, cheap enough to run every session. Strictly read-only; every
 // line is assembled from artifacts that already own the fact (no new home).
 
+// 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 s = collectStatus(projectRoot);

package/src/commands/report.js

@@ -1,3 +1,4 @@
+// @ts-check
 import path from "node:path";
 import process from "node:process";
 import { spawnSync } from "node:child_process";
@@ -8,15 +9,21 @@ import { openChanges } from "./prime.js";
 import { flagString } from "../lib/args.js";
 import { today } from "../lib/dates.js";
 import { c } from "../lib/colors.js";
+import { notADoctrinaProject } from "../lib/exit-codes.js";
 
 // Periodic digest in Markdown — the standup/PR-description view: what was
 // archived, where the gates stand, and what local git says about the period.
 // Read-only, no network; the git section degrades silently outside a repo.
 
+// 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: ["since"] };
+
 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 sinceRaw = flagString(flags, "since") ?? "7";

package/src/commands/review.js

@@ -1,3 +1,4 @@
+// @ts-check
 import path from "node:path";
 import process from "node:process";
 import { spawnSync } from "node:child_process";
@@ -7,6 +8,7 @@ import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { rankCapabilitiesByDiff } from "./work.js";
 import { parseDependsOn } from "../lib/scan.js";
+import { notADoctrinaProject } from "../lib/exit-codes.js";
 import { summarize as coverageSummary } from "./coverage.js";
 import { summarize as traceSummary } from "./trace.js";
 
@@ -20,10 +22,15 @@ import { summarize as traceSummary } from "./trace.js";
 // ceiling as `trace`/`clarify` (ADR 0005). Read-only; exits 0 as a report, 1
 // under --strict when any break exists (CI gate).
 
+// 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", "strict"], string: ["diff"] };
+
 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 strict = flagBool(flags, "strict", false);
   const against = flagString(flags, "diff"); // optional git ref to diff against

package/src/commands/search.js

@@ -1,8 +1,10 @@
+// @ts-check
 import path from "node:path";
 import process from "node:process";
 import { exists, isDir, read, relPath, walk } from "../lib/fs-ops.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
+import { notADoctrinaProject } from "../lib/exit-codes.js";
 
 // Category-aware full-text search across the artifact tree. Answers
 // "where is X specified / decided / proposed?" without knowing the
@@ -17,6 +19,11 @@ import { c } from "../lib/colors.js";
 
 const MAX_MATCHES_PER_FILE = 5;
 
+// 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", "archive"], string: [] };
+
 export async function run(positional, flags) {
   const terms = positional.map((t) => t.toLowerCase()).filter(Boolean);
   if (terms.length === 0) {
@@ -27,7 +34,7 @@ export async function run(positional, flags) {
   const includeArchive = flagBool(flags, "archive", false);
   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 categories = [

package/src/commands/show.js

@@ -1,3 +1,4 @@
+// @ts-check
 import path from "node:path";
 import process from "node:process";
 import { readdirSync } from "node:fs";
@@ -5,6 +6,7 @@ import { exists, isDir, isFile, read, relPath } from "../lib/fs-ops.js";
 import { parseAcceptanceCriteria } from "../lib/criteria.js";
 import { suggest } from "../lib/suggest.js";
 import { c } from "../lib/colors.js";
+import { notADoctrinaProject } from "../lib/exit-codes.js";
 
 // Point reads. An agent that needs ONE requirement re-reads a whole spec —
 // hundreds of lines for a two-line fact. `show` resolves a compact reference
@@ -20,11 +22,16 @@ import { c } from "../lib/colors.js";
 // conversation, not as immutable identifiers. C-refs use the criteria's own
 // explicit numbers and are as stable as the spec keeps them.
 
+// 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 ref = positional[0];
   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();
   }
   if (!ref) {
     console.error(c.red("error:") + " show requires a reference");