dotmd-cli 0.68.0 → 0.70.0

package/src/prompts.mjs

@@ -1,12 +1,20 @@
-import { readFileSync, statSync } from 'node:fs';
+import { readFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { asString, toRepoPath, die, resolveDocPath, isArchivedPath } from './util.mjs';
-import { buildIndex } from './index.mjs';
+import { buildIndex, resolveDocArg } from './index.mjs';
 import { runQuery } from './query.mjs';
-import { runArchive, runStatus } from './lifecycle.mjs';
+import { completePlanClaim, regenIndex, renderLifecycleMutation, runArchive, runStatus } from './lifecycle.mjs';
 import { runNew } from './new.mjs';
 import { green, dim } from './color.mjs';
+import { authorizeManagedSource } from './managed-path.mjs';
+import {
+  authoritativeSessionId,
+  classifyPlanPickup,
+  preparePlanClaim,
+  readPlanOwnership,
+} from './pickup.mjs';
+import { actionablePromptStatuses, comparePromptDocs } from './status-metadata.mjs';
 
 // `resume` is an alias for `use` — agents reach for "resume" when continuing a
 // session; `use` reads as internal mechanics. Both names stay valid; the
@@ -125,10 +133,10 @@ function slugToPlanPath(s, config) {
 // Resolve a markdown body link relative to the prompt's location so e.g.
 // `../plans/foo.md` from docs/prompts/x.md → docs/plans/foo.md.
 function resolveBodyLink(link, promptRepoPath) {
-  const cleaned = link.replace(/#.*$/, '');
+  const cleaned = link.replace(/#.*$/, '').replaceAll('\\', '/');
   if (cleaned.startsWith('/')) return cleaned.replace(/^\/+/, '');
-  const promptDir = path.dirname(promptRepoPath);
-  return path.normalize(path.join(promptDir, cleaned));
+  const promptDir = path.posix.dirname(promptRepoPath.replaceAll('\\', '/'));
+  return path.posix.normalize(path.posix.join(promptDir, cleaned));
 }
 
 function renderPromptsVerbose(index, config, { hasStatusFlag, includeArchived }) {
@@ -158,36 +166,27 @@ function renderPromptsVerbose(index, config, { hasStatusFlag, includeArchived })
 }
 
 export function pendingPromptsOldestFirst(config) {
-  const index = buildIndex(config);
+  const index = buildIndex(config, { fast: true, invokeHooks: false });
+  const actionable = actionablePromptStatuses(config);
   const prompts = index.docs.filter(d =>
     d.type === 'prompt'
-    && d.status === 'pending'
+    && actionable.has(d.status)
     && !isArchivedPath(d.path, config),
   );
 
   return prompts
-    .map(d => {
-      const abs = resolveDocPath(d.path, config);
-      let mtime = 0;
-      try { mtime = abs ? statSync(abs).mtimeMs : 0; } catch { mtime = 0; }
-      return { doc: d, abs, created: d.created ?? '', mtime };
-    })
-    .sort((a, b) => {
-      if (a.created && b.created && a.created !== b.created) return a.created.localeCompare(b.created);
-      if (a.created && !b.created) return -1;
-      if (!a.created && b.created) return 1;
-      return a.mtime - b.mtime;
-    });
+    .sort(comparePromptDocs)
+    .map(d => ({ doc: d, abs: resolveDocPath(d.path, config), created: d.created ?? '' }));
 }
 
-function runPromptsNext(argv, config, opts = {}) {
+async function runPromptsNext(argv, config, opts = {}) {
   const queue = pendingPromptsOldestFirst(config);
   if (queue.length === 0) {
     die('No pending prompts.');
   }
   const head = queue[0];
   if (!head.abs) die(`Could not resolve path: ${head.doc.path}`);
-  consumePrompt(head.abs, config, opts);
+  return consumePrompt(head.abs, config, opts);
 }
 
 // Resolve user input to a prompt path. Tries (in order): exact path,
@@ -204,7 +203,7 @@ export function resolvePromptInput(input, config, options = {}) {
     if (withExt) return withExt;
   }
 
-  const index = buildIndex(config);
+  const index = buildIndex(config, { fast: true, invokeHooks: false });
   const prompts = index.docs.filter(d => d.type === 'prompt');
   if (prompts.length === 0) {
     if (dieOnMiss) die(`No prompts in the index.`);
@@ -231,17 +230,18 @@ export function resolvePromptInput(input, config, options = {}) {
   return null;
 }
 
-function runPromptsUse(argv, config, opts = {}) {
+async function runPromptsUse(argv, config, opts = {}) {
   const input = argv.find(a => !a.startsWith('-'));
   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 filePath = resolvePromptInput(input, config);
-  consumePrompt(filePath, config, { ...opts, noIndex, showFiles });
+  return consumePrompt(filePath, config, { ...opts, noIndex, showFiles });
 }
 
-export function consumePrompt(filePath, config, opts) {
+export async function consumePrompt(filePath, config, opts) {
   const { dryRun, noIndex, showFiles } = opts;
+  filePath = authorizeManagedSource(filePath, config, { kind: 'Prompt consumption source' }).path;
   const raw = readFileSync(filePath, 'utf8');
   const { frontmatter, body } = extractFrontmatter(raw);
   const parsed = parseSimpleFrontmatter(frontmatter);
@@ -256,6 +256,10 @@ export function consumePrompt(filePath, config, opts) {
     die(`Already consumed: ${repoPath}`);
   }
 
+  const planRef = asString(parsed.plan);
+  let linkedClaim = null;
+  if (planRef) linkedClaim = prepareLinkedPromptClaim(planRef, config);
+
   if (dryRun) {
     const prefix = dim('[dry-run]');
     process.stderr.write(`${prefix} Would emit body and archive: ${repoPath} (${status ?? 'unknown'} → archived)\n`);
@@ -274,15 +278,117 @@ export function consumePrompt(filePath, config, opts) {
   // hook crash, anything), the body must not have already gone to stdout —
   // otherwise `claude "$(dotmd prompts next)"` consumes the prompt without it
   // ever being archived, and the next session sees the same prompt as pending.
-  // Body is already in memory from extractFrontmatter, so the source file
-  // can move out from under us safely.
-  const archiveResult = runArchive([filePath], config, { noIndex, showFiles, out: process.stderr });
-
-  process.stdout.write(body);
-  if (!body.endsWith('\n')) process.stdout.write('\n');
+  const archiveResult = runArchive([filePath], config, {
+    noIndex,
+    showFiles,
+    out: process.stderr,
+    testHooks: opts.testHooks,
+    deferIndex: Boolean(linkedClaim),
+    additionalUpdates: linkedClaim?.prepared?.updates,
+    creations: linkedClaim?.prepared?.creations,
+  });
+  const consumedBody = archiveResult?.consumedBody ?? body;
 
   const consumedPath = archiveResult?.newRepoPath ?? repoPath;
+  // Consume output is at-most-once: archive/claim commits before stdout. A
+  // downstream failure cannot roll the transaction back or make it consumable
+  // again; the archived path remains available through `prompts show`.
+  await writeConsumedBody(consumedBody, consumedPath, opts.writeBody, linkedClaim?.repoPath);
+  let completion = { indexRegenerated: false, ownershipChanged: false, hook: 'none', pending: false };
+  if (linkedClaim) {
+    try {
+      completion = completePlanClaim(linkedClaim.repoPath, config, opts);
+      if (!noIndex && config.indexPath && !completion.indexRegenerated) {
+        regenIndex(config, { throwOnError: true, testHooks: opts.testHooks });
+        completion.indexRegenerated = true;
+      }
+    } catch (err) {
+      throw new Error(`Prompt consumed and body delivered; linked claim completion remains pending for ${linkedClaim.repoPath}: ${err.message}`);
+    }
+    process.stderr.write(`${green('→ Claimed')}: ${linkedClaim.repoPath} (in-session)\n`);
+  }
   process.stderr.write(`${green('✓ Consumed')}: ${consumedPath}\n`);
+  const ownershipRecordPath = linkedClaim?.prepared?.recordPath ?? (linkedClaim ? readPlanOwnership(linkedClaim.repoPath, config)?.recordPath : null);
+  const ownershipPath = ownershipRecordPath ? toRepoPath(ownershipRecordPath, config.repoRoot) : null;
+  const normalize = candidate => path.isAbsolute(candidate) ? toRepoPath(candidate, config.repoRoot) : candidate.split(path.sep).join('/');
+  const resultPaths = [
+    ...(linkedClaim?.planChanged ? [linkedClaim.repoPath] : []),
+    ...(archiveResult?.referencePaths ?? []),
+  ].filter(Boolean).map(normalize);
+  const ownershipResultPaths = resultPaths.filter(candidate => candidate.startsWith('.dotmd/ownership/'));
+  const repositoryFiles = [...new Set(resultPaths.filter(candidate => !candidate.startsWith('.dotmd/ownership/')))];
+  const sessionFiles = [...new Set([
+    repoPath,
+    consumedPath,
+    (linkedClaim?.prepared || completion.ownershipChanged) ? ownershipPath : null,
+    ...ownershipResultPaths,
+  ].filter(Boolean).map(normalize))];
+  return {
+    operation: 'consume',
+    status: { from: status ?? null, to: 'archived', changed: true },
+    repositoryFiles,
+    sessionFiles,
+    generatedFiles: config.indexPath && !noIndex && (completion.indexRegenerated || archiveResult?.indexRegenerated) ? [toRepoPath(config.indexPath, config.repoRoot)] : [],
+    deferredGeneratedFiles: config.indexPath && noIndex ? [toRepoPath(config.indexPath, config.repoRoot)] : [],
+    claim: linkedClaim ? { plan: linkedClaim.repoPath, changed: linkedClaim.planChanged, pendingCompletion: completion.pending, hook: completion.hook } : null,
+  };
+}
+
+export async function writeConsumedBody(body, archivedPath, write = null, linkedPlan = null) {
+  const content = body.endsWith('\n') ? body : `${body}\n`;
+  try {
+    if (write) {
+      const accepted = await write(content);
+      if (accepted === false) throw Object.assign(new Error('writer reported unresolved backpressure'), { code: 'BACKPRESSURE' });
+    } else {
+      await new Promise((resolve, reject) => process.stdout.write(content, err => err ? reject(err) : resolve()));
+    }
+  }
+  catch (err) {
+    const completion = linkedPlan ? ` Then complete the linked claim with \`dotmd use ${linkedPlan}\`.` : '';
+    throw new Error(`Prompt was consumed but body output failed (${err.code ?? err.message}). It will not be emitted again; recover it with \`dotmd prompts show ${archivedPath}\`.${completion}`);
+  }
+}
+
+function prepareLinkedPromptClaim(planRef, config) {
+  let planPath = resolveDocPath(planRef, config) ?? resolveDocArg(planRef, config, { dieOnMiss: false });
+  if (!planPath || !existsSync(planPath)) die(`Linked plan is missing; prompt was not consumed: ${planRef}`);
+  planPath = authorizeManagedSource(planPath, config, { kind: 'Prompt linked plan source' }).path;
+  const raw = readFileSync(planPath, 'utf8');
+  let parsed;
+  try { parsed = parseSimpleFrontmatter(extractFrontmatter(raw).frontmatter); }
+  catch { die(`Linked plan is malformed; prompt was not consumed: ${planRef}`); }
+  const repoPath = toRepoPath(planPath, config.repoRoot);
+  const sessionId = authoritativeSessionId();
+  const ownership = readPlanOwnership(repoPath, config);
+  const oldStatus = asString(parsed.status);
+  const disposition = classifyPlanPickup({
+    type: asString(parsed.type),
+    status: oldStatus,
+    validStatuses: config.typeStatuses?.get('plan') ?? config.validStatuses,
+    startableStatuses: config.lifecycle.startableStatuses,
+    terminalStatuses: config.lifecycle.terminalStatuses,
+    archiveStatuses: config.lifecycle.archiveStatuses,
+    physicallyArchived: isArchivedPath(repoPath, config),
+    ownership,
+    sessionId,
+    malformed: false,
+  });
+  if (!disposition.pickupable) die(`Linked plan cannot be claimed (${disposition.kind}); prompt was not consumed: ${repoPath}`);
+  if (disposition.kind === 'resume') return { planPath, repoPath, prepared: null, planChanged: false, disposition: disposition.kind };
+  const now = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+  const rendered = disposition.kind === 'start'
+    ? renderLifecycleMutation(raw, { status: 'in-session', updated: now }, `Started (${oldStatus} → in-session).`, { createSection: true })
+    : null;
+  const prepared = preparePlanClaim({ filePath: planPath, sourceContent: raw, renderedContent: rendered,
+    ownership, sessionId, now, config });
+  return {
+    planPath,
+    repoPath,
+    prepared,
+    planChanged: prepared.updates.some(item => path.resolve(item.path) === path.resolve(planPath)),
+    disposition: disposition.kind,
+  };
 }
 
 // Read-only peek: print the body WITHOUT consuming. The sanctioned triage path

package/src/query.mjs

@@ -85,15 +85,21 @@ export function runQuery(index, argv, config, opts = {}) {
   if (filters.body && !filters.keyword) {
     die('`--body` extends a keyword search into document bodies — pass `--keyword <term>` (or use `dotmd grep <term>`).');
   }
-  const docs = filterDocs(index.docs, filters, config);
+  const docs = filterDocs(index.docs, filters, config, opts.gitMetadataOptions);
+  const summaryPreviewSkipped = filters.summarize && config._execution?.suppressSideEffects;
 
   if (filters.json) {
-    if (filters.summarize) {
+    if (filters.summarize && !summaryPreviewSkipped) {
       for (let i = 0; i < docs.length && i < filters.summarizeLimit; i++) {
         docs[i].aiSummary = getDocSummary(docs[i], config);
       }
     }
-    process.stdout.write(`${JSON.stringify({ filters, count: docs.length, docs }, null, 2)}\n`);
+    process.stdout.write(`${JSON.stringify({
+      filters,
+      count: docs.length,
+      docs,
+      ...(summaryPreviewSkipped ? { summaryPreview: { status: 'skipped-preview', reason: 'side-effect-free preview' } } : {}),
+    }, null, 2)}\n`);
     return;
   }
 
@@ -279,7 +285,7 @@ export function parseQueryArgs(argv) {
   return filters;
 }
 
-export function filterDocs(docs, filters, config) {
+export function filterDocs(docs, filters, config, gitMetadataOptions) {
   let result = [...docs];
 
   if (filters.types?.length) result = result.filter(d => filters.types.includes(d.type));
@@ -320,14 +326,18 @@ export function filterDocs(docs, filters, config) {
   if (filters.updatedSince) result = result.filter(d => d.updated && d.updated >= filters.updatedSince);
 
   if (filters.git) {
-    const gitDates = getGitLastModifiedBatch(config.repoRoot);
+    const gitMetadata = getGitLastModifiedBatch(config.repoRoot, result.map(doc => doc.path), gitMetadataOptions);
+    const gitDates = gitMetadata.dates;
     for (const doc of result) {
       const gitDate = gitDates.get(doc.path) ?? null;
       if (gitDate) {
         doc.daysSinceUpdate = computeDaysSinceUpdate(gitDate);
-        doc.isStale = computeIsStale(doc.status, gitDate, config);
+        doc.isStale = computeIsStale(doc.status, gitDate, config, doc.type);
       }
     }
+    if (!gitMetadata.complete) {
+      warn(`Git metadata is incomplete (${gitMetadata.reason}); query results use known dates only.`);
+    }
   }
 
   if (filters.stale) result = result.filter(d => d.isStale);
@@ -380,18 +390,16 @@ function scanBodyForKeyword(doc, needle, config) {
     warn(`Could not read ${doc.path}: ${err.message}`);
     return [];
   }
-  const { body } = extractFrontmatter(raw);
+  const { body, bodyLineOffset } = extractFrontmatter(raw);
   if (!body || !body.toLowerCase().includes(needle)) return [];
 
-  // body is a suffix of raw — the slice before it is the frontmatter block.
-  const bodyStartLine = raw.slice(0, raw.length - body.length).split('\n').length;
   const lines = body.split('\n');
   const matches = [];
   for (let i = 0; i < lines.length && matches.length < MAX_BODY_MATCHES; i++) {
     const text = lines[i].trim();
     const at = text.toLowerCase().indexOf(needle);
     if (at === -1) continue;
-    matches.push({ line: bodyStartLine + i, text: excerptAround(text, at, needle.length) });
+    matches.push({ line: bodyLineOffset + i + 1, text: excerptAround(text, at, needle.length) });
   }
   return matches;
 }
@@ -411,6 +419,7 @@ function getDocSummary(doc, config) {
     const { body } = extractFrontmatter(raw);
     if (!body?.trim()) return null;
     const meta = { title: doc.title, status: doc.status, path: doc.path };
+    if (config._execution?.suppressSideEffects) return null;
     return config.hooks.summarizeDoc
       ? config.hooks.summarizeDoc(body, meta)
       : summarizeDocBody(body, meta);
@@ -442,6 +451,9 @@ function renderQueryResults(docs, filters, config) {
   if (filters.hasNextStep) process.stdout.write('- has-next-step: true\n');
   if (filters.hasBlockers) process.stdout.write('- has-blockers: true\n');
   if (filters.checklistOpen) process.stdout.write('- checklist-open: true\n');
+  if (filters.summarize && config._execution?.suppressSideEffects) {
+    process.stdout.write('- summaries: skipped in side-effect-free preview\n');
+  }
   process.stdout.write('\n');
 
   if (docs.length === 0) { process.stdout.write('No matching docs.\n'); return; }

package/src/reference-planner.mjs

@@ -0,0 +1,292 @@
+import { realpathSync } from 'node:fs';
+import path from 'node:path';
+import { extractFrontmatter } from './frontmatter.mjs';
+
+function slash(value) { return value.split(path.sep).join('/'); }
+
+function canonicalExisting(filePath) {
+  try { return realpathSync(filePath); }
+  catch {
+    const suffix = [];
+    let cursor = path.resolve(filePath);
+    while (true) {
+      try { return path.join(realpathSync(cursor), ...suffix); }
+      catch {
+        const parent = path.dirname(cursor);
+        if (parent === cursor) return path.resolve(filePath);
+        suffix.unshift(path.basename(cursor));
+        cursor = parent;
+      }
+    }
+  }
+}
+
+export class AmbiguousReferenceError extends Error {
+  constructor(token, sourcePath, local, repository) {
+    super(`Ambiguous reference '${token}' in ${sourcePath}: document-relative resolves to ${local}, repository-relative resolves to ${repository}. Use an explicit unambiguous path.`);
+    this.name = 'AmbiguousReferenceError';
+    this.code = 'DOTMD_AMBIGUOUS_REFERENCE';
+  }
+}
+
+export function configuredReferenceFields(config) {
+  return [...new Set([
+    ...(config.referenceFields?.bidirectional ?? []),
+    ...(config.referenceFields?.unidirectional ?? []),
+  ])];
+}
+
+export function createReferenceIdentitySet(filePaths) {
+  const identities = new Set();
+  identities.paths = new Map();
+  for (const filePath of filePaths) {
+    const identity = canonicalExisting(filePath);
+    identities.add(identity);
+    identities.paths.set(identity, path.resolve(filePath));
+  }
+  return identities;
+}
+
+// Both interpretations are evaluated. A local document wins only when the
+// repo-relative spelling is absent or names the same identity; disagreement is
+// rejected rather than guessed.
+export function resolveReferenceIdentity(token, documentPath, repoRoot, identities) {
+  if (!token || /^(?:[a-z][a-z\d+.-]*:|\/\/|#)/i.test(token)) return null;
+  const clean = token.replace(/[?#].*$/, '').replace(/\\([\s()[\]<>])/g, '$1');
+  const local = canonicalExisting(path.resolve(path.dirname(documentPath), clean));
+  const repository = canonicalExisting(path.resolve(repoRoot, clean.replace(/^\/+/, '')));
+  const localExists = identities.has(local);
+  const repositoryExists = identities.has(repository);
+  if (localExists && repositoryExists && local !== repository) {
+    throw new AmbiguousReferenceError(token, documentPath, local, repository);
+  }
+  return localExists ? local : (repositoryExists ? repository : null);
+}
+
+function rewriteToken(token, sourcePath, outputPath, repoRoot, identities, oldIdentity, newPath, rebaseAll, format = 'plain') {
+  const target = resolveReferenceIdentity(token, sourcePath, repoRoot, identities);
+  if (!target || (!rebaseAll && target !== oldIdentity)) return token;
+  const destination = target === oldIdentity ? path.resolve(newPath) : (identities.paths?.get(target) ?? target);
+  const relative = slash(path.relative(path.dirname(outputPath), destination)) || path.basename(destination);
+  return format === 'escaped' ? relative.replace(/([\s()[\]<>])/g, '\\$1') : relative;
+}
+
+function rewritePathTokens(value, args) {
+  let quote = null;
+  let commentAt = -1;
+  for (let index = 0; index < value.length; index++) {
+    const char = value[index];
+    if (quote) {
+      if (char === quote && value[index - 1] !== '\\') quote = null;
+      continue;
+    }
+    if (char === '"' || char === "'") { quote = char; continue; }
+    if (char === '#' && index > 0 && /\s/.test(value[index - 1])) { commentAt = index - 1; break; }
+  }
+  const editable = commentAt === -1 ? value : value.slice(0, commentAt);
+  const comment = commentAt === -1 ? '' : value.slice(commentAt);
+  const quoted = editable.replace(/(["'])((?:\\.|(?!\1).)*)\1/g, (match, delimiter, token) => {
+    if (!/^.+\.md(?:[?#].*)?$/i.test(token)) return match;
+    const suffixAt = token.search(/[?#]/);
+    const bare = suffixAt === -1 ? token : token.slice(0, suffixAt);
+    const suffix = suffixAt === -1 ? '' : token.slice(suffixAt);
+    const rewritten = rewriteToken(bare, ...args);
+    return rewritten === bare ? match : `${delimiter}${rewritten}${suffix}${delimiter}`;
+  });
+  const rewritten = quoted.replace(/[^\s"'<>:[\],()#?]+\.md(?=$|[\s"'<>:[\],()#?])/g, token => rewriteToken(token, ...args));
+  return rewritten + comment;
+}
+
+function rewriteFrontmatter(frontmatter, fields, args) {
+  const allowed = new Set(fields);
+  const lines = frontmatter.split('\n');
+  let active = false;
+  return lines.map(line => {
+    const key = /^([A-Za-z_][\w-]*):(?:\s*(.*))?$/.exec(line);
+    if (key) {
+      active = allowed.has(key[1]);
+      if (!active) return line;
+      const colon = line.indexOf(':');
+      return line.slice(0, colon + 1) + rewritePathTokens(line.slice(colon + 1), args);
+    }
+    if (/^[^\s#][^:]*:/.test(line)) active = false;
+    if (!active || /^\s*#/.test(line)) return line;
+    return rewritePathTokens(line, args);
+  }).join('\n');
+}
+
+function destinationParts(raw) {
+  const angle = raw.startsWith('<') && raw.endsWith('>');
+  const inner = angle ? raw.slice(1, -1) : raw;
+  const suffixAt = inner.search(/[?#]/);
+  return {
+    angle,
+    path: suffixAt === -1 ? inner : inner.slice(0, suffixAt),
+    suffix: suffixAt === -1 ? '' : inner.slice(suffixAt),
+  };
+}
+
+function rewriteDestination(raw, args) {
+  const parsed = destinationParts(raw);
+  if (!/\.md$/i.test(parsed.path.replace(/\\./g, 'x'))) return raw;
+  const next = rewriteToken(parsed.path, ...args, parsed.angle ? 'plain' : 'escaped');
+  if (next === parsed.path) return raw;
+  const rendered = `${next}${parsed.suffix}`;
+  return parsed.angle ? `<${rendered}>` : rendered;
+}
+
+function rewriteMarkdownSegment(segment, args) {
+  // Inline links: angle destinations, escaped whitespace, optional titles.
+  let next = segment.replace(/(\[[^\]]*\]\(\s*)(<[^>\n]+>|(?:\\.|[^\s()])+)(\s+(?:"[^"]*"|'[^']*'|\([^)]*\)))?(\s*\))/g,
+    (match, prefix, destination, title = '', close, offset) => {
+      let escapes = 0;
+      for (let index = offset - 1; index >= 0 && segment[index] === '\\'; index--) escapes++;
+      if (escapes % 2 === 1) return match;
+      const rewritten = rewriteDestination(destination, args);
+      return rewritten === destination ? match : `${prefix}${rewritten}${title}${close}`;
+    });
+  // Reference definitions preserve labels, spacing, destinations, and titles.
+  next = next.replace(/^(\s{0,3}\[[^\]]+\]:\s*)(<[^>\n]+>|(?:\\.|[^\s])+)(.*)$/,
+    (match, prefix, destination, tail) => {
+      const rewritten = rewriteDestination(destination, args);
+      return rewritten === destination ? match : `${prefix}${rewritten}${tail}`;
+    });
+  return next;
+}
+
+function rewriteMarkdown(body, args) {
+  const lines = body.split('\n');
+  let fence = null;
+  let inlineRun = null;
+  let indentedCode = false;
+  let htmlBlock = null;
+  const containerContext = line => {
+    let rest = line;
+    let quotePrefix = '';
+    while (true) {
+      const quote = /^( {0,3}>[ \t]?)/.exec(rest);
+      if (!quote) break;
+      quotePrefix += quote[1];
+      rest = rest.slice(quote[1].length);
+    }
+    const list = /^( {0,3}(?:[-+*]|\d+[.)]))([ \t]+)/.exec(rest);
+    if (list) {
+      const padding = !list[2].includes('\t') && list[2].length <= 4 ? list[2] : list[2][0];
+      const listPrefix = `${list[1]}${padding}`;
+      rest = rest.slice(listPrefix.length);
+      return { content: rest, prefixes: [`${quotePrefix}${listPrefix}`, `${quotePrefix}${' '.repeat(listPrefix.length)}`] };
+    }
+    return { content: rest, prefixes: quotePrefix ? [quotePrefix] : [''] };
+  };
+  return lines.map(line => {
+    if (fence) {
+      const close = new RegExp(`^ {0,3}${fence.char === '`' ? '`' : '~'}{${fence.length},}[ \\t]*$`);
+      const compatible = fence.prefixes.find(prefix => line.startsWith(prefix));
+      if (compatible !== undefined && close.test(line.slice(compatible.length))) fence = null;
+      return line;
+    }
+    if (htmlBlock) {
+      if (htmlBlock === 'comment' && line.includes('-->')) htmlBlock = null;
+      else if (htmlBlock !== 'generic' && new RegExp(`</${htmlBlock}\\s*>`, 'i').test(line)) htmlBlock = null;
+      else if (htmlBlock === 'generic' && line.trim() === '') htmlBlock = null;
+      return line;
+    }
+    const trimmed = line.trimStart();
+    if (trimmed.startsWith('<!--')) {
+      if (!trimmed.includes('-->')) htmlBlock = 'comment';
+      return line;
+    }
+    const rawTag = /^<(pre|code|script|style)(?:\s|>|$)/i.exec(trimmed)?.[1]?.toLowerCase();
+    if (rawTag) {
+      if (!new RegExp(`</${rawTag}\\s*>`, 'i').test(trimmed)) htmlBlock = rawTag;
+      return line;
+    }
+    if (/^<\/?(?:address|article|aside|base|blockquote|body|caption|center|col|colgroup|dd|details|dialog|dir|div|dl|dt|fieldset|figcaption|figure|footer|form|h[1-6]|head|header|hr|html|iframe|legend|li|link|main|menu|menuitem|nav|ol|optgroup|option|p|param|search|section|summary|table|tbody|td|tfoot|th|thead|title|tr|track|ul)(?:\s|>|\/)/i.test(trimmed)) {
+      htmlBlock = 'generic';
+      return line;
+    }
+    if (trimmed.startsWith('<')) return line;
+    const container = containerContext(line);
+    if (indentedCode) {
+      if (container.content === '' || /^(?: {4}|\t)/.test(container.content)) return line;
+      indentedCode = false;
+    } else if (/^(?: {4}|\t)/.test(container.content)) {
+      indentedCode = true;
+      return line;
+    }
+    const opener = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(container.content);
+    if (opener) {
+      fence = { char: opener[1][0], length: opener[1].length, prefixes: container.prefixes };
+      return line;
+    }
+    let output = '';
+    let cursor = 0;
+    const runs = [...line.matchAll(/`+/g)];
+    let index = 0;
+    if (inlineRun !== null) {
+      const closingIndex = runs.findIndex(candidate => candidate[0].length === inlineRun);
+      if (closingIndex === -1) return line;
+      const closing = runs[closingIndex];
+      output += line.slice(0, closing.index + closing[0].length);
+      cursor = closing.index + closing[0].length;
+      index = closingIndex + 1;
+      inlineRun = null;
+    }
+    for (; index < runs.length; index++) {
+      const opening = runs[index];
+      const closingIndex = runs.findIndex((candidate, candidateIndex) => candidateIndex > index && candidate[0].length === opening[0].length);
+      if (closingIndex === -1) {
+        output += rewriteMarkdownSegment(line.slice(cursor, opening.index), args);
+        output += line.slice(opening.index);
+        inlineRun = opening[0].length;
+        cursor = line.length;
+        break;
+      }
+      const closing = runs[closingIndex];
+      output += rewriteMarkdownSegment(line.slice(cursor, opening.index), args);
+      output += line.slice(opening.index, closing.index + closing[0].length);
+      cursor = closing.index + closing[0].length;
+      index = closingIndex;
+    }
+    return output + rewriteMarkdownSegment(line.slice(cursor), args);
+  }).join('\n');
+}
+
+export function rewriteDocumentReferences(content, {
+  sourcePath,
+  outputPath = sourcePath,
+  repoRoot,
+  identities,
+  oldPath,
+  newPath,
+  referenceFields = [],
+  rebaseAll = false,
+}) {
+  const { frontmatter, body } = extractFrontmatter(content);
+  if (!frontmatter) return content;
+  const oldIdentity = canonicalExisting(oldPath);
+  const args = [sourcePath, outputPath, repoRoot, identities, oldIdentity, newPath, rebaseAll];
+  const nextFrontmatter = rewriteFrontmatter(frontmatter, referenceFields, args);
+  const nextBody = rewriteMarkdown(body, args);
+  return nextFrontmatter === frontmatter && nextBody === body ? content : `---\n${nextFrontmatter}\n---\n${nextBody}`;
+}
+
+export function planReferenceMove({ documents, oldPath, newPath, repoRoot, referenceFields = [] }) {
+  const identities = createReferenceIdentitySet(documents.map(document => document.path));
+  const oldIdentity = canonicalExisting(oldPath);
+  identities.add(oldIdentity);
+  const source = documents.find(document => path.resolve(document.path) === path.resolve(oldPath));
+  if (!source) throw new Error(`Reference move plan is missing source content: ${oldPath}`);
+  const movedContent = rewriteDocumentReferences(source.content, {
+    sourcePath: oldPath, outputPath: newPath, repoRoot, identities, oldPath, newPath, referenceFields, rebaseAll: true,
+  });
+  const updates = [];
+  for (const document of documents) {
+    if (path.resolve(document.path) === path.resolve(oldPath)) continue;
+    const content = rewriteDocumentReferences(document.content, {
+      sourcePath: document.path, repoRoot, identities, oldPath, newPath, referenceFields,
+    });
+    if (content !== document.content) updates.push({ path: document.path, expectedContent: document.content, content });
+  }
+  return { movedContent, updates, identities };
+}