@ngockhoale/ukit 2.2.1 → 2.2.2

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to UKit are documented here.
 
+## 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.2.1",
+  "version": "2.2.2",
   "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/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 {

package/templates/.omp/RULES.md

@@ -1,34 +1,62 @@
 # .omp/RULES.md — sticky always-apply rules
 
 omp re-attaches this file near every turn from its native location (`.omp/RULES.md` only, never a
-copy elsewhere). It carries the always-apply subset of root `CLAUDE.md` that omp's claude provider
-cannot see — that provider only reads `~/.claude/CLAUDE.md` and `<cwd>/.claude/CLAUDE.md`, never root
-`CLAUDE.md`. Keep this short: every line here is a per-turn tax.
+copy elsewhere). It carries the always-apply subset of root `AGENTS.md` that must survive even when
+nothing else is loaded. Keep this short: every line here is a per-turn tax.
 
-## 1. Execution Contract
+## 1. Classify first, then act
+
+- **Trivial** (typo, rename, flag, obvious config) — act directly. No doc reads, no index, no agents.
+- **Simple** (1-2 files, existing pattern) — act directly, pull the smallest useful context.
+- **Non-trivial / risky** (auth, migration, shared runtime, data-loss, flaky) — index-first, then
+  activate the matching skill, then verify.
+
+Pick the lane before the first tool call. Skipping this is what turns a direct chat into a
+scattershot one.
+
+## 2. Execution Contract
 
 For implement/apply/fix requests, continue until the actual edit is made or a real blocker is found.
 Do not stop after a read-only inspection step (read/grep/glob/search).
 
-## 2. No "done" after read-only
+## 3. No "done" after read-only
 
 Never say "done", "applied", or "fixed" after a read-only step. Completion wording requires concrete
 edit/write evidence in the current turn, plus verification when the change is risky.
 
-## 3. Index-first loop
+## 4. Index-first loop
 
 Check `.cache/index/` freshness first. Then run
 `node .claude/ukit/index/query-index.mjs "<error|symbol|path>"` and open only the top 1-3 suspect
 files before widening further. These node scripts work unchanged under omp.
 
-## 4. Safe Patch
+## 5. Auto-activate skills
+
+Skills live in `.claude/skills/` and omp reads them through its `claude` discovery provider — no
+mirror under `.omp/`. On any non-trivial task, and again after the first tool calls reveal what the
+work really is, read the matching `SKILL.md` without being asked. Users never name skills.
+
+## 6. Delegate to bind a model tier
+
+Your own model does not change mid-turn. A tier only applies when work is handed to a task-agent in
+`.omp/agents/`, whose `model:` field (`@lite` / `@code` / `@smart` / `@vision`) resolves through
+`modelRoles` in `.omp/config.yml`.
+
+- `tiny-fix` → `@lite` · `local-fix`, `local-build`, `shared-edit`, `find-cause`, `map-impact` →
+  `@code` · `review-release` → `@smart`
+- Images: `@vision` only. `@code`/`@smart` cannot see images on the UNIC gateway and must never
+  guess at their contents — hand every image to `ukit-vision-analyst` first.
+
+Doing everything inline is exactly what makes UKit look like it only has one model. Keep direct
+execution for trivial/simple work; delegate when the tier differs or when a noisy lane would other-
+wise flood this context.
+
+## 7. Safe Patch
 
 Prefer unique current-file anchors over line numbers or stale pasted blocks. Never silently merge a
 stale spec — re-read current source and confirm before applying. Preserve existing BOM and line
 endings.
 
-## Model roles (see `.omp/config.yml`)
-
-`modelRoles` ships UNIC gateway names as the default. A maintainer on a non-UNIC omp provider edits
-only the three cost-tier values — `lite`, `code`, `smart` — never `vision`, which stays `unic-vision`
-because it is a capability lane, not a cost tier.
+> Maintainer note, not a per-turn rule: `modelRoles` in `.omp/config.yml` ships UNIC gateway names.
+> On a non-UNIC provider, edit only the three cost tiers — `lite`, `code`, `smart` — never `vision`,
+> which stays `unic-vision` because it is a capability lane, not a cost tier.

package/templates/.omp/config.yml

@@ -79,10 +79,12 @@ memory:
 # Auto-compact must trigger BEFORE context-hardcap-gate.sh starts blocking tool
 # calls (compact.hardCapTokens, default 220000). Mirrors the Claude Code value
 # env.CLAUDE_CODE_AUTO_COMPACT_WINDOW = 180000 in templates/.claude/settings.json.
-# TODO(verify): the omp key name below is UNVERIFIED — omp is not installed on the
-# planning machine and no omp schema is vendored in this repo. If it is wrong, omp
-# ignores the unknown key and the session simply compacts later, with
-# context-hardcap-gate.sh + hardCapGraceCalls still acting as the backstop.
-# Degrades to "later, harder compact", never to "no gate". See PLAN.md §3 D13.
-compact:
-  autoCompactWindow: 180000   # TODO(verify) key name against a real omp install
+#
+# Key VERIFIED against omp v17.4.2 (2026-08-22): `compaction.thresholdTokens` is a
+# fixed token limit for context maintenance and overrides the percentage threshold
+# when set; omp's own default is -1 ("use compaction.thresholdPercent"). The key this
+# file shipped with in 2.2.1 — `compact.autoCompactWindow` — was a plan-time guess and
+# omp rejects it outright (`omp config get compact.autoCompactWindow` → "Unknown
+# setting"), so auto-compact never moved off omp's default. See PLAN.md §3 D13.
+compaction:
+  thresholdTokens: 180000

package/templates/.omp/hooks/pre/ukit-bridge.js

@@ -13,11 +13,14 @@
 //   3. Executes each script via `pi.exec()` (never spawns/copies the script
 //      body) and translates the exit code back into an omp-shaped result.
 //
-// omp's own `pi.exec` / `pi.on` argument shapes are UNVERIFIED (omp is not
-// installed in this environment, no source/schema vendored — PLAN.md D7).
-// The internal contract chosen below (see doc comments on each exported
-// function) is a reasonable, internally consistent design; it is exercised
-// end-to-end against a fake `pi` in tests/hooks/ompHookBridge.test.js.
+// Event NAMES are verified against omp v17.4.2 (2026-08-22): its extension API
+// registers `tool_call`, `tool_result`, `turn_start`, `session_start`,
+// `session.compacting` and `session_compact` exactly as spelled below.
+//
+// `pi.exec`'s argument shape is still unverified — the contract chosen below (see
+// the doc comments on each exported function) is internally consistent and is
+// exercised end-to-end against a fake `pi` in tests/hooks/ompHookBridge.test.js,
+// but nothing here has observed omp actually invoking it.
 
 import path from 'node:path';
 
@@ -307,11 +310,13 @@ export async function runSessionCompacting(pi, event, { projectRoot }) {
   return runScriptChain(pi, HOOK_EVENT_MAP['session.compacting'], payload, { projectRoot });
 }
 
-// Must run on EVERY session start, including a post-compact continuation --
-// no "first start only" guard. handoff-resume.sh is idempotent by design
-// (reads + prints the docs/AI_HANDOFF/RUN.md cursor, never advances state),
-// so re-running it on every start is safe and required for the mid-cycle
-// handoff run to resume correctly after a compaction (PLAN.md D11).
+// Claude Code's `SessionStart` entry in settings.json carries NO matcher, so it
+// fires on every source including `compact`. Reaching that same behaviour on omp
+// takes two events, not one -- see runSessionCompact below.
+//
+// handoff-resume.sh is idempotent by design (reads + prints the
+// docs/AI_HANDOFF/RUN.md cursor, never advances state), so running this chain
+// more than once in a session is safe (PLAN.md D11).
 export async function runSessionStart(pi, event, { projectRoot }) {
   const payload = buildHookPayload('SessionStart', {
     sessionId: event.sessionId,
@@ -320,6 +325,32 @@ export async function runSessionStart(pi, event, { projectRoot }) {
   return runScriptChain(pi, HOOK_EVENT_MAP.session_start, payload, { projectRoot });
 }
 
+// RESOLVED 2026-08-22 against a real omp v17.4.2 install. PLAN.md D11 carried this
+// as a `TODO(verify)`: "does omp emit `session_start` on a post-compact
+// continuation?" It does not -- and it does not need to, because omp exposes a
+// dedicated post-compaction event instead. Its extension API registers
+// `session_before_compact` -> `session.compacting` -> `session_compact`, the last
+// firing after compaction settles and carrying the resulting `compactionEntry`.
+//
+// Without this handler the omp side lost the whole post-compact chain: the run
+// cursor stayed un-surfaced, compact pressure was never reset, and a mid-cycle
+// handoff silently failed to resume after a compaction -- the exact failure the
+// plan named. Mapping `session_compact` onto the SAME script chain restores
+// parity with Claude Code's matcher-less SessionStart.
+//
+// The payload keeps `hook_event_name: 'SessionStart'` deliberately: the scripts
+// are shared with Claude Code and know that name, and Claude Code reaches them by
+// the same event with `source: "compact"`. Inventing an omp-only event name here
+// would mean forking the scripts, which is what this bridge exists to avoid.
+export async function runSessionCompact(pi, event, { projectRoot }) {
+  const payload = buildHookPayload('SessionStart', {
+    sessionId: event.sessionId,
+    cwd: event.cwd,
+    source: 'compact',
+  });
+  return runScriptChain(pi, HOOK_EVENT_MAP.session_start, payload, { projectRoot });
+}
+
 // ---------------------------------------------------------------------------
 // Default export -- omp hook factory contract: `export default function
 // hook(pi) { pi.on(event, handler) }`.
@@ -333,4 +364,5 @@ export default function hook(pi) {
   pi.on('turn_start', (event) => runTurnStart(pi, event, { projectRoot }));
   pi.on('session.compacting', (event) => runSessionCompacting(pi, event, { projectRoot }));
   pi.on('session_start', (event) => runSessionStart(pi, event, { projectRoot }));
+  pi.on('session_compact', (event) => runSessionCompact(pi, event, { projectRoot }));
 }

package/templates/AGENTS.md

@@ -1,16 +1,16 @@
 # AGENTS.md — {{project.name}}
 
-## Core UKit Rule
+## Core Rule
 
-- Human-facing workflow should optimize for one remembered command: `ukit install`.
-- After install, normal work should feel natural inside **Claude/Codex/OpenCode/omp**.
-- **Quality first, then speed, then token discipline**: do not waste reads, logs, or repeated helper output.
+- Human-facing UKit workflow should collapse to one remembered command: `ukit install`.
+- After install, default to natural-language work inside **Claude Code / Codex / OpenCode / omp**.
+- **Quality first, then speed, then token discipline.**
 - **Never stop after read-only steps.** For implement/apply/fix requests, continue to actual Edit/Write and verification in the same turn.
 
-## Fast Task Classification
+## Fast Classification
 
-- **Trivial** — typo, label, rename nhỏ, spacing, toggle flag, obvious config change.
-  - Act directly. No doc reads. No planning. No index.
+- **Trivial** — typo, label, small rename, spacing, toggle flag, obvious config change.
+  - Act directly. No doc reads. No planning. No index. No agents.
 - **Simple** — 1-2 files, clear scope, existing pattern.
   - Handle directly. Pull only the smallest useful context via resolver or targeted read.
 - **Non-trivial / Risky** — auth, security, migration, uninstall, shared runtime, race/flaky, data-loss.
@@ -44,11 +44,14 @@ For clearly non-code specialist lanes (docs-only, status, task queue), skip the
 ## Automatic Skill Activation (mandatory)
 
 - End users should not need to know skill names.
-- For every non-trivial task — and again after the first relevant tool calls — inspect installed project-local skills and **auto-activate the matching skill immediately**.
+- On every non-trivial task — and again after the first relevant tool calls — inspect installed project-local skills and **auto-activate the matching skill immediately**.
 - Match from both prompt wording and tool/file evidence.
 - Use the smallest effective set, usually 1-2 skills.
 - If evidence becomes more specific than the original prompt, upgrade the active skill choice immediately.
-- Prefer routed, compact context before widening manual reads.
+- If docs work is detected, read `.claude/skills/docs-quality/SKILL.md` when present.
+- Prefer routed context and routed verification over ad-hoc broad reading.
+- Reuse `.claude/ukit/skill-router-state.json` when it already carries compact route memory.
+- If shared route state already includes `previous-context` or `recent-output`, reuse those first.
 
 ### Common skill triggers
 
@@ -61,51 +64,65 @@ For clearly non-code specialist lanes (docs-only, status, task queue), skip the
 - auth / security / token / permission / validation / risky shell-path-delete-db work → `.claude/skills/discover-security/SKILL.md`
 - stale workspace / reinstall / cleanup / maintenance → `.claude/skills/repo-maintenance/SKILL.md`
 
-## Internal Helper Routing
+## Internal Helper Policy
 
-- If routing is complex or ambiguous, prefer the canonical helper first: `node .claude/ukit/index/route-task.mjs "<prompt>" [--tool-command <cmd>] [--target <file>]`.
-- If context is needed, prefer `node .claude/ukit/index/resolve-context.mjs ...`.
-- If a concrete verification lane is needed, prefer `node .claude/ukit/index/verify-context.mjs ...`.
-- These helper/index commands are internal orchestration. Run them yourself when needed; never turn them into required end-user workflow.
+- Prefer `node .claude/ukit/index/route-task.mjs "<prompt>" [--tool-command <cmd>] [--target <file>]` when routing is complex or ambiguous.
+- Prefer `node .claude/ukit/index/resolve-context.mjs ...` for indexed related-file context.
+- Prefer `node .claude/ukit/index/verify-context.mjs ...` for concrete verification lanes.
+- **Do not ask normal contributors to run internal helper commands**; run them yourself or tell them to rerun `ukit install`.
+- Do not ask normal contributors to memorize `ukit doctor`, `ukit diff`, `ukit uninstall`, or `ukit index ...` unless they explicitly need maintainer/debug help.
+- If the workspace needs a refresh, prefer telling them to rerun `ukit install`.
+
+## Skill Quality (maintainer-only)
+
+- When editing a template skill/agent under `templates/.claude/`, read `.claude/skills/skill-quality/SKILL.md` before shipping the change.
 
-## UKit v1.5.1 Shared Runtime
+## UKit v{{ukit.version}} Shared Runtime
 
 - Shared runtime state lives in `.ukit/storage/`.
 - Treat `.ukit/storage/config.json` as the source of runtime toggles for compact, token pipeline, router, memory, validation, and Safe Patch behavior.
-- Reuse `.ukit/storage/memory/` before asking users to restate prior decisions.
+- Reuse `.ukit/storage/memory/` before asking users to restate decisions.
 - For non-trivial work, prefer `ukit memory recall "<current task>"` before widening doc reads.
-- Reusable runtime cache lives in `.ukit/storage/cache/prompt-cache.json`, `.ukit/storage/cache/compact-history.json`, `.ukit/storage/cache/compact-pressure.json`, `.ukit/storage/cache/output-history.json`, and preserved raw tool outputs under `.ukit/storage/cache/tee/`.
+- Reusable cache/compact/output state lives in `.ukit/storage/cache/prompt-cache.json`, `.ukit/storage/cache/compact-history.json`, `.ukit/storage/cache/compact-pressure.json`, `.ukit/storage/cache/output-history.json`, and preserved raw tool outputs under `.ukit/storage/cache/tee/`.
 - Shared route memory lives in `.claude/ukit/skill-router-state.json`.
-- If shared route state already includes compact `previous-context` or `recent-output` lines, reuse those first before rescanning memory or replaying noisy logs.
+- If shared route state already includes compact `previous-context` or `recent-output`, reuse those first.
 - If an older repo still has a visible `ukit/` runtime root, rerun `ukit install`; UKit should migrate the shared runtime into hidden `.ukit/` when safe.
 - Maintainers can inspect runtime state with `ukit status` and `ukit memory export`, but normal teammates should still only need `ukit install`.
-- If runtime files are missing/corrupt, tell maintainers to rerun `ukit install`.
+- If runtime files are missing or corrupt, tell maintainers to rerun `ukit install`.
 - Threshold-based compact pressure is internal orchestration; do not expose it to users.
 - For Codex Desktop long sessions, UKit can use soft auto-compact handoffs. Default `compact.codexContext.compactTarget=150` means about 150 compact handoff lines (120-150 preferred, hard max 170), not 150 tokens.
 
-## Handoff Quality Gate — OPT-IN
+## Safe Patch Protocol
+
+- Safe Patch is internal orchestration: normal users still only need `ukit install` and natural language.
+- For risky/shared/large edits, prefer unique current-file anchors over line numbers or stale pasted blocks.
+- Do not silently merge stale specs: if `old_string` is missing or ambiguous, re-read current source and ask whether to apply as-is, adapt, or skip.
+- Preserve UTF-8 BOM/no-BOM and LF/CRLF for existing multilingual/user-authored files.
+- Use `node .claude/ukit/index/safe-patch.mjs` internally when normal Edit/Write may normalize bytes or when anchor-based matching is needed.
 
-Activates ONLY when work goes through `docs/AI_HANDOFF/` (user says "execute task TASK-xxx" or target is `docs/AI_HANDOFF/tasks/*.md`). Daily prompts → unchanged lightweight flow, no test-first/reviewer overhead.
+## Handoff Quality Gate — OPT-IN
 
-In Handoff mode: read `docs/AI_HANDOFF/RULES.md` for the 4-phase spec (Idea+Plan → Create Tasks → Implement+Test → Review+Test), state machine, comment thread, and self-reported model contract. Config: `.ukit/storage/config.json` → `handoff.*`.
+CHỈ kích hoạt khi task đi qua `docs/AI_HANDOFF/` (user nói "execute task TASK-xxx" hoặc target là `docs/AI_HANDOFF/tasks/*.md`). Daily prompt → KHÔNG đụng, flow cũ giữ nguyên.
 
+Khi Handoff mode: đọc `docs/AI_HANDOFF/RULES.md` để biết 4 phase (Idea+Plan → Create Tasks → Implement+Test → Review+Test) + state machine + comment thread + self-report model. Config: `.ukit/storage/config.json` → `handoff.*`.
 
 ## Context + Verification Budget
 
-- **Trivial**: no docs, no index query unless the file target is unclear.
-- **Simple**: default to `docs/MEMORY.md` only; pull related files/tests with the resolver.
-- **Non-trivial**: read `docs/MEMORY.md` + `docs/PROJECT.md` + `docs/CODE_MAP.md`.
-- `docs/STATUS.md`: read for open-ended status/continue prompts or meaningful continuation context; treat stale status as orientation only and verify against source/index.
-- `docs/TASKS.md`: read only for queued-task prompts or when status points at queued work; safely clean exact duplicates/completed overflow by default without deleting unfinished human-authored tasks.
-- `docs/WORKLOG.md`: only recent, relevant entries for continuation/debugging.
-- Follow routed verification policy: targeted first when localized, widen in order for shared/risky scope, ask before blanket broad runs when no related-test evidence exists.
+- **Trivial**: no docs, and no index query unless the file target is unclear.
+- **Simple**: `docs/MEMORY.md` only, plus resolver-selected files/tests.
+- **Non-trivial**: `docs/MEMORY.md` + `docs/PROJECT.md` + `docs/CODE_MAP.md`.
+- `docs/STATUS.md`: use for open-ended status/continue prompts or meaningful continuation context; stale status is orientation only.
+- `docs/TASKS.md`: use only for queued-task prompts or when status points at queued work; safely clean exact duplicates/completed overflow by default without deleting unfinished human-authored tasks.
+- `docs/WORKLOG.md`: only recent relevant entries. Follow the Budget Rules at the top of the file; archive oldest entries to `docs/WORKLOG_ARCHIVE.md` when over limits.
+- Follow routed verification policy: targeted first, widen only when risk/shared scope justifies it, ask before blanket broad runs.
 
 ## Living Status Workflow
 
-- `docs/STATUS.md` is compact current state, not a transcript and not source truth.
-- When the user asks "what next?", "continue", or "project đang ở đâu?" without a concrete target, use the `next-step` skill and show a freshness cue (fresh / possibly stale / stale / missing).
-- Concrete debug/implementation/review prompts beat open-ended wording; use the concrete skill first and only use status as background.
-- After meaningful work, use `update-status` to record state, verification, blockers, and next candidates; skip trivial/no-state-change tasks.
+- `docs/STATUS.md` captures compact current state, active work, debug threads, blockers, verification, and next candidates.
+- It is not source truth and must not replace source/index-first investigation.
+- For "what next?" / "continue" prompts without a concrete target, use `next-step` and show a freshness cue before relying on the status file.
+- For concrete debug/implementation/review prompts, keep the concrete workflow primary even if the user asks for an approach or next step.
+- After meaningful work, use `update-status`; skip trivial/no-state-change tasks and avoid transcript-style noise.
 - `docs/TASKS.md` is a local AI task queue: prefer `Ready for AI` when asked to pick queued work, and clean duplicates/prune `Done Recently` safely when reading/updating it.
 
 ## Small-Task Maintainer (internal)
@@ -117,36 +134,78 @@ In Handoff mode: read `docs/AI_HANDOFF/RULES.md` for the 4-phase spec (Idea+Plan
 - This is optional internal orchestration config from `.ukit/storage/config.json`; never turn it into an end-user workflow.
 - Always preserve the CoDev priority: quality > safety > speed > token discipline.
 
-## Subagent Policy (internal only)
+## Post-Edit Sidecar Review (internal)
 
-- Default to direct execution for trivial/simple work.
-- Delegate only when it clearly reduces context bloat or enables useful parallel progress.
+- If routed state's `routeSummary.line` includes a `review=code-reviewer(diff)` segment, a `local-build` or `shared-edit` task qualifies for a non-blocking second opinion — this exists because the daily-flow executor model can miss edge cases.
+- Only launch it once write evidence AND verification evidence already exist for the task (never before; never as a substitute for either).
+- Launch the `code-reviewer` agent (see the harness table under 3-Tier Model Routing) with `REVIEW_TARGET_TYPE=diff`, in the background, on the `smart` tier per `subagents.diffReviewModel`. Do not wait for it — continue and report the task as done using the normal completion rules.
+- Its findings are advisory only: never re-open, block, or delay the already-reported completion on their account. Surface them to the user as a follow-up note if/when they arrive.
+- This is internal orchestration — end users never invoke it directly; `ukit install` plus natural language remains the whole surface. No new commands.
+
+## Selective Subagent Policy (internal only)
+
+- Keep direct execution as the default for trivial/simple work.
+- Delegate only when it meaningfully shrinks context or enables useful parallel progress.
 - Good delegation triggers:
   - noisy side lanes (broad logs/search/test output)
   - 3+ independent failures/files/checks
   - explicit batch/plan execution
   - broad implementation/debug lanes that can return a concise summary
-- If route memory already includes `delegate=<lane>`, treat it as an internal hint after any required indexed-context step.
+- If route memory includes `delegate=<lane>`, treat it as an internal hint after any required indexed-context step.
 - Do not ask end users to name agents or remember agent commands.
 
-## Safe Patch Protocol
+## Adaptive Autonomy
 
-- Safe Patch is internal orchestration: normal users still only need `ukit install` and natural language.
-- For risky/shared/large edits, prefer unique current-file anchors over line numbers or stale pasted blocks.
-- Do not silently merge stale specs: if `old_string` is missing or ambiguous, re-read current source and ask whether to apply as-is, adapt, or skip.
-- Preserve UTF-8 BOM/no-BOM and LF/CRLF for existing multilingual/user-authored files.
-- Use `node .claude/ukit/index/safe-patch.mjs` internally when normal Edit/Write may normalize bytes or when anchor-based matching is needed.
+- `autonomy.level` in `.ukit/storage/config.json` controls how much UKit acts without asking first: `conservative` (ask more), `balanced` (default), `free-run` (auto-run more).
+- End users should not need to change this; maintainers may tune it per-project.
 
-## Team Workflow Safety
+## 3-Tier Model Routing
 
-- Do not teach normal contributors `ukit doctor`, `ukit diff`, `ukit uninstall`, or `ukit index ...` unless they are explicitly debugging UKit itself.
-- If the workspace needs a refresh, prefer telling them to rerun `ukit install`.
-- Keep scope tight, prefer the smallest correct change set, reuse existing code, and update docs when source changes.
+**Internal orchestration only — end users still just use natural language. No new commands.**
 
-## Adaptive Autonomy
+UKit routes tasks to one of three model tiers based on task complexity:
 
-- `autonomy.level` in `.ukit/storage/config.json` controls how much UKit acts without asking first: `conservative` (ask more), `balanced` (default), `free-run` (auto-run more).
-- End users should not need to change this; maintainers may tune it per-project.
+| Tier | Generic alias | Claude model | Typical tasks |
+|------|--------------|--------------|---------------|
+| lite | `unic-lite` | claude-haiku | Reads, git queries, bash summaries, small doc edits |
+| code | `unic-code` | claude-sonnet | Normal coding, local fixes, shared edits, builds, debugging, impact mapping |
+| smart | `unic-smart` | claude-opus | Release review/audit, and escalated deep reasoning after repeated failure |
+
+### Contract-to-tier mapping
+
+| Contract | Tier |
+|----------|------|
+| `tiny-fix` | lite |
+| `local-fix`, `local-build`, `shared-edit`, `find-cause`, `map-impact` | code |
+| `review-release` | smart |
+
+### How a tier is actually bound
+
+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:
+
+| Harness | Agent definitions | How to launch one |
+|---------|-------------------|-------------------|
+| Claude Code | `.claude/agents/*.md` (`model:` frontmatter) | Agent tool, `subagent_type: "<name>"` |
+| omp | `.omp/agents/*.md` (`model: "@lite"` / `"@code"` / `"@smart"` / `"@vision"`, resolved through `modelRoles` in `.omp/config.yml`) | task-agent `<name>` |
+
+When a task's contract maps to a tier other than the current session model, hand it to the
+matching agent instead of doing it inline. Doing everything inline is exactly what makes UKit
+behave as if it only had one model — the tier table above has no effect on its own.
+
+### Escalation rule
+
+When the same file or symbol fails `debugLoopThreshold` (default: 2) times in one session, UKit routes the next attempt one tier higher (capped at `smart`). Config: `orchestration.escalation` in `.ukit/storage/config.json`.
+
+This is internal orchestration — end users do not need to know about tiers, thresholds, or escalation. The AI handles routing transparently.
+
+### Vision lane (capability, not a cost tier)
+
+`unic-vision` is a **capability lane**, not a fourth cost tier — it is orthogonal to lite/code/smart above and never appears as a row in the tier table. `unic-code` and `unic-smart` cannot read images on the UNIC gateway; they must never guess at image contents.
+
+- **Gateway detection**: UNIC routing for a Claude Code session is decided ONLY by what changes Claude Code's own outbound endpoint — `ANTHROPIC_BASE_URL` (env var, or the `env.ANTHROPIC_BASE_URL` key in project/home `.claude/settings.json`) containing `unicjsc.com`. Other tools' configs — Codex `config.toml`, Kilo `secrets.json`, or an `OPENAI_BASE_URL` env var — describe a different tool's endpoint entirely and never decide this session's routing.
+- **Enforcement**: every image (pasted, local file path, or URL) must be analysed by the `ukit-vision-analyst` agent running on the vision lane before any related edit happens. `Edit`/`Write` are **hard-blocked** until an analysis receipt exists for every pending image; `Read`/`Grep`/`Glob`/`Bash` stay unblocked so the analyst itself can see the image and write its receipt.
+- This is internal orchestration — end users never invoke a vision command directly; `ukit install` plus natural language remains the whole surface. No new commands.
 
 ## Session Start — OpenCode
 
@@ -155,35 +214,43 @@ At the start of every OpenCode session, before working on the first task:
 2. Note which skills are installed by scanning `.claude/skills/` (directory listing only); read the full SKILL.md only when a task triggers it.
 3. For every non-trivial task: run `/ukit-route <task summary>` immediately to get skill + context hints **before** writing any code.
 4. If the route result points to a skill, read that SKILL.md before acting — do not skip this step.
-5. If `.ukit/storage/config.json` has `router.enabled: true`, prefer the router's output over ad-hoc guessing.
-
-## Environment Snapshot
-
-- Project name: {{project.name}}
-- Detected packs: {{project.stack}}
-- Frontend detected: {{stack.frontend}}
-- Backend API detected: {{stack.backendApi}}
-- PostgreSQL detected: {{stack.postgres}}
-- Package manager: {{runtime.packageManager}}
+5. If `.ukit/storage/config.json` has `router.enabled: true`, prefer the router output over ad-hoc guessing.
 
 ## Skills
 
 - Canonical skills live in `.claude/skills/`.
 - Adapter mirrors may also exist, for example `.codex/skills/` → `.claude/skills/` (symlink). **omp** has no mirror: it reads `.claude/skills/` directly through its own `claude` discovery provider.
-- **OpenCode**: reads `AGENTS.md` at session start only — it does NOT auto-load `.claude/skills/`. The model must explicitly read the triggered SKILL.md (see Session Start section above).
+- **OpenCode**: reads `AGENTS.md` at session start only — it does NOT auto-load `.claude/skills/`. The model must explicitly read the triggered SKILL.md.
 - If `opencode.json` ships `ukit-*` commands, treat them as internal helper entrypoints only and **never ask end users to run them**; humans should still only need `ukit install`.
 
+## Project Snapshot
+
+- Project: {{project.name}} | Root: {{project.root}}
+- Packs: {{project.stack}} | Frontend: {{stack.frontend}} | Backend API: {{stack.backendApi}} | PostgreSQL: {{stack.postgres}}
+- Package manager: {{runtime.packageManager}} | OS: {{runtime.os}} | Node: {{runtime.nodeVersion}} | Provider: {{providers.unic}}
+
+## Working Rules
+
+- Keep scope tight, prefer the smallest correct change set, and reuse existing code.
+- For explicit implement/apply/fix requests, keep working until the actual edit is made or a real blocker is found; do not stop after a read-only inspection step.
+- If routed state still says `pull-indexed-context`, treat it as an internal continuation step, not a stopping point.
+- If routed state shows `continuation required` or a stuck-lane rescue mode, finish the named milestone before widening reads or rephrasing the same partial status.
+- Never claim "done", "applied", or "fixed" after Read/Grep/analysis alone. Completion language requires concrete Edit/Write evidence in the current turn, plus verification when the change is risky.
+- Update `docs/WORKLOG.md` after significant work.
+- If source contradicts docs, update docs immediately.
+- Use `{{runtime.packageManager}}`.
+
 ## DuraOne Skill — Conditional Activation
 
 DuraOne skill chỉ active khi pack `duraone` được cài hoặc `.claude/skills/duraone/SKILL.md` tồn tại.
 
-- Khi active: đọc `.claude/skills/duraone/SKILL.md` trước khi code.
+- Khi active: luôn đọc `.claude/skills/duraone/SKILL.md` trước khi code.
 - References:
   - `.claude/skills/duraone/references/frontend.md`
   - `.claude/skills/duraone/references/backend.md`
   - `.claude/skills/duraone/references/sql.md`
   - `.claude/skills/duraone/references/workflow.md`
-- Khi không active: dùng generic coding standards + project patterns từ index.
+- Khi không active: dùng generic coding standards + project-specific patterns từ index.
 
 ## Completion Checklist
 
@@ -191,3 +258,4 @@ DuraOne skill chỉ active khi pack `duraone` được cài hoặc `.claude/skil
 - No unrelated changes
 - Verification executed and reported
 - Docs updated when source truth changed
+{{codegraphSection}}

package/templates/CLAUDE.md

@@ -3,15 +3,19 @@
 ## Core Rule
 
 - Human-facing UKit workflow should collapse to one remembered command: `ukit install`.
-- After install, default to natural-language work inside Claude/Codex.
+- After install, default to natural-language work inside **Claude Code / Codex / OpenCode / omp**.
 - **Quality first, then speed, then token discipline.**
 - **Never stop after read-only steps.** For implement/apply/fix requests, continue to actual Edit/Write and verification in the same turn.
 
 ## Fast Classification
 
-- **Trivial**: act directly, no doc reads, no agents.
-- **Simple**: keep scope tight; use the smallest useful context.
-- **Non-trivial / Risky**: read deeper, verify harder, and avoid shortcuts.
+- **Trivial** — typo, label, small rename, spacing, toggle flag, obvious config change.
+  - Act directly. No doc reads. No planning. No index. No agents.
+- **Simple** — 1-2 files, clear scope, existing pattern.
+  - Handle directly. Pull only the smallest useful context via resolver or targeted read.
+- **Non-trivial / Risky** — auth, security, migration, uninstall, shared runtime, race/flaky, data-loss.
+  - Read deeper, verify harder, and avoid shortcuts.
+  - Use index-first loop, then skill activation, then targeted verification.
 
 ## Execution Contract (mandatory)
 
@@ -33,6 +37,7 @@ For any task that needs code context:
 3. For bug signatures:
    - `node .claude/ukit/index/triage.mjs "<error signature>"`
 4. Open only the **top 1-3 suspect files first**, then widen if needed.
+5. For analog/reuse patterns, check if `resolve-context` returns related existing patterns.
 
 For clearly non-code specialist lanes (docs-only, status, task queue), skip the source-code index.
 
@@ -40,8 +45,9 @@ For clearly non-code specialist lanes (docs-only, status, task queue), skip the
 
 - End users should not need to know skill names.
 - On every non-trivial task — and again after the first relevant tool calls — inspect installed project-local skills and **auto-activate the matching skill immediately**.
-- Match from prompt signals plus tool/file evidence.
-- Use the smallest useful set.
+- Match from both prompt wording and tool/file evidence.
+- Use the smallest effective set, usually 1-2 skills.
+- If evidence becomes more specific than the original prompt, upgrade the active skill choice immediately.
 - If docs work is detected, read `.claude/skills/docs-quality/SKILL.md` when present.
 - Prefer routed context and routed verification over ad-hoc broad reading.
 - Reuse `.claude/ukit/skill-router-state.json` when it already carries compact route memory.
@@ -49,22 +55,23 @@ For clearly non-code specialist lanes (docs-only, status, task queue), skip the
 
 ### Common skill triggers
 
-- review / audit / diff → `.claude/skills/code-review/SKILL.md`
-- bug / error / crash / triage → `.claude/skills/debugging-toolkit/SKILL.md`
-- test / spec / coverage → `.claude/skills/testing-quality/SKILL.md`
+- review / audit / diff / PR feedback → `.claude/skills/code-review/SKILL.md`
+- bug / error / crash / triage / failing path → `.claude/skills/debugging-toolkit/SKILL.md`
+- test / spec / coverage / fixture → `.claude/skills/testing-quality/SKILL.md`
 - docs / README / changelog / handoff / editing `docs/` / cleaning `docs/TASKS.md` → `.claude/skills/docs-quality/SKILL.md`
 - open-ended next step / project status / continue with no concrete target / choose queued task → `.claude/skills/next-step/SKILL.md`
 - explicit handoff / wrap up / update `docs/STATUS.md` → `.claude/skills/update-status/SKILL.md`
-- auth / security / token / permission / validation → `.claude/skills/discover-security/SKILL.md`
-- stale workspace / reinstall / cleanup → `.claude/skills/repo-maintenance/SKILL.md`
+- auth / security / token / permission / validation / risky shell-path-delete-db work → `.claude/skills/discover-security/SKILL.md`
+- stale workspace / reinstall / cleanup / maintenance → `.claude/skills/repo-maintenance/SKILL.md`
 
 ## Internal Helper Policy
 
-- Prefer `node .claude/ukit/index/route-task.mjs ...` when routing is complex.
+- Prefer `node .claude/ukit/index/route-task.mjs "<prompt>" [--tool-command <cmd>] [--target <file>]` when routing is complex or ambiguous.
 - Prefer `node .claude/ukit/index/resolve-context.mjs ...` for indexed related-file context.
 - Prefer `node .claude/ukit/index/verify-context.mjs ...` for concrete verification lanes.
 - **Do not ask normal contributors to run internal helper commands**; run them yourself or tell them to rerun `ukit install`.
 - Do not ask normal contributors to memorize `ukit doctor`, `ukit diff`, `ukit uninstall`, or `ukit index ...` unless they explicitly need maintainer/debug help.
+- If the workspace needs a refresh, prefer telling them to rerun `ukit install`.
 
 ## Skill Quality (maintainer-only)
 
@@ -76,11 +83,11 @@ For clearly non-code specialist lanes (docs-only, status, task queue), skip the
 - Treat `.ukit/storage/config.json` as the source of runtime toggles for compact, token pipeline, router, memory, validation, and Safe Patch behavior.
 - Reuse `.ukit/storage/memory/` before asking users to restate decisions.
 - For non-trivial work, prefer `ukit memory recall "<current task>"` before widening doc reads.
-- Reusable cache/compact/output state lives in `.ukit/storage/cache/prompt-cache.json`, `.ukit/storage/cache/compact-history.json`, `.ukit/storage/cache/compact-pressure.json`, and `.ukit/storage/cache/output-history.json`.
+- Reusable cache/compact/output state lives in `.ukit/storage/cache/prompt-cache.json`, `.ukit/storage/cache/compact-history.json`, `.ukit/storage/cache/compact-pressure.json`, `.ukit/storage/cache/output-history.json`, and preserved raw tool outputs under `.ukit/storage/cache/tee/`.
 - Shared route memory lives in `.claude/ukit/skill-router-state.json`.
 - If shared route state already includes compact `previous-context` or `recent-output`, reuse those first.
 - If an older repo still has a visible `ukit/` runtime root, rerun `ukit install`; UKit should migrate the shared runtime into hidden `.ukit/` when safe.
-- Maintainers can inspect runtime state with `ukit status` and `ukit memory export`.
+- Maintainers can inspect runtime state with `ukit status` and `ukit memory export`, but normal teammates should still only need `ukit install`.
 - If runtime files are missing or corrupt, tell maintainers to rerun `ukit install`.
 - Threshold-based compact pressure is internal orchestration; do not expose it to users.
 - For Codex Desktop long sessions, UKit can use soft auto-compact handoffs. Default `compact.codexContext.compactTarget=150` means about 150 compact handoff lines (120-150 preferred, hard max 170), not 150 tokens.
@@ -99,10 +106,9 @@ CHỈ kích hoạt khi task đi qua `docs/AI_HANDOFF/` (user nói "execute task
 
 Khi Handoff mode: đọc `docs/AI_HANDOFF/RULES.md` để biết 4 phase (Idea+Plan → Create Tasks → Implement+Test → Review+Test) + state machine + comment thread + self-report model. Config: `.ukit/storage/config.json` → `handoff.*`.
 
-
 ## Context + Verification Budget
 
-- **Trivial**: no docs.
+- **Trivial**: no docs, and no index query unless the file target is unclear.
 - **Simple**: `docs/MEMORY.md` only, plus resolver-selected files/tests.
 - **Non-trivial**: `docs/MEMORY.md` + `docs/PROJECT.md` + `docs/CODE_MAP.md`.
 - `docs/STATUS.md`: use for open-ended status/continue prompts or meaningful continuation context; stale status is orientation only.
@@ -132,7 +138,7 @@ Khi Handoff mode: đọc `docs/AI_HANDOFF/RULES.md` để biết 4 phase (Idea+P
 
 - If routed state's `routeSummary.line` includes a `review=code-reviewer(diff)` segment, a `local-build` or `shared-edit` task qualifies for a non-blocking second opinion — this exists because the daily-flow executor model can miss edge cases.
 - Only launch it once write evidence AND verification evidence already exist for the task (never before; never as a substitute for either).
-- Launch the `code-reviewer` agent via the Agent tool with `REVIEW_TARGET_TYPE=diff` and `run_in_background: true` (model `unic-smart` per `subagents.diffReviewModel`). Do not wait for it — continue and report the task as done using the normal completion rules.
+- Launch the `code-reviewer` agent (see the harness table under 3-Tier Model Routing) with `REVIEW_TARGET_TYPE=diff`, in the background, on the `smart` tier per `subagents.diffReviewModel`. Do not wait for it — continue and report the task as done using the normal completion rules.
 - Its findings are advisory only: never re-open, block, or delay the already-reported completion on their account. Surface them to the user as a follow-up note if/when they arrive.
 - This is internal orchestration — end users never invoke it directly; `ukit install` plus natural language remains the whole surface. No new commands.
 
@@ -140,8 +146,13 @@ Khi Handoff mode: đọc `docs/AI_HANDOFF/RULES.md` để biết 4 phase (Idea+P
 
 - Keep direct execution as the default for trivial/simple work.
 - Delegate only when it meaningfully shrinks context or enables useful parallel progress.
-- Good delegation triggers: noisy research/log lanes, 3+ independent failures, explicit batch execution, or a broad debug/implementation lane with a clean handoff.
+- Good delegation triggers:
+  - noisy side lanes (broad logs/search/test output)
+  - 3+ independent failures/files/checks
+  - explicit batch/plan execution
+  - broad implementation/debug lanes that can return a concise summary
 - If route memory includes `delegate=<lane>`, treat it as an internal hint after any required indexed-context step.
+- Do not ask end users to name agents or remember agent commands.
 
 ## Adaptive Autonomy
 
@@ -168,6 +179,20 @@ UKit routes tasks to one of three model tiers based on task complexity:
 | `local-fix`, `local-build`, `shared-edit`, `find-cause`, `map-impact` | code |
 | `review-release` | smart |
 
+### How a tier is actually bound
+
+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:
+
+| Harness | Agent definitions | How to launch one |
+|---------|-------------------|-------------------|
+| Claude Code | `.claude/agents/*.md` (`model:` frontmatter) | Agent tool, `subagent_type: "<name>"` |
+| omp | `.omp/agents/*.md` (`model: "@lite"` / `"@code"` / `"@smart"` / `"@vision"`, resolved through `modelRoles` in `.omp/config.yml`) | task-agent `<name>` |
+
+When a task's contract maps to a tier other than the current session model, hand it to the
+matching agent instead of doing it inline. Doing everything inline is exactly what makes UKit
+behave as if it only had one model — the tier table above has no effect on its own.
+
 ### Escalation rule
 
 When the same file or symbol fails `debugLoopThreshold` (default: 2) times in one session, UKit routes the next attempt one tier higher (capped at `smart`). Config: `orchestration.escalation` in `.ukit/storage/config.json`.
@@ -179,9 +204,16 @@ This is internal orchestration — end users do not need to know about tiers, th
 `unic-vision` is a **capability lane**, not a fourth cost tier — it is orthogonal to lite/code/smart above and never appears as a row in the tier table. `unic-code` and `unic-smart` cannot read images on the UNIC gateway; they must never guess at image contents.
 
 - **Gateway detection**: UNIC routing for a Claude Code session is decided ONLY by what changes Claude Code's own outbound endpoint — `ANTHROPIC_BASE_URL` (env var, or the `env.ANTHROPIC_BASE_URL` key in project/home `.claude/settings.json`) containing `unicjsc.com`. Other tools' configs — Codex `config.toml`, Kilo `secrets.json`, or an `OPENAI_BASE_URL` env var — describe a different tool's endpoint entirely and never decide this session's routing.
-- **Enforcement**: every image (pasted, local file path, or URL) must be analysed by the `ukit-vision-analyst` agent running on `unic-vision` before any related edit happens. `Edit`/`Write` are **hard-blocked** until an analysis receipt exists for every pending image; `Read`/`Grep`/`Glob`/`Bash` stay unblocked so the analyst itself can see the image and write its receipt.
+- **Enforcement**: every image (pasted, local file path, or URL) must be analysed by the `ukit-vision-analyst` agent running on the vision lane before any related edit happens. `Edit`/`Write` are **hard-blocked** until an analysis receipt exists for every pending image; `Read`/`Grep`/`Glob`/`Bash` stay unblocked so the analyst itself can see the image and write its receipt.
 - This is internal orchestration — end users never invoke a vision command directly; `ukit install` plus natural language remains the whole surface. No new commands.
 
+## Skills
+
+- Canonical skills live in `.claude/skills/`.
+- Adapter mirrors may also exist, for example `.codex/skills/` → `.claude/skills/` (symlink). **omp** has no mirror: it reads `.claude/skills/` directly through its own `claude` discovery provider.
+- **OpenCode**: reads `AGENTS.md` at session start only — it does NOT auto-load `.claude/skills/`. The model must explicitly read the triggered SKILL.md.
+- If `opencode.json` ships `ukit-*` commands, treat them as internal helper entrypoints only and **never ask end users to run them**; humans should still only need `ukit install`.
+
 ## Project Snapshot
 
 - Project: {{project.name}} | Root: {{project.root}}
@@ -190,8 +222,7 @@ This is internal orchestration — end users do not need to know about tiers, th
 
 ## Working Rules
 
-- Keep scope tight.
-- Reuse existing code.
+- Keep scope tight, prefer the smallest correct change set, and reuse existing code.
 - For explicit implement/apply/fix requests, keep working until the actual edit is made or a real blocker is found; do not stop after a read-only inspection step.
 - If routed state still says `pull-indexed-context`, treat it as an internal continuation step, not a stopping point.
 - If routed state shows `continuation required` or a stuck-lane rescue mode, finish the named milestone before widening reads or rephrasing the same partial status.
@@ -211,4 +242,11 @@ DuraOne skill chỉ active khi pack `duraone` được cài hoặc `.claude/skil
   - `.claude/skills/duraone/references/sql.md`
   - `.claude/skills/duraone/references/workflow.md`
 - Khi không active: dùng generic coding standards + project-specific patterns từ index.
+
+## Completion Checklist
+
+- Requirements implemented
+- No unrelated changes
+- Verification executed and reported
+- Docs updated when source truth changed
 {{codegraphSection}}