doctrina-cli 0.20.0 → 0.22.0

package/src/commands/clarify.js

@@ -5,112 +5,9 @@ import { readdirSync } from "node:fs";
 import { exists, isDir, isFile, read, relPath, walk } from "../lib/fs-ops.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
-import { detectLanguage } from "../lib/lexicon.js";
-import { loadConfig } from "../lib/config.js";
+import { scanFile } from "../lib/clarify-scan.js";
 import { EXIT, 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*,
-// "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
-    // flags every EARS Optional is unusable on Doctrina-style specs.
-    // The remaining weasel terms are unambiguous.
-    name: "weasel",
-    re: /\b(might|could|should\s+probably|perhaps|maybe|approximately|roughly)\b/gi,
-    hint: "state explicitly with a definite verb",
-  },
-  {
-    name: "vague",
-    // Two exclusions, both structural rather than a vocabulary loosening.
-    // The lookahead was already here: `many 5` quantifies. The lookbehind is
-    // change 0079: `how many` is INTERROGATIVE, and a requirement that says
-    // "shall report how many contracts declared no rows" names exactly the
-    // number the command must print — the opposite of vague. Five of this
-    // repository's seventeen smells were that phrase, and the noise is what
-    // hid the one real finding among them ("name some of them", which said
-    // nothing about how many). A gate that cries wolf teaches people to
-    // ignore it.
-    //
-    // The quality adjectives sit here for the same reason the quantifiers do:
-    // "robust" names no threshold, so it cannot be met or missed. They were
-    // in the Portuguese lexicon and nowhere in this one, so the SAME sentence
-    // translated came back with three smells in one language and none in the
-    // other — and this project keeps its own pages in both. A smell test that
-    // answers differently per language is not testing the writing.
-    re: /(?<!\bhow\s+)\b(many|few|some|several|adequate|robust|scalable)\b(?!\s+\d)/gi,
-    hint: "quantify (use a number or a precise scope)",
-  },
-  {
-    name: "placeholder",
-    re: /\b(TBD|TODO|FIXME|XXX|\?\?\?)\b/g,
-    hint: "resolve before applying",
-  },
-];
-
-// How much of the previous line a rule may look back into. Long enough for
-// a wrapped two-word phrase, short enough that the probe stays cheap.
-const LOOKBEHIND_TAIL = 40;
-
-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).
-
-function projectLanguage(projectRoot) {
-  // One configuration reader (lib/config.js, change 0047): the key still
-  // lives in .doctrina/config.json, but `doctor` can now show what it
-  // resolved to, which is what a pt-BR project sitting red needed.
-  return loadConfig(projectRoot).language;
-}
-
-// Which lexicon a document is written in — the shared detector (change
-// 0040), so `clarify` and any future consumer count the same grammar words.
-function detectLang(text) {
-  return detectLanguage(text);
-}
-
-function rulesFor(projectRoot, text, forcedLang = null) {
-  const lang = forcedLang ?? projectLanguage(projectRoot);
-  if (lang) return lang === "pt" ? RULES_PT : RULES_EN;
-  // Detected per file, the document is scanned with BOTH lexicons (change
-  // 0107). A bilingual spec — Portuguese purpose, English EARS, or the
-  // reverse — detected as one language hid every smell written in the
-  // other: `clarify --all` found nothing where `--lang pt` found two. The
-  // two vocabularies do not overlap, so a smell in either is a smell; the
-  // detected language only decides which hint text the reader gets first.
-  const detected = detectLang(text);
-  const [first, second] = detected === "pt" ? [RULES_PT, RULES_EN] : [RULES_EN, RULES_PT];
-  // The `placeholder` rule is language-neutral and lives in both lists:
-  // one copy, or TBD is reported twice.
-  return [...first, ...second.filter((r) => r.name !== "placeholder")];
-}
-
 // --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" —
@@ -118,7 +15,7 @@ function rulesFor(projectRoot, text, forcedLang = null) {
 // guessing; persist it with .doctrina/config.json { "language": "pt-BR" }.
 function forcedLang(flags) {
   const raw = flagString(flags, "lang");
-  if (!raw || raw === true) return null;
+  if (!raw) return null;
   const lang = String(raw).toLowerCase();
   if (lang.startsWith("pt")) return "pt";
   if (lang.startsWith("en")) return "en";
@@ -176,7 +73,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, lang = null) {
+function clarifyAll(projectRoot, lang = /** @type {string | null} */ (null)) {
   if (!exists(path.join(projectRoot, ".doctrina"))) {
     throw notADoctrinaProject();
   }
@@ -221,106 +118,6 @@ function clarifyAll(projectRoot, lang = null) {
   return 1;
 }
 
-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. 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;
-    if (line.includes("clarify:ok")) {
-      cursor = lineEnd + 1;
-      continue;
-    }
-    // A rule reads the previous line as CONTEXT, never as content: a match
-    // is only reported when it starts inside this line. Prose wraps, and
-    // "report per spec how / many criteria..." split the interrogative
-    // across a line break — which a line-at-a-time scanner cannot see, so
-    // the phrase came back as a smell on one line of the same document and
-    // not on the next (change 0079). The prefix is trimmed to the tail of
-    // the previous line: enough for a lookbehind, cheap on every line.
-    const prev = i > 0 ? lines[i - 1].slice(-LOOKBEHIND_TAIL) : "";
-    const probe = prev === "" ? line : `${prev}\n${line}`;
-    const offset = probe.length - line.length;
-    for (const rule of rules) {
-      rule.re.lastIndex = 0;
-      let m;
-      while ((m = rule.re.exec(probe))) {
-        if (m.index < offset) continue;   // the match belongs to the previous line
-        const absoluteStart = lineStart + m.index - offset;
-        if (isInSkippedRange(absoluteStart, skippedRanges)) continue;
-        smells.push({
-          line: i + 1,
-          rule: rule.name,
-          token: m[0],
-          hint: rule.hint,
-        });
-      }
-    }
-    cursor = lineEnd + 1; // +1 for the newline
-  }
-
-  // Section rule: empty Acceptance criteria.
-  if (hasEmptyAcceptanceCriteria(text)) {
-    smells.push({
-      line: findAcceptanceLine(text),
-      rule: "empty-section",
-      token: "Acceptance criteria",
-      hint: "fill in observable, verifiable signals",
-    });
-  }
-
-  smells.sort((a, b) => a.line - b.line);
-  return smells;
-}
-
-// Build ranges to skip: fenced code blocks, HTML comments, inline backticks.
-function collectSkippedRanges(text) {
-  const ranges = [];
-  // Fenced code blocks (``` ... ```)
-  for (const m of text.matchAll(/```[\s\S]*?```/g)) ranges.push([m.index, m.index + m[0].length]);
-  // HTML comments (<!-- ... -->)
-  for (const m of text.matchAll(/<!--[\s\S]*?-->/g)) ranges.push([m.index, m.index + m[0].length]);
-  // Inline backtick spans (`...`)
-  for (const m of text.matchAll(/`[^`\n]+`/g)) ranges.push([m.index, m.index + m[0].length]);
-  return ranges;
-}
-
-function isInSkippedRange(offset, ranges) {
-  for (const [a, b] of ranges) if (offset >= a && offset < b) return true;
-  return false;
-}
-
-function hasEmptyAcceptanceCriteria(text) {
-  const headingRe = /^##\s+Acceptance criteria\s*$/m;
-  const m = headingRe.exec(text);
-  if (!m) return false;
-  const after = text.slice(m.index + m[0].length);
-  // Find the body between this heading and the next heading of equal level.
-  const nextHeadingMatch = after.match(/^##\s+/m);
-  const body = nextHeadingMatch ? after.slice(0, nextHeadingMatch.index) : after;
-  // Strip HTML comments before checking emptiness.
-  const stripped = body.replace(/<!--[\s\S]*?-->/g, "").trim();
-  return stripped.length === 0;
-}
-
-function findAcceptanceLine(text) {
-  const lines = text.split("\n");
-  for (let i = 0; i < lines.length; i++) {
-    if (/^##\s+Acceptance criteria\s*$/.test(lines[i])) return i + 1;
-  }
-  return 1;
-}
-
 export const help = `
 Usage: doctrina clarify <path> [--lang pt|en]
        doctrina clarify --all [--lang pt|en]

package/src/commands/close.js

@@ -463,7 +463,7 @@ async function closeOne(projectRoot, id, flags) {
     if (isFile(ledgerPath)) {
       // Written in the ledger's own entry grammar (change 0046): a waived
       // gate no reader can find is the same as an unrecorded one.
-      appendLedgerLine(projectRoot, docsGapLine(id, docsGap.signals));
+      appendLedgerLine(projectRoot, docsGapLine(id, /** @type {{ signals: string[] }} */ (/** @type {unknown} */ (docsGap)).signals));
       console.log(c.yellow("ledger") + " recorded the docs gap");
     }
   }

package/src/commands/context.js

@@ -14,7 +14,9 @@ import { GIT_STATE, historyState, changedFiles } from "../lib/git.js";
 import { terms as queryTerms, relevance } from "../lib/lexicon.js";
 import { notADoctrinaProject, EXIT } from "../lib/exit-codes.js";
 import * as idx from "../lib/index-json.js";
-import { adrDigest, sliceSpec } from "../lib/context-slice.js";
+import { adrDigest, sliceSpec, withoutComments } from "../lib/context-slice.js";
+import { contextRouting, workspaceActions, workspaceFindings, workspaceHandoff, workspaceRootAt, workspaceSnapshot, workspaceStatus } from "../lib/workspace-view.js";
+import { cdThen, qarg } from "../lib/shell.js";
 
 // Materialise the AGENTS.md read order as a command: print the exact
 // context pack for a task, in the order an agent should read it. This is
@@ -85,6 +87,21 @@ export async function run(positional, cmdFlags) {
   const diffRef = flagString(cmdFlags, "diff");
   const query = flagString(cmdFlags, "for");
   const projectRoot = process.cwd();
+  // At a workspace root there is no one spec tree to read: the pack is per
+  // repository. Name which repositories the task is about, and the command
+  // that reads each one's pack (change 0230).
+  const wsRoot = workspaceRootAt(projectRoot);
+  if (wsRoot) {
+    const ranked = contextRouting(workspaceSnapshot(wsRoot), query ?? capability ?? "");
+    console.log(c.bold("The context pack is read inside a repository.") + c.gray(query ? ` Projects for "${query}":` : " Projects:"));
+    for (const r of ranked) {
+      const mark = r.state === "ready" ? "" : c.yellow(` (${r.state})`);
+      console.log(`  ${r.name.padEnd(16)} ${query ? c.gray(`${r.score} shared term${r.score === 1 ? "" : "s"}${r.shared.length ? ` (${r.shared.slice(0, 5).join(", ")})` : ""}`) : ""}${mark}`);
+      console.log(`    ${c.cyan(cdThen(r.path, `doctrina context ${capability ?? "<capability>"}${query ? ` --for ${qarg(query)}` : ""} --concat`))}`);
+    }
+    if (ranked.length === 0) console.log(c.gray("  none registered — `doctrina workspace add <path>`"));
+    return 0;
+  }
   if (!exists(path.join(projectRoot, ".doctrina"))) {
     throw notADoctrinaProject();
   }
@@ -319,7 +336,17 @@ export async function run(positional, cmdFlags) {
     for (const ch of open) {
       if (ch.id === focusId) {
         // The change being worked on: every file, whole, in CORE.
-        for (const f of ch.files) pushFile(relPath(projectRoot, f), `open change: ${ch.id}`);
+        for (const f of ch.files) {
+          const item = pushFile(relPath(projectRoot, f), `open change: ${ch.id}`);
+          // Read, not written: the templates' authoring comments stay out
+          // unless --full (change 0228).
+          const bare = item && !full ? withoutComments(read(f)) : null;
+          if (item && bare !== null) {
+            item.slice = bare;
+            item.tokens = estimateTokens(bare);
+            item.note = `${item.note} — comments left out`;
+          }
+        }
         continue;
       }
       // A PARKED change is ONE entry in a queue, not three documents. It
@@ -749,6 +776,10 @@ active spec), open changes, accepted ADRs. Skills are
 listed name + description + when-trigger only — they are on-demand by
 design. The change archive is excluded.
 
+At a workspace root, where no one spec tree exists, it ranks the
+registered projects against --for and prints the command that reads
+each one's pack inside its repository.
+
 The pack is LEAN by default: AGENTS.md is not repeated (your agent
 loads it every turn), an accepted ADR is a digest — its title and the
 opening of its Decision; \`doctrina show NNNN\` reads the rest — and

package/src/commands/contract.js

@@ -278,6 +278,7 @@ the port map, the environment contract, and API/WS/event interfaces.
 
 Subcommands:
   new <name>          Scaffold .doctrina/contracts/<name>.md and index it
+                      (--force overwrites an existing contract)
   list                One line per contract: id, status, last updated
   check [<name>]      Verify the mechanically checkable parts.
 

package/src/commands/coverage.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import process from "node:process";
 import { spawnSync } from "node:child_process";
 import { exists, isFile, read, relPath } from "../lib/fs-ops.js";
+import { propertyCandidates, projectPropertyLibrary } from "../lib/properties.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { emitJson } from "../lib/json-out.js";
@@ -39,7 +40,7 @@ export { collect, summarize, deriveImplementation, derivedImplementations, imple
 // wrap it in the generic envelope.
 export const jsonNative = true;
 
-export const flags = { boolean: ["json", "run", "strict"], string: ["only"] };
+export const flags = { boolean: ["json", "run", "strict", "properties"], string: ["only"] };
 
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
@@ -77,6 +78,11 @@ export async function run(_positional, flags) {
     }
   }
 
+  // --properties: which requirements read as claims about EVERY input, and
+  // so ask for a property-based test (change 0254). A readout, exit 0: it
+  // proposes; the `[property]` mark on a criterion is what the gate enforces.
+  if (flagBool(flags, "properties", false)) return listProperties(projectRoot, only, json);
+
   const reports = collect(projectRoot, { only });
 
   // --run: execute the cited evidence instead of only checking it exists —
@@ -153,8 +159,8 @@ export async function run(_positional, flags) {
         if (r.unverified) {
           console.log(`    ${c.gray("○")} #${r.n}  proof resolves but the criterion is still marked [unverified] — flip the mark when the test proves it (spec set <cap> --criterion ${r.n}:verified)`);
         }
-        if (r.missing?.length > 0) {
-          console.log(`    ${c.yellow("!")} #${r.n}  also cites evidence that does not resolve: ${r.missing.map((m) => `\`${m}\``).join(", ")}`);
+        if ((r.missing ?? []).length > 0) {
+          console.log(`    ${c.yellow("!")} #${r.n}  also cites evidence that does not resolve: ${(r.missing ?? []).map((m) => `\`${m}\``).join(", ")}`);
         }
         continue;
       }
@@ -165,9 +171,9 @@ export async function run(_positional, flags) {
       } else if (r.kind === "conditional") {
         console.log(`    ${c.yellow("!")} #${r.n}  evidence is a skipped test (proves nothing): ${r.skipped.map((m) => `\`${m}\``).join(", ")}`);
       } else if (r.kind === "unguarded") {
-        console.log(`    ${c.red("✗")} #${r.n}  orchestration claim is not fail-closed: ${r.reason}`);
+        console.log(`    ${c.red("✗")} #${r.n}  ${r.label ?? "orchestration claim is not fail-closed"}: ${r.reason}`);
       } else {
-        console.log(`    ${c.yellow("!")} #${r.n}  evidence not found on disk: ${r.missing.map((m) => `\`${m}\``).join(", ")}`);
+        console.log(`    ${c.yellow("!")} #${r.n}  evidence not found on disk: ${(r.missing ?? []).map((m) => `\`${m}\``).join(", ")}`);
       }
     }
   }
@@ -250,8 +256,49 @@ function runEvidence(projectRoot, reports, strict) {
 }
 
 
+const CANDIDATES_SHOWN = 5;
+
+function listProperties(projectRoot, only, json) {
+  const caps = propertyCandidates(projectRoot, { only });
+  const lib = projectPropertyLibrary(projectRoot);
+  if (json) {
+    emitJson("coverage", { properties: caps, library: lib });
+    return 0;
+  }
+  const total = caps.reduce((n, cap) => n + cap.candidates.length, 0);
+  const proven = caps.reduce((n, cap) => n + cap.properties, 0);
+  console.log(c.bold("Property candidates") + c.gray(" — requirements that claim something of every input"));
+  console.log("");
+  if (total === 0) {
+    console.log(c.gray("no requirement here reads as an invariant (always/never, at most, unique, round trip, twice, in order)"));
+    return 0;
+  }
+  for (const cap of caps) {
+    if (cap.candidates.length === 0) continue;
+    console.log(`${c.cyan(cap.cap)}  ${cap.candidates.length} requirement${cap.candidates.length === 1 ? "" : "s"} read${cap.candidates.length === 1 ? "s" : ""} as invariant${cap.candidates.length === 1 ? "" : "s"}, ` +
+      `${cap.properties} criteri${cap.properties === 1 ? "on is a property" : "a are properties"}`);
+    for (const cand of cap.candidates.slice(0, CANDIDATES_SHOWN)) {
+      const text = cand.text.length > 110 ? `${cand.text.slice(0, 107)}…` : cand.text;
+      console.log(`    ${cand.ref.padEnd(13)} ${text}`);
+      console.log(c.gray(`    ${"".padEnd(13)} ${cand.shape}: ${cand.property}`));
+    }
+    if (cap.candidates.length > CANDIDATES_SHOWN) {
+      console.log(c.gray(`    … and ${cap.candidates.length - CANDIDATES_SHOWN} more — doctrina coverage --properties --only ${cap.cap} --json`));
+    }
+  }
+  console.log("");
+  console.log(`${total} candidate${total === 1 ? "" : "s"}, ${proven} propert${proven === 1 ? "y" : "ies"} claimed. A candidate is a reading of the words, not a verdict: choose the ones whose failure would be a bug.`);
+  const where = lib
+    ? `${lib.name}${lib.declared ? "" : " (not declared by this project yet — add it as a test dependency)"}`
+    : "the property library of the project's language";
+  console.log(`Write each as a test that generates its inputs with ${where}, then claim it:`);
+  console.log(c.cyan("  doctrina change delta <id> <capability> --property \"<what holds for every input> — verified by \`<the property test>\`\""));
+  console.log(c.gray("A criterion marked [property] counts as proven only when the test it cites is property-based."));
+  return 0;
+}
+
 export const help = `
-Usage: doctrina coverage [--strict] [--only <cap,cap>] [--run] [--json]
+Usage: doctrina coverage [--strict] [--only <cap,cap>] [--run] [--properties] [--json]
 
 Report how many acceptance criteria across .doctrina/specs/ cite an
 artifact or test that exists on disk. Each numbered criterion may cite
@@ -277,6 +324,22 @@ That check must declare an "expect" guard (see \`doctrina verify --help\`).
 A cited check with no guard is reported UNGUARDED and fails --strict: a
 check that exits 0 having run nothing would otherwise satisfy the claim.
 
+PROPERTY criteria. A requirement that claims something of EVERY input —
+"never returns a code already in use", "at most 100 items", "decoding
+gives back what was encoded" — is not proven by three examples. Mark the
+criterion [property] and cite a property-based test:
+
+  4. [property] no two codes collide, whatever the URLs —
+     verified by \`tests/test_codes_property.py\`
+
+It counts as covered only when that test generates its inputs
+(Hypothesis @given, fast-check fc.property, jqwik @Property, proptest,
+rapid, FsCheck, ScalaCheck); cited to an example test it is reported and
+fails --strict. \`doctrina coverage --properties\` lists, per capability,
+the requirements whose words read as an invariant, the property each
+suggests and the library this project would write it with — a readout,
+never a gate.
+
 A spec that declares a deliberate deferral —
 \`Implementation: planned — <why>\`, the same escape hatch validate
 honours — has its unproven criteria reported as DEFERRED: visible, but