doctrina-cli 0.12.0 → 0.14.0

package/src/commands/change.js

@@ -1,17 +1,29 @@
+// @ts-check
+import { getSection, getHeader } from "../lib/doc-model.js";
 import path from "node:path";
 import process from "node:process";
-import { exists, isDir, lineCount, mkdirp, move, read, relPath, remove, walk, write } from "../lib/fs-ops.js";
+import { exists, isDir, isFile, lineCount, mkdirp, move, read, relPath, remove, walk, write } from "../lib/fs-ops.js";
 import { diffLines, formatUnified } from "../lib/diff.js";
 import { locateTemplatesDir, loadTemplateTree, materialiseEntry } from "../lib/templates.js";
 import * as idx from "../lib/index-json.js";
 import { deriveIndex } from "../lib/scan.js";
 import { extractOps, applyOps } from "../lib/spec-ops.js";
+import { printAdrCheckpoint } from "../lib/adr-guard.js";
+import { GATES, TRANSITIONS, checkTransition, recordForcedGap } from "../lib/gates.js";
 import { today } from "../lib/dates.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
+import { confirm, isInteractive } from "../lib/prompt.js";
+import { EXIT } from "../lib/exit-codes.js";
+import { notADoctrinaProject } from "../lib/exit-codes.js";
 
-const SUBCOMMANDS = ["new", "apply", "archive", "diff", "abandon"];
+const SUBCOMMANDS = ["new", "apply", "archive", "check", "tick", "diff", "abandon"];
+
+// 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", "all", "chore", "design", "force", "no-spec"], string: ["reason"] };
 
 export async function run(positional, flags) {
   const sub = positional[0];
@@ -19,13 +31,17 @@ export async function run(positional, flags) {
     case "new":
       return changeNew(positional.slice(1), flags);
     case "apply":
-      return changeApply(positional.slice(1), flags);
+      return forEachId(positional.slice(1), "apply", (id) => changeApply([id], flags));
     case "archive":
-      return changeArchive(positional.slice(1), flags);
+      return forEachId(positional.slice(1), "archive", (id) => changeArchive([id], flags));
+    case "check":
+      return forEachId(positional.slice(1), "check", (id) => changeCheck(id));
+    case "tick":
+      return changeTick(positional.slice(1), flags);
     case "diff":
       return changeDiff(positional.slice(1), flags);
     case "abandon":
-      return changeAbandon(positional.slice(1), flags);
+      return await changeAbandon(positional.slice(1), flags);
     default:
       console.error(c.red("error:") + ` unknown change subcommand "${sub ?? ""}"`);
       const guess = suggest(sub, SUBCOMMANDS);
@@ -36,6 +52,63 @@ export async function run(positional, flags) {
   }
 }
 
+// Enforce a lifecycle transition's preconditions from the shared gate map.
+// Returns true when the transition may proceed. One implementation, so
+// every driver of a transition refuses — and explains, and forces —
+// identically (C6).
+function enforceTransition(projectRoot, id, changeDir, transition, flags) {
+  const force = flagBool(flags, "force", false);
+  const { ok, blockers } = checkTransition(projectRoot, changeDir, transition);
+  if (ok) return true;
+
+  const label = TRANSITIONS[transition].label;
+  if (!force) {
+    console.error(c.red("error:") + ` refusing to ${transition} "${id}" — ${blockers.length} blocker${blockers.length === 1 ? "" : "s"}:`);
+    for (const b of blockers) console.error(`  - [${b.gate}] ${b.message}`);
+    const reruns = [...new Set(blockers.map((b) => GATES[b.gate].rerun(id)))];
+    console.error(c.gray("hint: ") + `fix them (${reruns.join(" · ")}), or pass --force to ${transition} anyway (records the gap)`);
+    return false;
+  }
+  console.log(c.yellow("warn:") + ` ${label} "${id}" with ${blockers.length} blocker${blockers.length === 1 ? "" : "s"} (--force):`);
+  for (const b of blockers) console.log(c.yellow("  - ") + `[${b.gate}] ${b.message}`);
+  recordForcedGap(projectRoot, id, transition, blockers);
+  return true;
+}
+
+// Batch driver (operator review 2026-07-19 §3.5/§4.5): apply/archive/check
+// accept multiple ids so a backlog closes without a bash loop. Each id runs
+// independently — one failure does not stop the rest — and the exit code is
+// the worst one seen. `new` and `abandon` stay single-id on purpose (creation
+// wants a title; abandonment is destructive and deserves one deliberate call).
+async function forEachId(ids, name, one) {
+  if (ids.length === 0) {
+    console.error(c.red("error:") + ` change ${name} requires at least one <id>`);
+    return 2;
+  }
+  let worst = 0;
+  for (const id of ids) {
+    if (ids.length > 1) {
+      console.log("");
+      console.log(c.bold(`──── change ${name} ${id}`));
+    }
+    let code;
+    try {
+      code = await one(id);
+    } catch (err) {
+      console.error(c.red("error:") + ` ${err.message}`);
+      code = 1;
+    }
+    worst = Math.max(worst, code);
+  }
+  if (ids.length > 1) {
+    console.log("");
+    console.log(worst === 0
+      ? c.green("ok") + ` all ${ids.length} changes passed ${name}`
+      : c.red("fail") + ` at least one change failed ${name}`);
+  }
+  return worst;
+}
+
 function changeNew(args, flags) {
   const id = args[0];
   const title = args.slice(1).join(" ").trim();
@@ -107,7 +180,7 @@ function changeNew(args, flags) {
   return 0;
 }
 
-function changeApply(args, _flags) {
+function changeApply(args, flags) {
   const id = args[0];
   if (!id) {
     console.error(c.red("error:") + " change apply requires <id>");
@@ -122,6 +195,30 @@ function changeApply(args, _flags) {
     return 1;
   }
 
+  // Gate parity (C6). `apply` used to mutate specs with no preconditions,
+  // so `analyze` could exit 1 on a change and `apply` would write it anyway
+  // and exit 0 — through the very analyze → apply path the docs prescribe.
+  // The preconditions now come from the shared map, so what guards a
+  // transition does not depend on which command drove it.
+  if (!enforceTransition(projectRoot, id, changeDir, "apply", flags)) return 1;
+
+  // Applying twice is silent corruption. The ops verbs are ADDITIVE —
+  // `append-requirement` appends, `bump-version` bumps — so a second pass
+  // duplicates every requirement and criterion the delta carries and bumps
+  // the version again. `apply` stamps the proposal `applied` on success, so
+  // that stamp is the guard. (Found by `close` re-running apply on an
+  // already-applied change and doubling 15 requirements on this repo.)
+  const proposalPath = path.join(changeDir, "proposal.md");
+  const alreadyApplied = isFile(proposalPath)
+    && (getHeader(read(proposalPath), "Status") ?? "").trim().toLowerCase() === "applied";
+  if (alreadyApplied && !flagBool(flags, "force", false)) {
+    console.log(c.gray("skip ") + `change "${id}" is already applied — nothing to do`);
+    console.log(c.gray("The ops verbs are additive: applying twice duplicates every"));
+    console.log(c.gray("requirement this delta carries. Re-apply anyway with --force"));
+    console.log(c.gray("only after reverting the specs to their pre-apply state."));
+    return 0;
+  }
+
   const deltaFiles = walk(path.join(changeDir, "specs")).filter((p) => p.endsWith("delta.md"));
   const date = today();
   let errors = 0;
@@ -246,6 +343,193 @@ function changeApply(args, _flags) {
   return errors > 0 ? 1 : 0;
 }
 
+// Pre-close dry-run (operator review 2026-07-19 §4.4): everything analyze,
+// apply, and archive would refuse, listed BEFORE any of them runs, with the
+// remediation next to each finding. Read-only — the per-change `doctor`.
+async function changeCheck(id) {
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+  const changeDir = path.join(projectRoot, ".doctrina", "changes", id);
+  if (!isDir(changeDir)) {
+    console.error(c.red("error:") + ` change "${id}" not found at ${relPath(projectRoot, changeDir)}`);
+    return 1;
+  }
+
+  let failures = 0;
+
+  // 1. Structural analysis — same checks analyze runs before an apply.
+  console.log(c.gray("──── 1/3 structure (analyze)"));
+  const analyze = await import("./analyze.js");
+  if ((await analyze.run([id], new Map())) !== 0) failures += 1;
+
+  // 2. Ops dry-run: execute every MODIFIED delta's ops block against the
+  //    target spec in memory. An op that would fail at apply time (missing
+  //    header, no such criterion, unknown verb) is reported here, not days
+  //    later; a delta with no ops block is flagged as a manual merge so the
+  //    close is planned around it instead of surprised by it.
+  console.log(c.gray("──── 2/3 ops dry-run (what apply would do)"));
+  const deltaFiles = walk(path.join(changeDir, "specs")).filter((p) => p.endsWith("delta.md"));
+  let opsFindings = 0;
+  for (const deltaPath of deltaFiles) {
+    const text = read(deltaPath);
+    if (parseOperation(text) !== "MODIFIED") continue;
+    const capability = parseCapabilityFromDelta(text, deltaPath);
+    const rel = relPath(projectRoot, deltaPath);
+    const ops = extractOps(text);
+    if (ops.length === 0) {
+      console.log(c.yellow("⚠ ") + `${rel}: no ops block — apply will print a manual-merge pointer`);
+      continue;
+    }
+    const targetPath = path.join(projectRoot, ".doctrina", "specs", capability ?? "", "spec.md");
+    if (!capability || !exists(targetPath)) {
+      console.log(c.red("✗ ") + `${rel}: MODIFIED targets missing spec`);
+      opsFindings += 1;
+      continue;
+    }
+    const result = applyOps(read(targetPath), ops);
+    if (result.errors.length > 0) {
+      console.log(c.red("✗ ") + `${rel}: ${result.errors.length} op error${result.errors.length === 1 ? "" : "s"} (apply would refuse):`);
+      for (const e of result.errors) console.log(`    - ${e}`);
+      opsFindings += 1;
+    } else {
+      console.log(c.green("✓ ") + `${rel}: ${result.applied.length} op${result.applied.length === 1 ? "" : "s"} would apply cleanly`);
+    }
+  }
+  if (deltaFiles.length === 0) console.log(c.gray("- no spec deltas"));
+  if (opsFindings > 0) failures += 1;
+
+  // 3. Archive gate preview: what archive will refuse, listed with the fix.
+  console.log(c.gray("──── 3/3 archive gate"));
+  // Preview through the SAME map the transitions enforce, so `check` can
+  // never disagree with what `apply` / `archive` will actually do (C6).
+  const archiveGate = checkTransition(projectRoot, changeDir, "archive");
+  if (archiveGate.ok) {
+    console.log(c.green("✓ ") + `archive gate clear (${archiveGate.gates.join(" + ")})`);
+  } else {
+    failures += 1;
+    for (const b of archiveGate.blockers) console.log(c.red("✗ ") + `[${b.gate}] ${b.message}`);
+    console.log(c.gray("    check them off as they land, or in bulk: ") + c.cyan(`doctrina change tick ${id} --all`));
+  }
+
+  // Advisory (never gates): accepted ADRs citing the touched capabilities.
+  const caps = [...new Set(deltaFiles.map((p) => parseCapabilityFromDelta(read(p), p)).filter(Boolean))].sort();
+  console.log("");
+  printAdrCheckpoint(projectRoot, caps, { c });
+
+  console.log("");
+  if (failures === 0) {
+    console.log(c.green("ok") + ` ${id} is ready to close: ` + c.cyan(`doctrina close ${id}`));
+    return 0;
+  }
+  console.log(c.red("fail") + ` ${failures} area${failures === 1 ? "" : "s"} would block the close — fix them first`);
+  return 1;
+}
+
+// Bulk checkbox marking (operator review 2026-07-19 §3.5: "marcar checkbox
+// não tem comando nenhum" — it was sed/Python by hand). With no args it
+// LISTS the unchecked boxes with ordinals; `tick <id> 2 5` checks those;
+// `tick <id> --all` checks everything (tasks.md + the proposal's
+// ## Verification). Ticking is a claim of completion — the honest gate is
+// still archive/verify; this only removes the mechanical friction.
+function changeTick(args, flags) {
+  const id = args[0];
+  if (!id) {
+    console.error(c.red("error:") + " change tick requires <id> [ordinals... | --all]");
+    return 2;
+  }
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+  const changeDir = path.join(projectRoot, ".doctrina", "changes", id);
+  if (!isDir(changeDir)) {
+    console.error(c.red("error:") + ` change "${id}" not found at ${relPath(projectRoot, changeDir)}`);
+    return 1;
+  }
+
+  // Unified ordinal space over both files, in reading order: every unchecked
+  // `- [ ]` in tasks.md, then in the proposal's ## Verification section.
+  const files = [
+    { label: "tasks.md", path: path.join(changeDir, "tasks.md"), section: null },
+    { label: "proposal.md ## Verification", path: path.join(changeDir, "proposal.md"), section: "Verification" },
+  ];
+  const boxes = [];
+  for (const f of files) {
+    if (!isFile(f.path)) continue;
+    const lines = read(f.path).split(/\r?\n/);
+    const inScope = f.section === null
+      ? () => true
+      : (() => {
+          const scoped = new Set();
+          let inSection = false;
+          for (let i = 0; i < lines.length; i++) {
+            if (/^##\s+/.test(lines[i])) inSection = new RegExp(`^##\\s+${f.section}\\b`, "i").test(lines[i]);
+            else if (inSection) scoped.add(i);
+          }
+          return (i) => scoped.has(i);
+        })();
+    for (let i = 0; i < lines.length; i++) {
+      if (/^\s*-\s*\[ \]/.test(lines[i]) && inScope(i)) {
+        boxes.push({ file: f, lineIndex: i, text: lines[i].replace(/^\s*-\s*\[ \]\s*/, "") });
+      }
+    }
+  }
+
+  if (boxes.length === 0) {
+    console.log(c.green("ok") + " no unchecked boxes in tasks.md or the proposal's ## Verification");
+    return 0;
+  }
+
+  const all = flagBool(flags, "all", false);
+  const ordinals = args.slice(1).map(Number);
+  const isPlaceholder = (box) => box.text.trim() === "";
+  if (!all && ordinals.length === 0) {
+    console.log(c.bold(`Unchecked boxes in ${id}:`));
+    console.log("");
+    for (let i = 0; i < boxes.length; i++) {
+      const label = isPlaceholder(boxes[i])
+        ? c.yellow("(scaffold placeholder — write the real task, or delete the line)")
+        : boxes[i].text;
+      console.log(`  ${String(i + 1).padStart(3)}. ${label}  ${c.gray(`[${boxes[i].file.label}]`)}`);
+    }
+    console.log("");
+    console.log(c.gray("tick some: ") + c.cyan(`doctrina change tick ${id} 1 3`) + c.gray(" · all: ") + c.cyan(`doctrina change tick ${id} --all`));
+    return 0;
+  }
+
+  const picked = all ? boxes.map((_, i) => i + 1) : ordinals;
+  for (const n of picked) {
+    if (!Number.isInteger(n) || n < 1 || n > boxes.length) {
+      console.error(c.red("error:") + ` no box #${n} (1..${boxes.length} — run \`doctrina change tick ${id}\` to list)`);
+      return 2;
+    }
+  }
+  // Ticking an empty scaffold placeholder is a meaningless claim — it is how
+  // a hollow change games the archive gate. Refuse (all-or-nothing) and name
+  // the fix; analyze/close hard-fail on the placeholders regardless.
+  const empties = picked.filter((n) => isPlaceholder(boxes[n - 1]));
+  if (empties.length > 0) {
+    console.error(c.red("error:") + ` box${empties.length === 1 ? "" : "es"} ${empties.join(", ")} ${empties.length === 1 ? "is a" : "are"} scaffold placeholder${empties.length === 1 ? "" : "s"} with no text — nothing was ticked`);
+    console.error(c.gray("hint: ") + "write the real task on each line (or delete it), then tick");
+    return 2;
+  }
+
+  // Group edits per file so each file is read/written once.
+  const byPath = new Map();
+  for (const n of picked) {
+    const box = boxes[n - 1];
+    if (!byPath.has(box.file.path)) byPath.set(box.file.path, []);
+    byPath.get(box.file.path).push(box);
+  }
+  for (const [filePath, hits] of byPath) {
+    const lines = read(filePath).split(/\r?\n/);
+    for (const box of hits) {
+      lines[box.lineIndex] = lines[box.lineIndex].replace(/\[ \]/, "[x]");
+    }
+    write(filePath, lines.join("\n"), { force: true });
+  }
+  console.log(c.green("ticked ") + `${picked.length} box${picked.length === 1 ? "" : "es"} in ${byPath.size} file${byPath.size === 1 ? "" : "s"}`);
+  return 0;
+}
+
 function changeArchive(args, flags) {
   const id = args[0];
   if (!id) {
@@ -266,22 +550,12 @@ function changeArchive(args, flags) {
   // task (including closing steps) or any declared verification item is
   // still unchecked. This is the difference between "boxes marked" and
   // "verification passed" the framework was faulted for collapsing.
-  // --force is the escape hatch: it archives anyway and records the gap.
-  const force = flagBool(flags, "force", false);
-  const blockers = collectArchiveBlockers(changeDir);
-  if (blockers.length > 0) {
-    if (!force) {
-      console.error(c.red("error:") + ` refusing to archive "${id}" — verification incomplete:`);
-      for (const b of blockers) console.error(`  - ${b}`);
-      console.error(
-        c.gray("hint: ") +
-          "finish and check the items, or pass --force to archive anyway (records the gap)",
-      );
-      return 1;
-    }
-    console.log(c.yellow("warn:") + ` archiving "${id}" with verification incomplete (--force):`);
-    for (const b of blockers) console.log(c.yellow("  - ") + b);
-  }
+  // Preconditions from the shared map (C6): structure AND verification.
+  // Reaching archive directly used to skip the structural check that the
+  // `close` path always ran first, so the same state was guarded
+  // differently depending on the route taken. --force is the escape hatch
+  // for both, and records the gap.
+  if (!enforceTransition(projectRoot, id, changeDir, "archive", flags)) return 1;
 
   const date = today();
   const archiveName = `${date}-${id}`;
@@ -369,7 +643,7 @@ function changeArchive(args, flags) {
 // and record the abandonment in the ledger so the history shows the dead end
 // instead of a silent gap. This is the missing inverse of `change new` — the
 // review had to delete a stray folder and hand-edit index.json (G6).
-function changeAbandon(args, flags) {
+async function changeAbandon(args, flags) {
   const id = args[0];
   if (!id) {
     console.error(c.red("error:") + " change abandon requires <id>");
@@ -384,6 +658,31 @@ function changeAbandon(args, flags) {
     return 1;
   }
 
+  // Consent before destruction (audit item C9). This deletes work with no
+  // undo — the ledger line is good practice and is not a substitute for
+  // being asked. Off a terminal there is nobody to ask, so `--force` is
+  // required: silence is not consent.
+  const force = flagBool(flags, "force", false);
+  if (!force) {
+    const doomed = walk(changeDir);
+    console.log(c.yellow("About to delete") + ` ${relPath(projectRoot, changeDir)} — ${doomed.length} file${doomed.length === 1 ? "" : "s"}:`);
+    for (const f of doomed.slice(0, 10)) console.log(`    ${c.gray(relPath(changeDir, f))}`);
+    if (doomed.length > 10) console.log(c.gray(`    … and ${doomed.length - 10} more`));
+    console.log(c.gray("This cannot be undone (the change is deleted, not archived)."));
+
+    if (!isInteractive()) {
+      console.error("");
+      console.error(c.red("error:") + " refusing to delete without confirmation");
+      console.error(c.gray("hint: ") + `re-run with ${c.cyan("--force")} to abandon non-interactively`);
+      return EXIT.USAGE;
+    }
+    const ok = await confirm(`Abandon "${id}"?`, { defaultYes: false, whenNonInteractive: false });
+    if (!ok) {
+      console.log(c.gray("aborted — nothing was deleted"));
+      return EXIT.OK;
+    }
+  }
+
   const reason = flagString(flags, "reason") ?? "";
   const date = today();
 
@@ -552,32 +851,15 @@ function collectArchiveBlockers(changeDir) {
 
   const proposalPath = path.join(changeDir, "proposal.md");
   if (exists(proposalPath)) {
-    const n = countUnchecked(extractSection(read(proposalPath), "Verification"));
+    const n = countUnchecked(getSection(read(proposalPath), "Verification"));
     if (n > 0) blockers.push(`${n} unmet verification item${n === 1 ? "" : "s"} in proposal.md (## Verification)`);
   }
   return blockers;
 }
 
-// Return the body of a "## <name>" section (lines after the heading up to
-// the next "## " heading). Empty string when the section is absent.
-function extractSection(text, name) {
-  const lines = text.split(/\r?\n/);
-  const head = new RegExp(`^##\\s+${name}\\b`, "i");
-  let inSection = false;
-  const out = [];
-  for (const line of lines) {
-    if (/^##\s+/.test(line)) {
-      inSection = head.test(line);
-      continue;
-    }
-    if (inSection) out.push(line);
-  }
-  return out.join("\n");
-}
-
 function ensureDoctrinaProject(projectRoot) {
   if (!exists(path.join(projectRoot, ".doctrina"))) {
-    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+    throw notADoctrinaProject();
   }
 }
 
@@ -589,7 +871,7 @@ Subcommands:
                          (--chore / --no-spec: a spec-less change for infra /
                          docs / build that still gets a proposal + ledger;
                          --design: also scaffold design.md, opt-in)
-  apply <id>             Apply spec deltas: ADDED writes the full body (it
+  apply <id...>          Apply spec deltas: ADDED writes the full body (it
                          also REPLACES a target that is still the untouched
                          \`spec new\` scaffold — the canonical new-capability
                          flow; real content refuses), REMOVED deletes,
@@ -597,19 +879,34 @@ Subcommands:
                          (set-header / bump-version / set-criterion / ...),
                          MODIFIED without one prints a manual-merge pointer.
                          On any spec write the index is rebuilt from the tree.
-  archive <id>           Move the change to .doctrina/changes/archive/YYYY-MM-DD-<id>/
+  archive <id...>        Move the change to .doctrina/changes/archive/YYYY-MM-DD-<id>/
+  check <id...>          Pre-close dry-run, read-only: analyze's structural
+                         checks + every ops block executed in memory against
+                         its target + the archive gate preview + an advisory
+                         list of accepted ADRs citing the touched capabilities.
+                         Everything close would refuse, listed BEFORE it runs.
+  tick <id> [n... |--all]  List the unchecked boxes (tasks.md + proposal
+                         ## Verification) with ordinals; tick the given ones,
+                         or every one with --all. No args = list only.
   abandon <id>           Delete an open change folder and its index entry, and
                          record the abandonment in the ledger ([--reason "..."]).
   diff <id>              Preview every spec delta: line diff for MODIFIED,
                          summary for ADDED/REMOVED. Read-only.
 
+apply / archive / check accept multiple ids (batch close of a backlog); the
+exit code is the worst per-id result.
+
 A MODIFIED delta may carry a fenced operations block that \`apply\` executes:
   \`\`\`ops
   set-header Implementation: verified — durable adapter (\`src/db.ts\`)
   bump-version minor
   set-criterion 1: verified
   append-criterion [unverified] new signal — verified by \`test/x.test.ts\`
+  append-requirement event: When <trigger>, the system shall <action>.
+  replace-requirement ubiquitous 2: The system shall <action>.
   \`\`\`
+append-* ops resolve numbering/position at apply time, so concurrent open
+changes appending to the same spec cannot collide.
 
 Options:
   --force                Overwrite existing files (where applicable)

package/src/commands/clarify.js

@@ -1,9 +1,11 @@
+// @ts-check
 import path from "node:path";
 import process from "node:process";
 import { readdirSync } from "node:fs";
 import { exists, isDir, isFile, read, relPath, walk } from "../lib/fs-ops.js";
-import { flagBool } from "../lib/args.js";
+import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
+import { notADoctrinaProject } from "../lib/exit-codes.js";
 
 // Two lexicons, one linter (0.11.0 field review item 3: an English-only
 // clarify is permanently red on a PT-BR project — "some" is the verb *sumir*,
@@ -78,16 +80,35 @@ function detectLang(text) {
   return pt > en ? "pt" : "en";
 }
 
-function rulesFor(projectRoot, text) {
-  const declared = projectLanguage(projectRoot);
-  const lang = declared ?? detectLang(text);
+function rulesFor(projectRoot, text, forcedLang = null) {
+  const lang = forcedLang ?? projectLanguage(projectRoot) ?? detectLang(text);
   return lang === "pt" ? RULES_PT : RULES_EN;
 }
 
+// --lang pt|en wins over the project config and the per-file heuristic
+// (operator review 2026-07-19 §4.8: on a PT-BR project with no config.json,
+// a file whose stopword count tips English gets the EN lexicon and "some" —
+// the verb *sumir* — is flagged as the vague quantifier). One flag, zero
+// guessing; persist it with .doctrina/config.json { "language": "pt-BR" }.
+function forcedLang(flags) {
+  const raw = flagString(flags, "lang");
+  if (!raw || raw === true) return null;
+  const lang = String(raw).toLowerCase();
+  if (lang.startsWith("pt")) return "pt";
+  if (lang.startsWith("en")) return "en";
+  console.error(c.yellow("warn:") + ` unknown --lang "${raw}" (use pt|en) — falling back to detection`);
+  return null;
+}
+
+// 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", "all"], string: ["lang"] };
+
 export async function run(positional, flags) {
   const projectRoot = process.cwd();
 
-  if (flagBool(flags, "all", false)) return clarifyAll(projectRoot);
+  if (flagBool(flags, "all", false)) return clarifyAll(projectRoot, forcedLang(flags));
 
   const target = positional[0];
   if (!target) {
@@ -103,7 +124,7 @@ export async function run(positional, flags) {
   console.log(`clarify ${relPath(projectRoot, fullPath)}`);
   console.log("");
 
-  const smells = scanFile(fullPath);
+  const smells = scanFile(fullPath, projectRoot, forcedLang(flags));
   for (const s of smells) {
     console.log(`${c.yellow("⚠")} line ${s.line}: ${s.rule} "${s.token}" — ${s.hint}`);
   }
@@ -122,9 +143,9 @@ export async function run(positional, flags) {
 // and clarify each. ADRs are immutable and the archive is history, so
 // neither is included; AGENTS.md is dense command text, a different
 // register from prose specs.
-function clarifyAll(projectRoot) {
+function clarifyAll(projectRoot, lang = null) {
   if (!exists(path.join(projectRoot, ".doctrina"))) {
-    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+    throw notADoctrinaProject();
   }
   const files = [];
   const productPath = path.join(projectRoot, ".doctrina", "product.md");
@@ -149,7 +170,7 @@ function clarifyAll(projectRoot) {
 
   let total = 0;
   for (const f of files) {
-    const smells = scanFile(f);
+    const smells = scanFile(f, projectRoot, lang);
     if (smells.length === 0) continue;
     total += smells.length;
     const rel = relPath(projectRoot, f);
@@ -167,10 +188,10 @@ function clarifyAll(projectRoot) {
   return 1;
 }
 
-function scanFile(fullPath, projectRoot = process.cwd()) {
+function scanFile(fullPath, projectRoot = process.cwd(), lang = null) {
   const text = read(fullPath);
   const skippedRanges = collectSkippedRanges(text);
-  const rules = rulesFor(projectRoot, text);
+  const rules = rulesFor(projectRoot, text, lang);
   const smells = [];
 
   // Per-line rules: regex pass with skip-range filter. A line carrying the
@@ -257,20 +278,20 @@ function findAcceptanceLine(text) {
 }
 
 export const help = `
-Usage: doctrina clarify <path>
-       doctrina clarify --all
+Usage: doctrina clarify <path> [--lang pt|en]
+       doctrina clarify --all [--lang pt|en]
 
 Read a Markdown file and report weasel words, vague quantifiers,
 placeholders, and empty Acceptance criteria sections. Exits 0 when
 no smells are found, 1 otherwise. Matches inside fenced code
 blocks, HTML comments, and inline backtick spans are skipped.
 
-Language-aware: declare it in .doctrina/config.json
-({ "language": "pt-BR" }) or let a per-file stopword count decide.
-Portuguese mode uses a PT lexicon (bare TODO is the pronoun, only
-"TODO:" is a marker; "some"/"several" are not smells). A line ending
-in <!-- clarify:ok --> is author-accepted and never flagged — the
-escape hatch for a false positive.
+Language-aware: --lang pt|en forces the lexicon; otherwise
+.doctrina/config.json ({ "language": "pt-BR" }) decides, else a
+per-file stopword count. Portuguese mode uses a PT lexicon (bare
+TODO is the pronoun, only "TODO:" is a marker; "some"/"several" are
+not smells). A line ending in <!-- clarify:ok --> is author-accepted
+and never flagged — the escape hatch for a false positive.
 
 With --all, every living document is scanned in one pass:
 product.md, capability specs, open changes, and skills. ADRs