dotmd-cli 0.30.0 → 0.31.1

package/README.md

@@ -146,10 +146,9 @@ 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 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 hud                    Actionable triage (silent when clean — ideal SessionStart hook)
+dotmd pickup <file>          Pick up a plan (in-session + print body)
 dotmd release [<file>]       Release in-session lease (alias: unpickup)
-dotmd handoff <file> [...]   Queue a resume-prompt sidecar + release
 dotmd status <file> <status> Transition document status
 dotmd archive <file>         Archive (status + move + update refs)
 dotmd bulk archive <files>   Archive multiple files at once
@@ -267,7 +266,7 @@ dotmd prompts archive <file>      # archive a prompt
 dotmd prompts new <name> [body]   # alias for `dotmd new prompt`
 ```
 
-`dotmd hud` surfaces pending prompts on session start (alongside held leases and queued handoffs), so a saved prompt acts as a self-addressed reminder: write it now, the next session sees it.
+`dotmd hud` surfaces pending prompts on session start (alongside held leases), so a saved prompt acts as a self-addressed reminder: write it now, the next session sees it.
 
 Statuses: `pending` (drafted, awaiting a session), `claimed` (consumed by a session), `archived`.
 
@@ -448,7 +447,7 @@ dotmd bulk archive docs/old-*.md -n               # preview
 ### Pickup & Closeout
 
 ```bash
-dotmd pickup docs/plans/my-plan.md       # set in-session + print body (or queued handoff)
+dotmd pickup docs/plans/my-plan.md       # set in-session + print body
 dotmd archive docs/plans/my-plan.md      # fully shipped: archive + auto-release lease
 dotmd release docs/plans/my-plan.md      # need more work: release lease, flip to prior status
 dotmd status docs/plans/my-plan.md partial   # shipped + tail deferred (reference successors in body)
@@ -457,30 +456,6 @@ dotmd status docs/plans/my-plan.md awaiting  # stuck on a human decision
 
 `finish` is a legacy command that defaults to `status: done`, which is no longer in the default plan vocabulary as of 0.16. Use `archive` (fully shipped) or `release` + `status` (anything else). If you need it back, add `done` to `types.plan.statuses` in your config.
 
-### 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
@@ -544,7 +519,7 @@ either is silent.
 ```
 
 - **SessionStart** runs `dotmd hud`, which prints up to three actionable
-  lines (held leases, queued handoffs, stale leases) and stays silent when
+  lines (held leases, pending prompts, 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.

package/bin/dotmd.mjs

@@ -14,7 +14,7 @@ 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
+  hud [--json]                      Two-line actionable triage (held / prompts / stuck) — silent when clean
   list [--verbose] [--json]         List docs grouped by status (default command)
   briefing [--json]                 Full briefing with plan status counts + next steps
   context [--summarize] [--json]    Full briefing (LLM-oriented)
@@ -44,9 +44,8 @@ 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 body or queued handoff)
+  pickup <file> [--takeover]        Pick up a plan (set in-session + print body)
   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)
@@ -125,10 +124,6 @@ Sets the plan to in-session and prints its content (prefixed with a
 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).
 - Different session, live pid → refuses with "Held by …" message.
@@ -139,8 +134,7 @@ Options:
   --json                 Output as JSON
   --dry-run, -n          Preview without writing
 
-If no file is given, prompts with a list of active/planned plans plus
-any plan with a queued handoff (sorted to the top).`,
+If no file is given, prompts with a list of active/planned plans.`,
 
   unpickup: `dotmd unpickup [<file>] — release a plan from in-session
 
@@ -171,37 +165,6 @@ 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.
@@ -263,13 +226,12 @@ Options:
 
   hud: `dotmd hud — actionable triage for session start
 
-Prints up to four lines, in order:
+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 pending prompts: <slugs>      (saved prompts in docs/prompts/)
   ⚠ N stuck leases >24h             (suggest \`dotmd release --stale\`)
 
-Silent when all four are empty — designed for SessionStart hooks where
+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
@@ -816,7 +778,7 @@ async function main() {
   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' || 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 === 'handoff') { die('`dotmd handoff` was removed in 0.31.0. Use `dotmd prompts new <name>` to create a saved prompt instead. The .dotmd/handoffs/ sidecar mechanism no longer exists; see CHANGELOG.'); }
   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; }
@@ -1076,7 +1038,7 @@ async function main() {
   // Unknown command — suggest closest match
   const allCommands = [
     'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'briefing', 'context', 'hud',
-    'focus', 'query', 'plans', 'prompts', 'stale', 'actionable', 'index', 'pickup', 'release', 'handoff', 'finish', 'status', 'archive', 'bulk', 'touch', 'doctor',
+    'focus', 'query', 'plans', 'prompts', 'stale', 'actionable', 'index', 'pickup', 'release', '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.30.0",
+  "version": "0.31.1",
   "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,9 +16,8 @@ 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 pickup <file>` — pick up a plan (set in-session + print body)');
   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)');
@@ -47,44 +46,6 @@ 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;
@@ -156,7 +117,6 @@ 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) {
@@ -189,7 +149,7 @@ export function checkClaudeCommands(cwd) {
   if (!existsSync(commandsDir)) return [];
 
   const warnings = [];
-  for (const name of ['plans.md', 'docs.md', 'handoff.md']) {
+  for (const name of ['plans.md', 'docs.md']) {
     const filePath = path.join(commandsDir, name);
     const installedVersion = getInstalledVersion(filePath);
     if (installedVersion && installedVersion !== pkg.version) {

package/src/export.mjs

@@ -151,8 +151,8 @@ function exportMarkdown(docs, config) {
       lines.push(`### ${doc.title}`);
       const meta = [`Status: ${doc.status}`];
       if (doc.updated) meta.push(`Updated: ${doc.updated}`);
-      if (doc.module) meta.push(`Module: ${doc.module}`);
-      if (doc.surface) meta.push(`Surface: ${doc.surface}`);
+      if (doc.modules?.length) meta.push(`Module: ${doc.modules.join(', ')}`);
+      if (doc.surfaces?.length) meta.push(`Surface: ${doc.surfaces.join(', ')}`);
       if (doc.owner) meta.push(`Owner: ${doc.owner}`);
       lines.push(`> ${meta.join(' | ')}`, '');
       if (doc.body.trim()) lines.push(doc.body.trim());
@@ -292,8 +292,8 @@ function buildDocPage(doc) {
   let meta = `<table class="meta">`;
   meta += `<tr><td>Status</td><td><span class="badge ${badgeClass}">${doc.status ?? 'unknown'}</span></td></tr>`;
   if (doc.updated) meta += `<tr><td>Updated</td><td>${escHtml(doc.updated)}</td></tr>`;
-  if (doc.module) meta += `<tr><td>Module</td><td>${escHtml(doc.module)}</td></tr>`;
-  if (doc.surface) meta += `<tr><td>Surface</td><td>${escHtml(doc.surface)}</td></tr>`;
+  if (doc.modules?.length) meta += `<tr><td>Module</td><td>${escHtml(doc.modules.join(', '))}</td></tr>`;
+  if (doc.surfaces?.length) meta += `<tr><td>Surface</td><td>${escHtml(doc.surfaces.join(', '))}</td></tr>`;
   if (doc.owner) meta += `<tr><td>Owner</td><td>${escHtml(doc.owner)}</td></tr>`;
   meta += `<tr><td>Path</td><td><code>${escHtml(doc.path)}</code></td></tr>`;
   meta += `</table>`;

package/src/git.mjs

@@ -1,4 +1,6 @@
 import { spawnSync } from 'node:child_process';
+import { renameSync } from 'node:fs';
+import path from 'node:path';
 
 let gitChecked = false;
 function ensureGit() {
@@ -49,6 +51,20 @@ export function getGitLastModifiedBatch(repoRoot) {
 
 export function gitMv(source, target, repoRoot) {
   ensureGit();
+  // Source is untracked (scaffolded this session, never committed; or repoRoot
+  // is not a git repo at all): a plain rename is the only correct move. `git mv`
+  // would error with `fatal: not under version control` and the user can't act
+  // on that — the file is genuinely a doc, just not yet staged.
+  if (!isTracked(source, repoRoot)) {
+    const absSource = path.isAbsolute(source) ? source : path.join(repoRoot, source);
+    const absTarget = path.isAbsolute(target) ? target : path.join(repoRoot, target);
+    try {
+      renameSync(absSource, absTarget);
+      return { status: 0, stderr: '' };
+    } catch (err) {
+      return { status: 1, stderr: err.message };
+    }
+  }
   const result = spawnSync('git', ['mv', source, target], {
     cwd: repoRoot,
     encoding: 'utf8',
@@ -56,6 +72,15 @@ export function gitMv(source, target, repoRoot) {
   return { status: result.status, stderr: result.stderr };
 }
 
+function isTracked(source, repoRoot) {
+  const relSource = path.isAbsolute(source) ? path.relative(repoRoot, source) : source;
+  const result = spawnSync('git', ['ls-files', '--error-unmatch', '--', relSource], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+  });
+  return result.status === 0;
+}
+
 export function gitDiffSince(relPath, sinceDate, repoRoot, opts = {}) {
   ensureGit();
   // Find the last commit at or before sinceDate

package/src/graph.mjs

@@ -43,7 +43,9 @@ export function buildGraph(index, config, filters = {}) {
     title: d.title,
     status: d.status,
     module: d.module,
+    modules: d.modules,
     surface: d.surface,
+    surfaces: d.surfaces,
     edgeCount: 0,
   }));
   const nodeMap = new Map(nodes.map(n => [n.id, n]));

package/src/hud.mjs

@@ -1,7 +1,6 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { readLeases, findStaleLeases, currentSessionId } from './lease.mjs';
-import { listQueuedHandoffs } from './handoff.mjs';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { asString, toRepoPath } from './util.mjs';
 import { green, yellow, dim } from './color.mjs';
@@ -69,11 +68,10 @@ 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);
   const prompts = findActionablePrompts(config);
 
-  return { owned, queued, stale, prompts };
+  return { owned, stale, prompts };
 }
 
 export function runHud(argv, config) {
@@ -89,9 +87,6 @@ export function runHud(argv, config) {
   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.prompts.length > 0) {
     lines.push(green(`▶ ${hud.prompts.length} pending prompt${hud.prompts.length === 1 ? '' : 's'}: ${previewList(hud.prompts)}  ${dim('(consume: `dotmd prompts use <file>` — do not cat/read)')}`));
   }

package/src/lifecycle.mjs

@@ -16,7 +16,6 @@ import {
   currentSessionId,
   migrateLease,
 } from './lease.mjs';
-import { hasHandoff, consumeHandoff, appendHandoff, handoffPath, listQueuedHandoffs } from './handoff.mjs';
 import { buildCard, renderCard } from './pickup-card.mjs';
 import { walkSections, findSection } from './section.mjs';
 
@@ -163,17 +162,15 @@ export async function runPickup(argv, config, opts = {}) {
   const fullBody = argv.includes('--full');
   let input = argv.find(a => !a.startsWith('-'));
 
-  // Interactive: pick from active/planned plans + anything with a queued handoff
+  // Interactive: pick from active/planned plans
   if (!input) {
     if (!isInteractive()) die('Usage: dotmd pickup <file>');
     const index = buildIndex(config);
-    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))
+      d.type === 'plan' && (d.status === 'active' || d.status === 'planned')
     );
-    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}`;
+    if (candidates.length === 0) die('No active/planned plans.');
+    const labelFor = (d) => `${d.title} (${d.status}) — ${d.path}`;
     const choice = await promptChoice('Pick a plan:', candidates.map(labelFor));
     if (!choice) die('No plan selected.');
     const idx = candidates.findIndex(d => choice === labelFor(d));
@@ -207,9 +204,8 @@ 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) && !handoffQueued) die(`Cannot pick up a plan with status '${oldStatus}'. Must be active or planned.\n  ${repoPath}`);
+  if (oldStatus && !pickupable.has(oldStatus)) die(`Cannot pick up a plan with status '${oldStatus}'. Must be active or planned.\n  ${repoPath}`);
 
   const today = nowIso();
   const leaseOldStatus = oldStatus === 'in-session' ? 'active' : (oldStatus ?? 'active');
@@ -247,19 +243,13 @@ 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) {
-    const card = handoffBody ? null : buildCard(filePath, raw, config);
+    const card = buildCard(filePath, raw, config);
     process.stdout.write(JSON.stringify({
       path: repoPath, oldStatus, newStatus: 'in-session', title,
       reattached: leaseOutcome === 'reattached',
       takenOver: leaseOutcome === 'taken-over',
-      handoffConsumed: handoffBody !== null,
-      body: (handoffBody ?? body)?.trim() ?? '',
+      body: body?.trim() ?? '',
       card,
     }, null, 2) + '\n');
   } else {
@@ -270,18 +260,12 @@ export async function runPickup(argv, config, opts = {}) {
     } else {
       process.stderr.write(`${green('▶ Picked up')}: ${repoPath} (${oldStatus ?? 'unset'} → in-session)\n\n`);
     }
-    if (handoffBody) {
-      const header = `[dotmd] holding ${repoPath} — consumed handoff. Release with: dotmd release ${repoPath}\n---\n`;
-      process.stdout.write(header);
-      const content = handoffBody.trim();
-      if (content) process.stdout.write(content + '\n');
-    } else if (fullBody) {
+    if (fullBody) {
       const header = `[dotmd] holding ${repoPath} — release with: dotmd release ${repoPath}\n---\n`;
       process.stdout.write(header);
       const content = (body ?? '').trim();
       if (content) process.stdout.write(content + '\n');
     } else {
-      // Default: card view
       const card = buildCard(filePath, raw, config);
       process.stdout.write(renderCard(card));
     }
@@ -771,109 +755,6 @@ 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 });
-  }
-  appendVersionHistory(filePath, `Handoff queued (in-session → ${targetStatus}).`);
-  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}`); }
-}
-
 // Append a one-line dated bullet to the file's `## Version History` section.
 // Newest-first ordering: inserted at the top of the section, right after the
 // heading + blank-line gap. If the section is missing, this is a silent no-op

package/src/render.mjs

@@ -5,7 +5,6 @@ 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);
@@ -267,16 +266,6 @@ 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');
@@ -390,10 +379,10 @@ export function renderCoverage(index, config) {
 export function buildCoverage(index, config) {
   const scope = [...new Set(index.docs.map(d => d.status).filter(s => s && !config.lifecycle.terminalStatuses.has(s)))];
   const scoped = index.docs.filter(doc => doc.status && !config.lifecycle.terminalStatuses.has(doc.status));
-  const missingSurface = scoped.filter(doc => !doc.surface);
-  const missingModule = scoped.filter(doc => !doc.module);
-  const modulePlatform = scoped.filter(doc => doc.module === 'platform');
-  const moduleNone = scoped.filter(doc => doc.module === 'none');
+  const missingSurface = scoped.filter(doc => !doc.surfaces?.length);
+  const missingModule = scoped.filter(doc => !doc.modules?.length);
+  const modulePlatform = scoped.filter(doc => doc.modules?.includes('platform'));
+  const moduleNone = scoped.filter(doc => doc.modules?.includes('none'));
   const auditLevelNone = scoped.filter(doc => doc.auditLevel === 'none');
   const audited = scoped.filter(doc => ['pass1', 'pass2', 'deep'].includes(doc.auditLevel));
 

package/src/stats.mjs

@@ -64,8 +64,8 @@ export function buildStats(index, config) {
     completeness: {
       scoped: scoped.length,
       hasOwner: scoped.filter(d => d.owner).length,
-      hasSurface: scoped.filter(d => d.surface).length,
-      hasModule: scoped.filter(d => d.module).length,
+      hasSurface: scoped.filter(d => d.surfaces?.length).length,
+      hasModule: scoped.filter(d => d.modules?.length).length,
       hasNextStep: scoped.filter(d => d.hasNextStep).length,
     },
     checklists: {

package/src/validate.mjs

@@ -102,8 +102,8 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
     doc.errors.push({ path: doc.path, level: 'error', message: '`modules` must be a YAML list when present.' });
   }
 
-  if (config.moduleRequiredStatuses.has(doc.status) && !doc.module) {
-    doc.errors.push({ path: doc.path, level: 'error', message: '`module` is required for active/ready/planned/blocked docs; use a real module, `platform`, or `none`.' });
+  if (config.moduleRequiredStatuses.has(doc.status) && !doc.modules?.length) {
+    doc.errors.push({ path: doc.path, level: 'error', message: '`module` is required for active/ready/planned/blocked docs; use a real module, `platform`, or `none`. Accepts singular `module:` or plural `modules:` list.' });
   }
 
   if (config.validSurfaces) {

package/src/handoff.mjs

@@ -1,59 +0,0 @@
-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;
-}