@ngockhoale/ukit 2.3.9 → 2.3.10

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

@@ -544,7 +544,7 @@ const { pathToFileURL } = require('url');
     routingContext = {},
     previousContextFingerprint = null,
   }) {
-    return buildCompactMachineKey('route-v2', {
+    return buildCompactMachineKey('route-v3', {
       commandNamespace,
       indexGeneratedAtMs,
       projectFingerprint,
@@ -1577,8 +1577,10 @@ const { pathToFileURL } = require('url');
     intentMode = null,
     executionScores = {},
     executionCandidates = null,
+    signalText = '',
   } = {}) {
     const raw = `${promptText || ''}\n${commandText || ''}`.toLowerCase();
+    const signalRaw = `${raw}\n${String(signalText || '').toLowerCase()}`;
     const scores = executionScores;
     const candidates = executionCandidates ?? buildExecutionModeCandidates({
       promptText,
@@ -1591,15 +1593,45 @@ const { pathToFileURL } = require('url');
     const strongImpactLead = scores.sharedRisk
       && (scores.impactSignal || /\b(check all affected|map all affected|across all affected)\b/.test(raw));
     const boundedLocalBuildCandidate = scores.buildSignal && scores.boundedEditSignal && scores.explicitTarget && !scores.sharedRisk;
+    const releaseVerificationContinuation = /\b(?:pending\s+diff[- ]review|self-install|verify\s+(?:consistency|release)|release\s+(?:verification|readiness))\b/.test(raw)
+      && /\b(?:release|tag|publish|push|report)\b/.test(raw);
+    // A bare delivery command ("push this to git", "đẩy bộ này lên git") performs no
+    // repository mutation the ledger could ever receipt. With no edit/review/debug/
+    // build signal present, routing it to an investigation lane fabricates write debt
+    // and the completion gate then demands an edit that cannot exist. Delivery-only
+    // requests carry no completion contract instead.
+    const deliveryWordSignal = /\bgit\s+push\b/.test(signalRaw)
+      || /\bpush\b[^\n]{0,60}\b(?:git|github|gitlab|remote|origin|repo)\b/.test(signalRaw)
+      || /\b(?:git|github|gitlab|remote|origin|repo)\b[^\n]{0,60}\bpush\b/.test(signalRaw)
+      || /\bday\b(?:\s+\S+){0,3}?\s+len\b/.test(signalRaw);
+    const deliveryOnlySignal = deliveryWordSignal
+      && scores.editCertainty === 0
+      && !scores.implementSignal
+      && !scores.reviewSignal
+      && !scores.debugSignal
+      && !scores.failureSignal
+      && !scores.impactSignal
+      && !scores.buildSignal
+      && !scores.directTransformSignal
+      && !scores.smallFixSignal
+      && !scores.sharedRisk
+      && !targetFile;
 
     if (isInformationalPrompt({ promptText, commandText, scores })) {
       return 'informational';
     }
 
-    if ((intentMode === 'review-specific' || explicitReviewLead) && !scores.implementSignal) {
+    if (
+      releaseVerificationContinuation
+      || ((intentMode === 'review-specific' || explicitReviewLead) && !scores.implementSignal)
+    ) {
       return 'review-release';
     }
 
+    if (deliveryOnlySignal) {
+      return 'informational';
+    }
+
     if (strongImpactLead || (scores.blastRadius >= 3 && (scores.ambiguity >= 2 || scores.investigationNeed >= 2))) {
       return 'map-impact';
     }
@@ -1699,7 +1731,7 @@ const { pathToFileURL } = require('url');
       ),
       'map-impact': (
         (scores.sharedRisk ? 7 : 0)
-        + (scores.impactSignal ? 5 : 0)
+        + (scores.impactSignal ? 5 : -5)
         + (scores.ambiguity * 2)
         + scores.investigationNeed
       ),
@@ -2445,6 +2477,39 @@ const { pathToFileURL } = require('url');
   const debounceMs = 10 * 60 * 1000;
   const previousTs = Number(previous?.ts || 0);
   const informationalNoTargetPrompt = isInformationalPrompt({ promptText, commandText }) && !filePath;
+  // 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
+  // forward here made the Stop gate demand an edit that a push can never produce.
+  const noRouteScores = deriveExecutionScores({
+    promptText,
+    commandText,
+    targetFile: filePath,
+    intentMode,
+    taskType: '',
+  });
+  const noRouteSignalRaw = [
+    routeSignals.promptRawText || '',
+    routeSignals.promptNormalizedText || '',
+    routeSignals.commandRawText || '',
+    routeSignals.commandNormalizedText || '',
+  ].join('\n');
+  const deliveryWordSignal = /\bgit\s+push\b/.test(noRouteSignalRaw)
+    || /\bpush\b[^\n]{0,60}\b(?:git|github|gitlab|remote|origin|repo)\b/.test(noRouteSignalRaw)
+    || /\b(?:git|github|gitlab|remote|origin|repo)\b[^\n]{0,60}\bpush\b/.test(noRouteSignalRaw)
+    || /\bday\b(?:\s+\S+){0,3}?\s+len\b/.test(noRouteSignalRaw);
+  const deliveryOnlyNoRoute = deliveryWordSignal
+    && noRouteScores.editCertainty === 0
+    && !noRouteScores.implementSignal
+    && !noRouteScores.reviewSignal
+    && !noRouteScores.debugSignal
+    && !noRouteScores.failureSignal
+    && !noRouteScores.impactSignal
+    && !noRouteScores.buildSignal
+    && !noRouteScores.directTransformSignal
+    && !noRouteScores.smallFixSignal
+    && !noRouteScores.sharedRisk
+    && !filePath;
 
   if (active.length === 0 || informationalNoTargetPrompt) {
     const lastExplicitUserPromptText = promptText.trim()
@@ -2457,7 +2522,7 @@ const { pathToFileURL } = require('url');
       targetFile: filePath,
       contextIntent: '',
       taskType: '',
-      ...(informationalNoTargetPrompt ? { executionMode: 'informational' } : {}),
+      ...((informationalNoTargetPrompt || deliveryOnlyNoRoute) ? { executionMode: 'informational' } : {}),
     };
     const previousContext = buildPreviousContextSnapshot({
       projectRoot,
@@ -2494,8 +2559,8 @@ const { pathToFileURL } = require('url');
       activeSkills: [],
       routingContext: compactRoutingContext(routingContext),
       ...(previousContext ? { previousContext: compactPreviousContext(previousContext) } : {}),
-      ...(previous?.routeSummary ? { routeSummary: previous.routeSummary } : {}),
-      ...(previous?.requestKey ? { requestKey: previous.requestKey } : {}),
+      ...(previous?.routeSummary && !deliveryOnlyNoRoute ? { routeSummary: previous.routeSummary } : {}),
+      ...(previous?.requestKey && !deliveryOnlyNoRoute ? { requestKey: previous.requestKey } : {}),
     }));
     process.exit(0);
   }
@@ -2536,6 +2601,7 @@ const { pathToFileURL } = require('url');
     intentMode,
     executionScores,
     executionCandidates,
+    signalText: `${routeSignals.promptNormalizedText || ''}\n${routeSignals.commandNormalizedText || ''}`,
   });
   const lastExplicitUserPromptText = promptText.trim()
     || previous?.routingContext?.lastExplicitUserPromptText
@@ -2792,7 +2858,14 @@ const { pathToFileURL } = require('url');
 NODE
 
 if [ -f "$THRESHOLD_SCRIPT" ]; then
-  printf '%s' "$INPUT" | CLAUDE_PROJECT_DIR="$PROJECT_ROOT" node "$THRESHOLD_SCRIPT" prompt 2>/dev/null || true
+  # The 'prompt' phase only bookkeeps prompt-bearing events — a tool payload has no
+  # prompt text and that phase exits before doing anything. Every PreToolUse/
+  # PostToolUse call used to pay a second full node spawn for that no-op, doubling the
+  # per-mutation hook latency. Tool payloads always carry tool_name; skip them.
+  case "$INPUT" in
+    *'"tool_name"'*) ;;
+    *) printf '%s' "$INPUT" | CLAUDE_PROJECT_DIR="$PROJECT_ROOT" node "$THRESHOLD_SCRIPT" prompt 2>/dev/null || true ;;
+  esac
 fi
 
 exit 0

package/templates/.claude/hooks/verification-guard.sh

@@ -9,6 +9,7 @@ ROUTE_CACHE_FILE="$PROJECT_ROOT/.claude/ukit/route-cache.json"
 PROGRESS_FILE="$PROJECT_ROOT/.claude/ukit/verification-progress.json"
 
 INPUT="$INPUT" STATE_FILE="$STATE_FILE" ROUTE_CACHE_FILE="$ROUTE_CACHE_FILE" PROGRESS_FILE="$PROGRESS_FILE" node <<'NODE'
+const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
 
@@ -41,6 +42,23 @@ function sleepSync(ms) {
   Atomics.wait(new Int32Array(buffer), 0, 0, ms);
 }
 
+function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'EPERM';
+  }
+}
+
+function readLockOwner(lockPath) {
+  const owner = readJson(path.join(lockPath, 'owner'), null);
+  return owner && Number.isInteger(owner.pid) && typeof owner.token === 'string'
+    ? owner
+    : null;
+}
+
 // mkdir-based lock, protocol-compatible with runtime token-utils withFileLock. Sync on
 // purpose (see sleepSync). Fail-open after 5s: this hook must never hang a PreToolUse
 // chain, and a lost progress entry only costs one repeated advisory.
@@ -48,21 +66,37 @@ function withLockSync(lockPath, fn) {
   const staleMs = 10000;
   const maxWaitMs = 5000;
   const startedAt = Date.now();
+  const ownerToken = `${process.pid}-${crypto.randomBytes(8).toString('hex')}`;
   let held = false;
   while (!held) {
     try {
       fs.mkdirSync(path.dirname(lockPath), { recursive: true });
       fs.mkdirSync(lockPath);
+      try {
+        fs.writeFileSync(path.join(lockPath, 'owner'), JSON.stringify({
+          pid: process.pid,
+          token: ownerToken,
+          ts: Date.now(),
+        }));
+      } catch (error) {
+        try {
+          fs.rmSync(lockPath, { recursive: true, force: true });
+        } catch {}
+        throw error;
+      }
       held = true;
     } catch (error) {
       if (!error || error.code !== 'EEXIST') return fn();
       try {
         const stat = fs.statSync(lockPath);
         if (Date.now() - stat.mtimeMs > staleMs) {
-          try {
-            fs.rmSync(lockPath, { recursive: true, force: true });
-            continue;
-          } catch {}
+          const owner = readLockOwner(lockPath);
+          if (!owner || !isPidAlive(owner.pid)) {
+            try {
+              fs.rmSync(lockPath, { recursive: true, force: true });
+              continue;
+            } catch {}
+          }
         }
       } catch {}
       if (Date.now() - startedAt > maxWaitMs) break;
@@ -73,9 +107,12 @@ function withLockSync(lockPath, fn) {
     return fn();
   } finally {
     if (held) {
-      try {
-        fs.rmdirSync(lockPath);
-      } catch {}
+      const owner = readLockOwner(lockPath);
+      if (owner?.token === ownerToken) {
+        try {
+          fs.rmSync(lockPath, { recursive: true, force: true });
+        } catch {}
+      }
     }
   }
 }
@@ -288,14 +325,12 @@ function hasCompletedRecentTargetedLane({
   });
 }
 
-function deny(message) {
-  const advisory = message.replace(/^BLOCKED:/, 'ADVISORY:');
-  if (process.env.UKIT_VERIFICATION_GUARD_ENFORCE === '1') {
-    fs.writeSync(2, `${message}\n`);
-    process.exit(2);
-  }
-
-  fs.writeSync(1, `${advisory}\n`);
+function advise(message) {
+  // This hook is intentionally advisory. The executable hard gates are the completion
+  // ledger, context hard-cap, protected-file, and destructive-command guards; turning
+  // a verification-order recommendation into an exit-2 refusal gave a stale opt-in env
+  // variable a way to freeze a run before it could diagnose or land its current change.
+  fs.writeSync(1, `${message.replace(/^BLOCKED:/, 'ADVISORY:')}\n`);
   process.exit(0);
 }
 
@@ -433,31 +468,31 @@ if (isTargetedVerification) {
 }
 
 if (policyMode === 'confirm-then-broad' && isBroadTestCommand(command) && !explicitBroadRequested && !recentTargetedLaneCompleted) {
-  deny(
+  advise(
     `BLOCKED: Ask the user before broad verification. Routed policy is confirm-then-broad because the index could not localize related tests confidently.${helperCommand}`,
   );
 }
 
 if ((policyMode === 'auto-run-targeted' || policyMode === 'auto-run-targeted-then-fallback') && !isPrimaryCommand && missingPrimary.length > 0) {
-  deny(
+  advise(
     `BLOCKED: Run targeted verification first. Routed policy is ${policyMode} and the preferred first command(s) are: ${missingPrimaryText}.${helperCommand}`,
   );
 }
 
 if (policyMode === 'auto-run-targeted' && !explicitBroadRequested && !isPrimaryCommand) {
-  deny(
+  advise(
     `BLOCKED: Broader verification is not the default for this routed context. Stay with targeted verification unless the user explicitly requests a full suite. Preferred order: ${preferredText}.${helperCommand}`,
   );
 }
 
 if (policyMode === 'auto-run-targeted-then-fallback' && !explicitBroadRequested && isVerificationCommand(command) && !isPrimaryCommand && !isFallbackCommand) {
-  deny(
+  advise(
     `BLOCKED: Follow the routed verification order. This command is outside the recommended fallback lane. Preferred order: ${preferredText}.${helperCommand}`,
   );
 }
 
 if (policyMode === 'docs-light' && !explicitBroadRequested && isBroadTestCommand(command)) {
-  deny(
+  advise(
     `BLOCKED: Docs-focused change detected. Broad test runs are not the default for docs-light verification. Ask first if a full suite is still required.${helperCommand}`,
   );
 }

package/templates/.claude/ukit/index/route-task.mjs

@@ -450,6 +450,7 @@ async function prepareTaskRoute({
     intentMode,
     executionScores,
     executionCandidates,
+    signalText: buildNormalizedRouteSignalText(normalizedPrompt, normalizedCommand),
   });
   const preservedPrompt = normalizedPrompt || String(lastExplicitUserPromptText || '').trim();
   const visionInfo = await resolveVisionLane({
@@ -1749,8 +1750,10 @@ function deriveExecutionMode({
   intentMode = null,
   executionScores = {},
   executionCandidates = null,
+  signalText = '',
 } = {}) {
   const raw = `${promptText ?? ''}\n${commandText ?? ''}`.toLowerCase();
+  const signalRaw = `${raw}\n${String(signalText || '').toLowerCase()}`;
   const scores = executionScores;
   const candidates = executionCandidates ?? buildExecutionModeCandidates({
     promptText,
@@ -1760,18 +1763,48 @@ function deriveExecutionMode({
     executionScores,
   });
   const explicitReviewLead = /\b(review this|audit this|review\b.*\brelease readiness|verify\b.*\brelease readiness)\b/.test(raw);
+  const releaseVerificationContinuation = /\b(?:pending\s+diff[- ]review|self-install|verify\s+(?:consistency|release)|release\s+(?:verification|readiness))\b/.test(raw)
+    && /\b(?:release|tag|publish|push|report)\b/.test(raw);
   const strongImpactLead = scores.sharedRisk
     && (scores.impactSignal || /\b(check all affected|map all affected|across all affected)\b/.test(raw));
   const boundedLocalBuildCandidate = scores.buildSignal && scores.boundedEditSignal && scores.explicitTarget && !scores.sharedRisk;
+  // A bare delivery command ("push this to git", "đẩy bộ này lên git") performs no
+  // repository mutation the ledger could ever receipt. With no edit/review/debug/
+  // build signal present, routing it to an investigation lane fabricates write debt
+  // and the completion gate then demands an edit that cannot exist. Delivery-only
+  // requests carry no completion contract instead.
+  const deliveryWordSignal = /\bgit\s+push\b/.test(signalRaw)
+    || /\bpush\b[^\n]{0,60}\b(?:git|github|gitlab|remote|origin|repo)\b/.test(signalRaw)
+    || /\b(?:git|github|gitlab|remote|origin|repo)\b[^\n]{0,60}\bpush\b/.test(signalRaw)
+    || /\bday\b(?:\s+\S+){0,3}?\s+len\b/.test(signalRaw);
+  const deliveryOnlySignal = deliveryWordSignal
+    && scores.editCertainty === 0
+    && !scores.implementSignal
+    && !scores.reviewSignal
+    && !scores.debugSignal
+    && !scores.failureSignal
+    && !scores.impactSignal
+    && !scores.buildSignal
+    && !scores.directTransformSignal
+    && !scores.smallFixSignal
+    && !scores.sharedRisk
+    && !targetFile;
 
   if (isInformationalPrompt({ promptText, commandText, scores })) {
     return 'informational';
   }
 
-  if ((intentMode === 'review-specific' || explicitReviewLead) && !scores.implementSignal) {
+  if (
+    releaseVerificationContinuation
+    || ((intentMode === 'review-specific' || explicitReviewLead) && !scores.implementSignal)
+  ) {
     return 'review-release';
   }
 
+  if (deliveryOnlySignal) {
+    return 'informational';
+  }
+
   if (strongImpactLead || (scores.blastRadius >= 3 && (scores.ambiguity >= 2 || scores.investigationNeed >= 2))) {
     return 'map-impact';
   }
@@ -1871,7 +1904,7 @@ function buildExecutionModeCandidates({
     ),
     'map-impact': (
       (scores.sharedRisk ? 7 : 0)
-      + (scores.impactSignal ? 5 : 0)
+      + (scores.impactSignal ? 5 : -5)
       + (scores.ambiguity * 2)
       + scores.investigationNeed
     ),
@@ -2784,7 +2817,7 @@ function buildRouteRequestKey({
   previousContextSnapshot = null,
   recentOutputSnapshot = null,
 } = {}) {
-  return buildCompactMachineKey('route-v2', {
+  return buildCompactMachineKey('route-v3', {
     commandNamespace,
     indexGeneratedAtMs,
     projectFingerprint,

package/templates/.claude/ukit/runtime/compact-threshold.mjs

@@ -499,6 +499,21 @@ export function resetCompactPressureState(rawState = {}, config = {}) {
 }
 
 const BOUNDARY_TAIL_BYTES = 4 * 1024 * 1024;
+// Hook processes are short-lived, so an in-memory cache would not stop every Edit/Write
+// from reopening and parsing a 4MB transcript tail. Persist a very short probe window in
+// the session pressure record instead: a burst of mutations incurs one scan, not one per
+// call. PreCompact is still immediate; this is only the fallback for host auto-compactions
+// that skip PreCompact, where a two-second detection delay is preferable to killing the
+// 4s hook budget on a slow volume.
+const TRANSCRIPT_BOUNDARY_PROBE_TTL_MS = 2_000;
+
+function normalizeTranscriptProbe(value) {
+  if (!value || typeof value !== 'object' || typeof value.path !== 'string' || !value.path) return null;
+  const checkedAt = finiteNumber(value.checkedAt, 0);
+  return checkedAt > 0
+    ? { path: value.path, checkedAt, boundaryAt: finiteNumber(value.boundaryAt, 0) }
+    : null;
+}
 
 // Find the newest compaction recorded in the session transcript, as epoch ms (0 if none).
 // Every real compaction — manual /compact AND harness auto-compact — appends a
@@ -551,18 +566,46 @@ export async function detectLatestCompactBoundaryAt(transcriptPath, { tailBytes
 // history that was already summarised away and the hard-cap gate bricks a healthy
 // session. Callers must persist when reset=true, or the reset would re-fire (and
 // zero the counter) on every call.
-export async function syncCompactPressureStateWithTranscript(rawState = null, config = {}, transcriptPath = '') {
-  const boundaryAt = await detectLatestCompactBoundaryAt(transcriptPath);
+export async function syncCompactPressureStateWithTranscript(
+  rawState = null,
+  config = {},
+  transcriptPath = '',
+  { now = Date.now(), probeTtlMs = TRANSCRIPT_BOUNDARY_PROBE_TTL_MS } = {},
+) {
+  const normalizedPath = typeof transcriptPath === 'string' ? transcriptPath.trim() : '';
+  const previousProbe = normalizeTranscriptProbe(rawState?.transcriptBoundaryProbe);
+  // A process-persistent, session-scoped cache avoids rereading/parsing up to 4MB for every
+  // mutation during a tool burst. It keys on the path (not just time) so a resumed/new
+  // transcript always scans immediately. The short TTL is deliberately only a performance
+  // coalescing window; PreCompact remains the immediate source of truth.
+  const probeFresh = previousProbe
+    && previousProbe.path === normalizedPath
+    && now - previousProbe.checkedAt >= 0
+    && now - previousProbe.checkedAt < probeTtlMs;
+  const boundaryAt = probeFresh
+    ? previousProbe.boundaryAt
+    : await detectLatestCompactBoundaryAt(normalizedPath);
+  const probe = probeFresh
+    ? previousProbe
+    : { path: normalizedPath, checkedAt: now, boundaryAt };
   const accounted = finiteNumber(rawState?.lastCompactBoundaryAt, 0);
   if (!boundaryAt || boundaryAt <= accounted) {
-    return { state: rawState, reset: false };
+    return {
+      state: rawState && typeof rawState === 'object'
+        ? { ...rawState, transcriptBoundaryProbe: probe }
+        : rawState,
+      reset: false,
+      probed: !probeFresh,
+    };
   }
   return {
     state: {
       ...resetCompactPressureState(rawState ?? {}, config),
       lastCompactBoundaryAt: boundaryAt,
+      transcriptBoundaryProbe: probe,
     },
     reset: true,
+    probed: !probeFresh,
   };
 }
 
@@ -795,6 +838,7 @@ export function buildCompactPressureState(rawState = null, config = {}) {
     taskMode,
     cooldownUntil: finiteNumber(rawState?.cooldownUntil, 0),
     lastCompactBoundaryAt: finiteNumber(rawState?.lastCompactBoundaryAt, 0),
+    transcriptBoundaryProbe: normalizeTranscriptProbe(rawState?.transcriptBoundaryProbe),
     routingContext: rawState?.routingContext && typeof rawState.routingContext === 'object'
       ? rawState.routingContext
       : {},
@@ -1260,7 +1304,9 @@ async function runCli() {
         sessionConfig,
         payload.transcript_path,
       );
-      if (synced.reset) {
+      if (synced.reset || synced.probed) {
+        // Persist a clean probe too: this CLI runs in a fresh process on each hook,
+        // so retaining only resets would make every prompt rescan the same tail.
         await writeCompactPressureState(projectRoot, synced.state, sessionConfig);
       }
     } catch { /* advisory healing only — never block the prompt over it */ }