dotmd-cli 0.76.5 → 0.76.7

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.5",
+  "version": "0.76.7",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, lifecycle, and AI summaries.",
   "type": "module",
   "license": "MIT",

package/src/body-link.mjs

@@ -0,0 +1,40 @@
+import { existsSync, realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+function isWithin(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+
+// Markdown body links are filesystem paths relative to the document that
+// contains them. They deliberately do not inherit frontmatter references'
+// repo-root fallback: that fallback can make a broken Markdown link look valid.
+export function resolveBodyLinkTarget(href, docDir, repoRoot) {
+  if (!href) return { ok: false, reason: 'missing' };
+
+  const root = path.resolve(repoRoot);
+  const candidate = path.resolve(docDir, href);
+  if (!isWithin(root, candidate)) return { ok: false, reason: 'outside-repo' };
+  if (!existsSync(candidate)) return { ok: false, reason: 'missing' };
+
+  let canonicalRoot;
+  let canonicalTarget;
+  try {
+    canonicalRoot = realpathSync(root);
+    canonicalTarget = realpathSync(candidate);
+  } catch {
+    return { ok: false, reason: 'unreadable' };
+  }
+  if (!isWithin(canonicalRoot, canonicalTarget)) return { ok: false, reason: 'outside-repo' };
+
+  try {
+    const stat = statSync(canonicalTarget);
+    if (!stat.isFile() && !stat.isDirectory()) return { ok: false, reason: 'unsupported-target' };
+  } catch {
+    return { ok: false, reason: 'unreadable' };
+  }
+  // Return the authored lexical route after using the canonical route only for
+  // containment. Callers index documents by their repo-relative spelling (and
+  // may intentionally include an in-repo symlink alias).
+  return { ok: true, path: candidate, realPath: canonicalTarget };
+}

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

@@ -53,16 +53,28 @@ export function extractBodyLinks(body) {
     .replace(/^```[\s\S]*?^```/gm, '')
     .replace(/`[^`]+`/g, match => 'x'.repeat(match.length));
   const links = [];
-  // Match [text](path.md) or [text](path.md#anchor), skip images (preceded by !)
-  const regex = /(?<!!)\[([^\]]+)\]\(([^)]+\.md(?:#[^)]*)?)\)/g;
+  // Supported inline destinations are a whitespace-free token (with Markdown
+  // backslash escapes) or an angle-bracket destination, plus an optional
+  // quoted/parenthesized title. Reference links, HTML links, and nested
+  // unescaped parentheses remain deliberately outside this lightweight parser.
+  const regex = /(?<!!)\[([^\]\n]+)\]\(\s*(<[^>\n]+>|(?:\\.|[^\s()])+)(?:\s+(?:"[^"\n]*"|'[^'\n]*'|\([^\n)]*\)))?\s*\)/g;
   let match;
   while ((match = regex.exec(stripped)) !== null) {
-    const href = match[2];
-    // Skip external URLs
-    if (/^https?:\/\//i.test(href)) continue;
-    // Strip anchor fragment for path resolution
-    const cleanHref = href.replace(/#.*$/, '');
-    links.push({ text: match[1], href: cleanHref });
+    const destination = match[2];
+    const angle = destination.startsWith('<') && destination.endsWith('>');
+    const rawHref = angle ? destination.slice(1, -1) : destination;
+    // These destinations are meaningful to a renderer or another application,
+    // not portable repo-local filesystem targets.
+    if (/^(?:#|\/|[a-z][a-z\d+.-]*:)/i.test(rawHref)) continue;
+
+    const rawPath = rawHref.replace(/[?#].*$/, '');
+    if (!rawPath) continue;
+    const unescaped = rawPath.replace(/\\([\s()[\]<>])/g, '$1');
+    let href;
+    try { href = decodeURIComponent(unescaped); }
+    catch { href = unescaped; }
+    const targetKind = /\.md$/i.test(href) ? 'document' : 'file';
+    links.push({ text: match[1], rawHref, href, targetKind, angle });
   }
   return links;
 }

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/fix-refs.mjs

@@ -102,7 +102,9 @@ export function fixBrokenRefs(config, opts = {}) {
 
   for (const doc of index.docs) {
     const brokenBodyWarnings = doc.warnings.filter(w =>
-      w.message.startsWith('body link') && w.message.includes('does not resolve')
+      w.meta?.kind === 'body-link-resolution'
+        && w.meta?.targetKind === 'document'
+        && w.meta?.reason === 'missing'
     );
     if (!brokenBodyWarnings.length) continue;
 
@@ -112,12 +114,14 @@ export function fixBrokenRefs(config, opts = {}) {
     let newBody = body;
     const docDir = path.dirname(absPath);
     const bodyFixes = [];
+    const seenBodyTargets = new Set();
 
     for (const warn of brokenBodyWarnings) {
-      const match = warn.message.match(/body link `([^`]+)` does not resolve/);
-      if (!match) continue;
-
-      const brokenHref = match[1];
+      const brokenHref = warn.meta.relPath;
+      const rawHref = warn.meta.rawHref ?? brokenHref;
+      const targetKey = `${warn.meta.angle ? 'angle' : 'plain'}:${rawHref}`;
+      if (seenBodyTargets.has(targetKey)) continue;
+      seenBodyTargets.add(targetKey);
       const brokenBasename = path.basename(brokenHref);
 
       if (duplicateBasenames.has(brokenBasename)) continue;
@@ -127,14 +131,21 @@ export function fixBrokenRefs(config, opts = {}) {
       const correctHref = path.relative(docDir, resolved).split(path.sep).join('/');
       if (correctHref === brokenHref) continue;
 
+      const suffixAt = rawHref.search(/[?#]/);
+      const suffix = suffixAt === -1 ? '' : rawHref.slice(suffixAt);
+      const renderedHref = warn.meta.angle
+        ? `<${correctHref}${suffix}>`
+        : `${correctHref.replace(/([\s()[\]<>])/g, '\\$1')}${suffix}`;
       const linkRegex = new RegExp(
-        '(?<!!)\\[([^\\]]+)\\]\\(' + escapeRegex(brokenHref) + '(#[^)]*)?\\)',
+        '(\\]\\(\\s*)' + (warn.meta.angle ? '<' : '') + escapeRegex(rawHref) + (warn.meta.angle ? '>' : '') + '(?=\\s|\\))',
         'g'
       );
-      newBody = newBody.replace(linkRegex, (_, text, anchor) =>
-        `[${text}](${correctHref}${anchor ?? ''})`
-      );
-      bodyFixes.push({ brokenHref, correctHref });
+      let replacements = 0;
+      newBody = newBody.replace(linkRegex, (_, prefix) => {
+        replacements++;
+        return `${prefix}${renderedHref}`;
+      });
+      for (let i = 0; i < replacements; i++) bodyFixes.push({ brokenHref, correctHref });
     }
 
     if (bodyFixes.length > 0 && newBody !== body) {

package/src/hub-membership.mjs

@@ -1,8 +1,9 @@
 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';
 
 // 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
@@ -37,11 +38,159 @@ import { detectBodyRunlistRefs, isHubDoc } from './hub.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
   // type stays loud for another that declared the same name.
-  const quiet = (d) => config.lifecycle?.terminalStatuses?.has(d.status)
+  const quiet = (d) => (config.lifecycle?.isTerminal?.(d.status, d.type)
+      ?? config.lifecycle?.terminalStatuses?.has(d.status))
     || config.lifecycle?.skipsWarnings(d.status, d.type);
   const byPath = new Map(docs.map(doc => [doc.path, doc]));
   const refFields = [
@@ -54,6 +203,11 @@ export function checkHubMembershipDrift(docs, config) {
     const abs = resolveRefPath(String(ref).replace(/#.*$/, ''), dir, config.repoRoot);
     return abs ? byPath.get(toRepoPath(abs, config.repoRoot)) ?? null : null;
   };
+  const resolveBody = (link, dir) => {
+    if (link.targetKind && link.targetKind !== 'document') return null;
+    const result = resolveBodyLinkTarget(link.href, dir, config.repoRoot);
+    return result.ok ? byPath.get(toRepoPath(result.path, 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
@@ -68,7 +222,7 @@ export function checkHubMembershipDrift(docs, config) {
       }
     }
     for (const link of (hub.bodyLinks ?? [])) {
-      const target = resolve(link.href, dir);
+      const target = resolveBody(link, dir);
       if (target) known.add(target.path);
     }
     return known;
@@ -112,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/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/prompts.mjs

@@ -118,7 +118,7 @@ function findPromptTarget(promptDoc, config) {
   }
 
   const links = promptDoc.bodyLinks ?? [];
-  const mdLink = links.find(l => /\.md(?:#|$)/.test(l.href ?? ''));
+  const mdLink = links.find(l => l.targetKind === 'document');
   if (mdLink) return resolveBodyLink(mdLink.href, promptDoc.path);
   return null;
 }

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' };
@@ -454,7 +463,13 @@ export function classifyIssueAction(issue) {
   if (/`modules` is required/.test(message)) {
     return { action: `edit ${file} modules: or run dotmd lint --fix if scaffolded empty`, fixable: false, label: 'module metadata' };
   }
-  if (/entry `.*` does not resolve|body link `.*` does not resolve/.test(message)) {
+  if (issue?.meta?.kind === 'body-link-resolution') {
+    if (issue.meta.targetKind === 'document' && issue.meta.reason === 'missing') {
+      return { action: 'dotmd fix-refs --dry-run', fixable: true, label: 'document links' };
+    }
+    return { action: `edit ${file}: correct the linked file, asset, or directory`, fixable: false, label: 'file links' };
+  }
+  if (/entry `.*` does not resolve/.test(message)) {
     return { action: 'dotmd fix-refs --dry-run', fixable: true, label: 'references' };
   }
 

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/sync-status.mjs

@@ -1,9 +1,10 @@
 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 { die, isArchivedPath, toRepoPath } from './util.mjs';
 import { cyan, dim, green, red, yellow } from './color.mjs';
 import { authorizeManagedSweep } from './managed-path.mjs';
+import { resolveBodyLinkTarget } from './body-link.mjs';
 import {
   MARKER_CLOSE,
   MARKER_OPEN,
@@ -21,8 +22,8 @@ import {
 // 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
+// rowed in a plan hub is judged by the doc vocabulary), the strict Markdown
+// body-link resolver, 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
@@ -79,7 +80,7 @@ function truncate(text, max = 60) {
 // 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
+  // The filesystem resolver 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
@@ -91,7 +92,8 @@ export function collectHubStatusRows(docs, config, { hubPaths = null } = {}) {
   }
   // Per-doc: warning suppression is type-scoped, so a status name quiet for one
   // type stays loud for another that declared the same name.
-  const quiet = (d) => config.lifecycle?.terminalStatuses?.has(d.status)
+  const quiet = (d) => (config.lifecycle?.isTerminal?.(d.status, d.type)
+      ?? config.lifecycle?.terminalStatuses?.has(d.status))
     || config.lifecycle?.skipsWarnings(d.status, d.type);
   const out = [];
 
@@ -108,11 +110,11 @@ export function collectHubStatusRows(docs, config, { hubPaths = null } = {}) {
     const rows = [];
     for (const row of scanHubStatusRows(body)) {
       const href = row.ref.replace(/#.*$/, '');
-      const abs = resolveRefPath(href, hubDir, config.repoRoot);
+      const resolution = resolveBodyLinkTarget(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);
+      if (!resolution.ok) continue;
+      const repoPath = toRepoPath(resolution.path, config.repoRoot);
       const target = docByPath.get(repoPath) ?? docByFoldedPath.get(repoPath.toLowerCase()) ?? null;
       if (!target || target.path === hub.path) continue;
       const actual = effectiveStatus(target, config);

package/src/validate.mjs

@@ -3,6 +3,7 @@ import { asString, resolveRefPath, suggestCandidates } from './util.mjs';
 import { getGitLastModified, getGitLastModifiedBatch, getGitLastSubstantiveModifiedBatch } from './git.mjs';
 import { toRepoPath } from './util.mjs';
 import { detectMarker, isPhaseHeading, phaseMarkerConflict, walkSections } from './section.mjs';
+import { resolveBodyLinkTarget } from './body-link.mjs';
 
 const NOW = new Date();
 
@@ -277,12 +278,24 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
 
     // Validate body links resolve to existing files
     for (const link of (doc.bodyLinks || [])) {
-      if (!resolveRefPath(link.href, docDir, config.repoRoot)) {
+      const resolution = resolveBodyLinkTarget(link.href, docDir, config.repoRoot);
+      if (!resolution.ok) {
+        const shownHref = link.rawHref ?? link.href;
         doc.warnings.push({
           path: doc.path,
           level: 'warning',
-          message: `body link \`${link.href}\` does not resolve to an existing file.`,
-          meta: { kind: 'ref-resolution', field: 'body-link', relPath: link.href },
+          message: resolution.reason === 'outside-repo'
+            ? `body link \`${shownHref}\` escapes the repository.`
+            : `body link \`${shownHref}\` does not resolve to an existing file or directory.`,
+          meta: {
+            kind: 'body-link-resolution',
+            field: 'body-link',
+            relPath: link.href,
+            rawHref: shownHref,
+            targetKind: link.targetKind ?? 'document',
+            angle: link.angle === true,
+            reason: resolution.reason,
+          },
         });
       }
     }
@@ -326,7 +339,9 @@ function candidatePathsForType(docs, type) {
 // name implies one (e.g. `related_plans` → plans only).
 export function enrichRefErrorSuggestions(docs, config) {
   const enrich = (entry) => {
-    if (!entry?.meta || entry.meta.kind !== 'ref-resolution') return;
+    if (!entry?.meta || !['ref-resolution', 'body-link-resolution'].includes(entry.meta.kind)) return;
+    if (entry.meta.kind === 'body-link-resolution'
+      && (entry.meta.targetKind !== 'document' || entry.meta.reason !== 'missing')) return;
     if (entry._suggested) return;
     const inferred = inferRefFieldType(entry.meta.field);
     const candidates = candidatePathsForType(docs, inferred);
@@ -438,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',
+        },
       });
     }
   }