dotmd-cli 0.60.0 → 0.62.0

package/src/render.mjs

@@ -5,6 +5,7 @@ import { extractFrontmatter } from './frontmatter.mjs';
 import { summarizeDocBody } from './ai.mjs';
 import { bold, red, yellow, green, dim } from './color.mjs';
 import { categorizeWarnings } from './check-collapse.mjs';
+import { buildCoordinationIndex } from './runlist.mjs';
 
 // Render `currentState` with an `(auto)` prefix when the value was body-scraped
 // rather than read from frontmatter. Lets a reader see at a glance which docs
@@ -322,6 +323,15 @@ export function renderBriefing(index, config) {
   const research = index.docs.filter(d => d.type === 'research');
   const untyped = index.docs.filter(d => !d.type);
 
+  // Coordination hubs (prose-first runlists) are navigation maps, not units of
+  // work — so lift them out of the live-plan status breakdown into their own
+  // `runlists` bucket and drop them from the actionable `>` list, mirroring
+  // `dotmd plans` / `dotmd runlists`. (Sprint `runlist:` hubs stay as ordinary
+  // plans here; their folding treatment is scoped to `dotmd plans`.) On a repo
+  // with no coordination hubs this is a no-op and the output is unchanged.
+  const coordination = buildCoordinationIndex(index, config);
+  const isHub = (p) => coordination.has(p.path);
+
   if (plans.length) {
     // Headline counts LIVE plans first — "30 plans: 25 archived, …" skims as
     // 30 open work items when zero are. "Live" mirrors the `dotmd plans`
@@ -331,17 +341,26 @@ export function renderBriefing(index, config) {
       ...(config.lifecycle?.terminalStatuses ?? []),
     ]);
     const live = plans.filter(p => !closed.has(p.status) && !isArchivedPath(p.path, config));
+    const liveHubs = live.filter(isHub);
     const bySt = {};
-    for (const p of live) { bySt[p.status] = (bySt[p.status] ?? 0) + 1; }
-    const counts = Object.entries(bySt).map(([s, n]) => `${n} ${s}`).join(', ');
+    for (const p of live) { if (isHub(p)) continue; bySt[p.status] = (bySt[p.status] ?? 0) + 1; }
+    // Runlists lead the breakdown (then leaf statuses), and the bucket sums back
+    // to the live total so the headline stays honest.
+    const countParts = [];
+    if (liveHubs.length) countParts.push(`${liveHubs.length} runlist${liveHubs.length === 1 ? '' : 's'}`);
+    countParts.push(...Object.entries(bySt).map(([s, n]) => `${n} ${s}`));
+    const counts = countParts.join(', ');
     const closedCount = plans.length - live.length;
     const closedPart = closedCount ? ` (${closedCount} archived)` : '';
     lines.push(live.length ? `${live.length} live plans${closedPart}: ${counts}` : `0 live plans${closedPart}`);
-    const show = plans.filter(p => p.status === 'in-session' || p.status === 'active');
+    const show = plans.filter(p => (p.status === 'in-session' || p.status === 'active') && !isHub(p));
     for (const p of show) {
       const next = p.nextStep ? `next: ${p.nextStep}` : '(no next step)';
       lines.push(`  > ${path.basename(p.path, '.md')} (${p.status}) ${next}`);
     }
+    if (liveHubs.length) {
+      lines.push(`  ${liveHubs.length} runlist${liveHubs.length === 1 ? '' : 's'} ${dim('· dotmd runlists')}`);
+    }
   }
 
   const parts = [];

package/src/runlist.mjs

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

package/src/validate.mjs

@@ -433,6 +433,33 @@ export function checkRunlistBackPointers(docs, config) {
   return warnings;
 }
 
+// Coordination-hub hygiene: a plan whose slug is `*-runlist` / `runlist` reads
+// as a coordination runlist, but `dotmd plans` only *reliably* lifts it into the
+// Runlists section (and out of the active count) when `execution_mode:
+// coordination` is set. Slug detection is the fallback; the frontmatter field is
+// the canonical signal. Nudge the few hubs that lean on the slug alone to make
+// it explicit. Skips terminal/quiet statuses like every other warning-only check.
+export function checkCoordinationHubExecutionMode(docs, config) {
+  const warnings = [];
+  const skipStatuses = new Set([
+    ...(config.lifecycle.terminalStatuses ?? []),
+    ...(config.lifecycle.skipWarningsFor ?? []),
+  ]);
+  for (const doc of docs) {
+    if (doc.type && doc.type !== 'plan') continue;
+    if (skipStatuses.has(doc.status)) continue;
+    if (doc.executionMode === 'coordination') continue;
+    const base = (doc.path.split('/').pop() || '').replace(/\.md$/, '');
+    if (base !== 'runlist' && !base.endsWith('-runlist')) continue;
+    warnings.push({
+      path: doc.path,
+      level: 'warning',
+      message: `reads as a coordination runlist (slug \`${base}\`) but is missing \`execution_mode: coordination\`. Add it so \`dotmd plans\` / \`dotmd runlists\` reliably treat it as a runlist, not an active plan.`,
+    });
+  }
+  return warnings;
+}
+
 export function checkGitStaleness(docs, config) {
   const warnings = [];
   const gitDates = getGitLastModifiedBatch(config.repoRoot);
@@ -475,7 +502,7 @@ export function validatePlanShape(doc, body, frontmatter, config) {
     doc.warnings.push({
       path: doc.path,
       level: 'warning',
-      message: `\`next_step\` is ${nextStep.length} chars (cap: 800). Long prose belongs in the body — keep next_step as a 1-2 sentence pointer.`,
+      message: `\`next_step\` is ${nextStep.length} chars (cap: 800). One mechanical fix: \`dotmd doctor --frontmatter-fix\` (moves the overflow into the body) — do NOT hand-trim or re-run check in a loop. Going forward, write next_step as a 1-2 sentence pointer; detail goes in the body.`,
     });
   }
 
@@ -488,7 +515,7 @@ export function validatePlanShape(doc, body, frontmatter, config) {
     doc.warnings.push({
       path: doc.path,
       level: 'warning',
-      message: `\`current_state\` is ${currentState.length} chars (cap: 1500). Long prose belongs in the body.`,
+      message: `\`current_state\` is ${currentState.length} chars (cap: 1500). One mechanical fix: \`dotmd doctor --frontmatter-fix\` (moves the overflow into the body) — do NOT hand-trim or re-run check in a loop. Going forward, write current_state as a 2-4 sentence summary; detail goes in the body.`,
     });
   }