@ngockhoale/ukit 2.3.24 → 2.4.1

package/CHANGELOG.md

@@ -2,6 +2,63 @@
 
 All notable changes to UKit are documented here.
 
+## 2.4.1 - 2026-09-14
+
+Fix: the skill-router hook could hang the session and leak an orphaned process. `skill-router.sh`
+runs on the `UserPromptSubmit`/`PreToolUse` hot path. Unlike its sibling hooks
+(`task-watchdog.sh`, `handoff-resume.sh`), its node heredoc had no self-deadline watchdog: when
+indexed-context resolution hung (a wedged import, a stalled mount), the host killed only the bash
+wrapper with the node grandchild reparented to launchd and spinning forever — one orphan per run,
+hundreds accumulated over days, adding sustained RSS pressure that presented as UKit freezing with
+no message. The hook now arms the same wall-clock watchdog its siblings carry
+(`setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref()`, default 3000 ms, overridable via
+`UKIT_HOOK_DEADLINE_MS`), so a hang can never outlive the hook. Early exit only drops the routing
+hint — the same posture as a cache miss, and advisory-only as the hook already is. Applied
+byte-identically to the live and shipped (template) copies.
+
+## 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.3.24",
+  "version": "2.4.1",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex, OpenCode, and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

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/hooks/skill-router.sh

@@ -102,6 +102,17 @@ const path = require('path');
 const crypto = require('crypto');
 const { pathToFileURL } = require('url');
 
+// Wall-clock watchdog. This hook runs on the UserPromptSubmit/PreToolUse hot path but has
+// no host-side process-group kill: when indexed-context resolution hangs (a wedged import,
+// a stalled mount), the host kills only THIS bash wrapper, the node grandchild below is
+// reparented to launchd, and it spins forever. Verified: exactly one orphan leaked per run
+// of the router timeout test, 200+ accumulated over days. Self-exit at the deadline so a
+// hang can never outlive the hook. Advisory only — an early exit just drops the routing
+// hint, the same posture as a cache miss. Same watchdog task-watchdog.sh/handoff-resume.sh
+// already carry; keep this one aligned with them.
+const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10) || 3000;
+setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
+
 (async () => {
   const STOPWORDS = new Set([
     'the', 'a', 'an', 'and', 'or', 'to', 'for', 'of', 'with', 'in', 'on', 'is', 'are',

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)