dotmd-cli 0.77.3 → 0.78.0

package/README.md

@@ -125,8 +125,15 @@ operation:
 dotmd baton @/tmp/resume.md
 ```
 
+Baton refuses when a handoff for the same work is already pending, so one piece
+of work never has two resume prompts.
+
 Saved prompts are local session state. Consume them with `dotmd use`; inspect
-without consuming via `dotmd prompts show`.
+without consuming via `dotmd prompts show`. Consuming a baton prompt also claims
+its plan; `dotmd use --no-claim` reads and archives it without starting the plan.
+
+New plans are created `planned`; `dotmd use` starts one, and
+`dotmd new plan <name> --status <status>` sets a different starting status.
 
 ## Document Format
 

package/assets/opencode/plugin.js

@@ -32,7 +32,9 @@ function cliExecutables() {
   return process.platform === 'win32' ? ['runlist.cmd', 'dotmd.cmd'] : ['runlist', 'dotmd'];
 }
 
-function runHud(directory) {
+// Runs the CLI and resolves its trimmed stdout, or '' on any failure. `input`,
+// when given, is written to the child's stdin.
+function runCli(directory, args, input = null) {
   return new Promise(resolve => {
     let settled = false;
     const done = value => { if (!settled) { settled = true; resolve(value); } };
@@ -40,7 +42,7 @@ function runHud(directory) {
     const attempt = index => {
       if (index >= candidates.length) { done(''); return; }
       try {
-        execFile(candidates[index], ['hud'], {
+        const child = execFile(candidates[index], args, {
           cwd: directory,
           timeout: PRIMER_TIMEOUT_MS,
           windowsHide: true,
@@ -49,12 +51,33 @@ function runHud(directory) {
           if (error?.code === 'ENOENT') attempt(index + 1);
           else done(error ? '' : (stdout ?? '').trim());
         });
+        child.stdin?.on('error', () => {});
+        if (input !== null) child.stdin?.end(input);
+        else child.stdin?.end();
       } catch { attempt(index + 1); }
     };
     attempt(0);
   });
 }
 
+// OpenCode runs no Claude Code hooks, so `dotmd guard` never sees its tool
+// calls, and sessions opened pending prompts with the read tool, which prints a
+// prompt without archiving it. The guard's answer for a prompt read is a
+// warning, not a block, so it is applied after the call: the teaching text is
+// appended to what the agent sees. Only calls that name a prompt file reach
+// the CLI; everything else costs a regex.
+const PROMPT_FILE = /(^|[\\/])prompts[\\/]\S*\.md\b/;
+
+function guardPayload(tool, args) {
+  if (tool === 'read' && typeof args?.filePath === 'string' && PROMPT_FILE.test(args.filePath)) {
+    return { tool_name: 'Read', tool_input: { file_path: args.filePath } };
+  }
+  if (tool === 'bash' && typeof args?.command === 'string' && PROMPT_FILE.test(args.command)) {
+    return { tool_name: 'Bash', tool_input: { command: args.command } };
+  }
+  return null;
+}
+
 export default async function dotmdOpencodePlugin({ directory }) {
   // Keyed by session so a subagent session primes independently, the way
   // SubagentStart does under Claude Code.
@@ -68,7 +91,7 @@ export default async function dotmdOpencodePlugin({ directory }) {
     // only the first request — and a never-refreshed one would keep announcing
     // a pending prompt this session already consumed.
     if (cached && Date.now() - cached.at < PRIMER_TTL_MS) return cached.text;
-    const text = await runHud(directory);
+    const text = await runCli(directory, ['hud']);
     primers.set(key, { text, at: Date.now() });
     return text;
   }
@@ -93,6 +116,19 @@ export default async function dotmdOpencodePlugin({ directory }) {
       } catch { /* never break a shell over this */ }
     },
 
+    // The guard's warnings, appended after the call ran. A `deny` from the
+    // guard is ignored here: the call has already happened, so there is
+    // nothing left to refuse.
+    'tool.execute.after': async (input, output) => {
+      try {
+        const payload = guardPayload(input?.tool, input?.args);
+        if (!payload || typeof output?.output !== 'string') return;
+        const raw = await runCli(directory, ['guard'], JSON.stringify(payload));
+        const note = raw ? JSON.parse(raw)?.hookSpecificOutput?.additionalContext : null;
+        if (typeof note === 'string' && note) output.output += `\n\n${note}`;
+      } catch { /* a guard failure never touches the tool result */ }
+    },
+
     // Session priming — the equivalent of the SessionStart hook that runs
     // `dotmd hud` under Claude Code. Silent outside a dotmd repo (hud prints
     // nothing and exits 0), so this is inert in unrelated projects.

package/bin/dotmd.mjs

@@ -1150,6 +1150,10 @@ Subcommands:
 slug matching a prompt basename, or a unique substring of a prompt
 path. Ambiguous substrings error with the candidate list.
 
+A prompt saved by \`dotmd baton\` links its plan; consuming it (\`use\`,
+\`next\`, or top-level \`dotmd use\`) also claims that plan for this session.
+Pass \`--no-claim\` to read and archive the prompt without starting the plan.
+
 Default prompt statuses: pending, archived.
 
 Examples:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.77.3",
+  "version": "0.78.0",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, lifecycle, and AI summaries.",
   "type": "module",
   "license": "MIT",

package/src/baton.mjs

@@ -1,7 +1,7 @@
-import { readFileSync, existsSync, writeFileSync } from 'node:fs';
+import { readFileSync, existsSync, writeFileSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
-import { asString, toRepoPath, die, warn } from './util.mjs';
+import { asString, toRepoPath, die, warn, isArchivedPath, resolveRefPath } from './util.mjs';
 import { buildIndex, resolveDocArg } from './index.mjs';
 import { preparePromptDocument, runNew, readBodyInput, readPipedBodyInput } from './new.mjs';
 import { ensurePlanCompletionBeforeRelease, planHasPendingCompletion, runSet } from './lifecycle.mjs';
@@ -26,11 +26,42 @@ export function findOwnedPlan(config, index = null) {
   return { plan: clean && owned.length === 1 ? owned[0] : null, via: clean && owned.length === 1 ? 'ownership' : null, inSession, owned, diagnostics: records.diagnostics ?? [] };
 }
 
-const BODY_USAGE = `dotmd baton needs the resume draft as its body. Write 10–20 lines first — the next concrete decision plus any gotchas, NOT a recap of the plan — then:
-  dotmd baton @/tmp/draft.md             # body from file (preferred)
-  cat /tmp/draft.md | dotmd baton        # body from stdin
-  dotmd baton --message "..."            # one-liner
-No plan in-session? Name the handoff instead: dotmd baton <slug> @/tmp/draft.md`;
+// One line that says what is missing, then one example. Baton never drafts the
+// resume itself: the session that did the work is the only one that knows the
+// next decision, and a prompt assembled from frontmatter reads like a handoff
+// while carrying nothing the plan doesn't already say.
+const BODY_USAGE = `Nothing saved: baton needs the resume you wrote, passed as @<file> or - (stdin).
+  dotmd baton [<plan-or-slug>] @/tmp/draft.md`;
+
+// A handoff that lands beside a pending one leaves two prompts for the same
+// work, and the next session picks whichever sorts first. Baton used to step to
+// `resume-<x>-2` silently; it now refuses and names what is waiting, so the
+// older prompt is consumed or archived on purpose. Plan mode also catches a
+// pending prompt under a different name that links the same plan.
+function pendingHandoffs(promptPath, planPath, config) {
+  const found = new Set();
+  if (existsSync(promptPath)) found.add(toRepoPath(promptPath, config.repoRoot));
+  if (planPath) {
+    const planReal = realpathSync(planPath);
+    const index = buildIndex(config, { fast: true, invokeHooks: false });
+    for (const doc of index.docs) {
+      if (doc.type !== 'prompt' || doc.status === 'archived' || isArchivedPath(doc.path, config)) continue;
+      const abs = path.resolve(config.repoRoot, doc.path);
+      let planRef;
+      try { planRef = asString(parseSimpleFrontmatter(extractFrontmatter(readFileSync(abs, 'utf8')).frontmatter).plan); }
+      catch { continue; }
+      const linked = planRef ? resolveRefPath(planRef, path.dirname(abs), config.repoRoot) : null;
+      if (linked && realpathSync(linked) === planReal) found.add(doc.path);
+    }
+  }
+  return [...found];
+}
+
+function refusePendingHandoff(pending) {
+  const lines = pending.map(p => `  ${p}`).join('\n');
+  const slug = path.basename(pending[0], '.md');
+  die(`Nothing saved: a handoff for this is already pending:\n${lines}\nUse it (\`dotmd use ${slug}\`) or archive it (\`dotmd prompts archive ${pending[0]}\`), then run baton again.`);
+}
 
 // Is this positional a filesystem reference (must resolve, typos die) or a
 // bare word (may be a plan slug, may be a brand-new handoff name)?
@@ -114,6 +145,14 @@ export async function runBaton(argv, config, opts = {}) {
     }
   }
 
+  const nameBase = planPath ? path.basename(planPath, '.md') : promptSlug;
+  const slugBase = nameBase.startsWith('resume-') ? nameBase : `resume-${nameBase}`;
+  const refuseIfPending = () => {
+    const target = preparePromptDocument(slugBase, body, config, { dryRun: true });
+    const pending = pendingHandoffs(target.filePath, planPath, config);
+    if (pending.length) refusePendingHandoff(pending);
+  };
+
   let repoPath = null;
   let oldStatus = null;
   let ownershipPath = null;
@@ -140,18 +179,19 @@ export async function runBaton(argv, config, opts = {}) {
       die('`dotmd baton --status in-session` contradicts baton release semantics. Choose active/paused/awaiting/partial/blocked.');
     }
     assertPlanMutationAuthorized(repoPath, config, { sessionId: authoritativeSessionId(), force });
+    // Before the plan-completion step: a refusal must leave nothing changed.
+    refuseIfPending();
     ownershipPath = readPlanOwnership(repoPath, config)?.recordPath ?? null;
     if (!dryRun) ensurePlanCompletionBeforeRelease(repoPath, config, { testHooks: opts.testHooks });
     else if (planHasPendingCompletion(repoPath, config)) process.stderr.write(`${dim('[dry-run]')} Pending claim completion would block this release.\n`);
   } else {
+    refuseIfPending();
     if (statusFlag) warn(`--status ignored — no plan involved in this handoff (saving the prompt only).`);
     if (note) warn(`--note ignored — no plan involved in this handoff (notes land in a plan's Version History).`);
   }
 
   // Plan mode publishes the already-stamped prompt, status/history update, and
   // ownership release in one transaction. Slug mode has no plan transaction.
-  const nameBase = planPath ? path.basename(planPath, '.md') : promptSlug;
-  const slugBase = nameBase.startsWith('resume-') ? nameBase : `resume-${nameBase}`;
   let createdSlug = null;
   let archiveResult = null;
   let statusChanged = false;
@@ -162,49 +202,45 @@ export async function runBaton(argv, config, opts = {}) {
   if (json) process.stdout.write = chunk => { muted.push(String(chunk)); return true; };
   try {
   if (!planPath) {
-    for (let n = 1; n <= 9 && !createdSlug; n++) {
-      const slug = n === 1 ? slugBase : `${slugBase}-${n}`;
-      try {
-        const prepared = preparePromptDocument(slug, body, config, { dryRun });
-        newResult = await runNew(['prompt', slug, '--body', body], config, { dryRun, deferIndex: true });
-        createdSlug = slug;
-        promptRepoPath = prepared.repoPath;
-      }
-      catch (err) { if (!/File already exists/.test(String(err?.message))) throw err; }
+    const prepared = preparePromptDocument(slugBase, body, config, { dryRun });
+    try {
+      newResult = await runNew(['prompt', slugBase, '--body', body], config, { dryRun, deferIndex: true });
+    } catch (err) {
+      // Lost a race with another baton between the pending check and the write.
+      if (/File already exists/.test(String(err?.message))) refusePendingHandoff([prepared.repoPath]);
+      throw err;
     }
+    createdSlug = slugBase;
+    promptRepoPath = prepared.repoPath;
   } else {
-    for (let n = 1; n <= 9 && !createdSlug; n++) {
-      const candidate = n === 1 ? slugBase : `${slugBase}-${n}`;
-      const prepared = preparePromptDocument(candidate, body, config, { plan: repoPath, dryRun });
-      if (existsSync(prepared.filePath)) continue;
-      const setArgs = [status, planPath];
-      if (force) setArgs.push('--force');
-      if (note) setArgs.push('--note', note);
-      try {
-        if (dryRun) process.stdout.write(`${dim('[dry-run]')} Would create: ${prepared.repoPath}\n`);
-        archiveResult = await runSet(setArgs, config, {
-          dryRun,
-          viaBaton: true,
-          testHooks: opts.testHooks,
-          creations: dryRun ? [] : [{ path: prepared.filePath, content: prepared.content }],
-          deferIndex: true,
-        });
-        createdSlug = prepared.slug;
-        promptRepoPath = prepared.repoPath;
-        statusChanged = oldStatus !== status;
-        if (!dryRun) {
-          try { config.hooks.onNew?.({ path: prepared.repoPath, status: 'pending', title: prepared.slug, type: 'prompt' }); }
-          catch (err) { warn(`Hook 'onNew' threw: ${err.message}`); }
-        }
-      } catch (err) {
-        if (!/Destination already exists|File already exists/.test(String(err?.message))) throw err;
-      }
+    const prepared = preparePromptDocument(slugBase, body, config, { plan: repoPath, dryRun });
+    const setArgs = [status, planPath];
+    if (force) setArgs.push('--force');
+    if (note) setArgs.push('--note', note);
+    try {
+      if (dryRun) process.stdout.write(`${dim('[dry-run]')} Would create: ${prepared.repoPath}\n`);
+      archiveResult = await runSet(setArgs, config, {
+        dryRun,
+        viaBaton: true,
+        testHooks: opts.testHooks,
+        creations: dryRun ? [] : [{ path: prepared.filePath, content: prepared.content }],
+        deferIndex: true,
+      });
+    } catch (err) {
+      if (/Destination already exists|File already exists/.test(String(err?.message))) refusePendingHandoff([prepared.repoPath]);
+      throw err;
+    }
+    createdSlug = prepared.slug;
+    promptRepoPath = prepared.repoPath;
+    statusChanged = oldStatus !== status;
+    if (!dryRun) {
+      try { config.hooks.onNew?.({ path: prepared.repoPath, status: 'pending', title: prepared.slug, type: 'prompt' }); }
+      catch (err) { warn(`Hook 'onNew' threw: ${err.message}`); }
     }
   }
   } finally {
     if (json) process.stdout.write = originalStdoutWrite;
   }
-  if (!createdSlug) die(`Could not find a free prompt slug for ${slugBase} (tried ${slugBase}-2 … ${slugBase}-9).`);
 
   // A release status can FILE the plan into a bucket (`lifecycle.filedStatuses`,
   // e.g. paused → docs/plans/held/). The prompt is created inside the same

package/src/commands.mjs

@@ -92,16 +92,16 @@ const definitions = [
   command('prompts', mutates('managed sources/destinations by subcommand'), 'workflow', [
     form('', { options: [flag('--json'), value('--status'), flag('--include-archived'), value('--sort'), value('--limit'), flag('--all')] }),
     form('list', { subcommands: ['list', 'status'], options: [flag('--json'), value('--status'), flag('--include-archived'), value('--sort'), value('--limit'), flag('--all')] }),
-    form('next', { subcommands: ['next'] }),
-    form('use [file]', { subcommands: ['use', 'resume'], args: positionals(0, 1), options: [flag('--no-index'), flag('--show-files'), flag('--force')] }),
+    form('next', { subcommands: ['next'], options: [flag('--no-claim')] }),
+    form('use [file]', { subcommands: ['use', 'resume'], args: positionals(0, 1), options: [flag('--no-index'), flag('--show-files'), flag('--force'), flag('--no-claim')] }),
     form('show [file...]', { subcommands: ['show', 'peek'], args: positionals(0, Infinity), options: [flag('--json'), flag('--all'), value('--limit')] }),
     form('archive <file>', { subcommands: ['archive'], args: positionals(1, 1), options: [flag('--no-index'), flag('--show-files')] }),
     form('new <slug> [body...]', { subcommands: ['new'], args: positionals(1, Infinity), options: [value('--body', '--message'), value('--title'), value('--status')] }),
     form('hold <file>', { subcommands: ['hold', 'shelve'], args: positionals(1, 1) }),
     form('unhold <file>', { subcommands: ['unhold', 'unshelve'], args: positionals(1, 1) }),
   ], { aliases: ['prompt'] }),
-  command('use', mutates('managed source when starting/consuming; docs remain read-only'), 'workflow', [form('[file]', { args: positionals(0, 1), options: [flag('--json'), flag('--full'), flag('--no-index'), flag('--show-files'), flag('--force')] })]),
-  command('next', mutates('managed prompt source and same-root archive destination'), 'workflow', [form('', { options: [flag('--json'), flag('--no-index'), flag('--show-files'), flag('--force')] })]),
+  command('use', mutates('managed source when starting/consuming; docs remain read-only'), 'workflow', [form('[file]', { args: positionals(0, 1), options: [flag('--json'), flag('--full'), flag('--no-index'), flag('--show-files'), flag('--force'), flag('--no-claim')] })]),
+  command('next', mutates('managed prompt source and same-root archive destination'), 'workflow', [form('', { options: [flag('--json'), flag('--no-index'), flag('--show-files'), flag('--force'), flag('--no-claim')] })]),
   command('baton', mutates('managed plan/prompt sources and managed prompt destination'), 'workflow', [form('[plan|slug] <@<file>|->', { args: positionals(0, 2), options: [value('--status'), value('--note'), value('--body', '--message'), flag('--force'), flag('--json')] })]),
   command('runlist', mutates('managed hubs/children and managed scaffold destinations'), 'workflow', [
     form('<hub>', { args: positionals(1, 1), options: [flag('--json')] }),

package/src/guard.mjs

@@ -223,8 +223,11 @@ function editStatusResult(target, config, detail) {
     rule: 'edit-status',
     detail,
     reason:
-      `Looks like a hand-edit of the \`status:\` field in ${target}. Use \`dotmd set <status> ${target}\` instead — ` +
-      `it validates the status against this doc's type, runs lifecycle hooks, fixes refs, and keeps the index in sync. Direct edits skip all of that.`,
+      // Names the canonical executable: a session that follows this message
+      // should land on the current name, not the legacy alias.
+      `Looks like a hand-edit of the \`status:\` field in ${target}. Use \`runlist set <status> ${target}\` instead — ` +
+      `it validates the status against this doc's type, runs lifecycle hooks, fixes refs, and keeps the index in sync. Direct edits skip all of that. ` +
+      `Creating a doc? \`runlist new <type> <name> --status <status>\` writes the status in the same step.`,
   };
 }
 

package/src/new.mjs

@@ -132,7 +132,10 @@ ${ctx?.bodyInput?.trim() ?? ''}
     description: 'Execution plan — build-up shape (Problem → Phases → Closeout) with phase status markers and Version History',
     dir: 'plans',
     targetRoot: 'plans',
-    defaultStatus: 'active',
+    // A scaffolded plan is scoped, not being worked; `dotmd use` starts it.
+    // Defaulting to `active` forced a second, guarded status write for every
+    // plan that was only being written down.
+    defaultStatus: 'planned',
     // Body input lands in the Problem section. Plans don't have an Overview;
     // Problem is the established opening section in the build-up shape.
     acceptsBody: true,

package/src/prompts.mjs

@@ -196,7 +196,7 @@ async function runPromptsNext(argv, config, opts = {}) {
   }
   const head = queue[0];
   if (!head.abs) die(`Could not resolve path: ${head.doc.path}`);
-  return consumePrompt(head.abs, config, opts);
+  return consumePrompt(head.abs, config, { ...opts, noClaim: argv.includes('--no-claim') });
 }
 
 // Resolve user input to a prompt path. Tries (in order): exact path,
@@ -245,8 +245,9 @@ async function runPromptsUse(argv, config, opts = {}) {
   if (!input) die('Usage: dotmd prompts use <file-or-slug>');
   const noIndex = argv.includes('--no-index') || opts.noIndex;
   const showFiles = argv.includes('--show-files') || opts.showFiles;
+  const noClaim = argv.includes('--no-claim');
   const filePath = resolvePromptInput(input, config);
-  return consumePrompt(filePath, config, { ...opts, noIndex, showFiles });
+  return consumePrompt(filePath, config, { ...opts, noIndex, showFiles, noClaim });
 }
 
 export async function consumePrompt(filePath, config, opts) {
@@ -269,7 +270,9 @@ export async function consumePrompt(filePath, config, opts) {
   const planRef = asString(parsed.plan);
   let linkedClaim = null;
   let claimSkipReason = null;
-  if (planRef) {
+  if (planRef && opts.noClaim) {
+    claimSkipReason = `--no-claim, ${planRef} left as it is`;
+  } else if (planRef) {
     const outcome = prepareLinkedPromptClaim(planRef, config, path.dirname(filePath));
     if (outcome?.skipped) claimSkipReason = outcome.reason;
     else linkedClaim = outcome;

package/src/use.mjs

@@ -15,13 +15,16 @@ import { resolveDocArg } from './index.mjs';
 // With no argument, consumes the oldest pending prompt.
 export async function runUse(argv, config, opts = {}) {
   const positional = argv.find(a => !a.startsWith('-'));
+  // `--no-claim` reads and archives a prompt without starting the plan it links.
+  const noClaim = argv.includes('--no-claim');
+  const promptOpts = { ...opts, noClaim };
 
   if (!positional) {
     const queue = pendingPromptsOldestFirst(config);
     if (queue.length === 0) die('No pending prompts. Pass a file to use a plan or doc.');
     const head = queue[0];
     if (!head.abs) die(`Could not resolve path: ${head.doc.path}`);
-    return consumePrompt(head.abs, config, opts);
+    return consumePrompt(head.abs, config, promptOpts);
   }
 
   // Exact path first, then prompt slugs (they keep precedence on a slug
@@ -39,8 +42,9 @@ export async function runUse(argv, config, opts = {}) {
   const type = asString(parsed.type);
 
   if (type === 'prompt') {
-    return consumePrompt(filePath, config, opts);
+    return consumePrompt(filePath, config, promptOpts);
   }
+  if (noClaim) die('--no-claim applies to prompts only; a plan opened with `use` is always claimed.');
   if (type === 'plan') {
     // Mark in-session (pure frontmatter) and print the plan card.
     return startPlan([filePath, ...argv.filter(a => a !== positional)], config, opts);