dotmd-cli 0.31.3 → 0.31.4

package/package.json

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

package/src/hud.mjs

@@ -3,7 +3,8 @@ import path from 'node:path';
 import { readLeases, findStaleLeases, currentSessionId } from './lease.mjs';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { asString, toRepoPath } from './util.mjs';
-import { green, yellow, dim } from './color.mjs';
+import { green, yellow, red, dim } from './color.mjs';
+import { buildIndex } from './index.mjs';
 
 const MAX_PREVIEW = 5;
 
@@ -71,7 +72,17 @@ export function buildHud(config) {
   const stale = findStaleLeases(config).map(l => l.path);
   const prompts = findActionablePrompts(config);
 
-  return { owned, stale, prompts };
+  // Validation error count — hud's "silent when clean" contract should treat
+  // `check` errors as not-clean. Without this, a SessionStart hook firing hud
+  // can leave the agent with no visible signal that a check is failing.
+  // buildIndex wraps the same scan every other read command does; cost is fine.
+  let errors = 0;
+  try {
+    const index = buildIndex(config);
+    errors = index.errors.length;
+  } catch { /* swallow — bad config shouldn't break the SessionStart hook */ }
+
+  return { owned, stale, prompts, errors };
 }
 
 export function runHud(argv, config) {
@@ -93,6 +104,9 @@ export function runHud(argv, config) {
   if (hud.stale.length > 0) {
     lines.push(yellow(`⚠ ${hud.stale.length} stuck lease${hud.stale.length === 1 ? '' : 's'} >24h  ${dim('(run: dotmd release --stale)')}`));
   }
+  if (hud.errors > 0) {
+    lines.push(red(`✗ ${hud.errors} validation error${hud.errors === 1 ? '' : 's'}  ${dim('(run: dotmd check)')}`));
+  }
 
   if (lines.length === 0) return; // silent when clean
   process.stdout.write(lines.join('\n') + '\n');

package/src/index.mjs

@@ -125,7 +125,18 @@ export function parseDocFile(filePath, config) {
   const headingTitle = extractFirstHeading(body);
   const title = asString(parsedFrontmatter.title) ?? headingTitle ?? path.basename(filePath, '.md');
   const summary = asString(parsedFrontmatter.summary) ?? extractSummary(body) ?? null;
-  const currentState = asString(parsedFrontmatter.current_state) ?? extractStatusSnapshot(body) ?? 'No current_state set';
+  // For terminal-status docs (archived / reference / deprecated by default),
+  // skip the body-scrape and the "No current_state set" fallback when the user
+  // didn't set `current_state:` in frontmatter explicitly. Body text on a
+  // settled doc often contains stale "in progress" / "FIXED (uncommitted)"
+  // snapshots from when the doc was live; surfacing those in the index lies
+  // about current state. Frontmatter still wins if explicit — the audit's
+  // 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 currentState = fmCurrentState
+    ?? (isTerminalDoc ? null : (extractStatusSnapshot(body) ?? 'No current_state set'));
   const nextStep = asString(parsedFrontmatter.next_step) ?? extractNextStep(body) ?? null;
   const blockers = normalizeBlockers(parsedFrontmatter.blockers);
   const surface = asString(parsedFrontmatter.surface) ?? null;

package/src/init.mjs

@@ -1,4 +1,5 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { green, dim, yellow } from './color.mjs';
@@ -260,6 +261,23 @@ export async function runInit(cwd, config, opts = {}) {
     process.stdout.write(`  ${dryTag}${green('create')}  .gitignore\n`);
   }
 
+  // Warn when docs/ is gitignored — silently scaffolding into an ignored dir
+  // means every doc we manage falls outside git, which a doc-management tool
+  // should not leave the user guessing about. Three of gmax's six docs were
+  // force-added; the other three were untracked and the user had no way to
+  // know without `git ls-files docs/`.
+  if (existsSync(path.join(cwd, '.git'))) {
+    const probe = spawnSync('git', ['check-ignore', '-q', 'docs/'], {
+      cwd, encoding: 'utf8',
+    });
+    // Exit 0 → ignored. Exit 1 → not ignored. Exit 128 → not in repo / git error.
+    if (probe.status === 0) {
+      process.stdout.write(`\n  ${yellow('notice')}  docs/ is gitignored — files dotmd manages will NOT be tracked.\n`);
+      process.stdout.write(`           Add an exception to .gitignore so docs/ is tracked:\n`);
+      process.stdout.write(`             !docs/\n`);
+    }
+  }
+
   // Claude Code integration — auto-detect .claude/ directory.
   // Re-resolve config so the scaffold sees whatever we (may have) just written.
   // Pre-fix: the dispatcher passed `null` to runInit on a fresh repo because

package/src/new.mjs

@@ -13,6 +13,10 @@ const BUILTIN_TEMPLATES = {
   doc: {
     description: 'Reference doc, design note, module overview — build-up shape lite',
     defaultStatus: 'active',
+    // Body input optional. When passed (inline / --message / @file / stdin),
+    // it lands in the Overview section. Without it, Overview is left blank
+    // and the user fills it in.
+    acceptsBody: true,
     frontmatter: (s, d) => [
       'type: doc',
       `status: ${s}`,
@@ -32,7 +36,7 @@ const BUILTIN_TEMPLATES = {
 
 ## Overview
 
-
+${ctx?.bodyInput?.trim() ?? ''}
 
 ## Version History
 

package/src/query.mjs

@@ -59,7 +59,7 @@ export function runFocus(index, argv, config) {
   for (const doc of docs) {
     process.stdout.write(`- ${doc.title}\n`);
     process.stdout.write(`  path: ${doc.path}\n`);
-    process.stdout.write(`  state: ${doc.currentState}\n`);
+    if (doc.currentState) process.stdout.write(`  state: ${doc.currentState}\n`);
     if (doc.nextStep) {
       process.stdout.write(`  next: ${doc.nextStep}\n`);
     }
@@ -259,7 +259,7 @@ function renderQueryResults(docs, filters, config) {
     if (doc.daysSinceUpdate != null) process.stdout.write(`  days-since-update: ${doc.daysSinceUpdate}\n`);
     process.stdout.write(`  stale: ${doc.isStale ? 'yes' : 'no'}\n`);
     process.stdout.write(`  path: ${doc.path}\n`);
-    process.stdout.write(`  state: ${doc.currentState}\n`);
+    if (doc.currentState) process.stdout.write(`  state: ${doc.currentState}\n`);
     if (doc.nextStep) process.stdout.write(`  next: ${doc.nextStep}\n`);
     if (doc.owner) process.stdout.write(`  owner: ${doc.owner}\n`);
     if (doc.surfaces?.length) process.stdout.write(`  surfaces: ${doc.surfaces.join(', ')}\n`);

package/src/render.mjs

@@ -70,6 +70,21 @@ function _renderCompactList(index, config) {
     lines.push('');
   }
 
+  // Surface docs without a status (untagged — either no frontmatter at all,
+  // or frontmatter present but no `status:` key). Pre-fix these were silently
+  // dropped because every section filtered by status, so `dotmd list` on a
+  // freshly-init'd brownfield repo with N existing .md files showed just
+  // "Index" and looked like the tool didn't see them. Now they get their own
+  // section with the path so the user can find them and add frontmatter.
+  const untagged = index.docs.filter(d => !d.status);
+  if (untagged.length > 0) {
+    lines.push(bold(`Untagged (${untagged.length})  ${dim('— missing `status:` in frontmatter')}`));
+    for (const doc of untagged) {
+      lines.push(`  ${doc.path}`);
+    }
+    lines.push('');
+  }
+
   return `${lines.join('\n').trimEnd()}\n`;
 }
 
@@ -84,7 +99,10 @@ export function renderVerboseList(index, config) {
 
     lines.push(`${capitalize(status)} (${docs.length})`);
     for (const doc of docs) {
-      const parts = [`- ${doc.title}`, `${capitalize(status)}: ${doc.currentState}`, `(${doc.path})`];
+      const stateLabel = doc.currentState
+        ? `${capitalize(status)}: ${doc.currentState}`
+        : capitalize(status);
+      const parts = [`- ${doc.title}`, stateLabel, `(${doc.path})`];
       if (doc.nextStep) {
         parts.push(`next: ${doc.nextStep}`);
       }
@@ -102,7 +120,10 @@ export function renderVerboseList(index, config) {
 
     lines.push(`${capitalize(status)} (${docs.length})`);
     for (const doc of docs) {
-      const parts = [`- ${doc.title}`, `${capitalize(status)}: ${doc.currentState}`, `(${doc.path})`];
+      const stateLabel = doc.currentState
+        ? `${capitalize(status)}: ${doc.currentState}`
+        : capitalize(status);
+      const parts = [`- ${doc.title}`, stateLabel, `(${doc.path})`];
       if (doc.nextStep) {
         parts.push(`next: ${doc.nextStep}`);
       }
@@ -111,6 +132,17 @@ export function renderVerboseList(index, config) {
     lines.push('');
   }
 
+  // Surface untagged docs (no `status:` in frontmatter, or no frontmatter at
+  // all) — see _renderCompactList for the why.
+  const untagged = index.docs.filter(d => !d.status);
+  if (untagged.length > 0) {
+    lines.push(`Untagged (${untagged.length}) — missing \`status:\` in frontmatter`);
+    for (const doc of untagged) {
+      lines.push(`- ${doc.title} — (${doc.path})`);
+    }
+    lines.push('');
+  }
+
   return `${lines.join('\n').trimEnd()}\n`;
 }
 
@@ -408,7 +440,7 @@ export function renderProgressBar(checklist) {
 }
 
 export function formatSnapshot(doc, config) {
-  const defaultFormatter = (d) => _formatSnapshot(d);
+  const defaultFormatter = (d) => _formatSnapshot(d, config);
   if (config.hooks.formatSnapshot) {
     try { return config.hooks.formatSnapshot(doc, defaultFormatter); }
     catch (err) { warn(`Hook 'formatSnapshot' threw: ${err.message}`); }
@@ -416,7 +448,20 @@ export function formatSnapshot(doc, config) {
   return defaultFormatter(doc);
 }
 
-function _formatSnapshot(doc) {
+function _formatSnapshot(doc, config) {
+  // For terminal statuses (archived, reference, deprecated, etc.) a missing
+  // `current_state` is fine — these are settled docs, no one's expected to be
+  // tracking what they're "currently doing." Pre-fix, the bare-status fallback
+  // rendered as `Reference: No current_state set` everywhere, which looked
+  // like a noisy hint to add a field that the templates never scaffolded.
+  // Now: bare-status line when terminal AND no current_state.
+  // Paired with src/index.mjs's body-scrape suppression for terminal docs —
+  // both layers drop body-derived state when frontmatter is silent.
+  const terminal = config?.lifecycle?.terminalStatuses;
+  const isTerminal = doc.status && terminal && terminal.has(doc.status);
+  if (isTerminal && !doc.currentState) {
+    return capitalize(doc.status);
+  }
   const state = doc.currentState ?? 'No current_state set';
   if (/^active:|^ready:|^planned:|^scoping:|^blocked:|^archived:/i.test(state)) {
     return state;