dotmd-cli 0.59.0 → 0.61.0

package/src/diff.mjs

@@ -1,10 +1,10 @@
 import { readFileSync } from 'node:fs';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
-import { asString, toRepoPath, resolveDocPath, die, warn } from './util.mjs';
+import { asString, toRepoPath, die, warn } from './util.mjs';
 import { gitDiffSince } from './git.mjs';
-import { buildIndex } from './index.mjs';
+import { buildIndex, resolveDocArg } from './index.mjs';
 import { summarizeDiffText, DEFAULT_MODEL } from './ai.mjs';
-import { bold, dim, green } from './color.mjs';
+import { bold, dim } from './color.mjs';
 
 export function runDiff(argv, config) {
   // Parse flags
@@ -24,10 +24,7 @@ export function runDiff(argv, config) {
 
   if (file) {
     // Single file mode
-    const filePath = resolveDocPath(file, config);
-    if (!filePath) {
-      die(`File not found: ${file}\nSearched: ${toRepoPath(config.repoRoot, config.repoRoot) || '.'}, ${toRepoPath(config.docsRoot, config.repoRoot)}`);
-    }
+    const filePath = resolveDocArg(file, config);
 
     const raw = readFileSync(filePath, 'utf8');
     const { frontmatter } = extractFrontmatter(raw);

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

@@ -16,12 +16,14 @@ const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'),
 //
 // Two decision levels:
 //   'deny' — block the call and feed the reason back to the model. Reserved for
-//            moves that are guaranteed-wrong (committing a gitignored prompt — it
-//            would fail anyway).
+//            moves that are guaranteed-wrong: committing a gitignored prompt (it
+//            would fail anyway) and hand-editing a `status:` field (`dotmd set`
+//            is a complete substitute; config `guard: { deny: false }` drops the
+//            status rules back to warn).
 //   'warn' — let the call proceed but inject teaching context so the agent learns
 //            the dotmd-native command. Used for soft mistakes (cat/Read of a
-//            prompt, hand-editing a status field) where a human might legitimately
-//            do it; we nudge rather than block.
+//            prompt) where a human might legitimately do it; we nudge rather
+//            than block.
 
 const SHELL_READERS = new Set(['cat', 'less', 'more', 'head', 'tail', 'bat', 'view', 'open']);
 
@@ -56,44 +58,130 @@ function shellTokens(command) {
   return command.split(/\s+/).map(t => t.replace(/^['"]|['"]$/g, '')).filter(Boolean);
 }
 
-function evalBash(command, config, isIgnored) {
-  const tokens = shellTokens(command);
-  const promptTokens = tokens.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.
-  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.`,
-    };
+// 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');
+}
 
-  // Rule B — reading a prompt through the shell instead of consuming it.
-  if (tokens.length) {
-    const cmd0 = path.basename(tokens[0]);
+// 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.
+function editStatusDecision(config) {
+  return config?.guard?.deny === false ? 'warn' : 'deny';
+}
+
+function editStatusResult(target, config, detail) {
+  return {
+    decision: editStatusDecision(config),
+    rule: 'edit-status',
+    detail,
+    reason:
+      `Looks like a hand-edit of the \`status:\` field in ${target}. Use \`dotmd set <status> ${target}\` instead — ` +
+      `it validates the status against this doc's type, runs lifecycle hooks, fixes refs, and keeps the index in sync. Direct edits skip all of that.`,
+  };
+}
+
+// In-place stream editors (`sed -i`, `perl -pi`, `awk -i inplace`) are the
+// shell-side bypass of the Edit-tool status guard. Only the command text
+// before any heredoc marker is scanned — heredoc bodies are document content
+// (often prose *describing* these rules), not commands.
+const STREAM_EDITOR_INPLACE = [
+  /\bsed\b[^|;&<>]*\s-i/,
+  /\bperl\b[^|;&<>]*\s-[a-zA-Z]*i/,
+  /\bg?awk\b[^|;&<>]*\binplace\b/,
+];
+
+function evalBash(command, config, isIgnored) {
+  const segments = shellSegments(command);
+
+  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 (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. 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);
+    }
+  }
+
   return null;
 }
 
@@ -104,27 +192,44 @@ 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.`,
   };
 }
 
-const STATUS_LINE = /^\s*status\s*:/m;
+// Every `status:` line in a snippet, normalized for comparison.
+function statusLines(s) {
+  if (typeof s !== 'string') return [];
+  return (s.match(/^[ \t]*status[ \t]*:[^\n]*/gm) ?? []).map(l => l.trim());
+}
 
-function evalEdit(input, config) {
+// Only fire when the edit actually CHANGES a `status:` line. An edit whose
+// old/new strings both carry the same `status:` line is using it as anchor
+// context (e.g. adding a `summary:` field above it) — warning on those taught
+// sessions to ignore the rule (the health-repo repeat offenses were exactly
+// this false positive).
+function evalEdit(input, config, deps = {}) {
   const filePath = input?.file_path;
   if (!isManagedDoc(filePath, config)) return null;
-  // Only fire when the edit actually touches a `status:` frontmatter line.
-  const candidates = [input?.new_string, input?.content, input?.new_str]
-    .filter(s => typeof s === 'string');
-  if (!candidates.some(s => STATUS_LINE.test(s))) return null;
-  return {
-    decision: 'warn',
-    rule: 'edit-status',
-    detail: filePath,
-    reason:
-      `Looks like a hand-edit of the \`status:\` field in ${filePath}. Use \`dotmd set <status> ${filePath}\` instead — ` +
-      `it validates the status against this doc's type, runs lifecycle hooks, fixes refs, and keeps the index in sync. Direct edits skip all of that.`,
-  };
+
+  const pairs = [];
+  const newStr = input?.new_string ?? input?.new_str;
+  if (typeof newStr === 'string') pairs.push([input?.old_string ?? input?.old_str ?? '', newStr]);
+  for (const e of Array.isArray(input?.edits) ? input.edits : []) {
+    if (typeof e?.new_string === 'string') pairs.push([e.old_string ?? '', e.new_string]);
+  }
+  if (typeof input?.content === 'string') {
+    // Write replaces the whole file — diff against what's on disk. An
+    // unreadable/missing target is doc creation, not a status edit.
+    const readFile = deps.readFile ?? ((p) => readFileSync(p, 'utf8'));
+    let existing;
+    try { existing = readFile(filePath); } catch { existing = null; }
+    if (typeof existing === 'string') pairs.push([existing, input.content]);
+  }
+
+  const changed = pairs.some(([oldS, newS]) => statusLines(oldS).join('\n') !== statusLines(newS).join('\n'));
+  if (!changed) return null;
+  return editStatusResult(filePath, config, filePath);
 }
 
 // Pure evaluation — `deps.isIgnored(path) -> bool` is injected so tests don't
@@ -137,7 +242,7 @@ export function evaluateGuard(payload, config, deps = {}) {
 
   if (tool === 'Bash') return evalBash(input.command || '', config, isIgnored);
   if (tool === 'Read') return evalRead(input.file_path || '');
-  if (tool === 'Edit' || tool === 'Write' || tool === 'MultiEdit') return evalEdit(input, config);
+  if (tool === 'Edit' || tool === 'Write' || tool === 'MultiEdit') return evalEdit(input, config, deps);
   return null;
 }
 
@@ -149,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

@@ -6,8 +6,9 @@ import { asString, toRepoPath, currentSessionId } from './util.mjs';
 import { dim, yellow } from './color.mjs';
 import { buildIndex } from './index.mjs';
 import { refreshStaleSlashCommands } from './claude-commands.mjs';
-import { readJournalEntries, journalFilePath } from './journal.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
@@ -191,6 +196,39 @@ export function buildJournalSections(config, now = Date.now()) {
   return { previousSelf, fleet, recentRejections };
 }
 
+// Misuse recap: when sessions in THIS repo keep tripping the same guard rule,
+// say so once at SessionStart — the shipped self-correcting-hints pattern
+// pointed at repeat offenses. One line, only for the top rule, only past the
+// threshold; silent otherwise.
+const MISUSE_RECAP_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+const MISUSE_RECAP_THRESHOLD = 3;
+
+const MISUSE_CORRECTIONS = {
+  'edit-status': 'never hand-edit `status:`; use `dotmd set <status> <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',
+};
+
+export function buildMisuseRecap(config, now = Date.now()) {
+  let entries;
+  try { entries = readMisuseEntries(); } catch { return null; }
+  if (!entries.length) return null;
+  const cutoff = now - MISUSE_RECAP_WINDOW_MS;
+  const counts = new Map();
+  for (const e of entries) {
+    if (!e?.rule || (e.repo || '') !== config.repoRoot) continue;
+    const t = new Date(e.ts).getTime();
+    if (!Number.isFinite(t) || t < cutoff) continue;
+    counts.set(e.rule, (counts.get(e.rule) ?? 0) + 1);
+  }
+  const top = [...counts.entries()].sort((a, b) => b[1] - a[1])[0];
+  if (!top || top[1] < MISUSE_RECAP_THRESHOLD) return null;
+  const [rule, count] = top;
+  const fix = MISUSE_CORRECTIONS[rule] ?? 'see `dotmd misuse`';
+  return `sessions here tripped ${rule} ${count}× this week — ${fix}`;
+}
+
 export function buildHud(config) {
   const prompts = findActionablePrompts(config);
 
@@ -202,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
@@ -209,11 +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 };
+  return { owned, prompts, errors, previousSelf, fleet, recentRejections, misuseRecap };
 }
 
 // Subagent primer: a spawned subagent (Explore, Plan, general-purpose) starts
@@ -277,16 +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.
-  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/index.mjs

@@ -2,7 +2,7 @@ import { readdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { extractFirstHeading, extractSummary, extractStatusSnapshot, extractNextStep, extractChecklistCounts, extractBodyLinks } from './extractors.mjs';
-import { asString, normalizeStringList, normalizeBlockers, mergeUniqueStrings, toRepoPath, warn } from './util.mjs';
+import { asString, normalizeStringList, normalizeBlockers, mergeUniqueStrings, toRepoPath, warn, die, resolveDocPath, suggestCandidates } from './util.mjs';
 import { validateDoc, validatePlanShape, validateDocShape, checkBidirectionalReferences, checkGitStaleness, checkRunlistBackPointers, computeDaysSinceUpdate, computeIsStale, computeChecklistCompletionRate, enrichRefErrorSuggestions } from './validate.mjs';
 import { checkIndex } from './index-file.mjs';
 import { checkClaudeCommands } from './claude-commands.mjs';
@@ -152,6 +152,54 @@ export function collectDocFiles(config) {
   return files.sort((a, b) => a.localeCompare(b));
 }
 
+// Shared resolver for CLI file arguments — the single path every file-taking
+// verb (`use`, `set`, `archive`, `touch`, `rename`, …) funnels through so
+// bare slugs behave identically everywhere. Tries, in order: exact path
+// (the resolveDocPath fast path), `<input>.md`, then a unique basename match
+// across all doc roots. An ambiguous basename dies listing the candidates
+// rather than guessing — a wrong auto-resolved mutation is worse than a
+// retry. A full miss dies with did-you-mean suggestions drawn from the doc
+// corpus; pass { dieOnMiss: false } to get null instead and keep a custom
+// fallback at the call site.
+export function resolveDocArg(input, config, { dieOnMiss = true } = {}) {
+  if (!input) return null;
+  const direct = resolveDocPath(input, config);
+  if (direct) return direct;
+  if (!input.endsWith('.md')) {
+    const withExt = resolveDocPath(input + '.md', config);
+    if (withExt) return withExt;
+  }
+
+  const slug = input.replace(/\.md$/, '');
+  const files = collectDocFiles(config);
+  const byBasename = files.filter(f => path.basename(f, '.md') === slug);
+  if (byBasename.length === 1) return byBasename[0];
+  if (byBasename.length > 1) {
+    die(`Multiple docs match "${input}" by basename:\n${byBasename.map(f => '  ' + toRepoPath(f, config.repoRoot)).join('\n')}`);
+  }
+
+  if (!dieOnMiss) return null;
+  die(docArgMissMessage(input, config, files));
+}
+
+// `File not found` + the searched roots + up-to-3 did-you-mean candidates
+// matched on basename and printed as repo-relative paths. Exported so verbs
+// with their own resolution (e.g. interactive pickers) can reuse the message.
+export function docArgMissMessage(input, config, files = collectDocFiles(config)) {
+  const roots = config.docsRoots || [config.docsRoot];
+  const searched = [toRepoPath(config.repoRoot, config.repoRoot) || '.', ...roots.map(r => toRepoPath(r, config.repoRoot))].join(', ');
+  const slug = String(input).split('/').pop().replace(/\.md$/, '');
+  const pathsByBase = new Map();
+  for (const f of files) {
+    const base = path.basename(f, '.md');
+    if (!pathsByBase.has(base)) pathsByBase.set(base, toRepoPath(f, config.repoRoot));
+  }
+  const hits = suggestCandidates(slug, [...pathsByBase.keys()]);
+  let msg = `File not found: ${input}\nSearched: ${searched}`;
+  if (hits.length) msg += `\nDid you mean: ${hits.map(b => pathsByBase.get(b)).join(', ')}?`;
+  return msg;
+}
+
 function walkMarkdownFiles(directory, files, excludedDirs, skipPaths, seen = new Set()) {
   let entries;
   try {