@ngockhoale/ukit 2.6.10 → 2.6.11

package/src/core/memory/store.js

@@ -540,7 +540,8 @@ async function proposePatternCandidateV2(projectRoot, projectId, candidate) {
     .filter((record) => record.provenance === 'pattern-candidate'
       || String(record.provenance ?? '').includes('pattern-candidate'))
     .find((record) => record.meta?.legacyStatus === 'pending'
-      && normalizePatternText(record.text) === normalizedText);
+      && (normalizePatternText(record.text) === normalizedText
+        || (candidate?.signature && record.meta?.signature === candidate.signature)));
   if (existing) {
     return patternCandidateFromRecord(existing);
   }
@@ -553,6 +554,7 @@ async function proposePatternCandidateV2(projectRoot, projectId, candidate) {
     detectedAt: Date.now(),
     status: 'pending',
   };
+  if (candidate?.signature) entry.signature = candidate.signature;
 
   await v2.addRecord(projectRoot, {
     type: 'derived_fact',
@@ -626,7 +628,9 @@ export async function proposePatternCandidate(projectRoot, projectId, candidate)
 
   const patternCandidates = Array.isArray(memory.patternCandidates) ? memory.patternCandidates : [];
   const existingPending = patternCandidates.find(
-    (entry) => entry.status === 'pending' && normalizePatternText(entry.text) === normalizedText,
+    (entry) => entry.status === 'pending'
+      && (normalizePatternText(entry.text) === normalizedText
+        || (candidate?.signature && entry.signature === candidate.signature)),
   );
   if (existingPending) {
     return existingPending;
@@ -640,6 +644,7 @@ export async function proposePatternCandidate(projectRoot, projectId, candidate)
     detectedAt: Date.now(),
     status: 'pending',
   };
+  if (candidate?.signature) entry.signature = candidate.signature;
 
   memory.patternCandidates = [...patternCandidates, entry];
   await persistProjectMemoryWithHygiene(projectRoot, runtimePaths, projectId, filePath, memory);

package/src/core/runtimeConfig.js

@@ -209,6 +209,14 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       maxRetries: 1,
       confidenceThreshold: 50,
     },
+    // Phase-4 learning loop (SPEC §8a). Advisory only — applyMode 'manual'
+    // means suggestions are computed + persisted, never auto-applied.
+    learning: {
+      feedback: { enabled: true, maxEvents: 200 },
+      proposals: { minCount: 3, minSessions: 2 },
+      episodes: { autoWrite: false },
+      tuning: { enabled: true, applyMode: 'manual' },
+    },
     safePatch: {
       enabled: true,
       strictSharedRisk: true,
@@ -564,6 +572,51 @@ export function validateRuntimeConfig(config) {
     pushPositiveNumberError(errors, config.safePatch.deltaMaxDiffCells, 'safePatch.deltaMaxDiffCells');
   }
 
+  // learning is optional-present: absent → valid (old configs); present but
+  // not an object → error. Per-key checks apply only when the sub-object
+  // exists, so partial learning blocks stay valid via defaults merge.
+  if (config.learning !== undefined) {
+    if (!isPlainObject(config.learning)) {
+      errors.push('learning must be an object.');
+    } else {
+      const learning = config.learning;
+      if (learning.feedback !== undefined) {
+        if (!isPlainObject(learning.feedback)) {
+          errors.push('learning.feedback must be an object.');
+        } else {
+          pushBooleanError(errors, learning.feedback.enabled, 'learning.feedback.enabled');
+          pushPositiveNumberError(errors, learning.feedback.maxEvents, 'learning.feedback.maxEvents');
+        }
+      }
+      if (learning.proposals !== undefined) {
+        if (!isPlainObject(learning.proposals)) {
+          errors.push('learning.proposals must be an object.');
+        } else {
+          pushPositiveNumberError(errors, learning.proposals.minCount, 'learning.proposals.minCount');
+          pushPositiveNumberError(errors, learning.proposals.minSessions, 'learning.proposals.minSessions');
+        }
+      }
+      if (learning.episodes !== undefined) {
+        if (!isPlainObject(learning.episodes)) {
+          errors.push('learning.episodes must be an object.');
+        } else {
+          pushBooleanError(errors, learning.episodes.autoWrite, 'learning.episodes.autoWrite');
+        }
+      }
+      if (learning.tuning !== undefined) {
+        if (!isPlainObject(learning.tuning)) {
+          errors.push('learning.tuning must be an object.');
+        } else {
+          pushBooleanError(errors, learning.tuning.enabled, 'learning.tuning.enabled');
+          const VALID_APPLY_MODES = new Set(['manual', 'off']);
+          if (!VALID_APPLY_MODES.has(learning.tuning.applyMode)) {
+            errors.push(`learning.tuning.applyMode must be one of: ${[...VALID_APPLY_MODES].join(', ')}.`);
+          }
+        }
+      }
+    }
+  }
+
   if (!isPlainObject(config.subagents)) {
     errors.push('subagents must be an object.');
   } else {

package/src/diagnostics/failurePatterns.js

@@ -19,10 +19,9 @@
 
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { listLedgerFiles, LEDGER_DIR_REL } from './ledgerFiles.js';
 
-const LEDGER_DIR_REL = path.join('.ukit', 'storage', 'cache', 'exec-ledger');
 const ARTIFACT_REL = path.join('.ukit', 'storage', 'cache', 'failure-patterns.json');
-const NON_LEDGER_FILES = new Set(['gate-crash-counter.json']);
 const MAX_PATTERNS = 10;
 const MAX_EXAMPLES = 3;
 
@@ -33,14 +32,6 @@ function isObject(value) {
   return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
 
-function isLedgerFilename(name) {
-  if (typeof name !== 'string' || !name.endsWith('.json')) return false;
-  if (NON_LEDGER_FILES.has(name)) return false;
-  if (name.includes('.journal')) return false;
-  if (name.includes('.quarantine')) return false;
-  return true;
-}
-
 // First two whitespace tokens, lowercased; path-like or numeric tokens become `<arg>`.
 function normalizeSignature(command) {
   if (typeof command !== 'string') return null;
@@ -74,30 +65,6 @@ function failureCommands(ledger) {
   return out;
 }
 
-async function listLedgerFiles(dir, limit) {
-  let entries;
-  try {
-    entries = await fs.readdir(dir, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-  const files = [];
-  for (const entry of entries) {
-    if (!entry.isFile() || !isLedgerFilename(entry.name)) continue;
-    files.push(entry.name);
-  }
-  const withMtime = await Promise.all(files.map(async (name) => {
-    try {
-      const stat = await fs.stat(path.join(dir, name));
-      return { name, mtimeMs: stat.mtimeMs };
-    } catch {
-      return { name, mtimeMs: 0 };
-    }
-  }));
-  withMtime.sort((a, b) => b.mtimeMs - a.mtimeMs);
-  return withMtime.slice(0, limit).map((f) => f.name);
-}
-
 async function writeArtifact(filePath, result) {
   const dir = path.dirname(filePath);
   const tmp = path.join(dir, `.failure-patterns-${process.pid}.tmp`);

package/src/diagnostics/feedbackEvents.js

@@ -0,0 +1,196 @@
+// feedbackEvents.js — labeled wrong-route feedback events collector (SPEC C32 §3b).
+//
+// Derives labeled events from telemetry already on disk:
+//   * rescue          — route-audit entry with `rescueMode != null` → detail = rescueMode
+//   * re-route        — consecutive same-fingerprint audit entries where the later
+//                       entry changed executionMode (detail "<prev>→<new>")
+//   * repeat-stall    — audit `repeatCount >= minRepeat` with no matching
+//                       ledger `writeSucceeded` (join on requestKey)
+//   * user-correction — manual labels appended by `ukit feedback "<text>"` to
+//                       `.ukit/storage/cache/feedback-manual.jsonl`
+//
+// Contracts:
+//   * NEVER THROWS. Missing/malformed telemetry → zeroed result, `error` field
+//     on failure. Artifact write failure is non-fatal.
+//   * EVIDENCE-ONLY. The only side effect is the advisory artifact
+//     `.ukit/storage/learning/feedback-events.json` (tmp+rename).
+//   * Gated by config `learning?.feedback?.enabled !== false` (default true;
+//     the `learning` namespace lands in TASK-232 so the read is defensive).
+
+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 MANUAL_REL = path.join(CACHE_DIR_REL, 'feedback-manual.jsonl');
+const ARTIFACT_REL = path.join('.ukit', 'storage', 'learning', 'feedback-events.json');
+const CONFIG_REL = path.join('.ukit', 'storage', 'config.json');
+const MAX_EVENTS = 200;
+
+function isObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function zeroedResult(extra = {}) {
+  return {
+    generatedAt: new Date().toISOString(),
+    auditRowsScanned: 0,
+    ledgersScanned: 0,
+    byKind: { rescue: 0, 're-route': 0, 'repeat-stall': 0, 'user-correction': 0 },
+    events: [],
+    ...extra,
+  };
+}
+
+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;
+}
+
+// Manual jsonl is field-tolerant: unknown keys ignored, a legacy `context`
+// key is treated as an optional extra. Bad lines are skipped, not fatal.
+async function readManualEvents(projectRoot, byKind) {
+  const events = [];
+  let raw;
+  try {
+    raw = await fs.readFile(path.join(projectRoot, MANUAL_REL), 'utf8');
+  } catch {
+    return events;
+  }
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let record;
+    try {
+      record = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+    if (!isObject(record) || typeof record.text !== 'string') continue;
+    const event = {
+      ts: typeof record.ts === 'number' ? record.ts : 0,
+      kind: 'user-correction',
+      detail: record.text,
+      source: 'manual',
+    };
+    if (typeof record.targetFile === 'string') event.targetFile = record.targetFile;
+    events.push(event);
+    byKind['user-correction'] += 1;
+  }
+  return events;
+}
+
+async function writeArtifact(filePath, result) {
+  const dir = path.dirname(filePath);
+  const tmp = path.join(dir, `.feedback-events-${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 labeled wrong-route feedback events.
+ *
+ * @param {string} projectRoot repository root containing `.ukit/storage/`.
+ * @param {{ limitLedgers?: number, minRepeat?: number }} [options]
+ * @returns {Promise<{generatedAt: string, auditRowsScanned: number,
+ *   ledgersScanned: number, byKind: Record<string, number>,
+ *   events: Array<object>, error?: string}>} never throws.
+ */
+export async function collectFeedbackEvents(projectRoot, { limitLedgers = 500, minRepeat = 2 } = {}) {
+  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 writeOkKeys = new Set();
+    for (const name of ledgerNames) {
+      const ledger = await readJson(path.join(ledgerDir, name));
+      if (!isObject(ledger)) continue;
+      result.ledgersScanned += 1;
+      if (ledger.writeSucceeded === true && typeof ledger.requestKey === 'string') {
+        writeOkKeys.add(ledger.requestKey);
+      }
+    }
+
+    const events = [];
+    for (const entry of auditEntries) {
+      const base = {
+        ts: typeof entry.ts === 'number' ? entry.ts : 0,
+        requestKey: typeof entry.requestKey === 'string' ? entry.requestKey : undefined,
+        targetFile: typeof entry.targetFile === 'string' ? entry.targetFile : undefined,
+        taskType: typeof entry.taskType === 'string' ? entry.taskType : undefined,
+        executionMode: typeof entry.executionMode === 'string' ? entry.executionMode : undefined,
+        source: 'derived',
+      };
+
+      if (entry.rescueMode != null) {
+        events.push({ ...base, kind: 'rescue', detail: String(entry.rescueMode) });
+        result.byKind.rescue += 1;
+      }
+
+      if ((entry.repeatCount ?? 0) >= minRepeat && !writeOkKeys.has(entry.requestKey)) {
+        events.push({ ...base, kind: 'repeat-stall', detail: `repeatCount=${entry.repeatCount}` });
+        result.byKind['repeat-stall'] += 1;
+      }
+    }
+
+    // re-route: audit is newest-first — entry i is the later entry, i+1 the
+    // previous one for the same promptFingerprint + targetFile.
+    for (let i = 0; i < auditEntries.length - 1; i += 1) {
+      const later = auditEntries[i];
+      const prev = auditEntries[i + 1];
+      if (typeof later.promptFingerprint !== 'string' || !later.promptFingerprint) continue;
+      if (later.promptFingerprint !== prev.promptFingerprint) continue;
+      if (later.targetFile !== prev.targetFile) continue;
+      if (later.wideningBlocked === true) continue;
+      const prevMode = prev.executionMode;
+      const newMode = later.executionMode;
+      if (prevMode == null || newMode == null || prevMode === newMode) continue;
+      events.push({
+        ts: typeof later.ts === 'number' ? later.ts : 0,
+        kind: 're-route',
+        requestKey: typeof later.requestKey === 'string' ? later.requestKey : undefined,
+        targetFile: typeof later.targetFile === 'string' ? later.targetFile : undefined,
+        taskType: typeof later.taskType === 'string' ? later.taskType : undefined,
+        executionMode: typeof later.executionMode === 'string' ? later.executionMode : undefined,
+        detail: `${prevMode}→${newMode}`,
+        source: 'derived',
+      });
+      result.byKind['re-route'] += 1;
+    }
+
+    events.push(...await readManualEvents(projectRoot, result.byKind));
+
+    events.sort((a, b) => b.ts - a.ts);
+    result.events = events.slice(0, MAX_EVENTS);
+  } catch (error) {
+    result.error = error?.message ?? String(error);
+  }
+
+  await writeArtifact(path.join(projectRoot, ARTIFACT_REL), result);
+  return result;
+}

package/src/diagnostics/laneStats.js

@@ -0,0 +1,111 @@
+// laneStats.js — retriever lane contribution stats (SPEC C32 §5b).
+//
+// Reads `.ukit/storage/cache/retriever-lanes.jsonl` emitted by the retriever
+// (FR-202b) and rolls up per-lane counters:
+//   retrievals   = events where the lane had hits > 0
+//   totalHits    = sum of lane hits
+//   exclusive    = events where this lane was the SOLE lane with hits > 0
+//                  (emitters record per-lane hit counts only, so exclusivity
+//                  is approximated rather than per-path recomputed)
+//   avgWeight    = mean weightUsed over events that recorded one
+//   contribution = retrievals / max(1, events)
+//
+// Contracts: NEVER THROWS — missing/empty file → `empty: true` + zeroed lanes.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const LANES_REL = path.join('.ukit', 'storage', 'cache', 'retriever-lanes.jsonl');
+
+function isObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function zeroedResult(extra = {}) {
+  return {
+    generatedAt: new Date().toISOString(),
+    events: 0,
+    lanes: {},
+    empty: false,
+    ...extra,
+  };
+}
+
+function emptyLaneBucket() {
+  return {
+    retrievals: 0,
+    totalHits: 0,
+    exclusive: 0,
+    avgWeight: 0,
+    contribution: 0,
+    _weightSum: 0,
+    _weightCount: 0,
+  };
+}
+
+/**
+ * Collect retriever lane contribution stats.
+ *
+ * @param {string} projectRoot repository root containing `.ukit/storage/`.
+ * @param {{ maxEvents?: number }} [options]
+ * @returns {Promise<object>} never throws.
+ */
+export async function collectLaneStats(projectRoot, { maxEvents = 2000 } = {}) {
+  const result = zeroedResult();
+  try {
+    let raw;
+    try {
+      raw = await fs.readFile(path.join(projectRoot, LANES_REL), 'utf8');
+    } catch {
+      return { ...result, empty: true };
+    }
+    const lines = raw.split('\n');
+    const events = [];
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        const record = JSON.parse(trimmed);
+        if (isObject(record) && isObject(record.lanes)) events.push(record);
+      } catch {
+        // skip malformed line
+      }
+      if (events.length >= maxEvents) break;
+    }
+    if (events.length === 0) {
+      return { ...result, empty: true };
+    }
+    result.events = events.length;
+
+    for (const event of events) {
+      const positive = [];
+      for (const [lane, stats] of Object.entries(event.lanes)) {
+        if (!isObject(stats)) continue;
+        const bucket = result.lanes[lane] ??= emptyLaneBucket();
+        const hits = typeof stats.hits === 'number' ? stats.hits : 0;
+        if (hits > 0) {
+          bucket.retrievals += 1;
+          bucket.totalHits += hits;
+          positive.push(lane);
+        }
+        if (typeof stats.weightUsed === 'number') {
+          bucket._weightSum += stats.weightUsed;
+          bucket._weightCount += 1;
+        }
+      }
+      if (positive.length === 1) {
+        result.lanes[positive[0]].exclusive += 1;
+      }
+    }
+
+    for (const bucket of Object.values(result.lanes)) {
+      bucket.avgWeight = bucket._weightCount === 0 ? 0 : bucket._weightSum / bucket._weightCount;
+      bucket.contribution = bucket.retrievals / Math.max(1, result.events);
+      delete bucket._weightSum;
+      delete bucket._weightCount;
+    }
+  } catch (error) {
+    result.error = error?.message ?? String(error);
+  }
+  return result;
+}

package/src/diagnostics/ledgerFiles.js

@@ -0,0 +1,47 @@
+// ledgerFiles.js — shared exec-ledger directory helpers (SPEC C32 §3a).
+//
+// Extracted from failurePatterns.js so feedbackEvents (and any future
+// ledger-scanning diagnostics) share one glob/mtime discipline:
+//   * glob `*.json`, skip `gate-crash-counter.json`, `*.journal*`,
+//     `*.quarantine*`, bound results by mtime-desc order.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export const LEDGER_DIR_REL = path.join('.ukit', 'storage', 'cache', 'exec-ledger');
+
+const NON_LEDGER_FILES = new Set(['gate-crash-counter.json']);
+
+export function isLedgerFilename(name) {
+  if (typeof name !== 'string' || !name.endsWith('.json')) return false;
+  if (NON_LEDGER_FILES.has(name)) return false;
+  if (name.includes('.journal')) return false;
+  if (name.includes('.quarantine')) return false;
+  return true;
+}
+
+// Returns up to `limit` ledger filenames sorted by mtime descending.
+// Missing/unreadable dir → [] (never throws).
+export async function listLedgerFiles(dir, limit) {
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !isLedgerFilename(entry.name)) continue;
+    files.push(entry.name);
+  }
+  const withMtime = await Promise.all(files.map(async (name) => {
+    try {
+      const stat = await fs.stat(path.join(dir, name));
+      return { name, mtimeMs: stat.mtimeMs };
+    } catch {
+      return { name, mtimeMs: 0 };
+    }
+  }));
+  withMtime.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return withMtime.slice(0, Math.max(0, limit)).map((f) => f.name);
+}

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;
+}