dotmd-cli 0.70.0 → 0.70.2

package/bin/dotmd.mjs

@@ -200,7 +200,7 @@ Analyze:
   glossary <term> [--list] [--json] Look up domain terms + related docs
 
 Validate & Fix:
-  doctor [--apply]                  Auto-fix everything: refs, lint, dates, index (preview by default)
+  doctor [--apply]                  Auto-fix everything: refs, lint, long fields, dates, index (preview by default)
   self-check                        Project/version skew diagnostic (alias: doctor --project)
   lint [--fix]                      Check and auto-fix frontmatter issues
   fix-refs [--dry-run]              Auto-fix broken reference paths + body links
@@ -218,7 +218,7 @@ Lifecycle:
   ship [patch|minor|major]          Regen + commit + bump in one step (default: patch)
   bulk-tag [files...]               Tag pre-existing untagged .md files
   touch <file>                      Bump updated date
-  touch --git                       Bulk-sync dates from git history
+  touch --git [<file>...]           Sync dates from substantive git history
   rename <old> <new>                Rename doc and update all references
   migrate <field> <old> <new> [f...]Batch update a frontmatter field value (optional file filter)
 
@@ -702,8 +702,9 @@ the command says so instead of printing an empty list.`,
 
   doctor: `dotmd doctor — auto-fix everything in one pass
 
-Runs in sequence: fix broken references, lint --fix, sync dates from
-git, regenerate index, then show remaining issues.
+Runs in sequence: fix broken references, lint --fix, move over-cap
+frontmatter prose into body sections, sync dates from git, regenerate
+the index, then show remaining issues.
 
 Modes:
   (default)              Auto-fix pass — previews by default since 0.37.0
@@ -765,11 +766,12 @@ docs. Fixes are applied by rewriting the frontmatter path.
 Use --dry-run (-n) to preview changes without writing anything.`,
 
   touch: `dotmd touch <file> — bump updated date
-       dotmd touch --git  — bulk-sync dates from git history
+       dotmd touch --git [<file>...]  — sync dates from git history
 
 Without --git, updates a single file's frontmatter updated date to today.
-With --git, scans all docs (or a specific file) and syncs their updated
-date to match the last git commit date, fixing date drift warnings.
+With --git, scans all docs (or the specified files) and syncs their updated
+date to match the last substantive git commit date, fixing date drift warnings.
+Commits that only changed the updated line are ignored so the fix converges.
 
 Use --dry-run (-n) to preview changes without writing anything.`,
 
@@ -1380,6 +1382,12 @@ async function main() {
   let { command, explicitConfig, rootArg, typeArg, dryRun, verbose } = parsed;
   let restArgs = parsed.rest;
 
+  // Tolerate accidentally pasting the command prefix twice, while leaving all
+  // remaining arguments to the normal `use` grammar and path validation.
+  if (command === 'use') {
+    while (restArgs[0] === 'dotmd' && restArgs[1] === 'use') restArgs = restArgs.slice(2);
+  }
+
   // Reconstruct the active global flags for proxy commands (e.g. `watch`) that
   // re-invoke the CLI in a child process and must propagate them through.
   const globalFlagArgs = () => {
@@ -1444,6 +1452,10 @@ async function main() {
   const effectiveDryRun = dryRun || (command === 'doctor' && !doctorSubMode && !doctorExplicitApply);
   const passiveMachineContext = command === 'agent-context'
     || (command === 'context' && args.includes('--json') && args.includes('--compact'));
+  // Git/frontmatter drift is validation work, not index construction. Keep the
+  // bounded history scan on commands that report or repair that drift; ordinary
+  // reads still run schema/reference validation without walking 10k commits.
+  const gitStaleness = command === 'check' || command === 'doctor';
   _suppressObservability = effectiveDryRun || command === 'hud' || passiveMachineContext;
 
   // Per-command help
@@ -1474,7 +1486,7 @@ async function main() {
   _resolvedConfig = config;
   const suppressSideEffects = effectiveDryRun || command === 'hud' || passiveMachineContext;
   Object.defineProperty(config, '_execution', {
-    value: { dryRun, passive: command === 'hud' || passiveMachineContext, suppressSideEffects },
+    value: { dryRun, passive: command === 'hud' || passiveMachineContext, suppressSideEffects, gitStaleness },
     enumerable: false,
   });
   // Unknown names may still be user-defined query presets. Every built-in

package/package.json

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

package/src/check-collapse.mjs

@@ -18,13 +18,13 @@ const CATEGORIES = [
   },
   {
     key: 'singular-module',
-    match: /^`module:` \(singular\) is deprecated/,
+    match: /^`module:` \(singular\) is deprecated.*Run `dotmd lint --fix`/,
     label: 'docs use deprecated singular `module:`',
     fix: 'dotmd lint --fix',
   },
   {
     key: 'singular-surface',
-    match: /^`surface:` \(singular\) is deprecated/,
+    match: /^`surface:` \(singular\) is deprecated.*Run `dotmd lint --fix`/,
     label: 'docs use deprecated singular `surface:`',
     fix: 'dotmd lint --fix',
   },

package/src/commands.mjs

@@ -123,7 +123,7 @@ const definitions = [
     form('tag [files...]', { subcommands: ['tag'], args: positionals(0, Infinity), options: [value('--type'), value('--status'), flag('--json')] }),
   ]),
   command('bulk-tag', mutates('managed source sweep'), 'mutate', [form('[files...]', { args: positionals(0, Infinity), options: [value('--type'), value('--status'), flag('--json')] })]),
-  command('touch', mutates('managed source or managed source sweep'), 'mutate', [form('[file]', { args: positionals(0, 1), options: [flag('--git')] })]),
+  command('touch', mutates('managed source or managed source sweep'), 'mutate', [form('[file...]', { args: positionals(0, Infinity), options: [flag('--git')] })]),
   command('new', mutates('managed document destination; external body input unrestricted'), 'mutate', [form('[type] <name> [body...]', {
     args: positionals(0, Infinity),
     options: [value('--status'), value('--title'), value('--runlist'), flag('--coordination'), flag('--roadmap'), flag('--lite', '--minimal'), flag('--audit', '--findings'), value('--body', '--message'), value('--root'), flag('--show-files'), flag('--list-templates', '--list-types')],

package/src/doctor.mjs

@@ -89,14 +89,17 @@ export function runDoctor(argv, config, opts = {}) {
   process.stdout.write('\n' + bold('2. Fixing frontmatter issues...') + '\n');
   runLint(['--fix'], config, { dryRun });
 
-  // Step 3: Sync dates from git
-  process.stdout.write('\n' + bold('3. Syncing dates from git...') + '\n');
+  // Step 3: Move over-cap status prose into body sections.
+  process.stdout.write('\n' + bold('3. Fixing long frontmatter...') + '\n');
+  runFrontmatterFix(config, { dryRun });
+
+  // Step 4: Sync dates from git
+  process.stdout.write('\n' + bold('4. Syncing dates from git...') + '\n');
   runTouch(['--git'], config, { dryRun });
 
-  // 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');
+  // Step 5: Regenerate index. Heading always prints so numbering remains
+  // contiguous even when `index.path` isn't configured.
+  process.stdout.write('\n' + bold('5. Regenerating index...') + '\n');
   if (!config.indexPath) {
     process.stdout.write('No index path configured (skip).\n');
   } else if (dryRun) {
@@ -106,11 +109,11 @@ export function runDoctor(argv, config, opts = {}) {
     process.stdout.write('Index updated.\n');
   }
 
-  // Step 5: Clean up retired Claude Code command scaffolding. The per-repo
+  // Step 6: Clean up retired Claude Code command scaffolding. The per-repo
   // `.claude/commands/{plans,docs}.md` files are superseded by the dotmd plugin
   // skill; doctor sweeps any leftover banner-stamped (dotmd-generated) files.
-  // Always print the heading so the numbering stays `1,2,3,4,5,6`.
-  process.stdout.write('\n' + bold('5. Claude Code commands:') + '\n');
+  // Always print the heading so the numbering remains contiguous.
+  process.stdout.write('\n' + bold('6. Claude Code commands:') + '\n');
   if (dryRun) {
     const wouldRemove = removeGeneratedSlashCommands(config.repoRoot, { dryRun: true });
     if (wouldRemove.length === 0) {
@@ -131,8 +134,8 @@ export function runDoctor(argv, config, opts = {}) {
     }
   }
 
-  // Step 6: Show remaining check
-  const issueLabel = dryRun ? '6. Remaining issues in current tree (preview fixes above were not applied):' : '6. Remaining issues:';
+  // Step 7: Show remaining check
+  const issueLabel = dryRun ? '7. Remaining issues in current tree (preview fixes above were not applied):' : '7. Remaining issues:';
   process.stdout.write('\n' + bold(issueLabel) + '\n');
   const freshIndex = buildIndex(config);
   process.stdout.write(renderCheck(freshIndex, config));

package/src/frontmatter-fix.mjs

@@ -30,6 +30,10 @@ export function runFrontmatterFix(config, opts = {}) {
     // skip the warning too, so skip them here as well — auto-injecting a
     // `## Current State` into a non-plan doc would be surprising.
     if (docType !== 'plan') continue;
+    const status = asString(parsed.status);
+    if (config.lifecycle.terminalStatuses.has(status)
+      || config.lifecycle.archiveStatuses.has(status)
+      || config.lifecycle.skipWarningsFor.has(status)) continue;
 
     const ops = [];
     for (const { name, cap, target, heading } of FIELDS) {
@@ -129,13 +133,9 @@ export function replaceFrontmatterField(fm, key, newValue) {
       const isBlock = /^[>|][-+]?\s*$/.test(rest);
       i++;
       if (isBlock || rest === '') {
-        // Consume continuation: blank or indented lines until the next
-        // top-level key. The parser uses the same dedent rule (block scalar
-        // ends when indent returns to 0 and the line is non-blank).
-        while (i < lines.length) {
-          if (/^[A-Za-z0-9_-]+:/.test(lines[i])) break;
-          i++;
-        }
+        // Consume only scalar continuation lines. Top-level comments and other
+        // YAML syntax belong to the frontmatter, not to this field.
+        while (i < lines.length && (lines[i].trim() === '' || /^[ \t]/.test(lines[i]))) i++;
       }
       const folded = foldBlockScalar(newValue);
       out.push(`${key}: >`);

package/src/git.mjs

@@ -25,7 +25,7 @@ export function isGitIgnored(absPath, repoRoot) {
 let gitChecked = false;
 function assertSafeGitPaths(paths) {
   for (const filePath of paths) {
-    if (!filePath || path.isAbsolute(filePath) || filePath.split(/[\\/]/).includes('..')) {
+    if (!filePath || /[\0\r\n]/.test(filePath) || path.isAbsolute(filePath) || filePath.split(/[\\/]/).includes('..')) {
       throw new Error(`Unsafe repository-relative Git path: ${filePath}`);
     }
   }
@@ -39,6 +39,10 @@ function ensureGit() {
   gitChecked = true;
 }
 
+function literalGitPathspec(filePath) {
+  return filePath === '.' ? ':(top,literal)' : `:(top,literal)${filePath}`;
+}
+
 export function getGitLastModified(relPath, repoRoot) {
   const result = spawnSync('git', ['log', '-1', '--format=%aI', '--', relPath], {
     cwd: repoRoot,
@@ -61,6 +65,7 @@ export function getGitFirstAdded(relPath, repoRoot) {
 const DEFAULT_GIT_METADATA_MAX_COMMITS = 10_000;
 const DEFAULT_GIT_METADATA_MAX_BUFFER = 10 * 1024 * 1024;
 const DEFAULT_GIT_METADATA_PATH_BATCH = 256;
+const GIT_METADATA_HISTORY_PER_PATH = 16;
 
 function boundedPositiveInteger(value, fallback, name) {
   if (value == null) return fallback;
@@ -73,21 +78,33 @@ function boundedPositiveInteger(value, fallback, name) {
 function unavailableGitHistory(result) {
   if (result.error?.code === 'ENOENT') return true;
   const detail = `${result.stderr ?? ''}\n${result.error?.message ?? ''}`;
-  return /not a git repository|does not have any commits yet|bad revision ['"]?HEAD|ambiguous argument ['"]?HEAD/i.test(detail);
+  return /not a git repository|does not have any commits yet|bad revision|unknown revision|ambiguous argument/i.test(detail);
 }
 
-function parseGitMetadataOutput(stdout, dates, expectedPaths) {
+function parseGitMetadataOutput(stdout, dates, commits, history, expectedPaths) {
   const fields = String(stdout ?? '').split('\0');
   let currentDate = null;
+  let currentCommit = null;
   for (let i = 0; i < fields.length; i++) {
     const field = fields[i];
-    if (field === 'dotmd:git-metadata:commit' && /^\d{4}-\d{2}-\d{2}T/.test(fields[i + 1] ?? '')) {
+    if (field === 'dotmd:git-metadata:commit'
+      && /^[0-9a-f]{40,64}$/i.test(fields[i + 1] ?? '')
+      && /^\d{4}-\d{2}-\d{2}T/.test(fields[i + 2] ?? '')) {
+      currentCommit = fields[++i];
       currentDate = fields[++i];
       continue;
     }
     const filePath = field.startsWith('\n') ? field.slice(1) : field;
-    if (filePath && currentDate && expectedPaths.has(filePath) && !dates.has(filePath)) {
-      dates.set(filePath, currentDate);
+    if (filePath && currentDate && expectedPaths.has(filePath)) {
+      if (!history.has(filePath)) history.set(filePath, []);
+      const entries = history.get(filePath);
+      if (entries.length < GIT_METADATA_HISTORY_PER_PATH && entries.at(-1)?.commit !== currentCommit) {
+        entries.push({ date: currentDate, commit: currentCommit });
+      }
+      if (!dates.has(filePath)) {
+        dates.set(filePath, currentDate);
+        commits.set(filePath, currentCommit);
+      }
     }
   }
 }
@@ -101,36 +118,46 @@ export function getGitLastModifiedBatch(repoRoot, relPaths, options = {}) {
   const maxPathsPerBatch = boundedPositiveInteger(options.maxPathsPerBatch, DEFAULT_GIT_METADATA_PATH_BATCH, 'maxPathsPerBatch');
   const paths = [...new Set(relPaths ?? [])];
   assertSafeGitPaths(paths);
-  if (paths.length === 0) return { dates: new Map(), complete: true, reason: null };
+  if (paths.length === 0) return { dates: new Map(), commits: new Map(), history: new Map(), complete: true, reason: null };
+  // Full-tree callers can supply a small set of configured root pathspecs for
+  // diff extraction. Revision selection still uses the exact requested paths,
+  // so excluded or unrelated documents cannot consume the commit bound.
+  const scanPaths = options.pathspecs?.length ? [...new Set(options.pathspecs)] : paths;
+  assertSafeGitPaths(scanPaths);
+  const expectedPaths = new Set(paths);
+  const revision = options.revision ?? 'HEAD';
 
   const dates = new Map();
+  const commitsByPath = new Map();
+  const history = new Map();
   let reason = null;
-  const revisions = spawnSync('git', ['rev-list', `--max-count=${maxCommits + 1}`, 'HEAD'], {
+  const revisions = spawnSync('git', ['rev-list', '--stdin', `--max-count=${maxCommits + 1}`, revision], {
     cwd: repoRoot,
     encoding: 'utf8',
+    input: `--\n${paths.map(literalGitPathspec).join('\n')}\n`,
     maxBuffer,
   });
   if (revisions.error?.code === 'ENOBUFS') {
     reason = 'output-limit';
   } else if (revisions.error || revisions.status !== 0) {
-    if (unavailableGitHistory(revisions)) return { dates, complete: true, reason: null };
-    return { dates, complete: false, reason: 'git-error' };
+    if (unavailableGitHistory(revisions)) return { dates, commits: commitsByPath, history, complete: true, reason: null };
+    return { dates, commits: commitsByPath, history, complete: false, reason: 'git-error' };
   }
-  const commits = String(revisions.stdout ?? '')
+  const revisionList = String(revisions.stdout ?? '')
     .split('\n')
     .filter(line => /^[0-9a-f]{40,64}$/i.test(line))
     .slice(0, maxCommits);
-  if (commits.length === 0) return { dates, complete: reason === null, reason };
+  if (revisionList.length === 0) return { dates, commits: commitsByPath, history, complete: reason === null, reason };
   if (!reason && String(revisions.stdout ?? '').trim().split('\n').length > maxCommits) {
     reason = 'commit-limit';
   }
 
-  for (let offset = 0; offset < paths.length; offset += maxPathsPerBatch) {
-    const batch = paths.slice(offset, offset + maxPathsPerBatch);
+  for (let offset = 0; offset < scanPaths.length; offset += maxPathsPerBatch) {
+    const batch = scanPaths.slice(offset, offset + maxPathsPerBatch);
     const result = spawnSync('git', [
-      'diff-tree', '--stdin', '--root', '-r', '-z', '--format=%x00dotmd:git-metadata:commit%x00%aI%x00', '--name-only', '--diff-filter=ACDMR', '--', ...batch,
-    ], { cwd: repoRoot, encoding: 'utf8', input: commits.join('\n') + '\n', maxBuffer });
-    parseGitMetadataOutput(result.stdout, dates, new Set(batch));
+      'diff-tree', '--stdin', '--root', '-r', '-z', '--format=%x00dotmd:git-metadata:commit%x00%H%x00%aI%x00', '--name-only', '--diff-filter=ACDMR', '--', ...batch.map(literalGitPathspec),
+    ], { cwd: repoRoot, encoding: 'utf8', input: revisionList.join('\n') + '\n', maxBuffer });
+    parseGitMetadataOutput(result.stdout, dates, commitsByPath, history, expectedPaths);
 
     if (result.error?.code === 'ENOBUFS') {
       reason = 'output-limit';
@@ -139,7 +166,171 @@ export function getGitLastModifiedBatch(repoRoot, relPaths, options = {}) {
     }
   }
 
-  return { dates, complete: reason === null, reason };
+  // Reaching the history window is harmless when every requested tracked path
+  // already received a latest date. Only unresolved tracked paths require
+  // older history; untracked files legitimately have no Git date.
+  if (reason === 'commit-limit') {
+    const missing = paths.filter(filePath => !dates.has(filePath));
+    let unresolvedTracked = false;
+    let trackingCheckFailed = false;
+    for (let offset = 0; offset < missing.length; offset += maxPathsPerBatch) {
+      const batch = missing.slice(offset, offset + maxPathsPerBatch);
+      const result = spawnSync('git', ['ls-files', '-z', '--', ...batch.map(literalGitPathspec)], {
+        cwd: repoRoot, encoding: 'utf8', maxBuffer,
+      });
+      if (result.error || result.status !== 0) {
+        trackingCheckFailed = true;
+        break;
+      }
+      if (String(result.stdout ?? '').split('\0').some(Boolean)) {
+        unresolvedTracked = true;
+        break;
+      }
+    }
+    if (!trackingCheckFailed && !unresolvedTracked) reason = null;
+  }
+
+  return { dates, commits: commitsByPath, history, complete: reason === null, reason };
+}
+
+function parseBatchObjects(stdout, count) {
+  const output = Buffer.isBuffer(stdout) ? stdout : Buffer.from(stdout ?? '');
+  const objects = [];
+  let offset = 0;
+  while (objects.length < count && offset < output.length) {
+    const newline = output.indexOf(0x0a, offset);
+    if (newline < 0) return null;
+    const header = output.subarray(offset, newline).toString('utf8');
+    offset = newline + 1;
+    if (header.endsWith(' missing')) {
+      objects.push(null);
+      continue;
+    }
+    const size = Number(header.match(/\s(\d+)$/)?.[1]);
+    if (!Number.isSafeInteger(size) || size < 0 || offset + size > output.length) return null;
+    objects.push(output.subarray(offset, offset + size).toString('utf8'));
+    offset += size;
+    if (output[offset] === 0x0a) offset++;
+  }
+  return objects.length === count ? objects : null;
+}
+
+function withoutUpdatedLine(raw) {
+  if (raw == null) return null;
+  const eol = raw.startsWith('---\r\n') ? '\r\n' : raw.startsWith('---\n') ? '\n' : null;
+  if (!eol) return null;
+  const marker = `${eol}---${eol}`;
+  const end = raw.indexOf(marker, 3 + eol.length);
+  if (end < 0) return null;
+  const frontmatter = raw.slice(3 + eol.length, end).split(eol);
+  const index = frontmatter.findIndex(line => line.startsWith('updated:'));
+  if (index < 0) return { line: null, content: raw };
+  const [line] = frontmatter.splice(index, 1);
+  return { line, content: `---${eol}${frontmatter.join(eol)}${marker}${raw.slice(end + marker.length)}` };
+}
+
+function updatedOnlyPathsByCommit(repoRoot, byCommit, maxBuffer, maxPathsPerBatch) {
+  const entries = [...byCommit].flatMap(([commit, commitPaths]) => commitPaths.map(filePath => ({ commit, filePath })));
+  const paths = new Set();
+  // Blob contents are much larger than path metadata, so keep each bounded
+  // cat-file response comfortably below the shared output cap.
+  const batchSize = Math.min(maxPathsPerBatch, 32);
+  for (let offset = 0; offset < entries.length; offset += batchSize) {
+    const batch = entries.slice(offset, offset + batchSize);
+    if (batch.some(item => item.filePath.includes('\n'))) return { paths: new Set(), complete: false };
+    const specs = batch.flatMap(item => [`${item.commit}:${item.filePath}`, `${item.commit}^:${item.filePath}`]);
+    const result = spawnSync('git', ['cat-file', '--batch'], {
+      cwd: repoRoot, input: specs.join('\n') + '\n', maxBuffer,
+    });
+    if (result.error || result.status !== 0) {
+      return { paths: new Set(), complete: false };
+    }
+    const objects = parseBatchObjects(result.stdout, specs.length);
+    if (!objects) return { paths: new Set(), complete: false };
+    for (let i = 0; i < batch.length; i++) {
+      const current = withoutUpdatedLine(objects[i * 2]);
+      const parent = withoutUpdatedLine(objects[i * 2 + 1]);
+      if (!current || !parent || current.line === parent.line) continue;
+      if (current.content === parent.content) paths.add(`${batch[i].commit}\0${batch[i].filePath}`);
+    }
+  }
+  return { paths, complete: true };
+}
+
+// Resolve the latest substantive date for paths whose latest commit may only
+// have synchronized the top-level `updated:` line. Callers provide their first
+// bounded history scan so normal paths pay no extra Git cost. Metadata-only
+// paths are grouped by commit, then resolved from the retained history window
+// (with a bounded parent fallback); consecutive sync-only commits are skipped.
+export function getGitLastSubstantiveModifiedBatch(repoRoot, relPaths, initialMetadata, options = {}) {
+  const maxBuffer = boundedPositiveInteger(options.maxBuffer, DEFAULT_GIT_METADATA_MAX_BUFFER, 'maxBuffer');
+  const maxPathsPerBatch = boundedPositiveInteger(options.maxPathsPerBatch, DEFAULT_GIT_METADATA_PATH_BATCH, 'maxPathsPerBatch');
+  const paths = [...new Set(relPaths ?? [])];
+  assertSafeGitPaths(paths);
+  if (paths.length === 0) return { dates: new Map(), commits: new Map(), history: new Map(), complete: true, reason: null };
+
+  const initial = initialMetadata ?? getGitLastModifiedBatch(repoRoot, paths, options);
+  const dates = new Map(initial.dates);
+  const commits = new Map(initial.commits ?? []);
+  const history = new Map(initial.history ?? []);
+  let complete = initial.complete;
+  let reason = initial.reason;
+  const byCommit = new Map();
+  for (const filePath of paths) {
+    const commit = commits.get(filePath);
+    if (!commit) continue;
+    if (!byCommit.has(commit)) byCommit.set(commit, []);
+    byCommit.get(commit).push(filePath);
+  }
+
+  const classification = updatedOnlyPathsByCommit(repoRoot, byCommit, maxBuffer, maxPathsPerBatch);
+  if (!classification.complete) {
+    complete = false;
+    reason = reason ?? 'git-error';
+  }
+
+  for (const [commit, commitPaths] of byCommit) {
+    const metadataOnly = commitPaths.filter(filePath => classification.paths.has(`${commit}\0${filePath}`));
+    if (metadataOnly.length === 0) continue;
+
+    const older = {
+      dates: new Map(), commits: new Map(), history: new Map(),
+      complete: initial.complete, reason: initial.reason,
+    };
+    const unresolved = [];
+    for (const filePath of metadataOnly) {
+      const entries = history.get(filePath) ?? [];
+      const currentIndex = entries.findIndex(entry => entry.commit === commit);
+      const remaining = currentIndex >= 0 ? entries.slice(currentIndex + 1) : [];
+      if (remaining.length === 0) {
+        unresolved.push(filePath);
+        continue;
+      }
+      older.dates.set(filePath, remaining[0].date);
+      older.commits.set(filePath, remaining[0].commit);
+      older.history.set(filePath, remaining);
+    }
+    if (unresolved.length > 0) {
+      older.complete = false;
+      older.reason = older.reason ?? 'commit-limit';
+    }
+    const substantive = getGitLastSubstantiveModifiedBatch(repoRoot, metadataOnly, older, options);
+    complete = complete && substantive.complete;
+    reason = reason ?? substantive.reason;
+    for (const filePath of metadataOnly) {
+      if (substantive.dates.has(filePath)) {
+        dates.set(filePath, substantive.dates.get(filePath));
+        commits.set(filePath, substantive.commits.get(filePath));
+        if (substantive.history.has(filePath)) history.set(filePath, substantive.history.get(filePath));
+      } else {
+        dates.delete(filePath);
+        commits.delete(filePath);
+        history.delete(filePath);
+      }
+    }
+  }
+
+  return { dates, commits, history, complete, reason };
 }
 
 function parseNullPaths(result) {

package/src/index.mjs

@@ -26,6 +26,7 @@ import { checkSkillDrift } from './skill-drift.mjs';
 export function buildIndex(config, opts = {}) {
   const { fast = false, errorsOnly = false, autoHealIndex = false } = opts;
   const invokeHooks = opts.invokeHooks ?? !config._execution?.suppressSideEffects;
+  const gitStaleness = opts.gitStaleness ?? config._execution?.gitStaleness ?? true;
   const skipWarningOnlyChecks = fast || errorsOnly;
   const docs = collectDocFiles(config).map(f => parseDocFile(f, config, { fast }));
   if (!fast) {
@@ -141,8 +142,10 @@ export function buildIndex(config, opts = {}) {
       if (hub) hub.warnings.push(w);
     }
 
-    const gitWarnings = checkGitStaleness(transformedDocs, config, opts.gitMetadataOptions);
-    warnings.push(...gitWarnings);
+    if (gitStaleness) {
+      const gitWarnings = checkGitStaleness(transformedDocs, config, opts.gitMetadataOptions);
+      warnings.push(...gitWarnings);
+    }
 
     const claudeWarnings = checkClaudeCommands(config.repoRoot);
     warnings.push(...claudeWarnings);

package/src/lifecycle.mjs

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter, normalizeEol } from './frontmatter.mjs';
 import { asString, toRepoPath, die, warn, resolveDocPath, escapeRegex, nowIso, suggestCandidates, emitFilesFooter, isArchivedPath, currentSessionId } from './util.mjs';
 import { readJournalEntries } from './journal.mjs';
-import { captureGitIndexGeneration, getGitLastModifiedBatch, isTracked } from './git.mjs';
+import { captureGitIndexGeneration, getGitLastModifiedBatch, getGitLastSubstantiveModifiedBatch, isTracked } from './git.mjs';
 import { buildIndex, collectDocFiles, resolveDocArg } from './index.mjs';
 import { writeRenderedIndex } from './index-file.mjs';
 import { green, dim } from './color.mjs';
@@ -1137,41 +1137,70 @@ export function runTouch(argv, config, opts = {}) {
     if (argv[i].startsWith('-')) continue;
     positional.push(argv[i]);
   }
+  const inputs = positional;
   const input = positional[0];
 
   // --git mode: bulk-sync frontmatter dates from git history
   if (useGit) {
-    const allFiles = input ? [resolveDocArg(input, config)] : collectDocFiles(config);
+    const allFiles = inputs.length > 0
+      ? [...new Set(inputs.map(item => resolveDocArg(item, config)))]
+      : collectDocFiles(config);
     authorizeManagedSweep(allFiles, config, { kind: 'Touch --git source' });
 
-    const prefix = dryRun ? dim('[dry-run] ') : '';
-    let synced = 0;
-    const repoPaths = allFiles.map(filePath => toRepoPath(filePath, config.repoRoot));
-    const gitMetadata = getGitLastModifiedBatch(config.repoRoot, repoPaths, opts.gitMetadataOptions);
-    if (!gitMetadata.complete) {
-      die(`Cannot touch from incomplete Git metadata (${gitMetadata.reason}); no files were changed.`);
-    }
-    const gitDates = gitMetadata.dates;
-
+    const records = [];
     for (const filePath of allFiles) {
-      const repoPath = toRepoPath(filePath, config.repoRoot);
       const raw = readFileSync(filePath, 'utf8');
       const { frontmatter } = extractFrontmatter(raw);
       if (!frontmatter) continue;
-
       const parsed = parseSimpleFrontmatter(frontmatter);
-      const status = asString(parsed.status);
-      if (config.lifecycle.skipStaleFor.has(status)) continue;
+      if (config.lifecycle.skipStaleFor.has(asString(parsed.status))) continue;
+      records.push({
+        filePath,
+        repoPath: toRepoPath(filePath, config.repoRoot),
+        fmUpdated: asString(parsed.updated),
+      });
+    }
 
-      const fmUpdated = asString(parsed.updated);
-      const gitDate = gitDates.get(repoPath) ?? null;
+    const prefix = dryRun ? dim('[dry-run] ') : '';
+    let synced = 0;
+    const repoPaths = records.map(item => item.repoPath);
+    const rootPathspecs = inputs.length > 0 ? null : (config.docsRoots || [config.docsRoot])
+      .map(root => toRepoPath(root, config.repoRoot) || '.');
+    const gitMetadata = getGitLastModifiedBatch(config.repoRoot, repoPaths, {
+      ...(rootPathspecs ? { pathspecs: rootPathspecs } : {}),
+      ...opts.gitMetadataOptions,
+    });
+    if (!gitMetadata.complete) {
+      die(`Cannot touch from incomplete Git metadata (${gitMetadata.reason}); no files were changed.`);
+    }
+    const candidates = [];
+    for (const { filePath, repoPath, fmUpdated } of records) {
+      const gitDate = gitMetadata.dates.get(repoPath) ?? null;
       if (!gitDate) continue;
-
       const gitDay = gitDate.slice(0, 10);
       if (fmUpdated === gitDay) continue;
-
       // Only sync if git is newer than frontmatter (compare date strings)
       if (fmUpdated && fmUpdated >= gitDay) continue;
+      candidates.push({ filePath, repoPath, fmUpdated });
+    }
+
+    const candidatePaths = candidates.map(item => item.repoPath);
+    const substantiveMetadata = getGitLastSubstantiveModifiedBatch(config.repoRoot, candidatePaths, {
+      dates: new Map(candidatePaths.filter(p => gitMetadata.dates.has(p)).map(p => [p, gitMetadata.dates.get(p)])),
+      commits: new Map(candidatePaths.filter(p => gitMetadata.commits?.has(p)).map(p => [p, gitMetadata.commits.get(p)])),
+      history: new Map(candidatePaths.filter(p => gitMetadata.history?.has(p)).map(p => [p, gitMetadata.history.get(p)])),
+      complete: gitMetadata.complete,
+      reason: gitMetadata.reason,
+    }, opts.gitMetadataOptions);
+    if (!substantiveMetadata.complete) {
+      die(`Cannot touch from incomplete Git metadata (${substantiveMetadata.reason}); no files were changed.`);
+    }
+
+    for (const { filePath, repoPath, fmUpdated } of candidates) {
+      const gitDate = substantiveMetadata.dates.get(repoPath) ?? null;
+      if (!gitDate) continue;
+      const gitDay = gitDate.slice(0, 10);
+      if (fmUpdated && fmUpdated >= gitDay) continue;
 
       if (!dryRun) {
         const result = mutateFile(filePath, { repoRoot: config.repoRoot, testHooks: opts.testHooks }, current => {
@@ -1195,6 +1224,7 @@ export function runTouch(argv, config, opts = {}) {
     return;
   }
 
+  if (inputs.length > 1) die('Multiple files require `dotmd touch --git <file...>`.');
   if (!input) { die('Usage: dotmd touch <file>\n       dotmd touch --git          Bulk-sync dates from git history'); }
 
   let filePath = resolveDocArg(input, config);

package/src/lint.mjs

@@ -17,6 +17,55 @@ const KEY_RENAMES = {
   supportsPlans: 'supports_plans',
 };
 
+function frontmatterFieldBlock(frontmatter, field) {
+  const lines = frontmatter.split(/\r?\n/);
+  const fieldRe = new RegExp(`^${escapeRegex(field)}:`);
+  const start = lines.findIndex(line => fieldRe.test(line));
+  if (start < 0) return null;
+  let end = start + 1;
+  while (end < lines.length) {
+    if (/^[ \t]/.test(lines[end]) || lines[end].trim() === '') {
+      end++;
+      continue;
+    }
+    if (lines[end].trimStart().startsWith('#')) {
+      let next = end + 1;
+      while (next < lines.length && (lines[next].trim() === '' || lines[next].trimStart().startsWith('#'))) next++;
+      if (next < lines.length && /^[ \t]/.test(lines[next])) {
+        end++;
+        continue;
+      }
+    }
+    break;
+  }
+  return { lines, start, end };
+}
+
+function replaceFrontmatterFieldBlock(frontmatter, field, replacement = '') {
+  const block = frontmatterFieldBlock(frontmatter, field);
+  if (!block) return frontmatter;
+  const { lines, start, end } = block;
+  lines.splice(start, end - start, ...(replacement ? replacement.split('\n') : []));
+  return lines.join('\n');
+}
+
+function frontmatterFieldComments(frontmatter, field) {
+  const block = frontmatterFieldBlock(frontmatter, field);
+  if (!block) return [];
+  return block.lines
+    .slice(block.start + 1, block.end)
+    .map(line => line.trim())
+    .filter(line => line.startsWith('#'));
+}
+
+function isAutoFixableString(value) {
+  return typeof value === 'string' && !/(^|\s)#/.test(value);
+}
+
+function formatYamlScalar(value) {
+  return /^[A-Za-z0-9_./-]+$/.test(value) ? value : JSON.stringify(value);
+}
+
 export function runLint(argv, config, opts = {}) {
   const { dryRun } = opts;
   const fix = argv.includes('--fix');
@@ -30,6 +79,7 @@ export function runLint(argv, config, opts = {}) {
     const parsed = parseSimpleFrontmatter(frontmatter);
     const repoPath = toRepoPath(filePath, config.repoRoot);
     const fixes = [];
+    const skipWarnings = config.lifecycle.skipWarningsFor.has(asString(parsed.status));
 
     // Missing type (fixable — infer from root: plans → 'plan', else 'doc')
     if (!asString(parsed.type)) {
@@ -46,7 +96,7 @@ export function runLint(argv, config, opts = {}) {
     }
 
     // Missing updated
-    if (!asString(parsed.updated) && asString(parsed.status) && !config.lifecycle.skipWarningsFor.has(asString(parsed.status))) {
+    if (!asString(parsed.updated) && asString(parsed.status) && !skipWarnings) {
       const today = new Date().toISOString().slice(0, 10);
       fixes.push({ field: 'updated', oldValue: null, newValue: today, type: 'add' });
     }
@@ -72,26 +122,31 @@ export function runLint(argv, config, opts = {}) {
     // 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 rawVal = parsed[singular];
-      const val = asString(rawVal);
-      if (val) {
-        // Inline value (`surface: foo`) → migrate into the plural array.
-        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' });
-      } else if (singular in parsed && (!Array.isArray(rawVal) || rawVal.length === 0)) {
-        // Empty deprecated key (`surface:` with nothing after it, which the
-        // parser yields as `[]`) — usually sitting right above a populated
-        // `surfaces:`. There's no value to migrate; the deprecation warning
-        // just wants the dead line gone. `validate` treats the empty `[]` as
-        // present (so it warns), while the old `asString` gate here saw it as
-        // absent and skipped — the exact no-op reported in issue #17. Emit a
-        // drop fix so `lint --fix` does what the warning advertises. A
-        // populated block-form singular (rawVal.length > 0) is left untouched:
-        // too rare to risk mis-editing.
-        fixes.push({ field: singular, pluralKey: plural, type: 'drop-singular' });
+    if (!skipWarnings) {
+      for (const { singular, plural } of [{ singular: 'module', plural: 'modules' }, { singular: 'surface', plural: 'surfaces' }]) {
+        const rawVal = parsed[singular];
+        const rawPluralVal = parsed[plural];
+        const val = asString(rawVal);
+        const scalarValue = val && isAutoFixableString(val) ? val : null;
+        const blockValues = Array.isArray(rawVal) && rawVal.every(isAutoFixableString)
+          ? rawVal.map(item => item.trim()).filter(Boolean)
+          : [];
+        const pluralAutoFixable = rawPluralVal === undefined
+          || isAutoFixableString(rawPluralVal)
+          || (Array.isArray(rawPluralVal) && rawPluralVal.every(isAutoFixableString));
+        if (pluralAutoFixable && (scalarValue || blockValues.length > 0)) {
+          const values = blockValues.length > 0
+            ? blockValues
+            : scalarValue.includes(',')
+              ? scalarValue.split(',').map(s => s.trim()).filter(Boolean)
+              : [scalarValue];
+          fixes.push({ field: singular, oldValue: scalarValue || blockValues.join(', '), newValue: values, pluralKey: plural, type: 'singular-to-plural' });
+        } else if (pluralAutoFixable && singular in parsed && (
+          (typeof rawVal === 'string' && !rawVal.trim())
+          || (Array.isArray(rawVal) && rawVal.every(item => typeof item === 'string' && !item.trim()))
+        )) {
+          fixes.push({ field: singular, pluralKey: plural, type: 'drop-singular' });
+        }
       }
     }
 
@@ -113,27 +168,31 @@ export function runLint(argv, config, opts = {}) {
     }
   }
 
-  // Also get non-fixable issues from index, excluding issues we can already fix
-  const index = buildIndex(config);
-  const fixablePaths = new Set(fixable.map(f => f.repoPath));
-  // Singular-key deprecation warnings whose fix `lint --fix` will actually make.
-  // Without this, those warnings landed in BOTH the "fixable" preview and the
-  // "non-fixable" list, so the header claimed "N non-fixable" while every line
-  // told you to run `lint --fix` (issue #17, item 8).
-  const fixableSingularKeys = new Set();
-  for (const { repoPath, fixes } of fixable) {
-    for (const f of fixes) {
-      if (f.type === 'singular-to-plural' || f.type === 'drop-singular') {
-        fixableSingularKeys.add(`${repoPath}::${f.field}`);
+  let nonFixable = [];
+  if (!fix) {
+    // Report-only mode also gets non-fixable issues from the index. Fix mode
+    // does not render these and must not pay for a full validation/Git scan.
+    const index = buildIndex(config);
+    const fixablePaths = new Set(fixable.map(f => f.repoPath));
+    // Singular-key deprecation warnings whose fix `lint --fix` will actually make.
+    // Without this, those warnings landed in BOTH the "fixable" preview and the
+    // "non-fixable" list, so the header claimed "N non-fixable" while every line
+    // told you to run `lint --fix` (issue #17, item 8).
+    const fixableSingularKeys = new Set();
+    for (const { repoPath, fixes } of fixable) {
+      for (const f of fixes) {
+        if (f.type === 'singular-to-plural' || f.type === 'drop-singular') {
+          fixableSingularKeys.add(`${repoPath}::${f.field}`);
+        }
       }
     }
+    nonFixable = [...index.errors, ...index.warnings].filter(issue => {
+      if (issue.message.includes('Missing frontmatter `status`') && fixablePaths.has(issue.path)) return false;
+      const dep = issue.message.match(/^`(module|surface):` \(singular\) is deprecated/);
+      if (dep && fixableSingularKeys.has(`${issue.path}::${dep[1]}`)) return false;
+      return true;
+    });
   }
-  const nonFixable = [...index.errors, ...index.warnings].filter(issue => {
-    if (issue.message.includes('Missing frontmatter `status`') && fixablePaths.has(issue.path)) return false;
-    const dep = issue.message.match(/^`(module|surface):` \(singular\) is deprecated/);
-    if (dep && fixableSingularKeys.has(`${issue.path}::${dep[1]}`)) return false;
-    return true;
-  });
 
   if (!fix) {
     // Report mode
@@ -225,22 +284,25 @@ export function runLint(argv, config, opts = {}) {
       }
 
       // Apply singular-to-plural fixes (module/surface → modules/surfaces array).
-      // Removes the singular key line; merges its value(s) into the plural array,
+      // Removes the singular key block; 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);
-        let newFm = fm.replace(new RegExp(`^${escapeRegex(sa.field)}:.*$`, 'm'), '').replace(/\n{2,}/g, '\n');
-        const pluralLineRe = new RegExp(`^${escapeRegex(sa.pluralKey)}:[ \\t]*$`, 'm');
-        if (pluralLineRe.test(newFm)) {
-          for (const val of sa.newValue) {
-            const hasVal = new RegExp(`^[ \\t]*-[ \\t]+${escapeRegex(val)}[ \\t]*$`, 'm').test(newFm);
-            if (!hasVal) {
-              newFm = newFm.replace(pluralLineRe, `${sa.pluralKey}:\n  - ${val}`);
-            }
-          }
+        const parsedFm = parseSimpleFrontmatter(fm);
+        const pluralValue = parsedFm[sa.pluralKey];
+        const existing = Array.isArray(pluralValue)
+          ? pluralValue.filter(value => typeof value === 'string' && value.trim())
+          : asString(pluralValue) ? [asString(pluralValue)] : [];
+        const merged = [...new Set([...sa.newValue, ...existing])];
+        const comments = [...frontmatterFieldComments(fm, sa.field), ...frontmatterFieldComments(fm, sa.pluralKey)];
+        let newFm = replaceFrontmatterFieldBlock(fm, sa.field);
+        const pluralLines = [sa.pluralKey + ':', ...comments.map(comment => `  ${comment}`), ...merged.map(v => `  - ${formatYamlScalar(v)}`)];
+        const pluralBlock = pluralLines.join('\n');
+        if (Object.prototype.hasOwnProperty.call(parsedFm, sa.pluralKey)) {
+          newFm = replaceFrontmatterFieldBlock(newFm, sa.pluralKey, pluralBlock);
         } else {
-          newFm += `\n${sa.pluralKey}:\n${sa.newValue.map(v => `  - ${v}`).join('\n')}`;
+          newFm = `${newFm.trim()}\n${pluralBlock}`;
         }
         raw = replaceFrontmatter(raw, newFm.trim());
         writeFileSync(filePath, raw, 'utf8');
@@ -252,9 +314,8 @@ export function runLint(argv, config, opts = {}) {
       for (const ds of dropSingular) {
         let raw = readFileSync(filePath, 'utf8');
         const { frontmatter: fm } = extractFrontmatter(raw);
-        const newFm = fm
-          .replace(new RegExp(`^${escapeRegex(ds.field)}:[ \\t]*$`, 'm'), '')
-          .replace(/\n{2,}/g, '\n');
+        const comments = frontmatterFieldComments(fm, ds.field);
+        const newFm = replaceFrontmatterFieldBlock(fm, ds.field, comments.join('\n'));
         raw = replaceFrontmatter(raw, newFm.trim());
         writeFileSync(filePath, raw, 'utf8');
       }

package/src/render.mjs

@@ -422,7 +422,8 @@ export function classifyIssueAction(issue) {
   if (/Missing frontmatter `updated`/.test(message) || /frontmatter `updated: .*` is behind git history/.test(message)) {
     return { action: 'dotmd touch --git', fixable: true, label: 'dates' };
   }
-  if (/`(?:module|surface):` \(singular\) is deprecated/.test(message) || /camelCase|nextStep|currentState|auditLevel/.test(message)) {
+  if ((/`(?:module|surface):` \(singular\) is deprecated/.test(message) && /Run `dotmd lint --fix`/.test(message))
+    || /camelCase|nextStep|currentState|auditLevel/.test(message)) {
     return { action: 'dotmd lint --fix', fixable: true, label: 'frontmatter migrations' };
   }
   if (/Unknown surface/.test(message)) {
@@ -456,8 +457,9 @@ export function renderManualFixes(index) {
   for (const issue of issues) {
     const item = classifyIssueAction(issue);
     const key = `${item.fixable ? 'fixable' : 'manual'}:${item.action}`;
-    if (!groups.has(key)) groups.set(key, { ...item, paths: new Set() });
+    if (!groups.has(key)) groups.set(key, { ...item, paths: new Set(), reasons: new Set() });
     groups.get(key).paths.add(issue.path);
+    groups.get(key).reasons.add(issue.message);
   }
   if (groups.size === 0) return '';
 
@@ -478,7 +480,9 @@ export function renderManualFixes(index) {
     lines.push('Manual fixes remaining');
     for (const group of manual) {
       const count = group.paths.size;
-      lines.push(`- ${group.action} (${count} ${count === 1 ? 'file' : 'files'}: ${[...group.paths].slice(0, 3).join(', ')}${count > 3 ? ', ...' : ''})`);
+      const reasons = [...group.reasons];
+      const reason = reasons.slice(0, 2).join('; ') + (reasons.length > 2 ? '; ...' : '');
+      lines.push(`- ${group.action}: ${reason} (${count} ${count === 1 ? 'file' : 'files'}: ${[...group.paths].slice(0, 3).join(', ')}${count > 3 ? ', ...' : ''})`);
     }
     lines.push('');
   }

package/src/validate.mjs

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import { asString, resolveRefPath, suggestCandidates } from './util.mjs';
-import { getGitLastModified, getGitLastModifiedBatch } from './git.mjs';
+import { getGitLastModified, getGitLastModifiedBatch, getGitLastSubstantiveModifiedBatch } from './git.mjs';
 import { toRepoPath } from './util.mjs';
 
 const NOW = new Date();
@@ -156,17 +156,27 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
   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] : [];
+      if (!Object.prototype.hasOwnProperty.call(frontmatter, singular)) continue;
+      const rawPluralValue = frontmatter[plural];
+      const pluralValue = Array.isArray(rawPluralValue)
+        ? rawPluralValue
+        : rawPluralValue === undefined ? [] : [rawPluralValue];
+      const singularValues = Array.isArray(singularValue) ? singularValue : [singularValue];
       const merged = [];
-      for (const v of [singularValue, ...pluralValue]) {
+      for (const v of [...singularValues, ...pluralValue]) {
         if (typeof v === 'string' && v && !merged.includes(v)) merged.push(v);
       }
-      const target = `${plural}: [${merged.map(v => `"${v}"`).join(', ')}]`;
+      const target = `${plural}: [${merged.map(v => JSON.stringify(v)).join(', ')}]`;
+      const autoFixableString = value => typeof value === 'string' && !/(^|\s)#/.test(value);
+      const autoFixable = singularValues.every(autoFixableString)
+        && pluralValue.every(autoFixableString);
+      const guidance = autoFixable
+        ? `use \`${target}\`. Run \`dotmd lint --fix\` to migrate.`
+        : `use a \`${plural}:\` YAML list. Remove the deprecated \`${singular}:\` block manually and preserve all of its values.`;
       doc.warnings.push({
         path: doc.path,
         level: 'warning',
-        message: `\`${singular}:\` (singular) is deprecated — use \`${target}\`. Run \`dotmd lint --fix\` to migrate.`,
+        message: `\`${singular}:\` (singular) is deprecated — ${guidance}`,
       });
     }
   }
@@ -521,15 +531,33 @@ export function checkRoadmapHubExecutionMode(docs, config) {
 
 export function checkGitStaleness(docs, config, options = {}) {
   const warnings = [];
-  const gitMetadata = getGitLastModifiedBatch(config.repoRoot, docs.map(doc => doc.path), options);
-  const gitDates = gitMetadata.dates;
-  for (const doc of docs) {
-    if (config.lifecycle.skipStaleFor.has(doc.status)) continue;
-    if (!doc.updated) continue;
+  const eligibleDocs = docs.filter(doc => !config.lifecycle.skipStaleFor.has(doc.status) && doc.updated);
+  const pathspecs = (config.docsRoots || [config.docsRoot])
+    .map(root => toRepoPath(root, config.repoRoot) || '.');
+  const gitMetadata = getGitLastModifiedBatch(
+    config.repoRoot,
+    eligibleDocs.map(doc => doc.path),
+    { pathspecs, ...options },
+  );
+  const driftCandidates = eligibleDocs.filter(doc => {
+    const gitDate = gitMetadata.dates.get(doc.path) ?? null;
+    return Boolean(gitDate && gitDate.slice(0, 10) > doc.updated.slice(0, 10));
+  });
+  const candidatePaths = driftCandidates.map(doc => doc.path);
+  const candidateMetadata = {
+    dates: new Map(candidatePaths.filter(p => gitMetadata.dates.has(p)).map(p => [p, gitMetadata.dates.get(p)])),
+    commits: new Map(candidatePaths.filter(p => gitMetadata.commits?.has(p)).map(p => [p, gitMetadata.commits.get(p)])),
+    history: new Map(candidatePaths.filter(p => gitMetadata.history?.has(p)).map(p => [p, gitMetadata.history.get(p)])),
+    complete: gitMetadata.complete,
+    reason: gitMetadata.reason,
+  };
+  const substantiveMetadata = candidatePaths.length > 0
+    ? getGitLastSubstantiveModifiedBatch(config.repoRoot, candidatePaths, candidateMetadata, options)
+    : candidateMetadata;
 
-    const gitDate = gitDates.get(doc.path) ?? null;
+  for (const doc of driftCandidates) {
+    const gitDate = substantiveMetadata.dates.get(doc.path) ?? null;
     if (!gitDate) continue;
-
     const gitDay = gitDate.slice(0, 10);
     const fmDay = doc.updated.slice(0, 10);
 
@@ -541,11 +569,11 @@ export function checkGitStaleness(docs, config, options = {}) {
       });
     }
   }
-  if (!gitMetadata.complete) {
+  if (!substantiveMetadata.complete) {
     warnings.push({
       path: toRepoPath(config.docsRoot, config.repoRoot) || '.',
       level: 'warning',
-      message: `Git metadata is incomplete (${gitMetadata.reason}); staleness checks used known dates only.`,
+      message: `Git metadata is incomplete (${substantiveMetadata.reason}); staleness checks used known dates only.`,
     });
   }
   return warnings;