runlist 0.0.0 → 0.94.2

package/src/new.mjs

@@ -0,0 +1,1321 @@
+import { applyTemplateOverride, readTemplateStore, templateFile } from './template-store.mjs';
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, mkdirSync, fstatSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runNewDecision } from './decision.mjs';
+import { toRepoPath, die, warn, nowIso, emitFilesFooter } from './util.mjs';
+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'));
+
+// Surface-taxonomy hint emitted above the `surfaces:` line in scaffolded docs.
+// Discoverable-by-default: the author sees valid values without leaving the file
+// and without grepping sibling docs (issue #12 trap 1). When the project has no
+// configured taxonomy, fall back to a bare `surfaces:` line.
+function surfacesScaffold(ctx) {
+  const valid = ctx?.validSurfaces;
+  if (Array.isArray(valid) && valid.length > 0) {
+    return `# surfaces — valid: ${valid.join(', ')}\nsurfaces:`;
+  }
+  return 'surfaces:';
+}
+
+// Module-taxonomy parallel of surfacesScaffold. When `taxonomy.modules` is set,
+// scaffold lists valid values + a `- none` placeholder so the validator's
+// modules-required check passes by default and the author can swap to a real
+// module from the listed taxonomy. When unset, the project doesn't enumerate
+// modules — drop the placeholder entirely so new plans aren't sprinkled with a
+// meaningless sentinel.
+function modulesScaffold(ctx, kind /* 'doc' | 'plan' */) {
+  const valid = ctx?.validModules;
+  if (Array.isArray(valid) && valid.length > 0) {
+    const comment = kind === 'plan'
+      ? `# modules — valid: ${valid.join(', ')} (or \`none\` for tooling/infra plans)`
+      : `# modules — valid: ${valid.join(', ')} (or \`none\` for platform/infra docs)`;
+    return `${comment}\nmodules:\n  - none`;
+  }
+  return 'modules:';
+}
+
+// Full-body shortcut shared by the default plan scaffold and every plan body
+// variant (--lite / --audit / --runlist / --coordination hubs). When the
+// author's body input already carries its own `## Section` headings, it's a
+// complete body they wrote start-to-finish — return it verbatim (honoring a
+// leading `# Title`, otherwise prepending the scaffold title) rather than
+// nesting it inside the builder's single slot (`## Problem` / `## Scope`) and
+// appending skeleton sections after it. Without this, a full coordination/lite/
+// audit/runlist body got duplicated: the whole document landed under `## Scope`
+// and the skeleton's own `## Ranked queue` / `## Version History` were appended
+// below (leaving stray `## Closeout` etc.). Returns the verbatim body string,
+// or null when the input is section-content (no `## ` heading) and should flow
+// into the builder's slot as before.
+function fullBodyShortcut(title, bodyInput) {
+  const b = (bodyInput ?? '').trim();
+  if (!b || !/^##\s+\S/m.test(b)) return null;
+  const hasOwnTitle = /^#\s+\S/.test(b);
+  return hasOwnTitle ? `\n${b}\n` : `\n# ${title}\n\n${b}\n`;
+}
+
+function lexicallyInside(parent, child) {
+  return child === parent || child.startsWith(parent + path.sep);
+}
+
+// The default root for a type that doesn't name one of its own. This used to be
+// "whichever root is listed first", which drops a `doc` into `docs/plans` for
+// any project that lists its plans root first — the plan type's own root, for a
+// type that isn't a plan. When one configured root contains another it is
+// structurally the catch-all (`docs` holding `docs/plans` and `docs/adr`), so
+// prefer that; the deepest one, so a nested chain picks the most specific
+// container rather than the outermost. Single-root projects and flat sibling
+// roots have no catch-all to find and keep first-listed order.
+export function catchAllRoot(config) {
+  const roots = config.docsRoots ?? [config.docsRoot];
+  if (roots.length < 2) return config.docsRoot;
+  const containers = roots.filter(root => roots.some(other => other !== root && lexicallyInside(root, other)));
+  if (!containers.length) return config.docsRoot;
+  const depth = root => root.split(path.sep).length;
+  return containers.reduce((deepest, root) => depth(root) > depth(deepest) ? root : deepest);
+}
+
+const BUILTIN_TEMPLATES = {
+  doc: {
+    description: 'Reference doc, design note, module overview — build-up shape lite',
+    defaultStatus: 'active',
+    // Body input optional. When passed (inline / --body / @file / stdin),
+    // it lands in the Overview section. Without it, Overview is left blank
+    // and the user fills it in.
+    acceptsBody: true,
+    frontmatter: (s, d, ctx) => [
+      'type: doc',
+      `status: ${s}`,
+      `created: ${d}`,
+      `updated: ${d}`,
+      modulesScaffold(ctx, 'doc'),
+      surfacesScaffold(ctx),
+      'domain:',
+      'audience: internal',
+      'related_plans:',
+      'related_docs:',
+    ].join('\n'),
+    body: (t, ctx) => {
+      // Same full-body shortcut the plan templates use, and for the same
+      // reason: a body that already authors `## Section` headings is a complete
+      // document, not section-content for one slot. Nesting it under `## Overview`
+      // produced a second `# Title` under the scaffold's, a placeholder summary
+      // line above the author's own opening, and the skeleton's trailing
+      // sections after a document that had already ended.
+      const authored = fullBodyShortcut(t, ctx?.bodyInput);
+      if (authored !== null) return authored;
+      return `
+# ${t}
+
+> One-line summary of what this doc covers.
+
+## Overview
+
+${ctx?.bodyInput?.trim() ?? ''}
+
+## Version History
+
+- **${ctx?.today ?? ''}** Created.
+
+## Related Documentation
+
+`;
+    },
+  },
+  plan: {
+    description: 'Execution plan — build-up shape (Problem → Phases → Closeout) with phase status markers and Version History',
+    dir: 'plans',
+    targetRoot: 'plans',
+    // A scaffolded plan is scoped, not being worked; `runlist use` starts it.
+    // Defaulting to `active` forced a second, guarded status write for every
+    // plan that was only being written down.
+    defaultStatus: 'planned',
+    // Body input lands in the Problem section. Plans don't have an Overview;
+    // Problem is the established opening section in the build-up shape.
+    acceptsBody: true,
+    frontmatter: (s, d, ctx) => [
+      'type: plan',
+      `status: ${s}`,
+      `created: ${d}`,
+      `updated: ${d}`,
+      surfacesScaffold(ctx),
+      modulesScaffold(ctx, 'plan'),
+      'domain:',
+      'audience: internal',
+      'parent_plan:',
+      'related_plans:',
+      'related_docs:',
+      'current_state:',
+      'next_step:',
+    ].join('\n'),
+    body: (t, ctx) => {
+      // Full-body shortcut (shared with the plan variants): a body that already
+      // authors `## Section` headings is a complete plan the user/agent wrote
+      // start-to-finish — return it verbatim and drop the scaffold ladder.
+      const authored = fullBodyShortcut(t, ctx?.bodyInput);
+      if (authored !== null) return authored;
+      const bodyInput = ctx?.bodyInput?.trim() ?? '';
+      return `
+# ${t}
+
+> One-paragraph problem statement: what this plan is for, why now.
+
+## Problem
+
+${bodyInput}
+
+## Goals
+
+
+
+## Non-Goals
+
+
+
+## What Exists Today
+
+
+
+## Constraints
+
+
+
+## Decisions
+
+
+
+## Open Questions
+
+
+
+## Phases
+
+<!--
+Status markers (put in heading text):
+  ⬜  not started
+  🟡  in progress (pickup targets this)
+  ✅  shipped (history; pickup skips)
+  ⏭  skipped (with reason in body)
+  🚧  blocked (link to blocker)
+-->
+
+### Phase 1 — <title> ⬜
+
+
+
+## Deferred
+
+
+
+## Version History
+
+- **${ctx?.today ?? ''}** Created.
+
+## Closeout
+
+<!-- Filled on archive: what shipped, key commits, deferrals dispositioned. -->
+`;
+    },
+  },
+  prompt: {
+    description: 'Saved prompt to seed a future Claude session — body is required',
+    dir: 'prompts',
+    targetRoot: 'prompts',
+    defaultStatus: 'pending',
+    requiresBody: true,
+    acceptsBody: true,
+    frontmatter: (s, d, ctx) => [
+      'type: prompt',
+      `status: ${s}`,
+      `created: ${d}`,
+      `updated: ${d}`,
+      `runlist_version: ${pkg.version}`,
+      `context: ${ctx?.title ? `"${ctx.title.replace(/"/g, '\\"')}"` : ''}`,
+      'related_plans:',
+    ].join('\n'),
+    body: (t, ctx) => `\n${ctx?.bodyInput ?? '<!-- prompt body -->'}\n`,
+  },
+};
+
+// Body inputs from agents often arrive as a full document (frontmatter + body)
+// written to a tempfile and passed via `@path` or stdin. Without this split,
+// `runlist new` would prepend its scaffold frontmatter and treat the input's
+// frontmatter as literal body content — resulting in two `---` blocks and a
+// duplicated title. We instead parse the leading block (if any), merge its
+// keys onto the scaffold, and use only what follows as body. See issue #12
+// trap 4. Returns `{ frontmatter: object|null, body: string }`.
+function splitBodyFrontmatter(rawBody) {
+  if (!rawBody || typeof rawBody !== 'string') return { frontmatter: null, body: rawBody };
+  if (!normalizeEol(rawBody).startsWith('---\n')) return { frontmatter: null, body: rawBody };
+  const { frontmatter: fmText, body } = extractFrontmatter(rawBody);
+  if (!fmText) return { frontmatter: null, body: rawBody };
+  const parsed = parseSimpleFrontmatter(fmText);
+  return { frontmatter: parsed, body };
+}
+
+// Serialize a single frontmatter key/value pair to a YAML block. Mirrors the
+// scaffold's shape so merged output reads naturally next to scaffold defaults.
+function serializeScalar(value) {
+  if (typeof value !== 'string') return String(value);
+  return !value || /^[\s>|'"\[\]{},&*!%#@`]/.test(value) || /[:#\n\r\t\\]/.test(value) || /^(?:true|false|null)$/i.test(value)
+    ? JSON.stringify(value) : value;
+}
+
+function serializeFmEntry(key, value) {
+  if (value === null || value === undefined || value === '') return `${key}:`;
+  if (Array.isArray(value)) {
+    if (value.length === 0) return `${key}:`;
+    return `${key}:\n${value.map(v => `  - ${serializeScalar(v)}`).join('\n')}`;
+  }
+  if (typeof value === 'string' && value.includes('\n')) {
+    const indented = value.split('\n').map(l => `  ${l}`).join('\n');
+    return `${key}: |\n${indented}`;
+  }
+  return `${key}: ${serializeScalar(value)}`;
+}
+
+// Replace each key in `overrides` within the scaffold-generated frontmatter
+// string. Keys not present in the scaffold are appended. `type:` is never
+// overwritten — the CLI's type arg wins (warning emitted on conflict).
+function mergeBodyFrontmatter(scaffoldFm, overrides, cliType) {
+  if (!overrides || Object.keys(overrides).length === 0) return scaffoldFm;
+  let fm = scaffoldFm;
+  const appended = [];
+  for (const [key, value] of Object.entries(overrides)) {
+    if (key === 'type') {
+      if (cliType && value && value !== cliType) {
+        warn(`Body frontmatter declares \`type: ${value}\` but CLI arg is \`${cliType}\`; using \`${cliType}\`.`);
+      }
+      continue;
+    }
+    if (key === 'created' || key === 'updated') continue; // scaffold owns timestamps
+    const serialized = serializeFmEntry(key, value);
+    // Match `key:` line + any indented continuation (block-array items or
+    // block-scalar bodies). Indented lines start with whitespace; scaffold keys
+    // never do, so this consumes only the right slice.
+    const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const re = new RegExp(`^${escaped}:.*(\\n[ \\t]+.*)*`, 'm');
+    if (re.test(fm)) {
+      fm = fm.replace(re, serialized);
+    } else {
+      appended.push(serialized);
+    }
+  }
+  if (appended.length > 0) fm = fm + '\n' + appended.join('\n');
+  return fm;
+}
+
+// Metavariables that ship in help text, `runlist baton`'s signature, and the
+// wrap-up nudge. Agents copy them verbatim, and the bare `Body file not found:
+// draft` that resulted read like a missing file rather than an unsubstituted
+// placeholder — so the retry was usually another guess at the path. Only
+// consulted after existsSync fails, so a real file by any of these names wins.
+const BODY_PLACEHOLDER_NAMES = new Set([
+  'draft', 'draft.md', '/tmp/draft.md', 'tmp/draft.md',
+  '/tmp/baton.md', '/tmp/my-draft.md',
+  'path', 'file', 'body', 'FILE', 'PATH', 'BODY',
+]);
+
+function isBodyPlaceholder(file) {
+  if (/^<.+>$/.test(file)) return true; // <draft-file>, <path>, …
+  return BODY_PLACEHOLDER_NAMES.has(file);
+}
+
+// `@-` is the natural composition of the two spellings runlist documents (`@path`
+// and `-`), and agents write it — three times in the platform transcripts, each
+// with a valid heredoc already on stdin that was then thrown away for a file
+// literally named `-`. Nothing else can sensibly be meant by it, so it means
+// stdin, unconditionally. That follows the universal CLI convention rather than
+// the placeholder rule below (where a real file wins): under this convention a
+// file actually named `-` is spelled `./-`, which still takes the file branch.
+export function readBodyInput(source) {
+  if (source === '-' || source === '@-') {
+    try { return readFileSync(0, 'utf8'); } catch (err) { die(`Could not read body from stdin: ${err.message}`); }
+  }
+  if (typeof source === 'string' && source.startsWith('@')) {
+    const file = source.slice(1);
+    if (!existsSync(file)) {
+      if (isBodyPlaceholder(file)) {
+        die(`\`@${file}\` is a placeholder, not a real path — write the body to a file first, then pass it:\n` +
+          `  @/tmp/my-draft.md   read the body from that file\n` +
+          `  -                   read the body from stdin (\`cat notes.md | runlist …\`)\n` +
+          `  --message "..."     short one-liners only`);
+      }
+      die(`Body file not found: ${file}`);
+    }
+    return readFileSync(file, 'utf8');
+  }
+  return source;
+}
+
+// An agent's shell can hand a command a pipe that is open and never written or
+// closed (Claude Code does for chained and backgrounded commands), so a plain
+// blocking read of an implicit pipe hangs until the tool times out: a bare
+// `runlist baton` sat there for two minutes in the platform transcripts. A
+// child reads the pipe instead and gives up when the first byte doesn't arrive
+// within the window; once data starts it waits for EOF, so a slow producer that
+// has begun writing is never cut off.
+export const PIPED_STDIN_IDLE_MS = 1500;
+const STDIN_SILENT_EXIT = 3;
+const PIPE_READER = `let d='',got=false;` +
+  `const t=setTimeout(()=>{if(!got)process.exit(${STDIN_SILENT_EXIT})},Number(process.argv[1]));` +
+  `process.stdin.setEncoding('utf8');` +
+  `process.stdin.on('data',c=>{got=true;d+=c});` +
+  `process.stdin.on('end',()=>{clearTimeout(t);process.stdout.write(d)});`;
+
+function readPipeUnlessSilent() {
+  const r = spawnSync(process.execPath, ['-e', PIPE_READER, String(PIPED_STDIN_IDLE_MS)], {
+    stdio: [0, 'pipe', 'ignore'],
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+    windowsHide: true,
+  });
+  if (r.status !== 0) return null;
+  return r.stdout;
+}
+
+export function readPipedBodyInput() {
+  try {
+    const stat = fstatSync(0);
+    if (stat.isFile()) {
+      const redirected = readFileSync(0, 'utf8');
+      return redirected.length > 0 ? redirected : null;
+    }
+    const isWindowsPipe = process.platform === 'win32' && !process.stdin.isTTY;
+    if (stat.isFIFO() || stat.isSocket() || isWindowsPipe) {
+      const piped = readPipeUnlessSilent();
+      return piped ? 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, '');
+}
+export function titleize(s) {
+  return s.replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+}
+
+// Where saved prompts are written: the prompt template's targetRoot when a
+// root matches it, else the primary root plus the template's `dir`.
+export function promptDirectory(config, template = resolveTemplate('prompt', config)) {
+  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; }
+  }
+  return template.dir && !routed ? path.join(targetRoot, template.dir) : targetRoot;
+}
+
+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'));
+  const filePath = path.join(promptDirectory(config, template), `${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
+// — a path is rejected (wiring an ordered hub to a plan that already lives
+// elsewhere needs a hub-relative ref, so it's a hand-edit, not a scaffold).
+function planChildFromToken(hubSlug, token, pos) {
+  const t = token.trim();
+  if (t.includes('/') || t.includes(path.sep)) {
+    die(`Runlist child "${token}" must be a bare slug, not a path. To put an existing plan in the runlist, add it to the hub's runlist: by hand.`);
+  }
+  const childSlug = slugify(t.replace(/\.md$/, ''));
+  if (!childSlug) die(`Runlist child token resolves to an empty slug: "${token}"`);
+  const nn = String(pos).padStart(2, '0');
+  return { file: `${hubSlug}-${nn}-${childSlug}.md`, title: titleize(t.replace(/\.md$/, '')) };
+}
+
+// Body for a sprint runlist hub: the children ARE the phases, so the heavy
+// generic plan scaffold (Goals/Phases/Deferred/…) is replaced by an ordered
+// `## Order of operations` list that mirrors the `runlist:` frontmatter.
+function runlistHubBody(title, hubSlug, children, bodyInput, today) {
+  const steps = children
+    .map((c, i) => `${i + 1}. [${c.title}](${c.file}) ⬜`)
+    .join('\n');
+  const n = children.length;
+  return `
+# ${title}
+
+> One-paragraph problem statement: what this ordered hub sprints toward, why now.
+> The plans below are ordered on this hub; no separate runlist document is needed.
+
+## Problem
+
+${bodyInput?.trim() ?? ''}
+
+## Order of Operations
+
+${steps}
+
+Pick up the next child with \`runlist runlist next ${hubSlug}\` — it targets the
+first startable child, skipping archived and parked plans.
+\`runlist runlist ${hubSlug}\` shows the sequence + status.
+
+## Version History
+
+- **${today}** Created (ordered hub, ${n} ${n === 1 ? 'child' : 'children'}).
+`;
+}
+
+// Body for a coordination hub: prose-first domain map with a ranked-queue table.
+// Mirrors the `execution_mode: coordination` shape `runlist runlists` reads.
+function coordinationHubBody(title, bodyInput, today) {
+  return `
+# ${title}
+
+> One-paragraph: the domain this hub coordinates and how to read the queue below.
+> Older docs call this organizing document a runlist. Plans and supporting docs
+> belong to this hub; the ranked queue gives its plans an execution order.
+
+## Scope
+
+${bodyInput?.trim() ?? ''}
+
+## Ranked Queue
+
+<!-- One row per coordinated plan, in pickup order; the gating column explains
+dependencies. Wire each plan into related_plans: so the "N related" count and
+graph pick it up. -->
+
+| # | Plan | Why / gating | Status |
+|---|------|--------------|--------|
+| 1 | \`<plan>.md\` | | |
+
+## Version History
+
+- **${today}** Created (coordination hub).
+`;
+}
+
+// Body for an optional roadmap hub that collects other hubs and rolls their
+// progress up. Children are wired via related_plans:; direct plans are supported.
+function roadmapHubBody(title, hubSlug, bodyInput, today) {
+  return `
+# ${title}
+
+> One-paragraph: the domain this roadmap coordinates. A roadmap is an optional
+> hub collecting other hubs (called runlists in older docs) and rolling up their
+> progress. Direct plan children are also supported — see \`runlist roadmap ${hubSlug}\`.
+
+## Scope
+
+${bodyInput?.trim() ?? ''}
+
+## Runlists
+
+<!-- One row per child hub or direct plan, in priority order. Wire each into
+related_plans: so the rollup + graph pick it up. This table's Runlists label
+means hubs: coordination maps, ordered hubs or other roadmap hubs.
+Optional horizon flavor: replace this table with ## Now / ## Next / ## Later /
+## Icebox sections, each linking the hubs or plans in that horizon. -->
+
+| # | Runlist | Why / gating | Progress |
+|---|---------|--------------|----------|
+| 1 | \`<name>-runlist.md\` | | |
+
+## Version History
+
+- **${today}** Created (roadmap hub).
+`;
+}
+
+// Body for a `--lite` plan: the full build-up scaffold (Goals / Non-Goals /
+// What Exists Today / Constraints / Decisions / Open Questions / Deferred /
+// Closeout) is stripped down to the essentials — Problem → Phases → Version
+// History — for a quick plan that doesn't need the full ceremony.
+function litePlanBody(title, bodyInput, today) {
+  return `
+# ${title}
+
+> One-paragraph problem statement: what this plan is for, why now.
+
+## Problem
+
+${bodyInput?.trim() ?? ''}
+
+## Phases
+
+<!-- Status markers in heading text: ⬜ not started · 🟡 in progress (pickup
+targets this) · ✅ shipped · ⏭ skipped · 🚧 blocked. -->
+
+### Phase 1 — <title> ⬜
+
+
+
+## Version History
+
+- **${today}** Created.
+`;
+}
+
+// Body for an `--audit` plan: the recurring "investigated X, here's what I
+// found" shape — ranked findings with impact tags, a suggested order to act on
+// them, and open questions. The build-up phases scaffold doesn't fit audits
+// (e.g. the onboarding audit), which is why this shape recurs by hand.
+function auditPlanBody(title, bodyInput, today) {
+  return `
+# ${title}
+
+> One-paragraph: what was audited, and the headline finding.
+
+## Problem
+
+${bodyInput?.trim() ?? ''}
+
+## Findings (Ranked)
+
+### 1. <finding> [impact]
+
+
+
+### 2. <finding> [impact]
+
+
+
+## Suggested Order
+
+1. <which finding to act on first, and why>
+
+## Open Questions
+
+
+
+## Version History
+
+- **${today}** Created (audit).
+`;
+}
+
+// Minimal child plan stub for a scaffolded runlist child. parent_plan points
+// back at the hub (same dir) so \`runlist doctor\` is satisfied and the reverse
+// link/graph work; status starts `planned` (queued behind the hub).
+export function runlistChildContent(childTitle, hubSlug, hubTitle, childStatus, today) {
+  return `---
+type: plan
+status: ${childStatus}
+created: ${today}
+updated: ${today}
+parent_plan: ${hubSlug}.md
+related_plans:
+current_state:
+next_step:
+---
+
+# ${childTitle}
+
+> Plan in the ordered hub [${hubTitle}](${hubSlug}.md).
+
+## Problem
+
+
+
+## Version History
+
+- **${today}** Created (child plan of hub ${hubSlug}).
+`;
+}
+
+export async function runNew(argv, config, opts = {}) {
+  const { dryRun } = opts;
+
+  if (argv.find(a => !a.startsWith('-')) === 'decision') return runNewDecisionArgs(argv, config, opts);
+
+  const knownTypes = new Set(Object.keys(BUILTIN_TEMPLATES));
+  // Also include any custom templates from config
+  for (const k of Object.keys(config.raw?.templates ?? {})) knownTypes.add(k);
+  // `hub` is a plan with a hub body; `decision` is handled above.
+  knownTypes.add('hub');
+  knownTypes.add('decision');
+
+  const hasNameForBody = args => {
+    if (args.length >= 2 && knownTypes.has(args[0])) return true;
+    if (args.length >= 1 && !knownTypes.has(args[0])) return true;
+    return false;
+  };
+
+  // Parse args. Pull out flags first.
+  const positional = [];
+  let status = null;
+  let title = null;
+  let rootName = opts.root ?? null;
+  let bodyFlag = null;
+  let bodyFlagName = null; // tracks which spelling the caller used, for error attribution
+  let showFiles = opts.showFiles ?? false;
+  let runlistArg = null;     // --runlist a,b,c  → sprint hub + child stubs
+  let coordination = false;  // --coordination   → coordination hub skeleton
+  let roadmap = false;       // --roadmap        → roadmap hub skeleton
+  let lite = false;          // --lite/--minimal → trimmed plan body
+  let renderPreview = false;
+  let audit = false;         // --audit/--findings → ranked-findings plan body
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--render-preview') { renderPreview = true; continue; }
+    if (argv[i] === '--status' && argv[i + 1]) { status = argv[++i]; continue; }
+    if (argv[i] === '--title' && argv[i + 1]) { title = argv[++i]; continue; }
+    if (argv[i] === '--runlist' && argv[i + 1]) { runlistArg = argv[++i]; continue; }
+    if (argv[i] === '--coordination') { coordination = true; continue; }
+    if (argv[i] === '--roadmap') { roadmap = true; continue; }
+    if (argv[i] === '--lite' || argv[i] === '--minimal') { lite = true; continue; }
+    if (argv[i] === '--audit' || argv[i] === '--findings') { audit = true; continue; }
+    // --body is the canonical flag; --message is a back-compat alias.
+    if ((argv[i] === '--body' || argv[i] === '--message') && argv[i + 1]) {
+      bodyFlagName = argv[i];
+      bodyFlag = argv[++i];
+      continue;
+    }
+    if (argv[i] === '--root' && argv[i + 1]) { rootName = argv[++i]; continue; }
+    if (argv[i] === '--config') { i++; continue; }
+    if (argv[i] === '--show-files') { showFiles = true; continue; }
+    if (argv[i] === '--list-templates' || argv[i] === '--list-types') {
+      listTemplates(config);
+      return;
+    }
+    // Treat `-` alone (stdin marker) as a positional, not a flag.
+    // Once the type/name have been collected, a positional body may itself
+    // start with `---` frontmatter. Preserve it instead of dropping it as an
+    // unknown flag; the leading frontmatter merge below will handle it.
+    if (!argv[i].startsWith('-') || argv[i] === '-' || hasNameForBody(positional)) positional.push(argv[i]);
+  }
+
+  // Resolve type vs name:
+  //   `runlist new plan auth-revamp`     → type=plan, name=auth-revamp
+  //   `runlist new auth-revamp`          → type=doc (default), name=auth-revamp
+  //   `runlist new prompt foo "body"`    → type=prompt, name=foo, bodyArg="body"
+  let typeName, name, bodyArg = null;
+  if (positional.length >= 1 && knownTypes.has(positional[0])) {
+    typeName = positional[0];
+    name = positional[1];
+    if (positional.length > 2) bodyArg = positional.slice(2).join(' ');
+  } else {
+    // `new <name> <inline body>` is a doc with the type left out, but a single
+    // bare word in the body slot is almost always a mistyped type and a slug
+    // (`new decison foo`), which used to create `<type-name>.md` with the slug
+    // as its whole body.
+    const [first, second] = positional;
+    if (positional.length === 2 && !/[/\\]|\.md$/.test(first) && /^[A-Za-z][\w.-]*$/.test(second)) {
+      die(`Unknown type \`${first}\`. Types: ${[...knownTypes].join(', ')}.\n`
+        + `For a doc named ${first} with "${second}" as its body, run: runlist new doc ${first} "${second}"`);
+    }
+    typeName = 'doc';
+    name = positional[0];
+    if (positional.length > 1) bodyArg = positional.slice(1).join(' ');
+  }
+
+  // A hub is a plan with a hub body. Coordination is the default shape, being
+  // the one a hub without children or tiers has.
+  if (typeName === 'hub') {
+    typeName = 'plan';
+    if (runlistArg === null && !roadmap) coordination = true;
+  }
+
+  if (!name) {
+    if (isInteractive()) {
+      name = await promptText(`${typeName} name: `);
+      if (!name) die('No name provided.');
+    } else {
+      die(`Usage: runlist new <type> <name> [body]\n       types: ${[...knownTypes].join(', ')}\n       body: inline text | piped stdin (auto) | "@path" (file) | --body "..."`);
+    }
+  }
+
+  // Resolve template (by type name, falls back to lookup)
+  const template = resolveTemplate(typeName, config);
+
+  // Validate status. The template's `defaultStatus` is only used when it's
+  // actually valid in the user's per-type config — otherwise fall back to the
+  // first valid type status. This avoids the "Invalid status `active` for type
+  // `doc`" loop when a project overrides doc statuses to exclude 'active'.
+  if (!status) {
+    const typeStatuses = config.typeStatuses?.get(typeName);
+    const tmplDefault = (typeof template === 'object' && template.defaultStatus) ? template.defaultStatus : null;
+    if (tmplDefault && (!typeStatuses || typeStatuses.size === 0 || typeStatuses.has(tmplDefault))) {
+      status = tmplDefault;
+    } else if (typeStatuses && typeStatuses.size > 0) {
+      status = [...typeStatuses][0];
+    } else {
+      status = tmplDefault ?? 'active';
+    }
+  }
+  const effective = config.typeStatuses?.get(typeName) ?? config.validStatuses;
+  if (!effective.has(status)) {
+    die(`Invalid status \`${status}\` for type \`${typeName}\`\nValid: ${[...effective].join(', ')}`);
+  }
+
+  // Runlist/coordination hubs and the --lite/--audit variants are all plan
+  // *body shapes*, not separate types. Guard them to type plan and reject any
+  // combination — a plan has exactly one body shape (a sprint `runlist:` array,
+  // a prose-first coordination map, a trimmed lite plan, or a ranked-findings
+  // audit are mutually exclusive).
+  const isRunlistHub = runlistArg !== null;
+  const isCoordinationHub = coordination;
+  const isRoadmap = roadmap;
+  const isLite = lite;
+  const isAudit = audit;
+  const planShapes = [
+    ['--runlist', isRunlistHub],
+    ['--coordination', isCoordinationHub],
+    ['--roadmap', isRoadmap],
+    ['--lite', isLite],
+    ['--audit', isAudit],
+  ].filter(([, on]) => on);
+  if (planShapes.length > 0 && typeName !== 'plan') {
+    const flag = planShapes[0][0];
+    const usage = flag === '--runlist' ? '--runlist a,b,c' : flag;
+    die(`${flag} only applies to plans. Use: runlist new plan <name> ${usage}`);
+  }
+  if (planShapes.length > 1) {
+    die(`${planShapes.map(([f]) => f).join(' and ')} are mutually exclusive — a plan has one body shape. Pick one.`);
+  }
+  const runlistTokens = isRunlistHub
+    ? runlistArg.split(',').map(s => s.trim()).filter(Boolean)
+    : [];
+  if (isRunlistHub && runlistTokens.length === 0) {
+    die('--runlist needs at least one child, e.g. --runlist extract,rewrite,cleanup');
+  }
+
+  // Body input resolution: --body flag > positional bodyArg > auto-piped-stdin > nothing
+  let bodyInput = null;
+  let bodyInputSource = null;
+  if (bodyFlag !== null) { bodyInput = readBodyInput(bodyFlag); bodyInputSource = bodyFlagName; }
+  else if (bodyArg !== null) {
+    bodyInput = readBodyInput(bodyArg);
+    bodyInputSource = (bodyArg === '-' || bodyArg === '@-')
+      ? `stdin (\`${bodyArg}\`)`
+      : (bodyArg.startsWith('@') ? `file (\`${bodyArg}\`)` : 'inline body argument');
+  } else {
+    // Auto-consume piped or redirected stdin so agents don't need the `-`
+    // placeholder for the most common pattern (`cat draft.md | runlist new …`,
+    // `runlist new … < draft.md`, or a `<<'EOF'` heredoc). We probe stdin via
+    // fstatSync rather than `!isTTY` so a closed/inherited fd doesn't trigger
+    // a blocking read of an empty stream. We accept FIFO (shell pipes), regular
+    // file (shell redirection / heredoc), and socket (Node spawnSync `input:`
+    // 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.
+    const piped = readPipedBodyInput();
+    if (piped !== null) {
+      bodyInput = piped;
+      bodyInputSource = 'piped stdin';
+    }
+  }
+
+  // If the body input has a leading `---…---` frontmatter block, lift its keys
+  // out so they override scaffold defaults; only the content after the closing
+  // `---` is treated as body. The natural agent pattern is to draft a full doc
+  // to a tempfile and pass `@path` — without this, the scaffold ends up with
+  // two `---` blocks. See issue #12 trap 4.
+  let bodyFrontmatter = null;
+  if (bodyInput !== null) {
+    const split = splitBodyFrontmatter(bodyInput);
+    if (split.frontmatter) {
+      bodyFrontmatter = split.frontmatter;
+      bodyInput = split.body;
+    }
+  }
+
+  if (template.requiresBody && (!bodyInput || !bodyInput.trim())) {
+    die(`\`${typeName}\` template requires a body. Pipe stdin (\`cat draft.md | runlist new ${typeName} <slug>\`), pass @path, --body "...", or inline text.`);
+  }
+
+  // Fail-fast when the user passes body input to a template that doesn't
+  // consume it — silently discarding heredoc content is the worst UX.
+  // Templates opt in via `acceptsBody: true` or `requiresBody: true`.
+  if (bodyInput !== null && !template.acceptsBody && !template.requiresBody) {
+    const configTemplates = config.raw?.templates ?? {};
+    // Compute the accepting list from the RESOLVED set (config merged over
+    // built-ins) so the hint doesn't contradict the rejection.
+    const resolvedNames = new Set([...Object.keys(BUILTIN_TEMPLATES), ...Object.keys(configTemplates)]);
+    const accepting = [...resolvedNames]
+      .filter(n => n !== typeName)
+      .filter(n => {
+        const t = resolveTemplate(n, config);
+        return t.acceptsBody || t.requiresBody;
+      });
+    const hint = accepting.length > 0
+      ? ` Templates that accept body input: ${accepting.join(', ')}.`
+      : '';
+
+    // Override-of-builtin diagnosis: the most common cause is a project
+    // runlist.config.mjs that copy-pasted a stripped-down `plan` template
+    // and dropped the body-acceptance contract. Name that explicitly so
+    // an agent can self-fix without spelunking the config.
+    const builtin = BUILTIN_TEMPLATES[typeName];
+    const isOverride = Boolean(configTemplates[typeName] && builtin);
+    const builtinAccepts = Boolean(builtin && (builtin.acceptsBody || builtin.requiresBody));
+    let cause;
+    if (isOverride && builtinAccepts) {
+      const where = config.configPath ? toRepoPath(config.configPath, config.repoRoot) : 'runlist.config.mjs';
+      cause = `Your config (${where}) overrides the built-in \`${typeName}\` template, and the override drops body acceptance.\nFix: in that override, add \`acceptsBody: true\` AND interpolate \`\${ctx?.bodyInput?.trim() ?? ''}\` into your \`body\` fn (e.g., inside \`## Problem\`). Or drop the override to use the built-in.`;
+    } else {
+      cause = `Either drop the body, switch to a template that accepts it, or set \`acceptsBody: true\` on your custom \`${typeName}\` template in runlist.config.mjs.`;
+    }
+    die(`\`${typeName}\` template does not accept body input, but body was passed via ${bodyInputSource}.${hint}\n${cause}`);
+  }
+
+  // If name contains path separators, split into directory prefix and basename
+  let nameDir = null;
+  let namePart = name;
+  if (name.includes('/') || name.includes(path.sep)) {
+    nameDir = path.dirname(name);
+    namePart = path.basename(name, '.md');
+  } else if (name.endsWith('.md')) {
+    namePart = name.slice(0, -3);
+  }
+  // A prefix the *user* typed and one a template declares resolve differently
+  // below, so the distinction has to survive the template's assignment to nameDir.
+  const userNameDir = nameDir;
+
+  // Slugify
+  const slug = namePart.toLowerCase().replace(/[\s_]+/g, '-').replace(/[^a-z0-9-]/g, '').replace(/-+/g, '-').replace(/^-|-$/g, '');
+  if (!slug) { die('Name resolves to empty slug: ' + name); }
+
+  // Title
+  const docTitle = title ?? namePart.replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+
+  // Resolve target root. Precedence: CLI --root > template.targetRoot > config.docsRoot.
+  // When the chosen root is a first-class type-container (matched by --root or targetRoot),
+  // we skip the `template.dir` join — the root already points at the right directory.
+  let targetRoot = catchAllRoot(config);
+  let routedToTypeRoot = false;
+  if (rootName) {
+    const roots = config.docsRoots || [config.docsRoot];
+    const match = roots.find(r => r.endsWith(rootName) || path.basename(r) === rootName);
+    if (!match) {
+      const available = roots.map(r => path.basename(r)).join(', ');
+      die(`Unknown root: ${rootName}\nAvailable: ${available}`);
+    }
+    targetRoot = match;
+    routedToTypeRoot = true;
+  } else if (typeof template === 'object' && template.targetRoot) {
+    const roots = config.docsRoots || [config.docsRoot];
+    const match = roots.find(r => r.endsWith(template.targetRoot) || path.basename(r) === template.targetRoot);
+    if (match) {
+      targetRoot = match;
+      routedToTypeRoot = true;
+    }
+  }
+
+  // Template-declared subdirectory (e.g., prompt → 'prompts') — only relevant when we
+  // didn't already land in a type-specific root via --root or targetRoot.
+  if (typeof template === 'object' && template.dir && !nameDir && !routedToTypeRoot) {
+    nameDir = path.join(path.relative(config.repoRoot, targetRoot), template.dir);
+  }
+
+  // Path — a directory prefix is read relative to the repo, because `runlist new
+  // plan docs/plans/feature` is a full repo path and has to stay one. That was
+  // the ONLY reading, which is how `--root` came to be silently ignored the
+  // moment a name contained a slash: the block above picked a root and this line
+  // threw it away, so the one flag the out-of-root error advertises could not
+  // fix the error. With an explicit --root the prefix is now read relative to
+  // that root — unless the repo-relative reading already lands inside it, so
+  // full paths keep working.
+  const allRoots = config.docsRoots ?? [config.docsRoot];
+  let baseDir;
+  if (!nameDir) baseDir = targetRoot;
+  else if (userNameDir && rootName) {
+    const repoRelative = path.resolve(config.repoRoot, nameDir);
+    baseDir = lexicallyInside(targetRoot, repoRelative) ? repoRelative : path.resolve(targetRoot, nameDir);
+  } else baseDir = path.resolve(config.repoRoot, nameDir);
+  const filePath = path.join(baseDir, slug + '.md');
+  const repoPath = toRepoPath(filePath, config.repoRoot);
+
+  // Without --root there is nothing to disambiguate with, so a prefix pointing
+  // outside every root stays an error — but it names the flag that resolves it,
+  // and the flag now works. The generic containment error underneath reports
+  // absolute paths and no remedy, which is what agents kept re-guessing at.
+  //
+  // Gated on the remedy actually working: the suggestion is only offered when
+  // `--root` would land the file inside that root. That is what keeps this off
+  // a traversal (`../escaped`, an absolute path), where `--root` fixes nothing
+  // and the containment check below is the error that should speak — printing
+  // an untested remedy is the very defect this finding is about.
+  if (userNameDir && !rootName && !allRoots.some(root => lexicallyInside(root, filePath))) {
+    const rooted = path.resolve(targetRoot, userNameDir, slug + '.md');
+    if (lexicallyInside(targetRoot, rooted)) {
+      die(`Destination is outside every configured root:\n`
+        + `  ${repoPath}\n\n`
+        + `A name with a \`/\` is read relative to the repo.\n`
+        + `To place it under a root instead:\n`
+        + `  runlist new ${typeName} ${name} --root ${path.basename(targetRoot)}\n`
+        + `     → ${toRepoPath(rooted, config.repoRoot)}\n\n`
+        + `Roots: ${allRoots.map(root => path.basename(root)).join(', ')}`);
+    }
+  }
+  const destinationAuthorization = authorizeManagedDestination(filePath, config, { kind: 'New document destination' });
+
+  if (existsSync(filePath)) {
+    die(`File already exists: ${repoPath}`);
+  }
+
+  const today = nowIso();
+
+  // 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));
+  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
+  // for the "ended up in docs/plans/ for a doc" foot-gun.
+  // Report the root the file actually landed in, not the one resolution started
+  // from: a directory prefix can move the destination into a different root
+  // entirely, and the line used to say `Root: plans` while writing docs/prospects/.
+  let rootHint = '';
+  if (!rootName && allRoots.length > 1) {
+    const owningRoot = destinationAuthorization.root.lexicalPath;
+    const chosenLabel = path.basename(owningRoot);
+    const others = allRoots
+      .filter(r => r !== owningRoot)
+      .map(r => path.basename(r));
+    rootHint = `Root: ${chosenLabel} (others: ${others.join(', ')} — pass --root <name> to change)\n`;
+  }
+
+  const hubKind = isRunlistHub ? ' (runlist hub)'
+    : isCoordinationHub ? ' (coordination hub)'
+    : isRoadmap ? ' (roadmap hub)'
+    : isLite ? ' (lite plan)'
+    : isAudit ? ' (audit plan)'
+    : '';
+  const isCustomTemplate = Object.prototype.hasOwnProperty.call(config.raw?.templates ?? {}, typeName);
+
+  if (dryRun && !renderPreview) {
+    if (isCustomTemplate) {
+      process.stdout.write(`${dim('[dry-run]')} Target: ${repoPath}\n`);
+      process.stdout.write(`${dim('[dry-run]')} Custom template rendering skipped; use --render-preview to explicitly execute its JavaScript and inspect the resulting document.\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) {
+      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;
+    // A repo that overrides the plan or doc template keeps the built-in promise
+    // that an authored body replaces the outline. Without this, the override's
+    // body fn dropped the draft into its first slot and appended its own
+    // sections after it, so a draft opening `## Problem` came out with two, and
+    // sessions trimmed the tail by hand. Other custom types render as written.
+    const overridesShortcutType = template._overridesBuiltin && (typeName === 'plan' || typeName === 'doc');
+    const authored = variantBody || overridesShortcutType ? 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}`;
+  }
+
+  if (dryRun) {
+    process.stdout.write(`${dim('[dry-run]')} Would create: ${repoPath}\n${content}`);
+    return;
+  }
+
+  // Ensure parent dir exists (templates with `dir:` may target a new subdirectory)
+  mkdirSync(path.dirname(filePath), { recursive: true });
+
+  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;
+    }
+    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`);
+  }
+
+  // Post-create guidance. Prompts are the classic confusion point: agents
+  // reflexively `git add && commit` a freshly-created file, but saved prompts
+  // are session-local handoff artifacts — the next session consumes them via
+  // `runlist use`, and the prompts dir is often gitignored (the commit then fails
+  // confusingly). Tell the agent the next step explicitly, and flag a gitignored
+  // target for any type so "why won't this commit" never happens silently.
+  if (typeName === 'prompt') {
+    process.stdout.write(dim('Session-local — no need to commit. The next session runs `runlist use` (or `runlist use ' + repoPath + '`) to consume it.\n'));
+  }
+  // Teach the field-length contract at the moment the fields get written —
+  // learning it from a cap warning later sends sessions into hand-trim /
+  // re-check loops.
+  if (typeName === 'plan') {
+    process.stdout.write(dim('current_state = 2-4 sentence summary (cap 1500 chars); next_step = 1-2 sentence pointer (cap 800). Detail goes in the body, not frontmatter.\n'));
+  }
+  try {
+    const { isGitIgnored } = await import('./git.mjs');
+    if (isGitIgnored(filePath, config.repoRoot)) {
+      process.stdout.write(dim(`Note: ${repoPath} is gitignored — don't try to git add/commit it.\n`));
+    }
+  } catch { /* git absent / not a repo — skip the note */ }
+
+  const indexRegenerated = !opts.deferIndex ? regenIndex(config) : false;
+
+  if (showFiles) {
+    const touched = [filePath, ...childPaths];
+    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,
+  };
+}
+
+// The part of `new --help` only the repo can answer: which types exist here,
+// what status each starts at, which statuses are valid, and where each lands.
+// Sessions otherwise read the config file to find out.
+export function newHelpForRepo(config) {
+  // Only types with a template: a status-only type can't be created by `new`.
+  const types = new Set([...Object.keys(BUILTIN_TEMPLATES), ...Object.keys(config.raw?.templates ?? {})]);
+  const rows = [];
+  const width = Math.max(...[...types].map(t => t.length));
+  for (const typeName of types) {
+    const template = resolveTemplate(typeName, config);
+    if (!template) continue;
+    const statuses = [...(config.typeStatuses?.get(typeName) ?? [])];
+    const tmplDefault = typeof template === 'object' ? template.defaultStatus : null;
+    const start = tmplDefault && (!statuses.length || statuses.includes(tmplDefault)) ? tmplDefault : (statuses[0] ?? tmplDefault ?? 'active');
+    const roots = config.docsRoots ?? [config.docsRoot];
+    // Mirrors runNew: a matching targetRoot wins, else the catch-all root plus
+    // the template's `dir`.
+    const typeRoot = typeof template === 'object' && template.targetRoot
+      ? roots.find(r => r.endsWith(template.targetRoot) || path.basename(r) === template.targetRoot)
+      : null;
+    const dest = typeRoot ?? (typeof template === 'object' && template.dir
+      ? path.join(catchAllRoot(config), template.dir)
+      : catchAllRoot(config));
+    const where = toRepoPath(dest, config.repoRoot) + '/';
+    const custom = readTemplateStore(config).data.templates[typeName] ? ' (Markdown template)' : Object.prototype.hasOwnProperty.call(config.raw?.templates ?? {}, typeName) ? ' (this repo\'s template)' : '';
+    rows.push(`  ${typeName.padEnd(width)} → ${where}<slug>.md, starts ${start}${custom}`);
+    if (statuses.length) rows.push(`  ${''.padEnd(width)}   statuses: ${statuses.join(', ')}`);
+  }
+  const roots = (config.docsRoots ?? [config.docsRoot]).map(r => path.basename(r));
+  rows.push(`  ${'hub'.padEnd(width)} → a plan with a hub body (coordination unless --runlist or --roadmap)`);
+  rows.push(`  ${'decision'.padEnd(width)} → an entry in an existing plan's decisions section`);
+  return `This repo:
+${rows.join('\n')}
+  roots (for --root): ${roots.join(', ')}`;
+}
+
+function resolveTemplate(name, config) {
+  return applyTemplateOverride(name, resolveBaseTemplate(name, config), config, pkg.version);
+}
+
+function resolveBaseTemplate(name, config) {
+  const configTemplates = config.raw?.templates ?? {};
+  const override = configTemplates[name];
+  const builtin = BUILTIN_TEMPLATES[name];
+
+  if (override) {
+    if (!builtin) return { ...override, _overridesBuiltin: false };
+    // Partial-override DX: shallow-merge built-in under override so missing
+    // fields (description, dir, targetRoot, defaultStatus, frontmatter, body,
+    // acceptsBody, requiresBody) fall back to the built-in. Anything the
+    // override explicitly declares wins.
+    const merged = { ...builtin, ...override, _overridesBuiltin: true };
+
+    // Body-loss guard: if the override supplies its OWN body fn but doesn't
+    // explicitly opt in to body acceptance, the inherited built-in
+    // `acceptsBody`/`requiresBody` could let body input flow into a custom
+    // body fn that doesn't honor `ctx.bodyInput` — silently discarding the
+    // heredoc, the worst-UX bug fix #9 was added to prevent. Strip the
+    // inherited flags so the fail-fast guard fires. EXCEPT when the custom
+    // body fn references `bodyInput` itself, in which case it's clearly
+    // body-aware and inheriting acceptsBody is the agent-first move.
+    const overrodeBody = typeof override.body === 'function';
+    const declaredAcceptance = override.acceptsBody !== undefined || override.requiresBody !== undefined;
+    if (overrodeBody && !declaredAcceptance) {
+      const bodyAware = /bodyInput/.test(override.body.toString());
+      if (!bodyAware) {
+        merged.acceptsBody = undefined;
+        merged.requiresBody = undefined;
+      }
+    }
+    return merged;
+  }
+
+  if (builtin) return builtin;
+
+  const available = [...new Set([...Object.keys(BUILTIN_TEMPLATES), ...Object.keys(configTemplates)])];
+  die(`Unknown type: ${name}\nAvailable: ${available.join(', ')}`);
+}
+
+function listTemplates(config) {
+  const configTemplates = config.raw?.templates ?? {};
+  const all = { ...BUILTIN_TEMPLATES };
+  for (const [k, v] of Object.entries(configTemplates)) {
+    all[k] = v;
+  }
+
+  process.stdout.write(bold('Available types') + '\n\n');
+  for (const [name, tmpl] of Object.entries(all)) {
+    const desc = typeof tmpl === 'function'
+      ? '(custom function)'
+      : (tmpl.description ?? '');
+    const source = readTemplateStore(config).data.templates[name] ? dim(' (runlist.templates.json)') : configTemplates[name] ? dim(' (config)') : '';
+    process.stdout.write(`  ${name}${source}\n`);
+    if (desc) process.stdout.write(`  ${dim(desc)}\n`);
+    process.stdout.write('\n');
+  }
+  process.stdout.write(`  hub\n  ${dim('A plan with a hub body: coordination by default, --runlist or --roadmap for the others.')}\n\n`);
+  process.stdout.write(`  decision\n  ${dim('An entry in an existing plan\'s decisions section: runlist new decision <plan> --question "…" @record.md')}\n\n`);
+}
+
+function runNewDecisionArgs(argv, config, opts) {
+  const positional = [];
+  let question = null;
+  let disposition = null;
+  let answers = null;
+  let bodyFlag = null;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--question' && argv[i + 1] !== undefined) { question = argv[++i]; continue; }
+    if (a === '--disposition' && argv[i + 1] !== undefined) { disposition = argv[++i]; continue; }
+    if (a === '--answers' && argv[i + 1] !== undefined) { answers = argv[++i]; continue; }
+    if ((a === '--body' || a === '--message') && argv[i + 1] !== undefined) { bodyFlag = argv[++i]; continue; }
+    if (a === '--config' || a === '--root') { i++; continue; }
+    if (!a.startsWith('-') || a === '-') positional.push(a);
+  }
+  const [, planArg, ...rest] = positional;
+  let record = null;
+  if (bodyFlag !== null) record = readBodyInput(bodyFlag);
+  else if (rest.length) record = readBodyInput(rest.join(' '));
+  else record = readPipedBodyInput();
+  return runNewDecision({ planArg, question, disposition, record, answers }, config, { dryRun: opts.dryRun });
+}
+
+// Browsing templates must never invoke repository-provided JavaScript.
+export function renderAppDocument(name,{title,status,today,bodyInput},config) {
+  const type=name==='hub'?'plan':name;
+  if(!['plan','doc'].includes(type))throw new Error('Choose a plan, doc or hub scaffold.');
+  // Use the CLI's built-in scaffold/Markdown override and authored-body rules.
+  // Repository JavaScript functions are deliberately excluded from previews.
+  const template=name==='hub'?BUILTIN_TEMPLATES.plan:applyTemplateOverride(type,BUILTIN_TEMPLATES[type],config,pkg.version);
+  const ctx={title,status,today,bodyInput,validSurfaces:config.raw?.taxonomy?.surfaces??(config.validSurfaces?[...config.validSurfaces]:null),validModules:config.raw?.taxonomy?.modules??(config.validModules?[...config.validModules]:null)};
+  let fm=template.frontmatter(status,today,ctx);
+  if(name==='hub')fm=mergeBodyFrontmatter(fm,{execution_mode:'coordination'},'plan');
+  const authored=name==='hub'||template._overridesBuiltin?fullBodyShortcut(title,bodyInput):null;
+  const body=authored??(name==='hub'?coordinationHubBody(title,bodyInput,today):template.body(title,ctx));
+  return `---\n${fm}\n---\n${body}`;
+}
+
+export function appDocumentTemplates(config) {
+  const catalog = appTemplates(config);
+  const templates = catalog.templates.filter(t => ['plan','doc'].includes(t.name)).map(t => ({
+    ...t, origin:t.configuredSource && !t.overridden ? 'Built-in Markdown' : t.origin, type:t.name, defaultStatus:t.name === 'plan' ? 'planned' : 'active',
+    // JavaScript templates cannot be safely executed just to show a preview.
+    note:t.configuredSource && !t.overridden ? 'Uses the built-in Markdown scaffold. Customize and save a Markdown template to use repository-specific content here.' : null,
+  }));
+  const plan = templates.find(t => t.name === 'plan');
+  templates.push({name:'hub',type:'plan',description:'Coordination hub for related plans',defaultStatus:'planned',origin:'Built-in hub',
+    source:`---\n${extractFrontmatter(plan.defaultSource).frontmatter}\nexecution_mode: coordination\n---\n${coordinationHubBody('{{title}}','{{body}}','{{date}}')}`});
+  return {...catalog,templates};
+}
+
+export function appTemplates(config) {
+  const store = readTemplateStore(config);
+  const configFile = config.configPath ? toRepoPath(config.configPath,config.repoRoot) : 'runlist.config.mjs';
+  const code = value => typeof value === 'function' ? value.toString() : Object.entries(value).map(([key,v])=>`${key}: ${typeof v === 'function' ? v.toString() : JSON.stringify(v)}`).join('\n\n');
+  const templates = Object.entries(BUILTIN_TEMPLATES).map(([name,builtin]) => {
+    const ctx = {title:'{{title}}',status:'{{status}}',today:'{{date}}',bodyInput:'{{body}}',validSurfaces:config.raw?.taxonomy?.surfaces ?? (config.validSurfaces ? [...config.validSurfaces] : null),validModules:config.raw?.taxonomy?.modules ?? (config.validModules ? [...config.validModules] : null)};
+    const defaultSource = `---\n${builtin.frontmatter(ctx.status,ctx.today,ctx)}\n---\n${builtin.body(ctx.title,ctx)}`.replaceAll(pkg.version,'{{version}}');
+    const configured = config.raw?.templates?.[name];
+    return {name,description:builtin.description,source:store.data.templates[name]?.source ?? defaultSource,defaultSource,overridden:!!store.data.templates[name],origin:store.data.templates[name] ? templateFile : configured ? `${configFile} (JavaScript)` : 'Built-in',configuredSource:configured ? code(configured) : null,editable:true};
+  });
+  for (const [name,value] of Object.entries(config.raw?.templates ?? {})) if (!BUILTIN_TEMPLATES[name]) templates.push({name,description:value.description ?? 'Repository template',origin:`${configFile} (JavaScript)`,source:code(value),editable:false});
+  return {templates,revision:store.revision,file:templateFile,version:pkg.version};
+}