@ngockhoale/ukit 1.4.4 → 1.5.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to UKit are documented here.
 
+## 1.5.0 - 2026-05-24
+
+### Fixed
+
+- Switched safe-patch release regressions to `spawnSync`-based helpers so advisory-mode assertions capture `stderr` correctly even when the hook exits `0`.
+- Raised the packed artifact size budget slightly to preserve the shipped canvas font lane and recent runtime/router surfaces without failing release smoke on a 625-byte overage.
+
+### Changed
+
+- Bumped package and shared runtime version metadata to `1.5.0`.
+
+## 1.4.5 - 2026-05-24
+
+### Fixed
+
+- Stopped safe-patch hooks (`stale-spec-check`, `post-edit-verify`) from hard-blocking tool calls when configured via the new `safePatch.advisoryOnly` flag or the `UKIT_SAFE_PATCH_ADVISORY=1` env. Removes the mid-task "stop and wait for continue" stalls that hit shared-risk files in `.claude/`, `templates/`, `scripts/`, etc., while preserving the diagnostic message so Claude/Codex can self-correct instead of stalling.
+- Default behavior unchanged (`advisoryOnly: false`): pre-edit corruption guards (shebang-bom, non-text, whole-file Write to shared-risk) and the `protect-files` / `block-dangerous` hooks still hard-block.
+
+### Tests
+
+- Added regression coverage for advisory-mode exit code and stderr in `tests/hooks/safePatchProtocol.test.js`.
+- Added default + validation assertions for `safePatch.advisoryOnly` in `tests/core/runtimeConfig.test.js`.
+
 ## 1.4.4 - 2026-05-11
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "1.4.4",
+  "version": "1.5.0",
   "description": "Install/update an index-first AI workspace for Claude Code, Antigravity, OpenAI Codex, and OpenCode.",
   "license": "MIT",
   "type": "module",

package/src/core/runtimeConfig.js

@@ -49,7 +49,7 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
   const safeOverrides = isPlainObject(overrides) ? overrides : {};
 
   return mergeObjects({
-    version: '1.4.4',
+    version: '1.5.0',
     agent: 'claude-code',
     autonomy: {
       level: 'balanced',
@@ -183,6 +183,7 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
     safePatch: {
       enabled: true,
       strictSharedRisk: true,
+      advisoryOnly: false,
       largeFileLineThreshold: 800,
       largeFileByteThreshold: 200_000,
       backupEnabled: true,
@@ -368,6 +369,7 @@ export function validateRuntimeConfig(config) {
   } else {
     pushBooleanError(errors, config.safePatch.enabled, 'safePatch.enabled');
     pushBooleanError(errors, config.safePatch.strictSharedRisk, 'safePatch.strictSharedRisk');
+    pushBooleanError(errors, config.safePatch.advisoryOnly, 'safePatch.advisoryOnly');
     pushPositiveNumberError(errors, config.safePatch.largeFileLineThreshold, 'safePatch.largeFileLineThreshold');
     pushPositiveNumberError(errors, config.safePatch.largeFileByteThreshold, 'safePatch.largeFileByteThreshold');
     pushBooleanError(errors, config.safePatch.backupEnabled, 'safePatch.backupEnabled');

package/templates/.claude/ukit/index/post-edit-verify.mjs

@@ -2,7 +2,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { analyzeTextBuffer, analyzeTextFile, publicTextProfile } from '../runtime/text-profile.mjs';
-import { classifySafePatchRisk, parseJsonInput, pathExists, readRuntimeSafePatchConfig, resolveProjectFile } from '../runtime/safe-patch-core.mjs';
+import { classifySafePatchRisk, isSafePatchAdvisoryOnly, parseJsonInput, pathExists, readRuntimeSafePatchConfig, resolveProjectFile } from '../runtime/safe-patch-core.mjs';
 
 async function readStdin() {
   return await new Promise((resolve) => {
@@ -183,8 +183,10 @@ async function main() {
     process.stdout.write(json ? `${JSON.stringify({ help: text })}\n` : `${text}\n`);
     return;
   }
+  const projectRoot = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const runtimeConfig = await readRuntimeSafePatchConfig(projectRoot);
   const result = await verifyPostEdit({
-    projectRoot: process.env.CLAUDE_PROJECT_DIR || process.cwd(),
+    projectRoot,
     payload: parseJsonInput(await readStdin(), {}),
   });
   if (json) {
@@ -193,7 +195,14 @@ async function main() {
     process.stdout.write(`[ukit-safe-patch] ${result.message}\n`);
   }
   if (result.status === 'blocked') {
-    process.stderr.write(`[ukit-safe-patch] ${result.message}\n`);
+    const advisory = isSafePatchAdvisoryOnly(runtimeConfig);
+    const prefix = advisory ? 'ADVISORY' : 'BLOCKED';
+    const message = String(result.message || '').replace(/^BLOCKED:/, `${prefix}:`);
+    process.stderr.write(`[ukit-safe-patch] ${message}\n`);
+    if (advisory) {
+      process.stderr.write('[ukit-safe-patch] advisoryOnly=true — change is already written; continue planned follow-up without stopping.\n');
+      return;
+    }
     process.exit(2);
   }
 }

package/templates/.claude/ukit/index/stale-spec-check.mjs

@@ -4,6 +4,7 @@ import path from 'node:path';
 import {
   classifySafePatchRisk,
   countOccurrences,
+  isSafePatchAdvisoryOnly,
   lineNumberForIndex,
   parseJsonInput,
   pathExists,
@@ -169,7 +170,9 @@ async function main() {
     return;
   }
   const payload = parseJsonInput(await readStdin(), {});
-  const result = await checkStaleSpec({ projectRoot: process.env.CLAUDE_PROJECT_DIR || process.cwd(), payload });
+  const projectRoot = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const runtimeConfig = await readRuntimeSafePatchConfig(projectRoot);
+  const result = await checkStaleSpec({ projectRoot, payload });
   if (args.json) {
     process.stdout.write(`${JSON.stringify(result)}\n`);
   } else if (result.status === 'ok') {
@@ -179,7 +182,14 @@ async function main() {
   }
 
   if (result.status === 'blocked') {
-    process.stderr.write(`[ukit-safe-patch] ${result.message}\n`);
+    const advisory = isSafePatchAdvisoryOnly(runtimeConfig);
+    const prefix = advisory ? 'ADVISORY' : 'BLOCKED';
+    const message = String(result.message || '').replace(/^BLOCKED:/, `${prefix}:`);
+    process.stderr.write(`[ukit-safe-patch] ${message}\n`);
+    if (advisory) {
+      process.stderr.write('[ukit-safe-patch] advisoryOnly=true — continue with corrected old_string; do not stop and ask the user.\n');
+      return;
+    }
     process.exit(2);
   }
 }

package/templates/.claude/ukit/runtime/safe-patch-core.mjs

@@ -4,6 +4,7 @@ import path from 'node:path';
 export const DEFAULT_SAFE_PATCH_CONFIG = {
   enabled: true,
   strictSharedRisk: true,
+  advisoryOnly: false,
   largeFileLineThreshold: 800,
   largeFileByteThreshold: 200_000,
   backupEnabled: true,
@@ -13,6 +14,15 @@ export const DEFAULT_SAFE_PATCH_CONFIG = {
   deltaMaxDiffCells: 2_000_000,
 };
 
+// When advisoryOnly is true (via config or env UKIT_SAFE_PATCH_ADVISORY=1),
+// safe-patch hooks downgrade exit 2 (block) to exit 0 + WARNING. This keeps
+// Claude/Codex from stalling mid-task on stale/ambiguous spec or delta-budget
+// trips without losing the diagnostic message.
+export function isSafePatchAdvisoryOnly(config = DEFAULT_SAFE_PATCH_CONFIG) {
+  if (process.env.UKIT_SAFE_PATCH_ADVISORY === '1') return true;
+  return Boolean(config?.advisoryOnly);
+}
+
 const SHARED_RISK_PATTERNS = [
   /^\.claude\/hooks\//,
   /^\.claude\/ukit\//,

package/templates/ukit/README.md

@@ -1,6 +1,6 @@
 # UKit Shared Runtime
 
-This folder stores shared UKit runtime state for v1.4.4 features.
+This folder stores shared UKit runtime state for v1.5.0 features.
 
 - `storage/config.json` — runtime feature flags and defaults
 - `storage/cache/` — prompt-cache, compact history, compact pressure state, output summaries, and preserved raw tool outputs under `storage/cache/tee/`

package/templates/ukit/storage/config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.4.4",
+  "version": "1.5.0",
   "agent": "claude-code",
   "autonomy": {
     "level": "balanced",
@@ -147,6 +147,7 @@
   "safePatch": {
     "enabled": true,
     "strictSharedRisk": true,
+    "advisoryOnly": false,
     "largeFileLineThreshold": 800,
     "largeFileByteThreshold": 200000,
     "backupEnabled": true,
@@ -365,6 +366,7 @@
     "safePatch": {
       "enabled": "Bật Safe Patch Protocol: UKit âm thầm chặn patch stale/ambiguous trên file rủi ro và giữ an toàn encoding khi helper nội bộ sửa file.",
       "strictSharedRisk": "Nếu true, file runtime/shared-risk như .claude/hooks hoặc .claude/ukit sẽ bị guard chặt hơn; người dùng vẫn không cần nhớ command mới.",
+      "advisoryOnly": "Nếu true (hoặc env UKIT_SAFE_PATCH_ADVISORY=1), guard chỉ in WARNING thay vì exit 2 — tránh Claude/Codex dừng giữa chừng chờ user 'continue'. Vẫn giữ message để model tự retry.",
       "largeFileLineThreshold": "Số dòng từ đó file được xem là lớn và cần anchor/spec guard kỹ hơn.",
       "largeFileByteThreshold": "Kích thước byte từ đó file được xem là lớn/rủi ro khi agent edit.",
       "backupEnabled": "Nếu true, UKit tạo rollback bytes dưới .ukit/storage/backups cho edit rủi ro.",