dotmd-cli 0.20.0 → 0.22.0

package/bin/dotmd.mjs

@@ -341,6 +341,24 @@ Modes:
                          paused / queued-after). Heuristic only — verify
                          before migrating.
   --statuses --json      Machine-readable suggestion shape for tooling.
+  --migrate-template     Plan-template migrator for plans created before
+                         v0.21. Auto-fixes:
+                           - drops singular \`surface:\` when \`surfaces:\`
+                             array is populated (same for \`module:\`/\`modules:\`)
+                           - renames \`## Open questions\` → \`## Open Questions\`,
+                             \`## Out of scope\` / \`## Non-goals\` → \`## Non-Goals\`
+                           - adds \`## Version History\` section if missing,
+                             seeded with the file's \`updated\` timestamp
+                         Skips non-plans. Per-file diff. Doesn't touch
+                         long next_step/current_state or unmarked phase
+                         headings (those need human input).
+  --migrate-template <file>  Migrate just one plan.
+  --migrate-template --include-archived
+                         Also touch plans in the archive directory.
+                         Default skips archived plans (they're closed
+                         history; a "Migrated to v0.21 template" entry
+                         in their Version History would be misleading).
+  --migrate-template --json  Machine-readable result.
 
 Use --dry-run (-n) to preview all changes without writing anything.`,
 

package/package.json

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

@@ -6,6 +6,7 @@ import { renderIndexFile, writeIndex } from './index-file.mjs';
 import { renderCheck } from './render.mjs';
 import { bold, dim, green, yellow } from './color.mjs';
 import { scaffoldClaudeCommands } from './claude-commands.mjs';
+import { runMigrateTemplate } from './migrate-template.mjs';
 
 // Tunable thresholds for `dotmd doctor --statuses` conflation detection.
 // MIN_BUCKET_SIZE: only flag buckets with at least this many docs (small buckets aren't worth nagging).
@@ -41,6 +42,10 @@ export function runDoctor(argv, config, opts = {}) {
     runDoctorStatuses(config, { json: argv.includes('--json') });
     return;
   }
+  if (argv.includes('--migrate-template')) {
+    runMigrateTemplate(argv, config, opts);
+    return;
+  }
 
   const { dryRun } = opts;
   process.stdout.write(bold('dotmd doctor') + '\n\n');

package/src/index.mjs

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { extractFirstHeading, extractSummary, extractStatusSnapshot, extractNextStep, extractChecklistCounts, extractBodyLinks } from './extractors.mjs';
 import { asString, normalizeStringList, normalizeBlockers, mergeUniqueStrings, toRepoPath, warn } from './util.mjs';
-import { validateDoc, checkBidirectionalReferences, checkGitStaleness, computeDaysSinceUpdate, computeIsStale, computeChecklistCompletionRate } from './validate.mjs';
+import { validateDoc, validatePlanShape, checkBidirectionalReferences, checkGitStaleness, computeDaysSinceUpdate, computeIsStale, computeChecklistCompletionRate } from './validate.mjs';
 import { checkIndex } from './index-file.mjs';
 import { checkClaudeCommands } from './claude-commands.mjs';
 
@@ -193,5 +193,6 @@ export function parseDocFile(filePath, config) {
   }
 
   validateDoc(doc, parsedFrontmatter, headingTitle, config);
+  validatePlanShape(doc, body, parsedFrontmatter, config);
   return doc;
 }

package/src/migrate-template.mjs

@@ -0,0 +1,168 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { asString, toRepoPath, nowIso } from './util.mjs';
+import { collectDocFiles } from './index.mjs';
+import { bold, green, yellow, dim } from './color.mjs';
+
+const HEADING_RENAMES = [
+  { from: /^##\s+Open questions\s*$/gm, to: '## Open Questions' },
+  { from: /^##\s+open questions\s*$/gm, to: '## Open Questions' },
+  { from: /^##\s+Out of scope\s*$/gm, to: '## Non-Goals' },
+  { from: /^##\s+out of scope\s*$/gm, to: '## Non-Goals' },
+  { from: /^##\s+Non-goals\s*$/gm, to: '## Non-Goals' },
+];
+
+// Detect "both surface and surfaces are populated" — applies same logic to module/modules.
+// Returns the singular-line text to delete, or null if no fix needed.
+function findRedundantSingular(rawFrontmatter, singularKey, pluralKey, parsed) {
+  const singularVal = asString(parsed[singularKey]);
+  const pluralVal = parsed[pluralKey];
+  const pluralHasValues = Array.isArray(pluralVal) && pluralVal.length > 0;
+  if (!singularVal || !pluralHasValues) return null;
+  // Find the exact line: `<singularKey>: <value>` (single inline, not a block start)
+  const lineRe = new RegExp(`^${singularKey}:\\s*[^\\n]+$`, 'm');
+  const match = rawFrontmatter.match(lineRe);
+  return match ? match[0] : null;
+}
+
+function ensureVersionHistory(body, timestamp) {
+  if (/^##\s+Version History\s*$/m.test(body)) return null;
+  const newSection = `## Version History\n\n- **${timestamp}** Migrated to v0.21 template.\n`;
+  // Insert before ## Closeout if it exists; else append at end.
+  const closeoutMatch = body.match(/^##\s+Closeout\s*$/m);
+  if (closeoutMatch) {
+    const idx = body.indexOf(closeoutMatch[0]);
+    return body.slice(0, idx) + newSection + '\n' + body.slice(idx);
+  }
+  return body.trimEnd() + '\n\n' + newSection;
+}
+
+// Run plan-shape migrations on one file. Pure-ish: returns { changes, newRaw }
+// without writing. Caller handles IO.
+export function migrateOne(raw) {
+  const { frontmatter, body } = extractFrontmatter(raw);
+  if (!frontmatter || !body) return { changes: [], newRaw: raw };
+  const parsed = parseSimpleFrontmatter(frontmatter);
+  if (asString(parsed.type) !== 'plan') return { changes: [], newRaw: raw, skipped: 'not-plan' };
+
+  let newFrontmatter = frontmatter;
+  let newBody = body;
+  const changes = [];
+
+  // 1. Drop redundant singular surface/module when array form is populated.
+  const dropSurface = findRedundantSingular(newFrontmatter, 'surface', 'surfaces', parsed);
+  if (dropSurface) {
+    newFrontmatter = newFrontmatter.replace(new RegExp(`\\n?${dropSurface.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')}\\n?`), '\n').replace(/\n+/g, '\n');
+    changes.push({ kind: 'drop-singular', detail: dropSurface });
+  }
+  const dropModule = findRedundantSingular(newFrontmatter, 'module', 'modules', parsed);
+  if (dropModule) {
+    newFrontmatter = newFrontmatter.replace(new RegExp(`\\n?${dropModule.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')}\\n?`), '\n').replace(/\n+/g, '\n');
+    changes.push({ kind: 'drop-singular', detail: dropModule });
+  }
+
+  // 2. Heading renames in body
+  for (const { from, to } of HEADING_RENAMES) {
+    const matches = [...newBody.matchAll(from)];
+    if (matches.length > 0) {
+      newBody = newBody.replace(from, to);
+      for (const m of matches) {
+        changes.push({ kind: 'rename-heading', detail: `\`${m[0].trim()}\` → \`${to}\`` });
+      }
+    }
+  }
+
+  // 3. Add ## Version History section if missing.
+  // Use the file's `updated` timestamp if present, else nowIso(), so the
+  // seed entry reads truthfully ("when this plan was last touched") rather
+  // than dating itself to the migration moment.
+  const seedTs = asString(parsed.updated) || nowIso();
+  const withVh = ensureVersionHistory(newBody, seedTs);
+  if (withVh !== null) {
+    newBody = withVh;
+    changes.push({ kind: 'add-version-history', detail: `seeded with ${seedTs}` });
+  }
+
+  if (changes.length === 0) return { changes: [], newRaw: raw };
+
+  const newRaw = `---\n${newFrontmatter.trim()}\n---\n${newBody}`;
+  return { changes, newRaw };
+}
+
+function isInArchive(filePath, config) {
+  const archiveDir = config.archiveDir || 'archived';
+  const sep = path.sep;
+  return filePath.includes(`${sep}${archiveDir}${sep}`) || filePath.endsWith(`${sep}${archiveDir}`);
+}
+
+export function runMigrateTemplate(argv, config, opts = {}) {
+  const { dryRun } = opts;
+  const json = argv.includes('--json');
+  const includeArchived = argv.includes('--include-archived');
+  // First positional anywhere in argv (skip 'doctor' subcommand if present at idx 0).
+  const fileArg = argv.find(a => !a.startsWith('-') && a !== 'doctor');
+
+  // Allow targeting one file, else sweep all plans (excluding archived by default).
+  let files;
+  if (fileArg) {
+    const target = fileArg.endsWith('.md') ? fileArg : `${fileArg}.md`;
+    files = collectDocFiles(config).filter(f => f.endsWith(target) || f === target);
+    if (files.length === 0) {
+      process.stderr.write(`File not found: ${fileArg}\n`);
+      process.exitCode = 1;
+      return;
+    }
+  } else {
+    files = collectDocFiles(config);
+    if (!includeArchived) files = files.filter(f => !isInArchive(f, config));
+  }
+
+  const results = [];
+  let totalChanges = 0;
+  let touched = 0;
+
+  for (const filePath of files) {
+    const raw = readFileSync(filePath, 'utf8');
+    const result = migrateOne(raw);
+    if (result.changes.length === 0) continue;
+
+    const repoPath = toRepoPath(filePath, config.repoRoot);
+    results.push({ path: repoPath, changes: result.changes });
+    totalChanges += result.changes.length;
+    touched++;
+
+    if (!dryRun) writeFileSync(filePath, result.newRaw, 'utf8');
+  }
+
+  if (json) {
+    process.stdout.write(JSON.stringify({
+      dryRun: Boolean(dryRun),
+      filesTouched: touched,
+      totalChanges,
+      results,
+    }, null, 2) + '\n');
+    return;
+  }
+
+  if (results.length === 0) {
+    process.stdout.write(green('No template migrations needed.') + '\n');
+    return;
+  }
+
+  const prefix = dryRun ? dim('[dry-run] ') : '';
+  process.stdout.write(bold(`${prefix}${touched} plan${touched === 1 ? '' : 's'} ${dryRun ? 'would be' : 'were'} migrated (${totalChanges} change${totalChanges === 1 ? '' : 's'}):\n\n`));
+
+  for (const r of results) {
+    process.stdout.write(`  ${r.path}\n`);
+    for (const c of r.changes) {
+      process.stdout.write(dim(`    [${c.kind}] ${c.detail}\n`));
+    }
+  }
+
+  if (dryRun) {
+    process.stdout.write(`\nRun ${bold('dotmd doctor --migrate-template')} without --dry-run to apply.\n`);
+  } else {
+    process.stdout.write(`\n${green('Done.')} Re-run ${bold('dotmd check')} to see remaining issues.\n`);
+  }
+}

package/src/validate.mjs

@@ -174,6 +174,91 @@ export function checkGitStaleness(docs, config) {
   return warnings;
 }
 
+// Plan-shape lint: soft warnings on convention drift. Plan-only.
+// Body is the unparsed plan body (everything after the closing `---`).
+export function validatePlanShape(doc, body, frontmatter, config) {
+  if (doc.type !== 'plan') return;
+  // Skip plans in terminal/archive statuses (closed work shouldn't generate noise)
+  if (config.lifecycle.terminalStatuses.has(doc.status) || config.lifecycle.archiveStatuses.has(doc.status)) return;
+  if (config.lifecycle.skipWarningsFor.has(doc.status)) return;
+
+  // 1. next_step length cap (300 chars)
+  const nextStep = typeof frontmatter.next_step === 'string' ? frontmatter.next_step : '';
+  if (nextStep.length > 300) {
+    doc.warnings.push({
+      path: doc.path,
+      level: 'warning',
+      message: `\`next_step\` is ${nextStep.length} chars (cap: 300). Long prose belongs in the body — keep next_step as a 1-2 line pointer.`,
+    });
+  }
+
+  // 2. current_state length cap (500 chars)
+  const currentState = typeof frontmatter.current_state === 'string' ? frontmatter.current_state : '';
+  if (currentState.length > 500) {
+    doc.warnings.push({
+      path: doc.path,
+      level: 'warning',
+      message: `\`current_state\` is ${currentState.length} chars (cap: 500). Long prose belongs in the body.`,
+    });
+  }
+
+  // 3. surface AND surfaces both populated
+  if (frontmatter.surface && Array.isArray(frontmatter.surfaces) && frontmatter.surfaces.length > 0) {
+    doc.warnings.push({
+      path: doc.path,
+      level: 'warning',
+      message: 'Both `surface` (singular) and `surfaces` (array) are set. Pick one — prefer `surfaces` array form.',
+    });
+  }
+  if (frontmatter.module && Array.isArray(frontmatter.modules) && frontmatter.modules.length > 0) {
+    doc.warnings.push({
+      path: doc.path,
+      level: 'warning',
+      message: 'Both `module` (singular) and `modules` (array) are set. Pick one — prefer `modules` array form.',
+    });
+  }
+
+  if (!body) return;
+
+  // 4. Heading drift: case + name variants
+  const headingDrift = [
+    { wrong: /^##\s+Open questions\s*$/m, right: '## Open Questions' },
+    { wrong: /^##\s+(Non-goals|Out of scope|Out of Scope|out of scope)\s*$/m, right: '## Non-Goals' },
+    { wrong: /^##\s+open questions\s*$/m, right: '## Open Questions' },
+  ];
+  for (const { wrong, right } of headingDrift) {
+    const m = body.match(wrong);
+    if (m) {
+      doc.warnings.push({
+        path: doc.path,
+        level: 'warning',
+        message: `Heading drift: \`${m[0].trim()}\` → suggest \`${right}\`.`,
+      });
+    }
+  }
+
+  // 5. Phases section exists but no phase H3 has a status marker
+  const phasesIdx = body.search(/^## Phases\s*$/m);
+  if (phasesIdx >= 0) {
+    // Find the section's body (until next H2 or EOF)
+    const after = body.slice(phasesIdx);
+    const nextH2 = after.slice(8).search(/^## /m);
+    const phasesBody = nextH2 >= 0 ? after.slice(8, 8 + nextH2) : after.slice(8);
+    const phaseHeadings = [...phasesBody.matchAll(/^###\s+(.+?)\s*$/gm)].map(m => m[1]);
+    if (phaseHeadings.length > 0) {
+      const markerRe = /(✅|⏭|🟡|⬜|🚧|☑|✔|◻|☐|⬛|\bshipped\b|\bskip(?:ped)?\b|\bin[-_ ]?(?:progress|flight)\b|\bblocked\b|\btodo\b|\bnot[-_ ]?started\b|\bwip\b|\bdone\b|\bcomplete\b)/i;
+      const unmarked = phaseHeadings.filter(h => !markerRe.test(h));
+      if (unmarked.length > 0) {
+        doc.warnings.push({
+          path: doc.path,
+          level: 'warning',
+          message: `${unmarked.length} of ${phaseHeadings.length} phase heading(s) lack a status marker. Use one of ✅ shipped, ⏭ skipped, 🟡 in-progress, ⬜ todo, 🚧 blocked.`,
+        });
+      }
+    }
+  }
+}
+
 export function computeDaysSinceUpdate(updated) {
   if (!updated) return null;
   const parsed = new Date(updated);