@ngockhoale/ukit 1.4.1 → 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');
@@ -138,13 +139,30 @@ async function main() {
     requestKey,
   });
   if (cachedRouteState) {
+    const rescuedRouteSummary = cachedRouteState.routeSummary
+      ? {
+          ...cachedRouteState.routeSummary,
+          continuationState: advanceContinuationState(
+            cachedRouteState.routeSummary.continuationState ?? null,
+            cachedRouteState.routeSummary.continuationState ?? null,
+          ),
+        }
+      : null;
+    if (rescuedRouteSummary) {
+      applyRescueBiasToRouteSummary(rescuedRouteSummary);
+    }
     const sharedState = {
       ...cachedRouteState,
       source: 'task-route',
       ts: Date.now(),
       requestKey,
+      routeSummary: rescuedRouteSummary,
     };
+    sharedState.fingerprint = buildRouteStateFingerprint(sharedState);
     await writeJson(sharedStatePath, sharedState);
+    await appendRouteAuditEntry(routeAuditPath, buildRouteAuditEntry({
+      state: sharedState,
+    }));
     printRouteState(sharedState);
     return;
   }
@@ -166,6 +184,7 @@ async function main() {
     useIndexedContext,
     previousContextSnapshot,
     recentOutputSnapshot,
+    previousRouteSummary: previousState?.routeSummary ?? null,
   });
   await seedHelperCaches({
     rootDir,
@@ -182,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,
   });
@@ -255,6 +278,28 @@ async function prepareTaskRoute({
     selectedIds,
     targetFile: normalizedTarget,
   });
+  const executionScores = deriveExecutionScores({
+    promptText: normalizedPrompt,
+    commandText: normalizedCommand,
+    targetFile: normalizedTarget,
+    intentMode,
+    taskType: inferredTaskType,
+  });
+  const executionCandidates = buildExecutionModeCandidates({
+    promptText: normalizedPrompt,
+    commandText: normalizedCommand,
+    targetFile: normalizedTarget,
+    intentMode,
+    executionScores,
+  });
+  const executionMode = deriveExecutionMode({
+    promptText: normalizedPrompt,
+    commandText: normalizedCommand,
+    targetFile: normalizedTarget,
+    intentMode,
+    executionScores,
+    executionCandidates,
+  });
   const preservedPrompt = normalizedPrompt || String(lastExplicitUserPromptText || '').trim();
 
   return {
@@ -269,6 +314,9 @@ async function prepareTaskRoute({
       contextIntent,
       taskType: inferredTaskType,
       intentMode,
+      executionScores,
+      executionCandidates,
+      executionMode,
     },
   };
 }
@@ -283,6 +331,7 @@ async function finalizeTaskRoute({
   useIndexedContext = true,
   previousContextSnapshot = null,
   recentOutputSnapshot = null,
+  previousRouteSummary = null,
 } = {}) {
   const absoluteRoot = path.resolve(rootDir);
   const activeSkills = preparedRoute?.activeSkills ?? [];
@@ -347,10 +396,17 @@ async function finalizeTaskRoute({
     verificationRecommendation,
     nextAction,
   });
+  routeSummary.continuationState = advanceContinuationState(
+    routeSummary.continuationState,
+    previousRouteSummary?.continuationState ?? null,
+  );
+  applyRescueBiasToRouteSummary(routeSummary);
+  const approachSelector = routeSummary?.approachSelector ?? null;
 
   return {
     activeSkills,
     routingContext,
+    approachSelector,
     previousContext: previousContextSnapshot,
     recentOutput: recentOutputSnapshot,
     contextRecommendation,
@@ -445,7 +501,11 @@ function formatDisplayNextAction(routeSummary = null) {
   }
 
   const nextActionType = String(routeSummary.nextActionType ?? '').trim();
-  if (!nextActionType || nextActionType === 'read-skill-instructions') {
+  if (
+    !nextActionType
+    || nextActionType === 'read-skill-instructions'
+    || nextActionType === 'pull-indexed-context'
+  ) {
     return '';
   }
 
@@ -492,6 +552,10 @@ function formatDisplayHelperHint(routeSummary = null, compactSummary = '') {
     return '';
   }
 
+  if (String(routeSummary.nextActionType ?? '').trim() === 'pull-indexed-context') {
+    return '';
+  }
+
   let helperHint = String(routeSummary.helperHint ?? '').trim().replace(/\s+/g, ' ');
   if (!helperHint) {
     return '';
@@ -671,6 +735,10 @@ function shouldKeepRouteEntryForIntent(entry, intentMode) {
     return false;
   }
 
+  if (entry.id === 'code-review' && intentMode === 'implement-specific') {
+    return false;
+  }
+
   return true;
 }
 
@@ -710,6 +778,10 @@ function deriveSkillPriorityBoost(skillId, routeSignals = {}) {
     routeSignals.commandRawText ?? '',
     routeSignals.commandNormalizedText ?? '',
   ].join('\n');
+  const rawPromptSignals = [
+    routeSignals.promptRawText ?? '',
+    routeSignals.commandRawText ?? '',
+  ].join('\n');
 
   if (
     skillId === 'testing-quality'
@@ -718,6 +790,14 @@ function deriveSkillPriorityBoost(skillId, routeSignals = {}) {
     return 1;
   }
 
+  if (
+    skillId === 'code-review'
+    && /\b(implement|build|create|add|ship|deliver|refactor|integrate|integration|scaffold|feature|update|change|modify|inject|apply)\b/.test(rawPromptSignals)
+    && !/\b(review|audit|diff|pr feedback|code review|kiem tra|soat)\b/.test(rawPromptSignals)
+  ) {
+    return -4;
+  }
+
   return 0;
 }
 
@@ -768,13 +848,13 @@ 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(lower)) {
+    if (/\b(review|audit|diff|pr feedback|code review|kiem tra|soat)\b/.test(raw)) {
       return 'review-specific';
     }
-    if (/\b(implement|build|create|add|ship|deliver|refactor|integrate|integration|scaffold|feature)\b/.test(lower)) {
+    if (/\b(implement|build|create|add|ship|deliver|refactor|integrate|integration|scaffold|feature|update|change|modify|inject|apply)\b/.test(raw)) {
       return 'implement-specific';
     }
   }
@@ -806,7 +886,7 @@ function hasConcreteTaskSignal(lower, raw, targetFile, { taskQueueNext = false }
     return true;
   }
 
-  return /\b(bug|debug|error|crash|broken|failing|stack trace|triage|fix|implement|build|create|add|ship|deliver|refactor|integrate|integration|scaffold|feature|review|audit|diff|pr feedback|code review|auth|login|api|endpoint|test|spec)\b/.test(lower)
+  return /\b(bug|debug|error|crash|broken|failing|stack trace|triage|fix|implement|build|create|add|ship|deliver|refactor|integrate|integration|scaffold|feature|update|change|modify|inject|apply|review|audit|diff|pr feedback|code review|auth|login|api|endpoint|test|spec)\b/.test(lower)
     || /\b(sửa|fix|lỗi|bug|debug|implement|cài|thêm|review|kiểm tra|soát|đăng nhập)\b/.test(raw);
 }
 
@@ -1225,6 +1305,23 @@ function buildRouteSummary({
   const compactHelperLane = nextAction?.type === 'pull-indexed-context'
     && typeof contextRecommendation?.command === 'string'
     && 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({
+    executionMode,
+    verificationRecommendation,
+  });
+  const continuationState = buildContinuationState({
+    nextActionType: nextAction?.type ?? null,
+    completionState,
+  });
   const helperHint = compactHelperHint(
     compactHelperLane
       ? contextRecommendation?.command
@@ -1243,7 +1340,6 @@ function buildRouteSummary({
     editGuardHint ? `editGuard=${editGuardHint}` : null,
     delegationRecommendation?.hint ? `delegate=${delegationRecommendation.hint}` : null,
     policyMode ? `policy=${policyMode}` : null,
-    contextMode ? `mode=${contextMode}` : null,
   ].filter(Boolean).join(' | ');
 
   return {
@@ -1252,6 +1348,13 @@ function buildRouteSummary({
     preferredOrder,
     policyMode,
     editGuardHint,
+    executionMode,
+    executionScores,
+    executionCandidates,
+    approachSelector,
+    executionContract,
+    completionState,
+    continuationState,
     intentMode: routingContext.intentMode ?? null,
     delegateHint: delegationRecommendation?.hint ?? null,
     nextActionType: nextAction?.type ?? null,
@@ -1268,6 +1371,559 @@ function deriveContextMode(taskType) {
   return null;
 }
 
+function deriveExecutionScores({
+  promptText = '',
+  commandText = '',
+  targetFile = null,
+  intentMode = null,
+  taskType = null,
+} = {}) {
+  const raw = `${promptText ?? ''}\n${commandText ?? ''}`.toLowerCase();
+  const sharedRisk = isSharedImpactFile(targetFile);
+  const directTransformSignal = /\b(change|replace|set|rename|convert|swap)\b/.test(raw) || /\bchange\s+.+\s+to\s+.+\b/.test(raw);
+  const smallFixSignal = /\b(adjust|tweak|patch|fix|modify|update|apply)\b/.test(raw);
+  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) {
+    editCertainty = 3;
+  } else if (smallFixSignal) {
+    editCertainty = 2;
+  } else if (buildSignal) {
+    editCertainty = 1;
+  }
+
+  let investigationNeed = 0;
+  if (debugSignal) {
+    investigationNeed = 3;
+  } else if (failureSignal) {
+    investigationNeed = 2;
+  }
+
+  let blastRadius = 0;
+  if (sharedRisk) {
+    blastRadius = 3;
+  } else if (taskType === 'non-trivial' || taskType === 'shared-simple') {
+    blastRadius = 2;
+  } else if (!targetFile) {
+    blastRadius = 1;
+  }
+
+  let verificationBurden = 1;
+  if (reviewSignal || sharedRisk) {
+    verificationBurden = 3;
+  } else if (debugSignal || taskType === 'non-trivial') {
+    verificationBurden = 2;
+  }
+
+  let ambiguity = 0;
+  if (!targetFile) {
+    ambiguity = 2;
+  } else if (buildSignal && !directTransformSignal && !smallFixSignal) {
+    ambiguity = 1;
+  }
+
+  return {
+    editCertainty,
+    investigationNeed,
+    blastRadius,
+    verificationBurden,
+    ambiguity,
+    sharedRisk,
+    directTransformSignal,
+    smallFixSignal,
+    buildSignal,
+    debugSignal,
+    reviewSignal,
+    failureSignal,
+    impactSignal,
+    boundedEditSignal,
+    implementSignal,
+    explicitTarget,
+  };
+}
+
+function deriveExecutionMode({
+  promptText = '',
+  commandText = '',
+  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) && !scores.implementSignal) {
+    return 'review-release';
+  }
+
+  if (strongImpactLead || (scores.blastRadius >= 3 && (scores.ambiguity >= 2 || scores.investigationNeed >= 2))) {
+    return 'map-impact';
+  }
+
+  if (scores.sharedRisk && scores.failureSignal && scores.investigationNeed >= 2 && !scores.impactSignal) {
+    return 'shared-edit';
+  }
+
+  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 <= 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';
+  }
+
+  if (scores.editCertainty >= 2 && scores.investigationNeed === 0 && scores.blastRadius === 0) {
+    return 'local-fix';
+  }
+
+  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) {
+  if (!executionMode) {
+    return null;
+  }
+
+  const contracts = {
+    'tiny-fix': {
+      maxReadPasses: 0,
+      maxContextPulls: 0,
+      verificationPolicy: 'minimal-or-targeted',
+      completionRule: 'never-claim-done-without-write',
+      delegationPolicy: 'disallow',
+      completionEvidence: ['write-evidence'],
+    },
+    'local-fix': {
+      maxReadPasses: 1,
+      maxContextPulls: 1,
+      verificationPolicy: 'targeted-if-covered',
+      completionRule: 'require-write',
+      delegationPolicy: 'disallow',
+      completionEvidence: ['write-evidence'],
+    },
+    'local-build': {
+      maxReadPasses: 2,
+      maxContextPulls: 1,
+      verificationPolicy: 'targeted-if-covered',
+      completionRule: 'require-write',
+      delegationPolicy: 'disallow-by-default',
+      completionEvidence: ['write-evidence'],
+    },
+    'find-cause': {
+      maxReadPassesBeforeReassess: 3,
+      verificationPolicy: 'root-cause-then-targeted',
+      completionRule: 'never-claim-fixed-without-write-and-verification',
+      delegationPolicy: 'allow-specialized-debug-lane',
+      completionEvidence: ['write-evidence', 'verification-evidence'],
+    },
+    'shared-edit': {
+      maxReadPasses: 2,
+      maxContextPulls: 2,
+      verificationPolicy: 'targeted-then-widen-on-risk',
+      completionRule: 'require-write-and-verification',
+      delegationPolicy: 'allow-qualified-sidecar',
+      completionEvidence: ['write-evidence', 'verification-evidence'],
+      mirrorConsistencyRequired: true,
+    },
+    'map-impact': {
+      maxReadPasses: 3,
+      maxContextPulls: 3,
+      verificationPolicy: 'impact-first-then-targeted-then-widen-on-risk',
+      completionRule: 'require-impact-evidence-before-edit-claim',
+      delegationPolicy: 'allow-impact-sidecar',
+      completionEvidence: ['impact-evidence', 'write-evidence', 'verification-evidence'],
+      mirrorConsistencyRequired: true,
+    },
+    'review-release': {
+      verificationPolicy: 'evidence-first',
+      completionRule: 'report-findings-not-implementation',
+      delegationPolicy: 'allow-review-sidecar',
+      completionEvidence: ['verification-evidence'],
+    },
+  };
+
+  return contracts[executionMode] ? { ...contracts[executionMode] } : null;
+}
+
+function buildApproachSelectorResult({
+  executionMode = null,
+  executionScores = null,
+  executionCandidates = null,
+} = {}) {
+  if (!executionMode) {
+    return null;
+  }
+
+  const executionContract = buildExecutionContract(executionMode);
+  const policyByMode = {
+    'tiny-fix': {
+      riskLevel: 'minimal',
+      contextPolicy: 'confirm-target-only',
+    },
+    'local-fix': {
+      riskLevel: 'local',
+      contextPolicy: 'bounded-local',
+    },
+    'local-build': {
+      riskLevel: 'local',
+      contextPolicy: 'bounded-with-related-files',
+    },
+    'find-cause': {
+      riskLevel: 'investigation',
+      contextPolicy: 'trace-then-bounded-context',
+    },
+    'shared-edit': {
+      riskLevel: 'shared',
+      contextPolicy: 'bounded-with-related-tests',
+    },
+    'map-impact': {
+      riskLevel: 'wide',
+      contextPolicy: 'impact-map-first',
+    },
+    'review-release': {
+      riskLevel: 'release',
+      contextPolicy: 'evidence-review-only',
+    },
+  };
+  const selectedPolicy = policyByMode[executionMode] ?? {
+    riskLevel: 'local',
+    contextPolicy: 'bounded-local',
+  };
+
+  return {
+    executionMode,
+    executionScores: executionScores ? { ...executionScores } : null,
+    riskLevel: selectedPolicy.riskLevel,
+    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,
+    })),
+  };
+}
+
+function buildCompletionState({ executionMode = null, verificationRecommendation = null } = {}) {
+  if (!executionMode) {
+    return null;
+  }
+
+  const contract = buildExecutionContract(executionMode);
+  const missingEvidence = [...(contract?.completionEvidence ?? [])];
+  const requiresVerification = missingEvidence.includes('verification-evidence');
+  if (
+    requiresVerification
+    && verificationRecommendation
+    && !(verificationRecommendation.commands?.length || verificationRecommendation.fallbackCommands?.length)
+  ) {
+    missingEvidence.push('verification-plan');
+  }
+
+  let reason = 'completion evidence is still required';
+  if (['tiny-fix', 'local-fix', 'local-build', 'shared-edit'].includes(executionMode)) {
+    reason = 'implement request has not produced an edit yet';
+  } else if (executionMode === 'review-release') {
+    reason = 'review/release evidence is still required before final claim';
+  } else if (executionMode === 'map-impact') {
+    reason = 'impact evidence is still required before safe completion claim';
+  }
+
+  return {
+    claimAllowed: false,
+    missingEvidence,
+    reason,
+  };
+}
+
+function buildContinuationState({
+  nextActionType = null,
+  completionState = null,
+} = {}) {
+  const reasons = [];
+  const missingEvidence = unique(completionState?.missingEvidence ?? []);
+
+  if (nextActionType === 'pull-indexed-context') {
+    reasons.push('pending-bounded-context');
+  }
+
+  if (nextActionType === 'read-skill-instructions') {
+    reasons.push('pending-skill-read');
+  }
+
+  if (missingEvidence.includes('write-evidence')) {
+    reasons.push('missing-write-evidence');
+  }
+
+  if (missingEvidence.includes('verification-evidence') || missingEvidence.includes('verification-plan')) {
+    reasons.push('missing-verification-evidence');
+  }
+
+  if (missingEvidence.includes('impact-evidence')) {
+    reasons.push('missing-impact-evidence');
+  }
+
+  const nextMilestone = reasons.includes('pending-bounded-context')
+    ? 'complete-bounded-context-then-continue'
+    : (
+      reasons.includes('missing-write-evidence')
+        ? 'produce-write-evidence'
+        : (
+          reasons.includes('missing-verification-evidence')
+            ? 'produce-verification-evidence'
+            : (
+              reasons.includes('missing-impact-evidence')
+                ? 'produce-impact-evidence'
+                : null
+            )
+        )
+    );
+
+  return {
+    required: reasons.length > 0,
+    reasons,
+    doneLanguageBlocked: reasons.length > 0,
+    stopAllowedOnlyFor: reasons.length > 0 ? ['real-blocker'] : [],
+    nextMilestone,
+    repeatCount: reasons.length > 0 ? 1 : 0,
+    stuckRisk: null,
+    rescueMode: null,
+    wideningBlocked: false,
+    milestonePriority: reasons.length > 0 ? 'normal' : null,
+  };
+}
+
+function advanceContinuationState(continuationState = null, previousContinuationState = null) {
+  if (!continuationState || typeof continuationState !== 'object') {
+    return continuationState;
+  }
+
+  if (!continuationState.required) {
+    return {
+      ...continuationState,
+      repeatCount: 0,
+      stuckRisk: null,
+      rescueMode: null,
+      wideningBlocked: false,
+      milestonePriority: null,
+    };
+  }
+
+  const currentReasons = unique(continuationState.reasons ?? []);
+  const previousReasons = unique(previousContinuationState?.reasons ?? []);
+  const sameMilestone = Boolean(
+    previousContinuationState?.required
+    && continuationState.nextMilestone
+    && previousContinuationState.nextMilestone === continuationState.nextMilestone
+    && JSON.stringify(previousReasons) === JSON.stringify(currentReasons)
+  );
+  const repeatCount = sameMilestone
+    ? Math.max(1, Number(previousContinuationState?.repeatCount ?? 1) + 1)
+    : 1;
+  const rescueMode = repeatCount >= 2
+    ? (
+      currentReasons.includes('pending-bounded-context')
+        ? 'finish-current-milestone-before-more-reading'
+        : (
+          currentReasons.includes('missing-write-evidence')
+            ? 'finish-write-before-more-analysis'
+            : 'finish-required-milestone-before-widening'
+        )
+    )
+    : null;
+  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',
@@ -1687,6 +2343,7 @@ function buildRouteRequestKey({
     targetFile: routingContext.targetFile ?? '',
     contextIntent: routingContext.contextIntent ?? '',
     taskType: routingContext.taskType ?? '',
+    executionMode: routingContext.executionMode ?? '',
   });
 }
 
@@ -1704,10 +2361,23 @@ function buildStructuredRouteFingerprintPayload(route = {}) {
     previousContextIds: unique(route.previousContext?.selectedIds ?? []),
     recentOutputLine: route.recentOutput?.line ?? null,
     policyMode: routeSummary?.policyMode ?? null,
+    executionMode: routeSummary?.executionMode ?? null,
+    approachRiskLevel: routeSummary?.approachSelector?.riskLevel ?? null,
+    approachContextPolicy: routeSummary?.approachSelector?.contextPolicy ?? null,
+    approachVerificationPolicy: routeSummary?.approachSelector?.verificationPolicy ?? null,
+    approachCompletionRule: routeSummary?.approachSelector?.completionRule ?? null,
+    continuationRequired: routeSummary?.continuationState?.required ?? null,
+    continuationReasons: unique(routeSummary?.continuationState?.reasons ?? []),
+    continuationMilestone: routeSummary?.continuationState?.nextMilestone ?? null,
+    continuationRepeatCount: routeSummary?.continuationState?.repeatCount ?? null,
+    continuationStuckRisk: routeSummary?.continuationState?.stuckRisk ?? null,
+    continuationRescueMode: routeSummary?.continuationState?.rescueMode ?? null,
     delegateHint: routeSummary?.delegateHint ?? null,
     nextActionType: routeSummary?.nextActionType ?? null,
     nextActionCommand: routeSummary?.nextActionCommand ?? null,
     helperHint: routeSummary?.helperHint ?? null,
+    completionRule: routeSummary?.executionContract?.completionRule ?? null,
+    completionMissingEvidence: unique(routeSummary?.completionState?.missingEvidence ?? []),
     primaryCommands: unique(routeSummary?.primaryCommands ?? []),
     fallbackCommands: unique(routeSummary?.fallbackCommands ?? []),
     preferredOrder: unique(routeSummary?.preferredOrder ?? []),
@@ -1784,6 +2454,7 @@ function compactRoutingContext(routingContext = {}) {
     lastExplicitUserPromptText: routingContext.lastExplicitUserPromptText ?? '',
     taskType: routingContext.taskType ?? null,
     intentMode: routingContext.intentMode ?? null,
+    executionMode: routingContext.executionMode ?? null,
   };
 }
 
@@ -1846,6 +2517,12 @@ function compactRouteSummary(routeSummary = null) {
     fallbackCommands: unique(routeSummary.fallbackCommands ?? []).slice(0, 3),
     preferredOrder: unique(routeSummary.preferredOrder ?? []).slice(0, 5),
     policyMode: routeSummary.policyMode ?? null,
+    executionMode: routeSummary.executionMode ?? null,
+    executionScores: routeSummary.executionScores ?? null,
+    approachSelector: routeSummary.approachSelector ?? null,
+    executionContract: routeSummary.executionContract ?? null,
+    completionState: routeSummary.completionState ?? null,
+    continuationState: routeSummary.continuationState ?? null,
     delegateHint: routeSummary.delegateHint ?? null,
     nextActionType: routeSummary.nextActionType ?? null,
     nextActionCommand: routeSummary.nextActionCommand ?? null,
@@ -1898,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'));