runlist 0.0.0 → 0.94.1

package/src/host-integration.mjs

@@ -0,0 +1,339 @@
+// Installing runlist's integration into agent hosts other than Claude Code.
+//
+// Claude Code gets its integration through a real plugin (`plugins/runlist/`,
+// installed by `claude plugin`). OpenCode has no equivalent registry, but it
+// auto-discovers plugin files: it globs `{plugin,plugins}/*.{ts,js}` under the
+// global config dir and under a project's `.opencode/`, with no config entry
+// needed. So the integration ships as one generated file.
+//
+// It goes in the GLOBAL config dir, not per-repo. runlist retired per-repo
+// generated scaffolding once already (`.claude/commands`, see
+// claude-commands.mjs) because a file copied into every repo drifts from the
+// CLI that wrote it. One global file covers every repo and is refreshed by
+// `runlist update` in lockstep with the CLI.
+//
+// Writing outside the repo is why this is an explicit verb. `runlist doctor`
+// reports that the integration is missing and names the command; it never
+// installs. Passive commands touch nothing.
+
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { hostSessionSource } from './util.mjs';
+import { readEnv, stateDir } from './naming.mjs';
+import { LEGACY_PLUGIN_ID, planMarketplaceRepair } from './update.mjs';
+
+// New files carry the current banner. Every reader accepts both: files written
+// by dotmd-cli 0.78.0 and earlier carry the legacy banner, and those must stay
+// recognizable as generated forever, or an old install turns into a "foreign"
+// file that install/update/remove refuse to touch.
+export const GENERATED_MARKER = 'runlist-generated:';
+export const LEGACY_GENERATED_MARKER = 'dotmd-generated:';
+const GENERATED_MARKERS = [GENERATED_MARKER, LEGACY_GENERATED_MARKER];
+const PLUGIN_FILENAME = 'runlist.js';
+const LEGACY_PLUGIN_FILENAME = 'dotmd.js';
+const ASSET = path.resolve(fileURLToPath(import.meta.url), '..', '..', 'assets', 'opencode', 'plugin.js');
+
+// OpenCode's own resolution order for its global config directory. Verified
+// against the shipped binary: `OPENCODE_CONFIG_DIR` is an explicit override it
+// consults directly, and the default is the XDG location.
+export function opencodeConfigDir(env = process.env, homedir = os.homedir()) {
+  const explicit = env.OPENCODE_CONFIG_DIR?.trim();
+  if (explicit) return path.resolve(explicit);
+  const xdg = env.XDG_CONFIG_HOME?.trim();
+  return xdg ? path.join(path.resolve(xdg), 'opencode') : path.join(homedir, '.config', 'opencode');
+}
+
+// Both spellings are globbed, so an existing one is adopted rather than
+// creating a second plugin directory beside the user's own plugins.
+export function opencodePluginDir(configDir) {
+  for (const name of ['plugin', 'plugins']) {
+    const candidate = path.join(configDir, name);
+    if (existsSync(candidate)) return candidate;
+  }
+  return path.join(configDir, 'plugin');
+}
+
+export function opencodePluginPath(opts = {}) {
+  const { env = process.env, homedir = os.homedir(), dir } = opts;
+  if (dir) return path.join(path.resolve(dir), PLUGIN_FILENAME);
+  return path.join(opencodePluginDir(opencodeConfigDir(env, homedir)), PLUGIN_FILENAME);
+}
+
+function legacyOpencodePluginPath(opts = {}) {
+  const { env = process.env, homedir = os.homedir(), dir } = opts;
+  if (dir) return path.join(path.resolve(dir), LEGACY_PLUGIN_FILENAME);
+  return path.join(opencodePluginDir(opencodeConfigDir(env, homedir)), LEGACY_PLUGIN_FILENAME);
+}
+
+function banner(version) {
+  return [
+    `// ${GENERATED_MARKER}${version}`,
+    '// Generated by `runlist install opencode`. Refreshed by `runlist update`.',
+    '// Hand edits are overwritten — remove with `runlist install opencode --remove`.',
+    '',
+  ].join('\n');
+}
+
+export function renderOpencodePlugin(version) {
+  return banner(version) + readFileSync(ASSET, 'utf8');
+}
+
+// The banner a generated file carries — { marker, version } — or null when the
+// file is absent or carries neither banner. A file without a banner is the
+// user's own and is never written or removed — same rule the retired
+// slash-command scaffolding followed. The earliest banner in the file wins.
+export function readGeneratedBanner(filePath) {
+  let contents;
+  try { contents = readFileSync(filePath, 'utf8'); } catch { return null; }
+  let found = null;
+  for (const marker of GENERATED_MARKERS) {
+    const at = contents.indexOf(marker);
+    if (at >= 0 && (found === null || at < found.at)) found = { marker, at };
+  }
+  if (!found) return null;
+  const rest = contents.slice(found.at + found.marker.length);
+  return { marker: found.marker, version: rest.split('\n', 1)[0].trim() || null };
+}
+
+export function installedVersion(filePath) {
+  return readGeneratedBanner(filePath)?.version ?? null;
+}
+
+export function opencodeStatus(opts = {}) {
+  const { version, ...rest } = opts;
+  const filePath = opencodePluginPath(rest);
+  const legacyPath = legacyOpencodePluginPath(rest);
+  const currentExists = existsSync(filePath);
+  const oldExists = existsSync(legacyPath);
+  const generated = currentExists ? readGeneratedBanner(filePath) : null;
+  const oldGenerated = oldExists ? readGeneratedBanner(legacyPath) : null;
+  const installed = generated?.version ?? oldGenerated?.version ?? null;
+  const legacyGenerated = Boolean(oldGenerated);
+  const legacyBanner = generated?.marker === LEGACY_GENERATED_MARKER || oldGenerated?.marker === LEGACY_GENERATED_MARKER;
+  return {
+    path: filePath,
+    legacyPath,
+    exists: currentExists || oldExists,
+    version: installed,
+    // Generated legacy files migrate to runlist.js. Unmarked files remain user-owned.
+    foreign: (currentExists && !generated) || (!currentExists && oldExists && !oldGenerated),
+    foreignPath: currentExists && !generated ? filePath : oldExists && !oldGenerated ? legacyPath : null,
+    stale: installed !== null && ((version !== undefined && installed !== version) || legacyBanner || legacyGenerated),
+    legacyBanner,
+    legacyGenerated,
+  };
+}
+
+// Is OpenCode plausibly in use on this machine? Used only to decide whether to
+// mention the integration — never to install anything.
+export function opencodeDetected(opts = {}) {
+  const { env = process.env, homedir = os.homedir() } = opts;
+  if (env.OPENCODE || env.OPENCODE_PID) return true;
+  const configDir = opencodeConfigDir(env, homedir);
+  if (!existsSync(configDir)) return false;
+  try { return readdirSync(configDir).length > 0; } catch { return false; }
+}
+
+export function installOpencodePlugin(opts = {}) {
+  const { version, dryRun = false, force = false, ...rest } = opts;
+  const status = opencodeStatus({ version, ...rest });
+  if (status.foreign && !force) {
+    return { ...status, action: 'refused', reason: 'an OpenCode plugin file without a generated banner is already there — it was not written by runlist' };
+  }
+  if (status.exists && !status.stale && !status.foreign) {
+    return { ...status, action: 'current' };
+  }
+  const action = status.exists ? 'updated' : 'installed';
+  if (!dryRun) {
+    mkdirSync(path.dirname(status.path), { recursive: true });
+    writeFileSync(status.path, renderOpencodePlugin(version), 'utf8');
+    if (status.legacyGenerated) rmSync(status.legacyPath);
+  }
+  return { ...status, action, version };
+}
+
+// What identity does runlist actually see here, and can it tell this session
+// apart from its siblings? This report exists because the OpenCode breakage was
+// invisible until a verb failed: runlist looked for variables OpenCode never set,
+// and nothing surfaced that until `use` refused to run. Anyone on any host can
+// now check what runlist resolved instead of discovering it through a failure.
+export function describeSessionIdentity(opts = {}) {
+  const { env = process.env, homedir = os.homedir(), version } = opts;
+  const source = hostSessionSource(env);
+  const opencode = opencodeStatus({ env, homedir, version });
+  const underOpencode = Boolean(env.OPENCODE || env.OPENCODE_PID);
+
+  if (!source) {
+    return {
+      id: null, scope: 'none', source: null, host: null,
+      summary: 'no session identity — `use`, `set`, `baton` and `archive` fail closed',
+      advice: underOpencode
+        ? ['runlist install opencode', 'or set RUNLIST_SESSION_ID for this shell']
+        : ['set RUNLIST_SESSION_ID for this shell or host session', 'known hosts: runlist install'],
+    };
+  }
+
+  const advice = [];
+  // The distinction that matters: a process- or terminal-scoped id is shared by
+  // every session under it, so those sessions can release each other's plans.
+  if (source.scope === 'process' && source.host === 'OpenCode') {
+    advice.push(opencode.exists
+      // The plugin is there but this shell was spawned before it loaded, so it
+      // still carries the old identity — say so rather than leave a warning
+      // marker with no explanation.
+      ? 'restart OpenCode — this session predates the installed integration'
+      : 'runlist install opencode  — for a per-session identity');
+  } else if (source.scope === 'terminal') {
+    advice.push('every agent session in this terminal shares this id — set RUNLIST_SESSION_ID per session');
+  }
+  return {
+    id: source.id,
+    scope: source.scope,
+    source: source.variable,
+    host: source.host,
+    summary: source.scope === 'session'
+      ? `per-session identity from ${source.variable}`
+      : `${source.scope}-scoped identity from ${source.variable} — sessions sharing it can release each other's plans`,
+    advice,
+  };
+}
+
+// --- Telling the session it is running degraded -----------------------------
+//
+// Every other surface here has to be sought out: `doctor`, `install`, the npm
+// postinstall line. But the degraded mode is SILENT — with the OPENCODE_PID
+// fallback in place, `use`/`set`/`baton` all work, they just share one identity
+// across every session in the OpenCode process. Nobody goes looking for a
+// diagnostic about a thing that appears to work, so this comes to them.
+//
+// Warning, not error. Failing closed would undo the fallback that unblocked
+// OpenCode in the first place, and punish a setup that is working.
+//
+// Once per session per repo, via a marker under the gitignored .runlist/. Silent
+// under RUNLIST_NO_HINTS=1, the switch the repeat-failure hints already use.
+const NOTICE_DIR = 'notices';
+
+function noticeMarkerPath(repoRoot, key) {
+  const digest = createHash('sha256').update(key).digest('hex').slice(0, 32);
+  return path.join(stateDir(repoRoot), NOTICE_DIR, `${digest}`);
+}
+
+// Returns the notice text the first time it applies in a session, then null.
+// `record: false` answers without consuming the once-per-session budget.
+export function degradedIdentityNotice(repoRoot, opts = {}) {
+  const { env = process.env, homedir = os.homedir(), version, record = true } = opts;
+  if (readEnv('NO_HINTS', env) === '1') return null;
+  // Cheap env check first: a user on any other host pays nothing for this.
+  if (!env.OPENCODE && !env.OPENCODE_PID) return null;
+
+  const identity = describeSessionIdentity({ env, homedir, version });
+  if (identity.scope === 'session') return null;
+
+  const installed = opencodeStatus({ env, homedir, version }).exists;
+  const lines = installed
+    ? ['[runlist] This OpenCode session started before the runlist integration loaded, so its plan',
+      '        ownership is still process-scoped. Restart OpenCode to pick it up.']
+    : ['[runlist] OpenCode detected, runlist integration not installed — plan ownership is scoped to',
+      '        the OpenCode process, so another session in it can release plans this one claimed,',
+      '        and no session-start briefing runs. Fix once: runlist install opencode'];
+
+  if (!record) return lines.join('\n');
+  if (!repoRoot) return lines.join('\n');
+  const marker = noticeMarkerPath(repoRoot, `opencode:${identity.id}:${installed ? 'restart' : 'install'}`);
+  if (existsSync(marker)) return null;
+  try {
+    mkdirSync(path.dirname(marker), { recursive: true });
+    writeFileSync(marker, '', 'utf8');
+  } catch {
+    // Unwritable .runlist: say it once anyway rather than stay silent about a
+    // real ownership weakness. Worst case it repeats.
+  }
+  return lines.join('\n');
+}
+
+// --- Claude Code -----------------------------------------------------------
+//
+// Claude Code has a real plugin registry, so runlist drives `claude plugin`
+// rather than writing files. What it lacked was any CLI path to the FIRST
+// install: `runlist update` deliberately skips the plugin step when nothing is
+// installed ("runlist plugin not installed"), and the README's two slash commands
+// only work from inside a session. So a user who installed the CLI from npm had
+// no way to discover, from the CLI, that the plugin exists.
+
+export const CLAUDE_MARKETPLACE = 'reowens/runlist';
+export const CLAUDE_PLUGIN_ID = 'runlist@runlist';
+
+// Why `claude plugin marketplace add` can refuse a marketplace that is not
+// even registered: settings.json may still DECLARE it (extraKnownMarketplaces),
+// and Claude rejects an add whose source differs from that declaration in any
+// fetch-shaping field. runlist never writes that declaration and will not edit
+// it, so the most it can do is name the field.
+export function claudeMarketplaceRefusalHint(marketplace = 'runlist') {
+  return [
+    `Claude refused to register marketplace "${marketplace}". If ~/.claude/settings.json declares it under`,
+    `extraKnownMarketplaces, its source must be exactly {"source":"github","repo":"${CLAUDE_MARKETPLACE}"} —`,
+    'a stray "path", "ref" or header there makes the add fail and the installed plugin fail to load.',
+  ];
+}
+
+// Pure planner, mirroring planUpdate: the orchestration is unit-testable and
+// the side effects stay in the caller.
+export function planClaudeInstall({ installed, legacyInstalled, hasClaude, remove = false } = {}) {
+  if (remove) {
+    if (!installed) return [{ kind: 'skip', reason: 'runlist plugin is not installed' }];
+    const ids = installed.id === LEGACY_PLUGIN_ID || !legacyInstalled
+      ? [installed.id] : [installed.id, LEGACY_PLUGIN_ID];
+    return hasClaude
+      ? ids.map(id => ({ kind: 'run', cmd: ['claude', 'plugin', 'uninstall', id] }))
+      : [{ kind: 'manual', lines: ids.map(id => `/plugin uninstall ${id}`) }];
+  }
+  if (installed?.id === LEGACY_PLUGIN_ID) {
+    const lines = [`/plugin marketplace add ${CLAUDE_MARKETPLACE}`, `/plugin install ${CLAUDE_PLUGIN_ID}`, `/plugin uninstall ${LEGACY_PLUGIN_ID}`];
+    return hasClaude
+      ? [
+        { kind: 'run', cmd: ['claude', 'plugin', 'marketplace', 'add', CLAUDE_MARKETPLACE] },
+        { kind: 'run', cmd: ['claude', 'plugin', 'install', CLAUDE_PLUGIN_ID] },
+        { kind: 'run', cmd: ['claude', 'plugin', 'uninstall', LEGACY_PLUGIN_ID] },
+      ]
+      : [{ kind: 'manual', reason: 'Migrate the legacy Claude plugin', lines }];
+  }
+  if (installed?.id === CLAUDE_PLUGIN_ID && legacyInstalled) {
+    return hasClaude
+      ? [{ kind: 'run', cmd: ['claude', 'plugin', 'uninstall', LEGACY_PLUGIN_ID] }]
+      : [{ kind: 'manual', reason: 'Remove the legacy Claude plugin', lines: [`/plugin uninstall ${LEGACY_PLUGIN_ID}`] }];
+  }
+  // An install record whose marketplace registration is gone is not an
+  // installed plugin — Claude lists it as "failed to load". Skipping here with
+  // "already installed" left the user with no runlist verb that could repair it.
+  if (installed?.marketplaceRegistered === false) {
+    return planMarketplaceRepair(installed, { hasClaude, verb: 'update' })
+      .map(step => (step.kind === 'marketplace' || step.kind === 'plugin' ? { ...step, kind: 'run', step: step.kind } : step));
+  }
+  if (installed) return [{ kind: 'skip', reason: `runlist plugin already installed (${installed.version ?? 'unknown version'})` }];
+  // The marketplace has to be registered before the plugin resolves; adding one
+  // already present is a no-op, so this stays safe to re-run.
+  if (!hasClaude) {
+    return [{ kind: 'manual', lines: [`/plugin marketplace add ${CLAUDE_MARKETPLACE}`, `/plugin install ${CLAUDE_PLUGIN_ID}`] }];
+  }
+  return [
+    { kind: 'run', cmd: ['claude', 'plugin', 'marketplace', 'add', CLAUDE_MARKETPLACE] },
+    { kind: 'run', cmd: ['claude', 'plugin', 'install', CLAUDE_PLUGIN_ID] },
+  ];
+}
+
+export function removeOpencodePlugin(opts = {}) {
+  const { dryRun = false, force = false, ...rest } = opts;
+  const status = opencodeStatus(rest);
+  if (!status.exists) return { ...status, action: 'absent' };
+  if (status.foreign && !force) {
+    return { ...status, action: 'refused', reason: 'not a runlist-generated file' };
+  }
+  if (!dryRun) {
+    rmSync(status.path, { force: true });
+    if (status.legacyGenerated || force) rmSync(status.legacyPath, { force: true });
+  }
+  return { ...status, action: 'removed' };
+}

package/src/hub-membership.mjs

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