@ngockhoale/ukit 3.5.5 → 3.5.6

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 (53) hide show
  1. package/CHANGELOG.md +12 -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 +25 -72
  8. package/src/core/diffPlan.js +38 -9
  9. package/src/core/managedTemplateMerge.js +146 -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/queryIndex.js +41 -4
  20. package/src/index/routeResolver.js +2 -2
  21. package/src/index/semanticLane.js +269 -0
  22. package/src/learning/lessonClass.js +110 -0
  23. package/src/learning/patternProposals.js +111 -7
  24. package/src/learning/reeditMiner.js +104 -0
  25. package/src/learning/selfImprove.js +9 -1
  26. package/template_project/.claude/skills/canvas-design/SKILL.md +2 -2
  27. package/template_project/.claude/skills/canvas-design/canvas-fonts/{InstrumentSans-OFL.txt → InstrumentSerif-OFL.txt} +3 -3
  28. package/template_project/.claude/skills/canvas-design/scripts/fetch-fonts.mjs +148 -0
  29. package/template_project/.claude/ukit/index/embed-index.mjs +26 -0
  30. package/template_project/.claude/ukit/index/lib/index-core.mjs +43 -4
  31. package/template_project/.claude/ukit/index/lib/semantic-lane.mjs +269 -0
  32. package/template_project/.claude/ukit/index/query-index.mjs +9 -1
  33. package/template_project/.claude/ukit/index/route-resolver.mjs +2 -2
  34. package/template_project/.claude/ukit/runtime/memory-policy.mjs +5 -0
  35. package/template_project/ukit/storage/config.json +0 -32
  36. package/template_project/.claude/skills/canvas-design/canvas-fonts/BricolageGrotesque-Bold.ttf +0 -0
  37. package/template_project/.claude/skills/canvas-design/canvas-fonts/BricolageGrotesque-OFL.txt +0 -93
  38. package/template_project/.claude/skills/canvas-design/canvas-fonts/BricolageGrotesque-Regular.ttf +0 -0
  39. package/template_project/.claude/skills/canvas-design/canvas-fonts/InstrumentSans-Bold.ttf +0 -0
  40. package/template_project/.claude/skills/canvas-design/canvas-fonts/InstrumentSans-BoldItalic.ttf +0 -0
  41. package/template_project/.claude/skills/canvas-design/canvas-fonts/InstrumentSans-Italic.ttf +0 -0
  42. package/template_project/.claude/skills/canvas-design/canvas-fonts/InstrumentSans-Regular.ttf +0 -0
  43. package/template_project/.claude/skills/canvas-design/canvas-fonts/InstrumentSerif-Italic.ttf +0 -0
  44. package/template_project/.claude/skills/canvas-design/canvas-fonts/JetBrainsMono-Bold.ttf +0 -0
  45. package/template_project/.claude/skills/canvas-design/canvas-fonts/Lora-Bold.ttf +0 -0
  46. package/template_project/.claude/skills/canvas-design/canvas-fonts/Lora-BoldItalic.ttf +0 -0
  47. package/template_project/.claude/skills/canvas-design/canvas-fonts/Lora-Italic.ttf +0 -0
  48. package/template_project/.claude/skills/canvas-design/canvas-fonts/Lora-OFL.txt +0 -93
  49. package/template_project/.claude/skills/canvas-design/canvas-fonts/Lora-Regular.ttf +0 -0
  50. package/template_project/.claude/skills/canvas-design/canvas-fonts/Outfit-Bold.ttf +0 -0
  51. package/template_project/.claude/skills/canvas-design/canvas-fonts/Tektur-Medium.ttf +0 -0
  52. package/template_project/.claude/skills/canvas-design/canvas-fonts/YoungSerif-OFL.txt +0 -93
  53. package/template_project/.claude/skills/canvas-design/canvas-fonts/YoungSerif-Regular.ttf +0 -0
package/CHANGELOG.md CHANGED
@@ -2,6 +2,18 @@
2
2
 
3
3
  All notable changes to UKit are documented here.
4
4
 
5
+ ## 3.5.6 - 2026-11-15
6
+
7
+ Cleanup release: unused modules and flags removed, the `.ukit-new` files are gone, most design fonts moved out of the package, the two learning ideas rebuilt as one small, measured step, and an opt-in vector lane for index search. Every number below was measured on this repository only. No host (Claude Code, Codex, omp) was run live and nothing was run on Windows.
8
+
9
+ - **No more `.ukit-new` files.** `docs/AI_HANDOFF/RULES.md` and `docs/AI_HANDOFF/queued/README.md` used to get a `<file>.ukit-new` copy on every install once you had edited them. They are now merged in place, section by section (`## ` headings): a section you never touched is updated to the new template, a section you edited or added is kept, and a new template section is added. Three limits: a new template section is not added when its exact heading line already appears anywhere in your file, even quoted inside a code block (this is what keeps the file from growing on repeated installs); on the first install after upgrading from 3.5.5 or older there is no record of what UKit wrote, so every section that differs from the current template is kept as if you had edited it (and reported whenever the template later changes that section); and a section whose heading was renamed is kept while the template's section under the other name is added beside it — whether you renamed it or UKit did in an earlier version. The known case is `docs/AI_HANDOFF/queued/README.md`: 3.4.66 renamed "Deliberate-future queue" to "Deliberate-future queue (backlog)" and "Mandatory overflow (consumable, not backlog)" to "Mandatory overflow (consumable)", so a copy older than 3.4.66 that you edited, or that has no recorded hash, ends up once with the old and the new version of those two sections side by side and no message printed; delete the two old sections by hand. When a section you edited also changed in the template, install prints one line naming it and keeps yours. The previous file is copied to the backup folder before any change. A leftover `.ukit-new` from an older version is removed only when its content is UKit's own (recorded hash, or identical to the shipped template); anything else is left and reported once. Checked in a temporary project: install, add a section to `RULES.md`, install twice — no `.ukit-new`, the section is kept, the later runs print nothing about the file.
10
+ - **Seven unused modules and nine flags removed.** `runtimeScheduler`, `runtimeFilter`, `deliberation`, `dynamicWorkflow`, `deltaOverlays`, `learningCandidates` and `resourcePolicy` had no production caller and are deleted with their tests. Their flags are gone from the default config: `decisionRuntime.scheduler`, `.context`, `.completion`, `.quality`, `.resourcePolicy`, `experiments.deliberation`, `experiments.dynamicWorkflow`, `learning.overlays`, `learning.candidates`. A config that still contains them loads without a warning; memory records written by the removed modules are still readable.
11
+ - **Fix: unapproved lesson proposals no longer appear in recall.** Proposals waiting for approval were stored as verified records and showed up in `ukit memory recall`. Recall now leaves them out until they are approved.
12
+ - **`ukit memory learn --git`: lessons from files that keep getting fixed.** Reads the commit history (it refuses a shallow clone), finds source files fixed repeatedly, and writes them as candidates only — nothing is promoted automatically, and a candidate expires after 90 days. `--dry-run` shows what would be written. Files that no longer exist are dropped. Back-test on this repository, where "the file was fixed again later" stands in for "the lesson was right" (small numbers): last 400 commits, threshold 2: 11 files flagged, 36% fixed again; threshold 3: 5 flagged, 80%; last 90 days, threshold 2: 2 flagged, both fixed again. Coverage is low (3–13% of the files fixed later). Reproduce with `node scripts/bench/learning-backtest.mjs` in the source repository. Retracting a lesson when its file changes was not tested.
13
+ - **`unic-decision` can screen borderline lesson candidates — off by default.** Registry key `learn.candidate-class.v1`, stage `decisionPlane.families.learn.stage` (`off` | `shadow` | on). It is asked one yes/no question per borderline candidate (at most 8, 2 s each) and can only downgrade one. Measured effect in the back-test: one question asked, one candidate dropped (36% → 40%). That is too little to turn it on by default.
14
+ - **Design fonts: five bundled, the rest on demand.** The `canvas-design` skill now ships five fonts (Instrument Serif, JetBrains Mono, Nothing You Could Do, Outfit, Tektur) with their licences. The others are fetched when wanted: `node .claude/skills/canvas-design/scripts/fetch-fonts.mjs --list`, then `<Family>` or `--all`. Files come from a pinned commit of `google/fonts` and are checked by SHA-256 before they are written. Fetched variable fonts are saved as `<Family>-Variable.ttf`. An existing install keeps the fonts it already has (read from the code, not run on an old install).
15
+ - **Index search: opt-in vector lane for plain-language questions.** Off unless you set `UKIT_INDEX_EMBED_URL` to an OpenAI-compatible embeddings endpoint (`…/v1` or `…/v1/embeddings`; optional `UKIT_INDEX_EMBED_MODEL`, `UKIT_INDEX_EMBED_KEY`). With no URL nothing runs and nothing leaves the machine. **Privacy:** building vectors sends one short descriptor per indexed file (path, symbol names, leading comment, at most 240 characters) to that endpoint, and each question sends the question text; the build command prints the endpoint host first, and `.env`, key and credential files are never sent. Build with `node .claude/ukit/index/embed-index.mjs` — an explicit command, never part of index build, refresh or any hook. Vectors are stored in `.cache/index/semantic.bin` (int8) and reused by content hash, so a rerun only embeds changed files. `ukit index query` and `query-index.mjs` use the lane only for plain-language questions (four words or more, no path, identifier or error text) whose keyword result is not already clear, wait at most 1.5 s for the endpoint, and fall back to the keyword result on any error. Files gone from the index are never returned. Measured with a local Qwen3-Embedding-4B endpoint (1,536 dimensions) on a sealed set of 39 questions never used for tuning (40 in 3.5.5; one Vietnamese question, `bv04`, was dropped because its only expected file, `resourcePolicy.js`, is deleted in this release; it was not a top-3 hit in 3.5.5. Without the lane, Vietnamese top 3 is 3/19 here against 4/20 in 3.5.5 because one other question moved from rank 3 to rank 4): answer in top 3 from 5 to 21, in top 10 from 9 to 32 (English 20 questions: top 3 2 → 11; Vietnamese 19 questions: top 3 3 → 10); top 1 from 3 to 11. Cost: about 655 ms per question against 59 ms without the lane (machine under load), a 3.7 MB cache for 2,424 files, and a first build of 666 s measured while the machine was short of memory; a later rerun embedded 14 changed files in 5 s. An earlier fusion setting scored higher on Vietnamese (top 3 13) and lower on English (top 3 4); the shipped one is the better total. Embedding file bodies instead of descriptors was tried and not shipped (over an hour to build on this endpoint). Tested against one endpoint and one model only; hooks never use the lane.
16
+
5
17
  ## 3.5.5 - 2026-11-15
6
18
 
7
19
  Module pages for memory, symbols for eight more languages, and a Vietnamese-to-code vocabulary for index search. Every number below was measured on this repository only. Finding a file from an ordinary question is still weak, and this entry says so with numbers.
@@ -56,22 +56,9 @@ classes:
56
56
  codex: { support: degraded, note: 'no session-start/stop hooks; resume record is advisory context, never auto-reinjected' }
57
57
  omp: { support: enforced, evidence: tests/hooks/reinjectContextHook.test.js }
58
58
  promotionEvidence: { stage: off, evaluatedAt: null, verdict: not-evaluated, evidenceRef: null }
59
- learning-overlays:
60
- hosts:
61
- claude-code: { support: enforced, evidence: tests/core/deltaOverlays.test.js }
62
- codex: { support: degraded, note: 'overlay approval gate lives in shared runtime; codex consumes rendered policy without a hook gate' }
63
- omp: { support: enforced, evidence: tests/core/deltaOverlays.test.js }
64
- promotionEvidence: { stage: off, evaluatedAt: null, verdict: not-evaluated, evidenceRef: null }
65
59
  advisory:
66
60
  description: stdout/prompt text the model is asked to respect (routes, suppress, budgets)
67
61
  hosts:
68
62
  claude-code: { support: advisory }
69
63
  codex: { support: advisory }
70
64
  omp: { support: advisory }
71
- mechanisms:
72
- experiment-flags:
73
- hosts:
74
- claude-code: { support: advisory }
75
- codex: { support: advisory }
76
- omp: { support: advisory }
77
- promotionEvidence: { stage: off, evaluatedAt: null, verdict: not-evaluated, evidenceRef: null }
@@ -1806,6 +1806,18 @@ items:
1806
1806
  type: config
1807
1807
  sourceTemplate: .claude/ukit/index/lib/index-core.mjs
1808
1808
  targetPath: .claude/ukit/index/lib/index-core.mjs
1809
+ requires:
1810
+ - ukit-index-semantic-lane-lib
1811
+ mergeStrategy: overwrite_with_backup
1812
+ variables: []
1813
+ enabledByDefault: true
1814
+ packs:
1815
+ - core
1816
+
1817
+ - id: ukit-index-semantic-lane-lib
1818
+ type: config
1819
+ sourceTemplate: .claude/ukit/index/lib/semantic-lane.mjs
1820
+ targetPath: .claude/ukit/index/lib/semantic-lane.mjs
1809
1821
  requires: []
1810
1822
  mergeStrategy: overwrite_with_backup
1811
1823
  variables: []
@@ -1813,6 +1825,19 @@ items:
1813
1825
  packs:
1814
1826
  - core
1815
1827
 
1828
+ - id: ukit-index-embed-script
1829
+ type: config
1830
+ sourceTemplate: .claude/ukit/index/embed-index.mjs
1831
+ targetPath: .claude/ukit/index/embed-index.mjs
1832
+ requires:
1833
+ - ukit-index-core-lib
1834
+ - ukit-index-semantic-lane-lib
1835
+ mergeStrategy: overwrite_with_backup
1836
+ variables: []
1837
+ enabledByDefault: true
1838
+ packs:
1839
+ - core
1840
+
1816
1841
  - id: ukit-index-build-script
1817
1842
  type: config
1818
1843
  sourceTemplate: .claude/ukit/index/build-index.mjs
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ngockhoale/ukit",
3
- "version": "3.5.5",
3
+ "version": "3.5.6",
4
4
  "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -63,11 +63,6 @@
63
63
  "!src/core/agentRuntime/runtimeSupport.js",
64
64
  "!src/core/agentRuntime/completionGate.js",
65
65
  "!src/core/agentRuntime/qualityComparison.js",
66
- "!src/core/agentRuntime/resourcePolicy.js",
67
- "!src/core/memory/deltaOverlays.js",
68
- "!src/core/memory/learningCandidates.js",
69
- "!src/core/experiments/dynamicWorkflow.js",
70
- "!src/core/experiments/deliberation.js",
71
66
  "!src/core/observability/evaluation/scorecard.js",
72
67
  "!src/core/observability/evaluation/replay.js",
73
68
  "!src/core/observability/emit/sessionBoot.js",
@@ -83,8 +78,6 @@
83
78
  "!src/index/contextPack.js",
84
79
  "!src/index/sensitivePath.js",
85
80
  "!src/decision/reviewVerdict.js",
86
- "!src/decision/runtimeScheduler.js",
87
- "!src/decision/runtimeFilter.js",
88
81
  "!scripts/bench/**",
89
82
  "scripts/bench/decision-runtime-metrics.mjs",
90
83
  "!scripts/perf/**",
@@ -70,6 +70,7 @@ export async function runIndexTools({ projectRoot, argv = [] }) {
70
70
  rootDir: projectRoot,
71
71
  query,
72
72
  limit: Number.isNaN(limit) ? 5 : limit,
73
+ semantic: true,
73
74
  });
74
75
 
75
76
  const contentLaneNotice = results.contentLaneTruncated?.length
@@ -25,7 +25,7 @@ import { redactWritePayload } from '../../core/memory/writeGuard.js';
25
25
  import { checkProposalText } from '../../core/memory/writeGate.js';
26
26
  import { deletePromptCacheEntries } from '../../core/token/index.js';
27
27
  import { expand, getContextInjection, search } from '../../core/memory/retrieval.js';
28
- import { inspectRuntimeConfig } from '../../core/runtimeConfig.js';
28
+ import { inspectRuntimeConfig, loadRuntimeConfig } from '../../core/runtimeConfig.js';
29
29
  import { buildRuntimePaths } from '../../core/runtimePaths.js';
30
30
  import { buildUserPaths } from '../../core/userPaths.js';
31
31
  import { pathExists } from '../../core/fileOps.js';
@@ -854,7 +854,12 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
854
854
 
855
855
  if (subcommand === 'learn') {
856
856
  const applyFlag = rest.includes('--apply');
857
- const knownFlags = new Set(['--apply']);
857
+ const gitFlag = rest.includes('--git');
858
+ // --dry-run is an explicit no-op alias of the default (preview only).
859
+ if (applyFlag && rest.includes('--dry-run')) {
860
+ throw new Error('memory learn: --dry-run and --apply are mutually exclusive');
861
+ }
862
+ const knownFlags = new Set(['--apply', '--git', '--dry-run']);
858
863
  const minFlag = extractFlag(rest, '--min');
859
864
  const projectFlag = extractFlag(minFlag.rest, '--project');
860
865
  for (const arg of projectFlag.rest) {
@@ -868,11 +873,31 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
868
873
  }
869
874
  const projectId = projectFlag.value ?? (await detectProjectContext(projectRoot, { homeDir })).project.name;
870
875
 
871
- const { proposeFromPatterns } = await import('../../learning/patternProposals.js');
876
+ const { proposeFromPatterns, proposeFromReedits } = await import('../../learning/patternProposals.js');
877
+ // Decision plane (unic-decision) only refines the ambiguous cases, downgrade-only;
878
+ // stage off (default) or an unreachable provider leaves the rule result.
879
+ const { resolveLessonStage, createLessonClient } = await import('../../learning/lessonClass.js');
880
+ const learnConfig = await loadRuntimeConfig(projectRoot, { homeDir }).catch(() => null);
881
+ const stage = resolveLessonStage(learnConfig);
882
+ const client = createLessonClient({ config: learnConfig, projectRoot, homeDir });
872
883
  const result = await proposeFromPatterns(projectRoot, projectId, {
873
884
  minCount,
874
885
  dryRun: !applyFlag,
886
+ client,
887
+ stage,
875
888
  });
889
+ if (gitFlag) {
890
+ // Explicit command only: spawns git, so never part of a hook path.
891
+ const { mineGitReedits } = await import('../../learning/reeditMiner.js');
892
+ const reedits = await mineGitReedits(projectRoot, { minFixes: minCount ?? 3 });
893
+ const git = await proposeFromReedits(projectRoot, projectId, { reedits, dryRun: !applyFlag, client, stage });
894
+ if (git.decision && result.decision) {
895
+ for (const k of ['asked', 'answered', 'changed']) result.decision[k] += git.decision[k];
896
+ }
897
+ result.proposed.push(...git.proposed);
898
+ result.eligible += git.proposed.filter((p) => p.status !== 'skipped').length;
899
+ if (git.error && !result.error) result.error = git.error;
900
+ }
876
901
  if (result.error) {
877
902
  console.log(`[UKit] memory learn: ${result.error}`);
878
903
  }
@@ -893,6 +918,10 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
893
918
  console.log(` [${entry.status}] ${entry.signature} — ${entry.text}`);
894
919
  }
895
920
  console.log(`[UKit] memory learn: proposed ${proposed}, duplicate ${duplicates}, skipped ${skipped} for project ${projectId}.`);
921
+ if (result.decision && result.decision.stage !== 'off') {
922
+ const d = result.decision;
923
+ console.log(`[UKit] decision plane (stage ${d.stage}): asked ${d.asked}, answered ${d.answered}, changed ${d.changed}${d.answered === 0 && d.asked > 0 ? ' (provider gave no valid answer; rule results kept)' : ''}.`);
924
+ }
896
925
  if (proposed > 0) {
897
926
  console.log('[UKit] Review with `ukit memory list --pending`, then `ukit memory approve <id>`.');
898
927
  }
@@ -1128,7 +1157,7 @@ export function printMemoryHelp() {
1128
1157
  console.log(' propose "<text>" [--category <name>] [--project <id>] Propose a project convention for human approval');
1129
1158
  console.log(' approve <id> [--project <id>] Approve a pending pattern candidate into project conventions');
1130
1159
  console.log(' reject <id> [--project <id>] Reject a pending pattern candidate');
1131
- console.log(' learn [--apply] [--min <n>] [--project <id>] Propose pending candidates from mined failure patterns (dry-run by default)');
1160
+ console.log(' learn [--apply|--dry-run] [--git] [--min <n>] [--project <id>] Propose pending candidates from failure patterns, and with --git from files that keep needing fix commits (preview is the default; --apply writes)');
1132
1161
  console.log(' promote [--dry-run] Render approved rules/procedures into the ## ukit-learned block in docs/MEMORY.md');
1133
1162
  console.log(' episode [--dry-run] [--session <id>|--start] Write a session episode record from the exec-ledger');
1134
1163
  console.log(' topic build <dir>|list|show <dir>|check Module pages under docs/memory/topics (generated skeleton; stale when the directory changed)');
@@ -105,95 +105,48 @@ export async function pruneOldBackups(backupRoot, {
105
105
  return { scanned: files.length, removed };
106
106
  }
107
107
 
108
- // Writes the new template beside an owner-edited managed file. Returns the recorded
109
- // sidecar hash when UKit created/refreshed it, or null when it was preserved as owner
110
- // content. Absent sidecar → exclusive create (race-safe: an appearing owner file is
111
- // never overwritten). Existing sidecar → update ONLY when install.json recorded its
112
- // current hash; otherwise preserve and report a conflict.
113
- async function writeManagedTemplateSidecar(sidecarPath, content, recordedSidecarHash) {
114
- const bytes = Buffer.isBuffer(content) ? content : Buffer.from(content, 'utf8');
115
- const nextHash = sha256Hex(bytes);
116
- const state = await readSidecarState(sidecarPath);
117
-
118
- if (state.state === 'absent') {
119
- try {
120
- await writeFileExclusive(sidecarPath, content);
121
- return nextHash;
122
- } catch (error) {
123
- if (error?.code === 'EEXIST') {
124
- // Lost the race to an owner file — never overwrite it.
125
- console.warn(`[UKit] Warning: ${sidecarPath} appeared during install; left untouched (possible owner content).`);
126
- return null;
127
- }
128
- throw error;
129
- }
130
- }
131
- if (state.state === 'file' && typeof recordedSidecarHash === 'string' && recordedSidecarHash === state.hash) {
132
- if (state.hash === nextHash) {
133
- return nextHash; // already the current template — nothing to write
134
- }
135
- // Re-verify immediately before the rename: an owner edit landing between the
136
- // first read and this write must not be silently replaced (TOCTOU window).
137
- const recheck = await readSidecarState(sidecarPath);
138
- if (recheck.state !== 'file' || recheck.hash !== recordedSidecarHash) {
139
- console.warn(`[UKit] Warning: ${sidecarPath} changed during install; left untouched (possible owner content).`);
140
- return null;
141
- }
142
- await writeFileAtomic(sidecarPath, content);
143
- return nextHash;
144
- }
145
- // Owner-authored, owner-modified, symlink, or unreadable sidecar: keep it.
146
- console.warn(
147
- `[UKit] Warning: ${sidecarPath} is not UKit-managed (${state.state === 'file' ? 'content changed since UKit wrote it' : state.state}); preserved. Review it manually.`,
148
- );
149
- return null;
150
- }
151
-
152
- // Removes a sidecar only when install.json recorded the hash that is on disk now.
153
- // Unrecorded/owner-modified/symlink sidecars are preserved and reported.
154
- async function removeManagedTemplateSidecar(sidecarPath, recordedSidecarHash) {
108
+ // Legacy `.ukit-new` cleanup (sidecars are no longer written). A leftover is removed only when
109
+ // UKit can attribute it: install.json recorded its hash, or its bytes equal a UKit template
110
+ // render for that file. Anything else is left in place and reported once.
111
+ async function removeLegacySidecar(sidecarPath, recordedSidecarHash, templateRender) {
155
112
  const state = await readSidecarState(sidecarPath);
156
113
  if (state.state === 'absent') {
157
114
  return true;
158
115
  }
159
- if (state.state === 'file' && typeof recordedSidecarHash === 'string' && recordedSidecarHash === state.hash) {
116
+ const templateHash = templateRender === undefined || templateRender === null
117
+ ? null
118
+ : sha256Hex(Buffer.isBuffer(templateRender) ? templateRender : Buffer.from(templateRender, 'utf8'));
119
+ const recorded = typeof recordedSidecarHash === 'string' && recordedSidecarHash === state.hash;
120
+ if (state.state === 'file' && (recorded || (templateHash !== null && templateHash === state.hash))) {
160
121
  await fs.rm(sidecarPath, { force: true });
161
122
  return true;
162
123
  }
163
124
  console.warn(
164
- `[UKit] Warning: keeping ${sidecarPath} — ${state.state === 'file' ? 'its content no longer matches the UKit-written copy' : `it is ${state.state}`}; remove it manually if it is no longer needed.`,
125
+ `[UKit] Note: ${sidecarPath} is a leftover from an older UKit but its content is not UKit's own; left in place. Delete it when no longer needed.`,
165
126
  );
166
127
  return false;
167
128
  }
168
129
 
169
- export async function applyDiffResults(diffResults, { backupRoot, projectRoot, recordedSidecarHashes = null, sidecarHashes = {} } = {}) {
130
+ export async function applyDiffResults(diffResults, { backupRoot, projectRoot, recordedSidecarHashes = null, packageVersion = null } = {}) {
170
131
  const writes = [];
171
132
  let skippedUpdates = 0;
172
133
  const skippedByAction = { create: 0, update: 0 };
173
134
 
174
135
  for (const entry of diffResults) {
175
- // CR-13: owner-edited managed template — keep the file, write the new template beside it.
176
- // Provenance is the recorded sidecar hash, never the filename (see writeManagedTemplateSidecar).
177
- if (entry.action === 'sidecar') {
136
+ // Managed templates: clean up attributable `.ukit-new` leftovers from older versions, and
137
+ // surface section notices (the merge itself was computed in diffPlan).
138
+ if (entry.mergeStrategy === 'managed_template' && entry.type !== 'link') {
178
139
  const sidecarPath = `${entry.targetPath}.ukit-new`;
179
- const recorded = recordedSidecarHashes?.get(sidecarPath) ?? null;
180
- const writtenHash = await writeManagedTemplateSidecar(sidecarPath, entry.renderedContent, recorded);
181
- if (writtenHash) {
182
- sidecarHashes[sidecarPath] = writtenHash;
183
- console.log(`[UKit] Kept your edited ${path.basename(entry.targetPath)} unchanged; the new UKit template is at ${path.basename(sidecarPath)} — review and merge it.`);
184
- } else {
185
- console.log(`[UKit] Kept your edited ${path.basename(entry.targetPath)} unchanged; an owner file already exists at ${path.basename(sidecarPath)} and was preserved.`);
186
- }
187
- skippedUpdates += 1;
188
- skippedByAction.update += 1;
189
- continue;
190
- }
191
- if (entry.action === 'unchanged' && entry.removeSidecar) {
192
- // Only a UKit-generated, unmodified sidecar is cleaned up; owner files stay.
193
- await removeManagedTemplateSidecar(
194
- `${entry.targetPath}.ukit-new`,
195
- recordedSidecarHashes?.get(`${entry.targetPath}.ukit-new`) ?? null,
140
+ await removeLegacySidecar(
141
+ sidecarPath,
142
+ recordedSidecarHashes?.get(sidecarPath) ?? null,
143
+ entry.templateRender ?? entry.renderedContent,
196
144
  );
145
+ for (const notice of entry.mergeNotices ?? []) {
146
+ console.log(
147
+ `[UKit] ${path.basename(entry.targetPath)}: kept your edited section "${notice.heading}"; the UKit template for it changed${packageVersion ? ` in ${packageVersion}` : ''}.`,
148
+ );
149
+ }
197
150
  }
198
151
  if (entry.action !== 'create' && entry.action !== 'update') {
199
152
  continue;
@@ -243,7 +196,7 @@ export async function applyDiffResults(diffResults, { backupRoot, projectRoot, r
243
196
  // Back up the existing file before overwriting
244
197
  if (
245
198
  entry.action === 'update' &&
246
- (entry.mergeStrategy === 'overwrite_with_backup' || entry.mergeStrategy === 'merge_env_overwrite_with_backup') &&
199
+ (entry.mergeStrategy === 'overwrite_with_backup' || entry.mergeStrategy === 'merge_env_overwrite_with_backup' || entry.mergeStrategy === 'managed_template') &&
247
200
  backupRoot &&
248
201
  projectRoot
249
202
  ) {
@@ -333,5 +286,5 @@ export async function applyDiffResults(diffResults, { backupRoot, projectRoot, r
333
286
  });
334
287
  }
335
288
 
336
- return { writes, skippedUpdates, skippedByAction, sidecarHashes };
289
+ return { writes, skippedUpdates, skippedByAction };
337
290
  }
@@ -3,6 +3,7 @@ import fs from 'node:fs/promises';
3
3
  import YAML from 'yaml';
4
4
  import { isSymlinkTo } from './fileOps.js';
5
5
  import { GATEWAY_RESILIENCE_ENV_DEFAULTS } from './gatewayResilienceEnv.js';
6
+ import { mergeManagedTemplate, sectionHashes } from './managedTemplateMerge.js';
6
7
  import { isOmpConfigTarget, mergeOmpConfig } from './ompConfigMerge.js';
7
8
  import { mergeOmpProjectConfig } from './ompProjectConfig.js';
8
9
  import { mergeRuntimeConfigText } from './runtimeConfigMerge.js';
@@ -15,12 +16,13 @@ const GATEWAY_RESILIENCE_KEYS = new Set(Object.keys(GATEWAY_RESILIENCE_ENV_DEFAU
15
16
  // look identical to "missing" and the apply step would either overwrite the
16
17
  // live file atomically with no .bak (W2-C4) or crash mid-install on a 'wx'
17
18
  // create (W2-C6). Unreadable targets get a non-write action instead.
18
- // CR-13: managed AI_HANDOFF templates. Refresh only when the installed file is still the
19
+ // CR-13: managed AI_HANDOFF templates. Replace only when the installed file is still the
19
20
  // content UKit last recorded (its sha256 in install.json); an owner-edited or legacy
20
- // (no recorded hash) file stays byte-identical and the new template goes to a sidecar.
21
+ // (no recorded hash) file is merged by `## ` section (see managedTemplateMerge.js) — no
22
+ // sidecar file is ever written.
21
23
  const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');
22
24
 
23
- async function resolveManagedTemplateAction(entry, recordedHashes) {
25
+ async function resolveManagedTemplateAction(entry, recordedHashes, recordedSections = null) {
24
26
  const template = Buffer.isBuffer(entry.renderedContent) ? entry.renderedContent : Buffer.from(entry.renderedContent, 'utf8');
25
27
  const templateHash = sha256(template);
26
28
 
@@ -42,20 +44,43 @@ async function resolveManagedTemplateAction(entry, recordedHashes) {
42
44
  const read = await readFileOrStatus(entry.targetPath, null);
43
45
  if (read.status === 'missing') {
44
46
  // ONLY a confirmed absence permits create; unreadable must never overwrite.
45
- return { ...entry, exists: false, action: 'create', existingContent: null, managedHash: templateHash };
47
+ return {
48
+ ...entry, exists: false, action: 'create', existingContent: null, managedHash: templateHash,
49
+ managedSections: sectionHashes(template.toString('utf8'), { markdown: /\.md$/i.test(entry.targetPath) }),
50
+ };
46
51
  }
47
52
  if (read.status !== 'ok') {
48
53
  return conflictResult(entry, read.error);
49
54
  }
50
55
  const installed = read.content;
51
56
  const installedHash = sha256(installed);
57
+ const markdown = /\.md$/i.test(entry.targetPath);
58
+ const templateText = template.toString('utf8');
59
+ const managedSections = sectionHashes(templateText, { markdown });
52
60
  if (installedHash === templateHash) {
53
- return { ...entry, exists: true, action: 'unchanged', existingContent: installed, managedHash: templateHash, removeSidecar: true };
61
+ return { ...entry, exists: true, action: 'unchanged', existingContent: installed, managedHash: templateHash, managedSections };
54
62
  }
55
63
  if (recordedHashes?.get(entry.targetPath) === installedHash) {
56
- return { ...entry, exists: true, action: 'update', existingContent: installed, managedHash: templateHash, removeSidecar: true };
64
+ return { ...entry, exists: true, action: 'update', existingContent: installed, managedHash: templateHash, managedSections };
65
+ }
66
+ // Owner-edited (or legacy, no recorded hash): merge by section, never a sidecar.
67
+ const merged = mergeManagedTemplate({
68
+ existing: installed.toString('utf8'),
69
+ template: templateText,
70
+ recorded: recordedSections?.get(entry.targetPath) ?? null,
71
+ markdown,
72
+ });
73
+ const base = { ...entry, exists: true, existingContent: installed, managedSections: merged.sections, mergeNotices: merged.notices };
74
+ if (!merged.changed) {
75
+ return { ...base, action: 'unchanged', managedHash: null };
57
76
  }
58
- return { ...entry, exists: true, action: 'sidecar', existingContent: installed, managedHash: null };
77
+ const mergedBuf = Buffer.from(merged.content, 'utf8');
78
+ return {
79
+ ...base,
80
+ action: 'update',
81
+ renderedContent: mergedBuf,
82
+ managedHash: sha256(mergedBuf) === templateHash ? templateHash : null,
83
+ };
59
84
  }
60
85
 
61
86
  async function readFileOrStatus(filePath, encoding = 'utf8') {
@@ -402,7 +427,7 @@ async function resolveSkipEntryAction(entry, ompOwnership = null) {
402
427
  return resolveFileAction(entry, read.content, ompOwnership);
403
428
  }
404
429
 
405
- export async function diffInstallPlan(plan, { ompOwnership = null, settingsMigration = null, recordedManagedHashes = null } = {}) {
430
+ export async function diffInstallPlan(plan, { ompOwnership = null, settingsMigration = null, recordedManagedHashes = null, recordedManagedSections = null } = {}) {
406
431
  // Check all entries in parallel
407
432
  const results = await Promise.all(
408
433
  plan.entries.map(async (entry) => {
@@ -416,7 +441,11 @@ export async function diffInstallPlan(plan, { ompOwnership = null, settingsMigra
416
441
  }
417
442
 
418
443
  if (entry.mergeStrategy === 'managed_template') {
419
- return resolveManagedTemplateAction(entry, recordedManagedHashes);
444
+ // templateRender keeps the pristine template bytes (renderedContent may become the merge result).
445
+ return {
446
+ ...(await resolveManagedTemplateAction(entry, recordedManagedHashes, recordedManagedSections)),
447
+ templateRender: entry.renderedContent,
448
+ };
420
449
  }
421
450
 
422
451
  const read = await readFileOrStatus(
@@ -0,0 +1,146 @@
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
+ export function mergeManagedTemplate({ existing, template, recorded = null, markdown = true }) {
72
+ sectioned = markdown;
73
+ const bom = existing.startsWith('');
74
+ const eol = existing.includes('\r\n') ? '\r\n' : '\n';
75
+ const existingLf = normalizeEol(existing.replace(/^/, ''));
76
+ const templateSections = parseSections(normalizeEol(template.replace(/^/, '')));
77
+ const tplByKey = new Map(templateSections.map((s) => [s.key, s]));
78
+ const sections = Object.fromEntries(templateSections.map((s) => [s.key, hashOf(s.raw)]));
79
+ const notices = [];
80
+
81
+ const parts = [];
82
+ const existingSections = parseSections(existingLf);
83
+ let removedTail = null;
84
+ for (const [idx, e] of existingSections.entries()) {
85
+ const t = tplByKey.get(e.key);
86
+ const base = recorded?.[e.key];
87
+ if (e.suspect) {
88
+ parts.push({ key: e.key, raw: e.raw });
89
+ } else if (t) {
90
+ const eh = hashOf(e.raw);
91
+ const th = sections[e.key];
92
+ if (eh === th) {
93
+ parts.push({ key: e.key, raw: e.raw });
94
+ } else if (typeof base === 'string' && eh === base) {
95
+ parts.push({ key: e.key, raw: t.raw.trimEnd() + trailingWs(e.raw) });
96
+ } else {
97
+ // Owner-changed (or no baseline): keep. Notice only when the template moved since the record.
98
+ if (typeof base === 'string' && th !== base) notices.push({ heading: e.key || '(preamble)' });
99
+ parts.push({ key: e.key, raw: e.raw });
100
+ }
101
+ } else if (typeof base === 'string' && hashOf(e.raw) === base) {
102
+ // Upstream removed it and the owner never changed it.
103
+ if (idx === existingSections.length - 1) removedTail = trailingWs(e.raw);
104
+ } else {
105
+ parts.push({ key: e.key, raw: e.raw });
106
+ }
107
+ }
108
+
109
+ if (removedTail !== null && parts.length > 0) {
110
+ const last = parts[parts.length - 1];
111
+ last.raw = last.raw.trimEnd() + removedTail;
112
+ }
113
+
114
+ const have = new Set(parts.map((p) => p.key));
115
+ // Idempotence guard: a template section whose exact heading line already appears as ANY line
116
+ // of the existing text (fenced or not) is never appended again. Fence pairing in an
117
+ // owner-edited file is ambiguous: an owner's unclosed opener pairs with the first fence of a
118
+ // template-added section's own code block, shifting every later pairing, so headings that sit
119
+ // "inside closed fences" cannot be trusted to be quoted text. Fenced lines must therefore
120
+ // count, otherwise the file grows on every run. Limit: a heading the owner merely quoted in a
121
+ // code block blocks the real template section of that name.
122
+ const existingLines = new Set(existingLf.split('\n').map((l) => l.trimEnd()));
123
+ templateSections.forEach((t, i) => {
124
+ if (have.has(t.key)) return;
125
+ if (t.key !== '' && existingLines.has(t.key.replace(/#\d+$/, ''))) return;
126
+ let at = parts.length;
127
+ for (let j = i - 1; j >= 0; j -= 1) {
128
+ const idx = parts.findIndex((p) => p.key === templateSections[j].key);
129
+ if (idx !== -1) { at = idx + 1; break; }
130
+ }
131
+ parts.splice(at, 0, { key: t.key, raw: t.raw, added: true });
132
+ have.add(t.key);
133
+ });
134
+
135
+ parts.forEach((p, i) => {
136
+ if (!p.added) return;
137
+ if (i < parts.length - 1 && !p.raw.endsWith('\n\n')) p.raw = `${p.raw.trimEnd()}\n\n`;
138
+ const prev = parts[i - 1];
139
+ if (prev && prev.raw !== '' && !prev.raw.endsWith('\n\n')) prev.raw = `${prev.raw.trimEnd()}\n\n`;
140
+ });
141
+
142
+ const mergedLf = parts.map((p) => p.raw).join('');
143
+ if (mergedLf === existingLf) return { content: existing, changed: false, notices, sections };
144
+ const body = eol === '\r\n' ? mergedLf.replace(/\n/g, '\r\n') : mergedLf;
145
+ return { content: (bom ? '' : '') + body, changed: true, notices, sections };
146
+ }
@@ -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) {