doctrina-cli 0.11.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doctrina-cli",
-  "version": "0.11.0",
+  "version": "0.12.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];
@@ -74,8 +75,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

@@ -67,9 +67,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 +145,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`);
@@ -275,6 +290,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 +504,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,8 +587,12 @@ 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.
@@ -544,9 +614,10 @@ A MODIFIED delta may carry a fenced operations block that \`apply\` executes:
 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

@@ -5,7 +5,14 @@ import { exists, isDir, isFile, read, relPath, walk } from "../lib/fs-ops.js";
 import { flagBool } 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,6 +34,56 @@ 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) {
+  const declared = projectLanguage(projectRoot);
+  const lang = declared ?? detectLang(text);
+  return lang === "pt" ? RULES_PT : RULES_EN;
+}
+
 export async function run(positional, flags) {
   const projectRoot = process.cwd();
 
@@ -110,19 +167,27 @@ function clarifyAll(projectRoot) {
   return 1;
 }
 
-function scanFile(fullPath) {
+function scanFile(fullPath, projectRoot = process.cwd()) {
   const text = read(fullPath);
   const skippedRanges = collectSkippedRanges(text);
+  const rules = rulesFor(projectRoot, text);
   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))) {
@@ -200,6 +265,13 @@ 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.
+
 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.

package/src/commands/close.js

@@ -1,8 +1,9 @@
 import path from "node:path";
 import process from "node:process";
-import { exists, isFile } from "../lib/fs-ops.js";
+import { exists, isFile, read, walk } from "../lib/fs-ops.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
+import { parseCapabilityFromDelta } from "./change.js";
 import * as analyze from "./analyze.js";
 import * as change from "./change.js";
 import * as verify from "./verify.js";
@@ -30,9 +31,21 @@ export async function run(positional, flags) {
   }
 
   const force = flagBool(flags, "force", false);
-  const strict = new Map([["strict", true]]);
   const archiveFlags = force ? new Map([["force", true]]) : new Map();
 
+  // Scope the coverage gate to the capabilities THIS change touches (its
+  // deltas), so one deliberately deferred spec elsewhere in the tree cannot
+  // block closing a change that never went near it (0.11.0 field review
+  // item 4). A change with no deltas (chore / metadata-only) falls back to
+  // the whole-tree gate — there is no narrower honest scope for it.
+  const touched = touchedCapabilities(projectRoot, id);
+  const coverageFlags = new Map([["strict", true]]);
+  let coverageRerun = "doctrina coverage --strict";
+  if (touched.length > 0) {
+    coverageFlags.set("only", touched.join(","));
+    coverageRerun = `doctrina coverage --strict --only ${touched.join(",")}`;
+  }
+
   // Each step: a label, the command that runs it, and the literal command to
   // rerun on failure. verify is conditional (skipped, with a loud note, when no
   // verify.json is declared — a project may not have wired the real gate yet).
@@ -43,7 +56,11 @@ export async function run(positional, flags) {
     verifyConfigured
       ? { label: "verify", rerun: "doctrina verify", run: () => verify.run([], new Map()) }
       : { label: "verify", skip: "no .doctrina/verify.json — declare the real gate with `doctrina verify --init`" },
-    { label: "coverage", rerun: "doctrina coverage --strict", run: () => coverage.run([], strict) },
+    {
+      label: touched.length > 0 ? `coverage (scoped: ${touched.join(", ")})` : "coverage",
+      rerun: coverageRerun,
+      run: () => coverage.run([], coverageFlags),
+    },
     // trace is advisory (provenance is a warning, not a hard gate): report it,
     // never let it block the close.
     { label: "trace", rerun: "doctrina trace", run: async () => { await trace.run([], new Map()); return 0; } },
@@ -84,19 +101,35 @@ export async function run(positional, flags) {
   return 0;
 }
 
+// The capabilities this change's deltas target — the honest scope for its
+// coverage gate. Read from the change folder's specs/**/delta.md files.
+function touchedCapabilities(projectRoot, id) {
+  const specsDir = path.join(projectRoot, ".doctrina", "changes", id, "specs");
+  const caps = new Set();
+  for (const deltaPath of walk(specsDir)) {
+    if (!deltaPath.endsWith("delta.md")) continue;
+    const cap = parseCapabilityFromDelta(read(deltaPath), deltaPath);
+    if (cap) caps.add(cap);
+  }
+  return [...caps].sort();
+}
+
 export const help = `
 Usage: doctrina close <id> [--force]
 
 Run the whole closing sequence for a change in one pass, stopping at the
 first failure with the exact command to rerun:
 
-  analyze → change apply → verify → coverage --strict → trace → change
-  archive → validate
+  analyze → change apply → verify → coverage --strict (scoped to the
+  change's touched capabilities) → trace → change archive → validate
 
-verify is skipped (with a note) when no .doctrina/verify.json is declared;
-trace is advisory (a report, never a blocker). This is a driver over the
-existing commands — it adds no checks of its own — so the agent makes one
-call instead of seven and the human approves once.
+The coverage gate is scoped to the capabilities the change's deltas touch,
+so a deliberately deferred spec elsewhere cannot block an unrelated close;
+a change with no deltas gates on the whole tree. verify is skipped (with a
+note) when no .doctrina/verify.json is declared; trace is advisory (a
+report, never a blocker). This is a driver over the existing commands — it
+adds no checks of its own — so the agent makes one call instead of seven
+and the human approves once.
 
 Options:
   --force    Pass through to \`change archive\` (archive even if verification

package/src/commands/context.js

@@ -3,7 +3,7 @@ import process from "node:process";
 import { readdirSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { exists, isDir, isFile, read, relPath, walk } from "../lib/fs-ops.js";
-import { listHeader } from "../lib/scan.js";
+import { listHeader, parseDependsOn } from "../lib/scan.js";
 import { parseFrontmatter } from "./skill.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
@@ -80,6 +80,15 @@ export async function run(positional, flags) {
     const specRel = `.doctrina/specs/${capability}/spec.md`;
     if (isFile(path.join(projectRoot, specRel))) {
       pushFile(specRel, `spec: ${capability}`);
+      // Pull the declared dependencies into the pack (the machine-readable
+      // **Depends on:** header): a task on `risk-map` that builds on
+      // `reporting` needs both truths in one read. One level deep,
+      // deterministic, no cycles (each spec is pushed at most once).
+      for (const dep of parseDependsOn(read(path.join(projectRoot, specRel)))) {
+        if (dep === capability) continue;
+        const depRel = `.doctrina/specs/${dep}/spec.md`;
+        if (isFile(path.join(projectRoot, depRel))) pushFile(depRel, `dependency of ${capability}`);
+      }
     } else {
       specMissing = true;
     }