dotmd-cli 0.32.0 → 0.33.0

package/package.json

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

package/src/claude-commands.mjs

@@ -46,6 +46,22 @@ function generatePlansCommand(config) {
   return lines.join('\n');
 }
 
+function generateBatonCommand() {
+  const lines = [VERSION_MARKER, ''];
+  lines.push('You are wrapping this session. Hand the baton cleanly to the next one.');
+  lines.push('');
+  lines.push('1. **Update the in-flight plan.** Find it via `dotmd plans --status in-session`. Edit its `current_state:` / `next_step:` frontmatter so they reflect where things actually stand. If status should change (shipped → archive, stuck on a human decision → awaiting, etc.), transition with `dotmd status <file> <status>` — or `dotmd archive <file>` if work is done.');
+  lines.push('');
+  lines.push('2. **Save ONE lean handoff prompt.** Run `dotmd new prompt resume-<plan-slug>` with a body of ~10-20 lines: point at the plan file, name the next concrete decision, flag any gotchas. Do NOT recap the plan body (the plan is for that). Do NOT print the handoff into chat for the user to copy-paste — the saved prompt is the handoff.');
+  lines.push('');
+  lines.push('3. **Release the lease.** `dotmd release` (skip if `dotmd archive` already closed out — archive auto-releases).');
+  lines.push('');
+  lines.push('The next session\'s `dotmd hud` (SessionStart hook) surfaces the pending prompt automatically.');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
 function generateDocsCommand(config) {
   const roots = Array.isArray(config.raw?.root) ? config.raw.root : [config.raw?.root ?? 'docs'];
   const rootCount = roots.length;
@@ -118,6 +134,7 @@ export function scaffoldClaudeCommands(cwd, config, opts = {}) {
   const files = [
     { name: 'plans.md', generate: () => generatePlansCommand(config) },
     { name: 'docs.md', generate: () => generateDocsCommand(config) },
+    { name: 'baton.md', generate: () => generateBatonCommand() },
   ];
 
   for (const { name, generate } of files) {
@@ -149,12 +166,24 @@ export function scaffoldClaudeCommands(cwd, config, opts = {}) {
   return results;
 }
 
+// Self-heal: regen any slash-command file whose banner is older than pkg.version.
+// Designed for runHud to call at SessionStart — closes the gap between "user
+// upgraded dotmd" and "slash-command body reflects the new version" without
+// requiring a manual `dotmd doctor`. Returns only the entries that actually
+// changed so the caller can surface a one-line note; an empty array means the
+// hud silent-clean contract is preserved. `skipped` (user-managed, no banner)
+// and `current` entries are filtered out — callers don't care about them.
+export function refreshStaleSlashCommands(config) {
+  const results = scaffoldClaudeCommands(config.repoRoot, config);
+  return results.filter(r => r.action === 'updated');
+}
+
 export function checkClaudeCommands(cwd) {
   const commandsDir = path.join(cwd, '.claude', 'commands');
   if (!existsSync(commandsDir)) return [];
 
   const warnings = [];
-  for (const name of ['plans.md', 'docs.md']) {
+  for (const name of ['plans.md', 'docs.md', 'baton.md']) {
     const filePath = path.join(commandsDir, name);
     const installedVersion = getInstalledVersion(filePath);
     if (installedVersion && installedVersion !== pkg.version) {

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/hud.mjs

@@ -5,6 +5,7 @@ import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { asString, toRepoPath } from './util.mjs';
 import { green, yellow, red, dim } from './color.mjs';
 import { buildIndex } from './index.mjs';
+import { refreshStaleSlashCommands } from './claude-commands.mjs';
 
 const MAX_PREVIEW = 5;
 
@@ -89,6 +90,15 @@ export function runHud(argv, config) {
   const json = argv.includes('--json');
   const hud = buildHud(config);
 
+  // Self-heal stale slash-command files. Wrapped: a broken scaffolder must
+  // never kill the SessionStart hook (would block every session). Skipped in
+  // --json mode to keep the structured shape stable for programmatic callers.
+  let refreshed = [];
+  if (!json) {
+    try { refreshed = refreshStaleSlashCommands(config); }
+    catch { /* swallow — see comment above */ }
+  }
+
   if (json) {
     process.stdout.write(JSON.stringify(hud, null, 2) + '\n');
     return;
@@ -107,6 +117,12 @@ export function runHud(argv, config) {
   if (hud.errors > 0) {
     lines.push(red(`✗ ${hud.errors} validation error${hud.errors === 1 ? '' : 's'}  ${dim('(run: dotmd check)')}`));
   }
+  if (refreshed.length > 0) {
+    const from = refreshed[0].from;
+    const to = refreshed[0].to;
+    const names = refreshed.map(r => r.name).join(', ');
+    lines.push(dim(`↻ slash commands refreshed (v${from} → v${to}): ${names}`));
+  }
 
   if (lines.length === 0) return; // silent when clean
   process.stdout.write(lines.join('\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}`;
   });

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.`,
     });
   }