@ngockhoale/ukit 2.6.10 → 2.7.0

package/src/diagnostics/skillAccuracy.js

@@ -0,0 +1,158 @@
+// skillAccuracy.js — per-skill trigger accuracy collector (SPEC C32 §5a).
+//
+// Joins route-audit entries carrying `skillIds` (FR-202) to exec-ledger
+// ledgers via `requestKey` (same join discipline as routeOutcomes.js) and
+// aggregates per-skill counters:
+//   triggers  = audit rows listing the skill
+//   joined    = those matched to a ledger
+//   accuracy  = joined === 0 ? null : writeOk / joined
+//   verifyOk/verifyFail/rescue reported separately for nuance.
+// Skills with triggers >= 2 && accuracy !== null && accuracy < 0.5 are also
+// copied into `lowAccuracy` for quick scanning.
+//
+// Contracts: NEVER THROWS — missing/malformed telemetry → zeroed result with
+// `error` field. Only side effect is the advisory artifact
+// `.ukit/storage/learning/skill-accuracy.json` (tmp+rename, non-fatal).
+// Gated by config `learning?.feedback?.enabled !== false` (default true).
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { listLedgerFiles, LEDGER_DIR_REL } from './ledgerFiles.js';
+
+const CACHE_DIR_REL = path.join('.ukit', 'storage', 'cache');
+const AUDIT_REL = path.join(CACHE_DIR_REL, 'route-audit.json');
+const ARTIFACT_REL = path.join('.ukit', 'storage', 'learning', 'skill-accuracy.json');
+const CONFIG_REL = path.join('.ukit', 'storage', 'config.json');
+const MAX_SKILL_IDS = 8;
+
+function isObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function zeroedResult(extra = {}) {
+  return {
+    generatedAt: new Date().toISOString(),
+    auditRowsScanned: 0,
+    ledgersScanned: 0,
+    joined: 0,
+    skills: {},
+    lowAccuracy: [],
+    ...extra,
+  };
+}
+
+function emptySkillBucket() {
+  return {
+    triggers: 0,
+    joined: 0,
+    writeOk: 0,
+    writeFail: 0,
+    verifyOk: 0,
+    verifyFail: 0,
+    rescue: 0,
+    accuracy: null,
+  };
+}
+
+async function readJson(filePath) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Default true when `learning`/`feedback` is absent (namespace lands in TASK-232).
+async function feedbackEnabled(projectRoot) {
+  const config = await readJson(path.join(projectRoot, CONFIG_REL));
+  return config?.learning?.feedback?.enabled !== false;
+}
+
+function skillIdsOf(entry) {
+  if (!Array.isArray(entry?.skillIds)) return [];
+  return entry.skillIds
+    .filter((id) => typeof id === 'string' && id)
+    .slice(0, MAX_SKILL_IDS);
+}
+
+async function writeArtifact(filePath, result) {
+  const dir = path.dirname(filePath);
+  const tmp = path.join(dir, `.skill-accuracy-${process.pid}.tmp`);
+  try {
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(tmp, JSON.stringify(result, null, 2));
+    await fs.rename(tmp, filePath);
+  } catch {
+    await fs.rm(tmp, { force: true }).catch(() => {});
+  }
+}
+
+/**
+ * Collect per-skill trigger accuracy by joining route-audit `skillIds` to
+ * exec-ledger ledgers on `requestKey`.
+ *
+ * @param {string} projectRoot repository root containing `.ukit/storage/`.
+ * @param {{ limitLedgers?: number }} [options]
+ * @returns {Promise<object>} never throws.
+ */
+export async function collectSkillAccuracy(projectRoot, { limitLedgers = 500 } = {}) {
+  const result = zeroedResult();
+  try {
+    if (!(await feedbackEnabled(projectRoot))) {
+      return result;
+    }
+
+    const auditDoc = await readJson(path.join(projectRoot, AUDIT_REL));
+    const auditEntries = Array.isArray(auditDoc?.entries)
+      ? auditDoc.entries.filter(isObject)
+      : [];
+    result.auditRowsScanned = auditEntries.length;
+
+    const ledgerDir = path.join(projectRoot, LEDGER_DIR_REL);
+    const ledgerNames = await listLedgerFiles(ledgerDir, limitLedgers);
+    const ledgerByKey = new Map();
+    for (const name of ledgerNames) {
+      const ledger = await readJson(path.join(ledgerDir, name));
+      if (!isObject(ledger)) continue;
+      result.ledgersScanned += 1;
+      if (typeof ledger.requestKey === 'string' && ledger.requestKey) {
+        ledgerByKey.set(ledger.requestKey, ledger);
+      }
+    }
+
+    for (const entry of auditEntries) {
+      const ids = skillIdsOf(entry);
+      if (ids.length === 0) continue;
+      const ledger = typeof entry.requestKey === 'string'
+        ? ledgerByKey.get(entry.requestKey)
+        : undefined;
+      for (const id of ids) {
+        const bucket = result.skills[id] ??= emptySkillBucket();
+        bucket.triggers += 1;
+        if (!ledger) continue;
+        bucket.joined += 1;
+        if (ledger.writeSucceeded === true) bucket.writeOk += 1;
+        else if (ledger.writeAttempted === true || ledger.writeSucceeded === false) {
+          bucket.writeFail += 1;
+        }
+        if (ledger.verificationSucceeded === true) bucket.verifyOk += 1;
+        if (ledger.verificationFailed === true) bucket.verifyFail += 1;
+        if (entry.rescueMode != null) bucket.rescue += 1;
+      }
+      if (ledger) result.joined += 1;
+    }
+
+    for (const [id, bucket] of Object.entries(result.skills)) {
+      bucket.accuracy = bucket.joined === 0 ? null : bucket.writeOk / bucket.joined;
+      if (bucket.triggers >= 2 && bucket.accuracy !== null && bucket.accuracy < 0.5) {
+        result.lowAccuracy.push({ id, accuracy: bucket.accuracy });
+      }
+    }
+    result.lowAccuracy.sort((a, b) => a.accuracy - b.accuracy);
+  } catch (error) {
+    result.error = error?.message ?? String(error);
+  }
+
+  await writeArtifact(path.join(projectRoot, ARTIFACT_REL), result);
+  return result;
+}

package/src/learning/patternProposals.js

@@ -0,0 +1,151 @@
+// patternProposals.js — promotion lane step 1 (FR-204 / TASK-230).
+//
+// Turns mined failure patterns (`.ukit/storage/cache/failure-patterns.json`,
+// C31 artifact) into pending pattern-candidate records for human
+// `ukit memory approve`. Dry-run by default; `dryRun: false` writes via
+// `proposePatternCandidate` from `src/core/memory/store.js`.
+//
+// Contracts:
+//   * NEVER THROWS — missing artifact, unreadable ledgers, store failures →
+//     partial result with `error` field, no exception escapes.
+//   * Nothing auto-promotes: candidates stay `pending`.
+//   * Eligible: count >= minCount AND sessions >= 2.
+//   * Dedupe: normalized-text OR meta.signature match against existing pending
+//     candidates and active v2 records → status 'duplicate', no write.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+  listPendingPatternCandidates,
+  proposePatternCandidate,
+} from '../core/memory/store.js';
+
+const ARTIFACT_REL = path.join('.ukit', 'storage', 'cache', 'failure-patterns.json');
+const MIN_SESSIONS = 2;
+
+function normalizeText(text) {
+  return String(text ?? '').toLowerCase().replace(/\s+/g, ' ').trim();
+}
+
+function candidateText(pattern) {
+  const firstFile = Array.isArray(pattern.files) && pattern.files.length > 0
+    ? pattern.files[0]
+    : 'the affected files';
+  return `Verification pattern "${pattern.signature}" failed ${pattern.count}× across ${pattern.sessions} sessions — check ${firstFile} before retrying.`;
+}
+
+async function loadPatterns(projectRoot) {
+  try {
+    const raw = await fs.readFile(path.join(projectRoot, ARTIFACT_REL), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed && Array.isArray(parsed.patterns)) return parsed.patterns;
+  } catch {
+    // Artifact absent/corrupt → lazy re-mine below.
+  }
+  try {
+    const mod = await import('../diagnostics/failurePatterns.js');
+    if (typeof mod?.mineFailurePatterns !== 'function') return [];
+    const mined = await mod.mineFailurePatterns(projectRoot, { minCount: 1 });
+    return Array.isArray(mined?.patterns) ? mined.patterns : [];
+  } catch {
+    return [];
+  }
+}
+
+async function knownSignaturesAndTexts(projectRoot, projectId) {
+  const signatures = new Set();
+  const texts = new Set();
+  try {
+    const pending = await listPendingPatternCandidates(projectRoot, projectId);
+    for (const entry of pending) {
+      texts.add(normalizeText(entry.text));
+    }
+  } catch {
+    // listing failed → degrade, store dedupe is last line of defense
+  }
+  try {
+    const { queryRecords } = await import('../core/memory/storeV2.js');
+    const records = await queryRecords(projectRoot, { projectId });
+    for (const record of records) {
+      if (typeof record?.meta?.signature === 'string') {
+        signatures.add(record.meta.signature);
+      }
+      if (record?.status === 'active' || record?.meta?.legacyStatus === 'pending') {
+        texts.add(normalizeText(record.text));
+      }
+    }
+  } catch {
+    // v2 store unavailable → degrade
+  }
+  return { signatures, texts };
+}
+
+/**
+ * Propose pending pattern-candidates from mined failure patterns.
+ *
+ * @param {string} projectRoot
+ * @param {string} projectId
+ * @param {{ minCount?: number, dryRun?: boolean }} [options]
+ * @returns {Promise<{generatedAt: string, patternsScanned: number, eligible: number,
+ *   proposed: Array<{signature: string, text: string,
+ *     status: 'proposed'|'duplicate'|'skipped'}>, dryRun: boolean, error?: string}>}
+ */
+export async function proposeFromPatterns(projectRoot, projectId, { minCount = 3, dryRun = true } = {}) {
+  const result = {
+    generatedAt: new Date().toISOString(),
+    patternsScanned: 0,
+    eligible: 0,
+    proposed: [],
+    dryRun,
+  };
+
+  try {
+    const patterns = await loadPatterns(projectRoot);
+    result.patternsScanned = patterns.length;
+    const known = await knownSignaturesAndTexts(projectRoot, projectId);
+
+    for (const pattern of patterns) {
+      const signature = typeof pattern?.signature === 'string' ? pattern.signature : null;
+      const count = Number(pattern?.count) || 0;
+      const sessions = Number(pattern?.sessions) || 0;
+      if (!signature) continue;
+
+      const text = candidateText({ signature, count, sessions, files: pattern.files });
+      const eligible = count >= minCount && sessions >= MIN_SESSIONS;
+      if (!eligible) {
+        result.proposed.push({ signature, text, status: 'skipped' });
+        continue;
+      }
+      result.eligible += 1;
+
+      if (known.signatures.has(signature) || known.texts.has(normalizeText(text))) {
+        result.proposed.push({ signature, text, status: 'duplicate' });
+        continue;
+      }
+
+      if (dryRun) {
+        result.proposed.push({ signature, text, status: 'proposed' });
+        continue;
+      }
+
+      try {
+        await proposePatternCandidate(projectRoot, projectId, {
+          text,
+          category: 'failure-pattern',
+          signature,
+          detectedFrom: 'memory-learn',
+        });
+        known.signatures.add(signature);
+        known.texts.add(normalizeText(text));
+        result.proposed.push({ signature, text, status: 'proposed' });
+      } catch (err) {
+        result.proposed.push({ signature, text, status: 'skipped' });
+        result.error = err?.message ?? String(err);
+      }
+    }
+  } catch (err) {
+    result.error = err?.message ?? String(err);
+  }
+
+  return result;
+}

package/src/learning/tuning.js

@@ -0,0 +1,213 @@
+// tuning.js — advisory tuning suggestions for the Phase-4 learning loop
+// (SPEC C32 §8b).
+//
+// Reads the learning artifacts already on disk:
+//   * lane stats        — via lazy collectLaneStats() over
+//                         `.ukit/storage/cache/retriever-lanes.jsonl`
+//   * feedback events   — `.ukit/storage/learning/feedback-events.json`
+//   * skill accuracy    — `.ukit/storage/learning/skill-accuracy.json`
+//
+// Contracts:
+//   * NEVER THROWS. Missing/malformed inputs → `skipped` entries with a
+//     reason, never an exception. Artifact write failure is non-fatal.
+//   * ADVISORY ONLY. `learning.tuning.applyMode` is restricted to
+//     'manual'|'off'; suggestions are computed and persisted but NOTHING is
+//     ever written back to config weights/thresholds (`applied` stays []).
+//   * Gated by config `learning?.tuning?.enabled !== false` and
+//     `learning?.tuning?.applyMode !== 'off'`.
+//
+// Output shape (persisted to `.ukit/storage/learning/suggestions.json`,
+// tmp+rename):
+//   { generatedAt, applied: [], suggestions: [{target, current, suggested,
+//     evidence}], skipped: [{target, reason}] }
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const LEARNING_DIR_REL = path.join('.ukit', 'storage', 'learning');
+const SUGGESTIONS_REL = path.join(LEARNING_DIR_REL, 'suggestions.json');
+const FEEDBACK_EVENTS_REL = path.join(LEARNING_DIR_REL, 'feedback-events.json');
+const SKILL_ACCURACY_REL = path.join(LEARNING_DIR_REL, 'skill-accuracy.json');
+const CONFIG_REL = path.join('.ukit', 'storage', 'config.json');
+
+const MIN_LANE_EVENTS = 50;
+const DOMINANT_CONTRIBUTION = 0.5;
+const STARVED_CONTRIBUTION = 0.02;
+const WEIGHT_STEP = 0.1;
+const WEIGHT_MIN = 0.1;
+const WEIGHT_MAX = 2.0;
+const MIN_REPEAT_STALLS = 10;
+
+const DEFAULT_WEIGHTS = { exact: 1.0, symbol: 1.2, bm25: 0.8, semantic: 1.0, vector: 0.6 };
+const DEFAULT_DEBUG_LOOP_THRESHOLD = 2;
+
+function isObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}
+
+function round1(value) {
+  return Math.round(value * 10) / 10;
+}
+
+async function readJson(filePath) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+async function writeArtifact(filePath, result) {
+  const dir = path.dirname(filePath);
+  const tmp = path.join(dir, `.suggestions-${process.pid}.tmp`);
+  try {
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(tmp, JSON.stringify(result, null, 2));
+    await fs.rename(tmp, filePath);
+  } catch {
+    await fs.rm(tmp, { force: true }).catch(() => {});
+  }
+}
+
+async function tuningEnabled(config) {
+  const tuning = config?.learning?.tuning;
+  if (tuning?.enabled === false) return 'learning.tuning.enabled=false';
+  if (tuning?.applyMode === 'off') return "learning.tuning.applyMode='off'";
+  return null;
+}
+
+function laneWeightSuggestions(laneStats, weights, suggestions, skipped) {
+  if (!laneStats || laneStats.empty || !isObject(laneStats.lanes)) {
+    skipped.push({ target: 'codeIntel.retriever.weights.*', reason: 'no retriever-lanes.jsonl data' });
+    return;
+  }
+  if ((laneStats.events ?? 0) < MIN_LANE_EVENTS) {
+    skipped.push({
+      target: 'codeIntel.retriever.weights.*',
+      reason: `insufficient lane events (${laneStats.events ?? 0} < ${MIN_LANE_EVENTS})`,
+    });
+    return;
+  }
+  const lanes = Object.entries(laneStats.lanes);
+  const dominant = lanes.filter(([, b]) => (b?.contribution ?? 0) > DOMINANT_CONTRIBUTION);
+  const starved = lanes.filter(([, b]) => (b?.contribution ?? 0) < STARVED_CONTRIBUTION);
+  if (dominant.length === 0 || starved.length === 0) {
+    skipped.push({
+      target: 'codeIntel.retriever.weights.*',
+      reason: 'no dominant+starved lane pair',
+    });
+    return;
+  }
+  for (const [lane, bucket] of starved) {
+    const current = typeof weights[lane] === 'number' ? weights[lane] : (DEFAULT_WEIGHTS[lane] ?? 1.0);
+    suggestions.push({
+      target: `codeIntel.retriever.weights.${lane}`,
+      current,
+      suggested: round1(clamp(current - WEIGHT_STEP, WEIGHT_MIN, WEIGHT_MAX)),
+      evidence: {
+        events: laneStats.events,
+        contribution: bucket.contribution,
+        reason: `lane contribution ${bucket.contribution.toFixed(3)} < ${STARVED_CONTRIBUTION} while another lane dominates — step weight down`,
+      },
+    });
+  }
+  for (const [lane, bucket] of dominant) {
+    const current = typeof weights[lane] === 'number' ? weights[lane] : (DEFAULT_WEIGHTS[lane] ?? 1.0);
+    suggestions.push({
+      target: `codeIntel.retriever.weights.${lane}`,
+      current,
+      suggested: round1(clamp(current + WEIGHT_STEP, WEIGHT_MIN, WEIGHT_MAX)),
+      evidence: {
+        events: laneStats.events,
+        contribution: bucket.contribution,
+        reason: `lane contribution ${bucket.contribution.toFixed(3)} > ${DOMINANT_CONTRIBUTION} — step weight up`,
+      },
+    });
+  }
+}
+
+function escalationSuggestion(feedbackEvents, debugLoopThreshold, suggestions, skipped) {
+  const target = 'orchestration.escalation.debugLoopThreshold';
+  if (!isObject(feedbackEvents)) {
+    skipped.push({ target, reason: 'no feedback-events.json artifact' });
+    return;
+  }
+  const stalls = feedbackEvents.byKind?.['repeat-stall']
+    ?? (Array.isArray(feedbackEvents.events)
+      ? feedbackEvents.events.filter((e) => e?.kind === 'repeat-stall').length
+      : 0);
+  if (stalls < MIN_REPEAT_STALLS) {
+    skipped.push({ target, reason: `repeat-stall events ${stalls} < ${MIN_REPEAT_STALLS}` });
+    return;
+  }
+  const current = typeof debugLoopThreshold === 'number' ? debugLoopThreshold : DEFAULT_DEBUG_LOOP_THRESHOLD;
+  suggestions.push({
+    target,
+    current,
+    suggested: Math.max(1, current - 1),
+    evidence: {
+      repeatStalls: stalls,
+      reason: `${stalls} repeat-stall events >= ${MIN_REPEAT_STALLS} — lower escalation threshold one step (min 1)`,
+    },
+  });
+}
+
+/**
+ * Compute advisory tuning suggestions and persist them to
+ * `.ukit/storage/learning/suggestions.json` (tmp+rename). Never applies
+ * anything; never throws.
+ *
+ * @param {string} projectRoot repository root containing `.ukit/storage/`.
+ * @returns {Promise<{generatedAt: string, applied: Array,
+ *   suggestions: Array<object>, skipped: Array<{target: string, reason: string}>}>}
+ */
+export async function computeTuningSuggestions(projectRoot) {
+  const result = {
+    generatedAt: new Date().toISOString(),
+    applied: [],
+    suggestions: [],
+    skipped: [],
+  };
+  try {
+    const config = await readJson(path.join(projectRoot, CONFIG_REL));
+    const disabledReason = await tuningEnabled(config);
+    if (disabledReason) {
+      result.skipped.push({ target: 'learning.tuning', reason: `tuning disabled (${disabledReason})` });
+      await writeArtifact(path.join(projectRoot, SUGGESTIONS_REL), result);
+      return result;
+    }
+
+    let laneStats = null;
+    try {
+      const mod = await import('../diagnostics/laneStats.js');
+      if (typeof mod?.collectLaneStats === 'function') {
+        laneStats = await mod.collectLaneStats(projectRoot);
+      }
+    } catch {
+      laneStats = null;
+    }
+
+    const feedbackEvents = await readJson(path.join(projectRoot, FEEDBACK_EVENTS_REL));
+    const skillAccuracy = await readJson(path.join(projectRoot, SKILL_ACCURACY_REL));
+    if (!isObject(skillAccuracy)) {
+      result.skipped.push({ target: 'skills.*', reason: 'no skill-accuracy.json artifact' });
+    }
+
+    const weights = isObject(config?.codeIntel?.retriever?.weights)
+      ? config.codeIntel.retriever.weights
+      : DEFAULT_WEIGHTS;
+    const debugLoopThreshold = config?.orchestration?.escalation?.debugLoopThreshold;
+
+    laneWeightSuggestions(laneStats, weights, result.suggestions, result.skipped);
+    escalationSuggestion(feedbackEvents, debugLoopThreshold, result.suggestions, result.skipped);
+  } catch (error) {
+    result.skipped.push({ target: 'learning.tuning', reason: error?.message ?? String(error) });
+  }
+
+  await writeArtifact(path.join(projectRoot, SUGGESTIONS_REL), result);
+  return result;
+}

package/templates/.claude/hooks/block-dangerous.sh

@@ -16,10 +16,22 @@ source "$SCRIPT_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
   if [ "$__ukit_main_stage_rc" -ne 0 ]; then
     # Infra failure during staging (mktemp/truncate): payload was never
     # inspected — announce the degrade (SPEC §8), never a silent pass.
-    ukit_emit_input_degraded failclosed "dangerous-command gate"
+    # TASK-003: `deny`, not `ask` — ask auto-approves under bypassPermissions.
+    ukit_emit_permission_decision deny "UKit could not fully read this tool-call payload (stdin staging was cut at the deadline/size bound), so dangerous-command gate cannot prove it safe."
   fi
-# BUG-C21-01: a truncated/stalled staged payload must be announced (SPEC §8), never silently passed.
-ukit_input_degraded && ukit_emit_input_degraded failclosed "dangerous-command gate"
+# BUG-C21-01 / TASK-003: a truncated/stalled staged payload used to be announced
+# as a blanket `ask` — but `ask` auto-approves under bypassPermissions (direct
+# host) = the gate silently skipped. Now the degraded path first attempts a
+# bounded salvage of tool_input.command: a COMPLETE recovered command still gets
+# the normal verdict below; an unrecoverable/incomplete one is refused with
+# `deny` (the only verdict both hosts treat as closed — review R1-1).
+if ukit_input_degraded; then
+  if UKIT_SALVAGED_COMMAND="$(ukit_salvage_tool_field "$UKIT_INPUT_FILE" "tool_input.command")"; then
+    UKIT_SALVAGE_ACTIVE=1
+  else
+    ukit_emit_permission_decision deny "UKit could not fully read this tool-call payload (stdin staging was cut at the deadline/size bound) and the command could not be recovered, so dangerous-command gate cannot prove it safe."
+  fi
+fi
 else
   # Runtime helper missing (pre-install tree): the SAME bounded staging,
   # inline - `cat >/dev/null` used to block forever on a producer that never
@@ -52,16 +64,22 @@ else
     # path's ukit_emit_input_degraded.
     rm -f "$UKIT_INPUT_FILE"
     UKIT_INPUT_FILE=""
-    # TASK-223: same emit shape as ukit_emit_permission_decision — under a
-    # direct host the JSON only reaches the permission pipeline on exit 0; the
-    # omp chain needs exit 2 (marker exported by hook-chain-runner.mjs).
-    printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"UKit could not fully read this tool-call payload (stdin staging was cut at the deadline/size bound), so dangerous-command gate cannot prove it safe. UKit defers this to a human decision."}}'
-    echo "BLOCKED: dangerous-command gate could not inspect a truncated/stalled payload; deferred to human." >&2
+    # TASK-223 + TASK-003: same emit shape as ukit_emit_permission_decision —
+    # under a direct host the JSON only reaches the permission pipeline on exit
+    # 0; the omp chain needs exit 2 (marker exported by hook-chain-runner.mjs).
+    # The decision is `deny`, never `ask`: bypassPermissions auto-approves ask.
+    printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"UKit could not fully read this tool-call payload (stdin staging was cut at the deadline/size bound), so dangerous-command gate cannot prove it safe."}}'
+    echo "BLOCKED: dangerous-command gate could not inspect a truncated/stalled payload; refused fail-closed." >&2
     if [ -n "${UKIT_HOOK_CHAIN_RUNNER:-}" ]; then exit 2; fi
     exit 0
   fi
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
 fi
+if [ "${UKIT_SALVAGE_ACTIVE:-0}" = "1" ]; then
+  # TASK-003: degraded path already recovered a COMPLETE command — skip the
+  # normal extraction (the staged prefix would not parse anyway).
+  COMMAND="$UKIT_SALVAGED_COMMAND"
+else
 INPUT="$(cat "$UKIT_INPUT_FILE")"
 # jq is not installed on stock macOS. Keep jq as the low-latency normal path, but use
 # UKit's required Node runtime as a fallback so its absence cannot silently disable the gate.
@@ -81,6 +99,7 @@ process.stdin.on("end", () => {
 });
 ' 2>/dev/null)
 fi
+fi
 
 if [ -z "$COMMAND" ]; then
   exit 0
@@ -168,6 +187,37 @@ SAFE_ONE_TARGET_REGEX='^(\./)?(dist|build|coverage|\.next|\.nuxt|\.turbo|tmp|tem
 UNSAFE_ONE_TARGET_REGEX='^(/.*|~|~/.*|\.\.|\.\./.*|\.)$'
 RM_WORD_REGEX=$'(^|[;&|[:space:]"\x27])rm([[:space:]"\x27]|$)'
 
+# TASK-013 / SPEC §10: canonical-path containment for the name allowlist. A
+# target that passes SAFE_ONE_TARGET_REGEX must ALSO resolve inside
+# realpath(projectRoot) — a `dist` symlinked outside the project (or a `..`
+# segment) downgrades the segment to the generic verdict, never allow.
+#
+# ukit_canonical_path mirrors GNU `realpath -m` semantics portably:
+#   1. `realpath -m` (GNU/coreutils) when supported;
+#   2. ONE documented fallback — stock macOS `realpath` cannot resolve
+#      nonexistent paths, so resolve the deepest existing ancestor and append
+#      the lexical remainder (equivalent for containment);
+#   3. `realpath` itself absent → empty output → fail closed (unresolved-
+#      generic), never silently allow.
+ukit_canonical_path() {
+  __u_p="$1"
+  __u_out=$(realpath -m -- "$__u_p" 2>/dev/null) && [ -n "$__u_out" ] && { printf '%s' "$__u_out"; return 0; }
+  __u_rest=""
+  while [ -n "$__u_p" ] && [ "$__u_p" != "/" ] && [ ! -e "$__u_p" ] && [ ! -L "$__u_p" ]; do
+    __u_rest="/${__u_p##*/}${__u_rest}"
+    __u_p="${__u_p%/*}"
+  done
+  [ -z "$__u_p" ] && __u_p="/"
+  __u_out=$(realpath -- "$__u_p" 2>/dev/null) || return 1
+  printf '%s%s' "$__u_out" "$__u_rest"
+}
+
+# Project-root canonical prefix, resolved once before the segment loop. Targets
+# are interpreted relative to the project root (the host's rm cwd), not the
+# hook's own cwd. An unresolvable root fails closed: no allowlist target can
+# prove containment against an unknown root.
+UKIT_PROJECT_ROOT_CANON=$(ukit_canonical_path "${CLAUDE_PROJECT_DIR:-$PWD}")
+
 RM_VERDICT_UNSAFE=0
 RM_VERDICT_GENERIC=0
 RM_DIRECT_SEEN=0
@@ -201,7 +251,24 @@ while IFS= read -r segment; do
       seg_any_unsafe=1
       seg_all_safe=0
     elif printf '%s' "$target" | grep -qE "$SAFE_ONE_TARGET_REGEX"; then
-      :
+      # Containment gate (TASK-013): the allowlisted NAME is not enough — the
+      # canonical target must live inside the canonical project root. `..`
+      # segments and unresolvable/missing realpath fail closed to generic.
+      case "$target" in
+        *..*) seg_all_safe=0 ;;
+        *)
+          case "$target" in /*) __t_abs="$target" ;; *) __t_abs="$UKIT_PROJECT_ROOT_CANON/$target" ;; esac
+          __t_canon=$(ukit_canonical_path "$__t_abs")
+          if [ -z "$UKIT_PROJECT_ROOT_CANON" ] || [ -z "$__t_canon" ]; then
+            seg_all_safe=0
+          else
+            case "$__t_canon" in
+              "$UKIT_PROJECT_ROOT_CANON"/*) : ;;
+              *) seg_all_safe=0 ;;
+            esac
+          fi
+          ;;
+      esac
     else
       seg_all_safe=0
     fi