dotmd-cli 0.36.3 → 0.38.0

package/bin/dotmd.mjs

@@ -5,6 +5,7 @@ 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 { recordCliInvocation } from '../src/journal.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -41,7 +42,7 @@ Analyze:
 
 Validate & Fix:
   check [--fix] [--errors-only] [--json]  Validate frontmatter and references
-  doctor [--dry-run]                Auto-fix everything: refs, lint, dates, index
+  doctor [--apply]                  Auto-fix everything: refs, lint, dates, index (preview by default)
   lint [--fix]                      Check and auto-fix frontmatter issues
   fix-refs [--dry-run]              Auto-fix broken reference paths + body links
 
@@ -69,6 +70,8 @@ Setup:
   statuses [list|add|set|remove|migrate]  Manage per-project status taxonomy
   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]
+                                    View opt-in JSONL command journal (enable: DOTMD_JOURNAL=1 or journal: true)
 
 Global Options:
   --config <path>        Explicit config file path
@@ -95,6 +98,39 @@ Add to your shell config:
   bash: eval "$(dotmd completions bash)"
   zsh:  eval "$(dotmd completions zsh)"`,
 
+  journal: `dotmd journal — view opt-in command-usage journal
+
+dotmd's primary user is an agent (per docs/audit-beyond-platform.md F17),
+but the CLI gives no usage signal by default. Turn on the journal and every
+invocation appends one JSONL line to .dotmd/journal.jsonl with argv, exit
+code, elapsed ms, session id, and (on error) a single-line err message.
+
+Enable:
+  - env:    DOTMD_JOURNAL=1
+  - config: \`export const journal = true;\` in dotmd.config.mjs
+
+The env var beats config (DOTMD_JOURNAL=0 forces off). The journal is
+default-off so non-agent users don't pay the size/PII cost.
+
+Reader options:
+  --tail N            Last N entries (default: 20 when no other filter)
+  --errors            Only non-zero exits
+  --session <id>      Only entries from one session
+  --since <iso>       Only entries with ts >= iso
+  --by-command        Group by argv[0]: count, median ms, error rate
+  --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.
+
+Examples:
+  DOTMD_JOURNAL=1 dotmd plans
+  dotmd journal --tail 5
+  dotmd journal --errors
+  dotmd journal --by-command
+  dotmd journal --since 2025-01-01 --json`,
+
   query: `dotmd query — filtered document search
 
 Filters:
@@ -204,6 +240,11 @@ Options:
   --errors-only          Show only errors, suppress warnings
   --fix                  Auto-fix broken refs, lint issues, and regenerate index
   --json                 Output errors and warnings as JSON
+  --no-collapse          Show every warning per-doc (since 0.37.0, high-frequency
+                         auto-fixable warning categories — singular module/surface
+                         deprecations, updated-behind-git — are collapsed into a
+                         one-line summary with the bulk-fix command). --json output
+                         is unchanged regardless.
   --dry-run, -n          Preview fixes without writing (with --fix)`,
 
   archive: `dotmd archive <file> — archive a document
@@ -342,7 +383,10 @@ Runs in sequence: fix broken references, lint --fix, sync dates from
 git, regenerate index, then show remaining issues.
 
 Modes:
-  (default)              Auto-fix pass (writes by default; honors --dry-run)
+  (default)              Auto-fix pass — previews by default since 0.37.0
+                         (F4). Use --apply (alias --yes) to actually write;
+                         explicit --dry-run still wins over --apply if both
+                         are passed (safety prevails).
   --statuses             Read-only diagnostic: detect overloaded status
                          buckets where one status holds plans pursuing
                          multiple distinct unstuck-actions. Suggests how
@@ -374,7 +418,9 @@ Modes:
                          in their Version History would be misleading).
   --migrate-template --json  Machine-readable result.
 
-Use --dry-run (-n) to preview all changes without writing anything.`,
+--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.`,
 
   'fix-refs': `dotmd fix-refs — auto-fix broken reference paths
 
@@ -589,6 +635,10 @@ Subcommands:
   use <file-or-slug>         Consume a specific prompt (same as next, but
                              targets the named prompt instead of picking oldest)
   archive <file-or-slug>     Archive a prompt without printing its body
+  shelve <file-or-slug>      Park a prompt (status → shelved): kept in list,
+                             hidden from hud/briefing pending surfaces, skipped
+                             by \`prompts next\`. Use for "saved but not next."
+  unshelve <file-or-slug>    Move a shelved prompt back to pending.
   new <slug> [body]          Create a new prompt (alias for
                              \`dotmd new prompt <slug> [body]\`)
 
@@ -596,7 +646,7 @@ Subcommands:
 slug matching a prompt basename, or a unique substring of a prompt
 path. Ambiguous substrings error with the candidate list.
 
-Default prompt statuses: pending, claimed, archived.
+Default prompt statuses: pending, shelved, claimed, archived.
 
 Examples:
   dotmd prompts                        # pending prompts (default)
@@ -768,6 +818,7 @@ async function main() {
   const verbose = args.includes('--verbose');
 
   const config = await resolveConfig(process.cwd(), explicitConfig);
+  _resolvedConfig = config;
 
   // Init — runInit re-resolves the config from disk internally (after any
   // starter-config write), so we don't need to pre-pass it.
@@ -856,6 +907,7 @@ async function main() {
 
   // Lifecycle commands
   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 === '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.'); }
@@ -871,7 +923,22 @@ 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 === 'doctor') { const { runDoctor } = await import('../src/doctor.mjs'); runDoctor(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
+    // --apply (safety prevails). The F4 flip applies ONLY to the default
+    // 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 explicitApply = args.includes('--apply') || args.includes('--yes');
+    const explicitDryRun = args.includes('--dry-run') || args.includes('-n');
+    const doctorDryRun = subMode ? dryRun : (explicitDryRun || !explicitApply);
+    const filtered = restArgs.filter(a => a !== '--apply' && a !== '--yes');
+    const { runDoctor } = await import('../src/doctor.mjs');
+    runDoctor(filtered, config, { dryRun: doctorDryRun });
+    return;
+  }
   if (command === 'statuses') { const { runStatuses } = await import('../src/statuses.mjs'); await runStatuses(restArgs, config, { dryRun, type: typeArg }); return; }
 
   // All remaining commands need the index + render modules
@@ -931,6 +998,7 @@ async function main() {
   if (command === 'check') {
     const fix = args.includes('--fix');
     const errorsOnly = args.includes('--errors-only');
+    const noCollapse = args.includes('--no-collapse');
 
     if (fix) {
       // Auto-fix: broken refs, then lint, then rebuild index
@@ -961,7 +1029,7 @@ async function main() {
           passed: freshIndex.errors.length === 0,
         }, null, 2) + '\n');
       } else {
-        process.stdout.write('\n' + renderCheck(freshIndex, config, { errorsOnly }));
+        process.stdout.write('\n' + renderCheck(freshIndex, config, { errorsOnly, noCollapse }));
       }
       if (freshIndex.errors.length > 0) process.exitCode = 1;
       return;
@@ -980,7 +1048,7 @@ async function main() {
       return;
     }
 
-    process.stdout.write(renderCheck(index, config, { errorsOnly }));
+    process.stdout.write(renderCheck(index, config, { errorsOnly, noCollapse }));
     if (index.errors.length > 0) process.exitCode = 1;
     return;
   }
@@ -1144,7 +1212,31 @@ async function main() {
   die(`Unknown command: ${command}\n\nRun \`dotmd --help\` for available commands.`);
 }
 
-main().catch(err => {
-  process.stderr.write(`${err.message}\n`);
-  process.exitCode = 1;
-});
+// F17a: opt-in JSONL journal of every CLI invocation. The dispatch tail
+// records argv / exit / elapsed-ms / err once main() either returns or
+// throws — config is captured into the module-level _resolvedConfig the
+// moment it's loaded, so even early dispatcher errors (after config) get
+// journaled.
+let _resolvedConfig = null;
+const _startMs = Date.now();
+const _invocationArgs = process.argv.slice(2);
+
+function _journalExit(err) {
+  try {
+    recordCliInvocation({
+      config: _resolvedConfig,
+      startMs: _startMs,
+      args: _invocationArgs,
+      err,
+      version: pkg.version,
+    });
+  } catch { /* never break exit on journal failure */ }
+}
+
+main()
+  .then(() => { _journalExit(null); })
+  .catch(err => {
+    process.stderr.write(`${err.message}\n`);
+    process.exitCode = 1;
+    _journalExit(err);
+  });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.36.3",
+  "version": "0.38.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/check-collapse.mjs

@@ -0,0 +1,75 @@
+// F13 (0.37.0): collapse high-frequency auto-fixable `dotmd check` warnings
+// into one-line remediation hints. Without this, bulk-fixable noise (43
+// `updated behind git history`, N singular-key deprecations) drowns out
+// structural findings in the per-doc list — and forces the reader to
+// reconstruct the fix command per category.
+//
+// Each category names the message regex to match, a short label for the
+// summary line, and the exact `dotmd …` command that bulk-fixes it.
+
+const COLLAPSE_THRESHOLD = 3;
+
+const CATEGORIES = [
+  {
+    key: 'updated-behind-git',
+    match: /^frontmatter `updated:.*` is behind git history/,
+    label: 'docs have `updated` behind git history',
+    fix: 'dotmd touch --git',
+  },
+  {
+    key: 'singular-module',
+    match: /^`module:` \(singular\) is deprecated/,
+    label: 'docs use deprecated singular `module:`',
+    fix: 'dotmd lint --fix',
+  },
+  {
+    key: 'singular-surface',
+    match: /^`surface:` \(singular\) is deprecated/,
+    label: 'docs use deprecated singular `surface:`',
+    fix: 'dotmd lint --fix',
+  },
+];
+
+function categoryFor(message) {
+  for (const cat of CATEGORIES) {
+    if (cat.match.test(message)) return cat;
+  }
+  return null;
+}
+
+// Split warnings into per-doc passthrough lines and collapsed summary buckets.
+// A category that hits ≥COLLAPSE_THRESHOLD warnings is summarized; below the
+// threshold each warning falls through as a normal per-doc line (small counts
+// don't gain from collapse and lose path information).
+export function categorizeWarnings(warnings) {
+  const buckets = new Map();
+  const orphans = [];
+
+  for (const w of warnings) {
+    const cat = categoryFor(w.message);
+    if (!cat) {
+      orphans.push(w);
+      continue;
+    }
+    if (!buckets.has(cat.key)) buckets.set(cat.key, { cat, items: [] });
+    buckets.get(cat.key).items.push(w);
+  }
+
+  const collapsed = [];
+  const passthrough = [...orphans];
+
+  for (const { cat, items } of buckets.values()) {
+    if (items.length >= COLLAPSE_THRESHOLD) {
+      collapsed.push({ key: cat.key, label: cat.label, fix: cat.fix, count: items.length });
+    } else {
+      passthrough.push(...items);
+    }
+  }
+
+  passthrough.sort((a, b) => a.path.localeCompare(b.path));
+  collapsed.sort((a, b) => b.count - a.count || a.key.localeCompare(b.key));
+
+  return { passthrough, collapsed };
+}
+
+export const _internalForTest = { COLLAPSE_THRESHOLD, CATEGORIES };

package/src/commands.mjs

@@ -7,5 +7,5 @@ export const KNOWN_COMMANDS = [
   'focus', 'query', 'plans', 'prompts', 'stale', 'actionable', 'index', 'pickup', 'release', 'finish', 'status', 'archive', 'bulk', 'bulk-tag', 'touch', 'doctor',
   'unblocks', 'health', 'glossary', 'modules', 'module',
   'fix-refs', 'lint', 'rename', 'migrate', 'notion', 'export', 'summary',
-  'watch', 'diff', 'new', 'init', 'completions', 'statuses',
+  'watch', 'diff', 'new', 'init', 'completions', 'statuses', 'journal',
 ];

package/src/completions.mjs

@@ -3,7 +3,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', 'finish', 'status', 'archive', 'bulk', 'touch', 'doctor', 'lint', 'rename', 'migrate',
-  'fix-refs', 'notion', 'export', 'summary', 'watch', 'diff', 'init', 'new', 'completions',
+  'fix-refs', 'notion', 'export', 'summary', 'watch', 'diff', 'init', 'new', 'completions', 'journal',
 ];
 
 const GLOBAL_FLAGS = ['--config', '--dry-run', '--verbose', '--root', '--type', '--help', '--version'];
@@ -47,6 +47,7 @@ const COMMAND_FLAGS = {
   summary: ['--model', '--max-tokens', '--json'],
   context: ['--summarize', '--model', '--json'],
   touch: ['--git'],
+  journal: ['--tail', '--errors', '--session', '--since', '--by-command', '--json'],
 };
 
 function bashCompletion() {

package/src/config.mjs

@@ -36,8 +36,8 @@ const DEFAULTS = {
       staleDays: { draft: 30, active: 14, review: 14 },
     },
     prompt: {
-      statuses: ['pending', 'claimed', 'archived'],
-      context: { expanded: ['pending'], listed: [], counted: ['claimed', 'archived'] },
+      statuses: ['pending', 'shelved', 'claimed', 'archived'],
+      context: { expanded: ['pending'], listed: ['shelved'], counted: ['claimed', 'archived'] },
       staleDays: { pending: 30 },
     },
   },
@@ -98,6 +98,10 @@ const DEFAULTS = {
 
   notion: null,
 
+  // Opt-in JSONL command journal at .dotmd/journal.jsonl. Default off — agents
+  // and users who want usage observability flip this on (or set DOTMD_JOURNAL=1).
+  journal: false,
+
   presets: {
     stale: ['--status', 'active,ready,planned,blocked,scoping', '--stale', '--sort', 'updated', '--all'],
     actionable: ['--status', 'active,ready', '--has-next-step', '--sort', 'updated', '--all'],
@@ -483,6 +487,7 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     display: config.display,
     referenceFields: config.referenceFields,
     presets: config.presets,
+    journal: config.journal === true,
     hooks,
     configWarnings,
   };

package/src/doctor.mjs

@@ -53,7 +53,12 @@ export function runDoctor(argv, config, opts = {}) {
   }
 
   const { dryRun } = opts;
-  process.stdout.write(bold('dotmd doctor') + '\n\n');
+  // 0.37.0 (F4): the mode banner makes it impossible to mistake a preview run
+  // for a real one — and tells the user the exact flag that flips it.
+  const modeNote = dryRun
+    ? dim('[preview — run with --apply to write]')
+    : dim('[applying changes]');
+  process.stdout.write(bold('dotmd doctor') + ' ' + modeNote + '\n\n');
 
   // Step 1: Fix broken references
   process.stdout.write(bold('1. Fixing broken references...') + '\n');

package/src/journal-read.mjs

@@ -0,0 +1,88 @@
+import { existsSync } from 'node:fs';
+import {
+  readJournalEntries,
+  journalFilePath,
+  isJournalEnabled,
+} from './journal.mjs';
+import { dim, green, red } from './color.mjs';
+
+function parseArgs(argv) {
+  const opts = { tail: null, errorsOnly: false, sessionFilter: null, since: null, byCommand: false, asJson: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--tail') {
+      const n = parseInt(argv[++i], 10);
+      opts.tail = Number.isFinite(n) && n > 0 ? n : 20;
+    } else if (a === '--errors') opts.errorsOnly = true;
+    else if (a === '--session' && argv[i + 1]) opts.sessionFilter = argv[++i];
+    else if (a === '--since' && argv[i + 1]) opts.since = argv[++i];
+    else if (a === '--by-command') opts.byCommand = true;
+    else if (a === '--json') opts.asJson = true;
+  }
+  // Default to last 20 when no view flag is given.
+  if (opts.tail === null && !opts.errorsOnly && !opts.sessionFilter
+      && !opts.since && !opts.byCommand) {
+    opts.tail = 20;
+  }
+  return opts;
+}
+
+export function runJournal(argv, config) {
+  const file = journalFilePath(config);
+  if (!existsSync(file)) {
+    if (!isJournalEnabled(config)) {
+      process.stderr.write(
+        'Journal is opt-in. Enable with `DOTMD_JOURNAL=1` (env) or `journal: true` (in dotmd.config.mjs).\n',
+      );
+      return;
+    }
+    process.stderr.write(`No journal entries yet at ${file}.\n`);
+    return;
+  }
+
+  const opts = parseArgs(argv);
+  let entries = readJournalEntries(config);
+  if (opts.errorsOnly) entries = entries.filter(e => e.exit !== 0);
+  if (opts.sessionFilter) entries = entries.filter(e => e.sid === opts.sessionFilter);
+  if (opts.since) entries = entries.filter(e => typeof e.ts === 'string' && e.ts >= opts.since);
+
+  if (opts.byCommand) {
+    const groups = new Map();
+    for (const e of entries) {
+      const cmd = (e.argv && e.argv[0]) || '(none)';
+      if (!groups.has(cmd)) groups.set(cmd, []);
+      groups.get(cmd).push(e);
+    }
+    const rows = [...groups.entries()].map(([cmd, list]) => {
+      const total = list.length;
+      const errors = list.filter(e => e.exit !== 0).length;
+      const times = list.map(e => e.ms ?? 0).sort((a, b) => a - b);
+      const median = times.length ? times[Math.floor(times.length / 2)] : 0;
+      return { cmd, total, errors, median };
+    }).sort((a, b) => b.total - a.total);
+
+    if (opts.asJson) {
+      process.stdout.write(JSON.stringify(rows, null, 2) + '\n');
+      return;
+    }
+    for (const r of rows) {
+      const errPart = r.errors > 0 ? ` ${red(`${r.errors} err`)}` : '';
+      process.stdout.write(`${r.cmd.padEnd(20)} ${String(r.total).padStart(4)}× median ${r.median}ms${errPart}\n`);
+    }
+    return;
+  }
+
+  if (opts.tail) entries = entries.slice(-opts.tail);
+
+  if (opts.asJson) {
+    process.stdout.write(JSON.stringify(entries, null, 2) + '\n');
+    return;
+  }
+
+  for (const e of entries) {
+    const argvStr = Array.isArray(e.argv) ? e.argv.join(' ') : '';
+    const exitPart = e.exit === 0 ? green('ok') : red(`exit ${e.exit}`);
+    const errPart = e.err ? ` ${dim(`(${e.err})`)}` : '';
+    process.stdout.write(`[${e.ts}] ${argvStr} (${exitPart}, ${e.ms ?? '?'}ms)${errPart}\n`);
+  }
+}

package/src/journal.mjs

@@ -0,0 +1,98 @@
+import { existsSync, mkdirSync, appendFileSync, statSync, renameSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { currentSessionId } from './lease.mjs';
+
+const JOURNAL_DIR = '.dotmd';
+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;
+
+export function isJournalEnabled(config) {
+  if (process.env.DOTMD_JOURNAL === '1') return true;
+  if (process.env.DOTMD_JOURNAL === '0') return false;
+  return config?.journal === true;
+}
+
+export function journalFilePath(config) {
+  return path.join(config.repoRoot, JOURNAL_DIR, JOURNAL_FILE);
+}
+
+export function journalBackupPath(config) {
+  return path.join(config.repoRoot, JOURNAL_DIR, JOURNAL_BACKUP);
+}
+
+function maybeRotate(file, config) {
+  if (!existsSync(file)) return;
+  let st;
+  try { st = statSync(file); } catch { return; }
+  if (st.size > ROTATE_SIZE_BYTES) {
+    try { renameSync(file, journalBackupPath(config)); } catch {}
+    return;
+  }
+  if (st.size === 0) return;
+  // Age check: only the first line's ts matters for "oldest entry" — cheap
+  // peek instead of streaming the whole file.
+  try {
+    const sample = readFileSync(file, 'utf8');
+    const nl = sample.indexOf('\n');
+    const first = nl >= 0 ? sample.slice(0, nl) : sample;
+    if (!first) return;
+    const obj = JSON.parse(first);
+    const t = new Date(obj.ts).getTime();
+    if (!Number.isNaN(t) && (Date.now() - t) > ROTATE_AGE_MS) {
+      try { renameSync(file, journalBackupPath(config)); } catch {}
+    }
+  } catch {}
+}
+
+export function appendJournalEntry(config, entry) {
+  if (!isJournalEnabled(config)) return;
+  if (!config?.repoRoot) return;
+  try {
+    const dir = path.join(config.repoRoot, JOURNAL_DIR);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    const file = journalFilePath(config);
+    maybeRotate(file, config);
+    // 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.
+    appendFileSync(file, JSON.stringify(entry) + '\n', { flag: 'a' });
+  } catch {
+    // Journal write must never break a command.
+  }
+}
+
+export function readJournalEntries(config) {
+  const file = journalFilePath(config);
+  if (!existsSync(file)) return [];
+  let raw;
+  try { raw = readFileSync(file, 'utf8'); } catch { return []; }
+  const out = [];
+  for (const line of raw.split('\n')) {
+    if (!line) continue;
+    try { out.push(JSON.parse(line)); } catch { /* skip malformed */ }
+  }
+  return out;
+}
+
+export function recordCliInvocation({ config, startMs, args, err, version }) {
+  if (!config) return;
+  const entry = {
+    ts: new Date().toISOString(),
+    sid: currentSessionId(),
+    pid: process.pid,
+    argv: args,
+    exit: process.exitCode ?? 0,
+    ms: Date.now() - startMs,
+    v: version,
+  };
+  if (err) {
+    // Normalize whitespace so multi-line error messages (e.g. unknown-command
+    // hints) render as a single line in `dotmd journal --tail`. Cap at 200
+    // chars so a stray stack trace can't bloat the journal.
+    const flat = String(err.message ?? err).replace(/\s+/g, ' ').trim();
+    entry.err = flat.length > 200 ? flat.slice(0, 197) + '...' : flat;
+  }
+  appendJournalEntry(config, entry);
+}

package/src/prompts.mjs

@@ -4,11 +4,11 @@ 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 { runArchive, runStatus } from './lifecycle.mjs';
 import { runNew } from './new.mjs';
 import { green, dim } from './color.mjs';
 
-const SUBCOMMANDS = new Set(['list', 'next', 'use', 'archive', 'new']);
+const SUBCOMMANDS = new Set(['list', 'next', 'use', 'archive', 'new', 'shelve', 'unshelve']);
 
 export async function runPrompts(argv, config, opts = {}) {
   const sub = argv[0];
@@ -19,11 +19,13 @@ export async function runPrompts(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);
+    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);
+    case 'shelve':   return runPromptsShelve(rest, config, opts);
+    case 'unshelve': return runPromptsUnshelve(rest, config, opts);
   }
 }
 
@@ -168,3 +170,17 @@ async function runPromptsNew(argv, config, opts = {}) {
   }
   return runNew(['prompt', ...argv], config, opts);
 }
+
+async function runPromptsShelve(argv, config, opts = {}) {
+  const input = argv.find(a => !a.startsWith('-'));
+  if (!input) die('Usage: dotmd prompts shelve <file-or-slug>');
+  const filePath = resolvePromptInput(input, config);
+  return runStatus([filePath, 'shelved'], config, opts);
+}
+
+async function runPromptsUnshelve(argv, config, opts = {}) {
+  const input = argv.find(a => !a.startsWith('-'));
+  if (!input) die('Usage: dotmd prompts unshelve <file-or-slug>');
+  const filePath = resolvePromptInput(input, config);
+  return runStatus([filePath, 'pending'], config, opts);
+}

package/src/render.mjs

@@ -5,6 +5,7 @@ import { extractFrontmatter } from './frontmatter.mjs';
 import { summarizeDocBody } from './ai.mjs';
 import { bold, red, yellow, green, dim } from './color.mjs';
 import { findStaleLeases } from './lease.mjs';
+import { categorizeWarnings } from './check-collapse.mjs';
 
 // Render `currentState` with an `(auto)` prefix when the value was body-scraped
 // rather than read from frontmatter. Lets a reader see at a glance which docs
@@ -376,7 +377,7 @@ export function renderCheck(index, config, opts = {}) {
 }
 
 function _renderCheck(index, opts = {}) {
-  const { errorsOnly } = opts;
+  const { errorsOnly, noCollapse } = opts;
   const lines = ['Check', ''];
   lines.push(`- docs scanned: ${index.docs.length}`);
   lines.push(`- errors: ${index.errors.length}`);
@@ -393,8 +394,18 @@ function _renderCheck(index, opts = {}) {
 
   if (!errorsOnly && index.warnings.length > 0) {
     lines.push(yellow('Warnings'));
-    for (const issue of index.warnings) {
-      lines.push(`- ${issue.path}: ${issue.message}`);
+    if (noCollapse) {
+      for (const issue of index.warnings) {
+        lines.push(`- ${issue.path}: ${issue.message}`);
+      }
+    } else {
+      const { passthrough, collapsed } = categorizeWarnings(index.warnings);
+      for (const issue of passthrough) {
+        lines.push(`- ${issue.path}: ${issue.message}`);
+      }
+      for (const sum of collapsed) {
+        lines.push(`- ${sum.count} ${sum.label} — run \`${sum.fix}\` to bulk-fix`);
+      }
     }
     lines.push('');
   }

package/src/validate.mjs

@@ -2,6 +2,7 @@ import path from 'node:path';
 import { asString, resolveRefPath, suggestCandidates } from './util.mjs';
 import { getGitLastModified, getGitLastModifiedBatch } from './git.mjs';
 import { toRepoPath } from './util.mjs';
+import { readLeases, isLeaseStale } from './lease.mjs';
 
 const NOW = new Date();
 
@@ -168,6 +169,30 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
     doc.warnings.push({ path: doc.path, level: 'warning', message: 'Archived plan missing `## Closeout` section.' });
   }
 
+  // F11: `status: in-session` plans should have a matching live lease. If the
+  // lease file has no entry, the previous session crashed without releasing;
+  // if the entry is stale (>24h), the holder is gone. Either way the validator
+  // is the only place that knows enough to suggest the exact unstuck command,
+  // because the lease infrastructure is otherwise invisible to `dotmd check`.
+  if (doc.status === 'in-session' && !config.lifecycle.skipWarningsFor.has(doc.status)) {
+    const leases = readLeases(config);
+    const lease = leases[doc.path];
+    if (!lease) {
+      doc.warnings.push({
+        path: doc.path,
+        level: 'warning',
+        message: `\`status: in-session\` but no active lease found (last session may have crashed without releasing). Run \`dotmd release ${doc.path}\` to clear, or \`dotmd status ${doc.path} active\` to re-queue.`,
+      });
+    } else if (isLeaseStale(lease)) {
+      const ageHours = Math.floor((Date.now() - new Date(lease.pickedUpAt).getTime()) / (1000 * 60 * 60));
+      doc.warnings.push({
+        path: doc.path,
+        level: 'warning',
+        message: `\`status: in-session\` but lease is stale (last touched ${ageHours}h ago, >24h threshold). Run \`dotmd release ${doc.path}\` to clear, or \`dotmd status ${doc.path} active\` to re-queue.`,
+      });
+    }
+  }
+
   // Archive drift: a doc with an archive-flagged status (`status: archived` by
   // default) whose parent dir is a "live" type-conventional location is
   // misplaced — `dotmd archive` would have moved it under `<that>/archiveDir/`.