@ngockhoale/ukit 3.0.3 → 3.0.5

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

@@ -18,6 +18,14 @@ import {
 import { ROUTE_CATALOG } from './route-catalog.mjs';
 import { detectUnicGateway } from './unic-gateway.mjs';
 import { withAsyncLock } from '../runtime/async-lock.mjs';
+import { appendDecisionReceipt, recordLedgerEvent } from '../runtime/execution-ledger.mjs';
+import {
+  RESUMABLE_RUN_SCHEMA_VERSION,
+  readResumableRun,
+  resumableRunSourceFingerprint,
+  safeTaskId,
+  writeResumableRun,
+} from '../runtime/resumable-run.mjs';
 
 const {
   resolveContext,
@@ -280,6 +288,22 @@ export function resolveRouteStage(config = null, key) {
   return ROUTE_SCHEMA_STAGES.has(stage) ? stage : 'off';
 }
 
+// FR-008 (M07): decision-plane stage resolvers — same absent/malformed → 'off'
+// contract as routing.* stages. `decisionPlane.enabled === false` is the global
+// emergency disable and reads as 'off' regardless of stage keys.
+export function resolveDecisionPlaneStage(config = null) {
+  const plane = config?.decisionPlane;
+  if (!plane || typeof plane !== 'object' || plane.enabled === false) return 'off';
+  return ROUTE_SCHEMA_STAGES.has(plane.stage) ? plane.stage : 'off';
+}
+
+// Per-family override wins over the global stage; absence inherits it.
+export function resolveDecisionFamilyStage(config = null, family) {
+  const globalStage = resolveDecisionPlaneStage(config);
+  const override = config?.decisionPlane?.families?.[family]?.stage;
+  return ROUTE_SCHEMA_STAGES.has(override) ? override : globalStage;
+}
+
 // FR-003 (M01.2'): derive the additive riskFloor from hard signals. Codes are
 // collected in ROUTE_RISK_REASON_CODES table order; the floor is 'high-risk' iff
 // any of the first six (floor-raising) codes fired — informational codes never
@@ -1420,6 +1444,8 @@ export async function routeTask(input = {}, { signal = null, deadlineMs = null,
     recentOutputSnapshot,
     previousRouteSummary: null,
     escalationConfig,
+    sessionId: normalizedInput.sessionId ?? null,
+    indexGeneratedAtMs,
   });
   const sharedState = createSharedRouteState({
     route,
@@ -1641,6 +1667,8 @@ async function main() {
     recentOutputSnapshot,
     previousRouteSummary: previousState?.routeSummary ?? null,
     escalationConfig,
+    sessionId,
+    indexGeneratedAtMs,
   });
   await seedHelperCaches({
     rootDir,
@@ -1801,6 +1829,372 @@ async function prepareTaskRoute({
   };
 }
 
+// --- M07 decision-plane shadow hook (TASK-005, SPEC §5 FR-008/FR-011) ----------
+// Stage-gated adapter call at route finalize. 'off' (or enabled:false) → zero
+// adapter invocation, zero output change. Any other stage → the standalone
+// unic-decision.mjs CLI is spawned once with a bounded batch, its typed result
+// is folded into a redacted receipt (codes/bands only — never prompts, state
+// text, or raw probabilities), the receipt rides routeSummary.decisionPlane
+// additively, and one row is appended to .ukit/storage/decisions.tsv via
+// execution-ledger's appendDecision. Deterministic policy stays authoritative:
+// the shadow answer never rewrites a route field. Every failure path is
+// fail-silent to the deterministic baseline.
+const UNIC_DECISION_CLI_PATH = path.join(__routeTaskDir, 'unic-decision.mjs');
+const DECISION_SHADOW_TIMEOUT_CAP_MS = 3000;
+
+// Route-side shadow questions — mirror of the DECISION_REGISTRY entries owned
+// by taskRouting outside the preflight bundle (src/decision/registry.js).
+// Candidates are protocol-local labels, not user-facing prose.
+const ROUTE_SHADOW_QUESTIONS = Object.freeze([
+  {
+    decisionKey: 'route.intent-kind.v1',
+    family: 'route',
+    kind: 'choice',
+    instruction: 'Intent kind for the route: informational | mutation | investigation | review | delivery.',
+    candidates: ['informational', 'mutation', 'investigation', 'review', 'delivery'],
+  },
+  {
+    decisionKey: 'route.rigor.v1',
+    family: 'rigor',
+    kind: 'score',
+    instruction: 'R0-R4 rigor recommendation inside deterministic floors.',
+    candidates: ['r0', 'r1', 'r2', 'r3', 'r4'],
+  },
+]);
+
+// Only families whose resolved stage is not 'off' get a question.
+export function buildShadowDecisionQuestions(config = null) {
+  return ROUTE_SHADOW_QUESTIONS
+    .filter((q) => resolveDecisionFamilyStage(config, q.family) !== 'off')
+    .map(({ family, ...question }) => question);
+}
+
+// Probability → band for receipts. Bands only; raw probabilities never leave
+// the adapter result.
+function probabilityBand(value) {
+  if (!Number.isFinite(value)) return 'unknown';
+  if (value >= 0.8) return 'high';
+  if (value >= 0.5) return 'medium';
+  return 'low';
+}
+
+// Deterministic baselines the shadow answers are compared against. Only fields
+// the deterministic route already computes; null baseline → 'unknown'.
+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;
+  return null;
+}
+
+// Map a validated answer value onto its candidate label. Choice answers already
+// carry the label; score answers carry a 1-based integer over the question's
+// ordered candidates (2 → 'r1'). Returns null when no label can be resolved.
+function answerCandidateLabel(answer, question) {
+  if (question?.kind === 'score') {
+    const candidates = Array.isArray(question.candidates) ? question.candidates : [];
+    return Number.isInteger(answer?.value) ? candidates[answer.value - 1] ?? null : null;
+  }
+  return typeof answer?.value === 'string' ? answer.value : null;
+}
+
+// Fold a CLI batch result into the redacted receipt shape (FR-009):
+// {decisionKeys, probabilityBands, outcomeClass, checkpoint, latencyClass,
+//  fallbackCode, agreement}. Never carries state text, prompts, or secrets.
+function buildDecisionShadowReceipt({ stage, result, routeSummary, questions = [] }) {
+  const questionByKey = new Map(questions.map((q) => [q.decisionKey, q]));
+  const answers = Array.isArray(result?.answers) ? result.answers : [];
+  const probabilityBands = {};
+  let compared = 0;
+  let agreed = 0;
+  for (const answer of answers) {
+    if (answer?.validationStatus !== 'valid') continue;
+    const label = answerCandidateLabel(answer, questionByKey.get(answer.decisionKey));
+    const selectedProbability = label === null ? null : answer.probabilities?.[label];
+    probabilityBands[answer.decisionKey] = probabilityBand(selectedProbability);
+    const baseline = shadowBaselineFor(answer.decisionKey, routeSummary);
+    if (label !== null && baseline !== null && baseline !== undefined) {
+      compared += 1;
+      if (label.toLowerCase() === String(baseline).toLowerCase()) agreed += 1;
+    }
+  }
+  const agreement = compared === 0
+    ? 'unknown'
+    : agreed === compared ? 'agree' : agreed === 0 ? 'disagree' : 'mixed';
+  return {
+    stage,
+    outcomeClass: result?.status ?? 'unavailable',
+    decisionKeys: answers.map((a) => a?.decisionKey).filter(Boolean),
+    probabilityBands,
+    checkpoint: result?.checkpoint ?? null,
+    latencyClass: result?.latencyClass ?? 'unknown',
+    fallbackCode: result?.fallbackCode ?? null,
+    agreement,
+  };
+}
+
+/**
+ * Run the decision-plane shadow adapter for a finalized route. Returns the
+ * redacted receipt, or null when the plane is off / no family is enabled.
+ * Deadline-bounded (spawn timeout capped at DECISION_SHADOW_TIMEOUT_CAP_MS);
+ * every failure degrades to a receipt with outcomeClass 'unavailable' —
+ * never throws, never blocks the route.
+ */
+export async function runRouteDecisionShadow({
+  rootDir = process.cwd(),
+  config = null,
+  routeSummary = null,
+  routingContext = {},
+  spawnImpl = spawnSync,
+  appendDecisionImpl = null,
+  now = () => Date.now(),
+} = {}) {
+  const stage = resolveDecisionPlaneStage(config);
+  if (stage === 'off') return null;
+  const questions = buildShadowDecisionQuestions(config);
+  if (questions.length === 0) {
+    return { stage, outcomeClass: 'skipped', decisionKeys: [], probabilityBands: {},
+      checkpoint: null, latencyClass: 'unknown', fallbackCode: 'no-enabled-families',
+      agreement: 'unknown' };
+  }
+
+  const cliPath = process.env.UKIT_DECISION_CLI_PATH || UNIC_DECISION_CLI_PATH;
+  const timeoutMs = Math.min(
+    (Number.isFinite(config?.decisionPlane?.timeoutMs)
+      ? config.decisionPlane.timeoutMs
+      : DECISION_SHADOW_TIMEOUT_CAP_MS) + 1000,
+    DECISION_SHADOW_TIMEOUT_CAP_MS + 1000,
+  );
+  const batch = {
+    batchId: `route-shadow-${now().toString(36)}`,
+    boundary: 'route',
+    deadlineMs: Math.max(500, timeoutMs - 1000),
+    statePacket: {
+      stateVersion: 1,
+      taskClass: routingContext.taskClass ?? routingContext.taskType ?? 'unknown',
+      intentSignals: routingContext.intentMode ? [routingContext.intentMode] : [],
+      targetClass: routingContext.targetFile ? 'file-target' : 'no-target',
+      execution: routeSummary?.executionMode ? { mode: routeSummary.executionMode } : {},
+      riskSignals: routeSummary?.riskFloor?.codes ?? [],
+    },
+    questions,
+  };
+
+  let result = null;
+  const startedAt = now();
+  try {
+    const spawned = spawnImpl(
+      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' };
+  }
+  if (result.latencyClass == null) {
+    const elapsed = now() - startedAt;
+    result = {
+      ...result,
+      latencyClass: elapsed < 250 ? 'fast' : elapsed < 2000 ? 'normal' : 'slow',
+    };
+  }
+
+  const receipt = buildDecisionShadowReceipt({ stage, result, routeSummary, questions });
+  // Append-only receipt row (decisions.tsv): codes/bands only via the ledger's
+  // typed receipt writer (statically imported above alongside recordLedgerEvent).
+  try {
+    const append = appendDecisionImpl ?? appendDecisionReceipt;
+    await append(rootDir, {
+      kind: 'shadow',
+      boundary: 'route',
+      stage,
+      outcomeClass: receipt.outcomeClass,
+      checkpoint: receipt.checkpoint,
+      latencyClass: receipt.latencyClass,
+      decisionKeys: receipt.decisionKeys,
+      agreement: receipt.agreement,
+      fallbackCode: receipt.fallbackCode,
+      now: now(),
+    });
+  } catch {
+    // Receipt loss is advisory — never fail the route over telemetry.
+  }
+  return receipt;
+}
+
+// --- M04.1 resumable run emit (TASK-007, SPEC §5 FR-013..FR-015) --------------
+// At route finalize, stage != 'off' persists/updates the C10 record under
+// .ukit/storage/runs/<taskId>.json through resumable-run.mjs's fail-closed
+// lock/journal path, then lands a bounded `resumable-run` pointer event on the
+// execution ledger. Stage 'off' (or absent/malformed) returns null before any
+// I/O — the route stays byte-identical. Every failure is advisory: routing never
+// fails over run-state persistence.
+
+// Same absent/malformed → 'off' contract as the routing.* stage resolvers; the
+// stage key lives under continuity.resumableRun (TASK-001 config block).
+export function resolveResumableRunStage(config = null) {
+  const stage = config?.continuity?.resumableRun?.stage;
+  return ROUTE_SCHEMA_STAGES.has(stage) ? stage : 'off';
+}
+
+// The logical task boundary is the explicit user prompt — a new prompt means a
+// new task, so the persisted record resets instead of merging stale plans.
+// Hashed: prompt text never persists (C10 redaction contract).
+function resumableTaskBoundary(routingContext = {}) {
+  const text = String(
+    routingContext.lastExplicitUserPromptText ?? routingContext.promptText ?? '',
+  ).trim();
+  return text
+    ? crypto.createHash('sha256').update(text).digest('hex').slice(0, 32)
+    : 'no-prompt';
+}
+
+// Session-scoped when a session id exists (one record file per session, reset by
+// taskBoundary); prompt-scoped otherwise so concurrent anonymous routes never
+// collide on a shared 'default' file.
+function resumableTaskId({ sessionId = null, taskBoundary }) {
+  return safeTaskId(sessionId || `prompt-${taskBoundary}`);
+}
+
+// Merge semantics: within the same taskBoundary the record is UPDATED — plans
+// (hypotheses/decisions/failures) and completed receipts carry forward; a new
+// boundary starts a fresh record. The phase that just completed is appended to
+// completedBlocks when it changes.
+function buildResumableRunRecord({
+  taskId,
+  taskBoundary,
+  routeSummary,
+  previousRecord = null,
+  sourceSnapshot,
+}) {
+  const previous = previousRecord && previousRecord.taskBoundary === taskBoundary
+    ? previousRecord
+    : null;
+  const phase = String(
+    routeSummary?.continuationState?.nextMilestone
+      ?? routeSummary?.nextActionType
+      ?? 'routed',
+  ).slice(0, 512);
+  const completedBlocks = [...(previous?.workflow?.completedBlocks ?? [])];
+  const previousPhase = previous?.workflow?.phase;
+  if (previousPhase && previousPhase !== phase && !completedBlocks.includes(previousPhase)) {
+    completedBlocks.push(previousPhase);
+  }
+  const nextAction = routeSummary?.nextActionCommand ?? routeSummary?.nextActionType ?? null;
+  return {
+    schemaVersion: RESUMABLE_RUN_SCHEMA_VERSION,
+    taskId,
+    taskBoundary,
+    route: {
+      routeVersion: String(ROUTE_VERSION),
+      mode: String(routeSummary?.executionMode ?? 'unknown'),
+      rigor: String(routeSummary?.execution?.rigor ?? 'unresolved'),
+      contractVersion: String(ROUTE_CONTRACT_VERSION),
+    },
+    budget: {
+      policyVersion: String(routeSummary?.ceremonyBudget?.policyVersion ?? ROUTE_CONTRACT_VERSION),
+      consumed: 0,
+      remaining: Number.isFinite(routeSummary?.ceremonyBudget?.limits?.maxReadPasses)
+        ? routeSummary.ceremonyBudget.limits.maxReadPasses
+        : 0,
+    },
+    workflow: {
+      workflowId: String(routeSummary?.workflowPolicyName ?? 'route'),
+      workflowVersion: 'v1',
+      phase,
+      completedBlocks,
+    },
+    invariants: previous?.invariants ?? [],
+    hypotheses: previous?.hypotheses ?? [],
+    decisions: previous?.decisions ?? [],
+    evidenceRefs: previous?.evidenceRefs ?? [],
+    escalationHistory: previous?.escalationHistory ?? [],
+    unresolvedFailures: previous?.unresolvedFailures ?? [],
+    nextAction: typeof nextAction === 'string' ? nextAction.slice(0, 512) : null,
+    sourceSnapshot,
+  };
+}
+
+/**
+ * Emit/update the C10 record at route finalize. Returns the bounded pointer
+ * ({taskId, taskBoundary, stage, status}) that rides routeSummary.resumableRun
+ * additively, or null when the stage is off. Never throws.
+ */
+export async function emitResumableRun({
+  rootDir = process.cwd(),
+  config = null,
+  routeSummary = null,
+  routingContext = {},
+  sessionId = null,
+  indexGeneratedAtMs = null,
+  projectVerification = null,
+  signal = null,
+  deadlineMs = null,
+} = {}) {
+  const stage = resolveResumableRunStage(config);
+  if (stage === 'off') return null;
+  try {
+    const taskBoundary = resumableTaskBoundary(routingContext);
+    const taskId = resumableTaskId({ sessionId, taskBoundary });
+    const fingerprint = await resumableRunSourceFingerprint(rootDir, { indexGeneratedAtMs });
+    const sourceSnapshot = {
+      source: String(projectVerification?.fingerprint ?? 'none'),
+      ...fingerprint,
+    };
+    // Read-then-write: within the same boundary the record is updated (plans and
+    // receipts carry forward); a boundary change reads 'absent' → fresh record.
+    const resumed = await readResumableRun(rootDir, { taskId, taskBoundary });
+    const previousRecord = resumed.status === 'fresh' || resumed.status === 'stale'
+      ? resumed.record
+      : null;
+    const record = buildResumableRunRecord({
+      taskId,
+      taskBoundary,
+      routeSummary,
+      previousRecord,
+      sourceSnapshot,
+    });
+    const write = await writeResumableRun(rootDir, record, {
+      signal,
+      deadlineMs: deadlineMs ?? undefined,
+      config: { continuity: { resumableRun: { stage } } },
+    });
+    const status = write.ok
+      ? 'written'
+      : (write.journaled ? 'journaled' : `skipped-${write.reason ?? 'unknown'}`);
+    const pointer = { taskId, taskBoundary, stage, status };
+    // Ledger pointer event — same fail-closed journal discipline; advisory only.
+    try {
+      await recordLedgerEvent(
+        { type: 'resumable-run', run: { ...pointer, updatedAt: record.updatedAt ?? Date.now() } },
+        {
+          projectRoot: rootDir,
+          payload: sessionId ? { session_id: sessionId } : {},
+          signal,
+          deadlineMs: deadlineMs ?? undefined,
+        },
+      );
+    } catch {
+      // ledger pointer loss is advisory — the record itself is already durable
+    }
+    return pointer;
+  } catch {
+    return null; // persistence must never fail the route
+  }
+}
+
 async function finalizeTaskRoute({
   rootDir = process.cwd(),
   commandNamespace = '.claude',
@@ -1813,6 +2207,8 @@ async function finalizeTaskRoute({
   recentOutputSnapshot = null,
   previousRouteSummary = null,
   escalationConfig = null,
+  sessionId = null,
+  indexGeneratedAtMs = null,
 } = {}) {
   const absoluteRoot = path.resolve(rootDir);
   const activeSkills = preparedRoute?.activeSkills ?? [];
@@ -1910,6 +2306,35 @@ async function finalizeTaskRoute({
     targetFile: routingContext.targetFile ?? null,
   });
   appendRiskEscalationSegment(routeSummary);
+  // M07 (TASK-005): stage-gated decision-plane shadow call. 'off' → null and
+  // nothing else happens (byte-identical route); any other stage → bounded
+  // adapter batch, redacted receipt attached additively, decisions.tsv row.
+  const decisionShadow = await runRouteDecisionShadow({
+    rootDir: absoluteRoot,
+    config: escalationConfig,
+    routeSummary,
+    routingContext,
+  });
+  if (decisionShadow) {
+    routeSummary.decisionPlane = decisionShadow;
+  }
+  // M04.1 (TASK-007): stage-gated resumable-run emit. 'off' → null and nothing
+  // else happens (byte-identical route); any other stage → the C10 record is
+  // persisted/updated under .ukit/storage/runs/ and a bounded pointer lands on
+  // the execution ledger. The pointer rides routeSummary.resumableRun so the
+  // shared route state carries the taskId reinject-context resumes from.
+  const resumableRun = await emitResumableRun({
+    rootDir: absoluteRoot,
+    config: escalationConfig,
+    routeSummary,
+    routingContext,
+    sessionId,
+    indexGeneratedAtMs,
+    projectVerification,
+  });
+  if (resumableRun) {
+    routeSummary.resumableRun = resumableRun;
+  }
   const approachSelector = routeSummary?.approachSelector ?? null;
 
   return {
@@ -2641,6 +3066,17 @@ async function deriveVerificationPlan({
       reasons.push('highRiskFallback');
       commands.push(buildScriptCommand(packageManager, 'test'));
     }
+
+    // Non-empty floor (RULES.md test-selection §3): when nothing targeted and
+    // no fallback resolved, the plan must still route the broadest test
+    // script the project declares — an empty selection is never permitted.
+    if (commands.length === 0 && fallbackCommands.length === 0) {
+      const floorScript = scripts['test:release-core'] ? 'test:release-core' : (scripts.test ? 'test' : null);
+      if (floorScript) {
+        reasons.push('nonEmptyFloor');
+        fallbackCommands.push(buildScriptCommand(packageManager, floorScript));
+      }
+    }
   }
 
   if (commands.length === 0 && fallbackCommands.length === 0) {
@@ -4600,6 +5036,10 @@ export function compactRouteSummary(routeSummary = null) {
     nextActionType: routeSummary.nextActionType ?? null,
     nextActionCommand: routeSummary.nextActionCommand ?? null,
     helperHint: routeSummary.helperHint ?? null,
+    // M04.1 (TASK-007): the resumable-run pointer survives compaction so
+    // reinject-context resumes from the same taskId/boundary. Conditional
+    // spread — stage-off output stays byte-identical (no key when absent).
+    ...(routeSummary.resumableRun ? { resumableRun: routeSummary.resumableRun } : {}),
     // v3 advisory blocks: survive compaction so printRouteState and cached/shared route
     // states still emit them. Null when the lane suppresses them — cheap either way.
     workflowPolicyName: routeSummary.workflowPolicyName ?? null,
@@ -4617,6 +5057,10 @@ export function compactRouteSummary(routeSummary = null) {
     // skill-router-state.json compaction. Conditional spread keeps stage-off
     // output byte-identical (no key emitted when the field is absent).
     ...(routeSummary.riskEscalation ? { riskEscalation: routeSummary.riskEscalation } : {}),
+    // M07 (TASK-005): the decision-plane shadow receipt survives compaction so
+    // persisted route state keeps the redacted outcome. Conditional spread —
+    // stage-off output stays byte-identical (no key emitted when absent).
+    ...(routeSummary.decisionPlane ? { decisionPlane: routeSummary.decisionPlane } : {}),
     // M01.1 compact whitelist (C01): grouped fields survive compaction minus verbose
     // evidence; absent entirely when the route schema stage is off.
     ...(compactResolvedRoute(routeSummary) ?? {}),

package/template_project/.claude/ukit/index/task-budget-validator.mjs

@@ -95,23 +95,19 @@ function countTargetFiles(body) {
 
 function countTestCases(body) {
   if (body == null) return 0;
-  let count = 0;
-  let sawHeader = false;
-  let sawSeparator = false;
-  for (const line of body.split('\n')) {
-    const trimmed = line.trim();
-    if (!trimmed.startsWith('|')) continue;
-    if (!sawHeader) {
-      sawHeader = true;
-      continue;
-    }
-    if (!sawSeparator && /^\|[-\s|]+\|\s*$/.test(trimmed)) {
-      sawSeparator = true;
-      continue;
-    }
-    count += 1;
+  const rows = body
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith('|'));
+  const separatorIdx = rows.findIndex((r) => /^\|[-\s|]+\|\s*$/.test(r));
+  if (separatorIdx >= 0) {
+    // Header row + separator row precede the data rows.
+    return rows.length - (separatorIdx + 1);
   }
-  return count;
+  // No separator row: a leading canonical header (first cell '#') is still a
+  // header; every other pipe row is a test case — a headerless table counts
+  // every row, never silently dropping the first.
+  return rows[0] && /^\|\s*#\s*\|/.test(rows[0]) ? rows.length - 1 : rows.length;
 }
 
 function extractVerificationCommands(body) {