@ngockhoale/ukit 1.5.6 → 1.5.9

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.6",
+  "version": "1.5.9",
   "description": "Install/update an index-first AI workspace for Claude Code, Antigravity, OpenAI Codex, and OpenCode.",
   "license": "MIT",
   "type": "module",

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/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,73 @@
+# /ukit:clear-handoff
+
+Spawn **ukit-small-task-maintainer** (Haiku / unic-lite) to archive and reset the cycle.
+
+**HARD GATE: Will NOT clear if any task is not `done`.**
+
+---
+
+Spawn Agent:
+- `subagent_type: ukit-small-task-maintainer`
+- `model: haiku`
+- `prompt`:
+
+```
+Clear the current handoff cycle.
+
+## Step 1 — GATE CHECK (mandatory, cannot skip)
+
+Read docs/AI_HANDOFF/INDEX.md.
+List every task and its status.
+
+Find all tasks where status ≠ done:
+  - ready             → not started (run /ukit:implement-handoff TASK-xxx)
+  - in_progress       → executor still working
+  - pending_review    → waiting for review (run /ukit:review-handoff TASK-xxx)
+  - changes_requested → executor must fix (run /ukit:implement-handoff TASK-xxx)
+  - critical_block    → executor must fix (run /ukit:implement-handoff TASK-xxx)
+  - needs_breakdown   → planner must split (run /ukit:create-handoff to re-plan)
+  - blocked           → needs human decision
+
+If ANY task has status ≠ done → STOP IMMEDIATELY. Do NOT proceed to steps 2-4.
+Report:
+
+  ⛔ Cannot clear — X task(s) not done:
+  - TASK-001 [pending_review] → run /ukit:review-handoff TASK-001
+  - TASK-003 [changes_requested] → run /ukit:implement-handoff TASK-003
+  
+  Fix all tasks first, then re-run /ukit:clear-handoff.
+
+Only continue to Step 2 if ALL tasks are done.
+
+## Step 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
+
+## Step 3 — Archive cycle
+
+Read INDEX.md cycle ID.
+Write docs/AI_HANDOFF/archive/cycle-NNN.md:
+  # Cycle NNN — <YYYY-MM-DD>
+  ## Summary: <1 paragraph of what was accomplished>
+  ## Tasks: <copy INDEX.md table>
+
+If archive/ has > 3 files → delete oldest, append 1-line summary to HISTORY.md.
+
+## Step 4 — Reset state files
+
+PLAN.md       → "# PLAN\n_(empty)_"
+INDEX.md      → empty table header only
+ACTIVE.md     → "# ACTIVE\n_(no active cycle)_"
+tasks/TASK-*.md → delete all (keep _TEMPLATE.md)
+
+## Step 5 — Report
+
+Cycle NNN archived. X tasks completed. 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/ukit/storage/config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.5.6",
+  "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,