@ngockhoale/ukit 2.3.23 → 2.4.0

package/CHANGELOG.md

@@ -2,6 +2,83 @@
 
 All notable changes to UKit are documented here.
 
+## 2.4.0 - 2026-09-14
+
+Solution-discipline wording + offline instruments. This release is **additive**: it changes
+instruction text that is already loaded in daily sessions and adds offline test instruments
+under `tests/`, which the published tarball does not ship. It changes no runtime, config,
+route, hook, or gateway behaviour, and it removes no existing behaviour.
+
+- **Solution ladder + carve-outs in the delivery lane.** `templates/.claude/skills/delivery/SKILL.md`
+  (and its active mirror) now carry the canonical ladder: choose the smallest solution that fully
+  meets the stated requirements and project conventions; prefer reuse of an equivalent codebase
+  helper, then the standard library / native API / an already-installed dependency, and treat new
+  custom code or a new dependency as the last resort. The carve-out is explicit: never drop
+  validation, security, accessibility, error handling, compatibility, or required tests to reduce
+  code, and never ship a weaker version and ask. The delivery "Tier 2 — Structure Scan" step now
+  prefers the project index/resolver and falls back to raw Glob/Grep only when the index is stale,
+  missing, or returns no match — understanding source before editing is never skipped.
+- **Feature-implementer ladder (Claude Code + omp).** `templates/.claude/agents/feature-implementer.md`,
+  its active byte-twin, and `templates/.omp/agents/feature-implementer.md` gain the same ladder plus
+  a guard reminder that fewer lines are not a reason to drop a guard. The daily-mode test rule is
+  left verbatim: the ladder must not become an excuse to cut tests.
+- **Reviewer rubric (Claude Code + omp).** The `code-reviewer` copies gain 5 evidence-first
+  solution-fit questions (duplicate semantics / standard library suffices / guard-dropping
+  simplification / shared root cause / speculative abstraction) and a rule that says
+  **never grade brevity or line count as a quality win**. The sidecar diff lane stays
+  non-blocking with no auto-delete; verdict and model-isolation contracts are unchanged.
+- **Offline instruments (not shipped).** A pure metric protocol
+  (`tests/benchmarks/solution-discipline/protocol.mjs`), four acceptance fixtures under
+  `tests/fixtures/solution-discipline/` (F01 reuse-helper, F06 trust-boundary, F09 keep-failure-path,
+  F11 required-interface) with good/bad reference solutions, and a host driver core exercised through
+  fake hosts (nonzero exit, timeout, malformed events, duplicate usage, missing terminal event).
+  These live under `tests/`, which `package.json.files` does not publish, so they stay out of the
+  tarball by construction; the release check confirms the packed file list contains no `tests/` path.
+- **Deferred, with reasons.** The paid pilot (roadmap PT-06) and confirmatory benchmark (PT-09) are
+  deferred: no spending cap is approved and no billable model call was made this cycle. The runtime
+  lifecycle work (PT-07/PT-08 — shared renderer plus route/lifecycle/omp integration) is deferred
+  because the evidence for instruction-only wording is sufficient to start and no runtime drift has
+  been observed yet. The remaining fixtures and live-host probing are queued in
+  `docs/AI_HANDOFF/PROPOSAL-C18-benchmark-fixtures.md` for the funded pilot cycle.
+- **Evidence record.** The preflight inventory this release builds on is pinned in
+  `docs/plans/ponytail-evidence.md` (revision pin, existing/proposed inventory, command map, blockers).
+- **Truthfulness.** Savings are unverified until a paid benchmark pilot runs; no token/LOC reduction
+  is claimed for this release.
+
+## 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

package/package.json

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

@@ -45,22 +45,25 @@ 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).
+// 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 (isPathInside(projectRoot, templatesRoot)) {
+  if (path.dirname(path.resolve(templatesRoot)) === path.resolve(projectRoot)) {
     return true;
   }
   try {

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)

package/templates/.claude/agents/code-reviewer.md

@@ -35,6 +35,13 @@ If any input is missing, return `CHANGES-REQUESTED` with reason "incomplete hand
 4. **Safety / security / data loss** — Destructive actions, auth/permission, path handling, unsafe shell/DB/file ops.
 5. **Performance / scale** — Accidental N+1, repeated I/O, large scans inside hot paths.
 6. **Maintainability** — Duplicated logic, dead branches, misleading naming, drift between docs/tests/source.
+7. **Solution fit** — For each added block, ask with evidence and cite the construct + why (never the prose length):
+   - Does new code duplicate an existing helper with the same semantics? A same-semantics duplicate is `CHANGES-REQUESTED` — reuse the existing helper.
+   - Would the standard library or a native platform API satisfy every stated requirement? If yes, the custom implementation is avoidable.
+   - Does the simplification drop validation, security, accessibility, error handling, compatibility, or a required test? If yes it is a regression, not a simplification.
+   - Does a short diff fix the true shared root cause, or only one symptom or caller? Fix the root cause and its affected callers.
+   - Is there an abstraction serving only a hypothetical, speculative need? Remove it unless a stated requirement needs it.
+   **Never grade brevity or line count as a quality win** — a shorter diff is not evidence of a better change, and a longer one that fully meets requirements is not a finding. Every solution-fit finding must cite `file:line` + the construct + the reason, or it stays a hypothesis and must not drive code deletion.
 
 ### Severity ladder
 
@@ -171,13 +178,14 @@ the main task already has write + verification evidence; the caller is not waiti
 
 ### Review order
 
-Apply the same lenses as Code Review's steps 2-6, scoped to what the diff actually touches:
+Apply the same lenses as Code Review's steps 2-7, scoped to what the diff actually touches:
 
 1. **Correctness** — Does the diff do what it looks like it's trying to do? Wrong assumptions, stale refs, missing cases?
 2. **Regression risk** — Any existing behavior/tests/contracts this plausibly breaks?
 3. **Safety / security / data loss** — Destructive actions, auth/permission, path handling, unsafe shell/DB/file ops.
 4. **Performance / scale** — Accidental N+1, repeated I/O, large scans in hot paths.
 5. **Maintainability** — Duplicated logic, dead branches, misleading naming, drift between docs/tests/source.
+6. **Solution fit** — Apply the same 5 evidence-first questions as Code Review step 7 (duplicate semantics / standard library or native suffices / simplification dropping validation, security, accessibility or tests / shared root cause / speculative abstraction). **Never grade brevity or line count as a quality win.** Findings must cite the construct + reason, and here they remain advisory hypotheses only — never a delete-list, never an edit.
 
 Do not re-run the project's full verification suite here — this is an advisory pass, not a gate.
 You may read files for context but this mode never edits anything.

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

@@ -41,6 +41,7 @@ and even then, report it, don't ask about it.
 
 - List files to create/modify (max diff).
 - **Handoff mode only:** if no Test Plan exists in the task file and task is not `trivial`, write one inline before implementing (happy + ≥2 edge cases of different kinds; regression test if fixing a bug). In daily mode, skip this step.
+- **Choose the smallest solution that fully meets the stated requirements and project conventions.** When more than one option qualifies, prefer, in order: (1) reuse an existing codebase helper with the same semantics; (2) standard library, native platform API, or an already-installed dependency; (3) custom code or a new dependency (last resort). Never drop validation, security, accessibility, error handling, compatibility, or required tests to reduce code. A bugfix fixes the root cause and the affected callers. If the small option is insufficient, build the full option — never ship a weaker version and ask. No speculative abstraction for imagined needs.
 
 ### 3. Test First (RED) — Handoff mode
 
@@ -56,6 +57,7 @@ and even then, report it, don't ask about it.
 - Reuse existing code before creating new.
 - No unrelated changes or speculative refactors.
 - Follow project conventions (check `.claude/skills/` for patterns).
+- **Guard the smallest solution:** never weaken validation, security, accessibility, error handling, or required tests just to shorten the diff — fewer lines is not a reason to drop a guard.
 
 ### 5. Verify (REQUIRED before DONE in Handoff mode; targeted in Daily mode)
 

package/templates/.claude/skills/delivery/SKILL.md

@@ -13,6 +13,16 @@ Project: {{project.name}} | Stack: {{project.stack}}
 - Review gate for non-trivial edits (>3 files or >50 lines).
 - Reuse existing code. No drive-by refactors.
 
+## Solution Selection Ladder
+
+Choose the smallest solution that fully meets the stated requirements and project conventions. When more than one option qualifies, prefer, in order:
+
+1. reuse an existing codebase helper with the same semantics;
+2. standard library, native platform API, or an already-installed dependency;
+3. custom code or a new dependency (last resort).
+
+Never drop validation, security, accessibility, error handling, compatibility, or required tests to reduce code. A bugfix fixes the root cause and the affected callers. If the small option is insufficient, build the full option — never ship a weaker version and ask. No speculative abstraction for imagined needs.
+
 ## Docs-Centric Principle
 
 **Docs are the center.** Read docs first, write docs last.
@@ -35,9 +45,9 @@ Read in order. Never skip to Tier 3 without Tier 1+2.
 - Recent `docs/WORKLOG.md` → when continuing prior work or debugging
 
 **Tier 2 — Structure Scan** (before opening source files):
-- Glob file tree → know what exists where
-- Grep function/class/export signatures → understand shape without full reads
-- Narrows exactly which files to open in Tier 3
+- Prefer the project index/resolver to find what exists where and the shape of symbols.
+- Fall back to raw Glob/Grep only when the index is stale, missing, or returns no match.
+- Narrows exactly which files to open in Tier 3; understanding source before editing is never skipped.
 
 **Tier 3 — Targeted Source Reads** (only what is needed):
 - Read only the specific files relevant to the task
@@ -57,7 +67,7 @@ After any non-trivial task, AI must update docs proactively — **do not wait to
 ## Workflow
 
 1. **Orient** — Tier 1: read docs, form hypothesis about the system
-2. **Scan** — Tier 2: Glob + Grep to verify hypothesis, find relevant files
+2. **Scan** — Tier 2: use the project index/resolver to verify the hypothesis and find relevant files; raw Glob/Grep only when the index is stale, missing, or returns no match
 3. **Verify** — if source contradicts docs, update docs first
 4. **Execute** — smallest change, follow existing patterns
 5. **Test** — run tests, check regressions

package/templates/.omp/agents/code-reviewer.md

@@ -34,6 +34,13 @@ If any input is missing, return `CHANGES-REQUESTED` with reason "incomplete hand
 4. **Safety / security / data loss** — Destructive actions, auth/permission, path handling, unsafe shell/DB/file ops.
 5. **Performance / scale** — Accidental N+1, repeated I/O, large scans inside hot paths.
 6. **Maintainability** — Duplicated logic, dead branches, misleading naming, drift between docs/tests/source.
+7. **Solution fit** — For each added block, ask with evidence and cite the construct + why (never the prose length):
+   - Does new code duplicate an existing helper with the same semantics? A same-semantics duplicate is `CHANGES-REQUESTED` — reuse the existing helper.
+   - Would the standard library or a native platform API satisfy every stated requirement? If yes, the custom implementation is avoidable.
+   - Does the simplification drop validation, security, accessibility, error handling, compatibility, or a required test? If yes it is a regression, not a simplification.
+   - Does a short diff fix the true shared root cause, or only one symptom or caller? Fix the root cause and its affected callers.
+   - Is there an abstraction serving only a hypothetical, speculative need? Remove it unless a stated requirement needs it.
+   **Never grade brevity or line count as a quality win** — a shorter diff is not evidence of a better change, and a longer one that fully meets requirements is not a finding. Every solution-fit finding must cite `file:line` + the construct + the reason, or it stays a hypothesis and must not drive code deletion.
 
 ### Severity ladder
 
@@ -170,13 +177,14 @@ the main task already has write + verification evidence; the caller is not waiti
 
 ### Review order
 
-Apply the same lenses as Code Review's steps 2-6, scoped to what the diff actually touches:
+Apply the same lenses as Code Review's steps 2-7, scoped to what the diff actually touches:
 
 1. **Correctness** — Does the diff do what it looks like it's trying to do? Wrong assumptions, stale refs, missing cases?
 2. **Regression risk** — Any existing behavior/tests/contracts this plausibly breaks?
 3. **Safety / security / data loss** — Destructive actions, auth/permission, path handling, unsafe shell/DB/file ops.
 4. **Performance / scale** — Accidental N+1, repeated I/O, large scans in hot paths.
 5. **Maintainability** — Duplicated logic, dead branches, misleading naming, drift between docs/tests/source.
+6. **Solution fit** — Apply the same 5 evidence-first questions as Code Review step 7 (duplicate semantics / standard library or native suffices / simplification dropping validation, security, accessibility or tests / shared root cause / speculative abstraction). **Never grade brevity or line count as a quality win.** Findings must cite the construct + reason, and here they remain advisory hypotheses only — never a delete-list, never an edit.
 
 Do not re-run the project's full verification suite here — this is an advisory pass, not a gate.
 You may read files for context but this mode never edits anything.

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

@@ -40,6 +40,7 @@ and even then, report it, don't ask about it.
 
 - List files to create/modify (max diff).
 - **Handoff mode only:** if no Test Plan exists in the task file and task is not `trivial`, write one inline before implementing (happy + ≥2 edge cases of different kinds; regression test if fixing a bug). In daily mode, skip this step.
+- **Choose the smallest solution that fully meets the stated requirements and project conventions.** When more than one option qualifies, prefer, in order: (1) reuse an existing codebase helper with the same semantics; (2) standard library, native platform API, or an already-installed dependency; (3) custom code or a new dependency (last resort). Never drop validation, security, accessibility, error handling, compatibility, or required tests to reduce code. A bugfix fixes the root cause and the affected callers. If the small option is insufficient, build the full option — never ship a weaker version and ask. No speculative abstraction for imagined needs.
 
 ### 3. Test First (RED) — Handoff mode
 
@@ -55,6 +56,7 @@ and even then, report it, don't ask about it.
 - Reuse existing code before creating new.
 - No unrelated changes or speculative refactors.
 - Follow project conventions (check `.claude/skills/` for patterns).
+- **Guard the smallest solution:** never weaken validation, security, accessibility, error handling, or required tests just to shorten the diff — fewer lines is not a reason to drop a guard.
 
 ### 5. Verify (REQUIRED before DONE in Handoff mode; targeted in Daily mode)