dotmd-cli 0.66.0 → 0.67.0

package/bin/dotmd.mjs

@@ -237,6 +237,8 @@ Lifecycle:
   set <status> <file>               Change a document's status (frontmatter write; archive also moves the file)
   runlist <hub> [next|add|remove|reorder]   Show, walk, or mutate an ordered group of plans (see \`dotmd help runlist\`)
   runlists                          List coordination-hub runlists (the Runlists dashboard)
+  roadmap [<hub>] [next]            Tier-3: show a roadmap (runlists + rolled-up progress), or pick up its next action
+  roadmaps                          List roadmap hubs (the Roadmaps dashboard)
   status <file> <status>            Transition document status (deprecated; prefer \`set\`)
   archive <file>                    Archive (status + move + update refs)
   bulk archive <f1> <f2> ...        Archive multiple files at once
@@ -853,10 +855,15 @@ Scaffolding runlists (plans only):
   --coordination       Create a prose-first coordination hub: \`execution_mode:
                        coordination\` + a \`## Ranked queue\` skeleton (no children).
                        Surfaces in \`dotmd runlists\`, held out of the active count.
-  (\`--runlist\` and \`--coordination\` are mutually exclusive.)
+  --roadmap            Create a tier-3 roadmap hub: \`execution_mode: roadmap\` + a
+                       \`## Runlists\` skeleton. A roadmap composes *runlists* (not
+                       leaf plans) and rolls their done/total up — see
+                       \`dotmd roadmap\`. Wire child runlists via \`related_plans:\`.
+  (\`--runlist\`, \`--coordination\`, \`--roadmap\` are mutually exclusive.)
 
   dotmd new plan auth-revamp --runlist extract,rewrite,cleanup
   dotmd new plan platform --coordination
+  dotmd new plan q3 --roadmap
 
 Plan body variants (plans only — pick one body shape):
   --lite / --minimal   Trimmed plan: Problem → Phases → Version History. Drops
@@ -866,8 +873,8 @@ Plan body variants (plans only — pick one body shape):
   --audit / --findings Audit plan: Problem → Findings (ranked) → Suggested order
                        → Open Questions. The "investigated X, here's what I
                        found" shape, instead of build-up phases.
-  (The body variants and \`--runlist\`/\`--coordination\` are all mutually
-  exclusive — a plan has exactly one body shape.)
+  (The body variants and \`--runlist\`/\`--coordination\`/\`--roadmap\` are all
+  mutually exclusive — a plan has exactly one body shape.)
 
   dotmd new plan quick-fix --lite
   dotmd new plan perf-audit --audit
@@ -1515,6 +1522,30 @@ async function main() {
     runRunlists(index, restArgs, config);
     return;
   }
+  // `dotmd roadmaps` (dashboard over every roadmap hub) and `dotmd roadmap
+  // [<hub>] [next]` (one roadmap, or pick up the next action across its
+  // runlists). The tier-3 layer above `runlists`.
+  if (command === 'roadmaps') {
+    const { buildIndex } = await import('../src/index.mjs');
+    const { runRoadmaps } = await import('../src/roadmap.mjs');
+    const index = buildIndex(config);
+    applyIndexFilters(index);
+    runRoadmaps(index, restArgs, config);
+    return;
+  }
+  if (command === 'roadmap') {
+    const { buildIndex } = await import('../src/index.mjs');
+    const index = buildIndex(config);
+    applyIndexFilters(index);
+    if (restArgs[0] === 'next') {
+      const { runRoadmapNext } = await import('../src/roadmap.mjs');
+      await runRoadmapNext(index, restArgs.slice(1), config, { dryRun });
+      return;
+    }
+    const { runRoadmap } = await import('../src/roadmap.mjs');
+    runRoadmap(index, restArgs, config);
+    return;
+  }
   if (command === 'prompts') {
     const { runPrompts } = await import('../src/prompts.mjs');
     await runPrompts(restArgs, config, { dryRun, verbose });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.66.0",
+  "version": "0.67.0",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, Notion sync, AI summaries.",
   "type": "module",
   "license": "MIT",

package/src/health.mjs

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { buildIndex } from './index.mjs';
 import { bold, dim, green, yellow, red } from './color.mjs';
-import { buildCoordinationIndex, hubLabel } from './runlist.mjs';
+import { buildCoordinationIndex, buildRoadmapIndex, isRoadmapHub, hubLabel } from './runlist.mjs';
 import { isArchivedPath } from './util.mjs';
 
 export function runHealth(argv, config) {
@@ -22,10 +22,16 @@ export function runHealth(argv, config) {
     ...(config.lifecycle?.terminalStatuses ?? []),
   ]);
   const isLiveHub = (d) => coordination.has(d.path) && !closedStatuses.has(d.status) && !isArchivedPath(d.path, config);
-  const runlistHubs = allPlans.filter(isLiveHub)
+  const isLiveRoadmap = (d) => isRoadmapHub(d) && !closedStatuses.has(d.status) && !isArchivedPath(d.path, config);
+  const byAgeDesc = (a, b) => (b.daysSinceUpdate ?? -1) - (a.daysSinceUpdate ?? -1);
+  // Roadmaps (tier-3) get their own tally above Runlists — held out of the
+  // pipeline like coordination hubs, but pointed at via `dotmd roadmaps`.
+  const roadmapHubs = allPlans.filter(isLiveRoadmap).sort(byAgeDesc);
+  const roadmapIndex = roadmapHubs.length > 0 ? buildRoadmapIndex(index, config, { coordination }) : new Map();
+  const runlistHubs = allPlans.filter(d => isLiveHub(d) && !isRoadmapHub(d))
     // Most stale first — health is an aging lens, and it matches `dotmd runlists`'
     // default. Unknown-age hubs sort last so they never top the list.
-    .sort((a, b) => (b.daysSinceUpdate ?? -1) - (a.daysSinceUpdate ?? -1));
+    .sort(byAgeDesc);
   const plans = allPlans.filter(d => !isLiveHub(d));
   const now = Date.now();
 
@@ -87,7 +93,8 @@ export function runHealth(argv, config) {
       ready: { count: readyPlans.length },
       planned: { count: plannedPlans.length },
       recentlyArchived: { count: recentlyArchived.length, last30d: recentlyArchived.map(d => path.basename(d.path, '.md')) },
-      runlists: { count: runlistHubs.length, hubs: runlistHubs.map(d => ({ path: d.path, title: d.title, status: d.status, childCount: coordination.get(d.path)?.childCount ?? 0, nextPickup: coordination.get(d.path)?.nextPickup ?? null })) },
+      runlists: { count: runlistHubs.length, hubs: runlistHubs.map(d => { const info = coordination.get(d.path); return { path: d.path, title: d.title, status: d.status, childCount: info?.childCount ?? 0, total: info?.total ?? 0, doneCount: info?.doneCount ?? 0, parkedCount: info?.parkedCount ?? 0, nextPickup: info?.nextPickup ?? null }; }) },
+      roadmaps: { count: roadmapHubs.length, hubs: roadmapHubs.map(d => { const info = roadmapIndex.get(d.path); return { path: d.path, title: d.title, status: d.status, childCount: info?.childCount ?? 0, grandTotal: info?.grandTotal ?? 0, grandDone: info?.grandDone ?? 0, grandParked: info?.grandParked ?? 0 }; }) },
     }, null, 2) + '\n');
     return;
   }
@@ -114,6 +121,23 @@ export function runHealth(argv, config) {
   }
   process.stdout.write('\n');
 
+  // Roadmaps (tier-3) — pinned above Runlists with the recursive grand total.
+  if (roadmapHubs.length > 0) {
+    process.stdout.write(`${bold('Roadmaps:')} ${roadmapHubs.length}  ${dim('· dotmd roadmap')}\n`);
+    for (const doc of roadmapHubs.slice(0, 8)) {
+      const slug = hubLabel(doc).padEnd(28);
+      const age = doc.daysSinceUpdate != null ? `${doc.daysSinceUpdate}d` : '?d';
+      const info = roadmapIndex.get(doc.path);
+      const rollStr = info ? `  ${dim(`${info.grandDone}/${info.grandTotal}`)}` : '';
+      const kidStr = info ? `  ${dim(`${info.childCount} runlists`)}` : '';
+      process.stdout.write(`  ${slug} ${dim(age.padStart(4))}${rollStr}${kidStr}\n`);
+    }
+    if (roadmapHubs.length > 8) {
+      process.stdout.write(`  ${dim(`...and ${roadmapHubs.length - 8} more`)}\n`);
+    }
+    process.stdout.write('\n');
+  }
+
   // Runlists (coordination hubs) — held out of the leaf-plan pipeline above and
   // surfaced as their own tally so they don't inflate the active count. Newest
   // first, mirroring `dotmd runlists`; capped with a "more" footer.
@@ -123,7 +147,7 @@ export function runHealth(argv, config) {
       const slug = hubLabel(doc).padEnd(28);
       const age = doc.daysSinceUpdate != null ? `${doc.daysSinceUpdate}d` : '?d';
       const info = coordination.get(doc.path);
-      const relStr = info?.childCount ? `  ${dim(`${info.childCount} related`)}` : '';
+      const relStr = info?.total ? `  ${dim(`${info.doneCount}/${info.total}`)}` : '';
       const nextStr = info?.nextPickup ? `  ${green('→')} ${info.nextPickup.label}` : '';
       process.stdout.write(`  ${slug} ${dim(age.padStart(4))}${relStr}${nextStr}\n`);
     }

package/src/index.mjs

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { extractFirstHeading, extractSummary, extractStatusSnapshot, extractNextStep, extractChecklistCounts, extractBodyLinks } from './extractors.mjs';
 import { asString, normalizeStringList, normalizeBlockers, mergeUniqueStrings, toRepoPath, warn, die, resolveDocPath, suggestCandidates } from './util.mjs';
-import { validateDoc, validatePlanShape, validateDocShape, checkBidirectionalReferences, checkGitStaleness, checkRunlistBackPointers, checkCoordinationHubExecutionMode, computeDaysSinceUpdate, computeIsStale, computeChecklistCompletionRate, enrichRefErrorSuggestions } from './validate.mjs';
+import { validateDoc, validatePlanShape, validateDocShape, checkBidirectionalReferences, checkGitStaleness, checkRunlistBackPointers, checkCoordinationHubExecutionMode, checkRoadmapHubExecutionMode, computeDaysSinceUpdate, computeIsStale, computeChecklistCompletionRate, enrichRefErrorSuggestions } from './validate.mjs';
 import { checkIndex } from './index-file.mjs';
 import { checkClaudeCommands } from './claude-commands.mjs';
 import { checkGlossaryConfig } from './glossary-check.mjs';
@@ -128,6 +128,13 @@ export function buildIndex(config, opts = {}) {
       if (hub) hub.warnings.push(w);
     }
 
+    const roadmapHubWarnings = checkRoadmapHubExecutionMode(transformedDocs, config);
+    warnings.push(...roadmapHubWarnings);
+    for (const w of roadmapHubWarnings) {
+      const hub = transformedDocs.find(d => d.path === w.path);
+      if (hub) hub.warnings.push(w);
+    }
+
     const gitWarnings = checkGitStaleness(transformedDocs, config);
     warnings.push(...gitWarnings);
 

package/src/new.mjs

@@ -39,6 +39,25 @@ function modulesScaffold(ctx, kind /* 'doc' | 'plan' */) {
   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`;
+}
+
 const BUILTIN_TEMPLATES = {
   doc: {
     description: 'Reference doc, design note, module overview — build-up shape lite',
@@ -100,18 +119,12 @@ ${ctx?.bodyInput?.trim() ?? ''}
       '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() ?? '';
-      // Full-body shortcut: if the input already authors `## Section` headings,
-      // it's a complete plan body the user/agent wrote start-to-finish. Drop
-      // the scaffold's later sections to avoid duplicate empty `## Goals`,
-      // `## Phases`, etc. below the user's already-filled versions. A bare title
-      // (`# X`) at the head of the body is honored — we don't double-print the
-      // scaffold's title. Otherwise emit the scaffold and slot the body into
-      // `## Problem` as before (section-content mode).
-      if (/^##\s+\S/m.test(bodyInput)) {
-        const hasOwnTitle = /^#\s+\S/.test(bodyInput);
-        return hasOwnTitle ? `\n${bodyInput}\n` : `\n# ${t}\n\n${bodyInput}\n`;
-      }
       return `
 # ${t}
 
@@ -309,7 +322,7 @@ function runlistHubBody(title, hubSlug, children, bodyInput, today) {
 
 ${bodyInput?.trim() ?? ''}
 
-## Order of operations
+## Order of Operations
 
 ${steps}
 
@@ -334,7 +347,7 @@ function coordinationHubBody(title, bodyInput, today) {
 
 ${bodyInput?.trim() ?? ''}
 
-## Ranked queue
+## 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
@@ -350,6 +363,39 @@ graph pick it up. -->
 `;
 }
 
+// Body for a roadmap hub: the tier-3 hub that composes *runlists* (not leaf
+// plans) and rolls their progress up. Mirrors the coordination-hub shape but its
+// ranked rows point at runlists, and `dotmd roadmap` reads it. Children are wired
+// via related_plans: (each should be a runlist / coordination hub).
+function roadmapHubBody(title, hubSlug, bodyInput, today) {
+  return `
+# ${title}
+
+> One-paragraph: the domain this roadmap composes. A roadmap points at *runlists*
+> (not leaf plans) and rolls their done/total up — see \`dotmd roadmap ${hubSlug}\`.
+
+## Scope
+
+${bodyInput?.trim() ?? ''}
+
+## Runlists
+
+<!-- One row per child runlist, in priority order. Wire each into related_plans:
+so the rollup + graph pick it up. Children should be runlists / coordination hubs
+(execution_mode: coordination) or sprint runlist: hubs — not leaf plans.
+Optional horizon flavor: replace this table with ## Now / ## Next / ## Later /
+## Icebox sections, each linking the runlists 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
@@ -393,7 +439,7 @@ function auditPlanBody(title, bodyInput, today) {
 
 ${bodyInput?.trim() ?? ''}
 
-## Findings (ranked)
+## Findings (Ranked)
 
 ### 1. <finding> [impact]
 
@@ -403,7 +449,7 @@ ${bodyInput?.trim() ?? ''}
 
 
 
-## Suggested order
+## Suggested Order
 
 1. <which finding to act on first, and why>
 
@@ -469,6 +515,7 @@ export async function runNew(argv, config, opts = {}) {
   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        → tier-3 roadmap hub skeleton
   let lite = false;          // --lite/--minimal → trimmed plan body
   let audit = false;         // --audit/--findings → ranked-findings plan body
   for (let i = 0; i < argv.length; i++) {
@@ -476,6 +523,7 @@ export async function runNew(argv, config, opts = {}) {
     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.
@@ -552,11 +600,13 @@ export async function runNew(argv, config, opts = {}) {
   // 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);
@@ -732,9 +782,19 @@ export async function runNew(argv, config, opts = {}) {
     // on top of the standard plan scaffold, then swap in a purpose-built body.
     if (isRunlistHub) fm = mergeBodyFrontmatter(fm, { runlist: runlistChildren.map(c => c.file) }, typeName);
     if (isCoordinationHub) fm = mergeBodyFrontmatter(fm, { execution_mode: 'coordination' }, typeName);
+    if (isRoadmap) fm = mergeBodyFrontmatter(fm, { execution_mode: 'roadmap' }, typeName);
     let body;
-    if (isRunlistHub) body = runlistHubBody(docTitle, slug, runlistChildren, bodyInput, today);
+    // A full authored body (own `## Section` headings) wins over every variant
+    // skeleton too — otherwise the whole document gets nested in the builder's
+    // single slot and the skeleton is appended below it (duplicate Scope /
+    // Ranked queue / Version History). The default plan body applies the same
+    // shortcut inside template.body, so only the variant branches need it here.
+    const variantBody = isRunlistHub || isCoordinationHub || isRoadmap || isLite || isAudit;
+    const authored = variantBody ? fullBodyShortcut(docTitle, bodyInput) : null;
+    if (authored !== null) body = authored;
+    else if (isRunlistHub) body = runlistHubBody(docTitle, slug, runlistChildren, bodyInput, today);
     else if (isCoordinationHub) body = coordinationHubBody(docTitle, bodyInput, today);
+    else if (isRoadmap) body = roadmapHubBody(docTitle, slug, bodyInput, today);
     else if (isLite) body = litePlanBody(docTitle, bodyInput, today);
     else if (isAudit) body = auditPlanBody(docTitle, bodyInput, today);
     else body = template.body(docTitle, tmplCtx);
@@ -756,6 +816,7 @@ export async function runNew(argv, config, opts = {}) {
 
   const hubKind = isRunlistHub ? ' (runlist hub)'
     : isCoordinationHub ? ' (coordination hub)'
+    : isRoadmap ? ' (roadmap hub)'
     : isLite ? ' (lite plan)'
     : isAudit ? ' (audit plan)'
     : '';

package/src/query.mjs

@@ -7,7 +7,7 @@ import { getGitLastModifiedBatch } from './git.mjs';
 import { extractFrontmatter } from './frontmatter.mjs';
 import { summarizeDocBody } from './ai.mjs';
 import { bold, dim, yellow, red, green, blue, magenta, cyan, brightYellow } from './color.mjs';
-import { buildRunlistIndex, buildCoordinationIndex, hubLabel } from './runlist.mjs';
+import { buildRunlistIndex, buildCoordinationIndex, buildRoadmapIndex, isRoadmapHub, hubLabel } from './runlist.mjs';
 
 const STATUS_COLORS = {
   'in-session': (s) => bold(red(s)),
@@ -101,7 +101,8 @@ export function runQuery(index, argv, config, opts = {}) {
     // Runlist folding only applies to plans (prompts have no runlists).
     const runlist = opts.preset === 'plans' ? buildRunlistIndex(index, config) : null;
     const coordination = opts.preset === 'plans' ? buildCoordinationIndex(index, config) : null;
-    renderPlansOutput(docs, filters, config, { noun: opts.preset, runlist, coordination });
+    const roadmap = opts.preset === 'plans' ? buildRoadmapIndex(index, config, { coordination, runlist }) : null;
+    renderPlansOutput(docs, filters, config, { noun: opts.preset, runlist, coordination, roadmap });
     if (docs.length === 0) writeUnknownFilterValueHint(filters, index);
     return;
   }
@@ -157,26 +158,41 @@ export function runRunlists(index, argv, config) {
     ...(config.lifecycle?.archiveStatuses ?? []),
     ...(config.lifecycle?.terminalStatuses ?? []),
   ]);
+  // Roadmaps live in `coordination` (held-out-hub plumbing) but are a tier above
+  // runlists — exclude them here; they get their own `dotmd roadmaps` dashboard.
   const hubs = index.docs
-    .filter(d => coordination.has(d.path) && !archived.has(d.status) && !isArchivedPath(d.path, config))
+    .filter(d => coordination.has(d.path) && !isRoadmapHub(d) && !archived.has(d.status) && !isArchivedPath(d.path, config))
     .sort(runlistSorter(sortArg, coordination, config));
+  const roadmapCount = index.docs
+    .filter(d => isRoadmapHub(d) && !archived.has(d.status) && !isArchivedPath(d.path, config)).length;
 
   if (json) {
-    const runlists = hubs.map(d => ({
-      path: d.path,
-      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,
-    }));
+    const runlists = hubs.map(d => {
+      const info = coordination.get(d.path);
+      return {
+        path: d.path,
+        status: d.status,
+        title: d.title,
+        childCount: info?.childCount ?? 0,
+        total: info?.total ?? 0,
+        doneCount: info?.doneCount ?? 0,
+        parkedCount: info?.parkedCount ?? 0,
+        nextPickup: info?.nextPickup ?? null,
+        updated: d.updated,
+        nextStep: d.nextStep ?? null,
+      };
+    });
     process.stdout.write(JSON.stringify({ count: runlists.length, runlists }, null, 2) + '\n');
     return;
   }
 
+  const roadmapPointer = roadmapCount > 0
+    ? dim(`  ${roadmapCount} roadmap${roadmapCount === 1 ? '' : 's'}  ·  dotmd roadmaps\n`)
+    : '';
+
   if (hubs.length === 0) {
     process.stdout.write('No runlists found. A runlist is a plan with `execution_mode: coordination` (or a `*-runlist` slug).\n');
+    if (roadmapPointer) process.stdout.write(roadmapPointer);
     return;
   }
 
@@ -185,6 +201,7 @@ export function runRunlists(index, argv, config) {
   renderCoordinationSection(shown, coordination, maxWidth, hubs.length);
   const hidden = hubs.length - shown.length;
   if (hidden > 0) process.stdout.write(dim(`  ${hidden} more  ·  dotmd runlists --limit ${hubs.length}\n`));
+  if (roadmapPointer) process.stdout.write(roadmapPointer);
   process.stdout.write('\n');
 }
 
@@ -491,9 +508,14 @@ function renderPlansOutput(docs, filters, config, opts = {}) {
   // scoped to the flat triage view; grouped views keep their existing shape.
   const runlist = !grouped ? opts.runlist : null;
   const coordination = !grouped ? opts.coordination : null;
+  const roadmap = !grouped ? opts.roadmap : null;
   // A doc is a "runlist" for header/section purposes if it's either a
   // frontmatter-`runlist:` sprint hub or an `execution_mode: coordination` hub.
+  // Roadmaps are also in `coordination` (held-out-hub plumbing), so they read as
+  // hubs here too — but `isRoadmap` is checked first wherever counts/sections
+  // split, lifting them into their own tier above runlists.
   const isHub = (p) => Boolean(runlist?.hubs.has(p) || coordination?.has(p));
+  const isRoadmap = (p) => Boolean(roadmap?.has(p));
 
   // Summary line: middle-dot separator, ALWAYS based on the full pre-limit
   // pipeline so the top-of-page numbers stay honest when --limit is applied.
@@ -509,10 +531,12 @@ function renderPlansOutput(docs, filters, config, opts = {}) {
   // more active plan. Needs per-doc identity, so recompute from the pre-limit
   // matched set rather than the aggregate counts.
   let hubCount = 0;
+  let roadmapCount = 0;
   let counts;
   if ((runlist?.hubs.size || coordination?.size) && filters._matched) {
     const reclassed = {};
     for (const d of filters._matched) {
+      if (isRoadmap(d.path)) { roadmapCount += 1; continue; }
       if (isHub(d.path)) { hubCount += 1; continue; }
       const s = d.status ?? 'unknown';
       reclassed[s] = (reclassed[s] ?? 0) + 1;
@@ -522,12 +546,13 @@ function renderPlansOutput(docs, filters, config, opts = {}) {
     counts = Object.entries(bySt).sort((a, b) => b[1] - a[1]).map(([s, n]) => `${n} ${s}`);
   }
   const headerParts = [];
+  if (roadmapCount) headerParts.push(`${roadmapCount} roadmap${roadmapCount === 1 ? '' : 's'}`);
   if (hubCount) headerParts.push(`${hubCount} runlist${hubCount === 1 ? '' : 's'}`);
   headerParts.push(...counts);
-  // Hubs are held OUT of the headline plan count — they read as a separate
-  // `N runlist` sibling, never as actionable plans. So "N plans" counts leaves
-  // only and the status segments sum to it (the runlist sibling sits apart).
-  const headlineTotal = totalAll - hubCount;
+  // Hubs (runlists + roadmaps) are held OUT of the headline plan count — they
+  // read as separate siblings, never as actionable plans. So "N plans" counts
+  // leaves only and the status segments sum to it.
+  const headlineTotal = totalAll - hubCount - roadmapCount;
   const header = `${headlineTotal} ${noun}${headerParts.length ? ' · ' + headerParts.join(' · ') : ''}`;
   process.stdout.write(dim(header) + '\n');
 
@@ -575,14 +600,17 @@ function renderPlansOutput(docs, filters, config, opts = {}) {
     // both caps. The Runlists section is pinned — it shows whenever hubs exist,
     // independent of how the leaf list fills up.
     const matched = filters._matched ?? docs;
+    const roadmapAll = [];
     const coordAll = [];
     const mainAll = [];
     for (const d of matched) {
-      if (coordination?.has(d.path)) coordAll.push(d);
+      if (isRoadmap(d.path)) roadmapAll.push(d);
+      else if (coordination?.has(d.path)) coordAll.push(d);
       else mainAll.push(d);
     }
     const mainShown = filters.all ? mainAll : mainAll.slice(0, filters.limit);
     const coordShown = filters.all ? coordAll : coordAll.slice(0, filters.limit);
+    const roadmapShown = filters.all ? roadmapAll : roadmapAll.slice(0, filters.limit);
 
     process.stdout.write('\n');
     if (mainShown.length) {
@@ -595,6 +623,15 @@ function renderPlansOutput(docs, filters, config, opts = {}) {
       process.stdout.write(dim(`  ${mainHidden} more ${noun}  ·  dotmd ${noun} --all  ·  dotmd ${noun} status\n`));
     }
 
+    // Roadmaps tier — pinned above Runlists, with the recursive grand total.
+    if (roadmapShown.length) {
+      renderRoadmapsSection(roadmapShown, roadmap, maxWidth, roadmapAll.length);
+      const roadmapHidden = roadmapAll.length - roadmapShown.length;
+      if (roadmapHidden > 0) {
+        process.stdout.write(dim(`  ${roadmapHidden} more roadmaps  ·  dotmd roadmaps\n`));
+      }
+    }
+
     if (coordShown.length) {
       renderCoordinationSection(coordShown, coordination, maxWidth, coordAll.length);
       const coordHidden = coordAll.length - coordShown.length;
@@ -802,12 +839,36 @@ function renderHubBlock(hub, info, children, maxWidth, topMaxSlug) {
   }
 }
 
+// Roadmap hubs (tier-3) render in their own pinned section above Runlists:
+// label · age · recursive grand done/total · child-runlist count · descriptor.
+// The done/total here is the SUM across the roadmap's child runlists (the real
+// bird's-eye), distinct from the Runlists section's per-hub rollup. `dotmd
+// roadmap <hub>` expands one into its child rows.
+function renderRoadmapsSection(roadmapDocs, roadmap, maxWidth, total) {
+  process.stdout.write(`\n${bold(`Roadmaps (${total ?? roadmapDocs.length})`)} ${dim('· dotmd roadmap')}\n`);
+  const maxSlug = Math.min(34, Math.max(...roadmapDocs.map(d => hubLabel(d).length)));
+  for (const doc of roadmapDocs) {
+    const info = roadmap?.get(doc.path);
+    const slug = hubLabel(doc).padEnd(maxSlug);
+    const age = doc.daysSinceUpdate != null ? `${doc.daysSinceUpdate}d` : '—';
+    const ageStr = doc.daysSinceUpdate != null && doc.isStale ? red(age.padStart(4)) : dim(age.padStart(4));
+    const roll = (info ? `${info.grandDone}/${info.grandTotal}` : '').padStart(8);
+    const kids = info ? `${info.childCount} ${info.childCount === 1 ? 'runlist' : 'runlists'}` : '';
+    const statusTag = doc.status && doc.status !== 'active' ? ` ${colorTag(doc.status)}` : '';
+    const desc = (doc.nextStep || doc.currentState || doc.title || '').replace(/\s+/g, ' ').trim();
+    const left = `  ${slug}  ${ageStr}  ${dim(roll)}  ${dim(kids.padEnd(11))}  `;
+    const budget = Math.max(10, maxWidth - visibleLen(left) - visibleLen(statusTag) - 2);
+    const descR = desc.length > budget ? desc.slice(0, Math.max(0, budget - 3)) + '...' : desc;
+    process.stdout.write(`${left}${dim(descR)}${statusTag}\n`);
+  }
+}
+
 // Coordination hubs (prose-first runlists) render in their own compact section:
-// label · age · rough related-cluster size · one-line descriptor. No fold, no
-// per-row tag — the section header is the signal. The count is the resolved
-// `related_plans:` cluster, which includes peer/parent runlists, so it's
-// labelled `related` (not `plans`) to stay honest. Status shows only when it's
-// not the expected `active` (e.g. a `partial` hub).
+// label · age · done/total rollup · one-line descriptor. No fold, no per-row tag
+// — the section header is the signal. The rollup counts archived vs. resolved
+// `related_plans:` children; that cluster can include peer/parent runlists, so
+// it's a progress hint, not a contract (see buildCoordinationIndex). Status shows
+// only when it's not the expected `active` (e.g. a `partial` hub).
 function renderCoordinationSection(coordDocs, coordination, maxWidth, total) {
   process.stdout.write(`\n${bold(`Runlists (${total ?? coordDocs.length})`)}\n`);
   const maxSlug = Math.min(34, Math.max(...coordDocs.map(d => hubLabel(d).length)));
@@ -816,7 +877,7 @@ function renderCoordinationSection(coordDocs, coordination, maxWidth, total) {
     const slug = hubLabel(doc).padEnd(maxSlug);
     const age = doc.daysSinceUpdate != null ? `${doc.daysSinceUpdate}d` : '—';
     const ageStr = doc.daysSinceUpdate != null && doc.isStale ? red(age.padStart(4)) : dim(age.padStart(4));
-    const count = info?.childCount ? `${String(info.childCount).padStart(2)} related` : '          ';
+    const count = (info?.total ? `${info.doneCount}/${info.total}` : '').padStart(7);
     const statusTag = doc.status && doc.status !== 'active' ? ` ${colorTag(doc.status)}` : '';
     const desc = (doc.nextStep || doc.currentState || doc.title || '').replace(/\s+/g, ' ').trim();
 

package/src/render.mjs

@@ -5,7 +5,7 @@ import { extractFrontmatter } from './frontmatter.mjs';
 import { summarizeDocBody } from './ai.mjs';
 import { bold, red, yellow, green, dim } from './color.mjs';
 import { categorizeWarnings } from './check-collapse.mjs';
-import { buildCoordinationIndex } from './runlist.mjs';
+import { buildCoordinationIndex, isRoadmapHub } from './runlist.mjs';
 
 // Render `currentState` with an `(auto)` prefix when the value was body-scraped
 // rather than read from frontmatter. Lets a reader see at a glance which docs
@@ -342,6 +342,9 @@ export function renderBriefing(index, config) {
     ]);
     const live = plans.filter(p => !closed.has(p.status) && !isArchivedPath(p.path, config));
     const liveHubs = live.filter(isHub);
+    // Roadmaps (tier-3) are held out like runlists but pointed at separately.
+    const liveRoadmaps = live.filter(p => isRoadmapHub(p));
+    const liveRunlists = liveHubs.length - liveRoadmaps.length;
     const liveLeaves = live.length - liveHubs.length;
     const bySt = {};
     for (const p of live) { if (isHub(p)) continue; bySt[p.status] = (bySt[p.status] ?? 0) + 1; }
@@ -358,8 +361,11 @@ export function renderBriefing(index, config) {
       const next = p.nextStep ? `next: ${p.nextStep}` : '(no next step)';
       lines.push(`  > ${path.basename(p.path, '.md')} (${p.status}) ${next}`);
     }
-    if (liveHubs.length) {
-      lines.push(`  ${liveHubs.length} runlist${liveHubs.length === 1 ? '' : 's'} ${dim('· dotmd runlists')}`);
+    if (liveRoadmaps.length) {
+      lines.push(`  ${liveRoadmaps.length} roadmap${liveRoadmaps.length === 1 ? '' : 's'} ${dim('· dotmd roadmaps')}`);
+    }
+    if (liveRunlists) {
+      lines.push(`  ${liveRunlists} runlist${liveRunlists === 1 ? '' : 's'} ${dim('· dotmd runlists')}`);
     }
   }
 

package/src/roadmap.mjs

@@ -0,0 +1,184 @@
+import { buildRoadmapIndex, hubLabel } from './runlist.mjs';
+import { resolveDocArg } from './index.mjs';
+import { toRepoPath, die } from './util.mjs';
+import { bold, dim, green } from './color.mjs';
+
+// Strip ANSI for width math (query.mjs has its own copy but doesn't export it).
+function visibleLen(s) {
+  // eslint-disable-next-line no-control-regex
+  return s.replace(/\x1b\[[0-9;]*m/g, '').length;
+}
+
+// Structured form of one roadmap, shared by every `--json` path.
+function roadmapJson(info) {
+  return {
+    path: info.doc.path,
+    title: info.doc.title ?? null,
+    status: info.doc.status ?? null,
+    childCount: info.childCount,
+    grandTotal: info.grandTotal,
+    grandDone: info.grandDone,
+    grandParked: info.grandParked,
+    children: info.children.map(c => ({
+      path: c.path,
+      label: hubLabel(c.doc),
+      kind: c.kind,
+      total: c.total,
+      doneCount: c.doneCount,
+      parkedCount: c.parkedCount,
+      nextPath: c.nextPath,
+      nextLabel: c.nextLabel,
+    })),
+  };
+}
+
+// One child-runlist row: label · done/total · next → · one-line descriptor.
+function roadmapChildRow(child, maxSlug, maxWidth) {
+  const label = hubLabel(child.doc).padEnd(maxSlug);
+  const roll = `${child.doneCount}/${child.total}`.padStart(7);
+  const next = child.nextLabel ? `${green('→')} ${child.nextLabel}  ` : '';
+  const status = child.doc.status && child.doc.status !== 'active' ? ` ${dim(`[${child.doc.status}]`)}` : '';
+  const desc = (child.doc.nextStep || child.doc.currentState || child.doc.title || '').replace(/\s+/g, ' ').trim();
+  const left = `  ${label}  ${dim(roll)}  `;
+  const budget = Math.max(10, maxWidth - visibleLen(left) - visibleLen(next) - visibleLen(status) - 2);
+  const descR = desc.length > budget ? desc.slice(0, Math.max(0, budget - 3)) + '...' : desc;
+  return `${left}${next}${dim(descR)}${status}`;
+}
+
+// Full single-roadmap view: header with the recursive grand total, then one row
+// per child runlist (its own done/total + that runlist's next pickup).
+function renderRoadmap(info, maxWidth) {
+  const lines = [];
+  const pct = info.grandTotal > 0 ? Math.round((info.grandDone / info.grandTotal) * 100) : 0;
+  const parked = info.grandParked > 0 ? `  ${dim(`${info.grandParked} parked`)}` : '';
+  lines.push(`${bold(`Roadmap: ${info.doc.title || hubLabel(info.doc)}`)}   ${bold(`${info.grandDone}/${info.grandTotal}`)} ${dim(`(${pct}%)`)}${parked}`);
+  if (info.children.length === 0) {
+    lines.push(dim('  (no child runlists — wire runlists into related_plans:)'));
+    return lines.join('\n') + '\n';
+  }
+  const maxSlug = Math.min(34, Math.max(...info.children.map(c => hubLabel(c.doc).length)));
+  for (const c of info.children) lines.push(roadmapChildRow(c, maxSlug, maxWidth));
+  return lines.join('\n') + '\n';
+}
+
+const NO_ROADMAPS = 'No roadmaps found. A roadmap is a plan with `execution_mode: roadmap` that composes runlists.\nScaffold one: dotmd new plan <name> --roadmap\n';
+
+// `dotmd roadmaps` — the dashboard over every roadmap hub (mirrors `dotmd
+// runlists`): one row per roadmap with its recursive grand total + child count.
+export function runRoadmaps(index, argv, config) {
+  const json = argv.includes('--json');
+  const roadmaps = [...buildRoadmapIndex(index, config).values()]
+    .sort((a, b) => (b.doc.daysSinceUpdate ?? 0) - (a.doc.daysSinceUpdate ?? 0));
+
+  if (json) {
+    process.stdout.write(JSON.stringify({ count: roadmaps.length, roadmaps: roadmaps.map(roadmapJson) }, null, 2) + '\n');
+    return;
+  }
+  if (roadmaps.length === 0) {
+    process.stdout.write(NO_ROADMAPS);
+    return;
+  }
+  process.stdout.write(`\n${bold(`Roadmaps (${roadmaps.length})`)}\n`);
+  const maxSlug = Math.min(34, Math.max(...roadmaps.map(r => hubLabel(r.doc).length)));
+  for (const info of roadmaps) {
+    const slug = hubLabel(info.doc).padEnd(maxSlug);
+    const age = info.doc.daysSinceUpdate != null ? `${info.doc.daysSinceUpdate}d` : '—';
+    const roll = `${info.grandDone}/${info.grandTotal}`.padStart(8);
+    const kids = dim(`${info.childCount} ${info.childCount === 1 ? 'runlist' : 'runlists'}`);
+    process.stdout.write(`  ${slug}  ${dim(age.padStart(4))}  ${dim(roll)}  ${kids}\n`);
+  }
+  process.stdout.write('\n');
+}
+
+// `dotmd roadmap [<hub>]` — the single-roadmap view. No arg: show the sole
+// roadmap, or fall back to the `roadmaps` dashboard when there are several.
+export function runRoadmap(index, argv, config) {
+  const json = argv.includes('--json');
+  const positional = argv.filter(a => !a.startsWith('-') && a !== 'next');
+  const hubArg = positional[0] ?? null;
+
+  const roadmaps = buildRoadmapIndex(index, config);
+
+  if (hubArg) {
+    const abs = resolveDocArg(hubArg, config, { dieOnMiss: false });
+    if (!abs) die(`Roadmap not found: ${hubArg}`);
+    const repoPath = toRepoPath(abs, config.repoRoot);
+    const info = roadmaps.get(repoPath);
+    if (!info) {
+      die(`${repoPath} is not a roadmap hub (needs \`execution_mode: roadmap\`).\n` +
+        `See \`dotmd roadmaps\` for roadmaps, or \`dotmd runlist ${hubArg}\` if it's a runlist.`);
+    }
+    if (json) { process.stdout.write(JSON.stringify(roadmapJson(info), null, 2) + '\n'); return; }
+    process.stdout.write('\n' + renderRoadmap(info, process.stdout.columns || 100) + '\n');
+    return;
+  }
+
+  if (roadmaps.size === 0) {
+    if (json) { process.stdout.write(JSON.stringify({ count: 0, roadmaps: [] }, null, 2) + '\n'); return; }
+    process.stdout.write(NO_ROADMAPS);
+    return;
+  }
+  if (roadmaps.size === 1) {
+    const info = [...roadmaps.values()][0];
+    if (json) { process.stdout.write(JSON.stringify(roadmapJson(info), null, 2) + '\n'); return; }
+    process.stdout.write('\n' + renderRoadmap(info, process.stdout.columns || 100) + '\n');
+    return;
+  }
+  // Several roadmaps and no target named → the dashboard.
+  return runRoadmaps(index, argv, config);
+}
+
+// Resolve which roadmap a `next` / pickup verb targets: an explicit hub arg, or
+// the sole roadmap when there's exactly one. Dies with an actionable message
+// otherwise (none → scaffold; several → name one).
+function resolveRoadmapTarget(roadmaps, hubArg, config) {
+  if (hubArg) {
+    const abs = resolveDocArg(hubArg, config, { dieOnMiss: false });
+    if (!abs) die(`Roadmap not found: ${hubArg}`);
+    const info = roadmaps.get(toRepoPath(abs, config.repoRoot));
+    if (!info) die(`${hubArg} is not a roadmap hub (needs \`execution_mode: roadmap\`).`);
+    return info;
+  }
+  if (roadmaps.size === 0) die('No roadmaps found. Scaffold one: dotmd new plan <name> --roadmap');
+  if (roadmaps.size > 1) {
+    const listed = [...roadmaps.values()].map(r => `  ${hubLabel(r.doc)}`).join('\n');
+    die(`Multiple roadmaps — name one: dotmd roadmap next <hub>\n${listed}`);
+  }
+  return [...roadmaps.values()][0];
+}
+
+// `dotmd roadmap [<hub>] next` — the cross-runlist next-pickup. Walk the
+// roadmap's child runlists in `related_plans` (priority) order and open the FIRST
+// startable plan found inside any of them — the "what do I do next across the
+// whole roadmap?" verb. Each child's `nextPath` was already resolved by
+// buildRoadmapIndex (sprint via its runlist order, coordination via its body
+// order, a leaf-plan child = itself). When nothing is startable anywhere, list
+// each child runlist with why, so the blocker is visible.
+export async function runRoadmapNext(index, argv, config, opts = {}) {
+  const json = argv.includes('--json');
+  const hubArg = argv.find(a => !a.startsWith('-')) ?? null;
+  const roadmaps = buildRoadmapIndex(index, config);
+  const info = resolveRoadmapTarget(roadmaps, hubArg, config);
+
+  const target = info.children.find(c => c.nextPath);
+  if (!target) {
+    const lines = info.children.map(c => {
+      const state = c.total === 0 ? 'empty'
+        : c.doneCount >= c.total ? 'all done'
+        : c.parkedCount > 0 ? `${c.parkedCount} parked` : 'no pickup-able child';
+      return `  ${hubLabel(c.doc)} (${c.doneCount}/${c.total} · ${state})`;
+    }).join('\n');
+    die(`No pickup-able plan across roadmap ${hubLabel(info.doc)} — every child runlist is done or parked:\n${lines}\n` +
+      `Unstick one (e.g. \`dotmd set active <child>\`), or inspect a runlist: \`dotmd runlist <hub>\`.`);
+  }
+
+  if (!json) {
+    process.stdout.write(dim(`roadmap ${hubLabel(info.doc)} → ${hubLabel(target.doc)} → next pickup:\n`));
+  }
+  const { startPlan } = await import('./lifecycle.mjs');
+  const startArgs = [target.nextPath];
+  if (argv.includes('--full')) startArgs.push('--full');
+  if (argv.includes('--no-index')) startArgs.push('--no-index');
+  if (json) startArgs.push('--json');
+  await startPlan(startArgs, config, opts);
+}

package/src/runlist.mjs

@@ -105,11 +105,28 @@ export function buildRunlistIndex(index, config) {
 export function isCoordinationHub(doc) {
   if (!doc) return false;
   if (doc.type && doc.type !== 'plan') return false;
-  if (doc.executionMode === 'coordination') return true;
+  // Broad "held-out navigational hub" predicate: both coordination hubs and the
+  // tier-3 roadmap (`execution_mode: roadmap`) are lifted out of the active count
+  // and into a hub section. `isRoadmapHub` is the finer split the tier-3 views
+  // use to promote a roadmap above the Runlists section; here a roadmap counts as
+  // a coordination hub so all the existing held-out plumbing covers it for free.
+  if (doc.executionMode === 'coordination' || doc.executionMode === 'roadmap') return true;
   const base = (doc.path.split('/').pop() || '').replace(/\.md$/, '');
   return base === 'runlist' || base.endsWith('-runlist');
 }
 
+// A *roadmap* is the tier-3 hub: a coordination hub whose children are themselves
+// hubs (runlists / coordination hubs), with progress rolled up across them. The
+// signal is explicit — `execution_mode: roadmap` — with NO slug-convention
+// fallback (unlike coordination hubs' `*-runlist`): there's no naming convention
+// for roadmaps, and `dotmd check` nudges the structural case (a coordination hub
+// that points at other hubs) toward the explicit field rather than auto-promoting.
+export function isRoadmapHub(doc) {
+  if (!doc) return false;
+  if (doc.type && doc.type !== 'plan') return false;
+  return doc.executionMode === 'roadmap';
+}
+
 // Map each coordination hub to a `childCount` derived from its `related_plans:`
 // cluster (resolved against the index; peers/self excluded). It's an
 // approximation — `related_plans` is a *related* cluster, not a strict child
@@ -140,19 +157,128 @@ export function buildCoordinationIndex(index, config) {
     if (!isCoordinationHub(doc)) continue;
     const dir = path.dirname(path.join(config.repoRoot, doc.path));
     const refs = doc.refFields?.related_plans ?? [];
+    // Resolve the `related_plans` cluster to child plan docs (deduped by path;
+    // self and non-plans excluded). This is the membership set the rollup counts
+    // over — `related_plans` is the only child signal a prose-first coordination
+    // hub carries in frontmatter (its *body* order drives next-pickup, not
+    // membership). It's an approximation — a *related* cluster can include peer
+    // or parent runlists — so the done/total is a progress hint, not a contract.
     const childPaths = new Set();
+    const children = [];
     for (const ref of refs) {
       const child = resolveRef(ref, dir);
-      if (child && child.path !== doc.path && (child.type === 'plan' || child.type == null)) {
-        childPaths.add(child.path);
-      }
+      if (!child || child.path === doc.path) continue;
+      if (!(child.type === 'plan' || child.type == null)) continue;
+      if (childPaths.has(child.path)) continue;
+      childPaths.add(child.path);
+      const archived = archiveStatuses.has(child.status) || isArchivedPath(child.path, config);
+      children.push({ path: child.path, status: child.status ?? null, archived });
     }
+    // Rollup, mirroring buildRunlistIndex: done = archived; parked = live but not
+    // startable (blocked/partial/paused/awaiting/queued-after). `childCount`
+    // stays an alias of `total` so existing callers (sorters, JSON) keep working.
+    const doneCount = children.filter(c => c.archived).length;
+    const parkedCount = children.filter(c => !c.archived && !isPickupable(c.status)).length;
     const nextPickup = resolveHubNextPickup(doc, dir, resolveRef, archiveStatuses, config);
-    hubs.set(doc.path, { doc, childCount: childPaths.size, childPaths, nextPickup });
+    hubs.set(doc.path, {
+      doc,
+      childCount: childPaths.size,
+      total: childPaths.size,
+      doneCount,
+      parkedCount,
+      childPaths,
+      children,
+      nextPickup,
+    });
   }
   return hubs;
 }
 
+// Build the tier-3 rollup. For each roadmap hub, resolve its children (the
+// `related_plans:` cluster, exactly like a coordination hub's membership) and
+// roll each child's own done/total up into a grand total. A child that is itself
+// a hub contributes its hub rollup — sprint via `buildRunlistIndex`, coordination
+// via `buildCoordinationIndex`; a plain-plan child contributes one unit. The
+// grand total is the SUM of the children's totals (not a deduped union), so it
+// always equals the sum of the per-child rows the dashboard renders — two child
+// runlists that share a plan double-count it, the same "progress hint, not a
+// contract" approximation coordination-hub rollup already carries.
+//
+// Reuses precomputed `coordination` / `runlist` indexes when the caller has them
+// (the views build coordination already); otherwise builds what it needs. Returns
+//   Map<roadmapPath, { doc, children, childCount, grandTotal, grandDone, grandParked }>
+// with each child = { doc, path, kind: 'runlist'|'coordination'|'plan', total,
+// doneCount, parkedCount, nextPath, nextLabel } in `related_plans` order.
+export function buildRoadmapIndex(index, config, precomputed = {}) {
+  const roadmaps = index.docs.filter(isRoadmapHub);
+  if (roadmaps.length === 0) return new Map();
+
+  const coordination = precomputed.coordination ?? buildCoordinationIndex(index, config);
+  const runlist = precomputed.runlist ?? buildRunlistIndex(index, config);
+  const archiveStatuses = config.lifecycle?.archiveStatuses ?? new Set(['archived']);
+
+  const docByPath = new Map(index.docs.map(d => [d.path, d]));
+  const byBasename = new Map();
+  for (const d of index.docs) {
+    const base = d.path.split('/').pop();
+    if (!byBasename.has(base)) byBasename.set(base, d);
+  }
+  const resolveRef = (ref, dir) => {
+    const abs = resolveRefPath(ref, dir, config.repoRoot);
+    let child = abs ? docByPath.get(toRepoPath(abs, config.repoRoot)) ?? null : null;
+    if (!child) child = byBasename.get(ref.split('/').pop()) ?? null;
+    return child;
+  };
+
+  // Rollup numbers for one child of a roadmap, dispatched by what the child IS:
+  // a sprint runlist hub, a coordination hub, or a plain leaf plan. `nextPath` /
+  // `nextLabel` give a uniform per-child next-pickup target — the first startable
+  // plan *inside* that child — feeding both the `dotmd roadmap` view and the
+  // Phase-4 cross-runlist `dotmd roadmap next` (walk children → first nextPath).
+  const childRollup = (child) => {
+    if (runlist.hubs.has(child.path)) {
+      const h = runlist.hubs.get(child.path);
+      const nextPath = h.nextChildPath ?? null;
+      return { kind: 'runlist', total: h.total, doneCount: h.doneCount, parkedCount: h.parkedCount,
+        nextPath, nextLabel: nextPath ? path.basename(nextPath, '.md') : null };
+    }
+    if (coordination.has(child.path)) {
+      const h = coordination.get(child.path);
+      return { kind: 'coordination', total: h.total, doneCount: h.doneCount, parkedCount: h.parkedCount,
+        nextPath: h.nextPickup?.path ?? null, nextLabel: h.nextPickup?.label ?? null };
+    }
+    // A leaf-plan child is its own next action when it's startable.
+    const archived = archiveStatuses.has(child.status) || isArchivedPath(child.path, config);
+    const parked = !archived && !isPickupable(child.status);
+    const pickupable = !archived && isPickupable(child.status);
+    return { kind: 'plan', total: 1, doneCount: archived ? 1 : 0, parkedCount: parked ? 1 : 0,
+      nextPath: pickupable ? child.path : null, nextLabel: pickupable ? toSlug(child) : null };
+  };
+
+  const out = new Map();
+  for (const doc of roadmaps) {
+    const dir = path.dirname(path.join(config.repoRoot, doc.path));
+    const refs = doc.refFields?.related_plans ?? [];
+    const seen = new Set();
+    const children = [];
+    let grandTotal = 0, grandDone = 0, grandParked = 0;
+    for (const ref of refs) {
+      const child = resolveRef(ref, dir);
+      if (!child || child.path === doc.path) continue;
+      if (!(child.type === 'plan' || child.type == null)) continue;
+      if (seen.has(child.path)) continue;
+      seen.add(child.path);
+      const roll = childRollup(child);
+      grandTotal += roll.total;
+      grandDone += roll.doneCount;
+      grandParked += roll.parkedCount;
+      children.push({ doc: child, path: child.path, ...roll });
+    }
+    out.set(doc.path, { doc, children, childCount: children.length, grandTotal, grandDone, grandParked });
+  }
+  return out;
+}
+
 // Conventional container dirs whose name adds no disambiguation to a hub label.
 const HUB_CONTAINER_DIRS = new Set(['plans', 'prompts', 'archive', 'archived']);
 
@@ -339,7 +465,7 @@ function renderRunlist(hubRepoPath, children, opts = {}) {
   const lines = [];
   lines.push(bold(`runlist: ${hubRepoPath}`));
   if (children.length === 0) {
-    lines.push(dim('  (empty — add child plan paths to the hub plan\'s `runlist:` field, or add markdown links under `## Order of operations`)'));
+    lines.push(dim('  (empty — add child plan paths to the hub plan\'s `runlist:` field, or add markdown links under `## Order of Operations`)'));
     return lines.join('\n') + '\n';
   }
   if (opts.source === 'body') {
@@ -500,7 +626,7 @@ async function runRunlistAdd(positional, config, { dryRun, json }) {
   if (isCoord && existingRefs.length === 0) {
     die(
       `${hubRepoPath} is a coordination hub (execution_mode: coordination) — it keeps its order in the body\n` +
-      `(\`## Ranked queue\` table or \`## Order of operations\` list), not a \`runlist:\` array.\n` +
+      `(\`## Ranked Queue\` table or \`## Order of Operations\` list), not a \`runlist:\` array.\n` +
       `Add the plan as a ranked row/link there. \`runlist add\` manages sprint \`runlist:\` arrays.`,
     );
   }

package/src/validate.mjs

@@ -448,7 +448,10 @@ export function checkCoordinationHubExecutionMode(docs, config) {
   for (const doc of docs) {
     if (doc.type && doc.type !== 'plan') continue;
     if (skipStatuses.has(doc.status)) continue;
-    if (doc.executionMode === 'coordination') continue;
+    // A roadmap (`execution_mode: roadmap`) is already an explicit held-out hub —
+    // just a tier up. Don't nudge it toward `coordination` even when its slug is
+    // `*-runlist` (e.g. a `master-runlist` promoted to a roadmap).
+    if (doc.executionMode === 'coordination' || doc.executionMode === 'roadmap') continue;
     const base = (doc.path.split('/').pop() || '').replace(/\.md$/, '');
     if (base !== 'runlist' && !base.endsWith('-runlist')) continue;
     warnings.push({
@@ -460,6 +463,62 @@ export function checkCoordinationHubExecutionMode(docs, config) {
   return warnings;
 }
 
+// Roadmap-hub nudge: a coordination hub whose `related_plans:` children are
+// *themselves* hubs (runlists / coordination hubs) is structurally a tier-3
+// roadmap — dotmd renders it flat (a hub among its own children, no recursive
+// rollup) until `execution_mode: roadmap` is set. Nudge, never auto-promote: the
+// explicit field beats structural magic for a primitive (Open Q in the
+// roadmap-layer plan). Fires only when ≥2 children AND a majority are hubs, so a
+// coordination hub that merely references one sibling runlist isn't mislabelled.
+export function checkRoadmapHubExecutionMode(docs, config) {
+  const warnings = [];
+  const skipStatuses = new Set([
+    ...(config.lifecycle.terminalStatuses ?? []),
+    ...(config.lifecycle.skipWarningsFor ?? []),
+  ]);
+  const byPath = new Map(docs.map(d => [d.path, d]));
+  const byBasename = new Map();
+  for (const d of docs) {
+    const base = d.path.split('/').pop();
+    if (!byBasename.has(base)) byBasename.set(base, d);
+  }
+  const looksLikeHub = (d) => {
+    if (!d) return false;
+    if (d.executionMode === 'coordination' || d.executionMode === 'roadmap') return true;
+    if (Array.isArray(d.refFields?.runlist) && d.refFields.runlist.length > 0) return true;
+    const b = (d.path.split('/').pop() || '').replace(/\.md$/, '');
+    return b === 'runlist' || b.endsWith('-runlist');
+  };
+  for (const doc of docs) {
+    if (doc.type && doc.type !== 'plan') continue;
+    if (skipStatuses.has(doc.status)) continue;
+    if (doc.executionMode === 'roadmap') continue;       // already a roadmap
+    if (doc.executionMode !== 'coordination') continue;  // only nudge explicit coordination hubs
+    const refs = doc.refFields?.related_plans ?? [];
+    if (refs.length === 0) continue;
+    const dir = path.dirname(path.join(config.repoRoot, doc.path));
+    let resolved = 0, hubChildren = 0;
+    const seen = new Set();
+    for (const ref of refs) {
+      const abs = resolveRefPath(ref, dir, config.repoRoot);
+      let child = abs ? byPath.get(toRepoPath(abs, config.repoRoot)) ?? null : null;
+      if (!child) child = byBasename.get(ref.split('/').pop()) ?? null;
+      if (!child || child.path === doc.path || seen.has(child.path)) continue;
+      seen.add(child.path);
+      resolved++;
+      if (looksLikeHub(child)) hubChildren++;
+    }
+    if (hubChildren >= 2 && hubChildren > resolved / 2) {
+      warnings.push({
+        path: doc.path,
+        level: 'warning',
+        message: `is a coordination hub whose ${hubChildren} of ${resolved} \`related_plans:\` children are themselves runlists — that's structurally a tier-3 roadmap. Set \`execution_mode: roadmap\` so \`dotmd roadmap\` rolls their progress up (recursive done/total) instead of rendering it flat among them.`,
+      });
+    }
+  }
+  return warnings;
+}
+
 export function checkGitStaleness(docs, config) {
   const warnings = [];
   const gitDates = getGitLastModifiedBatch(config.repoRoot);