dotmd-cli 0.72.1 → 0.73.0

package/bin/dotmd.mjs

@@ -205,6 +205,7 @@ Validate & Fix:
   self-check                        Project/version skew diagnostic (alias: doctor --project)
   lint [--fix]                      Check and auto-fix frontmatter issues
   fix-refs [--dry-run]              Auto-fix broken reference paths + body links
+  sync-status [<hub>...] [--adopt]  Rewrite hub table rows whose printed status drifted from the plan
 
 Lifecycle:
   use <file>                        Open a plan (mark in-session + print it) or consume a prompt
@@ -772,6 +773,29 @@ Modes:
 Sub-modes (--statuses, --migrate-*, --frontmatter-fix, --project) keep their
 existing contracts: they write by default and honor --dry-run.`,
 
+  'sync-status': `dotmd sync-status — rewrite hub rows whose printed status drifted
+
+A runlist / coordination / roadmap hub rows its children in a table and prints
+each child's status by hand. This sweeps every hub, compares each row's status
+word against the plan it links to, and rewrites the ones that drifted. Case is
+preserved (\`Active\` stays capitalized), and nothing else in the cell is touched.
+
+  dotmd sync-status                  every hub in the repo (the normal case)
+  dotmd sync-status <hub>...         narrow to named hubs
+  dotmd sync-status --adopt          also wrap managed status words in <!--s-->…<!--/s-->
+  dotmd sync-status --dry-run --json
+
+The status word is found positionally — comments stripped, cell's leading token,
+matched against the vocabulary the CHILD's type declares — so no marker is
+needed. A marker pins the span for the rows position can't read (a status sitting
+behind a bolded headline). \`dotmd check\` warns on positional drift and ERRORS on
+marked drift: the marker is the author saying dotmd owns that word.
+
+Rows under a status column with no readable status word are reported by
+\`dotmd check\` and left alone here; rows in a table with no status column at all
+are not findings. Not to be confused with \`dotmd set <status>\`, which changes a
+document's OWN status — this only rewrites what a hub prints about others.`,
+
   'fix-refs': `dotmd fix-refs — auto-fix broken reference paths
 
 Scans all docs for reference fields that point to non-existent files,
@@ -1701,6 +1725,7 @@ async function main() {
   if (command === 'rename') { const { runRename } = await import('../src/rename.mjs'); await runRename(restArgs, config, { dryRun }); return; }
   if (command === 'migrate') { const { runMigrate } = await import('../src/migrate.mjs'); runMigrate(restArgs, config, { dryRun }); return; }
   if (command === 'fix-refs') { const { runFixRefs } = await import('../src/fix-refs.mjs'); runFixRefs(restArgs, config, { dryRun }); return; }
+  if (command === 'sync-status') { const { runSyncStatus } = await import('../src/sync-status.mjs'); await runSyncStatus(restArgs, config, { dryRun }); return; }
   if (command === 'self-check') {
     const { runDoctor } = await import('../src/doctor.mjs');
     runDoctor(['--project', ...restArgs], config, { dryRun });
@@ -1811,8 +1836,12 @@ async function main() {
       // Auto-fix: broken refs, then lint, then rebuild index
       const { fixBrokenRefs } = await import('../src/fix-refs.mjs');
       const { runLint } = await import('../src/lint.mjs');
+      const { syncHubStatuses } = await import('../src/sync-status.mjs');
       fixBrokenRefs(config, { dryRun, quiet: false });
       runLint(['--fix'], config, { dryRun });
+      // Rewrites drifted status TOKENS only. Adding markers is a content edit to
+      // prose the user wrote, so it stays opt-in behind `sync-status --adopt`.
+      syncHubStatuses(config, { docs: buildIndex(config).docs, dryRun, quiet: false });
       if (config.indexPath) {
         if (!dryRun) {
           const { writeRenderedIndex } = await import('../src/index-file.mjs');

package/package.json

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

package/src/commands.mjs

@@ -133,6 +133,7 @@ const definitions = [
   command('rename', mutates('managed source, same-root destination, and rewrite sweep'), 'mutate', [form('<old> [new]', { args: positionals(1, 2), options: [flag('--show-files')] })]),
   command('migrate', mutates('managed source sweep'), 'mutate', [form('<field> <old> <new> [files...]', { args: positionals(3, Infinity), options: [flag('--show-files')] })]),
   command('fix-refs', mutates('managed source sweep'), 'mutate', [form('', { options: [flag('--show-files')] })]),
+  command('sync-status', mutates('managed source sweep'), 'mutate', [form('[hubs...]', { args: positionals(0, Infinity), options: [flag('--adopt'), flag('--json')] })]),
   command('doctor', mutates('managed sweeps, repo index, and maintenance config paths by mode'), 'mutate', [form('[path]', { args: positionals(0, 1), options: [flag('--apply', '--yes'), flag('--statuses'), optionalValue('--migrate-template'), flag('--migrate-prompts'), flag('--frontmatter-fix'), flag('--project'), flag('--transactions'), flag('--json'), flag('--include-archived')] })]),
   command('statuses', mutates('project config path; document scan is read-only'), 'mutate', [
     form('list', { subcommands: ['list'], options: [value('--type'), flag('--json')] }),

package/src/doctor.mjs

@@ -2,6 +2,7 @@ import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { fixBrokenRefs } from './fix-refs.mjs';
 import { runLint } from './lint.mjs';
+import { syncHubStatuses } from './sync-status.mjs';
 import { runTouch } from './lifecycle.mjs';
 import { buildIndex, collectDocFiles } from './index.mjs';
 import { writeRenderedIndex } from './index-file.mjs';
@@ -157,13 +158,22 @@ export function runDoctor(argv, config, opts = {}) {
   process.stdout.write('\n' + bold('3. Fixing long frontmatter...') + '\n');
   runFrontmatterFix(config, { dryRun });
 
-  // Step 4: Sync dates from git
-  process.stdout.write('\n' + bold('4. Syncing dates from git...') + '\n');
+  // Step 4: Rewrite hub rows whose printed status drifted from the plan they
+  // link to. Tokens only — adding markers is a content edit to prose the user
+  // wrote, so it stays opt-in behind `dotmd sync-status --adopt`.
+  process.stdout.write('\n' + bold('4. Syncing hub status rows...') + '\n');
+  const hubSync = syncHubStatuses(config, { docs: buildIndex(config).docs, dryRun });
+  if (hubSync.fixed === 0 && hubSync.adopted === 0 && hubSync.unreadable === 0) {
+    process.stdout.write('Hub status rows are in sync.\n');
+  }
+
+  // Step 5: Sync dates from git
+  process.stdout.write('\n' + bold('5. Syncing dates from git...') + '\n');
   runTouch(['--git'], config, { dryRun });
 
-  // Step 5: Regenerate index. Heading always prints so numbering remains
+  // Step 6: Regenerate index. Heading always prints so numbering remains
   // contiguous even when `index.path` isn't configured.
-  process.stdout.write('\n' + bold('5. Regenerating index...') + '\n');
+  process.stdout.write('\n' + bold('6. Regenerating index...') + '\n');
   if (!config.indexPath) {
     process.stdout.write('No index path configured (skip).\n');
   } else if (dryRun) {
@@ -173,11 +183,11 @@ export function runDoctor(argv, config, opts = {}) {
     process.stdout.write('Index updated.\n');
   }
 
-  // Step 6: Clean up retired Claude Code command scaffolding. The per-repo
+  // Step 7: Clean up retired Claude Code command scaffolding. The per-repo
   // `.claude/commands/{plans,docs}.md` files are superseded by the dotmd plugin
   // skill; doctor sweeps any leftover banner-stamped (dotmd-generated) files.
   // Always print the heading so the numbering remains contiguous.
-  process.stdout.write('\n' + bold('6. Claude Code commands:') + '\n');
+  process.stdout.write('\n' + bold('7. Claude Code commands:') + '\n');
   if (dryRun) {
     const wouldRemove = removeGeneratedSlashCommands(config.repoRoot, { dryRun: true });
     if (wouldRemove.length === 0) {
@@ -198,8 +208,8 @@ export function runDoctor(argv, config, opts = {}) {
     }
   }
 
-  // Step 7: Show remaining check
-  const issueLabel = dryRun ? '7. Remaining issues in current tree (preview fixes above were not applied):' : '7. Remaining issues:';
+  // Step 8: Show remaining check
+  const issueLabel = dryRun ? '8. Remaining issues in current tree (preview fixes above were not applied):' : '8. Remaining issues:';
   process.stdout.write('\n' + bold(issueLabel) + '\n');
   const freshIndex = buildIndex(config);
   process.stdout.write(renderCheck(freshIndex, config));

package/src/hub.mjs

@@ -0,0 +1,217 @@
+// Hub primitives: what counts as a hub, and how to read a hub's body tables.
+//
+// This module is deliberately a LEAF — it imports nothing from dotmd. The hub
+// predicates used to live in `runlist.mjs`, but `runlist.mjs` imports
+// `index.mjs` (for `resolveDocArg`), and the hub-status check has to run FROM
+// `index.mjs`. Keeping the predicates here is what lets both sides share one
+// definition of "hub" instead of re-deriving it — the exact duplication the
+// hub-status-drift plan exists to avoid. `runlist.mjs` re-exports them so every
+// existing importer is unaffected.
+
+// 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;
+  // Broad "held-out navigational hub" predicate: both coordination hubs and the
+  // tier-3 roadmap (`execution_mode: roadmap`) are lifted out of the active count
+  // and into a hub section. `isRoadmapHub` is the finer split the tier-3 views
+  // use to promote a roadmap above the Runlists section; here a roadmap counts as
+  // a coordination hub so all the existing held-out plumbing covers it for free.
+  if (doc.executionMode === 'coordination' || doc.executionMode === 'roadmap') return true;
+  const base = (doc.path.split('/').pop() || '').replace(/\.md$/, '');
+  return base === 'runlist' || base.endsWith('-runlist');
+}
+
+// A *roadmap* is the tier-3 hub: a coordination hub whose children are themselves
+// hubs (runlists / coordination hubs), with progress rolled up across them. The
+// signal is explicit — `execution_mode: roadmap` — with NO slug-convention
+// fallback (unlike coordination hubs' `*-runlist`): there's no naming convention
+// for roadmaps, and `dotmd check` nudges the structural case (a coordination hub
+// that points at other hubs) toward the explicit field rather than auto-promoting.
+export function isRoadmapHub(doc) {
+  if (!doc) return false;
+  if (doc.type && doc.type !== 'plan') return false;
+  return doc.executionMode === 'roadmap';
+}
+
+// A *sprint hub* declares its ordered children in frontmatter (`runlist:`).
+export function isSprintHub(doc) {
+  return (doc?.refFields?.runlist ?? []).length > 0;
+}
+
+// Every shape of hub: a frontmatter sprint, a coordination map, or a roadmap.
+// This is the set whose body tables the hub-status guard reads.
+export function isHubDoc(doc) {
+  return isSprintHub(doc) || isCoordinationHub(doc);
+}
+
+// The row→target anchor: the first `.md` link in a table row is the plan that
+// row is ABOUT. Shared by next-pickup detection (`detectBodyRunlistRefs`) and
+// the hub-status guard, so the two can never disagree about which plan a given
+// row names.
+const ROW_LINK_RE = /\[[^\]]+\]\(([^)]+\.md(?:#[^)]+)?)\)/;
+
+export function firstRowLink(line) {
+  const match = ROW_LINK_RE.exec(line);
+  return match ? match[1] : null;
+}
+
+// ─── Reading the status word out of a hub row ──────────────────────────────
+//
+// A hub row prints its child's status by hand. Two ways to find that word:
+//
+//   position — strip HTML comments, take the cell's LEADING token, match it
+//              against the vocabulary the child's own type declares. No marker
+//              needed, so this works on tables that already exist. Measured on
+//              472 real rows: agrees with an explicitly marked span 96% of the
+//              time and picks a wrong token zero times. Every miss leaves a
+//              leading word outside the vocabulary, so it declines (and the row
+//              is reported as unreadable) rather than rewriting confidently.
+//   marker   — `<!--s-->active<!--/s-->` pins the span when position can't find
+//              it (the measured 4%: a status sitting behind a bolded headline).
+//
+// The marker is 19 characters against 62 for dotmd's block grammar
+// (`<!-- GENERATED:dotmd:start -->`). That difference only matters because this
+// one recurs hundreds of times per estate. It makes four comment grammars in
+// dotmd; the other three are block-level and correct at block level. Do NOT
+// "unify" them, and do not let the count grow again.
+export const MARKER_OPEN = '<!--s-->';
+export const MARKER_CLOSE = '<!--/s-->';
+
+const MARKED_SPAN_RE = /<!--\s*s\s*-->([\s\S]*?)<!--\s*\/s\s*-->/;
+const HTML_COMMENT_RE = /<!--[\s\S]*?-->/g;
+const FENCE_RE = /^\s{0,3}(`{3,}|~{3,})/;
+// Statuses are hyphenated single words (`in-session`, `queued-after`). The
+// optional emphasis prefix lets `**active**` read as a leading token while
+// `**Phase 1 gate** — active` still declines: the leading word there is `Phase`.
+const LEADING_TOKEN_RE = /^(\s*)(\*\*|__|\*|_|`)?([A-Za-z][A-Za-z0-9-]*)/;
+
+// Split a markdown table row into cells, keeping each cell's offsets into the
+// line so a fix can rewrite one word without touching the rest of the row.
+// Honors `\|` escapes and pipes inside inline code.
+export function splitRowCells(line) {
+  const cells = [];
+  let start = 0;
+  let inCode = false;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (ch === '\\') { i++; continue; }
+    if (ch === '`') { inCode = !inCode; continue; }
+    if (ch === '|' && !inCode) {
+      cells.push({ raw: line.slice(start, i), start, end: i });
+      start = i + 1;
+    }
+  }
+  cells.push({ raw: line.slice(start), start, end: line.length });
+  // Rows are conventionally pipe-delimited on both ends; drop the empty edge
+  // segments those produce so column indexes line up with the header's.
+  if (cells.length && cells[0].raw.trim() === '') cells.shift();
+  if (cells.length && cells[cells.length - 1].raw.trim() === '') cells.pop();
+  return cells;
+}
+
+function isDelimiterRow(cells) {
+  return cells.length > 0 && cells.every(cell => /^\s*:?-+:?\s*$/.test(cell.raw));
+}
+
+// A table declares a status column when a header cell IS "status"/"state".
+// Deliberately exact (after stripping emphasis): a header that only mentions
+// status in passing is not a promise that the column holds one.
+function isStatusHeader(raw) {
+  const normalized = raw.replace(/[*_`]/g, '').trim().toLowerCase();
+  return normalized === 'status' || normalized === 'state';
+}
+
+export function findMarkedSpan(line) {
+  const match = MARKED_SPAN_RE.exec(line);
+  if (!match) return null;
+  const innerStart = match.index + match[0].indexOf('-->') + 3;
+  const inner = match[1];
+  const lead = inner.length - inner.trimStart().length;
+  const text = inner.trim();
+  if (!text) return null;
+  return { start: innerStart + lead, end: innerStart + lead + text.length, text, marked: true };
+}
+
+// Positional read of a cell: leading token, comments stripped, vocabulary-gated.
+// `isKnownStatus` is the caller's vocabulary test — it depends on the CHILD's
+// type, which only the caller can resolve, so it is injected rather than
+// guessed here. Returns line-absolute offsets, like `findMarkedSpan`.
+export function readPositionalToken(cell, isKnownStatus) {
+  if (!cell) return null;
+  // Blank out comments instead of deleting them so offsets stay line-absolute.
+  const masked = cell.raw.replace(HTML_COMMENT_RE, comment => ' '.repeat(comment.length));
+  const match = LEADING_TOKEN_RE.exec(masked);
+  if (!match) return null;
+  const word = match[3];
+  if (!isKnownStatus(word)) return null;
+  const start = cell.start + match[1].length + (match[2]?.length ?? 0);
+  return { start, end: start + word.length, text: word, marked: false };
+}
+
+// Walk a hub body's markdown tables and return one entry per row that names a
+// child (`.md` link). Pure: no vocabulary, no resolution, no IO — the caller
+// resolves the target and then reads the status word, because the vocabulary
+// depends on the child's own type.
+//
+// Returns [{ lineIndex, ref, hasStatusColumn, statusCell, marked }] where
+// `lineIndex` is 0-based into `body.split('\n')` and `statusCell`/`marked`
+// carry line-absolute offsets.
+export function scanHubStatusRows(body) {
+  if (!body) return [];
+  const lines = body.split('\n');
+  const rows = [];
+  let fence = null;
+  let table = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const fenceMatch = FENCE_RE.exec(line);
+    if (fence) {
+      if (fenceMatch && fenceMatch[1][0] === fence[0] && fenceMatch[1].length >= fence.length) fence = null;
+      continue;
+    }
+    // Fenced examples routinely contain sample hub rows (this plan's own body
+    // does). Reading them would report drift against a fictional child.
+    if (fenceMatch) { fence = fenceMatch[1]; table = null; continue; }
+
+    if (!line.trim().startsWith('|')) { table = null; continue; }
+    const cells = splitRowCells(line);
+
+    if (!table) {
+      // A pipe line is a table header only when a delimiter row follows it.
+      const next = i + 1 < lines.length ? lines[i + 1] : '';
+      if (next.trim().startsWith('|') && isDelimiterRow(splitRowCells(next))) {
+        table = { statusColumn: cells.findIndex(cell => isStatusHeader(cell.raw)) };
+      }
+      continue;
+    }
+    if (isDelimiterRow(cells)) continue;
+
+    const ref = firstRowLink(line);
+    if (!ref) continue;
+    rows.push({
+      lineIndex: i,
+      ref,
+      hasStatusColumn: table.statusColumn >= 0,
+      statusCell: table.statusColumn >= 0 ? cells[table.statusColumn] ?? null : null,
+      marked: findMarkedSpan(line),
+    });
+  }
+  return rows;
+}
+
+// Write `replacement` in the case style the author used, so a fix never
+// restyles a table (`Active` stays capitalized, `ACTIVE` stays shouted).
+export function applyStatusCase(sample, replacement) {
+  if (/[A-Z]/.test(sample) && sample === sample.toUpperCase()) return replacement.toUpperCase();
+  if (/^[A-Z]/.test(sample)) return replacement.charAt(0).toUpperCase() + replacement.slice(1);
+  return replacement;
+}

package/src/index.mjs

@@ -9,6 +9,7 @@ import { checkIndex } from './index-file.mjs';
 import { checkClaudeCommands } from './claude-commands.mjs';
 import { checkGlossaryConfig } from './glossary-check.mjs';
 import { checkSkillDrift } from './skill-drift.mjs';
+import { checkHubStatusDrift } from './sync-status.mjs';
 
 // `fast: true` skips every pass that produces warnings/errors — the rendered
 // index file consumes only status/title/snapshot/etc., not the validation
@@ -117,6 +118,20 @@ export function buildIndex(config, opts = {}) {
     errors.push(...indexCheck.errors);
   }
 
+  // Hub status drift produces ERRORS (a drifted marked span), so it runs in
+  // errorsOnly mode too — that's what keeps `dotmd hud`'s error count equal to
+  // `dotmd check`'s. Its warnings still obey the warning-only gate.
+  if (!fast) {
+    const hubStatus = checkHubStatusDrift(transformedDocs, config);
+    errors.push(...hubStatus.errors);
+    if (!skipWarningOnlyChecks) warnings.push(...hubStatus.warnings);
+    for (const entry of [...hubStatus.errors, ...(skipWarningOnlyChecks ? [] : hubStatus.warnings)]) {
+      const hub = transformedDocs.find(d => d.path === entry.path);
+      if (!hub) continue;
+      (entry.level === 'error' ? hub.errors : hub.warnings).push(entry);
+    }
+  }
+
   if (!skipWarningOnlyChecks) {
     const refCheck = checkBidirectionalReferences(transformedDocs, config);
     warnings.push(...refCheck.warnings);

package/src/render.mjs

@@ -416,6 +416,16 @@ export function classifyIssueAction(issue) {
   const message = issue?.message ?? '';
   const file = issue?.path ?? '<file>';
 
+  // Hub status rows carry a `meta.kind`, so classify them by that rather than by
+  // re-matching their prose. Drift is mechanically fixable; an unreadable cell
+  // is not — nothing can guess which word in it was meant to be the status.
+  if (issue?.meta?.kind === 'hub-status-drift') {
+    return { action: 'dotmd sync-status', fixable: true, label: 'hub status drift' };
+  }
+  if (issue?.meta?.kind === 'hub-status-unreadable') {
+    return { action: `edit ${file}: lead the status cell with the status word, or wrap it in <!--s-->…<!--/s-->`, fixable: false, label: 'hub status rows' };
+  }
+
   if (/Missing frontmatter `status`/.test(message)) {
     return { action: `dotmd bulk-tag ${file}`, fixable: false, label: 'missing status' };
   }

package/src/runlist.mjs

@@ -14,6 +14,7 @@ import {
   toSlug,
   warn,
 } from './util.mjs';
+import { firstRowLink, isCoordinationHub, isRoadmapHub } from './hub.mjs';
 import { resolveDocArg } from './index.mjs';
 import { runlistChildContent, slugify, titleize } from './new.mjs';
 import { bold, cyan, dim, green, red, yellow } from './color.mjs';
@@ -96,38 +97,11 @@ export function buildRunlistIndex(index, config) {
   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;
-  // Broad "held-out navigational hub" predicate: both coordination hubs and the
-  // tier-3 roadmap (`execution_mode: roadmap`) are lifted out of the active count
-  // and into a hub section. `isRoadmapHub` is the finer split the tier-3 views
-  // use to promote a roadmap above the Runlists section; here a roadmap counts as
-  // a coordination hub so all the existing held-out plumbing covers it for free.
-  if (doc.executionMode === 'coordination' || doc.executionMode === 'roadmap') return true;
-  const base = (doc.path.split('/').pop() || '').replace(/\.md$/, '');
-  return base === 'runlist' || base.endsWith('-runlist');
-}
-
-// A *roadmap* is the tier-3 hub: a coordination hub whose children are themselves
-// hubs (runlists / coordination hubs), with progress rolled up across them. The
-// signal is explicit — `execution_mode: roadmap` — with NO slug-convention
-// fallback (unlike coordination hubs' `*-runlist`): there's no naming convention
-// for roadmaps, and `dotmd check` nudges the structural case (a coordination hub
-// that points at other hubs) toward the explicit field rather than auto-promoting.
-export function isRoadmapHub(doc) {
-  if (!doc) return false;
-  if (doc.type && doc.type !== 'plan') return false;
-  return doc.executionMode === 'roadmap';
-}
+// The hub predicates live in `hub.mjs` — a leaf module, so the check pipeline
+// (which runs from `index.mjs`, and can't import this file without a cycle) can
+// share ONE definition of "hub" with the views here. Re-exported so every
+// existing importer keeps reaching them at `runlist.mjs`.
+export { isCoordinationHub, isRoadmapHub };
 
 // Map each coordination hub to a `childCount` derived from its `related_plans:`
 // cluster (resolved against the index; peers/self excluded). It's an
@@ -378,8 +352,11 @@ function detectBodyRunlistRefs(body) {
     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]);
+      // `firstRowLink` is the shared row→target anchor: the hub-status guard
+      // reads the same link out of the same row, so next-pickup and drift
+      // detection can never disagree about which plan a row names.
+      const link = firstRowLink(line);
+      if (link) refs.push(link);
     }
   }
 

package/src/sync-status.mjs

@@ -0,0 +1,314 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { extractFrontmatter, normalizeEol } from './frontmatter.mjs';
+import { die, isArchivedPath, resolveRefPath, toRepoPath } from './util.mjs';
+import { cyan, dim, green, red, yellow } from './color.mjs';
+import { authorizeManagedSweep } from './managed-path.mjs';
+import {
+  MARKER_CLOSE,
+  MARKER_OPEN,
+  applyStatusCase,
+  isHubDoc,
+  readPositionalToken,
+  scanHubStatusRows,
+} from './hub.mjs';
+
+// Hub status drift: a hub rows its children in a table and prints each child's
+// status by hand. Nothing keeps that word honest — the child goes `archived`,
+// the hub still says `active`, and every later reader plans against a status
+// that stopped being true.
+//
+// dotmd already reads those rows to compute next-pickup, so the guard is
+// standing next to the data it needs. Everything it needs is already owned:
+// `config.types[<type>].statuses` for the vocabulary (type-aware, so a `doc`
+// rowed in a plan hub is judged by the doc vocabulary), `resolveRefPath` for
+// the link (case-fold-aware), the index for the child's real status, and
+// archive-dir-outranks-frontmatter for archived children.
+//
+// The three-way split below is the part that is easy to get wrong. A row with
+// no readable status token is NOT automatically a finding:
+//
+//   pointer    — the table has no status column at all. Legitimate; many hubs
+//                row a child just to say "related". SILENT.
+//   unreadable — the table HAS a `Status`/`State` column but no status word can
+//                be read from the cell. WARNING: the row opts out of the
+//                invariant invisibly, and that is exactly where real drift hides.
+//   manageable — a token was found (positionally or in a marker). Compare it.
+//
+// Collapsing those (treating every unmatched row as a finding) floods perfectly
+// correct hubs with false positives.
+
+// Warning when inferred, error when marked — no config knob. `dotmd check`
+// exits 0 on warnings and 1 on errors, and that asymmetry is the whole point: a
+// positional match is dotmd INFERRING from prose, so it nudges; a marked span is
+// the author declaring "dotmd owns this word", so drifting it fails the check.
+// No repo that never asked for this feature starts failing builds over an
+// inference.
+const DRIFT_KIND = 'hub-status-drift';
+const UNREADABLE_KIND = 'hub-status-unreadable';
+
+// Mirror `isValidStatus` in validate.mjs: a doc's own type owns its vocabulary,
+// falling back to the root set and then the global union for untyped docs.
+function statusVocabulary(doc, config) {
+  if (doc.type) {
+    const typeSet = config.typeStatuses?.get(doc.type);
+    if (typeSet?.size) return typeSet;
+  }
+  return config.rootValidStatuses?.get(doc.root) ?? config.validStatuses ?? new Set();
+}
+
+// A doc physically living under the archive dir is archived, whatever its
+// frontmatter says — the same precedence the rest of dotmd applies. (The
+// frontmatter itself is already an error from `validateDoc`; the hub row should
+// still be told the truth rather than agreeing with the stale word.)
+function effectiveStatus(doc, config) {
+  const archiveStatuses = config.lifecycle?.archiveStatuses ?? new Set(['archived']);
+  if (isArchivedPath(doc.path, config) && !archiveStatuses.has(doc.status)) {
+    return [...archiveStatuses][0] ?? 'archived';
+  }
+  return doc.status ?? null;
+}
+
+function truncate(text, max = 60) {
+  const squeezed = text.trim().replace(/\s+/g, ' ');
+  return squeezed.length > max ? `${squeezed.slice(0, max - 1)}…` : squeezed;
+}
+
+// Read every hub's rows and classify each one. `hubPaths` narrows the sweep to
+// named hubs; when given, quiet/terminal hubs are included too (the user asked
+// for that hub by name, so the noise-control rule doesn't apply).
+export function collectHubStatusRows(docs, config, { hubPaths = null } = {}) {
+  const docByPath = new Map(docs.map(doc => [doc.path, doc]));
+  // `resolveRefPath` is case-fold-aware, so on a case-folding filesystem a row
+  // linking `BILLING-A.md` resolves to the file that is indexed as
+  // `billing-a.md` — a path string the exact map can't answer. Fold as a
+  // fallback, and only when the fold is unambiguous: on a case-SENSITIVE
+  // filesystem those really are two different docs.
+  const docByFoldedPath = new Map();
+  for (const doc of docs) {
+    const key = doc.path.toLowerCase();
+    docByFoldedPath.set(key, docByFoldedPath.has(key) ? null : doc);
+  }
+  const quiet = new Set([
+    ...(config.lifecycle?.terminalStatuses ?? []),
+    ...(config.lifecycle?.skipWarningsFor ?? []),
+  ]);
+  const out = [];
+
+  for (const hub of docs) {
+    if (!isHubDoc(hub)) continue;
+    if (hubPaths) { if (!hubPaths.has(hub.path)) continue; }
+    else if (quiet.has(hub.status)) continue;
+
+    let raw;
+    try { raw = readFileSync(path.join(config.repoRoot, hub.path), 'utf8'); } catch { continue; }
+    const { body, bodyLineOffset } = extractFrontmatter(raw);
+    const hubDir = path.dirname(path.join(config.repoRoot, hub.path));
+
+    const rows = [];
+    for (const row of scanHubStatusRows(body)) {
+      const href = row.ref.replace(/#.*$/, '');
+      const abs = resolveRefPath(href, hubDir, config.repoRoot);
+      // A row whose link is broken is already a body-link finding. Reporting it
+      // again as unreadable status would double-report one problem.
+      if (!abs) continue;
+      const repoPath = toRepoPath(abs, config.repoRoot);
+      const target = docByPath.get(repoPath) ?? docByFoldedPath.get(repoPath.toLowerCase()) ?? null;
+      if (!target || target.path === hub.path) continue;
+      const actual = effectiveStatus(target, config);
+      if (!actual) continue; // missing `status:` is the child's own error
+
+      const vocabulary = statusVocabulary(target, config);
+      const span = row.marked
+        ?? readPositionalToken(row.statusCell, word => vocabulary.has(word.toLowerCase()));
+      const base = {
+        lineIndex: row.lineIndex,
+        line: bodyLineOffset + row.lineIndex + 1,
+        target: target.path,
+        actual,
+      };
+      if (!span) {
+        // No status column → pointer row → silent. Status column → the row opts
+        // out of the invariant invisibly, which is a finding.
+        if (row.hasStatusColumn) {
+          rows.push({ ...base, state: 'unreadable', marked: false, span: null, printed: null,
+            cell: row.statusCell ? truncate(row.statusCell.raw) : '' });
+        }
+        continue;
+      }
+      rows.push({
+        ...base,
+        state: span.text.toLowerCase() === String(actual).toLowerCase() ? 'ok' : 'drift',
+        marked: Boolean(row.marked),
+        span,
+        printed: span.text,
+      });
+    }
+    if (rows.length) out.push({ hub, rows, bodyLineOffset });
+  }
+  return out;
+}
+
+// The check-pipeline pass. Returns index-level warnings/errors; `src/index.mjs`
+// pushes them and attaches them to the owning hub doc.
+export function checkHubStatusDrift(docs, config) {
+  const warnings = [];
+  const errors = [];
+  for (const { hub, rows } of collectHubStatusRows(docs, config)) {
+    for (const row of rows) {
+      if (row.state === 'drift') {
+        const entry = {
+          path: hub.path,
+          level: row.marked ? 'error' : 'warning',
+          message: row.marked
+            ? `line ${row.line} rows \`${row.target}\` as \`${row.printed}\` inside a \`${MARKER_OPEN}…${MARKER_CLOSE}\` marker, but that doc's status is \`${row.actual}\`. The marker means dotmd owns that word — run \`dotmd sync-status\` to rewrite it, or change the doc's status.`
+            : `line ${row.line} rows \`${row.target}\` as \`${row.printed}\`, but that doc's status is \`${row.actual}\`. Run \`dotmd sync-status\` to rewrite the row, or change the doc's status.`,
+          meta: { kind: DRIFT_KIND, target: row.target, printed: row.printed, actual: row.actual, line: row.line, marked: row.marked },
+        };
+        (row.marked ? errors : warnings).push(entry);
+      } else if (row.state === 'unreadable') {
+        warnings.push({
+          path: hub.path,
+          level: 'warning',
+          message: `line ${row.line} rows \`${row.target}\` under a status column, but no status word could be read from the cell (\`${row.cell}\`). Lead the cell with the status, or wrap the status in \`${MARKER_OPEN}…${MARKER_CLOSE}\`, so drift in this row can be caught.`,
+          meta: { kind: UNREADABLE_KIND, target: row.target, line: row.line },
+        });
+      }
+    }
+  }
+  return { warnings, errors };
+}
+
+// Rewrite drifted status words, and (with `adopt`) wrap managed positional
+// tokens in markers. `adopt` is separate because wrapping a word in markers is a
+// content edit to prose the user wrote: `check --fix` / `doctor` rewrite status
+// TOKENS, marked or positional; only `--adopt` ADDS markers.
+export function syncHubStatuses(config, { docs, dryRun = false, adopt = false, hubPaths = null, quiet = false } = {}) {
+  const hubs = collectHubStatusRows(docs, config, { hubPaths });
+  if (hubs.length) {
+    authorizeManagedSweep(hubs.map(h => path.join(config.repoRoot, h.hub.path)), config, { kind: 'Hub status sync source' });
+  }
+
+  const prefix = dryRun ? dim('[dry-run] ') : '';
+  const result = { fixed: 0, adopted: 0, unreadable: 0, hubs: [], skippedLineStart: 0 };
+
+  for (const { hub, bodyLineOffset, rows } of hubs) {
+    const absPath = path.join(config.repoRoot, hub.path);
+    const raw = normalizeEol(readFileSync(absPath, 'utf8'));
+    const lines = raw.split('\n');
+    const applied = [];
+    let unreadable = 0;
+
+    for (const row of rows) {
+      if (row.state === 'unreadable') { unreadable++; continue; }
+      const drifted = row.state === 'drift';
+      let wrap = adopt && !row.marked;
+      // A marker must never begin a line: `reference-planner.mjs` returns any
+      // line starting with `<!--` unmodified (CommonMark HTML-block rule), so a
+      // link sharing that line would stop being rewritten by moves. A table row
+      // always starts with `|`, so this cannot bite in the intended use — the
+      // guard is here so a "markers on their own line" idea fails loudly.
+      if (wrap && !lines[bodyLineOffset + row.lineIndex].slice(0, row.span.start).trim()) {
+        wrap = false;
+        result.skippedLineStart++;
+      }
+      if (!drifted && !wrap) continue;
+
+      const replacement = drifted ? applyStatusCase(row.printed, row.actual) : row.printed;
+      const lineIdx = bodyLineOffset + row.lineIndex;
+      const line = lines[lineIdx];
+      lines[lineIdx] = line.slice(0, row.span.start)
+        + (wrap ? MARKER_OPEN : '') + replacement + (wrap ? MARKER_CLOSE : '')
+        + line.slice(row.span.end);
+      applied.push({ line: row.line, target: row.target, from: row.printed, to: replacement, drifted, wrapped: wrap, marked: row.marked });
+      if (drifted) result.fixed++;
+      if (wrap) result.adopted++;
+    }
+
+    result.unreadable += unreadable;
+    if (applied.length === 0) {
+      if (unreadable > 0) result.hubs.push({ path: hub.path, changes: [], unreadable });
+      continue;
+    }
+    if (!dryRun) writeFileSync(absPath, lines.join('\n'), 'utf8');
+    result.hubs.push({ path: hub.path, changes: applied, unreadable });
+
+    if (!quiet) {
+      process.stdout.write(`${prefix}${green('Synced')}: ${hub.path} (${applied.length} row${applied.length === 1 ? '' : 's'})\n`);
+      for (const change of applied) {
+        const what = change.drifted
+          ? `${red(change.from)} → ${green(change.to)}`
+          : `${dim('marked')} ${cyan(change.to)}`;
+        const wrapNote = change.wrapped && change.drifted ? dim(' + marker') : '';
+        process.stdout.write(`${prefix}  ${dim(`line ${change.line}`)} ${what}${wrapNote} ${dim(`(${change.target})`)}\n`);
+      }
+    }
+  }
+
+  if (!quiet) {
+    if (result.fixed > 0 || result.adopted > 0) {
+      const parts = [];
+      if (result.fixed) parts.push(`${result.fixed} row${result.fixed === 1 ? '' : 's'} rewritten`);
+      if (result.adopted) parts.push(`${result.adopted} marker${result.adopted === 1 ? '' : 's'} added`);
+      process.stdout.write(`\n${prefix}${parts.join(', ')}.\n`);
+    }
+    if (result.unreadable > 0) {
+      process.stdout.write(yellow(`${result.unreadable} row(s) sit under a status column with no readable status word`)
+        + ' — lead the cell with the status, or wrap it in '
+        + `${MARKER_OPEN}…${MARKER_CLOSE}. Run \`dotmd check\` to list them.\n`);
+    }
+  }
+  return result;
+}
+
+// Resolve `dotmd sync-status <hub...>` arguments against the index. Matching by
+// path, path+`.md`, or basename slug — the same handles every other verb takes —
+// with a hub-aware miss message (a plain plan named here is a mistake worth
+// naming, not a silent no-op).
+function resolveHubArgs(args, docs) {
+  const paths = new Set();
+  for (const arg of args) {
+    const slug = arg.replace(/\.md$/, '');
+    const matches = docs.filter(doc =>
+      doc.path === arg || doc.path === `${slug}.md`
+      || path.basename(doc.path, '.md') === path.basename(slug));
+    if (matches.length === 0) die(`No doc matches "${arg}".`);
+    if (matches.length > 1) {
+      die(`Multiple docs match "${arg}":\n${matches.map(m => `  ${m.path}`).join('\n')}`);
+    }
+    const [match] = matches;
+    if (!isHubDoc(match)) {
+      die(`${match.path} is not a hub — it has no \`runlist:\` and no \`execution_mode: coordination|roadmap\`. `
+        + 'Run `dotmd sync-status` with no argument to sweep every hub.');
+    }
+    paths.add(match.path);
+  }
+  return paths;
+}
+
+export async function runSyncStatus(argv, config, opts = {}) {
+  // Dynamic so this module stays importable FROM index.mjs (which needs
+  // `checkHubStatusDrift`) without closing an import cycle.
+  const { buildIndex } = await import('./index.mjs');
+
+  const adopt = argv.includes('--adopt');
+  const json = argv.includes('--json');
+  const hubArgs = argv.filter(arg => !arg.startsWith('-'));
+  const docs = buildIndex(config).docs;
+  const hubPaths = hubArgs.length ? resolveHubArgs(hubArgs, docs) : null;
+
+  const result = syncHubStatuses(config, { docs, dryRun: opts.dryRun, adopt, hubPaths, quiet: json });
+  if (json) {
+    process.stdout.write(`${JSON.stringify({ dryRun: Boolean(opts.dryRun), adopt, ...result }, null, 2)}\n`);
+    return;
+  }
+  if (result.fixed === 0 && result.adopted === 0 && result.unreadable === 0) {
+    process.stdout.write(green('Hub status rows are in sync.') + '\n');
+  }
+  if (adopt && result.skippedLineStart > 0) {
+    process.stdout.write(dim(`${result.skippedLineStart} token(s) left unmarked: a marker may never begin a line.\n`));
+  }
+}
+
+export { MARKER_CLOSE, MARKER_OPEN };
+export const HUB_STATUS_KINDS = Object.freeze({ drift: DRIFT_KIND, unreadable: UNREADABLE_KIND });