dotmd-cli 0.65.0 → 0.66.0

package/bin/dotmd.mjs

@@ -1219,12 +1219,19 @@ 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:

package/package.json

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

@@ -8,6 +8,7 @@ import { renderIndexFile, writeIndex } from './index-file.mjs';
 import { renderCheck, renderManualFixes } from './render.mjs';
 import { bold, dim, green, yellow } from './color.mjs';
 import { checkClaudeCommands, removeGeneratedSlashCommands } from './claude-commands.mjs';
+import { checkSkillDrift } from './skill-drift.mjs';
 import { runMigrateTemplate } from './migrate-template.mjs';
 import { runMigratePrompts } from './migrate-prompts.mjs';
 import { runFrontmatterFix } from './frontmatter-fix.mjs';
@@ -191,6 +192,7 @@ function runDoctorProject(config, { json = false } = {}) {
   const claudeCommandWarnings = checkClaudeCommands(config.repoRoot);
   const deprecatedCommandMentions = findDeprecatedCommandMentions(config);
   const { docsWithoutFrontmatter, planStatusGaps } = findWorkflowDrift(config);
+  const skillDriftWarnings = checkSkillDrift(config);
   const result = {
     cliVersion: cliPackage?.version ?? null,
     packageDependency: depVersion,
@@ -198,6 +200,7 @@ function runDoctorProject(config, { json = false } = {}) {
     deprecatedCommandMentions,
     docsWithoutFrontmatter,
     planStatusGaps,
+    skillDriftWarnings,
   };
 
   if (json) {
@@ -226,6 +229,11 @@ function runDoctorProject(config, { json = false } = {}) {
   } else {
     process.stdout.write('- plan status vocab: ok\n');
   }
+  if (skillDriftWarnings.length) {
+    process.stdout.write(yellow(`- canonical workflow block: drifted — CLAUDE.md and the plugin SKILL.md teach different workflows. Reconcile the block between the \`dotmd:canonical-workflow\` markers in both files.`) + '\n');
+  } else {
+    process.stdout.write('- canonical workflow block: in sync\n');
+  }
   return result;
 }
 

package/src/index.mjs

@@ -7,6 +7,7 @@ import { validateDoc, validatePlanShape, validateDocShape, checkBidirectionalRef
 import { checkIndex } from './index-file.mjs';
 import { checkClaudeCommands } from './claude-commands.mjs';
 import { checkGlossaryConfig } from './glossary-check.mjs';
+import { checkSkillDrift } from './skill-drift.mjs';
 
 // `fast: true` skips every pass that produces warnings/errors — the rendered
 // index file consumes only status/title/snapshot/etc., not the validation
@@ -135,6 +136,9 @@ export function buildIndex(config, opts = {}) {
 
     const glossaryWarnings = checkGlossaryConfig(config);
     warnings.push(...glossaryWarnings);
+
+    const skillDriftWarnings = checkSkillDrift(config);
+    warnings.push(...skillDriftWarnings);
   }
 
   return {

package/src/query.mjs

@@ -768,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);

package/src/runlist.mjs

@@ -20,6 +20,20 @@ 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
@@ -61,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,
     });
@@ -271,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;
@@ -330,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)}]`;
@@ -338,7 +365,12 @@ 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';
 }
@@ -817,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}\`.`);
     }
@@ -829,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.

package/src/skill-drift.mjs

@@ -0,0 +1,85 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+// dotmd is a drift- and staleness-catcher that didn't, until now, catch drift
+// in its OWN plugin surface. Two canonical workflow-doc surfaces are kept in
+// lockstep by hand: the repo's CLAUDE.md (its own instructions) and the plugin
+// SKILL.md (what every OTHER repo's session learns the workflow from). CLAUDE.md
+// literally says "keep it in sync with the guidance below" — this guard makes
+// that lockstep mechanical instead of manual.
+//
+// The comparison unit is a marked block (not a fuzzy phrase heuristic):
+// deterministic, robust, and zero false positives. Each surface wraps the
+// irreducible workflow contract between the markers below; the guard extracts
+// both and compares them whitespace-tolerantly. Editing the contract in one
+// surface and forgetting the other is exactly what this catches.
+
+export const CANONICAL_MARKERS = {
+  start: '<!-- dotmd:canonical-workflow:start -->',
+  end: '<!-- dotmd:canonical-workflow:end -->',
+};
+
+const CLAUDE_MD = 'CLAUDE.md';
+const SKILL_MD = path.join('plugins', 'dotmd', 'skills', 'dotmd', 'SKILL.md');
+
+// Pull the inner text between the canonical markers. Returns null when the
+// markers are absent or malformed — callers treat null as "this surface doesn't
+// participate in the lockstep block", which is what keeps a user repo that has
+// its own CLAUDE.md (but never adopted the block) from ever tripping the guard.
+export function extractCanonicalBlock(text) {
+  if (typeof text !== 'string') return null;
+  const startIdx = text.indexOf(CANONICAL_MARKERS.start);
+  if (startIdx === -1) return null;
+  const afterStart = startIdx + CANONICAL_MARKERS.start.length;
+  const endIdx = text.indexOf(CANONICAL_MARKERS.end, afterStart);
+  if (endIdx === -1 || endIdx < afterStart) return null;
+  return text.slice(afterStart, endIdx);
+}
+
+// Whitespace-tolerant so a CRLF vs LF or a stray trailing space between the two
+// files isn't reported as drift — only meaningful content divergence is.
+function normalizeBlock(block) {
+  return block
+    .replace(/\r\n?/g, '\n')
+    .split('\n')
+    .map(line => line.replace(/\s+$/, ''))
+    .join('\n')
+    .trim();
+}
+
+function readIfPresent(filePath) {
+  try {
+    if (!existsSync(filePath)) return null;
+    return readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+// Guard: the canonical workflow block must stay identical across CLAUDE.md and
+// the plugin SKILL.md. Returns [] unless BOTH files exist AND BOTH carry the
+// block — so it only fires in a repo that has adopted the lockstep convention
+// (i.e. the dotmd repo itself), never in a user repo that merely has its own
+// CLAUDE.md. That strict gate is the price of zero false positives; the
+// trade-off is that deleting the markers from one surface silently disables the
+// guard rather than warning (a deliberate, visible act, unlike a content edit).
+export function checkSkillDrift(config) {
+  const repoRoot = config?.repoRoot;
+  if (!repoRoot) return [];
+
+  const claudeText = readIfPresent(path.join(repoRoot, CLAUDE_MD));
+  const skillText = readIfPresent(path.join(repoRoot, SKILL_MD));
+  if (claudeText === null || skillText === null) return [];
+
+  const claudeBlock = extractCanonicalBlock(claudeText);
+  const skillBlock = extractCanonicalBlock(skillText);
+  if (claudeBlock === null || skillBlock === null) return [];
+
+  if (normalizeBlock(claudeBlock) === normalizeBlock(skillBlock)) return [];
+
+  return [{
+    path: SKILL_MD,
+    level: 'warning',
+    message: `canonical workflow block drifted from \`${CLAUDE_MD}\`. The block between \`${CANONICAL_MARKERS.start}\` and \`${CANONICAL_MARKERS.end}\` must stay identical in both files — reconcile them so the plugin skill and the repo instructions teach the same workflow.`,
+  }];
+}