doctrina-cli 0.18.0 → 0.21.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" —
@@ -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

@@ -1,7 +1,7 @@
 // @ts-check
 import path from "node:path";
 import process from "node:process";
-import { appendFileSync } from "node:fs";
+import { appendFileSync, readdirSync } from "node:fs";
 import { exists, isDir, isFile, read } from "../lib/fs-ops.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
@@ -166,6 +166,8 @@ async function closeOne(projectRoot, id, flags) {
   // archive), which is rendering, not sequencing.
   const verifyConfigured = isFile(path.join(projectRoot, ".doctrina", "verify.json"));
   const runners = {
+    // An applied change resumes here: analyze asks it only the integrity
+    // checks (change 0221).
     analyze: { run: () => analyze.run([id], new Map()) },
 
     // ADR checkpoint (operator review §4.6): the playbook's "record an ADR"
@@ -468,6 +470,13 @@ async function closeOne(projectRoot, id, flags) {
 
   console.log("");
   console.log(c.green(`✓ change ${id} closed`) + c.gray(closingClaim(ran, skippedSteps)));
+  // Where it went, and the sentence for the human (change 0214): the close
+  // moves the change out of every default read, and a field review found
+  // the person asking for "the doctrina work" of work already archived.
+  const archived = archivedPathOf(projectRoot, id);
+  if (archived) {
+    console.log(c.bold("Tell the human: ") + `change ${id} is closed — archived at ${archived}`);
+  }
   console.log(c.gray("Next: ") + c.cyan("doctrina next"));
   return 0;
 }
@@ -500,6 +509,14 @@ function closingClaim(ran, skippedSteps) {
   return `${claimed || " —"} ${skipped.length === 1 ? "Skipped" : "Skipped"}: ${skipped.join(", ")}.`;
 }
 
+// The archive folder a just-closed change landed in, newest first.
+function archivedPathOf(projectRoot, id) {
+  const dir = path.join(projectRoot, ".doctrina", "changes", "archive");
+  if (!isDir(dir)) return null;
+  const name = readdirSync(dir).sort().reverse().find((n) => n.endsWith(`-${id}`) && /^\d{4}-\d{2}-\d{2}-/.test(n));
+  return name ? `.doctrina/changes/archive/${name}/` : null;
+}
+
 function missingRunner(step) {
   console.error(c.red("error:") +
     ` "${step.label}" is declared in the close sequence but has no runner here`);

package/src/commands/context.js

@@ -14,6 +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, 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
@@ -72,15 +75,33 @@ export const TIER = { CORE: 0, SPEC: 1, CHANGE: 2, DEPENDENCY: 3, DECISION: 4 };
 // 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", "concat"], string: ["budget", "diff", "for"] };
+export const flags = { boolean: ["json", "concat", "full"], string: ["budget", "diff", "for"] };
 
 export async function run(positional, cmdFlags) {
   const capability = positional[0] ?? null;
   const concat = flagBool(cmdFlags, "concat", false);
+  // --full: the whole text of everything, as before change 0216 — AGENTS.md
+  // repeated, every spec and ADR whole. The lean pack is the default.
+  const full = flagBool(cmdFlags, "full", false);
   const budgetRaw = flagString(cmdFlags, "budget");
   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();
   }
@@ -162,6 +183,8 @@ export async function run(positional, cmdFlags) {
       tier: TIER.CORE,
       rank: [],
       degraded: false,
+      /** @type {string | null} */ slice: null,
+      /** @type {string | null} */ digest: null,
       ...extra,
     };
     pack.push(item);
@@ -170,7 +193,10 @@ export async function run(positional, cmdFlags) {
 
   // 1-2. Root rules and product truth — always first. Displayed paths are
   // POSIX strings (path.join would emit backslashes on Windows).
-  if (wanted("AGENTS.md")) pushFile("AGENTS.md", "root rules");
+  // AGENTS.md is not repeated by default (change 0216): every agent this
+  // pack is for loads it already — natively, or through its adapter — and
+  // it cost ~2.5k tokens per pack to say it twice.
+  if (wanted("AGENTS.md") && full) pushFile("AGENTS.md", "root rules");
   if (wanted(".doctrina/product.md")) pushFile(".doctrina/product.md", "product truth");
 
   // 3. The capability spec(s) — the current truth. With a named capability,
@@ -241,6 +267,21 @@ export async function run(positional, cmdFlags) {
     }
   }
 
+  // A spec read for a task — the task's own, and the ones it depends on — is
+  // cut to what the task is about (change
+  // 0216): headers, Purpose, and the requirements and criteria the query
+  // matches, the rest named by count. No query, or nothing matched: whole.
+  if (!full && terms.length > 0) {
+    for (const item of pack) {
+      if ((item.tier !== TIER.CORE && item.tier !== TIER.DEPENDENCY) || !item.rel.startsWith(".doctrina/specs/")) continue;
+      const sliced = sliceSpec(read(path.join(projectRoot, item.rel)), terms, item.rel);
+      if (!sliced) continue;
+      item.slice = sliced.text;
+      item.tokens = estimateTokens(sliced.text);
+      item.note = `${item.note} — sliced: ${sliced.kept} of ${sliced.total} items match`;
+    }
+  }
+
   // 4. Open changes (their proposal, tasks, and deltas) — never
   //    diff-filtered: work in flight is the one thing a resuming agent
   //    cannot reconstruct from anywhere else, so it is always present.
@@ -295,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
@@ -347,7 +398,7 @@ export async function run(positional, cmdFlags) {
 
     const id = path.basename(f).match(/^(\d{4})-/)?.[1] ?? "0000";
     const title = getTitle(text) ?? path.basename(f, ".md");
-    pushFile(rel, global ? "accepted ADR" : `accepted ADR (${scope.join(", ")})`, {
+    const adrItem = pushFile(rel, global ? "accepted ADR" : `accepted ADR (${scope.join(", ")})`, {
       tier: TIER.DECISION,
       // Best-first, deterministic: an ADR that NAMES this capability outranks
       // an unscoped one — which is DECLARED to belong in every pack — which in
@@ -360,6 +411,13 @@ export async function run(positional, cmdFlags) {
       title,
       summary: adrSummary(text),
     });
+    // A decision as a digest by default (change 0216): its title and the
+    // opening of its Decision — what tells a reader whether it binds the
+    // task. Sixteen whole ADRs were ~22k tokens of the `gates` pack.
+    if (adrItem && !full) {
+      adrItem.digest = adrDigest(text, title, id);
+      adrItem.tokens = estimateTokens(adrItem.digest);
+    }
   }
 
   // 6. Skills are on-demand: list name + description + trigger, never the
@@ -406,7 +464,8 @@ export async function run(positional, cmdFlags) {
     for (const item of kept) {
       console.log(`===== ${item.rel} (${item.note}) =====`);
       console.log("");
-      console.log(item.degraded ? degradedBody(item) : read(path.join(projectRoot, item.rel)).trimEnd());
+      console.log(item.degraded ? degradedBody(item)
+        : item.slice ?? item.digest ?? read(path.join(projectRoot, item.rel)).trimEnd());
       console.log("");
     }
     // Keep the pack pipeable: the budget verdict goes to stderr.
@@ -417,7 +476,7 @@ export async function run(positional, cmdFlags) {
     console.log(c.bold("Context pack") + (capability ? c.gray(` (capability: ${capability})`) : "") + forNote + scope + c.gray(" — read in this order:"));
     console.log("");
     kept.forEach((item, i) => {
-      const mark = item.degraded ? c.yellow(" summary") : "        ";
+      const mark = item.degraded ? c.yellow(" summary") : item.slice ? c.yellow("  sliced") : item.digest ? c.yellow("  digest") : "        ";
       console.log(`${String(i + 1).padStart(2)}. ${c.cyan(item.rel.padEnd(56))} ${String(item.lines).padStart(4)} lines ${c.gray(`~${String(item.tokens).padStart(5)} tok`)}${mark}  ${c.gray(item.note)}`);
     });
     console.log("");
@@ -709,14 +768,25 @@ function changedPaths(projectRoot, ref) {
 
 export const help = `
 Usage: doctrina context [<capability>] [--for "<task>"] [--concat]
-                        [--budget <tokens>] [--diff <ref>]
+                        [--budget <tokens>] [--diff <ref>] [--full]
 
 Print the exact context pack for a task, in the documented read
-order: AGENTS.md, product.md, the capability spec (when given —
-otherwise every active spec), open changes, accepted ADRs. Skills are
+order: product.md, the capability spec (when given — otherwise every
+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
+with --for the task's spec is sliced to its headers, Purpose and the
+requirements and criteria the task matches, the others named by count.
+--full restores every text whole.
+
 Assembly is retrieval, not a dump. A token budget ALWAYS applies
 (default ${DEFAULT_BUDGET}; set "context_budget": <n> in
 .doctrina/config.json, or pass --budget). Over budget, accepted ADRs
@@ -731,6 +801,8 @@ Flags:
                     the list — ready to pipe into an agent. The budget
                     verdict goes to stderr, keeping stdout pure.
   --budget <n>      Token ceiling for this call, overriding the project's.
+  --full            Every artifact whole: AGENTS.md included, specs not
+                    sliced, ADRs not digested (the pre-0.19 pack).
   --diff <ref>      Scope the stable artifacts (AGENTS.md, product.md,
                     specs, ADRs) to those changed since the git ref; open
                     changes are always included. The resume-session read.

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.