@ngockhoale/ukit 2.3.8 → 2.3.9

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to UKit are documented here.
 
+## 2.3.9 - 2026-09-10
+
+Freeze-sweep wave 5: fixes for completion-gate loops, worker-agent dead ends, and malformed
+context-cap configuration that could otherwise halt all mutation progress.
+
+**P1 — clean `find-cause` audits were forced into a Stop-hook loop.** A recommend-only
+investigation that found no actionable bug still required write and verification evidence, so
+the completion gate blocked the honest outcome and demanded a fabricated edit. The execution
+ledger now permits that narrow clean-audit outcome while retaining normal recovery blocks after
+a failed verification or incomplete mutation.
+
+**P1 — routed workers could wait for a user they cannot contact.** The Claude Code and omp
+`bug-debugger` / `feature-implementer` agents instructed workers to “ask the user” on unclear
+or non-reproducible work. They now perform one bounded next diagnostic step and return a
+structured `STATUS: BLOCKED` report with the exact missing artifact or decision to the parent
+agent, which owns user communication.
+
+**P1 — malformed context-cap configuration could brick mutations.** Invalid
+`compact.hardCapTokens` could collapse the cap to one token, invalid
+`hardCapGraceCalls` could eliminate the landing window, and wrong-shaped present
+`hardCapBlock` values could unexpectedly leave the hard gate enabled. The shared source/runtime
+threshold logic and Claude hook now accept only positive integer budgets, while malformed
+non-boolean `hardCapBlock` values fail open; the documented absent-key default remains enabled.
+The context-window advisory uses the same hard-cap validation. Regression coverage includes
+negative/zero/fraction/string/boolean/null budgets and malformed toggle values.
+
+Full suite: 81 files, 1,396 tests green.
+
 ## 2.3.8 - 2026-09-10
 
 Freeze-sweep wave 4: every fix in this release targets the "agent silently stops working"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.3.8",
+  "version": "2.3.9",
   "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/threshold.js

@@ -35,6 +35,15 @@ function finiteNumber(value, fallback = 0) {
   return Number.isFinite(number) ? number : fallback;
 }
 
+// A malformed hard cap must fail back to a safe ceiling, never collapse to one token and
+// brick every Edit/Write/Bash call. Unlike token estimates, configuration is an operator
+// contract: accept only whole positive token counts.
+function positiveInteger(value, fallback) {
+  return typeof value === 'number' && Number.isFinite(value) && Number.isInteger(value) && value > 0
+    ? value
+    : fallback;
+}
+
 function uniqueStrings(values) {
   const seen = new Set();
   const unique = [];
@@ -434,11 +443,15 @@ export function buildCompactThresholds(config = {}) {
   );
   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)));
+  // Keep the source mirror's config contract aligned with the installed runtime: malformed
+  // caps fall back to a safe ceiling rather than turning every mutation into an over-cap call.
+  const hardCapTokens = positiveInteger(config?.compact?.hardCapTokens, loadShippedCompactBudget().hardCapTokens);
 
   return {
     softThreshold,
     hardThreshold,
     baselineTokens,
+    hardCapTokens,
   };
 }
 

package/templates/.claude/agents/bug-debugger.md

@@ -18,7 +18,7 @@ Systematic debugging — understand before fixing.
 
 - Run the failing command/action.
 - Capture exact error message and stack trace.
-- If not reproducible → document conditions and ask user.
+- If not reproducible → document conditions, run the next most-discriminating bounded repro, then report any exact missing user-only artifact/permission to the parent agent. Never wait for or ask a user directly — you are a worker.
 
 ### 2. Trace Root Cause
 
@@ -83,4 +83,4 @@ Daily mode: skip. Handoff mode: set task status `pending_review` in `INDEX.md`;
   - non-trivial bug: `docs/MEMORY.md` + `docs/PROJECT.md` + `docs/CODE_MAP.md`
   - read `docs/WORKLOG.md` only recent relevant entries
 - Keep fix scope minimal — no drive-by refactors.
-- If root cause is unclear after 5 minutes of tracing → ask user for more context.
+- If root cause is unclear after 5 minutes of tracing → try one bounded alternative hypothesis/repro, then report precise evidence plus the smallest needed missing context to the parent agent. Never wait for or ask a user directly — the parent owns user communication.

package/templates/.claude/agents/feature-implementer.md

@@ -12,7 +12,9 @@ Implement requested behavior with minimal scope drift.
 - **Daily/ad-hoc mode** (DEFAULT): task didn't come from `docs/AI_HANDOFF/` → use the original lightweight workflow. Tests only when touched code already has coverage. No reviewer trigger.
 - **Handoff mode**: task file is `docs/AI_HANDOFF/tasks/TASK-xxx.md` OR user explicitly invokes handoff (e.g. "execute task TASK-001") → activate full Quality Gate: test-first → green → reviewer.
 
-If unsure which mode applies, ask the user. Don't apply Handoff mode rules to a quick one-off fix.
+If unsure which mode applies, default to Daily/ad-hoc mode unless the task path or prompt
+explicitly selects Handoff. Do not ask a user — you are a worker; report the ambiguity and
+reasoning to the parent agent so it can decide whether to re-route.
 
 **In Handoff mode you are running unattended — ask nothing.** You were spawned by an
 orchestrator driving a pipeline; there is no human in your conversation to answer, and a
@@ -33,7 +35,7 @@ and even then, report it, don't ask about it.
   - non-trivial: `docs/MEMORY.md` + `docs/PROJECT.md` + `docs/CODE_MAP.md`
 - Identify target files and existing patterns.
 - If task came from handoff, read `tasks/TASK-xxx.md` and locate its **Test Plan** + **Verification Commands**.
-- Daily mode: if confidence is low or risk is high, ask one short clarifying question before deeper analysis. Handoff mode: do not ask — decide and record the decision (see above).
+- Daily mode: if confidence is low or risk is high, inspect the next bounded source/context signal and hand back a concise `STATUS: BLOCKED` report with the exact missing decision or artifact if confidence remains low. Do not ask a user directly. Handoff mode: do not ask — decide and record the decision (see above).
 
 ### 2. Plan Approach (< 1 minute)
 
@@ -44,7 +46,7 @@ and even then, report it, don't ask about it.
 
 - Write the test(s) from §2 / from task Test Plan.
 - Run them: must FAIL for the expected reason. Capture output.
-- If test passes immediately → test is wrong or behavior already exists. Fix the test or stop and report.
+- If test passes immediately → test is wrong or behavior already exists. Fix the test; if the intended behavior cannot be inferred, hand back `STATUS: BLOCKED` with the observed behavior and the smallest decision the parent must resolve. Never silently stop.
 - **Daily mode**: skip this step unless touched code already has tests (then follow original rule).
 
 

package/templates/.claude/hooks/context-hardcap-gate.sh

@@ -96,7 +96,12 @@ function readRunCursor() {
       ? payload.session_id.trim()
       : undefined,
   };
-  if (config?.compact?.hardCapBlock === false) {
+  // This is a liveness backstop, not a security control. A present value with the wrong
+  // JSON shape must never leave the gate unexpectedly enabled and brick every mutation once
+  // the cap is reached. Only an explicitly configured boolean `true` enables the gate;
+  // missing preserves the documented default-on behavior for existing installations.
+  const rawHardCapBlock = config?.compact?.hardCapBlock;
+  if (rawHardCapBlock === false || (rawHardCapBlock !== undefined && typeof rawHardCapBlock !== 'boolean')) {
     process.exit(0);
     return;
   }
@@ -175,8 +180,15 @@ function readRunCursor() {
   }
   const resumable = run || ordinaryTask;
   if (resumable) {
-    const graceCalls = Number.isFinite(config?.compact?.hardCapGraceCalls)
-      ? config.compact.hardCapGraceCalls
+    // Invalid config must not turn the landing allowance negative/zero (which makes every
+    // unfinished run hard-block immediately). This hook is a liveness backstop, so malformed
+    // values deliberately fall back to the documented default rather than fail closed.
+    const configuredGraceCalls = config?.compact?.hardCapGraceCalls;
+    const graceCalls = typeof configuredGraceCalls === 'number'
+      && Number.isFinite(configuredGraceCalls)
+      && Number.isInteger(configuredGraceCalls)
+      && configuredGraceCalls > 0
+      ? configuredGraceCalls
       : 10;
 
     let slots = readSlots();

package/templates/.claude/hooks/context-window-guard.sh

@@ -73,7 +73,7 @@ function loadHardCap() {
   try {
     const raw = fs.readFileSync(path.join(projectRoot, '.ukit', 'storage', 'config.json'), 'utf8');
     const value = JSON.parse(raw)?.compact?.hardCapTokens;
-    if (Number.isFinite(value) && value > 0) return value;
+    if (typeof value === 'number' && Number.isFinite(value) && Number.isInteger(value) && value > 0) return value;
   } catch { /* fall through to the default */ }
   return 500_000;
 }

package/templates/.claude/ukit/runtime/compact-threshold.mjs

@@ -43,6 +43,15 @@ function finiteNumber(value, fallback = 0) {
   return Number.isFinite(number) ? number : fallback;
 }
 
+// A malformed hard cap must fail back to a safe ceiling, never collapse to one token and
+// brick every Edit/Write/Bash call. Unlike token estimates, configuration is an operator
+// contract: accept only whole positive token counts.
+function positiveInteger(value, fallback) {
+  return typeof value === 'number' && Number.isFinite(value) && Number.isInteger(value) && value > 0
+    ? value
+    : fallback;
+}
+
 function uniqueStrings(values) {
   const seen = new Set();
   const unique = [];
@@ -452,7 +461,7 @@ export function buildCompactThresholds(config = {}) {
   // 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));
+  const hardCapTokens = positiveInteger(config?.compact?.hardCapTokens, 500_000);
 
   return {
     softThreshold,

package/templates/.claude/ukit/runtime/execution-ledger.mjs

@@ -513,6 +513,28 @@ export function evaluateCompletion({ state = {}, ledger = {} } = {}) {
     return { continue: false, notify: false, missingEvidence: [] };
   }
 
+  // `find-cause` can validly end clean: an investigation may establish that no actionable
+  // defect exists. Its contract says a FIX cannot be claimed without write + verification;
+  // it does not make a mutation mandatory. Treating missing evidence as an unconditional
+  // command to edit made a clean audit self-block forever (Stop -> "make an Edit" -> no
+  // honest edit exists -> Stop again). Once a mutation was attempted, retain the normal
+  // recovery gate — only a no-mutation, recommend-only investigation that has not already
+  // observed a failed verification gets this release valve. A route that named an actionable
+  // command, or a failing check, has concrete unfinished work and must keep recovering.
+  if (
+    mode === 'find-cause'
+    && routeSummary.policyMode === 'recommend-only'
+    && !effectiveLedger.writeAttempted
+    && !effectiveLedger.verificationFailed
+  ) {
+    return {
+      continue: false,
+      notify: true,
+      missingEvidence,
+      reason: 'UKit investigation ended without a mutation. A clean audit is valid; report whether no actionable defect was found or a concrete blocker remains. Do not claim a bug was fixed without write and verification evidence.',
+    };
+  }
+
   const gated = IMPLEMENT_MODES.has(mode);
   if (!gated) {
     return {

package/templates/.omp/agents/bug-debugger.md

@@ -17,7 +17,7 @@ Systematic debugging — understand before fixing.
 
 - Run the failing command/action.
 - Capture exact error message and stack trace.
-- If not reproducible → document conditions and ask user.
+- If not reproducible → document conditions, run the next most-discriminating bounded repro, then report any exact missing user-only artifact/permission to the parent agent. Never wait for or ask a user directly — you are a worker.
 
 ### 2. Trace Root Cause
 
@@ -82,4 +82,4 @@ Daily mode: skip. Handoff mode: set task status `pending_review` in `INDEX.md`;
   - non-trivial bug: `docs/MEMORY.md` + `docs/PROJECT.md` + `docs/CODE_MAP.md`
   - read `docs/WORKLOG.md` only recent relevant entries
 - Keep fix scope minimal — no drive-by refactors.
-- If root cause is unclear after 5 minutes of tracing → ask user for more context.
+- If root cause is unclear after 5 minutes of tracing → try one bounded alternative hypothesis/repro, then report precise evidence plus the smallest needed missing context to the parent agent. Never wait for or ask a user directly — the parent owns user communication.

package/templates/.omp/agents/feature-implementer.md

@@ -11,7 +11,9 @@ Implement requested behavior with minimal scope drift.
 - **Daily/ad-hoc mode** (DEFAULT): task didn't come from `docs/AI_HANDOFF/` → use the original lightweight workflow. Tests only when touched code already has coverage. No reviewer trigger.
 - **Handoff mode**: task file is `docs/AI_HANDOFF/tasks/TASK-xxx.md` OR user explicitly invokes handoff (e.g. "execute task TASK-001") → activate full Quality Gate: test-first → green → reviewer.
 
-If unsure which mode applies, ask the user. Don't apply Handoff mode rules to a quick one-off fix.
+If unsure which mode applies, default to Daily/ad-hoc mode unless the task path or prompt
+explicitly selects Handoff. Do not ask a user — you are a worker; report the ambiguity and
+reasoning to the parent agent so it can decide whether to re-route.
 
 **In Handoff mode you are running unattended — ask nothing.** You were spawned by an
 orchestrator driving a pipeline; there is no human in your conversation to answer, and a
@@ -32,7 +34,7 @@ and even then, report it, don't ask about it.
   - non-trivial: `docs/MEMORY.md` + `docs/PROJECT.md` + `docs/CODE_MAP.md`
 - Identify target files and existing patterns.
 - If task came from handoff, read `tasks/TASK-xxx.md` and locate its **Test Plan** + **Verification Commands**.
-- Daily mode: if confidence is low or risk is high, ask one short clarifying question before deeper analysis. Handoff mode: do not ask — decide and record the decision (see above).
+- Daily mode: if confidence is low or risk is high, inspect the next bounded source/context signal and hand back a concise `STATUS: BLOCKED` report with the exact missing decision or artifact if confidence remains low. Do not ask a user directly. Handoff mode: do not ask — decide and record the decision (see above).
 
 ### 2. Plan Approach (< 1 minute)
 
@@ -43,7 +45,7 @@ and even then, report it, don't ask about it.
 
 - Write the test(s) from §2 / from task Test Plan.
 - Run them: must FAIL for the expected reason. Capture output.
-- If test passes immediately → test is wrong or behavior already exists. Fix the test or stop and report.
+- If test passes immediately → test is wrong or behavior already exists. Fix the test; if the intended behavior cannot be inferred, hand back `STATUS: BLOCKED` with the observed behavior and the smallest decision the parent must resolve. Never silently stop.
 - **Daily mode**: skip this step unless touched code already has tests (then follow original rule).