@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.
- package/CHANGELOG.md +25 -0
- package/manifests/engineConformance.yaml +0 -13
- package/manifests/platform.full.yaml +25 -0
- package/package.json +1 -8
- package/src/cli/commands/indexTools.js +1 -0
- package/src/cli/commands/memory.js +33 -4
- package/src/core/applyPlan.js +37 -72
- package/src/core/diffPlan.js +39 -9
- package/src/core/managedTemplateMerge.js +231 -0
- package/src/core/memory/memoryFlags.js +5 -6
- package/src/core/memory/policy.js +5 -0
- package/src/core/memory/store.js +17 -0
- package/src/core/metadata.js +12 -8
- package/src/core/runInstallPipeline.js +16 -10
- package/src/core/runtimeConfig.js +14 -83
- package/src/core/uninstall.js +8 -1
- package/src/decision/registry.js +17 -17
- package/src/decision/runtimeDecide.js +5 -5
- package/src/index/playbookRegistry.js +6 -1
- package/src/index/queryIndex.js +41 -4
- package/src/index/routeResolver.js +2 -2
- package/src/index/semanticLane.js +277 -0
- package/src/learning/lessonClass.js +110 -0
- package/src/learning/patternProposals.js +111 -7
- package/src/learning/reeditMiner.js +104 -0
- package/src/learning/selfImprove.js +9 -1
- package/template_project/.claude/hooks/skill-router.sh +273 -5
- package/template_project/.claude/skills/canvas-design/SKILL.md +2 -2
- package/template_project/.claude/skills/canvas-design/canvas-fonts/{InstrumentSans-OFL.txt → InstrumentSerif-OFL.txt} +3 -3
- package/template_project/.claude/skills/canvas-design/scripts/fetch-fonts.mjs +148 -0
- package/template_project/.claude/ukit/index/embed-index.mjs +26 -0
- package/template_project/.claude/ukit/index/lib/index-core.mjs +43 -4
- package/template_project/.claude/ukit/index/lib/semantic-lane.mjs +277 -0
- package/template_project/.claude/ukit/index/playbook-registry.mjs +6 -1
- package/template_project/.claude/ukit/index/publication-intent.mjs +159 -1
- package/template_project/.claude/ukit/index/query-index.mjs +9 -1
- package/template_project/.claude/ukit/index/route-resolver.mjs +2 -2
- package/template_project/.claude/ukit/index/route-task.mjs +14 -3
- package/template_project/.claude/ukit/runtime/memory-policy.mjs +5 -0
- package/template_project/.claude/ukit/runtime/stop-coordinator.mjs +12 -1
- package/template_project/ukit/storage/config.json +0 -32
- package/template_project/.claude/skills/canvas-design/canvas-fonts/BricolageGrotesque-Bold.ttf +0 -0
- package/template_project/.claude/skills/canvas-design/canvas-fonts/BricolageGrotesque-OFL.txt +0 -93
- package/template_project/.claude/skills/canvas-design/canvas-fonts/BricolageGrotesque-Regular.ttf +0 -0
- package/template_project/.claude/skills/canvas-design/canvas-fonts/InstrumentSans-Bold.ttf +0 -0
- package/template_project/.claude/skills/canvas-design/canvas-fonts/InstrumentSans-BoldItalic.ttf +0 -0
- package/template_project/.claude/skills/canvas-design/canvas-fonts/InstrumentSans-Italic.ttf +0 -0
- package/template_project/.claude/skills/canvas-design/canvas-fonts/InstrumentSans-Regular.ttf +0 -0
- package/template_project/.claude/skills/canvas-design/canvas-fonts/InstrumentSerif-Italic.ttf +0 -0
- package/template_project/.claude/skills/canvas-design/canvas-fonts/JetBrainsMono-Bold.ttf +0 -0
- package/template_project/.claude/skills/canvas-design/canvas-fonts/Lora-Bold.ttf +0 -0
- package/template_project/.claude/skills/canvas-design/canvas-fonts/Lora-BoldItalic.ttf +0 -0
- package/template_project/.claude/skills/canvas-design/canvas-fonts/Lora-Italic.ttf +0 -0
- package/template_project/.claude/skills/canvas-design/canvas-fonts/Lora-OFL.txt +0 -93
- package/template_project/.claude/skills/canvas-design/canvas-fonts/Lora-Regular.ttf +0 -0
- package/template_project/.claude/skills/canvas-design/canvas-fonts/Outfit-Bold.ttf +0 -0
- package/template_project/.claude/skills/canvas-design/canvas-fonts/Tektur-Medium.ttf +0 -0
- package/template_project/.claude/skills/canvas-design/canvas-fonts/YoungSerif-OFL.txt +0 -93
- package/template_project/.claude/skills/canvas-design/canvas-fonts/YoungSerif-Regular.ttf +0 -0
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,31 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to UKit are documented here.
|
|
4
4
|
|
|
5
|
+
## 3.5.7 - 2026-11-16
|
|
6
|
+
|
|
7
|
+
Bug-fix release: eight defects found while shipping 3.5.6, each fixed at its cause. No host (Claude Code, Codex, omp) was run live and nothing was run on Windows; the checks are unit tests and real hook processes on this repository.
|
|
8
|
+
|
|
9
|
+
- **Fix: a message from a teammate or subagent is no longer treated as a new task from you.** In Claude Code, a message delivered from another agent of the same session was routed like an owner prompt: it minted a new task and the completion gate then demanded edits and test runs for it. The router now exempts such a message only on the host's own delivery record: a transcript entry of the current turn and the same session that Claude Code stamped as a peer delivery and that carries exactly the delivered block (with at most the host's banner line before it and its one-line trailer after it). For the router, the text of a message is never proof on its own: the same block pasted by you, a record from another session or an earlier turn, or a block with any words of yours around it is routed as your prompt. A peer record stamped in a different session no longer exempts a prompt (in 3.5.6 it could). The stop coordinator never treats an entry the host stamped as typed by you as a peer message, whatever its text; host-stamped peer deliveries were already skipped. Entries without host stamps (older Claude Code versions) are still recognised there by their message envelope. Limits: Claude Code only, so omp and Codex behave as in 3.5.6. The hook-input shape was inferred from the recorded prompt fingerprints of seven single-block deliveries, not from a live capture. Any other shape (several blocks, changed trailer wording, a record outside the transcript tail) falls back to routing the prompt as yours. Teammate messages that Claude Code injects without a stamped delivery record never run the prompt hook and were never affected; only the stamped deliveries did.
|
|
10
|
+
- **Fix: stating a rule about bugs is not an order to fix one.** A prompt such as "luôn nhớ: có bug là phải fix ngay" or "always remember: any bug must be fixed at its root cause" names no defect, yet it was routed as a bug fix and owed a reproduction and a root cause. It is now advisory. The rule is deliberately narrow: only a prompt made entirely of the recognised generic rule sentences is advisory. A prompt that names a target, a symptom or a specific bug, or adds any other request in any language ("…, fix cái login đi", "… Trang thanh toán không chạy được", "… Fix checkout") stays a bug fix with its full evidence duty, and a task already in progress keeps its own duties. A rule worded differently from the recognised sentences is treated as a bug fix too (more evidence asked, never less). One limit: Vietnamese typed without accents is read as the rule wording, so an unaccented sentence that spells exactly a rule sentence (e.g. "thay bug la phai fix ngay", which could also mean "replace the bug…") is taken as the rule; with accents the two are told apart.
|
|
11
|
+
- **Fix: managed-template merge — two limits of 3.5.6 removed.** (1) A heading you only quoted inside a code block no longer stops the real template section of that name from being added. (2) A section you deleted stays deleted. What decides both is now the record of what UKit wrote, not a scan of the text. The record written by 3.5.6 cannot be trusted for this (it listed sections it had skipped), so on the first install after upgrading — from 3.5.6 or from anything older — every template section missing from your file is added once, including one you had deleted on purpose; delete it again and it stays gone. One case is held back: if your file has a code fence that is never closed, new sections are not added and install names them once; close the fence and the next install adds them. Still true from 3.5.6: on the first install after upgrading from 3.5.5 or older, a section that differs from the current template is kept as if you had edited it. A project that goes back to 3.5.6 reads the new record without change (tested against the shipped 3.5.6 code). **Correction to the 3.5.6 notes:** they described `docs/AI_HANDOFF/queued/README.md` copies older than 3.4.66 ending up with renamed sections side by side. No shipped template ever had the old headings (the file first shipped in 3.4.66 with the current ones), so that case does not exist. The merge can now follow a heading rename (an untouched section is renamed in place; an edited one is kept and reported once), but no rename is registered in this release.
|
|
12
|
+
- **Fix: index search with the vector lane on printed scores out of order.** The list was ordered by the fused rank but printed the older lexical score, so a lower line could show a higher number. `score` is now the value the list is sorted by; the lexical score is kept as `lexicalScore`. With the lane off the output is byte-identical to 3.5.6.
|
|
13
|
+
- **Fix: a decision call that ran out of time was logged as "could not start".** When the local decision adapter was killed at its time limit (seen under heavy CPU load), the decision log said `adapter-spawn-failed`; it now says `deadline-exceeded`. A non-zero exit or a missing adapter still says `adapter-spawn-failed`. Routing was never affected: the built-in fallback decided in both cases.
|
|
14
|
+
- **Fix: a very long prompt could leave the previous task in force.** The prompt hook stops itself at its time limit so it can never hang the host. On a long prompt (about 15,000 characters) on a busy machine the analysis alone took longer than that limit, so the hook ended before recording the new task and the previous task's duties stayed live. The cause was repeated work: the same text was analysed 20 times and one sub-check ran 295 times. Results are now reused within the run (identical output on 13,844 compared strings); in one development measurement the same prompt went from about 5.2 s to about 2.0 s under the same load — a single measurement, not a benchmark. The time limit itself is unchanged.
|
|
15
|
+
- **Fix: a prompt hook that runs out of time no longer leaves the previous task looking current.** If the hook still reaches its time limit after a new prompt of yours was accepted but before its task was recorded, it now records that the task switch did not finish. The stop check then blocks with "route publication incomplete" instead of judging your new prompt by the previous task's duties (or printing nothing), and the next prompt starts a new task. A standing stop order of yours is kept. Limits: the record is written only for a new prompt of yours that starts a task while a task that still owes evidence is current, outside a handoff run (a short reply that keeps the current task is left as it was); the time limit can only act between two steps of the hook, so if the host kills the hook during one long uninterrupted step, nothing is recorded and the behaviour is as in 3.5.6; if another write holds the state at that moment the record is skipped. Hint lines printed after a task is recorded can still be cut off between whole lines by a kill, as before.
|
|
16
|
+
- **Test fix: the router latency test measured machine load, not the hook.** The failure seen during the 3.5.6 release check was reproduced: with CPU load applied to only one of the two measured blocks, the old test fails (113 ms and 522 ms against a 100 ms limit) while every receipt still arrives. The paired test shipped in 3.5.6 holds under the same load (19–29 ms); its time limit is raised so heavy load cannot end it before its checks run. No check was loosened. Three more router tests had a time limit that measured the machine: two stopped the hook after 1 s to detect a hang (a healthy hook needs up to 0.9 s on a busy machine; a hook with the defect never exits, so the limit is now 10 s), and one killed the hook after a fixed 0.5 s and then expected its early record on disk (it now waits for the record, then kills). Each was shown to still fail on a deliberately broken hook.
|
|
17
|
+
|
|
18
|
+
## 3.5.6 - 2026-11-15
|
|
19
|
+
|
|
20
|
+
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.
|
|
21
|
+
|
|
22
|
+
- **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.
|
|
23
|
+
- **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.
|
|
24
|
+
- **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.
|
|
25
|
+
- **`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.
|
|
26
|
+
- **`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.
|
|
27
|
+
- **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).
|
|
28
|
+
- **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.
|
|
29
|
+
|
|
5
30
|
## 3.5.5 - 2026-11-15
|
|
6
31
|
|
|
7
32
|
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.
|
|
3
|
+
"version": "3.5.7",
|
|
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/**",
|
|
@@ -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
|
|
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
|
|
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)');
|
package/src/core/applyPlan.js
CHANGED
|
@@ -105,95 +105,60 @@ export async function pruneOldBackups(backupRoot, {
|
|
|
105
105
|
return { scanned: files.length, removed };
|
|
106
106
|
}
|
|
107
107
|
|
|
108
|
-
//
|
|
109
|
-
//
|
|
110
|
-
//
|
|
111
|
-
|
|
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
|
-
|
|
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]
|
|
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,
|
|
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
|
-
//
|
|
176
|
-
//
|
|
177
|
-
if (entry.
|
|
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
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
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
|
+
if (notice.held) {
|
|
147
|
+
console.log(
|
|
148
|
+
`[UKit] ${path.basename(entry.targetPath)}: did not add the UKit section "${notice.heading}" because your file has an unclosed code fence (a line starting with \`\`\` or ~~~ that is never closed). Close it and run install again, or add the section by hand from the template.`,
|
|
149
|
+
);
|
|
150
|
+
continue;
|
|
151
|
+
}
|
|
152
|
+
if (notice.renamedTo) {
|
|
153
|
+
console.log(
|
|
154
|
+
`[UKit] ${path.basename(entry.targetPath)}: your section "${notice.heading}" was renamed to "${notice.renamedTo}" upstream; kept yours unchanged and did not add the new one. Merge them by hand if you want the new text.`,
|
|
155
|
+
);
|
|
156
|
+
continue;
|
|
157
|
+
}
|
|
158
|
+
console.log(
|
|
159
|
+
`[UKit] ${path.basename(entry.targetPath)}: kept your edited section "${notice.heading}"; the UKit template for it changed${packageVersion ? ` in ${packageVersion}` : ''}.`,
|
|
160
|
+
);
|
|
161
|
+
}
|
|
197
162
|
}
|
|
198
163
|
if (entry.action !== 'create' && entry.action !== 'update') {
|
|
199
164
|
continue;
|
|
@@ -243,7 +208,7 @@ export async function applyDiffResults(diffResults, { backupRoot, projectRoot, r
|
|
|
243
208
|
// Back up the existing file before overwriting
|
|
244
209
|
if (
|
|
245
210
|
entry.action === 'update' &&
|
|
246
|
-
(entry.mergeStrategy === 'overwrite_with_backup' || entry.mergeStrategy === 'merge_env_overwrite_with_backup') &&
|
|
211
|
+
(entry.mergeStrategy === 'overwrite_with_backup' || entry.mergeStrategy === 'merge_env_overwrite_with_backup' || entry.mergeStrategy === 'managed_template') &&
|
|
247
212
|
backupRoot &&
|
|
248
213
|
projectRoot
|
|
249
214
|
) {
|
|
@@ -333,5 +298,5 @@ export async function applyDiffResults(diffResults, { backupRoot, projectRoot, r
|
|
|
333
298
|
});
|
|
334
299
|
}
|
|
335
300
|
|
|
336
|
-
return { writes, skippedUpdates, skippedByAction
|
|
301
|
+
return { writes, skippedUpdates, skippedByAction };
|
|
337
302
|
}
|
package/src/core/diffPlan.js
CHANGED
|
@@ -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, recordFor, renamesFor } 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.
|
|
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
|
|
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,44 @@ 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 {
|
|
47
|
+
return {
|
|
48
|
+
...entry, exists: false, action: 'create', existingContent: null, managedHash: templateHash,
|
|
49
|
+
managedSections: recordFor(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 = recordFor(templateText, { markdown });
|
|
52
60
|
if (installedHash === templateHash) {
|
|
53
|
-
return { ...entry, exists: true, action: 'unchanged', existingContent: installed, managedHash: templateHash,
|
|
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,
|
|
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
|
+
renames: renamesFor(entry.targetPath),
|
|
73
|
+
});
|
|
74
|
+
const base = { ...entry, exists: true, existingContent: installed, managedSections: merged.sections, mergeNotices: merged.notices };
|
|
75
|
+
if (!merged.changed) {
|
|
76
|
+
return { ...base, action: 'unchanged', managedHash: null };
|
|
57
77
|
}
|
|
58
|
-
|
|
78
|
+
const mergedBuf = Buffer.from(merged.content, 'utf8');
|
|
79
|
+
return {
|
|
80
|
+
...base,
|
|
81
|
+
action: 'update',
|
|
82
|
+
renderedContent: mergedBuf,
|
|
83
|
+
managedHash: sha256(mergedBuf) === templateHash ? templateHash : null,
|
|
84
|
+
};
|
|
59
85
|
}
|
|
60
86
|
|
|
61
87
|
async function readFileOrStatus(filePath, encoding = 'utf8') {
|
|
@@ -402,7 +428,7 @@ async function resolveSkipEntryAction(entry, ompOwnership = null) {
|
|
|
402
428
|
return resolveFileAction(entry, read.content, ompOwnership);
|
|
403
429
|
}
|
|
404
430
|
|
|
405
|
-
export async function diffInstallPlan(plan, { ompOwnership = null, settingsMigration = null, recordedManagedHashes = null } = {}) {
|
|
431
|
+
export async function diffInstallPlan(plan, { ompOwnership = null, settingsMigration = null, recordedManagedHashes = null, recordedManagedSections = null } = {}) {
|
|
406
432
|
// Check all entries in parallel
|
|
407
433
|
const results = await Promise.all(
|
|
408
434
|
plan.entries.map(async (entry) => {
|
|
@@ -416,7 +442,11 @@ export async function diffInstallPlan(plan, { ompOwnership = null, settingsMigra
|
|
|
416
442
|
}
|
|
417
443
|
|
|
418
444
|
if (entry.mergeStrategy === 'managed_template') {
|
|
419
|
-
|
|
445
|
+
// templateRender keeps the pristine template bytes (renderedContent may become the merge result).
|
|
446
|
+
return {
|
|
447
|
+
...(await resolveManagedTemplateAction(entry, recordedManagedHashes, recordedManagedSections)),
|
|
448
|
+
templateRender: entry.renderedContent,
|
|
449
|
+
};
|
|
420
450
|
}
|
|
421
451
|
|
|
422
452
|
const read = await readFileOrStatus(
|