@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
@@ -0,0 +1,35 @@
1
+ // session-episode-start.mjs - SessionStart in-proc chain step (3.5.4).
2
+ //
3
+ // Episodes must not depend on SessionEnd alone: a long-lived session (or a crash) never
4
+ // reaches it. On every SessionStart source (startup, resume, clear, compact) this step
5
+ // launches ONE detached, throttled worker that records the finished tasks of earlier
6
+ // ledgers and of the still-open session (`ukit memory episode --start`) - same
7
+ // writeEpisode/backfill code and dedupe keys as SessionEnd, so a later SessionEnd is a
8
+ // no-op for what is already written.
9
+ //
10
+ // Advisory end-to-end: always { code: 0 }, no output, async fs only, bounded by the chain
11
+ // deadline. The CLI resolution (and the stale-CLI refusal) happens inside the detached
12
+ // worker, never here.
13
+
14
+ import { fileURLToPath, pathToFileURL } from 'node:url';
15
+ import path from 'node:path';
16
+
17
+ const OK = { code: 0, stdout: '', stderr: '' };
18
+
19
+ export async function runHook(ctx = {}) {
20
+ try {
21
+ const payload = ctx && typeof ctx.payload === 'object' && ctx.payload ? ctx.payload : {};
22
+ const root = typeof ctx.projectRoot === 'string' && ctx.projectRoot
23
+ ? ctx.projectRoot
24
+ : (typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : process.env.CLAUDE_PROJECT_DIR);
25
+ if (!root) return OK;
26
+ const here = path.dirname(fileURLToPath(import.meta.url));
27
+ const trigger = await import(pathToFileURL(path.join(here, '..', 'ukit', 'runtime', 'self-improve-trigger.mjs')).href);
28
+ const budget = Number(ctx.deadlineMs) > 0 ? Number(ctx.deadlineMs) : 2000;
29
+ await Promise.race([
30
+ trigger.triggerEpisodeStart({ projectRoot: root }),
31
+ new Promise((resolve) => { setTimeout(resolve, Math.max(100, budget - 200)).unref?.(); }),
32
+ ]);
33
+ } catch { /* advisory */ }
34
+ return OK;
35
+ }
@@ -161,16 +161,21 @@ function runBounded(cmd, args, { timeout, cwd, env, shell } = {}) {
161
161
  try {
162
162
  trigger = await import(require("url").pathToFileURL(process.argv[4]).href);
163
163
  } catch {}
164
- const located = trigger?.resolveCliLocator?.(projectRoot) ?? null;
165
- const cli = located
166
- ? { cmd: located.node, pre: [located.bin], shell: false }
164
+ // 3.5.4: one shared resolver. cli.json wins; a PATH `ukit` older than the project
165
+ // runtime is refused (it writes the wrong record shape) and the reason is left in
166
+ // .ukit/storage/learning/episode-cli.json for `ukit doctor`. The PATH version probe is
167
+ // cached by binary path + mtime and async, inside this armed step.
168
+ const cli = trigger?.resolveEpisodeCli
169
+ ? await trigger.resolveEpisodeCli(projectRoot)
167
170
  : { cmd: "ukit", pre: [], shell: true };
171
+ if (cli.reason) return;
168
172
 
169
- const probe = await runBounded(cli.cmd, [...cli.pre, "--version"], { timeout: 2000 });
173
+ const probe = await runBounded(cli.cmd, [...cli.pre, "--version"], { timeout: 2000, shell: cli.shell });
170
174
  if (!probe.ok) return;
171
175
 
172
176
  await runBounded(cli.cmd, [...cli.pre, "memory", "episode"], {
173
177
  timeout: 4000,
178
+ shell: cli.shell,
174
179
  cwd: projectRoot,
175
180
  env: sessionId
176
181
  ? { ...process.env, UKIT_SESSION_ID: sessionId }
@@ -234,8 +234,8 @@
234
234
  "hooks": [
235
235
  {
236
236
  "type": "command",
237
- "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/project-important.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/auto-prune-bash.sh\":12 \"$CLAUDE_PROJECT_DIR/.claude/hooks/reset-compact-pressure.sh\":12 \"$CLAUDE_PROJECT_DIR/.claude/hooks/handoff-resume.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/observability-emit.mjs\":8",
238
- "timeout": 60
237
+ "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/project-important.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/auto-prune-bash.sh\":12 \"$CLAUDE_PROJECT_DIR/.claude/hooks/reset-compact-pressure.sh\":12 \"$CLAUDE_PROJECT_DIR/.claude/hooks/handoff-resume.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/observability-emit.mjs\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/session-episode-start.mjs\":8",
238
+ "timeout": 70
239
239
  }
240
240
  ]
241
241
  }
@@ -4,10 +4,12 @@
4
4
  import fs from 'node:fs/promises';
5
5
  import path from 'node:path';
6
6
  import crypto from 'node:crypto';
7
+ import { execFile } from 'node:child_process';
7
8
 
8
9
  export const EDIT_GRAPH_FILE = 'edit-graph.json';
9
10
  const SCHEMA = 1;
10
11
  const CAP = 5;
12
+ const TOGETHER = 3;
11
13
  const MIN_TWIN = 200;
12
14
  const MAX_HASH = 512 * 1024;
13
15
  const MAX_LOAD = 2 * 1024 * 1024;
@@ -71,21 +73,133 @@ export function findTwinGroups(entries) {
71
73
  .sort((a, b) => cmp(a[0], b[0]));
72
74
  }
73
75
 
74
- export function rankTestsForSource({ source, stemMatches = [], importingTests = [], mentionCounts = {} } = {}) {
76
+ // Tiers (lower = earlier). coTests: [{path, count}] test files committed together
77
+ // with the source. A name/import edge that history confirms is the strongest signal,
78
+ // a repeated co-change alone comes next, then the name edges the history never saw.
79
+ export const STRONG_CO = 3;
80
+ // Grid-picked on the replay: a name edge alone outranks a weak (count 2) co-change.
81
+ export const TIER_ORDER = ['both', 'strong', 'name', 'weak'];
82
+ export function rankTestsForSource({ source, stemMatches = [], importingTests = [], mentionCounts = {}, coTests = [] } = {}, tuning = {}) {
83
+ const strongCo = tuning.strongCo ?? STRONG_CO;
84
+ const order = tuning.order ?? TIER_ORDER;
75
85
  const base = path.posix.basename(norm(source), path.posix.extname(norm(source))).toLowerCase();
76
86
  const generic = GENERIC.has(base) || base.length < 5;
77
87
  const count = (t) => Number((mentionCounts instanceof Map ? mentionCounts.get(t) : mentionCounts?.[t]) ?? 0);
78
- const rows = new Map();
79
- const add = (t, tier) => { if (!rows.has(t) || rows.get(t).tier > tier) rows.set(t, { t, tier }); };
88
+ const co = new Map((coTests ?? []).map((c) => [c.path, Number(c.count) || 0]));
89
+ const name = new Map(); // test -> best name tier: 0 stem, 1 import, 2 mention
90
+ const add = (t, tier) => { if (!name.has(t) || name.get(t) > tier) name.set(t, tier); };
80
91
  for (const t of stemMatches) add(t, 0);
81
92
  for (const t of importingTests) add(t, 1);
82
93
  if (!generic) {
83
94
  const names = mentionCounts instanceof Map ? [...mentionCounts.keys()] : Object.keys(mentionCounts ?? {});
84
95
  for (const t of names) if (count(t) > 0) add(t, 2);
85
96
  }
86
- return [...rows.values()]
87
- .sort((a, b) => a.tier - b.tier || (a.tier === 2 ? count(b.t) - count(a.t) : 0) || cmp(a.t, b.t))
88
- .map((r) => r.t);
97
+ const klass = (t) => {
98
+ const n = name.get(t);
99
+ const c = co.get(t) ?? 0;
100
+ if (n === undefined) return c >= strongCo ? 'strong' : 'weak'; // co-change only
101
+ return c > 0 ? 'both' : 'name'; // name edge confirmed by history / name edge alone
102
+ };
103
+ const tierOf = (t) => order.indexOf(klass(t)) * 4 + (name.get(t) ?? 0);
104
+ return [...new Set([...name.keys(), ...co.keys()])]
105
+ .sort((a, b) => tierOf(a) - tierOf(b) || (co.get(b) ?? 0) - (co.get(a) ?? 0) || count(b) - count(a) || cmp(a, b));
106
+ }
107
+
108
+ // Co-change model: how often two files were committed together. Commits touching
109
+ // more than MAX_COMMIT_FILES files (merge/squash/format noise) add no pairs but
110
+ // still count toward a file's own commit total. add/remove keep a sliding window
111
+ // cheap, which is how the history bench mines "strictly before this commit".
112
+ export const CO_MAX_COMMITS = 500;
113
+ export const CO_MAX_COMMIT_FILES = 50;
114
+ export const CO_MIN_COUNT = 2;
115
+
116
+ export function createCoChange({ maxCommitFiles = CO_MAX_COMMIT_FILES } = {}) {
117
+ const peers = new Map(); // file -> Map(other -> count)
118
+ const commits = new Map(); // file -> number of commits touching it
119
+ const bump = (map, key, d) => {
120
+ const n = (map.get(key) ?? 0) + d;
121
+ if (n > 0) map.set(key, n); else map.delete(key);
122
+ };
123
+ const apply = (files, d_) => {
124
+ const set = [...new Set((files ?? []).map(norm).filter(Boolean))];
125
+ for (const f of set) bump(commits, f, d_);
126
+ if (set.length < 2 || set.length > maxCommitFiles) return;
127
+ for (const a of set) {
128
+ if (!peers.has(a)) peers.set(a, new Map());
129
+ for (const b of set) if (a !== b) bump(peers.get(a), b, d_);
130
+ if (!peers.get(a).size) peers.delete(a);
131
+ }
132
+ };
133
+ return {
134
+ add: (files) => apply(files, 1),
135
+ remove: (files) => apply(files, -1),
136
+ commitsOf: (file) => commits.get(norm(file)) ?? 0,
137
+ // [{path, count, confidence}] strongest first (count desc, confidence desc, path asc).
138
+ peersOf(file, { minCount = CO_MIN_COUNT } = {}) {
139
+ const f = norm(file);
140
+ const total = commits.get(f) ?? 0;
141
+ const out = [];
142
+ for (const [p, count] of peers.get(f) ?? []) if (count >= minCount) out.push({ path: p, count, confidence: count / total });
143
+ return out.sort((x, y) => y.count - x.count || y.confidence - x.confidence || cmp(x.path, y.path));
144
+ },
145
+ };
146
+ }
147
+
148
+ // Co-changed peers of `source` that still exist, split into test files and the rest.
149
+ // Shared by the graph build and the history bench so both score the same evidence.
150
+ export function coChangeFor(model, source, { exists = () => true, minCount = CO_MIN_COUNT } = {}) {
151
+ const tests = [];
152
+ const files = [];
153
+ const src = norm(source);
154
+ for (const peer of model?.peersOf(src, { minCount }) ?? []) {
155
+ if (peer.path === src || !exists(peer.path)) continue;
156
+ (isTestSource(peer.path) ? tests : isTestPath(peer.path) ? [] : files).push(peer);
157
+ }
158
+ return { tests, files };
159
+ }
160
+
161
+ // "@@<sha>" header lines followed by the commit's file names (git log --name-only).
162
+ export function parseCoChangeLog(out) {
163
+ const list = [];
164
+ let cur = null;
165
+ for (const line of String(out ?? '').split('\n')) {
166
+ if (line.startsWith('@@')) {
167
+ const sha = line.slice(2).trim();
168
+ cur = /^[0-9a-f]{40}$/i.test(sha) ? { sha: sha.toLowerCase(), files: [] } : null;
169
+ if (cur) list.push(cur);
170
+ } else if (cur && line.trim()) {
171
+ cur.files.push(norm(line));
172
+ }
173
+ }
174
+ return list;
175
+ }
176
+
177
+ function git(rootDir, args, { signal, timeoutMs = 20_000 } = {}) {
178
+ return new Promise((resolve) => {
179
+ if (signal?.aborted) return resolve(null);
180
+ try {
181
+ execFile('git', args, { cwd: rootDir, maxBuffer: 64 * 1024 * 1024, timeout: timeoutMs, killSignal: 'SIGKILL', ...(signal ? { signal } : {}), windowsHide: true },
182
+ (error, stdout) => resolve(error ? null : String(stdout)));
183
+ } catch {
184
+ resolve(null);
185
+ }
186
+ });
187
+ }
188
+
189
+ export async function gitHead(rootDir, opts = {}) {
190
+ const sha = String(await git(rootDir, ['rev-parse', 'HEAD'], { timeoutMs: 5000, ...opts }) ?? '').trim();
191
+ return /^[0-9a-f]{40}$/i.test(sha) ? sha.toLowerCase() : null;
192
+ }
193
+
194
+ // Bounded history for the graph build. Graph build/refresh only, never the hook path.
195
+ // Non-git directory or any git failure -> null (graph still builds without co-change).
196
+ export async function mineCoChange(rootDir, { maxCommits = CO_MAX_COMMITS, signal, timeoutMs } = {}) {
197
+ const root = path.resolve(rootDir ?? '.');
198
+ const head = await gitHead(root, { signal });
199
+ if (!head) return null;
200
+ const log = await git(root, ['-c', 'core.quotePath=false', 'log', '--no-renames', '--name-only', '--format=@@%H', '-n', String(maxCommits)], { signal, timeoutMs });
201
+ if (log === null) return null;
202
+ return { head, commits: parseCoChangeLog(log).map((c) => c.files) };
89
203
  }
90
204
 
91
205
  function cleanPair(raw) {
@@ -107,9 +221,10 @@ async function readHints(root, readFile) {
107
221
  return {
108
222
  mirrors: Array.isArray(h.mirrors) ? h.mirrors : [],
109
223
  ignore: Array.isArray(h.ignoreMirrors) ? h.ignoreMirrors.filter((v) => typeof v === 'string').map(norm) : [],
224
+ coChange: h.coChange === true, // the "changed together" line only; test co-change is always mined
110
225
  };
111
226
  } catch {
112
- return { mirrors: [], ignore: [] };
227
+ return { mirrors: [], ignore: [], coChange: false };
113
228
  }
114
229
  }
115
230
 
@@ -169,7 +284,7 @@ export async function buildEditGraph({
169
284
 
170
285
  const acc = new Map();
171
286
  const slot = (p) => {
172
- if (!acc.has(p)) acc.set(p, { m: [], t: [], i: new Set(), d: new Set() });
287
+ if (!acc.has(p)) acc.set(p, { m: [], t: [], c: [], i: new Set(), d: new Set() });
173
288
  return acc.get(p);
174
289
  };
175
290
  for (const [key, k] of pairs) {
@@ -198,15 +313,26 @@ export async function buildEditGraph({
198
313
  if (signal?.aborted) throw new Error('edit-graph build aborted');
199
314
  const byStem = new Map();
200
315
  for (const t of testPaths) byStem.set(stemOf(t), [...(byStem.get(stemOf(t)) ?? []), t]);
316
+ // Co-change from bounded git history (async, abortable; null outside git or on any
317
+ // git failure, in which case the graph is the name/import graph only).
318
+ const mined = await mineCoChange(root, { signal });
319
+ if (signal?.aborted) throw new Error('edit-graph build aborted');
320
+ const model = createCoChange();
321
+ for (const files of mined?.commits ?? []) model.add(files);
201
322
  for (const src of [...sizes.keys()].sort(cmp)) {
202
323
  if (isTestPath(src) || !SRC_RE.test(src)) continue;
324
+ const co = coChangeFor(model, src, { exists: (p) => sizes.has(p) });
203
325
  const ranked = rankTestsForSource({
204
326
  source: src,
205
327
  stemMatches: byStem.get(stemOf(src)) ?? [],
206
328
  importingTests: [...(acc.get(src)?.i ?? [])].filter(isTestPath),
207
329
  mentionCounts: mentionCountsFor(src, tokens),
330
+ coTests: co.tests,
208
331
  }).slice(0, CAP);
209
332
  if (ranked.length) slot(src).t = ranked;
333
+ const twins = new Set((acc.get(src)?.m ?? []).map((x) => x.p));
334
+ const together = co.files.filter((x) => !twins.has(x.path) && !ignored.has(x.path)).slice(0, TOGETHER).map((x) => ({ p: x.path, n: x.count }));
335
+ if (hints.coChange && together.length) slot(src).c = together;
210
336
  }
211
337
 
212
338
  const out = {};
@@ -214,9 +340,11 @@ export async function buildEditGraph({
214
340
  const s = acc.get(p);
215
341
  const m = s.m.sort((x, y) => cmp(x.p, y.p) || cmp(x.k, y.k)).slice(0, CAP);
216
342
  const entry = { m, t: s.t, i: cap([...s.i]), d: cap([...s.d]) };
217
- if (m.length || entry.t.length || entry.i.length || entry.d.length) out[p] = entry;
343
+ if (s.c.length) entry.c = s.c;
344
+ if (m.length || entry.t.length || entry.i.length || entry.d.length || s.c.length) out[p] = entry;
218
345
  }
219
- return { schemaVersion: SCHEMA, generatedAt: new Date().toISOString(), indexDigest, files: out };
346
+ // head: the commit the co-change evidence was mined at; a moved HEAD triggers a rebuild.
347
+ return { schemaVersion: SCHEMA, generatedAt: new Date().toISOString(), indexDigest, head: mined?.head ?? null, files: out };
220
348
  }
221
349
 
222
350
  const graphPath = (rootDir) => path.join(path.resolve(rootDir), '.cache', 'index', EDIT_GRAPH_FILE);
@@ -255,6 +383,7 @@ export function neighboursOf(graph, filePath) {
255
383
  tests: strs(e?.t),
256
384
  importers: strs(e?.i),
257
385
  imports: strs(e?.d),
386
+ together: (Array.isArray(e?.c) ? e.c : []).filter((x) => typeof x?.p === 'string').map((x) => ({ path: x.p, count: Number(x.n) || 0 })),
258
387
  };
259
388
  }
260
389
 
@@ -264,7 +393,8 @@ export function neighboursOf(graph, filePath) {
264
393
  export async function ensureEditGraph({ rootDir, indexDigest, inputs, signal } = {}) {
265
394
  try {
266
395
  const previousGraph = await loadEditGraph(rootDir);
267
- if (previousGraph && indexDigest && previousGraph.indexDigest === indexDigest) return previousGraph;
396
+ const head = await gitHead(path.resolve(rootDir), { signal });
397
+ if (previousGraph && indexDigest && previousGraph.indexDigest === indexDigest && (previousGraph.head ?? null) === head) return previousGraph;
268
398
  const graph = await buildEditGraph({ rootDir, indexDigest, previousGraph, signal, ...(typeof inputs === 'function' ? await inputs() : inputs) });
269
399
  await writeEditGraph(rootDir, graph);
270
400
  return graph;