dotmd-cli 0.62.0 → 0.64.0

package/src/init.mjs

@@ -152,6 +152,16 @@ function countMarkdownFiles(dir) {
   return { withFrontmatter, withoutFrontmatter };
 }
 
+// Sensible default stale thresholds (days) for statuses dotmd recognizes, used
+// only to scope the generated config's staleDays to detected statuses. Mirrors
+// the global + per-type defaults in config.mjs DEFAULTS; the repo's own custom
+// statuses are intentionally absent so we don't invent a threshold for vocab we
+// don't understand.
+const KNOWN_STALE_DAYS = {
+  'in-session': 1, active: 14, ready: 14, planned: 30, blocked: 30,
+  scoping: 30, paused: 3, awaiting: 14, draft: 30, review: 14, pending: 30,
+};
+
 function generateDetectedConfig(scan, rootPath) {
   const lines = [`// dotmd.config.mjs — auto-detected from ${scan.docCount} existing docs`, ''];
   lines.push(`export const root = '${rootPath}';`);
@@ -164,6 +174,18 @@ function generateDetectedConfig(scan, rootPath) {
   if (allStatuses.length > 0) {
     lines.push('export const statuses = {');
     lines.push(`  order: [${allStatuses.map(s => `'${s}'`).join(', ')}],`);
+    // Scope staleDays to the detected statuses. `statuses.staleDays` is a
+    // replace-key, so emitting it here stops the resolver from inheriting the
+    // default map (keyed by `ready`/`scoping`/… that this repo may not use) —
+    // which otherwise makes every command warn about statuses the user never
+    // wrote. Only statuses with a sensible known threshold get an entry;
+    // unrecognized ones (the repo's own vocab) are left for the user to tune.
+    const staleEntries = allStatuses.filter(s => s in KNOWN_STALE_DAYS);
+    if (staleEntries.length > 0) {
+      lines.push('  staleDays: {');
+      for (const s of staleEntries) lines.push(`    '${s}': ${KNOWN_STALE_DAYS[s]},`);
+      lines.push('  },');
+    }
     lines.push('};');
     lines.push('');
   }
@@ -333,16 +355,24 @@ export async function runInit(cwd, config, opts = {}) {
   // Claude Code integration. dotmd no longer scaffolds per-repo
   // `.claude/commands/*.md` slash commands — the dotmd plugin's SKILL.md is the
   // canonical agent-facing workflow now, and `dotmd hud` injects this repo's
-  // status vocab at runtime. If a `.claude/` exists, sweep any retired
-  // generated command files (banner-gated, so hand-authored ones survive) and
-  // point the user at the plugin instead.
-  if (existsSync(path.join(cwd, '.claude'))) {
+  // status vocab at runtime.
+  const hasProjectClaude = existsSync(path.join(cwd, '.claude'));
+  // A project `.claude/` proves it; a user-global `~/.claude/` means they run
+  // Claude Code elsewhere, so the plugin nudge is still relevant before this
+  // repo has any `.claude/` of its own (the common greenfield case).
+  const likelyClaudeUser = hasProjectClaude || existsSync(path.join(os.homedir(), '.claude'));
+
+  // If a `.claude/` exists, sweep any retired generated command files
+  // (banner-gated, so hand-authored ones survive).
+  if (hasProjectClaude) {
     const removed = removeGeneratedSlashCommands(cwd, { dryRun });
     for (const r of removed) {
       const verb = dryRun ? 'would remove' : 'removed';
       process.stdout.write(`  ${dryTag}${yellow('clean')}   .claude/commands/${r.name} (retired — ${verb}; guidance ships via the dotmd plugin)\n`);
     }
+  }
 
+  if (likelyClaudeUser) {
     const sessionStart = detectSessionStartHook(cwd);
     if (sessionStart.wired) {
       process.stdout.write(`  ${dim('exists')}  ${sessionStart.file} (SessionStart hook for \`dotmd hud\` already wired)\n`);
@@ -351,6 +381,8 @@ export async function runInit(cwd, config, opts = {}) {
       process.stdout.write(`            travel to every session and subagent automatically:\n\n`);
       process.stdout.write(`              /plugin marketplace add reowens/dotmd\n`);
       process.stdout.write(`              /plugin install dotmd@dotmd\n\n`);
+      process.stdout.write(`            The plugin's hooks call \`dotmd\` on your PATH, so install the CLI\n`);
+      process.stdout.write(`            globally too — ${green('npm i -g dotmd-cli')} (a project devDependency won't power them).\n\n`);
       process.stdout.write(`            Or, without the plugin, wire \`dotmd hud\` at SessionStart by hand —\n`);
       process.stdout.write(`            add to .claude/settings.json (merge into any existing hooks):\n\n`);
       process.stdout.write(`              "hooks": { "SessionStart": [\n`);

package/src/lifecycle.mjs

@@ -236,6 +236,10 @@ export async function runStatus(argv, config, opts = {}) {
       process.stdout.write(`${prefix} Would unfile: ${toRepoPath(filePath, config.repoRoot)} → ${toRepoPath(targetPath, config.repoRoot)}\n`);
       finalPath = targetPath;
     }
+    if (finalPath !== filePath) {
+      const refCount = countRefsToUpdate(filePath, finalPath, config);
+      if (refCount > 0) process.stdout.write(`${prefix} Would update references in ${refCount} file(s)\n`);
+    }
     if ((isArchiving || isUnarchiving || isFiling || isUnfiling) && config.indexPath) {
       process.stdout.write(`${prefix} Would regenerate index\n`);
     }
@@ -286,6 +290,22 @@ export async function runStatus(argv, config, opts = {}) {
     finalPath = targetPath;
   }
 
+  // Any of the four moves above shifts the file's directory, which breaks
+  // relative refs in both directions — links FROM the moved file and inbound
+  // refs TO it from other docs. runArchive repairs both; mirror that here so
+  // the deprecated `dotmd status <file> archived` path and the `dotmd set`
+  // unarchive/file/unfile transitions (which route through runStatus, not
+  // runArchive) don't silently leave dangling links.
+  let selfRefsFixed = false;
+  let inboundRefCount = 0;
+  let inboundRefPaths = [];
+  if (finalPath !== filePath) {
+    selfRefsFixed = updateRefsFromMovedFile(filePath, finalPath, config) > 0;
+    const inbound = updateRefsAfterMove(filePath, finalPath, config);
+    inboundRefCount = inbound.count;
+    inboundRefPaths = inbound.paths;
+  }
+
   // Regen the index on every status change — `active → planned` etc. drift
   // the per-status sections just as much as archive crossings. Archive paths
   // also benefit (replaces the previously-gated regen). `--no-index` skips
@@ -298,10 +318,13 @@ export async function runStatus(argv, config, opts = {}) {
   }
 
   process.stdout.write(`${green(toRepoPath(finalPath, config.repoRoot))}: ${oldStatus ?? 'unknown'} → ${newStatus}\n`);
+  if (selfRefsFixed) process.stdout.write('Updated references in moved file.\n');
+  if (inboundRefCount > 0) process.stdout.write(`Updated references in ${inboundRefCount} file(s).\n`);
 
   if (showFiles) {
     const touched = [filePath];
     if (finalPath !== filePath) touched.push(finalPath);
+    touched.push(...inboundRefPaths);
     if (config.indexPath && !noIndex) touched.push(config.indexPath);
     emitFilesFooter(touched, config);
   }
@@ -434,26 +457,37 @@ export function runArchive(argv, config, opts = {}) {
   const parsed = parseSimpleFrontmatter(frontmatter);
   const oldStatus = asString(parsed.status) ?? 'unknown';
 
+  // Preserve a configured custom archive status (e.g. `done` with archive:true)
+  // when one is threaded through from `dotmd set <archive-status>`. Fall back to
+  // the canonical `archived`, or — if the config has no `archived` at all — its
+  // first declared archive status, so we never write a status the config can't
+  // validate.
+  const archiveStatuses = config.lifecycle.archiveStatuses;
+  const defaultArchiveStatus = archiveStatuses.has('archived')
+    ? 'archived'
+    : (archiveStatuses.values().next().value ?? 'archived');
+  const targetStatus = opts.archiveStatus ?? defaultArchiveStatus;
+
   // Heal stuck frontmatter (issue #13): file is under archiveDir/ but its
   // status hasn't been flipped. Flip in place; don't try to move (it's already
   // archived on disk) and don't refuse — refusal leaves the drift permanent.
   if (inArchiveDir) {
-    if (oldStatus === 'archived') {
+    if (oldStatus === targetStatus) {
       die(`Already archived: ${toRepoPath(filePath, config.repoRoot)}`);
     }
     const today = nowIso();
     const repoPathHeal = toRepoPath(filePath, config.repoRoot);
     if (dryRun) {
       const prefix = dim('[dry-run]');
-      out.write(`${prefix} Would heal frontmatter in place: status: ${oldStatus} → archived, updated: ${today}\n`);
+      out.write(`${prefix} Would heal frontmatter in place: status: ${oldStatus} → ${targetStatus}, updated: ${today}\n`);
       out.write(`${prefix} Would skip git mv (file already under \`${config.archiveDir}/\`)\n`);
       return;
     }
-    updateFrontmatter(filePath, { status: 'archived', updated: today });
+    updateFrontmatter(filePath, { status: targetStatus, updated: today });
     const healEntry = `Archived (frontmatter healed in place from \`${oldStatus}\`)${note ? ` — ${note}` : '.'}`;
     appendVersionHistory(filePath, healEntry, { createSection: Boolean(note) });
     if (!noIndex) regenIndex(config);
-    out.write(`${green('✓ Healed')}: ${repoPathHeal} (${oldStatus} → archived; file already under \`${config.archiveDir}/\`)\n`);
+    out.write(`${green('✓ Healed')}: ${repoPathHeal} (${oldStatus} → ${targetStatus}; file already under \`${config.archiveDir}/\`)\n`);
     const touched = [repoPathHeal];
     if (config.indexPath && !noIndex) touched.push(config.indexPath);
     if (showFiles) emitFilesFooter(touched, config);
@@ -482,7 +516,7 @@ export function runArchive(argv, config, opts = {}) {
     } else if (closeoutAction?.action === 'skip') {
       out.write(`${prefix} \`## Closeout\` section already present — no injection\n`);
     }
-    out.write(`${prefix} Would update frontmatter: status: ${oldStatus} → archived, updated: ${today}\n`);
+    out.write(`${prefix} Would update frontmatter: status: ${oldStatus} → ${targetStatus}, updated: ${today}\n`);
     if (note) {
       out.write(`${prefix} Would append Version History: - **${today}** Archived — ${note}\n`);
     }
@@ -507,7 +541,7 @@ export function runArchive(argv, config, opts = {}) {
     writeFileSync(filePath, `---\n${frontmatter}\n---\n${closeoutAction.newBody}`, 'utf8');
   }
 
-  updateFrontmatter(filePath, { status: 'archived', updated: today });
+  updateFrontmatter(filePath, { status: targetStatus, updated: today });
   appendVersionHistory(filePath, note ? `Archived — ${note}` : 'Archived.', { createSection: Boolean(note) });
 
   mkdirSync(targetDir, { recursive: true });
@@ -591,7 +625,10 @@ export async function runSet(argv, config, opts = {}) {
     const archiveArgs = [filePath];
     if (noIndex) archiveArgs.push('--no-index');
     if (showFiles) archiveArgs.push('--show-files');
-    return runArchive(archiveArgs, config, { dryRun, note });
+    // Preserve the exact target status — a config may name its archive status
+    // `done` (with archive:true) rather than `archived`. Without this, runArchive
+    // would silently rewrite it to `archived`.
+    return runArchive(archiveArgs, config, { dryRun, note, archiveStatus: newStatus });
   }
 
   // `partial` promises a successor tracking the deferred tail. When neither a
@@ -749,6 +786,28 @@ export function runTouch(argv, config, opts = {}) {
   try { config.hooks.onTouch?.({ path: toRepoPath(filePath, config.repoRoot) }, { path: toRepoPath(filePath, config.repoRoot), date: today }); } catch (err) { warn(`Hook 'onTouch' threw: ${err.message}`); }
 }
 
+// Rewrite every frontmatter ref token (a `*.md` path in a YAML list item or an
+// inline scalar, quoted or `>`-prefixed) that points at `oldPath` so it points
+// at `newPath`. Each token is resolved doc-relative *and* repo-relative and
+// compared to oldPath by absolute path — mirroring how the body-link branch and
+// `updateRefsFromMovedFile` resolve refs. This replaces an older substring
+// rewrite (`fm.split(oldRelPath).join(newRelPath)`) that only knew doc-relative
+// paths, so it: left repo-relative cross-dir refs (`docs/plans/child.md` from
+// `docs/rfcs/spec.md`) broken; mangled same-dir repo-relative refs into
+// `docs/plans/../archived/child.md`; and could corrupt a `grandchild.md` ref
+// when archiving `child.md` (suffix match). oldPath no longer exists on disk
+// post-`git mv`, so existsSync-based resolveRefPath can't be used here.
+function rewriteFrontmatterRefs(fm, docDir, oldPath, newPath, repoRoot) {
+  // Exclude [ ] , from the token so flow-array elements (`refs: [a.md, b.md]`)
+  // match individually rather than swallowing the bracket and failing to resolve.
+  return fm.replace(/[^\s"'<>:[\],]+\.md\b/g, (token) => {
+    const docRelAbs = path.resolve(docDir, token);
+    const repoRelAbs = path.resolve(repoRoot, token);
+    if (docRelAbs !== oldPath && repoRelAbs !== oldPath) return token;
+    return path.relative(docDir, newPath).split(path.sep).join('/');
+  });
+}
+
 /**
  * After a file moves (archive/unarchive), update frontmatter references in all
  * docs that pointed to the old location so they point to the new one.
@@ -766,17 +825,7 @@ function updateRefsAfterMove(oldPath, newPath, config) {
     if (!fm) continue;
 
     const docDir = path.dirname(docFile);
-    const oldRelPath = path.relative(docDir, oldPath).split(path.sep).join('/');
-    const newRelPath = path.relative(docDir, newPath).split(path.sep).join('/');
-
-    let newFm = fm;
-    if (newFm.includes(oldRelPath)) {
-      newFm = newFm.split(oldRelPath).join(newRelPath);
-    }
-    const dotSlashOld = './' + oldRelPath;
-    if (newFm.includes(dotSlashOld)) {
-      newFm = newFm.split(dotSlashOld).join(newRelPath);
-    }
+    const newFm = rewriteFrontmatterRefs(fm, docDir, oldPath, newPath, config.repoRoot);
 
     // Body markdown links [text](path.md) or [text](path.md#anchor) pointing
     // at oldPath. resolveRefPath can't be used here: oldPath no longer exists
@@ -815,24 +864,28 @@ function updateRefsFromMovedFile(oldPath, newPath, config) {
   // when the source moves. Without the repo-root fallback, repo-relative refs
   // silently skipped rewriting (existsSync on the doubled doc-relative path
   // returned false).
+  // Token-based: rewrite every `*.md` path that resolved to a real file from
+  // the old location, regardless of YAML shape — block-sequence list items
+  // (`  - ./path.md`), inline scalars (`parent_plan: hub.md`), and flow arrays
+  // (`related_plans: [a.md, b.md]`). Quotes sit outside the matched token, so
+  // `"./path.md"` rewrites in place. Mirrors rewriteFrontmatterRefs (inbound).
   let newFm = frontmatter;
-  const refRegex = /^(\s+-\s+)(\S+\.md)$/gm;
-  newFm = newFm.replace(refRegex, (match, prefix, refPath) => {
-    const absTarget = resolveRefPath(refPath, oldDir, config.repoRoot);
-    if (!absTarget) return match;
-    const newRelPath = path.relative(newDir, absTarget).split(path.sep).join('/');
-    return `${prefix}${newRelPath}`;
+  newFm = newFm.replace(/[^\s"'<>:[\],]+\.md\b/g, (token) => {
+    const absTarget = resolveRefPath(token, oldDir, config.repoRoot);
+    if (!absTarget) return token;
+    return path.relative(newDir, absTarget).split(path.sep).join('/');
   });
 
-  // Fix body markdown links [text](path.md)
+  // Fix body markdown links [text](path.md) and [text](path.md#anchor) — the
+  // trailing fragment is preserved across the rewrite.
   let newBody = body;
-  const linkRegex = /(\[[^\]]*\]\()([^)]+\.md)(\))/g;
-  newBody = newBody.replace(linkRegex, (match, pre, href, post) => {
-    if (href.startsWith('http')) return match;
+  const linkRegex = /(\[[^\]]*\]\()([^)#]+\.md)(#[^)]*)?(\))/g;
+  newBody = newBody.replace(linkRegex, (match, pre, href, frag, post) => {
+    if (/^https?:/i.test(href)) return match;
     const absTarget = resolveRefPath(href, oldDir, config.repoRoot);
     if (!absTarget) return match;
     const newHref = path.relative(newDir, absTarget).split(path.sep).join('/');
-    return `${pre}${newHref}${post}`;
+    return `${pre}${newHref}${frag ?? ''}${post}`;
   });
 
   if (newFm !== frontmatter || newBody !== body) {
@@ -856,8 +909,7 @@ function countRefsToUpdate(oldPath, newPath, config) {
     if (!fm) continue;
 
     const docDir = path.dirname(docFile);
-    const oldRelPath = path.relative(docDir, oldPath).split(path.sep).join('/');
-    const fmHit = fm.includes(oldRelPath) || fm.includes('./' + oldRelPath);
+    const fmHit = rewriteFrontmatterRefs(fm, docDir, oldPath, newPath, config.repoRoot) !== fm;
 
     let bodyHit = false;
     if (!fmHit) {

package/src/new.mjs

@@ -268,6 +268,117 @@ export function readBodyInput(source) {
   return source;
 }
 
+// Slug/title helpers shared by name resolution and runlist child generation.
+function slugify(s) {
+  return s.toLowerCase().replace(/[\s_]+/g, '-').replace(/[^a-z0-9-]/g, '').replace(/-+/g, '-').replace(/^-|-$/g, '');
+}
+function titleize(s) {
+  return s.replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+}
+
+// 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 runlist sprints toward, why now.
+
+## Problem
+
+${bodyInput?.trim() ?? ''}
+
+## Order of operations
+
+${steps}
+
+Pick up the next child with \`dotmd runlist next ${hubSlug}\` — it targets the
+first non-archived child. \`dotmd runlist ${hubSlug}\` shows the sequence + status.
+
+## Version History
+
+- **${today}** Created (runlist 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 `dotmd runlists` reads.
+function coordinationHubBody(title, bodyInput, today) {
+  return `
+# ${title}
+
+> One-paragraph: the domain this hub coordinates and how to read the queue below.
+
+## 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).
+`;
+}
+
+// Minimal child plan stub for a scaffolded runlist child. parent_plan points
+// back at the hub (same dir) so \`dotmd doctor\` is satisfied and the reverse
+// link/graph work; status starts `planned` (queued behind the hub).
+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}
+
+> Runlist child of [${hubTitle}](${hubSlug}.md).
+
+## Problem
+
+
+
+## Version History
+
+- **${today}** Created (runlist child of ${hubSlug}).
+`;
+}
+
 export async function runNew(argv, config, opts = {}) {
   const { dryRun } = opts;
 
@@ -289,9 +400,13 @@ export async function runNew(argv, config, opts = {}) {
   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
   for (let i = 0; i < argv.length; i++) {
     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; }
     // --body is the canonical flag; --message is a back-compat alias.
     if ((argv[i] === '--body' || argv[i] === '--message') && argv[i + 1]) {
       bodyFlagName = argv[i];
@@ -359,6 +474,24 @@ export async function runNew(argv, config, opts = {}) {
     die(`Invalid status \`${status}\` for type \`${typeName}\`\nValid: ${[...effective].join(', ')}`);
   }
 
+  // Runlist/coordination hubs are a plan shape, not a separate type. Guard the
+  // flags to type plan and reject the contradictory combination (a sprint
+  // `runlist:` array vs a prose-first coordination map are different shapes).
+  const isRunlistHub = runlistArg !== null;
+  const isCoordinationHub = coordination;
+  if ((isRunlistHub || isCoordinationHub) && typeName !== 'plan') {
+    die(`--${isRunlistHub ? 'runlist' : 'coordination'} only applies to plans. Use: dotmd new plan <name> --${isRunlistHub ? 'runlist a,b,c' : 'coordination'}`);
+  }
+  if (isRunlistHub && isCoordinationHub) {
+    die('--runlist and --coordination are mutually exclusive: a sprint runlist hub carries an ordered `runlist:` array; a coordination hub is a prose-first map (`execution_mode: coordination`). 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;
@@ -498,6 +631,10 @@ export async function runNew(argv, config, opts = {}) {
 
   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));
+  const childStatus = effective.has('planned') ? 'planned' : status;
+
   // Generate content
   let content;
   const validSurfaces = config.raw?.taxonomy?.surfaces ?? (config.validSurfaces ? [...config.validSurfaces] : null);
@@ -508,7 +645,14 @@ export async function runNew(argv, config, opts = {}) {
   } else {
     let fm = template.frontmatter(status, today, tmplCtx);
     if (bodyFrontmatter) fm = mergeBodyFrontmatter(fm, bodyFrontmatter, typeName);
-    const body = template.body(docTitle, tmplCtx);
+    // Inject the hub-shape frontmatter (runlist array / coordination marker)
+    // on top of the standard plan scaffold, then swap in a purpose-built body.
+    if (isRunlistHub) fm = mergeBodyFrontmatter(fm, { runlist: runlistChildren.map(c => c.file) }, typeName);
+    if (isCoordinationHub) fm = mergeBodyFrontmatter(fm, { execution_mode: 'coordination' }, typeName);
+    let body;
+    if (isRunlistHub) body = runlistHubBody(docTitle, slug, runlistChildren, bodyInput, today);
+    else if (isCoordinationHub) body = coordinationHubBody(docTitle, bodyInput, today);
+    else body = template.body(docTitle, tmplCtx);
     content = `---\n${fm}\n---\n${body}`;
   }
 
@@ -525,9 +669,14 @@ export async function runNew(argv, config, opts = {}) {
     rootHint = `Root: ${chosenLabel} (others: ${others.join(', ')} — pass --root <name> to change)\n`;
   }
 
+  const hubKind = isRunlistHub ? ' (runlist hub)' : isCoordinationHub ? ' (coordination hub)' : '';
+
   if (dryRun) {
     process.stdout.write(`${dim('[dry-run]')} Would create: ${repoPath}\n`);
-    process.stdout.write(`${dim('[dry-run]')} Type: ${typeName}\n`);
+    process.stdout.write(`${dim('[dry-run]')} Type: ${typeName}${hubKind}\n`);
+    for (const c of runlistChildren) {
+      process.stdout.write(`${dim('[dry-run]')} Would create child: ${toRepoPath(path.join(baseDir, c.file), config.repoRoot)}\n`);
+    }
     if (rootHint) process.stdout.write(`${dim('[dry-run]')} ${rootHint}`);
     return;
   }
@@ -536,9 +685,22 @@ export async function runNew(argv, config, opts = {}) {
   mkdirSync(path.dirname(filePath), { recursive: true });
 
   writeFileSync(filePath, content, 'utf8');
-  process.stdout.write(`${green('Created')}: ${repoPath} ${dim(`(${typeName})`)}\n`);
+  process.stdout.write(`${green('Created')}: ${repoPath} ${dim(`(${typeName}${hubKind})`)}\n`);
   if (rootHint) process.stdout.write(dim(rootHint));
 
+  // Scaffold runlist child stubs. An existing child file is never clobbered.
+  const childPaths = [];
+  for (const c of runlistChildren) {
+    const childPath = path.join(baseDir, c.file);
+    if (existsSync(childPath)) {
+      warn(`Runlist child already exists, left as-is: ${toRepoPath(childPath, config.repoRoot)}`);
+      continue;
+    }
+    writeFileSync(childPath, runlistChildContent(c.title, slug, docTitle, childStatus, today), 'utf8');
+    childPaths.push(childPath);
+    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
@@ -564,7 +726,7 @@ export async function runNew(argv, config, opts = {}) {
   regenIndex(config);
 
   if (showFiles) {
-    const touched = [filePath];
+    const touched = [filePath, ...childPaths];
     if (config.indexPath) touched.push(config.indexPath);
     emitFilesFooter(touched, config);
   }

package/src/query.mjs

@@ -77,6 +77,11 @@ export function runFocus(index, argv, config) {
 
 export function runQuery(index, argv, config, opts = {}) {
   const filters = parseQueryArgs(argv);
+  // Global --type/--root are stripped by the dispatcher and applied to the
+  // index before it reaches here; reflect them in the filter echo so JSON
+  // metadata isn't reported as unfiltered when the result set is narrowed.
+  if (opts.type && !filters.types) filters.types = opts.type.split(',').map(v => v.trim()).filter(Boolean);
+  if (opts.root && !filters.root) filters.root = opts.root;
   if (filters.body && !filters.keyword) {
     die('`--body` extends a keyword search into document bodies — pass `--keyword <term>` (or use `dotmd grep <term>`).');
   }
@@ -162,6 +167,7 @@ export function runRunlists(index, argv, config) {
       status: d.status,
       title: d.title,
       childCount: coordination.get(d.path)?.childCount ?? 0,
+      nextPickup: coordination.get(d.path)?.nextPickup ?? null,
       updated: d.updated,
       nextStep: d.nextStep ?? null,
     }));
@@ -782,9 +788,18 @@ function renderCoordinationSection(coordDocs, coordination, maxWidth, total) {
     const statusTag = doc.status && doc.status !== 'active' ? ` ${colorTag(doc.status)}` : '';
     const desc = (doc.nextStep || doc.currentState || doc.title || '').replace(/\s+/g, ' ').trim();
 
+    // Next-pickup (first non-archived ranked child from the body) leads the
+    // description column when one resolves — it's the most actionable cell. Its
+    // status is shown only when it's not the expected `active`.
+    const next = info?.nextPickup;
+    const nextStr = next
+      ? `${green('→')} ${next.label}${next.status && next.status !== 'active' ? dim(` (${next.status})`) : ''}`
+      : '';
+    const nextPart = nextStr ? `${nextStr}  ` : '';
+
     const left = `  ${slug}  ${ageStr}  ${dim(count)}  `;
-    const budget = Math.max(10, maxWidth - visibleLen(left) - visibleLen(statusTag) - 2);
+    const budget = Math.max(10, maxWidth - visibleLen(left) - visibleLen(nextPart) - visibleLen(statusTag) - 2);
     const descR = desc.length > budget ? desc.slice(0, budget - 3) + '...' : desc;
-    process.stdout.write(`${left}${dim(descR)}${statusTag}\n`);
+    process.stdout.write(`${left}${nextPart}${dim(descR)}${statusTag}\n`);
   }
 }