@ngockhoale/ukit 3.5.1 → 3.5.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/CHANGELOG.md +35 -297
  2. package/README.md +1 -0
  3. package/manifests/platform.full.yaml +23 -0
  4. package/package.json +8 -1
  5. package/src/cli/commands/doctor.js +14 -2
  6. package/src/cli/commands/memory.js +30 -2
  7. package/src/core/memory/memoryHit.js +2 -0
  8. package/src/core/memory/mutateMemory.js +9 -0
  9. package/src/core/memory/projectIdentity.js +9 -2
  10. package/src/core/memory/recallEngine.js +86 -4
  11. package/src/core/memory/registryPrune.js +230 -0
  12. package/src/core/memory/retrieval.js +12 -3
  13. package/src/core/runtimeConfig.js +1 -0
  14. package/src/index/buildIndex.js +22 -0
  15. package/src/index/impactContext.js +11 -1
  16. package/src/index/queryIndex.js +151 -20
  17. package/template_project/.claude/hooks/edit-hint.mjs +119 -0
  18. package/template_project/.claude/settings.json +2 -2
  19. package/template_project/.claude/ukit/index/edit-graph.mjs +404 -0
  20. package/template_project/.claude/ukit/index/lib/index-core.mjs +185 -20
  21. package/template_project/.claude/ukit/index/post-edit-verify.mjs +8 -5
  22. package/template_project/.claude/ukit/index/resolve-context.mjs +17 -0
  23. package/template_project/.claude/ukit/index/route-task.mjs +4 -1
  24. package/template_project/.claude/ukit/runtime/hook-chain-runner.mjs +62 -5
  25. package/template_project/.claude/ukit/runtime/memory-lanes.mjs +259 -0
  26. package/template_project/.claude/ukit/runtime/memory-recall.mjs +86 -4
  27. package/template_project/.claude/ukit/runtime/memory-validity.mjs +232 -0
  28. package/template_project/.claude/ukit/runtime/reinject-context.mjs +4 -2
  29. package/template_project/.omp/hooks/pre/ukit-bridge.js +2 -1
  30. package/template_project/AGENTS.md +1 -1
  31. package/template_project/CLAUDE.md +1 -1
  32. package/template_project/instructions/core.md +1 -1
  33. package/src/core/observability/evaluation/experimentPlan.js +0 -95
  34. package/src/core/observability/evaluation/perturbation.js +0 -273
  35. package/src/diagnostics/classifyHang.js +0 -246
  36. package/src/diagnostics/ompStallSnapshot.js +0 -199
  37. package/src/render/instructionRenderer.js +0 -290
  38. package/src/skill/auditSkill.js +0 -140
  39. package/template_project/instructions/overlays/repo.md +0 -9
@@ -78,7 +78,7 @@ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5
78
78
  return QUERY_RESULT_CACHE.get(queryCacheKey);
79
79
  }
80
80
  const queryPromise = (async () => {
81
- const { files, searchDescriptorsByFile } = await loadQuerySearchBundle(absoluteRoot);
81
+ const { files, searchDescriptorsByFile, tokenWeights } = await loadQuerySearchBundle(absoluteRoot);
82
82
  const preferredArchetypes = inferPreferredArchetypes(queryDescriptor.tokens);
83
83
  const includeLikelyTestFiles = shouldIncludeLikelyTestFiles(queryDescriptor);
84
84
 
@@ -92,8 +92,10 @@ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5
92
92
  const searchDescriptor = searchDescriptorsByFile.get(filePath) ?? createFileSearchDescriptor({ filePath, symbols: [] });
93
93
  const { score, reasons } = scoreDirectFileMatch({
94
94
  queryDescriptor,
95
+ rawQuery: normalizedQuery,
95
96
  filePath,
96
97
  searchDescriptor,
98
+ tokenWeights,
97
99
  });
98
100
 
99
101
  if (score > 0) {
@@ -141,13 +143,17 @@ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5
141
143
  importersByTarget,
142
144
  testsMapBySource,
143
145
  });
144
- const finalScores = applyHotspotBoosts({
145
- scores: relatedScores,
146
- hotspotScores,
146
+ const finalScores = capBoostLift({
147
+ directScores,
148
+ scores: applyHotspotBoosts({
149
+ scores: relatedScores,
150
+ hotspotScores,
151
+ }),
147
152
  });
148
153
 
149
154
  return freezeQueryResults(
150
155
  [...finalScores.values()]
156
+ .map((entry) => ({ ...entry, score: finalizeScore(entry) }))
151
157
  .sort((a, b) => b.score - a.score || a.filePath.localeCompare(b.filePath))
152
158
  .slice(0, limit),
153
159
  );
@@ -259,9 +265,11 @@ async function loadQuerySearchBundle(rootDir) {
259
265
  const safeFiles = safeSchemaArtifact(files);
260
266
  const safeSymbols = safeSchemaArtifact(symbols);
261
267
  const symbolMap = groupBy(safeItems(safeSymbols), (item) => item.filePath);
268
+ const searchDescriptorsByFile = buildFileSearchDescriptors(safeItems(safeFiles), symbolMap);
262
269
  return {
263
270
  files: safeFiles,
264
- searchDescriptorsByFile: buildFileSearchDescriptors(safeItems(safeFiles), symbolMap),
271
+ searchDescriptorsByFile,
272
+ tokenWeights: buildTokenWeights(searchDescriptorsByFile),
265
273
  };
266
274
  })
267
275
  .catch((error) => {
@@ -330,9 +338,91 @@ function dedupe(values) {
330
338
  return [...new Set(values)];
331
339
  }
332
340
 
333
- function scoreDirectFileMatch({ queryDescriptor, filePath, searchDescriptor }) {
341
+ // ── Ranking constants (kept identical in template index-core.mjs) ──
342
+ const PATH_EXACT_SCORE = 60;
343
+ const PATH_SUFFIX_SCORE = 48;
344
+ const PATH_BASENAME_SCORE = 40;
345
+ const SYMBOL_EXACT_SCORE = 40;
346
+ const SYMBOL_DECAY = 0.35; // k-th best symbol of a file adds score * SYMBOL_DECAY^k
347
+ const SYMBOL_REASON_LIMIT = 3;
348
+ const MIN_SUBSTRING_TOKEN_LENGTH = 3;
349
+ const BOOST_LIFT_RATIO = 0.2; // import/hotspot/archetype boosts may add at most this share of a direct score (+1)
350
+ const BOOST_ONLY_RATIO = 0.3; // files with no direct match stay below this share of the best direct score
351
+
352
+ // Rarity weight per token in (0,1]: a token present in nearly every file is worth
353
+ // ~ln2/ln(1+N), a token unique to one file is worth 1. Computed once per bundle.
354
+ function buildTokenWeights(searchDescriptorsByFile) {
355
+ const docFrequency = new Map();
356
+ for (const descriptor of searchDescriptorsByFile.values()) {
357
+ const seen = new Set(descriptor.path.tokens);
358
+ for (const symbol of descriptor.symbols) {
359
+ for (const token of symbol.descriptor.tokens) {
360
+ seen.add(token);
361
+ }
362
+ }
363
+ for (const token of seen) {
364
+ docFrequency.set(token, (docFrequency.get(token) ?? 0) + 1);
365
+ }
366
+ }
367
+ const total = searchDescriptorsByFile.size;
368
+ const denominator = Math.log(1 + total) || 1;
369
+ const weights = new Map();
370
+ for (const [token, count] of docFrequency) {
371
+ weights.set(token, Math.max(0.05, Math.log(1 + total / count) / denominator));
372
+ }
373
+ return weights;
374
+ }
375
+
376
+ // Prior applied after scoring so an original beats its mirror copy on ties without
377
+ // hiding the mirror: root installed copies < template_project < everything else.
378
+ function mirrorPrior(filePath) {
379
+ if (/^\.(?:claude|codex|omp)\//.test(filePath)) {
380
+ return 0.88;
381
+ }
382
+ if (filePath.startsWith('template_project/')) {
383
+ return 0.94;
384
+ }
385
+ return 1;
386
+ }
387
+
388
+ function normalizePathQuery(rawQuery) {
389
+ const value = String(rawQuery ?? '').trim().toLowerCase().replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '');
390
+ return value.length >= 3 && !/\s/.test(value) ? value : '';
391
+ }
392
+
393
+ // Exact path / path-suffix (whole segments) / basename match for single-term queries.
394
+ function scorePathQuery(pathQuery, filePath) {
395
+ if (!pathQuery) {
396
+ return null;
397
+ }
398
+ const lower = filePath.toLowerCase();
399
+ const noExt = lower.replace(/\.[a-z0-9]+$/, '');
400
+ if (pathQuery === lower) {
401
+ return { score: PATH_EXACT_SCORE, reason: `path_exact:${filePath}` };
402
+ }
403
+ if (pathQuery.includes('/')) {
404
+ if (noExt === pathQuery || lower.endsWith(`/${pathQuery}`) || noExt.endsWith(`/${pathQuery}`)) {
405
+ return { score: PATH_SUFFIX_SCORE, reason: `path_suffix:${pathQuery}` };
406
+ }
407
+ return null;
408
+ }
409
+ const base = lower.slice(lower.lastIndexOf('/') + 1);
410
+ if (pathQuery === base || pathQuery === base.replace(/\.[a-z0-9]+$/, '')) {
411
+ return { score: PATH_BASENAME_SCORE, reason: `path_basename:${pathQuery}` };
412
+ }
413
+ return null;
414
+ }
415
+
416
+ function scoreDirectFileMatch({ queryDescriptor, rawQuery = '', filePath, searchDescriptor, tokenWeights = null }) {
334
417
  let score = 0;
335
418
  const reasons = [];
419
+ const weightOf = (token) => tokenWeights?.get(token) ?? 1;
420
+
421
+ const pathHit = scorePathQuery(normalizePathQuery(rawQuery), filePath);
422
+ if (pathHit) {
423
+ score += pathHit.score;
424
+ reasons.push(pathHit.reason);
425
+ }
336
426
 
337
427
  if (
338
428
  queryDescriptor.compact.length >= 6
@@ -344,43 +434,45 @@ function scoreDirectFileMatch({ queryDescriptor, filePath, searchDescriptor }) {
344
434
 
345
435
  for (const token of queryDescriptor.tokens) {
346
436
  if (searchDescriptor.path.tokens.has(token)) {
347
- score += 3;
437
+ score += 3 * weightOf(token);
348
438
  reasons.push(`path_token:${token}`);
349
- } else if (searchDescriptor.path.rawLower.includes(token)) {
350
- score += 1;
439
+ } else if (token.length >= MIN_SUBSTRING_TOKEN_LENGTH && searchDescriptor.path.rawLower.includes(token)) {
440
+ score += weightOf(token);
351
441
  reasons.push(`path_contains:${token}`);
352
442
  }
353
443
  }
354
444
 
445
+ const symbolHits = [];
355
446
  for (const symbolDescriptor of searchDescriptor.symbols) {
356
447
  if (
357
448
  queryDescriptor.compact.length >= 4
358
449
  && symbolDescriptor.descriptor.compact === queryDescriptor.compact
359
450
  ) {
360
- score += 8;
361
- reasons.push(`symbol_exact:${symbolDescriptor.name}`);
451
+ symbolHits.push({ score: SYMBOL_EXACT_SCORE, reasons: [`symbol_exact:${symbolDescriptor.name}`] });
362
452
  continue;
363
453
  }
364
454
 
455
+ let symbolScore = 0;
456
+ const symbolReasons = [];
365
457
  if (
366
458
  queryDescriptor.compact.length >= 6
367
459
  && symbolDescriptor.descriptor.compact.includes(queryDescriptor.compact)
368
460
  ) {
369
- score += 5;
370
- reasons.push(`symbol_compact:${symbolDescriptor.name}`);
461
+ symbolScore += 5;
462
+ symbolReasons.push(`symbol_compact:${symbolDescriptor.name}`);
371
463
  }
372
464
 
373
465
  let symbolContributed = false;
374
466
 
375
467
  for (const token of queryDescriptor.tokens) {
376
468
  if (symbolDescriptor.descriptor.tokens.has(token)) {
377
- score += 3;
469
+ symbolScore += 3 * weightOf(token);
378
470
  symbolContributed = true;
379
- reasons.push(`symbol_token:${symbolDescriptor.name}:${token}`);
380
- } else if (symbolDescriptor.descriptor.rawLower.includes(token)) {
381
- score += 1;
471
+ symbolReasons.push(`symbol_token:${symbolDescriptor.name}:${token}`);
472
+ } else if (token.length >= MIN_SUBSTRING_TOKEN_LENGTH && symbolDescriptor.descriptor.rawLower.includes(token)) {
473
+ symbolScore += weightOf(token);
382
474
  symbolContributed = true;
383
- reasons.push(`symbol_contains:${symbolDescriptor.name}`);
475
+ symbolReasons.push(`symbol_contains:${symbolDescriptor.name}`);
384
476
  }
385
477
  }
386
478
 
@@ -390,12 +482,28 @@ function scoreDirectFileMatch({ queryDescriptor, filePath, searchDescriptor }) {
390
482
  // from the stronger tiers above.
391
483
  if (!symbolContributed && queryDescriptor.compact.length >= 6) {
392
484
  if (symbolFuzzyMatches(queryDescriptor.compact, symbolDescriptor.descriptor.compact)) {
393
- score += 3;
394
- reasons.push(`symbol_fuzzy:${symbolDescriptor.name}`);
485
+ symbolScore += 3;
486
+ symbolReasons.push(`symbol_fuzzy:${symbolDescriptor.name}`);
395
487
  }
396
488
  }
489
+
490
+ if (symbolScore > 0) {
491
+ symbolHits.push({ score: symbolScore, reasons: symbolReasons });
492
+ }
397
493
  }
398
494
 
495
+ // Best symbol dominates; further symbols add with sharp diminishing returns so
496
+ // file size (symbol count) cannot outvote match quality.
497
+ symbolHits.sort((a, b) => b.score - a.score);
498
+ let decay = 1;
499
+ symbolHits.forEach((hit, index) => {
500
+ score += hit.score * decay;
501
+ decay *= SYMBOL_DECAY;
502
+ if (index < SYMBOL_REASON_LIMIT) {
503
+ reasons.push(...hit.reasons);
504
+ }
505
+ });
506
+
399
507
  return {
400
508
  score,
401
509
  reasons: dedupe(reasons),
@@ -403,6 +511,29 @@ function scoreDirectFileMatch({ queryDescriptor, filePath, searchDescriptor }) {
403
511
  };
404
512
  }
405
513
 
514
+ // Import-graph, hotspot and archetype boosts are context, not evidence: they may
515
+ // reorder near-equal direct matches but never lift a weak match over a strong one,
516
+ // and files with no direct match stay below the best direct match.
517
+ function capBoostLift({ directScores, scores }) {
518
+ let maxDirect = 0;
519
+ for (const entry of directScores.values()) {
520
+ maxDirect = Math.max(maxDirect, entry.score);
521
+ }
522
+ for (const [filePath, entry] of scores) {
523
+ const base = directScores.get(filePath)?.score;
524
+ if (base === undefined) {
525
+ entry.score = Math.min(entry.score, BOOST_ONLY_RATIO * maxDirect);
526
+ } else {
527
+ entry.score = base + Math.min(Math.max(entry.score - base, 0), BOOST_LIFT_RATIO * base + 1);
528
+ }
529
+ }
530
+ return scores;
531
+ }
532
+
533
+ function finalizeScore(entry) {
534
+ return Number((entry.score * mirrorPrior(entry.filePath)).toFixed(2));
535
+ }
536
+
406
537
  function groupBy(items, keyFn) {
407
538
  const map = new Map();
408
539
  for (const item of items) {
@@ -0,0 +1,119 @@
1
+ // edit-hint.mjs — PostToolUse Edit|Write chain step (advisory, always code 0).
2
+ // After a successful edit of file X, hands the MODEL the edit-graph hint once per
3
+ // file per task (mirror to fix, tests to run, cited memory). Claude Code: JSON
4
+ // hookSpecificOutput.additionalContext; omp: the bridge appends stdout verbatim,
5
+ // so plain text. Async fs only; self-deadline 400 ms; any failure emits nothing.
6
+ import fsp from 'node:fs/promises';
7
+ import path from 'node:path';
8
+
9
+ const DEADLINE_MS = 400; // once per file per task; the step slot is 8 s
10
+ const MEMORY_MS = 250; // memory sub-budget: a miss still emits mirrors/tests
11
+ const MAX_SEEN = 200;
12
+ const MAX_BYTES = 16 * 1024;
13
+ const NONE = { code: 0, stdout: '', stderr: '' };
14
+ const safe = (v, d) => String(v || d).replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 80) || d;
15
+ const readJson = async (file) => {
16
+ try { return JSON.parse(await fsp.readFile(file, 'utf8')); } catch { return null; }
17
+ };
18
+
19
+ // Retention: over 64 entries, drop this step's own `<safe>.<safe>.json` files older than 7 days (max 32 deletions, 128 stats per run). Fire-and-forget.
20
+ async function prune(dir, keep) {
21
+ try {
22
+ const names = await fsp.readdir(dir);
23
+ if (names.length <= 64) return;
24
+ let left = 32;
25
+ let stats = 128;
26
+ for (const n of names) {
27
+ if (left <= 0 || stats <= 0) break;
28
+ if (n === keep || !/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.json$/.test(n)) continue;
29
+ stats -= 1;
30
+ try {
31
+ const f = path.join(dir, n);
32
+ if (Date.now() - (await fsp.stat(f)).mtimeMs <= 7 * 864e5) continue;
33
+ await fsp.unlink(f);
34
+ left -= 1;
35
+ } catch { /* ignore */ }
36
+ }
37
+ } catch { /* retention is best-effort */ }
38
+ }
39
+
40
+ async function hint(ctx, signal, commit) {
41
+ const { payload: p = {}, projectRoot, env = {} } = ctx;
42
+ if (env.UKIT_EDIT_HINTS === '0' || process.env.UKIT_EDIT_HINTS === '0') return NONE;
43
+ if (!['Edit', 'Write'].includes(p.tool_name) || !projectRoot) return NONE;
44
+ const res = p.tool_response;
45
+ if (res && (res.is_error === true || res.isError === true || res.success === false)) return NONE;
46
+ const raw = p.tool_input?.file_path;
47
+ if (typeof raw !== 'string' || !raw) return NONE;
48
+ const rel = path.relative(projectRoot, path.resolve(p.cwd || projectRoot, raw)).split(path.sep).join('/');
49
+ if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return NONE;
50
+
51
+ const config = await readJson(path.join(projectRoot, '.ukit/storage/config.json'));
52
+ if (config?.memory?.editHints?.enabled === false) return NONE;
53
+ const route = await readJson(path.join(projectRoot, '.claude/ukit/skill-router-state.json'));
54
+ const session = safe(p.session_id, 'nosession');
55
+ const task = typeof route?.taskInstanceId === 'string' && route.taskInstanceId ? route.taskInstanceId : session;
56
+ const stateFile = path.join(projectRoot, '.ukit/storage/cache/edit-hints', `${session}.${safe(p.agent_id, 'main')}.json`);
57
+ const prev = await readJson(stateFile);
58
+ const st = prev && prev.task === task && Array.isArray(prev.seen)
59
+ ? { task, seen: prev.seen.filter((x) => typeof x === 'string'), shownMem: Array.isArray(prev.shownMem) ? prev.shownMem.filter((x) => typeof x === 'string') : [] }
60
+ : { task, seen: [], shownMem: [] };
61
+ if (st.seen.includes(rel)) return NONE;
62
+
63
+ const lanes = await import('../ukit/runtime/memory-lanes.mjs');
64
+ const out = await lanes.editHintFor({
65
+ projectRoot, target: rel, config: config ?? {}, signal, memoryBudgetMs: MEMORY_MS,
66
+ exclude: { paths: st.seen, memoryIds: st.shownMem },
67
+ });
68
+ if (signal.aborted) return NONE;
69
+ // Memory missed its budget and there is no graph text: not "nothing to say", retry next edit.
70
+ if (out?.memoryMissed && !out.text) return NONE;
71
+
72
+ // Commit point: once state is being marked, finish and emit (a few ms of fs) so a
73
+ // deadline firing mid-write can never mark the file seen without delivering the hint.
74
+ commit.on = true;
75
+ st.seen.push(rel);
76
+ st.shownMem.push(...(out?.memoryIds || []));
77
+ st.seen = st.seen.slice(-MAX_SEEN);
78
+ st.shownMem = st.shownMem.slice(-MAX_SEEN);
79
+ let body = JSON.stringify(st);
80
+ while (body.length > MAX_BYTES && st.seen.length > 1) {
81
+ st.seen.shift();
82
+ st.shownMem.shift();
83
+ body = JSON.stringify(st);
84
+ }
85
+ try {
86
+ await fsp.mkdir(path.dirname(stateFile), { recursive: true });
87
+ const tmp = `${stateFile}.${process.pid}.tmp`;
88
+ await fsp.writeFile(tmp, body);
89
+ await fsp.rename(tmp, stateFile);
90
+ } catch { /* state is best-effort */ }
91
+ void prune(path.dirname(stateFile), path.basename(stateFile));
92
+
93
+ const text = typeof out?.text === 'string' ? out.text.trim() : '';
94
+ if (!text) return NONE;
95
+ const omp = p.ukit_harness === 'omp' || env.UKIT_HARNESS === 'omp';
96
+ const stdout = omp
97
+ ? `${text}\n`
98
+ : `${JSON.stringify({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: text } })}\n`;
99
+ return { code: 0, stdout, stderr: '' };
100
+ }
101
+
102
+ export async function runHook(ctx = {}) {
103
+ const ac = new AbortController();
104
+ const commit = { on: false };
105
+ const ms = Math.min(DEADLINE_MS, Number.isFinite(ctx.deadlineMs) ? ctx.deadlineMs : DEADLINE_MS);
106
+ const timer = setTimeout(() => ac.abort(), Math.max(1, ms));
107
+ const outer = ctx.signal;
108
+ if (outer) outer.aborted ? ac.abort() : outer.addEventListener('abort', () => ac.abort(), { once: true });
109
+ try {
110
+ return await Promise.race([
111
+ hint(ctx, ac.signal, commit),
112
+ new Promise((resolve) => ac.signal.addEventListener('abort', () => { if (!commit.on) resolve(NONE); }, { once: true })),
113
+ ]);
114
+ } catch {
115
+ return NONE;
116
+ } finally {
117
+ clearTimeout(timer);
118
+ }
119
+ }
@@ -146,8 +146,8 @@
146
146
  "hooks": [
147
147
  {
148
148
  "type": "command",
149
- "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/post-edit-verify.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/record-execution.mjs\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/task-watchdog.sh\":8",
150
- "timeout": 34
149
+ "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/post-edit-verify.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/record-execution.mjs\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/task-watchdog.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/edit-hint.mjs\":8",
150
+ "timeout": 42
151
151
  }
152
152
  ]
153
153
  },