@ngockhoale/ukit 2.0.6 → 2.1.0

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 All notable changes to UKit are documented here.
 
+## 2.1.0 - 2026-08-16
+
+Handoff autonomy wave: `/ukit:handoff-fullstack` runs a whole goal end-to-end without stopping to ask. Questions are collected once, up front, in the planning phase; everything that used to be a mid-run STOP now resolves automatically and keeps going.
+
+### Added
+
+- **Autonomy Contract in all four handoff commands.** `handoff-create` owns the single question window — one batched `AskUserQuestion` (max 4, recommended option first) before planning starts, covering scope, conflicting interpretations, subsystem choice and acceptance criteria only. `handoff-fullstack`, `handoff-implement` and `handoff-review` ask nothing between that window and the Final Report; each command carries a table mapping every former STOP to its required automatic behavior.
+- **Run cursor + resume protocol (`docs/AI_HANDOFF/RUN.md`).** Every phase transition writes `Phase`/`Cursor`/`Next`. A `Phase:` other than `done` means the next session is a continuation: no re-plan, no re-scope, no questions. New config `handoff.autonomy.resumeFromCursor` / `runCursorFile`.
+- **`handoff-resume.sh` SessionStart hook** (manifest id `hook-handoff-resume`). Reads the run cursor and prints a resume banner with Goal/Base/Phase/Cursor/Next, plus two extra lines when the session started from `source: compact`. Advisory only, always exits 0, silent when there is no unfinished run.
+- **Auto-fix loop after review (max 2 rounds).** Non-approved tasks are re-waved and re-implemented in parallel — agents read their own `## Reviewer Verdict` from disk — then committed and re-reviewed. After round 2 the stuck tasks stay `blocked` and the rest of the pipeline proceeds instead of halting. Config: `handoff.autonomy.autoFixRounds`.
+- **Planner Grounding + 12-point Self-Audit.** `handoff-planner` must verify that every Target File exists (or is marked `(new)`), that every Verification Command is a real `package.json` script, and that test file paths match the neighbouring test layout; then run a 12-point self-audit (coverage / correctness / test quality, including "could every listed test pass against an empty implementation?") and report the result. Compensates for dropping plan review from 3 rounds to 2.
+- **Wave-boundary commit + context checkpoint.** Each wave ends with `git add -A && git commit -m "handoff: wave <N> — TASK-00x, ..."`, a cursor update, and a collapse of that wave to one line per task in working memory. Config: `handoff.autonomy.commitPerWave`.
+
+### Changed
+
+- **`git push` moved from the `ask` list to `allow`** in default settings, alongside `git add`, `git commit` and `git worktree`. Runs no longer stop at the final step for a confirmation. `git push --force` and `--force-with-lease` remain in `deny`, which still wins over `allow`.
+- **Subagent return contracts are now capped.** Executors return ≤10 lines (`TASK`/`STATUS`/`EXECUTOR_MODEL`/`FILES`/`RED`/`VERIFY`/`NOTE`), reviewers ≤6. Verbose agent reports injected back into the orchestrator were the main cause of context exhaustion on long fullstack runs; this addresses it structurally rather than by raising caps.
+- **`context-window-guard.sh` is now run-cursor aware.** With an unfinished run it emits shed-context-and-continue instructions instead of the stop-and-`/compact` directive. Asking the user to `/compact` is permitted only at a cycle boundary, in the Final Report — never mid-task. Config: `handoff.autonomy.compactAtCycleBoundaryOnly`.
+- **Same-wave file conflicts auto-serialize** instead of marking both tasks `needs_breakdown`: the higher-numbered task gains a `Dependencies: TASK-<lower>` line and moves to the next wave. Config: `handoff.autonomy.autoSerializeFileConflicts`.
+- **A dirty working tree no longer blocks Phase 3.** It is committed as `handoff: checkpoint before implement` and the run continues.
+- **Plan review loop cap: 3 rounds → 2**, then findings are applied and the run proceeds (logged as `### Round <N> — findings applied without re-review`). Config: `handoff.autonomy.planReviewRounds`.
+- **Review diff range is now anchored to the plan commit** (`git log --grep='^handoff: plan' -n 1`) rather than the working tree, since waves are committed as they finish.
+- **`handoff-planner` maximizes wave width.** `Dependencies: none` unless task B genuinely cannot be written without A's output — ordering preference, same code area and review order are explicitly not dependencies.
+- **`feature-implementer` and `code-reviewer` run unattended in handoff mode.** Ambiguity resolves through task file → PLAN.md → surrounding code → recommended choice, recorded in `## Discussion`; reviewer findings must be actionable defects (`file:line` + concrete failure + what correct looks like), never questions. Daily (non-handoff) behavior is unchanged.
+- **`handoff-model-guard.sh` gained a bash fast path** that skips the node spawn when the payload contains neither `AI_HANDOFF` nor `git push`. Behavior-identical (verified against the previous version across a 6-payload sweep); measured 67ms → 38ms per ordinary Bash/Edit/Write call, paid on every call in every parallel subagent.
+
+## 2.0.7 - 2026-08-15
+
+### Added
+
+- **`/ukit:handoff-create` and `/ukit:handoff-fullstack` gain a P2.5 independent plan review gate.** After the planner writes `PLAN.md` and before it's committed, a separate `code-reviewer` agent invocation (`REVIEW_TARGET_TYPE=plan`, fresh context — not the planner reviewing its own work) checks Completeness/Consistency/Clarity/Scope/YAGNI. `Issues Found` routes back to the planner to revise and resubmit; `Approved` unlocks the commit. Each round is logged to PLAN.md's new `## Plan Review Log` section, and the loop is capped at 3 `Issues Found` rounds — past that it escalates to the human instead of looping indefinitely.
+- **Same-wave file-conflict precheck in Phase 3.** Before spawning any implementation wave, `handoff-implement.md`/`handoff-fullstack.md` now compare `Target Files` across every task in that wave; any overlap stops the wave and marks both tasks `needs_breakdown` instead of risking a mid-wave merge conflict. Code-level backstop for the planner's existing "no shared files in one wave" scope constraint.
+- **TDD RED-state now requires real evidence.** The Executor Report template adds a mandatory `RED_OUTPUT` field — the actual failing-test output pasted before implementation, not a bare "confirmed" claim. `code-reviewer` checks this field during Test Plan adherence review and requests changes if it's missing or vague.
+- **`handoff.plan.requireLintOrTypecheckInVerification`** (default `true`): when the project has a lint/typecheck script, task Verification Commands must run it, not just tests; the planner must state an explicit N/A if the project has none. Enforced by `code-reviewer` as review-order step 0.
+
+### Changed
+
+- **`handoff.maxParallelAgents`**: 3 → 10, raising the default cap on concurrent background agents per wave (config comments still warn against exceeding ~10-15 — each agent's report gets injected back into the orchestrator's own context on completion).
+- **Phase 4 (Review) is now parallelized**, batched by `maxParallelAgents` the same way Phase 3 (Implement) already was — reviewer agents only read a diff and append a verdict to their own task file, so parallel review carries none of Phase 3's shared-worktree conflict risk.
+- **`handoff.plan.minTestsEdgeCase`**: 1 → 2, and the two edge cases must now be of different kinds (e.g. null/empty **and** boundary/concurrent) — two near-duplicate cases no longer satisfy the requirement. Wired through `handoff-planner`, `code-reviewer`, `feature-implementer`'s inline-test-plan fallback, `RULES.md`, and both handoff pipeline commands.
+
 ## 2.0.6 - 2026-08-12
 
 ### Changed

package/manifests/platform.full.yaml

@@ -1121,6 +1121,17 @@ items:
     packs:
       - core
 
+  - id: hook-handoff-resume
+    type: hook
+    sourceTemplate: .claude/hooks/handoff-resume.sh
+    targetPath: .claude/hooks/handoff-resume.sh
+    requires: []
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: hook-reset-compact-pressure
     type: hook
     sourceTemplate: .claude/hooks/reset-compact-pressure.sh

package/package.json

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

package/templates/.claude/agents/code-reviewer.md

@@ -27,7 +27,8 @@ If any input is missing, return `CHANGES-REQUESTED` with reason "incomplete hand
 
 ### Review order
 
-1. **Test Plan adherence** — Were all tests in §4 actually implemented? Run them yourself: `<task Verification Commands>`. Fresh PASS required, no trusting executor's output blindly.
+0. **Verification package completeness** — Check whether the project has a lint or typecheck script (`package.json` scripts, or the stack's equivalent). If it does and the task's Verification Commands don't run it, that is `CHANGES-REQUESTED`: "verification commands missing lint/typecheck — re-run planner or add the command and re-verify" — do this before anything else below.
+1. **Test Plan adherence** — Were all tests in §4 actually implemented, including the ≥2 edge cases required by `handoff.plan.minTestsEdgeCase`? Check the Executor Report's `RED_OUTPUT` field: it must contain actual failing-test output (assertion failure, stack trace, non-zero exit), not a bare claim like "confirmed" or "yes". Missing or vague `RED_OUTPUT` → `CHANGES-REQUESTED`: "no evidence tests were RED before implementation — re-run TDD cycle and paste real output". Then run the tests yourself: `<task Verification Commands>`. Fresh PASS required, no trusting executor's output blindly.
 2. **Correctness** — Does the diff implement the requested behavior? Any obvious wrong assumptions, stale refs, missing cases?
 3. **Regression risk** — What existing behavior could this break? Are shared paths/tests/contracts still aligned? Run the wider test suite if shared code was touched.
 4. **Safety / security / data loss** — Destructive actions, auth/permission, path handling, unsafe shell/DB/file ops.
@@ -66,6 +67,27 @@ NOTES: [1-2 sentences for human reviewer if needed]
 
 After writing the verdict, update `docs/AI_HANDOFF/INDEX.md` row for this task: set Status = NEXT_STATUS_FOR_INDEX, set Reviewer = your model name.
 
+**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 output into the returned message.
+The orchestrator is driving a whole pipeline in one context window and re-reads what it needs
+from the task file; pasted reviewer logs are a common reason a run exhausts its context and
+dies before the cycle finishes.
+
+**You may be running unattended.** Findings do not end the run — the caller feeds them to an
+auto-fix round and re-review. So write findings that a fresh executor can act on with no human
+present: point at `file:line`, state the concrete failure, and say what correct looks like. A
+finding phrased as a question ("should this handle null?") is not actionable; phrase it as the
+defect ("`parse()` at foo.js:41 throws on null input; expected an empty result").
+
 ### Model isolation check (FIRST thing you do)
 
 UKit cannot force any tool to use a specific model. The contract is enforced HERE, by you, via self-report comparison.
@@ -112,7 +134,10 @@ Only flag issues that would cause real problems during implementation planning.
 
 ### Output
 
+Append (do NOT overwrite) this block to the end of the reviewed document under a `## Plan Review Log` section — create the section if it doesn't exist yet, keep all prior round entries:
+
 ```
+### Round <N> — <YYYY-MM-DD> · <your model>
 Status: Approved | Issues Found
 
 COMPLETENESS:
@@ -128,3 +153,5 @@ YAGNI:
 
 NOTES: [1-2 sentences if needed]
 ```
+
+`<N>` = 1 + however many `### Round` entries already exist in the log (1 if this is the first review).

package/templates/.claude/agents/feature-implementer.md

@@ -12,7 +12,15 @@ Implement requested behavior with minimal scope drift.
 - **Daily/ad-hoc mode** (DEFAULT): task didn't come from `docs/AI_HANDOFF/` → use the original lightweight workflow. Tests only when touched code already has coverage. No reviewer trigger.
 - **Handoff mode**: task file is `docs/AI_HANDOFF/tasks/TASK-xxx.md` OR user explicitly invokes handoff (e.g. "execute task TASK-001") → activate full Quality Gate: test-first → green → reviewer.
 
-If unsure, ask the user. Don't apply Handoff mode rules to a quick one-off fix.
+If unsure which mode applies, ask the user. Don't apply Handoff mode rules to a quick one-off fix.
+
+**In Handoff mode you are running unattended — ask nothing.** You were spawned by an
+orchestrator driving a pipeline; there is no human in your conversation to answer, and a
+question there is silently dropped while the run stalls. Resolve ambiguity in this order:
+the task file → `PLAN.md` → the surrounding code's existing patterns → the choice you would
+recommend. Record what you chose and why in the task's `## Discussion` thread. Only a blocker
+outside the repo (missing credential, unreachable service) justifies reporting `FAIL` early —
+and even then, report it, don't ask about it.
 
 ## Workflow
 
@@ -25,12 +33,12 @@ If unsure, ask the user. Don't apply Handoff mode rules to a quick one-off fix.
   - non-trivial: `docs/MEMORY.md` + `docs/PROJECT.md` + `docs/CODE_MAP.md`
 - Identify target files and existing patterns.
 - If task came from handoff, read `tasks/TASK-xxx.md` and locate its **Test Plan** + **Verification Commands**.
-- If confidence is low or risk is high, ask one short clarifying question before deeper analysis.
+- Daily mode: if confidence is low or risk is high, ask one short clarifying question before deeper analysis. Handoff mode: do not ask — decide and record the decision (see above).
 
 ### 2. Plan Approach (< 1 minute)
 
 - List files to create/modify (max diff).
-- **Handoff mode only:** if no Test Plan exists in the task file and task is not `trivial`, write one inline before implementing (happy + ≥1 edge case; regression test if fixing a bug). In daily mode, skip this step.
+- **Handoff mode only:** if no Test Plan exists in the task file and task is not `trivial`, write one inline before implementing (happy + ≥2 edge cases of different kinds; regression test if fixing a bug). In daily mode, skip this step.
 
 ### 3. Test First (RED) — Handoff mode
 
@@ -79,6 +87,26 @@ NEXT: [follow-up needed, or "ready for review"]
 
 > **Self-report rule:** UKit cannot force any tool/host to use a specific model. Your self-reported `EXECUTOR_MODEL` is how the reviewer (in another tool or subagent) knows what to compare against its own model. Misreporting → reviewer refuses and asks the human to confirm.
 
+**Handoff mode — where that report goes.** Append the block above, in full, to the task file
+as `## Executor Report` (or `## Executor Report (fix round <N>)` on a re-run). Then return to
+the orchestrator **at most 10 lines**:
+
+```
+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, verification logs, diffs, or file contents in the returned message.
+The reviewer reads all of that from the task file on disk. The orchestrator is driving a whole
+pipeline in one context window, and pasted subagent logs are the single biggest reason a run
+runs out of context and dies half-finished. Being terse here is not a style preference — it is
+what lets the cycle reach the end.
+
 ### 7. Trigger Reviewer — Handoff mode ONLY
 
 - Daily mode: skip this step entirely. Just report and stop.

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

@@ -17,15 +17,43 @@ Use the strongest model available — planning with a weak model produces weak t
 
 ## Scope Check (before Phase 1)
 
-Before refining the request into `PLAN.md`, check whether it describes multiple independent subsystems (e.g. "CRM + AI + billing + analytics + mobile app"). If yes, stop and output a decomposition table instead of planning the mega-spec:
+Before refining the request into `PLAN.md`, check whether it describes multiple independent subsystems (e.g. "CRM + AI + billing + analytics + mobile app"). If yes, record the decomposition:
 
 ```
 Scope complexity: HIGH
 Detected systems: [...]
-Recommended decomposition: N modules — plan each as a separate PLAN.md
+Decomposition: N modules — module 1 planned now, modules 2..N queued
 ```
 
-Wait for human confirmation before writing `PLAN.md`.
+Then **plan module 1 in full and keep going** — do not wait for confirmation. A mega-spec is
+what you must avoid, not the work itself. Write the remaining modules into `PLAN.md` §2 as
+explicitly out-of-scope-for-this-cycle, and add one `queued` row per module to `INDEX.md` so
+the next cycle picks them up. Order modules so the one others depend on is planned first.
+
+The caller may be running unattended (`/ukit:handoff-fullstack`). Stopping to ask means the
+run dies and the human returns hours later to a question, which is the failure mode this
+whole pipeline exists to prevent.
+
+## Grounding — every path and command must be real
+
+The most common way a plan fails is not bad reasoning, it is **confident invention**: a target
+file that doesn't exist, a test command the project doesn't have, an import path that never
+resolved. Executors then burn a whole round discovering it.
+
+Before writing any path or command into `PLAN.md` or a task file, verify it:
+
+- **Target Files** — for each path, confirm it exists (`ls`/Glob), or that its parent
+  directory exists and the file is genuinely new. Mark new files `(new)` explicitly.
+- **Verification Commands** — read `package.json` `scripts` (or the stack's equivalent) and
+  use the script names that are actually defined. Do not write `npm test` when the repo uses
+  `yarn test`, and do not invent a `lint` script that isn't there. Run `--help` or a dry check
+  if unsure.
+- **Test Files** — follow the existing test layout and naming; open one neighbouring test file
+  and match its structure, framework and import style.
+- **Interfaces** — quote real signatures from the source, not plausible-looking ones.
+
+If something cannot be verified, say so in the task's `## Discussion` rather than guessing.
+A stated unknown costs the executor one read; a wrong path costs it a round.
 
 ## Phase 1 — Write PLAN.md
 
@@ -37,9 +65,15 @@ Write all 7 sections to `docs/AI_HANDOFF/PLAN.md`:
                   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)
+§4 Test Plan    — happy path × N + ≥2 edge cases of DIFFERENT kinds (e.g. null/empty AND
+                  boundary/concurrent — two near-duplicate cases do not satisfy this) +
+                  regression (if bugfix)
                   table: | Type | Test Name | Expected |
-§5 Verification — exact shell commands executor will run
+§5 Verification — exact shell commands executor will run. If the project has a lint or
+                  typecheck script (check package.json `scripts`, or the equivalent for
+                  the project's stack), it MUST be included here, not just the test
+                  command. If the project genuinely has none, state that explicitly —
+                  do not omit silently.
 §6 Acceptance   — checklist of done criteria (prefer verifiable/command-based criteria)
 §7 Global Constraints — one line each: version floors, dependency limits, naming/copy
                   rules, platform requirements. Every TASK-xxx.md inherits this section
@@ -55,6 +89,8 @@ Append this footer to `PLAN.md` — mandatory, checked by a hook before the writ
 PLANNER_MODEL: <your exact model ID — e.g. claude-opus-5>
 ```
 
+Your output does not go straight to implementation: an independent `code-reviewer` pass (`REVIEW_TARGET_TYPE=plan`) reviews `PLAN.md` next. If it returns `Issues Found`, you'll be re-invoked to revise and resubmit — write §1-§7 tight enough to pass on the first pass.
+
 ## Phase 2 — Split into TASK-xxx.md
 
 **Right-sizing rule:** A task is the smallest unit that carries its own test cycle and is worth a fresh reviewer's gate. Split only where a reviewer could meaningfully approve one task while rejecting its neighbor. Each task ends with an independently testable deliverable.
@@ -67,9 +103,9 @@ Use `_TEMPLATE.md` structure (from pre-read context or file).
 |-------|------|
 | 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 Cases | Type \| Test Name \| Expected — ≥1 happy + ≥2 edge cases of different kinds |
 | Test Files | Exact test file paths to create/modify |
-| Verification Commands | Runnable shell commands |
+| Verification Commands | Runnable shell commands — MUST include the project's lint/typecheck command if one exists (see §5 rule above) |
 | Acceptance Criteria | Verifiable checklist |
 
 Missing any field → `needs_breakdown`. Never mark incomplete tasks `ready`.
@@ -80,6 +116,30 @@ Missing any field → `needs_breakdown`. Never mark incomplete tasks `ready`.
 - 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
 
+### Maximize wave width — dependencies are expensive
+
+Wave width is the single biggest lever on how long a cycle takes: a wave of 6 finishes in
+roughly the time of its slowest task, while a chain of 6 takes six times that. Executors run
+up to `handoff.maxParallelAgents` (default 10) at once, so a plan that produces `none`
+dependencies for most tasks is dramatically faster than one that produces a chain.
+
+**Write `Dependencies: none` unless B genuinely cannot be written without A's output.** A real
+dependency means B imports a symbol A creates, or B tests behavior A implements. These are
+*not* dependencies:
+
+- "B is logically later" or "B builds on the same feature" — ordering preference, not a
+  dependency.
+- "Both touch the same area of the codebase" — irrelevant unless they touch the same *file*.
+- "A should be reviewed before B starts" — that is what the review phase is for.
+
+Same-file collisions are the one real constraint, and they are cheap to design around: split
+along file boundaries so each task owns its files outright. If two pieces of work truly must
+edit one file, prefer merging them into a single task over chaining two — one task with two
+test groups beats two waves.
+
+Before finalizing, count your waves. If the dependency graph is mostly a chain, re-examine it:
+most chains are ordering preferences that a wide wave 1 would satisfy just as well.
+
 ## Phase 3 — Update state files
 
 **INDEX.md** row per task: `| TASK-001 | <name> | ready | none | - |`
@@ -93,15 +153,59 @@ Status: planning_done — ready for executor
 ```
 Wave structure is NOT stored here — inferred from task `Dependencies` fields at runtime.
 
+## Self-Audit — run before reporting, every time
+
+The downstream pipeline is unattended: an incomplete or wrong plan is not caught by a human
+skimming it, it is caught by an executor failing three hours later. Independent plan review
+runs at most twice, so this audit is your own last line of defense.
+
+Walk the checklist and **fix what fails before you report** — do not report and hope review
+catches it:
+
+**Coverage — is anything missing?**
+1. Does every acceptance criterion in §6 trace to at least one task? Name the task per criterion.
+2. Does every task trace back to something in §1/§6? A task nothing asks for is scope creep — cut it.
+3. Do the tasks together actually deliver §1's success definition, or only the easy part of it? State the gap if there is one.
+4. Is the *unhappy* path planned — errors, empty input, permissions, migration of existing data — or only the feature?
+
+**Correctness — is anything wrong?**
+5. Every `Target Files` path verified per Grounding? Any `(new)` file marked as such?
+6. Every `Verification Command` a real, defined script in this repo?
+7. Any two same-wave tasks sharing a file? If yes, merge them or add the dependency now — the executor will otherwise serialize them for you and your wave plan was a lie.
+8. Does any task depend on a symbol or file that no earlier task creates? That's a missing task, not a dependency.
+
+**Test quality — the part most often faked:**
+9. Each task: ≥1 happy path + ≥2 edge cases of genuinely *different kinds*. "empty string" and "null" are the same kind — boundary, concurrency, malformed input, permission denied, duplicate, ordering are different kinds.
+10. Does each test case state a concrete `Expected` value, not "works correctly" or "returns successfully"? A test whose expectation cannot fail is not a test.
+11. Bugfix task → is there a regression test that fails against today's code?
+12. Could every listed test pass against an empty implementation? If so, the test cases describe nothing and must be rewritten.
+
+Append the result to `PLAN.md`:
+```
+## Planner Self-Audit
+Checklist: 12/12 pass
+Fixed during audit: <what you changed, or "nothing">
+Known gaps: <what you deliberately left out and why, or "none">
+```
+
+An honest `Known gaps` line is worth more than a clean sheet — it is the one thing the reviewer
+and executor cannot recover on their own.
+
 ## Output
 
+Keep the returned message under 25 lines — the caller may be an orchestrator whose context
+budget is the constraint on the whole run. Detail belongs in `PLAN.md`, not in the reply.
+
 - Task count + IDs
 - Dependency graph (text form: TASK-001 → TASK-003, TASK-002 independent)
+- Wave plan: `wave 1: N tasks | wave 2: M tasks` — flag it if the graph is mostly a chain
+- Self-audit result + any `Known gaps`
 - Any `needs_breakdown` tasks + reason
 - Next step: "Switch to Sonnet/unic-code → run `/ukit:handoff-implement`"
 
 ## Rules
 
 - Do NOT implement. Job ends when all tasks are `ready` or `needs_breakdown`.
-- Undone tasks in INDEX.md → warn human: continue old cycle or start fresh?
-- Cannot determine test cases → `needs_breakdown` + Discussion thread note.
+- Undone tasks in INDEX.md → continue that cycle; plan only what is still missing. Do not ask whether to start fresh, and do not overwrite task files that already carry an executor report or reviewer verdict.
+- Cannot determine test cases → `needs_breakdown` + Discussion thread note. Never mark a task `ready` with vague tests just to keep the pipeline moving — a task with fake tests passes review and ships a bug, which costs far more than one blocked task.
+- You may be invoked unattended. Ask nothing; where the caller allowed questions, that window closed before you were spawned. Resolve ambiguity by reading the codebase, choose the option you would recommend, and record the choice and its rationale in `PLAN.md §3`.

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

@@ -14,6 +14,29 @@ $ARGUMENTS
 
 ---
 
+## Question Policy — this is the one phase that may ask
+
+Planning is the **only** place in the handoff pipeline where asking the human is allowed, and
+it is where every ambiguity must be burned off. Whatever is left unresolved here becomes a
+guess during implementation, where nobody is available to correct it.
+
+**Ask once, up front, batched.** Before Step 1, if `$ARGUMENTS` leaves a choice that changes
+*what gets built* — not how — collect every such question into a **single** `AskUserQuestion`
+call (max 4 questions, each with a `(Recommended)` first option). Then close the window.
+
+Ask about: ambiguous scope boundaries, conflicting interpretations of the request, which
+existing subsystem to extend versus replace, and any acceptance criterion you would otherwise
+invent. Do **not** ask about: file layout, naming, test framework choice, library versions
+already used in the repo, or anything the codebase or `docs/` already answers — resolve those
+by reading, and record the resolution in `PLAN.md §3`.
+
+Record every answer verbatim in `PLAN.md §1 Intent`. Downstream phases treat that section as
+the human's own words and never re-ask.
+
+After the batched call, run Steps 1–2.5 to completion without further questions.
+
+---
+
 ## Step 1 — Read context (lite model)
 
 **Claude Code — MANDATORY, do this before anything else:** call the Agent tool with `subagent_type: "ukit-small-task-maintainer"`. Do NOT read these files yourself in the current session — this step is contracted to the lite tier (haiku/unic-lite), which only the spawned agent's frontmatter model guarantees. Ask the agent to:
@@ -36,7 +59,7 @@ The planner agent does the following (use Step 1 summary — do NOT re-read file
 
 1. Check INDEX.md task statuses:
    - All tasks are `ready` (planning only) → **re-run allowed**: overwrite PLAN.md and TASK-xxx.md freely — this is iterative refinement.
-   - Any task is `pending_review`, `changes_requested`, `merge_conflict`, or `blocked` → **STOP**: warn human — tasks are already in implement/review phase, cannot overwrite safely.
+   - Any task is `pending_review`, `changes_requested`, `merge_conflict`, or `blocked` → **do not overwrite**: that cycle is mid-flight and its task files carry executor reports and verdicts. Report which tasks are in flight and point the human at `/ukit:handoff-review` (to finish the cycle) or `/ukit:handoff-clear` (to abandon it). Planning is the one phase where stopping is correct — there is nothing safe to do automatically here.
    - No tasks → fresh cycle, proceed normally.
 
 2. Resolve base branch:
@@ -48,7 +71,7 @@ The planner agent does the following (use Step 1 summary — do NOT re-read file
    - §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)
+   - §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)
 
@@ -62,7 +85,7 @@ The planner agent does the following (use Step 1 summary — do NOT re-read file
    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 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)
@@ -85,4 +108,25 @@ The planner agent does the following (use Step 1 summary — do NOT re-read file
 
 ---
 
+## Step 2.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, and do not stop. 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` listing what changed, then finish.
+
+Two independent strong-model passes shape the plan before any code is written — that gate is
+intact. What it no longer does is hand a stalled plan back and wait.
+
+**Claude Code — MANDATORY, do this before anything else:** 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 Step 2'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 Step 2: planner revises `PLAN.md` and the affected `TASK-xxx.md` files to address every finding, then re-submit for another Step 2.5 review (this becomes the next round). Do NOT commit or hand off to executor on `Issues Found`.
+3. `Approved` → append `PLAN_REVIEW: Approved by <reviewer model>` to PLAN.md's `## Planner Report` footer, then proceed.
+
+> Other tools without subagent support: manually switch to the strong model in a **separate** chat/session from Step 2, paste PLAN.md, review using the Spec/Plan Review checklist in `.claude/agents/code-reviewer.md`.
+
+---
+
 **Next:** switch to code model → `/ukit:handoff-implement`