dotmd-cli 0.48.4 → 0.49.1

package/README.md

@@ -188,7 +188,7 @@ dotmd actionable             List docs with next steps
 dotmd index [--print]        Generate/update docs.md index block
 dotmd hud                    Actionable triage (silent when clean — ideal SessionStart hook)
 dotmd pickup <file>          Pick up a plan (in-session + print body)
-dotmd release [<file>]       Release in-session lease (alias: unpickup)
+dotmd release [<file>]       Release in-session lease (aliases: unpickup, finish)
 dotmd status <file> <status> Transition document status
 dotmd archive <file>         Archive (status + move + update refs)
 dotmd bulk archive <files>   Archive multiple files at once
@@ -335,8 +335,10 @@ Each invocation appends one JSON line:
 `{ts, sid, pid, argv, exit, ms, v, err?}`. Writes are atomic via
 `O_APPEND` (entries are well under `PIPE_BUF`), so concurrent sessions
 interleave cleanly without locking. Lazy rotation to
-`.dotmd/journal.jsonl.1` at >5MB or oldest entry >30 days; one backup
-retained.
+`.dotmd/journal.jsonl.1` on version change, at >5MB, or when the oldest
+entry is >30 days; one backup retained and pruned after 30 days.
+Version-change rotation keeps agent-facing journal summaries focused on the
+currently installed dotmd.
 
 Read it back with `dotmd journal`:
 
@@ -583,7 +585,9 @@ dotmd status docs/plans/my-plan.md partial   # shipped + tail deferred (referenc
 dotmd status docs/plans/my-plan.md awaiting  # stuck on a human decision
 ```
 
-`finish` is a legacy command that defaults to `status: done`, which is no longer in the default plan vocabulary as of 0.16. Use `archive` (fully shipped) or `release` + `status` (anything else). If you need it back, add `done` to `types.plan.statuses` in your config.
+`finish` is an alias for `release`, kept for older agent instructions that use
+that verb for closeout. To fully close shipped work, archive it. To keep working
+later, release it back to the prior status or use `dotmd set <status> <file>`.
 
 ### Session leases & release
 
@@ -596,8 +600,8 @@ distinct outcomes when a plan is already `in-session`:
   re-prints the body. No conflict.
 - **Cross-session conflict.** If another live session holds the plan,
   pickup refuses with `Held by <host>/<session> (pid <pid>) since <time>`.
-- **Stale lease.** If the holder's pid is dead (or the lease is >24h old),
-  pickup refuses but suggests `--takeover`.
+- **Reclaimable lease.** If the holder's same-host pid is dead, or the lease is
+  older than 4 hours, pickup can reclaim it without `--takeover`.
 
 Releasing leases (both names work; `release` is the recommended verb):
 
@@ -605,13 +609,13 @@ Releasing leases (both names work; `release` is the recommended verb):
 dotmd release                     # release every lease owned by current session
 dotmd release docs/plans/foo.md   # release that one (refuses cross-session)
 dotmd release --to planned        # override target status (default: lease.oldStatus)
-dotmd release --stale             # release leases with dead pid or >24h old
+dotmd release --stale             # release leases with dead same-host pid or >4h old
 dotmd release --all               # release every lease (administrative)
 dotmd release --json              # { released: [...], skipped: [...] }
 ```
 
-`finish`, `archive`, and `rename` auto-release / migrate the lease, so the
-common closeout paths are covered without ceremony.
+`finish` is the same as `release`. `archive` and `rename` auto-release or
+migrate the lease, so the common closeout paths are covered without ceremony.
 
 **Session id resolution** (in order, first wins):
 
@@ -666,7 +670,7 @@ either is silent.
 
 `dotmd check` also catches the symmetric failure mode: a plan whose
 frontmatter claims `status: in-session` but whose lease either doesn't
-exist (last session crashed before releasing) or is stale (>24h since
+exist (last session crashed before releasing) or is stale (>4h since
 pickup). Each warning names the exact unstuck command
 (`dotmd release <plan>` or `dotmd status <plan> active`), so plans
 don't sit stuck in-session indefinitely. Always-on — legit concurrent

package/bin/dotmd.mjs

@@ -4,7 +4,7 @@ import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import { resolveConfig } from '../src/config.mjs';
-import { die, warn, levenshtein } from '../src/util.mjs';
+import { die, warn, levenshtein, isArchivedPath } from '../src/util.mjs';
 import { recordCliInvocation, recordGlobalError } from '../src/journal.mjs';
 import { findRepeatFailureHint } from '../src/hints.mjs';
 
@@ -12,12 +12,62 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
 
+const QUERY_FLAGS = new Set([
+  '--type', '--status', '--keyword', '--owner', '--surface', '--module',
+  '--domain', '--audience', '--execution-mode', '--updated-since', '--limit',
+  '--sort', '--group', '--all', '--include-archived', '--exclude-archived',
+  '--stale', '--has-next-step', '--has-blockers', '--checklist-open', '--json',
+  '--git', '--summarize', '--summarize-limit', '--model',
+]);
+const QUERY_VALUE_FLAGS = new Set([
+  '--type', '--status', '--keyword', '--owner', '--surface', '--module',
+  '--domain', '--audience', '--execution-mode', '--updated-since', '--limit',
+  '--sort', '--group', '--summarize-limit', '--model',
+]);
+
+const FLAG_SPECS = {
+  plans: { flags: QUERY_FLAGS, values: QUERY_VALUE_FLAGS, subcommands: new Set(['status']) },
+  query: { flags: QUERY_FLAGS, values: QUERY_VALUE_FLAGS },
+  stale: { flags: QUERY_FLAGS, values: QUERY_VALUE_FLAGS },
+  actionable: { flags: QUERY_FLAGS, values: QUERY_VALUE_FLAGS },
+  list: { flags: new Set(['--json', '--verbose']), values: new Set() },
+  briefing: { flags: new Set(['--json']), values: new Set() },
+  context: { flags: new Set(['--json', '--compact', '--summarize', '--model']), values: new Set(['--model']) },
+  'agent-context': { flags: new Set(['--json']), values: new Set() },
+  hud: { flags: new Set(['--json']), values: new Set() },
+  check: { flags: new Set(['--fix', '--errors-only', '--no-collapse', '--json', '--verbose']), values: new Set() },
+  doctor: { flags: new Set(['--apply', '--yes', '--dry-run', '-n', '--statuses', '--migrate-template', '--migrate-prompts', '--frontmatter-fix', '--project', '--json', '--include-archived']), values: new Set() },
+  runlist: { flags: new Set(['--json', '--takeover', '--full', '--no-index', '--show-files']), values: new Set(), subcommands: new Set(['next']) },
+  release: { flags: new Set(['--json', '--all', '--stale', '--to', '--force', '--no-index', '--show-files']), values: new Set(['--to']) },
+  unpickup: { flags: new Set(['--json', '--all', '--stale', '--to', '--force', '--no-index', '--show-files']), values: new Set(['--to']) },
+  finish: { flags: new Set(['--json', '--all', '--stale', '--to', '--force', '--no-index', '--show-files']), values: new Set(['--to']) },
+  prompts: {
+    flags: new Set(['--json', '--status', '--include-archived', '--sort', '--limit', '--all', '--no-index', '--show-files', '--body', '--message', '--title']),
+    values: new Set(['--status', '--sort', '--limit', '--body', '--message', '--title']),
+    subcommands: new Set(['list', 'next', 'use', 'resume', 'archive', 'new', 'shelve', 'unshelve', 'status']),
+  },
+};
+
+function validateKnownFlags(command, argv, config) {
+  const spec = FLAG_SPECS[command] ?? (config?.presets?.[command] ? { flags: QUERY_FLAGS, values: QUERY_VALUE_FLAGS } : null);
+  if (!spec) return;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (spec.subcommands?.has(arg)) continue;
+    if (!arg.startsWith('-')) continue;
+    if (!spec.flags.has(arg)) die(`Unknown flag for \`dotmd ${command}\`: ${arg}`);
+    if (spec.values.has(arg)) i += 1;
+  }
+}
+
 const HELP = {
   _main: `dotmd v${pkg.version} — frontmatter markdown document manager
 
 Common commands:
   plans                 Live plans (excludes archived)
+  prompts               Prompt queue/admin (list, next, archive, new, shelve)
   briefing              Full briefing with plan counts + next steps
+  agent-context         Compact bounded JSON context for agents
   set <status> [file]   Transition status (start work, finish, archive — all via target status)
   new <type> <name>     Create plan/doc/prompt (pipe stdin or @path for body)
   use [<file>]          Open a doc by type: prompt → consume, plan → start, doc → read
@@ -40,7 +90,8 @@ View & Query:
   hud [--json]                      Two-line actionable triage (held / prompts / stuck) — silent when clean
   list [--verbose] [--json]         List docs grouped by status (default command)
   briefing [--json]                 Full briefing with plan status counts + next steps
-  context [--summarize] [--json]    Full briefing (LLM-oriented)
+  context [--summarize] [--json]    Full briefing (LLM-oriented; use --json --compact for bounded JSON)
+  agent-context [--json]            Compact bounded JSON context for agents
   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)
@@ -65,12 +116,16 @@ Analyze:
 
 Validate & Fix:
   doctor [--apply]                  Auto-fix everything: refs, lint, dates, index (preview by default)
+  self-check                        Project/version skew diagnostic (alias: doctor --project)
   lint [--fix]                      Check and auto-fix frontmatter issues
   fix-refs [--dry-run]              Auto-fix broken reference paths + body links
 
 Lifecycle:
+  pickup <file>                      Acquire an in-session lease and start work
+  release [<file>]                   Release held in-session work (alias: unpickup, finish)
   set <status> [<file>]             Unified transition: start work, change status, close out, archive — all via target status
   runlist <hub> [next]              Show or walk an ordered group of plans (see \`dotmd help runlist\`)
+  unpickup [<file>]                  Release held in-session work
   status <file> <status>            Transition document status (deprecated; prefer \`set\`)
   archive <file>                    Archive (status + move + update refs)
   bulk archive <f1> <f2> ...        Archive multiple files at once
@@ -228,8 +283,10 @@ Reader options:
   --json              Emit selected entries as a JSON array
 
 Storage:
-  Rotates to .dotmd/journal.jsonl.1 at >5MB or oldest entry >30 days.
-  Single backup retained; older history is dropped on rotation.
+  Rotates to .dotmd/journal.jsonl.1 on dotmd version change, at >5MB,
+  or when the oldest entry is >30 days.
+  Single backup retained for up to 30 days; older history is dropped on
+  rotation or pruned after the retention window.
 
 Examples:
   DOTMD_JOURNAL=1 dotmd plans
@@ -315,6 +372,11 @@ status. With no file, releases every lease owned by the current session.
 Identical behavior to \`dotmd unpickup\`; both names route to the same
 implementation. See \`dotmd unpickup --help\` for full option list.`,
 
+  finish: `dotmd finish [<file>] [--to <s>] — alias of dotmd release
+
+Compatibility alias for docs and agent loops that use "finish" for releasing
+in-session work. Same behavior as \`dotmd release\` / \`dotmd unpickup\`.`,
+
   ship: `dotmd ship [patch|minor|major] — regen + commit + bump in one step
 
 Bundles the multi-step release dance into a single command:
@@ -479,13 +541,21 @@ Options:
 
   context: `dotmd context — full briefing (LLM-oriented)
 
-Generates a compact status briefing designed for AI/LLM consumption.
+Generates a status briefing designed for AI/LLM consumption. The default
+JSON form is the full index grouped by type/status; use --compact for bounded
+agent-safe JSON.
 
 Options:
   --json                 Output as JSON
+  --compact              With --json, return counts + bounded next-action lists
   --summarize            Add AI summaries for expanded docs
   --model <name>         Model for AI summaries`,
 
+  'agent-context': `dotmd agent-context — compact bounded JSON for agents
+
+Equivalent to \`dotmd context --json --compact\`. Returns counts,
+validation totals, pending prompt next item, and bounded plan action lists.`,
+
   stats: `dotmd stats — doc health dashboard
 
 Shows aggregated metrics: status counts, staleness, errors/warnings,
@@ -615,9 +685,11 @@ Modes:
                          / \`## Next Step\` body section (created above
                          the first H2 if absent, appended otherwise).
                          Plans only; honors --dry-run.
+  --project              Report CLI/project version skew, generated command
+                         drift, and detectable deprecated command mentions.
 
 --apply (or --yes) opts into writes for the default auto-fix pass.
-Sub-modes (--statuses, --migrate-*, --frontmatter-fix) keep their
+Sub-modes (--statuses, --migrate-*, --frontmatter-fix, --project) keep their
 existing contracts: they write by default and honor --dry-run.`,
 
   'fix-refs': `dotmd fix-refs — auto-fix broken reference paths
@@ -1143,6 +1215,8 @@ async function main() {
     process.stderr.write(`Repo root: ${config.repoRoot}\n`);
   }
 
+  validateKnownFlags(command, restArgs, config);
+
   // Preset aliases (user config can override built-in commands below)
   if (config.presets[command]) {
     const { buildIndex } = await import('../src/index.mjs');
@@ -1214,7 +1288,7 @@ async function main() {
   if (command === 'hud') { const { runHud } = await import('../src/hud.mjs'); runHud(restArgs, config); return; }
   if (command === 'journal') { const { runJournal } = await import('../src/journal-read.mjs'); runJournal(restArgs, config); return; }
   if (command === 'pickup') { const { runPickup } = await import('../src/lifecycle.mjs'); await runPickup(restArgs, config, { dryRun }); return; }
-  if (command === 'unpickup' || command === 'release') { const { runUnpickup } = await import('../src/lifecycle.mjs'); await runUnpickup(restArgs, config, { dryRun }); return; }
+  if (command === 'unpickup' || command === 'release' || command === 'finish') { const { runUnpickup } = await import('../src/lifecycle.mjs'); await runUnpickup(restArgs, config, { dryRun }); return; }
   if (command === 'runlist') { const { runRunlist } = await import('../src/runlist.mjs'); await runRunlist(restArgs, config, { dryRun }); return; }
   if (command === 'handoff') { die('`dotmd handoff` was removed in 0.31.0. Use `dotmd prompts new <name>` to create a saved prompt instead. The .dotmd/handoffs/ sidecar mechanism no longer exists; see CHANGELOG.'); }
   if (command === 'status') { const { runStatus } = await import('../src/lifecycle.mjs'); await runStatus(restArgs, config, { dryRun }); return; }
@@ -1230,6 +1304,11 @@ async function main() {
   if (command === 'rename') { const { runRename } = await import('../src/rename.mjs'); await runRename(restArgs, config, { dryRun }); return; }
   if (command === 'migrate') { const { runMigrate } = await import('../src/migrate.mjs'); runMigrate(restArgs, config, { dryRun }); return; }
   if (command === 'fix-refs') { const { runFixRefs } = await import('../src/fix-refs.mjs'); runFixRefs(restArgs, config, { dryRun }); return; }
+  if (command === 'self-check') {
+    const { runDoctor } = await import('../src/doctor.mjs');
+    runDoctor(['--project', ...restArgs], config, { dryRun });
+    return;
+  }
   if (command === 'doctor') {
     // 0.37.0 (F4): the default auto-fix loop previews by default; --apply
     // (alias --yes) writes. Explicit --dry-run still works and wins over
@@ -1237,7 +1316,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') || args.includes('--frontmatter-fix');
+    const subMode = args.includes('--statuses') || args.includes('--migrate-template') || args.includes('--migrate-prompts') || args.includes('--frontmatter-fix') || args.includes('--project');
     const explicitApply = args.includes('--apply') || args.includes('--yes');
     const explicitDryRun = args.includes('--dry-run') || args.includes('-n');
     const doctorDryRun = subMode ? dryRun : (explicitDryRun || !explicitApply);
@@ -1255,7 +1334,7 @@ async function main() {
   // Opportunistic stale-lease scrub for user-facing "what's actionable now"
   // views. Diagnostic commands (`check`, `coverage`, `stats`, `index`) are
   // intentionally excluded — they should surface drift, not silently fix it.
-  const SCRUB_READ_COMMANDS = new Set(['list', 'briefing', 'context', 'focus', 'query', 'modules', 'module', 'surfaces']);
+  const SCRUB_READ_COMMANDS = new Set(['list', 'briefing', 'context', 'agent-context', 'focus', 'query', 'modules', 'module', 'surfaces']);
   if (SCRUB_READ_COMMANDS.has(command)) {
     const { scrubStaleSilently } = await import('../src/lease-scrub.mjs');
     scrubStaleSilently(config);
@@ -1436,6 +1515,55 @@ async function main() {
     runSurfaces(restArgs, config);
     return;
   }
+
+  function compactDoc(d) {
+    return {
+      path: d.path,
+      title: d.title,
+      status: d.status,
+      type: d.type,
+      nextStep: d.nextStep ?? null,
+      blockers: d.blockers ?? [],
+      daysSinceUpdate: d.daysSinceUpdate ?? null,
+    };
+  }
+
+  function buildCompactAgentContext(idx) {
+    const activeStatuses = new Set(['in-session', 'active', 'ready', 'planned', 'awaiting', 'blocked']);
+    const active = idx.docs.filter(d => d.type === 'plan' && activeStatuses.has(d.status));
+    const stale = idx.docs.filter(d => d.isStale && !config.lifecycle.skipStaleFor.has(d.status));
+    const awaiting = idx.docs.filter(d => d.status === 'awaiting');
+    const blocked = idx.docs.filter(d => d.status === 'blocked' || d.blockers?.length);
+    const pendingPrompts = idx.docs
+      .filter(d => d.type === 'prompt' && d.status === 'pending' && !isArchivedPath(d.path, config))
+      .sort((a, b) => (a.created ?? '').localeCompare(b.created ?? '') || (a.updated ?? '').localeCompare(b.updated ?? ''));
+    return {
+      generatedAt: new Date().toISOString(),
+      countsByStatus: idx.countsByStatus,
+      countsByType: idx.countsByType,
+      errors: {
+        count: idx.errors.length,
+        items: idx.errors.slice(0, 10).map(e => ({ path: e.path, message: e.message })),
+      },
+      warnings: { count: idx.warnings.length },
+      prompts: {
+        pending: pendingPrompts.length,
+        next: pendingPrompts[0] ? compactDoc(pendingPrompts[0]) : null,
+      },
+      plans: {
+        active: active.slice(0, 12).map(compactDoc),
+        awaiting: awaiting.slice(0, 8).map(compactDoc),
+        blocked: blocked.slice(0, 8).map(compactDoc),
+        stale: stale.slice(0, 12).map(compactDoc),
+      },
+    };
+  }
+
+  if (command === 'agent-context') {
+    process.stdout.write(JSON.stringify(buildCompactAgentContext(index), null, 2) + '\n');
+    return;
+  }
+
   if (command === 'briefing') {
     if (args.includes('--json')) {
       const plans = index.docs.filter(d => d.type === 'plan');
@@ -1456,10 +1584,15 @@ async function main() {
 
   if (command === 'context') {
     const summarize = args.includes('--summarize');
+    const compact = args.includes('--compact');
     const modelIdx = args.indexOf('--model');
     const model = modelIdx !== -1 && args[modelIdx + 1] ? args[modelIdx + 1] : undefined;
 
     if (args.includes('--json')) {
+      if (compact) {
+        process.stdout.write(JSON.stringify(buildCompactAgentContext(index), null, 2) + '\n');
+        return;
+      }
       const byStatus = {};
       for (const doc of index.docs) {
         const s = doc.status ?? 'unknown';

package/package.json

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

package/src/commands.mjs

@@ -3,10 +3,10 @@
 // that asserts every `dotmd <verb>` reference in generated slash-command
 // templates points at a real command.
 export const KNOWN_COMMANDS = [
-  'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'briefing', 'context', 'hud',
-  'focus', 'query', 'plans', 'prompts', 'stale', 'actionable', 'index', 'pickup', 'release', 'status', 'set', 'use', 'next', 'archive', 'bulk', 'bulk-tag', 'touch', 'doctor', 'runlist',
+  'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'briefing', 'context', 'agent-context', 'hud',
+  'focus', 'query', 'plans', 'prompts', 'stale', 'actionable', 'index', 'pickup', 'release', 'finish', 'status', 'set', 'use', 'next', 'archive', 'bulk', 'bulk-tag', 'touch', 'doctor', 'runlist',
   'unblocks', 'health', 'glossary', 'modules', 'module',
   'fix-refs', 'lint', 'rename', 'migrate', 'notion', 'export', 'summary',
   'watch', 'diff', 'new', 'init', 'completions', 'statuses', 'journal',
-  'ship',
+  'ship', 'self-check',
 ];

package/src/completions.mjs

@@ -2,7 +2,7 @@ import { die } from './util.mjs';
 
 const COMMANDS = [
   'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'unblocks', 'health', 'glossary', 'briefing', 'context', 'focus', 'query',
-  'plans', 'stale', 'actionable', 'index', 'pickup', 'unpickup', 'status', 'set', 'archive', 'bulk', 'touch', 'doctor', 'lint', 'rename', 'migrate',
+  'plans', 'stale', 'actionable', 'index', 'pickup', 'unpickup', 'release', 'finish', 'status', 'set', 'archive', 'bulk', 'touch', 'doctor', 'lint', 'rename', 'migrate',
   'fix-refs', 'notion', 'export', 'summary', 'watch', 'diff', 'init', 'new', 'completions', 'journal',
 ];
 
@@ -34,8 +34,9 @@ const COMMAND_FLAGS = {
   actionable: ['--json', '--sort', '--limit', '--all'],
   briefing: ['--json'],
   pickup: ['--json', '--takeover'],
-  unpickup: ['--json', '--all', '--stale', '--to', '--force'],
-  finish: ['--json'],
+  unpickup: ['--json', '--all', '--stale', '--to', '--force', '--no-index', '--show-files'],
+  release: ['--json', '--all', '--stale', '--to', '--force', '--no-index', '--show-files'],
+  finish: ['--json', '--all', '--stale', '--to', '--force', '--no-index', '--show-files'],
   status: [],
   archive: [],
   doctor: [],

package/src/doctor.mjs

@@ -1,14 +1,17 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
 import { fixBrokenRefs } from './fix-refs.mjs';
 import { runLint } from './lint.mjs';
 import { runTouch } from './lifecycle.mjs';
-import { buildIndex } from './index.mjs';
+import { buildIndex, collectDocFiles } from './index.mjs';
 import { renderIndexFile, writeIndex } from './index-file.mjs';
-import { renderCheck } from './render.mjs';
+import { renderCheck, renderManualFixes } from './render.mjs';
 import { bold, dim, green, yellow } from './color.mjs';
-import { scaffoldClaudeCommands } from './claude-commands.mjs';
+import { checkClaudeCommands, scaffoldClaudeCommands } from './claude-commands.mjs';
 import { runMigrateTemplate } from './migrate-template.mjs';
 import { runMigratePrompts } from './migrate-prompts.mjs';
 import { runFrontmatterFix } from './frontmatter-fix.mjs';
+import { toRepoPath } from './util.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).
@@ -40,6 +43,10 @@ const CUE_LABELS = {
 };
 
 export function runDoctor(argv, config, opts = {}) {
+  if (argv.includes('--project')) {
+    runDoctorProject(config, { json: argv.includes('--json') });
+    return;
+  }
   if (argv.includes('--statuses')) {
     runDoctorStatuses(config, { json: argv.includes('--json') });
     return;
@@ -118,6 +125,67 @@ export function runDoctor(argv, config, opts = {}) {
   process.stdout.write('\n' + bold('6. Remaining issues:') + '\n');
   const freshIndex = buildIndex(config);
   process.stdout.write(renderCheck(freshIndex, config));
+  const manual = renderManualFixes(freshIndex);
+  if (manual.trim()) {
+    process.stdout.write('\n' + bold('Closeout guidance') + '\n');
+    process.stdout.write(manual);
+  }
+}
+
+function readJsonIfPresent(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function findDeprecatedCommandMentions(config) {
+  const docs = collectDocFiles(config);
+  const matches = [];
+  for (const filePath of docs) {
+    let raw = '';
+    try { raw = readFileSync(filePath, 'utf8'); } catch { continue; }
+    if (/\bdotmd status\b/.test(raw) || /\bdotmd pickup\b/.test(raw)) {
+      matches.push(toRepoPath(filePath, config.repoRoot));
+    }
+  }
+  return matches;
+}
+
+function runDoctorProject(config, { json = false } = {}) {
+  const cliPackage = readJsonIfPresent(new URL('../package.json', import.meta.url));
+  const repoPackage = readJsonIfPresent(path.join(config.repoRoot, 'package.json'));
+  const depVersion = repoPackage?.dependencies?.['dotmd-cli']
+    ?? repoPackage?.devDependencies?.['dotmd-cli']
+    ?? repoPackage?.dependencies?.dotmd
+    ?? repoPackage?.devDependencies?.dotmd
+    ?? null;
+  const claudeCommandWarnings = checkClaudeCommands(config.repoRoot);
+  const deprecatedCommandMentions = findDeprecatedCommandMentions(config);
+  const result = {
+    cliVersion: cliPackage?.version ?? null,
+    packageDependency: depVersion,
+    claudeCommandWarnings,
+    deprecatedCommandMentions,
+  };
+
+  if (json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    return result;
+  }
+
+  process.stdout.write(bold('dotmd doctor --project') + '\n\n');
+  process.stdout.write(`- running CLI version: ${result.cliVersion ?? 'unknown'}\n`);
+  process.stdout.write(`- package dependency: ${result.packageDependency ?? '(none found)'}\n`);
+  process.stdout.write(`- stale Claude commands: ${claudeCommandWarnings.length}\n`);
+  if (deprecatedCommandMentions.length) {
+    process.stdout.write(`- docs mentioning deprecated commands: ${deprecatedCommandMentions.length}\n`);
+    for (const file of deprecatedCommandMentions.slice(0, 10)) process.stdout.write(`  - ${file}\n`);
+  } else {
+    process.stdout.write('- docs mentioning deprecated commands: 0\n');
+  }
+  return result;
 }
 
 export function analyzeStatusBuckets(docs) {

package/src/glossary-check.mjs

@@ -0,0 +1,35 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { suggestCandidates } from './util.mjs';
+
+function sectionHeadingRegex(sectionHeading) {
+  return new RegExp(`^##\\s+${sectionHeading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`, 'm');
+}
+
+export function checkGlossaryConfig(config) {
+  const glossaryConfig = config.raw?.glossary;
+  if (!glossaryConfig?.path) return [];
+
+  const filePath = path.resolve(config.repoRoot, glossaryConfig.path);
+  if (!existsSync(filePath)) {
+    return [{
+      path: glossaryConfig.path,
+      level: 'warning',
+      message: `Glossary file configured at \`${glossaryConfig.path}\` but the file does not exist.`,
+    }];
+  }
+
+  const content = readFileSync(filePath, 'utf8');
+  const section = glossaryConfig.section ?? 'Terminology';
+  if (sectionHeadingRegex(section).test(content)) return [];
+
+  const headings = [...content.matchAll(/^##\s+(.+?)\s*$/gm)].map(m => m[1].trim());
+  const suggestions = suggestCandidates(section, headings, 3);
+  const nearby = suggestions.length ? suggestions : headings.slice(0, 3);
+  const hint = nearby.length ? ` Nearby headings: ${nearby.map(s => `\`${s}\``).join(', ')}.` : '';
+  return [{
+    path: glossaryConfig.path,
+    level: 'warning',
+    message: `Glossary config points at section \`## ${section}\`, but that heading is missing in \`${glossaryConfig.path}\`.${hint} Update \`glossary.path\` / \`glossary.section\` or restore the heading.`,
+  }];
+}

package/src/glossary.mjs

@@ -4,8 +4,12 @@ import { buildIndex } from './index.mjs';
 import { die, warn, suggestCandidates } from './util.mjs';
 import { bold, dim, green, yellow } from './color.mjs';
 
+function sectionHeadingRegex(sectionHeading) {
+  return new RegExp(`^##\\s+${sectionHeading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`, 'm');
+}
+
 function parseGlossaryTable(content, sectionHeading) {
-  const headingRegex = new RegExp(`^##\\s+${sectionHeading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`, 'm');
+  const headingRegex = sectionHeadingRegex(sectionHeading);
   const match = content.match(headingRegex);
   if (!match) return { found: false, entries: [] };
 

package/src/hud.mjs

@@ -246,6 +246,13 @@ export function runHud(argv, config) {
   // one line, the minimum verb set.
   lines.push(dim('dotmd: plans|briefing  set <status> [<file>]  new <type> <slug>  use [<file>]  archive <file>  (use [no-arg] → oldest pending prompt)'));
 
+  const state = [];
+  if (hud.owned?.length) state.push(`held: ${hud.owned.length} (${previewList(hud.owned)})`);
+  if (hud.prompts?.length) state.push(`prompts: ${hud.prompts.length} (${previewList(hud.prompts)})`);
+  if (hud.stale?.length) state.push(`stuck: ${hud.stale.length} (${previewList(hud.stale)})`);
+  if (hud.errors > 0) state.push(`errors: ${hud.errors} (run dotmd check)`);
+  if (state.length) lines.push(yellow(state.join(' · ')));
+
   if (refreshed.length > 0) {
     const from = refreshed[0].from;
     const to = refreshed[0].to;

package/src/index.mjs

@@ -6,6 +6,7 @@ import { asString, normalizeStringList, normalizeBlockers, mergeUniqueStrings, t
 import { validateDoc, validatePlanShape, validateDocShape, checkBidirectionalReferences, checkGitStaleness, checkRunlistBackPointers, computeDaysSinceUpdate, computeIsStale, computeChecklistCompletionRate, enrichRefErrorSuggestions } from './validate.mjs';
 import { checkIndex } from './index-file.mjs';
 import { checkClaudeCommands } from './claude-commands.mjs';
+import { checkGlossaryConfig } from './glossary-check.mjs';
 
 // `fast: true` skips every pass that produces warnings/errors — the rendered
 // index file consumes only status/title/snapshot/etc., not the validation
@@ -124,6 +125,9 @@ export function buildIndex(config, opts = {}) {
 
     const claudeWarnings = checkClaudeCommands(config.repoRoot);
     warnings.push(...claudeWarnings);
+
+    const glossaryWarnings = checkGlossaryConfig(config);
+    warnings.push(...glossaryWarnings);
   }
 
   return {

package/src/journal.mjs

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, appendFileSync, statSync, renameSync, readFileSync } from 'node:fs';
+import { existsSync, mkdirSync, appendFileSync, statSync, renameSync, readFileSync, unlinkSync } from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { currentSessionId } from './lease.mjs';
@@ -8,6 +8,7 @@ const JOURNAL_FILE = 'journal.jsonl';
 const JOURNAL_BACKUP = 'journal.jsonl.1';
 const ROTATE_SIZE_BYTES = 5 * 1024 * 1024;
 const ROTATE_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+const BACKUP_RETENTION_MS = ROTATE_AGE_MS;
 
 const ERROR_LOG_FILE = 'dotmd-errors.log';
 const ERROR_LOG_BACKUP = 'dotmd-errors.log.1';
@@ -26,10 +27,31 @@ export function journalBackupPath(config) {
   return path.join(config.repoRoot, JOURNAL_DIR, JOURNAL_BACKUP);
 }
 
-function maybeRotate(file, backup) {
+function firstEntryVersion(file) {
+  try {
+    const sample = readFileSync(file, 'utf8');
+    const nl = sample.indexOf('\n');
+    const first = nl >= 0 ? sample.slice(0, nl) : sample;
+    if (!first.trim()) return null;
+    const obj = JSON.parse(first);
+    return obj?.v == null ? null : String(obj.v);
+  } catch {
+    return null;
+  }
+}
+
+function maybeRotate(file, backup, nextEntry = null) {
+  pruneStaleBackup(backup);
   if (!existsSync(file)) return;
   let st;
   try { st = statSync(file); } catch { return; }
+  if (nextEntry?.v) {
+    const existingVersion = firstEntryVersion(file);
+    if (existingVersion !== String(nextEntry.v)) {
+      try { renameSync(file, backup); } catch {}
+      return;
+    }
+  }
   if (st.size > ROTATE_SIZE_BYTES) {
     try { renameSync(file, backup); } catch {}
     return;
@@ -50,6 +72,16 @@ function maybeRotate(file, backup) {
   } catch {}
 }
 
+function pruneStaleBackup(backup) {
+  if (!existsSync(backup)) return;
+  try {
+    const st = statSync(backup);
+    if ((Date.now() - st.mtimeMs) > BACKUP_RETENTION_MS) {
+      try { unlinkSync(backup); } catch {}
+    }
+  } catch {}
+}
+
 export function appendJournalEntry(config, entry) {
   if (!isJournalEnabled(config)) return;
   if (!config?.repoRoot) return;
@@ -57,7 +89,7 @@ export function appendJournalEntry(config, entry) {
     const dir = path.join(config.repoRoot, JOURNAL_DIR);
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
     const file = journalFilePath(config);
-    maybeRotate(file, journalBackupPath(config));
+    maybeRotate(file, journalBackupPath(config), entry);
     // O_APPEND is atomic for writes under PIPE_BUF (4KB on Linux, 512B on
     // macOS). Entries are well under either threshold, so concurrent CLI
     // invocations interleave cleanly without locking.
@@ -143,7 +175,7 @@ export function recordGlobalError({ config, startMs, args, err, version }) {
     const dir = globalErrorLogDir();
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
     const file = globalErrorLogPath();
-    maybeRotate(file, globalErrorLogBackupPath());
+    maybeRotate(file, globalErrorLogBackupPath(), entry);
     appendFileSync(file, JSON.stringify(entry) + '\n', { flag: 'a' });
   } catch {
     // Logging must never break exit.

package/src/lease.mjs

@@ -100,18 +100,28 @@ export function isPidAlive(pid, host) {
   }
 }
 
+export function isLeasePidDead(lease) {
+  if (!lease || lease.host !== os.hostname()) return false;
+  if (!Number.isInteger(lease.pid) || lease.pid <= 0) return false;
+  return !isPidAlive(lease.pid, lease.host);
+}
+
 export function isLeaseStale(lease) {
   const t = new Date(lease.pickedUpAt).getTime();
   if (Number.isNaN(t)) return true;
   return Date.now() - t > STALE_LEASE_AGE_MS;
-  // Note: pid liveness is intentionally NOT used here. dotmd's own CLI pid is
-  // dead the moment the process exits, so it's not a useful signal for "is the
-  // session that wrote this lease still active." Use age and explicit takeover.
 }
 
-export function findStaleLeases(config) {
+export function isLeaseReclaimable(lease, opts = {}) {
+  if (isLeaseStale(lease)) return true;
+  const currentSession = opts.currentSession ?? currentSessionId();
+  if (lease?.session === currentSession) return false;
+  return isLeasePidDead(lease);
+}
+
+export function findStaleLeases(config, opts = {}) {
   const leases = readLeases(config);
-  return Object.values(leases).filter(isLeaseStale);
+  return Object.values(leases).filter(l => isLeaseReclaimable(l, opts));
 }
 
 export function acquireLease(config, repoPath, oldStatus, opts = {}) {
@@ -129,8 +139,7 @@ export function acquireLease(config, repoPath, oldStatus, opts = {}) {
     }
 
     if (existing && !opts.takeover) {
-      const ageMs = Date.now() - new Date(existing.pickedUpAt).getTime();
-      const stale = Number.isNaN(ageMs) || ageMs > STALE_LEASE_AGE_MS;
+      const stale = isLeaseReclaimable(existing, { currentSession: session });
       return {
         outcome: stale ? 'conflict-stale' : 'conflict-alive',
         conflict: existing,
@@ -189,12 +198,13 @@ export function releaseAllForSession(config, sessionId, opts = {}) {
   });
 }
 
-export function releaseStale(config) {
+export function releaseStale(config, opts = {}) {
   return withLeaseLock(config, () => {
     const leases = readLeases(config);
     const released = [];
+    const currentSession = opts.currentSession ?? currentSessionId();
     for (const [key, lease] of Object.entries(leases)) {
-      if (isLeaseStale(lease)) {
+      if (isLeaseReclaimable(lease, { currentSession })) {
         released.push(lease);
         delete leases[key];
       }

package/src/lifecycle.mjs

@@ -15,7 +15,7 @@ import {
   readLeases,
   currentSessionId,
   migrateLease,
-  STALE_LEASE_AGE_MS,
+  isLeaseReclaimable,
   STALE_LEASE_AGE_HOURS,
 } from './lease.mjs';
 import { buildCard, renderCard } from './pickup-card.mjs';
@@ -292,7 +292,7 @@ export async function runPickup(argv, config, opts = {}) {
   // Without this, a stale lease from a crashed prior session would still
   // produce 'conflict-stale' and force the agent to pass --takeover even
   // though we already know the holder is gone.
-  if (!dryRun) {
+  if (!dryRun && !takeover) {
     try {
       const { scrubStaleSilently } = await import('./lease-scrub.mjs');
       scrubStaleSilently(config);
@@ -511,10 +511,7 @@ export async function runUnpickup(argv, config, opts = {}) {
   if (targets === null) {
     // --stale path
     if (dryRun) {
-      const staleLeases = Object.values(leases).filter(l => {
-        const age = Date.now() - new Date(l.pickedUpAt).getTime();
-        return Number.isNaN(age) || age > STALE_LEASE_AGE_MS;
-      });
+      const staleLeases = Object.values(leases).filter(l => isLeaseReclaimable(l, { currentSession: session }));
       for (const l of staleLeases) {
         process.stderr.write(`${dim('[dry-run]')} Would release stale: ${l.path} (${l.session})\n`);
       }

package/src/prompts.mjs

@@ -38,12 +38,19 @@ function runPromptsList(argv, config, opts = {}) {
   const hasStatusFlag = argv.includes('--status');
   const includeArchived = argv.includes('--include-archived');
   const sub = argv[0];
+  const json = argv.includes('--json');
 
-  if (opts.verbose && !argv.includes('--json')) {
+  if (opts.verbose && !json) {
     renderPromptsVerbose(index, config, { hasStatusFlag, includeArchived });
     return;
   }
 
+  const hasPositionalFilter = argv.some(a => !a.startsWith('-') && a !== 'list');
+  if (!json && !hasStatusFlag && !includeArchived && !hasPositionalFilter && sub !== 'status' && !argv.some(a => a.startsWith('--sort') || a.startsWith('--limit') || a === '--all')) {
+    renderPromptQueueList(index, config);
+    return;
+  }
+
   let defaults;
   let extras = argv;
   if (sub === 'status') {
@@ -57,6 +64,34 @@ function runPromptsList(argv, config, opts = {}) {
   runQuery(index, [...defaults, ...extras], config, { preset: 'prompts' });
 }
 
+function renderPromptQueueList(index, config) {
+  const queue = pendingPromptsOldestFirst(config);
+  const queuedPaths = new Set(queue.map(q => q.doc.path));
+  const others = index.docs
+    .filter(d => d.type === 'prompt' && !queuedPaths.has(d.path) && !isArchivedPath(d.path, config) && d.status !== 'archived')
+    .sort((a, b) => (b.updated ?? '').localeCompare(a.updated ?? '') || (a.title ?? a.path).localeCompare(b.title ?? b.path));
+  const prompts = [...queue.map(q => q.doc), ...others];
+
+  if (prompts.length === 0) {
+    process.stdout.write('No prompts.\n');
+    return;
+  }
+
+  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(dim(`${prompts.length} prompts · ${summary}`) + '\n\n');
+
+  const maxSlug = Math.min(36, Math.max(...prompts.map(p => path.basename(p.path, '.md').length)));
+  for (let i = 0; i < prompts.length; i++) {
+    const p = prompts[i];
+    const slug = path.basename(p.path, '.md').padEnd(maxSlug);
+    const marker = i === 0 && p.status === 'pending' ? green('[NEXT]') : '      ';
+    const status = `[${(p.status ?? 'unknown').toUpperCase()}]`;
+    process.stdout.write(`  ${marker} ${slug} ${status}\n`);
+  }
+}
+
 // Resolve a prompt's "target plan" for `prompts list --verbose`. Order:
 //   1. frontmatter `related_plans:` (first entry — assumed plan slug)
 //   2. frontmatter `parent_plan:`

package/src/render.mjs

@@ -360,7 +360,7 @@ export function renderBriefing(index, config) {
   try {
     const staleLeases = findStaleLeases(config);
     if (staleLeases.length > 0) {
-      lines.push(yellow(`Stuck in-session: ${staleLeases.length} (>1d or dead pid, run \`dotmd release --stale\`)`));
+      lines.push(yellow(`Stuck in-session: ${staleLeases.length} (>4h or dead same-host pid, run \`dotmd release --stale\`)`));
     }
   } catch {}
 
@@ -376,6 +376,80 @@ export function renderCheck(index, config, opts = {}) {
   return defaultRenderer(index);
 }
 
+export function classifyIssueAction(issue) {
+  const message = issue?.message ?? '';
+  const file = issue?.path ?? '<file>';
+
+  if (/Missing frontmatter `status`/.test(message)) {
+    return { action: `dotmd bulk-tag ${file}`, fixable: false, label: 'missing status' };
+  }
+  if (/Missing frontmatter `updated`/.test(message) || /frontmatter `updated: .*` is behind git history/.test(message)) {
+    return { action: 'dotmd touch --git', fixable: true, label: 'dates' };
+  }
+  if (/`(?:module|surface):` \(singular\) is deprecated/.test(message) || /camelCase|nextStep|currentState|auditLevel/.test(message)) {
+    return { action: 'dotmd lint --fix', fixable: true, label: 'frontmatter migrations' };
+  }
+  if (/Unknown surface/.test(message)) {
+    return { action: 'dotmd surfaces', fixable: false, label: 'taxonomy' };
+  }
+  if (/Glossary config points at section|Glossary file configured/.test(message)) {
+    return { action: 'edit dotmd.config.mjs glossary.path/glossary.section', fixable: false, label: 'glossary config' };
+  }
+  if (/under `.*\/` but `status: .*` is not an archive status/.test(message)) {
+    return { action: message.match(/Run `([^`]+)`/)?.[1] ?? `dotmd set archived ${file}`, fixable: true, label: 'archive drift' };
+  }
+  if (/`status: .*` but file is a direct child/.test(message)) {
+    return { action: `dotmd archive ${file}`, fixable: true, label: 'archive drift' };
+  }
+  if (/`current_state` is \d+ chars|`next_step` is \d+ chars/.test(message)) {
+    return { action: 'dotmd doctor --frontmatter-fix', fixable: true, label: 'long frontmatter' };
+  }
+  if (/`modules` is required/.test(message)) {
+    return { action: `edit ${file} modules: or run dotmd lint --fix if scaffolded empty`, fixable: false, label: 'module metadata' };
+  }
+  if (/entry `.*` does not resolve|body link `.*` does not resolve/.test(message)) {
+    return { action: 'dotmd fix-refs --dry-run', fixable: true, label: 'references' };
+  }
+
+  return { action: `edit ${file}`, fixable: false, label: 'manual review' };
+}
+
+export function renderManualFixes(index) {
+  const issues = [...(index.errors ?? []), ...(index.warnings ?? [])];
+  const groups = new Map();
+  for (const issue of issues) {
+    const item = classifyIssueAction(issue);
+    const key = `${item.fixable ? 'fixable' : 'manual'}:${item.action}`;
+    if (!groups.has(key)) groups.set(key, { ...item, paths: new Set() });
+    groups.get(key).paths.add(issue.path);
+  }
+  if (groups.size === 0) return '';
+
+  const manual = [...groups.values()].filter(g => !g.fixable);
+  const fixable = [...groups.values()].filter(g => g.fixable);
+  const lines = [];
+
+  if (fixable.length > 0) {
+    lines.push('Fixable actions');
+    for (const group of fixable) {
+      const count = group.paths.size;
+      lines.push(`- ${group.action} (${count} ${count === 1 ? 'file' : 'files'}: ${[...group.paths].slice(0, 3).join(', ')}${count > 3 ? ', ...' : ''})`);
+    }
+    lines.push('');
+  }
+
+  if (manual.length > 0) {
+    lines.push('Manual fixes remaining');
+    for (const group of manual) {
+      const count = group.paths.size;
+      lines.push(`- ${group.action} (${count} ${count === 1 ? 'file' : 'files'}: ${[...group.paths].slice(0, 3).join(', ')}${count > 3 ? ', ...' : ''})`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
 function _renderCheck(index, opts = {}) {
   const { errorsOnly, noCollapse, verbose } = opts;
   const lines = ['Check', ''];
@@ -390,6 +464,10 @@ function _renderCheck(index, opts = {}) {
       lines.push(`- ${issue.path}: ${issue.message}`);
     }
     lines.push('');
+    const actions = renderManualFixes({ errors: index.errors, warnings: [] }).trimEnd();
+    if (actions) {
+      lines.push(actions);
+    }
   }
 
   // Warnings: terse by default — print count + pointer. The full per-doc list
@@ -415,7 +493,7 @@ function _renderCheck(index, opts = {}) {
       }
       lines.push('');
     } else {
-      lines.push(dim(`Run \`dotmd check --verbose\` for per-doc detail, or \`dotmd doctor\` to auto-fix where possible.`));
+      lines.push(dim(`Run \`dotmd check --verbose\` for per-doc detail. \`dotmd doctor\` auto-fixes supported issues; remaining issues need the suggested manual command.`));
       lines.push('');
     }
   }

package/src/runlist.mjs

@@ -45,12 +45,7 @@ function resolveHubInput(input, config) {
 // Read a hub plan's `runlist:` and resolve each entry to a repo-relative path
 // plus its current status. Missing files are reported with `missing: true`;
 // callers decide how to render them. Pure: no IO beyond file reads.
-function readRunlistChildren(hubAbsPath, config) {
-  const raw = readFileSync(hubAbsPath, 'utf8');
-  const { frontmatter: fmRaw } = extractFrontmatter(raw);
-  const fm = parseSimpleFrontmatter(fmRaw);
-  const refs = normalizeStringList(fm.runlist);
-
+function resolveRunlistRefs(refs, hubAbsPath, config) {
   const hubDir = path.dirname(hubAbsPath);
   const out = [];
   for (const ref of refs) {
@@ -79,6 +74,45 @@ function readRunlistChildren(hubAbsPath, config) {
   return out;
 }
 
+function detectBodyRunlistRefs(body) {
+  if (!body) return [];
+  const sectionRe = /^##\s+(Order of operations|Runlist|Execution order|Implementation order|Plan order)\s*$/gim;
+  const refs = [];
+  let match;
+  while ((match = sectionRe.exec(body)) !== null) {
+    const start = match.index + match[0].length;
+    const rest = body.slice(start);
+    const next = rest.search(/^##\s+/m);
+    const section = next >= 0 ? rest.slice(0, next) : rest;
+
+    const linkRe = /\[[^\]]+\]\(([^)]+\.md(?:#[^)]+)?)\)/g;
+    let link;
+    while ((link = linkRe.exec(section)) !== null) refs.push(link[1]);
+
+    const checklistRe = /^\s*[-*]\s+\[[ xX]\]\s+([^\s)]+\.md(?:#[^\s)]+)?)/gm;
+    let item;
+    while ((item = checklistRe.exec(section)) !== null) refs.push(item[1]);
+  }
+  return [...new Set(refs)];
+}
+
+function readRunlistChildren(hubAbsPath, config) {
+  const raw = readFileSync(hubAbsPath, 'utf8');
+  const { frontmatter: fmRaw, body } = extractFrontmatter(raw);
+  const fm = parseSimpleFrontmatter(fmRaw);
+  const refs = normalizeStringList(fm.runlist);
+
+  if (refs.length > 0) {
+    return { children: resolveRunlistRefs(refs, hubAbsPath, config), source: 'frontmatter' };
+  }
+
+  const bodyRefs = detectBodyRunlistRefs(body);
+  return {
+    children: resolveRunlistRefs(bodyRefs, hubAbsPath, config),
+    source: bodyRefs.length > 0 ? 'body' : 'empty',
+  };
+}
+
 const STATUS_TAG_COLORS = {
   'in-session': (s) => bold(red(s)),
   'active': green,
@@ -100,9 +134,12 @@ function renderRunlist(hubRepoPath, children, opts = {}) {
   const lines = [];
   lines.push(bold(`runlist: ${hubRepoPath}`));
   if (children.length === 0) {
-    lines.push(dim('  (empty — add child plan paths to the hub plan\'s `runlist:` field)'));
+    lines.push(dim('  (empty — add child plan paths to the hub plan\'s `runlist:` field, or add markdown links under `## Order of operations`)'));
     return lines.join('\n') + '\n';
   }
+  if (opts.source === 'body') {
+    lines.push(dim('  (from body links — add these paths to frontmatter `runlist:` to make the order canonical)'));
+  }
 
   const archiveStatuses = opts.archiveStatuses ?? new Set(['archived']);
   let nextPicked = false;
@@ -144,18 +181,20 @@ export async function runRunlist(argv, config, opts = {}) {
   if (!hubAbs) die(`Hub plan not found: ${hubInput}`);
   const hubRepoPath = toRepoPath(hubAbs, config.repoRoot);
 
-  const children = readRunlistChildren(hubAbs, config);
+  const runlist = readRunlistChildren(hubAbs, config);
+  const { children, source } = runlist;
   const archiveStatuses = config.lifecycle?.archiveStatuses ?? new Set(['archived']);
 
   if (sub === 'show') {
     if (json) {
       process.stdout.write(JSON.stringify({
         hub: hubRepoPath,
+        source,
         children,
       }, null, 2) + '\n');
       return;
     }
-    process.stdout.write(renderRunlist(hubRepoPath, children, { archiveStatuses }));
+    process.stdout.write(renderRunlist(hubRepoPath, children, { archiveStatuses, source }));
     return;
   }