@ngockhoale/ukit 3.4.78 → 3.4.81

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 CHANGED
@@ -2,6 +2,28 @@
2
2
 
3
3
  All notable changes to UKit are documented here.
4
4
 
5
+ ## 3.4.81 - 2026-11-08
6
+
7
+ - 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.
8
+ - 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).
9
+ - 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).
10
+ - 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.
11
+
12
+ ## 3.4.80 - 2026-11-08
13
+
14
+ - 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.
15
+ - 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.
16
+ - 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`.
17
+ - 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`.
18
+ - 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.
19
+
20
+ ## 3.4.79 - 2026-11-07
21
+
22
+ - 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`.
23
+ - 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.
24
+ - 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).
25
+ - 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.
26
+
5
27
  ## 3.4.78 - 2026-11-06
6
28
 
7
29
  - 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.
@@ -790,212 +812,6 @@ full playbook backlog and the queued orchestrator blueprint:
790
812
  Note: `npm pack` budgets raised once for the wave (packed 3.03MB, unpacked
791
813
  9.88MB — attributed in `tests/integration/packageArtifact.test.js`).
792
814
 
793
- ## 3.3.3 - 2026-09-27
794
-
795
- Republish of 3.3.2 — npm staged-version E409 limbo (same content, version bump only).
796
-
797
- ## 3.3.2 - 2026-09-27
798
-
799
- **Agent VM driver + self-improve code lane.** CLI (list/show/status/shadow-run/evidence), driver producing promotion evidence into , self-improve step (one shadow run per reference plan per pass), and step (AUTO-<id>.md handoff task files mined from recurring failure patterns — whitelist fix classes, denylist protected lanes, ≤3/pass, never commits code). See docs/plans/AGENT_VM_DRIVER_PLAN.md + SELF_IMPROVE_CODE_LANE.md.
800
-
801
-
802
- ## Unreleased
803
- - **Self-improve `codeProposals` step — the code lane (SELF_IMPROVE_CODE_LANE plan).** After telemetry, each rate-limited pass turns mined, recurring failure patterns into **AUTO handoff task files** (`docs/AI_HANDOFF/tasks/AUTO-<seq>.md`) on the standard `_TEMPLATE.md` skeleton — frozen pattern evidence, `ready`/`S`, executor + reviewer + tests stay the quality gate. Whitelist fix classes only (timeout/hang, missing-fallback, empty-output, stale-doc); denylist targets (`src/decision/`, `src/core/agentRuntime/`, runtimeConfig, auth/security code) are skipped, never proposed; ≤3 AUTO tasks per pass; signatures already carried by `tasks/` or `archive/` files dedupe to `duplicate`. `learning.selfImprove.codeProposals` (default `true`) gates the step; `learning.selfImprove.codeProposalsCommit` is hard-false — writing a task file is the ceiling, self-improve never writes code or commits. `ukit self-improve --proposals` prints the proposal list; `--dry-run` lists would-be AUTO tasks without writing.
804
- - **`ukit vm` driver surface + shadow-run + evidence (agent-VM driver D-01..D-03).** New `src/cli/commands/vm.js` exposes `list`/`show <planId>`/`status`/`shadow-run <planId>`/`evidence <key>` over the plan library; all subcommands refuse `stage_off` (exit 2, zero writes) when `decisionRuntime.vm` is `'off'`. New `src/core/agentRuntime/shadowRun.js` `runShadowPlan(planId, {projectRoot, config, plansDir?, engineDir?, evidence?})` replays a pinned plan through a real `createVmEngine` rooted at `.ukit/storage/agent-runtime/shadow/<planId>/` with a stub `startFn` — deterministic synthetic events (RUN/WAIT_EVENT → `operation.completed`, BRANCH → first declared choice) until terminal, never throws, returns `{transitions, nodeStates, wallMs, irHash, planVersion}`. Each run appends one record to `evidence/vm.jsonl` (256 KiB rotation; `qualityDelta`/`wallP95Ratio`/`costRatio` stay `null` so shadow evidence can never self-promote); `ukit vm evidence vm` prints the `promote()` verdict verbatim without writing config.
805
-
806
- - **Self-improve `vmShadow` step (agent-VM driver D-04).** After diagnostics, each rate-limited `runSelfImprove` pass now runs one shadow-run per `planLibrary` reference plan via `agentRuntime/shadowRun.js` when `decisionRuntime.vm.stage` is `'shadow'` or higher — the first live-path caller that accumulates evidence for `PROMOTION_CRITERIA`. `off` → step `skipped` (`stage_off`), zero writes under `.ukit/storage/agent-runtime/`; driver missing, refusing, or throwing → step status `error`, the pass never throws and later steps still run.
807
-
808
- - **`ukit vm run` — evidence-gated live lane (BL-031).** `src/cli/commands/vm.js` gains `run <planId>`: a real `VmEngine`+`createSupervisor` path (`runLivePlan` in `src/core/agentRuntime/shadowRun.js`) that launches RUN-node specs declaring the supervisor contract (`spec.command`/`spec.argv` — descriptive `spec.cmd` prose is never shelled out, it fails typed), relays supervised terminal outcomes into the engine, and appends one `lane:'live'` evidence record. Stage gate: `off` → `stage_off` refuse (zero writes); `shadow` → `live_stage_required` refuse — execution requires `canary`/`default`. BL-031 promotion bar is recorded verbatim (`REPLAY_PROMOTION_BAR`: promote only if the VM catches ≥1 defect the doc pipeline missed OR cuts cycle time ≥25% at equal verdicts); `buildReplayComparison`/`recordReplayComparison` write a `replay-comparison` record to the evidence store and `ukit vm evidence` prints its verdict verbatim — `promote()` stays the only stage-advance mechanism.
809
-
810
- ## 3.3.1 - 2026-09-27
811
-
812
- - **Republish of 3.3.0, content-identical.** npm staged 3.3.0 then returned E409 "previously staged version" on retry — same staged-limbo pattern as 3.0.11→3.0.12. Version bump only; parity verified below.
813
-
814
- ## 3.3.0 - 2026-09-27
815
-
816
- **Zero-config self-improvement: every feature stage ships on, UKit collects and learns from its own data.** Fixes the gap where 2.6.8–3.2.0 built the machinery (flight recorder, memory v2, learning, decision plane) but nothing on the live hook path fed it — measured 1 telemetry record and 0 memory-v2 records after days of use.
817
-
818
- - **`ukit self-improve` — the automatic collect → learn → apply pass** (`src/learning/selfImprove.js`, `src/cli/commands/selfImprove.js`). One bounded, rate-limited (10 min), lock-guarded pass that runs after every session: (1) backfills an episode for every idle exec-ledger — engine-agnostic, fixes omp session-id mismatch and Codex having no lifecycle hooks; (2) refreshes diagnostics (failure patterns, feedback, skill accuracy); (3) computes tuning suggestions and **auto-applies** them under `learning.tuning.applyMode: 'auto'` (new default) as clamped one-step moves into `.ukit/storage/learning/tuned.json` with a 24h per-key cooldown; (4) writes repeated failure patterns as pending pattern candidates (promotion still needs `ukit memory approve`); (5) ingests stored hook/ledger telemetry, flushes, refreshes the support view. Never throws; each step isolated.
819
- - **`self-improve-trigger.mjs`** (`template_project/.claude/ukit/runtime/`): fire-and-forget launcher called from Claude `SessionEnd`/`session-episode.sh`, omp `session_stop` via the bridge, and Codex `route-task.mjs` (its only per-task entry). Detached child, returns in ms, silent no-op on any failure; opt out via `learning.selfImprove.enabled: false` or `UKIT_SELF_IMPROVE=0`.
820
- - **CLI locator** (`.ukit/storage/cli.json`, `writeCliLocator` in `metadata.js`, written by `ukit install`): absolute node + bin paths so hooks spawning the CLI work on GUI-launched hosts whose PATH lacks nvm/volta. `resolveCliLocator` validates node basename, `bin/ukit` shape and `@ngockhoale/ukit` package identity before trusting it; PATH lookup stays the fallback.
821
- - **All stage flags default on**: `routing.*` → `default`; `memoryV2.decision` → `default`; `learning.candidates`/`overlays` → `default`; `continuity.resumableRun` → `default`; `decisionRuntime.*` → `shadow` (diagnostics → `default`); `experiments.deliberation`/`dynamicWorkflow` → enabled; `observability.stage` added to code defaults (`default`). `learning.tuning.applyMode` accepts `'auto'`; tuned overlay merges via `inspectRuntimeConfig`. Rollback: per-key `stage: "off"`, `applyMode: 'manual'`, or delete `tuned.json`.
822
- - **`ukit memory episode` refactored** onto shared `src/core/memory/episodes.js` (`resolveLedger`, `episodeText`, `writeEpisode`, `backfillEpisodes`) — one owner for the record shape between the single-session command and the self-improve backfill.
823
- - Tests: 28 new (tunedOverlay clamp/merge/cooldown, episodes resolve/write/backfill dedupe, trigger locator validation + spawn contract); stale stage-default pins updated to the 3.3.0 contract.
824
-
825
-
826
-
827
- ## 3.2.0 - 2026-09-26
828
-
829
- **Agent VM / Language-Compiled Runtime phase 2 (V-01..V-06)** — IR v2 flag-gated opcodes, decisionRuntime.vm stage-promotion machinery, plan library pins, VM decision nodes via unic-decision, host parity adapters, sanitized support bundle. All new surfaces ship `off`.
830
-
831
- - **Host lane adapters for the owned runner (agent-vm-runtime V2).** `adapters.js` gains the frozen `HOST_ADAPTERS` registry plus `detectHost` (env-marker best-effort ambient engine resolution, ambiguous → `null`) and `probeHostAdapter` — honest per-host capability statuses `supported` / `unsupported-probe` / `unsupported` with typed reasons (`unknown_host`, `process_group_kill_unavailable`, `host_spawn_unavailable`, `live_host_e2e_unproven`); `supported` is reachable only via explicit `liveHostE2E` evidence, never inferred from primitive presence (G-V2). `buildHostCapabilityMap` in `runtimeSupport.js` exposes the map per lane; every lane reports `completionApi: 'eventStore-journal'` — no engine exposes a host-owned durable completion API. `createSupervisor` accepts `opts.host` and per-launch `spec.host` (precedence spec → opts → ambient detect → no lane); a lane probed `unsupported` refuses `start()` typed (`host_unknown`/`host_unsupported`, zero fs writes) while `unsupported-probe` lanes still run the identical spawn → journal → terminal contract. Live-E2E gap for claude-code/codex is documented in the task file — never claimed as supported.
832
- - **Agent VM V-01 — IR v2 flag gate + versioned IR contract.** IR v2 ops (`PARALLEL`, `TIMEOUT`) now parse only behind an explicit opt-in — `ir.planVersion: 'v2'` on the artifact, `opts.irVersion: 'v2'` on `compilePlan`, a caller `allowedOps` list naming them, or a non-`off` `decisionRuntime.vm` stage forwarded by `planLibrary.loadPlan({config})`. Ungated v2 IR fails with `ir_v2_disabled`; unknown version literals fail `invalid_ir_version`. `contract.js` exports `IR_VERSIONS` (`['v1','v2']`) and `ValidatedPlan` carries `irVersion` derived from ops actually used — v1 plans compile byte-identical under every flag state (planVersion unchanged). RETRY lands as the bounded per-node `retry` policy (side-effect-class aware: non-auto-retryable classes can never claim `maxAttempts > 1`; a crashed non-idempotent node stays `recovery_required` and is never re-run blind). New fault coverage: TIMEOUT firing mid-node on deliver → deterministic `escalate` replay-identically; duplicate delivery at the join is idempotent across a crash (single `completed` fold in the wrapper journal); bounded fan-out honors `maxNodes`.
833
-
834
- - **V4 plan library: release pinning + spec text.** `planLibrary.loadPlan` now returns `specText` (the human-authored spec each plan was compiled from) and `planVersion`, and enforces `PLAN_PINS` — a shipped plan whose compiled hash drifts from its pin fails with `plan_version_mismatch` instead of silently running a different workflow. Fourth reference plan `flag-promotion` (stage-promotion gate: baseline replay → shadow runs → promote/rollback branch, mirroring `promotion.js`) joins `bugfix-loop`, `handoff-review-batch`, `release-check`. Coverage: artifact-hash stability, vmEngine replay determinism per plan, malformed-artifact rejection, pin drift.
835
- - **VM decision nodes via `unic-decision` (agent-vm-runtime V5).** `vmEngine` nodes may now carry a bounded `question` block (`{decisionKey?, instruction?, candidates?}`, validated by `validateNodeQuestion` in `contract.js` and carried through `planCompiler`). When `decisionRuntime.vm.stage` is promoted past `off` and no `classifyFn` is injected, unclassifiable events are routed by `createVmClassifyFn` (`src/decision/runtimeDecide.js`) through one bounded `runtime.node_route.v1` / `runtime.node_classify.v1` question — the only two keys a node may ask (registered `rolloutStage: 'off'`, owner `vmEngine`, deterministic escalate fallback). Model answers are data only (`tool_calls` never dispatched); `model_not_found`/timeout/invalid/adapter faults all resolve to the deterministic escalation lane with a `fallbackCode`, never a hard failure — a throwing `classifyFn` now escalates too. Stage `off` (default, absent, or malformed) installs no adapter: zero decision calls, byte-identical behaviour.
836
-
837
- - **Agent VM V-06 — per-run support bundle** (`src/core/agentRuntime/diagnostics.js` `exportSupportBundle`, `eventStore.js` `readJournalExcerpt` + `summarizeEvent`, `telemetry.js` `buildTraceExcerpt`, `ukit telemetry export-run <operationId>`): one sanitized bundle per operation lands in the Data Foundation support layout — `Documents/UKit Support/proj-<sha256>/run-<sha256>/` with `journal.jsonl` (bounded code summaries only), `trace.jsonl` (double-gated span excerpt, deterministic pseudonyms), `SUMMARY.md` and a `ukit-support/1` manifest with sha256 checksums, importable via `ukit telemetry import`. Privacy: redaction before persist — secret/path/PII rules + `sanitizeForSupport` on trace records + a final assembled-bytes re-scan that blocks all writes on any residual secret; no raw prompt/diff/path content can appear. `decisionRuntime.diagnostics.stage: 'off'` → `skipped` with zero writes. Missing/corrupt journals still emit bundles with declared `gap` markers; a 256 KiB cap drops excerpt lines deterministically (`coverage.dropped_lines`).
838
-
839
- ## 3.1.9 - 2026-09-26
840
-
841
- - **Checkpoint locked to `unic-decision` for all classes.** Owner decision: the single `unic-decision` model answers every decision (English, multilingual, unknown) — the provider swaps the backend (Lava/JEV) behind that name, so UKit no longer routes per-language. `checkpoints.{default,english,unknownLanguage}` all resolve to `unic-decision` in code + shipped config; `unic-decision-multilingual` removed from defaults (remains configurable via `decisionPlane.checkpoints` if ever needed). Endpoint config unchanged: `ukit decision` / `gatewayDecision.json` / `UKIT_DECISION_*` env.
842
-
843
- - **Agent VM V-03 — stage-promotion machinery** (`src/core/agentRuntime/promotion.js`, `src/core/runtimeConfig.js`): new `resolveDecisionRuntimeStage(config, key)` resolves `decisionRuntime.<key>.stage` with `decisionPlane` semantics (absent/malformed → `off`); new pure `promote(config, evidence)` advances one family flag `off → shadow → canary → default` only when the frozen `PROMOTION_CRITERIA` hold on ≥ `minSampledRuns` sampled runs (quality delta ≥ `-QUALITY_SCORE_FLOOR`, wall-p95 and cost ratios ≤ baseline), and instant rollback (`evidence.rollback` or any forbidden failure) resolves `off` — deterministic owners authoritative, zero VM calls. `off` never self-promotes and one noisy run never flips a default. All `decisionRuntime.*` stages stay `off`: machinery only, no rollout flip.
844
-
845
- ## 3.1.8 - 2026-09-26
846
-
847
- - **Agent VM IR v2**: `PARALLEL` (bounded fan-out, `join:'all'`) and `TIMEOUT` (deadline wrapper, `onTimeout: fail|escalate`, 30-minute ceiling) opcodes added to `planCompiler` + `vmEngine`; fault-injection coverage for crash-between-fan-out-and-join, non-idempotent child recovery, duplicate delivery. v2 plans hash under a `v2:`-prefixed serialization; v1 hashes unchanged.
848
- - **Install seeds `.ukit/storage/observability/`** — the segment writer's safe `resolveRoot` rejects a missing parent, so the first emit on a fresh install previously failed with ENOENT. `ukit install` now creates the directory (advisory, never fails).
849
-
850
- ## 3.1.7 - 2026-09-26
851
-
852
- - **Observability + memory recording enabled by default on install.** Shipped `config.json` now sets `observability.stage: 'default'` (recorder + analytics + projector + evaluation — the full Data Foundation pipeline) and `learning.episodes.autoWrite: true` + `learning.candidates.stage: 'shadow'` (ukit-memory records evidence without auto-applying anything). Privacy gates (`sanitizeObserved`, `sanitizeForSupport` default-deny) are unchanged. Code defaults in `runtimeConfig.js` updated to match. New: `planLibrary.js` + 3 versioned reference plans (`bugfix-loop`, `handoff-review-batch`, `release-check`) as the V4 artifact seed for the Agent VM phase-2 plan.
853
-
854
- ## 3.1.6 - 2026-09-26
855
-
856
- - **Decision endpoint URL normalization**: a `UKIT_DECISION_BASE_URL` that already ends in `/v1` (OpenAI convention) no longer produces `…/v1/v1/chat/completions`; the client strips a trailing `/v1` before joining. Applied to `src/decision/client.js` and mirrored in `unic-decision.mjs`.
857
-
858
- ## 3.1.5 - 2026-09-26
859
-
860
- - **Install/update warns when the decision lane has no API key.** After a project refresh, `ukit install` (and `ukit update`'s refresh) prints a bold-red warning with setup instructions — `ukit decision --base-url <url> --key <key>`, `~/.ukit/storage/gatewayDecision.json`, or `UKIT_DECISION_API_KEY` — whenever no dedicated decision key and no shared UNIC token are resolvable. When a key (or the shared UNIC token fallback) is found, a one-line confirmation is printed instead.
861
-
862
- ## 3.1.4 - 2026-09-26
863
-
864
- - **`ukit decision` — user-facing decision-lane gateway setup.** Resolution order (per field): env `UKIT_DECISION_BASE_URL`/`UKIT_DECISION_API_KEY`/`UKIT_DECISION_SCHEME` → `~/.ukit/storage/gatewayDecision.json` (new per-lane file; `gateway<Lane>.json` pattern) → `~/.ukit/storage/config.json` `decisionGateway` → `openai.unicjsc.com` + shared UNIC token. File field names mirror the env vars; `scheme` selects `Authorization: Bearer` vs `x-api-key`. Both files are seeded by `ukit install` with the full key set (`mergeStrategy: skip` — `ukit update` never overwrites user values). Commands: `--status`, `--base-url/--key/--scheme`, `--set-unic`, `--clear`.
865
-
866
- ## 3.1.3 - 2026-09-26
867
-
868
- - **`unic-decision-multilingual` becomes the shipped default checkpoint** — the variant is credential-bound on UNIC Provider (verified via live `health-probe` + `safe-vs-risky-lane` decision). `english`/`unknownLanguage` classes keep the bare `unic-decision` alias; `model_not_found` auto-fallback still covers unbound variants.
869
-
870
- ## 3.1.2 - 2026-09-26
871
-
872
- - **Decision plane goes live on the UNIC provider** — the decision lane now resolves its own endpoint independent of the engine's LLM gateway, so UKit uses UNIC even when Claude Code/Codex/omp point elsewhere:
873
- - **Endpoint chain**: `~/.ukit/storage/gateway.json` `{decision:{baseUrl,apiKey,scheme}}` → env `UKIT_DECISION_BASE_URL`/`UKIT_DECISION_API_KEY` → default `https://openai.unicjsc.com`; credential falls back to the shared UNIC token (ANTHROPIC_*). New resolvers `resolveDecisionBaseUrl`/`resolveDecisionApiKey` in `src/core/gatewayProbe.js`, mirrored in `unic-decision.mjs`.
874
- - **Live transport fixes** (verified against the real gateway): SSE `data: [DONE]` trailer — sometimes glued to the JSON body — is stripped via balanced-object extraction; model answers use native arg names (`choice`/`noul`/`score`) now accepted alongside the schema's `value`; a `model_not_found` variant checkpoint retries once on the bare `unic-decision` alias.
875
- - **Checkpoints**: shipped defaults collapse to the bare `unic-decision` model (the credential-safe alias); `unic-decision-multilingual`/variants remain configurable via `decisionPlane.checkpoints`.
876
- - **Optional backlog drained**: injection-point contracts documented (deliberation `judge`, vmEngine `classifyFn`, completionGate `modelJudgment`), `memoryV2.decision` plane marked reserved, `resume.next-action.v1` + `verify.depth.v1` shadow questions wired, gatewayProbe marked migration-exempt.
877
-
878
- ## 3.1.1 - 2026-09-26
879
-
880
- - **Decision plane — review + workflow families (UNIC_DECISION_MIGRATION S1–S4)** — the reserved `review` and `workflow` registry families are now populated and wired; all keys ship `rolloutStage: 'off'` so deterministic fallbacks stay authoritative (stage promotion is a separate owner decision):
881
- - **Registry** (`src/decision/registry.js`): `review.verdict.v1`, `review.finding-bucket.v1`, `review.panel-verdict.v1`, `workflow.sidecar-lane.v1`, `workflow.sidecar-risk.v1`, `workflow.routing-needed.v1`, `workflow.step-budget.v1`, `workflow.compact-now.v1`, `workflow.summarize-vs-keep.v1` — all `choice` kind, `off`, deterministic fallback owners recorded.
882
- - **Review adapter**: `src/decision/reviewVerdict.js` + installed twin `template_project/.claude/ukit/index/review-verdict.mjs` — findings (whitelisted `{id, severity, file, line, claim}`) in, stage-gated verdict + per-finding buckets out; reviewers still generate findings on the general model, only the bounded verdict moves to `unic-decision` when `decisionPlane.families.review.stage` is enabled.
883
- - **Sidecar adapter**: `template_project/.claude/ukit/index/sidecar-decision.mjs` answers the six `.codex/settings.json` `smallTaskModel.decisionPolicy.decisions` via a bounded `unic-decision` batch (stage-gated `decisionPlane.families.workflow.stage`); adapter failure → deterministic rule answer, never another LLM.
884
- - **Engine parity**: `.codex/ukit` is a symlink to `.claude/ukit` (installed layout), `decisionAdapter` hints in `.codex/settings.json`; all three index CLIs' `isMainModule` gates now use `realpathSync` + basename equality — symlinked invocation previously compared unresolved paths and silently exited 0 without running `main()`.
885
- - **Docs/tests**: `docs/pstack/UNIC_DECISION_GUIDE.md` (family keys + adapters), `docs/GATEWAY.md` §8, `docs/MEMORY.md`; parity + symlink-invocation coverage in `tests/index/{unicDecision,reviewVerdictCli,sidecarDecision}.test.js`.
886
-
887
- ## 3.1.0 - 2026-09-26
888
-
889
- - **Flight recorder — Data Foundation wave (cycle C81)** — the observability pipeline grows from record/segment plumbing into a full local diagnostics surface; still opt-in behind `observability.stage` (default `off`, `off→shadow→canary→default` per seam, absolute kill switch):
890
- - **Envelope v1.1 + sampling**: additive `agent_id`/`project_instance_id`/`sampling` stamp fields and new semantic names (`memory.write`, `memory.retrieved`, `retrieval.query`, `outcome.observed`, `anomaly.detected`, `telemetry.crashed`); `observability.sampling` seeded-bucket keep-rates per importance level with `SAMPLED_OUT`/`CONFIG_INVALID` reason codes — `critical` is never sampled.
891
- - **Segments**: sealed segments compress to `.jsonl.zst` on Node ≥ 22.15 (plain `.jsonl` otherwise); readers, recovery, and quarantine handle both transparently.
892
- - **Crash capture + lifecycle**: bounded `crashes/crash-<boot>-<seq>.json` capture on uncaughtException/unhandledRejection/SIGINT/SIGTERM (≤10 files, FIFO, never throws); `getRecorder` memoized per (root, boot) with interval flush and deadline-bounded exit flush.
893
- - **Ingestion + instrumentation**: `ingestStoredTelemetry` pulls stored hook telemetry, route/decision ledgers, and memory/context items into segments; agentRuntime and memory/retrieval paths emit real trace/span ids with honest `UNKNOWN` resource provenance.
894
- - **CLI**: `ukit telemetry` — `status`, `collect`, `digest`, `export-support`, `import <path>`, `evaluate` (`--json` on status/digest/evaluate; exit 0/2, usage 1). `ukit doctor` gains a flight-recorder section (stage, segments, support lag, crashes — `unknown` when unavailable). `ukit feedback` emits `outcome.observed`.
895
- - **Support view**: `Documents/UKit Support` provisioned at install (never deleted by uninstall); support refresh is scheduled after collect and on the lifecycle interval, with crash list, anomaly section, and freshness lag stamped in `SUMMARY.md`; `import` validates bundles (manifest/checksums/traversal/decompression bounds).
896
- - **Anomaly detection + evaluation**: deterministic detectors (duration outliers, retry storms, cache-miss/drop-rate spikes, verification-failure clusters) produce `anomaly.detected` records with evidence refs; `runEvaluation` dispatches to a configured `observability.evaluator` provider — `skipped/no-provider` is the honest default — and appends validated findings to the optimization KB; expanded golden corpus with `--anomalies` bench flag.
897
- - **Docs**: `docs/OBSERVABILITY.md` — stages, privacy contract (what is never recorded), the support-folder zip-send flow, CLI and config reference.
898
-
899
- ## 3.0.12 - 2026-09-26
900
-
901
- - Re-publish of the 3.0.11 content: npm staged-publish left 3.0.11 in limbo (E409 "previously staged version"); re-published as 3.0.12 — same tree, version bump only.
902
-
903
- ## 3.0.11 - 2026-09-26 (staged, never published)
904
-
905
- - **C80 bug-sweep fix cycle — all 23 confirmed/high-confidence execution-path bugs fixed** (`docs/AI_HANDOFF/REPORT-C80-bug-sweep.md`):
906
- - Index CLIs (`query-index`, `triage`, `resolve-context`, `verify-context`, `impact-context`, `route-task`): top-level try/catch error boundary — unhandled-rejection crashes become clean exit(1) (C80-01..06).
907
- - `cache-utils.mjs` `readRecentCacheEntry(touch:true)`: touch-write failures degrade to in-memory entry, matching the token-utils prompt-cache contract — a full/unwritable cache can no longer reject a read (C80-02).
908
- - `index-core.mjs`: new `ensureIndexFresh` — cross-process `withFileLock` build lock + staleness re-check inside the lock; artifact caches invalidated before publish writes, not after (C80-07/08).
909
- - `frontend-vue` composables: `useRequest` ×3 `finally` decrement of `loading_count` (stuck spinner); `useWebSocket` retry dedup + cancellable timer + disposed guard; `useSession.getSession` corrupt-blob guard; `indexDBStore` promises now settle on transaction/clear errors (C80-09..16).
910
- - Skill scripts: `with_server.py` pipe deadlock + process-group kill; `init-project-docs.sh` sed escaping + backup-instead-of-rm; `document.py` deterministic `close()`; `rearrange.py` samefile compare; `find-polluter.sh` glob/quoting fixes (C80-17..22).
911
- - `supervisor.js`: listeners attach before awaited work post-spawn; liveness via injectable `probeImpl` (kill(pid,0)); `killGroup` revalidates ownership before signaling a possibly-recycled pgid (C80-23).
912
-
913
- ## 3.0.10 - 2026-09-25
914
-
915
- - Re-publish of the 3.0.9 content: npm staged-publish left 3.0.9 in limbo (E409 "previously staged version"); re-published as 3.0.10 — same tree, version bump only.
916
-
917
- ## 3.0.9 - 2026-09-25 (staged, never published)
918
-
919
- - **ukit-memory stack (cycles C57–C62, waves W1–W6)** — the full v2 memory layer lands behind staged rollout flags:
920
- - **Record store v2**: versioned `records.json` store (`src/core/memory/storeV2.js`, `recordStore.js`, `records.js`) with tombstones, generation counters, fingerprint dedupe, and a locked read-modify-write path in `mutateMemory`; automatic v1→v2 migration (`migrate.js`, `migrateMapping.js`) with `autoMigrate` config.
921
- - **Retrieval**: deny-by-default eligibility policy (`policy.js` — status/expiry/provenance/trust-tier/project-binding), generation-bound in-memory `recordIndex`, ranked hits (`memoryHit.js`, `retrieval.js`), and labeled `## Previous Context` injection that renders record text as data, never instructions.
922
- - **Freshness**: `memoryFreshness.js` resolves `evidence[].locator` with `lstat`+`realpath` containment — symlinks escaping `projectRoot` report `locator-unverifiable`, never `fresh`.
923
- - **Write safety**: `writeGuard.js`/`writeClassification.js` reject secret-bearing payloads before persist; `sensitiveValueScanner` shared.
924
- - **Backup/restore/purge**: `storeBackup.js` byte-copy backups with sha256 manifest (mode 0600), manifest boundary check (`backup-file-out-of-boundary`), tombstone precedence on restore; CLI `memory purge/export` lanes sweep `deletePromptCacheEntries` so purged content cannot resurrect from the prompt cache.
925
- - **Rollout flags (W6)**: `memoryV2.{eligibility,writer,index,decision}.stage` on the shared `off→shadow→canary→default` ladder, `canaryProjects`, and absolute `killSwitch` — read live on every operation, config-only reversal, no storage-format change. Ships at `default` for eligibility/writer/index, `off` for decision, `killSwitch: false`.
926
- - **Security review (W6)**: `tests/security/memorySecurity.test.js` (11 tests) — fixed symlink-follow in `resolveLocator` and manifest path escape in `restoreBackup`; 0 open high-severity findings.
927
- - **Gate G6**: canary delta clean (0 hit/query divergence on 2000-record seeded corpus), kill-switch drill pass on read and write legs — verdict **GO** (`docs/AI_HANDOFF/inventory/g6-verdict.md`).
928
- - **Installed mirror**: `template_project/.claude/ukit/runtime/memory-{flags,freshness,policy}.mjs` shipped for hook-side parity.
929
-
930
- ## 3.0.8 - 2026-09-24
931
-
932
- - Re-release of the 3.0.7 content: npm staged-publish left 3.0.7 in limbo (E409 "previously staged version"); re-published as 3.0.8. Tag v3.0.7 exists on the same tree.
933
-
934
- ## 3.0.7 - 2026-09-24
935
-
936
- - **Data foundation & flight recorder (cycle C54)** — new `src/core/observability/` pipeline, all behind `observability.stage` (default `off`, staged `off→shadow→canary→default` per seam with kill switch):
937
- - **Schema + privacy**: versioned record envelope (`schema_version: 1`), semantic/reason-code registry, and a two-gate privacy boundary — `sanitizeObserved` before any persistent write (allowlist + deny-list + redaction), `sanitizeForSupport` as an independent default-deny second gate.
938
- - **Recorder + segments**: bounded non-blocking `emit()` with live stage gate, span tracking, deadline-bounded flush, and append-only JSONL segments with rotation/retention and partial-tail recovery.
939
- - **Analytics**: deterministic trace summaries (p50/p95/p99, causal critical path, retry/drop/cache metrics), honest `telemetry_complete=false` on drops/gaps/UNKNOWN host usage, and rebuild-from-segments recovery.
940
- - **Support view**: `UKit Support` materialized projection under the OS-native Documents folder — bundle-local pseudonyms, atomic writes, byte caps, failure-promoted digests, and a validated import path (manifest/checksums/traversal/decompression bounds).
941
- - **Evaluation**: offline evaluator packet (summary → anomalies → digest → evidence) and an optimization knowledge base recording hypothesis → experiment → guardrails → decision → rollback.
942
- - **Rollout**: `resolveSeamStages`/`resolveSeamConfig`/`killSwitch` in `src/core/observability/rollout.js` — recorder activates at `shadow`, support projection at `canary`, evaluation at `default`; per-seam overrides are restrictive-only so a global `off` is an absolute kill.
943
- - **Privacy fix**: `error_detail` added to the deny-list (free-form text, not a code) and `REDACTION_VERSION` bumped to `df-redact-3` — fixture secrets can no longer persist in canonical segments.
944
- - **unic-decision docs**: `docs/pstack/UNIC_DECISION_GUIDE.md` documents the local Lava/JEV decision model (not an LLM), checkpoint IDs, typed `tool_calls` contract, and `modelRoles.decision` binding for omp.
945
-
946
- ## 3.0.6 - 2026-09-24
947
-
948
- - Clarified the project owner's `unic-decision` contract in owner instructions, project memory, the technical spec, and shipped internals: a local Lava/JEV model in UNIC Provider, not an LLM; the OpenAI-compatible API is transport for convenient integration, not evidence of remote hosting or generative-model pricing.
949
- - Documented the preferred bounded typed-decision usage and the existing stage-off rollout/fallback in package-side client/config comments and the installed adapter, without changing runtime behavior or enabling decision calls.
950
-
951
-
952
- ## 3.0.5 - 2026-09-24
953
-
954
- - **Review-fix hardening (cycle C53 fix round 1)** — defects found by the release reviewer after 3.0.4 shipped:
955
- - **Memory**: `appendCompactHistory` read-modify-write now runs under the store lock — concurrent appends can no longer lose entries (unlocked RMW race).
956
- - **Installed mirror**: restored the missing `index-core` declaration in the installed `.claude/ukit/` mirror so dev-mirror parity checks pass on hydrated workspaces.
957
- - **Shipped hooks**: `sensitive-data-guard` no longer bypassed by wrapper commands (`sudo`/`env`/`bash -c`/`xargs`) or basename-obfuscated invocations — the guard now unwraps wrappers and matches on the real binary name.
958
- - **Test scoping**: `payloadDocs` stale-prose sweep restricted to shipped surfaces (root docs, `template_project`, `src`, `bin`, `scripts`) — it no longer walks `docs/AI_HANDOFF/**` reports or gitignored runtime dirs; `mirrorPayload` parity now tolerates stale/runtime files under the gitignored installed mirror.
959
- - **Installed-mirror resync**: stale `index/detectProjectContext.js`, query-index cache, lock dirs, and resolve-context cache regenerated so the installed mirror matches the template payload.
960
-
961
- ## 3.0.4 - 2026-09-24
962
-
963
- - **Full source audit (cycle C53) — ~86 defects fixed across all 14 audit areas**; every fix carries a RED→GREEN regression test under `tests/audit/`:
964
- - **CLI** (`bin/ukit`, `src/cli/**`): watchdog `unref()` silent-exit-0 on hung `runCli`; `--tools=` empty value deselecting all adapters; `install --help` exiting 1; `update`/`status` silently ignoring positional/unknown args; unknown `--adapter` silently mapping to `.claude`; `--flag=a=b` truncation; `extractFlag` swallowing the next flag as a value; `memory` crash on null ledger receipt.
965
- - **Lifecycle** (`src/core` install/update/uninstall/plan): uninstall data loss — tracked *file* entries removed via recursive `fs.rm` (a user dir replacing a managed file was deleted wholesale); `cleanupEmptyParents` crash on ENOTEMPTY/ENOENT races.
966
- - **Hooks/policy/security**: `hookChainDoctor` TypeError on missing `projectRoot`; `permissionPolicy` non-array surface lists miscompiled/crashed → now fail-closed `UKIT_EPOLICY`; `unattendedDoctor` counted only `'prompt'` not `'ask'`; uppercase SHA-256 allowlist digests silently unmatched; `gatewayProbe`/`resolveGatewayApiKey` threw despite never-throw contracts; `detectCustomGatewayAsync` was a dead sync wrapper now truly async and wired.
967
- - **Handoff/contracts/compact/experiments**: 10 defects incl. forced anchors dropped past `maxLines` while still counted; unlocked read-modify-write race in `appendCompactHistory`; shallow freeze letting a judge hide hard-constraint violations; retry-corrupted `state.budget.remaining`.
968
- - **Codeintel/output/token**: duplicate call edges + edges to non-existent callee nodes; `JsonGraphStore` crash on corrupt codegraph; `semanticProvider` reading `raw.files` vs `{items}` shape (index-wide resolve always empty); `PATH_RE` misrouting "and/or"/"n/a"; `packetToText` never rendering `packet.memory`; `drainDirty` dropping `saturated` flag; `parseCheckLine` returning wrong stderr line; `summaries` provider bound to `process.cwd()`; `sweepTeeCache` unenforceable maxFiles cap; `appendOutputHistory` dropping empty-command entries.
969
- - **Memory**: `addRecord` never ran `ensureMigrated` (first v2 write stranded all v1 data); corrupt legacy JSON silently dropped and hidden from `needsMigration`; unbounded `observeLearningSignal` text; concurrent-run counter races.
970
- - **Index/routing**: `queryCodeIndex`/`queryAnalog` TypeError on non-string input; corrupt artifact `items` crashing `groupBy`; substring signal misclassification ('score'→'core', 'install '→'all '); importers ignoring aliased specifiers; `extends: "pkg"` resolving `pkg.json` not `pkg/tsconfig.json`; `shellEscape` dropping apostrophes; empty verification-plan floor; `test:*` scripts missed by `TEST_RUNNER_COMMAND`; installed index-core mirror drift re-synced.
971
- - **Decision plane**: `sanitizeValue` `__proto__` prototype mutation; half-open circuit breaker with no single-probe gate and never-refreshed `openedAt`; `invalidateLease` raw TypeError on malformed records.
972
- - **Diagnostics/render/skill/learning/stack/bug**: `ledgerFiles` omitted-limit NaN → empty results; `renderTemplate` `{{constructor}}`/`{{toString}}` rendering `[native code]`; `statusSkillAudit` crash on null entries; `knownSignaturesAndTexts` missing legacy `signature` collection; `detectStack` raw SyntaxError on corrupt package.json; `triageBug` ignoring declared `packageManager`.
973
- - **Scripts toolchain**: missing flag values silently defaulting across 9 scripts; unknown flags ignored; unhandled promise rejections; silent partial index on unreadable files; `audit-perf.mjs` unbounded `spawnSync`/`execFileSync` (hang) → 60s SIGKILL timeout.
974
- - **Shipped hooks** (`template_project/.claude/hooks`): `block-dangerous` deadline fail-open + missed bare `git push -f`; `record-execution` never armed deadline; `sensitive-data-guard` missed joined/`=` credential forms and wrapper-command bypass (`sudo`/`env`/`bash -c`/`xargs`); `session-episode` hardcoded stdin watchdog; `handoff-model-guard` silent crash exit; `auto-allow-bash` unquoted glob expansion corrupting allow rules.
975
- - **Template payload/manifests/docs**: stale dev telemetry shipped via `runtime-cache` manifest item; `pdf-processing-pro` frontmatter name mismatch; handoff-planner `§7` drift; PLAN.md seed format drift; `QUICK_START` `@ukit/cli` ref; `RULES.md` nonexistent `PLAN.md §7` reference; broken archive doc links.
976
- - **Test health**: `test:handoff` now self-installs UKit first (19/50 failures on fresh clones); stale pre-TASK-025 watchdog wiring assertion fixed; dead conditionals removed.
977
-
978
- ## 3.0.3 - 2026-09-23
979
-
980
- - Same content as 3.0.2 (npm staged-publish never finalized; re-published as 3.0.3).
981
-
982
- ## 3.0.2 - 2026-09-23
983
-
984
- - **v3 reshape leftovers + docs verify-and-close (cycles C49–C51)**:
985
- - Decision table v2: `MODEL_TIER_BY_CONTRACT` + `resolveModelTier` in `src/core/executionContracts.js` — contract→tier resolution is now data-driven.
986
- - `limits=` route-text segment behind `routing.rigor.stage` (`src/index/taskRouting.js` + `route-task.mjs` mirror; stage-off output byte-identical, 10-case suite).
987
- - Mechanical validators: `handoffDocValidator.js` + `reviewPanelAggregate.js` (+ `.mjs` CLIs) — handoff doc checks and review-panel aggregation now scriptable.
988
- - Exit-predicate loop in stop-coordinator; diversity-review contract; M05.1' program-gate verdict + pstack doc banners.
989
- - Docs: DOC-201..206 verified shipped (165/165 acceptance tests); stale STATUS.md queue pointer + 11 roadmap rows corrected.
990
-
991
- ## 3.0.1 - 2026-09-23
992
-
993
- - **Template root split (breaking-scale layout change, kept on 3.0.x per owner decision)**: `templates/` → `template_project/` (project-level install surface) and `templates/user/` → `template_user/` (user-level `~/.ukit/` seeds). `buildPathConfig` gains `userTemplatesRoot`; `platform.user.yaml` sourceTemplates resolve relative to `template_user/`. Dev mirrors re-synced (C47 drift fixed). Pre-existing test debt fixed: `packageVersion` major pin, runtime config version, `routeCatalog` principle-skill map, `packageArtifact` negation handling, `artifactReferenceIntegrity` allowlist.
994
-
995
- ## 3.0.0 - 2026-09-23
996
-
997
- - Same content as 2.8.0 — re-versioned as a major: the UserLayer/ProjectLayer split plus the new `templates/user/` template set is a breaking-scale change and belongs on 3.x. 2.8.0 is deprecated on npm.
998
-
999
815
  ## 2.8.0 - 2026-09-23
1000
816
 
1001
817
  - **User-Level `.ukit` layer (cycle C46)**: new `~/.ukit/` layer resolved via `os.homedir()` (correct on Windows/Linux/macOS), immutable on `ukit update` (`level: "user"` manifests + `mergeStrategy: skip`).
@@ -1780,1387 +1596,6 @@ host.
1780
1596
  prompt-cache stats as `Local p-cache` — provider telemetry is reported `unknown`, never
1781
1597
  zero.
1782
1598
 
1783
- ## 2.4.3 - 2026-09-18
1784
-
1785
- C19 liveness-hardening release (23 handoff tasks): a full sweep of the shipped hook and
1786
- runtime surface against the freeze/stall/orphan classes behind the recurring "session
1787
- stands still mid-turn" reports, plus the regression instruments that keep them closed.
1788
-
1789
- - **Bounded hook stdin staging (H01)**: `hook-input.sh`/`hook-input.mjs` runtime helpers
1790
- plus bounded-staging fallback blocks in all 16 hook wrapper templates — a producer that
1791
- never closes the pipe can no longer hold a hook open (SIGKILL at the staging bound).
1792
- - **Deadline-aware hot-hook filesystem work**: hook runtime modules self-arm on
1793
- `UKIT_HOOK_DEADLINE_MS` so a wedged read or lock wait exits inside the hook budget
1794
- instead of orphaning a node child.
1795
- - **Process-tree + lock containment**: bounded process-tree kill when a descendant escapes
1796
- its group, atomic quarantine of validated stale lock generations, owner-stamp failure
1797
- no longer runs the callback under an ownerless lock, and deep-freeze + containment
1798
- fail-closed for discovery snapshot reuse.
1799
- - **Liveness suite + classifier**: `src/diagnostics/classifyHang.js`, `tests/liveness/`,
1800
- and the `test:liveness` script — evidence-only hang classification (an external signal
1801
- is not a TERM→KILL leak) with regression scenarios pinned in tests.
1802
- - **Execution-ledger hardening**: bounded route-scoped ledger journal, overflow guard on
1803
- drain commits, journal-local locking, and the Stop coordinator
1804
- (`stop-coordinator.mjs`) with its extracted watchdog path.
1805
- - **Runtime shipping fix**: the install pipeline ships every packaged
1806
- `.claude/ukit/runtime` module via the `ukit-runtime-scripts` directory item (TASK-035),
1807
- closing the class where a new runtime module shipped to npm but never installed.
1808
-
1809
- ## 2.4.2 - 2026-09-16
1810
-
1811
- Fix: the gateway resilience posture disabled the only recovery path a buffering gateway
1812
- leaves open — the direct client-side cause of the recurring "session stands still mid-turn
1813
- until the user interrupts and re-prompts" freeze. Live probes of the stall-class gateway on
1814
- 2026-09-16 proved the full chain: the gateway still buffers entire streams (a 16-token
1815
- probe returned 23 SSE events in ONE body read), so a long generation is silent until it
1816
- finishes; the non-streaming route is healthy (HTTP 200 + valid Anthropic Message); and the
1817
- managed env shipped since 2.3.16 kept the non-streaming fallback DISABLED with a 10-minute
1818
- stream-idle watchdog — meaning the client sat in dead air and, on abort, had no recovery
1819
- path at all. The managed posture now flips to fail-fast-and-recover.
1820
-
1821
- - **Posture flip** (`src/core/gatewayResilienceEnv.js`): `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK`
1822
- managed default `'1'` → `'0'` (fallback stays enabled — on a buffering gateway a
1823
- non-streaming POST is the one request shape without an idle watchdog), and
1824
- `CLAUDE_STREAM_IDLE_TIMEOUT_MS` `'600000'` → `'120000'` (a silent stream aborts after
1825
- 2 minutes and recovers via the healthy non-streaming route instead of hanging for 10).
1826
- Values equal to the previously shipped defaults are UKit's own earlier writes and are
1827
- migrated on the next `ukit install` (new `GATEWAY_RESILIENCE_ENV_LEGACY_DEFAULTS` map +
1828
- `migrated` report field, backup written as usual); genuinely user-tuned values are still
1829
- never touched.
1830
- - **Probe misdiagnosis fixed** (`src/core/gatewayProbe.js`): the probe 404'd healthy
1831
- alias-based gateways because it POSTed the built-in default `claude-sonnet-4-5`, which is
1832
- not provisioned there ("No active credentials for provider: claude", `model_not_found`,
1833
- reproduced live) while real sessions run on the `ANTHROPIC_DEFAULT_*_MODEL` lane aliases.
1834
- The probe now resolves `ANTHROPIC_MODEL` → `ANTHROPIC_DEFAULT_OPUS/SONNET/HAIKU_MODEL`
1835
- before the built-in default and reports the probed model. `anthropic-version` is now sent
1836
- for the Bearer scheme too (live-verified accepted), and the API key is resolved through
1837
- the same 3-tier order as the base URL (env → project settings → home settings) so plain
1838
- terminals no longer probe keyless (`resolveGatewayApiKey`).
1839
- - **request-id re-classified** (same file, `docs/GATEWAY.md` §3): a missing `request-id`
1840
- on an HTTP 200 + valid Anthropic Message is an advisory hint, not a FAIL — the real
1841
- gateway ships no request-id even on healthy responses and sessions complete fine. The
1842
- Message-shape hard gate still catches the 888-byte error-envelope class from 2.3.16.
1843
- - **Docs**: `docs/GATEWAY.md` intro/§1/§2/§3/§4/§5 updated for the fail-fast posture,
1844
- the 2026-09-16 buffering reconfirmation, the legacy-value migration, and the probe's
1845
- alias-model + key resolution.
1846
- - **Verification**: focused suites green (gatewayProbe 14, gatewayResilienceEnv 23,
1847
- packageVersion 3); full `yarn test` green; live re-probe after the fix reports the alias
1848
- model, a healthy non-streaming route, and the still-present buffering signature.
1849
- - **Orphan-leak class closed for the remaining hooks (2.4.1 follow-up)**: the 2.4.1 watchdog
1850
- shipped in exactly one hook (`skill-router.sh`); the other 18 node-spawning hooks could still
1851
- orphan a node grandchild to launchd when their work hung (wedged import, stalled mount — this
1852
- repo lives on an external volume). Every remaining hook now arms the same wall-clock
1853
- self-deadline: inline heredoc/`node -e` blocks carry
1854
- `setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref()` directly, wrapper hooks pass
1855
- `UKIT_HOOK_DEADLINE_MS` (default 3000 ms) and their runtime scripts (`execution-ledger`,
1856
- `output-compression`, `reinject-context`, `post-edit-verify`, `pre-edit-backup`,
1857
- `stale-spec-check`) self-exit only when that env var is present, so CLI usage is never
1858
- self-killed. Lock-mutation blocks with a 5000 ms bounded wait (auto-allow-bash,
1859
- auto-prune-bash, reset-compact-pressure) use an 8000 ms deadline so the watchdog can never
1860
- fire while the mutation is legally waiting for the lock.
1861
- `tests/consistency/hookWatchdogCoverage.test.js` enforces the coverage for every future hook.
1862
- - **Bounded stdin transport for the hook chain (C19 wave 1, H01)**: hook payloads no longer
1863
- materialize unbounded in a shell variable or the exec environment — the exec-env path that
1864
- made large PreToolUse payloads fail `exec` outright (E2BIG) on macOS. New
1865
- `templates/.claude/ukit/runtime/hook-input.sh` (`ukit_stage_hook_input` via `mktemp` +
1866
- byte-capped `head`, drained producer, overflow policies `truncate`/`temp-file`/`refuse`)
1867
- and `hook-input.mjs` (streaming reader + CLI) stage every payload to a bounded temp file;
1868
- all 16 node-spawning wrapper hooks now pass `INPUT_FILE`, never the payload, with a
1869
- bounded inline fallback when the helper is absent. Sensitive-data-guard overflow is
1870
- fail-closed (`refuse`, silent exit 2); 32 MiB receipts verified < 10 s.
1871
-
1872
- - Machine-envelope lane in the sensitive-data gate: harness-injected notifications (task-notification / system-reminder / cross-session-message tags) now deliver with a redacted labels/counts advisory instead of being blocked when they quote secret-shaped test fixtures — ends the silent "Waiting for N background agents" stall. User-typed prompts, file/grep/bash channels, allowlist and overflow-refuse posture unchanged (fail-closed, default-ON, never echoes values).
1873
-
1874
- ## 2.4.1 - 2026-09-14
1875
-
1876
- Fix: the skill-router hook could hang the session and leak an orphaned process. `skill-router.sh`
1877
- runs on the `UserPromptSubmit`/`PreToolUse` hot path. Unlike its sibling hooks
1878
- (`task-watchdog.sh`, `handoff-resume.sh`), its node heredoc had no self-deadline watchdog: when
1879
- indexed-context resolution hung (a wedged import, a stalled mount), the host killed only the bash
1880
- wrapper with the node grandchild reparented to launchd and spinning forever — one orphan per run,
1881
- hundreds accumulated over days, adding sustained RSS pressure that presented as UKit freezing with
1882
- no message. The hook now arms the same wall-clock watchdog its siblings carry
1883
- (`setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref()`, default 3000 ms, overridable via
1884
- `UKIT_HOOK_DEADLINE_MS`), so a hang can never outlive the hook. Early exit only drops the routing
1885
- hint — the same posture as a cache miss, and advisory-only as the hook already is. Applied
1886
- byte-identically to the live and shipped (template) copies.
1887
-
1888
- ## 2.4.0 - 2026-09-14
1889
-
1890
- Solution-discipline wording + offline instruments. This release is **additive**: it changes
1891
- instruction text that is already loaded in daily sessions and adds offline test instruments
1892
- under `tests/`, which the published tarball does not ship. It changes no runtime, config,
1893
- route, hook, or gateway behaviour, and it removes no existing behaviour.
1894
-
1895
- - **Solution ladder + carve-outs in the delivery lane.** `templates/.claude/skills/delivery/SKILL.md`
1896
- (and its active mirror) now carry the canonical ladder: choose the smallest solution that fully
1897
- meets the stated requirements and project conventions; prefer reuse of an equivalent codebase
1898
- helper, then the standard library / native API / an already-installed dependency, and treat new
1899
- custom code or a new dependency as the last resort. The carve-out is explicit: never drop
1900
- validation, security, accessibility, error handling, compatibility, or required tests to reduce
1901
- code, and never ship a weaker version and ask. The delivery "Tier 2 — Structure Scan" step now
1902
- prefers the project index/resolver and falls back to raw Glob/Grep only when the index is stale,
1903
- missing, or returns no match — understanding source before editing is never skipped.
1904
- - **Feature-implementer ladder (Claude Code + omp).** `templates/.claude/agents/feature-implementer.md`,
1905
- its active byte-twin, and `templates/.omp/agents/feature-implementer.md` gain the same ladder plus
1906
- a guard reminder that fewer lines are not a reason to drop a guard. The daily-mode test rule is
1907
- left verbatim: the ladder must not become an excuse to cut tests.
1908
- - **Reviewer rubric (Claude Code + omp).** The `code-reviewer` copies gain 5 evidence-first
1909
- solution-fit questions (duplicate semantics / standard library suffices / guard-dropping
1910
- simplification / shared root cause / speculative abstraction) and a rule that says
1911
- **never grade brevity or line count as a quality win**. The sidecar diff lane stays
1912
- non-blocking with no auto-delete; verdict and model-isolation contracts are unchanged.
1913
- - **Offline instruments (not shipped).** A pure metric protocol
1914
- (`tests/benchmarks/solution-discipline/protocol.mjs`), four acceptance fixtures under
1915
- `tests/fixtures/solution-discipline/` (F01 reuse-helper, F06 trust-boundary, F09 keep-failure-path,
1916
- F11 required-interface) with good/bad reference solutions, and a host driver core exercised through
1917
- fake hosts (nonzero exit, timeout, malformed events, duplicate usage, missing terminal event).
1918
- These live under `tests/`, which `package.json.files` does not publish, so they stay out of the
1919
- tarball by construction; the release check confirms the packed file list contains no `tests/` path.
1920
- - **Deferred, with reasons.** The paid pilot (roadmap PT-06) and confirmatory benchmark (PT-09) are
1921
- deferred: no spending cap is approved and no billable model call was made this cycle. The runtime
1922
- lifecycle work (PT-07/PT-08 — shared renderer plus route/lifecycle/omp integration) is deferred
1923
- because the evidence for instruction-only wording is sufficient to start and no runtime drift has
1924
- been observed yet. The remaining fixtures and live-host probing are queued in
1925
- `docs/AI_HANDOFF/PROPOSAL-C18-benchmark-fixtures.md` for the funded pilot cycle.
1926
- - **Evidence record.** The preflight inventory this release builds on is pinned in
1927
- `docs/plans/ponytail-evidence.md` (revision pin, existing/proposed inventory, command map, blockers).
1928
- - **Truthfulness.** Savings are unverified until a paid benchmark pilot runs; no token/LOC reduction
1929
- is claimed for this release.
1930
-
1931
- ## 2.3.24 - 2026-09-13
1932
-
1933
- Post-2.3.23 routing and self-install audit. Two real defects fixed, plus the repo-local
1934
- Release Policy mirror restored and guarded.
1935
-
1936
- - **`isInformationalPrompt` ported into the src canonical copy.** `src/index/taskRouting.js`
1937
- was missing the informational-prompt guard that the shipped copies in
1938
- `templates/.claude/ukit/index/route-task.mjs` and `templates/.claude/hooks/skill-router.sh`
1939
- received in 2.2.14. The 2.3.22 `consultationOnlySignal` only catches question-shaped
1940
- prompts (trailing `?`, a leading interrogative, or Vietnamese `…là gì / được không`), so a
1941
- prompt with an **embedded** interrogative and no leading marker — `"please tell me what the
1942
- auth module does"`, `"explain what files the installer writes"` — routed to `shared-edit`
1943
- with a write+verification contract in src while the shipped templates routed it
1944
- `informational`. That is exactly the fabricated-mutation-debt class 2.3.22 set out to fix,
1945
- still live in the copy that drives `ukit index route`. The helper is now byte-equivalent
1946
- across all three copies; implement/debug-worded questions still keep their lanes. Locked by
1947
- a new `tests/index/taskRouting.test.js` regression (verified RED without the call site).
1948
- - **Self-install detection no longer misfires on a local install.** The 2.3.23 guard treated
1949
- any `templates/` directory inside the install root as a self-install. A downstream project
1950
- that installs UKit locally (`node_modules/@ngockhoale/ukit/templates`) therefore matched,
1951
- and every `docs/` entry was downgraded to `skip` — so `ukit update` silently stopped
1952
- refreshing that project's docs. `isSelfInstall` now requires the package root itself to be
1953
- the project root (`<projectRoot>/templates` exactly) or the target `package.json` to name
1954
- `@ngockhoale/ukit`. Locked by a new `buildPlan` regression for the `node_modules` shape
1955
- (verified RED under the old containment test).
1956
- - **Release Policy mirror restored.** A `ukit install` run inside this repo (self-install)
1957
- had overwritten root `CLAUDE.md`/`AGENTS.md` from `templates/`, wiping the repo-local
1958
- Release Policy section that `docs/PROJECT.md` mandates at the top of both files. Restored
1959
- from the byte-identical pre-wipe copy; a new `tests/consistency/configDocsSync.test.js`
1960
- guard fails loudly if a future self-install wipes either copy again.
1961
- - **Verification.** `yarn test` 87 files / 1,553 tests green (also under `--sequence.shuffle`);
1962
- `yarn release:verify` exit 0; artifact unpacked ceiling raised once to 5,960,000 with
1963
- rationale in `tests/integration/packageArtifact.test.js`.
1964
-
1965
- ## 2.3.23 - 2026-09-13
1966
-
1967
- Self-install no longer clobbers UKit's own canonical docs. Running `ukit install` inside the UKit
1968
- source repository (e.g. the global CLI invoked from the repo) overwrote `docs/PROMPT_CACHING.md` —
1969
- the canonical 368-line ruleset — with the distilled 127-line copy shipped under `templates/docs/`,
1970
- because the manifest item is `overwrite_with_backup` and self-install went undetected.
1971
-
1972
- - **Self-install detection.** `buildInstallPlan` now recognizes an install targeting the UKit repo
1973
- by two independent signals: the templates resolving inside the install target (the repo has a
1974
- `templates/` directory, the global CLI does not), or the target `package.json` naming
1975
- `@ngockhoale/ukit`. This covers the common case where the global CLI runs inside the repo, which
1976
- the path-containment check alone misses.
1977
- - **Docs downgraded to seed-only.** On a detected self-install, every `overwrite_with_backup`
1978
- entry whose target lives under `docs/` is downgraded to `skip`: a missing doc is seeded, but an
1979
- existing canonical doc is never overwritten. Downstream projects are unaffected — their docs
1980
- refresh on `ukit update` as before.
1981
- - **Verification.** New `buildInstallPlan` regressions cover the containment signal, the
1982
- package-name signal, and the unchanged downstream path; the full suite stays green.
1983
-
1984
- ## 2.3.22 - 2026-09-13
1985
-
1986
- Consultation-question routing fix — pure questions no longer fabricate mutation debt that the
1987
- completion gate then enforces against an answer turn. Observed live the same day: two Vietnamese
1988
- consultation questions (no English signal word, no target file) scored every candidate mode ≤ 0,
1989
- the mode ladder's upward bias resolved the find-cause/shared-edit tie to `shared-edit`, and the
1990
- gate blocked the answer turn six times ("missing write-evidence / verification-evidence") until
1991
- the continuation cap released it.
1992
-
1993
- - **Consultation questions carry no completion contract.** A question-shaped prompt (trailing `?`,
1994
- a leading English or ASCII-folded Vietnamese interrogative, or a `là gì / được không` tail) with
1995
- no implement/review/debug/failure/impact signal and no target file routes `informational` — the
1996
- same no-mutation-debt lane delivery-only requests already use. Applied to
1997
- `src/index/taskRouting.js`, the standalone router `route-task.mjs`, and the hook-embedded
1998
- routing copy in `skill-router.sh` (live twins byte-identical).
1999
- - **Leading interrogatives override action words.** The router's signal regexes are English-only,
2000
- so Vietnamese how-questions mentioning an action ("Làm sao mà đo được khi tôi cài hệ thống
2001
- này…?") kept a mutation contract. A leading interrogative (làm sao / thế nào / tại sao / phải
2002
- làm gì / …) now marks the prompt consultative even when it contains implement verbs
2003
- (sửa / thêm / cài / cài đặt / …) — asking HOW something is done is not ordering the action
2004
- performed. Question-phrased edit orders ("bạn sửa giúp tôi… không?") keep their write contract.
2005
- - **Verification.** New routing regressions lock the two incident prompts to `informational` with
2006
- empty contract evidence, and lock both guard directions (English signal-word questions and
2007
- question-phrased Vietnamese edit orders stay in their lanes); full suite green.
2008
-
2009
- ## 2.3.21 - 2026-09-13
2010
-
2011
- C16 release — the prompt-caching ruleset turns from research into shipped guidance, and the
2012
- prompt-assembly surfaces that inject into model context are made deterministic. No new commands
2013
- and no default runtime behavior changes: the tool-call policy ships as guidance only, pending the
2014
- A/B required before any behavior change.
2015
-
2016
- - **Canonical prompt-caching ruleset (`docs/PROMPT_CACHING.md`, repo-local).** Distills the UNIC
2017
- caching roadmap into CTX-01..10 (MUST), the SHOULD set, and the never-do list, with
2018
- evidence-labeled vendor sections (Anthropic, OpenAI, DeepSeek, GLM, MiniMax) and an
2019
- adopt/adapt/reject matrix. Upstream vendor docs are reference only — never UNIC guarantees
2020
- (UNIC behavior is labeled `unknown`/`inferred`). Repo-local by design; not shipped.
2021
- - **Shipped caching guidance (`templates/docs/PROMPT_CACHING.md`).** The distilled CTX rules,
2022
- never-do list, and short tool-call policy now ship with UKit installs through a new manifest
2023
- item `docs-prompt-caching` (`mergeStrategy: overwrite_with_backup`, so `ukit update` refreshes
2024
- it). `templates/CLAUDE.md` and `templates/AGENTS.md` gain a matching `## Prompt Caching`
2025
- pointer section, and the repo-local `CLAUDE.md`/`AGENTS.md` carry a minimal pointer too.
2026
- - **Deterministic prompt assembly.** `templates/.claude/hooks/skill-router.sh` ordered
2027
- model-visible memory-recall output by volatile `updatedAt` timestamps, so the same state could
2028
- assemble different prompt bytes across runs and defeat prompt caching (CTX-01/CTX-04). Ordering
2029
- is now a stable sort with a deterministic tiebreak and no volatile timestamps in model-visible
2030
- output; the live `.claude/hooks/` twin is byte-identical. Locked by the new
2031
- `tests/hooks/promptAssemblyDeterminism.test.js` plus an ordering regression in
2032
- `tests/hooks/skillRouterHook.test.js`.
2033
-
2034
- ## 2.3.20 - 2026-09-13
2035
-
2036
- C15 bug-fix release record — this release completes the silent-stop class on top of the
2037
- already-published 2.3.19 (published to npm 2026-09-13, registry verified, carrying the C14
2038
- valve removal); it adds no new features. npm is the distribution channel and `ukit update`
2039
- pulls from npm, so an install on 2.3.19 (or older) needs an update to receive these fixes.
2040
-
2041
- - **`--evaluate-stop` never releases a routed stop silently.**
2042
- `templates/.claude/ukit/runtime/execution-ledger.mjs` had a final dispatch with no `else`, so any
2043
- evaluation result of `{continue:false, notify:false}` that was not `capped` wrote nothing at all
2044
- — the Stop was allowed and the session idled with no visible reason. That default path is now a
2045
- loud release: an invisible blocker and a route with empty/short completion evidence both emit a
2046
- `systemMessage` naming the cause and how to resume, instead of silence. Malformed stdin no longer
2047
- crashes the hook into a silent stderr exit — it blocks with the crash detail, bounded by a crash
2048
- counter that loudly releases after the threshold and resets on a clean evaluate.
2049
- - **Fail-loud completion-gate wrappers.**
2050
- `templates/.claude/hooks/completion-gate.sh` and `templates/.claude/hooks/record-execution.sh`
2051
- exited 0 silently when the runtime script was missing or failed; both now emit a
2052
- `systemMessage` naming the missing/failing runtime and the `ukit install` remedy.
2053
- - **omp reentrant stop gets the same never-silent contract as the CLI.**
2054
- `templates/.omp/hooks/pre/ukit-bridge.js` released a reentrant stop with a non-blocking notice
2055
- and no continuation; it now blocks with the actionable reason like any other stop, stays bounded
2056
- by the ledger's continuation cap, and releases loudly at the cap.
2057
-
2058
- ## 2.3.19 - 2026-09-12
2059
-
2060
- C14 bug-fix release record — one correctness fix is shipped; this release adds no new features.
2061
-
2062
- - **Completion gate no longer silently releases a reentrant stop.** `templates/.claude/ukit/runtime/execution-ledger.mjs` (`--evaluate-stop`) had a `stop_hook_active` valve:
2063
-
2064
- ## 2.3.18 - 2026-09-12
2065
-
2066
- C13 bug-sweep release record — two wave-1 correctness fixes are shipped; this release adds no new features.
2067
-
2068
- - **Task-budget validator heading and target-count fix.** `src/core/taskBudgetValidator.js` and the shipped twin `templates/.claude/ukit/index/task-budget-validator.mjs` now accept the template's `## Test Cases (REQUIRED — TDD)` heading without a false `missing-field` verdict and count only top-level `## Target Files` bullets, avoiding indented sub-bullet miscounts.
2069
- - **Task-progress guard multi-section fix.** `src/core/taskProgressGuard.js` now evaluates milestone entries across every `## Progress` section, so a fresh appended entry is not masked by an older first-section entry while malformed and drift checks remain active.
2070
-
2071
- Verification: version pin and targeted regression suites pass; `yarn release:verify` is the closing release gate.
2072
-
2073
- ## 2.3.17 - 2026-09-12
2074
-
2075
- Long-task resilience — a handoff run is now measured before planning, checkpointed during
2076
- execution, and auto-split on wall-clock overrun instead of silently wedging. Cycle C12 turns
2077
- three questions into enforced machinery: "is this task too big to hand to an executor?"
2078
- (answered with data before a task is ever marked `ready`), "did the executor actually record
2079
- where it last stood green?" (answered by a machine-checkable milestone protocol), and "what
2080
- happens when a task blows its time budget?" (answered by a watchdog that cuts the task in
2081
- half and keeps the pipeline moving). Also fixes a repo-level gitignore trap that could
2082
- silently swallow new template files.
2083
-
2084
- - **Task-budget validator — `needs_breakdown` as data, not prose.** New
2085
- `src/core/taskBudgetValidator.js` plus a behavior-identical shipped CLI twin at
2086
- `templates/.claude/ukit/index/task-budget-validator.mjs` (self-contained, no `src/`
2087
- dependency, so user installs get the same gate). Thresholds: `maxTargetFiles: 3`,
2088
- `maxTestCases: 8`, `maxVerificationMinutes: 10`, with a table-driven verification-minutes
2089
- estimator (`yarn test:release-core` = 3 min, `node scripts/release/verify-release.mjs` =
2090
- 2 min, `yarn vitest run` = 0.5 min per file argument, unknown commands flat 1 min) and an
2091
- `investigate`+`first` prose rule for spike-vs-build splits. The `handoff-planner` agents
2092
- (Claude Code + omp) run the twin on every candidate task and must mark over-budget
2093
- `needs_breakdown` instead of shipping it as `ready`. Missing required sections emit
2094
- `missing-field` reasons; the validator never throws and the CLI always exits 0 (advisory
2095
- gate). TDD: 14/14 vitest cases + 4/4 ship-contract checks.
2096
- - **Executor milestone protocol.** Task executors now append `## Progress` entries in a
2097
- fixed, parseable shape — `- <ISO-8601> · milestone: <name> · last-green: <what passed> ·
2098
- files: <paths> · drift: none|<why>` — and both task templates gain a `- Size: S|M|L`
2099
- line. New `src/core/taskProgressGuard.js` makes the entries machine-checkable, with the
2100
- staleness boundary at exactly 2 × `milestoneIntervalMin` (inclusive = ok, beyond = stale).
2101
- The feature-implementer agents (Claude Code + omp) and the `handoff-fullstack` command
2102
- carry matching protocol text as byte-identical pairs. TDD: 6/6 unit cases + 4/4 protocol
2103
- contract checks.
2104
- - **Wall-clock watchdog hook, `hardPolicy: "split"`.** New
2105
- `templates/.claude/hooks/task-watchdog.sh` + `templates/.claude/ukit/runtime/
2106
- task-watchdog.mjs`, wired through `.claude/settings.json` (Stop + PostToolUse Edit/Write,
2107
- timeout 4) and `manifests/platform.full.yaml` (`hook-task-watchdog`). Budgets come from
2108
- `handoff.taskBudgets`: S 8/15, M 15/30, L 25/45 soft/hard minutes, `milestoneIntervalMin:
2109
- 5` default, `hardPolicy` `"split"` (default) or `"pause"`. Soft overrun emits a visible
2110
- "checkpoint a milestone now" advisory; hard overrun under split policy emits a Stop
2111
- `decision=block` naming the follow-up `TASK-<id>-b` — blocking the stop IS the
2112
- auto-split-and-continue mechanism — capped at 2 blocks per task before degrading to an
2113
- advisory that hands back to the user. The hook can never hang a session: 3 s self-kill
2114
- (`HOOK_DEADLINE_MS`), all-async I/O, 64 KB stdin cap, fail-open `exit 0` on every path;
2115
- PostToolUse is advisory-only and never emits a decision. State lives at
2116
- `.ukit/storage/cache/task-watchdog/state.json`; config load is fail-open to
2117
- `DEFAULT_CONFIG`. TDD: 16 sandbox checks (hard-trip block, pause, cap, fail-open,
2118
- wiring, no-undefined advisories) + config-docs sync coverage.
2119
- - **Gitignore trap fixed at both layers.** An unanchored `.claude/` pattern treats every
2120
- directory named `.claude` at any depth as ignored, and `templates/.gitignore` is a
2121
- per-directory ignore for the `templates/` subtree — so it silently hid NEW files under
2122
- `templates/.claude/**` from `git status`/`diff`/`add` (already-tracked files were
2123
- unaffected, which is why the trap stayed invisible). It ate the TASK-014 CLI twin, which
2124
- a `git worktree remove --force` then destroyed. Root `.gitignore` runtime dirs are now
2125
- anchored (`/.claude/`, `/.codex/`, `/.omp/`, `/.ukit/`, `/.worktrees/`) and the
2126
- `templates/.gitignore` runtime-dir lines are removed with an explanatory NOTE; new
2127
- template files no longer need `git add -f`.
2128
-
2129
- ## 2.3.16 - 2026-09-11
2130
-
2131
- Gateway-stall root cause, part 5 — the operator's gateway stayed invisible in the repo. Wave 1
2132
- (TASK-011 + TASK-012) shipped the two client-side fixes that defend Claude Code against the
2133
- stall and the malformed-body incident; this release closes the loop with a written contract
2134
- the operator (UNIC or any other proxy in front of `ANTHROPIC_BASE_URL`) can be handed. The
2135
- two client-side fixes are also safe no-ops on the official Anthropic endpoint — they only
2136
- fire when a gateway is in the path, so uninstall does not need to clean them up.
2137
-
2138
- - **Managed gateway resilience env defaults.** When `ANTHROPIC_BASE_URL` is non-empty (env,
2139
- project `.claude/settings.json`, or home `~/.claude/settings.json`), `ukit install` now
2140
- writes `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK='1'` and
2141
- `CLAUDE_STREAM_IDLE_TIMEOUT_MS='600000'` into the project `.claude/settings.json` `env`
2142
- block via a new `merge_env_overwrite_with_backup` strategy. Never clobbers a user-set
2143
- value (a non-default value moves into the report's `skipped` list); re-running `ukit
2144
- install` is a no-op (`unchanged`); corrupt settings JSON fails safe without overwriting
2145
- the file. New module `src/core/gatewayResilienceEnv.js` + wiring in
2146
- `src/core/runInstallPipeline.js` and `src/cli/commands/install.js`. TDD: 12/12 unit
2147
- cases + 5/5 installCommand wiring cases green.
2148
- - **`ukit doctor --gateway` live probe.** New opt-in flag on `ukit doctor` posts one tiny
2149
- streaming and one tiny non-streaming probe to `/v1/messages` and prints a `✓`/`✗` per
2150
- requirement. Streaming is flagged as `buffered` when the first body read alone already
2151
- carries ≥2 SSE events (the exact stall signature). Non-streaming fails when the body is
2152
- HTTP 200 but not an Anthropic Message **or** the `request-id` header is missing — the
2153
- exact check whose absence let the 888-byte gateway error envelope slip through and kill
2154
- the user's turn. New module `src/core/gatewayProbe.js` (`fetchImpl` injectable, fully
2155
- hermetic test surface); wiring in `src/cli/commands/doctor.js` (`--gateway` added to
2156
- `KNOWN_FLAGS` + help; verdict is advisory and MUST NOT set `process.exitCode` so
2157
- scripted `ukit doctor` runs stay hermetic). TDD: 6/6 unit cases + 8/8 doctorCommand
2158
- wiring cases green.
2159
- - **Gateway operator requirements doc.** New `docs/GATEWAY.md` states the three
2160
- requirements the operator must satisfy — (1) SSE/bytes relayed incrementally (no
2161
- full-response buffering), (2) idle streams kept alive ≥600 s under the watchdog, (3)
2162
- non-streaming route returns a real Anthropic Message with a `request-id` header — plus a
2163
- client-side knob table (`CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK`,
2164
- `CLAUDE_STREAM_IDLE_TIMEOUT_MS`, `ukit doctor --gateway`) and the explicit safe-no-op
2165
- guarantee on the official Anthropic endpoint. Probe hint lines from TASK-012's
2166
- `gatewayProbe.js` point at this doc.
2167
-
2168
- Residual unknown: `gatewayProbe.js` is exercised end-to-end against the real gateway only
2169
- through a hermetic `fetchImpl` (every test path uses an injected `ReadableStream`). A live
2170
- `ukit doctor --gateway` round-trip against the real gateway was NOT run in CI; it is a
2171
- manual post-release step on a gateway-connected machine. Recorded in `docs/STATUS.md`.
2172
-
2173
- ## 2.3.15 - 2026-09-11
2174
-
2175
- Vision-lane root cause, part 4 — the analyst never looked at the image. Found by mining the
2176
- user's own failing sessions across four real projects (UnicDB, VSDB, BAGuide, AI-Gateway). The
2177
- decisive record: a failed analyst subagent transcript is THREE lines with ZERO Read calls — the
2178
- analyst refused by name ("I am running on unic-lite, which is not a vision-capable model … I
2179
- must refuse to open, describe, or guess") without ever probing. The user confirmed the gateway's
2180
- vision routing is stable by design: unic-vision (backed by minimax/glm/chatgpt in their setup)
2181
- always reads images; nothing falls back to a non-visual lane. The failure was entirely
2182
- UKit-side, two stacked defects:
2183
-
2184
- - **Refusal by name instead of by probe.** The omp analyst template mandated refusing *before
2185
- touching any image* when the runtime model could not be confirmed vision-capable — and any
2186
- backend self-identification (`glm-5-turbo`, `MiniMax-M3`) or lite-lane label counted as "not
2187
- confirmed". Both agent templates now decide ONLY by the first image Read (the probe): if the
2188
- probe shows the image the lane reads it and reports the mapping it actually ran on in
2189
- `MODEL:`; a probe that fails to deliver the image is still `STATUS: WRONG_MODEL`.
2190
- - **No fallback after a refusal.** The honored-lane hint ordered the parent to dispatch the
2191
- specialist and simply continue, so a name-refusal left the image unread even though the parent
2192
- could read it natively (`STATUS: OK` ×14 from main Claude lanes in one VSDB transcript). The
2193
- hint now verifies the parent's own vision FIRST (step 2: Read the materialized files yourself,
2194
- write the receipts, do NOT dispatch), dispatches the specialist only when the parent's own
2195
- Read yields no image (step 3), and defines the fallback: on `WRONG_MODEL`/`NO_IMAGE` re-read
2196
- natively, analyse from your own view for pasted images, and never fabricate when no reader can
2197
- see it (step 4).
2198
-
2199
- Unchanged doctrine: never guess at image contents — the fix removes the two paths that turned
2200
- "don't guess" into "don't read". omp mirrors synced. TDD: `vision-router-hint` tests 13-14 and
2201
- `vision-agent` test 13 written RED first, then GREEN; all vision suites pass.
2202
-
2203
- ## 2.3.14 - 2026-09-11
2204
-
2205
- Vision-lane root cause, part 3 — the decisive one: the extractor could not see images in REAL
2206
- Claude Code transcripts at all. Found by reproducing the failure against the user's own real
2207
- session transcripts after they insisted the bug lived "right at the image" — grep proved the
2208
- transcripts contained `"type":"image"` while every extraction returned `imageCount: 0`. The
2209
- 2.3.12/2.3.13 suites were green because the fixtures modeled an invented transcript shape.
2210
-
2211
- **P1 — real transcript image envelopes were invisible to the extractor.** Verified against
2212
- real transcripts from four projects, Claude Code stores images in THREE shapes:
2213
-
2214
- - flat: `message.content[i] = { type: 'image', source: { type: 'base64', … } }` — the only
2215
- shape the pre-fix parser handled;
2216
- - pasted: a top-level `attachment` envelope (`type: 'attachment'`,
2217
- `attachment.prompt[]` = content blocks) — every real pasted image lives here, NOT in
2218
- `message.content`; the pre-fix parser extracted nothing from any pasted image;
2219
- - tool-returned: `message.content[i] = { type: 'tool_result', content: [ { type: 'image',
2220
- … } ] }` — screenshots coming back from tools nest one level down; also invisible.
2221
-
2222
- Fix: `extractImageBlocks()` now walks a bounded collector (depth ≤ 3) across
2223
- `message.content[]`, nested `content[]` arrays inside blocks, and the top-level
2224
- `attachment.prompt[]` / `attachment.content` envelopes. Same-base64 payloads across
2225
- envelopes dedupe by sha as before. Real-data validation after the fix: the same four
2226
- transcripts now extract valid images (PNG 2278×2154 from the paste envelope, JPEG 1400×884
2227
- from a tool_result, PNG/JPEG from the flat shape), and a live analyst dispatch read the
2228
- real pasted screenshot.
2229
-
2230
- Tests: `tests/handoff/cycle10/extract-image-contract.test.mjs` gains three cases whose
2231
- fixtures copy the real envelope structures verbatim (RED pre-fix: `imageCount 0`), plus a
2232
- cross-envelope dedupe pin. All cycle10 + cycle4 vision suites green.
2233
-
2234
- ## 2.3.13 - 2026-09-11
2235
-
2236
- Vision-lane root cause, part 2: the Codex model catalog could still deny the vision lane on
2237
- every gateway machine, even after the 2.3.12 plumbing sweep. Found by a fresh end-to-end
2238
- repro (install into a clean project → fire the hook → live dispatch) plus a live gateway
2239
- probe on 2026-09-11 that returned `STATUS: OK / MODEL: unic-vision` on a machine whose
2240
- `~/.codex/model-catalog.json` omits the alias.
2241
-
2242
- **P1 — the Codex model catalog could deny the Claude Code vision lane from another tool's
2243
- config.** `unic-gateway.mjs` derived `aliasAvailable` solely from
2244
- `~/.codex/model-catalog.json`: a catalog that omitted `unic-vision` — or was missing
2245
- entirely, the default on any machine that never used Codex CLI — produced
2246
- `aliasAvailable: false`, and both consumers (the vision router hint and route-task's
2247
- `resolveVisionModel`) then force-downgraded the lane to "read natively / do NOT dispatch"
2248
- or a config fallback. The catalog is a different tool's config and says nothing about what
2249
- the gateway resolves server-side for this session — the same principle TASK-007 already
2250
- established for endpoints. Fix: the catalog may now only CONFIRM the alias (new
2251
- `catalogListed` field); silence (absent, malformed, or alias-omitting catalog) leaves the
2252
- lane honored, with an informational advisory instead of a denial. The analyst agent's own
2253
- `WRONG_MODEL` self-check remains the in-band safety net: a genuinely dead alias fails
2254
- loudly and never guesses. `aliasAvailable: false` is reserved for a future source of
2255
- positive unavailability evidence, so the dormant fallback branches in both consumers are
2256
- unchanged and still covered by tests.
2257
-
2258
- Tests: `tests/handoff/cycle4/unic-gateway.test.mjs` and
2259
- `tests/handoff/cycle10/vision-lane-fallback.test.mjs` rewritten for the flip (catalog
2260
- silent → lane honored; catalog missing → lane honored; listing → positive confirmation),
2261
- with the strict `=== false` fallback contract kept as a source-level case.
2262
-
2263
- ## 2.3.12 - 2026-09-11
2264
-
2265
- Vision-lane freeze-sweep (post-2.3.11): the four defects that stranded the vision image lane on
2266
- nearly every image are fixed, the second consumer of the same advisory now honors the fallback,
2267
- and the installed vision-agent file mode is corrected. The cycle10 + cycle4 scripts prove the
2268
- plumbing; a real UNIC round-trip dispatch is not covered by the suite (see `docs/STATUS.md`).
2269
-
2270
- **P1 — `--detect` could not resolve absolute image paths outside the project, or paths wrapped
2271
- in quotes or trailing punctuation.** `extract-image.mjs`'s `--detect` arm accepted relative
2272
- paths and in-project absolutes, but the path-capture regex in `vision-router.sh` then refused an
2273
- out-of-project image ("did not resolve from the project root … Nothing was armed"), and
2274
- trailing punctuation / wrapping quotes (`'<abs>/x.png'.`, `"<abs>/x.png"`) broke the existence
2275
- check. Fix: `stripPathNoise()` in the extractor tries raw / soft-trailing-stripped /
2276
- wrapping-pair-stripped / both shapes against `fs.existsSync`; the hook-side regex now uses the
2277
- same tolerance. The interior of the path is never touched, and relative handling is unchanged.
2278
-
2279
- **P1 — marker receipts were leaked into `images[]`, so the dispatch hint could carry a
2280
- `pending-*.json` path to the analyst.** `--mark-pending --json` returned each marker receipt
2281
- (`{ path: 'pending-<sha>.json', bytes: 0 }`) inside the same `images[]` array that was supposed
2282
- to carry materialized images; downstream code that filtered "bytes > 0" still sometimes passed
2283
- the marker through, and the dispatch hint could carry a `pending-*.json` path the analyst would
2284
- not have materialized. Fix: `images[]` is now the materialized-only invariant (empty in
2285
- `--detect` / `--mark-pending` mode; every entry has bytes > 0 and a non-`.json` extension
2286
- otherwise); receipts live in a new top-level `pendingMarkers[]` carrying
2287
- `{ path, sha, bytes: 0, … }` per detection. On-disk marker format (`pending-<sha>.json`,
2288
- `bytes: 0`) is untouched — only JSON presentation changed.
2289
-
2290
- **P1 — the hook never forwarded the parent transcript, and default session discovery could
2291
- pick a newer-but-empty subagent transcript over the parent's image-bearing one.** When a
2292
- subagent spawn raced the paste, the subagent's empty transcript was the newest file in the
2293
- sessions root, so `discoverSessionFile()` returned it and the analyst got `imageCount: 0`. The
2294
- dispatch hint also lacked any `--session` argument, so the analyst could not materialize from
2295
- the parent transcript even when one was named in the payload. Fix: `discoverSessionFile()`
2296
- honors `CLAUDE_CONFIG_DIR` when set, calls `fs.realpathSync` so the macOS `/var` ↔ `/private/var`
2297
- symlinks do not drift the slug, and runs a bounded newest-first scan (`DISCOVERY_SCAN_BOUND = 5`)
2298
- with a cheap 64 KiB `transcriptHasImageHead()` peek — never an unbounded walk or full-content
2299
- parse. When nothing image-bearing is found, the script emits an explicit `STATUS: NO_IMAGE
2300
- scanned=<names>` (and a JSON line first under `--json`) instead of a fake success. The hook
2301
- hint now always carries `--session <payload.transcript_path>` whenever the payload provides one;
2302
- explicit `--session` still bypasses discovery and the NO_IMAGE branch entirely.
2303
-
2304
- **P1 — when the vision lane was unavailable, both consumers forced a failing dispatch instead
2305
- of degrading to native read.** `unic-gateway.mjs`'s `aliasAvailable: false` advisory was
2306
- ignored by `resolveVisionModel` in `route-task.mjs` and by the hook's hint builder, so a
2307
- gateway without vision routed the analyst task with `[model: unic-vision]` and the agent model
2308
- itself had to read the image, only to fail mid-dispatch. Fix: both consumers now honor
2309
- `aliasAvailable === false` — `resolveVisionModel` returns a non-`unic-vision` (native/main-
2310
- model) lane and states the unavailability in the routed output; the hook hint omits
2311
- `[model: unic-vision]`, says `vision lane unavailable`, and instructs a native read instead of
2312
- dispatching the analyst. The missing-field case preserves today's default; the
2313
- `unicMode === false` short-circuit is unchanged. Also: installed
2314
- `.claude/agents/ukit-vision-analyst.md` is now mode 0644 (template stays `100644` in git) — a
2315
- stale 755 from a prior install that was never regenerated by `ukit install` because
2316
- `copyFileSafe` preserves template mode.
2317
-
2318
- ## 2.3.11 - 2026-09-11
2319
-
2320
- Freeze-sweep wave 11 (post-2.3.10): the two deferred liveness candidates fixed via TDD, plus
2321
- a self-refresh downgrade trap repaired during verification. All template/live mirrors are
2322
- byte-synced.
2323
-
2324
- **P1 — SessionStart hook could hang the session forever.** `handoff-resume.sh`'s "advisory,
2325
- always exit 0" rested on `|| true`, which never fires when the embedded node process wedges
2326
- (hung runtime import, unresolved lock wait, stalled file read) — session start stalls mid-run
2327
- with no visible reason. A 3s wall-clock watchdog (`UKIT_HOOK_DEADLINE_MS`, env-tunable) now
2328
- exits 0 unconditionally, and the RUN.md read is async so sync I/O cannot block the timer.
2329
-
2330
- **P1 — router state writes could tear; route-audit merge lost entries.** All five
2331
- `skill-router-state.json` / `route-audit.json` writes were direct `writeFileSync`: a torn or
2332
- empty state parses as `{}` downstream and completion-gate.sh then releases a premature Stop
2333
- with no message. Writes now go through tmp+rename (`writeJsonFileAtomic`), and the audit
2334
- append runs under the standard PID + owner-token lock (5s bounded, fail-open). 16 concurrent
2335
- router runs previously kept only 13/16 audit entries; now 16/16.
2336
-
2337
- **Incident — post-release self-refresh downgraded live hooks.** Running `ukit install` from a
2338
- global CLI older than the published release rewrote six live hook mirrors with pre-release
2339
- content, resurrecting just-fixed lock-theft bugs in the development workspace. Recovered by
2340
- upgrading the global CLI and re-installing; the deferred guard candidate is a stale-CLI
2341
- warning in `ukit install`.
2342
-
2343
- ## 2.3.10 - 2026-09-11
2344
-
2345
- Freeze-sweep waves 7-10 (post-2.3.9): twelve verified mid-run-freeze defects fixed, each locked
2346
- by a regression reproducing the failure first. All affected template/live mirrors are byte-synced.
2347
-
2348
- **P1 — continuation budget reset on every route re-key.** The router re-keys `requestKey` per
2349
- tool call (the target file is part of the key), but the Stop-gate continuation budget was keyed
2350
- on `requestKey` — the count reset to 0 on every re-key, the cap was unreachable, and omp looped
2351
- forever (no `stop_hook_active` valve). Budget identity is now the logical prompt hash
2352
- (`promptKey`) everywhere, and omp gained `stop_hook_active` parity via `noteStopProgress`.
2353
-
2354
- **P1 — parallel execution receipts crashed and raced.** Same-process concurrent receipt writers
2355
- shared one temp path and crashed with ENOENT mid-hook; unlocked read-modify-write also dropped
2356
- receipts, and a missing/foreign route state could rebuild a session ledger from blank, erasing
2357
- banked evidence. Temp paths are unique, the whole receipt write runs under `withFileLock`, and
2358
- a missing route no longer blanks the ledger.
2359
-
2360
- **P1 — ledger lock waits exceeded the hook child budget.** `withFileLock` waited up to 5s but
2361
- the hook chain kills children at 4s, so a contended lock got the recording hook killed and omp's
2362
- fail-closed Edit|Write chain then blocked the edit. Ledger lock waits now cap at 2.5s and fail
2363
- open — a lost receipt beats a killed hook.
2364
-
2365
- **P1 — vibecode had no exit when verification kept failing identically.** Two adjacent identical
2366
- failed verifications (no edit between) now mint a visible `verification-loop` blocker; vibecode
2367
- additionally escapes after the same command fails 4× across edits.
2368
-
2369
- **P1 — clean map-impact Stop loop.** A completed analysis-only `map-impact` route still demanded
2370
- write + verification evidence. A narrow visible release valve permits a completed impact read
2371
- with no mutation attempt and no failed verification; incomplete analysis and partial edits stay
2372
- gated.
2373
-
2374
- **P1 — omp hook child timeouts falsely blocked edits.** A 4s-killed `protect-files` gate was
2375
- treated as its fail-closed verdict, freezing all edits on a slow machine. Timeouts now fail open
2376
- as infrastructure failures with a visible warning; `block-dangerous.sh` stays fail-closed. An
2377
- unknown mutation-shaped omp tool now normalizes to `Edit` and runs the normal safety chain
2378
- instead of emitting an impossible "add host mapping" block.
2379
-
2380
- **P1 — hard-cap grace slots crossed session boundaries.** Global grace slots let one session
2381
- spend or reset another session's landing allowance, stranding it mid-edit. Slots and advisory
2382
- state are now session-keyed.
2383
-
2384
- **P2 — transcript fallback rescanned up to 4MB per mutation.** A persisted, session-bound
2385
- 2-second boundary-probe cache coalesces mutation bursts to one scan; `skill-router.sh` also
2386
- skips its redundant prompt-only Node spawn on tool payloads.
2387
-
2388
- **P1 — lock stale-reclaim could steal a live owner.** The shared runtime lock used mtime-only
2389
- reclaim: a slow-but-alive holder was deleted after 10s, then deleted its successor's lock in
2390
- `finally` — lost receipts re-triggered completion debt. All lock implementations (runtime
2391
- mirror, verification guard, auto-allow, auto-prune, compact-pressure reset) now stamp
2392
- PID + random owner tokens, reclaim only provably-dead owners, and release only their own token.
2393
-
2394
- **P3 — stale verification-guard enforcement env var froze runs.** An inherited
2395
- `UKIT_VERIFICATION_GUARD_ENFORCE=1` turned an advisory test-order recommendation into an
2396
- exit-2 block. The guard is now exclusively advisory; real safety gates keep enforcement.
2397
-
2398
- Also in wave 7: piped/redirected verification (`yarn test 2>&1 | tail -6`) counts as targeted,
2399
- and delivery-only requests ("push this to git") route `informational` with no fabricated
2400
- mutation debt in all three routing copies.
2401
-
2402
- Full suite: 81 files, 1,439 tests green (plus wave 9-10 focused regressions). No npm tag
2403
- policy change; artifact unpacked ceiling raised once to 5,785,000 with dated rationale.
2404
-
2405
- ## 2.3.9 - 2026-09-10
2406
-
2407
- Freeze-sweep wave 5: fixes for completion-gate loops, worker-agent dead ends, and malformed
2408
- context-cap configuration that could otherwise halt all mutation progress.
2409
-
2410
- **P1 — clean `find-cause` audits were forced into a Stop-hook loop.** A recommend-only
2411
- investigation that found no actionable bug still required write and verification evidence, so
2412
- the completion gate blocked the honest outcome and demanded a fabricated edit. The execution
2413
- ledger now permits that narrow clean-audit outcome while retaining normal recovery blocks after
2414
- a failed verification or incomplete mutation.
2415
-
2416
- **P1 — routed workers could wait for a user they cannot contact.** The Claude Code and omp
2417
- `bug-debugger` / `feature-implementer` agents instructed workers to “ask the user” on unclear
2418
- or non-reproducible work. They now perform one bounded next diagnostic step and return a
2419
- structured `STATUS: BLOCKED` report with the exact missing artifact or decision to the parent
2420
- agent, which owns user communication.
2421
-
2422
- **P1 — malformed context-cap configuration could brick mutations.** Invalid
2423
- `compact.hardCapTokens` could collapse the cap to one token, invalid
2424
- `hardCapGraceCalls` could eliminate the landing window, and wrong-shaped present
2425
- `hardCapBlock` values could unexpectedly leave the hard gate enabled. The shared source/runtime
2426
- threshold logic and Claude hook now accept only positive integer budgets, while malformed
2427
- non-boolean `hardCapBlock` values fail open; the documented absent-key default remains enabled.
2428
- The context-window advisory uses the same hard-cap validation. Regression coverage includes
2429
- negative/zero/fraction/string/boolean/null budgets and malformed toggle values.
2430
-
2431
- Full suite: 81 files, 1,396 tests green.
2432
-
2433
- ## 2.3.8 - 2026-09-10
2434
-
2435
- Freeze-sweep wave 4: every fix in this release targets the "agent silently stops working"
2436
- class — lost permission rules that turn into human-waiting prompts, a session start that
2437
- wipes a sibling session's near-cap warnings, torn state files, and lost concurrency
2438
- bookkeeping. All found by verified reproducers and fixed with regression coverage.
2439
-
2440
- **P1 — SessionStart wiped a sibling session's compact-pressure state.** The SessionStart
2441
- reset hook deleted the whole project-wide `compact-pressure.json`, so starting a second
2442
- session in the same project zeroed the first session's pressure history: its near-cap
2443
- warnings stopped firing, it ran into the real context cap, and it stalled. Pressure state
2444
- is now a session-keyed document (`{"v":2,"sessions":{<session_id>:{…}}}`) with the newest
2445
- record's flat fields still projected at the top level for raw readers. Every writer and
2446
- reader threads the hook payload's `session_id` (compact-threshold CLI, output-compression,
2447
- reinject-context PreCompact, context-hardcap-gate); a brand-new session id starts clean
2448
- and never inherits a sibling's totals; the reset hook removes only the calling session's
2449
- record; sessions are pruned to the 8 most recent; a legacy flat file upgrades in place.
2450
- Ships in both `src/core/compact/threshold.js` and the runtime mirror.
2451
-
2452
- **P1 — concurrent auto-allow invocations lost Bash permission rules.** The hook's
2453
- read-modify-write of `settings.local.json` and `permission-usage.json` was unlocked, and
2454
- 30 concurrent invocations kept only 26/30 rules and 23/30 usage records — a lost rule
2455
- means the next run of that command prompts for permission again, i.e. the agent sits
2456
- waiting for a human click. Both files are now written inside one mkdir lock on
2457
- `<permission-usage.json>.lock` (protocol-compatible with `withFileLock`, fail-open ≤5s,
2458
- parent directory created before locking) with atomic tmp+rename writes, so Claude Code
2459
- can never observe a torn settings file either — a torn parse would drop the entire allow
2460
- list and prompt on every command. `auto-prune-bash.sh` now shares the same lock and
2461
- atomic writes.
2462
-
2463
- **P2 — index cache writes lost entries under concurrency.** `cache-utils.mjs`
2464
- read-modify-write cycles were unlocked: 20 concurrent writers kept 2 entries. All cache
2465
- reads-modify-writes (write + touch paths) now run under `withFileLock` with atomic
2466
- compact writes (cache files stay single-line JSON by contract).
2467
-
2468
- **P2 — verification-progress and execution-ledger counters lost concurrent updates.**
2469
- `verification-guard.sh` now records attempts through a locked re-read + merge (sync
2470
- `Atomics.wait` backoff so the hook's `process.exit` flow is untouched) and writes
2471
- atomically; `execution-ledger.mjs`'s continuation/notified counters re-read inside
2472
- `withFileLock` so parallel subagent Stop hooks cannot reset each other's budgets.
2473
-
2474
- Full suite: 81 files, 1,373 tests green, including two shuffled runs.
2475
-
2476
- ## 2.3.7 - 2026-09-10
2477
-
2478
- Bug-sweep wave 3: a data-loss escape in uninstall, cross-process races on shared runtime
2479
- state, one flaky test, and one vulnerable runtime dependency — all found by verified
2480
- reproducers and fixed with regression coverage.
2481
-
2482
- **P0 — uninstall could delete files outside the project root.** Tracked-path ownership
2483
- checks were purely lexical: with `.claude` (or any parent directory) symlinked to an
2484
- external location, uninstall's recursive remove resolved through the symlink and deleted
2485
- whatever it pointed at — e.g. a shared dotfiles directory. Uninstall now inspects every
2486
- directory component between the project root and each tracked entry (the entry itself may
2487
- still be a tracked symlink, which is unlinked, never followed); entries with a symlinked
2488
- parent are refused, warned, and reported in a new `skippedSymlinkParents` field in both
2489
- dry-run and real results.
2490
-
2491
- **P1 — concurrent state mutations silently lost updates.** `appendOutputHistory` and the
2492
- compact-pressure writers (prompt, output, plan, and the plain state write) performed
2493
- unsynchronized read-modify-write cycles on files under `.ukit/storage/cache/`. With
2494
- parallel subagents firing hooks in separate processes, 30 concurrent updates left a single
2495
- surviving output-history entry (of a 25 cap) and 17 of 510 accumulated sessionTokens —
2496
- understating context pressure and delaying compaction. All mutations now run under
2497
- `withFileLock`, a directory-lock protocol beside each state file (atomic `mkdir`, stale
2498
- reclaim after 10s, fail-open after 5s so a stuck lock can never freeze a hook). The lock
2499
- ships in both `src/core/fileOps.js` and the runtime mirror `token-utils.mjs` using the
2500
- same `<file>.lock` path, so CLI processes and hook processes serialize against each
2501
- other; mirror state writes also became atomic (tmp + rename). An interop test runs both
2502
- implementations against one project root to keep the protocols locked together.
2503
-
2504
- **Flaky test** — the `--no-outline` index-tools test queued a `getFileOutline` once-mock
2505
- its own flag guaranteed would never be consumed; `vi.clearAllMocks()` drains no once-queues,
2506
- so test order leaked the stale value into the next test (18/30 shuffled solo runs failed).
2507
- The dead queue is gone; the full suite is now 3/3 green under `--sequence.shuffle`.
2508
-
2509
- **Dependency** — runtime dependency `yaml` 2.8.2 → 2.9.0 (GHSA-48c2-rrv3-qjmp, stack
2510
- overflow via deeply nested YAML — UKit parses project-supplied manifests). Production
2511
- dependency audit is now 0 findings.
2512
-
2513
- Full suite: 78 files, 1,359 tests green.
2514
-
2515
- ## 2.3.6 - 2026-09-10
2516
-
2517
- Anti-stall coverage parity release: the compact-recovery and stop-reason directives that
2518
- UKit hooks inject at runtime on Claude Code and omp now also reach harnesses that have no
2519
- hook system at all.
2520
-
2521
- A new `## Long-Run Continuity` section ships in both `templates/CLAUDE.md` and
2522
- `templates/AGENTS.md` (byte-identical, enforced by the per-section context-docs parity
2523
- test). Codex and OpenCode load no hooks, so root `AGENTS.md` is their only instruction
2524
- channel — before this release those sessions never saw the near-cap recovery order (LAND
2525
- one thing → DEFER the rest to `docs/STATUS.md` → DELEGATE broad work to subagents → only
2526
- then compact) or the post-compact discipline (no rereads of pre-compact context; if the
2527
- first turn after a compact still sits at ≥60% of the cap, recover by delegating or starting
2528
- fresh from disk state instead of burning the window again).
2529
-
2530
- The same session closed the long-running stall investigation with debug-log evidence: the
2531
- observed "runs a while, then goes silent" behaviour is UNIC-gateway/network streaming
2532
- latency (repeated 30s slow-first-byte, one 300s byte-idle abort), not UKit hooks —
2533
- hook-error cache empty, exec ledgers healthy. When a dead stream ends a turn early, the
2534
- existing ≥2.3.3 Stop-hook completion gate blocks the premature stop, so staying current
2535
- (`ukit update`) plus restarting stale sessions (hook config loads at session start) is the
2536
- full remediation available in-repo; gateway-side idle/failover fixes belong upstream.
2537
-
2538
- ## 2.3.5 - 2026-09-10
2539
-
2540
- Source-audit hardening release: the code index cannot corrupt itself, and a corrupt runtime
2541
- cache can no longer take down `ukit status` or `ukit memory`.
2542
-
2543
- Index artifacts (`files`, `symbols`, `imports`, `calls`, `tests-map`, `hotspots`,
2544
- `archetypes`, `relations`, `analogs`, `meta`) are now written through same-directory
2545
- `.tmp-<timestamp>-<random>` files followed by an atomic `rename`, in both the source builder
2546
- (`src/index/buildIndex.js`) and the shipped `templates/.claude/ukit/index/lib/index-core.mjs`
2547
- runtime mirror. A build that crashes mid-write — or two builds racing in one repo — can no
2548
- longer leave a half-written artifact that poisons every subsequent index read; failed writes
2549
- clean their temp file up before rethrowing.
2550
-
2551
- `ukit status` and `ukit memory` now read their cache/memory JSON through tolerant readers:
2552
- a corrupt `compact-history.json`, `compact-pressure.json`, `prompt-cache.json`,
2553
- `output-history.json`, or memory file prints a warning naming the exact file path and falls
2554
- back to defaults instead of crashing the whole command mid-report. `readJsonIfExists` itself
2555
- stays strict everywhere else, so genuinely bad callers still fail loudly.
2556
-
2557
- Nested test layouts (`packages/widget/tests/unit/...`) are now recognized as tests by the
2558
- source path classifier and both runtime-mirror predicates — those files previously slipped
2559
- past test detection, broke archetype classification, and never appeared in the test map.
2560
-
2561
- Each fix ships with regression coverage: a rename-spy test asserting all ten artifacts move
2562
- through temp files, corrupt-fixture tests asserting the warned paths and surviving output,
2563
- and a nested-`tests/` mapping/archetype test. Full suite: 77 files, 1,348 tests green.
2564
-
2565
- ## 2.3.4 - 2026-09-10
2566
-
2567
- Silent-stall audit and compact-recovery release. Two themes: every block reports a
2568
- user-visible reason, and compaction must actually buy back context.
2569
-
2570
- Security hooks can no longer be bypassed or silently disabled. `block-dangerous.sh` catches
2571
- split recursive/force flags (`rm -r -f`, `rm --force -r`) and evaluates every delete target
2572
- per shell segment, so one allowlisted word can no longer legitimise a sibling target
2573
- (`rm -rf dist /`); a bare `/` stays classified unsafe, wrapped forms keep the whole-command
2574
- fallback, and detections surface as structured `ask` decisions that never echo the raw
2575
- command. `block-dangerous.sh`, `protect-files.sh`, and `auto-allow-bash.sh` fall back to
2576
- Node when `jq` is absent (stock macOS), so a missing optional binary cannot disable a gate.
2577
- `protect-files.sh` matches exact sensitive basenames and directory components instead of
2578
- substrings — `.env.d.ts` and `app.envrc` are source files, not secrets — and emits a
2579
- structured human-decision response on real blocks. `sensitive-data-guard.sh` only treats
2580
- `-u/--user` as credentials on tools that authenticate with it, so `docker run --user
2581
- 1000:1000` no longer false-blocks while `curl -u user:pass` still does.
2582
-
2583
- Stops always carry a reason. `handoff-model-guard.sh` pairs its stderr refusal with a
2584
- structured `systemMessage`; the completion gate reports a lost route state after real
2585
- session activity instead of releasing silently; hard-cap grace and sensitive-data blocks
2586
- already speak `systemMessage` from 2.3.3. `Phase: done …` with trailing status text now
2587
- counts as finished (`^done\b`, not `^done$`) in `handoff-resume.sh`,
2588
- `context-hardcap-gate.sh`, and `context-window-guard.sh`, so annotated done-phases stop
2589
- being resumed forever. Multi-file resume intents survive compaction: identity is session +
2590
- prompt key, because the router re-keys `requestKey` on every tool call and that churn is
2591
- what made post-compact resume a silent no-op.
2592
-
2593
- The hard-cap grace budget is race-proof. Parallel subagents hitting the cap in one episode
2594
- used to race a single read-modify-write counter and multiply the budget; each spent call
2595
- now claims an exclusive-create sentinel file, so the sentinels present are the true count
2596
- and one claim can never be counted twice (verified by an 8-process parallel test: exactly
2597
- the configured grants, the next call blocked).
2598
-
2599
- omp payloads moved off argv. PostToolUse Bash payloads embed whole tool outputs and exceed
2600
- macOS's ~256KB-per-argument limit, failing exec with E2BIG before any hook ran. The bridge
2601
- now writes the payload to a temp file (`@path` marker, hourly sweep, inline fallback for
2602
- read-only roots) and `hook-chain-runner.mjs` reads the marker; raw JSON never starts with
2603
- `@`, so both forms stay unambiguous.
2604
-
2605
- Compact recovery, directed. Near-cap advisories now order the work: land the smallest
2606
- finishable item end-to-end, defer the rest as one-line notes to disk, delegate broad
2607
- reads/searches to subagents, then ask the user to compact. A new post-compact check fires
2608
- once per compact boundary when the live context after the boundary is still ≥60% of the
2609
- cap: stop re-reading old files (the fastest way to re-inflate a just-compacted session),
2610
- delegate, or finish in a fresh session — UKit resume state carries the goal across with a
2611
- near-empty window. The reinjected PROJECT CONTEXT block carries the same discipline.
2612
-
2613
- Also fixed: `ukit install|diff --with-codegraph` crashed before the flag was consumed;
2614
- `route-task.mjs` helper commands use POSIX single-quote escaping instead of `JSON.stringify`
2615
- (printed commands were open to `$(...)`/backtick expansion) and reject absolute outside-root
2616
- targets instead of routing foreign-file context.
2617
-
2618
- ## 2.3.3 - 2026-09-10
2619
-
2620
- False-stop and long-context release. Four fixes that share one theme: UKit must run a prompt
2621
- to a finished result, and any stop must say why.
2622
-
2623
- Session-bound completion gate. Project-scoped route state could outlive the session-scoped
2624
- execution ledger, so a new session could inherit an older session's completion contract and
2625
- stop with a false `missing write-evidence` message. `skill-router.sh` now binds fresh, cached,
2626
- and route-less state to `sessionId`; `execution-ledger.mjs` accepts route state only when its
2627
- session matches the hook payload and ignores unbound legacy state for session-aware payloads.
2628
- Same-session gating and prompt-scoped evidence carry remain intact. Regression coverage now
2629
- covers mismatched sessions, unbound legacy state, and prior-session route isolation.
2630
-
2631
- Orchestration envelopes no longer corrupt the active route. `<task-notification>`,
2632
- `<tool-result>`, `<system-reminder>`, and `<local-command-caveat>…</local-command-stdout>`
2633
- payloads delivered through the prompt boundary were treated as explicit user prompts,
2634
- rewriting route/cache/audit state mid-run. `skill-router.sh` now ignores complete envelopes
2635
- before routing (fail-open, opening-tag attributes accepted); router exceptions surface on
2636
- stderr instead of disappearing. Related ownership fixes: Stop evaluation loads route state
2637
- with the current session payload, execution-ledger/route-task reject incompatible explicit
2638
- session ownership without inventing identity, subagent tool calls cannot rewrite the main
2639
- route, and cache entries are not touched before ownership is established.
2640
-
2641
- Ordinary long-context tasks preserve and resume. A natural-language routed task with no
2642
- `docs/AI_HANDOFF/RUN.md` previously hit the hard-cap gate with no landing window and no
2643
- resume cursor after compaction. Ordinary ledger state now gets the existing finite
2644
- `hardCapGraceCalls` landing budget (only with explicit session ownership, matching
2645
- session/prompt/request identity, unfinished evidence, and no blocker); the first grace call
2646
- writes a 30-minute hash-only resume intent that `handoff-resume.sh` consumes once and
2647
- emits as a continuation instruction with no raw prompt/command data. The
2648
- `context-window-guard.sh` fallback moved from 220k to the shipped 500k default.
2649
-
2650
- New `vibecode` autonomy level. One typed prompt must run to a finished result: with
2651
- `autonomy.level: vibecode`, the completion gate opts out of the continuation cap entirely and
2652
- keeps blocking (including the reentrant `stop_hook_active` Stop) until completion evidence
2653
- arrives or a genuine blocker is recorded — every block carries its reason. `deriveTaskRoute`
2654
- now propagates `autonomyLevel` and a `continuousExecution` policy
2655
- (`{ enabled, stopOn, maxContinuations }`) into `routeSummary` for every level, and
2656
- `validateRuntimeConfig` accepts the fourth level.
2657
-
2658
- Dangerous commands are a human decision, not a silent block. `block-dangerous.sh` now emits a
2659
- structured `permissionDecision: "ask"` (PreToolUse JSON) with the raw command scrubbed from
2660
- all output — arguments and comments can carry secrets — while exit 2 still refuses the call
2661
- for harnesses that ignore structured output. The omp bridge chain layer translates the same
2662
- structured decision into an `ask` verdict; because omp has no native ask, its host boundary
2663
- surfaces it as a block carrying the decision reason.
2664
-
2665
- ## 2.3.2 - 2026-09-09
2666
-
2667
- Docs-contract release. "Every stop says why — no silent idle" is now a shipping Execution
2668
- Contract rule, born from a real incident: a turn ended waiting for the user's `npm login`,
2669
- the request sat at the bottom of a long report, the user did their part (created
2670
- `~/.npmrc`), and the idle session looked exactly like a stall for 79 minutes.
2671
-
2672
- The new contract (identical in `CLAUDE.md` and `AGENTS.md`, parity-test enforced): when a
2673
- turn ends only because the user must act (login, approval, protected-file edit), the reply
2674
- opens with one line naming the exact action — `WAITING ON YOU: <command/action>` — and a
2675
- one-shot wakeup (~20-30 min) is scheduled when the harness provides one, so the session
2676
- re-checks and auto-continues once the user has acted. An ended turn cannot observe
2677
- external/auth changes by itself; without that line the idle session is indistinguishable
2678
- from a stall. Companion rule: any error (failed command, hook, test, publish) is reported
2679
- verbatim in the same turn, never silently retried past the user.
2680
-
2681
- Decision recorded in `docs/MEMORY.md` with the incident as the reason. Verified: all
2682
- doc-referencing suites 298/298 (incl. the CLAUDE↔AGENTS parity test, which caught the
2683
- first one-sided edit before it could ship), consistency 194/194.
2684
-
2685
- ## 2.3.1 - 2026-09-09
2686
-
2687
- "1 prompt mà đứng 10 lần" is fixed at the root. Four stall vectors in the completion
2688
- gate and router are gone, no stop is silent anymore, and routine backend model swaps
2689
- are now worked through instead of stalled on. All found by root-cause debugging with a
2690
- failing regression test per fix.
2691
-
2692
- 1) Stop-hook recursion: `execution-ledger.mjs --evaluate-stop` re-blocked the reentrant
2693
- Stop event (Claude Code re-invokes Stop with `stop_hook_active: true` after a block), so
2694
- one block became a self-sustaining block/continue chain ending in a cap-forced mid-task
2695
- stop. The gate now honors `stop_hook_active` and, when evidence is still missing, emits
2696
- a user-visible `systemMessage` instead of silently ending.
2697
-
2698
- 2) requestKey churn wiped evidence: `skill-router.sh` rebuilds requestKey per tool call
2699
- (commandText/targetFile are hashed in), so the first verification command re-keyed the
2700
- route mid-request and `--record` took the freshLedger path, erasing the write/verification
2701
- evidence the same request had produced — the gate then re-blocked until the cap forced a
2702
- silent stop. The ledger now keys evidence identity by the user prompt text
2703
- (`promptKey`); a re-key within one logical request carries evidence forward, a genuinely
2704
- new prompt starts clean.
2705
-
2706
- 3) Subagent stalls: subagent tool calls run the same hooks against the same session
2707
- ledger and route state (docs-confirmed; sidechain payloads carry `agent_id`/
2708
- `agent_type`). A subagent's Edit could re-route the request to a different
2709
- executionMode, which both broke the old promptKey identity (wiping main evidence) and
2710
- replaced the main route's completionEvidence. Fixes: promptKey is the prompt text alone
2711
- (null prompt never carries), and `skill-router.sh` early-exits on sidechain payloads so
2712
- subagent tool calls never touch the main route state. omp's bridge invokes the same
2713
- script, so every harness is covered.
2714
-
2715
- 4) No silent endings: the non-gated modes' `notify` and the post-cap `capped` paths now
2716
- emit a `systemMessage` alongside their stderr line — previously these ended turns with
2717
- the user seeing nothing.
2718
-
2719
- Gateway model swaps (limit hit → a different vendor model behind the same alias) are
2720
- detected from the transcript's per-assistant `message.model` and surfaced in
2721
- `context-window-guard.sh` as ONE routine line per hour: keep working, do not restart or
2722
- re-plan; if a tool call errors after a swap, re-check the tool and call it again. The
2723
- swap itself cold-reads the prompt cache once — that latency is transport-level and
2724
- cannot be removed by hooks; everything after it now continues automatically.
2725
-
2726
- Integrated on top of 2.3.0 (rebased; not published as 2.2.17): 2.3.0's stricter gates
2727
- made the re-key carry load-bearing for `targetedVerificationSucceeded`/`sourceFiles`
2728
- too — without carrying them, a mid-request re-key re-demanded targeted evidence and
2729
- re-introduced the stall this release fixes (regression-tested RED→GREEN). The 2.3.0
2730
- notify test that expected a silent stdout was updated to the no-silent-stops contract.
2731
-
2732
- Verified: executionLedgerCli 29/29, skillRouterHook 33/33, contextWindowGuard 18/18;
2733
- full suite 1280/1280 (74 files) and `release:verify` green on the integrated tree;
2734
- template↔live mirrors byte-identical (live settings.json re-rendered through the install
2735
- pipeline, not copied raw).
2736
-
2737
- ## 2.3.0 - 2026-09-08
2738
-
2739
- Model-agnostic hardening release. Every configured model name is treated as a gateway
2740
- mapping whose backend can change at any time, so correctness now comes from stable role
2741
- contracts, explicit evidence, and regression fixtures — never provider identity.
2742
-
2743
- **Sensitive-data gate (fail-closed, default ON).** NEW `sensitive-data-guard.sh` scans
2744
- PreToolUse Read/Grep paths, Bash commands (secret-dump shapes, inline credentials,
2745
- high-confidence token patterns like `sk-…`), and UserPromptSubmit text; on suspicion it
2746
- blocks with exit 2 and shows only redacted previews (3-char prefix + length + sha256
2747
- prefix) — never the value. The only approval path is the USER editing the protected
2748
- allowlist `.ukit/storage/security/allowlist.json` (sha256 of the value, or an allowed file
2749
- path); `security.sensitiveDataGate: true` ships as the default and the gate can be disabled
2750
- in `.ukit/storage/config.json` for debugging. Wired into Claude settings hook chains, the
2751
- omp bridge, and the install manifest. Live-fire verified across all four channels.
2752
-
2753
- **Contract tables unified to one source.** NEW `src/core/executionContracts.js` is the
2754
- canonical table set (execution modes, contracts, contract→tier mapping, risk profiles).
2755
- `taskRouting.js` imports it, runtime config defaults derive from it, and the shipped
2756
- `route-task.mjs` keeps a literal copy locked by a new sync test — fixing a real drift where
2757
- route-task's `local-build` contract was missing verification evidence and the post-edit
2758
- review policy. `config.json` no longer duplicates `modelTier` per contract.
2759
-
2760
- **Tier-role wiring.** Route state now carries a `tierLane` hand-off: silent when the
2761
- contract tier is `code` (the default implementation lane), an explicit "hand this to an
2762
- agent bound to the lite/smart tier" instruction otherwise, and it follows `escalatedTier`
2763
- on repeat failures. This surfaced and fixed a real gap: `compactRouteSummary` is a
2764
- whitelist and was silently dropping `expectedSourceFiles`, which made target-aware
2765
- completion evidence inert on the real CLI path.
2766
-
2767
- **Evidence tightening.** Completion-gate `impact-evidence` now requires reading one of the
2768
- routed target files (any random read no longer counts), and verification receipts record
2769
- `targeted` vs `broad` scope against the routed verification plan; recovery instructions
2770
- name the exact files expected.
2771
-
2772
- **Vision flow smoothing.** Already-analysed images no longer re-trigger route hints
2773
- (`alreadyAnalyzed[]` from `extract-image.mjs --json`); unresolvable image paths get a short
2774
- note instead of a wrong remedy; the vision analyst gets a capability self-check (first
2775
- image Read is the probe), a task envelope carrying the ORIGINAL user prompt verbatim, and
2776
- an observations-vs-inference output block; hook-chain budgets now scale with chain size so
2777
- growing Edit/Write chains never orphan the runner.
2778
-
2779
- **Mapping fingerprint fixtures.** New consistency tests lock agent↔tier bindings across
2780
- Claude Code and omp, the omp modelRoles → `unic-*` labels, and the tier structure
2781
- (vision stays a capability tier outside the escalation ladder) — provider identities are
2782
- deliberately left unpinned so gateway mappings can change freely without breaking
2783
- behavior contracts.
2784
-
2785
- Verified: `yarn test` 1277/1277 (74 files), `test:release-core` 1270, `test:artifact` 7,
2786
- `release:verify` all checks passed, 13/13 handoff node suites, sensitive-data-guard
2787
- live-fire 5/5 as designed.
2788
-
2789
- ## 2.2.16 - 2026-09-06
2790
-
2791
- The vision gate is gone — image work is advisory-routed, never blocked. Since TASK-008, a
2792
- pasted image on the UNIC gateway armed `vision-gate.sh`, which refused every Edit/Write until
2793
- `ukit-vision-analyst` had produced receipts for ALL pending images. In practice this
2794
- repeatedly stranded sessions (receipts that never landed, one stale marker blocking
2795
- unrelated writes), so the maintainer retired the hard block: `vision-gate.sh` and its
2796
- manifest entry `hook-vision-gate` are removed from both the live tree and templates, the omp
2797
- bridge and `hook-chain-runner.mjs` no longer list it, and `vision-router.sh` now says "never
2798
- guess at image contents" instead of claiming edits are GATED. Routing to
2799
- `ukit-vision-analyst` still happens — on this gateway the main tier genuinely cannot read
2800
- images — but nothing blocks while it runs. Supersedes the 2.2.15 escape hatch, which patched
2801
- a message on a gate that no longer exists. Verified: vision-hook, route-vision,
2802
- vision-agent, install-wiring, provision-worktree, and ompHookBridge (52/52) all green.
2803
- (An interim 2026-09-05 patch that added an escape hatch to the block message is included
2804
- here and immediately superseded — the gate itself no longer exists.)
2805
-
2806
- ## 2.2.14 - 2026-09-05
2807
-
2808
- The context hard-cap gate no longer bricks healthy sessions with a phantom token count. The
2809
- tracker behind `compact.hardCapTokens` accumulates every prompt and tool output across a
2810
- session, and it only reset on the PreCompact hook — which fires for a manual `/compact` but not
2811
- for every harness auto-compact path (SDK/VSCode being the known gap). A session whose live
2812
- context had been compacted down to almost nothing could therefore reach a tracked 528k against
2813
- the 500k cap: Read/Grep stayed open but every Edit/Write/Bash was refused, and the user saw the
2814
- assistant freeze with no error. Every real compaction — manual or automatic — now also leaves a
2815
- `compact_boundary` entry in the session transcript, so `compact-threshold.mjs` rebase the
2816
- counter from that record (`syncCompactPressureStateWithTranscript`, stamped
2817
- `lastCompactBoundaryAt` so each boundary resets exactly once). Both the prompt-time hook and
2818
- `context-hardcap-gate.sh` sync before acting, and the reset is persisted so the gate re-arms
2819
- instead of disabling itself.
2820
-
2821
- When the cap is genuinely reached, the model is now ordered to tell the user instead of going
2822
- quiet. The hard-phase prompt warning and the gate's block message both lead with an explicit
2823
- directive — tell the user "gõ /compact ngay" as the first sentence of the reply, since typing
2824
- "continue" alone hits the same block — and the advisory soft phase tells the model to surface
2825
- `/compact` at the next natural pause. `context-window-guard.sh`'s overflow directive likewise
2826
- demands the compact instruction as the first sentence rather than a buried suggestion.
2827
-
2828
- Vietnamese concrete bug reports route to the debug lane again. Signals such as `lỗi`, `sửa`,
2829
- `đăng nhập`, `đang ở đâu` were written inside `\b(...)\b`, but JavaScript `\b` is ASCII-only and
2830
- those words have diacritic edges, so the patterns could never match — "app bị lỗi khi đăng nhập,
2831
- sửa giúp tôi" fell through to informational lanes while the identical English prompt routed
2832
- correctly. All Vietnamese intent patterns in the router and catalog now use explicit
2833
- `(?<![A-Za-z0-9_])` / `(?![A-Za-z0-9_])` edges; regression tests cover the debug-lane prompt,
2834
- the open-ended status question, and hook-level state.
2835
-
2836
- ## 2.2.13 - 2026-09-05
2837
-
2838
- Question-shaped prompts no longer get blocked by the completion gate. "Đây là lỗi gì?",
2839
- "model bạn đang dùng là model gì", or "what is this error?" route to the informational lane and
2840
- answer freely; only prompts that actually ask for a change (fix/sửa/build/…) still owe write and
2841
- verification evidence before claiming done. Two layered causes: the Vietnamese question pattern
2842
- only matched adjacent `là gì` (missing "là model gì" / "là lỗi gì"), and the `\blỗi` veto never
2843
- fired at all — JavaScript `\b` word boundaries don't exist around diacritic characters. A
2844
- `strongQuestion` signal (an explicit `?`, a leading interrogative, or the Vietnamese pattern) now
2845
- overrides error-wording vetoes, while "error when I run tests" and "why is build failing?" still
2846
- route to investigation.
2847
-
2848
- The source-code index understands SQL from the canonical source, not just the installed mirror.
2849
- `CREATE TABLE/VIEW/FUNCTION/PROCEDURE/INDEX/TYPE` and `ALTER TABLE` statements are extracted as
2850
- symbols with schema-qualified names captured by their bare object name (`qas.fn_rpt_billing` →
2851
- `fn_rpt_billing`), and `.sql` files are tracked and code-indexed. The schema bump had previously
2852
- landed only in the runtime mirror; `src/index/` now carries the same v8 schema so the mirror-parity
2853
- test holds and the `scripts/index` lane benefits too.
2854
-
2855
- The handoff model-tier guard closes an under-block found while scenario-testing it. Once a real
2856
- `EXECUTOR_MODEL` or `REVIEWER_MODEL` was on disk, an in-place rewrite could silently demote the
2857
- executor to a lite tier or set executor == reviewer; validation now also fires when an
2858
- already-real model line changes value (same-model rewrites and upward escalation stay free). The
2859
- push-time backstop was unaffected — this moves the rejection to write time, where it belongs.
2860
-
2861
- `handoff.maxParallelAgents` template default is now 2, matching the operator setting; the config
2862
- help prose no longer claims a default of 12 one line above a configured 2.
2863
-
2864
- ## 2.2.12 - 2026-09-04
2865
-
2866
- `ukit install` and `ukit update` now clean up broken Claude Code hook registrations automatically.
2867
-
2868
- A hook whose stdout contains a `hookSpecificOutput` object without the required `hookEventName`
2869
- field fails Claude Code's schema validation on **every** tool call, surfacing as a repeating
2870
- `PreToolUse:<Tool> hook error — Hook JSON output validation failed`. Such a hook has no effect
2871
- either way, since its output is discarded — it produces nothing but noise.
2872
-
2873
- New `src/core/repairBrokenHooks.js` detects that shape generically (not keyed to any one vendor)
2874
- across user settings, project settings, and `settings.local.json`, expanding
2875
- `$CLAUDE_PROJECT_DIR`/`$HOME`/`~` in hook commands and also catching hooks inlined into
2876
- `settings.json` instead of a script file. Offending registrations are removed after a
2877
- `.ukit-backup` restore point is written next to each settings file. Detection matches only real
2878
- key assignments, so prose mentions of the field in a hook's own comments or docstrings never
2879
- trigger a removal.
2880
-
2881
- Wired into the install pipeline; since `ukit update` re-runs `ukit install`, both commands are
2882
- covered with no new flags or commands to learn — teammates still only need `ukit install`.
2883
-
2884
- Scope is deliberate: UKit removes the *registration* only. An unregistered hook script never
2885
- executes, so that is sufficient, and UKit does not delete the script file or uninstall the tool
2886
- that wrote it. When the owning tool can be identified from the hook source, the install report
2887
- names it and notes that it may re-register on activation, leaving permanent removal as a human
2888
- decision.
2889
-
2890
- Known real-world instance: VSCode extension `tjcg.auto-accept-claude-code` v0.5.0 hardcodes two
2891
- such hook templates and rewrites its hook file on activation.
2892
-
2893
- ## 2.2.11 - 2026-08-29
2894
-
2895
- Same-day follow-up to 2.2.10. The two premises that release shipped as unverified were checked
2896
- against omp's own installed TypeScript source (`@oh-my-pi/pi-coding-agent` v18.0.10, not a live
2897
- session — omp still was not run) and both hold:
2898
-
2899
- - **`steer` after a compaction is accepted, not dropped.** `session-maintenance.ts` fires
2900
- `session_compact` only after `agent.replaceMessages()`/`rebaseAfterCompaction()` already ran, so
2901
- the session is idle at that point, and `agent-session.ts`'s `sendCustomMessage()` non-streaming
2902
- branch appends the message to the live context regardless of `deliverAs`.
2903
- - **`display: true` does trigger a visible re-render.** `extension-ui-controller.ts`'s
2904
- `applyCustomMessageDisplay()` calls `rebuildChatFromMessages()` for the non-streaming case (the
2905
- streaming case renders via the `message_end` event instead).
2906
-
2907
- `templates/.omp/hooks/pre/ukit-bridge.js`'s two `TODO(verify)` comments (PLAN.md §3 D3, D4) are
2908
- updated to record this — from "unverified, additive, worst-case-unchanged" to "source-confirmed,
2909
- one rung below a live repro." No runtime behaviour changes; both delivery paths (`steer` +
2910
- `nextTurn`, and the `finalNotice` fallback) stay in place as defense in depth either way. A stale
2911
- local `.omp/hooks/pre/ukit-bridge.js` install artifact in this repo — untracked, regenerated by
2912
- `ukit install`, and out of sync with `templates/.omp/` since before 2.2.10 shipped — was also found
2913
- and resynced; that file is never part of the published package.
2914
-
2915
- ## 2.2.10 - 2026-08-29
2916
-
2917
- User report: long omp (Oh My Pi) sessions go idle roughly 15 minutes into a task — no output, no
2918
- error, no notification, indistinguishable from a hang. Typing `continue` makes the session resume
2919
- and finish correctly (the user's observation, not a measurement — no field reproduction of the
2920
- stall exists on this machine to time it). Three real root causes were found by reading the source,
2921
- not guessed:
2922
-
2923
- ### Fixed
2924
-
2925
- - **`map-impact` — the mode wide implementation work actually routes to — was never gated by the
2926
- completion loop.** `templates/.claude/ukit/runtime/execution-ledger.mjs:12`'s `IMPLEMENT_MODES`
2927
- set omitted it, while `src/index/taskRouting.js:414` routes exactly this kind of task to
2928
- `map-impact` and `src/index/taskRouting.js:610` gives it the strictest contract
2929
- (`impact-evidence`, `write-evidence`, `verification-evidence`). So the longest tasks declared the
2930
- most evidence and got no gate at all — the session could stop with nothing written and nothing
2931
- verified, silently. `map-impact` is now in `IMPLEMENT_MODES`.
2932
- - **Reaching the continuation cap ended the session with a log line, not a message.** At
2933
- `MAX_CONTINUATIONS` (6, unchanged), `evaluateCompletion` returned `{ capped: true }` and the only
2934
- reaction was `pi.logger.warn` — a log sink, not the transcript. This is also the mechanical reason
2935
- a new prompt (`continue`) appeared to "fix" the stall: a new prompt writes a fresh `requestKey`,
2936
- which resets the per-request continuation count back to zero. The gate now spends exactly one
2937
- final continuation (`finalNotice`) instructing the model to state what is unfinished and stop, and
2938
- persists a one-shot `notified` flag on the ledger so the notice cannot refire.
2939
- - **The post-compact resume was delivered only to the next user turn, and every UKit→omp message was
2940
- `display: false`.** After an omp auto-compaction, the `docs/AI_HANDOFF/RUN.md` resume cursor was
2941
- sent with `deliverAs: 'nextTurn'` only — if compaction ended the agent loop, the cursor waited for
2942
- a human to type something. Separately, every message the bridge built hardcoded `display: false`,
2943
- so UKit had no user-visible channel in omp at all, for context or for stop notices.
2944
- `runSessionCompact` now sends the resume as `steer` (reaches a still-running turn) *and*
2945
- `nextTurn` (unchanged fallback), and `runSessionStop` now sends one `display: true` notice
2946
- whenever it stops with evidence still missing — including the previously-silent
2947
- `review-release` / ungated-mode case.
2948
-
2949
- **Two premises behind the third fix are unverified — omp is not installed in this development
2950
- environment.** Whether omp still accepts a `steer` message after a compaction, and whether omp
2951
- honours `display: true` on a bridge message, were not and could not be reproduced or measured here.
2952
- Both changes are additive: if either premise is false, the `nextTurn` delivery and the model's own
2953
- `finalNotice` message (from the second fix) still reach the user, so the worst case is unchanged
2954
- from today's behaviour, never worse. See `docs/STATUS.md` for the open thread and the evidence that
2955
- would confirm the continuation-cap path directly.
2956
-
2957
- - **`templates/.omp/RULES.md` gains one sticky rule**: ending a turn with no output is a defect, not
2958
- a pause — a model-side backstop for whatever a code gate cannot reach.
2959
-
2960
- ## 2.2.9 - 2026-08-28
2961
-
2962
- Retuning UKit's context budget used to mean editing five scattered places and hand-syncing two
2963
- of them. It is now **three numbers in one file**, and everything else is derived at install time.
2964
-
2965
- The shipped defaults also move up for a 1M context window: compaction is recommended at 150,000
2966
- estimated tokens (was 50,000) and the hard cap sits at 500,000 — half the window (was 220,000).
2967
-
2968
- ### Changed
2969
-
2970
- - **`compact.tokenThreshold` / `compact.hardCapTokens` / `compact.autoCompactWindowRatio` in
2971
- `.ukit/storage/config.json` are now the only knobs.** New `src/core/compact/contextBudget.js`
2972
- reads them and derives the rest, so the defaults in `runtimeConfig.js` and
2973
- `compact/threshold.js` no longer carry their own copies of the number. Edit the three values,
2974
- rerun `ukit install`, and the whole budget follows. Documented in README →
2975
- *Retuning The Context Budget (maintainers)*, including a window→cap sizing table, because the
2976
- new 500,000 default sits **above** a 200k or 256k model's window, where the gate could never fire.
2977
- - **New defaults:** `tokenThreshold` 50,000 → **150,000**; `hardCapTokens` 220,000 → **500,000**;
2978
- auto-compact fires at **70%** of the cap → 350,000.
2979
-
2980
- ### Fixed
2981
-
2982
- - **omp auto-compact had silently drifted out of sync.** `.omp/config.yml`'s
2983
- `compaction.thresholdTokens` was still 180,000 while Claude Code's
2984
- `CLAUDE_CODE_AUTO_COMPACT_WINDOW` had moved on — the two were separate hand-maintained numbers
2985
- with nothing pinning them together. Both are now rendered from the same derived value at
2986
- install time, so **omp and Claude Code auto-compact at the same point** and cannot drift apart
2987
- again.
2988
- - **`ompDocsSync > historical records are untouched by this cycle` failed on every new plan doc.**
2989
- The guard compared *all* changes under `docs/plans/` and friends against an old cycle's base
2990
- commit, so the first plan added afterwards (2.2.8's) tripped it permanently. Narrowed to
2991
- `--diff-filter=MDR`: rewriting, deleting or renaming a historical record still fails; adding a
2992
- new plan does not.
2993
-
2994
- ## 2.2.8 - 2026-08-28
2995
-
2996
- UKit already picked the right files to open, but the step *after* that — actually entering the
2997
- file — was unoptimised: the agent read the whole thing to find the one function it needed. This
2998
- release adds a signature outline so it can jump straight to a line instead.
2999
-
3000
- The outline is a map for **locating** code, not a substitute for reading it. Any code that is
3001
- about to be changed must still be read; the saving comes from narrower reads, not skipped ones.
3002
- That rule is stated in the shipped `CLAUDE.md` / `AGENTS.md` guidance next to the feature itself.
3003
-
3004
- ### Added
3005
-
3006
- - **Indexed symbols now carry `line` and `signature`.** `query-index` and `resolve-context` print
3007
- an `outline:` block (`line: signature`) for the top suspect files, so an agent can go straight
3008
- to `Read(file, offset=<line>)`. On this repo, locating the top-3 suspects for a representative
3009
- query costs 2,082 bytes / 25 lines instead of 131,702 bytes / 4,064 lines of whole-file reads.
3010
- On by default; `--no-outline` turns it off. Capped at the top 3 files and 12 symbols each.
3011
- - **`getFileOutline()`** in the index core, returning line-sorted, name-deduped rows. Missing
3012
- file, missing artifact, or a stale schema all resolve to `[]`, so callers can render
3013
- unconditionally.
3014
- - **First behavioural parity test for the hand-maintained index mirror**
3015
- (`tests/index/indexCoreParity.test.js`). `templates/.claude/ukit/index/lib/index-core.mjs`
3016
- duplicates `src/index/*` by hand and was flagged in `MIRROR_PAIRS` but never actually compared;
3017
- drift could only be caught by reading both files. It is now asserted.
3018
- - **Both harnesses covered.** omp runs the same Node helpers and reads `AGENTS.md`, so the
3019
- guidance ships identically in `templates/CLAUDE.md` and `templates/AGENTS.md` (byte-identical
3020
- section bodies, enforced by `tests/consistency/contextDocsParity.test.js`). No separate omp
3021
- code path was needed.
3022
-
3023
- ### Fixed
3024
-
3025
- - **`.vue` line numbers would have been silently wrong.** `extractScriptContent` joined the
3026
- `<script>` blocks together, so a symbol in the second block reported a line number offset by the
3027
- whole `<template>` above it. Script regions are now masked in place, preserving byte offsets, so
3028
- reported lines match the file on disk.
3029
-
3030
- ### Changed
3031
-
3032
- - `INDEX_SCHEMA_VERSION` 6 → 7. Existing `.cache/index/` artifacts are invalidated and rebuilt
3033
- automatically on first use; no migration step and no user action.
3034
-
3035
- ## 2.2.7 - 2026-08-28
3036
-
3037
- Follow-up to 2.2.6: that release only made the wrong-runtime failure message *explain* the
3038
- `UKIT_NODE_PATH` workaround better, but a user still had to diagnose the error and export the
3039
- variable by hand. This release removes the manual step for the common case.
3040
-
3041
- ### Fixed
3042
-
3043
- - **The omp bridge now auto-detects a working Node.js binary instead of requiring
3044
- `UKIT_NODE_PATH` to be set by hand.** [`ukit-bridge.js`](.omp/hooks/pre/ukit-bridge.js) probes
3045
- `process.execPath` with `--version` before trusting it; if that fails (e.g. a Bun-hosted or
3046
- self-compiled omp reporting its own binary as `process.execPath`), it falls back to the bare
3047
- `node` command name and lets normal OS `PATH` resolution find a real Node.js binary — this
3048
- works the same way on macOS, Linux, and Windows, since Node's `child_process` spawn does `PATH`
3049
- lookup for bare executable names on all three. An explicit `UKIT_NODE_PATH` still always wins
3050
- and skips the probe. The probe result is cached for the life of the omp process, so it only
3051
- runs once, not on every tool call. The transport-failure message's `UKIT_NODE_PATH` hint now
3052
- only appears when both the probe and the `node` PATH fallback have failed.
3053
-
3054
- ### Added
3055
-
3056
- - **1 regression test** in `tests/hooks/ompHookBridge.test.js` — with `UKIT_NODE_PATH` unset and
3057
- `process.execPath` mocked to fail the `--version` probe, the bridge falls back to invoking the
3058
- bare `node` command instead of blocking the tool call.
3059
-
3060
- ## 2.2.6 - 2026-08-27
3061
-
3062
- Follow-up to a real-world report: a user on a Bun-hosted/self-compiled omp build kept getting
3063
- every Edit/Write blocked with `UKit OMP hook runner failed before producing a valid result
3064
- (killed=true, ..., runtime=/Users/.../bin/omp)`. The diagnostic added in 2.2.4 was already
3065
- honest about the failure, but it did not say *why* — `runtime=` pointed straight at omp's own
3066
- binary (proof that `process.execPath` inside that omp build resolves to omp itself, not a real
3067
- Node.js binary), yet the message never told the user the fix was to set `UKIT_NODE_PATH`.
3068
-
3069
- ### Fixed
3070
-
3071
- - **The omp bridge's transport-failure message named the wrong-runtime symptom but never the
3072
- fix.** [`ukit-bridge.js`](.omp/hooks/pre/ukit-bridge.js) already resolved
3073
- `process.env.UKIT_NODE_PATH || process.execPath` and reported the resolved `runtime` on failure
3074
- (2.2.4), but a user seeing `runtime=/Users/lenk/.local/bin/omp` had no way to know that string
3075
- meant "wrong binary" or what to do about it. When `UKIT_NODE_PATH` is unset, the failure
3076
- message now appends: the reported runtime may not be a real Node.js binary, and the exact fix —
3077
- `export UKIT_NODE_PATH="$(command -v node)"`. No behavior change when `UKIT_NODE_PATH` is
3078
- already set.
3079
-
3080
- ### Added
3081
-
3082
- - **2 regression tests** in `tests/hooks/ompHookBridge.test.js` (case 13) — the wrong-runtime
3083
- hint appears when `UKIT_NODE_PATH` is unset, and is omitted when it is already set.
3084
-
3085
- ## 2.2.5 - 2026-08-27
3086
-
3087
- Follow-up to the user's report that UKit had become too heavy-handed: too many hook scripts firing per tool call, too much blocking, and a concrete false-positive in the destructive-command gate itself. This wave trims default hook wiring and fixes the false positive, while explicitly preserving `rm`/destructive-command protection as instructed.
3088
-
3089
- ### Changed
3090
-
3091
- - **`PreToolUse:Bash` now runs 4 hook scripts instead of 6.** `verification-guard.sh` was removed from the default Bash chain (both `.claude/settings.json` copies, the omp bridge's `HOOK_EVENT_MAP`/`FAIL_CLOSED_SCRIPTS`, and `hook-chain-runner.mjs`'s own classification). Its hard-block path is gated behind `UKIT_VERIFICATION_GUARD_ENFORCE=1`, unset by default, so it was pure per-call overhead (a full `node` spawn) for zero present safety value. The script and its standalone tests are untouched — still shippable, opt-in.
3092
- - **`PreToolUse:Read|Grep|Glob` no longer runs `skill-router.sh`.** Automatic skill activation still runs on `UserPromptSubmit` and `Edit|Write`, where a skill choice actually matters;
3093
-
3094
- ### Fixed
3095
-
3096
- - **`block-dangerous.sh` misidentified dangerous *text* as a dangerous *command*.** Both its per-pattern denylist and its `rm` handling matched against the entire raw command string with no awareness of shell quoting, so `grep -rn "rm -rf" .` or `echo "rm -rf /tmp/foo"` — which merely mention the text — were blocked as if they executed it. Quoted spans are now scrubbed before matching, but only when the command's own invoked program is a pure text tool (`grep|egrep|fgrep|rg|ag|awk|sed|echo|printf|cat`) and it does not pipe into a shell/eval sink (`| bash|sh|zsh|eval|xargs`), since `echo "rm -rf /" | bash` really does execute the quoted text. Every other command shape is scanned exactly as strictly as before.
3097
- - **`rm -rf ./dist` (and other allowlisted safe-cleanup targets with a `./` prefix) was blocked as an "unsafe delete target."** The unsafe-target check ran before the safe-cleanup allowlist check and its pattern misfired on the literal `./` prefix. Reordered so the allowlist is checked first; genuinely risky targets like `rm -rf ../important` still block.
3098
-
3099
- ### Added
3100
-
3101
- - **11 regression tests** in `tests/hooks/blockDangerous.test.js` covering the false-positive fix, the closed shell-pipe escape hatch, the `./dist` allowlist fix, and all pre-existing destructive-command blocks (`rm -rf /`, `rm -rf ~`, `rm -rf .`, `rm -rf ../important`, `git push --force`, `git reset --hard`).
3102
-
3103
- ## 2.2.4 - 2026-08-27
3104
-
3105
- Follow-up to 2.2.3's hook-chain collapse: a real omp session on a CloudMounter/FUSE-mounted project reported every tool call — including harmless `echo`, `pwd`, `ls`, and `Edit` — failing with `invalid hook-chain output`, and in one case `protect-files.sh hook chain was killed before safety gates completed`, despite `protect-files.sh` itself passing trivially. The bridge was misattributing any aggregate-runner transport failure to the first fail-closed script in the chain, whether or not that script ever ran.
3106
-
3107
- ### Fixed
3108
-
3109
- - **Outer transport failures no longer impersonate a specific safety gate.** `runScriptChain` in `ukit-bridge.js` treated a killed/timed-out `pi.exec`, empty stdout, or malformed JSON from `hook-chain-runner.mjs` as proof that the chain's first fail-closed script (e.g. `protect-files.sh`) had failed — without verifying that script ever ran. It now distinguishes "the runner returned a verifiable per-script result" from "the runner itself failed before producing one," and on the latter reports the real failure (killed/code/elapsedMs/runtime) instead of a fabricated gate name. Diagnostics are appended to `.ukit/storage/cache/hook-errors/<session>.jsonl`.
3110
- - **Bash and Read/Grep/Glob no longer fail closed on a bridge/runner outage.** Only `Edit`/`Write` chains still block when the runner can't produce a verdict, since those guard file mutation.
3111
- - **`process.execPath` is no longer trusted blindly for the runner subprocess.** The bridge resolves `process.env.UKIT_NODE_PATH || process.execPath` and records the resolved runtime in the failure diagnostic, so a Bun-hosted omp launching the Node-only runner under the wrong binary is now visible instead of silently assumed.
3112
-
3113
- ### Added
3114
-
3115
- - **6 regression tests** in `tests/hooks/ompHookBridge.test.js` (`case 13`) covering a killed outer exec, malformed stdout, a non-zero exit with empty stdout before any script ran, fail-open behavior for Bash and Read chains under the same failures, and `UKIT_NODE_PATH` override.
3116
-
3117
- ## 2.2.3 - 2026-08-26
3118
-
3119
- Sessions were stalling mid-task — the model would read source, then simply stop, with the work half done and nothing wrong upstream. This wave stops treating that as a prompting problem. Instructions asking a model to "continue until the edit is made" are advisory by nature: every hidden backend behind `unic-lite` / `unic-code` / `unic-smart` / `unic-vision` reads them slightly differently, and the ones that read them loosely stall. UKit now records what actually happened — real Edit/Write receipts, real verification exit codes — and enforces completion mechanically at the point of stopping, identically on Claude Code and omp. Nothing in the enforcement path branches on provider branding.
3120
-
3121
- ### Fixed
3122
-
3123
- - **Silent stalls were unenforceable, because nothing measured them.** A stop after a read-only pass was indistinguishable from a stop after finished work:
3124
- - **The omp bridge could exceed omp's own handler budget and freeze the session.** A single `Edit` fired 7 hook scripts as 7 serial `pi.exec` subprocesses at up to 8s each — worst case well past omp's ~30s outer timeout, which surfaces to the user as the session simply hanging. They now run in one bounded `hook-chain-runner.mjs` process: 4s per script, 10s total budget, under a 12s outer timeout. Per-event latency is appended to `.ukit/storage/cache/hook-latency/<session>.jsonl` so hook cost stops being invisible.
3125
- - **omp writes bypassed the safety gates entirely.** omp's `normalizeToolEventInput` emits `path` / `paths`;
3126
- - **An unmapped mutation-capable tool failed open and silently.** `mapToolName` returned `null` for any tool not in its table, and the bridge ran an empty script chain — so a host tool that writes files but is not yet mapped skipped every guard with no signal. Such tools are now blocked with a message naming the tool; unmapped read-only tools still pass through.
3127
- - **The ledger CLI silently did nothing under a symlinked project root.** Its main-guard compared `fileURLToPath(import.meta.url)` against `path.resolve(process.argv[1])`.
3128
- - **`.omp/config.yml` documented the model aliases backwards**, calling the UNIC names "LITERAL model names, not aliases".
3129
-
3130
- ### Added
3131
-
3132
- - **`tests/hooks/executionLedgerCli.test.js`** (4 tests) — drives the real CLI through a symlinked root:
3133
- - **Manifest entries and dev-mirror parity for the four new files** — `record-execution.sh`, `completion-gate.sh`, `execution-ledger.mjs`, `hook-chain-runner.mjs`.
3134
-
3135
- ## 2.2.2 - 2026-08-22
3136
-
3137
- Running Claude Code and omp side by side exposed that they were not, in fact, running the same UKit. `CLAUDE.md` and `AGENTS.md` are hand-maintained forks of one instruction set read by different harnesses, and `AGENTS.md` had fallen three minor versions behind — so omp was never told the model-tier table existed. This wave re-unifies them and adds a test that makes the drift impossible to repeat.
3138
-
3139
- It also settles the three `TODO(verify)` items 2.2.1 shipped with. Those were plan-time guesses about omp's API, unresolvable at the time because omp was not installed on any machine that could answer them. omp v17.4.2 is now installed and was inspected directly — and two of the three guesses were wrong, in the quiet way where nothing errors and the feature simply never engages.
3140
-
3141
- ### Fixed
3142
-
3143
- - **Auto-compact was never actually configured on omp.** `.omp/config.yml` set `compact.autoCompactWindow:
3144
- - **Post-compact hooks never ran on omp.** The bridge assumed omp re-emitted `session_start` after a compaction, the way Claude Code's matcher-less `SessionStart` hook fires with `source:
3145
- - **Two UNIC gateway probes could never have fired.** `unic-gateway.mjs` probed an `OMP_BASE_URL` env var and a `baseUrl` key in `.omp/config.yml`.
3146
- - **omp behaved as if UKit only had one model, because it was never told otherwise.** `templates/AGENTS.md` — the context doc omp, Codex and OpenCode read — was missing the entire `3-Tier Model Routing` block, plus `Post-Edit Sidecar Review` and `Skill Quality`, and still announced itself as `UKit v1.5.1`. `.omp/config.yml` declared `modelRoles` for all four lanes, but nothing in omp's context ever said *when* to use a tier, so everything ran inline on the session model.
3147
- - **Five section pairs had been renamed apart** — `Core Rule`/`Core UKit Rule`, `Fast Classification`/`Fast Task Classification`, `Internal Helper Policy`/`Internal Helper Routing`, `Selective Subagent Policy`/`Subagent Policy`, `Project Snapshot`/`Environment Snapshot`. This is what let the drift hide: once the headings differ, no diff lines up and the gap is invisible. Headings are now shared, and the two docs carry byte-identical bodies for every shared section.
3148
- - **Every session opened by being told to resume a finished cycle.** `docs/AI_HANDOFF/RUN.md` was left at `Phase:
3149
- - **`/ukit:*` commands re-pasted the user's whole problem statement up to seven times per file.** Only one `$ARGUMENTS` site per command is a real interpolation (the `## Problem / feature` body);
3150
- - **Eight fallback lines told the model to do something only a human can do.** `> Other tools without subagent support:
3151
-
3152
- ### Added
3153
-
3154
- - **`### How a tier is actually bound`** in both context docs. The main session model never changes mid-turn;
3155
- - **`tests/consistency/contextDocsParity.test.js`** (29 tests) — every `## ` section must exist in both `templates/CLAUDE.md` and `templates/AGENTS.md` with byte-identical bodies, unless allowlisted with a stated reason (currently one entry: `Session Start — OpenCode`, which exists because OpenCode does not auto-load `.claude/skills/`). Also asserts neither doc hardcodes a version, and that both manifest items declare the same variable set.
3156
- - **`.omp/RULES.md` grew from 4 rules to 7**, targeting direct chat specifically — direct chat is steered only by static context, so what is missing there is simply never applied.
3157
- - **The three `/ukit:*` sites that named only Claude Code now name omp too** — `handoff-fullstack.md`'s Model Split note, and the small-task-maintainer lines in `handoff-clear.md` and `handoff-status.md`.
3158
-
3159
- ### Changed
3160
-
3161
- - **Four more expired one-shot guards re-anchored, same class as the two below.** `ompDocsSync` cases 3 and 6 validated "the top CHANGELOG entry" — true on the day 2.2.1 shipped, false at the next release; they now find the omp entry by version. `ompContextLayer` case 10 guarded the compact key with a `TODO(verify)` marker instead of a value, and now asserts the verified key plus its provenance. `tests/handoff/cycle4/unic-gateway.test.mjs` case 13b had never actually run (it took its skip branch because the file it checked did not exist yet) and was matching a key spelling — `@vision:` — that belongs to the agent side, not the config side.
3162
- - **`tests/consistency/ompCommandParity.test.js` cases 4 and 5 no longer diff against `git show HEAD:`.** They were scope guards for one in-flight cycle ("TASK-005 must not modify these"), and that premise expired when the cycle shipped: against a committed baseline they pass vacuously, and against a dirty tree they block every later legitimate edit instead — which is exactly what they did. Both are re-expressed as the durable properties they stood in for (no `subagent_type` site in the two non-delegation commands; pinned per-file `Do NOT` and tier-justification-clause counts). No protection was dropped, only re-anchored.
3163
-
3164
1599
  ## 2.2.1 - 2026-08-22
3165
1600
 
3166
1601
  UKit gains a fourth runtime and loses one. omp (Oh My Pi) reaches full parity with the Claude Code workspace — same agents, same skills, same hooks, same `/ukit:*` commands — and the Antigravity adapter, unused and unmaintained, is gone. The parity is deliberate rather than incidental: the port reuses the existing `.claude/` assets wherever omp's discovery can already reach them, so there is one source of truth per capability, not two that drift.
@@ -3192,99 +1627,4 @@ UKit gains a fourth runtime and loses one. omp (Oh My Pi) reaches full parity wi
3192
1627
 
3193
1628
  **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`.
3194
1629
 
3195
- ## 2.1.5 - 2026-08-19
3196
-
3197
- `local-build` was the one execution contract in the daily (non-handoff) flow that let the executor claim done off write evidence alone — and it is also the busiest lane a weaker `unic-code` backend hits. This closes that gap and adds a non-blocking second opinion, without adding wait time to the main task.
3198
-
3199
- ### Changed
3200
-
3201
- - **`local-build` now requires verification evidence, not just write evidence, before claiming done.** `orchestration.contracts['local-build'].completionRule` was `require-write`;
3202
-
3203
- ### Added
3204
-
3205
- - **Non-blocking sidecar diff review for `local-build` and `shared-edit`.** After write + verification evidence exist for one of these tasks, routed state now carries a `review=code-reviewer(diff)` segment (`routeSummary.postEditReview`) instructing the agent to launch `code-reviewer` in the background (`run_in_background: true`, `REVIEW_TARGET_TYPE=diff`, model `unic-smart` per the new `subagents.diffReviewModel`) — reusing the reviewer-model-differs-from-executor precedent from `handoff.reviewer`, since a background pass can afford a stronger model without slowing the main task down. Findings are advisory only; the main task's completion is never blocked or reopened on their account. New `code-reviewer.md` mode: `REVIEW_TARGET_TYPE=diff`, documented in `templates/.claude/agents/code-reviewer.md` (mirrored byte-identically to `.claude/agents/code-reviewer.md`) and wired into `templates/CLAUDE.md` / this repo's own `CLAUDE.md` under "Post-Edit Sidecar Review (internal)".
3206
- - **`subagents.diffReviewEnabled` / `diffReviewAgent` / `diffReviewModel`** — new config fields in both `.ukit/storage/config.json` and `templates/ukit/storage/config.json`, defaulting to `true` / `code-reviewer` / `unic-smart`.
3207
-
3208
- ## 2.1.4 - 2026-08-19
3209
-
3210
- More room before compaction, the handoff hooks stop taxing every call they were meant to speed up, and the shipped handoff instructions stop contradicting the config they tell agents to read.
3211
-
3212
- ### Changed
3213
-
3214
- - **`compact.hardCapTokens` 160,000 → 220,000 and `env.CLAUDE_CODE_AUTO_COMPACT_WINDOW` 150,000 → 180,000.** 2.1.3 fixed the deadlock but left the pair sized for a 200k window, which meant compacting far more often than necessary on a 256k model. The new pair leaves roughly 40k of working room after auto-compact fires, and the ordering invariant `autoCompactWindow < hardCapTokens` still holds — `tests/core/autoCompactWindow.test.js` fails if either number moves in isolation. **On a 200k model, lower `hardCapTokens` back to 160,000 or below**; the `_help` text in `config.json` says so, and the gate cannot protect you if the cap sits above your real context window.
3215
- - **Config-missing fallbacks follow the default**: `compact-threshold.mjs` and `context-window-guard.sh` now fall back to `220_000` rather than `160_000`, so a corrupt or absent `config.json` behaves like a fresh install instead of silently reverting to the old cap.
3216
-
3217
- ### Fixed
3218
-
3219
- - **The shipped handoff instructions no longer restate a config value that had gone stale.** Eight lines across `handoff-fullstack.md`, `handoff-implement.md`, `handoff-review.md` and `handoff-planner.md` told agents `handoff.maxParallelAgents` defaults to **10**, while `config.json` in the same release ships **12** — so an installed project got instructions that contradicted its own runtime config. Every one of those lines already said "read from `.ukit/storage/config.json`", so the restated number was redundant as well as wrong; it is now gone and the value has exactly one home. This was the second occurrence (the first was the `3 → 10` bump), and the cause both times was hand-copying a config value into prose. `tests/consistency/configDocsSync.test.js` now fails the suite if any doc restates a numeric `handoff.*` default that contradicts config, in English or Vietnamese, and if a `templates/.claude` file without `{{ }}` variables drifts from its active copy — the "keep the two mirrors identical" rule was written in two places but had never been enforced by anything except a maintainer running `diff` by hand.
3220
- - **The worktree early-exit guard no longer costs more than it saves.** `skill-router.sh` and `stale-spec-guard.sh` skip routing for tool calls scoped to a disposable `.worktrees/task-*` tree — but the first cut spawned `node -e` on every call to decide that, measured at 53ms → 124ms per call in the main tree, where the skip never applies. A pure-bash `case "$INPUT" in *".worktrees/"*)` pre-check now gates the node spawn; it is a strict superset of what the node guard can match, so the main tree pays nothing. Both hooks still fail **open** — any parse error, missing field or node failure falls through to the normal path.
3221
-
3222
- ### Added
3223
-
3224
- - **`.claude/ukit/index/provision-worktree.mjs`** — deterministic worktree provisioning for handoff waves, packaged via `manifests/platform.full.yaml`.
3225
- - **Test-selection policy in `docs/AI_HANDOFF/RULES.md`** — per-task related tests are the floor, and a full suite at the wave/cycle boundary is mandatory, not optional.
3226
- - **`scripts/bench/parallel-agents.mjs`** — harness for measuring concurrent test-process contention at several parallelism levels, recording `slowdownFactor` / `perRunCost` / a `recommended` value plus the load averages the run happened under. It measures test-process contention, not LLM agents.
3227
- - **`handoff.maxParallelAgents`: 10 → 12.** Chosen, not measured — the benchmark above was never run on a quiet enough machine, so this is the middle of the ~10-15 safe band the config's own `_help` has always documented. Lower it to 3-5 if your tasks produce long verification output or you see compaction firing repeatedly.
3228
-
3229
- ## 2.1.3 - 2026-08-16
3230
-
3231
- The reason auto-compact never fired in the terminal was UKit itself. This makes it fire.
3232
-
3233
- ### Fixed
3234
-
3235
- - **Auto-compact now triggers below the hard cap instead of never.** `context-hardcap-gate.sh` refuses Edit/Write/Bash at `compact.hardCapTokens` (160,000 — 80% of a 200k window), while Claude Code's own auto-compact fires near the real window limit. The gate froze the session first, so the transcript stopped growing, so the auto-compact threshold was never reached: a deadlock whose only exit was typing `/compact` by hand. Default settings now ship `env.CLAUDE_CODE_AUTO_COMPACT_WINDOW = 150000`, which lands 10,000 tokens *before* the gate — compaction happens on its own, the run keeps going, and the grace window added in 2.1.2 stays as the backstop rather than the normal path.
3236
- - **`autoCompactEnabled: true` is pinned in default settings**, so a stale toggle in `/config` cannot silently reinstate the deadlock.
3237
-
3238
- ### Added
3239
-
3240
- - **`tests/core/autoCompactWindow.test.js`** — locks the ordering invariant `env.CLAUDE_CODE_AUTO_COMPACT_WINDOW < compact.hardCapTokens`, the 100,000–1,000,000 range Claude Code accepts, `autoCompactEnabled`, template/mirror parity, and the `overwrite_with_backup` merge strategy that lets existing installs pick the fix up. Change either number in isolation and the suite fails instead of the deadlock returning silently.
3241
-
3242
- ### Notes
3243
-
3244
- - `env` in `settings.json` applies to **new sessions**. After `npm i -g @ngockhoale/ukit@latest && ukit install`, restart the session (or `/compact` once) before the change takes effect.
3245
- - Still true, and unchanged: no hook can invoke `/compact` — it is client-only. 2.1.3 does not call it; it moves the client's own threshold below UKit's gate so the client compacts on its own.
3246
-
3247
- ## 2.1.2 - 2026-08-16
3248
-
3249
- Follow-up to 2.1.0, which fixed the wrong hook. Runs were still freezing mid-task because the gate that actually blocks tools was never touched.
3250
-
3251
- ### Fixed
3252
-
3253
- - **`context-hardcap-gate.sh` gets a grace window for unfinished runs.** 2.1.0 made the *advisory* `context-window-guard.sh` (UserPromptSubmit) run-cursor aware, but the halt users hit came from `context-hardcap-gate.sh` — a separate PreToolUse hook that hard-refuses Edit/Write/Bash with `exit 2` once `estimatedTotalTokens >= compact.hardCapTokens`. It knew nothing about `docs/AI_HANDOFF/RUN.md`, so it froze runs mid-edit exactly as before 2.1.0. It now reads the run cursor and, while a run is unfinished, allows a bounded `compact.hardCapGraceCalls` (default 10) further calls with an explicit "spend this on landing, not new work" directive — finish the edit, commit, write the cursor, push — then blocks hard as it always did.
3254
-
3255
- ### Added
3256
-
3257
- - **`compact.hardCapGraceCalls`** (default `10`). Budget is per over-cap episode, not per wave:
3258
- - **`tests/hooks/contextHardcapGate.test.js`** — 12 cases covering under-cap pass-through, blocking with no run in flight, `Phase:
3259
-
3260
- ### Notes
3261
-
3262
- - **No hook can call `/compact`** — it is a client-only command, so UKit cannot auto-compact on your behalf.
3263
-
3264
- ## 2.1.0 - 2026-08-16
3265
-
3266
- Handoff autonomy wave: `/ukit:handoff-fullstack` runs a whole goal end-to-end without stopping to ask. Questions are collected once, up front, in the planning phase; everything that used to be a mid-run STOP now resolves automatically and keeps going.
3267
-
3268
- ### Added
3269
-
3270
- - **Autonomy Contract in all four handoff commands.** `handoff-create` owns the single question window — one batched `AskUserQuestion` (max 4, recommended option first) before planning starts, covering scope, conflicting interpretations, subsystem choice and acceptance criteria only. `handoff-fullstack`, `handoff-implement` and `handoff-review` ask nothing between that window and the Final Report; each command carries a table mapping every former STOP to its required automatic behavior.
3271
- - **Run cursor + resume protocol (`docs/AI_HANDOFF/RUN.md`).** Every phase transition writes `Phase`/`Cursor`/`Next`.
3272
- - **`handoff-resume.sh` SessionStart hook** (manifest id `hook-handoff-resume`). Reads the run cursor and prints a resume banner with Goal/Base/Phase/Cursor/Next, plus two extra lines when the session started from `source: compact`. Advisory only, always exits 0, silent when there is no unfinished run.
3273
- - **Auto-fix loop after review (max 2 rounds).** Non-approved tasks are re-waved and re-implemented in parallel — agents read their own `## Reviewer Verdict` from disk — then committed and re-reviewed.
3274
- - **Planner Grounding + 12-point Self-Audit.** `handoff-planner` must verify that every Target File exists (or is marked `(new)`), that every Verification Command is a real `package.json` script, and that test file paths match the neighbouring test layout; then run a 12-point self-audit (coverage / correctness / test quality, including "could every listed test pass against an empty implementation?") and report the result. Compensates for dropping plan review from 3 rounds to 2.
3275
- - **Wave-boundary commit + context checkpoint.** Each wave ends with `git add -A && git commit -m "handoff:
3276
-
3277
- ### Changed
3278
-
3279
- - **`git push` moved from the `ask` list to `allow`** in default settings, alongside `git add`, `git commit` and `git worktree`.
3280
- - **Subagent return contracts are now capped.** Executors return ≤10 lines (`TASK`/`STATUS`/`EXECUTOR_MODEL`/`FILES`/`RED`/`VERIFY`/`NOTE`), reviewers ≤6.
3281
- - **`context-window-guard.sh` is now run-cursor aware.** With an unfinished run it emits shed-context-and-continue instructions instead of the stop-and-`/compact` directive.
3282
- - **Same-wave file conflicts auto-serialize** instead of marking both tasks `needs_breakdown`:
3283
- - **A dirty working tree no longer blocks Phase 3.** It is committed as `handoff: checkpoint before implement` and the run continues.
3284
- - **Plan review loop cap: 3 rounds → 2**, then findings are applied and the run proceeds (logged as `### Round <N> — findings applied without re-review`). Config: `handoff.autonomy.planReviewRounds`.
3285
- - **Review diff range is now anchored to the plan commit** (`git log --grep='^handoff: plan' -n 1`) rather than the working tree, since waves are committed as they finish.
3286
- - **`handoff-planner` maximizes wave width.** `Dependencies: none` unless task B genuinely cannot be written without A's output — ordering preference, same code area and review order are explicitly not dependencies.
3287
- - **`feature-implementer` and `code-reviewer` run unattended in handoff mode.** Ambiguity resolves through task file → PLAN.md → surrounding code → recommended choice, recorded in `## Discussion`;
3288
- - **`handoff-model-guard.sh` gained a bash fast path** that skips the node spawn when the payload contains neither `AI_HANDOFF` nor `git push`.
3289
-
3290
- Entries for 1.0.0 through 2.0.7 are archived in the repository at `docs/archive/CHANGELOG-1.0.0-2.0.7.md` (not shipped in the npm package).
1630
+ 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).