@ngockhoale/ukit 2.6.6 → 2.6.8

package/src/core/docContracts.js

@@ -0,0 +1,723 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import YAML from 'yaml';
+
+/**
+ * Doc contract validator (DOC-203, SPEC FR-005).
+ *
+ * `runDocContractChecks({ rootDir, scope? })` runs the seven v1 rules —
+ * links, stale-version, render-vars, commands, budgets, registry, templates —
+ * and returns a machine-readable report. It NEVER throws: unreadable input
+ * becomes a failed or skipped check with detail. TASK-210 wires this into
+ * `ukit doctor --docs`.
+ *
+ * CheckResult = { id, label, severity:'error'|'warning', passed:boolean,
+ *                 skipped?:boolean, detail?:string, remedy?:string }
+ * → { checks: CheckResult[], summary: { errors, warnings, passed, skipped } }
+ */
+
+const REGISTRY_PATH = 'manifests/documentation.yaml';
+const PACKAGE_PATH = 'package.json';
+const MD_LINK_RE = /\[([^\]]*)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+const VERSION_LITERAL_RE = /v\d+\.\d+\.\d+/g;
+const RENDER_VAR_RE = /\{\{[\s\S]*?\}\}/g;
+const COMMAND_REF_RE = /\.claude\/commands\/ukit\/([A-Za-z0-9._-]+\.md)/g;
+const EXECUTOR_FIELDS = ['EXECUTOR_TOOL', 'EXECUTOR_MODEL', 'EXECUTOR_SUBAGENT', 'RED_OUTPUT'];
+// DOC-304: a registered doc untouched for this many days counts as `stale`.
+export const ARCHIVE_STALE_DAYS = 180;
+
+// Registry schema enums — mirrored from tests/consistency/docRegistry.test.js
+// (TASK-209 interface: mirror, do not import, to avoid a test→src cycle).
+const CLASSES = ['owner', 'canonical', 'generated', 'runtime', 'derived', 'archive'];
+const AUDIENCES = ['agent', 'maintainer', 'user', 'owner', 'contributor'];
+const OWNERS = ['product', 'runtime', 'adapter', 'security', 'release', 'project-owner'];
+const MERGE_STRATEGIES = ['skip', 'overwrite_with_backup', 'merge_env_overwrite_with_backup', 'none'];
+const LOAD_POLICIES = ['always', 'on-demand', 'task-routed', 'continuation-only', 'never'];
+const ARCHIVE_POLICIES = ['never', 'replace-with-snapshot', 'date-rotate', 'immutable', 'owner-decides'];
+const BUDGET_ENFORCEMENTS = ['none', 'warning', 'error'];
+const KEBAB = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+// Files that legitimately pin a vX.Y.Z literal — mirrored from
+// tests/consistency/staleVersionProse.test.js (same justification rule:
+// every entry MUST state why the prose is allowed to pin a version).
+const STALE_VERSION_ALLOWLIST = {
+  'CLAUDE.md':
+    'repo-rendered instructions embed {{runtime.nodeVersion}} resolved to the dev Node (e.g. v22.22.1) — environment fact, not a UKit release pin',
+  'AGENTS.md':
+    'same interpolated runtime.nodeVersion — environment fact, not a UKit release pin',
+  'docs/WORKLOG_ARCHIVE.md':
+    'worklog history records past versions as release facts — immutable historical prose',
+  'templates/.gitignore':
+    'comment records the release that removed a legacy adapter — historical fact',
+  'templates/.claude/agents/code-reviewer.md':
+    'rubric row quotes the literal "v1.5.5+ contract" reviewer refusal wording — contractual string',
+  'templates/.omp/agents/code-reviewer.md':
+    'omp mirror of the same reviewer rubric row — contractual string',
+  'templates/.claude/ukit/index/unic-gateway.mjs':
+    'code comments record the omp version gateway detection was verified against — evidence',
+  'templates/.omp/hooks/pre/ukit-bridge.js':
+    'code comments record omp versions verified during source reads — evidence',
+  'templates/.omp/config.yml':
+    'comment records the omp version the config keys were verified against — evidence',
+};
+
+// Files covered by stale-version + render-vars beyond `templates/` generated
+// surfaces: the repo-rendered root instructions (registry class is `canonical`
+// because they are also the project-owner file) and derived mirrors.
+const RENDERED_EXTRA_TARGETS = ['CLAUDE.md', 'AGENTS.md'];
+
+async function readText(absPath) {
+  try {
+    return await fs.readFile(absPath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+async function existsPath(absPath) {
+  try {
+    await fs.stat(absPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function isDir(absPath) {
+  try {
+    return (await fs.stat(absPath)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+// Recursive repo-relative file walk under rootDir/dirRel. `filter` selects
+// files by extension etc. Never throws (unreadable dirs are skipped).
+async function walkFiles(rootDir, dirRel, filter = () => true) {
+  const out = [];
+  const dirAbs = dirRel ? path.join(rootDir, dirRel) : rootDir;
+  let names;
+  try {
+    names = await fs.readdir(dirAbs);
+  } catch {
+    return out;
+  }
+  for (const name of names) {
+    const rel = dirRel ? `${dirRel}/${name}` : name;
+    let st;
+    try {
+      st = await fs.stat(path.join(rootDir, rel));
+    } catch {
+      continue; // dangling symlink / unreadable
+    }
+    if (st.isDirectory()) out.push(...(await walkFiles(rootDir, rel, filter)));
+    else if (filter(name, rel)) out.push(rel);
+  }
+  return out;
+}
+
+function makeCheck(id, label, severity, extra) {
+  return { id, label, severity, passed: false, ...extra };
+}
+
+function skippedCheck(id, label, detail) {
+  return makeCheck(id, label, 'error', {
+    skipped: true,
+    detail,
+    remedy: `create or restore ${detail.match(/[\w./-]+\.\w+/)?.[0] || 'the required file'}`,
+  });
+}
+
+// ---- registry validation (mirrors docRegistry.test.js validateRegistry) ----
+
+function validateRegistryDoc(doc, fileExists) {
+  const problems = [];
+  if (!doc || typeof doc !== 'object') return ['registry is not an object'];
+  if (doc.version !== 1) problems.push('version must be 1');
+  if (doc.generated !== false) problems.push('generated must be false');
+  if (!Array.isArray(doc.entries) || doc.entries.length === 0) {
+    problems.push('entries must be a non-empty array');
+    return problems;
+  }
+  const seen = new Map();
+  doc.entries.forEach((e, i) => {
+    const tag = `entry[${i}] (${e && e.path ? e.path : 'no-path'})`;
+    if (!e || typeof e !== 'object') {
+      problems.push(`${tag}: not an object`);
+      return;
+    }
+    if (typeof e.id !== 'string' || !KEBAB.test(e.id)) problems.push(`${tag}: id missing/not kebab-case`);
+    if (typeof e.path !== 'string' || e.path.length === 0) problems.push(`${tag}: path missing`);
+    else {
+      if (seen.has(e.path)) problems.push(`${tag}: duplicate path '${e.path}'`);
+      else seen.set(e.path, i);
+    }
+    if (!CLASSES.includes(e.class)) problems.push(`${tag}: bad class '${e.class}'`);
+    if (!Array.isArray(e.audience) || e.audience.length === 0 || e.audience.some((a) => !AUDIENCES.includes(a))) {
+      problems.push(`${tag}: audience must be a non-empty subset of ${AUDIENCES.join(',')}`);
+    }
+    if (!OWNERS.includes(e.owner)) problems.push(`${tag}: bad owner '${e.owner}'`);
+    if (typeof e.source_of_truth !== 'string' || e.source_of_truth.length === 0) {
+      problems.push(`${tag}: source_of_truth missing`);
+    }
+    if (!MERGE_STRATEGIES.includes(e.merge_strategy)) problems.push(`${tag}: bad merge_strategy '${e.merge_strategy}'`);
+    if (!LOAD_POLICIES.includes(e.load_policy)) problems.push(`${tag}: bad load_policy '${e.load_policy}'`);
+    if (!Array.isArray(e.validation) || e.validation.length === 0) {
+      problems.push(`${tag}: validation must be a non-empty list`);
+    } else {
+      for (const v of e.validation) {
+        if (typeof v !== 'string') {
+          problems.push(`${tag}: validation item not a string`);
+          continue;
+        }
+        if (v === 'doctor' || v === 'manual' || v === 'none') continue;
+        if (v.startsWith('test:')) {
+          if (!fileExists(v.slice(5))) problems.push(`${tag}: validation test path '${v.slice(5)}' missing on disk`);
+          continue;
+        }
+        problems.push(`${tag}: unknown validation '${v}'`);
+      }
+    }
+    if (!ARCHIVE_POLICIES.includes(e.archive_policy)) problems.push(`${tag}: bad archive_policy '${e.archive_policy}'`);
+    if (e.budget !== undefined) {
+      if (typeof e.budget !== 'object' || e.budget === null) problems.push(`${tag}: budget not an object`);
+      else {
+        if (!Number.isInteger(e.budget.max_lines) || e.budget.max_lines <= 0) {
+          problems.push(`${tag}: budget.max_lines must be a positive int`);
+        }
+        if (!BUDGET_ENFORCEMENTS.includes(e.budget.enforcement)) {
+          problems.push(`${tag}: bad budget.enforcement '${e.budget.enforcement}'`);
+        }
+      }
+    }
+    if (e.notes !== undefined && typeof e.notes !== 'string') problems.push(`${tag}: notes must be a string`);
+  });
+  return problems;
+}
+
+// ---- individual rule runners (each returns one CheckResult) ----
+
+// Repo-relative .md files whose registry entry class is canonical or
+// generated — the "canonical docs" scope for links/stale-version/commands.
+async function canonicalMdFiles(rootDir, registry) {
+  const files = new Set();
+  for (const e of registry.entries) {
+    if (typeof e.path !== 'string') continue;
+    if (!['canonical', 'generated'].includes(e.class)) continue;
+    if (e.path.endsWith('/')) {
+      for (const f of await walkFiles(rootDir, e.path.slice(0, -1), (n) => n.endsWith('.md'))) {
+        files.add(f);
+      }
+    } else if (e.path.endsWith('.md')) {
+      if (await existsPath(path.join(rootDir, e.path))) files.add(e.path);
+    }
+  }
+  return [...files];
+}
+
+async function checkLinks(rootDir, registry) {
+  const id = 'links';
+  const label = 'relative markdown links in canonical docs resolve';
+  const files = await canonicalMdFiles(rootDir, registry);
+  if (files.length === 0) {
+    return makeCheck(id, label, 'error', { skipped: true, detail: 'no canonical .md files in scope' });
+  }
+  const broken = [];
+  for (const rel of files) {
+    const content = await readText(path.join(rootDir, rel));
+    if (content === null) continue;
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      MD_LINK_RE.lastIndex = 0;
+      let m;
+      while ((m = MD_LINK_RE.exec(lines[i])) !== null) {
+        const target = m[2].split('#')[0];
+        if (!target || /^(https?:|mailto:|tel:)/i.test(target)) continue;
+        if (target.startsWith('/') || target.startsWith('<') || target.startsWith('#')) continue;
+        // Placeholder links (e.g. `[action](request)`, `(link)`) carry no path
+        // separator and no file extension — they are illustrative, not links.
+        if (!target.includes('/') && !/\.[a-zA-Z0-9]{1,8}$/.test(target)) continue;
+        const resolved = path.normalize(path.join(path.dirname(rel), target));
+        let ok = await existsPath(path.join(rootDir, resolved));
+        // Tolerances: (a) root-relative links (docs write `docs/x.md` from repo
+        // root), (b) runtime surfaces shipped under templates/ (`.omp/...` in
+        // source repo lives at templates/.omp/...).
+        if (!ok) ok = await existsPath(path.join(rootDir, target));
+        if (!ok) ok = await existsPath(path.join(rootDir, 'templates', target));
+        if (!ok) broken.push(`${rel}:${i + 1} → ${target}`);
+      }
+    }
+  }
+  if (broken.length > 0) {
+    return makeCheck(id, label, 'error', {
+      detail: broken.slice(0, 10).join('; ') + (broken.length > 10 ? ` (+${broken.length - 10} more)` : ''),
+      remedy: 'fix or remove the broken relative links',
+    });
+  }
+  return makeCheck(id, label, 'error', { passed: true });
+}
+
+async function checkStaleVersion(rootDir, registry) {
+  const id = 'stale-version';
+  const label = 'no vX.Y.Z literals ≠ package.json version on scanned surfaces';
+  const pkgRaw = await readText(path.join(rootDir, PACKAGE_PATH));
+  let pkgVersion = null;
+  try {
+    pkgVersion = JSON.parse(pkgRaw || '').version;
+  } catch {
+    /* fall through */
+  }
+  if (typeof pkgVersion !== 'string') {
+    return makeCheck(id, label, 'error', { skipped: true, detail: 'package.json version unreadable' });
+  }
+  // Scanned set mirrors staleVersionProse: any-extension files under
+  // canonical/generated templates/ entries + the rendered root instructions.
+  const files = new Set(RENDERED_EXTRA_TARGETS);
+  for (const e of registry.entries) {
+    if (typeof e.path !== 'string' || !e.path.startsWith('templates/')) continue;
+    if (!['canonical', 'generated'].includes(e.class)) continue;
+    if (e.path.endsWith('/')) {
+      for (const f of await walkFiles(rootDir, e.path.slice(0, -1))) files.add(f);
+    } else {
+      files.add(e.path);
+    }
+  }
+  const violations = [];
+  for (const rel of files) {
+    if (rel in STALE_VERSION_ALLOWLIST) continue;
+    const content = await readText(path.join(rootDir, rel));
+    if (content === null) continue;
+    const stripped = content.replace(RENDER_VAR_RE, '');
+    for (const m of stripped.matchAll(VERSION_LITERAL_RE)) {
+      if (m[0] !== `v${pkgVersion}`) {
+        violations.push(`${rel}: stale literal '${m[0]}' (package.json is ${pkgVersion})`);
+      }
+    }
+  }
+  if (violations.length > 0) {
+    return makeCheck(id, label, 'error', {
+      detail: violations.slice(0, 10).join('; ') + (violations.length > 10 ? ` (+${violations.length - 10} more)` : ''),
+      remedy: 'interpolate {{ukit.version}} or add an allowlist entry with a written justification',
+    });
+  }
+  return makeCheck(id, label, 'error', { passed: true });
+}
+
+async function checkRenderVars(rootDir, registry) {
+  const id = 'render-vars';
+  const label = 'no unresolved {{var}} placeholders in rendered targets';
+  // Rendered surfaces: repo outputs (CLAUDE.md/AGENTS.md) + derived mirrors.
+  // templates/ generated files legitimately keep {{var}} for install-time
+  // interpolation, so they are out of scope.
+  const targets = new Set(RENDERED_EXTRA_TARGETS);
+  for (const e of registry.entries) {
+    if (typeof e.path !== 'string' || e.class !== 'derived' || e.path.startsWith('templates/')) continue;
+    // Only .md doc surfaces are render targets — scripts/components/templates
+    // inside derived dirs legitimately use {{ }} as their own placeholders.
+    if (e.path.endsWith('/')) {
+      for (const f of await walkFiles(rootDir, e.path.slice(0, -1), (n) => n.endsWith('.md'))) {
+        targets.add(f);
+      }
+    } else if (e.path.endsWith('.md')) {
+      targets.add(e.path);
+    }
+  }
+  const leftovers = [];
+  for (const rel of targets) {
+    const content = await readText(path.join(rootDir, rel));
+    if (content === null) continue;
+    const m = content.match(/\{\{[^{}]*\}\}/);
+    if (m) leftovers.push(`${rel}: unresolved '${m[0]}'`);
+  }
+  if (leftovers.length > 0) {
+    return makeCheck(id, label, 'error', {
+      detail: leftovers.slice(0, 10).join('; '),
+      remedy: 're-run yarn docs:render (or the responsible renderer) so variables resolve',
+    });
+  }
+  return makeCheck(id, label, 'error', { passed: true });
+}
+
+async function checkCommands(rootDir, registry) {
+  const id = 'commands';
+  const label = '.claude/commands/ukit/*.md referenced in canonical docs exist';
+  const files = await canonicalMdFiles(rootDir, registry);
+  if (files.length === 0) {
+    return makeCheck(id, label, 'error', { skipped: true, detail: 'no canonical .md files in scope' });
+  }
+  const missing = [];
+  for (const rel of files) {
+    const content = await readText(path.join(rootDir, rel));
+    if (content === null) continue;
+    for (const m of content.matchAll(COMMAND_REF_RE)) {
+      const name = m[1];
+      const inRepo = await existsPath(path.join(rootDir, '.claude/commands/ukit', name));
+      const inTemplates = await existsPath(
+        path.join(rootDir, 'templates/.claude/commands/ukit', name),
+      );
+      if (!inRepo && !inTemplates) missing.push(`${rel}: .claude/commands/ukit/${name}`);
+    }
+  }
+  if (missing.length > 0) {
+    return makeCheck(id, label, 'error', {
+      detail: missing.slice(0, 10).join('; '),
+      remedy: 'create the referenced command file or fix the reference',
+    });
+  }
+  return makeCheck(id, label, 'error', { passed: true });
+}
+
+async function checkBudgets(rootDir, registry) {
+  const id = 'budgets';
+  const label = 'registry line budgets obeyed (error enforcement blocks)';
+  const errorViolations = [];
+  const warningViolations = [];
+  for (const e of registry.entries) {
+    if (!e.budget || typeof e.path !== 'string' || e.path.endsWith('/')) continue;
+    if (!Number.isInteger(e.budget.max_lines)) continue;
+    const content = await readText(path.join(rootDir, e.path));
+    if (content === null) continue;
+    const lines = content.split('\n').length;
+    if (lines <= e.budget.max_lines) continue;
+    const msg = `${e.path}: ${lines} lines > max_lines ${e.budget.max_lines}`;
+    if (e.budget.enforcement === 'error') errorViolations.push(msg);
+    else if (e.budget.enforcement === 'warning') warningViolations.push(msg);
+  }
+  if (errorViolations.length > 0) {
+    return makeCheck(id, label, 'error', {
+      detail: errorViolations.join('; '),
+      remedy: 'shrink the file below its budget or raise the registry budget deliberately',
+    });
+  }
+  if (warningViolations.length > 0) {
+    return makeCheck(id, label, 'warning', {
+      passed: true, // advisory only — surfaced in detail, never blocks
+      detail: warningViolations.join('; '),
+      remedy: 'advisory only — shrink when convenient or revisit the budget',
+    });
+  }
+  return makeCheck(id, label, 'error', { passed: true });
+}
+
+// ---- dead-docs helpers (DOC-303; exported for TASK-216 archive-suggestions) ----
+
+// Exclusions per FR-006: release/changelog-style root docs, anything under an
+// `archive/` dir, node_modules, and dot-dirs/dot-files are never orphans.
+const DEAD_DOC_EXCLUDED_BASENAMES = new Set(['CHANGELOG.md', 'README.md']);
+function deadDocExcluded(rel) {
+  const segments = rel.split('/');
+  if (segments.some((s) => s === 'node_modules' || s === 'archive' || s.startsWith('.'))) {
+    return true;
+  }
+  return DEAD_DOC_EXCLUDED_BASENAMES.has(segments[segments.length - 1]);
+}
+
+/**
+ * Repo-relative `.md` files in dead-doc scope (FR-005): root `*.md`, `docs/**`,
+ * and any registered dir entry — minus FR-006 exclusions. Never throws.
+ * Returns Promise<string[]> sorted.
+ */
+export async function collectScannableDocs(rootDir, registry) {
+  const files = new Set();
+  // root *.md (non-recursive)
+  try {
+    for (const name of await fs.readdir(rootDir)) {
+      if (!name.endsWith('.md')) continue;
+      const st = await fs.stat(path.join(rootDir, name)).catch(() => null);
+      if (st && st.isFile()) files.add(name);
+    }
+  } catch {
+    /* unreadable root — nothing scannable */
+  }
+  // docs/** (registered dir entries are already inside docs/, but an entry may
+  // point elsewhere — e.g. a project-local doc dir — so add them explicitly).
+  const dirs = new Set(['docs']);
+  for (const e of registry.entries || []) {
+    if (typeof e.path === 'string' && e.path.endsWith('/')) dirs.add(e.path.slice(0, -1));
+  }
+  for (const dirRel of dirs) {
+    for (const f of await walkFiles(rootDir, dirRel, (n) => n.endsWith('.md'))) {
+      files.add(f);
+    }
+  }
+  return [...files].filter((rel) => !deadDocExcluded(rel)).sort();
+}
+
+/**
+ * Inbound markdown-link index over `mdFiles`: Map<relPath, Set<referrerRelPath>>.
+ * A link `[..](target)` counts when it resolves to another scanned file —
+ * resolved relative to the referrer's dir first, then relative to repo root
+ * (docs commonly write `docs/x.md` from root). Self-links do not count.
+ * Never throws; every scanned file gets an entry (empty set = no inbound).
+ */
+export async function computeInboundLinkIndex(rootDir, mdFiles) {
+  const index = new Map(mdFiles.map((rel) => [rel, new Set()]));
+  const scanned = new Set(mdFiles);
+  for (const rel of mdFiles) {
+    const content = await readText(path.join(rootDir, rel));
+    if (content === null) continue;
+    for (const line of content.split('\n')) {
+      MD_LINK_RE.lastIndex = 0;
+      let m;
+      while ((m = MD_LINK_RE.exec(line)) !== null) {
+        const target = m[2].split('#')[0];
+        if (!target || /^(https?:|mailto:|tel:)/i.test(target)) continue;
+        if (target.startsWith('/') || target.startsWith('<') || target.startsWith('#')) continue;
+        const candidates = [
+          path.normalize(path.join(path.dirname(rel), target)),
+          path.normalize(target),
+        ];
+        for (const resolved of candidates) {
+          const norm = resolved.split(path.sep).join('/');
+          if (norm !== rel && scanned.has(norm)) index.get(norm).add(rel);
+        }
+      }
+    }
+  }
+  return index;
+}
+
+// True when `rel` is a registry entry path (file entry, or inside a dir entry)
+// or is referenced as some entry's `source_of_truth` target.
+function registryCovers(registry, rel) {
+  for (const e of registry.entries || []) {
+    if (typeof e.path === 'string') {
+      if (e.path === rel) return true;
+      if (e.path.endsWith('/') && rel.startsWith(e.path)) return true;
+    }
+    if (typeof e.source_of_truth === 'string') {
+      if (e.source_of_truth === rel) return true;
+      if (e.source_of_truth.endsWith('/') && rel.startsWith(e.source_of_truth)) return true;
+    }
+  }
+  return false;
+}
+
+async function checkDeadDocs(rootDir, registry) {
+  const id = 'dead-docs';
+  const label = 'docs in scope are registered, referenced, or inbound-linked (orphans advisory)';
+  const mdFiles = await collectScannableDocs(rootDir, registry);
+  const inbound = await computeInboundLinkIndex(rootDir, mdFiles);
+  const dead = mdFiles.filter(
+    (rel) => !registryCovers(registry, rel) && (inbound.get(rel)?.size ?? 0) === 0,
+  );
+  if (dead.length > 0) {
+    return makeCheck(id, label, 'warning', {
+      passed: true, // advisory only — never blocks, never counts as an error
+      detail: dead.slice(0, 10).join('; ') + (dead.length > 10 ? ` (+${dead.length - 10} more)` : ''),
+      remedy: 'register the doc in manifests/documentation.yaml, link it from a canonical doc, or archive/remove it',
+    });
+  }
+  return makeCheck(id, label, 'warning', { passed: true });
+}
+
+// ---- archive-suggestions (DOC-304 / FR-007..008) ----
+
+// Registered file entries whose class is canonical or owner get scored on
+// staleness signals; ≥2 signals ranks them as archive candidates (advisory).
+async function checkArchiveSuggestions(rootDir, registry, nowMs) {
+  const id = 'archive-suggestions';
+  const label = 'registered canonical/owner docs scored for archive candidacy (advisory)';
+  const mdFiles = await collectScannableDocs(rootDir, registry);
+  const inbound = await computeInboundLinkIndex(rootDir, mdFiles);
+  const staleCutoffMs = nowMs - ARCHIVE_STALE_DAYS * 24 * 60 * 60 * 1000;
+  const candidates = [];
+  for (const e of registry.entries || []) {
+    if (!['canonical', 'owner'].includes(e.class)) continue;
+    if (typeof e.path !== 'string' || e.path.endsWith('/') || !e.path.endsWith('.md')) continue;
+    const abs = path.join(rootDir, e.path);
+    const content = await readText(abs);
+    if (content === null) continue;
+    const signals = [];
+    if ((inbound.get(e.path)?.size ?? 0) === 0) signals.push('unreferenced');
+    if (e.budget && Number.isInteger(e.budget.max_lines)) {
+      const lines = content.split('\n').length;
+      if (lines > e.budget.max_lines) signals.push('over-budget');
+    }
+    let st = null;
+    try {
+      st = await fs.stat(abs);
+    } catch {
+      /* unreadable — mtime signal skipped */
+    }
+    if (st && st.mtimeMs < staleCutoffMs) signals.push('stale');
+    if (signals.length >= 2) candidates.push({ path: e.path, signals });
+  }
+  candidates.sort((a, b) => b.signals.length - a.signals.length);
+  if (candidates.length > 0) {
+    const detail = candidates
+      .slice(0, 10)
+      .map((c) => `${c.path} [${c.signals.join(', ')}]`)
+      .join('; ');
+    return makeCheck(id, label, 'warning', {
+      passed: true, // advisory only — nothing is moved, never blocks
+      detail: detail + (candidates.length > 10 ? ` (+${candidates.length - 10} more)` : ''),
+      remedy: 'advisory only — consider archiving the listed docs under their archive_policy',
+    });
+  }
+  return makeCheck(id, label, 'warning', { passed: true });
+}
+
+async function checkRegistry(rootDir, registry, fileExists) {
+  const id = 'registry';
+  const label = 'manifests/documentation.yaml schema + disk cross-checks';
+  const problems = validateRegistryDoc(registry, fileExists);
+  for (const e of registry.entries || []) {
+    if (typeof e.path !== 'string' || e.path.length === 0) continue;
+    if (!fileExists(e.path)) problems.push(`entry path '${e.path}' does not exist on disk`);
+    if (typeof e.source_of_truth === 'string' && e.source_of_truth.length > 0 && !fileExists(e.source_of_truth)) {
+      problems.push(`entry '${e.path}': source_of_truth '${e.source_of_truth}' does not exist on disk`);
+    }
+  }
+  if (problems.length > 0) {
+    return makeCheck(id, label, 'error', {
+      detail: problems.slice(0, 10).join('; ') + (problems.length > 10 ? ` (+${problems.length - 10} more)` : ''),
+      remedy: 'fix manifests/documentation.yaml entries per docRegistry.test.js schema',
+    });
+  }
+  return makeCheck(id, label, 'error', { passed: true });
+}
+
+async function checkTemplates(rootDir) {
+  const id = 'templates';
+  const label = '_TEMPLATE.md copies declare the Executor Report header fields (FR-013)';
+  const copies = [
+    'docs/AI_HANDOFF/tasks/_TEMPLATE.md',
+    'templates/docs/AI_HANDOFF/tasks/_TEMPLATE.md',
+  ];
+  const foundAny = await Promise.all(
+    copies.map((rel) => existsPath(path.join(rootDir, rel))),
+  );
+  if (!foundAny.some(Boolean)) {
+    return makeCheck(id, label, 'error', {
+      skipped: true,
+      detail: 'no _TEMPLATE.md copies present',
+    });
+  }
+  const problems = [];
+  for (const rel of copies) {
+    const content = await readText(path.join(rootDir, rel));
+    if (content === null) {
+      problems.push(`${rel}: missing`);
+      continue;
+    }
+    for (const field of EXECUTOR_FIELDS) {
+      if (!content.includes(field)) problems.push(`${rel}: missing ${field}`);
+    }
+  }
+  if (problems.length > 0) {
+    return makeCheck(id, label, 'error', {
+      detail: problems.join('; '),
+      remedy: 'add the required header line: - EXECUTOR_TOOL: … / EXECUTOR_MODEL: … / EXECUTOR_SUBAGENT: … / RED_OUTPUT: …',
+    });
+  }
+  return makeCheck(id, label, 'error', { passed: true });
+}
+
+/**
+ * Run all v1 doc-contract rules against rootDir. Never throws.
+ * `scope` is reserved ('repo' is the only mode today).
+ */
+export async function runDocContractChecks({ rootDir, scope = 'repo', now } = {}) {
+  const checks = [];
+  const root = typeof rootDir === 'string' && rootDir.length > 0 ? rootDir : process.cwd();
+  // FR-008: injectable clock (ms epoch or Date) for deterministic staleness.
+  const nowMs = now instanceof Date ? now.getTime() : typeof now === 'number' ? now : Date.now();
+
+  const registryRaw = await readText(path.join(root, REGISTRY_PATH));
+  let registry = null;
+  if (registryRaw !== null) {
+    try {
+      registry = YAML.parse(registryRaw);
+    } catch (err) {
+      checks.push(
+        makeCheck('registry', 'manifests/documentation.yaml parses', 'error', {
+          detail: `YAML parse failed: ${err && err.message ? err.message : err}`,
+          remedy: `fix syntax in ${REGISTRY_PATH}`,
+        }),
+      );
+    }
+  }
+
+  if (registry === null) {
+    if (!checks.some((c) => c.id === 'registry')) {
+      checks.push(skippedCheck('registry', 'manifests/documentation.yaml schema', `${REGISTRY_PATH} absent`));
+    }
+    for (const [id, label] of [
+      ['links', 'relative markdown links in canonical docs resolve'],
+      ['stale-version', 'no stale version literals'],
+      ['render-vars', 'no unresolved {{var}} placeholders'],
+      ['commands', 'referenced command files exist'],
+      ['budgets', 'registry line budgets obeyed'],
+      ['dead-docs', 'docs in scope are registered, referenced, or inbound-linked'],
+      ['archive-suggestions', 'registered canonical/owner docs scored for archive candidacy'],
+    ]) {
+      checks.push(skippedCheck(id, label, `${REGISTRY_PATH} absent — no registry scope`));
+    }
+    checks.push(await checkTemplates(root));
+    return summarize(checks);
+  }
+
+  // existsOnDisk equivalent (dir entries end '/'; resolve symlinks so dev
+  // mirrors count). Bound once for the registry check.
+  const fileExistsCache = new Map();
+  const fileExists = (rel) => {
+    if (fileExistsCache.has(rel)) return fileExistsCache.get(rel);
+    const p = rel.endsWith('/') ? rel.slice(0, -1) : rel;
+    const promise = fs
+      .realpath(path.join(root, p))
+      .then(() => true)
+      .catch(() => existsPath(path.join(root, p)));
+    fileExistsCache.set(rel, promise);
+    return promise;
+  };
+  const fileExistsSyncWrap = (rel) => {
+    // validateRegistryDoc is sync; warm the cache first for all referenced paths.
+    return fileExistsCache.get(rel) === true;
+  };
+
+  // Pre-warm existence cache for validation test paths + entry paths.
+  const warm = [];
+  for (const e of registry.entries || []) {
+    if (Array.isArray(e.validation)) {
+      for (const v of e.validation) if (typeof v === 'string' && v.startsWith('test:')) warm.push(v.slice(5));
+    }
+    if (typeof e.path === 'string') warm.push(e.path);
+    if (typeof e.source_of_truth === 'string') warm.push(e.source_of_truth);
+  }
+  await Promise.all(warm.map((rel) => fileExists(rel).then((r) => fileExistsCache.set(rel, r))));
+  for (const [k, v] of fileExistsCache) {
+    if (v instanceof Promise) {
+      const resolved = await v;
+      fileExistsCache.set(k, resolved);
+    }
+  }
+
+  checks.push(await checkRegistry(root, registry, fileExistsSyncWrap));
+  checks.push(await checkLinks(root, registry));
+  checks.push(await checkStaleVersion(root, registry));
+  checks.push(await checkRenderVars(root, registry));
+  checks.push(await checkCommands(root, registry));
+  checks.push(await checkBudgets(root, registry));
+  checks.push(await checkDeadDocs(root, registry));
+  checks.push(await checkArchiveSuggestions(root, registry, nowMs));
+  checks.push(await checkTemplates(root));
+
+  return summarize(checks);
+}
+
+function summarize(checks) {
+  const summary = { errors: 0, warnings: 0, passed: 0, skipped: 0 };
+  for (const c of checks) {
+    if (c.skipped) {
+      summary.skipped += 1;
+    } else if (c.passed) {
+      summary.passed += 1;
+    } else if (c.severity === 'error') {
+      summary.errors += 1;
+    } else {
+      summary.warnings += 1;
+    }
+  }
+  return { checks, summary };
+}