@ngockhoale/ukit 2.6.9 → 2.6.11

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

@@ -52,9 +52,13 @@ 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
-    exit 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
@@ -115,15 +119,35 @@ DANGEROUS_PATTERNS=(
   "dd if=/dev/"
 )
 
-# Dangerous detections surface as a structured `ask` decision (stdout JSON) so a human
-# decides; exit 2 still refuses the call for harnesses that ignore structured output.
+# Dangerous detections surface as a structured decision (stdout JSON). TASK-223:
+# emission is centralized in ukit_emit_permission_decision — exit 0 on the direct
+# host (where a non-zero exit would discard the JSON as a bare "hook error"),
+# exit 2 inside the omp chain (whose bridge only parses stdout on code 2).
+# Probe verdict (2026-09-20, spec step 4): this repo runs
+# permissions.defaultMode=bypassPermissions, where an exit-0 `ask` auto-approves —
+# dead for refusals. So the direct host gets `deny` (a proper denied surface, still
+# fail-closed); the omp chain keeps `ask` (the host boundary prompts the human).
 # The raw command and the matched pattern are NEVER echoed — arguments and comments can
 # carry secrets, and the pattern text itself restates the dangerous command.
 emit_dangerous_decision() {
   REASON="$1"
-  printf '%s\n' "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"$REASON\"}}"
+  if command -v ukit_emit_permission_decision >/dev/null 2>&1; then
+    if [ -n "${UKIT_HOOK_CHAIN_RUNNER:-}" ]; then
+      ukit_emit_permission_decision ask "$REASON"
+    else
+      ukit_emit_permission_decision deny "$REASON"
+    fi
+  fi
+  # Helper unavailable (pre-install tree): keep the safe inline parity — the
+  # direct host gets deny + exit 0, the chain gets ask + exit 2.
+  if [ -n "${UKIT_HOOK_CHAIN_RUNNER:-}" ]; then
+    printf '%s\n' "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"$REASON\"}}"
+    echo "BLOCKED: $REASON" >&2
+    exit 2
+  fi
+  printf '%s\n' "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"$REASON\"}}"
   echo "BLOCKED: $REASON" >&2
-  exit 2
+  exit 0
 }
 
 for pattern in "${DANGEROUS_PATTERNS[@]}"; do

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

@@ -80,9 +80,12 @@ 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 — exit 0 on the
+    # direct host (non-zero discards stdout there), exit 2 inside the omp chain.
     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 context hard-cap gate cannot prove it safe. UKit defers this to a human decision."}}'
     echo "BLOCKED: context hard-cap gate could not inspect a truncated/stalled payload; deferred to human." >&2
-    exit 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

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

@@ -52,9 +52,12 @@ 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 — exit 0 on the
+    # direct host (non-zero discards stdout there), exit 2 inside the omp chain.
     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 protected-file gate cannot prove it safe. UKit defers this to a human decision."}}'
     echo "BLOCKED: protected-file gate could not inspect a truncated/stalled payload; deferred to human." >&2
-    exit 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
@@ -112,9 +115,29 @@ if [ -n "$PROTECTED_MATCH" ]; then
   # A stderr-only refusal can look like a silent stall when the host does not render
   # hook stderr. Do not expose the path/pattern on stdout: the generic explanation is
   # enough for the user and avoids leaking a potentially sensitive filename.
-  printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"UKit protected-file guard blocked this edit. Ask the user to modify the protected file manually."}}'
+  # TASK-223: emit through the centralized helper — exit 0 on the direct host so the
+  # structured decision survives (non-zero discards stdout there), exit 2 in the omp
+  # chain whose bridge parses stdout only on code 2. Probe verdict (2026-09-20):
+  # 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"
+    else
+      ukit_emit_permission_decision deny "$__ukit_protect_reason"
+    fi
+  fi
+  # Helper unavailable (pre-install tree): same decision/exit matrix inline.
+  if [ -n "${UKIT_HOOK_CHAIN_RUNNER:-}" ]; then
+    printf '%s\n' "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"$__ukit_protect_reason\"}}"
+    echo "BLOCKED: Cannot modify '$FILE_PATH' — matches protected pattern '$PROTECTED_MATCH'. Ask the user to modify this file manually." >&2
+    exit 2
+  fi
+  printf '%s\n' "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"$__ukit_protect_reason\"}}"
   echo "BLOCKED: Cannot modify '$FILE_PATH' — matches protected pattern '$PROTECTED_MATCH'. Ask the user to modify this file manually." >&2
-  exit 2
+  exit 0
 fi
 
 exit 0

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

@@ -0,0 +1,84 @@
+#!/bin/bash
+# session-episode.sh — SessionEnd hook: append a session episode to memory v2.
+#
+# Contract (SPEC §7b, TASK-231):
+#   * ALWAYS exits 0 — a session must never be blocked from ending.
+#   * No decision JSON — UKIT_HOOK_CHAIN_RUNNER-safe.
+#   * Runs `ukit memory episode` ONLY when
+#     .ukit/storage/config.json → learning.episodes.autoWrite === true
+#     (read defensively — the namespace may not exist yet) AND `ukit` resolves
+#     on PATH. Episode writes dedupe on meta.ledgerKey, so double-invocation is
+#     harmless.
+#   * Exports UKIT_SESSION_ID from the stdin payload's session_id so the CLI
+#     resolves the same exec-ledger file the session wrote.
+
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+CONFIG_FILE="$PROJECT_ROOT/.ukit/storage/config.json"
+
+# Bounded stdin read (existing hook style): cap +1 byte in background so a
+# producer that never closes the pipe cannot park the session teardown.
+UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-episode-in.XXXXXX")" || exit 0
+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.
+  ( sleep 2; kill "$UKIT_HEAD_PID" 2>/dev/null ) &
+  UKIT_WATCH_PID=$!
+  wait "$UKIT_HEAD_PID" 2>/dev/null
+  kill "$UKIT_WATCH_PID" 2>/dev/null
+fi
+
+# Gate + session extraction in one bounded node step; all failures → exit 0.
+# UKIT_HOOK_DEADLINE_MS:-5000 — keeps the registered 8s timeout comfortably
+# above stage (2s) + deadline (5s) + margin (1s).
+node -e '
+const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || "", 10) || 5000;
+setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
+
+const fs = require("fs");
+const { spawnSync } = require("child_process");
+
+const inputFile = process.argv[1];
+const configPath = process.argv[2];
+const projectRoot = process.argv[3];
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+let payload = {};
+try {
+  const raw = fs.readFileSync(inputFile, "utf8");
+  payload = JSON.parse(raw || "{}") || {};
+} catch {}
+
+const config = readJson(configPath) || {};
+if (config?.learning?.episodes?.autoWrite !== true) process.exit(0);
+
+const probe = spawnSync("ukit", ["--version"], {
+  shell: true, stdio: "ignore", timeout: 2000,
+});
+if (probe.error || probe.status === null || probe.status === undefined) process.exit(0);
+
+const sessionId = typeof payload.session_id === "string" && payload.session_id.trim()
+  ? payload.session_id.trim()
+  : null;
+
+spawnSync("ukit", ["memory", "episode"], {
+  shell: true,
+  stdio: "ignore",
+  timeout: 4000,
+  cwd: projectRoot,
+  env: sessionId
+    ? { ...process.env, UKIT_SESSION_ID: sessionId }
+    : process.env,
+});
+' "$UKIT_INPUT_FILE" "$CONFIG_FILE" "$PROJECT_ROOT" 2>/dev/null || true
+
+rm -f "$UKIT_INPUT_FILE" 2>/dev/null || true
+exit 0

package/templates/.claude/settings.json

@@ -253,6 +253,17 @@
           }
         ]
       }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/session-episode.sh\"",
+            "timeout": 8
+          }
+        ]
+      }
     ]
   }
 }

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

@@ -3793,6 +3793,12 @@ function buildRouteAuditEntry({ route = null, state = null } = {}) {
     }),
     targetFile: route?.routingContext?.targetFile ?? null,
     taskType: routingContext.taskType ?? null,
+    // FR-202a (TASK-228): active-skill ids for phase-2 skill-accuracy roll-ups.
+    // Telemetry only — deliberately excluded from dedupeKey/fingerprint inputs.
+    skillIds: (route?.activeSkills ?? state?.activeSkills ?? [])
+      .map((s) => s?.id)
+      .filter(Boolean)
+      .slice(0, 8),
     executionMode: routeSummary.executionMode ?? null,
     competingMode: routeSummary?.approachSelector?.competingMode ?? null,
     competingScoreGap: routeSummary?.approachSelector?.competingScoreGap ?? null,
@@ -3872,6 +3878,13 @@ function getMemoryTimestamp(item) {
 
 function buildMemorySegments(item) {
   const content = item.content ?? {};
+  if (item.type === 'record') {
+    return [
+      { text: content.recordType, weight: 1 },
+      { text: content.text, weight: 3 },
+    ];
+  }
+
   if (item.type === 'project') {
     return [
       { text: content.name, weight: 2 },
@@ -3964,6 +3977,7 @@ async function listMemoryItems(rootDir) {
   const userMemory = (await readJson(path.join(runtimeRoot, 'user.json'), null)) ?? { preferences: {}, rules: [] };
   const projectMemories = await readDirectoryJsonItems(path.join(runtimeRoot, 'projects'));
   const sessionMemories = await readDirectoryJsonItems(path.join(runtimeRoot, 'sessions'));
+  const recordMemories = await listMemoryV2RecordItems(runtimeRoot);
 
   return [
     {
@@ -3981,11 +3995,47 @@ async function listMemoryItems(rootDir) {
       type: 'session',
       content: item.content,
     })),
+    ...recordMemories,
   ];
 }
 
+const MEMORY_V2_RECORD_POOL_LIMIT = 20;
+
+// v2 lane (SI-101): approved records live in a single records.json document.
+// Missing/malformed store → [] (same never-throw discipline as
+// readDirectoryJsonItems). Candidates: status 'active' AND (valid_until == null
+// OR valid_until > now), capped at 20 newest by created_at.
+async function listMemoryV2RecordItems(runtimeRoot) {
+  const doc = await readJson(path.join(runtimeRoot, 'v2', 'records.json'), null);
+  const records = Array.isArray(doc?.records) ? doc.records : [];
+  const now = Date.now();
+
+  return records
+    .filter((record) => record && typeof record === 'object')
+    .filter((record) => record.status === 'active')
+    .filter((record) => record.valid_until == null || record.valid_until > now)
+    .sort((left, right) => (right.created_at ?? 0) - (left.created_at ?? 0))
+    .slice(0, MEMORY_V2_RECORD_POOL_LIMIT)
+    .map((record) => ({
+      id: `record:${record.id}`,
+      type: 'record',
+      content: {
+        recordType: record.type,
+        text: record.text,
+        projectId: record.project_id,
+        updatedAt: record.created_at,
+      },
+    }));
+}
+
 function buildPreviousContextSnippet(item) {
   const content = item.content ?? {};
+  if (item.type === 'record') {
+    const text = String(content.text ?? '').trim();
+    const truncated = text.length > 120 ? `${text.slice(0, 117)}...` : text;
+    return `[${content.recordType ?? 'record'}] ${truncated}`;
+  }
+
   if (item.type === 'project') {
     const decisions = compactPhraseList((content.decisions ?? []).map((decision) => decision.what), { limit: 1 });
     const rules = compactPhraseList(content.activeRules ?? [], { limit: 1 });
@@ -4036,11 +4086,18 @@ async function buildPreviousContextSnapshot({ rootDir = process.cwd(), routingCo
   const queryTokens = tokenize(taskQuery);
   const rankedItems = items
     .filter((item) => item.type !== 'user')
-    .filter((item) => (
-      item.type === 'project'
-        ? (item.content?.id === projectId)
-        : (item.type === 'session' ? item.content?.projectId === projectId : true)
-    ))
+    .filter((item) => {
+      if (item.type === 'project') {
+        return item.content?.id === projectId;
+      }
+      if (item.type === 'session') {
+        return item.content?.projectId === projectId;
+      }
+      if (item.type === 'record') {
+        return item.content?.projectId == null || item.content?.projectId === projectId;
+      }
+      return true;
+    })
     .map((item) => ({
       item,
       score: scoreMemoryItem(item, queryTokens),
@@ -4060,7 +4117,7 @@ async function buildPreviousContextSnapshot({ rootDir = process.cwd(), routingCo
   return {
     line: rankedItems.map((item) => buildPreviousContextSnippet(item)).join(' | '),
     selectedIds: rankedItems.map((item) => item.id),
-    fingerprint: buildCompactMachineKey('route-memory-v1', {
+    fingerprint: buildCompactMachineKey('route-memory-v2', {
       taskQuery: normalize(taskQuery),
       projectId,
       items: rankedItems.map((item) => ({

package/templates/.claude/ukit/runtime/hook-chain-runner.mjs

@@ -102,7 +102,15 @@ async function run(payloadText, scriptPaths) {
       deadlineMs: Math.min(childBudgetMs, remainingMs),
       maxBuffer: MAX_BUFFER_BYTES,
       cwd: projectRoot,
-      env: { ...process.env, CLAUDE_PROJECT_DIR: projectRoot },
+      // TASK-223 (HK-401): mark chain-spawned children so their structured
+      // permission decisions keep the omp contract (stdout parsed on exit 2).
+      // Direct Claude Code invocations carry no marker and exit 0 instead —
+      // a non-zero exit there discards stdout, killing the decision JSON.
+      env: {
+        ...process.env,
+        CLAUDE_PROJECT_DIR: projectRoot,
+        UKIT_HOOK_CHAIN_RUNNER: '1',
+      },
     });
     const failureKind = chainFailureKind(result);
     const code = Number.isFinite(result.code) ? result.code : 1;

package/templates/.claude/ukit/runtime/hook-input.sh

@@ -135,12 +135,35 @@ ukit_input_degraded() {
   [ "${UKIT_INPUT_TRUNCATED:-0}" = "1" ] || [ "${UKIT_HOOK_INPUT_STALLED:-0}" = "1" ]
 }
 
+# TASK-223 (HK-401): ALL PreToolUse structured permission decisions emit through
+# this one helper. The JSON shape is harness-agnostic, but the exit code is NOT:
+#   direct Claude Code (UKIT_HOOK_CHAIN_RUNNER unset) — a non-zero exit means the
+#     harness DISCARDS stdout, so a decision JSON + exit 2 is dead text rendered
+#     as a bare "hook error" with no human-approval path. Emit the JSON and exit 0
+#     so `deny`/`ask` actually reaches the permission pipeline. Under
+#     permissions.defaultMode=bypassPermissions `ask` is auto-approved (probe
+#     verdict 2026-09-20), so refusal call sites pass `deny` directly — the host
+#     surfaces a proper "denied" instead of a hook error, still fail-closed.
+#   omp chain (UKIT_HOOK_CHAIN_RUNNER=1, exported by hook-chain-runner.mjs) — the
+#     bridge parses hookSpecificOutput ONLY when the child exits 2; exit 0
+#     short-circuits to {block:false} and would turn every gate fail-open. Emit
+#     the JSON and exit 2 exactly as before.
+# stderr still carries the BLOCKED line on every path — the model needs the
+# block reason regardless of which stdout contract the harness honors.
+ukit_emit_permission_decision() {
+  local decision="${1:-ask}" reason="${2:-UKit deferred this tool call to a human decision.}"
+  printf '%s\n' "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"${decision}\",\"permissionDecisionReason\":\"${reason}\"}}"
+  echo "BLOCKED: ${reason}" >&2
+  if [ -n "${UKIT_HOOK_CHAIN_RUNNER:-}" ]; then
+    exit 2
+  fi
+  exit 0
+}
+
 ukit_emit_input_degraded() {
   local posture="${1:-advisory}" hook_name="${2:-hook}"
   if [ "$posture" = "failclosed" ]; then
-    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 ${hook_name} cannot prove it safe. UKit defers this to a human decision.\"}}"
-    echo "BLOCKED: ${hook_name} could not inspect a truncated/stalled payload; deferred to human." >&2
-    exit 2
+    ukit_emit_permission_decision ask "UKit could not fully read this tool-call payload (stdin staging was cut at the deadline/size bound), so ${hook_name} cannot prove it safe. UKit defers this to a human decision."
   fi
   printf '%s\n' "{\"systemMessage\":\"UKit ${hook_name}: tool-call payload was truncated or stalled during stdin staging; skipped this pass rather than act on incomplete input.\"}"
   exit 0

package/templates/docs/UKIT_INTERNALS.md

@@ -221,3 +221,20 @@ otherwise route to the specialist.
   - `.claude/skills/duraone/references/sql.md`
   - `.claude/skills/duraone/references/workflow.md`
 - Khi không active: dùng generic coding standards + project-specific patterns từ index.
+
+## Learning loop — detail
+
+Phase-4 telemetry → advisory tuning loop (FR-206, TASK-232).
+
+- **Config namespace `learning.*`** (optional-present; absent → defaults merge + valid):
+  - `learning.feedback.enabled` (default `true`) — gates `collectFeedbackEvents`.
+  - `learning.feedback.maxEvents` (default `200`) — cap on labeled feedback events.
+  - `learning.proposals.minCount` / `learning.proposals.minSessions` (defaults `3`/`2`) — pattern-proposal thresholds.
+  - `learning.episodes.autoWrite` (default `false`) — gates the SessionEnd episode hook.
+  - `learning.tuning.enabled` / `learning.tuning.applyMode` (defaults `true`/`'manual'`; `'off'` disables computation).
+- **Artifacts** (all under `.ukit/storage/`, written tmp+rename):
+  - `learning/feedback-events.json` — labeled wrong-route events (`rescue`, `re-route`, `repeat-stall`, `user-correction`).
+  - `learning/skill-accuracy.json` — per-skill trigger/join/accuracy roll-up.
+  - `learning/suggestions.json` — result of `computeTuningSuggestions(projectRoot)` (`src/learning/tuning.js`).
+  - `cache/retriever-lanes.jsonl` — per-query lane hit/weight telemetry consumed by `collectLaneStats`.
+- **Advisory-only contract**: `suggestions` carry `{target, current, suggested, evidence}`; `applied` is always `[]`. `applyMode` is restricted to `manual|off` — **no writer ever mutates `codeIntel.retriever.weights` or `orchestration.escalation.debugLoopThreshold`**. Rules: lane weight ±0.1 step (clamped `[0.1, 2.0]`) when events ≥ 50 with a >0.5 dominant lane and a <0.02 starved lane; `debugLoopThreshold − 1` (min 1) when repeat-stall events ≥ 10. `ukit metrics` prints a `learning` section (pending count + targets; `n/a` when the artifact is absent).

package/templates/ukit/storage/config.json

@@ -225,6 +225,12 @@
     "maxRetries": 1,
     "confidenceThreshold": 50
   },
+  "learning": {
+    "feedback": { "enabled": true, "maxEvents": 200 },
+    "proposals": { "minCount": 3, "minSessions": 2 },
+    "episodes": { "autoWrite": false },
+    "tuning": { "enabled": true, "applyMode": "manual" }
+  },
   "safePatch": {
     "enabled": true,
     "strictSharedRisk": true,
@@ -454,6 +460,18 @@
         "mac_dinh": true,
         "y_nghia": "Planner phải hoàn thành PLAN.md §4 (Test Plan) trước khi task chuyển ready. Tắt sẽ làm UKit cho phép skip TDD — kéo theo executor dễ làm sót.",
         "khuyen_nghi": "Giữ true."
+      },
+      "tu_ghi_episode_ket_thuc_session": {
+        "field": "learning.episodes.autoWrite",
+        "mac_dinh": false,
+        "y_nghia": "Nếu true, hook SessionEnd tự ghi episode vào memory v2 khi kết thúc session (cần `ukit` có trên PATH). Mặc định tắt để tránh ghi memory khi user chưa muốn.",
+        "khi_nao_bat": "Chỉ bật khi anh muốn UKit tự lưu episode mỗi session; dữ liệu vẫn nằm local trong .ukit/storage."
+      },
+      "tat_goi_y_tuning": {
+        "field": "learning.tuning.applyMode",
+        "mac_dinh": "manual",
+        "y_nghia": "manual = UKit chỉ tính và lưu gợi ý tuning vào .ukit/storage/learning/suggestions.json, KHÔNG bao giờ tự sửa weights/threshold. off = tắt luôn việc tính gợi ý.",
+        "khuyen_nghi": "Giữ manual. Không có chế độ auto-apply — mọi thay đổi weights/threshold đều do người dùng tự sửa."
       }
     },
     "version": "Phiên bản config runtime đi kèm package UKit.",