@ngockhoale/ukit 3.4.75 → 3.4.76

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,17 @@
2
2
 
3
3
  All notable changes to UKit are documented here.
4
4
 
5
+ ## 3.4.76 - 2026-11-03
6
+
7
+ **P0 follow-up: UNKNOWN-stop marker store, explicit STOP publication and negation-aware state classification. Isolated process/replay evidence only; not live-host certification.**
8
+
9
+ - `ukit marker-store migrate`: plan by default; `--apply --writers-stopped` refuses unless the owner attests every OMP/bridge session is closed, no process uses the project, no writer temp file exists and the store is unchanged across an observation window. It never kills processes, keeps releases byte-for-byte, turns blocks into sticky releases under the same hashed names, quarantines (never deletes) the old store, and resumes after interruption.
10
+ - Bridge: a fenced or unavailable store fails open (`degraded:storage`) without crash or repeated calls; release-only saturation keeps every release.
11
+ - Explicit owner STOP survives pending route publication and never expires by TTL.
12
+ - Classifier: a negated verb ("do not stop the job") no longer mints a state-verification debt; `khong sua ledger/gate/receipts` stays READ_ONLY.
13
+ - Consumers: close related OMP/bridge sessions, `ukit update`, `ukit marker-store migrate`, then `--apply --writers-stopped`, verify, reopen. STOP stays in effect; legacy cursors are adopted only via explicit `--adopt-legacy-run`.
14
+ - Artifact budget: packed < 3,500,000 and unpacked < 11,300,000 bytes (limits unchanged). To stay under the unpacked limit, about 92 verbose bullets in historical entries (mostly older than 2.7) were shortened in this file, saving about 22 KB; no release was removed, and the full original text is in git history at 46b48d11.
15
+
5
16
  ## 3.4.75 - 2026-11-01
6
17
 
7
18
  - Publish receipts bind to artifact integrity.
@@ -2038,7 +2049,7 @@ pulls from npm, so an install on 2.3.19 (or older) needs an update to receive th
2038
2049
 
2039
2050
  C14 bug-fix release record — one correctness fix is shipped; this release adds no new features.
2040
2051
 
2041
- - **Completion gate no longer silently releases a reentrant stop.** `templates/.claude/ukit/runtime/execution-ledger.mjs` (`--evaluate-stop`) had a `stop_hook_active` valve: when Claude Code re-fired `Stop` after the gate had already blocked once, the valve emitted only a `systemMessage` with no `decision` while completion evidence was still missing, so the turn ended and the session idled until the human typed "tiếp". The valve is removed — a reentrant stop is now evaluated like any other stop, blocking again with the actionable missing-evidence reason (produce the evidence or report a blocker), and the loop stays bounded by the existing visible continuation cap and the verification-loop blocker, so a finished task is never trapped.
2052
+ - **Completion gate no longer silently releases a reentrant stop.** `templates/.claude/ukit/runtime/execution-ledger.mjs` (`--evaluate-stop`) had a `stop_hook_active` valve:
2042
2053
 
2043
2054
  ## 2.3.18 - 2026-09-12
2044
2055
 
@@ -3068,7 +3079,7 @@ Follow-up to the user's report that UKit had become too heavy-handed: too many h
3068
3079
  ### Changed
3069
3080
 
3070
3081
  - **`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.
3071
- - **`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; it no longer re-evaluates on every read-only tool call. Traded away: skill-router no longer sees "which files were Read/Grep'd" as mid-task evidence — only the original prompt and Edit/Write targets.
3082
+ - **`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;
3072
3083
 
3073
3084
  ### Fixed
3074
3085
 
@@ -3086,7 +3097,7 @@ Follow-up to 2.2.3's hook-chain collapse: a real omp session on a CloudMounter/F
3086
3097
  ### Fixed
3087
3098
 
3088
3099
  - **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`.
3089
- - **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. Ordinary shell commands and read-only tools now fail open (with a logged warning), so a runner-level hiccup can no longer brick command execution or diagnosis tools.
3100
+ - **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.
3090
3101
  - **`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.
3091
3102
 
3092
3103
  ### Added
@@ -3099,17 +3110,17 @@ Sessions were stalling mid-task — the model would read source, then simply sto
3099
3110
 
3100
3111
  ### Fixed
3101
3112
 
3102
- - **Silent stalls were unenforceable, because nothing measured them.** A stop after a read-only pass was indistinguishable from a stop after finished work: both were just the model ending its turn. UKit now keeps a session-scoped execution ledger (`.ukit/storage/cache/exec-ledger/<session>.json`) recording source reads, write attempts and outcomes, and verification commands with their exit codes. A new `Stop` hook (`completion-gate.sh`, and omp's `session_stop`) reads it against the routed contract's `completionEvidence` and blocks a premature stop with the specific missing evidence and a recovery instruction matched to the actual state — no source yet, failed write, no write, failed verification, or no verification each get different guidance. Recovery is capped at 6 continuations, then degrades to a warning, so the gate can never loop.
3113
+ - **Silent stalls were unenforceable, because nothing measured them.** A stop after a read-only pass was indistinguishable from a stop after finished work:
3103
3114
  - **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.
3104
- - **omp writes bypassed the safety gates entirely.** omp's `normalizeToolEventInput` emits `path` / `paths`; every UKit hook script reads `file_path`. So `protect-files.sh` and `stale-spec-guard.sh` saw no target on an omp edit and waved it through. The bridge now normalizes `path` / `paths[0]` → `file_path` at the host boundary, without mutating the caller's event.
3115
+ - **omp writes bypassed the safety gates entirely.** omp's `normalizeToolEventInput` emits `path` / `paths`;
3105
3116
  - **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.
3106
- - **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])`. Under macOS `/tmp` → `/private/tmp`, or any symlinked work directory, those differ — so `--record` and `--evaluate-stop` returned exit 0 having done nothing: no receipts, no gate. The whole unit suite stayed green; only a scratch install under `/tmp` exposed it. Both paths are now compared by realpath, covered by `tests/hooks/executionLedgerCli.test.js`.
3107
- - **`.omp/config.yml` documented the model aliases backwards**, calling the UNIC names "LITERAL model names, not aliases". They are stable provider-neutral aliases whose hidden backends change during development — which is precisely why orchestration must not branch on vendor names.
3117
+ - **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])`.
3118
+ - **`.omp/config.yml` documented the model aliases backwards**, calling the UNIC names "LITERAL model names, not aliases".
3108
3119
 
3109
3120
  ### Added
3110
3121
 
3111
- - **`tests/hooks/executionLedgerCli.test.js`** (4 tests) — drives the real CLI through a symlinked root: receipts get written, a premature stop is blocked, a stop with write + passing verification is allowed, and the continuation cap engages at exactly 6. Verified RED against the pre-fix guard (3 of 4 fail).
3112
- - **Manifest entries and dev-mirror parity for the four new files** — `record-execution.sh`, `completion-gate.sh`, `execution-ledger.mjs`, `hook-chain-runner.mjs`. `templates/.claude/` is gitignored and existing template files were force-added, so new ones are invisible to both git and `npm pack` unless added the same way; verified present in the packed tarball, with hook scripts executable after a real `ukit install`.
3122
+ - **`tests/hooks/executionLedgerCli.test.js`** (4 tests) — drives the real CLI through a symlinked root:
3123
+ - **Manifest entries and dev-mirror parity for the four new files** — `record-execution.sh`, `completion-gate.sh`, `execution-ledger.mjs`, `hook-chain-runner.mjs`.
3113
3124
 
3114
3125
  ## 2.2.2 - 2026-08-22
3115
3126
 
@@ -3119,20 +3130,20 @@ It also settles the three `TODO(verify)` items 2.2.1 shipped with. Those were pl
3119
3130
 
3120
3131
  ### Fixed
3121
3132
 
3122
- - **Auto-compact was never actually configured on omp.** `.omp/config.yml` set `compact.autoCompactWindow: 180000`, a key omp does not have — `omp config get compact.autoCompactWindow` answers "Unknown setting", so the value was inert and omp stayed on its own default. The real key is `compaction.thresholdTokens` ("Fixed token limit for context maintenance; overrides percentage if set", omp's default `-1`). Verified end-to-end against a scratch project: the nested form now reads back as `180000`, which is below `compact.hardCapTokens` (220000) as intended, so auto-compact fires before `context-hardcap-gate.sh` starts blocking tool calls.
3123
- - **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: "compact"`. It does not — it has a dedicated event instead (`session_before_compact` → `session.compacting` → `session_compact`, the last firing once compaction settles). So on omp the entire post-compact chain was lost: the run cursor stayed un-surfaced, compact pressure was never reset, and a mid-cycle handoff silently failed to resume after a compaction. `ukit-bridge.js` now maps `session_compact` onto the same script chain, keeping `hook_event_name: 'SessionStart'` in the payload so the scripts stay shared with Claude Code rather than forked.
3124
- - **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`. Neither exists: omp's anthropic provider reads `ANTHROPIC_BASE_URL` (falling back to `https://api.anthropic.com`), and its settings schema declares no `baseUrl` at any level. Both probes are removed rather than left returning a permanent `false` — a probe that can never fire is worse than no probe, because it reads as coverage. Detection is unchanged in behaviour and now literally matches what the docs already claimed: routing is decided only by `ANTHROPIC_BASE_URL`, on omp for the same reason as on Claude Code.
3133
+ - **Auto-compact was never actually configured on omp.** `.omp/config.yml` set `compact.autoCompactWindow:
3134
+ - **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:
3135
+ - **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`.
3125
3136
  - **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.
3126
3137
  - **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.
3127
- - **Every session opened by being told to resume a finished cycle.** `docs/AI_HANDOFF/RUN.md` was left at `Phase: R4` after 2.2.1 shipped, so `handoff-resume.sh` — which runs in the `session_start` chain of *both* Claude Code and the omp bridge — fired a "CONTINUATION — resume immediately" banner at the start of every new, unrelated session. The cursor now reads `Phase: done`.
3128
- - **`/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); the other six were *references* that expanded to the entire paragraph again mid-sentence. They now say "the **Problem / feature** section above".
3129
- - **Eight fallback lines told the model to do something only a human can do.** `> Other tools without subagent support: manually switch to the strong model` reads, to a running model, as an instruction to itself — which it cannot follow, so it improvises. Each is now explicitly addressed: `> **For the human operator, on a tool with no agent support (Codex, OpenCode) — not an instruction to the model:**`.
3138
+ - **Every session opened by being told to resume a finished cycle.** `docs/AI_HANDOFF/RUN.md` was left at `Phase:
3139
+ - **`/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);
3140
+ - **Eight fallback lines told the model to do something only a human can do.** `> Other tools without subagent support:
3130
3141
 
3131
3142
  ### Added
3132
3143
 
3133
- - **`### How a tier is actually bound`** in both context docs. The main session model never changes mid-turn; a tier only takes effect when work is handed to an agent whose own definition binds that model. The section carries a harness table (Claude Code `.claude/agents/*.md` + `subagent_type`, omp `.omp/agents/*.md` + `task-agent`) and states the consequence plainly: doing everything inline is exactly what makes UKit behave as if it had one model.
3144
+ - **`### How a tier is actually bound`** in both context docs. The main session model never changes mid-turn;
3134
3145
  - **`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.
3135
- - **`.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. New: `Classify first, then act` (Trivial / Simple / Non-trivial lanes, decided *before* the first tool call), `Auto-activate skills`, and `Delegate to bind a model tier`. It stays short on purpose: it is re-attached near every turn.
3146
+ - **`.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.
3136
3147
  - **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`.
3137
3148
 
3138
3149
  ### Changed
@@ -3146,27 +3157,27 @@ UKit gains a fourth runtime and loses one. omp (Oh My Pi) reaches full parity wi
3146
3157
 
3147
3158
  ### Added
3148
3159
 
3149
- - **omp (Oh My Pi) adapter — `ukit install --tools=omp`** (alias `--tools=oh-my-pi`). Installs 11 files: `.omp/AGENTS.md` (a thin `@../AGENTS.md` import rather than a copy, so the shared instructions have exactly one home), `.omp/RULES.md` (sticky hard rules), `.omp/config.yml`, `.omp/README.md`, `.omp/hooks/pre/ukit-bridge.js`, and the six agents under `.omp/agents/`. **No symlinks are created.** omp's discovery providers already rank its `claude` provider above nothing at all for skills and commands, so `.claude/skills/` and `.claude/commands/` are read directly — an `.omp/skills` symlink would shadow the canonical tree for no benefit. `.omp/agents/` must be real files because omp explicitly skips `.claude/agents/*.md`.
3150
- - **All six shared agents ported to omp's task-agent contract**: `bug-debugger`, `code-reviewer`, `feature-implementer`, `handoff-planner`, `ukit-small-task-maintainer`, `ukit-vision-analyst`. The differences between each agent's Claude Code and omp form — and why each one is or is not a faithful port — are recorded in [`docs/research/2026-08-22_omp-agent-parity.md`](docs/research/2026-08-22_omp-agent-parity.md).
3151
- - **UNIC model names survive the port.** `.omp/config.yml` ships `modelRoles` with all four lanes intact: `lite: unic-lite`, `code: unic-code`, `smart: unic-smart`, `vision: unic-vision`. The vision lane stays a capability lane, not a fourth cost tier.
3160
+ - **omp (Oh My Pi) adapter — `ukit install --tools=omp`** (alias `--tools=oh-my-pi`).
3161
+ - **All six shared agents ported to omp's task-agent contract**: `bug-debugger`, `code-reviewer`, `feature-implementer`, `handoff-planner`, `ukit-small-task-maintainer`, `ukit-vision-analyst`.
3162
+ - **UNIC model names survive the port.** `.omp/config.yml` ships `modelRoles` with all four lanes intact:
3152
3163
  - **Hook bridge — one source of truth, two runtimes.** `.omp/hooks/pre/ukit-bridge.js` is an omp hook factory (`export default function hook(pi)`) that translates omp's events into the Claude Code hook JSON shape and then executes the **existing** `.claude/hooks/*.sh` scripts. The 20 shell hooks are not duplicated, forked, or rewritten for omp; a fix to one fixes both runtimes.
3153
- - **Auto-compact parity.** `compact.agentContext.targets` gains an `omp` entry using `mode: 'precompact-reinject'` — the same strategy as `claude`, not Codex's `soft-handoff`. omp exposes real pre-compaction hook events, so there is nothing to work around with a state file.
3154
- - **`agent-code-reviewer` manifest item.** `templates/.claude/agents/code-reviewer.md` had shipped as a template with no manifest item since it was introduced, and `autoDiscoverTemplates: false` meant it was therefore **silently never installed** — UKit was installing five of its six Claude agents. Both the handoff Phase 4 reviewer and the Post-Edit Sidecar Review added in 2.1.5 instruct the model to spawn an agent that was not present in any installed project. Found by the omp parity work, because the new adapter would otherwise have shipped a strictly better agent set than the one it was porting from.
3164
+ - **Auto-compact parity.** `compact.agentContext.targets` gains an `omp` entry using `mode:
3165
+ - **`agent-code-reviewer` manifest item.** `templates/.claude/agents/code-reviewer.md` had shipped as a template with no manifest item since it was introduced, and `autoDiscoverTemplates:
3155
3166
 
3156
3167
  ### Changed
3157
3168
 
3158
- - **`/ukit:*` commands are phrased for whichever runtime is reading them.** The command bodies no longer assume Claude Code's spawn mechanics; each names its model tier and its delegation step in runtime-neutral terms, so the same file drives the same pipeline under Claude Code and under omp.
3169
+ - **`/ukit:*` commands are phrased for whichever runtime is reading them.** The command bodies no longer assume Claude Code's spawn mechanics;
3159
3170
  - **`ukit status` reports `Oh My Pi (omp)`** and checks `.omp/config.yml`; the Antigravity row is gone.
3160
3171
  - **`.omp/` is TCC-protected** (`applyPlan.js`) and **git-ignored** by the managed `.gitignore` block, alongside `.claude/` and `.codex/`.
3161
3172
 
3162
3173
  ### Removed
3163
3174
 
3164
3175
  - **The Antigravity adapter.** `templates/.antigravity/`, `templates/adapter-presets/antigravity/`, the five `multi-antigravity-*` manifest items, its entry in `src/cli/adapters.js`, and every user-facing mention — in `README.md`, `QUICK_START.md`, `docs/PROJECT.md`, and in the installed workspace itself: `AGENTS.md`, `.codex/README.md` and the four `/ukit:handoff-*` command files all named Antigravity as a tool you could use. `--tools=antigravity` now fails fast with `Antigravity has been removed as a UKit adapter.` plus the list of adapters that do exist, rather than silently installing nothing.
3165
- - **Legacy cleanup is retained, not removed.** `ukit uninstall` still cleans `.antigravity/`, and `.antigravity/` keeps its TCC protection, because a stale pre-2.2.0 install still has the directory. Install-time pruning now covers it too: `.antigravity/` joined `AUTO_PRUNE_OBSOLETE_PREFIXES`, so a re-install removes the stale symlinks a pre-2.2.0 install left behind. Without it those links would dangle forever — pruning is the only pass that ever revisits them, and removing the adapter took them out of the manifest that uninstall reads. Only paths UKit itself recorded in `install.json` are considered, and a path the user has replaced with a real directory is skipped with a warning instead of being silently left behind.
3176
+ - **Legacy cleanup is retained, not removed.** `ukit uninstall` still cleans `.antigravity/`, and `.antigravity/` keeps its TCC protection, because a stale pre-2.2.0 install still has the directory.
3166
3177
 
3167
3178
  ### Fixed
3168
3179
 
3169
- - **Deselecting omp no longer orphans its agents.** `OPTIONAL_ADAPTERS`' `managedPaths` listed `.omp/agents` as a single entry, copying the shape of Codex's `.codex/agents`. Codex's is a symlink; omp's is a real directory of six real files. `removeFileOrLinkOnly` refuses real directories, so re-running `ukit install` without `omp` and confirming removal deleted nothing — while the metadata pass still dropped all six from `install.json`, leaving them on disk and untracked forever. The six paths are now listed individually, matching `uninstall.js`'s own list. Full `ukit uninstall` was never affected.
3180
+ - **Deselecting omp no longer orphans its agents.** `OPTIONAL_ADAPTERS`' `managedPaths` listed `.omp/agents` as a single entry, copying the shape of Codex's `.codex/agents`.
3170
3181
  - **The `--tools=antigravity` regression test was passing vacuously.** It asserted on a directory the install pipeline had never been pointed at, so the "no partial write" half would have held even if the error path did write. It now runs the real `bin/ukit`, and checks the exit code, the stderr text, the absence of a stack frame, and that not even the always-on `.claude/` adapter was written.
3171
3182
 
3172
3183
  **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`.
@@ -3177,7 +3188,7 @@ UKit gains a fourth runtime and loses one. omp (Oh My Pi) reaches full parity wi
3177
3188
 
3178
3189
  ### Changed
3179
3190
 
3180
- - **`local-build` now requires verification evidence, not just write evidence, before claiming done.** `orchestration.contracts['local-build'].completionRule` was `require-write`; every other multi-step contract (`shared-edit`, `find-cause`, `map-impact`) already required verification too, so `local-build` was the odd one out — the exact lane where a weaker executor model producing "silly bugs" that pass a glance but fail a real check would go unnoticed. `completionEvidence` now includes `verification-evidence` alongside `write-evidence` in `src/index/taskRouting.js`, mirrored in `src/core/runtimeConfig.js` and both `config.json` copies. `tests/index/taskRouting.test.js` and `tests/core/runtimeConfig.test.js` lock the new requirement.
3191
+ - **`local-build` now requires verification evidence, not just write evidence, before claiming done.** `orchestration.contracts['local-build'].completionRule` was `require-write`;
3181
3192
 
3182
3193
  ### Added
3183
3194
 
@@ -3200,8 +3211,8 @@ More room before compaction, the handoff hooks stop taxing every call they were
3200
3211
 
3201
3212
  ### Added
3202
3213
 
3203
- - **`.claude/ukit/index/provision-worktree.mjs`** — deterministic worktree provisioning for handoff waves, packaged via `manifests/platform.full.yaml`. It hides the worktree's `node_modules` symlink through the worktree's own `.git/info/exclude` (a symlink never matched `.gitignore`'s `node_modules/`, so an orchestrator `git add -A` would have committed a machine-local absolute path), and skips git-tracked files when copying `.claude/` so it cannot clobber `.claude/commands/ukit/handoff-fullstack.md`. **Shipped but not yet wired into `handoff-implement`** — the wiring is queued for a later release.
3204
- - **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. This is the compensating net that makes narrowed per-task scope safe; the agent definitions already cited it before it existed.
3214
+ - **`.claude/ukit/index/provision-worktree.mjs`** — deterministic worktree provisioning for handoff waves, packaged via `manifests/platform.full.yaml`.
3215
+ - **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.
3205
3216
  - **`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.
3206
3217
  - **`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.
3207
3218
 
@@ -3233,12 +3244,12 @@ Follow-up to 2.1.0, which fixed the wrong hook. Runs were still freezing mid-tas
3233
3244
 
3234
3245
  ### Added
3235
3246
 
3236
- - **`compact.hardCapGraceCalls`** (default `10`). Budget is per over-cap episode, not per wave: it resets only when the token estimate actually falls (a real compaction happened), so a long run cannot mint itself unlimited grace by advancing its cursor. With no unfinished run the gate's behavior is unchanged.
3237
- - **`tests/hooks/contextHardcapGate.test.js`** — 12 cases covering under-cap pass-through, blocking with no run in flight, `Phase: done` treated as no run, grace grant/exhaustion, no top-up on cursor advance, budget restored after a real compaction, `hardCapBlock=false` escape hatch, non-gated tools, fail-open on malformed input, template/mirror parity, and manifest+settings wiring.
3247
+ - **`compact.hardCapGraceCalls`** (default `10`). Budget is per over-cap episode, not per wave:
3248
+ - **`tests/hooks/contextHardcapGate.test.js`** — 12 cases covering under-cap pass-through, blocking with no run in flight, `Phase:
3238
3249
 
3239
3250
  ### Notes
3240
3251
 
3241
- - **No hook can call `/compact`** — it is a client-only command, so UKit cannot auto-compact on your behalf. The supported path is: land inside the grace window → user runs `/compact` (or Claude Code's own auto-compact fires) → the `handoff-resume.sh` SessionStart hook replays the cursor → the run continues. Enabling auto-compact in Claude Code's `/config` makes that middle step automatic.
3252
+ - **No hook can call `/compact`** — it is a client-only command, so UKit cannot auto-compact on your behalf.
3242
3253
 
3243
3254
  ## 2.1.0 - 2026-08-16
3244
3255
 
@@ -3247,39 +3258,39 @@ Handoff autonomy wave: `/ukit:handoff-fullstack` runs a whole goal end-to-end wi
3247
3258
  ### Added
3248
3259
 
3249
3260
  - **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.
3250
- - **Run cursor + resume protocol (`docs/AI_HANDOFF/RUN.md`).** Every phase transition writes `Phase`/`Cursor`/`Next`. A `Phase:` other than `done` means the next session is a continuation: no re-plan, no re-scope, no questions. New config `handoff.autonomy.resumeFromCursor` / `runCursorFile`.
3261
+ - **Run cursor + resume protocol (`docs/AI_HANDOFF/RUN.md`).** Every phase transition writes `Phase`/`Cursor`/`Next`.
3251
3262
  - **`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.
3252
- - **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. After round 2 the stuck tasks stay `blocked` and the rest of the pipeline proceeds instead of halting. Config: `handoff.autonomy.autoFixRounds`.
3263
+ - **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.
3253
3264
  - **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.
3254
- - **Wave-boundary commit + context checkpoint.** Each wave ends with `git add -A && git commit -m "handoff: wave <N> — TASK-00x, ..."`, a cursor update, and a collapse of that wave to one line per task in working memory. Config: `handoff.autonomy.commitPerWave`.
3265
+ - **Wave-boundary commit + context checkpoint.** Each wave ends with `git add -A && git commit -m "handoff:
3255
3266
 
3256
3267
  ### Changed
3257
3268
 
3258
- - **`git push` moved from the `ask` list to `allow`** in default settings, alongside `git add`, `git commit` and `git worktree`. Runs no longer stop at the final step for a confirmation. `git push --force` and `--force-with-lease` remain in `deny`, which still wins over `allow`.
3259
- - **Subagent return contracts are now capped.** Executors return ≤10 lines (`TASK`/`STATUS`/`EXECUTOR_MODEL`/`FILES`/`RED`/`VERIFY`/`NOTE`), reviewers ≤6. Verbose agent reports injected back into the orchestrator were the main cause of context exhaustion on long fullstack runs; this addresses it structurally rather than by raising caps.
3260
- - **`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. Asking the user to `/compact` is permitted only at a cycle boundary, in the Final Report — never mid-task. Config: `handoff.autonomy.compactAtCycleBoundaryOnly`.
3261
- - **Same-wave file conflicts auto-serialize** instead of marking both tasks `needs_breakdown`: the higher-numbered task gains a `Dependencies: TASK-<lower>` line and moves to the next wave. Config: `handoff.autonomy.autoSerializeFileConflicts`.
3269
+ - **`git push` moved from the `ask` list to `allow`** in default settings, alongside `git add`, `git commit` and `git worktree`.
3270
+ - **Subagent return contracts are now capped.** Executors return ≤10 lines (`TASK`/`STATUS`/`EXECUTOR_MODEL`/`FILES`/`RED`/`VERIFY`/`NOTE`), reviewers ≤6.
3271
+ - **`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.
3272
+ - **Same-wave file conflicts auto-serialize** instead of marking both tasks `needs_breakdown`:
3262
3273
  - **A dirty working tree no longer blocks Phase 3.** It is committed as `handoff: checkpoint before implement` and the run continues.
3263
3274
  - **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`.
3264
3275
  - **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.
3265
3276
  - **`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.
3266
- - **`feature-implementer` and `code-reviewer` run unattended in handoff mode.** Ambiguity resolves through task file → PLAN.md → surrounding code → recommended choice, recorded in `## Discussion`; reviewer findings must be actionable defects (`file:line` + concrete failure + what correct looks like), never questions. Daily (non-handoff) behavior is unchanged.
3267
- - **`handoff-model-guard.sh` gained a bash fast path** that skips the node spawn when the payload contains neither `AI_HANDOFF` nor `git push`. Behavior-identical (verified against the previous version across a 6-payload sweep); measured 67ms → 38ms per ordinary Bash/Edit/Write call, paid on every call in every parallel subagent.
3277
+ - **`feature-implementer` and `code-reviewer` run unattended in handoff mode.** Ambiguity resolves through task file → PLAN.md → surrounding code → recommended choice, recorded in `## Discussion`;
3278
+ - **`handoff-model-guard.sh` gained a bash fast path** that skips the node spawn when the payload contains neither `AI_HANDOFF` nor `git push`.
3268
3279
 
3269
3280
  ## 2.0.7 - 2026-08-15
3270
3281
 
3271
3282
  ### Added
3272
3283
 
3273
3284
  - **`/ukit:handoff-create` and `/ukit:handoff-fullstack` gain a P2.5 independent plan review gate.** After the planner writes `PLAN.md` and before it's committed, a separate `code-reviewer` agent invocation (`REVIEW_TARGET_TYPE=plan`, fresh context — not the planner reviewing its own work) checks Completeness/Consistency/Clarity/Scope/YAGNI. `Issues Found` routes back to the planner to revise and resubmit; `Approved` unlocks the commit. Each round is logged to PLAN.md's new `## Plan Review Log` section, and the loop is capped at 3 `Issues Found` rounds — past that it escalates to the human instead of looping indefinitely.
3274
- - **Same-wave file-conflict precheck in Phase 3.** Before spawning any implementation wave, `handoff-implement.md`/`handoff-fullstack.md` now compare `Target Files` across every task in that wave; any overlap stops the wave and marks both tasks `needs_breakdown` instead of risking a mid-wave merge conflict. Code-level backstop for the planner's existing "no shared files in one wave" scope constraint.
3285
+ - **Same-wave file-conflict precheck in Phase 3.** Before spawning any implementation wave, `handoff-implement.md`/`handoff-fullstack.md` now compare `Target Files` across every task in that wave;
3275
3286
  - **TDD RED-state now requires real evidence.** The Executor Report template adds a mandatory `RED_OUTPUT` field — the actual failing-test output pasted before implementation, not a bare "confirmed" claim. `code-reviewer` checks this field during Test Plan adherence review and requests changes if it's missing or vague.
3276
- - **`handoff.plan.requireLintOrTypecheckInVerification`** (default `true`): when the project has a lint/typecheck script, task Verification Commands must run it, not just tests; the planner must state an explicit N/A if the project has none. Enforced by `code-reviewer` as review-order step 0.
3287
+ - **`handoff.plan.requireLintOrTypecheckInVerification`** (default `true`): when the project has a lint/typecheck script, task Verification Commands must run it, not just tests;
3277
3288
 
3278
3289
  ### Changed
3279
3290
 
3280
3291
  - **`handoff.maxParallelAgents`**: 3 → 10, raising the default cap on concurrent background agents per wave (config comments still warn against exceeding ~10-15 — each agent's report gets injected back into the orchestrator's own context on completion).
3281
3292
  - **Phase 4 (Review) is now parallelized**, batched by `maxParallelAgents` the same way Phase 3 (Implement) already was — reviewer agents only read a diff and append a verdict to their own task file, so parallel review carries none of Phase 3's shared-worktree conflict risk.
3282
- - **`handoff.plan.minTestsEdgeCase`**: 1 → 2, and the two edge cases must now be of different kinds (e.g. null/empty **and** boundary/concurrent) — two near-duplicate cases no longer satisfy the requirement. Wired through `handoff-planner`, `code-reviewer`, `feature-implementer`'s inline-test-plan fallback, `RULES.md`, and both handoff pipeline commands.
3293
+ - **`handoff.plan.minTestsEdgeCase`**: 1 → 2, and the two edge cases must now be of different kinds (e.g.
3283
3294
 
3284
3295
  ## 2.0.6 - 2026-08-12
3285
3296
 
@@ -3297,9 +3308,9 @@ Handoff autonomy wave: `/ukit:handoff-fullstack` runs a whole goal end-to-end wi
3297
3308
 
3298
3309
  ### Added
3299
3310
 
3300
- - **`context-window-guard.sh`** (UserPromptSubmit) — measures the session's real context by reading the transcript, and warns at 80% of `compact.hardCapTokens` / raises an ALERT at 100%. It counts only the messages *after* the last `compact_boundary`, so it tracks live context rather than the file's lifetime size (on a real 5.8 MB transcript: 1,444,439 tokens whole-file vs 145,510 measured — the whole-file number is off by 10x and useless). Subagent entries (`isSidechain`) are counted separately, since each carries its own window. **Advisory only — it always exits 0.** A hook that blocked here would strand the user at exactly the moment they can no longer type their way out.
3301
- - **`handoff.maxParallelAgents`** (default `3`) — caps how many implementer agents a handoff wave spawns at once. `handoff-implement` and `handoff-fullstack` now batch each wave against it instead of launching every independent task simultaneously.
3302
- - **`ukit update` now refreshes the current project**, replacing the `ukit update && ukit install` two-step. `--no-install` keeps the old CLI-only behaviour. The refresh is spawned as a **child process** running the newly installed global `bin/ukit`: after `npm install -g`, the running process still holds the old module graph, so an in-process install would redeploy the *old* templates and silently defeat the update. It also refuses to scaffold a directory with no UKit markers (install writes `.claude/`, `CLAUDE.md` and edits `.gitignore` — an unwelcome surprise in a home directory), and never reports an install that did not actually happen.
3311
+ - **`context-window-guard.sh`** (UserPromptSubmit) — measures the session's real context by reading the transcript, and warns at 80% of `compact.hardCapTokens` / raises an ALERT at 100%.
3312
+ - **`handoff.maxParallelAgents`** (default `3`) — caps how many implementer agents a handoff wave spawns at once.
3313
+ - **`ukit update` now refreshes the current project**, replacing the `ukit update && ukit install` two-step.
3303
3314
 
3304
3315
  ### Changed
3305
3316
 
@@ -3311,30 +3322,30 @@ Handoff autonomy wave: `/ukit:handoff-fullstack` runs a whole goal end-to-end wi
3311
3322
 
3312
3323
  - **One pasted screenshot could brick `Edit`/`Write` for an entire session on every non-UNIC project.** The vision gate hard-blocks edits until a `ukit-vision-analyst` receipt exists, and it accepted a receipt only if the reported model matched a hardcoded, by-then-stale model ID. That acceptance path is unsatisfiable in practice: an honest agent reports the model it *actually* ran on, so the gate could never be cleared and the only escape was deleting a gitignored marker file by hand. The gate now stands down entirely when the session is off the UNIC gateway — where Claude reads images natively and there is nothing to enforce — and matches `unic-vision` by capability instead of by a pinned version string. Detection failure (`null`) still enforces, so breaking one gitignored file is not a bypass. `tests/handoff/cycle4/vision-gate.test.mjs` gains cases 21b/21c pinning "off-gateway + no receipt is allowed, never a deadlock" and "no fallback model needs to be configured"; the UNIC enforcement cases are untouched and still pass.
3313
3324
  - **The v2.0.2 hard cap could not stop what it was built to stop.** `context-hardcap-gate.sh` is `PreToolUse`, but a context-window rejection happens when the request is *sent* — before any tool call exists to gate. `UserPromptSubmit` is the only event that runs early enough, hence the new guard above. Related: only three modules ever advance `estimatedTotalTokens`, and none of them observe `Read` results, images, or returned subagent reports, so the tracked figure drifts far below reality on exactly the sessions that overflow.
3314
- - **UKit's index could not see what UKit ships — the root cause of three releases' worth of dead features.** Because `src`, `tests` and `manifests` all exist in this repo, `templates/` was never scanned: 0 of 303 shipped files indexed, while the hand-maintained `.claude/` dev mirror sat in plain view. CLAUDE.md mandates an index-first loop, so the AI was routed to `src/` and the mirror, and never learned that `templates/.claude/` is the copy that reaches users. Querying a shipped skill by its own name returned only `src/` files, with no signal that anything was out of scope. Coverage in this repo goes from 136 files to 442, including the 185 `templates/.claude` files and all 17 shipped hooks; the three assets behind the 2.0.0 and 2.0.2 bugs now rank first for their own names.
3325
+ - **UKit's index could not see what UKit ships — the root cause of three releases' worth of dead features.** Because `src`, `tests` and `manifests` all exist in this repo, `templates/` was never scanned:
3315
3326
  - `tests/index/scanScope.test.js` guards the class: code outside the old allowlist is indexed even when a listed directory exists, ignore rules define scope, the non-git fallback still covers the whole project, and the shipped `index-core.mjs` bundle must carry the same discovery logic as `src/` — that bundle is what installed projects actually run, so a fix landing only in `src/` reaches nobody.
3316
3327
 
3317
3328
  ## 2.0.3 - 2026-08-11
3318
3329
 
3319
3330
  ### Added
3320
3331
 
3321
- - **`ukit memory propose "<text>" [--category <name>] [--project <id>]`** — the missing first step of the Project Pattern Learning loop. Wires the existing `proposePatternCandidate()` to the CLI so a candidate can actually be created; duplicate proposals of the same text return the existing pending entry instead of stacking.
3332
+ - **`ukit memory propose "<text>" [--category <name>] [--project <id>]`** — the missing first step of the Project Pattern Learning loop.
3322
3333
 
3323
3334
  ### Fixed
3324
3335
 
3325
- - **Project Pattern Learning was unreachable in every real install.** v2.0.0 shipped `ukit memory list --pending` / `approve` / `reject`, but nothing could create a candidate: `proposePatternCandidate()` had zero production callers, and the `project-learning` skill told the AI to import it from `src/core/memory/store.js` — a path that only exists inside the UKit repo, never in an installed project. The skill now points at the new CLI subcommand, and `tests/cli/memoryCommand.test.js` drives the loop through the CLI only, so a fix that works solely via a direct function import cannot make those tests pass.
3336
+ - **Project Pattern Learning was unreachable in every real install.** v2.0.0 shipped `ukit memory list --pending` / `approve` / `reject`, but nothing could create a candidate:
3326
3337
  - **The v2.0.0 handoff Interfaces block never shipped.** `Consumes`/`Produces` were added to the repo's own `docs/AI_HANDOFF/RULES.md` and `tasks/_TEMPLATE.md` but not to the `templates/docs/AI_HANDOFF/` copies that `ukit install` actually delivers, so installed projects got handoff docs without the feature the 2.0.0 changelog claims. Same dev-mirror divergence class as the 2.0.2 hard-cap hooks.
3327
3338
 
3328
3339
  ## 2.0.2 - 2026-08-11
3329
3340
 
3330
3341
  ### Added
3331
3342
 
3332
- - **Absolute context hard cap** — new `compact.hardCapTokens` (default `220000`) and `compact.hardCapBlock` (default `true`). Crossing the cap makes `context-hardcap-gate.sh` refuse `Edit`/`Write`/`Bash` outright until real compaction happens, instead of only printing a suggestion. `Read`/`Grep`/`Glob` stay open so the agent can still explain the block — only a human can invoke compaction. This is a new, separate ceiling: the existing soft/hard advisory phases (`compact.tokenThreshold` 50k, derived hard 80k) are unchanged.
3343
+ - **Absolute context hard cap** — new `compact.hardCapTokens` (default `220000`) and `compact.hardCapBlock` (default `true`).
3333
3344
  - **`reset-compact-pressure.sh`** (SessionStart) — zeroes the compact pressure tracker at session start, so the cap measures the current session rather than accumulating over a project's lifetime.
3334
3345
 
3335
3346
  ### Fixed
3336
3347
 
3337
- - **The hard cap would have shipped dead.** Both new hooks were wired into `settings.json` but had no entry in `manifests/platform.full.yaml`, so `ukit install` never copied them: real installs got `settings.json` pointing at scripts that do not exist. Found by a scratch-project install, not by the test suite. Added a `tests/manifest/settingsHookCoverage.test.js` regression guard that fails whenever a hook is wired without a manifest entry, or a manifest hook's `sourceTemplate` is missing, or the dev mirror and template `settings.json` disagree.
3348
+ - **The hard cap would have shipped dead.** Both new hooks were wired into `settings.json` but had no entry in `manifests/platform.full.yaml`, so `ukit install` never copied them:
3338
3349
  - **Permanent-block deadlock.** `compact-pressure.json` accumulated forever, so the cap would eventually block `Edit`/`Write`/`Bash` in every future session even with tiny context — and because the gate covers `Bash`, the documented remedies could not run. Fixed by the SessionStart reset plus a PreCompact reset.
3339
3350
  - **Reset skipped on cache hit.** The PreCompact reset sat after `reinject-context.mjs`'s prompt-cache early return, so a cache hit left the gate tripped permanently. Moved ahead of the return.
3340
3351
  - **Gate bypass via `NotebookEdit`/`MultiEdit`.** The gate compared `tool_name` exactly while the `settings.json` matcher is a regex (`Edit|Write` also matches both), so those tools fired the hook and passed through it. Now matched against an explicit tool set.
@@ -3372,25 +3383,25 @@ Handoff autonomy wave: `/ukit:handoff-fullstack` runs a whole goal end-to-end wi
3372
3383
 
3373
3384
  ### Fixed
3374
3385
 
3375
- - **`extract-image.mjs`** no longer re-arms `pending-<sha>.json` for an image that already has an `analyzed-<sha>.json` receipt. `selectImages()` always returns the most recent N images from the whole transcript, so a fully-analyzed image never fell out of that window on its own; since `vision-router.sh` calls `--mark-pending` on every prompt, this re-triggered the vision hint/gate on the same closed-out image forever, even on unrelated prompts. Both `--detect` and `--mark-pending` now skip any sha with an existing analyzed receipt.
3386
+ - **`extract-image.mjs`** no longer re-arms `pending-<sha>.json` for an image that already has an `analyzed-<sha>.json` receipt.
3376
3387
 
3377
3388
  ## 1.6.7 - 2026-08-09
3378
3389
 
3379
3390
  ### Fixed
3380
3391
 
3381
3392
  - **`unic-gateway.mjs` `detectUnicGateway()`** is now scoped to Claude Code's own outbound endpoint only (`process.env.ANTHROPIC_BASE_URL`, and the `env.ANTHROPIC_BASE_URL` key in project/home `.claude/settings.json`). It no longer probes Codex `config.toml`, Kilo `secrets.json`, or `OPENAI_BASE_URL` — those describe a different tool's endpoint and were producing permanent false positives (`unicMode: true` for a plain Claude Code session whenever some other tool on the machine happened to be pointed at the UNIC gateway), which would deadlock Edit/Write on any image-mentioning turn under the vision gate.
3382
- - **`vision-router.sh`** no longer always tells the caller to invoke `Agent(subagent_type: "ukit-vision-analyst") [model: unic-vision]`. `unic-vision` is only an invokable model when the UNIC gateway is actually active for this session; the remedy message now branches on `detectUnicGateway()`'s `unicMode`: gateway active keeps today's `unic-vision` text, gateway inactive with a readable `orchestration.modelTiers.vision.fallbackModel` (read from `.ukit/storage/config.json`, the same path `vision-gate.sh` uses) tells the caller to override the model to that fallback and to self-report it in the analyst's receipt, and any missing/broken detection falls back to the strict `unic-vision` text as before. The hook's fail-open contract (never blocks the prompt, always exit 0) is unchanged.
3383
- - **`handoff-model-guard.sh`** no longer re-blocks `git push` forever over a closed, human-approved model-tier exception (a documented `## Model-Tier Guard Override` section with `OVERRIDE_APPROVED_BY: human` now exempts that task from the push-time reviewer/executor tier scan).
3393
+ - **`vision-router.sh`** no longer always tells the caller to invoke `Agent(subagent_type:
3394
+ - **`handoff-model-guard.sh`** no longer re-blocks `git push` forever over a closed, human-approved model-tier exception (a documented `## Model-Tier Guard Override` section with `OVERRIDE_APPROVED_BY:
3384
3395
 
3385
3396
  ## 1.6.6 - 2026-08-03
3386
3397
 
3387
3398
  ### Fixed
3388
3399
 
3389
- - **`ensureGitignore`** no longer silently no-ops on a damaged UKit block (missing/duplicate end marker). Marker detection is now a single source of truth (`parseGitignore` + `locateBlock`, exact-line matching, shared with `removeGitignoreBlock`), fixing data loss on substring-collision lines, content between two legitimate blocks, and CRLF round-tripping, while staying idempotent.
3400
+ - **`ensureGitignore`** no longer silently no-ops on a damaged UKit block (missing/duplicate end marker).
3390
3401
  - **Install summary counts** no longer go negative or misattribute a skip. `applyDiffResults` now tracks skips per planned action (`create`/`update`), and `runInstallPipeline` subtracts each skip from its own bucket instead of always assuming `update`.
3391
3402
  - **Runtime config default version** is now read from `package.json` instead of a hardcoded, drifting literal (was stuck at `1.5.2`).
3392
3403
  - **`mergeObjects` (runtime config)** now refuses `__proto__`, `constructor`, and `prototype` keys at every merge depth, closing a prototype-pollution path via a hand-edited `.ukit/storage/config.json`.
3393
- - **`buildInstallPlan`** no longer aborts the entire install when a template is missing for a *non-selected/excluded* item — it skips quietly. A missing template for a *selected* item still fails loudly with a clear error.
3404
+ - **`buildInstallPlan`** no longer aborts the entire install when a template is missing for a *non-selected/excluded* item — it skips quietly.
3394
3405
  - **`uninstallUkit`** now reports out-of-scope/forged tracked paths on real runs, not only `--dry-run`, while routine link-child paths stay silent.
3395
3406
 
3396
3407
  ## 1.6.5 - 2026-08-02
@@ -3399,10 +3410,10 @@ Handoff autonomy wave: `/ukit:handoff-fullstack` runs a whole goal end-to-end wi
3399
3410
 
3400
3411
  - **Enforced `unic-vision` image lane.** Images are now mechanically routed to a vision-capable model instead of being guessed at by `unic-code`/`unic-smart`, which cannot read images on the UNIC gateway.
3401
3412
  - `.claude/ukit/index/extract-image.mjs` — decodes pasted images out of the session transcript to disk (a spawned subagent receives text only and does not inherit image blocks), and writes content-addressed `pending-<sha>.json` markers. Single owner of the sha256; both the marker and the image filename come from the same hash.
3402
- - `.claude/hooks/vision-router.sh` (`UserPromptSubmit`) — detects all three input forms (pasted, local path, image URL) and arms a marker for each. Fails OPEN: a failure here degrades to no hint and no markers, never a wedged prompt.
3403
- - `.claude/hooks/vision-gate.sh` (`PreToolUse`, `Edit|Write` only) — hard-blocks the write (exit 2) until an `analyzed-<sha>.json` receipt exists whose self-reported model is vision-capable. A receipt from `unic-code`, `unic-smart`, `sonnet`, or `opus` is treated as ABSENT and still blocks. Fails CLOSED, and gateway detection that is missing or broken DENIES the fallback-model exception rather than granting it. `Read`/`Grep`/`Glob`/`Bash` are never gated — the vision analyst needs them to clear the gate.
3413
+ - `.claude/hooks/vision-router.sh` (`UserPromptSubmit`) — detects all three input forms (pasted, local path, image URL) and arms a marker for each.
3414
+ - `.claude/hooks/vision-gate.sh` (`PreToolUse`, `Edit|Write` only) — hard-blocks the write (exit 2) until an `analyzed-<sha>.json` receipt exists whose self-reported model is vision-capable.
3404
3415
  - `ukit-vision-analyst` agent — pinned to `unic-vision`, the only lane permitted to interpret images. Reports findings only; it has no `Edit`/`Write`.
3405
- - `.claude/ukit/index/unic-gateway.mjs` — detects a `unicjsc.com` gateway across Claude Code env, Codex config, Kilo config, and `OPENAI_BASE_URL`. Only ever tests for substring presence; never reads credential file contents into output.
3416
+ - `.claude/ukit/index/unic-gateway.mjs` — detects a `unicjsc.com` gateway across Claude Code env, Codex config, Kilo config, and `OPENAI_BASE_URL`.
3406
3417
 
3407
3418
  ### Changed
3408
3419
 
@@ -3414,14 +3425,14 @@ Handoff autonomy wave: `/ukit:handoff-fullstack` runs a whole goal end-to-end wi
3414
3425
 
3415
3426
  ### Added
3416
3427
 
3417
- - Hard enforcement of the handoff model-tier contract via a new `PreToolUse` hook (`.claude/hooks/handoff-model-guard.sh`), registered for both `Edit|Write` and `Bash`. Previously the plan=opus / implement=sonnet / review=opus split was only a prompt convention the orchestrating model could silently skip.
3428
+ - Hard enforcement of the handoff model-tier contract via a new `PreToolUse` hook (`.claude/hooks/handoff-model-guard.sh`), registered for both `Edit|Write` and `Bash`.
3418
3429
  - Blocks writing `docs/AI_HANDOFF/PLAN.md` unless it declares a smart-tier `PLANNER_MODEL` in a new mandatory `## Planner Report` footer.
3419
3430
  - Blocks creating a fresh `TASK-xxx.md` until `PLAN.md` has a valid smart-tier `PLANNER_MODEL`.
3420
3431
  - Blocks writing `## Executor Report` unless `EXECUTOR_MODEL` is present and not lite-tier.
3421
3432
  - Blocks writing `## Reviewer Verdict` unless `REVIEWER_MODEL` is smart-tier and differs from `EXECUTOR_MODEL`.
3422
3433
  - Blocks `git push` when any reviewed task in the active cycle violates the contract.
3423
3434
  - Applies identically to the standalone `/ukit:handoff-create`, `/ukit:handoff-implement`, `/ukit:handoff-review` commands and the combined `/ukit:handoff-fullstack` pipeline, since the gate is keyed on file content, not on which command ran.
3424
- - `/ukit:handoff-create`, `/ukit:handoff-implement`, `/ukit:handoff-review`, `/ukit:handoff-fullstack`: each phase now carries a mandatory Agent-tool-spawn directive (`ukit-small-task-maintainer`, `handoff-planner`, `feature-implementer`, `code-reviewer`) so the correct model tier is actually invoked, not just suggested.
3435
+ - `/ukit:handoff-create`, `/ukit:handoff-implement`, `/ukit:handoff-review`, `/ukit:handoff-fullstack`:
3425
3436
  - `handoff-planner` agent and `PLAN.md` now require a `## Planner Report` / `PLANNER_MODEL` self-report, mirroring the existing `EXECUTOR_MODEL` / `REVIEWER_MODEL` self-report contract on task files.
3426
3437
 
3427
3438
  ## 1.6.2 - 2026-07-26
@@ -3432,23 +3443,23 @@ Handoff autonomy wave: `/ukit:handoff-fullstack` runs a whole goal end-to-end wi
3432
3443
 
3433
3444
  ### Changed
3434
3445
 
3435
- - Downgraded `find-cause` and `map-impact` orchestration contracts from `modelTier: smart` (opus) to `modelTier: code` (sonnet); `review-release` stays on `smart`. Reduces unnecessary Opus usage for routine debugging/impact-mapping work.
3446
+ - Downgraded `find-cause` and `map-impact` orchestration contracts from `modelTier:
3436
3447
 
3437
3448
  ### Fixed
3438
3449
 
3439
- - Auto-compact context-pressure state is now surfaced to the model as a warning (`[ukit-skill-router] Context pressure: soft/hard ...`) once token usage crosses the soft/hard threshold, instead of being silently tracked and only reinjected after Claude Code's native compaction already began. Users previously had to compact manually because nothing ever prompted proactive `/compact` suggestions.
3450
+ - Auto-compact context-pressure state is now surfaced to the model as a warning (`[ukit-skill-router] Context pressure:
3440
3451
 
3441
3452
  ## 1.5.24 - 2026-06-10
3442
3453
 
3443
3454
  ### Fixed
3444
3455
 
3445
- - Register `command-handoff-fullstack` in `manifests/platform.full.yaml` so `ukit install` now copies `handoff-fullstack.md` to target projects. Previously the template existed but was missing from the manifest.
3456
+ - Register `command-handoff-fullstack` in `manifests/platform.full.yaml` so `ukit install` now copies `handoff-fullstack.md` to target projects.
3446
3457
 
3447
3458
  ## 1.5.23 - 2026-06-10
3448
3459
 
3449
3460
  ### Added
3450
3461
 
3451
- - `handoff-fullstack`: new all-in-one slash command combining `handoff-create` + `handoff-implement` + `handoff-review` into a single pipeline. Per-step model split (haiku/unic-lite for light work, sonnet/unic-code for implementation, opus/unic-smart for planning + review), plan auto-commit, conditional push on full approval, always-on worktree/branch cleanup, guaranteed clean git state at cycle end.
3462
+ - `handoff-fullstack`: new all-in-one slash command combining `handoff-create` + `handoff-implement` + `handoff-review` into a single pipeline.
3452
3463
 
3453
3464
  ## 1.5.22 - 2026-06-09
3454
3465
 
@@ -3460,14 +3471,14 @@ Handoff autonomy wave: `/ukit:handoff-fullstack` runs a whole goal end-to-end wi
3460
3471
 
3461
3472
  ### Changed
3462
3473
 
3463
- - Renamed handoff slash commands from `*-handoff` to `handoff-*` convention: `handoff-status`, `handoff-create`, `handoff-implement`, `handoff-review`, `handoff-clear`. Old `*-handoff.md` files removed; manifests and skill routing updated.
3474
+ - Renamed handoff slash commands from `*-handoff` to `handoff-*` convention: `handoff-status`, `handoff-create`, `handoff-implement`, `handoff-review`, `handoff-clear`.
3464
3475
  - Auto-prune now targets `handoff-abort.md` (new name) instead of `clear-handoff.md`.
3465
3476
 
3466
3477
  ## 1.5.16 - 2026-06-06
3467
3478
 
3468
3479
  ### Changed
3469
3480
 
3470
- - `handoff-clear`: added Step 2 — stage `docs/AI_HANDOFF/`, commit planning artifacts, merge `handoff/integration → $BASE`, push, delete integration branch. This is the **only** git commit+push in the entire handoff flow.
3481
+ - `handoff-clear`: added Step 2 — stage `docs/AI_HANDOFF/`, commit planning artifacts, merge `handoff/integration → $BASE`, push, delete integration branch.
3471
3482
  - `handoff-review`: removed all merge/push instructions from Step 3. Reviewer now stops at "Run /ukit:handoff-clear" after all tasks approved.
3472
3483
  - Rule enforced: `handoff-create`, `handoff-implement`, `handoff-review` may only change files inside `docs/AI_HANDOFF/`. No commits to main, no pushes.
3473
3484
 
@@ -3475,13 +3486,13 @@ Handoff autonomy wave: `/ukit:handoff-fullstack` runs a whole goal end-to-end wi
3475
3486
 
3476
3487
  ### Changed
3477
3488
 
3478
- - `handoff-review`: removed automatic `git merge handoff/integration → $BASE`. Reviewer now stops after all tasks are approved and instructs the human to merge manually. Only the end user (or an explicit human prompt) may commit to the base branch.
3489
+ - `handoff-review`: removed automatic `git merge handoff/integration → $BASE`. Reviewer now stops after all tasks are approved and instructs the human to merge manually.
3479
3490
 
3480
3491
  ## 1.5.14 - 2026-06-05
3481
3492
 
3482
3493
  ### Added
3483
3494
 
3484
- - Added 6 handoff slash commands to OpenCode template (`ukit-handoff-status`, `ukit-handoff-create`, `ukit-handoff-implement`, `ukit-handoff-review`, `ukit-handoff-clear`, `ukit-handoff-abort`). These now appear as Workflows in Kilo Code and slash commands in OpenCode after `ukit install`.
3495
+ - Added 6 handoff slash commands to OpenCode template (`ukit-handoff-status`, `ukit-handoff-create`, `ukit-handoff-implement`, `ukit-handoff-review`, `ukit-handoff-clear`, `ukit-handoff-abort`).
3485
3496
 
3486
3497
  ### Fixed
3487
3498
 
@@ -3491,17 +3502,17 @@ Handoff autonomy wave: `/ukit:handoff-fullstack` runs a whole goal end-to-end wi
3491
3502
 
3492
3503
  ### Fixed
3493
3504
 
3494
- - Fixed `compact-threshold.mjs` never being deployed by `ukit install` — the file existed in `templates/` since v1.1.2 but was missing from `manifests/platform.full.yaml`. Every Bash PostToolUse hook (`compress-output.sh`) and PreCompact hook (`reinject-context.sh`) crashed with `ERR_MODULE_NOT_FOUND`, causing the agent to silently stop mid-task.
3495
- - Added `ukit-runtime-compact-threshold-script` manifest entry with correct `requires` chain. Updated `requires` for `ukit-runtime-reinject-context-script`, `ukit-runtime-output-compression-script`, and `hook-skill-router` to declare the dependency.
3496
- - Changed default `safePatch.advisoryOnly` from `false` to `true` in `src/core/runtimeConfig.js`. Previously, `stale-spec-guard.sh` exited code 2 on any Edit to a shared/risky file with a stale `old_string`, causing Claude Code to block the tool call and halt the agent loop silently from the user's perspective. Advisory mode downgrades exit 2 → exit 0 + warning, allowing the agent to continue.
3505
+ - Fixed `compact-threshold.mjs` never being deployed by `ukit install` — the file existed in `templates/` since v1.1.2 but was missing from `manifests/platform.full.yaml`.
3506
+ - Added `ukit-runtime-compact-threshold-script` manifest entry with correct `requires` chain.
3507
+ - Changed default `safePatch.advisoryOnly` from `false` to `true` in `src/core/runtimeConfig.js`.
3497
3508
 
3498
3509
  ## 1.5.5 - 2026-05-30
3499
3510
 
3500
3511
  ### Added
3501
3512
 
3502
- - **Handoff Quality Gate** — opt-in, tool-agnostic, file-based, 4-phase pipeline (Idea+Plan → Create Tasks → Implement+Test → Review+Test) for tasks routed through `docs/AI_HANDOFF/`. Daily ad-hoc prompts are NOT affected and continue with the existing lightweight workflow.
3503
- - New agent `templates/.claude/agents/code-reviewer.md`: independent reviewer with a model-isolation check. Refuses to review when `EXECUTOR_MODEL` equals reviewer's own model, when either is missing/unknown, or when re-run of Verification Commands fails. Emits a structured `## Reviewer Verdict` block.
3504
- - New config block `handoff.*` in `templates/ukit/storage/config.json` with Vietnamese `_help` entries: `handoff.plan.requireTestPlan`, `handoff.executor.testFirstRequired`, `handoff.reviewer.model` (default `unic-smart`), `handoff.reviewer.blockOnCritical`, etc. The `*.modelHint` fields are explicitly documented as *labels for humans, not enforced selectors* — model enforcement happens via executor self-report + reviewer refusal.
3513
+ - **Handoff Quality Gate** — opt-in, tool-agnostic, file-based, 4-phase pipeline (Idea+Plan → Create Tasks → Implement+Test → Review+Test) for tasks routed through `docs/AI_HANDOFF/`.
3514
+ - New agent `templates/.claude/agents/code-reviewer.md`: independent reviewer with a model-isolation check.
3515
+ - New config block `handoff.*` in `templates/ukit/storage/config.json` with Vietnamese `_help` entries:
3505
3516
  - New `## 4. Test Plan (REQUIRED — TDD-style)` section in `templates/docs/AI_HANDOFF/PLAN.md`.
3506
3517
  - New `templates/docs/AI_HANDOFF/tasks/_TEMPLATE.md`: every task file MUST embed its own `## Test Cases` (table with happy + ≥1 edge case + regression for bug fixes) + `## Test Files` + `## Verification Commands` + `## Acceptance Criteria`. Tasks without these are `needs_breakdown`, not `ready`.
3507
3518
  - `## Discussion` section pattern on task files: structured AI-to-AI comment thread (date · role · tool/model) so planner/executor/reviewer can talk back to each other through files — no out-of-band channels.
@@ -3509,14 +3520,14 @@ Handoff autonomy wave: `/ukit:handoff-fullstack` runs a whole goal end-to-end wi
3509
3520
 
3510
3521
  ### Changed
3511
3522
 
3512
- - `templates/.claude/agents/feature-implementer.md`: now operates in two explicit modes. **Daily mode** (DEFAULT): unchanged lightweight flow — tests only when touched code has coverage, no reviewer trigger. **Handoff mode** (when task lives under `docs/AI_HANDOFF/tasks/`): test-first → green → reviewer; cannot claim `STATUS: DONE` without fresh PASS in turn. Report format now includes `EXECUTOR_TOOL`, `EXECUTOR_MODEL`, `EXECUTOR_SUBAGENT` self-report.
3523
+ - `templates/.claude/agents/feature-implementer.md`: now operates in two explicit modes.
3513
3524
  - `templates/.claude/agents/bug-debugger.md`: same two-mode split. Handoff mode requires regression-test-first (RED before fix, GREEN after); Daily mode unchanged.
3514
- - `templates/docs/AI_HANDOFF/RULES.md`: rewritten around the 4-phase model. Added `## Hard rule — All work stays in docs/AI_HANDOFF/` (no out-of-band AI communication). Added Phase 2 TDD-embedded requirement. Auto-compact 80-line rule scoped to state files (ACTIVE/INDEX/tasks); PLAN.md and RULES.md exempt.
3525
+ - `templates/docs/AI_HANDOFF/RULES.md`: rewritten around the 4-phase model. Added `## Hard rule — All work stays in docs/AI_HANDOFF/` (no out-of-band AI communication).
3515
3526
  - `templates/CLAUDE.md` + `templates/AGENTS.md`: added scoped `## Handoff Quality Gate` section with explicit OPT-IN scope language so adapter targets (Claude Code, Kilo Code, Codex, OpenCode, future tools) only apply Quality Gate to handoff work, not daily prompts.
3516
3527
 
3517
3528
  ### Fixed
3518
3529
 
3519
- - Fixed output-history deduplication for `promptCache: false` — the second call with semantically equivalent (but noisy) output now returns the cached first summary instead of recomputing. Root cause: `normalizeOutputSummaryForDedupe` wasn't stripping `FAIL`/`PASS`/`Test Files`/`Tests`/`Duration`/`Start at` lines from the dedup key, so slight token-budget differences between two similar payloads produced different keys and broke cache hits. Added `findOutputHistoryEntry` lookup in `main()` to serve cached summaries without prompt-cache.
3530
+ - Fixed output-history deduplication for `promptCache: false` — the second call with semantically equivalent (but noisy) output now returns the cached first summary instead of recomputing.
3520
3531
 
3521
3532
  ### Why
3522
3533
 
@@ -3586,7 +3597,7 @@ User had two real concerns: (1) cheap-model executors (e.g. Kilo Code) miss smal
3586
3597
 
3587
3598
  ### Fixed
3588
3599
 
3589
- - Stopped safe-patch hooks (`stale-spec-check`, `post-edit-verify`) from hard-blocking tool calls when configured via the new `safePatch.advisoryOnly` flag or the `UKIT_SAFE_PATCH_ADVISORY=1` env. Removes the mid-task "stop and wait for continue" stalls that hit shared-risk files in `.claude/`, `templates/`, `scripts/`, etc., while preserving the diagnostic message so Claude/Codex can self-correct instead of stalling.
3600
+ - Stopped safe-patch hooks (`stale-spec-check`, `post-edit-verify`) from hard-blocking tool calls when configured via the new `safePatch.advisoryOnly` flag or the `UKIT_SAFE_PATCH_ADVISORY=1` env.
3590
3601
  - Default behavior unchanged (`advisoryOnly: false`): pre-edit corruption guards (shebang-bom, non-text, whole-file Write to shared-risk) and the `protect-files` / `block-dangerous` hooks still hard-block.
3591
3602
 
3592
3603
  ### Tests
@@ -3679,7 +3690,7 @@ User had two real concerns: (1) cheap-model executors (e.g. Kilo Code) miss smal
3679
3690
  - Added post-edit delta verification for backed-up shared-risk edits so unexpected broad rewrites are flagged against the Safe Patch hunk/changed-line budget and rollback manifests record after hashes.
3680
3691
  - Added Safe Patch backup retention and bounded delta-diff fallback so rollback data does not grow forever and very large edits avoid unbounded LCS memory use.
3681
3692
  - Added byte-first UTF-8/BOM/newline profile handling so helper-mediated patches preserve UTF-8 BOM/no-BOM, LF/CRLF, Vietnamese/CJK/emoji content, and reject unsafe binary/invalid UTF-8 edit paths.
3682
- - Added `safePatch` runtime config defaults under `.ukit/storage/config.json` while keeping the end-user workflow unchanged: normal users still only need `ukit install`; helpers remain internal guardrails.
3693
+ - Added `safePatch` runtime config defaults under `.ukit/storage/config.json` while keeping the end-user workflow unchanged:
3683
3694
 
3684
3695
  ### Changed
3685
3696
 
@@ -3757,7 +3768,7 @@ User had two real concerns: (1) cheap-model executors (e.g. Kilo Code) miss smal
3757
3768
  - Added recovery-safe output compaction on top of the existing command-aware compression lane instead of introducing a second output/history subsystem.
3758
3769
  - Preserved raw tool output in `ukit/storage/cache/tee/` for high-value recovery cases such as failed commands, large raw outputs, or unusually high token savings.
3759
3770
  - Extended output-history entries with recovery metadata (`rawSaved`, `rawPath`, `rawBytes`, `recoveryReason`) so routed/runtime consumers can reuse the same shared artifact instead of rerunning noisy commands blindly.
3760
- - Appended a compact `Full output:` recovery hint only when it still preserves net token savings; when it would erase the savings, UKit still keeps the raw artifact and metadata without bloating the inline summary.
3771
+ - Appended a compact `Full output:` recovery hint only when it still preserves net token savings;
3761
3772
  - Kept source runtime behavior and shipped Claude hook behavior aligned for recovery-safe compaction, including prompt-cache reuse of recovery metadata and history dedupe that ignores the recovery-hint line.
3762
3773
  - Extended `ukit status` output-compression reporting to show recovery counts so maintainers can see when the runtime preserved raw evidence in addition to saving tokens.
3763
3774
  - Updated shared runtime docs/version surfaces to reflect the new v1.1.4 recovery-safe compaction lane while keeping the teammate workflow centered on `ukit install`.
@@ -3870,25 +3881,25 @@ User had two real concerns: (1) cheap-model executors (e.g. Kilo Code) miss smal
3870
3881
  - support nested DuraOne monorepo activation
3871
3882
  - Fixed index graph resolution for extensionless React-style internal imports (`.jsx`, `.tsx`, and directory `index.jsx` / `index.tsx`) so rerunning **`ukit install`** rebuilds correct relations/analogs in JSX/TSX projects too.
3872
3883
  - Fixed source discovery for supported **symlinked source files** in both the repo runtime and the shipped installed mirror, so alias file paths inside the project remain indexed/searchable even when the real file lives elsewhere.
3873
- - Stopped `ukit install` from claiming success before the required source-code index actually finishes; if index build fails, the command now tells maintainers to fix the repo state and rerun **`ukit install`**.
3884
+ - Stopped `ukit install` from claiming success before the required source-code index actually finishes;
3874
3885
  - Slimmed the bundled hidden `canvas-design` asset lane to a curated built-in font set, cutting the published tarball from roughly **3.3 MB** to **1.5 MB** while preserving immediate post-install usability and the one-command `ukit install` workflow.
3875
3886
  - Deduped the heavy hidden **OOXML** support bundle used by PPTX/DOCX into a shared installed lane, preserving the same skill paths after `ukit install` via symlinks and safely migrating previously managed real directories on reinstall.
3876
- - Hardened uninstall against stale tracked metadata under managed symlink roots: if old install records still mention descendants like `.claude/skills/pptx/ooxml/...` after the root became a tracked link, uninstall now removes only the tracked link and refuses to follow that symlink into the shared target bundle.
3877
- - Hardened reinstall migration for shared OOXML symlink targets so UKit only auto-replaces an old real directory when every nested path is still clearly UKit-managed; untracked empty subdirectories now block replacement instead of being silently deleted.
3878
- - Hardened reinstall migration again so even an **empty real directory** at a managed symlink target is treated as ambiguous user content; UKit now warns and keeps the directory instead of silently replacing it during `ukit install`.
3879
- - Hardened legacy reinstall cleanup so `ukit install` no longer deletes the whole old `ukit/.ukit/` directory tree; it now removes only the legacy `install.json` file and keeps any user files that may still live under that folder.
3880
- - Hardened legacy flat-file cleanup so paths like `.claude/skills/delivery.md` are removed only when they are actual files/symlinks; if a user has a real directory with the same legacy name, UKit now preserves it instead of recursively deleting it.
3887
+ - Hardened uninstall against stale tracked metadata under managed symlink roots:
3888
+ - Hardened reinstall migration for shared OOXML symlink targets so UKit only auto-replaces an old real directory when every nested path is still clearly UKit-managed;
3889
+ - Hardened reinstall migration again so even an **empty real directory** at a managed symlink target is treated as ambiguous user content;
3890
+ - Hardened legacy reinstall cleanup so `ukit install` no longer deletes the whole old `ukit/.ukit/` directory tree;
3891
+ - Hardened legacy flat-file cleanup so paths like `.claude/skills/delivery.md` are removed only when they are actual files/symlinks;
3881
3892
  - Hardened adapter deselection metadata cleanup so removing a managed link path also removes stale tracked descendants under that path, preventing old `.antigravity/skills/...` or `.codex/skills/...` entries from lingering in install metadata after `ukit install --tools=...` changes.
3882
- - Hardened maintainer preview flows so `ukit diff` / dry-run install planning no longer delete a previously managed real directory before showing the preview; only the real install path may perform safe managed-directory replacement.
3883
- - Fixed index import resolution for **single-segment `baseUrl` imports** (for example `import { loadUser } from 'userApi'` with `baseUrl: "./src/services"`), in both the source runtime and the shipped installed mirror, so source-code indexing keeps relations/query ranking correct for that TypeScript layout too.
3884
- - Hardened adapter deselection safety again so UKit only prunes deselected adapter files when install metadata proves UKit actually owns them; a first `ukit install` no longer deletes a teammate’s pre-existing `.codex/.antigravity` files just because the adapter is currently deselected.
3893
+ - Hardened maintainer preview flows so `ukit diff` / dry-run install planning no longer delete a previously managed real directory before showing the preview;
3894
+ - Fixed index import resolution for **single-segment `baseUrl` imports** (for example `import { loadUser } from 'userApi'` with `baseUrl:
3895
+ - Hardened adapter deselection safety again so UKit only prunes deselected adapter files when install metadata proves UKit actually owns them;
3885
3896
  - Tightened deselection ownership handling so when adapter cleanup is skipped (non-interactive mode, user says no, or the path is a real directory), UKit immediately drops those deselected paths from install metadata instead of carrying stale ownership forward to uninstall.
3886
- - Restored **index-first routing** for prompt-only hybrid lanes where a standalone specialist (for example Docker packaging) is selected together with a real code skill; source runtime, shipped `route-task`, and the Claude `skill-router` hook now keep `resolve-context` available instead of falling straight to `read-skill-instructions`.
3887
- - Hardened fresh `ukit install` ownership handling against stray/non-UKit `install.json` files: obsolete-path pruning and metadata carry-forward now trust previous tracked files only when metadata proves the prior install was actually written by UKit, so a first install no longer deletes or inherits ownership of user files from foreign/stale metadata.
3897
+ - Restored **index-first routing** for prompt-only hybrid lanes where a standalone specialist (for example Docker packaging) is selected together with a real code skill;
3898
+ - Hardened fresh `ukit install` ownership handling against stray/non-UKit `install.json` files:
3888
3899
  - Stopped tracking **skip-strategy bootstrap files** (for example `docs/PROJECT.md`, `docs/MEMORY.md`, `docs/WORKLOG.md`, `CLAUDE.md`, `AGENTS.md`, `.claude/settings.local.json`, `.codex/settings.local.json`) as uninstall-owned outputs, so UKit preserves team memory/local settings even when those files were first created by `ukit install`.
3889
- - Kept **test-like direct targets** targeted even when filenames omit `.test` / `.spec` (for example `tests/pages/LoginFlow.js`): source verification planning and shipped `resolve-context` / `verify-context` helpers now treat `tests/` / `specs/` targets as related tests instead of downgrading to minimal verification.
3890
- - Hardened source `deriveVerificationPlan(...)` again so callers that pass a precomputed/raw `contextResult` still normalize direct `tests/` / `specs/` primary targets into targeted verification; direct test files no longer fall back to `mode=minimal` just because `relatedTests` was not pre-expanded upstream.
3891
- - Fixed source + shipped index discovery so root-level **`specs/` / `spec/` / `test/` / `__tests__/`** lanes are scanned and treated consistently as likely tests; spec-root tests now feed `tests-map` / relations correctly and stay deprioritized in normal file search unless the prompt explicitly asks for tests/specs.
3900
+ - Kept **test-like direct targets** targeted even when filenames omit `.test` / `.spec` (for example `tests/pages/LoginFlow.js`):
3901
+ - Hardened source `deriveVerificationPlan(...)` again so callers that pass a precomputed/raw `contextResult` still normalize direct `tests/` / `specs/` primary targets into targeted verification;
3902
+ - Fixed source + shipped index discovery so root-level **`specs/` / `spec/` / `test/` / `__tests__/`** lanes are scanned and treated consistently as likely tests;
3892
3903
  - Completed the root test-lane hardening so **root `test/`, `spec/`, and `__tests__/`** paths are recognized consistently across index build, query ranking, and direct test-target routing/verification heuristics in both source and shipped helpers.
3893
3904
  - Aligned shipped helper cache keys with route-task seeding for **target-only helper invocations** (`--target ...` with no prompt text), so direct `resolve-context` / `verify-context` calls can reuse the route-seeded cache instead of recomputing indexed context.
3894
3905
  - Reused relations/analogs safely for alias-based projects when code + alias config stay unchanged, reducing wasted rebuild work on repeated refreshes.