@ngockhoale/ukit 1.1.6

package/src/index/taskRouting.js

@@ -0,0 +1,677 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { ROUTE_CATALOG } from './routeCatalog.js';
+import { buildRouteSignalText } from './languageTools.js';
+import { resolveContext } from './resolveContext.js';
+import { deriveVerificationPlan } from './verificationPlan.js';
+
+const MAX_ACTIVE_ROUTE_SKILLS = 2;
+
+export async function deriveTaskRoute({
+  rootDir = process.cwd(),
+  promptText = '',
+  commandText = '',
+  targetFile = null,
+  taskType = null,
+  lastExplicitUserPromptText = '',
+  commandNamespace = '.claude',
+} = {}) {
+  const absoluteRoot = path.resolve(rootDir);
+  const normalizedPrompt = String(promptText || '').trim();
+  const normalizedCommand = String(commandText || '').trim();
+  const normalizedTarget = normalizeRelativeFile(absoluteRoot, targetFile);
+  const activeSkills = await selectActiveSkills({
+    rootDir: absoluteRoot,
+    promptText: normalizedPrompt,
+    commandText: normalizedCommand,
+    targetFile: normalizedTarget,
+  });
+  const useIndexedContext = shouldUseIndexedContext({
+    activeSkills,
+    targetFile: normalizedTarget,
+  });
+  const selectedIds = activeSkills.map((entry) => entry.id);
+  const contextIntent = deriveContextIntent({
+    promptText: normalizedPrompt,
+    commandText: normalizedCommand,
+    targetFile: normalizedTarget,
+    selectedIds,
+  });
+  const inferredTaskType = taskType ?? inferTaskType({
+    promptText: normalizedPrompt,
+    commandText: normalizedCommand,
+    selectedIds,
+  });
+  const preservedPrompt = normalizedPrompt || String(lastExplicitUserPromptText || '').trim();
+  const contextResult = useIndexedContext && (contextIntent || normalizedTarget)
+    ? await resolveContext({
+        rootDir: absoluteRoot,
+        intent: contextIntent,
+        targetFile: normalizedTarget,
+        taskType: inferredTaskType,
+      })
+    : null;
+  const enrichedContextResult = expandRouteContext(contextResult);
+
+  const contextRecommendation = useIndexedContext
+    ? buildContextRecommendation({
+        commandNamespace,
+        contextIntent,
+        targetFile: normalizedTarget,
+        taskType: inferredTaskType,
+        contextResult: enrichedContextResult,
+      })
+    : null;
+  const verificationPlan = useIndexedContext
+    ? await deriveVerificationPlan({
+        rootDir: absoluteRoot,
+        intent: contextIntent,
+        targetFile: normalizedTarget,
+        taskType: inferredTaskType,
+        contextResult: enrichedContextResult,
+        skillIds: selectedIds,
+      })
+    : null;
+
+  const verificationRecommendation = verificationPlan
+    ? {
+        ...verificationPlan,
+        helperCommand: buildHelperCommand({
+          commandNamespace,
+          scriptName: 'verify-context.mjs',
+          intent: contextIntent,
+          targetFile: normalizedTarget,
+          taskType: inferredTaskType,
+        }),
+      }
+    : null;
+  const nextAction = deriveNextAction({
+    activeSkills,
+    contextRecommendation,
+    verificationRecommendation,
+  });
+  const routeSummary = buildRouteSummary({
+    activeSkills,
+    routingContext: {
+      promptText: normalizedPrompt,
+      lastExplicitUserPromptText: preservedPrompt,
+      commandText: normalizedCommand,
+      targetFile: normalizedTarget,
+      contextIntent,
+      taskType: inferredTaskType,
+    },
+    contextRecommendation,
+    verificationRecommendation,
+    nextAction,
+  });
+
+  return {
+    activeSkills,
+    routingContext: {
+      promptText: normalizedPrompt,
+      lastExplicitUserPromptText: preservedPrompt,
+      commandText: normalizedCommand,
+      targetFile: normalizedTarget,
+      contextIntent,
+      taskType: inferredTaskType,
+    },
+    contextRecommendation,
+    verificationRecommendation,
+    nextAction,
+    routeSummary,
+  };
+}
+
+export function buildRouteSummary({
+  activeSkills = [],
+  routingContext = {},
+  contextRecommendation = null,
+  verificationRecommendation = null,
+  nextAction = null,
+} = {}) {
+  const delegationRecommendation = deriveDelegationRecommendation({
+    activeSkills,
+    routingContext,
+    contextRecommendation,
+    verificationRecommendation,
+  });
+  const preview = contextRecommendation?.preview ?? {};
+  const primaryTargets = summarizeCompactList(preview.primaryTargets ?? [], 2);
+  const relatedTests = summarizeCompactList(preview.relatedTests ?? [], 2);
+  const styleFiles = summarizeCompactList(preview.styleFiles ?? [], 1);
+  const primaryCommands = unique(verificationRecommendation?.commands ?? []);
+  const fallbackCommands = unique(verificationRecommendation?.fallbackCommands ?? []);
+  const preferredOrder = unique(
+    verificationRecommendation?.executionPolicy?.preferredOrder
+      ?? [...primaryCommands, ...fallbackCommands],
+  );
+  const policyMode = verificationRecommendation?.executionPolicy?.policyMode ?? null;
+  const compactHelperLane = nextAction?.type === 'pull-indexed-context'
+    && typeof contextRecommendation?.command === 'string'
+    && contextRecommendation.command.trim();
+  const helperHint = compactHelperHint(
+    compactHelperLane
+      ? contextRecommendation?.command
+      : (
+        nextAction?.command
+          ? null
+          : verificationRecommendation?.helperCommand
+      ),
+  );
+  const nextActionCommand = compactHelperLane ? null : nextAction?.command ?? null;
+  const summaryLine = [
+    routingContext.taskType ? `task=${routingContext.taskType}` : null,
+    formatCompactSegment('targets', primaryTargets),
+    formatCompactSegment('tests', relatedTests),
+    formatCompactSegment('styles', styleFiles),
+    policyMode ? `policy=${policyMode}` : null,
+  ].filter(Boolean).join(' | ');
+
+  return {
+    primaryCommands,
+    fallbackCommands,
+    preferredOrder,
+    policyMode,
+    delegateHint: delegationRecommendation?.hint ?? null,
+    nextActionType: nextAction?.type ?? null,
+    nextActionCommand,
+    helperHint,
+    line: summaryLine || 'task=unknown',
+  };
+}
+
+async function selectActiveSkills({ rootDir, promptText, commandText, targetFile }) {
+  const routeSignals = {
+    promptRawText: String(promptText || '').toLowerCase(),
+    promptNormalizedText: buildRouteSignalText(promptText),
+    commandRawText: String(commandText || '').toLowerCase(),
+    commandNormalizedText: buildRouteSignalText(commandText),
+    fileText: String(targetFile || '').toLowerCase(),
+  };
+  const scoredEntries = ROUTE_CATALOG
+    .map((entry) => scoreSkillRouteEntry(entry, routeSignals))
+    .filter((entry) => entry.score > 0)
+    .sort((a, b) => b.score - a.score || a.order - b.order);
+  const active = [];
+
+  for (const entry of scoredEntries) {
+    if (await pathExists(path.join(rootDir, entry.path))) {
+      active.push(entry);
+      if (active.length >= MAX_ACTIVE_ROUTE_SKILLS) {
+        break;
+      }
+    }
+  }
+
+  return active.map(({ order, ...rest }) => rest);
+}
+
+function scoreSkillRouteEntry(entry, routeSignals = {}) {
+  let score = 0;
+  const reasons = [];
+
+  for (const signal of entry.signals) {
+    const {
+      directText,
+      normalizedText,
+    } = getSignalTexts(signal.type, routeSignals);
+    signal.regex.lastIndex = 0;
+    const directMatch = signal.regex.test(directText);
+    signal.regex.lastIndex = 0;
+    const normalizedMatch = !directMatch && Boolean(normalizedText) && signal.regex.test(normalizedText);
+    if (!directMatch && !normalizedMatch) {
+      continue;
+    }
+    score += directMatch
+      ? signal.score
+      : Math.max(1, signal.score - 1);
+    reasons.push(signal.type);
+  }
+
+  score += deriveSkillPriorityBoost(entry.id, routeSignals);
+
+  return {
+    id: entry.id,
+    path: entry.path,
+    contextMode: entry.contextMode ?? 'indexed',
+    reasons: [...new Set(reasons)],
+    score,
+    order: entry.order,
+  };
+}
+
+function deriveSkillPriorityBoost(skillId, routeSignals = {}) {
+  const combinedPromptSignals = [
+    routeSignals.promptRawText ?? '',
+    routeSignals.promptNormalizedText ?? '',
+    routeSignals.commandRawText ?? '',
+    routeSignals.commandNormalizedText ?? '',
+  ].join('\n');
+
+  if (
+    skillId === 'testing-quality'
+    && /\b(test|tests|spec|coverage|mock|fixture|assert|vitest|jest|playwright)\b/.test(combinedPromptSignals)
+  ) {
+    return 1;
+  }
+
+  return 0;
+}
+
+function getSignalTexts(signalType, routeSignals = {}) {
+  if (signalType === 'command') {
+    return {
+      directText: routeSignals.commandRawText ?? '',
+      normalizedText: routeSignals.commandNormalizedText ?? '',
+    };
+  }
+
+  if (signalType === 'file') {
+    return {
+      directText: routeSignals.fileText ?? '',
+      normalizedText: '',
+    };
+  }
+
+  return {
+    directText: routeSignals.promptRawText ?? '',
+    normalizedText: routeSignals.promptNormalizedText ?? '',
+  };
+}
+
+function shouldUseIndexedContext({ activeSkills = [], targetFile = null } = {}) {
+  if (activeSkills.length === 0) {
+    return Boolean(targetFile);
+  }
+
+  const primarySkill = activeSkills[0] ?? null;
+  const primaryIsStandalone = primarySkill?.contextMode === 'standalone';
+  if (!primaryIsStandalone) {
+    return true;
+  }
+
+  if (isStandaloneNonIndexedTarget(primarySkill, targetFile)) {
+    return false;
+  }
+
+  if (activeSkills.some((skill) => skill?.contextMode !== 'standalone')) {
+    return true;
+  }
+
+  return isCodeIndexedTarget(targetFile);
+}
+
+function isStandaloneNonIndexedTarget(primarySkill, targetFile) {
+  if (typeof targetFile !== 'string' || !targetFile.trim()) {
+    return false;
+  }
+
+  const normalized = targetFile.replaceAll('\\', '/');
+  if (primarySkill?.id === 'docker-packaging') {
+    return /(?:^|\/)(?:Dockerfile|docker-compose(?:\.ya?ml)?|compose\.ya?ml|\.dockerignore)$/i.test(normalized);
+  }
+
+  return false;
+}
+
+function isCodeIndexedTarget(filePath) {
+  if (typeof filePath !== 'string' || !filePath.trim()) {
+    return false;
+  }
+
+  const normalized = filePath.replaceAll('\\', '/');
+  if (/\.(?:[cm]?js|jsx|tsx?|vue|py|rb|go|rs|java|kt|swift|php|cs|c|cc|cpp|cxx|h|hpp|m|mm|scala|sh|bash|zsh|sql|psql|css|scss|sass|less|html|xml|json|ya?ml|toml)$/i.test(normalized)) {
+    return true;
+  }
+
+  return /(?:^|\/)(?:src|test|tests|app|lib|components|pages|screens|layouts|composables|api|routes?|controllers?|services?|db|database|migrations?|prisma|SQL)\//i.test(normalized);
+}
+
+function buildContextRecommendation({
+  commandNamespace,
+  contextIntent,
+  targetFile,
+  taskType,
+  contextResult,
+}) {
+  if (!contextIntent && !targetFile) {
+    return null;
+  }
+
+  return {
+    command: buildHelperCommand({
+      commandNamespace,
+      scriptName: 'resolve-context.mjs',
+      intent: contextIntent,
+      targetFile,
+      taskType,
+    }),
+    preview: contextResult
+      ? {
+          taskType: contextResult.taskType,
+          primaryTargets: contextResult.primaryTargets ?? [],
+          analogFiles: contextResult.analogFiles ?? [],
+          sharedAbstractions: contextResult.sharedAbstractions ?? [],
+          relatedTests: contextResult.relatedTests ?? [],
+          styleFiles: contextResult.styleFiles ?? [],
+        }
+      : null,
+  };
+}
+
+function expandRouteContext(contextResult) {
+  if (!contextResult) {
+    return contextResult;
+  }
+
+  const directTestTargets = (contextResult.primaryTargets ?? []).filter(isTestLikeFile);
+  if (directTestTargets.length === 0) {
+    return contextResult;
+  }
+
+  return {
+    ...contextResult,
+    relatedTests: unique([
+      ...(contextResult.relatedTests ?? []),
+      ...directTestTargets,
+    ]),
+  };
+}
+
+function deriveNextAction({
+  activeSkills = [],
+  contextRecommendation = null,
+  verificationRecommendation = null,
+}) {
+  const policy = verificationRecommendation?.executionPolicy ?? null;
+  const primaryCommands = verificationRecommendation?.commands ?? [];
+  const fallbackCommands = verificationRecommendation?.fallbackCommands ?? [];
+
+  if (policy?.requiresHumanConfirmationForBroadOrRisky) {
+    return {
+      type: 'ask-user-confirmation',
+      reason: 'Ask before broad verification because index evidence could not localize a safe targeted lane.',
+      followUpCommands: [...primaryCommands, ...fallbackCommands],
+    };
+  }
+
+  if (policy?.shouldAutoRunPrimaryCommands && primaryCommands.length > 0) {
+    return {
+      type: 'run-primary-verification',
+      command: primaryCommands[0],
+      reason: 'Targeted related verification is available from indexed context.',
+      followUpCommands: fallbackCommands,
+    };
+  }
+
+  if (policy?.shouldAutoRunFallbacks && fallbackCommands.length > 0) {
+    return {
+      type: 'run-fallback-verification',
+      command: fallbackCommands[0],
+      reason: 'No primary verification command was auto-runnable, but routed fallbacks are allowed.',
+      followUpCommands: fallbackCommands.slice(1),
+    };
+  }
+
+  if (contextRecommendation?.command) {
+    return {
+      type: 'pull-indexed-context',
+      command: contextRecommendation.command,
+      reason: 'Resolve the minimal indexed file bundle before widening reads.',
+    };
+  }
+
+  if (activeSkills.length > 0) {
+    return {
+      type: 'read-skill-instructions',
+      skillPaths: activeSkills.map((item) => item.path),
+      reason: 'Open the matching project-local skill before acting.',
+    };
+  }
+
+  return {
+    type: 'inspect-structure',
+    reason: 'No strong route found; inspect repository structure and indexed files first.',
+  };
+}
+
+function deriveDelegationRecommendation({
+  activeSkills = [],
+  routingContext = {},
+  contextRecommendation = null,
+  verificationRecommendation = null,
+} = {}) {
+  const skillIds = activeSkills.map((item) => item.id);
+  const lower = `${routingContext.promptText ?? ''}\n${routingContext.commandText ?? ''}`.toLowerCase();
+  const preview = contextRecommendation?.preview ?? {};
+  const contextBreadth = countDelegationContextBreadth(preview);
+  const hasExplicitTarget = Boolean(routingContext.targetFile);
+  const localizedIndexedLane = hasExplicitTarget && contextBreadth > 0 && contextBreadth <= 3;
+  const hasRelatedTests = (preview.relatedTests ?? []).length > 0;
+  const when = contextRecommendation?.command ? 'after-context' : 'now';
+
+  if (routingContext.taskType === 'trivial') {
+    return null;
+  }
+
+  if (
+    skillIds.includes('executing-plans')
+    || /\b(execute this plan|follow this plan|implementation plan|rollout plan|controlled batches?|review checkpoints?|batch execution|execute in batches)\b/.test(lower)
+  ) {
+    return {
+      hint: 'subagent-driven-development',
+      when,
+      reason: 'Explicit plan/batch execution is separable enough for deliberate subagent passes.',
+    };
+  }
+
+  const noisyDebugLane = skillIds.includes('debugging-toolkit') && (
+    Boolean(String(routingContext.commandText ?? '').trim())
+    || /\b(debug|error|crash|stack(?: trace)?|failing|flake|flaky|timeout|triage|root cause)\b/.test(lower)
+    || verificationRecommendation?.executionPolicy?.policyMode === 'confirm-then-broad'
+  );
+  if (noisyDebugLane && (!localizedIndexedLane || !hasRelatedTests || contextBreadth >= 4)) {
+    return {
+      hint: 'bug-debugger',
+      when,
+      reason: 'A noisy reproduce/trace/fix loop benefits from isolated debugging context.',
+    };
+  }
+
+  const hasImplementationSkill = skillIds.some((id) => DELEGATABLE_IMPLEMENTATION_SKILL_IDS.has(id));
+  const clearImplementationSignal = /\b(implement|build|create|add|ship|deliver|refactor|integrat(?:e|ion)|scaffold|feature)\b/.test(lower);
+  const multiLaneSignal = /\b(multiple|several|parallel|independent|across files|across modules|batch)\b/.test(lower);
+  if (
+    hasImplementationSkill
+    && clearImplementationSignal
+    && routingContext.taskType === 'non-trivial'
+    && (!localizedIndexedLane || !hasExplicitTarget || contextBreadth >= 4 || multiLaneSignal)
+  ) {
+    return {
+      hint: 'feature-implementer',
+      when,
+      reason: 'A broader implementation lane can be delegated without dragging all details through the main context.',
+    };
+  }
+
+  return null;
+}
+
+function deriveContextIntent({ promptText, commandText, targetFile, selectedIds }) {
+  if (promptText.trim()) {
+    return promptText.trim();
+  }
+
+  if (commandText.includes('triage.mjs')) {
+    return `debug ${commandText.trim()}`.trim();
+  }
+
+  if (commandText.includes('query-index.mjs')) {
+    return `investigate ${commandText.trim()}`.trim();
+  }
+
+  if (/\b(test|vitest|jest|playwright|cypress)\b/i.test(commandText)) {
+    return targetFile ? `fix failing test around ${targetFile}` : 'fix failing test';
+  }
+
+  if (targetFile) {
+    if (/^docs\//i.test(targetFile)) {
+      return `update docs for ${targetFile}`;
+    }
+    return `work on ${targetFile}`;
+  }
+
+  if (selectedIds.includes('docs-quality')) return 'update documentation';
+  if (selectedIds.includes('debugging-toolkit')) return 'debug failing issue';
+  if (selectedIds.includes('testing-quality')) return 'write targeted test';
+  if (selectedIds.includes('code-review')) return 'review change for regressions';
+  if (selectedIds.includes('repo-maintenance')) return 'refresh stale workspace';
+  if (selectedIds.includes('discover-security')) return 'review security-sensitive change';
+  return '';
+}
+
+function inferTaskType({ promptText, commandText, selectedIds }) {
+  const lower = buildRouteSignalText(promptText, commandText);
+
+  if (
+    selectedIds.includes('discover-security')
+    || selectedIds.includes('repo-maintenance')
+    || /\b(auth|security|token|permission|secret|migration|uninstall|delete all|drop table|race|flaky|timeout)\b/.test(lower)
+  ) {
+    return 'non-trivial';
+  }
+
+  if (/\b(typo|label|text|rename|color|spacing|toggle|comment)\b/.test(lower)) {
+    return 'trivial';
+  }
+
+  return 'simple';
+}
+
+function shellEscape(str) {
+  if (typeof str !== 'string') return '';
+  return "'" + str.replace(/'/g, "'\''") + "'";
+}
+
+function buildHelperCommand({
+  commandNamespace = '.claude',
+  scriptName,
+  intent = '',
+  targetFile = null,
+  taskType = null,
+}) {
+  const parts = ['node', `${commandNamespace}/ukit/index/${scriptName}`];
+  if (intent) {
+    parts.push(shellEscape(intent));
+  }
+  if (targetFile) {
+    parts.push('--target', shellEscape(targetFile));
+  }
+  if (taskType) {
+    parts.push('--type', taskType);
+  }
+  return parts.join(' ');
+}
+
+function isTestLikeFile(filePath) {
+  return /\.(test|spec)\.[a-z0-9]+$/i.test(filePath)
+    || /(^|\/)(?:__tests__|tests?|specs?)\//i.test(filePath);
+}
+
+function summarizeCompactList(values, limit = 2) {
+  const normalized = unique(values);
+  return {
+    items: normalized.slice(0, limit),
+    total: normalized.length,
+  };
+}
+
+function countDelegationContextBreadth(preview = {}) {
+  return unique([
+    ...(preview.primaryTargets ?? []),
+    ...(preview.analogFiles ?? []),
+    ...(preview.sharedAbstractions ?? []),
+    ...(preview.relatedTests ?? []),
+  ]).length;
+}
+
+function formatCompactSegment(label, summary) {
+  const items = summary?.items ?? [];
+  if (items.length === 0) {
+    return null;
+  }
+
+  const extraCount = Math.max((summary?.total ?? items.length) - items.length, 0);
+  return `${label}=${items.join(',')}${extraCount > 0 ? `,+${extraCount}` : ''}`;
+}
+
+function compactHelperHint(command) {
+  if (typeof command !== 'string' || !command.trim()) {
+    return null;
+  }
+
+  const normalized = command.trim().replace(/\s+/g, ' ');
+  const scriptMatch = normalized.match(/^node\s+([^\s]+)(?:\s+(.*))?$/i);
+  if (!scriptMatch) {
+    return normalized.length > 96 ? `${normalized.slice(0, 93)}...` : normalized;
+  }
+
+  const scriptName = scriptMatch[1].split('/').pop() ?? scriptMatch[1];
+  const rest = scriptMatch[2] ?? '';
+  const targetMatch = rest.match(/--target\s+("[^"]+"|'[^']+'|\S+)/);
+  const typeMatch = rest.match(/--type\s+(\S+)/);
+  const parts = [scriptName];
+
+  if (targetMatch) {
+    parts.push(`target=${stripShellQuotes(targetMatch[1])}`);
+  }
+  if (typeMatch) {
+    parts.push(`type=${typeMatch[1]}`);
+  }
+
+  return parts.join(' ');
+}
+
+function stripShellQuotes(value) {
+  return String(value ?? '').replace(/^['"]|['"]$/g, '');
+}
+
+function normalizeRelativeFile(rootDir, rawFilePath) {
+  if (typeof rawFilePath !== 'string' || !rawFilePath.trim()) {
+    return null;
+  }
+
+  const trimmed = rawFilePath.trim();
+  if (path.isAbsolute(trimmed)) {
+    const relative = path.relative(rootDir, trimmed);
+    if (relative && !relative.startsWith('..') && !path.isAbsolute(relative)) {
+      return relative.replaceAll('\\', '/');
+    }
+    return trimmed.replaceAll('\\', '/');
+  }
+
+  return trimmed.replace(/^\.\/+/, '').replaceAll('\\', '/');
+}
+
+async function pathExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function unique(values) {
+  return [...new Set(values.filter(Boolean))];
+}
+
+const DELEGATABLE_IMPLEMENTATION_SKILL_IDS = new Set([
+  'delivery',
+  'frontend',
+  'frontend-vue',
+  'backend-api',
+  'postgres',
+  'sql-optimization-patterns',
+]);