@ngockhoale/ukit 3.4.28 → 3.4.30

package/template_project/.claude/hooks/handoff-model-guard.sh

@@ -91,7 +91,7 @@ PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
 # transcript_path is read from the FIRST unescaped key occurrence: a tool_input string
 # can only carry the text with escaped quotes, so it cannot spoof this lookup.
 CREATE_SCOPE_RUN=0
-if printf '%s' "$INPUT" | grep -qE '"tool_name"[[:space:]]*:[[:space:]]*"(Edit|Write|MultiEdit|NotebookEdit|Bash)"'; then
+if printf '%s' "$INPUT" | grep -qE '"tool_name"[[:space:]]*:[[:space:]]*"(Edit|Write|MultiEdit|NotebookEdit|Bash|Agent|Task)"'; then
   __ukit_tp="$(printf '%s' "$INPUT" | grep -oE '"transcript_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -n 1 | sed -E 's/^"transcript_path"[[:space:]]*:[[:space:]]*"//; s/"$//')"
   case "$__ukit_tp" in
     '') ;;
@@ -106,6 +106,8 @@ if printf '%s' "$INPUT" | grep -qE '"tool_name"[[:space:]]*:[[:space:]]*"(Edit|W
               CREATE_SCOPE_RUN=1
             elif grep -q -a -F -m 1 handoff-create "$__ukit_tp" 2>/dev/null; then
               CREATE_SCOPE_RUN=1
+            elif head -c 8192 "$__ukit_tp" 2>/dev/null | grep -q -a -F '"parentSession"'; then
+              CREATE_SCOPE_RUN=1 # omp delegated session: authority is inherited from the parent transcript
             fi
             ;;
         esac
@@ -113,11 +115,38 @@ if printf '%s' "$INPUT" | grep -qE '"tool_name"[[:space:]]*:[[:space:]]*"(Edit|W
       ;;
   esac
 fi
-if [ "$CREATE_SCOPE_RUN" != 1 ] && ! printf '%s' "$INPUT" | grep -qE 'AI_HANDOFF|git[[:space:]]+push'; then
+# Phase-marker fallback (session-keyed, written by the node scope path on a conclusive intent
+# scan with phase=create). Consulted ONLY when the transcript cannot answer: no/unreadable
+# transcript, or a subagent payload (agent_id/agent_type) whose sidechain lacks the command
+# tag. A readable parent transcript with no `handoff-create` stays a conclusive "not create".
+if [ "$CREATE_SCOPE_RUN" != 1 ] && printf '%s' "$INPUT" | grep -qE '"tool_name"[[:space:]]*:[[:space:]]*"(Edit|Write|MultiEdit|NotebookEdit|Bash|Agent|Task)"'; then
+  __ukit_sid="$(printf '%s' "$INPUT" | grep -oE '"session_id"[[:space:]]*:[[:space:]]*"[A-Za-z0-9_-]+"' | head -n 1 | sed -E 's/^"session_id"[[:space:]]*:[[:space:]]*"//; s/"$//')"
+  __ukit_marker="$PROJECT_ROOT/.ukit/storage/cache/handoff-phase/$__ukit_sid.json"
+  if [ -n "$__ukit_sid" ] && [ -f "$__ukit_marker" ] && grep -q '"phase":"create"' "$__ukit_marker" 2>/dev/null; then
+    if [ -z "${__ukit_tp:-}" ] || [ ! -r "${__ukit_tp:-/nonexistent}" ] \
+      || printf '%s' "$INPUT" | grep -qE '"(agent_id|agent_type)"[[:space:]]*:'; then
+      CREATE_SCOPE_RUN=1
+    fi
+  fi
+fi
+# Task-claim pre-filter: an executor delegation naming a TASK id needs the claim check.
+TASK_CLAIM_RUN=0
+if printf '%s' "$INPUT" | grep -qE '"tool_name"[[:space:]]*:[[:space:]]*"(Agent|Task)"' \
+  && printf '%s' "$INPUT" | grep -qE 'TASK-([Cc][0-9]+-)?[0-9]+'; then
+  TASK_CLAIM_RUN=1
+fi
+# Main-agent ownership pre-filter: a source Edit/Write only needs the node gate while a
+# handoff-fullstack run sits in an implement phase (cheap RUN.md grep, no node spawn otherwise).
+MAIN_OWNER_RUN=0
+if printf '%s' "$INPUT" | grep -qE '"tool_name"[[:space:]]*:[[:space:]]*"(Edit|Write|MultiEdit)"' \
+  && grep -qE '^Phase:[[:space:]]*I[1-4]\b' "$PROJECT_ROOT/docs/AI_HANDOFF/RUN.md" 2>/dev/null; then
+  MAIN_OWNER_RUN=1
+fi
+if [ "$CREATE_SCOPE_RUN" != 1 ] && [ "$TASK_CLAIM_RUN" != 1 ] && [ "$MAIN_OWNER_RUN" != 1 ] && ! printf '%s' "$INPUT" | grep -qE 'AI_HANDOFF|git[[:space:]]+push'; then
   exit 0
 fi
 
-INPUT_FILE="$UKIT_INPUT_FILE" PROJECT_ROOT="$PROJECT_ROOT" CREATE_SCOPE_RUN="$CREATE_SCOPE_RUN" HOOK_DIR="$SCRIPT_DIR" node <<'NODE'
+INPUT_FILE="$UKIT_INPUT_FILE" PROJECT_ROOT="$PROJECT_ROOT" CREATE_SCOPE_RUN="$CREATE_SCOPE_RUN" TASK_CLAIM_RUN="$TASK_CLAIM_RUN" HOOK_DIR="$SCRIPT_DIR" node <<'NODE'
 const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10) || 3000;
 // SPEC §8: a timed-out gate silently passes work it never evaluated — announce the
 // degrade (fail-open posture kept: still exit 0).
@@ -562,24 +591,107 @@ async function createScopeVerdict({ toolName: tool, filePath, filePaths, command
   return { block: false, cls: 'allow' };
 }
 
+// Subagent types a planning-only session may delegate to: read-only / planning lanes. Anything
+// that carries Edit/Write/Bash for product work (feature-implementer, bug-debugger,
+// general-purpose, claude, or an unknown/missing type) is an implementation hand-off.
+const CREATE_AGENT_ALLOW = new Set([
+  'handoff-planner', 'code-reviewer', 'ukit-small-task-maintainer', 'ukit-vision-analyst',
+  'explore', 'plan', 'claude-code-guide', 'statusline-setup',
+  // omp read-only lanes (real omp `task` tool: input.tasks[].agent)
+  'scout', 'reviewer', 'security-reviewer',
+]);
+// Every delegated agent type in the payload: Claude Agent/Task (`subagent_type`) and the omp
+// `task` tool (`tasks[].agent`). A missing type is the host's DEFAULT agent, which can write —
+// it is reported as '' and therefore denied.
+function delegatedAgentTypes(inp) {
+  const types = [];
+  if (Array.isArray(inp?.tasks) && inp.tasks.length) {
+    for (const t of inp.tasks) types.push(String(t?.agent || t?.subagent_type || '').toLowerCase());
+  } else {
+    types.push(String(inp?.subagent_type || inp?.agent || inp?.agent_type || '').toLowerCase());
+  }
+  return types;
+}
+const PHASE_MARKER_TTL_MS = 12 * 60 * 60 * 1000;
+const phaseMarkerPath = (sidOverride) => {
+  const sid = String(sidOverride ?? payload?.session_id ?? '');
+  return /^[A-Za-z0-9_-]+$/.test(sid) ? path.join(projectRoot, '.ukit/storage/cache/handoff-phase', `${sid}.json`) : '';
+};
+async function writePhaseMarker(phase) {
+  const file = phaseMarkerPath();
+  if (!file) return;
+  try {
+    await fsp.mkdir(path.dirname(file), { recursive: true });
+    await fsp.writeFile(file, JSON.stringify({ phase, ts: Date.now() }) + '\n', 'utf8');
+  } catch {}
+}
+async function readPhaseMarker(sidOverride) {
+  const file = phaseMarkerPath(sidOverride);
+  if (!file) return null;
+  try {
+    const m = JSON.parse(await fsp.readFile(file, 'utf8'));
+    return m && typeof m.phase === 'string' && Date.now() - Number(m.ts) < PHASE_MARKER_TTL_MS ? m.phase : null;
+  } catch { return null; }
+}
+// Bounded deny-audit row (provider, tool, phase, reason class) — deterministic, no LLM.
+async function auditCreateDecision(row) {
+  try {
+    const dir = path.join(projectRoot, '.ukit/storage/cache');
+    await fsp.mkdir(dir, { recursive: true });
+    const file = path.join(dir, 'handoff-phase-audit.jsonl');
+    let prior = '';
+    try { prior = await fsp.readFile(file, 'utf8'); } catch {}
+    const lines = prior.split('\n').filter(Boolean).slice(-199);
+    lines.push(JSON.stringify({ ts: new Date().toISOString(), provider: process.env.UKIT_HARNESS || 'claude-code', tool: toolName, ...row }));
+    await fsp.writeFile(file, lines.join('\n') + '\n', 'utf8');
+  } catch {}
+}
+
 // Returns a degrade message to emit on a clean (exit 0) finish, or ''.
+// Phase source 1: the transcript (newest structured command wins). Memoized; a conclusive
+// scan refreshes the session marker so later subagent/oversized-transcript calls inherit it.
+let scanMemo = null;
+async function scanTranscript() {
+  if (scanMemo) return scanMemo;
+  let scan = { intent: null, known: false };
+  const transcriptPath = typeof payload?.transcript_path === 'string' ? payload.transcript_path : '';
+  let readable = false;
+  if (transcriptPath) {
+    try { await fsp.access(transcriptPath, fs.constants.R_OK); readable = true; } catch {}
+  }
+  if (readable) {
+    try {
+      const mod = await import(require('url').pathToFileURL(path.resolve(process.env.HOOK_DIR || '.', '../ukit/runtime/handoff-intent.mjs')).href);
+      scan = await (mod.transcriptHandoffIntentInherited || mod.transcriptHandoffIntent)(transcriptPath);
+    } catch {
+      scan = { intent: null, known: false };
+    }
+  }
+  if (scan.known && scan.intent) await writePhaseMarker(scan.intent);
+  scanMemo = { scan, readable };
+  return scanMemo;
+}
 async function createScopeGate() {
-  const SCOPE_TOOLS = ['Write', 'Edit', 'MultiEdit', 'NotebookEdit', 'Bash'];
+  const SCOPE_TOOLS = ['Write', 'Edit', 'MultiEdit', 'NotebookEdit', 'Bash', 'Agent', 'Task'];
   if (process.env.CREATE_SCOPE_RUN !== '1' || !SCOPE_TOOLS.includes(toolName)) return '';
   try {
     const cfg = JSON.parse(await fsp.readFile(path.join(projectRoot, '.ukit/storage/config.json'), 'utf8'));
     if (cfg?.handoff?.createScopeGuard === false) return '';
   } catch {}
 
+  await scanTranscript(); // refresh the phase marker even for in-scope calls
   const isBash = toolName === 'Bash';
+  const isAgent = toolName === 'Agent' || toolName === 'Task';
   const command = isBash ? String(input.command || '') : '';
   const filePath = String(input.file_path || input.notebook_path || input.path || '');
-  const patch = isBash ? { paths: [], unparseable: false } : patchTargets(input);
+  const patch = (isBash || isAgent) ? { paths: [], unparseable: false } : patchTargets(input);
   const filePaths = [...(Array.isArray(input.paths) ? input.paths.filter((p) => typeof p === 'string') : []), ...patch.paths];
-  if (isBash ? !shellWriteHit(command) : !(filePath || filePaths.length || patch.unparseable)) return '';
+  if (isAgent) {
+    // fall through: every delegation is checked against the allow-list below
+  } else if (isBash ? !shellWriteHit(command) : !(filePath || filePaths.length || patch.unparseable)) return '';
 
-  // Only deny/unknown classes (or a write-ish command) pay for the transcript scan.
-  if (!isBash) {
+  // Only deny/unknown classes (or a write-ish command, or a delegation) pay for the transcript scan.
+  if (!isBash && !isAgent) {
     let denied = patch.unparseable;
     for (const target of [filePath, ...filePaths]) {
       if (target && (await classifyTarget(target, projectRoot)).block) { denied = true; break; }
@@ -587,21 +699,51 @@ async function createScopeGate() {
     if (!denied) return '';
   }
 
-  const transcriptPath = typeof payload?.transcript_path === 'string' ? payload.transcript_path : '';
-  if (!transcriptPath) return '';
-  try { await fsp.access(transcriptPath, fs.constants.R_OK); } catch { return ''; } // missing/unreadable: silent
-  let scan;
-  try {
-    const mod = await import(require('url').pathToFileURL(path.resolve(process.env.HOOK_DIR || '.', '../ukit/runtime/handoff-intent.mjs')).href);
-    scan = await mod.transcriptHandoffIntent(transcriptPath);
-  } catch {
-    scan = { intent: null, known: false };
+  const { scan, readable } = await scanTranscript();
+  let intent = null;
+  let source = 'transcript';
+  if (scan.known && scan.intent) {
+    intent = scan.intent;
+  } else {
+    // Phase source 2: the session marker — for payloads whose transcript cannot answer
+    // (subagent sidechain without the command tag, oversized/timed-out/missing transcript).
+    const subagentPayload = Boolean(payload?.agent_id || payload?.agent_type);
+    if (!scan.known || subagentPayload || !readable) {
+      const marked = await readPhaseMarker();
+      if (marked) { intent = marked; source = 'marker'; }
+    }
+    // Declared-but-unreadable lineage (omp child whose parent transcript is gone): verified
+    // identity only — the PARENT's own session marker (keyed by the id in its transcript file
+    // name). No marker => unknown lineage, which stays advisory exactly as before; a marker
+    // for the parent is never borrowed from an unrelated session.
+    if (!intent && scan.unresolvedParent) {
+      const stem = path.basename(String(scan.unresolvedParent)).replace(/\.jsonl?$/i, '');
+      for (const cand of new Set([stem, ...stem.split('_')])) {
+        const marked = cand ? await readPhaseMarker(cand) : null;
+        if (marked) { intent = marked; source = 'parent-marker'; break; }
+      }
+    }
+  }
+  if (intent !== 'create') {
+    if (!scan.known && !intent) {
+      return 'UKit handoff create-scope guard: the session-intent scan was inconclusive (transcript larger than the 32 MiB scan window, scan timed out, or intent module unavailable) and no session phase marker exists; this call proceeded without the create write-scope check.';
+    }
+    return '';
+  }
+
+  if (isAgent) {
+    const type = delegatedAgentTypes(input).find((t) => !CREATE_AGENT_ALLOW.has(t));
+    if (type !== undefined) {
+      await auditCreateDecision({ phase: intent, source, decision: 'deny', cls: 'agent-delegation', agent: type || 'unspecified' });
+      block(`handoff-create is planning-only: delegating to '${type || 'general-purpose'}' (an implementation-capable agent) is not allowed here. Allowed: ${[...CREATE_AGENT_ALLOW].join(', ')}. To implement, run /ukit:handoff-implement or /ukit:handoff-fullstack.`);
+    }
+    return '';
   }
-  if (!scan.known) {
-    return 'UKit handoff create-scope guard: the session-intent scan was inconclusive (transcript larger than the 32 MiB scan window, scan timed out, or intent module unavailable); this write proceeded without the create write-scope check.';
+  const verdict = await createScopeVerdict({ toolName, filePath, filePaths, command, projectDir: projectRoot, intent, patchUnparseable: patch.unparseable });
+  if (verdict.block) {
+    await auditCreateDecision({ phase: intent, source, decision: 'deny', cls: verdict.cls });
+    block(verdict.reason);
   }
-  const verdict = await createScopeVerdict({ toolName, filePath, filePaths, command, projectDir: projectRoot, intent: scan.intent, patchUnparseable: patch.unparseable });
-  if (verdict.block) block(verdict.reason);
   return '';
 }
 
@@ -616,6 +758,78 @@ async function createScopeGate() {
   }
 }
 
+// Per-task execution claim (goal loop): no two executor agents run the same INDEX task, and a
+// finished task is never re-dispatched. Released by record-execution.mjs on the tool result;
+// an abandoned claim expires by TTL (stale takeover). Only lock/IO trouble degrades open —
+// an active foreign claim or a completed task is a hard, explained deny.
+async function taskClaimGate() {
+  if (process.env.TASK_CLAIM_RUN !== '1' || (toolName !== 'Agent' && toolName !== 'Task')) return;
+  try {
+    const cfg = JSON.parse(await fsp.readFile(path.join(projectRoot, '.ukit/storage/config.json'), 'utf8'));
+    if (cfg?.handoff?.taskClaims === false) return;
+  } catch {}
+  let mod;
+  try {
+    mod = await import(require('url').pathToFileURL(path.resolve(process.env.HOOK_DIR || '.', '../ukit/runtime/resumable-run.mjs')).href);
+  } catch { return; }
+  const indexText = await readTextSafe(path.join(projectRoot, 'docs/AI_HANDOFF/INDEX.md'));
+  if (!indexText) return; // no handoff cycle here
+  const rowFor = (id) => indexText.split('\n').find((line) => new RegExp(`^\\|\\s*${id}\\s*\\|`, 'i').test(line));
+  const targets = mod.delegatedClaimTargets(input, { isKnownTask: (id) => Boolean(rowFor(id)) });
+  const owner = mod.delegatedClaimOwner(payload);
+  if (!targets.length || !owner) return;
+  for (const { taskId } of targets) {
+    const row = rowFor(taskId);
+    if (!row) continue; // not a task of this cycle
+    const status = (row.split('|')[5] || '').trim().toLowerCase();
+    if (status === 'done' || status === 'cancelled' || status === 'cancelled_superseded' || status === 'archived') {
+      block(`${taskId} is already ${status} in docs/AI_HANDOFF/INDEX.md — it will not be dispatched again. Pick the next open task or reopen it explicitly in INDEX.md first.`);
+    }
+    const claim = await mod.acquireTaskClaim(projectRoot, taskId, { owner, sessionId: payload?.session_id || null, ttlMs: mod.DELEGATED_CLAIM_TTL_MS });
+    if (!claim.ok && claim.reason === 'active-claim') {
+      block(`${taskId} is already being executed by another agent (active claim). Wait for it to finish, or pick another task; a stale claim expires on its own.`);
+    }
+  }
+}
+await taskClaimGate();
+
+// Main-agent task ownership. handoff-fullstack contracts implementation to claim-bearing
+// executor subagents ("Do NOT implement the tasks yourself in the current session"). The
+// delegation path is claim-gated above; this closes the direct path: while a run is in an
+// implement phase (I1-I4), the MAIN Claude Code session (no agent_id/agent_type in the payload)
+// may not Edit/Write product files unless it holds an active `main:<session>` claim from the
+// SAME claim registry (`resumable-run.mjs claim <root> TASK-xxx --owner main:<session>`).
+// Docs/runtime/tooling paths and files outside this checkout (per-task worktrees) are exempt.
+// Provider limit: only Claude Code payloads prove main-vs-subagent identity, so omp/Codex
+// keep the delegation-only claim gate (no false denies against their subagent edits).
+async function mainAgentOwnershipGate() {
+  if (!['Write', 'Edit', 'MultiEdit'].includes(toolName)) return;
+  if (payload?.agent_id || payload?.agent_type) return;
+  if (String(process.env.UKIT_HARNESS || 'claude-code') !== 'claude-code') return;
+  try {
+    const cfg = JSON.parse(await fsp.readFile(path.join(projectRoot, '.ukit/storage/config.json'), 'utf8'));
+    if (cfg?.handoff?.taskClaims === false || cfg?.handoff?.mainAgentExecution === 'allow') return;
+  } catch {}
+  const filePath = String(input.file_path || input.path || '');
+  if (!filePath) return;
+  const rel = path.relative(projectRoot, filePath).replace(/\\/g, '/');
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return;
+  if (/^(docs|\.ukit|\.claude|\.omp|\.codex|\.cache|node_modules)(\/|$)/.test(rel)) return;
+  const run = await readTextSafe(path.join(projectRoot, 'docs/AI_HANDOFF/RUN.md'));
+  const phase = (run.match(/^Phase:\s*(\S+)/im) || [])[1] || '';
+  if (!/^I[1-4]\b/i.test(phase) || !/^Command:\s*handoff-fullstack/im.test(run)) return;
+  const sid = String(payload?.session_id || '');
+  try {
+    const claims = JSON.parse(await fsp.readFile(path.join(projectRoot, '.ukit/storage/runs/claims.json'), 'utf8'))?.claims || {};
+    const now = Date.now();
+    for (const claim of Object.values(claims)) {
+      if (sid && String(claim?.owner || '') === `main:${sid}` && now - Number(claim.heartbeat) <= Number(claim.ttlMs)) return;
+    }
+  } catch {}
+  block(`${rel}: the main session may not implement handoff tasks itself while the run is in ${phase}. Dispatch a feature-implementer agent (claim-bearing), or — only when no subagent is available — take a claim first: node .claude/ukit/runtime/resumable-run.mjs claim . TASK-xxx --owner main:${sid || '<session>'}`);
+}
+await mainAgentOwnershipGate();
+
 if (toolName === 'Write' || toolName === 'Edit') {
   const filePath = String(input.file_path || '');
   if (!filePath) process.exit(0);

package/template_project/.claude/hooks/record-execution.mjs

@@ -42,12 +42,35 @@ function parsePayload(rawInput) {
   }
 }
 
+// Goal-loop claim release: the delegation guard acquired a per-task claim on PreToolUse; the
+// tool result (success OR failure) hands the task back so it is retryable/recoverable.
+// Owner-checked inside releaseTaskClaim; any error is swallowed (TTL expiry is the backstop).
+async function releaseDelegatedClaims(payload, projectRoot) {
+  try {
+    const mod = await import(pathToFileURL(path.join(MODULE_DIR, '..', 'ukit', 'runtime', 'resumable-run.mjs')).href);
+    // Lease renewal: any tool event of the owning session proves its delegated agent is alive.
+    if (typeof mod.renewSessionClaims === 'function' && payload.session_id) {
+      await mod.renewSessionClaims(projectRoot, String(payload.session_id));
+    }
+    if (payload.tool_name !== 'Agent' && payload.tool_name !== 'Task') return;
+    const owner = mod.delegatedClaimOwner(payload);
+    if (!owner) return;
+    for (const { taskId } of mod.delegatedClaimTargets(payload.tool_input)) {
+      await mod.releaseTaskClaim(projectRoot, taskId, { owner });
+    }
+  } catch { /* advisory */ }
+}
+
 // Shared advisory body for both modes. `rawInput` that fails to parse is a
 // silent pass — identical to the .sh piping garbage into `node … --record`,
 // which JSON.parse-falls back to `{}` and early-returns on the missing
 // tool_name.
 async function record({ rawInput, projectRoot, env, signal, deadlineMs }) {
   const payload = parsePayload(rawInput) ?? {};
+  await releaseDelegatedClaims(payload, projectRoot);
+  // A failed delegation never reaches PostToolUse; the claim is already handed back above and
+  // there is no successful receipt to record.
+  if (payload.hook_event_name === 'PostToolUseFailure') return { code: 0, stdout: '', stderr: '' };
   const ledgerPath = env.UKIT_EXECUTION_LEDGER_PATH || DEFAULT_LEDGER_PATH;
   let ledger;
   try {

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

@@ -1132,6 +1132,35 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     }
   }
 
+  // Reuse/reference/clone/SQL asks name an EXISTING source (function, approved page, DDL
+  // column). Live runs showed agents guessing without it (OMP: "use checknull from Core" ->
+  // `import … from 'Core'`, an invented module). Emit one bounded line per detected signal
+  // naming the deterministic resolver. Advisory only — never blocks, never throws.
+  async function emitSourceResolutionAdvisory({ promptText, commandText, skip }) {
+    try {
+      if (skip) return;
+      const registry = await loadPlaybookRegistry();
+      if (!registry || typeof registry.deriveRouteOrchestrationSignals !== 'function') return;
+      const sig = registry.deriveRouteOrchestrationSignals({ promptText, commandText });
+      const text = String(promptText || '');
+      const advice = [];
+      if (sig.reuseFirst) {
+        const named = text.match(/\buse\s+([A-Za-z_][\w.]*)\s+from\b/i)?.[1];
+        advice.push(`Reuse-first: the ask names an existing function${named ? ` ("${named}")` : ''} — resolve the REAL definition with \`node .claude/ukit/index/query-index.mjs --symbol ${named || '<name>'}\`, read its signature/semantics, import it; never invent a module or re-implement it. A needs-confirmation candidate is a lookup result, not a substitution: state which symbol you chose.`);
+      }
+      if (sig.referenceTarget || sig.cloneIntent) {
+        advice.push('Reference/clone: locate the named source page/component with `node .claude/ukit/index/resolve-context.mjs "<ask>"`, read it and its API/loader dependencies first, reuse the existing component, change only target-specific parts, and leave the reference untouched.');
+      }
+      if (sig.sqlIntent) {
+        const ids = [...new Set(text.match(/\b[a-z][a-z0-9]*(?:_[a-z0-9]+)+\b/g) || [])].slice(0, 3);
+        advice.push(`SQL: resolve the identifier in the real DDL${ids.length ? ` (${ids.map((i) => `\`query-index.mjs --symbol ${i}\``).join(', ')})` : ''}; an exact alias match is not proof of a source column — verify table/schema, never invent a column, keep the requested output alias distinct from the source column, then check dependent objects.`);
+      }
+      for (const line of advice) {
+        process.stdout.write(`[ukit-skill-router] ${line}\n`);
+      }
+    } catch {}
+  }
+
   async function readProjectPackage(projectRoot) {
     return readJson(path.join(projectRoot, 'package.json'), null);
   }
@@ -1990,6 +2019,38 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     return questionSignal || consultShape;
   }
 
+  // Greeting fast-path (parity with route-task.mjs isPureGreetingPrompt): a
+  // bare "hi" / "xin chào" / "thanks" (≤6 tokens, no command, no target) is an
+  // informational turn — no mutating lane, no task debt. Any non-greeting
+  // word ("hi, fix the login bug") disqualifies the prompt.
+  function isPureGreetingPrompt({ promptText = '', commandText = '', targetFile = null } = {}) {
+    const raw = String(promptText ?? '').trim();
+    if (!raw || String(commandText ?? '').trim() || targetFile) return false;
+    if (raw.length > 64) return false;
+    const tokens = raw.toLowerCase().normalize('NFD').replace(/[\u0300-\u036f]/g, '').replace(/\u0111/g, 'd')
+      .replace(/[^a-z0-9\s]/g, ' ').split(/\s+/).filter(Boolean);
+    if (tokens.length === 0 || tokens.length > 6) return false;
+    const core = new Set([
+      'hi', 'hello', 'hey', 'yo', 'chao', 'xin', 'good',
+      'morning', 'afternoon', 'evening',
+      'thanks', 'thank', 'cam', 'on', 'bye', 'tam', 'biet',
+    ]);
+    const filler = new Set([
+      'you', 'u', 'there', 'guys', 'everyone', 'all',
+      'ban', 'cac', 'minh', 'moi', 'nguoi', 'nhe', 'nha', 'nhieu',
+      'ok', 'okay', 'again', 'still',
+    ]);
+    let coreHit = false;
+    for (const token of tokens) {
+      if (core.has(token)) {
+        coreHit = true;
+      } else if (!filler.has(token)) {
+        return false; // any non-greeting word means this is a task wearing a greeting
+      }
+    }
+    return coreHit;
+  }
+
   // TASK-C85-019: an explicit no-change/advisory assertion overrides the signal
   // scores. A report or advisory question carrying fix vocabulary as SUBJECT
   // MATTER ("không tạo thay đổi", "giữ nguyên mã", "do not change anything",
@@ -2053,6 +2114,7 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     // — "giữ nguyên header và sửa lỗi login" keeps 'và sửa lỗi' as a surviving
     // order; an unbounded [^.,;\n]* swallows it and the order escapes the gate.
     // TAIL = lazy strip ending before 'và'/'and' (folded va|and) or EOS.
+    const MUT_VERBS = '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';
     const TAIL = '[^.,;\\n]*?(?=\\s+(?:va|and)\\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-Za-z0-9_])|[.,;]|\\s*$)';
     // C89-008: WAIT_TAIL ends a waiting-clause strip before any coordinating
     // conjunction ('và/and/nhưng/rồi/then/later/sau đó') followed by anything
@@ -2061,7 +2123,12 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     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, ' ')
+      // A negated LIST ("do not implement, fix, or refactor"; "khong implement, sua, refactor hay chinh") negates every
+    // verb in the list: the TAIL strip below stops at the first comma, which would leave the later verbs as orders.
+    .replace(new RegExp(`\\b(?:do\\s+not|don't|dont|must\\s+not|never|not|khong(?:\\s+duoc)?|tuyet\\s+doi\\s+khong)\\s+(?:${MUT_VERBS})(?![A-Za-z0-9_])(?:\\s*(?:,|,?\\s+(?:or|and|nor|hay|hoac|va))\\s*(?:(?:${MUT_VERBS})(?![A-Za-z0-9_])|(?:${MUT_VERBS})\\s))*[^.,;\\n\u2014]*?(?=\\s+(?:va|and|then|roi|nhung|but)\\s|[.,;\u2014\\n]|\\s*$)`, 'g'), ' ')
       .replace(new RegExp(`\\bgiu\\s+nguyen\\b${TAIL}`, 'g'), ' ')
       .replace(new RegExp(`\\bmuon\\s+giu\\b${TAIL}`, 'g'), ' ')
       .replace(new RegExp(`\\bkhong\\s+(?!chi\\b)${TAIL}`, 'g'), ' ')
@@ -2081,7 +2148,6 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
       .replace(new RegExp(`\\b(?:de|cho)\\s+${TAIL}`, 'g'), ' ')
       .replace(new RegExp(`\\b(?:yeu\\s+cau|doi\\s+hoi|ep\\s+phai|bat\\s+buoc|bat\\s+phai)\\b${TAIL}`, 'g'), ' ')
       .replace(new RegExp(`\\b(?:demand(?:ed|s)?|require(?:d|s)?|forcing|forced|forcibly|must|has\\s+to|have\\s+to)\\b${TAIL}`, 'g'), ' ')
-      .replace(new RegExp(`\\b(?:do\\s+not|don't|dont|not|never|no)\\s+(?!only\\b)${TAIL}`, 'g'), ' ')
       .replace(new RegExp(`\\b(?:can|nen|phai|duoc)\\s+(?:duoc\\s+)?(?:sua|cau\\s+hinh|thay\\s+doi|cap\\s+nhat|edit|fix|config)\\b${TAIL}`, 'g'), ' ')
       .replace(/\bco\s+(?:can|nen)\s+sua\b[^.,;\n?]*/g, ' ')
       .replace(/(?:^|[.,;\n]\s*)(?:should|shall)\s+(?:i|we|you)\b[^.,;\n?]*/g, ' ')
@@ -2111,6 +2177,7 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     // — "giữ nguyên header và sửa lỗi login" keeps 'và sửa lỗi' as a surviving
     // order; an unbounded [^.,;\n]* swallows it and the order escapes the gate.
     // TAIL = lazy strip ending before 'và'/'and' (folded va|and) or EOS.
+    const MUT_VERBS = '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';
     const TAIL = '[^.,;\\n]*?(?=\\s+(?:va|and)\\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-Za-z0-9_])|[.,;]|\\s*$)';
     // C89-008: WAIT_TAIL ends a waiting-clause strip before a coordinating
     // conjunction ('và/and/nhưng/rồi/then/later/sau đó') followed by anything
@@ -2118,10 +2185,15 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     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, ' ')
       .replace(/\bwrite-evidence\b|\bverification-evidence\b|\bimpact-evidence\b|\broot-cause\b/g, ' ')
+      // A negated LIST ("do not implement, fix, or refactor"; "khong implement, sua, refactor hay chinh") negates every
+    // verb in the list: the TAIL strip below stops at the first comma, which would leave the later verbs as orders.
+    .replace(new RegExp(`\\b(?:do\\s+not|don't|dont|must\\s+not|never|not|khong(?:\\s+duoc)?|tuyet\\s+doi\\s+khong)\\s+(?:${MUT_VERBS})(?![A-Za-z0-9_])(?:\\s*(?:,|,?\\s+(?:or|and|nor|hay|hoac|va))\\s*(?:(?:${MUT_VERBS})(?![A-Za-z0-9_])|(?:${MUT_VERBS})\\s))*[^.,;\\n\u2014]*?(?=\\s+(?:va|and|then|roi|nhung|but)\\s|[.,;\u2014\\n]|\\s*$)`, 'g'), ' ')
       .replace(new RegExp(`\\bgiu\\s+nguyen\\b${TAIL}`, 'g'), ' ')
       .replace(new RegExp(`\\bmuon\\s+giu\\b${TAIL}`, 'g'), ' ')
       .replace(new RegExp(`\\bkhong\\s+(?!chi\\b)${TAIL}`, 'g'), ' ')
@@ -2143,7 +2215,6 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
       .replace(new RegExp(`\\b(?:de|cho)\\s+${TAIL}`, 'g'), ' ')
       .replace(new RegExp(`\\b(?:yeu\\s+cau|doi\\s+hoi|ep\\s+phai|bat\\s+buoc|bat\\s+phai)\\b${TAIL}`, 'g'), ' ')
       .replace(new RegExp(`\\b(?:demand(?:ed|s)?|require(?:d|s)?|forcing|forced|forcibly|must|has\\s+to|have\\s+to)\\b${TAIL}`, 'g'), ' ')
-      .replace(new RegExp(`\\b(?:do\\s+not|don't|dont|not|never|no)\\s+(?!only\\b)${TAIL}`, 'g'), ' ')
       .replace(new RegExp(`\\b(?:can|nen|phai|duoc)\\s+(?:duoc\\s+)?(?:sua|cau\\s+hinh|thay\\s+doi|cap\\s+nhat|edit|fix|config)\\b${TAIL}`, 'g'), ' ')
       .replace(/\bco\s+(?:can|nen)\s+sua\b[^.,;\n?]*/g, ' ')
       .replace(/(?:^|[.,;\n]\s*)(?:should|shall)\s+(?:i|we|you)\b[^.,;\n?]*/g, ' ')
@@ -2239,6 +2310,7 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
       /\b(?:chi|just|only)\s+(?:len|lap|vach|lam)\b[^.,;\n]{0,40}\b(?:plan|ke\s+hoach|phuong\s+an|lo\s+trinh|roadmap|blueprint)\b/.test(trimmed)
       || /\b(?:len|lap|vach|de\s+xuat|draft)\s+(?:ke\s+hoach|plan|phuong\s+an|lo\s+trinh|roadmap)\b/.test(trimmed)
       || /\b(?:plan|planning)\s+(?:only|first|mode)\b/.test(trimmed)
+      || /\b(?:chi|just|only)\s+(?:tao|create|make|write|draft)\s+(?:a\s+|an\s+|1\s+|mot\s+)?(?:plan|ke\s+hoach|phuong\s+an|roadmap)\b/.test(trimmed)
       || /\b(?:ke\s+hoach|plan|phuong\s+an|lo\s+trinh|roadmap)\b[^.,;\n]{0,40}\b(?:khong|chua|khong\s+can)\s+(?:implement|code|thuc\s+hien|thuc\s+thi|sua|lam|build|viet)\b/.test(trimmed)
       || (/\b(?:khong|chua|dung)\s+(?:implement|code|thuc\s+hien|thuc\s+thi|sua|lam|viet\s+code)\b/.test(trimmed)
         && /\b(?:plan|ke\s+hoach|phuong\s+an|roadmap)\b/.test(trimmed));
@@ -3509,6 +3581,26 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
   const sessionId = sessionCandidate === undefined || sessionCandidate === null
     ? null
     : String(sessionCandidate).trim() || null;
+
+  // Per-session sidecar next to the shared single-slot state: a concurrent session routing
+  // after this one overwrites the shared file, and this session's Stop would then see a
+  // foreign owner and report its route as lost. Best-effort — the shared write is authoritative.
+  async function persistRouteState(text) {
+    await writeJsonFileAtomic(statePath, text);
+    if (!sessionId) return;
+    try {
+      const dir = path.join(projectRoot, '.ukit', 'storage', 'cache', 'route-state');
+      await writeJsonFileAtomic(path.join(dir, `${String(sessionId).replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 96) || 'default'}.json`), text);
+      if (Math.random() < 0.05) {
+        const cutoff = Date.now() - 14 * 24 * 3600 * 1000;
+        for (const name of await fsp.readdir(dir)) {
+          const file = path.join(dir, name);
+          const st = await fsp.stat(file).catch(() => null);
+          if (st && st.mtimeMs < cutoff) await fsp.rm(file, { force: true });
+        }
+      }
+    } catch {}
+  }
   const storedPrevious = await readJson(statePath, {});
   // Route state is project-local, while hook ledgers are session-local. Do not let a
   // differently-bound snapshot become the contract for a new session.
@@ -3584,6 +3676,9 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
   const previousTs = Number(previous?.ts || 0);
   const informationalNoTargetPrompt = (isInformationalPrompt({ promptText, commandText })
     || hasAdvisoryOnlyAssertion({ promptText, commandText })) && !filePath;
+  // Greeting fast-path: a pure greeting gets the same read-only stamp as an
+  // informational question — never a mutating lane, never task debt.
+  const greetingFastPath = !filePath && isPureGreetingPrompt({ promptText, commandText });
   // A delivery-only prompt ("push this to git", "đẩy bộ này lên git") starts a new,
   // mutation-free action and typically matches no skill. It must not inherit the
   // previous request's completion contract — carrying find-cause/map-impact debt
@@ -3629,7 +3724,7 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
       targetFile: filePath,
       contextIntent: '',
       taskType: '',
-      ...((informationalNoTargetPrompt || deliveryOnlyNoRoute) ? { executionMode: 'informational' } : {}),
+      ...((informationalNoTargetPrompt || deliveryOnlyNoRoute || greetingFastPath) ? { executionMode: 'informational' } : {}),
       // Read-only/carried contexts: stamp whether THIS prompt ordered a
       // mutation so the Stop gate can release a misrouted write-debt instead
       // of looping "make an Edit" on an answer-only question.
@@ -3659,12 +3754,14 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
       process.exit(0);
     }
 
+    await emitSourceResolutionAdvisory({ promptText, commandText, skip: informationalNoTargetPrompt || greetingFastPath || deliveryOnlyNoRoute });
+
     await ensureDir(statePath);
     // A no-route prompt (short nudge, informational question) must not wipe the last full
     // route: completion-gate.sh reads routeSummary/requestKey from this state to decide
     // whether a Stop is premature. Downgrading to a route-less state here silently disarms
     // the gate mid-task, so carry the previous route forward until a real route replaces it.
-    await writeJsonFileAtomic(statePath, JSON.stringify({
+    await persistRouteState(JSON.stringify({
       ...(sessionId ? { sessionId } : {}),
       fingerprint,
       ts: now,
@@ -3809,7 +3906,7 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
   };
   provisionalState.fingerprint = buildRouteStateFingerprint(provisionalState);
   await ensureDir(statePath);
-  await writeJsonFileAtomic(statePath, JSON.stringify(provisionalState));
+  await persistRouteState(JSON.stringify(provisionalState));
 
   let cacheUtils = null;
   if (await pathExists(cacheUtilsPath)) {
@@ -3882,7 +3979,7 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     }
 
     await ensureDir(statePath);
-    await writeJsonFileAtomic(statePath, JSON.stringify(reusedState));
+    await persistRouteState(JSON.stringify(reusedState));
     await appendRouteAuditEntry(routeAuditPath, buildRouteAuditEntry({
       routingContext: reusedState.routingContext || {},
       routeSummary: rescuedRouteSummary || {},
@@ -4007,7 +4104,7 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     ...(helpers ? { helpers } : {}),
     routeSummary: compactRouteSummary(routeSummary),
   };
-  await writeJsonFileAtomic(statePath, JSON.stringify(sharedState));
+  await persistRouteState(JSON.stringify(sharedState));
   await appendRouteAuditEntry(routeAuditPath, buildRouteAuditEntry({
     routingContext,
     routeSummary,
@@ -4032,6 +4129,7 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
 
   process.stdout.write(`[ukit-skill-router] Read skills: ${getActiveSkillPaths(selected).join(', ')}\n`);
   process.stdout.write(`[ukit-skill-router] Route: ${formatDisplayRouteSummary(routeSummary, routingContext)}\n`);
+  await emitSourceResolutionAdvisory({ promptText, commandText, skip: false });
   const nextDisplay = formatDisplayNextAction(routeSummary);
   if (nextDisplay) {
     process.stdout.write(`[ukit-skill-router] Next: ${nextDisplay}\n`);

package/template_project/.claude/settings.json

@@ -49,7 +49,7 @@
       "Bash(rm -rf ..:*)",
       "Bash(rm -rf .:*)",
       "Bash(dd if=/dev/:*)",
-      "Bash(*> /dev/sda:*)",
+      "Bash(*> /dev/sda*)",
       "Bash(mkfs:*)",
       "Bash(:(){ :|:& };::*)",
       "Bash(gh pr create:*)",
@@ -79,6 +79,16 @@
           }
         ]
       },
+      {
+        "matcher": "MultiEdit|NotebookEdit|Agent|Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/handoff-model-guard.sh\":8",
+            "timeout": 18
+          }
+        ]
+      },
       {
         "matcher": "Bash",
         "hooks": [
@@ -111,6 +121,16 @@
           }
         ]
       },
+      {
+        "matcher": "MultiEdit|NotebookEdit|Agent|Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/record-execution.mjs\":8",
+            "timeout": 18
+          }
+        ]
+      },
       {
         "matcher": "Bash",
         "hooks": [