dotmd-cli 0.61.0 → 0.63.0

package/src/runlist.mjs

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

package/src/validate.mjs

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