@ngockhoale/ukit 3.4.85 → 3.5.2

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 (34) hide show
  1. package/CHANGELOG.md +33 -1064
  2. package/bin/ukit +9 -0
  3. package/manifests/documentation.yaml +12 -0
  4. package/manifests/platform.full.yaml +23 -0
  5. package/package.json +1 -1
  6. package/src/cli/commands/install.js +12 -0
  7. package/src/cli/commands/memory.js +30 -3
  8. package/src/core/memory/episodeArchive.js +147 -0
  9. package/src/core/memory/episodes.js +199 -37
  10. package/src/core/memory/memoryHit.js +59 -40
  11. package/src/core/memory/mutateMemory.js +23 -3
  12. package/src/core/memory/recallEngine.js +423 -0
  13. package/src/core/memory/retrieval.js +55 -92
  14. package/src/core/observability/emit/lifecycle.js +30 -0
  15. package/src/core/runtimeConfig.js +7 -0
  16. package/src/index/buildIndex.js +22 -0
  17. package/src/index/impactContext.js +11 -1
  18. package/template_project/.claude/hooks/edit-hint.mjs +119 -0
  19. package/template_project/.claude/hooks/skill-router.sh +82 -51
  20. package/template_project/.claude/settings.json +2 -2
  21. package/template_project/.claude/ukit/index/edit-graph.mjs +274 -0
  22. package/template_project/.claude/ukit/index/lib/index-core.mjs +36 -1
  23. package/template_project/.claude/ukit/index/post-edit-verify.mjs +8 -5
  24. package/template_project/.claude/ukit/index/resolve-context.mjs +17 -0
  25. package/template_project/.claude/ukit/index/route-task.mjs +29 -48
  26. package/template_project/.claude/ukit/runtime/execution-ledger.mjs +45 -0
  27. package/template_project/.claude/ukit/runtime/hook-chain-runner.mjs +62 -5
  28. package/template_project/.claude/ukit/runtime/memory-lanes.mjs +237 -0
  29. package/template_project/.claude/ukit/runtime/memory-recall.mjs +423 -0
  30. package/template_project/.claude/ukit/runtime/reinject-context.mjs +29 -45
  31. package/template_project/.omp/hooks/pre/ukit-bridge.js +2 -1
  32. package/template_project/AGENTS.md +1 -1
  33. package/template_project/CLAUDE.md +1 -1
  34. package/template_project/instructions/core.md +1 -1
@@ -170,8 +170,29 @@ function splitTopLevelJsonObjects(text) {
170
170
 
171
171
  function coalesceJsonStdout(text) {
172
172
  if (typeof text !== 'string' || text.length === 0) return text;
173
- const docs = splitTopLevelJsonObjects(text);
174
- if (!docs || docs.length < 2) return text;
173
+ const split = splitTopLevelJsonObjects(text);
174
+ // Mixed stream: single-line JSON documents plus plain text lines. Only when every
175
+ // JSON line is PostToolUse context-only (and at least one exists) is the text folded
176
+ // into the document's additionalContext; anything else (deny + log line) stays byte-exact.
177
+ let plain = [];
178
+ let docs = split;
179
+ if (!split) {
180
+ docs = [];
181
+ for (const line of text.split('\n')) {
182
+ if (!line.trim()) continue;
183
+ let obj = null;
184
+ if (line.trimStart().startsWith('{')) { try { obj = JSON.parse(line); } catch { obj = null; } }
185
+ if (obj && typeof obj === 'object' && !Array.isArray(obj)) docs.push(obj); else plain.push(line.trim());
186
+ }
187
+ // A pretty-printed JSON fragment is not a log line: leave the stream untouched.
188
+ // Bracketed log prefixes such as "[ukit-safe-patch] OK" stay plain text.
189
+ if (plain.some((l) => /^[{}[\]],?$/.test(l) || l.startsWith('{') || /^"[^"]*"\s*(:|,?$)/.test(l))) return text;
190
+ const verdictFree = (d) => !('decision' in d) && d.continue !== false && !('stopReason' in d)
191
+ && (!d.hookSpecificOutput || (d.hookSpecificOutput.hookEventName === 'PostToolUse'
192
+ && !('permissionDecision' in d.hookSpecificOutput) && !('decision' in d.hookSpecificOutput)));
193
+ if (!plain.length || !docs.some((d) => d.hookSpecificOutput) || !docs.every(verdictFree)) return text;
194
+ }
195
+ if (!docs || (docs.length < 2 && !plain.length)) return text;
175
196
  const merged = {};
176
197
  const messages = [];
177
198
  for (const d of docs) {
@@ -180,12 +201,25 @@ function coalesceJsonStdout(text) {
180
201
  if (typeof value === 'string' && value) messages.push(value);
181
202
  continue;
182
203
  }
204
+ if (key === 'hookSpecificOutput' && value && typeof value === 'object' && merged.hookSpecificOutput
205
+ && typeof merged.hookSpecificOutput === 'object') {
206
+ // Two steps may each carry context: join with a newline, never let the later win.
207
+ const prev = merged.hookSpecificOutput;
208
+ const joined = [prev.additionalContext, value.additionalContext].filter((t) => typeof t === 'string' && t);
209
+ merged.hookSpecificOutput = { ...prev, ...value, ...(joined.length ? { additionalContext: joined.join('\n') } : {}) };
210
+ continue;
211
+ }
183
212
  if (key === 'continue' && merged.continue === false) continue;
184
213
  if (key === 'decision' && merged.decision === 'block') continue;
185
214
  if (key === 'reason' && merged.decision === 'block' && d.decision !== 'block') continue;
186
215
  merged[key] = value;
187
216
  }
188
217
  }
218
+ if (plain.length) {
219
+ // Plain lines are trimmed and placed before the documents' context (original order/indentation not preserved).
220
+ const h = merged.hookSpecificOutput;
221
+ h.additionalContext = [...plain, h.additionalContext].filter((t) => typeof t === 'string' && t).join('\n');
222
+ }
189
223
  if (messages.length) merged.systemMessage = messages.join('\n');
190
224
  return `${JSON.stringify(merged)}\n`;
191
225
  }
@@ -195,13 +229,37 @@ function coalesceJsonStdout(text) {
195
229
  // enough — a child killed mid-write can carry the marker in a truncated
196
230
  // capture, and calling that a decision would exempt a genuinely-skipped gate
197
231
  // from the fail-closed verdict. A real decision is a clean exit-0 verdict.
232
+ // WP-C: behaviour is exactly as at HEAD (any clean marker-carrying entry owns
233
+ // stdout) except for ONE shape: stdout whose every document parses and is a
234
+ // PostToolUse context-only `hookSpecificOutput` (additionalContext, no
235
+ // permissionDecision/decision). That is advisory context, not a verdict, and
236
+ // must merge with other steps' output instead of ending the chain.
237
+ function isPostToolUseContextOnly(stdout) {
238
+ const docs = typeof stdout === 'string' ? splitTopLevelJsonObjects(stdout) : null;
239
+ return Boolean(docs) && docs.length > 0 && docs.every((d) => {
240
+ const h = d?.hookSpecificOutput;
241
+ return h && typeof h === 'object' && h.hookEventName === 'PostToolUse'
242
+ && !('permissionDecision' in h) && !('decision' in h)
243
+ && !('decision' in d) && d.continue !== false && !('stopReason' in d);
244
+ });
245
+ }
246
+
198
247
  function emitsPermissionDecision(entry) {
199
248
  return Boolean(entry)
200
249
  && !entry.killed
201
250
  && entry.code === 0
202
251
  && entry.failureKind === 'ok'
203
252
  && typeof entry.stdout === 'string'
204
- && entry.stdout.includes('"hookSpecificOutput"');
253
+ && entry.stdout.includes('"hookSpecificOutput"')
254
+ && !isPostToolUseContextOnly(entry.stdout);
255
+ }
256
+
257
+ // Emit-time owner lookup: HEAD's loose marker lookup, skipping only a CLEAN
258
+ // PostToolUse context-only entry; unclean marker-carrying entries stay candidates.
259
+ function isDecisionOwnerCandidate(r) {
260
+ if (!r || typeof r.stdout !== 'string' || !r.stdout.includes('"hookSpecificOutput"')) return false;
261
+ const clean = !r.killed && r.code === 0 && r.failureKind === 'ok';
262
+ return !(clean && isPostToolUseContextOnly(r.stdout));
205
263
  }
206
264
 
207
265
  function recordTiming(projectRoot, payload, timing) {
@@ -786,8 +844,7 @@ try {
786
844
  // non-zero decision emitter stays routed through the code-2/fail-closed
787
845
  // paths below, per SPEC §FR-001); the strict predicate decides whether that
788
846
  // entry may claim stdout outright.
789
- const decisionResult = chain.results.find((r) =>
790
- typeof r.stdout === 'string' && r.stdout.includes('"hookSpecificOutput"'));
847
+ const decisionResult = chain.results.find(isDecisionOwnerCandidate);
791
848
  const decisionOwnsVerdict = emitsPermissionDecision(decisionResult);
792
849
  const last = decisionResult ?? chain.results[chain.results.length - 1];
793
850
 
@@ -0,0 +1,237 @@
1
+ // memory-lanes.mjs (3.5.2) - attaches memory to code: path lane + graph lane.
2
+ // Standalone ESM; deterministic, no LLM, async fs only, never throws to callers.
3
+ import fsp from 'node:fs/promises';
4
+ import path from 'node:path';
5
+ import { loadMarkdownDocs, normalizeMemorySources, rankDocs } from './memory-recall.mjs';
6
+ import { eligible, resolveProjectIdentityMirror } from './memory-policy.mjs';
7
+ import { resolveMemoryStage } from './memory-flags.mjs';
8
+
9
+ const MAX_STORE_BYTES = 2 * 1024 * 1024;
10
+ const MAX_STAT = 8;
11
+ const LINE_CHARS = 160;
12
+ const KNOWN_ROOTS = new Set(['src', 'tests', 'test', 'docs', 'scripts', 'lib', 'app', 'template_project', 'packages', 'bin']);
13
+ const EXT_RE = /\.[A-Za-z][A-Za-z0-9]{0,7}$/;
14
+ const LEGACY_STUB_RE = /^\s*Session\s+\S+?:\s*(?:writeOk|writeFail)\b/;
15
+
16
+ function normalizePath(raw, { needSlash = true } = {}) {
17
+ let t = String(raw ?? '').trim().replace(/`/g, '').replace(/\\/g, '/');
18
+ t = t.replace(/^(\.\/)+/, '').replace(/:\d+(?::\d+)?$/, '').replace(/[.,;:!?)\]}>"'*]+$/, '').replace(/^[("'[{<]+/, '');
19
+ // Second pass is intentional: "a.js:12:" only exposes ":12" after the trailing ":" is stripped.
20
+ t = t.replace(/:\d+(?::\d+)?$/, '');
21
+ if (!t || t.includes('://') || t.startsWith('/') || /^[A-Za-z]:/.test(t) || t.startsWith('~')) return null;
22
+ const segs = t.split('/');
23
+ if (segs.some((s) => s === '..' || s === '')) {
24
+ if (!(t.endsWith('/') && segs.slice(0, -1).every((s) => s && s !== '..'))) return null;
25
+ segs.pop();
26
+ }
27
+ const clean = segs.join('/');
28
+ const last = segs[segs.length - 1];
29
+ if (EXT_RE.test(last) && last.length > 2) return needSlash && segs.length < 2 ? null : clean;
30
+ if (segs.length >= 2 && (t.endsWith('/') || KNOWN_ROOTS.has(segs[0]))) return clean;
31
+ return null;
32
+ }
33
+
34
+ export function extractAnchors(doc) {
35
+ const out = new Set();
36
+ const text = String(doc?.text ?? '');
37
+ for (const tok of text.split(/\s+/)) {
38
+ const hit = /[/\\]/.test(tok) ?normalizePath(tok) : null;
39
+ if (hit) out.add(hit);
40
+ }
41
+ for (const ev of Array.isArray(doc?.evidence) ? doc.evidence : []) {
42
+ if (typeof ev === 'string') { const p = normalizePath(ev, { needSlash: false }); if (p) out.add(p); continue; }
43
+ if (ev?.kind && ev.kind !== 'file') continue;
44
+ const p = normalizePath(ev?.locator, { needSlash: false });
45
+ if (p) out.add(p);
46
+ }
47
+ return [...out].sort();
48
+ }
49
+
50
+ const byId = (a, b) => String(a.id ?? '').localeCompare(String(b.id ?? ''));
51
+
52
+ export function fuseLanes(lanes, { limit = Infinity } = {}) {
53
+ const seen = new Set();
54
+ const out = [];
55
+ for (const lane of Array.isArray(lanes) ? lanes : []) {
56
+ for (const id of lane ?? []) {
57
+ if (seen.has(id)) continue;
58
+ seen.add(id);
59
+ out.push(id);
60
+ }
61
+ }
62
+ return out.slice(0, limit);
63
+ }
64
+
65
+ function docEligible(doc, now) {
66
+ if (!doc || typeof doc !== 'object') return false;
67
+ if (doc.type === 'markdown') return true;
68
+ if ((doc.status ?? 'active') !== 'active' || doc.superseded_by) return false;
69
+ if (doc.valid_until != null && doc.valid_until <= now) return false;
70
+ return !LEGACY_STUB_RE.test(String(doc.text ?? ''));
71
+ }
72
+
73
+ const paths = (list) => (Array.isArray(list) ? list : []).map((x) => (typeof x === 'string' ? x : x?.path)).filter(Boolean);
74
+
75
+ export function recallForTarget({ target, neighbours, docs, query = '', limit = 2 } = {}) {
76
+ const empty = { ranked: [], abstained: true };
77
+ try {
78
+ const now = Date.now();
79
+ const pool = (Array.isArray(docs) ? docs : []).filter((d) => docEligible(d, now));
80
+ if (pool.length === 0 || !target) return empty;
81
+ const n = neighbours ?? {};
82
+ const mirrors = new Set(paths(n.mirrors));
83
+ const tests = new Set(paths(n.tests));
84
+ const imports = new Set([...paths(n.importers), ...paths(n.imports)]);
85
+ const tiers = [[], [], [], []];
86
+ const info = new Map();
87
+ for (const doc of pool) {
88
+ const anchors = extractAnchors(doc);
89
+ let tier = -1;
90
+ let via = '';
91
+ if (anchors.includes(target)) { tier = 0; via = 'this file'; }
92
+ else if (anchors.some((a) => mirrors.has(a))) { tier = 1; via = 'via mirror'; }
93
+ else if (anchors.some((a) => tests.has(a))) { tier = 2; via = 'via test'; }
94
+ else if (anchors.some((a) => imports.has(a))) { tier = 2; via = 'via import'; }
95
+ else if (anchors.some((a) => !EXT_RE.test(a) && target.startsWith(`${a}/`))) { tier = 3; via = 'via directory'; }
96
+ if (tier >= 0) { tiers[tier].push(doc); info.set(doc.id, { doc, tier, via }); }
97
+ }
98
+ const hasQuery = String(query ?? '').trim() !== '';
99
+ const bm = hasQuery ? rankDocs(pool, query, { limit: pool.length }).ranked : [];
100
+ const score = new Map(bm.map((e) => [e.doc.id, e.score]));
101
+ const lanes = tiers.map((list) => [...list]
102
+ .sort((a, b) => (score.get(b.id) ?? 0) - (score.get(a.id) ?? 0) || byId(a, b))
103
+ .map((d) => d.id));
104
+ const fill = [];
105
+ for (const e of bm) {
106
+ if (!info.has(e.doc.id)) { info.set(e.doc.id, { doc: e.doc, tier: 4, via: 'query' }); }
107
+ fill.push(e.doc.id);
108
+ }
109
+ const ranked = fuseLanes([...lanes, fill], { limit }).map((id) => info.get(id));
110
+ return { ranked, abstained: ranked.length === 0 };
111
+ } catch {
112
+ return empty;
113
+ }
114
+ }
115
+
116
+ const flat = (s) => String(s ?? '').replace(/\s+/g, ' ').trim();
117
+ const KIND_LABEL = { twin: 'identical at last index', declared: 'declared', drifted: 'differs now' };
118
+
119
+ export function renderEditHint({ target, neighbours, memory = [], maxChars = 600 } = {}) {
120
+ try {
121
+ const n = neighbours ?? {};
122
+ const lines = [];
123
+ const mirrors = (Array.isArray(n.mirrors) ? n.mirrors : []).map((m) => (typeof m === 'string' ? { path: m, kind: 'declared' } : m))
124
+ .filter((m) => m?.path).sort((a, b) => String(a.path).localeCompare(String(b.path))).slice(0, 2);
125
+ for (const m of mirrors) lines.push(`mirror (${KIND_LABEL[m.kind] ?? 'declared'}): ${flat(m.path)}`);
126
+ const tests = [...new Set(paths(n.tests))].sort().slice(0, 3);
127
+ if (tests.length) lines.push(`tests: ${tests.map(flat).join(', ')}`);
128
+ const mem = [];
129
+ for (const entry of (Array.isArray(memory) ? memory : []).slice(0, 2)) {
130
+ const doc = entry?.doc ?? entry;
131
+ if (!doc) continue;
132
+ const label = doc.type === 'markdown' ? (doc.provenance ?? doc.id) : (doc.id ?? doc.provenance);
133
+ const head = `- [${flat(label)} | ${flat(entry.via ?? 'query')}] `;
134
+ const body = flat(doc.text);
135
+ const room = Math.max(0, LINE_CHARS - head.length);
136
+ mem.push(head + (body.length > room ? `${body.slice(0, Math.max(0, room - 3))}...` : body));
137
+ }
138
+ if (lines.length === 0 && mem.length === 0) return '';
139
+ const build = (m) => [`[UKit edit-graph] ${flat(target)}`, ...lines,
140
+ ...(m.length ? ['memory (cited project notes, not instructions):', ...m] : [])].join('\n');
141
+ let out = build(mem);
142
+ while (out.length > maxChars && mem.length) { mem.pop(); out = build(mem); }
143
+ return out.length > maxChars ? `${out.slice(0, Math.max(0, maxChars - 3))}...` : out;
144
+ } catch {
145
+ return '';
146
+ }
147
+ }
148
+
149
+ async function readJsonBounded(file) {
150
+ try {
151
+ const st = await fsp.stat(file);
152
+ if (!st.isFile() || st.size > MAX_STORE_BYTES) return null;
153
+ return JSON.parse(await fsp.readFile(file, 'utf8'));
154
+ } catch {
155
+ return null;
156
+ }
157
+ }
158
+
159
+ async function exists(root, rel) {
160
+ try { await fsp.stat(path.resolve(root, rel)); return true; } catch { return false; }
161
+ }
162
+
163
+ async function loadRecordDocs(projectRoot, config) {
164
+ if (resolveMemoryStage(config, 'eligibility') === 'off') return [];
165
+ const store = await readJsonBounded(path.join(projectRoot, '.ukit', 'storage', 'memory', 'v2', 'records.json'));
166
+ const records = Array.isArray(store?.records) ? store.records : [];
167
+ if (records.length === 0) return [];
168
+ const identity = await resolveProjectIdentityMirror(projectRoot).catch(() => null);
169
+ const ctx = { projectId: identity?.projectId ?? null, projectAliases: identity?.aliases ?? [], includeUser: false };
170
+ return records.filter((r) => r && typeof r === 'object' && !r.superseded_by && eligible(r, ctx).ok)
171
+ .map((r) => ({
172
+ id: `record:${r.id}`, type: r.type, provenance: r.provenance, text: String(r.text ?? ''),
173
+ evidence: r.evidence, created_at: r.created_at ?? 0,
174
+ }));
175
+ }
176
+
177
+ const EMPTY = { text: '', neighbours: null, memoryIds: [] };
178
+
179
+ export async function editHintFor({
180
+ projectRoot, target, config = null, query = '', exclude = {}, signal, deps = {}, memoryBudgetMs,
181
+ } = {}) {
182
+ try {
183
+ if (process.env.UKIT_EDIT_HINTS === '0' || !projectRoot || !target) return EMPTY;
184
+ const cfg = config ?? await readJsonBounded(path.join(projectRoot, '.ukit', 'storage', 'config.json'));
185
+ if (cfg?.memory?.editHints?.enabled === false) return EMPTY;
186
+ const rel = normalizePath(target, { needSlash: false });
187
+ if (!rel || signal?.aborted) return EMPTY;
188
+ let loadGraph = deps.loadEditGraph;
189
+ let neighboursOf = deps.neighboursOf;
190
+ if (!loadGraph || !neighboursOf) {
191
+ const mod = await import('../index/edit-graph.mjs').catch(() => null);
192
+ loadGraph = mod?.loadEditGraph;
193
+ neighboursOf = mod?.neighboursOf;
194
+ }
195
+ const graph = loadGraph ? await loadGraph(projectRoot, { signal }) : null;
196
+ const raw = graph && neighboursOf ? neighboursOf(graph, rel) : null;
197
+ const skip = new Set(Array.isArray(exclude?.paths) ? exclude.paths : []);
198
+ const keep = (p) => !skip.has(typeof p === 'string' ? p : p?.path);
199
+ const sorted = (list) => (Array.isArray(list) ? list : []).filter(keep)
200
+ .sort((a, b) => String(a?.path ?? a).localeCompare(String(b?.path ?? b)));
201
+ let neighbours = {
202
+ mirrors: sorted(raw?.mirrors), tests: sorted(raw?.tests),
203
+ importers: sorted(raw?.importers), imports: sorted(raw?.imports),
204
+ };
205
+ const probe = [...neighbours.mirrors.slice(0, 4).map((m) => m.path), ...neighbours.tests.slice(0, MAX_STAT - Math.min(4, neighbours.mirrors.length))];
206
+ const alive = new Set((await Promise.all(probe.slice(0, MAX_STAT).map(async (p) => ((await exists(projectRoot, p)) ? p : null)))).filter(Boolean));
207
+ const probed = new Set(probe.slice(0, MAX_STAT));
208
+ const live = (p) => !probed.has(p) || alive.has(p);
209
+ neighbours = {
210
+ ...neighbours,
211
+ mirrors: neighbours.mirrors.filter((m) => live(m.path)),
212
+ tests: neighbours.tests.filter(live),
213
+ };
214
+ if (signal?.aborted) return EMPTY;
215
+ // Graph part is ready; memory gets its own sub-budget and never delays it.
216
+ let timer;
217
+ const lookup = deps.loadMemory ? deps.loadMemory() : Promise.all([
218
+ loadRecordDocs(projectRoot, cfg),
219
+ loadMarkdownDocs(projectRoot, normalizeMemorySources(cfg)),
220
+ ]);
221
+ lookup.catch(() => {});
222
+ const loaded = Number.isFinite(memoryBudgetMs)
223
+ ? await Promise.race([lookup, new Promise((resolve) => { timer = setTimeout(() => resolve(null), Math.max(1, memoryBudgetMs)); })])
224
+ : await lookup;
225
+ clearTimeout(timer);
226
+ const memoryMissed = loaded === null;
227
+ const [records, markdown] = loaded ?? [[], []];
228
+ const drop = new Set(Array.isArray(exclude?.memoryIds) ? exclude.memoryIds : []);
229
+ const docs = [...records, ...markdown].filter((d) => !drop.has(d.id));
230
+ const { ranked } = recallForTarget({ target: rel, neighbours, docs, query });
231
+ const text = renderEditHint({ target: rel, neighbours, memory: ranked });
232
+ if (!text) return { text: '', neighbours, memoryIds: [], memoryMissed };
233
+ return { text, neighbours, memoryIds: ranked.slice(0, 2).map((e) => e.doc.id), memoryMissed };
234
+ } catch {
235
+ return EMPTY;
236
+ }
237
+ }