@ngockhoale/ukit 1.6.3 → 1.6.5

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to UKit are documented here.
 
+## 1.6.5 - 2026-08-02
+
+### Added
+
+- **Enforced `unic-vision` image lane.** Images are now mechanically routed to a vision-capable model instead of being guessed at by `unic-code`/`unic-smart`, which cannot read images on the UNIC gateway.
+  - `.claude/ukit/index/extract-image.mjs` — decodes pasted images out of the session transcript to disk (a spawned subagent receives text only and does not inherit image blocks), and writes content-addressed `pending-<sha>.json` markers. Single owner of the sha256; both the marker and the image filename come from the same hash.
+  - `.claude/hooks/vision-router.sh` (`UserPromptSubmit`) — detects all three input forms (pasted, local path, image URL) and arms a marker for each. Fails OPEN: a failure here degrades to no hint and no markers, never a wedged prompt.
+  - `.claude/hooks/vision-gate.sh` (`PreToolUse`, `Edit|Write` only) — hard-blocks the write (exit 2) until an `analyzed-<sha>.json` receipt exists whose self-reported model is vision-capable. A receipt from `unic-code`, `unic-smart`, `sonnet`, or `opus` is treated as ABSENT and still blocks. Fails CLOSED, and gateway detection that is missing or broken DENIES the fallback-model exception rather than granting it. `Read`/`Grep`/`Glob`/`Bash` are never gated — the vision analyst needs them to clear the gate.
+  - `ukit-vision-analyst` agent — pinned to `unic-vision`, the only lane permitted to interpret images. Reports findings only; it has no `Edit`/`Write`.
+  - `.claude/ukit/index/unic-gateway.mjs` — detects a `unicjsc.com` gateway across Claude Code env, Codex config, Kilo config, and `OPENAI_BASE_URL`. Only ever tests for substring presence; never reads credential file contents into output.
+
+### Changed
+
+- `orchestration.escalation` now has real consumers. `route-task.mjs` reads `debugLoopThreshold`, `tierOrder`, and `cap` from config instead of hardcoded literals, and emits `escalatedTier` alongside `modelTier` — one rung up, capped at `smart`. The same literals remain as fallbacks, so projects that never opted in behave identically.
+- `orchestration.modelTiers` documents all four UNIC models. `vision` is a capability lane orthogonal to the lite/code/smart cost tiers, never a fourth tier, and is stripped from any configured `tierOrder`.
+- `handoff-model-guard.sh`: `tierOf()` hardened against vision/unknown model names.
+
+## 1.6.4 - 2026-07-27
+
+### Added
+
+- Hard enforcement of the handoff model-tier contract via a new `PreToolUse` hook (`.claude/hooks/handoff-model-guard.sh`), registered for both `Edit|Write` and `Bash`. Previously the plan=opus / implement=sonnet / review=opus split was only a prompt convention the orchestrating model could silently skip.
+  - Blocks writing `docs/AI_HANDOFF/PLAN.md` unless it declares a smart-tier `PLANNER_MODEL` in a new mandatory `## Planner Report` footer.
+  - Blocks creating a fresh `TASK-xxx.md` until `PLAN.md` has a valid smart-tier `PLANNER_MODEL`.
+  - Blocks writing `## Executor Report` unless `EXECUTOR_MODEL` is present and not lite-tier.
+  - Blocks writing `## Reviewer Verdict` unless `REVIEWER_MODEL` is smart-tier and differs from `EXECUTOR_MODEL`.
+  - Blocks `git push` when any reviewed task in the active cycle violates the contract.
+  - Applies identically to the standalone `/ukit:handoff-create`, `/ukit:handoff-implement`, `/ukit:handoff-review` commands and the combined `/ukit:handoff-fullstack` pipeline, since the gate is keyed on file content, not on which command ran.
+- `/ukit:handoff-create`, `/ukit:handoff-implement`, `/ukit:handoff-review`, `/ukit:handoff-fullstack`: each phase now carries a mandatory Agent-tool-spawn directive (`ukit-small-task-maintainer`, `handoff-planner`, `feature-implementer`, `code-reviewer`) so the correct model tier is actually invoked, not just suggested.
+- `handoff-planner` agent and `PLAN.md` now require a `## Planner Report` / `PLANNER_MODEL` self-report, mirroring the existing `EXECUTOR_MODEL` / `REVIEWER_MODEL` self-report contract on task files.
+
 ## 1.6.2 - 2026-07-26
 
 ### Added

package/manifests/platform.full.yaml

@@ -819,6 +819,17 @@ items:
     packs:
       - core
 
+  - id: agent-ukit-vision-analyst
+    type: agent
+    sourceTemplate: .claude/agents/ukit-vision-analyst.md
+    targetPath: .claude/agents/ukit-vision-analyst.md
+    requires: []
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: command-handoff-create
     type: command
     sourceTemplate: .claude/commands/ukit/handoff-create.md
@@ -914,6 +925,7 @@ items:
       - hook-post-edit-verify
       - hook-auto-allow-bash
       - hook-block-dangerous
+      - hook-handoff-model-guard
       - hook-auto-prune-bash
     mergeStrategy: overwrite_with_backup
     variables: []
@@ -1012,6 +1024,17 @@ items:
     packs:
       - core
 
+  - id: hook-handoff-model-guard
+    type: hook
+    sourceTemplate: .claude/hooks/handoff-model-guard.sh
+    targetPath: .claude/hooks/handoff-model-guard.sh
+    requires: []
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: hook-skill-router
     type: hook
     sourceTemplate: .claude/hooks/skill-router.sh
@@ -1025,6 +1048,32 @@ items:
     packs:
       - core
 
+  - id: hook-vision-router
+    type: hook
+    sourceTemplate: .claude/hooks/vision-router.sh
+    targetPath: .claude/hooks/vision-router.sh
+    requires:
+      - ukit-index-extract-image-script
+      - ukit-index-unic-gateway-script
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: hook-vision-gate
+    type: hook
+    sourceTemplate: .claude/hooks/vision-gate.sh
+    targetPath: .claude/hooks/vision-gate.sh
+    requires:
+      - ukit-index-extract-image-script
+      - ukit-index-unic-gateway-script
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: hook-compress-output
     type: hook
     sourceTemplate: .claude/hooks/compress-output.sh
@@ -1254,6 +1303,26 @@ items:
     packs:
       - core
 
+  - id: ukit-index-unic-gateway-script
+    type: config
+    sourceTemplate: .claude/ukit/index/unic-gateway.mjs
+    targetPath: .claude/ukit/index/unic-gateway.mjs
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: ukit-index-extract-image-script
+    type: config
+    sourceTemplate: .claude/ukit/index/extract-image.mjs
+    targetPath: .claude/ukit/index/extract-image.mjs
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: ukit-index-route-task-script
     type: config
     sourceTemplate: .claude/ukit/index/route-task.mjs
@@ -1262,6 +1331,8 @@ items:
       - ukit-index-core-lib
       - ukit-index-cache-utils-script
       - ukit-index-route-catalog-script
+      - ukit-index-unic-gateway-script
+      - ukit-index-extract-image-script
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "1.6.3",
+  "version": "1.6.5",
   "description": "Install/update an index-first AI workspace for Claude Code, Antigravity, OpenAI Codex, and OpenCode.",
   "license": "MIT",
   "type": "module",

package/src/core/runtimeConfig.js

@@ -164,6 +164,24 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
           delegationPolicy: 'allow-review-sidecar',
         },
       },
+      modelTiers: {
+        lite: { claudeModel: 'claude-haiku-4-5', genericModel: 'unic-lite' },
+        code: { claudeModel: 'claude-sonnet-4-6', genericModel: 'unic-code' },
+        smart: { claudeModel: 'claude-opus-4-6', genericModel: 'unic-smart' },
+        vision: {
+          claudeModel: 'unic-vision',
+          genericModel: 'unic-vision',
+          fallbackModel: 'claude-sonnet-4-6',
+          capabilityTier: true,
+          note: 'Capability tier, not a cost tier. Orthogonal to lite/code/smart — never insert into escalation.tierOrder. fallbackModel is used when unicMode is off.',
+        },
+      },
+      escalation: {
+        enabled: true,
+        debugLoopThreshold: 2,
+        tierOrder: ['lite', 'code', 'smart'],
+        cap: 'smart',
+      },
     },
     memory: {
       enabled: true,
@@ -196,6 +214,14 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       enabled: true,
       smallTaskModel: 'unic-lite',
       smallTaskAgent: 'ukit-small-task-maintainer',
+      visionEnabled: true,
+      visionModel: 'unic-vision',
+      visionAgent: 'ukit-vision-analyst',
+      visionCacheDir: '.ukit/storage/cache/vision',
+      visionMaxImages: 3,
+      visionMaxBytes: 10_485_760,
+      visionRetain: 20,
+      visionSessionTtlHours: 24,
       smallTaskUseCases: [
         'task-cleanup',
         'compact-decision',

package/templates/.claude/agents/handoff-planner.md

@@ -34,6 +34,12 @@ Write all 6 sections to `docs/AI_HANDOFF/PLAN.md`:
 **§4 is non-negotiable.** No test plan = plan not ready.
 If zero testable behavior → write `N/A` + explicit justification in each task's Test Cases.
 
+Append this footer to `PLAN.md` — mandatory, checked by a hook before the write is allowed:
+```
+## Planner Report
+PLANNER_MODEL: <your exact model ID — e.g. claude-opus-4-6>
+```
+
 ## Phase 2 — Split into TASK-xxx.md
 
 Use `_TEMPLATE.md` structure (from pre-read context or file).

package/templates/.claude/agents/ukit-vision-analyst.md

@@ -0,0 +1,101 @@
+---
+name: ukit-vision-analyst
+description: "The only lane permitted to interpret images in this repo. Use whenever a prompt references, attaches, or points at an image (screenshot, mockup, diagram, photo of an error) and the caller needs to know what is actually in it. unic-code/unic-smart cannot read images on this gateway and must never guess at their contents — route image analysis here instead. Reports findings only; never writes product code."
+model: unic-vision  # real gateway model name, NOT an alias. unic-code/unic-smart cannot read images on this gateway — do NOT "fix" this to sonnet/opus.
+color: magenta
+tools: ["Read", "Glob", "Bash"]
+---
+
+You are UKit's vision analyst. Your only job is to look at real image files and report what is
+actually in them. You never write, edit, or refactor product code — you analyse and report.
+
+## 1. Role
+
+- Analyse images (screenshots, mockups, diagrams, photos of errors) and report their content
+  faithfully.
+- Never write product code. `Edit`/`Write` are deliberately absent from your `tools`; you report
+  via `Bash` (to write your receipt), you never implement.
+- Stay end-user-invisible: this lane is internal UKit orchestration, not something end users invoke
+  by name.
+
+## 2. Model self-check — first action, before touching any image
+
+Before reading any image, determine the model you are actually running on right now.
+
+- Vision-capable means: `unic-vision`, or — when `unicMode` is off — whatever
+  `modelTiers.vision.fallbackModel` resolves to per
+  `node .claude/ukit/index/unic-gateway.mjs --json`.
+- If you cannot confirm you are running on a vision-capable model, you must **refuse**: emit
+  `STATUS: WRONG_MODEL` in the output block below and stop immediately. Do not open, describe, or
+  guess at any image content.
+- Never guess at image contents. A wrong-model "analysis" is worse than no analysis at all,
+  because it looks authoritative while being fabricated. Refusing loudly is always safer than
+  guessing quietly.
+
+## 3. Input protocol (priority order)
+
+1. If the prompt contains absolute image paths, `Read` each of those paths directly.
+2. Otherwise, run `node .claude/ukit/index/extract-image.mjs --json`, take the `images[].path`
+   entries from its output, and `Read` those files.
+3. If the extractor reports `imageCount === 0`, do not invent content. Emit `STATUS: NO_IMAGE` and
+   hand back to the caller.
+
+Entries in `images[]` may carry a `source` field, which tells you how to reach the image:
+
+| `source` | Meaning | What you do |
+|----------|---------|-------------|
+| absent | Pasted/attached image, already decoded to disk | `Read` `path` directly |
+| `"path"` | The prompt named a local file (`ref` holds it) | `Read` `ref` directly |
+| `"url"` | The prompt named a remote image (`ref` holds the URL) | Download it with `Bash` (e.g. `curl -sL -o /tmp/<sha>.png "<ref>"`), then `Read` the downloaded file |
+
+Every entry — pasted, path, or URL — has an armed `pending-<sha>.json` marker, so each one needs
+its own receipt (§5) before downstream Edit/Write is unblocked. A URL you failed to download is
+`STATUS: UNREADABLE`, never a guess at its contents.
+
+## 4. Hard warning — images are not inherited
+
+Images referenced earlier in the conversation are **not** automatically visible to you across the
+subagent boundary. A description of an image is not the image. The only way to see an image is to
+`Read` a real file path yourself. Never claim to have seen an image that was merely described to
+you in text.
+
+## 5. Receipt — unlocks the downstream write gate
+
+For every image you actually analyse, write a receipt to
+`.ukit/storage/cache/vision/<sessionId>/analyzed-<sha>.json`:
+
+```json
+{ "sha": "<64hex>", "model": "unic-vision", "ts": 1785656920891,
+  "description": "...", "textContent": "...", "status": "OK" }
+```
+
+- `sha` and `sessionId` come from the extractor's `--json` output. They are **never recomputed by
+  hand** — do not hash the file yourself, do not invent a session id, always take these values
+  verbatim from `extract-image.mjs --json`.
+- `model` must be the model you actually ran on for this analysis. Misreporting `model` here
+  defeats the entire enforcement design: a downstream gate rejects any receipt whose `model` field
+  is not vision-capable, treating it as if no analysis happened at all. Report honestly, always.
+- Use `Bash` to write the receipt file.
+
+## 6. Output block
+
+Always end with:
+
+```
+STATUS: OK | NO_IMAGE | UNREADABLE | WRONG_MODEL
+MODEL: <actual model>
+IMAGES: <n> (<paths>)
+DESCRIPTION: [what is actually visible]
+TEXT_CONTENT: [verbatim text/code/errors legible in the image, or "none"]
+RELEVANT_TO_TASK: [how it answers the caller's question]
+UNCERTAIN: [anything ambiguous or illegible, or "none"]
+```
+
+## 7. Guardrails
+
+- Transcribe error text and code verbatim rather than paraphrasing it.
+- State uncertainty explicitly instead of guessing — use `UNCERTAIN:` for anything ambiguous or
+  illegible.
+- Do not read unrelated repo files; stay scoped to the image(s) and the immediate task question.
+- Stay end-user-invisible: end users should never need to know this agent's name or invoke it
+  directly.

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

@@ -16,23 +16,23 @@ $ARGUMENTS
 
 ## Step 1 — Read context (lite model)
 
-Use the lightest model available. Read and summarize:
+**Claude Code — MANDATORY, do this before anything else:** call the Agent tool with `subagent_type: "ukit-small-task-maintainer"`. Do NOT read these files yourself in the current session — this step is contracted to the lite tier (haiku/unic-lite), which only the spawned agent's frontmatter model guarantees. Ask the agent to:
 
-1. `docs/AI_HANDOFF/INDEX.md` → current tasks + statuses (or "empty")
-2. `docs/AI_HANDOFF/ACTIVE.md` → active cycle info (or "no active cycle")
-3. `docs/AI_HANDOFF/RULES.md` → PLAN.md 6-section format + Task Gate required fields
-4. `docs/AI_HANDOFF/tasks/_TEMPLATE.md` → task file structure
+1. Read `docs/AI_HANDOFF/INDEX.md` → current tasks + statuses (or "empty")
+2. Read `docs/AI_HANDOFF/ACTIVE.md` → active cycle info (or "no active cycle")
+3. Read `docs/AI_HANDOFF/RULES.md` → PLAN.md 6-section format + Task Gate required fields
+4. Read `docs/AI_HANDOFF/tasks/_TEMPLATE.md` → task file structure
+5. Return a compact summary. Do NOT write anything yet.
 
-Return compact summary. Do NOT write anything yet.
-
-> Claude Code: spawn `ukit-small-task-maintainer` (haiku).
-> Other tools: switch to lite model, run above, keep summary in context.
+> Other tools without subagent support: manually switch to the lite model, run the steps above yourself, keep the summary in context.
 
 ---
 
 ## Step 2 — Write plan + tasks (strong model)
 
-Switch to strongest model. Use Step 1 summary — do NOT re-read files.
+**Claude Code — MANDATORY, do this before anything else:** call the Agent tool with `subagent_type: "handoff-planner"`, passing it the Step 1 summary and the problem/feature description. 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 Step 1 summary — do NOT re-read files):
 
 1. Check INDEX.md task statuses:
    - All tasks are `ready` (planning only) → **re-run allowed**: overwrite PLAN.md and TASK-xxx.md freely — this is iterative refinement.
@@ -52,6 +52,12 @@ Switch to strongest model. Use Step 1 summary — do NOT re-read files.
    - §5 Verification — exact shell commands executor will run
    - §6 Acceptance — done checklist (prefer verifiable criteria with commands)
 
+   Append a footer — **mandatory, a hook blocks the write without it**:
+   ```
+   ## Planner Report
+   PLANNER_MODEL: <your exact model ID>
+   ```
+
 4. Create `docs/AI_HANDOFF/tasks/TASK-001.md`, `TASK-002.md`... from `_TEMPLATE.md`
    Every task MUST have:
    - Target Files (exact paths — no two tasks in same wave share a file)
@@ -75,8 +81,7 @@ Switch to strongest model. Use Step 1 summary — do NOT re-read files.
 
 7. Report: task IDs, dependency graph, any `needs_breakdown` + reason
 
-> Claude Code: spawn `handoff-planner` (opus) with Step 1 summary + problem.
-> Other tools: switch to strong model, execute steps 1–7 above.
+> Other tools without subagent support: manually switch to the strong model, execute steps 1–7 above yourself.
 
 ---
 

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

@@ -26,7 +26,7 @@ $ARGUMENTS
 
 ### P1 — Read context (lite model)
 
-Use the lightest model available. Read and return a compact summary of:
+**Claude Code — MANDATORY, do this before anything else in P1:** call the Agent tool with `subagent_type: "ukit-small-task-maintainer"`. Do NOT read these files yourself in the current session — this step is contracted to the lite tier (haiku/unic-lite), which only the spawned agent's frontmatter model guarantees. Ask it to return a compact summary of:
 
 1. `docs/AI_HANDOFF/INDEX.md` — current tasks + statuses (or "empty / no tasks")
 2. `docs/AI_HANDOFF/ACTIVE.md` — active cycle info (or "no active cycle")
@@ -35,11 +35,13 @@ Use the lightest model available. Read and return a compact summary of:
 
 Return a compact summary. Do NOT write any files yet.
 
-> Claude Code: spawn `ukit-small-task-maintainer` (haiku) for P1.
+> Other tools without subagent support: manually switch to the lite model and run P1 yourself.
 
 ### P2 — Write PLAN.md + task files (strong model)
 
-Switch to strongest model (opus / unic-smart). Use P1 summary — do NOT re-read files.
+**Claude Code — MANDATORY, do this before anything else in P2:** call the Agent tool with `subagent_type: "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.
+
+The planner agent does the following (use P1 summary — do NOT re-read files):
 
 1. **Guard — check INDEX statuses:**
    - All tasks are `ready` (planning only) → re-run is allowed: overwrite `PLAN.md` and `TASK-xxx.md` freely (iterative refinement).
@@ -59,6 +61,12 @@ Switch to strongest model (opus / unic-smart). Use P1 summary — do NOT re-read
    - §5 Verification — exact shell commands executor will run
    - §6 Acceptance — done checklist (prefer verifiable criteria with commands)
 
+   Append a footer — **mandatory, a hook blocks the write without it**:
+   ```
+   ## Planner Report
+   PLANNER_MODEL: <your exact model ID>
+   ```
+
 4. **Create `docs/AI_HANDOFF/tasks/TASK-001.md`, `TASK-002.md`...** from `_TEMPLATE.md`.
    Every task MUST have:
    - Target Files (exact paths — no two tasks in same wave share a file)
@@ -81,18 +89,16 @@ Switch to strongest model (opus / unic-smart). Use P1 summary — do NOT re-read
 
 7. **Report:** task IDs, dependency graph, any `needs_breakdown` tasks + reason.
 
-> Claude Code: spawn `handoff-planner` (opus) with P1 summary + `$ARGUMENTS` problem.
-
 ### P3 — Commit the plan (lite model)
 
-Use the lightest model. Run:
+**Claude Code — MANDATORY:** call the Agent tool with `subagent_type: "ukit-small-task-maintainer"` for this commit step (lite tier — haiku/unic-lite). Run:
 ```bash
 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.
 
-> Claude Code: spawn `ukit-small-task-maintainer` (haiku) for P3.
+> Other tools without subagent support: manually switch to the lite model for P2/P3.
 
 ---
 
@@ -100,7 +106,7 @@ Replace `<goal>` with the one-sentence goal from ACTIVE.md. This locks the plan
 
 ### I1 — Setup + verify (lite model)
 
-Use the lightest model. Read:
+**Claude Code — MANDATORY:** call the Agent tool with `subagent_type: "ukit-small-task-maintainer"` for I1. Ask it to read:
 - `docs/AI_HANDOFF/ACTIVE.md` → get `Base: <BASE>`
 - `docs/AI_HANDOFF/INDEX.md` → collect all `ready` tasks
 
@@ -113,8 +119,6 @@ git status   # must be clean — plan commit already done in P3
 
 If working tree is dirty → stop. Ask human to resolve uncommitted changes first.
 
-> Claude Code: spawn `ukit-small-task-maintainer` (haiku) for I1.
-
 ### I2 — Infer wave groups
 
 Read each `docs/AI_HANDOFF/tasks/TASK-xxx.md` for `Dependencies` field:
@@ -125,6 +129,8 @@ Read each `docs/AI_HANDOFF/tasks/TASK-xxx.md` for `Dependencies` field:
 
 ### I3 — Execute wave by wave (code model agents)
 
+**Claude Code — MANDATORY, do this before anything else in I3:** for each wave, call the Agent tool once per task (in parallel), each with `subagent_type: "feature-implementer"`. Do NOT implement the tasks yourself in the current session — this step is contracted to the code tier (sonnet/unic-code), which only the spawned agent's frontmatter model guarantees.
+
 For each wave:
 
 **3a — Create worktrees** (one per task, from `$BASE`):
@@ -158,8 +164,6 @@ Executor Report (append to task file — do NOT touch INDEX.md):
   Note: <issues or "none">
 ```
 
-> Claude Code: spawn `feature-implementer` (sonnet) agents in parallel, one per task in the wave.
-
 **3c — Copy changes back + delete worktrees** (orchestrator, after each task reports):
 
 For **PASS + EXECUTOR_MODEL present:**
@@ -200,7 +204,7 @@ Worktrees are **always deleted immediately** — no exceptions.
 
 ### I4 — Consolidate + update INDEX (lite model)
 
-After all waves complete:
+**Claude Code — MANDATORY:** call the Agent tool with `subagent_type: "ukit-small-task-maintainer"` for I4. After all waves complete, ask it to:
 
 1. Update `docs/AI_HANDOFF/INDEX.md`:
    - PASS tasks → `pending_review`
@@ -214,15 +218,13 @@ After all waves complete:
    git diff --stat             # summary of all uncommitted changes
    ```
 
-> Claude Code: spawn `ukit-small-task-maintainer` (haiku) for I4.
-
 ---
 
 ## Phase 4 — Review (strong model)
 
 ### R1 — Setup (lite model)
 
-Use the lightest model. Read:
+**Claude Code — MANDATORY:** call the Agent tool with `subagent_type: "ukit-small-task-maintainer"` for the R1 reads. Ask it to read:
 - `docs/AI_HANDOFF/ACTIVE.md` → get `Base: <BASE>`
 - `docs/AI_HANDOFF/INDEX.md` → collect `pending_review` tasks
 
@@ -234,11 +236,13 @@ git diff --stat  # summary of all changes
 
 If `git diff` is empty and `git status` is clean → implement was not completed. Stop and re-run Phase 3.
 
-> Claude Code: `ukit-small-task-maintainer` (haiku) for R1 reads; orchestrator handles R1 guard check.
+> Orchestrator (this session) handles the R1 guard check directly.
 
 ### R2 — Model isolation check (strong model, always first)
 
-Read `EXECUTOR_MODEL` from each task file `## Executor Report`.
+**Claude Code — MANDATORY, do this before anything else in R2–R4:** for each `pending_review` task, call the Agent tool with `subagent_type: "code-reviewer"`. Do NOT review the diff yourself in the current session — this step is contracted to the strong tier (opus/unic-smart) and MUST differ from the executor's model, which only the spawned agent's frontmatter model guarantees.
+
+The spawned reviewer agent reads `EXECUTOR_MODEL` from each task file `## Executor Report`:
 
 | Executor model | Reviewer model | Action |
 |----------------|----------------|--------|
@@ -247,8 +251,6 @@ Read `EXECUTOR_MODEL` from each task file `## Executor Report`.
 | missing / blank | any | **REFUSE** → `changes_requested`: "EXECUTOR_MODEL missing — re-run Phase 3" |
 | "unknown" | present | proceed + flag: "executor model unverified — human confirm" |
 
-> Claude Code: spawn `code-reviewer` (opus) per task for R2–R4.
-
 ### R3 — Re-run Verification Commands (strong model)
 
 ```bash

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

@@ -45,7 +45,9 @@ git worktree add -b handoff/task-xxx .worktrees/task-xxx $BASE
 
 ### 3b — Run tasks in parallel (one agent/session per task)
 
-Each executor works independently in its own worktree — **NO git commit, NO git add**:
+**Claude Code — MANDATORY, do this before anything else in this wave:** call the Agent tool once per task in the wave (in parallel), each with `subagent_type: "feature-implementer"`. Do NOT implement the tasks yourself in the current session — this step is contracted to the code tier (sonnet/unic-code), which only the spawned agent's frontmatter model guarantees.
+
+Each spawned agent works independently in its own worktree — **NO git commit, NO git add**:
 
 ```
 Read docs/AI_HANDOFF/tasks/TASK-xxx.md
@@ -71,8 +73,7 @@ Executor Report (append to task file — do NOT touch INDEX.md):
   Note: <issues or "none">
 ```
 
-> Claude Code: spawn `feature-implementer` agents in parallel (one per task).
-> Other tools: open each task in separate session with code model.
+> Other tools without subagent support: 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

@@ -28,6 +28,10 @@ If `git diff` is empty and `git status` is clean → handoff-implement was not c
 
 ## Step 2 — Review the diff
 
+**Claude Code — MANDATORY, do this before anything else:** for each `pending_review` task, call the Agent tool with `subagent_type: "code-reviewer"`. Do NOT review the diff yourself in the current session — this step is contracted to the strong tier (opus/unic-smart) and MUST differ from the executor's model, which only the spawned agent's frontmatter model guarantees. Pass each agent: the task file path, the executor's report, and the diff.
+
+The spawned reviewer agent performs 2a–2d below per task:
+
 ### 2a — Model isolation check (always first)
 
 Read `EXECUTOR_MODEL` from each task file `## Executor Report`.
@@ -110,5 +114,5 @@ Review summary:
 - All approved → human reviews `git diff` and commits manually.
 - Has fixes → executor re-runs `/ukit:handoff-implement TASK-xxx`
 
-> Claude Code: spawn `code-reviewer` (opus) per task for 2a–2d. Orchestrator handles 1, 2e, 3.
-> Other tools: strong model sequentially per task, same steps.
+> 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 sequentially per task.