@ngockhoale/ukit 1.1.8 → 1.2.1

package/templates/docs/PROJECT.md

@@ -45,7 +45,8 @@
 1. Run `ukit memory recall "<current task>"` for non-trivial work; reuse relevant `## Previous Context` before asking the user to restate prior decisions
 2. Read `docs/MEMORY.md` — architecture decisions, active constraints, known bugs
 3. Read `docs/STATUS.md` for open-ended status/continue prompts or meaningful continuation context; treat stale status as orientation only
-4. Read `docs/CODE_MAP.md` if it exists — structural navigation index
-5. Use the installed source-code index / routed helpers to localize the smallest relevant file + test set first
-6. Scan recent `docs/WORKLOG.md` entries if continuing prior work
-7. Verify understanding against source before acting — **docs orient, source is truth; keep the index-first workflow intact**
+4. Read `docs/TASKS.md` only when selecting queued AI work, or when status points at queued tasks; apply safe cleanup without deleting unfinished human intent
+5. Read `docs/CODE_MAP.md` if it exists — structural navigation index
+6. Use the installed source-code index / routed helpers to localize the smallest relevant file + test set first
+7. Scan recent `docs/WORKLOG.md` entries if continuing prior work
+8. Verify understanding against source before acting — **docs orient, source is truth; keep the index-first workflow intact**

package/templates/docs/STATUS.md

@@ -78,4 +78,4 @@ If this file is stale, AI must treat it as orientation only and verify against s
 
 ## Future Candidate: Task Context Files
 
-v1.2 candidate: task-scoped `docs/context/<slug>.md` files for granular bug/feature context. Keep this out of v1.1.8 scope unless a project already uses that folder.
+v1.2 candidate: task-scoped `docs/context/<slug>.md` files for granular bug/feature context. Keep this out of default scope unless a project already uses that folder.

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.1 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,65 @@
 {
-  "version": "1.1.8",
+  "version": "1.2.1",
   "agent": "claude-code",
   "compact": {
     "enabled": true,
     "tokenThreshold": 100000,
     "contextRotDetection": true,
-    "askBeforeDrop": true
+    "askBeforeDrop": true,
+    "codexContext": {
+      "enabled": true,
+      "autoCompact": true,
+      "budgetTokens": 60000,
+      "compactTarget": 150,
+      "compactTargetUnit": "lines",
+      "decisionModelEnv": "UKIT_SMALL_TASK_MODEL",
+      "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,
+      "decisionModelEnv": "UKIT_SMALL_TASK_MODEL",
+      "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 +87,65 @@
     "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
+    }
   }
 }