@ngockhoale/ukit 2.2.8 → 2.2.10

package/CHANGELOG.md

@@ -2,6 +2,85 @@
 
 All notable changes to UKit are documented here.
 
+## 2.2.10 - 2026-08-29
+
+User report: long omp (Oh My Pi) sessions go idle roughly 15 minutes into a task — no output, no
+error, no notification, indistinguishable from a hang. Typing `continue` makes the session resume
+and finish correctly (the user's observation, not a measurement — no field reproduction of the
+stall exists on this machine to time it). Three real root causes were found by reading the source,
+not guessed:
+
+### Fixed
+
+- **`map-impact` — the mode wide implementation work actually routes to — was never gated by the
+  completion loop.** `templates/.claude/ukit/runtime/execution-ledger.mjs:12`'s `IMPLEMENT_MODES`
+  set omitted it, while `src/index/taskRouting.js:414` routes exactly this kind of task to
+  `map-impact` and `src/index/taskRouting.js:610` gives it the strictest contract
+  (`impact-evidence`, `write-evidence`, `verification-evidence`). So the longest tasks declared the
+  most evidence and got no gate at all — the session could stop with nothing written and nothing
+  verified, silently. `map-impact` is now in `IMPLEMENT_MODES`.
+- **Reaching the continuation cap ended the session with a log line, not a message.** At
+  `MAX_CONTINUATIONS` (6, unchanged), `evaluateCompletion` returned `{ capped: true }` and the only
+  reaction was `pi.logger.warn` — a log sink, not the transcript. This is also the mechanical reason
+  a new prompt (`continue`) appeared to "fix" the stall: a new prompt writes a fresh `requestKey`,
+  which resets the per-request continuation count back to zero. The gate now spends exactly one
+  final continuation (`finalNotice`) instructing the model to state what is unfinished and stop, and
+  persists a one-shot `notified` flag on the ledger so the notice cannot refire.
+- **The post-compact resume was delivered only to the next user turn, and every UKit→omp message was
+  `display: false`.** After an omp auto-compaction, the `docs/AI_HANDOFF/RUN.md` resume cursor was
+  sent with `deliverAs: 'nextTurn'` only — if compaction ended the agent loop, the cursor waited for
+  a human to type something. Separately, every message the bridge built hardcoded `display: false`,
+  so UKit had no user-visible channel in omp at all, for context or for stop notices.
+  `runSessionCompact` now sends the resume as `steer` (reaches a still-running turn) *and*
+  `nextTurn` (unchanged fallback), and `runSessionStop` now sends one `display: true` notice
+  whenever it stops with evidence still missing — including the previously-silent
+  `review-release` / ungated-mode case.
+
+**Two premises behind the third fix are unverified — omp is not installed in this development
+environment.** Whether omp still accepts a `steer` message after a compaction, and whether omp
+honours `display: true` on a bridge message, were not and could not be reproduced or measured here.
+Both changes are additive: if either premise is false, the `nextTurn` delivery and the model's own
+`finalNotice` message (from the second fix) still reach the user, so the worst case is unchanged
+from today's behaviour, never worse. See `docs/STATUS.md` for the open thread and the evidence that
+would confirm the continuation-cap path directly.
+
+- **`templates/.omp/RULES.md` gains one sticky rule**: ending a turn with no output is a defect, not
+  a pause — a model-side backstop for whatever a code gate cannot reach.
+
+## 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.10",
   "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/.claude/ukit/runtime/execution-ledger.mjs

@@ -15,6 +15,7 @@ const IMPLEMENT_MODES = new Set([
   'local-build',
   'shared-edit',
   'find-cause',
+  'map-impact',
 ]);
 
 function safeSegment(value) {
@@ -159,6 +160,7 @@ function freshLedger(payload, routeState, harness) {
     receipts: [],
     blocker: null,
     continuationCount: 0,
+    notified: false,
     updatedAt: Date.now(),
   };
 }
@@ -252,24 +254,48 @@ export function evaluateCompletion({ state = {}, ledger = {} } = {}) {
   const routeSummary = state?.routeSummary || {};
   const mode = routeSummary.executionMode || routeSummary.approachSelector?.executionMode || null;
   const evidence = requiredEvidence(state);
-  if (!IMPLEMENT_MODES.has(mode) || evidence.length === 0 || ledger?.blocker) {
-    return { continue: false, missingEvidence: [] };
+  if (ledger?.blocker) {
+    return { continue: false, notify: false, missingEvidence: [] };
+  }
+  if (evidence.length === 0) {
+    return { continue: false, notify: false, missingEvidence: [] };
   }
 
   const sameRequest = !ledger?.requestKey || !state?.requestKey || ledger.requestKey === state.requestKey;
   const effectiveLedger = sameRequest ? ledger : {};
   const missingEvidence = evidence.filter((item) => !evidenceSatisfied(item, effectiveLedger));
   if (missingEvidence.length === 0) {
-    return { continue: false, missingEvidence: [] };
+    return { continue: false, notify: false, missingEvidence: [] };
+  }
+
+  const gated = IMPLEMENT_MODES.has(mode);
+  if (!gated) {
+    return {
+      continue: false,
+      notify: true,
+      missingEvidence,
+      reason: `UKit completion gate: missing ${missingEvidence.join(', ')}. This mode does not auto-continue; tell the user what is unfinished.`,
+    };
   }
 
   const continuationCount = Number(effectiveLedger?.continuationCount || 0);
   if (continuationCount >= MAX_CONTINUATIONS) {
+    if (effectiveLedger?.notified === true) {
+      return {
+        continue: false,
+        capped: true,
+        notify: true,
+        missingEvidence,
+        reason: `UKit continuation cap reached with missing evidence: ${missingEvidence.join(', ')}.`,
+      };
+    }
     return {
-      continue: false,
+      continue: true,
+      finalNotice: true,
+      notify: true,
       capped: true,
       missingEvidence,
-      reason: `UKit continuation cap reached with missing evidence: ${missingEvidence.join(', ')}.`,
+      reason: `UKit stopping with unfinished work: ${missingEvidence.join(', ')}. Tell the user what is unfinished and stop; do not continue further.`,
     };
   }
 
@@ -298,6 +324,13 @@ export async function incrementContinuation(projectRoot, payload = {}, ledger =
   return next;
 }
 
+export async function markNotified(projectRoot, payload = {}, ledger = null) {
+  const current = ledger || await readExecutionLedger(projectRoot, payload) || freshLedger(payload, null, 'unknown');
+  const next = { ...current, notified: true, updatedAt: Date.now() };
+  await writeJsonAtomic(ledgerPath(projectRoot, payload), next);
+  return next;
+}
+
 async function readStdin() {
   if (process.stdin.isTTY) return '';
   const chunks = [];
@@ -322,7 +355,8 @@ async function main() {
     const ledger = await readExecutionLedger(projectRoot, payload) || {};
     const result = evaluateCompletion({ state, ledger });
     if (result.continue) {
-      await incrementContinuation(projectRoot, payload, ledger);
+      if (result.finalNotice) await markNotified(projectRoot, payload, ledger);
+      else await incrementContinuation(projectRoot, payload, ledger);
       process.stdout.write(`${JSON.stringify({ decision: 'block', reason: result.reason })}\n`);
     } else if (result.capped) {
       process.stderr.write(`[ukit-completion] ${result.reason}\n`);

package/templates/.omp/RULES.md

@@ -57,6 +57,12 @@ Prefer unique current-file anchors over line numbers or stale pasted blocks. Nev
 stale spec — re-read current source and confirm before applying. Preserve existing BOM and line
 endings.
 
+## 8. Never end a turn silently
+
+Ending a turn with no output is a defect, not a pause. If you stop before the work is finished, the
+last thing you emit is one short line naming what is unfinished and what you need. Silence is never
+a status — the user cannot distinguish it from a crash.
+
 > Maintainer note, not a per-turn rule: `modelRoles` in `.omp/config.yml` ships UNIC gateway names.
 > On a non-UNIC provider, edit only the three cost tiers — `lite`, `code`, `smart` — never `vision`,
 > which stays `unic-vision` because it is a capability lane, not a cost tier.

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/.omp/hooks/pre/ukit-bridge.js

@@ -12,6 +12,7 @@ import { spawnSync } from 'node:child_process';
 import {
   evaluateCompletion,
   incrementContinuation,
+  markNotified,
   readExecutionLedger,
   readRouteState,
   recordExecutionReceipt,
@@ -337,18 +338,18 @@ function textFromContent(content) {
     .join('\n');
 }
 
-function hookContextMessage(content) {
+function hookContextMessage(content, { display = false } = {}) {
   return {
     customType: 'ukit-hook-context',
     content,
-    display: false,
+    display,
   };
 }
 
-function sendContext(pi, context, deliverAs) {
+function sendContext(pi, context, deliverAs, { display = false } = {}) {
   const content = context.filter(Boolean).join('\n').trim();
   if (!content || typeof pi.sendMessage !== 'function') return;
-  pi.sendMessage(hookContextMessage(content), { deliverAs });
+  pi.sendMessage(hookContextMessage(content, { display }), { deliverAs });
 }
 
 export async function runToolCall(pi, event, { projectRoot, context: extensionContext = {} }) {
@@ -469,6 +470,9 @@ export async function runSessionCompact(pi, event, { projectRoot, context: exten
   const metadata = runtimeMetadata(event, extensionContext);
   const payload = buildHookPayload('SessionStart', { ...metadata, source: 'compact' });
   const result = await runScriptChain(pi, HOOK_EVENT_MAP.session_start, payload, { projectRoot });
+  // TODO(verify) PLAN.md §3 D3: whether omp still accepts a 'steer' message after a compaction
+  // is unverified. If it drops steer, the 'nextTurn' copy below preserves prior behavior.
+  sendContext(pi, result.context, 'steer');
   sendContext(pi, result.context, 'nextTurn');
   return undefined;
 }
@@ -490,12 +494,23 @@ export async function runSessionStop(
   const evaluation = evaluateCompletion({ state, ledger });
   if (!evaluation.continue) {
     if (evaluation.capped) pi.logger?.warn?.(`[UKit] ${evaluation.reason}`);
+    if (Array.isArray(evaluation.missingEvidence) && evaluation.missingEvidence.length > 0) {
+      const notice = [
+        `[UKit] Stopping with unfinished work: ${evaluation.missingEvidence.join(', ')}.`,
+        evaluation.reason,
+      ].filter(Boolean).join(' ');
+      // TODO(verify) PLAN.md §3 D4: whether omp honours display:true on a sendMessage payload
+      // is unverified (omp is not installed). If display is ignored, the finalNotice
+      // continuation below (the model's own message) is the channel guaranteed to render.
+      sendContext(pi, [notice], 'nextTurn', { display: true });
+    }
     return undefined;
   }
 
   if (suppliedLedger === undefined) {
     try {
-      await incrementContinuation(projectRoot, payload, ledger);
+      if (evaluation.finalNotice) await markNotified(projectRoot, payload, ledger);
+      else await incrementContinuation(projectRoot, payload, ledger);
     } catch (error) {
       pi.logger?.warn?.(`[UKit] continuation bookkeeping failed open: ${error?.message || error}`);
     }

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.",