@ngockhoale/ukit 1.5.2 → 1.5.5

package/templates/docs/WORKLOG.md

@@ -2,6 +2,17 @@
 
 Track session-level execution details.
 
+## Budget Rules
+
+Keep this file compact to save AI context tokens:
+
+- **Max 30 entries.** When over, archive the oldest entries to `docs/WORKLOG_ARCHIVE.md`.
+- **Max ~600 lines.** If over, archive oldest entries until under budget.
+- Each entry should be 10-20 lines max (summary, not transcript).
+- On archive: move full entry block to `docs/WORKLOG_ARCHIVE.md` (create if missing).
+- Keep a compaction marker as the last line: `<!-- Entries before YYYY-MM archived to docs/WORKLOG_ARCHIVE.md. Keep this file < 600 lines. -->`
+- If the user says "compact worklog" or "clean worklog", perform the archive pass and report what moved.
+
 For each significant action, append:
 - Date/time
 - Action taken

package/templates/ukit/storage/config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.5.2",
+  "version": "1.5.5",
   "agent": "claude-code",
   "autonomy": {
     "level": "balanced",
@@ -156,6 +156,45 @@
     "deltaMaxHunks": 3,
     "deltaMaxDiffCells": 2000000
   },
+  "handoff": {
+    "enabled": true,
+    "crossTool": true,
+    "plan": {
+      "requireTestPlan": true,
+      "minTestsHappyPath": 1,
+      "minTestsEdgeCase": 1,
+      "regressionTestRequiredForBugfix": true,
+      "smartModelHint": "claude-opus-4-6"
+    },
+    "executor": {
+      "testFirstRequired": true,
+      "mustRunVerificationInTurn": true,
+      "blockDoneWithoutFreshPass": true,
+      "cheapSmartModelHint": "unic-code",
+      "appendReportToTaskFile": true
+    },
+    "reviewer": {
+      "enabled": true,
+      "model": "unic-smart",
+      "agent": "code-reviewer",
+      "mustDifferFromExecutor": true,
+      "blockOnCritical": true,
+      "blockOnChangesRequested": true,
+      "rerunVerificationCommands": true,
+      "appendVerdictToTaskFile": true
+    },
+    "statusFlow": [
+      "ready",
+      "in_progress",
+      "pending_review",
+      "changes_requested",
+      "critical_block",
+      "approved",
+      "approved_minor",
+      "blocked",
+      "done"
+    ]
+  },
   "subagents": {
     "enabled": true,
     "smallTaskModel": "unic-lite",
@@ -259,6 +298,30 @@
         "field": "compact.codexContext.autoCompact",
         "mac_dinh": true,
         "y_nghia": "Chỉ set false khi đang debug hành vi compact của UKit."
+      },
+      "doi_reviewer_model": {
+        "field": "handoff.reviewer.model",
+        "mac_dinh": "unic-smart",
+        "y_nghia": "Model dùng cho reviewer agent ở Phase 3. BẮT BUỘC khác model executor để bắt được lỗi mà executor miss. Có thể dùng claude-opus-4-6, unic-smart, hoặc bất kỳ model reasoning mạnh nào.",
+        "vi_du": "Nếu executor là unic-code (Kilo Code), set reviewer.model=unic-smart hoặc claude-opus-4-6. Nếu executor là claude-sonnet, set reviewer thành claude-opus."
+      },
+      "tat_reviewer_phase": {
+        "field": "handoff.reviewer.enabled",
+        "mac_dinh": true,
+        "y_nghia": "Tắt Phase 3 review nếu muốn chạy nhanh prototype. KHÔNG khuyến nghị cho code production — bỏ review là bỏ lưới an toàn cuối cùng.",
+        "khi_nao_tat": "Chỉ tắt cho throw-away prototype hoặc khi anh tự review thủ công."
+      },
+      "block_handoff_khi_critical": {
+        "field": "handoff.reviewer.blockOnCritical",
+        "mac_dinh": true,
+        "y_nghia": "Nếu reviewer báo CRITICAL → task không được phép done; executor phải fix và review lại. Set false chỉ khi muốn cảnh báo mềm.",
+        "khuyen_nghi": "Giữ true. Đây là rào chắn chống ship lỗi nghiêm trọng."
+      },
+      "bat_test_plan_bat_buoc": {
+        "field": "handoff.plan.requireTestPlan",
+        "mac_dinh": true,
+        "y_nghia": "Planner phải hoàn thành PLAN.md §4 (Test Plan) trước khi task chuyển ready. Tắt sẽ làm UKit cho phép skip TDD — kéo theo executor dễ làm sót.",
+        "khuyen_nghi": "Giữ true."
       }
     },
     "version": "Phiên bản config runtime đi kèm package UKit.",
@@ -374,6 +437,35 @@
       "deltaMaxChangedLines": "Ngân sách dòng đổi mặc định cho kiểm tra delta sau này.",
       "deltaMaxHunks": "Ngân sách hunk đổi mặc định cho kiểm tra delta sau này.",
       "deltaMaxDiffCells": "Giới hạn cell LCS khi tính delta; quá ngưỡng này UKit dùng fallback tuyến tính để tránh chậm trên file rất lớn."
+    },
+    "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.",
+      "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…).",
+        "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-4-6). UKit không tự ép, chỉ ghi hint vào task."
+      },
+      "executor": {
+        "testFirstRequired": "Executor phải viết test trước khi implement (RED → GREEN).",
+        "mustRunVerificationInTurn": "Phải chạy Verification Commands trong cùng turn báo DONE; không tin output cũ.",
+        "blockDoneWithoutFreshPass": "Không cho phép STATUS:DONE nếu chưa có PASS fresh trong turn này.",
+        "cheapSmartModelHint": "Gợi ý model rẻ-mà-vẫn-thông-minh cho executor (ví dụ unic-code). UKit chỉ ghi hint.",
+        "appendReportToTaskFile": "Executor append `## Executor Report` vào cuối task file để reviewer (tool khác) đọc được."
+      },
+      "reviewer": {
+        "enabled": "Bật Phase 3 review độc lập. Tắt = bỏ lưới an toàn cuối cùng, không khuyến nghị.",
+        "model": "Model reviewer. BẮT BUỘC khác executor model. Mặc định unic-smart; có thể dùng claude-opus-4-6 hoặc bất kỳ model reasoning mạnh nào.",
+        "agent": "Tên reviewer agent (xem .claude/agents/code-reviewer.md).",
+        "mustDifferFromExecutor": "Nếu true, reviewer tự refuse khi phát hiện cùng model với executor.",
+        "blockOnCritical": "CRITICAL → block handoff cứng. Set false chỉ khi muốn warning mềm.",
+        "blockOnChangesRequested": "CHANGES-REQUESTED → block handoff đến khi fix. Set false sẽ cho phép done với issue Important.",
+        "rerunVerificationCommands": "Reviewer phải tự chạy lại Verification Commands, không tin output executor.",
+        "appendVerdictToTaskFile": "Reviewer append `## Reviewer Verdict` vào task file để khép vòng handoff."
+      },
+      "statusFlow": "Danh sách status hợp lệ trong INDEX.md. Đổi tên trong này = đổi state machine handoff."
     }
   }
 }

package/templates/docs/AI_HANDOFF.md

@@ -1,118 +0,0 @@
-# AI Handoff — {{project.name}}
-
-Dùng file này làm active handoff duy nhất cho project.
-Source code và test vẫn là sự thật cuối cùng.
-
----
-
-## 1. Current Cycle Snapshot
-
-- Handoff status: `draft | ready_for_planning | ready_for_breakdown | ready_for_implementation | blocked | ready_for_next_cycle | done`
-- Current phase: `planning | breakdown | implementation | verification | wrap_up | cleared`
-- Updated at:
-- Updated by AI:
-- Human decision needed: `yes | no`
-- Human decision summary:
-
----
-
-## 2. Handoff Rules
-
-### How human should submit ideas
-- Có thể nói tự nhiên: `ukit:handoff`, `đưa vào handoff`, `gom các ý tưởng này thành task`, `chia việc cho AI làm tiếp`.
-- Nếu request đã là task cụ thể, rõ file/logic/đầu ra hoặc đủ nhỏ để làm ngay, bypass handoff và thực hiện trực tiếp.
-- Nếu request là ý tưởng rộng, nhiều tính năng, cải tiến mơ hồ, brainstorming, nhiều plan/task, hoặc cần chia cho AI kế tiếp, dùng handoff.
-
-### Default handoff flow
-1. Capture ideas/request.
-2. Write a concrete plan.
-3. Split the plan into ordered tasks.
-4. Add target files, verification, dependencies, acceptance criteria, and stop conditions.
-5. Resolve `ready` tasks in order.
-6. Update this file with results.
-7. Clear active handoff by keeping summary + carry-forward backlog only.
-
-### Fast-AI task gate
-Một task chỉ được là `ready` khi có:
-- target file/folder rõ;
-- action cụ thể;
-- dependency/blocker rõ;
-- verification rõ;
-- acceptance criteria rõ;
-- stop condition rõ;
-- không cần đoán product decision.
-
-Nếu thiếu, để `needs_breakdown`, `blocked`, hoặc `needs_human`.
-
-### Clear rule
-- `clear handoff` không bao giờ là wipe mù.
-- Trước khi clear, AI phải resolve hoặc triage task còn lại.
-- Completed work thành summary ngắn.
-- Unfinished work thành carry-forward backlog ngắn.
-- Sau clear, file phải ngắn, sẵn sàng cho cycle tiếp theo.
-
-### Docs sync rule
-- Handoff không thay thế docs.
-- Sau khi xong cycle, update các file docs trực tiếp bị ảnh hưởng như `docs/WORKLOG.md`, `docs/PROJECT.md`, `docs/CODE_MAP.md`, `CHANGELOG.md` nếu có liên quan.
-- Không cần update toàn bộ `docs/` nếu không bị ảnh hưởng.
-
----
-
-## 3. Completed Cycle Summary
-
-### Cycle summary
-- completed:
-- verification:
-- important decisions:
-- carry-forward needed:
-
----
-
-## 4. Carry-Forward Backlog
-
-### TASK-001
-- Title:
-- Priority: `P0-now | P1-next | P2-later | blocked | needs_human`
-- Size: `S | M | L`
-- AI capability: `fast_ai_ok | needs_smart_ai | needs_human`
-- Goal:
-- Target files:
-- Dependencies:
-- Must do:
-- Must not do:
-- Acceptance criteria:
-- Verification:
-- Stop condition:
-- Status: `ready | blocked | in_progress | done | needs_breakdown | needs_human`
-- Owner AI:
-
-### TASK-002
-- Title:
-- Priority: `P0-now | P1-next | P2-later | blocked | needs_human`
-- Size: `S | M | L`
-- AI capability: `fast_ai_ok | needs_smart_ai | needs_human`
-- Goal:
-- Target files:
-- Dependencies:
-- Must do:
-- Must not do:
-- Acceptance criteria:
-- Verification:
-- Stop condition:
-- Status: `ready | blocked | in_progress | done | needs_breakdown | needs_human`
-- Owner AI:
-
----
-
-## 5. Decisions Made By Human
-
-- 
-- 
-
----
-
-## 6. Do Not Lose This Context
-
-- 
-- 
--