dotmd-cli 0.39.3 → 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

@@ -68,6 +68,7 @@ Create & Export:
 Setup:
   init                              Create starter config + docs directory
   statuses [list|add|set|remove|migrate]  Manage per-project status taxonomy
+  help statuses                     Full status vocabulary + unstuck-actions + transitions
   watch [command]                   Re-run a command on file changes
   completions <shell>               Shell completion script (bash, zsh)
   journal [--tail N|--errors|--by-command|--session id|--since iso|--json]
@@ -92,6 +93,90 @@ Options:
 
 Outputs the complete document index as JSON to stdout.`,
 
+  // Help topic accessed via \`dotmd help statuses\` (not a command — see dispatch
+  // below). Single-source-of-truth for the built-in status vocabulary across all
+  // three doc types. User-defined types/statuses live in config; introspect them
+  // with \`dotmd statuses list\`.
+  'help:statuses': `dotmd help statuses — status vocabulary, unstuck-actions, and transitions
+
+Every document has a \`type:\` field; each type has its own valid statuses.
+Status validation is type-aware (type > root > global). To inspect or edit
+the status taxonomy in a specific project, use \`dotmd statuses list\`.
+
+────────────────────────────────────────────────────────────────────
+plan statuses (each maps to a distinct unstuck-action)
+
+  in-session     A Claude session is working on it now.
+                 Don't pick up unless you own it (auto-reattaches) or pass
+                 --takeover. Stale lease cleanup: \`dotmd release --stale\`.
+
+  active         Ready to be picked up.
+                 \`dotmd pickup <file>\` → in-session.
+
+  planned        Queued for future work, not yet ready to execute.
+                 Transition to active when ready to start.
+
+  blocked        External arrival wait — monitor.
+                 Hardware, vendor delivery, third-party rollout. Quiet
+                 (skipStale) — you can't speed it up by nagging.
+
+  partial        Shipped + deferred tail — spawn successor plans.
+                 Plan body should reference the successor plan(s). Quiet.
+
+  paused         Started but stopped mid-work — re-evaluate to resume.
+                 Short stale window (3 days) so resume-decisions don't decay.
+
+  awaiting       Needs human input/decision — chase the answer.
+                 NOT quiet — generates stale pressure so pings aren't forgotten.
+
+  queued-after   Sequenced behind another plan — check predecessor.
+                 Quiet. Can start once the predecessor ships.
+
+  archived       No longer relevant; auto-moved to archive directory.
+
+Canonical transitions:
+  active → in-session              \`dotmd pickup <file>\`
+  in-session → active              \`dotmd release <file>\`
+  in-session → partial             \`dotmd status <file> partial\` (+ release)
+  in-session → awaiting            \`dotmd status <file> awaiting\` (+ release)
+  any → archived                   \`dotmd archive <file>\`
+
+────────────────────────────────────────────────────────────────────
+doc statuses
+
+  draft          Work-in-progress reference doc.
+  active         Living document, kept up-to-date.
+  review         Awaiting peer review.
+  reference      Stable canonical reference (excluded from stale checks).
+  deprecated     Superseded but kept for history.
+  archived       No longer relevant; moved to archive directory.
+
+────────────────────────────────────────────────────────────────────
+prompt statuses
+
+  pending        Ready for the next session to consume.
+                 \`dotmd prompts use <file>\` prints body + archives atomically.
+                 \`dotmd prompts next\` does the same for the oldest pending.
+
+  shelved        Saved but hidden from \`hud\` / \`briefing\` / \`prompts next\`.
+                 Still listed by \`dotmd prompts list\`.
+                 \`dotmd prompts unshelve <file>\` → pending.
+
+  claimed        Legacy intermediate state (atomic use → archived now).
+
+  archived       Consumed prompt; body preserved in archive directory.
+
+────────────────────────────────────────────────────────────────────
+Related commands:
+  dotmd statuses              Inspect/manage per-project status taxonomy
+  dotmd status <f> <new>      Transition a document's status
+  dotmd briefing              See plans grouped by status
+  dotmd plans --status <s>    Filter live plans by status
+  dotmd hud                   Two-line actionable triage (held / prompts / stuck)
+
+Run \`dotmd statuses list --type plan\` to see the full set (including any
+project-specific custom statuses) with their flags.`,
+
   completions: `dotmd completions <bash|zsh> — output shell completion script
 
 Add to your shell config:
@@ -241,6 +326,9 @@ Default plan statuses (each maps to a distinct unstuck-action):
   queued-after   Sequenced behind another plan — check predecessor
   archived       No longer relevant; auto-moved to archive directory
 
+Run \`dotmd help statuses\` for the full vocabulary across all doc types
+(plan, doc, prompt) plus canonical transitions and related commands.
+
 Use --dry-run (-n) to preview changes without writing anything.`,
 
   check: `dotmd check — validate frontmatter and references
@@ -271,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
@@ -436,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
 
@@ -630,8 +734,8 @@ sorted by status. Supports all query flags (--status, --module, --json,
 --sort, --group, etc.).
 
 Default plan statuses: in-session, active, planned, blocked, partial,
-paused, awaiting, queued-after, archived. Run \`dotmd status --help\` for
-the unstuck-action behind each one.
+paused, awaiting, queued-after, archived. Run \`dotmd help statuses\` for
+the unstuck-action behind each one and canonical transitions.
 
 Examples:
   dotmd plans                          # live plans (default)
@@ -671,6 +775,9 @@ Default prompt statuses: pending, shelved, claimed, archived.
 
 Examples:
   dotmd prompts                        # pending prompts (default)
+  dotmd prompts list --verbose         # one row per prompt + target plan ref
+                                       # (from related_plans, parent_plan,
+                                       #  or the first body .md link)
   dotmd prompts list --include-archived # all prompts including archived
   dotmd prompts list --status claimed   # already-consumed prompts
   dotmd prompts --json                 # JSON output
@@ -825,6 +932,14 @@ async function main() {
   }
 
   if (command === 'help' || command === '--help' || command === '-h') {
+    const topic = args[1];
+    if (topic) {
+      const key = `help:${topic}`;
+      if (HELP[key]) { process.stdout.write(`${HELP[key]}\n`); return; }
+      if (HELP[topic]) { process.stdout.write(`${HELP[topic]}\n`); return; }
+      process.stderr.write(`Unknown help topic: ${topic}\n\nAvailable topics: statuses\nPer-command help: dotmd <cmd> --help\n`);
+      process.exit(1);
+    }
     process.stdout.write(`${HELP._main}\n`);
     return;
   }
@@ -927,7 +1042,7 @@ async function main() {
   }
   if (command === 'prompts') {
     const { runPrompts } = await import('../src/prompts.mjs');
-    await runPrompts(restArgs, config, { dryRun });
+    await runPrompts(restArgs, config, { dryRun, verbose });
     return;
   }
 
@@ -966,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.3",
+  "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;
 }
@@ -246,7 +284,15 @@ export async function runPickup(argv, config, opts = {}) {
   }
 
   const pickupable = new Set(['active', 'planned', 'in-session']);
-  if (oldStatus && !pickupable.has(oldStatus)) die(`Cannot pick up a plan with status '${oldStatus}'. Must be active or planned.\n  ${repoPath}`);
+  if (oldStatus && !pickupable.has(oldStatus)) {
+    die(
+      `Cannot pick up a plan with status '${oldStatus}'. Must be active or planned.\n` +
+      `  ${repoPath}\n` +
+      `\n` +
+      `Recover with:\n` +
+      `  dotmd status ${repoPath} active && dotmd pickup ${repoPath}`,
+    );
+  }
 
   const today = nowIso();
   const leaseOldStatus = oldStatus === 'in-session' ? 'active' : (oldStatus ?? 'active');
@@ -537,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>'); }
@@ -550,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);
@@ -562,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`);
@@ -572,9 +625,23 @@ export function runArchive(argv, config, opts = {}) {
     if (refCount > 0) {
       out.write(`${prefix} Would update references in ${refCount} file(s)\n`);
     }
+
+    // Preview lease release (only if a lease exists for this plan)
+    if (readLeases(config)[oldRepoPath]) {
+      out.write(`${prefix} Would release in-session lease: ${oldRepoPath}\n`);
+    }
+
+    // Preview onArchive hook fire
+    if (config.hooks?.onArchive) {
+      out.write(`${prefix} Would fire hook: onArchive\n`);
+    }
     return;
   }
 
+  if (closeoutAction?.action === 'inject') {
+    writeFileSync(filePath, `---\n${frontmatter}\n---\n${closeoutAction.newBody}`, 'utf8');
+  }
+
   updateFrontmatter(filePath, { status: 'archived', updated: today });
   appendVersionHistory(filePath, 'Archived.');
 
@@ -592,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');

package/src/prompts.mjs

@@ -29,12 +29,17 @@ export async function runPrompts(argv, config, opts = {}) {
   }
 }
 
-function runPromptsList(argv, config) {
+function runPromptsList(argv, config, opts = {}) {
   const index = buildIndex(config);
   const hasStatusFlag = argv.includes('--status');
   const includeArchived = argv.includes('--include-archived');
   const sub = argv[0];
 
+  if (opts.verbose && !argv.includes('--json')) {
+    renderPromptsVerbose(index, config, { hasStatusFlag, includeArchived });
+    return;
+  }
+
   let defaults;
   let extras = argv;
   if (sub === 'status') {
@@ -48,6 +53,67 @@ function runPromptsList(argv, config) {
   runQuery(index, [...defaults, ...extras], config, { preset: 'prompts' });
 }
 
+// Resolve a prompt's "target plan" for `prompts list --verbose`. Order:
+//   1. frontmatter `related_plans:` (first entry — assumed plan slug)
+//   2. frontmatter `parent_plan:`
+//   3. first body markdown link to a .md file
+// Returns a repo-relative display path or null.
+function findPromptTarget(promptDoc, config) {
+  const refs = promptDoc.refFields ?? {};
+  const fmTargets = [...(refs.related_plans ?? []), ...(refs.parent_plan ?? [])];
+  for (const t of fmTargets) {
+    if (typeof t === 'string' && t.trim()) return slugToPlanPath(t.trim(), config);
+  }
+
+  const links = promptDoc.bodyLinks ?? [];
+  const mdLink = links.find(l => /\.md(?:#|$)/.test(l.href ?? ''));
+  if (mdLink) return resolveBodyLink(mdLink.href, promptDoc.path);
+  return null;
+}
+
+// Plan slugs in frontmatter (e.g. `related_plans: [foo-bar]`) resolve to
+// <docs-root>/plans/<slug>.md.
+function slugToPlanPath(s, config) {
+  const cleaned = s.replace(/#.*$/, '').replace(/^\.\//, '');
+  if (cleaned.includes('/') || cleaned.endsWith('.md')) return cleaned;
+  return `${config.docsRootPrefix || 'docs/'}plans/${cleaned}.md`;
+}
+
+// Resolve a markdown body link relative to the prompt's location so e.g.
+// `../plans/foo.md` from docs/prompts/x.md → docs/plans/foo.md.
+function resolveBodyLink(link, promptRepoPath) {
+  const cleaned = link.replace(/#.*$/, '');
+  if (cleaned.startsWith('/')) return cleaned.replace(/^\/+/, '');
+  const promptDir = path.dirname(promptRepoPath);
+  return path.normalize(path.join(promptDir, cleaned));
+}
+
+function renderPromptsVerbose(index, config, { hasStatusFlag, includeArchived }) {
+  let prompts = index.docs.filter(d => d.type === 'prompt');
+  if (!hasStatusFlag && !includeArchived) {
+    prompts = prompts.filter(d => d.status !== 'archived');
+  }
+  if (prompts.length === 0) {
+    process.stdout.write('No prompts.\n');
+    return;
+  }
+
+  prompts.sort((a, b) => (b.updated ?? '').localeCompare(a.updated ?? ''));
+
+  const counts = {};
+  for (const p of prompts) counts[p.status ?? 'unknown'] = (counts[p.status ?? 'unknown'] ?? 0) + 1;
+  const summary = Object.entries(counts).map(([s, n]) => `${n} ${s}`).join(' · ');
+  process.stdout.write(`${prompts.length} prompt${prompts.length === 1 ? '' : 's'} · ${summary}\n\n`);
+
+  for (const p of prompts) {
+    const slug = path.basename(p.path, '.md');
+    const target = findPromptTarget(p, config);
+    const status = (p.status ?? 'unknown').toUpperCase();
+    const arrow = target ? `  ${dim('→')} ${target}` : `  ${dim('→ (no target plan)')}`;
+    process.stdout.write(`  ${green(slug)}  [${status}]\n${arrow}\n`);
+  }
+}
+
 function pendingPromptsOldestFirst(config) {
   const index = buildIndex(config);
   const prompts = index.docs.filter(d => d.type === 'prompt' && d.status === 'pending');
@@ -139,7 +205,15 @@ function consumePrompt(filePath, config, opts) {
   }
 
   if (dryRun) {
-    process.stderr.write(`${dim('[dry-run]')} Would emit body and archive: ${repoPath} (${status ?? 'unknown'} → archived)\n`);
+    const prefix = dim('[dry-run]');
+    process.stderr.write(`${prefix} Would emit body and archive: ${repoPath} (${status ?? 'unknown'} → archived)\n`);
+    const bytes = Buffer.byteLength(body, 'utf8');
+    const lines = body.split('\n').length;
+    process.stderr.write(`${prefix} body preview (${bytes}B, ${lines} lines):\n`);
+    process.stderr.write(`${dim('---8<---')}\n`);
+    process.stderr.write(body);
+    if (!body.endsWith('\n')) process.stderr.write('\n');
+    process.stderr.write(`${dim('--->8---')}\n`);
     runArchive([filePath], config, { dryRun: true, noIndex, out: process.stderr });
     return;
   }