dotmd-cli 0.36.1 → 0.36.3

package/README.md

@@ -97,8 +97,10 @@ Any `.md` file with YAML frontmatter:
 type: doc
 status: active
 updated: 2026-03-14
-module: auth
-surface: backend
+modules:
+  - auth
+surfaces:
+  - backend
 next_step: implement token refresh
 current_state: initial scaffolding complete
 related_plans:
@@ -116,6 +118,8 @@ Design doc content here...
 
 The only required field is `status`. Everything else is optional but unlocks more features. The `type` field (`plan`, `doc`, or `research`) enables type-specific statuses and smarter context briefings.
 
+> **Note:** `module:` and `surface:` (singular) are deprecated as of 0.36.3 — use the plural array forms (`modules:`, `surfaces:`). Run `dotmd lint --fix` to migrate existing docs.
+
 ## Document Types
 
 Every document can have a `type` field in its frontmatter. Types determine which statuses are valid and how the document appears in context briefings.
@@ -177,6 +181,8 @@ dotmd context [--summarize]  Full briefing (LLM-oriented)
 dotmd focus [status]         Detailed view for one status group
 dotmd query [filters]        Filtered search
 dotmd plans                  List all plans
+dotmd modules                Module dashboard (plans grouped by module)
+dotmd module <name>          Plans for one module, grouped by status
 dotmd stale                  List stale docs
 dotmd actionable             List docs with next steps
 dotmd index [--print]        Generate/update docs.md index block
@@ -314,6 +320,18 @@ dotmd check --fix            # auto-fix broken refs + lint + regen index
 
 Validates: required fields, status values, broken reference paths, broken body links (`[text](path.md)`), bidirectional reference symmetry, git date drift, taxonomy mismatches.
 
+#### Per-ref one-way opt-out (`>` prefix)
+
+`referenceFields.bidirectional` is per-field — once a field is bidirectional, every ref in it expects a back-ref. For leaf-to-upstream cases (a plan referencing the audit doc that spawned it; many docs pointing at a single hub) that's noise: the parent shouldn't list every child. Prefix the value with `>` to mark a single ref one-way without changing the field:
+
+```yaml
+related_docs:
+  - docs/sibling-design.md            # bidirectional (default for the field)
+  - "> docs/audit-beyond-platform.md" # one-way upstream — no back-ref expected
+```
+
+The prefix is stripped before path resolution — refs still resolve normally. Works on any ref field. Quote the value (it starts with `>`, which is YAML's block-scalar indicator). Shipped 0.35.0 — closed 7 false-positive warnings in this repo's own corpus.
+
 ### Stats
 
 ```bash
@@ -392,6 +410,39 @@ dotmd briefing                           # compact 5-10 line summary
 dotmd briefing --json                    # machine-readable
 ```
 
+### Modules Dashboard
+
+A triage view for codebases with enough plans that a flat list stops being useful (rule-of-thumb: ~50+ plans across many modules). Composes existing primitives (`modules: []`, `isStale`, `daysSinceUpdate`, `hasNextStep`, `statusOrder`) — no new config.
+
+```bash
+dotmd modules                            # one row per module, dynamic status columns
+dotmd modules --sort cleanup             # rank by (stale × avgAge) / total — "rotting hardest"
+dotmd modules --sort stale|age|nextstep|total
+dotmd modules --type doc                 # docs instead of plans
+dotmd modules --limit 20                 # default 20; --all to disable
+dotmd modules --json                     # includes _totalUnique for double-count detection
+
+dotmd module <name>                      # deep view of one module, plans grouped by status
+dotmd module <name> --sort updated|age   # default sort is status
+dotmd module <name> --json
+```
+
+Workflow for systematic cleanup:
+
+```
+dotmd modules --sort cleanup → walk the top row → dotmd module <name> → triage/archive → next
+```
+
+Notes:
+
+- Status columns are dynamic — only statuses with ≥1 plan render, so default and custom vocabularies both look right.
+- A plan with `modules: [a, b]` counts in both rows. This is intentional. `--json` exposes `_totalUnique` so tooling can detect this if needed.
+- `(none)` is a literal row for unmoduled plans — surfaces unowned work that would otherwise hide in a flat list.
+- Unknown module names exit with `Module 'foo' not found. Did you mean: …?` (substring-first, Levenshtein ≤3 fallback).
+- The dashboard auto-falls-back to a stacked render when the table doesn't fit your terminal width.
+
+`dotmd stale --group module` is the canonical "what's rotting per module" companion view (uses the existing `query --group` mechanism, called out here so it's findable).
+
 ### AI Summaries
 
 ```bash
@@ -694,7 +745,7 @@ export const types = {
     statuses: {
       'active':   { context: 'expanded', staleDays: 14, requiresModule: true },
       'planned':  { context: 'listed', staleDays: 30, requiresModule: true },
-      'blocked':  { context: 'listed', staleDays: 30, skipStale: true },
+      'blocked':  { context: 'listed', skipStale: true },
       'archived': { context: 'counted', archive: true, terminal: true, skipStale: true, skipWarnings: true },
     },
   },
@@ -715,6 +766,8 @@ export const types = {
 
 Object key order determines display order. The config resolver derives `statuses.order`, `lifecycle.*`, `taxonomy.moduleRequiredFor`, and `context.*` from these definitions. Explicit global sections still win when provided.
 
+**Contradiction check.** Combining `skipStale: true` with a `staleDays` value, or `skipWarnings: true` with `requiresModule: true`, makes one of the fields dead config — the boolean wins silently. From 0.36.2, dotmd `warn()`s at config load when it spots either pair, naming the type, status, and conflicting fields. Drop one to silence the warning. The same check runs against the `quiet: true` sugar (which implies both `skipStale` and `skipWarnings` unless explicitly overridden).
+
 ### Array form (also supported)
 
 The traditional array form remains fully backwards compatible:

package/bin/dotmd.mjs

@@ -410,14 +410,27 @@ Types and their default destinations:
 \`<type>\` can be omitted; defaults to \`doc\`.
 \`<name>\` is slugified for the filename.
 
-Body input (prompt type only):
+Body input (all built-in types — required for prompt, optional for plan/doc):
   <text>                 Inline body as 3rd positional
   --message "<text>"     Explicit inline body
   -                      Read body from stdin (heredoc-friendly for agents)
   @path                  Read body from a file
 
+For plan/doc, a single-section body lands under the type's first scaffolded
+section (e.g. \`## Problem\` for plans). If the body already authors
+\`## Section\` headings start-to-finish, the scaffold short-circuits and only
+the title + your body is emitted — no duplicated empty outline below
+(since 0.36.1).
+
 Examples:
   dotmd new plan auth-revamp
+  dotmd new plan auth-revamp "Investigation findings before scoping…"
+  dotmd new plan full-spec - <<'EOF'
+  ## Problem
+  …
+  ## Phases
+  …
+  EOF
   dotmd new prompt cleanup-tomorrow "look at remaining lint warnings"
   dotmd new prompt resume-foo - <<'EOF'
   multi-line

package/dotmd.config.example.mjs

@@ -36,6 +36,11 @@ export const excludeDirs = ['evidence'];
 // `terminal` and `quiet` are orthogonal. Mark a status `terminal` only when it represents closure
 // (excluded from active-work scope). Use `quiet` for noise suppression without closure semantics.
 //
+// Contradiction check (since 0.36.2): dotmd `warn()`s at config-load when a status combines
+// `skipStale: true` with a `staleDays` value (the number is silently ignored) or
+// `skipWarnings: true` with `requiresModule: true` (the module requirement can never fire).
+// The same check applies via the `quiet: true` sugar. Drop one of the conflicting fields to silence.
+//
 // Each plan stop-status maps to a distinct unstuck-action — the test for whether
 // the vocabulary earns its weight. blocked = monitor (external arrival on its own
 // schedule), awaiting = ask (chase the human/decision), queued-after = check the
@@ -151,6 +156,9 @@ export const context = {
   recentStatuses: ['active', 'ready', 'planned'],
   recentLimit: 10,
   truncateNextStep: 80,
+  // Cap on slugs shown in the "Stale: …" tail before "…and N more (run `dotmd stale`)"
+  // takes over (since 0.36.2). Raise on wide terminals; lower for tighter briefings.
+  staleTailLimit: 8,
 };
 
 // Display settings

package/package.json

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

package/src/config.mjs

@@ -158,6 +158,16 @@ function normalizeRichStatuses(config, userConfig) {
       const quietImpliesSkipStale = p.quiet && p.skipStale !== false;
       const quietImpliesSkipWarnings = p.quiet && p.skipWarnings !== false;
 
+      // Contradiction diagnostics — emit at load so dead config doesn't fail silently.
+      const skipStaleEffective = p.skipStale === true || quietImpliesSkipStale;
+      const skipWarningsEffective = p.skipWarnings === true || quietImpliesSkipWarnings;
+      if (skipStaleEffective && p.staleDays != null) {
+        warn(`dotmd config: status "${typeName}.${name}" has skipStale: true and staleDays: ${p.staleDays} — staleDays is ignored. Drop one to silence this warning.`);
+      }
+      if (skipWarningsEffective && p.requiresModule) {
+        warn(`dotmd config: status "${typeName}.${name}" has skipWarnings: true and requiresModule: true — the module requirement can never fire. Drop one to silence this warning.`);
+      }
+
       if (p.archive && !derived.archiveStatuses.includes(name)) derived.archiveStatuses.push(name);
       if ((p.skipStale || quietImpliesSkipStale) && !derived.skipStaleFor.includes(name)) derived.skipStaleFor.push(name);
       if ((p.skipWarnings || quietImpliesSkipWarnings) && !derived.skipWarningsFor.includes(name)) derived.skipWarningsFor.push(name);

package/src/glossary.mjs

@@ -7,7 +7,7 @@ import { bold, dim, green, yellow } from './color.mjs';
 function parseGlossaryTable(content, sectionHeading) {
   const headingRegex = new RegExp(`^##\\s+${sectionHeading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`, 'm');
   const match = content.match(headingRegex);
-  if (!match) return [];
+  if (!match) return { found: false, entries: [] };
 
   const sectionStart = match.index + match[0].length;
   const nextHeading = content.indexOf('\n## ', sectionStart);
@@ -47,7 +47,7 @@ function parseGlossaryTable(content, sectionHeading) {
     entries.push({ term: m[1], meaning: `UI label: "${m[2]}"${m[3] ? ` (${m[3]})` : ''}`, tiers: 'schema→UI' });
   }
 
-  return entries;
+  return { found: true, entries };
 }
 
 function loadGlossary(config) {
@@ -62,7 +62,8 @@ function loadGlossary(config) {
 
   const content = readFileSync(filePath, 'utf8');
   const section = glossaryConfig.section ?? 'Terminology';
-  return parseGlossaryTable(content, section);
+  const result = parseGlossaryTable(content, section);
+  return { ...result, path: glossaryConfig.path, section };
 }
 
 function matchTerm(query, entries) {
@@ -177,9 +178,15 @@ export function runGlossary(argv, config) {
   const listAll = argv.includes('--list');
   const term = argv.find(a => !a.startsWith('-'));
 
-  const entries = loadGlossary(config);
-  if (!entries) die('No glossary configured. Add glossary: { path, section } to your dotmd config.');
-  if (entries.length === 0) die('Glossary section found but no entries parsed.');
+  const result = loadGlossary(config);
+  if (!result) die('No glossary configured. Add glossary: { path, section } to your dotmd config.');
+  if (!result.found) {
+    die(`Glossary section "## ${result.section}" not found in ${result.path}. Add the section, or update glossary.section in dotmd.config.mjs.`);
+  }
+  if (result.entries.length === 0) {
+    die(`Glossary section "## ${result.section}" found in ${result.path} but contains no recognizable entries (expected markdown table or schema→UI bullets).`);
+  }
+  const entries = result.entries;
 
   if (json && listAll) {
     const index = buildIndex(config);

package/src/lint.mjs

@@ -67,11 +67,18 @@ export function runLint(argv, config, opts = {}) {
       }
     }
 
-    // Comma-separated surface → surfaces array
-    const surfaceVal = asString(parsed.surface);
-    if (surfaceVal && surfaceVal.includes(',')) {
-      const values = surfaceVal.split(',').map(s => s.trim()).filter(Boolean);
-      fixes.push({ field: 'surface', oldValue: surfaceVal, newValue: values, type: 'split-to-array' });
+    // Singular `module:` / `surface:` → plural array (F18 deprecation).
+    // Any singular use migrates, regardless of comma — comma-containing values
+    // split on `,`, single values become a one-item list. Merging with any
+    // existing plural array happens at apply-time so the message reflects
+    // just what's being introduced from the singular form.
+    for (const { singular, plural } of [{ singular: 'module', plural: 'modules' }, { singular: 'surface', plural: 'surfaces' }]) {
+      const val = asString(parsed[singular]);
+      if (!val) continue;
+      const values = val.includes(',')
+        ? val.split(',').map(s => s.trim()).filter(Boolean)
+        : [val];
+      fixes.push({ field: singular, oldValue: val, newValue: values, pluralKey: plural, type: 'singular-to-plural' });
     }
 
     // Trailing whitespace in values
@@ -111,8 +118,8 @@ export function runLint(argv, config, opts = {}) {
             process.stdout.write(dim(`    ${f.oldValue} → ${f.newValue}\n`));
           } else if (f.type === 'infer-status') {
             process.stdout.write(dim(`    missing status (fixable via AI)\n`));
-          } else if (f.type === 'split-to-array') {
-            process.stdout.write(dim(`    ${f.field}: "${f.oldValue}" → surfaces: [${f.newValue.join(', ')}]\n`));
+          } else if (f.type === 'singular-to-plural') {
+            process.stdout.write(dim(`    ${f.field}: "${f.oldValue}" → ${f.pluralKey}: [${f.newValue.join(', ')}]\n`));
           } else if (f.type === 'eof') {
             process.stdout.write(dim(`    missing newline at end of file\n`));
           } else if (f.type === 'add') {
@@ -147,7 +154,7 @@ export function runLint(argv, config, opts = {}) {
     const keyRenames = [];
     let needsEofFix = false;
     const trimFixes = [];
-    const splitToArray = [];
+    const singularToPlural = [];
 
     for (const f of fixes) {
       if (f.type === 'rename-key') {
@@ -156,8 +163,8 @@ export function runLint(argv, config, opts = {}) {
         needsEofFix = true;
       } else if (f.type === 'trim') {
         trimFixes.push(f);
-      } else if (f.type === 'split-to-array') {
-        splitToArray.push(f);
+      } else if (f.type === 'singular-to-plural') {
+        singularToPlural.push(f);
       } else {
         updates[f.field] = f.newValue;
       }
@@ -183,23 +190,23 @@ export function runLint(argv, config, opts = {}) {
         }
       }
 
-      // Apply split-to-array fixes (surface: a, b → surfaces: array)
-      for (const sa of splitToArray) {
+      // Apply singular-to-plural fixes (module/surface → modules/surfaces array).
+      // Removes the singular key line; merges its value(s) into the plural array,
+      // or creates the plural block if absent. Duplicates are skipped.
+      for (const sa of singularToPlural) {
         let raw = readFileSync(filePath, 'utf8');
         const { frontmatter: fm } = extractFrontmatter(raw);
-        // Remove the scalar surface line
         let newFm = fm.replace(new RegExp(`^${escapeRegex(sa.field)}:.*$`, 'm'), '').replace(/\n{2,}/g, '\n');
-        // Check if surfaces: array already exists
-        if (newFm.includes('surfaces:')) {
-          // Append new values to existing array
+        const pluralLineRe = new RegExp(`^${escapeRegex(sa.pluralKey)}:[ \\t]*$`, 'm');
+        if (pluralLineRe.test(newFm)) {
           for (const val of sa.newValue) {
-            if (!newFm.includes(`- ${val}`)) {
-              newFm = newFm.replace(/^(surfaces:)$/m, `$1\n  - ${val}`);
+            const hasVal = new RegExp(`^[ \\t]*-[ \\t]+${escapeRegex(val)}[ \\t]*$`, 'm').test(newFm);
+            if (!hasVal) {
+              newFm = newFm.replace(pluralLineRe, `${sa.pluralKey}:\n  - ${val}`);
             }
           }
         } else {
-          // Create new surfaces: array
-          newFm += `\nsurfaces:\n${sa.newValue.map(v => `  - ${v}`).join('\n')}`;
+          newFm += `\n${sa.pluralKey}:\n${sa.newValue.map(v => `  - ${v}`).join('\n')}`;
         }
         raw = replaceFrontmatter(raw, newFm.trim());
         writeFileSync(filePath, raw, 'utf8');
@@ -250,8 +257,8 @@ export function runLint(argv, config, opts = {}) {
         } else {
           process.stdout.write(`${prefix}  ${dim('status: (missing) — AI inference unavailable')}\n`);
         }
-      } else if (f.type === 'split-to-array') {
-        process.stdout.write(`${prefix}  ${dim(`${f.field}: "${f.oldValue}" → surfaces: [${f.newValue.join(', ')}]`)}\n`);
+      } else if (f.type === 'singular-to-plural') {
+        process.stdout.write(`${prefix}  ${dim(`${f.field}: "${f.oldValue}" → ${f.pluralKey}: [${f.newValue.join(', ')}]`)}\n`);
       } else if (f.type === 'add') {
         process.stdout.write(`${prefix}  ${dim(`add ${f.field}: ${f.newValue}`)}\n`);
       } else {

package/src/query.mjs

@@ -251,7 +251,13 @@ function getDocSummary(doc, config) {
 
 function renderQueryResults(docs, filters, config) {
   process.stdout.write('Query\n\n');
-  process.stdout.write(`- results: ${docs.length}\n`);
+  const total = filters._totalBeforeLimit ?? docs.length;
+  const truncated = !filters.all && total > docs.length;
+  if (truncated) {
+    process.stdout.write(`- results: ${docs.length} of ${total} ${dim('(use --all to see all)')}\n`);
+  } else {
+    process.stdout.write(`- results: ${docs.length}\n`);
+  }
   if (filters.types?.length) process.stdout.write(`- type: ${filters.types.join(', ')}\n`);
   if (filters.statuses?.length) process.stdout.write(`- status: ${filters.statuses.join(', ')}\n`);
   if (filters.keyword) process.stdout.write(`- keyword: ${filters.keyword}\n`);
@@ -381,12 +387,13 @@ function renderPlansOutput(docs, filters, config, opts = {}) {
     // Triage view: flat, sorted by recency, tag on right.
     process.stdout.write('\n');
     renderPlanRows(docs, filters, maxWidth, { showTag: true });
-    // Footer when the result was capped.
-    const hidden = totalAll - totalShown;
-    if (hidden > 0) {
-      process.stdout.write('\n');
-      process.stdout.write(dim(`  ${hidden} more ${noun}  ·  dotmd ${noun} --all  ·  dotmd ${noun} status\n`));
-    }
+  }
+
+  // Footer when the result was capped — emit for every view shape.
+  const hidden = totalAll - totalShown;
+  if (hidden > 0) {
+    process.stdout.write('\n');
+    process.stdout.write(dim(`  ${hidden} more ${noun}  ·  dotmd ${noun} --all  ·  dotmd ${noun} status\n`));
   }
 
   process.stdout.write('\n');

package/src/render.mjs

@@ -275,7 +275,13 @@ function _renderContext(index, config, opts = {}) {
 
   const stale = index.docs.filter(d => d.isStale && !config.lifecycle.skipStaleFor.has(d.status));
   if (stale.length) {
-    lines.push(`Stale: ${stale.map(d => `${toSlug(d)} (${d.daysSinceUpdate}d)`).join(', ')}`);
+    const cap = config.context?.staleTailLimit ?? 8;
+    const shown = stale.slice(0, cap).map(d => `${toSlug(d)} (${d.daysSinceUpdate}d)`).join(', ');
+    const overflow = stale.length - cap;
+    const tail = overflow > 0
+      ? `${shown}, …and ${overflow} more (run \`dotmd stale\` for the full list)`
+      : shown;
+    lines.push(`Stale: ${tail}`);
   } else {
     lines.push('Stale: none');
   }

package/src/validate.mjs

@@ -103,7 +103,7 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
   }
 
   if (config.moduleRequiredStatuses.has(doc.status) && !doc.modules?.length) {
-    doc.errors.push({ path: doc.path, level: 'error', message: '`module` is required for active/ready/planned/blocked docs; use a real module, `platform`, or `none`. Accepts singular `module:` or plural `modules:` list.' });
+    doc.errors.push({ path: doc.path, level: 'error', message: '`modules` is required for active/ready/planned/blocked docs; use a real module, `platform`, or `none`.' });
   }
 
   if (config.validSurfaces && !config.lifecycle.skipWarningsFor.has(doc.status)) {
@@ -114,6 +114,30 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
     }
   }
 
+  // F18: Singular `module:` / `surface:` are deprecated in favor of plural arrays.
+  // The reader still merges singular into plural transparently (back-compat),
+  // but new usage should always go through the plural form. The migration
+  // target is inlined in the message so `dotmd lint --fix` users see exactly
+  // what they'll end up with — and so non-fix readers can hand-migrate.
+  // Suppress for archived/terminal docs (same noise-control rule as F2).
+  if (!config.lifecycle.skipWarningsFor.has(doc.status)) {
+    for (const { singular, plural } of [{ singular: 'module', plural: 'modules' }, { singular: 'surface', plural: 'surfaces' }]) {
+      const singularValue = frontmatter[singular];
+      if (!singularValue) continue;
+      const pluralValue = Array.isArray(frontmatter[plural]) ? frontmatter[plural] : [];
+      const merged = [];
+      for (const v of [singularValue, ...pluralValue]) {
+        if (typeof v === 'string' && v && !merged.includes(v)) merged.push(v);
+      }
+      const target = `${plural}: [${merged.map(v => `"${v}"`).join(', ')}]`;
+      doc.warnings.push({
+        path: doc.path,
+        level: 'warning',
+        message: `\`${singular}:\` (singular) is deprecated — use \`${target}\`. Run \`dotmd lint --fix\` to migrate.`,
+      });
+    }
+  }
+
   // Prompts are intentionally body-only one-shot artifacts: the slug names the
   // prompt, the body IS the payload. Forcing a `title` or blockquote `summary`
   // is friction the prompt format was designed around.
@@ -357,27 +381,6 @@ export function validatePlanShape(doc, body, frontmatter, config) {
     });
   }
 
-  // 3. surface AND surfaces both populated with DIVERGENT values. When the
-  // singular value is already a member of the plural array, src/index.mjs
-  // merges them transparently — warning would be noise. Only divergence
-  // actually risks data loss when readers consult one form vs. the other.
-  if (frontmatter.surface && Array.isArray(frontmatter.surfaces) && frontmatter.surfaces.length > 0
-      && !frontmatter.surfaces.includes(frontmatter.surface)) {
-    doc.warnings.push({
-      path: doc.path,
-      level: 'warning',
-      message: `Both \`surface\` (singular: \`${frontmatter.surface}\`) and \`surfaces\` (array) are set with different values. Pick one — prefer \`surfaces\` array form.`,
-    });
-  }
-  if (frontmatter.module && Array.isArray(frontmatter.modules) && frontmatter.modules.length > 0
-      && !frontmatter.modules.includes(frontmatter.module)) {
-    doc.warnings.push({
-      path: doc.path,
-      level: 'warning',
-      message: `Both \`module\` (singular: \`${frontmatter.module}\`) and \`modules\` (array) are set with different values. Pick one — prefer \`modules\` array form.`,
-    });
-  }
-
   if (!body) return;
 
   // 4. Heading drift: case + name variants