@ngockhoale/ukit 3.4.5 → 3.4.7

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to UKit are documented here.
 
+## 3.4.7 - 2026-10-01
+
+**Completion gate no longer demands an edit for read-only questions.** The
+skill router now stamps `routingContext.mutationOrder` (was the prompt a real
+mutation order?) and the Stop gate releases with a loud reason when a
+no-mutation prompt was misrouted into a write-debt mode — ending the
+Stop → "make an Edit" → AskUserQuestion → Stop loop on questions like
+"nút Excel gọi hàm nào?". A real edit attempt keeps the normal gate.
+
+## 3.4.6 - 2026-09-30
+
+Republish of 3.4.4 — npm staged-version E409 limbo (same content, version bump only; 3.4.5 hit the same wall).
 
 ## 3.4.4 - 2026-09-30
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.5",
+  "version": "3.4.7",
   "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/hooks/skill-router.sh

@@ -2837,6 +2837,13 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
       taskType: routingContext.taskType || null,
       intentMode: routingContext.intentMode || null,
       executionMode: routingContext.executionMode || null,
+      // The ONLY signal the Stop gate needs: was this prompt an actual mutation
+      // order? A misrouted "find the function that runs on click" question
+      // mints write-evidence debt the turn can never satisfy — the gate reads
+      // this flag to release read-only stops loud instead of demanding an edit.
+      ...(typeof routingContext.mutationOrder === 'boolean'
+        ? { mutationOrder: routingContext.mutationOrder }
+        : {}),
     };
   }
 
@@ -3507,6 +3514,10 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
       contextIntent: '',
       taskType: '',
       ...((informationalNoTargetPrompt || deliveryOnlyNoRoute) ? { executionMode: 'informational' } : {}),
+      // Read-only/carried contexts: stamp whether THIS prompt ordered a
+      // mutation so the Stop gate can release a misrouted write-debt instead
+      // of looping "make an Edit" on an answer-only question.
+      mutationOrder: promptText.trim() ? hasMutationOrder({ promptText, commandText }) : null,
     };
     const previousContext = await buildPreviousContextSnapshot({
       projectRoot,
@@ -3601,6 +3612,9 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     executionScores,
     executionCandidates,
     executionMode,
+    // Was this prompt a real mutation order? The Stop gate reads this to
+    // release read-only stops that were misrouted into a write-debt mode.
+    mutationOrder: hasMutationOrder({ promptText, commandText }),
   };
   const useIndexedContext = shouldUseIndexedContext({
     activeSkills: selected,

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

@@ -326,7 +326,14 @@ function hasUnfinishedCompletion(state = {}, ledger = {}) {
   if (!IMPLEMENT_MODES.has(mode)) return false;
   const required = requiredEvidence(state);
   if (required.length === 0) return false;
-  const unfinished = required.some((item) => !evidenceSatisfied(item, ledger, state));
+  // Read-only prompts misrouted into a mutating mode stamp
+  // routingContext.mutationOrder === false; their write-debt is a misroute, not
+  // unfinished work (see evaluateCompletion's 'no-mutation-order' valve).
+  const effectiveRequired = state?.routingContext?.mutationOrder === false
+    && ledger?.writeAttempted !== true
+    ? required.filter((item) => item !== 'write-evidence')
+    : required;
+  const unfinished = effectiveRequired.some((item) => !evidenceSatisfied(item, ledger, state));
   if (unfinished) return true;
   // TASK-009 (BL-011): a bug-fix route is also unfinished while its floor is
   // missing — the generic evidence alone never releases a bug fix.
@@ -2630,6 +2637,33 @@ export function evaluateCompletion({ state = {}, ledger = {}, cwd } = {}) {
     };
   }
 
+  // USER-REPORTED (2026-10-01): a read-only question can still be routed into a
+  // mutating mode (find-cause/local-fix) when the prompt mentions mutation or
+  // failure vocabulary as SUBJECT matter ("nút Excel gọi hàm nào?", "find the
+  // function that runs on click") — the router's question-shape heuristics
+  // miss it, and the gate then demands a write the turn can never honestly
+  // produce: Stop → "make an Edit" → AskUserQuestion → Stop. The router now
+  // stamps routingContext.mutationOrder (hasMutationOrder on the raw prompt);
+  // `false` means the request never ordered a mutation, so write-debt is a
+  // misroute, not unfinished work. `null`/absent keeps the pre-stamp
+  // conservative path (no release) — only a positively-computed false opens
+  // the valve, and only when no mutation was actually attempted (a real edit
+  // keeps the normal gate regardless of prompt wording).
+  const mutationOrder = state?.routingContext?.mutationOrder;
+  if (
+    mutationOrder === false
+    && missingEvidence.includes('write-evidence')
+    && !effectiveLedger.writeAttempted
+  ) {
+    return {
+      continue: false,
+      notify: true,
+      gateRelease: 'no-mutation-order',
+      missingEvidence,
+      reason: 'UKit completion gate released a read-only stop: this prompt ordered no mutation, so missing write-evidence is a misroute, not unfinished work. If an edit IS needed, re-send the task as an explicit change request.',
+    };
+  }
+
   const gated = IMPLEMENT_MODES.has(mode);
   if (!gated) {
     return {