doctrina-cli 0.11.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doctrina-cli",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Doctrina CLI — spec-driven, AGENTS.md-native framework for multi-agent AI development.",
   "license": "MIT",
   "keywords": [

package/src/commands/analyze.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import process from "node:process";
 import { exists, isDir, isFile, read, relPath, walk } from "../lib/fs-ops.js";
 import { c } from "../lib/colors.js";
+import { isUntouchedScaffold } from "./change.js";
 
 export async function run(positional, _flags) {
   const id = positional[0];
@@ -40,6 +41,16 @@ export async function run(positional, _flags) {
   } else {
     results.push(pass("tasks.md present"));
     const text = read(tasksPath);
+    // Scaffold placeholders never replaced ("- [ ]" with no text, checked or
+    // not) mean the change was OPENED but never PLANNED — the agent went
+    // straight to implementing on a hollow change and nothing barked
+    // (operator report 2026-07-19). A hard failure here blocks `change
+    // check` and `close` until the plan is real; ticking an empty box does
+    // not help, `change tick` refuses those too.
+    const placeholders = (text.match(/^\s*-\s*\[[ xX]\]\s*$/gm) ?? []).length;
+    if (placeholders > 0) {
+      results.push(fail(`tasks.md still carries ${placeholders} scaffold placeholder task${placeholders === 1 ? "" : "s"} ("- [ ]" with no text) — plan the change before implementing: replace them with real tasks (or delete the lines)`));
+    }
     if (/^\s*-\s*\[\s\]/m.test(text)) results.push(pass("tasks.md has at least one unchecked task"));
     else results.push(info("tasks.md has no unchecked tasks (already done?)"));
   }
@@ -74,8 +85,13 @@ export async function run(positional, _flags) {
       const targetSpec = path.join(projectRoot, ".doctrina", "specs", cap, "spec.md");
       const targetRel = relPath(projectRoot, targetSpec);
       if (op === "ADDED") {
-        if (exists(targetSpec)) {
-          results.push(fail(`  ${cap} (ADDED) but target ${targetRel} already exists`, "  "));
+        // Mirrors `change apply`: an existing target that is still the
+        // untouched `spec new` scaffold is the canonical flow (spec new →
+        // ADDED delta), so it passes as a replacement; only real content fails.
+        if (exists(targetSpec) && !isUntouchedScaffold(read(targetSpec), cap)) {
+          results.push(fail(`  ${cap} (ADDED) but target ${targetRel} has real content — use MODIFIED or remove it first`, "  "));
+        } else if (exists(targetSpec)) {
+          results.push(pass(`  ${cap} (ADDED) → ${targetRel} (replaces the untouched scaffold)`, "  "));
         } else {
           results.push(pass(`  ${cap} (ADDED) → ${targetRel} (new)`, "  "));
         }

package/src/commands/change.js

@@ -1,17 +1,18 @@
 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 { today } from "../lib/dates.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 
-const SUBCOMMANDS = ["new", "apply", "archive", "diff", "abandon"];
+const SUBCOMMANDS = ["new", "apply", "archive", "check", "tick", "diff", "abandon"];
 
 export async function run(positional, flags) {
   const sub = positional[0];
@@ -19,9 +20,13 @@ 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":
@@ -36,6 +41,40 @@ export async function run(positional, flags) {
   }
 }
 
+// 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();
@@ -67,9 +106,15 @@ function changeNew(args, flags) {
   const date = today();
   const tokens = { CHANGE_ID: id, CHANGE_TITLE: title, DATE: date, CAPABILITY: "" };
 
+  // design.md is opt-in (--design): in practice it scaffolded on every change
+  // and stayed empty — nine changes out of nine in the 0.11.0 field review. A
+  // change that needs a design doc asks for one; the rest stop carrying a
+  // blank file through apply/archive/ledger.
+  const wantDesign = flagBool(flags, "design", false);
   const tree = loadTemplateTree(templatesDir, "change");
   for (const entry of tree) {
     if (entry.relativePath === "spec-delta.md.template") continue;
+    if (entry.relativePath === "design.md.template" && !wantDesign) continue;
     const written = materialiseEntry(entry, changeDir, tokens, { force });
     console.log(c.green("created") + ` ${relPath(projectRoot, written)}`);
   }
@@ -139,15 +184,24 @@ function changeApply(args, _flags) {
     const targetPath = path.join(projectRoot, ".doctrina", "specs", capability, "spec.md");
 
     if (op === "ADDED") {
-      if (exists(targetPath)) {
-        console.error(c.red("error:") + ` ADDED delta targets existing spec ${relPath(projectRoot, targetPath)} — refusing to overwrite`);
+      // The canonical new-capability flow is `spec new <cap>` (which creates
+      // the file) → write the ADDED delta — so "target already exists" is the
+      // NORMAL case, not a conflict. When the existing spec is still the
+      // untouched `spec new` scaffold, ADDED means "replace the placeholder
+      // with the real spec" and applies as a whole-file write. Only a spec
+      // with real content refuses, since overwriting it would destroy truth.
+      if (exists(targetPath) && !isUntouchedScaffold(read(targetPath), capability)) {
+        console.error(c.red("error:") + ` ADDED delta targets existing spec ${relPath(projectRoot, targetPath)} with real content — refusing to overwrite`);
+        console.error(c.gray("hint: ") + "use a MODIFIED delta (with an ```ops block for bookkeeping edits), or REMOVE the spec first if it is truly being replaced");
         errors += 1;
         continue;
       }
+      const replacing = exists(targetPath);
       const body = extractDeltaBody(text);
-      write(targetPath, body, { force: false });
+      write(targetPath, body, { force: replacing });
       writes += 1;
-      console.log(c.green("applied[ADDED]") + ` ${relPath(projectRoot, targetPath)}`);
+      console.log(c.green("applied[ADDED]") + ` ${relPath(projectRoot, targetPath)}` +
+        (replacing ? c.gray(" (replaced the untouched spec-new scaffold)") : ""));
     } else if (op === "REMOVED") {
       if (!exists(targetPath)) {
         console.log(c.yellow("warn:") + ` REMOVED delta targets missing spec ${relPath(projectRoot, targetPath)} — skipping`);
@@ -231,6 +285,191 @@ 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"));
+  const blockers = collectArchiveBlockers(changeDir);
+  if (blockers.length === 0) {
+    console.log(c.green("✓ ") + "archive gate clear (all boxes checked)");
+  } else {
+    failures += 1;
+    for (const b of blockers) console.log(c.red("✗ ") + b);
+    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) {
@@ -275,6 +514,25 @@ function changeArchive(args, flags) {
     console.error(c.red("error:") + ` archive target already exists: ${relPath(projectRoot, archiveDir)}`);
     return 1;
   }
+
+  // Flip the proposal Status before the move. `apply` only flips it when no
+  // delta fell back to a manual merge, so a change whose merges were manual
+  // (the common case before the ops-block docs) reached the archive still
+  // saying "proposed" — the index recorded applied, the file lied. Archiving
+  // IS the declaration that the change went in; stamp the file to match.
+  const proposalPathLive = path.join(changeDir, "proposal.md");
+  if (exists(proposalPathLive)) {
+    const txt = read(proposalPathLive);
+    const updated = txt.replace(
+      /^(-\s+\*\*Status:\*\*)\s+proposed\s*$/m,
+      `$1 applied\n- **Applied:** ${date}`,
+    );
+    if (updated !== txt) {
+      write(proposalPathLive, updated, { force: true });
+      console.log(c.green("status") + " proposal.md → applied (stamped at archive)");
+    }
+  }
+
   move(changeDir, archiveDir);
   console.log(c.green("archived") + ` ${relPath(projectRoot, archiveDir)}`);
 
@@ -470,6 +728,38 @@ function extractDeltaBody(text) {
   return text.slice(idxSep + 5).replace(/^\n+/, "");
 }
 
+// Is the on-disk spec still the untouched `spec new <cap>` scaffold? Precise
+// check: render the shipped capability template for the same capability and
+// compare, ignoring the date-bearing "Last updated" line and whitespace
+// normalisation. When the template cannot be located (unusual installs),
+// fall back to the scaffold's own placeholder fingerprints — text no real
+// spec keeps. Used by `change apply` so an ADDED delta can replace a
+// scaffold (the canonical spec-new → delta flow) without ever clobbering a
+// spec that carries real content.
+function isUntouchedScaffold(specText, capability) {
+  const normalize = (s) =>
+    s.replace(/\r\n/g, "\n")
+      .split("\n")
+      .filter((line) => !/^\*\*Last updated:\*\*/.test(line))
+      .join("\n")
+      .trim();
+  try {
+    const tplPath = path.join(locateTemplatesDir(), "spec.md.template");
+    const rendered = read(tplPath)
+      .replace(/\{\{CAPABILITY\}\}/g, capability)
+      .replace(/\{\{DATE\}\}/g, "");
+    if (normalize(rendered) === normalize(specText)) return true;
+  } catch {
+    // fall through to the fingerprint heuristic
+  }
+  // Fingerprints: the Purpose placeholder comment AND an empty Ubiquitous
+  // section survive only in a scaffold nobody edited.
+  return (
+    specText.includes("<!-- One paragraph: what this capability does and why it exists. -->") &&
+    /##\s+Requirements \(EARS\)[\s\S]*?### Ubiquitous\s*\n\s*-\s*\n/.test(specText)
+  );
+}
+
 // Reasons a change is not finished enough to archive. Counts unchecked
 // GitHub-style checkboxes (`- [ ]`) in tasks.md (every task, including the
 // closing steps) and in the proposal's "## Verification" section. Returns
@@ -521,32 +811,52 @@ Usage: doctrina change <subcommand> [args]
 Subcommands:
   new <id> "<title>"     Open a new change proposal at .doctrina/changes/<id>/
                          (--chore / --no-spec: a spec-less change for infra /
-                         docs / build that still gets a proposal + ledger)
-  apply <id>             Apply spec deltas: ADDED writes, REMOVED deletes,
+                         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
+                         also REPLACES a target that is still the untouched
+                         \`spec new\` scaffold — the canonical new-capability
+                         flow; real content refuses), REMOVED deletes,
                          MODIFIED with an \`\`\`ops block is applied mechanically
                          (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)
   --chore, --no-spec     With new, open a spec-less chore change
+  --design               With new, also scaffold design.md (opt-in)
   --reason "<text>"      With abandon, the reason recorded in the ledger
 `;
 
 // Re-export parsers so scan.js (index rebuild) can reuse them, and the
 // scaffold so `work` can open a change without duplicating the logic.
-export { parseOperation, parseCapabilityFromDelta, changeNew };
+export { parseOperation, parseCapabilityFromDelta, changeNew, isUntouchedScaffold };

package/src/commands/clarify.js

@@ -2,10 +2,17 @@ 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";
 
-const RULES = [
+// 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*,
+// "TODO o pensamento" is the pronoun *todo* — which teaches people to ignore
+// the gate). The language comes from `.doctrina/config.json` ("language":
+// "pt-BR" | "en"), else a per-file stopword heuristic. Portuguese mode swaps
+// the ambiguous EN tokens for a PT lexicon; TODO only counts with a colon
+// ("TODO:") since bare TODO is the pronoun.
+const RULES_EN = [
   {
     // "may" is intentionally NOT in this list: EARS Optional grammar
     // uses "the system may ..." legitimately, and a clarify pass that
@@ -27,10 +34,74 @@ const RULES = [
   },
 ];
 
+const RULES_PT = [
+  {
+    name: "weasel",
+    re: /\b(talvez|possivelmente|provavelmente|aproximadamente|quem sabe|eventualmente)\b/gi,
+    hint: "afirme explicitamente, com um verbo definido",
+  },
+  {
+    // ASCII-folded variants included so "varios"/"vários" both match.
+    name: "vague",
+    re: /\b(muitos|muitas|poucos|poucas|v[aá]rios|v[aá]rias|alguns|algumas|adequado|adequada|robusto|robusta|escal[aá]vel)\b(?!\s+\d)/gi,
+    hint: "quantifique (um número ou um escopo preciso)",
+  },
+  {
+    // Bare TODO is the Portuguese pronoun; only TODO: is a marker here.
+    name: "placeholder",
+    re: /\b(TBD|FIXME|XXX|\?\?\?)\b|\bTODO:/g,
+    hint: "resolva antes de aplicar",
+  },
+];
+
+// Language for a file: the project-declared `.doctrina/config.json`
+// ("language": "pt-BR" / "pt" / "en") wins; otherwise a deterministic
+// stopword count over the file text decides. Never semantic (ADR 0005).
+const PT_STOPWORDS = /\b(que|n[aã]o|para|uma|como|mais|ser|quando|est[aá]|s[aã]o|pela|pelo|dos|das|ou seja|deve)\b/gi;
+const EN_STOPWORDS = /\b(the|and|that|with|shall|when|this|from|are|not|for|must)\b/gi;
+
+function projectLanguage(projectRoot) {
+  const cfgPath = path.join(projectRoot, ".doctrina", "config.json");
+  if (isFile(cfgPath)) {
+    try {
+      const lang = String(JSON.parse(read(cfgPath))?.language ?? "").toLowerCase();
+      if (lang.startsWith("pt")) return "pt";
+      if (lang.startsWith("en")) return "en";
+    } catch { /* fall through to detection */ }
+  }
+  return null;
+}
+
+function detectLang(text) {
+  const pt = (text.match(PT_STOPWORDS) ?? []).length;
+  const en = (text.match(EN_STOPWORDS) ?? []).length;
+  return pt > en ? "pt" : "en";
+}
+
+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;
+}
+
 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) {
@@ -46,7 +117,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}`);
   }
@@ -65,7 +136,7 @@ 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.");
   }
@@ -92,7 +163,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);
@@ -110,19 +181,27 @@ function clarifyAll(projectRoot) {
   return 1;
 }
 
-function scanFile(fullPath) {
+function scanFile(fullPath, projectRoot = process.cwd(), lang = null) {
   const text = read(fullPath);
   const skippedRanges = collectSkippedRanges(text);
+  const rules = rulesFor(projectRoot, text, lang);
   const smells = [];
 
-  // Per-line rules: regex pass with skip-range filter.
+  // Per-line rules: regex pass with skip-range filter. A line carrying the
+  // inline suppression marker `<!-- clarify:ok -->` is deliberately accepted
+  // by the author — skip it entirely (the escape hatch for a false positive
+  // the lexicon cannot know about; "block, never imprison").
   const lines = text.split("\n");
   let cursor = 0;
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
     const lineStart = cursor;
     const lineEnd = cursor + line.length;
-    for (const rule of RULES) {
+    if (line.includes("clarify:ok")) {
+      cursor = lineEnd + 1;
+      continue;
+    }
+    for (const rule of rules) {
       rule.re.lastIndex = 0;
       let m;
       while ((m = rule.re.exec(line))) {
@@ -192,14 +271,21 @@ 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: --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
 (immutable) and the archive (history) are excluded. CI-friendly.