@ngockhoale/ukit 3.3.3 → 3.4.1

package/template_project/.claude/hooks/verification-guard.sh

@@ -62,7 +62,7 @@ STATE_FILE="$PROJECT_ROOT/.claude/ukit/skill-router-state.json"
 ROUTE_CACHE_FILE="$PROJECT_ROOT/.claude/ukit/route-cache.json"
 PROGRESS_FILE="$PROJECT_ROOT/.claude/ukit/verification-progress.json"
 
-INPUT_FILE="$UKIT_INPUT_FILE" STATE_FILE="$STATE_FILE" ROUTE_CACHE_FILE="$ROUTE_CACHE_FILE" PROGRESS_FILE="$PROGRESS_FILE" UKIT_RUNTIME_DIR="$SCRIPT_DIR/../ukit/runtime" node <<'NODE'
+INPUT_FILE="$UKIT_INPUT_FILE" STATE_FILE="$STATE_FILE" ROUTE_CACHE_FILE="$ROUTE_CACHE_FILE" PROGRESS_FILE="$PROGRESS_FILE" UKIT_RUNTIME_DIR="$SCRIPT_DIR/../ukit/runtime" PROJECT_ROOT="$PROJECT_ROOT" node <<'NODE'
 const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10) || 3000;
 const LOCK_STARTED_AT = Date.now();
 // SPEC §8: a timed-out gate silently passes work it never evaluated — announce the
@@ -88,6 +88,7 @@ setTimeout(() => {
 const fs = require('fs').promises;
 const path = require('path');
 const { pathToFileURL } = require('url');
+const { execFileSync } = require('child_process');
 
 async function readJson(filePath, fallback = null) {
   try {
@@ -403,6 +404,234 @@ if (typeof state?.ts === 'number' && stateAgeMs > STATE_FRESH_MS) {
   process.exit(0);
 }
 
+// --- BL-010 (TASK-008): small-feature done-criteria receipt classes ------------
+// On a `fastPathKind: small-feature` route the guard observes the two
+// done-criteria receipt classes (wired-into-usage, surface-check) and records
+// the latest status as an advisory `playbook-finding` receipt in the
+// exec-ledger. Findings never block (P2 GO gate `false-block = 0`) — docs-only
+// or non-feature routes skip the whole block.
+const runtimeDir = process.env.UKIT_RUNTIME_DIR || '';
+let ledgerModulePromise = null;
+function loadLedgerModule() {
+  if (!ledgerModulePromise) {
+    ledgerModulePromise = (async () => {
+      const modulePath = runtimeDir ? path.join(runtimeDir, 'execution-ledger.mjs') : '';
+      if (!modulePath) return null;
+      try {
+        await fs.access(modulePath);
+        return await import(pathToFileURL(modulePath).href);
+      } catch {
+        return null;
+      }
+    })();
+  }
+  return ledgerModulePromise;
+}
+
+const NEW_SOURCE_FILE_RE = /\.(jsx?|tsx?|mjs|cjs|vue|svelte|css|scss|sass|less|html)$/i;
+
+// `git status --porcelain` positions: untracked entries start '??', index-staged
+// adds start 'A'. Both are "component-create" candidates for the wiring check.
+function readGitChangedPaths(projectRoot) {
+  try {
+    const out = execFileSync('git', ['status', '--porcelain', '--untracked-files=all'], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      timeout: 1500,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return out.split('\n').map((line) => line.trim()).filter(Boolean);
+  } catch {
+    return null;
+  }
+}
+
+async function readSessionLedger(projectRoot, payload, ledgerModule) {
+  try {
+    if (ledgerModule && typeof ledgerModule.readExecutionLedger === 'function') {
+      return await ledgerModule.readExecutionLedger(projectRoot, payload);
+    }
+  } catch {}
+  try {
+    const sessionId = String(payload?.session_id || payload?.sessionId || 'default')
+      .trim().replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 96) || 'default';
+    return await readJson(path.join(
+      projectRoot, '.ukit', 'storage', 'cache', 'exec-ledger', `${sessionId}.json`,
+    ), null);
+  } catch {
+    return null;
+  }
+}
+
+async function observeSmallFeatureDoneCriteria({ projectRoot, payload, state }) {
+  const route = state?.routeSummary;
+  if (!route || (route.fastPathKind !== 'small-feature' && route.playbookId !== 'small-feature')) {
+    return;
+  }
+  const ledgerModule = await loadLedgerModule();
+  const ledger = await readSessionLedger(projectRoot, payload, ledgerModule);
+  const gitLines = readGitChangedPaths(projectRoot);
+  const newSourceFiles = gitLines === null ? [] : gitLines
+    .filter((line) => (line.startsWith('??') || line.startsWith('A')) && NEW_SOURCE_FILE_RE.test(line))
+    .map((line) => line.replace(/^(..)\s+/, ''))
+    // Rename lines carry "old -> new"; keep the destination only.
+    .map((entry) => entry.split(' -> ').pop());
+  const existingFileChanges = gitLines === null ? [] : gitLines
+    .filter((line) => !line.startsWith('??') && /^[MDRCTU]/.test(line));
+  const hasBuildEvidence = ledger?.writeAttempted === true || newSourceFiles.length > 0;
+  if (!hasBuildEvidence) return;
+
+  const observations = [];
+  // wired-into-usage: a created component with no change to any tracked file is
+  // the named cheat — nothing reaches it. Only observed when git answers; an
+  // absent repo yields no finding rather than a fabricated one.
+  if (gitLines !== null) {
+    if (newSourceFiles.length > 0 && existingFileChanges.length === 0) {
+      observations.push({
+        class: 'wired-into-usage',
+        status: 'missing',
+        detail: `new source file ${newSourceFiles[0]} with no tracked-file wiring edit`,
+        file: newSourceFiles[0],
+      });
+    } else if (newSourceFiles.length > 0) {
+      observations.push({
+        class: 'wired-into-usage',
+        status: 'satisfied',
+        detail: `new source file ${newSourceFiles[0]} plus ${existingFileChanges.length} tracked change(s)`,
+        file: newSourceFiles[0],
+      });
+    }
+  }
+  // surface-check: build-pass proves nothing — a verification receipt must land.
+  observations.push({
+    class: 'surface-check',
+    status: ledger?.verificationAttempted === true ? 'satisfied' : 'missing',
+    detail: ledger?.verificationAttempted === true
+      ? 'verification attempted on this ledger'
+      : 'no verification receipt recorded yet',
+  });
+
+  if (!ledgerModule || typeof ledgerModule.recordLedgerEvent !== 'function') return;
+  for (const observation of observations) {
+    try {
+      await ledgerModule.recordLedgerEvent(
+        {
+          type: 'receipt',
+          receipt: {
+            ts: Date.now(),
+            kind: 'playbook-finding',
+            success: true,
+            class: observation.class,
+            status: observation.status,
+            detail: observation.detail,
+            file: observation.file || null,
+          },
+        },
+        {
+          projectRoot,
+          payload,
+          harness: process.env.UKIT_HARNESS || 'claude',
+          routeState: state,
+          deadlineMs: Math.min(800, Math.max(200, HOOK_DEADLINE_MS - 400)),
+        },
+      );
+    } catch {
+      // Advisory finding — a failed write must never affect the command path.
+    }
+  }
+}
+
+await observeSmallFeatureDoneCriteria({
+  projectRoot: process.env.PROJECT_ROOT || process.cwd(),
+  payload,
+  state,
+});
+
+// --- BL-014 (TASK-C85-014): verification-map recipe findings ---------------
+// The guard consults the same verification-map the stop gate consumes: the
+// artifact class of the current change resolves a recipe whose
+// evidenceRequired[] classes become `recipe-evidence` playbook-finding
+// receipts (latest status banked per class). Unclassifiable diffs and
+// missing/malformed maps yield NO recipe → existing behavior unchanged.
+// Findings stay advisory — the guard never hard-blocks.
+const UKIT_INDEX_DIR = path.join(runtimeDir || '.', '..', 'index');
+let verificationMapModulePromise = null;
+function loadVerificationMapModule() {
+  if (!verificationMapModulePromise) {
+    verificationMapModulePromise = (async () => {
+      const modulePath = path.join(UKIT_INDEX_DIR, 'verification-map.mjs');
+      try {
+        await fs.access(modulePath);
+        return await import(pathToFileURL(modulePath).href);
+      } catch {
+        return null;
+      }
+    })();
+  }
+  return verificationMapModulePromise;
+}
+
+async function observeVerificationRecipe({ projectRoot, payload, state }) {
+  const route = state?.routeSummary;
+  const playbookId = route?.playbookId || null;
+  if (!playbookId) return; // no playbook route → no recipe consult at all
+  const mapModule = await loadVerificationMapModule();
+  if (!mapModule) return;
+
+  const gitLines = readGitChangedPaths(projectRoot);
+  if (gitLines === null) return; // no git answer → no classification, no recipe
+  const changedPaths = gitLines.map((line) => line.replace(/^(..)\s+/, ''));
+  const artifactClass = mapModule.classifyArtifactClass(changedPaths);
+  if (!artifactClass) return; // unknown class → pre-map behavior (case 5)
+
+  const map = await mapModule.loadVerificationMap({ projectRoot });
+  if (!map) return; // absent/malformed map → fail closed, no recipe
+  const recipe = await mapModule.recipeForArtifact({ playbookId, artifactClass, map });
+  if (!recipe || !Array.isArray(recipe.evidenceRequired) || recipe.evidenceRequired.length === 0) {
+    return; // recipe resolved but demands nothing (e.g. docs)
+  }
+
+  const ledgerModule = await loadLedgerModule();
+  const ledger = await readSessionLedger(projectRoot, payload, ledgerModule);
+  if (!ledgerModule || typeof ledgerModule.recordLedgerEvent !== 'function') return;
+
+  for (const requiredClass of recipe.evidenceRequired) {
+    const satisfied = mapModule.receiptEvidenceSatisfied(requiredClass, ledger || {});
+    try {
+      await ledgerModule.recordLedgerEvent(
+        {
+          type: 'receipt',
+          receipt: {
+            ts: Date.now(),
+            kind: 'playbook-finding',
+            success: true,
+            class: requiredClass,
+            status: satisfied ? 'satisfied' : 'missing',
+            detail: satisfied
+              ? `recipe ${artifactClass}: receipt class ${requiredClass} satisfied`
+              : `recipe ${artifactClass}: receipt class ${requiredClass} not yet evidenced — check: ${recipe.check || 'run the recipe check'}${recipe.fallback ? `; fallback: ${recipe.fallback}` : ''}`,
+          },
+        },
+        {
+          projectRoot,
+          payload,
+          harness: process.env.UKIT_HARNESS || 'claude',
+          routeState: state,
+          deadlineMs: Math.min(800, Math.max(200, HOOK_DEADLINE_MS - 400)),
+        },
+      );
+    } catch {
+      // Advisory finding — a failed write must never affect the command path.
+    }
+  }
+}
+
+await observeVerificationRecipe({
+  projectRoot: process.env.PROJECT_ROOT || process.cwd(),
+  payload,
+  state,
+});
+
 const primaryCommands = unique((
   routeSummary?.primaryCommands?.length
     ? routeSummary.primaryCommands

package/template_project/.claude/settings.json

@@ -160,8 +160,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/project-important.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/auto-prune-bash.sh\":12 \"$CLAUDE_PROJECT_DIR/.claude/hooks/reset-compact-pressure.sh\":12 \"$CLAUDE_PROJECT_DIR/.claude/hooks/handoff-resume.sh\":8",
-            "timeout": 50
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/project-important.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/auto-prune-bash.sh\":12 \"$CLAUDE_PROJECT_DIR/.claude/hooks/reset-compact-pressure.sh\":12 \"$CLAUDE_PROJECT_DIR/.claude/hooks/handoff-resume.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/observability-emit.mjs\":8",
+            "timeout": 60
           }
         ]
       }

package/template_project/.claude/ukit/index/cross-check-matrix.mjs

@@ -0,0 +1,415 @@
+// cross-check-matrix.mjs — parity-locked mirror of src/index/crossCheckMatrix.js
+// (BL-016 / SPEC FR-004 / ARCH §Adaptive Cross-Check). Mirrors never import
+// src/; tests/consistency/crossCheckParity.test.js locks the export surface,
+// the matrix rows, and identical {depth, reasons[]} on shared fixtures.
+// Keep logic identical.
+//
+// Verification depth scales with risk instead of being uniform — a separate
+// dimension from implementation depth (fast path vs full workflow). This
+// module is deterministic and pure: it resolves
+//
+//   change-risk × implementer-reliability × evidence-quality
+//     → none | runnable | review-round | escalate
+//
+// and the result feeds the review policy's `escalationDepth` input slot
+// (src/index/reviewPolicy.js), which maps depth → action floor.
+//
+// Contract (SPEC §8):
+//   resolveCrossCheckDepth({riskFloor?, rigor?, implementerReliability?,
+//     evidenceQuality?, reviewer?, implementer?, runnable?, role?, model?,
+//     project?, overrides?}) → {depth, reasons[]}
+//
+// Invariants from ARCH §Adaptive Cross-Check:
+//   * high change-risk overrides implementer reliability — a strong model on
+//     an auth/data-path change still escalates to mandatory review.
+//   * a reviewer of the SAME model family is not independent review — a
+//     same-family re-read never satisfies a review-round; the depth demotes
+//     to `runnable` with the limit stated in reasons[].
+//   * no reviewer → `runnable` where possible + honest stated limit; the
+//     caller reports INCONCLUSIVE when nothing is runnable (the depth enum
+//     cannot return INCONCLUSIVE — it names a depth, not a verdict).
+//   * implementer-reliability is a joined outcome signal, never a model-name
+//     verdict — absent or unrecognized input resolves to baseline-neutral
+//     'unknown' (GAP M13).
+//   * `crossCheck.{role|model}×{project}` maintainer overrides may tighten or
+//     loosen within the enum; malformed overrides are ignored, never fatal.
+//
+// Parity: tests/consistency/crossCheckParity.test.js locks this module and
+// the installed mirror to identical exports, identical matrix rows, and
+// identical {depth, reasons[]} on shared fixtures.
+
+// Ordered by severity — override clamping and floor comparisons rely on the
+// index order, so consumers must never reorder this list.
+export const CROSS_CHECK_DEPTHS = Object.freeze([
+  'none',
+  'runnable',
+  'review-round',
+  'escalate',
+]);
+
+export const CROSS_CHECK_RISK_LEVELS = Object.freeze(['low', 'medium', 'high']);
+
+export const CROSS_CHECK_RELIABILITY_LEVELS = Object.freeze([
+  'trusted',
+  'needs-oversight',
+  'unknown',
+]);
+
+export const CROSS_CHECK_EVIDENCE_QUALITIES = Object.freeze([
+  'strong',
+  'thin',
+  'missing-hooks',
+]);
+
+// The ARCH §Adaptive Cross-Check matrix verbatim (7 rows). 'any' is a
+// wildcard. First matching row wins, which gives the two 'any'-wildcard rows
+// their precedence: high-risk escalate beats everything; missing-hooks
+// degrade applies to whatever remains.
+export const CROSS_CHECK_MATRIX = Object.freeze([
+  { risk: 'low', reliability: 'trusted', evidence: 'strong', depth: 'none' },
+  { risk: 'low', reliability: 'needs-oversight', evidence: 'thin', depth: 'review-round' },
+  { risk: 'low', reliability: 'unknown', evidence: 'strong', depth: 'runnable' },
+  { risk: 'medium', reliability: 'trusted', evidence: 'strong', depth: 'runnable' },
+  { risk: 'medium', reliability: 'needs-oversight', evidence: 'any', depth: 'review-round' },
+  { risk: 'high', reliability: 'any', evidence: 'any', depth: 'escalate' },
+  { risk: 'any', reliability: 'any', evidence: 'missing-hooks', depth: 'runnable' },
+]);
+
+// Cells the matrix does not list resolve conservatively: needs-oversight on
+// a low/medium-risk change is the row-2/row-5 signal family, so it still
+// earns a review round; trusted and baseline-neutral reliability never drop
+// below `runnable` on unlisted cells — thin evidence can never justify `none`.
+const RELIABILITY_RESIDUAL = Object.freeze({
+  'needs-oversight': 'review-round',
+});
+
+// Bounded maintainer override shapes: a bound leaf carries only these keys
+// (validated in src/core/runtimeConfig.js); all other top-level keys of the
+// section are reserved.
+const BOUND_KEYS = new Set(['depth', 'minDepth', 'maxDepth']);
+const CROSS_CHECK_SECTION_KEYS = new Set(['enabled', 'byRole', 'byModel']);
+
+const MAX_ID_LENGTH = 96;
+
+const RISK_ALIASES = Object.freeze({
+  high: 'high',
+  'high-risk': 'high',
+  critical: 'high',
+  medium: 'medium',
+  moderate: 'medium',
+  low: 'low',
+  none: 'low',
+  trivial: 'low',
+});
+
+const RELIABILITY_ALIASES = Object.freeze({
+  trusted: 'trusted',
+  'needs-oversight': 'needs-oversight',
+  unknown: 'unknown',
+  baseline: 'unknown',
+  'baseline-neutral': 'unknown',
+});
+
+// Receipt classes attesting real-run/surface evidence vs build-only or
+// claimed-only work (ARCH: evidence-quality is about receipt classes present,
+// never about what the agent asserts).
+const STRONG_EVIDENCE_TOKENS = new Set([
+  'strong',
+  'surface-check',
+  'render-observation',
+  'io-run',
+  'run-receipt',
+  'real-run',
+  'verification-evidence',
+  'write-evidence',
+]);
+const THIN_EVIDENCE_TOKENS = new Set([
+  'thin',
+  'build-only',
+  'claimed',
+  'claimed-only',
+  'log',
+]);
+const MISSING_HOOKS_TOKENS = new Set([
+  'missing-hooks',
+  'unavailable',
+  'cannot-produce',
+]);
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function depthIndex(depth) {
+  return CROSS_CHECK_DEPTHS.indexOf(depth);
+}
+
+function boundedId(value) {
+  return typeof value === 'string' && value.trim()
+    ? value.trim().slice(0, MAX_ID_LENGTH)
+    : null;
+}
+
+// ─── input normalization ────────────────────────────────────────────────────
+
+// riskFloor arrives as the route record's {floor:'none'|'high-risk', codes[]},
+// a bare enum/code string, or a level name. `rigor` (R0-R4) only ever RAISES
+// the floor: R3+ ceremony on a non-floor route still counts as medium risk —
+// the router asked for deep work, so verification follows.
+function normalizeRisk(riskFloor, rigor) {
+  let risk = 'low';
+  if (typeof riskFloor === 'string') {
+    risk = RISK_ALIASES[riskFloor.trim().toLowerCase()] ?? 'low';
+  } else if (isPlainObject(riskFloor)) {
+    const floor = typeof riskFloor.floor === 'string'
+      ? riskFloor.floor.trim().toLowerCase()
+      : null;
+    if (RISK_ALIASES[floor]) {
+      risk = RISK_ALIASES[floor];
+    } else if (typeof riskFloor.risk === 'string') {
+      risk = RISK_ALIASES[riskFloor.risk.trim().toLowerCase()] ?? 'low';
+    }
+  }
+  if (risk === 'low' && typeof rigor === 'string') {
+    const level = /^r(\d)$/i.exec(rigor.trim());
+    if (level && Number(level[1]) >= 3) risk = 'medium';
+  }
+  return risk;
+}
+
+// Reliability is joined outcome data, never a model-name verdict: anything
+// absent or unrecognized collapses to baseline-neutral 'unknown'.
+function normalizeReliability(value) {
+  if (typeof value !== 'string') return 'unknown';
+  return RELIABILITY_ALIASES[value.trim().toLowerCase()] ?? 'unknown';
+}
+
+function normalizeEvidenceQuality(value) {
+  if (value == null) return 'thin';
+  if (Array.isArray(value)) {
+    if (value.length === 0) return 'thin';
+    const tokens = value
+      .filter((token) => typeof token === 'string' && token.trim())
+      .map((token) => token.trim().toLowerCase());
+    if (tokens.some((token) => MISSING_HOOKS_TOKENS.has(token))) return 'missing-hooks';
+    if (tokens.some((token) => STRONG_EVIDENCE_TOKENS.has(token))) return 'strong';
+    return 'thin';
+  }
+  if (typeof value === 'string') {
+    const token = value.trim().toLowerCase();
+    if (MISSING_HOOKS_TOKENS.has(token)) return 'missing-hooks';
+    if (STRONG_EVIDENCE_TOKENS.has(token)) return 'strong';
+    return 'thin';
+  }
+  if (isPlainObject(value)) {
+    if (typeof value.quality === 'string') return normalizeEvidenceQuality(value.quality);
+    if (Array.isArray(value.classes)) return normalizeEvidenceQuality(value.classes);
+  }
+  return 'thin';
+}
+
+// ─── reviewer independence ──────────────────────────────────────────────────
+// A review-round only counts when a reviewer of a DIFFERENT model family
+// exists — same-family re-reads and self re-reads are not independent review
+// (SPEC FR-004). A reviewer descriptor that supplies no family cannot be
+// proven same or different; it is treated as independent but the assumption
+// is named in the reasons so the receipt stays honest.
+function reviewerIndependence(reviewer, implementer) {
+  if (!isPlainObject(reviewer)) {
+    return { independent: false, reason: 'no reviewer available' };
+  }
+  const reviewerFamily = boundedId(reviewer.modelFamily) ?? boundedId(reviewer.family);
+  const reviewerModel = boundedId(reviewer.model) ?? boundedId(reviewer.id) ?? boundedId(reviewer.name);
+  const implementerFamily = isPlainObject(implementer)
+    ? (boundedId(implementer.modelFamily) ?? boundedId(implementer.family))
+    : null;
+  const implementerModel = isPlainObject(implementer)
+    ? (boundedId(implementer.model) ?? boundedId(implementer.id) ?? boundedId(implementer.name))
+    : null;
+  if (reviewerModel && implementerModel && reviewerModel === implementerModel) {
+    return { independent: false, reason: 'reviewer is the implementer re-reading its own diff — not independent' };
+  }
+  if (reviewerFamily && implementerFamily && reviewerFamily === implementerFamily) {
+    return { independent: false, reason: 'same-model-family reviewer is not independent review' };
+  }
+  return {
+    independent: true,
+    reason: reviewerFamily
+      ? 'different-model-family reviewer available'
+      : 'reviewer family unproven — assuming independent',
+  };
+}
+
+// ─── maintainer overrides ───────────────────────────────────────────────────
+// `crossCheck.{role|model}×{project}` bounded overrides, per ARCH §Config:
+// enum-only, shipped ON. A bound leaf is {depth|minDepth|maxDepth}; an entry
+// may also be a project map {projectId|'*': bound}. byRole wins over byModel;
+// a project-named leaf wins over the '*' leaf of the same entry. Unknown
+// shapes are ignored with a reason — a maintainer typo must never crash the
+// route nor invent a depth outside the enum.
+function boundLeaf(entry) {
+  if (!isPlainObject(entry)) return null;
+  if (Object.keys(entry).some((key) => BOUND_KEYS.has(key))) return entry;
+  return null;
+}
+
+function resolveOverrideBound(overrides, { role = null, model = null, project = null }) {
+  if (!isPlainObject(overrides) || overrides.enabled === false) return null;
+  const maps = [
+    ['role', role, overrides.byRole],
+    ['model', model, overrides.byModel],
+  ];
+  for (const [kind, name, map] of maps) {
+    if (!name || !isPlainObject(map)) continue;
+    const entry = map[name];
+    if (entry === undefined) continue;
+    const direct = boundLeaf(entry);
+    if (direct) {
+      return { bound: direct, label: `${kind} "${name}"` };
+    }
+    if (isPlainObject(entry)) {
+      const projectLeaf = project ? boundLeaf(entry[project]) : null;
+      const starLeaf = boundLeaf(entry['*']);
+      const picked = projectLeaf ?? starLeaf;
+      if (picked) {
+        return {
+          bound: picked,
+          label: `${kind} "${name}"${projectLeaf ? ` project "${project}"` : ''}`,
+        };
+      }
+    }
+    return { bound: null, label: `${kind} "${name}"` };
+  }
+  // A bare bound ({depth:…} / {minDepth:…} / {maxDepth:…}) applies directly.
+  const direct = boundLeaf(overrides);
+  if (direct) return { bound: direct, label: 'crossCheck' };
+  return null;
+}
+
+// ─── resolver ───────────────────────────────────────────────────────────────
+
+export function resolveCrossCheckDepth({
+  riskFloor = null,
+  rigor = null,
+  implementerReliability = null,
+  evidenceQuality = null,
+  reviewer = undefined,
+  implementer = null,
+  runnable = true,
+  role = null,
+  model = null,
+  project = null,
+  overrides = null,
+} = {}) {
+  const reasons = [];
+  const risk = normalizeRisk(riskFloor, rigor);
+  const reliability = normalizeReliability(implementerReliability);
+  const evidence = normalizeEvidenceQuality(evidenceQuality);
+
+  if (implementerReliability == null
+    || (typeof implementerReliability === 'string'
+      && RELIABILITY_ALIASES[implementerReliability.trim().toLowerCase()] === undefined)) {
+    reasons.push(
+      'implementerReliability unresolved — defaulting to project-baseline neutral '
+      + '("unknown"); reliability is a joined outcome signal, never a model-name verdict',
+    );
+  }
+
+  let depth = null;
+  let decidingRow = null;
+  for (const row of CROSS_CHECK_MATRIX) {
+    if ((row.risk === 'any' || row.risk === risk)
+      && (row.reliability === 'any' || row.reliability === reliability)
+      && (row.evidence === 'any' || row.evidence === evidence)) {
+      depth = row.depth;
+      decidingRow = row;
+      break;
+    }
+  }
+
+  if (depth) {
+    const index = CROSS_CHECK_MATRIX.indexOf(decidingRow) + 1;
+    reasons.push(
+      `matrix row ${index}: risk=${decidingRow.risk === 'any' ? risk : decidingRow.risk} × `
+      + `reliability=${decidingRow.reliability === 'any' ? reliability : decidingRow.reliability} × `
+      + `evidence=${decidingRow.evidence === 'any' ? evidence : decidingRow.evidence} → ${decidingRow.depth}`,
+    );
+    if (decidingRow.risk === 'high') {
+      reasons.push('high change-risk overrides implementer reliability — mandatory review regardless of track record');
+    }
+    if (decidingRow.evidence === 'missing-hooks') {
+      reasons.push(
+        'engine cannot produce a needed receipt class (missing hooks) — runnable '
+        + 'checks where possible + honest stated limit; INCONCLUSIVE if nothing runnable',
+      );
+    }
+  } else {
+    depth = RELIABILITY_RESIDUAL[reliability] ?? 'runnable';
+    reasons.push(
+      `no verbatim matrix row for risk=${risk} × reliability=${reliability} × evidence=${evidence} — `
+      + `residual rule resolves ${depth} (needs-oversight still earns a review round; `
+      + 'trusted/baseline never drops below runnable)',
+    );
+  }
+
+  // Reviewer independence only demotes the review-round depth: the matrix
+  // chose it for the signal, but without a different-family reviewer a
+  // same-family or self re-read is not independent review. 'escalate' is a
+  // mandatory hand-off — it never silently downgrades; the reason names the
+  // missing reviewer so the consumer escalates to a human or another lane.
+  const independence = reviewerIndependence(reviewer, implementer);
+  if (depth === 'review-round' && !independence.independent) {
+    reasons.push(`${independence.reason} — review-round demoted to runnable checks + stated limit`);
+    depth = 'runnable';
+    if (runnable === false) {
+      reasons.push('nothing runnable — report INCONCLUSIVE');
+    }
+  } else if (depth === 'review-round') {
+    reasons.push(independence.reason);
+  } else if (depth === 'escalate' && !independence.independent) {
+    reasons.push(
+      `${independence.reason} — escalate stands: mandatory review requires a `
+      + 'different-family reviewer or human sign-off, never a silent downgrade',
+    );
+  }
+
+  // Maintainer overrides bound the resolved depth last. A 'depth' pin wins;
+  // minDepth/maxDepth clamp within the enum. Invalid bound values are ignored
+  // with a named reason — schema validation in runtimeConfig.js rejects them
+  // at parse time; this guard covers programmatic callers.
+  const resolved = resolveOverrideBound(overrides, { role, model, project });
+  if (resolved && resolved.bound) {
+    const bound = resolved.bound;
+    let applied = null;
+    if (typeof bound.depth === 'string' && CROSS_CHECK_DEPTHS.includes(bound.depth)) {
+      depth = bound.depth;
+      applied = `depth=${bound.depth}`;
+    } else {
+      if (typeof bound.maxDepth === 'string'
+        && CROSS_CHECK_DEPTHS.includes(bound.maxDepth)
+        && depthIndex(depth) > depthIndex(bound.maxDepth)) {
+        depth = bound.maxDepth;
+        applied = `maxDepth=${bound.maxDepth}`;
+      }
+      if (typeof bound.minDepth === 'string'
+        && CROSS_CHECK_DEPTHS.includes(bound.minDepth)
+        && depthIndex(depth) < depthIndex(bound.minDepth)) {
+        depth = bound.minDepth;
+        applied = applied ? `${applied} + minDepth=${bound.minDepth}` : `minDepth=${bound.minDepth}`;
+      }
+    }
+    if (applied) {
+      reasons.push(`crossCheck override (${resolved.label}) applied: ${applied} → ${depth}`);
+    } else {
+      reasons.push(`crossCheck override (${resolved.label}) present but no enum bound applied`);
+    }
+  } else if (resolved) {
+    reasons.push(`crossCheck override (${resolved.label}) has no valid enum bound — ignored`);
+  } else if (isPlainObject(overrides) && Object.keys(overrides).some(
+    (key) => !CROSS_CHECK_SECTION_KEYS.has(key) && !BOUND_KEYS.has(key),
+  )) {
+    reasons.push('crossCheck override keys unrecognized — ignored');
+  }
+
+  return { depth, reasons };
+}