@ngockhoale/ukit 2.3.22 → 2.3.24

package/CHANGELOG.md

@@ -2,6 +2,59 @@
 
 All notable changes to UKit are documented here.
 
+## 2.3.24 - 2026-09-13
+
+Post-2.3.23 routing and self-install audit. Two real defects fixed, plus the repo-local
+Release Policy mirror restored and guarded.
+
+- **`isInformationalPrompt` ported into the src canonical copy.** `src/index/taskRouting.js`
+  was missing the informational-prompt guard that the shipped copies in
+  `templates/.claude/ukit/index/route-task.mjs` and `templates/.claude/hooks/skill-router.sh`
+  received in 2.2.14. The 2.3.22 `consultationOnlySignal` only catches question-shaped
+  prompts (trailing `?`, a leading interrogative, or Vietnamese `…là gì / được không`), so a
+  prompt with an **embedded** interrogative and no leading marker — `"please tell me what the
+  auth module does"`, `"explain what files the installer writes"` — routed to `shared-edit`
+  with a write+verification contract in src while the shipped templates routed it
+  `informational`. That is exactly the fabricated-mutation-debt class 2.3.22 set out to fix,
+  still live in the copy that drives `ukit index route`. The helper is now byte-equivalent
+  across all three copies; implement/debug-worded questions still keep their lanes. Locked by
+  a new `tests/index/taskRouting.test.js` regression (verified RED without the call site).
+- **Self-install detection no longer misfires on a local install.** The 2.3.23 guard treated
+  any `templates/` directory inside the install root as a self-install. A downstream project
+  that installs UKit locally (`node_modules/@ngockhoale/ukit/templates`) therefore matched,
+  and every `docs/` entry was downgraded to `skip` — so `ukit update` silently stopped
+  refreshing that project's docs. `isSelfInstall` now requires the package root itself to be
+  the project root (`<projectRoot>/templates` exactly) or the target `package.json` to name
+  `@ngockhoale/ukit`. Locked by a new `buildPlan` regression for the `node_modules` shape
+  (verified RED under the old containment test).
+- **Release Policy mirror restored.** A `ukit install` run inside this repo (self-install)
+  had overwritten root `CLAUDE.md`/`AGENTS.md` from `templates/`, wiping the repo-local
+  Release Policy section that `docs/PROJECT.md` mandates at the top of both files. Restored
+  from the byte-identical pre-wipe copy; a new `tests/consistency/configDocsSync.test.js`
+  guard fails loudly if a future self-install wipes either copy again.
+- **Verification.** `yarn test` 87 files / 1,553 tests green (also under `--sequence.shuffle`);
+  `yarn release:verify` exit 0; artifact unpacked ceiling raised once to 5,960,000 with
+  rationale in `tests/integration/packageArtifact.test.js`.
+
+## 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.3.22",
+  "version": "2.3.24",
   "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,55 @@ function safeResolve(basePath, relativePath) {
   return resolvedPath;
 }
 
+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 directly under the install target (`<projectRoot>/templates`
+// — the repo layout, which the global CLI does not have), 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).
+//
+// The path signal deliberately requires `<projectRoot>/templates` exactly, not merely
+// "templates somewhere inside projectRoot". A downstream project that installs UKit locally
+// (`node_modules/@ngockhoale/ukit/templates`) also has templates inside its root; treating
+// that as a self-install downgraded every docs entry to `skip`, so `ukit update` never
+// refreshed that project's docs. Only the package root itself being the project root is a
+// self-install.
+async function isSelfInstall({ templatesRoot, projectRoot }) {
+  if (path.dirname(path.resolve(templatesRoot)) === path.resolve(projectRoot)) {
+    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 +313,8 @@ export async function buildInstallPlan({
     }
   }
 
+  await downgradeSelfInstallDocOverwrites(planEntries, { templatesRoot, projectRoot });
+
   return {
     selectedItems,
     entries: planEntries,

package/src/index/taskRouting.js

@@ -406,6 +406,56 @@ function deriveExecutionScores({
   };
 }
 
+// A prompt that only asks a question (no command, no action verb, no error report) is
+// asking for an explanation, not a repository change. Routing it to an investigation or
+// edit lane fabricates write/verification debt the completion gate then enforces against an
+// answer turn. Kept byte-equivalent to the shipped copies in
+// templates/.claude/ukit/index/route-task.mjs and templates/.claude/hooks/skill-router.sh;
+// this is the canonical copy those are mirror-tested against. It deliberately ignores
+// targetFile: an edit order phrased as a question is caught by implementWords below, while a
+// pure targeted question ("how does X work?") is still just a question.
+function isInformationalPrompt({
+  promptText = '',
+  commandText = '',
+  scores = null,
+} = {}) {
+  if (String(commandText || '').trim()) return false;
+  const raw = String(promptText || '').toLowerCase().trim();
+  if (!raw) return false;
+  const questionSignal = raw.includes('?')
+    || /\b(what|how|when|which|where|who|is|are|does|do|did|can|could|would|should|will)\b/.test(raw)
+    || /(là\s+(?:[^\s]+\s+){0,2}gì|thế nào|như thế nào|bao nhiêu|khi nào|bao giờ|ở đâu|nghĩa là|được không|không\b)/.test(raw);
+  // '?' or a leading/Vietnamese interrogative — required to overrule error wording.
+  const strongQuestion = raw.includes('?')
+    || /^(what|how|when|which|where|who|is|are|does|do|did|can|could|would|should|will)\b/.test(raw)
+    || /(là\s+(?:[^\s]+\s+){0,2}gì|thế nào|như thế nào|bao nhiêu|khi nào|bao giờ|ở đâu)/.test(raw);
+  if (scores) {
+    if (
+      scores.implementSignal
+      || scores.reviewSignal
+      || scores.debugSignal
+      || scores.impactSignal
+      || scores.smallFixSignal
+      || scores.directTransformSignal
+    ) {
+      return false;
+    }
+    if (scores.failureSignal && !strongQuestion) {
+      return false;
+    }
+  }
+  const implementWords = /(?<![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|build|chạy|cài)(?![A-Za-z0-9_])/.test(raw);
+  if (implementWords) return false;
+  const investigationWords = /\b(why|debug|triage|root cause|investigate|tại sao)\b/.test(raw);
+  if (investigationWords) return false;
+  // \b never matches around 'lỗi' (diacritics are not \w), so test it as a plain
+  // substring: an error report is informational only when phrased as a question.
+  if (raw.includes('lỗi') && !strongQuestion) return false;
+  const reviewWords = /\b(review|audit|verify)\b/.test(raw);
+  if (reviewWords) return false;
+  return questionSignal;
+}
+
 function deriveExecutionMode({
   promptText = '',
   commandText = '',
@@ -494,6 +544,10 @@ function deriveExecutionMode({
     && !scores.sharedRisk
     && !targetFile;
 
+  if (isInformationalPrompt({ promptText, commandText, scores })) {
+    return 'informational';
+  }
+
   if (
     releaseVerificationContinuation
     || ((intentMode === 'review-specific' || explicitReviewLead) && !scores.implementSignal)