dotmd-cli 0.76.2 → 0.76.4

package/bin/dotmd.mjs

@@ -1831,7 +1831,7 @@ async function main() {
 
   // All remaining commands need the index + render modules
   const { buildIndex } = await import('../src/index.mjs');
-  const { renderCompactList, renderVerboseList, renderContext, renderBriefing, renderCheck, renderCoverage, buildCoverage } = await import('../src/render.mjs');
+  const { renderCompactList, renderVerboseList, renderContext, renderBriefing, renderCheck, renderCoverage, buildCoverage, buildReferenceValidationCoverage } = await import('../src/render.mjs');
   const { runFocus, runQuery } = await import('../src/query.mjs');
   // `dotmd check` is the one shared-buildIndex command that should auto-heal a
   // drifted index block (frontmatter edits by direct Edit/Write, `lint --fix`,
@@ -1898,6 +1898,7 @@ async function main() {
         warnings: errorsOnly ? [] : checkIndex.warnings,
         errorCount: checkIndex.errors.length,
         warningCount: checkIndex.warnings.length,
+        referenceValidation: buildReferenceValidationCoverage(checkIndex, config),
         passed: complete ? builtInPassed : null,
         ...(complete ? {} : {
           builtInPassed,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.76.2",
+  "version": "0.76.4",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, lifecycle, and AI summaries.",
   "type": "module",
   "license": "MIT",

package/src/config.mjs

@@ -154,6 +154,7 @@ function normalizeRichStatuses(config, userConfig) {
     // reads them has to be too.
     skipWarningsForByType: {},
     terminalStatuses: [],
+    terminalStatusesByType: {},
     moduleRequiredFor: [],
     // F15: status-name → directory-name (defaults to the status name verbatim).
     // Filed statuses move docs into <root>/<dirName>/ on transition INTO the
@@ -177,6 +178,7 @@ function normalizeRichStatuses(config, userConfig) {
     // declared its statuses and suppresses nothing", which must not fall back to
     // the global union. Absent entirely means "type never declared rich statuses".
     derived.skipWarningsForByType[typeName] ??= [];
+    derived.terminalStatusesByType[typeName] ??= [];
     const statusNames = [];
     const typeContext = { expanded: [], listed: [], counted: [] };
     const typeStaleDays = {};
@@ -218,7 +220,10 @@ function normalizeRichStatuses(config, userConfig) {
         if (!derived.skipWarningsFor.includes(name)) derived.skipWarningsFor.push(name);
         (derived.skipWarningsForByType[typeName] ??= []).push(name);
       }
-      if (p.terminal && !derived.terminalStatuses.includes(name)) derived.terminalStatuses.push(name);
+      if (p.terminal) {
+        if (!derived.terminalStatuses.includes(name)) derived.terminalStatuses.push(name);
+        derived.terminalStatusesByType[typeName].push(name);
+      }
       if (p.requiresModule && !derived.moduleRequiredFor.includes(name)) derived.moduleRequiredFor.push(name);
       if (p.filed && !derived.filedStatuses[name]) {
         // dirName defaults to the status name; users can override with
@@ -281,6 +286,10 @@ function applyDerivedConfig(config, userConfig, derived) {
   }
   if (!userConfig.lifecycle?.terminalStatuses && derived.terminalStatuses.length) {
     config.lifecycle.terminalStatuses = derived.terminalStatuses;
+    config.lifecycle.terminalStatusesByType = derived.terminalStatusesByType;
+  } else {
+    // An explicit lifecycle list is intentionally repo-wide.
+    config.lifecycle.terminalStatusesByType = {};
   }
   if (!userConfig.lifecycle?.filedStatuses && Object.keys(derived.filedStatuses).length) {
     config.lifecycle.filedStatuses = derived.filedStatuses;
@@ -539,6 +548,13 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     return own ? own.has(status) : skipWarningsFor.has(status);
   };
   const terminalStatuses = new Set(lifecycle.terminalStatuses);
+  const terminalStatusesByType = new Map(
+    Object.entries(lifecycle.terminalStatusesByType ?? {}).map(([type, names]) => [type, new Set(names)]),
+  );
+  const isTerminal = (status, type) => {
+    const own = type != null ? terminalStatusesByType.get(type) : undefined;
+    return own ? own.has(status) : terminalStatuses.has(status);
+  };
   // F15: filedStatuses keyed by status name, value = directory name. Empty
   // object when no status opts in via `filed: true` (or `filed: '<dirname>'`).
   const filedStatuses = new Map(Object.entries(lifecycle.filedStatuses ?? {}));
@@ -589,7 +605,7 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     rootValidStatuses,
     staleDaysByStatus,
 
-    lifecycle: { archiveStatuses, startableStatuses, skipStaleFor, skipWarningsFor, skipWarningsForByType, skipsWarnings, terminalStatuses, filedStatuses, archiveNestedTypes },
+    lifecycle: { archiveStatuses, startableStatuses, skipStaleFor, skipWarningsFor, skipWarningsForByType, skipsWarnings, terminalStatuses, terminalStatusesByType, isTerminal, filedStatuses, archiveNestedTypes },
 
     validSurfaces,
     validModules,

package/src/index.mjs

@@ -290,7 +290,8 @@ export function parseDocFile(filePath, config, opts = {}) {
   // criterion: "should defer to frontmatter when status is terminal."
   const fmCurrentState = asString(parsedFrontmatter.current_state);
   const docStatus = asString(parsedFrontmatter.status);
-  const isTerminalDoc = docStatus && config.lifecycle?.terminalStatuses?.has?.(docStatus);
+  const isTerminalDoc = docStatus && (config.lifecycle?.isTerminal?.(docStatus, asString(parsedFrontmatter.type) ?? null)
+    ?? config.lifecycle?.terminalStatuses?.has?.(docStatus));
   // Track where currentState came from so renderers can prefix `(auto)` on
   // body-scraped values. Frontmatter wins silently; body-scraped values flag
   // their origin so the user knows the string was inferred (and that adding

package/src/render.mjs

@@ -404,7 +404,7 @@ export function renderBriefing(index, config) {
 }
 
 export function renderCheck(index, config, opts = {}) {
-  const defaultRenderer = (idx) => _renderCheck(idx, opts);
+  const defaultRenderer = (idx) => _renderCheck(idx, config, opts);
   if (!config._execution?.suppressSideEffects && config.hooks.renderCheck) {
     try { return config.hooks.renderCheck(index, defaultRenderer); }
     catch (err) { warn(`Hook 'renderCheck' threw: ${err.message}`); }
@@ -500,12 +500,26 @@ export function renderManualFixes(index) {
   return lines.join('\n');
 }
 
-function _renderCheck(index, opts = {}) {
+export function buildReferenceValidationCoverage(index, config) {
+  let checkedDocs = 0;
+  let terminalDocsSkipped = 0;
+  for (const doc of index.docs) {
+    const terminal = config.lifecycle.isTerminal?.(doc.status, doc.type)
+      ?? config.lifecycle.terminalStatuses.has(doc.status);
+    if (terminal) terminalDocsSkipped++;
+    else checkedDocs++;
+  }
+  return { checkedDocs, terminalDocsSkipped };
+}
+
+function _renderCheck(index, config, opts = {}) {
   const { errorsOnly, noCollapse, verbose } = opts;
+  const referenceValidation = buildReferenceValidationCoverage(index, config);
   const lines = ['Check', ''];
   lines.push(`- docs scanned: ${index.docs.length}`);
   lines.push(`- errors: ${index.errors.length}`);
   lines.push(`- warnings: ${index.warnings.length}`);
+  lines.push(`- reference validation: ${referenceValidation.checkedDocs} docs checked; ${referenceValidation.terminalDocsSkipped} terminal docs skipped`);
   lines.push('');
 
   if (index.errors.length > 0) {

package/src/section.mjs

@@ -9,6 +9,7 @@ export function walkSections(body) {
   const headingRe = /^(#{1,6})\s+(.+?)\s*$/;
   const sections = [];
   let fenceChar = null;
+  let h2Ancestor = null;
 
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
@@ -22,13 +23,18 @@ export function walkSections(body) {
     if (fenceChar !== null) continue;
     const h = line.match(headingRe);
     if (!h) continue;
+    const level = h[1].length;
+    const heading = h[2];
+    if (level === 1) h2Ancestor = null;
     sections.push({
-      level: h[1].length,
-      heading: h[2],
+      level,
+      heading,
+      h2Ancestor: level > 2 ? h2Ancestor : null,
       lineStart: i + 1, // 1-indexed
       lineEnd: lines.length, // patched below
       bodyLineStart: i + 2,
     });
+    if (level === 2) h2Ancestor = heading;
   }
 
   for (let i = 0; i < sections.length; i++) {
@@ -111,6 +117,7 @@ export function detectMarker(heading) {
 // codepoint was. Reported by the owner, 2026-08-16.
 const PHASE_DECORATION = String.raw`[\s>*_~\`#-]*(?:[✅🚧⬜🟡⏭☑✔✓◻☐⬛🔴🔄][︎️]?\s*)*`;
 const PHASE_LEAD = new RegExp(`^${PHASE_DECORATION}phase\\b`, 'i');
+const FILES_MANIFEST_ANCESTOR = new RegExp(`^${PHASE_DECORATION}files\\b`, 'i');
 
 // "Phase 3 outcome" is commentary ABOUT a phase, not a phase. Counting it
 // inflates the phase set, and because `findActivePhase` ranks blocked above
@@ -126,9 +133,33 @@ const PHASE_COMMENTARY = new RegExp(
   'i',
 );
 
+// Compound commentary shapes proven against the full platform corpus. Keep
+// these anchored immediately after the phase identifier: the individual nouns
+// all collide with genuine work. In particular, do not add bare `status`,
+// `audit`, `design`, `shape`, `plan`, `pre-plan`, or `gap-check`; the corpus has
+// executable phases with each of those names. The dated gap-check form below is
+// a status report, while `Phase N — gap-check fixes` remains a real phase.
+const PHASE_COMPOUND_COMMENTARY = new RegExp(
+  `^${PHASE_DECORATION}phase\\s+\\S+\\s+(?:` +
+    `execution\\s+status|` +
+    `status\\s+snapshot|` +
+    `gap[- ]check\\s+\\d{4}-\\d{2}-\\d{2}|` +
+    `audit\\s+results?|` +
+    `inventory\\s+findings?|` +
+    `deviations\\s*(?:\\+|&|and)\\s*(?:open\\s+questions|notes?)|` +
+    `design\\s+[-—:]\\s*researched|` +
+    `shape\\s+[-—:]\\s*worked\\s+out|` +
+    `sub[- ]phases` +
+  `)\\b`,
+  'i',
+);
+
 export function isPhaseHeading(section) {
   if (section.level !== 3) return false;
-  return PHASE_LEAD.test(section.heading) && !PHASE_COMMENTARY.test(section.heading);
+  if (FILES_MANIFEST_ANCESTOR.test(section.h2Ancestor ?? '')) return false;
+  return PHASE_LEAD.test(section.heading)
+    && !PHASE_COMMENTARY.test(section.heading)
+    && !PHASE_COMPOUND_COMMENTARY.test(section.heading);
 }
 
 // A phase's OWN checklist — the boxes directly under its heading, stopping at

package/src/status-metadata.mjs

@@ -30,7 +30,7 @@ export function resolveStatusMetadata(config) {
         context: contextByStatus.get(name) ?? 'counted',
         staleDays: hasTypeStaleDays ? typeDef.staleDays[name] : (config.staleDaysByStatus?.[name] ?? null),
         startable: config.lifecycle.startableStatuses.has(name),
-        terminal: config.lifecycle.terminalStatuses.has(name),
+        terminal: config.lifecycle.isTerminal?.(name, type) ?? config.lifecycle.terminalStatuses.has(name),
         archive: config.lifecycle.archiveStatuses.has(name),
         filed: config.lifecycle.filedStatuses.get(name) ?? null,
         skipStale,

package/src/validate.mjs

@@ -259,18 +259,20 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
   // exit code with a hard error.
   const docDir = path.dirname(path.join(config.repoRoot, doc.path));
   const allRefFields = [...(config.referenceFields.bidirectional || []), ...(config.referenceFields.unidirectional || [])];
-  const skipRefValidation = config.lifecycle.terminalStatuses.has(doc.status)
-    || config.lifecycle.skipsWarnings(doc.status, doc.type);
+  const skipRefValidation = config.lifecycle.isTerminal?.(doc.status, doc.type)
+    ?? config.lifecycle.terminalStatuses.has(doc.status);
   if (!skipRefValidation) {
+    const compatibilityWarning = config.lifecycle.skipsWarnings(doc.status, doc.type);
     for (const field of allRefFields) {
       for (const relPath of (doc.refFields[field] || [])) {
         if (!resolveRefPath(relPath, docDir, config.repoRoot)) {
-          doc.errors.push({
+          const issue = {
             path: doc.path,
-            level: 'error',
+            level: compatibilityWarning ? 'warning' : 'error',
             message: `${field} entry \`${relPath}\` does not resolve to an existing file.`,
-            meta: { kind: 'ref-resolution', field, relPath },
-          });
+            meta: { kind: compatibilityWarning ? 'ref-resolution-compat' : 'ref-resolution', field, relPath },
+          };
+          (compatibilityWarning ? doc.warnings : doc.errors).push(issue);
         }
       }
     }
@@ -326,7 +328,7 @@ function candidatePathsForType(docs, type) {
 // name implies one (e.g. `related_plans` → plans only).
 export function enrichRefErrorSuggestions(docs, config) {
   const enrich = (entry) => {
-    if (!entry?.meta || entry.meta.kind !== 'ref-resolution') return;
+    if (!entry?.meta || !['ref-resolution', 'ref-resolution-compat'].includes(entry.meta.kind)) return;
     if (entry._suggested) return;
     const inferred = inferRefFieldType(entry.meta.field);
     const candidates = candidatePathsForType(docs, inferred);