@ngockhoale/ukit 1.4.2 → 1.4.3

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

@@ -49,6 +49,7 @@ async function main() {
   const rootDir = getRootDir(args);
   const sharedStatePath = path.join(rootDir, '.claude', 'ukit', 'skill-router-state.json');
   const routeCachePath = path.join(rootDir, '.claude', 'ukit', 'route-cache.json');
+  const routeAuditPath = path.join(rootDir, '.ukit', 'storage', 'cache', 'route-audit.json');
   const previousState = await readJson(sharedStatePath, {});
   const targetFile = readFlagValue(args, '--target');
   const taskType = readFlagValue(args, '--type');
@@ -147,6 +148,9 @@ async function main() {
           ),
         }
       : null;
+    if (rescuedRouteSummary) {
+      applyRescueBiasToRouteSummary(rescuedRouteSummary);
+    }
     const sharedState = {
       ...cachedRouteState,
       source: 'task-route',
@@ -156,6 +160,9 @@ async function main() {
     };
     sharedState.fingerprint = buildRouteStateFingerprint(sharedState);
     await writeJson(sharedStatePath, sharedState);
+    await appendRouteAuditEntry(routeAuditPath, buildRouteAuditEntry({
+      state: sharedState,
+    }));
     printRouteState(sharedState);
     return;
   }
@@ -194,6 +201,10 @@ async function main() {
     indexGeneratedAtMs,
   });
   await writeJson(sharedStatePath, sharedState);
+  await appendRouteAuditEntry(routeAuditPath, buildRouteAuditEntry({
+    route,
+    state: sharedState,
+  }));
   await writeRecentCacheEntry(routeCachePath, compactRouteCacheState(sharedState), {
     maxEntries: DEFAULT_RECENT_CACHE_MAX_ENTRIES,
   });
@@ -274,13 +285,20 @@ async function prepareTaskRoute({
     intentMode,
     taskType: inferredTaskType,
   });
+  const executionCandidates = buildExecutionModeCandidates({
+    promptText: normalizedPrompt,
+    commandText: normalizedCommand,
+    targetFile: normalizedTarget,
+    intentMode,
+    executionScores,
+  });
   const executionMode = deriveExecutionMode({
     promptText: normalizedPrompt,
     commandText: normalizedCommand,
     targetFile: normalizedTarget,
     intentMode,
-    taskType: inferredTaskType,
     executionScores,
+    executionCandidates,
   });
   const preservedPrompt = normalizedPrompt || String(lastExplicitUserPromptText || '').trim();
 
@@ -297,6 +315,7 @@ async function prepareTaskRoute({
       taskType: inferredTaskType,
       intentMode,
       executionScores,
+      executionCandidates,
       executionMode,
     },
   };
@@ -381,6 +400,7 @@ async function finalizeTaskRoute({
     routeSummary.continuationState,
     previousRouteSummary?.continuationState ?? null,
   );
+  applyRescueBiasToRouteSummary(routeSummary);
   const approachSelector = routeSummary?.approachSelector ?? null;
 
   return {
@@ -828,7 +848,7 @@ function deriveIntentMode({ promptText = '', commandText = '', targetFile = null
   }
 
   if (concreteTask) {
-    if (/\b(bug|debug|error|crash|broken|failing|stack trace|triage|fix|login|timeout)\b/.test(lower)) {
+    if (/\b(bug|debug|error|crash|broken|failing|stack trace|triage|fix|timeout)\b/.test(lower)) {
       return 'debug-specific';
     }
     if (/\b(review|audit|diff|pr feedback|code review|kiem tra|soat)\b/.test(raw)) {
@@ -1287,9 +1307,11 @@ function buildRouteSummary({
     && contextRecommendation.command.trim();
   const executionMode = routingContext.executionMode ?? null;
   const executionScores = routingContext.executionScores ?? null;
+  const executionCandidates = routingContext.executionCandidates ?? null;
   const approachSelector = buildApproachSelectorResult({
     executionMode,
     executionScores,
+    executionCandidates,
   });
   const executionContract = buildExecutionContract(executionMode);
   const completionState = buildCompletionState({
@@ -1328,6 +1350,7 @@ function buildRouteSummary({
     editGuardHint,
     executionMode,
     executionScores,
+    executionCandidates,
     approachSelector,
     executionContract,
     completionState,
@@ -1362,6 +1385,12 @@ function deriveExecutionScores({
   const buildSignal = /\b(build|create|add|implement|feature)\b/.test(raw);
   const debugSignal = intentMode === 'debug-specific' || /\b(root cause|debug|triage|flaky|investigate|why)\b/.test(raw);
   const reviewSignal = intentMode === 'review-specific' || /\b(review|audit|verify|release readiness)\b/.test(raw);
+  const failureSignal = /\b(failing|failed|broken|error|crash|timeout|undefined|exception|eacces|trace)\b/.test(raw);
+  const impactSignal = /\b(map impact|impact|blast radius|all affected|across (?:runtime|templates|helpers|adapters|mirrors)|affected adapters|affected mirrors|inspect impact)\b/.test(raw);
+  const boundedEditSignal = /\b(one[- ]line|small|tiny|single|local|guard|log line|loading message|label)\b/.test(raw);
+  const implementSignal = /\b(implement|apply|update|modify|add|create|ship|deliver|fix)\b/.test(raw)
+    || /\bchange\s+.+\s+to\s+.+\b/.test(raw);
+  const explicitTarget = Boolean(targetFile);
 
   let editCertainty = 0;
   if (directTransformSignal) {
@@ -1375,7 +1404,7 @@ function deriveExecutionScores({
   let investigationNeed = 0;
   if (debugSignal) {
     investigationNeed = 3;
-  } else if (/\b(failing|broken|error|crash|timeout)\b/.test(raw)) {
+  } else if (failureSignal) {
     investigationNeed = 2;
   }
 
@@ -1408,6 +1437,17 @@ function deriveExecutionScores({
     blastRadius,
     verificationBurden,
     ambiguity,
+    sharedRisk,
+    directTransformSignal,
+    smallFixSignal,
+    buildSignal,
+    debugSignal,
+    reviewSignal,
+    failureSignal,
+    impactSignal,
+    boundedEditSignal,
+    implementSignal,
+    explicitTarget,
   };
 }
 
@@ -1417,40 +1457,64 @@ function deriveExecutionMode({
   targetFile = null,
   intentMode = null,
   executionScores = {},
+  executionCandidates = null,
 } = {}) {
   const raw = `${promptText ?? ''}\n${commandText ?? ''}`.toLowerCase();
   const scores = executionScores;
+  const candidates = executionCandidates ?? buildExecutionModeCandidates({
+    promptText,
+    commandText,
+    targetFile,
+    intentMode,
+    executionScores,
+  });
   const explicitReviewLead = /\b(review this|audit this|review\b.*\brelease readiness|verify\b.*\brelease readiness)\b/.test(raw);
+  const strongImpactLead = scores.sharedRisk
+    && (scores.impactSignal || /\b(check all affected|map all affected|across all affected)\b/.test(raw));
+  const boundedLocalBuildCandidate = scores.buildSignal && scores.boundedEditSignal && scores.explicitTarget && !scores.sharedRisk;
 
-  if (intentMode === 'review-specific' || explicitReviewLead) {
+  if ((intentMode === 'review-specific' || explicitReviewLead) && !scores.implementSignal) {
     return 'review-release';
   }
 
-  if (scores.blastRadius >= 3 && (scores.ambiguity >= 2 || scores.investigationNeed >= 2)) {
+  if (strongImpactLead || (scores.blastRadius >= 3 && (scores.ambiguity >= 2 || scores.investigationNeed >= 2))) {
     return 'map-impact';
   }
 
-  if (scores.blastRadius >= 3 || isSharedImpactFile(targetFile)) {
+  if (scores.sharedRisk && scores.failureSignal && scores.investigationNeed >= 2 && !scores.impactSignal) {
     return 'shared-edit';
   }
 
-  if (scores.investigationNeed >= 3) {
+  if (scores.blastRadius >= 3 || scores.sharedRisk) {
+    return 'shared-edit';
+  }
+
+  if (scores.investigationNeed >= 3 || (scores.failureSignal && scores.investigationNeed >= 2)) {
     return 'find-cause';
   }
 
+  if (scores.directTransformSignal && !scores.explicitTarget && scores.investigationNeed === 0 && !scores.sharedRisk) {
+    return 'local-build';
+  }
+
   if (
     scores.editCertainty >= 3
-    && scores.ambiguity === 0
+    && scores.ambiguity <= 1
     && scores.blastRadius === 0
     && scores.verificationBurden <= 1
   ) {
     return 'tiny-fix';
   }
 
+  if (boundedLocalBuildCandidate && scores.investigationNeed === 0) {
+    return 'local-fix';
+  }
+
   if (
     /\b(build|create|add|implement|feature|summary card)\b/.test(raw)
     && scores.investigationNeed === 0
     && scores.blastRadius < 3
+    && !scores.boundedEditSignal
   ) {
     return 'local-build';
   }
@@ -1459,7 +1523,107 @@ function deriveExecutionMode({
     return 'local-fix';
   }
 
-  return 'local-build';
+  return applySafeUpwardBias(candidates, 'local-build');
+}
+
+function buildExecutionModeCandidates({
+  promptText = '',
+  commandText = '',
+  targetFile = null,
+  intentMode = null,
+  executionScores = {},
+} = {}) {
+  const scores = executionScores;
+  const raw = `${promptText ?? ''}\n${commandText ?? ''}`.toLowerCase();
+  const explicitReviewLead = (intentMode === 'review-specific' || /\b(review this|audit this|review\b.*\brelease readiness|verify\b.*\brelease readiness)\b/.test(raw))
+    && !scores.implementSignal;
+
+  const modeScores = {
+    'tiny-fix': (
+      (scores.editCertainty * 4)
+      + (scores.directTransformSignal ? 4 : 0)
+      + (scores.explicitTarget ? 1 : 0)
+      - (scores.failureSignal ? 4 : 0)
+      - (scores.blastRadius * 4)
+      - (scores.ambiguity * 2)
+    ),
+    'local-fix': (
+      (scores.editCertainty * 3)
+      + (scores.boundedEditSignal ? 3 : 0)
+      + (scores.explicitTarget ? 1 : 0)
+      - (scores.failureSignal ? 2 : 0)
+      - (scores.blastRadius * 4)
+    ),
+    'local-build': (
+      (scores.buildSignal ? 6 : 0)
+      + (scores.editCertainty * 1)
+      + (scores.explicitTarget ? 1 : 0)
+      - (scores.boundedEditSignal ? 3 : 0)
+      - (scores.failureSignal ? 3 : 0)
+      - (scores.blastRadius * 4)
+    ),
+    'find-cause': (
+      (scores.investigationNeed * 4)
+      + (scores.failureSignal ? 3 : 0)
+      + (scores.debugSignal ? 2 : 0)
+      - (scores.blastRadius >= 3 ? 1 : 0)
+    ),
+    'shared-edit': (
+      (scores.sharedRisk ? 8 : 0)
+      + (scores.editCertainty * 1)
+      + (scores.buildSignal ? 1 : 0)
+      - (scores.impactSignal ? 2 : 0)
+    ),
+    'map-impact': (
+      (scores.sharedRisk ? 7 : 0)
+      + (scores.impactSignal ? 5 : 0)
+      + (scores.ambiguity * 2)
+      + scores.investigationNeed
+    ),
+    'review-release': (
+      (explicitReviewLead ? 10 : 0)
+      + (scores.reviewSignal ? 3 : 0)
+      - (scores.implementSignal ? 5 : 0)
+    ),
+  };
+
+  return Object.entries(modeScores)
+    .map(([mode, score]) => ({ mode, score }))
+    .sort((a, b) => b.score - a.score || executionModeRank(a.mode) - executionModeRank(b.mode));
+}
+
+function applySafeUpwardBias(candidates = [], fallbackMode = 'local-build') {
+  const [topCandidate, competingCandidate] = candidates;
+  if (!topCandidate) {
+    return fallbackMode;
+  }
+
+  if (!competingCandidate) {
+    return topCandidate.mode;
+  }
+
+  const scoreGap = Number(topCandidate.score ?? 0) - Number(competingCandidate.score ?? 0);
+  const rankGap = executionModeRank(competingCandidate.mode) - executionModeRank(topCandidate.mode);
+  if (scoreGap <= 1 && rankGap === 1) {
+    return competingCandidate.mode;
+  }
+
+  return topCandidate.mode;
+}
+
+function executionModeRank(mode = '') {
+  const orderedModes = [
+    'tiny-fix',
+    'local-fix',
+    'local-build',
+    'find-cause',
+    'shared-edit',
+    'map-impact',
+    'review-release',
+  ];
+
+  const index = orderedModes.indexOf(mode);
+  return index >= 0 ? index : orderedModes.length;
 }
 
 function buildExecutionContract(executionMode = null) {
@@ -1531,6 +1695,7 @@ function buildExecutionContract(executionMode = null) {
 function buildApproachSelectorResult({
   executionMode = null,
   executionScores = null,
+  executionCandidates = null,
 } = {}) {
   if (!executionMode) {
     return null;
@@ -1579,6 +1744,14 @@ function buildApproachSelectorResult({
     contextPolicy: selectedPolicy.contextPolicy,
     verificationPolicy: executionContract?.verificationPolicy ?? null,
     completionRule: executionContract?.completionRule ?? null,
+    competingMode: executionCandidates?.[1]?.mode ?? null,
+    competingScoreGap: executionCandidates?.length >= 2
+      ? Number(executionCandidates[0]?.score ?? 0) - Number(executionCandidates[1]?.score ?? 0)
+      : null,
+    candidateModes: (executionCandidates ?? []).slice(0, 3).map((entry) => ({
+      mode: entry.mode,
+      score: entry.score,
+    })),
   };
 }
 
@@ -1666,6 +1839,8 @@ function buildContinuationState({
     repeatCount: reasons.length > 0 ? 1 : 0,
     stuckRisk: null,
     rescueMode: null,
+    wideningBlocked: false,
+    milestonePriority: reasons.length > 0 ? 'normal' : null,
   };
 }
 
@@ -1680,6 +1855,8 @@ function advanceContinuationState(continuationState = null, previousContinuation
       repeatCount: 0,
       stuckRisk: null,
       rescueMode: null,
+      wideningBlocked: false,
+      milestonePriority: null,
     };
   }
 
@@ -1708,15 +1885,45 @@ function advanceContinuationState(continuationState = null, previousContinuation
   const stuckRisk = repeatCount >= 3
     ? 'high'
     : (repeatCount === 2 ? 'elevated' : null);
+  const wideningBlocked = repeatCount >= 2 && Boolean(rescueMode);
+  const nextMilestone = repeatCount >= 2 && currentReasons.includes('missing-write-evidence')
+    ? 'finish-write-before-more-analysis'
+    : (
+      repeatCount >= 2 && currentReasons.includes('pending-bounded-context')
+        ? 'finish-current-milestone-before-more-reading'
+        : continuationState.nextMilestone
+    );
 
   return {
     ...continuationState,
+    nextMilestone,
     repeatCount,
     stuckRisk,
     rescueMode,
+    wideningBlocked,
+    milestonePriority: wideningBlocked ? 'execute-current-milestone' : 'normal',
   };
 }
 
+function applyRescueBiasToRouteSummary(routeSummary = null) {
+  if (!routeSummary || typeof routeSummary !== 'object') {
+    return routeSummary;
+  }
+
+  const continuationState = routeSummary.continuationState;
+  if (
+    continuationState?.repeatCount >= 2
+    && continuationState?.wideningBlocked
+    && (continuationState.reasons ?? []).includes('missing-write-evidence')
+  ) {
+    routeSummary.nextActionType = 'execute-current-milestone';
+    routeSummary.nextActionCommand = null;
+    routeSummary.helperHint = null;
+  }
+
+  return routeSummary;
+}
+
 function deriveExecutionPolicy({
   taskType = 'simple',
   mode = 'minimal',
@@ -2368,6 +2575,67 @@ function shouldIncludeRecentOutput({
   return true;
 }
 
+function buildRouteAuditEntry({ route = null, state = null } = {}) {
+  const routingContext = route?.routingContext ?? state?.routingContext ?? {};
+  const routeSummary = route?.routeSummary ?? state?.routeSummary ?? {};
+  const candidateModes = Array.isArray(routeSummary?.approachSelector?.candidateModes)
+    ? routeSummary.approachSelector.candidateModes
+    : [];
+
+  return {
+    ts: Date.now(),
+    source: state?.source ?? 'task-route',
+    requestKey: state?.requestKey ?? null,
+    adapter: routingContext.adapter ?? 'claude',
+    promptFingerprint: stableMachineDigest({
+      prompt: routingContext.lastExplicitUserPromptText ?? '',
+      adapter: routingContext.adapter ?? 'claude',
+    }),
+    targetFile: route?.routingContext?.targetFile ?? null,
+    taskType: routingContext.taskType ?? null,
+    executionMode: routeSummary.executionMode ?? null,
+    competingMode: routeSummary?.approachSelector?.competingMode ?? null,
+    competingScoreGap: routeSummary?.approachSelector?.competingScoreGap ?? null,
+    candidateModes: candidateModes.slice(0, 3),
+    nextActionType: routeSummary.nextActionType ?? null,
+    nextMilestone: routeSummary?.continuationState?.nextMilestone ?? null,
+    repeatCount: routeSummary?.continuationState?.repeatCount ?? null,
+    rescueMode: routeSummary?.continuationState?.rescueMode ?? null,
+    wideningBlocked: routeSummary?.continuationState?.wideningBlocked ?? null,
+  };
+}
+
+async function appendRouteAuditEntry(filePath, entry) {
+  if (!entry || typeof entry !== 'object') {
+    return;
+  }
+
+  const existing = await readJson(filePath, { entries: [] });
+  const entries = Array.isArray(existing?.entries) ? existing.entries : [];
+  const dedupeKey = stableMachineDigest({
+    requestKey: entry.requestKey,
+    executionMode: entry.executionMode,
+    nextActionType: entry.nextActionType,
+    nextMilestone: entry.nextMilestone,
+    repeatCount: entry.repeatCount,
+    rescueMode: entry.rescueMode,
+  });
+  const filtered = entries.filter((item) => {
+    const itemKey = stableMachineDigest({
+      requestKey: item?.requestKey ?? null,
+      executionMode: item?.executionMode ?? null,
+      nextActionType: item?.nextActionType ?? null,
+      nextMilestone: item?.nextMilestone ?? null,
+      repeatCount: item?.repeatCount ?? null,
+      rescueMode: item?.rescueMode ?? null,
+    });
+    return itemKey !== dedupeKey;
+  });
+  await writeJson(filePath, {
+    entries: [entry, ...filtered].slice(0, 40),
+  });
+}
+
 async function readJson(filePath, fallback = null) {
   try {
     return JSON.parse(await fs.readFile(filePath, 'utf8'));

package/templates/.claude/ukit/runtime/reinject-context.mjs

@@ -66,9 +66,12 @@ async function main() {
     line.startsWith('- Recent routed lane:')
     || line.startsWith('- Current approach:')
     || line.startsWith('- Completion debt:')
+    || line.startsWith('- Execution rule:')
     || line.startsWith('- Continuation required:')
     || line.startsWith('- Stuck-lane rescue:')
+    || line.startsWith('- Rescue rule:')
     || line.startsWith('- Continue rule:')
+    || line.startsWith('- Decision rule:')
     || line.startsWith('- Previous context:')
     || line.startsWith('- Recent command output:')
     || line.startsWith('- Recent delegation hint:')
@@ -113,9 +116,9 @@ async function main() {
       compressEnabled
         ? compactContextBlock(bodyLines, {
             maxTokens,
-            maxLines: 12,
-            anchorLines: anchorLines.slice(0, 3),
-            maxAnchors: 3,
+            maxLines: 14,
+            anchorLines: anchorLines.slice(0, 6),
+            maxAnchors: 6,
           })
         : {
             text: bodyLines.join('\n'),
@@ -284,7 +287,7 @@ function buildStaticGuidanceLines(state = {}, { compact = true } = {}) {
       '- Simple: read docs/MEMORY.md; use context resolver for related files.',
       '- Non-trivial: read docs/MEMORY.md + docs/PROJECT.md + docs/CODE_MAP.md.',
       '- WORKLOG: read only for continuation/debugging.',
-      '- If confidence is low or the area is high-risk, escalate analysis or ask 1 short clarify question.',
+      '- If one safe path is clear, execute it; ask only when choices or risk need a user decision.',
       '- Reuse existing code. Use yarn. Run tests after code changes.',
       '- Scope-based verification: match verify effort to change scope.',
       '- Auto-activate matching project-local skills from prompt + tool/file signals.',
@@ -306,7 +309,7 @@ function buildStaticGuidanceLines(state = {}, { compact = true } = {}) {
   return [
     currentLaneLine,
     '- WORKLOG: read only for continuation/debugging.',
-    '- If confidence is low or the area is high-risk, escalate analysis or ask 1 short clarify question.',
+    '- If one safe path is clear, execute it; ask only when choices or risk need a user decision.',
     '- Reuse existing code; use yarn; verify after changes with scope-matched effort.',
     '- Auto-activate matching project-local skills from prompt + tool/file signals.',
   ];
@@ -560,6 +563,9 @@ function buildApproachSelectorLines(state = {}) {
         || null;
       lines.push('- Completion debt: ' + missingEvidence.join(', ') + (completionRule ? ` | gate=${completionRule}` : ''));
       lines.push('- Continue rule: while completion debt remains, do not end with done/applied/fixed language unless a real blocker is found.');
+      if (missingEvidence.includes('write-evidence')) {
+        lines.push('- Execution rule: execute the next safe milestone first; explain only if blocked or the risk changes.');
+      }
     }
   }
 
@@ -573,6 +579,9 @@ function buildApproachSelectorLines(state = {}) {
         + (continuationState.stuckRisk ? ` | risk=${continuationState.stuckRisk}` : '')
         + (continuationState.rescueMode ? ` | mode=${continuationState.rescueMode}` : ''));
     }
+    if (continuationState.wideningBlocked) {
+      lines.push('- Rescue rule: do not widen reads yet; execute the current milestone before more analysis.');
+    }
     if ((continuationState.reasons ?? []).includes('pending-bounded-context')) {
       lines.push('- Continue rule: pull-indexed-context is an internal continuation step; after the bounded read, continue to edit/verify in the same turn when safe.');
     }
@@ -639,6 +648,8 @@ function deriveContinuationState(state = {}) {
     repeatCount: 1,
     stuckRisk: null,
     rescueMode: null,
+    wideningBlocked: false,
+    milestonePriority: 'normal',
   };
 }
 

package/templates/.codex/README.md

@@ -12,7 +12,7 @@ Auto-generated by UKit for OpenAI Codex.
 - Do not make end users memorize skill names, helper scripts, or routing internals unless they are debugging UKit itself.
 - **Treat helper commands as internal orchestration. Do not ask end users to run them.**
 
-## UKit v1.4.2 Shared Runtime
+## UKit v1.4.3 Shared Runtime
 
 - Shared runtime state lives in `.ukit/storage/`.
 - Treat `.ukit/storage/config.json` as the source of compact, token-pipeline, router, memory, validation, and Safe Patch guardrail toggles.

package/templates/ukit/README.md

@@ -1,6 +1,6 @@
 # UKit Shared Runtime
 
-This folder stores shared UKit runtime state for v1.4.2 features.
+This folder stores shared UKit runtime state for v1.4.3 features.
 
 - `storage/config.json` — runtime feature flags and defaults
 - `storage/cache/` — prompt-cache, compact history, compact pressure state, output summaries, and preserved raw tool outputs under `storage/cache/tee/`

package/templates/ukit/storage/config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.4.2",
+  "version": "1.4.3",
   "agent": "claude-code",
   "autonomy": {
     "level": "balanced",