doctrina-cli 0.16.0 → 0.17.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`,
           );
         }
       }
@@ -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]));

package/src/lib/views.js

@@ -222,6 +222,9 @@ export function handoff(s) {
     out.push("## Open work");
     out.push("");
     out.push("- none — the tree is at rest; start with `doctrina work \"<prompt>\"`");
+    // The note is pasted into another session, so the section has to END like
+    // the loop below ends: a heading glued to a list item is not a heading.
+    out.push("");
   } else {
     for (const ch of s.openChanges) {
       out.push(`## Open change \`${ch.id}\`${ch.title ? ` — ${ch.title}` : ""}`);
@@ -405,6 +408,6 @@ export function report(s, { days = 7, cutoffIso = "", git = null, gitState = nul
   }
 
   out.push("");
-  out.push(`*Generated read-only by \`doctrina report --since ${days}\`; deeper numbers: \`doctrina metrics\`.*`);
+  out.push(`*Generated read-only by \`doctrina status --view report --since ${days}\`; deeper numbers: \`doctrina metrics\`.*`);
   return out;
 }

package/src/lib/work-model.js

@@ -44,6 +44,31 @@ export function rankCapabilitiesByDiff(projectRoot, files, { limit = 3 } = {}) {
   return ranked.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id)).slice(0, limit);
 }
 
+/**
+ * The capabilities whose `Source:` header CLAIMS a file — ADR 0027's question
+ * asked directly, with no inference in the answer.
+ *
+ * `rankCapabilitiesByDiff` deliberately falls back to inferences so a project
+ * that has not declared anything still gets a hint. That makes it the wrong
+ * function to enforce the declaration with: a file no spec names still comes
+ * back with an owner, scored 5 instead of 10, and a test asking "does this
+ * have an owner" cannot tell the two apart. `lib/names.js` sat undeclared
+ * behind exactly that.
+ */
+export function declaredOwners(projectRoot, file) {
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  if (!isDir(specsDir)) return [];
+  const norm = String(file).replace(/\\/g, "/");
+  const owners = [];
+  for (const cap of readdirSync(specsDir).sort()) {
+    const specPath = path.join(specsDir, cap, "spec.md");
+    if (!isFile(specPath)) continue;
+    const globs = parseSourceGlobs(read(specPath)).map((g) => globToRegExp(g));
+    if (globs.some((re) => re.test(norm))) owners.push(cap);
+  }
+  return owners;
+}
+
 // Deterministic term overlap: fold prompt and spec text with the SHARED
 // lexicon, then score. This is a hint for the agent, never a decision
 // (ADR 0005).

package/templates/AGENTS.md.template

@@ -46,13 +46,12 @@ canonical templates and syncs `index.json`. Flags: `doctrina <cmd> --help`.
 - `doctrina triage` — classify the lane (product/runtime/chore) and check the declared runtime surface. *When:* a request arrives — BEFORE scaffolding, especially if it smells like an incident.
 - `doctrina work "<prompt>" (--capability · --chore · --from-diff · --quiet)` — scaffold a change and print the playbook to execute. *When:* a request arrives that changes behaviour (triage says PRODUCT).
 - `doctrina spec new|list|set` — create, list, and edit capability specs. *When:* a capability needs creating or its headers advancing.
-- `doctrina change new|apply|archive|check|tick|abandon` — new / apply / archive / check (--verbose) / tick / abandon. *When:* driving a change through its lifecycle by hand.
+- `doctrina change new|apply|archive|check|tick|abandon` — drive a change by hand — check --verbose previews every delta. *When:* driving a change through its lifecycle by hand.
 - `doctrina contract new|list|check` — own and verify the integration surface. *When:* the change touches ports, env vars, or public endpoints.
 - `doctrina decision new|accept|land|supersede|list|scope` — record, accept, land, scope, and supersede ADRs. *When:* the change decides something a later session must not relitigate.
-- `doctrina skill new|list|sync|suggest` — capture on-demand procedural memory. *When:* a lesson is worth not relearning.
+- `doctrina skill new|list|suggest` — capture on-demand procedural memory. *When:* a lesson is worth not relearning.
 - `doctrina intent add|list` — append and list product intent anchors. *When:* new product intent appears after the intake.
 **Gate**
-- `doctrina analyze` — structural pre-flight on a change folder. *When:* before applying a change.
 - `doctrina clarify --all (--lang pt|en)` — smell-test Markdown for ambiguity. *When:* before applying, or before opening a PR.
 - `doctrina validate (--fix)` — schema, structure, EARS, and index drift. *When:* after any artifact edit, and before considering work done.
 - `doctrina coverage --strict` — acceptance criteria against cited evidence. *When:* before claiming a capability is proven.
@@ -61,7 +60,7 @@ canonical templates and syncs `index.json`. Flags: `doctrina <cmd> --help`.
 - `doctrina verify` — the project's declared typecheck/test/build checks. *When:* the real build gate must run.
 - `doctrina close <id...>` — the whole closing sequence in one attested pass. *When:* a change is implemented and ready to finish.
 - `doctrina doctor` — aggregate diagnostic with per-finding remedies. *When:* something looks wrong and you do not know which gate to ask.
-**Maintain** (triggers: `doctrina <command> --help`) — `doctrina templates list|check|update` · `doctrina hooks install` · `doctrina index rebuild` · `doctrina watch` · `doctrina metrics` · `doctrina report` · `doctrina completion` · `doctrina upgrade --write` · `doctrina ci --emit github`
+**Maintain** (triggers: `doctrina <command> --help`) — `doctrina templates list` · `doctrina hooks install` · `doctrina index rebuild` · `doctrina watch` · `doctrina metrics` · `doctrina completion` · `doctrina upgrade --write` · `doctrina ci --emit github`
 <!-- doctrina:surface:end -->
 
 ## Stack and tooling

package/templates/adapters/claude/.claude/commands/doctrina-work.md.template

@@ -9,9 +9,12 @@ Drive the Doctrina spec-driven workflow for **{{PROJECT_NAME}}**.
    (No prompt, but you already edited code? Use `doctrina work --from-diff`.)
 2. Execute the printed playbook in order: read the pack with
    `doctrina context <capability> --concat`, write the spec delta, fill
-   `tasks.md`, implement, then `doctrina analyze <id>` → `doctrina change apply <id>`.
-3. Close it: `doctrina close <id>` (verify → coverage → archive → validate) and
-   resolve every `error:` before reporting the work done.
+   `tasks.md`, implement. `doctrina change check <id>` previews everything
+   the close would refuse.
+3. Close it: `doctrina close <id>` — one attested pass over every gate. The
+   sequence is declared in one place and printed by `doctrina close --help`;
+   read it there rather than from a copy. Resolve every `error:` before
+   reporting the work done.
 
 Reach for the CLI instead of hand-authoring artifacts. Ask the human only on
 genuine ambiguity.

package/templates/adapters/cursor/.cursor/commands/doctrina-work.md.template

@@ -5,8 +5,9 @@ Turn the request into a Doctrina change and drive it through the gates.
 1. Run `doctrina work "<the request>"` (or `doctrina work --from-diff` if you
    already edited code) and follow the printed playbook.
 2. `doctrina context <capability> --concat` → write the spec delta → fill
-   `tasks.md` → implement → `doctrina analyze <id>` → `doctrina change apply <id>`.
-3. `doctrina close <id>` (verify → coverage → archive → validate); resolve
-   every `error:` before reporting the work done.
+   `tasks.md` → implement → `doctrina change check <id>` (the close's preview).
+3. `doctrina close <id>` — one attested pass over every gate; the sequence is
+   declared in one place and printed by `doctrina close --help`, so read it
+   there and not from a copy. Resolve every `error:` before reporting done.
 
 Prefer the CLI over hand-authoring artifacts. Ask only on genuine ambiguity.

package/templates/change/proposal.md.template

@@ -6,6 +6,21 @@
 - **Lane:**
 - **Affects specs:**
 
+<!--
+Optional, and usually absent. The closing docs gate reads COMMAND and FLAG
+names out of the prose below and asks for documentation when it finds any.
+It cannot tell a change from a mention: explaining an effect, or writing a
+Scope boundaries line about what this deliberately does NOT touch, names
+things just as loudly as changing them would.
+
+When that happens, say so on the record instead of forcing the close:
+
+- **Documented surface:** n/a — names two commands to explain an effect; alters neither
+
+`none` reads the same as `n/a`, and a BARE one silences nothing — the
+reason is the declaration.
+-->
+
 ## Why
 
 <!-- The user-visible or technical reason this change exists. -->

package/templates/change/tasks.md.template

@@ -2,16 +2,11 @@
 
 <!--
 Each task is a single checkable item. Keep tasks small (under a few hours
-of work). The change is done when every box is checked, including the
-three closing steps at the bottom.
+of work). The change is done when every box is checked and
+`doctrina close {{CHANGE_ID}}` succeeds — the close applies the deltas,
+archives the change and updates the index, so those are not boxes here.
 -->
 
 - [ ]
 - [ ]
 - [ ]
-
-## Closing steps
-
-- [ ] Apply the change: merge each delta into the corresponding spec.
-- [ ] Archive the change folder to `.doctrina/changes/archive/{{DATE}}-{{CHANGE_ID}}/`.
-- [ ] Update `.doctrina/index.json` with new or modified artifacts.

package/templates/contract.md.template

@@ -107,8 +107,8 @@ Example (Behave): features/**/*.feature with pattern @([a-z0-9_-]+)
 <!--
 Ceilings that are a CONTRACT, not a preference: token limits, payload
 caps, timeouts. Direction distinguishes what goes IN from what comes
-OUT, because they fail differently — and `doctrina analyze` refuses a
-change that "fixes" an overflow by raising an OUTPUT ceiling, which
+OUT, because they fail differently — and `doctrina change check` and the
+close refuse a change that "fixes" an overflow by raising an OUTPUT ceiling, which
 buys headroom by truncating what mattered rather than sending less.
 -->
 

package/templates/hooks/pre-commit.sample

@@ -26,3 +26,13 @@ $DOCTRINA validate --fix || exit 1
 if [ -f .doctrina/index.json ]; then
   git add .doctrina/index.json
 fi
+
+# ...and then check that the index this commit carries describes THIS COMMIT.
+#
+# Everything above reads the working tree. index.json is derived from the
+# whole tree, so it cannot describe a subset of one: stage part of
+# .doctrina/ and the index that just got staged names artifacts the commit
+# does not contain. On your disk they are all still there, so `validate`,
+# `index rebuild --check` and the close all pass — and the checkout in CI
+# fails with "index.json references missing artifact".
+$DOCTRINA index rebuild --check --staged || exit 1

package/templates/playbooks/bootstrap.md.template

@@ -35,8 +35,12 @@ Execute in order, in a single linear pass:
    If something in the intake is genuinely ambiguous, ask the user
    before assuming.
 
-7. Mark the intake consumed: in .doctrina/intake.md flip
-   "- **Status:** pending" to "- **Status:** converted".
+7. Mark the intake consumed — through the CLI, not by hand:
+       [[c]]doctrina intake --converted[[/c]]
+[[g]]   `next` branches on that header and `validate` refuses any other[[/g]]
+[[g]]   value, because every word but the two declared ones used to read[[/g]]
+[[g]]   as pending in silence. It refuses while `validate` reports an[[/g]]
+[[g]]   error — the step-6 gates are what "done" means.[[/g]]
 
 8. [[c]]doctrina next[[/c]] — follow the recommendation. Implementation then
    flows through [[c]]doctrina work "<brief prompt>"[[/c]], one change at a time.

package/templates/playbooks/chore.md.template

@@ -6,14 +6,19 @@ Execute in order, in a single linear pass:
 
 1. Replace the placeholder tasks in .doctrina/changes/{{CHANGE_ID}}/tasks.md
    with small, checkable steps; implement them, checking each box.
-[[g]]   (Do it before implementing — analyze/close refuse leftover scaffold[[/g]]
+[[g]]   (Do it before implementing — the close refuses leftover scaffold[[/g]]
 [[g]]   placeholders, and `change tick` will not tick an empty box.)[[/g]]
-2. Prove it (archive refuses unchecked boxes):
+2. Prove it (the close refuses unchecked boxes):
        [[c]]doctrina verify[[/c]]     — the project's typecheck/test/build gate
        [[c]]doctrina verify --clean[[/c]] — clean-checkout reproducibility lint
    Then check the proposal's ## Verification boxes and every task.
 3. This is a chore: no spec changes. If you find yourself needing a
    spec delta, it is not a chore — reopen with [[c]]doctrina work "<prompt>"[[/c]].
-4. [[c]]doctrina change apply {{CHANGE_ID}}[[/c]]  (zero deltas → flips to applied).
-5. [[c]]doctrina change archive {{CHANGE_ID}}[[/c]], then [[c]]doctrina validate[[/c]].
+4. Close in one attested pass — the same close as any change; a chore
+   simply has no delta to apply:
+       [[c]]doctrina close {{CHANGE_ID}}[[/c]]
+[[g]]   It stops at the first failure with the exact rerun command, and the[[/g]]
+[[g]]   sequence is printed by the close itself. A chore that alters a[[/g]]
+[[g]]   documented surface still owes the docs and a changelog entry — or[[/g]]
+[[g]]   `- **Documented surface:** n/a — <why>` in the proposal.[[/g]]
 [[g]]   If this fix taught a lesson worth not relearning, capture it: [[/g]][[c]]doctrina skill new <slug>[[/c]][[g]].[[/g]]

package/templates/playbooks/work.md.template

@@ -45,7 +45,7 @@ Execute in order, in a single linear pass:
 4. Replace the placeholder tasks in .doctrina/changes/{{CHANGE_ID}}/tasks.md
    with small, checkable implementation tasks (a few hours each, max),
    and record the change's What/Scope in its proposal.md. Do this BEFORE
-   implementing — analyze and close refuse a change whose scaffold
+   implementing — `change check` and close refuse a change whose scaffold
    placeholders were never replaced, and `change tick` will not tick them.
 
 5. Implement task by task, checking each box as it lands. Advance the
@@ -67,9 +67,16 @@ Execute in order, in a single linear pass:
 [[g]]   It self-reviews on the way through: the close runs `doctrina review`[[/g]]
 [[g]]   before the apply, where its findings can still change what gets[[/g]]
 [[g]]   written. Advisory — it reports and the close continues.[[/g]]
-[[g]]   (equivalent, step by step: [[/g]][[g]]analyze → change apply → verify → coverage → trace → change archive → validate)[[/g]]
+[[g]]   The sequence is declared in one place and printed by the close itself,[[/g]]
+[[g]]   so read it there rather than from a copy that goes stale.[[/g]]
    Before it: check the proposal's ## Verification boxes and every task,
-   closing steps included, and bump Implementation to verified.
+   and bump Implementation to verified.
+   Two gates ask for WRITING, and both refuse late if you leave them:
+   a change that alters a documented surface needs the documentation to
+   move with it, AND an entry in the project's changelog — one says how it
+   works, the other says that it changed. If the command and flag names in
+   your prose are only MENTIONED, declare it instead of forcing:
+   [[c]]- **Documented surface:** n/a — <why>[[/c]] in the proposal.
 
 8. [[c]]doctrina next[[/c]] for the follow-up.
 [[g]]   If this change taught a reusable lesson (a fix you'd hate to relearn,[[/g]]