dotmd-cli 0.61.0 → 0.62.0

package/README.md

@@ -33,7 +33,7 @@ dotmd new my-feature        # scaffold a new doc with frontmatter
 dotmd list                  # index all docs grouped by status
 dotmd check                 # validate frontmatter and references
 dotmd context               # compact briefing (great for LLM context)
-dotmd doctor                # auto-fix everything in one pass
+dotmd doctor                # preview fixes for everything (--apply to write)
 ```
 
 ### Shell Completion
@@ -83,7 +83,9 @@ Explicit frontmatter always wins. Body extraction is a cushion for partially-tag
 ## What It Does
 
 - **Index** — group docs by status, with auto-detected progress bars (from `- [ ]` checklists) and next steps
-- **Query** — filter by status, keyword, module, surface, owner, staleness
+- **Query** — filter by status, keyword, module, surface, owner, staleness; `dotmd grep` searches document bodies too
+- **Resume handoff** — `dotmd baton` saves a resume prompt for the next session and releases the in-session plan in one verb
+- **Runlists** — group plans into an ordered sequence on a hub plan; `dotmd runlist next` picks up the next one
 - **Validate** — check for missing fields, broken references, broken body links, stale dates
 - **Stats** — health dashboard with staleness, completeness, audit coverage
 - **Graph** — visualize document relationships as text, Graphviz DOT, or JSON
@@ -129,7 +131,7 @@ Design doc content here...
 - [ ] Add tests
 ```
 
-The only required field is `status`. Everything else is optional but unlocks more features. The `type` field (`plan`, `doc`, or `research`) enables type-specific statuses and smarter context briefings.
+The only required field is `status`. Everything else is optional but unlocks more features. The `type` field (`plan`, `doc`, or `prompt`) enables type-specific statuses and smarter context briefings.
 
 > **Note:** `module:` and `surface:` (singular) are deprecated as of 0.36.3 — use the plural array forms (`modules:`, `surfaces:`). Run `dotmd lint --fix` to migrate existing docs.
 
@@ -177,6 +179,34 @@ Each *quiet* status (`partial`, `queued-after`, `archived`) is exempt from stale
 
 > **Heads-up:** versions before 0.15 included a `done` plan status in the defaults. It saw effectively zero real-world use (plans went `in-session`/`active` → `archived` directly), so it was dropped from the built-in vocabulary. To finish a plan, run `dotmd archive <plan-file>` — or, if you preferred the previous behavior, add `done` back via the `types.plan.statuses` key in your config.
 
+### Runlists: ordered groups of plans
+
+When several plans must ship in a known order (an "auth revamp" sprint with extract → rewrite → cleanup phases), declare a `runlist:` array on a hub plan instead of chaining `queued-after` per pair or keeping the order in prose:
+
+```yaml
+---
+type: plan
+status: active
+title: Auth Revamp
+runlist:
+  - auth-revamp-01-extract.md
+  - auth-revamp-02-rewrite.md
+  - auth-revamp-03-cleanup.md
+---
+```
+
+```bash
+dotmd runlist <hub>          # children + statuses in order; first non-archived child marked →
+dotmd runlist next <hub>     # pick up the next child (marks in-session + prints it)
+dotmd runlists               # dashboard of coordination-hub runlists (--json, --limit N)
+```
+
+`runlist next` stops with a runlist-aware error if the next child isn't in a workable status (`active` / `planned` / `in-session`), so you resolve the blocker before continuing. Each child should set `parent_plan:` pointing back at the hub — `dotmd check` warns when it doesn't. There's no separate doc type: a runlist hub is just a plan with the array.
+
+In `dotmd plans`, hubs are tagged `[RUNLIST]` (not `[ACTIVE]`) with their children folded underneath — the hub row shows `done/total` progress and the next-pickup `→`, so a multi-plan sprint reads as one runlist instead of cluttering the triage list. A child whose hub is filtered out of the view (e.g. `--status active` when the hub is `planned`) still renders on its own.
+
+**Coordination runlists.** A `runlist:` array fits a small ordered *sprint*. For a large, prose-first *coordination map* (a domain hub pointing at many plans, with gating/sequence rationale, sometimes unordered), set `execution_mode: coordination` instead — or just name it `*-runlist`. These aren't folded: `dotmd plans` lifts them into a pinned `Runlists` section and out of the active count, and `dotmd runlists` shows that dashboard standalone. `dotmd briefing` and `dotmd health` do the same — coordination hubs are pulled out of the live/active counts into a `runlists` bucket (briefing) and a held-out `Runlists:` tally (health), so they don't inflate the actionable-plan or aging numbers. The per-hub "N related" count comes from `related_plans:`. `dotmd check` nudges a `*-runlist` hub missing `execution_mode: coordination`.
+
 ## Commands
 
 ```
@@ -191,27 +221,36 @@ dotmd unblocks <file>        Show what depends on this doc
 dotmd health [--json]        Plan velocity, aging, and pipeline
 dotmd briefing               Compact summary for session start
 dotmd context [--summarize]  Full briefing (LLM-oriented)
+dotmd agent-context          Compact bounded JSON context for agents
 dotmd focus [status]         Detailed view for one status group
-dotmd query [filters]        Filtered search
-dotmd plans                  List all plans
+dotmd query [filters]        Filtered search (--body scans document bodies)
+dotmd grep <term>            Keyword search incl. bodies — "which doc discussed X?"
+dotmd plans                  List live plans (excludes archived)
 dotmd modules                Module dashboard (plans grouped by module)
 dotmd module <name>          Plans for one module, grouped by status
+dotmd surfaces               List configured surface taxonomy
 dotmd stale                  List stale docs
 dotmd actionable             List docs with next steps
 dotmd index [--print]        Generate/update docs.md index block
 dotmd hud                    Actionable triage (silent when clean — ideal SessionStart hook)
-dotmd use <file>             Open a plan (in-session + print it) or consume a prompt
-dotmd set <status> <file>    Change a document's status (frontmatter write)
+dotmd use [<file-or-slug>]   Open by type: prompt → consume, plan → start, doc → read
+                             (no arg: consume the oldest pending prompt)
+dotmd set <status> <file>    Change a document's status (--note appends why to Version History)
+dotmd baton [<plan>|<slug>] <@draft|->  Save a resume prompt; releases the in-session plan
+dotmd runlist <hub> [next]   Show or walk an ordered group of plans
 dotmd status <file> <status> Transition document status (deprecated; prefer set)
 dotmd archive <file>         Archive (status + move + update refs)
 dotmd bulk archive <files>   Archive multiple files at once
+dotmd bulk-tag [files]       Tag pre-existing untagged .md files
 dotmd touch <file>           Bump updated date
 dotmd touch --git            Bulk-sync dates from git history
-dotmd doctor                 Auto-fix everything in one pass
+dotmd doctor [--apply]       Fix refs, lint, dates, index (previews by default)
+dotmd self-check             Project/version skew diagnostic
 dotmd fix-refs               Auto-fix broken reference paths
 dotmd lint [--fix]           Check and auto-fix frontmatter issues
 dotmd rename <old> <new>     Rename doc and update references
 dotmd migrate <f> <old> <new>  Batch update a frontmatter field
+dotmd ship [patch|minor|major] Regen + commit + bump in one step
 dotmd notion <sub> [db-id]   Notion import/export/sync
 dotmd export [file]          Export docs as md, html, or json
 dotmd summary <file>         AI summary of a document
@@ -219,19 +258,22 @@ dotmd glossary <term>        Look up domain terms + related docs
 dotmd watch [command]        Re-run a command on file changes
 dotmd diff [file]            Show changes since last updated date
 dotmd new <type> <name>      Create a new doc (type: doc, plan, or prompt)
-dotmd prompts [sub]          Manage saved prompts (list, next, use, hold, archive, new)
+dotmd prompts [sub]          Manage saved prompts (list, show, hold, archive, new)
+dotmd statuses [sub]         Manage per-project status taxonomy
 dotmd journal [flags]        View opt-in command-usage journal (DOTMD_JOURNAL=1)
 dotmd init                   Create starter config + docs directory
 dotmd completions <shell>    Output shell completion script (bash, zsh)
 ```
 
+Run `dotmd help all` for the always-current version of this list, `dotmd help statuses` for the status vocabulary, and `dotmd <cmd> --help` for per-command details.
+
 ### Global Flags
 
 ```
 --config <path>        Explicit config file path
 --dry-run, -n          Preview changes without writing anything
 --root <name>          Filter to a specific docs root
---type <t1,t2>         Filter by document type (plan, doc, research)
+--type <t1,t2>         Filter by document type (plan, doc, prompt, or custom)
 --verbose              Show resolved config details
 --help, -h             Show help (per-command with: dotmd <cmd> --help)
 --version, -v          Show version
@@ -246,9 +288,12 @@ dotmd query --stale --sort updated --all
 dotmd query --surface backend --checklist-open
 dotmd query --status active --summarize             # AI summaries
 dotmd query --status active --summarize --summarize-limit 3
+dotmd query --keyword "retries" --body              # scan document bodies too
 ```
 
-Flags: `--type`, `--status`, `--keyword`, `--module`, `--surface`, `--domain`, `--owner`, `--updated-since`, `--stale`, `--has-next-step`, `--has-blockers`, `--checklist-open`, `--sort`, `--limit`, `--all`, `--git`, `--json`, `--summarize`, `--summarize-limit`, `--model`.
+Flags: `--type`, `--status`, `--keyword`, `--body`, `--module`, `--surface`, `--domain`, `--owner`, `--updated-since`, `--stale`, `--has-next-step`, `--has-blockers`, `--checklist-open`, `--sort`, `--limit`, `--all`, `--git`, `--json`, `--summarize`, `--summarize-limit`, `--model`.
+
+`dotmd grep <term>` is the "which doc discussed X?" shorthand — an alias for `dotmd query --keyword <term> --body --all` that prints doc cards plus line-numbered excerpts per body hit. Bodies are read lazily (frontmatter filters run first), and it composes with the usual query flags.
 
 ### Create Documents
 
@@ -311,9 +356,19 @@ dotmd new prompt from-file @/tmp/draft.md
 
 Manage them with the `prompts` command family:
 
+Consume one with `dotmd use` — it atomically prints the body and archives the prompt so it can't be double-consumed:
+
+```bash
+dotmd use                         # consume the oldest pending prompt
+dotmd use <file-or-slug>          # consume a specific prompt
+```
+
+Admin verbs live under the `prompts` namespace:
+
 ```bash
 dotmd prompts                     # list pending prompts (default)
 dotmd prompts list --all          # all statuses
+dotmd prompts show <file>         # read-only peek: print the body WITHOUT consuming
 dotmd prompts next                # print body of oldest pending + auto-archive (one-shot)
 dotmd prompts use <file>          # print body of a specific prompt + auto-archive
 dotmd prompts hold <file>         # park a prompt (status → held) under prompts/held/:
@@ -328,6 +383,31 @@ dotmd prompts new <name> [body]   # alias for `dotmd new prompt`
 
 Statuses: `pending` (drafted, awaiting a session), `held` (saved but parked under `prompts/held/` — visible in `prompts list`, hidden from `hud`/`briefing`, skipped by `prompts next`), `archived` (consumed or filed away). `shelved` is a legacy spelling accepted for older files; `claimed` is reserved for a future "in-flight" state but is currently a synonym for archived in practice.
 
+### Baton: resume prompts & session handoff
+
+`dotmd baton` is the "save a resume prompt" verb — the way one session hands work to the next without pasting resume text into chat. Write a short draft (the next concrete decision plus any gotchas, not a recap), then:
+
+```bash
+dotmd baton @/tmp/draft.md        # plan mode: a plan is in-session
+```
+
+In plan mode, baton does the whole closeout in one call:
+
+1. Saves a resume prompt named `resume-<plan-slug>` (collision-safe: `-2`, `-3`, …) under `docs/prompts/` with `status: pending`.
+2. Releases the plan: one status flip, `in-session` → `active` by default (`--status paused|awaiting|partial|blocked` to override, `--note "why"` to record the reason in `## Version History`).
+3. Prints the exact `git commit` command for the plan's frontmatter change — the prompt stays out of the pathspec, because saved prompts are session-local.
+
+Baton resolves *your* plan via the command journal (or takes it explicitly: `dotmd baton <plan-file> @draft`), falling back to the only in-session plan.
+
+No plan involved? Slug mode saves the prompt and touches nothing else:
+
+```bash
+dotmd baton checkout-fixes @/tmp/draft.md    # saves resume-checkout-fixes; no status changes
+cat /tmp/draft.md | dotmd baton              # body from stdin
+```
+
+Either way, the next session's `dotmd hud` surfaces the pending prompt, and `dotmd use` consumes it.
+
 ### Command Journal (opt-in)
 
 dotmd's primary user is an agent. Every CLI invocation can be journaled
@@ -403,8 +483,8 @@ Shows: status counts, staleness, errors/warnings, freshness (today/week/month),
 ### Doctor
 
 ```bash
-dotmd doctor                 # fix refs → lint → sync git dates → regen index
-dotmd doctor --dry-run       # preview all changes
+dotmd doctor                 # preview: fix refs → lint → sync git dates → regen index
+dotmd doctor --apply         # actually write the fixes (previews by default since 0.37.0)
 dotmd doctor --statuses      # detect overloaded status buckets (read-only)
 dotmd doctor --statuses --json  # machine-readable suggestions
 ```
@@ -607,6 +687,15 @@ dotmd archive docs/plans/my-plan.md --closeout-template   # also inject ## Close
 `in-session` is a status like any other — `dotmd set <status> <file>` writes it
 to the file's frontmatter and does nothing else.
 
+Add `--note "why"` to any `set` or `archive` to append the reason to the doc's
+`## Version History` section in the same call (creates the section if missing) —
+it saves the status-change + worklog-edit round-trip. `set partial` without a
+note or successor link prints a reminder.
+
+To stop mid-work and hand off to a future session, use `dotmd baton` (see
+[Baton](#baton-resume-prompts--session-handoff)) — it saves the resume prompt
+and releases the plan in one verb.
+
 **Recommended Claude Code hook** — add to `~/.claude/settings.json`
 (or your project's `.claude/settings.json`):
 

package/bin/dotmd.mjs

@@ -44,6 +44,7 @@ const FLAG_SPECS = {
   check: { flags: new Set(['--fix', '--errors-only', '--no-collapse', '--json', '--verbose']), values: new Set() },
   doctor: { flags: new Set(['--apply', '--yes', '--dry-run', '-n', '--statuses', '--migrate-template', '--migrate-prompts', '--frontmatter-fix', '--project', '--json', '--include-archived']), values: new Set() },
   runlist: { flags: new Set(['--json', '--full', '--no-index', '--show-files']), values: new Set(), subcommands: new Set(['next']) },
+  runlists: { flags: new Set(['--json', '--limit', '--sort']), values: new Set(['--limit', '--sort']) },
   prompts: {
     flags: new Set(['--json', '--status', '--include-archived', '--sort', '--limit', '--all', '--no-index', '--show-files', '--body', '--message', '--title']),
     values: new Set(['--status', '--sort', '--limit', '--body', '--message', '--title']),
@@ -235,6 +236,7 @@ Lifecycle:
   use <file>                        Open a plan (mark in-session + print it) or consume a prompt
   set <status> <file>               Change a document's status (frontmatter write; archive also moves the file)
   runlist <hub> [next]              Show or walk an ordered group of plans (see \`dotmd help runlist\`)
+  runlists                          List coordination-hub runlists (the Runlists 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
@@ -263,7 +265,7 @@ Setup:
 Global Options:
   --config <path>        Explicit config file path
   --root <name>          Filter to a specific docs root
-  --type <t1,t2>         Filter by document type (plan, doc, research)
+  --type <t1,t2>         Filter by document type (plan, doc, prompt)
   --dry-run, -n          Preview changes without writing anything
   --verbose              Show config details and doc count
   --help, -h             Show help (per-command: dotmd <cmd> --help)
@@ -410,7 +412,7 @@ Examples:
   query: `dotmd query — filtered document search
 
 Filters:
-  --type <t1,t2>         Filter by type (plan, doc, research)
+  --type <t1,t2>         Filter by type (plan, doc, prompt)
   --status <s1,s2>       Filter by status (comma-separated)
   --keyword <term>       Search title, summary, state, path
   --body                 Extend --keyword into document bodies (lazy scan, shows matching-line excerpts)
@@ -887,7 +889,7 @@ Options:
   --format <md|html|json>  Output format (default: md)
   --output <path>          Write to file/directory (default: stdout for md/json)
   --status <s1,s2>         Filter by status
-  --type <t1,t2>           Filter by type (plan, doc, research)
+  --type <t1,t2>           Filter by type (plan, doc, prompt)
   --module <name>          Filter by module
   --root <name>            Filter by root
   --dry-run, -n            Preview without writing`,
@@ -1212,7 +1214,33 @@ Common shape:
   ---
 
 Child plans should set \`parent_plan:\` back at the hub — \`dotmd check\` warns
-when they don't.`,
+when they don't.
+
+In \`dotmd plans\`, a hub is tagged \`[RUNLIST]\` (not \`[ACTIVE]\`) and its
+children fold underneath it — progress (\`done/total\`) and the next pickup
+\`→\` show on the hub row, so a sprint reads as one runlist instead of N loose
+plans. Children whose hub is filtered out of the view (e.g. \`--status active\`
+when the hub is \`planned\`) still render on their own.
+
+Larger, prose-first "coordination" runlists (a domain map pointing at many
+plans, marked \`execution_mode: coordination\` or named \`*-runlist\`) aren't
+folded — they're lifted into a separate \`Runlists\` section in \`dotmd plans\`
+and out of the active count. \`dotmd runlists\` shows that dashboard on its own.`,
+
+  runlists: `dotmd runlists — the coordination-hub dashboard
+
+Lists every *coordination runlist*: a prose-first plan that sits above a
+cluster of others (a domain map), detected by \`execution_mode: coordination\`
+or a \`*-runlist\` / \`runlist\` slug. Each row shows the hub, its age, the rough
+size of its \`related_plans:\` cluster, and a one-line descriptor.
+
+This is the standalone form of the \`Runlists\` section that \`dotmd plans\`
+pins beneath the leaf-plan triage list.
+
+  dotmd runlists               All runlists (a small bounded set), most stale first.
+  dotmd runlists --sort recent Order by recency instead (age|recent|related|title|status).
+  dotmd runlists --limit N     Cap the list at N.
+  dotmd runlists --json        Structured rows (path, status, childCount, …).`,
 
   'bulk-tag': `dotmd bulk-tag [files...] — fill in type/status frontmatter on pre-existing markdown
 
@@ -1372,6 +1400,16 @@ async function main() {
     runQuery(index, [...defaults, ...extras], config, { preset: 'plans' });
     return;
   }
+  // `dotmd runlists` (plural) — the coordination-hub dashboard (the `Runlists`
+  // section of `dotmd plans`, standalone). Distinct from `dotmd runlist <hub>`
+  // (singular), which walks one hub's children.
+  if (command === 'runlists') {
+    const { buildIndex } = await import('../src/index.mjs');
+    const { runRunlists } = await import('../src/query.mjs');
+    const index = buildIndex(config);
+    runRunlists(index, restArgs, config);
+    return;
+  }
   if (command === 'prompts') {
     const { runPrompts } = await import('../src/prompts.mjs');
     await runPrompts(restArgs, config, { dryRun, verbose });
@@ -1722,8 +1760,16 @@ async function main() {
       const docs = index.docs.filter(d => d.type === 'doc');
       const research = index.docs.filter(d => d.type === 'research');
       const stale = index.docs.filter(d => d.isStale && !config.lifecycle.skipStaleFor.has(d.status)).length;
+      // Coordination hubs are runlists, not actionable plans — split them out of
+      // inSession/active into their own `runlists` array so the JSON mirrors the
+      // rendered briefing. Empty on repos with no coordination hubs.
+      const { buildCoordinationIndex } = await import('../src/runlist.mjs');
+      const coordination = buildCoordinationIndex(index, config);
+      const isHub = (d) => coordination.has(d.path);
+      const closedStatuses = new Set([...config.lifecycle.archiveStatuses, ...config.lifecycle.terminalStatuses]);
+      const isLiveHub = (d) => isHub(d) && !closedStatuses.has(d.status) && !isArchivedPath(d.path, config);
       process.stdout.write(JSON.stringify({
-        plans: { total: plans.length, inSession: plans.filter(d => d.status === 'in-session').map(d => ({ path: d.path, title: d.title, nextStep: d.nextStep })), active: plans.filter(d => d.status === 'active').map(d => ({ path: d.path, title: d.title, nextStep: d.nextStep })) },
+        plans: { total: plans.length, inSession: plans.filter(d => d.status === 'in-session' && !isHub(d)).map(d => ({ path: d.path, title: d.title, nextStep: d.nextStep })), active: plans.filter(d => d.status === 'active' && !isHub(d)).map(d => ({ path: d.path, title: d.title, nextStep: d.nextStep })), runlists: plans.filter(isLiveHub).map(d => ({ path: d.path, title: d.title, status: d.status, childCount: coordination.get(d.path)?.childCount ?? 0 })) },
         docs: { total: docs.length, active: docs.filter(d => !config.lifecycle.terminalStatuses.has(d.status)).length },
         research: { total: research.length, active: research.filter(d => d.status === 'active').length },
         stale, errorCount: index.errors.length, warningCount: index.warnings.length,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.61.0",
+  "version": "0.62.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/commands.mjs

@@ -4,7 +4,7 @@
 // templates points at a real command.
 export const KNOWN_COMMANDS = [
   'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'briefing', 'context', 'agent-context', 'hud',
-  'focus', 'query', 'grep', 'plans', 'prompts', 'stale', 'actionable', 'index', 'status', 'set', 'use', 'next', 'archive', 'bulk', 'bulk-tag', 'touch', 'doctor', 'runlist',
+  'focus', 'query', 'grep', 'plans', 'prompts', 'stale', 'actionable', 'index', 'status', 'set', 'use', 'next', 'archive', 'bulk', 'bulk-tag', 'touch', 'doctor', 'runlist', 'runlists',
   'unblocks', 'health', 'glossary', 'modules', 'module',
   'fix-refs', 'lint', 'rename', 'migrate', 'notion', 'export', 'summary',
   'watch', 'diff', 'new', 'init', 'completions', 'statuses', 'journal',

package/src/completions.mjs

@@ -2,7 +2,7 @@ import { die } from './util.mjs';
 
 const COMMANDS = [
   'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'unblocks', 'health', 'glossary', 'briefing', 'context', 'focus', 'query', 'grep',
-  'plans', 'stale', 'actionable', 'index', 'status', 'set', 'archive', 'bulk', 'touch', 'doctor', 'lint', 'rename', 'migrate',
+  'plans', 'runlist', 'runlists', 'stale', 'actionable', 'index', 'status', 'set', 'archive', 'bulk', 'touch', 'doctor', 'lint', 'rename', 'migrate',
   'fix-refs', 'notion', 'export', 'summary', 'watch', 'diff', 'init', 'new', 'completions', 'journal',
 ];
 

package/src/health.mjs

@@ -1,13 +1,32 @@
 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 { isArchivedPath } from './util.mjs';
 
 export function runHealth(argv, config) {
   const json = argv.includes('--json');
   const index = buildIndex(config);
 
   // Only plans (type: plan or untyped docs in plans root)
-  const plans = index.docs.filter(d => d.type === 'plan' || (!d.type && d.root?.includes('plan')));
+  const allPlans = index.docs.filter(d => d.type === 'plan' || (!d.type && d.root?.includes('plan')));
+  // Coordination hubs (prose-first runlists) are navigation maps, not execution
+  // units — they carry no checklist and skew active-plan aging — so lift the
+  // LIVE ones out of the pipeline + active set into a dedicated Runlists tally,
+  // mirroring `dotmd plans` / `dotmd runlists`. Archived hubs stay in `plans` so
+  // the archived/velocity counts are unchanged. No coordination hubs → `plans`
+  // equals the full set and every count below is identical to before.
+  const coordination = buildCoordinationIndex(index, config);
+  const closedStatuses = new Set([
+    ...(config.lifecycle?.archiveStatuses ?? []),
+    ...(config.lifecycle?.terminalStatuses ?? []),
+  ]);
+  const isLiveHub = (d) => coordination.has(d.path) && !closedStatuses.has(d.status) && !isArchivedPath(d.path, config);
+  const runlistHubs = allPlans.filter(isLiveHub)
+    // 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));
+  const plans = allPlans.filter(d => !isLiveHub(d));
   const now = Date.now();
 
   // Status distribution
@@ -68,24 +87,51 @@ 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 })) },
     }, null, 2) + '\n');
     return;
   }
 
   process.stdout.write(bold('Plan Health') + '\n\n');
 
-  // Pipeline
+  // Pipeline — ordered by the configured status vocab, then any present-but-
+  // unconfigured statuses (custom ones a repo defines, by count). Deriving from
+  // the live status set means in-session/partial/awaiting/etc. all show, and a
+  // dead status never leaves an empty row — unlike the old hand-kept list that
+  // drifted out of sync with the vocabulary.
   process.stdout.write(bold('Pipeline:') + '\n');
-  const pipeline = ['active', 'paused', 'ready', 'planned', 'blocked', 'scoping', 'archived'];
-  for (const s of pipeline) {
-    const count = byStatus[s] || 0;
-    if (count > 0) {
-      const bar = '█'.repeat(Math.min(count, 40));
-      process.stdout.write(`  ${s.padEnd(10)} ${String(count).padStart(4)}  ${dim(bar)}\n`);
-    }
+  const statusOrder = config.statusOrder ?? [];
+  const present = Object.keys(byStatus).filter(s => byStatus[s] > 0);
+  const ordered = [
+    ...statusOrder.filter(s => present.includes(s)),
+    ...present.filter(s => !statusOrder.includes(s)).sort((a, b) => byStatus[b] - byStatus[a]),
+  ];
+  const pad = Math.max(10, ...ordered.map(s => s.length));
+  for (const s of ordered) {
+    const count = byStatus[s];
+    const bar = '█'.repeat(Math.min(count, 40));
+    process.stdout.write(`  ${s.padEnd(pad)} ${String(count).padStart(4)}  ${dim(bar)}\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.
+  if (runlistHubs.length > 0) {
+    process.stdout.write(`${bold('Runlists:')} ${runlistHubs.length}  ${dim('· dotmd runlists')}\n`);
+    for (const doc of runlistHubs.slice(0, 8)) {
+      const slug = hubLabel(doc).padEnd(28);
+      const age = doc.daysSinceUpdate != null ? `${doc.daysSinceUpdate}d` : '?d';
+      const rel = coordination.get(doc.path)?.childCount;
+      const relStr = rel ? `  ${dim(`${rel} related`)}` : '';
+      process.stdout.write(`  ${slug} ${dim(age.padStart(4))}${relStr}\n`);
+    }
+    if (runlistHubs.length > 8) {
+      process.stdout.write(`  ${dim(`...and ${runlistHubs.length - 8} more`)}\n`);
+    }
+    process.stdout.write('\n');
+  }
+
   // Active plan health
   if (activePlans.length > 0) {
     process.stdout.write(bold('Active plans:') + '\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/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`);
   }
 }

package/src/render.mjs

@@ -5,6 +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';
 
 // 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
@@ -322,6 +323,15 @@ export function renderBriefing(index, config) {
   const research = index.docs.filter(d => d.type === 'research');
   const untyped = index.docs.filter(d => !d.type);
 
+  // Coordination hubs (prose-first runlists) are navigation maps, not units of
+  // work — so lift them out of the live-plan status breakdown into their own
+  // `runlists` bucket and drop them from the actionable `>` list, mirroring
+  // `dotmd plans` / `dotmd runlists`. (Sprint `runlist:` hubs stay as ordinary
+  // plans here; their folding treatment is scoped to `dotmd plans`.) On a repo
+  // with no coordination hubs this is a no-op and the output is unchanged.
+  const coordination = buildCoordinationIndex(index, config);
+  const isHub = (p) => coordination.has(p.path);
+
   if (plans.length) {
     // Headline counts LIVE plans first — "30 plans: 25 archived, …" skims as
     // 30 open work items when zero are. "Live" mirrors the `dotmd plans`
@@ -331,17 +341,26 @@ export function renderBriefing(index, config) {
       ...(config.lifecycle?.terminalStatuses ?? []),
     ]);
     const live = plans.filter(p => !closed.has(p.status) && !isArchivedPath(p.path, config));
+    const liveHubs = live.filter(isHub);
     const bySt = {};
-    for (const p of live) { bySt[p.status] = (bySt[p.status] ?? 0) + 1; }
-    const counts = Object.entries(bySt).map(([s, n]) => `${n} ${s}`).join(', ');
+    for (const p of live) { if (isHub(p)) continue; bySt[p.status] = (bySt[p.status] ?? 0) + 1; }
+    // Runlists lead the breakdown (then leaf statuses), and the bucket sums back
+    // to the live total so the headline stays honest.
+    const countParts = [];
+    if (liveHubs.length) countParts.push(`${liveHubs.length} runlist${liveHubs.length === 1 ? '' : 's'}`);
+    countParts.push(...Object.entries(bySt).map(([s, n]) => `${n} ${s}`));
+    const counts = countParts.join(', ');
     const closedCount = plans.length - live.length;
     const closedPart = closedCount ? ` (${closedCount} archived)` : '';
     lines.push(live.length ? `${live.length} live plans${closedPart}: ${counts}` : `0 live plans${closedPart}`);
-    const show = plans.filter(p => p.status === 'in-session' || p.status === 'active');
+    const show = plans.filter(p => (p.status === 'in-session' || p.status === 'active') && !isHub(p));
     for (const p of show) {
       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')}`);
+    }
   }
 
   const parts = [];

package/src/runlist.mjs

@@ -4,15 +4,133 @@ import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import {
   asString,
   die,
+  isArchivedPath,
   normalizeStringList,
   resolveRefPath,
   toRepoPath,
+  toSlug,
 } from './util.mjs';
 import { resolveDocArg } from './index.mjs';
 import { bold, cyan, dim, green, red, yellow } from './color.mjs';
 
 const PICKUPABLE_STATUSES = new Set(['active', 'planned', 'in-session']);
 
+// Build a hub/child map straight from the in-memory index — no disk IO. A doc
+// is a runlist *hub* when its `runlist:` frontmatter (`refFields.runlist`) is
+// non-empty. Each ref resolves to a doc in the index by path, falling back to
+// basename so children that were archived (and physically moved into an
+// archive dir) still resolve. Used by the `dotmd plans` triage view to fold
+// children under their hub and tag hubs as runlists rather than plain plans.
+//
+// Returns:
+//   hubs:       Map<hubPath, { hub, total, doneCount, children, nextChildPath }>
+//                 children: [{ ref, doc, path, status, archived, missing }] in runlist order
+//   childToHub: Map<childPath, hubPath>  (first hub wins on the rare double-claim)
+export function 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 hubs = new Map();
+  const childToHub = new Map();
+  for (const hub of index.docs) {
+    const refs = hub.refFields?.runlist ?? [];
+    if (refs.length === 0) continue;
+    const hubDir = path.dirname(path.join(config.repoRoot, hub.path));
+
+    const children = [];
+    for (const ref of refs) {
+      const abs = resolveRefPath(ref, hubDir, config.repoRoot);
+      let childDoc = abs ? docByPath.get(toRepoPath(abs, config.repoRoot)) ?? null : null;
+      if (!childDoc) childDoc = byBasename.get(ref.split('/').pop()) ?? null;
+      if (childDoc) {
+        const archived = archiveStatuses.has(childDoc.status) || isArchivedPath(childDoc.path, config);
+        children.push({ ref, doc: childDoc, path: childDoc.path, status: childDoc.status, archived, missing: false });
+        if (!childToHub.has(childDoc.path)) childToHub.set(childDoc.path, hub.path);
+      } else {
+        children.push({ ref, doc: null, path: null, status: null, archived: false, missing: true });
+      }
+    }
+
+    const next = children.find(c => !c.missing && !c.archived) ?? null;
+    hubs.set(hub.path, {
+      hub,
+      total: children.length,
+      doneCount: children.filter(c => c.archived).length,
+      children,
+      nextChildPath: next?.path ?? null,
+    });
+  }
+
+  return { hubs, childToHub };
+}
+
+// A *coordination hub* is a prose-first plan that sits above a cluster of other
+// plans — a "runlist" in the platform sense (master-runlist, ai-runlist, …)
+// rather than a strictly-ordered frontmatter `runlist:` sprint. The signal is
+// already in frontmatter (`execution_mode: coordination`), with the
+// `*-runlist` / `runlist` naming convention as a fallback for the few hubs that
+// predate the field. These plans aren't units of executable work — they're
+// navigation maps — so the triage view tags them and lifts them out of the
+// leaf-plan flow rather than treating them as one more active plan.
+export function isCoordinationHub(doc) {
+  if (!doc) return false;
+  if (doc.type && doc.type !== 'plan') return false;
+  if (doc.executionMode === 'coordination') return true;
+  const base = (doc.path.split('/').pop() || '').replace(/\.md$/, '');
+  return base === 'runlist' || base.endsWith('-runlist');
+}
+
+// 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
+// list — so it's shown as a rough "N plans" hint, not an authoritative count.
+export function buildCoordinationIndex(index, config) {
+  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 hubs = new Map();
+  for (const doc of index.docs) {
+    if (!isCoordinationHub(doc)) continue;
+    const dir = path.dirname(path.join(config.repoRoot, doc.path));
+    const refs = doc.refFields?.related_plans ?? [];
+    const childPaths = new Set();
+    for (const ref of refs) {
+      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;
+      if (child && child.path !== doc.path && (child.type === 'plan' || child.type == null)) {
+        childPaths.add(child.path);
+      }
+    }
+    hubs.set(doc.path, { doc, childCount: childPaths.size, childPaths });
+  }
+  return hubs;
+}
+
+// Conventional container dirs whose name adds no disambiguation to a hub label.
+const HUB_CONTAINER_DIRS = new Set(['plans', 'prompts', 'archive', 'archived']);
+
+// Display label for a hub. A bare basename loses context for hubs that live in
+// a subdirectory (e.g. `docs/plans/pos/runlist.md` would read as just
+// `runlist`), so prefix the immediate parent dir unless it's a conventional
+// container. → `pos/runlist`, but `billing-runlist` stays as-is. Shared by the
+// `dotmd plans` Runlists section, `dotmd runlists`, and `dotmd health` so a hub
+// reads the same everywhere.
+export function hubLabel(doc) {
+  const slug = toSlug(doc);
+  const parent = path.basename(path.dirname(doc.path));
+  return HUB_CONTAINER_DIRS.has(parent) ? slug : `${parent}/${slug}`;
+}
+
 // Bare hub slugs resolve through the shared resolver; the caller keeps its
 // runlist-specific miss message, so no die-on-miss here.
 function resolveHubInput(input, config) {

package/src/validate.mjs

@@ -433,6 +433,33 @@ export function checkRunlistBackPointers(docs, config) {
   return warnings;
 }
 
+// Coordination-hub hygiene: a plan whose slug is `*-runlist` / `runlist` reads
+// as a coordination runlist, but `dotmd plans` only *reliably* lifts it into the
+// Runlists section (and out of the active count) when `execution_mode:
+// coordination` is set. Slug detection is the fallback; the frontmatter field is
+// the canonical signal. Nudge the few hubs that lean on the slug alone to make
+// it explicit. Skips terminal/quiet statuses like every other warning-only check.
+export function checkCoordinationHubExecutionMode(docs, config) {
+  const warnings = [];
+  const skipStatuses = new Set([
+    ...(config.lifecycle.terminalStatuses ?? []),
+    ...(config.lifecycle.skipWarningsFor ?? []),
+  ]);
+  for (const doc of docs) {
+    if (doc.type && doc.type !== 'plan') continue;
+    if (skipStatuses.has(doc.status)) continue;
+    if (doc.executionMode === 'coordination') continue;
+    const base = (doc.path.split('/').pop() || '').replace(/\.md$/, '');
+    if (base !== 'runlist' && !base.endsWith('-runlist')) continue;
+    warnings.push({
+      path: doc.path,
+      level: 'warning',
+      message: `reads as a coordination runlist (slug \`${base}\`) but is missing \`execution_mode: coordination\`. Add it so \`dotmd plans\` / \`dotmd runlists\` reliably treat it as a runlist, not an active plan.`,
+    });
+  }
+  return warnings;
+}
+
 export function checkGitStaleness(docs, config) {
   const warnings = [];
   const gitDates = getGitLastModifiedBatch(config.repoRoot);