runlist 0.0.0 → 0.94.1

package/src/validate.mjs

@@ -0,0 +1,794 @@
+import path from 'node:path';
+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';
+import { getStageDefinitions, readPlanStage } from './stages.mjs';
+import { assessmentIssues } from './yardstick.mjs';
+
+const NOW = new Date();
+
+// Type-conventional dirs are the directories where `runlist new <type>` lands
+// live (non-archive) docs of that type. Built-ins use `dir` ('plans'/'prompts')
+// and `targetRoot`. In flat-array root configs (e.g. root: ['docs/plans',
+// 'docs/prompts']), the root itself is a type-conventional dir; in default
+// single-root configs (root: 'docs'), the type-conventional dirs are
+// '<root>/plans' and '<root>/prompts'. This helper builds the union so the
+// archive-drift check works for both layouts. Custom user templates with
+// their own `dir` would extend this; we hard-code the built-in dir names.
+const BUILTIN_TYPE_DIR_NAMES = ['plans', 'prompts'];
+
+function liveTypeDirsForRoots(config) {
+  const set = new Set();
+  const roots = config.docsRoots || (config.docsRoot ? [config.docsRoot] : []);
+  // F15: filed-status bucket dirs are "live" too — a doc whose status is
+  // an archive status but whose parent dir is a filed bucket should still
+  // trigger the archive-drift warning (the file needs to move into the
+  // archive bucket).
+  const filedDirs = [...((config.lifecycle?.filedStatuses?.values?.()) ?? [])];
+  for (const root of roots) {
+    const rootRel = path.relative(config.repoRoot, root).split(path.sep).join('/');
+    // The root itself is a live dir (covers flat-array layouts where the
+    // root IS the type-container).
+    set.add(rootRel);
+    // Each builtin type-dir joined to the root (covers single-root layouts
+    // where 'docs' contains 'docs/plans' and 'docs/prompts' subdirs).
+    for (const dirName of BUILTIN_TYPE_DIR_NAMES) {
+      // Skip if root already ends in this name (no double-nesting like
+      // 'docs/prompts/prompts').
+      if (path.basename(rootRel) === dirName) continue;
+      set.add(rootRel ? `${rootRel}/${dirName}` : dirName);
+    }
+    // User template dirs from config (extend the set with whatever live
+    // dirs custom types declare).
+    for (const tmpl of Object.values(config.raw?.templates ?? {})) {
+      if (!tmpl || typeof tmpl !== 'object') continue;
+      if (tmpl.dir && path.basename(rootRel) !== tmpl.dir) {
+        set.add(rootRel ? `${rootRel}/${tmpl.dir}` : tmpl.dir);
+      }
+    }
+    // F15: filed bucket dirs joined to each root.
+    for (const dirName of filedDirs) {
+      if (path.basename(rootRel) === dirName) continue;
+      set.add(rootRel ? `${rootRel}/${dirName}` : dirName);
+      for (const typeDir of BUILTIN_TYPE_DIR_NAMES) {
+        if (path.basename(rootRel) === typeDir) continue;
+        const typeRoot = rootRel ? `${rootRel}/${typeDir}` : typeDir;
+        set.add(`${typeRoot}/${dirName}`);
+      }
+    }
+  }
+  return set;
+}
+
+function isValidStatus(status, root, config, type) {
+  // When a doc declares a known type, that type's status set is authoritative.
+  // Falling through to the global union (across all types) would allow a
+  // `type: prompt` doc to carry `status: active` just because `active` is valid
+  // for plans — defeating the purpose of type-scoped vocabularies.
+  if (type) {
+    const typeSet = config.typeStatuses?.get(type);
+    if (typeSet) return typeSet.has(status);
+  }
+  const rootSet = config.rootValidStatuses?.get(root);
+  if (rootSet) return rootSet.has(status);
+  return config.validStatuses.has(status);
+}
+
+export function validateDoc(doc, frontmatter, headingTitle, config) {
+  if (doc.type === 'plan') {
+    const archived = config.lifecycle.archiveStatuses.has(doc.status) || doc.path.split('/').includes(config.archiveDir);
+    for (const message of assessmentIssues(frontmatter, archived)) {
+      doc.warnings.push({ path: doc.path, level: 'warning', message });
+    }
+    const stage = readPlanStage(frontmatter.ships);
+    const milestones = (config.raw ?? config).taxonomy?.milestones;
+    if (stage.invalid) {
+      doc.errors.push({ path: doc.path, level: 'error', message: '`ships` must be a single stage string on one line without NUL characters; leave it blank or omit it for Unset.' });
+    } else if (stage.word && Array.isArray(milestones) && !getStageDefinitions(config).some(definition => definition.word === stage.word)) {
+      doc.errors.push({ path: doc.path, level: 'error', message: `Unknown stage \`${stage.word}\` in \`ships\`; expected a configured \`taxonomy.milestones\` value.` });
+    }
+  }
+
+  // Validate type field
+  if (doc.type && config.validTypes && !config.validTypes.has(doc.type)) {
+    doc.warnings.push({ path: doc.path, level: 'warning', message: `Unknown type \`${doc.type}\`; expected one of: ${[...config.validTypes].join(', ')}.` });
+  }
+
+  if (!doc.status) {
+    doc.errors.push({ path: doc.path, level: 'error', message: 'Missing frontmatter `status`.' });
+  } else if (!isValidStatus(doc.status, doc.root, config, doc.type)) {
+    const typeSet = doc.type && config.typeStatuses?.get(doc.type);
+    const rootSet = config.rootValidStatuses?.get(doc.root);
+    // When the doc has a known type, scope the error hint to that type's vocab.
+    // Otherwise fall back to root-specific or global validStatuses.
+    const hint = typeSet
+      ? `valid for type \`${doc.type}\`: ${[...typeSet].join(', ')}`
+      : `valid: ${[...(rootSet ?? config.validStatuses)].join(', ')}`;
+    doc.errors.push({ path: doc.path, level: 'error', message: `Unknown status \`${doc.status}\`; ${hint}.` });
+  }
+
+  const knownStatus = isValidStatus(doc.status, doc.root, config, doc.type);
+
+  if (knownStatus && !config.lifecycle.skipsWarnings(doc.status, doc.type) && !doc.updated) {
+    doc.errors.push({ path: doc.path, level: 'error', message: 'Missing frontmatter `updated` for non-archived doc.' });
+  }
+
+  if (knownStatus && doc.auditLevel && doc.auditLevel !== 'none' && !doc.audited) {
+    doc.errors.push({ path: doc.path, level: 'error', message: '`audit_level` is set without `audited`.' });
+  }
+
+  if (knownStatus && doc.auditLevel === 'none' && doc.audited) {
+    doc.errors.push({ path: doc.path, level: 'error', message: '`audit_level: none` cannot be combined with `audited`.' });
+  }
+
+  if (Object.prototype.hasOwnProperty.call(frontmatter, 'blockers') && !Array.isArray(frontmatter.blockers)) {
+    doc.errors.push({ path: doc.path, level: 'error', message: '`blockers` must be a YAML list when present.' });
+  }
+
+  if (Object.prototype.hasOwnProperty.call(frontmatter, 'blocked_by') && !Array.isArray(frontmatter.blocked_by)) {
+    doc.errors.push({ path: doc.path, level: 'error', message: '`blocked_by` must be a YAML list when present.' });
+  }
+
+  if (Object.prototype.hasOwnProperty.call(frontmatter, 'surfaces') && !Array.isArray(frontmatter.surfaces)) {
+    doc.errors.push({ path: doc.path, level: 'error', message: '`surfaces` must be a YAML list when present.' });
+  }
+
+  if (Object.prototype.hasOwnProperty.call(frontmatter, 'modules') && !Array.isArray(frontmatter.modules)) {
+    doc.errors.push({ path: doc.path, level: 'error', message: '`modules` must be a YAML list when present.' });
+  }
+
+  // modules-required gate: only fires when the project has actively declared
+  // a module taxonomy (`taxonomy.modules` is an array). Repos with no product
+  // modules (CLIs, dev tooling, single-domain apps) shouldn't be forced to
+  // sprinkle `modules: [none]` on every plan as a sentinel. Mirrors the
+  // long-standing `taxonomy.surfaces` opt-in semantics.
+  if (config.validModules && config.moduleRequiredStatuses.has(doc.status) && !doc.modules?.length) {
+    doc.errors.push({ path: doc.path, level: 'error', message: '`modules` is required for this status; declare a real module from `taxonomy.modules`, or `none` as the explicit no-module sentinel.' });
+  }
+
+  if (config.validSurfaces && !config.lifecycle.skipsWarnings(doc.status, doc.type)) {
+    const knownSurfaces = [...config.validSurfaces];
+    for (const surface of doc.surfaces) {
+      if (!config.validSurfaces.has(surface)) {
+        const suggestions = suggestCandidates(surface, knownSurfaces, 3);
+        const hint = suggestions.length
+          ? ` Did you mean: ${suggestions.map(s => `\`${s}\``).join(' | ')}?`
+          : '';
+        doc.warnings.push({
+          path: doc.path,
+          level: 'warning',
+          message: `Unknown surface \`${surface}\`; expected a known surface taxonomy value.${hint} Run \`runlist surfaces\` to list all valid values.`,
+        });
+      }
+    }
+  }
+
+  // F18: Singular `module:` / `surface:` are deprecated in favor of plural arrays.
+  // The reader still merges singular into plural transparently (back-compat),
+  // but new usage should always go through the plural form. The migration
+  // target is inlined in the message so `runlist lint --fix` users see exactly
+  // what they'll end up with — and so non-fix readers can hand-migrate.
+  // Suppress for archived/terminal docs (same noise-control rule as F2).
+  if (!config.lifecycle.skipsWarnings(doc.status, doc.type)) {
+    for (const { singular, plural } of [{ singular: 'module', plural: 'modules' }, { singular: 'surface', plural: 'surfaces' }]) {
+      const singularValue = frontmatter[singular];
+      if (!Object.prototype.hasOwnProperty.call(frontmatter, singular)) continue;
+      const rawPluralValue = frontmatter[plural];
+      const pluralValue = Array.isArray(rawPluralValue)
+        ? rawPluralValue
+        : rawPluralValue === undefined ? [] : [rawPluralValue];
+      const singularValues = Array.isArray(singularValue) ? singularValue : [singularValue];
+      const merged = [];
+      for (const v of [...singularValues, ...pluralValue]) {
+        if (typeof v === 'string' && v && !merged.includes(v)) merged.push(v);
+      }
+      const target = `${plural}: [${merged.map(v => JSON.stringify(v)).join(', ')}]`;
+      const autoFixableString = value => typeof value === 'string' && !/(^|\s)#/.test(value);
+      const autoFixable = singularValues.every(autoFixableString)
+        && pluralValue.every(autoFixableString);
+      const guidance = autoFixable
+        ? `use \`${target}\`. Run \`runlist lint --fix\` to migrate.`
+        : `use a \`${plural}:\` YAML list. Remove the deprecated \`${singular}:\` block manually and preserve all of its values.`;
+      doc.warnings.push({
+        path: doc.path,
+        level: 'warning',
+        message: `\`${singular}:\` (singular) is deprecated — ${guidance}`,
+      });
+    }
+  }
+
+  // Prompts are intentionally body-only one-shot artifacts: the slug names the
+  // prompt, the body IS the payload. Forcing a `title` or blockquote `summary`
+  // is friction the prompt format was designed around.
+  const skipTitleSummary = doc.type === 'prompt';
+
+  if (!skipTitleSummary && !headingTitle && !asString(frontmatter.title)) {
+    doc.warnings.push({ path: doc.path, level: 'warning', message: 'Missing `title` and no H1 found for fallback.' });
+  }
+
+  if (!skipTitleSummary && !config.lifecycle.skipsWarnings(doc.status, doc.type) && !asString(frontmatter.summary) && !doc.summary) {
+    doc.warnings.push({ path: doc.path, level: 'warning', message: 'Missing `summary` and no blockquote fallback found.' });
+  }
+
+  // Determine which statuses should have current_state and next_step (plans only, not docs/research)
+  const isPlanWork = knownStatus && doc.status && (!doc.type || doc.type === 'plan')
+    && !config.lifecycle.terminalStatuses.has(doc.status) && !config.lifecycle.skipsWarnings(doc.status, doc.type);
+
+  if (isPlanWork && !asString(frontmatter.current_state)) {
+    doc.warnings.push({ path: doc.path, level: 'warning', message: 'Missing `current_state`; index output is using a fallback or placeholder.' });
+  }
+
+  if (isPlanWork && doc.status !== 'blocked' && !asString(frontmatter.next_step)) {
+    doc.warnings.push({ path: doc.path, level: 'warning', message: 'Missing `next_step`; command output will omit a clear immediate action.' });
+  }
+
+  // Archived plans must have a ## Closeout section
+  if (config.lifecycle.archiveStatuses.has(doc.status) && doc.type === 'plan' && !doc.hasCloseout) {
+    doc.warnings.push({ path: doc.path, level: 'warning', message: 'Archived plan missing `## Closeout` section.' });
+  }
+
+  // Archive drift: a doc with an archive-flagged status (`status: archived` by
+  // default) whose parent dir is a "live" type-conventional location is
+  // misplaced — `runlist archive` would have moved it under `<that>/archiveDir/`.
+  // Without this check, default `runlist plans` / `runlist prompts` views silently
+  // drop the file (because they exclude archived paths), and the user gets no
+  // signal it exists but is invisible. Nested intentional content (e.g.,
+  // `docs/plans/audit/<file>.md`) is in a non-conventional subdir and exempt.
+  if (config.lifecycle.archiveStatuses.has(doc.status)) {
+    const parentDir = path.dirname(doc.path);
+    const liveDirs = liveTypeDirsForRoots(config);
+    if (liveDirs.has(parentDir)) {
+      const expected = `${parentDir}/${config.archiveDir}/${path.basename(doc.path)}`;
+      doc.errors.push({
+        path: doc.path,
+        level: 'error',
+        message: `\`status: ${doc.status}\` but file is a direct child of \`${parentDir}/\`, not \`${parentDir}/${config.archiveDir}/\`. Run \`runlist archive ${doc.path}\` to relocate to \`${expected}\`, or change the status.`,
+      });
+    }
+  }
+
+  // Inverse archive drift (issue #13): a doc whose path is under
+  // `<dir>/<archiveDir>/` but whose status is NOT an archive status. Without
+  // this check, the file is invisible to default queries (the path is below
+  // an archive bucket so it's filtered out by `--exclude-archived`), yet its
+  // `status: pending` (or similar) still makes it surface in pending-prompt
+  // scans. The heal is to flip the frontmatter via `runlist <type-or-set>
+  // archive`, which now restores in place rather than failing.
+  if (doc.status && !config.lifecycle.archiveStatuses.has(doc.status)) {
+    const parentSegments = path.dirname(doc.path).split('/');
+    if (parentSegments.includes(config.archiveDir)) {
+      const heal = doc.type === 'prompt'
+        ? `runlist prompts archive ${doc.path}`
+        : `runlist set archived ${doc.path}`;
+      doc.errors.push({
+        path: doc.path,
+        level: 'error',
+        message: `File is under \`${config.archiveDir}/\` but \`status: ${doc.status}\` is not an archive status. Run \`${heal}\` to heal the frontmatter in place, or move the file out of the archive directory.`,
+      });
+    }
+  }
+
+  // Historical documents still need navigable references. Their prose is a
+  // dated record, but links to moved or deleted files cannot be followed.
+  const docDir = path.dirname(path.join(config.repoRoot, doc.path));
+  const allRefFields = [...(config.referenceFields.bidirectional || []), ...(config.referenceFields.unidirectional || [])];
+  for (const field of allRefFields) {
+    for (const relPath of (doc.refFields[field] || [])) {
+      if (!resolveRefPath(relPath, docDir, config.repoRoot)) {
+        doc.errors.push({
+          path: doc.path,
+          level: 'error',
+          message: `${field} entry \`${relPath}\` does not resolve to an existing file.`,
+          meta: { kind: 'ref-resolution', field, relPath },
+        });
+      }
+    }
+  }
+
+  for (const link of (doc.bodyLinks || [])) {
+    const resolution = resolveBodyLinkTarget(link.href, docDir, config.repoRoot, config.externalBodyLinkRoots);
+    if (!resolution.ok) {
+      const shownHref = link.rawHref ?? link.href;
+      doc.errors.push({
+        path: doc.path,
+        level: 'error',
+        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,
+        },
+      });
+    }
+  }
+}
+
+// Guess which doc type a ref field expects so suggestions don't propose
+// nonsense (a `related_plans` ref shouldn't suggest doc filenames). Heuristic:
+// match common substrings in the field name. When ambiguous, return null so
+// the caller suggests across all types.
+function inferRefFieldType(field) {
+  if (!field) return null;
+  const f = field.toLowerCase();
+  if (f.includes('plan')) return 'plan';
+  if (f.includes('doc')) return 'doc';
+  if (f.includes('prompt')) return 'prompt';
+  if (f.includes('research')) return 'research';
+  return null;
+}
+
+function candidatePathsForType(docs, type) {
+  // When the field implies a type, exclude docs that explicitly declare a
+  // different type. Untyped docs (no frontmatter `type:`) are kept — we
+  // don't know they aren't the target, so suggesting them is still useful.
+  const matches = type ? docs.filter(d => !d.type || d.type === type) : docs;
+  // Suggest by basename (the friendly handle agents/humans actually type) and
+  // by repo-relative path (covers cases where multiple files share a basename
+  // and the disambiguator is the directory).
+  const out = new Set();
+  for (const d of matches) {
+    out.add(path.basename(d.path));
+    out.add(d.path);
+  }
+  return [...out];
+}
+
+// Post-pass enrichment: walk every doc's errors/warnings for unresolved-ref
+// entries and append `Did you mean: a, b, c?` using the full index. Runs
+// after parsing so it has the global doc list (validateDoc runs per-file and
+// can't see siblings). Filters candidates by ref-field type when the field
+// name implies one (e.g. `related_plans` → plans only).
+export function enrichRefErrorSuggestions(docs, config) {
+  // One candidate list per inferred type, not per broken ref. The list is a
+  // filter plus a ~2-per-doc Set build over the whole index, and it does not
+  // depend on the entry — rebuilding it for each entry made this pass quadratic
+  // in (docs × broken refs), adding repeated work to every index build.
+  const candidateCache = new Map();
+  const candidatesFor = (type) => {
+    const key = type ?? '';
+    if (!candidateCache.has(key)) candidateCache.set(key, candidatePathsForType(docs, type));
+    return candidateCache.get(key);
+  };
+
+  const enrich = (entry) => {
+    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 suggestions = suggestCandidates(path.basename(entry.meta.relPath), candidatesFor(inferred));
+    entry._suggested = true;
+    if (suggestions.length === 0) return;
+    entry.message = `${entry.message} Did you mean: ${suggestions.join(', ')}?`;
+  };
+
+  for (const doc of docs) {
+    for (const e of (doc.errors || [])) enrich(e);
+    for (const w of (doc.warnings || [])) enrich(w);
+  }
+}
+
+export function checkBidirectionalReferences(docs, config) {
+  const warnings = [];
+  const biFields = config.referenceFields.bidirectional || [];
+  if (!biFields.length) return { warnings, errors: [] };
+
+  // refMap stores `Set<targetPath>` keyed by the source doc path — used to
+  // answer "does B reference A?" via .has(). oneWayMap stores the subset of A's
+  // outbound refs that opted out of expecting a back-ref (via the `>` prefix in
+  // frontmatter, parsed in src/index.mjs:parseDocFile). We split these so the
+  // membership check stays cheap (Set.has) while the per-ref directionality
+  // filter only consults oneWayMap when iterating outbound edges.
+  const refMap = new Map();
+  const oneWayMap = new Map();
+  for (const doc of docs) {
+    const docDir = path.dirname(path.join(config.repoRoot, doc.path));
+    const refs = new Set();
+    const oneWay = new Set();
+    for (const field of biFields) {
+      const entries = doc.refFields[field] || [];
+      const dirs = doc.refFieldDirections?.[field] || [];
+      for (let i = 0; i < entries.length; i++) {
+        const relPath = entries[i];
+        // Use the same doc-relative-then-repo-root fallback as validateDoc so
+        // both styles produce identical refMap keys; otherwise an entry like
+        // `docs/foo.md` (repo-root style) gets keyed as
+        // `<doc-parent>/docs/foo.md` and never matches the target's repo path.
+        const resolved = resolveRefPath(relPath, docDir, config.repoRoot)
+          ?? path.resolve(docDir, relPath);
+        const targetPath = toRepoPath(resolved, config.repoRoot);
+        refs.add(targetPath);
+        if (dirs[i] === 'one-way') oneWay.add(targetPath);
+      }
+    }
+    refMap.set(doc.path, refs);
+    oneWayMap.set(doc.path, oneWay);
+  }
+
+  for (const [docPath, refs] of refMap) {
+    const oneWay = oneWayMap.get(docPath);
+    for (const targetPath of refs) {
+      if (oneWay.has(targetPath)) continue;
+      const targetRefs = refMap.get(targetPath);
+      if (targetRefs && !targetRefs.has(docPath)) {
+        warnings.push({ path: docPath, level: 'warning',
+          message: `references \`${targetPath}\` in ${biFields.join('/')}, but that doc does not reference back.` });
+      }
+    }
+  }
+
+  return { warnings, errors: [] };
+}
+
+// Runlist back-pointer check: when a hub plan declares a `runlist:` of children,
+// each child SHOULD have `parent_plan:` pointing back at the hub. The two
+// fields encode complementary information (runlist = ordered execution intent;
+// parent_plan = reverse-link the rest of runlist already uses for related-summary
+// rendering), so divergence almost always means the agent forgot the back-link.
+// Warning fires on the CHILD (that's the file that needs the edit). Skips
+// terminal/archive statuses on either side — runlists referencing closed work
+// are a normal history pattern. A `>`-prefixed (one-way) runlist entry opts
+// that child out of the back-pointer requirement — the same per-ref escape
+// hatch the bidirectional reciprocity check honors (A4) — so a hub can order a
+// child it doesn't own without nagging the child to add `parent_plan:`.
+export function checkRunlistBackPointers(docs, config) {
+  const warnings = [];
+  // Per-doc, not a precomputed name set: warning suppression is type-scoped, so
+  // the same status name can be quiet for one type and loud for another.
+  const skipDoc = (d) => config.lifecycle.terminalStatuses.has(d.status)
+    || config.lifecycle.skipsWarnings(d.status, d.type);
+  const byPath = new Map(docs.map(d => [d.path, d]));
+
+  for (const hub of docs) {
+    if (skipDoc(hub)) continue;
+    const runlistRefs = hub.refFields?.runlist ?? [];
+    const runlistDirs = hub.refFieldDirections?.runlist ?? [];
+    if (runlistRefs.length === 0) continue;
+    const hubDir = path.dirname(path.join(config.repoRoot, hub.path));
+
+    for (let i = 0; i < runlistRefs.length; i++) {
+      const ref = runlistRefs[i];
+      if (runlistDirs[i] === 'one-way') continue; // `> child.md` → ordered but no back-pointer expected
+      const resolved = resolveRefPath(ref, hubDir, config.repoRoot);
+      if (!resolved) continue; // unresolved refs already get their own existence error
+      const childPath = toRepoPath(resolved, config.repoRoot);
+      const child = byPath.get(childPath);
+      if (!child) continue;
+      if (skipDoc(child)) continue;
+      const childParents = (child.refFields?.parent_plan ?? []).map(p => {
+        const abs = resolveRefPath(p, path.dirname(path.join(config.repoRoot, child.path)), config.repoRoot);
+        return abs ? toRepoPath(abs, config.repoRoot) : p;
+      });
+      if (childParents.includes(hub.path)) continue;
+      warnings.push({
+        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',
+        },
+      });
+    }
+  }
+  return warnings;
+}
+
+// Coordination-hub hygiene: a plan whose slug is `*-runlist` / `runlist` reads
+// as a coordination runlist, but `runlist plans` only *reliably* lifts it into the
+// Runlists section (and out of the active count) when `execution_mode:
+// coordination` is set. Slug detection is the fallback; the frontmatter field is
+// the canonical signal. Nudge the few hubs that lean on the slug alone to make
+// it explicit. Skips terminal/quiet statuses like every other warning-only check.
+export function checkCoordinationHubExecutionMode(docs, config) {
+  const warnings = [];
+  // Per-doc, not a precomputed name set: warning suppression is type-scoped, so
+  // the same status name can be quiet for one type and loud for another.
+  const skipDoc = (d) => config.lifecycle.terminalStatuses.has(d.status)
+    || config.lifecycle.skipsWarnings(d.status, d.type);
+  for (const doc of docs) {
+    if (doc.type && doc.type !== 'plan') continue;
+    if (skipDoc(doc)) continue;
+    // ANY explicit `execution_mode` ends it. The field is the canonical signal
+    // and the slug is only a fallback for hubs that predate it, so a plan that
+    // already answered — `implementation`, `roadmap`, anything — has said what it
+    // is. Nudging past that misfires on exactly one population: plans ABOUT
+    // runlists, whose slug contains the word while the document is ordinary work.
+    // (A real one: a plan to rename the runlist concept, declared
+    // `execution_mode: implementation`, nagged to call itself a coordination hub.)
+    if (doc.executionMode) continue;
+    const base = (doc.path.split('/').pop() || '').replace(/\.md$/, '');
+    if (base !== 'runlist' && !base.endsWith('-runlist')) continue;
+    warnings.push({
+      path: doc.path,
+      level: 'warning',
+      message: `reads as a coordination runlist (slug \`${base}\`) but is missing \`execution_mode: coordination\`. Add it so \`runlist plans\` / \`runlist runlists\` reliably treat it as a runlist, not an active plan.`,
+    });
+  }
+  return warnings;
+}
+
+// Roadmap-hub nudge: a coordination hub whose `related_plans:` children are
+// *themselves* hubs (runlists / coordination hubs) is structurally a tier-3
+// roadmap — runlist renders it flat (a hub among its own children, no recursive
+// rollup) until `execution_mode: roadmap` is set. Nudge, never auto-promote: the
+// explicit field beats structural magic for a primitive (Open Q in the
+// roadmap-layer plan). Fires only when ≥2 children AND a majority are hubs, so a
+// coordination hub that merely references one sibling runlist isn't mislabelled.
+export function checkRoadmapHubExecutionMode(docs, config) {
+  const warnings = [];
+  // Per-doc, not a precomputed name set: warning suppression is type-scoped, so
+  // the same status name can be quiet for one type and loud for another.
+  const skipDoc = (d) => config.lifecycle.terminalStatuses.has(d.status)
+    || config.lifecycle.skipsWarnings(d.status, d.type);
+  const byPath = new Map(docs.map(d => [d.path, d]));
+  const byBasename = new Map();
+  for (const d of docs) {
+    const base = d.path.split('/').pop();
+    if (!byBasename.has(base)) byBasename.set(base, d);
+  }
+  const looksLikeHub = (d) => {
+    if (!d) return false;
+    if (d.executionMode === 'coordination' || d.executionMode === 'roadmap') return true;
+    if (Array.isArray(d.refFields?.runlist) && d.refFields.runlist.length > 0) return true;
+    const b = (d.path.split('/').pop() || '').replace(/\.md$/, '');
+    return b === 'runlist' || b.endsWith('-runlist');
+  };
+  for (const doc of docs) {
+    if (doc.type && doc.type !== 'plan') continue;
+    if (skipDoc(doc)) continue;
+    if (doc.executionMode === 'roadmap') continue;       // already a roadmap
+    if (doc.executionMode !== 'coordination') continue;  // only nudge explicit coordination hubs
+    const refs = doc.refFields?.related_plans ?? [];
+    if (refs.length === 0) continue;
+    const dir = path.dirname(path.join(config.repoRoot, doc.path));
+    let resolved = 0, hubChildren = 0;
+    const seen = new Set();
+    for (const ref of refs) {
+      const abs = resolveRefPath(ref, dir, config.repoRoot);
+      let child = abs ? byPath.get(toRepoPath(abs, config.repoRoot)) ?? null : null;
+      if (!child) child = byBasename.get(ref.split('/').pop()) ?? null;
+      if (!child || child.path === doc.path || seen.has(child.path)) continue;
+      seen.add(child.path);
+      resolved++;
+      if (looksLikeHub(child)) hubChildren++;
+    }
+    if (hubChildren >= 2 && hubChildren > resolved / 2) {
+      warnings.push({
+        path: doc.path,
+        level: 'warning',
+        message: `is a coordination hub whose ${hubChildren} of ${resolved} \`related_plans:\` children are themselves runlists — that's structurally a tier-3 roadmap. Set \`execution_mode: roadmap\` so \`runlist roadmap\` rolls their progress up (recursive done/total) instead of rendering it flat among them.`,
+      });
+    }
+  }
+  return warnings;
+}
+
+export function checkGitStaleness(docs, config, options = {}) {
+  const warnings = [];
+  const eligibleDocs = docs.filter(doc => !config.lifecycle.skipStaleFor.has(doc.status) && doc.updated);
+  const pathspecs = (config.docsRoots || [config.docsRoot])
+    .map(root => toRepoPath(root, config.repoRoot) || '.');
+  const gitMetadata = getGitLastModifiedBatch(
+    config.repoRoot,
+    eligibleDocs.map(doc => doc.path),
+    { pathspecs, ...options },
+  );
+  const driftCandidates = eligibleDocs.filter(doc => {
+    const gitDate = gitMetadata.dates.get(doc.path) ?? null;
+    return Boolean(gitDate && gitDate.slice(0, 10) > doc.updated.slice(0, 10));
+  });
+  const candidatePaths = driftCandidates.map(doc => doc.path);
+  const candidateMetadata = {
+    dates: new Map(candidatePaths.filter(p => gitMetadata.dates.has(p)).map(p => [p, gitMetadata.dates.get(p)])),
+    commits: new Map(candidatePaths.filter(p => gitMetadata.commits?.has(p)).map(p => [p, gitMetadata.commits.get(p)])),
+    history: new Map(candidatePaths.filter(p => gitMetadata.history?.has(p)).map(p => [p, gitMetadata.history.get(p)])),
+    complete: gitMetadata.complete,
+    reason: gitMetadata.reason,
+  };
+  const substantiveMetadata = candidatePaths.length > 0
+    ? getGitLastSubstantiveModifiedBatch(config.repoRoot, candidatePaths, candidateMetadata, options)
+    : candidateMetadata;
+
+  for (const doc of driftCandidates) {
+    const gitDate = substantiveMetadata.dates.get(doc.path) ?? null;
+    if (!gitDate) continue;
+    const gitDay = gitDate.slice(0, 10);
+    const fmDay = doc.updated.slice(0, 10);
+
+    if (gitDay > fmDay) {
+      warnings.push({
+        path: doc.path,
+        level: 'warning',
+        message: `frontmatter \`updated: ${doc.updated}\` is behind git history (last committed ${gitDate.slice(0, 10)}).`,
+      });
+    }
+  }
+  if (!substantiveMetadata.complete) {
+    warnings.push({
+      path: toRepoPath(config.docsRoot, config.repoRoot) || '.',
+      level: 'warning',
+      message: `Git metadata is incomplete (${substantiveMetadata.reason}); staleness checks used known dates only.`,
+    });
+  }
+  return warnings;
+}
+
+// Plan-shape lint: soft warnings on convention drift. Plan-only.
+// Body is the unparsed plan body (everything after the closing `---`).
+export function validatePlanShape(doc, body, frontmatter, config) {
+  if (doc.type !== 'plan') return;
+  // Skip plans in terminal/archive statuses (closed work shouldn't generate noise)
+  if (config.lifecycle.terminalStatuses.has(doc.status) || config.lifecycle.archiveStatuses.has(doc.status)) return;
+  if (config.lifecycle.skipsWarnings(doc.status, doc.type)) return;
+
+  // 1. next_step length cap (800 chars). Was 300; raised in parallel with
+  // current_state for the same reason: agents need to encode "what to do next"
+  // with enough specificity (which file, which decision, which branch) that
+  // 300 chars often forced truncation into the body where the briefing
+  // doesn't read it.
+  const nextStep = typeof frontmatter.next_step === 'string' ? frontmatter.next_step : '';
+  if (nextStep.length > 800) {
+    doc.warnings.push({
+      path: doc.path,
+      level: 'warning',
+      message: `\`next_step\` is ${nextStep.length} chars (cap: 800). One mechanical fix: \`runlist doctor --frontmatter-fix\` (moves the overflow into the body) — do NOT hand-trim or re-run check in a loop. Going forward, write next_step as a 1-2 sentence pointer; detail goes in the body.`,
+    });
+  }
+
+  // 2. current_state length cap (1500 chars). Was 500; raised because agents
+  // legitimately need ~150-250 words of resume-context (prior incidents, what
+  // shipped, what's verified, where to look) and the prior cap forced a
+  // truncate-and-move-to-body retry loop on non-trivial plans.
+  const currentState = typeof frontmatter.current_state === 'string' ? frontmatter.current_state : '';
+  if (currentState.length > 1500) {
+    doc.warnings.push({
+      path: doc.path,
+      level: 'warning',
+      message: `\`current_state\` is ${currentState.length} chars (cap: 1500). One mechanical fix: \`runlist doctor --frontmatter-fix\` (moves the overflow into the body) — do NOT hand-trim or re-run check in a loop. Going forward, write current_state as a 2-4 sentence summary; detail goes in the body.`,
+    });
+  }
+
+  if (!body) return;
+
+  // 4. Heading drift: case + name variants
+  const headingDrift = [
+    { wrong: /^##\s+(Non-goals|Out of scope|Out of Scope|out of scope)\s*$/m, right: '## Non-Goals' },
+  ];
+  for (const { wrong, right } of headingDrift) {
+    const m = body.match(wrong);
+    if (m) {
+      doc.warnings.push({
+        path: doc.path,
+        level: 'warning',
+        message: `Heading drift: \`${m[0].trim()}\` → suggest \`${right}\`.`,
+      });
+    }
+  }
+
+  // 5 & 6 read phases through section.mjs rather than re-parsing them here.
+  // This check used to carry its own heading scan and its own copy of the
+  // marker vocabulary, which drifted from the real reader in both directions:
+  // it counted `### Phase 3 outcome` as a phase needing a marker, and it never
+  // learned the fixes section.mjs got. Two parsers for one concept disagreeing
+  // is the same defect class as `reference-planner` vs `resolveRefPath`.
+  const phases = walkSections(body).filter(isPhaseHeading);
+
+  // 5. Phase headings that carry no status marker at all.
+  if (phases.length > 0) {
+    const unmarked = phases.filter(p => detectMarker(p.heading) === null);
+    if (unmarked.length > 0) {
+      doc.warnings.push({
+        path: doc.path,
+        level: 'warning',
+        message: `${unmarked.length} of ${phases.length} phase heading(s) lack a status marker. Use one of ✅ shipped, ⏭ skipped, 🟡 in-progress, ⬜ todo, 🚧 blocked.`,
+      });
+    }
+  }
+
+  // 6. A phase whose own checklist contradicts its marker. Reported, never
+  // fixed: runlist cannot know whether the marker or the boxes are the stale
+  // half, and guessing would either mark work done that is not, or reopen work
+  // that is. Both halves are the author's own writing — this only says they
+  // disagree.
+  for (const phase of phases) {
+    const conflict = phaseMarkerConflict(phase);
+    if (!conflict) continue;
+    doc.warnings.push({
+      path: doc.path,
+      level: 'warning',
+      message: `Phase marker contradicts its own checklist (line ${phase.lineStart}): \`${phase.heading.trim()}\` is marked ${conflict.declared}, but ${conflict.checked}/${conflict.total} boxes are checked — that reads as ${conflict.implied}. Update whichever half is stale.`,
+    });
+  }
+}
+
+// Doc-shape lint: soft warnings on convention drift. Doc-only.
+// Mirrors validatePlanShape's structure.
+export function validateDocShape(doc, body, frontmatter, config) {
+  if (doc.type !== 'doc') return;
+  if (config.lifecycle.terminalStatuses.has(doc.status) || config.lifecycle.archiveStatuses.has(doc.status)) return;
+  if (config.lifecycle.skipsWarnings(doc.status, doc.type)) return;
+
+  if (!body) return;
+
+  // Heading drift for docs.
+  const headingDrift = [
+    { wrong: /^##\s+Related Documents\s*$/m, right: '## Related Documentation' },
+  ];
+  for (const { wrong, right } of headingDrift) {
+    const m = body.match(wrong);
+    if (m) {
+      doc.warnings.push({
+        path: doc.path,
+        level: 'warning',
+        message: `Heading drift: \`${m[0].trim()}\` → suggest \`${right}\`.`,
+      });
+    }
+  }
+}
+
+export function computeDaysSinceUpdate(updated) {
+  if (!updated) return null;
+  const parsed = new Date(updated);
+  if (Number.isNaN(parsed.getTime())) return null;
+
+  const diffMs = NOW.getTime() - parsed.getTime();
+  if (diffMs < 0) return 0;
+  return Math.floor(diffMs / (1000 * 60 * 60 * 24));
+}
+
+export function computeIsStale(status, updated, config, type = null) {
+  const typeStaleDays = type ? config.raw?.types?.[type]?.staleDays : null;
+  const hasTypeDays = Object.prototype.hasOwnProperty.call(typeStaleDays ?? {}, status);
+  const staleAfterDays = hasTypeDays ? typeStaleDays[status] : (config.staleDaysByStatus[status] ?? null);
+  if (staleAfterDays == null) return false;
+
+  const daysSinceUpdate = computeDaysSinceUpdate(updated);
+  if (daysSinceUpdate == null) return false;
+  return daysSinceUpdate > staleAfterDays;
+}
+
+export function computeChecklistCompletionRate(checklist) {
+  if (!checklist.total) return null;
+  return Number((checklist.completed / checklist.total).toFixed(4));
+}
+
+// A floor under the scan surface.
+//
+// Every other check in this file asks "is this doc wrong?" — none of them can ask
+// "did we look at anything?". If the scan surface breaks (a root that stopped
+// resolving, a config edit that narrowed the tree, a rename that moved docs/ out
+// from under us), `runlist check` reports zero errors, and that output is
+// byte-identical to a clean estate. A guard's whole failure mode is going quiet,
+// and this is the one that would go quiet silently.
+//
+// Off unless `minDocs` is configured — a floor is a claim about YOUR corpus size
+// and runlist cannot guess it. Deliberately an error, not a warning: a warning exits
+// 0, which is the exact outcome this exists to prevent.
+export function applyScanFloor(index, config, { scoped = false } = {}) {
+  const floor = config?.minDocs;
+  if (!floor) return index;
+  // A path-scoped check (`runlist check docs/plans/x.md`) is a deliberate subset, so
+  // the floor would fire on every single-file check. Not a corpus claim at all.
+  if (scoped) return index;
+  if (index.docs.length >= floor) return index;
+
+  index.errors.push({
+    path: null,
+    level: 'error',
+    message: `only ${index.docs.length} docs in the scan surface (expected at least ${floor}) — `
+      + 'the file list broke, so a pass here would mean nothing. Check `root`/`excludeDirs` in '
+      + 'your config, or lower `minDocs` if the corpus genuinely shrank.',
+    meta: { kind: 'scan-floor', found: index.docs.length, floor },
+  });
+  return index;
+}