@ngockhoale/ukit 1.5.10 → 1.5.12

package/manifests/platform.full.yaml

@@ -865,6 +865,30 @@ items:
     packs:
       - core
 
+  - id: command-status-handoff
+    type: command
+    sourceTemplate: .claude/commands/ukit/status-handoff.md
+    targetPath: .claude/commands/ukit/status-handoff.md
+    requires:
+      - command-create-handoff
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: command-abort-handoff
+    type: command
+    sourceTemplate: .claude/commands/ukit/abort-handoff.md
+    targetPath: .claude/commands/ukit/abort-handoff.md
+    requires:
+      - command-create-handoff
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: provider-compat-config
     type: config
     sourceTemplate: .claude/config/providers.md

package/package.json

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

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

@@ -12,11 +12,8 @@ Use the strongest model available — planning with a weak model produces weak t
 ## Inputs
 
 - Problem/feature description from the user.
-- **Pre-read context** (if provided in the prompt): compact summary of INDEX.md, ACTIVE.md, RULES.md, _TEMPLATE.md read by a lite agent. **Use it directly — do NOT re-read those files.**
-- If no pre-read context → read the files yourself (fallback for direct invocation):
-  - `docs/AI_HANDOFF/INDEX.md` + `ACTIVE.md` (current state)
-  - `docs/AI_HANDOFF/RULES.md` (PLAN.md format + Task Gate rules)
-  - `docs/AI_HANDOFF/tasks/_TEMPLATE.md` (task file structure)
+- **Pre-read context** (if provided): compact summary of INDEX.md, ACTIVE.md, RULES.md, _TEMPLATE.md. Use it directly — do NOT re-read those files.
+- If no pre-read context → read the files yourself (fallback for direct invocation).
 
 ## Phase 1 — Write PLAN.md
 
@@ -25,11 +22,13 @@ Write all 6 sections to `docs/AI_HANDOFF/PLAN.md`:
 ```
 §1 Intent       — what problem, what success looks like
 §2 Scope        — in-scope / out-of-scope
+                  CONSTRAINT: tasks in the same wave must not modify the same file.
+                  If two tasks need the same file → make one depend on the other.
 §3 Approach     — technical solution, trade-offs, alternatives rejected
 §4 Test Plan    — happy path × N + ≥1 edge case + regression (if bugfix)
                   table: | Type | Test Name | Expected |
 §5 Verification — exact shell commands executor will run
-§6 Acceptance   — checklist of done criteria
+§6 Acceptance   — checklist of done criteria (prefer verifiable/command-based criteria)
 ```
 
 **§4 is non-negotiable.** No test plan = plan not ready.
@@ -43,32 +42,38 @@ Use `_TEMPLATE.md` structure (from pre-read context or file).
 
 | Field | Rule |
 |-------|------|
-| Target Files | Exact paths: `src/foo/bar.js`, `tests/foo/bar.test.js` |
-| Dependencies | `TASK-xxx` or `none` |
+| Target Files | Exact paths — no two tasks in same wave share a file |
+| Dependencies | `TASK-xxx` or `none` — wave order is inferred from this |
 | Test Cases | Type \| Test Name \| Expected — ≥1 happy + ≥1 edge case |
 | Test Files | Exact test file paths to create/modify |
 | Verification Commands | Runnable shell commands |
-| Acceptance Criteria | Checklist items |
+| Acceptance Criteria | Verifiable checklist |
 
 Missing any field → `needs_breakdown`. Never mark incomplete tasks `ready`.
 
-**Wave grouping:** Wave 1 = `dependencies: none`, Wave 2 = depends on Wave 1, etc. Document in ACTIVE.md.
+**Wave logic (for your reference when splitting):**
+- Wave 1 = tasks with `Dependencies: none`
+- Wave 2 = tasks whose all deps are in Wave 1
+- Chain: A → B → C runs as 3 sequential waves (1 task each, no parallelism)
+- Independent: A, B, C (all `none`) runs as 1 wave, all parallel
 
 ## Phase 3 — Update state files
 
 **INDEX.md** row per task: `| TASK-001 | <name> | ready | none | - |`
 
-**ACTIVE.md** snapshot:
+**ACTIVE.md** — store base branch + cycle info:
 ```
-Cycle: <ID>   Date: <YYYY-MM-DD>
+Cycle: <ID>   Date: <YYYY-MM-DD>   Base: <current HEAD branch>
 Goal: <1 sentence>
-Tasks: <N> total | Wave 1: TASK-001, TASK-002 | Wave 2: TASK-003
+Tasks: <N> total
 Status: planning_done — ready for executor
 ```
+Wave structure is NOT stored here — inferred from task `Dependencies` fields at runtime.
 
 ## Output
 
-- Task count + IDs, wave structure
+- Task count + IDs
+- Dependency graph (text form: TASK-001 → TASK-003, TASK-002 independent)
 - Any `needs_breakdown` tasks + reason
 - Next step: "Switch to Sonnet/unic-code → run `/ukit:implement-handoff`"
 

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

@@ -0,0 +1,59 @@
+# /ukit:abort-handoff — Force Abandon Cycle (no archive)
+
+**Role: CLEANUP**
+**Tool: any**
+**Model: lite model** (haiku · unic-lite)
+
+**Use when:** plan is wrong from the root, or cycle is unrecoverable. Discards everything — no archive, no history entry.
+**Different from `/ukit:clear-handoff`:** clear = "done, save it". abort = "throw it away".
+
+---
+
+## Step 1 — Confirm intent
+
+Report the current state before doing anything:
+```
+⚠️  About to ABORT handoff cycle:
+  Cycle: <ID>   Goal: <goal>
+  Tasks that will be lost: TASK-001 [in_progress], TASK-002 [ready], ...
+  Worktrees to delete: .worktrees/task-001, ...
+  
+  This will NOT be archived. All work in worktrees will be discarded.
+  Respond "confirm abort" to proceed.
+```
+
+Wait for human to confirm. If not confirmed → stop.
+
+## Step 2 — Force remove all worktrees + branches
+
+```bash
+# Remove task worktrees + branches
+git worktree list | grep '.worktrees/task-' | awk '{print $1}' | while read wt; do
+  name=$(basename $wt)
+  git worktree remove $wt --force
+  git branch -D handoff/$name 2>/dev/null
+done
+
+# Remove integration branch
+git branch -D handoff/integration 2>/dev/null
+
+git worktree prune
+```
+
+## Step 3 — Reset state files (no archive)
+
+```
+PLAN.md   → "# PLAN\n_(empty)_"
+INDEX.md  → empty table header only
+ACTIVE.md → "# ACTIVE\n_(no active cycle)_"
+tasks/TASK-*.md → delete all (keep _TEMPLATE.md)
+```
+
+## Step 4 — Report
+
+Cycle aborted. No archive written. Worktrees and branches removed. Ready for new cycle.
+
+> Claude Code: spawn `ukit-small-task-maintainer` (haiku) with steps 1–4.
+> Other tools: use lite model, follow steps above.
+
+**Next:** `/ukit:create-handoff <new problem description>` (start fresh)

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

@@ -1,73 +1,73 @@
-# /ukit:clear-handoff
+# /ukit:clear-handoff — Archive + Reset
 
-Spawn **ukit-small-task-maintainer** (Haiku / unic-lite) to archive and reset the cycle.
+**Role: CLEANUP**
+**Tool: any**
+**Model: lite model** (haiku · unic-lite · cheapest — this is file ops only)
 
 **HARD GATE: Will NOT clear if any task is not `done`.**
 
 ---
 
-Spawn Agent:
-- `subagent_type: ukit-small-task-maintainer`
-- `model: haiku`
-- `prompt`:
+## Step 1 — Gate check (mandatory, cannot skip)
 
-```
-Clear the current handoff cycle.
+Read `docs/AI_HANDOFF/INDEX.md`. List every task + status.
+Read `docs/AI_HANDOFF/ACTIVE.md` → get `Base: <BASE>`.
 
-## Step 1 — GATE CHECK (mandatory, cannot skip)
+If ANY task status ≠ `done` → **STOP**. Report and exit:
 
-Read docs/AI_HANDOFF/INDEX.md.
-List every task and its status.
+```
+⛔ Cannot clear — X task(s) not done:
+  TASK-001 [pending_review]    → /ukit:review-handoff TASK-001
+  TASK-003 [changes_requested] → /ukit:implement-handoff TASK-003
+  TASK-005 [ready]             → /ukit:implement-handoff TASK-005
+  TASK-006 [merge_conflict]    → rebase handoff/task-006 on handoff/integration, re-run implement
 
-Find all tasks where status ≠ done:
-  - ready             → not started (run /ukit:implement-handoff TASK-xxx)
-  - in_progress       → executor still working
-  - pending_review    → waiting for review (run /ukit:review-handoff TASK-xxx)
-  - changes_requested → executor must fix (run /ukit:implement-handoff TASK-xxx)
-  - critical_block    → executor must fix (run /ukit:implement-handoff TASK-xxx)
-  - needs_breakdown   → planner must split (run /ukit:create-handoff to re-plan)
-  - blocked           → needs human decision
+Fix all tasks first, then re-run /ukit:clear-handoff.
+```
 
-If ANY task has status ≠ done → STOP IMMEDIATELY. Do NOT proceed to steps 2-4.
-Report:
+Only continue if ALL tasks are `done`.
 
-  ⛔ Cannot clear — X task(s) not done:
-  - TASK-001 [pending_review] → run /ukit:review-handoff TASK-001
-  - TASK-003 [changes_requested] → run /ukit:implement-handoff TASK-003
-  
-  Fix all tasks first, then re-run /ukit:clear-handoff.
+## Step 2 — Cleanup worktrees + branches
 
-Only continue to Step 2 if ALL tasks are done.
+```bash
+# Remove any remaining task worktrees (should already be gone after review, but be safe)
+git worktree list | grep '.worktrees/task-' | awk '{print $1}' | while read wt; do
+  name=$(basename $wt)
+  git worktree remove $wt --force 2>/dev/null
+  git branch -D handoff/$name 2>/dev/null
+done
 
-## Step 2 — Cleanup worktrees
+# Remove integration branch if still exists
+git branch -D handoff/integration 2>/dev/null
 
-git worktree list | grep handoff/
-For each .worktrees/task-xxx:
-  git worktree remove .worktrees/task-xxx --force
-  git branch -D handoff/task-xxx
 git worktree prune
+```
 
 ## Step 3 — Archive cycle
 
-Read INDEX.md cycle ID.
-Write docs/AI_HANDOFF/archive/cycle-NNN.md:
-  # Cycle NNN — <YYYY-MM-DD>
-  ## Summary: <1 paragraph of what was accomplished>
-  ## Tasks: <copy INDEX.md table>
-
-If archive/ has > 3 files → delete oldest, append 1-line summary to HISTORY.md.
+Read INDEX.md for cycle ID and task list.
+Write `docs/AI_HANDOFF/archive/cycle-NNN.md`:
+```
+# Cycle NNN — <YYYY-MM-DD>   Base: <BASE>
+## Summary: <1 paragraph of what was accomplished>
+## Tasks: <copy INDEX.md table>
+```
+If `archive/` has > 3 files → delete oldest, append 1-line summary to `HISTORY.md`.
 
 ## Step 4 — Reset state files
 
-PLAN.md       → "# PLAN\n_(empty)_"
-INDEX.md      → empty table header only
-ACTIVE.md     → "# ACTIVE\n_(no active cycle)_"
+```
+PLAN.md  → "# PLAN\n_(empty)_"
+INDEX.md → empty table header only
+ACTIVE.md → "# ACTIVE\n_(no active cycle)_"
 tasks/TASK-*.md → delete all (keep _TEMPLATE.md)
+```
 
 ## Step 5 — Report
 
-Cycle NNN archived. X tasks completed. Worktrees removed. Ready for new cycle.
-```
+Cycle NNN archived. X tasks completed. Base was $BASE. Worktrees removed. Ready for new cycle.
+
+> Claude Code: spawn `ukit-small-task-maintainer` (haiku) with steps 1–5.
+> Other tools: use lite model, follow steps 1–5 above.
 
-After agent completes:
-> Ready for new cycle → `/ukit:create-handoff <description>`
+**Next:** `/ukit:create-handoff <new problem description>`

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

@@ -1,61 +1,77 @@
-# /ukit:create-handoff
+# /ukit:create-handoff — Phase 1 + 2: Plan
 
-Two-step: **lite model reads context** → **Opus writes plan**.
+**Role: PLANNER**
+**Tool: any** (Claude Code / Codex / Antigravity / Kilo / OpenCode — your choice)
+**Model split:**
+- Read/understand → lite model (haiku · unic-lite · cheapest available)
+- Write plan + tasks → strong model (Opus · unic-smart · strongest available)
 
 ## Problem / feature
 $ARGUMENTS
 
 ---
 
-## Step 1 — Pre-read (Haiku / unic-lite, fast)
+## Step 1 — Read context (lite model)
 
-Spawn Agent:
-- `subagent_type: ukit-small-task-maintainer`
-- `model: haiku`
-- `prompt`:
+Use the lightest model available. Read and summarize:
 
-```
-Read and summarize the current handoff state for the planner. Be compact.
+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 → list all tasks + statuses (or "empty" if none)
-2. Read docs/AI_HANDOFF/ACTIVE.md → current cycle ID + goal (or "no active cycle")
-3. Read docs/AI_HANDOFF/RULES.md → extract: PLAN.md 6 sections, Task Gate fields, wave grouping rule
-4. Read docs/AI_HANDOFF/tasks/_TEMPLATE.md → paste the template structure
+Return compact summary. Do NOT write anything yet.
 
-Return a compact summary block the planner can read directly without opening files.
-```
+> Claude Code: spawn `ukit-small-task-maintainer` (haiku).
+> Other tools: switch to lite model, run above, keep summary in context.
 
 ---
 
-## Step 2 — Plan (Opus / unic-smart, strong)
+## Step 2 — Write plan + tasks (strong model)
 
-Take the summary from Step 1. Spawn Agent:
-- `subagent_type: handoff-planner`
-- `model: opus`
-- `prompt`:
+Switch to strongest model. Use Step 1 summary — do NOT re-read files.
 
-```
-Problem to plan: $ARGUMENTS
+1. If INDEX.md has undone tasks → warn human: continue old cycle or start fresh?
 
-Pre-read context (from lite agent):
-<insert Step 1 output here>
+2. Resolve base branch:
+   ```bash
+   BASE=$(git symbolic-ref --short HEAD)
+   ```
 
-Using the context above (do NOT re-read the same files):
+3. Write `docs/AI_HANDOFF/PLAN.md` — all 6 sections mandatory:
+   - §1 Intent — problem + success definition
+   - §2 Scope — in / out of scope. **Add a constraint**: same-wave tasks must not modify the same file (prevents merge conflicts). If two tasks need the same file, make one depend on the other.
+   - §3 Approach — solution, trade-offs, alternatives rejected
+   - §4 Test Plan — happy path + ≥1 edge case + regression if bugfix (non-negotiable)
+   - §5 Verification — exact shell commands executor will run
+   - §6 Acceptance — done checklist (prefer verifiable criteria with commands)
 
-1. If INDEX.md shows undone tasks → warn human: continue old cycle or start fresh?
+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)
+   - Dependencies (`TASK-xxx` or `none` — wave structure inferred from this, not stored separately)
+   - Test Cases (Type | Name | Expected — ≥1 happy + ≥1 edge case)
+   - Test Files (exact paths)
+   - Verification Commands (runnable shell commands)
+   - Acceptance Criteria (verifiable checklist)
+   Missing any field → status: `needs_breakdown`, never `ready`
 
-2. Write docs/AI_HANDOFF/PLAN.md — all 6 sections (from RULES.md format in context):
-   §1 Intent | §2 Scope | §3 Approach | §4 Test Plan | §5 Verification | §6 Acceptance
-   §4 Test Plan: happy path + ≥1 edge case + regression if bugfix — non-negotiable
+5. Update `INDEX.md` — one row per task, `status=ready`
 
-3. Create docs/AI_HANDOFF/tasks/TASK-001.md ... using _TEMPLATE.md structure (from context)
-   Each task MUST have all Task Gate fields. Missing any → needs_breakdown, never ready.
+6. Update `ACTIVE.md`:
+   ```
+   Cycle: <ID>   Date: <YYYY-MM-DD>   Base: <BASE>
+   Goal: <1 sentence>
+   Tasks: <N> total
+   Status: planning_done — ready for executor
+   ```
+   Note: wave structure is inferred from task Dependencies fields — not stored here.
 
-4. Update INDEX.md — add rows, status=ready
-5. Update ACTIVE.md — cycle snapshot + wave structure
+7. Report: task IDs, dependency graph, any `needs_breakdown` + reason
 
-6. Report: task list + IDs, wave map, any needs_breakdown, next step for human
-```
+> Claude Code: spawn `handoff-planner` (opus) with Step 1 summary + problem.
+> Other tools: switch to strong model, execute steps 1–7 above.
 
-After both agents complete:
-> Switch to **Sonnet / unic-code** → run `/ukit:implement-handoff`
+---
+
+**Next:** switch to code model → `/ukit:implement-handoff`

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

@@ -1,47 +1,109 @@
-# /ukit:implement-handoff
+# /ukit:implement-handoff — Phase 3: Execute
 
-Spawn **feature-implementer** agents in parallel waves (Sonnet / unic-code).
+**Role: EXECUTOR (orchestrated)**
+**Tool: any** (Claude Code / Codex / Antigravity / Kilo / OpenCode — your choice)
+**Model: code model** (Sonnet · unic-code · cheap-smart)
 
 ## Target (optional)
 $ARGUMENTS
-_Empty = all ready tasks. Or: "TASK-001" for a specific task._
+_Empty = all `ready` tasks. Or: "TASK-001" for a specific task._
 
 ---
 
-1. Read `docs/AI_HANDOFF/INDEX.md`
-   - Collect tasks with status `ready` (or the specific task from $ARGUMENTS)
-   - If none → report and stop
+## Step 1 — Setup
 
-2. Group tasks into waves by dependency:
-   - Wave 1: tasks with `dependencies: none` or all deps already `done`
-   - Wave 2+: tasks whose deps are in the previous wave
+Read `docs/AI_HANDOFF/ACTIVE.md` → get `Base: <BASE>` (the branch set at plan time).
+Read `docs/AI_HANDOFF/INDEX.md` → collect `ready` tasks (or specific task from $ARGUMENTS).
+If no ready tasks → report and stop.
 
-3. For each wave — spawn feature-implementer agents **in parallel**, one per task:
+Create integration branch (once per cycle, skip if already exists):
+```bash
+git branch handoff/integration $BASE 2>/dev/null || echo "integration branch already exists"
+```
+
+## Step 2 — Build wave groups
+
+Wave structure is inferred from task `Dependencies` fields — read each `tasks/TASK-xxx.md`:
+- Wave 1: tasks where `Dependencies: none` (or all deps already `done`)
+- Wave 2: tasks whose deps are all in Wave 1
+- Wave N+1: tasks whose deps are all in Wave N or earlier
+
+## Step 3 — Execute wave by wave
 
+For each wave:
+
+### 3a — Create worktrees (branch from `handoff/integration`)
+```bash
+# For each task in this wave:
+git worktree add -b handoff/task-xxx .worktrees/task-xxx handoff/integration
+# (omit -b if branch already exists; worktrees stay open until review-handoff cleans up)
 ```
-Implement docs/AI_HANDOFF/tasks/TASK-xxx.md in handoff mode.
 
-Worktree:
-  git worktree add -b handoff/task-xxx .worktrees/task-xxx
-  (skip -b if branch already exists)
+### 3b — Run tasks in parallel (one agent/session per task)
+
+Each executor does — **independently, in its own worktree**:
+
+```
+Read docs/AI_HANDOFF/tasks/TASK-xxx.md
 
-TDD (mandatory):
-  1. Write tests from §Test Cases → run → confirm RED
+TDD — mandatory:
+  1. Write tests from §Test Cases
+     Run: cd .worktrees/task-xxx && <test command>
+     Confirm RED (if immediately GREEN → test is wrong or feature already exists — flag this)
   2. Implement → run → confirm GREEN
-  3. Run §Verification Commands → paste full output
+  3. Run §Verification Commands from INSIDE the worktree:
+     cd .worktrees/task-xxx && <each verification command>
+     Paste full output.
 
-Executor Report (append to task file):
-  EXECUTOR_TOOL / EXECUTOR_MODEL / EXECUTOR_SUBAGENT: feature-implementer
+Commit in worktree (required before reporting):
+  git -C .worktrees/task-xxx add -A
+  git -C .worktrees/task-xxx commit -m "feat(TASK-xxx): <intent from task §1>"
+
+Executor Report (append to task file — do NOT touch INDEX.md):
+  ## Executor Report
+  EXECUTOR_TOOL: <tool name>
+  EXECUTOR_MODEL: <exact model ID — mandatory, reviewer will refuse if missing>
+  EXECUTOR_SUBAGENT: <subagent name or "-">
   Verification Output: <paste>
   Status: PASS | FAIL
+  Note: <any issues, or "none">
+```
 
-Update INDEX.md: status → pending_review
+> Claude Code: spawn `feature-implementer` agents in parallel (one per task).
+> Other tools: open each task in a separate session with code model.
 
-If tests FAIL → fix in same worktree before updating status. Never mark pending_review with a FAIL.
-```
+### 3c — After all tasks in wave report back (orchestrator)
+
+For each task:
+- If `Status: PASS` AND `EXECUTOR_MODEL` present → merge into integration:
+  ```bash
+  if git merge handoff/task-xxx --no-ff -m "wave-merge(TASK-xxx)" --no-commit 2>/dev/null; then
+    git commit -m "wave-merge(TASK-xxx)"
+    # update INDEX.md: status → pending_review
+  else
+    git merge --abort
+    # update INDEX.md: status → merge_conflict
+    # append to task §Discussion: "merge_conflict with <previously merged tasks in this wave>"
+    # report to human: rebase handoff/task-xxx on handoff/integration, re-run
+  fi
+  ```
+- If `Status: FAIL` → update INDEX.md: status → `blocked`
+- If `EXECUTOR_MODEL` missing → update INDEX.md: status → `needs_executor_report`; do not set pending_review
 
-4. Wait for all agents in the wave → run next wave
+**Orchestrator writes INDEX.md** — agents never touch INDEX directly.
 
-5. Report: PASS/FAIL per task, worktrees created, any blockers
+### 3d — Next wave
+Branch new wave worktrees from `handoff/integration` (which now includes Wave N's code).
+Repeat 3a–3c.
+
+## Step 4 — Report
+
+```
+Wave summary:
+  Wave 1: TASK-001 [pending_review], TASK-002 [blocked]
+  Wave 2: TASK-003 [pending_review]
+  Merge conflicts: none | TASK-xxx (needs rebase)
+  Worktrees open: .worktrees/task-001, .worktrees/task-003
+```
 
-> Switch to **Opus / unic-smart** → run `/ukit:review-handoff`
+**Next:** switch to strong model → `/ukit:review-handoff`

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

@@ -1,61 +1,117 @@
-# /ukit:review-handoff
+# /ukit:review-handoff — Phase 4: Review
 
-Spawn **code-reviewer** agents (Opus / unic-smart — MUST differ from executor).
-After approval: merge worktree → delete branch + worktree.
+**Role: REVIEWER**
+**Tool: any** (Claude Code / Codex / Antigravity / Kilo / OpenCode — your choice)
+**Model: strong model, MUST differ from executor** (Opus · unic-smart · strongest available)
 
 ## Target (optional)
 $ARGUMENTS
-_Empty = all pending_review tasks. Or: "TASK-001" for a specific task._
+_Empty = all `pending_review` tasks. Or: "TASK-001" for a specific task._
 
 ---
 
-1. Read `docs/AI_HANDOFF/INDEX.md`
-   - Collect tasks with status `pending_review` (or specific task from $ARGUMENTS)
-   - If none → report and stop
+## Step 1 — Setup
 
-2. For each task — spawn a **code-reviewer** agent:
+Read `docs/AI_HANDOFF/ACTIVE.md` → get `Base: <BASE>`.
+Read `docs/AI_HANDOFF/INDEX.md` → collect `pending_review` tasks (or specific task).
+If none → report and stop.
 
+## Step 2 — Review each task
+
+**IMPORTANT: run tasks sequentially (not parallel) to avoid INDEX.md race conditions.**
+
+For each task:
+
+### 2a — Model isolation check (do this first, always)
+
+Read `EXECUTOR_MODEL` from `## Executor Report` in task file.
+
+| Executor model | Your model | Action |
+|----------------|------------|--------|
+| present, ≠ yours | present | proceed |
+| present, == yours | present | REFUSE → `changes_requested`: "reviewer model must differ from executor" |
+| missing / blank | any | REFUSE → `changes_requested`: "EXECUTOR_MODEL not reported — executor must re-run and fill in" |
+| "unknown" | present | proceed, add NOTES: "executor model unverified — human confirm before merge" |
+
+### 2b — Re-run verification (in the worktree, not main)
+
+```bash
+# Run INSIDE the task's worktree — not from root:
+cd .worktrees/task-xxx
+<each command from §Verification Commands>
 ```
-Review docs/AI_HANDOFF/tasks/TASK-xxx.md
-
-Inputs:
-  - Task file (Test Plan + Verification Commands + Executor Report)
-  - Diff: git -C .worktrees/task-xxx diff main
-
-Steps:
-  1. Read EXECUTOR_MODEL from Executor Report
-     → REFUSE if same as your model (or model unknown)
-  2. Re-run §Verification Commands fresh — do NOT trust executor output
-     → If FAIL → verdict: critical_block, stop
-  3. Review diff: correctness, regression risk, security, maintainability
-  4. Append ## Reviewer Verdict to task file:
-       VERDICT: approved | approved_minor | changes_requested | critical_block
-       REVIEWER_MODEL / EXECUTOR_MODEL
-       VERIFICATION_RERUN: result
-       FINDINGS: critical / important / minor
-       NEXT_STATUS_FOR_INDEX: <status>
-
-  5. Update INDEX.md: set status = NEXT_STATUS_FOR_INDEX
+
+If any command fails → verdict: `critical_block`. Stop — do not review code.
+
+### 2c — Review diff
+
+```bash
+# What this task added on top of its wave base:
+BASE_OF_TASK=$(git merge-base handoff/integration handoff/task-xxx)
+git diff $BASE_OF_TASK..handoff/task-xxx
 ```
 
-3. After each agent verdict:
+Check: correctness, regression risk, security, edge cases, maintainability.
 
-   **approved / approved_minor:**
-   ```bash
-   git merge handoff/task-xxx --no-ff -m "feat: merge TASK-xxx"
-   git worktree remove .worktrees/task-xxx
-   git branch -d handoff/task-xxx
-   # INDEX.md: status → done
-   ```
+### 2d — Append verdict to task file
 
-   **changes_requested / critical_block:**
-   ```
-   Keep worktree — executor must fix
-   Write findings in task file §Discussion
-   # INDEX.md: status → changes_requested | critical_block
-   ```
+```
+## Reviewer Verdict
+VERDICT: approved | approved_minor | changes_requested | critical_block
+REVIEWER_MODEL: <your exact model ID>
+EXECUTOR_MODEL: <from Executor Report>
+VERIFICATION_RERUN: PASS | FAIL
+FINDINGS:
+  critical: <file:line — what fails> | none
+  important: <file:line — risk> | none
+  minor: <style/naming> | none
+NEXT_STATUS_FOR_INDEX: approved | approved_minor | changes_requested | critical_block
+```
+
+### 2e — Orchestrator updates INDEX.md
+
+Set `status = NEXT_STATUS_FOR_INDEX` for this task.
+(Reviewer writes verdict to task file; orchestrator writes INDEX — same principle as implement.)
+
+## Step 3 — After all tasks reviewed: handle integration
+
+**Only if all tasks are `approved` or `approved_minor`:**
+
+```bash
+# Merge integration → BASE (single merge, one clean history entry)
+git checkout $BASE
+if git merge handoff/integration --no-ff -m "feat: handoff cycle complete"; then
+  # Cleanup all task worktrees + branches
+  for task in $(git worktree list | grep '.worktrees/task-' | awk '{print $1}'); do
+    name=$(basename $task)
+    git worktree remove $task --force
+    git branch -d handoff/$name 2>/dev/null || git branch -D handoff/$name
+  done
+  git branch -d handoff/integration
+  # INDEX.md: all approved tasks → done
+else
+  git merge --abort
+  # Report: unexpected conflict on integration→BASE merge. Human must resolve manually.
+fi
+```
+
+**If any task has `changes_requested` or `critical_block`:**
+Keep all worktrees and integration branch open.
+Report which tasks need fixes.
+
+## Step 4 — Report
+
+```
+Review summary:
+  TASK-001: approved — merged
+  TASK-002: changes_requested — see §Discussion
+  Integration: pending (TASK-002 needs fix first)
+  Worktrees remaining: .worktrees/task-002
+```
 
-4. Report: approved+merged tasks, tasks needing fixes, remaining worktrees
+**Next:**
+- All approved + merged → `/ukit:clear-handoff`
+- Has fixes → executor re-runs `/ukit:implement-handoff TASK-xxx`
 
-> All done? → `/ukit:clear-handoff`
-> Tasks need fixes? → human runs `/ukit:implement-handoff TASK-xxx`
+> Claude Code: spawn `code-reviewer` agent (opus) per task for Steps 2a–2e. Orchestrator handles Steps 1, 2e (INDEX write), and Step 3.
+> Other tools: use strong model sequentially per task, same steps.

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

@@ -0,0 +1,49 @@
+# /ukit:status-handoff — Dashboard (read-only)
+
+**Role: OBSERVER**
+**Tool: any**
+**Model: lite model** (haiku · unic-lite — read-only, no writes)
+
+---
+
+Read and display current handoff state. Do NOT modify any files.
+
+## Read
+
+1. `docs/AI_HANDOFF/ACTIVE.md` → cycle ID, goal, base branch
+2. `docs/AI_HANDOFF/INDEX.md` → all tasks + statuses
+3. `git worktree list` → open worktrees
+4. `git branch | grep handoff/` → open handoff branches
+
+## Report
+
+```
+━━━ Handoff Status ━━━━━━━━━━━━━━━━━━━━━━━━
+Cycle:  <ID>   Base: <branch>   Date: <date>
+Goal:   <goal>
+
+Tasks:
+  ✅ done          TASK-001  <name>
+  🔄 pending_review TASK-002  <name>
+  🔧 in_progress   TASK-003  <name>
+  🔴 blocked       TASK-004  <name>
+  ⏳ ready         TASK-005  <name>
+
+Summary: X done / Y pending_review / Z in_progress / ... / N total
+
+Worktrees open:
+  .worktrees/task-002  [handoff/task-002]
+  .worktrees/task-003  [handoff/task-003]
+
+Integration branch: handoff/integration [exists | not created yet]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Next action:
+  pending_review tasks → /ukit:review-handoff
+  ready tasks          → /ukit:implement-handoff
+  all done             → /ukit:clear-handoff
+  no active cycle      → /ukit:create-handoff <description>
+```
+
+> Claude Code: spawn `ukit-small-task-maintainer` (haiku) with the above prompt.
+> Other tools: use lite model, run the reads above, format the report.