@ngockhoale/ukit 3.0.12 → 3.1.1

package/template_project/.claude/ukit/index/review-verdict.mjs

@@ -0,0 +1,592 @@
+#!/usr/bin/env node
+/**
+ * review-verdict.mjs (S2 / UNIC_DECISION_MIGRATION)
+ *
+ * Review-verdict adapter — the bounded classification pass for the `review`
+ * decision family (unic-decision batch: review.verdict.v1 solo /
+ * review.panel-verdict.v1 panel + review.finding-bucket.v1 per finding).
+ * Reviewers still GENERATE the findings; when the family stage is enabled the
+ * FINAL verdict/bucket emission goes through this adapter. Model isolation is
+ * preserved — the verdict model is the local decision model, never the
+ * executor and never another general LLM.
+ *
+ * Usage:
+ *   cat findings.json | node .claude/ukit/index/review-verdict.mjs [--panel]
+ *   node .claude/ukit/index/review-verdict.mjs --file findings.json [--panel]
+ *   node .claude/ukit/index/review-verdict.mjs --fixture fixture.json
+ *
+ * Input findings JSON: an array, or {findings: [...]}. Each finding is
+ * whitelisted to {id, severity, file, line, claim} — diff hunks, prose and
+ * any other field never cross the transport.
+ *
+ * Stage contract (decisionPlane.families.review.stage, resolved like
+ * route-task.mjs resolveDecisionFamilyStage):
+ *   'off'      → deterministic fallback, ZERO model calls. Rule:
+ *                any critical → CHANGES-REQUESTED; ≥1 important or
+ *                unclassified → APPROVED-WITH-MINOR; else APPROVED.
+ *   otherwise  → one unic-decision batch over the whitelisted findings; the
+ *                answer is folded into verdict + buckets. Any failure
+ *                (gateway unavailable, malformed/invalid answers) emits the
+ *                deterministic fallback verdict with outcomeClass reflecting
+ *                the typed failure — the fallback stays authoritative.
+ *
+ * Never throws: malformed input still prints a fallback verdict
+ * (outcomeClass 'invalid-input', conservative CHANGES-REQUESTED) so an
+ * unattended pipeline always gets a parseable verdict. Advisory by design —
+ * exits 0 on every input path; a missing/unreadable --fixture/--file is the
+ * only exit-1 usage error.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import { requestBatch, parseBatchResponse } from './unic-decision.mjs';
+
+// ---------------------------------------------------------------------------
+// Review-verdict logic — literal port of src/decision/reviewVerdict.js.
+// Parity is locked by tests/index/reviewVerdictCli.test.js; edit both or
+// neither.
+// ---------------------------------------------------------------------------
+
+const VERDICT_CANDIDATES = Object.freeze([
+  'APPROVED',
+  'APPROVED-WITH-MINOR',
+  'CHANGES-REQUESTED',
+  'CRITICAL',
+]);
+
+const BUCKET_CANDIDATES = Object.freeze([
+  'Act on',
+  'Consider',
+  'Noted',
+  'Dismissed',
+]);
+
+const REVIEW_VERDICT_KEYS = Object.freeze({
+  solo: 'review.verdict.v1',
+  bucket: 'review.finding-bucket.v1',
+  panel: 'review.panel-verdict.v1',
+});
+
+export const MAX_FINDINGS = 24;
+export const MAX_CLAIM_LENGTH = 160;
+const MAX_LOCATION_LENGTH = 160;
+const MAX_ID_LENGTH = 64;
+const MAX_SEVERITY_LENGTH = 24;
+
+const KNOWN_SEVERITIES = new Set(['critical', 'important', 'minor']);
+
+const BUCKET_INSTRUCTION =
+  'Triage this single review finding into exactly one bucket: '
+  + '"Act on" feeds the auto-fix loop; "Consider" is advisory but worth the '
+  + 'author\'s attention; "Noted" is informational only; "Dismissed" is '
+  + 'rejected as not actionable.';
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function collapseWhitespace(text) {
+  return String(text).replace(/\s+/g, ' ').trim();
+}
+
+function truncate(text, max) {
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+function normalizeSeverity(raw) {
+  const severity = typeof raw === 'string'
+    ? raw.trim().toLowerCase().slice(0, MAX_SEVERITY_LENGTH)
+    : '';
+  return KNOWN_SEVERITIES.has(severity) ? severity : 'unknown';
+}
+
+function sanitizeFinding(raw, index, usedIds) {
+  const source = isPlainObject(raw) ? raw : {};
+  let id = typeof source.id === 'string' && source.id.trim().length > 0
+    ? source.id.trim().replace(/[^A-Za-z0-9._-]/g, '_').slice(0, MAX_ID_LENGTH)
+    : `F${index + 1}`;
+  if (id.length === 0 || usedIds.has(id)) {
+    // Collision fallback must itself be unique — two findings both claiming
+    // 'F2' must not collapse into one wire name / one bucket row.
+    let suffix = '';
+    while (usedIds.has(`F${index + 1}${suffix}`)) suffix = `${suffix}x`;
+    id = `F${index + 1}${suffix}`;
+  }
+  usedIds.add(id);
+
+  let file = typeof source.file === 'string' ? collapseWhitespace(source.file) : '';
+  const line = Number.isInteger(source.line) && source.line > 0 ? source.line : null;
+  if (file.length > 0) file = truncate(file, MAX_LOCATION_LENGTH - 8);
+  const location = file.length > 0
+    ? (line !== null ? `${file}:${line}` : file)
+    : (line !== null ? `line ${line}` : '-');
+
+  const claimSource = [source.claim, source.title, source.summary, source.message]
+    .find((v) => typeof v === 'string' && v.trim().length > 0);
+
+  return {
+    id,
+    severity: normalizeSeverity(source.severity),
+    location,
+    claim: truncate(collapseWhitespace(claimSource ?? ''), MAX_CLAIM_LENGTH),
+  };
+}
+
+function stableBatchId(findings) {
+  let h = 0x811c9dc5;
+  const text = JSON.stringify(findings.map((f) => [f.id, f.severity, f.location, f.claim]));
+  for (let i = 0; i < text.length; i += 1) {
+    h ^= text.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return `rv-${(h >>> 0).toString(16).padStart(8, '0')}`;
+}
+
+export function buildReviewVerdictBatch({ findings = [], mode = 'solo' } = {}) {
+  const usedIds = new Set();
+  const sanitized = (Array.isArray(findings) ? findings : [])
+    .slice(0, MAX_FINDINGS)
+    .map((raw, index) => sanitizeFinding(raw, index, usedIds));
+
+  const verdictDecisionKey = mode === 'panel'
+    ? REVIEW_VERDICT_KEYS.panel
+    : REVIEW_VERDICT_KEYS.solo;
+
+  const counts = { critical: 0, important: 0, minor: 0, unknown: 0 };
+  for (const f of sanitized) counts[f.severity] += 1;
+
+  const verdictQuestion = {
+    decisionKey: verdictDecisionKey,
+    schemaVersion: 1,
+    family: 'review',
+    owner: 'handoffReview',
+    kind: 'choice',
+    instruction:
+      'Pick the bounded review verdict for this finding set. '
+      + 'APPROVED = clean; APPROVED-WITH-MINOR = ship with nits logged; '
+      + 'CHANGES-REQUESTED = must fix before merge; CRITICAL = unsafe to ship.',
+    candidates: [...VERDICT_CANDIDATES],
+    hardConstraintRefs: ['verdict-vocabulary'],
+  };
+
+  const bucketQuestions = sanitized.map((f) => ({
+    decisionKey: `${REVIEW_VERDICT_KEYS.bucket}#${f.id}`,
+    schemaVersion: 1,
+    family: 'review',
+    owner: 'handoffReview',
+    kind: 'choice',
+    instruction: `${BUCKET_INSTRUCTION} Finding ${f.id} [${f.severity}] ${f.location}: ${f.claim || '(no claim text)'}`,
+    candidates: [...BUCKET_CANDIDATES],
+    hardConstraintRefs: ['bucket-vocabulary'],
+  }));
+
+  const questions = [verdictQuestion, ...bucketQuestions];
+
+  const statePacket = {
+    kind: 'review-verdict',
+    mode: mode === 'panel' ? 'panel' : 'solo',
+    findingCount: sanitized.length,
+    severityCounts: counts,
+    findings: sanitized,
+  };
+
+  const batch = {
+    batchVersion: 1,
+    batchId: stableBatchId(sanitized),
+    boundary: 'review-verdict',
+    questions,
+    statePacket,
+  };
+
+  return { questions, statePacket, batch, findings: sanitized, verdictDecisionKey };
+}
+
+// Deterministic fallback — the documented off-stage rule and the
+// authoritative verdict on every failure path:
+//   any critical  → CHANGES-REQUESTED
+//   ≥1 important or ≥1 unclassified → APPROVED-WITH-MINOR
+//   else          → APPROVED
+export function deriveDeterministicVerdict(findings) {
+  const list = Array.isArray(findings) ? findings : [];
+  let importantish = false;
+  for (const raw of list) {
+    const severity = isPlainObject(raw) ? normalizeSeverity(raw.severity) : 'unknown';
+    if (severity === 'critical') return 'CHANGES-REQUESTED';
+    if (severity === 'important' || severity === 'unknown') importantish = true;
+  }
+  return importantish ? 'APPROVED-WITH-MINOR' : 'APPROVED';
+}
+
+export function deriveDeterministicBucket(finding) {
+  const severity = normalizeSeverity(isPlainObject(finding) ? finding.severity : null);
+  return severity === 'minor' ? 'Noted' : 'Act on';
+}
+
+function splitWireName(name) {
+  const text = String(name ?? '');
+  const hash = text.lastIndexOf('#');
+  if (hash > 0 && text.slice(0, hash) === REVIEW_VERDICT_KEYS.bucket) {
+    return { decisionKey: REVIEW_VERDICT_KEYS.bucket, findingId: text.slice(hash + 1) };
+  }
+  return { decisionKey: text, findingId: null };
+}
+
+export function parseVerdictAnswer(result, { findings = [] } = {}) {
+  const status = typeof result?.status === 'string' ? result.status : 'invalid';
+  const answers = Array.isArray(result?.answers) ? result.answers : [];
+  const list = Array.isArray(findings) ? findings : [];
+
+  let verdict = null;
+  let verdictStatus = 'missing';
+  const bucketByFinding = new Map();
+  for (const raw of list) {
+    if (!isPlainObject(raw)) continue;
+    const id = typeof raw.id === 'string' && raw.id.length > 0 ? raw.id : null;
+    if (id === null) continue;
+    bucketByFinding.set(id, {
+      bucket: deriveDeterministicBucket(raw),
+      bucketStatus: 'default',
+    });
+  }
+
+  for (const answer of answers) {
+    if (!isPlainObject(answer)) continue;
+    const { decisionKey, findingId } = splitWireName(answer.decisionKey);
+    const valid = answer.validationStatus === 'valid'
+      && typeof answer.value === 'string';
+    if (decisionKey === REVIEW_VERDICT_KEYS.solo
+        || decisionKey === REVIEW_VERDICT_KEYS.panel) {
+      if (valid && VERDICT_CANDIDATES.includes(answer.value)) {
+        verdict = answer.value;
+        verdictStatus = 'valid';
+      } else {
+        verdictStatus = 'invalid';
+      }
+      continue;
+    }
+    if (decisionKey === REVIEW_VERDICT_KEYS.bucket && findingId !== null) {
+      bucketByFinding.set(
+        findingId,
+        valid && BUCKET_CANDIDATES.includes(answer.value)
+          ? { bucket: answer.value, bucketStatus: 'valid' }
+          : { bucket: deriveDeterministicBucket({ severity: 'unknown' }), bucketStatus: 'invalid' },
+      );
+    }
+  }
+
+  const buckets = [...bucketByFinding.entries()].map(([findingId, entry]) => ({
+    findingId,
+    bucket: entry.bucket,
+    bucketStatus: entry.bucketStatus,
+  }));
+
+  return { status, verdict, verdictStatus, buckets };
+}
+
+// ---------------------------------------------------------------------------
+// Stage resolution — same contract as route-task.mjs
+// resolveDecisionFamilyStage(config, 'review'): enabled===false or absent/
+// malformed values read as 'off'; the family override wins over the global
+// decisionPlane.stage when present.
+// ---------------------------------------------------------------------------
+
+const ROUTE_SCHEMA_STAGES = new Set(['off', 'shadow', 'canary', 'default']);
+
+export function resolveReviewStage(config = null) {
+  const plane = config?.decisionPlane;
+  if (!plane || typeof plane !== 'object' || plane.enabled === false) return 'off';
+  const override = plane?.families?.review?.stage;
+  if (ROUTE_SCHEMA_STAGES.has(override)) return override;
+  return ROUTE_SCHEMA_STAGES.has(plane.stage) ? plane.stage : 'off';
+}
+
+// ---------------------------------------------------------------------------
+// Runtime config — same merged view (project over user) as unic-decision.mjs.
+// ---------------------------------------------------------------------------
+
+function safeReadJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function mergeConfigObjects(base, override) {
+  if (!isPlainObject(base)) return isPlainObject(override) ? { ...override } : {};
+  if (!isPlainObject(override)) return { ...base };
+  const out = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    if (key === '__proto__' || key === 'constructor' || key === 'prototype') continue;
+    out[key] = isPlainObject(value) && isPlainObject(base[key])
+      ? mergeConfigObjects(base[key], value)
+      : value;
+  }
+  return out;
+}
+
+function readMergedConfig(rootDir, homeDir) {
+  const projectRaw = rootDir
+    ? safeReadJson(path.join(rootDir, '.ukit', 'storage', 'config.json'))
+    : null;
+  const userRaw = safeReadJson(
+    path.join(homeDir ?? os.homedir(), '.ukit', 'storage', 'config.json'),
+  );
+  return mergeConfigObjects(userRaw ?? {}, projectRaw ?? {});
+}
+
+// ---------------------------------------------------------------------------
+// Verdict run — shared by the CLI paths and tests.
+// ---------------------------------------------------------------------------
+
+// Deterministic output object. Field order is fixed so the printed JSON is
+// byte-identical for identical findings on the off/failure paths.
+function emitVerdict({ mode, stage, outcomeClass, verdict, verdictStatus,
+  verdictSource, buckets, batchId, fallbackCode }) {
+  return {
+    schema: 'review-verdict/v1',
+    mode,
+    stage,
+    outcomeClass,
+    verdict,
+    verdictStatus,
+    verdictSource,
+    buckets,
+    batchId,
+    fallbackCode: fallbackCode ?? null,
+  };
+}
+
+function deterministicResult({ mode, stage, outcomeClass, findings, batchId, fallbackCode }) {
+  return emitVerdict({
+    mode,
+    stage,
+    outcomeClass,
+    verdict: deriveDeterministicVerdict(findings),
+    verdictStatus: 'deterministic',
+    verdictSource: 'deterministic',
+    buckets: findings.map((f) => ({
+      findingId: f.id,
+      bucket: deriveDeterministicBucket(f),
+      bucketStatus: 'deterministic',
+    })),
+    batchId,
+    fallbackCode,
+  });
+}
+
+function foldBatchResult(result, built, mode, stage) {
+  const folded = parseVerdictAnswer(result, { findings: built.findings });
+  const modelVerdict = folded.verdict;
+  // Parse-level classes (accepted/partial/invalid/abstained) pass through;
+  // every transport/gateway class surfaces as 'unavailable' — the fallback
+  // code carries the finer-grained reason for receipts.
+  const PARSE_CLASSES = new Set(['accepted', 'partial', 'invalid', 'abstained']);
+  const outcomeClass = PARSE_CLASSES.has(folded.status) ? folded.status : 'unavailable';
+  return emitVerdict({
+    mode,
+    stage,
+    outcomeClass,
+    verdict: modelVerdict ?? deriveDeterministicVerdict(built.findings),
+    verdictStatus: modelVerdict === null
+      ? `fallback:${folded.verdictStatus}`
+      : folded.verdictStatus,
+    verdictSource: modelVerdict === null ? 'deterministic' : 'model',
+    buckets: folded.buckets,
+    batchId: built.batch.batchId,
+    fallbackCode: modelVerdict === null
+      ? (result?.fallbackCode ?? folded.status)
+      : null,
+  });
+}
+
+/**
+ * Run the verdict pass over a findings list. Returns the emitted object; the
+ * caller prints it. Never throws and never touches transport when stage is
+ * 'off'.
+ */
+export async function runReviewVerdict({ findings, mode = 'solo', config,
+  projectRoot, homeDir, env, transport } = {}) {
+  const built = buildReviewVerdictBatch({ findings, mode });
+  const normalizedMode = mode === 'panel' ? 'panel' : 'solo';
+  const stage = resolveReviewStage(config);
+
+  if (stage === 'off') {
+    return deterministicResult({
+      mode: normalizedMode,
+      stage,
+      outcomeClass: 'skipped',
+      findings: built.findings,
+      batchId: built.batch.batchId,
+      fallbackCode: 'stage-off',
+    });
+  }
+
+  const result = await requestBatch(built.batch, {
+    config,
+    transport,
+    projectRoot,
+    homeDir,
+    env,
+  });
+  return foldBatchResult(result, built, normalizedMode, stage);
+}
+
+/**
+ * Offline fixture replay: {findings, mode?, response} → emitted verdict
+ * object. Zero transport, zero dispatch — the fixture's tool_calls are parsed
+ * as data exactly once (same contract as unic-decision --fixture).
+ */
+export function runFixture(fixture) {
+  const mode = fixture?.mode === 'panel' ? 'panel' : 'solo';
+  const built = buildReviewVerdictBatch({ findings: fixture?.findings, mode });
+  if (!fixture || fixture.response === undefined) {
+    // No recorded response — emit the batch that would be sent, so fixtures
+    // can also be used to inspect question generation offline.
+    return { ...built.batch, emitted: 'batch-only' };
+  }
+  const parsed = parseBatchResponse(fixture.response, built.questions);
+  return foldBatchResult(parsed, built, mode, 'fixture');
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+function readFlagValue(argv, flag) {
+  const index = argv.indexOf(flag);
+  if (index === -1) return null;
+  const value = argv[index + 1];
+  return value && !value.startsWith('--') ? value : null;
+}
+
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}
+
+function printResult(result) {
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+// Findings input accepts a bare array or {findings:[...]}; anything else
+// (unparseable JSON, wrong shape) still yields a verdict — conservative
+// CHANGES-REQUESTED, flagged 'invalid-input' — never a crash, never APPROVED.
+function invalidInputResult(mode, detail) {
+  return emitVerdict({
+    mode,
+    stage: 'unknown',
+    outcomeClass: 'invalid-input',
+    verdict: 'CHANGES-REQUESTED',
+    verdictStatus: 'deterministic',
+    verdictSource: 'deterministic',
+    buckets: [],
+    batchId: null,
+    fallbackCode: detail ?? 'invalid-input',
+  });
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const rootDir = readFlagValue(args, '--root') ?? process.env.UKIT_TEST_ROOT ?? process.cwd();
+  const homeDir = process.env.UKIT_TEST_HOME ?? os.homedir();
+  const mode = args.includes('--panel') ? 'panel' : 'solo';
+  const config = readMergedConfig(rootDir, homeDir);
+
+  const fixturePath = readFlagValue(args, '--fixture');
+  if (fixturePath !== null) {
+    let fixture;
+    try {
+      fixture = JSON.parse(fs.readFileSync(fixturePath, 'utf8'));
+    } catch (error) {
+      process.stderr.write(
+        `review-verdict: cannot read fixture ${fixturePath}: ${error?.message ?? error}\n`,
+      );
+      return 1;
+    }
+    printResult(runFixture(fixture));
+    return 0;
+  }
+
+  const filePath = readFlagValue(args, '--file');
+  let raw = null;
+  if (filePath !== null) {
+    try {
+      raw = fs.readFileSync(filePath, 'utf8');
+    } catch (error) {
+      process.stderr.write(
+        `review-verdict: cannot read file ${filePath}: ${error?.message ?? error}\n`,
+      );
+      return 1;
+    }
+  } else {
+    raw = await readStdin();
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    process.stderr.write(
+      'review-verdict: expected findings JSON on stdin or --file '
+        + '(array, or {findings: [...]}); emitting fallback verdict\n',
+    );
+    printResult(invalidInputResult(mode, 'unparseable-input'));
+    return 0;
+  }
+  const findings = Array.isArray(parsed)
+    ? parsed
+    : (isPlainObject(parsed) ? parsed.findings : null);
+  if (!Array.isArray(findings)) {
+    process.stderr.write(
+      'review-verdict: input has no findings array; emitting fallback verdict\n',
+    );
+    printResult(invalidInputResult(mode, 'no-findings-array'));
+    return 0;
+  }
+
+  printResult(await runReviewVerdict({
+    findings,
+    mode,
+    config,
+    projectRoot: rootDir,
+    homeDir,
+    env: process.env,
+  }));
+  return 0;
+}
+
+const isMainModule = (() => {
+  try {
+    const invoked = process.argv[1] ?? '';
+    if (!invoked) return false;
+    const self = path.resolve(fileURLToPath(import.meta.url));
+    const target = path.resolve(invoked);
+    if (self === target) return true;
+    // Installed mirrors may be reached through a symlinked directory (e.g.
+    // .codex/ukit -> ../.claude/ukit): realpath resolves the link, basename
+    // equality keeps same-named unrelated scripts from matching.
+    return path.basename(invoked) === 'review-verdict.mjs'
+      && fs.realpathSync(target) === self;
+  } catch {
+    return false;
+  }
+})();
+
+if (isMainModule) {
+  main()
+    .then((code) => { process.exitCode = code; })
+    .catch((error) => {
+      process.stderr.write(`review-verdict: ${error?.message ?? error}\n`);
+      process.exitCode = 1;
+    });
+}