dotmd-cli 0.31.2 → 0.31.4

package/bin/dotmd.mjs

@@ -690,10 +690,11 @@ async function main() {
 
   const config = await resolveConfig(process.cwd(), explicitConfig);
 
-  // Init — now has access to config for Claude command generation
+  // Init — runInit re-resolves the config from disk internally (after any
+  // starter-config write), so we don't need to pre-pass it.
   if (command === 'init') {
     const { runInit } = await import('../src/init.mjs');
-    runInit(process.cwd(), config.configFound ? config : null, { dryRun });
+    await runInit(process.cwd(), config, { dryRun });
     return;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.31.2",
+  "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/doctor.mjs

@@ -67,27 +67,39 @@ export function runDoctor(argv, config, opts = {}) {
   process.stdout.write('\n' + bold('3. Syncing dates from git...') + '\n');
   runTouch(['--git'], config, { dryRun });
 
-  // Step 4: Regenerate index
-  if (config.indexPath) {
-    process.stdout.write('\n' + bold('4. Regenerating index...') + '\n');
-    if (!dryRun) {
-      const index = buildIndex(config);
-      writeIndex(renderIndexFile(index, config), config);
-      process.stdout.write('Index updated.\n');
-    } else {
-      process.stdout.write('[dry-run] Would regenerate index.\n');
-    }
+  // Step 4: Regenerate index. Heading always prints so the numbering stays
+  // `1,2,3,4,5,6` even when `index.path` isn't configured — pre-fix this was
+  // gated on `config.indexPath`, producing `1,2,3,5,6` on repos with no index.
+  process.stdout.write('\n' + bold('4. Regenerating index...') + '\n');
+  if (!config.indexPath) {
+    process.stdout.write('No index path configured (skip).\n');
+  } else if (dryRun) {
+    process.stdout.write('[dry-run] Would regenerate index.\n');
+  } else {
+    const index = buildIndex(config);
+    writeIndex(renderIndexFile(index, config), config);
+    process.stdout.write('Index updated.\n');
   }
 
-  // Step 5: Refresh Claude Code commands
-  const claudeResults = dryRun ? [] : scaffoldClaudeCommands(config.repoRoot, config);
-  if (claudeResults.some(r => r.action !== 'current' && r.action !== 'skipped')) {
-    process.stdout.write('\n' + bold('5. Claude Code commands:') + '\n');
-    for (const r of claudeResults) {
-      if (r.action === 'updated') {
-        process.stdout.write(`${green('Updated')} .claude/commands/${r.name} (v${r.from} → v${r.to})\n`);
-      } else if (r.action === 'created') {
-        process.stdout.write(`${green('Created')} .claude/commands/${r.name}\n`);
+  // Step 5: Refresh Claude Code commands. Always print the heading so the
+  // numbering stays `1,2,3,4,5,6` — pre-fix it was conditional, so a doctor
+  // run where everything was already current printed `1,2,3,4,6` with `5.`
+  // silently missing.
+  process.stdout.write('\n' + bold('5. Claude Code commands:') + '\n');
+  if (dryRun) {
+    process.stdout.write('[dry-run] Would refresh .claude/commands/ if outdated.\n');
+  } else {
+    const claudeResults = scaffoldClaudeCommands(config.repoRoot, config);
+    const changes = claudeResults.filter(r => r.action === 'updated' || r.action === 'created');
+    if (changes.length === 0) {
+      process.stdout.write('Nothing to refresh.\n');
+    } else {
+      for (const r of changes) {
+        if (r.action === 'updated') {
+          process.stdout.write(`${green('Updated')} .claude/commands/${r.name} (v${r.from} → v${r.to})\n`);
+        } else if (r.action === 'created') {
+          process.stdout.write(`${green('Created')} .claude/commands/${r.name}\n`);
+        }
       }
     }
   }

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,9 +1,11 @@
 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';
 import { warn } from './util.mjs';
 import { scaffoldClaudeCommands } from './claude-commands.mjs';
+import { resolveConfig } from './config.mjs';
 
 // Subdirectories scaffolded under docsRoot and tracked separately during scans.
 // Each maps to a builtin type (plan, prompt). New types added here should also
@@ -151,7 +153,7 @@ function generateDetectedConfig(scan, rootPath) {
   return lines.join('\n');
 }
 
-export function runInit(cwd, config, opts = {}) {
+export async function runInit(cwd, config, opts = {}) {
   const { dryRun = false } = opts;
   const configPath = path.join(cwd, 'dotmd.config.mjs');
   const docsDir = path.join(cwd, 'docs');
@@ -259,12 +261,38 @@ export 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
+  // resolveConfig was called before init wrote the starter, so the `if (config)`
+  // gate below silently skipped slash-command scaffolding entirely on first init.
+  // Re-resolving picks up STARTER_CONFIG (or any pre-existing config) in the
+  // real-run path; in dry-run with no on-disk config, it returns the merged
+  // DEFAULTS, which is enough for the preview line (`would create…`).
+  //
   // Reports all four scaffold outcomes so the user can't be surprised by
   // either a silent regenerate (pre-fix: `updated` was unreported) or by
   // dotmd skipping a user-managed file (pre-fix: `skipped` was unreported).
-  if (config) {
-    const results = scaffoldClaudeCommands(cwd, config, { dryRun });
+  const scaffoldConfig = await resolveConfig(cwd);
+  if (scaffoldConfig) {
+    const results = scaffoldClaudeCommands(cwd, scaffoldConfig, { dryRun });
     for (const r of results) {
       const filename = `.claude/commands/${r.name}`;
       if (r.action === 'created') {

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/pickup-card.mjs

@@ -1,7 +1,7 @@
 import { readFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
-import { asString, toRepoPath, resolveDocPath } from './util.mjs';
+import { asString, toRepoPath, resolveDocPath, resolveRefPath } from './util.mjs';
 import { walkSections, findSection, findActivePhase, summarizePhases, isPhaseHeading, detectMarker } from './section.mjs';
 import { dim, green } from './color.mjs';
 
@@ -29,7 +29,14 @@ function statusSummary(counts) {
   return order.filter(k => counts[k]).map(k => `${counts[k]}${icons[k]}`).join(' ');
 }
 
-function readRelatedSummary(rawList, config) {
+// `docDir` is the directory of the doc whose frontmatter we're reading.
+// Pre-fix: this used `resolveDocPath` which only tries repo-root and docsRoots-
+// relative, NOT doc-relative — so a bare basename like `sibling-plan.md` written
+// in `docs/plans/foo.md`'s `related_plans:` always showed `(missing)`, even
+// though graph/validate resolve the same ref fine via `resolveRefPath`. Now
+// matches graph's resolver semantics: doc-relative first, then repo-relative;
+// docsRoots-relative is kept as a final fallback for legacy refs.
+function readRelatedSummary(rawList, config, docDir) {
   const list = Array.isArray(rawList) ? rawList : (typeof rawList === 'string' && rawList.trim() ? [rawList] : []);
   const out = [];
   for (const ref of list) {
@@ -37,7 +44,10 @@ function readRelatedSummary(rawList, config) {
     const refStr = String(ref).trim();
     if (!refStr) continue;
     let abs = null;
-    try { abs = resolveDocPath(refStr, config); } catch { abs = null; }
+    try {
+      abs = resolveRefPath(refStr, docDir, config.repoRoot)
+        ?? resolveDocPath(refStr, config);
+    } catch { abs = null; }
     if (!abs || !existsSync(abs)) {
       out.push({ ref: refStr, status: null, missing: true });
       continue;
@@ -96,10 +106,13 @@ export function buildCard(filePath, raw, config) {
   const currentState = truncate(cleanInline(fm.current_state), CAPS.currentState);
   const nextStep = truncate(cleanInline(fm.next_step), CAPS.nextStep);
 
-  // Related plans (compressed: slug + status only — show all, don't cap count)
+  // Related plans (compressed: slug + status only — show all, don't cap count).
+  // docDir lets the resolver try same-dir basenames first — graph/validate do this
+  // already; pickup-card now matches.
+  const docDir = path.dirname(filePath);
   const related = [
-    ...readRelatedSummary(fm.parent_plan, config).map(r => ({ ...r, kind: 'parent' })),
-    ...readRelatedSummary(fm.related_plans, config).map(r => ({ ...r, kind: 'related' })),
+    ...readRelatedSummary(fm.parent_plan, config, docDir).map(r => ({ ...r, kind: 'parent' })),
+    ...readRelatedSummary(fm.related_plans, config, docDir).map(r => ({ ...r, kind: 'related' })),
   ];
 
   // Phases summary + active phase (pointer only, no body)

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`;
 }
 
@@ -297,7 +329,13 @@ export function renderBriefing(index, config) {
   if (parts.length) lines.push(parts.join(' | '));
 
   const stale = index.docs.filter(d => d.isStale && !config.lifecycle.skipStaleFor.has(d.status)).length;
-  lines.push(`Stale: ${stale} | Errors: ${index.errors.length} | Warnings: ${index.warnings.length}`);
+  // Append a hint when errors are present — otherwise the user sees `Errors: 1`
+  // with no clue what or where. `dotmd check` is the canonical detail view.
+  const errorCount = index.errors.length;
+  const errorPart = errorCount > 0
+    ? `Errors: ${errorCount} ${dim('(run `dotmd check` to see)')}`
+    : `Errors: ${errorCount}`;
+  lines.push(`Stale: ${stale} | ${errorPart} | Warnings: ${index.warnings.length}`);
 
   try {
     const staleLeases = findStaleLeases(config);
@@ -402,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}`); }
@@ -410,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;