@ngockhoale/ukit 1.4.0 → 1.4.2

package/src/index/taskRouting.js

@@ -52,18 +52,44 @@ export async function deriveTaskRoute({
     selectedIds,
     targetFile: normalizedTarget,
   });
+  const executionScores = deriveExecutionScores({
+    promptText: normalizedPrompt,
+    commandText: normalizedCommand,
+    targetFile: normalizedTarget,
+    intentMode,
+    taskType: inferredTaskType,
+  });
+  const executionMode = deriveExecutionMode({
+    promptText: normalizedPrompt,
+    commandText: normalizedCommand,
+    targetFile: normalizedTarget,
+    intentMode,
+    taskType: inferredTaskType,
+    executionScores,
+  });
   const preservedPrompt = normalizedPrompt || String(lastExplicitUserPromptText || '').trim();
-  const contextResult = useIndexedContext && (contextIntent || normalizedTarget)
-    ? await resolveContext({
-        rootDir: absoluteRoot,
-        intent: contextIntent,
-        targetFile: normalizedTarget,
-        taskType: inferredTaskType,
-      })
-    : null;
+  const degradedWarnings = [];
+  let contextResult = null;
+  if (useIndexedContext && (contextIntent || normalizedTarget)) {
+    const indexReadError = await findUnreadableIndexArtifact(absoluteRoot);
+    if (indexReadError) {
+      degradedWarnings.push(`resolve-context failed: ${indexReadError.message}`);
+    } else {
+      try {
+        contextResult = await resolveContext({
+          rootDir: absoluteRoot,
+          intent: contextIntent,
+          targetFile: normalizedTarget,
+          taskType: inferredTaskType,
+        });
+      } catch (error) {
+        degradedWarnings.push(`resolve-context failed: ${error?.message ?? String(error)}`);
+      }
+    }
+  }
   const enrichedContextResult = expandRouteContext(contextResult);
 
-  const contextRecommendation = useIndexedContext
+  const contextRecommendation = useIndexedContext && degradedWarnings.length === 0
     ? buildContextRecommendation({
         commandNamespace,
         contextIntent,
@@ -72,8 +98,10 @@ export async function deriveTaskRoute({
         contextResult: enrichedContextResult,
       })
     : null;
-  const verificationPlan = useIndexedContext
-    ? await deriveVerificationPlan({
+  let verificationPlan = null;
+  if (useIndexedContext && contextResult) {
+    try {
+      verificationPlan = await deriveVerificationPlan({
         rootDir: absoluteRoot,
         intent: contextIntent,
         targetFile: normalizedTarget,
@@ -81,8 +109,11 @@ export async function deriveTaskRoute({
         contextResult: enrichedContextResult,
         skillIds: selectedIds,
         autonomyLevel,
-      })
-    : null;
+      });
+    } catch (error) {
+      degradedWarnings.push(`verify-context failed: ${error?.message ?? String(error)}`);
+    }
+  }
 
   const verificationRecommendation = verificationPlan
     ? {
@@ -112,11 +143,14 @@ export async function deriveTaskRoute({
       taskType: inferredTaskType,
       intentMode,
       autonomyLevel,
+      executionScores,
+      executionMode,
     },
     contextRecommendation,
     verificationRecommendation,
     nextAction,
   });
+  const approachSelector = routeSummary?.approachSelector ?? null;
 
   return {
     activeSkills,
@@ -129,11 +163,15 @@ export async function deriveTaskRoute({
       taskType: inferredTaskType,
       intentMode,
       autonomyLevel,
+      executionScores,
+      executionMode,
     },
+    approachSelector,
     contextRecommendation,
     verificationRecommendation,
     nextAction,
     routeSummary,
+    ...(degradedWarnings.length > 0 ? { degradedWarnings } : {}),
   };
 }
 
@@ -169,6 +207,21 @@ export 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 approachSelector = buildApproachSelectorResult({
+    executionMode,
+    executionScores,
+  });
+  const executionContract = buildExecutionContract(executionMode);
+  const completionState = buildCompletionState({
+    executionMode,
+    verificationRecommendation,
+  });
+  const continuationState = buildContinuationState({
+    nextActionType: nextAction?.type ?? null,
+    completionState,
+  });
   const helperHint = compactHelperHint(
     compactHelperLane
       ? contextRecommendation?.command
@@ -187,7 +240,6 @@ export function buildRouteSummary({
     editGuardHint ? `editGuard=${editGuardHint}` : null,
     delegationRecommendation?.hint ? `delegate=${delegationRecommendation.hint}` : null,
     policyMode ? `policy=${policyMode}` : null,
-    contextMode ? `mode=${contextMode}` : null,
   ].filter(Boolean).join(' | ');
 
   return {
@@ -196,6 +248,12 @@ export function buildRouteSummary({
     preferredOrder,
     policyMode,
     editGuardHint,
+    executionMode,
+    executionScores,
+    approachSelector,
+    executionContract,
+    completionState,
+    continuationState,
     intentMode: routingContext.intentMode ?? null,
     delegateHint: delegationRecommendation?.hint ?? null,
     nextActionType: nextAction?.type ?? null,
@@ -212,6 +270,327 @@ 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);
+
+  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 (/\b(failing|broken|error|crash|timeout)\b/.test(raw)) {
+    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,
+  };
+}
+
+function deriveExecutionMode({
+  promptText = '',
+  commandText = '',
+  targetFile = null,
+  intentMode = null,
+  executionScores = {},
+} = {}) {
+  const raw = `${promptText ?? ''}\n${commandText ?? ''}`.toLowerCase();
+  const scores = executionScores;
+  const explicitReviewLead = /\b(review this|audit this|review\b.*\brelease readiness|verify\b.*\brelease readiness)\b/.test(raw);
+
+  if (intentMode === 'review-specific' || explicitReviewLead) {
+    return 'review-release';
+  }
+
+  if (scores.blastRadius >= 3 && (scores.ambiguity >= 2 || scores.investigationNeed >= 2)) {
+    return 'map-impact';
+  }
+
+  if (scores.blastRadius >= 3 || isSharedImpactFile(targetFile)) {
+    return 'shared-edit';
+  }
+
+  if (scores.investigationNeed >= 3) {
+    return 'find-cause';
+  }
+
+  if (
+    scores.editCertainty >= 3
+    && scores.ambiguity === 0
+    && scores.blastRadius === 0
+    && scores.verificationBurden <= 1
+  ) {
+    return 'tiny-fix';
+  }
+
+  if (
+    /\b(build|create|add|implement|feature|summary card)\b/.test(raw)
+    && scores.investigationNeed === 0
+    && scores.blastRadius < 3
+  ) {
+    return 'local-build';
+  }
+
+  if (scores.editCertainty >= 2 && scores.investigationNeed === 0 && scores.blastRadius === 0) {
+    return 'local-fix';
+  }
+
+  return 'local-build';
+}
+
+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,
+} = {}) {
+  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,
+  };
+}
+
+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,
+  };
+}
+
 async function selectActiveSkills({ rootDir, promptText, commandText, targetFile, intentMode = null }) {
   const routeSignals = {
     promptRawText: String(promptText || '').toLowerCase(),
@@ -252,6 +631,10 @@ function shouldKeepRouteEntryForIntent(entry, intentMode) {
     return false;
   }
 
+  if (entry.id === 'code-review' && intentMode === 'implement-specific') {
+    return false;
+  }
+
   return true;
 }
 
@@ -296,6 +679,10 @@ function deriveSkillPriorityBoost(skillId, routeSignals = {}) {
     routeSignals.commandRawText ?? '',
     routeSignals.commandNormalizedText ?? '',
   ].join('\n');
+  const rawPromptSignals = [
+    routeSignals.promptRawText ?? '',
+    routeSignals.commandRawText ?? '',
+  ].join('\n');
 
   if (
     skillId === 'testing-quality'
@@ -304,6 +691,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;
 }
 
@@ -357,10 +752,10 @@ function deriveIntentMode({ promptText = '', commandText = '', targetFile = null
     if (/\b(bug|debug|error|crash|broken|failing|stack trace|triage|fix|login|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';
     }
   }
@@ -392,7 +787,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);
 }
 
@@ -857,12 +1252,36 @@ function normalizeRelativeFile(rootDir, rawFilePath) {
     if (relative && !relative.startsWith('..') && !path.isAbsolute(relative)) {
       return relative.replaceAll('\\', '/');
     }
-    return trimmed.replaceAll('\\', '/');
+    return null;
   }
 
   return trimmed.replace(/^\.\/+/, '').replaceAll('\\', '/');
 }
 
+async function findUnreadableIndexArtifact(rootDir) {
+  const indexDir = path.join(rootDir, '.cache', 'index');
+  let entries;
+  try {
+    entries = await fs.readdir(indexDir);
+  } catch {
+    return null;
+  }
+
+  for (const entry of entries) {
+    if (!entry.endsWith('.json')) {
+      continue;
+    }
+
+    try {
+      JSON.parse(await fs.readFile(path.join(indexDir, entry), 'utf8'));
+    } catch (error) {
+      return new Error(`${entry}: ${error?.message ?? String(error)}`);
+    }
+  }
+
+  return null;
+}
+
 async function pathExists(filePath) {
   try {
     await fs.access(filePath);
@@ -879,6 +1298,7 @@ function unique(values) {
 const DELEGATABLE_IMPLEMENTATION_SKILL_IDS = new Set([
   'delivery',
   'frontend',
+  'frontend-design',
   'frontend-vue',
   'backend-api',
   'postgres',

package/src/index/verificationPlan.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
+import { detectPackageManagerFromFingerprint, getDeclaredPackageManager } from '../core/packageManager.js';
 import { resolveContext } from './resolveContext.js';
 
 const RISKY_SKILL_IDS = new Set(['discover-security', 'repo-maintenance']);
@@ -277,7 +278,7 @@ async function loadProjectVerificationEnvironment({
     .then((resolvedPkg) => ({
       pkg: resolvedPkg,
       scripts: extractScripts(resolvedPkg),
-      packageManager: detectPackageManager({ fingerprintEntries, pkg: resolvedPkg }),
+      packageManager: detectPackageManagerFromFingerprint({ fingerprintEntries, pkg: resolvedPkg }),
     }))
     .catch((error) => {
       PROJECT_VERIFICATION_ENV_CACHE.delete(cacheKey);
@@ -297,41 +298,6 @@ function extractScripts(pkg = null) {
   return pkg?.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {};
 }
 
-function detectPackageManager({ fingerprintEntries = [], pkg = null } = {}) {
-  const declaredPackageManager = getDeclaredPackageManager(pkg);
-  if (declaredPackageManager) return declaredPackageManager;
-
-  const existingFiles = new Set(
-    fingerprintEntries
-      .filter((entry) => entry && entry.mtimeMs !== null)
-      .map((entry) => entry.filePath),
-  );
-  const checks = [
-    ['pnpm-lock.yaml', 'pnpm'],
-    ['yarn.lock', 'yarn'],
-    ['bun.lockb', 'bun'],
-    ['bun.lock', 'bun'],
-    ['package-lock.json', 'npm'],
-  ];
-
-  for (const [lockFile, pm] of checks) {
-    if (existingFiles.has(lockFile)) {
-      return pm;
-    }
-  }
-
-  return 'npm';
-}
-
-function getDeclaredPackageManager(pkg = null) {
-  const declared = String(pkg?.packageManager ?? '').toLowerCase();
-  if (declared.startsWith('pnpm')) return 'pnpm';
-  if (declared.startsWith('yarn')) return 'yarn';
-  if (declared.startsWith('bun')) return 'bun';
-  if (declared.startsWith('npm')) return 'npm';
-  return null;
-}
-
 function buildScriptCommand(packageManager, scriptName, args = []) {
   const filteredArgs = args.filter(Boolean);
 

package/templates/.claude/hooks/reinject-context.sh

@@ -23,6 +23,8 @@ cat <<'FALLBACK'
 - Auto-activate matching project-local skills from prompt + tool/file signals.
 - Reuse existing code. Use yarn. Run tests after code changes.
 - Scope-based verification: match verify effort to change scope.
+- If a routed lane still needs `pull-indexed-context` or still has completion debt, treat that as internal continuation work, not a stopping point.
+- Do not end with “done/applied/fixed” language while write/verification evidence is still missing unless a real blocker is found.
 - If broad verification gets blocked by a Claude hook, follow the routed targeted order or ask for explicit full-suite confirmation.
 === END ===
 FALLBACK

package/templates/.claude/hooks/session-start.md

@@ -8,6 +8,8 @@
 - Auto-activate matching project-local skills from prompt + tool/file signals; end users should not need to know skill names.
 - After routing skill + context, prefer verification derived from related tests/context bundle before broad test runs.
 - Follow routed verification policy: auto-run targeted checks when localized, widen in order for shared/risky scope, and ask before blanket broad runs when no related test evidence exists.
+- Nếu route còn `pull-indexed-context`, coi đó là bước nội bộ để tiếp tục chứ không phải điểm dừng; đọc xong context thì tiếp tục edit/verify ngay khi an toàn.
+- Không được kết thúc bằng “done/applied/fixed” khi còn thiếu write-evidence hoặc verification-evidence, trừ khi có blocker thật.
 - If Claude blocks a broad verification command, do not fight the hook blindly — use the targeted indexed lane first or get explicit confirmation for a full-suite run.
 - Nếu mơ hồ hoặc risk cao (security/migration/auth/data-loss/uninstall-core), escalate đọc sâu hơn hoặc hỏi 1 câu clarify ngắn.
 - Docs là navigation aid, source code là ground truth. Nếu mâu thuẫn → source thắng, update docs trước khi tiếp tục.