@ngockhoale/ukit 1.1.7 → 1.2.1

package/src/index/taskRouting.js

@@ -22,11 +22,17 @@ export async function deriveTaskRoute({
   const normalizedPrompt = String(promptText || '').trim();
   const normalizedCommand = String(commandText || '').trim();
   const normalizedTarget = normalizeRelativeFile(absoluteRoot, targetFile);
+  const intentMode = deriveIntentMode({
+    promptText: normalizedPrompt,
+    commandText: normalizedCommand,
+    targetFile: normalizedTarget,
+  });
   const activeSkills = await selectActiveSkills({
     rootDir: absoluteRoot,
     promptText: normalizedPrompt,
     commandText: normalizedCommand,
     targetFile: normalizedTarget,
+    intentMode,
   });
   const useIndexedContext = shouldUseIndexedContext({
     activeSkills,
@@ -102,6 +108,7 @@ export async function deriveTaskRoute({
       targetFile: normalizedTarget,
       contextIntent,
       taskType: inferredTaskType,
+      intentMode,
     },
     contextRecommendation,
     verificationRecommendation,
@@ -117,6 +124,7 @@ export async function deriveTaskRoute({
       targetFile: normalizedTarget,
       contextIntent,
       taskType: inferredTaskType,
+      intentMode,
     },
     contextRecommendation,
     verificationRecommendation,
@@ -167,6 +175,7 @@ export function buildRouteSummary({
     formatCompactSegment('targets', primaryTargets),
     formatCompactSegment('tests', relatedTests),
     formatCompactSegment('styles', styleFiles),
+    delegationRecommendation?.hint ? `delegate=${delegationRecommendation.hint}` : null,
     policyMode ? `policy=${policyMode}` : null,
   ].filter(Boolean).join(' | ');
 
@@ -175,6 +184,7 @@ export function buildRouteSummary({
     fallbackCommands,
     preferredOrder,
     policyMode,
+    intentMode: routingContext.intentMode ?? null,
     delegateHint: delegationRecommendation?.hint ?? null,
     nextActionType: nextAction?.type ?? null,
     nextActionCommand,
@@ -183,7 +193,7 @@ export function buildRouteSummary({
   };
 }
 
-async function selectActiveSkills({ rootDir, promptText, commandText, targetFile }) {
+async function selectActiveSkills({ rootDir, promptText, commandText, targetFile, intentMode = null }) {
   const routeSignals = {
     promptRawText: String(promptText || '').toLowerCase(),
     promptNormalizedText: buildRouteSignalText(promptText),
@@ -194,6 +204,7 @@ async function selectActiveSkills({ rootDir, promptText, commandText, targetFile
   const scoredEntries = ROUTE_CATALOG
     .map((entry) => scoreSkillRouteEntry(entry, routeSignals))
     .filter((entry) => entry.score > 0)
+    .filter((entry) => shouldKeepRouteEntryForIntent(entry, intentMode))
     .sort((a, b) => b.score - a.score || a.order - b.order);
   const active = [];
 
@@ -209,6 +220,22 @@ async function selectActiveSkills({ rootDir, promptText, commandText, targetFile
   return active.map(({ order, ...rest }) => rest);
 }
 
+function shouldKeepRouteEntryForIntent(entry, intentMode) {
+  if (entry.id === 'next-step' && ['scoped-advice', 'docs-specific'].includes(intentMode)) {
+    return false;
+  }
+
+  if (entry.id === 'update-status' && intentMode === 'docs-specific') {
+    return false;
+  }
+
+  if (entry.id === 'docs-quality' && ['open-ended-status', 'status-update'].includes(intentMode)) {
+    return false;
+  }
+
+  return true;
+}
+
 function scoreSkillRouteEntry(entry, routeSignals = {}) {
   let score = 0;
   const reasons = [];
@@ -282,6 +309,131 @@ function getSignalTexts(signalType, routeSignals = {}) {
   };
 }
 
+function deriveIntentMode({ promptText = '', commandText = '', targetFile = null } = {}) {
+  const lower = buildRouteSignalText(promptText, commandText);
+  const raw = `${promptText ?? ''}\n${commandText ?? ''}`.toLowerCase();
+  const taskQueueNext = hasTaskQueueNextSignal(lower, raw);
+  const docsSpecific = hasDocsSpecificTaskSignal(lower, raw, targetFile, { taskQueueNext });
+  const statusUpdate = hasStatusUpdateSignal(lower, raw);
+  const openEndedStatus = hasOpenEndedStatusSignal(lower, raw) || taskQueueNext;
+  const concreteTask = hasConcreteTaskSignal(lower, raw, targetFile, { taskQueueNext });
+
+  if (docsSpecific) {
+    return 'docs-specific';
+  }
+
+  if (statusUpdate) {
+    return 'status-update';
+  }
+
+  if (concreteTask && openEndedStatus) {
+    return 'scoped-advice';
+  }
+
+  if (openEndedStatus) {
+    return 'open-ended-status';
+  }
+
+  if (concreteTask) {
+    if (/\b(bug|debug|error|crash|broken|failing|stack trace|triage|fix|login|timeout)\b/.test(lower)) {
+      return 'debug-specific';
+    }
+    if (/\b(review|audit|diff|pr feedback|code review|kiem tra|soat)\b/.test(lower)) {
+      return 'review-specific';
+    }
+    if (/\b(implement|build|create|add|ship|deliver|refactor|integrate|integration|scaffold|feature)\b/.test(lower)) {
+      return 'implement-specific';
+    }
+  }
+
+  return null;
+}
+
+function hasStatusUpdateSignal(lower, raw) {
+  return /\b(update|refresh|write|sync|record|capture|summarize|summarise).{0,64}\b(status\.md|project status|current state|next candidates|session state)\b/.test(lower)
+    || /\b(status\.md|project status).{0,64}\b(update|refresh|write|sync|record|capture|summarize|summarise)\b/.test(lower)
+    || /\b(wrap up|handoff|end this session|ending this session|session summary|before final)\b/.test(lower)
+    || /\b(cap nhat|ghi lai|tong ket|chot session|ban giao).{0,64}\b(status|trang thai|viec tiep theo)\b/.test(lower)
+    || /\b(cập nhật|ghi lại|tổng kết|chốt session|bàn giao).{0,64}\b(status|trạng thái|việc tiếp theo)\b/.test(raw);
+}
+
+function hasOpenEndedStatusSignal(lower, raw) {
+  return /\b(what next|what is next|what's next|next step|next steps|project status|current status|where are we|continue|continue from last session|roadmap|status\.md|task queue|tasks\.md|next queued task|pick next task|work from tasks)\b/.test(lower)
+    || /\b(lam gi tiep|buoc tiep theo|tiep theo lam gi|lam tiep|dang o dau|trang thai project|tinh trang project|task tiep theo|viec tiep theo trong tasks)\b/.test(lower)
+    || /\b(làm gì tiếp|bước tiếp theo|tiếp theo làm gì|làm tiếp|đang ở đâu|trạng thái project|tình trạng project|task tiếp theo|việc tiếp theo trong tasks)\b/.test(raw);
+}
+
+function hasTaskQueueNextSignal(lower, raw) {
+  return /\b(task queue|tasks\.md|next queued task|pick next task|work from tasks|next task from tasks|ready for ai)\b/.test(lower)
+    || /\b(task tiếp theo|việc tiếp theo trong tasks|làm task trong tasks|lấy task tiếp theo)\b/.test(raw);
+}
+
+function hasConcreteTaskSignal(lower, raw, targetFile, { taskQueueNext = false } = {}) {
+  if (targetFile && !isStatusFileTarget(targetFile) && !(taskQueueNext && isTasksFileTarget(targetFile))) {
+    return true;
+  }
+
+  return /\b(bug|debug|error|crash|broken|failing|stack trace|triage|fix|implement|build|create|add|ship|deliver|refactor|integrate|integration|scaffold|feature|review|audit|diff|pr feedback|code review|auth|login|api|endpoint|test|spec)\b/.test(lower)
+    || /\b(sửa|fix|lỗi|bug|debug|implement|cài|thêm|review|kiểm tra|soát|đăng nhập)\b/.test(raw);
+}
+
+function hasDocsSpecificTaskSignal(lower, raw, targetFile, { taskQueueNext = false } = {}) {
+  if (!targetFile || !isDocsTarget(targetFile)) {
+    return /\b(clean tasks|cleanup tasks|prune tasks|dedupe tasks|clear completed tasks|dọn tasks|dọn task)\b/.test(lower)
+      || /\b(dọn tasks|dọn task|dọn danh sách task|xóa task đã xong)\b/.test(raw);
+  }
+
+  if (taskQueueNext && isTasksFileTarget(targetFile) && !/\b(clean|cleanup|prune|dedupe|edit|template|wording|format|structure)\b/.test(lower)) {
+    return false;
+  }
+
+  const targetName = path.posix.basename(String(targetFile || '').replaceAll('\\', '/')).toLowerCase();
+  const explicitStatusUpdate = hasExplicitStatusUpdateSignal(lower, raw);
+
+  if (!isStatusFileTarget(targetFile)) {
+    if (explicitStatusUpdate && !mentionsTargetDoc(lower, targetName)) {
+      return false;
+    }
+
+    return mentionsTargetDoc(lower, targetName)
+      || /\b(edit|write|improve|document|docs?|readme|changelog|worklog|memory|code map|template|wording|copy|grammar|format|structure|heading|section|handoff notes?)\b/.test(lower)
+      || /\b(câu chữ|chỉnh|sửa chữ|ngữ pháp|định dạng|cấu trúc|tài liệu|ghi chú bàn giao)\b/.test(raw);
+  }
+
+  return /\b(template|wording|edit|copy|grammar|format|structure|heading|section|docs?)\b/.test(lower)
+    || /\b(mẫu|câu chữ|chỉnh|sửa chữ|ngữ pháp|định dạng|cấu trúc|tài liệu)\b/.test(raw);
+}
+
+function hasExplicitStatusUpdateSignal(lower, raw) {
+  return /\b(update|refresh|write|sync|record|capture|summarize|summarise).{0,64}\b(status\.md|project status|current state|next candidates|session state)\b/.test(lower)
+    || /\b(status\.md|project status).{0,64}\b(update|refresh|write|sync|record|capture|summarize|summarise)\b/.test(lower)
+    || /\b(cap nhat|ghi lai|tong ket|chot session|ban giao).{0,64}\b(status|trang thai|viec tiep theo)\b/.test(lower)
+    || /\b(cập nhật|ghi lại|tổng kết|chốt session|bàn giao).{0,64}\b(status|trạng thái|việc tiếp theo)\b/.test(raw);
+}
+
+function mentionsTargetDoc(lower, targetName) {
+  if (!targetName) {
+    return false;
+  }
+
+  const escaped = targetName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const withoutExt = escaped.replace(/\\\.md$/i, '');
+  return new RegExp(`\\b(?:${escaped}|${withoutExt})\\b`, 'i').test(lower);
+}
+
+function isStatusFileTarget(targetFile) {
+  return /(?:^|\/)docs\/STATUS\.md$|(?:^|\/)STATUS\.md$/i.test(String(targetFile || ''));
+}
+
+function isTasksFileTarget(targetFile) {
+  return /(?:^|\/)docs\/TASKS\.md$|(?:^|\/)TASKS\.md$/i.test(String(targetFile || ''));
+}
+
+function isDocsTarget(targetFile) {
+  const normalized = String(targetFile || '').replaceAll('\\', '/');
+  return /(?:^|\/)docs\/.+\.md$|(?:^|\/)(?:README|CHANGELOG|AGENTS|CLAUDE|STATUS)\.md$/i.test(normalized);
+}
+
 function shouldUseIndexedContext({ activeSkills = [], targetFile = null } = {}) {
   if (activeSkills.length === 0) {
     return Boolean(targetFile);
@@ -453,6 +605,16 @@ function deriveDelegationRecommendation({
   const hasRelatedTests = (preview.relatedTests ?? []).length > 0;
   const when = contextRecommendation?.command ? 'after-context' : 'now';
 
+  const smallTaskMaintenanceSignal = /\b(?:ukit|docs\/tasks\.md|tasks\.md|task queue|queued tasks?|compact(?:ion)?|summari[sz](?:e|ation)|doc(?:ument)? summary|cleanup|clean up|dọn rác|dọn dẹp|auto[- ]?triage|queue maintenance|small decision|ra quyết định)\b/.test(lower)
+    && /\b(?:task|queue|compact(?:ion)?|summari[sz](?:e|ation)|doc(?:ument)?s?|cleanup|clean up|dọn rác|dọn dẹp|classif(?:y|ication)|triage|maintenance|small decision|ra quyết định)\b/.test(lower);
+  if (smallTaskMaintenanceSignal) {
+    return {
+      hint: 'ukit-small-task-maintainer',
+      when,
+      reason: 'Low-risk UKit maintenance decisions should use the configured small-task model without blocking the main AI flow.',
+    };
+  }
+
   if (routingContext.taskType === 'trivial') {
     return null;
   }

package/templates/.claude/agents/ukit-small-task-maintainer.md

@@ -0,0 +1,72 @@
+---
+name: ukit-small-task-maintainer
+description: "Internal UKit maintenance subagent for low-risk, reversible UKit decisions. Use proactively when UKit needs to decide or perform safe cleanup such as pruning docs/TASKS.md, classifying queued work, choosing whether compact/summarization is appropriate, summarizing local docs/status, or maintaining small UKit runtime queues. Do not use for product implementation, security, release/publish, data-loss, architecture, or risky/shared code changes."
+model: inherit
+color: cyan
+tools: ["Read", "Grep", "Glob", "Edit", "Write"]
+---
+
+You are UKit's internal small-task maintainer. You run as a sidecar/parallel/non-blocking lane for safe, reversible UKit orchestration chores so the end user can stay focused on product work and only remember `ukit install`. You must follow `docs/UKIT_CODEV_PRINCIPLES.md`: hide complexity, preserve output quality, and never trade correctness for speed or token savings.
+
+## Model Policy
+
+- Use the model selected by `UKIT_SMALL_TASK_MODEL` when the host supports model selection for this subagent.
+- Default intended model: `unic-lite`.
+- If the host cannot bind a model from env directly, still follow this role and report that the configured model is a hint.
+- This lane must run separately from the user's main task model. It must never replace, pause, or slow down the main task.
+
+## Use For
+
+- Cleaning and deduplicating `docs/TASKS.md`.
+- Pruning stale local AI queue/status noise.
+- Classifying queued items by readiness/risk.
+- Deciding whether compacting or summarizing context/docs is appropriate.
+- Summarizing `docs/STATUS.md`, `docs/TASKS.md`, `docs/WORKLOG.md`, or memory snippets into compact handoff notes.
+- Deciding fast vs slow lane, safe vs risky lane, whether a skill should be activated, and whether the current prompt has enough steps planned.
+- Choosing compact-now vs compact-later and summarize-vs-keep-detail for UKit context hygiene.
+- Keeping agent context compact without removing existing lanes: Claude PreCompact/reinject stays active, OpenCode native auto/prune compaction stays active, and Codex Desktop soft handoffs use `UKIT_CODEX_COMPACT_TARGET` (default 150 lines; preferred 120-150; hard max 170) while preserving critical state.
+- Small, reversible UKit runtime maintenance decisions.
+
+## Never Use For
+
+- Security/auth/permission/secrets work.
+- Release, tag, publish, package ownership, or irreversible registry decisions.
+- Data deletion beyond clearly safe local queue/doc cleanup.
+- Architecture decisions, roadmap trade-offs, or deep product reasoning.
+- Product code changes or risky/shared implementation edits.
+- Any action where the consequence is not easy to inspect and undo.
+
+## Workflow
+
+1. Read the smallest relevant local state file first.
+2. Identify whether the requested action is safe and reversible.
+3. If risky, hand back to the main model with a concise reason; do not ask the end user and do not block the main AI flow.
+4. If the main task can continue without this sidecar result, return a compact recommendation and let the main task proceed immediately.
+5. If safe, make the smallest cleanup/summary/classification/routing decision.
+6. Follow the CoDev priority order: output quality first, then safety, then speed, then token discipline. Spend tokens/steps when they protect correctness.
+7. Use small step budgets: trivial = 1 step, simple = up to 2 steps, non-trivial = up to 4 planned steps before the main model reassesses.
+8. For long sessions, preserve existing Claude/OpenCode auto-compact behavior; for Codex Desktop, target a compact handoff of about 120-150 lines, never above 170 lines for this lane, not a full transcript replay.
+9. Preserve user-owned content; do not delete unclear tasks.
+10. Report exactly what changed or what decision was made.
+
+## Output Format
+
+```
+STATUS: DONE | SKIPPED | HAND_BACK
+MODEL_HINT: UKIT_SMALL_TASK_MODEL=<value-or-default>
+SUMMARY: [one sentence]
+CHANGES:
+  - [file/area]: [what changed]
+HAND_BACK_REASON: [only if HAND_BACK]
+NEXT: [small follow-up or "none"]
+```
+
+## Guardrails
+
+- Keep UKit invisible: never ask end users to remember this agent, model name, or config path.
+- Never block AI decision-making; escalate to the main model instead of waiting for user input when risk exceeds this lane.
+- Never block, replace, or slow the user's main task; this lane is a sidecar hint/maintenance worker only.
+- Prefer no-op over destructive cleanup when uncertain.
+- Do not invent product requirements.
+- Never choose cheap/fast if it risks wrong context, weak verification, over-compaction, or lower answer quality.
+- Do not widen reads beyond local UKit state unless the main model explicitly scoped the handoff.

package/templates/.claude/skills/docs-quality/SKILL.md

@@ -61,7 +61,7 @@ Docs should **not** become:
 
 - update README / docs after code changes
 - fix source-vs-doc drift
-- improve `docs/PROJECT.md`, `docs/MEMORY.md`, `docs/WORKLOG.md`, `docs/CODE_MAP.md`
+- improve `docs/PROJECT.md`, `docs/MEMORY.md`, `docs/STATUS.md`, `docs/TASKS.md`, `docs/WORKLOG.md`, `docs/CODE_MAP.md`
 - prepare durable handoff notes
 - tighten or remove stale setup instructions
 - document newly discovered module boundaries, dangerous areas, or bug patterns
@@ -97,6 +97,28 @@ Use for durable knowledge:
 
 Prefer short entries that future sessions can scan in seconds.
 
+#### `docs/STATUS.md`
+Use for compact current state:
+- current focus / active work
+- live debug threads, blockers, and verification status
+- next candidates for open-ended continuation
+
+Do **not** treat it as source truth or duplicate full session history here.
+
+#### `docs/TASKS.md`
+Use for:
+- local AI task queue items the human or an AI may hand to another AI/agent later
+- `Inbox` ideas that still need acceptance/verification details
+- `Ready for AI` tasks that are specific enough to implement without scanning the whole repo
+
+Default cleanup when reading/updating it:
+- remove exact duplicates
+- prune `Done Recently` to 10 compact lines
+- move stale/vague/blocked tasks to `Deferred / Needs Human Review`
+- only delete unfinished human-authored tasks when explicitly asked and clearly obsolete/duplicated
+
+Do **not** treat it as a roadmap, project history, or source truth. It is local working state.
+
 #### `docs/WORKLOG.md`
 Use for session-level execution history:
 - what changed

package/templates/.claude/skills/next-step/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: next-step
+description: Use when the user asks what to do next, asks for project status, says continue/làm tiếp without a concrete target, or needs a lightweight session-start orientation from docs/STATUS.md and optional docs/TASKS.md. Do not use as the primary skill for concrete debug, implementation, review, or docs tasks.
+---
+
+# Next Step
+
+## Purpose
+
+Suggest the next useful project action without scanning the whole repository.
+
+This skill is for open-ended continuity prompts such as:
+- "what next?", "project status?", "where are we?"
+- "continue", "continue from last session"
+- "làm gì tiếp?", "làm tiếp", "project đang ở đâu?"
+
+It is **not** a replacement for concrete workflows. If the user names a bug, feature, file, test, PR, or review target, keep the concrete workflow primary and use this skill only as background if useful.
+
+## Hard Guardrails
+
+- End users should not need to know this skill name.
+- Do not ask users to run a `next-step` command. The human workflow remains `ukit install` + natural language.
+- `docs/STATUS.md` is orientation, not truth. Source code, tests, and the UKit index win.
+- `docs/TASKS.md` is a local AI task queue, not a roadmap and not source truth.
+- Concrete task beats open-ended wording. Example: "I'm fixing login bug but unsure next step" is a debug approach question, not a global roadmap request.
+- Do not scan the whole repo unless `docs/STATUS.md` is missing/stale and the user still wants project-level direction.
+- When reading `docs/TASKS.md`, perform only safe cleanup by default: remove exact duplicates, prune `Done Recently` to 10 lines, and move stale/vague items to `Deferred / Needs Human Review`; do not delete unfinished human-authored tasks unless explicitly asked and clearly obsolete/duplicated.
+
+## Freshness Check
+
+Before relying on status content, check both:
+1. filesystem modified time for `docs/STATUS.md` (fallback: root `STATUS.md` if present)
+2. the `Last meaningful update` field inside the file
+
+Use this cue in your response:
+
+- 🟢 fresh: modified within 24h
+- 🟡 possibly stale: 24-72h old
+- 🔴 stale: older than 72h
+- ⚪ missing: no status file yet
+
+If stale or missing, downgrade confidence and verify with the smallest current tree/index/context signal before recommending work.
+
+## Input Order
+
+Read only what is needed:
+1. `docs/STATUS.md` (or existing root `STATUS.md` fallback)
+2. `docs/TASKS.md` only for queued-task prompts, “continue” with no active status, or when status points at queued work
+3. `docs/CODE_MAP.md` only when navigation is needed
+4. `docs/MEMORY.md` only when constraints/decisions affect the suggestion
+5. routed index/tree summary only if status/tasks are stale, missing, or contradicted
+
+## Output Shape
+
+Keep output compact:
+
+```md
+STATUS freshness: 🟡 possibly stale
+- last modified: YYYY-MM-DD HH:mm
+- confidence: medium-low
+
+Suggested next steps:
+1. Candidate — why now — likely files — verification — risk
+2. Candidate — why now — likely files — verification — risk
+
+Queued tasks (if `docs/TASKS.md` was used):
+- Ready: task title — acceptance — verification
+- Deferred/blocked: compact note only if relevant
+
+Recommended: ...
+Why: ...
+First check: ...
+```
+
+## Intent Handling
+
+- `open-ended-status`: read status and suggest 1-3 candidates.
+- `queued-task-selection`: read `docs/TASKS.md`, prefer `Ready for AI`, and suggest the best next task with acceptance/verification.
+- `continue-existing-work`: prefer Active Work / Current Debug Threads, then `Ready for AI`, then Next Candidates.
+- `scoped-advice`: do not produce a global roadmap; hand off to the concrete skill and suggest the immediate approach only.
+- `debug-specific`, `implement-specific`, `review-specific`: do not use this skill as primary.
+
+## Missing or Stale Status
+
+If missing, suggest creating/updating `docs/STATUS.md` after the current task, but do not block the user.
+If stale, say so visibly and treat old Next Candidates as hypotheses, not fact.

package/templates/.claude/skills/update-status/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: update-status
+description: Use near the end of a meaningful session or explicit handoff/status request to update docs/STATUS.md with compact current state, verification, blockers, and next candidates. Skip trivial/no-state-change tasks.
+---
+
+# Update Status
+
+## Purpose
+
+Keep `docs/STATUS.md` useful as a compact living state document for future AI sessions.
+
+This skill should run when:
+- the user explicitly asks to update status / handoff / wrap up
+- meaningful source/docs/tests/package state changed
+- a task is paused, blocked, completed, or has a new verified next action
+- a bug root cause, verification result, or durable blocker was discovered
+
+Do **not** run for trivial typo-only edits, pure Q&A, or exploration with no durable finding.
+
+## Hard Guardrails
+
+- End users should not need to know this skill name.
+- Do not ask users to run a `update-status` command. The human workflow remains `ukit install` + natural language.
+- Keep `docs/STATUS.md` compact. It is not `docs/WORKLOG.md` and not a raw session transcript.
+- Keep `docs/TASKS.md` compact when the completed/active work is related to queued tasks; this queue is local working state and should stay gitignored.
+- Source code and tests are truth. If status/tasks conflict with source, update the docs to match source or mark uncertainty.
+- Do not invent verification. Record only commands actually run and their outcome.
+- Preserve user edits and rewrite the smallest relevant section.
+
+## Update Decision
+
+Before editing, ask internally:
+
+1. Did project state actually change?
+2. Is any work still active/blocked?
+3. Was a root cause, decision, blocker, or next action confirmed?
+4. What verification ran?
+5. Will future sessions be faster if this is recorded?
+6. Did any `docs/TASKS.md` queued task become done, duplicate, stale, or blocked?
+
+If all answers are no, skip the update and mention that no status change was needed.
+
+## Freshness Fields
+
+When updating meaningful state, update the header:
+
+```md
+## Freshness
+
+- Last meaningful update: YYYY-MM-DD HH:mm
+- Updated by: Claude / Codex / OpenCode / human
+- Status confidence: high / medium / low
+- Stale after: 72h
+```
+
+Confidence guide:
+- `high`: implementation/fix verified by targeted tests or stronger
+- `medium`: state changed but verification was partial or docs-only
+- `low`: investigation/hypothesis only, blocked, or stale recovery
+
+## Section Rules
+
+- `Snapshot`: only current focus, health, branch/state, release/version.
+- `Active Work`: only live unfinished work.
+- `Current Debug Threads`: compact bug state; detailed context should link to future `docs/context/<slug>.md` files when available.
+- `Decisions Pending`: unresolved choices only.
+- `Next Candidates`: max 3-5 actionable candidates.
+- `Recently Completed`: max 10 compact lines; detailed session history belongs in `docs/WORKLOG.md`.
+
+## What to Record
+
+Prefer concrete bullets:
+
+- files changed or likely involved
+- verification commands and pass/fail/blocked result
+- current blocker
+- next action that can be started immediately
+- uncertainty labels (`unknown`, `unverified`, `suspected`) when needed
+
+Avoid:
+
+- raw command output
+- every file opened/read
+- speculative TODO spam
+- duplicate history already better suited for WORKLOG
+- global roadmap changes caused by a concrete one-file task
+
+## Future Context Note
+
+Do not create task-scoped `CONTEXT.md` by default unless the project already has that convention. If detailed bug/feature context is needed, note it as a v1.2 candidate or link to an existing `docs/context/<slug>.md` file.
+
+## TASKS.md Cleanup
+
+When the session touched queued work or the user asks to clean/dọn tasks:
+
+- Read `docs/TASKS.md` if it exists; do not create noisy task entries just to summarize the session.
+- Auto-remove exact duplicate tasks.
+- Auto-prune `Done Recently` to max 10 compact lines.
+- Remove a task from active sections only after all are true: it is done, verification is recorded, and completion is summarized in `docs/WORKLOG.md` or `Done Recently`.
+- Move stale, vague, or blocked tasks to `Deferred / Needs Human Review` instead of deleting uncertain human intent.
+- Do not delete non-completed human-authored tasks unless the user explicitly asked for cleanup and the task is clearly obsolete or duplicated.
+- Report the cleanup in one compact line: removed duplicates, moved deferred, pruned done, or no safe cleanup.

package/templates/.claude/ukit/.env.example

@@ -0,0 +1,17 @@
+# UKit optional local runtime overrides.
+# Copy to .claude/ukit/.env only if you need machine-local overrides.
+# This is internal orchestration config; normal teammates still only need `ukit install`.
+
+# Lightweight model for the internal UKit small-task maintainer subagent.
+# Used for safe UKit decisions such as task cleanup, compact decisions,
+# doc summarization, classification, auto-triage, and queue maintenance.
+# It follows UKit CoDev principles: quality > speed > token savings.
+# Risky/shared/security/release/data-loss/architecture work must keep the main model.
+UKIT_SMALL_TASK_MODEL=unic-lite
+
+# Codex Desktop soft auto-compact handoff budget.
+# Target is compact handoff length (lines), not full app context tokens.
+# 120-150 is preferred; 170 lines is the hard max for this lane.
+UKIT_CODEX_AUTO_COMPACT=true
+UKIT_CODEX_CONTEXT_BUDGET=60000
+UKIT_CODEX_COMPACT_TARGET=150

package/templates/.claude/ukit/index/route-catalog.mjs

@@ -223,8 +223,30 @@ export const ROUTE_CATALOG = [
     path: '.claude/skills/docs-quality/SKILL.md',
     order: 12,
     signals: [
-      { type: 'prompt', regex: /\b(docs|documentation|readme|changelog|handoff|worklog|memory|code map)\b/i, score: 4 },
-      { type: 'file', regex: /\bdocs\/|readme\.md$|project\.md$|memory\.md$|worklog\.md$|code_map\.md$/i, score: 4 },
+      { type: 'prompt', regex: /\b(docs|documentation|readme|changelog|handoff|worklog|memory|code map|status\.md|tasks\.md|task queue|clean tasks|cleanup tasks|dọn tasks|dọn task)\b/i, score: 4 },
+      { type: 'file', regex: /\bdocs\/|readme\.md$|project\.md$|memory\.md$|status\.md$|tasks\.md$|worklog\.md$|code_map\.md$/i, score: 4 },
+    ],
+  },
+  {
+    id: 'next-step',
+    path: '.claude/skills/next-step/SKILL.md',
+    order: 12.1,
+    contextMode: 'standalone',
+    signals: [
+      { type: 'prompt', regex: /\b(what(?:'s| is)? next|next steps?|project status|current status|where are we|continue(?: from)?(?: last session)?|roadmap|status\.md|task queue|tasks\.md|next queued task|pick next task|work from tasks)\b/i, score: 7 },
+      { type: 'prompt', regex: /\b(làm gì tiếp|bước tiếp theo|tiếp theo làm gì|làm tiếp|đang ở đâu|trạng thái project|tình trạng project|task tiếp theo|việc tiếp theo trong tasks)\b/i, score: 7 },
+    ],
+  },
+  {
+    id: 'update-status',
+    path: '.claude/skills/update-status/SKILL.md',
+    order: 12.2,
+    contextMode: 'standalone',
+    signals: [
+      { type: 'prompt', regex: /\b(update|refresh|write|sync|record|capture|summari[sz]e).{0,48}\b(status\.md|project status|current state|next candidates?|session state)\b/i, score: 9 },
+      { type: 'prompt', regex: /\b(status\.md|project status).{0,48}\b(update|refresh|write|sync|record|capture|summari[sz]e)\b/i, score: 9 },
+      { type: 'prompt', regex: /\b(wrap up|handoff|end(?:ing)? this session|session summary|before final)\b/i, score: 7 },
+      { type: 'prompt', regex: /\b(cập nhật|ghi lại|tổng kết|chốt session|bàn giao).{0,48}\b(status|trạng thái|việc tiếp theo)\b/i, score: 9 },
     ],
   },
   {