@ngockhoale/ukit 3.4.31 → 3.4.32

package/CHANGELOG.md

@@ -9,6 +9,16 @@ All notable changes to UKit are documented here.
 - New `/ukit:ci-check` command + `ci-check.mjs` helper (core pack): prechecks, fail-closed budget guard, local preflight, at most one dispatch per invocation, write-ahead run-id state, `status` (never dispatches), `--ref`, `--dry-run`, per-OS report. Never pushes, merges or publishes.
 - Default-branch bootstrap stub documented in `docs/design/CI-CROSS-PLATFORM-MATRIX.md` (requires separate approval).
 
+## 3.4.32 - 2026-10-11
+
+**UNIC-Decision integration P1: safety floors, ordinal score contract, request caps.** Verified with the full suite (566 files) and `yarn release:verify`; no live inference was run (offline fixtures plus an offline run of the Laya server translator).
+- **Sidecar is deterministic-only.** The six `workflow.*` sidecar decisions always return the deterministic answer at every stage; no adapter call is made. `modelAnswer`/`agreement` are no longer emitted; `--fixture`, `--list` and the result schema keys are unchanged.
+- **Escalation floors.** Fix-loop escalation never lowers verification depth (depth = max(deterministic floor, model), order `none<runnable<review-round<escalate`), never swaps the lane, and never applies model output at `shadow`. Fixed in both the template and the live `src/index/fixLoopEscalation.js`.
+- **Review safety floor.** The verdict floor always runs over all findings: critical → `CHANGES-REQUESTED`; important/unknown → at least `APPROVED-WITH-MINOR`; `Act on` buckets cannot be downgraded; `shadow` keeps the deterministic verdict.
+- **Score contract.** Ordinal `score` questions are sent as a string enum of ordered labels (rubric in the function description) and decoded as `indexOf(label)+1`; numeric answers are rejected. Wire format of `route.rigor.v1`/`preflight.rigor.v1` is now labels (`r0`..`r4`); parsed values stay integer 1..N.
+- **Request caps.** `decisionPlane.maxBatchQuestions` (default 8) and `maxEnumLabels` (default 11) are enforced before transport (`unsupported`, deterministic fallback); duplicate question keys are `invalid`. Route shadow and review use partial coverage in ONE batch: skipped decisions are reported (`coverage`, `skippedDecisions`, `outcomeClass: partial`) and keep deterministic results; no request splitting.
+- Limits: oversize requests outside route shadow/review fall back deterministically; escalation lane model answers are never applied; the server-side `unic-decision` model alias is unchanged. Details: `docs/UNIC-DECISION-INTEGRATION-P1-FIX.md`.
+
 ## 3.4.31 - 2026-10-11
 
 **Completion Gate: task-aware operational completion (fixes the CronDelete/CronList false positive).** Verified with the full suite (`yarn test`, 566 files) plus focused six-scenario routing → recorder → Stop regressions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.31",
+  "version": "3.4.32",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/src/decision/reviewVerdict.js

@@ -135,7 +135,7 @@ function stableBatchId(findings) {
  *            findings: object[], verdictDecisionKey: string}}
  *          Never throws — garbage input sanitizes to an empty finding list.
  */
-export function buildReviewVerdictBatch({ findings = [], mode = 'solo' } = {}) {
+export function buildReviewVerdictBatch({ findings = [], mode = 'solo', maxQuestions = Infinity } = {}) {
   const usedIds = new Set();
   // Sanitize the FULL finding set — MAX_FINDINGS is a display/transport bound
   // for the batch, not a verdict bound. The deterministic verdict and the
@@ -145,6 +145,19 @@ export function buildReviewVerdictBatch({ findings = [], mode = 'solo' } = {}) {
   const batchFindings = sanitized.slice(0, MAX_FINDINGS);
   const truncated = sanitized.length > batchFindings.length;
 
+  // Request-cap handling (no extra call): when verdict + one bucket question per
+  // finding would exceed `maxQuestions`, ask only findings whose bucket the model
+  // can actually change. `Act on` is a deterministic floor the model cannot
+  // lower, so critical/important/unknown findings carry no semantic value in the
+  // batch; the rest keep their deterministic bucket and are reported as skipped.
+  const slots = Number.isInteger(maxQuestions) && maxQuestions > 0
+    ? maxQuestions - 1 : Infinity;
+  const askedFindings = batchFindings.length <= slots
+    ? batchFindings
+    : batchFindings.filter((f) => deriveDeterministicBucket(f) !== 'Act on').slice(0, slots);
+  const askedIds = new Set(askedFindings.map((f) => f.id));
+  const skippedFindingIds = batchFindings.filter((f) => !askedIds.has(f.id)).map((f) => f.id);
+
   const verdictDecisionKey = mode === 'panel'
     ? REVIEW_VERDICT_KEYS.panel
     : REVIEW_VERDICT_KEYS.solo;
@@ -169,7 +182,7 @@ export function buildReviewVerdictBatch({ findings = [], mode = 'solo' } = {}) {
   // 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 = batchFindings.map((f) => ({
+  const bucketQuestions = askedFindings.map((f) => ({
     decisionKey: `${REVIEW_VERDICT_KEYS.bucket}#${f.id}`,
     schemaVersion: 1,
     family: 'review',
@@ -207,6 +220,7 @@ export function buildReviewVerdictBatch({ findings = [], mode = 'solo' } = {}) {
     findings: batchFindings,
     fullFindings: sanitized,
     truncated,
+    skippedFindingIds,
     verdictDecisionKey,
   };
 }

package/src/index/fixLoopEscalation.js

@@ -394,14 +394,20 @@ export async function applyFixLoopEscalation({
     : null;
   // A model lane that refuses to deepen is not an escalation answer — the
   // deterministic deeper lane wins so the loop actually exits its lane.
-  const usableModelLane = modelLane && modelLane !== currentLane ? modelLane : null;
-  const lane = usableModelLane ?? deterministicLane;
+  // Lanes are capabilities, not an ordinal ladder. Without a validated policy
+  // relation only the deterministic destination is admissible.
+  const usableModelLane = planeStage !== 'shadow' && modelLane === deterministicLane
+    ? modelLane : null;
+  const lane = deterministicLane;
   const endpointDown = batchResult !== null
     && batchResult.status !== 'accepted'
     && batchResult.status !== 'partial'
     && !usableModelLane;
-  const depth = (modelDepth && modelDepth !== 'none' ? modelDepth : null)
-    ?? resolveEscalationVerificationDepth({ routeSummary, config });
+  const depthFloor = resolveEscalationVerificationDepth({ routeSummary, config });
+  const depthOrder = ['none', 'runnable', 'review-round', 'escalate'];
+  const depth = planeStage !== 'shadow'
+    && depthOrder.indexOf(modelDepth) > depthOrder.indexOf(depthFloor)
+    ? modelDepth : depthFloor;
 
   const reason = [
     `fix-loop: fixLoopCount=${fixLoopCount} threshold=${settings.debugLoopThreshold} fingerprint-joined`,

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

@@ -146,7 +146,7 @@ function stableBatchId(findings) {
   return `rv-${(h >>> 0).toString(16).padStart(8, '0')}`;
 }
 
-export function buildReviewVerdictBatch({ findings = [], mode = 'solo' } = {}) {
+export function buildReviewVerdictBatch({ findings = [], mode = 'solo', maxQuestions = Infinity } = {}) {
   const usedIds = new Set();
   // Sanitize the FULL finding set — MAX_FINDINGS is a display/transport bound
   // for the batch, not a verdict bound. The deterministic verdict and the
@@ -156,6 +156,19 @@ export function buildReviewVerdictBatch({ findings = [], mode = 'solo' } = {}) {
   const batchFindings = sanitized.slice(0, MAX_FINDINGS);
   const truncated = sanitized.length > batchFindings.length;
 
+  // Request-cap handling (no extra call): when verdict + one bucket question per
+  // finding would exceed `maxQuestions`, ask only findings whose bucket the model
+  // can actually change. `Act on` is a deterministic floor the model cannot
+  // lower, so critical/important/unknown findings carry no semantic value in the
+  // batch; the rest keep their deterministic bucket and are reported as skipped.
+  const slots = Number.isInteger(maxQuestions) && maxQuestions > 0
+    ? maxQuestions - 1 : Infinity;
+  const askedFindings = batchFindings.length <= slots
+    ? batchFindings
+    : batchFindings.filter((f) => deriveDeterministicBucket(f) !== 'Act on').slice(0, slots);
+  const askedIds = new Set(askedFindings.map((f) => f.id));
+  const skippedFindingIds = batchFindings.filter((f) => !askedIds.has(f.id)).map((f) => f.id);
+
   const verdictDecisionKey = mode === 'panel'
     ? REVIEW_VERDICT_KEYS.panel
     : REVIEW_VERDICT_KEYS.solo;
@@ -177,7 +190,7 @@ export function buildReviewVerdictBatch({ findings = [], mode = 'solo' } = {}) {
     hardConstraintRefs: ['verdict-vocabulary'],
   };
 
-  const bucketQuestions = batchFindings.map((f) => ({
+  const bucketQuestions = askedFindings.map((f) => ({
     decisionKey: `${REVIEW_VERDICT_KEYS.bucket}#${f.id}`,
     schemaVersion: 1,
     family: 'review',
@@ -213,6 +226,7 @@ export function buildReviewVerdictBatch({ findings = [], mode = 'solo' } = {}) {
     findings: batchFindings,
     fullFindings: sanitized,
     truncated,
+    skippedFindingIds,
     verdictDecisionKey,
   };
 }
@@ -362,7 +376,7 @@ function readMergedConfig(rootDir, homeDir) {
 // 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 }) {
+  verdictSource, buckets, batchId, fallbackCode, coverage }) {
   return {
     schema: 'review-verdict/v1',
     mode,
@@ -374,6 +388,7 @@ function emitVerdict({ mode, stage, outcomeClass, verdict, verdictStatus,
     buckets,
     batchId,
     fallbackCode: fallbackCode ?? null,
+    ...(coverage ? { coverage } : {}),
   };
 }
 
@@ -413,11 +428,19 @@ function foldBatchResult(result, built, mode, stage) {
       fallbackCode: 'shadow-observation-only',
       verdictOverride: deriveDeterministicVerdict(built.fullFindings ?? built.findings) });
   }
+  const skipped = new Set(built.skippedFindingIds ?? []);
   folded.buckets = folded.buckets.map((bucket, index) => {
     const floor = deriveDeterministicBucket(built.findings[index]);
+    if (skipped.has(bucket.findingId)) {
+      return { findingId: bucket.findingId, bucket: floor, bucketStatus: 'deterministic:not-asked' };
+    }
     return floor === 'Act on' && bucket.bucket !== floor
       ? { ...bucket, bucket: floor, bucketStatus: 'clamp:safety-floor' } : bucket;
   });
+  const coverage = skipped.size > 0
+    ? { asked: built.findings.length - skipped.size, total: built.findings.length,
+        skippedFindingIds: [...skipped], reason: 'batch-cap', complete: false }
+    : null;
   const modelVerdict = folded.verdict;
   // W3-RV1: the batch may be display-truncated at MAX_FINDINGS — the model
   // verdict was computed on `built.findings` only, so when truncation
@@ -433,8 +456,10 @@ function foldBatchResult(result, built, mode, stage) {
   // 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';
+  let outcomeClass = PARSE_CLASSES.has(folded.status) ? folded.status : 'unavailable';
+  if (coverage && outcomeClass === 'accepted') outcomeClass = 'partial';
   return emitVerdict({
+    coverage,
     mode,
     stage,
     outcomeClass,
@@ -460,7 +485,11 @@ function foldBatchResult(result, built, mode, stage) {
  */
 export async function runReviewVerdict({ findings, mode = 'solo', config,
   projectRoot, homeDir, env, transport } = {}) {
-  const built = buildReviewVerdictBatch({ findings, mode });
+  const capValue = config?.decisionPlane?.maxBatchQuestions;
+  const built = buildReviewVerdictBatch({
+    findings, mode,
+    maxQuestions: Number.isInteger(capValue) && capValue > 0 ? capValue : 8,
+  });
   const normalizedMode = mode === 'panel' ? 'panel' : 'solo';
   const stage = resolveReviewStage(config);
 

package/template_project/.claude/ukit/index/route-task.mjs

@@ -1663,6 +1663,11 @@ function probabilityBand(value) {
 // executionMode. The review/cross-check/verification-depth baselines are
 // produced by later wave modules; until then their baseline stays null and
 // receipts record bands + agreement 'unknown' — real data, not fabricated.
+// Route-shadow questions that add no observation: asked authoritatively by the
+// fix-loop escalation batch (verification.depth.v1) and without a route-level
+// baseline to compare against here.
+const SHADOW_REDUNDANT_KEYS = new Set(['verification.depth.v1']);
+
 function shadowBaselineFor(decisionKey, routeSummary) {
   if (decisionKey === 'route.intent-kind.v1') return routeSummary?.intent?.kind ?? null;
   if (decisionKey === 'route.rigor.v1') return routeSummary?.execution?.rigor ?? null;
@@ -1819,7 +1824,42 @@ export async function runRouteDecisionShadow({
   // Greeting fast-path: a social turn carries nothing the decision plane could
   // answer — never spawn the adapter shadow for one.
   if (routingContext?.greetingFastPath) return null;
-  const questions = buildShadowDecisionQuestions(config);
+  // Observation-only batch: honour the adapter request caps without a second
+  // call. Selection is semantic, not positional: (1) enums over maxEnumLabels
+  // are never truncated, they are skipped (`enum-cap`); (2) questions the route
+  // cannot compare to a deterministic baseline AND that another stage already
+  // asks authoritatively are redundant here; (3) the remainder is ranked
+  // baseline-comparable first, table order within a rank, and cut at
+  // maxBatchQuestions (`batch-cap`). Every skip is reported with its reason.
+  const shadowCaps = {
+    batch: Number.isInteger(config?.decisionPlane?.maxBatchQuestions) && config.decisionPlane.maxBatchQuestions > 0
+      ? config.decisionPlane.maxBatchQuestions : 8,
+    labels: Number.isInteger(config?.decisionPlane?.maxEnumLabels) && config.decisionPlane.maxEnumLabels > 0
+      ? config.decisionPlane.maxEnumLabels : 11,
+  };
+  const wanted = buildShadowDecisionQuestions(config);
+  const skippedDecisions = [];
+  const candidatesForBatch = [];
+  for (const q of wanted) {
+    if ((q.candidates?.length ?? 0) > shadowCaps.labels) {
+      skippedDecisions.push({ decisionKey: q.decisionKey, reason: 'enum-cap' });
+    } else if (SHADOW_REDUNDANT_KEYS.has(q.decisionKey)) {
+      skippedDecisions.push({ decisionKey: q.decisionKey, reason: 'redundant' });
+    } else {
+      candidatesForBatch.push(q);
+    }
+  }
+  const hasBaseline = (q) => shadowBaselineFor(q.decisionKey, routeSummary) != null;
+  const ranked = [
+    ...candidatesForBatch.filter(hasBaseline),
+    ...candidatesForBatch.filter((q) => !hasBaseline(q)),
+  ];
+  const picked = new Set(ranked.slice(0, shadowCaps.batch));
+  for (const q of candidatesForBatch) {
+    if (!picked.has(q)) skippedDecisions.push({ decisionKey: q.decisionKey, reason: 'batch-cap' });
+  }
+  const questions = candidatesForBatch.filter((q) => picked.has(q));
+  const skippedDecisionKeys = skippedDecisions.map((d) => d.decisionKey);
   if (questions.length === 0) {
     return { stage, outcomeClass: 'skipped', decisionKeys: [], probabilityBands: {},
       checkpoint: null, latencyClass: 'unknown', fallbackCode: 'no-enabled-families',
@@ -1904,6 +1944,10 @@ export async function runRouteDecisionShadow({
     };
   }
 
+  // Partial coverage is never reported as full success.
+  if (skippedDecisions.length > 0 && result.status === 'accepted') {
+    result = { ...result, status: 'partial' };
+  }
   const receipt = buildDecisionShadowReceipt({
     stage,
     result,
@@ -1960,7 +2004,14 @@ export async function runRouteDecisionShadow({
       // Receipt loss is advisory — never fail the route over telemetry.
     }
   }
-  return receipt;
+  return skippedDecisions.length > 0
+    ? {
+        ...receipt,
+        skippedDecisionKeys,
+        skippedDecisions,
+        coverage: { asked: questions.length, total: wanted.length, complete: false },
+      }
+    : receipt;
 }
 
 // BL-018 (SPEC FR-006): the bounded-question `ask` seam — one batch through

package/template_project/.claude/ukit/index/sidecar-decision.mjs

@@ -296,67 +296,12 @@ export function buildStatePacket(decision, context) {
   return packet;
 }
 
-// ---------------------------------------------------------------------------
-// Adapter spawn — one bounded single-question batch to unic-decision.mjs.
-// Never throws: every failure resolves to a typed 'unavailable' result.
-// ---------------------------------------------------------------------------
-
-function runAdapterBatch({ spec, context, rootDir, config, batchId }) {
-  const cliPath = process.env.UKIT_DECISION_CLI_PATH || UNIC_DECISION_CLI_PATH;
-  const timeoutMs = Math.min(
-    (isFiniteNumber(config?.decisionPlane?.timeoutMs)
-      ? config.decisionPlane.timeoutMs
-      : ADAPTER_TIMEOUT_CAP_MS) + 1000,
-    ADAPTER_TIMEOUT_CAP_MS + 1000,
-  );
-  const batch = {
-    batchId,
-    boundary: 'sidecar',
-    deadlineMs: Math.max(500, timeoutMs - 1000),
-    statePacket: buildStatePacket(spec.decision, context),
-    questions: [spec.question],
-  };
-  let result = null;
-  try {
-    const spawned = spawnSync(
-      process.execPath,
-      [cliPath, '--root', rootDir],
-      {
-        cwd: rootDir,
-        input: JSON.stringify(batch),
-        encoding: 'utf8',
-        timeout: timeoutMs,
-      },
-    );
-    if (spawned && !spawned.error && spawned.status === 0 && spawned.stdout) {
-      result = JSON.parse(spawned.stdout);
-    } else {
-      result = { status: 'unavailable', fallbackCode: 'adapter-spawn-failed' };
-    }
-  } catch {
-    result = { status: 'unavailable', fallbackCode: 'adapter-spawn-failed' };
-  }
-  if (!result || typeof result !== 'object') {
-    result = { status: 'unavailable', fallbackCode: 'malformed-response' };
-  }
-  return result;
-}
-
-function validModelAnswer(result, decisionKey) {
-  const answers = Array.isArray(result?.answers) ? result.answers : [];
-  const answer = answers.find(
-    (a) => a?.decisionKey === decisionKey && a.validationStatus === 'valid',
-  );
-  return typeof answer?.value === 'string' ? answer.value : null;
-}
-
 /**
  * Resolve one sidecar decision. Returns a typed result; never throws.
  *   {decision, decisionKey, stage, answer, deterministic, source,
- *    outcomeClass, modelAnswer?, agreement?, fallbackCode}
- * `answer` is the authoritative value: the deterministic rule at 'off' and
- * 'shadow', the model's valid answer at 'canary'/'default', and the
- * deterministic rule again on any adapter failure (outcomeClass 'unavailable').
+ *    outcomeClass, fallbackPolicy}
+ * `answer` is always the deterministic rule at every stage: no model call is
+ * made, so there is no model answer, agreement or adapter fallback to report.
  */
 export async function runSidecarDecision({ decision, context = {}, rootDir, homeDir, config } = {}) {
   // Own-property lookup (W3-SD1): `SIDECAR_DECISIONS[name]` would also resolve