dotmd-cli 0.60.0 → 0.61.0

package/bin/dotmd.mjs

@@ -36,6 +36,8 @@ const FLAG_SPECS = {
   context: { flags: new Set(['--json', '--compact', '--summarize', '--model']), values: new Set(['--model']) },
   'agent-context': { flags: new Set(['--json']), values: new Set() },
   hud: { flags: new Set(['--json', '--subagent']), values: new Set() },
+  // '-' is the stdin marker (a positional, not a flag) — listed so validation lets it through.
+  baton: { flags: new Set(['--status', '--note', '--body', '--message', '--dry-run', '-n', '-']), values: new Set(['--status', '--note', '--body', '--message']) },
   guard: { flags: new Set(), values: new Set() },
   misuse: { flags: new Set(['--json', '--tail', '--by-rule', '--repo']), values: new Set(['--tail', '--repo']) },
   update: { flags: new Set(['--check', '--cli-only', '--plugin-only']), values: new Set() },
@@ -45,7 +47,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', 'hold', 'unhold', 'shelve', 'unshelve', 'status']),
+    subcommands: new Set(['list', 'next', 'use', 'resume', 'show', 'peek', 'archive', 'new', 'hold', 'unhold', 'shelve', 'unshelve', 'status']),
   },
 };
 
@@ -133,6 +135,7 @@ Common commands:
   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-or-slug>]  Open a doc by type: prompt → consume, plan → start, doc → read
+  baton [<plan>|<slug>] <@draft|-> Save a resume prompt (+ release the plan, if one is in-session)
                         (no file: consume oldest pending prompt)
   archive <file>        Close out a plan (status → archived, move, update refs)
 
@@ -203,7 +206,8 @@ View & Query:
   grep <term>                       Keyword search incl. document bodies (query --keyword --body --all)
   plans                             Live plans (excludes archived; --include-archived for all)
   use [<file-or-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.
+  baton [<plan>|<slug>] <@draft|->  Save a resume prompt; releases the plan + prints the commit when one is in-session
+  prompts [list|show|archive|new|hold] Prompt admin (list / peek / archive / save / hold). Use \`dotmd use\` to consume.
   stale                             Stale docs (preset)
   actionable                        Docs with next steps (preset)
 
@@ -603,7 +607,8 @@ Recommended SessionStart hook (in ~/.claude/settings.json):
   "SessionStart": [{ "hooks": [{ "type": "command", "command": "dotmd hud", "timeout": 5 }] }]
 
 Options:
-  --json                 Output as JSON ({ owned, queued, prompts, stale })`,
+  --json                 Output as JSON ({ owned, prompts, errors, previousSelf,
+                         fleet, recentRejections, misuseRecap, drift })`,
 
   briefing: `dotmd briefing — compact summary for session start
 
@@ -993,6 +998,8 @@ Subcommands:
                              targets the named prompt instead of picking oldest)
   resume <file-or-slug>      Alias for \`use\` — same behavior, easier name
                              when continuing a session
+  show <file-or-slug>        Read-only peek: print the body WITHOUT consuming
+                             (triage). \`peek\` is an alias.
   archive <file-or-slug>     Archive a prompt without printing its body
   hold <file-or-slug>        Park a prompt (status → held) under prompts/held/:
                              kept in list, hidden from hud/briefing pending
@@ -1023,10 +1030,50 @@ Examples:
   claude "$(dotmd prompts resume resume-foo)"        # \`resume\` is an alias for \`use\`
   dotmd prompt list                    # singular alias for \`dotmd prompts list\`
 
+  dotmd prompts show resume-foo        # peek without consuming (triage)
   dotmd prompts next --dry-run         # preview without consuming
   dotmd prompts archive old-thing
   dotmd prompts new my-prompt "Body text here"`,
 
+  baton: `dotmd baton — save a resume prompt for whatever you're doing (and release the plan, if there is one)
+
+The "save a resume prompt" verb. Works mid-anything:
+
+Plan mode (a plan is in-session, or you pass one):
+  1. Saves a resume prompt named resume-<plan-slug> (collision-safe: -2, -3, …).
+     The prompt is session-local — the next session's hud surfaces it; never
+     paste resume text into chat.
+  2. Releases the plan: one status flip, in-session → active by default
+     (--status to override, --note to record why in ## Version History).
+  3. Prints the exact \`git commit\` for the plan's frontmatter change — the
+     prompt stays OUT of the pathspec (it's session-local, often gitignored).
+  Which plan? Pass it explicitly, or baton resolves the one THIS session marked
+  in-session (via the journal), falling back to the only in-session plan.
+
+Slug mode (no plan involved — "save a resume prompt for this"):
+  dotmd baton <slug> @/tmp/draft.md   →  saves resume-<slug>, touches NOTHING
+  else: no status changes, no commit, no plan required. Reference any relevant
+  plans/docs inside the draft body.
+
+Usage:
+  dotmd baton [<plan-file> | <slug>] [@draft.md | - | --message "..."]
+
+Options:
+  --status <s>           Target status for the plan (default: active; plan mode only)
+  --note "why"           Append the reason to ## Version History (plan mode only)
+  --message / --body     Inline body (one-liners; prefer @path or stdin)
+  --dry-run, -n          Preview without writing
+
+Examples:
+  dotmd baton @/tmp/draft.md                       # owned plan, body from file
+  dotmd baton checkout-fixes @/tmp/draft.md        # no plan: just save resume-checkout-fixes
+  cat /tmp/draft.md | dotmd baton                  # body from stdin
+  dotmd baton docs/plans/auth.md @/tmp/draft.md    # explicit plan
+  dotmd baton --status paused --note "blocked on review" @/tmp/d.md
+
+Write the draft FIRST (10–20 lines): the next concrete decision plus any
+gotchas — not a recap of the plan body.`,
+
   stale: `dotmd stale — list stale documents
 
 Shows docs that haven't been updated within their staleness threshold.
@@ -1339,6 +1386,14 @@ async function main() {
     await runUse(restArgs, config, { dryRun });
     return;
   }
+  // `dotmd baton [plan] <@draft|->` — the one-command handoff: save the resume
+  // prompt, release the plan (one status flip), print the exact commit. See
+  // src/baton.mjs for why this is a single verb and not a skill choreography.
+  if (command === 'baton') {
+    const { runBaton } = await import('../src/baton.mjs');
+    await runBaton(restArgs, config, { dryRun });
+    return;
+  }
   // `dotmd next` is a top-level alias for `dotmd use` with no arg — consume
   // the oldest pending prompt. Wired separately so agents who reach for the
   // literal verb "next" don't bounce off an Unknown-command. Any positional

package/dotmd.config.example.mjs

@@ -193,7 +193,11 @@ export const presets = {
 // Properties:
 //   description:    string — shown in `dotmd new --list-types`
 //   defaultStatus:  string — initial status if `--status` not passed
-//   requiresBody:   boolean — error if no body input (see `prompt` builtin)
+//   acceptsBody:    boolean — allow body input (inline / --body / @file / piped stdin).
+//                   REQUIRED if you want `cat draft.md | dotmd new <type> <slug>` (or @path,
+//                   --body, heredoc) to work. Your `body` fn must also interpolate the input,
+//                   e.g. `${ctx?.bodyInput?.trim() ?? ''}`. See the body-acceptance guard below.
+//   requiresBody:   boolean — error if no body input (implies acceptsBody; see `prompt` builtin)
 //   targetRoot:     string — name (basename or suffix) of the root this type lives in.
 //                   In flat-array `root` configs (e.g. ['docs/plans', 'docs/prompts']),
 //                   the new doc lands in the matching root. Falls back to `config.docsRoot`
@@ -203,7 +207,17 @@ export const presets = {
 //                   under `docsRoot='docs'`, `dir` puts files in `docs/plans/` and `docs/prompts/`;
 //                   under flat-array roots, `targetRoot` routes directly to the type-specific root.
 //   frontmatter:    (status, isoTime, ctx) => string
-//   body:           (title, ctx) => string
+//   body:           (title, ctx) => string — slot user-supplied body via `ctx.bodyInput`
+//
+// Body-acceptance guard (the #1 custom-template gotcha):
+//   When you override a builtin and supply your OWN `body` fn that NEVER references
+//   `bodyInput`, dotmd assumes the fn would silently discard piped input — so it strips
+//   the inherited `acceptsBody`/`requiresBody` and rejects body input with a fail-fast
+//   error. Two ways to keep piped/@path/heredoc bodies working in a custom template:
+//     1. interpolate `${ctx?.bodyInput?.trim() ?? ''}` somewhere in your `body` fn, OR
+//     2. set `acceptsBody: true` explicitly (do BOTH if you want the input to actually land).
+//   A `body: (t) =>` that ignores `ctx` is the classic trap — it scaffolds fine but
+//   `dotmd new <type> <slug> < draft.md` errors until you wire in `bodyInput`.
 //
 // Custom type example — adds a `spike` type that lives in the `spikes` root (or
 // under `docs/spikes/` in single-root layouts):
@@ -218,8 +232,11 @@ export const presets = {
 //   },
 //
 //   // Override a builtin (e.g. project-specific prompt frontmatter shape).
-//   // IMPORTANT: builtin properties are NOT inherited — re-declare `targetRoot`, `dir`,
-//   // `defaultStatus`, `requiresBody`, etc. that you want preserved.
+//   // Overrides shallow-merge OVER the builtin: any property you omit is inherited
+//   // (`targetRoot`, `dir`, `defaultStatus`, `requiresBody`, …), and anything you declare
+//   // wins. EXCEPTION: if you supply your own `body` fn that doesn't reference `bodyInput`,
+//   // the inherited `acceptsBody`/`requiresBody` are dropped (see the guard above) — so
+//   // re-declare `acceptsBody: true` and wire in `ctx.bodyInput` if you want piped bodies.
 //   // prompt: {
 //   //   description: 'Project resume prompt',
 //   //   defaultStatus: 'pending',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.60.0",
+  "version": "0.61.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/baton.mjs

@@ -0,0 +1,231 @@
+import { readFileSync, fstatSync } from 'node:fs';
+import path from 'node:path';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { asString, toRepoPath, die, warn, currentSessionId } from './util.mjs';
+import { buildIndex, resolveDocArg } from './index.mjs';
+import { readJournalEntries } from './journal.mjs';
+import { runNew, readBodyInput } from './new.mjs';
+import { runSet } from './lifecycle.mjs';
+import { green, dim } from './color.mjs';
+
+// `dotmd baton` is the one-command handoff: save the resume prompt AND release
+// the plan in a single atomic-ish verb. It exists because the three-step skill
+// version ("save prompt, pick a status, commit") kept expanding in practice —
+// sessions turned closeout into repo triage, forgot the prompt body, or got
+// tangled in what to commit. Baton does exactly one plan, one prompt, one
+// status flip, and then *tells* the agent the exact commit command.
+
+// Does a journal argv doc reference point at this index doc? References come
+// from `use <x>` / `set in-session <x>` invocations, so they may be a repo
+// path, a bare basename, or a slug without .md.
+function matchesDocRef(doc, ref) {
+  if (typeof ref !== 'string' || !ref) return false;
+  const cleaned = ref.replace(/^\.\//, '');
+  if (doc.path === cleaned) return true;
+  const base = path.basename(doc.path, '.md');
+  if (cleaned === base || cleaned === `${base}.md`) return true;
+  return doc.path.endsWith(`/${cleaned}`) || doc.path.endsWith(`/${cleaned}.md`);
+}
+
+// Resolve which in-session plan belongs to THIS session. There is no checkout
+// or lock — in-session is just frontmatter — so ownership is reconstructed
+// from the per-repo journal: the last `use <plan>` / `set in-session <plan>`
+// this sid ran whose target is still in-session. Falls back to "the only
+// in-session plan" when the journal can't answer (disabled, or another tool
+// flipped the status). Returns { plan, via, inSession }; plan is null when
+// there's no defensible answer (caller decides how to ask).
+export function findOwnedPlan(config, index = null) {
+  const idx = index ?? buildIndex(config);
+  const inSession = idx.docs.filter(d => d.type === 'plan' && d.status === 'in-session');
+  if (inSession.length === 0) return { plan: null, via: null, inSession };
+
+  const sid = currentSessionId();
+  let entries = [];
+  try { entries = readJournalEntries(config); } catch { entries = []; }
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const e = entries[i];
+    if (e?.sid !== sid || !Array.isArray(e.argv) || (e.exit ?? 0) !== 0) continue;
+    const a = e.argv;
+    let ref = null;
+    if (a[0] === 'use') ref = a.slice(1).find(x => typeof x === 'string' && !x.startsWith('-'));
+    else if (a[0] === 'set' && a[1] === 'in-session') ref = a.slice(2).find(x => typeof x === 'string' && !x.startsWith('-'));
+    else if (a[0] === 'status' && a.includes('in-session')) ref = a.slice(1).find(x => typeof x === 'string' && !x.startsWith('-') && x !== 'in-session');
+    if (!ref) continue;
+    const doc = inSession.find(d => matchesDocRef(d, ref));
+    if (doc) return { plan: doc, via: 'journal', inSession };
+  }
+
+  if (inSession.length === 1) return { plan: inSession[0], via: 'single-in-session', inSession };
+  return { plan: null, via: null, inSession };
+}
+
+const BODY_USAGE = `dotmd baton needs the resume draft as its body. Write 10–20 lines first — the next concrete decision plus any gotchas, NOT a recap of the plan — then:
+  dotmd baton @/tmp/draft.md             # body from file (preferred)
+  cat /tmp/draft.md | dotmd baton        # body from stdin
+  dotmd baton --message "..."            # one-liner
+No plan in-session? Name the handoff instead: dotmd baton <slug> @/tmp/draft.md`;
+
+// Is this positional a filesystem reference (must resolve, typos die) or a
+// bare word (may be a plan slug, may be a brand-new handoff name)?
+function looksLikePath(arg) {
+  return arg.includes('/') || arg.endsWith('.md');
+}
+
+export async function runBaton(argv, config, opts = {}) {
+  const { dryRun } = opts;
+
+  let status = 'active';
+  let statusFlag = false;
+  let note = null;
+  let bodyFlag = null;
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--status' && argv[i + 1]) { status = argv[++i]; statusFlag = true; continue; }
+    if (a === '--note' && argv[i + 1]) { note = argv[++i]; continue; }
+    if ((a === '--body' || a === '--message') && argv[i + 1]) { bodyFlag = argv[++i]; continue; }
+    if (!a.startsWith('-') || a === '-' || a.startsWith('@')) { positionals.push(a); continue; }
+    die(`Unknown flag for \`dotmd baton\`: ${a}`);
+  }
+
+  let planArg = null;
+  let bodyArg = null;
+  for (const p of positionals) {
+    if (p === '-' || p.startsWith('@')) { bodyArg = p; continue; }
+    if (!planArg) { planArg = p; continue; }
+    if (bodyArg === null) bodyArg = p; // trailing inline body
+  }
+
+  // Body FIRST — it's the common failure (`new prompt` without a body was the
+  // top real-world baton error), and nothing must mutate before it's secured.
+  let body = null;
+  if (bodyFlag !== null) body = bodyFlag;
+  else if (bodyArg !== null) body = readBodyInput(bodyArg);
+  else {
+    // Auto-consume piped/redirected stdin, same probe as `dotmd new`.
+    try {
+      const stat = fstatSync(0);
+      if (stat.isFIFO() || stat.isFile() || stat.isSocket()) {
+        const piped = readFileSync(0, 'utf8');
+        if (piped.length > 0) body = piped;
+      }
+    } catch { /* stdin not introspectable */ }
+  }
+  if (!body || !body.trim()) die(BODY_USAGE);
+
+  // Resolve what's being handed off. Two modes:
+  //   plan mode — a plan is released alongside the prompt (one status flip).
+  //   slug mode — no plan involved: "save a resume prompt for what I'm doing
+  //   right now". The hallmark use ("update the docs and save a resume prompt
+  //   for this") must work mid-anything, claimed plan or not — baton does
+  //   nothing but save the prompt in this mode.
+  let planPath = null;
+  let promptSlug = null;
+  if (planArg) {
+    if (looksLikePath(planArg)) {
+      planPath = resolveDocArg(planArg, config); // typos die loudly — a mistyped path must not silently become a prompt name
+    } else {
+      // Bare word: a plan slug if it resolves to a plan, else a handoff name.
+      const resolved = resolveDocArg(planArg, config, { dieOnMiss: false });
+      let resolvedType = null;
+      if (resolved) {
+        try {
+          const { frontmatter: fmProbe } = extractFrontmatter(readFileSync(resolved, 'utf8'));
+          resolvedType = fmProbe ? asString(parseSimpleFrontmatter(fmProbe).type) : null;
+        } catch { resolvedType = null; }
+      }
+      if (resolved && resolvedType === 'plan') planPath = resolved;
+      else promptSlug = planArg;
+    }
+  } else {
+    const owned = findOwnedPlan(config);
+    if (owned.plan) {
+      planPath = path.resolve(config.repoRoot, owned.plan.path);
+      if (owned.via === 'single-in-session') {
+        process.stderr.write(dim(`Handing off the only in-session plan: ${owned.plan.path}\n`));
+      }
+    } else if (owned.inSession.length > 1) {
+      die(`Multiple plans are in-session and the journal can't tell which is this session's — pass yours explicitly:\n${owned.inSession.map(d => '  dotmd baton ' + d.path + ' @/tmp/draft.md').join('\n')}\nNot about a plan? Name the handoff instead: dotmd baton <slug> @/tmp/draft.md`);
+    } else {
+      die(`No in-session plan, so baton needs a name for the resume prompt:\n  dotmd baton <slug> @/tmp/draft.md      # saves resume-<slug>, touches nothing else\nHanding off a specific plan? dotmd baton <plan-file> @/tmp/draft.md`);
+    }
+  }
+
+  let repoPath = null;
+  let oldStatus = null;
+  if (planPath) {
+    repoPath = toRepoPath(planPath, config.repoRoot);
+    const raw = readFileSync(planPath, 'utf8');
+    const { frontmatter: fmRaw } = extractFrontmatter(raw);
+    if (!fmRaw) {
+      die(`${repoPath} has no frontmatter block — baton can't flip its status.\nFix the doc first (\`dotmd bulk-tag ${repoPath} --type plan --status in-session\`), or save the prompt without a status flip: dotmd baton ${path.basename(planPath, '.md')} @/tmp/draft.md`);
+    }
+    const fm = parseSimpleFrontmatter(fmRaw);
+    const docType = asString(fm.type);
+    oldStatus = asString(fm.status) ?? 'unset';
+    if (docType && docType !== 'plan') warn(`${repoPath} has type '${docType}', not 'plan'.`);
+
+    // Validate the target status BEFORE creating the prompt so a bad --status
+    // doesn't leave a half-done handoff.
+    const validStatuses = config.typeStatuses?.get(docType ?? 'plan') ?? config.validStatuses;
+    if (validStatuses && validStatuses.size > 0 && !validStatuses.has(status)) {
+      die(`Invalid status \`${status}\` for type \`${docType ?? 'plan'}\`\nValid: ${[...validStatuses].join(', ')}`);
+    }
+  } else {
+    if (statusFlag) warn(`--status ignored — no plan involved in this handoff (saving the prompt only).`);
+    if (note) warn(`--note ignored — no plan involved in this handoff (notes land in a plan's Version History).`);
+  }
+
+  // 1. Save the resume prompt. Collision-safe: resume-<slug>, then -2, -3, …
+  // (a pending resume-<slug> from an earlier handoff must never block this one,
+  // and bodies are not mergeable).
+  const nameBase = planPath ? path.basename(planPath, '.md') : promptSlug;
+  const slugBase = nameBase.startsWith('resume-') ? nameBase : `resume-${nameBase}`;
+  let createdSlug = null;
+  for (let n = 1; n <= 9 && !createdSlug; n++) {
+    const slug = n === 1 ? slugBase : `${slugBase}-${n}`;
+    try {
+      await runNew(['prompt', slug, '--body', body], config, { dryRun });
+      createdSlug = slug;
+    } catch (err) {
+      if (!/File already exists/.test(String(err?.message))) throw err;
+    }
+  }
+  if (!createdSlug) die(`Could not find a free prompt slug for ${slugBase} (tried ${slugBase}-2 … ${slugBase}-9).`);
+
+  // 2. Release the plan — exactly one status flip. Skipped entirely in slug
+  // mode: with no plan involved there is nothing to release.
+  let archiveResult = null;
+  let statusChanged = false;
+  if (planPath) {
+    if (oldStatus === status) {
+      process.stderr.write(dim(`Plan already ${status}: ${repoPath} (no status change)\n`));
+    } else {
+      const setArgs = [status, planPath];
+      if (note) setArgs.push('--note', note);
+      archiveResult = await runSet(setArgs, config, { dryRun });
+      statusChanged = true;
+    }
+  }
+
+  // 3. Tell the agent exactly what to commit — and what NOT to. The prompt is
+  // session-local (often gitignored); only the plan's frontmatter change is
+  // repo state.
+  const prefix = dryRun ? dim('[dry-run] ') : '';
+  process.stderr.write(`\n${prefix}${green('✓ Baton passed')}: ${createdSlug} (the next session's hud surfaces it — nothing to paste into chat)\n`);
+  if (statusChanged) {
+    const newRepoPath = archiveResult?.newRepoPath ?? null;
+    const pathspec = newRepoPath && newRepoPath !== repoPath ? `${repoPath} ${newRepoPath}` : repoPath;
+    let gitignored = false;
+    try {
+      const { isGitIgnored } = await import('./git.mjs');
+      gitignored = isGitIgnored(planPath, config.repoRoot);
+    } catch { /* not a git repo — fall through to the hint */ }
+    if (gitignored) {
+      process.stderr.write(dim(`${repoPath} is gitignored — no commit needed.\n`));
+    } else {
+      process.stderr.write(`${prefix}Commit the plan's status change (keep the prompt OUT of the pathspec — it's session-local):\n`);
+      process.stderr.write(`${prefix}  git commit -m "baton: ${path.basename(planPath, '.md')} ${oldStatus} → ${status}" -- ${pathspec}\n`);
+    }
+  }
+}

package/src/commands.mjs

@@ -9,5 +9,5 @@ export const KNOWN_COMMANDS = [
   'fix-refs', 'lint', 'rename', 'migrate', 'notion', 'export', 'summary',
   'watch', 'diff', 'new', 'init', 'completions', 'statuses', 'journal',
   'guard', 'misuse', 'update',
-  'ship', 'self-check',
+  'ship', 'self-check', 'baton',
 ];

package/src/doctor.mjs

@@ -155,6 +155,30 @@ function findDeprecatedCommandMentions(config) {
   return matches;
 }
 
+// Workflow-drift checks: configurations and docs that make the agent-facing
+// verbs (`use`, `set`, `baton`) blow up at the worst moment — mid-handoff.
+// Both failure modes came from real sessions: a repo whose plan vocab dropped
+// `in-session` (every `dotmd use` died), and a repo full of docs without
+// frontmatter blocks (every `dotmd set` died during closeout).
+function findWorkflowDrift(config) {
+  const docsWithoutFrontmatter = [];
+  for (const filePath of collectDocFiles(config)) {
+    let raw = '';
+    try { raw = readFileSync(filePath, 'utf8'); } catch { continue; }
+    if (!raw.startsWith('---\n')) docsWithoutFrontmatter.push(toRepoPath(filePath, config.repoRoot));
+  }
+
+  const planStatusGaps = [];
+  const planStatuses = config.typeStatuses?.get('plan');
+  if (planStatuses && planStatuses.size > 0) {
+    for (const required of ['in-session', 'active']) {
+      if (!planStatuses.has(required)) planStatusGaps.push(required);
+    }
+  }
+
+  return { docsWithoutFrontmatter, planStatusGaps };
+}
+
 function runDoctorProject(config, { json = false } = {}) {
   const cliPackage = readJsonIfPresent(new URL('../package.json', import.meta.url));
   const repoPackage = readJsonIfPresent(path.join(config.repoRoot, 'package.json'));
@@ -165,11 +189,14 @@ function runDoctorProject(config, { json = false } = {}) {
     ?? null;
   const claudeCommandWarnings = checkClaudeCommands(config.repoRoot);
   const deprecatedCommandMentions = findDeprecatedCommandMentions(config);
+  const { docsWithoutFrontmatter, planStatusGaps } = findWorkflowDrift(config);
   const result = {
     cliVersion: cliPackage?.version ?? null,
     packageDependency: depVersion,
     claudeCommandWarnings,
     deprecatedCommandMentions,
+    docsWithoutFrontmatter,
+    planStatusGaps,
   };
 
   if (json) {
@@ -187,6 +214,17 @@ function runDoctorProject(config, { json = false } = {}) {
   } else {
     process.stdout.write('- docs mentioning deprecated commands: 0\n');
   }
+  if (docsWithoutFrontmatter.length) {
+    process.stdout.write(yellow(`- docs without a frontmatter block: ${docsWithoutFrontmatter.length} — every status verb (\`set\`, \`archive\`, \`baton\`) dies on these. Fix: dotmd bulk-tag <file> --type <type> --status <status>`) + '\n');
+    for (const file of docsWithoutFrontmatter.slice(0, 10)) process.stdout.write(`  - ${file}\n`);
+  } else {
+    process.stdout.write('- docs without a frontmatter block: 0\n');
+  }
+  if (planStatusGaps.length) {
+    process.stdout.write(yellow(`- plan status vocab missing: ${planStatusGaps.join(', ')} — \`dotmd use\` and \`dotmd baton\` depend on these; add them to types.plan.statuses in dotmd.config.mjs`) + '\n');
+  } else {
+    process.stdout.write('- plan status vocab: ok\n');
+  }
   return result;
 }
 

package/src/guard.mjs

@@ -58,6 +58,45 @@ function shellTokens(command) {
   return command.split(/\s+/).map(t => t.replace(/^['"]|['"]$/g, '')).filter(Boolean);
 }
 
+// Drop heredoc bodies, keeping the command line that opens them. Heredoc
+// bodies are document content — resume-prompt drafts routinely mention
+// `docs/prompts/…` paths and even describe the guard's own rules, and none of
+// that is the *command* doing anything.
+function stripHeredocBodies(command) {
+  if (typeof command !== 'string' || !command.includes('<<')) return command;
+  const lines = command.split('\n');
+  const out = [];
+  let marker = null;
+  for (const line of lines) {
+    if (marker !== null) {
+      if (line.trim() === marker) marker = null;
+      continue;
+    }
+    out.push(line);
+    const m = line.match(/<<-?\s*(['"]?)(\w+)\1/);
+    if (m) marker = m[2];
+  }
+  return out.join('\n');
+}
+
+// Split a compound command into independently-evaluated segments. Each side of
+// a pipe / && / || / ; / newline runs its own program, so a rule should only
+// fire on the segment whose program actually touches the prompt — `dotmd check
+// docs/prompts/x.md; git commit -- docs/plans/y.md` commits no prompt.
+function shellSegments(command) {
+  return stripHeredocBodies(command)
+    .split(/\|\|?|&&|;|\n/)
+    .map(s => s.trim())
+    .filter(Boolean);
+}
+
+// Blank out quoted strings that contain whitespace — prose, not paths. A
+// commit message like `-m "handoff saved to docs/prompts/x.md"` only *mentions*
+// a prompt; `git add "docs/prompts/foo.md"` (no inner whitespace) survives.
+function stripProseStrings(s) {
+  return s.replace(/"([^"]*)"|'([^']*)'/g, (m, d, q) => (/\s/.test(d ?? q ?? '') ? '""' : m));
+}
+
 // Decision level for the status-edit rules. Hand-editing `status:` has no
 // legitimate variant — `dotmd set` is a complete substitute — so it denies by
 // default. `guard: { deny: false }` in config drops it back to warn-only.
@@ -87,48 +126,57 @@ const STREAM_EDITOR_INPLACE = [
 ];
 
 function evalBash(command, config, isIgnored) {
-  const tokens = shellTokens(command);
-  const promptTokens = tokens.filter(isPromptPath);
+  const segments = shellSegments(command);
 
-  // Rule A — committing/adding a gitignored prompt. The exact failure the guard
-  // exists for: an agent reflexively `git add`s a session-local prompt that
-  // lives under a gitignored path, and the commit dies confusingly.
-  if (/\bgit\s+(add|commit|stage)\b/.test(command) && promptTokens.length) {
-    const ignored = promptTokens.filter(p => isIgnored(p));
-    const targets = ignored.length ? ignored : promptTokens;
-    const ignoredNote = ignored.length
-      ? ` ${ignored.join(', ')} is gitignored — it cannot be committed.`
-      : '';
-    return {
-      decision: 'deny',
-      rule: 'commit-prompt',
-      detail: command,
-      reason:
-        `Saved prompts (${targets.join(', ')}) are session-local dotmd artifacts, not source to commit.${ignoredNote} ` +
-        `Don't git add/commit them. The next session consumes a prompt with \`dotmd use <file>\` (or \`dotmd use\` for the oldest pending), which prints the body and archives it atomically.`,
-    };
-  }
+  for (const seg of segments) {
+    const segTokens = shellTokens(stripProseStrings(seg));
+    if (!segTokens.length) continue;
+    const cmd0 = path.basename(segTokens[0]);
+    const promptTokens = segTokens.filter(isPromptPath);
+
+    // Rule A — committing/adding a gitignored prompt. The exact failure the
+    // guard exists for: an agent reflexively `git add`s a session-local prompt
+    // that lives under a gitignored path, and the commit dies confusingly.
+    // Scoped to the git segment's own arguments: a prompt path in a sibling
+    // segment (`dotmd check docs/prompts/x.md; git commit …`) or inside a
+    // quoted commit message is a mention, not a commit.
+    if (cmd0 === 'git' && /^(add|commit|stage)$/.test(segTokens[1] ?? '') && promptTokens.length) {
+      const ignored = promptTokens.filter(p => isIgnored(p));
+      const targets = ignored.length ? ignored : promptTokens;
+      const ignoredNote = ignored.length
+        ? ` ${ignored.join(', ')} is gitignored — it cannot be committed.`
+        : '';
+      return {
+        decision: 'deny',
+        rule: 'commit-prompt',
+        detail: command,
+        reason:
+          `Saved prompts (${targets.join(', ')}) are session-local dotmd artifacts, not source to commit.${ignoredNote} ` +
+          `Don't git add/commit them — commit your other changes without the prompt in the pathspec. ` +
+          `The next session consumes a prompt with \`dotmd use <file>\` (or \`dotmd use\` for the oldest pending), which prints the body and archives it atomically.`,
+      };
+    }
 
-  // Rule B — reading a prompt through the shell instead of consuming it.
-  if (tokens.length) {
-    const cmd0 = path.basename(tokens[0]);
+    // Rule B — reading a prompt through the shell instead of consuming it.
     if (SHELL_READERS.has(cmd0) && promptTokens.length) {
       return {
         decision: 'warn',
         rule: 'cat-prompt',
         detail: command,
         reason:
-          `${promptTokens.join(', ')} is a saved dotmd prompt. Don't \`${cmd0}\` it — run \`dotmd use ${promptTokens[0]}\` ` +
-          `to print the body and archive it in one atomic step (prevents the same prompt being consumed twice). Use \`dotmd use\` with no arg for the oldest pending prompt.`,
+          `${promptTokens.join(', ')} is a saved dotmd prompt. To start work from it, run \`dotmd use ${promptTokens[0]}\` — ` +
+          `it prints the body and archives the prompt in one atomic step (prevents double-consumption). ` +
+          `Just peeking or triaging (not consuming)? \`dotmd prompts show ${promptTokens[0]}\` reads it without archiving. Don't \`${cmd0}\` it directly.`,
       };
     }
   }
 
   // Rule C — in-place stream-editing `status:` in a managed doc. Same wrong-move
-  // as the Edit-tool rule, reached via the shell.
-  const beforeHeredoc = command.split(/<<-?\s*['"]?\w/)[0];
-  if (/status/.test(beforeHeredoc) && STREAM_EDITOR_INPLACE.some(re => re.test(beforeHeredoc))) {
-    const managed = shellTokens(beforeHeredoc).filter(t => isManagedDoc(t, config));
+  // as the Edit-tool rule, reached via the shell. Heredoc bodies are document
+  // content (often prose *describing* these rules), not commands.
+  const stripped = stripHeredocBodies(command);
+  if (/status/.test(stripped) && STREAM_EDITOR_INPLACE.some(re => re.test(stripped))) {
+    const managed = shellTokens(stripped).filter(t => isManagedDoc(t, config));
     if (managed.length) {
       return editStatusResult(managed[0], config, command);
     }
@@ -144,7 +192,8 @@ function evalRead(filePath) {
     rule: 'read-prompt',
     detail: filePath,
     reason:
-      `${filePath} is a saved dotmd prompt. Prefer \`dotmd use ${filePath}\` over reading it directly — it prints the body and archives the prompt atomically so it can't be double-consumed.`,
+      `${filePath} is a saved dotmd prompt. To start work from it, run \`dotmd use ${filePath}\` — it prints the body and archives the prompt atomically so it can't be double-consumed. ` +
+      `Just peeking or triaging (not consuming)? \`dotmd prompts show ${filePath}\` reads it without archiving.`,
   };
 }
 
@@ -205,8 +254,11 @@ function readStdin() {
       process.stdin.on('data', (c) => { data += c; });
       process.stdin.on('end', () => resolve(data));
       process.stdin.on('error', () => resolve(data));
-      // Don't hang the tool dispatch if stdin never closes.
-      setTimeout(() => resolve(data), 2000);
+      // Don't hang the tool dispatch if stdin never closes. unref() so the
+      // timer can't hold the event loop open — without it every guard
+      // invocation lingered the full 2s AFTER answering, which added ~2s of
+      // dead latency to every guarded tool call in every session.
+      setTimeout(() => resolve(data), 2000).unref();
     } catch {
       resolve(data);
     }

package/src/hud.mjs

@@ -8,6 +8,7 @@ import { buildIndex } from './index.mjs';
 import { refreshStaleSlashCommands } from './claude-commands.mjs';
 import { readJournalEntries, journalFilePath, readMisuseEntries } from './journal.mjs';
 import { compareVersions } from './update.mjs';
+import { findOwnedPlan } from './baton.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
@@ -51,6 +52,8 @@ export function actionablePromptStatuses(config) {
   return new Set(['pending']);
 }
 
+// Returns repo paths, oldest-created first — the same order no-arg `dotmd use`
+// consumes them, so prompts[0] is always "the one you'd pick up next".
 function findActionablePrompts(config) {
   const roots = config.docsRoots || (config.docsRoot ? [config.docsRoot] : []);
   const archiveDir = config.archiveDir || 'archived';
@@ -80,11 +83,13 @@ function findActionablePrompts(config) {
       const fm = parseSimpleFrontmatter(frontmatter);
       if (asString(fm.type) !== 'prompt') continue;
       if (!actionable.has(asString(fm.status))) continue;
-      found.push(toRepoPath(filePath, config.repoRoot));
+      found.push({ path: toRepoPath(filePath, config.repoRoot), created: asString(fm.created) ?? '' });
     }
   }
 
-  return found.sort();
+  return found
+    .sort((a, b) => a.created.localeCompare(b.created) || a.path.localeCompare(b.path))
+    .map(p => p.path);
 }
 
 // F17b: hud reads journal. Three additive sections, gated on
@@ -200,8 +205,8 @@ const MISUSE_RECAP_THRESHOLD = 3;
 
 const MISUSE_CORRECTIONS = {
   'edit-status': 'never hand-edit `status:`; use `dotmd set <status> <file>`',
-  'cat-prompt': 'read saved prompts with `dotmd use <file>`',
-  'read-prompt': 'read saved prompts with `dotmd use <file>`',
+  'cat-prompt': 'consume prompts with `dotmd use <file>`; peek without consuming via `dotmd prompts show <file>`',
+  'read-prompt': 'consume prompts with `dotmd use <file>`; peek without consuming via `dotmd prompts show <file>`',
   'commit-prompt': 'saved prompts are session-local; never git add/commit them',
 };
 
@@ -235,6 +240,10 @@ export function buildHud(config) {
   // SessionStart for platform-scale corpora. Per-file validation + checkIndex
   // still run, so the error count matches `dotmd check`'s.
   let errors = 0;
+  // `owned` answers "which plan is THIS session's?" for programmatic callers
+  // (the baton flow reads it) — derived from the journal, falling back to the
+  // only in-session plan. Null when there's no defensible answer.
+  let owned = null;
   try {
     // `autoHealIndex: true` mirrors `dotmd check` — drift from non-regen
     // mutation paths (`lint --fix`, direct file edits, etc.) heals silently
@@ -242,12 +251,14 @@ export function buildHud(config) {
     // spurious "Run `dotmd index`" error in the hud error count.
     const index = buildIndex(config, { errorsOnly: true, autoHealIndex: true });
     errors = index.errors.length;
+    const o = findOwnedPlan(config, index);
+    if (o.plan) owned = { path: o.plan.path, title: o.plan.title ?? null, via: o.via };
   } catch { /* swallow — bad config shouldn't break the SessionStart hook */ }
 
   const { previousSelf, fleet, recentRejections } = buildJournalSections(config);
   const misuseRecap = buildMisuseRecap(config);
 
-  return { prompts, errors, previousSelf, fleet, recentRejections, misuseRecap };
+  return { owned, prompts, errors, previousSelf, fleet, recentRejections, misuseRecap };
 }
 
 // Subagent primer: a spawned subagent (Explore, Plan, general-purpose) starts
@@ -311,19 +322,30 @@ export function runHud(argv, config) {
     return;
   }
 
-  // SessionStart contract: emit ONLY the command primer — the verb cheat-sheet
-  // that tells the agent which dotmd verbs exist. Everything else hud used to
-  // print (held/prompts/stuck/errors state, slash-command refresh notices, and
-  // the journal-aware previous-self / fleet / recent-rejections sections) is
-  // deliberately suppressed here: those signals nudged agents into phantom
-  // follow-up work — e.g. "errors: 1 (run dotmd check)" prompting a check run
-  // for state that belongs inside its own command. Each of those signals lives
-  // in its proper command (`plans`, `prompts`, `check`) and stays available via
-  // `dotmd hud --json` for programmatic callers. The hook's job is purely to
-  // teach the verbs, never to report status. The misuse recap below is the one
-  // exception because it IS teaching: a repeat-offense rule means the primer
-  // alone isn't landing, so name the specific habit to break.
-  process.stdout.write(dim('dotmd: plans|briefing  set <status> [<file>]  new <type> <slug>  use [<file>]  archive <file>  (use [no-arg] → oldest pending prompt)') + '\n');
+  // SessionStart contract: the command primer, plus ONLY signals that carry a
+  // direct instruction for this session. Passive state (error counts,
+  // slash-command refresh notices, previous-self / fleet / recent-rejections)
+  // stays suppressed — those nudged agents into phantom follow-up work (e.g.
+  // "errors: 1" prompting a check run) and live in their proper commands and
+  // `dotmd hud --json`. Two signals ARE instructions and must print, because
+  // the handoff loop dies without them (sessions were saving batons that no
+  // next session ever picked up):
+  //   - pending prompts: the previous session queued work for THIS one;
+  //     consuming it is the very next action.
+  //   - an in-session plan attributed to this sid via the journal: this
+  //     session (pre-compaction) owns it and should continue or hand it off.
+  //     The single-in-session fallback is deliberately NOT printed — at
+  //     SessionStart that plan likely belongs to another live session.
+  // The misuse recap stays for the same reason: a repeat-offense rule means
+  // the primer alone isn't landing, so name the habit to break.
+  process.stdout.write(dim('dotmd: plans|briefing  set <status> [<file>]  new <type> <slug>  use [<file>]  archive <file>  baton [<slug>] <@draft|-> (save a resume prompt; releases the in-session plan if any)  (use [no-arg] → oldest pending prompt)') + '\n');
+  if (hud.owned && hud.owned.via === 'journal') {
+    process.stdout.write(yellow(`[dotmd] in-session (yours): ${hud.owned.path} — continue it; hand off with \`dotmd baton @/tmp/draft.md\` before stopping.`) + '\n');
+  }
+  if (hud.prompts.length > 0) {
+    const n = hud.prompts.length;
+    process.stdout.write(yellow(`[dotmd] ${n} pending prompt${n === 1 ? '' : 's'} queued for this session — unless the user asks for something else, start by running \`dotmd use\` to consume the oldest (${hud.prompts[0]}) and act on it. Peek first: \`dotmd prompts show <file>\`; list: \`dotmd prompts\`.`) + '\n');
+  }
   if (hud.misuseRecap) process.stdout.write(yellow(`[dotmd] ${hud.misuseRecap}`) + '\n');
   if (drift) process.stdout.write(yellow(drift) + '\n');
 }

package/src/lifecycle.mjs

@@ -928,7 +928,10 @@ export function appendVersionHistory(filePath, entry, { createSection = false }
 
 export function updateFrontmatter(filePath, updates) {
   const raw = readFileSync(filePath, 'utf8');
-  if (!raw.startsWith('---\n')) throw new Error(`${filePath} has no frontmatter block.`);
+  // Name the remedy in the error: this is where every status verb lands when a
+  // doc was created outside dotmd, and "no frontmatter block" alone left
+  // sessions retrying other verbs instead of fixing the doc.
+  if (!raw.startsWith('---\n')) throw new Error(`${filePath} has no frontmatter block. Retrofit it first: dotmd bulk-tag ${filePath} --type <type> --status <status>`);
 
   const endMarker = raw.indexOf('\n---\n', 4);
   if (endMarker === -1) throw new Error(`${filePath} has unclosed frontmatter block.`);

package/src/new.mjs

@@ -256,7 +256,7 @@ function mergeBodyFrontmatter(scaffoldFm, overrides, cliType) {
   return fm;
 }
 
-function readBodyInput(source) {
+export function readBodyInput(source) {
   if (source === '-') {
     try { return readFileSync(0, 'utf8'); } catch (err) { die(`Could not read body from stdin: ${err.message}`); }
   }
@@ -548,6 +548,12 @@ export async function runNew(argv, config, opts = {}) {
   if (typeName === 'prompt') {
     process.stdout.write(dim('Session-local — no need to commit. The next session runs `dotmd use` (or `dotmd use ' + repoPath + '`) to consume it.\n'));
   }
+  // Teach the field-length contract at the moment the fields get written —
+  // learning it from a cap warning later sends sessions into hand-trim /
+  // re-check loops.
+  if (typeName === 'plan') {
+    process.stdout.write(dim('current_state = 2-4 sentence summary (cap 1500 chars); next_step = 1-2 sentence pointer (cap 800). Detail goes in the body, not frontmatter.\n'));
+  }
   try {
     const { isGitIgnored } = await import('./git.mjs');
     if (isGitIgnored(filePath, config.repoRoot)) {

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', 'hold', 'unhold', 'shelve', 'unshelve']);
+const SUBCOMMANDS = new Set(['list', 'next', 'use', 'resume', 'show', 'peek', 'archive', 'new', 'hold', 'unhold', 'shelve', 'unshelve']);
 
 export async function runPrompts(argv, config, opts = {}) {
   const sub = argv[0];
@@ -26,6 +26,8 @@ export async function runPrompts(argv, config, opts = {}) {
     case 'next':     return runPromptsNext(rest, config, opts);
     case 'use':      return runPromptsUse(rest, config, opts);
     case 'resume':   return runPromptsUse(rest, config, opts);
+    case 'show':     return runPromptsShow(rest, config);
+    case 'peek':     return runPromptsShow(rest, config);
     case 'archive':  return runPromptsArchive(rest, config, opts);
     case 'new':      return runPromptsNew(rest, config, opts);
     case 'hold':     return runPromptsHold(rest, config, opts);
@@ -283,6 +285,28 @@ export function consumePrompt(filePath, config, opts) {
   process.stderr.write(`${green('✓ Consumed')}: ${consumedPath}\n`);
 }
 
+// Read-only peek: print the body WITHOUT consuming. The sanctioned triage path
+// — surveying pending prompts must not archive them (that's `use`'s job), and
+// it must not require raw cat/Read (which the guard warns about).
+function runPromptsShow(argv, config) {
+  const input = argv.find(a => !a.startsWith('-'));
+  if (!input) die('Usage: dotmd prompts show <file-or-slug>');
+  const filePath = resolvePromptInput(input, config);
+
+  const raw = readFileSync(filePath, 'utf8');
+  const { frontmatter, body } = extractFrontmatter(raw);
+  const parsed = parseSimpleFrontmatter(frontmatter);
+  const repoPath = toRepoPath(filePath, config.repoRoot);
+  if (asString(parsed.type) !== 'prompt') {
+    die(`Not a prompt (type: ${asString(parsed.type) ?? 'unknown'}): ${repoPath}`);
+  }
+
+  const status = asString(parsed.status) ?? 'unknown';
+  process.stderr.write(dim(`${repoPath} [${status}] — read-only peek; \`dotmd use ${repoPath}\` to consume\n`));
+  process.stdout.write(body);
+  if (!body.endsWith('\n')) process.stdout.write('\n');
+}
+
 function runPromptsArchive(argv, config, opts = {}) {
   const input = argv.find(a => !a.startsWith('-'));
   if (!input) die('Usage: dotmd prompts archive <file-or-slug>');

package/src/validate.mjs

@@ -475,7 +475,7 @@ export function validatePlanShape(doc, body, frontmatter, config) {
     doc.warnings.push({
       path: doc.path,
       level: 'warning',
-      message: `\`next_step\` is ${nextStep.length} chars (cap: 800). Long prose belongs in the body — keep next_step as a 1-2 sentence pointer.`,
+      message: `\`next_step\` is ${nextStep.length} chars (cap: 800). One mechanical fix: \`dotmd doctor --frontmatter-fix\` (moves the overflow into the body) — do NOT hand-trim or re-run check in a loop. Going forward, write next_step as a 1-2 sentence pointer; detail goes in the body.`,
     });
   }
 
@@ -488,7 +488,7 @@ export function validatePlanShape(doc, body, frontmatter, config) {
     doc.warnings.push({
       path: doc.path,
       level: 'warning',
-      message: `\`current_state\` is ${currentState.length} chars (cap: 1500). Long prose belongs in the body.`,
+      message: `\`current_state\` is ${currentState.length} chars (cap: 1500). One mechanical fix: \`dotmd doctor --frontmatter-fix\` (moves the overflow into the body) — do NOT hand-trim or re-run check in a loop. Going forward, write current_state as a 2-4 sentence summary; detail goes in the body.`,
     });
   }