dotmd-cli 0.37.0 → 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);
@@ -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.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/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/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/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/`.