@ngockhoale/ukit 1.5.2 → 1.5.4

package/CHANGELOG.md

@@ -2,23 +2,48 @@
 
 All notable changes to UKit are documented here.
 
+## 1.5.4 - 2026-05-28
+
+### Fixed
+
+- Fixed stale `docs/AI_HANDOFF.md` references in next-step skill, INSTALL.md, UKIT_USAGE_GUIDE.md, PROJECT.md (template + local).
+- Fixed mirror `route-task.mjs` not showing `handoff=` in summary — wrong intent order (docsSpecific before handoff) + missing handoffFile field + missing display segment.
+- Added `WORKLOG_ARCHIVE.md` to `.gitignore`.
+
+### Changed
+
+- Compacted `docs/MEMORY.md` from 118KB/298 lines to 7.8KB/78 lines. Old entries archived to `docs/MEMORY_ARCHIVE.md`.
+- Cleared handoff task queue after all cycle 002 tasks resolved.
+
+## 1.5.3 - 2026-05-28
+
+### Changed
+
+- Restructured `docs/AI_HANDOFF.md` into `docs/AI_HANDOFF/` folder: ACTIVE.md (snapshot), RULES.md (flow + token budget), PLAN.md (brainstorm), INDEX.md (task index), tasks/ (per-task files), archive/ (completed cycles, max 3).
+- Each task is now an isolated file in `tasks/TASK-xxx.md` — AI reads only the task it implements, not the entire backlog.
+- Added token budget rule: combined handoff reads must stay under 200 lines per request.
+- Added auto-compact rule: if any handoff file exceeds 80 lines, trigger `clear handoff`.
+- Updated template mirror `templates/docs/AI_HANDOFF/` to match new folder structure.
+- Updated `taskRouting.js` handoffFile target from `docs/AI_HANDOFF.md` to `docs/AI_HANDOFF/ACTIVE.md`.
+- Updated `install.js`, `doctor.js`, `uninstall.js` to check for `docs/AI_HANDOFF/ACTIVE.md`.
+
 ## 1.5.2 - 2026-05-28
 
 ### Added
 
 - Added first-class `ukit:handoff` prompt detection and routing for explicit handoff/brainstorm-to-task flows.
-- Added `intentMode: handoff` to route summaries so hooks and helpers can prioritize `docs/AI_HANDOFF.md` automatically.
-- Added a reusable generic `docs/AI_HANDOFF.md` handoff template for installed projects.
+- Added `intentMode: handoff` to route summaries so hooks and helpers can prioritize handoff file automatically.
+- Added a reusable generic handoff template for installed projects.
 
 ### Changed
 
-- Handoff prompts now route through `docs-quality` skill instead of generic `update-status`, making `docs/AI_HANDOFF.md` the primary coordination artifact.
-- Updated installed `next-step` skill guidance to read `docs/AI_HANDOFF.md` first for explicit handoff prompts.
+- Handoff prompts now route through `docs-quality` skill instead of generic `update-status`.
+- Updated installed `next-step` skill guidance to read handoff file first for explicit handoff prompts.
 - Updated `route-task` mirror and hook behavior in both source and installed artifact so `ukit install` users get consistent handoff routing.
 
 ### Fixed
 
-- Handoff authoring is now advisory (exit 0) in Safe Patch, so large `docs/AI_HANDOFF.md` batches no longer block the handoff workflow.
+- Handoff authoring is now advisory (exit 0) in Safe Patch, so large handoff batches no longer block the handoff workflow.
 - Hard runtime/shared-risk file broad rewrites still block by default unless `advisoryOnly=true` or `UKIT_SAFE_PATCH_ADVISORY=1` is set.
 
 ### Tests

package/README.md

@@ -32,7 +32,7 @@ ukit install
 4. Fill in the generated docs baseline:
    - `docs/PROJECT.md`
    - `docs/MEMORY.md`
-   - `docs/AI_HANDOFF.md`
+   - `docs/AI_HANDOFF/`
    - `docs/WORKLOG.md`
 5. Open your AI tool and work in natural language.
 
@@ -90,7 +90,7 @@ UKit v1.3.1 keeps the same shared runtime contract while adding Safe Patch Proto
 - 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/AI_HANDOFF.md` as the default cross-AI handoff file for plan → task breakdown → implementation continuity, with explicit sections so one AI can plan, another can refine tasks, and another can implement them reliably
+- install `docs/AI_HANDOFF/` as the cross-AI handoff folder with per-task isolation: ACTIVE.md (snapshot), INDEX.md (task index), tasks/ (one file per task) so each AI reads only the task it needs, with token budget rules in RULES.md
 - 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

package/manifests/platform.full.yaml

@@ -145,8 +145,8 @@ items:
 
   - id: docs-ai-handoff
     type: config
-    sourceTemplate: docs/AI_HANDOFF.md
-    targetPath: docs/AI_HANDOFF.md
+    sourceTemplate: docs/AI_HANDOFF
+    targetPath: docs/AI_HANDOFF
     requires:
       - docs-project
       - docs-memory

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "1.5.2",
+  "version": "1.5.4",
   "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

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import fs from 'node:fs/promises';
 import { pathExists, readJsonIfExists } from '../../core/fileOps.js';
 import { buildPathConfig } from '../../core/paths.js';
 import { buildRuntimePaths } from '../../core/runtimePaths.js';
@@ -45,6 +46,15 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [] }) {
     : [];
   const codexAdapterTracked = trackedPaths.some((entry) => entry.startsWith('.codex/'));
 
+  const WORKLOG_MAX_LINES = 600;
+  let worklogLineCount = 0;
+  try {
+    const content = await fs.readFile(path.join(projectRoot, 'docs', 'WORKLOG.md'), 'utf8');
+    worklogLineCount = content.split('\n').length;
+  } catch {
+    // file may not exist
+  }
+
   const checks = {
     manifestLoaded: Boolean(manifest?.name),
     templatesDirExists: await pathExists(pathConfig.templatesRoot),
@@ -62,8 +72,9 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [] }) {
     sessionMemoryDirExists: await pathExists(runtimePaths.sessionsDir),
     docsProjectExists: await pathExists(path.join(projectRoot, 'docs', 'PROJECT.md')),
     docsMemoryExists: await pathExists(path.join(projectRoot, 'docs', 'MEMORY.md')),
-    docsAiHandoffExists: await pathExists(path.join(projectRoot, 'docs', 'AI_HANDOFF.md')),
+    docsAiHandoffExists: await pathExists(path.join(projectRoot, 'docs', 'AI_HANDOFF', 'ACTIVE.md')),
     docsWorklogExists: await pathExists(path.join(projectRoot, 'docs', 'WORKLOG.md')),
+    docsWorklogUnderBudget: worklogLineCount <= WORKLOG_MAX_LINES,
     allProvidersConfigured: providers.allSupported,
     ...(codexAdapterTracked
       ? {
@@ -104,8 +115,9 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [] }) {
   console.log(`[UKit]   ${ok(checks.sessionMemoryDirExists)}  .ukit/storage/memory/sessions/`);
   console.log(`[UKit]   ${ok(checks.docsProjectExists)}  docs/PROJECT.md`);
   console.log(`[UKit]   ${ok(checks.docsMemoryExists)}  docs/MEMORY.md`);
-  console.log(`[UKit]   ${ok(checks.docsAiHandoffExists)}  docs/AI_HANDOFF.md`);
+  console.log(`[UKit]   ${ok(checks.docsAiHandoffExists)}  docs/AI_HANDOFF/`);
   console.log(`[UKit]   ${ok(checks.docsWorklogExists)}  docs/WORKLOG.md`);
+  console.log(`[UKit]   ${ok(checks.docsWorklogUnderBudget)}  docs/WORKLOG.md under budget (${worklogLineCount}/${WORKLOG_MAX_LINES} lines)`);
   if (codexAdapterTracked) {
     console.log(`[UKit]   ${ok(checks.codexReadmeExists)}  .codex/README.md`);
     console.log(`[UKit]   ${ok(checks.codexSettingsExists)}  .codex/settings.json`);

package/src/cli/commands/install.js

@@ -239,7 +239,7 @@ export async function runInstall({ packageRoot, projectRoot, packageVersion, arg
   const docsLabels = [
     'docs/PROJECT.md',
     'docs/MEMORY.md',
-    'docs/AI_HANDOFF.md',
+    'docs/AI_HANDOFF/ACTIVE.md',
     'docs/WORKLOG.md',
   ];
 
@@ -254,7 +254,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/AI_HANDOFF.md, docs/WORKLOG.md');
+    console.log('[UKit] Docs baseline ready: docs/PROJECT.md, docs/MEMORY.md, docs/AI_HANDOFF/, 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/AI_HANDOFF.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/AI_HANDOFF/, docs/WORKLOG.md contain user content and were preserved. Delete manually if needed.');
 }

package/src/index/taskRouting.js

@@ -139,6 +139,10 @@ export async function deriveTaskRoute({
     contextRecommendation,
     verificationRecommendation,
   });
+  const handoffBudget = intentMode === 'handoff'
+    ? await checkHandoffBudget(absoluteRoot)
+    : null;
+  const worklogBudget = await checkWorklogBudget(absoluteRoot);
   const routeSummary = buildRouteSummary({
     activeSkills,
     routingContext: {
@@ -157,6 +161,8 @@ export async function deriveTaskRoute({
     contextRecommendation,
     verificationRecommendation,
     nextAction,
+    handoffBudget,
+    worklogBudget,
   });
   const approachSelector = routeSummary?.approachSelector ?? null;
 
@@ -180,6 +186,8 @@ export async function deriveTaskRoute({
     verificationRecommendation,
     nextAction,
     routeSummary,
+    handoffBudget,
+    worklogBudget,
     ...(degradedWarnings.length > 0 ? { degradedWarnings } : {}),
   };
 }
@@ -190,6 +198,8 @@ export function buildRouteSummary({
   contextRecommendation = null,
   verificationRecommendation = null,
   nextAction = null,
+  handoffBudget = null,
+  worklogBudget = null,
 } = {}) {
   const autonomyLevel = routingContext.autonomyLevel ?? 'balanced';
   const delegationRecommendation = deriveDelegationRecommendation({
@@ -243,7 +253,7 @@ export function buildRouteSummary({
       ),
   );
   const nextActionCommand = compactHelperLane ? null : nextAction?.command ?? null;
-  const handoffFile = routingContext.intentMode === 'handoff' ? 'docs/AI_HANDOFF.md' : null;
+  const handoffFile = routingContext.intentMode === 'handoff' ? 'docs/AI_HANDOFF/ACTIVE.md' : null;
   const summaryLine = [
     routingContext.taskType ? `task=${routingContext.taskType}` : null,
     handoffFile ? `handoff=${handoffFile}` : null,
@@ -253,6 +263,8 @@ export function buildRouteSummary({
     editGuardHint ? `editGuard=${editGuardHint}` : null,
     delegationRecommendation?.hint ? `delegate=${delegationRecommendation.hint}` : null,
     policyMode ? `policy=${policyMode}` : null,
+    handoffBudget?.warning ? `budget=${handoffBudget.warning}` : null,
+    worklogBudget?.warning ? `budget=${worklogBudget.warning}` : null,
   ].filter(Boolean).join(' | ');
 
   return {
@@ -270,6 +282,8 @@ export function buildRouteSummary({
     continuationState,
     intentMode: routingContext.intentMode ?? null,
     handoffFile,
+    handoffBudget,
+    worklogBudget,
     delegateHint: delegationRecommendation?.hint ?? null,
     nextActionType: nextAction?.type ?? null,
     nextActionCommand,
@@ -1480,6 +1494,108 @@ function unique(values) {
   return [...new Set(values.filter(Boolean))];
 }
 
+const HANDOFF_BUDGET_MAX_LINES = 200;
+const HANDOFF_FILE_MAX_LINES = 80;
+const WORKLOG_BUDGET_MAX_LINES = 600;
+const WORKLOG_BUDGET_MAX_ENTRIES = 30;
+
+export async function checkHandoffBudget(rootDir) {
+  const handoffDir = path.join(rootDir, 'docs', 'AI_HANDOFF');
+  const checkFiles = ['ACTIVE.md', 'INDEX.md'];
+  let totalLines = 0;
+  const fileDetails = [];
+
+  for (const fileName of checkFiles) {
+    const filePath = path.join(handoffDir, fileName);
+    try {
+      const content = await fs.readFile(filePath, 'utf8');
+      const lines = content.split('\n').length;
+      totalLines += lines;
+      fileDetails.push({ file: fileName, lines });
+    } catch {
+      // File may not exist yet — not an error
+    }
+  }
+
+  // Also count task files
+  const tasksDir = path.join(handoffDir, 'tasks');
+  try {
+    const taskFiles = await fs.readdir(tasksDir);
+    for (const taskFile of taskFiles) {
+      if (!taskFile.endsWith('.md')) continue;
+      const content = await fs.readFile(path.join(tasksDir, taskFile), 'utf8');
+      const lines = content.split('\n').length;
+      totalLines += lines;
+      fileDetails.push({ file: `tasks/${taskFile}`, lines });
+    }
+  } catch {
+    // tasks dir may not exist
+  }
+
+  const oversizedFiles = fileDetails.filter((f) => f.lines > HANDOFF_FILE_MAX_LINES);
+  const overBudget = totalLines > HANDOFF_BUDGET_MAX_LINES;
+
+  let warning = null;
+  if (overBudget) {
+    warning = 'over-budget';
+  } else if (oversizedFiles.length > 0) {
+    warning = 'file-oversized';
+  }
+
+  return {
+    totalLines,
+    maxLines: HANDOFF_BUDGET_MAX_LINES,
+    fileDetails,
+    oversizedFiles: oversizedFiles.map((f) => f.file),
+    overBudget,
+    warning,
+    action: warning ? 'clear-handoff' : null,
+  };
+}
+
+export async function checkWorklogBudget(rootDir) {
+  const worklogPath = path.join(rootDir, 'docs', 'WORKLOG.md');
+  try {
+    const content = await fs.readFile(worklogPath, 'utf8');
+    const lines = content.split('\n').length;
+    const entryMatches = content.match(/^## \d{4}-\d{2}-\d{2}/gm) ?? [];
+    const entryCount = entryMatches.length;
+
+    const overLineBudget = lines > WORKLOG_BUDGET_MAX_LINES;
+    const overEntryBudget = entryCount > WORKLOG_BUDGET_MAX_ENTRIES;
+    const overBudget = overLineBudget || overEntryBudget;
+
+    let warning = null;
+    if (overLineBudget && overEntryBudget) {
+      warning = 'worklog-lines-and-entries-over';
+    } else if (overLineBudget) {
+      warning = 'worklog-lines-over';
+    } else if (overEntryBudget) {
+      warning = 'worklog-entries-over';
+    }
+
+    return {
+      lines,
+      maxLines: WORKLOG_BUDGET_MAX_LINES,
+      entryCount,
+      maxEntries: WORKLOG_BUDGET_MAX_ENTRIES,
+      overBudget,
+      warning,
+      action: warning ? 'compact-worklog' : null,
+    };
+  } catch {
+    return {
+      lines: 0,
+      maxLines: WORKLOG_BUDGET_MAX_LINES,
+      entryCount: 0,
+      maxEntries: WORKLOG_BUDGET_MAX_ENTRIES,
+      overBudget: false,
+      warning: null,
+      action: null,
+    };
+  }
+}
+
 const DELEGATABLE_IMPLEMENTATION_SKILL_IDS = new Set([
   'delivery',
   'frontend',

package/templates/.claude/hooks/skill-router.sh

@@ -3,7 +3,7 @@
 # Used from UserPromptSubmit and PreToolUse so end users do not need to name skills.
 
 INPUT=$(cat)
-PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
 STATE_FILE="$PROJECT_ROOT/.claude/ukit/skill-router-state.json"
 HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
 THRESHOLD_SCRIPT="$HOOK_DIR/../ukit/runtime/compact-threshold.mjs"

package/templates/.claude/hooks/verification-guard.sh

@@ -3,7 +3,7 @@
 # and does not jump to blanket verification when targeted evidence already exists.
 
 INPUT=$(cat)
-PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
 STATE_FILE="$PROJECT_ROOT/.claude/ukit/skill-router-state.json"
 ROUTE_CACHE_FILE="$PROJECT_ROOT/.claude/ukit/route-cache.json"
 PROGRESS_FILE="$PROJECT_ROOT/.claude/ukit/verification-progress.json"

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

@@ -44,7 +44,7 @@ If stale or missing, downgrade confidence and verify with the smallest current t
 ## Input Order
 
 Read only what is needed:
-1. `docs/AI_HANDOFF.md` first when the prompt explicitly names handoff / `ukit:handoff` / brainstorm-to-task flow
+1. `docs/AI_HANDOFF/ACTIVE.md` first when the prompt explicitly names handoff / `ukit:handoff` / brainstorm-to-task flow
 2. `docs/STATUS.md` (or existing root `STATUS.md` fallback) for normal status/continue prompts
 3. `docs/TASKS.md` only for queued-task prompts, “continue” with no active status, or when status points at queued work
 4. `docs/CODE_MAP.md` only when navigation is needed

package/templates/.claude/ukit/index/post-edit-verify.mjs

@@ -18,7 +18,8 @@ function getFilePath(payload = {}) {
 }
 
 function isHandoffAuthoringFile(relativePath) {
-  return relativePath === 'docs/AI_HANDOFF.md';
+  return relativePath === 'docs/AI_HANDOFF.md'
+    || relativePath.startsWith('docs/AI_HANDOFF/');
 }
 
 async function listManifestPaths(backupsRoot) {
@@ -200,7 +201,7 @@ async function main() {
     process.stdout.write(`[ukit-safe-patch] ${result.message}\n`);
   } else if (result.status === 'advisory') {
     process.stderr.write(`[ukit-safe-patch] ${result.message}\n`);
-    process.stderr.write('[ukit-safe-patch] handoff authoring advisory — change is already written; continue updating docs/AI_HANDOFF.md.\n');
+    process.stderr.write('[ukit-safe-patch] handoff authoring advisory — change is already written; continue updating docs/AI_HANDOFF/.\n');
   }
   if (result.status === 'blocked') {
     const advisory = isSafePatchAdvisoryOnly(runtimeConfig);

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

@@ -481,6 +481,7 @@ function formatDisplayRouteSummary(routeSummary = null, routingContext = {}) {
 
   const segments = [
     taskSegment,
+    extractRouteLineSegment(line, 'handoff'),
     extractRouteLineSegment(line, 'targets'),
     extractRouteLineSegment(line, 'tests'),
     extractRouteLineSegment(line, 'styles'),
@@ -831,14 +832,14 @@ function deriveIntentMode({ promptText = '', commandText = '', targetFile = null
   const openEndedStatus = hasOpenEndedStatusSignal(lower, raw) || taskQueueNext;
   const concreteTask = hasConcreteTaskSignal(lower, raw, targetFile, { taskQueueNext });
 
-  if (docsSpecific) {
-    return 'docs-specific';
-  }
-
   if (hasHandoffSignal(lower, raw)) {
     return 'handoff';
   }
 
+  if (docsSpecific) {
+    return 'docs-specific';
+  }
+
   if (statusUpdate) {
     return 'status-update';
   }
@@ -1350,8 +1351,10 @@ function buildRouteSummary({
       ),
   );
   const nextActionCommand = compactHelperLane ? null : nextAction?.command ?? null;
+  const handoffFile = routingContext.intentMode === 'handoff' ? 'docs/AI_HANDOFF/ACTIVE.md' : null;
   const line = [
     routingContext.taskType ? `task=${routingContext.taskType}` : null,
+    handoffFile ? `handoff=${handoffFile}` : null,
     formatCompactSegment('targets', primaryTargets),
     formatCompactSegment('tests', relatedTests),
     formatCompactSegment('styles', styleFiles),
@@ -1374,6 +1377,7 @@ function buildRouteSummary({
     completionState,
     continuationState,
     intentMode: routingContext.intentMode ?? null,
+    handoffFile,
     delegateHint: delegationRecommendation?.hint ?? null,
     nextActionType: nextAction?.type ?? null,
     nextActionCommand,

package/templates/CLAUDE.md

@@ -96,7 +96,7 @@ For clearly non-code specialist lanes (docs-only, status, task queue), skip the
 - **Non-trivial**: `docs/MEMORY.md` + `docs/PROJECT.md` + `docs/CODE_MAP.md`.
 - `docs/STATUS.md`: use for open-ended status/continue prompts or meaningful continuation context; stale status is orientation only.
 - `docs/TASKS.md`: use only for queued-task prompts or when status points at queued work; safely clean exact duplicates/completed overflow by default without deleting unfinished human-authored tasks.
-- `docs/WORKLOG.md`: only recent relevant entries.
+- `docs/WORKLOG.md`: only recent relevant entries. Follow the Budget Rules at the top of the file; archive oldest entries to `docs/WORKLOG_ARCHIVE.md` when over limits.
 - Follow routed verification policy: targeted first, widen only when risk/shared scope justifies it, ask before blanket broad runs.
 
 ## Living Status Workflow

package/templates/docs/AI_HANDOFF/ACTIVE.md

@@ -0,0 +1,9 @@
+# Active Handoff Cycle
+
+- Status: `ready_for_next_cycle`
+- Phase: `cleared`
+- Updated:
+- Updated by:
+- Human decision needed: `no`
+
+<!-- Snapshot only. Rules in RULES.md. Tasks in tasks/. Plan brainstorm in PLAN.md. -->

package/templates/docs/AI_HANDOFF/HISTORY.md

@@ -0,0 +1,4 @@
+# Handoff History
+
+| Cycle | Date | Summary |
+|-------|------|---------|

package/templates/docs/AI_HANDOFF/INDEX.md

@@ -0,0 +1,6 @@
+# Handoff Task Index
+
+| ID | Title | Priority | Size | Status | File |
+|----|-------|----------|------|--------|------|
+
+Updated:

package/templates/docs/AI_HANDOFF/PLAN.md

@@ -0,0 +1,5 @@
+# Handoff Plan
+
+Status: `empty`
+
+<!-- AI ghi ý tưởng + phân tích ở đây. Sau khi tách thành tasks, clear phần dưới. -->

package/templates/docs/AI_HANDOFF/RULES.md

@@ -0,0 +1,47 @@
+# Handoff Rules
+
+## Token Budget (MANDATORY)
+
+- **Combined handoff reads must stay under 200 lines per request.**
+- Read order: `ACTIVE.md` (if needed) → `INDEX.md` (scan tasks) → single `tasks/TASK-xxx.md` (implement one task).
+- Do NOT read `RULES.md` every request — only when you need flow clarification.
+- Do NOT read multiple task files in one request.
+- If ACTIVE.md + INDEX.md + task file would exceed budget, read only the task file.
+- Auto-compact: if any single handoff file exceeds 80 lines, trigger `clear handoff` immediately.
+
+## How Human Submits Ideas
+
+- Natural language is enough: `ukit:handoff`, `gom ý tưởng`, `chia task`, `đưa vào handoff`.
+- If request is already a concrete task (clear file/logic/output, small enough to do now), bypass handoff and execute directly.
+- If request is broad/ambiguous/multi-step, use handoff.
+
+## Handoff Flow
+
+1. Human submits ideas → AI writes to `PLAN.md`.
+2. Human approves plan → AI splits into `tasks/TASK-xxx.md` + updates `INDEX.md`.
+3. AI implementer reads `INDEX.md` → picks task → reads `tasks/TASK-xxx.md` → implements.
+4. After implementation → update `INDEX.md` status, archive cycle if done.
+
+## Task Gate
+
+A task is `ready` only when it has:
+- Clear target files
+- Clear action
+- Dependencies stated
+- Verification command
+- Acceptance criteria
+
+Missing any → `needs_breakdown`, `blocked`, or `needs_human`.
+
+## Clear Handoff
+
+1. Archive current cycle → `archive/cycle-NNN.md`.
+2. If archive > 3 files → delete oldest, append 1-line summary to `HISTORY.md`.
+3. Reset `ACTIVE.md` to empty template.
+4. Clear `INDEX.md`.
+5. Delete all files in `tasks/`.
+6. Clear `PLAN.md`.
+
+## Docs Sync
+
+After cycle, update affected docs only: `WORKLOG.md`, `PROJECT.md`, `CODE_MAP.md`, `CHANGELOG.md`.

package/templates/docs/INSTALL.md

@@ -47,7 +47,7 @@ End users do not need to manage any of that manually.
 Complete these files before first serious use:
 - `docs/PROJECT.md`
 - `docs/MEMORY.md`
-- `docs/AI_HANDOFF.md`
+- `docs/AI_HANDOFF/`
 - `docs/WORKLOG.md`
 
 ### 4) Open your AI tool
@@ -97,7 +97,7 @@ ukit install
 Check that the docs baseline files exist and are filled in:
 - `docs/PROJECT.md`
 - `docs/MEMORY.md`
-- `docs/AI_HANDOFF.md`
+- `docs/AI_HANDOFF/`
 - `docs/WORKLOG.md`
 
 ---

package/templates/docs/PROJECT.md

@@ -44,7 +44,7 @@
 
 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/AI_HANDOFF.md` when continuing cross-AI planning, task breakdown, or task implementation handoff work
+3. Read `docs/AI_HANDOFF/ACTIVE.md` when continuing cross-AI planning, task breakdown, or task implementation handoff work
 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

package/templates/docs/UKIT_USAGE_GUIDE.md

@@ -138,7 +138,7 @@ Project đang ở đâu, làm gì tiếp?
 
 Expected UKit behavior:
 1. auto-load the hidden next-step lane
-2. read `docs/AI_HANDOFF.md` when the team is passing planning, task breakdown, or implementation context between AIs
+2. read `docs/AI_HANDOFF/ACTIVE.md` when the team is passing planning, task breakdown, or implementation context between AIs
 3. verify the handoff against source/index before treating it as authoritative
 4. suggest only a few actionable next candidates
 5. if the prompt names a concrete bug/feature/review target, keep the concrete workflow primary instead of producing a global roadmap

package/templates/docs/WORKLOG.md

@@ -2,6 +2,17 @@
 
 Track session-level execution details.
 
+## Budget Rules
+
+Keep this file compact to save AI context tokens:
+
+- **Max 30 entries.** When over, archive the oldest entries to `docs/WORKLOG_ARCHIVE.md`.
+- **Max ~600 lines.** If over, archive oldest entries until under budget.
+- Each entry should be 10-20 lines max (summary, not transcript).
+- On archive: move full entry block to `docs/WORKLOG_ARCHIVE.md` (create if missing).
+- Keep a compaction marker as the last line: `<!-- Entries before YYYY-MM archived to docs/WORKLOG_ARCHIVE.md. Keep this file < 600 lines. -->`
+- If the user says "compact worklog" or "clean worklog", perform the archive pass and report what moved.
+
 For each significant action, append:
 - Date/time
 - Action taken

package/templates/ukit/storage/config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.5.2",
+  "version": "1.5.4",
   "agent": "claude-code",
   "autonomy": {
     "level": "balanced",

package/templates/docs/AI_HANDOFF.md

@@ -1,118 +0,0 @@
-# AI Handoff — {{project.name}}
-
-Dùng file này làm active handoff duy nhất cho project.
-Source code và test vẫn là sự thật cuối cùng.
-
----
-
-## 1. Current Cycle Snapshot
-
-- Handoff status: `draft | ready_for_planning | ready_for_breakdown | ready_for_implementation | blocked | ready_for_next_cycle | done`
-- Current phase: `planning | breakdown | implementation | verification | wrap_up | cleared`
-- Updated at:
-- Updated by AI:
-- Human decision needed: `yes | no`
-- Human decision summary:
-
----
-
-## 2. Handoff Rules
-
-### How human should submit ideas
-- Có thể nói tự nhiên: `ukit:handoff`, `đưa vào handoff`, `gom các ý tưởng này thành task`, `chia việc cho AI làm tiếp`.
-- Nếu request đã là task cụ thể, rõ file/logic/đầu ra hoặc đủ nhỏ để làm ngay, bypass handoff và thực hiện trực tiếp.
-- Nếu request là ý tưởng rộng, nhiều tính năng, cải tiến mơ hồ, brainstorming, nhiều plan/task, hoặc cần chia cho AI kế tiếp, dùng handoff.
-
-### Default handoff flow
-1. Capture ideas/request.
-2. Write a concrete plan.
-3. Split the plan into ordered tasks.
-4. Add target files, verification, dependencies, acceptance criteria, and stop conditions.
-5. Resolve `ready` tasks in order.
-6. Update this file with results.
-7. Clear active handoff by keeping summary + carry-forward backlog only.
-
-### Fast-AI task gate
-Một task chỉ được là `ready` khi có:
-- target file/folder rõ;
-- action cụ thể;
-- dependency/blocker rõ;
-- verification rõ;
-- acceptance criteria rõ;
-- stop condition rõ;
-- không cần đoán product decision.
-
-Nếu thiếu, để `needs_breakdown`, `blocked`, hoặc `needs_human`.
-
-### Clear rule
-- `clear handoff` không bao giờ là wipe mù.
-- Trước khi clear, AI phải resolve hoặc triage task còn lại.
-- Completed work thành summary ngắn.
-- Unfinished work thành carry-forward backlog ngắn.
-- Sau clear, file phải ngắn, sẵn sàng cho cycle tiếp theo.
-
-### Docs sync rule
-- Handoff không thay thế docs.
-- Sau khi xong cycle, update các file docs trực tiếp bị ảnh hưởng như `docs/WORKLOG.md`, `docs/PROJECT.md`, `docs/CODE_MAP.md`, `CHANGELOG.md` nếu có liên quan.
-- Không cần update toàn bộ `docs/` nếu không bị ảnh hưởng.
-
----
-
-## 3. Completed Cycle Summary
-
-### Cycle summary
-- completed:
-- verification:
-- important decisions:
-- carry-forward needed:
-
----
-
-## 4. Carry-Forward Backlog
-
-### TASK-001
-- Title:
-- Priority: `P0-now | P1-next | P2-later | blocked | needs_human`
-- Size: `S | M | L`
-- AI capability: `fast_ai_ok | needs_smart_ai | needs_human`
-- Goal:
-- Target files:
-- Dependencies:
-- Must do:
-- Must not do:
-- Acceptance criteria:
-- Verification:
-- Stop condition:
-- Status: `ready | blocked | in_progress | done | needs_breakdown | needs_human`
-- Owner AI:
-
-### TASK-002
-- Title:
-- Priority: `P0-now | P1-next | P2-later | blocked | needs_human`
-- Size: `S | M | L`
-- AI capability: `fast_ai_ok | needs_smart_ai | needs_human`
-- Goal:
-- Target files:
-- Dependencies:
-- Must do:
-- Must not do:
-- Acceptance criteria:
-- Verification:
-- Stop condition:
-- Status: `ready | blocked | in_progress | done | needs_breakdown | needs_human`
-- Owner AI:
-
----
-
-## 5. Decisions Made By Human
-
-- 
-- 
-
----
-
-## 6. Do Not Lose This Context
-
-- 
-- 
--