dotmd-cli 0.17.1 → 0.19.0

package/README.md

@@ -146,7 +146,10 @@ dotmd plans                  List all plans
 dotmd stale                  List stale docs
 dotmd actionable             List docs with next steps
 dotmd index [--write]        Generate/update docs.md index block
-dotmd pickup <file>          Pick up a plan (in-session + print)
+dotmd hud                    Three-line actionable triage (silent when clean — ideal SessionStart hook)
+dotmd pickup <file>          Pick up a plan (in-session + print body or queued handoff)
+dotmd release [<file>]       Release in-session lease (alias: unpickup)
+dotmd handoff <file> [...]   Queue a resume-prompt sidecar + release
 dotmd finish <file>          Finish a plan (done or active)
 dotmd status <file> <status> Transition document status
 dotmd archive <file>         Archive (status + move + update refs)
@@ -397,12 +400,36 @@ dotmd bulk archive docs/old-*.md -n               # preview
 ### Pickup & Finish
 
 ```bash
-dotmd pickup docs/plans/my-plan.md       # set in-session + print content
+dotmd pickup docs/plans/my-plan.md       # set in-session + print body (or queued handoff)
 dotmd finish docs/plans/my-plan.md       # set done + bump date
 dotmd finish docs/plans/my-plan.md active  # back to active for more work
 ```
 
-### Session leases & unpickup
+### Handoff (resume-prompts attached to plans)
+
+When you're stopping mid-work and the next session will need to pick up where
+you left off, write a handoff sidecar instead of printing a resume prompt to
+chat for copy-paste:
+
+```bash
+dotmd handoff docs/plans/foo.md "continue from validate(); next: write tests"
+dotmd handoff docs/plans/foo.md - <<'EOF'   # heredoc-friendly for Claude
+…multi-line resume prompt…
+EOF
+dotmd handoff docs/plans/foo.md @/tmp/handoff.md   # from file
+```
+
+The handoff is written to `<repoRoot>/.dotmd/handoffs/<plan-path>` as a
+timestamped section (append mode by default; `--replace` to overwrite). The
+lease is released and the plan flips back to its prior status. The next
+`dotmd pickup` of that plan prints the handoff *instead of* the plan body
+and atomically unlinks the sidecar — single-claim, can't be consumed twice.
+
+The included `/handoff` slash command (scaffolded under
+`.claude/commands/handoff.md` by `dotmd init` / `dotmd doctor`) instructs
+Claude to synthesize and queue handoffs for every plan the session holds.
+
+### Session leases & release
 
 `dotmd pickup` records a lease at `<repoRoot>/.dotmd/in-session.json` that
 identifies which Claude session owns the plan. The lease enables three
@@ -416,15 +443,15 @@ distinct outcomes when a plan is already `in-session`:
 - **Stale lease.** If the holder's pid is dead (or the lease is >24h old),
   pickup refuses but suggests `--takeover`.
 
-Releasing leases:
+Releasing leases (both names work; `release` is the recommended verb):
 
 ```bash
-dotmd unpickup                    # release every lease owned by current session
-dotmd unpickup docs/plans/foo.md  # release that one (refuses cross-session)
-dotmd unpickup --to planned       # override target status (default: lease.oldStatus)
-dotmd unpickup --stale            # release leases with dead pid or >24h old
-dotmd unpickup --all              # release every lease (administrative)
-dotmd unpickup --json             # { released: [...], skipped: [...] }
+dotmd release                     # release every lease owned by current session
+dotmd release docs/plans/foo.md   # release that one (refuses cross-session)
+dotmd release --to planned        # override target status (default: lease.oldStatus)
+dotmd release --stale             # release leases with dead pid or >24h old
+dotmd release --all               # release every lease (administrative)
+dotmd release --json              # { released: [...], skipped: [...] }
 ```
 
 `finish`, `archive`, and `rename` auto-release / migrate the lease, so the
@@ -440,16 +467,23 @@ common closeout paths are covered without ceremony.
 The session id survives `/clear` and auto-compaction, so a re-attach after
 either is silent.
 
-**Auto-release on Claude Code session end** — add this to
-`~/.claude/settings.json` (or your project's `.claude/settings.json`):
+**Recommended Claude Code hooks** — add both to `~/.claude/settings.json`
+(or your project's `.claude/settings.json`):
 
 ```json
 {
   "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          { "type": "command", "command": "dotmd hud", "timeout": 5 }
+        ]
+      }
+    ],
     "SessionEnd": [
       {
         "hooks": [
-          { "type": "command", "command": "dotmd unpickup", "timeout": 10 }
+          { "type": "command", "command": "dotmd release", "timeout": 10 }
         ]
       }
     ]
@@ -457,16 +491,22 @@ either is silent.
 }
 ```
 
-When the Claude Code session ends, the hook runs `dotmd unpickup` with
-`$CLAUDE_CODE_SESSION_ID` in the environment, releasing every lease for
-that session and flipping plans back to their prior status.
+- **SessionStart** runs `dotmd hud`, which prints up to three actionable
+  lines (held leases, queued handoffs, stale leases) and stays silent when
+  nothing is queued. Use this instead of `dotmd briefing` for the hook role
+  — `briefing` dumps per-plan next_step prose that can run to many kilobytes
+  on large repos. `hud` is the zero-pollution surface.
+- **SessionEnd** runs `dotmd release` (the new name for `dotmd unpickup`;
+  both still work), which releases every lease owned by the ending session
+  and flips plans back to their prior status.
 
-> The double-`hooks` nesting is correct: `hooks.SessionEnd[*].hooks[*]`
-> is the schema Claude Code requires. `Bash(dotmd:*)` should be in your
-> `permissions.allow` list as well, otherwise the hook will be blocked.
+> The double-`hooks` nesting is correct: `hooks.<Event>[*].hooks[*]` is the
+> schema Claude Code requires. `Bash(dotmd:*)` should be in your
+> `permissions.allow` list as well, otherwise the hooks will be blocked.
 
-`dotmd briefing` surfaces a `Stuck in-session: N` line when stale leases
-exist, with a `dotmd unpickup --stale` suggestion.
+`dotmd hud` (and `dotmd briefing` for the verbose case) surface a
+`⚠ N stuck leases` line when stale leases exist, with a
+`dotmd release --stale` suggestion.
 
 ### Touch
 

package/bin/dotmd.mjs

@@ -14,8 +14,9 @@ const HELP = {
   _main: `dotmd v${pkg.version} — frontmatter markdown document manager
 
 View & Query:
+  hud [--json]                      Three-line actionable triage (held / handoffs / stuck) — silent when clean
   list [--verbose] [--json]         List docs grouped by status (default command)
-  briefing [--json]                 Compact summary for session start
+  briefing [--json]                 Full briefing with plan status counts + next steps
   context [--summarize] [--json]    Full briefing (LLM-oriented)
   focus [status] [--json]           Detailed view for one status group
   query [filters] [--json]          Filtered search (--status, --keyword, --stale, etc.)
@@ -41,8 +42,9 @@ Validate & Fix:
   fix-refs [--dry-run]              Auto-fix broken reference paths + body links
 
 Lifecycle:
-  pickup <file> [--takeover]        Pick up a plan (set in-session + print)
-  unpickup [<file>] [--to <s>]      Release in-session lease (default: all owned by current session)
+  pickup <file> [--takeover]        Pick up a plan (set in-session + print body or queued handoff)
+  release [<file>] [--to <s>]       Release in-session lease (alias: unpickup)
+  handoff <file> [text|-|@path]     Queue a resume-prompt sidecar + release (append-mode)
   finish <file> [done|active]       Finish a plan (set done or active)
   status <file> <status>            Transition document status
   archive <file>                    Archive (status + move + update refs)
@@ -116,9 +118,14 @@ Filters:
 
   pickup: `dotmd pickup <file> — pick up a plan and start working
 
-Sets the plan to in-session and prints its content. Writes a session
-lease to <repoRoot>/.dotmd/in-session.json so the same Claude session
-can re-attach silently after compaction or /clear.
+Sets the plan to in-session and prints its content (prefixed with a
+"[dotmd] holding <path>" line so the fresh session knows what it holds).
+Writes a session lease to <repoRoot>/.dotmd/in-session.json so the same
+Claude session can re-attach silently after compaction or /clear.
+
+If a handoff sidecar is queued for the plan (\`.dotmd/handoffs/<path>\`),
+pickup prints the handoff *instead of* the plan body and unlinks the
+sidecar atomically — single-claim, can't be consumed twice.
 
 If a plan is already in-session:
 - Same session → silent re-attach (prints body, no error).
@@ -130,7 +137,8 @@ Options:
   --json                 Output as JSON
   --dry-run, -n          Preview without writing
 
-If no file is given, prompts with a list of active plans.`,
+If no file is given, prompts with a list of active/planned plans plus
+any plan with a queued handoff (sorted to the top).`,
 
   unpickup: `dotmd unpickup [<file>] — release a plan from in-session
 
@@ -154,6 +162,44 @@ Options:
 Manual-edit fallback: if the plan's status is in-session but no lease
 exists, --to <status> flips it anyway with a warning.`,
 
+  release: `dotmd release [<file>] [--to <s>] — alias of dotmd unpickup
+
+Release the in-session lease(s) and flip frontmatter back to the prior
+status. With no file, releases every lease owned by the current session.
+Identical behavior to \`dotmd unpickup\`; both names route to the same
+implementation. See \`dotmd unpickup --help\` for full option list.`,
+
+  handoff: `dotmd handoff <file> [text | - | @path] — queue resume prompt + release
+
+Writes a handoff sidecar attached to the plan, then releases the lease
+and flips frontmatter back to the prior status. The next \`dotmd pickup\`
+of the plan prints the handoff (instead of the plan body) and atomically
+unlinks the sidecar — single-claim guaranteed.
+
+Sidecars live at <repoRoot>/.dotmd/handoffs/<plan-path> and accumulate
+timestamped sections on repeat writes. To replace the chain instead of
+appending, pass --replace.
+
+Sources for handoff text (pick one):
+  <text>                 Inline argument (best for short notes)
+  --message "<text>"     Explicit --message flag (equivalent to inline)
+  -                      Read from stdin (heredoc-friendly for Claude)
+  @path                  Read from a file
+
+Examples:
+  dotmd handoff plans/foo.md "continue from validate(); next: write tests"
+  dotmd handoff plans/foo.md - <<'EOF'
+  …multi-line handoff…
+  EOF
+  dotmd handoff plans/foo.md @/tmp/handoff.md
+
+Options:
+  --replace              Overwrite the sidecar chain instead of appending
+  --json                 Output as JSON
+  --dry-run, -n          Preview without writing
+
+Refuses if the plan is not currently held by this session.`,
+
   finish: `dotmd finish <file> [done|active] — finish working on a plan
 
 Sets the plan status to done (default) or back to active.
@@ -213,6 +259,25 @@ Shows detailed info for all docs matching the given status (default: active).
 Options:
   --json                 Output as JSON`,
 
+  hud: `dotmd hud — three-line actionable triage
+
+Prints up to three lines, in order:
+  ▶ You hold N plans: <slugs>       (leases owned by current session)
+  ▶ N handoffs queued: <slugs>      (resume-prompt sidecars waiting)
+  ⚠ N stuck leases >24h             (suggest \`dotmd release --stale\`)
+
+Silent when all three are empty — designed for SessionStart hooks where
+zero noise is the right default. Distinct from \`dotmd briefing\`, which
+dumps the full plan-status pipeline and per-plan next_step bodies (kilobytes
+on large repos). Use hud for ergonomic session boot; use briefing for
+explicit "give me the full picture."
+
+Recommended SessionStart hook (in ~/.claude/settings.json):
+  "SessionStart": [{ "hooks": [{ "type": "command", "command": "dotmd hud", "timeout": 5 }] }]
+
+Options:
+  --json                 Output as JSON ({ owned, queued, stale })`,
+
   briefing: `dotmd briefing — compact summary for session start
 
 Shows plan statuses with next steps, doc/research counts, and health
@@ -635,8 +700,10 @@ async function main() {
   if (command === 'notion') { const { runNotion } = await import('../src/notion.mjs'); await runNotion(restArgs, config, { dryRun }); return; }
 
   // Lifecycle commands
+  if (command === 'hud') { const { runHud } = await import('../src/hud.mjs'); runHud(restArgs, config); return; }
   if (command === 'pickup') { const { runPickup } = await import('../src/lifecycle.mjs'); await runPickup(restArgs, config, { dryRun }); return; }
-  if (command === 'unpickup') { const { runUnpickup } = await import('../src/lifecycle.mjs'); await runUnpickup(restArgs, config, { dryRun }); return; }
+  if (command === 'unpickup' || command === 'release') { const { runUnpickup } = await import('../src/lifecycle.mjs'); await runUnpickup(restArgs, config, { dryRun }); return; }
+  if (command === 'handoff') { const { runHandoff } = await import('../src/lifecycle.mjs'); await runHandoff(restArgs, config, { dryRun }); return; }
   if (command === 'finish') { const { runFinish } = await import('../src/lifecycle.mjs'); await runFinish(restArgs, config, { dryRun }); return; }
   if (command === 'status') { const { runStatus } = await import('../src/lifecycle.mjs'); await runStatus(restArgs, config, { dryRun }); return; }
   if (command === 'archive') { const { runArchive } = await import('../src/lifecycle.mjs'); runArchive(restArgs, config, { dryRun }); return; }
@@ -895,8 +962,8 @@ async function main() {
 
   // Unknown command — suggest closest match
   const allCommands = [
-    'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'briefing', 'context',
-    'focus', 'query', 'plans', 'stale', 'actionable', 'index', 'pickup', 'finish', 'status', 'archive', 'bulk', 'touch', 'doctor',
+    'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'briefing', 'context', 'hud',
+    'focus', 'query', 'plans', 'stale', 'actionable', 'index', 'pickup', 'release', 'handoff', 'finish', 'status', 'archive', 'bulk', 'touch', 'doctor',
     'unblocks', 'health', 'glossary',
     'fix-refs', 'lint', 'rename', 'migrate', 'notion', 'export', 'summary',
     'watch', 'diff', 'new', 'init', 'completions', 'statuses',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.17.1",
+  "version": "0.19.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/claude-commands.mjs

@@ -16,6 +16,9 @@ function generatePlansCommand(config) {
   lines.push('');
   lines.push('Plan-specific commands:');
   lines.push('- `dotmd context` — briefing with active/paused/ready plans, age tags, next steps');
+  lines.push('- `dotmd pickup <file>` — pick up a plan (set in-session + print body or queued handoff)');
+  lines.push('- `dotmd release` — release current session\'s leases (alias: unpickup)');
+  lines.push('- `dotmd handoff <file> -` — queue a resume-prompt sidecar + release (see /handoff)');
   lines.push('- `dotmd health` — plan velocity, aging, checklist progress, pipeline view');
   lines.push('- `dotmd unblocks <file>` — what depends on / is blocked by a plan');
   lines.push('- `dotmd next` — ready plans with next steps (what to promote)');
@@ -39,6 +42,44 @@ function generatePlansCommand(config) {
   return lines.join('\n');
 }
 
+function generateHandoffCommand(config) {
+  const lines = [VERSION_MARKER, ''];
+  lines.push('Queue a resume-prompt sidecar for every plan this session is currently holding. Use this whenever the user asks for a "resume prompt" / "handoff" / "context dump", or when you are about to stop mid-work and the next session will need to pick up where you left off. NEVER print the resume prompt into chat for copy-paste — write it as a handoff sidecar so the next `dotmd pickup` can consume it cleanly.');
+  lines.push('');
+  lines.push('Steps:');
+  lines.push('');
+  lines.push('1. Identify which plans this session is holding by running:');
+  lines.push('   ```');
+  lines.push('   dotmd plans --status in-session --json');
+  lines.push('   ```');
+  lines.push('   Filter to leases owned by the current session (compare `lease.session` against `$CLAUDE_CODE_SESSION_ID` if needed). If the user passed a specific plan path as an argument, use only that one.');
+  lines.push('');
+  lines.push('2. For each held plan, synthesize a handoff prompt covering:');
+  lines.push('   - One-line summary of where the session got to');
+  lines.push('   - What is already done (and verified working)');
+  lines.push('   - What is in flight / partial / needs verification');
+  lines.push('   - Concrete next step the resuming session should take');
+  lines.push('   - Key files touched (with paths) and any non-obvious gotchas');
+  lines.push('   - Open questions or decisions deferred');
+  lines.push('');
+  lines.push('3. Write each handoff via Bash heredoc:');
+  lines.push('   ```bash');
+  lines.push('   dotmd handoff <plan-path> - <<\'EOF\'');
+  lines.push('   <synthesized handoff body>');
+  lines.push('   EOF');
+  lines.push('   ```');
+  lines.push('   Append-mode is the default. The sidecar accumulates timestamped sections, so a session that writes multiple handoffs over time builds up a chronicle the next session reads in order.');
+  lines.push('');
+  lines.push('4. Report back which plans got handoffs queued and where their sidecars live (the `▶ Handoff queued: <path>` output line). The user closes their window; the next session runs `claude "$(dotmd pickup <plan>)"` and lands seeded with the handoff content.');
+  lines.push('');
+  lines.push('Rules:');
+  lines.push('- If a plan is not held by this session, do not write a handoff for it (dotmd will refuse anyway).');
+  lines.push('- If `dotmd handoff` errors with a recoverable message (existing sidecar conflict, etc.), read the path it cites, merge mentally, then re-run with `--replace`.');
+  lines.push('- Never print the resume text into the conversation as a copy-paste block.');
+  lines.push('');
+  return lines.join('\n');
+}
+
 function generateDocsCommand(config) {
   const roots = Array.isArray(config.raw?.root) ? config.raw.root : [config.raw?.root ?? 'docs'];
   const rootCount = roots.length;
@@ -104,6 +145,7 @@ export function scaffoldClaudeCommands(cwd, config) {
   const files = [
     { name: 'plans.md', generate: () => generatePlansCommand(config) },
     { name: 'docs.md', generate: () => generateDocsCommand(config) },
+    { name: 'handoff.md', generate: () => generateHandoffCommand(config) },
   ];
 
   for (const { name, generate } of files) {
@@ -136,7 +178,7 @@ export function checkClaudeCommands(cwd) {
   if (!existsSync(commandsDir)) return [];
 
   const warnings = [];
-  for (const name of ['plans.md', 'docs.md']) {
+  for (const name of ['plans.md', 'docs.md', 'handoff.md']) {
     const filePath = path.join(commandsDir, name);
     const installedVersion = getInstalledVersion(filePath);
     if (installedVersion && installedVersion !== pkg.version) {

package/src/handoff.mjs

@@ -0,0 +1,59 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+const HANDOFF_DIR = path.join('.dotmd', 'handoffs');
+
+export function handoffPath(config, repoPath) {
+  return path.join(config.repoRoot, HANDOFF_DIR, repoPath);
+}
+
+export function hasHandoff(config, repoPath) {
+  return existsSync(handoffPath(config, repoPath));
+}
+
+export function readHandoff(config, repoPath) {
+  const file = handoffPath(config, repoPath);
+  if (!existsSync(file)) return null;
+  return readFileSync(file, 'utf8');
+}
+
+export function appendHandoff(config, repoPath, text, opts = {}) {
+  const file = handoffPath(config, repoPath);
+  mkdirSync(path.dirname(file), { recursive: true });
+  const stamp = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+  const block = `## ${stamp}\n\n${text.trimEnd()}\n`;
+  if (opts.replace || !existsSync(file)) {
+    writeFileSync(file, block + '\n', 'utf8');
+  } else {
+    const prior = readFileSync(file, 'utf8').trimEnd();
+    writeFileSync(file, `${prior}\n\n${block}\n`, 'utf8');
+  }
+  return file;
+}
+
+export function consumeHandoff(config, repoPath) {
+  const file = handoffPath(config, repoPath);
+  if (!existsSync(file)) return null;
+  const body = readFileSync(file, 'utf8');
+  unlinkSync(file);
+  return body;
+}
+
+export function listQueuedHandoffs(config) {
+  const root = path.join(config.repoRoot, HANDOFF_DIR);
+  if (!existsSync(root)) return [];
+  const out = [];
+  function walk(dir) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) { walk(full); continue; }
+      if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+      const repoPath = path.relative(root, full).split(path.sep).join('/');
+      const st = statSync(full);
+      out.push({ repoPath, path: full, mtimeMs: st.mtimeMs });
+    }
+  }
+  walk(root);
+  out.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return out;
+}

package/src/hud.mjs

@@ -0,0 +1,48 @@
+import path from 'node:path';
+import { readLeases, findStaleLeases, currentSessionId } from './lease.mjs';
+import { listQueuedHandoffs } from './handoff.mjs';
+import { green, yellow, dim } from './color.mjs';
+
+const MAX_PREVIEW = 5;
+
+function slug(repoPath) { return path.basename(repoPath, '.md'); }
+
+function previewList(items, max = MAX_PREVIEW) {
+  const slugs = items.slice(0, max).map(slug);
+  const more = items.length > max ? `, +${items.length - max} more` : '';
+  return slugs.join(', ') + more;
+}
+
+export function buildHud(config) {
+  const session = currentSessionId();
+  const leases = readLeases(config);
+  const owned = Object.values(leases).filter(l => l.session === session).map(l => l.path);
+  const queued = listQueuedHandoffs(config).map(h => h.repoPath);
+  const stale = findStaleLeases(config).map(l => l.path);
+
+  return { owned, queued, stale };
+}
+
+export function runHud(argv, config) {
+  const json = argv.includes('--json');
+  const hud = buildHud(config);
+
+  if (json) {
+    process.stdout.write(JSON.stringify(hud, null, 2) + '\n');
+    return;
+  }
+
+  const lines = [];
+  if (hud.owned.length > 0) {
+    lines.push(green(`▶ You hold ${hud.owned.length} plan${hud.owned.length === 1 ? '' : 's'}: ${previewList(hud.owned)}`));
+  }
+  if (hud.queued.length > 0) {
+    lines.push(green(`▶ ${hud.queued.length} handoff${hud.queued.length === 1 ? '' : 's'} queued: ${previewList(hud.queued)}  ${dim('(resume: dotmd pickup)')}`));
+  }
+  if (hud.stale.length > 0) {
+    lines.push(yellow(`⚠ ${hud.stale.length} stuck lease${hud.stale.length === 1 ? '' : 's'} >24h  ${dim('(run: dotmd release --stale)')}`));
+  }
+
+  if (lines.length === 0) return; // silent when clean
+  process.stdout.write(lines.join('\n') + '\n');
+}

package/src/lifecycle.mjs

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter, replaceFrontmatter } from './frontmatter.mjs';
-import { asString, toRepoPath, die, warn, resolveDocPath, escapeRegex } from './util.mjs';
+import { asString, toRepoPath, die, warn, resolveDocPath, escapeRegex, nowIso } from './util.mjs';
 import { gitMv, getGitLastModified, getGitLastModifiedBatch } from './git.mjs';
 import { buildIndex, collectDocFiles } from './index.mjs';
 import { renderIndexFile, writeIndex } from './index-file.mjs';
@@ -16,6 +16,7 @@ import {
   currentSessionId,
   migrateLease,
 } from './lease.mjs';
+import { hasHandoff, consumeHandoff, appendHandoff, handoffPath, listQueuedHandoffs } from './handoff.mjs';
 
 function findFileRoot(filePath, config) {
   const roots = config.docsRoots || [config.docsRoot];
@@ -70,7 +71,7 @@ export async function runStatus(argv, config, opts = {}) {
     return;
   }
 
-  const today = new Date().toISOString().slice(0, 10);
+  const today = nowIso();
   const archiveDir = path.join(fileRoot, config.archiveDir);
   const relFromRoot = path.relative(fileRoot, filePath);
   const inArchive = relFromRoot.startsWith(config.archiveDir + '/') || relFromRoot.startsWith(config.archiveDir + path.sep);
@@ -136,17 +137,22 @@ export async function runPickup(argv, config, opts = {}) {
   const takeover = argv.includes('--takeover');
   let input = argv.find(a => !a.startsWith('-'));
 
-  // Interactive: pick from active plans
+  // Interactive: pick from active/planned plans + anything with a queued handoff
   if (!input) {
     if (!isInteractive()) die('Usage: dotmd pickup <file>');
     const index = buildIndex(config);
-    const active = index.docs.filter(d => d.type === 'plan' && (d.status === 'active' || d.status === 'planned'));
-    if (active.length === 0) die('No active or planned plans to pick up.');
-    const choice = await promptChoice('Pick a plan:', active.map(d => `${d.title} (${d.status}) — ${d.path}`));
+    const queued = new Set(listQueuedHandoffs(config).map(h => h.repoPath));
+    const candidates = index.docs.filter(d =>
+      d.type === 'plan' && (d.status === 'active' || d.status === 'planned' || queued.has(d.path))
+    );
+    if (candidates.length === 0) die('No active/planned plans and no queued handoffs.');
+    candidates.sort((a, b) => Number(queued.has(b.path)) - Number(queued.has(a.path)));
+    const labelFor = (d) => `${queued.has(d.path) ? '▶ handoff queued · ' : ''}${d.title} (${d.status}) — ${d.path}`;
+    const choice = await promptChoice('Pick a plan:', candidates.map(labelFor));
     if (!choice) die('No plan selected.');
-    const idx = active.findIndex((_, i) => choice === `${active[i].title} (${active[i].status}) — ${active[i].path}`);
+    const idx = candidates.findIndex(d => choice === labelFor(d));
     if (idx === -1) die('No plan selected.');
-    input = active[idx].path;
+    input = candidates[idx].path;
   }
 
   const filePath = resolveDocPath(input, config);
@@ -175,10 +181,11 @@ export async function runPickup(argv, config, opts = {}) {
     }
   }
 
+  const handoffQueued = hasHandoff(config, repoPath);
   const pickupable = new Set(['active', 'planned', 'in-session']);
-  if (oldStatus && !pickupable.has(oldStatus)) die(`Cannot pick up a plan with status '${oldStatus}'. Must be active or planned.\n  ${repoPath}`);
+  if (oldStatus && !pickupable.has(oldStatus) && !handoffQueued) die(`Cannot pick up a plan with status '${oldStatus}'. Must be active or planned.\n  ${repoPath}`);
 
-  const today = new Date().toISOString().slice(0, 10);
+  const today = nowIso();
   const leaseOldStatus = oldStatus === 'in-session' ? 'active' : (oldStatus ?? 'active');
   let leaseOutcome = 'acquired';
 
@@ -204,12 +211,18 @@ export async function runPickup(argv, config, opts = {}) {
     }
   }
 
+  let handoffBody = null;
+  if (handoffQueued && !dryRun) {
+    try { handoffBody = consumeHandoff(config, repoPath); } catch (err) { warn(`Could not consume handoff for ${repoPath}: ${err.message}`); }
+  }
+
   if (json) {
     process.stdout.write(JSON.stringify({
       path: repoPath, oldStatus, newStatus: 'in-session', title,
       reattached: leaseOutcome === 'reattached',
       takenOver: leaseOutcome === 'taken-over',
-      body: body?.trim() ?? '',
+      handoffConsumed: handoffBody !== null,
+      body: (handoffBody ?? body)?.trim() ?? '',
     }, null, 2) + '\n');
   } else {
     if (leaseOutcome === 'reattached') {
@@ -219,7 +232,12 @@ export async function runPickup(argv, config, opts = {}) {
     } else {
       process.stderr.write(`${green('▶ Picked up')}: ${repoPath} (${oldStatus ?? 'unset'} → in-session)\n\n`);
     }
-    if (body?.trim()) process.stdout.write(body.trim() + '\n');
+    const header = handoffBody
+      ? `[dotmd] holding ${repoPath} — consumed handoff. Release with: dotmd release ${repoPath}\n---\n`
+      : `[dotmd] holding ${repoPath} — release with: dotmd release ${repoPath}\n---\n`;
+    process.stdout.write(header);
+    const content = (handoffBody ?? body ?? '').trim();
+    if (content) process.stdout.write(content + '\n');
   }
 
   try { config.hooks.onPickup?.({ path: repoPath, oldStatus, newStatus: 'in-session' }); } catch (err) { warn(`Hook 'onPickup' threw: ${err.message}`); }
@@ -284,7 +302,7 @@ export async function runUnpickup(argv, config, opts = {}) {
       const parsedFm = parseSimpleFrontmatter(fmRaw);
       const cur = asString(parsedFm.status);
       if (cur === 'in-session') {
-        const today = new Date().toISOString().slice(0, 10);
+        const today = nowIso();
         updateFrontmatter(filePath, { status: newStatus, updated: today });
       }
       // If frontmatter is no longer in-session (manual flip), leave it alone.
@@ -394,7 +412,7 @@ export async function runFinish(argv, config, opts = {}) {
 
   if (oldStatus !== 'in-session') die(`Plan is not in-session (current: ${oldStatus}).\n  ${repoPath}`);
 
-  const today = new Date().toISOString().slice(0, 10);
+  const today = nowIso();
 
   if (dryRun) {
     process.stderr.write(`${dim('[dry-run]')} Would update: status: in-session → ${targetStatus}, updated: ${today}\n`);
@@ -433,7 +451,7 @@ export function runArchive(argv, config, opts = {}) {
   const parsed = parseSimpleFrontmatter(frontmatter);
   const oldStatus = asString(parsed.status) ?? 'unknown';
 
-  const today = new Date().toISOString().slice(0, 10);
+  const today = nowIso();
   const targetDir = path.join(archiveFileRoot, config.archiveDir);
   const targetPath = path.join(targetDir, path.basename(filePath));
   const oldRepoPath = toRepoPath(filePath, config.repoRoot);
@@ -590,7 +608,7 @@ export function runTouch(argv, config, opts = {}) {
   const filePath = resolveDocPath(input, config);
   if (!filePath) { die(`File not found: ${input}\nSearched: ${toRepoPath(config.repoRoot, config.repoRoot) || '.'}, ${toRepoPath(config.docsRoot, config.repoRoot)}`); }
 
-  const today = new Date().toISOString().slice(0, 10);
+  const today = nowIso();
 
   if (dryRun) {
     process.stdout.write(`${dim('[dry-run]')} Would touch: ${toRepoPath(filePath, config.repoRoot)} (updated → ${today})\n`);
@@ -706,6 +724,108 @@ function countRefsToUpdate(oldPath, newPath, config) {
   return count;
 }
 
+function readHandoffInput(source) {
+  if (source === '-') {
+    const chunks = [];
+    try { chunks.push(readFileSync(0, 'utf8')); } catch (err) { die(`Could not read handoff from stdin: ${err.message}`); }
+    return chunks.join('');
+  }
+  if (typeof source === 'string' && source.startsWith('@')) {
+    const file = source.slice(1);
+    if (!existsSync(file)) die(`Handoff file not found: ${file}`);
+    return readFileSync(file, 'utf8');
+  }
+  return source;
+}
+
+export async function runHandoff(argv, config, opts = {}) {
+  const { dryRun } = opts;
+  const json = argv.includes('--json');
+  const replace = argv.includes('--replace');
+  const messageIdx = argv.indexOf('--message');
+  const messageFlag = messageIdx >= 0 ? argv[messageIdx + 1] : null;
+  const positional = argv.filter((a, i) => !a.startsWith('--') && argv[i - 1] !== '--message');
+
+  let input = positional[0];
+  let text = messageFlag !== null ? messageFlag : positional[1];
+
+  // Interactive: pick from in-session plans owned by current session
+  if (!input) {
+    if (!isInteractive()) die('Usage: dotmd handoff <file> [text | - | @path]   (or --message "text")');
+    const leases = readLeases(config);
+    const session = currentSessionId();
+    const owned = Object.values(leases).filter(l => l.session === session);
+    if (owned.length === 0) die('No in-session plans owned by this session.');
+    if (owned.length === 1) {
+      input = owned[0].path;
+      process.stderr.write(`${dim(`Auto-selected: ${input}`)}\n`);
+    } else {
+      const choice = await promptChoice('Handoff which plan:', owned.map(l => l.path));
+      if (!choice) die('No plan selected.');
+      input = choice;
+    }
+  }
+
+  const filePath = resolveDocPath(input, config);
+  if (!filePath) die(`File not found: ${input}`);
+  const repoPath = toRepoPath(filePath, config.repoRoot);
+
+  // Resolve text: explicit arg/stdin/@file, else die (no $EDITOR fallback — sessions are non-interactive)
+  if (text === undefined || text === null) {
+    die('Missing handoff text. Pass inline, --message "text", - for stdin, or @path for a file.');
+  }
+  const body = readHandoffInput(text);
+  if (!body.trim()) die('Handoff text is empty.');
+
+  const raw = readFileSync(filePath, 'utf8');
+  const { frontmatter: fmRaw } = extractFrontmatter(raw);
+  const parsedFm = parseSimpleFrontmatter(fmRaw);
+  const oldStatus = asString(parsedFm.status);
+
+  // Must be holding this plan in current session
+  const leases = readLeases(config);
+  const lease = leases[repoPath];
+  const session = currentSessionId();
+  if (!lease || lease.session !== session) {
+    die(`Not held by this session: ${repoPath}\n  Run \`dotmd pickup ${repoPath}\` first.`);
+  }
+
+  const today = nowIso();
+  const targetStatus = lease.oldStatus || 'active';
+
+  if (dryRun) {
+    process.stderr.write(`${dim('[dry-run]')} Would ${replace ? 'replace' : 'append to'} ${toRepoPath(handoffPath(config, repoPath), config.repoRoot)}\n`);
+    process.stderr.write(`${dim('[dry-run]')} Would release lease and flip status: in-session → ${targetStatus}\n`);
+    if (json) process.stdout.write(JSON.stringify({ path: repoPath, handoff: toRepoPath(handoffPath(config, repoPath), config.repoRoot), bytes: body.length, replace, dryRun: true }, null, 2) + '\n');
+    return;
+  }
+
+  // Order: write handoff first, then release. A crash between leaves a queued
+  // handoff with a held lease (recoverable) instead of a released lease with
+  // no handoff (silently lost).
+  const written = appendHandoff(config, repoPath, body, { replace });
+
+  if (oldStatus === 'in-session') {
+    updateFrontmatter(filePath, { status: targetStatus, updated: today });
+  }
+  releaseLease(config, repoPath, { force: true });
+
+  if (json) {
+    process.stdout.write(JSON.stringify({
+      path: repoPath,
+      handoff: toRepoPath(written, config.repoRoot),
+      bytes: body.length,
+      replace,
+      newStatus: targetStatus,
+    }, null, 2) + '\n');
+  } else {
+    process.stdout.write(`${green('▶ Handoff queued')}: ${toRepoPath(written, config.repoRoot)} (${body.length} bytes${replace ? ', replaced' : ', appended'})\n`);
+    process.stdout.write(`${green('↩ Released')}: ${repoPath} (in-session → ${targetStatus})\n`);
+  }
+
+  try { config.hooks.onUnpickup?.({ path: repoPath, oldStatus: 'in-session', newStatus: targetStatus }); } catch (err) { warn(`Hook 'onUnpickup' threw: ${err.message}`); }
+}
+
 export function updateFrontmatter(filePath, updates) {
   const raw = readFileSync(filePath, 'utf8');
   if (!raw.startsWith('---\n')) throw new Error(`${filePath} has no frontmatter block.`);

package/src/new.mjs

@@ -1,6 +1,6 @@
 import { existsSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
-import { toRepoPath, die, warn } from './util.mjs';
+import { toRepoPath, die, warn, nowIso } from './util.mjs';
 import { green, dim, bold } from './color.mjs';
 import { isInteractive, promptText } from './prompt.mjs';
 
@@ -11,9 +11,82 @@ const BUILTIN_TEMPLATES = {
     body: (t) => `\n# ${t}\n`,
   },
   plan: {
-    description: 'Execution plan with module, surface, and cross-references',
-    frontmatter: (s, d) => `type: plan\nstatus: ${s}\nupdated: ${d}\nsurface:\nmodule:\ncurrent_state:\nrelated_plans:`,
-    body: (t) => `\n# ${t}\n\n## Overview\n\n\n\n## Implementation Plan\n\n- [ ] \n\n## Open Questions\n\n\n`,
+    description: 'Execution plan — build-up shape (Problem → Phases → Closeout) with phase status markers and Version History',
+    frontmatter: (s, d) => [
+      'type: plan',
+      `status: ${s}`,
+      `created: ${d}`,
+      `updated: ${d}`,
+      'surfaces: []',
+      'modules: []',
+      'domain:',
+      'audience: internal',
+      'parent_plan:',
+      'related_plans: []',
+      'related_docs: []',
+      'current_state:',
+      'next_step:',
+    ].join('\n'),
+    body: (t, ctx) => `
+# ${t}
+
+> One-paragraph problem statement: what this plan is for, why now.
+
+## Problem
+
+
+
+## Goals
+
+
+
+## Non-Goals
+
+
+
+## What Exists Today
+
+
+
+## Constraints
+
+
+
+## Decisions
+
+
+
+## Open Questions
+
+
+
+## Phases
+
+<!--
+Status markers (put in heading text):
+  ⬜  not started
+  🟡  in progress (pickup targets this)
+  ✅  shipped (history; pickup skips)
+  ⏭  skipped (with reason in body)
+  🚧  blocked (link to blocker)
+-->
+
+### Phase 1 — <title> ⬜
+
+
+
+## Deferred
+
+
+
+## Version History
+
+- **${ctx?.today ?? ''}** Created.
+
+## Closeout
+
+<!-- Filled on archive: what shipped, key commits, deferrals dispositioned. -->
+`,
   },
   adr: {
     description: 'Architecture Decision Record',
@@ -115,7 +188,7 @@ export async function runNew(argv, config, opts = {}) {
     die(`File already exists: ${repoPath}`);
   }
 
-  const today = new Date().toISOString().slice(0, 10);
+  const today = nowIso();
 
   // Generate content
   let content;
@@ -123,7 +196,7 @@ export async function runNew(argv, config, opts = {}) {
     content = template(name, { status, title: docTitle, today });
   } else {
     const fm = template.frontmatter(status, today);
-    const body = template.body(docTitle);
+    const body = template.body(docTitle, { today, status });
     content = `---\n${fm}\n---\n${body}`;
   }
 

package/src/render.mjs

@@ -5,6 +5,7 @@ import { extractFrontmatter } from './frontmatter.mjs';
 import { summarizeDocBody } from './ai.mjs';
 import { bold, red, yellow, green, dim } from './color.mjs';
 import { findStaleLeases } from './lease.mjs';
+import { listQueuedHandoffs } from './handoff.mjs';
 
 export function renderCompactList(index, config) {
   const defaultRenderer = (idx) => _renderCompactList(idx, config);
@@ -265,6 +266,17 @@ function _renderContext(index, config, opts = {}) {
 
 export function renderBriefing(index, config) {
   const lines = [];
+
+  try {
+    const queued = listQueuedHandoffs(config);
+    if (queued.length > 0) {
+      const preview = queued.slice(0, 3).map(h => path.basename(h.repoPath, '.md')).join(', ');
+      const more = queued.length > 3 ? `, +${queued.length - 3} more` : '';
+      lines.push(green(`▶ ${queued.length} handoff${queued.length === 1 ? '' : 's'} queued: ${preview}${more}`));
+      lines.push(dim(`  Resume: claude "$(dotmd pickup <plan>)"  or just: dotmd pickup`));
+    }
+  } catch {}
+
   const plans = index.docs.filter(d => d.type === 'plan');
   const docs = index.docs.filter(d => d.type === 'doc');
   const research = index.docs.filter(d => d.type === 'research');
@@ -301,7 +313,7 @@ export function renderBriefing(index, config) {
   try {
     const staleLeases = findStaleLeases(config);
     if (staleLeases.length > 0) {
-      lines.push(yellow(`Stuck in-session: ${staleLeases.length} (>1d or dead pid, run \`dotmd unpickup --stale\`)`));
+      lines.push(yellow(`Stuck in-session: ${staleLeases.length} (>1d or dead pid, run \`dotmd release --stale\`)`));
     }
   } catch {}
 

package/src/util.mjs

@@ -55,6 +55,10 @@ export function toRepoPath(absolutePath, repoRoot) {
   return path.relative(repoRoot, absolutePath).split(path.sep).join('/');
 }
 
+export function nowIso() {
+  return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+
 export function warn(message) {
   process.stderr.write(`${dim(message)}\n`);
 }