@ngockhoale/ukit 2.0.6 → 2.1.0

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

@@ -22,6 +22,66 @@ $ARGUMENTS
 
 ---
 
+## Autonomy Contract — read before anything else
+
+This command is a **one-shot pipeline**. The human is not watching. Treat every phase below
+as unattended: they may walk away after submitting `$ARGUMENTS` and come back to a finished
+result.
+
+**The single question window is P0, before any file is written.** If `$ARGUMENTS` leaves a
+choice that would change what gets built — not how it gets built — batch every such question
+into **one** `AskUserQuestion` call (max 4 questions, each with a `(Recommended)` first
+option) and resolve them all at once. Record the answers in `PLAN.md` §1.
+
+**After P0 closes, do not ask the human anything until the Final Report.** Every decision
+point in the phases below has a defined automatic resolution. Take it. Specifically:
+
+| Situation | Old behavior | Required behavior now |
+|-----------|--------------|----------------------|
+| Scope spans multiple subsystems | wait for confirmation | decompose into sequential cycles, run cycle 1 now, queue the rest in `INDEX.md` |
+| Plan review returns `Issues Found` | up to 3 rounds, then stop | 1 revision round; if round 2 still has findings, apply them and proceed — log to `## Plan Review Log` |
+| Two same-wave tasks share a file | STOP | move the later task to the next wave (add the dependency), continue |
+| INDEX has `pending_review`/`blocked` tasks | STOP | **resume** — see Resume below |
+| Reviewer returns `changes_requested`/`critical_block` | report and stop | run the Phase 4 auto-fix loop (max 2 rounds) |
+| Verification command fails | stop | fix and re-verify inside the auto-fix loop |
+
+Escalate to the human **only** for: a blocker outside the repo (missing credential, external
+service down), or a task still failing after both auto-fix rounds. Even then, finish every
+other task first and report what was left undone.
+
+**Never pause to ask for `/compact`.** Context is managed structurally — subagents write full
+logs to disk and return short summaries (see 3b), and the run cursor makes the pipeline
+resumable. If compaction does happen, the run resumes from the cursor automatically.
+
+### Run cursor — write after every step
+
+Maintain `docs/AI_HANDOFF/RUN.md`. Rewrite it (whole file, 6 lines) immediately after every
+numbered step completes:
+
+```
+Command: handoff-fullstack
+Goal: <one sentence from $ARGUMENTS>
+Base: <BASE branch>
+Phase: <P1|P2|P2.5|P3|I1|I2|I3|I4|R1|R2|R3|R4|R5|done>
+Cursor: wave <N> batch <M> — <what just finished>
+Next: <the exact next step to run>
+```
+
+This file is the resume contract. It costs one small write per step and is what turns an
+interrupted run into a continuable one.
+
+### Resume — when the run is re-invoked mid-flight
+
+If `docs/AI_HANDOFF/RUN.md` exists with `Phase:` not `done`, this is a **continuation, not a
+new cycle**. Do NOT re-plan, do NOT overwrite `PLAN.md`, do NOT ask the human whether to
+continue. Read the cursor, then jump straight to `Next:` and carry on. Tasks already `done`
+or `pending_review` are skipped; only `ready`, `in_progress`, `changes_requested` and
+`blocked` tasks are picked up.
+
+Only when `RUN.md` is absent or `Phase: done` does `$ARGUMENTS` start a fresh cycle.
+
+---
+
 ## Phase 1+2 — Plan (strong model)
 
 ### P1 — Read context (lite model)
@@ -45,7 +105,7 @@ 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).
-   - Any task has status `pending_review`, `changes_requested`, `merge_conflict`, or `blocked` → **STOP**: warn the human — tasks are already in implement/review phase, cannot overwrite safely.
+   - Any task has status `pending_review`, `changes_requested`, `merge_conflict`, or `blocked` → **do not overwrite, and do not stop either.** Mid-flight work exists. Skip the rest of P2 entirely, write the run cursor with `Phase: I1`, and hand control back to the orchestrator to resume from Phase 3 with the surviving tasks (see Resume in the Autonomy Contract). Overwriting is what is unsafe here — stopping is not required.
    - No tasks → fresh cycle, proceed.
 
 2. **Resolve base branch:**
@@ -57,7 +117,7 @@ The planner agent does the following (use P1 summary — do NOT re-read files):
    - §1 Intent — problem + success definition
    - §2 Scope — in / out of scope; same-wave tasks must not modify the same file (prevents merge conflicts)
    - §3 Approach — solution, trade-offs, alternatives rejected
-   - §4 Test Plan — happy path + ≥1 edge case + regression if bugfix (non-negotiable)
+   - §4 Test Plan — happy path + ≥2 edge cases of different kinds + regression if bugfix (non-negotiable)
    - §5 Verification — exact shell commands executor will run
    - §6 Acceptance — done checklist (prefer verifiable criteria with commands)
 
@@ -71,7 +131,7 @@ The planner agent does the following (use P1 summary — do NOT re-read files):
    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)
-   - Test Cases (Type | Name | Expected — ≥1 happy + ≥1 edge case)
+   - Test Cases (Type | Name | Expected — ≥1 happy + ≥2 edge cases of different kinds)
    - Test Files (exact paths)
    - Verification Commands (runnable shell commands)
    - Acceptance Criteria (verifiable checklist)
@@ -89,6 +149,25 @@ The planner agent does the following (use P1 summary — do NOT re-read files):
 
 7. **Report:** task IDs, dependency graph, any `needs_breakdown` tasks + reason.
 
+### P2.5 — Independent plan review (strong model, separate agent)
+
+**Loop cap — check first:** count `### Round` entries in PLAN.md's `## Plan Review Log` (0 if the section doesn't exist yet).
+
+- count = 0 → run the review below.
+- count = 1 and the round returned `Issues Found` → planner revises once, then run **one** more review round.
+- count ≥ 2 → do NOT invoke the reviewer again. **Do not stop and do not ask the human.** Have the planner apply every outstanding finding directly to `PLAN.md` and the affected `TASK-xxx.md` files, append `### Round <N> — findings applied without re-review` to the Plan Review Log listing what was changed, then proceed to P3.
+
+The gate still does its job — two independent opus passes shape the plan before a line of code
+is written. What it no longer does is hand a stalled plan back to a human who isn't there.
+
+**Claude Code — MANDATORY, do this before anything else in P2.5:** call the Agent tool with `subagent_type: "code-reviewer"`, passing `REVIEW_TARGET_TYPE=plan` and the path to `docs/AI_HANDOFF/PLAN.md`. This MUST be a separate agent invocation from P2's `handoff-planner` call (fresh context) — same-session self-review defeats the purpose of an independent gate.
+
+1. Reviewer reads `PLAN.md` only (no diff, no task files, no executor report), checks Completeness / Consistency / Clarity / Scope / YAGNI — see `.claude/agents/code-reviewer.md` → Spec/Plan Review — and appends its verdict to PLAN.md's `## Plan Review Log` (new round entry, prior rounds kept).
+2. `Issues Found` → route back to P2: `handoff-planner` revises `PLAN.md` and the affected `TASK-xxx.md` files to address every finding, then re-submit for one more P2.5 review round — subject to the loop cap above.
+3. `Approved` → append `PLAN_REVIEW: Approved by <reviewer model>` to PLAN.md's `## Planner Report` footer, then proceed to P3.
+
+> Other tools without subagent support: manually switch to the strong model in a **separate** chat/session from P2, paste PLAN.md, review using the Spec/Plan Review checklist in `.claude/agents/code-reviewer.md`.
+
 ### P3 — Commit the plan (lite model)
 
 **Claude Code — MANDATORY:** call the Agent tool with `subagent_type: "ukit-small-task-maintainer"` for this commit step (lite tier — haiku/unic-lite). Run:
@@ -117,7 +196,11 @@ Verify working tree is clean after the plan commit:
 git status   # must be clean — plan commit already done in P3
 ```
 
-If working tree is dirty → stop. Ask human to resolve uncommitted changes first.
+If the working tree is dirty, do not stop. Commit the stragglers as a checkpoint so they stay
+recoverable and the wave copy-back starts from a known state:
+```bash
+git add -A && git commit -m "handoff: checkpoint before implement"
+```
 
 ### I2 — Infer wave groups
 
@@ -127,8 +210,20 @@ Read each `docs/AI_HANDOFF/tasks/TASK-xxx.md` for `Dependencies` field:
 - Chain A→B→C = 3 waves of 1 task each (sequential)
 - Independent A, B, C = 1 wave of 3 tasks (parallel)
 
+**Conflict check — mandatory, before spawning any wave.** For every pair of tasks landing in
+the same wave, compare their `Target Files` lists. If any file path appears in both, **resolve
+it automatically — do not stop.** Keep the lower-numbered task in the current wave and push
+the other one into the next wave by adding `Dependencies: TASK-<lower>` to its task file. Two
+tasks that touch the same file are safe as long as they never run concurrently, and
+serializing them is the one resolution that is always correct. Note the demotion in the wave
+plan and in `RUN.md`.
+
+This is the code-level safety net for the planner's own §2 Scope constraint (same-wave tasks
+must not share a file) in case it slipped through review. Only mark a task `needs_breakdown`
+if it is missing required fields — never merely for sharing a file.
+
 **Batch each wave — mandatory.** Read `handoff.maxParallelAgents` from
-`.ukit/storage/config.json` (default **3**). A wave with more tasks than that is split
+`.ukit/storage/config.json` (default **10**). A wave with more tasks than that is split
 into consecutive batches of at most that many; finish one batch completely (including 3c
 copy-back and worktree deletion) before starting the next.
 
@@ -139,7 +234,7 @@ leaves worktrees behind. Batching only ever narrows a wave, never reorders acros
 
 ### 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 the current batch** (in parallel, at most `handoff.maxParallelAgents` — default 3), 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.
+**Claude Code — MANDATORY, do this before anything else in I3:** for each wave, call the Agent tool once per task **in the current batch** (in parallel, at most `handoff.maxParallelAgents` — default 10), 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:
 
@@ -156,7 +251,8 @@ Read docs/AI_HANDOFF/tasks/TASK-xxx.md
 TDD — mandatory:
   1. Write tests from §Test Cases
      cd .worktrees/task-xxx && <test command>
-     Confirm RED (immediately GREEN → test is wrong — flag this)
+     Confirm RED — paste the actual failing output, don't just assert it happened
+     (immediately GREEN → test is wrong — flag this)
   2. Implement → run → confirm GREEN
   3. Run §Verification Commands inside the worktree:
      cd .worktrees/task-xxx && <each verification command>
@@ -169,9 +265,25 @@ Executor Report (append to task file — do NOT touch INDEX.md):
   EXECUTOR_TOOL: <tool>
   EXECUTOR_MODEL: <exact model ID — mandatory>
   EXECUTOR_SUBAGENT: <name or "-">
+  RED_OUTPUT: <paste the actual failing-test output from step 1 — a claim like
+               "confirmed" without pasted output is not acceptable>
   Verification Output: <paste full output>
   Status: PASS | FAIL
   Note: <issues or "none">
+
+Then RETURN TO THE ORCHESTRATOR AT MOST 10 LINES, in exactly this shape:
+  TASK: TASK-xxx
+  STATUS: PASS | FAIL
+  EXECUTOR_MODEL: <exact model ID>
+  FILES: <comma-separated changed paths>
+  RED: confirmed | not-confirmed
+  VERIFY: <n> commands, all pass | <first failing command + one-line reason>
+  NOTE: <one line or "none">
+
+Do NOT repeat RED_OUTPUT or verification logs in the returned message. They are already
+written to the task file on disk, which is where the reviewer reads them from. Pasting
+them back a second time is what blows up the orchestrator's context window and kills the
+run mid-pipeline.
 ```
 
 **3c — Copy changes back + delete worktrees** (orchestrator, after each task reports):
@@ -212,6 +324,36 @@ git branch -D handoff/task-xxx
 
 Worktrees are **always deleted immediately** — no exceptions.
 
+**3d — Wave boundary: commit + context checkpoint** (orchestrator, after every wave)
+
+A wave boundary is the only safe place to shed context, because everything of value is
+already on disk (task files hold the full logs, git holds the code). Do all four, in order:
+
+1. **Checkpoint the code** — one commit per wave, so every wave is independently revertible:
+   ```bash
+   git add -A && git commit -m "handoff: wave <N> — TASK-00x, TASK-00y"
+   ```
+   Do not push here; the single push happens at R5.
+
+2. **Update the run cursor** — rewrite `docs/AI_HANDOFF/RUN.md` with `Phase: I3`,
+   `Cursor: wave <N> done`, `Next: wave <N+1>` (or `I4` if that was the last wave).
+
+3. **Collapse the wave in working memory.** From this point on, refer to the finished wave
+   only by its one-line-per-task summary (`TASK-xxx PASS <files>`). Do not re-read the task
+   files, do not restate executor reports, do not quote diffs from earlier waves. Anything
+   the reviewer needs, the reviewer reads from disk itself.
+
+4. **Check the pressure before spawning the next wave.** If a UKit context warning has fired
+   this run, or the wave just finished involved more than ~5 agents, state one line —
+   `context checkpoint: wave <N> collapsed, <M> tasks summarized` — and continue anyway. Do
+   not ask the human to run `/compact`, and do not abandon the run. If the session is
+   compacted or restarted for any reason, `RUN.md` plus the `SessionStart` resume hook bring
+   the pipeline back exactly here.
+
+With a ~200k window and per-task returns capped at 10 lines (3b), a wave of 10 tasks costs
+the orchestrator roughly 100 lines instead of the thousands that pasted RED and verification
+logs used to cost. That difference is what makes a multi-wave cycle finish in one run.
+
 ### I4 — Consolidate + update INDEX (lite model)
 
 **Claude Code — MANDATORY:** call the Agent tool with `subagent_type: "ukit-small-task-maintainer"` for I4. After all waves complete, ask it to:
@@ -244,13 +386,21 @@ git status       # should show modified/new files, no handoff branches/worktrees
 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.
+Because 3d commits each wave, the changes under review are in **commits since the plan commit**, not only in the working tree. Resolve the review range once and use it everywhere below:
+```bash
+PLAN_COMMIT=$(git log --format=%H --grep='^handoff: plan' -n 1)
+git diff $PLAN_COMMIT   # all handoff changes: committed waves + anything uncommitted
+```
+
+If that diff is empty → implement was not completed. Do not stop: re-enter Phase 3 from the run cursor with the remaining `ready` tasks.
 
 > Orchestrator (this session) handles the R1 guard check directly.
 
 ### R2 — Model isolation check (strong model, always first)
 
-**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.
+**Batch the review set — mandatory.** Read `handoff.maxParallelAgents` from `.ukit/storage/config.json` (default **10**). If more `pending_review` tasks exist than that, split into consecutive batches of at most that many; finish one batch's verdicts (R2–R4, appended to each task file) before starting the next.
+
+**Claude Code — MANDATORY, do this before anything else in R2–R4:** for each batch, call the Agent tool once per `pending_review` task **in parallel** (at most `handoff.maxParallelAgents`), each with `subagent_type: "code-reviewer"`. Reviewer agents only read the diff and append a verdict to their own task file — no worktree, no shared write target — so running them in parallel carries none of Phase 3's file-conflict risk. 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`:
 
@@ -272,8 +422,8 @@ If any command fails → verdict `critical_block`. Stop. Do NOT proceed to R4.
 ### R4 — Review unified diff + append verdict (strong model)
 
 ```bash
-git diff    # all uncommitted changes vs $BASE
-git status  # overview of modified/new/deleted files
+git diff $PLAN_COMMIT   # every handoff change: committed waves + working tree
+git status              # overview of modified/new/deleted files
 ```
 
 Review as one unified diff — correctness, regression risk, security, edge cases, maintainability. Cross-reference each task's intent in `docs/AI_HANDOFF/tasks/TASK-xxx.md`.
@@ -292,21 +442,70 @@ FINDINGS:
 NEXT_STATUS_FOR_INDEX: <status>
 ```
 
-### R5 — Commit + push or stop (orchestrator)
+Then return to the orchestrator **at most 6 lines** — the full verdict is already on disk:
+```
+TASK: TASK-xxx
+VERDICT: approved | approved_minor | changes_requested | critical_block
+REVIEWER_MODEL: <exact model ID>
+VERIFICATION_RERUN: PASS | FAIL
+BLOCKING: <one line per critical/important finding, or "none">
+```
+Do not paste the diff, the findings prose, or verification logs back into the orchestrator.
+
+### R4.5 — Auto-fix loop (max 2 rounds)
+
+Any task with `changes_requested` or `critical_block` enters this loop. **Do not report to
+the human and stop** — that is the single biggest reason a cycle used to stretch across days.
+
+For round in 1..2:
+
+1. Collect every task still not `approved`/`approved_minor`. If none, exit the loop.
+2. Group them into waves exactly as I2 does (dependencies + the same auto-serializing file
+   conflict rule). Spawn one `feature-implementer` per task **in parallel**, at most
+   `handoff.maxParallelAgents`, each in a fresh worktree per 3a. Each agent gets:
+   - the task file path (it reads its own `## Reviewer Verdict` from disk — do not paste
+     findings into the prompt),
+   - the instruction: fix every `critical` and `important` finding, leave `minor` alone
+     unless trivially safe, keep the existing tests green, add a regression test for each
+     critical finding, then re-run §Verification Commands and append a new
+     `## Executor Report (fix round <N>)` to the task file.
+   - the same ≤10-line return contract as 3b.
+3. Copy back and delete worktrees per 3c. Commit the round:
+   ```bash
+   git add -A && git commit -m "handoff: fix round <N> — TASK-00x"
+   ```
+4. Re-review **only the tasks touched this round**, in parallel, per R2–R4. A reviewer must
+   still differ from the executor model, and still re-runs verification itself.
+5. Update `INDEX.md` and `RUN.md`. If everything is now approved, exit the loop.
 
-**All tasks `approved` or `approved_minor`:**
+After round 2, any task still not approved is genuinely stuck: leave it `blocked`, record why
+in its `## Discussion` thread, and carry it into the Final Report. **Every other task still
+proceeds to R5** — one stubborn task must never hold the whole cycle hostage.
 
-Update `docs/AI_HANDOFF/INDEX.md`: all approved tasks → `done`.
+### R5 — Commit + push (orchestrator)
+
+R4.5 has already run, so by this point every task is either approved or genuinely stuck.
+
+Update `docs/AI_HANDOFF/INDEX.md`: approved tasks → `done`; anything still failing after both
+fix rounds → `blocked`.
+
+Commit whatever remains uncommitted (the per-wave commits from 3d are already in), then push
+once — this is the run's only push:
 
 ```bash
-git add . && git commit -m "handoff: implement <goal>" && git push origin $BASE
+git add -A && git commit -m "handoff: implement <goal>"   # skip if nothing left to commit
+git push origin $BASE
 ```
 
-Replace `<goal>` with the one-sentence goal from ACTIVE.md.
+Replace `<goal>` with the one-sentence goal from ACTIVE.md. Push without asking — `git push`
+is in the settings `allow` list precisely so a one-shot run never stalls at the last step.
+Force-push stays denied, so this can only ever fast-forward.
 
-**Any task `changes_requested` or `critical_block`:**
+**If some tasks are `blocked`:** still push. The approved work is reviewed, tested, and
+committed; withholding it helps no one, and the per-wave commits make any subset revertible.
+Name the blocked tasks in the Final Report.
 
-Report which tasks need fixes. Do NOT push. Executor re-runs Phase 3 for those tasks.
+Finally set `Phase: done` in `docs/AI_HANDOFF/RUN.md`.
 
 ---
 
@@ -337,7 +536,19 @@ Re-run assertions after removal to confirm clean state.
 handoff-fullstack complete:
   Cycle: <ID>
   Tasks: <N> approved, <M> blocked
-  Git: committed + pushed to <branch> | pending human (<M> blocked)
+  Fix rounds used: <0|1|2>
+  Git: <K> wave commits + pushed to <branch>
   Worktrees: all cleaned
   Branches: all cleaned
+  Blocked (needs you): <TASK-xxx — one-line reason> | none
 ```
+
+Then, as the last line of the run:
+
+> Cycle finished. Run `/compact` before starting the next cycle — this session is carrying
+> the whole pipeline's history and the next cycle deserves a clean window.
+
+This is the **only** place in the pipeline that may ask for a compaction. Asking at a cycle
+boundary costs nothing: all state is in git, `INDEX.md` and `RUN.md`, so a compacted or
+brand-new session picks the next cycle up with no loss. Asking mid-cycle is forbidden — see
+the Autonomy Contract.

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

@@ -8,7 +8,48 @@
 $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.
+> **Commits: yes, one per wave. Push: no.** Each wave is checkpointed to git so any step is
+> revertible, but nothing leaves the machine — `/ukit:handoff-review` decides what gets pushed.
+
+---
+
+## Autonomy Contract — read before anything else
+
+Run every `ready` task to completion in this one invocation. The human is not watching and
+will not answer mid-run.
+
+**Ask nothing after the run starts.** Every decision below has a defined automatic
+resolution — take it, and note it in the wave summary:
+
+| Situation | Required behavior |
+|-----------|------------------|
+| Working tree dirty at Step 1 | commit a checkpoint, continue |
+| Two same-wave tasks share a file | move the later task to the next wave, continue |
+| A task's agent reports FAIL | leave it `blocked`, finish every other task, report at the end |
+| Context warning fires | collapse the finished wave to one line per task, continue |
+| No `ready` tasks but `changes_requested` ones exist | treat those as the work — this is a fix pass |
+
+Escalate only for a blocker outside the repo. Never pause mid-wave to ask for `/compact`:
+context is managed structurally (short agent returns + wave-boundary collapse), and the run
+cursor makes an interrupted run resumable. A compaction request belongs at the end of the
+command, never inside it.
+
+### Run cursor — write after every step
+
+Maintain `docs/AI_HANDOFF/RUN.md`, rewritten (whole file) after every numbered step:
+
+```
+Command: handoff-implement
+Goal: <one sentence>
+Base: <BASE>
+Phase: <1|2|3|4|done>
+Cursor: wave <N> batch <M> — <what just finished>
+Next: <the exact next step to run>
+```
+
+If this file already exists with `Phase:` not `done` when the command starts, this is a
+**continuation**: read the cursor, jump to `Next:`, skip tasks already `pending_review` or
+`done`. Do not restart from Step 1 and do not ask whether to continue.
 
 ---
 
@@ -16,14 +57,19 @@ _Empty = all `ready` tasks. Or: "TASK-001" for a specific task._
 
 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.
+If there are no `ready` tasks, check for `changes_requested`/`blocked` ones and run those
+instead. Only if nothing is actionable → report and stop.
 
-Verify working tree is clean before starting:
+Verify working tree state:
 ```bash
-git status   # must be clean — no uncommitted changes
+git status
 ```
 
-If working tree is dirty → stop. Ask human to commit or stash first.
+If the working tree is dirty, do not stop — commit a checkpoint so the wave copy-back starts
+from a known state and the pre-existing edits stay recoverable:
+```bash
+git add -A && git commit -m "handoff: checkpoint before implement"
+```
 
 ## Step 2 — Build wave groups
 
@@ -33,9 +79,22 @@ Read each `tasks/TASK-xxx.md` for `Dependencies` field:
 - Chain A→B→C = 3 waves of 1 task each (sequential, no parallel)
 - Independent A, B, C = 1 wave of 3 tasks (parallel)
 
+### Conflict check — mandatory, before spawning any wave
+
+For every pair of tasks landing in the same wave, compare their `Target Files` lists. If any
+file path appears in both, **resolve it automatically — do not stop.** Keep the
+lower-numbered task in the current wave and push the other into the next wave by adding
+`Dependencies: TASK-<lower>` to its task file. Two tasks touching the same file are safe as
+long as they never run concurrently, and serializing them is the one resolution that is
+always correct.
+
+This is the code-level safety net for the planner's own §2 Scope constraint (same-wave tasks
+must not share a file) in case it slipped through review. Only mark a task `needs_breakdown`
+when it is missing required fields — never merely for sharing a file.
+
 ### Batch each wave — mandatory
 
-Read `handoff.maxParallelAgents` from `.ukit/storage/config.json` (default **3**). A wave
+Read `handoff.maxParallelAgents` from `.ukit/storage/config.json` (default **10**). A wave
 with more tasks than that is split into consecutive batches of at most that many; finish
 one batch completely (including 3c copy-back and worktree deletion) before starting the
 next.
@@ -68,7 +127,8 @@ Read docs/AI_HANDOFF/tasks/TASK-xxx.md
 TDD — mandatory:
   1. Write tests from §Test Cases
      cd .worktrees/task-xxx && <test command>
-     Confirm RED (immediately GREEN → test is wrong — flag this)
+     Confirm RED — paste the actual failing output, don't just assert it happened
+     (immediately GREEN → test is wrong — flag this)
   2. Implement → run → confirm GREEN
   3. Run §Verification Commands inside the worktree:
      cd .worktrees/task-xxx && <each verification command>
@@ -81,9 +141,24 @@ Executor Report (append to task file — do NOT touch INDEX.md):
   EXECUTOR_TOOL: <tool>
   EXECUTOR_MODEL: <exact model ID — mandatory>
   EXECUTOR_SUBAGENT: <name or "-">
+  RED_OUTPUT: <paste the actual failing-test output from step 1 — a claim like
+               "confirmed" without pasted output is not acceptable>
   Verification Output: <paste>
   Status: PASS | FAIL
   Note: <issues or "none">
+
+Then RETURN TO THE ORCHESTRATOR AT MOST 10 LINES, in exactly this shape:
+  TASK: TASK-xxx
+  STATUS: PASS | FAIL
+  EXECUTOR_MODEL: <exact model ID>
+  FILES: <comma-separated changed paths>
+  RED: confirmed | not-confirmed
+  VERIFY: <n> commands, all pass | <first failing command + one-line reason>
+  NOTE: <one line or "none">
+
+Do NOT repeat RED_OUTPUT or verification logs in the returned message. They are already on
+disk in the task file, which is where the reviewer reads them from. Pasting them back a
+second time is what blows up the orchestrator's context window and kills the run mid-wave.
 ```
 
 > Other tools without subagent support: open each task in a separate session with the code model.
@@ -132,21 +207,44 @@ git branch -D handoff/task-xxx
 **Orchestrator writes INDEX.md** — agents never touch INDEX directly.
 **Worktrees are always deleted immediately** — no exceptions.
 
-### 3d — Next wave
-Create new worktrees from `$BASE`. Repeat 3a–3c.
+### 3d — Wave boundary: commit + context checkpoint
+
+A wave boundary is the only safe place to shed context, because everything of value is
+already on disk (task files hold the full logs, git holds the code). Do all four, in order:
+
+1. **Checkpoint the code** — one commit per wave, so every wave is independently revertible:
+   ```bash
+   git add -A && git commit -m "handoff: wave <N> — TASK-00x, TASK-00y"
+   ```
+   Do not push. `/ukit:handoff-review` owns that decision.
+
+2. **Update the run cursor** — rewrite `docs/AI_HANDOFF/RUN.md` with `Cursor: wave <N> done`,
+   `Next: wave <N+1>` (or `Step 4` if that was the last wave).
+
+3. **Collapse the wave in working memory.** From here on, refer to the finished wave only by
+   its one-line-per-task summary. Do not re-read task files, restate executor reports, or
+   quote earlier diffs. The reviewer reads what it needs from disk itself.
+
+4. **Continue.** If a UKit context warning has fired, say one line —
+   `context checkpoint: wave <N> collapsed` — and start the next wave anyway. Do not ask for
+   `/compact` here. If the session ends regardless, `RUN.md` plus the `SessionStart` resume
+   hook bring the run back to exactly this point.
+
+Then create the next wave's worktrees from `$BASE` and repeat 3a–3c.
 
 ## Step 4 — Finalize: verify cleanup
 
 All waves complete. Verify:
 
 ```bash
-git worktree list        # must show only main worktree
+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
+git log --oneline -n 10    # one commit per wave
+git status                 # clean, or only trailing edits from the last wave
 ```
 
-All changes are in the **main working tree as uncommitted files**. No branches or worktrees remain.
+All changes are committed as **one commit per wave on `$BASE`**, nothing pushed. No branches
+or worktrees remain. Set `Phase: done` in `docs/AI_HANDOFF/RUN.md`.
 
 ## Step 5 — Report
 
@@ -154,8 +252,13 @@ All changes are in the **main working tree as uncommitted files**. No branches o
 Wave summary:
   Wave 1: TASK-001 [pending_review], TASK-002 [blocked]
   Wave 2: TASK-003 [pending_review]
+Commits: <K> wave commits on <BASE>, not pushed
 All worktrees and branches removed.
-Uncommitted changes in working tree — human commits when ready.
+Blocked (needs you): <TASK-xxx — one-line reason> | none
 ```
 
 **Next:** switch to strong model → `/ukit:handoff-review`
+
+If this session is now heavy, this is the right moment to `/compact` — the wave commits,
+`INDEX.md` and `RUN.md` hold all the state the review phase needs. Suggest it here, at the
+command boundary, never inside a wave.