@ngockhoale/ukit 2.0.4 → 2.0.6

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to UKit are documented here.
 
+## 2.0.6 - 2026-08-12
+
+### Changed
+
+- **`context-window-guard.sh` now issues an actionable directive instead of a passive notice.** At 80%+ of `compact.hardCapTokens` it previously only printed an FYI warning that nothing acted on, so it kept re-firing every prompt with no remedy. It now instructs the agent, in the same turn: persist progress to `docs/STATUS.md` (update-status skill), split remaining multi-phase work (e.g. a `handoff-fullstack` run) into bounded `docs/AI_HANDOFF` tasks instead of continuing in one long thread, or tell the user plainly to `/compact`/start a fresh session. The full directive is debounced (3 min at hard phase, 8 min at soft) so it does not repeat in full every prompt — a short reminder line stands in until the phase changes or the cooldown lapses. `/compact` itself still cannot be invoked from a hook (client-only command), so this closes the gap by making the advisory self-actionable rather than attempting to fake a call the hook has no access to.
+
+## 2.0.5 - 2026-08-11
+
+### Changed
+
+- **Model IDs refreshed to the Claude 5 family**: `claude-sonnet-4-6` → `claude-sonnet-5`, `claude-opus-4-6` → `claude-opus-5`, across the `code`/`smart` tiers, `orchestration.modelTiers.vision.fallbackModel`, `handoff.defaultModel`/`advisorModel`/`orchestratorModel`, the Codex adapter settings, the `handoff-planner` agent example, and the config's own Vietnamese documentation strings. `claude-haiku-4-5` is unchanged — Haiku 4.5 is still current, so the `lite` tier was already correct. 54 references in live config, source and tests; historical records (`docs/AI_HANDOFF/archive/`, `docs/plans/`, `docs/WORKLOG.md`, `.ukit/storage/backups/`) are deliberately left alone, since rewriting what a past cycle actually ran on would be falsifying the record.
+
 ## 2.0.4 - 2026-08-11
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "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

@@ -117,14 +117,14 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
     },
     router: {
       enabled: true,
-      defaultModel: 'claude-sonnet-4-6',
-      advisorModel: 'claude-opus-4-6',
+      defaultModel: 'claude-sonnet-5',
+      advisorModel: 'claude-opus-5',
       advisorEnabled: true,
       maxAdvisorCalls: 3,
     },
     orchestration: {
       enabled: true,
-      orchestratorModel: 'claude-sonnet-4-6',
+      orchestratorModel: 'claude-sonnet-5',
       advisorEnabled: true,
       contracts: {
         'tiny-fix': {
@@ -176,12 +176,12 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       },
       modelTiers: {
         lite: { claudeModel: 'claude-haiku-4-5', genericModel: 'unic-lite' },
-        code: { claudeModel: 'claude-sonnet-4-6', genericModel: 'unic-code' },
-        smart: { claudeModel: 'claude-opus-4-6', genericModel: 'unic-smart' },
+        code: { claudeModel: 'claude-sonnet-5', genericModel: 'unic-code' },
+        smart: { claudeModel: 'claude-opus-5', genericModel: 'unic-smart' },
         vision: {
           claudeModel: 'unic-vision',
           genericModel: 'unic-vision',
-          fallbackModel: 'claude-sonnet-4-6',
+          fallbackModel: 'claude-sonnet-5',
           capabilityTier: true,
           note: 'Capability tier, not a cost tier. Orthogonal to lite/code/smart — never insert into escalation.tierOrder. fallbackModel is used when unicMode is off.',
         },

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

@@ -52,7 +52,7 @@ If zero testable behavior → write `N/A` + explicit justification in each task'
 Append this footer to `PLAN.md` — mandatory, checked by a hook before the write is allowed:
 ```
 ## Planner Report
-PLANNER_MODEL: <your exact model ID — e.g. claude-opus-4-6>
+PLANNER_MODEL: <your exact model ID — e.g. claude-opus-5>
 ```
 
 ## Phase 2 — Split into TASK-xxx.md

package/templates/.claude/hooks/context-window-guard.sh

@@ -134,21 +134,55 @@ const ratio = estimatedTokens / hardCap;
 if (ratio < 0.8) process.exit(0);
 
 const pct = Math.round(ratio * 100);
+const phase = ratio >= 1 ? 'hard' : 'soft';
+
+// Debounce the directive block so it does not re-print in full every single prompt
+// while the phase is unchanged — that would just be more tokens added to the same
+// oversized context it is warning about. Re-arms on phase change (soft -> hard) or
+// after the cooldown, and resets naturally once a real compaction/new session drops
+// the live transcript back under 0.8, since this whole branch exits early above.
+const GUARD_STATE_PATH = path.join(projectRoot, '.ukit', 'storage', 'cache', 'context-guard-state.json');
+const COOLDOWN_MS = phase === 'hard' ? 3 * 60 * 1000 : 8 * 60 * 1000;
+
+function readGuardState() {
+  try {
+    return JSON.parse(fs.readFileSync(GUARD_STATE_PATH, 'utf8'));
+  } catch {
+    return { lastPhase: null, lastActionAt: 0 };
+  }
+}
+
+function writeGuardState(state) {
+  try {
+    fs.mkdirSync(path.dirname(GUARD_STATE_PATH), { recursive: true });
+    fs.writeFileSync(GUARD_STATE_PATH, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+  } catch { /* best-effort only; never block the prompt over this */ }
+}
+
+const guardState = readGuardState();
+const now = Date.now();
+const withinCooldown = guardState.lastPhase === phase
+  && (now - Number(guardState.lastActionAt || 0)) < COOLDOWN_MS;
+
 const lines_out = [];
 if (ratio >= 1) {
   lines_out.push(`UKIT CONTEXT ALERT — live context ~${estimatedTokens.toLocaleString()} tokens, at/over the ${hardCap.toLocaleString()} cap (${pct}%).`);
   lines_out.push('The next few turns risk "Your input exceeds the context window of this model".');
-  lines_out.push('Act now: /compact, or finish this thread and start a fresh session.');
-  lines_out.push('If /compact itself already failed, the context is too large to summarise —');
-  lines_out.push('a new session is the only way out. Work committed to disk is not lost.');
 } else {
   lines_out.push(`UKIT CONTEXT WARNING — live context ~${estimatedTokens.toLocaleString()} tokens (${pct}% of the ${hardCap.toLocaleString()} cap).`);
-  lines_out.push('Wrap up or /compact soon, while compacting still works.');
 }
-if (sidechainEntries > 0) {
-  lines_out.push(`Note: ${sidechainEntries} subagent entries in this stretch. Each teammate carries its own`);
-  lines_out.push('context window, and every finished report is injected back here — running many at');
-  lines_out.push('once is the fastest way to overflow this session.');
+
+if (withinCooldown) {
+  lines_out.push('(Directive already issued this phase — act on it now if not already done; this is just a reminder.)');
+} else {
+  lines_out.push('ACTION THIS TURN, before starting new investigation/subagents/pipeline phases:');
+  lines_out.push('1) Persist current progress now (update docs/STATUS.md, e.g. via the update-status skill) so nothing is lost.');
+  lines_out.push('2) If the remaining work still has multiple steps or pipeline phases left (e.g. a handoff-fullstack run with implement/review/deploy still ahead), split what remains into bounded docs/AI_HANDOFF tasks instead of continuing in this one thread — smaller phases keep each turn under the cap.');
+  lines_out.push('3) Otherwise, tell the user plainly: run /compact now, or wrap up and start a fresh session — work already committed/persisted to disk is not lost.');
+  if (sidechainEntries > 0) {
+    lines_out.push(`Note: ${sidechainEntries} subagent entries in this stretch — each teammate carries its own context window, and every finished report is injected back here, so running many at once is the fastest way to overflow this session. Avoid spawning more until context drops back under the cap.`);
+  }
+  writeGuardState({ lastPhase: phase, lastActionAt: now });
 }
 
 process.stdout.write(`${lines_out.join('\n')}\n`);

package/templates/.codex/settings.json

@@ -264,7 +264,7 @@
       "configPath": ".ukit/storage/config.json",
       "modelField": "orchestration.orchestratorModel",
       "advisorField": "orchestration.advisorEnabled",
-      "defaultModel": "claude-sonnet-4-6",
+      "defaultModel": "claude-sonnet-5",
       "internalOnly": true,
       "qualityFirst": true,
       "safeUpwardBias": true,

package/templates/ukit/storage/config.json

@@ -73,14 +73,14 @@
   },
   "router": {
     "enabled": true,
-    "defaultModel": "claude-sonnet-4-6",
-    "advisorModel": "claude-opus-4-6",
+    "defaultModel": "claude-sonnet-5",
+    "advisorModel": "claude-opus-5",
     "advisorEnabled": true,
     "maxAdvisorCalls": 3
   },
   "orchestration": {
     "enabled": true,
-    "orchestratorModel": "claude-sonnet-4-6",
+    "orchestratorModel": "claude-sonnet-5",
     "advisorEnabled": true,
     "contracts": {
       "tiny-fix": {
@@ -139,12 +139,12 @@
     },
     "modelTiers": {
       "lite": { "claudeModel": "claude-haiku-4-5", "genericModel": "unic-lite" },
-      "code": { "claudeModel": "claude-sonnet-4-6", "genericModel": "unic-code" },
-      "smart": { "claudeModel": "claude-opus-4-6", "genericModel": "unic-smart" },
+      "code": { "claudeModel": "claude-sonnet-5", "genericModel": "unic-code" },
+      "smart": { "claudeModel": "claude-opus-5", "genericModel": "unic-smart" },
       "vision": {
         "claudeModel": "unic-vision",
         "genericModel": "unic-vision",
-        "fallbackModel": "claude-sonnet-4-6",
+        "fallbackModel": "claude-sonnet-5",
         "capabilityTier": true,
         "note": "Capability tier, not a cost tier. Orthogonal to lite/code/smart — never insert into escalation.tierOrder. fallbackModel is used when unicMode is off."
       }
@@ -192,7 +192,7 @@
       "minTestsHappyPath": 1,
       "minTestsEdgeCase": 1,
       "regressionTestRequiredForBugfix": true,
-      "smartModelHint": "claude-opus-4-6"
+      "smartModelHint": "claude-opus-5"
     },
     "executor": {
       "testFirstRequired": true,
@@ -338,8 +338,8 @@
       "doi_reviewer_model": {
         "field": "handoff.reviewer.model",
         "mac_dinh": "unic-smart",
-        "y_nghia": "Model dùng cho reviewer agent ở Phase 3. BẮT BUỘC khác model executor để bắt được lỗi mà executor miss. Có thể dùng claude-opus-4-6, unic-smart, hoặc bất kỳ model reasoning mạnh nào.",
-        "vi_du": "Nếu executor là unic-code (Kilo Code), set reviewer.model=unic-smart hoặc claude-opus-4-6. Nếu executor là claude-sonnet, set reviewer thành claude-opus."
+        "y_nghia": "Model dùng cho reviewer agent ở Phase 3. BẮT BUỘC khác model executor để bắt được lỗi mà executor miss. Có thể dùng claude-opus-5, unic-smart, hoặc bất kỳ model reasoning mạnh nào.",
+        "vi_du": "Nếu executor là unic-code (Kilo Code), set reviewer.model=unic-smart hoặc claude-opus-5. Nếu executor là claude-sonnet, set reviewer thành claude-opus."
       },
       "tat_reviewer_phase": {
         "field": "handoff.reviewer.enabled",
@@ -485,7 +485,7 @@
         "minTestsHappyPath": "Tối thiểu test cho happy path.",
         "minTestsEdgeCase": "Tối thiểu test cho edge case (null/empty/boundary/concurrent…).",
         "regressionTestRequiredForBugfix": "Bug fix phải có regression test fail-trước-fix.",
-        "smartModelHint": "Gợi ý model mạnh nhất cho phase plan (ví dụ claude-opus-4-6). UKit không tự ép, chỉ ghi hint vào task."
+        "smartModelHint": "Gợi ý model mạnh nhất cho phase plan (ví dụ claude-opus-5). UKit không tự ép, chỉ ghi hint vào task."
       },
       "executor": {
         "testFirstRequired": "Executor phải viết test trước khi implement (RED → GREEN).",
@@ -496,7 +496,7 @@
       },
       "reviewer": {
         "enabled": "Bật Phase 3 review độc lập. Tắt = bỏ lưới an toàn cuối cùng, không khuyến nghị.",
-        "model": "Model reviewer. BẮT BUỘC khác executor model. Mặc định unic-smart; có thể dùng claude-opus-4-6 hoặc bất kỳ model reasoning mạnh nào.",
+        "model": "Model reviewer. BẮT BUỘC khác executor model. Mặc định unic-smart; có thể dùng claude-opus-5 hoặc bất kỳ model reasoning mạnh nào.",
         "agent": "Tên reviewer agent (xem .claude/agents/code-reviewer.md).",
         "mustDifferFromExecutor": "Nếu true, reviewer tự refuse khi phát hiện cùng model với executor.",
         "blockOnCritical": "CRITICAL → block handoff cứng. Set false chỉ khi muốn warning mềm.",