@ngockhoale/ukit 2.0.6 → 2.1.0

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

@@ -8,7 +8,26 @@
 $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.
+> **The reviewer agents never commit.** The orchestrator does: it checkpoints each fix round
+> and, once the set is approved, pushes. Force-push stays denied.
+
+---
+
+## Autonomy Contract — read before anything else
+
+Review every `pending_review` task and drive the set to a decision in this one invocation.
+The human is not watching.
+
+**Ask nothing after the run starts.** Findings do not end the run — they start the auto-fix
+loop (Step 3). Escalate only for a blocker outside the repo, or a task still failing after
+both fix rounds, and even then finish everything else first.
+
+Never pause mid-review to ask for `/compact`. Reviewer agents return ≤6 lines and write the
+full verdict to disk; a compaction request belongs at the end of the command, never inside it.
+
+Maintain `docs/AI_HANDOFF/RUN.md` (`Command: handoff-review`, `Phase:`, `Cursor:`, `Next:`)
+after every step. If it already exists with `Phase:` not `done`, this is a **continuation**:
+jump to `Next:` instead of restarting, and do not ask whether to continue.
 
 ---
 
@@ -18,17 +37,22 @@ 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 there are uncommitted changes from handoff-implement:
+`/ukit:handoff-implement` commits one commit per wave, so the changes under review are in
+commits since the plan commit, not only in the working tree. Resolve the review range once:
 ```bash
-git status           # should show modified/new files, no handoff branches/worktrees
-git diff --stat      # summary of all changes
+PLAN_COMMIT=$(git log --format=%H --grep='^handoff: plan' -n 1)
+git diff --stat $PLAN_COMMIT   # every handoff change: wave commits + working tree
+git status                     # no handoff branches/worktrees should remain
 ```
 
-If `git diff` is empty and `git status` is clean → handoff-implement was not completed. Stop and re-run it.
+If that diff is empty → handoff-implement was not completed. Report which tasks are still
+`ready` and stop; there is nothing to review yet.
 
 ## Step 2 — Review the diff
 
-**Claude Code — MANDATORY, do this before anything else:** 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. Pass each agent: the task file path, the executor's report, and the diff.
+**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 (2a–2d, appended to each task file) before starting the next.
+
+**Claude Code — MANDATORY, do this before anything else:** 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. Pass each agent: the task file path, the executor's report, and the diff.
 
 The spawned reviewer agent performs 2a–2d below per task:
 
@@ -49,13 +73,14 @@ Read `EXECUTOR_MODEL` from each task file `## Executor Report`.
 <each command from §Verification Commands across all tasks>
 ```
 
-If any command fails → verdict: `critical_block`. Stop.
+If any command fails → verdict: `critical_block` for this task. That ends **this task's**
+review, not the run — the orchestrator picks it up in Step 3's auto-fix loop.
 
 ### 2c — Review unified diff
 
 ```bash
-git diff             # all uncommitted changes vs $BASE
-git status           # overview of modified/new/deleted files
+git diff $PLAN_COMMIT   # every handoff change: wave commits + working tree
+git status              # overview of modified/new/deleted files
 ```
 
 Review as one unified diff — correctness, regression risk, security, edge cases, maintainability.
@@ -76,43 +101,89 @@ FINDINGS:
 NEXT_STATUS_FOR_INDEX: <status>
 ```
 
+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.
+
 ### 2e — Orchestrator updates INDEX.md
 
 Set `status = NEXT_STATUS_FOR_INDEX`. Orchestrator writes INDEX, not the reviewer.
 
-## Step 3 — After all tasks reviewed
-
-**All `approved` or `approved_minor`:**
-
-Update INDEX.md: all approved tasks → `done`.
-
-**DO NOT commit. DO NOT push.** Leave the working tree as-is for human review.
-
-Report:
-```
-✅ 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
+## Step 3 — 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** — an unattended review that ends in a to-do list is what stretches a
+cycle across days.
+
+For round in 1..2:
+
+1. Collect every task not yet `approved`/`approved_minor`. If none, exit the loop.
+2. Group them into waves by `Dependencies`, auto-serializing any pair that shares a target
+   file. Spawn one `feature-implementer` per task **in parallel**, at most
+   `handoff.maxParallelAgents`, each in its own worktree. Each agent gets:
+   - the task file path — it reads its own `## Reviewer Verdict` from disk, so do not paste
+     findings into the prompt;
+   - the instruction: fix every `critical` and `important` finding, leave `minor` alone
+     unless trivially safe, keep existing tests green, add a regression test per critical
+     finding, re-run §Verification Commands, and append `## Executor Report (fix round <N>)`
+     to the task file;
+   - a ≤10-line return contract (`TASK` / `STATUS` / `EXECUTOR_MODEL` / `FILES` / `VERIFY` /
+     `NOTE`) — no pasted logs.
+3. Copy changes back, delete worktrees, then checkpoint:
+   ```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 2a–2e. The reviewer must
+   still differ from the executor model and still re-runs verification itself.
+5. Update `INDEX.md` and `RUN.md`. Exit when everything is approved.
+
+After round 2, a task still failing is genuinely stuck: leave it `blocked`, record why in its
+`## Discussion` thread, and name it in the report. **Every other task still proceeds to Step
+4** — one stubborn task must not hold the rest hostage.
+
+## Step 4 — Commit + push
+
+Update `INDEX.md`: approved tasks → `done`; still-failing tasks → `blocked`.
+
+Commit anything left uncommitted, then push once:
+```bash
+git add -A && git commit -m "handoff: review <goal>"   # skip if nothing left to commit
+git push origin $BASE
 ```
 
-**Any `changes_requested` or `critical_block`:**
+Push without asking — `git push` is in the settings `allow` list precisely so an unattended
+run never stalls at the last step. Force-push stays denied, so this can only fast-forward.
+
+If some tasks are `blocked`, still push: the approved work is reviewed, tested and
+committed, and the per-wave commits make any subset revertible.
 
-Report which files need fixes. Executor re-runs `/ukit:handoff-implement TASK-xxx`.
-Changes from the failed task remain in the working tree — executor fixes them in place (no new worktree needed for simple fixes).
+Set `Phase: done` in `docs/AI_HANDOFF/RUN.md`.
 
-## Step 4 — Report
+## Step 5 — Report
 
 ```
 Review summary:
   TASK-001: approved
-  TASK-002: changes_requested — see §Discussion
-  Working tree: unchanged — human commits when satisfied
+  TASK-002: approved (fix round 1)
+  TASK-003: blocked — <one-line reason>
+Fix rounds used: <0|1|2>
+Git: <K> commits pushed to <BASE>
+Blocked (needs you): <TASK-xxx> | none
 ```
 
-**Next:**
-- All approved → human reviews `git diff` and commits manually.
-- Has fixes → executor re-runs `/ukit:handoff-implement TASK-xxx`
+Then, as the last line:
+
+> Cycle finished. Run `/compact` before starting the next cycle — this session carries the
+> whole review history and the next cycle deserves a clean window.
+
+This is the only place this command may ask for a compaction. All state lives in git,
+`INDEX.md` and `RUN.md`, so a compacted or fresh session resumes with nothing lost.
 
 > Orchestrator (this session) handles Step 1, 2e, and 3 directly — those are not delegated.
-> Other tools without subagent support: manually switch to the strong model, run 2a–2d sequentially per task.
+> Other tools without subagent support: manually switch to the strong model, run 2a–2d per task (one session at a time).

package/templates/.claude/hooks/context-window-guard.sh

@@ -164,6 +164,28 @@ const now = Date.now();
 const withinCooldown = guardState.lastPhase === phase
   && (now - Number(guardState.lastActionAt || 0)) < COOLDOWN_MS;
 
+// A one-shot pipeline (handoff-fullstack) is mid-flight when RUN.md exists with a phase
+// other than `done`. Telling the agent to stop and ask for /compact there is actively
+// harmful: the human is deliberately away, the pipeline has a disk cursor that makes it
+// resumable, and a mid-cycle halt is what used to strand a cycle for days. The right
+// directive during a run is "shed context at the next wave boundary and keep going" —
+// compaction is requested once, at the cycle boundary, by the command's Final Report.
+function readRunCursor() {
+  try {
+    const text = fs.readFileSync(path.join(projectRoot, 'docs', 'AI_HANDOFF', 'RUN.md'), 'utf8');
+    const runPhase = (text.match(/^Phase:\s*(.+)$/m)?.[1] || '').trim();
+    if (!runPhase || /^done$/i.test(runPhase)) return null;
+    return {
+      phase: runPhase,
+      cursor: (text.match(/^Cursor:\s*(.+)$/m)?.[1] || '').trim(),
+    };
+  } catch {
+    return null;
+  }
+}
+
+const run = readRunCursor();
+
 const lines_out = [];
 if (ratio >= 1) {
   lines_out.push(`UKIT CONTEXT ALERT — live context ~${estimatedTokens.toLocaleString()} tokens, at/over the ${hardCap.toLocaleString()} cap (${pct}%).`);
@@ -174,10 +196,21 @@ if (ratio >= 1) {
 
 if (withinCooldown) {
   lines_out.push('(Directive already issued this phase — act on it now if not already done; this is just a reminder.)');
+} else if (run) {
+  lines_out.push(`A handoff run is mid-flight (RUN.md — Phase: ${run.phase}${run.cursor ? `, Cursor: ${run.cursor}` : ''}). DO NOT stop, DO NOT ask the user to /compact, DO NOT re-scope the remaining work into a new cycle.`);
+  lines_out.push('ACTION THIS TURN — shed context, then keep going:');
+  lines_out.push('1) Finish the step in flight, then update docs/AI_HANDOFF/RUN.md so the cursor is current.');
+  lines_out.push('2) At the next wave boundary, collapse the finished wave to one line per task and stop re-reading task files, executor reports, and earlier diffs — that detail is already on disk.');
+  lines_out.push('3) Make sure spawned agents are returning their short summary form (<=10 lines), not pasted RED/verification logs. Pasted subagent logs are the usual cause of this warning.');
+  lines_out.push('4) Continue to the next wave/phase. The user is asked to /compact once, at the end of the cycle — not now.');
+  if (sidechainEntries > 0) {
+    lines_out.push(`Note: ${sidechainEntries} subagent entries in this stretch. Keep concurrency at or below handoff.maxParallelAgents and keep returns short; do not widen the batch while this warning stands.`);
+  }
+  writeGuardState({ lastPhase: phase, lastActionAt: now });
 } else {
   lines_out.push('ACTION THIS TURN, before starting new investigation/subagents/pipeline phases:');
   lines_out.push('1) Persist current progress now (update docs/STATUS.md, e.g. via the update-status skill) so nothing is lost.');
-  lines_out.push('2) If the remaining work still has multiple steps or pipeline phases left (e.g. a handoff-fullstack run with implement/review/deploy still ahead), split what remains into bounded docs/AI_HANDOFF tasks instead of continuing in this one thread — smaller phases keep each turn under the cap.');
+  lines_out.push('2) If the remaining work still has multiple steps or pipeline phases left, split what remains into bounded docs/AI_HANDOFF tasks instead of continuing in this one thread — smaller phases keep each turn under the cap.');
   lines_out.push('3) Otherwise, tell the user plainly: run /compact now, or wrap up and start a fresh session — work already committed/persisted to disk is not lost.');
   if (sidechainEntries > 0) {
     lines_out.push(`Note: ${sidechainEntries} subagent entries in this stretch — each teammate carries its own context window, and every finished report is injected back here, so running many at once is the fastest way to overflow this session. Avoid spawning more until context drops back under the cap.`);

package/templates/.claude/hooks/handoff-model-guard.sh

@@ -14,6 +14,18 @@
 INPUT=$(cat)
 PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
 
+# Fast path — skip the node spawn (~70ms) when this hook provably has nothing to say.
+# The two branches below only ever act on (a) Edit/Write under docs/AI_HANDOFF/, or
+# (b) a Bash `git push`. If neither marker appears anywhere in the raw payload, the node
+# program is guaranteed to exit 0, so running it is pure latency — paid on EVERY Bash,
+# Edit and Write in every session and every parallel subagent, which is where a
+# many-agent pipeline quietly loses minutes.
+# Conservative by construction: a payload that merely mentions these strings still falls
+# through to the real check below. This can only skip work, never skip a block.
+if ! printf '%s' "$INPUT" | grep -qE 'AI_HANDOFF|git[[:space:]]+push'; then
+  exit 0
+fi
+
 INPUT="$INPUT" PROJECT_ROOT="$PROJECT_ROOT" node <<'NODE'
 const fs = require('fs');
 const path = require('path');

package/templates/.claude/hooks/handoff-resume.sh

@@ -0,0 +1,90 @@
+#!/bin/bash
+# SessionStart hook: resume an interrupted handoff-fullstack run.
+#
+# Why this exists:
+#   A one-shot pipeline is only one-shot if an interruption is recoverable without the human
+#   retyping anything. Compaction, a crash, or closing the terminal all end the session while
+#   the cycle is still mid-flight. docs/AI_HANDOFF/RUN.md is the cursor the command writes
+#   after every step; this hook reads it back at session start and injects the continuation
+#   instruction, so the very next turn picks up where the run stopped.
+#
+#   Pairs with context-window-guard.sh, which stops telling the agent to halt for /compact
+#   while a run is active. Between them: never stop mid-cycle, and if the session ends anyway,
+#   resume automatically.
+#
+# Fires on every SessionStart source (startup / resume / clear / compact). `compact` is the
+# important one — that is the path the command's own Final Report tells the user to take
+# between cycles, and the path an over-full session takes mid-cycle.
+#
+# ADVISORY ONLY — always exit 0. A resume hint must never be able to block a session from
+# starting.
+
+INPUT=$(cat)
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+
+INPUT="$INPUT" PROJECT_ROOT="$PROJECT_ROOT" node <<'NODE' || true
+const fs = require('fs');
+const path = require('path');
+
+const payload = (() => {
+  try {
+    const parsed = JSON.parse(process.env.INPUT || '');
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+})();
+
+const projectRoot = process.env.PROJECT_ROOT;
+const runPath = path.join(projectRoot, 'docs', 'AI_HANDOFF', 'RUN.md');
+
+let text;
+try {
+  text = fs.readFileSync(runPath, 'utf8');
+} catch {
+  // No cursor file: nothing was running, or the last cycle was cleared. Stay silent —
+  // a resume banner on every ordinary session start would be pure noise.
+  process.exit(0);
+}
+
+const field = (name) => (text.match(new RegExp(`^${name}:\\s*(.+)$`, 'm'))?.[1] || '').trim();
+
+const phase = field('Phase');
+// `done` means the last cycle finished cleanly. Anything else means a step was in flight.
+if (!phase || /^done$/i.test(phase)) process.exit(0);
+
+const goal = field('Goal');
+const base = field('Base');
+const cursor = field('Cursor');
+const next = field('Next');
+const source = typeof payload.source === 'string' ? payload.source : 'startup';
+
+const out = [
+  'UKIT HANDOFF RESUME — an unfinished handoff-fullstack run was found on disk.',
+  `  Goal:   ${goal || '(not recorded)'}`,
+  `  Base:   ${base || '(not recorded)'}`,
+  `  Phase:  ${phase}`,
+  `  Cursor: ${cursor || '(not recorded)'}`,
+  `  Next:   ${next || '(not recorded)'}`,
+  '',
+  'This is a CONTINUATION, not a new cycle. Do not re-plan, do not overwrite PLAN.md or the',
+  'task files, and do not ask the user whether to continue — they already asked for a',
+  'one-shot run and the pipeline was interrupted, not cancelled.',
+  '',
+  'Read docs/AI_HANDOFF/RUN.md and docs/AI_HANDOFF/INDEX.md, then execute the `Next:` step',
+  'above using .claude/commands/ukit/handoff-fullstack.md as the procedure. Skip tasks',
+  'already `done` or `pending_review`; pick up `ready`, `in_progress`, `changes_requested`',
+  'and `blocked` ones. Keep writing the cursor after every step.',
+];
+
+if (source === 'compact') {
+  out.push('');
+  out.push('The session was just compacted, so the window is clean — this is the ideal moment');
+  out.push('to continue. Resume immediately rather than reporting status and waiting.');
+}
+
+process.stdout.write(`${out.join('\n')}\n`);
+process.exit(0);
+NODE
+
+exit 0

package/templates/.claude/settings.json

@@ -26,10 +26,13 @@
       "Bash(git status:*)",
       "Bash(git diff:*)",
       "Bash(git log:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git push:*)",
+      "Bash(git worktree:*)",
       "Bash(jq:*)"
     ],
     "ask": [
-      "Bash(git push:*)",
       "Bash(gh pr create:*)",
       "Bash(gh pr comment:*)",
       "Bash(gh issue comment:*)"
@@ -197,6 +200,11 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/reset-compact-pressure.sh\"",
             "timeout": 8
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/handoff-resume.sh\"",
+            "timeout": 8
           }
         ]
       }

package/templates/docs/AI_HANDOFF/RULES.md

@@ -38,6 +38,53 @@ Khi cần hỏi-lại / push-back / gợi ý cho phase khác, AI ghi vào `## Di
 
 Phase kế tiếp PHẢI đọc Discussion trước khi tiếp tục — coi như inbox.
 
+## Autonomy Model — hỏi một lần, chạy tới hết
+
+Handoff được thiết kế để chạy **không cần người ngồi canh**. Config: `.ukit/storage/config.json` → `handoff.autonomy`.
+
+**Cửa sổ hỏi duy nhất là lúc plan.** `/ukit:handoff-create` (và bước P0 của `/ukit:handoff-fullstack`) gom mọi câu hỏi vào **một** lần `AskUserQuestion` rồi đóng cửa sổ. Câu trả lời ghi nguyên văn vào `PLAN.md §1` — các phase sau coi đó là lời của người dùng và không hỏi lại.
+
+Từ sau đó, mọi ngã ba đều có cách giải quyết tự động:
+
+| Tình huống | Xử lý tự động |
+|-----------|---------------|
+| Scope nhiều subsystem | tách module, plan module 1, queue phần còn lại vào `INDEX.md` |
+| Plan review còn `Issues Found` sau 2 vòng | planner áp findings rồi đi tiếp, ghi vào Plan Review Log |
+| 2 task cùng wave đụng 1 file | đẩy task sau xuống wave kế (thêm dependency) |
+| Working tree bẩn | commit checkpoint rồi chạy tiếp |
+| Reviewer trả `changes_requested`/`critical_block` | vào vòng auto-fix, tối đa 2 vòng |
+| Task vẫn fail sau 2 vòng fix | để `blocked`, **các task khác vẫn đi tiếp tới push** |
+
+Chỉ escalate cho người khi: blocker nằm ngoài repo (thiếu credential, service chết), hoặc task còn fail sau cả 2 vòng fix. Kể cả vậy vẫn phải làm xong mọi task khác trước rồi mới báo.
+
+**Quality gate không bị nới.** Bỏ chỗ *hỏi người*, không bỏ chỗ *kiểm tra*: TDD RED→GREEN vẫn bắt buộc, reviewer vẫn phải khác model executor, vẫn re-run Verification Commands, vẫn cấm claim DONE khi chưa có PASS tươi.
+
+### Run cursor — `RUN.md`
+
+Mỗi command ghi lại `docs/AI_HANDOFF/RUN.md` sau **mỗi bước**:
+
+```
+Command: <handoff-fullstack|handoff-implement|handoff-review>
+Goal: <1 câu>
+Base: <branch>
+Phase: <phase hiện tại | done>
+Cursor: wave <N> batch <M> — <vừa xong cái gì>
+Next: <bước kế tiếp chính xác>
+```
+
+`Phase:` khác `done` = có run đang dở. Command được gọi lại sẽ **chạy tiếp từ cursor**, không plan lại, không hỏi. Hook `SessionStart` (`handoff-resume.sh`) đọc file này và tự inject lệnh chạy tiếp — nên compact hay mất session giữa chừng đều không làm mất run.
+
+### Context: không bao giờ dừng giữa nhiệm vụ
+
+- Subagent ghi **full log vào task file trên đĩa**, chỉ trả về orchestrator ≤10 dòng (executor) / ≤6 dòng (reviewer). Paste log ngược lại orchestrator là nguyên nhân số 1 làm run chết vì hết context.
+- Hết mỗi wave: commit, ghi cursor, **collapse** wave đó còn 1 dòng/task trong bộ nhớ làm việc, rồi chạy tiếp.
+- Yêu cầu `/compact` **chỉ** được đặt ở cuối command, giữa 2 cycle. Giữa cycle thì tuyệt đối không — state đã nằm hết ở git + `INDEX.md` + `RUN.md` nên compact ở ranh giới cycle không mất gì.
+
+### Git
+
+- `handoff-implement`: **1 commit / wave**, không push. Mỗi wave revert độc lập được.
+- `handoff-review` / `handoff-fullstack`: commit thêm mỗi vòng auto-fix, rồi **push 1 lần** ở cuối. Push không hỏi (`Bash(git push:*)` nằm trong `allow`); force-push vẫn bị `deny`.
+
 ## Handoff Flow (tool-agnostic, file-based state machine)
 
 UKit handoff hoạt động qua **file state**. Anh tự chọn tool nào cho từng phase — Claude Code / Kilo Code / Codex / OpenCode / tool mới sau này — đều được. UKit chỉ care về **role của model**, không care tool.
@@ -72,23 +119,24 @@ pending_review ──[reviewer]──▶ approved | approved_minor ──▶ don
 **Phase 1 — Idea + Plan** (smart/reasoning model)
 - Human submit ideas (natural language).
 - AI ghi vào `PLAN.md`: §1 Intent, §2 Scope, §3 Approach, **§4 Test Plan (bắt buộc TDD-style)**, §5 Verification Commands, §6 Acceptance Criteria.
-- Output: PLAN.md đầy đủ, chờ human approve.
+- Đây là **cửa sổ hỏi duy nhất** của cả pipeline: gom mọi câu hỏi vào 1 lần `AskUserQuestion` trước khi viết, ghi câu trả lời vào §1.
+- Output: PLAN.md đầy đủ + Planner Self-Audit. Chạy standalone (`/ukit:handoff-create`) thì dừng ở đây chờ human xem; chạy trong `/ukit:handoff-fullstack` thì đi thẳng tiếp sang Phase 2 — plan review độc lập là gate thay cho human.
 
 **Phase 2 — Create Tasks (TDD-embedded, MANDATORY)** (smart/reasoning model, thường cùng phase 1)
 - Human approve plan → AI split `PLAN.md §7` sang nhiều `tasks/TASK-xxx.md`.
 - **Mỗi TASK file BẮT BUỘC có Test Plan của riêng nó**, không chỉ trỏ về PLAN.md. Cụ thể:
-  - `§ Test Cases`: bảng test (loại, tên test, expected) cho phần task này — happy + ≥1 edge case + regression (nếu fix bug).
+  - `§ Test Cases`: bảng test (loại, tên test, expected) cho phần task này — happy + ≥2 edge case KHÁC loại nhau (vd null/empty + boundary/concurrent, không tính 2 case gần giống nhau) + regression (nếu fix bug).
   - `§ Test Files`: đường dẫn cụ thể file test sẽ tạo/sửa (ví dụ `tests/auth/login.test.js`).
-  - `§ Verification Commands`: lệnh executor sẽ chạy để xác nhận PASS.
+  - `§ Verification Commands`: lệnh executor sẽ chạy để xác nhận PASS. Nếu project có sẵn lint/typecheck script → BẮT BUỘC liệt kê ở đây, không chỉ lệnh test. Project không có thì ghi rõ N/A, không được bỏ qua im lặng.
   - `§ Acceptance Criteria`: checklist.
 - Nếu split mà task nào không kèm được Test Cases + Test Files cụ thể → task đó chưa đủ `ready`, đánh `needs_breakdown`.
 - Update `INDEX.md`: thêm row mỗi task với status `ready`.
-- Đây là **điểm cắt human-approval**: phase này xong, executor được phép pick.
+- Đây là **điểm cắt cuối trước khi code chạy**: phase này xong, executor được phép pick. Trong `/ukit:handoff-fullstack`, gate ở đây là plan review độc lập (model mạnh, context riêng) chứ không phải human — vì người dùng đã chủ động chọn chạy one-shot.
 - Mục tiêu: executor (cheap-smart model) đọc task file là biết NGAY test gì cần viết trước, KHÔNG phải tự suy diễn.
 
 **Phase 3 — Implement + Test** (cheap-smart/code model)
 - User: "execute next task" / "làm TASK-001" / "implement task 1".
-- Executor đọc `INDEX.md` → pick `ready` task → đổi `in_progress` → **viết test trước → RED → implement → GREEN** → chạy Verification Commands fresh trong turn → append `## Executor Report` (gồm `EXECUTOR_TOOL`/`EXECUTOR_MODEL`/`EXECUTOR_SUBAGENT` + verification output) vào cuối task file → đổi status `pending_review`.
+- Executor đọc `INDEX.md` → pick `ready` task → đổi `in_progress` → **viết test trước → RED (paste output failing thật, không chỉ khai đã confirm) → implement → GREEN** → chạy Verification Commands fresh trong turn → append `## Executor Report` (gồm `EXECUTOR_TOOL`/`EXECUTOR_MODEL`/`EXECUTOR_SUBAGENT`/`RED_OUTPUT` + verification output) vào cuối task file → đổi status `pending_review`.
 - KHÔNG được claim DONE nếu chưa có PASS fresh.
 
 **Phase 4 — Review + Test** (reviewer model — KHÁC model executor)
@@ -108,8 +156,8 @@ A task is `ready` only when it has:
 - Dependencies stated
 - **Interfaces** — Consumes/Produces với chữ ký thật (function/endpoint/type), không placeholder;
   `(none)` hợp lệ nếu task không có input/output liên task
-- **Test Plan** (PLAN.md §4) — happy path + ≥1 edge case (+ regression test nếu fix bug); hoặc `N/A` kèm lý do
-- Verification command (lệnh executor sẽ chạy)
+- **Test Plan** (PLAN.md §4) — happy path + ≥2 edge case khác loại (+ regression test nếu fix bug); hoặc `N/A` kèm lý do
+- Verification command (lệnh executor sẽ chạy) — PHẢI gồm lint/typecheck nếu project có sẵn
 - Acceptance criteria
 
 Missing any → `needs_breakdown`, `blocked`, or `needs_human`.

package/templates/ukit/storage/config.json

@@ -186,11 +186,24 @@
   "handoff": {
     "enabled": true,
     "crossTool": true,
-    "maxParallelAgents": 3,
+    "maxParallelAgents": 10,
+    "autonomy": {
+      "askWindow": "plan-only",
+      "planReviewRounds": 2,
+      "autoFixRounds": 2,
+      "autoSerializeFileConflicts": true,
+      "resumeFromCursor": true,
+      "runCursorFile": "docs/AI_HANDOFF/RUN.md",
+      "commitPerWave": true,
+      "pushOnComplete": true,
+      "compactAtCycleBoundaryOnly": true,
+      "agentReturnMaxLines": 10
+    },
     "plan": {
       "requireTestPlan": true,
       "minTestsHappyPath": 1,
-      "minTestsEdgeCase": 1,
+      "minTestsEdgeCase": 2,
+      "requireLintOrTypecheckInVerification": true,
       "regressionTestRequiredForBugfix": true,
       "smartModelHint": "claude-opus-5"
     },
@@ -479,11 +492,12 @@
     "handoff": {
       "enabled": "Bật Quality Gate cho handoff: plan có Test Plan, executor test-first, reviewer model khác. Tắt = quay về flow cũ (dễ lọt lỗi vặt).",
       "crossTool": "true nghĩa là handoff truyền qua file (PLAN/INDEX/tasks) chứ không qua in-process subagent — cho phép plan ở Claude Code, execute ở Kilo Code, review ở Claude Code khác model.",
-      "maxParallelAgents": "Số agent chạy song song TỐI ĐA trong một wave (mặc định 3). Một wave có nhiều task hơn số này sẽ được chia thành nhiều batch chạy lần lượt. Lý do: mỗi agent nền có context window riêng, và report của agent khi xong sẽ được inject ngược vào session chính — chạy quá nhiều cùng lúc là cách nhanh nhất làm session chính vượt context window. Hạ xuống 2 nếu task nặng; không nên vượt 3.",
+      "maxParallelAgents": "Số agent chạy song song TỐI ĐA trong một wave (mặc định 10, tăng từ 3 để giảm thời gian chờ khi có nhiều task độc lập). Một wave có nhiều task hơn số này sẽ được chia thành nhiều batch chạy lần lượt — áp dụng cho cả Phase 3 Implement và Phase 4 Review. Lý do giới hạn vẫn còn: mỗi agent nền có context window riêng, và report của agent khi xong sẽ được inject ngược vào session chính — chạy quá nhiều cùng lúc (vd 20+) vẫn có thể làm session chính vượt context window và bỏ lại worktree rác. Hạ xuống 3-5 nếu task nặng (verification output dài) hoặc thấy compact bị trigger liên tục; tránh vượt quá ~10-15.",
       "plan": {
         "requireTestPlan": "Bắt buộc PLAN.md §4 phải có Test Plan trước khi task chuyển ready.",
         "minTestsHappyPath": "Tối thiểu test cho happy path.",
-        "minTestsEdgeCase": "Tối thiểu test cho edge case (null/empty/boundary/concurrent…).",
+        "minTestsEdgeCase": "Tối thiểu test cho edge case (mặc định 2, tăng từ 1 — phải khác loại nhau, vd null/empty + boundary/concurrent, không tính 2 test gần giống nhau là đủ).",
+        "requireLintOrTypecheckInVerification": "Nếu project có sẵn lint/typecheck script (package.json hoặc tương đương), Verification Commands của mỗi task BẮT BUỘC phải gồm lệnh đó — không chỉ chạy test. Project không có lint/typecheck thì planner phải ghi rõ lý do N/A thay vì bỏ qua im lặng.",
         "regressionTestRequiredForBugfix": "Bug fix phải có regression test fail-trước-fix.",
         "smartModelHint": "Gợi ý model mạnh nhất cho phase plan (ví dụ claude-opus-5). UKit không tự ép, chỉ ghi hint vào task."
       },