@ngockhoale/ukit 3.5.2 → 3.5.4

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 (75) hide show
  1. package/CHANGELOG.md +38 -90
  2. package/README.md +1 -0
  3. package/manifests/documentation.yaml +12 -1
  4. package/manifests/platform.full.yaml +12 -0
  5. package/package.json +34 -1
  6. package/src/cli/commands/doctor.js +55 -2
  7. package/src/cli/commands/indexTools.js +10 -4
  8. package/src/cli/commands/memory.js +107 -8
  9. package/src/core/memory/episodes.js +106 -7
  10. package/src/core/memory/memoryCheck.js +241 -0
  11. package/src/core/memory/memoryCheckRun.js +27 -0
  12. package/src/core/memory/memoryHit.js +2 -0
  13. package/src/core/memory/mutateMemory.js +46 -1
  14. package/src/core/memory/observations.js +192 -0
  15. package/src/core/memory/projectIdentity.js +9 -2
  16. package/src/core/memory/recallEngine.js +204 -9
  17. package/src/core/memory/records.js +23 -0
  18. package/src/core/memory/registryPrune.js +230 -0
  19. package/src/core/memory/retrieval.js +12 -3
  20. package/src/core/memory/writeGate.js +137 -0
  21. package/src/core/runtimeConfig.js +12 -2
  22. package/src/index/buildIndex.js +26 -0
  23. package/src/index/paths.js +3 -1
  24. package/src/index/queryIndex.js +372 -26
  25. package/src/index/resolveContext.js +1 -1
  26. package/template_project/.claude/hooks/edit-hint.mjs +64 -17
  27. package/template_project/.claude/hooks/session-episode-start.mjs +35 -0
  28. package/template_project/.claude/hooks/session-episode.sh +9 -4
  29. package/template_project/.claude/settings.json +2 -2
  30. package/template_project/.claude/ukit/index/edit-graph.mjs +141 -11
  31. package/template_project/.claude/ukit/index/lib/index-core.mjs +400 -27
  32. package/template_project/.claude/ukit/index/query-index.mjs +14 -3
  33. package/template_project/.claude/ukit/index/resolve-context.mjs +1 -1
  34. package/template_project/.claude/ukit/index/route-task.mjs +8 -2
  35. package/template_project/.claude/ukit/runtime/memory-check.mjs +241 -0
  36. package/template_project/.claude/ukit/runtime/memory-lanes.mjs +44 -22
  37. package/template_project/.claude/ukit/runtime/memory-recall.mjs +204 -9
  38. package/template_project/.claude/ukit/runtime/memory-validity.mjs +259 -0
  39. package/template_project/.claude/ukit/runtime/reinject-context.mjs +4 -2
  40. package/template_project/.claude/ukit/runtime/self-improve-trigger.mjs +212 -5
  41. package/template_project/.omp/hooks/pre/ukit-bridge.js +2 -1
  42. package/template_project/ukit/storage/config.json +4 -2
  43. package/src/core/agentRuntime/completionGate.js +0 -179
  44. package/src/core/agentRuntime/context.js +0 -571
  45. package/src/core/agentRuntime/qualityComparison.js +0 -112
  46. package/src/core/agentRuntime/resourcePolicy.js +0 -78
  47. package/src/core/agentRuntime/runtimeSupport.js +0 -255
  48. package/src/core/codeintel/manifest.js +0 -176
  49. package/src/core/experiments/deliberation.js +0 -327
  50. package/src/core/experiments/dynamicWorkflow.js +0 -507
  51. package/src/core/handoffDocValidator.js +0 -154
  52. package/src/core/memory/deltaOverlays.js +0 -493
  53. package/src/core/memory/learningCandidates.js +0 -347
  54. package/src/core/observability/emit/sessionBoot.js +0 -407
  55. package/src/core/observability/evaluation/experimentPlan.js +0 -95
  56. package/src/core/observability/evaluation/perturbation.js +0 -273
  57. package/src/core/observability/evaluation/replay.js +0 -149
  58. package/src/core/observability/evaluation/scorecard.js +0 -465
  59. package/src/core/observability/schema/compatibility.js +0 -180
  60. package/src/core/observability/support/renderer.js +0 -130
  61. package/src/core/reviewPanelAggregate.js +0 -204
  62. package/src/core/taskBudgetValidator.js +0 -251
  63. package/src/core/taskProgressGuard.js +0 -227
  64. package/src/decision/reviewVerdict.js +0 -339
  65. package/src/decision/runtimeFilter.js +0 -150
  66. package/src/decision/runtimeScheduler.js +0 -239
  67. package/src/diagnostics/classifyHang.js +0 -246
  68. package/src/diagnostics/ompStallSnapshot.js +0 -199
  69. package/src/index/contextPack.js +0 -285
  70. package/src/index/impactContext.js +0 -360
  71. package/src/index/reviewPolicy.js +0 -368
  72. package/src/index/sensitivePath.js +0 -21
  73. package/src/render/instructionRenderer.js +0 -290
  74. package/src/skill/auditSkill.js +0 -140
  75. package/template_project/instructions/overlays/repo.md +0 -9
@@ -53,7 +53,8 @@ function safeSchemaArtifact(artifact) {
53
53
  return normalized.schemaVersion === INDEX_SCHEMA_VERSION ? normalized : { items: [] };
54
54
  }
55
55
 
56
- export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5 } = {}) {
56
+ // contentLane=false skips the error-string content search (context-resolution paths never pay for it).
57
+ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5, contentLane = true } = {}) {
57
58
  const normalizedQuery = String(query ?? '').trim();
58
59
  if (!normalizedQuery) {
59
60
  return [];
@@ -73,12 +74,13 @@ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5
73
74
  rootDir: absoluteRoot,
74
75
  query: normalizedQuery,
75
76
  limit,
77
+ contentLane,
76
78
  });
77
79
  if (QUERY_RESULT_CACHE.has(queryCacheKey)) {
78
80
  return QUERY_RESULT_CACHE.get(queryCacheKey);
79
81
  }
80
82
  const queryPromise = (async () => {
81
- const { files, searchDescriptorsByFile } = await loadQuerySearchBundle(absoluteRoot);
83
+ const { files, searchDescriptorsByFile, tokenWeights } = await loadQuerySearchBundle(absoluteRoot);
82
84
  const preferredArchetypes = inferPreferredArchetypes(queryDescriptor.tokens);
83
85
  const includeLikelyTestFiles = shouldIncludeLikelyTestFiles(queryDescriptor);
84
86
 
@@ -92,8 +94,10 @@ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5
92
94
  const searchDescriptor = searchDescriptorsByFile.get(filePath) ?? createFileSearchDescriptor({ filePath, symbols: [] });
93
95
  const { score, reasons } = scoreDirectFileMatch({
94
96
  queryDescriptor,
97
+ rawQuery: normalizedQuery,
95
98
  filePath,
96
99
  searchDescriptor,
100
+ tokenWeights,
97
101
  });
98
102
 
99
103
  if (score > 0) {
@@ -105,8 +109,51 @@ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5
105
109
  }
106
110
  }
107
111
 
112
+ // Content lane: a message-like query with no confident symbol/path hit also searches
113
+ // file contents through the existing bounded fallback search. It only adds a bounded
114
+ // bonus, so it can never displace a confident hit (those skip the lane entirely).
115
+ let bestDirect = 0;
116
+ let contentLaneRan = false;
117
+ let contentCutShort = [];
118
+ for (const entry of directScores.values()) {
119
+ bestDirect = Math.max(bestDirect, entry.score);
120
+ }
121
+ if (contentLane && bestDirect < CONTENT_LANE_CONFIDENT_SCORE && queryDescriptor.tokens.size >= CONTENT_LANE_MIN_TOKENS && looksLikeLiteralMessage(normalizedQuery)) {
122
+ contentLaneRan = true;
123
+ // A literal message sits on one source line: every query token must share the matched
124
+ // line, otherwise this is a scattered token hit, not the message. The scan order and the
125
+ // count/byte caps are functions of the index and file contents only (never of load or of
126
+ // ripgrep being installed); wall-clock is a safety cap that reports 'time-budget'.
127
+ const messageTokens = [...new Set(normalizeIdentifierTokens(queryDescriptor.rawLower))];
128
+ let lineHits = [];
129
+ try {
130
+ const ordered = rankContentLaneFiles({
131
+ files, searchDescriptorsByFile, tokenWeights, queryTokens: queryDescriptor.tokens, includeLikelyTestFiles,
132
+ });
133
+ const scan = await scanContentLane({ absoluteRoot, ordered, tokens: messageTokens, limit: CONTENT_LANE_LIMIT });
134
+ lineHits = scan.hits;
135
+ contentCutShort = scan.truncated;
136
+ } catch {
137
+ contentCutShort = ['error'];
138
+ }
139
+ lineHits.forEach((row, index) => {
140
+ const existing = directScores.get(row.filePath);
141
+ const reason = `content_match:${row.filePath}${row.line ? `:${row.line}` : ''}`;
142
+ if (existing) {
143
+ existing.score += CONTENT_LANE_BONUS;
144
+ existing.reasons = dedupe([...(existing.reasons ?? []), reason]);
145
+ } else {
146
+ directScores.set(row.filePath, {
147
+ filePath: row.filePath,
148
+ score: CONTENT_LANE_ONLY_SCORE - index * 0.1,
149
+ reasons: [reason],
150
+ });
151
+ }
152
+ });
153
+ }
154
+
108
155
  if (directScores.size === 0) {
109
- return Object.freeze([]);
156
+ return withContentLaneStatus(Object.freeze([]), contentLaneRan, contentCutShort);
110
157
  }
111
158
 
112
159
  const {
@@ -141,16 +188,20 @@ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5
141
188
  importersByTarget,
142
189
  testsMapBySource,
143
190
  });
144
- const finalScores = applyHotspotBoosts({
145
- scores: relatedScores,
146
- hotspotScores,
191
+ const finalScores = capBoostLift({
192
+ directScores,
193
+ scores: applyHotspotBoosts({
194
+ scores: relatedScores,
195
+ hotspotScores,
196
+ }),
147
197
  });
148
198
 
149
- return freezeQueryResults(
199
+ return withContentLaneStatus(freezeQueryResults(
150
200
  [...finalScores.values()]
201
+ .map((entry) => ({ ...entry, score: finalizeScore(entry) }))
151
202
  .sort((a, b) => b.score - a.score || a.filePath.localeCompare(b.filePath))
152
203
  .slice(0, limit),
153
- );
204
+ ), contentLaneRan, contentCutShort);
154
205
  })().catch((error) => {
155
206
  QUERY_RESULT_CACHE.delete(queryCacheKey);
156
207
  throw error;
@@ -179,7 +230,11 @@ function isFunctionLikeSignature(signature) {
179
230
  // Reads symbols.json through the existing readArtifact cache (no new file reads, no new
180
231
  // cache). Never throws: an absent file, a missing artifact, or a stale schema all resolve
181
232
  // to [] so callers can render an outline block unconditionally.
182
- export async function getFileOutline({ rootDir = process.cwd(), filePath, limit = 12 } = {}) {
233
+ const OUTLINE_WINDOW = 12; // matches OUTLINE_SYMBOLS_LIMIT in the CLI printers
234
+
235
+ // `focus`: symbol names the query matched (see queryMatchedSymbolNames); they are pinned into
236
+ // the first OUTLINE_WINDOW rows even when unexported, so the printed outline shows the hit.
237
+ export async function getFileOutline({ rootDir = process.cwd(), filePath, limit = 12, focus = null } = {}) {
183
238
  if (!filePath) {
184
239
  return Object.freeze([]);
185
240
  }
@@ -205,9 +260,26 @@ export async function getFileOutline({ rootDir = process.cwd(), filePath, limit
205
260
  seenNames.add(item.name);
206
261
  deduped.push(item);
207
262
  }
263
+ // The first OUTLINE_WINDOW rows (what the CLI prints) hold exported/top-level symbols
264
+ // first; unexported functions and class methods only take the remaining slots. Each
265
+ // part stays in line order, and rows beyond the window follow in line order.
266
+ const window = Number.isFinite(limit) ? limit : OUTLINE_WINDOW;
267
+ let kept = deduped;
268
+ if (deduped.length > window) {
269
+ const pinned = new Set(focus ?? []);
270
+ const isPinned = (item) => pinned.has(item.name);
271
+ const ranked = [
272
+ ...deduped.filter(isPinned),
273
+ ...deduped.filter((item) => !isPinned(item) && !isLocalOutlineRow(item)),
274
+ ...deduped.filter((item) => !isPinned(item) && isLocalOutlineRow(item)),
275
+ ];
276
+ const head = ranked.slice(0, window).sort((a, b) => a.line - b.line);
277
+ const inHead = new Set(head);
278
+ kept = [...head, ...deduped.filter((item) => !inHead.has(item))];
279
+ }
208
280
 
209
281
  return Object.freeze(
210
- deduped.slice(0, limit).map((item) => Object.freeze({
282
+ kept.slice(0, limit).map((item) => Object.freeze({
211
283
  line: item.line,
212
284
  name: item.name,
213
285
  type: item.type,
@@ -259,9 +331,11 @@ async function loadQuerySearchBundle(rootDir) {
259
331
  const safeFiles = safeSchemaArtifact(files);
260
332
  const safeSymbols = safeSchemaArtifact(symbols);
261
333
  const symbolMap = groupBy(safeItems(safeSymbols), (item) => item.filePath);
334
+ const searchDescriptorsByFile = buildFileSearchDescriptors(safeItems(safeFiles), symbolMap);
262
335
  return {
263
336
  files: safeFiles,
264
- searchDescriptorsByFile: buildFileSearchDescriptors(safeItems(safeFiles), symbolMap),
337
+ searchDescriptorsByFile,
338
+ tokenWeights: buildTokenWeights(searchDescriptorsByFile),
265
339
  };
266
340
  })
267
341
  .catch((error) => {
@@ -330,9 +404,103 @@ function dedupe(values) {
330
404
  return [...new Set(values)];
331
405
  }
332
406
 
333
- function scoreDirectFileMatch({ queryDescriptor, filePath, searchDescriptor }) {
407
+ // ── Ranking constants (kept identical in template index-core.mjs) ──
408
+ const PATH_EXACT_SCORE = 60;
409
+ const PATH_SUFFIX_SCORE = 48;
410
+ const PATH_BASENAME_SCORE = 40;
411
+ const SYMBOL_EXACT_SCORE = 40;
412
+ const LOCAL_SYMBOL_FACTOR = 0.85; // unexported symbols (local function/class, method, unexported type) rank below an exported symbol of the same name
413
+ const SYMBOL_DECAY = 0.35; // k-th best symbol of a file adds score * SYMBOL_DECAY^k
414
+ const SYMBOL_REASON_LIMIT = 3;
415
+ const MIN_SUBSTRING_TOKEN_LENGTH = 3;
416
+ const BOOST_LIFT_RATIO = 0.2; // import/hotspot/archetype boosts may add at most this share of a direct score (+1)
417
+ const CONTENT_LANE_CONFIDENT_SCORE = 30; // a best direct score at/above this (exact symbol or path hit) skips the content lane
418
+ const CONTENT_LANE_MIN_TOKENS = 3; // shorter queries are names, not messages
419
+ const CONTENT_LANE_LIMIT = 40; // candidates only share tokens somewhere in the file; the same-line check below keeps the real ones
420
+ const CONTENT_LANE_CODE_EXT = /\.(?:m?js|cjs|jsx?|tsx?|vue|sql|sh)$/i; // docs/data files quote queries verbatim (baselines, logs); only source carries error strings
421
+ const CONTENT_LANE_BONUS = 14; // added to a file that already has a direct score
422
+ const CONTENT_LANE_ONLY_SCORE = 13; // base for a file found only by content; below CONTENT_LANE_CONFIDENT_SCORE by design
423
+ const CONTENT_LANE_MAX_FILES = 1500; // files read per query, in priority order (primary bound)
424
+ const CONTENT_LANE_MAX_BYTES = 24 * 1024 * 1024; // characters read per query (primary bound)
425
+ const CONTENT_LANE_MAX_FILE_BYTES = 512 * 1024; // larger files are generated/data, never scanned
426
+ const CONTENT_LANE_BATCH = 24;
427
+ const CONTENT_LANE_SAFETY_MS = 5000; // safety cap only: hitting it reports 'time-budget', normal runs never do
428
+ const BOOST_ONLY_RATIO = 0.3; // files with no direct match stay below this share of the best direct score
429
+
430
+ // Rarity weight per token in (0,1]: a token present in nearly every file is worth
431
+ // ~ln2/ln(1+N), a token unique to one file is worth 1. Computed once per bundle.
432
+ function buildTokenWeights(searchDescriptorsByFile) {
433
+ const docFrequency = new Map();
434
+ for (const descriptor of searchDescriptorsByFile.values()) {
435
+ const seen = new Set(descriptor.path.tokens);
436
+ for (const symbol of descriptor.symbols) {
437
+ for (const token of symbol.descriptor.tokens) {
438
+ seen.add(token);
439
+ }
440
+ }
441
+ for (const token of seen) {
442
+ docFrequency.set(token, (docFrequency.get(token) ?? 0) + 1);
443
+ }
444
+ }
445
+ const total = searchDescriptorsByFile.size;
446
+ const denominator = Math.log(1 + total) || 1;
447
+ const weights = new Map();
448
+ for (const [token, count] of docFrequency) {
449
+ weights.set(token, Math.max(0.05, Math.log(1 + total / count) / denominator));
450
+ }
451
+ return weights;
452
+ }
453
+
454
+ // Prior applied after scoring so an original beats its mirror copy on ties without
455
+ // hiding the mirror: root installed copies < template_project < everything else.
456
+ function mirrorPrior(filePath) {
457
+ if (/^\.(?:claude|codex|omp)\//.test(filePath)) {
458
+ return 0.8;
459
+ }
460
+ if (filePath.startsWith('template_project/')) {
461
+ return 0.85;
462
+ }
463
+ return 1;
464
+ }
465
+
466
+ function normalizePathQuery(rawQuery) {
467
+ const value = String(rawQuery ?? '').trim().toLowerCase().replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '');
468
+ return value.length >= 3 && !/\s/.test(value) ? value : '';
469
+ }
470
+
471
+ // Exact path / path-suffix (whole segments) / basename match for single-term queries.
472
+ function scorePathQuery(pathQuery, filePath) {
473
+ if (!pathQuery) {
474
+ return null;
475
+ }
476
+ const lower = filePath.toLowerCase();
477
+ const noExt = lower.replace(/\.[a-z0-9]+$/, '');
478
+ if (pathQuery === lower) {
479
+ return { score: PATH_EXACT_SCORE, reason: `path_exact:${filePath}` };
480
+ }
481
+ if (pathQuery.includes('/')) {
482
+ if (noExt === pathQuery || lower.endsWith(`/${pathQuery}`) || noExt.endsWith(`/${pathQuery}`)) {
483
+ return { score: PATH_SUFFIX_SCORE, reason: `path_suffix:${pathQuery}` };
484
+ }
485
+ return null;
486
+ }
487
+ const base = lower.slice(lower.lastIndexOf('/') + 1);
488
+ if (pathQuery === base || pathQuery === base.replace(/\.[a-z0-9]+$/, '')) {
489
+ return { score: PATH_BASENAME_SCORE, reason: `path_basename:${pathQuery}` };
490
+ }
491
+ return null;
492
+ }
493
+
494
+ function scoreDirectFileMatch({ queryDescriptor, rawQuery = '', filePath, searchDescriptor, tokenWeights = null }) {
334
495
  let score = 0;
335
496
  const reasons = [];
497
+ const weightOf = (token) => tokenWeights?.get(token) ?? 1;
498
+
499
+ const pathHit = scorePathQuery(normalizePathQuery(rawQuery), filePath);
500
+ if (pathHit) {
501
+ score += pathHit.score;
502
+ reasons.push(pathHit.reason);
503
+ }
336
504
 
337
505
  if (
338
506
  queryDescriptor.compact.length >= 6
@@ -344,43 +512,45 @@ function scoreDirectFileMatch({ queryDescriptor, filePath, searchDescriptor }) {
344
512
 
345
513
  for (const token of queryDescriptor.tokens) {
346
514
  if (searchDescriptor.path.tokens.has(token)) {
347
- score += 3;
515
+ score += 3 * weightOf(token);
348
516
  reasons.push(`path_token:${token}`);
349
- } else if (searchDescriptor.path.rawLower.includes(token)) {
350
- score += 1;
517
+ } else if (token.length >= MIN_SUBSTRING_TOKEN_LENGTH && searchDescriptor.path.rawLower.includes(token)) {
518
+ score += weightOf(token);
351
519
  reasons.push(`path_contains:${token}`);
352
520
  }
353
521
  }
354
522
 
523
+ const symbolHits = [];
355
524
  for (const symbolDescriptor of searchDescriptor.symbols) {
356
525
  if (
357
526
  queryDescriptor.compact.length >= 4
358
527
  && symbolDescriptor.descriptor.compact === queryDescriptor.compact
359
528
  ) {
360
- score += 8;
361
- reasons.push(`symbol_exact:${symbolDescriptor.name}`);
529
+ symbolHits.push({ score: SYMBOL_EXACT_SCORE * (symbolDescriptor.local ? LOCAL_SYMBOL_FACTOR : 1), reasons: [`symbol_exact:${symbolDescriptor.name}`] });
362
530
  continue;
363
531
  }
364
532
 
533
+ let symbolScore = 0;
534
+ const symbolReasons = [];
365
535
  if (
366
536
  queryDescriptor.compact.length >= 6
367
537
  && symbolDescriptor.descriptor.compact.includes(queryDescriptor.compact)
368
538
  ) {
369
- score += 5;
370
- reasons.push(`symbol_compact:${symbolDescriptor.name}`);
539
+ symbolScore += 5;
540
+ symbolReasons.push(`symbol_compact:${symbolDescriptor.name}`);
371
541
  }
372
542
 
373
543
  let symbolContributed = false;
374
544
 
375
545
  for (const token of queryDescriptor.tokens) {
376
546
  if (symbolDescriptor.descriptor.tokens.has(token)) {
377
- score += 3;
547
+ symbolScore += 3 * weightOf(token);
378
548
  symbolContributed = true;
379
- reasons.push(`symbol_token:${symbolDescriptor.name}:${token}`);
380
- } else if (symbolDescriptor.descriptor.rawLower.includes(token)) {
381
- score += 1;
549
+ symbolReasons.push(`symbol_token:${symbolDescriptor.name}:${token}`);
550
+ } else if (token.length >= MIN_SUBSTRING_TOKEN_LENGTH && symbolDescriptor.descriptor.rawLower.includes(token)) {
551
+ symbolScore += weightOf(token);
382
552
  symbolContributed = true;
383
- reasons.push(`symbol_contains:${symbolDescriptor.name}`);
553
+ symbolReasons.push(`symbol_contains:${symbolDescriptor.name}`);
384
554
  }
385
555
  }
386
556
 
@@ -390,12 +560,28 @@ function scoreDirectFileMatch({ queryDescriptor, filePath, searchDescriptor }) {
390
560
  // from the stronger tiers above.
391
561
  if (!symbolContributed && queryDescriptor.compact.length >= 6) {
392
562
  if (symbolFuzzyMatches(queryDescriptor.compact, symbolDescriptor.descriptor.compact)) {
393
- score += 3;
394
- reasons.push(`symbol_fuzzy:${symbolDescriptor.name}`);
563
+ symbolScore += 3;
564
+ symbolReasons.push(`symbol_fuzzy:${symbolDescriptor.name}`);
395
565
  }
396
566
  }
567
+
568
+ if (symbolScore > 0) {
569
+ symbolHits.push({ score: symbolScore * (symbolDescriptor.local ? LOCAL_SYMBOL_FACTOR : 1), reasons: symbolReasons });
570
+ }
397
571
  }
398
572
 
573
+ // Best symbol dominates; further symbols add with sharp diminishing returns so
574
+ // file size (symbol count) cannot outvote match quality.
575
+ symbolHits.sort((a, b) => b.score - a.score);
576
+ let decay = 1;
577
+ symbolHits.forEach((hit, index) => {
578
+ score += hit.score * decay;
579
+ decay *= SYMBOL_DECAY;
580
+ if (index < SYMBOL_REASON_LIMIT) {
581
+ reasons.push(...hit.reasons);
582
+ }
583
+ });
584
+
399
585
  return {
400
586
  score,
401
587
  reasons: dedupe(reasons),
@@ -403,6 +589,29 @@ function scoreDirectFileMatch({ queryDescriptor, filePath, searchDescriptor }) {
403
589
  };
404
590
  }
405
591
 
592
+ // Import-graph, hotspot and archetype boosts are context, not evidence: they may
593
+ // reorder near-equal direct matches but never lift a weak match over a strong one,
594
+ // and files with no direct match stay below the best direct match.
595
+ function capBoostLift({ directScores, scores }) {
596
+ let maxDirect = 0;
597
+ for (const entry of directScores.values()) {
598
+ maxDirect = Math.max(maxDirect, entry.score);
599
+ }
600
+ for (const [filePath, entry] of scores) {
601
+ const base = directScores.get(filePath)?.score;
602
+ if (base === undefined) {
603
+ entry.score = Math.min(entry.score, BOOST_ONLY_RATIO * maxDirect);
604
+ } else {
605
+ entry.score = base + Math.min(Math.max(entry.score - base, 0), BOOST_LIFT_RATIO * base + 1);
606
+ }
607
+ }
608
+ return scores;
609
+ }
610
+
611
+ function finalizeScore(entry) {
612
+ return Number((entry.score * mirrorPrior(entry.filePath)).toFixed(2));
613
+ }
614
+
406
615
  function groupBy(items, keyFn) {
407
616
  const map = new Map();
408
617
  for (const item of items) {
@@ -822,11 +1031,124 @@ function buildFileSearchDescriptors(files, symbolMap) {
822
1031
  return descriptors;
823
1032
  }
824
1033
 
1034
+ // Rows whose declaration is not exported. 'callable' keeps its pre-3.5.4 weight.
1035
+ // Outline-only: a 'callable' const without `export` is also unexported.
1036
+ function isLocalOutlineRow(item) {
1037
+ return isLocalSymbolRow(item) || (item?.type === 'callable' && !/^\s*export\b/.test(item?.signature ?? ''));
1038
+ }
1039
+
1040
+ function isLocalSymbolRow(symbol) {
1041
+ const type = symbol?.type;
1042
+ if (type === 'local-function' || type === 'local-class' || type === 'method') {
1043
+ return true;
1044
+ }
1045
+ return type === 'type' && !/^\s*export\b/.test(symbol?.signature ?? '');
1046
+ }
1047
+
1048
+ // Single identifiers, questions and non-ASCII (Vietnamese) prose are descriptions of behaviour, not strings
1049
+ // that appear in source, so they never pay for a content search.
1050
+ function looksLikeLiteralMessage(query) {
1051
+ return /^[\x20-\x7e]+$/.test(query)
1052
+ && query.split(/\s+/).length >= CONTENT_LANE_MIN_TOKENS // identifiers and short phrases are symbol queries, never a message
1053
+ && !/^(?:how|where|what|why|which|when|who|does|do|is|are|can|find|show|list)\b/i.test(query);
1054
+ }
1055
+
1056
+ // Stable verify order: index evidence first (rarity-weighted overlap of the query tokens with
1057
+ // each file's path and symbol tokens), originals before mirrors, then path order.
1058
+ function rankContentLaneFiles({ files, searchDescriptorsByFile, tokenWeights, queryTokens, includeLikelyTestFiles }) {
1059
+ const rows = [];
1060
+ for (const file of safeItems(files)) {
1061
+ const filePath = file?.filePath;
1062
+ if (typeof filePath !== 'string' || !CONTENT_LANE_CODE_EXT.test(filePath)) {
1063
+ continue;
1064
+ }
1065
+ if (isLikelyTestFilePath(filePath) && !includeLikelyTestFiles) {
1066
+ continue;
1067
+ }
1068
+ let overlap = 0;
1069
+ const descriptor = searchDescriptorsByFile.get(filePath);
1070
+ if (descriptor) {
1071
+ const seen = new Set(descriptor.path.tokens);
1072
+ for (const symbol of descriptor.symbols) {
1073
+ for (const token of symbol.descriptor.tokens) {
1074
+ seen.add(token);
1075
+ }
1076
+ }
1077
+ for (const token of queryTokens) {
1078
+ if (seen.has(token)) {
1079
+ overlap += tokenWeights?.get(token) ?? 1;
1080
+ }
1081
+ }
1082
+ }
1083
+ rows.push({ filePath, overlap, mirror: mirrorPrior(filePath) < 1 ? 1 : 0, size: Number.isFinite(Number(file.size)) && Number(file.size) >= 0 ? Number(file.size) : null });
1084
+ }
1085
+ rows.sort((a, b) => (b.overlap - a.overlap) || (a.mirror - b.mirror) || (a.filePath < b.filePath ? -1 : a.filePath > b.filePath ? 1 : 0));
1086
+ return rows;
1087
+ }
1088
+
1089
+ // Reads files in priority order (batched for speed, consumed in order) until the hit limit or a
1090
+ // count/byte cap. Caps are checked at batch boundaries on counts and byte totals only, so the
1091
+ // same tree yields the same hits regardless of machine load.
1092
+ async function scanContentLane({ absoluteRoot, ordered, tokens, limit }) {
1093
+ const hits = [];
1094
+ const truncated = new Set();
1095
+ if (tokens.length === 0) {
1096
+ return { hits, truncated: [] };
1097
+ }
1098
+ let scanned = 0;
1099
+ let bytes = 0;
1100
+ const deadline = Date.now() + CONTENT_LANE_SAFETY_MS;
1101
+ for (let start = 0; start < ordered.length && hits.length < limit; start += CONTENT_LANE_BATCH) {
1102
+ if (scanned >= CONTENT_LANE_MAX_FILES) { truncated.add('max-files'); break; }
1103
+ if (bytes >= CONTENT_LANE_MAX_BYTES) { truncated.add('max-bytes'); break; }
1104
+ if (Date.now() > deadline) { truncated.add('time-budget'); break; }
1105
+ const batch = ordered.slice(start, start + Math.min(CONTENT_LANE_BATCH, CONTENT_LANE_MAX_FILES - scanned));
1106
+ // Size comes from the index entry, else a stat; an oversized file is skipped before any read.
1107
+ const texts = await Promise.all(batch.map(async (row) => {
1108
+ try {
1109
+ const absolute = path.join(absoluteRoot, row.filePath);
1110
+ const size = row.size ?? (await fs.stat(absolute)).size;
1111
+ if (size > CONTENT_LANE_MAX_FILE_BYTES) {
1112
+ return { text: '', size: 0 };
1113
+ }
1114
+ const text = await fs.readFile(absolute, 'utf8');
1115
+ return { text, size: Buffer.byteLength(text, 'utf8') };
1116
+ } catch {
1117
+ return { text: '', size: 0 };
1118
+ }
1119
+ }));
1120
+ for (const [index, { text, size }] of texts.entries()) {
1121
+ scanned += 1;
1122
+ bytes += size;
1123
+ if (text.length === 0 || size > CONTENT_LANE_MAX_FILE_BYTES) {
1124
+ continue;
1125
+ }
1126
+ const lower = text.toLowerCase();
1127
+ if (!tokens.every((token) => lower.includes(token))) {
1128
+ continue;
1129
+ }
1130
+ const lines = lower.split('\n');
1131
+ const lineIndex = lines.findIndex((line) => tokens.every((token) => line.includes(token)));
1132
+ if (lineIndex >= 0) {
1133
+ hits.push({ filePath: batch[index].filePath, line: lineIndex + 1 });
1134
+ if (hits.length >= limit) {
1135
+ break;
1136
+ }
1137
+ }
1138
+ }
1139
+ }
1140
+ if (scanned >= CONTENT_LANE_MAX_FILES && scanned < ordered.length && hits.length < limit) {
1141
+ truncated.add('max-files');
1142
+ }
1143
+ return { hits, truncated: [...truncated] };
1144
+ }
1145
+
825
1146
  function createFileSearchDescriptor({ filePath, symbols }) {
826
1147
  return {
827
1148
  path: buildTextSearchDescriptor(filePath),
828
1149
  symbols: symbols.map((symbol) => ({
829
1150
  name: symbol.name,
1151
+ local: isLocalSymbolRow(symbol),
830
1152
  descriptor: buildTextSearchDescriptor(symbol.name),
831
1153
  })),
832
1154
  };
@@ -1096,6 +1418,30 @@ export function clearIndexArtifactCache(rootDir = null) {
1096
1418
  }
1097
1419
  }
1098
1420
 
1421
+ // Names of the symbols a query result matched, parsed from its `symbol_exact:` /
1422
+ // `symbol_token:` reasons; feed to getFileOutline({ focus }).
1423
+ export function queryMatchedSymbolNames(result) {
1424
+ const names = [];
1425
+ for (const reason of result?.reasons ?? []) {
1426
+ const match = /^symbol_(?:exact|compact|contains):([^:]+)$/.exec(reason) ?? /^symbol_token:([^:]+):/.exec(reason);
1427
+ if (match) {
1428
+ names.push(match[1]);
1429
+ }
1430
+ }
1431
+ return names;
1432
+ }
1433
+
1434
+ // Non-enumerable (array equality and JSON stay unchanged), like boundedSourceSearch rows.truncated:
1435
+ // `contentLane` is true when the content search ran; `contentLaneTruncated` lists why it was cut
1436
+ // short ('verify-cap', 'time-budget', 'max-files', ...) so a partial scan never reads as "no match".
1437
+ function withContentLaneStatus(results, ran, truncated) {
1438
+ // results arrive frozen, so copy before attaching the status and freeze again.
1439
+ const out = [...results];
1440
+ Object.defineProperty(out, 'contentLane', { value: ran, enumerable: false });
1441
+ Object.defineProperty(out, 'contentLaneTruncated', { value: Object.freeze([...truncated]), enumerable: false });
1442
+ return Object.freeze(out);
1443
+ }
1444
+
1099
1445
  function freezeQueryResults(results) {
1100
1446
  return Object.freeze(
1101
1447
  results.map((item) => Object.freeze({
@@ -83,7 +83,7 @@ export async function resolveContext({
83
83
  }
84
84
 
85
85
  if (queryWasUsed) {
86
- const queryResults = await queryCodeIndex({ rootDir, query: intent, limit: budget.maxFiles });
86
+ const queryResults = await queryCodeIndex({ rootDir, query: intent, limit: budget.maxFiles, contentLane: false });
87
87
  for (const qr of queryResults) {
88
88
  addExplainedFile(result, 'primaryTargets', qr.filePath, buildQueryReason(qr));
89
89
  }
@@ -37,6 +37,34 @@ async function prune(dir, keep) {
37
37
  } catch { /* retention is best-effort */ }
38
38
  }
39
39
 
40
+ function emit(text, p, env) {
41
+ if (!text) return NONE;
42
+ const omp = p.ukit_harness === 'omp' || env.UKIT_HARNESS === 'omp';
43
+ const stdout = omp
44
+ ? `${text}\n`
45
+ : `${JSON.stringify({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: text } })}\n`;
46
+ return { code: 0, stdout, stderr: '' };
47
+ }
48
+
49
+ // null: not a memory source (fall through to the graph hint); '' clean; else one advisory line.
50
+ async function memoryAdvisory(projectRoot, rel, config, signal) {
51
+ try {
52
+ const recall = await import('../ukit/runtime/memory-recall.mjs');
53
+ const entries = recall.normalizeMemorySources(config ?? {});
54
+ // Sync pre-check: no directory listing for edits that are not a memory source.
55
+ if (!recall.matchesMemorySource(entries, rel)) return null;
56
+ const sources = await recall.expandMemorySources(projectRoot, entries);
57
+ if (!sources.includes(rel)) return null;
58
+ const check = await import('../ukit/runtime/memory-check.mjs');
59
+ const res = await check.checkMemorySources(projectRoot, {
60
+ sources, engine: { tokenize: recall.tokenize, parseMarkdownBullets: recall.parseMarkdownBullets }, files: [rel],
61
+ });
62
+ return signal.aborted ? '' : check.formatCheckLine(res);
63
+ } catch {
64
+ return '';
65
+ }
66
+ }
67
+
40
68
  async function hint(ctx, signal, commit) {
41
69
  const { payload: p = {}, projectRoot, env = {} } = ctx;
42
70
  if (env.UKIT_EDIT_HINTS === '0' || process.env.UKIT_EDIT_HINTS === '0') return NONE;
@@ -55,9 +83,42 @@ async function hint(ctx, signal, commit) {
55
83
  const task = typeof route?.taskInstanceId === 'string' && route.taskInstanceId ? route.taskInstanceId : session;
56
84
  const stateFile = path.join(projectRoot, '.ukit/storage/cache/edit-hints', `${session}.${safe(p.agent_id, 'main')}.json`);
57
85
  const prev = await readJson(stateFile);
86
+ const strs = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string') : []);
58
87
  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: [] };
88
+ ? { task, seen: strs(prev.seen), shownMem: strs(prev.shownMem), advised: strs(prev.advised) }
89
+ : { task, seen: [], shownMem: [], advised: [] };
90
+ const persist = async () => {
91
+ st.seen = st.seen.slice(-MAX_SEEN);
92
+ st.shownMem = st.shownMem.slice(-MAX_SEEN);
93
+ st.advised = st.advised.slice(-MAX_SEEN);
94
+ let body = JSON.stringify(st);
95
+ while (body.length > MAX_BYTES && st.seen.length > 1) {
96
+ st.seen.shift();
97
+ st.shownMem.shift();
98
+ st.advised.shift();
99
+ body = JSON.stringify(st);
100
+ }
101
+ try {
102
+ await fsp.mkdir(path.dirname(stateFile), { recursive: true });
103
+ const tmp = `${stateFile}.${process.pid}.tmp`;
104
+ await fsp.writeFile(tmp, body);
105
+ await fsp.rename(tmp, stateFile);
106
+ } catch { /* state is best-effort */ }
107
+ void prune(path.dirname(stateFile), path.basename(stateFile));
108
+ };
109
+ // 3.5.4: an edited memory source gets the checker's advisory line instead of a graph hint,
110
+ // once per task per finding (the line names file:line and the code), so a project that
111
+ // stays over the cap is not nagged on every edit.
112
+ if (/^docs\/.+\.md$/i.test(rel)) {
113
+ const advisory = await memoryAdvisory(projectRoot, rel, config, signal);
114
+ if (advisory !== null) {
115
+ if (!advisory || st.advised.includes(advisory) || signal.aborted) return NONE;
116
+ commit.on = true;
117
+ st.advised.push(advisory);
118
+ await persist();
119
+ return emit(advisory, p, env);
120
+ }
121
+ }
61
122
  if (st.seen.includes(rel)) return NONE;
62
123
 
63
124
  const lanes = await import('../ukit/runtime/memory-lanes.mjs');
@@ -74,21 +135,7 @@ async function hint(ctx, signal, commit) {
74
135
  commit.on = true;
75
136
  st.seen.push(rel);
76
137
  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));
138
+ await persist();
92
139
 
93
140
  const text = typeof out?.text === 'string' ? out.text.trim() : '';
94
141
  if (!text) return NONE;