doctrina-cli 0.16.0 → 0.18.0

package/src/lib/spec-ops.js

@@ -117,6 +117,40 @@ function matchOpsBlock(text) {
   return null;
 }
 
+/** One op line, parsed by the grammar `apply` reads: `{ verb, ... }` or `{ verb, error }`. */
+export function parseOp(line) {
+  return parseOpLine(String(line).trim());
+}
+
+/**
+ * Append op lines to a delta's live `ops` block — creating the block at the
+ * end when there is none (change 0205). A `bump-version` line replaces the
+ * block's existing one instead of stacking a second bump on it. Pure.
+ *
+ * @param {string} deltaText
+ * @param {string[]} lines  already validated with `parseOp`
+ * @returns {string}
+ */
+export function insertOps(deltaText, lines) {
+  const ranges = commentRanges(deltaText);
+  const fenceRe = /^([ \t]*```[ \t]*ops[ \t]*\r?\n)([\s\S]*?)(^[ \t]*```[ \t]*$)/gm;
+  const bumps = lines.some((l) => parseOp(l).verb === "bump-version");
+  let m;
+  while ((m = fenceRe.exec(deltaText))) {
+    if (isInsideComment(ranges, m.index)) continue;
+    const kept = m[2].split(/\r?\n/).filter((l) => l.trim() !== "")
+      .filter((l) => !(bumps && parseOp(l).verb === "bump-version"));
+    // The bump goes last, where a reader looks for it.
+    const ordered = [...kept, ...lines].sort((a, b) =>
+      Number(parseOp(a).verb === "bump-version") - Number(parseOp(b).verb === "bump-version"));
+    const block = `${m[1]}${ordered.join("\n")}\n${m[3]}`;
+    return deltaText.slice(0, m.index) + block + deltaText.slice(m.index + m[0].length);
+  }
+  const ordered = [...lines].sort((a, b) =>
+    Number(parseOp(a).verb === "bump-version") - Number(parseOp(b).verb === "bump-version"));
+  return `${deltaText.replace(/\s*$/, "")}\n\n\`\`\`ops\n${ordered.join("\n")}\n\`\`\`\n`;
+}
+
 function parseOpLine(line) {
   // `<verb> <rest>` — the verb is the first whitespace-delimited token.
   const sp = line.indexOf(" ");
@@ -178,6 +212,24 @@ function parseOpLine(line) {
       if (!value) return { verb, error: `replace-requirement ${n} is missing the requirement text` };
       return { verb, section, n, value };
     }
+    case "remove-requirement": {
+      // remove-requirement <section> <n>[: <why>] — the reason is for the
+      // reader of the delta; the spec loses the bullet either way.
+      const colon = rest.indexOf(":");
+      const head = (colon < 0 ? rest : rest.slice(0, colon)).trim().split(/\s+/);
+      const n = Number(head[head.length - 1]);
+      const section = normalizeSection(head.slice(0, -1).join(" "));
+      if (!section) return { verb, error: `remove-requirement: unknown section "${head.slice(0, -1).join(" ")}" (use ${SECTION_TOKENS})` };
+      if (!Number.isInteger(n) || n < 1) return { verb, error: `remove-requirement needs "<section> <n>" with a positive bullet number (got "${rest}")` };
+      return { verb, section, n };
+    }
+    case "remove-criterion": {
+      // remove-criterion <n>[: <why>]
+      const colon = rest.indexOf(":");
+      const n = Number((colon < 0 ? rest : rest.slice(0, colon)).trim());
+      if (!Number.isInteger(n) || n < 1) return { verb, error: `remove-criterion needs a positive criterion number (got "${rest}")` };
+      return { verb, n };
+    }
     default:
       return { verb: null, error: `unknown operation "${verb}"` };
   }
@@ -238,6 +290,10 @@ function applyOne(text, op) {
       return appendRequirement(text, op.section, op.value);
     case "replace-requirement":
       return replaceRequirement(text, op.section, op.n, op.value);
+    case "remove-requirement":
+      return removeRequirement(text, op.section, op.n);
+    case "remove-criterion":
+      return removeCriterion(text, op.n);
     default:
       return { error: `unknown operation "${op.verb}"` };
   }
@@ -256,7 +312,10 @@ export function setHeader(text, name, value) {
   // has a lifecycle of its own (proposed -> applied, accepted, superseded).
   const listForm = /^\s*-/.test(text.match(re)?.[1] ?? "");
   const domain = listForm ? null : headerValueError(name, value);
-  if (domain) return { error: `set-header: ${domain}` };
+  // `cause: "argument"` marks an error about the value supplied, not about
+  // the document: `spec set` answers it as USAGE, a delta as a defect of
+  // the work (ADR 0018).
+  if (domain) return { error: `set-header: ${domain}`, cause: "argument" };
   const next = text.replace(re, (_m, prefix) => `${prefix} ${value}`.replace(/\s+$/, ""));
   return { text: next, summary: `set ${name}: ${value}` };
 }
@@ -309,10 +368,10 @@ export function setCriterionMark(text, n, markRaw) {
   const loc = locateCriteria(text);
   if (!loc) return { error: "set-criterion: spec has no '## Acceptance criteria' section" };
   const item = loc.items.find((it) => it.n === n);
-  if (!item) return { error: `set-criterion: no criterion #${n} found` };
+  if (!item) return { error: `set-criterion: no criterion #${n} found`, cause: "argument" };
   const mark = markRaw.replace(/^\[|\]$/g, "").trim();
   const domain = criterionMarkError(mark);
-  if (domain) return { error: `set-criterion: ${domain}` };
+  if (domain) return { error: `set-criterion: ${domain}`, cause: "argument" };
   const line = loc.lines[item.lineIndex];
   let next;
   if (/\[[^\]]*\]/.test(line)) {
@@ -331,10 +390,33 @@ export function replaceCriterion(text, n, value) {
   if (!loc) return { error: "replace-criterion: spec has no '## Acceptance criteria' section" };
   const item = loc.items.find((it) => it.n === n);
   if (!item) return { error: `replace-criterion: no criterion #${n} found` };
-  loc.lines[item.lineIndex] = `${item.indent}${n}. ${value}`;
+  // The whole item, continuation lines included (change 0206) — the lesson
+  // `replace-requirement` learned, which this verb never picked up: a
+  // criterion wrapped over three lines kept its old second and third lines
+  // under the new first one, so the spec stated a proof and then the
+  // previous proof's tail.
+  loc.lines.splice(item.lineIndex, endOfItem(loc.lines, item.lineIndex) - item.lineIndex + 1, `${item.indent}${n}. ${value}`);
   return { text: loc.lines.join("\n"), summary: `replace-criterion ${n}` };
 }
 
+// remove-criterion <n> — delete criterion n, continuation lines included,
+// and renumber the ones after it so the list stays 1..N (change 0206). A
+// spec only ever grew: there was no verb to take a criterion out, so a
+// superseded one stayed beside its replacement for good.
+export function removeCriterion(text, n) {
+  const loc = locateCriteria(text);
+  if (!loc) return { error: "remove-criterion: spec has no '## Acceptance criteria' section" };
+  const item = loc.items.find((it) => it.n === n);
+  if (!item) return { error: `remove-criterion: no criterion #${n} found` };
+  const end = endOfItem(loc.lines, item.lineIndex);
+  const lines = loc.lines;
+  for (const it of loc.items) {
+    if (it.n > n) lines[it.lineIndex] = lines[it.lineIndex].replace(/^(\s*)\d+\./, `$1${it.n - 1}.`);
+  }
+  lines.splice(item.lineIndex, end - item.lineIndex + 1);
+  return { text: lines.join("\n"), summary: `remove-criterion ${n} (${loc.items.length - n} renumbered)` };
+}
+
 // The `### <Section>` blocks under `## Requirements (EARS)`. Returns
 // { lines, sections: { <token>: { headingIndex, endIndex, bullets: [lineIndex] } } }
 // or null when the Requirements section is absent. A section's token is the
@@ -481,11 +563,44 @@ export function replaceRequirement(text, section, n, value) {
   if (n > real.length) {
     return { error: `replace-requirement: section "${section}" has ${real.length} requirement${real.length === 1 ? "" : "s"}, no #${n}` };
   }
-  const indent = loc.lines[real[n - 1]].match(/^(\s*)/)[1];
-  loc.lines[real[n - 1]] = `${indent}- ${value}`;
+  // REPLACE THE WHOLE ITEM, continuation lines included.
+  //
+  // Writing only the first line leaves the old bullet's wrapped prose sitting
+  // under the new one, indented, reading as part of it. That is not cosmetic:
+  // the orphan is the PREVIOUS version of the requirement, so the spec ends up
+  // stating a contract and then contradicting it two lines later, and a spec
+  // is the one artifact this framework asks everyone to trust.
+  //
+  // It had already happened four times in this repository's own tree before
+  // anyone noticed — twice in `gates` (a closing sequence missing its review
+  // and runtime steps, a doctor set missing its runtime row) and once in
+  // `insight`, all three describing older behaviour beside the current one.
+  //
+  // `append-requirement` learned this in 0.13.0 and got `endOfItem`; this verb
+  // was written afterwards and never picked it up.
+  const start = real[n - 1];
+  const indent = loc.lines[start].match(/^(\s*)/)[1];
+  loc.lines.splice(start, endOfItem(loc.lines, start) - start + 1, `${indent}- ${value}`);
   return { text: loc.lines.join("\n"), summary: `replace-requirement ${section} ${n}` };
 }
 
+// remove-requirement <section> <n> — delete the nth bullet (1-based) of the
+// EARS subsection, continuation lines included (change 0206). The heading
+// stays even when it empties: `append-requirement` can fill it again.
+export function removeRequirement(text, section, n) {
+  const loc = locateRequirements(text);
+  if (!loc) return { error: "remove-requirement: spec has no '## Requirements (EARS)' section" };
+  const sec = loc.sections[section];
+  if (!sec) return { error: `remove-requirement: no '### ${section}...' subsection found under Requirements` };
+  const real = sec.bullets.filter((i) => !/^\s*-\s*$/.test(loc.lines[i]));
+  if (n > real.length) {
+    return { error: `remove-requirement: section "${section}" has ${real.length} requirement${real.length === 1 ? "" : "s"}, no #${n}` };
+  }
+  const start = real[n - 1];
+  loc.lines.splice(start, endOfItem(loc.lines, start) - start + 1);
+  return { text: loc.lines.join("\n"), summary: `remove-requirement ${section} ${n}` };
+}
+
 // append-criterion <text> — add a new numbered criterion after the last one
 // in the section.
 export function appendCriterion(text, value) {
@@ -504,3 +619,23 @@ export function appendCriterion(text, value) {
   loc.lines.splice(endOfItem(loc.lines, last.lineIndex) + 1, 0, `${last.indent}${nextN}. ${value}`);
   return { text: loc.lines.join("\n"), summary: `append-criterion ${nextN}` };
 }
+
+/**
+ * The size of a spec, as `work --consolidate` reports it (change 0206):
+ * lines, real requirement bullets per EARS subsection, and criteria.
+ * @param {string} text
+ */
+export function specShape(text) {
+  const req = locateRequirements(text);
+  const sections = {};
+  let requirements = 0;
+  for (const token of EARS_ORDER) {
+    const sec = req?.sections[token];
+    if (!sec) continue;
+    const n = sec.bullets.filter((i) => !/^\s*-\s*$/.test(req.lines[i])).length;
+    sections[token] = n;
+    requirements += n;
+  }
+  const crit = locateCriteria(text);
+  return { lines: text.split(/\r?\n/).length, requirements, sections, criteria: crit ? crit.items.length : 0 };
+}

package/src/lib/templates-model.js

@@ -9,7 +9,7 @@ import { exists, isDir, isFile, lineCount, read, relPath, walk, write } from "./
 import { adapterFiles, isHubPointer, listAdapterNames } from "./adapters.js";
 import { readTemplate } from "./templates.js";
 import { PLAYBOOKS } from "./playbook.js";
-import { COMMAND_META, COMMAND_NAMES, SURFACE_LINE_BUDGET, surfaceBlock, surfaceMarkdown, findSurfaceBlock } from "./commands.js";
+import { COMMAND_META, COMMAND_NAMES, DEPRECATED, REMOVED, SURFACE_LINE_BUDGET, surfaceBlock, surfaceMarkdown, findSurfaceBlock } from "./commands.js";
 import { declaredBudget } from "./runtime.js";
 import { agentsMdBudget } from "./validation-model.js";
 /**
@@ -80,6 +80,16 @@ export const PRODUCT_SECTIONS = [
   "## Success criteria",
 ];
 
+// The first deprecated or removed operation a text tells you to run, as
+// `doctrina <op>`, or null.
+function retiredCommandIn(text) {
+  for (const op of [...Object.keys(DEPRECATED), ...Object.keys(REMOVED)]) {
+    const name = op.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    if (new RegExp(`doctrina ${name}(?![a-z-])`).test(text)) return op;
+  }
+  return null;
+}
+
 // The findings `templates check` reports, as structured records with an
 // executable remedy. Exported so a test can seed each finding, run the
 // remedy it names, and assert the finding clears — a remedy that cannot
@@ -111,16 +121,16 @@ export function collectFindings(projectRoot) {
             : ` — the ${missingSections.length} missing stub(s) cost ${budget.cost} lines and ` +
               `AGENTS.md has ${budget.slack} left of its declared ceiling`),
         remedy: budget.fits
-          ? "doctrina templates update --write"
-          : `cut ${budget.over} line(s) of prose from AGENTS.md, then \`doctrina templates update --write\``,
+          ? "doctrina upgrade --write"
+          : `cut ${budget.over} line(s) of prose from AGENTS.md, then \`doctrina upgrade --write\``,
       });
     }
     // Command-surface block: present and current vs the installed catalog.
     const block = findSurfaceBlock(text);
     if (!block) {
-      findings.push({ message: "AGENTS.md has no doctrina:surface block — agents discover commands through this file", remedy: "doctrina templates update --write" });
+      findings.push({ message: "AGENTS.md has no doctrina:surface block — agents discover commands through this file", remedy: "doctrina upgrade --write" });
     } else if (normalizeBlock(text.slice(block.start, block.end)) !== normalizeBlock(surfaceBlock())) {
-      findings.push({ message: "AGENTS.md doctrina:surface block is stale vs the installed CLI", remedy: "doctrina templates update --write" });
+      findings.push({ message: "AGENTS.md doctrina:surface block is stale vs the installed CLI", remedy: "doctrina upgrade --write" });
     } else {
       ok.push("AGENTS.md: doctrina:surface block current");
     }
@@ -134,7 +144,7 @@ export function collectFindings(projectRoot) {
     const text = read(productPath);
     for (const heading of PRODUCT_SECTIONS) {
       if (hasHeading(text, heading)) ok.push(`product.md: ${heading}`);
-      else findings.push({ message: `.doctrina/product.md missing recommended section "${heading}"`, remedy: "doctrina templates update --write" });
+      else findings.push({ message: `.doctrina/product.md missing recommended section "${heading}"`, remedy: "doctrina upgrade --write" });
     }
   } else {
     findings.push({ message: ".doctrina/product.md missing", remedy: "doctrina init --force" });
@@ -151,7 +161,24 @@ export function collectFindings(projectRoot) {
     for (const file of spec.files) {
       const installed = path.join(projectRoot, file.relativePath);
       if (!isFile(installed)) continue; // not installed — nothing to check
-      if (!isHubPointer(file)) continue; // command shim, not a pointer
+      if (!isHubPointer(file)) {
+        // A command shim is copied into the project once, so an upgrade
+        // of the CLI leaves it teaching whatever the CLI taught then: the
+        // 0.16 `/doctrina-work` still ran `analyze` → `change apply` after
+        // 0.17 deprecated one and handed the other to the close (change
+        // 0187). A shim naming a retired command is stale; the same rewrite
+        // from the template that repairs a pointer repairs it.
+        const retired = retiredCommandIn(read(installed));
+        if (retired) {
+          findings.push({
+            message: `adapter ${file.relativePath} still teaches \`doctrina ${retired}\`, which this CLI ${DEPRECATED[retired] ? "deprecated" : "removed"} — the agent running it follows the old flow`,
+            remedy: `doctrina adapter add ${name} --force`,
+          });
+        } else {
+          ok.push(`adapter ${file.relativePath}: teaches live commands only`);
+        }
+        continue;
+      }
       if (read(installed).includes("AGENTS.md")) {
         ok.push(`adapter ${file.relativePath}: points at AGENTS.md`);
       } else {
@@ -195,7 +222,7 @@ export function collectFindings(projectRoot) {
       const idx = JSON.parse(read(indexPath));
       for (const field of INDEX_FIELDS) {
         if (idx[field] !== undefined) ok.push(`index.json: ${field}`);
-        else findings.push({ message: `.doctrina/index.json missing field "${field}"`, remedy: "doctrina templates update --write" });
+        else findings.push({ message: `.doctrina/index.json missing field "${field}"`, remedy: "doctrina upgrade --write" });
       }
       if (idx.$schema_version && idx.$schema_version !== "0.1.0") {
         findings.push({ message: `.doctrina/index.json $schema_version is "${idx.$schema_version}" (expected "0.1.0")`, remedy: null });

package/src/lib/validation-model.js

@@ -16,11 +16,13 @@
 import path from "node:path";
 import { readdirSync } from "node:fs";
 import { exists, isDir, isFile, lineCount, read, relPath, walk, write } from "./fs-ops.js";
+import { fold, terms } from "./lexicon.js";
+import { intakeStatusError } from "./intake-model.js";
 import * as idx from "./index-json.js";
 import { SCHEMA_VERSION } from "./index-json.js";
 import { cliVersion, newestVersion } from "./version.js";
 import { today } from "./dates.js";
-import { checklistProgress, kindFromPath, maskComments, nonConformingHeaders, repairHeaders, parseFrontmatter, isPlaceholderHeaderValue } from "./doc-model.js";
+import { checklistProgress, kindFromPath, maskComments, nonConformingHeaders, repairHeaders, parseFrontmatter, isPlaceholderHeaderValue, isScaffoldValue } from "./doc-model.js";
 import { checkEars, isEarsSpec } from "./ears.js";
 import { parseAdrScope, parseSourceGlobs, parseDependsOn, specHeader, listHeader, deriveIndex, indexesMatch, stableStringify } from "./scan.js";
 import { COMMAND_NAMES, referencedCommands, DEPRECATED } from "./commands.js";
@@ -144,6 +146,21 @@ export function collectValidation(projectRoot, { fix = false, runtime = false }
   const productMd = path.join(projectRoot, ".doctrina", "product.md");
   if (!isFile(productMd)) errors.push(".doctrina/product.md missing");
 
+  // 2b. intake.md's status, when there is one.
+  //
+  // `next` branches on this value to decide whether the bootstrap is done,
+  // and the playbook has the agent write it BY HAND — so it is the one
+  // control value in the tree that nothing read back. Anything but the two
+  // declared words meant "pending" in silence: "convertido" typed in a
+  // Portuguese project, or an empty value left by a botched edit, both left
+  // `next` asking forever for a bootstrap that had already happened.
+  // A spec's Status gets an enum and an error; so does this one.
+  const intakeMd = path.join(projectRoot, ".doctrina", "intake.md");
+  if (isFile(intakeMd)) {
+    const badStatus = intakeStatusError(read(intakeMd));
+    if (badStatus) errors.push(`.doctrina/intake.md: ${badStatus}`);
+  }
+
   // Header repair (M3). One grammar means a non-canonical header can be
   // REWRITTEN, not just reported: `- **Status**: x` becomes
   // `- **Status:** x`, and a spec written with list-style headers is
@@ -435,7 +452,7 @@ export function collectValidation(projectRoot, { fix = false, runtime = false }
         if (ph > 0) {
           warnings.push(
             `open change "${entry}" tasks.md still carries ${ph} scaffold placeholder task${ph === 1 ? "" : "s"} — ` +
-              `the change was opened but never planned (replace them with real tasks; analyze/close refuse them)`,
+              `the change was opened but never planned (replace them with real tasks; \`change check\` and the close refuse them)`,
           );
         }
       }
@@ -443,10 +460,15 @@ export function collectValidation(projectRoot, { fix = false, runtime = false }
       // capabilities a change touches, and a name with no spec behind it
       // — a typo, or a capability that was never created — passed
       // analyze, check and close in silence. A capability this change is
-      // about to CREATE (an ADDED delta) is not a ghost.
+      // about to CREATE (an ADDED delta) is not a ghost. Neither is the
+      // header's own "none": a chore is scaffolded with "(none — chore)",
+      // and reading its words as names warned twice on every chore (change
+      // 0190). A parenthesised aside is a note, not a capability.
       if (isFile(proposal)) {
-        const affects = (listHeader(read(proposal), "Affects specs") ?? "")
-          .match(/[a-z][a-z0-9-]*/g) ?? [];
+        const header = (listHeader(read(proposal), "Affects specs") ?? "").trim();
+        const affects = /^\(?\s*(none|n\/a)\b/i.test(header)
+          ? []
+          : header.replace(/\([^)]*\)/g, "").match(/[a-z][a-z0-9-]*/g) ?? [];
         const specsRoot = path.join(projectRoot, ".doctrina", "specs");
         for (const cap of affects) {
           if (isFile(path.join(specsRoot, cap, "spec.md"))) continue;
@@ -464,12 +486,12 @@ export function collectValidation(projectRoot, { fix = false, runtime = false }
         if (!m) {
           warnings.push(
             `${relPath(projectRoot, deltaPath)} has no **Operation:** header — ` +
-              `analyze/apply will refuse it at close time (add "**Operation:** ADDED|MODIFIED|REMOVED")`,
+              `\`change apply\` and the close will refuse it (add "**Operation:** ADDED|MODIFIED|REMOVED")`,
           );
         } else if (!["ADDED", "MODIFIED", "REMOVED"].includes(m[1])) {
           warnings.push(
             `${relPath(projectRoot, deltaPath)} Operation "${m[1]}" is not ADDED|MODIFIED|REMOVED — ` +
-              `analyze/apply will refuse it at close time`,
+              `\`change apply\` and the close will refuse it`,
           );
         }
       }
@@ -487,7 +509,7 @@ export function collectValidation(projectRoot, { fix = false, runtime = false }
       const specPath = path.join(specsDir, cap, "spec.md");
       if (isFile(specPath)) {
         const lines = lineCount(specPath);
-        if (lines > 400) warnings.push(`${relPath(projectRoot, specPath)} is ${lines} lines (>400 soft cap)`);
+        if (lines > 400) warnings.push(`${relPath(projectRoot, specPath)} is ${lines} lines (>400 soft cap) — consolidate it: \`doctrina work --consolidate ${path.basename(path.dirname(specPath))}\``);
 
         // 8b. EARS grammar shape — section-appropriate When/While/Where/shall.
         const text = read(specPath);
@@ -732,10 +754,25 @@ export function collectValidation(projectRoot, { fix = false, runtime = false }
     const productPath = path.join(projectRoot, ".doctrina", "product.md");
     if (isFile(productPath)) {
       const seen = new Map();
+      // The mirror case: ONE intent under TWO ids. Realize either and the
+      // other stays "dropped" forever, so `trace --strict` — a CI gate —
+      // fails on a gap nobody can close. Compared folded, so case, accents
+      // and spacing do not hide a twin.
+      const seenText = new Map();
       const lines = read(productPath).split(/\r?\n/);
       for (let i = 0; i < lines.length; i++) {
-        const m = lines[i].match(/^\s*[-*]\s+\[([A-Z]+\d+)\]\s+/);
+        const m = lines[i].match(/^\s*[-*]\s+\[([A-Z]+\d+)\]\s+(.*)$/);
         if (!m) continue;
+        const key = intentKey(m[2]);
+        if (key && seenText.has(key) && seenText.get(key).id !== m[1]) {
+          const first = seenText.get(key);
+          warnings.push(
+            `.doctrina/product.md:${i + 1} intent [${m[1]}] states the same intent as [${first.id}] (line ${first.line}) — ` +
+              `realizing one leaves the other dropped, so \`trace --strict\` fails on a gap nobody can close; delete the twin`,
+          );
+        } else if (key && !seenText.has(key)) {
+          seenText.set(key, { id: m[1], line: i + 1 });
+        }
         if (seen.has(m[1])) {
           errors.push(
             `.doctrina/product.md:${i + 1} intent anchor [${m[1]}] is declared twice (first at line ${seen.get(m[1])}) — ` +
@@ -972,11 +1009,11 @@ export function collectValidation(projectRoot, { fix = false, runtime = false }
       else if (lines > 150) warnings.push(`${rel} is ${lines} lines (>150 soft cap)`);
 
       // 15. Skill description drift — index.json must mirror the
-      //     frontmatter description (run `doctrina skill sync`).
+      //     frontmatter description (`doctrina index rebuild` does).
       if (descField && index?.artifacts?.skills) {
         const entry = index.artifacts.skills.find((s) => s.id === baseName);
         if (entry && entry.description !== descField) {
-          warnings.push(`${rel} description differs from index.json (run \`doctrina skill sync\`)`);
+          warnings.push(`${rel} description differs from index.json (run \`doctrina index rebuild\`)`);
         }
       }
     }
@@ -1012,7 +1049,9 @@ export function collectValidation(projectRoot, { fix = false, runtime = false }
   // rule is a forbid-regex over glob-scoped paths; a match is an ERROR with
   // the rule's own message. Deterministic, zero-deps, and the instruction
   // survives sessions because it is an artifact, not a memory.
-  for (const line of checkProjectRules(projectRoot)) errors.push(line);
+  const ruleFindings = checkProjectRules(projectRoot);
+  for (const line of ruleFindings.errors) errors.push(line);
+  for (const line of ruleFindings.warnings) warnings.push(line);
   for (const key of loadConfig(projectRoot).unknown) {
     warnings.push(`${CONFIG_REL}: unknown key "${key}" is ignored — the keys are language, context_budget, rules (a typo here is a setting that never applied)`);
   }
@@ -1043,27 +1082,45 @@ export function collectValidation(projectRoot, { fix = false, runtime = false }
 // something concrete — a path or glob, a command, a quoted error string, a
 // file extension, an ALL_CAPS identifier, or simply enough distinctive
 // keywords to match on.
-const VAGUE_TRIGGER = /^(?:when(?:ever)?\s+)?(?:it|this|you|the agent)?\s*(?:is\s+)?(?:seems?|feels?|looks?)?\s*(?:relevant|appropriate|needed|necessary|useful|applicable|as needed|if needed)\.?$/i;
+// One list per language, because this framework runs on Portuguese projects
+// too — and the vagueness it exists to catch is written in the project's own
+// language. Change 0158 found the same split in `clarify`'s lexicons; this is
+// the same asymmetry one module over. Matched against the FOLDED text, so
+// "necessário" and "necessario" are one phrase.
+const VAGUE_TRIGGER_EN = /^(?:when(?:ever)?\s+)?(?:it|this|you|the agent)?\s*(?:is\s+)?(?:seems?|feels?|looks?|makes?)?\s*(?:relevant|appropriate|needed|necessary|useful|applicable|sense|right|as needed|if needed)\.?$/i;
+const VAGUE_TRIGGER_PT =
+  /^(?:(?:sempre\s+)?que|quando|se)?\s*(?:isso|isto|voce|o agente)?\s*(?:for|foi|parecer|fizer|achar|julgar)?\s*(?:relevante|apropriad[oa]|necessari[oa]|util|aplicavel|preciso|sentido|cert[oa])\.?$/i;
 
-/** A value still wrapped in the template's angle brackets: `<one-sentence …>`. */
-export function isScaffoldValue(value) {
-  return /^<[^<>]*>$/.test(String(value ?? "").trim());
+function looksVague(text) {
+  const folded = fold(text).trim();
+  if (folded === "") return true;
+  return VAGUE_TRIGGER_EN.test(folded) || VAGUE_TRIGGER_PT.test(folded);
+}
+
+// Owned by the document model since change 0177 (the rebuild needs it and
+// cannot import this module); re-exported so existing callers stay put.
+export { isScaffoldValue };
+
+/** An intent's text, folded for comparison: case, accents and spacing ignored. */
+export function intentKey(text) {
+  return fold(String(text ?? "")).replace(/\s+/g, " ").replace(/[.;:!\s]+$/, "").trim();
 }
 
 export function hasDetectableTrigger(when) {
   const text = String(when ?? "").trim();
-  if (text === "" || VAGUE_TRIGGER.test(text)) return false;
+  if (looksVague(text)) return false;
   // The scaffold's own placeholder has enough words to rank on and names
   // nothing (change 0111): a trigger nobody wrote fires for nobody.
   if (isScaffoldValue(text)) return false;
   // Anything structural is inherently matchable.
-  if (/[\/\]|\*|`|"|'|\.\w{2,4}|[A-Z][A-Z0-9_]{2,}/.test(text)) return true;
-  // Otherwise: enough distinctive words to rank on. Stopwords do not count.
-  const STOP = new Set(["when", "whenever", "the", "a", "an", "is", "are", "you", "your",
-    "it", "its", "this", "that", "and", "or", "to", "of", "in", "on", "for", "with",
-    "any", "some", "need", "needs", "needed", "should", "must", "at", "as", "by", "be"]);
-  const words = text.toLowerCase().match(/[a-z][a-z0-9-]{2,}/g) ?? [];
-  return words.filter((w) => !STOP.has(w)).length >= 2;
+  if (/[\/\]|\*|`|"|'|\.\w{2,4}|[A-Z][A-Z0-9_]{2,}/.test(text)) return true;
+  // Otherwise: enough distinctive words to rank on — counted by the SHARED
+  // lexicon, which folds and carries the connective tissue of both languages.
+  // The private stop list here was English-only, so every Portuguese function
+  // word ("quando", "que", "para") counted as distinctive and a two-word
+  // Portuguese phrase cleared the bar on grammar alone. One lexicon, the way
+  // `work` and `context` already read text (audit findings F5/F6).
+  return terms(text).length >= 2;
 }
 
 // Enforce the project's rules — permanent constraints as forbid-regexes over
@@ -1073,9 +1130,16 @@ export function hasDetectableTrigger(when) {
 //                  "message": "white-label product; use a generic placeholder" } ] }
 // Declared in .doctrina/config.json; still read from the legacy
 // .doctrina/rules.json when that is where a project put them (change 0047).
-// Returns error strings (one per offending file+rule, capped per rule so a
-// mass violation stays readable). No rules → nothing to enforce; a malformed
-// file is reported once, by the reader. Binary-ish and vendored dirs are
+// Returns { errors, warnings }: an error per offending file+rule (capped per
+// rule so a mass violation stays readable), and a warning for a rule that
+// reached no file at all. No rules → nothing to enforce; a malformed file is
+// reported once, by the reader.
+//
+// The dead-scope warning is the same finding 8h makes about a `**Source:**`
+// glob and RT05 makes about a selector: a declaration that matches nothing
+// reads as coverage and provides none. A rule is the strongest of the three
+// — a permanent constraint the project believes is enforced — and it was the
+// one that said nothing, while `doctor` went on counting it as configured. Binary-ish and vendored dirs are
 // skipped by the same bounded walk validate already uses elsewhere.
 const RULES_SKIP_DIRS = new Set([
   ".git", "node_modules", "vendor", "dist", "build", "out", "target",
@@ -1086,6 +1150,7 @@ const RULES_MAX_HITS_PER_RULE = 10;
 function checkProjectRules(projectRoot) {
   const cfg = loadConfig(projectRoot);
   const out = [...cfg.errors];
+  const warn = [];
   const where = cfg.sources.rules === SOURCES.config ? CONFIG_REL : RULES_REL;
   const compiled = [];
   for (const r of cfg.rules) {
@@ -1100,10 +1165,16 @@ function checkProjectRules(projectRoot) {
       out.push(`${where}: rule "${r.id ?? r.forbid}" has an invalid regex: ${err.message}`);
       continue;
     }
-    const paths = Array.isArray(r.paths) && r.paths.length ? r.paths : ["**"];
-    compiled.push({ id: r.id ?? r.forbid, re, matchers: paths.map(globToRegExp), message: r.message ?? "", hits: 0 });
+    const declared = Array.isArray(r.paths) && r.paths.length ? r.paths : null;
+    const paths = declared ?? ["**"];
+    compiled.push({
+      id: r.id ?? r.forbid, re, matchers: paths.map(globToRegExp),
+      message: r.message ?? "", hits: 0,
+      // Only a DECLARED scope can be dead; the implicit `**` is not a claim.
+      declared, scanned: 0,
+    });
   }
-  if (compiled.length === 0) return out;
+  if (compiled.length === 0) return { errors: out, warnings: warn };
 
   // One bounded walk; each text file is read at most once.
   const stack = [projectRoot];
@@ -1123,7 +1194,11 @@ function checkProjectRules(projectRoot) {
       }
       const rel = relPath(projectRoot, full).replace(/\\/g, "/");
       if (rel === ".doctrina/rules.json") continue; // the rule text itself always matches
-      const applicable = compiled.filter((cr) => cr.hits < RULES_MAX_HITS_PER_RULE && cr.matchers.some((m) => m.test(rel)));
+      // Count the reach BEFORE the hit cap: a rule that stopped reporting
+      // because it hit the cap has plainly reached files.
+      const inScope = compiled.filter((cr) => cr.matchers.some((m) => m.test(rel)));
+      for (const cr of inScope) cr.scanned += 1;
+      const applicable = inScope.filter((cr) => cr.hits < RULES_MAX_HITS_PER_RULE);
       if (applicable.length === 0) continue;
       let text;
       try {
@@ -1145,8 +1220,15 @@ function checkProjectRules(projectRoot) {
     if (cr.hits >= RULES_MAX_HITS_PER_RULE) {
       out.push(`rule "${cr.id}": more matches suppressed after ${RULES_MAX_HITS_PER_RULE} files`);
     }
+    if (cr.declared && cr.scanned === 0) {
+      warn.push(
+        `${where}: rule "${cr.id}" scopes to ${cr.declared.map((g) => `\`${g}\``).join(", ")}, ` +
+          "which matches no file — the constraint is declared and never enforced; " +
+          "correct the paths or drop the rule",
+      );
+    }
   }
-  return out;
+  return { errors: out, warnings: warn };
 }
 
 // Minimal glob → RegExp: ** crosses directories, * stays within a segment.
@@ -1168,9 +1250,9 @@ function globToRegExp(glob) {
 // artifact whose recorded metadata no longer matches its file.
 function metadataDrift(current, derived) {
   const lines = [];
-  // Skills are deliberately excluded: their description has a dedicated
-  // reconciliation command (`doctrina skill sync`) and stays an advisory
-  // warning (see section 15), not a hard error.
+  // Skills are deliberately excluded: their description is reconciled by
+  // `doctrina index rebuild` and stays an advisory warning (see section
+  // 15), not a hard error.
   const cats = ["specs", "decisions", "changes", "changes_archive", "contracts"];
   for (const cat of cats) {
     const cur = new Map((current.artifacts?.[cat] ?? []).map((e) => [e.id, e]));