doctrina-cli 0.13.0 → 0.14.0

package/src/commands/validate.js

@@ -1,13 +1,17 @@
+// @ts-check
 import path from "node:path";
 import process from "node:process";
 import { readdirSync } from "node:fs";
-import { exists, isDir, isFile, lineCount, read, relPath, walk } from "../lib/fs-ops.js";
+import { exists, isDir, isFile, lineCount, read, relPath, walk , write} from "../lib/fs-ops.js";
 import * as idx from "../lib/index-json.js";
 import { SCHEMA_VERSION } from "../lib/index-json.js";
 import { cliVersion } from "../lib/version.js";
 import { today } from "../lib/dates.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
+import { kindFromPath, nonConformingHeaders, repairHeaders } from "../lib/doc-model.js";
+import { emitJson } from "../lib/json-out.js";
+import { notADoctrinaProject } from "../lib/exit-codes.js";
 import { parseFrontmatter } from "./skill.js";
 import { checkEars, isEarsSpec } from "../lib/ears.js";
 import { specHeader, listHeader, deriveIndex, indexesMatch, stableStringify } from "../lib/scan.js";
@@ -19,8 +23,21 @@ import { parseAcceptanceCriteria, isVerified } from "../lib/criteria.js";
 // `doctrina --help` and is never nagged about omissions.
 const CATALOG_THRESHOLD = 8;
 
+// 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: ["fix", "json"], string: [] };
+
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
+  // Outside a Doctrina project this is a PRECONDITION, not a pile of
+  // gate failures about missing files: the remedy is `doctrina init`,
+  // not editing artifacts that do not exist yet (C7).
+  if (!isDir(path.join(projectRoot, ".doctrina"))) throw notADoctrinaProject();
   const errors = [];
   const warnings = [];
 
@@ -87,6 +104,45 @@ export async function run(_positional, flags) {
   const productMd = path.join(projectRoot, ".doctrina", "product.md");
   if (!isFile(productMd)) errors.push(".doctrina/product.md missing");
 
+  // Header repair (M3). One grammar means a non-canonical header can be
+  // REWRITTEN, not just reported: `- **Status**: x` becomes
+  // `- **Status:** x`, and a spec written with list-style headers is
+  // normalised to the bare-bold form its kind uses. Content is never
+  // touched — only the header's own punctuation and style.
+  const doFix = flagBool(flags, "fix", false);
+  {
+    const artifacts = [];
+    const dot = path.join(projectRoot, ".doctrina");
+    for (const f of walk(dot)) {
+      if (!f.endsWith(".md")) continue;
+      const rel = relPath(projectRoot, f).replace(/\\/g, "/");
+      if (rel.includes("/changes/archive/")) continue; // history is immutable
+      artifacts.push({ file: f, rel, kind: kindFromPath(rel) });
+    }
+    let repairedFiles = 0;
+    for (const a of artifacts) {
+      const text = read(a.file);
+      const bad = nonConformingHeaders(text, a.kind);
+      if (bad.length === 0) continue;
+      if (doFix) {
+        const { text: fixed, repaired } = repairHeaders(text, a.kind);
+        if (repaired > 0 && fixed !== text) {
+          write(a.file, fixed, { force: true });
+          repairedFiles += 1;
+        }
+      } else {
+        for (const h of bad) {
+          warnings.push(
+            `${a.rel}:${h.line} header "${h.name}" is ${h.wrongStyle ? `in ${h.style} style but a ${a.kind} uses ${h.expectedStyle} style` : "not in canonical form"} — run \`doctrina validate --fix\``,
+          );
+        }
+      }
+    }
+    if (doFix && repairedFiles > 0) {
+      console.log(c.green("fixed") + ` normalised headers in ${repairedFiles} artifact${repairedFiles === 1 ? "" : "s"}`);
+    }
+  }
+
   // 3. index.json
   let index = null;
   try {
@@ -574,7 +630,7 @@ export async function run(_positional, flags) {
 
   // Output
   if (flagBool(flags, "json", false)) {
-    console.log(JSON.stringify({ ok: errors.length === 0, errors, warnings }, null, 2));
+    emitJson("validate", { ok: errors.length === 0, errors, warnings });
     return errors.length === 0 ? 0 : 1;
   }
   for (const w of warnings) console.log(c.yellow("warn:  ") + w);

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
@@ -29,10 +31,15 @@ const STARTER = {
   ],
 };
 
+// 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 +73,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;

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,6 +9,7 @@ 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 { notADoctrinaProject } from "../lib/exit-codes.js";
 import { changeNew } from "./change.js";
 
 // `work` is the second half of the no-ceremony path (ADR 0005): a brief
@@ -18,11 +20,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

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,7 @@ 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";
 
 const COMMANDS = {
   init, spec, change, decision, validate, hooks, analyze, clarify,
@@ -48,7 +54,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,
 };
 
 const TOP_HELP = `
@@ -60,6 +66,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 +79,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 +118,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 +127,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";

package/src/lib/args.js

@@ -1,3 +1,4 @@
+// @ts-check
 // Tiny argv parser. Returns { positional: string[], flags: Map<string, string|boolean> }.
 // Supports:
 //   --flag                          -> flags.set("flag", true)
@@ -82,6 +83,15 @@ export function flagString(flags, name, fallback = undefined) {
   return String(v);
 }
 
+// True when a value-taking flag was written WITHOUT one — `--budget` at the
+// end of the line, or `--budget -100`, where the parser cannot tell a value
+// from the next flag. `flagString` reports both as absent, so without this
+// a mistyped number silently becomes "use the default", which is the one
+// outcome the author definitely did not ask for.
+export function flagGivenWithoutValue(flags, name) {
+  return flags.get(name) === true;
+}
+
 export function flagBool(flags, name, fallback = false) {
   const v = flags.get(name);
   if (v === undefined) return fallback;

package/src/lib/clarity.js

@@ -1,3 +1,4 @@
+// @ts-check
 // Deterministic under-specification detector for free-text briefs and
 // intakes — the clarification gate (review Topic A). It does NOT judge
 // meaning (that stays the agent's job, ADR 0005); it flags input that is

package/src/lib/colors.js

@@ -1,3 +1,4 @@
+// @ts-check
 // ANSI colour helpers. Falls back to plain text when:
 //   - stdout is not a TTY, OR
 //   - the NO_COLOR environment variable is set (any value), OR