@ngockhoale/ukit 2.6.10 → 2.6.11

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/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,

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.",