doctrina-cli 0.15.1 → 0.16.0

package/src/index.js

@@ -5,11 +5,11 @@ import { parseArgs } from "./lib/args.js";
 import { c } from "./lib/colors.js";
 import { suggest } from "./lib/suggest.js";
 import { cliVersion } from "./lib/version.js";
-import { surfaceHelp, OPERATIONS } from "./lib/commands.js";
+import { surfaceHelp, OPERATIONS, deprecationFor } from "./lib/commands.js";
 import { GLOBAL_FLAGS } from "./lib/flag-catalog.js";
 import { EXIT, exitCodeHelp } from "./lib/exit-codes.js";
-import { recordUsage } from "./lib/usage.js";
-import { wantsJson, emitJson, captureOutput, stripAnsi } from "./lib/json-out.js";
+import { recordUsage, operationOf } from "./lib/usage.js";
+import { wantsJson, emitJson, captureOutput, stripAnsi, setDeprecation, deferJson, flushJson } from "./lib/json-out.js";
 
 import * as init from "./commands/init.js";
 import * as spec from "./commands/spec.js";
@@ -48,6 +48,7 @@ import * as intent from "./commands/intent.js";
 import * as upgrade from "./commands/upgrade.js";
 import * as adapter from "./commands/adapter.js";
 import * as triage from "./commands/triage.js";
+import * as ci from "./commands/ci.js";
 
 const COMMANDS = {
   init, spec, change, decision, validate, hooks, analyze, clarify,
@@ -55,7 +56,7 @@ const COMMANDS = {
   intake, work, coverage, verify, contract, trace,
   status, close, review, watch, why, constitution,
   prime, handoff, show, doctor, report, completion,
-  intent, upgrade, adapter, triage,
+  intent, upgrade, adapter, triage, ci,
 };
 
 const TOP_HELP = `
@@ -127,18 +128,98 @@ async function main(argv) {
     return 0;
   }
 
+  // A flag the command does not declare is REFUSED, never ignored.
+  //
+  // Declaring the flags (C3) fixed the parser swallowing a positional; it
+  // did not make anything CHECK the declaration, so an unrecognised flag was
+  // simply dropped. On the same tree, `doctrina coverage --strict` exited 1
+  // and `doctrina coverage --stricts` exited 0: the gate the operator asked
+  // for never ran, and nothing said so. That is the most expensive failure a
+  // gate can have, because it is indistinguishable from success — a CI job
+  // with a typo in `--strict` stays green forever over a tree the gate would
+  // reject (change 0082).
+  //
+  // Usage error, not gate failure: exit 2 (ADR 0018). Checked after --help,
+  // so `doctrina <cmd> --typo --help` still explains the command instead of
+  // refusing to.
+  if (spec) {
+    const declared = new Set([
+      ...GLOBAL_FLAGS.boolean, ...GLOBAL_FLAGS.string,
+      ...(spec.boolean ?? []), ...(spec.string ?? []),
+    ]);
+    const undeclared = [...flags.keys()].filter((f) => !declared.has(f));
+    if (undeclared.length > 0) {
+      const lines = [];
+      for (const f of undeclared) {
+        lines.push(`error: unknown flag "--${f}" for \`doctrina ${commandName}\``);
+        console.error(c.red("error:") + ` unknown flag "--${f}" for \`doctrina ${commandName}\``);
+        const guess = suggest(f, [...declared]);
+        if (guess) {
+          lines.push(`hint: did you mean \`--${guess}\`?`);
+          console.error(c.gray("hint: ") + `did you mean \`--${guess}\`?`);
+        }
+      }
+      lines.push(`hint: \`doctrina ${commandName} --help\` lists the flags it accepts`);
+      console.error(c.gray("hint: ") + `\`doctrina ${commandName} --help\` lists the flags it accepts`);
+      // A consumer that asked for JSON gets JSON, including when the answer
+      // is "I refused" (third audit, finding 7). Change 0086 made the
+      // envelope tell the truth about the exit code; the flag check runs
+      // BEFORE the envelope exists, so a rejected invocation returned exit 2
+      // with an empty stdout and the consumer got a parse error instead of
+      // `{ok: false, exit_code: 2}`.
+      if (wantsJson(flags)) {
+        emitJson(operationName(positional), { stderr: lines },
+          { ok: false, exitCode: EXIT.USAGE, args: positional.slice(1) });
+      }
+      return EXIT.USAGE;
+    }
+  }
+
+  // A deprecated name keeps working and says so, once, before it runs
+  // (change 0049). On stderr, so a piped stdout stays exactly what it was —
+  // a warning that corrupts the output it warns about is a breaking change
+  // wearing a deprecation's clothes.
+  const deprecated = deprecationFor(positional);
+  if (deprecated) {
+    console.error(c.yellow("deprecated:") + ` this command is superseded — use ${c.cyan(deprecated.use)}`);
+    console.error(c.gray(`            ${deprecated.why}; the old name still works and will be removed in a later minor.`));
+    // And into the envelope, for the consumer that never sees a terminal
+    // (change 0061). The prose line above stays for the one that does.
+    setDeprecation({ use: deprecated.use, since: deprecated.since, why: deprecated.why });
+  }
+
   try {
     // --json on a command that builds no payload of its own still answers in
     // JSON: its output is captured into a versioned envelope beside `ok` and
     // `exit_code`. Branch on those; the lines are for completeness (M7).
-    if (wantsJson(flags) && !command.jsonNative) {
+    // A module with several subcommands is native for some and not others —
+    // `contract check` builds a real payload, `contract new` has nothing but
+    // its prose — so `jsonNative` may be a predicate over the subcommand's
+    // own arguments (change 0068).
+    const jsonNative = typeof command.jsonNative === "function"
+      ? command.jsonNative(positional.slice(1))
+      : command.jsonNative === true;
+    if (wantsJson(flags) && !jsonNative) {
       const { code, stdout, stderr } = await captureOutput(
         () => command.run(positional.slice(1), flags),
       );
-      emitJson([commandName, ...positional.slice(1)].join(" "), {
+      emitJson(operationName(positional), {
         stdout: stdout.map(stripAnsi),
         stderr: stderr.map(stripAnsi),
-      }, { ok: code === EXIT.OK, exitCode: code });
+      }, { ok: code === EXIT.OK, exitCode: code, args: operationArgs(positional) });
+      return code;
+    }
+    // The native path: hold the payload the command builds, run it, then
+    // write the envelope with the code it returned — so `ok` and `exit_code`
+    // say what the process says (change 0086).
+    if (wantsJson(flags)) {
+      deferJson();
+      let code = EXIT.OK;
+      try {
+        code = (await command.run(positional.slice(1), flags)) ?? EXIT.OK;
+      } finally {
+        flushJson(code);
+      }
       return code;
     }
     return await command.run(positional.slice(1), flags);
@@ -157,6 +238,24 @@ async function main(argv) {
   }
 }
 
+// The OPERATION an invocation names, and the arguments it carries — the two
+// halves the envelope's `command` field used to run together (third audit,
+// finding 6). `doctrina why carteira --json` answered `"command": "why
+// carteira"`, so a consumer reading that field got a different shape for
+// every capability, while `next --json` documents `command`/`args` as the
+// contract to branch on. The catalog is what tells a sub-operation
+// (`spec list`) from an argument (`why carteira`) — shape alone cannot,
+// which is the same reason `lib/usage.js` consults it.
+const KNOWN_OPERATIONS = new Set(OPERATIONS.map((o) => o[0]));
+
+function operationName(positional) {
+  return operationOf(positional, KNOWN_OPERATIONS) ?? positional[0] ?? "";
+}
+
+function operationArgs(positional) {
+  return positional.slice(operationName(positional).split(" ").length);
+}
+
 main(process.argv.slice(2)).then((code) => {
   // Record which operation ran, if and only if the operator asked for it
   // by setting DOCTRINA_USAGE_LOG (M8). Off by default, local file only,

package/src/lib/actions.js

@@ -0,0 +1,484 @@
+// @ts-check
+import path from "node:path";
+import { readdirSync } from "node:fs";
+import { isDir, isFile, read, relPath, walk } from "./fs-ops.js";
+import * as idx from "./index-json.js";
+import { deriveIndex, indexesMatch, listHeader, specHeader } from "./scan.js";
+import { collectRuntimeFindings } from "./runtime.js";
+import { FIX_SHAPED } from "./lexicon.js";
+import { summarize as coverageSummary } from "./coverage-model.js";
+import { summarize as traceSummary } from "./trace-model.js";
+
+// What comes next, as DATA (change 0032).
+//
+// This used to live in `commands/next.js` and return strings: the CLI
+// assembled `"doctrina change archive 0031 — applied but not archived"`
+// character by character, and then handed the agent a sentence to
+// re-interpret in order to re-issue the command it had just built. Even
+// `--json` returned that same prose inside quotes. Every other part of the
+// framework exists to keep a machine from having to read English; this was
+// the one place the deterministic chain leaked back into it.
+//
+// So an action is a record. `text` is the human rendering, built HERE from
+// the same fields, so the sentence and the structure can never disagree —
+// one builder owns both. A machine branches on `command`/`args`; a person
+// reads `text`; `next --run` executes the first `runnable` one.
+
+/**
+ * @typedef {object} Action
+ * @property {string} id        Stable slug for the KIND of action, not the instance.
+ * @property {string|null} command  The doctrina operation ("change archive"), or null
+ *                                  when the next step is authorship, not a command.
+ * @property {string[]} args
+ * @property {string} why       One line: why this is next.
+ * @property {string|null} gate The gate this action clears, when it clears one.
+ * @property {"blocking"|"advisory"} severity
+ * @property {boolean} runnable Whether `next --run` may execute it unattended.
+ * @property {string} text      The rendered line. Derived from the fields above.
+ */
+
+/**
+ * Build one action. `text` is derived unless the line needs a shape the
+ * default does not cover (a command embedded mid-sentence, a placeholder
+ * argument the caller must fill in).
+ *
+ * `runnable` defaults to FALSE and is opted into deliberately. An action is
+ * runnable only when running it unattended is both safe and the whole of
+ * what the action asks for. Anything that needs a human to DECIDE —
+ * accepting an ADR, writing a proposal, capturing a skill, ticking a box —
+ * is not runnable however mechanical the edit would be, because the edit is
+ * not the work.
+ *
+ * @param {Partial<Action> & { id: string, why: string }} spec
+ * @returns {Action}
+ */
+export function action(spec) {
+  const command = spec.command ?? null;
+  const args = spec.args ?? [];
+  return {
+    id: spec.id,
+    command,
+    args,
+    why: spec.why,
+    gate: spec.gate ?? null,
+    severity: spec.severity ?? "blocking",
+    runnable: spec.runnable ?? false,
+    text: spec.text ?? defaultText(command, args, spec.why),
+  };
+}
+
+/** The invocation a person would type, or null when there is no command. */
+export function invocation(a) {
+  if (!a.command) return null;
+  return `doctrina ${[a.command, ...a.args].join(" ")}`;
+}
+
+function defaultText(command, args, why) {
+  const cmd = command ? `doctrina ${[command, ...args].join(" ")}` : null;
+  return cmd ? `${cmd} — ${why}` : why;
+}
+
+/**
+ * The priority-ordered action list. Shared by `next`, `prime`, `handoff`
+ * and `watch`.
+ *
+ * `gates` is the already-collected gate state, passed in by `snapshot.js`
+ * so the whole read costs one collection (change 0037). Omitted — as `next`
+ * omits it — the collectors run here instead; the answer is the same either
+ * way, which is the point.
+ *
+ * @param {string} projectRoot
+ * @param {{ coverage?: any, trace?: any, verify?: any }} [gates]
+ * @returns {Action[]}
+ */
+export function computeActions(projectRoot, gates = {}) {
+  /** @type {Action[]} */
+  const actions = [];
+
+  // RUNTIME FIRST (change 0029). A declared wiring that does not hold is
+  // not a queue item — it is the reason the last run lied. After a job goes
+  // green having executed nothing, "open a change on the observability
+  // capability" sends the agent to polish the Markdown of an empty-state
+  // message while the cause sits in a file no other action names. A broken
+  // declaration outranks every artifact chore below it.
+  try {
+    const runtime = collectRuntimeFindings(projectRoot);
+    const errs = runtime.findings.filter((f) => f.level === "error");
+    if (errs.length > 0) {
+      actions.push(action({
+        id: "runtime-declarations",
+        command: "triage",
+        gate: "runtime",
+        runnable: true,
+        why:
+          `${errs.length} runtime declaration${errs.length === 1 ? " does" : "s do"} not hold ` +
+          `(first: ${errs[0].code} ${errs[0].message.slice(0, 80)}${errs[0].message.length > 80 ? "…" : ""})`,
+      }));
+    }
+  } catch {
+    // A malformed contract is `validate`'s finding to make, not a reason
+    // for `next` to fall over.
+  }
+
+  // A pending intake is the very first thing to resolve: until it is
+  // converted, product.md and the specs are still empty scaffolding.
+  const intakePath = path.join(projectRoot, ".doctrina", "intake.md");
+  const intakeExists = isFile(intakePath);
+  if (intakeExists) {
+    const status = (listHeader(read(intakePath), "Status") ?? "pending").toLowerCase();
+    if (status !== "converted") {
+      actions.push(action({
+        id: "intake-pending",
+        command: "intake",
+        runnable: true,
+        why: "a pending intake awaits conversion into product.md and specs",
+      }));
+    }
+  } else if (specCapabilities(projectRoot).length === 0) {
+    // And the state BEFORE that one, which had no action at all (second
+    // audit). `init` does not write an intake.md — deliberately: an empty
+    // pending intake would be a mould passing for content, which change 0065
+    // just made a refusable thing. So the condition that means "the specs are
+    // not written yet" is read from what IS on disk: no capability spec.
+    //
+    // Without this the bootstrap door was invisible at exactly the moment it
+    // was needed. The hub tells the agent to check a file `init` never
+    // creates, and `prime`, `next` and `doctor` named `intake` nowhere.
+    actions.push(action({
+      id: "bootstrap-unspecced",
+      command: "intake",
+      args: ["--text", '"<what this project is>"'],
+      severity: "blocking",
+      why: "no capability is specced yet, so nothing states what this project must do",
+      text: 'doctrina intake --text "<what this project is>" — no capability is specced yet; ' +
+        "for an existing codebase, `doctrina work --from-diff` backfills from the code instead",
+    }));
+  }
+
+  // Open changes drive the loop: finish what is started before opening more.
+  const changesDir = path.join(projectRoot, ".doctrina", "changes");
+  if (isDir(changesDir)) {
+    for (const id of readdirSync(changesDir).sort()) {
+      if (id === "archive" || id.startsWith(".")) continue;
+      if (!isDir(path.join(changesDir, id))) continue;
+      const proposalPath = path.join(changesDir, id, "proposal.md");
+      if (!isFile(proposalPath)) {
+        actions.push(action({
+          id: "change-missing-proposal",
+          why: `add a proposal.md to .doctrina/changes/${id}/ (open changes need one)`,
+        }));
+        continue;
+      }
+      const status = listHeader(read(proposalPath), "Status") ?? "proposed";
+      if (status === "applied") {
+        actions.push(action({
+          id: "change-archive-pending",
+          command: "change archive",
+          args: [id],
+          gate: "archive",
+          runnable: true,
+          why: "applied but not archived",
+        }));
+        continue;
+      }
+      const tasksPath = path.join(changesDir, id, "tasks.md");
+      const unchecked = isFile(tasksPath)
+        ? (read(tasksPath).match(/^-\s+\[ \]/gm) ?? []).length
+        : 0;
+      if (unchecked > 0) {
+        // Deliberately NOT runnable, and deliberately without a command:
+        // the only thing that clears this is doing the work. `change tick`
+        // would tick the box, which is the dishonesty every gate here
+        // exists to prevent.
+        actions.push(action({
+          id: "change-tasks-open",
+          why: `complete ${unchecked} open task${unchecked === 1 ? "" : "s"} in .doctrina/changes/${id}/tasks.md`,
+        }));
+        continue;
+      }
+      const deltas = walk(path.join(changesDir, id, "specs")).filter((p) => p.endsWith("delta.md"));
+      if (deltas.length > 0) {
+        actions.push(action({
+          id: "change-apply-ready",
+          command: "analyze",
+          args: [id],
+          gate: "structure",
+          runnable: true,
+          why: `tasks done, ${deltas.length} delta${deltas.length === 1 ? "" : "s"} ready`,
+          text: `doctrina analyze ${id}, then doctrina change apply ${id} — ` +
+            `tasks done, ${deltas.length} delta${deltas.length === 1 ? "" : "s"} ready`,
+        }));
+      } else {
+        actions.push(action({
+          id: "change-deltas-missing",
+          command: "change apply",
+          args: [id],
+          why: `add spec deltas under .doctrina/changes/${id}/specs/, or apply as metadata-only`,
+          text: `add spec deltas under .doctrina/changes/${id}/specs/, ` +
+            `or apply as metadata-only: doctrina change apply ${id}`,
+        }));
+      }
+    }
+  }
+
+  // ADRs stuck in proposed need a human decision; accepted-but-bare ADRs are
+  // the rot the review flagged — a decision with nothing behind it (no Evidence,
+  // no Landed) is drift waiting to be superseded. Surface the proposed ones
+  // first (a pending decision blocks more than a missing stamp).
+  const adrDir = path.join(projectRoot, ".doctrina", "decisions");
+  /** @type {Action[]} */
+  const landNudges = [];
+  const isBareValue = (v) => {
+    const t = (v ?? "").trim();
+    return t === "" || t === "—" || t === "-";
+  };
+  for (const f of walk(adrDir)) {
+    if (!f.endsWith(".md")) continue;
+    const m = path.basename(f).match(/^(\d{4})-/);
+    if (!m) continue;
+    const text = read(f);
+    const status = listHeader(text, "Status");
+    if (status && status.toLowerCase() === "proposed") {
+      // Accepting a decision is the human's call, not a step to automate:
+      // `runnable` stays false however mechanical the header edit is.
+      actions.push(action({
+        id: "adr-proposed",
+        command: "decision accept",
+        args: [m[1]],
+        why: `ADR ${m[1]} is still proposed`,
+        text: `review ADR ${m[1]} (${relPath(projectRoot, f)}): doctrina decision accept ${m[1]}, or supersede it`,
+      }));
+    } else if (status && status.toLowerCase() === "accepted") {
+      // Bare only when BOTH anchors are empty (Evidence header present-but-bare
+      // and no Landed stamp). An ADR that opts out of Evidence entirely
+      // (header absent) is not nagged.
+      const evidence = listHeader(text, "Evidence");
+      const landed = listHeader(text, "Landed");
+      if (evidence !== null && isBareValue(evidence) && isBareValue(landed)) {
+        landNudges.push(action({
+          id: "adr-unproven",
+          command: "decision land",
+          args: [m[1]],
+          severity: "advisory",
+          why: `nothing proves ADR ${m[1]}`,
+          text: `record what proves ADR ${m[1]}: cite its **Evidence:**, or once it ships, doctrina decision land ${m[1]}`,
+        }));
+      }
+    }
+  }
+  for (const n of landNudges) actions.push(n);
+
+  // No procedural memory captured yet, but the history shows a fix-shaped
+  // change — exactly the lesson a skill exists to keep from being relearned
+  // (review §5: the change-0003 "tolerate LLM code fences" case). One gentle
+  // nudge, only when skills are empty, so it never nags a project that opted in.
+  const skillNudge = suggestSkillCapture(projectRoot);
+  if (skillNudge) actions.push(skillNudge);
+
+  // GATE SIGNALS. `next` used to answer "no open work" over a tree where
+  // `doctor` reported five findings with a named remedy each: it knew the
+  // change/ADR/index/intake/runtime/skill lifecycle and nothing about whether
+  // the gates were satisfied. The command whose entire job is to answer "what
+  // now?" was the one that said "nothing" (second audit).
+  //
+  // Change 0037 unified the views so they could not disagree; this is that
+  // unification finally reaching `next`. Same collections, same numbers — the
+  // only difference is that a view REPORTS and an action RECOMMENDS.
+  // The gates measure capabilities, so they say nothing before any exists. A
+  // freshly initialised project must be told to run `intake`, not to write
+  // acceptance criteria for capabilities it has not named yet — three tidy
+  // recommendations ahead of the one that matters is the noise this whole
+  // change exists to remove.
+  const hasSpecs = specCapabilities(projectRoot).length > 0;
+
+  const cov = hasSpecs ? (gates.coverage ?? safely(() => coverageSummary(projectRoot))) : null;
+  if (cov) {
+    if (cov.totalDangling > 0) {
+      actions.push(action({
+        id: "coverage-dangling",
+        command: "coverage",
+        gate: "coverage",
+        why: `${cov.totalDangling} acceptance criterion(s) cite evidence missing on disk`,
+      }));
+    } else if (cov.totalCriteria === 0) {
+      actions.push(action({
+        id: "coverage-none",
+        command: null,
+        gate: "coverage",
+        severity: "advisory",
+        why: "no acceptance criteria declared yet — nothing proves any capability",
+        text: "write acceptance criteria with cited evidence — no capability is proven yet " +
+          "(`doctrina coverage` reports them once they exist)",
+      }));
+    }
+  }
+
+  const tr = hasSpecs ? (gates.trace ?? safely(() => traceSummary(projectRoot))) : null;
+  if (tr) {
+    if (tr.dropped > 0) {
+      actions.push(action({
+        id: "trace-dropped",
+        command: "trace",
+        gate: "trace",
+        why: `${tr.dropped} product intent anchor(s) are realized by no spec`,
+      }));
+    } else if (tr.anchors === 0) {
+      actions.push(action({
+        id: "trace-no-anchors",
+        command: null,
+        gate: "trace",
+        severity: "advisory",
+        why: "no intent anchors declared in product.md, so nothing traces to product intent",
+        text: 'tag product.md success criteria as "- [SC1] ..." and cite them with ' +
+          "**Realizes:** in each spec — nothing traces to product intent yet",
+      }));
+    }
+  }
+
+  // An active spec still `planned` with no note is an inventory claim: the
+  // document says the capability is current and the axis says nothing is built.
+  const inventoryClaims = activeButUnbuilt(projectRoot);
+  if (inventoryClaims.length > 0) {
+    actions.push(action({
+      id: "spec-inventory-claim",
+      command: "spec set",
+      args: [inventoryClaims[0], "--implementation", "auto"],
+      gate: "validate",
+      why: `${inventoryClaims.length} active spec(s) are still "planned" with no note ` +
+        `(${inventoryClaims.slice(0, 3).join(", ")})`,
+    }));
+  }
+
+  // The build gate undeclared is the quietest failure of all: `close` skips
+  // step 7 and every change ships without the project's own tests ever running.
+  const verify = hasSpecs ? (gates.verify ?? readVerifyState(projectRoot)) : { configured: true, invalid: false };
+  if (verify.invalid) {
+    actions.push(action({
+      id: "verify-invalid",
+      command: null,
+      gate: "verify",
+      why: ".doctrina/verify.json is not valid JSON, so the build gate cannot run",
+      text: "fix .doctrina/verify.json — it is not valid JSON, so `doctrina verify` " +
+        "and the close's build gate cannot run",
+    }));
+  } else if (!verify.configured) {
+    actions.push(action({
+      id: "verify-unconfigured",
+      command: "verify",
+      args: ["--init"],
+      gate: "verify",
+      // NOT runnable, though the command is one call: `verify --init` writes a
+      // fail-closed placeholder that a person still has to replace with the
+      // project's real commands, so running it unattended is not the whole of
+      // what the action asks for. Marking it runnable in change 0064 was a
+      // mistake — `next --run` picked it, found no runner registered, and
+      // errored where it should have said the next step needs a person.
+      why: "no .doctrina/verify.json — the close skips its build gate entirely",
+    }));
+  }
+
+  // Index drift is silent rot; surface it last.
+  try {
+    const current = idx.load(projectRoot);
+    if (!indexesMatch(deriveIndex(projectRoot, current), current)) {
+      actions.push(action({
+        id: "index-drift",
+        command: "index rebuild",
+        gate: "index",
+        runnable: true,
+        why: "index.json has drifted from the tree",
+      }));
+    }
+  } catch {
+    actions.push(action({
+      id: "index-unreadable",
+      command: "index rebuild",
+      gate: "index",
+      runnable: true,
+      why: "index.json is missing or unreadable",
+    }));
+  }
+
+  return actions;
+}
+
+// Return a single skill-capture nudge, or null. Fires only when no skill has
+// been written yet (skills/ holds nothing but .gitkeep) AND the archive shows a
+// fix-shaped change whose lesson is the textbook case for a skill. Deterministic
+// pattern match on the archived folder name — a hint, never a decision (ADR 0005).
+
+function suggestSkillCapture(projectRoot) {
+  const skillsDir = path.join(projectRoot, ".doctrina", "skills");
+  if (isDir(skillsDir)) {
+    const hasSkill = walk(skillsDir).some((f) => f.endsWith(".md"));
+    if (hasSkill) return null; // opted in already — never nag
+  }
+  const archiveDir = path.join(projectRoot, ".doctrina", "changes", "archive");
+  if (!isDir(archiveDir)) return null;
+  for (const name of readdirSync(archiveDir).sort()) {
+    if (!isDir(path.join(archiveDir, name))) continue;
+    const id = name.replace(/^\d{4}-\d{2}-\d{2}-/, "");
+    if (FIX_SHAPED.test(id)) {
+      return action({
+        id: "skill-capture",
+        command: "skill new",
+        args: ["<slug>"],
+        severity: "advisory",
+        why: "a past fix went uncaptured and no skill exists yet",
+        text: `capture a skill from past fixes (e.g. "${id}"): doctrina skill new <slug> — ` +
+          `on-demand procedural memory so the next agent does not relearn it (none exist yet)`,
+      });
+    }
+  }
+  return null;
+}
+
+// A collector that throws is a finding for `validate` to make, never a reason
+// for `next` to fall over — the same posture the runtime block above takes.
+function safely(fn) {
+  try {
+    return fn();
+  } catch {
+    return null;
+  }
+}
+
+// Whether the project declares its build gate. Deliberately the same three
+// states `doctor` reports — configured, absent, invalid — read the same way.
+function readVerifyState(projectRoot) {
+  const p = path.join(projectRoot, ".doctrina", "verify.json");
+  if (!isFile(p)) return { configured: false, invalid: false };
+  try {
+    const cfg = JSON.parse(read(p));
+    return { configured: Array.isArray(cfg?.checks) && cfg.checks.length > 0, invalid: false };
+  } catch {
+    return { configured: false, invalid: true };
+  }
+}
+
+// Active capability specs whose Implementation is still a bare "planned".
+// A note after the value ("planned — backend deferred to Q3") is the declared
+// gap and is left alone, exactly as `validate` leaves it alone.
+function specCapabilities(projectRoot) {
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  if (!isDir(specsDir)) return [];
+  return readdirSync(specsDir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && isFile(path.join(specsDir, e.name, "spec.md")))
+    .map((e) => e.name)
+    .sort();
+}
+
+function activeButUnbuilt(projectRoot) {
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  const out = [];
+  for (const cap of specCapabilities(projectRoot)) {
+    const entry = { name: cap };
+    const file = path.join(specsDir, entry.name, "spec.md");
+    const text = read(file);
+    const status = (specHeader(text, "Status") ?? "").toLowerCase();
+    const impl = (specHeader(text, "Implementation") ?? "").trim();
+    if (status !== "active") continue;
+    if (impl.toLowerCase() === "planned") out.push(entry.name);
+  }
+  return out.sort();
+}

package/src/lib/adapters.js

@@ -126,15 +126,4 @@ export function renderAdapterFile(file, tokens) {
   });
 }
 
-// Is this project-relative path one that some adapter owns? Used by
-// `adapter remove` so it deletes only what an adapter created, and by
-// `init` so it never counts adapter files as user content.
-export function isAdapterOwnedPath(projectRoot, relPathPosix) {
-  for (const name of listAdapterNames(projectRoot)) {
-    const spec = adapterFiles(projectRoot, name);
-    if (spec?.files.some((f) => f.relativePath === relPathPosix)) return true;
-  }
-  return false;
-}
-
 export { exists };

package/src/lib/adr-guard.js

@@ -12,6 +12,25 @@ import { listHeader } from "./scan.js";
 // (`decision supersede` / `decision new`) instead of drifting past it.
 // A word match on capability names — a hint, never a decision (ADR 0005),
 // and never a blocker (an ADR merely MENTIONING a capability is normal).
+/**
+ * How many ADRs on disk are accepted.
+ *
+ * The checkpoint prints "no accepted ADR cites the touched capabilities",
+ * which is conformance only when there ARE accepted ADRs to cite them. With
+ * none, the sentence is vacuously true and reads as a decision checked
+ * (change 0089), so the caller needs the count to tell the two apart.
+ */
+export function acceptedDecisionCount(projectRoot) {
+  const adrDir = path.join(projectRoot, ".doctrina", "decisions");
+  if (!isDir(adrDir)) return 0;
+  let n = 0;
+  for (const f of walk(adrDir)) {
+    if (!/^\d{4}-.*\.md$/.test(path.basename(f))) continue;
+    if ((listHeader(read(f), "Status") ?? "").toLowerCase() === "accepted") n += 1;
+  }
+  return n;
+}
+
 export function adrAdvisories(projectRoot, capabilities) {
   const adrDir = path.join(projectRoot, ".doctrina", "decisions");
   if (!isDir(adrDir) || capabilities.length === 0) return [];