@ngockhoale/ukit 1.2.2 → 1.3.0

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

@@ -0,0 +1,206 @@
+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';
+
+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 getFilePath(payload = {}) {
+  return payload.tool_input?.file_path || payload.file_path || '';
+}
+
+async function listManifestPaths(backupsRoot) {
+  const dates = await fs.readdir(backupsRoot, { withFileTypes: true }).catch(() => []);
+  return dates
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => path.join(backupsRoot, entry.name, 'manifest.jsonl'))
+    .sort()
+    .reverse();
+}
+
+async function readJsonl(filePath) {
+  const raw = await fs.readFile(filePath, 'utf8').catch(() => '');
+  return raw
+    .split(/\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+async function findLatestBackup(projectRoot, relativePath) {
+  const backupsRoot = path.join(projectRoot, '.ukit', 'storage', 'backups');
+  for (const manifestPath of await listManifestPaths(backupsRoot)) {
+    const entries = await readJsonl(manifestPath);
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+      const entry = entries[index];
+      if (entry.file === relativePath && entry.rollbackPath && !entry.afterHash) {
+        return { entry, manifestPath };
+      }
+    }
+  }
+  return null;
+}
+
+function diffLineStats(beforeText, afterText, { maxCells = 2_000_000 } = {}) {
+  const before = String(beforeText ?? '').split(/\n/);
+  const after = String(afterText ?? '').split(/\n/);
+  const cellCount = (before.length + 1) * (after.length + 1);
+  if (cellCount > Number(maxCells || 2_000_000)) {
+    return boundedDiffLineStats(before, after, cellCount);
+  }
+
+  const rows = before.length + 1;
+  const cols = after.length + 1;
+  const dp = Array.from({ length: rows }, () => Array(cols).fill(0));
+
+  for (let i = before.length - 1; i >= 0; i -= 1) {
+    for (let j = after.length - 1; j >= 0; j -= 1) {
+      dp[i][j] = before[i] === after[j]
+        ? dp[i + 1][j + 1] + 1
+        : Math.max(dp[i + 1][j], dp[i][j + 1]);
+    }
+  }
+
+  let i = 0;
+  let j = 0;
+  let changedLines = 0;
+  let hunkCount = 0;
+  let inHunk = false;
+  while (i < before.length || j < after.length) {
+    if (i < before.length && j < after.length && before[i] === after[j]) {
+      inHunk = false;
+      i += 1;
+      j += 1;
+    } else if (j < after.length && (i === before.length || dp[i][j + 1] >= dp[i + 1]?.[j])) {
+      changedLines += 1;
+      if (!inHunk) hunkCount += 1;
+      inHunk = true;
+      j += 1;
+    } else if (i < before.length) {
+      changedLines += 1;
+      if (!inHunk) hunkCount += 1;
+      inHunk = true;
+      i += 1;
+    }
+  }
+
+  return { changedLines, hunkCount, algorithm: 'lcs', cellCount };
+}
+
+function boundedDiffLineStats(before, after, cellCount) {
+  let start = 0;
+  while (start < before.length && start < after.length && before[start] === after[start]) {
+    start += 1;
+  }
+
+  let beforeEnd = before.length - 1;
+  let afterEnd = after.length - 1;
+  while (beforeEnd >= start && afterEnd >= start && before[beforeEnd] === after[afterEnd]) {
+    beforeEnd -= 1;
+    afterEnd -= 1;
+  }
+
+  const removed = Math.max(0, beforeEnd - start + 1);
+  const added = Math.max(0, afterEnd - start + 1);
+  const changedLines = removed + added;
+  return {
+    changedLines,
+    hunkCount: changedLines > 0 ? 1 : 0,
+    algorithm: 'bounded-fallback',
+    cellCount,
+  };
+}
+
+async function appendPostEditEntry(manifestPath, entry) {
+  await fs.appendFile(manifestPath, `${JSON.stringify(entry)}\n`, 'utf8');
+}
+
+export async function verifyPostEdit({ projectRoot = process.cwd(), payload = {} } = {}) {
+  const config = await readRuntimeSafePatchConfig(projectRoot);
+  if (config.enabled === false || config.backupEnabled === false) return { status: 'disabled' };
+  const filePath = getFilePath(payload);
+  if (!filePath) return { status: 'skipped', reason: 'no-file' };
+  const resolved = resolveProjectFile(projectRoot, filePath);
+  if (!(await pathExists(resolved.absolute))) return { status: 'skipped', reason: 'missing-after', file: resolved.relative };
+
+  const latest = await findLatestBackup(projectRoot, resolved.relative);
+  if (!latest) return { status: 'skipped', reason: 'no-backup', file: resolved.relative };
+
+  const rollbackPath = path.resolve(projectRoot, latest.entry.rollbackPath);
+  const beforeBuffer = await fs.readFile(rollbackPath);
+  const beforeProfile = analyzeTextBuffer(beforeBuffer);
+  const afterProfile = await analyzeTextFile(resolved.absolute);
+  const risk = classifySafePatchRisk(resolved.relative, afterProfile, config);
+  const delta = beforeProfile.utf8Valid && afterProfile.utf8Valid
+    ? diffLineStats(beforeProfile.text, afterProfile.text, { maxCells: Number(config.deltaMaxDiffCells || 2_000_000) })
+    : { changedLines: Number.POSITIVE_INFINITY, hunkCount: Number.POSITIVE_INFINITY };
+
+  const overChangedLines = delta.changedLines > Number(config.deltaMaxChangedLines || 120);
+  const overHunks = delta.hunkCount > Number(config.deltaMaxHunks || 3);
+  const status = risk.strict && (overChangedLines || overHunks) ? 'blocked' : 'ok';
+  const postEntry = {
+    event: 'post-edit',
+    file: resolved.relative,
+    beforeHash: beforeProfile.sha256,
+    afterHash: afterProfile.sha256,
+    timestamp: new Date().toISOString(),
+    delta,
+    riskLabels: risk.labels,
+    profile: publicTextProfile(afterProfile),
+    rollbackPath: latest.entry.rollbackPath,
+    status,
+  };
+  await appendPostEditEntry(latest.manifestPath, postEntry);
+
+  return {
+    ...postEntry,
+    message: status === 'blocked'
+      ? `BLOCKED: '${resolved.relative}' exceeded Safe Patch delta budget (changedLines=${delta.changedLines}/${config.deltaMaxChangedLines}, hunks=${delta.hunkCount}/${config.deltaMaxHunks}). Review diff or restore from ${latest.entry.rollbackPath}.`
+      : `OK: '${resolved.relative}' delta changedLines=${delta.changedLines}, hunks=${delta.hunkCount}.`,
+  };
+}
+
+async function main() {
+  const json = process.argv.includes('--json');
+  const help = process.argv.includes('--help') || process.argv.includes('-h');
+  if (help) {
+    const text = 'Usage: post-edit-verify.mjs < Claude hook JSON on stdin';
+    process.stdout.write(json ? `${JSON.stringify({ help: text })}\n` : `${text}\n`);
+    return;
+  }
+  const result = await verifyPostEdit({
+    projectRoot: process.env.CLAUDE_PROJECT_DIR || process.cwd(),
+    payload: parseJsonInput(await readStdin(), {}),
+  });
+  if (json) {
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+  } else if (result.status === 'ok') {
+    process.stdout.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] post-edit ERROR: ${error?.message || error}\n`);
+    process.exit(1);
+  });
+}

package/templates/.claude/ukit/index/pre-edit-backup.mjs

@@ -0,0 +1,84 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { analyzeTextFile, publicTextProfile } from '../runtime/text-profile.mjs';
+import { classifySafePatchRisk, parseJsonInput, pathExists, readRuntimeSafePatchConfig, resolveProjectFile } from '../runtime/safe-patch-core.mjs';
+import { fileURLToPath } from 'node:url';
+
+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 getFilePath(payload = {}) {
+  return payload.tool_input?.file_path || payload.file_path || '';
+}
+
+function getToolName(payload = {}) {
+  return String(payload.tool_name || payload.tool || payload.name || '').trim() || 'Edit/Write';
+}
+
+async function pruneOldBackups(projectRoot, config) {
+  const retentionDays = Number(config.backupRetentionDays || 30);
+  if (!Number.isFinite(retentionDays) || retentionDays <= 0) return;
+  const backupsRoot = path.join(projectRoot, '.ukit', 'storage', 'backups');
+  const entries = await fs.readdir(backupsRoot, { withFileTypes: true }).catch(() => []);
+  const cutoffMs = Date.now() - retentionDays * 24 * 60 * 60 * 1000;
+  await Promise.all(entries.map(async (entry) => {
+    if (!entry.isDirectory() || !/^\d{4}-\d{2}-\d{2}$/.test(entry.name)) return;
+    const backupTime = Date.parse(`${entry.name}T00:00:00.000Z`);
+    if (!Number.isFinite(backupTime) || backupTime >= cutoffMs) return;
+    await fs.rm(path.join(backupsRoot, entry.name), { recursive: true, force: true });
+  }));
+}
+
+async function backupIfNeeded({ projectRoot, payload }) {
+  const config = await readRuntimeSafePatchConfig(projectRoot);
+  if (config.enabled === false || config.backupEnabled === false) return { status: 'disabled' };
+  await pruneOldBackups(projectRoot, config);
+  const filePath = getFilePath(payload);
+  if (!filePath) return { status: 'skipped', reason: 'no-file' };
+  const resolved = resolveProjectFile(projectRoot, filePath);
+  if (!(await pathExists(resolved.absolute))) return { status: 'skipped', reason: 'new-file', file: resolved.relative };
+  const profile = await analyzeTextFile(resolved.absolute);
+  const risk = classifySafePatchRisk(resolved.relative, profile, config);
+  if (!risk.strict) return { status: 'skipped', reason: 'low-risk', file: resolved.relative };
+
+  const session = new Date().toISOString().slice(0, 10);
+  const backupRoot = path.join(projectRoot, '.ukit', 'storage', 'backups', session);
+  const filesDir = path.join(backupRoot, 'files');
+  await fs.mkdir(filesDir, { recursive: true });
+  const backupName = `${profile.sha256}-before`;
+  const rollbackPath = path.join(filesDir, backupName);
+  await fs.copyFile(resolved.absolute, rollbackPath);
+  const manifestPath = path.join(backupRoot, 'manifest.jsonl');
+  const entry = {
+    file: resolved.relative,
+    beforeHash: profile.sha256,
+    profile: publicTextProfile(profile),
+    tool: getToolName(payload),
+    timestamp: new Date().toISOString(),
+    riskLabels: risk.labels,
+    rollbackPath: path.relative(projectRoot, rollbackPath).replace(/\\/g, '/'),
+  };
+  await fs.appendFile(manifestPath, `${JSON.stringify(entry)}\n`, 'utf8');
+  return { status: 'backed-up', ...entry };
+}
+
+async function main() {
+  const payload = parseJsonInput(await readStdin(), {});
+  const result = await backupIfNeeded({ projectRoot: process.env.CLAUDE_PROJECT_DIR || process.cwd(), payload });
+  if (result.status === 'backed-up') {
+    process.stdout.write(`[ukit-safe-patch] backup=${result.rollbackPath} file=${result.file}\n`);
+  }
+}
+
+if (process.argv[1] && path.basename(fileURLToPath(import.meta.url)) === path.basename(process.argv[1])) {
+  main().catch((error) => {
+    process.stderr.write(`[ukit-safe-patch] backup ERROR: ${error?.message || error}\n`);
+    process.exit(1);
+  });
+}

package/templates/.claude/ukit/index/route-task.mjs

@@ -1196,6 +1196,7 @@ 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();
@@ -1214,6 +1215,7 @@ 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(' | ');
@@ -1223,6 +1225,7 @@ function buildRouteSummary({
     fallbackCommands,
     preferredOrder,
     policyMode,
+    editGuardHint,
     intentMode: routingContext.intentMode ?? null,
     delegateHint: delegationRecommendation?.hint ?? null,
     nextActionType: nextAction?.type ?? null,
@@ -1336,6 +1339,9 @@ function buildHelperCommand({ commandNamespace = '.claude', scriptName, intent =
 }
 
 const SHARED_IMPACT_PATTERNS = [
+  /^\.claude\/hooks\//,
+  /^\.claude\/ukit\//,
+  /^\.codex\//,
   /^src\/index\//,
   /^src\/core\/(runInstallPipeline|applyPlan|buildPlan|diffPlan|metadata|migrateLegacy|uninstall|runtimeConfig|runtimePaths)\.js$/,
   /^src\/core\/(output|token|compact)\//,

package/templates/.claude/ukit/index/safe-patch.mjs

@@ -0,0 +1,97 @@
+import fs from 'node:fs/promises';
+import { analyzeTextFile, normalizeNewlinesForProfile, publicTextProfile, writeTextWithProfile } from '../runtime/text-profile.mjs';
+import { buildLineWindow, countOccurrences, lineNumberForIndex, resolveProjectFile } from '../runtime/safe-patch-core.mjs';
+import { searchAnchor } from './anchor-search.mjs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const args = { json: false, contextLines: 8 };
+  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 === '--anchor') args.anchor = argv[++i];
+    else if (arg === '--old') args.oldString = argv[++i];
+    else if (arg === '--new') args.newString = argv[++i];
+    else if (arg === '--context-lines') args.contextLines = Number(argv[++i]);
+    else if (arg === '--help' || arg === '-h') args.help = true;
+  }
+  return args;
+}
+
+function usage() {
+  return 'Usage: node .claude/ukit/index/safe-patch.mjs --file <path> --anchor <unique-anchor> --old <text> --new <text> [--json]';
+}
+
+export async function applySafePatch({ projectRoot = process.cwd(), filePath, anchor, oldString, newString, contextLines = 8 } = {}) {
+  const resolved = resolveProjectFile(projectRoot, filePath);
+  if (!resolved) throw new Error('Missing --file.');
+  if (!anchor) throw new Error('Missing --anchor.');
+  if (!oldString) throw new Error('Missing --old.');
+
+  const anchorResult = await searchAnchor({ projectRoot, filePath, query: anchor, contextLines });
+  if (anchorResult.status !== 'unique') {
+    throw new Error(`Anchor is ${anchorResult.status}; expected unique anchor before patching.`);
+  }
+
+  const beforeProfile = await analyzeTextFile(resolved.absolute);
+  if (beforeProfile.binaryLike || !beforeProfile.utf8Valid) {
+    throw new Error('Target is not strict UTF-8 text; refusing safe patch.');
+  }
+
+  const oldForProfile = normalizeNewlinesForProfile(oldString, beforeProfile);
+  const newForProfile = normalizeNewlinesForProfile(newString ?? '', beforeProfile);
+  const occurrence = countOccurrences(beforeProfile.text, oldForProfile);
+  if (occurrence.count !== 1) {
+    throw new Error(`Patch old text occurrence is ${occurrence.count}; expected exactly 1.`);
+  }
+
+  const anchorLine = anchorResult.matches[0].line;
+  const oldLine = lineNumberForIndex(beforeProfile.text, occurrence.indexes[0]);
+  const window = buildLineWindow(beforeProfile.text, anchorLine, Number.isFinite(contextLines) ? contextLines : 8);
+  if (oldLine < window.startLine || oldLine > window.endLine) {
+    throw new Error('Patch old text is outside the bounded anchor window.');
+  }
+
+  const nextText = beforeProfile.text.replace(oldForProfile, newForProfile);
+  await writeTextWithProfile(resolved.absolute, nextText, beforeProfile);
+  const afterProfile = await analyzeTextFile(resolved.absolute);
+
+  return {
+    status: 'patched',
+    file: resolved.relative,
+    anchor,
+    before: { profile: publicTextProfile(beforeProfile) },
+    after: { profile: publicTextProfile(afterProfile) },
+  };
+}
+
+async function main() {
+  const args = parseArgs();
+  if (args.help || !args.file || !args.anchor || !args.oldString) {
+    const help = usage();
+    process.stdout.write(args.json ? `${JSON.stringify({ help })}\n` : `${help}\n`);
+    return;
+  }
+  const result = await applySafePatch({
+    projectRoot: process.env.CLAUDE_PROJECT_DIR || process.cwd(),
+    filePath: args.file,
+    anchor: args.anchor,
+    oldString: args.oldString,
+    newString: args.newString ?? '',
+    contextLines: args.contextLines,
+  });
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+  } else {
+    process.stdout.write(`[ukit:safe-patch] patched ${result.file} anchor=${JSON.stringify(result.anchor)} newline=${result.after.profile.newline} bom=${result.after.profile.hasBom ? 'yes' : 'no'}\n`);
+  }
+}
+
+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/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);
+  });
+}