dotmd-cli 0.60.0 → 0.62.0

package/src/hud.mjs

@@ -8,6 +8,7 @@ import { buildIndex } from './index.mjs';
 import { refreshStaleSlashCommands } from './claude-commands.mjs';
 import { readJournalEntries, journalFilePath, readMisuseEntries } from './journal.mjs';
 import { compareVersions } from './update.mjs';
+import { findOwnedPlan } from './baton.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
@@ -51,6 +52,8 @@ export function actionablePromptStatuses(config) {
   return new Set(['pending']);
 }
 
+// Returns repo paths, oldest-created first — the same order no-arg `dotmd use`
+// consumes them, so prompts[0] is always "the one you'd pick up next".
 function findActionablePrompts(config) {
   const roots = config.docsRoots || (config.docsRoot ? [config.docsRoot] : []);
   const archiveDir = config.archiveDir || 'archived';
@@ -80,11 +83,13 @@ function findActionablePrompts(config) {
       const fm = parseSimpleFrontmatter(frontmatter);
       if (asString(fm.type) !== 'prompt') continue;
       if (!actionable.has(asString(fm.status))) continue;
-      found.push(toRepoPath(filePath, config.repoRoot));
+      found.push({ path: toRepoPath(filePath, config.repoRoot), created: asString(fm.created) ?? '' });
     }
   }
 
-  return found.sort();
+  return found
+    .sort((a, b) => a.created.localeCompare(b.created) || a.path.localeCompare(b.path))
+    .map(p => p.path);
 }
 
 // F17b: hud reads journal. Three additive sections, gated on
@@ -200,8 +205,8 @@ const MISUSE_RECAP_THRESHOLD = 3;
 
 const MISUSE_CORRECTIONS = {
   'edit-status': 'never hand-edit `status:`; use `dotmd set <status> <file>`',
-  'cat-prompt': 'read saved prompts with `dotmd use <file>`',
-  'read-prompt': 'read saved prompts with `dotmd use <file>`',
+  'cat-prompt': 'consume prompts with `dotmd use <file>`; peek without consuming via `dotmd prompts show <file>`',
+  'read-prompt': 'consume prompts with `dotmd use <file>`; peek without consuming via `dotmd prompts show <file>`',
   'commit-prompt': 'saved prompts are session-local; never git add/commit them',
 };
 
@@ -235,6 +240,10 @@ export function buildHud(config) {
   // SessionStart for platform-scale corpora. Per-file validation + checkIndex
   // still run, so the error count matches `dotmd check`'s.
   let errors = 0;
+  // `owned` answers "which plan is THIS session's?" for programmatic callers
+  // (the baton flow reads it) — derived from the journal, falling back to the
+  // only in-session plan. Null when there's no defensible answer.
+  let owned = null;
   try {
     // `autoHealIndex: true` mirrors `dotmd check` — drift from non-regen
     // mutation paths (`lint --fix`, direct file edits, etc.) heals silently
@@ -242,12 +251,14 @@ export function buildHud(config) {
     // spurious "Run `dotmd index`" error in the hud error count.
     const index = buildIndex(config, { errorsOnly: true, autoHealIndex: true });
     errors = index.errors.length;
+    const o = findOwnedPlan(config, index);
+    if (o.plan) owned = { path: o.plan.path, title: o.plan.title ?? null, via: o.via };
   } catch { /* swallow — bad config shouldn't break the SessionStart hook */ }
 
   const { previousSelf, fleet, recentRejections } = buildJournalSections(config);
   const misuseRecap = buildMisuseRecap(config);
 
-  return { prompts, errors, previousSelf, fleet, recentRejections, misuseRecap };
+  return { owned, prompts, errors, previousSelf, fleet, recentRejections, misuseRecap };
 }
 
 // Subagent primer: a spawned subagent (Explore, Plan, general-purpose) starts
@@ -311,19 +322,30 @@ export function runHud(argv, config) {
     return;
   }
 
-  // SessionStart contract: emit ONLY the command primer — the verb cheat-sheet
-  // that tells the agent which dotmd verbs exist. Everything else hud used to
-  // print (held/prompts/stuck/errors state, slash-command refresh notices, and
-  // the journal-aware previous-self / fleet / recent-rejections sections) is
-  // deliberately suppressed here: those signals nudged agents into phantom
-  // follow-up work — e.g. "errors: 1 (run dotmd check)" prompting a check run
-  // for state that belongs inside its own command. Each of those signals lives
-  // in its proper command (`plans`, `prompts`, `check`) and stays available via
-  // `dotmd hud --json` for programmatic callers. The hook's job is purely to
-  // teach the verbs, never to report status. The misuse recap below is the one
-  // exception because it IS teaching: a repeat-offense rule means the primer
-  // alone isn't landing, so name the specific habit to break.
-  process.stdout.write(dim('dotmd: plans|briefing  set <status> [<file>]  new <type> <slug>  use [<file>]  archive <file>  (use [no-arg] → oldest pending prompt)') + '\n');
+  // SessionStart contract: the command primer, plus ONLY signals that carry a
+  // direct instruction for this session. Passive state (error counts,
+  // slash-command refresh notices, previous-self / fleet / recent-rejections)
+  // stays suppressed — those nudged agents into phantom follow-up work (e.g.
+  // "errors: 1" prompting a check run) and live in their proper commands and
+  // `dotmd hud --json`. Two signals ARE instructions and must print, because
+  // the handoff loop dies without them (sessions were saving batons that no
+  // next session ever picked up):
+  //   - pending prompts: the previous session queued work for THIS one;
+  //     consuming it is the very next action.
+  //   - an in-session plan attributed to this sid via the journal: this
+  //     session (pre-compaction) owns it and should continue or hand it off.
+  //     The single-in-session fallback is deliberately NOT printed — at
+  //     SessionStart that plan likely belongs to another live session.
+  // The misuse recap stays for the same reason: a repeat-offense rule means
+  // the primer alone isn't landing, so name the habit to break.
+  process.stdout.write(dim('dotmd: plans|briefing  set <status> [<file>]  new <type> <slug>  use [<file>]  archive <file>  baton [<slug>] <@draft|-> (save a resume prompt; releases the in-session plan if any)  (use [no-arg] → oldest pending prompt)') + '\n');
+  if (hud.owned && hud.owned.via === 'journal') {
+    process.stdout.write(yellow(`[dotmd] in-session (yours): ${hud.owned.path} — continue it; hand off with \`dotmd baton @/tmp/draft.md\` before stopping.`) + '\n');
+  }
+  if (hud.prompts.length > 0) {
+    const n = hud.prompts.length;
+    process.stdout.write(yellow(`[dotmd] ${n} pending prompt${n === 1 ? '' : 's'} queued for this session — unless the user asks for something else, start by running \`dotmd use\` to consume the oldest (${hud.prompts[0]}) and act on it. Peek first: \`dotmd prompts show <file>\`; list: \`dotmd prompts\`.`) + '\n');
+  }
   if (hud.misuseRecap) process.stdout.write(yellow(`[dotmd] ${hud.misuseRecap}`) + '\n');
   if (drift) process.stdout.write(yellow(drift) + '\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, computeDaysSinceUpdate, computeIsStale, computeChecklistCompletionRate, enrichRefErrorSuggestions } from './validate.mjs';
+import { validateDoc, validatePlanShape, validateDocShape, checkBidirectionalReferences, checkGitStaleness, checkRunlistBackPointers, checkCoordinationHubExecutionMode, 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';
@@ -120,6 +120,13 @@ export function buildIndex(config, opts = {}) {
       if (child) child.warnings.push(w);
     }
 
+    const coordHubWarnings = checkCoordinationHubExecutionMode(transformedDocs, config);
+    warnings.push(...coordHubWarnings);
+    for (const w of coordHubWarnings) {
+      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/lifecycle.mjs

@@ -928,7 +928,10 @@ export function appendVersionHistory(filePath, entry, { createSection = false }
 
 export function updateFrontmatter(filePath, updates) {
   const raw = readFileSync(filePath, 'utf8');
-  if (!raw.startsWith('---\n')) throw new Error(`${filePath} has no frontmatter block.`);
+  // Name the remedy in the error: this is where every status verb lands when a
+  // doc was created outside dotmd, and "no frontmatter block" alone left
+  // sessions retrying other verbs instead of fixing the doc.
+  if (!raw.startsWith('---\n')) throw new Error(`${filePath} has no frontmatter block. Retrofit it first: dotmd bulk-tag ${filePath} --type <type> --status <status>`);
 
   const endMarker = raw.indexOf('\n---\n', 4);
   if (endMarker === -1) throw new Error(`${filePath} has unclosed frontmatter block.`);

package/src/new.mjs

@@ -256,7 +256,7 @@ function mergeBodyFrontmatter(scaffoldFm, overrides, cliType) {
   return fm;
 }
 
-function readBodyInput(source) {
+export function readBodyInput(source) {
   if (source === '-') {
     try { return readFileSync(0, 'utf8'); } catch (err) { die(`Could not read body from stdin: ${err.message}`); }
   }
@@ -548,6 +548,12 @@ export async function runNew(argv, config, opts = {}) {
   if (typeName === 'prompt') {
     process.stdout.write(dim('Session-local — no need to commit. The next session runs `dotmd use` (or `dotmd use ' + repoPath + '`) to consume it.\n'));
   }
+  // Teach the field-length contract at the moment the fields get written —
+  // learning it from a cap warning later sends sessions into hand-trim /
+  // re-check loops.
+  if (typeName === 'plan') {
+    process.stdout.write(dim('current_state = 2-4 sentence summary (cap 1500 chars); next_step = 1-2 sentence pointer (cap 800). Detail goes in the body, not frontmatter.\n'));
+  }
   try {
     const { isGitIgnored } = await import('./git.mjs');
     if (isGitIgnored(filePath, config.repoRoot)) {

package/src/prompts.mjs

@@ -11,7 +11,7 @@ import { green, dim } from './color.mjs';
 // `resume` is an alias for `use` — agents reach for "resume" when continuing a
 // session; `use` reads as internal mechanics. Both names stay valid; the
 // canonical output ("Consumed: …") is unchanged.
-const SUBCOMMANDS = new Set(['list', 'next', 'use', 'resume', 'archive', 'new', 'hold', 'unhold', 'shelve', 'unshelve']);
+const SUBCOMMANDS = new Set(['list', 'next', 'use', 'resume', 'show', 'peek', 'archive', 'new', 'hold', 'unhold', 'shelve', 'unshelve']);
 
 export async function runPrompts(argv, config, opts = {}) {
   const sub = argv[0];
@@ -26,6 +26,8 @@ export async function runPrompts(argv, config, opts = {}) {
     case 'next':     return runPromptsNext(rest, config, opts);
     case 'use':      return runPromptsUse(rest, config, opts);
     case 'resume':   return runPromptsUse(rest, config, opts);
+    case 'show':     return runPromptsShow(rest, config);
+    case 'peek':     return runPromptsShow(rest, config);
     case 'archive':  return runPromptsArchive(rest, config, opts);
     case 'new':      return runPromptsNew(rest, config, opts);
     case 'hold':     return runPromptsHold(rest, config, opts);
@@ -283,6 +285,28 @@ export function consumePrompt(filePath, config, opts) {
   process.stderr.write(`${green('✓ Consumed')}: ${consumedPath}\n`);
 }
 
+// Read-only peek: print the body WITHOUT consuming. The sanctioned triage path
+// — surveying pending prompts must not archive them (that's `use`'s job), and
+// it must not require raw cat/Read (which the guard warns about).
+function runPromptsShow(argv, config) {
+  const input = argv.find(a => !a.startsWith('-'));
+  if (!input) die('Usage: dotmd prompts show <file-or-slug>');
+  const filePath = resolvePromptInput(input, config);
+
+  const raw = readFileSync(filePath, 'utf8');
+  const { frontmatter, body } = extractFrontmatter(raw);
+  const parsed = parseSimpleFrontmatter(frontmatter);
+  const repoPath = toRepoPath(filePath, config.repoRoot);
+  if (asString(parsed.type) !== 'prompt') {
+    die(`Not a prompt (type: ${asString(parsed.type) ?? 'unknown'}): ${repoPath}`);
+  }
+
+  const status = asString(parsed.status) ?? 'unknown';
+  process.stderr.write(dim(`${repoPath} [${status}] — read-only peek; \`dotmd use ${repoPath}\` to consume\n`));
+  process.stdout.write(body);
+  if (!body.endsWith('\n')) process.stdout.write('\n');
+}
+
 function runPromptsArchive(argv, config, opts = {}) {
   const input = argv.find(a => !a.startsWith('-'));
   if (!input) die('Usage: dotmd prompts archive <file-or-slug>');

package/src/query.mjs

@@ -7,6 +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';
 
 const STATUS_COLORS = {
   'in-session': (s) => bold(red(s)),
@@ -92,7 +93,10 @@ export function runQuery(index, argv, config, opts = {}) {
   }
 
   if (opts.preset === 'plans' || opts.preset === 'prompts') {
-    renderPlansOutput(docs, filters, config, { noun: opts.preset });
+    // 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 });
     if (docs.length === 0) writeUnknownFilterValueHint(filters, index);
     return;
   }
@@ -101,6 +105,83 @@ export function runQuery(index, argv, config, opts = {}) {
   if (docs.length === 0) writeUnknownFilterValueHint(filters, index);
 }
 
+// Sort comparator for the runlists dashboard. Default `age` puts the MOST STALE
+// hub first — a triage lens (which nav-map has gone longest untouched?), echoing
+// `dotmd modules --sort cleanup`. `recent` is the old newest-first order.
+// Unknown-age hubs sort last in both directions so they never dominate.
+const RUNLIST_SORTS = new Set(['age', 'recent', 'related', 'title', 'status']);
+function runlistSorter(sort, coordination, config) {
+  const cmpAge = (a, b, dir) => {
+    const av = a.daysSinceUpdate, bv = b.daysSinceUpdate;
+    if (av == null && bv == null) return 0;
+    if (av == null) return 1;
+    if (bv == null) return -1;
+    return dir * (av - bv);
+  };
+  const related = (d) => coordination.get(d.path)?.childCount ?? 0;
+  const byLabel = (a, b) => hubLabel(a).localeCompare(hubLabel(b));
+  if (sort === 'recent') return (a, b) => cmpAge(a, b, 1) || byLabel(a, b);
+  if (sort === 'related') return (a, b) => related(b) - related(a) || cmpAge(a, b, -1) || byLabel(a, b);
+  if (sort === 'title') return byLabel;
+  if (sort === 'status') {
+    return (a, b) => {
+      const ai = config.statusOrder.indexOf(a.status), bi = config.statusOrder.indexOf(b.status);
+      const aIdx = ai === -1 ? Number.MAX_SAFE_INTEGER : ai, bIdx = bi === -1 ? Number.MAX_SAFE_INTEGER : bi;
+      return aIdx - bIdx || cmpAge(a, b, -1) || byLabel(a, b);
+    };
+  }
+  return (a, b) => cmpAge(a, b, -1) || byLabel(a, b); // 'age' (default): most stale first
+}
+
+// `dotmd runlists` — the dedicated coordination-hub dashboard: the `Runlists`
+// section from `dotmd plans`, on its own, showing every hub (no leaf list, no
+// cap by default — runlists are a small bounded set). `--limit N` caps it,
+// `--sort age|recent|related|title|status` orders it (default `age`, most stale
+// first), `--json` emits structured rows.
+export function runRunlists(index, argv, config) {
+  const json = argv.includes('--json');
+  let limit = Infinity;
+  const li = argv.indexOf('--limit');
+  if (li >= 0 && argv[li + 1]) { const n = Number.parseInt(argv[li + 1], 10); if (Number.isFinite(n)) limit = n; }
+  const si = argv.indexOf('--sort');
+  const sortArg = si >= 0 && argv[si + 1] ? argv[si + 1] : 'age';
+  if (!RUNLIST_SORTS.has(sortArg)) die(`Unknown --sort '${sortArg}'. Use one of: ${[...RUNLIST_SORTS].join(', ')}.`);
+
+  const coordination = buildCoordinationIndex(index, config);
+  const archived = new Set([
+    ...(config.lifecycle?.archiveStatuses ?? []),
+    ...(config.lifecycle?.terminalStatuses ?? []),
+  ]);
+  const hubs = index.docs
+    .filter(d => coordination.has(d.path) && !archived.has(d.status) && !isArchivedPath(d.path, config))
+    .sort(runlistSorter(sortArg, coordination, config));
+
+  if (json) {
+    const runlists = hubs.map(d => ({
+      path: d.path,
+      status: d.status,
+      title: d.title,
+      childCount: coordination.get(d.path)?.childCount ?? 0,
+      updated: d.updated,
+      nextStep: d.nextStep ?? null,
+    }));
+    process.stdout.write(JSON.stringify({ count: runlists.length, runlists }, null, 2) + '\n');
+    return;
+  }
+
+  if (hubs.length === 0) {
+    process.stdout.write('No runlists found. A runlist is a plan with `execution_mode: coordination` (or a `*-runlist` slug).\n');
+    return;
+  }
+
+  const maxWidth = process.stdout.columns || 100;
+  const shown = hubs.slice(0, limit);
+  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`));
+  process.stdout.write('\n');
+}
+
 // When a query returns nothing AND a value-shaped filter (currently --module)
 // names a value that doesn't exist anywhere in the index, the empty result is
 // almost certainly a typo rather than a combination miss. Surface a hint so
@@ -254,6 +335,10 @@ export function filterDocs(docs, filters, config) {
     const s = d.status ?? 'unknown';
     filters._statusCounts[s] = (filters._statusCounts[s] ?? 0) + 1;
   }
+  // Keep a reference to the full pre-limit set so the plans header can
+  // reclassify runlist hubs out of the status breakdown (it needs per-doc
+  // identity, not just aggregate counts).
+  filters._matched = result;
   return filters.all ? result : result.slice(0, filters.limit);
 }
 
@@ -394,6 +479,16 @@ function renderPlansOutput(docs, filters, config, opts = {}) {
     return;
   }
 
+  const maxWidth = process.stdout.columns || 100;
+  const grouped = filters.sort === 'status' || filters.group;
+  // Runlist treatment (sprint-hub folding + the coordination-hub section) is
+  // scoped to the flat triage view; grouped views keep their existing shape.
+  const runlist = !grouped ? opts.runlist : null;
+  const coordination = !grouped ? opts.coordination : 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.
+  const isHub = (p) => Boolean(runlist?.hubs.has(p) || coordination?.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.
   const totalShown = docs.length;
@@ -403,9 +498,27 @@ function renderPlansOutput(docs, filters, config, opts = {}) {
     for (const d of docs) { counts[d.status] = (counts[d.status] ?? 0) + 1; }
     return counts;
   })();
-  // Sort statuses by count desc for a stable visual.
-  const counts = Object.entries(bySt).sort((a, b) => b[1] - a[1]).map(([s, n]) => `${n} ${s}`).join(' · ');
-  const header = `${totalAll} ${noun}${counts ? ' · ' + counts : ''}`;
+  // With runlists present, pull hubs out of the per-status breakdown into a
+  // dedicated `N runlist` bucket so a hub reads as an active *runlist*, not one
+  // more active plan. Needs per-doc identity, so recompute from the pre-limit
+  // matched set rather than the aggregate counts.
+  let hubCount = 0;
+  let counts;
+  if ((runlist?.hubs.size || coordination?.size) && filters._matched) {
+    const reclassed = {};
+    for (const d of filters._matched) {
+      if (isHub(d.path)) { hubCount += 1; continue; }
+      const s = d.status ?? 'unknown';
+      reclassed[s] = (reclassed[s] ?? 0) + 1;
+    }
+    counts = Object.entries(reclassed).sort((a, b) => b[1] - a[1]).map(([s, n]) => `${n} ${s}`);
+  } else {
+    counts = Object.entries(bySt).sort((a, b) => b[1] - a[1]).map(([s, n]) => `${n} ${s}`);
+  }
+  const headerParts = [];
+  if (hubCount) headerParts.push(`${hubCount} runlist${hubCount === 1 ? '' : 's'}`);
+  headerParts.push(...counts);
+  const header = `${totalAll} ${noun}${headerParts.length ? ' · ' + headerParts.join(' · ') : ''}`;
   process.stdout.write(dim(header) + '\n');
 
   // Active filter note
@@ -420,9 +533,6 @@ function renderPlansOutput(docs, filters, config, opts = {}) {
   if (filters.hasBlockers) activeFilters.push('has blockers');
   if (activeFilters.length) process.stdout.write(dim(`  filtered: ${activeFilters.join(' | ')}`) + '\n');
 
-  const maxWidth = process.stdout.columns || 100;
-  const grouped = filters.sort === 'status' || filters.group;
-
   if (filters.group === 'module') {
     process.stdout.write('\n');
     renderPlansByGroup(docs, d => d.modules?.length ? d.modules : ['(none)'], filters, maxWidth);
@@ -447,12 +557,47 @@ function renderPlansOutput(docs, filters, config, opts = {}) {
       renderPlanRows(group, filters, maxWidth, { showTag: false });
     }
   } else {
-    // Triage view: flat, sorted by recency, tag on right.
+    // Flat triage view, "capped like leaves": work from the full pre-limit
+    // matched set and cap each kind independently. Leaf plans (+ frontmatter
+    // `runlist:` sprint hubs, which still fold inline) fill the main list;
+    // coordination hubs are lifted into their own `Runlists` section. Each
+    // section caps at `--limit` with its own "N more" footer; `--all` lifts
+    // 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 coordAll = [];
+    const mainAll = [];
+    for (const d of matched) {
+      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);
+
     process.stdout.write('\n');
-    renderPlanRows(docs, filters, maxWidth, { showTag: true });
+    if (mainShown.length) {
+      if (runlist?.hubs.size) renderTriageWithRunlists(mainShown, runlist, maxWidth);
+      else renderPlanRows(mainShown, filters, maxWidth, { showTag: true });
+    }
+    const mainHidden = mainAll.length - mainShown.length;
+    if (mainHidden > 0) {
+      process.stdout.write('\n');
+      process.stdout.write(dim(`  ${mainHidden} more ${noun}  ·  dotmd ${noun} --all  ·  dotmd ${noun} status\n`));
+    }
+
+    if (coordShown.length) {
+      renderCoordinationSection(coordShown, coordination, maxWidth, coordAll.length);
+      const coordHidden = coordAll.length - coordShown.length;
+      if (coordHidden > 0) {
+        process.stdout.write(dim(`  ${coordHidden} more runlists  ·  dotmd ${noun} --all\n`));
+      }
+    }
+
+    process.stdout.write('\n');
+    return;
   }
 
-  // Footer when the result was capped — emit for every view shape.
+  // Footer (grouped views) — emit when the result was capped.
   const hidden = totalAll - totalShown;
   if (hidden > 0) {
     process.stdout.write('\n');
@@ -483,49 +628,163 @@ function renderPlansByGroup(docs, keyFn, filters, maxWidth) {
 // next-step column when right-aligning tags.
 const MAX_TAG_WIDTH = '[QUEUED-AFTER]'.length;
 
-function renderPlanRows(group, filters, maxWidth, opts = {}) {
+// Format a single triage row: `<indent><slug>  <age>  <pct>  <next-step>` with
+// an optional right-aligned tag. `indent` carries the left gutter (and, for
+// runlist children, the `→` next-pickup marker), so its visible length must be
+// stable across sibling rows for the slug column to align. `tag` overrides the
+// status tag (used for the `[RUNLIST]` hub tag).
+function formatPlanRow(doc, maxWidth, { slug, indent = '  ', maxSlug, showTag = false, tag } = {}) {
+  const slugCell = slug.padEnd(maxSlug ?? slug.length);
+  const age = doc.daysSinceUpdate != null ? `${doc.daysSinceUpdate}d` : '—';
+  const ageStr = doc.daysSinceUpdate != null && doc.isStale ? red(age.padStart(4)) : dim(age.padStart(4));
+
+  // Compact percentage cell (always 5 chars: "100% " / " 99% " / "  5% " / "     ")
+  let pctCell = '     ';
+  if (doc.checklist?.total) {
+    const pct = Math.round((doc.checklist.completed / doc.checklist.total) * 100);
+    pctCell = `${pct.toString().padStart(3)}% `;
+  }
+
+  const leftBlock = `${indent}${slugCell}  ${ageStr}  ${dim(pctCell)}`;
+  const leftLen = visibleLen(leftBlock);
+
+  // Next-step / blocker text. Budget = maxWidth - leftLen - separator - (tag column if shown).
+  let nextText = '';
+  if (doc.blockers?.length && doc.status === 'blocked') {
+    nextText = `blocked by ${doc.blockers.join('; ')}`;
+  } else if (doc.nextStep) {
+    nextText = doc.nextStep;
+  }
+
+  const tagBudget = showTag ? MAX_TAG_WIDTH + 2 : 0; // 2 = gap before tag
+  const nextBudget = Math.max(10, maxWidth - leftLen - 2 - tagBudget); // -2 for `  ` separator
+  let nextRendered = nextText;
+  if (nextText.length > nextBudget) nextRendered = nextText.slice(0, nextBudget - 3) + '...';
+
+  // Coloring for "blocked by" stays yellow.
+  if (doc.blockers?.length && doc.status === 'blocked') nextRendered = yellow(nextRendered);
+
+  let line = `${leftBlock}  ${nextRendered}`;
+  if (showTag) {
+    // Pad next column to push tag to the right column boundary.
+    const consumed = visibleLen(line);
+    const targetCol = maxWidth - MAX_TAG_WIDTH;
+    const padCount = Math.max(2, targetCol - consumed);
+    line = `${line}${' '.repeat(padCount)}${tag ?? colorTag(doc.status)}`;
+  }
+  return line;
+}
+
+function renderPlanRows(group, _filters, maxWidth, opts = {}) {
   const { showTag = false } = opts;
   const maxSlug = Math.min(30, Math.max(...group.map(d => toSlug(d).length)));
-
   for (const doc of group) {
-    const slug = toSlug(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));
+    process.stdout.write(formatPlanRow(doc, maxWidth, { slug: toSlug(doc), maxSlug, showTag }) + '\n');
+  }
+}
 
-    // Compact percentage cell (always 5 chars: "100% " / " 99% " / "  5% " / "     ")
-    let pctCell = '     ';
-    if (doc.checklist?.total) {
-      const pct = Math.round((doc.checklist.completed / doc.checklist.total) * 100);
-      pctCell = `${pct.toString().padStart(3)}% `;
-    }
+const RUNLIST_TAG = bold(cyan('[RUNLIST]'));
 
-    const leftBlock = `  ${slug}  ${ageStr}  ${dim(pctCell)}`;
-    const leftLen = visibleLen(leftBlock);
+// Drop a hub's slug prefix off a child slug so a sprint's children read as
+// `01-extract` rather than `auth-revamp-01-extract`. Falls back to the full
+// slug when there's no shared prefix.
+function stripHubPrefix(childSlug, hubSlug) {
+  return childSlug.startsWith(`${hubSlug}-`) ? childSlug.slice(hubSlug.length + 1) : childSlug;
+}
 
-    // Next-step / blocker text. Budget = maxWidth - leftLen - separator - (tag column if shown).
-    let nextText = '';
-    if (doc.blockers?.length && doc.status === 'blocked') {
-      nextText = `blocked by ${doc.blockers.join('; ')}`;
-    } else if (doc.nextStep) {
-      nextText = doc.nextStep;
-    }
+// Flat triage view, runlist-aware. Standalone plans render as before; each hub
+// becomes a `[RUNLIST]` header with its (filtered) children folded underneath
+// in runlist order, the next pickup marked `→`. A child whose hub is absent
+// from this filtered set (e.g. `--status active` hid the hub) renders
+// standalone so it still surfaces. Render units sort by their most-recent
+// member so an actively-worked sprint stays near the top.
+function renderTriageWithRunlists(docs, runlist, maxWidth) {
+  const { hubs, childToHub } = runlist;
+  const docPathSet = new Set(docs.map(d => d.path));
+
+  const folded = new Set();
+  for (const d of docs) {
+    const hubPath = childToHub.get(d.path);
+    if (hubPath && docPathSet.has(hubPath)) folded.add(d.path);
+  }
 
-    const tagBudget = showTag ? MAX_TAG_WIDTH + 2 : 0; // 2 = gap before tag
-    const nextBudget = Math.max(10, maxWidth - leftLen - 2 - tagBudget); // -2 for `  ` separator
-    let nextRendered = nextText;
-    if (nextText.length > nextBudget) nextRendered = nextText.slice(0, nextBudget - 3) + '...';
-
-    // Coloring for "blocked by" stays yellow.
-    if (doc.blockers?.length && doc.status === 'blocked') nextRendered = yellow(nextRendered);
-
-    let line = `${leftBlock}  ${nextRendered}`;
-    if (showTag) {
-      // Pad next column to push tag to the right column boundary.
-      const consumed = visibleLen(line);
-      const targetCol = maxWidth - MAX_TAG_WIDTH;
-      const padCount = Math.max(2, targetCol - consumed);
-      line = `${line}${' '.repeat(padCount)}${colorTag(doc.status)}`;
+  const units = [];
+  for (const d of docs) {
+    if (folded.has(d.path)) continue; // emitted under its hub
+    const info = hubs.get(d.path);
+    if (info) {
+      const children = docs.filter(c => childToHub.get(c.path) === d.path);
+      const ages = [d.daysSinceUpdate, ...children.map(c => c.daysSinceUpdate)].filter(n => n != null);
+      units.push({ anchor: ages.length ? Math.min(...ages) : Infinity, kind: 'hub', hub: d, info, children });
+    } else {
+      units.push({ anchor: d.daysSinceUpdate ?? Infinity, kind: 'plan', doc: d });
+    }
+  }
+  // Stable sort by most-recent member ascending (docs arrive already sorted by
+  // `updated`, so equal anchors keep their incoming order).
+  units.sort((a, b) => a.anchor - b.anchor);
+
+  // Shared slug width for the left-most rows (standalone plans + hub headers).
+  const topSlugs = units.map(u => u.kind === 'hub' ? toSlug(u.hub) : toSlug(u.doc));
+  const topMaxSlug = Math.min(30, Math.max(...topSlugs.map(s => s.length)));
+
+  for (const u of units) {
+    if (u.kind === 'plan') {
+      process.stdout.write(formatPlanRow(u.doc, maxWidth, { slug: toSlug(u.doc), maxSlug: topMaxSlug, showTag: true }) + '\n');
+    } else {
+      renderHubBlock(u.hub, u.info, u.children, maxWidth, topMaxSlug);
     }
-    process.stdout.write(line + '\n');
+  }
+}
+
+function renderHubBlock(hub, info, children, maxWidth, topMaxSlug) {
+  const hubSlug = toSlug(hub);
+  const nextDoc = info.nextChildPath ? info.children.find(c => c.path === info.nextChildPath)?.doc : null;
+  const nextLabel = nextDoc ? stripHubPrefix(toSlug(nextDoc), hubSlug) : null;
+  const descr = nextLabel
+    ? `runlist · ${info.doneCount}/${info.total} · next → ${nextLabel}`
+    : `runlist · ${info.doneCount}/${info.total} · all archived`;
+
+  // Header row: hub slug + descriptor, with `[RUNLIST]` right-aligned like a tag.
+  const slugCell = hubSlug.padEnd(topMaxSlug);
+  let header = `  ${slugCell}  ${dim(descr)}`;
+  const targetCol = maxWidth - MAX_TAG_WIDTH;
+  const pad = Math.max(2, targetCol - visibleLen(header));
+  header = `${header}${' '.repeat(pad)}${RUNLIST_TAG}`;
+  process.stdout.write(header + '\n');
+
+  if (children.length === 0) return;
+  const childMaxSlug = Math.min(28, Math.max(...children.map(c => stripHubPrefix(toSlug(c), hubSlug).length)));
+  for (const c of children) {
+    const isNext = c.path === info.nextChildPath;
+    const indent = isNext ? `    ${green('→')} ` : '      ';
+    process.stdout.write(formatPlanRow(c, maxWidth, {
+      slug: stripHubPrefix(toSlug(c), hubSlug), indent, maxSlug: childMaxSlug, showTag: true,
+    }) + '\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).
+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)));
+  for (const doc of coordDocs) {
+    const info = coordination.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 count = info?.childCount ? `${String(info.childCount).padStart(2)} related` : '          ';
+    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(count)}  `;
+    const budget = Math.max(10, maxWidth - visibleLen(left) - visibleLen(statusTag) - 2);
+    const descR = desc.length > budget ? desc.slice(0, budget - 3) + '...' : desc;
+    process.stdout.write(`${left}${dim(descR)}${statusTag}\n`);
   }
 }