dotmd-cli 0.39.4 → 0.39.5

package/README.md

@@ -577,6 +577,7 @@ dotmd bulk archive docs/old-*.md -n               # preview
 ```bash
 dotmd pickup docs/plans/my-plan.md       # set in-session + print body
 dotmd archive docs/plans/my-plan.md      # fully shipped: archive + auto-release lease
+dotmd archive docs/plans/my-plan.md --closeout-template   # also inject ## Closeout skeleton
 dotmd release docs/plans/my-plan.md      # need more work: release lease, flip to prior status
 dotmd status docs/plans/my-plan.md partial   # shipped + tail deferred (reference successors in body)
 dotmd status docs/plans/my-plan.md awaiting  # stuck on a human decision

package/bin/dotmd.mjs

@@ -359,6 +359,13 @@ Options:
                          listing every doc/index path the command touched
                          (deduped, sorted, repo-relative). Lets agents do
                          \`git add\` with the exact set instead of guessing.
+  --closeout-template    Inject a \`## Closeout\` skeleton into the plan body
+                         before archiving — bullets for outcomes, key
+                         commits, deferrals. No-op if a \`## Closeout\`
+                         section already exists. Placed just before
+                         \`## Version History\` if present, else at end
+                         of body. Fill it in after archive (the archived
+                         file is still editable).
   --dry-run, -n          Preview changes without writing anything.`,
 
   coverage: `dotmd coverage — metadata coverage report
@@ -524,10 +531,19 @@ Modes:
                          history; a "Migrated to v0.21 template" entry
                          in their Version History would be misleading).
   --migrate-template --json  Machine-readable result.
+  --frontmatter-fix      Auto-fix the long-frontmatter warnings that
+                         \`dotmd check\` flags: \`current_state\` >500 chars
+                         or \`next_step\` >300 chars. Truncates the
+                         frontmatter field at the nearest sentence
+                         boundary under the target (300 / 200) and
+                         appends the remainder to a \`## Current State\`
+                         / \`## Next Step\` body section (created above
+                         the first H2 if absent, appended otherwise).
+                         Plans only; honors --dry-run.
 
 --apply (or --yes) opts into writes for the default auto-fix pass.
-Sub-modes (--statuses, --migrate-*) keep their existing contracts:
-they write by default and honor --dry-run.`,
+Sub-modes (--statuses, --migrate-*, --frontmatter-fix) keep their
+existing contracts: they write by default and honor --dry-run.`,
 
   'fix-refs': `dotmd fix-refs — auto-fix broken reference paths
 
@@ -1065,7 +1081,7 @@ async function main() {
     // auto-fix path — sub-modes (--statuses, --migrate-template,
     // --migrate-prompts) keep their existing "write unless --dry-run"
     // contract because they're explicit one-shots the user opted into.
-    const subMode = args.includes('--statuses') || args.includes('--migrate-template') || args.includes('--migrate-prompts');
+    const subMode = args.includes('--statuses') || args.includes('--migrate-template') || args.includes('--migrate-prompts') || args.includes('--frontmatter-fix');
     const explicitApply = args.includes('--apply') || args.includes('--yes');
     const explicitDryRun = args.includes('--dry-run') || args.includes('-n');
     const doctorDryRun = subMode ? dryRun : (explicitDryRun || !explicitApply);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.39.4",
+  "version": "0.39.5",
   "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

@@ -8,6 +8,7 @@ import { bold, dim, green, yellow } from './color.mjs';
 import { scaffoldClaudeCommands } from './claude-commands.mjs';
 import { runMigrateTemplate } from './migrate-template.mjs';
 import { runMigratePrompts } from './migrate-prompts.mjs';
+import { runFrontmatterFix } from './frontmatter-fix.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).
@@ -51,6 +52,10 @@ export function runDoctor(argv, config, opts = {}) {
     runMigratePrompts(argv, config, opts);
     return;
   }
+  if (argv.includes('--frontmatter-fix')) {
+    runFrontmatterFix(config, opts);
+    return;
+  }
 
   const { dryRun } = opts;
   // 0.37.0 (F4): the mode banner makes it impossible to mistake a preview run

package/src/frontmatter-fix.mjs

@@ -0,0 +1,193 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { asString, toRepoPath, escapeRegex, warn } from './util.mjs';
+import { collectDocFiles } from './index.mjs';
+import { bold, green, dim } from './color.mjs';
+
+// Caps must stay in lockstep with the warnings emitted by validatePlanShape in
+// src/validate.mjs — that's where the user first sees these numbers. Targets
+// are deliberately under the cap so a fix-then-edit cycle doesn't reintroduce
+// the warning on the next few-word touch-up.
+const FIELDS = [
+  { name: 'current_state', cap: 500, target: 300, heading: '## Current State' },
+  { name: 'next_step',     cap: 300, target: 200, heading: '## Next Step' },
+];
+
+export function runFrontmatterFix(config, opts = {}) {
+  const { dryRun, out = process.stdout } = opts;
+  const allFiles = collectDocFiles(config);
+  const results = [];
+
+  for (const filePath of allFiles) {
+    const raw = readFileSync(filePath, 'utf8');
+    const { frontmatter: fm, body } = extractFrontmatter(raw);
+    if (!fm) continue;
+    const parsed = parseSimpleFrontmatter(fm);
+    const docType = asString(parsed.type);
+    // The warnings only fire for type: plan (validatePlanShape). Untyped docs
+    // 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 ops = [];
+    for (const { name, cap, target, heading } of FIELDS) {
+      const value = asString(parsed[name]);
+      if (!value || value.length <= cap) continue;
+      const { head, tail } = splitAtBoundary(value, target);
+      if (!tail) continue;
+      ops.push({ field: name, heading, before: value.length, head, tail });
+    }
+    if (ops.length === 0) continue;
+
+    let newFm = fm;
+    let newBody = body;
+    for (const op of ops) {
+      newFm = replaceFrontmatterField(newFm, op.field, op.head);
+      newBody = insertOrAppendSection(newBody, op.heading, op.tail);
+    }
+
+    if (!dryRun) {
+      writeFileSync(filePath, `---\n${newFm}\n---\n${newBody}`, 'utf8');
+      try { config.hooks.onLint?.({ path: toRepoPath(filePath, config.repoRoot), fixes: ops.map(o => ({ field: o.field, type: 'frontmatter-fix' })) }); } catch (err) { warn(`Hook 'onLint' threw: ${err.message}`); }
+    }
+    results.push({ filePath, repoPath: toRepoPath(filePath, config.repoRoot), ops });
+  }
+
+  const prefix = dryRun ? dim('[dry-run] ') : '';
+  const banner = dryRun ? dim(' [preview — run without --dry-run to write]') : '';
+  out.write(bold('dotmd doctor --frontmatter-fix') + banner + '\n\n');
+
+  if (results.length === 0) {
+    out.write(green('No over-cap fields found.') + '\n');
+    return { results };
+  }
+
+  out.write(`${results.length} file(s) with over-cap fields:\n\n`);
+  for (const r of results) {
+    out.write(`  ${r.repoPath}\n`);
+    for (const op of r.ops) {
+      const moved = op.before - op.head.length;
+      out.write(dim(`    ${prefix}${op.field}: ${op.before} → ${op.head.length} chars (moved ${moved} to \`${op.heading}\`)\n`));
+    }
+  }
+  out.write(`\n${prefix}${green(dryRun ? 'Would fix' : 'Fixed')}: ${results.length} file(s)\n`);
+  return { results };
+}
+
+// Splits at the last sentence-ending punctuation (`.!?` + space/newline/EOS)
+// within `target` chars. If no good sentence boundary lands in the back half of
+// the window, falls back to the last whitespace. If even that fails, a hard
+// cut at `target` — the result still parses; readability just suffers.
+export function splitAtBoundary(value, target) {
+  if (value.length <= target) return { head: value, tail: '' };
+
+  const windowStr = value.slice(0, target);
+  // Sentence boundary: greedy match capturing everything up to the last `.!?`
+  // followed by whitespace or end-of-string inside the window.
+  const sentenceRe = /^[\s\S]*[.!?](?=\s|$)/;
+  const sentenceMatch = windowStr.match(sentenceRe);
+  if (sentenceMatch && sentenceMatch[0].length >= Math.floor(target / 2)) {
+    const splitIdx = sentenceMatch[0].length;
+    return {
+      head: value.slice(0, splitIdx).trim(),
+      tail: value.slice(splitIdx).trim(),
+    };
+  }
+
+  const wsIdx = Math.max(windowStr.lastIndexOf(' '), windowStr.lastIndexOf('\n'));
+  if (wsIdx >= Math.floor(target / 2)) {
+    return {
+      head: value.slice(0, wsIdx).trim(),
+      tail: value.slice(wsIdx + 1).trim(),
+    };
+  }
+
+  return {
+    head: value.slice(0, target).trim(),
+    tail: value.slice(target).trim(),
+  };
+}
+
+// Replace a single frontmatter scalar with a folded block scalar (`key: >\n  …`).
+// Folded form is safe regardless of YAML-special chars in the value (colons,
+// quotes, leading dashes) and matches what `parseSimpleFrontmatter` already
+// reads. Consumes the existing key's continuation block if it was multi-line.
+export function replaceFrontmatterField(fm, key, newValue) {
+  const lines = fm.split('\n');
+  const out = [];
+  let i = 0;
+  let replaced = false;
+
+  while (i < lines.length) {
+    const line = lines[i];
+    const keyRe = new RegExp(`^${escapeRegex(key)}:(.*)$`);
+    const match = !replaced && line.match(keyRe);
+    if (match) {
+      const rest = match[1].trim();
+      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++;
+        }
+      }
+      const folded = foldBlockScalar(newValue);
+      out.push(`${key}: >`);
+      for (const fLine of folded) out.push(`  ${fLine}`);
+      replaced = true;
+      continue;
+    }
+    out.push(line);
+    i++;
+  }
+
+  if (!replaced) {
+    const folded = foldBlockScalar(newValue);
+    out.push(`${key}: >`);
+    for (const fLine of folded) out.push(`  ${fLine}`);
+  }
+
+  return out.join('\n');
+}
+
+// Collapse whitespace into a single line — folded block scalar joins on a
+// single space anyway, so writing one wide line keeps the diff tight and
+// round-trips identically.
+function foldBlockScalar(value) {
+  const single = value.replace(/\s+/g, ' ').trim();
+  return [single];
+}
+
+// Ensure a `## <heading>` section exists in the body and contains `content`.
+// If the section is present (case-insensitive heading match), append the new
+// content to its end. If absent, insert a new section just before the first
+// H2 (so it lands above other content sections) — or append at end if no H2
+// exists.
+export function insertOrAppendSection(body, heading, content) {
+  const headingPattern = new RegExp(`^${escapeRegex(heading)}\\s*$`, 'mi');
+  const existing = body.match(headingPattern);
+  if (existing && existing.index !== undefined) {
+    const startIdx = existing.index + existing[0].length;
+    const after = body.slice(startIdx);
+    const nextHeaderRel = after.search(/\n#{1,2}\s+/);
+    const sectionEnd = nextHeaderRel >= 0 ? startIdx + nextHeaderRel : body.length;
+    const before = body.slice(0, sectionEnd).replace(/\s+$/, '');
+    const rest = body.slice(sectionEnd);
+    return `${before}\n\n${content}\n${rest.startsWith('\n') ? rest : '\n' + rest}`;
+  }
+
+  const firstH2 = body.match(/^##\s+/m);
+  if (firstH2 && firstH2.index !== undefined) {
+    const insertIdx = firstH2.index;
+    const before = body.slice(0, insertIdx).replace(/\s+$/, '');
+    const rest = body.slice(insertIdx);
+    return `${before}\n\n${heading}\n\n${content}\n\n${rest}`;
+  }
+
+  const trimmed = body.replace(/\s+$/, '');
+  return `${trimmed}\n\n${heading}\n\n${content}\n`;
+}

package/src/lifecycle.mjs

@@ -44,24 +44,62 @@ export function regenIndex(config) {
 }
 
 // Pick an archive destination that won't clobber an existing record. If
-// `<dir>/<basename>` is free, returns it unchanged; otherwise appends a UTC
-// timestamp (and a counter on the vanishingly rare same-second collision) so
-// both the prior archive and the current one survive.
+// `<dir>/<basename>` is free, returns it unchanged; otherwise appends a
+// numeric suffix (`-2`, `-3`, …) so the slug → path mapping stays readable
+// across re-archives (issue #10 finding #6). The pre-0.39.5 behavior used a
+// UTC timestamp on collision, which made the second archive's path
+// non-deterministic and harder to cross-reference against the original.
+// Closeout skeleton injected by `dotmd archive --closeout-template`. Loose
+// bullet shape (not sub-headings) matches the freeform prose-and-bullets style
+// of existing in-repo closeouts — agents replace bullets with prose when that
+// flows better. The HTML comment is the agent-facing prompt.
+const CLOSEOUT_SKELETON = `## Closeout
+
+<!-- Fill in below. Replace bullets with prose if that flows better. -->
+- **Outcomes:**
+- **Key commits:**
+- **Deferrals:**
+`;
+
+// Plans where to inject the closeout skeleton without writing anything. Returns:
+//   { action: 'skip' }                          — section already present
+//   { action: 'inject', placement, newBody }    — built body with skeleton inserted
+// Placement: just before `## Version History` (so the closeout reads as work
+// content, not appendix); falls back to end-of-body if VH is absent.
+export function planCloseoutInjection(body) {
+  if (/^##\s+Closeout\s*$/mi.test(body)) {
+    return { action: 'skip' };
+  }
+  const vhMatch = body.match(/^##\s+Version History\s*$/mi);
+  if (vhMatch && vhMatch.index !== undefined) {
+    const before = body.slice(0, vhMatch.index).replace(/\s+$/, '');
+    const rest = body.slice(vhMatch.index);
+    return {
+      action: 'inject',
+      placement: 'before `## Version History`',
+      newBody: `${before}\n\n${CLOSEOUT_SKELETON}\n${rest}`,
+    };
+  }
+  const trimmed = body.replace(/\s+$/, '');
+  return {
+    action: 'inject',
+    placement: 'end of body',
+    newBody: `${trimmed}\n\n${CLOSEOUT_SKELETON}`,
+  };
+}
+
 function uniqueArchiveTarget(targetDir, basename) {
   const base = path.join(targetDir, basename);
   if (!existsSync(base)) return base;
 
   const ext = path.extname(basename);
   const stem = basename.slice(0, -ext.length);
-  const d = new Date();
-  const pad = (n) => String(n).padStart(2, '0');
-  const stamp = `${d.getUTCFullYear()}${pad(d.getUTCMonth() + 1)}${pad(d.getUTCDate())}T${pad(d.getUTCHours())}${pad(d.getUTCMinutes())}${pad(d.getUTCSeconds())}Z`;
 
-  let target = path.join(targetDir, `${stem}-${stamp}${ext}`);
   let n = 2;
+  let target = path.join(targetDir, `${stem}-${n}${ext}`);
   while (existsSync(target)) {
-    target = path.join(targetDir, `${stem}-${stamp}-${n}${ext}`);
     n++;
+    target = path.join(targetDir, `${stem}-${n}${ext}`);
   }
   return target;
 }
@@ -545,7 +583,8 @@ export function runArchive(argv, config, opts = {}) {
   const { dryRun, out = process.stdout } = opts;
   const noIndex = argv.includes('--no-index') || opts.noIndex;
   const showFiles = argv.includes('--show-files') || opts.showFiles;
-  argv = argv.filter(a => a !== '--no-index' && a !== '--show-files');
+  const closeoutTemplate = argv.includes('--closeout-template');
+  argv = argv.filter(a => a !== '--no-index' && a !== '--show-files' && a !== '--closeout-template');
   const input = argv[0];
 
   if (!input) { die('Usage: dotmd archive <file>'); }
@@ -558,9 +597,10 @@ export function runArchive(argv, config, opts = {}) {
   if (relFromRoot.startsWith(config.archiveDir + '/') || relFromRoot.startsWith(config.archiveDir + path.sep)) { die(`Already archived: ${toRepoPath(filePath, config.repoRoot)}`); }
 
   const raw = readFileSync(filePath, 'utf8');
-  const { frontmatter } = extractFrontmatter(raw);
+  const { frontmatter, body } = extractFrontmatter(raw);
   const parsed = parseSimpleFrontmatter(frontmatter);
   const oldStatus = asString(parsed.status) ?? 'unknown';
+  const closeoutAction = closeoutTemplate ? planCloseoutInjection(body) : null;
 
   const today = nowIso();
   const targetDir = path.join(archiveFileRoot, config.archiveDir);
@@ -570,6 +610,11 @@ export function runArchive(argv, config, opts = {}) {
 
   if (dryRun) {
     const prefix = dim('[dry-run]');
+    if (closeoutAction?.action === 'inject') {
+      out.write(`${prefix} Would inject \`## Closeout\` template (${closeoutAction.placement})\n`);
+    } else if (closeoutAction?.action === 'skip') {
+      out.write(`${prefix} \`## Closeout\` section already present — no injection\n`);
+    }
     out.write(`${prefix} Would update frontmatter: status: ${oldStatus} → archived, updated: ${today}\n`);
     out.write(`${prefix} Would move: ${oldRepoPath} → ${newRepoPath}\n`);
     if (config.indexPath && !noIndex) out.write(`${prefix} Would regenerate index\n`);
@@ -593,6 +638,10 @@ export function runArchive(argv, config, opts = {}) {
     return;
   }
 
+  if (closeoutAction?.action === 'inject') {
+    writeFileSync(filePath, `---\n${frontmatter}\n---\n${closeoutAction.newBody}`, 'utf8');
+  }
+
   updateFrontmatter(filePath, { status: 'archived', updated: today });
   appendVersionHistory(filePath, 'Archived.');
 
@@ -610,6 +659,11 @@ export function runArchive(argv, config, opts = {}) {
   if (!noIndex) regenIndex(config);
 
   out.write(`${green('Archived')}: ${oldRepoPath} → ${newRepoPath}\n`);
+  if (closeoutAction?.action === 'inject') {
+    out.write(`Injected \`## Closeout\` template — fill in: outcomes, key commits, deferrals.\n`);
+  } else if (closeoutAction?.action === 'skip') {
+    out.write(dim('(closeout template skipped — `## Closeout` section already present)\n'));
+  }
   if (selfRefsFixed) out.write('Updated references in archived file.\n');
   if (updatedRefCount > 0) out.write(`Updated references in ${updatedRefCount} file(s).\n`);
   if (config.indexPath && !noIndex) out.write('Index regenerated.\n');