@ngockhoale/ukit 1.2.2 → 1.3.1

package/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to UKit are documented here.
 
 ## Unreleased
 
+## 1.3.1 - 2026-05-06
+
+### Fixed
+
+- Fixed `ukit install` failing with `ENOENT` when a published/global package is missing optional `templates/.gitignore`; install now uses a built-in fallback.
+
+### Tests
+
+- Added a regression test for package artifacts without `templates/.gitignore`.
+
+## 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.

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.2 Runtime
+## UKit v1.3.1 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.2 keeps the same shared runtime contract while adding a local AI task queue alongside living project status routing:
+UKit v1.3.1 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.2 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.2 also keeps the fast path improvements from the recent runtime releases:
+UKit v1.3.1 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

package/manifests/platform.full.yaml

@@ -838,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
@@ -869,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
@@ -961,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.2",
+  "version": "1.3.1",
   "description": "Install/update an index-first AI workspace for Claude Code, Antigravity, OpenAI Codex, and OpenCode.",
   "license": "MIT",
   "type": "module",

package/src/core/buildPlan.js

@@ -25,6 +25,14 @@ const BINARY_TEMPLATE_EXTENSIONS = new Set([
   '.pdf',
 ]);
 
+const FALLBACK_ROOT_GITIGNORE_TEMPLATE = 'node_modules/\n.env\n*.log\n.DS_Store\n';
+
+function isRootGitignoreItem(item) {
+  return item?.id === 'gitignore-root'
+    && item?.sourceTemplate === '.gitignore'
+    && item?.targetPath === '.gitignore';
+}
+
 function safeResolve(basePath, relativePath) {
   const resolvedPath = path.resolve(basePath, relativePath);
   const relativeToBase = path.relative(basePath, resolvedPath);
@@ -118,7 +126,27 @@ export async function buildInstallPlan({
       });
     } else {
       const sourcePath = safeResolve(templatesRoot, item.sourceTemplate);
-      const stat = await fs.stat(sourcePath);
+      let stat;
+      try {
+        stat = await fs.stat(sourcePath);
+      } catch (error) {
+        if (error?.code === 'ENOENT' && isRootGitignoreItem(item)) {
+          const targetPath = safeResolve(projectRoot, item.targetPath);
+          explicitTargetPaths.add(targetPath);
+          planEntries.push({
+            id: item.id,
+            type: item.type,
+            sourcePath: null,
+            targetPath,
+            mergeStrategy: item.mergeStrategy,
+            renderedContent: FALLBACK_ROOT_GITIGNORE_TEMPLATE,
+            requires: item.requires ?? [],
+            mode: 0o644,
+          });
+          continue;
+        }
+        throw error;
+      }
       if (stat.isDirectory()) {
         const nestedFiles = await walkDirectory(sourcePath);
         const nestedStats = await Promise.all(nestedFiles.map((filePath) => fs.stat(filePath)));

package/src/core/runtimeConfig.js

@@ -49,7 +49,7 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
   const safeOverrides = isPlainObject(overrides) ? overrides : {};
 
   return mergeObjects({
-    version: '1.2.2',
+    version: '1.3.1',
     agent: 'claude-code',
     compact: {
       enabled: true,
@@ -122,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',
@@ -271,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 {

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/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": [

package/templates/.claude/ukit/index/anchor-search.mjs

@@ -0,0 +1,99 @@
+import { analyzeTextFile, publicTextProfile } from '../runtime/text-profile.mjs';
+import { buildLineWindow, countOccurrences, lineNumberForIndex, resolveProjectFile, summarizeSnippet } from '../runtime/safe-patch-core.mjs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const args = { json: false, contextLines: 3 };
+  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 === '--query' || arg === '--anchor') args.query = argv[++i];
+    else if (arg === '--context-lines') args.contextLines = Number(argv[++i]);
+    else if (arg === '--start-line') args.startLine = Number(argv[++i]);
+    else if (arg === '--end-line') args.endLine = Number(argv[++i]);
+    else if (arg === '--help' || arg === '-h') args.help = true;
+  }
+  return args;
+}
+
+function usage() {
+  return 'Usage: node .claude/ukit/index/anchor-search.mjs --file <path> --query <anchor> [--json] [--context-lines N]';
+}
+
+export async function searchAnchor({ projectRoot = process.cwd(), filePath, query, contextLines = 3, startLine = null, endLine = null } = {}) {
+  const resolved = resolveProjectFile(projectRoot, filePath);
+  if (!resolved) throw new Error('Missing --file.');
+  if (!query) throw new Error('Missing --query.');
+
+  const profile = await analyzeTextFile(resolved.absolute);
+  if (profile.binaryLike || !profile.utf8Valid) {
+    return {
+      status: 'non-text',
+      file: resolved.relative,
+      query,
+      count: 0,
+      matches: [],
+      profile: publicTextProfile(profile),
+    };
+  }
+
+  const occurrence = countOccurrences(profile.text, query);
+  let matches = occurrence.indexes.map((index) => {
+    const line = lineNumberForIndex(profile.text, index);
+    const window = buildLineWindow(profile.text, line, 0);
+    return { index, line, snippet: summarizeSnippet(window.text, 160) };
+  });
+
+  if (Number.isFinite(startLine) || Number.isFinite(endLine)) {
+    const minLine = Number.isFinite(startLine) ? startLine : 1;
+    const maxLine = Number.isFinite(endLine) ? endLine : Number.MAX_SAFE_INTEGER;
+    matches = matches.filter((match) => match.line >= minLine && match.line <= maxLine);
+  }
+
+  const count = matches.length;
+  const status = count === 1 ? 'unique' : count === 0 ? 'not-found' : 'ambiguous';
+  const firstLine = matches[0]?.line ?? 1;
+  return {
+    status,
+    file: resolved.relative,
+    query,
+    count,
+    matches,
+    ...(count === 1 ? { window: buildLineWindow(profile.text, firstLine, Number.isFinite(contextLines) ? contextLines : 3) } : {}),
+    profile: publicTextProfile(profile),
+  };
+}
+
+async function main() {
+  const args = parseArgs();
+  if (args.help || !args.file || !args.query) {
+    const help = usage();
+    process.stdout.write(args.json ? `${JSON.stringify({ help })}\n` : `${help}\n`);
+    return;
+  }
+  const result = await searchAnchor({
+    projectRoot: process.env.CLAUDE_PROJECT_DIR || process.cwd(),
+    filePath: args.file,
+    query: args.query,
+    contextLines: args.contextLines,
+    startLine: args.startLine,
+    endLine: args.endLine,
+  });
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+  } else {
+    process.stdout.write(`[ukit:anchor] status=${result.status} count=${result.count} file=${result.file} query=${JSON.stringify(result.query)}\n`);
+    for (const match of result.matches.slice(0, 5)) {
+      process.stdout.write(`- line ${match.line}: ${match.snippet}\n`);
+    }
+  }
+}
+
+if (process.argv[1] && path.basename(fileURLToPath(import.meta.url)) === path.basename(process.argv[1])) {
+  main().catch((error) => {
+    process.stderr.write(`[ukit:anchor] ERROR: ${error?.message || error}\n`);
+    process.exit(1);
+  });
+}

package/templates/.claude/ukit/index/lib/index-core.mjs

@@ -2828,6 +2828,9 @@ async function detectPackageManager(rootDir) {
 }
 
 const IMPACT_SHARED_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' },
   {
     regex: /^src\/core\/(runInstallPipeline|applyPlan|buildPlan|diffPlan|metadata|migrateLegacy|uninstall|runtimeConfig|runtimePaths)\.js$/,