@ngockhoale/ukit 1.5.1 → 1.5.4

package/CHANGELOG.md

@@ -2,6 +2,55 @@
 
 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 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`.
+- 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 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
+
+- Added explicit handoff routing coverage in `tests/index/taskRouting.test.js`.
+- Verified Safe Patch protocol still passes 12 tests including the new handoff advisory case.
+
 ## 1.5.0 - 2026-05-24
 
 ### Fixed

package/README.md

@@ -32,8 +32,7 @@ ukit install
 4. Fill in the generated docs baseline:
    - `docs/PROJECT.md`
    - `docs/MEMORY.md`
-   - `docs/STATUS.md`
-   - `docs/TASKS.md`
+   - `docs/AI_HANDOFF/`
    - `docs/WORKLOG.md`
 5. Open your AI tool and work in natural language.
 
@@ -66,7 +65,7 @@ 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 / TASKS / WORKLOG baseline
+- `docs/` — PROJECT / MEMORY / AI_HANDOFF / WORKLOG baseline
 
 ## UKit v1.3.1 Runtime
 
@@ -91,8 +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/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
+- 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

@@ -143,10 +143,10 @@ items:
     packs:
       - core
 
-  - id: docs-status
+  - id: docs-ai-handoff
     type: config
-    sourceTemplate: docs/STATUS.md
-    targetPath: docs/STATUS.md
+    sourceTemplate: docs/AI_HANDOFF
+    targetPath: docs/AI_HANDOFF
     requires:
       - docs-project
       - docs-memory
@@ -159,19 +159,6 @@ 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
@@ -495,8 +482,7 @@ items:
     targetPath: .claude/skills/next-step/SKILL.md
     requires:
       - docs-quality-skill
-      - docs-status
-      - docs-tasks
+      - docs-ai-handoff
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true
@@ -509,8 +495,7 @@ items:
     targetPath: .claude/skills/update-status/SKILL.md
     requires:
       - docs-quality-skill
-      - docs-status
-      - docs-tasks
+      - docs-ai-handoff
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "1.5.1",
+  "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,9 +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')),
-    docsStatusExists: await pathExists(path.join(projectRoot, 'docs', 'STATUS.md')),
-    docsTasksExists: await pathExists(path.join(projectRoot, 'docs', 'TASKS.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
       ? {
@@ -105,9 +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.docsStatusExists)}  docs/STATUS.md`);
-  console.log(`[UKit]   ${ok(checks.docsTasksExists)}  docs/TASKS.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,10 +239,10 @@ export async function runInstall({ packageRoot, projectRoot, packageVersion, arg
   const docsLabels = [
     'docs/PROJECT.md',
     'docs/MEMORY.md',
-    'docs/STATUS.md',
-    'docs/TASKS.md',
+    'docs/AI_HANDOFF/ACTIVE.md',
     'docs/WORKLOG.md',
   ];
+
   const docsPaths = docsLabels.map((label) => path.join(projectRoot, ...label.split('/')));
   const missingDocs = [];
   for (let i = 0; i < docsPaths.length; i++) {
@@ -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/STATUS.md, docs/TASKS.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/STATUS.md, docs/TASKS.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/core/ensureGitignore.js

@@ -11,8 +11,6 @@ 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

@@ -49,7 +49,7 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
   const safeOverrides = isPlainObject(overrides) ? overrides : {};
 
   return mergeObjects({
-    version: '1.5.1',
+    version: '1.5.2',
     agent: 'claude-code',
     autonomy: {
       level: 'balanced',

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,14 +253,18 @@ export function buildRouteSummary({
       ),
   );
   const nextActionCommand = compactHelperLane ? null : nextAction?.command ?? null;
+  const handoffFile = routingContext.intentMode === 'handoff' ? 'docs/AI_HANDOFF/ACTIVE.md' : null;
   const summaryLine = [
     routingContext.taskType ? `task=${routingContext.taskType}` : null,
+    handoffFile ? `handoff=${handoffFile}` : null,
     formatCompactSegment('targets', primaryTargets),
     formatCompactSegment('tests', relatedTests),
     formatCompactSegment('styles', styleFiles),
     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 {
@@ -267,6 +281,9 @@ export function buildRouteSummary({
     completionState,
     continuationState,
     intentMode: routingContext.intentMode ?? null,
+    handoffFile,
+    handoffBudget,
+    worklogBudget,
     delegateHint: delegationRecommendation?.hint ?? null,
     nextActionType: nextAction?.type ?? null,
     nextActionCommand,
@@ -783,11 +800,11 @@ async function selectActiveSkills({ rootDir, promptText, commandText, targetFile
 }
 
 function shouldKeepRouteEntryForIntent(entry, intentMode) {
-  if (entry.id === 'next-step' && ['scoped-advice', 'docs-specific'].includes(intentMode)) {
+  if (entry.id === 'next-step' && ['scoped-advice', 'docs-specific', 'handoff'].includes(intentMode)) {
     return false;
   }
 
-  if (entry.id === 'update-status' && intentMode === 'docs-specific') {
+  if (entry.id === 'update-status' && ['docs-specific', 'handoff'].includes(intentMode)) {
     return false;
   }
 
@@ -896,6 +913,10 @@ function deriveIntentMode({ promptText = '', commandText = '', targetFile = null
   const openEndedStatus = hasOpenEndedStatusSignal(lower, raw) || taskQueueNext;
   const concreteTask = hasConcreteTaskSignal(lower, raw, targetFile, { taskQueueNext });
 
+  if (hasHandoffSignal(lower, raw)) {
+    return 'handoff';
+  }
+
   if (docsSpecific) {
     return 'docs-specific';
   }
@@ -927,6 +948,20 @@ function deriveIntentMode({ promptText = '', commandText = '', targetFile = null
   return null;
 }
 
+function hasHandoffSignal(lower, raw) {
+  return /\bukit:handoff\b/.test(raw)
+    || /\b(ai handoff|handoff phase|handoff mode|clear handoff|update handoff|start handoff|handoff clear)\b/.test(lower)
+    || /\b(brainstorm|idea dump|ideas?).{0,80}\b(handoff|tasks?|taskify|split|breakdown)\b/.test(lower)
+    || /\b(handoff|tasks?|taskify|split|breakdown).{0,80}\b(brainstorm|idea dump|ideas?)\b/.test(lower)
+    || /\b(gom|chia|tach|tách|lên|len|xóa|clear|dọn).{0,80}\b(idea|ý tưởng|y tuong|task|công việc|cong viec|handoff)\b/.test(raw)
+    || /\b(bàn giao|ban giao).{0,80}\b(ai|task|công việc|cong viec)\b/.test(raw);
+}
+
+function hasHandoffClearSignal(lower, raw) {
+  return /\b(clear handoff|handoff clear|dọn handoff|xóa handoff|reset handoff|compact handoff)\b/.test(lower)
+    || (/\bukit:handoff\b/.test(raw) && /\b(clear|dọn|xóa|reset|compact)\b/.test(lower));
+}
+
 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)
@@ -1459,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,11 +44,12 @@ If stale or missing, downgrade confidence and verify with the smallest current t
 ## 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
+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
+5. `docs/MEMORY.md` only when constraints/decisions affect the suggestion
+6. routed index/tree summary only if status/tasks are stale, missing, or contradicted
 
 ## Output Shape
 

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

@@ -17,6 +17,11 @@ function getFilePath(payload = {}) {
   return payload.tool_input?.file_path || payload.file_path || '';
 }
 
+function isHandoffAuthoringFile(relativePath) {
+  return relativePath === 'docs/AI_HANDOFF.md'
+    || relativePath.startsWith('docs/AI_HANDOFF/');
+}
+
 async function listManifestPaths(backupsRoot) {
   const dates = await fs.readdir(backupsRoot, { withFileTypes: true }).catch(() => []);
   return dates
@@ -152,7 +157,8 @@ export async function verifyPostEdit({ projectRoot = process.cwd(), payload = {}
 
   const overChangedLines = delta.changedLines > Number(config.deltaMaxChangedLines || 120);
   const overHunks = delta.hunkCount > Number(config.deltaMaxHunks || 3);
-  const status = risk.strict && (overChangedLines || overHunks) ? 'blocked' : 'ok';
+  const handoffAdvisory = isHandoffAuthoringFile(resolved.relative) && risk.labels.every((label) => ['large-file', 'multilingual-text'].includes(label));
+  const status = risk.strict && (overChangedLines || overHunks) ? (handoffAdvisory ? 'advisory' : 'blocked') : 'ok';
   const postEntry = {
     event: 'post-edit',
     file: resolved.relative,
@@ -169,8 +175,8 @@ export async function verifyPostEdit({ projectRoot = process.cwd(), payload = {}
 
   return {
     ...postEntry,
-    message: status === 'blocked'
-      ? `BLOCKED: '${resolved.relative}' exceeded Safe Patch delta budget (changedLines=${delta.changedLines}/${config.deltaMaxChangedLines}, hunks=${delta.hunkCount}/${config.deltaMaxHunks}). Review diff or restore from ${latest.entry.rollbackPath}.`
+    message: status === 'blocked' || status === 'advisory'
+      ? `${status === 'advisory' ? 'ADVISORY' : 'BLOCKED'}: '${resolved.relative}' exceeded Safe Patch delta budget (changedLines=${delta.changedLines}/${config.deltaMaxChangedLines}, hunks=${delta.hunkCount}/${config.deltaMaxHunks}). Review diff or restore from ${latest.entry.rollbackPath}.`
       : `OK: '${resolved.relative}' delta changedLines=${delta.changedLines}, hunks=${delta.hunkCount}.`,
   };
 }
@@ -193,6 +199,9 @@ async function main() {
     process.stdout.write(`${JSON.stringify(result)}\n`);
   } else if (result.status === 'ok') {
     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/.\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'),
@@ -723,11 +724,11 @@ async function selectActiveSkills({ rootDir, promptText, commandText, targetFile
 }
 
 function shouldKeepRouteEntryForIntent(entry, intentMode) {
-  if (entry.id === 'next-step' && ['scoped-advice', 'docs-specific'].includes(intentMode)) {
+  if (entry.id === 'next-step' && ['scoped-advice', 'docs-specific', 'handoff'].includes(intentMode)) {
     return false;
   }
 
-  if (entry.id === 'update-status' && intentMode === 'docs-specific') {
+  if (entry.id === 'update-status' && ['docs-specific', 'handoff'].includes(intentMode)) {
     return false;
   }
 
@@ -831,6 +832,10 @@ function deriveIntentMode({ promptText = '', commandText = '', targetFile = null
   const openEndedStatus = hasOpenEndedStatusSignal(lower, raw) || taskQueueNext;
   const concreteTask = hasConcreteTaskSignal(lower, raw, targetFile, { taskQueueNext });
 
+  if (hasHandoffSignal(lower, raw)) {
+    return 'handoff';
+  }
+
   if (docsSpecific) {
     return 'docs-specific';
   }
@@ -870,6 +875,20 @@ function hasStatusUpdateSignal(lower, raw) {
     || /\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 hasHandoffSignal(lower, raw) {
+  return /\bukit:handoff\b/.test(raw)
+    || /\b(ai handoff|handoff phase|handoff mode|clear handoff|update handoff|start handoff|handoff clear)\b/.test(lower)
+    || /\b(brainstorm|idea dump|ideas?).{0,80}\b(handoff|tasks?|taskify|split|breakdown)\b/.test(lower)
+    || /\b(handoff|tasks?|taskify|split|breakdown).{0,80}\b(brainstorm|idea dump|ideas?)\b/.test(lower)
+    || /\b(gom|chia|tach|tách|lên|len|xóa|clear|dọn).{0,80}\b(idea|ý tưởng|y tuong|task|công việc|cong viec|handoff)\b/.test(raw)
+    || /\b(bàn giao|ban giao).{0,80}\b(ai|task|công việc|cong viec)\b/.test(raw);
+}
+
+function hasHandoffClearSignal(lower, raw) {
+  return /\b(clear handoff|handoff clear|dọn handoff|xóa handoff|reset handoff|compact handoff)\b/.test(lower)
+    || (/\bukit:handoff\b/.test(raw) && /\b(clear|dọn|xóa|reset|compact)\b/.test(lower));
+}
+
 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)
@@ -1332,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),
@@ -1356,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,8 +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/STATUS.md`
-- `docs/TASKS.md`
+- `docs/AI_HANDOFF/`
 - `docs/WORKLOG.md`
 
 ### 4) Open your AI tool
@@ -98,8 +97,7 @@ ukit install
 Check that the docs baseline files exist and are filled in:
 - `docs/PROJECT.md`
 - `docs/MEMORY.md`
-- `docs/STATUS.md`
-- `docs/TASKS.md`
+- `docs/AI_HANDOFF/`
 - `docs/WORKLOG.md`
 
 ---

package/templates/docs/PROJECT.md

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

package/templates/docs/UKIT_USAGE_GUIDE.md

@@ -138,11 +138,10 @@ Project đang ở đâu, làm gì tiếp?
 
 Expected UKit behavior:
 1. auto-load the hidden next-step lane
-2. read `docs/STATUS.md` first and show whether it is fresh, possibly stale, stale, or missing
-3. read `docs/TASKS.md` only when selecting queued work or when status points at queued tasks
+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 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
+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.1",
+  "version": "1.5.4",
   "agent": "claude-code",
   "autonomy": {
     "level": "balanced",