@ngockhoale/ukit 3.4.9 → 3.4.11

package/CHANGELOG.md

@@ -2,9 +2,18 @@
 
 All notable changes to UKit are documented here.
 
+## 3.4.10 - 2026-10-01
+
+**sensitive-data-guard reads .env placeholders.** `classifySecretFile` now
+exempts every dotenv name carrying a distributable marker
+(`example|examples|sample|template|dist`) — `.env.example.local`,
+`.env.production.example`, `.env.sample`, `.env.dist`, `.env.template`
+alongside the old `.env.example` — for Read/Grep and Bash lanes alike.
+Real env files (`.env`, `.env.local`, `.env.production`) stay blocked.
+
 ## 3.4.8 - 2026-10-01
 
-(Also republishes 3.4.7 — npm staged-version E409 limbo.)
+(3.4.7 and 3.4.9 were lost to npm staged-version E409 limbo; 3.4.8 landed and its `latest` tag was assigned via `npm dist-tag`.)
 
 
 **Completion gate no longer demands an edit for read-only questions.** The

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.9",
+  "version": "3.4.11",
   "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/sensitive-data-guard.mjs

@@ -201,7 +201,14 @@ async function evaluate({ rawInput, projectRoot, env }) {
     const rawBase = normalized.split('/').pop();
     if (!rawBase) return null;
     const base = rawBase.toLowerCase();
-    if (base.endsWith('.env.example')) return null;
+    // .env* placeholders that carry no secrets by convention: any dotenv file
+    // whose basename marks it a non-secret distributable — .env.example,
+    // .env.example.local, .env.examples, .env.sample, .env.dist,
+    // .env.template, .env.dev.example. The marker must appear after the
+    // '.env' prefix so a real env file can never dodge by containing the word
+    // earlier (there is nothing before '.env' in the basename anyway — the
+    // check is anchored on the dotenv name itself).
+    if (/^\.env[._-]?.*\b(example|examples|sample|template|dist)\b/i.test(base)) return null;
     if (base === '.env' || base.startsWith('.env.')) return 'dotenv/secret env file';
     if (base.endsWith('.pub') || base.endsWith('.public')) return null;
     if (/^id_(rsa|dsa|ecdsa|ed25519)(\.|$)/.test(base)) return 'SSH private key';

package/template_project/.claude/hooks/skill-router.sh

@@ -2157,6 +2157,32 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     return /(?<![A-Za-z0-9_])(?:implement|apply|update|modify|add|create|ship|deliver|fix|refactor|remove|delete|rename|change|write|build|make|install|run|deploy|execute|edit|sua|them|tao|xoa|doi|thay\s+the|cap\s+nhat|viet|chay|cai|chinh|trien\s+khai|cau\s+hinh)(?![A-Za-z0-9_])/.test(residue);
   }
 
+  // USER-REPORTED (2026-10-01): "chỉ lên plan cho tôi" / "just plan it" asks
+  // for a plan and nothing more — the deliverable is a document in the reply,
+  // not a mutation. mutationOrder=false alone does NOT cover these: they name
+  // files and future work, so the router lands them on local-build/local-fix,
+  // mints write debt, and the gate forces an implement the user never asked
+  // for. Plan-only = explicit plan-request signal AND no surviving mutation
+  // order ("lên plan rồi sửa luôn" is an implement request, not plan-only).
+  function isPlanOnlyRequest({ promptText = '', commandText = '' } = {}) {
+    const folded = `${promptText ?? ''}\n${commandText ?? ''}`
+      .toLowerCase()
+      .normalize('NFD')
+      .replace(/[\u0300-\u036f]/g, '')
+      .replace(/\u0111/g, 'd');
+    const trimmed = folded.trim();
+    if (!trimmed) return false;
+    const planSignal =
+      /\b(?:chi|just|only)\s+(?:len|lap|vach|lam)\b[^.,;\n]{0,40}\b(?:plan|ke\s+hoach|phuong\s+an|lo\s+trinh|roadmap|blueprint)\b/.test(trimmed)
+      || /\b(?:len|lap|vach|de\s+xuat|draft)\s+(?:ke\s+hoach|plan|phuong\s+an|lo\s+trinh|roadmap)\b/.test(trimmed)
+      || /\b(?:plan|planning)\s+(?:only|first|mode)\b/.test(trimmed)
+      || /\b(?:ke\s+hoach|plan|phuong\s+an|lo\s+trinh|roadmap)\b[^.,;\n]{0,40}\b(?:khong|chua|khong\s+can)\s+(?:implement|code|thuc\s+hien|thuc\s+thi|sua|lam|build|viet)\b/.test(trimmed)
+      || (/\b(?:khong|chua|dung)\s+(?:implement|code|thuc\s+hien|thuc\s+thi|sua|lam|viet\s+code)\b/.test(trimmed)
+        && /\b(?:plan|ke\s+hoach|phuong\s+an|roadmap)\b/.test(trimmed));
+    if (!planSignal) return false;
+    return !hasMutationOrder({ promptText, commandText });
+  }
+
   function deriveExecutionMode({
     promptText = '',
     commandText = '',
@@ -2844,7 +2870,9 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
       ...(typeof routingContext.mutationOrder === 'boolean'
         ? { mutationOrder: routingContext.mutationOrder }
         : {}),
-    };
+      ...(typeof routingContext.planOnly === 'boolean'
+        ? { planOnly: routingContext.planOnly }
+        : {}),
   }
 
   function compactHelpers({
@@ -3518,6 +3546,7 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
       // 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,
+      planOnly: promptText.trim() ? isPlanOnlyRequest({ promptText, commandText }) : null,
     };
     const previousContext = await buildPreviousContextSnapshot({
       projectRoot,
@@ -3615,6 +3644,9 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     // 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 }),
+    // User-requested default-answer posture: a prompt that only wants a
+    // plan/answer releases the gate even on a mutating route.
+    planOnly: isPlanOnlyRequest({ promptText, commandText }),
   };
   const useIndexedContext = shouldUseIndexedContext({
     activeSkills: selected,

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

@@ -326,12 +326,15 @@ function hasUnfinishedCompletion(state = {}, ledger = {}) {
   if (!IMPLEMENT_MODES.has(mode)) return false;
   const required = requiredEvidence(state);
   if (required.length === 0) return false;
-  // 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')
+  // USER-REPORTED (2026-10-01): default posture is answer/plan/review — a
+  // prompt that never ordered a mutation, or an explicit plan-only request,
+  // must not mint unfinished write/verification debt even when it was
+  // misrouted into a mutating mode (see evaluateCompletion's
+  // 'no-mutation-order' valve). A real edit attempt keeps the debt.
+  const readOnlyPrompt = state?.routingContext?.mutationOrder === false
+    || state?.routingContext?.planOnly === true;
+  const effectiveRequired = readOnlyPrompt && ledger?.writeAttempted !== true
+    ? required.filter((item) => item !== 'write-evidence' && item !== 'verification-evidence')
     : required;
   const unfinished = effectiveRequired.some((item) => !evidenceSatisfied(item, ledger, state));
   if (unfinished) return true;
@@ -2637,30 +2640,29 @@ 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;
+  // USER-REPORTED (2026-10-01): the default posture is answer/plan/review —
+  // "chỉ lên plan", "trả lời cho tôi", "xem lại plan" carry no mutation order
+  // and the turn's deliverable is the reply itself. Two stamped signals cover
+  // it: routingContext.mutationOrder === false (no imperative verb survived
+  // the clause strips) or routingContext.planOnly === true (explicit
+  // plan-request wording). When either holds, write-evidence AND
+  // verification-evidence debt from a misrouted mutating lane are
+  // misroutes, not unfinished work — release loud so the stop names why it
+  // is allowed. `null`/absent stays conservative; an actual edit attempt
+  // (writeAttempted) keeps the normal gate regardless of prompt wording.
+  const readOnlyPrompt = state?.routingContext?.mutationOrder === false
+    || state?.routingContext?.planOnly === true;
   if (
-    mutationOrder === false
-    && missingEvidence.includes('write-evidence')
+    readOnlyPrompt
     && !effectiveLedger.writeAttempted
+    && missingEvidence.some((item) => item === 'write-evidence' || item === 'verification-evidence')
   ) {
     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.',
+      reason: 'UKit completion gate released a read-only stop: this prompt asked for an answer or a plan, not a change, so missing write/verification evidence is a misroute, not unfinished work. To implement, re-send the task as an explicit change request ("implement", "sửa", "làm luôn", "execute this plan").',
     };
   }