@ngockhoale/ukit 1.5.19 → 1.5.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "1.5.19",
+  "version": "1.5.20",
   "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/create-handoff.md

@@ -10,6 +10,7 @@
 $ARGUMENTS
 
 > **Can be run multiple times.** If the plan or tasks aren't satisfactory after the first run, re-run `/ukit:create-handoff` to refine until the plan is good — as long as no task has been implemented yet.
+> **NO git commit. NO git push.** This phase only writes docs files. No code changes.
 
 ---
 

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

@@ -8,6 +8,8 @@
 $ARGUMENTS
 _Empty = all `ready` tasks. Or: "TASK-001" for a specific task._
 
+> **NO git commit. NO git push. Ever.** AI only makes file changes. Human commits when ready.
+
 ---
 
 ## Step 1 — Setup
@@ -16,11 +18,13 @@ Read `docs/AI_HANDOFF/ACTIVE.md` → get `Base: <BASE>`.
 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):
+Verify working tree is clean before starting:
 ```bash
-git branch handoff/integration $BASE 2>/dev/null || echo "already exists"
+git status   # must be clean — no uncommitted changes
 ```
 
+If working tree is dirty → stop. Ask human to commit or stash first.
+
 ## Step 2 — Build wave groups
 
 Read each `tasks/TASK-xxx.md` for `Dependencies` field:
@@ -33,15 +37,15 @@ Read each `tasks/TASK-xxx.md` for `Dependencies` field:
 
 For each wave:
 
-### 3a — Create worktrees (from `handoff/integration`)
+### 3a — Create worktrees (from `$BASE`, no extra branch)
 ```bash
-git worktree add -b handoff/task-xxx .worktrees/task-xxx handoff/integration
+git worktree add -b handoff/task-xxx .worktrees/task-xxx $BASE
 # (omit -b if branch already exists)
 ```
 
 ### 3b — Run tasks in parallel (one agent/session per task)
 
-Each executor does independently in its own worktree:
+Each executor works independently in its own worktree — **NO git commit, NO git add**:
 
 ```
 Read docs/AI_HANDOFF/tasks/TASK-xxx.md
@@ -55,17 +59,13 @@ TDD — mandatory:
      cd .worktrees/task-xxx && <each verification command>
      Paste full output.
 
-Commit in worktree:
-  git -C .worktrees/task-xxx add -A
-  git -C .worktrees/task-xxx commit -m "feat(TASK-xxx): <intent>"
-  COMMIT_SHA=$(git -C .worktrees/task-xxx rev-parse HEAD)
+DO NOT run: git add, git commit, git push — leave files as-is in worktree.
 
 Executor Report (append to task file — do NOT touch INDEX.md):
   ## Executor Report
   EXECUTOR_TOOL: <tool>
   EXECUTOR_MODEL: <exact model ID — mandatory>
   EXECUTOR_SUBAGENT: <name or "-">
-  COMMIT_SHA: <sha>
   Verification Output: <paste>
   Status: PASS | FAIL
   Note: <issues or "none">
@@ -74,25 +74,31 @@ Executor Report (append to task file — do NOT touch INDEX.md):
 > Claude Code: spawn `feature-implementer` agents in parallel (one per task).
 > Other tools: open each task in separate session with code model.
 
-### 3c — Orchestrator: merge + IMMEDIATELY delete worktree
+### 3c — Orchestrator: copy changes to main + IMMEDIATELY delete worktree
 
 For each task that reported back:
 
 **PASS + EXECUTOR_MODEL present:**
 ```bash
-git checkout handoff/integration
-if git merge handoff/task-xxx --no-ff -m "feat(TASK-xxx)" 2>/dev/null; then
-  # Delete worktree and branch immediately — no lingering
-  git worktree remove .worktrees/task-xxx --force
-  git branch -D handoff/task-xxx
-  # update INDEX.md: status → pending_review
-else
-  git merge --abort
-  git worktree remove .worktrees/task-xxx --force
-  git branch -D handoff/task-xxx
-  # update INDEX.md: status → merge_conflict
-  # append to §Discussion: conflict with <previously merged tasks>
-fi
+WORKTREE=".worktrees/task-xxx"
+
+# Copy modified tracked files to main working tree
+git -C "$WORKTREE" diff --name-only | while read f; do
+  mkdir -p "$(dirname "$f")"
+  cp "$WORKTREE/$f" "$f"
+done
+
+# Copy new untracked files
+git -C "$WORKTREE" ls-files --others --exclude-standard | while read f; do
+  mkdir -p "$(dirname "$f")"
+  cp "$WORKTREE/$f" "$f"
+done
+
+# Delete worktree and branch immediately
+git worktree remove "$WORKTREE" --force
+git branch -D handoff/task-xxx
+
+# update INDEX.md: status → pending_review
 ```
 
 **FAIL:**
@@ -113,31 +119,20 @@ git branch -D handoff/task-xxx
 **Worktrees are always deleted immediately** — no exceptions.
 
 ### 3d — Next wave
-Branch new worktrees from `handoff/integration` (now includes Wave N). Repeat 3a–3c.
+Create new worktrees from `$BASE`. Repeat 3a–3c.
 
-## Step 4 — Finalize: squash merge + cleanup
+## Step 4 — Finalize: verify cleanup
 
-All waves complete. Bring all changes back to `$BASE` as a staged diff — no auto-commit.
+All waves complete. Verify:
 
 ```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
+git worktree list        # must show only main worktree
+git branch | grep handoff  # must be empty
+git status               # shows uncommitted changes — this is expected
+git diff --stat          # summary of everything that changed
 ```
 
-All changes are now **staged on `$BASE`**. No branches or worktrees remain.
+All changes are in the **main working tree as uncommitted files**. No branches or worktrees remain.
 
 ## Step 5 — Report
 
@@ -145,8 +140,8 @@ All changes are now **staged on `$BASE`**. No branches or worktrees remain.
 Wave summary:
   Wave 1: TASK-001 [pending_review], TASK-002 [blocked]
   Wave 2: TASK-003 [pending_review]
-All branches and worktrees removed.
-Staged diff on $BASE — ready for review.
+All worktrees and branches removed.
+Uncommitted changes in working tree — human commits when ready.
 ```
 
 **Next:** switch to strong model → `/ukit:review-handoff`

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

@@ -8,6 +8,8 @@
 $ARGUMENTS
 _Empty = all `pending_review` tasks. Or: "TASK-001" for a specific task._
 
+> **NO git commit. NO git push.** Reviewer only reads and reports. Human decides when to commit.
+
 ---
 
 ## Step 1 — Setup
@@ -16,15 +18,15 @@ 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.
 
-Verify we are on `$BASE` with staged changes from implement-handoff:
+Verify there are uncommitted changes from implement-handoff:
 ```bash
-git status          # should show staged changes, no handoff branches/worktrees
-git diff --staged --stat   # summary of everything implement-handoff merged
+git status           # should show modified/new files, no handoff branches/worktrees
+git diff --stat      # summary of all changes
 ```
 
-If `git diff --staged` is empty → implement-handoff was not completed. Stop and re-run it.
+If `git diff` is empty and `git status` is clean → implement-handoff was not completed. Stop and re-run it.
 
-## Step 2 — Review the staged diff
+## Step 2 — Review the diff
 
 ### 2a — Model isolation check (always first)
 
@@ -37,7 +39,7 @@ Read `EXECUTOR_MODEL` from each 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 staged working tree)
+### 2b — Re-run verification
 
 ```bash
 <each command from §Verification Commands across all tasks>
@@ -48,7 +50,8 @@ If any command fails → verdict: `critical_block`. Stop.
 ### 2c — Review unified diff
 
 ```bash
-git diff --staged        # full staged diff vs $BASE
+git diff             # all uncommitted changes vs $BASE
+git status           # overview of modified/new/deleted files
 ```
 
 Review as one unified diff — correctness, regression risk, security, edge cases, maintainability.
@@ -79,26 +82,20 @@ Set `status = NEXT_STATUS_FOR_INDEX`. Orchestrator writes INDEX, not the reviewe
 
 Update INDEX.md: all approved tasks → `done`.
 
-Commit the staged changes:
-```bash
-git add docs/AI_HANDOFF/
-git commit -m "feat: complete handoff cycle"
-git push origin $BASE
-```
+**DO NOT commit. DO NOT push.** Leave the working tree as-is for human review.
 
 Report:
 ```
-✅ All tasks approved and committed to $BASE.
-Handoff cycle complete.
+✅ All tasks approved.
+Uncommitted changes are in the working tree — human commits when ready.
+  git diff --stat     ← review summary
+  git add . && git commit -m "..."   ← when ready
 ```
 
 **Any `changes_requested` or `critical_block`:**
 
-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`.
+Report which files need fixes. Executor re-runs `/ukit:implement-handoff TASK-xxx`.
+Changes from the failed task remain in the working tree — executor fixes them in place (no new worktree needed for simple fixes).
 
 ## Step 4 — Report
 
@@ -106,12 +103,12 @@ Report which tasks need fixes. Executor re-runs `/ukit:implement-handoff TASK-xx
 Review summary:
   TASK-001: approved
   TASK-002: changes_requested — see §Discussion
-  Result: committed to $BASE | changes requested (staged reset, re-implement needed)
+  Working tree: unchanged — human commits when satisfied
 ```
 
 **Next:**
-- All approved → done. Committed to `$BASE`.
-- Has fixes → unstage (`git restore --staged .`) + executor re-runs `/ukit:implement-handoff TASK-xxx`
+- All approved → human reviews `git diff` and commits manually.
+- Has fixes → 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.