dotmd-cli 0.74.5 → 0.74.6

package/package.json

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

package/src/baton.mjs

@@ -1,4 +1,4 @@
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { asString, toRepoPath, die, warn } from './util.mjs';
@@ -206,6 +206,26 @@ export async function runBaton(argv, config, opts = {}) {
   }
   if (!createdSlug) die(`Could not find a free prompt slug for ${slugBase} (tried ${slugBase}-2 … ${slugBase}-9).`);
 
+  // A release status can FILE the plan into a bucket (`lifecycle.filedStatuses`,
+  // e.g. paused → docs/plans/held/). The prompt is created inside the same
+  // transaction as that move, so its `plan:` link necessarily holds the
+  // pre-move path and is stale the instant it lands. The move's own reference
+  // rewrite does not cover it: `plan` is deliberately not a `referenceFields`
+  // entry, so nothing validates or repoints it. Retarget it here.
+  if (!dryRun && promptRepoPath && archiveResult?.newRepoPath && archiveResult.newRepoPath !== repoPath) {
+    const promptPath = path.join(config.repoRoot, promptRepoPath);
+    try {
+      const { frontmatter, body } = extractFrontmatter(readFileSync(promptPath, 'utf8'));
+      // Rewritten in place rather than through replaceFrontmatterField, which
+      // always emits a folded block scalar — right for prose fields, wrong for
+      // a path every other prompt carries on one line. Baton wrote this line
+      // itself moments ago, so the single-line form is guaranteed.
+      const rewritten = frontmatter.replace(/^plan:[ \t]*\S.*$/m, `plan: ${archiveResult.newRepoPath}`);
+      if (rewritten !== frontmatter) writeFileSync(promptPath, `---\n${rewritten}\n---\n${body}`, 'utf8');
+    }
+    catch (err) { warn(`Saved the prompt, but could not repoint its plan link to ${archiveResult.newRepoPath}: ${err.message}`); }
+  }
+
   const normalizeRepoPath = candidate => {
     if (!candidate) return null;
     return path.isAbsolute(candidate) ? toRepoPath(candidate, config.repoRoot) : candidate;

package/src/glossary.mjs

@@ -136,7 +136,7 @@ function renderEntry(entry, index, allEntries) {
   if (relatedDocs.length > 0) {
     lines.push('');
 
-    // Module entry point (the main module doc, e.g. situ.md)
+    // Module entry point (the main module doc, e.g. ledger.md)
     const entryPoint = relatedDocs.find(d =>
       d.root?.includes('modules') && path.basename(d.path, '.md') === entry.term.toLowerCase()
     );

package/src/prompts.mjs

@@ -6,7 +6,7 @@ import { buildIndex, resolveDocArg } from './index.mjs';
 import { runQuery } from './query.mjs';
 import { completePlanClaim, regenIndex, renderLifecycleMutation, runArchive, runStatus } from './lifecycle.mjs';
 import { runNew } from './new.mjs';
-import { green, dim } from './color.mjs';
+import { green, dim, yellow } from './color.mjs';
 import { authorizeManagedSource } from './managed-path.mjs';
 import {
   authoritativeSessionId,
@@ -259,11 +259,17 @@ export async function consumePrompt(filePath, config, opts) {
 
   const planRef = asString(parsed.plan);
   let linkedClaim = null;
-  if (planRef) linkedClaim = prepareLinkedPromptClaim(planRef, config, path.dirname(filePath));
+  let claimSkipReason = null;
+  if (planRef) {
+    const outcome = prepareLinkedPromptClaim(planRef, config, path.dirname(filePath));
+    if (outcome?.skipped) claimSkipReason = outcome.reason;
+    else linkedClaim = outcome;
+  }
 
   if (dryRun) {
     const prefix = dim('[dry-run]');
     process.stderr.write(`${prefix} Would emit body and archive: ${repoPath} (${status ?? 'unknown'} → archived)\n`);
+    if (claimSkipReason) process.stderr.write(`${prefix} Would NOT claim the linked plan: ${claimSkipReason}\n`);
     const bytes = Buffer.byteLength(body, 'utf8');
     const lines = body.split('\n').length;
     process.stderr.write(`${prefix} body preview (${bytes}B, ${lines} lines):\n`);
@@ -315,6 +321,7 @@ export async function consumePrompt(filePath, config, opts) {
     }
     process.stderr.write(`${green('→ Claimed')}: ${linkedClaim.repoPath} (in-session)\n`);
   }
+  if (claimSkipReason) process.stderr.write(`${yellow('→ Not claimed')}: ${claimSkipReason}\n`);
   process.stderr.write(`${green('✓ Consumed')}: ${consumedPath}\n`);
   const ownershipRecordPath = linkedClaim?.prepared?.recordPath ?? (linkedClaim ? readPlanOwnership(linkedClaim.repoPath, config)?.recordPath : null);
   const ownershipPath = ownershipRecordPath ? toRepoPath(ownershipRecordPath, config.repoRoot) : null;
@@ -364,16 +371,54 @@ export async function writeConsumedBody(body, archivedPath, write = null, linked
 // with `resolveDocPath` alone read only the repo-root form, so a doc-relative
 // link — the form nothing validates, since `plan` is not a `referenceFields`
 // entry — died as "missing" while pointing at a file that was plainly there.
+// Why a linked plan could not be claimed, phrased so the reader knows what to
+// do next. Each of these used to abort consumption entirely (see the skip
+// contract on prepareLinkedPromptClaim).
+// `startable` comes from the repo's own lifecycle config rather than the
+// built-in default: a repo that configures its own startable statuses would
+// otherwise be told to run `dotmd set active`, which its own validation
+// rejects.
+function explainUnclaimablePlan(disposition, repoPath, status, startable) {
+  switch (disposition.kind) {
+    case 'parked':
+      return `${repoPath} is ${status} — \`dotmd set ${startable} ${repoPath}\` to unpark it, then \`dotmd use ${repoPath}\``;
+    case 'busy':
+      return `${repoPath} is claimed by another session (${disposition.owner})`;
+    case 'terminal':
+    case 'physical-archive':
+      return `${repoPath} is already closed (${status})`;
+    case 'wrong-type':
+      return `${repoPath} is not a plan`;
+    case 'unconfigured-status':
+      return `${repoPath} has a status this repo does not configure (${status ?? 'none'})`;
+    case 'ownership-corrupt':
+      return `${repoPath} has an unreadable ownership record — \`dotmd doctor --claims\``;
+    default:
+      return `${repoPath} cannot be claimed (${disposition.kind})`;
+  }
+}
+
+// Returns a claim, or `{ skipped, reason }` when the linked plan cannot be
+// claimed. It never refuses the consumption itself.
+//
+// It used to `die` on all three of these paths, which deadlocked the handoff
+// loop the feature exists to close: `dotmd baton` stamps this link and parks
+// the plan in the same breath, and five of the seven statuses it parks with are
+// not startable — so baton routinely produced a prompt that `dotmd use` would
+// refuse forever, while the SessionStart hud kept telling every new session to
+// run exactly that command. The body is the whole point of a saved prompt, and
+// no reason to skip the claim is a reason to withhold it.
 function prepareLinkedPromptClaim(planRef, config, promptDir) {
+  const skip = reason => ({ skipped: true, reason });
   let planPath = resolveRefPath(planRef, promptDir, config.repoRoot)
     ?? resolveDocPath(planRef, config)
     ?? resolveDocArg(planRef, config, { dieOnMiss: false });
-  if (!planPath || !existsSync(planPath)) die(`Linked plan is missing; prompt was not consumed: ${planRef}`);
+  if (!planPath || !existsSync(planPath)) return skip(`linked plan is missing (moved or renamed): ${planRef}`);
   planPath = authorizeManagedSource(planPath, config, { kind: 'Prompt linked plan source' }).path;
   const raw = readFileSync(planPath, 'utf8');
   let parsed;
   try { parsed = parseSimpleFrontmatter(extractFrontmatter(raw).frontmatter); }
-  catch { die(`Linked plan is malformed; prompt was not consumed: ${planRef}`); }
+  catch { return skip(`linked plan has malformed frontmatter: ${toRepoPath(planPath, config.repoRoot)}`); }
   const repoPath = toRepoPath(planPath, config.repoRoot);
   const sessionId = authoritativeSessionId();
   const ownership = readPlanOwnership(repoPath, config);
@@ -391,7 +436,10 @@ function prepareLinkedPromptClaim(planRef, config, promptDir) {
     sessionId,
     malformed: false,
   });
-  if (!disposition.pickupable) die(`Linked plan cannot be claimed (${disposition.kind}); prompt was not consumed: ${repoPath}`);
+  if (!disposition.pickupable) {
+    const startable = [...(config.lifecycle.startableStatuses ?? [])][0] ?? 'active';
+    return skip(explainUnclaimablePlan(disposition, repoPath, oldStatus, startable));
+  }
   if (disposition.kind === 'resume') return { planPath, repoPath, prepared: null, planChanged: false, disposition: disposition.kind };
   const now = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
   const rendered = disposition.kind === 'start'

package/src/section.mjs

@@ -53,23 +53,121 @@ export function findSection(sections, name) {
 
 // Status marker detection for phase headings. Returns one of:
 //   'shipped' | 'skipped' | 'in-progress' | 'blocked' | 'todo' | null
-const MARKER_PATTERNS = [
-  { kind: 'shipped',     re: /(✅|☑|✔|\bshipped\b|\bdone\b|\bcomplete\b)/i },
-  { kind: 'skipped',     re: /(⏭|\bskip(?:ped)?\b)/i },
-  { kind: 'in-progress', re: /(🟡|🔄|\bin[-_ ]?(?:progress|flight)\b|\bwip\b)/i },
-  { kind: 'blocked',     re: /(🚧|🔴|\bblocked\b)/i },
-  { kind: 'todo',        re: /(⬜|⬛|◻|☐|\btodo\b|\bnot[-_ ]?started\b)/i },
+// Glyphs are checked BEFORE prose, not interleaved with it. A glyph is a
+// deliberate mark; a prose word is often about something else in the sentence:
+//
+//   ⬜ Phase 4: Retry budget rework (scoping COMPLETE)              ← the SCOPING completed
+//   Phase 2 — schema migrated ⬜ todo (column rename half DONE)     ← half a RENAME is done
+//   Phase 3 (original scope) — ⏭ superseded by the shipped Phase 3  ← a DIFFERENT phase shipped
+//
+// Interleaved, first-match-wins order called all three shipped, so
+// findActivePhase skipped a phase the author had explicitly marked unstarted.
+// Within each tier the order is still priority order, which decides a heading
+// carrying more than one mark.
+const GLYPH_PATTERNS = [
+  { kind: 'shipped',     re: /(✅|☑|✔)/ },
+  { kind: 'skipped',     re: /(⏭)/ },
+  { kind: 'in-progress', re: /(🟡|🔄)/ },
+  { kind: 'blocked',     re: /(🚧|🔴)/ },
+  { kind: 'todo',        re: /(⬜|⬛|◻|☐)/ },
+];
+
+const PROSE_PATTERNS = [
+  // A qualifier inverts the word it modifies, and these run BEFORE the plain
+  // `shipped` pattern so the qualifier wins. Otherwise `mostly done` and
+  // `(partially complete)` both read as shipped, and findActivePhase skips a
+  // phase whose own checklist still has open boxes.
+  { kind: 'todo',        re: /\b(?:not|never)[\s-]+(?:complete(?:d)?|done|shipped|started)\b/i },
+  { kind: 'in-progress', re: /\b(?:partially|partly|mostly|nearly|almost|half)[\s-]*(?:complete(?:d)?|done|shipped)\b/i },
+  { kind: 'shipped',     re: /(\bshipped\b|\bdone\b|\bcomplete\b)/i },
+  { kind: 'skipped',     re: /(\bskip(?:ped)?\b)/i },
+  { kind: 'in-progress', re: /(\bin[-_ ]?(?:progress|flight)\b|\bwip\b)/i },
+  { kind: 'blocked',     re: /(\bblocked\b)/i },
+  { kind: 'todo',        re: /(\btodo\b|\bnot[-_ ]?started\b)/i },
 ];
 
 export function detectMarker(heading) {
-  for (const { kind, re } of MARKER_PATTERNS) {
+  for (const { kind, re } of GLYPH_PATTERNS) {
+    if (re.test(heading)) return kind;
+  }
+  for (const { kind, re } of PROSE_PATTERNS) {
     if (re.test(heading)) return kind;
   }
   return null;
 }
 
+// Leading decoration a phase heading may carry before the word "Phase":
+// emphasis punctuation and any run of status markers. `detectMarker` already
+// reads a marker wherever it sits, but this test was anchored at `^phase`, so
+// a plan that writes `### ⬜ Phase 2 — …` had NO phases at all — not a
+// miscount, an empty phase set, which drops the pickup card to its
+// "no ## Phases section" fallback. 93 headings in one 482-plan corpus.
+// Several of these glyphs are commonly typed in emoji-presentation form
+// (the base codepoint plus a variation selector): the skip mark, the ballot
+// box, the check mark. `detectMarker` is a substring test so it never
+// noticed. This is a character CLASS, and the selector sits between the glyph
+// and the space, is not \s, and ends the run — so a heading led by the
+// emoji-presentation form was not a phase heading at all, while the bare
+// codepoint was. Reported by the owner, 2026-08-16.
+const PHASE_DECORATION = String.raw`[\s>*_~\`#-]*(?:[✅🚧⬜🟡⏭☑✔◻☐⬛🔴🔄][︎️]?\s*)*`;
+const PHASE_LEAD = new RegExp(`^${PHASE_DECORATION}phase\\b`, 'i');
+
+// "Phase 3 outcome" is commentary ABOUT a phase, not a phase. Counting it
+// inflates the phase set, and because `findActivePhase` ranks blocked above
+// todo, a heading like "Phase 3 smoke findings — BLOCKER" gets picked as the
+// plan's active phase over a real unstarted one. 43 in the same corpus.
+//
+// The noun list is deliberately tight. Wrongly excluding a real phase hides
+// work; wrongly including commentary only miscounts — so this errs toward
+// counting, and a word is added here only once the corpus shows it standing
+// for a retrospective rather than a phase.
+const PHASE_COMMENTARY = new RegExp(
+  `^${PHASE_DECORATION}phase\\s+\\S+\\s+(outcome|progress|notes?|findings?|smoke|retro|review|recap|summary)\\b`,
+  'i',
+);
+
 export function isPhaseHeading(section) {
-  return section.level === 3 && /^phase\b/i.test(section.heading);
+  if (section.level !== 3) return false;
+  return PHASE_LEAD.test(section.heading) && !PHASE_COMMENTARY.test(section.heading);
+}
+
+// A phase's OWN checklist — the boxes directly under its heading, stopping at
+// the next heading of any level so a sub-section's checklist is never counted
+// as the parent phase's evidence.
+export function phaseTally(section) {
+  let checked = 0, unchecked = 0;
+  for (const line of String(section?.body ?? '').split('\n')) {
+    if (/^#{1,6}\s/.test(line)) break;
+    if (/^\s*[-*]\s*\[x\]/i.test(line)) checked++;
+    else if (/^\s*[-*]\s*\[ \]/.test(line)) unchecked++;
+  }
+  return { checked, unchecked, total: checked + unchecked };
+}
+
+/**
+ * A phase whose declared marker its own checklist contradicts.
+ *
+ * Only two disagreements are reported, because only two are unambiguous:
+ *
+ *   shipped + an open box  — the plan's own checklist says otherwise
+ *   todo    + every box checked — the work is done, the marker says unstarted
+ *
+ * `blocked` and `skipped` are judgements a tally cannot refute (blocked at 0/7
+ * is perfectly coherent), and `in-progress` with everything checked usually
+ * means work the checklist does not enumerate. Including those three took the
+ * count from 13 to 19 on a 482-plan corpus, every extra one arguable — so they
+ * are excluded rather than reported and explained away.
+ *
+ * Returns null when there is no conflict, no marker, or no checklist.
+ */
+export function phaseMarkerConflict(section) {
+  const declared = detectMarker(section?.heading ?? '');
+  if (declared !== 'shipped' && declared !== 'todo') return null;
+  const tally = phaseTally(section);
+  if (tally.total === 0) return null;
+  if (declared === 'shipped' && tally.unchecked > 0) return { declared, implied: 'in progress', ...tally };
+  if (declared === 'todo' && tally.unchecked === 0) return { declared, implied: 'shipped', ...tally };
+  return null;
 }
 
 // Summarize a phase set: { 'shipped': 2, 'in-progress': 1, 'todo': 2 }

package/src/validate.mjs

@@ -2,6 +2,7 @@ import path from 'node:path';
 import { asString, resolveRefPath, suggestCandidates } from './util.mjs';
 import { getGitLastModified, getGitLastModifiedBatch, getGitLastSubstantiveModifiedBatch } from './git.mjs';
 import { toRepoPath } from './util.mjs';
+import { detectMarker, isPhaseHeading, phaseMarkerConflict, walkSections } from './section.mjs';
 
 const NOW = new Date();
 
@@ -635,26 +636,40 @@ export function validatePlanShape(doc, body, frontmatter, config) {
     }
   }
 
-  // 5. Phases section exists but no phase H3 has a status marker
-  const phasesIdx = body.search(/^## Phases\s*$/m);
-  if (phasesIdx >= 0) {
-    // Find the section's body (until next H2 or EOF)
-    const after = body.slice(phasesIdx);
-    const nextH2 = after.slice(8).search(/^## /m);
-    const phasesBody = nextH2 >= 0 ? after.slice(8, 8 + nextH2) : after.slice(8);
-    const phaseHeadings = [...phasesBody.matchAll(/^###\s+(.+?)\s*$/gm)].map(m => m[1]);
-    if (phaseHeadings.length > 0) {
-      const markerRe = /(✅|⏭|🟡|⬜|🚧|☑|✔|◻|☐|⬛|\bshipped\b|\bskip(?:ped)?\b|\bin[-_ ]?(?:progress|flight)\b|\bblocked\b|\btodo\b|\bnot[-_ ]?started\b|\bwip\b|\bdone\b|\bcomplete\b)/i;
-      const unmarked = phaseHeadings.filter(h => !markerRe.test(h));
-      if (unmarked.length > 0) {
-        doc.warnings.push({
-          path: doc.path,
-          level: 'warning',
-          message: `${unmarked.length} of ${phaseHeadings.length} phase heading(s) lack a status marker. Use one of ✅ shipped, ⏭ skipped, 🟡 in-progress, ⬜ todo, 🚧 blocked.`,
-        });
-      }
+  // 5 & 6 read phases through section.mjs rather than re-parsing them here.
+  // This check used to carry its own heading scan and its own copy of the
+  // marker vocabulary, which drifted from the real reader in both directions:
+  // it counted `### Phase 3 outcome` as a phase needing a marker, and it never
+  // learned the fixes section.mjs got. Two parsers for one concept disagreeing
+  // is the same defect class as `reference-planner` vs `resolveRefPath`.
+  const phases = walkSections(body).filter(isPhaseHeading);
+
+  // 5. Phase headings that carry no status marker at all.
+  if (phases.length > 0) {
+    const unmarked = phases.filter(p => detectMarker(p.heading) === null);
+    if (unmarked.length > 0) {
+      doc.warnings.push({
+        path: doc.path,
+        level: 'warning',
+        message: `${unmarked.length} of ${phases.length} phase heading(s) lack a status marker. Use one of ✅ shipped, ⏭ skipped, 🟡 in-progress, ⬜ todo, 🚧 blocked.`,
+      });
     }
   }
+
+  // 6. A phase whose own checklist contradicts its marker. Reported, never
+  // fixed: dotmd cannot know whether the marker or the boxes are the stale
+  // half, and guessing would either mark work done that is not, or reopen work
+  // that is. Both halves are the author's own writing — this only says they
+  // disagree.
+  for (const phase of phases) {
+    const conflict = phaseMarkerConflict(phase);
+    if (!conflict) continue;
+    doc.warnings.push({
+      path: doc.path,
+      level: 'warning',
+      message: `Phase marker contradicts its own checklist (line ${phase.lineStart}): \`${phase.heading.trim()}\` is marked ${conflict.declared}, but ${conflict.checked}/${conflict.total} boxes are checked — that reads as ${conflict.implied}. Update whichever half is stale.`,
+    });
+  }
 }
 
 // Doc-shape lint: soft warnings on convention drift. Doc-only.