dotmd-cli 0.64.3 → 0.65.1

package/bin/dotmd.mjs

@@ -43,7 +43,7 @@ const FLAG_SPECS = {
   update: { flags: new Set(['--check', '--cli-only', '--plugin-only']), values: new Set() },
   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']) },
+  runlist: { flags: new Set(['--json', '--full', '--no-index', '--show-files', '--clear-parent', '--before', '--after']), values: new Set(['--before', '--after']), subcommands: new Set(['next', 'add', 'remove', 'reorder']) },
   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']),
@@ -235,7 +235,7 @@ Validate & Fix:
 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\`)
+  runlist <hub> [next|add|remove|reorder]   Show, walk, or mutate an ordered group of plans (see \`dotmd help runlist\`)
   runlists                          List coordination-hub runlists (the Runlists dashboard)
   status <file> <status>            Transition document status (deprecated; prefer \`set\`)
   archive <file>                    Archive (status + move + update refs)
@@ -1212,19 +1212,49 @@ directory, updates references, and regenerates the index.
 
 Use --dry-run (-n) to preview changes without writing anything.`,
 
-  runlist: `dotmd runlist <hub> [next] — work with an ordered group of plans
+  runlist: `dotmd runlist <hub> [next|add|remove|reorder] — work with an ordered group of plans
 
 A "runlist" is just a plan with a \`runlist:\` array of child plan paths in its
 frontmatter — there is no separate doc type. The hub plan can have any status;
 the order of the children comes from the array.
 
 Usage:
-  dotmd runlist <hub>          Show children + their statuses, in order.
-                               The first non-archived child is marked \`→\`.
-  dotmd runlist next <hub>     Open the first non-archived child (marks it
-                               in-session + prints it). Stops if it's not in a
-                               workable status (active / planned / in-session)
-                               so you resolve the blocker first.
+  dotmd runlist <hub>          Show children + their statuses, in order. The
+                               first pickup-able child (active / planned /
+                               in-session) is marked \`→\`. Archived (done) and
+                               parked children (blocked / partial / paused /
+                               awaiting / queued-after) are skipped — \`→\`
+                               advances to the first child you can actually
+                               start. Parked ≠ done: they don't count toward
+                               done/total.
+  dotmd runlist next <hub>     Open the first pickup-able child (marks it
+                               in-session + prints it), advancing past archived
+                               and parked children. If every remaining child is
+                               parked, stops and lists them + the unstick verbs
+                               so you resolve a blocker first.
+  dotmd runlist add <hub> <child...>
+                               Append children to the hub's \`runlist:\` array
+                               (no more hand-editing the YAML). Each child can be:
+                                 • a bare slug (\`cleanup\`) → scaffolds a
+                                   \`planned\` stub \`<hub>-NN-<slug>.md\` next to
+                                   the hub (mirrors \`new plan --runlist\`), or
+                                 • a path/slug of an existing plan → wired in by a
+                                   hub-relative ref, with its \`parent_plan:\` set
+                                   back at the hub.
+                               A plain plan gains a \`runlist:\` (becomes a hub).
+                               Coordination hubs (body-order) aren't handled here.
+  dotmd runlist remove <hub> <child...>
+                               Drop children from the \`runlist:\` array. Children
+                               match by full path or short slug (\`cleanup\` finds
+                               \`<hub>-03-cleanup.md\`). \`--clear-parent\` also blanks
+                               each removed child's \`parent_plan:\` back-ref.
+  dotmd runlist reorder <hub> <child> --before|--after <other>
+  dotmd runlist reorder <hub> <c1> <c2> <c3...>
+                               Move one child relative to another, or pass every
+                               child to set a full new order.
+                               All three mutators take \`--dry-run\` / \`--json\` and
+                               keep any body \`## Order of operations\` link list in
+                               sync (preserving per-item ⬜/✅ markers).
 
 Flags (only meaningful with \`next\`):
   --full             Print full plan body instead of the card.

package/package.json

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

package/src/new.mjs

@@ -269,10 +269,10 @@ export function readBodyInput(source) {
 }
 
 // Slug/title helpers shared by name resolution and runlist child generation.
-function slugify(s) {
+export function slugify(s) {
   return s.toLowerCase().replace(/[\s_]+/g, '-').replace(/[^a-z0-9-]/g, '').replace(/-+/g, '-').replace(/^-|-$/g, '');
 }
-function titleize(s) {
+export function titleize(s) {
   return s.replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
 }
 
@@ -420,7 +420,7 @@ ${bodyInput?.trim() ?? ''}
 // Minimal child plan stub for a scaffolded runlist child. parent_plan points
 // back at the hub (same dir) so \`dotmd doctor\` is satisfied and the reverse
 // link/graph work; status starts `planned` (queued behind the hub).
-function runlistChildContent(childTitle, hubSlug, hubTitle, childStatus, today) {
+export function runlistChildContent(childTitle, hubSlug, hubTitle, childStatus, today) {
   return `---
 type: plan
 status: ${childStatus}

package/src/query.mjs

@@ -524,7 +524,11 @@ function renderPlansOutput(docs, filters, config, opts = {}) {
   const headerParts = [];
   if (hubCount) headerParts.push(`${hubCount} runlist${hubCount === 1 ? '' : 's'}`);
   headerParts.push(...counts);
-  const header = `${totalAll} ${noun}${headerParts.length ? ' · ' + headerParts.join(' · ') : ''}`;
+  // Hubs are held OUT of the headline plan count — they read as a separate
+  // `N runlist` sibling, never as actionable plans. So "N plans" counts leaves
+  // only and the status segments sum to it (the runlist sibling sits apart).
+  const headlineTotal = totalAll - hubCount;
+  const header = `${headlineTotal} ${noun}${headerParts.length ? ' · ' + headerParts.join(' · ') : ''}`;
   process.stdout.write(dim(header) + '\n');
 
   // Active filter note
@@ -599,6 +603,23 @@ function renderPlansOutput(docs, filters, config, opts = {}) {
       }
     }
 
+    // Runlist nav stays discoverable under a narrowing filter. The Runlists
+    // section respects the active filter (a coordination hub shows only when its
+    // own status matches), so `--status blocked` legitimately hides an `active`
+    // hub. Rather than silently dropping the map, point at `dotmd runlists` when
+    // a filter hid live hubs — honest count, filter respected, map never lost.
+    if (coordination?.size && activeFilters.length) {
+      const archiveStatuses = config.lifecycle?.archiveStatuses ?? new Set(['archived']);
+      const shownHubs = new Set(coordAll.map(d => d.path));
+      const filterHidden = [...coordination.values()].filter(v =>
+        !shownHubs.has(v.doc.path)
+        && !archiveStatuses.has(v.doc.status)
+        && !isArchivedPath(v.doc.path, config)).length;
+      if (filterHidden > 0) {
+        process.stdout.write(dim(`  ${filterHidden} runlist${filterHidden === 1 ? '' : 's'} hidden by filter  ·  dotmd runlists\n`));
+      }
+    }
+
     process.stdout.write('\n');
     return;
   }
@@ -747,9 +768,13 @@ 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;
+  // No pickup-able child: "N parked" when a live-but-unstartable child remains
+  // (the runlist is stuck, not finished), else "all archived" (truly done).
   const descr = nextLabel
     ? `runlist · ${info.doneCount}/${info.total} · next → ${nextLabel}`
-    : `runlist · ${info.doneCount}/${info.total} · all archived`;
+    : info.parkedCount > 0
+      ? `runlist · ${info.doneCount}/${info.total} · ${info.parkedCount} parked`
+      : `runlist · ${info.doneCount}/${info.total} · all archived`;
 
   // Header row: hub slug + descriptor, with `[RUNLIST]` right-aligned like a tag.
   const slugCell = hubSlug.padEnd(topMaxSlug);
@@ -760,8 +785,15 @@ function renderHubBlock(hub, info, children, maxWidth, topMaxSlug) {
   process.stdout.write(header + '\n');
 
   if (children.length === 0) return;
+  // Render rows in runlist order (info.children), not the docs view's recency
+  // sort — a runlist reads in sequence, and a just-added child shouldn't jump to
+  // the top because its mtime is newest. Only children present in the current
+  // view are shown; any not tracked by the runlist index trail at the end.
+  const byPath = new Map(children.map(c => [c.path, c]));
+  const ordered = info.children.map(ic => byPath.get(ic.path)).filter(Boolean);
+  for (const c of children) if (!ordered.includes(c)) ordered.push(c);
   const childMaxSlug = Math.min(28, Math.max(...children.map(c => stripHubPrefix(toSlug(c), hubSlug).length)));
-  for (const c of children) {
+  for (const c of ordered) {
     const isNext = c.path === info.nextChildPath;
     const indent = isNext ? `    ${green('→')} ` : '      ';
     process.stdout.write(formatPlanRow(c, maxWidth, {

package/src/render.mjs

@@ -342,17 +342,17 @@ export function renderBriefing(index, config) {
     ]);
     const live = plans.filter(p => !closed.has(p.status) && !isArchivedPath(p.path, config));
     const liveHubs = live.filter(isHub);
+    const liveLeaves = live.length - liveHubs.length;
     const bySt = {};
     for (const p of live) { if (isHub(p)) continue; bySt[p.status] = (bySt[p.status] ?? 0) + 1; }
-    // 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(', ');
+    // Coordination hubs are navigation maps, not units of work — held OUT of the
+    // headline plan count entirely (they get their own `N runlists · dotmd
+    // runlists` pointer line below). The breakdown is leaf statuses only and sums
+    // back to the leaf count, so "N live plans" means N things to actually work on.
+    const counts = Object.entries(bySt).map(([s, n]) => `${n} ${s}`).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}`);
+    lines.push(liveLeaves ? `${liveLeaves} live plans${closedPart}: ${counts}` : `0 live plans${closedPart}`);
     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)';

package/src/runlist.mjs

@@ -1,20 +1,39 @@
-import { readFileSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
-import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { extractFrontmatter, parseSimpleFrontmatter, replaceFrontmatter } from './frontmatter.mjs';
+import { extractFirstHeading } from './extractors.mjs';
 import {
   asString,
   die,
+  escapeRegex,
   isArchivedPath,
   normalizeStringList,
+  nowIso,
   resolveRefPath,
   toRepoPath,
   toSlug,
+  warn,
 } from './util.mjs';
 import { resolveDocArg } from './index.mjs';
+import { runlistChildContent, slugify, titleize } from './new.mjs';
 import { bold, cyan, dim, green, red, yellow } from './color.mjs';
 
 const PICKUPABLE_STATUSES = new Set(['active', 'planned', 'in-session']);
 
+// A child is the runlist's NEXT PICKUP only when a session could start it right
+// now — i.e. its status is one `dotmd use` accepts. The "parked" statuses
+// (blocked/partial/paused/awaiting/queued-after) are deliberately NOT
+// pickup-able: each needs its own unstuck action (monitor / spawn successor /
+// re-evaluate / ask / check predecessor) before work resumes. So next-pickup
+// resolution skips them and advances to the first child that's actually
+// startable. Skipping ≠ done, though: a parked child is not archived, so it
+// never counts toward `done/total` — that tally tracks closed (archived) only.
+// This keeps the `→` marker in agreement with `runlist next`, which already
+// gates on PICKUPABLE_STATUSES.
+function isPickupable(status) {
+  return PICKUPABLE_STATUSES.has(status);
+}
+
 // 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
@@ -56,11 +75,17 @@ export function buildRunlistIndex(index, config) {
       }
     }
 
-    const next = children.find(c => !c.missing && !c.archived) ?? null;
+    // Next pickup = first child a session can actually start. Skip archived
+    // (done) AND parked children alike; advance to the first pickup-able one.
+    const next = children.find(c => !c.missing && !c.archived && isPickupable(c.status)) ?? null;
     hubs.set(hub.path, {
       hub,
       total: children.length,
       doneCount: children.filter(c => c.archived).length,
+      // Live-but-not-startable children (parked: blocked/partial/paused/…). Lets
+      // the `dotmd plans` fold say "N parked" instead of mislabelling a hub with
+      // a parked-but-unfinished child as "all archived".
+      parkedCount: children.filter(c => !c.missing && !c.archived && !isPickupable(c.status)).length,
       children,
       nextChildPath: next?.path ?? null,
     });
@@ -164,13 +189,16 @@ function resolveRunlistRefs(refs, hubAbsPath, config) {
     const repoPath = toRepoPath(abs, config.repoRoot);
     try {
       const childRaw = readFileSync(abs, 'utf8');
-      const { frontmatter: childFmRaw } = extractFrontmatter(childRaw);
+      const { frontmatter: childFmRaw, body: childBody } = extractFrontmatter(childRaw);
       const childFm = parseSimpleFrontmatter(childFmRaw);
       out.push({
         ref,
         path: repoPath,
         status: asString(childFm.status) ?? null,
-        title: asString(childFm.title) ?? path.basename(abs, '.md'),
+        // Fall back to the body H1 (like the main index) before the bare
+        // filename — runlist child stubs carry their title as an H1, not a
+        // `title:` field, so this keeps the synced body order list readable.
+        title: asString(childFm.title) ?? extractFirstHeading(childBody) ?? path.basename(abs, '.md'),
         parentPlan: childFm.parent_plan ?? null,
         missing: false,
       });
@@ -263,6 +291,11 @@ function resolveHubNextPickup(hubDoc, hubDir, resolveRef, archiveStatuses, confi
     if (child.type && child.type !== 'plan') continue;
     const archived = archiveStatuses.has(child.status) || isArchivedPath(child.path, config);
     if (archived) continue;
+    // Skip parked ranked children too (blocked/partial/paused/awaiting/
+    // queued-after) — the hub's next-pickup is the first startable plan, the
+    // same gate sprint runlists use, so a hub never points `→` at a child a
+    // session can't actually pick up.
+    if (!isPickupable(child.status)) continue;
     return { path: child.path, status: child.status ?? null, label: coordinationChildLabel(child, hubDoc) };
   }
   return null;
@@ -322,7 +355,9 @@ function renderRunlist(hubRepoPath, children, opts = {}) {
       lines.push(`  ${idx}. ${red('missing')}  ${c.ref}`);
       continue;
     }
-    const isNext = !nextPicked && !archiveStatuses.has(c.status);
+    // → marks the first child a session can actually start: skip archived and
+    // parked (blocked/partial/paused/awaiting/queued-after) alike.
+    const isNext = !nextPicked && isPickupable(c.status);
     if (isNext) nextPicked = true;
     const marker = isNext ? green('→') : ' ';
     const statusTag = `[${colorStatus(c.status)}]`;
@@ -330,16 +365,460 @@ function renderRunlist(hubRepoPath, children, opts = {}) {
   }
   if (!nextPicked) {
     lines.push('');
-    lines.push(dim('  All children archived. Hub is ready for archive.'));
+    // No pickup-able child. Distinguish "done — ready to archive" from "stuck —
+    // a parked child needs unsticking" so the agent knows which it is.
+    const parked = children.filter(c => !c.missing && !archiveStatuses.has(c.status));
+    lines.push(dim(parked.length === 0
+      ? '  All children archived. Hub is ready for archive.'
+      : `  No pickup-able child — ${parked.length} parked. Unstick one (e.g. \`dotmd set active <child>\`) to continue.`));
   }
   return lines.join('\n') + '\n';
 }
 
+// --- `runlist add` mutation (Phase 1) -------------------------------------
+
+// Replace a top-level frontmatter field (its `key:` line + any indented
+// continuation block) with `serialized`, or append it when absent. The regex
+// mirrors what `mergeBodyFrontmatter` uses so the rewritten field keeps the
+// scaffold's shape. Shared by the block-array (`runlist:`) and scalar
+// (`parent_plan:`, `updated:`) writers below.
+function upsertFrontmatterField(fm, key, serialized) {
+  const re = new RegExp(`^${escapeRegex(key)}:.*(\\n[ \\t]+.*)*`, 'm');
+  if (re.test(fm)) return fm.replace(re, serialized);
+  return fm.replace(/\s*$/, '') + '\n' + serialized;
+}
+
+function serializeBlockArray(key, items) {
+  if (items.length === 0) return `${key}:`;
+  return `${key}:\n${items.map(v => `  - ${v}`).join('\n')}`;
+}
+
+// Hub-relative ref for a child path: a bare basename when the child sits in the
+// hub's directory (the common case, matching how `--runlist` writes refs), else
+// a relative path (forward slashes) so the ref resolves from the hub. This is
+// the hub-relative resolution that lets an existing plan elsewhere be wired in
+// (the thrice-parked "point a hub at an existing plan" carryover).
+function hubRelativeRef(childAbs, hubDir) {
+  const rel = path.relative(hubDir, childAbs).split(path.sep).join('/');
+  return rel;
+}
+
+// Resolve one `runlist add` child token against an existing hub. Returns one of:
+//   { kind: 'existing', abs, repoPath, ref }   — token names a plan that exists
+//   { kind: 'scaffold', abs, repoPath, ref, slug, title }  — bare slug to create
+// Dies on an unresolvable path (a `/`-bearing token that points nowhere — we
+// scaffold from bare slugs only, never invent a nested path).
+function classifyChildToken(token, hubDir, hubSlug, pos, config) {
+  // Existing plan? Try hub-relative first (Phase 3 resolution), then the shared
+  // resolver (repo-relative / by-basename across the index).
+  const hubRel = resolveRefPath(token, hubDir, config.repoRoot)
+    || (token.endsWith('.md') ? null : resolveRefPath(`${token}.md`, hubDir, config.repoRoot));
+  const abs = hubRel || resolveDocArg(token, config, { dieOnMiss: false });
+  if (abs) {
+    return {
+      kind: 'existing',
+      abs,
+      repoPath: toRepoPath(abs, config.repoRoot),
+      ref: hubRelativeRef(abs, hubDir),
+    };
+  }
+
+  // Not found. Scaffold a stub — but only from a bare slug. A `/`-bearing token
+  // is a path to a file that doesn't exist; refuse rather than guess.
+  if (token.includes('/') || token.includes(path.sep)) {
+    die(`No plan found at "${token}". Pass a bare slug (e.g. \`cleanup\`) to scaffold a new child, or a path to an existing plan.`);
+  }
+  const childSlug = slugify(token.replace(/\.md$/, ''));
+  if (!childSlug) die(`Child token resolves to an empty slug: "${token}"`);
+  const nn = String(pos).padStart(2, '0');
+  const file = `${hubSlug}-${nn}-${childSlug}.md`;
+  const childAbs = path.join(hubDir, file);
+  return {
+    kind: 'scaffold',
+    abs: childAbs,
+    repoPath: toRepoPath(childAbs, config.repoRoot),
+    ref: file,
+    slug: childSlug,
+    title: titleize(token.replace(/\.md$/, '')),
+  };
+}
+
+// Set `parent_plan:` on an existing child to point back at the hub, unless it
+// already resolves to the hub. Never clobbers a parent_plan that points
+// elsewhere (warns instead — the child may belong to another hub). Returns
+// true when it wrote, false when it left the file alone.
+function setChildParentPlan(childAbs, hubAbs, config, { dryRun }) {
+  const raw = readFileSync(childAbs, 'utf8');
+  const { frontmatter: fmRaw } = extractFrontmatter(raw);
+  if (fmRaw == null) return false;
+  const fm = parseSimpleFrontmatter(fmRaw);
+  const childDir = path.dirname(childAbs);
+  const existing = asString(fm.parent_plan);
+  if (existing) {
+    const resolved = resolveRefPath(existing, childDir, config.repoRoot);
+    if (resolved === hubAbs) return false; // already points at this hub
+    warn(`${toRepoPath(childAbs, config.repoRoot)} already has parent_plan: ${existing} — left as-is (not pointing it at the hub).`);
+    return false;
+  }
+  const ref = path.relative(childDir, hubAbs).split(path.sep).join('/');
+  if (dryRun) return true;
+  let newFm = upsertFrontmatterField(fmRaw, 'parent_plan', `parent_plan: ${ref}`);
+  newFm = upsertFrontmatterField(newFm, 'updated', `updated: ${nowIso()}`);
+  writeFileSync(childAbs, replaceFrontmatter(raw, newFm), 'utf8');
+  return true;
+}
+
+// `dotmd runlist add <hub> <child...>` — append children to a hub's `runlist:`
+// array, scaffolding a `planned` stub for any bare-slug child that doesn't yet
+// exist (mirroring `dotmd new plan --runlist`) and wiring each child's
+// `parent_plan:` back-ref. Coordination hubs (body-order, no `runlist:` array)
+// are out of this path — guarded with an actionable message.
+async function runRunlistAdd(positional, config, { dryRun, json }) {
+  const hubInput = positional[0];
+  const childTokens = positional.slice(1);
+  if (!hubInput || childTokens.length === 0) {
+    die('Usage: dotmd runlist add <hub-plan> <child...>  (one or more child slugs or plan paths)');
+  }
+
+  const hubAbs = resolveHubInput(hubInput, config);
+  if (!hubAbs) die(`Hub plan not found: ${hubInput}`);
+  const hubRepoPath = toRepoPath(hubAbs, config.repoRoot);
+  const hubDir = path.dirname(hubAbs);
+  const hubSlug = path.basename(hubAbs, '.md');
+
+  const hubRaw = readFileSync(hubAbs, 'utf8');
+  const { frontmatter: hubFmRaw } = extractFrontmatter(hubRaw);
+  if (hubFmRaw == null) die(`Hub ${hubRepoPath} has no frontmatter.`);
+  const hubFm = parseSimpleFrontmatter(hubFmRaw);
+  const existingRefs = normalizeStringList(hubFm.runlist);
+  const isCoord = hubFm.execution_mode === 'coordination';
+
+  // Coordination hubs keep their order in the body (`## Ranked queue` /
+  // `## Order of operations`), not a `runlist:` array. Mutating that prose-first
+  // order is a separate path; for now point the user at it rather than writing a
+  // `runlist:` array onto a hub that deliberately doesn't use one.
+  if (isCoord && existingRefs.length === 0) {
+    die(
+      `${hubRepoPath} is a coordination hub (execution_mode: coordination) — it keeps its order in the body\n` +
+      `(\`## Ranked queue\` table or \`## Order of operations\` list), not a \`runlist:\` array.\n` +
+      `Add the plan as a ranked row/link there. \`runlist add\` manages sprint \`runlist:\` arrays.`,
+    );
+  }
+
+  // Resolve every token up front (so a bad token aborts before any write), then
+  // dedupe against refs already in the runlist (by resolved abs path).
+  const resolvedExisting = new Set();
+  for (const ref of existingRefs) {
+    const abs = resolveRefPath(ref, hubDir, config.repoRoot);
+    if (abs) resolvedExisting.add(abs);
+  }
+
+  const toAdd = [];
+  let pos = existingRefs.length;
+  for (const token of childTokens) {
+    pos += 1;
+    const c = classifyChildToken(token, hubDir, hubSlug, pos, config);
+    if (c.abs === hubAbs) { warn(`Skipping "${token}" — a hub can't list itself.`); pos -= 1; continue; }
+    if (resolvedExisting.has(c.abs)) { warn(`Skipping "${token}" — already in the runlist (${c.repoPath}).`); pos -= 1; continue; }
+    resolvedExisting.add(c.abs);
+    toAdd.push(c);
+  }
+  if (toAdd.length === 0) die('Nothing to add — all children were already in the runlist or skipped.');
+
+  const hubTitle = asString(hubFm.title) ?? titleize(hubSlug);
+  const today = nowIso();
+  const newRefs = [...existingRefs, ...toAdd.map(c => c.ref)];
+
+  if (json) {
+    process.stdout.write(JSON.stringify({
+      hub: hubRepoPath,
+      added: toAdd.map(c => ({ ref: c.ref, path: c.repoPath, scaffolded: c.kind === 'scaffold' })),
+      runlist: newRefs,
+      dryRun: !!dryRun,
+    }, null, 2) + '\n');
+    if (dryRun) return;
+  }
+
+  const prefix = dryRun ? `${dim('[dry-run]')} ` : '';
+  if (!json) process.stdout.write(bold(`${prefix}runlist add → ${hubRepoPath}`) + '\n');
+
+  for (const c of toAdd) {
+    if (c.kind === 'scaffold') {
+      if (!dryRun) {
+        if (existsSync(c.abs)) {
+          warn(`Child already exists, left as-is: ${c.repoPath}`);
+        } else {
+          writeFileSync(c.abs, runlistChildContent(c.title, hubSlug, hubTitle, 'planned', today), 'utf8');
+        }
+      }
+      if (!json) process.stdout.write(`${prefix}  ${green('+')} ${c.repoPath} ${dim('(scaffolded · planned)')}\n`);
+    } else {
+      const wrote = setChildParentPlan(c.abs, hubAbs, config, { dryRun });
+      const note = wrote ? 'existing · parent_plan set' : 'existing';
+      if (!json) process.stdout.write(`${prefix}  ${green('+')} ${c.repoPath} ${dim(`(${note})`)}\n`);
+    }
+  }
+
+  // Write the hub's `runlist:` array (+ bump `updated:`, + sync the body order
+  // list). The child stubs are already on disk, so title resolution works.
+  if (!dryRun) writeHubRunlist(hubAbs, newRefs, config, today);
+
+  if (!json) {
+    process.stdout.write(dim(`  runlist now has ${newRefs.length} ${newRefs.length === 1 ? 'child' : 'children'}.`) + '\n');
+    if (!dryRun) {
+      process.stdout.write(dim(`  Show: dotmd runlist ${hubRepoPath}   ·   pick up next: dotmd runlist next ${hubRepoPath}`) + '\n');
+    }
+  }
+}
+
+// --- `runlist remove` / `runlist reorder` mutation (Phase 2) ---------------
+
+// Heading alternatives that carry a `## Order of operations`-style link list
+// mirroring the `runlist:` array (the `new plan --runlist` scaffold writes one).
+const ORDER_SECTION_RE = /^##\s+(?:Order of operations|Runlist|Execution order|Implementation order|Plan order)\b.*$/im;
+
+// Keep a hub's body `## Order of operations` link list in sync with the
+// authoritative `runlist:` array. Regenerates the numbered link block from
+// `orderedRefs`, preserving each item's display title and trailing status
+// marker (⬜/✅/…) for children that remain — so a hand-checked-off item keeps
+// its mark across an add/remove/reorder. No such section → body untouched (we
+// never invent one). Only the contiguous run of list-item lines is rewritten;
+// surrounding prose (e.g. the "pick up the next child" note) is preserved.
+function syncOrderList(body, orderedRefs, titleFor) {
+  const m = body.match(ORDER_SECTION_RE);
+  if (!m || m.index === undefined) return body;
+  const headingEnd = m.index + m[0].length;
+  const rest = body.slice(headingEnd);
+  const nextRel = rest.search(/^##\s+/m);
+  const sectionEnd = nextRel >= 0 ? headingEnd + nextRel : body.length;
+
+  const lines = body.slice(headingEnd, sectionEnd).split('\n');
+  const isItem = (l) => /^\s*(?:\d+\.|[-*])\s+/.test(l) && /\.md(?:[#)\s]|$)/.test(l);
+  let start = -1, end = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (isItem(lines[i])) { if (start === -1) start = i; end = i; }
+    else if (start !== -1) break; // first non-item after the block ends it
+  }
+  if (start === -1) return body; // section present but no list to sync
+
+  const linkRe = /\[([^\]]+)\]\(([^)]+\.md)(?:#[^)]*)?\)/;
+  const prior = new Map(); // basename → { title, marker }
+  for (let i = start; i <= end; i++) {
+    const lk = linkRe.exec(lines[i]);
+    if (lk) {
+      prior.set(lk[2].split('/').pop(), { title: lk[1], marker: lines[i].slice(lk.index + lk[0].length).trim() });
+    } else {
+      const bare = /(\S+\.md)/.exec(lines[i]);
+      if (bare) prior.set(bare[1].split('/').pop(), { title: null, marker: lines[i].slice(bare.index + bare[0].length).trim() });
+    }
+  }
+
+  const rebuilt = orderedRefs.map((ref, i) => {
+    const prev = prior.get(ref.split('/').pop());
+    const title = prev?.title ?? titleFor(ref);
+    const marker = prev?.marker ? ` ${prev.marker}` : ' ⬜';
+    return `${i + 1}. [${title}](${ref})${marker}`;
+  });
+
+  const newLines = [...lines.slice(0, start), ...rebuilt, ...lines.slice(end + 1)];
+  return body.slice(0, headingEnd) + newLines.join('\n') + body.slice(sectionEnd);
+}
+
+// Authoritative hub write: set `runlist:` to `newRefs`, bump `updated:`, and
+// resync the body order list. Shared by add/remove/reorder so all three keep
+// the frontmatter array and the body link list consistent.
+function writeHubRunlist(hubAbs, newRefs, config, today) {
+  const raw = readFileSync(hubAbs, 'utf8');
+  const { frontmatter: fmRaw, body } = extractFrontmatter(raw);
+  let newFm = upsertFrontmatterField(fmRaw, 'runlist', serializeBlockArray('runlist', newRefs));
+  newFm = upsertFrontmatterField(newFm, 'updated', `updated: ${today}`);
+
+  const titles = new Map();
+  for (const r of resolveRunlistRefs(newRefs, hubAbs, config)) {
+    if (r.title) titles.set(r.ref.split('/').pop(), r.title);
+  }
+  const titleFor = (ref) => titles.get(ref.split('/').pop()) ?? titleize(path.basename(ref, '.md'));
+  const newBody = syncOrderList(body, newRefs, titleFor);
+
+  writeFileSync(hubAbs, `---\n${newFm}\n---\n${newBody}`, 'utf8');
+}
+
+// Match a child token to one of the hub's existing runlist refs. Resolves
+// hub-relative (then by slug/basename across the index), then compares against
+// each ref's resolved abs path, with a basename fallback for refs that don't
+// resolve to a file. Returns the matched ref string, or null.
+function findRefForToken(token, existingRefs, hubDir, config) {
+  const tokenAbs = resolveRefPath(token, hubDir, config.repoRoot)
+    || (token.endsWith('.md') ? null : resolveRefPath(`${token}.md`, hubDir, config.repoRoot))
+    || resolveDocArg(token, config, { dieOnMiss: false });
+  const tokBase = token.endsWith('.md') ? token.split('/').pop() : `${token.split('/').pop()}.md`;
+  // Exact: resolved-path match or basename match.
+  for (const ref of existingRefs) {
+    const refAbs = resolveRefPath(ref, hubDir, config.repoRoot);
+    if (tokenAbs && refAbs && refAbs === tokenAbs) return ref;
+    if (ref.split('/').pop() === tokBase) return ref;
+  }
+  // Convenience: the short slug a sprint child was scaffolded from — e.g.
+  // `cleanup` matches `auth-revamp-03-cleanup.md`. Unique-or-bust so an
+  // ambiguous slug never silently picks the wrong child.
+  const slug = tokBase.replace(/\.md$/, '');
+  const suffixMatches = existingRefs.filter(ref => {
+    const base = ref.split('/').pop().replace(/\.md$/, '');
+    return base === slug || base.endsWith(`-${slug}`);
+  });
+  if (suffixMatches.length === 1) return suffixMatches[0];
+  if (suffixMatches.length > 1) {
+    die(`"${token}" matches multiple children: ${suffixMatches.join(', ')}. Use the full filename.`);
+  }
+  return null;
+}
+
+// Clear a removed child's `parent_plan:` when it points back at this hub (so the
+// reverse link doesn't dangle). Leaves a parent_plan pointing elsewhere alone.
+function clearChildParentPlan(childAbs, hubAbs, config, { dryRun }) {
+  let raw;
+  try { raw = readFileSync(childAbs, 'utf8'); } catch { return false; }
+  const { frontmatter: fmRaw } = extractFrontmatter(raw);
+  if (fmRaw == null) return false;
+  const fm = parseSimpleFrontmatter(fmRaw);
+  const existing = asString(fm.parent_plan);
+  if (!existing) return false;
+  if (resolveRefPath(existing, path.dirname(childAbs), config.repoRoot) !== hubAbs) return false;
+  if (dryRun) return true;
+  let newFm = upsertFrontmatterField(fmRaw, 'parent_plan', 'parent_plan:');
+  newFm = upsertFrontmatterField(newFm, 'updated', `updated: ${nowIso()}`);
+  writeFileSync(childAbs, replaceFrontmatter(raw, newFm), 'utf8');
+  return true;
+}
+
+// Shared front half of remove/reorder: resolve the hub, read its `runlist:`,
+// die if it isn't a sprint hub with an array to mutate.
+function loadSprintHub(hubInput, verb, config) {
+  if (!hubInput) die(`Usage: dotmd runlist ${verb} <hub-plan> <child...>`);
+  const hubAbs = resolveHubInput(hubInput, config);
+  if (!hubAbs) die(`Hub plan not found: ${hubInput}`);
+  const hubRepoPath = toRepoPath(hubAbs, config.repoRoot);
+  const hubDir = path.dirname(hubAbs);
+  const raw = readFileSync(hubAbs, 'utf8');
+  const { frontmatter: fmRaw } = extractFrontmatter(raw);
+  const fm = fmRaw == null ? {} : parseSimpleFrontmatter(fmRaw);
+  const existingRefs = normalizeStringList(fm.runlist);
+  if (existingRefs.length === 0) {
+    die(`${hubRepoPath} has no \`runlist:\` array to ${verb} from.` +
+      (fm.execution_mode === 'coordination' ? ' (It is a coordination hub — order lives in the body.)' : ''));
+  }
+  return { hubAbs, hubRepoPath, hubDir, existingRefs };
+}
+
+async function runRunlistRemove(positional, config, { dryRun, json, clearParent }) {
+  const { hubAbs, hubRepoPath, hubDir, existingRefs } = loadSprintHub(positional[0], 'remove', config);
+  const childTokens = positional.slice(1);
+  if (childTokens.length === 0) die('Usage: dotmd runlist remove <hub-plan> <child...>');
+
+  const removeRefs = [];
+  for (const token of childTokens) {
+    const ref = findRefForToken(token, existingRefs, hubDir, config);
+    if (!ref) die(`"${token}" is not in the runlist of ${hubRepoPath}.`);
+    if (!removeRefs.includes(ref)) removeRefs.push(ref);
+  }
+  const newRefs = existingRefs.filter(r => !removeRefs.includes(r));
+  const today = nowIso();
+
+  if (json) {
+    process.stdout.write(JSON.stringify({ hub: hubRepoPath, removed: removeRefs, runlist: newRefs, clearedParent: !!clearParent, dryRun: !!dryRun }, null, 2) + '\n');
+  } else {
+    process.stdout.write(bold(`${dryRun ? dim('[dry-run]') + ' ' : ''}runlist remove → ${hubRepoPath}`) + '\n');
+    for (const ref of removeRefs) process.stdout.write(`${dryRun ? dim('[dry-run]') + ' ' : ''}  ${red('-')} ${ref}\n`);
+  }
+
+  if (!dryRun) writeHubRunlist(hubAbs, newRefs, config, today);
+  if (clearParent) {
+    for (const ref of removeRefs) {
+      const abs = resolveRefPath(ref, hubDir, config.repoRoot);
+      if (abs && clearChildParentPlan(abs, hubAbs, config, { dryRun }) && !json) {
+        process.stdout.write(`${dryRun ? dim('[dry-run]') + ' ' : ''}  ${dim(`cleared parent_plan on ${toRepoPath(abs, config.repoRoot)}`)}\n`);
+      }
+    }
+  }
+  if (!json) process.stdout.write(dim(`  runlist now has ${newRefs.length} ${newRefs.length === 1 ? 'child' : 'children'}.`) + '\n');
+}
+
+// Parse `reorder` argv: skip the subcommand + flags, capture `--before`/`--after`
+// values (their operands would otherwise leak into the child list).
+function parseReorderArgs(argv) {
+  const pos = [];
+  let before = null, after = null;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === 'reorder') continue;
+    if (a === '--before') { before = argv[++i] ?? null; continue; }
+    if (a === '--after') { after = argv[++i] ?? null; continue; }
+    if (a.startsWith('-')) continue;
+    pos.push(a);
+  }
+  return { hubInput: pos[0], children: pos.slice(1), before, after };
+}
+
+async function runRunlistReorder(argv, config, { dryRun, json }) {
+  const { hubInput, children, before, after } = parseReorderArgs(argv);
+  if (!hubInput || children.length === 0) {
+    die('Usage: dotmd runlist reorder <hub> <child> --before|--after <other>\n   or: dotmd runlist reorder <hub> <child1> <child2> ...  (full new order)');
+  }
+  const { hubAbs, hubRepoPath, hubDir, existingRefs } = loadSprintHub(hubInput, 'reorder', config);
+
+  let newRefs;
+  if (before || after) {
+    if (children.length !== 1) die('--before/--after move exactly one child. Pass a single child, or list every child for a full reorder.');
+    const moving = findRefForToken(children[0], existingRefs, hubDir, config);
+    if (!moving) die(`"${children[0]}" is not in the runlist of ${hubRepoPath}.`);
+    const anchorTok = before || after;
+    const anchor = findRefForToken(anchorTok, existingRefs, hubDir, config);
+    if (!anchor) die(`"${anchorTok}" is not in the runlist of ${hubRepoPath}.`);
+    if (moving === anchor) die('A child cannot be moved relative to itself.');
+    const without = existingRefs.filter(r => r !== moving);
+    const idx = without.indexOf(anchor);
+    const insertAt = before ? idx : idx + 1;
+    newRefs = [...without.slice(0, insertAt), moving, ...without.slice(insertAt)];
+  } else {
+    if (children.length !== existingRefs.length) {
+      die(`Full reorder needs all ${existingRefs.length} children in the new order; got ${children.length}. Use --before/--after to move just one.`);
+    }
+    newRefs = children.map(tok => {
+      const ref = findRefForToken(tok, existingRefs, hubDir, config);
+      if (!ref) die(`"${tok}" is not in the runlist of ${hubRepoPath}.`);
+      return ref;
+    });
+    if (new Set(newRefs).size !== newRefs.length) die('The new order repeats a child — list each exactly once.');
+  }
+
+  if (newRefs.join('\n') === existingRefs.join('\n')) die('New order matches the current order — nothing to do.');
+  const today = nowIso();
+
+  if (json) {
+    process.stdout.write(JSON.stringify({ hub: hubRepoPath, runlist: newRefs, dryRun: !!dryRun }, null, 2) + '\n');
+  } else {
+    process.stdout.write(bold(`${dryRun ? dim('[dry-run]') + ' ' : ''}runlist reorder → ${hubRepoPath}`) + '\n');
+    newRefs.forEach((ref, i) => process.stdout.write(`${dryRun ? dim('[dry-run]') + ' ' : ''}  ${String(i + 1).padStart(2)}. ${ref}\n`));
+  }
+  if (!dryRun) writeHubRunlist(hubAbs, newRefs, config, today);
+}
+
 export async function runRunlist(argv, config, opts = {}) {
   const json = argv.includes('--json');
   const positional = argv.filter(a => !a.startsWith('-'));
 
-  // Subcommand dispatch: `runlist <hub>` (show) vs `runlist next <hub>` (pickup)
+  // Subcommand dispatch: mutators (`add`/`remove`/`reorder`) vs `next` (pickup)
+  // vs `show` (default).
+  if (positional[0] === 'add') {
+    return runRunlistAdd(positional.slice(1), config, { dryRun: opts.dryRun, json });
+  }
+  if (positional[0] === 'remove') {
+    return runRunlistRemove(positional.slice(1), config, { dryRun: opts.dryRun, json, clearParent: argv.includes('--clear-parent') });
+  }
+  if (positional[0] === 'reorder') {
+    return runRunlistReorder(argv, config, { dryRun: opts.dryRun, json });
+  }
+
   const sub = positional[0] === 'next' ? 'next' : 'show';
   const hubInput = sub === 'next' ? positional[1] : positional[0];
 
@@ -370,11 +849,29 @@ export async function runRunlist(argv, config, opts = {}) {
     return;
   }
 
-  // sub === 'next' — find first non-archived non-missing child and pick it up.
-  const target = children.find(c => !c.missing && !archiveStatuses.has(c.status));
+  // sub === 'next' — pick up the first child a session can actually start.
+  // Skip both archived (done) and parked (blocked/partial/paused/awaiting/
+  // queued-after) children: the runlist advances to the first pickup-able one,
+  // so the picked target is guaranteed in a `dotmd use`-able status.
+  const target = children.find(c => !c.missing && !archiveStatuses.has(c.status) && isPickupable(c.status));
   if (!target) {
     if (children.length === 0) die(`Hub ${hubRepoPath} has empty \`runlist:\` — nothing to pick up.`);
-    const allArchived = children.every(c => !c.missing && archiveStatuses.has(c.status));
+    // Live (non-archived, non-missing) children that exist but aren't startable.
+    const parked = children.filter(c => !c.missing && !archiveStatuses.has(c.status));
+    if (parked.length > 0) {
+      // Every remaining child is parked — surface them with statuses + the
+      // unstick verbs so the agent can resume one instead of being told a
+      // generic "no pickup" with no path forward.
+      const listed = parked.map(c => `  ${c.path} (status: ${c.status})`).join('\n');
+      die(
+        `No pickup-able child in runlist ${hubRepoPath} — every remaining child is parked:\n` +
+        `${listed}\n` +
+        `Unstick one before continuing:\n` +
+        `  dotmd set active <child>   # if ready to resume\n` +
+        `  dotmd use <child>          # to inspect`,
+      );
+    }
+    const allArchived = children.some(c => !c.missing) && children.every(c => c.missing || archiveStatuses.has(c.status));
     if (allArchived) {
       die(`All children in runlist ${hubRepoPath} are archived. Hub is ready for \`dotmd archive ${hubRepoPath}\`.`);
     }
@@ -382,18 +879,6 @@ export async function runRunlist(argv, config, opts = {}) {
     die(`No pickup-able child in runlist ${hubRepoPath}. Unresolved refs: ${missing.join(', ')}`);
   }
 
-  // Pre-check status: pickup will die on non-pickup-able statuses, but with
-  // a generic message. Surface the runlist context first so the agent knows
-  // which list is blocked and on which item.
-  if (!PICKUPABLE_STATUSES.has(target.status)) {
-    die(
-      `Next child in runlist ${hubRepoPath} is ${target.path} (status: ${target.status}).\n` +
-      `Resolve the blocker before continuing the runlist.\n` +
-      `  dotmd set active ${target.path}   # if ready to resume\n` +
-      `  dotmd use ${target.path}          # to inspect`,
-    );
-  }
-
   // Open the next child: set it in-session (frontmatter) and render its card.
   // Dynamic import to avoid circular module-load cost when the runlist command
   // isn't used.