@ngockhoale/ukit 1.5.11 → 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.11",
+  "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

@@ -2,7 +2,7 @@
 
 **Role: CLEANUP**
 **Tool: any**
-**Model: lite model** (haiku · unic-lite · cheapest available — this is just file ops)
+**Model: lite model** (haiku · unic-lite · cheapest — this is file ops only)
 
 **HARD GATE: Will NOT clear if any task is not `done`.**
 
@@ -11,52 +11,61 @@
 ## Step 1 — Gate check (mandatory, cannot skip)
 
 Read `docs/AI_HANDOFF/INDEX.md`. List every task + status.
+Read `docs/AI_HANDOFF/ACTIVE.md` → get `Base: <BASE>`.
 
-If ANY task has status ≠ `done` → **STOP**. Report and exit:
+If ANY task status ≠ `done` → **STOP**. Report and exit:
 
 ```
 ⛔ 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
-  TASK-005 [ready]             → run /ukit:implement-handoff TASK-005
+  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
 
 Fix all tasks first, then re-run /ukit:clear-handoff.
 ```
 
-Only proceed if ALL tasks are `done`.
+Only continue if ALL tasks are `done`.
 
-## Step 2 — Cleanup worktrees
+## Step 2 — Cleanup worktrees + branches
 
 ```bash
-git worktree list | grep handoff/
-# For each .worktrees/task-xxx:
-git worktree remove .worktrees/task-xxx --force
-git branch -D handoff/task-xxx
+# 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
+
+# Remove integration branch if still exists
+git branch -D handoff/integration 2>/dev/null
+
 git worktree prune
 ```
 
 ## Step 3 — Archive cycle
 
+Read INDEX.md for cycle ID and task list.
 Write `docs/AI_HANDOFF/archive/cycle-NNN.md`:
 ```
-# Cycle NNN — <YYYY-MM-DD>
+# 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 to `HISTORY.md`.
+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.

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

@@ -13,51 +13,64 @@ $ARGUMENTS
 
 ## Step 1 — Read context (lite model)
 
-Use the lightest/cheapest model available. Read and summarize:
+Use the lightest model available. Read and summarize:
 
 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
 
-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) with the above prompt.
-> Other tools: switch to your lite model, run the above steps, keep the summary in context.
+> Claude Code: spawn `ukit-small-task-maintainer` (haiku).
+> Other tools: switch to lite model, run above, keep summary in context.
 
 ---
 
 ## Step 2 — Write plan + tasks (strong model)
 
-Switch to strongest model. Using the summary from Step 1 (do NOT re-read files):
+Switch to strongest model. Use Step 1 summary — do NOT re-read files.
 
 1. If INDEX.md has undone tasks → warn human: continue old cycle or start fresh?
 
-2. Write `docs/AI_HANDOFF/PLAN.md` — all 6 sections mandatory:
+2. Resolve base branch:
+   ```bash
+   BASE=$(git symbolic-ref --short HEAD)
+   ```
+
+3. Write `docs/AI_HANDOFF/PLAN.md` — all 6 sections mandatory:
    - §1 Intent — problem + success definition
-   - §2 Scope — in / out of scope
+   - §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
+   - §6 Acceptance — done checklist (prefer verifiable criteria with commands)
 
-3. Create `docs/AI_HANDOFF/tasks/TASK-001.md`, `TASK-002.md`... from `_TEMPLATE.md`
+4. Create `docs/AI_HANDOFF/tasks/TASK-001.md`, `TASK-002.md`... from `_TEMPLATE.md`
    Every task MUST have:
-   - Target Files (exact paths)
-   - Dependencies (`TASK-xxx` or `none`)
+   - 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 (checklist)
+   - Acceptance Criteria (verifiable checklist)
    Missing any field → status: `needs_breakdown`, never `ready`
 
-4. Update `INDEX.md` — one row per task, `status=ready`
-5. Update `ACTIVE.md` — cycle snapshot + wave structure (Wave 1 = no deps, Wave 2 = depends on Wave 1...)
+5. Update `INDEX.md` — one row per task, `status=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.
 
-6. Report: task IDs, wave map, any `needs_breakdown` + reason
+7. Report: task IDs, dependency graph, any `needs_breakdown` + reason
 
-> Claude Code: spawn `handoff-planner` (opus) with Step 1 summary + problem injected.
-> Other tools: switch to strong model, execute steps 1–6 above.
+> Claude Code: spawn `handoff-planner` (opus) with Step 1 summary + problem.
+> Other tools: switch to strong model, execute steps 1–7 above.
 
 ---
 

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

@@ -1,8 +1,8 @@
 # /ukit:implement-handoff — Phase 3: Execute
 
-**Role: EXECUTOR**
+**Role: EXECUTOR (orchestrated)**
 **Tool: any** (Claude Code / Codex / Antigravity / Kilo / OpenCode — your choice)
-**Model: code model** (Sonnet · unic-code · cheap-smart available)
+**Model: code model** (Sonnet · unic-code · cheap-smart)
 
 ## Target (optional)
 $ARGUMENTS
@@ -10,47 +10,100 @@ _Empty = all `ready` tasks. Or: "TASK-001" for a specific task._
 
 ---
 
-1. Read `docs/AI_HANDOFF/INDEX.md`
-   - Collect all tasks with status `ready` (or specific task from $ARGUMENTS)
-   - If none → report and stop
-
-2. Group into waves by dependency:
-   - Wave 1: `dependencies: none` or all deps already `done`
-   - Wave 2+: depends on previous wave
-
-3. For each wave — run tasks **in parallel** (one agent/session per task):
-
-   **Each task executor does:**
-
-   ```
-   Worktree (isolated per task):
-     git worktree add -b handoff/task-xxx .worktrees/task-xxx
-     (omit -b if branch already exists)
-
-   TDD — mandatory:
-     1. Read §Test Cases from task file
-     2. Write tests → run → confirm RED
-     3. Implement → run → confirm GREEN
-     4. Run §Verification Commands → paste full output
-
-   Executor Report (append to task file):
-     ## Executor Report
-     EXECUTOR_TOOL: <tool name>
-     EXECUTOR_MODEL: <exact model ID — must be honest, reviewer will check>
-     Verification Output: <paste>
-     Status: PASS | FAIL
-
-   Update INDEX.md: status → pending_review
-
-   If FAIL → fix in same worktree before updating status.
-   Never mark pending_review while tests still fail.
-   ```
-
-   > Claude Code: spawn `feature-implementer` agent per task (parallel).
-   > Other tools: open each task in a separate session/tab with code model, follow steps above.
-
-4. Wait for all tasks in wave → run next wave if any
-
-5. Report: PASS/FAIL per task, worktrees created, blockers
+## Step 1 — Setup
+
+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.
+
+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)
+```
+
+### 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: 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 from INSIDE the worktree:
+     cd .worktrees/task-xxx && <each verification command>
+     Paste full output.
+
+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">
+```
+
+> Claude Code: spawn `feature-implementer` agents in parallel (one per task).
+> Other tools: open each task in a separate session with code model.
+
+### 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
+
+**Orchestrator writes INDEX.md** — agents never touch INDEX directly.
+
+### 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
+```
 
 **Next:** switch to strong model → `/ukit:review-handoff`

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

@@ -10,63 +10,108 @@ _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
-
-2. For each task — **MUST use a different model than the executor**:
-
-   ```
-   Read task file: docs/AI_HANDOFF/tasks/TASK-xxx.md
-
-   Model isolation check (first thing):
-     Read EXECUTOR_MODEL from Executor Report
-     → REFUSE if your model == EXECUTOR_MODEL (or either is unknown)
-     → This is non-negotiable. Same model reviewing its own work defeats the quality gate.
-
-   Re-run §Verification Commands fresh:
-     → Do NOT trust executor's output. Run them yourself.
-     → If FAIL → verdict: critical_block. Stop.
-
-   Review diff:
-     git -C .worktrees/task-xxx diff main
-     Check: correctness, regression risk, security, edge cases, maintainability
-
-   Append ## Reviewer Verdict to task file:
-     VERDICT: approved | approved_minor | changes_requested | critical_block
-     REVIEWER_MODEL: <your model>
-     EXECUTOR_MODEL: <from report>
-     VERIFICATION_RERUN: PASS | FAIL
-     FINDINGS:
-       critical: ...
-       important: ...
-       minor: ...
-     NEXT_STATUS_FOR_INDEX: <status>
-
-   Update INDEX.md: status = NEXT_STATUS_FOR_INDEX
-   ```
-
-   > Claude Code: spawn `code-reviewer` agent (opus) per task.
-   > Other tools: switch to strong model (different from executor), follow steps above per task.
-
-3. After each verdict:
-
-   **approved / approved_minor →** merge + cleanup:
-   ```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
-   ```
-
-   **changes_requested / critical_block →** keep worktree for executor to fix:
-   ```
-   Write findings in §Discussion of task file
-   # INDEX.md: status → changes_requested | critical_block
-   ```
-
-4. Report: merged tasks, tasks needing fixes, remaining worktrees
+## Step 1 — Setup
+
+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>
+```
+
+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
+```
+
+Check: correctness, regression risk, security, edge cases, maintainability.
+
+### 2d — Append verdict to task file
+
+```
+## 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
+```
 
 **Next:**
-- All done → `/ukit:clear-handoff`
-- Has fixes → executor runs `/ukit:implement-handoff TASK-xxx`
+- All approved + merged → `/ukit:clear-handoff`
+- Has fixes → executor re-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.