@ngockhoale/ukit 1.5.0 → 1.5.2

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to UKit are documented here.
 
+## 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.
+
+### 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.
+- 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.
+- 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.md`
    - `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.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
 - 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

@@ -84,7 +84,7 @@ items:
     requires:
       - docs-project
       - docs-memory
-    mergeStrategy: skip
+    mergeStrategy: overwrite_with_backup
     variables:
       - project.name
       - project.root
@@ -107,7 +107,7 @@ items:
     requires:
       - docs-project
       - docs-memory
-    mergeStrategy: skip
+    mergeStrategy: overwrite_with_backup
     variables:
       - project.name
       - project.stack
@@ -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.md
+    targetPath: docs/AI_HANDOFF.md
     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
@@ -1302,6 +1287,15 @@ items:
     packs:
       - core
 
+  - id: multi-antigravity-agents-link
+    type: link
+    sourceTemplate: .claude/agents
+    targetPath: .antigravity/agents
+    requires: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: multi-antigravity-rules
     type: config
     sourceTemplate: adapter-presets/antigravity/rules.md
@@ -1349,6 +1343,15 @@ items:
     packs:
       - core
 
+  - id: multi-codex-agents-link
+    type: link
+    sourceTemplate: .claude/agents
+    targetPath: .codex/agents
+    requires: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: multi-codex-readme
     type: config
     sourceTemplate: .codex/README.md

package/package.json

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

package/src/cli/adapters.js

@@ -7,12 +7,14 @@ export const OPTIONAL_ADAPTERS = [
       'multi-antigravity-ukit-link',
       'multi-antigravity-rules',
       'multi-antigravity-readme',
+      'multi-antigravity-agents-link',
     ],
     managedPaths: [
       '.antigravity/skills',
       '.antigravity/ukit',
       '.antigravity/rules/rules.md',
       '.antigravity/README.md',
+      '.antigravity/agents',
     ],
   },
   {
@@ -24,6 +26,7 @@ export const OPTIONAL_ADAPTERS = [
       'multi-codex-readme',
       'multi-codex-settings-json',
       'multi-codex-settings-local',
+      'multi-codex-agents-link',
     ],
     managedPaths: [
       '.codex/skills',
@@ -31,6 +34,7 @@ export const OPTIONAL_ADAPTERS = [
       '.codex/README.md',
       '.codex/settings.json',
       '.codex/settings.local.json',
+      '.codex/agents',
     ],
   },
   {

package/src/cli/commands/doctor.js

@@ -62,8 +62,7 @@ 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.md')),
     docsWorklogExists: await pathExists(path.join(projectRoot, 'docs', 'WORKLOG.md')),
     allProvidersConfigured: providers.allSupported,
     ...(codexAdapterTracked
@@ -105,8 +104,7 @@ 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.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

@@ -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.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.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/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.md, docs/WORKLOG.md contain user content and were preserved. Delete manually if needed.');
 }

package/src/core/applyPlan.js

@@ -2,6 +2,16 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { writeFileAtomic, copyFileSafe, createDirectoryLink, removeLinkOnly } from './fileOps.js';
 
+const TCC_PROTECTED_PREFIXES = ['.codex/', '.antigravity/'];
+
+function isTccProtectedPath(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+  return TCC_PROTECTED_PREFIXES.some((prefix) => {
+    const idx = normalized.indexOf(`/${prefix}`);
+    return idx !== -1 || normalized.startsWith(prefix);
+  });
+}
+
 export async function applyDiffResults(diffResults, { backupRoot, projectRoot } = {}) {
   const writes = [];
   let skippedUpdates = 0;
@@ -12,14 +22,9 @@ export async function applyDiffResults(diffResults, { backupRoot, projectRoot }
     }
 
     if (entry.type === 'link') {
-      // Remove existing symlink before recreating.
-      // Use removeLinkOnly — NOT removeLinkOrDir — to protect real directories that may
-      // contain user content. If the path is not a symlink, skip and warn instead of
-      // recursively deleting it.
       if (entry.action === 'update') {
         const removed = await removeLinkOnly(entry.targetPath);
         if (!removed) {
-          // Determine what actually exists at this path for a precise warning message.
           let existingKind = 'unknown path';
           try {
             const stat = await fs.lstat(entry.targetPath);
@@ -34,7 +39,18 @@ export async function applyDiffResults(diffResults, { backupRoot, projectRoot }
           continue;
         }
       }
-      await createDirectoryLink(entry.linkTarget, entry.targetPath);
+      try {
+        await createDirectoryLink(entry.linkTarget, entry.targetPath);
+      } catch (linkError) {
+        if (linkError.code === 'EPERM' || linkError.code === 'EACCES') {
+          console.warn(
+            `[UKit] Warning: skipping link creation for ${entry.targetPath} — permission denied. Run 'ukit install' from within the target tool to create it.`,
+          );
+          skippedUpdates += 1;
+          continue;
+        }
+        throw linkError;
+      }
       writes.push({
         id: entry.id,
         targetPath: entry.targetPath,
@@ -54,7 +70,18 @@ export async function applyDiffResults(diffResults, { backupRoot, projectRoot }
       const relPath = path.relative(projectRoot, entry.targetPath);
       const timestamp = Date.now();
       const backupPath = path.join(backupRoot, `${relPath}.${timestamp}.bak`);
-      await copyFileSafe(entry.targetPath, backupPath);
+      try {
+        await copyFileSafe(entry.targetPath, backupPath);
+      } catch (backupError) {
+        if (backupError.code === 'EPERM' || backupError.code === 'EACCES') {
+          console.warn(
+            `[UKit] Warning: skipping backup for ${entry.targetPath} — permission denied.`,
+          );
+          skippedUpdates += 1;
+          continue;
+        }
+        throw backupError;
+      }
     }
 
     const binaryEntry = Buffer.isBuffer(entry.renderedContent);
@@ -73,7 +100,21 @@ export async function applyDiffResults(diffResults, { backupRoot, projectRoot }
           )
           : entry.renderedContent;
 
-    await writeFileAtomic(entry.targetPath, nextContent);
+    try {
+      await writeFileAtomic(entry.targetPath, nextContent);
+    } catch (writeError) {
+      if (
+        (writeError.code === 'EPERM' || writeError.code === 'EACCES') &&
+        isTccProtectedPath(entry.targetPath)
+      ) {
+        console.warn(
+          `[UKit] Warning: skipping write for ${entry.targetPath} — permission denied (macOS TCC). Run 'ukit install' from within the owning tool to update it.`,
+        );
+        skippedUpdates += 1;
+        continue;
+      }
+      throw writeError;
+    }
     if (typeof entry.mode === 'number') {
       await fs.chmod(entry.targetPath, entry.mode);
     }

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.0',
+    version: '1.5.2',
     agent: 'claude-code',
     autonomy: {
       level: 'balanced',

package/src/index/taskRouting.js

@@ -243,8 +243,10 @@ export function buildRouteSummary({
       ),
   );
   const nextActionCommand = compactHelperLane ? null : nextAction?.command ?? null;
+  const handoffFile = routingContext.intentMode === 'handoff' ? 'docs/AI_HANDOFF.md' : null;
   const summaryLine = [
     routingContext.taskType ? `task=${routingContext.taskType}` : null,
+    handoffFile ? `handoff=${handoffFile}` : null,
     formatCompactSegment('targets', primaryTargets),
     formatCompactSegment('tests', relatedTests),
     formatCompactSegment('styles', styleFiles),
@@ -267,6 +269,7 @@ export function buildRouteSummary({
     completionState,
     continuationState,
     intentMode: routingContext.intentMode ?? null,
+    handoffFile,
     delegateHint: delegationRecommendation?.hint ?? null,
     nextActionType: nextAction?.type ?? null,
     nextActionCommand,
@@ -783,11 +786,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 +899,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 +934,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)

package/src/manifest/selectItems.js

@@ -3,11 +3,13 @@ export const OPTIONAL_ADAPTER_ITEM_IDS = new Set([
   'multi-antigravity-ukit-link',
   'multi-antigravity-rules',
   'multi-antigravity-readme',
+  'multi-antigravity-agents-link',
   'multi-codex-skills-link',
   'multi-codex-ukit-link',
   'multi-codex-readme',
   'multi-codex-settings-json',
   'multi-codex-settings-local',
+  'multi-codex-agents-link',
   'multi-opencode-config',
 ]);
 

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

@@ -1,7 +1,7 @@
 ---
 name: ukit-small-task-maintainer
 description: "Internal UKit maintenance subagent for low-risk, reversible UKit decisions. Use proactively when UKit needs to decide or perform safe cleanup such as pruning docs/TASKS.md, classifying queued work, choosing whether compact/summarization is appropriate, summarizing local docs/status, or maintaining small UKit runtime queues. Do not use for product implementation, security, release/publish, data-loss, architecture, or risky/shared code changes."
-model: inherit
+model: unic-lite
 color: cyan
 tools: ["Read", "Grep", "Glob", "Edit", "Write"]
 ---

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.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,10 @@ function getFilePath(payload = {}) {
   return payload.tool_input?.file_path || payload.file_path || '';
 }
 
+function isHandoffAuthoringFile(relativePath) {
+  return relativePath === 'docs/AI_HANDOFF.md';
+}
+
 async function listManifestPaths(backupsRoot) {
   const dates = await fs.readdir(backupsRoot, { withFileTypes: true }).catch(() => []);
   return dates
@@ -152,7 +156,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 +174,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 +198,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.md.\n');
   }
   if (result.status === 'blocked') {
     const advisory = isSafePatchAdvisoryOnly(runtimeConfig);

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

@@ -723,11 +723,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;
   }
 
@@ -835,6 +835,10 @@ function deriveIntentMode({ promptText = '', commandText = '', targetFile = null
     return 'docs-specific';
   }
 
+  if (hasHandoffSignal(lower, raw)) {
+    return 'handoff';
+  }
+
   if (statusUpdate) {
     return 'status-update';
   }
@@ -870,6 +874,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)