@ngockhoale/ukit 3.4.29 → 3.4.31

package/src/index/queryIndex.js

@@ -1,9 +1,18 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { execFile } from 'node:child_process';
 
 import { getArtifactPath, getIndexDir, INDEX_ARTIFACTS, INDEX_SCHEMA_VERSION, isLikelyTestFilePath } from './paths.js';
 import { importsNeedAliasContext, loadImportAliasContext, resolveImportSpecifier } from './importResolution.js';
-import { buildSearchDescriptor } from './languageTools.js';
+import {
+  buildSearchDescriptor,
+  boundedDamerauDistance,
+  expandIdentifierQueryVariants,
+  isCompactCharSubsequence,
+  isOrderedTokenSubsequence,
+  normalizeIdentifierTokens,
+  FUZZY_EDIT_DISTANCE_MIN_LENGTH,
+} from './languageTools.js';
 
 const ARTIFACT_CACHE = new Map();
 const QUERY_SEARCH_BUNDLE_CACHE = new Map();
@@ -361,15 +370,30 @@ function scoreDirectFileMatch({ queryDescriptor, filePath, searchDescriptor }) {
       reasons.push(`symbol_compact:${symbolDescriptor.name}`);
     }
 
+    let symbolContributed = false;
+
     for (const token of queryDescriptor.tokens) {
       if (symbolDescriptor.descriptor.tokens.has(token)) {
         score += 3;
+        symbolContributed = true;
         reasons.push(`symbol_token:${symbolDescriptor.name}:${token}`);
       } else if (symbolDescriptor.descriptor.rawLower.includes(token)) {
         score += 1;
+        symbolContributed = true;
         reasons.push(`symbol_contains:${symbolDescriptor.name}`);
       }
     }
+
+    // Fuzzy floor for misspelt or compacted symbol queries ('custmer_code' →
+    // 'customer_code'): subsequence or bounded edit-distance match on the
+    // already-precomputed compacts. Only fires when the symbol earned nothing
+    // from the stronger tiers above.
+    if (!symbolContributed && queryDescriptor.compact.length >= 6) {
+      if (symbolFuzzyMatches(queryDescriptor.compact, symbolDescriptor.descriptor.compact)) {
+        score += 3;
+        reasons.push(`symbol_fuzzy:${symbolDescriptor.name}`);
+      }
+    }
   }
 
   return {
@@ -391,6 +415,396 @@ function groupBy(items, keyFn) {
   return map;
 }
 
+// Fuzzy predicate shared by scoreDirectFileMatch and resolveSymbolCandidates:
+// ordered containment (either direction, on tokens or compacts) or a bounded
+// Damerau distance. Cheap length gates run first so the common non-fuzzy case
+// never builds a distance matrix.
+function symbolFuzzyMatches(queryCompact, symbolCompact) {
+  if (!queryCompact || !symbolCompact) {
+    return false;
+  }
+  if (Math.abs(queryCompact.length - symbolCompact.length) > 2) {
+    return false;
+  }
+  if (isCompactCharSubsequence(queryCompact, symbolCompact) || isCompactCharSubsequence(symbolCompact, queryCompact)) {
+    return true;
+  }
+  if (
+    queryCompact.length >= FUZZY_EDIT_DISTANCE_MIN_LENGTH
+    && symbolCompact.length >= FUZZY_EDIT_DISTANCE_MIN_LENGTH
+    && boundedDamerauDistance(queryCompact, symbolCompact, 2) <= 2
+  ) {
+    return true;
+  }
+  return false;
+}
+
+// ── Symbol-level resolution ──
+// Ranks symbol rows against a (possibly misspelt or phrase-form) query:
+// exact > normalized (case/underscore/hyphen/camel-insensitive) > ordered
+// token/compact subsequence > bounded edit distance. Fuzzy-only results never
+// auto-substitute: they carry confidence 'fuzzy' and needsConfirmation, and any
+// tie inside `scoreMargin` marks the whole leading band ambiguous.
+export function resolveSymbolCandidates(query, symbols, { limit = 8, scoreMargin = 5 } = {}) {
+  const normalizedQuery = String(query ?? '').trim();
+  if (!normalizedQuery || !Array.isArray(symbols)) {
+    return [];
+  }
+
+  const baseTokens = normalizeIdentifierTokens(normalizedQuery);
+  if (baseTokens.length === 0) {
+    return [];
+  }
+  const baseCompact = baseTokens.join('');
+  const variants = expandIdentifierQueryVariants(normalizedQuery);
+
+  const rows = [];
+  const seen = new Set();
+  for (const symbol of symbols) {
+    if (!symbol || typeof symbol?.name !== 'string') {
+      continue;
+    }
+    const symbolTokens = normalizeIdentifierTokens(symbol.name);
+    if (symbolTokens.length === 0) {
+      continue;
+    }
+    const dedupeKey = `${symbol.name}\u0000${symbol.filePath ?? ''}\u0000${symbol.parent ?? ''}\u0000${symbol.schema ?? ''}`;
+    if (seen.has(dedupeKey)) {
+      continue;
+    }
+    seen.add(dedupeKey);
+
+    const match = scoreSymbolCandidate({
+      query: normalizedQuery,
+      baseTokens,
+      baseCompact,
+      variants,
+      symbol,
+      symbolTokens,
+      symbolCompact: symbolTokens.join(''),
+    });
+    if (match) {
+      rows.push(match);
+    }
+  }
+
+  rows.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name) || String(a.filePath ?? '').localeCompare(String(b.filePath ?? '')));
+
+  const top = rows.slice(0, Math.max(limit, 0));
+  const topScore = top[0]?.score ?? 0;
+  const ambiguousBand = top.filter((candidate) => topScore - candidate.score <= scoreMargin);
+  const ambiguous = ambiguousBand.length > 1;
+
+  return top.map((candidate) => ({
+    ...candidate,
+    needsConfirmation: candidate.confidence === 'fuzzy' || ambiguous,
+  }));
+}
+
+function scoreSymbolCandidate({ query, baseTokens, baseCompact, variants, symbol, symbolTokens, symbolCompact }) {
+  const row = {
+    name: symbol.name,
+    filePath: symbol.filePath ?? null,
+    line: Number.isFinite(symbol.line) ? symbol.line : null,
+    kind: symbol.type ?? 'symbol',
+    parent: symbol.parent ?? null,
+    schema: symbol.schema ?? null,
+  };
+
+  if (symbol.name === query) {
+    return { ...row, score: 100, reason: 'exact', confidence: 'exact' };
+  }
+  if (symbolCompact === baseCompact) {
+    return { ...row, score: 90, reason: 'normalized', confidence: 'high' };
+  }
+
+  let best = null;
+  for (const variantTokens of variants) {
+    const variantCompact = variantTokens.join('');
+    if (isOrderedTokenSubsequence(variantTokens, symbolTokens)) {
+      const candidate = { score: 70, reason: 'token-subsequence' };
+      if (!best || candidate.score > best.score) {
+        best = candidate;
+      }
+    }
+    if (isCompactCharSubsequence(variantCompact, symbolCompact)) {
+      const candidate = { score: 65, reason: 'compact-subsequence' };
+      if (!best || candidate.score > best.score) {
+        best = candidate;
+      }
+    }
+    if (
+      variantCompact.length >= FUZZY_EDIT_DISTANCE_MIN_LENGTH
+      && symbolCompact.length >= FUZZY_EDIT_DISTANCE_MIN_LENGTH
+    ) {
+      const distance = boundedDamerauDistance(variantCompact, symbolCompact, 2);
+      if (distance <= 2) {
+        const candidate = { score: 60 - distance * 10, reason: `edit-distance:${distance}` };
+        if (!best || candidate.score > best.score) {
+          best = candidate;
+        }
+      }
+    }
+  }
+
+  if (!best) {
+    return null;
+  }
+  return { ...row, ...best, confidence: 'fuzzy' };
+}
+
+// Loads symbols.json (schema-gated, poisoned rows dropped) and resolves the
+// query against every indexed symbol row, including SQL columns and
+// global-registered frontend functions.
+export async function querySymbolCandidates({ rootDir = process.cwd(), query, limit = 8, scoreMargin = 5 } = {}) {
+  const normalizedQuery = String(query ?? '').trim();
+  if (!normalizedQuery) {
+    return [];
+  }
+
+  const absoluteRoot = path.resolve(rootDir);
+  const symbolsArtifact = await readArtifact(absoluteRoot, INDEX_ARTIFACTS.symbols);
+  const safeSymbolsArtifact = safeSchemaArtifact(symbolsArtifact);
+  return resolveSymbolCandidates(normalizedQuery, safeItems(safeSymbolsArtifact), { limit, scoreMargin });
+}
+
+// ── Fallback source search (index unavailable) ──
+// Bounded ripgrep-first text search so query-index / impact-context can answer
+// from source when the index is missing or its rebuild fails. `rg` runs via
+// child_process when present; otherwise (or on rg failure) a bounded node
+// directory walk honors the same ignore-dir set as the index builder. Rows are
+// { filePath, line } and require EVERY query token to appear in the file.
+export const FALLBACK_SEARCH_IGNORE_DIRS = [
+  'node_modules', '.git', '.cache', '.next', '.nuxt', '.output', '.vercel',
+  '.turbo', '.yarn', 'dist', 'build', 'out', 'coverage', 'tmp', 'temp',
+  'vendor', '.venv', 'venv',
+];
+const FALLBACK_SEARCH_IGNORE_DIR_SET = new Set(FALLBACK_SEARCH_IGNORE_DIRS);
+const FALLBACK_SEARCH_EXTENSIONS = new Set([
+  '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.vue', '.sql', '.json',
+  '.md', '.yaml', '.yml', '.sh', '.css', '.scss', '.sass', '.less', '.html',
+]);
+const FALLBACK_SEARCH_DEFAULTS = {
+  maxFiles: 2000,
+  maxFileBytes: 512 * 1024,
+  rgTimeoutMs: 5000,
+  // Traversal bounds: maxFiles caps MATCHED candidates only, so the walk also needs a cap on
+  // everything it merely visits (huge SQL/data trees, generated dirs not in the ignore set).
+  maxEntries: 20000,
+  maxDepth: 12,
+  maxVerify: 400,
+  walkBudgetMs: 3000,
+};
+
+export async function boundedSourceSearch({
+  rootDir = process.cwd(),
+  query,
+  limit = 8,
+  maxFiles = FALLBACK_SEARCH_DEFAULTS.maxFiles,
+  maxFileBytes = FALLBACK_SEARCH_DEFAULTS.maxFileBytes,
+  engine = 'auto',
+  maxEntries = FALLBACK_SEARCH_DEFAULTS.maxEntries,
+  maxDepth = FALLBACK_SEARCH_DEFAULTS.maxDepth,
+  maxVerify = FALLBACK_SEARCH_DEFAULTS.maxVerify,
+  walkBudgetMs = FALLBACK_SEARCH_DEFAULTS.walkBudgetMs,
+} = {}) {
+  const normalizedQuery = String(query ?? '').trim();
+  if (!normalizedQuery) {
+    return [];
+  }
+  const truncation = new Set();
+  const foldedQuery = buildSearchDescriptor(normalizedQuery).rawLower;
+  const tokens = [...new Set(normalizeIdentifierTokens(foldedQuery))];
+  if (tokens.length === 0) {
+    return [];
+  }
+
+  const absoluteRoot = path.resolve(rootDir);
+  let candidatePaths = null;
+  if (engine === 'auto') {
+    candidatePaths = await ripgrepCandidatePaths({ absoluteRoot, tokens, maxFileBytes });
+  }
+  if (candidatePaths === null) {
+    candidatePaths = await walkCandidatePaths({
+      absoluteRoot, maxFiles, maxFileBytes, maxEntries, maxDepth, walkBudgetMs, truncation,
+    });
+  }
+
+  const rows = [];
+  let verified = 0;
+  for (const relativePath of candidatePaths) {
+    if (verified >= maxVerify) {
+      truncation.add('verify-cap');
+      break;
+    }
+    verified += 1;
+    const verification = await readMatchingLine(absoluteRoot, relativePath, tokens, maxFileBytes);
+    if (!verification) {
+      continue;
+    }
+    rows.push({ filePath: relativePath, line: verification.line, reason: 'fallback-search' });
+    if (rows.length >= Math.max(limit, 0)) {
+      break;
+    }
+  }
+  // A partial scan must never read as exhaustive: callers that care read `rows.truncated`
+  // (non-enumerable, so array equality and JSON output are unchanged).
+  Object.defineProperty(rows, 'truncated', { value: [...truncation], enumerable: false });
+  return rows;
+}
+
+function execFileRipgrep(args, timeoutMs) {
+  return new Promise((resolve) => {
+    execFile('rg', args, { timeout: timeoutMs, maxBuffer: 4 * 1024 * 1024 }, (error, stdout) => {
+      if (error) {
+        // rg exit code 1 = "no matches" (a valid empty answer; error.code is the
+        // number 1). A spawn failure (code 'ENOENT'), a timeout, or exit ≥2
+        // means rg is unusable and the walk must take over.
+        resolve(error.code === 1 ? [] : null);
+        return;
+      }
+      resolve(String(stdout ?? ''));
+    });
+  });
+}
+
+async function ripgrepCandidatePaths({ absoluteRoot, tokens, maxFileBytes }) {
+  const stdout = await execFileRipgrep(
+    [
+      '-i', '--no-heading', '--line-number', '--max-count', '3',
+      '--max-filesize', String(Math.round(maxFileBytes / 1024)) + 'K',
+      ...FALLBACK_SEARCH_IGNORE_DIRS.flatMap((dir) => ['--glob', `!${dir}/**`]),
+      '--glob', '!**/*.min.*',
+      ...tokens.flatMap((token) => ['-e', token]),
+      absoluteRoot,
+    ],
+    FALLBACK_SEARCH_DEFAULTS.rgTimeoutMs,
+  );
+  if (stdout === null) {
+    return null;
+  }
+
+  const paths = [];
+  const seen = new Set();
+  for (const line of stdout.split('\n')) {
+    const separator = line.indexOf(':');
+    if (separator <= 0) {
+      continue;
+    }
+    const matchedPath = line.slice(0, separator);
+    if (!matchedPath || seen.has(matchedPath)) {
+      continue;
+    }
+    seen.add(matchedPath);
+    const relativePath = path.relative(absoluteRoot, matchedPath).replace(/\\/g, '/');
+    if (relativePath && !relativePath.startsWith('..')) {
+      paths.push(relativePath);
+    }
+  }
+  return paths;
+}
+
+// Depth-first walk collecting candidate text files (size- and count-bounded).
+// Token verification happens once in boundedSourceSearch, so the walk only
+// filters by ignore-set, extension, and size.
+async function walkCandidatePaths({
+  absoluteRoot, maxFiles, maxFileBytes, maxEntries, maxDepth, walkBudgetMs, truncation = new Set(),
+}) {
+  const results = [];
+  let visited = 0;
+  const deadline = Date.now() + walkBudgetMs;
+  const exhausted = () => {
+    if (results.length >= maxFiles) { truncation.add('max-files'); return true; }
+    if (visited >= maxEntries) { truncation.add('max-entries'); return true; }
+    if (Date.now() > deadline) { truncation.add('time-budget'); return true; }
+    return false;
+  };
+
+  const walk = async (dir, depth) => {
+    if (exhausted()) {
+      return;
+    }
+    if (depth > maxDepth) {
+      truncation.add('max-depth');
+      return;
+    }
+    let entries;
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      if (exhausted()) {
+        return;
+      }
+      visited += 1;
+      if (entry.isSymbolicLink()) {
+        continue; // never follow links out of the tree (cycles, escapes)
+      }
+      const entryPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (FALLBACK_SEARCH_IGNORE_DIR_SET.has(entry.name) || entry.name.startsWith('.')) {
+          continue;
+        }
+        await walk(entryPath, depth + 1);
+        continue;
+      }
+      if (!entry.isFile() || !FALLBACK_SEARCH_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) {
+        continue;
+      }
+      try {
+        const stat = await fs.stat(entryPath);
+        if (stat.size > maxFileBytes) {
+          continue;
+        }
+      } catch {
+        continue;
+      }
+      results.push(path.relative(absoluteRoot, entryPath).replace(/\\/g, '/'));
+    }
+  };
+
+  await walk(absoluteRoot, 0);
+  return results;
+}
+
+async function readMatchingLine(absoluteRoot, relativePath, tokens, maxFileBytes) {
+  if (!relativePath) {
+    return null;
+  }
+  let content;
+  try {
+    content = await fs.readFile(path.join(absoluteRoot, relativePath), 'utf8');
+  } catch {
+    return null;
+  }
+  if (content.length > maxFileBytes) {
+    return null;
+  }
+  const foldedContent = buildSearchDescriptor(content.slice(0, 64 * 1024)).rawLower;
+  if (!tokens.every((token) => foldedContent.includes(token))) {
+    return null;
+  }
+  const rawLines = content.split('\n');
+  const foldedLines = foldedContent.split('\n');
+  for (const [index, rawLine] of rawLines.entries()) {
+    const foldedLine = foldedLines[index] ?? '';
+    if (tokens.every((token) => foldedLine.includes(token))) {
+      return { line: index + 1 };
+    }
+  }
+  // All tokens present in the file but never on one line — still a hit; point
+  // at the first line containing any token.
+  for (const [index, rawLine] of rawLines.entries()) {
+    const foldedLine = foldedLines[index] ?? '';
+    if (tokens.some((token) => foldedLine.includes(token))) {
+      return { line: index + 1 };
+    }
+  }
+  return { line: null };
+}
+
 function buildFileSearchDescriptors(files, symbolMap) {
   const descriptors = new Map();
 

package/src/index/routeCatalog.js

@@ -68,7 +68,7 @@ export const ROUTE_CATALOG = [
     path: '.claude/skills/postgres/SKILL.md',
     order: 4.5,
     signals: [
-      { type: 'prompt', regex: /\b(sql|postgres|postgresql|migration|schema|table|view|index|trigger|function|stored procedure|materialized view|query plan|explain)\b/i, score: 5 },
+      { type: 'prompt', regex: /\b(sql|postgres|postgresql|migration|schema|trigger|stored (?:procedure|function)|materialized view|query plan|explain|(?:create|alter|drop|truncate) (?:or replace )?(?:table|view|index|function))\b/i, score: 5 },
       { type: 'command', regex: /\b(psql|prisma|drizzle|knex|sequelize|typeorm)\b/i, score: 4 },
       { type: 'file', regex: /\.(?:sql|psql)$/i, score: 5 },
       { type: 'file', regex: /(?:^|\/)(?:SQL\/|sql\/|database\/|db\/|migrations?\/|prisma\/schema\.prisma$)/i, score: 4 },

package/src/index/routeResolver.js

@@ -509,12 +509,12 @@ function unique(values) {
 
 // Completion contract for a lane. Informational routes carry no completion debt;
 // every contract lane returns the still-missing evidence classes plus a reason.
-export function buildCompletionState({ executionMode = null, verificationRecommendation = null } = {}) {
+export function buildCompletionState({ executionMode = null, verificationRecommendation = null, executionContract = null } = {}) {
   if (!executionMode || executionMode === 'informational') {
     return null;
   }
 
-  const contract = buildExecutionContract(executionMode);
+  const contract = executionContract || buildExecutionContract(executionMode);
   const missingEvidence = [...(contract?.completionEvidence ?? [])];
   const requiresVerification = missingEvidence.includes('verification-evidence');
   if (

package/src/index/taskRouting.js

@@ -1,3 +1,4 @@
+import { classifyTaskSemantics, applyTaskSemantics } from '../core/executionContracts.js';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
@@ -113,6 +114,15 @@ If the user says "new task", re-route — do not treat the message as the next s
 4. Implement the smallest change satisfying the predicate.
 5. Verify against the predicate on the real artifact — not "it compiles".
 6. Widen once: check the impact surface the route named, no broader.
+Reference reuse: when the ask points at an existing surface ("like the Customer
+page", "giống trang X", "same as module Y"), read that surface first and mirror
+its structure — the reference defines the done predicate, not just inspiration.
+Reuse-first: when the ask names an existing function, helper, or pattern
+("using validation from Z", "dùng hàm có sẵn"), reuse it — extend or wrap
+before writing new logic, and name the reuse in the report.
+Clone: when the ask duplicates a feature ("clone the Customer page", "nhân bản
+tính năng X"), copy the source feature's structure, rename and adapt each
+surface, and verify the clone against the same predicate class as the original.
 Reply: what changed, the predicate, the evidence it now holds.
 Ask the human only for: irreversible writes, a genuine preference call no experiment
 settles, or a real dead end. Everything else: do it, report it.`,
@@ -660,10 +670,11 @@ export function buildRouteSummary({
     executionScores,
     executionCandidates,
   });
-  const executionContract = buildExecutionContract(executionMode);
+  const executionContract = applyTaskSemantics(buildExecutionContract(executionMode), classifyTaskSemantics({ promptText: routingContext.lastExplicitUserPromptText || routingContext.promptText, targetFile: routingContext.targetFile }));
   const continuousExecution = buildContinuousExecutionPolicy(autonomyLevel);
   const completionState = buildCompletionState({
     executionMode,
+    executionContract,
     verificationRecommendation,
   });
   const continuationState = buildContinuationState({
@@ -871,8 +882,16 @@ function deriveExecutionScores({
 } = {}) {
   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);
+  // Vietnamese edit verbs (\b never matches around diacritics — JS word chars
+  // are ASCII-only), so a small Vietnamese edit like "đổi màu nút thành đỏ"
+  // or "sửa cột …" scores as the small mutating task it is instead of
+  // falling to the all-zero shared-edit floor.
+  const vietnameseEditVerb = /(?<![A-Za-z0-9_])(?:sửa|sua|đổi|doi|thay|chỉnh|chinh|cập\s+nhật|cap\s+nhat)(?![A-Za-z0-9_])/.test(raw);
+  const directTransformSignal = /\b(change|replace|set|rename|convert|swap)\b/.test(raw)
+    || /\bchange\s+.+\s+to\s+.+\b/.test(raw)
+    // "đổi X thành Y" is the Vietnamese "change X to Y".
+    || /(?<![A-Za-z0-9_])(?:đổi|doi|sửa|sua|đặt|dat)\s+[^\n,.;]{1,48}?\s+(?:thành|thanh|to)\s+/.test(raw);
+  const smallFixSignal = /\b(adjust|tweak|patch|fix|modify|update|apply)\b/.test(raw) || vietnameseEditVerb;
   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);
@@ -880,6 +899,7 @@ function deriveExecutionScores({
   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)
+    || vietnameseEditVerb
     || /\bchange\s+.+\s+to\s+.+\b/.test(raw);
   const explicitTarget = Boolean(targetFile);
 
@@ -1082,6 +1102,8 @@ function hasAdvisoryOnlyAssertion({ promptText = '', commandText = '' } = {}) {
   const WAIT_TAIL = '[^.,;\\n]*?(?=\\s+(?:va|and|nhung|roi|then|later|sau\\s+do)\\s+[^.,;\\n]*?\\b(?:implement|apply|update|modify|add|create|ship|deliver|fix|refactor|remove|delete|rename|change|write|build|make|install|run|deploy|execute|edit|sua|them|tao|xoa|doi|thay\\s+the|cap\\s+nhat|viet|chay|cai|chinh|trien\\s+khai|cau\\s+hinh)(?![A-Za-z0-9_])|[.,;]|\\s*$)';
   const residue = trimmed
     .replace(/"[^"\n]*"|«[^»\n]*»/g, ' ')
+      // "tạo plan" / "create a plan": the plan is the deliverable, not a mutation order.
+      .replace(/\b(?:tao|lap|create|make|write|draft)\s+(?:cho\s+toi\s+)?(?:a\s+|an\s+|the\s+|1\s+|mot\s+)?(?:plan|ke\s+hoach|phuong\s+an|lo\s+trinh|roadmap)\b/g, ' ')
     .replace(/\bwrite-evidence\b|\bverification-evidence\b|\bimpact-evidence\b|\broot-cause\b/g, ' ')
     .replace(new RegExp(`\\bgiu\\s+nguyen\\b${TAIL}`, 'g'), ' ')
     .replace(new RegExp(`\\bmuon\\s+giu\\b${TAIL}`, 'g'), ' ')
@@ -1193,6 +1215,8 @@ function hasMutationOrder({ promptText = '', commandText = '' } = {}) {
   const WAIT_TAIL = '[^.,;\\n]*?(?=\\s+(?:va|and|nhung|roi|then|later|sau\\s+do)\\s+[^.,;\\n]*?\\b(?:implement|apply|update|modify|add|create|ship|deliver|fix|refactor|remove|delete|rename|change|write|build|make|install|run|deploy|execute|edit|sua|them|tao|xoa|doi|thay\\s+the|cap\\s+nhat|viet|chay|cai|chinh|trien\\s+khai|cau\\s+hinh)(?![A-Za-z0-9_])|[.,;]|\\s*$)';
   const residue = trimmed
     .replace(/"[^"\n]*"|«[^»\n]*»/g, ' ')
+      // "tạo plan" / "create a plan": the plan is the deliverable, not a mutation order.
+      .replace(/\b(?:tao|lap|create|make|write|draft)\s+(?:cho\s+toi\s+)?(?:a\s+|an\s+|the\s+|1\s+|mot\s+)?(?:plan|ke\s+hoach|phuong\s+an|lo\s+trinh|roadmap)\b/g, ' ')
     // Descriptive state, not an order: "đã/vừa [được] + verb" ("hooks vừa được cài đặt") reports
     // something already done. Only the verb is stripped, so a later imperative still survives.
     .replace(/(?<![a-z0-9_])(?:da|vua)\s+(?:duoc\s+)?(?:implement|apply|update|modify|add|create|ship|deliver|fix|refactor|remove|delete|rename|change|write|build|make|install|run|deploy|execute|edit|sua|them|tao|xoa|doi|thay\s+the|cap\s+nhat|viet|chay|cai|chinh|trien\s+khai|cau\s+hinh)(?![a-z0-9_])/g, ' ')
@@ -1815,7 +1839,7 @@ function hasConcreteTaskSignal(lower, raw, targetFile, { taskQueueNext = false }
   }
 
   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)
-    || /(?<![A-Za-z0-9_])(sửa|fix|lỗi|bug|debug|implement|cài|thêm|review|kiểm tra|soát|đăng nhập)(?![A-Za-z0-9_])/.test(raw);
+    || /(?<![A-Za-z0-9_])(sửa|đổi|thay|chỉnh|fix|lỗi|bug|debug|implement|cài|thêm|review|kiểm tra|soát|đăng nhập)(?![A-Za-z0-9_])/.test(raw);
 }
 
 function hasDocsSpecificTaskSignal(lower, raw, targetFile, { taskQueueNext = false } = {}) {

package/template_project/.claude/commands/ukit/handoff-create.md

@@ -132,6 +132,11 @@ by reading, and record the resolution in `PLAN.md §3`.
 Record every answer verbatim in `PLAN.md §1 Intent`. Downstream phases treat that section as
 the human's own words and never re-ask.
 
+**Headless / non-interactive** (`-p`/print mode, no interactive question tool, or an unattended
+run): there is nobody to answer, so do not ask. Take each question's `(Recommended)` option,
+record every defaulted choice in `PLAN.md §1 Intent` as `Assumed (headless): …`, and continue.
+Ending the turn on a question with no plan written is a failed create.
+
 After the batched call, run Steps 1–2.5 to completion without further questions.
 
 ---

package/template_project/.claude/commands/ukit/handoff-fullstack.md

@@ -74,9 +74,32 @@ QuietScans: <n>/<required>   # only while sweeping for stragglers near the end
 ```
 
 `ExitPredicate` grammar: `all(<term>[,<term>...])` or a single term; terms are
-`index:all-done`, `git:clean`, `file-exists:<relpath>`. The stop gate evaluates it
-mechanically when the cursor claims `Phase: done` — a `done` claim with failing terms
-is bounced back with the per-term state. Keep the line verbatim on every rewrite.
+`index:all-done`, `git:clean`, `file-exists:<relpath>`; goal-level runs add
+`agents:none-running` and `verify:pass` (an unprovable term reads as unmet, never
+as an error). The stop gate evaluates it mechanically when the cursor claims
+`Phase: done` — a `done` claim with failing terms is bounced back with the
+per-term state. A `done` claim with NO `ExitPredicate` line evaluates the default
+`all(index:all-done)` over the current backlog (a project with no `INDEX.md` at
+all keeps the plain phase-only release). Keep the line verbatim on every rewrite.
+
+**Goal status vs cycle.** The run reports two layers: the CYCLE (the `Phase:`/
+`Cursor:` lines above) and the GOAL — `Status: RUNNING|PAUSED|BLOCKED|COMPLETED`,
+derived mechanically from the cursor, the current `INDEX.md` backlog (including
+review-created repair tasks and tasks added mid-run), running agents, and
+verification evidence. `COMPLETED` is only ever derived — cursor `Phase: done`,
+every in-scope task `done`/`cancelled_superseded`, `agents:none-running`,
+`verify:pass`, dependency-consistent (no task `done` behind an unfinished
+dependency), final snapshot consistent — never claimed from model text. An
+optional `Paused: yes` line marks a quota/user pause: the gate releases instead
+of forcing continuation, and nothing resumes until an explicit instruction.
+
+**Run-all rule.** When the invocation is a run-all instruction, the run cursor records `GoalScope: run-all`; a finalized (header-only `INDEX.md`) cycle then does NOT release the stop while consumable `queued/` blueprints remain or the queue is unreadable — open the next cycle. A run-all instruction ("run all remaining tasks", "finish
+everything", "chạy hết các task còn lại") binds the GOAL, not one cycle: a
+`Phase: done` cursor over an unfinished backlog is bounced straight back with the
+default `all(index:all-done)` until the backlog is empty. A single-task prompt
+("run task 3") never triggers the goal loop. The loop stays bounded: the stall
+breaker (unchanged cursor AND task snapshot) and the per-task
+`maxAttemptsPerFailure` cap release a run that keeps failing the same wall.
 
 This file is the resume contract. It costs one small write per step and is what turns an
 interrupted run into a continuable one.
@@ -350,6 +373,8 @@ git add docs/AI_HANDOFF/ && git commit -m "handoff: plan — <goal>"
 
 Replace `<goal>` with the one-sentence goal from ACTIVE.md. This locks the plan in git before any implementation begins.
 
+If the lite agent reports it has no shell/Bash tool (or its shell call is rejected), run the same two git commands yourself in the main session and continue — a missing shell on the sidecar lane is never a blocker for P3. Only `blocked` the run if the main session's own `git commit` fails.
+
 > **For the human operator, on a tool with no agent support (Codex) — not an instruction to the model:** manually switch to the lite model for P2/P3.
 
 ---
@@ -745,11 +770,24 @@ When `handoff.fullstack.autoArchive` is true (default), archive per `handoff-cle
 conventions so a future session needs no transcript to understand the cycle:
 
 1. Move the completed cycle's records (PLAN.md, SPEC.md, task files, ACTIVE.md snapshot)
-   into `docs/AI_HANDOFF/archive/cycle-<NN>/`.
+   into `docs/AI_HANDOFF/archive/cycle-<NN>/`, then — BEFORE resetting `INDEX.md` — run
+   `node .claude/ukit/runtime/resumable-run.mjs archive-cycle . <NN>`. It writes the verified
+   INDEX rows to `archive/cycle-<NN>/INDEX.md` and stamps each terminal task header, so the
+   stop predicate reads the INDEX status, not a stale executor-written header. It is
+   idempotent; after an interrupted archive just run it again.
 2. If `archive/` holds more than 3 cycle folders → fold the oldest into a one-line
    summary in `HISTORY.md` and remove it.
 3. Reset `ACTIVE.md` to its empty template; clear `INDEX.md` rows to a fresh header;
    remove `tasks/TASK-*.md`; clear `PLAN.md`/`SPEC.md` (templates stay).
+   **Predicate terms:** the stop gate's `index:all-done` accepts a header-only INDEX when
+   every task in `archive/cycle-<NN>/` is terminal-success (`done`/`cancelled_superseded`)
+   according to that cycle's INDEX snapshot (legacy archives without one fall back to the task
+   header). A finalized cycle is NOT run-all completion: under `GoalScope: run-all` the
+   predicate still fails while `queued/<slug>/` blueprints (not `QueueIntent:
+   deliberate-future`) remain. Keep archived task files until the goal is complete. When the
+   `ExitPredicate` contains `verify:pass`, run the final verification command through the
+   shell in THIS session after the last edit (the receipt is per-session; a pipe without
+   `pipefail` is unproven).
    Then **verify the write** on each reset file (read back the empty header /
    template marker).
 4. Commit the docs + archive changes:
@@ -759,6 +797,7 @@ conventions so a future session needs no transcript to understand the cycle:
 
 Set `Phase: done` in `docs/AI_HANDOFF/RUN.md`, disarm any watchdog job armed at the
 start, and emit the Final Report below.
+
    Then **verify the write** (read back `Phase: done`) — a lost cursor write
    leaves the next session resuming a finished run.
 

package/template_project/.claude/hooks/block-dangerous.mjs

@@ -207,7 +207,13 @@ async function evaluate({ command, projectRoot, env, deadlineMs, signal }) {
   const cmdHead = normalizeExecWord(head);
   let scan = command;
   if (SAFE_TEXT_HEADS.has(cmdHead) && !PIPE_TO_SHELL_RE.test(command)) {
-    scan = command.replace(/'[^']*'/g, "'Q'").replace(/"[^"]*"/g, '"Q"');
+    // A quoted-delimiter heredoc body (<<'EOF') is inert literal text — no
+    // expansion, no execution. Unquoted delimiters expand $(...) so they stay
+    // scanned. Only the body is dropped; the command line itself is still scanned.
+    scan = command
+      .replace(/(<<-?[ \t]*(['"])([A-Za-z_][\w]*)\2[^\n]*\n)[\s\S]*?\n[ \t]*\3[ \t]*(?=\n|$)/g, '$1Q')
+      .replace(/'[^']*'/g, "'Q'")
+      .replace(/"[^"]*"/g, '"Q"');
   }
 
   for (const literal of DANGEROUS_LITERALS) {