dotmd-cli 0.39.3 → 0.39.4

package/bin/dotmd.mjs

@@ -68,6 +68,7 @@ Create & Export:
 Setup:
   init                              Create starter config + docs directory
   statuses [list|add|set|remove|migrate]  Manage per-project status taxonomy
+  help statuses                     Full status vocabulary + unstuck-actions + transitions
   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]
@@ -92,6 +93,90 @@ Options:
 
 Outputs the complete document index as JSON to stdout.`,
 
+  // Help topic accessed via \`dotmd help statuses\` (not a command — see dispatch
+  // below). Single-source-of-truth for the built-in status vocabulary across all
+  // three doc types. User-defined types/statuses live in config; introspect them
+  // with \`dotmd statuses list\`.
+  'help:statuses': `dotmd help statuses — status vocabulary, unstuck-actions, and transitions
+
+Every document has a \`type:\` field; each type has its own valid statuses.
+Status validation is type-aware (type > root > global). To inspect or edit
+the status taxonomy in a specific project, use \`dotmd statuses list\`.
+
+────────────────────────────────────────────────────────────────────
+plan statuses (each maps to a distinct unstuck-action)
+
+  in-session     A Claude session is working on it now.
+                 Don't pick up unless you own it (auto-reattaches) or pass
+                 --takeover. Stale lease cleanup: \`dotmd release --stale\`.
+
+  active         Ready to be picked up.
+                 \`dotmd pickup <file>\` → in-session.
+
+  planned        Queued for future work, not yet ready to execute.
+                 Transition to active when ready to start.
+
+  blocked        External arrival wait — monitor.
+                 Hardware, vendor delivery, third-party rollout. Quiet
+                 (skipStale) — you can't speed it up by nagging.
+
+  partial        Shipped + deferred tail — spawn successor plans.
+                 Plan body should reference the successor plan(s). Quiet.
+
+  paused         Started but stopped mid-work — re-evaluate to resume.
+                 Short stale window (3 days) so resume-decisions don't decay.
+
+  awaiting       Needs human input/decision — chase the answer.
+                 NOT quiet — generates stale pressure so pings aren't forgotten.
+
+  queued-after   Sequenced behind another plan — check predecessor.
+                 Quiet. Can start once the predecessor ships.
+
+  archived       No longer relevant; auto-moved to archive directory.
+
+Canonical transitions:
+  active → in-session              \`dotmd pickup <file>\`
+  in-session → active              \`dotmd release <file>\`
+  in-session → partial             \`dotmd status <file> partial\` (+ release)
+  in-session → awaiting            \`dotmd status <file> awaiting\` (+ release)
+  any → archived                   \`dotmd archive <file>\`
+
+────────────────────────────────────────────────────────────────────
+doc statuses
+
+  draft          Work-in-progress reference doc.
+  active         Living document, kept up-to-date.
+  review         Awaiting peer review.
+  reference      Stable canonical reference (excluded from stale checks).
+  deprecated     Superseded but kept for history.
+  archived       No longer relevant; moved to archive directory.
+
+────────────────────────────────────────────────────────────────────
+prompt statuses
+
+  pending        Ready for the next session to consume.
+                 \`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\`.
+                 Still listed by \`dotmd prompts list\`.
+                 \`dotmd prompts unshelve <file>\` → pending.
+
+  claimed        Legacy intermediate state (atomic use → archived now).
+
+  archived       Consumed prompt; body preserved in archive directory.
+
+────────────────────────────────────────────────────────────────────
+Related commands:
+  dotmd statuses              Inspect/manage per-project status taxonomy
+  dotmd status <f> <new>      Transition a document's status
+  dotmd briefing              See plans grouped by status
+  dotmd plans --status <s>    Filter live plans by status
+  dotmd hud                   Two-line actionable triage (held / prompts / stuck)
+
+Run \`dotmd statuses list --type plan\` to see the full set (including any
+project-specific custom statuses) with their flags.`,
+
   completions: `dotmd completions <bash|zsh> — output shell completion script
 
 Add to your shell config:
@@ -241,6 +326,9 @@ Default plan statuses (each maps to a distinct unstuck-action):
   queued-after   Sequenced behind another plan — check predecessor
   archived       No longer relevant; auto-moved to archive directory
 
+Run \`dotmd help statuses\` for the full vocabulary across all doc types
+(plan, doc, prompt) plus canonical transitions and related commands.
+
 Use --dry-run (-n) to preview changes without writing anything.`,
 
   check: `dotmd check — validate frontmatter and references
@@ -630,8 +718,8 @@ sorted by status. Supports all query flags (--status, --module, --json,
 --sort, --group, etc.).
 
 Default plan statuses: in-session, active, planned, blocked, partial,
-paused, awaiting, queued-after, archived. Run \`dotmd status --help\` for
-the unstuck-action behind each one.
+paused, awaiting, queued-after, archived. Run \`dotmd help statuses\` for
+the unstuck-action behind each one and canonical transitions.
 
 Examples:
   dotmd plans                          # live plans (default)
@@ -671,6 +759,9 @@ Default prompt statuses: pending, shelved, claimed, archived.
 
 Examples:
   dotmd prompts                        # pending prompts (default)
+  dotmd prompts list --verbose         # one row per prompt + target plan ref
+                                       # (from related_plans, parent_plan,
+                                       #  or the first body .md link)
   dotmd prompts list --include-archived # all prompts including archived
   dotmd prompts list --status claimed   # already-consumed prompts
   dotmd prompts --json                 # JSON output
@@ -825,6 +916,14 @@ async function main() {
   }
 
   if (command === 'help' || command === '--help' || command === '-h') {
+    const topic = args[1];
+    if (topic) {
+      const key = `help:${topic}`;
+      if (HELP[key]) { process.stdout.write(`${HELP[key]}\n`); return; }
+      if (HELP[topic]) { process.stdout.write(`${HELP[topic]}\n`); return; }
+      process.stderr.write(`Unknown help topic: ${topic}\n\nAvailable topics: statuses\nPer-command help: dotmd <cmd> --help\n`);
+      process.exit(1);
+    }
     process.stdout.write(`${HELP._main}\n`);
     return;
   }
@@ -927,7 +1026,7 @@ async function main() {
   }
   if (command === 'prompts') {
     const { runPrompts } = await import('../src/prompts.mjs');
-    await runPrompts(restArgs, config, { dryRun });
+    await runPrompts(restArgs, config, { dryRun, verbose });
     return;
   }
 

package/package.json

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

package/src/lifecycle.mjs

@@ -246,7 +246,15 @@ export async function runPickup(argv, config, opts = {}) {
   }
 
   const pickupable = new Set(['active', 'planned', 'in-session']);
-  if (oldStatus && !pickupable.has(oldStatus)) die(`Cannot pick up a plan with status '${oldStatus}'. Must be active or planned.\n  ${repoPath}`);
+  if (oldStatus && !pickupable.has(oldStatus)) {
+    die(
+      `Cannot pick up a plan with status '${oldStatus}'. Must be active or planned.\n` +
+      `  ${repoPath}\n` +
+      `\n` +
+      `Recover with:\n` +
+      `  dotmd status ${repoPath} active && dotmd pickup ${repoPath}`,
+    );
+  }
 
   const today = nowIso();
   const leaseOldStatus = oldStatus === 'in-session' ? 'active' : (oldStatus ?? 'active');
@@ -572,6 +580,16 @@ export function runArchive(argv, config, opts = {}) {
     if (refCount > 0) {
       out.write(`${prefix} Would update references in ${refCount} file(s)\n`);
     }
+
+    // Preview lease release (only if a lease exists for this plan)
+    if (readLeases(config)[oldRepoPath]) {
+      out.write(`${prefix} Would release in-session lease: ${oldRepoPath}\n`);
+    }
+
+    // Preview onArchive hook fire
+    if (config.hooks?.onArchive) {
+      out.write(`${prefix} Would fire hook: onArchive\n`);
+    }
     return;
   }
 

package/src/prompts.mjs

@@ -29,12 +29,17 @@ export async function runPrompts(argv, config, opts = {}) {
   }
 }
 
-function runPromptsList(argv, config) {
+function runPromptsList(argv, config, opts = {}) {
   const index = buildIndex(config);
   const hasStatusFlag = argv.includes('--status');
   const includeArchived = argv.includes('--include-archived');
   const sub = argv[0];
 
+  if (opts.verbose && !argv.includes('--json')) {
+    renderPromptsVerbose(index, config, { hasStatusFlag, includeArchived });
+    return;
+  }
+
   let defaults;
   let extras = argv;
   if (sub === 'status') {
@@ -48,6 +53,67 @@ function runPromptsList(argv, config) {
   runQuery(index, [...defaults, ...extras], config, { preset: 'prompts' });
 }
 
+// Resolve a prompt's "target plan" for `prompts list --verbose`. Order:
+//   1. frontmatter `related_plans:` (first entry — assumed plan slug)
+//   2. frontmatter `parent_plan:`
+//   3. first body markdown link to a .md file
+// Returns a repo-relative display path or null.
+function findPromptTarget(promptDoc, config) {
+  const refs = promptDoc.refFields ?? {};
+  const fmTargets = [...(refs.related_plans ?? []), ...(refs.parent_plan ?? [])];
+  for (const t of fmTargets) {
+    if (typeof t === 'string' && t.trim()) return slugToPlanPath(t.trim(), config);
+  }
+
+  const links = promptDoc.bodyLinks ?? [];
+  const mdLink = links.find(l => /\.md(?:#|$)/.test(l.href ?? ''));
+  if (mdLink) return resolveBodyLink(mdLink.href, promptDoc.path);
+  return null;
+}
+
+// Plan slugs in frontmatter (e.g. `related_plans: [foo-bar]`) resolve to
+// <docs-root>/plans/<slug>.md.
+function slugToPlanPath(s, config) {
+  const cleaned = s.replace(/#.*$/, '').replace(/^\.\//, '');
+  if (cleaned.includes('/') || cleaned.endsWith('.md')) return cleaned;
+  return `${config.docsRootPrefix || 'docs/'}plans/${cleaned}.md`;
+}
+
+// Resolve a markdown body link relative to the prompt's location so e.g.
+// `../plans/foo.md` from docs/prompts/x.md → docs/plans/foo.md.
+function resolveBodyLink(link, promptRepoPath) {
+  const cleaned = link.replace(/#.*$/, '');
+  if (cleaned.startsWith('/')) return cleaned.replace(/^\/+/, '');
+  const promptDir = path.dirname(promptRepoPath);
+  return path.normalize(path.join(promptDir, cleaned));
+}
+
+function renderPromptsVerbose(index, config, { hasStatusFlag, includeArchived }) {
+  let prompts = index.docs.filter(d => d.type === 'prompt');
+  if (!hasStatusFlag && !includeArchived) {
+    prompts = prompts.filter(d => d.status !== 'archived');
+  }
+  if (prompts.length === 0) {
+    process.stdout.write('No prompts.\n');
+    return;
+  }
+
+  prompts.sort((a, b) => (b.updated ?? '').localeCompare(a.updated ?? ''));
+
+  const counts = {};
+  for (const p of prompts) counts[p.status ?? 'unknown'] = (counts[p.status ?? 'unknown'] ?? 0) + 1;
+  const summary = Object.entries(counts).map(([s, n]) => `${n} ${s}`).join(' · ');
+  process.stdout.write(`${prompts.length} prompt${prompts.length === 1 ? '' : 's'} · ${summary}\n\n`);
+
+  for (const p of prompts) {
+    const slug = path.basename(p.path, '.md');
+    const target = findPromptTarget(p, config);
+    const status = (p.status ?? 'unknown').toUpperCase();
+    const arrow = target ? `  ${dim('→')} ${target}` : `  ${dim('→ (no target plan)')}`;
+    process.stdout.write(`  ${green(slug)}  [${status}]\n${arrow}\n`);
+  }
+}
+
 function pendingPromptsOldestFirst(config) {
   const index = buildIndex(config);
   const prompts = index.docs.filter(d => d.type === 'prompt' && d.status === 'pending');
@@ -139,7 +205,15 @@ function consumePrompt(filePath, config, opts) {
   }
 
   if (dryRun) {
-    process.stderr.write(`${dim('[dry-run]')} Would emit body and archive: ${repoPath} (${status ?? 'unknown'} → archived)\n`);
+    const prefix = dim('[dry-run]');
+    process.stderr.write(`${prefix} Would emit body and archive: ${repoPath} (${status ?? 'unknown'} → archived)\n`);
+    const bytes = Buffer.byteLength(body, 'utf8');
+    const lines = body.split('\n').length;
+    process.stderr.write(`${prefix} body preview (${bytes}B, ${lines} lines):\n`);
+    process.stderr.write(`${dim('---8<---')}\n`);
+    process.stderr.write(body);
+    if (!body.endsWith('\n')) process.stderr.write('\n');
+    process.stderr.write(`${dim('--->8---')}\n`);
     runArchive([filePath], config, { dryRun: true, noIndex, out: process.stderr });
     return;
   }