@ngockhoale/ukit 2.5.0 → 2.6.0

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,
@@ -545,7 +575,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."
+      }
     }
   }
 }