@ngockhoale/ukit 1.5.17 → 1.5.18

package/package.json

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

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

@@ -1,82 +1,47 @@
-# /ukit:clear-handoff — Archive + Reset
+# /ukit:clear-handoff — Emergency Reset
 
-**Role: CLEANUP**
+**Role: CLEANUP UTILITY**
 **Tool: any**
-**Model: lite model** (haiku · unic-lite · cheapest — this is file ops only)
+**Model: lite model** (haiku · unic-lite · cheapest — file ops + git cleanup only)
 
-**HARD GATE: Will NOT clear if any task is not `done`.**
+**Use when:** handoff cycle is stuck, abandoned, or you want to wipe and start fresh.
+**Not a step in the main process** — main flow is: create → implement → review.
 
 ---
 
-## 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 status ≠ `done` → **STOP**. Report and exit:
-
-```
-⛔ 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
-
-Fix all tasks first, then re-run /ukit:clear-handoff.
-```
-
-Only continue if ALL tasks are `done`.
-
-## Step 2 — Merge + commit + push to $BASE
-
-This is the **only step in the entire handoff that commits and pushes to the base branch.**
+## Step 1 — Force-remove all handoff worktrees and branches
 
 ```bash
-git checkout $BASE
-
-# Stage handoff planning docs (written to workspace during create-handoff, never committed yet)
-git add docs/AI_HANDOFF/
-if ! git diff --staged --quiet; then
-  git commit -m "docs(handoff): add cycle planning artifacts"
-fi
-
-# Merge integration branch (code changes from implement-handoff worktrees)
-if git merge handoff/integration --no-ff -m "feat: complete handoff cycle"; then
-  git push origin $BASE
-  git branch -D handoff/integration
-else
-  git merge --abort
-  echo "⛔ Merge conflict on handoff/integration → $BASE. Resolve manually, then re-run /ukit:clear-handoff."
-  exit 1
-fi
-```
+# Remove task worktrees
+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
+git worktree prune
 
-## Step 3 — Cleanup stray worktrees (safety net)
+# Remove integration branch if still exists
+git branch -D handoff/integration 2>/dev/null || true
+```
 
-Task worktrees are deleted immediately during implement — none should remain. Safety net only:
+## Step 2 — Unstage any pending changes
 
 ```bash
-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
-
-git worktree prune
+git restore --staged . 2>/dev/null || true
 ```
 
-## Step 4 — Archive cycle
+## Step 3 — Archive whatever is done (best-effort)
 
-Read INDEX.md for cycle ID and task list.
-Write `docs/AI_HANDOFF/archive/cycle-NNN.md`:
+Read `docs/AI_HANDOFF/INDEX.md` for any tasks that were completed.
+Write `docs/AI_HANDOFF/archive/cycle-NNN.md` (if there is anything worth archiving):
 ```
-# Cycle NNN — <YYYY-MM-DD>   Base: <BASE>
-## Summary: <1 paragraph of what was accomplished>
-## Tasks: <copy INDEX.md table>
+# Cycle NNN — <YYYY-MM-DD> — ABORTED
+## Summary: cycle was cleared before completion
+## Tasks: <copy INDEX.md table as-is>
 ```
 If `archive/` has > 3 files → delete oldest, append 1-line summary to `HISTORY.md`.
 
-## Step 5 — Reset state files
+## Step 4 — Reset state files
 
 ```
 PLAN.md  → "# PLAN\n_(empty)_"
@@ -85,11 +50,14 @@ ACTIVE.md → "# ACTIVE\n_(no active cycle)_"
 tasks/TASK-*.md → delete all (keep _TEMPLATE.md)
 ```
 
-## Step 6 — Report
+## Step 5 — Report
 
-Cycle NNN merged + pushed to $BASE. X tasks completed. Worktrees removed. Ready for new cycle.
+```
+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) with steps 1–6.
-> Other tools: use lite model, follow steps 1–6 above.
+> Claude Code: spawn `ukit-small-task-maintainer` (haiku).
+> Other tools: lite model, follow steps 1–5.
 
 **Next:** `/ukit:create-handoff <new problem description>`

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

@@ -115,14 +115,38 @@ git branch -D handoff/task-xxx
 ### 3d — Next wave
 Branch new worktrees from `handoff/integration` (now includes Wave N). Repeat 3a–3c.
 
-## Step 4 — Report
+## Step 4 — Finalize: squash merge + cleanup
+
+All waves complete. Bring all changes back to `$BASE` as a staged diff — no auto-commit.
+
+```bash
+git checkout $BASE
+
+# Stage all integration changes without committing
+git merge --squash handoff/integration
+
+# Delete integration branch
+git branch -D handoff/integration
+
+# Safety-net: remove any stray task worktrees/branches
+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
+git worktree prune
+```
+
+All changes are now **staged on `$BASE`**. No branches or worktrees remain.
+
+## Step 5 — 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)
-No worktrees remaining.
+All branches and worktrees removed.
+Staged diff on $BASE — ready for review.
 ```
 
 **Next:** switch to strong model → `/ukit:review-handoff`

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

@@ -16,18 +16,19 @@ 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.
 
-Checkout integration branch for verification:
+Verify we are on `$BASE` with staged changes from implement-handoff:
 ```bash
-git checkout handoff/integration
+git status          # should show staged changes, no handoff branches/worktrees
+git diff --staged --stat   # summary of everything implement-handoff merged
 ```
 
-## Step 2 — Review each task (sequential — no parallel to avoid INDEX race)
+If `git diff --staged` is empty → implement-handoff was not completed. Stop and re-run it.
 
-For each task:
+## Step 2 — Review the staged diff
 
 ### 2a — Model isolation check (always first)
 
-Read `EXECUTOR_MODEL` from task file `## Executor Report`.
+Read `EXECUTOR_MODEL` from each task file `## Executor Report`.
 
 | Executor model | Your model | Action |
 |----------------|------------|--------|
@@ -36,26 +37,24 @@ Read `EXECUTOR_MODEL` from task file `## Executor Report`.
 | missing / blank | any | REFUSE → `changes_requested`: "EXECUTOR_MODEL missing — re-run implement" |
 | "unknown" | present | proceed + NOTES: "executor model unverified — human confirm" |
 
-### 2b — Re-run verification (on integration branch, no worktree needed)
+### 2b — Re-run verification (on staged working tree)
 
 ```bash
-# Already on handoff/integration from Step 1
-<each command from task §Verification Commands>
+<each command from §Verification Commands across all tasks>
 ```
 
 If any command fails → verdict: `critical_block`. Stop.
 
-### 2c — Review diff (per task, using COMMIT_SHA from Executor Report)
+### 2c — Review unified diff
 
 ```bash
-COMMIT_SHA=<from Executor Report>
-git show $COMMIT_SHA          # what this task changed
-git diff $COMMIT_SHA^..$COMMIT_SHA  # same, as diff format
+git diff --staged        # full staged diff vs $BASE
 ```
 
-Check: correctness, regression risk, security, edge cases, maintainability.
+Review as one unified diff — correctness, regression risk, security, edge cases, maintainability.
+Cross-reference with each task's intent in `docs/AI_HANDOFF/tasks/TASK-xxx.md`.
 
-### 2d — Append verdict to task file
+### 2d — Append verdict to each task file
 
 ```
 ## Reviewer Verdict
@@ -80,17 +79,26 @@ Set `status = NEXT_STATUS_FOR_INDEX`. Orchestrator writes INDEX, not the reviewe
 
 Update INDEX.md: all approved tasks → `done`.
 
-**STOP. Do not commit, do not push, do not merge.** Only `docs/AI_HANDOFF/` was touched during this entire cycle. The merge + commit + push happens exclusively in `/ukit:clear-handoff`.
+Commit the staged changes:
+```bash
+git add docs/AI_HANDOFF/
+git commit -m "feat: complete handoff cycle"
+git push origin $BASE
+```
 
 Report:
-
 ```
-✅ All tasks approved. Cycle ready to finalize.
-Run: /ukit:clear-handoff
+✅ All tasks approved and committed to $BASE.
+Handoff cycle complete.
 ```
 
 **Any `changes_requested` or `critical_block`:**
-Keep `handoff/integration` open. Report which tasks need fixes.
+
+Do NOT commit. Unstage all changes and re-open the cycle:
+```bash
+git restore --staged .
+```
+Report which tasks need fixes. Executor re-runs `/ukit:implement-handoff TASK-xxx`.
 
 ## Step 4 — Report
 
@@ -98,12 +106,12 @@ Keep `handoff/integration` open. Report which tasks need fixes.
 Review summary:
   TASK-001: approved
   TASK-002: changes_requested — see §Discussion
-  Integration: ready for clear-handoff | pending (fix TASK-002 first)
+  Result: committed to $BASE | changes requested (staged reset, re-implement needed)
 ```
 
 **Next:**
-- All approved → `/ukit:clear-handoff` (does the merge + commit + push)
-- Has fixes → executor re-runs `/ukit:implement-handoff TASK-xxx`
+- All approved → done. Committed to `$BASE`.
+- Has fixes → unstage (`git restore --staged .`) + executor re-runs `/ukit:implement-handoff 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.