@ngockhoale/ukit 2.0.5 → 2.0.6

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.0.5",
+  "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/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`);