dotmd-cli 0.49.3 → 0.49.5

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`, `shelved`, `claimed`, `archived` |
+| `prompt` | Saved prompts that seed future Claude sessions | `pending`, `held`, `shelved`, `claimed`, `archived` |
 
 Documents without a `type` field use the global `statuses.order` from config.
 
@@ -206,7 +206,7 @@ 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]          Manage saved prompts (list, next, use, shelve, archive, new)
+dotmd prompts [sub]          Manage saved prompts (list, next, use, hold, 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)
@@ -303,16 +303,17 @@ dotmd prompts                     # list pending prompts (default)
 dotmd prompts list --all          # all statuses
 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 hold <file>         # park a prompt (status → held) under prompts/held/:
+                                  # kept in list, hidden from hud/briefing, skipped by `next`
+dotmd prompts unhold <file>       # move a held prompt back to pending
+dotmd prompts shelve <file>       # legacy alias for `hold`
 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. Shelved prompts are kept out of the SessionStart surface — use them for "saved but not next."
+`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. Held prompts are kept out of the SessionStart surface — use them for "saved but not next."
 
-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.
+Statuses: `pending` (drafted, awaiting a session), `held` (saved but parked under `prompts/held/` — visible in `prompts list`, hidden from `hud`/`briefing`, skipped by `prompts next`), `archived` (consumed or filed away). `shelved` is a legacy spelling accepted for older files; `claimed` is reserved for a future "in-flight" state but is currently a synonym for archived in practice.
 
 ### Command Journal (opt-in)
 

package/bin/dotmd.mjs

@@ -44,7 +44,7 @@ const FLAG_SPECS = {
   prompts: {
     flags: new Set(['--json', '--status', '--include-archived', '--sort', '--limit', '--all', '--no-index', '--show-files', '--body', '--message', '--title']),
     values: new Set(['--status', '--sort', '--limit', '--body', '--message', '--title']),
-    subcommands: new Set(['list', 'next', 'use', 'resume', 'archive', 'new', 'shelve', 'unshelve', 'status']),
+    subcommands: new Set(['list', 'next', 'use', 'resume', 'archive', 'new', 'hold', 'unhold', 'shelve', 'unshelve', 'status']),
   },
 };
 
@@ -65,12 +65,12 @@ const HELP = {
 
 Common commands:
   plans                 Live plans (excludes archived)
-  prompts               Prompt queue/admin (list, next, archive, new, shelve)
+  prompts               Prompt queue/admin (list, next, archive, new, hold)
   briefing              Full briefing with plan counts + next steps
   agent-context         Compact bounded JSON context for agents
   set <status> [file]   Transition status (start work, finish, archive — all via target status)
   new <type> <name>     Create plan/doc/prompt (pipe stdin or @path for body)
-  use [<file>]          Open a doc by type: prompt → consume, plan → start, doc → read
+  use [<file-or-prompt-slug>] Open a doc by type: prompt → consume, plan → start, doc → read
                         (no file: consume oldest pending prompt)
   archive <file>        Close out a plan (status → archived, move, update refs)
 
@@ -95,8 +95,8 @@ View & Query:
   focus [status] [--json]           Detailed view for one status group
   query [filters] [--json]          Filtered search (--status, --keyword, --stale, etc.)
   plans                             Live plans (excludes archived; --include-archived for all)
-  use [<file>]                      Open a doc by type: prompt → consume, plan → start, doc → read
-  prompts [list|archive|new|shelve] Prompt admin (list / archive / save / shelve). Use \`dotmd use\` to consume.
+  use [<file-or-prompt-slug>]       Open a doc by type: prompt → consume, plan → start, doc → read
+  prompts [list|archive|new|hold] Prompt admin (list / archive / save / hold). Use \`dotmd use\` to consume.
   stale                             Stale docs (preset)
   actionable                        Docs with next steps (preset)
 
@@ -235,9 +235,13 @@ prompt statuses
                  \`dotmd prompts use <file>\` prints body + archives atomically.
                  \`dotmd prompts next\` does the same for the oldest pending.
 
-  shelved        Saved but hidden from \`hud\` / \`briefing\` / \`prompts next\`.
+  held           Saved under prompts/held/ and hidden from \`hud\` /
+                 \`briefing\` / \`prompts next\`.
                  Still listed by \`dotmd prompts list\`.
-                 \`dotmd prompts unshelve <file>\` → pending.
+                 \`dotmd prompts unhold <file>\` → pending.
+
+  shelved        Legacy spelling for held prompts. \`dotmd prompts shelve\`
+                 now writes \`status: held\`.
 
   claimed        Legacy intermediate state (atomic use → archived now).
 
@@ -920,10 +924,11 @@ Subcommands:
   resume <file-or-slug>      Alias for \`use\` — same behavior, easier name
                              when continuing a session
   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.
+  hold <file-or-slug>        Park a prompt (status → held) under prompts/held/:
+                             kept in list, hidden from hud/briefing pending
+                             surfaces, skipped by \`prompts next\`.
+  unhold <file-or-slug>      Move a held prompt back to pending.
+  shelve / unshelve          Legacy aliases for hold / unhold.
   new <slug> [body]          Create a new prompt (alias for
                              \`dotmd new prompt <slug> [body]\`)
 
@@ -931,7 +936,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, shelved, claimed, archived.
+Default prompt statuses: pending, held, shelved, claimed, archived.
 
 Examples:
   dotmd prompts                        # pending prompts (default)

package/package.json

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

package/src/config.mjs

@@ -11,6 +11,7 @@ const CONFIG_FILENAMES = ['dotmd.config.mjs', '.dotmd.config.mjs', 'dotmd.config
 const REPLACE_KEYS = new Set([
   'statuses.staleDays',
   'statuses.rootStatuses',
+  'lifecycle.filedStatuses',
   'presets',
   'context',
 ]);
@@ -36,8 +37,8 @@ const DEFAULTS = {
       staleDays: { draft: 30, active: 14, review: 14 },
     },
     prompt: {
-      statuses: ['pending', 'shelved', 'claimed', 'archived'],
-      context: { expanded: ['pending'], listed: ['shelved'], counted: ['claimed', 'archived'] },
+      statuses: ['pending', 'held', 'shelved', 'claimed', 'archived'],
+      context: { expanded: ['pending'], listed: ['held', 'shelved'], counted: ['claimed', 'archived'] },
       staleDays: { pending: 30 },
     },
   },
@@ -58,10 +59,10 @@ const DEFAULTS = {
     skipStaleFor: ['archived', 'reference', 'partial', 'queued-after'],
     skipWarningsFor: ['archived', 'partial', 'queued-after'],
     terminalStatuses: ['archived', 'deprecated', 'reference'],
-    // F15: opt-in per-status `{ filed: true }` in `types.<type>.statuses`
-    // populates this map (status → dirName). Empty by default — archive: true
-    // remains a separate primitive untouched.
-    filedStatuses: {},
+    // F15: per-status filing buckets (status → dirName). Built-in held/paused
+    // statuses file under the owning type folder; archive remains a separate
+    // primitive untouched.
+    filedStatuses: { held: 'held', shelved: 'held', paused: 'held' },
   },
 
   taxonomy: {

package/src/lifecycle.mjs

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
-import { asString, toRepoPath, die, warn, resolveDocPath, resolveRefPath, escapeRegex, nowIso, suggestCandidates, emitFilesFooter } from './util.mjs';
+import { asString, toRepoPath, die, warn, resolveDocPath, resolveRefPath, escapeRegex, nowIso, suggestCandidates, emitFilesFooter, isArchivedPath } from './util.mjs';
 import { gitMv, getGitLastModified, getGitLastModifiedBatch } from './git.mjs';
 import { buildIndex, collectDocFiles } from './index.mjs';
 import { renderIndexFile, writeIndex } from './index-file.mjs';
@@ -26,6 +26,23 @@ function findFileRoot(filePath, config) {
   return roots.find(r => filePath.startsWith(r + '/')) ?? config.docsRoot;
 }
 
+function defaultTypeDir(docType, config) {
+  if (docType === 'plan') return 'plans';
+  if (docType === 'prompt') return 'prompts';
+  const templateDir = config.raw?.templates?.[docType]?.dir;
+  return typeof templateDir === 'string' && templateDir ? templateDir : null;
+}
+
+function findFilingRoot(filePath, fileRoot, docType, config) {
+  const dirName = defaultTypeDir(docType, config);
+  if (!dirName) return fileRoot;
+  if (path.basename(fileRoot) === dirName) return fileRoot;
+
+  const relSegments = path.relative(fileRoot, filePath).split(path.sep);
+  if (relSegments[0] === dirName) return path.join(fileRoot, dirName);
+  return fileRoot;
+}
+
 // Best-effort index regen for any doc-set or doc-status mutation. The
 // generated block groups by status and embeds per-doc snapshots, so any
 // change that affects what would render leaves the index stale. Wrapped
@@ -167,9 +184,10 @@ export async function runStatus(argv, config, opts = {}) {
 
   const today = nowIso();
   const archiveDir = path.join(fileRoot, config.archiveDir);
-  const relFromRoot = path.relative(fileRoot, filePath);
-  const relSegments = relFromRoot.split(path.sep);
-  const inArchive = relFromRoot.startsWith(config.archiveDir + '/') || relFromRoot.startsWith(config.archiveDir + path.sep);
+  const filingRoot = findFilingRoot(filePath, fileRoot, docType, config);
+  const relFromFilingRoot = path.relative(filingRoot, filePath);
+  const relSegments = relFromFilingRoot.split(path.sep);
+  const inArchive = isArchivedPath(toRepoPath(filePath, config.repoRoot), config);
   const isArchiving = config.lifecycle.archiveStatuses.has(newStatus) && !inArchive;
   const isUnarchiving = !config.lifecycle.archiveStatuses.has(newStatus) && inArchive;
 
@@ -200,12 +218,12 @@ export async function runStatus(argv, config, opts = {}) {
       finalPath = targetPath;
     }
     if (isFiling) {
-      const targetPath = path.join(fileRoot, newFiledDir, path.basename(filePath));
+      const targetPath = path.join(filingRoot, newFiledDir, path.basename(filePath));
       process.stdout.write(`${prefix} Would file: ${toRepoPath(filePath, config.repoRoot)} → ${toRepoPath(targetPath, config.repoRoot)}\n`);
       finalPath = targetPath;
     }
     if (isUnfiling) {
-      const targetPath = path.join(fileRoot, path.basename(filePath));
+      const targetPath = path.join(filingRoot, path.basename(filePath));
       process.stdout.write(`${prefix} Would unfile: ${toRepoPath(filePath, config.repoRoot)} → ${toRepoPath(targetPath, config.repoRoot)}\n`);
       finalPath = targetPath;
     }
@@ -236,7 +254,7 @@ export async function runStatus(argv, config, opts = {}) {
   }
 
   if (isFiling) {
-    const targetDir = path.join(fileRoot, newFiledDir);
+    const targetDir = path.join(filingRoot, newFiledDir);
     mkdirSync(targetDir, { recursive: true });
     const targetPath = path.join(targetDir, path.basename(filePath));
     if (existsSync(targetPath)) { die(`Target already exists: ${toRepoPath(targetPath, config.repoRoot)}`); }
@@ -246,7 +264,7 @@ export async function runStatus(argv, config, opts = {}) {
   }
 
   if (isUnfiling) {
-    const targetPath = path.join(fileRoot, path.basename(filePath));
+    const targetPath = path.join(filingRoot, path.basename(filePath));
     if (existsSync(targetPath)) { die(`Target already exists: ${toRepoPath(targetPath, config.repoRoot)}`); }
     const result = gitMv(filePath, targetPath, config.repoRoot);
     if (result.status !== 0) { die(result.stderr || 'git mv failed.'); }
@@ -620,8 +638,15 @@ export function runArchive(argv, config, opts = {}) {
     appendVersionHistory(filePath, `Archived (frontmatter healed in place from \`${oldStatus}\`).`);
     if (!noIndex) regenIndex(config);
     out.write(`${green('✓ Healed')}: ${repoPathHeal} (${oldStatus} → archived; file already under \`${config.archiveDir}/\`)\n`);
-    if (showFiles) emitFilesFooter([repoPathHeal, config.indexPath], config);
-    return;
+    const touched = [repoPathHeal];
+    if (config.indexPath && !noIndex) touched.push(config.indexPath);
+    if (showFiles) emitFilesFooter(touched, config);
+    return {
+      action: 'healed',
+      oldRepoPath: repoPathHeal,
+      newRepoPath: repoPathHeal,
+      touched,
+    };
   }
 
   const closeoutAction = closeoutTemplate ? planCloseoutInjection(body) : null;
@@ -701,7 +726,12 @@ export function runArchive(argv, config, opts = {}) {
 
   try { config.hooks.onArchive?.({ path: newRepoPath, oldStatus }, { oldPath: oldRepoPath, newPath: newRepoPath }); } catch (err) { warn(`Hook 'onArchive' threw: ${err.message}`); }
 
-  return { touched };
+  return {
+    action: 'archived',
+    oldRepoPath,
+    newRepoPath,
+    touched,
+  };
 }
 
 // Unified status-transition verb. Collapses status/archive/release into one
@@ -763,9 +793,7 @@ export async function runSet(argv, config, opts = {}) {
   const parsedFm = parseSimpleFrontmatter(fmRaw);
   const oldStatus = asString(parsedFm.status);
 
-  const fileRoot = findFileRoot(filePath, config);
-  const relFromRoot = path.relative(fileRoot, filePath);
-  const inArchive = relFromRoot.startsWith(config.archiveDir + '/') || relFromRoot.startsWith(config.archiveDir + path.sep);
+  const inArchive = isArchivedPath(toRepoPath(filePath, config.repoRoot), config);
 
   if (config.lifecycle.archiveStatuses.has(newStatus) && !inArchive) {
     const archiveArgs = [filePath];
@@ -807,11 +835,7 @@ export function runBulkArchive(argv, config, opts = {}) {
     }
   }
 
-  const unique = [...new Set(matched)].filter(f => {
-    const root = findFileRoot(f, config);
-    const rel = path.relative(root, f);
-    return !rel.startsWith(config.archiveDir + '/') && !rel.startsWith(config.archiveDir + path.sep);
-  });
+  const unique = [...new Set(matched)].filter(f => !isArchivedPath(toRepoPath(f, config.repoRoot), config));
   if (unique.length === 0) die('No matching files found (already-archived files are excluded).');
 
   process.stdout.write(`${unique.length} file(s) to archive:\n`);

package/src/prompts.mjs

@@ -11,7 +11,7 @@ import { green, dim } from './color.mjs';
 // `resume` is an alias for `use` — agents reach for "resume" when continuing a
 // session; `use` reads as internal mechanics. Both names stay valid; the
 // canonical output ("Consumed: …") is unchanged.
-const SUBCOMMANDS = new Set(['list', 'next', 'use', 'resume', 'archive', 'new', 'shelve', 'unshelve']);
+const SUBCOMMANDS = new Set(['list', 'next', 'use', 'resume', 'archive', 'new', 'hold', 'unhold', 'shelve', 'unshelve']);
 
 export async function runPrompts(argv, config, opts = {}) {
   const sub = argv[0];
@@ -28,8 +28,10 @@ export async function runPrompts(argv, config, opts = {}) {
     case 'resume':   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);
+    case 'hold':     return runPromptsHold(rest, config, opts);
+    case 'unhold':   return runPromptsUnhold(rest, config, opts);
+    case 'shelve':   return runPromptsHold(rest, config, opts);
+    case 'unshelve': return runPromptsUnhold(rest, config, opts);
   }
 }
 
@@ -190,7 +192,8 @@ function runPromptsNext(argv, config, opts = {}) {
 // path + '.md', exact basename match across type: prompt docs, substring
 // match across type: prompt docs. Returns the absolute path or dies with a
 // helpful message (no match / ambiguous match).
-function resolvePromptInput(input, config) {
+export function resolvePromptInput(input, config, options = {}) {
+  const dieOnMiss = options.dieOnMiss !== false;
   const direct = resolveDocPath(input, config);
   if (direct) return direct;
 
@@ -201,7 +204,10 @@ function resolvePromptInput(input, config) {
 
   const index = buildIndex(config);
   const prompts = index.docs.filter(d => d.type === 'prompt');
-  if (prompts.length === 0) die(`No prompts in the index.`);
+  if (prompts.length === 0) {
+    if (dieOnMiss) die(`No prompts in the index.`);
+    return null;
+  }
 
   const slug = input.replace(/\.md$/, '');
 
@@ -219,7 +225,8 @@ function resolvePromptInput(input, config) {
     die(`Multiple prompts match "${input}":\n${bySubstring.map(d => '  ' + d.path).join('\n')}`);
   }
 
-  die(`No prompt found matching: ${input}`);
+  if (dieOnMiss) die(`No prompt found matching: ${input}`);
+  return null;
 }
 
 function runPromptsUse(argv, config, opts = {}) {
@@ -243,7 +250,7 @@ export function consumePrompt(filePath, config, opts) {
   if (docType !== 'prompt') {
     die(`Not a prompt (type: ${docType ?? 'unknown'}): ${repoPath}`);
   }
-  if (status === 'archived') {
+  if (status === 'archived' || isArchivedPath(repoPath, config)) {
     die(`Already consumed: ${repoPath}`);
   }
 
@@ -267,12 +274,13 @@ export function consumePrompt(filePath, config, opts) {
   // ever being archived, and the next session sees the same prompt as pending.
   // Body is already in memory from extractFrontmatter, so the source file
   // can move out from under us safely.
-  runArchive([filePath], config, { noIndex, showFiles, out: process.stderr });
+  const archiveResult = runArchive([filePath], config, { noIndex, showFiles, out: process.stderr });
 
   process.stdout.write(body);
   if (!body.endsWith('\n')) process.stdout.write('\n');
 
-  process.stderr.write(`${green('✓ Consumed')}: ${repoPath}\n`);
+  const consumedPath = archiveResult?.newRepoPath ?? repoPath;
+  process.stderr.write(`${green('✓ Consumed')}: ${consumedPath}\n`);
 }
 
 function runPromptsArchive(argv, config, opts = {}) {
@@ -299,16 +307,16 @@ async function runPromptsNew(argv, config, opts = {}) {
   return runNew(['prompt', ...argv], config, opts);
 }
 
-async function runPromptsShelve(argv, config, opts = {}) {
+async function runPromptsHold(argv, config, opts = {}) {
   const input = argv.find(a => !a.startsWith('-'));
-  if (!input) die('Usage: dotmd prompts shelve <file-or-slug>');
+  if (!input) die('Usage: dotmd prompts hold <file-or-slug>');
   const filePath = resolvePromptInput(input, config);
-  return runStatus([filePath, 'shelved'], config, opts);
+  return runStatus([filePath, 'held'], config, opts);
 }
 
-async function runPromptsUnshelve(argv, config, opts = {}) {
+async function runPromptsUnhold(argv, config, opts = {}) {
   const input = argv.find(a => !a.startsWith('-'));
-  if (!input) die('Usage: dotmd prompts unshelve <file-or-slug>');
+  if (!input) die('Usage: dotmd prompts unhold <file-or-slug>');
   const filePath = resolvePromptInput(input, config);
   return runStatus([filePath, 'pending'], config, opts);
 }

package/src/use.mjs

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { asString, die, resolveDocPath, toRepoPath } from './util.mjs';
-import { consumePrompt, pendingPromptsOldestFirst } from './prompts.mjs';
+import { consumePrompt, pendingPromptsOldestFirst, resolvePromptInput } from './prompts.mjs';
 import { runPickup } from './lifecycle.mjs';
 
 // Top-level `dotmd use [file]` — the single "start engaging with this doc"
@@ -22,7 +22,7 @@ export async function runUse(argv, config, opts = {}) {
     return consumePrompt(head.abs, config, opts);
   }
 
-  const filePath = resolveDocPath(positional, config);
+  const filePath = resolveDocPath(positional, config) ?? resolvePromptInput(positional, config, { dieOnMiss: false });
   if (!filePath) die(`File not found: ${positional}`);
 
   const raw = readFileSync(filePath, 'utf8');

package/src/validate.mjs

@@ -49,6 +49,11 @@ function liveTypeDirsForRoots(config) {
     for (const dirName of filedDirs) {
       if (path.basename(rootRel) === dirName) continue;
       set.add(rootRel ? `${rootRel}/${dirName}` : dirName);
+      for (const typeDir of BUILTIN_TYPE_DIR_NAMES) {
+        if (path.basename(rootRel) === typeDir) continue;
+        const typeRoot = rootRel ? `${rootRel}/${typeDir}` : typeDir;
+        set.add(`${typeRoot}/${dirName}`);
+      }
     }
   }
   return set;