dotmd-cli 0.61.0 → 0.63.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,38 @@ 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.
+For these, \`runlist\`/\`runlist next\` also read order from the body when there's
+no \`runlist:\` array — a \`## Ranked queue\` table or \`## Order of operations\`
+list of markdown links (the first \`.md\` link per row/item, in order).`,
+
+  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, a \`next → <child>\` when the hub's body
+encodes order as markdown links (\`## Ranked queue\` table / \`## Order of
+operations\` list), 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, nextPickup, …).`,
 
   'bulk-tag': `dotmd bulk-tag [files...] — fill in type/status frontmatter on pre-existing markdown
 
@@ -1372,6 +1405,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 +1765,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.63.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,52 @@ export function runHealth(argv, config) {
       ready: { count: readyPlans.length },
       planned: { count: plannedPlans.length },
       recentlyArchived: { count: recentlyArchived.length, last30d: recentlyArchived.map(d => path.basename(d.path, '.md')) },
+      runlists: { count: runlistHubs.length, hubs: runlistHubs.map(d => ({ path: d.path, title: d.title, status: d.status, childCount: coordination.get(d.path)?.childCount ?? 0, nextPickup: coordination.get(d.path)?.nextPickup ?? null })) },
     }, 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 info = coordination.get(doc.path);
+      const relStr = info?.childCount ? `  ${dim(`${info.childCount} related`)}` : '';
+      const nextStr = info?.nextPickup ? `  ${green('→')} ${info.nextPickup.label}` : '';
+      process.stdout.write(`  ${slug} ${dim(age.padStart(4))}${relStr}${nextStr}\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/lifecycle.mjs

@@ -236,6 +236,10 @@ export async function runStatus(argv, config, opts = {}) {
       process.stdout.write(`${prefix} Would unfile: ${toRepoPath(filePath, config.repoRoot)} → ${toRepoPath(targetPath, config.repoRoot)}\n`);
       finalPath = targetPath;
     }
+    if (finalPath !== filePath) {
+      const refCount = countRefsToUpdate(filePath, finalPath, config);
+      if (refCount > 0) process.stdout.write(`${prefix} Would update references in ${refCount} file(s)\n`);
+    }
     if ((isArchiving || isUnarchiving || isFiling || isUnfiling) && config.indexPath) {
       process.stdout.write(`${prefix} Would regenerate index\n`);
     }
@@ -286,6 +290,22 @@ export async function runStatus(argv, config, opts = {}) {
     finalPath = targetPath;
   }
 
+  // Any of the four moves above shifts the file's directory, which breaks
+  // relative refs in both directions — links FROM the moved file and inbound
+  // refs TO it from other docs. runArchive repairs both; mirror that here so
+  // the deprecated `dotmd status <file> archived` path and the `dotmd set`
+  // unarchive/file/unfile transitions (which route through runStatus, not
+  // runArchive) don't silently leave dangling links.
+  let selfRefsFixed = false;
+  let inboundRefCount = 0;
+  let inboundRefPaths = [];
+  if (finalPath !== filePath) {
+    selfRefsFixed = updateRefsFromMovedFile(filePath, finalPath, config) > 0;
+    const inbound = updateRefsAfterMove(filePath, finalPath, config);
+    inboundRefCount = inbound.count;
+    inboundRefPaths = inbound.paths;
+  }
+
   // Regen the index on every status change — `active → planned` etc. drift
   // the per-status sections just as much as archive crossings. Archive paths
   // also benefit (replaces the previously-gated regen). `--no-index` skips
@@ -298,10 +318,13 @@ export async function runStatus(argv, config, opts = {}) {
   }
 
   process.stdout.write(`${green(toRepoPath(finalPath, config.repoRoot))}: ${oldStatus ?? 'unknown'} → ${newStatus}\n`);
+  if (selfRefsFixed) process.stdout.write('Updated references in moved file.\n');
+  if (inboundRefCount > 0) process.stdout.write(`Updated references in ${inboundRefCount} file(s).\n`);
 
   if (showFiles) {
     const touched = [filePath];
     if (finalPath !== filePath) touched.push(finalPath);
+    touched.push(...inboundRefPaths);
     if (config.indexPath && !noIndex) touched.push(config.indexPath);
     emitFilesFooter(touched, config);
   }
@@ -749,6 +772,26 @@ export function runTouch(argv, config, opts = {}) {
   try { config.hooks.onTouch?.({ path: toRepoPath(filePath, config.repoRoot) }, { path: toRepoPath(filePath, config.repoRoot), date: today }); } catch (err) { warn(`Hook 'onTouch' threw: ${err.message}`); }
 }
 
+// Rewrite every frontmatter ref token (a `*.md` path in a YAML list item or an
+// inline scalar, quoted or `>`-prefixed) that points at `oldPath` so it points
+// at `newPath`. Each token is resolved doc-relative *and* repo-relative and
+// compared to oldPath by absolute path — mirroring how the body-link branch and
+// `updateRefsFromMovedFile` resolve refs. This replaces an older substring
+// rewrite (`fm.split(oldRelPath).join(newRelPath)`) that only knew doc-relative
+// paths, so it: left repo-relative cross-dir refs (`docs/plans/child.md` from
+// `docs/rfcs/spec.md`) broken; mangled same-dir repo-relative refs into
+// `docs/plans/../archived/child.md`; and could corrupt a `grandchild.md` ref
+// when archiving `child.md` (suffix match). oldPath no longer exists on disk
+// post-`git mv`, so existsSync-based resolveRefPath can't be used here.
+function rewriteFrontmatterRefs(fm, docDir, oldPath, newPath, repoRoot) {
+  return fm.replace(/[^\s"'<>:]+\.md\b/g, (token) => {
+    const docRelAbs = path.resolve(docDir, token);
+    const repoRelAbs = path.resolve(repoRoot, token);
+    if (docRelAbs !== oldPath && repoRelAbs !== oldPath) return token;
+    return path.relative(docDir, newPath).split(path.sep).join('/');
+  });
+}
+
 /**
  * After a file moves (archive/unarchive), update frontmatter references in all
  * docs that pointed to the old location so they point to the new one.
@@ -766,17 +809,7 @@ function updateRefsAfterMove(oldPath, newPath, config) {
     if (!fm) continue;
 
     const docDir = path.dirname(docFile);
-    const oldRelPath = path.relative(docDir, oldPath).split(path.sep).join('/');
-    const newRelPath = path.relative(docDir, newPath).split(path.sep).join('/');
-
-    let newFm = fm;
-    if (newFm.includes(oldRelPath)) {
-      newFm = newFm.split(oldRelPath).join(newRelPath);
-    }
-    const dotSlashOld = './' + oldRelPath;
-    if (newFm.includes(dotSlashOld)) {
-      newFm = newFm.split(dotSlashOld).join(newRelPath);
-    }
+    const newFm = rewriteFrontmatterRefs(fm, docDir, oldPath, newPath, config.repoRoot);
 
     // Body markdown links [text](path.md) or [text](path.md#anchor) pointing
     // at oldPath. resolveRefPath can't be used here: oldPath no longer exists
@@ -856,8 +889,7 @@ function countRefsToUpdate(oldPath, newPath, config) {
     if (!fm) continue;
 
     const docDir = path.dirname(docFile);
-    const oldRelPath = path.relative(docDir, oldPath).split(path.sep).join('/');
-    const fmHit = fm.includes(oldRelPath) || fm.includes('./' + oldRelPath);
+    const fmHit = rewriteFrontmatterRefs(fm, docDir, oldPath, newPath, config.repoRoot) !== fm;
 
     let bodyHit = false;
     if (!fmHit) {