@ngockhoale/ukit 3.5.5 → 3.5.7

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 +25 -0
  2. package/manifests/engineConformance.yaml +0 -13
  3. package/manifests/platform.full.yaml +25 -0
  4. package/package.json +1 -8
  5. package/src/cli/commands/indexTools.js +1 -0
  6. package/src/cli/commands/memory.js +33 -4
  7. package/src/core/applyPlan.js +37 -72
  8. package/src/core/diffPlan.js +39 -9
  9. package/src/core/managedTemplateMerge.js +231 -0
  10. package/src/core/memory/memoryFlags.js +5 -6
  11. package/src/core/memory/policy.js +5 -0
  12. package/src/core/memory/store.js +17 -0
  13. package/src/core/metadata.js +12 -8
  14. package/src/core/runInstallPipeline.js +16 -10
  15. package/src/core/runtimeConfig.js +14 -83
  16. package/src/core/uninstall.js +8 -1
  17. package/src/decision/registry.js +17 -17
  18. package/src/decision/runtimeDecide.js +5 -5
  19. package/src/index/playbookRegistry.js +6 -1
  20. package/src/index/queryIndex.js +41 -4
  21. package/src/index/routeResolver.js +2 -2
  22. package/src/index/semanticLane.js +277 -0
  23. package/src/learning/lessonClass.js +110 -0
  24. package/src/learning/patternProposals.js +111 -7
  25. package/src/learning/reeditMiner.js +104 -0
  26. package/src/learning/selfImprove.js +9 -1
  27. package/template_project/.claude/hooks/skill-router.sh +273 -5
  28. package/template_project/.claude/skills/canvas-design/SKILL.md +2 -2
  29. package/template_project/.claude/skills/canvas-design/canvas-fonts/{InstrumentSans-OFL.txt → InstrumentSerif-OFL.txt} +3 -3
  30. package/template_project/.claude/skills/canvas-design/scripts/fetch-fonts.mjs +148 -0
  31. package/template_project/.claude/ukit/index/embed-index.mjs +26 -0
  32. package/template_project/.claude/ukit/index/lib/index-core.mjs +43 -4
  33. package/template_project/.claude/ukit/index/lib/semantic-lane.mjs +277 -0
  34. package/template_project/.claude/ukit/index/playbook-registry.mjs +6 -1
  35. package/template_project/.claude/ukit/index/publication-intent.mjs +159 -1
  36. package/template_project/.claude/ukit/index/query-index.mjs +9 -1
  37. package/template_project/.claude/ukit/index/route-resolver.mjs +2 -2
  38. package/template_project/.claude/ukit/index/route-task.mjs +14 -3
  39. package/template_project/.claude/ukit/runtime/memory-policy.mjs +5 -0
  40. package/template_project/.claude/ukit/runtime/stop-coordinator.mjs +12 -1
  41. package/template_project/ukit/storage/config.json +0 -32
  42. package/template_project/.claude/skills/canvas-design/canvas-fonts/BricolageGrotesque-Bold.ttf +0 -0
  43. package/template_project/.claude/skills/canvas-design/canvas-fonts/BricolageGrotesque-OFL.txt +0 -93
  44. package/template_project/.claude/skills/canvas-design/canvas-fonts/BricolageGrotesque-Regular.ttf +0 -0
  45. package/template_project/.claude/skills/canvas-design/canvas-fonts/InstrumentSans-Bold.ttf +0 -0
  46. package/template_project/.claude/skills/canvas-design/canvas-fonts/InstrumentSans-BoldItalic.ttf +0 -0
  47. package/template_project/.claude/skills/canvas-design/canvas-fonts/InstrumentSans-Italic.ttf +0 -0
  48. package/template_project/.claude/skills/canvas-design/canvas-fonts/InstrumentSans-Regular.ttf +0 -0
  49. package/template_project/.claude/skills/canvas-design/canvas-fonts/InstrumentSerif-Italic.ttf +0 -0
  50. package/template_project/.claude/skills/canvas-design/canvas-fonts/JetBrainsMono-Bold.ttf +0 -0
  51. package/template_project/.claude/skills/canvas-design/canvas-fonts/Lora-Bold.ttf +0 -0
  52. package/template_project/.claude/skills/canvas-design/canvas-fonts/Lora-BoldItalic.ttf +0 -0
  53. package/template_project/.claude/skills/canvas-design/canvas-fonts/Lora-Italic.ttf +0 -0
  54. package/template_project/.claude/skills/canvas-design/canvas-fonts/Lora-OFL.txt +0 -93
  55. package/template_project/.claude/skills/canvas-design/canvas-fonts/Lora-Regular.ttf +0 -0
  56. package/template_project/.claude/skills/canvas-design/canvas-fonts/Outfit-Bold.ttf +0 -0
  57. package/template_project/.claude/skills/canvas-design/canvas-fonts/Tektur-Medium.ttf +0 -0
  58. package/template_project/.claude/skills/canvas-design/canvas-fonts/YoungSerif-OFL.txt +0 -93
  59. package/template_project/.claude/skills/canvas-design/canvas-fonts/YoungSerif-Regular.ttf +0 -0
@@ -0,0 +1,231 @@
1
+ import { createHash } from 'node:crypto';
2
+
3
+ // Section-level merge for `managed_template` files (replaces the old `.ukit-new` sidecar).
4
+ // A file is split by `## ` headings (outside code fences); the text before the first heading
5
+ // is the preamble (key ''). `recorded` is the per-section hash map UKit stored at the last
6
+ // install (the template's sections at that time), or null when none exists yet.
7
+
8
+ const sha256 = (text) => createHash('sha256').update(text, 'utf8').digest('hex');
9
+ const normalizeEol = (text) => text.replace(/\r\n/g, '\n');
10
+ const hashOf = (raw) => sha256(raw.trimEnd());
11
+
12
+ let sectioned = true; // set per call; non-markdown managed files are one whole-file section
13
+
14
+ // CommonMark fences: an opener is <=3 spaces + 3+ backticks/tildes (a backtick opener's info
15
+ // string may not contain a backtick); it closes only on the same character, at least the same
16
+ // length, with nothing but whitespace after. An UNCLOSED opener is treated as plain text, not a
17
+ // fence: CommonMark would run it to end of file, which would hide every later heading and make
18
+ // the merge re-append template sections on each run. Returns fenceAt[i] = line i is inside/on a fence.
19
+ function fenceMap(lines) {
20
+ const fenceAt = new Array(lines.length).fill(false);
21
+ for (let i = 0; i < lines.length; i += 1) {
22
+ const open = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(lines[i]);
23
+ if (!open || (open[1][0] === '`' && open[2].includes('`'))) continue;
24
+ const ch = open[1][0];
25
+ const len = open[1].length;
26
+ const closer = new RegExp(`^ {0,3}\\${ch}{${len},}\\s*$`);
27
+ let end = -1;
28
+ for (let j = i + 1; j < lines.length; j += 1) {
29
+ if (closer.test(lines[j])) { end = j; break; }
30
+ }
31
+ if (end === -1) { // unclosed: not a fence, but everything after it is suspect (see mergeManagedTemplate)
32
+ if (fenceAt.unclosedFrom === undefined) fenceAt.unclosedFrom = i;
33
+ continue;
34
+ }
35
+ for (let k = i; k <= end; k += 1) fenceAt[k] = true;
36
+ i = end;
37
+ }
38
+ return fenceAt;
39
+ }
40
+
41
+ function parseSections(lfText) {
42
+ if (!sectioned) return [{ key: '', raw: lfText }];
43
+ const lines = lfText.split('\n');
44
+ const sections = [{ key: '', raw: '' }];
45
+ const seen = new Map();
46
+ const fenceAt = fenceMap(lines);
47
+ lines.forEach((line, i) => {
48
+ const text = i < lines.length - 1 ? `${line}\n` : line;
49
+ if (!fenceAt[i] && /^## /.test(line)) {
50
+ const base = line.trimEnd();
51
+ const n = (seen.get(base) ?? 0) + 1;
52
+ seen.set(base, n);
53
+ // suspect: heading-shaped line after an unclosed fence opener — possibly inside the
54
+ // owner's intended code block, so the merge never rewrites or removes it.
55
+ sections.push({ key: n === 1 ? base : `${base}#${n}`, raw: '', suspect: fenceAt.unclosedFrom !== undefined && i > fenceAt.unclosedFrom });
56
+ }
57
+ sections[sections.length - 1].raw += text;
58
+ });
59
+ return sections;
60
+ }
61
+
62
+ export function sectionHashes(text, { markdown = true } = {}) {
63
+ sectioned = markdown;
64
+ const out = {};
65
+ for (const s of parseSections(normalizeEol(text.replace(/^/, '')))) out[s.key] = hashOf(s.raw);
66
+ return out;
67
+ }
68
+
69
+ const trailingWs = (raw) => raw.slice(raw.trimEnd().length);
70
+
71
+ // Record to store when the whole template was placed verbatim (create / unchanged / whole-file
72
+ // update): every key was really offered and placed, so the record is trusted (`@format: 2`).
73
+ export function recordFor(text, opts) {
74
+ return { ...sectionHashes(text, opts), '@format': '2' };
75
+ }
76
+
77
+ // Heading renames UKit ships, per managed file (matched by path suffix). Add an entry here in
78
+ // the same release that renames a heading in a managed template:
79
+ // { file: 'docs/AI_HANDOFF/<x>.md', renames: [{ from: '## Old', to: '## New', fromHashes: [...] }] }
80
+ // `fromHashes` = section hashes of every body ever shipped under the old heading: an old section
81
+ // whose hash is listed (or equals the recorded baseline) was never edited by the owner and is
82
+ // safe to rewrite or drop. Empty today: no shipped template has renamed a heading yet (the old
83
+ // `queued/README.md` headings only ever existed in this repo's own docs copy, never in a
84
+ // shipped template).
85
+ export const MANAGED_RENAMES = [];
86
+
87
+ export function renamesFor(targetPath) {
88
+ const p = String(targetPath).replace(/\\/g, '/');
89
+ return MANAGED_RENAMES.find((m) => p.endsWith(`/${m.file}`) || p === m.file)?.renames ?? [];
90
+ }
91
+
92
+ // A record is usable only if it is a plain object of string hashes; anything else (lost or
93
+ // corrupt) is "no record". Ack and marker keys live in the same map: they can never equal a
94
+ // `## ` heading key, so older UKit versions ignore them.
95
+ // `@format: 2` marks a record written by this merge. A record WITHOUT it (3.5.6 or older) still
96
+ // serves for the edited-vs-untouched decision, but not for "this key was already offered and
97
+ // placed": 3.5.6 recorded every template key, including one it skipped because its heading sat
98
+ // in a fence. For append decisions a legacy record is treated like no record.
99
+ const FORMAT_KEY = '@format';
100
+ const FORMAT = '2';
101
+ const ACK = (heading) => `@renamed ${heading}`;
102
+ const HELD = (heading) => `@held ${heading}`;
103
+ const validRecord = (r) => (r && typeof r === 'object' && !Array.isArray(r) && Object.values(r).every((v) => typeof v === 'string') && Object.keys(r).length > 0 ? r : null);
104
+
105
+ export function mergeManagedTemplate({ existing, template, recorded: rawRecorded = null, markdown = true, renames = [] }) {
106
+ sectioned = markdown;
107
+ const recorded = validRecord(rawRecorded);
108
+ const trusted = recorded?.[FORMAT_KEY] === FORMAT; // written by this merge: key presence means "offered"
109
+ const bom = existing.startsWith('');
110
+ const eol = existing.includes('\r\n') ? '\r\n' : '\n';
111
+ const existingLf = normalizeEol(existing.replace(/^/, ''));
112
+ const templateSections = parseSections(normalizeEol(template.replace(/^/, '')));
113
+ const tplByKey = new Map(templateSections.map((s) => [s.key, s]));
114
+ const sections = Object.fromEntries(templateSections.map((s) => [s.key, hashOf(s.raw)]));
115
+ sections[FORMAT_KEY] = FORMAT;
116
+ const notices = [];
117
+ const skipAppend = new Set(); // template keys already represented by a renamed owner section
118
+ const acks = new Set(); // old headings whose rename notice was already shown
119
+
120
+ const parts = [];
121
+ const existingSections = parseSections(existingLf);
122
+ const existingKeys = new Set(existingSections.map((s) => s.key));
123
+ let removedTail = null;
124
+ for (const [idx, e] of existingSections.entries()) {
125
+ const t = tplByKey.get(e.key);
126
+ const base = recorded?.[e.key];
127
+ const ren = !e.suspect && !t ? renames.find((r) => r.from === e.key && tplByKey.has(r.to) && !tplByKey.has(r.from)) : null;
128
+ if (ren) {
129
+ const eh = hashOf(e.raw);
130
+ if (eh === base || (ren.fromHashes ?? []).includes(eh)) {
131
+ // Never edited by the owner: drop it if the new heading is already there, else rename in place.
132
+ if (existingKeys.has(ren.to)) {
133
+ if (idx === existingSections.length - 1) removedTail = trailingWs(e.raw);
134
+ } else {
135
+ parts.push({ key: ren.to, raw: tplByKey.get(ren.to).raw.trimEnd() + trailingWs(e.raw) });
136
+ }
137
+ } else {
138
+ // Owner-edited old section: keep it, never add the renamed one next to it, say so once.
139
+ skipAppend.add(ren.to);
140
+ acks.add(e.key);
141
+ if (recorded?.[ACK(e.key)] === undefined) notices.push({ heading: e.key, renamedTo: ren.to });
142
+ parts.push({ key: e.key, raw: e.raw });
143
+ }
144
+ } else if (e.suspect) {
145
+ parts.push({ key: e.key, raw: e.raw, suspect: true });
146
+ } else if (t) {
147
+ const eh = hashOf(e.raw);
148
+ const th = sections[e.key];
149
+ if (eh === th) {
150
+ parts.push({ key: e.key, raw: e.raw });
151
+ } else if (typeof base === 'string' && eh === base) {
152
+ parts.push({ key: e.key, raw: t.raw.trimEnd() + trailingWs(e.raw) });
153
+ } else {
154
+ // Owner-changed (or no baseline): keep. Notice only when the template moved since the record.
155
+ if (typeof base === 'string' && th !== base) notices.push({ heading: e.key || '(preamble)' });
156
+ parts.push({ key: e.key, raw: e.raw });
157
+ }
158
+ } else if (typeof base === 'string' && hashOf(e.raw) === base) {
159
+ // Upstream removed it and the owner never changed it.
160
+ if (idx === existingSections.length - 1) removedTail = trailingWs(e.raw);
161
+ } else {
162
+ parts.push({ key: e.key, raw: e.raw });
163
+ }
164
+ }
165
+
166
+ if (removedTail !== null && parts.length > 0) {
167
+ const last = parts[parts.length - 1];
168
+ last.raw = last.raw.trimEnd() + removedTail;
169
+ }
170
+
171
+ // A suspect section (heading-shaped line after an unclosed fence) is not proof the template
172
+ // section is present: it is held below instead of counted.
173
+ const have = new Set(parts.filter((p) => !p.suspect).map((p) => p.key));
174
+ // Idempotence comes from RECORDED STATE, not from scanning the text: every template key that
175
+ // was ever merged is in `recorded`, and a recorded key is never appended again. That makes the
176
+ // result independent of how fences pair in an owner-edited file (unclosed fences cannot grow
177
+ // the file) and keeps a deliberately deleted section deleted. A heading the owner merely quoted
178
+ // in a code block therefore no longer blocks a new template section of that name.
179
+ // A key that is not recorded (no record, a lost/corrupt record, or a section new in this
180
+ // version) is appended, even if its heading is merely quoted in a CLOSED fence: the appended
181
+ // section parses as a real section next run, and its balanced fences cannot shift pairing.
182
+ // Only when the owner's file holds an UNCLOSED fence can an appended section's own fence pair
183
+ // with it, close it, and shift every later pairing (F1 growth, and a held section flipping to
184
+ // appended on run 2). So when such a section exists, NOTHING unrecorded is appended: each is
185
+ // HELD: removed from the recorded section hashes (so it is not recorded as present), and
186
+ // acked once under `@held <heading>` so the owner is told once and the notice is not repeated.
187
+ // When the owner closes the fence the key is no longer held and the next run appends it once.
188
+ const unclosed = fenceMap(existingLf.split('\n')).unclosedFrom !== undefined;
189
+ const existingLines = unclosed ? new Set(existingLf.split('\n').map((l) => l.trimEnd())) : null;
190
+ const offered = (key) => trusted && recorded[key] !== undefined;
191
+ const pending = (t) => t.key !== '' && !have.has(t.key) && !skipAppend.has(t.key) && !offered(t.key);
192
+ // If any pending section is held, hold every pending one: appending a sibling whose own fence
193
+ // closes the owner's unclosed opener would change the pairing and release the held one on run 2.
194
+ const holdAll = unclosed && templateSections.some((t) => pending(t) && existingLines.has(t.key.replace(/#\d+$/, '')));
195
+ templateSections.forEach((t, i) => {
196
+ if (have.has(t.key) || skipAppend.has(t.key)) return;
197
+ if (t.key !== '') {
198
+ if (offered(t.key)) return;
199
+ if (holdAll) {
200
+ if (recorded?.[HELD(t.key)] === undefined) notices.push({ heading: t.key, held: true });
201
+ delete sections[t.key];
202
+ sections[HELD(t.key)] = sha256(t.key);
203
+ return;
204
+ }
205
+ }
206
+ let at = parts.length;
207
+ for (let j = i - 1; j >= 0; j -= 1) {
208
+ const idx = parts.findIndex((p) => p.key === templateSections[j].key);
209
+ if (idx !== -1) { at = idx + 1; break; }
210
+ }
211
+ parts.splice(at, 0, { key: t.key, raw: t.raw, added: true });
212
+ have.add(t.key);
213
+ });
214
+
215
+ parts.forEach((p, i) => {
216
+ if (!p.added) return;
217
+ if (i < parts.length - 1 && !p.raw.endsWith('\n\n')) p.raw = `${p.raw.trimEnd()}\n\n`;
218
+ const prev = parts[i - 1];
219
+ if (prev && prev.raw !== '' && !prev.raw.endsWith('\n\n')) prev.raw = `${prev.raw.trimEnd()}\n\n`;
220
+ });
221
+
222
+ for (const h of acks) sections[ACK(h)] = sha256(h);
223
+ for (const r of renames) {
224
+ if (recorded?.[ACK(r.from)] !== undefined && have.has(r.from)) sections[ACK(r.from)] = sha256(r.from);
225
+ }
226
+
227
+ const mergedLf = parts.map((p) => p.raw).join('');
228
+ if (mergedLf === existingLf) return { content: existing, changed: false, notices, sections };
229
+ const body = eol === '\r\n' ? mergedLf.replace(/\n/g, '\r\n') : mergedLf;
230
+ return { content: (bom ? '' : '') + body, changed: true, notices, sections };
231
+ }
@@ -4,12 +4,11 @@
4
4
  // resolveConfigStage machinery: off → shadow → canary → default. Flags only
5
5
  // ever REDUCE capability — malformed/missing resolves 'off', killSwitch is
6
6
  // absolute, and 'canary' without an opted-in projectId resolves 'off'.
7
- // The `decision` plane is reserved for the memoryV2 candidate-classification
8
- // lane (registry key `learn.candidate-class.v1`, family 'learn'). Note the
9
- // decision-plane stage namespace is separate: promotion gates that key via
10
- // `decisionPlane.families.learn.stage`, NOT `memoryV2.decision.stage` — this
11
- // flag only guards the memoryV2 lane itself. Zero consumers today — do not
12
- // remove; user configs may pin its stage key.
7
+ // The `decision` plane is reserved for the memoryV2 decision lane and has no
8
+ // consumer today — do not remove; user configs may pin its stage key. Lesson
9
+ // classification (registry key `learn.candidate-class.v1`, family 'learn',
10
+ // owner src/learning/lessonClass.js) is a separate namespace: it is gated by
11
+ // `decisionPlane.families.learn.stage`, NOT `memoryV2.decision.stage`.
13
12
  //
14
13
  // Shadow receipts are the only telemetry: bounded JSONL of counts/codes/
15
14
  // latency bands — never record text, prompt bodies, or secrets.
@@ -70,6 +70,11 @@ export function eligible(record, context = {}, policy = {}) {
70
70
  if (NON_AUTHORITY_TRUST_TIERS.includes(record.trust_tier)) {
71
71
  return deny('non-authority-trust-tier');
72
72
  }
73
+ // Records written before candidates got trust_tier 'candidate' sit as
74
+ // active/verified with meta.legacyStatus 'pending' — still unreviewed.
75
+ if (record.meta?.legacyStatus === 'pending') {
76
+ return deny('pending-approval');
77
+ }
73
78
 
74
79
  if (record.scope === 'user') {
75
80
  if (context.includeUser !== true) {
@@ -608,6 +608,8 @@ function patternCandidateFromRecord(record) {
608
608
  };
609
609
  }
610
610
 
611
+ const DAY_MS = 24 * 60 * 60 * 1000;
612
+
611
613
  async function proposePatternCandidateV2(projectRoot, projectId, candidate, { homeDir } = {}) {
612
614
  const v2 = await storeV2();
613
615
  const normalizedText = normalizePatternText(candidate?.text);
@@ -643,6 +645,19 @@ async function proposePatternCandidateV2(projectRoot, projectId, candidate, { ho
643
645
  confidence: 0.4,
644
646
  createdBy: 'propose',
645
647
  projectId,
648
+ // Unreviewed until `memory approve`: candidate tier keeps it out of every
649
+ // recall path; approval flips it to verified and clears the expiry.
650
+ // Only mined lessons ask for an expiry (candidate.ttlDays); a hand-written
651
+ // `memory propose` candidate stays pending until a person decides.
652
+ trustTier: 'candidate',
653
+ validUntil: Number(candidate?.ttlDays) > 0 ? Date.now() + Number(candidate.ttlDays) * DAY_MS : null,
654
+ evidence: (Array.isArray(candidate?.evidence) ? candidate.evidence : []).map((ev) => ({
655
+ kind: ev.kind,
656
+ locator: ev.locator,
657
+ observed_at: Date.now(),
658
+ fingerprint: null,
659
+ trust_tier: 'verified',
660
+ })),
646
661
  meta: { ...entry, legacyStatus: 'pending' },
647
662
  }, { homeDir });
648
663
  return entry;
@@ -684,6 +699,8 @@ async function resolvePatternCandidateV2(projectRoot, projectId, candidateId, de
684
699
  provenance: `${target.provenance ?? 'pattern-candidate'};promoted-from:${target.id}`,
685
700
  // Approval is a trust transition — the promoted record is authoritative.
686
701
  trust_tier: 'verified',
702
+ // A promoted rule must not inherit a mined lesson's expiry.
703
+ valid_until: null,
687
704
  meta: {
688
705
  ...target.meta,
689
706
  legacyStatus: 'approved',
@@ -73,7 +73,7 @@ export async function writeInstallMetadata({
73
73
  ompConfigOwnership = null,
74
74
  settingsDefaultsMigration = null,
75
75
  managedHashes = null,
76
- sidecarHashes = null,
76
+ managedSections = null,
77
77
  lockStaleMs,
78
78
  lockMaxWaitMs,
79
79
  }) {
@@ -158,17 +158,21 @@ export async function writeInstallMetadata({
158
158
  const migrationMarker = settingsDefaultsMigration ?? (previousData?.tool === 'ukit' ? previousData.settingsDefaultsMigration : null);
159
159
  if (migrationMarker) metadata.settingsDefaultsMigration = migrationMarker;
160
160
 
161
- // CR-13 provenance for `.ukit-new` sidecars. Only hashes recorded for a sidecar
162
- // UKit actually created this run are kept; every other recorded sidecar is
163
- // re-verified against disk so a record never outlives (or claims) owner content.
164
- // A sidecar whose bytes changed is dropped — it is owner-modified from then on.
161
+ // Per-section template hashes (section-merge baseline for managed templates). Kept across
162
+ // runs; entries for files rewritten this run are replaced.
163
+ const prevSections = previousData?.tool === 'ukit' && previousData.managedSections && typeof previousData.managedSections === 'object'
164
+ ? previousData.managedSections
165
+ : {};
166
+ const mergedSections = { ...prevSections, ...(managedSections ?? {}) };
167
+ if (Object.keys(mergedSections).length > 0) metadata.managedSections = mergedSections;
168
+
169
+ // Legacy `.ukit-new` provenance (sidecars are no longer written). Previously recorded
170
+ // hashes are kept only while the file on disk still matches, so a later cleanup /
171
+ // uninstall can still attribute them; nothing new is ever added.
165
172
  const previousSidecars = previousData?.tool === 'ukit' && previousData.sidecars && typeof previousData.sidecars === 'object'
166
173
  ? previousData.sidecars
167
174
  : {};
168
175
  const mergedSidecars = { ...previousSidecars };
169
- for (const [relPath, hash] of Object.entries(sidecarHashes ?? {})) {
170
- if (typeof hash === 'string') mergedSidecars[normalizeTrackedRelativePath(relPath)] = hash;
171
- }
172
176
  const verifiedSidecars = {};
173
177
  if (projectRoot) {
174
178
  for (const [relPath, hash] of Object.entries(mergedSidecars)) {
@@ -466,14 +466,21 @@ export async function runInstallPipeline({
466
466
  .filter(([p, h]) => typeof p === 'string' && typeof h === 'string')
467
467
  .map(([p, h]) => [path.join(pathConfig.projectRoot, p), h]),
468
468
  );
469
- const diffResults = await diffInstallPlan(plan, { ompOwnership, settingsMigration, recordedManagedHashes });
469
+ // Per-section template hashes recorded at the last install (absent in older install.json).
470
+ const recordedManagedSections = new Map(
471
+ Object.entries(installMetaData?.managedSections ?? {})
472
+ .filter(([p, m]) => typeof p === 'string' && m && typeof m === 'object')
473
+ .map(([p, m]) => [path.join(pathConfig.projectRoot, p), m]),
474
+ );
475
+ const diffResults = await diffInstallPlan(plan, { ompOwnership, settingsMigration, recordedManagedHashes, recordedManagedSections });
470
476
  const plannedSummary = summarizeDiff(diffResults);
471
477
 
472
478
  if (!dryRun) {
473
- const { writes, skippedUpdates, skippedByAction, sidecarHashes } = await applyDiffResults(diffResults, {
479
+ const { writes, skippedUpdates, skippedByAction } = await applyDiffResults(diffResults, {
474
480
  backupRoot: pathConfig.backupRoot,
475
481
  projectRoot: pathConfig.projectRoot,
476
482
  recordedSidecarHashes,
483
+ packageVersion,
477
484
  });
478
485
 
479
486
  for (const entry of diffResults) {
@@ -580,18 +587,17 @@ export async function runInstallPipeline({
580
587
  .filter((e) => e.managedHash && ['create', 'update', 'unchanged'].includes(e.action))
581
588
  .map((e) => [path.relative(pathConfig.projectRoot, e.targetPath).split(path.sep).join('/'), e.managedHash]),
582
589
  );
583
- // Sidecar provenance map (relative path → sha256 UKit wrote this run). Written
584
- // only after apply succeeded, so a failed create never claims ownership.
585
- const sidecarRecords = Object.fromEntries(
586
- Object.entries(sidecarHashes).map(([absPath, h]) => [
587
- path.relative(pathConfig.projectRoot, absPath).split(path.sep).join('/'),
588
- h,
589
- ]),
590
+ // Per-section template hashes for managed templates (recorded after apply succeeded;
591
+ // a conflict/skipped entry has none).
592
+ const managedSections = Object.fromEntries(
593
+ diffResults
594
+ .filter((e) => e.managedSections && ['create', 'update', 'unchanged'].includes(e.action))
595
+ .map((e) => [path.relative(pathConfig.projectRoot, e.targetPath).split(path.sep).join('/'), e.managedSections]),
590
596
  );
591
597
  await writeInstallMetadata({
592
598
  installMetaPath: pathConfig.installMetaPath,
593
599
  managedHashes,
594
- sidecarHashes: sidecarRecords,
600
+ managedSections,
595
601
  packageVersion,
596
602
  manifest,
597
603
  stackContext,
@@ -207,9 +207,7 @@ export function resolveConfigStage(config = null, path) {
207
207
 
208
208
  // decisionRuntime family stage resolver (V-03): resolves
209
209
  // `decisionRuntime.<key>.stage` for one pinned family flag ('vm',
210
- // 'supervisor', 'scheduler', 'contract', 'adapters', 'context',
211
- // 'completion', 'quality', 'promotion', 'resourcePolicy',
212
- // 'diagnostics'). Same semantics as resolveConfigStage: absent config,
210
+ // 'supervisor', 'contract', 'adapters', 'promotion', 'diagnostics'). Same semantics as resolveConfigStage: absent config,
213
211
  // absent family, non-string key, or malformed stage all resolve 'off'
214
212
  // — a bad config can never promote a decisionRuntime slice.
215
213
  export function resolveDecisionRuntimeStage(config = null, key = 'vm') {
@@ -573,13 +571,6 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
573
571
  // codeProposalsCommit is a reserved hard-false — writing a task file is
574
572
  // the ceiling; self-improve never commits code (clamped below).
575
573
  selfImprove: { enabled: true, codeProposals: true, codeProposalsCommit: false },
576
- // C52 M04.2 stage keys (SPEC §5 FR-016–FR-018). candidates: repeated
577
- // corrections/suppressions/escalations promote to a LearningCandidate
578
- // only after minOccurrences + cross-session evidence (status
579
- // 'proposed'; rule promotion still needs approval). overlays: only
580
- // approved + enabled overlays apply; base-version mismatch → conflict.
581
- candidates: { stage: 'default', minOccurrences: 3 },
582
- overlays: { stage: 'default' },
583
574
  },
584
575
  // C52 M04.1 compact resumable state (SPEC §5 FR-012–FR-015): a bounded
585
576
  // resumable-run record per route so a compacted session resumes mid-task.
@@ -590,14 +581,11 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
590
581
  // decision-first-runtime (SPEC §2 G1-FR07, §2 G2-FR07/08, §2 G4-FR07,
591
582
  // §2 G5-FR07, §2 G7-FR04/07). Pinned keys — `decisionRuntime.contract`
592
583
  // gates the G1 contract/eventStore prototype; `decisionRuntime.supervisor`
593
- // gates the G2 owned-process supervisor; `decisionRuntime.scheduler`
594
- // gates the G3 scheduler; `decisionRuntime.vm` gates the G4 plan-VM
595
- // engine; `decisionRuntime.adapters`, `decisionRuntime.context`,
596
- // `decisionRuntime.completion`, and `decisionRuntime.quality` gate the
597
- // G5 adapters/context/completion/quality slice; `decisionRuntime.promotion`
598
- // gates the G6 caller-wait promotion profile and
599
- // `decisionRuntime.resourcePolicy` gates the G6 pressure/coalescing
600
- // policy; `decisionRuntime.diagnostics` gates the G7 explainable-trace /
584
+ // gates the G2 owned-process supervisor; `decisionRuntime.vm` gates the
585
+ // G4 plan-VM engine; `decisionRuntime.adapters` gates the G5 adapters
586
+ // slice; `decisionRuntime.promotion`
587
+ // gates the G6 caller-wait promotion profile;
588
+ // `decisionRuntime.diagnostics` gates the G7 explainable-trace /
601
589
  // replay / support-record readers. 3.3.0 zero-config: every family ships
602
590
  // 'shadow' — evidence is recorded while the deterministic owners stay
603
591
  // authoritative; promotion.js promotes a family only once its frozen
@@ -606,14 +594,9 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
606
594
  decisionRuntime: {
607
595
  contract: { stage: 'shadow' },
608
596
  supervisor: { stage: 'shadow' },
609
- scheduler: { stage: 'shadow' },
610
597
  vm: { stage: 'shadow' },
611
598
  adapters: { stage: 'shadow' },
612
- context: { stage: 'shadow' },
613
- completion: { stage: 'shadow' },
614
- quality: { stage: 'shadow' },
615
599
  promotion: { stage: 'shadow' },
616
- resourcePolicy: { stage: 'shadow' },
617
600
  diagnostics: { stage: 'default' },
618
601
  },
619
602
 
@@ -629,14 +612,6 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
629
612
  roleAdvice: { stage: 'off' },
630
613
  contextSelection: { stage: 'off' },
631
614
  },
632
-
633
- // C52 M06 experiments (SPEC §5 FR-021–FR-023). 3.3.0 zero-config: enabled;
634
- // each experiment still runs only where a caller invokes it and never
635
- // auto-promotes its own result.
636
- experiments: {
637
- deliberation: { enabled: true },
638
- dynamicWorkflow: { enabled: true, maxAttemptsPerFailure: 2, noProgressCap: 3 },
639
- },
640
615
  // Flight recorder (docs/OBSERVABILITY.md): 'default' activates recorder,
641
616
  // analytics, support projection and evaluation. 'off' is the kill switch.
642
617
  observability: { stage: 'default' },
@@ -944,16 +919,18 @@ export function validateRuntimeConfig(config) {
944
919
  // C63 DR-02 + C64 DR-03/04 + C67 DR-07/08 + C68 DR-09 + C69 DR-10
945
920
  // decisionRuntime — optional-present; carries one stage key per prototype
946
921
  // (pinned: decisionRuntime.contract, decisionRuntime.supervisor,
947
- // decisionRuntime.scheduler, decisionRuntime.vm, decisionRuntime.adapters,
948
- // decisionRuntime.context, decisionRuntime.completion,
949
- // decisionRuntime.quality, decisionRuntime.promotion,
950
- // decisionRuntime.resourcePolicy, decisionRuntime.diagnostics). Absent →
951
- // valid; malformed stage → error + resolver falls back to 'off'.
922
+ // decisionRuntime.vm, decisionRuntime.adapters, decisionRuntime.promotion,
923
+ // decisionRuntime.diagnostics). Absent →
924
+ // valid; malformed stage → error + resolver falls back to 'off'. Retired
925
+ // keys (decisionRuntime.scheduler/context/completion/quality/resourcePolicy,
926
+ // experiments.*, learning.candidates/overlays — no reader, removed in
927
+ // 3.5.6) are not validated, so old configs carrying them stay valid and
928
+ // their values are ignored without a warning.
952
929
  if (config.decisionRuntime !== undefined) {
953
930
  if (!isPlainObject(config.decisionRuntime)) {
954
931
  errors.push('decisionRuntime must be an object.');
955
932
  } else {
956
- for (const key of ['contract', 'supervisor', 'scheduler', 'vm', 'adapters', 'context', 'completion', 'quality', 'promotion', 'resourcePolicy', 'diagnostics']) {
933
+ for (const key of ['contract', 'supervisor', 'vm', 'adapters', 'promotion', 'diagnostics']) {
957
934
  const stageKey = config.decisionRuntime[key];
958
935
  if (stageKey === undefined) continue;
959
936
  if (!isPlainObject(stageKey)) {
@@ -984,34 +961,6 @@ export function validateRuntimeConfig(config) {
984
961
  }
985
962
  }
986
963
  }
987
- // C52 M06 experiments — optional-present; both experiments are
988
- // disabled-by-default booleans plus bounded breakers.
989
- if (config.experiments !== undefined) {
990
- if (!isPlainObject(config.experiments)) {
991
- errors.push('experiments must be an object.');
992
- } else {
993
- if (config.experiments.deliberation !== undefined) {
994
- if (!isPlainObject(config.experiments.deliberation)) {
995
- errors.push('experiments.deliberation must be an object.');
996
- } else {
997
- pushBooleanError(errors, config.experiments.deliberation.enabled, 'experiments.deliberation.enabled');
998
- }
999
- }
1000
- if (config.experiments.dynamicWorkflow !== undefined) {
1001
- if (!isPlainObject(config.experiments.dynamicWorkflow)) {
1002
- errors.push('experiments.dynamicWorkflow must be an object.');
1003
- } else {
1004
- pushBooleanError(errors, config.experiments.dynamicWorkflow.enabled, 'experiments.dynamicWorkflow.enabled');
1005
- if (config.experiments.dynamicWorkflow.maxAttemptsPerFailure !== undefined) {
1006
- pushPositiveNumberError(errors, config.experiments.dynamicWorkflow.maxAttemptsPerFailure, 'experiments.dynamicWorkflow.maxAttemptsPerFailure');
1007
- }
1008
- if (config.experiments.dynamicWorkflow.noProgressCap !== undefined) {
1009
- pushPositiveNumberError(errors, config.experiments.dynamicWorkflow.noProgressCap, 'experiments.dynamicWorkflow.noProgressCap');
1010
- }
1011
- }
1012
- }
1013
- }
1014
- }
1015
964
 
1016
965
  // modelRoles is optional-present and additive-namespaced (SPEC-model-roles): absent →
1017
966
  // valid (pre-v3 configs); present → must be an object. Entry-level issues (unknown
@@ -1327,24 +1276,6 @@ export function validateRuntimeConfig(config) {
1327
1276
  pushBooleanError(errors, learning.selfImprove.codeProposalsCommit, 'learning.selfImprove.codeProposalsCommit');
1328
1277
  }
1329
1278
  }
1330
- // C52 M04.2 stage keys — same optional-present contract as routing.*.
1331
- if (learning.candidates !== undefined) {
1332
- if (!isPlainObject(learning.candidates)) {
1333
- errors.push('learning.candidates must be an object.');
1334
- } else {
1335
- pushStageError(errors, learning.candidates, 'learning.candidates');
1336
- if (learning.candidates.minOccurrences !== undefined) {
1337
- pushPositiveNumberError(errors, learning.candidates.minOccurrences, 'learning.candidates.minOccurrences');
1338
- }
1339
- }
1340
- }
1341
- if (learning.overlays !== undefined) {
1342
- if (!isPlainObject(learning.overlays)) {
1343
- errors.push('learning.overlays must be an object.');
1344
- } else {
1345
- pushStageError(errors, learning.overlays, 'learning.overlays');
1346
- }
1347
- }
1348
1279
  }
1349
1280
  }
1350
1281
 
@@ -501,7 +501,14 @@ export async function uninstallUkit({ projectRoot, dryRun = false }) {
501
501
  const sidecarRel = `${entry.normalizedRelative}.ukit-new`;
502
502
  const recordedSidecarHash = installData.sidecars?.[sidecarRel];
503
503
  const sidecarState = await readSidecarState(sidecarAbs);
504
- if (sidecarState.state === 'file' && typeof recordedSidecarHash === 'string' && recordedSidecarHash === sidecarState.hash) {
504
+ // Also attributable: bytes equal to the shipped template (what old versions wrote).
505
+ const shippedForSidecar = managedMap.has(entry.normalizedRelative) && sidecarState.state === 'file'
506
+ ? await fs.readFile(managedMap.get(entry.normalizedRelative)).catch(() => null)
507
+ : null;
508
+ if (sidecarState.state === 'file' && (
509
+ (typeof recordedSidecarHash === 'string' && recordedSidecarHash === sidecarState.hash)
510
+ || (shippedForSidecar !== null && sha256Hex(shippedForSidecar) === sidecarState.hash)
511
+ )) {
505
512
  regularPaths.push({ abs: sidecarAbs, recursive: false });
506
513
  } else if (sidecarState.state !== 'absent') {
507
514
  preservedSidecars.push(sidecarAbs);
@@ -22,8 +22,8 @@ export const DECISION_FAMILIES = new Set([
22
22
  'verify',
23
23
  'review',
24
24
  'resume',
25
- 'learn',
26
25
  'memory',
26
+ 'learn',
27
27
  'runtime',
28
28
  ]);
29
29
 
@@ -273,22 +273,6 @@ export const DECISION_REGISTRY = Object.freeze([
273
273
  cacheSensitivity: 'none',
274
274
  leasePolicy: 'none',
275
275
  },
276
- {
277
- decisionKey: 'learn.candidate-class.v1',
278
- schemaVersion: 1,
279
- family: 'learn',
280
- owner: 'learningCandidates',
281
- kind: 'choice',
282
- description: 'Learning candidate classification for a captured signal. Reserved for the memoryV2 decision lane; promotion gates via decisionPlane.families.learn.stage.',
283
- candidatePolicy: 'owner-shortlist',
284
- hardConstraints: ['promotion-approval'],
285
- probabilityPolicy: 'raw-label',
286
- fallbackPolicy: 'deterministic-classifier',
287
- telemetryClass: 'decision',
288
- rolloutStage: 'off',
289
- cacheSensitivity: 'none',
290
- leasePolicy: 'none',
291
- },
292
276
  {
293
277
  decisionKey: 'review.verdict.v1',
294
278
  schemaVersion: 1,
@@ -449,6 +433,22 @@ export const DECISION_REGISTRY = Object.freeze([
449
433
  cacheSensitivity: 'none',
450
434
  leasePolicy: 'none',
451
435
  },
436
+ {
437
+ decisionKey: 'learn.candidate-class.v1',
438
+ schemaVersion: 1,
439
+ family: 'learn',
440
+ owner: 'lessonClass',
441
+ kind: 'noul',
442
+ description: 'Whether one mined pattern is a real recurring lesson (asked once per ambiguous candidate, wire name carries `#c<n>`). A low answer can only downgrade a candidate to noise; it never approves or promotes. Gated by decisionPlane.families.learn.stage; session end and `ukit memory learn` only.',
443
+ candidatePolicy: 'ambiguous-mined-patterns',
444
+ hardConstraints: ['no-promotion', 'downgrade-only'],
445
+ probabilityPolicy: 'raw-label',
446
+ fallbackPolicy: 'deterministic-rules',
447
+ telemetryClass: 'decision',
448
+ rolloutStage: 'off',
449
+ cacheSensitivity: 'none',
450
+ leasePolicy: 'none',
451
+ },
452
452
  ]);
453
453
 
454
454
  // Deep-freeze the shipped catalog — entries are shared metadata consumed by