@ngockhoale/ukit 1.2.1 → 1.3.0

package/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to UKit are documented here.
 
 ## Unreleased
 
+## 1.3.0 - 2026-05-06
+
+### Added
+
+- Added UKit Safe Patch Protocol guardrails for risky AI edits: stale/ambiguous `old_string` detection, whole-file shared-risk `Write` blocking, anchor-search helper, safe patch helper, text-profile detection, and pre-edit rollback bytes for shared-risk files.
+- Added post-edit delta verification for backed-up shared-risk edits so unexpected broad rewrites are flagged against the Safe Patch hunk/changed-line budget and rollback manifests record after hashes.
+- Added Safe Patch backup retention and bounded delta-diff fallback so rollback data does not grow forever and very large edits avoid unbounded LCS memory use.
+- Added byte-first UTF-8/BOM/newline profile handling so helper-mediated patches preserve UTF-8 BOM/no-BOM, LF/CRLF, Vietnamese/CJK/emoji content, and reject unsafe binary/invalid UTF-8 edit paths.
+- Added `safePatch` runtime config defaults under `.ukit/storage/config.json` while keeping the end-user workflow unchanged: normal users still only need `ukit install`; helpers remain internal guardrails.
+
+### Changed
+
+- Promoted shared-risk edit routing to surface an internal `editGuard=anchor-required` hint for installed runtime/template targets.
+- Extended impact-risk classification to installed runtime paths such as `.claude/hooks/**`, `.claude/ukit/**`, and `.codex/**`.
+
+### Tests
+
+- Added focused Safe Patch Protocol hook/helper coverage and install wiring coverage.
+
+## 1.2.2 - 2026-05-05
+
+- Removed the `.claude/ukit/.env` / `.env.example` config surface so UKit runtime tuning lives in `.ukit/storage/config.json` only.
+- Added full Vietnamese `_help` guidance inside `templates/ukit/storage/config.json`, including common edits for changing the internal model and Codex compact thresholds.
+- Set Codex Desktop compact budget default to 100,000 tokens as a quality/safety balance, with compact handoff target 150 lines and hard max 170 lines.
+- Preserved Claude PreCompact/reinject and OpenCode native auto/prune compaction while keeping `ukit-small-task-maintainer` as a non-blocking sidecar lane.
+
 ## 1.2.1 - 2026-05-05
 
 ### Local AI Task Queue
@@ -13,7 +39,7 @@ All notable changes to UKit are documented here.
 - Added safe default cleanup rules: remove exact duplicates, prune `Done Recently` to 10 compact lines, move stale/vague work to deferred review, and never delete unfinished human-authored tasks unless explicitly asked and clearly obsolete/duplicated.
 - Updated `next-step`, `update-status`, and `docs-quality` guidance plus route signals so queued-task selection goes to `next-step` while task cleanup/editing goes to `docs-quality`.
 - Added `docs/STATUS.md` and `docs/TASKS.md` to generated gitignore handling so living local AI state does not pollute project commits.
-- Added the internal `ukit-small-task-maintainer` subagent, powered by optional `UKIT_SMALL_TASK_MODEL=unic-lite`, for safe UKit decisions such as task cleanup, compact decisions, doc summarization, classification, auto-triage, queue maintenance, and small reversible cleanup while keeping risky/security/release work on the main model.
+- Added the internal `ukit-small-task-maintainer` subagent, powered by optional `subagents.smallTaskModel=unic-lite`, for safe UKit decisions such as task cleanup, compact decisions, doc summarization, classification, auto-triage, queue maintenance, and small reversible cleanup while keeping risky/security/release work on the main model.
 
 ## 1.1.8 - 2026-05-05
 

package/README.md

@@ -68,13 +68,14 @@ If maintainers roll out a newer CLI build, the in-project workflow still stays t
 - `.ukit/` — hidden shared runtime storage for config, cache, and cross-agent memory
 - `docs/` — PROJECT / MEMORY / STATUS / TASKS / WORKLOG baseline
 
-## UKit v1.2.1 Runtime
+## UKit v1.3.0 Runtime
 
 UKit now installs a hidden shared local runtime at `.ukit/` for production-oriented state that should survive across agent sessions:
 
 - `.ukit/storage/config.json` — runtime defaults for compact/router/memory/validation/subagent hints
 - `.ukit/storage/cache/` — reusable prompt-cache, compact history, compact-pressure state, and output summaries
 - `.ukit/storage/memory/` — cross-agent local memory
+- `.ukit/storage/backups/` — rollback bytes for risky Safe Patch Protocol edits
 
 If an older repo still has a visible legacy `ukit/` runtime folder, rerunning `ukit install` now migrates the shared runtime into hidden `.ukit/` when the target paths are free.
 
@@ -85,7 +86,7 @@ When long sessions approach the compact threshold, UKit now uses a conservative
 - compact only safe-zone history/noise
 - preserve active task, rules, decisions, and current code focus
 
-UKit v1.2.1 keeps the same shared runtime contract while adding a local AI task queue alongside living project status routing:
+UKit v1.3.0 keeps the same shared runtime contract while adding Safe Patch Protocol guardrails and the local AI task queue alongside living project status routing:
 
 - install globally with `npm install -g @ngockhoale/ukit`
 - keep using the exact same human workflow inside projects: `ukit install`
@@ -95,8 +96,9 @@ UKit v1.2.1 keeps the same shared runtime contract while adding a local AI task
 - auto-route open-ended “what next?” / “continue” prompts to the `next-step` skill with a visible freshness cue when status may be stale
 - auto-route explicit handoff/wrap-up requests to the `update-status` skill while skipping trivial/no-state-change tasks
 - keep concrete debug/implementation/review prompts primary, so project status never replaces source/index-first task work
+- quietly guard risky AI edits with Safe Patch Protocol: stale/ambiguous specs are blocked, shared-risk whole-file writes are discouraged, and internal helpers preserve UTF-8 BOM/no-BOM plus LF/CRLF for multilingual text
 
-UKit v1.2.1 also keeps the fast path improvements from the recent runtime releases:
+UKit v1.3.0 also keeps the fast path improvements from the recent runtime releases:
 
 - Vietnamese prompts now normalize more effectively for English-heavy code symbols and paths
 - localized simple direct-target lanes skip extra previous-context / recent-output work when it would not change the next action
@@ -131,8 +133,8 @@ UKit is built so the team can stop memorizing UKit subcommands and focus on prod
 - let Claude Code / Codex / OpenCode auto-detect and use the right project-local skill from the prompt and the files/tools involved
 - let the AI prefer targeted verification first, then widen only when shared/risky scope justifies it
 - let the AI selectively auto-delegate internal subagents only when that actually reduces context/noise or unlocks parallel progress; small localized work should stay direct
-- keep long sessions compact across agents: Claude keeps PreCompact/reinject, OpenCode keeps native auto/prune compaction, and Codex Desktop uses internal `UKIT_CODEX_COMPACT_TARGET` soft handoffs (default 150 lines; 120-150 preferred, hard max 170), without asking end users to manage context manually
-- let UKit internally use the `ukit-small-task-maintainer` subagent with `UKIT_SMALL_TASK_MODEL=unic-lite` for safe task cleanup, fast-vs-slow/safe-vs-risky lane hints, skill-routing/step-budget hints, agent context-budget decisions, compact decisions, doc summarization, classification, and queue maintenance while risky/security/release/quality-risk work stays on the main model
+- keep long sessions compact across agents: Claude keeps PreCompact/reinject, OpenCode keeps native auto/prune compaction, and Codex Desktop uses internal `compact.codexContext.compactTarget` soft handoffs (default 150 lines; 120-150 preferred, hard max 170), without asking end users to manage context manually
+- let UKit internally use the `ukit-small-task-maintainer` subagent with `subagents.smallTaskModel=unic-lite` for safe task cleanup, fast-vs-slow/safe-vs-risky lane hints, skill-routing/step-budget hints, agent context-budget decisions, compact decisions, doc summarization, classification, and queue maintenance while risky/security/release/quality-risk work stays on the main model
 - rerun `ukit install` when you need to refresh the workspace
 
 End users should **not** need to know or memorize skill names.

package/manifests/platform.full.yaml

@@ -77,18 +77,6 @@ items:
     packs:
       - core
 
-  - id: ukit-env-example
-    type: config
-    sourceTemplate: .claude/ukit/.env.example
-    targetPath: .claude/ukit/.env.example
-    requires:
-      - runtime-config
-    mergeStrategy: overwrite_with_backup
-    variables: []
-    enabledByDefault: true
-    packs:
-      - core
-
   - id: root-claude-md
     type: config
     sourceTemplate: CLAUDE.md
@@ -824,7 +812,7 @@ items:
     sourceTemplate: .claude/agents/ukit-small-task-maintainer.md
     targetPath: .claude/agents/ukit-small-task-maintainer.md
     requires:
-      - ukit-env-example
+      - runtime-config
     mergeStrategy: overwrite_with_backup
     variables:
       - ukit.version
@@ -850,6 +838,9 @@ items:
     targetPath: .claude/settings.json
     requires:
       - hook-protect-files
+      - hook-stale-spec-guard
+      - hook-pre-edit-backup
+      - hook-post-edit-verify
       - hook-auto-allow-bash
       - hook-block-dangerous
       - hook-auto-prune-bash
@@ -881,6 +872,42 @@ items:
     packs:
       - core
 
+  - id: hook-stale-spec-guard
+    type: hook
+    sourceTemplate: .claude/hooks/stale-spec-guard.sh
+    targetPath: .claude/hooks/stale-spec-guard.sh
+    requires:
+      - ukit-index-stale-spec-check-script
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: hook-pre-edit-backup
+    type: hook
+    sourceTemplate: .claude/hooks/pre-edit-backup.sh
+    targetPath: .claude/hooks/pre-edit-backup.sh
+    requires:
+      - ukit-index-pre-edit-backup-script
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: hook-post-edit-verify
+    type: hook
+    sourceTemplate: .claude/hooks/post-edit-verify.sh
+    targetPath: .claude/hooks/post-edit-verify.sh
+    requires:
+      - ukit-index-post-edit-verify-script
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: hook-auto-allow-bash
     type: hook
     sourceTemplate: .claude/hooks/auto-allow-bash.sh
@@ -973,6 +1000,93 @@ items:
     packs:
       - core
 
+  - id: ukit-runtime-text-profile-script
+    type: config
+    sourceTemplate: .claude/ukit/runtime/text-profile.mjs
+    targetPath: .claude/ukit/runtime/text-profile.mjs
+    requires: []
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: ukit-runtime-safe-patch-core-script
+    type: config
+    sourceTemplate: .claude/ukit/runtime/safe-patch-core.mjs
+    targetPath: .claude/ukit/runtime/safe-patch-core.mjs
+    requires:
+      - ukit-runtime-text-profile-script
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: ukit-index-anchor-search-script
+    type: config
+    sourceTemplate: .claude/ukit/index/anchor-search.mjs
+    targetPath: .claude/ukit/index/anchor-search.mjs
+    requires:
+      - ukit-runtime-text-profile-script
+      - ukit-runtime-safe-patch-core-script
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: ukit-index-safe-patch-script
+    type: config
+    sourceTemplate: .claude/ukit/index/safe-patch.mjs
+    targetPath: .claude/ukit/index/safe-patch.mjs
+    requires:
+      - ukit-index-anchor-search-script
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: ukit-index-stale-spec-check-script
+    type: config
+    sourceTemplate: .claude/ukit/index/stale-spec-check.mjs
+    targetPath: .claude/ukit/index/stale-spec-check.mjs
+    requires:
+      - ukit-runtime-text-profile-script
+      - ukit-runtime-safe-patch-core-script
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: ukit-index-pre-edit-backup-script
+    type: config
+    sourceTemplate: .claude/ukit/index/pre-edit-backup.mjs
+    targetPath: .claude/ukit/index/pre-edit-backup.mjs
+    requires:
+      - ukit-runtime-text-profile-script
+      - ukit-runtime-safe-patch-core-script
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: ukit-index-post-edit-verify-script
+    type: config
+    sourceTemplate: .claude/ukit/index/post-edit-verify.mjs
+    targetPath: .claude/ukit/index/post-edit-verify.mjs
+    requires:
+      - ukit-runtime-text-profile-script
+      - ukit-runtime-safe-patch-core-script
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: ukit-index-core-lib
     type: config
     sourceTemplate: .claude/ukit/index/lib/index-core.mjs

package/package.json

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

package/src/core/runInstallPipeline.js

@@ -18,6 +18,10 @@ const AUTO_PRUNE_OBSOLETE_PREFIXES = [
   '.claude/skills/',
 ];
 
+const AUTO_PRUNE_OBSOLETE_PATHS = new Set([
+  '.claude/ukit/.env.example',
+]);
+
 function normalizeRelativePath(relativePath) {
   if (typeof relativePath !== 'string') {
     return null;
@@ -49,7 +53,8 @@ function buildTrackedManagedRelativePathSet(plan, projectRoot) {
 }
 
 function shouldAutoPruneObsoletePath(relativePath) {
-  return AUTO_PRUNE_OBSOLETE_PREFIXES.some((prefix) => relativePath.startsWith(prefix));
+  return AUTO_PRUNE_OBSOLETE_PATHS.has(relativePath)
+    || AUTO_PRUNE_OBSOLETE_PREFIXES.some((prefix) => relativePath.startsWith(prefix));
 }
 
 async function isDirEmpty(dirPath) {

package/src/core/runtimeConfig.js

@@ -45,103 +45,11 @@ function pushNonEmptyStringError(errors, value, label) {
   }
 }
 
-function parseRuntimeEnv(content = '') {
-  const result = {};
-  for (const rawLine of String(content || '').split(/\r?\n/)) {
-    const line = rawLine.trim();
-    if (!line || line.startsWith('#') || !line.includes('=')) {
-      continue;
-    }
-    const index = line.indexOf('=');
-    const key = line.slice(0, index).trim();
-    let value = line.slice(index + 1).trim();
-    if (
-      (value.startsWith('"') && value.endsWith('"'))
-      || (value.startsWith("'") && value.endsWith("'"))
-    ) {
-      value = value.slice(1, -1);
-    }
-    result[key] = value;
-  }
-  return result;
-}
-
-async function loadRuntimeEnv(projectRoot) {
-  const envPath = path.join(projectRoot, '.claude', 'ukit', '.env');
-  try {
-    return parseRuntimeEnv(await fs.readFile(envPath, 'utf8'));
-  } catch (error) {
-    if (error?.code !== 'ENOENT') {
-      throw error;
-    }
-    return {};
-  }
-}
-
-function parsePositiveIntegerEnv(value) {
-  if (typeof value !== 'string' || value.trim() === '') {
-    return null;
-  }
-  const parsed = Number.parseInt(value.trim(), 10);
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
-}
-
-function buildEnvOverrides(env = process.env) {
-  const overrides = {};
-  const smallTaskModel = env.UKIT_SMALL_TASK_MODEL;
-  if (typeof smallTaskModel === 'string' && smallTaskModel.trim() !== '') {
-    overrides.subagents = {
-      ...(overrides.subagents ?? {}),
-      smallTaskModel: smallTaskModel.trim(),
-    };
-  }
-
-  const rawCodexCompactTarget = parsePositiveIntegerEnv(env.UKIT_CODEX_COMPACT_TARGET);
-  const codexCompactTarget = rawCodexCompactTarget ? Math.min(rawCodexCompactTarget, 170) : null;
-  const codexContextBudget = parsePositiveIntegerEnv(env.UKIT_CODEX_CONTEXT_BUDGET);
-  const codexAutoCompact = typeof env.UKIT_CODEX_AUTO_COMPACT === 'string'
-    ? !['0', 'false', 'no', 'off'].includes(env.UKIT_CODEX_AUTO_COMPACT.trim().toLowerCase())
-    : null;
-
-  if (codexCompactTarget || codexContextBudget || codexAutoCompact !== null) {
-    overrides.compact = {
-      ...(overrides.compact ?? {}),
-      agentContext: {
-        enabled: true,
-        decisionModelEnv: 'UKIT_SMALL_TASK_MODEL',
-        decisionAgent: 'ukit-small-task-maintainer',
-        executionMode: 'sidecar-parallel',
-        mustNotBlockMainTask: true,
-        targets: {
-          claude: { autoCompact: true, mode: 'precompact-reinject', preserveExistingHooks: true },
-          opencode: { autoCompact: true, mode: 'native-auto-prune', preserveExistingCompaction: true },
-          codex: {
-            autoCompact: true,
-            mode: 'soft-handoff',
-            compactTarget: 150,
-            compactTargetUnit: 'lines',
-            compactTargetRecommendedRange: [120, 170],
-            compactTargetMax: 170,
-          },
-        },
-      },
-      codexContext: {
-        ...(overrides.compact?.codexContext ?? {}),
-        ...(codexCompactTarget ? { compactTarget: codexCompactTarget } : {}),
-        ...(codexContextBudget ? { budgetTokens: codexContextBudget } : {}),
-        ...(codexAutoCompact !== null ? { autoCompact: codexAutoCompact } : {}),
-      },
-    };
-  }
-
-  return overrides;
-}
-
 export function buildDefaultRuntimeConfig(overrides = {}) {
   const safeOverrides = isPlainObject(overrides) ? overrides : {};
 
   return mergeObjects({
-    version: '1.2.1',
+    version: '1.3.0',
     agent: 'claude-code',
     compact: {
       enabled: true,
@@ -150,7 +58,6 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       askBeforeDrop: true,
       agentContext: {
         enabled: true,
-        decisionModelEnv: 'UKIT_SMALL_TASK_MODEL',
         decisionAgent: 'ukit-small-task-maintainer',
         executionMode: 'sidecar-parallel',
         mustNotBlockMainTask: true,
@@ -170,12 +77,11 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       codexContext: {
         enabled: true,
         autoCompact: true,
-        budgetTokens: 60_000,
+        budgetTokens: 100_000,
         compactTarget: 150,
         compactTargetUnit: 'lines',
         compactTargetRecommendedRange: [120, 170],
         compactTargetMax: 170,
-        decisionModelEnv: 'UKIT_SMALL_TASK_MODEL',
         decisionAgent: 'ukit-small-task-maintainer',
         mode: 'soft-handoff',
         preserve: [
@@ -216,6 +122,17 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       maxRetries: 1,
       confidenceThreshold: 50,
     },
+    safePatch: {
+      enabled: true,
+      strictSharedRisk: true,
+      largeFileLineThreshold: 800,
+      largeFileByteThreshold: 200_000,
+      backupEnabled: true,
+      backupRetentionDays: 30,
+      deltaMaxChangedLines: 120,
+      deltaMaxHunks: 3,
+      deltaMaxDiffCells: 2_000_000,
+    },
     subagents: {
       enabled: true,
       smallTaskModel: 'unic-lite',
@@ -292,7 +209,6 @@ export function validateRuntimeConfig(config) {
       errors.push('compact.agentContext must be an object.');
     } else {
       pushBooleanError(errors, config.compact.agentContext.enabled, 'compact.agentContext.enabled');
-      pushNonEmptyStringError(errors, config.compact.agentContext.decisionModelEnv, 'compact.agentContext.decisionModelEnv');
       pushNonEmptyStringError(errors, config.compact.agentContext.decisionAgent, 'compact.agentContext.decisionAgent');
       pushNonEmptyStringError(errors, config.compact.agentContext.executionMode, 'compact.agentContext.executionMode');
       pushBooleanError(errors, config.compact.agentContext.mustNotBlockMainTask, 'compact.agentContext.mustNotBlockMainTask');
@@ -315,7 +231,6 @@ export function validateRuntimeConfig(config) {
       if (Number(config.compact.codexContext.compactTarget) > Number(config.compact.codexContext.compactTargetMax)) {
         errors.push('compact.codexContext.compactTarget must be <= compact.codexContext.compactTargetMax.');
       }
-      pushNonEmptyStringError(errors, config.compact.codexContext.decisionModelEnv, 'compact.codexContext.decisionModelEnv');
       pushNonEmptyStringError(errors, config.compact.codexContext.decisionAgent, 'compact.codexContext.decisionAgent');
       pushNonEmptyStringError(errors, config.compact.codexContext.mode, 'compact.codexContext.mode');
       if (!Array.isArray(config.compact.codexContext.preserve)) {
@@ -367,6 +282,20 @@ export function validateRuntimeConfig(config) {
     pushPositiveNumberError(errors, config.validation.confidenceThreshold, 'validation.confidenceThreshold');
   }
 
+  if (!isPlainObject(config.safePatch)) {
+    errors.push('safePatch must be an object.');
+  } else {
+    pushBooleanError(errors, config.safePatch.enabled, 'safePatch.enabled');
+    pushBooleanError(errors, config.safePatch.strictSharedRisk, 'safePatch.strictSharedRisk');
+    pushPositiveNumberError(errors, config.safePatch.largeFileLineThreshold, 'safePatch.largeFileLineThreshold');
+    pushPositiveNumberError(errors, config.safePatch.largeFileByteThreshold, 'safePatch.largeFileByteThreshold');
+    pushBooleanError(errors, config.safePatch.backupEnabled, 'safePatch.backupEnabled');
+    pushPositiveNumberError(errors, config.safePatch.backupRetentionDays, 'safePatch.backupRetentionDays');
+    pushPositiveNumberError(errors, config.safePatch.deltaMaxChangedLines, 'safePatch.deltaMaxChangedLines');
+    pushPositiveNumberError(errors, config.safePatch.deltaMaxHunks, 'safePatch.deltaMaxHunks');
+    pushPositiveNumberError(errors, config.safePatch.deltaMaxDiffCells, 'safePatch.deltaMaxDiffCells');
+  }
+
   if (!isPlainObject(config.subagents)) {
     errors.push('subagents must be an object.');
   } else {
@@ -407,31 +336,19 @@ export async function inspectRuntimeConfig(projectRoot) {
     }
   }
 
-  let runtimeEnv = {};
-  let envError = null;
-  try {
-    runtimeEnv = await loadRuntimeEnv(projectRoot);
-  } catch (error) {
-    envError = error?.message ?? String(error);
-  }
-
-  const config = buildDefaultRuntimeConfig(
-    mergeObjects(rawConfig ?? {}, buildEnvOverrides({ ...runtimeEnv, ...process.env })),
-  );
+  const config = buildDefaultRuntimeConfig(rawConfig ?? {});
   const validation = validateRuntimeConfig(config);
   const errors = [
     ...(parseError ? [`config.json parse error: ${parseError}`] : []),
-    ...(envError ? [`runtime .env error: ${envError}`] : []),
     ...validation.errors,
   ];
 
   return {
     exists,
     rawConfig,
-    runtimeEnv,
     config,
     parseError,
-    valid: exists && !parseError && !envError && validation.valid,
+    valid: exists && !parseError && validation.valid,
     errors,
   };
 }

package/src/index/impactCatalog.js

@@ -1,4 +1,16 @@
 const SHARED_IMPACT_PATTERNS = [
+  {
+    regex: /^\.claude\/hooks\//,
+    label: 'installed-hook-runtime',
+  },
+  {
+    regex: /^\.claude\/ukit\//,
+    label: 'installed-helper-runtime',
+  },
+  {
+    regex: /^\.codex\//,
+    label: 'installed-codex-runtime',
+  },
   {
     regex: /^src\/index\//,
     label: 'shared-index-runtime',

package/src/index/taskRouting.js

@@ -157,6 +157,7 @@ export function buildRouteSummary({
       ?? [...primaryCommands, ...fallbackCommands],
   );
   const policyMode = verificationRecommendation?.executionPolicy?.policyMode ?? null;
+  const editGuardHint = isSharedImpactFile(routingContext.targetFile) ? 'anchor-required' : null;
   const compactHelperLane = nextAction?.type === 'pull-indexed-context'
     && typeof contextRecommendation?.command === 'string'
     && contextRecommendation.command.trim();
@@ -175,6 +176,7 @@ export function buildRouteSummary({
     formatCompactSegment('targets', primaryTargets),
     formatCompactSegment('tests', relatedTests),
     formatCompactSegment('styles', styleFiles),
+    editGuardHint ? `editGuard=${editGuardHint}` : null,
     delegationRecommendation?.hint ? `delegate=${delegationRecommendation.hint}` : null,
     policyMode ? `policy=${policyMode}` : null,
   ].filter(Boolean).join(' | ');
@@ -184,6 +186,7 @@ export function buildRouteSummary({
     fallbackCommands,
     preferredOrder,
     policyMode,
+    editGuardHint,
     intentMode: routingContext.intentMode ?? null,
     delegateHint: delegationRecommendation?.hint ?? null,
     nextActionType: nextAction?.type ?? null,

package/templates/.claude/agents/ukit-small-task-maintainer.md

@@ -6,13 +6,13 @@ color: cyan
 tools: ["Read", "Grep", "Glob", "Edit", "Write"]
 ---
 
-You are UKit's internal small-task maintainer. You run as a sidecar/parallel/non-blocking lane for safe, reversible UKit orchestration chores so the end user can stay focused on product work and only remember `ukit install`. You must follow `docs/UKIT_CODEV_PRINCIPLES.md`: hide complexity, preserve output quality, and never trade correctness for speed or token savings.
+You are UKit's internal small-task maintainer. You run as a sidecar/parallel/non-blocking lane for safe, reversible UKit orchestration chores so the end user can stay focused on product work and only remember `ukit install`. Runtime tuning lives in `.ukit/storage/config.json`. You must follow `docs/UKIT_CODEV_PRINCIPLES.md`: hide complexity, preserve output quality, and never trade correctness for speed or token savings.
 
 ## Model Policy
 
-- Use the model selected by `UKIT_SMALL_TASK_MODEL` when the host supports model selection for this subagent.
+- Use the model selected by `subagents.smallTaskModel` when the host supports model selection for this subagent.
 - Default intended model: `unic-lite`.
-- If the host cannot bind a model from env directly, still follow this role and report that the configured model is a hint.
+- If the host cannot bind a model from config directly, still follow this role and report that the configured model is a hint.
 - This lane must run separately from the user's main task model. It must never replace, pause, or slow down the main task.
 
 ## Use For
@@ -24,7 +24,7 @@ You are UKit's internal small-task maintainer. You run as a sidecar/parallel/non
 - Summarizing `docs/STATUS.md`, `docs/TASKS.md`, `docs/WORKLOG.md`, or memory snippets into compact handoff notes.
 - Deciding fast vs slow lane, safe vs risky lane, whether a skill should be activated, and whether the current prompt has enough steps planned.
 - Choosing compact-now vs compact-later and summarize-vs-keep-detail for UKit context hygiene.
-- Keeping agent context compact without removing existing lanes: Claude PreCompact/reinject stays active, OpenCode native auto/prune compaction stays active, and Codex Desktop soft handoffs use `UKIT_CODEX_COMPACT_TARGET` (default 150 lines; preferred 120-150; hard max 170) while preserving critical state.
+- Keeping agent context compact without removing existing lanes: Claude PreCompact/reinject stays active, OpenCode native auto/prune compaction stays active, and Codex Desktop soft handoffs use `compact.codexContext.compactTarget` (default 150 lines; preferred 120-150; hard max 170) while preserving critical state.
 - Small, reversible UKit runtime maintenance decisions.
 
 ## Never Use For
@@ -53,7 +53,7 @@ You are UKit's internal small-task maintainer. You run as a sidecar/parallel/non
 
 ```
 STATUS: DONE | SKIPPED | HAND_BACK
-MODEL_HINT: UKIT_SMALL_TASK_MODEL=<value-or-default>
+MODEL_HINT: subagents.smallTaskModel=<value-or-default>
 SUMMARY: [one sentence]
 CHANGES:
   - [file/area]: [what changed]

package/templates/.claude/hooks/post-edit-verify.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+# PostToolUse hook: verify risky Edit|Write delta after rollback bytes exist.
+# Matched on: Edit|Write
+
+INPUT=$(cat)
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+SCRIPT="$PROJECT_ROOT/.claude/ukit/index/post-edit-verify.mjs"
+
+if [ ! -f "$SCRIPT" ]; then
+  exit 0
+fi
+
+printf '%s' "$INPUT" | node "$SCRIPT"

package/templates/.claude/hooks/pre-edit-backup.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+# PreToolUse hook: create rollback bytes for risky Edit|Write operations.
+# Matched on: Edit|Write
+
+INPUT=$(cat)
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+SCRIPT="$PROJECT_ROOT/.claude/ukit/index/pre-edit-backup.mjs"
+
+if [ ! -f "$SCRIPT" ]; then
+  exit 0
+fi
+
+printf '%s' "$INPUT" | node "$SCRIPT"

package/templates/.claude/hooks/stale-spec-guard.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+# PreToolUse hook: prevent stale/ambiguous risky Edit specs and whole-file risky Write.
+# Matched on: Edit|Write
+
+INPUT=$(cat)
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+SCRIPT="$PROJECT_ROOT/.claude/ukit/index/stale-spec-check.mjs"
+
+if [ ! -f "$SCRIPT" ]; then
+  exit 0
+fi
+
+printf '%s' "$INPUT" | node "$SCRIPT"

package/templates/.claude/settings.json

@@ -62,6 +62,16 @@
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/protect-files.sh\"",
             "timeout": 8
           },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/stale-spec-guard.sh\"",
+            "timeout": 8
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/pre-edit-backup.sh\"",
+            "timeout": 8
+          },
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-router.sh\"",
@@ -96,6 +106,16 @@
       }
     ],
     "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/post-edit-verify.sh\"",
+            "timeout": 8
+          }
+        ]
+      },
       {
         "matcher": "Bash",
         "hooks": [