dotmd-cli 0.39.6 → 0.39.7

package/bin/dotmd.mjs

@@ -49,6 +49,7 @@ Validate & Fix:
 Lifecycle:
   pickup <file> [--takeover]        Pick up a plan (set in-session + print body)
   release [<file>] [--to <s>]       Release in-session lease (alias: unpickup)
+  runlist <hub> [next]              Show or walk an ordered group of plans (see \`dotmd help runlist\`)
   finish <file> [done|active]       Finish a plan (set done or active)
   status <file> <status>            Transition document status
   archive <file>                    Archive (status + move + update refs)
@@ -897,6 +898,40 @@ 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
+
+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>     Pick up the first non-archived child.
+                               Stops if it's not in a pickup-able status
+                               (active / planned / in-session) so you resolve
+                               the blocker before continuing the runlist.
+
+Flags (only meaningful with \`next\`, forwarded to pickup):
+  --takeover         Override a held lease.
+  --full             Print full plan body instead of the pickup card.
+  --no-index         Skip index regeneration.
+  --show-files       Emit \`files: …\` footer.
+
+Common shape:
+  ---
+  type: plan
+  status: active
+  title: Auth Revamp
+  runlist:
+    - auth-revamp-01-extract.md
+    - auth-revamp-02-rewrite.md
+    - auth-revamp-03-cleanup.md
+  ---
+
+Child plans should set \`parent_plan:\` back at the hub — \`dotmd check\` warns
+when they don't.`,
+
   'bulk-tag': `dotmd bulk-tag [files...] — fill in type/status frontmatter on pre-existing markdown
 
 Scans the docs tree for files that are missing either \`type:\` or \`status:\`
@@ -1061,6 +1096,7 @@ async function main() {
   if (command === 'journal') { const { runJournal } = await import('../src/journal-read.mjs'); runJournal(restArgs, config); return; }
   if (command === 'pickup') { const { runPickup } = await import('../src/lifecycle.mjs'); await runPickup(restArgs, config, { dryRun }); return; }
   if (command === 'unpickup' || command === 'release') { const { runUnpickup } = await import('../src/lifecycle.mjs'); await runUnpickup(restArgs, config, { dryRun }); return; }
+  if (command === 'runlist') { const { runRunlist } = await import('../src/runlist.mjs'); await runRunlist(restArgs, config, { dryRun }); return; }
   if (command === 'handoff') { die('`dotmd handoff` was removed in 0.31.0. Use `dotmd prompts new <name>` to create a saved prompt instead. The .dotmd/handoffs/ sidecar mechanism no longer exists; see CHANGELOG.'); }
   if (command === 'finish') { const { runFinish } = await import('../src/lifecycle.mjs'); await runFinish(restArgs, config, { dryRun }); return; }
   if (command === 'status') { const { runStatus } = await import('../src/lifecycle.mjs'); await runStatus(restArgs, config, { dryRun }); return; }

package/package.json

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

package/src/config.mjs

@@ -89,7 +89,7 @@ const DEFAULTS = {
     // resolver work without config. Override by setting `referenceFields`
     // in your config — your value fully replaces (no per-field merge).
     bidirectional: ['related_plans', 'related_docs'],
-    unidirectional: ['parent_plan'],
+    unidirectional: ['parent_plan', 'runlist'],
   },
 
   templates: {},

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 } from './util.mjs';
-import { validateDoc, validatePlanShape, validateDocShape, checkBidirectionalReferences, checkGitStaleness, computeDaysSinceUpdate, computeIsStale, computeChecklistCompletionRate, enrichRefErrorSuggestions } from './validate.mjs';
+import { validateDoc, validatePlanShape, validateDocShape, checkBidirectionalReferences, checkGitStaleness, checkRunlistBackPointers, computeDaysSinceUpdate, computeIsStale, computeChecklistCompletionRate, enrichRefErrorSuggestions } from './validate.mjs';
 import { checkIndex } from './index-file.mjs';
 import { checkClaudeCommands } from './claude-commands.mjs';
 
@@ -96,6 +96,13 @@ export function buildIndex(config, opts = {}) {
     const refCheck = checkBidirectionalReferences(transformedDocs, config);
     warnings.push(...refCheck.warnings);
 
+    const runlistWarnings = checkRunlistBackPointers(transformedDocs, config);
+    warnings.push(...runlistWarnings);
+    for (const w of runlistWarnings) {
+      const child = transformedDocs.find(d => d.path === w.path);
+      if (child) child.warnings.push(w);
+    }
+
     const gitWarnings = checkGitStaleness(transformedDocs, config);
     warnings.push(...gitWarnings);
 

package/src/init.mjs

@@ -64,7 +64,7 @@ export const index = {
 // Add field names here (and to your templates) to track more relationships.
 export const referenceFields = {
   bidirectional: ['related_plans', 'related_docs'],
-  unidirectional: ['parent_plan'],
+  unidirectional: ['parent_plan', 'runlist'],
 };
 `;
 

package/src/runlist.mjs

@@ -0,0 +1,169 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import {
+  asString,
+  die,
+  normalizeStringList,
+  resolveDocPath,
+  resolveRefPath,
+  toRepoPath,
+  toSlug,
+} from './util.mjs';
+import { bold, cyan, dim, green, red, yellow } from './color.mjs';
+
+const PICKUPABLE_STATUSES = new Set(['active', 'planned', 'in-session']);
+
+// Read a hub plan's `runlist:` and resolve each entry to a repo-relative path
+// plus its current status. Missing files are reported with `missing: true`;
+// callers decide how to render them. Pure: no IO beyond file reads.
+function readRunlistChildren(hubAbsPath, config) {
+  const raw = readFileSync(hubAbsPath, 'utf8');
+  const { frontmatter: fmRaw } = extractFrontmatter(raw);
+  const fm = parseSimpleFrontmatter(fmRaw);
+  const refs = normalizeStringList(fm.runlist);
+
+  const hubDir = path.dirname(hubAbsPath);
+  const out = [];
+  for (const ref of refs) {
+    const abs = resolveRefPath(ref, hubDir, config.repoRoot);
+    if (!abs) {
+      out.push({ ref, path: null, status: null, title: null, missing: true });
+      continue;
+    }
+    const repoPath = toRepoPath(abs, config.repoRoot);
+    try {
+      const childRaw = readFileSync(abs, 'utf8');
+      const { frontmatter: childFmRaw } = extractFrontmatter(childRaw);
+      const childFm = parseSimpleFrontmatter(childFmRaw);
+      out.push({
+        ref,
+        path: repoPath,
+        status: asString(childFm.status) ?? null,
+        title: asString(childFm.title) ?? path.basename(abs, '.md'),
+        parentPlan: childFm.parent_plan ?? null,
+        missing: false,
+      });
+    } catch {
+      out.push({ ref, path: repoPath, status: null, title: null, missing: true });
+    }
+  }
+  return out;
+}
+
+const STATUS_TAG_COLORS = {
+  'in-session': (s) => bold(red(s)),
+  'active': green,
+  'planned': (s) => s,
+  'blocked': yellow,
+  'partial': (s) => dim(green(s)),
+  'paused': (s) => yellow(s),
+  'awaiting': yellow,
+  'queued-after': (s) => dim(cyan(s)),
+  'archived': dim,
+};
+
+function colorStatus(status) {
+  const fn = STATUS_TAG_COLORS[status] ?? ((s) => s);
+  return fn(status ?? 'unknown');
+}
+
+function renderRunlist(hubRepoPath, children, opts = {}) {
+  const lines = [];
+  lines.push(bold(`runlist: ${hubRepoPath}`));
+  if (children.length === 0) {
+    lines.push(dim('  (empty — add child plan paths to the hub plan\'s `runlist:` field)'));
+    return lines.join('\n') + '\n';
+  }
+
+  const archiveStatuses = opts.archiveStatuses ?? new Set(['archived']);
+  let nextPicked = false;
+  for (let i = 0; i < children.length; i++) {
+    const c = children[i];
+    const idx = String(i + 1).padStart(2);
+    if (c.missing) {
+      lines.push(`  ${idx}. ${red('missing')}  ${c.ref}`);
+      continue;
+    }
+    const isNext = !nextPicked && !archiveStatuses.has(c.status);
+    if (isNext) nextPicked = true;
+    const marker = isNext ? green('→') : ' ';
+    const statusTag = `[${colorStatus(c.status)}]`;
+    lines.push(`  ${marker} ${idx}. ${statusTag} ${c.path}`);
+  }
+  if (!nextPicked) {
+    lines.push('');
+    lines.push(dim('  All children archived. Hub is ready for archive.'));
+  }
+  return lines.join('\n') + '\n';
+}
+
+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)
+  const sub = positional[0] === 'next' ? 'next' : 'show';
+  const hubInput = sub === 'next' ? positional[1] : positional[0];
+
+  if (!hubInput) {
+    die(sub === 'next'
+      ? 'Usage: dotmd runlist next <hub-plan>'
+      : 'Usage: dotmd runlist <hub-plan>');
+  }
+
+  const hubAbs = resolveDocPath(hubInput, config);
+  if (!hubAbs) die(`Hub plan not found: ${hubInput}`);
+  const hubRepoPath = toRepoPath(hubAbs, config.repoRoot);
+
+  const children = readRunlistChildren(hubAbs, config);
+  const archiveStatuses = config.lifecycle?.archiveStatuses ?? new Set(['archived']);
+
+  if (sub === 'show') {
+    if (json) {
+      process.stdout.write(JSON.stringify({
+        hub: hubRepoPath,
+        children,
+      }, null, 2) + '\n');
+      return;
+    }
+    process.stdout.write(renderRunlist(hubRepoPath, children, { archiveStatuses }));
+    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));
+  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));
+    if (allArchived) {
+      die(`All children in runlist ${hubRepoPath} are archived. Hub is ready for \`dotmd archive ${hubRepoPath}\`.`);
+    }
+    const missing = children.filter(c => c.missing).map(c => c.ref);
+    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 status ${target.path} active   # if ready to resume\n` +
+      `  dotmd pickup ${target.path}          # to inspect`,
+    );
+  }
+
+  // Delegate to runPickup — same lease semantics, same VH append, same card
+  // render. Dynamic import to avoid circular module-load cost when the
+  // runlist command isn't used.
+  const { runPickup } = await import('./lifecycle.mjs');
+  const pickupArgs = [target.path];
+  if (argv.includes('--takeover')) pickupArgs.push('--takeover');
+  if (argv.includes('--full')) pickupArgs.push('--full');
+  if (argv.includes('--no-index')) pickupArgs.push('--no-index');
+  if (argv.includes('--show-files')) pickupArgs.push('--show-files');
+  if (json) pickupArgs.push('--json');
+  await runPickup(pickupArgs, config, opts);
+}

package/src/validate.mjs

@@ -358,6 +358,50 @@ export function checkBidirectionalReferences(docs, config) {
   return { warnings, errors: [] };
 }
 
+// Runlist back-pointer check: when a hub plan declares a `runlist:` of children,
+// each child SHOULD have `parent_plan:` pointing back at the hub. The two
+// fields encode complementary information (runlist = ordered execution intent;
+// parent_plan = reverse-link the rest of dotmd already uses for related-summary
+// rendering), so divergence almost always means the agent forgot the back-link.
+// Warning fires on the CHILD (that's the file that needs the edit). Skips
+// terminal/archive statuses on either side — runlists referencing closed work
+// are a normal history pattern.
+export function checkRunlistBackPointers(docs, config) {
+  const warnings = [];
+  const skipStatuses = new Set([
+    ...(config.lifecycle.terminalStatuses ?? []),
+    ...(config.lifecycle.skipWarningsFor ?? []),
+  ]);
+  const byPath = new Map(docs.map(d => [d.path, d]));
+
+  for (const hub of docs) {
+    if (skipStatuses.has(hub.status)) continue;
+    const runlistRefs = hub.refFields?.runlist ?? [];
+    if (runlistRefs.length === 0) continue;
+    const hubDir = path.dirname(path.join(config.repoRoot, hub.path));
+
+    for (const ref of runlistRefs) {
+      const resolved = resolveRefPath(ref, hubDir, config.repoRoot);
+      if (!resolved) continue; // unresolved refs already get their own existence error
+      const childPath = toRepoPath(resolved, config.repoRoot);
+      const child = byPath.get(childPath);
+      if (!child) continue;
+      if (skipStatuses.has(child.status)) continue;
+      const childParents = (child.refFields?.parent_plan ?? []).map(p => {
+        const abs = resolveRefPath(p, path.dirname(path.join(config.repoRoot, child.path)), config.repoRoot);
+        return abs ? toRepoPath(abs, config.repoRoot) : p;
+      });
+      if (childParents.includes(hub.path)) continue;
+      warnings.push({
+        path: child.path,
+        level: 'warning',
+        message: `appears in runlist of \`${hub.path}\` but \`parent_plan:\` does not point back at it. Add \`parent_plan: ${hub.path}\` so reverse-link tooling (pickup-card Related:, graph) stays consistent.`,
+      });
+    }
+  }
+  return warnings;
+}
+
 export function checkGitStaleness(docs, config) {
   const warnings = [];
   const gitDates = getGitLastModifiedBatch(config.repoRoot);