npm - dotmd-cli - Versions diffs - 0.25.0 → 0.27.0 - Mend

dotmd-cli 0.25.0 → 0.27.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/bin/dotmd.mjs CHANGED Viewed

@@ -21,7 +21,8 @@ View & Query:
   focus [status] [--json]           Detailed view for one status group
   query [filters] [--json]          Filtered search (--status, --keyword, --stale, etc.)
   plans                             Live plans (excludes archived; --include-archived for all)
-  prompts                           Pending prompts in docs/prompts/
+  prompts [list|next|use|archive|new]
+                                    Manage saved prompts (default: list pending)
   stale                             Stale docs (preset)
   actionable                        Docs with next steps (preset)
@@ -260,24 +261,29 @@ Shows detailed info for all docs matching the given status (default: active).
 Options:
   --json                 Output as JSON`,
-  hud: `dotmd hud — three-line actionable triage
+  hud: `dotmd hud — actionable triage for session start
-Prints up to three lines, in order:
+Prints up to four lines, in order:
   ▶ You hold N plans: <slugs>       (leases owned by current session)
   ▶ N handoffs queued: <slugs>      (resume-prompt sidecars waiting)
+  ▶ N pending prompts: <slugs>      (saved prompts in docs/prompts/)
   ⚠ N stuck leases >24h             (suggest \`dotmd release --stale\`)
-Silent when all three are empty — designed for SessionStart hooks where
+Silent when all four are empty — designed for SessionStart hooks where
 zero noise is the right default. Distinct from \`dotmd briefing\`, which
 dumps the full plan-status pipeline and per-plan next_step bodies (kilobytes
 on large repos). Use hud for ergonomic session boot; use briefing for
 explicit "give me the full picture."
+The pending-prompts line tells Claude to consume them via
+\`dotmd prompts use <file>\` rather than reading/cat'ing — that atomically
+prints the body and archives the prompt so it cannot be double-consumed.
 Recommended SessionStart hook (in ~/.claude/settings.json):
   "SessionStart": [{ "hooks": [{ "type": "command", "command": "dotmd hud", "timeout": 5 }] }]
 Options:
-  --json                 Output as JSON ({ owned, queued, stale })`,
+  --json                 Output as JSON ({ owned, queued, prompts, stale })`,
   briefing: `dotmd briefing — compact summary for session start
@@ -555,19 +561,36 @@ Examples:
   dotmd plans --group module           # plans grouped by module
   dotmd plans --json                   # JSON output`,
-  prompts: `dotmd prompts — list saved prompts (excludes archived by default)
+  prompts: `dotmd prompts — manage saved prompts (subcommand namespace)
+Prompts are documents with \`type: prompt\`, typically saved under
+docs/prompts/. They seed future Claude sessions; consuming a prompt
+prints its body to stdout and atomically archives it (one-shot).
-Shows documents with type: prompt, typically saved under docs/prompts/.
-Prompts are created with \`dotmd new prompt <name> "<body>"\` and seed
-future Claude sessions via \`claude "$(cat docs/prompts/<name>.md)"\`.
+Subcommands:
+  list                       List pending prompts (default)
+  next                       Consume the oldest pending prompt:
+                             print body to stdout, flip status to archived
+  use <file>                 Consume a specific prompt (same as next, but
+                             targets <file> instead of picking oldest)
+  archive <file>             Archive a prompt without printing its body
+  new <slug> [body]          Create a new prompt (alias for
+                             \`dotmd new prompt <slug> [body]\`)
 Default prompt statuses: pending, claimed, archived.
 Examples:
   dotmd prompts                        # pending prompts (default)
-  dotmd prompts --include-archived     # all prompts including archived
-  dotmd prompts --status claimed       # already-consumed prompts
-  dotmd prompts --json                 # JSON output`,
+  dotmd prompts list --include-archived # all prompts including archived
+  dotmd prompts list --status claimed   # already-consumed prompts
+  dotmd prompts --json                 # JSON output
+  claude "$(dotmd prompts next)"       # consume oldest pending + run claude
+  claude "$(dotmd prompts use docs/prompts/foo.md)"
+  dotmd prompts next --dry-run         # preview without consuming
+  dotmd prompts archive docs/prompts/old.md
+  dotmd prompts new my-prompt "Body text here"`,
   stale: `dotmd stale — list stale documents
@@ -769,19 +792,8 @@ async function main() {
     return;
   }
   if (command === 'prompts') {
-    const { buildIndex } = await import('../src/index.mjs');
-    const { runQuery } = await import('../src/query.mjs');
-    const index = buildIndex(config);
-    const sub = restArgs[0];
-    let defaults;
-    let extras = restArgs;
-    if (sub === 'status') {
-      defaults = ['--type', 'prompt', '--exclude-archived', '--sort', 'status', '--all'];
-      extras = restArgs.slice(1);
-    } else {
-      defaults = ['--type', 'prompt', '--exclude-archived', '--sort', 'updated', '--limit', '10'];
-    }
-    runQuery(index, [...defaults, ...extras], config, { preset: 'prompts' });
+    const { runPrompts } = await import('../src/prompts.mjs');
+    await runPrompts(restArgs, config, { dryRun });
     return;
   }

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.25.0",
+  "version": "0.27.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 CHANGED Viewed

@@ -23,7 +23,9 @@ function generatePlansCommand(config) {
   lines.push('- `dotmd unblocks <file>` — what depends on / is blocked by a plan');
   lines.push('- `dotmd next` — ready plans with next steps (what to promote)');
   lines.push('- `dotmd new plan <name>` — scaffold with full phase structure');
-  lines.push('- `dotmd new prompt <name> "<body>"` — save a resume-prompt to docs/prompts/');
+  lines.push('- `dotmd prompts new <name> "<body>"` — save a resume-prompt to docs/prompts/');
+  lines.push('- `dotmd prompts next` — consume oldest pending prompt (prints body, auto-archives)');
+  lines.push('- `dotmd prompts use <file>` — consume a specific prompt (prints body, auto-archives)');
   lines.push('- `dotmd archive <file>` — archive with auto ref-fixing (both directions)');
   lines.push('- `dotmd bulk archive <files>` — archive multiple at once');
   lines.push('- `dotmd status <file> <status>` — transition status');
@@ -39,6 +41,8 @@ function generatePlansCommand(config) {
   lines.push('If the user asks to change a plan\'s status, use `dotmd status <file> <status>`.');
   lines.push('If the user asks to archive a plan, use `dotmd archive <file>`.');
   lines.push('');
+  lines.push('**Saved prompts (`docs/prompts/*.md`):** if the user references a file under `docs/prompts/` — e.g. "resume via docs/prompts/foo.md", "use this prompt", "load that one" — consume it with `dotmd prompts use <file>` (atomically prints the body and archives the prompt so it cannot be double-consumed). Do NOT `cat` it, read it with the file-reading tool, or copy its body into chat. To pick the oldest pending prompt without naming a file, use `dotmd prompts next`.');
+  lines.push('');
   return lines.join('\n');
 }
@@ -118,7 +122,9 @@ function generateDocsCommand(config) {
   lines.push('Lifecycle:');
   lines.push('- `dotmd new plan <name>` — scaffold new plan');
   lines.push('- `dotmd new doc <name>` — scaffold reference doc');
-  lines.push('- `dotmd new prompt <name> "<body>"` — save a resume-prompt');
+  lines.push('- `dotmd prompts new <name> "<body>"` — save a resume-prompt');
+  lines.push('- `dotmd prompts next` — consume oldest pending prompt (prints body, auto-archives)');
+  lines.push('- `dotmd prompts use <file>` — consume a specific prompt (prints body, auto-archives)');
   lines.push('- `dotmd status <file> <status>` — transition status');
   lines.push('- `dotmd archive <file>` — archive with auto ref-fixing');
   lines.push('- `dotmd bulk archive <files>` — archive multiple at once');
@@ -127,6 +133,8 @@ function generateDocsCommand(config) {
   lines.push('- `dotmd fix-refs` — repair broken references and body links');
   lines.push('- `dotmd rename <old> <new>` — rename doc + update all references');
   lines.push('');
+  lines.push('**Saved prompts (`docs/prompts/*.md`):** if the user references a file under `docs/prompts/` — e.g. "resume via docs/prompts/foo.md", "use this prompt" — consume it with `dotmd prompts use <file>` (prints the body and archives atomically). Do NOT `cat` it or read it with the file-reading tool. To pick the oldest pending prompt without naming a file, use `dotmd prompts next`.');
+  lines.push('');
   return lines.join('\n');
 }

package/src/frontmatter.mjs CHANGED Viewed

@@ -26,15 +26,22 @@ export function replaceFrontmatter(raw, newFrontmatter) {
 // structural issues (e.g. duplicate keys) — caller decides whether to surface
 // them. Default behavior is unchanged: keep first occurrence of a duplicate
 // key, ignore subsequent ones.
+//
+// Supports:
+//   inline scalars         `key: value`
+//   arrays                 `key:\n  - item\n  - item`
+//   folded block scalar    `key: >\n  one line\n  continues`         → "one line continues"
+//   literal block scalar   `key: |\n  one\n  two`                    → "one\ntwo"
+//   chomping indicators    `>-`, `|-` (strip), `>+`, `|+` (keep), default (clip to one trailing \n)
 export function parseSimpleFrontmatter(text, warnings) {
   const data = {};
   const seenDupKeys = new Set();
   let currentArrayKey = null;
-  let lineNum = 0;
+  const lines = text.split('\n');
-  for (const rawLine of text.split('\n')) {
-    lineNum++;
-    const line = rawLine.replace(/\r$/, '');
+  for (let i = 0; i < lines.length; i++) {
+    const lineNum = i + 1;
+    const line = lines[i].replace(/\r$/, '');
     if (!line.trim()) continue;
     const keyMatch = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
@@ -49,11 +56,25 @@ export function parseSimpleFrontmatter(text, warnings) {
         }
         continue;
       }
-      if (!rawValue.trim()) {
+      const trimmedValue = rawValue.trim();
+      // Block scalar marker: > or | with optional chomping indicator (-/+).
+      const blockMatch = trimmedValue.match(/^([>|])([-+])?\s*$/);
+      if (blockMatch) {
+        const [, style, chomp] = blockMatch;
+        const { value, consumed } = collectBlockScalar(lines, i + 1, style, chomp);
+        data[key] = value;
+        i += consumed;
+        currentArrayKey = null;
+        continue;
+      }
+      if (!trimmedValue) {
         data[key] = [];
         currentArrayKey = key;
       } else {
-        data[key] = parseScalar(rawValue.trim());
+        data[key] = parseScalar(trimmedValue);
         currentArrayKey = null;
       }
       continue;
@@ -71,6 +92,83 @@ export function parseSimpleFrontmatter(text, warnings) {
   return data;
 }
+// Reads lines starting at startIdx and collects them as a YAML block scalar
+// body. Stops when a line is encountered that is dedented to (or past) the
+// key's indent level (zero in our frontmatter context). Returns the joined
+// string and the number of lines consumed (for the caller to advance `i`).
+function collectBlockScalar(lines, startIdx, style, chomp) {
+  // Determine content indent from the first non-blank line.
+  let contentIndent = null;
+  const collected = [];
+  let i = startIdx;
+  for (; i < lines.length; i++) {
+    const line = lines[i].replace(/\r$/, '');
+    if (line.trim() === '') {
+      collected.push(''); // preserve as blank for folding/literal rules
+      continue;
+    }
+    const indent = line.match(/^(\s*)/)[1].length;
+    if (contentIndent === null) {
+      // First non-blank content line establishes the indent.
+      // If it's at column 0, that's a sibling key — block was empty.
+      if (indent === 0) break;
+      contentIndent = indent;
+      collected.push(line.slice(contentIndent));
+      continue;
+    }
+    if (indent < contentIndent) {
+      // Dedented past content level — end of block scalar.
+      break;
+    }
+    collected.push(line.slice(contentIndent));
+  }
+  // Strip trailing blank lines we accidentally captured before the dedent
+  // (they belong to the document, not the scalar's chomping window).
+  while (collected.length > 0 && collected[collected.length - 1] === '') {
+    collected.pop();
+  }
+  // Join according to style.
+  let value;
+  if (style === '|') {
+    // Literal: each line preserved as-is, joined with \n.
+    value = collected.join('\n');
+  } else {
+    // Folded: single newline between non-blank lines folds to space;
+    // a blank-line run between content becomes a single \n (paragraph break).
+    value = '';
+    let hasContent = false;
+    let prevWasBlank = false;
+    for (const line of collected) {
+      if (line === '') {
+        if (hasContent && !prevWasBlank) value += '\n';
+        prevWasBlank = true;
+      } else {
+        if (hasContent && !prevWasBlank) value += ' ';
+        value += line;
+        hasContent = true;
+        prevWasBlank = false;
+      }
+    }
+  }
+  // Apply chomping: default = clip (single trailing \n if any content),
+  // '-' = strip (no trailing \n), '+' = keep (preserve all).
+  if (chomp === '-') {
+    value = value.replace(/\n+$/, '');
+  } else if (chomp === '+') {
+    if (!value.endsWith('\n')) value = value + '\n';
+  } else {
+    // Clip: strip multiple trailing newlines down to none for inline content
+    // (matches the practical expectation that `key: >` yields a string without
+    // trailing whitespace artifacts when used inline).
+    value = value.replace(/\n+$/, '');
+  }
+  return { value, consumed: i - startIdx };
+}
 function parseScalar(value) {
   let unquoted = value;
   if (value.length > 1 &&

package/src/hud.mjs CHANGED Viewed

@@ -1,6 +1,9 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { readLeases, findStaleLeases, currentSessionId } from './lease.mjs';
 import { listQueuedHandoffs } from './handoff.mjs';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { asString, toRepoPath } from './util.mjs';
 import { green, yellow, dim } from './color.mjs';
 const MAX_PREVIEW = 5;
@@ -13,14 +16,45 @@ function previewList(items, max = MAX_PREVIEW) {
   return slugs.join(', ') + more;
 }
+function findPendingPrompts(config) {
+  const roots = config.docsRoots || (config.docsRoot ? [config.docsRoot] : []);
+  const archiveDir = config.archiveDir || 'archived';
+  const found = [];
+  for (const root of roots) {
+    const dir = path.join(root, 'prompts');
+    if (!existsSync(dir)) continue;
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const entry of entries) {
+      if (entry.isDirectory()) continue;
+      if (!entry.name.endsWith('.md')) continue;
+      const filePath = path.join(dir, entry.name);
+      // Skip any nested archived/ collisions just in case
+      if (filePath.includes(`/${archiveDir}/`)) continue;
+      let raw;
+      try { raw = readFileSync(filePath, 'utf8'); } catch { continue; }
+      const { frontmatter } = extractFrontmatter(raw);
+      if (!frontmatter) continue;
+      const fm = parseSimpleFrontmatter(frontmatter);
+      if (asString(fm.type) !== 'prompt') continue;
+      if (asString(fm.status) !== 'pending') continue;
+      found.push(toRepoPath(filePath, config.repoRoot));
+    }
+  }
+  return found.sort();
+}
 export function buildHud(config) {
   const session = currentSessionId();
   const leases = readLeases(config);
   const owned = Object.values(leases).filter(l => l.session === session).map(l => l.path);
   const queued = listQueuedHandoffs(config).map(h => h.repoPath);
   const stale = findStaleLeases(config).map(l => l.path);
+  const prompts = findPendingPrompts(config);
-  return { owned, queued, stale };
+  return { owned, queued, stale, prompts };
 }
 export function runHud(argv, config) {
@@ -39,6 +73,9 @@ export function runHud(argv, config) {
   if (hud.queued.length > 0) {
     lines.push(green(`▶ ${hud.queued.length} handoff${hud.queued.length === 1 ? '' : 's'} queued: ${previewList(hud.queued)}  ${dim('(resume: dotmd pickup)')}`));
   }
+  if (hud.prompts.length > 0) {
+    lines.push(green(`▶ ${hud.prompts.length} pending prompt${hud.prompts.length === 1 ? '' : 's'}: ${previewList(hud.prompts)}  ${dim('(consume: `dotmd prompts use <file>` — do not cat/read)')}`));
+  }
   if (hud.stale.length > 0) {
     lines.push(yellow(`⚠ ${hud.stale.length} stuck lease${hud.stale.length === 1 ? '' : 's'} >24h  ${dim('(run: dotmd release --stale)')}`));
   }

package/src/index.mjs CHANGED Viewed

@@ -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, validatePlanShape, checkBidirectionalReferences, checkGitStaleness, computeDaysSinceUpdate, computeIsStale, computeChecklistCompletionRate } from './validate.mjs';
+import { validateDoc, validatePlanShape, validateDocShape, checkBidirectionalReferences, checkGitStaleness, computeDaysSinceUpdate, computeIsStale, computeChecklistCompletionRate } from './validate.mjs';
 import { checkIndex } from './index-file.mjs';
 import { checkClaudeCommands } from './claude-commands.mjs';
@@ -194,5 +194,6 @@ export function parseDocFile(filePath, config) {
   validateDoc(doc, parsedFrontmatter, headingTitle, config);
   validatePlanShape(doc, body, parsedFrontmatter, config);
+  validateDocShape(doc, body, parsedFrontmatter, config);
   return doc;
 }

package/src/lifecycle.mjs CHANGED Viewed

@@ -18,6 +18,7 @@ import {
 } from './lease.mjs';
 import { hasHandoff, consumeHandoff, appendHandoff, handoffPath, listQueuedHandoffs } from './handoff.mjs';
 import { buildCard, renderCard } from './pickup-card.mjs';
+import { walkSections, findSection } from './section.mjs';
 function findFileRoot(filePath, config) {
   const roots = config.docsRoots || [config.docsRoot];
@@ -101,6 +102,7 @@ export async function runStatus(argv, config, opts = {}) {
   }
   updateFrontmatter(filePath, { status: newStatus, updated: today });
+  appendVersionHistory(filePath, `Status: ${oldStatus ?? 'unknown'} → ${newStatus}.`);
   if (isArchiving) {
     mkdirSync(archiveDir, { recursive: true });
@@ -211,6 +213,16 @@ export async function runPickup(argv, config, opts = {}) {
     if (oldStatus !== 'in-session') {
       updateFrontmatter(filePath, { status: 'in-session', updated: today });
     }
+    // VH append per lease outcome:
+    //   acquired   → `Picked up (<old> → in-session).`
+    //   taken-over → `Took over from <session>.`
+    //   reattached → no entry (same-session noise)
+    if (leaseOutcome === 'acquired') {
+      appendVersionHistory(filePath, `Picked up (${oldStatus ?? 'unknown'} → in-session).`);
+    } else if (leaseOutcome === 'taken-over') {
+      const fromSession = result.conflict?.session ?? 'unknown';
+      appendVersionHistory(filePath, `Took over from ${fromSession}.`);
+    }
   }
   let handoffBody = null;
@@ -317,6 +329,7 @@ export async function runUnpickup(argv, config, opts = {}) {
       if (cur === 'in-session') {
         const today = nowIso();
         updateFrontmatter(filePath, { status: newStatus, updated: today });
+        appendVersionHistory(filePath, `Released (in-session → ${newStatus}).`);
       }
       // If frontmatter is no longer in-session (manual flip), leave it alone.
     } catch (err) {
@@ -447,7 +460,7 @@ export async function runFinish(argv, config, opts = {}) {
 }
 export function runArchive(argv, config, opts = {}) {
-  const { dryRun } = opts;
+  const { dryRun, out = process.stdout } = opts;
   const input = argv[0];
   if (!input) { die('Usage: dotmd archive <file>'); }
@@ -472,20 +485,21 @@ export function runArchive(argv, config, opts = {}) {
   if (dryRun) {
     const prefix = dim('[dry-run]');
-    process.stdout.write(`${prefix} Would update frontmatter: status: ${oldStatus} → archived, updated: ${today}\n`);
+    out.write(`${prefix} Would update frontmatter: status: ${oldStatus} → archived, updated: ${today}\n`);
     if (existsSync(targetPath)) { die(`Target already exists: ${toRepoPath(targetPath, config.repoRoot)}`); }
-    process.stdout.write(`${prefix} Would move: ${oldRepoPath} → ${newRepoPath}\n`);
-    if (config.indexPath) process.stdout.write(`${prefix} Would regenerate index\n`);
+    out.write(`${prefix} Would move: ${oldRepoPath} → ${newRepoPath}\n`);
+    if (config.indexPath) out.write(`${prefix} Would regenerate index\n`);
     // Preview reference updates
     const refCount = countRefsToUpdate(filePath, targetPath, config);
     if (refCount > 0) {
-      process.stdout.write(`${prefix} Would update references in ${refCount} file(s)\n`);
+      out.write(`${prefix} Would update references in ${refCount} file(s)\n`);
     }
     return;
   }
   updateFrontmatter(filePath, { status: 'archived', updated: today });
+  appendVersionHistory(filePath, 'Archived.');
   mkdirSync(targetDir, { recursive: true });
   if (existsSync(targetPath)) { die(`Target already exists: ${toRepoPath(targetPath, config.repoRoot)}`); }
@@ -504,10 +518,10 @@ export function runArchive(argv, config, opts = {}) {
     writeIndex(renderIndexFile(index, config), config);
   }
-  process.stdout.write(`${green('Archived')}: ${oldRepoPath} → ${newRepoPath}\n`);
-  if (selfRefsFixed) process.stdout.write('Updated references in archived file.\n');
-  if (updatedRefCount > 0) process.stdout.write(`Updated references in ${updatedRefCount} file(s).\n`);
-  if (config.indexPath) process.stdout.write('Index regenerated.\n');
+  out.write(`${green('Archived')}: ${oldRepoPath} → ${newRepoPath}\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) out.write('Index regenerated.\n');
   try { releaseLease(config, oldRepoPath, { force: true }); } catch (err) { warn(`Could not release lease for ${oldRepoPath}: ${err.message}`); }
@@ -821,6 +835,7 @@ export async function runHandoff(argv, config, opts = {}) {
   if (oldStatus === 'in-session') {
     updateFrontmatter(filePath, { status: targetStatus, updated: today });
   }
+  appendVersionHistory(filePath, `Handoff queued (in-session → ${targetStatus}).`);
   releaseLease(config, repoPath, { force: true });
   if (json) {
@@ -839,6 +854,47 @@ export async function runHandoff(argv, config, opts = {}) {
   try { config.hooks.onUnpickup?.({ path: repoPath, oldStatus: 'in-session', newStatus: targetStatus }); } catch (err) { warn(`Hook 'onUnpickup' threw: ${err.message}`); }
 }
+// Append a one-line dated bullet to the file's `## Version History` section.
+// Newest-first ordering: inserted at the top of the section, right after the
+// heading + blank-line gap. If the section is missing, this is a silent no-op
+// — never auto-creates the section (don't surprise users on old plans/docs).
+export function appendVersionHistory(filePath, entry) {
+  let raw;
+  try { raw = readFileSync(filePath, 'utf8'); } catch { return false; }
+  if (!raw.startsWith('---\n')) return false;
+  const endMarker = raw.indexOf('\n---\n', 4);
+  if (endMarker === -1) return false;
+  const frontmatter = raw.slice(4, endMarker);
+  const body = raw.slice(endMarker + 5);
+  const vh = findSection(walkSections(body), 'Version History');
+  if (!vh) return false;
+  const bullet = `- **${nowIso()}** ${entry}`;
+  const lines = body.split('\n');
+  // vh.lineStart is 1-indexed for the heading line. The line immediately
+  // after the heading is at 0-indexed `vh.lineStart`. Skip leading blanks
+  // to find the first content line (existing bullet or next heading).
+  let insertAt = vh.lineStart;
+  while (insertAt < lines.length && lines[insertAt].trim() === '') {
+    insertAt++;
+  }
+  // If we're inserting just before another heading (next H2), pad with a
+  // blank line after our bullet for readability. Otherwise just splice in.
+  const atSectionBoundary = insertAt >= lines.length || lines[insertAt].startsWith('#');
+  if (atSectionBoundary) {
+    lines.splice(insertAt, 0, bullet, '');
+  } else {
+    lines.splice(insertAt, 0, bullet);
+  }
+  writeFileSync(filePath, `---\n${frontmatter}\n---\n${lines.join('\n')}`, 'utf8');
+  return true;
+}
 export function updateFrontmatter(filePath, updates) {
   const raw = readFileSync(filePath, 'utf8');
   if (!raw.startsWith('---\n')) throw new Error(`${filePath} has no frontmatter block.`);

package/src/prompts.mjs ADDED Viewed

@@ -0,0 +1,135 @@
+import { readFileSync, statSync } from 'node:fs';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { asString, toRepoPath, die, resolveDocPath } from './util.mjs';
+import { buildIndex } from './index.mjs';
+import { runQuery } from './query.mjs';
+import { runArchive } from './lifecycle.mjs';
+import { runNew } from './new.mjs';
+import { green, dim } from './color.mjs';
+const SUBCOMMANDS = new Set(['list', 'next', 'use', 'archive', 'new']);
+export async function runPrompts(argv, config, opts = {}) {
+  const sub = argv[0];
+  if (!sub || !SUBCOMMANDS.has(sub)) {
+    return runPromptsList(argv, config, opts);
+  }
+  const rest = argv.slice(1);
+  switch (sub) {
+    case 'list':   return runPromptsList(rest, config, opts);
+    case 'next':   return runPromptsNext(rest, config, opts);
+    case 'use':    return runPromptsUse(rest, config, opts);
+    case 'archive': return runPromptsArchive(rest, config, opts);
+    case 'new':    return runPromptsNew(rest, config, opts);
+  }
+}
+function runPromptsList(argv, config) {
+  const index = buildIndex(config);
+  const hasStatusFlag = argv.includes('--status');
+  const includeArchived = argv.includes('--include-archived');
+  const sub = argv[0];
+  let defaults;
+  let extras = argv;
+  if (sub === 'status') {
+    defaults = ['--type', 'prompt', '--exclude-archived', '--sort', 'status', '--all'];
+    extras = argv.slice(1);
+  } else if (hasStatusFlag || includeArchived) {
+    defaults = ['--type', 'prompt', '--sort', 'updated', '--limit', '10'];
+  } else {
+    defaults = ['--type', 'prompt', '--exclude-archived', '--sort', 'updated', '--limit', '10'];
+  }
+  runQuery(index, [...defaults, ...extras], config, { preset: 'prompts' });
+}
+function pendingPromptsOldestFirst(config) {
+  const index = buildIndex(config);
+  const prompts = index.docs.filter(d => d.type === 'prompt' && d.status === 'pending');
+  return prompts
+    .map(d => {
+      const abs = resolveDocPath(d.path, config);
+      let mtime = 0;
+      try { mtime = abs ? statSync(abs).mtimeMs : 0; } catch { mtime = 0; }
+      return { doc: d, abs, created: d.created ?? '', mtime };
+    })
+    .sort((a, b) => {
+      if (a.created && b.created && a.created !== b.created) return a.created.localeCompare(b.created);
+      if (a.created && !b.created) return -1;
+      if (!a.created && b.created) return 1;
+      return a.mtime - b.mtime;
+    });
+}
+function runPromptsNext(argv, config, opts = {}) {
+  const queue = pendingPromptsOldestFirst(config);
+  if (queue.length === 0) {
+    die('No pending prompts.');
+  }
+  const head = queue[0];
+  if (!head.abs) die(`Could not resolve path: ${head.doc.path}`);
+  consumePrompt(head.abs, config, opts);
+}
+function runPromptsUse(argv, config, opts = {}) {
+  const input = argv.find(a => !a.startsWith('-'));
+  if (!input) die('Usage: dotmd prompts use <file>');
+  const filePath = resolveDocPath(input, config);
+  if (!filePath) die(`File not found: ${input}`);
+  consumePrompt(filePath, config, opts);
+}
+function consumePrompt(filePath, config, opts) {
+  const { dryRun } = opts;
+  const raw = readFileSync(filePath, 'utf8');
+  const { frontmatter, body } = extractFrontmatter(raw);
+  const parsed = parseSimpleFrontmatter(frontmatter);
+  const docType = asString(parsed.type);
+  const status = asString(parsed.status);
+  const repoPath = toRepoPath(filePath, config.repoRoot);
+  if (docType !== 'prompt') {
+    die(`Not a prompt (type: ${docType ?? 'unknown'}): ${repoPath}`);
+  }
+  if (status === 'archived') {
+    die(`Already consumed: ${repoPath}`);
+  }
+  if (dryRun) {
+    process.stderr.write(`${dim('[dry-run]')} Would emit body and archive: ${repoPath} (${status ?? 'unknown'} → archived)\n`);
+    runArchive([filePath], config, { dryRun: true, out: process.stderr });
+    return;
+  }
+  process.stdout.write(body);
+  if (!body.endsWith('\n')) process.stdout.write('\n');
+  runArchive([filePath], config, { out: process.stderr });
+  process.stderr.write(`${green('✓ Consumed')}: ${repoPath}\n`);
+}
+function runPromptsArchive(argv, config, opts = {}) {
+  const input = argv.find(a => !a.startsWith('-'));
+  if (!input) die('Usage: dotmd prompts archive <file>');
+  const filePath = resolveDocPath(input, config);
+  if (!filePath) die(`File not found: ${input}`);
+  const raw = readFileSync(filePath, 'utf8');
+  const { frontmatter } = extractFrontmatter(raw);
+  const parsed = parseSimpleFrontmatter(frontmatter);
+  if (asString(parsed.type) !== 'prompt') {
+    die(`Not a prompt: ${toRepoPath(filePath, config.repoRoot)}`);
+  }
+  runArchive([filePath], config, opts);
+}
+async function runPromptsNew(argv, config, opts = {}) {
+  if (!argv[0] || argv[0].startsWith('-')) {
+    die('Usage: dotmd prompts new <slug> [body]\n       body: inline text | "-" (stdin) | "@path" (file) | --message "..."');
+  }
+  return runNew(['prompt', ...argv], config, opts);
+}

package/src/validate.mjs CHANGED Viewed

@@ -259,6 +259,31 @@ export function validatePlanShape(doc, body, frontmatter, config) {
   }
 }
+// Doc-shape lint: soft warnings on convention drift. Doc-only.
+// Mirrors validatePlanShape's structure.
+export function validateDocShape(doc, body, frontmatter, config) {
+  if (doc.type !== 'doc') return;
+  if (config.lifecycle.terminalStatuses.has(doc.status) || config.lifecycle.archiveStatuses.has(doc.status)) return;
+  if (config.lifecycle.skipWarningsFor.has(doc.status)) return;
+  if (!body) return;
+  // Heading drift for docs.
+  const headingDrift = [
+    { wrong: /^##\s+Related Documents\s*$/m, right: '## Related Documentation' },
+  ];
+  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}\`.`,
+      });
+    }
+  }
+}
 export function computeDaysSinceUpdate(updated) {
   if (!updated) return null;
   const parsed = new Date(updated);