@ngockhoale/ukit 3.4.19 → 3.4.20

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to UKit are documented here.
 
+## 3.4.20 - 2026-10-06
+
+**`ukit update` now displays the NEW version.** The running process is the old code, so the
+banner used to print only the stale "Current version" and read like the update had not
+worked. It now prints `Updated: <old> -> <new>` (version read from the freshly installed global
+package.json) right after `npm install -g`, repeats the new version in the final line, and says
+"already the latest" when nothing changed.
+
+**Release/verify tooling no longer wastes minutes on trivial work.**
+- `release:verify` now runs the cheap deterministic gates first (`docs:render:check`, `tests/consistency`) and
+  stops the ~4 min core suite after 5 failures (`--bail 5`); a stale instruction render or template/active
+  drift is reported in seconds, not after the full suite.
+- Single-instance lock: a second concurrent `release:verify` for the same repo exits 3 naming the live pid
+  instead of racing the first (two concurrent suites made both slow and flaky).
+- `rollout.test.js` no longer re-runs the entire `release:verify` from inside `release:verify` (that one test
+  took ~307 s, doubling the release gate).
+- Instruction core: "Long commands run once" rule (never duplicate a backgrounded/timed-out long run).
+- Fixed a comment in `handoff-model-guard.sh` that the watchdog-coverage scan mistook for an unarmed inline
+  `node -e` block (shipped red in 3.4.18/3.4.19 because only the hooks suite was run before release).
+
 ## 3.4.19 - 2026-10-06
 
 **Create-scope guard: more read-only shell false positives removed (found by replaying 4vn's real blocked commands).**

package/package.json

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

package/scripts/release/verify-release.mjs

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process';
-import { readFileSync } from 'node:fs';
+import { readFileSync, writeFileSync, unlinkSync, existsSync } from 'node:fs';
+import crypto from 'node:crypto';
 import os from 'node:os';
 import path from 'node:path';
 
@@ -38,7 +39,48 @@ if (postPublish) {
   process.exit(0);
 }
 
+
+// Single-instance guard (full verification takes ~4 min). Starting a second run while one is
+// alive (e.g. after the first was moved to the background by a tool timeout) only makes both
+// slower and flakier — wait for / read the first run's result instead.
+let lockPath = null;
+function acquireVerifyLock() {
+  // Nested runs (the release suite's own tests spawn this script) and test workers must not contend.
+  if (process.env.UKIT_RELEASE_VERIFY_ACTIVE === '1' || process.env.VITEST || process.env.UKIT_VERIFY_NO_LOCK === '1') return;
+  lockPath = path.join(os.tmpdir(), `ukit-release-verify-${crypto.createHash('sha1').update(rootDir).digest('hex').slice(0, 10)}.lock`);
+  if (existsSync(lockPath)) {
+    const pid = Number(readFileSync(lockPath, 'utf8').trim());
+    let alive = false;
+    try { process.kill(pid, 0); alive = Number.isInteger(pid) && pid > 0 && pid !== process.pid; } catch { /* stale */ }
+    if (alive) {
+      console.error(`[release:verify] another release:verify is already running for this repo (pid ${pid}). Wait for it (or read its output) — do NOT start a second full run; two concurrent suites slow each other and cause flaky failures.`);
+      process.exit(3);
+    }
+  }
+  writeFileSync(lockPath, String(process.pid));
+  process.env.UKIT_RELEASE_VERIFY_ACTIVE = '1';
+  const release = () => { try { if (readFileSync(lockPath, 'utf8').trim() === String(process.pid)) unlinkSync(lockPath); } catch { /* gone */ } };
+  process.on('exit', release);
+  for (const sig of ['SIGINT', 'SIGTERM']) process.on(sig, () => { release(); process.exit(130); });
+}
+
+acquireVerifyLock();
+
+// Cheap, deterministic gates FIRST (seconds): a stale instruction render or a consistency drift
+// used to surface only after the ~4 min full suite.
 const steps = [
+  {
+    label: 'Rendered instructions up to date (fix: yarn docs:render)',
+    command: 'yarn',
+    args: ['docs:render:check'],
+    env: process.env,
+  },
+  {
+    label: 'Consistency suite (template<->active sync, watchdog coverage, render parity)',
+    command: 'yarn',
+    args: ['vitest', 'run', 'tests/consistency'],
+    env: process.env,
+  },
   {
     label: 'Artifact smoke',
     command: 'yarn',
@@ -54,7 +96,7 @@ const steps = [
   {
     label: 'Core test suite',
     command: 'yarn',
-    args: ['test:release-core'],
+    args: ['test:release-core', '--bail', '5'], // stop after 5 failures instead of finishing a doomed 4 min run
     env: process.env,
   },
   {

package/src/cli/commands/update.js

@@ -1,4 +1,4 @@
-import { updateUkit, runInstallAfterUpdate, UKIT_PACKAGE_NAME } from '../../core/update.js';
+import { updateUkit, runInstallAfterUpdate, readInstalledGlobalVersion, UKIT_PACKAGE_NAME } from '../../core/update.js';
 
 const KNOWN_UPDATE_FLAGS = new Set(['--help', '-h', '--no-install']);
 
@@ -27,13 +27,23 @@ export async function runUpdate({ packageVersion, argv = [], cwd = process.cwd()
     );
   }
 
-  console.log(`[UKit] Current version: ${packageVersion}`);
+  console.log(`[UKit] Version before update: ${packageVersion}`);
   console.log(`[UKit] Running: npm install -g ${UKIT_PACKAGE_NAME}`);
 
   updateUkit();
 
+  // This process still runs the OLD code, so report the version the update actually
+  // installed (read from disk), never the stale `packageVersion`.
+  const installedVersion = readInstalledGlobalVersion();
+  const versionLine = installedVersion
+    ? installedVersion === packageVersion
+      ? `[UKit] Installed version: ${installedVersion} (already the latest)`
+      : `[UKit] Updated: ${packageVersion} -> ${installedVersion}`
+    : '[UKit] Updated (could not read the new version — run `ukit --version`)';
+  console.log(versionLine);
+
   if (argv.includes('--no-install')) {
-    console.log('[UKit] Update complete. Skipped project refresh (--no-install).');
+    console.log(`[UKit] Update complete${installedVersion ? ` — UKit ${installedVersion}` : ''}. Skipped project refresh (--no-install).`);
     return;
   }
 
@@ -41,7 +51,7 @@ export async function runUpdate({ packageVersion, argv = [], cwd = process.cwd()
   const { ran, reason } = runInstallAfterUpdate({ projectRoot: cwd });
 
   if (ran) {
-    console.log('[UKit] Update complete — CLI upgraded and project refreshed.');
+    console.log(`[UKit] Update complete — UKit ${installedVersion ?? 'latest'} installed and project refreshed.`);
     return;
   }
 

package/src/core/update.js

@@ -62,6 +62,22 @@ function resolveGlobalUkitBinDetailed({ spawnSync = defaultSpawnSync } = {}) {
   return { binPath: fs.existsSync(binPath) ? binPath : null, timedOut: false };
 }
 
+/**
+ * Version of the globally installed UKit package as it is on disk NOW, or null if unreadable.
+ * `packageVersion` in the running process is the OLD code's version (the process predates
+ * `npm install -g`), so it must never be printed as the post-update version.
+ */
+export function readInstalledGlobalVersion({ spawnSync = defaultSpawnSync } = {}) {
+  try {
+    const { binPath } = resolveGlobalUkitBinDetailed({ spawnSync });
+    if (!binPath) return null;
+    const pkg = JSON.parse(fs.readFileSync(path.join(path.dirname(binPath), '..', 'package.json'), 'utf8'));
+    return typeof pkg.version === 'string' ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Run `ukit install` in `projectRoot` using the freshly installed global package.
  * Returns { ran, reason } so the caller can report accurately rather than claim an

package/template_project/.claude/hooks/handoff-model-guard.sh

@@ -388,7 +388,7 @@ const SHELL_WRITE_PATTERNS = [
   new RegExp(String.raw`${CMD_POS}curl\s(?:[^;&|\n]*\s)?(?:-[sSfLvkiI#]*[oO]\b|--(?:output|remote-name|output-dir)\b)`),
   new RegExp(String.raw`${CMD_POS}[gm]?awk\s(?:[^;&|\n]*\s)?-i\s*inplace\b`),
 ];
-// Read-only inline interpreters (`node -e '…'`, `python3 -c '…'`, `python3 - <<'PY'`, `jq '…'`):
+// Read-only inline interpreters (inline node scripts (-e flag), `python3 -c '…'`, `python3 - <<'PY'`, `jq '…'`):
 // their quoted script/program body is code, not shell. Scanning it with the shell write
 // patterns misfires on arrow functions (`l=>{…}`), comparisons (`n>1750`), and words such as
 // `ln`/`cp`/`install` used as identifiers — which blocked read-only transcript analysis in a

package/template_project/AGENTS.md

@@ -86,6 +86,7 @@ Chỉ active khi task đi qua `docs/AI_HANDOFF/` ("execute task TASK-xxx" hoặc
 - **Trivial**: no docs, no index query unless the target is unclear. **Simple**: `docs/MEMORY.md` + resolver-selected files/tests. **Non-trivial**: + `docs/PROJECT.md` + `docs/CODE_MAP.md`.
 <!-- RULES: BUDGET-02 BUDGET-03 -->
 - `docs/STATUS.md` for open-ended/continue; `docs/TASKS.md` only for queued-task prompts; `docs/WORKLOG.md` recent entries only. Verification: targeted first, widen on risk/shared scope, ask before broad runs.
+- **Long commands run once:** start a full suite/release gate (>1 min) a single time; if it times out or goes to background, read its output — never launch a duplicate in parallel. Cheap deterministic gates first; trivial/simple tasks never need the full suite.
 
 ## Living Status Workflow
 <!-- RULE: STATUS-01 -->

package/template_project/CLAUDE.md

@@ -86,6 +86,7 @@ Chỉ active khi task đi qua `docs/AI_HANDOFF/` ("execute task TASK-xxx" hoặc
 - **Trivial**: no docs, no index query unless the target is unclear. **Simple**: `docs/MEMORY.md` + resolver-selected files/tests. **Non-trivial**: + `docs/PROJECT.md` + `docs/CODE_MAP.md`.
 <!-- RULES: BUDGET-02 BUDGET-03 -->
 - `docs/STATUS.md` for open-ended/continue; `docs/TASKS.md` only for queued-task prompts; `docs/WORKLOG.md` recent entries only. Verification: targeted first, widen on risk/shared scope, ask before broad runs.
+- **Long commands run once:** start a full suite/release gate (>1 min) a single time; if it times out or goes to background, read its output — never launch a duplicate in parallel. Cheap deterministic gates first; trivial/simple tasks never need the full suite.
 
 ## Living Status Workflow
 <!-- RULE: STATUS-01 -->

package/template_project/instructions/core.md

@@ -83,6 +83,7 @@ Chỉ active khi task đi qua `docs/AI_HANDOFF/` ("execute task TASK-xxx" hoặc
 - **Trivial**: no docs, no index query unless the target is unclear. **Simple**: `docs/MEMORY.md` + resolver-selected files/tests. **Non-trivial**: + `docs/PROJECT.md` + `docs/CODE_MAP.md`.
 <!-- RULES: BUDGET-02 BUDGET-03 -->
 - `docs/STATUS.md` for open-ended/continue; `docs/TASKS.md` only for queued-task prompts; `docs/WORKLOG.md` recent entries only. Verification: targeted first, widen on risk/shared scope, ask before broad runs.
+- **Long commands run once:** start a full suite/release gate (>1 min) a single time; if it times out or goes to background, read its output — never launch a duplicate in parallel. Cheap deterministic gates first; trivial/simple tasks never need the full suite.
 
 ## Living Status Workflow
 <!-- RULE: STATUS-01 -->