@ngockhoale/ukit 2.3.5 → 2.3.6

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to UKit are documented here.
 
+## 2.3.6 - 2026-09-10
+
+Anti-stall coverage parity release: the compact-recovery and stop-reason directives that
+UKit hooks inject at runtime on Claude Code and omp now also reach harnesses that have no
+hook system at all.
+
+A new `## Long-Run Continuity` section ships in both `templates/CLAUDE.md` and
+`templates/AGENTS.md` (byte-identical, enforced by the per-section context-docs parity
+test). Codex and OpenCode load no hooks, so root `AGENTS.md` is their only instruction
+channel — before this release those sessions never saw the near-cap recovery order (LAND
+one thing → DEFER the rest to `docs/STATUS.md` → DELEGATE broad work to subagents → only
+then compact) or the post-compact discipline (no rereads of pre-compact context; if the
+first turn after a compact still sits at ≥60% of the cap, recover by delegating or starting
+fresh from disk state instead of burning the window again).
+
+The same session closed the long-running stall investigation with debug-log evidence: the
+observed "runs a while, then goes silent" behaviour is UNIC-gateway/network streaming
+latency (repeated 30s slow-first-byte, one 300s byte-idle abort), not UKit hooks —
+hook-error cache empty, exec ledgers healthy. When a dead stream ends a turn early, the
+existing ≥2.3.3 Stop-hook completion gate blocks the premature stop, so staying current
+(`ukit update`) plus restarting stale sessions (hook config loads at session start) is the
+full remediation available in-repo; gateway-side idle/failover fixes belong upstream.
+
 ## 2.3.5 - 2026-09-10
 
 Source-audit hardening release: the code index cannot corrupt itself, and a corrupt runtime

package/package.json

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

package/templates/AGENTS.md

@@ -26,6 +26,14 @@
 - **Do NOT say "done", "applied", or "fixed" after Read/Grep/analysis alone.** Completion wording requires concrete Edit/Write evidence in the current turn, and verification when the scope is risky.
 - **Every stop says why — no silent idle.** When a turn ends because only the user can act (login, approval, protected-file edit), open the reply with one line naming the exact action: `WAITING ON YOU: <command/action>`, and schedule a one-shot wakeup (~20-30 min) when the harness provides one so the session re-checks and auto-continues once the user has acted. An ended turn cannot observe external/auth changes by itself, so without that line (and the wakeup) the idle session looks identical to a stall. Any error — failed command, hook, test, publish — is reported verbatim in the same turn, never silently retried past the user.
 
+## Long-Run Continuity
+
+Mirrors what UKit hooks inject at runtime on Claude Code and omp; on harnesses without hooks (Codex, OpenCode) this section is the only carrier — keep it in sync with `.claude/hooks/context-window-guard.sh`.
+
+- Near token-cap: **LAND one thing** — finish the smallest in-flight item end-to-end (edit + verify, ≤3 tool calls) and report it done. **DEFER the rest** — one line per remaining step into `docs/STATUS.md`, or split into bounded `docs/AI_HANDOFF/` tasks. **DELEGATE** broad work (searches, big reads, multi-file edits) to subagents whose tool output lives in their own windows. Only then compact.
+- After any compact or handoff: do not reread pre-compact context — continue from the persisted disk state, delegate broad work, keep replies short. If the first turn after a compact still sits at ≥60% of the cap, stop rereading immediately and recover by delegating or starting a fresh session from the disk state; do not burn the window again.
+- A run ends only on completion evidence, a genuine blocker, or a user-only action — and per the Execution Contract above, every such stop names its reason in the final reply.
+
 ## Index-First Loop
 
 For any task that needs code context:

package/templates/CLAUDE.md

@@ -26,6 +26,14 @@
 - **Do NOT say "done", "applied", or "fixed" after Read/Grep/analysis alone.** Completion wording requires concrete Edit/Write evidence in the current turn, and verification when the scope is risky.
 - **Every stop says why — no silent idle.** When a turn ends because only the user can act (login, approval, protected-file edit), open the reply with one line naming the exact action: `WAITING ON YOU: <command/action>`, and schedule a one-shot wakeup (~20-30 min) when the harness provides one so the session re-checks and auto-continues once the user has acted. An ended turn cannot observe external/auth changes by itself, so without that line (and the wakeup) the idle session looks identical to a stall. Any error — failed command, hook, test, publish — is reported verbatim in the same turn, never silently retried past the user.
 
+## Long-Run Continuity
+
+Mirrors what UKit hooks inject at runtime on Claude Code and omp; on harnesses without hooks (Codex, OpenCode) this section is the only carrier — keep it in sync with `.claude/hooks/context-window-guard.sh`.
+
+- Near token-cap: **LAND one thing** — finish the smallest in-flight item end-to-end (edit + verify, ≤3 tool calls) and report it done. **DEFER the rest** — one line per remaining step into `docs/STATUS.md`, or split into bounded `docs/AI_HANDOFF/` tasks. **DELEGATE** broad work (searches, big reads, multi-file edits) to subagents whose tool output lives in their own windows. Only then compact.
+- After any compact or handoff: do not reread pre-compact context — continue from the persisted disk state, delegate broad work, keep replies short. If the first turn after a compact still sits at ≥60% of the cap, stop rereading immediately and recover by delegating or starting a fresh session from the disk state; do not burn the window again.
+- A run ends only on completion evidence, a genuine blocker, or a user-only action — and per the Execution Contract above, every such stop names its reason in the final reply.
+
 ## Index-First Loop
 
 For any task that needs code context: