dotmd-cli 0.31.4 → 0.32.1

package/README.md

@@ -33,9 +33,43 @@ eval "$(dotmd completions bash)"    # add to ~/.bashrc
 eval "$(dotmd completions zsh)"     # add to ~/.zshrc
 ```
 
+## Auto-Detected From Your Markdown
+
+dotmd reads what's already in your `.md` files — you don't have to migrate everything into frontmatter to get useful output.
+
+Add `- [ ]` checkboxes anywhere in the body:
+
+```markdown
+## Polish
+
+- [x] Index regen on every mutation
+- [x] Auto-checklist progress bars
+- [x] Untagged docs surfaced in `list`
+- [ ] SessionStart hook auto-wired by init
+- [ ] Bulk-tag prompt for brownfield repos
+```
+
+`dotmd list` picks them up — zero config, no extra field:
+
+```
+Polish-Pass                   2d  ██████░░░░ 3/5
+```
+
+Same story for these signals, each picked up from body text when the matching frontmatter field is missing:
+
+| Field | Falls back to | Example body |
+|-------|---------------|--------------|
+| `title` | first `# H1` heading | `# Auth Token Refresh` |
+| `summary` | first `> blockquote` line (skipping `Status note` lines) | `> One-line summary of what this doc covers.` |
+| `current_state` | `**Status:** ...`, `- Status: ...`, or `> Status note (...): ...` lines (skipped on terminal docs to avoid stale claims) | `**Status:** Phase 2 underway` |
+| `next_step` | first bullet under a `## Next Step` (or `## Suggested Next Step`) H2 section | `## Next Step`<br>`- wire token refresh into middleware` |
+| Body links | inline `[text](path.md)` references | validated as ref edges by `check` |
+
+Explicit frontmatter always wins. Body extraction is a cushion for partially-tagged docs, not a replacement for it.
+
 ## What It Does
 
-- **Index** — group docs by status, show progress bars, next steps
+- **Index** — group docs by status, with auto-detected progress bars (from `- [ ]` checklists) and next steps
 - **Query** — filter by status, keyword, module, surface, owner, staleness
 - **Validate** — check for missing fields, broken references, broken body links, stale dates
 - **Stats** — health dashboard with staleness, completeness, audit coverage

package/bin/dotmd.mjs

@@ -50,6 +50,7 @@ Lifecycle:
   status <file> <status>            Transition document status
   archive <file>                    Archive (status + move + update refs)
   bulk archive <f1> <f2> ...        Archive multiple files at once
+  bulk-tag [files...]               Tag pre-existing untagged .md files
   touch <file>                      Bump updated date
   touch --git                       Bulk-sync dates from git history
   rename <old> <new>                Rename doc and update all references
@@ -647,6 +648,29 @@ Archives each file: sets status to archived, moves to archive
 directory, updates references, and regenerates the index.
 
 Use --dry-run (-n) to preview changes without writing anything.`,
+
+  'bulk-tag': `dotmd bulk-tag [files...] — fill in type/status frontmatter on pre-existing markdown
+
+Scans the docs tree for files that are missing either \`type:\` or \`status:\`
+(or have no frontmatter block at all) and writes minimal frontmatter so they
+appear in \`dotmd list\`, \`query\`, and \`briefing\`.
+
+Type is inferred from the file's subdir under docsRoot:
+  docs/plans/foo.md    → type: plan,   status: planned
+  docs/prompts/bar.md  → type: prompt, status: pending
+  docs/baz.md          → type: doc,    status: draft
+
+Already-tagged files (both \`type:\` and \`status:\` set) are skipped. Files
+under the archive directory are excluded.
+
+Flags:
+  --type <t>       Override inferred type for every candidate.
+  --status <s>     Override the per-type default status.
+  --json           Emit a structured candidate list.
+  --dry-run (-n)   Preview without writing.
+
+Pass file paths as positional args to scope to those files only; otherwise
+the whole docs tree is scanned.`,
 };
 
 async function main() {
@@ -784,6 +808,8 @@ async function main() {
   if (command === 'status') { const { runStatus } = await import('../src/lifecycle.mjs'); await runStatus(restArgs, config, { dryRun }); return; }
   if (command === 'archive') { const { runArchive } = await import('../src/lifecycle.mjs'); runArchive(restArgs, config, { dryRun }); return; }
   if (command === 'bulk' && restArgs[0] === 'archive') { const { runBulkArchive } = await import('../src/lifecycle.mjs'); runBulkArchive(restArgs.slice(1), config, { dryRun }); return; }
+  if (command === 'bulk' && restArgs[0] === 'tag') { const { runBulkTag } = await import('../src/bulk-tag.mjs'); runBulkTag(restArgs.slice(1), config, { dryRun }); return; }
+  if (command === 'bulk-tag') { const { runBulkTag } = await import('../src/bulk-tag.mjs'); runBulkTag(restArgs, config, { dryRun }); return; }
   if (command === 'touch') { const { runTouch } = await import('../src/lifecycle.mjs'); runTouch(restArgs, config, { dryRun }); return; }
   if (command === 'new') { const { runNew } = await import('../src/new.mjs'); await runNew(restArgs, config, { dryRun, root: rootArg }); return; }
   if (command === 'lint') { const { runLint } = await import('../src/lint.mjs'); runLint(restArgs, config, { dryRun }); return; }

package/package.json

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

package/src/bulk-tag.mjs

@@ -0,0 +1,174 @@
+import path from 'node:path';
+import { readFileSync } from 'node:fs';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { collectDocFiles } from './index.mjs';
+import { toRepoPath, die, warn, resolveDocPath } from './util.mjs';
+import { writeFrontmatter } from './lifecycle.mjs';
+import { green, dim, yellow } from './color.mjs';
+
+// Per-type default status for bulk-tagging pre-existing untagged markdown.
+// These intentionally lean conservative (draft / planned) rather than active —
+// the user is triaging files they didn't create through `dotmd new`, so
+// dropping them into the active list would clutter it without consent. The
+// audit handoff endorsed this conservative default.
+const DEFAULT_STATUS_BY_TYPE = {
+  plan: 'planned',
+  doc: 'draft',
+  prompt: 'pending',
+};
+
+// Derive a doc type from the file's first subdir under its docsRoot:
+//   docs/plans/foo.md   → 'plan'
+//   docs/prompts/bar.md → 'prompt'
+//   docs/baz.md         → 'doc'  (root-level under docsRoot)
+//   docs/notes/qux.md   → 'doc'  (unrecognized subdir falls through)
+// Centralizes the inline `rootLabel.includes('plan')` heuristic from lint.mjs
+// and extends it for prompts.
+export function inferTypeFromPath(filePath, docsRoot) {
+  const rel = path.relative(docsRoot, filePath);
+  const segments = rel.split(path.sep);
+  if (segments.length >= 2) {
+    const sub = segments[0];
+    if (sub === 'plans') return 'plan';
+    if (sub === 'prompts') return 'prompt';
+  }
+  return 'doc';
+}
+
+function parseArgs(argv) {
+  const opts = { typeOverride: null, statusOverride: null, json: false, positional: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--type') { opts.typeOverride = argv[++i]; continue; }
+    if (a === '--status') { opts.statusOverride = argv[++i]; continue; }
+    if (a === '--json') { opts.json = true; continue; }
+    if (a.startsWith('-')) die(`Unknown flag: ${a}`);
+    opts.positional.push(a);
+  }
+  return opts;
+}
+
+function findFileRoot(filePath, config) {
+  const roots = config.docsRoots || [config.docsRoot];
+  return roots.find(r => filePath.startsWith(r + '/')) ?? config.docsRoot;
+}
+
+export function runBulkTag(argv, config, opts = {}) {
+  const { dryRun } = opts;
+  const args = parseArgs(argv);
+
+  // Determine candidate set: explicit positional args take precedence; otherwise
+  // scan all collected doc files (which already excludes config.indexPath).
+  const allFiles = collectDocFiles(config);
+  let pool;
+  if (args.positional.length > 0) {
+    pool = args.positional
+      .map(p => resolveDocPath(p, config))
+      .filter(Boolean);
+    if (pool.length === 0) die('No matching files found for the given paths.');
+  } else {
+    pool = allFiles;
+  }
+
+  // Skip already-archived files (mirrors bulk archive's policy at
+  // lifecycle.mjs:569–573) — settled docs shouldn't be retroactively tagged.
+  const archiveDir = config.archiveDir;
+  const inArchive = (f) => {
+    const root = findFileRoot(f, config);
+    const rel = path.relative(root, f);
+    return rel.startsWith(archiveDir + '/') || rel.startsWith(archiveDir + path.sep);
+  };
+
+  const candidates = [];
+  for (const filePath of pool) {
+    if (inArchive(filePath)) continue;
+    let raw;
+    try { raw = readFileSync(filePath, 'utf8'); } catch (err) { warn(`Could not read ${filePath}: ${err.message}`); continue; }
+    const { frontmatter } = extractFrontmatter(raw);
+    const parsed = frontmatter ? parseSimpleFrontmatter(frontmatter) : {};
+    const hasType = typeof parsed.type === 'string' && parsed.type.length > 0;
+    const hasStatus = typeof parsed.status === 'string' && parsed.status.length > 0;
+    // Only files missing type OR status are candidates; fully tagged files are
+    // skipped silently (bulk-tag's job is to fill gaps, not nag).
+    if (hasType && hasStatus) continue;
+
+    const root = findFileRoot(filePath, config);
+    const inferredType = args.typeOverride ?? (hasType ? parsed.type : inferTypeFromPath(filePath, root));
+    const defaultStatus = DEFAULT_STATUS_BY_TYPE[inferredType] ?? 'draft';
+    const inferredStatus = args.statusOverride ?? (hasStatus ? parsed.status : defaultStatus);
+
+    const updates = {};
+    if (!hasType) updates.type = inferredType;
+    if (!hasStatus) updates.status = inferredStatus;
+
+    candidates.push({
+      filePath,
+      relPath: toRepoPath(filePath, config.repoRoot),
+      hadFrontmatter: Boolean(frontmatter),
+      hadType: hasType,
+      hadStatus: hasStatus,
+      currentType: hasType ? parsed.type : null,
+      currentStatus: hasStatus ? parsed.status : null,
+      newType: inferredType,
+      newStatus: inferredStatus,
+      updates,
+    });
+  }
+
+  if (args.json) {
+    process.stdout.write(JSON.stringify({
+      dryRun: Boolean(dryRun),
+      count: candidates.length,
+      candidates: candidates.map(c => ({
+        path: c.relPath,
+        hadFrontmatter: c.hadFrontmatter,
+        currentType: c.currentType,
+        currentStatus: c.currentStatus,
+        newType: c.newType,
+        newStatus: c.newStatus,
+        updates: c.updates,
+      })),
+    }, null, 2) + '\n');
+    if (!dryRun) {
+      for (const c of candidates) {
+        try { writeFrontmatter(c.filePath, c.updates); }
+        catch (err) { warn(`Failed to tag ${c.relPath}: ${err.message}`); }
+      }
+    }
+    return;
+  }
+
+  if (candidates.length === 0) {
+    process.stdout.write(green('No untagged files found.') + '\n');
+    return;
+  }
+
+  process.stdout.write(`${candidates.length} untagged file(s) — will tag:\n`);
+  const pathWidth = Math.min(60, Math.max(...candidates.map(c => c.relPath.length)));
+  for (const c of candidates) {
+    const fields = [];
+    if (c.updates.type) fields.push(`type: ${c.updates.type}`);
+    if (c.updates.status) fields.push(`status: ${c.updates.status}`);
+    const note = c.hadFrontmatter
+      ? `(added ${Object.keys(c.updates).join(', ')})`
+      : '(no frontmatter)';
+    process.stdout.write(`  ${c.relPath.padEnd(pathWidth)}  ${fields.join('  ')}  ${dim(note)}\n`);
+  }
+
+  if (dryRun) {
+    process.stdout.write(dim('\n[dry-run] No changes made.\n'));
+    return;
+  }
+
+  process.stdout.write('\n');
+  let tagged = 0;
+  for (const c of candidates) {
+    try {
+      writeFrontmatter(c.filePath, c.updates);
+      tagged++;
+    } catch (err) {
+      warn(`Failed to tag ${c.relPath}: ${err.message}`);
+    }
+  }
+  process.stdout.write(green(`Tagged ${tagged} file(s).`) + '\n');
+}

package/src/commands.mjs

@@ -4,7 +4,7 @@
 // templates points at a real command.
 export const KNOWN_COMMANDS = [
   'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'briefing', 'context', 'hud',
-  'focus', 'query', 'plans', 'prompts', 'stale', 'actionable', 'index', 'pickup', 'release', 'finish', 'status', 'archive', 'bulk', 'touch', 'doctor',
+  'focus', 'query', 'plans', 'prompts', 'stale', 'actionable', 'index', 'pickup', 'release', 'finish', 'status', 'archive', 'bulk', 'bulk-tag', 'touch', 'doctor',
   'unblocks', 'health', 'glossary',
   'fix-refs', 'lint', 'rename', 'migrate', 'notion', 'export', 'summary',
   'watch', 'diff', 'new', 'init', 'completions', 'statuses',

package/src/graph.mjs

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { toSlug, toRepoPath, warn } from './util.mjs';
+import { toSlug, toRepoPath, warn, resolveRefPath } from './util.mjs';
 import { bold, red, green, dim } from './color.mjs';
 
 const STATUS_COLORS = {
@@ -60,7 +60,7 @@ export function buildGraph(index, config, filters = {}) {
 
     for (const field of allRefFields) {
       for (const relPath of (doc.refFields[field] || [])) {
-        const resolved = path.resolve(docDir, relPath);
+        const resolved = resolveRefPath(relPath, docDir, config.repoRoot) ?? path.resolve(docDir, relPath);
         const targetPath = toRepoPath(resolved, config.repoRoot);
         const edgeKey = `${doc.path}|${targetPath}|${field}`;
         if (edgeKeys.has(edgeKey)) continue;

package/src/index.mjs

@@ -135,8 +135,27 @@ export function parseDocFile(filePath, config) {
   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'));
+  // 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
+  // `current_state:` to frontmatter would override). The placeholder
+  // `'No current_state set'` is neither — origin stays null.
+  let currentState;
+  let currentStateOrigin = null;
+  if (fmCurrentState) {
+    currentState = fmCurrentState;
+    currentStateOrigin = 'frontmatter';
+  } else if (isTerminalDoc) {
+    currentState = null;
+  } else {
+    const scraped = extractStatusSnapshot(body);
+    if (scraped) {
+      currentState = scraped;
+      currentStateOrigin = 'body';
+    } else {
+      currentState = 'No current_state set';
+    }
+  }
   const nextStep = asString(parsedFrontmatter.next_step) ?? extractNextStep(body) ?? null;
   const blockers = normalizeBlockers(parsedFrontmatter.blockers);
   const surface = asString(parsedFrontmatter.surface) ?? null;
@@ -179,6 +198,7 @@ export function parseDocFile(filePath, config) {
     title,
     summary,
     currentState,
+    currentStateOrigin,
     nextStep,
     blockers,
     updated: asString(parsedFrontmatter.updated) ?? null,

package/src/init.mjs

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
+import os from 'node:os';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { green, dim, yellow } from './color.mjs';
@@ -12,6 +13,40 @@ import { resolveConfig } from './config.mjs';
 // have a matching builtin template so `dotmd new <type>` lands files correctly.
 const TYPE_SUBDIRS = ['plans', 'prompts'];
 
+// Look for a `dotmd hud` SessionStart hook already wired in either the project
+// (.claude/settings{,.local}.json) or the user-global config (~/.claude/
+// settings.json). User-global counts because Claude Code merges global hooks
+// into every project — if the user has it wired globally, this project gets it
+// for free and the init snippet would be noise. We only inspect — we do NOT
+// mutate any file. Settings-merge logic is hostile to do silently (clobbering
+// an existing SessionStart entry would surprise the user), so init just prints
+// a paste-ready snippet when the hook isn't found.
+function detectSessionStartHook(cwd) {
+  const candidates = [
+    path.join(cwd, '.claude', 'settings.json'),
+    path.join(cwd, '.claude', 'settings.local.json'),
+    path.join(os.homedir(), '.claude', 'settings.json'),
+  ];
+  for (const file of candidates) {
+    if (!existsSync(file)) continue;
+    let parsed;
+    try { parsed = JSON.parse(readFileSync(file, 'utf8')); }
+    catch { continue; }
+    const sessionStart = parsed?.hooks?.SessionStart;
+    if (!Array.isArray(sessionStart)) continue;
+    for (const entry of sessionStart) {
+      const inner = Array.isArray(entry?.hooks) ? entry.hooks : [];
+      for (const hook of inner) {
+        if (typeof hook?.command === 'string' && /\bdotmd\s+hud\b/.test(hook.command)) {
+          const rel = file.startsWith(cwd) ? path.relative(cwd, file) : file;
+          return { wired: true, file: rel };
+        }
+      }
+    }
+  }
+  return { wired: false };
+}
+
 const STARTER_CONFIG = `// dotmd.config.mjs — document management configuration
 // All exports are optional. See dotmd.config.example.mjs for full reference.
 
@@ -48,6 +83,10 @@ function scanExistingDocs(dir) {
   const modules = new Set();
   const refFieldNames = new Set();
   let docCount = 0;
+  // Files without a frontmatter block, OR with a block that's missing `type:`
+  // or `status:`. Surfaced by the init "bulk-tag hint" to point users at the
+  // command that can fix them all in one shot.
+  let untaggedCount = 0;
   // Track files per top-level subdir under `dir` (e.g. plans/, prompts/, "")
   // so callers can report what's already there — including files without frontmatter,
   // which are otherwise invisible to detection.
@@ -73,10 +112,13 @@ function scanExistingDocs(dir) {
       try { raw = readFileSync(path.join(d, entry.name), 'utf8'); } catch (err) { warn(`Could not read ${entry.name}: ${err.message}`); continue; }
       const { frontmatter } = extractFrontmatter(raw);
       const subdir = topSubdir ?? '';
-      if (!frontmatter) { bump(subdir, false); continue; }
+      if (!frontmatter) { bump(subdir, false); untaggedCount++; continue; }
       bump(subdir, true);
       const parsed = parseSimpleFrontmatter(frontmatter);
       docCount++;
+      const hasType = typeof parsed.type === 'string' && parsed.type.length > 0;
+      const hasStatus = typeof parsed.status === 'string' && parsed.status.length > 0;
+      if (!hasType || !hasStatus) untaggedCount++;
       if (parsed.status) statuses.add(String(parsed.status).toLowerCase());
       if (parsed.surface) surfaces.add(String(parsed.surface));
       if (Array.isArray(parsed.surfaces)) parsed.surfaces.forEach(s => surfaces.add(String(s)));
@@ -91,7 +133,7 @@ function scanExistingDocs(dir) {
   }
 
   walk(dir, null);
-  return { docCount, statuses, surfaces, modules, refFieldNames, subdirCounts };
+  return { docCount, statuses, surfaces, modules, refFieldNames, subdirCounts, untaggedCount };
 }
 
 // Count .md files (regardless of frontmatter) directly inside a single directory.
@@ -275,9 +317,19 @@ export async function runInit(cwd, config, opts = {}) {
       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`);
+      process.stdout.write(`           Or run: echo '!docs/' >> .gitignore\n`);
     }
   }
 
+  // Bulk-tag hint — when init found pre-existing .md files without
+  // type/status, point at the command that can tag them in one shot. Init's
+  // job here is discovery; the per-file detail lives in `bulk-tag --dry-run`.
+  if (scan?.untaggedCount > 0) {
+    const n = scan.untaggedCount;
+    const noun = n === 1 ? 'file' : 'files';
+    process.stdout.write(`\n  ${yellow('hint')}    ${n} untagged .md ${noun} found — run \`dotmd bulk-tag --dry-run\` to preview tagging.\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
@@ -307,9 +359,30 @@ export async function runInit(cwd, config, opts = {}) {
     }
   }
 
+  // SessionStart hook hint — only when .claude/ exists. Print-only; users with
+  // existing settings.json need to merge by hand because auto-merging hook
+  // arrays would silently mutate user-managed files.
+  if (existsSync(path.join(cwd, '.claude'))) {
+    const sessionStart = detectSessionStartHook(cwd);
+    if (sessionStart.wired) {
+      process.stdout.write(`  ${dim('exists')}  ${sessionStart.file} (SessionStart hook for \`dotmd hud\` already wired)\n`);
+    } else {
+      process.stdout.write(`\n  ${yellow('hint')}    wire \`dotmd hud\` to run at SessionStart — add to .claude/settings.json:\n\n`);
+      process.stdout.write(`            {\n`);
+      process.stdout.write(`              "hooks": {\n`);
+      process.stdout.write(`                "SessionStart": [\n`);
+      process.stdout.write(`                  { "hooks": [{ "type": "command", "command": "dotmd hud" }] }\n`);
+      process.stdout.write(`                ]\n`);
+      process.stdout.write(`              }\n`);
+      process.stdout.write(`            }\n\n`);
+      process.stdout.write(`            If .claude/settings.json already exists, merge into the existing\n`);
+      process.stdout.write(`            \`hooks.SessionStart\` array rather than replacing the file.\n`);
+    }
+  }
+
   process.stdout.write(`\nReady. A few starting points:\n`);
   process.stdout.write(`  dotmd new doc my-doc            # scaffold a reference doc\n`);
   process.stdout.write(`  dotmd new plan my-plan          # scaffold an execution plan\n`);
   process.stdout.write(`  dotmd list                      # see what you've got\n`);
-  process.stdout.write(`  dotmd hud                       # session-start triage (ideal SessionStart hook)\n\n`);
+  process.stdout.write(`  dotmd hud                       # session-start triage\n\n`);
 }

package/src/lifecycle.mjs

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter, replaceFrontmatter } from './frontmatter.mjs';
-import { asString, toRepoPath, die, warn, resolveDocPath, escapeRegex, nowIso } from './util.mjs';
+import { asString, toRepoPath, die, warn, resolveDocPath, resolveRefPath, escapeRegex, nowIso } from './util.mjs';
 import { gitMv, getGitLastModified, getGitLastModifiedBatch } from './git.mjs';
 import { buildIndex, collectDocFiles } from './index.mjs';
 import { renderIndexFile, writeIndex } from './index-file.mjs';
@@ -717,12 +717,17 @@ function updateRefsFromMovedFile(oldPath, newPath, config) {
   let raw = readFileSync(newPath, 'utf8');
   const { frontmatter, body } = extractFrontmatter(raw);
 
-  // Fix frontmatter ref fields (YAML list items like  - ./path.md)
+  // Fix frontmatter ref fields (YAML list items like  - ./path.md).
+  // Resolve doc-relative first, then repo-root-relative — so a ref like
+  // `docs/foo/bar.md` written from any nesting level gets rewritten correctly
+  // when the source moves. Without the repo-root fallback, repo-relative refs
+  // silently skipped rewriting (existsSync on the doubled doc-relative path
+  // returned false).
   let newFm = frontmatter;
   const refRegex = /^(\s+-\s+)(\S+\.md)$/gm;
   newFm = newFm.replace(refRegex, (match, prefix, refPath) => {
-    const absTarget = path.resolve(oldDir, refPath);
-    if (!existsSync(absTarget)) return match;
+    const absTarget = resolveRefPath(refPath, oldDir, config.repoRoot);
+    if (!absTarget) return match;
     const newRelPath = path.relative(newDir, absTarget).split(path.sep).join('/');
     return `${prefix}${newRelPath}`;
   });
@@ -732,8 +737,8 @@ function updateRefsFromMovedFile(oldPath, newPath, config) {
   const linkRegex = /(\[[^\]]*\]\()([^)]+\.md)(\))/g;
   newBody = newBody.replace(linkRegex, (match, pre, href, post) => {
     if (href.startsWith('http')) return match;
-    const absTarget = path.resolve(oldDir, href);
-    if (!existsSync(absTarget)) return match;
+    const absTarget = resolveRefPath(href, oldDir, config.repoRoot);
+    if (!absTarget) return match;
     const newHref = path.relative(newDir, absTarget).split(path.sep).join('/');
     return `${pre}${newHref}${post}`;
   });
@@ -832,3 +837,18 @@ export function updateFrontmatter(filePath, updates) {
 
   writeFileSync(filePath, `---\n${frontmatter}\n---\n${body}`, 'utf8');
 }
+
+// Prepend a fresh `---\n…\n---\n` block to a file that has no frontmatter yet.
+// Sibling to updateFrontmatter() for the bulk-tag flow, which needs to tag
+// pre-existing markdown files that never had a frontmatter block. Delegates
+// to updateFrontmatter when a block already exists so callers can hand it any
+// file without pre-checking — the result is the same shape either way.
+export function writeFrontmatter(filePath, fields) {
+  const raw = readFileSync(filePath, 'utf8');
+  if (raw.startsWith('---\n')) {
+    updateFrontmatter(filePath, fields);
+    return;
+  }
+  const lines = Object.entries(fields).map(([k, v]) => `${k}: ${v}`).join('\n');
+  writeFileSync(filePath, `---\n${lines}\n---\n${raw}`, 'utf8');
+}

package/src/query.mjs

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { capitalize, toSlug, truncate, warn } from './util.mjs';
-import { renderProgressBar } from './render.mjs';
+import { renderProgressBar, formatCurrentState } from './render.mjs';
 import { computeDaysSinceUpdate, computeIsStale } from './validate.mjs';
 import { getGitLastModifiedBatch } from './git.mjs';
 import { extractFrontmatter } from './frontmatter.mjs';
@@ -59,7 +59,8 @@ export function runFocus(index, argv, config) {
   for (const doc of docs) {
     process.stdout.write(`- ${doc.title}\n`);
     process.stdout.write(`  path: ${doc.path}\n`);
-    if (doc.currentState) process.stdout.write(`  state: ${doc.currentState}\n`);
+    const stateValue = formatCurrentState(doc);
+    if (stateValue) process.stdout.write(`  state: ${stateValue}\n`);
     if (doc.nextStep) {
       process.stdout.write(`  next: ${doc.nextStep}\n`);
     }
@@ -259,7 +260,8 @@ 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`);
-    if (doc.currentState) process.stdout.write(`  state: ${doc.currentState}\n`);
+    const stateValue = formatCurrentState(doc);
+    if (stateValue) process.stdout.write(`  state: ${stateValue}\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

@@ -6,6 +6,17 @@ import { summarizeDocBody } from './ai.mjs';
 import { bold, red, yellow, green, dim } from './color.mjs';
 import { findStaleLeases } from './lease.mjs';
 
+// Render `currentState` with an `(auto)` prefix when the value was body-scraped
+// rather than read from frontmatter. Lets a reader see at a glance which docs
+// have an explicit `current_state:` line versus a string inferred from the body
+// — and that overriding it is as simple as adding the field to frontmatter.
+export function formatCurrentState(doc) {
+  if (!doc.currentState) return null;
+  return doc.currentStateOrigin === 'body'
+    ? `(auto) ${doc.currentState}`
+    : doc.currentState;
+}
+
 export function renderCompactList(index, config) {
   const defaultRenderer = (idx) => _renderCompactList(idx, config);
   if (config.hooks.renderCompactList) {
@@ -99,8 +110,9 @@ export function renderVerboseList(index, config) {
 
     lines.push(`${capitalize(status)} (${docs.length})`);
     for (const doc of docs) {
-      const stateLabel = doc.currentState
-        ? `${capitalize(status)}: ${doc.currentState}`
+      const stateValue = formatCurrentState(doc);
+      const stateLabel = stateValue
+        ? `${capitalize(status)}: ${stateValue}`
         : capitalize(status);
       const parts = [`- ${doc.title}`, stateLabel, `(${doc.path})`];
       if (doc.nextStep) {
@@ -120,8 +132,9 @@ export function renderVerboseList(index, config) {
 
     lines.push(`${capitalize(status)} (${docs.length})`);
     for (const doc of docs) {
-      const stateLabel = doc.currentState
-        ? `${capitalize(status)}: ${doc.currentState}`
+      const stateValue = formatCurrentState(doc);
+      const stateLabel = stateValue
+        ? `${capitalize(status)}: ${stateValue}`
         : capitalize(status);
       const parts = [`- ${doc.title}`, stateLabel, `(${doc.path})`];
       if (doc.nextStep) {
@@ -462,7 +475,7 @@ function _formatSnapshot(doc, config) {
   if (isTerminal && !doc.currentState) {
     return capitalize(doc.status);
   }
-  const state = doc.currentState ?? 'No current_state set';
+  const state = formatCurrentState(doc) ?? 'No current_state set';
   if (/^active:|^ready:|^planned:|^scoping:|^blocked:|^archived:/i.test(state)) {
     return state;
   }

package/src/validate.mjs

@@ -106,7 +106,7 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
     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.' });
   }
 
-  if (config.validSurfaces) {
+  if (config.validSurfaces && !config.lifecycle.skipWarningsFor.has(doc.status)) {
     for (const surface of doc.surfaces) {
       if (!config.validSurfaces.has(surface)) {
         doc.warnings.push({ path: doc.path, level: 'warning', message: `Unknown surface \`${surface}\`; expected a known surface taxonomy value.` });
@@ -164,21 +164,28 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
     }
   }
 
-  // Validate reference fields resolve to existing files
+  // Validate reference fields resolve to existing files. Terminal statuses
+  // (archived, deprecated, etc.) document historical state — their refs may
+  // legitimately point at moved/deleted targets and shouldn't gate the
+  // exit code with a hard error.
   const docDir = path.dirname(path.join(config.repoRoot, doc.path));
   const allRefFields = [...(config.referenceFields.bidirectional || []), ...(config.referenceFields.unidirectional || [])];
-  for (const field of allRefFields) {
-    for (const relPath of (doc.refFields[field] || [])) {
-      if (!resolveRefPath(relPath, docDir, config.repoRoot)) {
-        doc.errors.push({ path: doc.path, level: 'error', message: `${field} entry \`${relPath}\` does not resolve to an existing file.` });
+  const skipRefValidation = config.lifecycle.terminalStatuses.has(doc.status)
+    || config.lifecycle.skipWarningsFor.has(doc.status);
+  if (!skipRefValidation) {
+    for (const field of allRefFields) {
+      for (const relPath of (doc.refFields[field] || [])) {
+        if (!resolveRefPath(relPath, docDir, config.repoRoot)) {
+          doc.errors.push({ path: doc.path, level: 'error', message: `${field} entry \`${relPath}\` does not resolve to an existing file.` });
+        }
       }
     }
-  }
 
-  // Validate body links resolve to existing files
-  for (const link of (doc.bodyLinks || [])) {
-    if (!resolveRefPath(link.href, docDir, config.repoRoot)) {
-      doc.warnings.push({ path: doc.path, level: 'warning', message: `body link \`${link.href}\` does not resolve to an existing file.` });
+    // Validate body links resolve to existing files
+    for (const link of (doc.bodyLinks || [])) {
+      if (!resolveRefPath(link.href, docDir, config.repoRoot)) {
+        doc.warnings.push({ path: doc.path, level: 'warning', message: `body link \`${link.href}\` does not resolve to an existing file.` });
+      }
     }
   }
 }
@@ -271,19 +278,24 @@ export function validatePlanShape(doc, body, frontmatter, config) {
     });
   }
 
-  // 3. surface AND surfaces both populated
-  if (frontmatter.surface && Array.isArray(frontmatter.surfaces) && frontmatter.surfaces.length > 0) {
+  // 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) and `surfaces` (array) are set. Pick one — prefer `surfaces` array form.',
+      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) {
+  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) and `modules` (array) are set. Pick one — prefer `modules` array form.',
+      message: `Both \`module\` (singular: \`${frontmatter.module}\`) and \`modules\` (array) are set with different values. Pick one — prefer \`modules\` array form.`,
     });
   }