dotmd-cli 0.69.0 → 0.70.1

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 };
+}

package/src/rename.mjs

@@ -1,107 +1,99 @@
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { toRepoPath, die, warn } from './util.mjs';
 import { collectDocFiles, resolveDocArg } from './index.mjs';
 import { regenIndex } from './lifecycle.mjs';
-import { gitMv } from './git.mjs';
+import { captureGitIndexGeneration, isTracked } from './git.mjs';
 import { green, dim } from './color.mjs';
 import { isInteractive, promptText } from './prompt.mjs';
+import { authorizeManagedDestination, authorizeManagedSource, authorizeManagedSweep } from './managed-path.mjs';
+import { availableSessionId, prepareOwnershipMigration } from './pickup.mjs';
+import { moveFileAtomic } from './atomic-mutation.mjs';
+import { configuredReferenceFields, createReferenceIdentitySet, planReferenceMove, rewriteDocumentReferences } from './reference-planner.mjs';
 
 export async function runRename(argv, config, opts = {}) {
   const { dryRun } = opts;
-
-  // Parse positional args (skip flags)
-  const positional = [];
-  for (let i = 0; i < argv.length; i++) {
-    if (argv[i].startsWith('-')) continue;
-    positional.push(argv[i]);
-  }
-
+  const positional = argv.filter(arg => !arg.startsWith('-'));
   const oldInput = positional[0];
   let newInput = positional[1];
-
-  if (!oldInput) { die('Usage: dotmd rename <old> <new>'); }
+  if (!oldInput) die('Usage: dotmd rename <old> <new>');
   if (!newInput) {
-    if (isInteractive()) {
-      newInput = await promptText('New name: ');
-      if (!newInput) die('No name provided.');
-    } else {
-      die('Usage: dotmd rename <old> <new>');
-    }
+    if (!isInteractive()) die('Usage: dotmd rename <old> <new>');
+    newInput = await promptText('New name: ');
+    if (!newInput) die('No name provided.');
   }
 
-  // Resolve old path
-  const oldPath = resolveDocArg(oldInput, config);
-
-  // Compute new path — cross-directory if input has slashes, same directory otherwise
+  let oldPath = resolveDocArg(oldInput, config);
+  const sourceAuthorization = authorizeManagedSource(oldPath, config, { kind: 'Rename source' });
+  oldPath = sourceAuthorization.path;
   let newPath;
   if (newInput.includes('/') || newInput.includes(path.sep)) {
-    let resolved = newInput;
-    if (!resolved.endsWith('.md')) resolved += '.md';
-    newPath = path.resolve(config.repoRoot, resolved);
+    newPath = path.resolve(config.repoRoot, newInput.endsWith('.md') ? newInput : `${newInput}.md`);
   } else {
-    let newBasename = newInput;
-    if (!newBasename.endsWith('.md')) newBasename += '.md';
-    newPath = path.join(path.dirname(oldPath), newBasename);
-  }
-
-  if (existsSync(newPath)) {
-    die(`Target already exists: ${toRepoPath(newPath, config.repoRoot)}`);
-    return;
+    newPath = path.join(path.dirname(oldPath), newInput.endsWith('.md') ? newInput : `${newInput}.md`);
   }
+  if (existsSync(newPath)) die(`Target already exists: ${toRepoPath(newPath, config.repoRoot)}`);
+  newPath = authorizeManagedDestination(newPath, config, { root: sourceAuthorization.root, kind: 'Rename destination' }).path;
 
   const oldRepoPath = toRepoPath(oldPath, config.repoRoot);
   const newRepoPath = toRepoPath(newPath, config.repoRoot);
-  const oldBasename = path.basename(oldPath);
-  const newBasename = path.basename(newPath);
-
-  // Scan for references in other docs
   const allFiles = collectDocFiles(config);
-  const filesToUpdate = [];
-
-  for (const filePath of allFiles) {
-    if (filePath === oldPath) continue;
-    const raw = readFileSync(filePath, 'utf8');
-    if (raw.includes(oldBasename)) {
-      filesToUpdate.push(filePath);
-    }
+  authorizeManagedSweep(allFiles, config, { kind: 'Rename reference rewrite source' });
+  const documents = allFiles.map(filePath => ({ path: filePath, content: readFileSync(filePath, 'utf8') }));
+  let sourceDocument = documents.find(document => document.path === oldPath);
+  if (!sourceDocument) {
+    sourceDocument = { path: oldPath, content: readFileSync(oldPath, 'utf8') };
+    documents.push(sourceDocument);
   }
+  const sourceContent = sourceDocument.content;
+  const referenceFields = configuredReferenceFields(config);
+  const referencePlan = planReferenceMove({ documents, oldPath, newPath, repoRoot: config.repoRoot, referenceFields });
+  const ownership = prepareOwnershipMigration(oldRepoPath, newPath, config, { sessionId: availableSessionId() });
 
   if (dryRun) {
     const prefix = dim('[dry-run]');
     process.stdout.write(`${prefix} Would rename: ${oldRepoPath} → ${newRepoPath}\n`);
-    if (filesToUpdate.length > 0) {
-      process.stdout.write(`${prefix} Would update references in ${filesToUpdate.length} file(s):\n`);
-      for (const f of filesToUpdate) {
-        process.stdout.write(`${prefix}   ${toRepoPath(f, config.repoRoot)}\n`);
-      }
+    if (referencePlan.updates.length) {
+      process.stdout.write(`${prefix} Would update references in ${referencePlan.updates.length} file(s):\n`);
+      for (const item of referencePlan.updates) process.stdout.write(`${prefix}   ${toRepoPath(item.path, config.repoRoot)}\n`);
     }
+    if (ownership) process.stdout.write(`${prefix} Would migrate this session's ownership record.\n`);
     return;
   }
 
-  // Perform git mv
-  const result = gitMv(oldPath, newPath, config.repoRoot);
-  if (result.status !== 0) {
-    die(result.stderr || 'git mv failed.');
-  }
-
-  // Update all references (frontmatter + body) in other docs
-  let updatedCount = 0;
-  for (const filePath of filesToUpdate) {
-    const raw = readFileSync(filePath, 'utf8');
-    const updated = raw.split(oldBasename).join(newBasename);
-    if (updated !== raw) {
-      writeFileSync(filePath, updated, 'utf8');
-      updatedCount++;
-    }
-  }
-
+  const tracked = isTracked(oldPath, config.repoRoot);
+  const gitIndex = tracked ? captureGitIndexGeneration(config.repoRoot) : null;
+  const identities = createReferenceIdentitySet(allFiles);
+  const result = moveFileAtomic(oldPath, newPath, current => rewriteDocumentReferences(current, {
+    sourcePath: oldPath,
+    outputPath: newPath,
+    repoRoot: config.repoRoot,
+    identities,
+    oldPath,
+    newPath,
+    referenceFields,
+    rebaseAll: true,
+  }), {
+    repoRoot: config.repoRoot,
+    config,
+    updates: allFiles.filter(filePath => filePath !== oldPath).map(filePath => ({
+      path: filePath,
+      render: current => rewriteDocumentReferences(current, {
+        sourcePath: filePath, repoRoot: config.repoRoot, identities, oldPath, newPath, referenceFields,
+      }),
+    })),
+    creations: ownership ? [{ path: ownership.newRecordPath, content: ownership.newContent, label: 'ownership' }] : [],
+    deletions: ownership ? [{ path: ownership.oldRecordPath, expectedContent: ownership.oldContent, label: 'ownership' }] : [],
+    gitMove: tracked,
+    gitIndex,
+    operation: 'rename',
+    sessionId: availableSessionId(),
+    testHooks: opts.testHooks,
+  });
   regenIndex(config);
-
   process.stdout.write(`${green('Renamed')}: ${oldRepoPath} → ${newRepoPath}\n`);
-  if (updatedCount > 0) {
-    process.stdout.write(`Updated references in ${updatedCount} file(s).\n`);
-  }
-
-  try { config.hooks.onRename?.({ oldPath: oldRepoPath, newPath: newRepoPath, referencesUpdated: updatedCount }); } catch (err) { warn(`Hook 'onRename' threw: ${err.message}`); }
+  if (result.updatedPaths.length) process.stdout.write(`Updated references in ${result.updatedPaths.length} file(s).\n`);
+  try { config.hooks.onRename?.({ oldPath: oldRepoPath, newPath: newRepoPath, referencesUpdated: result.updatedPaths.length }); }
+  catch (err) { warn(`Hook 'onRename' threw: ${err.message}`); }
+  return { oldRepoPath, newRepoPath, referencePaths: result.updatedPaths.map(item => toRepoPath(item, config.repoRoot)) };
 }

package/src/render.mjs

@@ -6,6 +6,7 @@ import { summarizeDocBody } from './ai.mjs';
 import { bold, red, yellow, green, dim } from './color.mjs';
 import { categorizeWarnings } from './check-collapse.mjs';
 import { buildCoordinationIndex, isRoadmapHub } from './runlist.mjs';
+import { resolveStatusMetadata, statusMetadataFor } from './status-metadata.mjs';
 
 // Render `currentState` with an `(auto)` prefix when the value was body-scraped
 // rather than read from frontmatter. Lets a reader see at a glance which docs
@@ -20,7 +21,7 @@ export function formatCurrentState(doc) {
 
 export function renderCompactList(index, config) {
   const defaultRenderer = (idx) => _renderCompactList(idx, config);
-  if (config.hooks.renderCompactList) {
+  if (!config._execution?.suppressSideEffects && config.hooks.renderCompactList) {
     try { return config.hooks.renderCompactList(index, defaultRenderer); }
     catch (err) { warn(`Hook 'renderCompactList' threw: ${err.message}`); }
   }
@@ -162,7 +163,7 @@ export function renderVerboseList(index, config) {
 
 export function renderContext(index, config, opts = {}) {
   const defaultRenderer = (idx) => _renderContext(idx, config, opts);
-  if (config.hooks.renderContext) {
+  if (!config._execution?.suppressSideEffects && config.hooks.renderContext) {
     try { return config.hooks.renderContext(index, defaultRenderer); }
     catch (err) { warn(`Hook 'renderContext' threw: ${err.message}`); }
   }
@@ -190,7 +191,7 @@ function _renderContextSection(docs, ctx, opts, config, lines) {
         ? truncate(doc.nextStep, ctx.truncateNextStep || 80)
         : '(no next step)';
       lines.push(`  ${slug}${ageTag}  next: ${next}`);
-      if (opts.summarize) {
+      if (opts.summarize && !config._execution?.suppressSideEffects) {
         try {
           const absPath = path.resolve(config.repoRoot, doc.path);
           const raw = readFileSync(absPath, 'utf8');
@@ -225,6 +226,9 @@ function _renderContextSection(docs, ctx, opts, config, lines) {
 function _renderContext(index, config, opts = {}) {
   const today = new Date().toISOString().slice(0, 10);
   const lines = [`BRIEFING (${today})`, ''];
+  if (opts.summarize && config._execution?.suppressSideEffects) {
+    lines.push(dim('[preview] AI summaries skipped; models and custom summarizeDoc hooks are not invoked.'), '');
+  }
 
   // Group docs by type
   const typeOrder = ['plan', 'doc', 'research'];
@@ -352,11 +356,16 @@ export function renderBriefing(index, config) {
     // headline plan count entirely (they get their own `N runlists · dotmd
     // runlists` pointer line below). The breakdown is leaf statuses only and sums
     // back to the leaf count, so "N live plans" means N things to actually work on.
-    const counts = Object.entries(bySt).map(([s, n]) => `${n} ${s}`).join(', ');
+    const planStatusOrder = (resolveStatusMetadata(config).byType.plan ?? []).map(item => item.name);
+    const orderedStatuses = [
+      ...planStatusOrder.filter(status => bySt[status]),
+      ...Object.keys(bySt).filter(status => !planStatusOrder.includes(status)).sort(),
+    ];
+    const counts = orderedStatuses.map(status => `${bySt[status]} ${status}`).join(', ');
     const closedCount = plans.length - live.length;
     const closedPart = closedCount ? ` (${closedCount} archived)` : '';
     lines.push(liveLeaves ? `${liveLeaves} live plans${closedPart}: ${counts}` : `0 live plans${closedPart}`);
-    const show = plans.filter(p => (p.status === 'in-session' || p.status === 'active') && !isHub(p));
+    const show = plans.filter(p => statusMetadataFor(config, 'plan', p.status)?.context === 'expanded' && !isHub(p));
     for (const p of show) {
       const next = p.nextStep ? `next: ${p.nextStep}` : '(no next step)';
       lines.push(`  > ${path.basename(p.path, '.md')} (${p.status}) ${next}`);
@@ -382,7 +391,7 @@ export function renderBriefing(index, config) {
   if (untyped.length) parts.push(`${untyped.length} untyped`);
   if (parts.length) lines.push(parts.join(' | '));
 
-  const stale = index.docs.filter(d => d.isStale && !config.lifecycle.skipStaleFor.has(d.status)).length;
+  const stale = index.docs.filter(d => d.isStale && !statusMetadataFor(config, d.type, d.status)?.skipStale).length;
   // Append a hint when errors are present — otherwise the user sees `Errors: 1`
   // with no clue what or where. `dotmd check` is the canonical detail view.
   const errorCount = index.errors.length;
@@ -396,7 +405,7 @@ export function renderBriefing(index, config) {
 
 export function renderCheck(index, config, opts = {}) {
   const defaultRenderer = (idx) => _renderCheck(idx, opts);
-  if (config.hooks.renderCheck) {
+  if (!config._execution?.suppressSideEffects && config.hooks.renderCheck) {
     try { return config.hooks.renderCheck(index, defaultRenderer); }
     catch (err) { warn(`Hook 'renderCheck' threw: ${err.message}`); }
   }
@@ -413,7 +422,8 @@ export function classifyIssueAction(issue) {
   if (/Missing frontmatter `updated`/.test(message) || /frontmatter `updated: .*` is behind git history/.test(message)) {
     return { action: 'dotmd touch --git', fixable: true, label: 'dates' };
   }
-  if (/`(?:module|surface):` \(singular\) is deprecated/.test(message) || /camelCase|nextStep|currentState|auditLevel/.test(message)) {
+  if ((/`(?:module|surface):` \(singular\) is deprecated/.test(message) && /Run `dotmd lint --fix`/.test(message))
+    || /camelCase|nextStep|currentState|auditLevel/.test(message)) {
     return { action: 'dotmd lint --fix', fixable: true, label: 'frontmatter migrations' };
   }
   if (/Unknown surface/.test(message)) {
@@ -447,8 +457,9 @@ export function renderManualFixes(index) {
   for (const issue of issues) {
     const item = classifyIssueAction(issue);
     const key = `${item.fixable ? 'fixable' : 'manual'}:${item.action}`;
-    if (!groups.has(key)) groups.set(key, { ...item, paths: new Set() });
+    if (!groups.has(key)) groups.set(key, { ...item, paths: new Set(), reasons: new Set() });
     groups.get(key).paths.add(issue.path);
+    groups.get(key).reasons.add(issue.message);
   }
   if (groups.size === 0) return '';
 
@@ -469,7 +480,9 @@ export function renderManualFixes(index) {
     lines.push('Manual fixes remaining');
     for (const group of manual) {
       const count = group.paths.size;
-      lines.push(`- ${group.action} (${count} ${count === 1 ? 'file' : 'files'}: ${[...group.paths].slice(0, 3).join(', ')}${count > 3 ? ', ...' : ''})`);
+      const reasons = [...group.reasons];
+      const reason = reasons.slice(0, 2).join('; ') + (reasons.length > 2 ? '; ...' : '');
+      lines.push(`- ${group.action}: ${reason} (${count} ${count === 1 ? 'file' : 'files'}: ${[...group.paths].slice(0, 3).join(', ')}${count > 3 ? ', ...' : ''})`);
     }
     lines.push('');
   }
@@ -586,7 +599,7 @@ export function renderProgressBar(checklist) {
 
 export function formatSnapshot(doc, config) {
   const defaultFormatter = (d) => _formatSnapshot(d, config);
-  if (config.hooks.formatSnapshot) {
+  if (!config._execution?.suppressSideEffects && config.hooks.formatSnapshot) {
     try { return config.hooks.formatSnapshot(doc, defaultFormatter); }
     catch (err) { warn(`Hook 'formatSnapshot' threw: ${err.message}`); }
   }