dotmd-cli 0.59.0 → 0.61.0

package/bin/dotmd.mjs

@@ -13,7 +13,7 @@ const __dirname = path.dirname(__filename);
 const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
 
 const QUERY_FLAGS = new Set([
-  '--type', '--status', '--keyword', '--owner', '--surface', '--module',
+  '--type', '--status', '--keyword', '--body', '--owner', '--surface', '--module',
   '--domain', '--audience', '--execution-mode', '--updated-since', '--limit',
   '--sort', '--group', '--all', '--include-archived', '--exclude-archived',
   '--stale', '--has-next-step', '--has-blockers', '--checklist-open', '--json',
@@ -28,6 +28,7 @@ const QUERY_VALUE_FLAGS = new Set([
 const FLAG_SPECS = {
   plans: { flags: QUERY_FLAGS, values: QUERY_VALUE_FLAGS, subcommands: new Set(['status']) },
   query: { flags: QUERY_FLAGS, values: QUERY_VALUE_FLAGS },
+  grep: { flags: QUERY_FLAGS, values: QUERY_VALUE_FLAGS },
   stale: { flags: QUERY_FLAGS, values: QUERY_VALUE_FLAGS },
   actionable: { flags: QUERY_FLAGS, values: QUERY_VALUE_FLAGS },
   list: { flags: new Set(['--json', '--verbose']), values: new Set() },
@@ -35,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() },
@@ -44,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']),
   },
 };
 
@@ -131,7 +134,8 @@ Common commands:
   agent-context         Compact bounded JSON context for agents
   set <status> [file]   Transition status (start work, finish, archive — all via target status)
   new <type> <name>     Create plan/doc/prompt (pipe stdin or @path for body)
-  use [<file-or-prompt-slug>] Open a doc by type: prompt → consume, plan → start, doc → read
+  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)
 
@@ -153,10 +157,16 @@ Rules:
   commit-prompt  deny  git add/commit of a (often gitignored) saved prompt
   cat-prompt     warn  cat/less/head of a docs/prompts/*.md (use \`dotmd use\`)
   read-prompt    warn  Read tool on a saved prompt (use \`dotmd use\`)
-  edit-status    warn  hand-edit of a \`status:\` field (use \`dotmd set\`)
+  edit-status    deny  CHANGING a \`status:\` line — via Edit/Write or in-place
+                       stream editors (sed -i, perl -pi, awk -i inplace).
+                       Use \`dotmd set <status> <file>\`. Edits that merely
+                       carry an unchanged status: line as context don't fire.
 
-Every catch is appended to the cross-repo misuse log. Disable with DOTMD_GUARD=0.
-Read the log with \`dotmd misuse\`.`,
+\`guard: { deny: false }\` in dotmd.config.mjs drops edit-status back to
+warn-only. Every catch is appended to the cross-repo misuse log. Disable the
+guard entirely with DOTMD_GUARD=0. Read the log with \`dotmd misuse\`; when one
+rule trips ≥3× in 7 days in a repo, \`dotmd hud\` opens the next session there
+with a one-line recap naming the habit to break.`,
 
   update: `dotmd update — update the dotmd CLI and the Claude Code plugin together
 
@@ -192,10 +202,12 @@ View & Query:
   context [--summarize] [--json]    Full briefing (LLM-oriented; use --json --compact for bounded JSON)
   agent-context [--json]            Compact bounded JSON context for agents
   focus [status] [--json]           Detailed view for one status group
-  query [filters] [--json]          Filtered search (--status, --keyword, --stale, etc.)
+  query [filters] [--json]          Filtered search (--status, --keyword, --body, --stale, etc.)
+  grep <term>                       Keyword search incl. document bodies (query --keyword --body --all)
   plans                             Live plans (excludes archived; --include-archived for all)
-  use [<file-or-prompt-slug>]       Open a doc by type: prompt → consume, plan → start, doc → read
-  prompts [list|archive|new|hold] Prompt admin (list / archive / save / hold). Use \`dotmd use\` to consume.
+  use [<file-or-slug>]              Open a doc by type: prompt → consume, plan → start, doc → read
+  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)
 
@@ -401,6 +413,7 @@ Filters:
   --type <t1,t2>         Filter by type (plan, doc, research)
   --status <s1,s2>       Filter by status (comma-separated)
   --keyword <term>       Search title, summary, state, path
+  --body                 Extend --keyword into document bodies (lazy scan, shows matching-line excerpts)
   --module <name>        Filter by module
   --surface <name>       Filter by surface
   --domain <name>        Filter by domain
@@ -420,6 +433,22 @@ Filters:
   --summarize-limit <n>  Max docs to summarize (default: 5)
   --model <name>         Model for AI summaries`,
 
+  grep: `dotmd grep <term> — keyword search across frontmatter AND document bodies
+
+Alias for \`dotmd query --keyword <term> --body --all\`. Answers "which doc
+discussed X?" with full doc cards (type, status, updated, path) plus 1-2
+matching-line excerpts per body hit — instead of raw-grep's bare paths.
+
+Bodies are read lazily: frontmatter filters run first, only surviving
+candidates are opened. Archived docs are included but clearly labeled.
+
+Composes with the usual query flags:
+  dotmd grep skipStale                     everything mentioning skipStale
+  dotmd grep retries --type plan           only plans
+  dotmd grep retries --status active       only active docs
+  dotmd grep retries --limit 5             cap results (default: unlimited)
+  dotmd grep retries --json                machine-readable (bodyMatches per doc)`,
+
   ship: `dotmd ship [patch|minor|major] — regen + commit + bump in one step
 
 Bundles the release steps into a single command:
@@ -444,21 +473,28 @@ Network failures mid-bump (e.g. \`git push\` fails) leave the local
 commit + tag intact. Inspect with \`git log -1\` and rerun
 \`git push origin main --tags\` to recover.`,
 
-  set: `dotmd set <status> <file> — change a document's status
+  set: `dotmd set <status> <file-or-slug> — change a document's status
 
 Writes the new status into the file's frontmatter. Nothing else — no plan
 checkout, no session locks.
   - target is an archive status → archive the file (move + ref update)
   - everything else             → plain frontmatter status bump
 
+<file-or-slug> resolves like \`dotmd use\`/\`archive\`: exact path first, then
+a unique bare slug / basename across the doc roots (\`set paused auth-revamp\`).
+Ambiguous slugs error with the candidate list instead of guessing.
+
 Options:
+  --note "<text>"        Append the reason to \`## Version History\` in the
+                         same call (creates the section if missing). Saves
+                         the status-change + worklog-edit round-trip.
   --no-index             Skip index regen (see \`dotmd archive --help\`).
   --show-files           Append \`files: …\` footer.
   --dry-run, -n          Preview without writing.
 
 Examples:
   dotmd set in-session docs/plans/x  # mark a plan in-session
-  dotmd set partial docs/plans/x     # mark partial
+  dotmd set partial docs/plans/x --note "tail tracked in y.md"
   dotmd set archived docs/plans/x    # archive a specific plan
 
 To open a plan (mark in-session AND print its body), use \`dotmd use <file>\`.`,
@@ -518,6 +554,8 @@ basename match under the doc roots. An ambiguous basename (the same name in
 two places) errors with the candidate list instead of guessing.
 
 Options:
+  --note "<text>"        Append \`Archived — <text>\` to \`## Version History\`
+                         in the same call (creates the section if missing).
   --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
@@ -569,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
 
@@ -959,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
@@ -989,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.
@@ -1305,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
@@ -1540,6 +1629,23 @@ async function main() {
 
   if (command === 'focus') { runFocus(index, restArgs, config); return; }
   if (command === 'query') { runQuery(index, restArgs, config); return; }
+  // `dotmd grep <term>` — ergonomic alias for `query --keyword <term> --body`.
+  // Unlimited by default (grep semantics) unless the caller bounds it themselves.
+  if (command === 'grep') {
+    let term = null;
+    const passthrough = [];
+    for (let i = 0; i < restArgs.length; i++) {
+      const arg = restArgs[i];
+      if (QUERY_VALUE_FLAGS.has(arg)) { passthrough.push(arg, restArgs[i + 1]); i += 1; continue; }
+      if (arg.startsWith('-') || term !== null) { passthrough.push(arg); continue; }
+      term = arg;
+    }
+    if (!term) die('Usage: dotmd grep <term> [query flags]\n\nSearches frontmatter fields AND document bodies; alias for `dotmd query --keyword <term> --body --all`.');
+    const defaults = ['--keyword', term, '--body'];
+    if (!passthrough.includes('--limit') && !passthrough.includes('--all')) defaults.push('--all');
+    runQuery(index, [...defaults, ...passthrough], config);
+    return;
+  }
   if (command === 'modules' || command === 'module') {
     // D3: default `--type plan` when the user didn't pass --type explicitly.
     // applyIndexFilters already narrowed by typeArg if it was set; if not, the

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.59.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

@@ -4,10 +4,10 @@
 // templates points at a real command.
 export const KNOWN_COMMANDS = [
   'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'briefing', 'context', 'agent-context', 'hud',
-  'focus', 'query', 'plans', 'prompts', 'stale', 'actionable', 'index', 'status', 'set', 'use', 'next', 'archive', 'bulk', 'bulk-tag', 'touch', 'doctor', 'runlist',
+  'focus', 'query', 'grep', 'plans', 'prompts', 'stale', 'actionable', 'index', 'status', 'set', 'use', 'next', 'archive', 'bulk', 'bulk-tag', 'touch', 'doctor', 'runlist',
   'unblocks', 'health', 'glossary', 'modules', 'module',
   '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/completions.mjs

@@ -1,7 +1,7 @@
 import { die } from './util.mjs';
 
 const COMMANDS = [
-  'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'unblocks', 'health', 'glossary', 'briefing', 'context', 'focus', 'query',
+  'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'unblocks', 'health', 'glossary', 'briefing', 'context', 'focus', 'query', 'grep',
   'plans', 'stale', 'actionable', 'index', 'status', 'set', 'archive', 'bulk', 'touch', 'doctor', 'lint', 'rename', 'migrate',
   'fix-refs', 'notion', 'export', 'summary', 'watch', 'diff', 'init', 'new', 'completions', 'journal',
 ];
@@ -9,10 +9,12 @@ const COMMANDS = [
 const GLOBAL_FLAGS = ['--config', '--dry-run', '--verbose', '--root', '--type', '--help', '--version'];
 
 const COMMAND_FLAGS = {
-  query: ['--type', '--status', '--keyword', '--module', '--surface', '--domain', '--owner',
+  query: ['--type', '--status', '--keyword', '--body', '--module', '--surface', '--domain', '--owner',
           '--updated-since', '--stale', '--has-next-step', '--has-blockers',
           '--checklist-open', '--sort', '--limit', '--all', '--git', '--json',
           '--summarize', '--summarize-limit', '--model'],
+  grep: ['--type', '--status', '--limit', '--all', '--json', '--sort',
+         '--module', '--surface', '--domain', '--owner'],
   index: ['--write'],
   list: ['--verbose', '--json'],
   coverage: ['--json'],

package/src/config.mjs

@@ -118,6 +118,10 @@ const DEFAULTS = {
   // and users who want usage observability flip this on (or set DOTMD_JOURNAL=1).
   journal: false,
 
+  // PreToolUse guard behavior. `deny: false` drops the status-edit rules from
+  // deny (block the tool call) back to warn-only teaching context.
+  guard: { deny: true },
+
   presets: {
     stale: ['--status', 'active,ready,planned,blocked,scoping', '--stale', '--sort', 'updated', '--all'],
     actionable: ['--status', 'active,ready', '--has-next-step', '--sort', 'updated', '--all'],
@@ -533,6 +537,7 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     referenceFields: config.referenceFields,
     presets: config.presets,
     journal: config.journal === true,
+    guard: { deny: config.guard?.deny !== false },
     hooks,
     configWarnings,
   };

package/src/deps.mjs

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { buildGraph } from './graph.mjs';
-import { buildIndex } from './index.mjs';
-import { resolveDocPath, toSlug, toRepoPath, die, warn } from './util.mjs';
+import { buildIndex, resolveDocArg } from './index.mjs';
+import { toRepoPath, die } from './util.mjs';
 import { bold, dim, green } from './color.mjs';
 
 export function runDeps(argv, config) {
@@ -38,8 +38,7 @@ export function runDeps(argv, config) {
 
   if (input) {
     // Tree view for a specific doc
-    const filePath = resolveDocPath(input, config);
-    if (!filePath) die(`File not found: ${input}`);
+    const filePath = resolveDocArg(input, config);
     const repoPath = toRepoPath(filePath, config.repoRoot);
     const doc = docByPath.get(repoPath);
     if (!doc) die(`Doc not in index: ${repoPath}`);
@@ -255,8 +254,7 @@ export function runUnblocks(argv, config) {
   const json = argv.includes('--json');
   if (!input) die('Usage: dotmd unblocks <file>');
 
-  const filePath = resolveDocPath(input, config);
-  if (!filePath) die(`File not found: ${input}`);
+  const filePath = resolveDocArg(input, config);
   const repoPath = toRepoPath(filePath, config.repoRoot);
 
   const index = buildIndex(config);