dotmd-cli 0.29.3 → 0.31.0

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.29.3",
+  "version": "0.31.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,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/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/init.mjs

@@ -1,10 +1,15 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
-import { green, dim } from './color.mjs';
+import { green, dim, yellow } from './color.mjs';
 import { warn } from './util.mjs';
 import { scaffoldClaudeCommands } from './claude-commands.mjs';
 
+// Subdirectories scaffolded under docsRoot and tracked separately during scans.
+// Each maps to a builtin type (plan, prompt). New types added here should also
+// have a matching builtin template so `dotmd new <type>` lands files correctly.
+const TYPE_SUBDIRS = ['plans', 'prompts'];
+
 const STARTER_CONFIG = `// dotmd.config.mjs — document management configuration
 // All exports are optional. See dotmd.config.example.mjs for full reference.
 
@@ -33,17 +38,33 @@ function scanExistingDocs(dir) {
   const modules = new Set();
   const refFieldNames = new Set();
   let docCount = 0;
+  // Track files per top-level subdir under `dir` (e.g. plans/, prompts/, "")
+  // so callers can report what's already there — including files without frontmatter,
+  // which are otherwise invisible to detection.
+  const subdirCounts = {};
+
+  function bump(subdir, hasFrontmatter) {
+    if (!subdirCounts[subdir]) subdirCounts[subdir] = { withFrontmatter: 0, withoutFrontmatter: 0 };
+    if (hasFrontmatter) subdirCounts[subdir].withFrontmatter++;
+    else subdirCounts[subdir].withoutFrontmatter++;
+  }
 
-  function walk(d) {
+  function walk(d, topSubdir) {
     let entries;
     try { entries = readdirSync(d, { withFileTypes: true }); } catch (err) { warn(`Could not read ${d}: ${err.message}`); return; }
     for (const entry of entries) {
-      if (entry.isDirectory()) { walk(path.join(d, entry.name)); continue; }
+      if (entry.isDirectory()) {
+        const nextTop = topSubdir === null ? entry.name : topSubdir;
+        walk(path.join(d, entry.name), nextTop);
+        continue;
+      }
       if (!entry.name.endsWith('.md')) continue;
       let raw;
       try { raw = readFileSync(path.join(d, entry.name), 'utf8'); } catch (err) { warn(`Could not read ${entry.name}: ${err.message}`); continue; }
       const { frontmatter } = extractFrontmatter(raw);
-      if (!frontmatter) continue;
+      const subdir = topSubdir ?? '';
+      if (!frontmatter) { bump(subdir, false); continue; }
+      bump(subdir, true);
       const parsed = parseSimpleFrontmatter(frontmatter);
       docCount++;
       if (parsed.status) statuses.add(String(parsed.status).toLowerCase());
@@ -59,8 +80,25 @@ function scanExistingDocs(dir) {
     }
   }
 
-  walk(dir);
-  return { docCount, statuses, surfaces, modules, refFieldNames };
+  walk(dir, null);
+  return { docCount, statuses, surfaces, modules, refFieldNames, subdirCounts };
+}
+
+// Count .md files (regardless of frontmatter) directly inside a single directory.
+// Used to detect root-level plans/ or prompts/ siblings that aren't under docsRoot.
+function countMarkdownFiles(dir) {
+  let withFrontmatter = 0;
+  let withoutFrontmatter = 0;
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return { withFrontmatter, withoutFrontmatter }; }
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+    let raw;
+    try { raw = readFileSync(path.join(dir, entry.name), 'utf8'); } catch { continue; }
+    const { frontmatter } = extractFrontmatter(raw);
+    if (frontmatter) withFrontmatter++; else withoutFrontmatter++;
+  }
+  return { withFrontmatter, withoutFrontmatter };
 }
 
 function generateDetectedConfig(scan, rootPath) {
@@ -112,10 +150,11 @@ export function runInit(cwd, config) {
 
   process.stdout.write('\n');
 
+  const scan = existsSync(docsDir) ? scanExistingDocs(docsDir) : null;
+
   if (existsSync(configPath)) {
     process.stdout.write(`  ${dim('exists')}  dotmd.config.mjs\n`);
   } else {
-    const scan = existsSync(docsDir) ? scanExistingDocs(docsDir) : null;
     if (scan && scan.docCount > 0) {
       writeFileSync(configPath, generateDetectedConfig(scan, 'docs'), 'utf8');
       process.stdout.write(`  ${green('create')}  dotmd.config.mjs (detected ${scan.docCount} docs)\n`);
@@ -132,6 +171,41 @@ export function runInit(cwd, config) {
     process.stdout.write(`  ${green('create')}  docs/\n`);
   }
 
+  // Inspect root-level siblings (e.g. ./plans/, ./prompts/) before scaffolding.
+  // If a sibling already holds content, skip creating the matching docs/<sub>/
+  // so we don't quietly create a parallel dir the user has to reconcile.
+  const siblingsWithContent = [];
+  for (const sub of TYPE_SUBDIRS) {
+    const siblingPath = path.join(cwd, sub);
+    if (!existsSync(siblingPath)) continue;
+    const c = countMarkdownFiles(siblingPath);
+    const total = c.withFrontmatter + c.withoutFrontmatter;
+    if (total > 0) siblingsWithContent.push({ sub, total });
+  }
+  const siblingSet = new Set(siblingsWithContent.map(s => s.sub));
+
+  // Scaffold the canonical type subdirs (docs/plans/, docs/prompts/) so the
+  // builtin `dotmd new plan` / `dotmd new prompt` templates land somewhere
+  // sensible without extra config.
+  for (const sub of TYPE_SUBDIRS) {
+    const subPath = path.join(docsDir, sub);
+    const counts = scan?.subdirCounts?.[sub];
+    const total = counts ? counts.withFrontmatter + counts.withoutFrontmatter : 0;
+    if (siblingSet.has(sub) && !existsSync(subPath)) {
+      process.stdout.write(`  ${yellow('skip')}    docs/${sub}/ (root-level ./${sub}/ already holds content)\n`);
+      continue;
+    }
+    if (existsSync(subPath)) {
+      const detail = total > 0
+        ? ` (${counts.withFrontmatter} dotmd-tracked, ${counts.withoutFrontmatter} plain .md)`
+        : '';
+      process.stdout.write(`  ${dim('exists')}  docs/${sub}/${detail}\n`);
+    } else {
+      mkdirSync(subPath, { recursive: true });
+      process.stdout.write(`  ${green('create')}  docs/${sub}/\n`);
+    }
+  }
+
   if (existsSync(indexPath)) {
     process.stdout.write(`  ${dim('exists')}  docs/docs.md\n`);
   } else {
@@ -139,6 +213,20 @@ export function runInit(cwd, config) {
     process.stdout.write(`  ${green('create')}  docs/docs.md\n`);
   }
 
+  if (siblingsWithContent.length > 0) {
+    const list = siblingsWithContent
+      .map(({ sub, total }) => `${sub}/ (${total} .md file${total === 1 ? '' : 's'})`)
+      .join(', ');
+    const subs = siblingsWithContent.map(s => s.sub);
+    process.stdout.write(`\n  ${yellow('notice')}  found at repo root: ${list}\n`);
+    process.stdout.write(`           these are NOT under docs/ and won't be tracked by the default config. Either:\n`);
+    for (const sub of subs) {
+      process.stdout.write(`             • move into docs/: mv ./${sub}/* docs/${sub}/ && rmdir ./${sub}\n`);
+    }
+    process.stdout.write(`             • or use a flat layout — set in dotmd.config.mjs:\n`);
+    process.stdout.write(`                 export const root = [${subs.map(s => `'${s}'`).join(', ')}];\n`);
+  }
+
   // .gitignore: ensure .dotmd/ is ignored (session leases live there)
   const gitignorePath = path.join(cwd, '.gitignore');
   const ignoreLine = '.dotmd/';

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');

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;
-}