dotmd-cli 0.76.6 → 0.76.8

package/bin/dotmd.mjs

@@ -238,12 +238,13 @@ Analyze:
   glossary <term> [--list] [--json] Look up domain terms + related docs
 
 Validate & Fix:
-  doctor [--apply]                  Auto-fix everything: refs, lint, long fields, dates, index (preview by default)
+  doctor [--apply]                  Auto-fix everything: refs, membership, lint, long fields, dates, index (preview by default)
   doctor --transactions             Report/clear wedged mutation transactions (run this if mutations refuse repo-wide)
   doctor --claims                   Report/release plan claims held by sessions that are gone ("busy in another session")
   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
+  fix-membership [<hub>...]         Add unambiguous missing child parent_plan back-references
   sync-status [<hub>...] [--adopt]  Rewrite hub table rows whose printed status drifted from the plan
 
 Lifecycle:
@@ -749,9 +750,10 @@ the command says so instead of printing an empty list.`,
 
   doctor: `dotmd doctor — auto-fix everything in one pass
 
-Runs in sequence: fix broken references, lint --fix, move over-cap
-frontmatter prose into body sections, sync dates from git, regenerate
-the index, then show remaining issues.
+Runs in sequence: fix broken references, repair unambiguous membership
+back-references, lint --fix, move over-cap frontmatter prose into body sections,
+sync hub status rows, sync dates from git, regenerate the index, then show
+remaining issues.
 
 Modes:
   (default)              Auto-fix pass — previews by default since 0.37.0
@@ -861,6 +863,21 @@ Rows under a status column with no readable status word are reported by
 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-membership': `dotmd fix-membership — repair unambiguous missing parent_plan back-references
+
+A repair is safe only when one live hub has already declared the relationship
+in its frontmatter runlist or body execution order and the live child plan has
+no parent_plan at all. The command writes the child-relative back-reference and
+updated date atomically.
+
+It never creates or edits hub prose, never overwrites another parent, and skips
+a parentless child ranked by multiple hubs as ambiguous.
+
+  dotmd fix-membership                 every hub in the repo
+  dotmd fix-membership <hub>...        narrow to named hubs
+  dotmd fix-membership --dry-run       preview without writing
+  dotmd fix-membership --dry-run --json`,
+
   'fix-refs': `dotmd fix-refs — auto-fix broken reference paths
 
 Scans all docs for reference fields that point to non-existent files,
@@ -1806,6 +1823,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 === 'fix-membership') { const { runFixMembership } = await import('../src/fix-membership.mjs'); await runFixMembership(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');
@@ -1917,11 +1935,14 @@ async function main() {
     }
 
     if (fix) {
-      // Auto-fix: broken refs, then lint, then rebuild index
+      // Auto-fix: broken refs, mechanical membership back-references, lint,
+      // hub status tokens, then rebuild the index.
       const { fixBrokenRefs } = await import('../src/fix-refs.mjs');
+      const { fixMembershipBackrefs } = await import('../src/fix-membership.mjs');
       const { runLint } = await import('../src/lint.mjs');
       const { syncHubStatuses } = await import('../src/sync-status.mjs');
       fixBrokenRefs(config, { dryRun, quiet: false });
+      fixMembershipBackrefs(config, { docs: buildIndex(config).docs, 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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.76.6",
+  "version": "0.76.8",
   "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

@@ -136,6 +136,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('fix-membership', mutates('managed source sweep'), 'mutate', [form('[hubs...]', { args: positionals(0, Infinity), options: [flag('--json')] })]),
   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('--claims'), flag('--session'), value('--older-than'), flag('--json'), flag('--include-archived')] })]),
   command('statuses', mutates('project config path; document scan is read-only'), 'mutate', [

package/src/doctor.mjs

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { fixBrokenRefs } from './fix-refs.mjs';
 import { runLint } from './lint.mjs';
 import { syncHubStatuses } from './sync-status.mjs';
+import { fixMembershipBackrefs } from './fix-membership.mjs';
 import { runSet, runTouch } from './lifecycle.mjs';
 import { buildIndex, collectDocFiles } from './index.mjs';
 import { writeRenderedIndex } from './index-file.mjs';
@@ -285,30 +286,35 @@ export function runDoctor(argv, config, opts = {}) {
   process.stdout.write(bold('1. Fixing broken references...') + '\n');
   fixBrokenRefs(config, { dryRun });
 
-  // Step 2: Lint --fix
-  process.stdout.write('\n' + bold('2. Fixing frontmatter issues...') + '\n');
+  // Step 2: Add only child back-references already authorized by one
+  // unambiguous hub. Hub prose is never generated or edited here.
+  process.stdout.write('\n' + bold('2. Fixing membership back-references...') + '\n');
+  fixMembershipBackrefs(config, { docs: buildIndex(config).docs, dryRun, testHooks });
+
+  // Step 3: Lint --fix
+  process.stdout.write('\n' + bold('3. Fixing frontmatter issues...') + '\n');
   runLint(['--fix'], config, { dryRun });
 
-  // Step 3: Move over-cap status prose into body sections.
-  process.stdout.write('\n' + bold('3. Fixing long frontmatter...') + '\n');
+  // Step 4: Move over-cap status prose into body sections.
+  process.stdout.write('\n' + bold('4. Fixing long frontmatter...') + '\n');
   runFrontmatterFix(config, { dryRun });
 
-  // Step 4: Rewrite hub rows whose printed status drifted from the plan they
+  // Step 5: 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');
+  process.stdout.write('\n' + bold('5. 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');
+  // Step 6: Sync dates from git
+  process.stdout.write('\n' + bold('6. Syncing dates from git...') + '\n');
   runTouch(['--git'], config, { dryRun });
 
-  // Step 6: Regenerate index. Heading always prints so numbering remains
+  // Step 7: Regenerate index. Heading always prints so numbering remains
   // contiguous even when `index.path` isn't configured.
-  process.stdout.write('\n' + bold('6. Regenerating index...') + '\n');
+  process.stdout.write('\n' + bold('7. Regenerating index...') + '\n');
   if (!config.indexPath) {
     process.stdout.write('No index path configured (skip).\n');
   } else if (dryRun) {
@@ -318,11 +324,11 @@ export function runDoctor(argv, config, opts = {}) {
     process.stdout.write('Index updated.\n');
   }
 
-  // Step 7: Clean up retired Claude Code command scaffolding. The per-repo
+  // Step 8: 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('7. Claude Code commands:') + '\n');
+  process.stdout.write('\n' + bold('8. Claude Code commands:') + '\n');
   if (dryRun) {
     const wouldRemove = removeGeneratedSlashCommands(config.repoRoot, { dryRun: true });
     if (wouldRemove.length === 0) {
@@ -343,8 +349,8 @@ export function runDoctor(argv, config, opts = {}) {
     }
   }
 
-  // Step 8: Show remaining check
-  const issueLabel = dryRun ? '8. Remaining issues in current tree (preview fixes above were not applied):' : '8. Remaining issues:';
+  // Step 9: Show remaining check
+  const issueLabel = dryRun ? '9. Remaining issues in current tree (preview fixes above were not applied):' : '9. Remaining issues:';
   process.stdout.write('\n' + bold(issueLabel) + '\n');
   const freshIndex = buildIndex(config);
   process.stdout.write(renderCheck(freshIndex, config));

package/src/extractors.mjs

@@ -1,3 +1,5 @@
+import { maskInlineCodeSpans } from './markdown-code-spans.mjs';
+
 export function extractFirstHeading(body) {
   return body.match(/^#\s+(.+)$/m)?.[1]?.trim() ?? null;
 }
@@ -49,9 +51,7 @@ export function extractBodyLinks(body) {
   // every one of them was also never checked for breakage. Masking to same-length
   // filler keeps the link matchable while still neutralizing a link that is
   // itself inside code (`[fake](x.md)` stays unmatched), and preserves offsets.
-  const stripped = body
-    .replace(/^```[\s\S]*?^```/gm, '')
-    .replace(/`[^`]+`/g, match => 'x'.repeat(match.length));
+  const stripped = maskInlineCodeSpans(body.replace(/^```[\s\S]*?^```/gm, ''));
   const links = [];
   // Supported inline destinations are a whitespace-free token (with Markdown
   // backslash escapes) or an angle-bracket destination, plus an optional

package/src/fix-membership.mjs

@@ -0,0 +1,132 @@
+import path from 'node:path';
+import { collectMembershipBackrefCandidates } from './hub-membership.mjs';
+import { planChildParentUpdate } from './parent-plan.mjs';
+import { mutateFileSet, MutationConflictError } from './atomic-mutation.mjs';
+import { authorizeManagedSweep } from './managed-path.mjs';
+import { isHubDoc } from './hub.mjs';
+import { bold, dim, green, yellow } from './color.mjs';
+import { die } from './util.mjs';
+
+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(match => `  ${match.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 fix-membership` with no argument to sweep every hub.');
+    }
+    paths.add(match.path);
+  }
+  return paths;
+}
+
+export function fixMembershipBackrefs(config, {
+  docs,
+  dryRun = false,
+  hubPaths = null,
+  quiet = false,
+  testHooks,
+} = {}) {
+  const planned = collectMembershipBackrefCandidates(docs, config, { hubPaths });
+  const updates = [];
+  const changes = [];
+  const skipped = [];
+  const guardByPath = new Map();
+
+  testHooks?.afterMembershipCandidates?.(planned);
+  for (const candidate of planned.candidates) {
+    if (candidate.childType !== 'plan') {
+      skipped.push({ path: candidate.childPath, hub: candidate.hubPath, reason: 'untyped-child' });
+      continue;
+    }
+    const update = planChildParentUpdate(candidate.childAbs, candidate.hubAbs, config);
+    if (update.raw !== candidate.childRaw) {
+      throw new MutationConflictError(`Child changed while membership repair was being prepared: ${candidate.childPath}`);
+    }
+    if (!update.update) {
+      skipped.push({
+        path: candidate.childPath,
+        hub: candidate.hubPath,
+        reason: update.reason,
+        ...(update.existing ? { existing: update.existing } : {}),
+      });
+      continue;
+    }
+    updates.push(update.update);
+    guardByPath.set(candidate.hubAbs, { path: candidate.hubAbs, expectedContent: candidate.hubRaw });
+    changes.push({
+      path: candidate.childPath,
+      hub: candidate.hubPath,
+      ref: update.ref,
+      sources: candidate.sources,
+    });
+  }
+
+  const ambiguous = planned.ambiguous.map(item => ({ path: item.childPath, hubs: item.hubPaths }));
+  const managed = [
+    ...updates.map(update => update.path),
+    ...guardByPath.values().map(guard => guard.path),
+  ];
+  if (managed.length) authorizeManagedSweep(managed, config, { kind: 'Membership repair source' });
+
+  testHooks?.afterMembershipPlan?.({ changes, ambiguous, skipped });
+  if (!dryRun && updates.length > 0) {
+    mutateFileSet({ updates, guards: [...guardByPath.values()] }, { repoRoot: config.repoRoot, testHooks });
+  }
+
+  const result = {
+    fixed: changes.length,
+    skipped: skipped.length + ambiguous.length,
+    ambiguous: ambiguous.length,
+    changes,
+    skippedDetails: skipped,
+    ambiguousDetails: ambiguous,
+  };
+
+  if (!quiet) {
+    const prefix = dryRun ? `${dim('[dry-run]')} ` : '';
+    for (const change of changes) {
+      process.stdout.write(`${prefix}${green(dryRun ? 'Would set' : 'Set')}: ${change.path} `
+        + `${dim(`parent_plan: ${change.ref} (stated by ${change.hub})`)}\n`);
+    }
+    for (const item of ambiguous) {
+      process.stdout.write(yellow(`Skipped ambiguous membership: ${item.path} is ranked by ${item.hubs.join(', ')}.`) + '\n');
+    }
+    for (const item of skipped) {
+      process.stdout.write(yellow(`Skipped membership repair: ${item.path} (${item.reason}).`) + '\n');
+    }
+    if (changes.length > 0) {
+      process.stdout.write(`\n${bold(`${prefix}${changes.length} membership back-reference${changes.length === 1 ? '' : 's'} ${dryRun ? 'would be repaired' : 'repaired'}.`)}\n`);
+    } else if (ambiguous.length === 0 && skipped.length === 0) {
+      process.stdout.write(green('Membership back-references are in sync.') + '\n');
+    }
+  }
+  return result;
+}
+
+export async function runFixMembership(argv, config, opts = {}) {
+  const { buildIndex } = await import('./index.mjs');
+  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 = fixMembershipBackrefs(config, {
+    docs,
+    dryRun: opts.dryRun,
+    hubPaths,
+    quiet: json,
+    testHooks: opts.testHooks,
+  });
+  if (json) {
+    process.stdout.write(`${JSON.stringify({ dryRun: Boolean(opts.dryRun), ...result }, null, 2)}\n`);
+  }
+  return result;
+}

package/src/hub-membership.mjs

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
-import { extractFrontmatter } from './frontmatter.mjs';
-import { resolveRefPath, toRepoPath } from './util.mjs';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { asString, normalizeStringList, resolveRefPath, toRepoPath } from './util.mjs';
 import { detectBodyRunlistRefs, isHubDoc } from './hub.mjs';
 import { resolveBodyLinkTarget } from './body-link.mjs';
 
@@ -38,6 +38,153 @@ import { resolveBodyLinkTarget } from './body-link.mjs';
 const ORPHAN_KIND = 'hub-membership-orphan';
 const BACKREF_KIND = 'hub-membership-backref';
 
+function quietDoc(status, type, config) {
+  return (config.lifecycle?.isTerminal?.(status, type)
+      ?? config.lifecycle?.terminalStatuses?.has(status))
+    || config.lifecycle?.skipsWarnings(status, type);
+}
+
+function configuredRunlist(parsed, config) {
+  const fields = [
+    ...(config.referenceFields?.bidirectional ?? []),
+    ...(config.referenceFields?.unidirectional ?? []),
+  ];
+  if (!fields.includes('runlist')) return { paths: [], directions: [] };
+  const paths = [];
+  const directions = [];
+  for (const entry of normalizeStringList(parsed.runlist)) {
+    const oneWay = entry.match(/^>\s*(.+)$/);
+    paths.push(oneWay ? oneWay[1].trim() : entry);
+    directions.push(oneWay ? 'one-way' : 'two-way');
+  }
+  return { paths, directions };
+}
+
+// One shared definition of mechanically repairable membership evidence. It
+// reads the exact hub/child bytes it returns so callers can bind those snapshots
+// into an atomic mutation: frontmatter `runlist:` (except `>` one-way entries)
+// plus the body order read by `dotmd runlist next`. Ordinary body links remain
+// pointers, and an existing parent — same or different — is never a candidate.
+export function collectMembershipBackrefCandidates(docs, config, { hubPaths = null } = {}) {
+  const byPath = new Map(docs.map(doc => [doc.path, doc]));
+  const evidence = new Map();
+
+  const resolve = (ref, dir) => {
+    const abs = resolveRefPath(String(ref).replace(/#.*$/, ''), dir, config.repoRoot);
+    return abs ? byPath.get(toRepoPath(abs, config.repoRoot)) ?? null : null;
+  };
+
+  for (const indexedHub of docs) {
+    if (hubPaths && !hubPaths.has(indexedHub.path)) continue;
+    // The index is the discovery snapshot. Re-read only docs it identified as
+    // hubs; current bytes below can still demote one safely, while a doc that
+    // became a hub after indexing is simply discovered on the next run.
+    if (!isHubDoc(indexedHub)) continue;
+    const hubAbs = path.join(config.repoRoot, indexedHub.path);
+    let hubRaw;
+    let hubFrontmatter;
+    let body;
+    try {
+      hubRaw = readFileSync(hubAbs, 'utf8');
+      ({ frontmatter: hubFrontmatter, body } = extractFrontmatter(hubRaw));
+    } catch { continue; }
+    const parsedHub = parseSimpleFrontmatter(hubFrontmatter);
+    const runlist = configuredRunlist(parsedHub, config);
+    const currentHub = {
+      ...indexedHub,
+      type: asString(parsedHub.type) ?? null,
+      status: asString(parsedHub.status) ?? null,
+      executionMode: asString(parsedHub.execution_mode) ?? null,
+      refFields: { ...indexedHub.refFields, runlist: runlist.paths },
+      refFieldDirections: { ...indexedHub.refFieldDirections, runlist: runlist.directions },
+    };
+    if (!isHubDoc(currentHub) || quietDoc(currentHub.status, currentHub.type, config)) continue;
+
+    const hubDir = path.dirname(hubAbs);
+    const runlistTargets = new Map();
+    for (let index = 0; index < runlist.paths.length; index++) {
+      const child = resolve(runlist.paths[index], hubDir);
+      if (!child || child.path === currentHub.path) continue;
+      runlistTargets.set(child.path, runlist.directions[index]);
+      if (runlist.directions[index] === 'one-way') continue;
+      addEvidence(child, 'frontmatter-runlist', runlist.paths[index]);
+    }
+    for (const ref of detectBodyRunlistRefs(body)) {
+      const child = resolve(ref, hubDir);
+      if (!child || child.path === currentHub.path) continue;
+      // A frontmatter entry owns this pair. A `>` entry is an explicit opt-out;
+      // a normal entry was already recorded above. Either way, body order must
+      // not create a second or contradictory authorization.
+      if (runlistTargets.has(child.path)) continue;
+      addEvidence(child, 'body-order', ref);
+    }
+
+    function addEvidence(indexedChild, source, ref) {
+      const childAbs = path.join(config.repoRoot, indexedChild.path);
+      let childRaw;
+      let childFrontmatter;
+      try {
+        childRaw = readFileSync(childAbs, 'utf8');
+        ({ frontmatter: childFrontmatter } = extractFrontmatter(childRaw));
+      } catch { return; }
+      const parsedChild = parseSimpleFrontmatter(childFrontmatter);
+      const childType = asString(parsedChild.type) ?? null;
+      const childStatus = asString(parsedChild.status) ?? null;
+      if (quietDoc(childStatus, childType, config)) return;
+      // Preserve the validator's brownfield behavior: an untyped legacy doc is
+      // still plan-like enough to diagnose. The writer applies the stricter
+      // type: plan boundary before it mutates anything.
+      if (childType && childType !== 'plan') return;
+      const childRunlist = configuredRunlist(parsedChild, config);
+      const currentChild = {
+        ...indexedChild,
+        type: childType,
+        status: childStatus,
+        executionMode: asString(parsedChild.execution_mode) ?? null,
+        refFields: { ...indexedChild.refFields, runlist: childRunlist.paths },
+      };
+      if (isHubDoc(currentChild)) return;
+      if (normalizeStringList(parsedChild.parent_plan).length > 0) return;
+
+      const key = `${indexedChild.path}\0${currentHub.path}`;
+      const existing = evidence.get(key);
+      if (existing) {
+        if (!existing.sources.includes(source)) existing.sources.push(source);
+        if (!existing.refs.includes(ref)) existing.refs.push(ref);
+        return;
+      }
+      evidence.set(key, {
+        child: indexedChild,
+        hub: currentHub,
+        childPath: indexedChild.path,
+        hubPath: currentHub.path,
+        childAbs,
+        hubAbs,
+        childRaw,
+        childType,
+        hubRaw,
+        sources: [source],
+        refs: [ref],
+      });
+    }
+  }
+
+  const byChild = new Map();
+  for (const item of evidence.values()) {
+    if (!byChild.has(item.childPath)) byChild.set(item.childPath, []);
+    byChild.get(item.childPath).push(item);
+  }
+  const candidates = [];
+  const ambiguous = [];
+  for (const [childPath, items] of byChild) {
+    if (items.length === 1) candidates.push(items[0]);
+    else ambiguous.push({ childPath, hubPaths: items.map(item => item.hubPath).sort(), evidence: items });
+  }
+  candidates.sort((a, b) => a.childPath.localeCompare(b.childPath));
+  ambiguous.sort((a, b) => a.childPath.localeCompare(b.childPath));
+  return { candidates, ambiguous, evidence: [...evidence.values()] };
+}
+
 export function checkHubMembershipDrift(docs, config) {
   const warnings = [];
   // Per-doc: warning suppression is type-scoped, so a status name quiet for one
@@ -119,37 +266,16 @@ export function checkHubMembershipDrift(docs, config) {
   // 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(hub)) 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(child)) 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 },
-      });
-    }
+  const { evidence } = collectMembershipBackrefCandidates(docs, config);
+  for (const item of evidence) {
+    if (!item.sources.includes('body-order')) continue;
+    const { child, hub } = item;
+    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, source: 'body-order' },
+    });
   }
 
   return warnings;

package/src/markdown-code-spans.mjs

@@ -0,0 +1,47 @@
+function maskRange(value, start, end) {
+  return value.slice(0, start)
+    + value.slice(start, end).replace(/[^\n]/g, 'x')
+    + value.slice(end);
+}
+
+// Markdown code spans close only on a backtick run of the same length as their
+// opener. The mask is deliberately the same length as the source so consumers
+// can inspect neutralized Markdown while applying any edits at source offsets.
+// `state` lets the conservative multiline behavior used by the reference
+// rewriter survive: after an unmatched opener, nothing is treated as prose
+// until a compatible closer appears.
+export function maskInlineCodeLine(line, state = { run: null }) {
+  const ranges = [];
+  const runs = [...line.matchAll(/`+/g)];
+  let index = 0;
+
+  if (state.run !== null) {
+    const closingIndex = runs.findIndex(candidate => candidate[0].length === state.run);
+    if (closingIndex === -1) return maskRange(line, 0, line.length);
+    const closing = runs[closingIndex];
+    ranges.push([0, closing.index + closing[0].length]);
+    index = closingIndex + 1;
+    state.run = null;
+  }
+
+  for (; index < runs.length; index++) {
+    const opening = runs[index];
+    const closingIndex = runs.findIndex((candidate, candidateIndex) =>
+      candidateIndex > index && candidate[0].length === opening[0].length);
+    if (closingIndex === -1) {
+      ranges.push([opening.index, line.length]);
+      state.run = opening[0].length;
+      break;
+    }
+    const closing = runs[closingIndex];
+    ranges.push([opening.index, closing.index + closing[0].length]);
+    index = closingIndex;
+  }
+
+  return ranges.reduceRight((masked, [start, end]) => maskRange(masked, start, end), line);
+}
+
+export function maskInlineCodeSpans(value) {
+  const state = { run: null };
+  return value.split('\n').map(line => maskInlineCodeLine(line, state)).join('\n');
+}

package/src/parent-plan.mjs

@@ -0,0 +1,58 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { extractFrontmatter, parseSimpleFrontmatter, replaceFrontmatter } from './frontmatter.mjs';
+import { MutationConflictError } from './atomic-mutation.mjs';
+import { escapeRegex, normalizeStringList, nowIso, resolveRefPath, toRepoPath } from './util.mjs';
+
+// Replace a top-level frontmatter field (its `key:` line + any indented
+// continuation block) with `serialized`, or append it when absent. Shared by
+// runlist mutations and the membership back-reference fixer so both paths
+// serialize `parent_plan:` identically.
+export function upsertFrontmatterField(fm, key, serialized) {
+  const re = new RegExp(`^${escapeRegex(key)}:.*(\\n[ \\t]+.*)*`, 'm');
+  if (re.test(fm)) return fm.replace(re, serialized);
+  return fm.replace(/\s*$/, '') + '\n' + serialized;
+}
+
+// Plan an atomic child-side `parent_plan:` update. The caller owns the evidence
+// that authorizes the relationship (a runlist entry or body-order row); this
+// helper owns the byte-level invariant: never clobber another parent, write a
+// child-relative forward-slash ref, bump `updated:`, and compare-and-swap the
+// exact child snapshot used to make the decision.
+export function planChildParentUpdate(childAbs, hubAbs, config) {
+  const raw = readFileSync(childAbs, 'utf8');
+  const { frontmatter: fmRaw } = extractFrontmatter(raw);
+  if (fmRaw == null) return { wrote: false, reason: 'missing-frontmatter', raw };
+  const fm = parseSimpleFrontmatter(fmRaw);
+  const childDir = path.dirname(childAbs);
+  const existingRefs = normalizeStringList(fm.parent_plan);
+  if (existingRefs.length > 0) {
+    const resolved = existingRefs.map(ref => resolveRefPath(ref, childDir, config.repoRoot));
+    if (existingRefs.length === 1 && resolved[0] === hubAbs) {
+      return { wrote: false, reason: 'already-set', raw };
+    }
+    return { wrote: false, reason: 'different-parent', existing: existingRefs.join(', '), raw };
+  }
+  const ref = path.relative(childDir, hubAbs).split(path.sep).join('/');
+  return {
+    wrote: true,
+    ref,
+    raw,
+    update: {
+      path: childAbs,
+      expectedContent: raw,
+      render: current => {
+        const { frontmatter: currentFm } = extractFrontmatter(current);
+        const currentParsed = parseSimpleFrontmatter(currentFm);
+        const currentParents = normalizeStringList(currentParsed.parent_plan);
+        if (currentParents.length > 0
+          && !(currentParents.length === 1 && resolveRefPath(currentParents[0], childDir, config.repoRoot) === hubAbs)) {
+          throw new MutationConflictError(`Child parent_plan changed while the membership mutation was being prepared: ${toRepoPath(childAbs, config.repoRoot)}`);
+        }
+        let updatedFm = upsertFrontmatterField(currentFm, 'parent_plan', `parent_plan: ${ref}`);
+        updatedFm = upsertFrontmatterField(updatedFm, 'updated', `updated: ${nowIso()}`);
+        return replaceFrontmatter(current, updatedFm);
+      },
+    },
+  };
+}

package/src/reference-planner.mjs

@@ -1,6 +1,7 @@
 import { realpathSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter } from './frontmatter.mjs';
+import { maskInlineCodeLine } from './markdown-code-spans.mjs';
 
 function slash(value) { return value.split(path.sep).join('/'); }
 
@@ -233,29 +234,37 @@ function rewriteDestination(raw, args) {
   return parsed.angle ? `<${rendered}>` : rendered;
 }
 
-function rewriteMarkdownSegment(segment, args) {
-  // Inline links: angle destinations, escaped whitespace, optional titles.
-  let next = segment.replace(/(\[[^\]]*\]\(\s*)(<[^>\n]+>|(?:\\.|[^\s()])+)(\s+(?:"[^"]*"|'[^']*'|\([^)]*\)))?(\s*\))/g,
-    (match, prefix, destination, title = '', close, offset) => {
-      let escapes = 0;
-      for (let index = offset - 1; index >= 0 && segment[index] === '\\'; index--) escapes++;
-      if (escapes % 2 === 1) return match;
-      const rewritten = rewriteDestination(destination, args);
-      return rewritten === destination ? match : `${prefix}${rewritten}${title}${close}`;
-    });
+function rewriteMarkdownLine(line, masked, args) {
+  const edits = [];
+  const inline = /(\[[^\]]*\]\(\s*)(<[^>\n]+>|(?:\\.|[^\s()])+)(\s+(?:"[^"]*"|'[^']*'|\([^)]*\)))?(\s*\))/g;
+  let match;
+  while ((match = inline.exec(masked)) !== null) {
+    let escapes = 0;
+    for (let index = match.index - 1; index >= 0 && line[index] === '\\'; index--) escapes++;
+    if (escapes % 2 === 1) continue;
+    const start = match.index + match[1].length;
+    const destination = line.slice(start, start + match[2].length);
+    const rewritten = rewriteDestination(destination, args);
+    if (rewritten !== destination) edits.push({ start, end: start + destination.length, value: rewritten });
+  }
+
   // Reference definitions preserve labels, spacing, destinations, and titles.
-  next = next.replace(/^(\s{0,3}\[[^\]]+\]:\s*)(<[^>\n]+>|(?:\\.|[^\s])+)(.*)$/,
-    (match, prefix, destination, tail) => {
-      const rewritten = rewriteDestination(destination, args);
-      return rewritten === destination ? match : `${prefix}${rewritten}${tail}`;
-    });
-  return next;
+  const definition = /^(\s{0,3}\[[^\]]+\]:\s*)(<[^>\n]+>|(?:\\.|[^\s])+)(.*)$/.exec(masked);
+  if (definition) {
+    const start = definition[1].length;
+    const destination = line.slice(start, start + definition[2].length);
+    const rewritten = rewriteDestination(destination, args);
+    if (rewritten !== destination) edits.push({ start, end: start + destination.length, value: rewritten });
+  }
+
+  return edits.sort((left, right) => right.start - left.start)
+    .reduce((next, edit) => next.slice(0, edit.start) + edit.value + next.slice(edit.end), line);
 }
 
 function rewriteMarkdown(body, args) {
   const lines = body.split('\n');
   let fence = null;
-  let inlineRun = null;
+  const inlineState = { run: null };
   let indentedCode = false;
   let htmlBlock = null;
   const containerContext = line => {
@@ -317,36 +326,7 @@ function rewriteMarkdown(body, args) {
       fence = { char: opener[1][0], length: opener[1].length, prefixes: container.prefixes };
       return line;
     }
-    let output = '';
-    let cursor = 0;
-    const runs = [...line.matchAll(/`+/g)];
-    let index = 0;
-    if (inlineRun !== null) {
-      const closingIndex = runs.findIndex(candidate => candidate[0].length === inlineRun);
-      if (closingIndex === -1) return line;
-      const closing = runs[closingIndex];
-      output += line.slice(0, closing.index + closing[0].length);
-      cursor = closing.index + closing[0].length;
-      index = closingIndex + 1;
-      inlineRun = null;
-    }
-    for (; index < runs.length; index++) {
-      const opening = runs[index];
-      const closingIndex = runs.findIndex((candidate, candidateIndex) => candidateIndex > index && candidate[0].length === opening[0].length);
-      if (closingIndex === -1) {
-        output += rewriteMarkdownSegment(line.slice(cursor, opening.index), args);
-        output += line.slice(opening.index);
-        inlineRun = opening[0].length;
-        cursor = line.length;
-        break;
-      }
-      const closing = runs[closingIndex];
-      output += rewriteMarkdownSegment(line.slice(cursor, opening.index), args);
-      output += line.slice(opening.index, closing.index + closing[0].length);
-      cursor = closing.index + closing[0].length;
-      index = closingIndex;
-    }
-    return output + rewriteMarkdownSegment(line.slice(cursor), args);
+    return rewriteMarkdownLine(line, maskInlineCodeLine(line, inlineState), args);
   }).join('\n');
 }
 

package/src/render.mjs

@@ -425,6 +425,15 @@ export function classifyIssueAction(issue) {
   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 (issue?.meta?.kind === 'hub-membership-backref') {
+    return { action: 'dotmd fix-membership', fixable: true, label: 'membership back-references' };
+  }
+  if (issue?.meta?.kind === 'hub-membership-orphan') {
+    return { action: `edit ${file}: add the child to the hub's meaningful list, or correct the child's parent_plan`, fixable: false, label: 'orphan membership claims' };
+  }
+  if (issue?.meta?.kind === 'hub-membership-conflict') {
+    return { action: `edit ${file}: reconcile its existing parent_plan with ${issue.meta.hub}`, fixable: false, label: 'membership parent conflicts' };
+  }
 
   if (/Missing frontmatter `status`/.test(message)) {
     return { action: `dotmd bulk-tag ${file}`, fixable: false, label: 'missing status' };

package/src/runlist.mjs

@@ -5,7 +5,6 @@ import { extractFirstHeading } from './extractors.mjs';
 import {
   asString,
   die,
-  escapeRegex,
   isArchivedPath,
   normalizeStringList,
   nowIso,
@@ -21,6 +20,7 @@ import { bold, cyan, dim, green, red, yellow } from './color.mjs';
 import { authorizeManagedDestination, authorizeManagedSource } from './managed-path.mjs';
 import { mutateFileSet, MutationConflictError } from './atomic-mutation.mjs';
 import { pickupFactsForDoc } from './pickup.mjs';
+import { planChildParentUpdate, upsertFrontmatterField } from './parent-plan.mjs';
 
 // A child is the runlist's NEXT PICKUP only when a session could start it right
 // now — i.e. its status is one `dotmd use` accepts. The "parked" statuses
@@ -433,17 +433,6 @@ function renderRunlist(hubRepoPath, children, opts = {}) {
 
 // --- `runlist add` mutation (Phase 1) -------------------------------------
 
-// Replace a top-level frontmatter field (its `key:` line + any indented
-// continuation block) with `serialized`, or append it when absent. The regex
-// mirrors what `mergeBodyFrontmatter` uses so the rewritten field keeps the
-// scaffold's shape. Shared by the block-array (`runlist:`) and scalar
-// (`parent_plan:`, `updated:`) writers below.
-function upsertFrontmatterField(fm, key, serialized) {
-  const re = new RegExp(`^${escapeRegex(key)}:.*(\\n[ \\t]+.*)*`, 'm');
-  if (re.test(fm)) return fm.replace(re, serialized);
-  return fm.replace(/\s*$/, '') + '\n' + serialized;
-}
-
 function serializeBlockArray(key, items) {
   if (items.length === 0) return `${key}:`;
   return `${key}:\n${items.map(v => `  - ${v}`).join('\n')}`;
@@ -499,37 +488,6 @@ function classifyChildToken(token, hubDir, hubSlug, pos, config) {
   };
 }
 
-// Set `parent_plan:` on an existing child to point back at the hub, unless it
-// already resolves to the hub. Never clobbers a parent_plan that points
-// elsewhere (warns instead — the child may belong to another hub). Returns
-// true when it wrote, false when it left the file alone.
-function planChildParentUpdate(childAbs, hubAbs, config) {
-  const raw = readFileSync(childAbs, 'utf8');
-  const { frontmatter: fmRaw } = extractFrontmatter(raw);
-  if (fmRaw == null) return { wrote: false };
-  const fm = parseSimpleFrontmatter(fmRaw);
-  const childDir = path.dirname(childAbs);
-  const existing = asString(fm.parent_plan);
-  if (existing) {
-    const resolved = resolveRefPath(existing, childDir, config.repoRoot);
-    if (resolved === hubAbs) return { wrote: false }; // already points at this hub
-    warn(`${toRepoPath(childAbs, config.repoRoot)} already has parent_plan: ${existing} — left as-is (not pointing it at the hub).`);
-    return { wrote: false };
-  }
-  const ref = path.relative(childDir, hubAbs).split(path.sep).join('/');
-  return { wrote: true, update: { path: childAbs, expectedContent: raw, render: current => {
-    const { frontmatter: currentFm } = extractFrontmatter(current);
-    const currentParsed = parseSimpleFrontmatter(currentFm);
-    const currentParent = asString(currentParsed.parent_plan);
-    if (currentParent && resolveRefPath(currentParent, childDir, config.repoRoot) !== hubAbs) {
-      throw new MutationConflictError(`Child parent_plan changed while the runlist mutation was being prepared: ${toRepoPath(childAbs, config.repoRoot)}`);
-    }
-    let updatedFm = upsertFrontmatterField(currentFm, 'parent_plan', `parent_plan: ${ref}`);
-    updatedFm = upsertFrontmatterField(updatedFm, 'updated', `updated: ${nowIso()}`);
-    return replaceFrontmatter(current, updatedFm);
-  } } };
-}
-
 // `dotmd runlist add <hub> <child...>` — append children to a hub's `runlist:`
 // array, scaffolding a `planned` stub for any bare-slug child that doesn't yet
 // exist (mirroring `dotmd new plan --runlist`) and wiring each child's
@@ -619,6 +577,9 @@ async function runRunlistAdd(positional, config, { dryRun, json, testHooks }) {
       if (!json) process.stdout.write(`${prefix}  ${green('+')} ${c.repoPath} ${dim('(scaffolded · planned)')}\n`);
     } else {
       const planned = planChildParentUpdate(c.abs, hubAbs, config);
+      if (planned.reason === 'different-parent') {
+        warn(`${c.repoPath} already has parent_plan: ${planned.existing} — left as-is (not pointing it at the hub).`);
+      }
       if (planned.update) updates.push(planned.update);
       const note = planned.wrote ? 'existing · parent_plan set' : 'existing';
       if (!json) process.stdout.write(`${prefix}  ${green('+')} ${c.repoPath} ${dim(`(${note})`)}\n`);

package/src/validate.mjs

@@ -453,6 +453,11 @@ export function checkRunlistBackPointers(docs, config) {
         path: child.path,
         level: 'warning',
         message: `appears in runlist of \`${hub.path}\` but \`parent_plan:\` does not point back at it. Add \`parent_plan: ${hub.path}\` so reverse-link tooling (pickup-card Related:, graph) stays consistent.`,
+        meta: {
+          kind: childParents.length === 0 ? 'hub-membership-backref' : 'hub-membership-conflict',
+          hub: hub.path,
+          source: 'frontmatter-runlist',
+        },
       });
     }
   }