@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.
- package/CHANGELOG.md +21 -0
- package/manifests/documentation.yaml +12 -1
- package/manifests/platform.full.yaml +12 -0
- package/package.json +27 -1
- package/src/cli/commands/doctor.js +41 -0
- package/src/cli/commands/indexTools.js +10 -4
- package/src/cli/commands/memory.js +77 -6
- package/src/core/memory/episodes.js +106 -7
- package/src/core/memory/memoryCheck.js +241 -0
- package/src/core/memory/memoryCheckRun.js +27 -0
- package/src/core/memory/mutateMemory.js +37 -1
- package/src/core/memory/observations.js +192 -0
- package/src/core/memory/recallEngine.js +120 -7
- package/src/core/memory/records.js +23 -0
- package/src/core/memory/writeGate.js +137 -0
- package/src/core/runtimeConfig.js +11 -1
- package/src/index/buildIndex.js +26 -0
- package/src/index/paths.js +3 -1
- package/src/index/queryIndex.js +225 -10
- package/src/index/resolveContext.js +1 -1
- package/template_project/.claude/hooks/edit-hint.mjs +64 -17
- package/template_project/.claude/hooks/session-episode-start.mjs +35 -0
- package/template_project/.claude/hooks/session-episode.sh +9 -4
- package/template_project/.claude/settings.json +2 -2
- package/template_project/.claude/ukit/index/lib/index-core.mjs +255 -12
- package/template_project/.claude/ukit/index/query-index.mjs +14 -3
- package/template_project/.claude/ukit/index/route-task.mjs +4 -1
- package/template_project/.claude/ukit/runtime/memory-check.mjs +241 -0
- package/template_project/.claude/ukit/runtime/memory-recall.mjs +120 -7
- package/template_project/.claude/ukit/runtime/memory-validity.mjs +28 -1
- package/template_project/.claude/ukit/runtime/self-improve-trigger.mjs +212 -5
- package/template_project/.omp/hooks/pre/ukit-bridge.js +2 -1
- package/template_project/ukit/storage/config.json +4 -2
- package/src/core/agentRuntime/completionGate.js +0 -179
- package/src/core/agentRuntime/context.js +0 -571
- package/src/core/agentRuntime/qualityComparison.js +0 -112
- package/src/core/agentRuntime/resourcePolicy.js +0 -78
- package/src/core/agentRuntime/runtimeSupport.js +0 -255
- package/src/core/codeintel/manifest.js +0 -176
- package/src/core/experiments/deliberation.js +0 -327
- package/src/core/experiments/dynamicWorkflow.js +0 -507
- package/src/core/handoffDocValidator.js +0 -154
- package/src/core/memory/deltaOverlays.js +0 -493
- package/src/core/memory/learningCandidates.js +0 -347
- package/src/core/observability/emit/sessionBoot.js +0 -407
- package/src/core/observability/evaluation/replay.js +0 -149
- package/src/core/observability/evaluation/scorecard.js +0 -465
- package/src/core/observability/schema/compatibility.js +0 -180
- package/src/core/observability/support/renderer.js +0 -130
- package/src/core/reviewPanelAggregate.js +0 -204
- package/src/core/taskBudgetValidator.js +0 -251
- package/src/core/taskProgressGuard.js +0 -227
- package/src/decision/reviewVerdict.js +0 -339
- package/src/decision/runtimeFilter.js +0 -150
- package/src/decision/runtimeScheduler.js +0 -239
- package/src/index/contextPack.js +0 -285
- package/src/index/impactContext.js +0 -360
- package/src/index/reviewPolicy.js +0 -368
- 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
|
-
}
|