@ngockhoale/ukit 1.2.1 → 1.3.0

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

@@ -0,0 +1,192 @@
+import { analyzeTextFile, publicTextProfile } from '../runtime/text-profile.mjs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import {
+  classifySafePatchRisk,
+  countOccurrences,
+  lineNumberForIndex,
+  parseJsonInput,
+  pathExists,
+  readRuntimeSafePatchConfig,
+  resolveProjectFile,
+  summarizeSnippet,
+} from '../runtime/safe-patch-core.mjs';
+
+function getToolName(payload = {}) {
+  return String(payload.tool_name || payload.tool || payload.name || '').trim();
+}
+
+function getFilePath(payload = {}) {
+  return payload.tool_input?.file_path || payload.file_path || '';
+}
+
+function getOldString(payload = {}) {
+  return payload.tool_input?.old_string ?? payload.old_string;
+}
+
+function formatRisk(risk) {
+  return risk.labels.length > 0 ? risk.labels.join(',') : 'low';
+}
+
+export async function checkStaleSpec({ projectRoot = process.cwd(), payload = {} } = {}) {
+  const config = await readRuntimeSafePatchConfig(projectRoot);
+  if (config.enabled === false) {
+    return { status: 'disabled' };
+  }
+
+  const toolName = getToolName(payload);
+  const filePath = getFilePath(payload);
+  if (!filePath) return { status: 'skipped', reason: 'no-file' };
+  const resolved = resolveProjectFile(projectRoot, filePath);
+  const exists = await pathExists(resolved.absolute);
+
+  let profile = null;
+  let risk = classifySafePatchRisk(resolved.relative, null, config);
+  if (exists) {
+    profile = await analyzeTextFile(resolved.absolute);
+    risk = classifySafePatchRisk(resolved.relative, profile, config);
+  }
+  const strict = Boolean(config.strictSharedRisk) && risk.strict;
+
+  if (profile?.shebangHasBom && strict) {
+    return {
+      status: 'blocked',
+      code: 'shebang-bom',
+      message: `BLOCKED: shebang file '${resolved.relative}' has a UTF-8 BOM before #!. Use safe-patch.mjs after removing/handling BOM intentionally.`,
+      file: resolved.relative,
+      risk,
+      profile: publicTextProfile(profile),
+    };
+  }
+
+  if (profile && (profile.binaryLike || !profile.utf8Valid) && strict) {
+    return {
+      status: 'blocked',
+      code: 'non-text',
+      message: `BLOCKED: '${resolved.relative}' is not strict UTF-8 text. Refusing risky agent edit to avoid corruption.`,
+      file: resolved.relative,
+      risk,
+      profile: publicTextProfile(profile),
+    };
+  }
+
+  if (/write/i.test(toolName) && exists && strict) {
+    return {
+      status: 'blocked',
+      code: 'shared-risk-write',
+      message: `BLOCKED: whole-file Write to existing shared-risk file '${resolved.relative}'. Use anchored Edit or node .claude/ukit/index/safe-patch.mjs with a unique anchor.`,
+      file: resolved.relative,
+      risk,
+      profile: profile ? publicTextProfile(profile) : null,
+    };
+  }
+
+  if (!/edit/i.test(toolName)) {
+    return { status: 'skipped', reason: 'not-edit', file: resolved.relative, risk };
+  }
+
+  const oldString = getOldString(payload);
+  if (!exists) {
+    return { status: 'skipped', reason: 'new-file', file: resolved.relative, risk };
+  }
+  if (typeof oldString !== 'string' || oldString.length === 0) {
+    if (strict) {
+      return {
+        status: 'blocked',
+        code: 'missing-old-string',
+        message: `BLOCKED: missing old_string for shared-risk edit '${resolved.relative}'. Use a unique current-file anchor and exact old_string.`,
+        file: resolved.relative,
+        risk,
+        profile: publicTextProfile(profile),
+      };
+    }
+    return { status: 'warn', code: 'missing-old-string', file: resolved.relative, risk };
+  }
+
+  const occurrence = countOccurrences(profile.text, oldString);
+  if (occurrence.count === 1) {
+    return {
+      status: 'ok',
+      specStatus: 'exact',
+      file: resolved.relative,
+      risk,
+      profile: publicTextProfile(profile),
+      line: lineNumberForIndex(profile.text, occurrence.indexes[0]),
+    };
+  }
+
+  const code = occurrence.count === 0 ? 'stale-spec' : 'ambiguous-spec';
+  const message = occurrence.count === 0
+    ? `BLOCKED: stale spec for '${resolved.relative}' — old_string was not found in current file. Re-read current source, then choose Apply as-is / Adapt to current code / Skip.`
+    : `BLOCKED: ambiguous spec for '${resolved.relative}' — old_string matched ${occurrence.count} times. Use a unique anchor or narrower old_string.`;
+
+  if (strict) {
+    return {
+      status: 'blocked',
+      code,
+      message,
+      file: resolved.relative,
+      risk,
+      profile: publicTextProfile(profile),
+      matches: occurrence.indexes.slice(0, 5).map((index) => ({
+        line: lineNumberForIndex(profile.text, index),
+        snippet: summarizeSnippet(profile.text.slice(index, index + Math.min(oldString.length, 180))),
+      })),
+    };
+  }
+
+  return {
+    status: 'warn',
+    code,
+    message: message.replace(/^BLOCKED:/, 'WARNING:'),
+    file: resolved.relative,
+    risk,
+    profile: publicTextProfile(profile),
+  };
+}
+
+async function readStdin() {
+  return await new Promise((resolve) => {
+    let raw = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { raw += chunk; });
+    process.stdin.on('end', () => resolve(raw));
+  });
+}
+
+function parseArgs(argv = process.argv.slice(2)) {
+  return {
+    json: argv.includes('--json'),
+    help: argv.includes('--help') || argv.includes('-h'),
+  };
+}
+
+async function main() {
+  const args = parseArgs();
+  if (args.help) {
+    const help = 'Usage: stale-spec-check.mjs < Claude hook JSON on stdin';
+    process.stdout.write(args.json ? `${JSON.stringify({ help })}\n` : `${help}\n`);
+    return;
+  }
+  const payload = parseJsonInput(await readStdin(), {});
+  const result = await checkStaleSpec({ projectRoot: process.env.CLAUDE_PROJECT_DIR || process.cwd(), payload });
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+  } else if (result.status === 'ok') {
+    process.stdout.write(`[ukit-safe-patch] spec=exact file=${result.file} line=${result.line} risk=${formatRisk(result.risk)}\n`);
+  } else if (result.status === 'warn') {
+    process.stderr.write(`[ukit-safe-patch] ${result.message}\n`);
+  }
+
+  if (result.status === 'blocked') {
+    process.stderr.write(`[ukit-safe-patch] ${result.message}\n`);
+    process.exit(2);
+  }
+}
+
+if (process.argv[1] && path.basename(fileURLToPath(import.meta.url)) === path.basename(process.argv[1])) {
+  main().catch((error) => {
+    process.stderr.write(`[ukit-safe-patch] ERROR: ${error?.message || error}\n`);
+    process.exit(1);
+  });
+}

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

@@ -0,0 +1,140 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export const DEFAULT_SAFE_PATCH_CONFIG = {
+  enabled: true,
+  strictSharedRisk: true,
+  largeFileLineThreshold: 800,
+  largeFileByteThreshold: 200_000,
+  backupEnabled: true,
+  backupRetentionDays: 30,
+  deltaMaxChangedLines: 120,
+  deltaMaxHunks: 3,
+  deltaMaxDiffCells: 2_000_000,
+};
+
+const SHARED_RISK_PATTERNS = [
+  /^\.claude\/hooks\//,
+  /^\.claude\/ukit\//,
+  /^\.codex\//,
+  /^templates\/\.claude\/hooks\//,
+  /^templates\/\.claude\/ukit\//,
+  /^src\/index\//,
+  /^src\/core\/(runInstallPipeline|applyPlan|buildPlan|diffPlan|metadata|migrateLegacy|uninstall|runtimeConfig|runtimePaths)\.js$/,
+  /^src\/core\/(output|token|compact)\//,
+  /^manifests\/platform\.full\.yaml$/,
+  // Intentional for UKit development: template edits become installed runtime behavior after `ukit install`,
+  // so templates stay in the strict shared-risk lane rather than being treated as ordinary docs/assets.
+  /^templates\//,
+  /^scripts\//,
+  /(^|\/)(AGENTS|CLAUDE)\.md$/,
+];
+
+export function parseJsonInput(raw, fallback = {}) {
+  try {
+    return JSON.parse(String(raw || '').trim() || '{}');
+  } catch {
+    return fallback;
+  }
+}
+
+export async function readRuntimeSafePatchConfig(projectRoot) {
+  const configPath = path.join(projectRoot, '.ukit', 'storage', 'config.json');
+  try {
+    const raw = await fs.readFile(configPath, 'utf8');
+    const config = JSON.parse(raw);
+    return { ...DEFAULT_SAFE_PATCH_CONFIG, ...(config.safePatch && typeof config.safePatch === 'object' ? config.safePatch : {}) };
+  } catch {
+    return { ...DEFAULT_SAFE_PATCH_CONFIG };
+  }
+}
+
+export function normalizeRelativePath(value) {
+  return String(value || '').trim().replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+export function resolveProjectFile(projectRoot, filePath) {
+  const root = path.resolve(projectRoot || process.cwd());
+  const raw = String(filePath || '').trim();
+  if (!raw) return null;
+  const absolute = path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(root, raw);
+  const relative = path.relative(root, absolute);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error(`Path escapes project root: ${filePath}`);
+  }
+  return {
+    absolute,
+    relative: normalizeRelativePath(relative),
+  };
+}
+
+export async function pathExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function classifySafePatchRisk(relativePath, profile = null, config = DEFAULT_SAFE_PATCH_CONFIG) {
+  const normalized = normalizeRelativePath(relativePath);
+  const labels = [];
+  if (SHARED_RISK_PATTERNS.some((pattern) => pattern.test(normalized))) {
+    labels.push('shared-risk');
+  }
+  if (profile?.size > Number(config.largeFileByteThreshold || DEFAULT_SAFE_PATCH_CONFIG.largeFileByteThreshold)) {
+    labels.push('large-file');
+  }
+  if (profile?.text) {
+    const lines = profile.text.split(/\r\n|\n|\r/).length;
+    if (lines > Number(config.largeFileLineThreshold || DEFAULT_SAFE_PATCH_CONFIG.largeFileLineThreshold)) {
+      labels.push('large-file');
+    }
+  }
+  if (profile?.hasBom) labels.push('bom-sensitive');
+  if (profile?.newline === 'CRLF' || profile?.newline === 'CR' || profile?.newline === 'mixed') labels.push('newline-sensitive');
+  if (profile?.text && /[^\x00-\x7f]/.test(profile.text)) labels.push('multilingual-text');
+  if (profile?.shebangHasBom) labels.push('shebang-bom');
+  if (profile?.binaryLike || profile?.utf8Valid === false) labels.push('non-text');
+
+  return {
+    labels: [...new Set(labels)],
+    strict: labels.includes('shared-risk') || labels.includes('large-file') || labels.includes('shebang-bom'),
+  };
+}
+
+export function countOccurrences(text, needle) {
+  const haystack = String(text ?? '');
+  const query = String(needle ?? '');
+  if (!query) return { count: 0, indexes: [] };
+  const indexes = [];
+  let start = 0;
+  while (start <= haystack.length) {
+    const index = haystack.indexOf(query, start);
+    if (index === -1) break;
+    indexes.push(index);
+    start = index + Math.max(query.length, 1);
+  }
+  return { count: indexes.length, indexes };
+}
+
+export function lineNumberForIndex(text, index) {
+  return String(text ?? '').slice(0, Math.max(0, index)).split(/\n/).length;
+}
+
+export function buildLineWindow(text, line, contextLines = 3) {
+  const lines = String(text ?? '').split(/\r\n|\n|\r/);
+  const startLine = Math.max(1, Number(line || 1) - contextLines);
+  const endLine = Math.min(lines.length, Number(line || 1) + contextLines);
+  return {
+    startLine,
+    endLine,
+    text: lines.slice(startLine - 1, endLine).join('\n'),
+  };
+}
+
+export function summarizeSnippet(value, max = 240) {
+  const compact = String(value || '').replace(/\s+/g, ' ').trim();
+  return compact.length > max ? `${compact.slice(0, max - 3)}...` : compact;
+}

package/templates/.claude/ukit/runtime/text-profile.mjs

@@ -0,0 +1,139 @@
+import fs from 'node:fs/promises';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const UTF8_BOM = Buffer.from([0xef, 0xbb, 0xbf]);
+
+export function analyzeTextBuffer(buffer) {
+  const bytes = Buffer.isBuffer(buffer) ? buffer : Buffer.from(buffer ?? '');
+  const hasBom = bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf;
+  const body = hasBom ? bytes.subarray(3) : bytes;
+  const sha256 = crypto.createHash('sha256').update(bytes).digest('hex');
+  const binaryLike = looksBinaryLike(body);
+
+  let text = '';
+  let utf8Valid = false;
+  let decodeError = null;
+  if (!binaryLike) {
+    try {
+      text = new TextDecoder('utf-8', { fatal: true }).decode(body);
+      utf8Valid = true;
+    } catch (error) {
+      decodeError = error?.message || String(error);
+    }
+  }
+
+  const newline = utf8Valid ? detectNewlineStyle(text) : 'unknown';
+  const hasFinalNewline = utf8Valid ? /(?:\r\n|\n|\r)$/.test(text) : false;
+  const shebangHasBom = hasBom && body.length >= 2 && body[0] === 0x23 && body[1] === 0x21;
+
+  return {
+    hasBom,
+    newline,
+    hasFinalNewline,
+    binaryLike,
+    utf8Valid,
+    sha256,
+    size: bytes.length,
+    text,
+    bodySize: body.length,
+    shebangHasBom,
+    ...(decodeError ? { decodeError } : {}),
+  };
+}
+
+export async function analyzeTextFile(filePath) {
+  const buffer = await fs.readFile(filePath);
+  return analyzeTextBuffer(buffer);
+}
+
+export function publicTextProfile(profile) {
+  return {
+    hasBom: Boolean(profile?.hasBom),
+    newline: profile?.newline ?? 'unknown',
+    hasFinalNewline: Boolean(profile?.hasFinalNewline),
+    binaryLike: Boolean(profile?.binaryLike),
+    utf8Valid: Boolean(profile?.utf8Valid),
+    sha256: profile?.sha256 ?? '',
+    size: Number(profile?.size ?? 0),
+    shebangHasBom: Boolean(profile?.shebangHasBom),
+  };
+}
+
+export function encodeTextWithProfile(text, profile = {}) {
+  const encoded = Buffer.from(String(text ?? ''), 'utf8');
+  return profile.hasBom ? Buffer.concat([UTF8_BOM, encoded]) : encoded;
+}
+
+export function normalizeNewlinesForProfile(text, profile = {}) {
+  const value = String(text ?? '');
+  if (profile.newline !== 'CRLF' && profile.newline !== 'CR') {
+    return value;
+  }
+
+  const normalized = value.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+  if (profile.newline === 'CR') {
+    return normalized.replace(/\n/g, '\r');
+  }
+  return normalized.replace(/\n/g, '\r\n');
+}
+
+export async function writeTextWithProfile(filePath, text, profile = {}) {
+  await fs.writeFile(filePath, encodeTextWithProfile(text, profile));
+}
+
+function detectNewlineStyle(text) {
+  const crlf = (text.match(/\r\n/g) || []).length;
+  const bareLf = (text.match(/(?<!\r)\n/g) || []).length;
+  const bareCr = (text.match(/\r(?!\n)/g) || []).length;
+  const styles = [crlf > 0 ? 'CRLF' : null, bareLf > 0 ? 'LF' : null, bareCr > 0 ? 'CR' : null].filter(Boolean);
+  if (styles.length === 0) return 'none';
+  if (styles.length === 1) return styles[0];
+  return 'mixed';
+}
+
+function looksBinaryLike(buffer) {
+  if (!buffer || buffer.length === 0) return false;
+  const sample = buffer.subarray(0, Math.min(buffer.length, 4096));
+  let suspicious = 0;
+  for (const byte of sample) {
+    if (byte === 0) return true;
+    if (byte < 0x09) suspicious += 1;
+    if (byte > 0x0d && byte < 0x20) suspicious += 1;
+  }
+  return suspicious / sample.length > 0.15;
+}
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const args = { json: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--json') args.json = true;
+    else if (arg === '--file') args.file = argv[++i];
+    else if (arg === '--help' || arg === '-h') args.help = true;
+  }
+  return args;
+}
+
+async function main() {
+  const args = parseArgs();
+  if (args.help || !args.file) {
+    const help = 'Usage: node text-profile.mjs --file <path> [--json]';
+    process.stdout.write(args.json ? `${JSON.stringify({ help })}\n` : `${help}\n`);
+    return;
+  }
+  const profile = publicTextProfile(await analyzeTextFile(args.file));
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify({ profile })}\n`);
+  } else {
+    process.stdout.write(`[ukit:text-profile] ${args.file} bom=${profile.hasBom ? 'yes' : 'no'} newline=${profile.newline} utf8=${profile.utf8Valid ? 'valid' : 'invalid'} bytes=${profile.size}\n`);
+  }
+}
+
+if (process.argv[1] && path.basename(fileURLToPath(import.meta.url)) === path.basename(process.argv[1])) {
+  main().catch((error) => {
+    process.stderr.write(`[ukit:text-profile] ERROR: ${error?.message || error}\n`);
+    process.exit(1);
+  });
+}

package/templates/.codex/README.md

@@ -12,10 +12,10 @@ Auto-generated by UKit for OpenAI Codex.
 - Do not make end users memorize skill names, helper scripts, or routing internals unless they are debugging UKit itself.
 - **Treat helper commands as internal orchestration. Do not ask end users to run them.**
 
-## UKit v1.2.1 Shared Runtime
+## UKit v1.3.0 Shared Runtime
 
 - Shared runtime state lives in `.ukit/storage/`.
-- Treat `.ukit/storage/config.json` as the source of compact, token-pipeline, router, memory, and validation toggles.
+- Treat `.ukit/storage/config.json` as the source of compact, token-pipeline, router, memory, validation, and Safe Patch guardrail toggles.
 - Reuse `.ukit/storage/memory/` before asking users to restate prior decisions.
 - For non-trivial work, prefer `ukit memory recall "<current task>"` before widening docs.
 - Reusable cache state lives in `.ukit/storage/cache/prompt-cache.json`, `.ukit/storage/cache/compact-history.json`, `.ukit/storage/cache/compact-pressure.json`, `.ukit/storage/cache/output-history.json`, and preserved raw tool outputs under `.ukit/storage/cache/tee/`.
@@ -23,7 +23,8 @@ Auto-generated by UKit for OpenAI Codex.
 - Maintainers can inspect runtime state with `ukit status` and `ukit memory export`.
 - Reuse compact `previous-context` / `recent-output` route snapshots before replaying raw history.
 - Threshold-based compact pressure is internal orchestration; Codex users should not need to manage it manually.
-- UKit keeps Claude PreCompact/reinject and OpenCode native auto/prune compaction intact. For Codex Desktop long sessions, UKit can use `UKIT_SMALL_TASK_MODEL` through `ukit-small-task-maintainer` to decide soft auto-compact handoffs. Default `UKIT_CODEX_COMPACT_TARGET=150` means about 150 compact handoff lines (120-150 preferred, hard max 170), not 150 app-context tokens.
+- UKit keeps Claude PreCompact/reinject and OpenCode native auto/prune compaction intact. For Codex Desktop long sessions, UKit can use `subagents.smallTaskModel` through `ukit-small-task-maintainer` to decide soft auto-compact handoffs. Default `compact.codexContext.compactTarget=150` means about 150 compact handoff lines (120-150 preferred, hard max 170), not 150 app-context tokens.
+- Safe Patch Protocol is internal: for risky file edits, prefer current-file anchors and exact specs, avoid whole-file rewrites, and preserve multilingual/BOM/newline profiles. Do not ask normal users to run helper commands.
 
 ## Speed / Reading Contract
 

package/templates/.codex/settings.json

@@ -148,7 +148,6 @@
       }
     },
     "smallTaskModel": {
-      "env": "UKIT_SMALL_TASK_MODEL",
       "default": "unic-lite",
       "agent": "ukit-small-task-maintainer",
       "useFor": [
@@ -209,12 +208,9 @@
       },
       "codexContext": {
         "autoCompact": true,
-        "budgetTokens": 60000,
+        "budgetTokens": 100000,
         "compactTarget": 150,
         "compactTargetUnit": "lines",
-        "targetEnv": "UKIT_CODEX_COMPACT_TARGET",
-        "budgetEnv": "UKIT_CODEX_CONTEXT_BUDGET",
-        "autoCompactEnv": "UKIT_CODEX_AUTO_COMPACT",
         "mode": "soft-handoff",
         "preserve": [
           "current-goal",
@@ -229,19 +225,20 @@
           120,
           170
         ],
-        "compactTargetMax": 170
+        "compactTargetMax": 170,
+        "configPath": ".ukit/storage/config.json",
+        "targetField": "compact.codexContext.compactTarget",
+        "budgetField": "compact.codexContext.budgetTokens",
+        "autoCompactField": "compact.codexContext.autoCompact"
       },
       "agentContext": {
         "preserveClaudePreCompact": true,
         "preserveOpenCodeCompaction": true,
         "codexSoftHandoff": {
           "autoCompact": true,
-          "budgetTokens": 60000,
+          "budgetTokens": 100000,
           "compactTarget": 150,
           "compactTargetUnit": "lines",
-          "targetEnv": "UKIT_CODEX_COMPACT_TARGET",
-          "budgetEnv": "UKIT_CODEX_CONTEXT_BUDGET",
-          "autoCompactEnv": "UKIT_CODEX_AUTO_COMPACT",
           "mode": "soft-handoff",
           "preserve": [
             "current-goal",
@@ -258,7 +255,9 @@
           ],
           "compactTargetMax": 170
         }
-      }
+      },
+      "configPath": ".ukit/storage/config.json",
+      "configField": "subagents.smallTaskModel"
     }
   },
   "execution": {

package/templates/.gitignore

@@ -18,7 +18,6 @@ out/
 .env.development.local
 .env.test.local
 .env.production.local
-.claude/ukit/.env
 
 # Logs
 logs/

package/templates/AGENTS.md

@@ -43,10 +43,10 @@
 - If a concrete verification lane is needed, prefer `node .claude/ukit/index/verify-context.mjs ...`.
 - These helper/index commands are internal orchestration. Run them yourself when needed; never turn them into required end-user workflow.
 
-## UKit v1.2.1 Shared Runtime
+## UKit v1.3.0 Shared Runtime
 
 - Shared runtime state lives in `.ukit/storage/`.
-- Treat `.ukit/storage/config.json` as the source of runtime toggles for compact, token pipeline, router, memory, and validation behavior.
+- Treat `.ukit/storage/config.json` as the source of runtime toggles for compact, token pipeline, router, memory, validation, and Safe Patch behavior.
 - Reuse `.ukit/storage/memory/` before asking users to restate prior decisions.
 - For non-trivial work, prefer `ukit memory recall "<current task>"` before widening doc reads.
 - Reusable runtime cache lives in `.ukit/storage/cache/prompt-cache.json`, `.ukit/storage/cache/compact-history.json`, and `.ukit/storage/cache/output-history.json`.
@@ -78,10 +78,10 @@
 
 ## Small-Task Maintainer (internal)
 
-- UKit may route low-risk internal decisions to the `ukit-small-task-maintainer` subagent using `UKIT_SMALL_TASK_MODEL` (default `unic-lite`).
+- UKit may route low-risk internal decisions to the `ukit-small-task-maintainer` subagent using `subagents.smallTaskModel` (default `unic-lite`).
 - Use it for safe/reversible UKit chores: dọn `docs/TASKS.md`, queued-task classification, fast-vs-slow/safe-vs-risky lane decisions, skill-routing/step-budget hints, agent context-budget decisions, compact/summary decisions, docs/status summarization, auto-triage, queue maintenance, and small workspace cleanup.
 - Run it as a sidecar/parallel lane only; do not block, replace, or slow the user task. Do not block the main AI flow: if the small-task lane sees security, risky/shared code, release/publish, data-loss, architecture, deep-reasoning risk, weak context, or quality risk, it hands back to the main model instead of asking the end user to decide.
-- This is optional internal orchestration config from `.claude/ukit/.env` / `.ukit/storage/config.json`; never turn it into an end-user workflow. End users still only need `ukit install` and natural-language product work. Always preserve the CoDev priority: quality > safety > speed > token discipline. Keep Claude PreCompact/reinject and OpenCode native auto/prune compaction enabled. For Codex Desktop long sessions, `UKIT_CODEX_COMPACT_TARGET` defaults to 150 compact handoff lines (120-150 preferred, hard max 170), decided internally by the small-task maintainer.
+- This is optional internal orchestration config from `.ukit/storage/config.json`; never turn it into an end-user workflow. End users still only need `ukit install` and natural-language product work. Always preserve the CoDev priority: quality > safety > speed > token discipline. Keep Claude PreCompact/reinject and OpenCode native auto/prune compaction enabled. For Codex Desktop long sessions, `compact.codexContext.compactTarget` defaults to 150 compact handoff lines (120-150 preferred, hard max 170), decided internally by the small-task maintainer.
 
 ## Subagent Policy (internal only)
 
@@ -95,6 +95,13 @@
 - If route memory already includes `delegate=<lane>`, treat it as an internal hint after any required indexed-context step.
 - Do not ask end users to name agents or remember agent commands.
 
+## Safe Patch Protocol
+
+- Safe Patch is internal orchestration: normal users still only need `ukit install` and natural language.
+- For risky/shared/large edits, prefer unique current-file anchors over line numbers or stale pasted blocks.
+- Do not silently merge stale specs: if `old_string` is missing or ambiguous, re-read current source and ask whether to apply as-is, adapt, or skip.
+- Preserve UTF-8 BOM/no-BOM and LF/CRLF for existing multilingual/user-authored files; use UKit safe patch helpers internally when normal Edit/Write may normalize bytes.
+
 ## Team Workflow Safety
 
 - Do not teach normal contributors `ukit doctor`, `ukit diff`, `ukit uninstall`, or `ukit index ...` unless they are explicitly debugging UKit itself.

package/templates/CLAUDE.md

@@ -42,10 +42,10 @@
 - **Do not ask normal contributors to run internal helper commands**; run them yourself or tell them to rerun `ukit install`.
 - Do not ask normal contributors to memorize `ukit doctor`, `ukit diff`, `ukit uninstall`, or `ukit index ...` unless they explicitly need maintainer/debug help.
 
-## UKit v1.2.1 Shared Runtime
+## UKit v1.3.0 Shared Runtime
 
 - Shared runtime state lives in `.ukit/storage/`.
-- Treat `.ukit/storage/config.json` as the source of runtime toggles for compact, token pipeline, router, memory, and validation behavior.
+- Treat `.ukit/storage/config.json` as the source of runtime toggles for compact, token pipeline, router, memory, validation, and Safe Patch behavior.
 - Reuse `.ukit/storage/memory/` before asking users to restate decisions.
 - For non-trivial work, prefer `ukit memory recall "<current task>"` before widening doc reads.
 - Reusable cache/compact/output state lives in `.ukit/storage/cache/prompt-cache.json`, `.ukit/storage/cache/compact-history.json`, and `.ukit/storage/cache/output-history.json`.
@@ -53,6 +53,14 @@
 - Maintainers can inspect runtime state with `ukit status` and `ukit memory export`.
 - If runtime files are missing or corrupt, tell maintainers to rerun `ukit install`.
 
+
+## Safe Patch Protocol
+
+- Safe Patch is internal orchestration: normal users still only need `ukit install` and natural language.
+- For risky/shared/large edits, prefer unique current-file anchors over line numbers or stale pasted blocks.
+- Do not silently merge stale specs: if `old_string` is missing or ambiguous, re-read current source and ask whether to apply as-is, adapt, or skip.
+- Preserve UTF-8 BOM/no-BOM and LF/CRLF for existing multilingual/user-authored files; use UKit safe patch helpers internally when normal Edit/Write may normalize bytes.
+
 ## Context + Verification Budget
 
 - **Trivial**: no docs.
@@ -75,10 +83,10 @@
 
 ## Small-Task Maintainer (internal)
 
-- UKit may route low-risk internal decisions to the `ukit-small-task-maintainer` subagent using `UKIT_SMALL_TASK_MODEL` (default `unic-lite`).
+- UKit may route low-risk internal decisions to the `ukit-small-task-maintainer` subagent using `subagents.smallTaskModel` (default `unic-lite`).
 - Use it for safe/reversible UKit chores: dọn `docs/TASKS.md`, queued-task classification, fast-vs-slow/safe-vs-risky lane decisions, skill-routing/step-budget hints, agent context-budget decisions, compact/summary decisions, docs/status summarization, auto-triage, queue maintenance, and small workspace cleanup.
 - Run it as a sidecar/parallel lane only; do not block, replace, or slow the user task. Do not block the main AI flow: if the small-task lane sees security, risky/shared code, release/publish, data-loss, architecture, deep-reasoning risk, weak context, or quality risk, it hands back to the main model instead of asking the end user to decide.
-- This is optional internal orchestration config from `.claude/ukit/.env` / `.ukit/storage/config.json`; never turn it into an end-user workflow. End users still only need `ukit install` and natural-language product work. Always preserve the CoDev priority: quality > safety > speed > token discipline. Keep Claude PreCompact/reinject and OpenCode native auto/prune compaction enabled. For Codex Desktop long sessions, `UKIT_CODEX_COMPACT_TARGET` defaults to 150 compact handoff lines (120-150 preferred, hard max 170), decided internally by the small-task maintainer.
+- This is optional internal orchestration config from `.ukit/storage/config.json`; never turn it into an end-user workflow. End users still only need `ukit install` and natural-language product work. Always preserve the CoDev priority: quality > safety > speed > token discipline. Keep Claude PreCompact/reinject and OpenCode native auto/prune compaction enabled. For Codex Desktop long sessions, `compact.codexContext.compactTarget` defaults to 150 compact handoff lines (120-150 preferred, hard max 170), decided internally by the small-task maintainer.
 
 ## Selective Subagent Policy (internal only)
 

package/templates/ukit/README.md

@@ -1,6 +1,6 @@
 # UKit Shared Runtime
 
-This folder stores shared UKit runtime state for v1.2.1 features.
+This folder stores shared UKit runtime state for v1.3.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/`