@ngockhoale/ukit 3.5.2 → 3.5.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +38 -90
- package/README.md +1 -0
- package/manifests/documentation.yaml +12 -1
- package/manifests/platform.full.yaml +12 -0
- package/package.json +34 -1
- package/src/cli/commands/doctor.js +55 -2
- package/src/cli/commands/indexTools.js +10 -4
- package/src/cli/commands/memory.js +107 -8
- package/src/core/memory/episodes.js +106 -7
- package/src/core/memory/memoryCheck.js +241 -0
- package/src/core/memory/memoryCheckRun.js +27 -0
- package/src/core/memory/memoryHit.js +2 -0
- package/src/core/memory/mutateMemory.js +46 -1
- package/src/core/memory/observations.js +192 -0
- package/src/core/memory/projectIdentity.js +9 -2
- package/src/core/memory/recallEngine.js +204 -9
- package/src/core/memory/records.js +23 -0
- package/src/core/memory/registryPrune.js +230 -0
- package/src/core/memory/retrieval.js +12 -3
- package/src/core/memory/writeGate.js +137 -0
- package/src/core/runtimeConfig.js +12 -2
- package/src/index/buildIndex.js +26 -0
- package/src/index/paths.js +3 -1
- package/src/index/queryIndex.js +372 -26
- package/src/index/resolveContext.js +1 -1
- package/template_project/.claude/hooks/edit-hint.mjs +64 -17
- package/template_project/.claude/hooks/session-episode-start.mjs +35 -0
- package/template_project/.claude/hooks/session-episode.sh +9 -4
- package/template_project/.claude/settings.json +2 -2
- package/template_project/.claude/ukit/index/edit-graph.mjs +141 -11
- package/template_project/.claude/ukit/index/lib/index-core.mjs +400 -27
- package/template_project/.claude/ukit/index/query-index.mjs +14 -3
- package/template_project/.claude/ukit/index/resolve-context.mjs +1 -1
- package/template_project/.claude/ukit/index/route-task.mjs +8 -2
- package/template_project/.claude/ukit/runtime/memory-check.mjs +241 -0
- package/template_project/.claude/ukit/runtime/memory-lanes.mjs +44 -22
- package/template_project/.claude/ukit/runtime/memory-recall.mjs +204 -9
- package/template_project/.claude/ukit/runtime/memory-validity.mjs +259 -0
- package/template_project/.claude/ukit/runtime/reinject-context.mjs +4 -2
- package/template_project/.claude/ukit/runtime/self-improve-trigger.mjs +212 -5
- package/template_project/.omp/hooks/pre/ukit-bridge.js +2 -1
- package/template_project/ukit/storage/config.json +4 -2
- package/src/core/agentRuntime/completionGate.js +0 -179
- package/src/core/agentRuntime/context.js +0 -571
- package/src/core/agentRuntime/qualityComparison.js +0 -112
- package/src/core/agentRuntime/resourcePolicy.js +0 -78
- package/src/core/agentRuntime/runtimeSupport.js +0 -255
- package/src/core/codeintel/manifest.js +0 -176
- package/src/core/experiments/deliberation.js +0 -327
- package/src/core/experiments/dynamicWorkflow.js +0 -507
- package/src/core/handoffDocValidator.js +0 -154
- package/src/core/memory/deltaOverlays.js +0 -493
- package/src/core/memory/learningCandidates.js +0 -347
- package/src/core/observability/emit/sessionBoot.js +0 -407
- package/src/core/observability/evaluation/experimentPlan.js +0 -95
- package/src/core/observability/evaluation/perturbation.js +0 -273
- package/src/core/observability/evaluation/replay.js +0 -149
- package/src/core/observability/evaluation/scorecard.js +0 -465
- package/src/core/observability/schema/compatibility.js +0 -180
- package/src/core/observability/support/renderer.js +0 -130
- package/src/core/reviewPanelAggregate.js +0 -204
- package/src/core/taskBudgetValidator.js +0 -251
- package/src/core/taskProgressGuard.js +0 -227
- package/src/decision/reviewVerdict.js +0 -339
- package/src/decision/runtimeFilter.js +0 -150
- package/src/decision/runtimeScheduler.js +0 -239
- package/src/diagnostics/classifyHang.js +0 -246
- package/src/diagnostics/ompStallSnapshot.js +0 -199
- package/src/index/contextPack.js +0 -285
- package/src/index/impactContext.js +0 -360
- package/src/index/reviewPolicy.js +0 -368
- package/src/index/sensitivePath.js +0 -21
- package/src/render/instructionRenderer.js +0 -290
- package/src/skill/auditSkill.js +0 -140
- package/template_project/instructions/overlays/repo.md +0 -9
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,43 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to UKit are documented here.
|
|
4
4
|
|
|
5
|
+
## 3.5.4 - 2026-11-15
|
|
6
|
+
|
|
7
|
+
The index now knows almost every function and can search file contents for error text; memory writes pass a gate and `docs/MEMORY.md` becomes a capped core. Every number below was measured on this repository only.
|
|
8
|
+
|
|
9
|
+
- **The index covers functions that are not exported.** Non-exported functions, arrow-function constants, class methods and TypeScript `interface` / `type` / `enum` declarations are now symbols. Function declarations under `src/` that the index knows: 745 of 2,289 (32.5%, the frozen 3.5.3 baseline) → 2,334 of 2,336 (99.9%). An unexported symbol weighs slightly less than an exported one, and the outline of a file now always shows the symbols the query matched.
|
|
10
|
+
- **Error text is searched in file contents.** When no symbol or path matches well and the query is three or more plain words, `query-index` scans source files for the text (at most 1,500 files, 512 KB per file, 5 s; a cut-off scan prints `content-lane: truncated (<reason>)`). The scan order is fixed, so the same query gives the same answer under load. Edit-time hooks do not run it.
|
|
11
|
+
- **Measured on the 67-query gold set** (`scripts/bench/index-gold.mjs`; before = 3.5.3, frozen in `scripts/bench/baselines/index-gold-3.5.3.json`; after frozen in `index-gold-3.5.4.json`, three identical runs): right file first 61.2% → 86.6%, in the top 3 65.7% → 92.5%, the right line 47.1% → 100% of the 34 queries that have one. Per group, first / top 3: unexported symbol 8.3 → 100 / 16.7 → 100; error string 40 → 90 / 50 → 100; English sentence 63.6 → 72.7 / 72.7 → 81.8; Vietnamese sentence 50 → 50 / 50 → 70; exported symbol and path stay 100 / 100. No group got worse. A mirror outranks its original in 2 of 12 queries (was 3). Median query 3.3 → 6.9 ms, p95 6 → 38 ms (the content scan); median result size 3,735 → 5,457 bytes. A test holds every group at these numbers.
|
|
12
|
+
- **Cost:** `symbols.json` for this repository grows from 1,062,577 to 2,319,331 bytes and a full index build went from 1.30 s to 1.45 s (one clean build each of the 3.5.3 tree and this tree in temporary copies, by the maintainer; not part of the frozen baselines).
|
|
13
|
+
- **`docs/MEMORY.md` is a capped core.** One line per decision, at most 150 lines and 12 KB, each line pointing at a detail file under `docs/memory/`. Recall reads the core and every `docs/memory/*.md` (`memory.sources`, default `docs/MEMORY.md` + `docs/memory/*.md`); when a core line and its detail both match, only the detail is returned. On this repository recall output got 14% smaller with the same gold result. Existing projects keep working unchanged: a `docs/MEMORY.md` over the cap is reported, never rewritten.
|
|
14
|
+
- **`ukit memory check`** reports a core over its cap, a `Detail:` pointer to a missing file, and notes that name no existing file (warning only). After an edit to a memory file the edit hint carries the same findings (Claude Code and omp; Codex runs the command).
|
|
15
|
+
- **A note can replace another:** tag the old bullet `[id: <slug>]` and the new one `[supersedes: <slug>]`; recall drops the old one.
|
|
16
|
+
- **Memory writes pass a gate** (`memory.writeGate`, default `strict`; `off` disables). `ukit memory --user add/update`, `ukit memory v2 promote/stale` and `ukit memory propose` reject text over 1,200 characters, text containing a secret, and a near-duplicate of an existing entry; project record changes also need evidence (an existing file, a commit, an episode). A rejection prints `[UKit] rejected: <code>: <reason> (to pass: <fix>)` and exits 1 — secret rejections included, which used to exit 0. Every write to the user store is gated while the gate is on, because that store is shared across projects; `off` disables the gate there too. Not gated: records written by hooks and generators, and other library callers (size cap only). There is no project-level `memory add` command; the agent's project write path is editing the markdown files, which `ukit memory check` covers.
|
|
17
|
+
- **Episodes are written during long sessions, not only at session end.** A session-start step (Claude Code: startup, resume, clear, compact; omp: session start and compact; Codex: on a routed prompt, at most every 10 minutes) records finished tasks' episodes in the background, at most 25 per run. Three causes of empty stores are fixed: episodes waited for SessionEnd, paths were dropped when the project root was spelled differently, and only the newest 25 ledgers were scanned. An episode without a real project file is not recorded. On this repository the first run recorded 11 episodes (37 with content in total).
|
|
18
|
+
- **A stale global `ukit` is refused for episode writes.** If the `ukit` on PATH is older than the installed runtime, the step does not use it and `ukit doctor` says why. On Windows the PATH lookup follows `PATHEXT` (`ukit.cmd`, `ukit.exe`); that path is covered by tests with an injected platform and was not run on Windows. A project deleted while the step runs is not recreated.
|
|
19
|
+
- **`ukit memory observe`** proposes observations from episodes (files written together, a repeated failing check, a follow-up task), each citing its episodes; an observation whose evidence is gone is labelled. Proposals only — nothing is written. With the default minimum of 3 supporting episodes it proposes nothing on this repository's 37 episodes; at 2 it proposes two pairs, both correct. It has no measured value yet.
|
|
20
|
+
- **A long episode no longer answers on common words alone.** An episode must cover at least half of the question's weighted words. Found when the new episodes made one no-answer question return unrelated release tasks. Memory gold: answer in the top 3 stays 37/38, no-answer questions that stay silent 10/10.
|
|
21
|
+
- **The npm package drops 26 unused modules (about 270 KB).** Modules under `src/` that nothing in the shipped runtime imports (kept in the repository for tests and benchmarks) are no longer packed; a new test fails if a packed file ever imports one of them. Package: 725 files, 3.42 MB packed.
|
|
22
|
+
- Engines: index, recall, gate and check are shared runtime and CLI code used by Claude Code, omp (through the bridge) and Codex (through the CLI helpers). None of the three hosts was run live for this release, including the new session-start step; coverage is the tests and benches above.
|
|
23
|
+
- Correction to the 3.5.3 entry below: its "752 of 2,299 (32.7%)" coverage, "3,788 bytes" median result and "3.8 ms" median query do not match the frozen 3.5.3 baseline file, which holds 745 of 2,289 (32.5%), 3,735 bytes and 3.3 ms. The baseline file is the measurement; the ranking percentages in that entry do match it.
|
|
24
|
+
- Still weak: Vietnamese sentences (right file first 50%); test hints per source file (unchanged); 403 of the index's 2,713 `callable` symbols are `const x = (…)` expressions, not functions (an older rule, not new here).
|
|
25
|
+
|
|
26
|
+
## 3.5.3 - 2026-11-15
|
|
27
|
+
|
|
28
|
+
Source index ranking, and memory that knows when the code it describes has changed. Every number below was measured on this repository only.
|
|
29
|
+
|
|
30
|
+
- **Index search ranks the right file first far more often.** `query-index` (and everything that uses it: routing, triage, `resolve-context`) has a new scoring formula. An exact symbol name dominates; one file can no longer fill the list with many weak symbol hits (the best symbol counts in full, further ones are discounted); rare query words weigh more than common ones; substring matching only applies to words of 3+ characters; a path query matches the exact path, then a path suffix, then the basename; an original file ranks above its mirror copy (`template_project/`, `.claude/`, `.codex/`, `.omp/`); import-graph, hotspot and archetype boosts are capped so they cannot outrank a direct match.
|
|
31
|
+
- **Measured on a new 67-query gold set** (`scripts/bench/index-gold.mjs`, `scripts/bench/indexGold.json`; before = 3.5.2 scoring, frozen in `scripts/bench/baselines/index-gold.json`): right file first 16.4% → 61.2%, in the top 3 32.8% → 65.7%. Per group, first / top 3: exported symbol 41.7 → 100 / 66.7 → 100; path 8.3 → 100 / 8.3 → 100; English sentence 18.2 → 63.6 / 45.5 → 72.7; Vietnamese sentence 0 → 50 / 40 → 50; error string 20 → 40 / 30 → 50; unexported symbol 8.3 → 8.3 / 8.3 → 16.7. No group got worse. Median result size 7,001 → 3,788 bytes; median query time 2.9 → 3.8 ms. A test holds the new numbers as a floor.
|
|
32
|
+
- **Still weak, not fixed here:** unexported symbols and error strings, because the index only knows 32.7% of the function declarations under `src/` (752 of 2,299) and has no content search. A mirror still outranks its original in 3 of 12 queries that have one. Both are scheduled for 3.5.4.
|
|
33
|
+
- **Notes whose source changed are labelled.** When a memory note names a file, UKit records that file's state at write time (and for existing notes, the first time the CLI recalls them). If the file later changes or disappears, recall shows the note with `[source changed since noted — verify]` and ranks it slightly below equally relevant notes that are still current; a note whose file is gone ranks last. `ukit memory v2 confirm <record-id | path:line>` marks a note as re-checked. State lives in `.ukit/storage/memory/v2/anchors.json`; hooks only read it. Off: `UKIT_MEMORY_VALIDITY=0`. On the 48-question memory gold set the label and the mild ranking keep 37/38 answers in the top 3 and 10/10 abstentions when 6 of the 12 notes that name a file (of 68 notes) are marked changed; a strict "changed notes last" ranking was tried, lost an answer (36/38) and was not kept as default.
|
|
34
|
+
- **A record that another record supersedes is no longer returned** (`supersedes` on memory records; markdown bullets have no such field yet).
|
|
35
|
+
- **Test hints after an edit use git history.** The edit graph now mines which files changed together (last 500 commits, at index build, about 70 ms) and uses it to rank the suggested tests. Replay of 148 commits, top 3: per commit recall 0.39 → 0.43, precision 0.18 → 0.21, at least one right test in 97 → 116 commits. Per source file, recall is 0.06 → 0.07 (the best possible with three suggestions is 0.24) — the target of a clear rise was not met; test hints remain a starting point.
|
|
36
|
+
- **"Often changed together" line: shipped off.** `memory.editHints.coChange: true` adds one line of files that historically changed with the edited file. Top-3 precision was 0.51 overall but 0.27 on the older half of the history and 0.60 on the newer half, and no threshold kept both halves above 0.5, so it is not on by default.
|
|
37
|
+
- **Tried and removed:** a recall lane that resolves file and symbol names in the question and fuses the notes attached to those files with the text ranking. On 12 new file-naming questions it raised answers in the top 3 from 9 to 11, but 2 of 4 new no-answer questions still returned unrelated notes (with or without the lane) and the hook got about 8–10 ms slower at the median and about 35 ms at p95. The code is not in the package; the questions stay in the gold file as a separate, non-gating block.
|
|
38
|
+
- **The user-level project registry prunes itself.** `~/.ukit/storage/projects/registry.json` kept an entry for every directory UKit was ever installed into, including deleted temp directories; on the maintainer's machine 48,075 of 48,101 entries were dead (19.7 MB; counted by the maintainer, not by the independent review). On a synthetic registry of 48,001 entries a project registration took 272 ms. An entry is now removed only when every root and git directory is provably gone, its drive or volume is mounted, and no user-level memory record points at it. It runs at most once a day once the registry has 500+ entries, within 1.5 s, or on demand: `ukit doctor --prune-registry [--dry-run]`. After pruning the synthetic registry, registration took 2 ms.
|
|
39
|
+
- Engines: the index and memory changes are shared runtime and CLI code, used by Claude Code, omp (through the bridge) and Codex (through the CLI helpers). None of the three hosts was run live for this release; coverage is the tests and benches above.
|
|
40
|
+
- Repository only: `CHANGELOG.md` entries 3.4.76–3.4.85 moved verbatim to `docs/archive/CHANGELOG-3.4.76-3.4.85.md`, and six modules used only by repository scripts and tests plus the repo-only instruction overlay are no longer packed, to keep the package inside its size budget (limits unchanged).
|
|
41
|
+
|
|
5
42
|
## 3.5.2 - 2026-11-15
|
|
6
43
|
|
|
7
44
|
Edit hints. After the agent edits a file, UKit now tells it what else usually has to change with that file, instead of leaving the agent to find the mirror copy or the test on its own.
|
|
@@ -34,95 +71,6 @@ First release of the memory line (3.5.x). Recall now returns the project's writt
|
|
|
34
71
|
- Engines: Claude Code and omp use all lanes (omp through the Claude runtime bridge). Codex has no UKit hooks, so it gets the new recall through `ukit memory recall`, and its episodes are recorded by the idle-ledger backfill rather than at session end. Codex and omp were not run live for this release; coverage is the shared runtime's tests.
|
|
35
72
|
- Repository only: `CHANGELOG.md` entries 2.7.0–2.8.0 and 3.4.0–3.4.50 (except 3.4.14 and 3.4.22) moved verbatim to `docs/archive/` to keep the package inside its size budget (limits unchanged). The memory module inventory moved to `docs/design/memory-io-inventory.md`.
|
|
36
73
|
|
|
37
|
-
## 3.4.85 - 2026-11-14
|
|
38
|
-
|
|
39
|
-
- Release gate (repository only): **the publish guard no longer has an owner-authorization prerequisite.** Since 3.4.72 `npm publish` also required a fresh owner chat message naming the exact version, so finished, verified and reviewed work stopped to ask for a sentence. The project owner did not want that step: a release is a new version number for users to check. The per-version message check and the standing-grant form added in 3.4.84 are both removed; a receipt needs no `authorization` block and a leftover one is ignored. Still mandatory: an official `release:verify` PASS on the exact candidate (unchanged), and an independent review whose final verdict is exactly APPROVED, derived from a native reviewer session. One review rule replaces a side effect of the removed step: the owner-session comparison was also what kept the reviewer apart from the working session, so the cited review message must now come from a separate reviewer agent's own transcript (`<session>/subagents/agent-<id>.jsonl`); a message from a main session is refused. `PROJECT_IMPORTANT.md` §4.4 now records the rule (finished work ships without asking; the two quality gates stay).
|
|
40
|
-
- Tests: `tests/release/publishGuard.test.js` drops the owner-message and standing-grant cases; the session-store provenance cases (unknown uuid, hash mismatch, foreign store, cwd binding, session metadata, text blocks) now run against the reviewer message. New cases: a main-session reviewer message refuses; a reviewer agent working in a linked worktree passes.
|
|
41
|
-
|
|
42
|
-
## 3.4.84 - 2026-11-14
|
|
43
|
-
|
|
44
|
-
Follow-up to the 3.4.83 hook audit: the items that release left open.
|
|
45
|
-
|
|
46
|
-
- Fix: **a command that only mentions a test runner no longer counts as verification.** The completion gate's classifier matched runner names anywhere in the command text, so `grep -n pytest file`, `ls node_modules/.bin/vitest`, `echo yarn test`, `yarn add -D vitest`, `npm install jest` or `which vitest`, run with exit 0, were recorded as a verification receipt with a satisfying `test-verified` verdict — a task could be declared verified with no test run. Each simple command is now judged by the word that executes: direct runners (`vitest`, `jest`, `mocha`, `ava`, `pytest`, `tsc`, `eslint`, `biome`, `ruff`, `mypy`), package-manager scripts (`test`, `test:*`, `lint`, `typecheck`, `check`, `build`, `release:verify`, via `run`/`exec`/`dlx`/`workspace` and `npx`), `python -m pytest`, `uv`/`poetry run …`, `node --test` / `node --check`. Leading assignments, the env/time/timeout/sudo/nohup/corepack wrappers and value-taking options (`yarn --cwd DIR …`, `pnpm -C DIR …`, `npm --prefix DIR …`) are skipped; arguments, paths, comments, quoted strings and heredoc bodies are never evidence. Newly recognised: `pnpm -C pkg test`, `npm --prefix pkg test`, `yarn workspace foo test`, `node node_modules/vitest/vitest.mjs run`. `[ vitest = vitest ]` / `test vitest = vitest` now produce no verification receipt at all.
|
|
47
|
-
- Fix: **`reset-auto-permissions.mjs --help` no longer performs a reset.** Arguments were checked with `includes`, so `--help` or any typo (`--dry-runn`) fell through to the real reset. `--help` / `-h` print usage and exit 0; any unknown argument exits 2; both return before a file is read.
|
|
48
|
-
- Fix: **decision-plane shadow calls stop timing out on a healthy endpoint.** The detached hook-path shadow child blocks no hook, yet shared the inline path's 3 s cap; an 8-question batch to the local `unic-decision` endpoint measured about 2 s typical with 3–6 s tails, so whole batches timed out and then opened the circuit breaker. The detached child now honours `decisionPlane.timeoutMs` up to 8 s; the inline path keeps 3 s and shadow answers still never change a route. The "five keys never answered" note in 3.4.83 was not reproduced: all eight asked keys returned valid answers in the audited week (five have no baseline to compare against and log `agree=unknown`).
|
|
49
|
-
- Fix: self-improve classifies `timeout-hang` from host evidence. A Bash receipt carries `timedOut` when Claude Code reports the call as a failure whose own error reads "Command timed out after …"; mined patterns carry the marker and `timeout-hang` accepts it. Exit 137/143 alone stay unclassified (137 is also the OOM-kill status). Codex and omp expose no equivalent field that could be confirmed, so their timeouts still rely on exit 124 or the text markers.
|
|
50
|
-
- Release gate (repository only): **the publish guard accepts a standing owner authorization.** Since 3.4.72 every publish needed a fresh owner chat message naming the exact version, so a finished, verified and reviewed fix still stopped to ask. The receipt may now cite `authorization: { by: 'user', standing: true }`; the guard then reads the grant from the "Standing publish authorization" section of the git-tracked `PROJECT_IMPORTANT.md` (regular file, committed and unmodified at HEAD, names the package, covers every version, one line that authorizes publishing, states the verification + review conditions, no denial, pending or negated grant). The verified run and the independent APPROVED review are unchanged and still mandatory; a receipt that cites a message is judged on that message only. The template `PROJECT_IMPORTANT.md` shipped to installed projects carries no grant.
|
|
51
|
-
- Tests: new `tests/hooks/verificationCommandWord.test.js`; argument-safety cases in `tests/hooks/c91ResetAutoPermissions.test.js`; timeout-budget cases in `tests/index/unicDecisionCircuit.test.js`; `timedOut` cases in the ledger, pattern and proposal tests; standing-authorization cases in `tests/release/publishGuard.test.js`. `tests/hooks/nativePublicationRouting.test.js` now reports router and gate output when its foreign-session assertion fails.
|
|
52
|
-
- Not changed: that test failed once under full-suite load in 3.4.83 and could not be reproduced (load average 60, slowed git, paused coordinator), so no product change was made for it. A related gap was found and is not fixed here: when the router is killed by its deadline before its first route write, or its session lock is busy, the following Stop evaluates no route and releases without a message.
|
|
53
|
-
|
|
54
|
-
## 3.4.83 - 2026-11-13
|
|
55
|
-
|
|
56
|
-
Hook fixes from a one-week audit of this repository's own Claude Code transcripts, hook-latency rows, decision log and permission audit log (6,685 hook runs, no hook timeouts; Stop p95 about 1.6s).
|
|
57
|
-
|
|
58
|
-
- Fix: **`auto-allow-bash` no longer mints junk permission rules.** The binary was picked by whitespace splitting, so a leading assignment with a quoted or substituted value was cut in half and the next fragment became the "binary": `UKIT_EVIDENCE='… HEAD …' yarn test` minted `Bash(HEAD:*)`, `d=$(ls -td …)` minted `Bash(-td:*)`. The hook now scans real shell words (single/double quotes, `$(…)` with nesting, backticks, backslash escapes), skips whole `NAME=value` / `NAME+=value` words, and mints nothing when the first command word cannot be determined (unbalanced quote or substitution, leading operator, redirection or subshell) or starts with `-`. Behaviour change: `command -v node` and `env -i FOO=1 ls` now mint nothing (they minted `-v` / `-i`). The denylist block, charset check, interpreter list and locked atomic write are unchanged. omp runs this same script through its bridge; Codex has no auto-allow lane.
|
|
59
|
-
- Fix: `reset-auto-permissions.mjs --sanitize` also removes rules whose token starts with `-` (option fragments left by the old tokenizer), behind the same proven-provenance gate. Other junk words (`HEAD`, `status`, `view` …) cannot be told apart from real binaries and are left in place; the full reset removes every UKit-managed rule.
|
|
60
|
-
- Fix: **`task-watchdog` no longer announces "payload was truncated or stalled" on large Edit/Write calls.** Its PostToolUse path reads only the event name from the payload (tasks, state and config come from disk), yet any payload over the 64 KiB staging cap was reported as incomplete input. A payload cut only by the size cap, whose event name is provably complete and exactly `PostToolUse`, now runs normally. Stalled staging, an unrecoverable event name, Stop (which forwards the raw payload to the coordinator) and the pre-install fallback branch keep the announced degrade.
|
|
61
|
-
- Fix: **self-improve no longer mints handoff tasks for failures that never happened.** The `timeout-hang` class matched `timeout|hang|hung` anywhere in a command's text, so "c*hang*elog", "unc*hang*ed", a test file named `verifyReleaseTimeout.test.js` or an env var `UKIT_VERIFY_STEP_TIMEOUT_MS` each produced an `AUTO-<n>.md` task telling the executor to raise a timeout. Mined patterns now carry the failed receipts' exit codes (`exitCodes`); `timeout-hang` needs exit 124 or a whole-word marker ("timed out", "timeout exceeded/expired", "hangs", "hanging", "hung") on the command's invocation lines — heredoc bodies and comment lines are not read. The other three classes use whole-word matches on the same stripped text. Known limit: a timeout the host kills with exit 1 or 137 is not classified (a missed task, not a wrong one).
|
|
62
|
-
- Fix (tests only): hook latency telemetry from test runs no longer lands in the repository's own `.ukit/storage/cache/hook-latency/` (seven test files spawned hooks against the real root; about 4,200 rows over five days). `appendTelemetryRow` drops rows for the root named by `UKIT_TELEMETRY_DENY_ROOT`, which only this repository's `vitest.config.js` sets; unset, it is inert.
|
|
63
|
-
- Fix (pre-release review): the new scanner gives up — mints nothing — on constructs whose end it cannot prove. Two review rounds each found a command resolving to the wrong binary (`X=$'\' curl ' ls` and `A=${x:- curl } ls` both minted `Bash(curl:*)` while bash runs `ls`). Every `$` now goes through one helper that accepts only `$(…)`, `$NAME` and a simple `${NAME}`; ANSI-C/locale quoting (`$'…'`, `$"…"`), any other `${…}`, `$[…]`, and a `#`, heredoc or `case` inside `$(…)` mint nothing. The scan is bounded to the first 4,096 characters of the command (a 100 KB assignment value stalled the hook for more than 45 seconds; a first command word not resolved inside the window mints nothing), and variable names are matched against explicit ASCII classes (`É=a ls` no longer counts as an assignment).
|
|
64
|
-
- Tests: `tests/hooks/autoAllowBinaryResolution.test.js` (41), four size-truncation cases in `tests/hooks/taskWatchdog.test.js`, classifier and `exitCodes` cases in `tests/core/codeProposals.test.js` / `tests/core/failurePatterns.test.js`.
|
|
65
|
-
- Packaging: the 2.5.1–2.6.11 changelog entries moved verbatim to `docs/archive/CHANGELOG-2.5.1-2.6.11.md` (repository only); size limits unchanged.
|
|
66
|
-
- Not changed: decision-plane shadow calls to the local `unic-decision` endpoint timed out 184 times in the audited week and five decision keys never returned a valid answer — shadow-only, not root-caused in this release.
|
|
67
|
-
|
|
68
|
-
## 3.4.82 - 2026-11-10
|
|
69
|
-
|
|
70
|
-
Completion-gate fixes from a field-telemetry audit of the projects running UKit (Stop/gate logs, hook latency, route state, session transcripts).
|
|
71
|
-
|
|
72
|
-
- Fix: **a stale legacy handoff cursor no longer marks every stop BLOCKED.** A `docs/AI_HANDOFF/RUN.md` written before `RunId` existed has no authority record, so nobody can own it until `/ukit:handoff-fullstack --adopt-legacy-run=<RunId>`. A session whose published route holds no handoff binding is now `NOT_OWNED` (an ordinary session beside an old cursor) instead of `UNKNOWN`; telemetry showed ~2,500 "handoff ownership UNKNOWN … report BLOCKED" advisories, 2,000 of them in one project in one month. A route that carries a `handoffRunId`, a duplicated `RunId`, or a missing/foreign/incomplete route still fails closed as `UNKNOWN`; the cursor is never touched and adoption is unchanged.
|
|
73
|
-
- Fix: **questions and acknowledgements are no longer routed as change orders.** Tone-folding turned "cái" into the verb *cài* (install) — likewise chính/chỉnh, Việt/viết, đợi·đối·đội/đổi, cháy·chảy/chạy, sữa/sửa, thèm/thêm — so "Cái này là gì, tại sao có chế độ này" owed write + verification evidence. Also released: "chưa được cấp quyền cập nhật …" / "no permission to update" (a read-only banner, not an order), "còn cần làm gì thêm nữa không" / "có thêm test nữa không" ("anything else", not "add") — only in the closed "còn/có … gì thêm [nữa] [không]" / clause-final "thêm nữa không" shape, so "thêm gì vào README.md" stays an order, a what-is question followed by punctuation, a leading "giải thích …" / "explain …", and bare acknowledgements after a task ("ok", "có", "được", "ừ", "được rồi") which now park the previous contract instead of re-arming it. Every release keeps its order control: "Cái này là gì, sửa giúp tôi", "thêm test nữa đi", "ok sửa đi", "giải thích rồi sửa luôn", "cấp quyền cập nhật cho user admin trong file roles.js" still block an empty stop. A bare "yes / ok / có / được / ừ / đồng ý" that answers a question the agent itself just asked (the last assistant text in the host transcript ends with a question, with no other owner turn in between) is the go-ahead for that same task and keeps its contract armed; "đóng nhé" (close it) is no longer read as "đồng ý". The homograph / banner / question rules are applied to `src/index/taskRouting.js`, `route-task.mjs` and the `skill-router.sh` hook; the acknowledgement rules live in `route-task.mjs` and the hook (the `src/index` copy has no greeting lane).
|
|
74
|
-
- Improved: **an unproven verification now names the command that proves it.** Most verification-evidence blocks were a runner piped into `tail`/`grep`/`tee` or followed by `; echo exit=$?`, and sessions repeated the same masked shape. The PostToolUse notice and the gate instruction now add "Run exactly this once: …" (`set -o pipefail; <same command>` for a pipe, the command up to and including the runner for a status echo, keeping a leading `cd`/env prefix) — only when the same classifier accepts that command and no second runner would be dropped. Guidance only: what counts as proof is unchanged, and loop/background shapes keep the generic wording.
|
|
75
|
-
- Fix: **"semantic contract invariant violation … contradictory contracts" no longer blocks a healthy session.** Telemetry: 172 such Stop blocks. The router re-scores the execution mode on every tool event while the contract stays the task's own, and both the router and the gate re-derived the contract from the *current* mode — so a contract built under `find-cause`/`map-impact` compared unequal to itself once the mode moved to `local-fix`. The comparison now accepts a stored contract that any execution mode reproduces for the same prompt and engine; a contract no mode reproduces (foreign evidence tag, different task kind) still blocks. Two feeders are closed as well: a new task no longer inherits the previous task's evidence tags, operation goals or state targets (a read-only review's `impact-evidence` leaking into the next change order), and a system-injected turn (compact summary, `/loop` wakeup) after an answer-only turn no longer mints a contract bound to the owner's prompt.
|
|
76
|
-
- Fix: **a slow Stop evaluation is no longer reported as a broken install.** One evaluation repeated the same git probes (16 spawns → 10; about 950ms → 550ms measured on this repo); they are now memoized for that single evaluation only. The evaluator's time slice scales with the hook deadline (1500ms → up to 3000ms; `completion-gate.sh` default deadline 3000 → 5000ms, inside the hook's slot, see below), and an evaluator that still runs out of time blocks fail-closed with its own fixed text ("ran out of time … Stop again to re-evaluate") instead of "Run: ukit install".
|
|
77
|
-
- Fix: the Stop message for an unproven verification cut the command at 80 characters — on a real `cd <root> && PYTHONPATH=. venv/bin/python3.12 -m pytest … | grep … | tail -40` that ended exactly at `python3.12 -`, naming a command that never ran and hiding the pipe that made it unproven. The label now keeps the whole command up to 240 characters (both ends beyond that). The hook-deadline block now says to stop again first and reach for `ukit install` only if it repeats; it stays fail-closed.
|
|
78
|
-
- Fix: a Stop on which the completion evaluator could not finish (killed at its time slice, hook deadline, evaluator crash) blocked every time with no cap — one field session took 170+ such blocks in a row on a loaded machine, each costing a turn the agent could do nothing with. These blocks now have their own bounded breaker in `completion-gate.sh`: counted per session (one session never releases another), released only after more than `stopGateMaxCrashStreaks` (default 3) consecutive failures (no more than 10 minutes apart) that also span at least 120 seconds — stopping again a few times in a row never releases — and the release is announced as a blocked, non-complete outcome ("completion was NOT verified … not a pass"). Any real verdict resets the count; evidence blocks, and any decision carrying a handoff-cursor or task-watchdog block, are never counted. The crash breaker for a coordinator that exits non-zero is unchanged and separate. A block verdict the evaluator had already written when its time-slice kill landed is now honoured as that verdict instead of being reported as an evaluator failure (a cut-short release is still never trusted).
|
|
79
|
-
- Fix: the Stop hook's chain slot is 12s (was 8s) and its host timeout 22s (was 18s), keeping the chain-budget rule host ≥ slot + 10s. With the 5000ms coordinator deadline plus the 1500ms killer the wrapper could need 6.5s before bash start-up and staging, and a chain-runner timeout of this wrapper would have been a silent release.
|
|
80
|
-
- Tests: `tests/hooks/semanticContractModeChurn.test.js`, `tests/hooks/stopEvaluatorBudget.test.js`, `tests/hooks/telemetryAuditRouting.test.js` (real hook + gate, fresh and after-task, with order controls), a legacy-cursor bystander case with fail-closed controls in `handoffProvenance.test.js`, and rerun-guidance cases in `stopGateReceiptCapture.test.js`.
|
|
81
|
-
- Not changed (by design, per the audit): pipe/`; echo $?` shapes stay unproven; a carried compact-summary contract still owes its evidence; the teammate-message lane has no fix in this release.
|
|
82
|
-
|
|
83
|
-
## 3.4.81 - 2026-11-08
|
|
84
|
-
|
|
85
|
-
- New: **automatic Claude Code session discovery for UKit Advisor.** `ukit:advisor` / `$ukit-advisor` with nothing after the trigger (or only a short remark such as "lỗi rồi") reads the latest main-agent Claude Code session of the current project — no paste needed; `session <id>` and `project <path>` name one explicitly; anything else is still pasted output, as in 3.4.80. A bundled read-only Node reader (`scripts/claude-session-reader.mjs` inside the skill, also `ukit advisor context [--last|--session <id>|--project <path>] [--json]`) matches the project by the session's recorded cwd (realpath, git root, linked worktrees; nested repos and sibling folders excluded), honours `CLAUDE_CONFIG_DIR`, skips subagent/sidechain transcripts and symlinks, refuses to guess between concurrent sessions, streams huge/partial/concurrently-written JSONL with bounded secret redaction, and renders a bounded, redacted, untrusted digest that keeps owner messages, tool results, assistant claims and Stop-hook/gate refusals apart (owner STOP ≠ hook refusal). It never writes, spawns, resumes or messages Claude Code; no session, no permission or a Codex model that cannot run shell commands yields one safe status-request prompt.
|
|
86
|
-
- Tests: 41 session-reader tests on synthetic transcripts with an isolated `CLAUDE_CONFIG_DIR`; the repo-only live runner `scripts/dev/advisor-live-eval.mjs` gains `--mode=auto` and counts only real `command_execution` events as a reader run; two load-sensitive hook tests get timing headroom (assertions unchanged).
|
|
87
|
-
- Release note: 3.4.80 was tagged and GitHub-released but never published to npm; 3.4.81 is the first npm release carrying UKit Advisor (both the paste mode and session discovery).
|
|
88
|
-
- Packaging: the 2.3.0–2.4.3 changelog entries moved verbatim to `docs/archive/CHANGELOG-2.3.0-2.4.3.md` (repository only); size limits unchanged.
|
|
89
|
-
|
|
90
|
-
## 3.4.80 - 2026-11-08
|
|
91
|
-
|
|
92
|
-
- New: **UKit Advisor for Codex.** Paste Claude Code output (status, errors, stalled transcripts, STOP/gate/release messages — VN/EN/mixed) into Codex after `$ukit-advisor` or `ukit:advisor` and get back exactly ONE copy-ready Vietnamese prompt for Claude Code (PROMPT ONLY: no analysis section, no code fence, no alternatives). The advisor is read-only, treats the paste as untrusted data, never lifts an owner STOP, never forges ownership/receipts, never starts duplicate jobs, keeps release states distinct (never republishes a verified npm version) and redacts secrets.
|
|
93
|
-
- Surfaces: `$ukit-advisor` is a native Codex skill seeded into `~/.agents/skills/ukit-advisor` (`allow_implicit_invocation: false`). `ukit:advisor` is instruction-routed — a marker-delimited block in the active global Codex instructions file (`$CODEX_HOME/AGENTS.override.md` when present, else `AGENTS.md`) points the prefix at the same SKILL.md; it is not a native Codex command.
|
|
94
|
-
- Lifecycle: installed/refreshed by `ukit install` when the Codex adapter is selected, and by `ukit update` (with `--no-install` or outside a UKit project it only refreshes an advisor UKit already installed); idempotent; ownership via `.ukit-managed.json` hashes, so an unrelated same-name skill is never overwritten and user-edited files are kept; the user's AGENTS.md bytes, BOM and line endings are preserved; a damaged BEGIN/END marker pair or a symlinked AGENTS.md is reported and never rewritten. New `ukit advisor status|install|uninstall [--dry-run]`; opt out with `UKIT_CODEX_ADVISOR=0`.
|
|
95
|
-
- Tests: lifecycle/ownership/cross-platform unit tests, a deterministic PROMPT-ONLY contract checker with 13 eval fixtures, test isolation now pins `CODEX_HOME`, and a repo-only live runner `scripts/dev/advisor-live-eval.mjs`.
|
|
96
|
-
- Packaging: the 3.0.0–3.3.3 changelog entries moved verbatim to `docs/archive/CHANGELOG-3.0.0-3.3.3.md` (repository only); size limits unchanged.
|
|
97
|
-
|
|
98
|
-
## 3.4.79 - 2026-11-07
|
|
99
|
-
|
|
100
|
-
- P0 handoff queue lifecycle: one read-only classifier (`classifyQueuedBlueprints`) now decides which `docs/AI_HANDOFF/queued/` blueprints still count as unfinished work. `QueueIntent: superseded|stale` + `QueueSupersededBy: archive:cycle-NN[, …] | queue:<slug>` excludes a blueprint only when the provenance is proven (every package task archived in an 8-column cycle snapshot as delivered/grounded-cancelled, or a live non-cyclic replacement inside the project); self-references, cycles, paths, symlink escapes, partial archives and malformed headers fail closed with diagnostics. Legacy blueprints and `deliberate-future` keep their behaviour; the array API stays compatible. A frozen `ScopeQueue` naming a superseded blueprint warns instead of consuming it silently; a sibling `queue/` directory is reported, never migrated. A `queue:<slug>` replacement that is `deliberate-future` backlog cannot carry the obligation (fails closed). New read-only `resumable-run.mjs queue-status`.
|
|
101
|
-
- P0 completion contract: plan/doc-only prompts (Vietnamese "tài liệu/kế hoạch", guide/plan/notes nouns, `update docs/x.md`) owe only the written `docs/…md` artifact instead of code write+test evidence, and a filename such as `docs/plans/deploy.md` is no longer read as a deploy order. Code prompts keep write+verification; deploy prompts keep operation verification. Every clause must be doc-only (whitelist): an inspection lead, a bare `write`/`update` with no doc noun, or a vague order ("do it", "proceed", "làm tiếp") keeps the code contract; inside a docs-path clause free prose is allowed only after a describe/explain lead, and any order behind plus/once/as well as/parentheses/colon keeps the code contract.
|
|
102
|
-
- Acceptance: 6-column INDEX/snapshot layouts fail closed and are never rewritten; the consumer migration procedure (backup → dry-run on a copy → 8-column re-snapshot → idempotent → rollback, collision, 3-digit cycle, crash recovery) is covered by `tests/handoff/queueLifecycleAcceptance.test.mjs`. Consumer guidance: `docs/release/3.4.79-QUEUE-LIFECYCLE-MIGRATION.md` (repository only).
|
|
103
|
-
- Packaging: the 2.1.0–2.2.16 changelog entries moved verbatim to `docs/archive/CHANGELOG-2.1.0-2.2.16.md` (repository only); size limits unchanged.
|
|
104
|
-
|
|
105
|
-
## 3.4.78 - 2026-11-06
|
|
106
|
-
|
|
107
|
-
- P0 RC4 (delayed wakeup): a `/loop` fire queued behind a busy turn is delivered only after that turn ends, so its `scheduled_task_fire` record sat behind the turn's assistant entries and beyond the router's 128KB tail (real incident: 177KB, 7 minutes) and the wakeup minted a fresh CODE_IMPLEMENTATION task. An UNCONSUMED same-session fire (no later entry carries its `scheduledFireId`), matching the prompt, at most 6h old, found in a bounded 8MB tail is now host provenance: the previous task and contract carry, a read-only wakeup stays a coordination turn. Consumed, foreign-session, stale, timestamp-less or different-prompt fires never exempt an owner prompt. Replay of the real transcript: HEAD minted a new task, fixed router carries.
|
|
108
|
-
|
|
109
|
-
## 3.4.77 - 2026-11-06
|
|
110
|
-
|
|
111
|
-
- Packaging: the 1.0.0–2.0.7 changelog entries moved verbatim to `docs/archive/CHANGELOG-1.0.0-2.0.7.md` (repository only) so the npm artifact stays inside the unchanged size budget; no runtime or safety code was removed and the size limits were not raised.
|
|
112
|
-
- P0 acceptance: a Claude Code scheduled wakeup (`scheduled_task_fire` in the current delivery window) is recognized as host provenance, never owner authorization; commit/push + script deploy keeps a separate git goal; a milestone with no attempted operation hands back instead of demanding operation verification; an unchanged-state Stop gives a single finite handback.
|
|
113
|
-
- P0 continuation: a pending host background job yields a WAIT Stop (no budget, no edit demand, one release per job); an explicit owner continue/authorization adopts the predecessor task's content-current evidence via a single-hop link; scoped (conditional/purpose/other-subject/quoted) bans no longer prohibit an authorized deploy; non-npm native deploys are proven by deploy + post-deploy receipts; unproven-exit messages name the runner. Replay/unit evidence only.
|
|
114
|
-
|
|
115
|
-
## 3.4.76 - 2026-11-03
|
|
116
|
-
|
|
117
|
-
**P0 follow-up: UNKNOWN-stop marker store, explicit STOP publication and negation-aware state classification. Isolated process/replay evidence only; not live-host certification.**
|
|
118
|
-
|
|
119
|
-
- `ukit marker-store migrate`: plan by default; `--apply --writers-stopped` refuses unless the owner attests every OMP/bridge session is closed, no process uses the project, no writer temp file exists and the store is unchanged across an observation window. It never kills processes, keeps releases byte-for-byte, turns blocks into sticky releases under the same hashed names, quarantines (never deletes) the old store, and resumes after interruption.
|
|
120
|
-
- Bridge: a fenced or unavailable store fails open (`degraded:storage`) without crash or repeated calls; release-only saturation keeps every release.
|
|
121
|
-
- Explicit owner STOP survives pending route publication and never expires by TTL.
|
|
122
|
-
- Classifier: a negated verb ("do not stop the job") no longer mints a state-verification debt; `khong sua ledger/gate/receipts` stays READ_ONLY.
|
|
123
|
-
- Consumers: close related OMP/bridge sessions, `ukit update`, `ukit marker-store migrate`, then `--apply --writers-stopped`, verify, reopen. STOP stays in effect; legacy cursors are adopted only via explicit `--adopt-legacy-run`.
|
|
124
|
-
- Artifact budget: packed < 3,500,000 and unpacked < 11,300,000 bytes (limits unchanged). To stay under the unpacked limit, about 92 verbose bullets in historical entries (mostly older than 2.7) were shortened in this file, saving about 22 KB; no release was removed, and the full original text is in git history at 46b48d11.
|
|
125
|
-
|
|
126
74
|
## 3.4.22 - 2026-10-07
|
|
127
75
|
|
|
128
76
|
**Windows: `.sh` hooks no longer deny every Edit/Write/Bash.**
|
|
@@ -243,4 +191,4 @@ UKit gains a fourth runtime and loses one. omp (Oh My Pi) reaches full parity wi
|
|
|
243
191
|
|
|
244
192
|
**Known gap:** omp was not installed on the machine this release was built on. Every omp assertion in the test suite is against the generated `.omp/` tree and the bridge module's shape — the packed-tarball test confirms `templates/.omp/**` actually publishes, but nothing here observes omp's runtime behaviour. The three open verification items (does omp emit `session_start` on a post-compact continuation; omp's real base-URL key; omp's real auto-compact-window key) are recorded in `docs/AI_HANDOFF/tasks/TASK-008.md`.
|
|
245
193
|
|
|
246
|
-
Entries for 3.4.0 through 3.4.50 (except 3.4.14 and 3.4.22) are archived in the repository at `docs/archive/CHANGELOG-3.4.0-3.4.50.md`. Entries for 2.7.0 through 2.8.0 are archived in the repository at `docs/archive/CHANGELOG-2.7.0-2.8.0.md`. Entries for 2.5.1 through 2.6.11 are archived in the repository at `docs/archive/CHANGELOG-2.5.1-2.6.11.md`. Entries for 3.0.0 through 3.3.3 are archived in the repository at `docs/archive/CHANGELOG-3.0.0-3.3.3.md`. Entries for 2.1.0 through 2.2.16 (except 2.2.1) are archived in the repository at `docs/archive/CHANGELOG-2.1.0-2.2.16.md`; entries for 1.0.0 through 2.0.7 at `docs/archive/CHANGELOG-1.0.0-2.0.7.md` (neither is shipped in the npm package).
|
|
194
|
+
Entries for 3.4.76 through 3.4.85 are archived in the repository at `docs/archive/CHANGELOG-3.4.76-3.4.85.md`. Entries for 3.4.0 through 3.4.50 (except 3.4.14 and 3.4.22) are archived in the repository at `docs/archive/CHANGELOG-3.4.0-3.4.50.md`. Entries for 2.7.0 through 2.8.0 are archived in the repository at `docs/archive/CHANGELOG-2.7.0-2.8.0.md`. Entries for 2.5.1 through 2.6.11 are archived in the repository at `docs/archive/CHANGELOG-2.5.1-2.6.11.md`. Entries for 3.0.0 through 3.3.3 are archived in the repository at `docs/archive/CHANGELOG-3.0.0-3.3.3.md`. Entries for 2.1.0 through 2.2.16 (except 2.2.1) are archived in the repository at `docs/archive/CHANGELOG-2.1.0-2.2.16.md`; entries for 1.0.0 through 2.0.7 at `docs/archive/CHANGELOG-1.0.0-2.0.7.md` (neither is shipped in the npm package).
|
package/README.md
CHANGED
|
@@ -108,6 +108,7 @@ Maintainer/debug commands (advanced workflows, not team onboarding):
|
|
|
108
108
|
|
|
109
109
|
- `ukit diff` — preview file changes before install
|
|
110
110
|
- `ukit doctor` — validate UKit state and docs baseline
|
|
111
|
+
- `ukit doctor --prune-registry [--dry-run]` — drop user-registry entries whose project root provably no longer exists (unmounted volumes, stat errors and entries with user memory are kept; `--dry-run` prints counts only)
|
|
111
112
|
- `ukit uninstall` — remove UKit-managed assets
|
|
112
113
|
- `ukit status` — inspect shared UKit runtime state
|
|
113
114
|
- `ukit memory ...` — inspect/export/forget shared memory items
|
|
@@ -223,7 +223,18 @@ entries:
|
|
|
223
223
|
validation: [manual]
|
|
224
224
|
archive_policy: never
|
|
225
225
|
budget: { max_lines: 110, enforcement: warning }
|
|
226
|
-
notes: 'recalibrated TASK-217: actual 82 lines; 200 was ~2.4× actual — 110 leaves ~34% headroom'
|
|
226
|
+
notes: 'recalibrated TASK-217: actual 82 lines; 200 was ~2.4× actual — 110 leaves ~34% headroom. 3.5.4: the core is capped at 150 lines / 12000 bytes by `ukit memory check`; this warning budget stays tighter'
|
|
227
|
+
- id: docs-memory-detail
|
|
228
|
+
path: docs/memory/
|
|
229
|
+
class: canonical
|
|
230
|
+
audience: [agent, maintainer]
|
|
231
|
+
owner: product
|
|
232
|
+
source_of_truth: docs/memory/
|
|
233
|
+
merge_strategy: none
|
|
234
|
+
load_policy: on-demand
|
|
235
|
+
validation: [manual]
|
|
236
|
+
archive_policy: never
|
|
237
|
+
notes: '3.5.4: verbatim detail for the one-line items in docs/MEMORY.md; listed in memory.sources so recall still reaches it'
|
|
227
238
|
- id: docs-project
|
|
228
239
|
path: docs/PROJECT.md
|
|
229
240
|
class: canonical
|
|
@@ -1654,6 +1654,18 @@ items:
|
|
|
1654
1654
|
packs:
|
|
1655
1655
|
- core
|
|
1656
1656
|
|
|
1657
|
+
- id: hook-session-episode-start-module
|
|
1658
|
+
type: hook
|
|
1659
|
+
sourceTemplate: .claude/hooks/session-episode-start.mjs
|
|
1660
|
+
targetPath: .claude/hooks/session-episode-start.mjs
|
|
1661
|
+
requires:
|
|
1662
|
+
- ukit-runtime-scripts
|
|
1663
|
+
mergeStrategy: overwrite_with_backup
|
|
1664
|
+
variables: []
|
|
1665
|
+
enabledByDefault: true
|
|
1666
|
+
packs:
|
|
1667
|
+
- core
|
|
1668
|
+
|
|
1657
1669
|
- id: hook-session-episode
|
|
1658
1670
|
type: hook
|
|
1659
1671
|
sourceTemplate: .claude/hooks/session-episode.sh
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ngockhoale/ukit",
|
|
3
|
-
"version": "3.5.
|
|
3
|
+
"version": "3.5.4",
|
|
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",
|
|
@@ -53,6 +53,38 @@
|
|
|
53
53
|
"!scripts/audit/c100/usage-provenance.mjs",
|
|
54
54
|
"!scripts/audit/decision-coverage.mjs",
|
|
55
55
|
"!scripts/audit/subagent-cost/**",
|
|
56
|
+
"!src/render/instructionRenderer.js",
|
|
57
|
+
"!src/diagnostics/ompStallSnapshot.js",
|
|
58
|
+
"!src/diagnostics/classifyHang.js",
|
|
59
|
+
"!src/skill/auditSkill.js",
|
|
60
|
+
"!src/core/observability/evaluation/perturbation.js",
|
|
61
|
+
"!src/core/observability/evaluation/experimentPlan.js",
|
|
62
|
+
"!src/core/agentRuntime/context.js",
|
|
63
|
+
"!src/core/agentRuntime/runtimeSupport.js",
|
|
64
|
+
"!src/core/agentRuntime/completionGate.js",
|
|
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
|
+
"!src/core/observability/evaluation/scorecard.js",
|
|
72
|
+
"!src/core/observability/evaluation/replay.js",
|
|
73
|
+
"!src/core/observability/emit/sessionBoot.js",
|
|
74
|
+
"!src/core/observability/schema/compatibility.js",
|
|
75
|
+
"!src/core/observability/support/renderer.js",
|
|
76
|
+
"!src/core/reviewPanelAggregate.js",
|
|
77
|
+
"!src/core/taskBudgetValidator.js",
|
|
78
|
+
"!src/core/taskProgressGuard.js",
|
|
79
|
+
"!src/core/handoffDocValidator.js",
|
|
80
|
+
"!src/core/codeintel/manifest.js",
|
|
81
|
+
"!src/index/reviewPolicy.js",
|
|
82
|
+
"!src/index/impactContext.js",
|
|
83
|
+
"!src/index/contextPack.js",
|
|
84
|
+
"!src/index/sensitivePath.js",
|
|
85
|
+
"!src/decision/reviewVerdict.js",
|
|
86
|
+
"!src/decision/runtimeScheduler.js",
|
|
87
|
+
"!src/decision/runtimeFilter.js",
|
|
56
88
|
"!scripts/bench/**",
|
|
57
89
|
"scripts/bench/decision-runtime-metrics.mjs",
|
|
58
90
|
"!scripts/perf/**",
|
|
@@ -61,6 +93,7 @@
|
|
|
61
93
|
"!template_project/**/.smbdelete*",
|
|
62
94
|
"!template_project/.smbdelete*",
|
|
63
95
|
"!template_project/.ukit/**",
|
|
96
|
+
"!template_project/instructions/overlays/repo.md",
|
|
64
97
|
"!template_project/**/skill-router-state.json",
|
|
65
98
|
"CHANGELOG.md",
|
|
66
99
|
"template_project/.gitignore",
|
|
@@ -30,6 +30,7 @@ import { inspectPermissions } from '../../core/permissionDoctor.js';
|
|
|
30
30
|
import { inspectHookChainHealth } from '../../core/hookChainDoctor.js';
|
|
31
31
|
import { findOpencodeArtifacts, opencodeSteerMessage } from '../../core/opencodeSteer.js';
|
|
32
32
|
import { buildUserPaths } from '../../core/userPaths.js';
|
|
33
|
+
import { pruneRegistry } from '../../core/memory/registryPrune.js';
|
|
33
34
|
import { loadPlaybooks } from '../../core/userPlaybooks.js';
|
|
34
35
|
import { userMemoryStats } from '../../core/memory/userMemory.js';
|
|
35
36
|
import {
|
|
@@ -54,8 +55,8 @@ import {
|
|
|
54
55
|
} from '../../core/observability/support/schedule.js';
|
|
55
56
|
|
|
56
57
|
export const DOCTOR_HELP_FLAGS = new Set(['--help', '-h']);
|
|
57
|
-
const KNOWN_FLAGS = new Set([...DOCTOR_HELP_FLAGS, '--skills', '--gateway', '--docs', '--permissions', '--conformance', '--json']);
|
|
58
|
-
const SUPPORTED_FLAGS_LIST = '--help, -h, --skills, --gateway, --docs, --permissions, --conformance, --json';
|
|
58
|
+
const KNOWN_FLAGS = new Set([...DOCTOR_HELP_FLAGS, '--skills', '--gateway', '--docs', '--permissions', '--conformance', '--json', '--prune-registry', '--dry-run']);
|
|
59
|
+
const SUPPORTED_FLAGS_LIST = '--help, -h, --skills, --gateway, --docs, --permissions, --conformance, --json, --prune-registry, --dry-run';
|
|
59
60
|
|
|
60
61
|
export function printDoctorHelp() {
|
|
61
62
|
console.log('Usage: ukit doctor [options]');
|
|
@@ -68,6 +69,8 @@ export function printDoctorHelp() {
|
|
|
68
69
|
console.log(' --gateway Live gateway probe (streaming + non-streaming); advisory only');
|
|
69
70
|
console.log(' --docs Run doc-contract checks (manifests/documentation.yaml projects only)');
|
|
70
71
|
console.log(' --permissions Print the full per-host permission report table');
|
|
72
|
+
console.log(' --prune-registry Remove user-registry entries whose project root provably no longer exists');
|
|
73
|
+
console.log(' (unmounted volumes, stat errors and entries with user memory are kept); add --dry-run to print counts only');
|
|
71
74
|
console.log(' --json Emit the permission report as JSON ({permissions:{...}})');
|
|
72
75
|
console.log(' --conformance Print the engine conformance matrix (enforcement class per host)');
|
|
73
76
|
}
|
|
@@ -315,6 +318,39 @@ async function inspectCodexSurface({ projectRoot, packageRoot }) {
|
|
|
315
318
|
};
|
|
316
319
|
}
|
|
317
320
|
|
|
321
|
+
// Lines for `ukit doctor`: cli.json missing / invalid / older than the installed runtime,
|
|
322
|
+
// plus the last reason a hook refused to write episodes (episode-cli.json).
|
|
323
|
+
export async function inspectEpisodeCli({ projectRoot, runtimeVersion = null }) {
|
|
324
|
+
const readJson = async (rel) => {
|
|
325
|
+
try { return JSON.parse(await fs.readFile(path.join(projectRoot, rel), 'utf8')); } catch { return null; }
|
|
326
|
+
};
|
|
327
|
+
const lines = [];
|
|
328
|
+
const loc = await readJson(path.join('.ukit', 'storage', 'cli.json'));
|
|
329
|
+
const vnum = (v) => (/(\d+)\.(\d+)\.(\d+)/.exec(String(v ?? '')) ?? []).slice(1).map(Number);
|
|
330
|
+
const older = (a, b) => {
|
|
331
|
+
const x = vnum(a); const y = vnum(b);
|
|
332
|
+
if (x.length !== 3 || y.length !== 3) return false;
|
|
333
|
+
for (let i = 0; i < 3; i += 1) if (x[i] !== y[i]) return x[i] < y[i];
|
|
334
|
+
return false;
|
|
335
|
+
};
|
|
336
|
+
if (!loc || typeof loc.node !== 'string' || typeof loc.bin !== 'string') {
|
|
337
|
+
lines.push('WARN episode CLI locator (.ukit/storage/cli.json) missing or invalid - rerun ukit install');
|
|
338
|
+
} else if (!(await pathExists(loc.bin)) || !(await pathExists(loc.node))) {
|
|
339
|
+
lines.push('WARN episode CLI locator points at a missing node/bin - rerun ukit install');
|
|
340
|
+
} else if (runtimeVersion && older(loc.version, runtimeVersion)) {
|
|
341
|
+
lines.push(`WARN episode CLI locator is stale (cli.json ${loc.version} < runtime ${runtimeVersion}) - rerun ukit install`);
|
|
342
|
+
}
|
|
343
|
+
const state = await readJson(path.join('.ukit', 'storage', 'learning', 'episode-cli.json'));
|
|
344
|
+
if (state && state.ok === false && state.reason) lines.push(`WARN episodes not written by hooks: ${state.reason} (${state.at ?? 'unknown time'})`);
|
|
345
|
+
const last = await readJson(path.join('.ukit', 'storage', 'learning', 'episode-start-result.json'));
|
|
346
|
+
if (last) {
|
|
347
|
+
if (last.ok === true) lines.push(`episode start trigger: last run ok (recorded=${last.recorded} skipped=${last.skipped} failed=${last.failed}) at ${last.at}`);
|
|
348
|
+
else if (last.ok === false) lines.push(`WARN episode start trigger: last run failed - ${last.reason} (${last.at})`);
|
|
349
|
+
else lines.push(`WARN episode start trigger: last worker never finished (started ${last.at})`);
|
|
350
|
+
}
|
|
351
|
+
return lines;
|
|
352
|
+
}
|
|
353
|
+
|
|
318
354
|
function printCodexSurfaceSection(surface) {
|
|
319
355
|
const mark = (v) => (v ? '✓' : '✗');
|
|
320
356
|
console.log('[UKit] Codex surface checks (advisory — never affects exit code):');
|
|
@@ -430,6 +466,15 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir =
|
|
|
430
466
|
return;
|
|
431
467
|
}
|
|
432
468
|
|
|
469
|
+
// Standalone maintenance surface: prune stale project-registry entries (counts only).
|
|
470
|
+
if (argv.includes('--prune-registry')) {
|
|
471
|
+
const dryRun = argv.includes('--dry-run');
|
|
472
|
+
const r = await pruneRegistry({ homeDir, dryRun, keepRoots: [projectRoot] });
|
|
473
|
+
console.log(`[UKit] registry prune${dryRun ? ' (dry-run, nothing written)' : ''}: status=${r.status} total=${r.total} stale=${r.stale} removed=${r.removed} keptWithMemory=${r.keptWithMemory} unproven=${r.unproven}`);
|
|
474
|
+
if (r.status !== 'ok' && r.status !== 'no-registry') process.exitCode = 1;
|
|
475
|
+
return;
|
|
476
|
+
}
|
|
477
|
+
|
|
433
478
|
// TASK-006 / FR-006 — `--json` is a machine surface: emit ONLY the permission
|
|
434
479
|
// report object (plus TASK-016's flight-recorder snapshot), exit 1 when any
|
|
435
480
|
// FAIL class fires.
|
|
@@ -767,6 +812,14 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir =
|
|
|
767
812
|
// enters `checks` or `projectChecks` and cannot move the exit code.
|
|
768
813
|
printCodexSurfaceSection(await inspectCodexSurface({ projectRoot, packageRoot }));
|
|
769
814
|
|
|
815
|
+
// 3.5.4 — episode CLI locator. Advisory: a missing/stale cli.json makes episode hooks
|
|
816
|
+
// fall back to a PATH `ukit` (refused when older than the runtime).
|
|
817
|
+
if (installMeta) {
|
|
818
|
+
for (const line of await inspectEpisodeCli({ projectRoot, runtimeVersion: installMeta.version })) {
|
|
819
|
+
console.log(`[UKit] ${line}`);
|
|
820
|
+
}
|
|
821
|
+
}
|
|
822
|
+
|
|
770
823
|
|
|
771
824
|
// TASK-C85-014 (BL-014) — verification-map recipe check. Advisory only:
|
|
772
825
|
// warn rows never enter the blocking set and never fabricate a command —
|
|
@@ -8,7 +8,7 @@ import {
|
|
|
8
8
|
import { resolveContext } from '../../index/resolveContext.js';
|
|
9
9
|
import { deriveVerificationPlan } from '../../index/verificationPlan.js';
|
|
10
10
|
import { deriveTaskRoute } from '../../index/taskRouting.js';
|
|
11
|
-
import { queryCodeIndex, getFileOutline } from '../../index/queryIndex.js';
|
|
11
|
+
import { queryCodeIndex, getFileOutline, queryMatchedSymbolNames } from '../../index/queryIndex.js';
|
|
12
12
|
import { triageBug } from '../../bug/triageBug.js';
|
|
13
13
|
import { installIndexRefreshHooks, removeIndexRefreshHooks } from '../../index/gitHooks.js';
|
|
14
14
|
import fs from 'node:fs/promises';
|
|
@@ -72,8 +72,13 @@ export async function runIndexTools({ projectRoot, argv = [] }) {
|
|
|
72
72
|
limit: Number.isNaN(limit) ? 5 : limit,
|
|
73
73
|
});
|
|
74
74
|
|
|
75
|
+
const contentLaneNotice = results.contentLaneTruncated?.length
|
|
76
|
+
? `content-lane: truncated (${results.contentLaneTruncated.join(',')}) — results may be incomplete`
|
|
77
|
+
: null;
|
|
78
|
+
|
|
75
79
|
if (results.length === 0) {
|
|
76
80
|
console.log('[UKit] No index matches found.');
|
|
81
|
+
if (contentLaneNotice) console.log(contentLaneNotice);
|
|
77
82
|
return;
|
|
78
83
|
}
|
|
79
84
|
|
|
@@ -88,9 +93,10 @@ export async function runIndexTools({ projectRoot, argv = [] }) {
|
|
|
88
93
|
console.log(` reasons: ${item.reasons.join(', ')}`);
|
|
89
94
|
}
|
|
90
95
|
if (showOutline && idx < OUTLINE_TOP_FILES_LIMIT) {
|
|
91
|
-
await printOutlineForFile(projectRoot, item.filePath);
|
|
96
|
+
await printOutlineForFile(projectRoot, item.filePath, queryMatchedSymbolNames(item));
|
|
92
97
|
}
|
|
93
98
|
}
|
|
99
|
+
if (contentLaneNotice) console.log(contentLaneNotice);
|
|
94
100
|
return;
|
|
95
101
|
}
|
|
96
102
|
|
|
@@ -418,8 +424,8 @@ async function refreshIndexIfStale(rootDir) {
|
|
|
418
424
|
return true;
|
|
419
425
|
}
|
|
420
426
|
|
|
421
|
-
async function printOutlineForFile(rootDir, filePath) {
|
|
422
|
-
const outline = await getFileOutline({ rootDir, filePath, limit: Infinity });
|
|
427
|
+
async function printOutlineForFile(rootDir, filePath, focus = null) {
|
|
428
|
+
const outline = await getFileOutline({ rootDir, filePath, limit: Infinity, focus });
|
|
423
429
|
if (outline.length === 0) {
|
|
424
430
|
return;
|
|
425
431
|
}
|