@ngockhoale/ukit 3.5.2 → 3.5.3
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 +17 -90
- package/README.md +1 -0
- package/package.json +8 -1
- package/src/cli/commands/doctor.js +14 -2
- package/src/cli/commands/memory.js +30 -2
- package/src/core/memory/memoryHit.js +2 -0
- package/src/core/memory/mutateMemory.js +9 -0
- package/src/core/memory/projectIdentity.js +9 -2
- package/src/core/memory/recallEngine.js +86 -4
- package/src/core/memory/registryPrune.js +230 -0
- package/src/core/memory/retrieval.js +12 -3
- package/src/core/runtimeConfig.js +1 -1
- package/src/index/queryIndex.js +151 -20
- package/template_project/.claude/ukit/index/edit-graph.mjs +141 -11
- package/template_project/.claude/ukit/index/lib/index-core.mjs +149 -19
- package/template_project/.claude/ukit/index/resolve-context.mjs +1 -1
- package/template_project/.claude/ukit/index/route-task.mjs +4 -1
- package/template_project/.claude/ukit/runtime/memory-lanes.mjs +44 -22
- package/template_project/.claude/ukit/runtime/memory-recall.mjs +86 -4
- package/template_project/.claude/ukit/runtime/memory-validity.mjs +232 -0
- package/template_project/.claude/ukit/runtime/reinject-context.mjs +4 -2
- package/src/core/observability/evaluation/experimentPlan.js +0 -95
- package/src/core/observability/evaluation/perturbation.js +0 -273
- package/src/diagnostics/classifyHang.js +0 -246
- package/src/diagnostics/ompStallSnapshot.js +0 -199
- 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,22 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to UKit are documented here.
|
|
4
4
|
|
|
5
|
+
## 3.5.3 - 2026-11-15
|
|
6
|
+
|
|
7
|
+
Source index ranking, and memory that knows when the code it describes has changed. Every number below was measured on this repository only.
|
|
8
|
+
|
|
9
|
+
- **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.
|
|
10
|
+
- **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.
|
|
11
|
+
- **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.
|
|
12
|
+
- **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.
|
|
13
|
+
- **A record that another record supersedes is no longer returned** (`supersedes` on memory records; markdown bullets have no such field yet).
|
|
14
|
+
- **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.
|
|
15
|
+
- **"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.
|
|
16
|
+
- **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.
|
|
17
|
+
- **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.
|
|
18
|
+
- 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.
|
|
19
|
+
- 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).
|
|
20
|
+
|
|
5
21
|
## 3.5.2 - 2026-11-15
|
|
6
22
|
|
|
7
23
|
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 +50,6 @@ First release of the memory line (3.5.x). Recall now returns the project's writt
|
|
|
34
50
|
- 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
51
|
- 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
52
|
|
|
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
53
|
## 3.4.22 - 2026-10-07
|
|
127
54
|
|
|
128
55
|
**Windows: `.sh` hooks no longer deny every Edit/Write/Bash.**
|
|
@@ -243,4 +170,4 @@ UKit gains a fourth runtime and loses one. omp (Oh My Pi) reaches full parity wi
|
|
|
243
170
|
|
|
244
171
|
**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
172
|
|
|
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).
|
|
173
|
+
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
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ngockhoale/ukit",
|
|
3
|
-
"version": "3.5.
|
|
3
|
+
"version": "3.5.3",
|
|
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,12 @@
|
|
|
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",
|
|
56
62
|
"!scripts/bench/**",
|
|
57
63
|
"scripts/bench/decision-runtime-metrics.mjs",
|
|
58
64
|
"!scripts/perf/**",
|
|
@@ -61,6 +67,7 @@
|
|
|
61
67
|
"!template_project/**/.smbdelete*",
|
|
62
68
|
"!template_project/.smbdelete*",
|
|
63
69
|
"!template_project/.ukit/**",
|
|
70
|
+
"!template_project/instructions/overlays/repo.md",
|
|
64
71
|
"!template_project/**/skill-router-state.json",
|
|
65
72
|
"CHANGELOG.md",
|
|
66
73
|
"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
|
}
|
|
@@ -430,6 +433,15 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir =
|
|
|
430
433
|
return;
|
|
431
434
|
}
|
|
432
435
|
|
|
436
|
+
// Standalone maintenance surface: prune stale project-registry entries (counts only).
|
|
437
|
+
if (argv.includes('--prune-registry')) {
|
|
438
|
+
const dryRun = argv.includes('--dry-run');
|
|
439
|
+
const r = await pruneRegistry({ homeDir, dryRun, keepRoots: [projectRoot] });
|
|
440
|
+
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}`);
|
|
441
|
+
if (r.status !== 'ok' && r.status !== 'no-registry') process.exitCode = 1;
|
|
442
|
+
return;
|
|
443
|
+
}
|
|
444
|
+
|
|
433
445
|
// TASK-006 / FR-006 — `--json` is a machine surface: emit ONLY the permission
|
|
434
446
|
// report object (plus TASK-016's flight-recorder snapshot), exit 1 when any
|
|
435
447
|
// FAIL class fires.
|
|
@@ -31,6 +31,8 @@ import { pathExists } from '../../core/fileOps.js';
|
|
|
31
31
|
import { detectProjectContext } from '../../context/detectProjectContext.js';
|
|
32
32
|
import { episodeText, readRouteState, resolveLedger, writeEpisode } from '../../core/memory/episodes.js';
|
|
33
33
|
import { archiveLegacyEpisodes, purgeArchivedEpisode, restoreArchivedEpisodes } from '../../core/memory/episodeArchive.js';
|
|
34
|
+
import { loadMarkdownDocs, normalizeMemorySources } from '../../core/memory/recallEngine.js';
|
|
35
|
+
import { captureAnchors } from '../../../template_project/.claude/ukit/runtime/memory-validity.mjs';
|
|
34
36
|
import fs from 'node:fs/promises';
|
|
35
37
|
import os from 'node:os';
|
|
36
38
|
import path from 'node:path';
|
|
@@ -167,6 +169,32 @@ async function runMemoryV2(projectRoot, homeDir, args) {
|
|
|
167
169
|
return;
|
|
168
170
|
}
|
|
169
171
|
|
|
172
|
+
if (op === 'confirm') {
|
|
173
|
+
// Re-anchor a note to its named files' current state (clears the
|
|
174
|
+
// "[source changed since noted — verify]" marker). Record id or markdown path:line.
|
|
175
|
+
const id = rest.join(' ').trim();
|
|
176
|
+
if (!id) {
|
|
177
|
+
throw new Error('Missing id. Usage: ukit memory v2 confirm <record-id | path:line>');
|
|
178
|
+
}
|
|
179
|
+
let doc = null;
|
|
180
|
+
const record = await getRecord(projectRoot, id, { homeDir });
|
|
181
|
+
if (record) {
|
|
182
|
+
doc = { id: `record:${record.id}`, type: record.type, provenance: record.provenance, text: record.text, evidence: record.evidence };
|
|
183
|
+
} else {
|
|
184
|
+
const { config } = await inspectRuntimeConfig(projectRoot, { homeDir });
|
|
185
|
+
const mdDocs = await loadMarkdownDocs(projectRoot, normalizeMemorySources(config)).catch(() => []);
|
|
186
|
+
doc = mdDocs.find((d) => d.provenance === id || d.id === id) ?? null;
|
|
187
|
+
}
|
|
188
|
+
if (!doc) {
|
|
189
|
+
throw new Error(`Memory item not found: ${id}`);
|
|
190
|
+
}
|
|
191
|
+
const n = await captureAnchors(projectRoot, [doc]);
|
|
192
|
+
console.log(n > 0
|
|
193
|
+
? `[UKit] confirmed ${id}: anchored to current source state.`
|
|
194
|
+
: `[UKit] ${id} names no existing file; nothing to anchor.`);
|
|
195
|
+
return;
|
|
196
|
+
}
|
|
197
|
+
|
|
170
198
|
if (op === 'promote') {
|
|
171
199
|
const id = rest.join(' ').trim();
|
|
172
200
|
if (!id) {
|
|
@@ -276,7 +304,7 @@ async function runMemoryV2(projectRoot, homeDir, args) {
|
|
|
276
304
|
console.log(`[UKit] v2 store: ${stats.total} record(s) — ${JSON.stringify(stats.byType)}`);
|
|
277
305
|
return;
|
|
278
306
|
}
|
|
279
|
-
throw new Error(`Unknown memory v2 op: ${op}. Expected list|show|promote|stale|migrate.`);
|
|
307
|
+
throw new Error(`Unknown memory v2 op: ${op}. Expected list|show|confirm|promote|stale|migrate.`);
|
|
280
308
|
}
|
|
281
309
|
|
|
282
310
|
// ---- `ukit memory --user` — user-level store at ~/.ukit (FR-011) ----
|
|
@@ -1029,6 +1057,6 @@ export function printMemoryHelp() {
|
|
|
1029
1057
|
console.log(' backup [--out <dir>] [--user] Snapshot v2 store(s) + sha256 manifest into a backup dir');
|
|
1030
1058
|
console.log(' restore <dir> [--dry-run] [--user] Restore store(s) from a backup dir (plan only with --dry-run)');
|
|
1031
1059
|
console.log(' doctor [--user] Diagnose v2 store state + counts + quarantine (read-only)');
|
|
1032
|
-
console.log(' v2 <list|show|promote|stale|migrate> Operate on the project v2 record store (migrate supports --dry-run plan output)');
|
|
1060
|
+
console.log(' v2 <list|show|confirm|promote|stale|migrate> Operate on the project v2 record store (migrate supports --dry-run plan output)');
|
|
1033
1061
|
console.log(' --user [v2] <list|add|get|update|forget|purge|stats> Operate on the user-level store at ~/.ukit/storage/memory/v2/records.json (purge requires --confirm)');
|
|
1034
1062
|
}
|
|
@@ -67,6 +67,7 @@ export function buildMemoryHit(record, { freshness = null, score = 0, reasons =
|
|
|
67
67
|
summary: snippet,
|
|
68
68
|
source: record?.type ?? null,
|
|
69
69
|
timestamp: createdAt,
|
|
70
|
+
...(record?.validity ? { validity: record.validity } : {}),
|
|
70
71
|
};
|
|
71
72
|
}
|
|
72
73
|
|
|
@@ -115,6 +116,7 @@ export function buildMarkdownHit(doc, { score = 0 } = {}) {
|
|
|
115
116
|
source: 'markdown',
|
|
116
117
|
timestamp: 0,
|
|
117
118
|
provenance: doc.provenance,
|
|
119
|
+
...(doc.validity ? { validity: doc.validity } : {}),
|
|
118
120
|
};
|
|
119
121
|
}
|
|
120
122
|
|
|
@@ -28,6 +28,7 @@ import { guardWritePayload, redactWritePayload } from './writeGuard.js';
|
|
|
28
28
|
import { classifyWrite, mergeEvidence, REVIEW_QUEUE_MAX } from './writeClassification.js';
|
|
29
29
|
import { resolveMemoryStage, appendRolloutReceipt, latencyBandForMs } from './memoryFlags.js';
|
|
30
30
|
import { resolveProjectIdentity } from './projectIdentity.js';
|
|
31
|
+
import { captureAnchors } from '../../../template_project/.claude/ukit/runtime/memory-validity.mjs';
|
|
31
32
|
|
|
32
33
|
const JOURNAL_MAX = 256;
|
|
33
34
|
const OPS = new Set(['add', 'update', 'archive', 'forget', 'purge', 'restore', 'relocate']);
|
|
@@ -351,6 +352,14 @@ export async function mutateMemory(target, envelope = {}, { classifyAdd, guard,
|
|
|
351
352
|
latencyBand: latencyBandForMs(Date.now() - startedAt),
|
|
352
353
|
});
|
|
353
354
|
}
|
|
355
|
+
// 3.5.3: anchor a freshly written note to the files it names (sidecar only,
|
|
356
|
+
// outside the store lock, never fails the write).
|
|
357
|
+
if (result?.status === 'ok' && op === 'add' && target.kind === 'project' && result.record && result.reason !== 'review') {
|
|
358
|
+
await captureAnchors(target.projectRoot, [{
|
|
359
|
+
id: `record:${result.record.id}`, type: result.record.type, provenance: result.record.provenance,
|
|
360
|
+
text: result.record.text, evidence: result.record.evidence,
|
|
361
|
+
}]).catch(() => 0);
|
|
362
|
+
}
|
|
354
363
|
return result;
|
|
355
364
|
} catch (error) {
|
|
356
365
|
if (error instanceof StoreCorruptError || error?.name === 'StoreCorruptError') {
|
|
@@ -3,6 +3,7 @@ import path from 'node:path';
|
|
|
3
3
|
import crypto from 'node:crypto';
|
|
4
4
|
import { readJsonIfExists, writeJson, withFileLock } from '../fileOps.js';
|
|
5
5
|
import { buildUserPaths } from '../userPaths.js';
|
|
6
|
+
import { maybeAutoPrune } from './registryPrune.js';
|
|
6
7
|
|
|
7
8
|
/**
|
|
8
9
|
* Host-owned stable project identity resolver (M01-01, SPEC §5 FR-001..003).
|
|
@@ -225,7 +226,7 @@ export async function resolveProjectIdentity(projectRoot, { homeDir, mint = true
|
|
|
225
226
|
if (fresh === null) return null; // became corrupt between read and lock
|
|
226
227
|
const existing = findByRoot(fresh, realRoot)
|
|
227
228
|
?? (commonDir ? findByGitCommonDir(fresh, commonDir) : null);
|
|
228
|
-
if (existing) return existing;
|
|
229
|
+
if (existing) return { projectId: existing, entryCount: 0 };
|
|
229
230
|
|
|
230
231
|
const now = new Date().toISOString();
|
|
231
232
|
const projectId = mintProjectId(realRoot);
|
|
@@ -238,10 +239,16 @@ export async function resolveProjectIdentity(projectRoot, { homeDir, mint = true
|
|
|
238
239
|
};
|
|
239
240
|
indexAliases(fresh, projectId, aliases);
|
|
240
241
|
await writeJson(regPath, fresh);
|
|
241
|
-
return projectId;
|
|
242
|
+
return { projectId, entryCount: Object.keys(fresh.projects).length };
|
|
242
243
|
});
|
|
243
244
|
|
|
244
245
|
if (minted === undefined || minted === null) return unverified;
|
|
246
|
+
if (typeof minted === 'object') {
|
|
247
|
+
// Amortised stale-entry cleanup (never awaited by the caller's deadline path beyond its
|
|
248
|
+
// own bounded budget; failure-proof). Runs after the lock is released.
|
|
249
|
+
await maybeAutoPrune({ homeDir, entryCount: minted.entryCount, currentRoot: realRoot });
|
|
250
|
+
return { projectId: minted.projectId, source: 'registry', ambiguous: false, aliases };
|
|
251
|
+
}
|
|
245
252
|
return { projectId: minted, source: 'registry', ambiguous: false, aliases };
|
|
246
253
|
}
|
|
247
254
|
|
|
@@ -161,6 +161,69 @@ export function docTokens(doc) {
|
|
|
161
161
|
return tokenize(text.replace(EPISODE_LABEL_RE, ' '));
|
|
162
162
|
}
|
|
163
163
|
|
|
164
|
+
// Source-validity marker shown next to an item whose anchored file changed or
|
|
165
|
+
// vanished (set on docs as `validity` by memory-validity.mjs).
|
|
166
|
+
export const STALE_MARKER = '[source changed since noted — verify]';
|
|
167
|
+
export const RRF_K = 60;
|
|
168
|
+
export const validityRank = (doc) => (doc?.validity === 'missing' ? 2 : doc?.validity === 'changed' ? 1 : 0);
|
|
169
|
+
const bareId = (id) => String(id ?? '').replace(/^record:/, '');
|
|
170
|
+
|
|
171
|
+
// A doc is superseded when it says so (`superseded_by`) or another candidate
|
|
172
|
+
// lists it in `supersedes`: the superseding doc wins even if the old text
|
|
173
|
+
// scores higher, so the old one never reaches the ranking.
|
|
174
|
+
export function dropSuperseded(docs) {
|
|
175
|
+
const replaced = new Set();
|
|
176
|
+
for (const doc of docs) {
|
|
177
|
+
if (!doc || !Array.isArray(doc.supersedes)) continue;
|
|
178
|
+
for (const id of doc.supersedes) replaced.add(bareId(id));
|
|
179
|
+
}
|
|
180
|
+
return docs.filter((doc) => doc != null && !doc.superseded_by && !replaced.has(bareId(doc.id)));
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
// Reciprocal rank fusion over ordered id lists (best first); lists are lanes.
|
|
184
|
+
// Score = sum weight/(k + rank). Ties break on id, never on a timestamp.
|
|
185
|
+
export function fuseRanked(lanes, { k = RRF_K, weights = [] } = {}) {
|
|
186
|
+
const scores = new Map();
|
|
187
|
+
(Array.isArray(lanes) ? lanes : []).forEach((lane, idx) => {
|
|
188
|
+
const weight = Number.isFinite(weights[idx]) ? weights[idx] : 1;
|
|
189
|
+
const seen = new Set();
|
|
190
|
+
let rank = 0;
|
|
191
|
+
for (const id of lane ?? []) {
|
|
192
|
+
if (seen.has(id)) continue;
|
|
193
|
+
seen.add(id);
|
|
194
|
+
rank += 1;
|
|
195
|
+
scores.set(id, (scores.get(id) ?? 0) + weight / (k + rank));
|
|
196
|
+
}
|
|
197
|
+
});
|
|
198
|
+
return [...scores].map(([id, score]) => ({ id, score }))
|
|
199
|
+
.sort((a, b) => b.score - a.score || String(a.id).localeCompare(String(b.id)));
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
// Validity as one more fusion lane (3.5.3). `changed` (an anchored source was
|
|
203
|
+
// edited) is always labelled but only mildly demoted: lane 1 is the incoming
|
|
204
|
+
// relevance order, lane 2 the same items valid-first, fused with a small weight,
|
|
205
|
+
// so a clearly more relevant changed note still beats a weakly relevant valid
|
|
206
|
+
// one. `missing` (file gone) is labelled and ranked last. Nothing is dropped.
|
|
207
|
+
// Measurement knob UKIT_MEMORY_VALIDITY_RANK: `hard` (every changed below every
|
|
208
|
+
// valid), `label` (marker only, no rank change), `mild[:<weight>]` (default).
|
|
209
|
+
export const VALIDITY_WEIGHT = 0.35;
|
|
210
|
+
const pad = (i) => String(i).padStart(6, '0');
|
|
211
|
+
export function demoteByValidity(items, docOf = (item) => item?.doc ?? item) {
|
|
212
|
+
const list = Array.isArray(items) ? [...items] : [];
|
|
213
|
+
if (!list.some((item) => validityRank(docOf(item)) > 0)) return list;
|
|
214
|
+
const [mode, raw] = String(process.env.UKIT_MEMORY_VALIDITY_RANK ?? 'mild').split(':');
|
|
215
|
+
if (mode === 'label') return list;
|
|
216
|
+
const rank = (item) => validityRank(docOf(item));
|
|
217
|
+
if (mode === 'hard') return list.sort((a, b) => rank(a) - rank(b));
|
|
218
|
+
const weight = Number.isFinite(Number(raw)) && raw !== undefined && raw !== '' ? Number(raw) : VALIDITY_WEIGHT;
|
|
219
|
+
const byIndex = list.map((item, i) => ({ item, i }));
|
|
220
|
+
const lane1 = byIndex.map((e) => pad(e.i));
|
|
221
|
+
const lane2 = [...byIndex].sort((a, b) => rank(a.item) - rank(b.item)).map((e) => pad(e.i));
|
|
222
|
+
return fuseRanked([lane1, lane2], { weights: [1, weight] })
|
|
223
|
+
.map((e) => list[Number(e.id)])
|
|
224
|
+
.sort((a, b) => Number(rank(a) === 2) - Number(rank(b) === 2));
|
|
225
|
+
}
|
|
226
|
+
|
|
164
227
|
function idf(totalDocs, docFreq) {
|
|
165
228
|
return Math.log(1 + (totalDocs - docFreq + 0.5) / (docFreq + 0.5));
|
|
166
229
|
}
|
|
@@ -176,6 +239,8 @@ export function rankDocs(docs, query, { limit = 10 } = {}) {
|
|
|
176
239
|
ranked: [], candidateCount: 0, queryTokenCount: queryTokens.length, topScore: 0, abstained: true,
|
|
177
240
|
};
|
|
178
241
|
if (!Array.isArray(docs) || docs.length === 0 || queryTokens.length === 0) return empty;
|
|
242
|
+
docs = dropSuperseded(docs);
|
|
243
|
+
if (docs.length === 0) return empty;
|
|
179
244
|
|
|
180
245
|
const stats = [];
|
|
181
246
|
const docFreq = new Map();
|
|
@@ -222,7 +287,10 @@ export function rankDocs(docs, query, { limit = 10 } = {}) {
|
|
|
222
287
|
scored.sort((a, b) => b.score - a.score
|
|
223
288
|
|| String(a.doc.id ?? '').localeCompare(String(b.doc.id ?? '')));
|
|
224
289
|
const top = scored.length > 0 ? scored[0].score : 0;
|
|
225
|
-
|
|
290
|
+
// Temporal lane (3.5.3): validity is one more fusion lane over the docs that
|
|
291
|
+
// cleared the floor and cutoff (see demoteByValidity); nothing is dropped.
|
|
292
|
+
const ranked = demoteByValidity(scored.filter((entry) => entry.score >= RELATIVE_CUTOFF * top), (entry) => entry.doc)
|
|
293
|
+
.slice(0, limit);
|
|
226
294
|
return {
|
|
227
295
|
ranked,
|
|
228
296
|
candidateCount,
|
|
@@ -359,16 +427,30 @@ const SNIPPET_CHARS = 160;
|
|
|
359
427
|
|
|
360
428
|
// Shared hook lane: score ALL eligible docs (no newest-N pre-filter) together
|
|
361
429
|
// with the markdown source bullets, then cut. Async I/O only; never throws.
|
|
362
|
-
|
|
430
|
+
// `annotate(docs) -> Promise<docs>` is an optional caller-injected async step
|
|
431
|
+
// (source validity, 3.5.3); this file stays free of non-node imports. A failing
|
|
432
|
+
// or slow-to-throw annotate never affects recall.
|
|
433
|
+
export async function recallForHook({
|
|
434
|
+
projectRoot, query, docs = [], config = null, limit = 2, annotate = null,
|
|
435
|
+
} = {}) {
|
|
363
436
|
let markdown = [];
|
|
364
437
|
try {
|
|
365
438
|
markdown = await loadMarkdownDocs(projectRoot, normalizeMemorySources(config));
|
|
366
439
|
} catch {
|
|
367
440
|
markdown = [];
|
|
368
441
|
}
|
|
442
|
+
let pool = [...docs, ...markdown];
|
|
443
|
+
if (typeof annotate === 'function') {
|
|
444
|
+
try {
|
|
445
|
+
const annotated = await annotate(pool);
|
|
446
|
+
if (Array.isArray(annotated) && annotated.length === pool.length) pool = annotated;
|
|
447
|
+
} catch {
|
|
448
|
+
// keep the unannotated pool
|
|
449
|
+
}
|
|
450
|
+
}
|
|
369
451
|
let result;
|
|
370
452
|
try {
|
|
371
|
-
result = rankDocs(
|
|
453
|
+
result = rankDocs(pool, query, { limit });
|
|
372
454
|
} catch {
|
|
373
455
|
result = rankDocs([], '', { limit });
|
|
374
456
|
}
|
|
@@ -419,5 +501,5 @@ async function emitRecallTelemetry(projectRoot, config, result) {
|
|
|
419
501
|
export function renderMarkdownDoc(doc, maxChars = SNIPPET_CHARS) {
|
|
420
502
|
const text = String(doc?.text ?? '');
|
|
421
503
|
const body = text.length > maxChars ? `${text.slice(0, maxChars - 3)}...` : text;
|
|
422
|
-
return `[${doc?.provenance ?? 'markdown'}] ${body}`;
|
|
504
|
+
return `[${doc?.provenance ?? 'markdown'}] ${body}${doc?.validity ? ` ${STALE_MARKER}` : ''}`;
|
|
423
505
|
}
|