@ngockhoale/ukit 3.4.28 → 3.4.30

package/template_project/.claude/ukit/index/playbook-registry.mjs

@@ -21,6 +21,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { isRunAllRequest } from '../runtime/handoff-intent.mjs';
 import { deriveEscalationTriggers, deriveRiskFloor } from './route-resolver.mjs';
 
 const PLAYBOOK_NAME_RE = /\.md$/i;
@@ -47,7 +48,10 @@ export const PLAYBOOK_ID_ALIASES = Object.freeze({
 // Compiled once; every row's discriminator reads the same normalized signals so
 // confusable pairs split on the discriminator column, never trigger text.
 const CREATE_VERB_RE = /\b(create|add|write|build|implement|scaffold|tạo|thêm)\b/i;
-const CHANGE_VERB_RE = /\b(fix|update|modify|change|rename|refactor|restructure|remove|delete|move|migrate|improve|patch|rework|sửa|đổi|cập nhật|thay thế|xóa)\b/i;
+// Vietnamese words never match `\b` (JS word chars are ASCII-only — 'sửa' ends
+// in a non-word char, 'đổi' starts with one), so the diacritic alternates use
+// explicit lookarounds instead. Same word list as the original literal.
+const CHANGE_VERB_RE = /(?:\b(?:fix|update|modify|change|rename|refactor|restructure|remove|delete|move|migrate|improve|patch|rework)\b|(?<![A-Za-z0-9_])(?:sửa|sua|đổi|doi|cập\s+nhật|cap\s+nhat|thay\s+thế|thay\s+the|thay|chỉnh(?:\s+sửa|\s+sua)?|chinh(?:\s+sua)?|xóa|xoa)(?![A-Za-z0-9_]))/i;
 const INVESTIGATION_TRIGGER_RE = /\b(how does|how do|why does|why do|why is|why are|explain|what happens|investigate|understand how|validate the assumption|tại sao|như thế nào|thế nào)\b/i;
 const DEFECT_TRIGGER_RE = /\b(fix|bug|defect|broken|crash(?:es|ed)?|regression|not working|doesn['’]?t work|won['’]?t work|fails?|failing|không hoạt động|lỗi)\b/i;
 const CHECK_VERB_RE = /\b(verify|check|confirm|prove|validate|assert)\b/i;
@@ -76,6 +80,68 @@ const AUTONOMOUS_TRIGGER_RE = /\b(finish (?:this|the) backlog|bounded (?:long )?
 const RELEASE_TRIGGER_RE = /\b(publish|ship it|release|bump (?:the )?version|deploy|cut a release|tag (?:the )?release)\b/i;
 const HANDOFF_CYCLE_TRIGGER_RE = /\b(handoff|multi[- ]?task cycle|task pipeline|execute the plan|worktree)\b/i;
 
+// --- Routing-orchestration signals (reference/clone/SQL/reuse/run-all) -------
+// Shared vocabulary for the discriminators below AND for the additive route
+// summary fields route-task.mjs emits (referenceTargets/cloneIntent/sqlIntent/
+// reuseFirst/goalScope). Kept here so both router surfaces read one definition.
+// Reference-based ask: "like the Customer page", "làm giống trang Customer",
+// "same as module Y", "using validation from Z" — resolve the named source.
+const REFERENCE_TARGET_RE = /(?:\b(?:like|same\s+as|similar\s+to|based\s+on|modell?ed\s+(?:on|after))\s+(?:the\s+|this\s+|that\s+|our\s+)?(?:existing\s+)?(?:[\w-]{1,32}\s){0,2}(?:page|screen|module|component|view|flow|dropdown|select|form|report)\b)|\b(?:page|screen|module|component|view|flow)\b[^\n?]{0,32}\b(?:like|same\s+as)\b|(?<![A-Za-z0-9_])(?:giống|giong|tương\s+tự|tuong\s+tu|như)\s+(?:cái\s+)?(?:trang|page|module|component|tính\s+năng|tinh\s+nang|man\s+hình|view)|(?<![A-Za-z0-9_])(?:trang|page|module|component|man\s+hình)\s+(?:giống|giong|tương\s+tự|tuong\s+tu)|\b(?:using|reuse(?:d)?)\s+(?:the\s+)?(?:validation|logic|pattern|structure|style)\b[^\n?]{0,32}\bfrom\b/i;
+// Clone ask: duplicate a named surface ("clone the Customer page", "nhân bản
+// trang này", "copy the login screen"). A bare "clone the repo" (git) and a
+// bare "copy" without a surface noun stay unmatched.
+const CLONE_INTENT_RE = /(?:\b(?:clone|duplicate|copy)\s+(?:the\s+|this\s+|that\s+|our\s+|my\s+)?(?:existing\s+)?[\w-]{0,32}\s?(?:page|screen|module|component|feature|view|flow|form)\b)|(?<![A-Za-z0-9_])(?:nhân\s+bản|nhan\s+ban|sao\s+chép|sao\s+chep)(?![A-Za-z0-9_])/i;
+// SQL-work ask: the prompt lives in the database layer (a .sql file, a view,
+// column, table, stored function). Vietnamese table words break \b, hence the
+// lookarounds.
+const SQL_INTENT_RE = /(?:\.sql\b)|(?<![A-Za-z0-9_])(?:view|column|table|schema|cột|bảng|cot|bang|stored\s+(?:procedure|function))(?![A-Za-z0-9_])/i;
+// Bare UI-ambiguous words (view/column/table/schema/cột/bảng) only count as SQL work
+// next to SQL context: a DB word, a DDL phrase, a snake_case identifier, or a .sql file.
+// "View the logs" / "a column of buttons" stay ordinary UI language.
+const SQL_STRONG_RE = /(?:\.sql\b)|stored\s+(?:procedure|function)|\b(?:sql|ddl|dml|plpgsql|postgres(?:ql)?|mysql|sqlite)\b|\b(?:create|alter|drop|truncate)\s+(?:or\s+replace\s+)?(?:(?:a|an|the|new)\s+)?(?:\w+\s+)?(?:table|view|schema|function|procedure)\b/i;
+const SQL_WEAK_RE = /(?<![A-Za-z0-9_])(?:view|column|table|schema|cột|bảng|cot|bang)(?![A-Za-z0-9_])/gi;
+const SQL_IDENT_RE = /\b[a-z]+(?:_[a-z0-9]+){1,}\b/;
+function hasSqlIntent(text) {
+  const t = String(text ?? '');
+  if (SQL_STRONG_RE.test(t)) return true;
+  const weak = new Set((t.match(SQL_WEAK_RE) || []).map((w) => w.toLowerCase()));
+  if (weak.size === 0 || /\bcolumn\s+of\b/i.test(t)) return false;
+  // A column+table pair, or a bare DB word beside a snake_case identifier, is schema work.
+  const pair = (weak.has('column') || weak.has('cột') || weak.has('cot')) && (weak.has('table') || weak.has('bảng') || weak.has('bang'));
+  return pair || SQL_IDENT_RE.test(t);
+}
+// The SQL ask touches shape/data rather than a read-only query — routes the
+// migration row instead of a feature build.
+const SQL_SCHEMA_RE = /(?<![A-Za-z0-9_])(?:ddl|alter|drop|(?:create|alter|drop|truncate)\s+table|(?:add|drop|rename|change|modify|update|thêm|xóa|xoá|sửa|sua|đổi|doi)\s+(?:a\s+|the\s+|new\s+|một\s+)*(?:column|cột|cot)(?!\s+of\b)|kiểu\s+dữ\s+liệu|kieu\s+du\s+lieu|data\s?type|not\s+null|constraint|migration|migrate)(?![A-Za-z0-9_])/i;
+// Reuse-first ask: "use the existing/core function", "dùng hàm có sẵn",
+// "tái sử dụng" — search for the function before writing a new one.
+const REUSE_FIRST_RE = /(?:\buse\s+(?:the\s+)?(?:existing|core|shared|same|current)\b)|(?:\buse\s+[\w.]+\s+from\s+(?:the\s+)?(?:core|shared|utils?|common|lib)\b)|\b(?:existing|core|shared)\s+(?:function|helper|util(?:ity|ities)?|service|component)\b|\breuse\b|(?<![A-Za-z0-9_])(?:tái\s+sử\s+dụng|tai\s+su\s+dung)|(?<![A-Za-z0-9_])(?:dùng|dung|dựa|dua)\s+(?:vào\s+|vao\s+)?(?:hàm|ham)(?:\s+(?:có\s+sẵn|co\s+san|sẵn\s+có|san\s+co|đã\s+có|da\s+co|cũ|cu))?(?![A-Za-z0-9_])/i;
+// Run-all goal scope: the prompt queues the WHOLE remaining backlog, never a
+// single named task (single-task refs veto below). A scope signal only — it
+// must never set mutation permission by itself.
+
+// One bounded derivation for the route summary signals. Pure — no I/O. Both
+// router surfaces call this; the discriminators above read the same booleans
+// through buildRouteSignals so the route fields and playbook row selection
+// cannot diverge.
+export function deriveRouteOrchestrationSignals({ promptText = '', commandText = '' } = {}) {
+  const signalText = [promptText, commandText]
+    .map((value) => String(value || '').trim().toLowerCase())
+    .filter(Boolean)
+    .join('\n');
+  if (!signalText) {
+    return { referenceTarget: false, cloneIntent: false, sqlIntent: false, sqlSchemaChange: false, reuseFirst: false, runAll: false };
+  }
+  return {
+    referenceTarget: REFERENCE_TARGET_RE.test(signalText),
+    cloneIntent: CLONE_INTENT_RE.test(signalText),
+    sqlIntent: hasSqlIntent(signalText),
+    sqlSchemaChange: hasSqlIntent(signalText) && SQL_SCHEMA_RE.test(signalText),
+    reuseFirst: REUSE_FIRST_RE.test(signalText),
+    runAll: isRunAllRequest(signalText),
+  };
+}
+
 // session-pickup discriminator needs the resumable-record check. ASYNC scan
 // (W3-PB2): the resolve path runs inside hook processes where a sync
 // readdirSync parks the event loop and can starve the hook self-deadline.
@@ -104,18 +170,32 @@ export const PLAYBOOK_ROUTING_TABLE = Object.freeze([
     // confusable pair 1: no escalation trigger AND single-surface scope. The
     // `!s.escalated` clause is the BL-010 fast-path guard — any derived
     // floor-raising trigger (the six listed triggers map to risk codes +
-    // contract signals) escalates to feature-implementation.
-    discriminator: (s) => !s.escalated && !s.contractSignal && !s.multiSurface && s.changeVerbOrCreate,
+    // contract signals) escalates to feature-implementation. Reference-driven,
+    // clone, reuse-first and SQL-schema asks take the same escape: they name a
+    // source of truth or a data contract the small path must not gloss over.
+    discriminator: (s) => !s.escalated && !s.contractSignal && !s.multiSurface && !s.sqlSchemaChange && !s.referenceTarget && !s.cloneIntent && !s.reuseFirst && s.changeVerbOrCreate,
     fastPath: 'small-feature',
   },
   {
     workGroup: 'feature-implementation',
     playbookId: 'feature-implementation',
     lanes: ['local-build', 'shared-edit', 'map-impact'],
-    triggers: [/implement|add|create|build|integrat|ship|deliver|wir(?:e|ed|ing)/i],
-    // confusable pairs 1/5/8: articulated contract OR ≥1 escalation trigger,
-    // and the ask is not a disposable spike nor the ship chain itself.
-    discriminator: (s) => (s.contractSignal || s.multiSurface || s.escalated || s.wiredShipAsk) && !s.disposable && !s.releaseAsk,
+    triggers: [
+      /implement|add|create|build|integrat|ship|deliver|wir(?:e|ed|ing)/i,
+      REFERENCE_TARGET_RE,
+      CLONE_INTENT_RE,
+      REUSE_FIRST_RE,
+    ],
+    // confusable pairs 1/5/8: articulated contract OR ≥1 escalation trigger OR
+    // a reference/clone/reuse-driven ask — and the ask is not a disposable
+    // spike nor the ship chain itself. The reference/clone/reuse clauses only
+    // claim when no defect verb leads the ask ("fix login like signup" stays
+    // bug-fix); an escalation raised by SQL schema work yields to the
+    // migration row instead of capturing the build lane.
+    discriminator: (s) => (
+      (s.contractSignal || s.multiSurface || (s.escalated && !s.sqlSchemaChange) || s.wiredShipAsk)
+      || ((s.referenceTarget || s.cloneIntent || s.reuseFirst) && s.defectIdx === -1)
+    ) && !s.disposable && !s.releaseAsk,
   },
   {
     workGroup: 'bug-fix',
@@ -190,9 +270,19 @@ export const PLAYBOOK_ROUTING_TABLE = Object.freeze([
     workGroup: 'migration',
     playbookId: 'migration',
     lanes: ['shared-edit', 'map-impact'],
-    triggers: [/migrat|move (?:the |this |all )?[\w-]*|new schema|port (?:the|to)/i],
+    triggers: [
+      /migrat|move (?:the |this |all )?[\w-]*|new schema|port (?:the|to)/i,
+      // SQL schema work pairs a change verb with a shape noun even without a
+      // "migrate" verb — "sửa cột so_created_date trong view", "alter the
+      // users table". A bare noun ("fix the users table") is not enough —
+      // defect-led asks stay bug-fix.
+      /(?:\b(?:alter|drop|add|remove|rename|modify|change|resize)\b[^\n]{0,24}?\b(?:column|table)s?\b)|(?<![A-Za-z0-9_])(?:sửa|sua|đổi|doi|thay|chỉnh|chinh|thêm|them|xóa|xoa|cập\s+nhật|cap\s+nhat)\s+(?:cột|bảng|cot|bang)/i,
+    ],
     // confusable pair 7: behavior change + data/contract move (rollback needed).
-    discriminator: (s) => s.dataMove,
+    // A SQL ask that touches shape (column/table/schema vocabulary) is the same
+    // class even without an explicit move verb — unless a defect verb leads the
+    // ask ("fix the users table" stays bug-fix).
+    discriminator: (s) => s.dataMove || (s.sqlIntent && s.sqlSchemaChange && s.defectIdx === -1),
   },
   {
     workGroup: 'verification',
@@ -332,6 +422,10 @@ async function buildRouteSignals({
     || /(?:chưa|chua|được không|duoc khong|đúng không|dung khong|không nhỉ|khong nhi|thế nào|the nao|như thế nào|nhu the nao|tại sao|tai sao|là gì|la gi|bao giờ|bao gio|khi nào|khi nao|ở đâu|o dau|không biết|khong biet)/.test(signalText)
     || /(?:chưa|chua|đúng không|dung khong|không|khong)\s*[?.!]?\s*$/.test(signalText);
   const questionAsk = questionShaped && !changeRequested;
+  const referenceTarget = REFERENCE_TARGET_RE.test(signalText);
+  const cloneIntent = CLONE_INTENT_RE.test(signalText);
+  const sqlIntent = hasSqlIntent(signalText);
+  const reuseFirst = REUSE_FIRST_RE.test(signalText);
   return {
     signalText,
     executionMode,
@@ -346,6 +440,11 @@ async function buildRouteSignals({
     questionAsk,
     checkFirst,
     changeVerbOrCreate: changeIdx !== -1 || createIdx !== -1,
+    referenceTarget,
+    cloneIntent,
+    sqlIntent,
+    sqlSchemaChange: sqlIntent && SQL_SCHEMA_RE.test(signalText),
+    reuseFirst,
     contractSignal: CONTRACT_SIGNAL_RE.test(signalText) || /\boauth\b/i.test(signalText),
     multiSurface: MULTI_SURFACE_RE.test(signalText),
     escalated: Array.isArray(escalationTriggers) && escalationTriggers.length > 0,

package/template_project/.claude/ukit/index/query-index.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import fs from 'node:fs/promises';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import * as indexCore from './lib/index-core.mjs';
@@ -23,12 +24,15 @@ const args = process.argv.slice(2);
 const rootDir = getRootDir(args);
 const limitArg = readFlagValue(args, '--limit');
 const limit = Number.parseInt(limitArg ?? '5', 10);
+const symbolQuery = readFlagValue(args, '--symbol');
 const showOutline = !args.includes('--no-outline');
 const query = collectPositionalArgs(args, ['--no-outline']);
 
-if (!query) {
-  console.error('Usage: node .claude/ukit/index/query-index.mjs "<error|symbol|path>"');
+if (!query && !symbolQuery) {
+  console.error('Usage: node .claude/ukit/index/query-index.mjs "<error|symbol|path>" [--symbol <name>]');
   process.exitCode = 1;
+} else if (symbolQuery) {
+  await runSymbolMode(symbolQuery);
 } else try {
   const indexGeneratedAtMs = await ensureFreshIndex({ rootDir, logPrefix: 'index:query' });
   const effectiveLimit = Number.isNaN(limit) ? 5 : limit;
@@ -60,11 +64,16 @@ if (!query) {
     });
   }
 
-  if (results.length === 0) {
+  // Stale-entry guard: entries for files that no longer exist (renamed/deleted
+  // after the last build) are dropped from the output instead of pointing at
+  // ghosts.
+  const existingResults = await filterExistingResults(results);
+
+  if (existingResults.length === 0) {
     console.log('[ukit:index:query] no matches');
   } else {
-    console.log(`[ukit:index:query] top ${results.length} matches for: ${query}`);
-    for (const [idx, item] of results.entries()) {
+    console.log(`[ukit:index:query] top ${existingResults.length} matches for: ${query}`);
+    for (const [idx, item] of existingResults.entries()) {
       console.log(`${idx + 1}. ${item.filePath} (score=${item.score})`);
       if ((item.tests ?? []).length > 0) {
         console.log(`   tests: ${item.tests.slice(0, 2).join(', ')}`);
@@ -80,8 +89,92 @@ if (!query) {
 }
 
 catch (error) {
-  console.error(error && error.message ? error.message : error);
-  process.exit(1);
+  // Index missing, rebuild failed, or lock timed out — answer from source with
+  // a bounded search instead of exiting 1.
+  const fallbackRows = await runFallbackSearch(query);
+  if (fallbackRows === null) {
+    console.error(error && error.message ? error.message : error);
+    process.exit(1);
+  }
+}
+
+async function runSymbolMode(symbolQuery) {
+  try {
+    await ensureFreshIndex({ rootDir, logPrefix: 'index:query' });
+    const effectiveLimit = Number.isNaN(limit) ? 8 : limit;
+    const resolveSymbolCandidates = typeof indexCore.querySymbolCandidates === 'function'
+      ? indexCore.querySymbolCandidates
+      : null;
+    if (!resolveSymbolCandidates) {
+      throw new Error('querySymbolCandidates unavailable in index-core');
+    }
+    const candidates = await resolveSymbolCandidates({ rootDir, query: symbolQuery, limit: effectiveLimit });
+    printSymbolCandidates(candidates, 'index');
+  } catch (error) {
+    const fallbackRows = await runFallbackSearch(symbolQuery);
+    if (fallbackRows === null) {
+      console.error(error && error.message ? error.message : error);
+      process.exit(1);
+    }
+  }
+}
+
+function printSymbolCandidates(candidates, origin) {
+  if (!candidates || candidates.length === 0) {
+    console.log('[ukit:index:symbol] no matches');
+    return;
+  }
+  console.log(`[ukit:index:symbol] top ${candidates.length} candidates`);
+  console.log(`source: ${origin === 'fallback' ? 'fallback-search' : 'index'}`);
+  for (const [idx, candidate] of (candidates ?? []).entries()) {
+    const location = candidate.line ? `${candidate.filePath}:${candidate.line}` : String(candidate.filePath ?? '');
+    const parentLabel = candidate.parent ? ` parent=${candidate.parent}${candidate.schema ? `.${candidate.schema}` : ''}` : '';
+    console.log(`${idx + 1}. ${candidate.name} ${location} kind=${candidate.kind} score=${candidate.score} reason=${candidate.reason}${parentLabel}`);
+    if (candidate.needsConfirmation) {
+      console.log('   needs-confirmation: true (candidate, not a substitution)');
+    }
+  }
+}
+
+async function runFallbackSearch(searchQuery) {
+  if (typeof indexCore.boundedSourceSearch !== 'function' || !searchQuery) {
+    return null;
+  }
+  try {
+    const effectiveLimit = Number.isNaN(limit) ? 5 : limit;
+    const rows = await indexCore.boundedSourceSearch({ rootDir, query: searchQuery, limit: effectiveLimit });
+    console.log(`[ukit:index:query] index unavailable — source: fallback-search (${rows.length} matches for: ${searchQuery})`);
+    for (const [idx, row] of rows.entries()) {
+      console.log(`${idx + 1}. ${row.filePath}${row.line ? `:${row.line}` : ''} (reason=${row.reason})`);
+    }
+    if (rows.truncated?.length) {
+      console.log(`[ukit:index:query] search truncated (${rows.truncated.join(',')}) — results are NOT exhaustive`);
+    }
+    return rows;
+  } catch (fallbackError) {
+    console.error(`fallback-search failed: ${fallbackError && fallbackError.message ? fallbackError.message : fallbackError}`);
+    return null;
+  }
+}
+
+async function filterExistingResults(results) {
+  if (!Array.isArray(results)) {
+    return [];
+  }
+  const checks = await Promise.all(results.map(async (item) => ({
+    item,
+    exists: await fileExists(path.join(rootDir, item.filePath)),
+  })));
+  return checks.filter((check) => check.exists).map((check) => check.item);
+}
+
+async function fileExists(absolutePath) {
+  try {
+    await fs.access(absolutePath);
+    return true;
+  } catch {
+    return false;
+  }
 }
 
 async function printOutlineForFile(root, filePath) {

package/template_project/.claude/ukit/index/route-catalog.mjs

@@ -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 },