@ngockhoale/ukit 3.5.2 → 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 (75) hide show
  1. package/CHANGELOG.md +38 -90
  2. package/README.md +1 -0
  3. package/manifests/documentation.yaml +12 -1
  4. package/manifests/platform.full.yaml +12 -0
  5. package/package.json +34 -1
  6. package/src/cli/commands/doctor.js +55 -2
  7. package/src/cli/commands/indexTools.js +10 -4
  8. package/src/cli/commands/memory.js +107 -8
  9. package/src/core/memory/episodes.js +106 -7
  10. package/src/core/memory/memoryCheck.js +241 -0
  11. package/src/core/memory/memoryCheckRun.js +27 -0
  12. package/src/core/memory/memoryHit.js +2 -0
  13. package/src/core/memory/mutateMemory.js +46 -1
  14. package/src/core/memory/observations.js +192 -0
  15. package/src/core/memory/projectIdentity.js +9 -2
  16. package/src/core/memory/recallEngine.js +204 -9
  17. package/src/core/memory/records.js +23 -0
  18. package/src/core/memory/registryPrune.js +230 -0
  19. package/src/core/memory/retrieval.js +12 -3
  20. package/src/core/memory/writeGate.js +137 -0
  21. package/src/core/runtimeConfig.js +12 -2
  22. package/src/index/buildIndex.js +26 -0
  23. package/src/index/paths.js +3 -1
  24. package/src/index/queryIndex.js +372 -26
  25. package/src/index/resolveContext.js +1 -1
  26. package/template_project/.claude/hooks/edit-hint.mjs +64 -17
  27. package/template_project/.claude/hooks/session-episode-start.mjs +35 -0
  28. package/template_project/.claude/hooks/session-episode.sh +9 -4
  29. package/template_project/.claude/settings.json +2 -2
  30. package/template_project/.claude/ukit/index/edit-graph.mjs +141 -11
  31. package/template_project/.claude/ukit/index/lib/index-core.mjs +400 -27
  32. package/template_project/.claude/ukit/index/query-index.mjs +14 -3
  33. package/template_project/.claude/ukit/index/resolve-context.mjs +1 -1
  34. package/template_project/.claude/ukit/index/route-task.mjs +8 -2
  35. package/template_project/.claude/ukit/runtime/memory-check.mjs +241 -0
  36. package/template_project/.claude/ukit/runtime/memory-lanes.mjs +44 -22
  37. package/template_project/.claude/ukit/runtime/memory-recall.mjs +204 -9
  38. package/template_project/.claude/ukit/runtime/memory-validity.mjs +259 -0
  39. package/template_project/.claude/ukit/runtime/reinject-context.mjs +4 -2
  40. package/template_project/.claude/ukit/runtime/self-improve-trigger.mjs +212 -5
  41. package/template_project/.omp/hooks/pre/ukit-bridge.js +2 -1
  42. package/template_project/ukit/storage/config.json +4 -2
  43. package/src/core/agentRuntime/completionGate.js +0 -179
  44. package/src/core/agentRuntime/context.js +0 -571
  45. package/src/core/agentRuntime/qualityComparison.js +0 -112
  46. package/src/core/agentRuntime/resourcePolicy.js +0 -78
  47. package/src/core/agentRuntime/runtimeSupport.js +0 -255
  48. package/src/core/codeintel/manifest.js +0 -176
  49. package/src/core/experiments/deliberation.js +0 -327
  50. package/src/core/experiments/dynamicWorkflow.js +0 -507
  51. package/src/core/handoffDocValidator.js +0 -154
  52. package/src/core/memory/deltaOverlays.js +0 -493
  53. package/src/core/memory/learningCandidates.js +0 -347
  54. package/src/core/observability/emit/sessionBoot.js +0 -407
  55. package/src/core/observability/evaluation/experimentPlan.js +0 -95
  56. package/src/core/observability/evaluation/perturbation.js +0 -273
  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/diagnostics/classifyHang.js +0 -246
  68. package/src/diagnostics/ompStallSnapshot.js +0 -199
  69. package/src/index/contextPack.js +0 -285
  70. package/src/index/impactContext.js +0 -360
  71. package/src/index/reviewPolicy.js +0 -368
  72. package/src/index/sensitivePath.js +0 -21
  73. package/src/render/instructionRenderer.js +0 -290
  74. package/src/skill/auditSkill.js +0 -140
  75. package/template_project/instructions/overlays/repo.md +0 -9
@@ -0,0 +1,137 @@
1
+ // writeGate.js — deterministic admission gate for record writes (3.5.4).
2
+ // No LLM. Called by mutateMemory on `add` / `update` after the schema build and
3
+ // the secret guard; returns a typed rejection with a one-line reason.
4
+ //
5
+ // code reason prefix rule
6
+ // too-large too-large: record text over RECORD_TEXT_MAX chars
7
+ // no-evidence no-evidence: no source evidence (see hasSourceEvidence)
8
+ // near-duplicate near-duplicate: lexical near-duplicate of a live record
9
+ //
10
+ // (schema -> `invalid-record`, secret -> `secret-detected` stay where they were
11
+ // in mutateMemory; the codes above are the gate's own.) Stored items are never
12
+ // rejected retroactively: the gate only looks at the incoming write.
13
+ //
14
+ // Source evidence (project lane), any one of:
15
+ // - evidence[] entry kind 'file' whose locator is an existing path inside the project
16
+ // - evidence[] entry kind 'ledger' whose locator is an existing episode id (store or archive)
17
+ // - evidence[] entry kind 'command' whose locator names a commit: `commit:<sha>` or a bare 7-40 hex sha
18
+ // - an observation with meta.evidence.episodes that validateObservationEvidence accepts
19
+ // kinds 'manual' and 'import' are claims, not evidence, and do not count.
20
+ // Machine-generated writers (GENERATED_CREATORS) skip evidence and duplicate
21
+ // checks (their text is templated from a ledger); size still applies.
22
+ import fsp from 'node:fs/promises';
23
+ import path from 'node:path';
24
+
25
+ import { GENERATED_CREATORS, RECORD_TEXT_MAX, findNearDuplicate } from './memoryCheck.js';
26
+ import { tokenize } from './recallEngine.js';
27
+ import { guardWritePayload } from './writeGuard.js';
28
+ import { loadEpisodeIdsFor, validateObservationEvidence } from './observations.js';
29
+
30
+ const COMMIT_RE = /^(?:commit:)?[0-9a-f]{7,40}$/i;
31
+
32
+ async function fileExists(projectRoot, locator) {
33
+ if (typeof projectRoot !== 'string' || typeof locator !== 'string' || !locator) return false;
34
+ const root = path.resolve(projectRoot);
35
+ const abs = path.resolve(root, locator);
36
+ if (abs !== root && !abs.startsWith(root + path.sep)) return false;
37
+ try {
38
+ await fsp.stat(abs);
39
+ return true;
40
+ } catch {
41
+ return false;
42
+ }
43
+ }
44
+
45
+ /** hasSourceEvidence(record, {projectRoot}) -> Promise<{ok, detail?}> */
46
+ export async function hasSourceEvidence(record, { projectRoot } = {}) {
47
+ if (record?.type === 'observation') {
48
+ const res = await validateObservationEvidence(record, { projectRoot });
49
+ return res.ok ? { ok: true } : { ok: false, detail: res.reason };
50
+ }
51
+ let episodeIds = null;
52
+ for (const ev of Array.isArray(record?.evidence) ? record.evidence : []) {
53
+ if (!ev || typeof ev.locator !== 'string') continue;
54
+ if (ev.kind === 'file' && await fileExists(projectRoot, ev.locator)) return { ok: true };
55
+ if (ev.kind === 'command' && COMMIT_RE.test(ev.locator)) return { ok: true };
56
+ if (ev.kind === 'ledger') {
57
+ episodeIds ??= await loadEpisodeIdsFor(projectRoot).catch(() => new Set());
58
+ if (episodeIds.has(ev.locator)) return { ok: true };
59
+ }
60
+ }
61
+ return { ok: false, detail: 'add evidence: a file path that exists, a commit sha, or an episode id' };
62
+ }
63
+
64
+ /**
65
+ * checkProposalText({ text, existing, config, projectId }) -> { ok: true } | { ok, code, reason, labels? }
66
+ * Text-only gate for `ukit memory propose` (a human approves candidates, so no
67
+ * evidence rule): size cap, secret scan, near-duplicate of `existing` ([{id,text}],
68
+ * pending + approved candidates). Honours memory.writeGate 'off'.
69
+ */
70
+ export function checkProposalText({ text, existing = [], config = null, projectId = null } = {}) {
71
+ const mode = config?.memory?.writeGate;
72
+ if (mode === false || mode === 'off') return { ok: true };
73
+ const body = String(text ?? '');
74
+ if (body.length > RECORD_TEXT_MAX) {
75
+ return {
76
+ ok: false, code: 'too-large',
77
+ reason: `too-large: text is ${body.length} chars (max ${RECORD_TEXT_MAX}); move the detail to docs/memory/ and keep one line here`,
78
+ };
79
+ }
80
+ const guarded = guardWritePayload({ text: body }, { config, projectId });
81
+ if (guarded?.ok === false) {
82
+ return { ok: false, code: 'secret-detected', reason: guarded.reason ?? 'secret-detected', labels: guarded.labels };
83
+ }
84
+ const dup = findNearDuplicate(body, existing, tokenize);
85
+ if (dup) {
86
+ return {
87
+ ok: false, code: 'near-duplicate',
88
+ reason: `near-duplicate: ${Math.round(dup.similarity * 100)}% lexical overlap with ${dup.id}; approve or reject that candidate instead`,
89
+ };
90
+ }
91
+ return { ok: true };
92
+ }
93
+
94
+ const isLive = (r) => r && r.status !== 'archived' && !r.superseded_by;
95
+
96
+ /**
97
+ * checkRecordWrite({ record, records, projectRoot, op, replaces }) ->
98
+ * { ok: true } | { ok: false, code, reason }
99
+ * record: the built (validated) record or, for update, the would-be merged record.
100
+ * records: current store contents. replaces: ids this write supersedes or updates
101
+ * (excluded from the duplicate comparison). op 'update' only enforces the rules
102
+ * the patch can break (size, duplicate of changed text, evidence it supplies).
103
+ */
104
+ export async function checkRecordWrite({
105
+ record, records = [], projectRoot = null, op = 'add', replaces = [], patch = null, strict = false,
106
+ } = {}) {
107
+ const text = String(record?.text ?? '');
108
+ const touchesText = op === 'add' || (patch && 'text' in patch);
109
+ if (touchesText && text.length > RECORD_TEXT_MAX) {
110
+ return {
111
+ ok: false, code: 'too-large',
112
+ reason: `too-large: text is ${text.length} chars (max ${RECORD_TEXT_MAX}); move the detail to docs/memory/ and keep one line here`,
113
+ };
114
+ }
115
+ // Evidence and near-duplicate rules are for agent-authored notes (strict).
116
+ // Legacy callers that write bare records (tests, tools, restore flows) pass
117
+ // the size cap only; generated writers are exempt even when strict.
118
+ if (!strict || GENERATED_CREATORS.has(record?.created_by)) return { ok: true };
119
+
120
+ const touchesEvidence = op === 'add' || (patch && ('evidence' in patch || 'meta' in patch || patch.type === 'observation'));
121
+ if (touchesEvidence && projectRoot) {
122
+ const res = await hasSourceEvidence(record, { projectRoot });
123
+ if (!res.ok) return { ok: false, code: 'no-evidence', reason: `no-evidence: ${res.detail}` };
124
+ }
125
+
126
+ if (touchesText) {
127
+ const skip = new Set([record.id, ...replaces, ...(Array.isArray(record.supersedes) ? record.supersedes : [])]);
128
+ const dup = findNearDuplicate(text, records.filter((r) => isLive(r) && !skip.has(r.id)), tokenize);
129
+ if (dup) {
130
+ return {
131
+ ok: false, code: 'near-duplicate',
132
+ reason: `near-duplicate: ${Math.round(dup.similarity * 100)}% lexical overlap with ${dup.id}; update it, or pass supersedes: ["${dup.id}"] to replace it`,
133
+ };
134
+ }
135
+ }
136
+ return { ok: true };
137
+ }
@@ -531,8 +531,15 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
531
531
  maxArchivedSessions: 50,
532
532
  maxPatternCandidates: 50,
533
533
  redactSecrets: true,
534
- sources: ['docs/MEMORY.md'],
535
- editHints: { enabled: true, mirrors: [], ignoreMirrors: [] },
534
+ // Capped core + every docs/memory/*.md detail file (3.5.4; one directory
535
+ // level, expanded by recallEngine.expandMemorySources). A missing directory
536
+ // contributes nothing, so a project with only docs/MEMORY.md behaves as before.
537
+ sources: ['docs/MEMORY.md', 'docs/memory/*.md'],
538
+ // Record write gate (3.5.4): 'strict' (default) = size cap, secrets, source
539
+ // evidence and near-duplicate checks on every non-generated record write;
540
+ // 'off' = no gate. scope user needs no file evidence. See writeGate.js.
541
+ writeGate: 'strict',
542
+ editHints: { enabled: true, mirrors: [], ignoreMirrors: [], coChange: false },
536
543
  },
537
544
  validation: {
538
545
  enabled: true,
@@ -1195,6 +1202,9 @@ export function validateRuntimeConfig(config) {
1195
1202
  || config.memory.sources.some((entry) => typeof entry !== 'string'))) {
1196
1203
  errors.push('memory.sources must be an array of relative .md paths.');
1197
1204
  }
1205
+ if (config.memory.writeGate !== undefined && !['strict', 'off', false].includes(config.memory.writeGate)) {
1206
+ errors.push('memory.writeGate must be "strict" or "off".');
1207
+ }
1198
1208
  }
1199
1209
 
1200
1210
  if (!isPlainObject(config.validation)) {
@@ -1682,6 +1682,8 @@ function computeSignature(content, lineStartIndex) {
1682
1682
  return `${collapsed.slice(0, 199)}…`;
1683
1683
  }
1684
1684
 
1685
+ const CLASS_METHOD_SKIP = new Set(['if', 'for', 'while', 'switch', 'catch', 'function', 'return', 'with', 'constructor', 'super']);
1686
+
1685
1687
  export function extractSymbols(filePath, content) {
1686
1688
  const symbols = [];
1687
1689
  const lineStarts = computeLineStarts(content);
@@ -1750,6 +1752,30 @@ export function extractSymbols(filePath, content) {
1750
1752
  addMatches(/defineComponent\(\s*\{[\s\S]*?name\s*:\s*['"]([^'"]+)['"]/g, 'component-name');
1751
1753
  addMatches(/export\s+default\s*\{[\s\S]*?name\s*:\s*['"]([^'"]+)['"]/g, 'component-name');
1752
1754
 
1755
+ // Unexported declarations (3.5.4). Line-anchored, so `export function` / `export class`
1756
+ // (indexed above as exported) never double-count. Local types rank below exported ones.
1757
+ addMatches(/^[ \t]*(?:async\s+)?function\s*\*?\s*([A-Za-z_$][A-Za-z0-9_$]*)\s*[(<]/gm, 'local-function');
1758
+ addMatches(/^[ \t]*(?:const|let|var)\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*=\s*(?:async\s+)?function\b/gm, 'callable');
1759
+ addMatches(/^[ \t]*(?:abstract\s+)?class\s+([A-Za-z_$][A-Za-z0-9_$]*)/gm, 'local-class');
1760
+ if (/\.(?:ts|tsx|mts|cts|vue)$/.test(filePath)) {
1761
+ addMatches(/^[ \t]*(?:export\s+)?(?:declare\s+)?(?:const\s+)?(?:interface|enum)\s+([A-Za-z_$][A-Za-z0-9_$]*)/gm, 'type');
1762
+ addMatches(/^[ \t]*(?:export\s+)?(?:declare\s+)?type\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*(?:<[^=\n]*>)?\s*=/gm, 'type');
1763
+ }
1764
+ // Class methods: indented `name(args) {` lines inside a balanced class body.
1765
+ for (const classMatch of content.matchAll(/(?:^|[^\w$.])class\s+[A-Za-z_$][A-Za-z0-9_$]*(?:\s+extends\s+[\w$.]+(?:\([^)]*\))?)?\s*\{/g)) {
1766
+ const bodyStart = classMatch.index + classMatch[0].length;
1767
+ const classBody = sliceBalancedBlock(content, bodyStart);
1768
+ if (!classBody) {
1769
+ continue;
1770
+ }
1771
+ for (const methodMatch of classBody.matchAll(/^[ \t]+(?:(?:static|async|get|set)\s+)*\*?\s*(#?[A-Za-z_$][A-Za-z0-9_$]*)\s*\([^()]*\)\s*\{/gm)) {
1772
+ if (CLASS_METHOD_SKIP.has(methodMatch[1])) {
1773
+ continue;
1774
+ }
1775
+ addSymbol(methodMatch[1], 'method', bodyStart + methodMatch.index + methodMatch[0].indexOf(methodMatch[1]));
1776
+ }
1777
+ }
1778
+
1753
1779
  // Global-registered frontend functions: reachable from anywhere without an
1754
1780
  // import edge, so impact analysis must treat them as verified dependencies.
1755
1781
  addMatches(/\b(?:window|globalThis|global)\s*\.\s*([A-Za-z_$][A-Za-z0-9_$]*)\s*=/g, 'global');
@@ -19,7 +19,9 @@ export const INDEX_ARTIFACTS = {
19
19
  // SQL 'column' rows with parent/schema, and calls.json gains per-object SQL
20
20
  // reference records — a v8 cached artifact must not be reused for unchanged
21
21
  // files or the new extractions silently vanish.
22
- export const INDEX_SCHEMA_VERSION = 9;
22
+ // v10: symbols.json gains unexported function/class ('local-function', 'local-class'),
23
+ // function-expression consts, class 'method' rows and TS interface/enum/type ('type') rows.
24
+ export const INDEX_SCHEMA_VERSION = 10;
23
25
 
24
26
  export function getIndexDir(rootDir) {
25
27
  return path.join(rootDir, '.cache', 'index');