@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
@@ -1,327 +0,0 @@
1
- /**
2
- * deliberation.js (TASK-011 / M06.1)
3
- *
4
- * Read-only deliberation experiments — Arena (2–3 independent candidates +
5
- * evidence-rubric judge), Swarm (≥3 independent read-only lanes), smart judge —
6
- * behind `experiments.deliberation.enabled` (default false). Not wired into
7
- * route-task; evaluated by fixtures (SPEC §5 FR-021, FR-023; §14 "M06 wiring").
8
- *
9
- * Disabled posture: activation predicates return `{activate:false}` and
10
- * `runArena` returns `{status:'disabled'}` BEFORE any judge call — zero calls,
11
- * zero prompt content.
12
- *
13
- * Judge contract: `judge({findings, rubric}) → verdict` where findings are
14
- * frozen candidate descriptors `{candidateId, criterionScores?, violations?,
15
- * evidence?}` and verdict is `{selected, rejected, uncertainty,
16
- * requiredValidation}`. `selected`/`rejected[]` entries MUST carry `citations`
17
- * drawn from candidate evidence — a majority-only verdict is rejected. Hard
18
- * rubric constraints (`rubric.hardConstraints`) are floors: a verdict that
19
- * selects a violator or declares `waivedConstraints` is rejected. `smartJudge`
20
- * is the built-in deterministic judge implementing the same contract.
21
- */
22
-
23
- const MIN_ARENA_CANDIDATES = 2;
24
- const MAX_ARENA_CANDIDATES = 3;
25
- const MIN_SWARM_LANES = 3;
26
-
27
- function deliberationEnabled(config) {
28
- return config?.experiments?.deliberation?.enabled === true;
29
- }
30
-
31
- function isPlainObject(value) {
32
- return value !== null && typeof value === 'object' && !Array.isArray(value);
33
- }
34
-
35
- function candidateIdOf(entry) {
36
- return entry?.candidateId ?? entry?.id ?? null;
37
- }
38
-
39
- function citationsOf(entry) {
40
- return Array.isArray(entry?.citations) ? entry.citations : [];
41
- }
42
-
43
- /**
44
- * Arena activation predicate. Fires only when the route carries ≥2 materially
45
- * different viable alternatives AND budget allows; suppressed on established
46
- * precedent, reversible changes, or cosmetic-only alternatives.
47
- *
48
- * @param {object} route — route summary fields: `alternatives[]`
49
- * ({id, viable, materiallyDifferent}), `budget.callsRemaining`,
50
- * `precedent`, `reversible`.
51
- * @param {object} [config] — runtime config; absent/disabled → suppress.
52
- * @returns {{activate: boolean, reasons: string[]}}
53
- */
54
- export function evaluateArenaActivation(route = null, config = null) {
55
- if (!deliberationEnabled(config)) {
56
- return { activate: false, reasons: ['experiment-disabled'] };
57
- }
58
- const reasons = [];
59
- if (route?.precedent) {
60
- reasons.push('established-precedent');
61
- }
62
- if (route?.reversible === true) {
63
- reasons.push('reversible-change');
64
- }
65
- const alternatives = Array.isArray(route?.alternatives) ? route.alternatives : [];
66
- const material = alternatives.filter(
67
- (alt) => alt?.viable === true && alt?.materiallyDifferent === true,
68
- );
69
- if (material.length < MIN_ARENA_CANDIDATES) {
70
- reasons.push('insufficient-material-alternatives');
71
- }
72
- const callsRemaining = route?.budget?.callsRemaining;
73
- const budgetAllows = !(typeof callsRemaining === 'number' && callsRemaining < 1);
74
- if (!budgetAllows) {
75
- reasons.push('budget-exhausted');
76
- }
77
- if (reasons.length > 0) {
78
- return { activate: false, reasons };
79
- }
80
- return { activate: true, reasons: ['material-alternatives', 'budget-allows'] };
81
- }
82
-
83
- /**
84
- * Swarm activation predicate. Fires only on ≥3 independent read-only lanes;
85
- * any mutating or dependent lane suppresses the whole swarm.
86
- *
87
- * @param {object} route — route summary field `lanes[]`
88
- * ({id, readOnly, independent}).
89
- * @param {object} [config]
90
- * @returns {{activate: boolean, reasons: string[], lanes?: string[]}}
91
- */
92
- export function evaluateSwarmActivation(route = null, config = null) {
93
- if (!deliberationEnabled(config)) {
94
- return { activate: false, reasons: ['experiment-disabled'], lanes: [] };
95
- }
96
- const lanes = Array.isArray(route?.lanes) ? route.lanes : [];
97
- const reasons = [];
98
- if (lanes.some((lane) => lane?.readOnly !== true)) {
99
- reasons.push('lane-not-read-only');
100
- }
101
- const independent = lanes.filter(
102
- (lane) => lane?.readOnly === true && lane?.independent === true,
103
- );
104
- if (independent.length < MIN_SWARM_LANES) {
105
- reasons.push('insufficient-independent-lanes');
106
- }
107
- if (reasons.length > 0) {
108
- return { activate: false, reasons, lanes: [] };
109
- }
110
- return {
111
- activate: true,
112
- reasons: ['independent-read-only-lanes'],
113
- lanes: independent.map((lane) => lane.id),
114
- };
115
- }
116
-
117
- /**
118
- * Deterministic evidence-rubric judge. Scores each finding against weighted
119
- * rubric criteria; findings violating a hard constraint are ineligible for
120
- * selection regardless of score. Hard constraints are never waivable.
121
- *
122
- * @param {{findings: object[], rubric: {criteria?: {id, weight?}[],
123
- * hardConstraints?: string[]}}} input
124
- * @returns {{selected: object|null, rejected: object[], uncertainty: string[],
125
- * requiredValidation: string[]}}
126
- */
127
- export function smartJudge({ findings = [], rubric = {} } = {}) {
128
- const criteria = Array.isArray(rubric?.criteria) ? rubric.criteria : [];
129
- const hardConstraints = new Set(
130
- Array.isArray(rubric?.hardConstraints) ? rubric.hardConstraints : [],
131
- );
132
- const scored = (Array.isArray(findings) ? findings : []).map((finding) => {
133
- const scores = isPlainObject(finding?.criterionScores) ? finding.criterionScores : {};
134
- const score = criteria.reduce(
135
- (sum, criterion) => sum + Number(scores[criterion.id] ?? 0) * Number(criterion.weight ?? 1),
136
- 0,
137
- );
138
- const violations = (Array.isArray(finding?.violations) ? finding.violations : [])
139
- .filter((id) => hardConstraints.has(id));
140
- return { finding, score, violations };
141
- });
142
-
143
- const eligible = scored.filter((entry) => entry.violations.length === 0);
144
- const rejected = [];
145
- for (const entry of scored) {
146
- if (entry.violations.length > 0) {
147
- rejected.push({
148
- candidateId: candidateIdOf(entry.finding),
149
- reason: `hard-constraint:${entry.violations.join(',')}`,
150
- citations: Array.isArray(entry.finding?.evidence) ? entry.finding.evidence : [],
151
- });
152
- }
153
- }
154
-
155
- eligible.sort((a, b) => b.score - a.score);
156
- const top = eligible[0] ?? null;
157
- const runnerUp = eligible[1] ?? null;
158
- const uncertainty = [];
159
- const requiredValidation = [];
160
-
161
- let selected = null;
162
- if (top) {
163
- const citations = Array.isArray(top.finding?.evidence) ? top.finding.evidence : [];
164
- if (citations.length === 0) {
165
- uncertainty.push(`no-evidence:${candidateIdOf(top.finding)}`);
166
- requiredValidation.push(`collect-evidence:${candidateIdOf(top.finding)}`);
167
- } else {
168
- selected = {
169
- candidateId: candidateIdOf(top.finding),
170
- score: top.score,
171
- citations,
172
- };
173
- }
174
- }
175
- if (top && runnerUp && top.score - runnerUp.score <= 1) {
176
- uncertainty.push(`close-call:${candidateIdOf(top.finding)}~${candidateIdOf(runnerUp.finding)}`);
177
- requiredValidation.push(`validate-tiebreak:${candidateIdOf(top.finding)}`);
178
- }
179
- for (const entry of eligible) {
180
- if (entry === top) continue;
181
- rejected.push({
182
- candidateId: candidateIdOf(entry.finding),
183
- reason: 'lower-score',
184
- citations: Array.isArray(entry.finding?.evidence) ? entry.finding.evidence : [],
185
- });
186
- }
187
- if (!selected && !top) {
188
- uncertainty.push('no-eligible-candidate');
189
- requiredValidation.push('re-scope-candidates');
190
- }
191
-
192
- return { selected, rejected, uncertainty, requiredValidation };
193
- }
194
-
195
- /**
196
- * Post-checks a judge verdict against the arena floors. Returns the list of
197
- * rejection reasons (empty = verdict stands).
198
- */
199
- function verdictViolations(verdict, candidates, rubric) {
200
- const reasons = [];
201
- const hardConstraints = new Set(
202
- Array.isArray(rubric?.hardConstraints) ? rubric.hardConstraints : [],
203
- );
204
- const waived = Array.isArray(verdict?.waivedConstraints) ? verdict.waivedConstraints : [];
205
- if (waived.some((id) => hardConstraints.has(id)) || waived.length > 0) {
206
- reasons.push('hard-constraint-waived');
207
- }
208
- const selectedId = candidateIdOf(verdict?.selected);
209
- if (selectedId !== null) {
210
- const selectedFinding = candidates.find((c) => candidateIdOf(c) === selectedId);
211
- const violations = Array.isArray(selectedFinding?.violations) ? selectedFinding.violations : [];
212
- if (violations.some((id) => hardConstraints.has(id))) {
213
- reasons.push('hard-constraint-violation-selected');
214
- }
215
- }
216
- const entries = [verdict?.selected, ...(Array.isArray(verdict?.rejected) ? verdict.rejected : [])]
217
- .filter(Boolean);
218
- if (entries.some((entry) => citationsOf(entry).length === 0)) {
219
- reasons.push('majority-only-verdict');
220
- }
221
- return reasons;
222
- }
223
-
224
- // Deep-frozen structural copy: plain objects and arrays are cloned and frozen
225
- // recursively so a judge cannot mutate nested state (violations, evidence)
226
- // to defeat the verdict post-check. Non-plain values pass through frozen-safe.
227
- function deepFreezeCopy(value) {
228
- if (Array.isArray(value)) {
229
- return Object.freeze(value.map(deepFreezeCopy));
230
- }
231
- if (isPlainObject(value)) {
232
- const copy = {};
233
- for (const [key, item] of Object.entries(value)) {
234
- copy[key] = deepFreezeCopy(item);
235
- }
236
- return Object.freeze(copy);
237
- }
238
- return value;
239
- }
240
-
241
- /**
242
- * Run a read-only arena over 2–3 frozen candidates with an evidence-rubric
243
- * judge. The judge receives frozen copies — mutation attempts throw. The
244
- * verdict is post-checked: hard-constraint waivers/violations and
245
- * majority-only (citation-free) verdicts are rejected.
246
- *
247
- * Migration contract (decision plane): an injected `judge` implementation
248
- * that performs bounded verdict work MUST route it through the decision
249
- * plane (`createDecisionClient` + `src/decision/registry.js` keys) — never a
250
- * general LLM call. The default `smartJudge` is deterministic: pure scoring,
251
- * hard-constraint filtering, and a stable sort — no I/O, no model calls.
252
- *
253
- * @param {{candidates: object[], rubric: object, judge: Function,
254
- * config?: object}} input
255
- * @returns {{status: 'ok'|'disabled'|'rejected', selected?: object|null,
256
- * rejected?: object[], uncertainty?: string[], requiredValidation?: string[],
257
- * reasons?: string[]}}
258
- */
259
- export function runArena({ candidates = [], rubric = {}, judge = smartJudge, config = null } = {}) {
260
- if (!deliberationEnabled(config)) {
261
- return { status: 'disabled', selected: null, rejected: [], reasons: ['experiment-disabled'] };
262
- }
263
- const list = Array.isArray(candidates) ? candidates : [];
264
- if (list.length < MIN_ARENA_CANDIDATES || list.length > MAX_ARENA_CANDIDATES) {
265
- throw new TypeError(
266
- `arena requires ${MIN_ARENA_CANDIDATES}–${MAX_ARENA_CANDIDATES} candidates.`,
267
- );
268
- }
269
- if (typeof judge !== 'function') {
270
- throw new TypeError('arena judge must be a function.');
271
- }
272
- // Read-only: the judge sees deep-frozen copies — mutation of any nested field
273
- // (e.g. hiding a hard-constraint violation) throws in strict mode. A shallow
274
- // freeze would leave nested arrays/objects mutable and defeat the post-check.
275
- const findings = list.map((candidate) => deepFreezeCopy(candidate));
276
- const verdict = judge({ findings, rubric }) ?? {};
277
- const reasons = verdictViolations(verdict, findings, rubric);
278
- if (reasons.length > 0) {
279
- return { status: 'rejected', selected: null, rejected: [], reasons };
280
- }
281
- return {
282
- status: 'ok',
283
- selected: verdict.selected ?? null,
284
- rejected: Array.isArray(verdict.rejected) ? verdict.rejected : [],
285
- uncertainty: Array.isArray(verdict.uncertainty) ? verdict.uncertainty : [],
286
- requiredValidation: Array.isArray(verdict.requiredValidation) ? verdict.requiredValidation : [],
287
- };
288
- }
289
-
290
- const SCORECARD_VERDICTS = new Set(['net-gain', 'neutral', 'negative']);
291
-
292
- /**
293
- * Emit a normalized experiment scorecard (FR-023). Promotion requires
294
- * `verdict:'net-gain'` + maintainer review; `neutral|negative` keeps the
295
- * experiment disabled.
296
- *
297
- * @param {{experimentId: string, taskClass: string, baselineRef: string,
298
- * deltas: {quality,rework,latency,calls}, verdict: string}} record
299
- * @returns {object} scorecard with `promotionEligible` + `disposition`.
300
- */
301
- export function emitExperimentScorecard(record = {}) {
302
- if (!isPlainObject(record) || typeof record.experimentId !== 'string' || !record.experimentId) {
303
- throw new TypeError('scorecard record.experimentId must be a non-empty string.');
304
- }
305
- if (!SCORECARD_VERDICTS.has(record.verdict)) {
306
- throw new TypeError(`scorecard verdict must be one of ${[...SCORECARD_VERDICTS].join('|')}.`);
307
- }
308
- const deltas = isPlainObject(record.deltas) ? record.deltas : {};
309
- const scorecard = {
310
- experimentId: record.experimentId,
311
- taskClass: record.taskClass ?? null,
312
- baselineRef: record.baselineRef ?? null,
313
- deltas: {
314
- quality: Number(deltas.quality ?? 0),
315
- rework: Number(deltas.rework ?? 0),
316
- latency: Number(deltas.latency ?? 0),
317
- calls: Number(deltas.calls ?? 0),
318
- },
319
- verdict: record.verdict,
320
- };
321
- const promotionEligible = record.verdict === 'net-gain';
322
- return {
323
- ...scorecard,
324
- promotionEligible,
325
- disposition: promotionEligible ? 'maintainer-review' : 'stay-disabled',
326
- };
327
- }