@ngockhoale/ukit 1.6.1 → 1.6.3

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.1",
+  "version": "1.6.3",
   "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/agents/bug-debugger.md

@@ -1,7 +1,7 @@
 ---
 name: bug-debugger
 description: "Debugging specialist for reproducible errors, failing tests, and unexpected behavior. Use proactively when investigation will involve noisy logs, stack traces, or a self-contained reproduce-trace-fix-verify loop. Do not use for trivial obvious fixes or broad architecture ideation."
-model: inherit
+model: sonnet  # unic-code
 color: red
 tools: ["Read", "Grep", "Glob", "Bash", "Edit", "TodoWrite"]
 ---

package/templates/.claude/agents/code-reviewer.md

@@ -1,7 +1,7 @@
 ---
 name: code-reviewer
 description: "Independent reviewer for handoff Phase 3. Use after executor reports STATUS: DONE on a handoff task. MUST run with a model different from the executor (configured in .ukit/storage/config.json → handoff.reviewer.model, default unic-smart). Produces a verdict: APPROVED | APPROVED-WITH-MINOR | CHANGES-REQUESTED | CRITICAL."
-model: inherit
+model: opus  # unic-smart
 color: yellow
 tools: ["Read", "Grep", "Glob", "Bash"]
 ---

package/templates/.claude/agents/feature-implementer.md

@@ -1,7 +1,7 @@
 ---
 name: feature-implementer
 description: "Implementation specialist for clear, self-contained coding tasks. Use proactively when the approach is clear and the work can be completed in a bounded pass with a concise summary. Do not use for trivial one-file tweaks or tightly coupled exploratory work."
-model: inherit
+model: sonnet  # unic-code
 color: green
 tools: ["Read", "Edit", "Write", "Grep", "Glob", "Bash", "TodoWrite"]
 ---

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

@@ -1,7 +1,7 @@
 ---
 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
+model: opus  # unic-smart
 color: purple
 tools: ["Read", "Edit", "Write", "Glob", "Bash", "TodoWrite"]
 ---

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: unic-lite
+model: haiku  # unic-lite
 color: cyan
 tools: ["Read", "Grep", "Glob", "Edit", "Write"]
 ---

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/settings.json

@@ -1,5 +1,6 @@
 {
-  "fastMode": true,
+  "model": "sonnet",
+  "fastMode": false,
   "fastModePerSessionOptIn": false,
   "alwaysThinkingEnabled": true,
   "effortLevel": "high",

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

@@ -1685,7 +1685,7 @@ function buildExecutionContract(executionMode = null) {
       completionEvidence: ['write-evidence'],
     },
     'find-cause': {
-      modelTier: 'smart',
+      modelTier: 'code',
       maxReadPassesBeforeReassess: 3,
       verificationPolicy: 'root-cause-then-targeted',
       completionRule: 'never-claim-fixed-without-write-and-verification',
@@ -1703,7 +1703,7 @@ function buildExecutionContract(executionMode = null) {
       mirrorConsistencyRequired: true,
     },
     'map-impact': {
-      modelTier: 'smart',
+      modelTier: 'code',
       maxReadPasses: 3,
       maxContextPulls: 3,
       verificationPolicy: 'impact-first-then-targeted-then-widen-on-risk',

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

@@ -145,16 +145,16 @@ 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 |
-| smart | `unic-smart` | claude-opus | Deep reasoning, root-cause analysis, release review |
+| 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` | code |
-| `find-cause`, `map-impact`, `review-release` | smart |
+| `local-fix`, `local-build`, `shared-edit`, `find-cause`, `map-impact` | code |
+| `review-release` | smart |
 
 ### Escalation rule