@ngockhoale/ukit 3.5.3 → 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 (59) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/manifests/documentation.yaml +12 -1
  3. package/manifests/platform.full.yaml +12 -0
  4. package/package.json +27 -1
  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 +77 -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 +27 -0
  11. package/src/core/memory/mutateMemory.js +37 -1
  12. package/src/core/memory/observations.js +192 -0
  13. package/src/core/memory/recallEngine.js +120 -7
  14. package/src/core/memory/records.js +23 -0
  15. package/src/core/memory/writeGate.js +137 -0
  16. package/src/core/runtimeConfig.js +11 -1
  17. package/src/index/buildIndex.js +26 -0
  18. package/src/index/paths.js +3 -1
  19. package/src/index/queryIndex.js +225 -10
  20. package/src/index/resolveContext.js +1 -1
  21. package/template_project/.claude/hooks/edit-hint.mjs +64 -17
  22. package/template_project/.claude/hooks/session-episode-start.mjs +35 -0
  23. package/template_project/.claude/hooks/session-episode.sh +9 -4
  24. package/template_project/.claude/settings.json +2 -2
  25. package/template_project/.claude/ukit/index/lib/index-core.mjs +255 -12
  26. package/template_project/.claude/ukit/index/query-index.mjs +14 -3
  27. package/template_project/.claude/ukit/index/route-task.mjs +4 -1
  28. package/template_project/.claude/ukit/runtime/memory-check.mjs +241 -0
  29. package/template_project/.claude/ukit/runtime/memory-recall.mjs +120 -7
  30. package/template_project/.claude/ukit/runtime/memory-validity.mjs +28 -1
  31. package/template_project/.claude/ukit/runtime/self-improve-trigger.mjs +212 -5
  32. package/template_project/.omp/hooks/pre/ukit-bridge.js +2 -1
  33. package/template_project/ukit/storage/config.json +4 -2
  34. package/src/core/agentRuntime/completionGate.js +0 -179
  35. package/src/core/agentRuntime/context.js +0 -571
  36. package/src/core/agentRuntime/qualityComparison.js +0 -112
  37. package/src/core/agentRuntime/resourcePolicy.js +0 -78
  38. package/src/core/agentRuntime/runtimeSupport.js +0 -255
  39. package/src/core/codeintel/manifest.js +0 -176
  40. package/src/core/experiments/deliberation.js +0 -327
  41. package/src/core/experiments/dynamicWorkflow.js +0 -507
  42. package/src/core/handoffDocValidator.js +0 -154
  43. package/src/core/memory/deltaOverlays.js +0 -493
  44. package/src/core/memory/learningCandidates.js +0 -347
  45. package/src/core/observability/emit/sessionBoot.js +0 -407
  46. package/src/core/observability/evaluation/replay.js +0 -149
  47. package/src/core/observability/evaluation/scorecard.js +0 -465
  48. package/src/core/observability/schema/compatibility.js +0 -180
  49. package/src/core/observability/support/renderer.js +0 -130
  50. package/src/core/reviewPanelAggregate.js +0 -204
  51. package/src/core/taskBudgetValidator.js +0 -251
  52. package/src/core/taskProgressGuard.js +0 -227
  53. package/src/decision/reviewVerdict.js +0 -339
  54. package/src/decision/runtimeFilter.js +0 -150
  55. package/src/decision/runtimeScheduler.js +0 -239
  56. package/src/index/contextPack.js +0 -285
  57. package/src/index/impactContext.js +0 -360
  58. package/src/index/reviewPolicy.js +0 -368
  59. package/src/index/sensitivePath.js +0 -21
@@ -1,347 +0,0 @@
1
- // learningCandidates.js — M04.2 learning candidates (SPEC §5 FR-016, FR-018; C11).
2
- //
3
- // Normalizes repeated corrections/suppressions/escalations/verification-gaps
4
- // into observation records, then promotes them to LearningCandidate records
5
- // (C11) only after configured recurrence AND cross-session evidence.
6
- //
7
- // Contracts:
8
- // * Gated by `learning.candidates.stage` — 'off' (default) means zero
9
- // writes: observeLearningSignal is a no-op, maybeCreateCandidate returns
10
- // null. At 'shadow'/'canary'/'default' everything is still REPORT-ONLY:
11
- // candidates are created with meta.status 'proposed' and promotion stays
12
- // manual via the existing pending-candidate flow in store.js.
13
- // * Observations are memoryV2 records (provenance 'learning-observation');
14
- // candidates are memoryV2 records (provenance 'learning-candidate').
15
- // No second store.
16
- // * Scope classification is conservative: any session-scoped signal pins
17
- // the candidate to 'session' — session signals never leak to
18
- // project/user.
19
- // * Conflict detection prefers conditional refinement; project constraints
20
- // outrank user preferences (C11).
21
- // * NEVER THROWS on malformed signals — they are skipped, not fatal.
22
-
23
- import crypto from 'node:crypto';
24
- import { loadRuntimeConfig, resolveConfigStage } from '../runtimeConfig.js';
25
- import { queryRecords } from './storeV2.js';
26
- import { mutateMemory } from './mutateMemory.js';
27
-
28
- export const OBSERVATION_PROVENANCE = 'learning-observation';
29
- export const CANDIDATE_PROVENANCE = 'learning-candidate';
30
-
31
- const SIGNAL_KINDS = new Set([
32
- 'correction',
33
- 'suppression',
34
- 'escalation',
35
- 'verification-gap',
36
- ]);
37
-
38
- // C11 proposalType per signal kind.
39
- const PROPOSAL_TYPE_BY_KIND = {
40
- correction: 'preference',
41
- suppression: 'constraint',
42
- escalation: 'knowledge',
43
- 'verification-gap': 'overlay',
44
- };
45
-
46
- // C11 candidate scopes → memoryV2 record scopes.
47
- const CANDIDATE_TO_RECORD_SCOPE = {
48
- session: 'session',
49
- project: 'repo',
50
- user: 'user',
51
- };
52
-
53
- const DEFAULT_MIN_OCCURRENCES = 3;
54
- const DEFAULT_MIN_SESSIONS = 2;
55
- const MAX_EVIDENCE_REFS = 24;
56
- // Records live in the single records.json document — bound every field that
57
- // carries caller-controlled text so a signal can never grow it unboundedly.
58
- const MAX_SIGNAL_TEXT = 512;
59
- const MAX_META_FIELD = 512;
60
-
61
- function boundText(value, max = MAX_META_FIELD) {
62
- if (value == null) return null;
63
- const text = typeof value === 'string' ? value : JSON.stringify(value);
64
- return typeof text === 'string' ? text.slice(0, max) : null;
65
- }
66
-
67
- // Like boundText but preserves non-string scalars (numbers/booleans) so a
68
- // proposedDelta value keeps its type for downstream overlay conversion.
69
- function boundField(value, max = MAX_META_FIELD) {
70
- if (value == null) return null;
71
- if (typeof value !== 'string') return value;
72
- return value.slice(0, max);
73
- }
74
-
75
- // Bounds a proposedDelta in place-shape: {field, value} stay typed fields —
76
- // stringifying the whole object would break detectCandidateConflicts and
77
- // overlayFromCandidate, which read delta.field/delta.value.
78
- function boundDelta(delta) {
79
- if (delta == null || typeof delta !== 'object') return boundText(delta);
80
- return {
81
- ...delta,
82
- field: boundField(delta.field),
83
- value: boundField(delta.value),
84
- };
85
- }
86
-
87
- function normalizeText(text) {
88
- return String(text ?? '').toLowerCase().replace(/\s+/g, ' ').trim();
89
- }
90
-
91
- function normalizeValue(value) {
92
- if (value == null) return '';
93
- return normalizeText(typeof value === 'string' ? value : JSON.stringify(value));
94
- }
95
-
96
-
97
- function signalScopeHint(signal) {
98
- const hint = signal?.scopeHint ?? signal?.scope;
99
- return hint === 'project' || hint === 'user' ? hint : 'session';
100
- }
101
-
102
- async function candidatesConfig(projectRoot) {
103
- const config = await loadRuntimeConfig(projectRoot);
104
- const stage = resolveConfigStage(config, 'learning.candidates.stage');
105
- const raw = config?.learning?.candidates ?? {};
106
- return {
107
- stage,
108
- minOccurrences: Number.isFinite(raw.minOccurrences) && raw.minOccurrences > 0
109
- ? raw.minOccurrences
110
- : DEFAULT_MIN_OCCURRENCES,
111
- minSessions: Number.isFinite(raw.minSessions) && raw.minSessions > 0
112
- ? raw.minSessions
113
- : DEFAULT_MIN_SESSIONS,
114
- };
115
- }
116
-
117
- /**
118
- * classifyCandidateScope(signal) → 'session' | 'project' | 'user'
119
- * Conservative: unknown/absent hints resolve to 'session'.
120
- */
121
- export function classifyCandidateScope(signal) {
122
- return signalScopeHint(signal);
123
- }
124
-
125
- /**
126
- * detectCandidateConflicts(candidate, existing) → conflicts[]
127
- * A conflict is a contradiction on the same target: the candidate proposes a
128
- * different value for a field an existing project_rule/constraint already
129
- * pins. Project (repo-scoped) constraints outrank user-scoped candidates —
130
- * the conflict is flagged `outranked` and resolved by conditional refinement
131
- * rather than silent override.
132
- */
133
- export function detectCandidateConflicts(candidate, existing = []) {
134
- const target = normalizeText(candidate?.target ?? candidate?.proposedDelta?.field);
135
- if (!target) return [];
136
- const proposedValue = normalizeValue(
137
- candidate?.proposedDelta?.value ?? candidate?.proposedDelta,
138
- );
139
-
140
- const conflicts = [];
141
- for (const record of existing ?? []) {
142
- if (!record || record.status === 'archived') continue;
143
- if (record.provenance === CANDIDATE_PROVENANCE
144
- && record.meta?.status !== 'approved') continue;
145
- const recordTarget = normalizeText(record.meta?.target ?? record.meta?.constraint);
146
- if (!recordTarget || recordTarget !== target) continue;
147
- const recordValue = normalizeValue(record.meta?.value);
148
- if (!recordValue || recordValue === proposedValue) continue;
149
- const isProjectConstraint = record.type === 'project_rule' || record.scope === 'repo';
150
- conflicts.push({
151
- type: 'contradiction',
152
- recordId: record.id,
153
- target,
154
- existingValue: record.meta?.value ?? null,
155
- proposedValue: candidate?.proposedDelta?.value ?? null,
156
- outranked: isProjectConstraint && candidate?.scope === 'user',
157
- resolution: 'conditional-refinement',
158
- });
159
- }
160
- return conflicts;
161
- }
162
-
163
- /**
164
- * observeLearningSignal(projectRoot, signal) → observation record | null
165
- * signal: { kind, text, sessionId?, projectId?, scopeHint?, target?,
166
- * condition?, proposedDelta?, evidenceRef? }
167
- * Returns null when the feature stage is 'off' or the signal is malformed.
168
- */
169
- export async function observeLearningSignal(projectRoot, signal = {}) {
170
- const { stage } = await candidatesConfig(projectRoot);
171
- if (stage === 'off') return null;
172
- if (!SIGNAL_KINDS.has(signal?.kind) || !normalizeText(signal?.text)) return null;
173
-
174
- // Every caller-controlled string is bounded — records.json is a single
175
- // document, so an unbounded signal would grow it without limit.
176
- const text = boundText(signal.text, MAX_SIGNAL_TEXT);
177
- const target = boundText(signal.target);
178
- const signature = `${signal.kind}:${normalizeText(target ?? text)}`.slice(0, MAX_META_FIELD);
179
- // Idempotency is per (signature, session): the same signal re-observed in
180
- // the same session is one record, while distinct sessions still count as
181
- // separate occurrences for the minSessions promotion gate.
182
- const signalHash = crypto.createHash('sha1')
183
- .update(`${signature}|${boundText(signal.sessionId) ?? ''}`)
184
- .digest('hex');
185
-
186
- try {
187
- const res = await mutateMemory(
188
- { kind: 'project', projectRoot },
189
- {
190
- op: 'add',
191
- payload: {
192
- type: 'derived_fact',
193
- scope: CANDIDATE_TO_RECORD_SCOPE[signalScopeHint(signal)],
194
- text: `learning-signal ${signal.kind}: ${String(text).trim()}`,
195
- provenance: OBSERVATION_PROVENANCE,
196
- confidence: 0.3,
197
- createdBy: 'learning-observe',
198
- projectId: boundText(signal.projectId),
199
- trustTier: 'observation',
200
- meta: {
201
- kind: signal.kind,
202
- signature,
203
- sessionId: boundText(signal.sessionId),
204
- scopeHint: signalScopeHint(signal),
205
- target,
206
- condition: boundText(signal.condition),
207
- proposedDelta: boundDelta(signal.proposedDelta),
208
- evidenceRef: boundText(signal.evidenceRef),
209
- observedAt: Date.now(),
210
- },
211
- },
212
- idempotencyKey: `obs:${signalHash}`,
213
- actor: 'learning',
214
- },
215
- // Recurring signals share meta.signature with different text — generic
216
- // classification would REVIEW-archive them as 'contradiction'. Dedupe
217
- // here is the idempotency journal, not text classification.
218
- { classifyAdd: () => ({ action: 'ADD' }) },
219
- );
220
- if (res.status === 'ok' || res.status === 'duplicate') return res.record ?? null;
221
- return null;
222
- } catch {
223
- return null;
224
- }
225
- }
226
-
227
- function candidateText(kind, signalText, occurrences, sessions) {
228
- return `Learning candidate (${kind}): "${String(signalText).trim()}" — observed ${occurrences}× across ${sessions} sessions.`;
229
- }
230
-
231
- /**
232
- * maybeCreateCandidate(projectRoot) → candidate record | null
233
- * Scans observation records, groups by signature + projectId, and promotes
234
- * the first eligible group (occurrences >= minOccurrences AND distinct
235
- * sessions >= minSessions) into a proposed LearningCandidate. Idempotent —
236
- * an existing proposed/approved candidate for the signature is returned
237
- * instead of duplicated.
238
- */
239
- export async function maybeCreateCandidate(projectRoot) {
240
- const { stage, minOccurrences, minSessions } = await candidatesConfig(projectRoot);
241
- if (stage === 'off') return null;
242
-
243
- const records = await queryRecords(projectRoot, {});
244
- const observations = records
245
- .filter((r) => r.provenance === OBSERVATION_PROVENANCE && r.status !== 'archived')
246
- .sort((a, b) => (a.meta?.observedAt ?? a.created_at ?? 0) - (b.meta?.observedAt ?? b.created_at ?? 0));
247
- const existingCandidates = records.filter((r) => r.provenance === CANDIDATE_PROVENANCE);
248
-
249
- const groups = new Map();
250
- for (const obs of observations) {
251
- const key = `${obs.project_id ?? ''}|${obs.meta?.signature ?? ''}`;
252
- if (!groups.has(key)) groups.set(key, []);
253
- groups.get(key).push(obs);
254
- }
255
-
256
- let firstExisting = null;
257
- for (const group of groups.values()) {
258
- const signature = group[0]?.meta?.signature;
259
- const projectId = group[0]?.project_id ?? null;
260
-
261
- const existing = existingCandidates.find(
262
- (r) => r.meta?.signature === signature
263
- && (r.project_id ?? null) === projectId
264
- && (r.meta?.status === 'proposed' || r.meta?.status === 'approved'),
265
- );
266
- // Remember the first existing candidate but KEEP SCANNING — returning it
267
- // here starved every later eligible group: group A's candidate blocked
268
- // group B's from ever being created.
269
- if (existing) {
270
- firstExisting ??= existing;
271
- continue;
272
- }
273
-
274
- const sessions = new Set(group.map((o) => o.meta?.sessionId ?? null));
275
- if (group.length < minOccurrences || sessions.size < minSessions) continue;
276
-
277
- const scope = group.reduce(
278
- (narrowest, o) => {
279
- const s = o.meta?.scopeHint ?? 'session';
280
- return s === 'session' ? 'session' : narrowest === 'session' ? 'session' : s === 'project' ? 'project' : narrowest;
281
- },
282
- 'user',
283
- );
284
-
285
- const first = group[0];
286
- const evidenceRefs = group
287
- .flatMap((o) => [o.meta?.evidenceRef, o.id])
288
- .filter(Boolean)
289
- .slice(0, MAX_EVIDENCE_REFS);
290
-
291
- const draft = {
292
- scope,
293
- target: first.meta?.target ?? null,
294
- proposedDelta: first.meta?.proposedDelta ?? { field: first.meta?.target ?? null, value: first.text },
295
- };
296
- const conflicts = detectCandidateConflicts(draft, records);
297
-
298
- const candidateId = `lc_${crypto.randomBytes(6).toString('hex')}`;
299
- try {
300
- const res = await mutateMemory(
301
- { kind: 'project', projectRoot },
302
- {
303
- op: 'add',
304
- payload: {
305
- type: 'derived_fact',
306
- scope: CANDIDATE_TO_RECORD_SCOPE[scope],
307
- text: candidateText(first.meta?.kind, first.text, group.length, sessions.size),
308
- provenance: CANDIDATE_PROVENANCE,
309
- confidence: Math.min(0.9, 0.4 + group.length * 0.1),
310
- createdBy: 'learning-candidate',
311
- projectId,
312
- trustTier: 'candidate',
313
- meta: {
314
- id: candidateId,
315
- candidateId,
316
- schemaVersion: 1,
317
- status: 'proposed',
318
- signature,
319
- kind: first.meta?.kind ?? null,
320
- scope,
321
- proposalType: PROPOSAL_TYPE_BY_KIND[first.meta?.kind] ?? 'knowledge',
322
- condition: first.meta?.condition ?? `when ${first.meta?.kind ?? 'signal'} recurs`,
323
- proposedDelta: draft.proposedDelta,
324
- target: draft.target,
325
- evidenceRefs,
326
- occurrences: group.length,
327
- sessions: sessions.size,
328
- conflicts,
329
- },
330
- },
331
- idempotencyKey: `cand:${projectId ?? ''}|${signature}`,
332
- actor: 'learning',
333
- },
334
- // Candidate text differs from its source observations under the same
335
- // meta.signature — generic classification would REVIEW-archive it as
336
- // 'contradiction'. Dedupe is the signature scan above + journal.
337
- { classifyAdd: () => ({ action: 'ADD' }) },
338
- );
339
- if (res.status === 'ok' || res.status === 'duplicate') return res.record ?? null;
340
- return null;
341
- } catch {
342
- return null;
343
- }
344
- }
345
-
346
- return firstExisting;
347
- }