dotmd-cli 0.37.0 → 0.38.1

package/README.md

@@ -128,7 +128,7 @@ Every document can have a `type` field in its frontmatter. Types determine which
 |------|---------|----------------|
 | `plan` | Execution plans | `in-session`, `active`, `planned`, `blocked`, `partial`, `paused`, `awaiting`, `queued-after`, `archived` |
 | `doc` | Design docs, specs, ADRs, RFCs, reference material | `draft`, `active`, `review`, `reference`, `deprecated`, `archived` |
-| `prompt` | Saved prompts that seed future Claude sessions | `pending`, `claimed`, `archived` |
+| `prompt` | Saved prompts that seed future Claude sessions | `pending`, `shelved`, `claimed`, `archived` |
 
 Documents without a `type` field use the global `statuses.order` from config.
 
@@ -206,7 +206,8 @@ dotmd glossary <term>        Look up domain terms + related docs
 dotmd watch [command]        Re-run a command on file changes
 dotmd diff [file]            Show changes since last updated date
 dotmd new <type> <name>      Create a new doc (type: doc, plan, or prompt)
-dotmd prompts [sub]          List, claim, or archive saved prompts
+dotmd prompts [sub]          Manage saved prompts (list, next, use, shelve, archive, new)
+dotmd journal [flags]        View opt-in command-usage journal (DOTMD_JOURNAL=1)
 dotmd init                   Create starter config + docs directory
 dotmd completions <shell>    Output shell completion script (bash, zsh)
 ```
@@ -300,15 +301,57 @@ Manage them with the `prompts` command family:
 ```bash
 dotmd prompts                     # list pending prompts (default)
 dotmd prompts list --all          # all statuses
-dotmd prompts next                # show + claim the oldest pending prompt (prints body)
-dotmd prompts use <file>          # claim a specific prompt (prints body, flips to claimed)
-dotmd prompts archive <file>      # archive a prompt
+dotmd prompts next                # print body of oldest pending + auto-archive (one-shot)
+dotmd prompts use <file>          # print body of a specific prompt + auto-archive
+dotmd prompts shelve <file>       # park a prompt (status → shelved): kept in list,
+                                  # hidden from hud/briefing, skipped by `next`
+dotmd prompts unshelve <file>     # move a shelved prompt back to pending
+dotmd prompts archive <file>      # archive without printing the body
 dotmd prompts new <name> [body]   # alias for `dotmd new prompt`
 ```
 
-`dotmd hud` surfaces pending prompts on session start (alongside held leases), so a saved prompt acts as a self-addressed reminder: write it now, the next session sees it.
+`dotmd hud` surfaces pending prompts on session start (alongside held leases), so a saved prompt acts as a self-addressed reminder: write it now, the next session sees it. Shelved prompts are kept out of the SessionStart surface — use them for "saved but not next."
 
-Statuses: `pending` (drafted, awaiting a session), `claimed` (consumed by a session), `archived`.
+Statuses: `pending` (drafted, awaiting a session), `shelved` (saved but parked — visible in `prompts list`, hidden from `hud`/`briefing`, skipped by `prompts next`), `archived` (consumed or filed away). `claimed` is reserved for a future "in-flight" state but is currently a synonym for archived in practice.
+
+### Command Journal (opt-in)
+
+dotmd's primary user is an agent. Every CLI invocation can be journaled
+to `.dotmd/journal.jsonl` so agents (and humans) can see what got run,
+what failed, and how long things took — observability that turns every
+session into data the next design call can use.
+
+Default off. Enable with either:
+
+```bash
+export DOTMD_JOURNAL=1                                # env var
+# or, in dotmd.config.mjs:
+export const journal = true;                          # config flag
+```
+
+(`DOTMD_JOURNAL=0` forces off even when the config opts in.)
+
+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.
+
+Read it back with `dotmd journal`:
+
+```bash
+dotmd journal --tail 20            # last N entries (default)
+dotmd journal --errors             # only non-zero exits
+dotmd journal --session <id>       # filter by session id
+dotmd journal --since 2026-05-01   # filter by ts
+dotmd journal --by-command         # group by argv[0]: count, median ms, errors
+dotmd journal --json               # raw entries as a JSON array
+```
+
+The journal is local-only and gitignored (or should be — `.dotmd/` is
+typically already ignored). Default-off keeps the surface clean for
+users who don't want the storage / PII tradeoff.
 
 ### Check & Fix
 
@@ -620,6 +663,15 @@ either is silent.
 `⚠ N stuck leases` line when stale leases exist, with a
 `dotmd release --stale` suggestion.
 
+`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
+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
+sessions hold real leases, so the warning only fires on actual
+divergence.
+
 ### Touch
 
 ```bash

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);
@@ -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:
@@ -599,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]\`)
 
@@ -606,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)
@@ -778,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.
@@ -866,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.'); }
@@ -1170,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.37.0",
+  "version": "0.38.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

@@ -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/index.mjs

@@ -7,14 +7,23 @@ import { validateDoc, validatePlanShape, validateDocShape, checkBidirectionalRef
 import { checkIndex } from './index-file.mjs';
 import { checkClaudeCommands } from './claude-commands.mjs';
 
-export function buildIndex(config) {
-  const docs = collectDocFiles(config).map(f => parseDocFile(f, config));
-  // Per-file validation (validateDoc) ran during parse without sibling
-  // visibility. Now that the full index is materialized, enrich
-  // unresolved-ref entries with "Did you mean..." candidates drawn from the
-  // index — mutates doc.errors/doc.warnings in place so the aggregations
-  // below pick up the enriched messages.
-  enrichRefErrorSuggestions(docs, config);
+// `fast: true` skips every pass that only produces warnings/errors — the
+// rendered index file consumes only status/title/snapshot/etc., not the
+// validation output. Use it from `regenIndex` (post-mutation index refresh)
+// where validation has already run elsewhere (or will, next time the user
+// runs `dotmd check`). Saves the full-repo `git log` scan in
+// `checkGitStaleness` plus the bidirectional ref walk + claude-commands check.
+export function buildIndex(config, opts = {}) {
+  const { fast = false } = opts;
+  const docs = collectDocFiles(config).map(f => parseDocFile(f, config, { fast }));
+  if (!fast) {
+    // Per-file validation (validateDoc) ran during parse without sibling
+    // visibility. Now that the full index is materialized, enrich
+    // unresolved-ref entries with "Did you mean..." candidates drawn from the
+    // index — mutates doc.errors/doc.warnings in place so the aggregations
+    // below pick up the enriched messages.
+    enrichRefErrorSuggestions(docs, config);
+  }
   const warnings = [];
   const errors = [];
 
@@ -23,7 +32,7 @@ export function buildIndex(config) {
     errors.push(...doc.errors);
   }
 
-  if (config.hooks.validate) {
+  if (!fast && config.hooks.validate) {
     const ctx = { config, allDocs: docs, repoRoot: config.repoRoot };
     for (const doc of docs) {
       try {
@@ -65,20 +74,22 @@ export function buildIndex(config) {
     }
   }
 
-  if (config.indexPath) {
-    const indexCheck = checkIndex(transformedDocs, config);
-    warnings.push(...indexCheck.warnings);
-    errors.push(...indexCheck.errors);
-  }
+  if (!fast) {
+    if (config.indexPath) {
+      const indexCheck = checkIndex(transformedDocs, config);
+      warnings.push(...indexCheck.warnings);
+      errors.push(...indexCheck.errors);
+    }
 
-  const refCheck = checkBidirectionalReferences(transformedDocs, config);
-  warnings.push(...refCheck.warnings);
+    const refCheck = checkBidirectionalReferences(transformedDocs, config);
+    warnings.push(...refCheck.warnings);
 
-  const gitWarnings = checkGitStaleness(transformedDocs, config);
-  warnings.push(...gitWarnings);
+    const gitWarnings = checkGitStaleness(transformedDocs, config);
+    warnings.push(...gitWarnings);
 
-  const claudeWarnings = checkClaudeCommands(config.repoRoot);
-  warnings.push(...claudeWarnings);
+    const claudeWarnings = checkClaudeCommands(config.repoRoot);
+    warnings.push(...claudeWarnings);
+  }
 
   return {
     generatedAt: new Date().toISOString(),
@@ -122,7 +133,8 @@ function walkMarkdownFiles(directory, files, excludedDirs, skipPaths, seen = new
   }
 }
 
-export function parseDocFile(filePath, config) {
+export function parseDocFile(filePath, config, opts = {}) {
+  const { fast = false } = opts;
   const relativePath = toRepoPath(filePath, config.repoRoot);
   const raw = readFileSync(filePath, 'utf8');
   const { frontmatter, body } = extractFrontmatter(raw);
@@ -250,8 +262,10 @@ export function parseDocFile(filePath, config) {
     doc.warnings.push({ path: relativePath, level: 'warning', message: w.message });
   }
 
-  validateDoc(doc, parsedFrontmatter, headingTitle, config);
-  validatePlanShape(doc, body, parsedFrontmatter, config);
-  validateDocShape(doc, body, parsedFrontmatter, config);
+  if (!fast) {
+    validateDoc(doc, parsedFrontmatter, headingTitle, config);
+    validatePlanShape(doc, body, parsedFrontmatter, config);
+    validateDocShape(doc, body, parsedFrontmatter, config);
+  }
   return doc;
 }

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/lifecycle.mjs

@@ -32,7 +32,11 @@ function findFileRoot(filePath, config) {
 export function regenIndex(config) {
   if (!config.indexPath) return;
   try {
-    const index = buildIndex(config);
+    // Fast path: skip validation/git-staleness/ref-checking — the rendered
+    // index file only consumes status/title/snapshot/etc. Validation runs on
+    // explicit `dotmd check` / `dotmd index`. This keeps lifecycle commands
+    // snappy on repos with huge git history or heavy `validate` hooks.
+    const index = buildIndex(config, { fast: true });
     writeIndex(renderIndexFile(index, config), config);
   } catch (err) {
     warn(`Could not regenerate index (run \`dotmd index\`): ${err.message}`);

package/src/new.mjs

@@ -230,13 +230,19 @@ export async function runNew(argv, config, opts = {}) {
   // Resolve template (by type name, falls back to lookup)
   const template = resolveTemplate(typeName, config);
 
-  // Validate status (template default first, then per-type list, then 'active')
+  // Validate status. The template's `defaultStatus` is only used when it's
+  // actually valid in the user's per-type config — otherwise fall back to the
+  // first valid type status. This avoids the "Invalid status `active` for type
+  // `doc`" loop when a project overrides doc statuses to exclude 'active'.
   if (!status) {
-    if (typeof template === 'object' && template.defaultStatus) {
-      status = template.defaultStatus;
+    const typeStatuses = config.typeStatuses?.get(typeName);
+    const tmplDefault = (typeof template === 'object' && template.defaultStatus) ? template.defaultStatus : null;
+    if (tmplDefault && (!typeStatuses || typeStatuses.size === 0 || typeStatuses.has(tmplDefault))) {
+      status = tmplDefault;
+    } else if (typeStatuses && typeStatuses.size > 0) {
+      status = [...typeStatuses][0];
     } else {
-      const typeStatuses = config.typeStatuses?.get(typeName);
-      status = typeStatuses && typeStatuses.size > 0 ? [...typeStatuses][0] : 'active';
+      status = tmplDefault ?? 'active';
     }
   }
   const effective = config.typeStatuses?.get(typeName) ?? config.validStatuses;
@@ -340,9 +346,23 @@ export async function runNew(argv, config, opts = {}) {
     content = `---\n${fm}\n---\n${body}`;
   }
 
+  // When the project has >1 root and `--root` was omitted, surface the choice
+  // so agents can see that an alternative root was available. Cheap visibility
+  // for the "ended up in docs/plans/ for a doc" foot-gun.
+  const allRoots = config.docsRoots ?? [config.docsRoot];
+  let rootHint = '';
+  if (!rootName && allRoots.length > 1) {
+    const chosenLabel = path.basename(targetRoot);
+    const others = allRoots
+      .filter(r => r !== targetRoot)
+      .map(r => path.basename(r));
+    rootHint = `Root: ${chosenLabel} (others: ${others.join(', ')} — pass --root <name> to change)\n`;
+  }
+
   if (dryRun) {
     process.stdout.write(`${dim('[dry-run]')} Would create: ${repoPath}\n`);
     process.stdout.write(`${dim('[dry-run]')} Type: ${typeName}\n`);
+    if (rootHint) process.stdout.write(`${dim('[dry-run]')} ${rootHint}`);
     return;
   }
 
@@ -351,6 +371,7 @@ export async function runNew(argv, config, opts = {}) {
 
   writeFileSync(filePath, content, 'utf8');
   process.stdout.write(`${green('Created')}: ${repoPath} ${dim(`(${typeName})`)}\n`);
+  if (rootHint) process.stdout.write(dim(rootHint));
 
   regenIndex(config);
 

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/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/`.