dotmd-cli 0.40.2 → 0.41.0

package/bin/dotmd.mjs

@@ -53,6 +53,7 @@ Lifecycle:
   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
+  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
@@ -306,6 +307,30 @@ Options:
 
 If no file is given, prompts with a list of in-session plans.`,
 
+  set: `dotmd set <status> [<file>] — unified status-transition verb
+
+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:
+  --no-index             Skip index regen (see \`dotmd archive --help\`).
+  --show-files           Append \`files: …\` footer.
+  --dry-run, -n          Preview without writing.
+
+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
 
 Moves the document to the new status. If transitioning to an archive
@@ -1137,6 +1162,7 @@ async function main() {
   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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.40.2",
+  "version": "0.41.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

@@ -14,21 +14,49 @@ const VERSION_MARKER = `<!-- dotmd-generated: ${pkg.version} -->`;
 const VERSION_REGEX = /<!-- dotmd-generated: ([\d.]+) -->/;
 
 // Trigger sentences surfaced by Claude Code's available-skills system reminder.
-// Keep each ≤200 chars (well under the 1,536-char auto-load truncation limit)
-// and front-load the "when to reach for it" cue so Claude can route to the
-// right slash command without the user having to type the slash.
+// Front-load the "when to reach for it" cue so Claude can route to the right
+// slash command without the user having to type the slash. The plans entry
+// gets a per-type status vocab appended at generation time so agents arrive
+// with the valid `dotmd status` / `dotmd archive` values already in context.
 const SLASH_DESCRIPTIONS = {
   plans: "dotmd-managed plan briefing for this repo. Use when the user asks what's on the plate, references a plan slug, queues work, or wants to pick up / release / archive a plan.",
   docs: "dotmd-managed docs briefing for this repo. Use when the user asks to list, scaffold, query, validate, archive, or rename non-plan docs (reference docs, ADRs, RFCs, design notes), or asks how the dotmd doc lifecycle works here.",
   baton: "Save a resume prompt for the held plan and release the lease — the minimum handoff. Use when the user says hand off / save a resume / wrap up, or when context is getting tight.",
 };
 
-function frontmatterFor(name) {
-  return ['---', `description: ${SLASH_DESCRIPTIONS[name]}`, '---'];
+const VOCAB_TRUNCATE_AT = 12;
+
+// Per-type valid statuses, rendered as one clause per type. Appended to the
+// plans description so it lands in Claude's available-skills listing at
+// SessionStart — no discovery command needed before the first `dotmd status`
+// / `dotmd archive` call. Types with no declared statuses are skipped (the
+// generic global list applies); types with >VOCAB_TRUNCATE_AT statuses are
+// truncated with an ellipsis so the description stays bounded.
+function statusVocabClause(config) {
+  if (!config?.typeStatuses) return '';
+  const parts = [];
+  for (const [type, statusesSet] of config.typeStatuses.entries()) {
+    if (!statusesSet || statusesSet.size === 0) continue;
+    let statuses = [...statusesSet];
+    if (statuses.length > VOCAB_TRUNCATE_AT) {
+      statuses = [...statuses.slice(0, VOCAB_TRUNCATE_AT), '…'];
+    }
+    parts.push(`Valid ${type} statuses: ${statuses.join(', ')}.`);
+  }
+  return parts.join(' ');
+}
+
+function frontmatterFor(name, config) {
+  let description = SLASH_DESCRIPTIONS[name];
+  if (name === 'plans') {
+    const vocab = statusVocabClause(config);
+    if (vocab) description = `${description} ${vocab}`;
+  }
+  return ['---', `description: ${description}`, '---'];
 }
 
 function generatePlansCommand(config) {
-  const lines = [...frontmatterFor('plans'), VERSION_MARKER, ''];
+  const lines = [...frontmatterFor('plans', config), VERSION_MARKER, ''];
   lines.push('Run `dotmd context` to get the current plans briefing, then use it to orient yourself.');
   lines.push('');
   lines.push(`Plans are managed by **dotmd** (v${pkg.version}). Config at \`dotmd.config.mjs\`. Always use \`dotmd\` directly.`);
@@ -46,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) {
@@ -65,8 +94,8 @@ function generatePlansCommand(config) {
   return lines.join('\n');
 }
 
-function generateBatonCommand() {
-  const lines = [...frontmatterFor('baton'), VERSION_MARKER, ''];
+function generateBatonCommand(config) {
+  const lines = [...frontmatterFor('baton', config), VERSION_MARKER, ''];
   lines.push('Wrap this session. Minimum required (two commands):');
   lines.push('');
   lines.push('1. **Save the resume prompt.** `dotmd new prompt resume-<plan-slug>` with a 10-20 line body via heredoc: the next concrete decision plus any gotchas. NOT a recap of the plan body. The saved prompt IS the handoff — never print it into chat for copy-paste.');
@@ -89,7 +118,7 @@ function generateDocsCommand(config) {
   const roots = Array.isArray(config.raw?.root) ? config.raw.root : [config.raw?.root ?? 'docs'];
   const rootCount = roots.length;
 
-  const lines = [...frontmatterFor('docs'), VERSION_MARKER, ''];
+  const lines = [...frontmatterFor('docs', config), VERSION_MARKER, ''];
   lines.push(`All documentation in this repo is managed by **dotmd** (v${pkg.version}). Docs across ${rootCount} root${rootCount > 1 ? 's' : ''}: ${roots.join(', ')}. Config at \`dotmd.config.mjs\`.`);
   lines.push('');
 
@@ -125,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');
@@ -157,7 +187,7 @@ export function scaffoldClaudeCommands(cwd, config, opts = {}) {
   const files = [
     { name: 'plans.md', generate: () => generatePlansCommand(config) },
     { name: 'docs.md', generate: () => generateDocsCommand(config) },
-    { name: 'baton.md', generate: () => generateBatonCommand() },
+    { name: 'baton.md', generate: () => generateBatonCommand(config) },
   ];
 
   for (const { name, generate } of files) {

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', 'finish', '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/lifecycle.mjs

@@ -680,6 +680,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 });
+
+  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;