@ngockhoale/ukit 1.1.7 → 1.2.1

package/templates/docs/STATUS.md

@@ -0,0 +1,81 @@
+# Project Status — {{project.name}}
+
+> Living project state for AI sessions.
+> Keep this compact: current state only, not a session transcript.
+> Source code, tests, and the UKit index remain ground truth.
+
+## Freshness
+
+- Last meaningful update: TODO YYYY-MM-DD HH:mm
+- Updated by: TODO
+- Status confidence: low
+- Stale after: 72h
+
+If this file is stale, AI must treat it as orientation only and verify against source/index before recommending or editing.
+
+## Snapshot
+
+- Current focus: TODO
+- Health: unknown
+- Branch/state: TODO
+- Release/version: TODO
+
+## Active Work
+
+<!-- Keep only live work. Move finished work to Recently Completed or WORKLOG.md. -->
+
+### TODO work item
+
+- Status: planned / in-progress / blocked / done
+- Goal: TODO
+- Done: TODO
+- Remaining: TODO
+- Files involved: TODO
+- Verification: TODO
+- Next action: TODO
+
+## Current Debug Threads
+
+<!-- Detailed bug context belongs in docs/context/<task>.md when that exists. STATUS should only link/summarize. -->
+
+### TODO debug thread
+
+- Status: investigating / root cause found / fixed / blocked
+- Symptom: TODO
+- Root cause: unknown
+- Evidence: TODO
+- Changed files: TODO
+- Verification: TODO
+- Remaining risk: TODO
+- Next action: TODO
+
+## Decisions Pending
+
+- [ ] TODO decision
+  - Context: TODO
+  - Options: TODO
+  - Recommended: TODO
+
+## Next Candidates
+
+1. TODO candidate
+   - Why now: TODO
+   - Expected files: TODO
+   - Verification: TODO
+   - Risk: TODO
+
+## Recently Completed
+
+<!-- Max 10 compact lines. Use docs/WORKLOG.md for session history. -->
+
+- TODO YYYY-MM-DD — summary — verification
+
+## Notes for Next AI Session
+
+- Read first: docs/STATUS.md, then docs/CODE_MAP.md only if navigation is needed.
+- Avoid: treating this file as source truth when it is stale or contradicted by code/tests.
+- Known traps: keep concrete debug/implementation prompts on their specific workflow; do not turn them into global roadmap suggestions.
+
+## Future Candidate: Task Context Files
+
+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

@@ -14,6 +14,7 @@ UKit should handle:
 - hidden skill selection
 - source-code indexing
 - compact context selection
+- living project status for open-ended continuation prompts
 - targeted verification
 - optional internal delegation when it is actually useful
 
@@ -127,6 +128,22 @@ Expected UKit behavior:
 2. use DuraOne references only when the repo actually matches that domain/shape
 3. keep the user away from manual skill selection
 
+### F) Continue / what next
+
+User says:
+
+```text
+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. 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
+
 ---
 
 ## What users should NOT need to do

package/templates/ukit/README.md

@@ -1,6 +1,6 @@
 # UKit Shared Runtime
 
-This folder stores shared UKit runtime state for v1.1.7 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.7",
+  "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
+    }
   }
 }