@ngockhoale/ukit 3.5.3 → 3.5.5

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 (70) hide show
  1. package/CHANGELOG.md +36 -0
  2. package/manifests/documentation.yaml +12 -1
  3. package/manifests/platform.full.yaml +12 -0
  4. package/package.json +29 -2
  5. package/src/cli/commands/doctor.js +41 -0
  6. package/src/cli/commands/indexTools.js +10 -4
  7. package/src/cli/commands/memory.js +88 -6
  8. package/src/core/memory/episodes.js +106 -7
  9. package/src/core/memory/memoryCheck.js +241 -0
  10. package/src/core/memory/memoryCheckRun.js +39 -0
  11. package/src/core/memory/memoryHit.js +31 -15
  12. package/src/core/memory/mutateMemory.js +37 -1
  13. package/src/core/memory/observations.js +192 -0
  14. package/src/core/memory/recallEngine.js +159 -10
  15. package/src/core/memory/recallLanes.js +182 -0
  16. package/src/core/memory/records.js +23 -0
  17. package/src/core/memory/retrieval.js +13 -1
  18. package/src/core/memory/topicCommand.js +75 -0
  19. package/src/core/memory/topicPages.js +545 -0
  20. package/src/core/memory/writeGate.js +137 -0
  21. package/src/core/runtimeConfig.js +56 -1
  22. package/src/decision/registry.js +17 -0
  23. package/src/index/buildIndex.js +312 -5
  24. package/src/index/languageTools.js +100 -0
  25. package/src/index/paths.js +4 -1
  26. package/src/index/queryIndex.js +356 -14
  27. package/src/index/resolveContext.js +1 -1
  28. package/template_project/.claude/hooks/edit-hint.mjs +64 -17
  29. package/template_project/.claude/hooks/session-episode-start.mjs +35 -0
  30. package/template_project/.claude/hooks/session-episode.sh +9 -4
  31. package/template_project/.claude/settings.json +2 -2
  32. package/template_project/.claude/ukit/index/lib/index-core.mjs +769 -18
  33. package/template_project/.claude/ukit/index/query-index.mjs +14 -3
  34. package/template_project/.claude/ukit/index/refresh-index.mjs +11 -0
  35. package/template_project/.claude/ukit/index/route-task.mjs +4 -1
  36. package/template_project/.claude/ukit/runtime/memory-check.mjs +241 -0
  37. package/template_project/.claude/ukit/runtime/memory-lanes.mjs +9 -2
  38. package/template_project/.claude/ukit/runtime/memory-recall.mjs +159 -10
  39. package/template_project/.claude/ukit/runtime/memory-topics.mjs +545 -0
  40. package/template_project/.claude/ukit/runtime/memory-validity.mjs +28 -1
  41. package/template_project/.claude/ukit/runtime/self-improve-trigger.mjs +212 -5
  42. package/template_project/.omp/hooks/pre/ukit-bridge.js +2 -1
  43. package/template_project/ukit/storage/config.json +21 -2
  44. package/manifests/instructionRules.yaml +0 -442
  45. package/src/core/agentRuntime/completionGate.js +0 -179
  46. package/src/core/agentRuntime/context.js +0 -571
  47. package/src/core/agentRuntime/qualityComparison.js +0 -112
  48. package/src/core/agentRuntime/resourcePolicy.js +0 -78
  49. package/src/core/agentRuntime/runtimeSupport.js +0 -255
  50. package/src/core/codeintel/manifest.js +0 -176
  51. package/src/core/experiments/deliberation.js +0 -327
  52. package/src/core/experiments/dynamicWorkflow.js +0 -507
  53. package/src/core/handoffDocValidator.js +0 -154
  54. package/src/core/memory/deltaOverlays.js +0 -493
  55. package/src/core/memory/learningCandidates.js +0 -347
  56. package/src/core/observability/emit/sessionBoot.js +0 -407
  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/index/contextPack.js +0 -285
  68. package/src/index/impactContext.js +0 -360
  69. package/src/index/reviewPolicy.js +0 -368
  70. package/src/index/sensitivePath.js +0 -21
@@ -22,7 +22,7 @@
22
22
  import fs from 'node:fs';
23
23
  import path from 'node:path';
24
24
  import { spawn } from 'node:child_process';
25
- import { fileURLToPath } from 'node:url';
25
+ import { fileURLToPath, pathToFileURL } from 'node:url';
26
26
 
27
27
  export const MIN_INTERVAL_MS = 10 * 60 * 1000;
28
28
 
@@ -83,16 +83,223 @@ export function triggerSelfImprove({ projectRoot, now = Date.now(), spawnImpl =
83
83
  }
84
84
  }
85
85
 
86
+ // ---- Episode CLI resolution + session-start trigger (3.5.4) ----------------
87
+ // One resolver for every episode/self-improve spawn: the project-pinned CLI
88
+ // (cli.json) wins. Without it the PATH `ukit` is used ONLY when it is not older
89
+ // than the project's installed runtime - an older CLI writes the wrong record
90
+ // shape, so it is refused and the reason is left in episode-cli.json, which
91
+ // `ukit doctor` prints. Async fs only; the PATH version probe is cached by
92
+ // binary path + mtime and only ever runs in a detached worker or the SessionEnd
93
+ // hook's own (already bounded) CLI probe step, never in the SessionStart hook.
94
+ export const EPISODE_START_MIN_INTERVAL_MS = 10 * 60 * 1000;
95
+ const CLI_STATE_REL = path.join('.ukit', 'storage', 'learning', 'episode-cli.json');
96
+ const START_MARKER_REL = path.join('.ukit', 'storage', 'learning', 'episode-start.json');
97
+ const RESULT_REL = path.join('.ukit', 'storage', 'learning', 'episode-start-result.json');
98
+ const PROBE_CACHE_REL = path.join('.ukit', 'storage', 'cache', 'ukit-cli-probe.json');
99
+
100
+ function parseVersion(text) {
101
+ const m = /(\d+)\.(\d+)\.(\d+)/.exec(String(text ?? ''));
102
+ return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
103
+ }
104
+ export function compareVersions(a, b) {
105
+ const x = parseVersion(a); const y = parseVersion(b);
106
+ if (!x || !y) return null;
107
+ for (let i = 0; i < 3; i += 1) if (x[i] !== y[i]) return x[i] < y[i] ? -1 : 1;
108
+ return 0;
109
+ }
110
+
111
+ async function readJsonAsync(file) {
112
+ try { return JSON.parse(await fs.promises.readFile(file, 'utf8')); } catch { return null; }
113
+ }
114
+ // Advisory state only, and never a reason to resurrect a project: when `<root>/.ukit/storage`
115
+ // is gone (project deleted, temp dir torn down while a detached worker was still running) the
116
+ // write is dropped instead of `mkdir -p`-ing the whole tree back into existence.
117
+ async function writeJsonAsync(file, value) {
118
+ try {
119
+ const marker = path.join('.ukit', 'storage');
120
+ const at = file.lastIndexOf(marker);
121
+ if (at >= 0) {
122
+ try { await fs.promises.stat(file.slice(0, at + marker.length)); } catch { return; }
123
+ }
124
+ await fs.promises.mkdir(path.dirname(file), { recursive: true });
125
+ const tmp = `${file}.${process.pid}.tmp`;
126
+ await fs.promises.writeFile(tmp, `${JSON.stringify(value)}\n`, 'utf8');
127
+ await fs.promises.rename(tmp, file);
128
+ } catch { /* advisory state only */ }
129
+ }
130
+
131
+ // Version of the runtime installed in this project (what the CLI must not be older than).
132
+ async function projectRuntimeVersion(projectRoot) {
133
+ const meta = await readJsonAsync(path.join(projectRoot, '.claude', 'ukit', '.ukit', 'install.json'));
134
+ return typeof meta?.version === 'string' ? meta.version : null;
135
+ }
136
+
137
+ // PATH lookup of `ukit`. On win32 npm installs `ukit.cmd` (and an extensionless sh shim that
138
+ // Windows cannot execute), so the bare name is never tried there: PATHEXT order decides.
139
+ // `platform` is injectable so the Windows branch is unit-testable off Windows.
140
+ async function findOnPath(name, env = process.env, platform = process.platform) {
141
+ const win = platform === 'win32';
142
+ const sep = win ? ';' : path.delimiter;
143
+ const pathVar = win ? (env.PATH ?? env.Path ?? env.path) : env.PATH;
144
+ const exts = win
145
+ ? String(env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)
146
+ : [''];
147
+ // path.join IS path.win32.join on a real Windows host; keeping it host-native also lets the
148
+ // injected-platform unit test stat real files off Windows.
149
+ const join = path.join;
150
+ for (const dir of String(pathVar ?? '').split(sep).filter(Boolean)) {
151
+ for (const ext of exts) {
152
+ const file = join(dir, `${name}${ext}`);
153
+ try { const st = await fs.promises.stat(file); if (st.isFile()) return { file, mtimeMs: st.mtimeMs }; } catch { /* next */ }
154
+ }
155
+ }
156
+ return null;
157
+ }
158
+
159
+ // How to execute an ABSOLUTE binary path. POSIX and win32 .exe/.com spawn directly (no shell,
160
+ // so a timeout kill reaches the real process). Only win32 .cmd/.bat needs cmd.exe; the path is
161
+ // quoted because shell:true concatenates the command into one string.
162
+ function spawnSpec(file, platform = process.platform) {
163
+ const shell = platform === 'win32' && /\.(cmd|bat)$/i.test(file);
164
+ return { cmd: shell && /\s/.test(file) ? `"${file}"` : file, shell };
165
+ }
166
+
167
+ function runVersion(file, platform) {
168
+ return new Promise((resolve) => {
169
+ let out = '';
170
+ let child;
171
+ const spec = spawnSpec(file, platform);
172
+ try {
173
+ child = spawn(spec.cmd, ['--version'], { stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000, killSignal: 'SIGKILL', ...(spec.shell ? { shell: true } : {}) });
174
+ } catch { resolve(null); return; }
175
+ child.stdout.on('data', (d) => { out += d; });
176
+ child.on('error', () => resolve(null));
177
+ child.on('close', () => resolve(parseVersion(out) ? out.trim() : null));
178
+ });
179
+ }
180
+
181
+ async function pathCliVersion(projectRoot, env = process.env, platform = process.platform) {
182
+ const found = await findOnPath('ukit', env, platform);
183
+ if (!found) return { version: null, file: null };
184
+ const cacheFile = path.join(projectRoot, PROBE_CACHE_REL);
185
+ const cache = await readJsonAsync(cacheFile);
186
+ if (cache?.file === found.file && cache.mtimeMs === found.mtimeMs && cache.version) return { version: cache.version, file: found.file };
187
+ const version = await runVersion(found.file, platform);
188
+ if (version) await writeJsonAsync(cacheFile, { file: found.file, mtimeMs: found.mtimeMs, version });
189
+ return { version, file: found.file };
190
+ }
191
+
192
+ // -> { cmd, pre, shell, source } | { reason }. Records the outcome for doctor. For the PATH
193
+ // source `cmd` is the ABSOLUTE path that was probed (the probed binary is the one executed).
194
+ export async function resolveEpisodeCli(projectRoot, env = process.env, platform = process.platform) {
195
+ const stateFile = path.join(projectRoot, CLI_STATE_REL);
196
+ const located = resolveCliLocator(projectRoot);
197
+ if (located) {
198
+ await writeJsonAsync(stateFile, { ok: true, source: 'cli.json', at: new Date().toISOString() });
199
+ return { cmd: located.node, pre: [located.bin], shell: false, source: 'cli.json' };
200
+ }
201
+ const runtime = await projectRuntimeVersion(projectRoot);
202
+ const probe = await pathCliVersion(projectRoot, env, platform);
203
+ let reason = null;
204
+ if (!probe.file) reason = 'cli.json missing/invalid and no ukit on PATH';
205
+ // Refuse only a CLI PROVABLY older than the runtime; an unreadable version is not proof.
206
+ else if (runtime && probe.version && compareVersions(probe.version, runtime) === -1) {
207
+ reason = `cli.json missing/invalid and PATH ukit ${probe.version} is older than the project runtime ${runtime}`;
208
+ }
209
+ if (reason) {
210
+ await writeJsonAsync(stateFile, { ok: false, reason: `${reason} - rerun ukit install`, at: new Date().toISOString() });
211
+ return { reason };
212
+ }
213
+ await writeJsonAsync(stateFile, { ok: true, source: 'path', at: new Date().toISOString() });
214
+ const spec = spawnSpec(probe.file, platform);
215
+ return { cmd: spec.cmd, pre: [], shell: spec.shell, source: 'path' };
216
+ }
217
+
218
+ // SessionStart (every source): throttled, detached, bounded. Writes the marker BEFORE
219
+ // spawning so a compact storm cannot launch twice. Returns true when a worker was launched.
220
+ export async function triggerEpisodeStart({ projectRoot, now = Date.now(), spawnImpl = spawn } = {}) {
221
+ try {
222
+ if (typeof projectRoot !== 'string' || !projectRoot) return false;
223
+ const root = path.resolve(projectRoot);
224
+ const config = await readJsonAsync(path.join(root, '.ukit', 'storage', 'config.json'));
225
+ if (config?.learning?.episodes?.autoWrite !== true) return false;
226
+ const marker = path.join(root, START_MARKER_REL);
227
+ const last = Number((await readJsonAsync(marker))?.at);
228
+ if (Number.isFinite(last) && last <= now && now - last < EPISODE_START_MIN_INTERVAL_MS) return false;
229
+ await writeJsonAsync(marker, { at: now });
230
+ const env = { ...process.env };
231
+ delete env.UKIT_HOOK_DEADLINE_MS;
232
+ const child = spawnImpl(process.execPath, [fileURLToPath(import.meta.url), '--episode-start', root], {
233
+ cwd: root, env, detached: true, stdio: 'ignore', windowsHide: true,
234
+ });
235
+ child.on?.('error', () => {});
236
+ child.unref?.();
237
+ return true;
238
+ } catch {
239
+ return false;
240
+ }
241
+ }
242
+
243
+ // Detached worker body: resolve the CLI, then `memory episode --start` (bounded).
244
+ // Records its outcome next to the marker (episode-start-result.json) so a failed spawn or
245
+ // dead worker is visible in `ukit doctor` instead of silently costing the throttle window.
246
+ export async function runEpisodeStartWorker(projectRoot) {
247
+ // The project vanished between the trigger and this worker: exit quietly, create nothing.
248
+ try { await fs.promises.stat(path.join(projectRoot, '.ukit', 'storage')); } catch { return { ok: false, reason: 'project gone' }; }
249
+ const resultFile = path.join(projectRoot, RESULT_REL);
250
+ const done = async (outcome) => { await writeJsonAsync(resultFile, { ...outcome, at: new Date().toISOString() }); return outcome; };
251
+ await writeJsonAsync(resultFile, { ok: null, state: 'started', at: new Date().toISOString() });
252
+ const cli = await resolveEpisodeCli(projectRoot);
253
+ if (cli.reason) return done({ ok: false, reason: cli.reason });
254
+ return new Promise((resolve) => {
255
+ let child;
256
+ let out = '';
257
+ try {
258
+ child = spawn(cli.cmd, [...cli.pre, 'memory', 'episode', '--start'], {
259
+ cwd: projectRoot, stdio: ['ignore', 'pipe', 'ignore'], timeout: 20000, killSignal: 'SIGKILL', ...(cli.shell ? { shell: true } : {}),
260
+ });
261
+ } catch (e) { resolve(done({ ok: false, reason: `spawn failed: ${e?.message ?? e}` })); return; }
262
+ child.stdout.on('data', (d) => { if (out.length < 4096) out += d; });
263
+ child.on('error', (e) => resolve(done({ ok: false, reason: `spawn error: ${e?.message ?? e}` })));
264
+ child.on('close', (code, signal) => {
265
+ const m = /recorded=(\d+) skipped=(\d+) failed=(\d+)/.exec(out);
266
+ if (code === 0 && m) resolve(done({ ok: true, recorded: Number(m[1]), skipped: Number(m[2]), failed: Number(m[3]) }));
267
+ else resolve(done({ ok: false, reason: signal ? `killed by ${signal} (timeout)` : `exit ${code}` }));
268
+ });
269
+ });
270
+ }
271
+
272
+ // No fs here: this runs at IMPORT time, which for the SessionStart/route-task paths is inside an
273
+ // armed hook deadline (no sync fs there, ever). Node already resolved the main entry's symlinks
274
+ // when it built import.meta.url, and every launcher (the detached worker, a direct
275
+ // `node self-improve-trigger.mjs`) passes that same resolved path, so a URL compare is exact.
86
276
  function isMainModule() {
87
277
  try {
88
- const self = fs.realpathSync(fileURLToPath(import.meta.url));
89
- const invoked = process.argv[1] ? fs.realpathSync(process.argv[1]) : '';
90
- return self === invoked;
278
+ return Boolean(process.argv[1]) && import.meta.url === pathToFileURL(process.argv[1]).href;
279
+ } catch {
280
+ return false;
281
+ }
282
+ }
283
+
284
+ // A symlinked entry path (`.codex/ukit/...` -> real dir) keeps its link spelling in argv[1] while
285
+ // import.meta.url is the real path, so the URL compare misses. Only the worker launch (which
286
+ // carries --episode-start, never the hook's plain import) pays an ASYNC realpath to compare again.
287
+ async function isEpisodeStartEntry() {
288
+ if (process.argv[2] !== '--episode-start' || !process.argv[1]) return false;
289
+ try {
290
+ return import.meta.url === pathToFileURL(await fs.promises.realpath(process.argv[1])).href;
91
291
  } catch {
92
292
  return false;
93
293
  }
94
294
  }
95
295
 
296
+ function runEpisodeStartEntry() {
297
+ runEpisodeStartWorker(path.resolve(process.argv[3] || process.cwd())).catch(() => {}).finally(() => process.exit(0));
298
+ }
299
+
96
300
  if (isMainModule()) {
97
- triggerSelfImprove({ projectRoot: process.argv[2] || process.env.CLAUDE_PROJECT_DIR || process.cwd() });
301
+ if (process.argv[2] === '--episode-start') runEpisodeStartEntry();
302
+ else triggerSelfImprove({ projectRoot: process.argv[2] || process.env.CLAUDE_PROJECT_DIR || process.cwd() });
303
+ } else if (process.argv[2] === '--episode-start') {
304
+ isEpisodeStartEntry().then((yes) => { if (yes) runEpisodeStartEntry(); }).catch(() => {});
98
305
  }
@@ -85,7 +85,7 @@ export const HOOK_EVENT_MAP = {
85
85
  // owns the mandate-first lead (TASK-042 contract); the emit is advisory,
86
86
  // <250ms, and writes the session's `execution.started` record after the
87
87
  // context-producing scripts.
88
- session_start: ['project-important.sh', 'auto-prune-bash.sh', 'reset-compact-pressure.sh', 'handoff-resume.sh', 'observability-emit.mjs'],
88
+ session_start: ['project-important.sh', 'auto-prune-bash.sh', 'reset-compact-pressure.sh', 'handoff-resume.sh', 'observability-emit.mjs', 'session-episode-start.mjs'],
89
89
  // TASK-002 (cycle 45): omp emits `session_stop` (no `session_end`); the chain
90
90
  // runs only on RELEASED stops inside runSessionStop — never on blocked or
91
91
  // dedupe-skipped stops, since `ukit memory episode` dedupes on meta.ledgerKey
@@ -184,6 +184,7 @@ export const ADVISORY_SCRIPTS = new Set([
184
184
  // TASK-003 (FR-003): session-start emit step, advisory — a telemetry fault
185
185
  // can never block or delay session start.
186
186
  'observability-emit.mjs',
187
+ 'session-episode-start.mjs',
187
188
  ]);
188
189
 
189
190
  function classifyFailure(scriptName) {
@@ -337,13 +337,29 @@
337
337
  },
338
338
  "killSwitch": false
339
339
  },
340
+ "index": {
341
+ "fusion": false
342
+ },
340
343
  "memory": {
341
344
  "enabled": true,
342
345
  "progressiveRetrieval": true,
343
346
  "maxInjectionTokens": 320,
344
347
  "archiveAfterDays": 30,
345
348
  "maxSessions": 20,
346
- "redactSecrets": true
349
+ "redactSecrets": true,
350
+ "writeGate": "strict",
351
+ "topics": {
352
+ "recall": true,
353
+ "hint": true
354
+ },
355
+ "recall": {
356
+ "vector": {
357
+ "enabled": false
358
+ },
359
+ "rerank": {
360
+ "stage": "off"
361
+ }
362
+ }
347
363
  },
348
364
  "validation": {
349
365
  "enabled": true,
@@ -766,7 +782,10 @@
766
782
  "maxInjectionTokens": "S\u1ed1 token memory t\u1ed1i \u0111a \u0111\u01b0\u1ee3c inject v\u00e0o context (clamp th\u1ef1c t\u1ebf trong kho\u1ea3ng 160\u2013640).",
767
783
  "archiveAfterDays": "Sau bao nhi\u00eau ng\u00e0y memory c\u00f3 th\u1ec3 \u0111\u01b0\u1ee3c archive/compact.",
768
784
  "maxSessions": "S\u1ed1 session memory g\u1ea7n \u0111\u00e2y gi\u1eef active.",
769
- "redactSecrets": "C\u1ed1 tr\u00e1nh l\u01b0u secret v\u00e0o memory."
785
+ "redactSecrets": "C\u1ed1 tr\u00e1nh l\u01b0u secret v\u00e0o memory.",
786
+ "writeGate": "strict (default) or off. strict: every non-generated record write is checked for size, secrets, source evidence (an existing file, commit or episode id) and near-duplicates; scope user needs no file evidence.",
787
+ "topics": "Topic pages (docs/memory/topics/*.md, built with `ukit memory topic build <dir>`). recall (default true): pages are recall documents, a page whose directory changed is labelled stale; inert until a page exists. hint (default true): the edit hint names the module page path.",
788
+ "recall": "Optional CLI-only recall lanes, both off. vector.enabled: embedding cosine fused with BM25 by RRF. rerank.stage (off|shadow|canary|default): unic-decision confirms the top candidates; timeout or failure keeps the BM25 order. Measured on the gold bench neither raised the numbers, so both stay off."
770
789
  },
771
790
  "validation": {
772
791
  "enabled": "B\u1eadt ki\u1ec3m tra output nh\u1eb9.",