@ngockhoale/ukit 3.1.0 → 3.1.2

package/src/decision/reviewVerdict.js

@@ -0,0 +1,309 @@
+/**
+ * reviewVerdict.js (S2 / UNIC_DECISION_MIGRATION)
+ *
+ * Review-verdict producer for the `review` decision family. Reviewers (the
+ * general-LLM code-reviewer agents) still generate findings; when
+ * `decisionPlane.families.review.stage` is promoted past 'off', the FINAL
+ * verdict and per-finding bucket pass runs through unic-decision instead.
+ * Deterministic severity aggregation stays authoritative on 'off' and on
+ * every failure path — never another LLM for the verdict.
+ *
+ * Registered keys (src/decision/registry.js):
+ *   review.verdict.v1        — solo reviewer verdict (choice)
+ *   review.finding-bucket.v1 — per-finding triage bucket (choice; asked once
+ *                              per finding, wire name carries `#<id>`)
+ *   review.panel-verdict.v1  — aggregated panel verdict (choice)
+ *
+ * Transport discipline (C13/statePacket conventions): only whitelisted,
+ * truncated finding fields cross the wire — {id, severity, location, claim}.
+ * No diff hunks, no prose, no secrets. Everything below is pure — no I/O —
+ * and never throws (client.js precedent).
+ */
+
+export const VERDICT_CANDIDATES = Object.freeze([
+  'APPROVED',
+  'APPROVED-WITH-MINOR',
+  'CHANGES-REQUESTED',
+  'CRITICAL',
+]);
+
+export const BUCKET_CANDIDATES = Object.freeze([
+  'Act on',
+  'Consider',
+  'Noted',
+  'Dismissed',
+]);
+
+export const REVIEW_VERDICT_KEYS = Object.freeze({
+  solo: 'review.verdict.v1',
+  bucket: 'review.finding-bucket.v1',
+  panel: 'review.panel-verdict.v1',
+});
+
+// Bounds keep the batch inside the state budget and the tool list small.
+// MAX_FINDINGS mirrors statePacket.js MAX_ARRAY_ITEMS (24); a question plus a
+// verdict slot means at most MAX_FINDINGS bucket questions per batch.
+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';
+}
+
+// Whitelist one finding down to the exact fields the verdict pass is allowed
+// to see. Location collapses file:line into a single label; every other
+// field on the input object is dropped silently.
+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),
+  };
+}
+
+// Stable short fingerprint for the batch id — same findings → same batchId
+// across runs, so receipts and logs reconcile.
+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')}`;
+}
+
+/**
+ * Build the C13 question batch for the review verdict pass.
+ *
+ * @param {object} [input]
+ * @param {Array}  [input.findings]  extracted review findings (whitelisted
+ *        fields only: id/severity/file/line/claim|title|summary|message).
+ * @param {string} [input.mode]      'solo' → review.verdict.v1 question;
+ *        'panel' → review.panel-verdict.v1 instead.
+ * @returns {{questions: object[], statePacket: object, batch: object,
+ *            findings: object[], verdictDecisionKey: string}}
+ *          Never throws — garbage input sanitizes to an empty finding list.
+ */
+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'],
+  };
+
+  // One bucket question per finding. The shared registered key cannot repeat
+  // in one batch (name-based reconciliation), so each wire name carries
+  // `#<findingId>`; parseVerdictAnswer splits it back off.
+  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];
+
+  // Producer-owned packet — only sanitized whitelisted fields. `findingCount`
+  // is the only aggregate the model needs; severities ride the findings array.
+  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 verdict from finding severities — the authoritative path at
+ * stage 'off' and the fallback on every failure (unic-decision unavailable,
+ * malformed/invalid answers). Rule (documented in review-verdict.mjs):
+ *   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';
+}
+
+/**
+ * Deterministic per-finding bucket — the fallback the lead reviewer's
+ * bucketing judgment replaces only when the family stage is enabled.
+ *   critical | important | unclassified → 'Act on'
+ *   minor                              → 'Noted'
+ * Conservative: an unknown severity feeds the auto-fix loop rather than
+ * being silently dismissed.
+ */
+export function deriveDeterministicBucket(finding) {
+  const severity = normalizeSeverity(isPlainObject(finding) ? finding.severity : null);
+  return severity === 'minor' ? 'Noted' : 'Act on';
+}
+
+// Wire name → {decisionKey, findingId}: 'review.finding-bucket.v1#F3' splits
+// into the registered key plus the finding the bucket answer belongs to.
+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 };
+}
+
+/**
+ * Fold a DecisionBatchResult (from client.requestBatch or an offline
+ * parseBatchResponse) into the review-verdict shape. Never throws; every
+ * invalid/missing answer degrades to `null`/deterministic-bucket so callers
+ * can substitute deriveDeterministicVerdict as the authoritative fallback.
+ *
+ * @param {object} [result] DecisionBatchResult — {status, answers}.
+ * @param {object} [opts]
+ * @param {Array}  [opts.findings] sanitized or raw findings — supplies the
+ *        bucket fold order and per-finding fallback values.
+ * @returns {{status: string, verdict: string|null, verdictStatus: string,
+ *            buckets: Array<{findingId, bucket, bucketStatus}>}}
+ */
+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';
+  // findingId → {bucket, bucketStatus}; 'default' marks the deterministic
+  // fallback standing in because the batch never produced an answer for it.
+  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 };
+}

package/template_project/.claude/agents/code-reviewer.md

@@ -49,6 +49,26 @@ If any input is missing, return `CHANGES-REQUESTED` with reason "incomplete hand
 - **APPROVED-WITH-MINOR** — Minor naming / doc / style issues. Logged on task file but handoff allowed.
 - **APPROVED** — Clean.
 
+### Stage gate — verdict emission (unic-decision)
+
+You generate the findings; the FINAL verdict/bucket classification is a bounded
+decision owned by the local decision model when staged. Read
+`decisionPlane.families.review.stage` from `.ukit/storage/config.json`:
+
+- `off` (default) or any adapter failure (`outcomeClass` ≠ `accepted`/`partial`) →
+  you emit the verdict directly, exactly as today; the deterministic severity
+  aggregate (any critical → CHANGES-REQUESTED; ≥1 important or any
+  unclassified/unknown severity → APPROVED-WITH-MINOR; else APPROVED) stays
+  authoritative.
+- not `off` → emit the verdict via `node .claude/ukit/index/review-verdict.mjs`
+  (registered key `review.verdict.v1`): pipe your extracted findings as JSON on
+  stdin — whitelisted fields only (`id`, `severity`, `file`, `line`, short
+  `claim`; never diff hunks or secrets). Use the adapter's `verdict`/`buckets`
+  fields in the `## Reviewer Verdict` block.
+
+Model isolation is preserved: the verdict pass runs on the local unic-decision
+model, so reviewer ≠ executor still stands.
+
 ### Output (append to task file as `## Reviewer Verdict`)
 
 ```
@@ -138,7 +158,11 @@ verdict block — with these additions:
   `node .claude/ukit/index/review-panel-aggregate.mjs <TASK-xxx.md...>` and hands you
   the output, the lead fills `AGREEMENT_MAP` with the emitted finding → members map
   and applies the lead-judgment buckets to every finding: **Act on** / **Consider** /
-  **Noted** / **Dismissed**.
+  **Noted** / **Dismissed**. When `decisionPlane.families.review.stage` is not `off`,
+  the lead's bucketing and panel verdict go through
+  `node .claude/ukit/index/review-verdict.mjs --panel` (`review.finding-bucket.v1` /
+  `review.panel-verdict.v1`) per the stage gate above — the deterministic aggregate
+  stays authoritative at `off` or on adapter failure.
 - `consensus≥2 identical findings = high signal`: a finding reported by two or more
   panel members is high-signal and must not be bucketed below **Consider** without a
   stated reason.

package/template_project/.claude/agents/ukit-small-task-maintainer.md

@@ -27,6 +27,22 @@ You are UKit's internal small-task maintainer. You run as a sidecar/parallel/non
 - Keeping agent context compact without removing existing lanes: Claude PreCompact/reinject stays active and Codex Desktop soft handoffs use `compact.codexContext.compactTarget` (default 150 lines; preferred 120-150; hard max 170) while preserving critical state.
 - Small, reversible UKit runtime maintenance decisions.
 
+## Bounded Decisions (stage-gated unic-decision)
+
+The six bounded decisions enumerated in `.codex/settings.json` `smallTaskModel.decisionPolicy.decisions` — `fast-vs-slow-lane`, `safe-vs-risky-lane`, `skill-routing-needed`, `step-budget-enough`, `compact-now-or-later`, `summarize-docs-or-keep-detail` — consult `unic-decision` first via the installed CLI when the decision-plane stage allows:
+
+```
+node .claude/ukit/index/sidecar-decision.mjs --decision <name> [--root <dir>]   # context JSON on stdin
+```
+
+The CLI resolves `decisionPlane.families.workflow.stage` and owns the name → `workflow.*` decision-key mapping (`--list` prints it):
+
+- `off` (default): the CLI's deterministic rules answer directly — zero transport, authoritative.
+- `shadow`: run the batch for comparison only; the deterministic rule answer stays authoritative.
+- `canary`/`default`: a valid unic-decision answer wins; an invalid or unavailable adapter falls back to the deterministic rule (`outcomeClass: 'unavailable'`).
+
+`unic-decision` is the only model allowed in these decision steps — on any failure the deterministic rule is the fallback, never another LLM for the verdict. This lane's own model (`unic-lite`) keeps generative work only: summarization, doc maintenance, and cleanup — it never emits a verdict for these decisions.
+
 ## Never Use For
 
 - Security/auth/permission/secrets work.

package/template_project/.claude/commands/ukit/handoff-fullstack.md

@@ -576,6 +576,8 @@ git status              # overview of modified/new/deleted files
 
 Review as one unified diff — correctness, regression risk, security, edge cases, maintainability. Cross-reference each task's intent in `docs/AI_HANDOFF/tasks/TASK-xxx.md`.
 
+Stage gate (unic-decision): reviewers still generate findings; when `decisionPlane.families.review.stage` is not `off`, the emitted verdict goes through `node .claude/ukit/index/review-verdict.mjs` (`review.verdict.v1`; `--panel` for `review.panel-verdict.v1`/`review.finding-bucket.v1`) — the deterministic severity aggregate stays authoritative at `off` or on adapter failure.
+
 Append verdict to each task file:
 ```
 ## Reviewer Verdict

package/template_project/.claude/commands/ukit/handoff-review.md

@@ -141,6 +141,18 @@ carrying the Agreement Map and the bucketed findings. `Act on` findings feed Ste
 auto-fix loop; `Consider`/`Noted`/`Dismissed` are advisory. A high-signal finding must
 not be bucketed below `Consider` without a stated reason.
 
+Stage gate (unic-decision): findings stay generated by the general-LLM panel — only
+the FINAL verdict/bucket pass consults the local decision model. When
+`decisionPlane.families.review.stage` (`.ukit/storage/config.json`) is not `off`, the
+lead member's finding bucketing and the panel verdict go through
+`node .claude/ukit/index/review-verdict.mjs --panel` (registered keys
+`review.panel-verdict.v1` + `review.finding-bucket.v1`) instead of free judgment;
+pipe the extracted findings (id/severity/file:line/short claim — never diff hunks)
+as JSON on stdin. At stage `off` or on any `outcomeClass` ≠ `accepted`/`partial`
+(gateway unavailable, invalid answers) the deterministic severity aggregate above
+stays authoritative. Model isolation is preserved: the verdict pass is the local
+decision model, so reviewer ≠ executor still stands.
+
 ### 2f — Orchestrator updates INDEX.md
 
 Set `status = NEXT_STATUS_FOR_INDEX`. Orchestrator writes INDEX, not the reviewer.