dotmd-cli 0.62.0 → 0.63.0

package/bin/dotmd.mjs

@@ -1225,14 +1225,19 @@ 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.`,
+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, and a one-line descriptor.
+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.
@@ -1240,7 +1245,7 @@ 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, …).`,
+  dotmd runlists --json        Structured rows (path, status, childCount, nextPickup, …).`,
 
   'bulk-tag': `dotmd bulk-tag [files...] — fill in type/status frontmatter on pre-existing markdown
 

package/package.json

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

@@ -87,7 +87,7 @@ 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 })) },
+      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;
   }
@@ -122,9 +122,10 @@ export function runHealth(argv, config) {
     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`);
+      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`);

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) {

package/src/query.mjs

@@ -162,6 +162,7 @@ export function runRunlists(index, argv, config) {
       status: d.status,
       title: d.title,
       childCount: coordination.get(d.path)?.childCount ?? 0,
+      nextPickup: coordination.get(d.path)?.nextPickup ?? null,
       updated: d.updated,
       nextStep: d.nextStep ?? null,
     }));
@@ -782,9 +783,18 @@ function renderCoordinationSection(coordDocs, coordination, maxWidth, total) {
     const statusTag = doc.status && doc.status !== 'active' ? ` ${colorTag(doc.status)}` : '';
     const desc = (doc.nextStep || doc.currentState || doc.title || '').replace(/\s+/g, ' ').trim();
 
+    // Next-pickup (first non-archived ranked child from the body) leads the
+    // description column when one resolves — it's the most actionable cell. Its
+    // status is shown only when it's not the expected `active`.
+    const next = info?.nextPickup;
+    const nextStr = next
+      ? `${green('→')} ${next.label}${next.status && next.status !== 'active' ? dim(` (${next.status})`) : ''}`
+      : '';
+    const nextPart = nextStr ? `${nextStr}  ` : '';
+
     const left = `  ${slug}  ${ageStr}  ${dim(count)}  `;
-    const budget = Math.max(10, maxWidth - visibleLen(left) - visibleLen(statusTag) - 2);
+    const budget = Math.max(10, maxWidth - visibleLen(left) - visibleLen(nextPart) - visibleLen(statusTag) - 2);
     const descR = desc.length > budget ? desc.slice(0, budget - 3) + '...' : desc;
-    process.stdout.write(`${left}${dim(descR)}${statusTag}\n`);
+    process.stdout.write(`${left}${nextPart}${dim(descR)}${statusTag}\n`);
   }
 }

package/src/runlist.mjs

@@ -89,6 +89,10 @@ export function isCoordinationHub(doc) {
 // 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.
+// Each hub also gets a `nextPickup` (or null) parsed from its body order — the
+// first non-archived ranked child — so prose-first hubs surface a next-pickup
+// target the way sprint `runlist:` hubs do. Reads each hub's file (a small,
+// bounded set), so this is no longer pure in-memory like `buildRunlistIndex`.
 export function buildCoordinationIndex(index, config) {
   const docByPath = new Map(index.docs.map(d => [d.path, d]));
   const byBasename = new Map();
@@ -96,6 +100,15 @@ export function buildCoordinationIndex(index, config) {
     const base = d.path.split('/').pop();
     if (!byBasename.has(base)) byBasename.set(base, d);
   }
+  const archiveStatuses = config.lifecycle?.archiveStatuses ?? new Set(['archived']);
+
+  // Resolve a path-or-basename ref (from frontmatter or body) to an indexed doc.
+  const resolveRef = (ref, dir) => {
+    const abs = resolveRefPath(ref, dir, config.repoRoot);
+    let child = abs ? docByPath.get(toRepoPath(abs, config.repoRoot)) ?? null : null;
+    if (!child) child = byBasename.get(ref.split('/').pop()) ?? null;
+    return child;
+  };
 
   const hubs = new Map();
   for (const doc of index.docs) {
@@ -104,14 +117,13 @@ export function buildCoordinationIndex(index, config) {
     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;
+      const child = resolveRef(ref, dir);
       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 });
+    const nextPickup = resolveHubNextPickup(doc, dir, resolveRef, archiveStatuses, config);
+    hubs.set(doc.path, { doc, childCount: childPaths.size, childPaths, nextPickup });
   }
   return hubs;
 }
@@ -169,28 +181,93 @@ function resolveRunlistRefs(refs, hubAbsPath, config) {
   return out;
 }
 
+// Extract ordered plan refs from a hub's body prose. Two shapes:
+//   - link-list sections (`## Order of operations`, `## Runlist`, …) — every
+//     `.md` link or checklist item, in document order.
+//   - ranked-queue tables (`## Ranked queue`, …) — the first `.md` link in each
+//     table row (the ranked plan); header/separator rows contribute none.
+// Coordination hubs encode their next-pickup order in the table shape; sprint-
+// ish hubs use the link list. Deduped, first occurrence wins, order preserved.
 function detectBodyRunlistRefs(body) {
   if (!body) return [];
-  const sectionRe = /^##\s+(Order of operations|Runlist|Execution order|Implementation order|Plan order)\s*$/gim;
   const refs = [];
-  let match;
-  while ((match = sectionRe.exec(body)) !== null) {
-    const start = match.index + match[0].length;
+  const linkRe = /\[[^\]]+\]\(([^)]+\.md(?:#[^)]+)?)\)/;
+  const sliceSection = (start) => {
     const rest = body.slice(start);
     const next = rest.search(/^##\s+/m);
-    const section = next >= 0 ? rest.slice(0, next) : rest;
+    return next >= 0 ? rest.slice(0, next) : rest;
+  };
 
-    const linkRe = /\[[^\]]+\]\(([^)]+\.md(?:#[^)]+)?)\)/g;
+  const linkSectionRe = /^##\s+(?:Order of operations|Runlist|Execution order|Implementation order|Plan order)\b.*$/gim;
+  let match;
+  while ((match = linkSectionRe.exec(body)) !== null) {
+    const section = sliceSection(match.index + match[0].length);
+    const allLinks = new RegExp(linkRe.source, 'g');
     let link;
-    while ((link = linkRe.exec(section)) !== null) refs.push(link[1]);
+    while ((link = allLinks.exec(section)) !== null) refs.push(link[1]);
 
     const checklistRe = /^\s*[-*]\s+\[[ xX]\]\s+([^\s)]+\.md(?:#[^\s)]+)?)/gm;
     let item;
     while ((item = checklistRe.exec(section)) !== null) refs.push(item[1]);
   }
+
+  // Ranked-queue tables: the first `.md` link per row is the ranked plan. A
+  // header (`| Rank | Plan | … |`) and separator (`|---|`) carry no link and are
+  // skipped naturally. Heading may carry trailing text (`## Ranked queue (next
+  // pickup)`), so match the leading words, not an exact line.
+  const queueSectionRe = /^##\s+(?:Ranked queue|Queue|Pickup order|Heads)\b.*$/gim;
+  while ((match = queueSectionRe.exec(body)) !== null) {
+    const section = sliceSection(match.index + match[0].length);
+    for (const rawLine of section.split('\n')) {
+      const line = rawLine.trim();
+      if (!line.startsWith('|')) continue;
+      const link = linkRe.exec(line);
+      if (link) refs.push(link[1]);
+    }
+  }
+
   return [...new Set(refs)];
 }
 
+// Label for a hub's next-pickup child: its slug with the hub's leading module
+// segment stripped when shared (so `founder-runlist` → `founder-brand-conflicts`
+// reads as `brand-conflicts`), mirroring how sprint children drop the hub
+// prefix. Falls back to the full slug when there's no shared leading segment.
+function coordinationChildLabel(childDoc, hubDoc) {
+  const childSlug = toSlug(childDoc);
+  const seg = toSlug(hubDoc).split('-')[0];
+  if (seg.length >= 2 && childSlug.startsWith(`${seg}-`) && childSlug.length > seg.length + 1) {
+    return childSlug.slice(seg.length + 1);
+  }
+  return childSlug;
+}
+
+// Read a coordination hub's body order (a `## Ranked queue` table or a
+// `## Order of operations` link list) and return its NEXT PICKUP: the first
+// ranked child that isn't archived, resolved to its live status from the index.
+// Prose-first hubs keep their sequence in the body, invisible to the
+// frontmatter-only index — this surfaces `next → <child>` the way sprint
+// `runlist:` hubs already do. Returns null when the hub has no parseable body
+// order or every ranked child is archived. Best-effort: a read failure degrades
+// to null, never throws.
+function resolveHubNextPickup(hubDoc, hubDir, resolveRef, archiveStatuses, config) {
+  let body;
+  try {
+    ({ body } = extractFrontmatter(readFileSync(path.join(config.repoRoot, hubDoc.path), 'utf8')));
+  } catch {
+    return null;
+  }
+  for (const ref of detectBodyRunlistRefs(body)) {
+    const child = resolveRef(ref, hubDir);
+    if (!child || child.path === hubDoc.path) continue;
+    if (child.type && child.type !== 'plan') continue;
+    const archived = archiveStatuses.has(child.status) || isArchivedPath(child.path, config);
+    if (archived) continue;
+    return { path: child.path, status: child.status ?? null, label: coordinationChildLabel(child, hubDoc) };
+  }
+  return null;
+}
+
 function readRunlistChildren(hubAbsPath, config) {
   const raw = readFileSync(hubAbsPath, 'utf8');
   const { frontmatter: fmRaw, body } = extractFrontmatter(raw);