dotmd-cli 0.40.3 → 0.41.1

package/bin/dotmd.mjs

@@ -51,8 +51,8 @@ Lifecycle:
   pickup <file> [--takeover]        Pick up a plan (set in-session + print body)
   release [<file>] [--to <s>]       Release in-session lease (alias: unpickup)
   runlist <hub> [next]              Show or walk an ordered group of plans (see \`dotmd help runlist\`)
-  finish <file> [done|active]       Finish a plan (set done or active)
-  status <file> <status>            Transition document status
+  status <file> <status>            Transition document status (deprecated; prefer \`set\`)
+  set <status> [<file>]             Unified transition: archive/release/transition in one verb
   archive <file>                    Archive (status + move + update refs)
   bulk archive <f1> <f2> ...        Archive multiple files at once
   bulk-tag [files...]               Tag pre-existing untagged .md files
@@ -138,10 +138,10 @@ plan statuses (each maps to a distinct unstuck-action)
 
 Canonical transitions:
   active → in-session              \`dotmd pickup <file>\`
-  in-session → active              \`dotmd release <file>\`
-  in-session → partial             \`dotmd status <file> partial\` (+ release)
-  in-session → awaiting            \`dotmd status <file> awaiting\` (+ release)
-  any → archived                   \`dotmd archive <file>\`
+  in-session → active              \`dotmd set active\` (auto-releases lease)
+  in-session → partial             \`dotmd set partial\` (auto-releases lease)
+  in-session → awaiting            \`dotmd set awaiting\` (auto-releases lease)
+  any → archived                   \`dotmd set archived <file>\` (or \`dotmd archive\`)
 
 ────────────────────────────────────────────────────────────────────
 doc statuses
@@ -295,16 +295,29 @@ 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.`,
 
-  finish: `dotmd finish <file> [done|active] — finish working on a plan
+  set: `dotmd set <status> [<file>] — unified status-transition verb
 
-Sets the plan status to done (default) or back to active.
-Only works on plans currently in-session.
+Routes to the right plumbing based on the target status:
+  - target is an archive status → archive the file (move + ref update)
+  - source is in-session         → also releases the held lease
+  - everything else              → plain frontmatter status bump
+
+When <file> is omitted, dotmd infers it from the calling session's held
+lease. With zero or multiple leases, you must pass <file> explicitly.
+
+To acquire an in-session lease, use \`dotmd pickup <file>\` instead —
+\`dotmd set in-session\` is refused so the asymmetric lease-acquisition
+path is never skipped silently.
 
 Options:
-  --json                 Output as JSON
-  --dry-run, -n          Preview without writing
+  --no-index             Skip index regen (see \`dotmd archive --help\`).
+  --show-files           Append \`files: …\` footer.
+  --dry-run, -n          Preview without writing.
 
-If no file is given, prompts with a list of in-session plans.`,
+Examples:
+  dotmd set partial                 # release current lease, mark partial
+  dotmd set archived docs/plans/x   # archive a specific plan
+  dotmd set active                  # finish a held in-session plan`,
 
   status: `dotmd status <file> <new-status> — transition document status
 
@@ -1135,8 +1148,8 @@ async function main() {
   if (command === 'unpickup' || command === 'release') { const { runUnpickup } = await import('../src/lifecycle.mjs'); await runUnpickup(restArgs, config, { dryRun }); return; }
   if (command === 'runlist') { const { runRunlist } = await import('../src/runlist.mjs'); await runRunlist(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 === 'set') { const { runSet } = await import('../src/lifecycle.mjs'); await runSet(restArgs, config, { dryRun }); return; }
   if (command === 'archive') { const { runArchive } = await import('../src/lifecycle.mjs'); runArchive(restArgs, config, { dryRun }); return; }
   if (command === 'bulk' && restArgs[0] === 'archive') { const { runBulkArchive } = await import('../src/lifecycle.mjs'); runBulkArchive(restArgs.slice(1), config, { dryRun }); return; }
   if (command === 'bulk' && restArgs[0] === 'tag') { const { runBulkTag } = await import('../src/bulk-tag.mjs'); runBulkTag(restArgs.slice(1), config, { dryRun }); return; }

package/dotmd.config.example.mjs

@@ -268,7 +268,6 @@ export const presets = {
 // 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.40.3",
+  "version": "0.41.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

@@ -74,7 +74,8 @@ function generatePlansCommand(config) {
   lines.push('- `dotmd prompts use <file>` — consume a specific prompt (prints body, auto-archives)');
   lines.push('- `dotmd archive <file>` — archive with auto ref-fixing (both directions)');
   lines.push('- `dotmd bulk archive <files>` — archive multiple at once');
-  lines.push('- `dotmd status <file> <status>` — transition status');
+  lines.push('- `dotmd set <status> [<file>]` — unified transition (archive / release / status bump in one verb; infers path from held lease)');
+  lines.push('- `dotmd status <file> <status>` — transition status (legacy; `set` is preferred)');
   lines.push('- `dotmd query --keyword <term>` — find plans by keyword');
 
   if (config.raw?.glossary) {
@@ -153,7 +154,8 @@ function generateDocsCommand(config) {
   lines.push('- `dotmd prompts new <name> "<body>"` — save a resume-prompt');
   lines.push('- `dotmd prompts next` — consume oldest pending prompt (prints body, auto-archives)');
   lines.push('- `dotmd prompts use <file>` — consume a specific prompt (prints body, auto-archives)');
-  lines.push('- `dotmd status <file> <status>` — transition status');
+  lines.push('- `dotmd set <status> [<file>]` — unified transition (archive / release / status bump; infers path from held lease)');
+  lines.push('- `dotmd status <file> <status>` — transition status (legacy; `set` is preferred)');
   lines.push('- `dotmd archive <file>` — archive with auto ref-fixing');
   lines.push('- `dotmd bulk archive <files>` — archive multiple at once');
   lines.push('- `dotmd touch --git` — bulk-sync updated dates from git history');

package/src/commands.mjs

@@ -4,7 +4,7 @@
 // templates points at a real command.
 export const KNOWN_COMMANDS = [
   'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'briefing', 'context', 'hud',
-  'focus', 'query', 'plans', 'prompts', 'stale', 'actionable', 'index', 'pickup', 'release', 'finish', 'status', 'archive', 'bulk', 'bulk-tag', 'touch', 'doctor',
+  'focus', 'query', 'plans', 'prompts', 'stale', 'actionable', 'index', 'pickup', 'release', 'status', 'set', 'archive', 'bulk', 'bulk-tag', 'touch', 'doctor',
   'unblocks', 'health', 'glossary', 'modules', 'module',
   'fix-refs', 'lint', 'rename', 'migrate', 'notion', 'export', 'summary',
   'watch', 'diff', 'new', 'init', 'completions', 'statuses', 'journal',

package/src/completions.mjs

@@ -2,7 +2,7 @@ import { die } from './util.mjs';
 
 const COMMANDS = [
   'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'unblocks', 'health', 'glossary', 'briefing', 'context', 'focus', 'query',
-  'plans', 'stale', 'actionable', 'index', 'pickup', 'unpickup', 'finish', 'status', 'archive', 'bulk', 'touch', 'doctor', 'lint', 'rename', 'migrate',
+  'plans', 'stale', 'actionable', 'index', 'pickup', 'unpickup', 'status', 'set', 'archive', 'bulk', 'touch', 'doctor', 'lint', 'rename', 'migrate',
   'fix-refs', 'notion', 'export', 'summary', 'watch', 'diff', 'init', 'new', 'completions', 'journal',
 ];
 

package/src/lifecycle.mjs

@@ -112,6 +112,10 @@ export async function runStatus(argv, config, opts = {}) {
   const input = argv[0];
   let newStatus = argv[1];
 
+  if (!opts.suppressDeprecation) {
+    process.stderr.write(dim('`dotmd status <file> <status>` is deprecated; prefer `dotmd set <status> [<file>]` (note: <status> first, <file> optional when a lease is held). Removed in a future major.\n'));
+  }
+
   if (!input) { die('Usage: dotmd status <file> <new-status>'); }
 
   const filePath = resolveDocPath(input, config);
@@ -519,66 +523,6 @@ export async function runUnpickup(argv, config, opts = {}) {
   }
 }
 
-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 = nowIso();
-
-  if (dryRun) {
-    process.stderr.write(`${dim('[dry-run]')} Would update: status: in-session → ${targetStatus}, updated: ${today}\n`);
-  } else {
-    updateFrontmatter(filePath, { status: targetStatus, updated: today });
-    regenIndex(config);
-  }
-
-  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`);
-  }
-
-  if (!dryRun) {
-    try { releaseLease(config, repoPath, { force: true }); } catch (err) { warn(`Could not release lease for ${repoPath}: ${err.message}`); }
-  }
-
-  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, out = process.stdout } = opts;
   const noIndex = argv.includes('--no-index') || opts.noIndex;
@@ -680,6 +624,82 @@ export function runArchive(argv, config, opts = {}) {
   return { touched };
 }
 
+// Unified status-transition verb. Collapses status/archive/release into one
+// signature — `dotmd set <status> [<path>]` — and dispatches to the right
+// plumbing based on the *target* status:
+//   - target in archiveStatuses (and file not already archived) → runArchive
+//     (gets us ref-fixing + auto lease release + closeout-template offer)
+//   - source = in-session, target != in-session                → runStatus +
+//     auto-release of the held lease (so users don't have to chain `release`)
+//   - everything else (incl. unarchive, plain transitions)     → runStatus
+//
+// Path is inferred from the calling session's held lease when omitted. With
+// zero leases or >1 leases, we refuse and ask for explicit `<path>` instead
+// of guessing.
+//
+// `dotmd set in-session <path>` is refused — acquiring a lease is asymmetric
+// enough to deserve its own verb (`dotmd pickup`), and silently routing here
+// would skip the lease-acquisition path entirely.
+export async function runSet(argv, config, opts = {}) {
+  const { dryRun } = opts;
+  const noIndex = argv.includes('--no-index');
+  const showFiles = argv.includes('--show-files');
+  argv = argv.filter(a => a !== '--no-index' && a !== '--show-files');
+
+  const newStatus = argv[0];
+  let input = argv[1];
+
+  if (!newStatus) die('Usage: dotmd set <status> [<path>]');
+
+  if (newStatus === 'in-session') {
+    die('To acquire an in-session lease, use `dotmd pickup <file>`. `dotmd set` is for releasing/transitioning a held lease.');
+  }
+
+  if (!input) {
+    const leases = readLeases(config);
+    const sid = currentSessionId();
+    const owned = Object.entries(leases).filter(([_, l]) => l.session === sid);
+    if (owned.length === 0) {
+      die('No <path> given and no held lease to infer from.\nUsage: dotmd set <status> <path>');
+    }
+    if (owned.length > 1) {
+      const paths = owned.map(([p]) => `  - ${p}`).join('\n');
+      die(`No <path> given; you hold ${owned.length} leases:\n${paths}\nSpecify <path> explicitly.`);
+    }
+    input = owned[0][0];
+  }
+
+  const filePath = resolveDocPath(input, config);
+  if (!filePath) die(`File not found: ${input}\nSearched: ${toRepoPath(config.repoRoot, config.repoRoot) || '.'}, ${toRepoPath(config.docsRoot, config.repoRoot)}`);
+
+  const raw = readFileSync(filePath, 'utf8');
+  const { frontmatter: fmRaw } = extractFrontmatter(raw);
+  const parsedFm = parseSimpleFrontmatter(fmRaw);
+  const oldStatus = asString(parsedFm.status);
+
+  const fileRoot = findFileRoot(filePath, config);
+  const relFromRoot = path.relative(fileRoot, filePath);
+  const inArchive = relFromRoot.startsWith(config.archiveDir + '/') || relFromRoot.startsWith(config.archiveDir + path.sep);
+
+  if (config.lifecycle.archiveStatuses.has(newStatus) && !inArchive) {
+    const archiveArgs = [filePath];
+    if (noIndex) archiveArgs.push('--no-index');
+    if (showFiles) archiveArgs.push('--show-files');
+    return runArchive(archiveArgs, config, { dryRun });
+  }
+
+  const statusArgs = [filePath, newStatus];
+  if (noIndex) statusArgs.push('--no-index');
+  if (showFiles) statusArgs.push('--show-files');
+  await runStatus(statusArgs, config, { dryRun, suppressDeprecation: true });
+
+  if (oldStatus === 'in-session' && newStatus !== 'in-session' && !dryRun) {
+    const repoPath = toRepoPath(filePath, config.repoRoot);
+    try { releaseLease(config, repoPath, { force: false }); }
+    catch (err) { warn(`Could not release lease for ${repoPath}: ${err.message}`); }
+  }
+}
+
 export function runBulkArchive(argv, config, opts = {}) {
   const { dryRun } = opts;
   const noIndex = argv.includes('--no-index') || opts.noIndex;