@ngockhoale/ukit 1.1.8 → 1.2.1

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to UKit are documented here.
 
 ## Unreleased
 
+## 1.2.1 - 2026-05-05
+
+### Local AI Task Queue
+
+- Added gitignored `docs/TASKS.md` as a local AI task queue for deferred work that one AI can write and another AI/agent can implement later.
+- Installed `docs/TASKS.md` with skip merge semantics so end-user task notes are never overwritten or uninstall-owned.
+- Added safe default cleanup rules: remove exact duplicates, prune `Done Recently` to 10 compact lines, move stale/vague work to deferred review, and never delete unfinished human-authored tasks unless explicitly asked and clearly obsolete/duplicated.
+- Updated `next-step`, `update-status`, and `docs-quality` guidance plus route signals so queued-task selection goes to `next-step` while task cleanup/editing goes to `docs-quality`.
+- Added `docs/STATUS.md` and `docs/TASKS.md` to generated gitignore handling so living local AI state does not pollute project commits.
+- Added the internal `ukit-small-task-maintainer` subagent, powered by optional `UKIT_SMALL_TASK_MODEL=unic-lite`, for safe UKit decisions such as task cleanup, compact decisions, doc summarization, classification, auto-triage, queue maintenance, and small reversible cleanup while keeping risky/security/release work on the main model.
+
 ## 1.1.8 - 2026-05-05
 
 ### Living Project Status

package/README.md

@@ -33,6 +33,7 @@ ukit install
    - `docs/PROJECT.md`
    - `docs/MEMORY.md`
    - `docs/STATUS.md`
+   - `docs/TASKS.md`
    - `docs/WORKLOG.md`
 5. Open your AI tool and work in natural language.
 
@@ -65,13 +66,13 @@ If maintainers roll out a newer CLI build, the in-project workflow still stays t
 **Project support files**
 - `.claude/ukit/.ukit/` — installer manifests, metadata, backups
 - `.ukit/` — hidden shared runtime storage for config, cache, and cross-agent memory
-- `docs/` — PROJECT / MEMORY / STATUS / WORKLOG baseline
+- `docs/` — PROJECT / MEMORY / STATUS / TASKS / WORKLOG baseline
 
-## UKit v1.1.8 Runtime
+## UKit v1.2.1 Runtime
 
 UKit now installs a hidden shared local runtime at `.ukit/` for production-oriented state that should survive across agent sessions:
 
-- `.ukit/storage/config.json` — runtime defaults for compact/router/memory/validation
+- `.ukit/storage/config.json` — runtime defaults for compact/router/memory/validation/subagent hints
 - `.ukit/storage/cache/` — reusable prompt-cache, compact history, compact-pressure state, and output summaries
 - `.ukit/storage/memory/` — cross-agent local memory
 
@@ -84,17 +85,18 @@ When long sessions approach the compact threshold, UKit now uses a conservative
 - compact only safe-zone history/noise
 - preserve active task, rules, decisions, and current code focus
 
-UKit v1.1.8 keeps the same shared runtime contract while adding living project status routing for continuity-safe AI sessions:
+UKit v1.2.1 keeps the same shared runtime contract while adding a local AI task queue alongside living project status routing:
 
 - install globally with `npm install -g @ngockhoale/ukit`
 - keep using the exact same human workflow inside projects: `ukit install`
 - preserve the same `ukit` binary, hooks, and install-first orchestration while standardizing the runtime root as hidden `.ukit/`
 - install `docs/STATUS.md` as a compact living state file for active work, debug threads, blockers, verification, and next candidates
+- install gitignored `docs/TASKS.md` as a local AI task queue for deferred/ready work, with safe AI cleanup rules that remove duplicates and prune completed history without deleting unfinished human intent
 - auto-route open-ended “what next?” / “continue” prompts to the `next-step` skill with a visible freshness cue when status may be stale
 - auto-route explicit handoff/wrap-up requests to the `update-status` skill while skipping trivial/no-state-change tasks
 - keep concrete debug/implementation/review prompts primary, so project status never replaces source/index-first task work
 
-UKit v1.1.8 also keeps the fast path improvements from the recent runtime releases:
+UKit v1.2.1 also keeps the fast path improvements from the recent runtime releases:
 
 - Vietnamese prompts now normalize more effectively for English-heavy code symbols and paths
 - localized simple direct-target lanes skip extra previous-context / recent-output work when it would not change the next action
@@ -129,6 +131,8 @@ UKit is built so the team can stop memorizing UKit subcommands and focus on prod
 - let Claude Code / Codex / OpenCode auto-detect and use the right project-local skill from the prompt and the files/tools involved
 - let the AI prefer targeted verification first, then widen only when shared/risky scope justifies it
 - let the AI selectively auto-delegate internal subagents only when that actually reduces context/noise or unlocks parallel progress; small localized work should stay direct
+- keep long sessions compact across agents: Claude keeps PreCompact/reinject, OpenCode keeps native auto/prune compaction, and Codex Desktop uses internal `UKIT_CODEX_COMPACT_TARGET` soft handoffs (default 150 lines; 120-150 preferred, hard max 170), without asking end users to manage context manually
+- let UKit internally use the `ukit-small-task-maintainer` subagent with `UKIT_SMALL_TASK_MODEL=unic-lite` for safe task cleanup, fast-vs-slow/safe-vs-risky lane hints, skill-routing/step-budget hints, agent context-budget decisions, compact decisions, doc summarization, classification, and queue maintenance while risky/security/release/quality-risk work stays on the main model
 - rerun `ukit install` when you need to refresh the workspace
 
 End users should **not** need to know or memorize skill names.

package/manifests/platform.full.yaml

@@ -77,6 +77,18 @@ items:
     packs:
       - core
 
+  - id: ukit-env-example
+    type: config
+    sourceTemplate: .claude/ukit/.env.example
+    targetPath: .claude/ukit/.env.example
+    requires:
+      - runtime-config
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: root-claude-md
     type: config
     sourceTemplate: CLAUDE.md
@@ -159,6 +171,19 @@ items:
     packs:
       - core
 
+  - id: docs-tasks
+    type: config
+    sourceTemplate: docs/TASKS.md
+    targetPath: docs/TASKS.md
+    requires:
+      - docs-status
+    mergeStrategy: skip
+    variables:
+      - project.name
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: docs-bugfix
     type: config
     sourceTemplate: docs/BUGFIX.md
@@ -483,6 +508,7 @@ items:
     requires:
       - docs-quality-skill
       - docs-status
+      - docs-tasks
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true
@@ -496,6 +522,7 @@ items:
     requires:
       - docs-quality-skill
       - docs-status
+      - docs-tasks
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true
@@ -792,6 +819,19 @@ items:
     packs:
       - core
 
+  - id: agent-ukit-small-task-maintainer
+    type: agent
+    sourceTemplate: .claude/agents/ukit-small-task-maintainer.md
+    targetPath: .claude/agents/ukit-small-task-maintainer.md
+    requires:
+      - ukit-env-example
+    mergeStrategy: overwrite_with_backup
+    variables:
+      - ukit.version
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: provider-compat-config
     type: config
     sourceTemplate: .claude/config/providers.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "1.1.8",
+  "version": "1.2.1",
   "description": "Install/update an index-first AI workspace for Claude Code, Antigravity, OpenAI Codex, and OpenCode.",
   "license": "MIT",
   "type": "module",

package/src/cli/commands/doctor.js

@@ -63,6 +63,7 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [] }) {
     docsProjectExists: await pathExists(path.join(projectRoot, 'docs', 'PROJECT.md')),
     docsMemoryExists: await pathExists(path.join(projectRoot, 'docs', 'MEMORY.md')),
     docsStatusExists: await pathExists(path.join(projectRoot, 'docs', 'STATUS.md')),
+    docsTasksExists: await pathExists(path.join(projectRoot, 'docs', 'TASKS.md')),
     docsWorklogExists: await pathExists(path.join(projectRoot, 'docs', 'WORKLOG.md')),
     allProvidersConfigured: providers.allSupported,
     ...(codexAdapterTracked
@@ -105,6 +106,7 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [] }) {
   console.log(`[UKit]   ${ok(checks.docsProjectExists)}  docs/PROJECT.md`);
   console.log(`[UKit]   ${ok(checks.docsMemoryExists)}  docs/MEMORY.md`);
   console.log(`[UKit]   ${ok(checks.docsStatusExists)}  docs/STATUS.md`);
+  console.log(`[UKit]   ${ok(checks.docsTasksExists)}  docs/TASKS.md`);
   console.log(`[UKit]   ${ok(checks.docsWorklogExists)}  docs/WORKLOG.md`);
   if (codexAdapterTracked) {
     console.log(`[UKit]   ${ok(checks.codexReadmeExists)}  .codex/README.md`);

package/src/cli/commands/install.js

@@ -241,13 +241,14 @@ export async function runInstall({ packageRoot, projectRoot, packageVersion, arg
     .join(', ');
   console.log(`[UKit] Providers: ${providerStatus}, all=${result.providerContext.allSupported}`);
 
-  const docsPaths = [
-    path.join(projectRoot, 'docs', 'PROJECT.md'),
-    path.join(projectRoot, 'docs', 'MEMORY.md'),
-    path.join(projectRoot, 'docs', 'STATUS.md'),
-    path.join(projectRoot, 'docs', 'WORKLOG.md'),
+  const docsLabels = [
+    'docs/PROJECT.md',
+    'docs/MEMORY.md',
+    'docs/STATUS.md',
+    'docs/TASKS.md',
+    'docs/WORKLOG.md',
   ];
-  const docsLabels = ['docs/PROJECT.md', 'docs/MEMORY.md', 'docs/STATUS.md', 'docs/WORKLOG.md'];
+  const docsPaths = docsLabels.map((label) => path.join(projectRoot, ...label.split('/')));
   const missingDocs = [];
   for (let i = 0; i < docsPaths.length; i++) {
     if (!(await pathExists(docsPaths[i]))) {
@@ -258,7 +259,7 @@ export async function runInstall({ packageRoot, projectRoot, packageVersion, arg
   if (missingDocs.length > 0) {
     console.log(`[UKit] Missing docs — fill these in before first use: ${missingDocs.join(', ')}`);
   } else {
-    console.log('[UKit] Docs baseline ready: docs/PROJECT.md, docs/MEMORY.md, docs/STATUS.md, docs/WORKLOG.md');
+    console.log('[UKit] Docs baseline ready: docs/PROJECT.md, docs/MEMORY.md, docs/STATUS.md, docs/TASKS.md, docs/WORKLOG.md');
     console.log('[UKit] Fill them once with real project context for the best results.');
   }
 

package/src/cli/commands/uninstall.js

@@ -47,5 +47,5 @@ export async function runUninstall({ projectRoot, argv = [] }) {
   }
 
   console.log(`[UKit] Uninstall complete. Removed ${result.removed}/${result.attempted} managed paths.`);
-  console.log('[UKit] Note: docs/PROJECT.md, docs/MEMORY.md, docs/STATUS.md, docs/WORKLOG.md contain user content and were preserved. Delete manually if needed.');
+  console.log('[UKit] Note: docs/PROJECT.md, docs/MEMORY.md, docs/STATUS.md, docs/TASKS.md, docs/WORKLOG.md contain user content and were preserved. Delete manually if needed.');
 }

package/src/core/ensureGitignore.js

@@ -11,6 +11,8 @@ const UKIT_ENTRIES = [
   'opencode.json',
   'AGENTS.md',
   'CLAUDE.md',
+  'docs/STATUS.md',
+  'docs/TASKS.md',
   '.claude/ukit/.ukit/',
   '.claude/ukit/permission-usage.json',
   '.claude/ukit/permission-audit.log',

package/src/core/runtimeConfig.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs/promises';
+import path from 'node:path';
 import { buildRuntimePaths } from './runtimePaths.js';
 
 const VALID_AGENTS = new Set(['claude-code', 'codex', 'antigravity', 'opencode']);
@@ -38,17 +39,155 @@ function pushPositiveNumberError(errors, value, label) {
   }
 }
 
+function pushNonEmptyStringError(errors, value, label) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    errors.push(`${label} must be a non-empty string.`);
+  }
+}
+
+function parseRuntimeEnv(content = '') {
+  const result = {};
+  for (const rawLine of String(content || '').split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#') || !line.includes('=')) {
+      continue;
+    }
+    const index = line.indexOf('=');
+    const key = line.slice(0, index).trim();
+    let value = line.slice(index + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"'))
+      || (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    result[key] = value;
+  }
+  return result;
+}
+
+async function loadRuntimeEnv(projectRoot) {
+  const envPath = path.join(projectRoot, '.claude', 'ukit', '.env');
+  try {
+    return parseRuntimeEnv(await fs.readFile(envPath, 'utf8'));
+  } catch (error) {
+    if (error?.code !== 'ENOENT') {
+      throw error;
+    }
+    return {};
+  }
+}
+
+function parsePositiveIntegerEnv(value) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    return null;
+  }
+  const parsed = Number.parseInt(value.trim(), 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+
+function buildEnvOverrides(env = process.env) {
+  const overrides = {};
+  const smallTaskModel = env.UKIT_SMALL_TASK_MODEL;
+  if (typeof smallTaskModel === 'string' && smallTaskModel.trim() !== '') {
+    overrides.subagents = {
+      ...(overrides.subagents ?? {}),
+      smallTaskModel: smallTaskModel.trim(),
+    };
+  }
+
+  const rawCodexCompactTarget = parsePositiveIntegerEnv(env.UKIT_CODEX_COMPACT_TARGET);
+  const codexCompactTarget = rawCodexCompactTarget ? Math.min(rawCodexCompactTarget, 170) : null;
+  const codexContextBudget = parsePositiveIntegerEnv(env.UKIT_CODEX_CONTEXT_BUDGET);
+  const codexAutoCompact = typeof env.UKIT_CODEX_AUTO_COMPACT === 'string'
+    ? !['0', 'false', 'no', 'off'].includes(env.UKIT_CODEX_AUTO_COMPACT.trim().toLowerCase())
+    : null;
+
+  if (codexCompactTarget || codexContextBudget || codexAutoCompact !== null) {
+    overrides.compact = {
+      ...(overrides.compact ?? {}),
+      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,
+          },
+        },
+      },
+      codexContext: {
+        ...(overrides.compact?.codexContext ?? {}),
+        ...(codexCompactTarget ? { compactTarget: codexCompactTarget } : {}),
+        ...(codexContextBudget ? { budgetTokens: codexContextBudget } : {}),
+        ...(codexAutoCompact !== null ? { autoCompact: codexAutoCompact } : {}),
+      },
+    };
+  }
+
+  return overrides;
+}
+
 export function buildDefaultRuntimeConfig(overrides = {}) {
   const safeOverrides = isPlainObject(overrides) ? overrides : {};
 
   return mergeObjects({
-    version: '1.1.8',
+    version: '1.2.1',
     agent: 'claude-code',
     compact: {
       enabled: true,
       tokenThreshold: 100_000,
       contextRotDetection: true,
       askBeforeDrop: true,
+      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,
+          },
+        },
+      },
+      codexContext: {
+        enabled: true,
+        autoCompact: true,
+        budgetTokens: 60_000,
+        compactTarget: 150,
+        compactTargetUnit: 'lines',
+        compactTargetRecommendedRange: [120, 170],
+        compactTargetMax: 170,
+        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',
+        ],
+      },
     },
     tokenPipeline: {
       inputCompression: true,
@@ -77,6 +216,53 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       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,
+        executionMode: 'sidecar-parallel',
+        mustNotBlockMainTask: true,
+        maxSidecarWaitMs: 0,
+        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',
+          'codex-context-budget',
+          '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' },
+        },
+      },
+    },
   }, safeOverrides);
 }
 
@@ -102,6 +288,40 @@ export function validateRuntimeConfig(config) {
     pushPositiveNumberError(errors, config.compact.tokenThreshold, 'compact.tokenThreshold');
     pushBooleanError(errors, config.compact.contextRotDetection, 'compact.contextRotDetection');
     pushBooleanError(errors, config.compact.askBeforeDrop, 'compact.askBeforeDrop');
+    if (!isPlainObject(config.compact.agentContext)) {
+      errors.push('compact.agentContext must be an object.');
+    } else {
+      pushBooleanError(errors, config.compact.agentContext.enabled, 'compact.agentContext.enabled');
+      pushNonEmptyStringError(errors, config.compact.agentContext.decisionModelEnv, 'compact.agentContext.decisionModelEnv');
+      pushNonEmptyStringError(errors, config.compact.agentContext.decisionAgent, 'compact.agentContext.decisionAgent');
+      pushNonEmptyStringError(errors, config.compact.agentContext.executionMode, 'compact.agentContext.executionMode');
+      pushBooleanError(errors, config.compact.agentContext.mustNotBlockMainTask, 'compact.agentContext.mustNotBlockMainTask');
+      if (!isPlainObject(config.compact.agentContext.targets)) {
+        errors.push('compact.agentContext.targets must be an object.');
+      }
+    }
+    if (!isPlainObject(config.compact.codexContext)) {
+      errors.push('compact.codexContext must be an object.');
+    } else {
+      pushBooleanError(errors, config.compact.codexContext.enabled, 'compact.codexContext.enabled');
+      pushBooleanError(errors, config.compact.codexContext.autoCompact, 'compact.codexContext.autoCompact');
+      pushPositiveNumberError(errors, config.compact.codexContext.budgetTokens, 'compact.codexContext.budgetTokens');
+      pushPositiveNumberError(errors, config.compact.codexContext.compactTarget, 'compact.codexContext.compactTarget');
+      pushNonEmptyStringError(errors, config.compact.codexContext.compactTargetUnit, 'compact.codexContext.compactTargetUnit');
+      if (!Array.isArray(config.compact.codexContext.compactTargetRecommendedRange)) {
+        errors.push('compact.codexContext.compactTargetRecommendedRange must be an array.');
+      }
+      pushPositiveNumberError(errors, config.compact.codexContext.compactTargetMax, 'compact.codexContext.compactTargetMax');
+      if (Number(config.compact.codexContext.compactTarget) > Number(config.compact.codexContext.compactTargetMax)) {
+        errors.push('compact.codexContext.compactTarget must be <= compact.codexContext.compactTargetMax.');
+      }
+      pushNonEmptyStringError(errors, config.compact.codexContext.decisionModelEnv, 'compact.codexContext.decisionModelEnv');
+      pushNonEmptyStringError(errors, config.compact.codexContext.decisionAgent, 'compact.codexContext.decisionAgent');
+      pushNonEmptyStringError(errors, config.compact.codexContext.mode, 'compact.codexContext.mode');
+      if (!Array.isArray(config.compact.codexContext.preserve)) {
+        errors.push('compact.codexContext.preserve must be an array.');
+      }
+    }
   }
 
   if (!isPlainObject(config.tokenPipeline)) {
@@ -147,6 +367,23 @@ export function validateRuntimeConfig(config) {
     pushPositiveNumberError(errors, config.validation.confidenceThreshold, 'validation.confidenceThreshold');
   }
 
+  if (!isPlainObject(config.subagents)) {
+    errors.push('subagents must be an object.');
+  } else {
+    pushBooleanError(errors, config.subagents.enabled, 'subagents.enabled');
+    pushNonEmptyStringError(errors, config.subagents.smallTaskModel, 'subagents.smallTaskModel');
+    pushNonEmptyStringError(errors, config.subagents.smallTaskAgent, 'subagents.smallTaskAgent');
+    if (!Array.isArray(config.subagents.smallTaskUseCases)) {
+      errors.push('subagents.smallTaskUseCases must be an array.');
+    }
+    if (!Array.isArray(config.subagents.keepMainModelFor)) {
+      errors.push('subagents.keepMainModelFor must be an array.');
+    }
+    if (!isPlainObject(config.subagents.decisionPolicy)) {
+      errors.push('subagents.decisionPolicy must be an object.');
+    }
+  }
+
   return {
     valid: errors.length === 0,
     errors,
@@ -170,16 +407,31 @@ export async function inspectRuntimeConfig(projectRoot) {
     }
   }
 
-  const config = buildDefaultRuntimeConfig(rawConfig);
+  let runtimeEnv = {};
+  let envError = null;
+  try {
+    runtimeEnv = await loadRuntimeEnv(projectRoot);
+  } catch (error) {
+    envError = error?.message ?? String(error);
+  }
+
+  const config = buildDefaultRuntimeConfig(
+    mergeObjects(rawConfig ?? {}, buildEnvOverrides({ ...runtimeEnv, ...process.env })),
+  );
   const validation = validateRuntimeConfig(config);
-  const errors = parseError ? [`config.json parse error: ${parseError}`, ...validation.errors] : validation.errors;
+  const errors = [
+    ...(parseError ? [`config.json parse error: ${parseError}`] : []),
+    ...(envError ? [`runtime .env error: ${envError}`] : []),
+    ...validation.errors,
+  ];
 
   return {
     exists,
     rawConfig,
+    runtimeEnv,
     config,
     parseError,
-    valid: exists && !parseError && validation.valid,
+    valid: exists && !parseError && !envError && validation.valid,
     errors,
   };
 }

package/src/core/uninstall.js

@@ -200,7 +200,7 @@ export async function uninstallUkit({ projectRoot, dryRun = false }) {
     }
   } else {
     // Old format (no files list): fall back to hardcoded managed paths.
-    // NOTE: docs/PROJECT.md, MEMORY.md, STATUS.md, WORKLOG.md are intentionally excluded.
+    // NOTE: docs/PROJECT.md, MEMORY.md, STATUS.md, TASKS.md, WORKLOG.md are intentionally excluded.
     // These are user-created content (mergeStrategy: skip) — deleting them
     // would cause data loss. Users must remove them manually if desired.
     const fallback = buildFallbackPaths(projectRoot);

package/src/index/routeCatalog.js

@@ -223,8 +223,8 @@ 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|status\.md)\b/i, score: 4 },
-      { type: 'file', regex: /\bdocs\/|readme\.md$|project\.md$|memory\.md$|status\.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 },
     ],
   },
   {
@@ -233,8 +233,8 @@ export const ROUTE_CATALOG = [
     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)\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)\b/i, score: 7 },
+      { 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 },
     ],
   },
   {

package/src/index/taskRouting.js

@@ -175,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(' | ');
 
@@ -311,10 +312,11 @@ function getSignalTexts(signalType, routeSignals = {}) {
 function deriveIntentMode({ promptText = '', commandText = '', targetFile = null } = {}) {
   const lower = buildRouteSignalText(promptText, commandText);
   const raw = `${promptText ?? ''}\n${commandText ?? ''}`.toLowerCase();
-  const docsSpecific = hasDocsSpecificTaskSignal(lower, raw, targetFile);
+  const taskQueueNext = hasTaskQueueNextSignal(lower, raw);
+  const docsSpecific = hasDocsSpecificTaskSignal(lower, raw, targetFile, { taskQueueNext });
   const statusUpdate = hasStatusUpdateSignal(lower, raw);
-  const openEndedStatus = hasOpenEndedStatusSignal(lower, raw);
-  const concreteTask = hasConcreteTaskSignal(lower, raw, targetFile);
+  const openEndedStatus = hasOpenEndedStatusSignal(lower, raw) || taskQueueNext;
+  const concreteTask = hasConcreteTaskSignal(lower, raw, targetFile, { taskQueueNext });
 
   if (docsSpecific) {
     return 'docs-specific';
@@ -356,13 +358,18 @@ function hasStatusUpdateSignal(lower, 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)\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)\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)\b/.test(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 hasConcreteTaskSignal(lower, raw, targetFile) {
-  if (targetFile && !isStatusFileTarget(targetFile)) {
+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;
   }
 
@@ -370,8 +377,13 @@ function hasConcreteTaskSignal(lower, raw, targetFile) {
     || /\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) {
+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;
   }
 
@@ -413,6 +425,10 @@ 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);
@@ -589,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;
   }