@ngockhoale/ukit 2.2.1 → 2.2.3

package/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 All notable changes to UKit are documented here.
 
+## 2.2.3 - 2026-08-26
+
+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.
+
+### Fixed
+
+- **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.
+- **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.
+- **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.
+- **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.
+- **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`.
+- **`.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.
+
+### Added
+
+- **`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).
+- **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`.
+
+## 2.2.2 - 2026-08-22
+
+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.
+
+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.
+
+### Fixed
+
+- **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.
+- **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.
+- **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.
+- **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.
+- **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.
+- **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`.
+- **`/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".
+- **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:**`.
+
+### Added
+
+- **`### 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.
+- **`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.
+- **`.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.
+- **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`.
+
+### Changed
+
+- **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.
+- **`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.
+
 ## 2.2.1 - 2026-08-22
 
 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.

package/manifests/platform.full.yaml

@@ -110,13 +110,21 @@ items:
       - docs-project
       - docs-memory
     mergeStrategy: overwrite_with_backup
+    # Same set as root-claude-md: AGENTS.md is the same body with a different H1 plus one
+    # OpenCode-only section, so it interpolates the same variables. Kept in sync by
+    # tests/consistency/contextDocsParity.test.js.
     variables:
       - project.name
+      - project.root
       - project.stack
       - stack.frontend
       - stack.backendApi
       - stack.postgres
       - runtime.packageManager
+      - runtime.os
+      - runtime.nodeVersion
+      - providers.unic
+      - ukit.version
     enabledByDefault: true
     packs:
       - core
@@ -1029,6 +1037,30 @@ items:
     packs:
       - core
 
+  - id: hook-record-execution
+    type: hook
+    sourceTemplate: .claude/hooks/record-execution.sh
+    targetPath: .claude/hooks/record-execution.sh
+    requires:
+      - ukit-runtime-execution-ledger-script
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: hook-completion-gate
+    type: hook
+    sourceTemplate: .claude/hooks/completion-gate.sh
+    targetPath: .claude/hooks/completion-gate.sh
+    requires:
+      - ukit-runtime-execution-ledger-script
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: hook-auto-allow-bash
     type: hook
     sourceTemplate: .claude/hooks/auto-allow-bash.sh
@@ -1215,6 +1247,28 @@ items:
     packs:
       - core
 
+  - id: ukit-runtime-execution-ledger-script
+    type: config
+    sourceTemplate: .claude/ukit/runtime/execution-ledger.mjs
+    targetPath: .claude/ukit/runtime/execution-ledger.mjs
+    requires: []
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: ukit-runtime-hook-chain-runner-script
+    type: config
+    sourceTemplate: .claude/ukit/runtime/hook-chain-runner.mjs
+    targetPath: .claude/ukit/runtime/hook-chain-runner.mjs
+    requires: []
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: ukit-runtime-safe-patch-core-script
     type: config
     sourceTemplate: .claude/ukit/runtime/safe-patch-core.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.2.1",
+  "version": "2.2.3",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex, OpenCode, and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/templates/.claude/commands/ukit/handoff-clear.md

@@ -57,7 +57,7 @@ Cleared: X worktrees removed, Y branches deleted, staged changes unstaged.
 Handoff docs reset. Ready for new cycle.
 ```
 
-> Claude Code: spawn `ukit-small-task-maintainer` (haiku).
+> Claude Code: spawn `ukit-small-task-maintainer` (haiku). omp: the `task` tool with `agent: "ukit-small-task-maintainer"`.
 > Other tools: lite model, follow steps 1–5.
 
 **Next:** `/ukit:handoff-create <new problem description>`

package/templates/.claude/commands/ukit/handoff-create.md

@@ -22,7 +22,7 @@ Planning is the **only** place in the handoff pipeline where asking the human is
 it is where every ambiguity must be burned off. Whatever is left unresolved here becomes a
 guess during implementation, where nobody is available to correct it.
 
-**Ask once, up front, batched.** Before Step 1, if `$ARGUMENTS` leaves a choice that changes
+**Ask once, up front, batched.** Before Step 1, if the **Problem / feature** section above leaves a choice that changes
 *what gets built* — not how — collect every such question into a **single** `AskUserQuestion`
 call (max 4 questions, each with a `(Recommended)` first option). Then close the window.
 
@@ -49,7 +49,7 @@ After the batched call, run Steps 1–2.5 to completion without further question
 4. Read `docs/AI_HANDOFF/tasks/_TEMPLATE.md` → task file structure
 5. Return a compact summary. Do NOT write anything yet.
 
-> Other tools without subagent support: manually switch to the lite model, run the steps above yourself, keep the summary in context.
+> **For the human operator, on a tool with no agent support (Codex, OpenCode) — not an instruction to the model:** manually switch to the lite model, run the steps above yourself, keep the summary in context.
 
 ---
 
@@ -106,7 +106,7 @@ The planner agent does the following (use Step 1 summary — do NOT re-read file
 
 7. Report: task IDs, dependency graph, any `needs_breakdown` + reason
 
-> Other tools without subagent support: manually switch to the strong model, execute steps 1–7 above yourself.
+> **For the human operator, on a tool with no agent support (Codex, OpenCode) — not an instruction to the model:** manually switch to the strong model, execute steps 1–7 above yourself.
 
 ---
 
@@ -127,7 +127,7 @@ intact. What it no longer does is hand a stalled plan back and wait.
 2. `Issues Found` → route back to Step 2: planner revises `PLAN.md` and the affected `TASK-xxx.md` files to address every finding, then re-submit for another Step 2.5 review (this becomes the next round). Do NOT commit or hand off to executor on `Issues Found`.
 3. `Approved` → append `PLAN_REVIEW: Approved by <reviewer model>` to PLAN.md's `## Planner Report` footer, then proceed.
 
-> Other tools without subagent support: manually switch to the strong model in a **separate** chat/session from Step 2, paste PLAN.md, review using the Spec/Plan Review checklist in `.claude/agents/code-reviewer.md`.
+> **For the human operator, on a tool with no agent support (Codex, OpenCode) — not an instruction to the model:** manually switch to the strong model in a **separate** chat/session from Step 2, paste PLAN.md, review using the Spec/Plan Review checklist in `.claude/agents/code-reviewer.md`.
 
 ---
 

package/templates/.claude/commands/ukit/handoff-fullstack.md

@@ -12,6 +12,8 @@
 | Planning + Review (reasoning, design, verification) | opus · unic-smart · strongest available |
 
 > Claude Code: spawn `ukit-small-task-maintainer` (haiku) for light steps; spawn `handoff-planner` (opus) for planning; spawn `feature-implementer` (sonnet) agents for implementation; spawn `code-reviewer` (opus) per task for review.
+>
+> omp: same four agents, launched with the `task` tool (`agent: "<name>"`). They live in `.omp/agents/` and bind their tier through `model: "@lite"` / `"@code"` / `"@smart"`, resolved via `modelRoles` in `.omp/config.yml` — you do not pass a model name.
 
 > **omp model tiers:** the tiers above map to `.omp/config.yml`'s `modelRoles`, referenced from agent frontmatter as `@lite` / `@code` / `@smart`.
 
@@ -20,17 +22,17 @@
 ## Problem / feature
 $ARGUMENTS
 
-> **If `$ARGUMENTS` is empty:** Do NOT proceed. Ask the user: "What problem or feature would you like to tackle in this handoff cycle? Please describe it in one or more sentences." Wait for the answer before running any phase.
+> **If the **Problem / feature** section above is empty:** Do NOT proceed. Ask the user: "What problem or feature would you like to tackle in this handoff cycle? Please describe it in one or more sentences." Wait for the answer before running any phase.
 
 ---
 
 ## Autonomy Contract — read before anything else
 
 This command is a **one-shot pipeline**. The human is not watching. Treat every phase below
-as unattended: they may walk away after submitting `$ARGUMENTS` and come back to a finished
+as unattended: they may walk away after submitting the request and come back to a finished
 result.
 
-**The single question window is P0, before any file is written.** If `$ARGUMENTS` leaves a
+**The single question window is P0, before any file is written.** If the **Problem / feature** section above leaves a
 choice that would change what gets built — not how it gets built — batch every such question
 into **one** `AskUserQuestion` call (max 4 questions, each with a `(Recommended)` first
 option) and resolve them all at once. Record the answers in `PLAN.md` §1.
@@ -62,7 +64,7 @@ numbered step completes:
 
 ```
 Command: handoff-fullstack
-Goal: <one sentence from $ARGUMENTS>
+Goal: <one sentence from the **Problem / feature** section above>
 Base: <BASE branch>
 Phase: <P1|P2|P2.5|P3|I1|I2|I3|I4|R1|R2|R3|R4|R5|done>
 Cursor: wave <N> batch <M> — <what just finished>
@@ -80,7 +82,7 @@ continue. Read the cursor, then jump straight to `Next:` and carry on. Tasks alr
 or `pending_review` are skipped; only `ready`, `in_progress`, `changes_requested` and
 `blocked` tasks are picked up.
 
-Only when `RUN.md` is absent or `Phase: done` does `$ARGUMENTS` start a fresh cycle.
+Only when `RUN.md` is absent or `Phase: done` does a new request start a fresh cycle.
 
 ---
 
@@ -97,11 +99,11 @@ Only when `RUN.md` is absent or `Phase: done` does `$ARGUMENTS` start a fresh cy
 
 Return a compact summary. Do NOT write any files yet.
 
-> Other tools without subagent support: manually switch to the lite model and run P1 yourself.
+> **For the human operator, on a tool with no agent support (Codex, OpenCode) — not an instruction to the model:** manually switch to the lite model and run P1 yourself.
 
 ### P2 — Write PLAN.md + task files (strong model)
 
-**Claude Code — MANDATORY, do this before anything else in P2:** call the Agent tool with `subagent_type: "handoff-planner"` (omp: the `task` tool with `agent: "handoff-planner"`), passing it the P1 summary and `$ARGUMENTS`. Do NOT write PLAN.md or task files yourself in the current session — this step is contracted to the strong tier (opus/unic-smart), which only the spawned agent's frontmatter model guarantees.
+**Claude Code — MANDATORY, do this before anything else in P2:** call the Agent tool with `subagent_type: "handoff-planner"` (omp: the `task` tool with `agent: "handoff-planner"`), passing it the P1 summary and the **Problem / feature** section above. Do NOT write PLAN.md or task files yourself in the current session — this step is contracted to the strong tier (opus/unic-smart), which only the spawned agent's frontmatter model guarantees.
 
 The planner agent does the following (use P1 summary — do NOT re-read files):
 
@@ -168,7 +170,7 @@ is written. What it no longer does is hand a stalled plan back to a human who is
 2. `Issues Found` → route back to P2: `handoff-planner` revises `PLAN.md` and the affected `TASK-xxx.md` files to address every finding, then re-submit for one more P2.5 review round — subject to the loop cap above.
 3. `Approved` → append `PLAN_REVIEW: Approved by <reviewer model>` to PLAN.md's `## Planner Report` footer, then proceed to P3.
 
-> Other tools without subagent support: manually switch to the strong model in a **separate** chat/session from P2, paste PLAN.md, review using the Spec/Plan Review checklist in `.claude/agents/code-reviewer.md`.
+> **For the human operator, on a tool with no agent support (Codex, OpenCode) — not an instruction to the model:** manually switch to the strong model in a **separate** chat/session from P2, paste PLAN.md, review using the Spec/Plan Review checklist in `.claude/agents/code-reviewer.md`.
 
 ### P3 — Commit the plan (lite model)
 
@@ -179,7 +181,7 @@ git add docs/AI_HANDOFF/ && git commit -m "handoff: plan — <goal>"
 
 Replace `<goal>` with the one-sentence goal from ACTIVE.md. This locks the plan in git before any implementation begins.
 
-> Other tools without subagent support: manually switch to the lite model for P2/P3.
+> **For the human operator, on a tool with no agent support (Codex, OpenCode) — not an instruction to the model:** manually switch to the lite model for P2/P3.
 
 ---
 

package/templates/.claude/commands/ukit/handoff-implement.md

@@ -58,7 +58,7 @@ If this file already exists with `Phase:` not `done` when the command starts, th
 ## Step 1 — Setup
 
 Read `docs/AI_HANDOFF/ACTIVE.md` → get `Base: <BASE>`.
-Read `docs/AI_HANDOFF/INDEX.md` → collect `ready` tasks (or specific task from $ARGUMENTS).
+Read `docs/AI_HANDOFF/INDEX.md` → collect `ready` tasks (or the specific task named in the request above).
 If there are no `ready` tasks, check for `changes_requested`/`blocked` ones and run those
 instead. Only if nothing is actionable → report and stop.
 
@@ -163,7 +163,7 @@ disk in the task file, which is where the reviewer reads them from. Pasting them
 second time is what blows up the orchestrator's context window and kills the run mid-wave.
 ```
 
-> Other tools without subagent support: open each task in a separate session with the code model.
+> **For the human operator, on a tool with no agent support (Codex, OpenCode) — not an instruction to the model:** open each task in a separate session with the code model.
 
 ### 3c — Orchestrator: copy changes to main + IMMEDIATELY delete worktree
 

package/templates/.claude/commands/ukit/handoff-review.md

@@ -188,4 +188,4 @@ This is the only place this command may ask for a compaction. All state lives in
 `INDEX.md` and `RUN.md`, so a compacted or fresh session resumes with nothing lost.
 
 > Orchestrator (this session) handles Step 1, 2e, and 3 directly — those are not delegated.
-> Other tools without subagent support: manually switch to the strong model, run 2a–2d per task (one session at a time).
+> **For the human operator, on a tool with no agent support (Codex, OpenCode) — not an instruction to the model:** manually switch to the strong model, run 2a–2d per task (one session at a time).

package/templates/.claude/commands/ukit/handoff-status.md

@@ -45,5 +45,5 @@ Next action:
   no active cycle      → /ukit:handoff-create <description>
 ```
 
-> Claude Code: spawn `ukit-small-task-maintainer` (haiku) with the above prompt.
+> Claude Code: spawn `ukit-small-task-maintainer` (haiku) with the above prompt. omp: the `task` tool with `agent: "ukit-small-task-maintainer"`.
 > Other tools: use lite model, run the reads above, format the report.

package/templates/.claude/hooks/completion-gate.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+# Stop hook: block premature terminal stops while routed completion evidence is missing.
+
+INPUT=$(cat)
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+SCRIPT="$PROJECT_ROOT/.claude/ukit/runtime/execution-ledger.mjs"
+
+if [ ! -f "$SCRIPT" ]; then
+  exit 0
+fi
+
+printf '%s' "$INPUT" | UKIT_HARNESS=claude-code node "$SCRIPT" --evaluate-stop

package/templates/.claude/hooks/record-execution.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+# PostToolUse hook: persist session-scoped source/write/verification receipts.
+
+INPUT=$(cat)
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+SCRIPT="$PROJECT_ROOT/.claude/ukit/runtime/execution-ledger.mjs"
+
+if [ ! -f "$SCRIPT" ]; then
+  exit 0
+fi
+
+printf '%s' "$INPUT" | UKIT_HARNESS=claude-code node "$SCRIPT" --record

package/templates/.claude/settings.json

@@ -139,6 +139,16 @@
       }
     ],
     "PostToolUse": [
+      {
+        "matcher": "Read|Grep|Glob",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/record-execution.sh\"",
+            "timeout": 4
+          }
+        ]
+      },
       {
         "matcher": "Edit|Write",
         "hooks": [
@@ -146,6 +156,11 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/post-edit-verify.sh\"",
             "timeout": 8
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/record-execution.sh\"",
+            "timeout": 4
           }
         ]
       },
@@ -156,6 +171,11 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/compress-output.sh\"",
             "timeout": 8
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/record-execution.sh\"",
+            "timeout": 4
           }
         ]
       }
@@ -181,6 +201,17 @@
         ]
       }
     ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/completion-gate.sh\"",
+            "timeout": 4
+          }
+        ]
+      }
+    ],
     "PreCompact": [
       {
         "hooks": [

package/templates/.claude/ukit/index/unic-gateway.mjs

@@ -13,10 +13,13 @@
  *   1. process.env.ANTHROPIC_BASE_URL                        -> 'env'
  *   2. project .claude/settings.json -> env.ANTHROPIC_BASE_URL -> 'claude-settings'
  *   3. ~/.claude/settings.json -> env.ANTHROPIC_BASE_URL       -> 'claude-settings'
- *   4. process.env.OMP_BASE_URL (TASK-004, name unverified)   -> 'omp-env'
- *   5. project .omp/config.yml -> baseUrl (TASK-004, key unverified) -> 'omp-config'
  *
- * Every probe here (including the two omp probes) is scoped to what changes the CALLING
+ * omp needs no probe of its own: verified against omp v17.4.2, it reads `ANTHROPIC_BASE_URL`
+ * for the anthropic provider, so probe 1 covers an omp session for the same reason it covers a
+ * Claude Code one. See the note above the probe list below for the two guessed omp probes this
+ * replaced, and why they could never have fired.
+ *
+ * Every probe here is scoped to what changes the CALLING
  * runtime's OWN outbound endpoint — same rule that already governs probes 1-3. Cross-tool
  * configs are NOT probed. This module is only ever invoked from Claude Code / omp hooks
  * (vision-router.sh, vision-gate.sh, route-task.mjs, and the omp bridge) to gate what THIS
@@ -51,21 +54,23 @@ import { fileURLToPath } from 'node:url';
 const UNIC_TOKEN = 'unicjsc.com';
 const VISION_MODEL_ALIAS = 'unic-vision';
 
-// TODO(verify): omp's own base-URL env var name is a guess -- omp is not installed on this
-// machine and no source/schema is vendored, so this has never been confirmed against a real
-// omp runtime. Resolve via TASK-008's manual smoke test before treating this as confirmed.
-const OMP_BASE_URL_ENV_VAR = 'OMP_BASE_URL';
-
-// TODO(verify): the `.omp/config.yml` key path (`baseUrl`, top-level) is a guess for the same
-// reason as OMP_BASE_URL_ENV_VAR above. Deliberately matched with a narrow anchored regex
-// instead of importing the `yaml` package at runtime -- this file is installed into end-user
-// projects via `ukit install` and must not risk depending on `yaml` being resolvable from a
-// target project's own node_modules tree for a single-key check. This mirrors the codebase's
-// own established precedent for the analogous Codex `config.toml` probe (see git history:
-// CODEX_BASE_URL_UNIC_RE, pre-TASK-007), which rejected a TOML parser dependency for the same
-// reason and documented the trade-off: a malformed/unexpected file just degrades to no hit,
-// which fails safe rather than throwing.
-const OMP_CONFIG_BASE_URL_UNIC_RE = /^\s*baseUrl\s*:\s*["']?[^"'\r\n#]*unicjsc\.com[^"'\r\n#]*["']?\s*(?:#.*)?$/m;
+// RESOLVED 2026-08-22 against a real omp v17.4.2 install -- both omp-specific probes that
+// shipped in 2.2.1 were guesses, and both were wrong:
+//
+//   * `OMP_BASE_URL` does not exist in omp. Its bundled provider resolver reads
+//     `ANTHROPIC_BASE_URL` for the anthropic provider, falling back to
+//     "https://api.anthropic.com" -- i.e. the exact variable probe 1 already reads.
+//   * `.omp/config.yml` has no `baseUrl` key at any level. `omp config get baseUrl` answers
+//     "Unknown setting", and omp's settings schema declares none.
+//
+// So omp needs no probe of its own: an omp session pointed at the UNIC gateway is detected by
+// probe 1, on the same variable and for the same reason as a Claude Code session. That is what
+// makes the rule stated in CLAUDE.md/AGENTS.md ("routing is decided ONLY by ANTHROPIC_BASE_URL")
+// literally true on omp rather than an approximation of it. Both dead probes are removed rather
+// than left in place returning a permanent false -- a probe that can never fire is worse than no
+// probe, because it reads as coverage. Custom per-model `baseUrl` values do exist in omp, but
+// they live in its models config, not in `.omp/config.yml`; if that ever needs probing it is a
+// new probe against a verified path, not a revival of these.
 
 function safeReadFile(filePath) {
   try {
@@ -115,12 +120,6 @@ function probeClaudeSettings(filePath) {
 
 // Narrow anchored regex probe (no YAML parsing) for the omp config file's `baseUrl` key. A
 // missing file, unreadable path, or malformed YAML all degrade to "no hit" -- never throws.
-function probeOmpConfig(filePath) {
-  const raw = safeReadFile(filePath);
-  if (raw == null) return false;
-  return OMP_CONFIG_BASE_URL_UNIC_RE.test(raw);
-}
-
 /**
  * Checks whether the Codex model catalog exists and, if so, whether it lists `unic-vision`.
  * A missing/unreadable/malformed catalog is never an error — it degrades to "unknown" and the
@@ -163,8 +162,6 @@ export function detectUnicGateway(options = {}) {
     () => recordHit(probeEnvVar('ANTHROPIC_BASE_URL'), 'env'),
     () => recordHit(probeClaudeSettings(path.join(rootDir, '.claude', 'settings.json')), 'claude-settings'),
     () => recordHit(probeClaudeSettings(path.join(homeDir, '.claude', 'settings.json')), 'claude-settings'),
-    () => recordHit(probeEnvVar(OMP_BASE_URL_ENV_VAR), 'omp-env'),
-    () => recordHit(probeOmpConfig(path.join(rootDir, '.omp', 'config.yml')), 'omp-config'),
   ];
   for (const probe of probes) {
     try {