@ngockhoale/ukit 1.1.6

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

@@ -0,0 +1,271 @@
+#!/bin/bash
+# PreToolUse hook: enforce routed verification execution policy so AI stays index-first
+# and does not jump to blanket verification when targeted evidence already exists.
+
+INPUT=$(cat)
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+STATE_FILE="$PROJECT_ROOT/.claude/ukit/skill-router-state.json"
+PROGRESS_FILE="$PROJECT_ROOT/.claude/ukit/verification-progress.json"
+
+INPUT="$INPUT" STATE_FILE="$STATE_FILE" PROGRESS_FILE="$PROGRESS_FILE" node <<'NODE'
+const fs = require('fs');
+const path = require('path');
+
+function readJson(filePath, fallback = null) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(value));
+}
+
+function normalizeCommand(value) {
+  return String(value || '').trim().replace(/\s+/g, ' ');
+}
+
+function unique(values) {
+  return [...new Set(values.filter(Boolean))];
+}
+
+function formatCompactCommandList(values, {
+  limit = 2,
+  separator = ' | ',
+  empty = 'none',
+} = {}) {
+  const normalized = unique((values || []).map(normalizeCommand).filter(Boolean));
+  if (normalized.length === 0) {
+    return empty;
+  }
+
+  const shown = normalized.slice(0, limit);
+  const remaining = normalized.length - shown.length;
+  return remaining > 0
+    ? `${shown.join(separator)}${separator}+${remaining} more`
+    : shown.join(separator);
+}
+
+function stripShellQuotes(value) {
+  return String(value || '').replace(/^['"]|['"]$/g, '');
+}
+
+function compactHelperHint(command) {
+  if (typeof command !== 'string' || !command.trim()) return '';
+
+  const normalized = command.trim().replace(/\s+/g, ' ');
+  const scriptMatch = normalized.match(/^node\s+([^\s]+)(?:\s+(.*))?$/i);
+  if (!scriptMatch) return normalized.length > 96 ? normalized.slice(0, 93) + '...' : normalized;
+
+  const scriptName = scriptMatch[1].split('/').pop() || scriptMatch[1];
+  const rest = scriptMatch[2] || '';
+  const targetMatch = rest.match(/--target\s+("[^"]+"|'[^']+'|\S+)/);
+  const typeMatch = rest.match(/--type\s+(\S+)/);
+  const parts = [scriptName];
+  if (targetMatch) parts.push('target=' + stripShellQuotes(targetMatch[1]));
+  if (typeMatch) parts.push('type=' + typeMatch[1]);
+  return parts.join(' ');
+}
+
+function looksTargetedTestCommand(command) {
+  return (
+    /\.(test|spec)\.[a-z0-9]+/i.test(command)
+    || /(^|\s)(tests?|specs?)\//i.test(command)
+    || /(--runTestsByPath|--testPathPattern|--grep|--filter)\b/i.test(command)
+  );
+}
+
+function isBroadTestCommand(command) {
+  if (!command) return false;
+  if (looksTargetedTestCommand(command)) return false;
+  return [
+    /^yarn test(?:\s|$)/i,
+    /^pnpm test(?:\s|$)/i,
+    /^bun test(?:\s|$)/i,
+    /^npm test(?:\s|$)/i,
+    /^npm run test(?:\s|$)/i,
+    /^vitest(?:\s|$)/i,
+    /^npx vitest(?:\s|$)/i,
+    /^jest(?:\s|$)/i,
+    /^npx jest(?:\s|$)/i,
+  ].some((pattern) => pattern.test(command));
+}
+
+function isVerificationCommand(command) {
+  if (!command) return false;
+  if (isBroadTestCommand(command) || looksTargetedTestCommand(command)) return true;
+  return [
+    /^yarn lint(?:\s|$)/i,
+    /^pnpm lint(?:\s|$)/i,
+    /^bun lint(?:\s|$)/i,
+    /^npm run lint(?:\s|$)/i,
+    /^yarn typecheck(?:\s|$)/i,
+    /^pnpm typecheck(?:\s|$)/i,
+    /^bun typecheck(?:\s|$)/i,
+    /^npm run typecheck(?:\s|$)/i,
+    /^tsc(?:\s|$)/i,
+  ].some((pattern) => pattern.test(command));
+}
+
+function isExplicitBroadVerificationRequest(promptText) {
+  const text = String(promptText || '').toLowerCase();
+  return [
+    /run (the )?full test suite/,
+    /run all tests/,
+    /full verification/,
+    /verify everything/,
+    /run the whole suite/,
+    /run broad verification/,
+    /full suite/,
+    /chạy (?:toàn bộ|full) test/,
+    /chạy hết test/,
+    /chạy full test suite/,
+    /verify toàn bộ/,
+    /kiểm tra toàn bộ/,
+  ].some((pattern) => pattern.test(text));
+}
+
+function deny(message) {
+  process.stderr.write(`${message}\n`);
+  process.exit(2);
+}
+
+const payload = (() => {
+  try {
+    return JSON.parse(process.env.INPUT || '{}');
+  } catch {
+    return {};
+  }
+})();
+const command = normalizeCommand(payload?.tool_input?.command || payload?.command || '');
+if (!command) {
+  process.exit(0);
+}
+
+const statePath = process.env.STATE_FILE;
+const progressPath = process.env.PROGRESS_FILE;
+const state = readJson(statePath, null);
+const recommendation = state?.verificationRecommendation ?? null;
+const routeSummary = state?.routeSummary ?? null;
+const helpers = state?.helpers ?? null;
+const policy = recommendation?.executionPolicy ?? null;
+const policyMode = routeSummary?.policyMode ?? policy?.policyMode ?? null;
+const stateAgeMs = typeof state?.ts === 'number' ? Date.now() - state.ts : Infinity;
+const STATE_FRESH_MS = 30 * 60 * 1000; // 30 minutes
+
+if (!recommendation && !routeSummary) {
+  process.exit(0);
+}
+
+// Stale state — do not enforce policy from old route context
+// Only apply when ts is explicitly present (current state format)
+if (typeof state?.ts === 'number' && stateAgeMs > STATE_FRESH_MS) {
+  process.exit(0);
+}
+
+const primaryCommands = unique((
+  routeSummary?.primaryCommands?.length
+    ? routeSummary.primaryCommands
+    : recommendation?.commands ?? (
+      routeSummary?.nextActionType === 'run-primary-verification'
+        ? [routeSummary.nextActionCommand]
+        : []
+    )
+).map(normalizeCommand));
+const fallbackCommands = unique((
+  routeSummary?.fallbackCommands?.length
+    ? routeSummary.fallbackCommands
+    : recommendation?.fallbackCommands ?? (
+      routeSummary?.nextActionType === 'run-fallback-verification'
+        ? [routeSummary.nextActionCommand]
+        : []
+    )
+).map(normalizeCommand));
+const preferredOrder = unique((
+  routeSummary?.preferredOrder?.length
+    ? routeSummary.preferredOrder
+    : policy?.preferredOrder ?? [...primaryCommands, ...fallbackCommands]
+).map(normalizeCommand));
+
+if (!policyMode && primaryCommands.length === 0 && fallbackCommands.length === 0) {
+  process.exit(0);
+}
+
+const progress = readJson(progressPath, {});
+const normalizedProgress = progress?.fingerprint === state?.fingerprint
+  ? progress
+  : { fingerprint: state?.fingerprint || null, attemptedCommands: [] };
+const attemptedCommands = new Set((normalizedProgress.attemptedCommands ?? []).map(normalizeCommand));
+
+function persistAttempt(commandText) {
+  attemptedCommands.add(commandText);
+  writeJson(progressPath, {
+    fingerprint: state?.fingerprint || null,
+    attemptedCommands: [...attemptedCommands],
+  });
+}
+
+const isPrimaryCommand = primaryCommands.includes(command);
+const explicitBroadRequested = isExplicitBroadVerificationRequest(
+  state?.routingContext?.lastExplicitUserPromptText || state?.routingContext?.promptText || '',
+);
+const isFallbackCommand = fallbackCommands.includes(command);
+if (!isPrimaryCommand && !isFallbackCommand && !isVerificationCommand(command)) {
+  process.exit(0);
+}
+
+const helperSource = routeSummary?.helperHint
+  || helpers?.verificationHelperHint
+  || compactHelperHint(recommendation?.helperCommand || '')
+  || '';
+const helperCommand = helperSource ? ` Helper: ${helperSource}` : '';
+const missingPrimary = primaryCommands.filter((item) => !attemptedCommands.has(item));
+const preferredText = formatCompactCommandList(preferredOrder, { separator: ' -> ' });
+const missingPrimaryText = formatCompactCommandList(missingPrimary);
+
+if (policyMode === 'confirm-then-broad' && !explicitBroadRequested) {
+  deny(
+    `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(
+    `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(
+    `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(
+    `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(
+    `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}`,
+  );
+}
+
+if (isPrimaryCommand) {
+  persistAttempt(command);
+  process.exit(0);
+}
+
+if (isFallbackCommand || isVerificationCommand(command)) {
+  persistAttempt(command);
+}
+
+process.exit(0);
+NODE
+
+exit $?

package/templates/.claude/settings.json

@@ -0,0 +1,144 @@
+{
+  "fastMode": true,
+  "fastModePerSessionOptIn": false,
+  "alwaysThinkingEnabled": true,
+  "effortLevel": "high",
+  "includeGitInstructions": false,
+  "promptSuggestionEnabled": false,
+  "showThinkingSummaries": false,
+  "spinnerTipsEnabled": false,
+  "defaultView": "chat",
+  "permissions": {
+    "defaultMode": "bypassPermissions",
+    "allow": [
+      "Read",
+      "Glob",
+      "Grep",
+      "Edit",
+      "Write",
+      "TodoWrite",
+      "TaskOutput",
+      "Bash(ls:*)",
+      "Bash(node:*)",
+      "Bash(yarn:*)",
+      "Bash(corepack yarn:*)",
+      "Bash(git status:*)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(jq:*)"
+    ],
+    "ask": [
+      "Bash(git push:*)",
+      "Bash(gh pr create:*)",
+      "Bash(gh pr comment:*)",
+      "Bash(gh issue comment:*)"
+    ],
+    "deny": [
+      "Bash(git reset --hard:*)",
+      "Bash(git push --force:*)",
+      "Bash(git push --force-with-lease:*)",
+      "Bash(rm -rf /:*)",
+      "Bash(rm -rf ~:*)",
+      "Bash(rm -rf ..:*)"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Read|Grep|Glob",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-router.sh\"",
+            "timeout": 8
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/protect-files.sh\"",
+            "timeout": 8
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-router.sh\"",
+            "timeout": 8
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/verification-guard.sh\"",
+            "timeout": 8
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/auto-allow-bash.sh\"",
+            "timeout": 8
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-router.sh\"",
+            "timeout": 8
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/block-dangerous.sh\"",
+            "timeout": 8
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/compress-output.sh\"",
+            "timeout": 8
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-router.sh\"",
+            "timeout": 8
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/reinject-context.sh\"",
+            "timeout": 8
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/auto-prune-bash.sh\"",
+            "timeout": 8
+          }
+        ]
+      }
+    ]
+  }
+}