@ngockhoale/ukit 2.2.8 → 2.2.9

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 All notable changes to UKit are documented here.
 
+## 2.2.9 - 2026-08-28
+
+Retuning UKit's context budget used to mean editing five scattered places and hand-syncing two
+of them. It is now **three numbers in one file**, and everything else is derived at install time.
+
+The shipped defaults also move up for a 1M context window: compaction is recommended at 150,000
+estimated tokens (was 50,000) and the hard cap sits at 500,000 — half the window (was 220,000).
+
+### Changed
+
+- **`compact.tokenThreshold` / `compact.hardCapTokens` / `compact.autoCompactWindowRatio` in
+  `.ukit/storage/config.json` are now the only knobs.** New `src/core/compact/contextBudget.js`
+  reads them and derives the rest, so the defaults in `runtimeConfig.js` and
+  `compact/threshold.js` no longer carry their own copies of the number. Edit the three values,
+  rerun `ukit install`, and the whole budget follows. Documented in README →
+  *Retuning The Context Budget (maintainers)*, including a window→cap sizing table, because the
+  new 500,000 default sits **above** a 200k or 256k model's window, where the gate could never fire.
+- **New defaults:** `tokenThreshold` 50,000 → **150,000**; `hardCapTokens` 220,000 → **500,000**;
+  auto-compact fires at **70%** of the cap → 350,000.
+
+### Fixed
+
+- **omp auto-compact had silently drifted out of sync.** `.omp/config.yml`'s
+  `compaction.thresholdTokens` was still 180,000 while Claude Code's
+  `CLAUDE_CODE_AUTO_COMPACT_WINDOW` had moved on — the two were separate hand-maintained numbers
+  with nothing pinning them together. Both are now rendered from the same derived value at
+  install time, so **omp and Claude Code auto-compact at the same point** and cannot drift apart
+  again.
+- **`ompDocsSync > historical records are untouched by this cycle` failed on every new plan doc.**
+  The guard compared *all* changes under `docs/plans/` and friends against an old cycle's base
+  commit, so the first plan added afterwards (2.2.8's) tripped it permanently. Narrowed to
+  `--diff-filter=MDR`: rewriting, deleting or renaming a historical record still fails; adding a
+  new plan does not.
+
 ## 2.2.8 - 2026-08-28
 
 UKit already picked the right files to open, but the step *after* that — actually entering the

package/README.md

@@ -114,6 +114,36 @@ For maintainers, the runtime is inspectable with:
 
 Normal teammates should still only need **`ukit install`**.
 
+## Retuning The Context Budget (maintainers)
+
+Switching to a model with a different context window is a **three-number edit in one file**:
+`templates/ukit/storage/config.json` → `compact`.
+
+| Key | Default | What it means |
+| --- | --- | --- |
+| `tokenThreshold` | `150000` | Soft advisory. Past this UKit starts recommending compaction. |
+| `hardCapTokens` | `500000` | Absolute ceiling — 50% of a 1M window. `context-hardcap-gate` blocks Edit/Write/Bash here. |
+| `autoCompactWindowRatio` | `0.7` | Auto-compact fires at this fraction of the cap (→ `350000`). Must be `< 1`. |
+
+Everything else is derived — do **not** hand-edit these:
+
+- `.claude/settings.json` → `env.CLAUDE_CODE_AUTO_COMPACT_WINDOW`
+- `.omp/config.yml` → `compaction.thresholdTokens`
+- the code-side defaults in `src/core/runtimeConfig.js` and `src/core/compact/threshold.js`
+
+They are all rendered/read from the three keys above via `src/core/compact/contextBudget.js`.
+Edit the three numbers, rerun **`ukit install`**, and Claude Code and omp both follow.
+
+`hardCapTokens` must stay **below the model's real context window**, otherwise the API rejects
+the request before the gate can ever fire. Sizing at 50% of the window keeps room for the
+response plus the estimator's own undercount:
+
+| Model window | `hardCapTokens` | derived auto-compact |
+| --- | --- | --- |
+| 1M | `500000` | `350000` |
+| 256k | `128000` | `89600` |
+| 200k | `100000` | `70000` |
+
 ## Installer Behavior
 
 - idempotent install (safe to rerun)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.2.8",
+  "version": "2.2.9",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex, OpenCode, and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/src/core/compact/contextBudget.js

@@ -0,0 +1,57 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+// The shipped compact.tokenThreshold / compact.hardCapTokens / compact.autoCompactWindowRatio
+// trio is the ONLY place the context budget is written down. Every other number — the
+// code-side defaults, CLAUDE_CODE_AUTO_COMPACT_WINDOW in .claude/settings.json, and
+// compaction.thresholdTokens in .omp/config.yml — is read or derived from here, so retuning
+// UKit for a different model context window is a three-number edit in
+// templates/ukit/storage/config.json and nothing else.
+const SHIPPED_CONFIG_URL = new URL('../../../templates/ukit/storage/config.json', import.meta.url);
+
+// Only reachable if the package ships without its own templates. Deliberately conservative:
+// a 200k model survives these, a 1M model merely compacts earlier than it had to.
+const EMERGENCY_BUDGET = {
+  tokenThreshold: 50_000,
+  hardCapTokens: 160_000,
+  autoCompactWindowRatio: 0.7,
+};
+
+// Auto-compact must land strictly below hardCapTokens so the client heals itself before
+// context-hardcap-gate starts refusing Edit/Write/Bash; a ratio >= 1 would invert that and is
+// treated as a typo rather than honoured.
+export function deriveAutoCompactWindow(hardCapTokens, ratio) {
+  const safeRatio = Number.isFinite(ratio) && ratio > 0 && ratio < 1
+    ? ratio
+    : EMERGENCY_BUDGET.autoCompactWindowRatio;
+  return Math.round(hardCapTokens * safeRatio);
+}
+
+let cachedBudget = null;
+
+export function loadShippedCompactBudget() {
+  if (cachedBudget) {
+    return cachedBudget;
+  }
+
+  let compact = EMERGENCY_BUDGET;
+  try {
+    compact = JSON.parse(readFileSync(fileURLToPath(SHIPPED_CONFIG_URL), 'utf8')).compact ?? {};
+  } catch {
+    compact = EMERGENCY_BUDGET;
+  }
+
+  const tokenThreshold = Number.isFinite(compact.tokenThreshold)
+    ? compact.tokenThreshold
+    : EMERGENCY_BUDGET.tokenThreshold;
+  const hardCapTokens = Number.isFinite(compact.hardCapTokens)
+    ? compact.hardCapTokens
+    : EMERGENCY_BUDGET.hardCapTokens;
+
+  cachedBudget = {
+    tokenThreshold,
+    hardCapTokens,
+    autoCompactWindow: deriveAutoCompactWindow(hardCapTokens, compact.autoCompactWindowRatio),
+  };
+  return cachedBudget;
+}

package/src/core/compact/threshold.js

@@ -2,6 +2,7 @@ import { readJsonIfExists, writeJson } from '../fileOps.js';
 import { buildRuntimePaths } from '../runtimePaths.js';
 import { buildCompactMachineKey, compressLine, estimateTokenCount } from '../token/index.js';
 import { compactContextBlock } from './index.js';
+import { loadShippedCompactBudget } from './contextBudget.js';
 
 const DEFAULT_MAX_PROMPT_ENTRIES = 12;
 const DEFAULT_MAX_OUTPUT_ENTRIES = 12;
@@ -427,7 +428,10 @@ function computeEstimatedTotalTokens({
 }
 
 export function buildCompactThresholds(config = {}) {
-  const softThreshold = Math.max(1, finiteNumber(config?.compact?.tokenThreshold, 50_000));
+  const softThreshold = Math.max(
+    1,
+    finiteNumber(config?.compact?.tokenThreshold, loadShippedCompactBudget().tokenThreshold),
+  );
   const hardThreshold = Math.max(softThreshold + 1, Math.round(softThreshold * 1.6));
   const baselineTokens = Math.max(120, Math.min(18_000, Math.round(softThreshold * 0.18)));
 

package/src/core/runtimeConfig.js

@@ -2,6 +2,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 import { buildRuntimePaths } from './runtimePaths.js';
+import { loadShippedCompactBudget } from './compact/contextBudget.js';
 
 const require = createRequire(import.meta.url);
 const { version: PACKAGE_VERSION } = require('../../package.json');
@@ -70,7 +71,7 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
     },
     compact: {
       enabled: true,
-      tokenThreshold: 50_000,
+      tokenThreshold: loadShippedCompactBudget().tokenThreshold,
       contextRotDetection: true,
       askBeforeDrop: true,
       agentContext: {

package/src/render/buildVariables.js

@@ -1,3 +1,5 @@
+import { loadShippedCompactBudget } from '../core/compact/contextBudget.js';
+
 const CODEGRAPH_SECTION = `
 ## CodeGraph Integration (active)
 
@@ -12,7 +14,15 @@ To disable: rerun \`ukit install\` without \`--with-codegraph\`.
 `;
 
 export function buildTemplateVariables({ projectContext, stackContext, packageVersion, providerContext, withCodegraph = false }) {
+  // Derived, never hand-written: .claude/settings.json is read by Claude Code itself and so
+  // cannot consult .ukit/storage/config.json at runtime. Baking the window in here keeps
+  // compact.hardCapTokens the single number that retunes both.
+  const { autoCompactWindow } = loadShippedCompactBudget();
+
   return {
+    compact: {
+      autoCompactWindow: String(autoCompactWindow),
+    },
     project: {
       name: projectContext.project.name,
       root: projectContext.project.root,

package/templates/.claude/settings.json

@@ -11,7 +11,7 @@
   "defaultView": "chat",
   "autoCompactEnabled": true,
   "env": {
-    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "180000"
+    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "{{compact.autoCompactWindow}}"
   },
   "permissions": {
     "defaultMode": "bypassPermissions",

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

@@ -434,7 +434,7 @@ function computeEstimatedTotalTokens({
 }
 
 export function buildCompactThresholds(config = {}) {
-  const softThreshold = Math.max(1, finiteNumber(config?.compact?.tokenThreshold, 50_000));
+  const softThreshold = Math.max(1, finiteNumber(config?.compact?.tokenThreshold, 150_000));
   const hardThreshold = Math.max(softThreshold + 1, Math.round(softThreshold * 1.6));
   const baselineTokens = Math.max(120, Math.min(18_000, Math.round(softThreshold * 0.18)));
   // Deliberately NOT coupled to hardThreshold: this is an absolute ceiling, so raising
@@ -442,13 +442,15 @@ export function buildCompactThresholds(config = {}) {
   //
   // Must stay BELOW the model's real context window or the cap is unreachable: the API
   // rejects the request with "input exceeds the context window" long before an estimate
-  // climbing toward a higher number ever trips this. 220_000 is sized for a 256k window
-  // and leaves headroom for the response plus the estimator's own undercount. On a 200k
-  // model this default sits ABOVE the window, so the gate can never fire and is dead code
-  // in exactly the situation it exists to prevent — set compact.hardCapTokens to 160_000
-  // or lower for those. Pair it with env.CLAUDE_CODE_AUTO_COMPACT_WINDOW, which must stay
-  // strictly below this cap so the client auto-compacts before the gate blocks tools.
-  const hardCapTokens = Math.max(1, finiteNumber(config?.compact?.hardCapTokens, 220_000));
+  // climbing toward a higher number ever trips this. 500_000 is half of a 1M window, which
+  // leaves ample headroom for the response plus the estimator's own undercount. On any
+  // smaller model this default sits ABOVE the window, so the gate can never fire and is
+  // dead code in exactly the situation it exists to prevent — set compact.hardCapTokens to
+  // 100_000 (200k model) or 128_000 (256k model) for those. Both
+  // env.CLAUDE_CODE_AUTO_COMPACT_WINDOW and omp's compaction.thresholdTokens are rendered
+  // from this number at install time (70% of it), so the client auto-compacts before the
+  // gate blocks tools without anyone hand-syncing a second value.
+  const hardCapTokens = Math.max(1, finiteNumber(config?.compact?.hardCapTokens, 500_000));
 
   return {
     softThreshold,

package/templates/.omp/config.yml

@@ -78,8 +78,11 @@ memory:
   backend: off
 
 # Auto-compact must trigger BEFORE context-hardcap-gate.sh starts blocking tool
-# calls (compact.hardCapTokens, default 220000). Mirrors the Claude Code value
-# env.CLAUDE_CODE_AUTO_COMPACT_WINDOW = 180000 in templates/.claude/settings.json.
+# calls (compact.hardCapTokens, default 500000). Rendered at install time from the
+# same derived number as env.CLAUDE_CODE_AUTO_COMPACT_WINDOW in
+# templates/.claude/settings.json (70% of hardCapTokens), so omp and Claude Code
+# cannot drift apart and retuning both is a single edit to
+# templates/ukit/storage/config.json.
 #
 # Key VERIFIED against omp v17.4.2 (2026-08-22): `compaction.thresholdTokens` is a
 # fixed token limit for context maintenance and overrides the percentage threshold
@@ -88,4 +91,4 @@ memory:
 # omp rejects it outright (`omp config get compact.autoCompactWindow` → "Unknown
 # setting"), so auto-compact never moved off omp's default. See PLAN.md §3 D13.
 compaction:
-  thresholdTokens: 180000
+  thresholdTokens: {{compact.autoCompactWindow}}

package/templates/docs/AI_HANDOFF/RULES.md

@@ -79,8 +79,8 @@ Next: <bước kế tiếp chính xác>
 - Subagent ghi **full log vào task file trên đĩa**, chỉ trả về orchestrator ≤10 dòng (executor) / ≤6 dòng (reviewer). Paste log ngược lại orchestrator là nguyên nhân số 1 làm run chết vì hết context.
 - Hết mỗi wave: commit, ghi cursor, **collapse** wave đó còn 1 dòng/task trong bộ nhớ làm việc, rồi chạy tiếp.
 - Yêu cầu `/compact` **chỉ** được đặt ở cuối command, giữa 2 cycle. Giữa cycle thì tuyệt đối không — state đã nằm hết ở git + `INDEX.md` + `RUN.md` nên compact ở ranh giới cycle không mất gì.
-- Vượt `compact.hardCapTokens` (mặc định 220k, cỡ cho context window 256k) mà `RUN.md` còn run dở: `context-hardcap-gate` cho thêm `compact.hardCapGraceCalls` (mặc định 10) tool call rồi mới chặn cứng. **Grace đó chỉ để hạ cánh** — hoàn tất edit đang dở, commit, ghi cursor, push. Không mở task mới, không đọc thêm file, không spawn agent. Hết grace là chặn thật; budget chỉ reset khi ước lượng token thực sự giảm (có compact thật), không reset theo wave.
-- Không hook nào gọi được `/compact` — đó là lệnh client-only. Nhưng từ 2.1.3, settings mặc định đặt `env.CLAUDE_CODE_AUTO_COMPACT_WINDOW = 180000` < `hardCapTokens` (220k), nên **client tự auto-compact trước khi gate chặn**. Đường thường: auto-compact chạy → `handoff-resume.sh` replay cursor → chạy tiếp, không cần người gõ gì. Grace window ở trên chỉ còn là lưới an toàn.
+- Vượt `compact.hardCapTokens` (mặc định 500k = 50% của context window 1M) mà `RUN.md` còn run dở: `context-hardcap-gate` cho thêm `compact.hardCapGraceCalls` (mặc định 10) tool call rồi mới chặn cứng. **Grace đó chỉ để hạ cánh** — hoàn tất edit đang dở, commit, ghi cursor, push. Không mở task mới, không đọc thêm file, không spawn agent. Hết grace là chặn thật; budget chỉ reset khi ước lượng token thực sự giảm (có compact thật), không reset theo wave.
+- Không hook nào gọi được `/compact` — đó là lệnh client-only. Nhưng từ 2.1.3, settings mặc định đặt `env.CLAUDE_CODE_AUTO_COMPACT_WINDOW` = 70% của `hardCapTokens` (mặc định 350000 < 500k), render lúc install, nên **client tự auto-compact trước khi gate chặn**. Đường thường: auto-compact chạy → `handoff-resume.sh` replay cursor → chạy tiếp, không cần người gõ gì. Grace window ở trên chỉ còn là lưới an toàn.
 - Sửa một trong hai số đó thì phải giữ `autoCompactWindow < hardCapTokens`. Đảo thứ tự là deadlock: gate chặn tool trước → transcript ngừng lớn → ngưỡng auto-compact không bao giờ tới. `tests/core/autoCompactWindow.test.js` khóa bất biến này.
 
 ### Git

package/templates/ukit/storage/config.json

@@ -8,8 +8,9 @@
   },
   "compact": {
     "enabled": true,
-    "tokenThreshold": 50000,
-    "hardCapTokens": 220000,
+    "tokenThreshold": 150000,
+    "hardCapTokens": 500000,
+    "autoCompactWindowRatio": 0.7,
     "hardCapBlock": true,
     "hardCapGraceCalls": 10,
     "contextRotDetection": true,
@@ -394,7 +395,8 @@
     "compact": {
       "enabled": "Bật/tắt toàn bộ helper compact của UKit.",
       "tokenThreshold": "Ngưỡng token chung cho runtime compact dùng chung.",
-      "hardCapTokens": "Ngưỡng cứng tuyệt đối (mặc định 220000 token ước lượng, cỡ cho context window 256k). Chạm/vượt ngưỡng này thì context coi như quá dài — không phải gợi ý nữa, là bắt buộc. PHẢI thấp hơn context window thật của model, nếu không API sẽ báo lỗi vượt context trước khi gate kịp chặn — model 200k thì hạ xuống 160000 hoặc thấp hơn. Đi kèm env.CLAUDE_CODE_AUTO_COMPACT_WINDOW trong .claude/settings.json (mặc định 180000), số đó phải nhỏ hơn ngưỡng này để client tự auto-compact trước khi gate chặn tool.",
+      "hardCapTokens": "Ngưỡng cứng tuyệt đối (mặc định 500000 token ước lượng = 50% của context window 1M). Chạm/vượt ngưỡng này thì context coi như quá dài — không phải gợi ý nữa, là bắt buộc. PHẢI thấp hơn context window thật của model, nếu không API sẽ báo lỗi vượt context trước khi gate kịp chặn — model 200k thì hạ xuống 100000, model 256k thì 128000. Cả env.CLAUDE_CODE_AUTO_COMPACT_WINDOW (.claude/settings.json) lẫn compaction.thresholdTokens (.omp/config.yml) đều được SUY RA từ số này khi chạy ukit install, nên chỉ cần sửa ở đây rồi cài lại là auto-compact của cả Claude Code và omp đổi theo.",
+      "autoCompactWindowRatio": "Auto-compact chạy ở bao nhiêu phần của hardCapTokens (mặc định 0.7 → 350000). Phải < 1 để client tự compact TRƯỚC khi context-hardcap-gate chặn tool; số càng nhỏ thì compact càng sớm và càng nhiều đệm an toàn.",
       "hardCapBlock": "Nếu true, hook context-hardcap-gate chặn cứng Edit/Write/Bash (exit 2) khi vượt hardCapTokens, cho tới khi có compact thật (PreCompact) reset lại bộ đếm.",
       "hardCapGraceCalls": "Số tool call được phép chạy tiếp sau khi vượt hardCapTokens KHI docs/AI_HANDOFF/RUN.md còn run dở (mặc định 10). Dùng để run kịp commit + ghi cursor + push rồi mới bị chặn, thay vì chết giữa lúc đang Edit. Hết grace là chặn cứng như cũ. Budget tính theo mỗi đợt vượt cap, chỉ reset khi ước lượng token thật sự giảm (có compact thật) — không reset theo wave.",
       "contextRotDetection": "Phát hiện context quá dài/dễ mục để giữ lại state quan trọng trước khi AI nhớ sai.",