@ngockhoale/ukit 1.1.6 → 1.1.7

package/src/index/verificationPlan.js

@@ -23,6 +23,7 @@ export async function deriveVerificationPlan({
   targetFile = null,
   taskType = null,
   contextResult = null,
+  impactContext = null,
   skillIds = [],
 } = {}) {
   const absoluteRoot = path.resolve(rootDir);
@@ -72,7 +73,15 @@ export async function deriveVerificationPlan({
     const notes = [];
     const docsOnly = primaryTargets.length > 0
       && primaryTargets.every((filePath) => filePath.startsWith('docs/'));
+    const impactTests = unique(impactContext?.recommendedTestFiles ?? []);
+    const impactRisk = Boolean(
+      impactContext?.requiresImpactCheck
+      || (impactContext?.riskLabels ?? []).length > 0,
+    );
+    const sharedSimple = effectiveTaskType === 'shared-simple' || taskType === 'shared-simple';
     const risky = effectiveTaskType === 'non-trivial'
+      || sharedSimple
+      || impactRisk
       || skillIds.some((skillId) => RISKY_SKILL_IDS.has(skillId));
 
     let mode = 'minimal';
@@ -98,6 +107,14 @@ export async function deriveVerificationPlan({
         }
       }
 
+      if (impactTests.length > 0 && scripts.test) {
+        mode = relatedTests.length > 0 ? mode : 'impact-tests-first';
+        reasons.push('impactTests');
+        for (const testFile of impactTests.slice(0, 2)) {
+          commands.push(buildScriptCommand(packageManager, 'test', [testFile]));
+        }
+      }
+
       if (risky) {
         reasons.push('riskySkillOrTask');
         if (scripts.test) {
@@ -345,7 +362,7 @@ function deriveExecutionPolicy({
     || reasons.includes('riskySkillOrTask')
     || reasons.includes('highRiskFallback');
   const hasPrimaryCommands = commands.length > 0;
-  const hasTargetedPrimaryCommands = mode === 'targeted-tests-first' && hasPrimaryCommands;
+  const hasTargetedPrimaryCommands = (mode === 'targeted-tests-first' || mode === 'impact-tests-first') && hasPrimaryCommands;
   const sharedScope = sharedAbstractions.length > 0;
   const noRelatedTests = relatedTests.length === 0;
   const broadOnlyPrimary = hasPrimaryCommands && !hasTargetedPrimaryCommands && noRelatedTests;

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

@@ -386,7 +386,7 @@ const { pathToFileURL } = require('url');
     return '';
   }
 
-  function inferTaskType({ promptText, commandText, selectedIds, buildRouteSignalText }) {
+  function inferTaskType({ promptText, commandText, selectedIds, buildRouteSignalText, targetFile = null }) {
     const lower = buildRouteSignalText(promptText, commandText);
 
     if (

package/templates/.claude/hooks/verification-guard.sh

@@ -5,9 +5,10 @@
 INPUT=$(cat)
 PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
 STATE_FILE="$PROJECT_ROOT/.claude/ukit/skill-router-state.json"
+ROUTE_CACHE_FILE="$PROJECT_ROOT/.claude/ukit/route-cache.json"
 PROGRESS_FILE="$PROJECT_ROOT/.claude/ukit/verification-progress.json"
 
-INPUT="$INPUT" STATE_FILE="$STATE_FILE" PROGRESS_FILE="$PROGRESS_FILE" node <<'NODE'
+INPUT="$INPUT" STATE_FILE="$STATE_FILE" ROUTE_CACHE_FILE="$ROUTE_CACHE_FILE" PROGRESS_FILE="$PROGRESS_FILE" node <<'NODE'
 const fs = require('fs');
 const path = require('path');
 
@@ -125,12 +126,122 @@ function isExplicitBroadVerificationRequest(promptText) {
     /chạy full test suite/,
     /verify toàn bộ/,
     /kiểm tra toàn bộ/,
+    // Plan-driven execution prompts often authorize the plan's final broad
+    // verification without spelling it as "full test suite".
+    /(?:run|execute|implement|do)\b.*\bfull\b.*\b(?:prd\s+)?plan\b/,
+    /\bfull\b.*\b(?:prd\s+)?plan\b.*\b(?:verify|verification|test|tests)\b/,
+    /(?:chạy|lam|làm|thực hiện|triển khai)\b.*\bfull\b.*\b(?:prd|plan|ke hoach|kế hoạch)\b/,
+    /\bfull\b.*\b(?:prd|plan|ke hoach|kế hoạch)\b.*\b(?:verify|verification|test|tests|kiểm tra)\b/,
   ].some((pattern) => pattern.test(text));
 }
 
+function collectRecentPromptTexts(state, routeCache, maxAgeMs) {
+  const prompts = [
+    state?.routingContext?.lastExplicitUserPromptText,
+    state?.routingContext?.promptText,
+  ];
+  const now = Date.now();
+
+  for (const entry of routeCache?.entries ?? []) {
+    const updatedAt = Number(entry?.updatedAt ?? entry?.ts ?? 0);
+    if (Number.isFinite(updatedAt) && updatedAt > 0 && now - updatedAt > maxAgeMs) {
+      continue;
+    }
+    prompts.push(
+      entry?.routingContext?.lastExplicitUserPromptText,
+      entry?.routingContext?.promptText,
+    );
+  }
+
+  return unique(prompts.map((prompt) => String(prompt || '').trim()).filter(Boolean));
+}
+
+function hasRecentExplicitBroadVerificationRequest(state, routeCache, maxAgeMs) {
+  return collectRecentPromptTexts(state, routeCache, maxAgeMs)
+    .some((promptText) => isExplicitBroadVerificationRequest(promptText));
+}
+
+function collectRecentRouteSummaries(routeCache, maxAgeMs) {
+  const now = Date.now();
+  const summaries = [];
+
+  for (const entry of routeCache?.entries ?? []) {
+    const updatedAt = Number(entry?.updatedAt ?? entry?.ts ?? 0);
+    if (Number.isFinite(updatedAt) && updatedAt > 0 && now - updatedAt > maxAgeMs) {
+      continue;
+    }
+    if (entry?.routeSummary && typeof entry.routeSummary === 'object') {
+      summaries.push(entry.routeSummary);
+    }
+  }
+
+  return summaries;
+}
+
+function collectAttemptedCommands(progress, {
+  currentFingerprint = null,
+  maxAgeMs,
+} = {}) {
+  const now = Date.now();
+  const attempted = [];
+  const progressUpdatedAt = Number(progress?.updatedAt ?? 0);
+  const legacyProgressIsFresh = Number.isFinite(progressUpdatedAt)
+    && progressUpdatedAt > 0
+    && now - progressUpdatedAt <= maxAgeMs;
+
+  if (progress?.fingerprint === currentFingerprint || legacyProgressIsFresh) {
+    attempted.push(...(progress?.attemptedCommands ?? []));
+  }
+
+  for (const entry of progress?.recentAttempts ?? []) {
+    const ts = Number(entry?.ts ?? 0);
+    if (Number.isFinite(ts) && ts > 0 && now - ts <= maxAgeMs) {
+      attempted.push(entry.command);
+    }
+  }
+
+  return new Set(attempted.map(normalizeCommand).filter(Boolean));
+}
+
+function hasCompletedRecentTargetedLane({
+  routeCache,
+  attemptedCommands,
+  command,
+  maxAgeMs,
+} = {}) {
+  const normalizedCommand = normalizeCommand(command);
+  if (!isBroadTestCommand(normalizedCommand)) {
+    return false;
+  }
+
+  return collectRecentRouteSummaries(routeCache, maxAgeMs).some((summary) => {
+    const mode = summary?.policyMode;
+    if (mode !== 'auto-run-targeted' && mode !== 'auto-run-targeted-then-fallback') {
+      return false;
+    }
+
+    const recentPrimary = unique((summary?.primaryCommands ?? []).map(normalizeCommand));
+    if (recentPrimary.length === 0 || !recentPrimary.every((item) => attemptedCommands.has(item))) {
+      return false;
+    }
+
+    const recentFallbacks = unique((summary?.fallbackCommands ?? []).map(normalizeCommand));
+    const recentPreferred = unique((summary?.preferredOrder ?? []).map(normalizeCommand));
+    return recentFallbacks.includes(normalizedCommand)
+      || recentPreferred.includes(normalizedCommand)
+      || recentPrimary.includes(normalizedCommand);
+  });
+}
+
 function deny(message) {
-  process.stderr.write(`${message}\n`);
-  process.exit(2);
+  const advisory = message.replace(/^BLOCKED:/, 'ADVISORY:');
+  if (process.env.UKIT_VERIFICATION_GUARD_ENFORCE === '1') {
+    fs.writeSync(2, `${message}\n`);
+    process.exit(2);
+  }
+
+  fs.writeSync(1, `${advisory}\n`);
+  process.exit(0);
 }
 
 const payload = (() => {
@@ -148,6 +259,7 @@ if (!command) {
 const statePath = process.env.STATE_FILE;
 const progressPath = process.env.PROGRESS_FILE;
 const state = readJson(statePath, null);
+const routeCache = readJson(process.env.ROUTE_CACHE_FILE, null);
 const recommendation = state?.verificationRecommendation ?? null;
 const routeSummary = state?.routeSummary ?? null;
 const helpers = state?.helpers ?? null;
@@ -195,24 +307,39 @@ if (!policyMode && primaryCommands.length === 0 && fallbackCommands.length === 0
 }
 
 const progress = readJson(progressPath, {});
-const normalizedProgress = progress?.fingerprint === state?.fingerprint
-  ? progress
-  : { fingerprint: state?.fingerprint || null, attemptedCommands: [] };
-const attemptedCommands = new Set((normalizedProgress.attemptedCommands ?? []).map(normalizeCommand));
+const attemptedCommands = collectAttemptedCommands(progress, {
+  currentFingerprint: state?.fingerprint || null,
+  maxAgeMs: STATE_FRESH_MS,
+});
 
 function persistAttempt(commandText) {
-  attemptedCommands.add(commandText);
+  const normalizedCommandText = normalizeCommand(commandText);
+  attemptedCommands.add(normalizedCommandText);
+  const now = Date.now();
+  const recentAttempts = [
+    ...(progress?.recentAttempts ?? []),
+    { command: normalizedCommandText, ts: now },
+  ]
+    .map((entry) => ({
+      command: normalizeCommand(entry?.command),
+      ts: Number(entry?.ts ?? now),
+    }))
+    .filter((entry) => entry.command && Number.isFinite(entry.ts) && now - entry.ts <= STATE_FRESH_MS)
+    .filter((entry, index, list) => (
+      list.findLastIndex((candidate) => candidate.command === entry.command) === index
+    ));
   writeJson(progressPath, {
     fingerprint: state?.fingerprint || null,
+    updatedAt: now,
     attemptedCommands: [...attemptedCommands],
+    recentAttempts,
   });
 }
 
 const isPrimaryCommand = primaryCommands.includes(command);
-const explicitBroadRequested = isExplicitBroadVerificationRequest(
-  state?.routingContext?.lastExplicitUserPromptText || state?.routingContext?.promptText || '',
-);
+const explicitBroadRequested = hasRecentExplicitBroadVerificationRequest(state, routeCache, STATE_FRESH_MS);
 const isFallbackCommand = fallbackCommands.includes(command);
+const isTargetedVerification = looksTargetedTestCommand(command);
 if (!isPrimaryCommand && !isFallbackCommand && !isVerificationCommand(command)) {
   process.exit(0);
 }
@@ -223,10 +350,21 @@ const helperSource = routeSummary?.helperHint
   || '';
 const helperCommand = helperSource ? ` Helper: ${helperSource}` : '';
 const missingPrimary = primaryCommands.filter((item) => !attemptedCommands.has(item));
+const recentTargetedLaneCompleted = hasCompletedRecentTargetedLane({
+  routeCache,
+  attemptedCommands,
+  command,
+  maxAgeMs: STATE_FRESH_MS,
+});
 const preferredText = formatCompactCommandList(preferredOrder, { separator: ' -> ' });
 const missingPrimaryText = formatCompactCommandList(missingPrimary);
 
-if (policyMode === 'confirm-then-broad' && !explicitBroadRequested) {
+if (isTargetedVerification) {
+  persistAttempt(command);
+  process.exit(0);
+}
+
+if (policyMode === 'confirm-then-broad' && isBroadTestCommand(command) && !explicitBroadRequested && !recentTargetedLaneCompleted) {
   deny(
     `BLOCKED: Ask the user before broad verification. Routed policy is confirm-then-broad because the index could not localize related tests confidently.${helperCommand}`,
   );

package/templates/.claude/ukit/index/impact-context.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import * as indexCore from './lib/index-core.mjs';
+
+const {
+  buildCodeIndex,
+  DEFAULT_INDEX_CACHE_MAX_AGE_MS,
+  getIndexArtifactGeneratedAt,
+  isIndexStale,
+} = indexCore;
+
+const resolveImpactContext = typeof indexCore.resolveImpactContext === 'function'
+  ? indexCore.resolveImpactContext
+  : null;
+const formatImpactConfidenceSummary = typeof indexCore.formatImpactConfidenceSummary === 'function'
+  ? indexCore.formatImpactConfidenceSummary
+  : null;
+
+const CALLEE_CAP = 5;
+const CALLER_CAP = 5;
+const MIRROR_CAP = 3;
+const TEST_CAP = 4;
+const VERIFY_CAP = 3;
+
+async function main() {
+  const args = process.argv.slice(2);
+  const rootDir = getRootDir(args);
+  const changedFiles = parseCsv(readFlagValue(args, '--changed'));
+  const changedSymbols = parseCsv(readFlagValue(args, '--symbol'));
+
+  if (changedFiles.length === 0) {
+    console.error('Usage: node .claude/ukit/index/impact-context.mjs --changed <file[,file]> [--symbol <name[,name]>] [--root <dir>]');
+    process.exitCode = 1;
+    return;
+  }
+
+  await ensureFreshIndex(rootDir);
+
+  const impact = resolveImpactContext
+    ? await resolveImpactContext({ rootDir, changedFiles, changedSymbols })
+    : {
+        changedFiles,
+        changedSymbols,
+        riskLabels: [],
+        callees: [],
+        callers: [],
+        importers: [],
+        mirrorCounterparts: [],
+        relatedTests: [],
+        recommendedTestFiles: [],
+      };
+
+  printCompact(impact);
+
+  if (formatImpactConfidenceSummary) {
+    console.log('');
+    console.log(formatImpactConfidenceSummary(impact));
+  }
+}
+
+async function ensureFreshIndex(rootDir) {
+  const generatedAtMs = await getIndexArtifactGeneratedAt({ rootDir });
+  const stale = generatedAtMs === null
+    ? true
+    : await isIndexStale({
+        rootDir,
+        maxAgeMs: DEFAULT_INDEX_CACHE_MAX_AGE_MS,
+        now: Date.now(),
+        generatedAtMs,
+      });
+
+  if (stale) {
+    await buildCodeIndex({ rootDir });
+  }
+}
+
+function printCompact(impact) {
+  const changed = (impact.changedFiles ?? []).slice(0, 5).join(', ');
+  const symbols = (impact.changedSymbols ?? []).slice(0, 5).join(', ');
+  const risk = (impact.riskLabels ?? []).slice(0, 5).join(', ');
+  const callees = unique((impact.callees ?? []).map((entry) => entry?.symbol).filter(Boolean)).slice(0, CALLEE_CAP).join(', ');
+  const callers = unique((impact.callers ?? []).map((entry) => entry?.filePath).filter(Boolean)).slice(0, CALLER_CAP).join(', ');
+  const mirrors = unique((impact.mirrorCounterparts ?? []).map((entry) => entry?.filePath).filter(Boolean)).slice(0, MIRROR_CAP).join(', ');
+  const tests = (impact.recommendedTestFiles ?? impact.relatedTests ?? []).slice(0, TEST_CAP);
+  const verify = tests.slice(0, VERIFY_CAP).map((testFile) => `yarn test ${testFile}`).join(' | ');
+
+  console.log('[ukit:impact]');
+  console.log(`changed: ${changed || '(none)'}`);
+  if (symbols) console.log(`symbols: ${symbols}`);
+  if (risk) console.log(`risk: ${risk}`);
+  if (callees) console.log(`callees: ${callees}`);
+  if (callers) console.log(`callers: ${callers}`);
+  if (mirrors) console.log(`mirrors: ${mirrors}`);
+  if (tests.length > 0) console.log(`related-tests: ${tests.join(', ')}`);
+  if (verify) console.log(`verify: ${verify}`);
+}
+
+function parseCsv(value) {
+  return unique(
+    String(value ?? '')
+      .split(',')
+      .map((entry) => entry.trim().replace(/^\.\//, ''))
+      .filter(Boolean),
+  );
+}
+
+function unique(values = []) {
+  return [...new Set(values)];
+}
+
+function readFlagValue(args, flag) {
+  const index = args.indexOf(flag);
+  if (index === -1) return null;
+  return args[index + 1] ?? null;
+}
+
+function getRootDir(args) {
+  const explicitRoot = readFlagValue(args, '--root');
+  return path.resolve(explicitRoot || process.cwd());
+}
+
+await main();