doctrina-cli 0.13.0 → 0.15.0

package/src/commands/verify.js

@@ -1,3 +1,4 @@
+// @ts-check
 import path from "node:path";
 import process from "node:process";
 import { readdirSync } from "node:fs";
@@ -6,6 +7,7 @@ import { exists, isDir, isFile, read, write, relPath } from "../lib/fs-ops.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { today } from "../lib/dates.js";
 import { c } from "../lib/colors.js";
+import { EXIT, notADoctrinaProject } from "../lib/exit-codes.js";
 
 // The build/verify gate `validate` is not. `validate` checks the shape of
 // the artifact tree; it never runs the project, so a repo that does not
@@ -23,16 +25,24 @@ const STARTER = {
     "doctrina verify runs each check below, in order, through your shell. " +
     "Replace the example with your real typecheck/test/build commands. A " +
     "non-zero exit fails the gate. This file is the project's executable " +
-    "definition of 'the code actually works'.",
+    "definition of 'the code actually works'. A check may add an \"expect\" " +
+    "block — {\"fail_if_output_matches\": \"<regex>\"} and/or " +
+    "{\"require_output_matches\": \"<regex>\"} — so that a run which exits 0 " +
+    "having executed NOTHING fails the gate instead of passing it.",
   checks: [
     { name: "example", run: "exit 1" },
   ],
 };
 
+// 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", "clean", "force", "init", "list", "strict"], string: ["signoff"] };
+
 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();
   }
 
   // --clean is the reproducibility lint (review G4): `verify` runs the
@@ -66,7 +76,10 @@ export async function run(_positional, flags) {
     // the false confidence this command exists to prevent. Fail loudly.
     console.error(c.red("error:") + ` no ${CONFIG_REL} — nothing to verify`);
     console.error(c.gray("hint: ") + "scaffold one with `doctrina verify --init`, then declare your typecheck/test/build commands");
-    return 1;
+    // PRECONDITION, not a gate failure: the work may be perfect; this
+    // project has simply never declared a build gate. An agent reading
+    // exit 1 would iterate on the code forever (C7).
+    return EXIT.PRECONDITION;
   }
 
   let config;
@@ -89,6 +102,15 @@ export async function run(_positional, flags) {
       console.error(c.red("error:") + ` every check in ${CONFIG_REL} needs a non-empty "run" string (or "type": "manual")`);
       return 1;
     }
+    // An uncompilable expectation must fail LOUDLY at config time. Skipping
+    // it would leave a check that looks fail-closed and is not — the
+    // failure mode this whole feature exists to remove.
+    try {
+      parseExpectation(ch);
+    } catch (err) {
+      console.error(c.red("error:") + ` check "${ch.name ?? "?"}" declares an "expect" pattern that is not a valid regular expression: ${err.message}`);
+      return EXIT.USAGE;
+    }
   }
   if (checks.length === 0) {
     console.error(c.red("error:") + ` ${CONFIG_REL} declares zero checks — a verify gate with no checks proves nothing`);
@@ -131,6 +153,15 @@ export async function run(_positional, flags) {
     checks.forEach((ch, i) => {
       const what = ch.type === "manual" ? c.gray(`manual${ch.rubric ? " — " + ch.rubric : ""}`) : c.gray(ch.run);
       console.log(`  ${i + 1}. ${c.cyan((ch.name ?? "check").padEnd(16))} ${what}`);
+      // A fail-closed check must be visible as one: a reader auditing the
+      // gate needs to see which checks judge their own output.
+      const exp = parseExpectation(ch);
+      if (exp) {
+        const parts = [];
+        if (exp.failIfSource) parts.push(`fail if output matches /${exp.failIfSource}/`);
+        if (exp.requireSource) parts.push(`require output matches /${exp.requireSource}/`);
+        console.log(`     ${" ".repeat(16)} ${c.gray(parts.join("; "))}`);
+      }
     });
     return 0;
   }
@@ -167,14 +198,46 @@ export async function run(_positional, flags) {
     // monorepo target a sub-package, e.g. { run: "node --test", cwd:
     // "packages/api" } — the multi-service shape the contract artifact
     // also serves.
+    // A check that declares OUTPUT EXPECTATIONS must have its output read,
+    // so it runs piped and is echoed straight through — the operator still
+    // sees everything, just at the end of the check rather than streaming.
+    // Only checks that opt in pay that cost.
+    const expectation = parseExpectation(ch);
     const res = spawnSync(ch.run, {
       cwd: ch.cwd ? path.resolve(projectRoot, ch.cwd) : projectRoot,
       shell: true,
-      stdio: "inherit",
+      stdio: expectation ? "pipe" : "inherit",
+      encoding: expectation ? "utf8" : undefined,
+      // A suite's output can be large; the default 1MB cap would truncate
+      // the very line an expectation is looking for.
+      maxBuffer: expectation ? 64 * 1024 * 1024 : undefined,
     });
-    const ok = !res.error && res.status === 0;
+    if (expectation) {
+      if (res.stdout) process.stdout.write(res.stdout);
+      if (res.stderr) process.stderr.write(res.stderr);
+    }
+
+    let ok = !res.error && res.status === 0;
+    /** @type {string | null} */
+    let expectationNote = null;
+    if (ok && expectation) {
+      // THE FAIL-CLOSED RULE. A green exit code answers "did the runner
+      // crash", never "did the runner do anything". A suite whose filter
+      // matched nothing prints "0 scenarios" and exits 0, and every gate
+      // above this one calls that a pass. An expectation makes the run's
+      // own output part of the verdict.
+      const output = `${res.stdout ?? ""}\n${res.stderr ?? ""}`;
+      const verdict = judgeOutput(expectation, output);
+      if (!verdict.ok) {
+        ok = false;
+        expectationNote = verdict.reason;
+      }
+    }
+
     if (res.error) {
       console.log(c.red(`✗ ${name}`) + c.gray(` — could not run: ${res.error.message}`));
+    } else if (expectationNote) {
+      console.log(c.red(`✗ ${name}`) + c.gray(` — exit 0, but ${expectationNote}`));
     } else {
       console.log(ok ? c.green(`✓ ${name}`) : c.red(`✗ ${name} (exit ${res.status})`));
     }
@@ -203,6 +266,47 @@ export async function run(_positional, flags) {
   return 1;
 }
 
+// An `expect` block, normalised and compiled, or null when the check does
+// not declare one. Runner-agnostic by construction: Doctrina supplies no
+// patterns of its own and knows nothing about what the output means — the
+// project declares the line that proves its run was real.
+//
+//   "expect": {
+//     "fail_if_output_matches": "0 scenarios|0 features",
+//     "require_output_matches": "\\d+ scenarios? passed"
+//   }
+export function parseExpectation(check) {
+  const raw = check?.expect;
+  if (!raw || typeof raw !== "object") return null;
+  const out = {};
+  if (typeof raw.fail_if_output_matches === "string" && raw.fail_if_output_matches !== "") {
+    out.failIf = new RegExp(raw.fail_if_output_matches, "im");
+    out.failIfSource = raw.fail_if_output_matches;
+  }
+  if (typeof raw.require_output_matches === "string" && raw.require_output_matches !== "") {
+    out.requireMatch = new RegExp(raw.require_output_matches, "im");
+    out.requireSource = raw.require_output_matches;
+  }
+  return out.failIf || out.requireMatch ? out : null;
+}
+
+/** @returns {{ok: boolean, reason?: string}} */
+export function judgeOutput(expectation, output) {
+  if (expectation.failIf && expectation.failIf.test(output)) {
+    return {
+      ok: false,
+      reason: `its output matched /${expectation.failIfSource}/ — the check declares that shape a failure (a run that executed nothing exits 0 too)`,
+    };
+  }
+  if (expectation.requireMatch && !expectation.requireMatch.test(output)) {
+    return {
+      ok: false,
+      reason: `its output never matched /${expectation.requireSource}/ — the check requires that proof of a real run`,
+    };
+  }
+  return { ok: true };
+}
+
 // Static reproducibility lint: walk the project's package.json files and
 // report the two "works on my machine" footguns the review hit — a package
 // whose entry points live in a build-output dir with nothing that builds it
@@ -360,6 +464,23 @@ A manual check passes when it has been signed off and is otherwise reported
 as "pending" — non-blocking by default, failing only under --strict (so CI
 can require the sign-off). Sign-offs are stored in ${SIGNOFF_REL}.
 
+OUTPUT EXPECTATIONS — fail-closed on a run that did nothing. An exit code
+answers "did the runner crash", never "did the runner run anything": a suite
+whose filter matched no cases prints "0 scenarios" and exits 0, and every
+gate calls it a pass. Add an "expect" block to make the output part of the
+verdict:
+
+      { "name": "e2e", "run": "behave --tags @smoke",
+        "expect": { "fail_if_output_matches": "0 scenarios",
+                    "require_output_matches": "\\\\d+ scenarios? passed" } }
+
+Doctrina supplies no patterns of its own and knows nothing about what the
+output means — the project declares the line that proves its run was real,
+so this works for any runner in any language. A check with an "expect"
+block runs piped (its output is echoed through when it finishes, rather
+than streaming); every other check still streams. An "expect" pattern that
+is not a valid regular expression fails at config time, not silently.
+
 Flags:
   --init     Scaffold a starter ${CONFIG_REL} (refuses to overwrite without --force)
   --list     Print the configured checks without running them

package/src/commands/watch.js

@@ -1,9 +1,11 @@
+// @ts-check
 import path from "node:path";
 import process from "node:process";
 import { watch as fsWatch } from "node:fs";
 import { exists } from "../lib/fs-ops.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
+import { notADoctrinaProject } from "../lib/exit-codes.js";
 import * as validate from "./validate.js";
 import * as next from "./next.js";
 
@@ -15,11 +17,16 @@ import * as next from "./next.js";
 // makes) so it never loops on its own output. `--once` runs a single pass and
 // exits — the testable, scriptable form.
 
+// 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", "once"], string: [] };
+
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
   const dot = path.join(projectRoot, ".doctrina");
   if (!exists(dot)) {
-    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+    throw notADoctrinaProject();
   }
 
   if (flagBool(flags, "once", false)) {

package/src/commands/why.js

@@ -1,3 +1,5 @@
+// @ts-check
+import { getSectionParagraph } from "../lib/doc-model.js";
 import path from "node:path";
 import process from "node:process";
 import { readdirSync } from "node:fs";
@@ -7,6 +9,7 @@ import { parseAcceptanceCriteria, isVerified } from "../lib/criteria.js";
 import * as idx from "../lib/index-json.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
+import { notADoctrinaProject } from "../lib/exit-codes.js";
 
 // Provenance explainer (review 2026-06-27 passive-user feature #5): answer
 // "why does this capability exist / why was it built this way?" by assembling
@@ -16,11 +19,16 @@ import { suggest } from "../lib/suggest.js";
 // asks; the tool answers from the artifacts, instead of grepping by hand.
 // Read-only. Builds on the Realizes:/trace provenance (ADR 0006/0011).
 
+// 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 cap = 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();
   }
   const specsDir = path.join(projectRoot, ".doctrina", "specs");
   const known = isDir(specsDir) ? readdirSync(specsDir).filter((e) => isFile(path.join(specsDir, e, "spec.md"))) : [];
@@ -72,7 +80,7 @@ export async function run(positional, _flags) {
   const status = specHeader(text, "Status") ?? "—";
   const impl = specHeader(text, "Implementation") ?? "—";
   console.log(`    ${c.gray("status:")} ${status}   ${c.gray("implementation:")} ${impl}`);
-  const purpose = sectionParagraph(text, "Purpose");
+  const purpose = getSectionParagraph(text, "Purpose");
   if (purpose) console.log("    " + purpose.replace(/\s+/g, " ").trim());
 
   // Dependency graph, both directions (the machine-readable **Depends on:**
@@ -229,28 +237,6 @@ function productAnchors(projectRoot) {
   return out;
 }
 
-// First non-comment paragraph under a "## <name>" heading.
-function sectionParagraph(text, name) {
-  const lines = text.split(/\r?\n/);
-  let inSection = false;
-  const buf = [];
-  for (const line of lines) {
-    if (/^##\s+/.test(line)) {
-      if (inSection) break;
-      if (new RegExp(`^##\\s+${name}\\b`, "i").test(line)) inSection = true;
-      continue;
-    }
-    if (!inSection) continue;
-    if (/^\s*<!--/.test(line) || /-->/.test(line)) continue;
-    if (line.trim() === "") {
-      if (buf.length) break;
-      continue;
-    }
-    buf.push(line.trim());
-  }
-  return buf.join(" ");
-}
-
 // Accepted ADRs whose body names the capability (word-ish boundary).
 function decisionsMentioning(projectRoot, cap) {
   const adrDir = path.join(projectRoot, ".doctrina", "decisions");

package/src/commands/work.js

@@ -1,3 +1,4 @@
+// @ts-check
 import path from "node:path";
 import process from "node:process";
 import { readdirSync } from "node:fs";
@@ -8,7 +9,9 @@ import * as idx from "../lib/index-json.js";
 import { c } from "../lib/colors.js";
 import { assessBrief } from "../lib/clarity.js";
 import { locateTemplatesDir, substitute } from "../lib/templates.js";
+import { EXIT, notADoctrinaProject } from "../lib/exit-codes.js";
 import { changeNew } from "./change.js";
+import { classify } from "./triage.js";
 
 // `work` is the second half of the no-ceremony path (ADR 0005): a brief
 // prompt ("add login") becomes a fully scaffolded change plus a playbook
@@ -18,11 +21,16 @@ import { changeNew } from "./change.js";
 // unproven verification). The CLI's own language processing stops at
 // slugging and term counting; everything semantic is the agent's job.
 
+// 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", "chore", "force", "from-diff", "no-spec", "quiet"], string: ["capability", "id", "resume", "title"] };
+
 export async function run(positional, flags) {
   const prompt = positional.join(" ").trim();
   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();
   }
 
   // --resume <id>: reprint the playbook for an existing open change rather than
@@ -65,6 +73,31 @@ export async function run(positional, flags) {
     }
   }
 
+  // LANE CHECK (change 0029). `work` was the default answer to every
+  // request, so a broken workflow or a suite that ran nothing became a
+  // change with a proposal, tasks and a spec delta — ceremony spent on a
+  // diagnosis, and a close that attested to nothing. A runtime-shaped
+  // prompt is stopped here, once, with the diagnosis path named. It is a
+  // deterministic term match and it can be wrong, so --force proceeds and
+  // the message says so.
+  if (!fromDiff && !chore && !flagBool(flags, "force", false)) {
+    const verdict = classify(prompt);
+    if (verdict.lane === "runtime" && verdict.confident) {
+      console.error(c.yellow("hold:") + " this reads as a RUNTIME problem, not a change of behaviour");
+      console.error(c.gray(`signals: ${[...new Set(verdict.scores.runtime.hits)].slice(0, 6).join(", ")}`));
+      console.error("");
+      console.error("Nothing here says the spec is wrong — diagnose the running system first:");
+      console.error(`  ${c.cyan(`doctrina triage "${prompt.length > 60 ? `${prompt.slice(0, 59)}…` : prompt}"`)}`);
+      console.error("");
+      console.error(c.gray("If the requirement really is missing, open the change anyway:"));
+      console.error(c.gray("  doctrina work --force \"<prompt>\"   ·   or --chore for wiring already specified"));
+      // PRECONDITION: the work may be perfectly valid; this project has
+      // simply not been diagnosed yet. A gate code (1) would read as
+      // "the prompt is bad" and invite rewording it forever.
+      return EXIT.PRECONDITION;
+    }
+  }
+
   const pinned = flagString(flags, "capability");
   if (pinned && !/^[a-z][a-z0-9-]*$/.test(pinned)) {
     console.error(c.red("error:") + ` invalid capability "${pinned}" (lowercase letters, digits, hyphens)`);
@@ -538,6 +571,14 @@ Options:
                        prompt needed) and print a code-first playbook (F8)
   --chore, --no-spec   Open a spec-less chore change (infra/docs/build) with a
                        playbook that skips the spec-delta steps (F9)
-  --force              Open a new change even when one is open, and overwrite
-                       an existing change folder
+  --force              Open a new change even when one is open, overwrite an
+                       existing change folder, and proceed past the lane hold
+                       below
+
+A prompt that reads as a RUNTIME problem — a workflow, an env value, a run
+that executed nothing — is HELD before anything is scaffolded, and pointed
+at \`doctrina triage\` instead (exit 3: a precondition, not a bad prompt).
+The classifier is deterministic term matching and can be wrong; --force
+opens the change anyway, and --chore is the lane for wiring the spec
+already covers.
 `;

package/src/index.js

@@ -1,10 +1,15 @@
 #!/usr/bin/env node
+// @ts-check
 import process from "node:process";
 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 } from "./lib/commands.js";
+import { surfaceHelp, OPERATIONS } 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 * as init from "./commands/init.js";
 import * as spec from "./commands/spec.js";
@@ -41,6 +46,8 @@ import * as report from "./commands/report.js";
 import * as completion from "./commands/completion.js";
 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";
 
 const COMMANDS = {
   init, spec, change, decision, validate, hooks, analyze, clarify,
@@ -48,7 +55,7 @@ const COMMANDS = {
   intake, work, coverage, verify, contract, trace,
   status, close, review, watch, why, constitution,
   prime, handoff, show, doctor, report, completion,
-  intent, upgrade,
+  intent, upgrade, adapter, triage,
 };
 
 const TOP_HELP = `
@@ -60,6 +67,10 @@ ${surfaceHelp()}
 Global flags:
   --help, -h           Show this message (or per-command help if after a command)
   --version, -v        Print the version
+  --debug              On an unexpected error, also print the stack trace
+
+Exit codes (a contract — an agent reads these to decide what to do next):
+${exitCodeHelp()}
 `;
 
 async function main(argv) {
@@ -69,8 +80,23 @@ async function main(argv) {
   // version and exit, looking exactly like the spec's version had been set
   // (0.11.0 field-review papercut). `-v` stays global either way.
   const versionOnly = argv.every((t) => t === "--version" || t === "-v") && argv.length > 0;
+
+  // Two passes. The first resolves only the command name, using the global
+  // flags; the second re-parses with THAT command's declared flags merged in.
+  //
+  // One global boolean list used to serve every command, and six flags read
+  // via flagBool were missing from it. An undeclared flag whose next token
+  // does not start with "-" swallows that token as its value, so
+  // `change new --chore ajuste-ci "Ajustar CI"` lost the id AND silently
+  // ignored the flag, reporting "requires a title" for a quoted title (C3).
+  // Declarations now live with the command, so a new command cannot
+  // reintroduce the gap by forgetting to edit this file.
+  const bootstrap = parseArgs(argv, { boolean: [...GLOBAL_FLAGS.boolean] });
+  const commandModule = COMMANDS[bootstrap.positional[0]];
+  const spec = commandModule?.flags;
   const { positional, flags } = parseArgs(argv, {
-    boolean: ["help", "h", "v", "force", "non-interactive", "check", "save", "bug", "write", "all", "concat", "archive", "strict", "list", "init", "fix", "once", "clean", "json"],
+    boolean: [...GLOBAL_FLAGS.boolean, ...(spec?.boolean ?? [])],
+    string: [...GLOBAL_FLAGS.string, ...(spec?.string ?? [])],
   });
 
   if (versionOnly || flags.get("v") === true) {
@@ -93,7 +119,7 @@ async function main(argv) {
     } else {
       console.error(c.gray("hint: ") + "try `doctrina --help` for the command surface");
     }
-    return 2;
+    return EXIT.USAGE;
   }
 
   if (flags.get("help") || flags.get("h")) {
@@ -102,14 +128,43 @@ async function main(argv) {
   }
 
   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) {
+      const { code, stdout, stderr } = await captureOutput(
+        () => command.run(positional.slice(1), flags),
+      );
+      emitJson([commandName, ...positional.slice(1)].join(" "), {
+        stdout: stdout.map(stripAnsi),
+        stderr: stderr.map(stripAnsi),
+      }, { ok: code === EXIT.OK, exitCode: code });
+      return code;
+    }
     return await command.run(positional.slice(1), flags);
   } catch (err) {
     console.error(c.red("error:") + ` ${err.message}`);
+    if (err.remedy) {
+      console.error(c.gray("hint: ") + `run ${c.cyan(err.remedy)} first, then retry`);
+    }
     if (flags.get("debug") && err.stack) {
       console.error(c.gray(err.stack));
     }
-    return 1;
+    // A typed error carries its own class (precondition vs environment).
+    // An untyped throw is an unexpected failure of the work itself, which
+    // is the GATE class: something is wrong here, fix it and retry (C7).
+    return err.exitCode ?? EXIT.GATE;
   }
 }
 
-main(process.argv.slice(2)).then((code) => process.exit(code ?? 0));
+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,
+  // no arguments captured, and never fatal. See lib/usage.js.
+  recordUsage(
+    process.argv.slice(2).filter((a) => !a.startsWith("-")),
+    code,
+    new Set(OPERATIONS.map((o) => o[0])),
+  );
+  process.exit(code ?? 0);
+});

package/src/lib/adapters.js

@@ -0,0 +1,140 @@
+// @ts-check
+import path from "node:path";
+import { readdirSync } from "node:fs";
+import { exists, isDir, isFile, read, relPath, walk } from "./fs-ops.js";
+import { locateTemplatesDir, substitute } from "./templates.js";
+
+// Agent adapters: the thin per-agent files that point at AGENTS.md.
+//
+// Installing one used to be reachable ONLY through a full `doctrina init`
+// run, and `init` refuses to run twice — so `init --force` was the only
+// path, and it regenerated AGENTS.md and product.md from blank templates,
+// destroying every hand-authored rule and the entire product definition
+// with no warning (audit item C1, data loss). This module owns adapters as
+// their own concern so adding one can be strictly additive.
+//
+// Three states, which the old surface could not tell apart:
+//   installed      — the adapter's files are present in the project
+//   available      — the adapter ships files and none are installed
+//   native         — the agent reads AGENTS.md directly and needs no file
+//                    (its template dir carries only a README)
+
+export const ADAPTER_STATES = Object.freeze({
+  INSTALLED: "installed",
+  AVAILABLE: "available",
+  NATIVE: "native",
+});
+
+// Where a named adapter's templates live. A project-local adapter under
+// `.doctrina/templates/adapters/<name>/` wins over the bundled one, so a
+// team can ship an adapter for an agent Doctrina does not know about.
+export function resolveAdapterDir(projectRoot, name) {
+  const local = path.join(projectRoot, ".doctrina", "templates", "adapters", name);
+  if (isDir(local) && walk(local).length > 0) return { dir: local, source: "project" };
+  const bundledRoot = path.join(locateTemplatesDir(), "adapters");
+  const bundled = path.join(bundledRoot, name);
+  if (isDir(bundled)) return { dir: bundled, source: "bundled" };
+  return null;
+}
+
+// Every adapter name known to this project: bundled plus project-local.
+export function listAdapterNames(projectRoot) {
+  const names = new Set();
+  try {
+    const bundledRoot = path.join(locateTemplatesDir(), "adapters");
+    if (isDir(bundledRoot)) {
+      for (const e of readdirSync(bundledRoot)) {
+        if (isDir(path.join(bundledRoot, e))) names.add(e);
+      }
+    }
+  } catch { /* unusual install without a templates dir */ }
+  const localRoot = path.join(projectRoot, ".doctrina", "templates", "adapters");
+  if (isDir(localRoot)) {
+    for (const e of readdirSync(localRoot)) {
+      if (isDir(path.join(localRoot, e))) names.add(e);
+    }
+  }
+  return [...names].sort();
+}
+
+// The files a named adapter would write, as project-relative POSIX paths
+// paired with their template source. A README inside the adapter template
+// dir documents the adapter and is never materialised.
+export function adapterFiles(projectRoot, name) {
+  const resolved = resolveAdapterDir(projectRoot, name);
+  if (!resolved) return null;
+  const out = [];
+  for (const templatePath of walk(resolved.dir)) {
+    const rel = relPath(resolved.dir, templatePath).replace(/\\/g, "/");
+    if (rel === "README.md" || rel.endsWith(".gitkeep")) continue;
+    out.push({
+      templatePath,
+      relativePath: rel.replace(/\.template$/, ""),
+    });
+  }
+  return { source: resolved.source, files: out.sort((a, b) => a.relativePath.localeCompare(b.relativePath)) };
+}
+
+// Adapter state plus the files backing it, for `adapter list`.
+export function describeAdapter(projectRoot, name) {
+  const spec = adapterFiles(projectRoot, name);
+  if (!spec) return { name, state: ADAPTER_STATES.AVAILABLE, source: "unknown", files: [], installed: [] };
+  if (spec.files.length === 0) {
+    // Reads AGENTS.md natively — "no adapter installed" and "no adapter
+    // needed" were indistinguishable before this distinction existed.
+    return { name, state: ADAPTER_STATES.NATIVE, source: spec.source, files: [], installed: [] };
+  }
+  const installed = spec.files.filter((f) => isFile(path.join(projectRoot, f.relativePath)));
+  return {
+    name,
+    source: spec.source,
+    files: spec.files,
+    installed,
+    state: installed.length > 0 ? ADAPTER_STATES.INSTALLED : ADAPTER_STATES.AVAILABLE,
+  };
+}
+
+// The AGENTS.md path an adapter file should point at, relative to its own
+// location — a nested command file needs "../../AGENTS.md".
+export function agentsMdPathFor(relativePath) {
+  const depth = relativePath.split("/").length - 1;
+  return depth === 0 ? "AGENTS.md" : "../".repeat(depth) + "AGENTS.md";
+}
+
+// Is this adapter file a HUB POINTER — a file whose job is to route the
+// agent at AGENTS.md?
+//
+// Declared by the template itself: a template that uses the
+// {{AGENTS_MD_PATH}} token is saying "I point at the hub". Everything else
+// is a command shim — a Claude/Cursor slash command like `/doctrina-status`
+// whose job is to invoke the CLI, and which reaches the hub through its
+// parent CLAUDE.md rather than by naming it.
+//
+// This distinction is the fix for audit item C2: the pointer check demanded
+// the literal string "AGENTS.md" in EVERY adapter file, so a clean
+// `init --agent claude` failed `templates check` on four command shims that
+// were never pointers, and neither suggested remedy could clear it.
+export function isHubPointer(file) {
+  return read(file.templatePath).includes("{{AGENTS_MD_PATH}}");
+}
+
+// Render one adapter file's body for this project.
+export function renderAdapterFile(file, tokens) {
+  return substitute(read(file.templatePath), {
+    ...tokens,
+    AGENTS_MD_PATH: agentsMdPathFor(file.relativePath),
+  });
+}
+
+// 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

@@ -1,3 +1,4 @@
+// @ts-check
 import path from "node:path";
 import { isDir, read, walk } from "./fs-ops.js";
 import { listHeader } from "./scan.js";