runlist 0.99.2 → 0.100.0

package/src/new.mjs

@@ -12,6 +12,8 @@ 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';
+import { assertPublishedPromptFolder, carriedOnto, carryLegacyPrompts, isHandoffsMode, planHandoffsConfig, planningRefusal, publishHandoffsConfig } from './handoffs-mode.mjs';
+import { PROMPT_DIR, rootIsWorkingFolder } from './naming.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
@@ -410,6 +412,12 @@ export function titleize(s) {
 
 // Where saved prompts are written: the prompt template's targetRoot when a
 // root matches it, else the primary root plus the template's `dir`.
+// The prompt template's routing alone, for callers that must not read the
+// Markdown template store (hooks, settings inspection).
+export function promptRouting(config) {
+  return { dir: rootIsWorkingFolder(config) ? PROMPT_DIR : 'prompts', targetRoot: 'prompts', ...config.raw?.templates?.prompt };
+}
+
 export function promptDirectory(config, template = resolveTemplate('prompt', config)) {
   let targetRoot = config.docsRoot;
   let routed = false;
@@ -420,6 +428,24 @@ export function promptDirectory(config, template = resolveTemplate('prompt', con
   return template.dir && !routed ? path.join(targetRoot, template.dir) : targetRoot;
 }
 
+// The same default/template routing used by `new plan`, including before setup.
+export function planDirectory(config, template = resolveTemplate('plan', config)) {
+  const roots = config.docsRoots ?? [config.docsRoot];
+  const routed = template.targetRoot && roots.find(root => root.endsWith(template.targetRoot) || path.basename(root) === template.targetRoot);
+  return routed || path.join(catchAllRoot(config), template.dir || '');
+}
+
+// Only reached where no handoffs config is created for the prompt: a plan
+// handed off before setup, or a save outside Git in a folder an older runlist
+// saved handoffs or plans in.
+export function unconfiguredPromptHint(config) {
+  return config.configFound ? '' : 'No runlist config here yet — run `runlist setup`; it carries this prompt over.\n';
+}
+
+function userNameDirIn(name) {
+  return Boolean(name && (name.includes('/') || name.includes(path.sep)));
+}
+
 function bindPromptParent(content, parentPrompt) {
   if (!parentPrompt) return content;
   const { frontmatter, body } = extractFrontmatter(content);
@@ -668,10 +694,122 @@ next_step:
 `;
 }
 
+// Where `runlist new` puts a document: the name's own folder (read relative
+// to the repo, or to --root), else the template's root and folder. Shared by
+// the check a first prompt runs before the carry and by the write itself.
+function resolveNewTarget(name, typeName, template, config, rootName, { explainRoots = true } = {}) {
+  // 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); }
+
+  // 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 (explainRoots && 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(', ')}`);
+    }
+  }
+  return { nameDir, namePart, userNameDir, slug, targetRoot, baseDir, filePath, repoPath };
+}
+
+// Prompts live in the prompt folder and nowhere else where planning is off or
+// not set up yet (one prompt location, src/naming.mjs): a name with a folder in
+// it lands inside that folder or is refused, so nothing writes a root prompts/.
+function assertPromptFolder(target, name, config) {
+  if (config.configFound && !isHandoffsMode(config)) return;
+  const folder = promptDirectory(config);
+  if (lexicallyInside(folder, target.filePath)) return;
+  const where = toRepoPath(folder, config.repoRoot);
+  die(`Nothing saved: prompts are saved in ${where}/, and \`${name}\` is outside it. Use a plain name (runlist new prompt ${path.basename(name, '.md')} …) or a path inside ${where}/.`);
+}
+
+async function waitingForSetup(config) {
+  const { documentsWaitingForSetup } = await import('./setup-waiting.mjs');
+  return documentsWaitingForSetup(config);
+}
+
 export async function runNew(argv, config, opts = {}) {
   const { dryRun } = opts;
 
-  if (argv.find(a => !a.startsWith('-')) === 'decision') return runNewDecisionArgs(argv, config, opts);
+  if (argv.find(a => !a.startsWith('-')) === 'decision') {
+    if (isHandoffsMode(config)) die(planningRefusal('`runlist new decision`', await waitingForSetup(config)));
+    return runNewDecisionArgs(argv, config, opts);
+  }
 
   const knownTypes = new Set(Object.keys(BUILTIN_TEMPLATES));
   // Also include any custom templates from config
@@ -759,6 +897,9 @@ export async function runNew(argv, config, opts = {}) {
     typeName = 'plan';
     if (runlistArg === null && !roadmap) coordination = true;
   }
+  // A handoffs-only project scans its prompt folder alone; anything else
+  // created there would land among the prompts and outside every listing.
+  if (isHandoffsMode(config) && typeName !== 'prompt') die(planningRefusal(`\`runlist new ${typeName}\``, await waitingForSetup(config)));
 
   if (!name) {
     if (isInteractive()) {
@@ -861,6 +1002,10 @@ export async function runNew(argv, config, opts = {}) {
     if (split.frontmatter) {
       bodyFrontmatter = split.frontmatter;
       bodyInput = split.body;
+      if (Object.hasOwn(bodyFrontmatter, 'status') && !effective.has(bodyFrontmatter.status)) {
+        process.stdout.write(`status \`${bodyFrontmatter.status}\` is not a ${typeName} status; using \`${status}\`\n`);
+        delete bodyFrontmatter.status;
+      }
     }
   }
 
@@ -903,95 +1048,46 @@ export async function runNew(argv, config, opts = {}) {
     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);
+  // Zero setup: the first prompt saved in a repository with no config creates
+  // a handoffs-only config (src/handoffs-mode.mjs), and prompts an older
+  // version saved in the root prompts/ move to docs/prompts/ first. Every check
+  // that can refuse the save runs against docs/prompts/ as that carry leaves
+  // it, before anything moves or is written, and dry-run stops at that point.
+  let handoffsLine = null;
+  if (typeName === 'prompt' && !config.configFound && !opts.handoffsPlanned) {
+    const setup = await planHandoffsConfig(process.cwd(), config, { dryRun, out: process.stdout });
+    if (setup.previewStopped) return;
+    config = setup.config;
+    const target = resolveNewTarget(name, typeName, resolveTemplate('prompt', config), config, rootName, { explainRoots: false });
+    assertPromptFolder(target, name, config);
+    const carried = carriedOnto(setup, target.filePath);
+    if (carried) die(`File already exists: ${carried.from} (it moves to ${carried.to} before this prompt is saved)`);
+    if (existsSync(target.filePath)) die(`File already exists: ${target.repoPath}`);
+    if (dryRun) {
+      if (setup.dryRunLine) process.stdout.write(`${dim(setup.dryRunLine)}\n`);
+      await carryLegacyPrompts(setup, { dryRun, out: process.stdout });
+      process.stdout.write(`${dim('[dry-run]')} Would create: ${target.repoPath}\n${dim('[dry-run]')} Type: prompt\n`);
+      return;
+    }
+    await carryLegacyPrompts(setup, { out: process.stdout });
+    if (!setup.legacy) {
+      const published = await publishHandoffsConfig(setup, { testHooks: opts.testHooks });
+      config = published.config;
+      assertPublishedPromptFolder(setup, published, promptDirectory(config));
+      handoffsLine = published.line;
+      if (handoffsLine) process.stdout.write(`${handoffsLine}\n`);
+    }
   }
-  // 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); }
+  const promptFolderOnly = typeName === 'prompt' && (!config.configFound || isHandoffsMode(config));
+  const { namePart, slug, baseDir, filePath, repoPath } = resolveNewTarget(name, typeName, typeName === 'prompt' ? resolveTemplate('prompt', config) : template, config, rootName, { explainRoots: !promptFolderOnly });
+  if (promptFolderOnly) assertPromptFolder({ filePath }, name, config);
 
   // 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)) {
@@ -1123,14 +1219,15 @@ export async function runNew(argv, config, opts = {}) {
     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.
+  // Prompt consumption and Git tracking are separate choices. Describe the
+  // resolved policy, then flag an actually ignored target for any type.
   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'));
+    if (!handoffsLine) process.stdout.write(unconfiguredPromptHint(config));
+    const tracking = config.promptTracking ?? 'local';
+    const policy = tracking === 'tracked' ? 'Prompt commits are allowed.'
+      : tracking === 'untracked' ? 'Leave untracked to reduce commit churn; git add -A can still stage it.'
+        : 'Local policy: keep pending prompts out of Git operations.';
+    process.stdout.write(dim(`${policy} Inspect with \`runlist config get promptTracking\`. The next session runs \`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 /
@@ -1170,7 +1267,9 @@ export async function runNew(argv, config, opts = {}) {
 // 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 ?? {})]);
+  // Where planning is off, a prompt is the one thing it creates.
+  const promptsOnly = isHandoffsMode(config);
+  const types = promptsOnly ? new Set(['prompt']) : 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) {
@@ -1194,6 +1293,7 @@ export function newHelpForRepo(config) {
     if (statuses.length) rows.push(`  ${''.padEnd(width)}   statuses: ${statuses.join(', ')}`);
   }
   const roots = (config.docsRoots ?? [config.docsRoot]).map(r => path.basename(r));
+  if (promptsOnly) return `This repo:\n${rows.join('\n')}\n  Plans and docs come with planning; \`runlist setup\` turns it on.`;
   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:
@@ -1238,7 +1338,10 @@ function resolveBaseTemplate(name, config) {
     return merged;
   }
 
-  if (builtin) return builtin;
+  // Before any config the docs root is the working folder, so the built-in
+  // prompt folder is spelled out in full: prompts go to docs/prompts/ there
+  // too, never to a root prompts/ (src/naming.mjs).
+  if (builtin) return name === 'prompt' && rootIsWorkingFolder(config) ? { ...builtin, dir: PROMPT_DIR } : builtin;
 
   const available = [...new Set([...Object.keys(BUILTIN_TEMPLATES), ...Object.keys(configTemplates)])];
   die(`Unknown type: ${name}\nAvailable: ${available.join(', ')}`);
@@ -1251,8 +1354,12 @@ function listTemplates(config) {
     all[k] = v;
   }
 
+  // Where planning is off, a prompt is the one thing `new` creates, so it is
+  // the one type listed.
+  const promptsOnly = isHandoffsMode(config);
   process.stdout.write(bold('Available types') + '\n\n');
   for (const [name, tmpl] of Object.entries(all)) {
+    if (promptsOnly && name !== 'prompt') continue;
     const desc = typeof tmpl === 'function'
       ? '(custom function)'
       : (tmpl.description ?? '');
@@ -1261,6 +1368,10 @@ function listTemplates(config) {
     if (desc) process.stdout.write(`  ${dim(desc)}\n`);
     process.stdout.write('\n');
   }
+  if (promptsOnly) {
+    process.stdout.write(`${dim('Plans and docs come with planning; `runlist setup` turns it on.')}\n`);
+    return;
+  }
   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`);
 }

package/src/pickup-card.mjs

@@ -282,7 +282,7 @@ export function renderCard(card) {
   }
 
   lines.push('');
-  lines.push(dim(`Body: ${formatBytes(card.bodyBytes)}. \`runlist set in-session ${card.path} --full\` for everything, or Read the file with offset/limit to target a section by line number.`));
+  lines.push(dim(`Body: ${formatBytes(card.bodyBytes)}. \`runlist show ${card.path} --section "<heading>"\` reads one section; \`runlist set in-session ${card.path} --full\` prints everything.`));
   return lines.join('\n') + '\n';
 }
 

package/src/plan-changes.mjs

@@ -11,6 +11,55 @@ import { isGitIgnored } from './git.mjs';
 
 const SHOWN_COMMITS = 10;
 
+// List-time hints share one bounded Git window. Consume-time detail below
+// keeps its existing next_step comparison and commit messages.
+export function summarizePlanChanges(requests, config, { runGit = spawnSync, stat = statSync } = {}) {
+  const maxTargets = 64, maxCommits = 256;
+  const targets = new Map();
+  for (const { plan } of requests) {
+    if (!plan || targets.has(plan) || targets.size >= maxTargets || path.isAbsolute(plan)
+      || plan.split(/[\\/]/).includes('..') || /[\0\r\n]/.test(plan)) continue;
+    try { targets.set(plan, stat(path.resolve(config.repoRoot, plan))); }
+    catch { targets.set(plan, null); }
+  }
+  const paths = [...targets].filter(([, stamp]) => stamp?.isFile()).map(([file]) => file);
+  const query = args => {
+    if (!paths.length) return null;
+    try {
+      const result = runGit('git', args, { cwd: config.repoRoot, encoding: 'utf8', timeout: 750, maxBuffer: 256 * 1024 });
+      return !result.error && result.status === 0 ? result.stdout : null;
+    } catch { return null; }
+  };
+  const pathspecs = paths.map(file => `:(top,literal)${file}`);
+  const trackedOutput = query(['ls-files', '-z', '--', ...pathspecs]);
+  const tracked = new Set((trackedOutput ?? '').split('\0'));
+  const trackedPaths = paths.filter(file => tracked.has(file));
+  const validTimes = requests.map(({ since }) => since ? new Date(since).getTime() : NaN).filter(Number.isFinite);
+  const earliest = validTimes.length ? new Date(Math.min(...validTimes)).toISOString() : null;
+  const log = trackedPaths.length && earliest
+    ? query(['log', `--max-count=${maxCommits + 1}`, `--since=${earliest}`, '--format=%x00runlist:change:%ct%x00', '--name-only', '-z', '--', ...trackedPaths.map(file => `:(top,literal)${file}`)]) : null;
+  const dirtyOutput = trackedPaths.length ? query(['diff', '--name-only', '-z', 'HEAD', '--', ...trackedPaths.map(file => `:(top,literal)${file}`)]) : null;
+  const dirty = new Set((dirtyOutput ?? '').split('\0'));
+  const latest = new Map();
+  let date = null, commits = 0;
+  for (const field of (log ?? '').split('\0')) {
+    const marker = /^runlist:change:(\d+)$/.exec(field);
+    if (marker) { date = Number(marker[1]) * 1000; commits++; continue; }
+    const file = field.replace(/^\n/, '');
+    if (date !== null && tracked.has(file)) latest.set(file, Math.max(latest.get(file) ?? 0, date));
+  }
+  return requests.map(({ plan, since }) => {
+    const when = since ? new Date(since).getTime() : NaN;
+    const stamp = targets.get(plan);
+    if (!Number.isFinite(when) || !stamp?.isFile() || trackedOutput === null) return 'unknown';
+    if (!tracked.has(plan)) return stamp.mtimeMs > when ? 'edited since save (file clock)' : 'no edits since save (file clock)';
+    if ((latest.get(plan) ?? 0) > when) return 'changed since save';
+    if (dirty.has(plan)) return 'working changes (time unknown)';
+    if (log === null || dirtyOutput === null || commits > maxCommits) return 'unknown';
+    return 'no commits since save';
+  });
+}
+
 function git(args, repoRoot) {
   const result = spawnSync('git', args, { cwd: repoRoot, encoding: 'utf8' });
   if (result.error || result.status !== 0) return null;

package/src/prompt-handoff.mjs

@@ -59,6 +59,22 @@ parent_prompt: {{parent_prompt}}
   },
 };
 
+// The built-in outlines without plan wording, for a project where planning is
+// off (src/handoffs-mode.mjs). A saved override is the user's text and is used
+// as written.
+const HANDOFFS_ONLY_LINES = [
+  ['<!-- Work to resume and owning plan path + section, or a durable brief if there is no plan. -->', '<!-- Work to resume, with the paths it concerns or a durable brief. -->'],
+  ['<!-- Review linked child handoffs and record completed results in the owning plan. -->', '<!-- Review linked child handoffs and carry their completed results forward. -->'],
+  ['<!-- One sentence: the bounded job and its owning plan or brief. -->', '<!-- One sentence: the bounded job and its brief. -->'],
+  ["<!-- Owned files, shared claims, current authorization, and any required new go. -->", '<!-- Owned files, current authorization, and any required new go. -->'],
+  ["<!-- Do not release or claim the parent's plan. This handoff grants no new authority. -->", '<!-- This handoff grants no new authority. -->'],
+];
+
+export function builtinHandoffTemplate(key, { planning = true } = {}) {
+  const { source } = HANDOFF_TEMPLATES[key];
+  return planning ? source : HANDOFFS_ONLY_LINES.reduce((text, [from, to]) => text.replace(from, () => to), source);
+}
+
 // Explicit links win, including missing/ambiguous parents. Legacy child names
 // may share a parent stem; the longest whole-stem match is the most specific.