dotmd-cli 0.39.2 → 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:
@@ -170,6 +255,8 @@ If a plan is already in-session:
 
 Options:
   --takeover             Force-claim a plan held by another session
+  --no-index             Skip index regen (see \`dotmd archive --help\`)
+  --show-files           Append \`files: …\` line to stderr (see \`dotmd archive --help\`)
   --json                 Output as JSON
   --dry-run, -n          Preview without writing
 
@@ -191,6 +278,8 @@ Options:
   --all                  Release every lease in the file (administrative)
   --stale                Release leases whose pid is dead or age >24h
   --force                Override "not yours" refusal on a specific file
+  --no-index             Skip index regen (see \`dotmd archive --help\`)
+  --show-files           Append \`files: …\` line to stderr (see \`dotmd archive --help\`)
   --json                 Output as JSON ({ released, skipped })
   --dry-run, -n          Preview without writing
 
@@ -221,6 +310,11 @@ Moves the document to the new status. If transitioning to an archive
 status, automatically moves the file to the archive directory and
 regenerates the index (if configured).
 
+Options:
+  --no-index             Skip index regen (useful in concurrent-session repos
+                         doing path-limited commits — see \`dotmd archive --help\`).
+  --show-files           Append \`files: …\` line to stderr (see \`dotmd archive --help\`).
+
 Default plan statuses (each maps to a distinct unstuck-action):
   in-session     A Claude session is working on it now
   active         Ready to be picked up
@@ -232,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
@@ -252,7 +349,17 @@ Options:
 Sets status to 'archived', moves to the archive directory, auto-updates
 references in other docs, and regenerates the index.
 
-Use --dry-run (-n) to preview changes without writing anything.`,
+Options:
+  --no-index             Skip index regen. Use when multiple sessions are
+                         working concurrently and you want a path-limited
+                         commit that doesn't pull other agents' uncommitted
+                         index changes into your staging area. Run \`dotmd index\`
+                         later (or wire it into a commit hook) to refresh.
+  --show-files           Append a final \`files: a b c …\` line to stderr
+                         listing every doc/index path the command touched
+                         (deduped, sorted, repo-relative). Lets agents do
+                         \`git add\` with the exact set instead of guessing.
+  --dry-run, -n          Preview changes without writing anything.`,
 
   coverage: `dotmd coverage — metadata coverage report
 
@@ -488,6 +595,8 @@ Other options:
   --status <s>         Set initial status (defaults to first valid status for the type)
   --title <t>          Override the auto-derived title
   --root <name>        Create in a specific docs root
+  --show-files         Append \`files: …\` line to stderr listing what was touched
+                       (the new doc + the index file). See \`dotmd archive --help\`.
   --list-types         Show registered types (alias: --list-templates)
 
 For plans, the default status vocabulary is: in-session, active, planned,
@@ -609,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)
@@ -650,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
@@ -680,6 +792,21 @@ Supports all query flags (--status, --json, --sort, etc.)`,
 Shows documents that reference or depend on the given file.
 Useful for impact analysis before archiving or changing a plan.
 
+The dependency edge is read from each plan's \`blockers:\` frontmatter
+(a YAML list of plan slugs or paths). \`blocked_by:\` is accepted as
+an alias since 0.39.3 — both populate the same index field, so use
+whichever name reads better.
+
+Frontmatter shape:
+
+    ---
+    type: plan
+    status: blocked
+    blockers:
+      - foo-plan.md
+      - docs/plans/bar-plan.md
+    ---
+
 Options:
   --json                 Output as JSON`,
 
@@ -789,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;
   }
@@ -891,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.2",
+  "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/index.mjs

@@ -175,7 +175,13 @@ export function parseDocFile(filePath, config, opts = {}) {
     }
   }
   const nextStep = asString(parsedFrontmatter.next_step) ?? extractNextStep(body) ?? null;
-  const blockers = normalizeBlockers(parsedFrontmatter.blockers);
+  // `blocked_by` is accepted as an alias for `blockers` since 0.39.3 — agents
+  // filing tickets naturally reach for the JIRA/Linear name. If both are set,
+  // they're merged (de-duped via normalizeBlockers → mergeUniqueStrings).
+  const blockers = mergeUniqueStrings(
+    normalizeBlockers(parsedFrontmatter.blockers),
+    normalizeBlockers(parsedFrontmatter.blocked_by),
+  );
   const surface = asString(parsedFrontmatter.surface) ?? null;
   const surfaces = normalizeStringList(parsedFrontmatter.surfaces);
   const moduleName = asString(parsedFrontmatter.module) ?? null;

package/src/lifecycle.mjs

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter, replaceFrontmatter } from './frontmatter.mjs';
-import { asString, toRepoPath, die, warn, resolveDocPath, resolveRefPath, escapeRegex, nowIso, suggestCandidates } from './util.mjs';
+import { asString, toRepoPath, die, warn, resolveDocPath, resolveRefPath, escapeRegex, nowIso, suggestCandidates, emitFilesFooter } from './util.mjs';
 import { gitMv, getGitLastModified, getGitLastModifiedBatch } from './git.mjs';
 import { buildIndex, collectDocFiles } from './index.mjs';
 import { renderIndexFile, writeIndex } from './index-file.mjs';
@@ -68,6 +68,9 @@ function uniqueArchiveTarget(targetDir, basename) {
 
 export async function runStatus(argv, config, opts = {}) {
   const { dryRun } = opts;
+  const noIndex = argv.includes('--no-index') || opts.noIndex;
+  const showFiles = argv.includes('--show-files') || opts.showFiles;
+  argv = argv.filter(a => a !== '--no-index' && a !== '--show-files');
   const input = argv[0];
   let newStatus = argv[1];
 
@@ -167,11 +170,24 @@ export async function runStatus(argv, config, opts = {}) {
 
   // Regen the index on every status change — `active → planned` etc. drift
   // the per-status sections just as much as archive crossings. Archive paths
-  // also benefit (replaces the previously-gated regen).
-  regenIndex(config);
+  // also benefit (replaces the previously-gated regen). `--no-index` skips
+  // this so concurrent agents can do path-limited commits without pulling
+  // each other's uncommitted index changes into the staging area.
+  if (noIndex) {
+    process.stderr.write(dim('(index not regenerated — run `dotmd index` to refresh)\n'));
+  } else {
+    regenIndex(config);
+  }
 
   process.stdout.write(`${green(toRepoPath(finalPath, config.repoRoot))}: ${oldStatus ?? 'unknown'} → ${newStatus}\n`);
 
+  if (showFiles) {
+    const touched = [filePath];
+    if (finalPath !== filePath) touched.push(finalPath);
+    if (config.indexPath && !noIndex) touched.push(config.indexPath);
+    emitFilesFooter(touched, config);
+  }
+
   try { config.hooks.onStatusChange?.({ path: toRepoPath(finalPath, config.repoRoot), oldStatus, newStatus }, {
     oldPath: toRepoPath(filePath, config.repoRoot),
     newPath: toRepoPath(finalPath, config.repoRoot),
@@ -183,6 +199,8 @@ export async function runPickup(argv, config, opts = {}) {
   const json = argv.includes('--json');
   const takeover = argv.includes('--takeover');
   const fullBody = argv.includes('--full');
+  const noIndex = argv.includes('--no-index') || opts.noIndex;
+  const showFiles = argv.includes('--show-files') || opts.showFiles;
   let input = argv.find(a => !a.startsWith('-'));
 
   // Interactive: pick from active/planned plans
@@ -228,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');
@@ -253,7 +279,11 @@ export async function runPickup(argv, config, opts = {}) {
     }
     if (oldStatus !== 'in-session') {
       updateFrontmatter(filePath, { status: 'in-session', updated: today });
-      regenIndex(config);
+      if (noIndex) {
+        process.stderr.write(dim('(index not regenerated — run `dotmd index` to refresh)\n'));
+      } else {
+        regenIndex(config);
+      }
     }
     // VH append per lease outcome:
     //   acquired   → `Picked up (<old> → in-session).`
@@ -295,6 +325,12 @@ export async function runPickup(argv, config, opts = {}) {
     }
   }
 
+  if (showFiles && oldStatus !== 'in-session') {
+    const touched = [filePath];
+    if (config.indexPath && !noIndex) touched.push(config.indexPath);
+    emitFilesFooter(touched, config);
+  }
+
   try { config.hooks.onPickup?.({ path: repoPath, oldStatus, newStatus: 'in-session' }); } catch (err) { warn(`Hook 'onPickup' threw: ${err.message}`); }
 }
 
@@ -304,10 +340,13 @@ export async function runUnpickup(argv, config, opts = {}) {
   const all = argv.includes('--all');
   const stale = argv.includes('--stale');
   const force = argv.includes('--force');
+  const noIndex = argv.includes('--no-index') || opts.noIndex;
+  const showFiles = argv.includes('--show-files') || opts.showFiles;
   const toIdx = argv.indexOf('--to');
   const toStatus = toIdx >= 0 ? argv[toIdx + 1] : null;
   const positional = argv.filter((a, i) => !a.startsWith('-') && argv[i - 1] !== '--to');
   const fileArg = positional[0];
+  const touched = [];
 
   const session = currentSessionId();
   const released = [];
@@ -360,7 +399,12 @@ export async function runUnpickup(argv, config, opts = {}) {
         const today = nowIso();
         updateFrontmatter(filePath, { status: newStatus, updated: today });
         appendVersionHistory(filePath, `Released (in-session → ${newStatus}).`);
-        regenIndex(config);
+        touched.push(filePath);
+        if (noIndex) {
+          process.stderr.write(dim('(index not regenerated — run `dotmd index` to refresh)\n'));
+        } else {
+          regenIndex(config);
+        }
       }
       // If frontmatter is no longer in-session (manual flip), leave it alone.
     } catch (err) {
@@ -429,6 +473,12 @@ export async function runUnpickup(argv, config, opts = {}) {
       process.stderr.write(`${yellow('⚠ Skipped')}: ${s.path} (held by ${s.session}; use --force to override)\n`);
     }
   }
+
+  if (showFiles && touched.length > 0) {
+    const all = [...touched];
+    if (config.indexPath && !noIndex) all.push(config.indexPath);
+    emitFilesFooter(all, config);
+  }
 }
 
 export async function runFinish(argv, config, opts = {}) {
@@ -493,6 +543,9 @@ export async function runFinish(argv, config, opts = {}) {
 
 export function runArchive(argv, config, opts = {}) {
   const { dryRun, out = process.stdout } = opts;
+  const noIndex = argv.includes('--no-index') || opts.noIndex;
+  const showFiles = argv.includes('--show-files') || opts.showFiles;
+  argv = argv.filter(a => a !== '--no-index' && a !== '--show-files');
   const input = argv[0];
 
   if (!input) { die('Usage: dotmd archive <file>'); }
@@ -519,13 +572,24 @@ export function runArchive(argv, config, opts = {}) {
     const prefix = dim('[dry-run]');
     out.write(`${prefix} Would update frontmatter: status: ${oldStatus} → archived, updated: ${today}\n`);
     out.write(`${prefix} Would move: ${oldRepoPath} → ${newRepoPath}\n`);
-    if (config.indexPath) out.write(`${prefix} Would regenerate index\n`);
+    if (config.indexPath && !noIndex) out.write(`${prefix} Would regenerate index\n`);
+    if (config.indexPath && noIndex) out.write(`${prefix} Would skip index regen (--no-index)\n`);
 
     // Preview reference updates
     const refCount = countRefsToUpdate(filePath, targetPath, config);
     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;
   }
 
@@ -541,22 +605,31 @@ export function runArchive(argv, config, opts = {}) {
   const selfRefsFixed = updateRefsFromMovedFile(filePath, targetPath, config);
 
   // Auto-update references in other docs
-  const updatedRefCount = updateRefsAfterMove(filePath, targetPath, config);
+  const { count: updatedRefCount, paths: refTouchedPaths } = updateRefsAfterMove(filePath, targetPath, config);
 
-  regenIndex(config);
+  if (!noIndex) regenIndex(config);
 
   out.write(`${green('Archived')}: ${oldRepoPath} → ${newRepoPath}\n`);
   if (selfRefsFixed) out.write('Updated references in archived file.\n');
   if (updatedRefCount > 0) out.write(`Updated references in ${updatedRefCount} file(s).\n`);
-  if (config.indexPath) out.write('Index regenerated.\n');
+  if (config.indexPath && !noIndex) out.write('Index regenerated.\n');
+  if (config.indexPath && noIndex) out.write(dim('(index not regenerated — run `dotmd index` to refresh)\n'));
 
   try { releaseLease(config, oldRepoPath, { force: true }); } catch (err) { warn(`Could not release lease for ${oldRepoPath}: ${err.message}`); }
 
+  const touched = [oldRepoPath, newRepoPath, ...refTouchedPaths];
+  if (config.indexPath && !noIndex) touched.push(config.indexPath);
+  if (showFiles) emitFilesFooter(touched, config);
+
   try { config.hooks.onArchive?.({ path: newRepoPath, oldStatus }, { oldPath: oldRepoPath, newPath: newRepoPath }); } catch (err) { warn(`Hook 'onArchive' threw: ${err.message}`); }
+
+  return { touched };
 }
 
 export function runBulkArchive(argv, config, opts = {}) {
   const { dryRun } = opts;
+  const noIndex = argv.includes('--no-index') || opts.noIndex;
+  const showFiles = argv.includes('--show-files') || opts.showFiles;
   const inputs = argv.filter(a => !a.startsWith('-'));
   if (inputs.length === 0) die('Usage: dotmd bulk archive <file1> <file2> ... or <glob>');
 
@@ -592,14 +665,30 @@ export function runBulkArchive(argv, config, opts = {}) {
   }
 
   process.stdout.write('\n');
+  // Bulk archives always defer index regen to the end — N individual regens
+  // is wasteful and the final state is the same. `--no-index` skips even
+  // the final one.
+  const bulkTouched = [];
   for (const f of unique) {
     const relPath = toRepoPath(f, config.repoRoot);
     try {
-      runArchive([relPath], config, opts);
+      const result = runArchive([relPath], config, { ...opts, noIndex: true, showFiles: false });
+      if (result?.touched) bulkTouched.push(...result.touched);
     } catch (err) {
       warn(`Failed to archive ${relPath}: ${err.message}`);
     }
   }
+  if (!noIndex) {
+    regenIndex(config);
+    if (config.indexPath) process.stdout.write('Index regenerated.\n');
+  } else if (config.indexPath) {
+    process.stdout.write(dim('(index not regenerated — run `dotmd index` to refresh)\n'));
+  }
+  if (showFiles) {
+    const all = [...bulkTouched];
+    if (config.indexPath && !noIndex) all.push(config.indexPath);
+    emitFilesFooter(all, config);
+  }
 }
 
 export function runTouch(argv, config, opts = {}) {
@@ -682,7 +771,7 @@ export function runTouch(argv, config, opts = {}) {
 function updateRefsAfterMove(oldPath, newPath, config) {
   const basename = path.basename(oldPath);
   const allFiles = collectDocFiles(config);
-  let updatedCount = 0;
+  const touched = [];
 
   for (const docFile of allFiles) {
     if (docFile === newPath) continue;
@@ -710,11 +799,11 @@ function updateRefsAfterMove(oldPath, newPath, config) {
     if (newFm !== fm) {
       raw = replaceFrontmatter(raw, newFm);
       writeFileSync(docFile, raw, 'utf8');
-      updatedCount++;
+      touched.push(docFile);
     }
   }
 
-  return updatedCount;
+  return { count: touched.length, paths: touched };
 }
 
 function updateRefsFromMovedFile(oldPath, newPath, config) {

package/src/new.mjs

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { toRepoPath, die, warn, nowIso } from './util.mjs';
+import { toRepoPath, die, warn, nowIso, emitFilesFooter } from './util.mjs';
 import { green, dim, bold } from './color.mjs';
 import { isInteractive, promptText } from './prompt.mjs';
 import { regenIndex } from './lifecycle.mjs';
@@ -185,12 +185,14 @@ export async function runNew(argv, config, opts = {}) {
   let title = null;
   let rootName = opts.root ?? null;
   let messageFlag = null;
+  let showFiles = opts.showFiles ?? false;
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === '--status' && argv[i + 1]) { status = argv[++i]; continue; }
     if (argv[i] === '--title' && argv[i + 1]) { title = argv[++i]; continue; }
     if (argv[i] === '--message' && argv[i + 1]) { messageFlag = argv[++i]; continue; }
     if (argv[i] === '--root' && argv[i + 1]) { rootName = argv[++i]; continue; }
     if (argv[i] === '--config') { i++; continue; }
+    if (argv[i] === '--show-files') { showFiles = true; continue; }
     if (argv[i] === '--list-templates' || argv[i] === '--list-types') {
       listTemplates(config);
       return;
@@ -395,6 +397,12 @@ export async function runNew(argv, config, opts = {}) {
 
   regenIndex(config);
 
+  if (showFiles) {
+    const touched = [filePath];
+    if (config.indexPath) touched.push(config.indexPath);
+    emitFilesFooter(touched, config);
+  }
+
   try { config.hooks.onNew?.({ path: repoPath, status, title: docTitle, type: typeName }); } catch (err) { warn(`Hook 'onNew' threw: ${err.message}`); }
 }
 

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');
@@ -116,12 +182,14 @@ function resolvePromptInput(input, config) {
 function runPromptsUse(argv, config, opts = {}) {
   const input = argv.find(a => !a.startsWith('-'));
   if (!input) die('Usage: dotmd prompts use <file-or-slug>');
+  const noIndex = argv.includes('--no-index') || opts.noIndex;
+  const showFiles = argv.includes('--show-files') || opts.showFiles;
   const filePath = resolvePromptInput(input, config);
-  consumePrompt(filePath, config, opts);
+  consumePrompt(filePath, config, { ...opts, noIndex, showFiles });
 }
 
 function consumePrompt(filePath, config, opts) {
-  const { dryRun } = opts;
+  const { dryRun, noIndex, showFiles } = opts;
   const raw = readFileSync(filePath, 'utf8');
   const { frontmatter, body } = extractFrontmatter(raw);
   const parsed = parseSimpleFrontmatter(frontmatter);
@@ -137,21 +205,31 @@ function consumePrompt(filePath, config, opts) {
   }
 
   if (dryRun) {
-    process.stderr.write(`${dim('[dry-run]')} Would emit body and archive: ${repoPath} (${status ?? 'unknown'} → archived)\n`);
-    runArchive([filePath], config, { dryRun: true, out: process.stderr });
+    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;
   }
 
   process.stdout.write(body);
   if (!body.endsWith('\n')) process.stdout.write('\n');
 
-  runArchive([filePath], config, { out: process.stderr });
+  runArchive([filePath], config, { noIndex, showFiles, out: process.stderr });
   process.stderr.write(`${green('✓ Consumed')}: ${repoPath}\n`);
 }
 
 function runPromptsArchive(argv, config, opts = {}) {
   const input = argv.find(a => !a.startsWith('-'));
   if (!input) die('Usage: dotmd prompts archive <file-or-slug>');
+  const noIndex = argv.includes('--no-index') || opts.noIndex;
+  const showFiles = argv.includes('--show-files') || opts.showFiles;
   const filePath = resolvePromptInput(input, config);
 
   const raw = readFileSync(filePath, 'utf8');
@@ -161,7 +239,7 @@ function runPromptsArchive(argv, config, opts = {}) {
     die(`Not a prompt: ${toRepoPath(filePath, config.repoRoot)}`);
   }
 
-  runArchive([filePath], config, opts);
+  runArchive([filePath], config, { ...opts, noIndex, showFiles });
 }
 
 async function runPromptsNew(argv, config, opts = {}) {

package/src/util.mjs

@@ -55,6 +55,18 @@ export function toRepoPath(absolutePath, repoRoot) {
   return path.relative(repoRoot, absolutePath).split(path.sep).join('/');
 }
 
+// Emit a `files: a b c` line to stderr listing every doc / index path
+// the command touched (deduped, sorted, repo-relative). Lets agents do
+// `git add` with the exact set instead of guessing. Opt-in via
+// `--show-files` on lifecycle commands; default off to keep output stable.
+export function emitFilesFooter(paths, config) {
+  const rel = [...new Set(paths.filter(Boolean))]
+    .map(p => path.isAbsolute(p) ? toRepoPath(p, config.repoRoot) : p)
+    .sort();
+  if (rel.length === 0) return;
+  process.stderr.write(`files: ${rel.join(' ')}\n`);
+}
+
 export function nowIso() {
   return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
 }

package/src/validate.mjs

@@ -95,6 +95,10 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
     doc.errors.push({ path: doc.path, level: 'error', message: '`blockers` must be a YAML list when present.' });
   }
 
+  if (Object.prototype.hasOwnProperty.call(frontmatter, 'blocked_by') && !Array.isArray(frontmatter.blocked_by)) {
+    doc.errors.push({ path: doc.path, level: 'error', message: '`blocked_by` must be a YAML list when present.' });
+  }
+
   if (Object.prototype.hasOwnProperty.call(frontmatter, 'surfaces') && !Array.isArray(frontmatter.surfaces)) {
     doc.errors.push({ path: doc.path, level: 'error', message: '`surfaces` must be a YAML list when present.' });
   }