@ngockhoale/ukit 2.3.1 → 2.3.2

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to UKit are documented here.
 
+## 2.3.2 - 2026-09-09
+
+Docs-contract release. "Every stop says why — no silent idle" is now a shipping Execution
+Contract rule, born from a real incident: a turn ended waiting for the user's `npm login`,
+the request sat at the bottom of a long report, the user did their part (created
+`~/.npmrc`), and the idle session looked exactly like a stall for 79 minutes.
+
+The new contract (identical in `CLAUDE.md` and `AGENTS.md`, parity-test enforced): when a
+turn ends only because the user must act (login, approval, protected-file edit), the reply
+opens with one line naming the exact action — `WAITING ON YOU: <command/action>` — and a
+one-shot wakeup (~20-30 min) is scheduled 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; without that line the idle session is indistinguishable
+from a stall. Companion rule: any error (failed command, hook, test, publish) is reported
+verbatim in the same turn, never silently retried past the user.
+
+Decision recorded in `docs/MEMORY.md` with the incident as the reason. Verified: all
+doc-referencing suites 298/298 (incl. the CLAUDE↔AGENTS parity test, which caught the
+first one-sided edit before it could ship), consistency 194/194.
+
 ## 2.3.1 - 2026-09-09
 
 "1 prompt mà đứng 10 lần" is fixed at the root. Four stall vectors in the completion

package/package.json

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

@@ -24,6 +24,7 @@
 - If routed state says `pull-indexed-context`, treat it as internal continuation — after the bounded read, **continue to edit/verify in the same turn** when safe.
 - If routed state shows `continuation required` or a stuck-lane rescue mode, finish the named milestone before widening reads or repeating analysis.
 - **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.
 
 ## Index-First Loop
 

package/templates/CLAUDE.md

@@ -24,6 +24,7 @@
 - If routed state says `pull-indexed-context`, treat it as internal continuation — after the bounded read, **continue to edit/verify in the same turn** when safe.
 - If routed state shows `continuation required` or a stuck-lane rescue mode, finish the named milestone before widening reads or repeating analysis.
 - **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.
 
 ## Index-First Loop