dotmd-cli 0.68.0 → 0.70.0

package/src/lint.mjs

@@ -6,6 +6,7 @@ import { buildIndex, collectDocFiles } from './index.mjs';
 import { updateFrontmatter } from './lifecycle.mjs';
 import { runMLX, checkUvAvailable } from './ai.mjs';
 import { bold, green, yellow, dim } from './color.mjs';
+import { authorizeManagedSweep, findLexicalDocsRoot } from './managed-path.mjs';
 
 const KEY_RENAMES = {
   nextStep: 'next_step',
@@ -32,8 +33,7 @@ export function runLint(argv, config, opts = {}) {
 
     // Missing type (fixable — infer from root: plans → 'plan', else 'doc')
     if (!asString(parsed.type)) {
-      const roots = config.docsRoots || [config.docsRoot];
-      const docRoot = roots.find(r => filePath.startsWith(r)) ?? config.docsRoot;
+      const docRoot = findLexicalDocsRoot(filePath, config) ?? config.docsRoot;
       const rootLabel = path.relative(config.repoRoot, docRoot).split(path.sep).join('/');
       // If the root label contains 'plan' (e.g. 'docs/plans'), default to plan type
       const inferredType = rootLabel.includes('plan') ? 'plan' : 'doc';
@@ -73,12 +73,26 @@ export function runLint(argv, config, opts = {}) {
     // existing plural array happens at apply-time so the message reflects
     // just what's being introduced from the singular form.
     for (const { singular, plural } of [{ singular: 'module', plural: 'modules' }, { singular: 'surface', plural: 'surfaces' }]) {
-      const val = asString(parsed[singular]);
-      if (!val) continue;
-      const values = val.includes(',')
-        ? val.split(',').map(s => s.trim()).filter(Boolean)
-        : [val];
-      fixes.push({ field: singular, oldValue: val, newValue: values, pluralKey: plural, type: 'singular-to-plural' });
+      const rawVal = parsed[singular];
+      const val = asString(rawVal);
+      if (val) {
+        // Inline value (`surface: foo`) → migrate into the plural array.
+        const values = val.includes(',')
+          ? val.split(',').map(s => s.trim()).filter(Boolean)
+          : [val];
+        fixes.push({ field: singular, oldValue: val, newValue: values, pluralKey: plural, type: 'singular-to-plural' });
+      } else if (singular in parsed && (!Array.isArray(rawVal) || rawVal.length === 0)) {
+        // Empty deprecated key (`surface:` with nothing after it, which the
+        // parser yields as `[]`) — usually sitting right above a populated
+        // `surfaces:`. There's no value to migrate; the deprecation warning
+        // just wants the dead line gone. `validate` treats the empty `[]` as
+        // present (so it warns), while the old `asString` gate here saw it as
+        // absent and skipped — the exact no-op reported in issue #17. Emit a
+        // drop fix so `lint --fix` does what the warning advertises. A
+        // populated block-form singular (rawVal.length > 0) is left untouched:
+        // too rare to risk mis-editing.
+        fixes.push({ field: singular, pluralKey: plural, type: 'drop-singular' });
+      }
     }
 
     // Trailing whitespace in values
@@ -102,8 +116,22 @@ export function runLint(argv, config, opts = {}) {
   // Also get non-fixable issues from index, excluding issues we can already fix
   const index = buildIndex(config);
   const fixablePaths = new Set(fixable.map(f => f.repoPath));
+  // Singular-key deprecation warnings whose fix `lint --fix` will actually make.
+  // Without this, those warnings landed in BOTH the "fixable" preview and the
+  // "non-fixable" list, so the header claimed "N non-fixable" while every line
+  // told you to run `lint --fix` (issue #17, item 8).
+  const fixableSingularKeys = new Set();
+  for (const { repoPath, fixes } of fixable) {
+    for (const f of fixes) {
+      if (f.type === 'singular-to-plural' || f.type === 'drop-singular') {
+        fixableSingularKeys.add(`${repoPath}::${f.field}`);
+      }
+    }
+  }
   const nonFixable = [...index.errors, ...index.warnings].filter(issue => {
     if (issue.message.includes('Missing frontmatter `status`') && fixablePaths.has(issue.path)) return false;
+    const dep = issue.message.match(/^`(module|surface):` \(singular\) is deprecated/);
+    if (dep && fixableSingularKeys.has(`${issue.path}::${dep[1]}`)) return false;
     return true;
   });
 
@@ -120,6 +148,8 @@ export function runLint(argv, config, opts = {}) {
             process.stdout.write(dim(`    missing status (fixable via AI)\n`));
           } else if (f.type === 'singular-to-plural') {
             process.stdout.write(dim(`    ${f.field}: "${f.oldValue}" → ${f.pluralKey}: [${f.newValue.join(', ')}]\n`));
+          } else if (f.type === 'drop-singular') {
+            process.stdout.write(dim(`    remove deprecated \`${f.field}:\` (empty; \`${f.pluralKey}:\` is the live key)\n`));
           } else if (f.type === 'eof') {
             process.stdout.write(dim(`    missing newline at end of file\n`));
           } else if (f.type === 'add') {
@@ -146,6 +176,7 @@ export function runLint(argv, config, opts = {}) {
   }
 
   // Fix mode
+  authorizeManagedSweep(fixable.map(item => item.filePath), config, { kind: 'Lint fix source' });
   const prefix = dryRun ? dim('[dry-run] ') : '';
   let totalFixes = 0;
 
@@ -155,6 +186,7 @@ export function runLint(argv, config, opts = {}) {
     let needsEofFix = false;
     const trimFixes = [];
     const singularToPlural = [];
+    const dropSingular = [];
 
     for (const f of fixes) {
       if (f.type === 'rename-key') {
@@ -165,6 +197,8 @@ export function runLint(argv, config, opts = {}) {
         trimFixes.push(f);
       } else if (f.type === 'singular-to-plural') {
         singularToPlural.push(f);
+      } else if (f.type === 'drop-singular') {
+        dropSingular.push(f);
       } else {
         updates[f.field] = f.newValue;
       }
@@ -212,6 +246,19 @@ export function runLint(argv, config, opts = {}) {
         writeFileSync(filePath, raw, 'utf8');
       }
 
+      // Drop empty deprecated singular keys. The value is known-empty (the fix
+      // is only emitted for `[]`/`''`), so this matches the bare `key:` line
+      // exactly — never a line carrying content — and removes it.
+      for (const ds of dropSingular) {
+        let raw = readFileSync(filePath, 'utf8');
+        const { frontmatter: fm } = extractFrontmatter(raw);
+        const newFm = fm
+          .replace(new RegExp(`^${escapeRegex(ds.field)}:[ \\t]*$`, 'm'), '')
+          .replace(/\n{2,}/g, '\n');
+        raw = replaceFrontmatter(raw, newFm.trim());
+        writeFileSync(filePath, raw, 'utf8');
+      }
+
       // Apply key renames and trim fixes via raw string manipulation
       if (keyRenames.length > 0 || trimFixes.length > 0) {
         let raw = readFileSync(filePath, 'utf8');
@@ -259,6 +306,8 @@ export function runLint(argv, config, opts = {}) {
         }
       } else if (f.type === 'singular-to-plural') {
         process.stdout.write(`${prefix}  ${dim(`${f.field}: "${f.oldValue}" → ${f.pluralKey}: [${f.newValue.join(', ')}]`)}\n`);
+      } else if (f.type === 'drop-singular') {
+        process.stdout.write(`${prefix}  ${dim(`removed deprecated \`${f.field}:\` (empty)`)}\n`);
       } else if (f.type === 'add') {
         process.stdout.write(`${prefix}  ${dim(`add ${f.field}: ${f.newValue}`)}\n`);
       } else {
@@ -274,4 +323,3 @@ export function runLint(argv, config, opts = {}) {
 
   process.stdout.write(`\n${prefix}${totalFixes} fix${totalFixes !== 1 ? 'es' : ''} applied across ${fixable.length} file(s).\n`);
 }
-

package/src/managed-path.mjs

@@ -0,0 +1,192 @@
+import { existsSync, lstatSync, realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+// These checks are authorization preflights, not filesystem transactions. A
+// concurrent actor can still replace a checked ancestor before the later write
+// (TOCTOU); eliminating that residual boundary requires descriptor-relative IO.
+
+function contains(parent, child) {
+  const rel = path.relative(parent, child);
+  return rel === '' || (!rel.startsWith(`..${path.sep}`) && rel !== '..' && !path.isAbsolute(rel));
+}
+
+function sameNode(a, b) {
+  try {
+    const left = statSync(a, { bigint: true });
+    const right = statSync(b, { bigint: true });
+    return left.dev === right.dev && left.ino === right.ino;
+  } catch { return false; }
+}
+
+// realpath on case-insensitive macOS volumes may preserve the caller's casing.
+// Prove an alias by inode before treating it as contained; lowercase string
+// comparison alone would be unsafe on case-sensitive volumes.
+function aliasContainment(parent, child) {
+  if (contains(parent, child)) return { contained: true, relative: path.relative(parent, child) };
+  const parentParts = path.resolve(parent).split(path.sep).filter(Boolean);
+  const childParts = path.resolve(child).split(path.sep).filter(Boolean);
+  if (childParts.length < parentParts.length) return { contained: false, relative: null };
+  const childPrefix = `${path.parse(path.resolve(child)).root}${childParts.slice(0, parentParts.length).join(path.sep)}`;
+  if (!sameNode(parent, childPrefix)) return { contained: false, relative: null };
+  return { contained: true, relative: childParts.slice(parentParts.length).join(path.sep) };
+}
+
+function lexicalRootsFor(config) {
+  return (config.docsRoots ?? [config.docsRoot]).map(configuredPath => ({
+    configuredPath,
+    lexicalPath: path.resolve(configuredPath),
+  }));
+}
+
+function rootsFor(config) {
+  return lexicalRootsFor(config).map(root => {
+    const { configuredPath, lexicalPath } = root;
+    let canonicalPath;
+    try {
+      canonicalPath = realpathSync(lexicalPath);
+    } catch (err) {
+      throw new Error(`Configured docs root cannot be resolved: ${lexicalPath} (${err.message})`);
+    }
+    return { configuredPath, lexicalPath, canonicalPath };
+  });
+}
+
+function rootsMessage(roots) {
+  return roots.map(root => root.lexicalPath).join(', ');
+}
+
+function markdown(pathname, kind, roots) {
+  if (!pathname.endsWith('.md')) {
+    throw new Error(`${kind} must be a Markdown file ending in .md: ${pathname}\nConfigured docs roots: ${rootsMessage(roots)}`);
+  }
+}
+
+function nearestExistingAncestor(input, roots, kind) {
+  let current = input;
+  while (!existsSync(current)) {
+    try {
+      // existsSync is false for dangling symlinks, but lstat still sees them.
+      if (lstatSync(current).isSymbolicLink()) {
+        throw new Error(`dangling symlink: ${current}`);
+      }
+    } catch (err) {
+      if (err?.code !== 'ENOENT' && err?.code !== 'ENOTDIR') {
+        throw new Error(`${kind} has an unsafe existing ancestor: ${current} (${err.message})\nConfigured docs roots: ${rootsMessage(roots)}`);
+      }
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  try {
+    return realpathSync(current);
+  } catch (err) {
+    throw new Error(`${kind} ancestor cannot be resolved: ${current} (${err.message})\nConfigured docs roots: ${rootsMessage(roots)}`);
+  }
+}
+
+function lexicalOwner(input, roots) {
+  return roots
+    .filter(root => contains(root.lexicalPath, input))
+    .sort((a, b) => b.lexicalPath.length - a.lexicalPath.length)[0] ?? null;
+}
+
+export function findLexicalDocsRoot(input, config) {
+  return lexicalOwner(path.resolve(input), lexicalRootsFor(config))?.lexicalPath ?? null;
+}
+
+export function authorizeManagedSource(input, config, { kind = 'Managed mutation source' } = {}) {
+  const roots = rootsFor(config);
+  const lexicalPath = path.resolve(input);
+  markdown(lexicalPath, kind, roots);
+
+  if (!existsSync(lexicalPath)) {
+    throw new Error(`${kind} does not exist: ${lexicalPath}\nConfigured docs roots: ${rootsMessage(roots)}`);
+  }
+  if (lstatSync(lexicalPath).isSymbolicLink()) {
+    throw new Error(`${kind} may not be a symlink: ${lexicalPath}\nConfigured docs roots: ${rootsMessage(roots)}`);
+  }
+
+  let canonicalPath;
+  try {
+    canonicalPath = realpathSync(lexicalPath);
+  } catch (err) {
+    throw new Error(`${kind} cannot be resolved: ${lexicalPath} (${err.message})\nConfigured docs roots: ${rootsMessage(roots)}`);
+  }
+  if (!statSync(canonicalPath).isFile()) {
+    throw new Error(`${kind} is not a file: ${lexicalPath}\nConfigured docs roots: ${rootsMessage(roots)}`);
+  }
+
+  const lexical = lexicalOwner(lexicalPath, roots);
+  if (lexical && !aliasContainment(lexical.canonicalPath, canonicalPath).contained) {
+    throw new Error(`${kind} is lexically owned by ${lexical.lexicalPath} but resolves outside that root: ${lexicalPath} -> ${canonicalPath}\nConfigured docs roots: ${rootsMessage(roots)}`);
+  }
+  const root = lexical
+    ?? roots.filter(candidate => aliasContainment(candidate.canonicalPath, canonicalPath).contained)
+      .sort((a, b) => b.canonicalPath.length - a.canonicalPath.length)[0];
+  if (!root) {
+    throw new Error(`${kind} resolves outside configured docs roots: ${lexicalPath} -> ${canonicalPath}\nConfigured docs roots: ${rootsMessage(roots)}`);
+  }
+
+  // Keep operations on the configured root spelling (important when the root
+  // itself is a symlink), while normalizing OS-level aliases such as /var ->
+  // /private/var back through the owning root.
+  const managedPath = lexical
+    ? lexicalPath
+    : path.join(root.lexicalPath, aliasContainment(root.canonicalPath, canonicalPath).relative);
+  return { path: managedPath, canonicalPath, root };
+}
+
+export function authorizeManagedDestination(input, config, { root: requiredRoot = null, kind = 'Managed mutation destination' } = {}) {
+  const roots = rootsFor(config);
+  const lexicalPath = path.resolve(input);
+  markdown(lexicalPath, kind, roots);
+
+  const root = requiredRoot
+    ? roots.find(candidate => candidate.lexicalPath === requiredRoot.lexicalPath && candidate.canonicalPath === requiredRoot.canonicalPath)
+    : lexicalOwner(lexicalPath, roots);
+  if (!root || !contains(root.lexicalPath, lexicalPath)) {
+    const ownership = requiredRoot ? `Owning docs root: ${requiredRoot.lexicalPath}\n` : '';
+    throw new Error(`${kind} is lexically outside its configured docs root: ${lexicalPath}\n${ownership}Configured docs roots: ${rootsMessage(roots)}`);
+  }
+
+  const ancestor = nearestExistingAncestor(lexicalPath, roots, kind);
+  if (!aliasContainment(root.canonicalPath, ancestor).contained) {
+    throw new Error(`${kind} escapes through an existing symlinked parent: ${lexicalPath} -> ${ancestor}\nOwning docs root: ${root.lexicalPath}\nConfigured docs roots: ${rootsMessage(roots)}`);
+  }
+  return { path: lexicalPath, canonicalPath: existsSync(lexicalPath) ? realpathSync(lexicalPath) : null, root };
+}
+
+export function authorizeManagedMove(source, destination, config, options = {}) {
+  const authorizedSource = authorizeManagedSource(source, config, options);
+  const authorizedDestination = authorizeManagedDestination(destination, config, {
+    ...options,
+    kind: options.destinationKind ?? 'Managed mutation destination',
+    root: authorizedSource.root,
+  });
+  return { source: authorizedSource, destination: authorizedDestination };
+}
+
+export function authorizeManagedSweep(files, config, { kind = 'Managed mutation sweep' } = {}) {
+  return files.map(file => authorizeManagedSource(file, config, { kind }));
+}
+
+export function authorizeRepoGeneratedPath(input, config, { kind = 'Repository-generated destination' } = {}) {
+  const lexicalPath = path.resolve(input);
+  const repoRoot = path.resolve(config.repoRoot);
+  let canonicalRepo;
+  try { canonicalRepo = realpathSync(repoRoot); }
+  catch (err) { throw new Error(`Repository root cannot be resolved: ${repoRoot} (${err.message})`); }
+
+  if (!contains(repoRoot, lexicalPath)) {
+    throw new Error(`${kind} is outside the repository: ${lexicalPath}\nRepository root: ${repoRoot}`);
+  }
+  const ancestor = nearestExistingAncestor(lexicalPath, [{ lexicalPath: repoRoot }], kind);
+  if (!contains(canonicalRepo, ancestor)) {
+    throw new Error(`${kind} escapes through an existing symlinked parent: ${lexicalPath} -> ${ancestor}\nRepository root: ${repoRoot}`);
+  }
+  if (existsSync(lexicalPath) && lstatSync(lexicalPath).isSymbolicLink()) {
+    throw new Error(`${kind} may not be a symlink: ${lexicalPath}\nRepository root: ${repoRoot}`);
+  }
+  return { path: lexicalPath, canonicalPath: existsSync(lexicalPath) ? realpathSync(lexicalPath) : null };
+}

package/src/migrate-prompts.mjs

@@ -6,6 +6,7 @@ import { getGitFirstAdded } from './git.mjs';
 import { bold, green, dim } from './color.mjs';
 import { readFileSync as rfs } from 'node:fs';
 import { fileURLToPath } from 'node:url';
+import { authorizeManagedSweep } from './managed-path.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(rfs(path.join(__dirname, '..', 'package.json'), 'utf8'));
@@ -124,6 +125,7 @@ export function runMigratePrompts(argv, config, opts = {}) {
   } else {
     files = findPromptCandidates(config);
   }
+  authorizeManagedSweep(files, config, { kind: 'Prompt migration source' });
 
   const results = [];
   let touched = 0;

package/src/migrate-template.mjs

@@ -4,6 +4,7 @@ import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { asString, toRepoPath, nowIso } from './util.mjs';
 import { collectDocFiles } from './index.mjs';
 import { bold, green, yellow, dim } from './color.mjs';
+import { authorizeManagedSweep } from './managed-path.mjs';
 
 const HEADING_RENAMES = [
   { from: /^##\s+Open questions\s*$/gm, to: '## Open Questions' },
@@ -117,6 +118,7 @@ export function runMigrateTemplate(argv, config, opts = {}) {
     files = collectDocFiles(config);
     if (!includeArchived) files = files.filter(f => !isInArchive(f, config));
   }
+  authorizeManagedSweep(files, config, { kind: 'Template migration source' });
 
   const results = [];
   let totalChanges = 0;

package/src/migrate.mjs

@@ -5,6 +5,7 @@ import { asString, toRepoPath, resolveDocPath, die } from './util.mjs';
 import { collectDocFiles } from './index.mjs';
 import { updateFrontmatter } from './lifecycle.mjs';
 import { bold, green, dim } from './color.mjs';
+import { authorizeManagedSweep } from './managed-path.mjs';
 
 export function runMigrate(argv, config, opts = {}) {
   const { dryRun } = opts;
@@ -38,7 +39,11 @@ export function runMigrate(argv, config, opts = {}) {
         matched.push(filePath);
         continue;
       }
-      const hits = allFiles.filter(f => f.includes(input) || path.basename(f).includes(input));
+      const normalizedInput = input.replaceAll('\\', '/');
+      const hits = allFiles.filter(f => {
+        const repoPath = toRepoPath(f, config.repoRoot);
+        return repoPath.includes(normalizedInput) || path.basename(f).includes(input);
+      });
       if (hits.length === 0) {
         unresolved.push(input);
       } else {
@@ -52,6 +57,7 @@ export function runMigrate(argv, config, opts = {}) {
   }
 
   const matches = [];
+  authorizeManagedSweep(fileFilter ? [...fileFilter] : allFiles, config, { kind: 'Migration source' });
 
   for (const filePath of allFiles) {
     if (fileFilter && !fileFilter.has(filePath)) continue;

package/src/new.mjs

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, writeFileSync, mkdirSync, fstatSync } from 'node:fs';
+import { existsSync, readFileSync, mkdirSync, fstatSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { toRepoPath, die, warn, nowIso, emitFilesFooter } from './util.mjs';
@@ -6,6 +6,8 @@ import { green, dim, bold } from './color.mjs';
 import { isInteractive, promptText } from './prompt.mjs';
 import { regenIndex } from './lifecycle.mjs';
 import { extractFrontmatter, parseSimpleFrontmatter, normalizeEol } from './frontmatter.mjs';
+import { authorizeManagedDestination } from './managed-path.mjs';
+import { createFileExclusive, mutateFileSet, MutationConflictError } from './atomic-mutation.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
@@ -281,6 +283,18 @@ export function readBodyInput(source) {
   return source;
 }
 
+export function readPipedBodyInput() {
+  try {
+    const stat = fstatSync(0);
+    const isWindowsPipe = process.platform === 'win32' && !process.stdin.isTTY;
+    if (stat.isFIFO() || stat.isFile() || stat.isSocket() || isWindowsPipe) {
+      const piped = readFileSync(0, 'utf8');
+      return piped.length > 0 ? piped : null;
+    }
+  } catch { /* stdin not introspectable */ }
+  return null;
+}
+
 // Slug/title helpers shared by name resolution and runlist child generation.
 export function slugify(s) {
   return s.toLowerCase().replace(/[\s_]+/g, '-').replace(/[^a-z0-9-]/g, '').replace(/-+/g, '-').replace(/^-|-$/g, '');
@@ -289,6 +303,48 @@ export function titleize(s) {
   return s.replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
 }
 
+export function preparePromptDocument(name, bodyInput, config, { plan = null, dryRun = false } = {}) {
+  const template = resolveTemplate('prompt', config);
+  const typeStatuses = config.typeStatuses?.get('prompt');
+  const status = template.defaultStatus && (!typeStatuses || typeStatuses.has(template.defaultStatus))
+    ? template.defaultStatus
+    : ([...(typeStatuses ?? [])][0] ?? 'pending');
+  if (!bodyInput?.trim()) die('`prompt` template requires a body.');
+  const slug = slugify(path.basename(name, '.md'));
+  const title = titleize(path.basename(name, '.md'));
+  let targetRoot = config.docsRoot;
+  let routed = false;
+  if (template.targetRoot) {
+    const match = (config.docsRoots || [config.docsRoot]).find(root => root.endsWith(template.targetRoot) || path.basename(root) === template.targetRoot);
+    if (match) { targetRoot = match; routed = true; }
+  }
+  const baseDir = template.dir && !routed ? path.join(targetRoot, template.dir) : targetRoot;
+  const filePath = path.join(baseDir, `${slug}.md`);
+  authorizeManagedDestination(filePath, config, { kind: 'Baton prompt destination' });
+  if (dryRun) return { slug, filePath, repoPath: toRepoPath(filePath, config.repoRoot), content: null };
+
+  const today = nowIso();
+  const split = splitBodyFrontmatter(bodyInput);
+  const body = split.frontmatter ? split.body : bodyInput;
+  const ctx = { status, title, today, bodyInput: body };
+  let content;
+  if (typeof template === 'function') {
+    content = template(name, ctx);
+    if (plan) {
+      const end = content.indexOf('\n---\n', 4);
+      if (!content.startsWith('---\n') || end === -1) throw new Error('Custom prompt template must return frontmatter for baton plan binding.');
+      const fm = mergeBodyFrontmatter(content.slice(4, end), { plan }, 'prompt');
+      content = `---\n${fm}${content.slice(end)}`;
+    }
+  } else {
+    let fm = template.frontmatter(status, today, ctx);
+    if (split.frontmatter) fm = mergeBodyFrontmatter(fm, split.frontmatter, 'prompt');
+    if (plan) fm = mergeBodyFrontmatter(fm, { plan }, 'prompt');
+    content = `---\n${fm}\n---\n${template.body(title, ctx)}`;
+  }
+  return { slug, filePath, repoPath: toRepoPath(filePath, config.repoRoot), content };
+}
+
 // Resolve one `--runlist` token to a scaffolded child plan: a bare slug becomes
 // `<hub>-NN-<slug>.md` (the documented runlist naming convention). `pos` is the
 // 1-based position used for the zero-padded NN prefix. Tokens must be bare slugs
@@ -642,16 +698,11 @@ export async function runNew(argv, config, opts = {}) {
     // delivers stdin as an AF_UNIX socket). Probe this even for templates that
     // don't accept bodies so the fail-fast guard below can reject accidental
     // heredoc/input instead of silently scaffolding without it.
-    try {
-      const stat = fstatSync(0);
-      if (stat.isFIFO() || stat.isFile() || stat.isSocket()) {
-        const piped = readFileSync(0, 'utf8');
-        if (piped.length > 0) {
-          bodyInput = piped;
-          bodyInputSource = 'piped stdin';
-        }
-      }
-    } catch { /* stdin not introspectable — skip auto-consume */ }
+    const piped = readPipedBodyInput();
+    if (piped !== null) {
+      bodyInput = piped;
+      bodyInputSource = 'piped stdin';
+    }
   }
 
   // If the body input has a leading `---…---` frontmatter block, lift its keys
@@ -757,6 +808,7 @@ export async function runNew(argv, config, opts = {}) {
   const baseDir = nameDir ? path.resolve(config.repoRoot, nameDir) : targetRoot;
   const filePath = path.join(baseDir, slug + '.md');
   const repoPath = toRepoPath(filePath, config.repoRoot);
+  const destinationAuthorization = authorizeManagedDestination(filePath, config, { kind: 'New document destination' });
 
   if (existsSync(filePath)) {
     die(`File already exists: ${repoPath}`);
@@ -766,40 +818,13 @@ export async function runNew(argv, config, opts = {}) {
 
   // Resolve runlist children from the hub slug (e.g. `extract` → hub-01-extract.md).
   const runlistChildren = runlistTokens.map((tok, i) => planChildFromToken(slug, tok, i + 1));
-  const childStatus = effective.has('planned') ? 'planned' : status;
-
-  // Generate content
-  let content;
-  const validSurfaces = config.raw?.taxonomy?.surfaces ?? (config.validSurfaces ? [...config.validSurfaces] : null);
-  const validModules = config.raw?.taxonomy?.modules ?? (config.validModules ? [...config.validModules] : null);
-  const tmplCtx = { status, title: docTitle, today, bodyInput, validSurfaces, validModules };
-  if (typeof template === 'function') {
-    content = template(name, tmplCtx);
-  } else {
-    let fm = template.frontmatter(status, today, tmplCtx);
-    if (bodyFrontmatter) fm = mergeBodyFrontmatter(fm, bodyFrontmatter, typeName);
-    // Inject the hub-shape frontmatter (runlist array / coordination marker)
-    // on top of the standard plan scaffold, then swap in a purpose-built body.
-    if (isRunlistHub) fm = mergeBodyFrontmatter(fm, { runlist: runlistChildren.map(c => c.file) }, typeName);
-    if (isCoordinationHub) fm = mergeBodyFrontmatter(fm, { execution_mode: 'coordination' }, typeName);
-    if (isRoadmap) fm = mergeBodyFrontmatter(fm, { execution_mode: 'roadmap' }, typeName);
-    let body;
-    // A full authored body (own `## Section` headings) wins over every variant
-    // skeleton too — otherwise the whole document gets nested in the builder's
-    // single slot and the skeleton is appended below it (duplicate Scope /
-    // Ranked queue / Version History). The default plan body applies the same
-    // shortcut inside template.body, so only the variant branches need it here.
-    const variantBody = isRunlistHub || isCoordinationHub || isRoadmap || isLite || isAudit;
-    const authored = variantBody ? fullBodyShortcut(docTitle, bodyInput) : null;
-    if (authored !== null) body = authored;
-    else if (isRunlistHub) body = runlistHubBody(docTitle, slug, runlistChildren, bodyInput, today);
-    else if (isCoordinationHub) body = coordinationHubBody(docTitle, bodyInput, today);
-    else if (isRoadmap) body = roadmapHubBody(docTitle, slug, bodyInput, today);
-    else if (isLite) body = litePlanBody(docTitle, bodyInput, today);
-    else if (isAudit) body = auditPlanBody(docTitle, bodyInput, today);
-    else body = template.body(docTitle, tmplCtx);
-    content = `---\n${fm}\n---\n${body}`;
+  for (const child of runlistChildren) {
+    authorizeManagedDestination(path.join(baseDir, child.file), config, {
+      root: destinationAuthorization.root,
+      kind: 'Runlist child destination',
+    });
   }
+  const childStatus = effective.has('planned') ? 'planned' : status;
 
   // When the project has >1 root and `--root` was omitted, surface the choice
   // so agents can see that an alternative root was available. Cheap visibility
@@ -820,34 +845,81 @@ export async function runNew(argv, config, opts = {}) {
     : isLite ? ' (lite plan)'
     : isAudit ? ' (audit plan)'
     : '';
+  const isCustomTemplate = Object.prototype.hasOwnProperty.call(config.raw?.templates ?? {}, typeName);
 
   if (dryRun) {
-    process.stdout.write(`${dim('[dry-run]')} Would create: ${repoPath}\n`);
+    if (isCustomTemplate) {
+      process.stdout.write(`${dim('[dry-run]')} Target: ${repoPath}\n`);
+      process.stdout.write(`${dim('[dry-run]')} Custom template rendering skipped; preview cannot confirm creation will succeed.\n`);
+    } else {
+      process.stdout.write(`${dim('[dry-run]')} Would create: ${repoPath}\n`);
+    }
     process.stdout.write(`${dim('[dry-run]')} Type: ${typeName}${hubKind}\n`);
     for (const c of runlistChildren) {
-      process.stdout.write(`${dim('[dry-run]')} Would create child: ${toRepoPath(path.join(baseDir, c.file), config.repoRoot)}\n`);
+      const childPath = path.join(baseDir, c.file);
+      const action = existsSync(childPath) ? 'Would leave existing child unchanged' : 'Would create child';
+      process.stdout.write(`${dim('[dry-run]')} ${action}: ${toRepoPath(childPath, config.repoRoot)}\n`);
     }
     if (rootHint) process.stdout.write(`${dim('[dry-run]')} ${rootHint}`);
     return;
   }
 
+  // Generate content only for a real create. Custom template functions are
+  // user code and may have side effects, so previews stop before invoking them.
+  let content;
+  const validSurfaces = config.raw?.taxonomy?.surfaces ?? (config.validSurfaces ? [...config.validSurfaces] : null);
+  const validModules = config.raw?.taxonomy?.modules ?? (config.validModules ? [...config.validModules] : null);
+  const tmplCtx = { status, title: docTitle, today, bodyInput, validSurfaces, validModules };
+  if (typeof template === 'function') {
+    content = template(name, tmplCtx);
+  } else {
+    let fm = template.frontmatter(status, today, tmplCtx);
+    if (bodyFrontmatter) fm = mergeBodyFrontmatter(fm, bodyFrontmatter, typeName);
+    if (isRunlistHub) fm = mergeBodyFrontmatter(fm, { runlist: runlistChildren.map(c => c.file) }, typeName);
+    if (isCoordinationHub) fm = mergeBodyFrontmatter(fm, { execution_mode: 'coordination' }, typeName);
+    if (isRoadmap) fm = mergeBodyFrontmatter(fm, { execution_mode: 'roadmap' }, typeName);
+    let body;
+    const variantBody = isRunlistHub || isCoordinationHub || isRoadmap || isLite || isAudit;
+    const authored = variantBody ? fullBodyShortcut(docTitle, bodyInput) : null;
+    if (authored !== null) body = authored;
+    else if (isRunlistHub) body = runlistHubBody(docTitle, slug, runlistChildren, bodyInput, today);
+    else if (isCoordinationHub) body = coordinationHubBody(docTitle, bodyInput, today);
+    else if (isRoadmap) body = roadmapHubBody(docTitle, slug, bodyInput, today);
+    else if (isLite) body = litePlanBody(docTitle, bodyInput, today);
+    else if (isAudit) body = auditPlanBody(docTitle, bodyInput, today);
+    else body = template.body(docTitle, tmplCtx);
+    content = `---\n${fm}\n---\n${body}`;
+  }
+
   // Ensure parent dir exists (templates with `dir:` may target a new subdirectory)
   mkdirSync(path.dirname(filePath), { recursive: true });
 
-  writeFileSync(filePath, content, 'utf8');
-  process.stdout.write(`${green('Created')}: ${repoPath} ${dim(`(${typeName}${hubKind})`)}\n`);
-  if (rootHint) process.stdout.write(dim(rootHint));
-
-  // Scaffold runlist child stubs. An existing child file is never clobbered.
   const childPaths = [];
+  const creations = [{ path: filePath, content }];
   for (const c of runlistChildren) {
     const childPath = path.join(baseDir, c.file);
     if (existsSync(childPath)) {
       warn(`Runlist child already exists, left as-is: ${toRepoPath(childPath, config.repoRoot)}`);
       continue;
     }
-    writeFileSync(childPath, runlistChildContent(c.title, slug, docTitle, childStatus, today), 'utf8');
+    creations.push({ path: childPath, content: runlistChildContent(c.title, slug, docTitle, childStatus, today) });
     childPaths.push(childPath);
+  }
+  try {
+    if (runlistChildren.length > 0) mutateFileSet({ creations }, { repoRoot: config.repoRoot, testHooks: opts.testHooks });
+    else createFileExclusive(filePath, content, { repoRoot: config.repoRoot, testHooks: opts.testHooks });
+  } catch (err) {
+    if (err instanceof MutationConflictError) die(`Could not create runlist atomically because a destination already exists: ${err.message}`);
+    throw err;
+  }
+  process.stdout.write(`${green('Created')}: ${repoPath} ${dim(`(${typeName}${hubKind})`)}\n`);
+  if (rootHint) process.stdout.write(dim(rootHint));
+
+  // Existing children discovered before the transaction are consistently left
+  // unchanged; absent children and the hub publish or roll back together.
+  for (const c of runlistChildren) {
+    const childPath = path.join(baseDir, c.file);
+    if (!childPaths.includes(childPath)) continue;
     process.stdout.write(`${green('Created')}: ${toRepoPath(childPath, config.repoRoot)} ${dim(`(plan · runlist child, ${childStatus})`)}\n`);
   }
 
@@ -873,15 +945,24 @@ export async function runNew(argv, config, opts = {}) {
     }
   } catch { /* git absent / not a repo — skip the note */ }
 
-  regenIndex(config);
+  const indexRegenerated = !opts.deferIndex ? regenIndex(config) : false;
 
   if (showFiles) {
     const touched = [filePath, ...childPaths];
-    if (config.indexPath) touched.push(config.indexPath);
+    if (config.indexPath && !opts.deferIndex) touched.push(config.indexPath);
     emitFilesFooter(touched, config);
   }
 
   try { config.hooks.onNew?.({ path: repoPath, status, title: docTitle, type: typeName }); } catch (err) { warn(`Hook 'onNew' threw: ${err.message}`); }
+  const sessionLocal = typeName === 'prompt';
+  return {
+    operation: 'new',
+    repositoryFiles: sessionLocal ? [] : [repoPath, ...childPaths.map(item => toRepoPath(item, config.repoRoot))],
+    sessionFiles: sessionLocal ? [repoPath] : [],
+    generatedFiles: config.indexPath && indexRegenerated ? [toRepoPath(config.indexPath, config.repoRoot)] : [],
+    deferredGeneratedFiles: config.indexPath && opts.deferIndex ? [toRepoPath(config.indexPath, config.repoRoot)] : [],
+    path: repoPath,
+  };
 }
 
 function resolveTemplate(name, config) {