@ngockhoale/ukit 3.4.14 → 3.4.15

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to UKit are documented here.
 
+## 3.4.15 - 2026-10-05
+
+**Hook chain no longer masks a real gate block (stops blind-retry token burn).**
+When a mid-chain gate exited 2 with its own reason (e.g. `handoff-model-guard.sh`:
+`PLAN.md has no valid PLANNER_MODEL`), `hook-chain-runner.mjs` treated the unrun later gate
+as "chain broke before fail-closed gate(s) ran: context-hardcap-gate.sh" and discarded the
+real reason. Agents (notably `handoff-planner`) could not tell what to fix and were respawned
+repeatedly. A completed exit-2 gate is now the verdict: its stderr/systemMessage is surfaced
+and later gates stay unrun. Infra failures (timeout/signal/budget) still fail closed with the
+"chain broke" message. Regression test in `tests/hooks/hookChainFailureSurface.test.js`.
+
 ## 3.4.14 - 2026-10-04
 
 **New `advisor-plan` skill, a create-session write-scope guard, and a deliberate-future queue contract.**

package/package.json

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

package/template_project/.claude/ukit/runtime/hook-chain-runner.mjs

@@ -386,7 +386,16 @@ async function run(payloadText, scriptArgs, { chainMarker = true, decisionShortC
   // ... unless this break WAS the decision: a decision owns the verdict, so the
   // unrun gates are not a fail-closed gap (SPEC §FR-001 — the verdict must stay
   // exit 0 with the decision JSON).
-  const skippedFailClosed = !decisionEmitted && scriptPaths
+  // ... and unless the break was a REAL block: a script that ran to completion and
+  // exited 2 (e.g. handoff-model-guard: exit 2 + systemMessage, no decision JSON) is
+  // itself the verdict. Reporting "chain broke before <later gate>" instead hides the
+  // actual reason, so the agent cannot fix it and retries blind (token burn).
+  const brokeAt = results[results.length - 1];
+  const realBlock = Boolean(brokeAt)
+    && brokeAt.code === 2
+    && brokeAt.failureKind === 'exit-code'
+    && !brokeAt.killed;
+  const skippedFailClosed = !decisionEmitted && !realBlock && scriptPaths
     .slice(results.length)
     .some((p) => FAIL_CLOSED_SCRIPTS.has(failClosedName(p)));