@ngockhoale/ukit 3.3.3 → 3.4.1

package/src/index/reviewPolicy.js

@@ -0,0 +1,368 @@
+// reviewPolicy.js — deterministic review decision policy evaluator (BL-015 /
+// SPEC FR-003 / ARCH §Review Decision Policy).
+//
+// The evaluator answers "is one more verification round needed?" at checkpoints
+// — playbook step boundaries and the pre-Stop gate (stop-coordinator.mjs) —
+// from checkable signals only. It is the TRIGGER for the existing review lane
+// (`review-verdict.mjs` + `review-panel-aggregate.mjs`, GAP M05 reuse), never a
+// new reviewer and never a second gate: consumers record the verdict as an
+// advisory while the completion gate stays the single Stop authority.
+//
+// Contract:
+//   evaluateReviewPolicy({signals, doneCriteria, evidenceClasses, fixLoopCount,
+//     round, cap, escalationDepth?, crossCheck?, projectRoot?,
+//     appendDecisionReceipt?})
+//   → {action, namedCheck?, signalsHit[], rationale, reviewRounds,
+//      verified[], notVerified[], missingEvidence[]}
+//
+//   action ∈ REVIEW_POLICY_ACTIONS — exactly five:
+//     'finish'               stop; done predicates evidenced, no suspicion.
+//     'run-targeted-check'   name the command/surface + predicate to satisfy.
+//     'independent-review'   name what the reviewer must verify; the caller
+//                            bundles {original request, diff, context files,
+//                            run evidence} for the review-verdict lane — never
+//                            the agent's summary alone (SPEC FR-004d).
+//     'escalate'             name the deeper lane/question (unic-decision
+//                            laneDeepening/verificationDepth family) or the
+//                            human authorization boundary. Terminal hand-off:
+//                            it is NOT another round, so the cap never traps it.
+//     'inconclusive'         honest stop: report verified-vs-not, name the
+//                            missing evidence. Round cap + timeout land here —
+//                            never an infinite block.
+//
+// Safety boundary (ARCH §Safety boundary): no self-declared confidence exists
+// in the input contract — keys like `confidence`/`statedConfidence` are ignored
+// by design, so identical signal sets decide identically whether or not the
+// agent narrates certainty.
+//
+// Calibration (ARCH §Calibration plan): when a caller supplies `projectRoot` +
+// an `appendDecisionReceipt` implementation (execution-ledger.mjs signature,
+// consumed unchanged), every evaluation emits one `kind:'review-policy'`
+// receipt carrying action + namedCheck + signalsHit + round so decision↔outcome
+// joins can measure unnecessary-review and escaped-defect rates.
+//
+// Parity: tests/consistency/reviewPolicyParity.test.js locks this module and
+// the installed mirror to identical exports and identical verdicts.
+
+import { resolveCrossCheckDepth } from './crossCheckMatrix.js';
+
+// Exactly five actions — the closed enum consumers may switch on.
+export const REVIEW_POLICY_ACTIONS = Object.freeze([
+  'finish',
+  'run-targeted-check',
+  'independent-review',
+  'escalate',
+  'inconclusive',
+]);
+
+// Action severity for multi-signal precedence and the escalationDepth bias.
+// A higher-severity fired signal wins the action; the namedCheck travels with
+// the winning signal.
+const ACTION_SEVERITY = Object.freeze({
+  finish: 0,
+  'run-targeted-check': 1,
+  'independent-review': 2,
+  escalate: 3,
+  inconclusive: 0,
+});
+
+// Suspicion signal → action the policy fires. 'targeted' resolves to
+// 'run-targeted-check', 'review' to 'independent-review'.
+const SIGNAL_ACTION = Object.freeze({
+  targeted: 'run-targeted-check',
+  review: 'independent-review',
+  escalate: 'escalate',
+});
+
+// The 8-signal suspicion catalogue (ARCH §Suspicion-signal catalogue), kept as
+// data so calibration + docs share one list. `check` names the exact check the
+// action demands — command/surface + predicate, or what the reviewer verifies.
+export const SUSPICION_SIGNAL_CATALOGUE = Object.freeze([
+  {
+    id: 'unchecked-request-details',
+    fires: 'targeted',
+    check: 'cross-check every request detail against the diff — each stated requirement must have a corresponding hunk or an explicit, evidenced skip',
+  },
+  {
+    id: 'wider-than-goal',
+    fires: 'review',
+    check: 'independent reviewer verifies each out-of-scope hunk is either required for the stated goal or reverted',
+  },
+  {
+    id: 'unwired-component',
+    fires: 'targeted',
+    check: 'verify the component is reachable in the usage flow — import/callsite present + render/import observation, not just a file on disk',
+  },
+  {
+    id: 'claimed-verification',
+    fires: 'targeted',
+    check: 're-run the claimed verification and require verbatim captured output — a claimed pass with no output is not evidence',
+  },
+  {
+    id: 'impl-detail-tests-only',
+    fires: 'targeted',
+    check: 'run one concrete behavioral input→output case per public entry point — tests asserting internals cannot catch user-visible failure',
+  },
+  {
+    id: 'tool-error-storm',
+    fires: 'review',
+    check: 'independent reviewer checks whether the unexplained tool errors mask a real (often environment-dependent) defect',
+  },
+  {
+    id: 'fix-loop-same-fingerprint',
+    fires: 'escalate',
+    check: 'fire the unic-decision laneDeepening/verificationDepth question → deeper debug lane (runtime-forensics for a live symptom, systematic-debugging depth otherwise); never another same-lane retry',
+  },
+  {
+    id: 'unconfirmed-assumptions',
+    fires: 'review',
+    check: 'independent reviewer verifies the unconfirmed assumptions the run carried to done — each must be confirmed or named as a stated limit',
+  },
+]);
+
+// Catalogue ids callers may assert through `signals` (object-map or array).
+// Derived signals (`claimed-verification`, `fix-loop-same-fingerprint`) share
+// the same catalogue — the caller never has to restate what the inputs already
+// prove.
+const SIGNAL_ID_SET = new Set(SUSPICION_SIGNAL_CATALOGUE.map((s) => s.id));
+
+// Round-cap default: one initial check + one re-check round is the ARCH
+// "one round default-sufficient for small tasks" bound. Every check-driven
+// loop must land `inconclusive` at the cap, never retry forever.
+export const DEFAULT_REVIEW_ROUND_CAP = 2;
+
+// Same-fingerprint fix-loop threshold — aligned with the route layer's
+// debugLoopThreshold default (runtimeConfig.js:379). fixLoopCount ≥ threshold
+// derives suspicion signal #7 and routes to `escalate`.
+export const DEFAULT_FIX_LOOP_THRESHOLD = 2;
+
+// escalationDepth (forward-declared slot for TASK-C85-016's depth matrix):
+// {depth, reasons[]?} or a bare depth string. The depth matrix may only RAISE
+// the action floor — it never suppresses a fired suspicion signal.
+const DEPTH_MIN_ACTION = Object.freeze({
+  none: 'finish',
+  runnable: 'run-targeted-check',
+  'review-round': 'independent-review',
+  escalate: 'escalate',
+});
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function clampInt(value, fallback, min = 0, max = 99) {
+  const n = Number(value);
+  return Number.isFinite(n) ? Math.max(min, Math.min(max, Math.trunc(n))) : fallback;
+}
+
+// doneCriteria entry → {name, status}. Statuses:
+//   'verified' — a real-run/surface receipt attests the predicate.
+//   'claimed'  — asserted with no captured output (suspicion signal #4).
+//   'missing'  — no evidence at all.
+// Bare strings and `{satisfied:true}` shorthands normalize so callers can pass
+// the completion contract's bare class tokens when they have nothing richer.
+function normalizeDoneCriterion(entry) {
+  if (typeof entry === 'string' && entry.trim()) {
+    return { name: entry.trim(), status: 'missing' };
+  }
+  if (!isPlainObject(entry)) return null;
+  const name = typeof entry.name === 'string' && entry.name.trim()
+    ? entry.name.trim()
+    : (typeof entry.id === 'string' && entry.id.trim() ? entry.id.trim() : null);
+  if (!name) return null;
+  let status = typeof entry.status === 'string' ? entry.status.trim().toLowerCase() : null;
+  if (status !== 'verified' && status !== 'claimed') {
+    status = entry.satisfied === true || entry.verified === true ? 'verified' : 'missing';
+  }
+  return { name, status };
+}
+
+// signals may arrive as an object map ({'unwired-component': true, ...}) or an
+// array of catalogue ids. Only catalogue keys with a truthy flag count — a
+// caller cannot inject self-declared confidence or invent signals, and a
+// `confidence: 'sure'` key is silently ignored by design.
+function assertedSignalIds(signals) {
+  const ids = new Set();
+  if (Array.isArray(signals)) {
+    for (const id of signals) {
+      if (typeof id === 'string' && SIGNAL_ID_SET.has(id)) ids.add(id);
+    }
+  } else if (isPlainObject(signals)) {
+    for (const [id, flag] of Object.entries(signals)) {
+      if (flag && SIGNAL_ID_SET.has(id)) ids.add(id);
+    }
+  }
+  return ids;
+}
+
+function escalationDepthAction(escalationDepth) {
+  const depth = typeof escalationDepth === 'string'
+    ? escalationDepth
+    : escalationDepth?.depth;
+  return typeof depth === 'string' && Object.hasOwn(DEPTH_MIN_ACTION, depth)
+    ? DEPTH_MIN_ACTION[depth]
+    : 'finish';
+}
+
+// Resolve the route record's crossCheck sub-record (BL-016): a pinned `depth`
+// field counts as an already-resolved value; otherwise the full sub-record
+// (risk/implementerReliability/evidenceQuality/rigor/…) feeds the matrix.
+// Returns null when no usable depth exists — never throws.
+function resolveCrossCheckInput(crossCheck) {
+  if (crossCheck == null) return null;
+  if (typeof crossCheck === 'string') {
+    return Object.hasOwn(DEPTH_MIN_ACTION, crossCheck) ? crossCheck : null;
+  }
+  if (!isPlainObject(crossCheck)) return null;
+  if (typeof crossCheck.depth === 'string' && Object.hasOwn(DEPTH_MIN_ACTION, crossCheck.depth)) {
+    return crossCheck.depth;
+  }
+  try {
+    return resolveCrossCheckDepth(crossCheck);
+  } catch {
+    return null; // a malformed sub-record never blocks the evaluation
+  }
+}
+
+// ─── evaluator ──────────────────────────────────────────────────────────────
+
+export function evaluateReviewPolicy({
+  signals = {},
+  doneCriteria = [],
+  evidenceClasses = [],
+  fixLoopCount = 0,
+  round = 0,
+  cap = DEFAULT_REVIEW_ROUND_CAP,
+  escalationDepth = null,
+  // TASK-C85-016 (BL-016): the route record's crossCheck sub-record resolves
+  // its depth through the matrix when the caller didn't pass an explicit
+  // escalationDepth. A pinned `depth` field on the sub-record wins as an
+  // already-resolved value; explicit escalationDepth wins over both.
+  crossCheck = null,
+  fixLoopThreshold = DEFAULT_FIX_LOOP_THRESHOLD,
+  projectRoot = null,
+  appendDecisionReceipt = null,
+} = {}) {
+  const criteria = (Array.isArray(doneCriteria) ? doneCriteria : [])
+    .map(normalizeDoneCriterion)
+    .filter(Boolean);
+  const verified = criteria.filter((c) => c.status === 'verified').map((c) => c.name);
+  const notVerified = criteria.filter((c) => c.status !== 'verified').map((c) => c.name);
+  const claimed = criteria.filter((c) => c.status === 'claimed').map((c) => c.name);
+  const requiredEvidence = (Array.isArray(evidenceClasses) ? evidenceClasses : [])
+    .filter((e) => typeof e === 'string' && e.trim());
+  const cappedRound = clampInt(round, 0);
+  const cappedCap = clampInt(cap, DEFAULT_REVIEW_ROUND_CAP, 1);
+
+  // ── signal detection ────────────────────────────────────────────────────
+  // Caller-asserted signals + the two the inputs derive on their own: a
+  // 'claimed' criterion IS signal #4 (verification claimed, no output) and
+  // fixLoopCount ≥ threshold IS signal #7 (same-fingerprint fix loop).
+  const hitIds = assertedSignalIds(signals);
+  if (claimed.length > 0) hitIds.add('claimed-verification');
+  if (clampInt(fixLoopCount, 0) >= Math.max(1, clampInt(fixLoopThreshold, DEFAULT_FIX_LOOP_THRESHOLD))) {
+    hitIds.add('fix-loop-same-fingerprint');
+  }
+
+  const hits = SUSPICION_SIGNAL_CATALOGUE.filter((s) => hitIds.has(s.id));
+
+  // ── base action ─────────────────────────────────────────────────────────
+  let action = 'finish';
+  let namedCheck = null;
+  let rationale;
+
+  if (hits.length > 0) {
+    const winning = hits.reduce((best, signal) => (
+      ACTION_SEVERITY[SIGNAL_ACTION[signal.fires]] > ACTION_SEVERITY[SIGNAL_ACTION[best.fires]]
+        ? signal
+        : best
+    ));
+    action = SIGNAL_ACTION[winning.fires];
+    namedCheck = winning.check;
+    rationale = `suspicion signal${hits.length > 1 ? 's' : ''} fired: ${hits.map((s) => s.id).join(', ')} — strongest is ${winning.id} (${action})`;
+  } else if (notVerified.length > 0) {
+    // Unevidenced work with no named suspicion still cannot finish: demand one
+    // cheap targeted check per the cheapest defect to catch.
+    action = 'run-targeted-check';
+    namedCheck = `obtain the named evidence for: ${notVerified.join(', ')} — receipt or verbatim output, not a claim`;
+    rationale = `unverified done-criteria with no fired signal: ${notVerified.join(', ')}`;
+  } else if (criteria.length === 0 && requiredEvidence.length > 0) {
+    // No criteria but required evidence classes → confirm the classes landed.
+    action = 'run-targeted-check';
+    namedCheck = `confirm receipt classes present: ${requiredEvidence.join(', ')}`;
+    rationale = 'no done-criteria; required evidence classes unaccounted';
+  } else if (criteria.length === 0) {
+    // Nothing checkable exists at all — the honest report, not a free pass.
+    action = 'inconclusive';
+    rationale = 'no done-criteria and no evidence classes to verify — nothing checkable was provided';
+  } else {
+    // Every criterion verified — a verified criterion IS the evidence;
+    // declared evidence classes add no extra round on their own.
+    rationale = 'all done-criteria verified, no suspicion signals — review round suppressed';
+  }
+
+  // ── cross-check depth floor (escalationDepth) ───────────────────────────
+  // TASK-C85-016 wires the depth matrix here: a depth may raise the action
+  // floor (e.g. 'review-round' forces ≥ independent-review) but never lowers
+  // it — a fired suspicion signal always outranks a shallow depth.
+  const effectiveDepth = escalationDepth ?? resolveCrossCheckInput(crossCheck);
+  const depthFloor = escalationDepthAction(effectiveDepth);
+  if (ACTION_SEVERITY[depthFloor] > ACTION_SEVERITY[action]) {
+    const depth = typeof effectiveDepth === 'object' ? (effectiveDepth?.depth ?? effectiveDepth) : effectiveDepth;
+    action = depthFloor;
+    namedCheck = namedCheck
+      ?? (action === 'independent-review'
+        ? 'cross-check depth matrix requires one independent review round — reviewer verifies the request is satisfied, wired into flow, and free of convention breaks'
+        : (action === 'escalate'
+          ? SUSPICION_SIGNAL_CATALOGUE.find((s) => s.id === 'fix-loop-same-fingerprint').check
+          : 'run the artifact-class runnable checks required by the depth matrix'));
+    rationale += `; escalationDepth=${depth} raised the action floor to ${action}`;
+  }
+
+  // ── round cap → inconclusive (never infinite blocking) ──────────────────
+  // 'escalate' bypasses the cap deliberately: it is a terminal hand-off to a
+  // deeper lane, not another loop iteration.
+  if (action !== 'finish' && action !== 'escalate' && cappedRound >= cappedCap) {
+    const previous = action;
+    action = 'inconclusive';
+    namedCheck = null;
+    rationale = `review round cap reached (round=${cappedRound} ≥ cap=${cappedCap}) — ${previous} could not be confirmed; reporting verified-vs-not honestly instead of looping`;
+  }
+
+  const missingEvidence = [...new Set([...notVerified, ...requiredEvidence])];
+
+  const decision = {
+    action,
+    namedCheck,
+    signalsHit: hits.map((s) => s.id),
+    rationale,
+    reviewRounds: cappedRound + (action === 'finish' || action === 'inconclusive' ? 0 : 1),
+    verified,
+    notVerified,
+    missingEvidence,
+  };
+
+  // ── calibration receipt (consumed signature — never edited) ─────────────
+  // decisionKeys carry the receipt fields the ledger schema doesn't model:
+  // signalsHit, round, and outcome (unknown at decision time → pending).
+  if (typeof appendDecisionReceipt === 'function' && projectRoot) {
+    try {
+      const appended = appendDecisionReceipt(projectRoot, {
+        kind: 'review-policy',
+        boundary: 'review',
+        stage: 'deterministic',
+        outcomeClass: decision.action,
+        checkpoint: decision.namedCheck,
+        decisionKeys: [
+          `signalsHit=${decision.signalsHit.join(',') || 'none'}`,
+          `round=${cappedRound}`,
+          'outcome=pending',
+        ],
+        agreement: 'n/a',
+      });
+      if (appended?.catch) appended.catch(() => {});
+    } catch { /* calibration telemetry never fails the evaluation */ }
+  }
+
+  return decision;
+}