@ngockhoale/ukit 1.4.2 → 1.4.4

package/templates/.claude/hooks/skill-router.sh

@@ -273,7 +273,7 @@ const { pathToFileURL } = require('url');
     }
 
     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)) {
@@ -1307,9 +1307,11 @@ const { pathToFileURL } = require('url');
       && 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({
@@ -1345,6 +1347,7 @@ const { pathToFileURL } = require('url');
       policyMode,
       executionMode,
       executionScores,
+      executionCandidates,
       approachSelector,
       executionContract,
       completionState,
@@ -1371,6 +1374,12 @@ const { pathToFileURL } = require('url');
     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) {
@@ -1384,7 +1393,7 @@ const { pathToFileURL } = require('url');
     let investigationNeed = 0;
     if (debugSignal) {
       investigationNeed = 3;
-    } else if (/\b(failing|broken|error|crash|timeout)\b/.test(raw)) {
+    } else if (failureSignal) {
       investigationNeed = 2;
     }
 
@@ -1417,6 +1426,17 @@ const { pathToFileURL } = require('url');
       blastRadius,
       verificationBurden,
       ambiguity,
+      sharedRisk,
+      directTransformSignal,
+      smallFixSignal,
+      buildSignal,
+      debugSignal,
+      reviewSignal,
+      failureSignal,
+      impactSignal,
+      boundedEditSignal,
+      implementSignal,
+      explicitTarget,
     };
   }
 
@@ -1426,40 +1446,64 @@ const { pathToFileURL } = require('url');
     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';
     }
@@ -1468,7 +1512,107 @@ const { pathToFileURL } = require('url');
       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) {
@@ -1540,6 +1684,7 @@ const { pathToFileURL } = require('url');
   function buildApproachSelectorResult({
     executionMode = null,
     executionScores = null,
+    executionCandidates = null,
   } = {}) {
     if (!executionMode) {
       return null;
@@ -1588,6 +1733,14 @@ const { pathToFileURL } = require('url');
       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,
+      })),
     };
   }
 
@@ -1675,6 +1828,8 @@ const { pathToFileURL } = require('url');
       repeatCount: reasons.length > 0 ? 1 : 0,
       stuckRisk: null,
       rescueMode: null,
+      wideningBlocked: false,
+      milestonePriority: reasons.length > 0 ? 'normal' : null,
     };
   }
 
@@ -1689,6 +1844,8 @@ const { pathToFileURL } = require('url');
         repeatCount: 0,
         stuckRisk: null,
         rescueMode: null,
+        wideningBlocked: false,
+        milestonePriority: null,
       };
     }
 
@@ -1717,15 +1874,45 @@ const { pathToFileURL } = require('url');
     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;
+  }
+
   const SHARED_IMPACT_PATTERNS = [
     /^\.claude\/hooks\//,
     /^\.claude\/ukit\//,
@@ -1901,6 +2088,79 @@ const { pathToFileURL } = require('url');
     };
   }
 
+  function buildRouteAuditEntry({
+    routingContext = {},
+    routeSummary = {},
+    state = null,
+  } = {}) {
+    const candidateModes = Array.isArray(routeSummary?.approachSelector?.candidateModes)
+      ? routeSummary.approachSelector.candidateModes
+      : [];
+
+    return {
+      ts: Date.now(),
+      source: state?.source || 'skill-router',
+      requestKey: state?.requestKey || null,
+      adapter: routingContext.adapter || 'claude',
+      promptFingerprint: stableMachineDigest({
+        prompt: routingContext.lastExplicitUserPromptText || '',
+        adapter: routingContext.adapter || 'claude',
+      }),
+      targetFile: 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,
+    };
+  }
+
+  function appendRouteAuditEntry(filePath, entry) {
+    if (!entry || typeof entry !== 'object') {
+      return;
+    }
+
+    let parsed = { entries: [] };
+    if (fs.existsSync(filePath)) {
+      try {
+        parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+      } catch {
+        parsed = { entries: [] };
+      }
+    }
+
+    const entries = Array.isArray(parsed?.entries) ? parsed.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;
+    });
+
+    ensureDir(filePath);
+    fs.writeFileSync(filePath, JSON.stringify({
+      entries: [entry, ...filtered].slice(0, 40),
+    }));
+  }
+
   function shouldIncludePreviousContext({ routingContext = {}, useIndexedContext = true } = {}) {
     const taskType = String(routingContext?.taskType || '').trim();
     const hasExplicitTarget = Boolean(String(routingContext?.targetFile || '').trim());
@@ -1999,6 +2259,7 @@ const { pathToFileURL } = require('url');
   const projectRoot = process.env.PROJECT_ROOT || process.cwd();
   const statePath = process.env.STATE_FILE || path.join(projectRoot, '.claude', 'ukit', 'skill-router-state.json');
   const routeCachePath = path.join(projectRoot, '.claude', 'ukit', 'route-cache.json');
+  const routeAuditPath = path.join(projectRoot, '.ukit', 'storage', 'cache', 'route-audit.json');
   const cacheUtilsPath = path.join(projectRoot, '.claude', 'ukit', 'index', 'cache-utils.mjs');
   const previous = readJson(statePath, {});
   const runtimeConfig = loadRuntimeConfig(projectRoot);
@@ -2106,13 +2367,20 @@ const { pathToFileURL } = require('url');
     intentMode,
     taskType,
   });
+  const executionCandidates = buildExecutionModeCandidates({
+    promptText,
+    commandText,
+    targetFile: filePath,
+    intentMode,
+    executionScores,
+  });
   const executionMode = deriveExecutionMode({
     promptText,
     commandText,
     targetFile: filePath,
     intentMode,
-    taskType,
     executionScores,
+    executionCandidates,
   });
   const lastExplicitUserPromptText = promptText.trim()
     || previous?.routingContext?.lastExplicitUserPromptText
@@ -2126,6 +2394,7 @@ const { pathToFileURL } = require('url');
     taskType,
     intentMode,
     executionScores,
+    executionCandidates,
     executionMode,
   };
   const useIndexedContext = shouldUseIndexedContext({
@@ -2193,6 +2462,9 @@ const { pathToFileURL } = require('url');
           ),
         }
       : null;
+    if (rescuedRouteSummary) {
+      applyRescueBiasToRouteSummary(rescuedRouteSummary);
+    }
     const reusedState = {
       ...cachedRouteState,
       source: 'skill-router',
@@ -2208,6 +2480,9 @@ const { pathToFileURL } = require('url');
 
     ensureDir(statePath);
     fs.writeFileSync(statePath, JSON.stringify(reusedState));
+    appendRouteAuditEntry(routeAuditPath, buildRouteAuditEntry({
+      state: reusedState,
+    }));
 
     process.stdout.write(`[ukit-skill-router] Read skills: ${getActiveSkillPaths(reusedState.activeSkills || []).join(', ')}\n`);
     process.stdout.write(`[ukit-skill-router] Route: ${formatDisplayRouteSummary(reusedState.routeSummary, reusedState.routingContext)}\n`);
@@ -2263,6 +2538,7 @@ const { pathToFileURL } = require('url');
       routeSummary.continuationState,
       previous?.routeSummary?.continuationState || null,
     );
+    applyRescueBiasToRouteSummary(routeSummary);
 
   const fingerprint = buildRouteStateFingerprint({
     activeSkills: selected,
@@ -2292,6 +2568,11 @@ const { pathToFileURL } = require('url');
     routeSummary: compactRouteSummary(routeSummary),
   };
   fs.writeFileSync(statePath, JSON.stringify(sharedState));
+  appendRouteAuditEntry(routeAuditPath, buildRouteAuditEntry({
+    routingContext,
+    routeSummary,
+    state: sharedState,
+  }));
   if (typeof cacheUtils?.writeRecentCacheEntry === 'function') {
     await cacheUtils.writeRecentCacheEntry(routeCachePath, compactRouteCacheState(sharedState), {
       maxEntries: cacheUtils.DEFAULT_RECENT_CACHE_MAX_ENTRIES,

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

@@ -178,7 +178,7 @@ export const ROUTE_CATALOG = [
     order: 20,
     contextMode: 'standalone',
     signals: [
-      { type: 'prompt', regex: /\b(pdf|pdf form|fill (?:this )?pdf|merge pdf|split pdf|extract tables? from .*pdf|extract text from .*pdf)\b/i, score: 8 },
+      { type: 'prompt', regex: /\b(pdf form|fillable pdf|fill (?:this )?pdf|merge pdfs?|split pdfs?|extract tables? from .*pdf|extract text from .*pdf|read (?:this |the |a )?pdf|open (?:this |the |a )?pdf|analy(?:s|z)e (?:this |the |a )?pdf|annotate (?:this |the |a )?pdf|create pdf|convert .*pdf|pdf extraction|pdf parser|pdf parsing)\b/i, score: 8 },
       { type: 'command', regex: /\b(pdftotext|qpdf|pypdf|pdfplumber|reportlab)\b/i, score: 5 },
       { type: 'file', regex: /\.pdf$/i, score: 5 },
     ],