@ngockhoale/ukit 1.1.6 → 1.1.8

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

@@ -5,9 +5,10 @@
 INPUT=$(cat)
 PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
 STATE_FILE="$PROJECT_ROOT/.claude/ukit/skill-router-state.json"
+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" PROGRESS_FILE="$PROGRESS_FILE" node <<'NODE'
+INPUT="$INPUT" STATE_FILE="$STATE_FILE" ROUTE_CACHE_FILE="$ROUTE_CACHE_FILE" PROGRESS_FILE="$PROGRESS_FILE" node <<'NODE'
 const fs = require('fs');
 const path = require('path');
 
@@ -125,12 +126,122 @@ function isExplicitBroadVerificationRequest(promptText) {
     /chạy full test suite/,
     /verify toàn bộ/,
     /kiểm tra toàn bộ/,
+    // Plan-driven execution prompts often authorize the plan's final broad
+    // verification without spelling it as "full test suite".
+    /(?:run|execute|implement|do)\b.*\bfull\b.*\b(?:prd\s+)?plan\b/,
+    /\bfull\b.*\b(?:prd\s+)?plan\b.*\b(?:verify|verification|test|tests)\b/,
+    /(?:chạy|lam|làm|thực hiện|triển khai)\b.*\bfull\b.*\b(?:prd|plan|ke hoach|kế hoạch)\b/,
+    /\bfull\b.*\b(?:prd|plan|ke hoach|kế hoạch)\b.*\b(?:verify|verification|test|tests|kiểm tra)\b/,
   ].some((pattern) => pattern.test(text));
 }
 
+function collectRecentPromptTexts(state, routeCache, maxAgeMs) {
+  const prompts = [
+    state?.routingContext?.lastExplicitUserPromptText,
+    state?.routingContext?.promptText,
+  ];
+  const now = Date.now();
+
+  for (const entry of routeCache?.entries ?? []) {
+    const updatedAt = Number(entry?.updatedAt ?? entry?.ts ?? 0);
+    if (Number.isFinite(updatedAt) && updatedAt > 0 && now - updatedAt > maxAgeMs) {
+      continue;
+    }
+    prompts.push(
+      entry?.routingContext?.lastExplicitUserPromptText,
+      entry?.routingContext?.promptText,
+    );
+  }
+
+  return unique(prompts.map((prompt) => String(prompt || '').trim()).filter(Boolean));
+}
+
+function hasRecentExplicitBroadVerificationRequest(state, routeCache, maxAgeMs) {
+  return collectRecentPromptTexts(state, routeCache, maxAgeMs)
+    .some((promptText) => isExplicitBroadVerificationRequest(promptText));
+}
+
+function collectRecentRouteSummaries(routeCache, maxAgeMs) {
+  const now = Date.now();
+  const summaries = [];
+
+  for (const entry of routeCache?.entries ?? []) {
+    const updatedAt = Number(entry?.updatedAt ?? entry?.ts ?? 0);
+    if (Number.isFinite(updatedAt) && updatedAt > 0 && now - updatedAt > maxAgeMs) {
+      continue;
+    }
+    if (entry?.routeSummary && typeof entry.routeSummary === 'object') {
+      summaries.push(entry.routeSummary);
+    }
+  }
+
+  return summaries;
+}
+
+function collectAttemptedCommands(progress, {
+  currentFingerprint = null,
+  maxAgeMs,
+} = {}) {
+  const now = Date.now();
+  const attempted = [];
+  const progressUpdatedAt = Number(progress?.updatedAt ?? 0);
+  const legacyProgressIsFresh = Number.isFinite(progressUpdatedAt)
+    && progressUpdatedAt > 0
+    && now - progressUpdatedAt <= maxAgeMs;
+
+  if (progress?.fingerprint === currentFingerprint || legacyProgressIsFresh) {
+    attempted.push(...(progress?.attemptedCommands ?? []));
+  }
+
+  for (const entry of progress?.recentAttempts ?? []) {
+    const ts = Number(entry?.ts ?? 0);
+    if (Number.isFinite(ts) && ts > 0 && now - ts <= maxAgeMs) {
+      attempted.push(entry.command);
+    }
+  }
+
+  return new Set(attempted.map(normalizeCommand).filter(Boolean));
+}
+
+function hasCompletedRecentTargetedLane({
+  routeCache,
+  attemptedCommands,
+  command,
+  maxAgeMs,
+} = {}) {
+  const normalizedCommand = normalizeCommand(command);
+  if (!isBroadTestCommand(normalizedCommand)) {
+    return false;
+  }
+
+  return collectRecentRouteSummaries(routeCache, maxAgeMs).some((summary) => {
+    const mode = summary?.policyMode;
+    if (mode !== 'auto-run-targeted' && mode !== 'auto-run-targeted-then-fallback') {
+      return false;
+    }
+
+    const recentPrimary = unique((summary?.primaryCommands ?? []).map(normalizeCommand));
+    if (recentPrimary.length === 0 || !recentPrimary.every((item) => attemptedCommands.has(item))) {
+      return false;
+    }
+
+    const recentFallbacks = unique((summary?.fallbackCommands ?? []).map(normalizeCommand));
+    const recentPreferred = unique((summary?.preferredOrder ?? []).map(normalizeCommand));
+    return recentFallbacks.includes(normalizedCommand)
+      || recentPreferred.includes(normalizedCommand)
+      || recentPrimary.includes(normalizedCommand);
+  });
+}
+
 function deny(message) {
-  process.stderr.write(`${message}\n`);
-  process.exit(2);
+  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`);
+  process.exit(0);
 }
 
 const payload = (() => {
@@ -148,6 +259,7 @@ if (!command) {
 const statePath = process.env.STATE_FILE;
 const progressPath = process.env.PROGRESS_FILE;
 const state = readJson(statePath, null);
+const routeCache = readJson(process.env.ROUTE_CACHE_FILE, null);
 const recommendation = state?.verificationRecommendation ?? null;
 const routeSummary = state?.routeSummary ?? null;
 const helpers = state?.helpers ?? null;
@@ -195,24 +307,39 @@ if (!policyMode && primaryCommands.length === 0 && fallbackCommands.length === 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));
+const attemptedCommands = collectAttemptedCommands(progress, {
+  currentFingerprint: state?.fingerprint || null,
+  maxAgeMs: STATE_FRESH_MS,
+});
 
 function persistAttempt(commandText) {
-  attemptedCommands.add(commandText);
+  const normalizedCommandText = normalizeCommand(commandText);
+  attemptedCommands.add(normalizedCommandText);
+  const now = Date.now();
+  const recentAttempts = [
+    ...(progress?.recentAttempts ?? []),
+    { command: normalizedCommandText, ts: now },
+  ]
+    .map((entry) => ({
+      command: normalizeCommand(entry?.command),
+      ts: Number(entry?.ts ?? now),
+    }))
+    .filter((entry) => entry.command && Number.isFinite(entry.ts) && now - entry.ts <= STATE_FRESH_MS)
+    .filter((entry, index, list) => (
+      list.findLastIndex((candidate) => candidate.command === entry.command) === index
+    ));
   writeJson(progressPath, {
     fingerprint: state?.fingerprint || null,
+    updatedAt: now,
     attemptedCommands: [...attemptedCommands],
+    recentAttempts,
   });
 }
 
 const isPrimaryCommand = primaryCommands.includes(command);
-const explicitBroadRequested = isExplicitBroadVerificationRequest(
-  state?.routingContext?.lastExplicitUserPromptText || state?.routingContext?.promptText || '',
-);
+const explicitBroadRequested = hasRecentExplicitBroadVerificationRequest(state, routeCache, STATE_FRESH_MS);
 const isFallbackCommand = fallbackCommands.includes(command);
+const isTargetedVerification = looksTargetedTestCommand(command);
 if (!isPrimaryCommand && !isFallbackCommand && !isVerificationCommand(command)) {
   process.exit(0);
 }
@@ -223,10 +350,21 @@ const helperSource = routeSummary?.helperHint
   || '';
 const helperCommand = helperSource ? ` Helper: ${helperSource}` : '';
 const missingPrimary = primaryCommands.filter((item) => !attemptedCommands.has(item));
+const recentTargetedLaneCompleted = hasCompletedRecentTargetedLane({
+  routeCache,
+  attemptedCommands,
+  command,
+  maxAgeMs: STATE_FRESH_MS,
+});
 const preferredText = formatCompactCommandList(preferredOrder, { separator: ' -> ' });
 const missingPrimaryText = formatCompactCommandList(missingPrimary);
 
-if (policyMode === 'confirm-then-broad' && !explicitBroadRequested) {
+if (isTargetedVerification) {
+  persistAttempt(command);
+  process.exit(0);
+}
+
+if (policyMode === 'confirm-then-broad' && isBroadTestCommand(command) && !explicitBroadRequested && !recentTargetedLaneCompleted) {
   deny(
     `BLOCKED: Ask the user before broad verification. Routed policy is confirm-then-broad because the index could not localize related tests confidently.${helperCommand}`,
   );

package/templates/.claude/skills/docs-quality/SKILL.md

@@ -61,7 +61,7 @@ Docs should **not** become:
 
 - update README / docs after code changes
 - fix source-vs-doc drift
-- improve `docs/PROJECT.md`, `docs/MEMORY.md`, `docs/WORKLOG.md`, `docs/CODE_MAP.md`
+- improve `docs/PROJECT.md`, `docs/MEMORY.md`, `docs/STATUS.md`, `docs/WORKLOG.md`, `docs/CODE_MAP.md`
 - prepare durable handoff notes
 - tighten or remove stale setup instructions
 - document newly discovered module boundaries, dangerous areas, or bug patterns
@@ -97,6 +97,14 @@ Use for durable knowledge:
 
 Prefer short entries that future sessions can scan in seconds.
 
+#### `docs/STATUS.md`
+Use for compact current state:
+- current focus / active work
+- live debug threads, blockers, and verification status
+- next candidates for open-ended continuation
+
+Do **not** treat it as source truth or duplicate full session history here.
+
 #### `docs/WORKLOG.md`
 Use for session-level execution history:
 - what changed

package/templates/.claude/skills/next-step/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: next-step
+description: Use when the user asks what to do next, asks for project status, says continue/làm tiếp without a concrete target, or needs a lightweight session-start orientation from docs/STATUS.md. Do not use as the primary skill for concrete debug, implementation, review, or docs tasks.
+---
+
+# Next Step
+
+## Purpose
+
+Suggest the next useful project action without scanning the whole repository.
+
+This skill is for open-ended continuity prompts such as:
+- "what next?", "project status?", "where are we?"
+- "continue", "continue from last session"
+- "làm gì tiếp?", "làm tiếp", "project đang ở đâu?"
+
+It is **not** a replacement for concrete workflows. If the user names a bug, feature, file, test, PR, or review target, keep the concrete workflow primary and use this skill only as background if useful.
+
+## Hard Guardrails
+
+- End users should not need to know this skill name.
+- Do not ask users to run a `next-step` command. The human workflow remains `ukit install` + natural language.
+- `docs/STATUS.md` is orientation, not truth. Source code, tests, and the UKit index win.
+- Concrete task beats open-ended wording. Example: "I'm fixing login bug but unsure next step" is a debug approach question, not a global roadmap request.
+- Do not scan the whole repo unless `docs/STATUS.md` is missing/stale and the user still wants project-level direction.
+
+## Freshness Check
+
+Before relying on status content, check both:
+1. filesystem modified time for `docs/STATUS.md` (fallback: root `STATUS.md` if present)
+2. the `Last meaningful update` field inside the file
+
+Use this cue in your response:
+
+- 🟢 fresh: modified within 24h
+- 🟡 possibly stale: 24-72h old
+- 🔴 stale: older than 72h
+- ⚪ missing: no status file yet
+
+If stale or missing, downgrade confidence and verify with the smallest current tree/index/context signal before recommending work.
+
+## Input Order
+
+Read only what is needed:
+1. `docs/STATUS.md` (or existing root `STATUS.md` fallback)
+2. `docs/CODE_MAP.md` only when navigation is needed
+3. `docs/MEMORY.md` only when constraints/decisions affect the suggestion
+4. routed index/tree summary only if status is stale, missing, or contradicted
+
+## Output Shape
+
+Keep output compact:
+
+```md
+STATUS freshness: 🟡 possibly stale
+- last modified: YYYY-MM-DD HH:mm
+- confidence: medium-low
+
+Suggested next steps:
+1. Candidate — why now — likely files — verification — risk
+2. Candidate — why now — likely files — verification — risk
+
+Recommended: ...
+Why: ...
+First check: ...
+```
+
+## Intent Handling
+
+- `open-ended-status`: read status and suggest 1-3 candidates.
+- `continue-existing-work`: prefer Active Work / Current Debug Threads, then Next Candidates.
+- `scoped-advice`: do not produce a global roadmap; hand off to the concrete skill and suggest the immediate approach only.
+- `debug-specific`, `implement-specific`, `review-specific`: do not use this skill as primary.
+
+## Missing or Stale Status
+
+If missing, suggest creating/updating `docs/STATUS.md` after the current task, but do not block the user.
+If stale, say so visibly and treat old Next Candidates as hypotheses, not fact.

package/templates/.claude/skills/update-status/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: update-status
+description: Use near the end of a meaningful session or explicit handoff/status request to update docs/STATUS.md with compact current state, verification, blockers, and next candidates. Skip trivial/no-state-change tasks.
+---
+
+# Update Status
+
+## Purpose
+
+Keep `docs/STATUS.md` useful as a compact living state document for future AI sessions.
+
+This skill should run when:
+- the user explicitly asks to update status / handoff / wrap up
+- meaningful source/docs/tests/package state changed
+- a task is paused, blocked, completed, or has a new verified next action
+- a bug root cause, verification result, or durable blocker was discovered
+
+Do **not** run for trivial typo-only edits, pure Q&A, or exploration with no durable finding.
+
+## Hard Guardrails
+
+- End users should not need to know this skill name.
+- Do not ask users to run a `update-status` command. The human workflow remains `ukit install` + natural language.
+- Keep `docs/STATUS.md` compact. It is not `docs/WORKLOG.md` and not a raw session transcript.
+- Source code and tests are truth. If status conflicts with source, update status to match source or mark uncertainty.
+- Do not invent verification. Record only commands actually run and their outcome.
+- Preserve user edits and rewrite the smallest relevant section.
+
+## Update Decision
+
+Before editing, ask internally:
+
+1. Did project state actually change?
+2. Is any work still active/blocked?
+3. Was a root cause, decision, blocker, or next action confirmed?
+4. What verification ran?
+5. Will future sessions be faster if this is recorded?
+
+If all answers are no, skip the update and mention that no status change was needed.
+
+## Freshness Fields
+
+When updating meaningful state, update the header:
+
+```md
+## Freshness
+
+- Last meaningful update: YYYY-MM-DD HH:mm
+- Updated by: Claude / Codex / OpenCode / human
+- Status confidence: high / medium / low
+- Stale after: 72h
+```
+
+Confidence guide:
+- `high`: implementation/fix verified by targeted tests or stronger
+- `medium`: state changed but verification was partial or docs-only
+- `low`: investigation/hypothesis only, blocked, or stale recovery
+
+## Section Rules
+
+- `Snapshot`: only current focus, health, branch/state, release/version.
+- `Active Work`: only live unfinished work.
+- `Current Debug Threads`: compact bug state; detailed context should link to future `docs/context/<slug>.md` files when available.
+- `Decisions Pending`: unresolved choices only.
+- `Next Candidates`: max 3-5 actionable candidates.
+- `Recently Completed`: max 10 compact lines; detailed session history belongs in `docs/WORKLOG.md`.
+
+## What to Record
+
+Prefer concrete bullets:
+
+- files changed or likely involved
+- verification commands and pass/fail/blocked result
+- current blocker
+- next action that can be started immediately
+- uncertainty labels (`unknown`, `unverified`, `suspected`) when needed
+
+Avoid:
+
+- raw command output
+- every file opened/read
+- speculative TODO spam
+- duplicate history already better suited for WORKLOG
+- global roadmap changes caused by a concrete one-file task
+
+## Future Context Note
+
+Do not create task-scoped `CONTEXT.md` as part of v1.1.8 unless the project already has that convention. If detailed bug/feature context is needed, note it as a v1.2 candidate or link to an existing `docs/context/<slug>.md` file.

package/templates/.claude/ukit/index/impact-context.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import * as indexCore from './lib/index-core.mjs';
+
+const {
+  buildCodeIndex,
+  DEFAULT_INDEX_CACHE_MAX_AGE_MS,
+  getIndexArtifactGeneratedAt,
+  isIndexStale,
+} = indexCore;
+
+const resolveImpactContext = typeof indexCore.resolveImpactContext === 'function'
+  ? indexCore.resolveImpactContext
+  : null;
+const formatImpactConfidenceSummary = typeof indexCore.formatImpactConfidenceSummary === 'function'
+  ? indexCore.formatImpactConfidenceSummary
+  : null;
+
+const CALLEE_CAP = 5;
+const CALLER_CAP = 5;
+const MIRROR_CAP = 3;
+const TEST_CAP = 4;
+const VERIFY_CAP = 3;
+
+async function main() {
+  const args = process.argv.slice(2);
+  const rootDir = getRootDir(args);
+  const changedFiles = parseCsv(readFlagValue(args, '--changed'));
+  const changedSymbols = parseCsv(readFlagValue(args, '--symbol'));
+
+  if (changedFiles.length === 0) {
+    console.error('Usage: node .claude/ukit/index/impact-context.mjs --changed <file[,file]> [--symbol <name[,name]>] [--root <dir>]');
+    process.exitCode = 1;
+    return;
+  }
+
+  await ensureFreshIndex(rootDir);
+
+  const impact = resolveImpactContext
+    ? await resolveImpactContext({ rootDir, changedFiles, changedSymbols })
+    : {
+        changedFiles,
+        changedSymbols,
+        riskLabels: [],
+        callees: [],
+        callers: [],
+        importers: [],
+        mirrorCounterparts: [],
+        relatedTests: [],
+        recommendedTestFiles: [],
+      };
+
+  printCompact(impact);
+
+  if (formatImpactConfidenceSummary) {
+    console.log('');
+    console.log(formatImpactConfidenceSummary(impact));
+  }
+}
+
+async function ensureFreshIndex(rootDir) {
+  const generatedAtMs = await getIndexArtifactGeneratedAt({ rootDir });
+  const stale = generatedAtMs === null
+    ? true
+    : await isIndexStale({
+        rootDir,
+        maxAgeMs: DEFAULT_INDEX_CACHE_MAX_AGE_MS,
+        now: Date.now(),
+        generatedAtMs,
+      });
+
+  if (stale) {
+    await buildCodeIndex({ rootDir });
+  }
+}
+
+function printCompact(impact) {
+  const changed = (impact.changedFiles ?? []).slice(0, 5).join(', ');
+  const symbols = (impact.changedSymbols ?? []).slice(0, 5).join(', ');
+  const risk = (impact.riskLabels ?? []).slice(0, 5).join(', ');
+  const callees = unique((impact.callees ?? []).map((entry) => entry?.symbol).filter(Boolean)).slice(0, CALLEE_CAP).join(', ');
+  const callers = unique((impact.callers ?? []).map((entry) => entry?.filePath).filter(Boolean)).slice(0, CALLER_CAP).join(', ');
+  const mirrors = unique((impact.mirrorCounterparts ?? []).map((entry) => entry?.filePath).filter(Boolean)).slice(0, MIRROR_CAP).join(', ');
+  const tests = (impact.recommendedTestFiles ?? impact.relatedTests ?? []).slice(0, TEST_CAP);
+  const verify = tests.slice(0, VERIFY_CAP).map((testFile) => `yarn test ${testFile}`).join(' | ');
+
+  console.log('[ukit:impact]');
+  console.log(`changed: ${changed || '(none)'}`);
+  if (symbols) console.log(`symbols: ${symbols}`);
+  if (risk) console.log(`risk: ${risk}`);
+  if (callees) console.log(`callees: ${callees}`);
+  if (callers) console.log(`callers: ${callers}`);
+  if (mirrors) console.log(`mirrors: ${mirrors}`);
+  if (tests.length > 0) console.log(`related-tests: ${tests.join(', ')}`);
+  if (verify) console.log(`verify: ${verify}`);
+}
+
+function parseCsv(value) {
+  return unique(
+    String(value ?? '')
+      .split(',')
+      .map((entry) => entry.trim().replace(/^\.\//, ''))
+      .filter(Boolean),
+  );
+}
+
+function unique(values = []) {
+  return [...new Set(values)];
+}
+
+function readFlagValue(args, flag) {
+  const index = args.indexOf(flag);
+  if (index === -1) return null;
+  return args[index + 1] ?? null;
+}
+
+function getRootDir(args) {
+  const explicitRoot = readFlagValue(args, '--root');
+  return path.resolve(explicitRoot || process.cwd());
+}
+
+await main();