dotmd-cli 0.73.0 → 0.74.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.73.0",
+  "version": "0.74.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/hub-membership.mjs

@@ -0,0 +1,151 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { extractFrontmatter } from './frontmatter.mjs';
+import { resolveRefPath, toRepoPath } from './util.mjs';
+import { detectBodyRunlistRefs, isHubDoc } from './hub.mjs';
+
+// Membership drift: a hub's list of children and the plans that claim it via
+// `parent_plan:` are two halves of one relationship, and either half can go
+// stale on its own. dotmd already checks one direction — `checkRunlistBackPointers`
+// warns when a `runlist:` child lacks the back-ref. These are the two arrows it
+// doesn't cover.
+//
+// Membership only. The row is NEVER generated — same constraint as the status
+// guard: the prose beside a row is why the row exists.
+//
+// ── What counts as a membership claim (measured, not assumed) ───────────────
+//
+// A body table row is NOT one. dotmd's own estate has an aggregator hub whose
+// ranked queue draws plans from three other programs, and whose other tables row
+// children purely to say "related" — the same pointer-row shape the status guard
+// already declines to judge. Treating every rowed link as membership would flood
+// correct hubs.
+//
+// What IS a claim: `runlist:` (frontmatter order) and the hub's BODY ORDER
+// (`## Ranked queue` / `## Order of operations`) — the list `dotmd runlist next`
+// actually walks. A plan there is one this hub would hand a session.
+//
+// ── Why "points at a different hub" is deliberately silent ──────────────────
+//
+// The scaffolded plan wanted a warning when a rowed child "moved to another
+// hub". Measured against a real estate, sharing is legitimate and common: an
+// aggregator hub ranks plans whose `parent_plan:` names the program hub that
+// owns them, and demanding exclusivity would fire on every one of those rows
+// with no fix that doesn't break the other hub's claim. So the guard fires only
+// on the unambiguous half — a ranked plan claiming NO parent at all.
+
+const ORPHAN_KIND = 'hub-membership-orphan';
+const BACKREF_KIND = 'hub-membership-backref';
+
+export function checkHubMembershipDrift(docs, config) {
+  const warnings = [];
+  const quiet = new Set([
+    ...(config.lifecycle?.terminalStatuses ?? []),
+    ...(config.lifecycle?.skipWarningsFor ?? []),
+  ]);
+  const byPath = new Map(docs.map(doc => [doc.path, doc]));
+  const refFields = [
+    ...(config.referenceFields?.bidirectional ?? []),
+    ...(config.referenceFields?.unidirectional ?? []),
+  ];
+
+  const dirOf = (doc) => path.dirname(path.join(config.repoRoot, doc.path));
+  const resolve = (ref, dir) => {
+    const abs = resolveRefPath(String(ref).replace(/#.*$/, ''), dir, config.repoRoot);
+    return abs ? byPath.get(toRepoPath(abs, config.repoRoot)) ?? null : null;
+  };
+
+  // Everything a hub says about other docs: every configured reference field
+  // plus every body link. Config-driven rather than a hardcoded field list, so a
+  // repo that renames its reference fields keeps working.
+  const knownTo = (hub) => {
+    const dir = dirOf(hub);
+    const known = new Set();
+    for (const field of refFields) {
+      for (const ref of (hub.refFields?.[field] ?? [])) {
+        const target = resolve(ref, dir);
+        if (target) known.add(target.path);
+      }
+    }
+    for (const link of (hub.bodyLinks ?? [])) {
+      const target = resolve(link.href, dir);
+      if (target) known.add(target.path);
+    }
+    return known;
+  };
+
+  // ── Arrow 1: a claim only the child makes ────────────────────────────────
+  // The plan says `parent_plan: <hub>` and the hub references it NOWHERE — not
+  // in a reference field, not as a body link. One side of the relationship
+  // silently dropped the other, and every hub view (fold, rollup, next-pickup)
+  // is computed from the hub's side, so the child is invisible where it thinks
+  // it lives. Warns on the HUB: the hub's list is the half that lost the entry.
+  const knownCache = new Map();
+  for (const child of docs) {
+    if (quiet.has(child.status)) continue;
+    const parents = child.refFields?.parent_plan ?? [];
+    if (parents.length === 0) continue;
+    const dir = dirOf(child);
+    for (const ref of parents) {
+      const hub = resolve(ref, dir);
+      // Only hubs are asked to carry a membership list. A plain plan named as a
+      // parent rows nothing, and demanding a link back there would be a new
+      // opinion rather than a drift check.
+      if (!hub || hub.path === child.path || !isHubDoc(hub)) continue;
+      if (quiet.has(hub.status)) continue;
+      if (!knownCache.has(hub.path)) knownCache.set(hub.path, knownTo(hub));
+      if (knownCache.get(hub.path).has(child.path)) continue;
+      warnings.push({
+        path: hub.path,
+        level: 'warning',
+        message: `\`${child.path}\` claims \`parent_plan: ${ref}\` but this hub references it nowhere — no reference field, no body link. Add it to the hub's list, or fix the child's \`parent_plan:\`. A membership only one side records is invisible to every hub view (fold, rollup, next-pickup), which all read the hub's half.`,
+        meta: { kind: ORPHAN_KIND, child: child.path, ref },
+      });
+    }
+  }
+
+  // ── Arrow 2: a claim only the hub makes ──────────────────────────────────
+  // The hub's BODY ORDER ranks a plan — the list `dotmd runlist next <hub>`
+  // walks, so this hub would hand a session that plan — and the plan carries no
+  // `parent_plan:` at all. This is the same finding `checkRunlistBackPointers`
+  // makes for frontmatter `runlist:` children, extended to the body-order hubs
+  // it can't see; children already covered there are skipped, so one missing
+  // back-ref is never reported twice. Warns on the CHILD, matching that check:
+  // it's the file that needs the edit.
+  for (const hub of docs) {
+    if (!isHubDoc(hub) || quiet.has(hub.status)) continue;
+    let body;
+    try { ({ body } = extractFrontmatter(readFileSync(path.join(config.repoRoot, hub.path), 'utf8'))); }
+    catch { continue; }
+    const ranked = detectBodyRunlistRefs(body);
+    if (ranked.length === 0) continue;
+    const dir = dirOf(hub);
+    const inFrontmatterRunlist = new Set();
+    for (const ref of (hub.refFields?.runlist ?? [])) {
+      const target = resolve(ref, dir);
+      if (target) inFrontmatterRunlist.add(target.path);
+    }
+
+    const seen = new Set();
+    for (const ref of ranked) {
+      const child = resolve(ref, dir);
+      if (!child || child.path === hub.path || seen.has(child.path)) continue;
+      seen.add(child.path);
+      if (quiet.has(child.status)) continue;                 // closed work is normal history
+      if (inFrontmatterRunlist.has(child.path)) continue;    // checkRunlistBackPointers owns it
+      if (isHubDoc(child)) continue;                         // a hub under a hub is the roadmap tier
+      if (child.type && child.type !== 'plan') continue;     // `parent_plan` is a plan relationship
+      if ((child.refFields?.parent_plan ?? []).length > 0) continue;
+      warnings.push({
+        path: child.path,
+        level: 'warning',
+        message: `is ranked in the body order of \`${hub.path}\` (the list \`dotmd runlist next\` walks) but has no \`parent_plan:\`. Add \`parent_plan: ${hub.path}\` so reverse-link tooling (pickup-card Related:, graph) stays consistent.`,
+        meta: { kind: BACKREF_KIND, hub: hub.path },
+      });
+    }
+  }
+
+  return warnings;
+}
+
+export const HUB_MEMBERSHIP_KINDS = Object.freeze({ orphan: ORPHAN_KIND, backref: BACKREF_KIND });

package/src/hub.mjs

@@ -215,3 +215,56 @@ export function applyStatusCase(sample, replacement) {
   if (/^[A-Z]/.test(sample)) return replacement.charAt(0).toUpperCase() + replacement.slice(1);
   return replacement;
 }
+
+// Extract ordered plan refs from a hub's body prose. Two shapes:
+//   - link-list sections (`## Order of operations`, `## Runlist`, …) — every
+//     `.md` link or checklist item, in document order.
+//   - ranked-queue tables (`## Ranked queue`, …) — the first `.md` link in each
+//     table row (the ranked plan); header/separator rows contribute none.
+// Coordination hubs encode their next-pickup order in the table shape; sprint-
+// ish hubs use the link list. Deduped, first occurrence wins, order preserved.
+//
+// This is a hub's BODY MEMBERSHIP claim, not merely a set of links: it is the
+// order `dotmd runlist <hub>` / `runlist next <hub>` walk, so a plan listed here
+// is one this hub would hand a session. The membership guard leans on exactly
+// that — a plan in some other table is a pointer, a plan in this order is a claim.
+export function detectBodyRunlistRefs(body) {
+  if (!body) return [];
+  const refs = [];
+  const linkRe = /\[[^\]]+\]\(([^)]+\.md(?:#[^)]+)?)\)/;
+  const sliceSection = (start) => {
+    const rest = body.slice(start);
+    const next = rest.search(/^##\s+/m);
+    return next >= 0 ? rest.slice(0, next) : rest;
+  };
+
+  const linkSectionRe = /^##\s+(?:Order of operations|Runlist|Execution order|Implementation order|Plan order)\b.*$/gim;
+  let match;
+  while ((match = linkSectionRe.exec(body)) !== null) {
+    const section = sliceSection(match.index + match[0].length);
+    const allLinks = new RegExp(linkRe.source, 'g');
+    let link;
+    while ((link = allLinks.exec(section)) !== null) refs.push(link[1]);
+
+    const checklistRe = /^\s*[-*]\s+\[[ xX]\]\s+([^\s)]+\.md(?:#[^\s)]+)?)/gm;
+    let item;
+    while ((item = checklistRe.exec(section)) !== null) refs.push(item[1]);
+  }
+
+  // Ranked-queue tables: the first `.md` link per row is the ranked plan. A
+  // header (`| Rank | Plan | … |`) and separator (`|---|`) carry no link and are
+  // skipped naturally. Heading may carry trailing text (`## Ranked queue (next
+  // pickup)`), so match the leading words, not an exact line.
+  const queueSectionRe = /^##\s+(?:Ranked queue|Queue|Pickup order|Heads)\b.*$/gim;
+  while ((match = queueSectionRe.exec(body)) !== null) {
+    const section = sliceSection(match.index + match[0].length);
+    for (const rawLine of section.split('\n')) {
+      const line = rawLine.trim();
+      if (!line.startsWith('|')) continue;
+      const link = firstRowLink(line);
+      if (link) refs.push(link);
+    }
+  }
+
+  return [...new Set(refs)];
+}

package/src/index.mjs

@@ -10,6 +10,7 @@ import { checkClaudeCommands } from './claude-commands.mjs';
 import { checkGlossaryConfig } from './glossary-check.mjs';
 import { checkSkillDrift } from './skill-drift.mjs';
 import { checkHubStatusDrift } from './sync-status.mjs';
+import { checkHubMembershipDrift } from './hub-membership.mjs';
 
 // `fast: true` skips every pass that produces warnings/errors — the rendered
 // index file consumes only status/title/snapshot/etc., not the validation
@@ -143,6 +144,13 @@ export function buildIndex(config, opts = {}) {
       if (child) child.warnings.push(w);
     }
 
+    const membershipWarnings = checkHubMembershipDrift(transformedDocs, config);
+    warnings.push(...membershipWarnings);
+    for (const w of membershipWarnings) {
+      const owner = transformedDocs.find(d => d.path === w.path);
+      if (owner) owner.warnings.push(w);
+    }
+
     const coordHubWarnings = checkCoordinationHubExecutionMode(transformedDocs, config);
     warnings.push(...coordHubWarnings);
     for (const w of coordHubWarnings) {

package/src/runlist.mjs

@@ -14,7 +14,7 @@ import {
   toSlug,
   warn,
 } from './util.mjs';
-import { firstRowLink, isCoordinationHub, isRoadmapHub } from './hub.mjs';
+import { detectBodyRunlistRefs, 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';
@@ -312,56 +312,6 @@ function resolveRunlistRefs(refs, hubAbsPath, config) {
   return out;
 }
 
-// Extract ordered plan refs from a hub's body prose. Two shapes:
-//   - link-list sections (`## Order of operations`, `## Runlist`, …) — every
-//     `.md` link or checklist item, in document order.
-//   - ranked-queue tables (`## Ranked queue`, …) — the first `.md` link in each
-//     table row (the ranked plan); header/separator rows contribute none.
-// Coordination hubs encode their next-pickup order in the table shape; sprint-
-// ish hubs use the link list. Deduped, first occurrence wins, order preserved.
-function detectBodyRunlistRefs(body) {
-  if (!body) return [];
-  const refs = [];
-  const linkRe = /\[[^\]]+\]\(([^)]+\.md(?:#[^)]+)?)\)/;
-  const sliceSection = (start) => {
-    const rest = body.slice(start);
-    const next = rest.search(/^##\s+/m);
-    return next >= 0 ? rest.slice(0, next) : rest;
-  };
-
-  const linkSectionRe = /^##\s+(?:Order of operations|Runlist|Execution order|Implementation order|Plan order)\b.*$/gim;
-  let match;
-  while ((match = linkSectionRe.exec(body)) !== null) {
-    const section = sliceSection(match.index + match[0].length);
-    const allLinks = new RegExp(linkRe.source, 'g');
-    let link;
-    while ((link = allLinks.exec(section)) !== null) refs.push(link[1]);
-
-    const checklistRe = /^\s*[-*]\s+\[[ xX]\]\s+([^\s)]+\.md(?:#[^\s)]+)?)/gm;
-    let item;
-    while ((item = checklistRe.exec(section)) !== null) refs.push(item[1]);
-  }
-
-  // Ranked-queue tables: the first `.md` link per row is the ranked plan. A
-  // header (`| Rank | Plan | … |`) and separator (`|---|`) carry no link and are
-  // skipped naturally. Heading may carry trailing text (`## Ranked queue (next
-  // pickup)`), so match the leading words, not an exact line.
-  const queueSectionRe = /^##\s+(?:Ranked queue|Queue|Pickup order|Heads)\b.*$/gim;
-  while ((match = queueSectionRe.exec(body)) !== null) {
-    const section = sliceSection(match.index + match[0].length);
-    for (const rawLine of section.split('\n')) {
-      const line = rawLine.trim();
-      if (!line.startsWith('|')) continue;
-      // `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);
-    }
-  }
-
-  return [...new Set(refs)];
-}
 
 // Label for a hub's next-pickup child: its slug with the hub's leading module
 // segment stripped when shared (so `founder-runlist` → `founder-brand-conflicts`