@ngockhoale/ukit 2.3.21 → 2.3.23

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 All notable changes to UKit are documented here.
 
+## 2.3.23 - 2026-09-13
+
+Self-install no longer clobbers UKit's own canonical docs. Running `ukit install` inside the UKit
+source repository (e.g. the global CLI invoked from the repo) overwrote `docs/PROMPT_CACHING.md` —
+the canonical 368-line ruleset — with the distilled 127-line copy shipped under `templates/docs/`,
+because the manifest item is `overwrite_with_backup` and self-install went undetected.
+
+- **Self-install detection.** `buildInstallPlan` now recognizes an install targeting the UKit repo
+  by two independent signals: the templates resolving inside the install target (the repo has a
+  `templates/` directory, the global CLI does not), or the target `package.json` naming
+  `@ngockhoale/ukit`. This covers the common case where the global CLI runs inside the repo, which
+  the path-containment check alone misses.
+- **Docs downgraded to seed-only.** On a detected self-install, every `overwrite_with_backup`
+  entry whose target lives under `docs/` is downgraded to `skip`: a missing doc is seeded, but an
+  existing canonical doc is never overwritten. Downstream projects are unaffected — their docs
+  refresh on `ukit update` as before.
+- **Verification.** New `buildInstallPlan` regressions cover the containment signal, the
+  package-name signal, and the unchanged downstream path; the full suite stays green.
+
+## 2.3.22 - 2026-09-13
+
+Consultation-question routing fix — pure questions no longer fabricate mutation debt that the
+completion gate then enforces against an answer turn. Observed live the same day: two Vietnamese
+consultation questions (no English signal word, no target file) scored every candidate mode ≤ 0,
+the mode ladder's upward bias resolved the find-cause/shared-edit tie to `shared-edit`, and the
+gate blocked the answer turn six times ("missing write-evidence / verification-evidence") until
+the continuation cap released it.
+
+- **Consultation questions carry no completion contract.** A question-shaped prompt (trailing `?`,
+  a leading English or ASCII-folded Vietnamese interrogative, or a `là gì / được không` tail) with
+  no implement/review/debug/failure/impact signal and no target file routes `informational` — the
+  same no-mutation-debt lane delivery-only requests already use. Applied to
+  `src/index/taskRouting.js`, the standalone router `route-task.mjs`, and the hook-embedded
+  routing copy in `skill-router.sh` (live twins byte-identical).
+- **Leading interrogatives override action words.** The router's signal regexes are English-only,
+  so Vietnamese how-questions mentioning an action ("Làm sao mà đo được khi tôi cài hệ thống
+  này…?") kept a mutation contract. A leading interrogative (làm sao / thế nào / tại sao / phải
+  làm gì / …) now marks the prompt consultative even when it contains implement verbs
+  (sửa / thêm / cài / cài đặt / …) — asking HOW something is done is not ordering the action
+  performed. Question-phrased edit orders ("bạn sửa giúp tôi… không?") keep their write contract.
+- **Verification.** New routing regressions lock the two incident prompts to `informational` with
+  empty contract evidence, and lock both guard directions (English signal-word questions and
+  question-phrased Vietnamese edit orders stay in their lanes); full suite green.
+
 ## 2.3.21 - 2026-09-13
 
 C16 release — the prompt-caching ruleset turns from research into shipped guidance, and the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.3.21",
+  "version": "2.3.23",
   "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/buildPlan.js

@@ -2,6 +2,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { selectManifestItems } from '../manifest/selectItems.js';
 import { renderTemplateString } from '../render/renderTemplate.js';
+import { UKIT_PACKAGE_NAME } from './update.js';
 
 const BINARY_TEMPLATE_EXTENSIONS = new Set([
   '.ttf',
@@ -44,6 +45,52 @@ function safeResolve(basePath, relativePath) {
   return resolvedPath;
 }
 
+function isPathInside(parentPath, childPath) {
+  const relative = path.relative(parentPath, childPath);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function isDocsTarget(targetPath, projectRoot) {
+  const relative = path.relative(projectRoot, targetPath);
+  return relative === 'docs' || relative.startsWith(`docs${path.sep}`);
+}
+
+// Detect `ukit install` running against the UKit source repository itself. Two independent
+// signals: the templates resolve inside the install target (the repo has a templates/ dir, the
+// global CLI does not), or the target's package.json declares UKIT_PACKAGE_NAME (the path check
+// misses the common case where the global CLI runs inside the repo).
+async function isSelfInstall({ templatesRoot, projectRoot }) {
+  if (isPathInside(projectRoot, templatesRoot)) {
+    return true;
+  }
+  try {
+    const raw = await fs.readFile(path.join(projectRoot, 'package.json'), 'utf8');
+    return JSON.parse(raw)?.name === UKIT_PACKAGE_NAME;
+  } catch {
+    return false;
+  }
+}
+
+// In the UKit source repo, docs/ holds canonical sources that deliberately diverge from the
+// shipped copies under templates/ (docs/PROMPT_CACHING.md is the full ruleset while
+// templates/docs/ ships a distilled version). The refresh-on-update strategy would silently
+// clobber those canonical files, so downgrade docs overwrites to skip: seed a missing doc, but
+// never overwrite one that already exists.
+async function downgradeSelfInstallDocOverwrites(planEntries, { templatesRoot, projectRoot }) {
+  if (!(await isSelfInstall({ templatesRoot, projectRoot }))) {
+    return;
+  }
+
+  for (const entry of planEntries) {
+    if (entry.type === 'link' || entry.mergeStrategy !== 'overwrite_with_backup') {
+      continue;
+    }
+    if (isDocsTarget(entry.targetPath, projectRoot)) {
+      entry.mergeStrategy = 'skip';
+    }
+  }
+}
+
 async function readTemplateFile(filePath, { binary = false } = {}) {
   if (binary) {
     return fs.readFile(filePath);
@@ -263,6 +310,8 @@ export async function buildInstallPlan({
     }
   }
 
+  await downgradeSelfInstallDocOverwrites(planEntries, { templatesRoot, projectRoot });
+
   return {
     selectedItems,
     entries: planEntries,

package/src/index/taskRouting.js

@@ -452,6 +452,47 @@ function deriveExecutionMode({
     && !scores.smallFixSignal
     && !scores.sharedRisk
     && !targetFile;
+  // A pure consultation question ("Rồi việc kế tiếp của tôi phải làm gì…?", "how do I
+  // measure this on another machine?") asks for an answer, not a repository change. The
+  // signal regexes are English-only, so a Vietnamese (or signal-free English) question
+  // with no target file scores every candidate mode ≤ 0 and the ladder's upward bias
+  // resolves the 0-score find-cause/shared-edit tie to shared-edit — fabricating
+  // write+verification debt that a text answer can never satisfy, after which the
+  // completion gate blocks the answer turn until the continuation cap releases it.
+  // Consultation questions carry no completion contract instead. A question that also
+  // carries an implement/review/debug/failure signal keeps its lane; targeted questions
+  // (explicit file target) keep their contract so a Vietnamese edit order against a
+  // named file stays enforced.
+  const trimmedPromptText = String(promptText || '').trim();
+  const foldedPromptText = trimmedPromptText
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/\u0111/g, 'd');
+  const leadingInterrogative = /^(?:what|how|which|when|where|who)\b/.test(foldedPromptText)
+    || /^(?:lam sao|the nao|nhu the nao|nhu nao|vi sao|tai sao|khi nao|bao gio|bao nhieu|o dau|phai lam gi|lam gi|lam cach nao)\b/.test(foldedPromptText);
+  const questionShapedPrompt = /\?\s*$/.test(trimmedPromptText)
+    || leadingInterrogative
+    || /\b(?:la gi|duoc khong)\s*$/.test(foldedPromptText);
+  // Implement verbs (Vietnamese included — the English-only scores above cannot see
+  // them) mark an action order even when phrased as a question ("ban sua giup toi…?" is
+  // an edit order, not a consultation). A leading interrogative overrides them:
+  // "Lam sao ma do duoc khi toi cai…?" asks HOW something is done, it does not order
+  // the action performed.
+  const consultationImplementWords = /(?<![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|sửa|thêm|tạo|xóa|đổi|thay thế|cập nhật|viết|chạy|cài)(?![A-Za-z0-9_])/.test(trimmedPromptText);
+  const consultationOnlySignal = questionShapedPrompt
+    && (leadingInterrogative || !consultationImplementWords)
+    && scores.editCertainty === 0
+    && !scores.implementSignal
+    && !scores.reviewSignal
+    && !scores.debugSignal
+    && !scores.failureSignal
+    && !scores.impactSignal
+    && !scores.buildSignal
+    && !scores.directTransformSignal
+    && !scores.smallFixSignal
+    && !scores.sharedRisk
+    && !targetFile;
 
   if (
     releaseVerificationContinuation
@@ -460,7 +501,7 @@ function deriveExecutionMode({
     return 'review-release';
   }
 
-  if (deliveryOnlySignal) {
+  if (deliveryOnlySignal || consultationOnlySignal) {
     return 'informational';
   }
 

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

@@ -1652,7 +1652,38 @@ const { pathToFileURL } = require('url');
       return 'review-release';
     }
 
-    if (deliveryOnlySignal) {
+    const trimmedPromptText = String(promptText || '').trim();
+    const foldedPromptText = trimmedPromptText
+      .toLowerCase()
+      .normalize('NFD')
+      .replace(/[\u0300-\u036f]/g, '')
+      .replace(/\u0111/g, 'd');
+    const leadingInterrogative = /^(?:what|how|which|when|where|who)\b/.test(foldedPromptText)
+      || /^(?:lam sao|the nao|nhu the nao|nhu nao|vi sao|tai sao|khi nao|bao gio|bao nhieu|o dau|phai lam gi|lam gi|lam cach nao)\b/.test(foldedPromptText);
+    const questionShapedPrompt = /\?\s*$/.test(trimmedPromptText)
+      || leadingInterrogative
+      || /\b(?:la gi|duoc khong)\s*$/.test(foldedPromptText);
+    // Implement verbs (Vietnamese included — the English-only scores above cannot see
+    // them) mark an action order even when phrased as a question ("ban sua giup toi…?" is
+    // an edit order, not a consultation). A leading interrogative overrides them:
+    // "Lam sao ma do duoc khi toi cai…?" asks HOW something is done, it does not order
+    // the action performed.
+    const consultationImplementWords = /(?<![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|sửa|thêm|tạo|xóa|đổi|thay thế|cập nhật|viết|chạy|cài)(?![A-Za-z0-9_])/.test(trimmedPromptText);
+    const consultationOnlySignal = questionShapedPrompt
+      && (leadingInterrogative || !consultationImplementWords)
+      && scores.editCertainty === 0
+      && !scores.implementSignal
+      && !scores.reviewSignal
+      && !scores.debugSignal
+      && !scores.failureSignal
+      && !scores.impactSignal
+      && !scores.buildSignal
+      && !scores.directTransformSignal
+      && !scores.smallFixSignal
+      && !scores.sharedRisk
+      && !targetFile;
+    
+    if (deliveryOnlySignal || consultationOnlySignal) {
       return 'informational';
     }
 

package/templates/.claude/ukit/index/route-task.mjs

@@ -1832,7 +1832,38 @@ function deriveExecutionMode({
     return 'review-release';
   }
 
-  if (deliveryOnlySignal) {
+  const trimmedPromptText = String(promptText || '').trim();
+  const foldedPromptText = trimmedPromptText
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/\u0111/g, 'd');
+  const leadingInterrogative = /^(?:what|how|which|when|where|who)\b/.test(foldedPromptText)
+    || /^(?:lam sao|the nao|nhu the nao|nhu nao|vi sao|tai sao|khi nao|bao gio|bao nhieu|o dau|phai lam gi|lam gi|lam cach nao)\b/.test(foldedPromptText);
+  const questionShapedPrompt = /\?\s*$/.test(trimmedPromptText)
+    || leadingInterrogative
+    || /\b(?:la gi|duoc khong)\s*$/.test(foldedPromptText);
+  // Implement verbs (Vietnamese included — the English-only scores above cannot see
+  // them) mark an action order even when phrased as a question ("ban sua giup toi…?" is
+  // an edit order, not a consultation). A leading interrogative overrides them:
+  // "Lam sao ma do duoc khi toi cai…?" asks HOW something is done, it does not order
+  // the action performed.
+  const consultationImplementWords = /(?<![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|sửa|thêm|tạo|xóa|đổi|thay thế|cập nhật|viết|chạy|cài)(?![A-Za-z0-9_])/.test(trimmedPromptText);
+  const consultationOnlySignal = questionShapedPrompt
+    && (leadingInterrogative || !consultationImplementWords)
+    && scores.editCertainty === 0
+    && !scores.implementSignal
+    && !scores.reviewSignal
+    && !scores.debugSignal
+    && !scores.failureSignal
+    && !scores.impactSignal
+    && !scores.buildSignal
+    && !scores.directTransformSignal
+    && !scores.smallFixSignal
+    && !scores.sharedRisk
+    && !targetFile;
+  
+  if (deliveryOnlySignal || consultationOnlySignal) {
     return 'informational';
   }