@ngockhoale/ukit 1.1.8 → 1.2.2

package/templates/docs/TASKS.md

@@ -0,0 +1,79 @@
+# AI Task Queue — {{project.name}}
+
+> Local AI task queue.
+> Use this for work the human wants an AI/agent to pick up later.
+> Keep tasks actionable; source code, tests, and project docs remain ground truth.
+
+## How to Use
+
+- Human or AI can add tasks here when work is deferred.
+- AI should read this for open-ended “what next?” / “continue” prompts, or when the user asks to work from the task queue.
+- AI/agents may implement tasks from `Ready for AI`; do not dispatch from `Inbox` until the task has acceptance and verification notes.
+- This file is local working state, not project history and not a full roadmap.
+- Completed work belongs in `docs/WORKLOG.md`; current state belongs in `docs/STATUS.md`.
+
+## Auto-Cleanup Rules
+
+AI should keep this file compact by default whenever it reads or updates the queue:
+
+- Auto-remove exact duplicate tasks.
+- Auto-prune `Done Recently` to max 10 compact lines.
+- Auto-remove tasks from active sections after all are true:
+  - the task is done,
+  - verification is recorded,
+  - completion is summarized in `docs/WORKLOG.md` or `Done Recently`.
+- Auto-move stale, vague, or blocked tasks to `Deferred / Needs Human Review` instead of deleting them.
+- Do not delete non-completed human-authored tasks unless the user explicitly asks for cleanup and the task is clearly obsolete or duplicated.
+- If the user says “clean tasks” / “dọn tasks”, perform the cleanup pass and report what changed.
+
+## Inbox
+
+<!-- Raw ideas go here first. Refine before moving to Ready for AI. -->
+
+- [ ] TODO task title
+  - Why: TODO
+  - Context: TODO
+  - Expected files: TODO
+  - Acceptance: TODO
+  - Verification: TODO
+  - Risk: low / medium / high
+
+## Ready for AI
+
+<!-- Tasks here should be specific enough for an AI/agent to start without scanning the whole repo. -->
+
+- [ ] TODO ready task
+  - Goal: TODO
+  - Files likely involved: TODO
+  - Constraints: TODO
+  - Acceptance: TODO
+  - Verification: TODO
+  - Notes: TODO
+
+## In Progress
+
+- [ ] TODO active task
+  - Owner: human / Claude / Codex / OpenCode / agent
+  - Started: TODO YYYY-MM-DD
+  - Current state: TODO
+  - Next action: TODO
+
+## Blocked / Waiting
+
+- [ ] TODO blocked task
+  - Blocker: TODO
+  - Needed from human: TODO
+
+## Deferred / Needs Human Review
+
+<!-- AI should move stale/vague/blocked tasks here instead of deleting uncertain human intent. -->
+
+- [ ] TODO deferred task
+  - Reason deferred: TODO
+  - Last touched: TODO YYYY-MM-DD
+
+## Done Recently
+
+<!-- Keep max 10. Older completed work belongs in docs/WORKLOG.md. -->
+
+- TODO YYYY-MM-DD — task — verification

package/templates/docs/UKIT_USAGE_GUIDE.md

@@ -139,9 +139,10 @@ Project đang ở đâu, làm gì tiếp?
 Expected UKit behavior:
 1. auto-load the hidden next-step lane
 2. read `docs/STATUS.md` first and show whether it is fresh, possibly stale, stale, or missing
-3. suggest only a few actionable next candidates
-4. if status is stale, verify with source/index before treating any candidate as authoritative
-5. if the prompt names a concrete bug/feature/review target, keep the concrete workflow primary instead of producing a global roadmap
+3. read `docs/TASKS.md` only when selecting queued work or when status points at queued tasks
+4. suggest only a few actionable next candidates
+5. if status/tasks are stale, verify with source/index before treating any candidate as authoritative
+6. if the prompt names a concrete bug/feature/review target, keep the concrete workflow primary instead of producing a global roadmap
 
 ---
 

package/templates/ukit/README.md

@@ -1,6 +1,6 @@
 # UKit Shared Runtime
 
-This folder stores shared UKit runtime state for v1.1.8 features.
+This folder stores shared UKit runtime state for v1.2.2 features.
 
 - `storage/config.json` — runtime feature flags and defaults
 - `storage/cache/` — prompt-cache, compact history, compact pressure state, output summaries, and preserved raw tool outputs under `storage/cache/tee/`

package/templates/ukit/storage/config.json

@@ -1,11 +1,63 @@
 {
-  "version": "1.1.8",
+  "version": "1.2.2",
   "agent": "claude-code",
   "compact": {
     "enabled": true,
     "tokenThreshold": 100000,
     "contextRotDetection": true,
-    "askBeforeDrop": true
+    "askBeforeDrop": true,
+    "codexContext": {
+      "enabled": true,
+      "autoCompact": true,
+      "budgetTokens": 100000,
+      "compactTarget": 150,
+      "compactTargetUnit": "lines",
+      "decisionAgent": "ukit-small-task-maintainer",
+      "mode": "soft-handoff",
+      "preserve": [
+        "current-goal",
+        "non-negotiable-rules",
+        "active-files",
+        "decisions",
+        "unresolved-failures",
+        "verification-evidence",
+        "next-actions"
+      ],
+      "compactTargetRecommendedRange": [
+        120,
+        170
+      ],
+      "compactTargetMax": 170
+    },
+    "agentContext": {
+      "enabled": true,
+      "decisionAgent": "ukit-small-task-maintainer",
+      "executionMode": "sidecar-parallel",
+      "mustNotBlockMainTask": true,
+      "targets": {
+        "claude": {
+          "autoCompact": true,
+          "mode": "precompact-reinject",
+          "preserveExistingHooks": true
+        },
+        "opencode": {
+          "autoCompact": true,
+          "mode": "native-auto-prune",
+          "preserveExistingCompaction": true
+        },
+        "codex": {
+          "autoCompact": true,
+          "mode": "soft-handoff",
+          "compactTarget": 150,
+          "compactTargetUnit": "lines",
+          "compactTargetRecommendedRange": [
+            120,
+            170
+          ],
+          "compactTargetMax": 170
+        }
+      }
+    }
   },
   "tokenPipeline": {
     "inputCompression": true,
@@ -33,5 +85,194 @@
     "autoRetry": true,
     "maxRetries": 1,
     "confidenceThreshold": 50
+  },
+  "subagents": {
+    "enabled": true,
+    "smallTaskModel": "unic-lite",
+    "smallTaskAgent": "ukit-small-task-maintainer",
+    "smallTaskUseCases": [
+      "task-cleanup",
+      "compact-decision",
+      "codex-context-budget",
+      "doc-summarization",
+      "classification",
+      "small-decision",
+      "auto-triage",
+      "queue-maintenance",
+      "workspace-maintenance"
+    ],
+    "keepMainModelFor": [
+      "security",
+      "risky-code-change",
+      "release",
+      "data-loss",
+      "architecture-decision",
+      "deep-reasoning"
+    ],
+    "decisionPolicy": {
+      "nonBlocking": true,
+      "endUserInvisible": true,
+      "handBackOnRisk": true,
+      "optimizeOrder": [
+        "quality",
+        "safety",
+        "speed",
+        "token-discipline"
+      ],
+      "decisions": [
+        "fast-vs-slow-lane",
+        "safe-vs-risky-lane",
+        "skill-routing-needed",
+        "step-budget-enough",
+        "compact-now-or-later",
+        "summarize-docs-or-keep-detail"
+      ],
+      "stepBudgets": {
+        "trivial": {
+          "maxSteps": 1,
+          "verification": "skip-unless-risky"
+        },
+        "simple": {
+          "maxSteps": 2,
+          "verification": "targeted-if-covered"
+        },
+        "nonTrivial": {
+          "maxSteps": 4,
+          "verification": "targeted-then-widen-on-risk"
+        }
+      },
+      "executionMode": "sidecar-parallel",
+      "mustNotBlockMainTask": true,
+      "maxSidecarWaitMs": 0
+    }
+  },
+  "_help": {
+    "README": {
+      "muc_dich": "Đây là file cấu hình runtime duy nhất của UKit, khi install sẽ nằm ở .ukit/storage/config.json. Không dùng .env để chỉnh UKit nữa.",
+      "ai_nen_sua": "Người dùng bình thường vẫn chỉ cần nhớ `ukit install`. Maintainer hoặc power user mới cần sửa file JSON này để chỉnh cách UKit tự điều phối AI.",
+      "cach_sua": "Chỉ sửa value, không đổi tên key. Đây là JSON chuẩn: string phải dùng dấu nháy kép, có dấu phẩy giữa các field, không dùng // comment.",
+      "nguyen_tac_chat_luong": "Luôn theo UKit CoDev: chất lượng > an toàn > tốc độ > tiết kiệm token. Không chỉnh cho nhanh nếu làm AI trả lời kém hơn.",
+      "sau_khi_sua": "Sau khi sửa file này, nên mở session AI mới. Nếu muốn refresh template trong repo thì chạy lại `ukit install`."
+    },
+    "cac_chinh_sua_thuong_gap": {
+      "doi_model_noi_bo": {
+        "field": "subagents.smallTaskModel",
+        "mac_dinh": "unic-lite",
+        "y_nghia": "Model nội bộ chạy sidecar cho các quyết định nhỏ/an toàn của UKit. Không thay thế model chính đang làm task của user.",
+        "vi_du": "Đổi subagents.smallTaskModel sang tên model khác nếu unic-lite không dùng được hoặc bạn muốn model nội bộ khác."
+      },
+      "compact_codex_khi_gan_150k_token": {
+        "field": "compact.codexContext.budgetTokens",
+        "mac_dinh": 100000,
+        "co_the_tang_len": 150000,
+        "khuyen_nghi": "100000 là mức cân bằng: đủ context cho chất lượng nhưng tránh để phiên chạy tới 150k-180k token dễ gặp lỗi connection/capacity.",
+        "y_nghia": "Ngưỡng token context của Codex Desktop trước khi UKit chuẩn bị compact/handoff. Ví dụ 100000 nghĩa là gần 100k token thì compact."
+      },
+      "doi_do_dai_ban_tom_tat_codex": {
+        "field": "compact.codexContext.compactTarget",
+        "mac_dinh": 150,
+        "khoang_goi_y": [
+          120,
+          170
+        ],
+        "y_nghia": "Độ dài bản handoff sau compact, tính bằng dòng, không phải token. Không set 150000 ở đây."
+      },
+      "tat_auto_compact_codex": {
+        "field": "compact.codexContext.autoCompact",
+        "mac_dinh": true,
+        "y_nghia": "Chỉ set false khi đang debug hành vi compact của UKit."
+      }
+    },
+    "version": "Phiên bản config runtime đi kèm package UKit.",
+    "agent": "Adapter mặc định của workspace. Thường giữ nguyên theo lúc install.",
+    "compact": {
+      "enabled": "Bật/tắt toàn bộ helper compact của UKit.",
+      "tokenThreshold": "Ngưỡng token chung cho runtime compact dùng chung.",
+      "contextRotDetection": "Phát hiện context quá dài/dễ mục để giữ lại state quan trọng trước khi AI nhớ sai.",
+      "askBeforeDrop": "Giữ thái độ thận trọng trước khi bỏ context quan trọng. Nếu rủi ro thì hand back cho main model.",
+      "agentContext": {
+        "enabled": "Bật policy compact context theo từng agent.",
+        "decisionAgent": "Agent nội bộ hỗ trợ quyết định compact/handoff trong trường hợp an toàn.",
+        "executionMode": "sidecar-parallel nghĩa là lane quyết định compact chạy song song với task chính.",
+        "mustNotBlockMainTask": "Nếu true, sidecar nội bộ không được dừng/thay thế/làm chậm task chính của user.",
+        "targets": {
+          "claude": {
+            "autoCompact": "Giữ compact lane của Claude bật.",
+            "mode": "precompact-reinject nghĩa là Claude được bơm context quan trọng trước/sau compact.",
+            "preserveExistingHooks": "Nên giữ true để không gỡ PreCompact/reinject của Claude."
+          },
+          "opencode": {
+            "autoCompact": "Giữ compact lane của OpenCode bật.",
+            "mode": "native-auto-prune nghĩa là OpenCode dùng compaction.auto/prune native.",
+            "preserveExistingCompaction": "Nên giữ true để không gỡ compact native của OpenCode."
+          },
+          "codex": {
+            "autoCompact": "Bật policy soft handoff compact cho Codex Desktop.",
+            "mode": "soft-handoff nghĩa là UKit tạo/dùng state tóm tắt, không can thiệp trực tiếp vào internals của app Codex.",
+            "compactTarget": "Độ dài bản handoff sau compact, tính bằng dòng.",
+            "compactTargetUnit": "Đơn vị của compactTarget. Nên giữ là lines.",
+            "compactTargetRecommendedRange": "Khoảng số dòng khuyến nghị cho bản handoff.",
+            "compactTargetMax": "Số dòng tối đa cho bản handoff, tránh lỡ tay set quá dài."
+          }
+        }
+      },
+      "codexContext": {
+        "enabled": "Bật policy soft context handoff cho Codex Desktop.",
+        "autoCompact": "Cho phép UKit tự quyết định compact/handoff khi context Codex dài.",
+        "budgetTokens": "Ngưỡng token context của Codex Desktop trước khi compact. Mặc định 100000 để cân bằng chất lượng và giảm lỗi capacity/connection. Có thể tăng 150000 nếu cần, nhưng không nên để quá dài.",
+        "compactTarget": "Độ dài bản handoff sau compact, tính bằng dòng, không phải token. Mặc định 150; nên 120-150; tối đa 170.",
+        "compactTargetUnit": "Đơn vị của compactTarget. Nên giữ là lines.",
+        "compactTargetRecommendedRange": "Khoảng số dòng khuyến nghị. Nên ở trong khoảng này nếu không có lý do đặc biệt.",
+        "compactTargetMax": "Số dòng tối đa cho bản handoff. Chặn trường hợp lỡ set 150000 dòng.",
+        "decisionAgent": "Agent nội bộ dùng cho quyết định compact an toàn.",
+        "mode": "soft-handoff nghĩa là UKit tóm tắt state để tiếp tục thay vì replay toàn bộ transcript.",
+        "preserve": "Những thứ bắt buộc phải giữ khi compact: mục tiêu, rule, file đang làm, quyết định, lỗi chưa xử lý, bằng chứng verify, bước tiếp theo."
+      }
+    },
+    "tokenPipeline": {
+      "inputCompression": "Nén/tái sử dụng input context khi an toàn.",
+      "outputCompression": "Tóm tắt output command ồn nhưng vẫn giữ recovery hint.",
+      "promptCache": "Dùng cache prompt/context compact để giảm lặp lại."
+    },
+    "router": {
+      "enabled": "Bật task routing nội bộ.",
+      "defaultModel": "Model hint cân bằng cho công việc bình thường. Adapter/provider có thể map khác.",
+      "advisorModel": "Model hint mạnh hơn cho planning/reasoning khó khi được bật.",
+      "advisorEnabled": "Cho phép advisor-style planning cho task phức tạp.",
+      "maxAdvisorCalls": "Giới hạn số lần gọi advisor để không lãng phí."
+    },
+    "memory": {
+      "enabled": "Bật memory local của UKit.",
+      "autoCapture": "Cho phép UKit lưu decision/rule bền vững khi an toàn.",
+      "progressiveRetrieval": "Lấy memory liên quan nhỏ trước, chỉ mở rộng khi cần.",
+      "maxInjectionTokens": "Số token memory tối đa được inject vào context.",
+      "archiveAfterDays": "Sau bao nhiêu ngày memory có thể được archive/compact.",
+      "maxSessions": "Số session memory gần đây giữ active.",
+      "redactSecrets": "Cố tránh lưu secret vào memory."
+    },
+    "validation": {
+      "enabled": "Bật kiểm tra output nhẹ.",
+      "autoRetry": "Cho phép retry an toàn một lần khi validation thấy lỗi rõ.",
+      "maxRetries": "Số lần retry tối đa.",
+      "confidenceThreshold": "Ngưỡng confidence tối thiểu trước khi báo thận trọng."
+    },
+    "subagents": {
+      "enabled": "Cho phép UKit dùng các lane subagent nội bộ khi hữu ích.",
+      "smallTaskModel": "Model sidecar nội bộ cho quyết định nhỏ/an toàn của UKit. Đổi key này nếu muốn đổi model nội bộ.",
+      "smallTaskAgent": "Tên agent nội bộ phụ trách quyết định nhỏ không block task chính.",
+      "smallTaskUseCases": "Các loại việc an toàn sidecar có thể xử lý: dọn task, compact decision, phân loại, triage, queue maintenance, workspace maintenance.",
+      "keepMainModelFor": "Các việc rủi ro phải giữ ở main model: security, code risky, release, data-loss, architecture, deep reasoning.",
+      "decisionPolicy": {
+        "nonBlocking": "Sidecar nội bộ không được block task chính của user.",
+        "endUserInvisible": "Không biến orchestration nội bộ thành thứ end user phải học.",
+        "handBackOnRisk": "Nếu sidecar thấy rủi ro thì trả lại main model quyết định.",
+        "executionMode": "sidecar-parallel nghĩa là việc nội bộ có thể chạy riêng/song song với task chính.",
+        "mustNotBlockMainTask": "True nghĩa là sidecar không được dừng/thay thế/làm chậm task chính.",
+        "maxSidecarWaitMs": "0 nghĩa là không chờ sidecar trước khi tiếp tục task chính.",
+        "optimizeOrder": "Thứ tự ưu tiên khi ra quyết định nội bộ.",
+        "decisions": "Nhóm quyết định sidecar được phép hỗ trợ.",
+        "stepBudgets": "Gợi ý số bước planning tối đa theo độ lớn task trước khi reassess."
+      }
+    }
   }
 }