dotmd-cli 0.11.1 → 0.13.0

package/README.md

@@ -113,13 +113,16 @@ dotmd coverage [--json]      Metadata coverage report
 dotmd stats [--json]         Doc health dashboard
 dotmd graph [--dot|--json]   Visualize document relationships
 dotmd deps [file]            Dependency tree or overview
-dotmd context [--summarize]  Compact briefing (LLM-oriented)
+dotmd briefing               Compact summary for session start
+dotmd context [--summarize]  Full briefing (LLM-oriented)
 dotmd focus [status]         Detailed view for one status group
 dotmd query [filters]        Filtered search
 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 finish <file>          Finish a plan (done or active)
 dotmd status <file> <status> Transition document status
 dotmd archive <file>         Archive (status + move + update refs)
 dotmd touch <file>           Bump updated date

package/bin/dotmd.mjs

@@ -5,10 +5,10 @@ import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import { resolveConfig } from '../src/config.mjs';
 import { buildIndex } from '../src/index.mjs';
-import { renderCompactList, renderVerboseList, renderContext, renderCheck, renderCoverage, buildCoverage } from '../src/render.mjs';
+import { renderCompactList, renderVerboseList, renderContext, renderBriefing, renderCheck, renderCoverage, buildCoverage } from '../src/render.mjs';
 import { renderIndexFile, writeIndex } from '../src/index-file.mjs';
 import { runFocus, runQuery } from '../src/query.mjs';
-import { runStatus, runArchive, runTouch, runBulkArchive } from '../src/lifecycle.mjs';
+import { runStatus, runArchive, runTouch, runBulkArchive, runPickup, runFinish } from '../src/lifecycle.mjs';
 import { runInit } from '../src/init.mjs';
 import { runNew } from '../src/new.mjs';
 import { runCompletions } from '../src/completions.mjs';
@@ -39,7 +39,8 @@ const HELP = {
 View & Query:
   list [--verbose] [--json]         List docs grouped by status (default command)
   json                              Full index as JSON
-  context [--summarize] [--json]    Compact briefing (LLM-oriented)
+  briefing [--json]                 Compact summary for session start (5-10 lines)
+  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.)
   coverage [--json]                 Metadata coverage report
@@ -62,6 +63,8 @@ Validate & Fix:
   fix-refs [--dry-run]              Auto-fix broken reference paths + body links
 
 Lifecycle:
+  pickup <file>                     Pick up a plan (set in-session + print)
+  finish <file> [done|active]       Finish a plan (set done or active)
   status <file> <status>            Transition document status
   archive <file>                    Archive (status + move + update refs)
   bulk archive <f1> <f2> ...        Archive multiple files at once
@@ -130,6 +133,28 @@ Filters:
   --summarize-limit <n>  Max docs to summarize (default: 5)
   --model <name>         Model for AI summaries`,
 
+  pickup: `dotmd pickup <file> — pick up a plan and start working
+
+Sets the plan to in-session and prints its content.
+Fails if the plan is already in-session, blocked, done, or archived.
+
+Options:
+  --json                 Output as JSON
+  --dry-run, -n          Preview without writing
+
+If no file is given, prompts with a list of active plans.`,
+
+  finish: `dotmd finish <file> [done|active] — finish working on a plan
+
+Sets the plan status to done (default) or back to active.
+Only works on plans currently in-session.
+
+Options:
+  --json                 Output as JSON
+  --dry-run, -n          Preview without writing
+
+If no file is given, prompts with a list of in-session plans.`,
+
   status: `dotmd status <file> <new-status> — transition document status
 
 Moves the document to the new status. If transitioning to an archive
@@ -167,7 +192,15 @@ Shows detailed info for all docs matching the given status (default: active).
 Options:
   --json                 Output as JSON`,
 
-  context: `dotmd context — compact briefing (LLM-oriented)
+  briefing: `dotmd briefing — compact summary for session start
+
+Shows plan statuses with next steps, doc/research counts, and health
+in 5-10 lines. Designed for LLM context injection.
+
+Options:
+  --json                 Output as JSON`,
+
+  context: `dotmd context — full briefing (LLM-oriented)
 
 Generates a compact status briefing designed for AI/LLM consumption.
 
@@ -468,6 +501,8 @@ async function main() {
   if (command === 'notion') { await runNotion(restArgs, config, { dryRun }); return; }
 
   // Lifecycle commands
+  if (command === 'pickup') { await runPickup(restArgs, config, { dryRun }); return; }
+  if (command === 'finish') { await runFinish(restArgs, config, { dryRun }); return; }
   if (command === 'status') { await runStatus(restArgs, config, { dryRun }); return; }
   if (command === 'archive') { runArchive(restArgs, config, { dryRun }); return; }
   if (command === 'bulk' && restArgs[0] === 'archive') { runBulkArchive(restArgs.slice(1), config, { dryRun }); return; }
@@ -622,6 +657,24 @@ async function main() {
 
   if (command === 'focus') { runFocus(index, restArgs, config); return; }
   if (command === 'query') { runQuery(index, restArgs, config); return; }
+  if (command === 'briefing') {
+    if (args.includes('--json')) {
+      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');
+      const stale = index.docs.filter(d => d.isStale && !config.lifecycle.skipStaleFor.has(d.status)).length;
+      process.stdout.write(JSON.stringify({
+        plans: { total: plans.length, inSession: plans.filter(d => d.status === 'in-session').map(d => ({ path: d.path, title: d.title, nextStep: d.nextStep })), active: plans.filter(d => d.status === 'active').map(d => ({ path: d.path, title: d.title, nextStep: d.nextStep })) },
+        docs: { total: docs.length, active: docs.filter(d => !config.lifecycle.terminalStatuses.has(d.status)).length },
+        research: { total: research.length, active: research.filter(d => d.status === 'active').length },
+        stale, errorCount: index.errors.length, warningCount: index.warnings.length,
+      }, null, 2) + '\n');
+    } else {
+      process.stdout.write(renderBriefing(index, config));
+    }
+    return;
+  }
+
   if (command === 'context') {
     const summarize = args.includes('--summarize');
     const modelIdx = args.indexOf('--model');
@@ -697,8 +750,8 @@ async function main() {
 
   // Unknown command — suggest closest match
   const allCommands = [
-    'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'context',
-    'focus', 'query', 'plans', 'stale', 'actionable', 'index', 'status', 'archive', 'touch', 'doctor',
+    'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'briefing', 'context',
+    'focus', 'query', 'plans', 'stale', 'actionable', 'index', 'pickup', 'finish', 'status', 'archive', 'touch', 'doctor',
     'fix-refs', 'lint', 'rename', 'migrate', 'notion', 'export', 'summary',
     'watch', 'diff', 'new', 'init', 'completions',
   ];

package/dotmd.config.example.mjs

@@ -147,6 +147,8 @@ export const presets = {
 // export function onNew({ path, status, title, template }) {}
 // export function onRename({ oldPath, newPath, referencesUpdated }) {}
 // export function onLint({ path, fixes }) {}
+// export function onPickup({ path, oldStatus, newStatus }) {}
+// export function onFinish({ path, oldStatus, newStatus }) {}
 
 // AI hooks — override summarization (replaces local MLX model).
 // export function summarizeDoc(body, meta) { return 'Custom summary'; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.11.1",
+  "version": "0.13.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/completions.mjs

@@ -1,8 +1,8 @@
 import { die } from './util.mjs';
 
 const COMMANDS = [
-  'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'unblocks', 'health', 'glossary', 'context', 'focus', 'query',
-  'plans', 'stale', 'actionable', 'index', 'status', 'archive', 'bulk', 'touch', 'doctor', 'lint', 'rename', 'migrate',
+  'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'unblocks', 'health', 'glossary', 'briefing', 'context', 'focus', 'query',
+  'plans', 'stale', 'actionable', 'index', 'pickup', 'finish', 'status', 'archive', 'bulk', 'touch', 'doctor', 'lint', 'rename', 'migrate',
   'fix-refs', 'notion', 'export', 'summary', 'watch', 'diff', 'init', 'new', 'completions',
 ];
 
@@ -32,6 +32,9 @@ const COMMAND_FLAGS = {
   plans: ['--status', '--json', '--sort', '--limit', '--all', '--stale', '--has-next-step'],
   stale: ['--json', '--sort', '--limit', '--all'],
   actionable: ['--json', '--sort', '--limit', '--all'],
+  briefing: ['--json'],
+  pickup: ['--json'],
+  finish: ['--json'],
   status: [],
   archive: [],
   doctor: [],

package/src/lifecycle.mjs

@@ -119,6 +119,118 @@ export async function runStatus(argv, config, opts = {}) {
   }); } catch (err) { warn(`Hook 'onStatusChange' threw: ${err.message}`); }
 }
 
+export async function runPickup(argv, config, opts = {}) {
+  const { dryRun } = opts;
+  const json = argv.includes('--json');
+  let input = argv.find(a => !a.startsWith('-'));
+
+  // Interactive: pick from active plans
+  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}`));
+    if (!choice) die('No plan selected.');
+    const idx = active.findIndex((_, i) => choice === `${active[i].title} (${active[i].status}) — ${active[i].path}`);
+    if (idx === -1) die('No plan selected.');
+    input = active[idx].path;
+  }
+
+  const filePath = resolveDocPath(input, config);
+  if (!filePath) die(`File not found: ${input}`);
+
+  const raw = readFileSync(filePath, 'utf8');
+  const { frontmatter: fmRaw, body } = extractFrontmatter(raw);
+  const parsedFm = parseSimpleFrontmatter(fmRaw);
+  const docType = asString(parsedFm.type) ?? null;
+  const oldStatus = asString(parsedFm.status);
+  const title = asString(parsedFm.title) ?? path.basename(filePath, '.md');
+  const repoPath = toRepoPath(filePath, config.repoRoot);
+
+  if (docType && docType !== 'plan') warn(`${repoPath} has type '${docType}', not 'plan'.`);
+
+  if (oldStatus === 'in-session') die(`Already in-session — another Claude instance may be working on this.\n  ${repoPath}`);
+  if (oldStatus === 'blocked') {
+    const blockers = parsedFm.blockers ? (Array.isArray(parsedFm.blockers) ? parsedFm.blockers.join(', ') : String(parsedFm.blockers)) : 'unknown';
+    die(`Plan is blocked: ${blockers}\n  ${repoPath}`);
+  }
+  const pickupable = new Set(['active', 'planned']);
+  if (oldStatus && !pickupable.has(oldStatus)) die(`Cannot pick up a plan with status '${oldStatus}'. Must be active or planned.\n  ${repoPath}`);
+
+  const today = new Date().toISOString().slice(0, 10);
+
+  if (dryRun) {
+    process.stderr.write(`${dim('[dry-run]')} Would update: status: ${oldStatus} → in-session, updated: ${today}\n`);
+  } else {
+    updateFrontmatter(filePath, { status: 'in-session', updated: today });
+  }
+
+  if (json) {
+    process.stdout.write(JSON.stringify({ path: repoPath, oldStatus, newStatus: 'in-session', title, body: body?.trim() ?? '' }, null, 2) + '\n');
+  } else {
+    process.stderr.write(`${green('▶ Picked up')}: ${repoPath} (${oldStatus} → in-session)\n\n`);
+    if (body?.trim()) process.stdout.write(body.trim() + '\n');
+  }
+
+  try { config.hooks.onPickup?.({ path: repoPath, oldStatus, newStatus: 'in-session' }); } catch (err) { warn(`Hook 'onPickup' threw: ${err.message}`); }
+}
+
+export async function runFinish(argv, config, opts = {}) {
+  const { dryRun } = opts;
+  const json = argv.includes('--json');
+  const positional = argv.filter(a => !a.startsWith('-'));
+  let input = positional[0];
+  const targetStatus = positional[1] ?? 'done';
+
+  if (!['done', 'active'].includes(targetStatus)) die(`Invalid finish status: ${targetStatus}. Use 'done' or 'active'.`);
+
+  // Interactive: pick from in-session plans
+  if (!input) {
+    if (!isInteractive()) die('Usage: dotmd finish <file> [done|active]');
+    const index = buildIndex(config);
+    const inSession = index.docs.filter(d => d.status === 'in-session');
+    if (inSession.length === 0) die('No plans currently in-session.');
+    if (inSession.length === 1) {
+      input = inSession[0].path;
+      process.stderr.write(`${dim(`Auto-selected: ${input}`)}\n`);
+    } else {
+      const choice = await promptChoice('Finish which plan:', inSession.map(d => `${d.title} — ${d.path}`));
+      if (!choice) die('No plan selected.');
+      const idx = inSession.findIndex((_, i) => choice === `${inSession[i].title} — ${inSession[i].path}`);
+      if (idx === -1) die('No plan selected.');
+      input = inSession[idx].path;
+    }
+  }
+
+  const filePath = resolveDocPath(input, config);
+  if (!filePath) die(`File not found: ${input}`);
+
+  const raw = readFileSync(filePath, 'utf8');
+  const { frontmatter: fmRaw } = extractFrontmatter(raw);
+  const parsedFm = parseSimpleFrontmatter(fmRaw);
+  const oldStatus = asString(parsedFm.status);
+  const repoPath = toRepoPath(filePath, config.repoRoot);
+
+  if (oldStatus !== 'in-session') die(`Plan is not in-session (current: ${oldStatus}).\n  ${repoPath}`);
+
+  const today = new Date().toISOString().slice(0, 10);
+
+  if (dryRun) {
+    process.stderr.write(`${dim('[dry-run]')} Would update: status: in-session → ${targetStatus}, updated: ${today}\n`);
+  } else {
+    updateFrontmatter(filePath, { status: targetStatus, updated: today });
+  }
+
+  if (json) {
+    process.stdout.write(JSON.stringify({ path: repoPath, oldStatus, newStatus: targetStatus }, null, 2) + '\n');
+  } else {
+    process.stdout.write(`${green('✓ Finished')}: ${repoPath} (in-session → ${targetStatus})\n`);
+  }
+
+  try { config.hooks.onFinish?.({ path: repoPath, oldStatus, newStatus: targetStatus }); } catch (err) { warn(`Hook 'onFinish' threw: ${err.message}`); }
+}
+
 export function runArchive(argv, config, opts = {}) {
   const { dryRun } = opts;
   const input = argv[0];

package/src/render.mjs

@@ -258,6 +258,44 @@ function _renderContext(index, config, opts = {}) {
   return `${lines.join('\n').trimEnd()}\n`;
 }
 
+export function renderBriefing(index, config) {
+  const lines = [];
+  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');
+  const untyped = index.docs.filter(d => !d.type);
+
+  if (plans.length) {
+    const bySt = {};
+    for (const p of plans) { bySt[p.status] = (bySt[p.status] ?? 0) + 1; }
+    const counts = Object.entries(bySt).map(([s, n]) => `${n} ${s}`).join(', ');
+    lines.push(`${plans.length} plans: ${counts}`);
+    const show = plans.filter(p => p.status === 'in-session' || p.status === 'active');
+    for (const p of show) {
+      const next = p.nextStep ? `next: ${p.nextStep}` : '(no next step)';
+      lines.push(`  > ${path.basename(p.path, '.md')} (${p.status}) ${next}`);
+    }
+  }
+
+  const parts = [];
+  if (docs.length) {
+    const active = docs.filter(d => !config.lifecycle.terminalStatuses.has(d.status)).length;
+    const rest = docs.length - active;
+    parts.push(`${active} docs active` + (rest ? `, ${rest} other` : ''));
+  }
+  if (research.length) {
+    const active = research.filter(d => d.status === 'active').length;
+    parts.push(`${active} research active`);
+  }
+  if (untyped.length) parts.push(`${untyped.length} untyped`);
+  if (parts.length) lines.push(parts.join(' | '));
+
+  const stale = index.docs.filter(d => d.isStale && !config.lifecycle.skipStaleFor.has(d.status)).length;
+  lines.push(`Stale: ${stale} | Errors: ${index.errors.length} | Warnings: ${index.warnings.length}`);
+
+  return lines.join('\n') + '\n';
+}
+
 export function renderCheck(index, config, opts = {}) {
   const defaultRenderer = (idx) => _renderCheck(idx, opts);
   if (config.hooks.renderCheck) {