@ngockhoale/ukit 1.6.0 → 1.6.2

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to UKit are documented here.
 
+## 1.6.2 - 2026-07-26
+
+### Added
+
+- `ukit update` — new command that upgrades the globally installed UKit CLI to the latest published version (equivalent to `npm install -g @ngockhoale/ukit`).
+
+### Changed
+
+- Downgraded `find-cause` and `map-impact` orchestration contracts from `modelTier: smart` (opus) to `modelTier: code` (sonnet); `review-release` stays on `smart`. Reduces unnecessary Opus usage for routine debugging/impact-mapping work.
+
+### Fixed
+
+- Auto-compact context-pressure state is now surfaced to the model as a warning (`[ukit-skill-router] Context pressure: soft/hard ...`) once token usage crosses the soft/hard threshold, instead of being silently tracked and only reinjected after Claude Code's native compaction already began. Users previously had to compact manually because nothing ever prompted proactive `/compact` suggestions.
+
 ## 1.5.24 - 2026-06-10
 
 ### Fixed

package/README.md

@@ -162,6 +162,7 @@ These commands are still available, but they are **advanced workflows**, not def
 - `ukit uninstall` — remove UKit-managed assets
 - `ukit status` — inspect shared UKit runtime state
 - `ukit memory ...` — inspect/export/forget shared memory items
+- `ukit update` — upgrade the global UKit CLI to the latest published version (same as `npm install -g @ngockhoale/ukit`)
 - `ukit index ...` — run repo indexing/query/triage tools directly
 - `ukit build index` — alias for `ukit index build`
 

package/package.json

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

package/src/cli/commands/update.js

@@ -0,0 +1,27 @@
+import { updateUkit, UKIT_PACKAGE_NAME } from '../../core/update.js';
+
+const KNOWN_UPDATE_FLAGS = new Set(['--help', '-h']);
+
+export async function runUpdate({ packageVersion, argv = [] }) {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    console.log('Usage: ukit update');
+    console.log('');
+    console.log('Upgrade the globally installed UKit CLI to the latest published version.');
+    console.log(`Equivalent to: npm install -g ${UKIT_PACKAGE_NAME}`);
+    return;
+  }
+
+  const unknownFlags = argv.filter((a) => a.startsWith('-') && !KNOWN_UPDATE_FLAGS.has(a));
+  if (unknownFlags.length > 0) {
+    throw new Error(
+      `Unknown option(s): ${unknownFlags.join(', ')}. Run \`ukit update --help\` for usage.`,
+    );
+  }
+
+  console.log(`[UKit] Current version: ${packageVersion}`);
+  console.log(`[UKit] Running: npm install -g ${UKIT_PACKAGE_NAME}`);
+
+  updateUkit();
+
+  console.log('[UKit] Update complete. Run `ukit --version` to confirm the new version.');
+}

package/src/cli/index.js

@@ -5,6 +5,7 @@ import { runUninstall } from './commands/uninstall.js';
 import { runIndexTools } from './commands/indexTools.js';
 import { runStatus } from './commands/status.js';
 import { runMemory } from './commands/memory.js';
+import { runUpdate } from './commands/update.js';
 
 const GLOBAL_FLAGS = new Set(['--help', '-h', '--version', '-v']);
 
@@ -58,6 +59,11 @@ export async function runCli({ argv, packageRoot, projectRoot, packageVersion })
     return;
   }
 
+  if (command === 'update') {
+    await runUpdate({ packageVersion, argv: commandArgv });
+    return;
+  }
+
   if (command === 'build' && (commandArgv[0] ?? '').toLowerCase() === 'index') {
     await runIndexTools({ projectRoot, argv: ['build', ...commandArgv.slice(1)] });
     return;
@@ -85,6 +91,7 @@ export async function runCli({ argv, packageRoot, projectRoot, packageVersion })
     console.log('  index              Codebase index tools (build/query/triage)');
     console.log('  status             Show UKit runtime status');
     console.log('  memory             Inspect shared UKit memory');
+    console.log('  update             Upgrade the global UKit CLI to the latest version');
     console.log('  version            Show UKit version');
     console.log('');
     console.log('Options (install / diff):');

package/src/core/update.js

@@ -0,0 +1,19 @@
+import { spawnSync as defaultSpawnSync } from 'node:child_process';
+
+export const UKIT_PACKAGE_NAME = '@ngockhoale/ukit';
+
+export function updateUkit({ spawnSync = defaultSpawnSync } = {}) {
+  const result = spawnSync('npm', ['install', '-g', UKIT_PACKAGE_NAME], {
+    stdio: 'inherit',
+  });
+
+  if (result.error) {
+    throw new Error(`Failed to run npm install -g ${UKIT_PACKAGE_NAME}: ${result.error.message}`);
+  }
+
+  if (result.status !== 0) {
+    throw new Error(`npm install -g ${UKIT_PACKAGE_NAME} exited with code ${result.status}`);
+  }
+
+  return result;
+}

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

@@ -2601,7 +2601,7 @@ const { pathToFileURL } = require('url');
 NODE
 
 if [ -f "$THRESHOLD_SCRIPT" ]; then
-  printf '%s' "$INPUT" | CLAUDE_PROJECT_DIR="$PROJECT_ROOT" node "$THRESHOLD_SCRIPT" prompt >/dev/null 2>&1 || true
+  printf '%s' "$INPUT" | CLAUDE_PROJECT_DIR="$PROJECT_ROOT" node "$THRESHOLD_SCRIPT" prompt 2>/dev/null || true
 fi
 
 exit 0

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

@@ -433,6 +433,9 @@ function printRouteState(state) {
     console.log(`recent-output: ${recentOutputDisplay}`);
   }
   console.log(`summary: ${compactSummary}`);
+  if (state.routeSummary?.executionContract?.modelTier) {
+    console.log(`modelTier: ${state.routeSummary.executionContract.modelTier}`);
+  }
   if (nextDisplay) {
     console.log(`next: ${nextDisplay}`);
   }
@@ -1655,6 +1658,7 @@ function buildExecutionContract(executionMode = null) {
 
   const contracts = {
     'tiny-fix': {
+      modelTier: 'lite',
       maxReadPasses: 0,
       maxContextPulls: 0,
       verificationPolicy: 'minimal-or-targeted',
@@ -1663,6 +1667,7 @@ function buildExecutionContract(executionMode = null) {
       completionEvidence: ['write-evidence'],
     },
     'local-fix': {
+      modelTier: 'code',
       maxReadPasses: 1,
       maxContextPulls: 1,
       verificationPolicy: 'targeted-if-covered',
@@ -1671,6 +1676,7 @@ function buildExecutionContract(executionMode = null) {
       completionEvidence: ['write-evidence'],
     },
     'local-build': {
+      modelTier: 'code',
       maxReadPasses: 2,
       maxContextPulls: 1,
       verificationPolicy: 'targeted-if-covered',
@@ -1679,6 +1685,7 @@ function buildExecutionContract(executionMode = null) {
       completionEvidence: ['write-evidence'],
     },
     'find-cause': {
+      modelTier: 'code',
       maxReadPassesBeforeReassess: 3,
       verificationPolicy: 'root-cause-then-targeted',
       completionRule: 'never-claim-fixed-without-write-and-verification',
@@ -1686,6 +1693,7 @@ function buildExecutionContract(executionMode = null) {
       completionEvidence: ['write-evidence', 'verification-evidence'],
     },
     'shared-edit': {
+      modelTier: 'code',
       maxReadPasses: 2,
       maxContextPulls: 2,
       verificationPolicy: 'targeted-then-widen-on-risk',
@@ -1695,6 +1703,7 @@ function buildExecutionContract(executionMode = null) {
       mirrorConsistencyRequired: true,
     },
     'map-impact': {
+      modelTier: 'code',
       maxReadPasses: 3,
       maxContextPulls: 3,
       verificationPolicy: 'impact-first-then-targeted-then-widen-on-risk',
@@ -1704,6 +1713,7 @@ function buildExecutionContract(executionMode = null) {
       mirrorConsistencyRequired: true,
     },
     'review-release': {
+      modelTier: 'smart',
       verificationPolicy: 'evidence-first',
       completionRule: 'report-findings-not-implementation',
       delegationPolicy: 'allow-review-sidecar',

package/templates/.claude/ukit/runtime/compact-threshold.mjs

@@ -1019,12 +1019,18 @@ async function runCli() {
       return;
     }
 
-    await updateCompactPressureFromPrompt(projectRoot, {
+    const nextState = await updateCompactPressureFromPrompt(projectRoot, {
       promptText,
       routingContext: routeState?.routingContext ?? {},
       previousContext: routeState?.previousContext ?? null,
       routeSummary: routeState?.routeSummary ?? null,
     }, config);
+
+    if (nextState.phase === 'soft' || nextState.phase === 'hard') {
+      process.stdout.write(
+        `[ukit-skill-router] Context pressure: ${nextState.phase} (est ${nextState.estimatedTotalTokens} / soft ${nextState.softThreshold} / hard ${nextState.hardThreshold}). Suggest running /compact soon, or I will self-summarize before continuing.\n`,
+      );
+    }
   }
 }
 

package/templates/CLAUDE.md

@@ -136,6 +136,32 @@ Khi Handoff mode: đọc `docs/AI_HANDOFF/RULES.md` để biết 4 phase (Idea+P
 - `autonomy.level` in `.ukit/storage/config.json` controls how much UKit acts without asking first: `conservative` (ask more), `balanced` (default), `free-run` (auto-run more).
 - End users should not need to change this; maintainers may tune it per-project.
 
+## 3-Tier Model Routing
+
+**Internal orchestration only — end users still just use natural language. No new commands.**
+
+UKit routes tasks to one of three model tiers based on task complexity:
+
+| Tier | Generic alias | Claude model | Typical tasks |
+|------|--------------|--------------|---------------|
+| lite | `unic-lite` | claude-haiku | Reads, git queries, bash summaries, small doc edits |
+| code | `unic-code` | claude-sonnet | Normal coding, local fixes, shared edits, builds, debugging, impact mapping |
+| smart | `unic-smart` | claude-opus | Release review/audit, and escalated deep reasoning after repeated failure |
+
+### Contract-to-tier mapping
+
+| Contract | Tier |
+|----------|------|
+| `tiny-fix` | lite |
+| `local-fix`, `local-build`, `shared-edit`, `find-cause`, `map-impact` | code |
+| `review-release` | smart |
+
+### Escalation rule
+
+When the same file or symbol fails `debugLoopThreshold` (default: 2) times in one session, UKit routes the next attempt one tier higher (capped at `smart`). Config: `orchestration.escalation` in `.ukit/storage/config.json`.
+
+This is internal orchestration — end users do not need to know about tiers, thresholds, or escalation. The AI handles routing transparently.
+
 ## Project Snapshot
 
 - Project: {{project.name}} | Root: {{project.root}}