runlist 0.96.0 → 0.97.0

package/plugins/runlist-codex/skills/runlist/SKILL.md

@@ -16,7 +16,9 @@ Use this skill in repositories with `runlist.config.mjs` or `dotmd.config.mjs`.
 - Change status with `runlist set <status> <file> [--note "why"]`; this runs validation, lifecycle hooks, ref repairs, and index updates. Never hand-edit a `status:` field.
 - Close a shipped plan with `runlist archive <file>`; use `partial`, `active`, `awaiting`, or `blocked` when those match the actual state. Valid statuses are repository and type specific: `runlist statuses list --type plan`.
 - For a handoff, write a concrete resume draft, then run `runlist baton [<plan-or-slug>] @<draft-file>`. An owned plan is released in the same operation. If a handoff for that work is pending, inspect it with `runlist prompts show <file>`; keep it if current or pass `--replace` with the new draft. Replacement archives the old text and refreshes exactly one pending prompt.
-- **Subagent handoffs:** use `runlist baton --subagent <task-slug> @/tmp/draft.md` to save `subagent-<task-slug>`. Under a parent-owned plan, choose a distinct task slug that does not resolve to a plan; do not release the parent's claim. A child owning a dedicated plan can use `runlist baton --subagent <plan-file> @/tmp/draft.md`. Parent-session batons keep the default `resume-*` naming. Matching prefixes are kept once; conflicting prefixes are refused. Existing prompts keep their names, and `--subagent --replace` refuses a parent-prefixed prompt.
+- **Subagent handoffs:** use `runlist baton --subagent <task-slug> @/tmp/draft.md` to save `subagent-<task-slug>`. Under a parent-owned plan, choose a distinct task slug that does not resolve to a plan; do not release the parent's claim. A child owning a dedicated plan can use `runlist baton --subagent <plan-file> @/tmp/draft.md`. Add `--parent resume-<session-name>` to link the child beneath its parent in `rl prompts`; the parent may be saved later. Parent-session batons keep the default `resume-*` naming. Matching prefixes are kept once; conflicting prefixes are refused. Existing prompts keep their names, and `--subagent --replace` refuses a parent-prefixed prompt.
+- **Draft outlines:** `runlist baton --template` prints the resume outline. The desktop Templates editor saves resume/subagent outlines in `runlist.templates.json`; repository baton instructions still apply.
+- **Child draft:** `runlist baton --subagent --template --parent resume-<name>` prints the saved child outline (built-in: Task, State, Next, Evidence and Boundaries). Fill the draft; its `parent_prompt` travels on save. A launcher can pass `RUNLIST_PARENT_PROMPT` into the child environment instead. Keep full records at durable repo-relative paths with commits and checked results; temporary scratch paths are supplementary. Completed work is a result for the parent to record, not another restart. Repair old links without replacing text: `runlist prompts link <child...> --parent resume-<name>`. Showing or consuming a parent surfaces its pending children without consuming them.
 - Consume a saved prompt with `runlist use <prompt-file>` (or bare `runlist use` for the oldest). This archives and claims before printing the body. For read-only triage, use `runlist prompts show <file>` or `runlist prompts show --all`; never open pending prompts with a file reader or `cat`.
 - Pending prompts are session-local. Commit the tracked plan or source files named by baton, not `docs/prompts/*.md`.
 - Create a document with `runlist new <type> <name> @<draft-file>`. A draft starting with frontmatter can supply scaffold fields; `type` is fixed by the command.

package/src/app.mjs

@@ -7,6 +7,14 @@ import { SourceEditError } from './source-editor.mjs';
 import { resolveDocArg } from './index.mjs';
 
 const assets = new URL('../assets/app/', import.meta.url);
+const staticFiles = new Map([
+  'app.mjs','theme.mjs','transport.mjs','shared.mjs','document-create.mjs',
+  'quick-navigation.mjs','recovery-center.mjs','settings.mjs','document-lifecycle.mjs',
+  'record-navigation.mjs','library-navigation.mjs','outline.mjs','editor-navigation.mjs',
+  'template-editor.mjs','block-model.mjs','block-editor.mjs','git-changes.mjs','git-commit.mjs',
+  'document-views.mjs','document-stages.mjs','document-yardstick.mjs',
+  'filing-navigation.mjs','semantic-search.mjs','stage-source.mjs','app.css',
+].map(file => [`/${file}`, [file, file.endsWith('.css') ? 'text/css' : 'text/javascript']]));
 const ttl = 12 * 60 * 60 * 1000;
 const secret = () => randomBytes(32).toString('base64url');
 function problem(code,message) { throw new SourceEditError(code,message); }
@@ -40,10 +48,7 @@ export async function startApp({ config, port = 5173, initialPath = null, actor
       if (!origin || ![new URL(origin).host, `localhost:${server.address().port}`].includes(req.headers.host)) problem('forbidden', 'Invalid local application host.');
       const url = new URL(req.url, origin);
       if (req.method === 'GET' && url.pathname === '/') return send(200, readFileSync(new URL('index.html', assets)), 'text/html; charset=utf-8');
-      const staticFiles = { '/document-create.mjs':['document-create.mjs','text/javascript'], '/quick-navigation.mjs':['quick-navigation.mjs','text/javascript'], '/recovery-center.mjs':['recovery-center.mjs','text/javascript'], '/transport.mjs':['transport.mjs','text/javascript'], '/settings.mjs':['settings.mjs','text/javascript'], '/document-lifecycle.mjs':['document-lifecycle.mjs','text/javascript'], '/record-navigation.mjs':['record-navigation.mjs','text/javascript'], '/theme.mjs':['theme.mjs','text/javascript'], '/library-navigation.mjs':['library-navigation.mjs','text/javascript'], '/outline.mjs':['outline.mjs','text/javascript'], '/editor-navigation.mjs':['editor-navigation.mjs','text/javascript'], '/template-editor.mjs':['template-editor.mjs','text/javascript'], '/block-model.mjs':['block-model.mjs','text/javascript'], '/block-editor.mjs':['block-editor.mjs','text/javascript'], '/app.mjs': ['app.mjs','text/javascript'], '/shared.mjs':['shared.mjs','text/javascript'], '/app.css':['app.css','text/css'] };
-      staticFiles['/git-changes.mjs']=['git-changes.mjs','text/javascript'];
-      staticFiles['/git-commit.mjs']=['git-commit.mjs','text/javascript'];
-      if (req.method === 'GET' && staticFiles[url.pathname]) { const [file, type] = staticFiles[url.pathname]; return send(200, readFileSync(new URL(file, assets)), `${type}; charset=utf-8`); }
+      if (req.method === 'GET' && staticFiles.has(url.pathname)) { const [file, type] = staticFiles.get(url.pathname); return send(200, readFileSync(new URL(file, assets)), `${type}; charset=utf-8`); }
       const requestOrigin = req.headers.origin;
       const permittedOrigins = [origin, `http://localhost:${server.address().port}`];
       if (requestOrigin && !permittedOrigins.includes(requestOrigin)) problem('forbidden', 'Cross-origin requests are refused.');

package/src/baton.mjs

@@ -1,7 +1,7 @@
 import { readFileSync, existsSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
-import { asString, toRepoPath, die, warn, isArchivedPath, resolveRefPath, nowIso } from './util.mjs';
+import { asString, toRepoPath, die, warn, isArchivedPath, resolveRefPath, nowIso, shellQuote } from './util.mjs';
 import { buildIndex, resolveDocArg } from './index.mjs';
 import { preparePromptDocument, runNew, readBodyInput, readPipedBodyInput, slugify } from './new.mjs';
 import { ensurePlanCompletionBeforeRelease, planHasPendingCompletion, renderLifecycleMutation, runSet } from './lifecycle.mjs';
@@ -10,6 +10,8 @@ import { handoffNotDoneLine, recordPendingHandoff, runBatonDone } from './handof
 import { authorizeManagedDestination, authorizeManagedSource } from './managed-path.mjs';
 import { mutateFileSet } from './atomic-mutation.mjs';
 import { assertPlanMutationAuthorized, authoritativeSessionId, listOwnedPlans, readPlanOwnership } from './pickup.mjs';
+import { HANDOFF_TEMPLATES, parentPromptName } from './prompt-handoff.mjs';
+import { readTemplateStore, templateFile } from './template-store.mjs';
 
 // `runlist baton` is the one-command handoff: save the resume prompt AND release
 // the plan in a single atomic-ish verb. It exists because the three-step skill
@@ -80,11 +82,6 @@ function archivedCopyPath(promptPath, config) {
   return authorizeManagedDestination(candidate, config, { kind: 'Baton replacement archive' }).path;
 }
 
-function shellQuote(value) {
-  const raw = String(value);
-  return /^[A-Za-z0-9_./:@+-]+$/.test(raw) ? raw : `"${raw.replace(/["\\$`]/g, '\\$&')}"`;
-}
-
 function commitCommand(config, message, paths) {
   const fallback = ['git', 'commit', '-m', message, '--', ...paths];
   let argv = fallback;
@@ -124,6 +121,8 @@ export async function runBaton(argv, config, opts = {}) {
   let replace = false;
   let done = false;
   let subagent = false;
+  let parentPrompt = null;
+  let template = false;
   const positionals = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -134,10 +133,31 @@ export async function runBaton(argv, config, opts = {}) {
     if (a === '--replace') { replace = true; continue; }
     if (a === '--done') { done = true; continue; }
     if (a === '--subagent') { subagent = true; continue; }
+    if (a === '--template') { template = true; continue; }
+    if (a === '--parent') {
+      const value = argv[++i];
+      try { parentPrompt = parentPromptName(value); }
+      catch { die('--parent requires a resume prompt name, e.g. --parent resume-session-name.'); }
+      continue;
+    }
     if (a === '--json') continue;
     if (!a.startsWith('-') || a === '-' || a.startsWith('@')) { positionals.push(a); continue; }
     die(`Unknown flag for \`runlist baton\`: ${a}`);
   }
+  if (parentPrompt && !subagent) die('--parent requires --subagent.');
+  if (template) {
+    if (done || replace || force || statusFlag || note !== null || positionals.length || bodyFlag !== null) {
+      die('Use `runlist baton --template` or `runlist baton --subagent --template [--parent resume-name]` to print a draft without saving.');
+    }
+    if (subagent && !parentPrompt && process.env.RUNLIST_PARENT_PROMPT) parentPrompt = parentPromptName(process.env.RUNLIST_PARENT_PROMPT);
+    const name = subagent ? 'subagent' : 'resume';
+    const key = `handoff:${name}`;
+    const override = config ? readTemplateStore(config).data.templates[key]?.source : null;
+    const source = override ?? HANDOFF_TEMPLATES[key].source;
+    const draft = source.replaceAll('{{parent_prompt}}', parentPrompt ?? '<resume-parent-name>');
+    process.stdout.write(json ? JSON.stringify({ operation: 'baton-template', name, origin: override ? templateFile : 'Built-in', parentPrompt, template: draft }, null, 2) + '\n' : draft);
+    return;
+  }
 
   let planArg = null;
   let bodyArg = null;
@@ -164,6 +184,13 @@ export async function runBaton(argv, config, opts = {}) {
     body = readPipedBodyInput();
   }
   if (!body || !body.trim()) die(BODY_USAGE);
+  const draft = extractFrontmatter(body);
+  const draftFm = parseSimpleFrontmatter(draft.frontmatter);
+  if (!subagent && asString(draftFm.parent_prompt)) die('parent_prompt requires --subagent; a resume handoff cannot be its own child.');
+  if (subagent && !parentPrompt) {
+    const draftParent = asString(draftFm.parent_prompt);
+    if (draftParent) parentPrompt = parentPromptName(draftParent);
+  }
 
   // Resolve what's being handed off. Two modes:
   //   plan mode — a plan is released alongside the prompt (one status flip).
@@ -249,10 +276,14 @@ export async function runBaton(argv, config, opts = {}) {
     if (!planPath && priorPlanRef) {
       die(`Nothing replaced: ${oldRepoPath} links a plan (${priorPlanRef}). Use \`runlist baton <plan-file> @<draft-file> --replace\` so the plan link and release stay together.`);
     }
+    const priorParent = asString(fm.parent_prompt);
+    parentPrompt ??= priorParent;
     replacement = {
-      oldPath, oldRepoPath, oldRaw,
+      oldPath, oldRepoPath, oldRaw, priorParent,
       archivedPath: archivedCopyPath(oldPath, config),
-      alreadyCurrent: oldBody.trim() === body.trim()
+      alreadyCurrent: oldBody.trim() === draft.body.trim()
+        && Object.entries(draftFm).every(([key, value]) => key === 'parent_prompt' || JSON.stringify(fm[key]) === JSON.stringify(value))
+        && (priorParent ?? null) === parentPrompt
         && (!planPath || (priorPlanPath && path.resolve(priorPlanPath) === path.resolve(planPath))),
       canonicalPath: target.filePath,
     };
@@ -324,6 +355,12 @@ export async function runBaton(argv, config, opts = {}) {
     if (note) warn(`--note ignored — no plan involved in this handoff (notes land in a plan's Version History).`);
   }
 
+  if (subagent) {
+    if (!parentPrompt && process.env.RUNLIST_PARENT_PROMPT) parentPrompt = parentPromptName(process.env.RUNLIST_PARENT_PROMPT);
+    if (replacement && (replacement.priorParent ?? null) !== parentPrompt) replacement.alreadyCurrent = false;
+    if (!parentPrompt) warn('Subagent handoff has no parent link. Pass --parent resume-name, include parent_prompt in the draft, or inherit RUNLIST_PARENT_PROMPT. Use `runlist prompts link <child> --parent <resume-name>` to repair an existing handoff.');
+  }
+
   const preparedReplacement = prepared => {
     if (!replacement || replacement.alreadyCurrent) return { updates: [], creations: [], guards: [] };
     let archivedContent = renderLifecycleMutation(replacement.oldRaw,
@@ -353,14 +390,14 @@ export async function runBaton(argv, config, opts = {}) {
   try {
   if (!planPath) {
     const promptName = replacement ? path.basename(replacement.oldPath, '.md') : slugBase;
-    const prepared = preparePromptDocument(promptName, body, config, { dryRun });
+    const prepared = preparePromptDocument(promptName, body, config, { parentPrompt, dryRun });
     if (replacement) {
       const mutation = preparedReplacement(prepared);
       if (!dryRun && !replacement.alreadyCurrent) mutateFileSet(mutation, { repoRoot: config.repoRoot, testHooks: opts.testHooks });
       newResult = { sessionFiles: [replacement.oldRepoPath, ...(replacement.alreadyCurrent ? [] : [toRepoPath(replacement.archivedPath, config.repoRoot)])] };
     } else {
       try {
-        newResult = await runNew(['prompt', slugBase, '--body', body], config, { dryRun, deferIndex: true });
+        newResult = await runNew(['prompt', slugBase, '--body', body], config, { parentPrompt, dryRun, deferIndex: true });
       } catch (err) {
         // Lost a race with another baton between the pending check and the write.
         if (/File already exists/.test(String(err?.message))) refusePendingHandoff([prepared.repoPath]);
@@ -371,7 +408,7 @@ export async function runBaton(argv, config, opts = {}) {
     createdSlug = path.basename(promptRepoPath, '.md');
   } else {
     const promptName = replacement ? path.basename(replacement.oldPath, '.md') : slugBase;
-    const prepared = preparePromptDocument(promptName, body, config, { plan: repoPath, dryRun });
+    const prepared = preparePromptDocument(promptName, body, config, { plan: repoPath, parentPrompt, dryRun });
     const mutation = preparedReplacement(prepared);
     const setArgs = [status, planPath];
     if (force) setArgs.push('--force');
@@ -434,6 +471,7 @@ export async function runBaton(argv, config, opts = {}) {
   }
   const operationResult = {
     operation: 'baton',
+    parentPrompt,
     dryRun: Boolean(dryRun),
     disposition: replacement?.alreadyCurrent && !statusChanged && !wouldReleaseClaim ? 'already-current' : dryRun ? 'would-change' : 'applied',
     wouldChange: Boolean(dryRun),

package/src/brief.mjs

@@ -0,0 +1,145 @@
+import { extractFrontmatter, normalizeEol } from './frontmatter.mjs';
+import { walkSections, matchSections, walkChecklist } from './section.mjs';
+
+// A document in a few KB, for an agent to read in place of the whole file: a
+// heading outline and the open checklist boxes, both with file line numbers,
+// and one section on request. Pure: callers read the file and render.
+
+export const LIMITS = {
+  outline: 60, // headings shown; the deepest levels drop first
+  boxes: 30, // open boxes shown without --all
+  width: 140, // a heading, box or frontmatter line is cut to this
+  listItems: 8, // a frontmatter list longer than this is collapsed
+  textLines: 4, // and a multi-line frontmatter value cut to this many lines
+  sectionLines: 500, // lines of one section read
+  sectionBytes: 60 * 1024,
+};
+
+// Several files at once is a survey; each one gets less.
+export const SURVEY_LIMITS = { ...LIMITS, outline: 20, boxes: 10 };
+
+export const cut = (text, width = LIMITS.width) =>
+  text.length > width ? `${text.slice(0, width - 3)}...` : text;
+
+// The file split into lines, without the empty one a final newline leaves.
+function fileLines(text) {
+  const lines = text.split('\n');
+  if (lines.length > 1 && lines[lines.length - 1] === '') lines.pop();
+  return lines;
+}
+
+// Headings with file coordinates: `line` is the heading, `end` the last line of
+// its section (the line before the next heading at the same or a higher level).
+function headingsOf(body, bodyLineOffset, lastLine) {
+  return walkSections(body).map(s => ({
+    line: s.lineStart + bodyLineOffset,
+    end: Math.min(s.lineEnd + bodyLineOffset, lastLine),
+    level: s.level,
+    heading: s.heading,
+  }));
+}
+
+// Drop the deepest heading levels until the outline fits, then cut the tail.
+function boundOutline(headings, cap) {
+  let shown = headings;
+  while (shown.length > cap) {
+    const deepest = Math.max(...shown.map(h => h.level));
+    if (deepest <= 1) break;
+    shown = shown.filter(h => h.level < deepest);
+  }
+  shown = shown.slice(0, cap);
+  return { shown, omitted: headings.length - shown.length };
+}
+
+// Frontmatter as written, with long values cut and long lists collapsed.
+export function collapseFrontmatter(frontmatter, limits = LIMITS) {
+  if (!frontmatter) return [];
+  const out = [];
+  let listRun = 0;
+  let textRun = 0;
+  const flush = () => {
+    if (listRun > limits.listItems) out.push(`  (+${listRun - limits.listItems} more)`);
+    if (textRun > limits.textLines) out.push(`  (+${textRun - limits.textLines} more lines)`);
+    listRun = 0;
+    textRun = 0;
+  };
+  for (const line of frontmatter.split('\n')) {
+    if (/^\s+-\s/.test(line)) {
+      if (++listRun <= limits.listItems) out.push(cut(line, limits.width));
+      continue;
+    }
+    if (/^\s+\S/.test(line)) {
+      if (++textRun <= limits.textLines) out.push(cut(line, limits.width));
+      continue;
+    }
+    flush();
+    out.push(cut(line, limits.width));
+  }
+  flush();
+  return out;
+}
+
+/**
+ * The brief of one document's raw text: its size, a bounded outline and the
+ * open boxes. `all` lists every open box. Counts are of what sits outside code
+ * fences, so a template's example checklist is not reported as work.
+ */
+export function buildBrief(raw, { all = false, limits = LIMITS } = {}) {
+  const text = normalizeEol(raw);
+  const { frontmatter, body, bodyLineOffset } = extractFrontmatter(text);
+  const lines = fileLines(text);
+  const headings = headingsOf(body, bodyLineOffset, lines.length);
+  const { shown, omitted } = boundOutline(headings, limits.outline);
+  const boxes = walkChecklist(body).map(b => ({ ...b, line: b.line + bodyLineOffset }));
+  const open = boxes.filter(b => b.open).map(({ line, text: t }) => ({ line, text: t }));
+  const listed = all ? open : open.slice(0, limits.boxes);
+  return {
+    lines: lines.length,
+    bytes: Buffer.byteLength(text),
+    frontmatterLines: frontmatter ? bodyLineOffset : 0,
+    outline: shown,
+    outlineOmitted: omitted,
+    boxes: { open: open.length, done: boxes.length - open.length },
+    open: listed,
+    openOmitted: open.length - listed.length,
+  };
+}
+
+/**
+ * One section of a document by heading: its lines from `from` (default the
+ * heading) to the section's end, cut at `limits.sectionLines` lines or
+ * `limits.sectionBytes`. `next` is the first line not printed when cut.
+ * Returns { found: false, headings } when nothing matches.
+ */
+export function readSection(raw, query, { from = null, limits = LIMITS } = {}) {
+  const text = normalizeEol(raw);
+  const { body, bodyLineOffset } = extractFrontmatter(text);
+  const lines = fileLines(text);
+  const headings = headingsOf(body, bodyLineOffset, lines.length);
+  const matches = matchSections(headings, query);
+  if (!matches.length) return { found: false, query, headings };
+
+  const [match, ...others] = matches;
+  const start = from == null ? match.line : Math.max(from, match.line);
+  if (start > match.end) {
+    return { found: true, past: true, query, heading: match, from: start, others };
+  }
+  const rows = [];
+  let bytes = 0;
+  for (let n = start; n <= match.end; n++) {
+    bytes += Buffer.byteLength(lines[n - 1]) + 1;
+    if (rows.length >= limits.sectionLines || (rows.length && bytes > limits.sectionBytes)) break;
+    rows.push({ line: n, text: lines[n - 1] });
+  }
+  const to = rows.length ? rows[rows.length - 1].line : start - 1;
+  return {
+    found: true,
+    query,
+    heading: match,
+    from: start,
+    to,
+    next: to < match.end ? to + 1 : null,
+    rows,
+    others,
+  };
+}

package/src/commands.mjs

@@ -109,7 +109,7 @@ const definitions = [
     form('use <name>', { subcommands: ['use'], args: positionals(1, 1) }),
     form('cap <gb>', { subcommands: ['cap'], args: positionals(1, 1) }),
   ]),
-  command('show', none, 'read', [form('<file...>', { args: positionals(1, Infinity), options: [flag('--json')] })]),
+  command('show', none, 'read', [form('<file...>', { args: positionals(1, Infinity), options: [flag('--json'), flag('--card'), flag('--all'), flag('--frontmatter'), value('--section', '-s'), value('--from')] })]),
   command('xref', mutates('the flags log under the state directory with --check --flag; otherwise read-only'), 'read', [
     form('<file...> | --check [--flag]', { args: positionals(0, Infinity), options: [flag('--json'), flag('--check'), flag('--flag')] }),
   ]),
@@ -134,13 +134,14 @@ const definitions = [
     form('use [file]', { subcommands: ['use', 'resume'], args: positionals(0, 1), options: [flag('--no-index'), flag('--show-files'), flag('--force'), flag('--no-claim')] }),
     form('show [file...]', { subcommands: ['show', 'peek'], args: positionals(0, Infinity), options: [flag('--json'), flag('--all'), value('--limit')] }),
     form('archive <file>', { subcommands: ['archive'], args: positionals(1, 1), options: [flag('--no-index'), flag('--show-files')] }),
+    form('link <child...> --parent <resume-name>', { subcommands: ['link'], args: positionals(1, Infinity), options: [value('--parent'), flag('--json')] }),
     form('new <slug> [body...]', { subcommands: ['new'], args: positionals(1, Infinity), options: [value('--body', '--message'), value('--title'), value('--status')] }),
     form('hold <file>', { subcommands: ['hold', 'shelve'], args: positionals(1, 1) }),
     form('unhold <file>', { subcommands: ['unhold', 'unshelve'], args: positionals(1, 1) }),
   ], { aliases: ['prompt'] }),
   command('use', mutates('managed source when starting/consuming; docs remain read-only'), 'workflow', [form('[file]', { args: positionals(0, 1), options: [flag('--json'), flag('--full'), flag('--no-index'), flag('--show-files'), flag('--force'), flag('--no-claim')] })]),
   command('next', mutates('managed prompt source and same-root archive destination'), 'workflow', [form('', { options: [flag('--json'), flag('--no-index'), flag('--show-files'), flag('--force'), flag('--no-claim')] })]),
-  command('baton', mutates('managed plan/prompt sources and managed prompt destination'), 'workflow', [form('[plan|slug] <@<file>|->', { args: positionals(0, 2), options: [value('--status'), value('--note'), value('--body', '--message'), flag('--force'), flag('--replace'), flag('--done'), flag('--subagent'), flag('--json')] })]),
+  command('baton', mutates('managed plan/prompt sources and managed prompt destination'), 'workflow', [form('[plan|slug] <@<file>|->', { args: positionals(0, 2), options: [value('--status'), value('--note'), value('--body', '--message'), value('--parent'), flag('--template'), flag('--force'), flag('--replace'), flag('--done'), flag('--subagent'), flag('--json')] })]),
   command('runlist', mutates('managed hubs/children and managed scaffold destinations'), 'workflow', [
     form('<hub>', { args: positionals(1, 1), options: [flag('--json')] }),
     form('next <hub>', { subcommands: ['next'], args: positionals(1, 1), options: [flag('--json'), flag('--full'), flag('--no-index'), flag('--show-files')] }),
@@ -180,7 +181,7 @@ const definitions = [
   ]),
   command('fix-membership', mutates('managed source sweep'), 'mutate', [form('[hubs...]', { args: positionals(0, Infinity), options: [flag('--json')] })]),
   command('sync-status', mutates('managed source sweep'), 'mutate', [form('[hubs...]', { args: positionals(0, Infinity), options: [flag('--adopt'), flag('--json')] })]),
-  command('doctor', mutates('managed sweeps, repo index, and maintenance config paths by mode'), 'mutate', [form('[path]', { args: positionals(0, 1), options: [flag('--apply', '--yes'), flag('--statuses'), optionalValue('--migrate-template'), flag('--migrate-prompts'), flag('--frontmatter-fix'), flag('--project'), flag('--transactions'), flag('--claims'), flag('--session'), value('--older-than'), flag('--json'), flag('--include-archived')] })]),
+  command('doctor', mutates('managed sweeps, repo index, and maintenance config paths by mode'), 'mutate', [form('[path]', { args: positionals(0, 1), options: [flag('--apply', '--yes'), flag('--statuses'), optionalValue('--migrate-template'), flag('--migrate-prompts'), flag('--frontmatter-fix'), flag('--project'), flag('--prompts'), flag('--transactions'), flag('--claims'), flag('--session'), value('--older-than'), flag('--json'), flag('--include-archived')] })]),
   command('statuses', mutates('project config path; document scan is read-only'), 'mutate', [
     form('list', { subcommands: ['list'], options: [value('--type'), flag('--json')] }),
     form('add <name>', { subcommands: ['add'], args: positionals(1, 1), options: STATUS_PROPERTY_OPTIONS }),

package/src/config.mjs

@@ -88,14 +88,10 @@ const DEFAULTS = {
     skipStaleFor: ['archived', 'reference', 'partial', 'queued-after'],
     skipWarningsFor: ['archived', 'partial', 'queued-after'],
     terminalStatuses: ['archived', 'deprecated', 'reference'],
-    // F15: per-status filing buckets (status → dirName). Built-in held/paused
-    // statuses file under the owning type folder; archive remains a separate
-    // primitive untouched.
-    // Plans only. A paused plan files under <plansDir>/held/ so the live plan
-    // list stays readable. Prompts were removed from this map 2026-08-30 along
-    // with their held/shelved statuses — `archived` is the only directory a
-    // prompt ever moves into.
-    filedStatuses: { paused: 'held' },
+    // Optional status → directory filing. Ordinary status changes keep the
+    // current path by default; archive remains a separate move. Repositories
+    // can opt in here or with per-status `filed: true` / `filed: 'held'`.
+    filedStatuses: {},
     // Types whose archive nests under their own type dir (<typeDir>/<archiveDir>,
     // e.g. docs/prompts/archived/) instead of the shared <root>/<archiveDir>.
     // Prompts are session-local churn — keeping their archive out of the shared
@@ -465,14 +461,24 @@ function deepMerge(defaults, overrides, parentPath = '') {
   return result;
 }
 
-export async function resolveConfig(cwd, explicitConfigPath) {
+// Locate repository data without importing or executing its JavaScript config.
+export function locateConfig(cwd, explicitConfigPath) {
   const configPath = explicitConfigPath
     ? path.resolve(cwd, explicitConfigPath)
     : findConfigFile(cwd);
+  const configDir = configPath && existsSync(configPath) ? path.dirname(configPath) : cwd;
+  let repoRoot = configDir;
+  for (let dir = configDir; dir !== path.parse(dir).root; dir = path.dirname(dir)) {
+    if (existsSync(path.join(dir, '.git'))) { repoRoot = dir; break; }
+  }
+  return {configPath,configDir,repoRoot};
+}
+
+export async function resolveConfig(cwd, explicitConfigPath) {
+  const {configPath,configDir,repoRoot} = locateConfig(cwd, explicitConfigPath);
 
   let userConfig = {};
   let hooks = {};
-  let configDir = cwd;
 
   if (configPath && existsSync(configPath)) {
     const configUrl = pathToFileURL(configPath).href;
@@ -483,8 +489,6 @@ export async function resolveConfig(cwd, explicitConfigPath) {
       die('Failed to load config: ' + configPath + '\n' + err.message + '\nCheck for syntax errors in your config file.');
     }
 
-    configDir = path.dirname(configPath);
-
     for (const [key, value] of Object.entries(mod)) {
       if (key === 'default') continue;
       if (typeof value === 'function') {
@@ -523,20 +527,6 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     }
   }
 
-  // Find repo root by walking up looking for .git
-  let repoRoot = configDir;
-  {
-    let dir = configDir;
-    const fsRoot = path.parse(dir).root;
-    while (dir !== fsRoot) {
-      if (existsSync(path.join(dir, '.git'))) {
-        repoRoot = dir;
-        break;
-      }
-      dir = path.dirname(dir);
-    }
-  }
-
   // Resolve document types
   const typesConfig = config.types ?? {};
   const validTypes = new Set(Object.keys(typesConfig));

package/src/doctor.mjs

@@ -1,4 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
+import { installationReport, formatInstallationReport } from './installation.mjs';
+import { diagnosePromptParents } from './prompt-handoff.mjs';
 import path from 'node:path';
 import { fixBrokenRefs } from './fix-refs.mjs';
 import { runLint } from './lint.mjs';
@@ -235,6 +237,17 @@ function runDoctorSession(argv) {
 }
 
 export function runDoctor(argv, config, opts = {}) {
+  if (argv.includes('--prompts')) {
+    const index=buildIndex(config,{fast:true,invokeHooks:false});
+    const result=diagnosePromptParents(index.docs.filter(doc=>doc.type==='prompt'),config);
+    if(argv.includes('--json'))process.stdout.write(JSON.stringify(result,null,2)+'\n');
+    else {
+      process.stdout.write(`Prompt parent links: ${result.children} child handoffs · ${result.counts.linked??0} explicitly linked\n`);
+      for(const item of result.findings)process.stdout.write(`  ${item.state}: ${item.path}${item.parentPrompt?` → ${item.parentPrompt}`:''}${item.candidates.length?` (${item.candidates.join(', ')})`:''}\n`);
+      if(result.findings.length)process.stdout.write('Inspect with `runlist prompts show <child>`. Repair an existing link with `runlist prompts link <child> --parent <resume-name>`; diagnostics change no prompts.\n');
+    }
+    return result;
+  }
   if (argv.includes('--project')) {
     runDoctorProject(config, { json: argv.includes('--json') });
     return;
@@ -434,6 +447,7 @@ function runDoctorProject(config, { json = false } = {}) {
   const skillDriftWarnings = checkSkillDrift(config);
   const result = {
     cliVersion: cliPackage?.version ?? null,
+    installations: installationReport(config),
     packageDependency: depVersion,
     claudeCommandWarnings,
     deprecatedCommandMentions,
@@ -448,6 +462,7 @@ function runDoctorProject(config, { json = false } = {}) {
   }
 
   process.stdout.write(bold('runlist doctor --project') + '\n\n');
+  process.stdout.write(formatInstallationReport(result.installations)+'\n');
   process.stdout.write(`- running CLI version: ${result.cliVersion ?? 'unknown'}\n`);
   process.stdout.write(`- package dependency: ${result.packageDependency ?? '(none found)'}\n`);
   process.stdout.write(`- stale Claude commands: ${claudeCommandWarnings.length}\n`);

package/src/extractors.mjs

@@ -1,4 +1,5 @@
 import { maskInlineCodeSpans } from './markdown-code-spans.mjs';
+import { walkChecklist } from './section.mjs';
 
 export function extractFirstHeading(body) {
   return body.match(/^#\s+(.+)$/m)?.[1]?.trim() ?? null;
@@ -80,22 +81,14 @@ export function extractBodyLinks(body) {
   return links;
 }
 
+// Boxes inside a code fence are examples, not work, so they are not counted;
+// `runlist show` lists the open ones by the same rule (walkChecklist).
 export function extractChecklistCounts(body) {
-  const matches = [...body.matchAll(/^\s*[-*]\s+\[([ xX~])\]\s+/gm)];
-  let completed = 0;
-  let open = 0;
-
-  for (const match of matches) {
-    if (match[1].toLowerCase() === 'x') {
-      completed += 1;
-    } else {
-      open += 1;
-    }
-  }
-
+  const boxes = walkChecklist(body);
+  const open = boxes.filter(b => b.open).length;
   return {
-    completed,
+    completed: boxes.length - open,
     open,
-    total: completed + open,
+    total: boxes.length,
   };
 }

package/src/flags.mjs

@@ -221,13 +221,15 @@ function placeLabel(flag, config) {
 const severityLabel = s => (s === 'problem' ? red(s) : s === 'warn' ? yellow(s) : dim(s));
 
 // One line for the session-start banner, or null when nothing is open.
-export function flagsHudLine(config, { top = 3 } = {}) {
+// A count for the session-start line; `runlist flags` lists them. Printing the
+// first few flags' text put problems unrelated to the session's task in front
+// of every session, cut mid-sentence.
+export function flagsHudLine(config) {
   let open;
   try { open = openFlags(config); } catch { return null; }
   if (open.length === 0) return null;
   const problems = open.filter(f => f.severity === 'problem').length;
-  const items = open.slice(0, top).map(f => `${f.id} ${f.line != null ? `${f.file}:${f.line}` : f.file} ${f.text.slice(0, 80)}`).join('; ');
-  return `[runlist] ${open.length} open flag${open.length === 1 ? '' : 's'}${problems ? `, ${problems} problem${problems === 1 ? '' : 's'}` : ''}, for awareness: ${items}. List: \`runlist flags\`.`;
+  return `${open.length} open flag${open.length === 1 ? '' : 's'}${problems ? `, ${problems} problem${problems === 1 ? '' : 's'}` : ''}, for awareness: \`runlist flags\` lists them.`;
 }
 
 export function runFlags(argv, config) {