dotmd-cli 0.73.0 → 0.74.1

package/package.json

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

package/src/atomic-mutation.mjs

@@ -1279,9 +1279,9 @@ export function createFileExclusive(filePath, content, options) {
 }
 
 export function moveFileAtomic(sourcePath, targetPath, render, options) {
-  const { repoRoot, finalize, rollbackFinalize, testHooks, updates = [], creations = [], deletions = [] } = options;
+  const { repoRoot, finalize, rollbackFinalize, testHooks, updates = [], creations = [], deletions = [], guards = [] } = options;
   recoverAbandonedTransactions(repoRoot, options);
-  return withPathLocks([sourcePath, targetPath, ...updates.map(item => item.path), ...creations.map(item => item.path), ...deletions.map(item => item.path)], options, () => {
+  return withPathLocks([sourcePath, targetPath, ...updates.map(item => item.path), ...creations.map(item => item.path), ...deletions.map(item => item.path), ...guards.map(item => item.path)], options, () => {
     testHooks?.afterTransactionPhase?.('lock', { sourcePath, targetPath });
     testHooks?.beforeMoveSnapshot?.({ sourcePath, targetPath });
     const source = snapshotFile(sourcePath);
@@ -1304,6 +1304,15 @@ export function moveFileAtomic(sourcePath, targetPath, render, options) {
       }
       return { ...item, snapshot };
     });
+    // Read-only participants (see `mutateFileSet`). Checked before the
+    // transaction manifest exists, so a guard conflict can never leave a
+    // transaction to recover from.
+    for (const guard of guards) {
+      const snapshot = snapshotFile(guard.path);
+      if (guard.expectedContent !== undefined && snapshot.content !== guard.expectedContent) {
+        throw new MutationConflictError(`File changed while the move mutation set was being prepared: ${snapshot.path}`);
+      }
+    }
     for (const item of creations) {
       if (existsSync(item.path)) throw new MutationConflictError(`Destination already exists: ${path.resolve(item.path)}`);
     }
@@ -1627,9 +1636,30 @@ export function moveFileAtomic(sourcePath, targetPath, render, options) {
   });
 }
 
-export function mutateFileSet({ updates = [], creations = [] }, options) {
-  const paths = [...updates.map(item => item.path), ...creations.map(item => item.path)];
+// `guards` are read-only participants: files the mutation's VALIDITY depends on
+// but that it never writes. They take part in locking and in the same
+// compare-and-swap as `updates`, so a mutation decided from a file it doesn't
+// modify cannot land after that file changed underneath it.
+//
+// Without this, a decision read and the write it justifies are two separate
+// steps with nothing holding the gap. A claim that adopts an already-in-session
+// plan writes only the ownership record — so a concurrent `set` releasing that
+// plan could win the status write while the claim still took ownership, leaving
+// a record that owns a plan the file says is `active`. A no-op update on the
+// plan file would close the gap too, but it would rewrite bytes and report the
+// plan as changed to anything counting touched files. A guard says what is meant.
+export function mutateFileSet({ updates = [], creations = [], guards = [] }, options) {
+  const paths = [...updates.map(item => item.path), ...creations.map(item => item.path), ...guards.map(item => item.path)];
   return withPathLocks(paths, options, () => {
+    // Guards are pure preconditions, so they are checked before anything at all
+    // is created — a guard conflict must leave the tree byte-identical, not even
+    // an empty directory behind.
+    for (const guard of guards) {
+      const snapshot = snapshotFile(guard.path);
+      if (guard.expectedContent !== undefined && snapshot.content !== guard.expectedContent) {
+        throw new MutationConflictError(`File changed while the mutation set was being prepared: ${snapshot.path}`);
+      }
+    }
     const createdDirectories = [];
     for (const item of creations) {
       const directory = path.dirname(item.path);
@@ -1654,7 +1684,7 @@ export function mutateFileSet({ updates = [], creations = [] }, options) {
     for (const item of creations) {
       if (existsSync(item.path)) throw new MutationConflictError(`Destination already exists: ${path.resolve(item.path)}`);
     }
-    options.testHooks?.afterSetPreflight?.({ updates: preparedUpdates, creations });
+    options.testHooks?.afterSetPreflight?.({ updates: preparedUpdates, creations, guards });
 
     const committedUpdates = [];
     const committedCreations = [];

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/lifecycle.mjs

@@ -107,6 +107,7 @@ function commitLifecycleMutation(filePath, targetPath, config, updates, historyF
         }),
       })), ...additionalUpdates],
       creations: options.creations ?? [],
+      guards: options.guards ?? [],
       gitMove: tracked,
       gitIndex,
       operation: 'lifecycle-move',
@@ -115,12 +116,13 @@ function commitLifecycleMutation(filePath, targetPath, config, updates, historyF
     });
     return { ...result, sourceContent: moveResult.source.content, updatedPaths: moveResult.updatedPaths };
   }
-  if ((options.additionalUpdates?.length ?? 0) > 0 || (options.creations?.length ?? 0) > 0) {
+  if ((options.additionalUpdates?.length ?? 0) > 0 || (options.creations?.length ?? 0) > 0 || (options.guards?.length ?? 0) > 0) {
     const sourceContent = readFileSync(filePath, 'utf8');
     const result = render(sourceContent);
     mutateFileSet({
       updates: [{ path: filePath, expectedContent: sourceContent, content: result.content }, ...(options.additionalUpdates ?? [])],
       creations: options.creations ?? [],
+      guards: options.guards ?? [],
     }, { repoRoot: config.repoRoot, testHooks: options.testHooks });
     return { ...result, sourceContent, updatedPaths: [] };
   }
@@ -767,6 +769,7 @@ export function runArchive(argv, config, opts = {}) {
         createSection: Boolean(note),
         additionalUpdates: [...(opts.additionalUpdates ?? []), ...(releaseUpdate ? [releaseUpdate] : [])],
         creations: opts.creations,
+        guards: opts.guards,
         testHooks: opts.testHooks,
       });
     if (!noIndex && !opts.deferIndex) regenIndex(config);
@@ -833,6 +836,7 @@ export function runArchive(argv, config, opts = {}) {
       testHooks: opts.testHooks,
       additionalUpdates: [...(opts.additionalUpdates ?? []), ...(releaseUpdate ? [releaseUpdate] : [])],
       creations: opts.creations,
+      guards: opts.guards,
       skipInboundRefs: opts.skipInboundRefs,
       bodyTransform: closeoutTemplate ? currentBody => {
         committedCloseoutAction = planCloseoutInjection(currentBody);

package/src/pickup.mjs

@@ -258,19 +258,28 @@ export function preparePlanClaim({ filePath, sourceContent, renderedContent, own
   const content = recordContent({ identity, sessionId, state: 'owned', now,
     claimedAt: ownership && !ownership.corrupt ? ownership.claimedAt : null, operation });
   const updates = [];
+  const guards = [];
   if (renderedContent !== null && renderedContent !== sourceContent) {
     updates.push({ path: filePath, expectedContent: sourceContent, content: renderedContent });
+  } else {
+    // An `adopt` claim writes only the ownership record — the plan is already
+    // `in-session`, so there is nothing to render. The DECISION still rests on
+    // the plan's status, which was read before this mutation was prepared, so
+    // the plan file joins as a read-only guard. Without it, a concurrent
+    // `set active` could win the status write while this claim takes ownership,
+    // leaving a record that owns a plan the file calls `active`.
+    guards.push({ path: filePath, expectedContent: sourceContent });
   }
   const creations = [];
   if (ownership) updates.push({ path: recordPath, expectedContent: ownership.raw, content });
   else creations.push({ path: recordPath, content });
-  return { identity, recordPath, updates, creations, operationId };
+  return { identity, recordPath, updates, creations, guards, operationId };
 }
 
 export function commitPlanClaim(args) {
   const prepared = preparePlanClaim(args);
   mkdirSync(path.dirname(prepared.recordPath), { recursive: true });
-  mutateFileSet({ updates: prepared.updates, creations: prepared.creations }, {
+  mutateFileSet({ updates: prepared.updates, creations: prepared.creations, guards: prepared.guards }, {
     repoRoot: args.config.repoRoot,
     testHooks: args.testHooks,
   });

package/src/prompts.mjs

@@ -289,6 +289,10 @@ export async function consumePrompt(filePath, config, opts) {
     skipInboundRefs: true,
     additionalUpdates: linkedClaim?.prepared?.updates,
     creations: linkedClaim?.prepared?.creations,
+    // An adopt-shaped claim writes no plan content, so the plan file rides
+    // along as a read-only guard — the claim is only valid while the plan still
+    // says what the disposition was read from.
+    guards: linkedClaim?.prepared?.guards,
   });
   const consumedBody = archiveResult?.consumedBody ?? body;
 

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`