@ngockhoale/ukit 3.0.3 → 3.0.4

package/src/index/importResolution.js

@@ -291,19 +291,22 @@ function buildBaseUrlDirs({ rootDir, compilerOptions }) {
 }
 
 async function resolveExtendedConfigPath(configDir, extendsValue) {
-  const withExtension = extendsValue.endsWith('.json')
-    ? extendsValue
-    : `${extendsValue}.json`;
-  if (withExtension.startsWith('.') || withExtension.startsWith('/')) {
+  if (extendsValue.startsWith('.') || extendsValue.startsWith('/')) {
+    const withExtension = extendsValue.endsWith('.json')
+      ? extendsValue
+      : `${extendsValue}.json`;
     return path.resolve(configDir, withExtension);
   }
 
-  const parts = withExtension.split('/').filter(Boolean);
+  // Package specifiers split on the RAW value: appending `.json` first would
+  // turn a bare `extends: "acme-base"` into the package name `acme-base.json`,
+  // which never exists under node_modules.
+  const parts = extendsValue.split('/').filter(Boolean);
   if (parts.length === 0) {
     return null;
   }
 
-  const packageName = withExtension.startsWith('@')
+  const packageName = extendsValue.startsWith('@')
     ? parts.slice(0, 2).join('/')
     : parts[0];
   const packageRest = parts.slice(packageName.startsWith('@') ? 2 : 1).join('/');
@@ -312,7 +315,10 @@ async function resolveExtendedConfigPath(configDir, extendsValue) {
     return null;
   }
 
-  return path.join(packageRoot, packageRest || 'tsconfig.json');
+  const rest = packageRest && !packageRest.endsWith('.json')
+    ? `${packageRest}.json`
+    : packageRest;
+  return path.join(packageRoot, rest || 'tsconfig.json');
 }
 
 async function findNodeModulePackageRoot(startDir, packageName) {

package/src/index/queryIndex.js

@@ -24,7 +24,8 @@ function setBoundedCacheEntry(map, key, value, maxEntries = MAX_CACHE_ENTRIES) {
 }
 
 export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5 } = {}) {
-  if (!query || !query.trim()) {
+  const normalizedQuery = String(query ?? '').trim();
+  if (!normalizedQuery) {
     return [];
   }
   if (limit <= 0) {
@@ -32,7 +33,6 @@ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5
   }
 
   const absoluteRoot = path.resolve(rootDir);
-  const normalizedQuery = String(query).trim();
   const queryDescriptor = buildSearchDescriptor(normalizedQuery, {
     expandVietnameseAliases: true,
   });
@@ -590,12 +590,12 @@ function buildResolvedImportGraphs(rootDir, imports, indexedFileSet, importAlias
 // ── Index V2: Analog Query ──
 
 export async function queryAnalog({ rootDir = process.cwd(), filePath, limit = 5 } = {}) {
-  if (!filePath || !filePath.trim()) {
+  const normalizedFilePath = String(filePath ?? '').trim();
+  if (!normalizedFilePath) {
     return [];
   }
 
   const absoluteRoot = path.resolve(rootDir);
-  const normalizedFilePath = String(filePath).trim();
   const analogCacheKey = JSON.stringify({
     rootDir: absoluteRoot,
     filePath: normalizedFilePath,
@@ -670,7 +670,13 @@ function freezeAnalogResults(results) {
 }
 
 function ensureArtifact(artifact) {
-  return artifact && typeof artifact === 'object' ? artifact : { items: [] };
+  if (!artifact || typeof artifact !== 'object') {
+    return { items: [] };
+  }
+  // A schema-current artifact whose `items` is not an array (truncated or
+  // hand-corrupted JSON) must degrade to an empty item list — callers iterate
+  // `items` unconditionally and a non-array value crashes the query path.
+  return Array.isArray(artifact.items) ? artifact : { ...artifact, items: [] };
 }
 
 function escapeJsonString(value) {

package/src/index/resolveContext.js

@@ -33,10 +33,20 @@ const EXPANSION_SIGNALS = [
   'project',
   'repo',
   'workspace',
-  'all ',
-  'every ',
+  'all',
+  'every',
 ];
 
+// Signals must match whole words: bare `includes` let 'score' fire 'core',
+// 'author' fire 'auth', 'context' fire 'text', and 'install ' fire 'all '.
+function escapeSignalRegExp(signal) {
+  return signal.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function containsSignalWord(lower, signals) {
+  return signals.some((signal) => new RegExp(`\\b${escapeSignalRegExp(signal)}\\b`).test(lower));
+}
+
 export async function resolveContext({
   rootDir = process.cwd(),
   intent = '',
@@ -183,14 +193,14 @@ export function classifyTask(intent) {
   const lower = intent.toLowerCase();
 
   // Check risky first (highest priority)
-  if (RISKY_SIGNALS.some((signal) => lower.includes(signal))) {
+  if (containsSignalWord(lower, RISKY_SIGNALS)) {
     return 'non-trivial';
   }
 
   // Check trivial
-  if (TRIVIAL_SIGNALS.some((signal) => lower.includes(signal))) {
+  if (containsSignalWord(lower, TRIVIAL_SIGNALS)) {
     // But if intent also mentions multiple files or broad scope, upgrade
-    if (lower.includes('all ') || lower.includes('every ') || lower.includes('multiple')) {
+    if (/\ball\b/.test(lower) || /\bevery\b/.test(lower) || /\bmultiple\b/.test(lower)) {
       return 'simple';
     }
     return 'trivial';
@@ -218,7 +228,7 @@ function shouldQueryIndex({
     return true;
   }
 
-  return EXPANSION_SIGNALS.some((signal) => normalizedIntent.includes(signal));
+  return containsSignalWord(normalizedIntent, EXPANSION_SIGNALS);
 }
 function enforceContextBudget(result, maxFiles) {
   const prioritizedGroups = [

package/src/index/taskRouting.js

@@ -14,7 +14,8 @@ import {
   ROUTE_EFFORTS,
   resolveModelTier,
 } from '../core/executionContracts.js';
-import { resolveModelRoles, readMergedRuntimeConfig } from '../core/runtimeConfig.js';
+import { resolveModelRoles, readMergedRuntimeConfig, resolveConfigStage } from '../core/runtimeConfig.js';
+import { runShadowDecisions } from '../decision/shadow.js';
 import { resolvePlaybook } from '../core/userPlaybooks.js';
 
 // --- v3 route-side advisory blocks (docs/pstack/SPEC-playbook-todo.md, ------------------
@@ -378,6 +379,10 @@ function isDeliveryOnlyRequest({ signalText = '', scores = {}, targetFile = null
     && !targetFile;
 }
 
+
+// @decision-point route.intent-kind.v1 — intent kind is a registered
+// consequential decision (DECISION_REGISTRY); this deterministic mapping is
+// its fallback policy implementation.
 // CONTRACTS.md "Intent vocabulary mapping": taskType informs mode priors, not
 // intent.kind; intentMode maps to kind as question/explanation → informational,
 // ship/deliver → delivery, code change → mutation, root-cause/diagnosis →
@@ -629,6 +634,9 @@ export async function deriveTaskRoute({
   autonomyLevel = 'balanced',
   runtimeConfig = null,
   homeDir = undefined,
+  // TASK-004 (FR-008/FR-009): decision-plane runtime seam — transport/env/
+  // hostCapabilities overrides for the shadow evaluator. Unused at stage off.
+  decisionPlaneOptions = null,
 } = {}) {
   const absoluteRoot = path.resolve(rootDir);
   // M01.1: additive route-schema stage. Absent config / absent key / unknown value all
@@ -793,6 +801,45 @@ export async function deriveTaskRoute({
   });
   const approachSelector = routeSummary?.approachSelector ?? null;
 
+  // TASK-004 (SPEC §5 FR-008/FR-009): decision-plane hook. Stage resolves via
+  // the shared resolver — absent/malformed → 'off' → zero cost, byte-identical
+  // route. shadow → redacted receipt only (deterministic policy authoritative);
+  // canary/default → validated preflight bundle attached. Any failure degrades
+  // to the deterministic baseline with one bounded diagnostic.
+  const decisionPlaneStage = resolveConfigStage(resolvedRuntimeConfig, 'decisionPlane.stage');
+  if (decisionPlaneStage !== 'off' && resolvedRuntimeConfig?.decisionPlane?.enabled !== false) {
+    try {
+      const shadow = await runShadowDecisions({
+        route: routeSummary,
+        config: resolvedRuntimeConfig,
+        transport: decisionPlaneOptions?.transport,
+        hostCapabilities: decisionPlaneOptions?.hostCapabilities,
+        env: decisionPlaneOptions?.env,
+        projectRoot: absoluteRoot,
+        homeDir,
+        now: decisionPlaneOptions?.now,
+        deadlineMs: decisionPlaneOptions?.deadlineMs,
+      });
+      if (shadow?.receipt) {
+        routeSummary.decisionPlane = {
+          stage: decisionPlaneStage,
+          receipt: shadow.receipt,
+          ...(shadow.preflight ? { preflight: shadow.preflight } : {}),
+        };
+        if (shadow.receipt.fallbackCode) {
+          degradedWarnings.push(
+            `decision-plane ${decisionPlaneStage}: ${shadow.receipt.outcomeClass} (${shadow.receipt.fallbackCode})`,
+          );
+        }
+      }
+    } catch (error) {
+      degradedWarnings.push(
+        `decision-plane ${decisionPlaneStage}: unavailable (${error?.message ?? String(error)})`,
+      );
+    }
+  }
+
+
   return {
     activeSkills,
     routingContext: {
@@ -831,6 +878,10 @@ export function buildRouteSummary({
   routeSchemaStage = 'off',
   runtimeConfig = null,
   resolvedWorkflowPolicy = null,
+  // TASK-004 (FR-009): additive decision-plane block for callers that already
+  // hold a shadow/canary result (deriveTaskRoute attaches post-build since the
+  // evaluator consumes the built summary). Absent → no field, byte-identical.
+  decisionPlane = null,
 } = {}) {
   const autonomyLevel = routingContext.autonomyLevel ?? 'balanced';
   const delegationRecommendation = deriveDelegationRecommendation({
@@ -1015,6 +1066,9 @@ export function buildRouteSummary({
     ...(workflowPolicy ? { workflowPolicySource: resolvedWorkflowPolicy?.source ?? 'builtin' } : {}),
     principleIndex,
     modelRolesBlock,
+    // TASK-004 additive field — present only when a caller supplies a
+    // decision-plane result (stage != 'off').
+    ...(decisionPlane ? { decisionPlane } : {}),
     line: summaryLine || 'task=unknown',
   };
 }
@@ -1168,6 +1222,10 @@ function isInformationalPrompt({
   return questionSignal;
 }
 
+
+// @decision-point preflight.execution-lane.v1 — the execution lane is a
+// registered preflight decision; this deterministic ladder is its
+// 'deterministic-route' fallback policy implementation.
 function deriveExecutionMode({
   promptText = '',
   commandText = '',
@@ -2105,7 +2163,10 @@ function inferTaskType({ promptText, commandText, selectedIds, targetFile = null
 
 function shellEscape(str) {
   if (typeof str !== 'string') return '';
-  return "'" + str.replace(/'/g, "'\''") + "'";
+  // POSIX single-quote escape: close, escaped quote, reopen. The JS literal
+  // needs a double backslash — "'\''" collapses to ''' and silently drops
+  // the apostrophe from the routed intent text.
+  return "'" + str.replace(/'/g, "'\\''") + "'";
 }
 
 function buildHelperCommand({

package/src/index/verificationPlan.js

@@ -7,7 +7,7 @@ import { resolveContext } from './resolveContext.js';
 const RISKY_SKILL_IDS = new Set(['discover-security', 'repo-maintenance']);
 // SPEC-typed-verdicts §2.5: commands matching a test runner can mint a
 // `test-verified` verdict; everything else a plan routes is `check-only`.
-const TEST_RUNNER_COMMAND = /(?:^|\s)(?:vitest|jest|mocha|ava|pytest|py\.test)(?:\s|$)|(?:npm|pnpm|yarn|bun)(?:\s+run)?\s+test(?:\s|$)/i;
+const TEST_RUNNER_COMMAND = /(?:^|\s)(?:vitest|jest|mocha|ava|pytest|py\.test)(?:\s|$)|(?:npm|pnpm|yarn|bun)(?:\s+run)?\s+test(?::[^\s]+)?(?:\s|$)/i;
 const TRACKED_VERIFICATION_FILES = [
   'package.json',
   'package-lock.json',
@@ -140,6 +140,17 @@ export async function deriveVerificationPlan({
         reasons.push('highRiskFallback');
         commands.push(buildScriptCommand(packageManager, 'test'));
       }
+
+      // Non-empty floor (RULES.md test-selection §3): when nothing targeted and
+      // no fallback resolved, the plan must still route the broadest test
+      // script the project declares — an empty selection is never permitted.
+      if (commands.length === 0 && fallbackCommands.length === 0) {
+        const floorScript = scripts['test:release-core'] ? 'test:release-core' : (scripts.test ? 'test' : null);
+        if (floorScript) {
+          reasons.push('nonEmptyFloor');
+          fallbackCommands.push(buildScriptCommand(packageManager, floorScript));
+        }
+      }
     }
 
     if (commands.length === 0 && fallbackCommands.length === 0) {

package/src/learning/patternProposals.js

@@ -59,6 +59,12 @@ async function knownSignaturesAndTexts(projectRoot, projectId) {
     const pending = await listPendingPatternCandidates(projectRoot, projectId);
     for (const entry of pending) {
       texts.add(normalizeText(entry.text));
+      // Legacy pending candidates carry `signature` at top level (v2 records
+      // carry it under meta, collected below). Missing this let a same-signature
+      // pattern with a changed count/text slip past dedupe as 'proposed'.
+      if (typeof entry.signature === 'string' && entry.signature) {
+        signatures.add(entry.signature);
+      }
     }
   } catch {
     // listing failed → degrade, store dedupe is last line of defense

package/src/render/renderTemplate.js

@@ -1,6 +1,6 @@
 const TOKEN_PATTERN = /\{\{\s*([a-zA-Z0-9_.-]+)\s*\}\}/g;
 
-function flattenObject(input, prefix = '', output = {}) {
+function flattenObject(input, prefix = '', output = Object.create(null)) {
   if (input === null || input === undefined) {
     return output;
   }

package/src/skill/auditSkill.js

@@ -80,7 +80,9 @@ export async function statusSkillAudit({ rootDir = process.cwd(), skillName } =
 
   const openRationalizations = history
     .flatMap((record) => record.rationalizationsFound ?? [])
-    .filter((item) => !(typeof item === 'object' && item.closed === true));
+    // `typeof null === 'object'` — a null entry in a hand-edited history file
+    // crashed status on `item.closed`. Optional chaining keeps nulls open.
+    .filter((item) => item?.closed !== true);
 
   return { latest, openRationalizations, entryCount: history.length };
 }

package/src/stack/detectStack.js

@@ -131,7 +131,9 @@ async function detectDuraOne(projectRoot) {
 
 export async function detectStack(projectRoot) {
   const packageJsonPath = path.join(projectRoot, 'package.json');
-  const packageJson = await readJsonIfExists(packageJsonPath);
+  // A corrupt package.json must degrade to the core pack — the same precedent
+  // detectProjectContext follows — not crash install/routing with a SyntaxError.
+  const packageJson = await readJsonIfExists(packageJsonPath).catch(() => null);
   const dependencySet = collectDependencySet(packageJson);
 
   const frontendSignals = collectDependencySignals(dependencySet, FRONTEND_DEPENDENCIES);

package/template_project/.claude/agents/handoff-planner.md

@@ -86,7 +86,7 @@ defect — fix it before writing tasks.
 
 ## Phase 1 — Write PLAN.md
 
-Write all 7 sections to `docs/AI_HANDOFF/PLAN.md`:
+Write all 6 sections to `docs/AI_HANDOFF/PLAN.md`:
 
 ```
 §1 Intent       — what problem, what success looks like
@@ -104,9 +104,6 @@ Write all 7 sections to `docs/AI_HANDOFF/PLAN.md`:
                   command. If the project genuinely has none, state that explicitly —
                   do not omit silently.
 §6 Acceptance   — checklist of done criteria (prefer verifiable/command-based criteria)
-§7 Global Constraints — one line each: version floors, dependency limits, naming/copy
-                  rules, platform requirements. Every TASK-xxx.md inherits this section
-                  by reference — do not repeat these constraints inside each task.
 ```
 
 **§4 is non-negotiable.** No test plan = plan not ready.
@@ -118,7 +115,7 @@ Append this footer to `PLAN.md` — mandatory, checked by a hook before the writ
 PLANNER_MODEL: <your exact model ID — e.g. claude-opus-5>
 ```
 
-Your output does not go straight to implementation: an independent `code-reviewer` pass (`REVIEW_TARGET_TYPE=plan`) reviews `PLAN.md` next. If it returns `Issues Found`, you'll be re-invoked to revise and resubmit — write §1-§7 tight enough to pass on the first pass.
+Your output does not go straight to implementation: an independent `code-reviewer` pass (`REVIEW_TARGET_TYPE=plan`) reviews `PLAN.md` next. If it returns `Issues Found`, you'll be re-invoked to revise and resubmit — write §1-§6 tight enough to pass on the first pass.
 
 ## Phase 2 — Split into TASK-xxx.md
 

package/template_project/.claude/hooks/auto-allow-bash.sh

@@ -81,6 +81,10 @@ if [ -z "$COMMAND" ]; then
   exit 0
 fi
 
+# set -f: unquoted $COMMAND word-splits AND glob-expands — a bare `*` or `*.sh`
+# command would otherwise resolve to cwd filenames and persist an allow rule
+# for a file that was never the invoked binary.
+set -f
 BIN=""
 for token in $COMMAND; do
   case "$token" in
@@ -91,6 +95,7 @@ for token in $COMMAND; do
   BIN="$token"
   break
 done
+set +f
 
 if [ -z "$BIN" ]; then
   exit 0

package/template_project/.claude/hooks/block-dangerous.mjs

@@ -101,7 +101,7 @@ const DANGEROUS_LITERALS = [
   'rm -rf /',
   'rm -rf ~',
   'git push --force',
-  'git push -f ',
+  'git push -f',
   'git reset --hard',
   'git clean -fd',
   '> /dev/sda',
@@ -345,9 +345,16 @@ export function isDirectRun() {
 async function main() {
   const env = process.env;
   const HOOK_DEADLINE_MS = Number.parseInt(env.UKIT_HOOK_DEADLINE_MS || '', 10) || 3000;
-  // .sh parity: the deadline bounded the extraction node — expiry produced an
-  // empty command and a pass (exit 0, no output).
-  const timer = setTimeout(() => process.exit(0), HOOK_DEADLINE_MS);
+  // Fail-closed (BUG-C21-03 parity): the deadline bounds the WHOLE scan —
+  // extraction plus evaluation. A wedged scan (stalled realpath, dead mount)
+  // must refuse exactly like runHook's TIMEOUT_REFUSAL, never silently pass an
+  // uninspected payload: the pre-port .sh had no scan deadline, so a hang ended
+  // as a non-zero hook error = blocked; a silent exit 0 would pass it.
+  const timer = setTimeout(() => {
+    try { process.stdout.write(TIMEOUT_REFUSAL.stdout); } catch {}
+    try { process.stderr.write(TIMEOUT_REFUSAL.stderr); } catch {}
+    process.exit(TIMEOUT_REFUSAL.code);
+  }, HOOK_DEADLINE_MS);
   if (timer && typeof timer.unref === 'function') timer.unref();
 
   let rawInput = '';

package/template_project/.claude/hooks/context-hardcap-gate.sh

@@ -438,4 +438,13 @@ async function readRunCursor() {
 });
 NODE
 
-exit $?
+NODE_RC=$?
+# Fail-open parity with the in-block catch and the deadline path: a node crash
+# (missing runtime, OOM, preload failure) means the cap was never evaluated —
+# announce the degrade (SPEC §8) and release, never a silent non-blocking hook
+# error. Exit 2 (a real hard-cap block) passes through untouched.
+if [ "$NODE_RC" -ne 0 ] && [ "$NODE_RC" -ne 2 ]; then
+  printf '%s\n' '{"systemMessage":"UKit context hard-cap gate: evaluation crashed before finishing; this tool call proceeded without the hard-cap check. Run `ukit install` if this repeats."}'
+  exit 0
+fi
+exit "$NODE_RC"

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

@@ -131,9 +131,11 @@ function block(message) {
 function tierOf(model) {
   if (!model) return null;
   if (/unic-vision/i.test(model)) return 'vision';
-  if (/opus|unic-smart/i.test(model)) return 'smart';
-  if (/sonnet|unic-code/i.test(model)) return 'code';
-  if (/haiku|unic-lite/i.test(model)) return 'lite';
+  // omp tier aliases resolve through .omp/config.yml modelRoles:
+  // @slow → smart/opus lane, @default → code/sonnet lane, @smol → lite/haiku lane.
+  if (/opus|unic-smart|@?slow\b/i.test(model)) return 'smart';
+  if (/sonnet|unic-code|@?default\b/i.test(model)) return 'code';
+  if (/haiku|unic-lite|@?smol\b/i.test(model)) return 'lite';
   return 'unknown';
 }
 
@@ -384,4 +386,12 @@ process.exit(0);
 })();
 NODE
 
-exit $?
+NODE_RC=$?
+# Fail-open parity with the deadline path above: a node crash (missing runtime,
+# OOM, preload failure) means the tier check never ran — announce the degrade
+# (SPEC §8) and release, never a silent non-blocking hook error.
+if [ "$NODE_RC" -ne 0 ] && [ "$NODE_RC" -ne 2 ]; then
+  printf '%s\n' '{"systemMessage":"UKit handoff-model-guard: evaluation crashed before finishing; this tool call proceeded without the model check. Run `ukit install` if this repeats."}'
+  exit 0
+fi
+exit "$NODE_RC"

package/template_project/.claude/hooks/handoff-resume.sh

@@ -196,7 +196,16 @@ async function emitOrdinaryResume(payload, source) {
 
   process.stdout.write(`${out.join('\n')}\n`);
   process.exit(0);
-})();
+})().catch((err) => {
+  // Advisory hook: an unexpected error must never surface as a silent masked
+  // exit — announce the degrade (SPEC §8(ii)) and exit 0 like every other path.
+  try {
+    process.stdout.write(`${JSON.stringify({
+      systemMessage: `UKit handoff-resume crashed (${String(err?.message ?? err).slice(0, 200)}) — the resume check was skipped this session start.`,
+    })}\n`);
+  } catch {}
+  process.exit(0);
+});
 NODE
 
 exit 0

package/template_project/.claude/hooks/protect-files.sh

@@ -138,7 +138,6 @@ if [ -n "$PROTECTED_MATCH" ]; then
   # under bypassPermissions an exit-0 `ask` auto-approves — dead for a protected-file
   # refusal — so the direct host emits `deny`; the chain keeps `ask` for the human.
   __ukit_protect_reason='UKit protected-file guard blocked this edit. Ask the user to modify the protected file manually.'
-  echo "BLOCKED: Cannot modify '$FILE_PATH' — matches protected pattern '$PROTECTED_MATCH'. Ask the user to modify this file manually." >&2
   if command -v ukit_emit_permission_decision >/dev/null 2>&1; then
     if [ -n "${UKIT_HOOK_CHAIN_RUNNER:-}" ]; then
       ukit_emit_permission_decision ask "$__ukit_protect_reason"

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

@@ -118,6 +118,18 @@ export function isDirectRun() {
 
 async function main() {
   const env = process.env;
+  // The .sh wrapper exports UKIT_HOOK_DEADLINE_MS but this entry point never
+  // armed it: a wedged ledger import or stalled read hung the hook until the
+  // host killed it — a silent pass for a receipt that was never recorded.
+  // Deadline expiry is a failed runtime: emit the same loud line the .sh
+  // prints for a non-zero node exit (advisory posture kept: exit 0).
+  const HOOK_DEADLINE_MS = Number.parseInt(env.UKIT_HOOK_DEADLINE_MS || '', 10) || 3000;
+  const timer = setTimeout(() => {
+    try { process.stdout.write(RUNTIME_FAILED); } catch {}
+    process.exit(0);
+  }, HOOK_DEADLINE_MS);
+  if (timer && typeof timer.unref === 'function') timer.unref();
+
   let rawInput = '';
   try {
     rawInput = await fsp.readFile(env.INPUT_FILE || '', 'utf8');
@@ -125,7 +137,7 @@ async function main() {
     // No staged payload — silent advisory pass, same as an unreadable INPUT.
   }
   const projectRoot = env.PROJECT_ROOT || process.cwd();
-  const verdict = await record({ rawInput, projectRoot, env });
+  const verdict = await record({ rawInput, projectRoot, env, deadlineMs: HOOK_DEADLINE_MS });
   if (verdict.stdout) process.stdout.write(verdict.stdout);
   process.exit(0);
 }

package/template_project/.claude/hooks/sensitive-data-guard.mjs

@@ -238,19 +238,85 @@ async function evaluate({ rawInput, projectRoot, env }) {
         continue;
       }
 
-      if (DUMP_VERBS.has(head)) {
-        for (const token of tokens.slice(1)) {
+      // Wrapper executables run the real command as their operand — `sudo cat
+      // .env` dumps the file exactly like `cat .env`, so the dump-verb check
+      // must resolve the EFFECTIVE head, not tokens[0]. Each wrapper maps to
+      // the number of positional operands it takes BEFORE the command (sudo
+      // takes none — `sudo curl` runs curl; `timeout` takes one — its
+      // duration). Unknown flags consume their operand only when it cannot be
+      // a command (not a verb/wrapper/assignment/flag), so a miss degrades to
+      // the old tokens[0] behavior rather than a false positive.
+      const WRAPPER_POSITIONALS = new Map([
+        ['sudo', 0], ['doas', 0], ['pkexec', 0], ['unshare', 0], ['nsenter', 0],
+        ['setpriv', 0], ['capsh', 0], ['systemd-run', 0], ['env', 0], ['nice', 0],
+        ['ionice', 0], ['stdbuf', 0], ['chrt', 0], ['nohup', 0], ['watch', 0],
+        ['xargs', 0], ['strace', 0], ['ltrace', 0], ['time', 0], ['command', 0],
+        ['builtin', 0], ['exec', 0], ['eval', 0],
+        ['bash', 0], ['sh', 0], ['zsh', 0], ['dash', 0], ['ksh', 0],
+        ['runuser', 1], ['sg', 1], ['su', 1], ['ssh', 1], ['mosh', 1],
+        ['timeout', 1], ['chroot', 1], ['setarch', 1], ['taskset', 1],
+        ['flock', 1],
+        ['docker', 2], ['podman', 2], ['nerdctl', 2], ['ctr', 2],
+        ['kubectl', 2], ['machinectl', 2],
+      ]);
+      const unquote = (t) => String(t || '').replace(/^["']+|["']+$/g, '');
+      const isVerbToken = (t) => DUMP_VERBS.has(unquote(t).replace(/^.*\//, ''));
+      const wrapperPositionals = (t) => WRAPPER_POSITIONALS.get(unquote(t).replace(/^.*\//, ''));
+      const isAssignToken = (t) => /^[A-Za-z_][A-Za-z0-9_]*=/.test(t);
+      const isFlagToken = (t) => /^-[^-]?|--/.test(t);
+      let headIdx = 0;
+      let wrapperPositionalPending = 0;
+      for (;;) {
+        const t = tokens[headIdx];
+        if (t === undefined) break;
+        if (t === '--') { headIdx += 1; break; }
+        if (isAssignToken(t)) { headIdx += 1; continue; }
+        const positionalCount = wrapperPositionals(t);
+        if (positionalCount !== undefined) {
+          wrapperPositionalPending = positionalCount;
+          headIdx += 1;
+          continue;
+        }
+        if (isFlagToken(t)) {
+          headIdx += 1;
+          const next = tokens[headIdx];
+          // A flag's operand is consumed only when it cannot be the command:
+          // verbs, wrappers, assignments and further flags are never operands.
+          if (next !== undefined
+            && !isFlagToken(next)
+            && !isAssignToken(next)
+            && !isVerbToken(next)
+            && wrapperPositionals(next) === undefined) {
+            headIdx += 1;
+          }
+          continue;
+        }
+        if (wrapperPositionalPending > 0 && !isVerbToken(t)) {
+          // The wrapper's own operand (user/host/duration/image), then the
+          // next token is the real command.
+          wrapperPositionalPending -= 1;
+          headIdx += 1;
+          continue;
+        }
+        break;
+      }
+      const effectiveHead = unquote(tokens[headIdx] ?? '');
+
+      if (DUMP_VERBS.has(effectiveHead)) {
+        for (const token of tokens.slice(headIdx + 1)) {
           const cleaned = token.replace(/^["']+|["',:]+$/g, '');
           const kind = classifySecretFile(cleaned);
           if (kind && !pathAllowed(cleaned)) {
-            found.push({ label: `${head} reads ${kind}`, value: cleaned, isPath: true });
+            found.push({ label: `${effectiveHead} reads ${kind}`, value: cleaned, isPath: true });
           }
         }
       }
 
-      const headBase = head.replace(/^.*\//, '');
+      const headBase = effectiveHead.replace(/^.*\//, '');
       const CRED_USER_TOOLS = new Set(['curl', 'wget', 'ftp', 'lftp', 'aria2c', 'http', 'https']);
-      const inlineUser = /(^|\s)(-u|--user)\s+["']?([^\s"':]+):([^\s"']+)/.exec(segment);
+      // `-uuser:pass`, `-u user:pass`, `--user=user:pass`, `--user user:pass` —
+      // the old `\s+` separator missed the joined and `=` forms entirely.
+      const inlineUser = /(^|\s)(-u|--user)[\s=]*["']?([^\s"':]+):([^\s"']+)/.exec(segment);
       if (inlineUser && CRED_USER_TOOLS.has(headBase)) {
         const numericIds = /^\d+$/.test(inlineUser[3]) && /^\d+$/.test(inlineUser[4]);
         if (!numericIds) {

package/template_project/.claude/hooks/session-episode.sh

@@ -64,11 +64,18 @@ if [ -e /dev/fd/0 ]; then
   exec 8<&0
   head -c 65537 <&8 > "$UKIT_INPUT_FILE" 2>/dev/null &
   UKIT_HEAD_PID=$!
-  # UKIT_HOOK_STAGE_MS:-2000 — bounded wait for the staged payload.
+  # UKIT_HOOK_STAGE_MS:-2000 — bounded wait for the staged payload (same derived
+  # budget every other hook uses; a hardcoded sleep ignored the operator knob).
+  __ukit_ep_stage_ms="${UKIT_HOOK_STAGE_MS:-2000}"
+  case "$__ukit_ep_stage_ms" in
+    ''|*[!0-9]*) __ukit_ep_stage_ms=2000 ;;
+  esac
+  [ "$__ukit_ep_stage_ms" -gt 0 ] 2>/dev/null || __ukit_ep_stage_ms=2000
+  printf -v __ukit_ep_stage_s '%d.%03d' $((__ukit_ep_stage_ms / 1000)) $((__ukit_ep_stage_ms % 1000))
   # TASK-002: detach the watchdog's inherited stdout/stderr — otherwise a
   # captured-stdio caller (hook-chain-runner) sees the pipe held open ~2s
   # after the script exits, inflating the SessionEnd residual to ~2000ms.
-  ( sleep 2; kill "$UKIT_HEAD_PID" 2>/dev/null ) >/dev/null 2>&1 &
+  ( sleep "$__ukit_ep_stage_s"; kill "$UKIT_HEAD_PID" 2>/dev/null ) >/dev/null 2>&1 &
   UKIT_WATCH_PID=$!
   wait "$UKIT_HEAD_PID" 2>/dev/null
   kill "$UKIT_WATCH_PID" 2>/dev/null

package/template_project/.claude/skills/pdf-processing-pro/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: PDF Processing Pro
+name: pdf-processing-pro
 description: Production-ready PDF processing with forms, tables, OCR, validation, and batch operations. Use when working with complex PDF workflows in production environments, processing large volumes of PDFs, or requiring robust error handling and validation.
 ---
 

package/template_project/.claude/ukit/index/handoff-doc-validator.mjs

@@ -63,7 +63,9 @@ function planSectionPositions(sections) {
   const positions = new Map();
   for (const s of sections) {
     for (const token of PLAN_SECTIONS) {
-      if (!positions.has(token) && s.name.startsWith(token)) positions.set(token, s.pos);
+      // `## §10`/`## §12` must not satisfy `§1` — the token only matches when it
+      // is the whole heading or is followed by a non-digit boundary (space, colon…).
+      if (!positions.has(token) && new RegExp(`^${token}(?!\\d)`).test(s.name)) positions.set(token, s.pos);
     }
   }
   return positions;