doctrina-cli 0.15.1 → 0.16.0

package/src/commands/prime.js

@@ -1,14 +1,11 @@
 // @ts-check
 import path from "node:path";
 import process from "node:process";
-import { readdirSync } from "node:fs";
-import { exists, isDir, isFile, read } from "../lib/fs-ops.js";
-import { listHeader } from "../lib/scan.js";
-import { collectStatus } from "./status.js";
-import { computeActions } from "./next.js";
-import { acceptedDecisions, productSection } from "./constitution.js";
-import { c } from "../lib/colors.js";
+import { exists } from "../lib/fs-ops.js";
+import { flagBool } from "../lib/args.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
+import { collectSnapshot } from "../lib/snapshot.js";
+import { renderView } from "../lib/views.js";
 
 // Session primer: the ~40-line read that orients an agent at the start of a
 // session — where things stand, what the standing rules are, what work is
@@ -16,102 +13,30 @@ import { notADoctrinaProject } from "../lib/exit-codes.js";
 // It sits between `status` (numbers only) and `context --concat` (everything):
 // enough to act, cheap enough to run every session. Strictly read-only; every
 // line is assembled from artifacts that already own the fact (no new home).
+//
+// Since change 0037 the primer is a VIEW over lib/snapshot.js, rendered by
+// lib/views.js and reachable as `doctrina status --view prime`. This module
+// is the name AGENTS.md tells agents to run, and nothing else: no collection,
+// no formatting, and nothing for another command to import out of.
 
 // 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"], string: [] };
+export const flags = { boolean: ["json", "rules"], string: [] };
 
-export async function run(_positional, _flags) {
+export async function run(_positional, flags) {
   const projectRoot = process.cwd();
   if (!exists(path.join(projectRoot, ".doctrina"))) {
     throw notADoctrinaProject();
   }
-
-  const s = collectStatus(projectRoot);
-
-  console.log(c.bold("Doctrina prime") + c.gray(` — ${s.project}  (framework ${s.stamp ?? "—"} / CLI ${s.cli})`));
-  console.log("");
-
-  // One-line gate digest.
-  const cov = `${s.coverage.pct}% (${s.coverage.totalCovered}/${s.coverage.totalCriteria})`;
-  const tr = s.trace.anchors === 0 ? "no anchors" : `${s.trace.realized}/${s.trace.anchors}`;
-  const verify = s.verify.configured ? `${s.verify.checks} verify checks` : "verify not configured";
-  console.log(c.bold("Gates  ") + `index ${s.indexState} · coverage ${cov} · trace ${tr} · ${verify}`);
-  const implBreak = Object.entries(s.specs.impl).map(([k, v]) => `${v} ${k}`).join(", ");
-  console.log(
-    c.bold("Work   ") +
-      `${s.specs.total} specs${implBreak ? ` (${implBreak})` : ""} · ${s.specs.openChanges} open change${s.specs.openChanges === 1 ? "" : "s"} · ` +
-      `${s.decisions.total} decisions · ${s.skills} skills`,
-  );
-
-  // Standing rules, titles only — `constitution` has the full text.
-  const adrs = acceptedDecisions(projectRoot);
-  console.log("");
-  console.log(c.bold("Rules") + c.gray(`  (${adrs.length} accepted ADRs — \`doctrina constitution\` for detail)`));
-  for (const a of adrs) console.log(`  ${c.cyan(a.id)}  ${a.title}`);
-  const nonGoals = productSection(projectRoot, "Non-goals");
-  if (nonGoals.length > 0) {
-    console.log(c.gray(`  + ${nonGoals.length} non-goal${nonGoals.length === 1 ? "" : "s"} declared in product.md`));
-  }
-
-  // Open work, with unchecked-task counts — the resume points.
-  console.log("");
-  console.log(c.bold("Open work"));
-  const open = openChanges(projectRoot);
-  if (open.length === 0) {
-    console.log(c.gray("  none — `doctrina work \"<prompt>\"` opens the next change"));
-  } else {
-    for (const ch of open) {
-      const tasks = ch.tasksTotal > 0 ? ` · tasks ${ch.tasksDone}/${ch.tasksTotal}` : "";
-      console.log(`  ${c.cyan(ch.id)}  ${ch.title ?? ""}${c.gray(` (${ch.status}${tasks})`)}`);
-    }
-  }
-
-  // Next actions (top 5 — `doctrina next` for the full list).
-  const actions = computeActions(projectRoot);
-  console.log("");
-  console.log(c.bold("Next"));
-  if (actions.length === 0) {
-    console.log(c.gray("  nothing pending — pick up new work"));
-  } else {
-    actions.slice(0, 5).forEach((a, i) => console.log(`  ${i + 1}. ${a}`));
-    if (actions.length > 5) console.log(c.gray(`  … ${actions.length - 5} more — \`doctrina next\``));
-  }
-
-  console.log("");
-  console.log(c.gray("Read deeper: `doctrina context [<cap>] --concat` · `doctrina why <cap>` · `doctrina show <ref>`"));
+  // --rules: the standing rules in full, which is what `constitution` printed
+  // (change 0049). The primer names the ADRs and counts the non-goals; this
+  // prints both lists, from the same collection, so the two cannot disagree.
+  const view = flagBool(flags, "rules", false) ? "rules" : "prime";
+  for (const line of renderView(view, collectSnapshot(projectRoot))) console.log(line);
   return 0;
 }
 
-// Open changes with their proposal status/title and task progress.
-export function openChanges(projectRoot) {
-  const changesDir = path.join(projectRoot, ".doctrina", "changes");
-  const out = [];
-  if (!isDir(changesDir)) return out;
-  for (const id of readdirSync(changesDir).sort()) {
-    if (id === "archive" || id.startsWith(".")) continue;
-    if (!isDir(path.join(changesDir, id))) continue;
-    const proposalPath = path.join(changesDir, id, "proposal.md");
-    const proposal = isFile(proposalPath) ? read(proposalPath) : null;
-    const title = proposal?.match(/^#\s+(?:Change\s+[^—-]*[—-]\s*)?(.+)$/m)?.[1]?.trim() ?? null;
-    const status = proposal ? (listHeader(proposal, "Status") ?? "proposed") : "no proposal.md";
-    const tasksPath = path.join(changesDir, id, "tasks.md");
-    let tasksDone = 0, tasksTotal = 0, unchecked = [];
-    if (isFile(tasksPath)) {
-      for (const line of read(tasksPath).split(/\r?\n/)) {
-        const m = line.match(/^-\s+\[([ xX])\]\s+(.*)$/);
-        if (!m) continue;
-        tasksTotal += 1;
-        if (m[1] === " ") unchecked.push(m[2].trim());
-        else tasksDone += 1;
-      }
-    }
-    out.push({ id, title, status, tasksDone, tasksTotal, unchecked });
-  }
-  return out;
-}
-
 export const help = `
 Usage: doctrina prime
 
@@ -120,6 +45,14 @@ titles + non-goal count), open work with task progress, and the top
 next actions — the ~40-line read that orients an agent at session
 start without paying for the full context pack.
 
+The same view as \`doctrina status --view prime\`; both render one
+collection of the tree, so they cannot disagree.
+
+  --rules   Print the standing rules in full instead of the primer: every
+            accepted ADR and every declared non-goal. The same lines
+            \`doctrina constitution\` printed, from the same collection —
+            that command is deprecated and delegates here.
+
 Read-only; always exits 0. Deeper reads: \`doctrina context\`,
 \`doctrina why <cap>\`, \`doctrina show <ref>\`.
 `;

package/src/commands/report.js

@@ -1,24 +1,30 @@
 // @ts-check
 import path from "node:path";
 import process from "node:process";
-import { spawnSync } from "node:child_process";
 import { exists } from "../lib/fs-ops.js";
-import * as idx from "../lib/index-json.js";
-import { collectStatus } from "./status.js";
-import { openChanges } from "./prime.js";
-import { flagString } from "../lib/args.js";
-import { today } from "../lib/dates.js";
+import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
+import { collectSnapshot } from "../lib/snapshot.js";
+import { renderView } from "../lib/views.js";
+import { gitWindow, historyState, windowCutoff } from "../lib/git.js";
+import { draftAgentChangelog, renderDraft } from "../lib/agent-changelog.js";
+import { collectMetrics } from "../lib/metrics-model.js";
+import { cliVersion } from "../lib/version.js";
 
 // Periodic digest in Markdown — the standup/PR-description view: what was
 // archived, where the gates stand, and what local git says about the period.
 // Read-only, no network; the git section degrades silently outside a repo.
+//
+// Since change 0037 it is a VIEW over the shared snapshot (lib/snapshot.js →
+// lib/views.js), also reachable as `doctrina status --view report --since N`,
+// and its two git probes go through lib/git.js rather than a private
+// spawnSync that could read a refusal as an empty answer.
 
 // 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"], string: ["since"] };
+export const flags = { boolean: ["json", "agent-changelog"], string: ["since"] };
 
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
@@ -26,117 +32,42 @@ export async function run(_positional, flags) {
     throw notADoctrinaProject();
   }
 
-  const sinceRaw = flagString(flags, "since") ?? "7";
-  const days = Number.parseInt(sinceRaw, 10);
+  const sinceRaw = flagString(flags, "since");
+  const days = Number.parseInt(sinceRaw ?? "7", 10);
   if (!Number.isFinite(days) || days <= 0) {
     console.error(c.red("error:") + ` --since expects a positive day count, got "${sinceRaw}"`);
     return 2;
   }
-  const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
-  const cutoffIso = cutoff.toISOString().slice(0, 10);
 
-  const s = collectStatus(projectRoot);
-
-  console.log(`# Doctrina report — ${s.project} (${cutoffIso} → ${today()})`);
-  console.log("");
-
-  // Gates.
-  console.log("## Gates");
-  console.log("");
-  console.log(`- index: ${s.indexState} · framework stamp: ${s.stamp ?? "—"} (CLI ${s.cli})`);
-  console.log(`- coverage: ${s.coverage.pct}% (${s.coverage.totalCovered}/${s.coverage.totalCriteria} criteria)` +
-    (s.coverage.totalDangling ? ` — ${s.coverage.totalDangling} dangling` : "") +
-    (s.coverage.totalConditional ? ` — ${s.coverage.totalConditional} conditional` : ""));
-  console.log(`- trace: ${s.trace.anchors === 0 ? "no anchors declared" : `${s.trace.realized}/${s.trace.anchors} anchors realized`}`);
-  console.log(`- verify: ${s.verify.configured ? `${s.verify.checks} checks declared` : "not configured"}`);
-
-  // Work shipped in the window (from the index ledger) + work in flight.
-  console.log("");
-  console.log("## Changes");
-  console.log("");
-  const archived = archivedSince(projectRoot, cutoffIso);
-  if (archived.length === 0) {
-    console.log(`- archived in period: none`);
-  } else {
-    console.log(`- archived in period: ${archived.length}`);
-    for (const ch of archived) console.log(`  - ${ch.applied} — \`${ch.id}\` ${ch.title}`);
-  }
-  const open = openChanges(projectRoot);
-  if (open.length === 0) {
-    console.log("- open now: none");
-  } else {
-    console.log(`- open now: ${open.length}`);
-    for (const ch of open) {
-      const tasks = ch.tasksTotal > 0 ? ` (tasks ${ch.tasksDone}/${ch.tasksTotal})` : "";
-      console.log(`  - \`${ch.id}\`${ch.title ? ` ${ch.title}` : ""}${tasks}`);
-    }
+  // --agent-changelog: a DRAFT of the block `upgrade --write` writes into
+  // AGENTS.md, proposed from what the archived changes said they touched.
+  // A different report for a different audience — five bullets for an
+  // arriving agent, not a digest for a standup — so it replaces the view
+  // rather than appending to it. Authorship stays human (ADR 0005): the
+  // command proposes, a person cuts and rewrites.
+  if (flagBool(flags, "agent-changelog", false)) {
+    const draft = draftAgentChangelog(projectRoot, { days: sinceRaw === undefined ? null : days });
+    for (const line of renderDraft(draft, cliVersion())) console.log(line);
+    return 0;
   }
 
-  // Artifact counts, for trend-watching between reports.
-  console.log("");
-  console.log("## Artifacts");
-  console.log("");
-  console.log(`- specs: ${s.specs.total} · decisions: ${s.decisions.total}` +
-    (s.decisions.proposed ? ` (${s.decisions.proposed} proposed)` : "") +
-    ` · skills: ${s.skills}`);
-
-  // Local git window — commits, fix share, top churn. No network.
-  console.log("");
-  console.log("## Git (local, last " + days + " days)");
-  console.log("");
-  const git = gitWindow(projectRoot, days);
-  if (!git) {
-    console.log("- no git history available (not a repository, or git not installed)");
-  } else {
-    console.log(`- commits: ${git.commits} (${git.fixes} fix-shaped, ${git.commits ? Math.round((git.fixes / git.commits) * 100) : 0}%)`);
-    if (git.churn.length > 0) {
-      console.log(`- top-churn files:`);
-      for (const [file, n] of git.churn) console.log(`  - ${file} (${n} touches)`);
-    }
-  }
-
-  console.log("");
-  console.log(`*Generated read-only by \`doctrina report --since ${days}\`; deeper numbers: \`doctrina metrics\`.*`);
+  const options = {
+    days,
+    cutoffIso: windowCutoff(days),
+    git: gitWindow(projectRoot, days),
+    // Why there is no window, when there is none — the same door `metrics`
+    // and `context` already ask, so the three cannot disagree about the
+    // state of one repository (change 0080).
+    gitState: historyState(projectRoot),
+    // The same snapshot `metrics` renders, for the same window (change
+    // 0050). One definition of "revert rate", so the digest and the metrics
+    // command cannot report two different numbers for one period.
+    metrics: collectMetrics(projectRoot, `${days} days ago`),
+  };
+  for (const line of renderView("report", collectSnapshot(projectRoot), options)) console.log(line);
   return 0;
 }
 
-function archivedSince(projectRoot, cutoffIso) {
-  let index;
-  try {
-    index = idx.load(projectRoot);
-  } catch {
-    return [];
-  }
-  return (index.artifacts?.changes_archive ?? [])
-    .filter((ch) => typeof ch.applied === "string" && ch.applied >= cutoffIso)
-    .sort((a, b) => String(a.applied).localeCompare(String(b.applied)));
-}
-
-function gitWindow(projectRoot, days) {
-  const log = spawnSync("git", ["log", `--since=${days} days ago`, "--pretty=%s"], {
-    cwd: projectRoot,
-    encoding: "utf8",
-  });
-  if (log.status !== 0) return null;
-  const subjects = log.stdout.split(/\r?\n/).filter((l) => l.trim().length > 0);
-  const fixes = subjects.filter((sub) => /^(fix|bug|hotfix|patch)(\(|:|!)/i.test(sub)).length;
-
-  const files = spawnSync("git", ["log", `--since=${days} days ago`, "--name-only", "--pretty=format:"], {
-    cwd: projectRoot,
-    encoding: "utf8",
-  });
-  const counts = new Map();
-  if (files.status === 0) {
-    for (const line of files.stdout.split(/\r?\n/)) {
-      const f = line.trim();
-      if (!f) continue;
-      counts.set(f, (counts.get(f) ?? 0) + 1);
-    }
-  }
-  const churn = [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5);
-  return { commits: subjects.length, fixes, churn };
-}
-
 export const help = `
 Usage: doctrina report [--since <days>]
 
@@ -146,4 +77,15 @@ work with task progress, artifact counts, and a local-git summary
 (commits, fix share, top-churn files). Made for standups and PR
 descriptions. Read-only; no network. \`doctrina metrics\` has the
 deeper git-derived numbers.
+
+The same view as \`doctrina status --view report --since <days>\`.
+
+  --agent-changelog   Draft the AGENTS.md "What changed" block instead of
+                      the digest: one candidate bullet per archived change
+                      that touched a documented surface (a command, a flag,
+                      an exit code), newest first, capped at the block's
+                      five bullets. The window is "since the last tag"
+                      unless --since names one. It PROPOSES; a person cuts
+                      and rewrites, because what an agent must do
+                      differently is a judgement the CLI does not make.
 `;

package/src/commands/review.js

@@ -1,16 +1,17 @@
 // @ts-check
 import path from "node:path";
 import process from "node:process";
-import { spawnSync } from "node:child_process";
 import { readdirSync } from "node:fs";
 import { exists, isDir, isFile, read } from "../lib/fs-ops.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
-import { rankCapabilitiesByDiff } from "./work.js";
-import { parseDependsOn } from "../lib/scan.js";
-import { notADoctrinaProject } from "../lib/exit-codes.js";
-import { summarize as coverageSummary } from "./coverage.js";
-import { summarize as traceSummary } from "./trace.js";
+import { rankCapabilitiesByDiff } from "../lib/work-model.js";
+import { readLedger, churnByCapability } from "../lib/ledger.js";
+import { changedFiles, windowCutoff, historyState, refExists } from "../lib/git.js";
+import { dependentsOf } from "../lib/scan.js";
+import { notADoctrinaProject, EXIT } from "../lib/exit-codes.js";
+import { summarize as coverageSummary } from "../lib/coverage-model.js";
+import { summarize as traceSummary } from "../lib/trace-model.js";
 
 // Deterministic conformance review (review 2026-06-27 passive-user feature #3).
 // Given the working tree (or a diff against a ref), report STRUCTURAL breaks
@@ -25,6 +26,17 @@ import { summarize as traceSummary } from "./trace.js";
 // 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).
+// How far back the churn note looks, and how many landed changes make it
+// worth saying at all. A window rather than "all time": a capability that
+// moved nine times two years ago is history, not news.
+const CHURN_WINDOW_DAYS = 60;
+const CHURN_NOTABLE = 3;
+
+// How many unclaimed files the orphan note names before it summarises the
+// rest. Long enough to act on, short enough that a wide refactor does not
+// bury every other finding under a file listing.
+const ORPHAN_LIST_LIMIT = 5;
+
 export const flags = { boolean: ["json", "strict"], string: ["diff"] };
 
 export async function run(_positional, flags) {
@@ -35,7 +47,20 @@ export async function run(_positional, flags) {
   const strict = flagBool(flags, "strict", false);
   const against = flagString(flags, "diff"); // optional git ref to diff against
 
-  const { all, sourceFiles } = changedFiles(projectRoot, against);
+  // A ref the git cannot resolve is a filter that matches nothing, and the
+  // review used to read it as "nothing changed" — exit 0, `--strict`
+  // included, on a tree where a valid ref reported breaks. A CI job running
+  // `doctrina review --diff main --strict` stayed green forever on a shallow
+  // clone with no local `main` (change 0092). Only asked inside a usable
+  // repository: outside one the command still stays silent rather than
+  // accusing.
+  if (against && historyState(projectRoot).usable && !refExists(projectRoot, against)) {
+    console.error(c.red("error:") + ` --diff names a ref this repository cannot resolve: "${against}"`);
+    console.error(c.gray("hint: ") + "check the branch or commit name — a ref that resolves to nothing is not an empty diff");
+    return EXIT.USAGE;
+  }
+
+  const { all, sourceFiles } = reviewScope(projectRoot, against);
   console.log(c.bold("Review") + c.gray(against ? ` — vs ${against}` : " — working-tree changes"));
   console.log("");
 
@@ -69,23 +94,39 @@ export async function run(_positional, flags) {
   // 1b. Dependents of touched capabilities (the machine-readable
   //     **Depends on:** header): a spec that builds on something you changed
   //     may silently no longer hold. Advisory — a pointer, not a verdict.
-  const specsDir = path.join(projectRoot, ".doctrina", "specs");
-  if (isDir(specsDir) && touched.size > 0) {
-    for (const cap of readdirSync(specsDir).sort()) {
-      if (touched.has(cap)) continue;
-      const specPath = path.join(specsDir, cap, "spec.md");
-      if (!isFile(specPath)) continue;
-      const deps = parseDependsOn(read(specPath)).filter((d) => touched.has(d));
-      if (deps.length > 0) {
-        notes.push(`capability "${cap}" depends on touched ${deps.map((d) => `"${d}"`).join(", ")} — confirm it still holds (\`doctrina why ${cap}\`)`);
-      }
+  for (const dep of dependentsOf(projectRoot, touched)) {
+    notes.push(`capability "${dep.capability}" depends on touched ${dep.dependsOn.map((d) => `"${d}"`).join(", ")} — confirm it still holds (\`doctrina why ${dep.capability}\`)`);
+  }
+
+  // 1c. How often each touched capability has moved lately, from the archive
+  //     ledger (change 0046). Reported as a NUMBER and never as a verdict:
+  //     frequent change can mean a spec that was drawn badly or a spec that
+  //     is simply where the work is, and nothing here can tell those apart
+  //     (ADR 0005). It is context for the human reading the review, not a
+  //     finding — so it goes in the notes even when the count is high.
+  if (touched.size > 0) {
+    const since = windowCutoff(CHURN_WINDOW_DAYS);
+    const churn = churnByCapability(readLedger(projectRoot).entries, { since })
+      .filter((row) => touched.has(row.capability) && row.changes >= CHURN_NOTABLE);
+    for (const row of churn) {
+      notes.push(`capability "${row.capability}" landed ${row.changes} changes in the last ${CHURN_WINDOW_DAYS} days (last ${row.last}) — history, not a verdict: read it as "this area is moving", not "this area is wrong"`);
     }
   }
 
-  // 2. New source files that map to no capability at all — code with no home
-  //    in any spec (a likely new, unspecced capability).
-  if (ranked.length === 0 && sourceFiles.length > 0) {
-    notes.push(`changed code maps to no existing capability spec — if this is a new capability, scaffold it: \`doctrina spec new <capability>\` (or \`doctrina work --from-diff\`)`);
+  // 2. Changed source files that map to no capability at all — code with no
+  //    home in any spec. Reported PER FILE (change 0077): the old form fired
+  //    only when the WHOLE diff matched nothing, so one incidental match —
+  //    any file under `docs/`, which matches the `docs` capability because
+  //    the directory is named after it — silenced the finding for every other
+  //    file in the change. A review of an adapter change reported
+  //    "Capabilities touched: docs" and said nothing about the adapter.
+  const orphans = sourceFiles.filter(
+    (f) => rankCapabilitiesByDiff(projectRoot, [f], { limit: 1 }).length === 0,
+  );
+  if (orphans.length > 0) {
+    const shown = orphans.slice(0, ORPHAN_LIST_LIMIT).map((f) => `\`${f}\``).join(", ");
+    const more = orphans.length > ORPHAN_LIST_LIMIT ? `, and ${orphans.length - ORPHAN_LIST_LIMIT} more` : "";
+    notes.push(`${orphans.length} changed file(s) belong to no capability: ${shown}${more} — claim them with a \`**Source:**\` header on the owning spec, or scaffold the capability they are (\`doctrina spec new <capability>\`)`);
   }
 
   // 3. Coverage — acceptance criteria whose cited proof is missing/skipped.
@@ -133,21 +174,12 @@ export async function run(_positional, flags) {
 }
 
 // Changed paths between a base (a git ref, or HEAD + untracked for the working
-// tree) and now. Returns the full list and the subset outside .doctrina/.
-function changedFiles(projectRoot, against) {
-  const run = (args) => {
-    const r = spawnSync("git", args, { cwd: projectRoot, encoding: "utf8" });
-    if (r.error || r.status !== 0) return [];
-    return r.stdout.split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
-  };
-  const set = new Set();
-  if (against) {
-    for (const f of run(["diff", "--name-only", against])) set.add(f);
-  } else {
-    for (const f of run(["diff", "--name-only", "HEAD"])) set.add(f);
-    for (const f of run(["ls-files", "--others", "--exclude-standard"])) set.add(f);
-  }
-  const all = [...set];
+// tree) and now, split into the full list and the subset outside .doctrina/.
+// The git question itself goes through the one door (lib/git.js).
+function reviewScope(projectRoot, against) {
+  // Against a named ref, untracked files are noise: the question is what this
+  // branch changed, not what is lying around uncommitted.
+  const all = changedFiles(projectRoot, { since: against, untracked: !against }).files;
   const sourceFiles = all.filter((f) => !f.replace(/\\/g, "/").startsWith(".doctrina/"));
   return { all, sourceFiles };
 }

package/src/commands/search.js

@@ -4,6 +4,7 @@ import process from "node:process";
 import { exists, isDir, read, relPath, walk } from "../lib/fs-ops.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
+import { fold } from "../lib/lexicon.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
 
 // Category-aware full-text search across the artifact tree. Answers
@@ -25,7 +26,13 @@ const MAX_MATCHES_PER_FILE = 5;
 export const flags = { boolean: ["json", "archive"], string: [] };
 
 export async function run(positional, flags) {
-  const terms = positional.map((t) => t.toLowerCase()).filter(Boolean);
+  // Folded, not merely lowercased (third audit, finding 8). `search` matched
+  // raw substrings, so an accent decided the answer: `search patrimonio`
+  // found nothing in a spec that says "patrimônio" — and typing without the
+  // accent is the common case, not the rare one. The shared lexicon (ADR
+  // 0040) already folds for `work` and `context --for`; `search` was the
+  // one retrieval surface still deciding on its own.
+  const terms = positional.map((t) => fold(t)).filter(Boolean);
   if (terms.length === 0) {
     console.error(c.red("error:") + " search requires at least one term");
     return 2;
@@ -64,7 +71,7 @@ export async function run(positional, flags) {
       const hits = [];
       for (let i = 0; i < lines.length; i++) {
         const raw = lines[i];
-        const low = raw.toLowerCase();
+        const low = fold(raw);
         if (terms.every((t) => low.includes(t))) {
           hits.push({ line: i + 1, text: raw.trim(), score: lineScore(raw, low, phrase) });
         }
@@ -92,7 +99,14 @@ export async function run(positional, flags) {
 
   if (totalMatches === 0) {
     console.log(c.gray(`no matches for "${positional.join(" ")}"${includeArchive ? "" : " (archive excluded; pass --archive to include it)"}`));
-    return 1;
+    // Not finding is the answer, not a failure. Exit 1 is GATE in the
+    // five-class contract — "fix the work, retry the same command" — and
+    // this command fixes nothing. The `insight` spec says it outright: a
+    // VIEW assembles what is there and never refuses anything, and the
+    // other six listings (spec, decision, skill, contract, templates,
+    // intent) all exit 0 on an empty result. The grep convention is a
+    // shell habit; this CLI declared its own contract (change 0093).
+    return 0;
   }
   console.log(c.gray(`${totalMatches} match${totalMatches === 1 ? "" : "es"} in ${filesWithMatches} file${filesWithMatches === 1 ? "" : "s"}`));
   return 0;
@@ -116,7 +130,7 @@ function lineScore(raw, low, phrase) {
 // A file whose name carries the query is almost always the right one;
 // reward a full filename match more than a partial one.
 function filenameBonus(rel, terms) {
-  const base = rel.toLowerCase();
+  const base = fold(rel);
   if (terms.every((t) => base.includes(t))) return 3;
   return terms.some((t) => base.includes(t)) ? 1 : 0;
 }

package/src/commands/show.js

@@ -6,7 +6,8 @@ import { exists, isDir, isFile, read, relPath } from "../lib/fs-ops.js";
 import { parseAcceptanceCriteria } from "../lib/criteria.js";
 import { suggest } from "../lib/suggest.js";
 import { c } from "../lib/colors.js";
-import { notADoctrinaProject } from "../lib/exit-codes.js";
+import { notADoctrinaProject, EXIT } from "../lib/exit-codes.js";
+import { maskComments } from "../lib/doc-model.js";
 
 // Point reads. An agent that needs ONE requirement re-reads a whole spec —
 // hundreds of lines for a two-line fact. `show` resolves a compact reference
@@ -57,7 +58,7 @@ function showAdr(projectRoot, num) {
   const file = isDir(dir) ? readdirSync(dir).find((f) => f.startsWith(`${num}-`) && f.endsWith(".md")) : null;
   if (!file) {
     console.error(c.red("error:") + ` no ADR ${num} under .doctrina/decisions/`);
-    return 1;
+    return EXIT.USAGE;
   }
   const full = path.join(dir, file);
   console.log(c.gray(`— ${relPath(projectRoot, full)} —`));
@@ -79,7 +80,7 @@ function loadSpec(projectRoot, cap) {
 
 function showSpecHead(projectRoot, cap) {
   const spec = loadSpec(projectRoot, cap);
-  if (!spec) return 1;
+  if (!spec) return EXIT.USAGE;
   const lines = spec.text.split(/\r?\n/);
   const out = [];
   let mode = "head"; // header block -> seek Purpose -> purpose body -> stop
@@ -98,14 +99,14 @@ function showSpecHead(projectRoot, cap) {
 
 function showSpecItem(projectRoot, cap, kind, n) {
   const spec = loadSpec(projectRoot, cap);
-  if (!spec) return 1;
+  if (!spec) return EXIT.USAGE;
 
   if (kind === "C") {
     const criteria = parseAcceptanceCriteria(spec.text);
     const crit = criteria.find((r) => r.n === n);
     if (!crit) {
       console.error(c.red("error:") + ` ${cap} has no acceptance criterion #${n} (it declares ${criteria.length})`);
-      return 1;
+      return EXIT.USAGE;
     }
     console.log(c.gray(`— ${cap}-C${n} · ${relPath(projectRoot, spec.specPath)} · ## Acceptance criteria —`));
     console.log(`${n}. ${crit.body}`);
@@ -119,7 +120,7 @@ function showSpecItem(projectRoot, cap, kind, n) {
   const req = reqs[n - 1];
   if (!req) {
     console.error(c.red("error:") + ` ${cap} has no requirement R${n} (it declares ${reqs.length})`);
-    return 1;
+    return EXIT.USAGE;
   }
   console.log(c.gray(`— ${cap}-R${n} · ${relPath(projectRoot, spec.specPath)} · ${req.section} —`));
   console.log(req.text);
@@ -129,7 +130,13 @@ function showSpecItem(projectRoot, cap, kind, n) {
 // Top-level bullets of the "## Requirements (EARS)" section, in file order,
 // each with its `### <grammar>` sub-section name and continuation lines.
 export function parseRequirements(text) {
-  const lines = text.split(/\r?\n/);
+  // The scaffolded spec writes the five-line EARS legend as bullets inside
+  // an HTML comment under `## Requirements (EARS)`. Counted as content, the
+  // legend became R1..R5 and the capability's first real requirement was R6
+  // — on every spec `doctrina spec new` had ever created. Comments are
+  // blanked by position (same offsets, same line count), so the numbering
+  // below is over authored bullets only.
+  const lines = maskComments(text).split(/\r?\n/);
   const out = [];
   let inSection = false;
   let sub = "";
@@ -175,6 +182,14 @@ Point-read one artifact fragment instead of a whole file:
   doctrina show 0007       ADR 0007 (the whole decision)
   doctrina show cli        the spec's header block + Purpose only
 
-R-refs are positional (they shift when a requirement is inserted above);
-C-refs use the criteria's own numbers. Read-only.
+R-refs are positional across the WHOLE spec, in file order, and they shift
+when a requirement is inserted above. C-refs use the criteria's own numbers.
+Both count authored content only — a bullet inside an HTML comment (the
+scaffold's EARS legend, for one) is annotation and is never numbered.
+
+A spec delta's replace-requirement <section> <n> numbers differently, and
+on purpose: it counts WITHIN one "### <section>", so the number stays put
+when another section grows. doctrina show <cap>-RN prints the section it
+landed in, which is what turns an R-ref into the delta's pair of coordinates.
+Read-only.
 `;