@ngockhoale/ukit 2.5.1 → 2.6.2

package/templates/docs/AI_HANDOFF/RULES.md

@@ -19,10 +19,12 @@
 
 Mọi giao tiếp giữa các AI trong handoff CHỈ qua file dưới `docs/AI_HANDOFF/`:
 
+- `SPEC.md` — spec chi tiết (15 section, viết ở handoff-create trước PLAN tasks). Executor implement theo SPEC + task file, không theo prompt thô.
 - `PLAN.md` — brainstorm + Test Plan tổng (Phase 1).
 - `INDEX.md` — bảng task + status (mọi phase đọc/ghi).
 - `tasks/TASK-xxx.md` — nơi sống của từng task: Goal + Test Cases + Verification + Executor Report + Reviewer Verdict + **Discussion thread**.
 - `ACTIVE.md` — snapshot cycle hiện tại.
+- `RUN.md` — run cursor của `/ukit:handoff-fullstack`; `Phase:` ≠ `done`/`blocked` khiến Stop gate từ chối stop → run tự chạy tiếp.
 - `archive/` — cycle cũ.
 
 **Cấm**: AI gửi câu hỏi/comment qua chat tool khác, qua commit message, hay qua file ngoài thư mục này. Lý do: cross-tool/cross-subagent chỉ đồng bộ được qua file. AI nào không đọc folder này = không tham gia handoff.
@@ -115,8 +117,38 @@ brainstorm ──[plan approved]──▶ ready ──[executor pick]──▶ i
 pending_review ──[reviewer]──▶ approved | approved_minor ──▶ done
                             ├▶ changes_requested ──[fix]──▶ in_progress
                             └▶ critical_block      ──[fix]──▶ in_progress
+<any stuck state> ──[record không resume được]──▶ cancelled_superseded → TASK-xxx-R<n> mới
 ```
 
+### Recovery — `cancelled_superseded` + `-R<n>`
+
+Task ở `pending`, stale `in_progress`, hay `blocked` mà record không resume sạch được
+(worktree mất, report mâu thuẫn, state invalid): **không bỏ lơi**. Đánh
+`cancelled_superseded`, tạo `TASK-xxx-R1` (`-R2`, …) giữ nguyên spec references +
+acceptance + verification, link `## Discussion` hai chiều, chạy task mới ngay trong
+cycle hiện tại.
+
+### Handoff-fullstack loop (autonomous)
+
+`/ukit:handoff-fullstack` = create → implement → review → recovery → docs → archive,
+chạy **đến khi không còn gì để làm**:
+
+- Chỉ 2 output kết thúc hợp lệ: `HANDOFF FULLSTACK COMPLETE` hoặc
+  `HANDOFF FULLSTACK BLOCKED`. Recap/checkpoint không phải điểm dừng — dùng form
+  `CHECKPOINT — WORK CONTINUING` rồi làm tiếp ngay.
+- Phase 0 sweep gom mọi unfinished work: INDEX, task files, cycle cũ (HISTORY/archive),
+  `docs/TASKS.md` `Ready for AI`, uncommitted WIP.
+- Quiet-period: chỉ đóng run khi backlog rỗng + `handoff.fullstack.quietScansRequired`
+  (mặc định 2) scan liên tiếp không thấy việc mới.
+- Stop gate (Claude Code): `RUN.md` `Phase:` ≠ `done`/`blocked` → Stop hook từ chối
+  stop kèm `Next:` step. Breaker `stopGateMaxStalledBlocks` (mặc định 12) thả ra nếu
+  cursor không nhích — lối thoát, không phải đường thường.
+- `handoff-clear` PHẢI đặt `Phase: done` (hoặc xóa RUN.md) — cursor sống sẽ giữ gate
+  chặn stop của session sau.
+- Phase F: docs sync (WORKLOG luôn; PROJECT/CODE_MAP/CHANGELOG khi đổi surface) →
+  archive cycle vào `archive/cycle-NN/` (khi `autoArchive=true`) → `Phase: done` →
+  Final Report với marker.
+
 ### 4 Phases
 
 **Phase 1 — Idea + Plan** (smart/reasoning model)
@@ -179,12 +211,13 @@ Missing any → `needs_breakdown`, `blocked`, or `needs_human`.
 
 ## Clear Handoff
 
-1. Archive current cycle → `archive/cycle-NNN.md`.
-2. If archive > 3 files → delete oldest, append 1-line summary to `HISTORY.md`.
+1. Archive current cycle → `archive/cycle-NNN.md` hoặc `archive/cycle-NN/` (gồm PLAN + SPEC + task files).
+2. If archive > 3 entries → delete oldest, append 1-line summary to `HISTORY.md`.
 3. Reset `ACTIVE.md` to empty template.
 4. Clear `INDEX.md`.
-5. Delete all files in `tasks/`.
-6. Clear `PLAN.md`.
+5. Delete all files in `tasks/` (keep `_TEMPLATE.md`).
+6. Clear `PLAN.md`; restore `SPEC.md` về template.
+7. **`RUN.md` → `Phase: done` hoặc xóa** — bắt buộc, không thì Stop gate chặn session sau.
 
 ## Docs Sync
 

package/templates/docs/AI_HANDOFF/SPEC.md

@@ -0,0 +1,98 @@
+# SPEC — <feature / cycle goal>
+
+<!--
+Written by the planner at handoff-create (Step 2, before PLAN.md tasks).
+Rule: cụ thể đến mức executor implement KHÔNG cần đoán — exact paths, module names,
+API methods, statuses, schemas, validation rules, permissions, empty/error states,
+migration behavior, test expectations. Section nào không áp dụng thì ghi "N/A — <lý do>",
+không xóa heading. Open question nào cũng phải chốt 1 default và ghi vào §14.
+-->
+
+## 1. Problem and context
+
+<Vấn đề, hiện trạng code/docs liên quan, tại sao cần làm ngay.>
+
+## 2. Goals
+
+- <Kết quả đo được — thành công trông như thế nào.>
+
+## 3. Non-goals
+
+- <Cái CỤ THỂ không làm trong cycle này — chặn scope creep.>
+
+## 4. User journeys
+
+- <Ai dùng, flow từng bước, kể cả unhappy path.>
+
+## 5. Functional requirements
+
+- FR-001: <requirement>
+  - Given: <pre-state>
+  - When: <action>
+  - Then: <observable result>
+  - Error cases: <invalid input → exact behavior/message>
+
+## 6. Fullstack scope
+
+### Backend
+<modules, functions, services — exact paths>
+### Database / schema / migrations
+<schema changes, migration file names, backfill behavior>
+### API contract
+<methods, routes, request/response shapes, status codes>
+### Frontend UI and state
+<components, states, empty/error/loading>
+### Integration
+<điểm nối giữa các layer>
+### Security and permissions
+<ai được làm gì, validation/authz checks>
+### Performance
+<budgets, query concerns, payload sizes>
+### Observability / logging
+<log points, metrics, error surfacing>
+### Deployment and rollback
+<feature flags, rollback path, ordering>
+
+## 7. Data model
+
+<entities, fields, types, invariants, indexes>
+
+## 8. API contract
+
+<endpoint table: method, path, request schema, response schema, error codes>
+
+## 9. UI behavior
+
+<state machine per screen: loading / empty / error / success; copy nếu user-facing>
+
+## 10. Edge cases
+
+- <concurrency, retries, offline, partial failure, large input, unicode, etc.>
+
+## 11. Test matrix
+
+| Area | Cases | Test file |
+|------|-------|-----------|
+| <unit> | <happy + edge list> | <tests/...> |
+
+## 12. Acceptance criteria
+
+- [ ] <verifiable criterion — ideally a command or observable state>
+
+## 13. Migration / upgrade steps
+
+<ordered steps for existing installs; nếu không có ghi N/A>
+
+## 14. Open questions and chosen defaults
+
+| Question | Chosen default | Rationale |
+|----------|----------------|-----------|
+| <q> | <default đã chọn> | <why> |
+
+## 15. Review checklist
+
+- [ ] Mọi FR testable (có Given/When/Then hoặc command).
+- [ ] Mọi layer fullstack được cover hoặc ghi N/A có lý do.
+- [ ] Không còn instruction mơ hồ ("improve", "better UX" không định nghĩa).
+- [ ] Dependencies giữa các phần đã ghi rõ.
+- [ ] Legacy/unfinished work từ Phase 0 sweep đã được tính vào.

package/templates/docs/AI_HANDOFF/tasks/_TEMPLATE.md

@@ -6,11 +6,14 @@ File này BẮT BUỘC giữ structure: Goal + Test Cases + Test Files + Verific
 Mọi AI (planner / executor / reviewer) đọc và ghi vào file NÀY. Không trao đổi ngoài file.
 -->
 
-- Status: `ready`  <!-- ready | in_progress | pending_review | changes_requested | critical_block | approved | approved_minor | blocked | done -->
+- Status: `ready`  <!-- ready | in_progress | pending_review | changes_requested | critical_block | approved | approved_minor | blocked | done | cancelled_superseded -->
 - Size: `M`        <!-- S | M | L — runtime budgets key off this field; defaults to M when missing -->
 - Owner: `-`       <!-- tool đang giữ task -->
 - Reviewer: `-`    <!-- model name reviewer dùng, set ở Phase 4 -->
 - Parent plan: `docs/AI_HANDOFF/PLAN.md` §<section>
+- Spec references: `docs/AI_HANDOFF/SPEC.md` §<n>, §<n>  <!-- FR/section IDs this task implements -->
+- Supersedes: `(none)`  <!-- hoặc TASK-xxx — recovery task (-R<n>) thay thế một record kẹt -->
+- Superseded by: `(none)` <!-- set khi status = cancelled_superseded -->
 
 ## Goal
 

package/templates/ukit/storage/config.json

@@ -144,9 +144,18 @@
       }
     },
     "modelTiers": {
-      "lite": { "claudeModel": "claude-haiku-4-5", "genericModel": "unic-lite" },
-      "code": { "claudeModel": "claude-sonnet-5", "genericModel": "unic-code" },
-      "smart": { "claudeModel": "claude-opus-5", "genericModel": "unic-smart" },
+      "lite": {
+        "claudeModel": "claude-haiku-4-5",
+        "genericModel": "unic-lite"
+      },
+      "code": {
+        "claudeModel": "claude-sonnet-5",
+        "genericModel": "unic-code"
+      },
+      "smart": {
+        "claudeModel": "claude-opus-5",
+        "genericModel": "unic-smart"
+      },
       "vision": {
         "claudeModel": "unic-vision",
         "genericModel": "unic-vision",
@@ -158,7 +167,11 @@
     "escalation": {
       "enabled": true,
       "debugLoopThreshold": 2,
-      "tierOrder": ["lite", "code", "smart"],
+      "tierOrder": [
+        "lite",
+        "code",
+        "smart"
+      ],
       "cap": "smart"
     }
   },
@@ -242,12 +255,29 @@
       "done"
     ],
     "taskBudgets": {
-      "S": { "softMin": 8, "hardMin": 15 },
-      "M": { "softMin": 15, "hardMin": 30 },
-      "L": { "softMin": 25, "hardMin": 45 },
+      "S": {
+        "softMin": 8,
+        "hardMin": 15
+      },
+      "M": {
+        "softMin": 15,
+        "hardMin": 30
+      },
+      "L": {
+        "softMin": 25,
+        "hardMin": 45
+      },
       "hardPolicy": "split"
     },
-    "milestoneIntervalMin": 5
+    "milestoneIntervalMin": 5,
+    "fullstack": {
+      "stopGateEnabled": true,
+      "stopGateMaxStalledBlocks": 12,
+      "quietScansRequired": 2,
+      "idleWatchdogMin": 5,
+      "autoArchive": true,
+      "specRequired": true
+    }
   },
   "subagents": {
     "enabled": true,
@@ -299,6 +329,7 @@
         "skill-routing-needed",
         "step-budget-enough",
         "compact-now-or-later",
+        "codex-context-budget",
         "summarize-docs-or-keep-detail"
       ],
       "stepBudgets": {
@@ -545,7 +576,15 @@
         "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."
+      "statusFlow": "Danh sách status hợp lệ trong INDEX.md. Đổi tên trong này = đổi state machine handoff.",
+      "fullstack": {
+        "stopGateEnabled": "Bật Stop gate handoff: RUN.md Phase != done/blocked → Stop hook từ chối stop kèm Next step, giữ handoff-fullstack chạy tiếp thay vì đứng sau recap. Tắt chỉ khi debug.",
+        "stopGateMaxStalledBlocks": "Liveness breaker: cursor không nhích qua N lần block liên tiếp thì gate thả stop (tránh vòng lặp vô tận). Mặc định 12.",
+        "quietScansRequired": "Số scan liên tiếp không thấy việc mới trước khi handoff-fullstack được phép đóng run. Mặc định 2.",
+        "idleWatchdogMin": "Khoảng phút cho scheduled wakeup nếu harness hỗ trợ (cron/loop). Mặc định 5.",
+        "autoArchive": "true = Phase F tự archive cycle vào docs/AI_HANDOFF/archive/cycle-NN/ khi hoàn tất.",
+        "specRequired": "true = handoff-create bắt buộc viết docs/AI_HANDOFF/SPEC.md chi tiết trước khi tạo task."
+      }
     }
   }
 }