@ngockhoale/ukit 1.5.5 → 1.5.8

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to UKit are documented here.
 
+## 1.5.7 - 2026-06-02
+
+### Fixed
+
+- Fixed `compact-threshold.mjs` never being deployed by `ukit install` — the file existed in `templates/` since v1.1.2 but was missing from `manifests/platform.full.yaml`. Every Bash PostToolUse hook (`compress-output.sh`) and PreCompact hook (`reinject-context.sh`) crashed with `ERR_MODULE_NOT_FOUND`, causing the agent to silently stop mid-task.
+- Added `ukit-runtime-compact-threshold-script` manifest entry with correct `requires` chain. Updated `requires` for `ukit-runtime-reinject-context-script`, `ukit-runtime-output-compression-script`, and `hook-skill-router` to declare the dependency.
+- Changed default `safePatch.advisoryOnly` from `false` to `true` in `src/core/runtimeConfig.js`. Previously, `stale-spec-guard.sh` exited code 2 on any Edit to a shared/risky file with a stale `old_string`, causing Claude Code to block the tool call and halt the agent loop silently from the user's perspective. Advisory mode downgrades exit 2 → exit 0 + warning, allowing the agent to continue.
+
 ## 1.5.5 - 2026-05-30
 
 ### Added

package/manifests/platform.full.yaml

@@ -768,6 +768,18 @@ items:
     packs:
       - core
 
+  - id: agent-handoff-planner
+    type: agent
+    sourceTemplate: .claude/agents/handoff-planner.md
+    targetPath: .claude/agents/handoff-planner.md
+    requires:
+      - docs-ai-handoff
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: agent-feature-implementer
     type: agent
     sourceTemplate: .claude/agents/feature-implementer.md
@@ -805,6 +817,54 @@ items:
     packs:
       - core
 
+  - id: command-create-handoff
+    type: command
+    sourceTemplate: .claude/commands/ukit/create-handoff.md
+    targetPath: .claude/commands/ukit/create-handoff.md
+    requires:
+      - docs-ai-handoff
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: command-implement-handoff
+    type: command
+    sourceTemplate: .claude/commands/ukit/implement-handoff.md
+    targetPath: .claude/commands/ukit/implement-handoff.md
+    requires:
+      - command-create-handoff
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: command-review-handoff
+    type: command
+    sourceTemplate: .claude/commands/ukit/review-handoff.md
+    targetPath: .claude/commands/ukit/review-handoff.md
+    requires:
+      - command-create-handoff
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: command-clear-handoff
+    type: command
+    sourceTemplate: .claude/commands/ukit/clear-handoff.md
+    targetPath: .claude/commands/ukit/clear-handoff.md
+    requires:
+      - command-create-handoff
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: provider-compat-config
     type: config
     sourceTemplate: .claude/config/providers.md
@@ -932,6 +992,7 @@ items:
     targetPath: .claude/hooks/skill-router.sh
     requires:
       - ukit-index-route-catalog-script
+      - ukit-runtime-compact-threshold-script
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true
@@ -1214,12 +1275,25 @@ items:
     packs:
       - core
 
+  - id: ukit-runtime-compact-threshold-script
+    type: config
+    sourceTemplate: .claude/ukit/runtime/compact-threshold.mjs
+    targetPath: .claude/ukit/runtime/compact-threshold.mjs
+    requires:
+      - ukit-runtime-token-utils-script
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: ukit-runtime-reinject-context-script
     type: config
     sourceTemplate: .claude/ukit/runtime/reinject-context.mjs
     targetPath: .claude/ukit/runtime/reinject-context.mjs
     requires:
       - ukit-runtime-token-utils-script
+      - ukit-runtime-compact-threshold-script
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true
@@ -1232,6 +1306,7 @@ items:
     targetPath: .claude/ukit/runtime/output-compression.mjs
     requires:
       - ukit-runtime-token-utils-script
+      - ukit-runtime-compact-threshold-script
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true

package/package.json

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

package/src/cli/commands/diff.js

@@ -18,6 +18,7 @@ export async function runDiff({ packageRoot, projectRoot, packageVersion, argv =
   const toolsArg = parseToolsArg(argv);
   const selectedOptionalTools = resolveOptionalToolKeys(toolsArg);
   const selectedAdapterItemIds = toSelectedAdapterItemIds(selectedOptionalTools);
+  const withCodegraph = argv.includes('--with-codegraph');
 
   const pathConfig = buildPathConfig({ packageRoot, projectRoot });
 
@@ -26,6 +27,7 @@ export async function runDiff({ packageRoot, projectRoot, packageVersion, argv =
     pathConfig,
     dryRun: true,
     selectedAdapterItemIds,
+    withCodegraph,
   });
 
   console.log('[UKit] Diff preview:');

package/src/cli/commands/install.js

@@ -198,6 +198,7 @@ export async function pruneDeselectedAdapters({
 export async function runInstall({ packageRoot, projectRoot, packageVersion, argv = [] }) {
   const toolsArg = parseToolsArg(argv);
   const selectedOptionalTools = resolveOptionalToolKeys(toolsArg);
+  const withCodegraph = argv.includes('--with-codegraph');
 
   const pruneResult = await pruneDeselectedAdapters({
     projectRoot,
@@ -213,6 +214,7 @@ export async function runInstall({ packageRoot, projectRoot, packageVersion, arg
     dryRun: false,
     selectedAdapterItemIds,
     retainedManagedRelativePaths: pruneResult?.retainedManagedPaths ?? [],
+    withCodegraph,
   });
 
   const { create, update, unchanged, skip } = result.summary;

package/src/cli/index.js

@@ -92,6 +92,10 @@ export async function runCli({ argv, packageRoot, projectRoot, packageVersion })
     console.log('                     Values: claude, antigravity, codex, opencode');
     console.log('                     Example: ukit install --tools=claude,codex,opencode');
     console.log('                     Use --tools=none to disable all optional adapters');
+    console.log('  --with-codegraph   Enable CodeGraph MCP integration in CLAUDE.md');
+    console.log('                     Adds routing rules that prefer codegraph_* tools for');
+    console.log('                     symbol search, context building, and impact analysis.');
+    console.log('                     Omit this flag to remove the section on reinstall.');
     console.log('');
     console.log('Maintainer / debug examples:');
     console.log('  ukit index build');

package/src/core/runInstallPipeline.js

@@ -217,6 +217,7 @@ export async function runInstallPipeline({
   dryRun,
   selectedAdapterItemIds,
   retainedManagedRelativePaths = [],
+  withCodegraph = false,
 }) {
   // Check for an existing install before making any changes.
   // cleanupLegacyPaths() is only safe to run on reinstalls: on a fresh install
@@ -239,6 +240,7 @@ export async function runInstallPipeline({
     stackContext,
     packageVersion,
     providerContext,
+    withCodegraph,
   });
 
   const plan = await buildInstallPlan({

package/src/core/runtimeConfig.js

@@ -183,7 +183,7 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
     safePatch: {
       enabled: true,
       strictSharedRisk: true,
-      advisoryOnly: false,
+      advisoryOnly: true,
       largeFileLineThreshold: 800,
       largeFileByteThreshold: 200_000,
       backupEnabled: true,

package/src/render/buildVariables.js

@@ -1,4 +1,17 @@
-export function buildTemplateVariables({ projectContext, stackContext, packageVersion, providerContext }) {
+const CODEGRAPH_SECTION = `
+## CodeGraph Integration (active)
+
+CodeGraph MCP is enabled for this project. When \`codegraph_*\` tools appear in your tool list:
+- **Symbol search** → \`codegraph_search\` (replaces \`node .claude/ukit/index/query-index.mjs\`)
+- **Context building** → \`codegraph_context\` (replaces \`resolve-context.mjs\`)
+- **Impact analysis** → \`codegraph_impact\` (replaces \`impact-context.mjs\`)
+- **Call graph** → \`codegraph_trace\`, \`codegraph_callers\`, \`codegraph_callees\` (new capability, no UKit equivalent)
+
+UKit routing, memory, and skill activation remain primary. CodeGraph is the index query layer only.
+To disable: rerun \`ukit install\` without \`--with-codegraph\`.
+`;
+
+export function buildTemplateVariables({ projectContext, stackContext, packageVersion, providerContext, withCodegraph = false }) {
   return {
     project: {
       name: projectContext.project.name,
@@ -35,5 +48,6 @@ export function buildTemplateVariables({ projectContext, stackContext, packageVe
     user: {
       profile: 'default',
     },
+    codegraphSection: withCodegraph ? CODEGRAPH_SECTION : '',
   };
 }

package/templates/.claude/agents/handoff-planner.md

@@ -0,0 +1,79 @@
+---
+name: handoff-planner
+description: "Handoff planning specialist for Phase 1+2. Use when creating a new handoff cycle: writes PLAN.md with full test plan, splits into TASK-xxx.md files with TDD-embedded test cases, and updates INDEX.md. Always use the strongest available model (Opus/unic-smart)."
+model: inherit
+color: purple
+tools: ["Read", "Edit", "Write", "Glob", "Bash", "TodoWrite"]
+---
+
+You are the PLANNER for UKit's handoff system. Your job is Phase 1 (write plan) + Phase 2 (split tasks). Always use the strongest model available — planning with a weak model produces weak tasks.
+
+## Inputs
+
+- Problem/feature description passed by the user (or from the invoking command).
+- Existing state in `docs/AI_HANDOFF/`: read `INDEX.md` and `ACTIVE.md` first.
+
+## Phase 1 — Write PLAN.md
+
+Read `docs/AI_HANDOFF/RULES.md` §4 for the full PLAN.md template. Write all 6 sections:
+
+```
+§1 Intent       — what problem, what success looks like
+§2 Scope        — in-scope / out-of-scope
+§3 Approach     — technical solution, trade-offs, alternatives rejected
+§4 Test Plan    — happy path × N + ≥1 edge case + regression (if bugfix)
+                  table: | Type | Test Name | Expected |
+§5 Verification — exact shell commands executor will run
+§6 Acceptance   — checklist of done criteria
+```
+
+**§4 is non-negotiable.** No test plan = plan is not ready. If the problem has zero testable behavior, write `N/A` + explicit justification in each task's Test Cases field.
+
+## Phase 2 — Split into TASK-xxx.md
+
+Use `docs/AI_HANDOFF/tasks/_TEMPLATE.md` as the template for each file.
+
+**Every task file MUST have:**
+
+| Field | Rule |
+|-------|------|
+| Target Files | Exact paths: `src/foo/bar.js`, `tests/foo/bar.test.js` |
+| Dependencies | `TASK-xxx` or `none` |
+| Test Cases | Table: Type \| Test Name \| Expected — ≥1 happy + ≥1 edge case |
+| Test Files | Exact test file paths to create/modify |
+| Verification Commands | Runnable shell commands (e.g. `yarn test tests/foo/bar.test.js`) |
+| Acceptance Criteria | Checklist items |
+
+Task missing any field → status = `needs_breakdown`. Never mark incomplete tasks `ready`.
+
+**Wave grouping:** Group tasks so Wave 1 = tasks with `dependencies: none`, Wave 2 = tasks depending on Wave 1, etc. Document the wave structure in `ACTIVE.md`.
+
+## Phase 3 — Update state files
+
+**INDEX.md** — add one row per task:
+```
+| TASK-001 | <short name> | ready | none | - |
+```
+
+**ACTIVE.md** — write snapshot:
+```
+Cycle: <cycle-ID>   Date: <YYYY-MM-DD>
+Goal: <1 sentence>
+Tasks: <N> total | Wave 1: TASK-001, TASK-002 | Wave 2: TASK-003
+Status: planning_done — ready for executor
+```
+
+## Output
+
+Report:
+- Number of tasks created + their IDs
+- Wave structure
+- Any tasks flagged `needs_breakdown` (explain why)
+- Exact next step for human: "Switch to Sonnet/unic-code → run `/ukit:implement-handoff`"
+
+## Rules
+
+- Do NOT start implementing. Your job ends when all tasks are `ready` (or `needs_breakdown`).
+- If existing INDEX.md has undone tasks → warn human, ask: continue old cycle or clear and start fresh?
+- Prefer more smaller tasks over fewer large tasks. Each task should be completable in one executor session.
+- If you cannot determine test cases for a task → flag `needs_breakdown`, add a Discussion thread note explaining what's missing.

package/templates/.claude/commands/ukit/clear-handoff.md

@@ -0,0 +1,42 @@
+# /ukit:clear-handoff
+
+Spawn **ukit-small-task-maintainer** (Haiku / unic-lite) to archive and reset the cycle.
+
+---
+
+Spawn Agent:
+- `subagent_type: ukit-small-task-maintainer`
+- `model: haiku`
+- `prompt`:
+
+```
+Clear the current handoff cycle.
+
+1. Read docs/AI_HANDOFF/INDEX.md
+   → If any task is in_progress or pending_review → WARN human, ask to confirm before proceeding
+
+2. Cleanup worktrees:
+   git worktree list | grep handoff/
+   For each .worktrees/task-xxx:
+     git worktree remove .worktrees/task-xxx --force
+     git branch -D handoff/task-xxx
+   git worktree prune
+
+3. Archive cycle:
+   Write docs/AI_HANDOFF/archive/cycle-NNN.md:
+     # Cycle NNN — <YYYY-MM-DD>
+     ## Summary: <1 paragraph>
+     ## Tasks: <INDEX.md table>
+   If archive/ has > 3 files → delete oldest, append 1-line to HISTORY.md
+
+4. Reset state files:
+   PLAN.md       → "# PLAN\n_(empty)_"
+   INDEX.md      → empty table header
+   ACTIVE.md     → "# ACTIVE\n_(no active cycle)_"
+   tasks/TASK-*.md → delete all (keep _TEMPLATE.md)
+
+5. Report: cycle archived, worktrees removed, ready for new cycle
+```
+
+After agent completes:
+> Ready for new cycle → `/ukit:create-handoff <description>`

package/templates/.claude/commands/ukit/create-handoff.md

@@ -0,0 +1,39 @@
+# /ukit:create-handoff
+
+Spawn a **handoff-planner** agent (Opus / unic-smart) to run Phase 1 + Phase 2.
+
+## Problem / feature
+$ARGUMENTS
+
+---
+
+Spawn Agent:
+- `subagent_type: handoff-planner`
+- `model: opus`
+- `prompt`:
+
+```
+Problem to plan: $ARGUMENTS
+
+1. Read docs/AI_HANDOFF/INDEX.md + ACTIVE.md
+   → If undone tasks exist, warn and ask human: continue old cycle or start fresh?
+
+2. Read docs/AI_HANDOFF/RULES.md for PLAN.md format + Task Gate rules
+
+3. Write docs/AI_HANDOFF/PLAN.md — all 6 sections mandatory:
+   §1 Intent | §2 Scope | §3 Approach | §4 Test Plan | §5 Verification Commands | §6 Acceptance Criteria
+   §4 Test Plan: happy path + ≥1 edge case + regression if bugfix
+
+4. Create docs/AI_HANDOFF/tasks/TASK-001.md ... using _TEMPLATE.md
+   Each task MUST have: Target Files, Dependencies, Test Cases, Test Files,
+   Verification Commands, Acceptance Criteria
+   Missing any field → status: needs_breakdown (never ready)
+
+5. Update INDEX.md — add row per task, status=ready
+6. Update ACTIVE.md — cycle snapshot + wave structure
+
+7. Report: task list + statuses, wave map, next step for human
+```
+
+After agent completes, tell human:
+> Switch to **Sonnet / unic-code** → run `/ukit:implement-handoff`

package/templates/.claude/commands/ukit/implement-handoff.md

@@ -0,0 +1,47 @@
+# /ukit:implement-handoff
+
+Spawn **feature-implementer** agents in parallel waves (Sonnet / unic-code).
+
+## Target (optional)
+$ARGUMENTS
+_Empty = all ready tasks. Or: "TASK-001" for a specific task._
+
+---
+
+1. Read `docs/AI_HANDOFF/INDEX.md`
+   - Collect tasks with status `ready` (or the specific task from $ARGUMENTS)
+   - If none → report and stop
+
+2. Group tasks into waves by dependency:
+   - Wave 1: tasks with `dependencies: none` or all deps already `done`
+   - Wave 2+: tasks whose deps are in the previous wave
+
+3. For each wave — spawn feature-implementer agents **in parallel**, one per task:
+
+```
+Implement docs/AI_HANDOFF/tasks/TASK-xxx.md in handoff mode.
+
+Worktree:
+  git worktree add -b handoff/task-xxx .worktrees/task-xxx
+  (skip -b if branch already exists)
+
+TDD (mandatory):
+  1. Write tests from §Test Cases → run → confirm RED
+  2. Implement → run → confirm GREEN
+  3. Run §Verification Commands → paste full output
+
+Executor Report (append to task file):
+  EXECUTOR_TOOL / EXECUTOR_MODEL / EXECUTOR_SUBAGENT: feature-implementer
+  Verification Output: <paste>
+  Status: PASS | FAIL
+
+Update INDEX.md: status → pending_review
+
+If tests FAIL → fix in same worktree before updating status. Never mark pending_review with a FAIL.
+```
+
+4. Wait for all agents in the wave → run next wave
+
+5. Report: PASS/FAIL per task, worktrees created, any blockers
+
+> Switch to **Opus / unic-smart** → run `/ukit:review-handoff`

package/templates/.claude/commands/ukit/review-handoff.md

@@ -0,0 +1,61 @@
+# /ukit:review-handoff
+
+Spawn **code-reviewer** agents (Opus / unic-smart — MUST differ from executor).
+After approval: merge worktree → delete branch + worktree.
+
+## Target (optional)
+$ARGUMENTS
+_Empty = all pending_review tasks. Or: "TASK-001" for a specific task._
+
+---
+
+1. Read `docs/AI_HANDOFF/INDEX.md`
+   - Collect tasks with status `pending_review` (or specific task from $ARGUMENTS)
+   - If none → report and stop
+
+2. For each task — spawn a **code-reviewer** agent:
+
+```
+Review docs/AI_HANDOFF/tasks/TASK-xxx.md
+
+Inputs:
+  - Task file (Test Plan + Verification Commands + Executor Report)
+  - Diff: git -C .worktrees/task-xxx diff main
+
+Steps:
+  1. Read EXECUTOR_MODEL from Executor Report
+     → REFUSE if same as your model (or model unknown)
+  2. Re-run §Verification Commands fresh — do NOT trust executor output
+     → If FAIL → verdict: critical_block, stop
+  3. Review diff: correctness, regression risk, security, maintainability
+  4. Append ## Reviewer Verdict to task file:
+       VERDICT: approved | approved_minor | changes_requested | critical_block
+       REVIEWER_MODEL / EXECUTOR_MODEL
+       VERIFICATION_RERUN: result
+       FINDINGS: critical / important / minor
+       NEXT_STATUS_FOR_INDEX: <status>
+
+  5. Update INDEX.md: set status = NEXT_STATUS_FOR_INDEX
+```
+
+3. After each agent verdict:
+
+   **approved / approved_minor:**
+   ```bash
+   git merge handoff/task-xxx --no-ff -m "feat: merge TASK-xxx"
+   git worktree remove .worktrees/task-xxx
+   git branch -d handoff/task-xxx
+   # INDEX.md: status → done
+   ```
+
+   **changes_requested / critical_block:**
+   ```
+   Keep worktree — executor must fix
+   Write findings in task file §Discussion
+   # INDEX.md: status → changes_requested | critical_block
+   ```
+
+4. Report: approved+merged tasks, tasks needing fixes, remaining worktrees
+
+> All done? → `/ukit:clear-handoff`
+> Tasks need fixes? → human runs `/ukit:implement-handoff TASK-xxx`

package/templates/CLAUDE.md

@@ -165,3 +165,4 @@ DuraOne skill chỉ active khi pack `duraone` được cài hoặc `.claude/skil
   - `.claude/skills/duraone/references/sql.md`
   - `.claude/skills/duraone/references/workflow.md`
 - Khi không active: dùng generic coding standards + project-specific patterns từ index.
+{{codegraphSection}}

package/templates/ukit/storage/config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.5.5",
+  "version": "1.5.7",
   "agent": "claude-code",
   "autonomy": {
     "level": "balanced",
@@ -147,7 +147,7 @@
   "safePatch": {
     "enabled": true,
     "strictSharedRisk": true,
-    "advisoryOnly": false,
+    "advisoryOnly": true,
     "largeFileLineThreshold": 800,
     "largeFileByteThreshold": 200000,
     "backupEnabled": true,