dotmd-cli 0.38.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.38.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/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/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);