dotmd-cli 0.87.1 → 0.88.1

package/README.md

@@ -97,20 +97,21 @@ Restart Claude Code, or run `/reload-plugins`, after a plugin update.
 ```bash
 runlist init                    # create config, docs/, and the generated index
 runlist new plan auth-refresh  # scaffold a typed document
-runlist briefing               # compact active-work orientation
-runlist plans                  # live plan dashboard
+runlist plans                  # compact live plan dashboard
+runlist briefing               # comprehensive active-work view
 runlist check                  # validate schema, references, and lifecycle shape
 runlist doctor                 # preview repairs; add --apply to write
 ```
 
-`runlist briefing` is the compact orientation view. `runlist context` is the fuller
+`runlist plans` is the compact orientation view. `runlist briefing` lists live
+plans with next steps and grows with the corpus. `runlist context` is the fuller
 human/LLM briefing, while `runlist agent-context` emits bounded structured JSON for
 agent integrations.
 
 ## Core Workflow
 
 ```bash
-runlist briefing
+runlist plans
 runlist use docs/plans/auth-refresh.md
 runlist set awaiting docs/plans/auth-refresh.md --note "Need API owner decision"
 runlist set active docs/plans/auth-refresh.md --note "Decision received"
@@ -130,7 +131,15 @@ runlist 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.
+of work never has two resume prompts. Inspect the pending handoff with
+`runlist prompts show <slug>`. Keep it if current; if stale, pass `--replace`
+with a new draft. Baton archives the previous text and refreshes the pending
+prompt in the same operation as any plan release.
+
+Repositories with a commit wrapper can export `batonCommitCommand(message, paths)`
+from `dotmd.config.mjs` and return an argv array such as
+`['just', 'commit', message, ...paths]`. Baton quotes the printed command and
+excludes session prompts from `paths`.
 
 Saved prompts are local session state. Consume them with `runlist use`; inspect
 without consuming via `runlist prompts show`. Consuming a baton prompt also claims

package/bin/dotmd.mjs

@@ -676,10 +676,11 @@ Options:
   --json                 Output as JSON ({ owned, prompts, errors, previousSelf,
                          fleet, recentRejections, misuseRecap, drift })`,
 
-  briefing: `runlist briefing — compact summary for session start
+  briefing: `runlist briefing — comprehensive live-work summary
 
-Shows plan statuses with next steps, doc/research counts, and health
-in 5-10 lines. Designed for LLM context injection.
+Shows every live plan with its next step, plus doc/research counts and health.
+Output grows with the corpus; use \`runlist plans\` for compact orientation or
+\`runlist agent-context\` for structured agent context.
 
 Options:
   --json                 Output as JSON`,
@@ -1270,13 +1271,21 @@ Options:
   --note "why"           Append the reason to ## Version History (plan mode only)
   --message / --body     Inline body (one-liners; prefer @path or stdin)
   --force                Recover another session's plan (explicit path required)
+  --replace              Replace exactly one pending handoff; archive its prior text
   --json                 Structured repository/session/generated file result
   --dry-run, -n          Preview without writing
 
+Repo-specific commit hint (dotmd.config.mjs):
+  export function batonCommitCommand(message, paths) {
+    return ['just', 'commit', message, ...paths];
+  }
+The function returns argv; baton shell-quotes each argument before printing.
+
 Examples:
   runlist baton @/tmp/draft.md
   runlist baton checkout-fixes @/tmp/draft.md
   runlist baton docs/plans/auth.md @/tmp/draft.md
+  runlist baton docs/plans/auth.md @/tmp/new-draft.md --replace
   runlist baton --status paused --note "blocked on review" @/tmp/d.md
   cat /tmp/draft.md | runlist baton
 
@@ -1295,11 +1304,13 @@ cooperating transaction:
   grant ownership. A live pickup-hook delivery lease blocks release and force
   takeover; hooks are at-least-once and deduplicate the stable operationId.
 
-Slug mode (no plan involved) saves resume-<slug> and touches nothing else: no
-status change, no commit. A bare word that names a plan is treated as that plan.
+Slug mode (no plan involved) saves resume-<slug> without a status change or
+commit. A bare word that names a plan is treated as that plan.
 
 Baton saves nothing while a handoff for the same work is pending (resume-<name>,
-or a pending prompt linked to the plan): consume or archive it, then re-run.
+or a pending prompt linked to the plan): inspect it with \`runlist prompts show\`.
+Keep it if current; use \`--replace\` with a new draft if stale. Replacement
+preserves the prior text under archived/ and refuses multiple matches.
 With no @file, \`-\` or --message, baton reads stdin only when something is piped
 in; an open pipe that sends nothing is given up on after a moment.`,
 
@@ -1983,7 +1994,15 @@ async function main() {
   if (command === 'glossary') { const { runGlossary } = await import('../src/glossary.mjs'); runGlossary(restArgs, config); return; }
   if (command === 'model') { const { runModel } = await import('../src/model.mjs'); await runModel(restArgs, config); return; }
   if (command === 'show') { const { runShow } = await import('../src/show.mjs'); runShow(restArgs, config); return; }
-  if (command === 'decisions') { const { runDecisions } = await import('../src/decisions.mjs'); runDecisions(restArgs, config); return; }
+  if (command === 'decisions') {
+    const { runDecisions } = await import('../src/decisions.mjs');
+    const result = runDecisions(restArgs, config);
+    if (result?.defects?.length) {
+      const first = result.defects[0];
+      _exitFailureMessage = `${result.defects.length} decision defect(s); first: ${first.doc}:${first.line} ${first.message}`;
+    }
+    return;
+  }
   if (command === 'export') { const { runExport } = await import('../src/export.mjs'); runExport(restArgs, config, { dryRun, root: rootArg, type: typeArg }); return; }
 
   // Lifecycle commands
@@ -2175,7 +2194,10 @@ async function main() {
         writeCheckPreviewNote();
         process.stdout.write('\n' + renderCheck(freshIndex, config, { errorsOnly, noCollapse, verbose }));
       }
-      if (freshIndex.errors.length > 0) process.exitCode = 1;
+      if (freshIndex.errors.length > 0) {
+        process.exitCode = 1;
+        _exitFailureMessage = checkFailureSummary(freshIndex.errors);
+      }
       return;
     }
 
@@ -2185,13 +2207,19 @@ async function main() {
 
     if (args.includes('--json')) {
       process.stdout.write(JSON.stringify(checkJson(index), null, 2) + '\n');
-      if (index.errors.length > 0) process.exitCode = 1;
+      if (index.errors.length > 0) {
+        process.exitCode = 1;
+        _exitFailureMessage = checkFailureSummary(index.errors);
+      }
       return;
     }
 
     writeCheckPreviewNote();
     process.stdout.write(renderCheck(index, config, { errorsOnly, noCollapse, verbose }));
-    if (index.errors.length > 0) process.exitCode = 1;
+    if (index.errors.length > 0) {
+      process.exitCode = 1;
+      _exitFailureMessage = checkFailureSummary(index.errors);
+    }
     return;
   }
 
@@ -2416,9 +2444,15 @@ async function main() {
 let _resolvedConfig = null;
 let _resolvedCommand = null;
 let _suppressObservability = false;
+let _exitFailureMessage = null;
 const _startMs = Date.now();
 const _invocationArgs = process.argv.slice(2);
 
+function checkFailureSummary(errors) {
+  const first = errors[0];
+  return `${errors.length} check error(s); first: ${first.path ? `${first.path}: ` : ''}${first.message}`;
+}
+
 function _journalExit(err) {
   if (_suppressObservability || _resolvedCommand === 'hud' || _invocationArgs.includes('--dry-run') || _invocationArgs.includes('-n')) return;
   try {
@@ -2433,7 +2467,7 @@ function _journalExit(err) {
   // A command that reports its own failure through the exit code (check with
   // errors, a failed update step) is a failure too.
   const code = Number(process.exitCode ?? 0);
-  const failure = err ?? (code !== 0 ? { name: 'ExitStatus', message: `exited with status ${code}` } : null);
+  const failure = err ?? (code !== 0 ? { name: 'ExitStatus', message: _exitFailureMessage ?? `exited with status ${code}` } : null);
   if (failure) {
     try {
       recordGlobalError({

package/package.json

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

package/src/atomic-mutation.mjs

@@ -1310,6 +1310,10 @@ export function moveFileAtomic(sourcePath, targetPath, render, options) {
     // transaction manifest exists, so a guard conflict can never leave a
     // transaction to recover from.
     for (const guard of guards) {
+      if (guard.absent) {
+        if (existsSync(guard.path)) throw new MutationConflictError(`File appeared while the move mutation set was being prepared: ${path.resolve(guard.path)}`);
+        continue;
+      }
       const snapshot = snapshotFile(guard.path);
       if (guard.expectedContent !== undefined && snapshot.content !== guard.expectedContent) {
         throw new MutationConflictError(`File changed while the move mutation set was being prepared: ${snapshot.path}`);
@@ -1657,6 +1661,10 @@ export function mutateFileSet({ updates = [], creations = [], guards = [] }, opt
     // is created — a guard conflict must leave the tree byte-identical, not even
     // an empty directory behind.
     for (const guard of guards) {
+      if (guard.absent) {
+        if (existsSync(guard.path)) throw new MutationConflictError(`File appeared while the mutation set was being prepared: ${path.resolve(guard.path)}`);
+        continue;
+      }
       const snapshot = snapshotFile(guard.path);
       if (guard.expectedContent !== undefined && snapshot.content !== guard.expectedContent) {
         throw new MutationConflictError(`File changed while the mutation set was being prepared: ${snapshot.path}`);

package/src/baton.mjs

@@ -1,12 +1,13 @@
-import { readFileSync, existsSync, writeFileSync, realpathSync } from 'node:fs';
+import { readFileSync, existsSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
-import { asString, toRepoPath, die, warn, isArchivedPath, resolveRefPath } from './util.mjs';
+import { asString, toRepoPath, die, warn, isArchivedPath, resolveRefPath, nowIso } from './util.mjs';
 import { buildIndex, resolveDocArg } from './index.mjs';
 import { preparePromptDocument, runNew, readBodyInput, readPipedBodyInput } from './new.mjs';
-import { ensurePlanCompletionBeforeRelease, planHasPendingCompletion, runSet } from './lifecycle.mjs';
+import { ensurePlanCompletionBeforeRelease, planHasPendingCompletion, renderLifecycleMutation, runSet } from './lifecycle.mjs';
 import { green, dim } from './color.mjs';
-import { authorizeManagedSource } from './managed-path.mjs';
+import { authorizeManagedDestination, authorizeManagedSource } from './managed-path.mjs';
+import { mutateFileSet } from './atomic-mutation.mjs';
 import { assertPlanMutationAuthorized, authoritativeSessionId, listOwnedPlans, readPlanOwnership } from './pickup.mjs';
 
 // `dotmd baton` is the one-command handoff: save the resume prompt AND release
@@ -56,7 +57,8 @@ function pendingHandoffs(promptPath, planPath, config) {
       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);
+      try { if (linked && realpathSync(linked) === planReal) found.add(doc.path); }
+      catch { /* stale plan link is not evidence this prompt belongs to the plan */ }
     }
   }
   return [...found];
@@ -65,7 +67,36 @@ function pendingHandoffs(promptPath, planPath, config) {
 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 (\`runlist use ${slug}\`) or archive it (\`runlist prompts archive ${pending[0]}\`), then run baton again.`);
+  die(`Nothing saved: a handoff for this is already pending:\n${lines}\nInspect it with \`runlist prompts show ${slug}\`. If it is current, keep it and do not hand off again. If it is stale, re-run baton with \`--replace\` to preserve the old handoff under archived/.`);
+}
+
+function archivedCopyPath(promptPath, config) {
+  const dir = path.join(path.dirname(promptPath), config.archiveDir);
+  const ext = path.extname(promptPath);
+  const stem = path.basename(promptPath, ext);
+  let candidate = path.join(dir, `${stem}${ext}`);
+  for (let n = 2; existsSync(candidate); n++) candidate = path.join(dir, `${stem}-${n}${ext}`);
+  return authorizeManagedDestination(candidate, config, { kind: 'Baton replacement archive' }).path;
+}
+
+function shellQuote(value) {
+  const raw = String(value);
+  return /^[A-Za-z0-9_./:@+-]+$/.test(raw) ? raw : `"${raw.replace(/["\\$`]/g, '\\$&')}"`;
+}
+
+function commitCommand(config, message, paths) {
+  const fallback = ['git', 'commit', '-m', message, '--', ...paths];
+  let argv = fallback;
+  if (typeof config.hooks.batonCommitCommand === 'function') {
+    try {
+      const custom = config.hooks.batonCommitCommand(message, [...paths]);
+      if (!Array.isArray(custom) || custom.length === 0 || !custom.every(part => typeof part === 'string' && part.length > 0)) {
+        throw new Error('return a nonempty string argv array');
+      }
+      argv = custom;
+    } catch (err) { warn(`batonCommitCommand failed (${err.message}); printing the default git command.`); }
+  }
+  return argv.map(shellQuote).join(' ');
 }
 
 // Is this positional a filesystem reference (must resolve, typos die) or a
@@ -83,6 +114,7 @@ export async function runBaton(argv, config, opts = {}) {
   let note = null;
   let bodyFlag = null;
   let force = false;
+  let replace = false;
   const positionals = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -90,6 +122,7 @@ export async function runBaton(argv, config, opts = {}) {
     if (a === '--note' && argv[i + 1]) { note = argv[++i]; continue; }
     if ((a === '--body' || a === '--message') && argv[i + 1]) { bodyFlag = argv[++i]; continue; }
     if (a === '--force') { force = true; continue; }
+    if (a === '--replace') { replace = true; continue; }
     if (a === '--json') continue;
     if (!a.startsWith('-') || a === '-' || a.startsWith('@')) { positionals.push(a); continue; }
     die(`Unknown flag for \`runlist baton\`: ${a}`);
@@ -152,16 +185,45 @@ 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 = () => {
+  let replacement = null;
+  const resolvePending = () => {
     const target = preparePromptDocument(slugBase, body, config, { dryRun: true });
     const pending = pendingHandoffs(target.filePath, planPath, config);
-    if (pending.length) refusePendingHandoff(pending);
+    if (!replace) {
+      if (pending.length) refusePendingHandoff(pending);
+      return;
+    }
+    if (pending.length !== 1) {
+      const detail = pending.length ? `Found ${pending.length}:\n${pending.map(p => `  ${p}`).join('\n')}` : 'No pending handoff matches this work.';
+      die(`Nothing replaced: --replace requires exactly one pending handoff. ${detail}`);
+    }
+    const oldRepoPath = pending[0];
+    const oldPath = authorizeManagedSource(path.resolve(config.repoRoot, oldRepoPath), config, { kind: 'Baton replacement source' }).path;
+    const oldRaw = readFileSync(oldPath, 'utf8');
+    const { frontmatter, body: oldBody } = extractFrontmatter(oldRaw);
+    const fm = parseSimpleFrontmatter(frontmatter);
+    if (asString(fm.type) !== 'prompt' || asString(fm.status) !== 'pending') {
+      die(`Nothing replaced: ${oldRepoPath} is not a pending prompt.`);
+    }
+    const priorPlanRef = asString(fm.plan);
+    const priorPlanPath = priorPlanRef ? resolveRefPath(priorPlanRef, path.dirname(oldPath), config.repoRoot) : null;
+    if (!planPath && priorPlanRef) {
+      die(`Nothing replaced: ${oldRepoPath} links a plan (${priorPlanRef}). Use \`runlist baton <plan-file> @<draft-file> --replace\` so the plan link and release stay together.`);
+    }
+    replacement = {
+      oldPath, oldRepoPath, oldRaw,
+      archivedPath: archivedCopyPath(oldPath, config),
+      alreadyCurrent: oldBody.trim() === body.trim()
+        && (!planPath || (priorPlanPath && path.resolve(priorPlanPath) === path.resolve(planPath))),
+      canonicalPath: target.filePath,
+    };
   };
 
   let repoPath = null;
   let oldStatus = null;
   let ownershipPath = null;
   let planGuard = null;
+  let wouldReleaseClaim = false;
   if (planPath) {
     planPath = authorizeManagedSource(planPath, config, { kind: 'Baton plan source' }).path;
     repoPath = toRepoPath(planPath, config.repoRoot);
@@ -187,6 +249,7 @@ export async function runBaton(argv, config, opts = {}) {
     const sessionId = authoritativeSessionId();
     const ownership = assertPlanMutationAuthorized(repoPath, config, { sessionId, force });
     const ownedHere = ownership?.state === 'owned' && ownership.sessionId === sessionId;
+    wouldReleaseClaim = ownership?.state === 'owned';
     // Baton's release only means something when there is a claim to release. A
     // plan that is neither in-session nor owned here carries a status someone
     // chose on purpose (`awaiting`, `blocked`, a repo's own `awaiting-testing`),
@@ -208,16 +271,36 @@ export async function runBaton(argv, config, opts = {}) {
       if (note) warn('--note ignored — the plan\'s status is unchanged, so there is no transition to record.');
     }
     // Before the plan-completion step: a refusal must leave nothing changed.
-    refuseIfPending();
+    resolvePending();
+    // A status transition may file the plan at a new path. Refreshing the
+    // prompt inside that transaction keeps its plan link valid even when its
+    // body text happened to be identical to the previous handoff.
+    if (replacement && status !== oldStatus) replacement.alreadyCurrent = false;
     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();
+    resolvePending();
     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).`);
   }
 
+  const preparedReplacement = prepared => {
+    if (!replacement || replacement.alreadyCurrent) return { updates: [], creations: [], guards: [] };
+    let archivedContent = renderLifecycleMutation(replacement.oldRaw,
+      { status: 'archived', updated: nowIso() }, () => 'Archived.');
+    if (repoPath) archivedContent = archivedContent.replace(/^plan:[ \t]*\S.*$/m, `plan: ${repoPath}`);
+    return {
+      updates: [{ path: replacement.oldPath, expectedContent: replacement.oldRaw, content: prepared.content }],
+      creations: [{ path: replacement.archivedPath, content: archivedContent }],
+      guards: path.resolve(replacement.canonicalPath) === path.resolve(replacement.oldPath)
+        ? [] : [{ path: replacement.canonicalPath, absent: true }],
+    };
+  };
+  if (dryRun && !json && replacement && !replacement.alreadyCurrent) {
+    process.stdout.write(`${dim('[dry-run]')} Would preserve old handoff: ${replacement.oldRepoPath} → ${toRepoPath(replacement.archivedPath, config.repoRoot)}\n`);
+  }
+
   // Plan mode publishes the already-stamped prompt, status/history update, and
   // ownership release in one transaction. Slug mode has no plan transaction.
   let createdSlug = null;
@@ -230,29 +313,39 @@ export async function runBaton(argv, config, opts = {}) {
   if (json) process.stdout.write = chunk => { muted.push(String(chunk)); return true; };
   try {
   if (!planPath) {
-    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;
+    const promptName = replacement ? path.basename(replacement.oldPath, '.md') : slugBase;
+    const prepared = preparePromptDocument(promptName, body, config, { dryRun });
+    if (replacement) {
+      const mutation = preparedReplacement(prepared);
+      if (!dryRun && !replacement.alreadyCurrent) mutateFileSet(mutation, { repoRoot: config.repoRoot, testHooks: opts.testHooks });
+      newResult = { sessionFiles: [replacement.oldRepoPath, ...(replacement.alreadyCurrent ? [] : [toRepoPath(replacement.archivedPath, config.repoRoot)])] };
+    } else {
+      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;
+    createdSlug = promptName;
+    promptRepoPath = replacement?.oldRepoPath ?? prepared.repoPath;
   } else {
-    const prepared = preparePromptDocument(slugBase, body, config, { plan: repoPath, dryRun });
+    const promptName = replacement ? path.basename(replacement.oldPath, '.md') : slugBase;
+    const prepared = preparePromptDocument(promptName, body, config, { plan: repoPath, dryRun });
+    const mutation = preparedReplacement(prepared);
     const setArgs = [status, planPath];
     if (force) setArgs.push('--force');
     if (note && !planGuard) setArgs.push('--note', note);
     try {
-      if (dryRun) process.stdout.write(`${dim('[dry-run]')} Would create: ${prepared.repoPath}\n`);
+      if (dryRun) process.stdout.write(`${dim('[dry-run]')} Would ${replacement ? (replacement.alreadyCurrent ? 'keep' : 'replace') : 'create'}: ${replacement?.oldRepoPath ?? prepared.repoPath}\n`);
       archiveResult = await runSet(setArgs, config, {
         dryRun,
         viaBaton: true,
         testHooks: opts.testHooks,
-        creations: dryRun ? [] : [{ path: prepared.filePath, content: prepared.content }],
-        guards: planGuard && !dryRun ? [planGuard] : [],
+        additionalUpdates: dryRun ? [] : mutation.updates,
+        creations: dryRun ? [] : replacement ? mutation.creations : [{ path: prepared.filePath, content: prepared.content }],
+        guards: dryRun ? [] : [...mutation.guards, ...(planGuard ? [planGuard] : [])],
         deferIndex: true,
       });
     } catch (err) {
@@ -260,9 +353,9 @@ export async function runBaton(argv, config, opts = {}) {
       throw err;
     }
     createdSlug = prepared.slug;
-    promptRepoPath = prepared.repoPath;
+    promptRepoPath = replacement?.oldRepoPath ?? prepared.repoPath;
     statusChanged = oldStatus !== status;
-    if (!dryRun) {
+    if (!dryRun && !replacement) {
       try { config.hooks.onNew?.({ path: prepared.repoPath, status: 'pending', title: prepared.slug, type: 'prompt' }); }
       catch (err) { warn(`Hook 'onNew' threw: ${err.message}`); }
     }
@@ -271,24 +364,12 @@ export async function runBaton(argv, config, opts = {}) {
     if (json) process.stdout.write = originalStdoutWrite;
   }
 
-  // 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
-  // transaction as that move, so its `plan:` link necessarily holds the
-  // pre-move path and is stale the instant it lands. The move's own reference
-  // rewrite does not cover it: `plan` is deliberately not a `referenceFields`
-  // entry, so nothing validates or repoints it. Retarget it here.
-  if (!dryRun && promptRepoPath && archiveResult?.newRepoPath && archiveResult.newRepoPath !== repoPath) {
-    const promptPath = path.join(config.repoRoot, promptRepoPath);
-    try {
-      const { frontmatter, body } = extractFrontmatter(readFileSync(promptPath, 'utf8'));
-      // Rewritten in place rather than through replaceFrontmatterField, which
-      // always emits a folded block scalar — right for prose fields, wrong for
-      // a path every other prompt carries on one line. Baton wrote this line
-      // itself moments ago, so the single-line form is guaranteed.
-      const rewritten = frontmatter.replace(/^plan:[ \t]*\S.*$/m, `plan: ${archiveResult.newRepoPath}`);
-      if (rewritten !== frontmatter) writeFileSync(promptPath, `---\n${rewritten}\n---\n${body}`, 'utf8');
-    }
-    catch (err) { warn(`Saved the prompt, but could not repoint its plan link to ${archiveResult.newRepoPath}: ${err.message}`); }
+  if (!dryRun && replacement && !replacement.alreadyCurrent) {
+    const archivedRepoPath = toRepoPath(replacement.archivedPath, config.repoRoot);
+    try { config.hooks.onArchive?.({ path: archivedRepoPath, oldStatus: 'pending' }, { oldPath: replacement.oldRepoPath, newPath: archivedRepoPath }); }
+    catch (err) { warn(`Hook 'onArchive' threw: ${err.message}`); }
+    try { config.hooks.onNew?.({ path: replacement.oldRepoPath, status: 'pending', title: createdSlug, type: 'prompt' }); }
+    catch (err) { warn(`Hook 'onNew' threw: ${err.message}`); }
   }
 
   const normalizeRepoPath = candidate => {
@@ -297,13 +378,14 @@ export async function runBaton(argv, config, opts = {}) {
   };
   const touched = (archiveResult?.touched ?? (planPath && statusChanged ? [repoPath] : [])).map(normalizeRepoPath);
   const ownershipRepoPath = normalizeRepoPath(ownershipPath);
-  const repositoryFiles = [...new Set(touched.filter(candidate => candidate && candidate !== ownershipRepoPath && candidate !== promptRepoPath && candidate !== normalizeRepoPath(config.indexPath)))];
-  const sessionFiles = [...new Set([...(newResult?.sessionFiles ?? []), promptRepoPath, ownershipRepoPath].filter(Boolean))];
+  const archivedPromptRepoPath = replacement && !replacement.alreadyCurrent ? toRepoPath(replacement.archivedPath, config.repoRoot) : null;
+  const repositoryFiles = [...new Set(touched.filter(candidate => candidate && candidate !== ownershipRepoPath && candidate !== promptRepoPath && candidate !== archivedPromptRepoPath && candidate !== normalizeRepoPath(config.indexPath)))];
+  const sessionFiles = [...new Set([...(newResult?.sessionFiles ?? []), promptRepoPath, archivedPromptRepoPath, ownershipRepoPath].filter(Boolean))];
   const deferredGeneratedFiles = [...new Set(newResult?.deferredGeneratedFiles ?? (config.indexPath ? [normalizeRepoPath(config.indexPath)] : []))];
   const operationResult = {
     operation: 'baton',
     dryRun: Boolean(dryRun),
-    disposition: dryRun ? 'would-change' : 'applied',
+    disposition: replacement?.alreadyCurrent && !statusChanged && !wouldReleaseClaim ? 'already-current' : dryRun ? 'would-change' : 'applied',
     wouldChange: Boolean(dryRun),
     mode: planPath ? 'plan' : 'slug',
     status: planPath ? { from: oldStatus, to: status, changed: statusChanged } : null,
@@ -313,6 +395,14 @@ export async function runBaton(argv, config, opts = {}) {
     deferredGeneratedFiles,
     prompt: promptRepoPath,
     plan: archiveResult?.newRepoPath ?? repoPath,
+    planMovement: planPath ? { from: repoPath, to: archiveResult?.newRepoPath ?? repoPath } : null,
+    replacement: replacement ? {
+      previousPrompt: replacement.oldRepoPath,
+      archivedPrompt: archivedPromptRepoPath,
+      pendingPrompt: promptRepoPath,
+      alreadyCurrent: replacement.alreadyCurrent,
+    } : null,
+    claimRelease: planPath ? { wouldRelease: wouldReleaseClaim, released: !dryRun && wouldReleaseClaim } : null,
   };
 
   const prefix = dryRun ? dim('[dry-run] ') : '';
@@ -320,13 +410,14 @@ export async function runBaton(argv, config, opts = {}) {
     process.stdout.write(JSON.stringify(operationResult, null, 2) + '\n');
     return operationResult;
   }
-  process.stderr.write(`\n${prefix}${green('✓ Baton passed')}: ${createdSlug} (the next session's hud surfaces it — nothing to paste into chat)\n`);
+  const verdict = replacement?.alreadyCurrent ? '✓ Handoff kept' : replacement ? '✓ Baton replaced' : '✓ Baton passed';
+  process.stderr.write(`\n${prefix}${green(verdict)}: ${createdSlug} (the next session's hud surfaces it — nothing to paste into chat)\n`);
+  if (archivedPromptRepoPath) process.stderr.write(dim(`${prefix}Previous handoff preserved: ${archivedPromptRepoPath}\n`));
   if (planGuard) {
     process.stderr.write(dim(`${repoPath} left at \`${oldStatus}\` — it was not in-session, so there was no claim to release.\n`));
     process.stderr.write(dim(`Meant to change it? runlist set <status> ${repoPath}\n`));
   }
   if (statusChanged) {
-    const pathspec = operationResult.repositoryFiles.join(' ');
     let gitignored = false;
     try {
       const { isGitIgnored } = await import('./git.mjs');
@@ -336,7 +427,7 @@ export async function runBaton(argv, config, opts = {}) {
       process.stderr.write(dim(`${repoPath} is gitignored — no commit needed.\n`));
     } else {
       process.stderr.write(`${prefix}Commit the repository files (session files stay OUT of the pathspec):\n`);
-      process.stderr.write(`${prefix}  git commit -m "baton: ${path.basename(planPath, '.md')} ${oldStatus} → ${status}" -- ${pathspec}\n`);
+      process.stderr.write(`${prefix}  ${commitCommand(config, `baton: ${path.basename(planPath, '.md')} ${oldStatus} → ${status}`, operationResult.repositoryFiles)}\n`);
     }
   }
   if (operationResult.deferredGeneratedFiles.length) process.stderr.write(dim(`Generated index deferred: ${operationResult.deferredGeneratedFiles.join(', ')}\n`));

package/src/commands.mjs

@@ -123,7 +123,7 @@ const definitions = [
   ], { 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'), 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('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('--replace'), flag('--json')] })]),
   command('runlist', mutates('managed hubs/children and managed scaffold destinations'), 'workflow', [
     form('<hub>', { args: positionals(1, 1), options: [flag('--json')] }),
     form('next <hub>', { subcommands: ['next'], args: positionals(1, 1), options: [flag('--json'), flag('--full'), flag('--no-index'), flag('--show-files')] }),

package/src/decisions.mjs

@@ -689,7 +689,7 @@ export function runDecisions(args, config) {
       process.stdout.write(`${items.length} decision items in ${docs.length} documents; ${defects.length} defects.\n`);
     }
     if (defects.length) process.exitCode = 1;
-    return;
+    return { defects };
   }
 
   let docFilter = null;

package/src/lifecycle.mjs

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter, normalizeEol } from './frontmatter.mjs';
-import { asString, toRepoPath, die, warn, resolveDocPath, escapeRegex, nowIso, suggestCandidates, emitFilesFooter, isArchivedPath, currentSessionId } from './util.mjs';
+import { asString, toRepoPath, die, warn, resolveDocPath, resolveRefPath, escapeRegex, nowIso, suggestCandidates, emitFilesFooter, isArchivedPath, currentSessionId } from './util.mjs';
 import { readJournalEntries } from './journal.mjs';
 import { captureGitIndexGeneration, getGitLastModifiedBatch, getGitLastSubstantiveModifiedBatch, isTracked } from './git.mjs';
 import { buildIndex, collectDocFiles, resolveDocArg } from './index.mjs';
@@ -78,6 +78,22 @@ function commitLifecycleMutation(filePath, targetPath, config, updates, historyF
     };
   };
   if (targetPath) {
+    // A companion prompt created or refreshed by baton links this plan before
+    // its status transition decides whether to file it elsewhere. Stamp the
+    // destination into that companion before publishing any transaction path.
+    const newRepoPath = toRepoPath(targetPath, config.repoRoot);
+    const retargetPrompt = item => {
+      if (typeof item.content !== 'string') return item;
+      const { frontmatter, body } = extractFrontmatter(item.content);
+      if (!frontmatter) return item;
+      const fm = parseSimpleFrontmatter(frontmatter);
+      const linked = asString(fm.plan);
+      const resolved = linked ? resolveRefPath(linked, path.dirname(item.path), config.repoRoot) : null;
+      if (asString(fm.type) !== 'prompt' || !resolved || path.resolve(resolved) !== path.resolve(filePath)) return item;
+      const rewritten = frontmatter.replace(/^plan:[ \t]*\S.*$/m, `plan: ${newRepoPath}`);
+      return { ...item, content: `---\n${rewritten}\n---\n${body}` };
+    };
+    const creations = (options.creations ?? []).map(retargetPrompt);
     let result;
     const tracked = isTracked(filePath, config.repoRoot);
     const gitIndex = tracked ? captureGitIndexGeneration(config.repoRoot) : null;
@@ -89,8 +105,8 @@ function commitLifecycleMutation(filePath, targetPath, config, updates, historyF
     const identities = createReferenceIdentitySet([filePath, ...allFiles]);
     const referenceFields = configuredReferenceFields(config);
     const additionalUpdates = options.skipInboundRefs
-      ? (options.additionalUpdates ?? [])
-      : (options.additionalUpdates ?? []).map(item => ({
+      ? (options.additionalUpdates ?? []).map(retargetPrompt)
+      : (options.additionalUpdates ?? []).map(item => retargetPrompt({
           ...item,
           content: item.content === undefined ? undefined : rewriteDocumentReferences(item.content, {
             sourcePath: item.path, repoRoot: config.repoRoot, identities, oldPath: filePath, newPath: targetPath, referenceFields,
@@ -108,7 +124,7 @@ function commitLifecycleMutation(filePath, targetPath, config, updates, historyF
           sourcePath: docFile, repoRoot: config.repoRoot, identities, oldPath: filePath, newPath: targetPath, referenceFields,
         }),
       })), ...additionalUpdates],
-      creations: options.creations ?? [],
+      creations,
       guards: options.guards ?? [],
       gitMove: tracked,
       gitIndex,
@@ -506,7 +522,7 @@ export async function runStatus(argv, config, opts = {}) {
       process.stdout.write(`${prefix} Would append Version History: - **${today}** Status: ${oldStatus ?? 'unknown'} → ${newStatus} — ${note}\n`);
     }
     process.stdout.write(`${prefix} ${toRepoPath(finalPath, config.repoRoot)}: ${oldStatus ?? 'unknown'} → ${newStatus}\n`);
-    return;
+    return { dryRun: true, oldRepoPath: toRepoPath(filePath, config.repoRoot), newRepoPath: toRepoPath(finalPath, config.repoRoot), touched: [] };
   }
 
   const mutationResult = commitLifecycleMutation(filePath, targetPath, config, { status: newStatus, updated: today }, currentOld => {
@@ -516,6 +532,7 @@ export async function runStatus(argv, config, opts = {}) {
     createSection: Boolean(note),
     additionalUpdates: opts.additionalUpdates,
     creations: opts.creations,
+    guards: opts.guards,
     testHooks: opts.testHooks,
   });
 
@@ -845,7 +862,7 @@ export function runArchive(argv, config, opts = {}) {
     if (config.hooks?.onArchive) {
       out.write(`${prefix} Would fire hook: onArchive\n`);
     }
-    return;
+    return { dryRun: true, oldRepoPath, newRepoPath, touched: [] };
   }
 
   const mutationResult = commitLifecycleMutation(filePath, targetPath, config, { status: targetStatus, updated: today },
@@ -1008,6 +1025,7 @@ export async function runSet(argv, config, opts = {}) {
       dryRun, note, archiveStatus: newStatus, force, testHooks: opts.testHooks, deferIndex: opts.deferIndex,
       additionalUpdates: opts.additionalUpdates,
       creations: opts.creations,
+      guards: opts.guards,
     });
   }
 
@@ -1059,8 +1077,9 @@ export async function runSet(argv, config, opts = {}) {
     dryRun,
     suppressDeprecation: true,
     note,
-    additionalUpdates: releaseUpdate ? [releaseUpdate] : [],
+    additionalUpdates: [...(opts.additionalUpdates ?? []), ...(releaseUpdate ? [releaseUpdate] : [])],
     creations: opts.creations,
+    guards: opts.guards,
     testHooks: opts.testHooks,
     deferIndex: opts.deferIndex,
   });