@ngockhoale/ukit 2.2.1 → 2.2.3

package/templates/.claude/ukit/runtime/execution-ledger.mjs

@@ -0,0 +1,354 @@
+#!/usr/bin/env node
+
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const LEDGER_VERSION = 1;
+const MAX_RECEIPTS = 24;
+const MAX_CONTINUATIONS = 6;
+const IMPLEMENT_MODES = new Set([
+  'tiny-fix',
+  'local-fix',
+  'local-build',
+  'shared-edit',
+  'find-cause',
+]);
+
+function safeSegment(value) {
+  return String(value || 'default')
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]/g, '_')
+    .slice(0, 96) || 'default';
+}
+
+function firstDefined(values) {
+  return values.find((value) => value !== undefined && value !== null);
+}
+
+function sessionIdentity(payload = {}) {
+  const sessionId = firstDefined([
+    payload.session_id,
+    payload.sessionId,
+  ]);
+  if (sessionId) return safeSegment(sessionId);
+
+  const transcriptPath = firstDefined([
+    payload.transcript_path,
+    payload.transcriptPath,
+  ]);
+  if (transcriptPath) {
+    return `transcript-${crypto.createHash('sha256').update(String(transcriptPath)).digest('hex').slice(0, 20)}`;
+  }
+  return 'default';
+}
+
+function ledgerPath(projectRoot, payload = {}) {
+  return path.join(
+    projectRoot,
+    '.ukit',
+    'storage',
+    'cache',
+    'exec-ledger',
+    `${sessionIdentity(payload)}.json`,
+  );
+}
+
+async function readJson(filePath, fallback = null) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+async function writeJsonAtomic(filePath, value) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.${process.pid}.tmp`;
+  await fs.writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  await fs.rename(tempPath, filePath);
+}
+
+export async function readRouteState(projectRoot) {
+  return readJson(path.join(projectRoot, '.claude', 'ukit', 'skill-router-state.json'), null);
+}
+
+export async function readExecutionLedger(projectRoot, payload = {}) {
+  return readJson(ledgerPath(projectRoot, payload), null);
+}
+
+function explicitError(payload = {}) {
+  return [
+    payload.isError,
+    payload.is_error,
+    payload.tool_output?.isError,
+    payload.tool_output?.is_error,
+    payload.tool_result?.isError,
+    payload.tool_result?.is_error,
+    payload.tool_response?.isError,
+    payload.tool_response?.is_error,
+  ].some((value) => value === true);
+}
+
+function extractExitCode(payload = {}) {
+  const candidates = [
+    payload.tool_output?.exitCode,
+    payload.tool_output?.exit_code,
+    payload.tool_result?.details?.exitCode,
+    payload.tool_result?.details?.exit_code,
+    payload.tool_result?.exitCode,
+    payload.tool_result?.exit_code,
+    payload.tool_response?.exitCode,
+    payload.tool_response?.exit_code,
+    payload.exitCode,
+    payload.exit_code,
+  ];
+  for (const value of candidates) {
+    const number = Number(value);
+    if (Number.isFinite(number)) return number;
+  }
+  return null;
+}
+
+function isVerificationCommand(command) {
+  const text = String(command || '').trim();
+  if (!text) return false;
+  return [
+    /(?:^|\s)(?:vitest|jest|mocha|ava|pytest|py\.test)(?:\s|$)/i,
+    /(?:^|\s)(?:npm|pnpm|yarn|bun)(?:\s+run)?\s+(?:test|lint|typecheck|check|build)(?:\s|$)/i,
+    /(?:^|\s)(?:tsc|eslint|biome|ruff|mypy)(?:\s|$)/i,
+    /(?:^|\s)node\s+--check(?:\s|$)/i,
+  ].some((pattern) => pattern.test(text));
+}
+
+function compactReceipt(receipt) {
+  const compact = {
+    ts: receipt.ts,
+    kind: receipt.kind,
+    success: receipt.success,
+  };
+  for (const key of ['toolName', 'toolUseId', 'file', 'command', 'exitCode', 'error']) {
+    if (receipt[key] !== undefined && receipt[key] !== null && receipt[key] !== '') {
+      compact[key] = receipt[key];
+    }
+  }
+  return compact;
+}
+
+function appendReceipt(receipts, receipt) {
+  return [...(receipts || []), compactReceipt(receipt)].slice(-MAX_RECEIPTS);
+}
+
+function freshLedger(payload, routeState, harness) {
+  return {
+    version: LEDGER_VERSION,
+    sessionKey: sessionIdentity(payload),
+    sessionId: payload.session_id || payload.sessionId || null,
+    transcriptPath: payload.transcript_path || payload.transcriptPath || null,
+    harness,
+    requestKey: routeState?.requestKey || null,
+    routeFingerprint: routeState?.fingerprint || null,
+    sourceSucceeded: false,
+    writeAttempted: false,
+    writeSucceeded: false,
+    verificationAttempted: false,
+    verificationSucceeded: false,
+    verificationFailed: false,
+    receipts: [],
+    blocker: null,
+    continuationCount: 0,
+    updatedAt: Date.now(),
+  };
+}
+
+export async function recordExecutionReceipt({
+  projectRoot,
+  payload = {},
+  toolName = payload.tool_name,
+  harness = 'unknown',
+} = {}) {
+  if (!projectRoot || !toolName) return null;
+  const routeState = await readRouteState(projectRoot);
+  const current = await readExecutionLedger(projectRoot, payload);
+  const ledger = !current || current.requestKey !== (routeState?.requestKey || null)
+    ? freshLedger(payload, routeState, harness)
+    : { ...current, harness: current.harness || harness };
+
+  const failed = explicitError(payload);
+  const exitCode = extractExitCode(payload);
+  const success = !failed && (exitCode === null || exitCode === 0);
+  const toolInput = payload.tool_input || {};
+  const receipt = {
+    ts: Date.now(),
+    toolName,
+    toolUseId: payload.tool_use_id || null,
+    success,
+    exitCode,
+  };
+
+  if (toolName === 'Read' || toolName === 'Grep' || toolName === 'Glob') {
+    receipt.kind = 'source';
+    receipt.file = toolInput.file_path || toolInput.path || null;
+    ledger.sourceSucceeded ||= success;
+  } else if (toolName === 'Edit' || toolName === 'Write') {
+    receipt.kind = 'write';
+    receipt.file = toolInput.file_path || toolInput.path || toolInput.paths?.[0] || null;
+    ledger.writeAttempted = true;
+    ledger.writeSucceeded ||= success;
+  } else if (toolName === 'Bash' && isVerificationCommand(toolInput.command)) {
+    receipt.kind = 'verification';
+    receipt.command = String(toolInput.command || '').trim();
+    ledger.verificationAttempted = true;
+    ledger.verificationSucceeded ||= success;
+    ledger.verificationFailed ||= !success;
+  } else {
+    return ledger;
+  }
+
+  ledger.receipts = appendReceipt(ledger.receipts, receipt);
+  ledger.updatedAt = Date.now();
+  await writeJsonAtomic(ledgerPath(projectRoot, payload), ledger);
+  return ledger;
+}
+
+function requiredEvidence(state = {}) {
+  const routeSummary = state?.routeSummary || {};
+  const contractEvidence = routeSummary.executionContract?.completionEvidence;
+  if (Array.isArray(contractEvidence) && contractEvidence.length > 0) {
+    return [...new Set(contractEvidence)];
+  }
+  return [...new Set(routeSummary.completionState?.missingEvidence || [])];
+}
+
+function evidenceSatisfied(evidence, ledger = {}) {
+  if (evidence === 'write-evidence') return ledger.writeSucceeded === true;
+  if (evidence === 'verification-evidence') return ledger.verificationSucceeded === true;
+  if (evidence === 'impact-evidence') return ledger.sourceSucceeded === true;
+  return false;
+}
+
+function recoveryInstruction(missingEvidence, ledger = {}) {
+  if (missingEvidence.includes('write-evidence')) {
+    if (!ledger.sourceSucceeded) {
+      return 'Pull one bounded indexed source slice, then make the requested Edit/Write in this continuation.';
+    }
+    if (ledger.writeAttempted && !ledger.writeSucceeded) {
+      return 'Recover from the failed mutation using the current error, then retry the smallest correct Edit/Write.';
+    }
+    return 'Make the smallest correct Edit/Write now; do not end after more read-only analysis.';
+  }
+  if (missingEvidence.includes('verification-evidence')) {
+    if (ledger.verificationFailed) {
+      return 'Use the latest failed verification output, fix the failure, and rerun targeted verification.';
+    }
+    return 'Run the routed targeted verification now and inspect its result before stopping.';
+  }
+  return 'Complete the current routed milestone before stopping.';
+}
+
+export function evaluateCompletion({ state = {}, ledger = {} } = {}) {
+  const routeSummary = state?.routeSummary || {};
+  const mode = routeSummary.executionMode || routeSummary.approachSelector?.executionMode || null;
+  const evidence = requiredEvidence(state);
+  if (!IMPLEMENT_MODES.has(mode) || evidence.length === 0 || ledger?.blocker) {
+    return { continue: false, missingEvidence: [] };
+  }
+
+  const sameRequest = !ledger?.requestKey || !state?.requestKey || ledger.requestKey === state.requestKey;
+  const effectiveLedger = sameRequest ? ledger : {};
+  const missingEvidence = evidence.filter((item) => !evidenceSatisfied(item, effectiveLedger));
+  if (missingEvidence.length === 0) {
+    return { continue: false, missingEvidence: [] };
+  }
+
+  const continuationCount = Number(effectiveLedger?.continuationCount || 0);
+  if (continuationCount >= MAX_CONTINUATIONS) {
+    return {
+      continue: false,
+      capped: true,
+      missingEvidence,
+      reason: `UKit continuation cap reached with missing evidence: ${missingEvidence.join(', ')}.`,
+    };
+  }
+
+  const finalAttempt = continuationCount === MAX_CONTINUATIONS - 1;
+  const instruction = recoveryInstruction(missingEvidence, effectiveLedger);
+  return {
+    continue: true,
+    missingEvidence,
+    reason: [
+      `UKit completion gate: missing ${missingEvidence.join(', ')}.`,
+      instruction,
+      finalAttempt ? 'Final automatic recovery attempt: finish now or report a concrete blocker with its evidence.' : null,
+    ].filter(Boolean).join(' '),
+  };
+}
+
+export async function incrementContinuation(projectRoot, payload = {}, ledger = null) {
+  const current = ledger || await readExecutionLedger(projectRoot, payload) || freshLedger(payload, null, 'unknown');
+  const next = {
+    ...current,
+    continuationCount: Number(current.continuationCount || 0) + 1,
+    lastContinuationAt: Date.now(),
+    updatedAt: Date.now(),
+  };
+  await writeJsonAtomic(ledgerPath(projectRoot, payload), next);
+  return next;
+}
+
+async function readStdin() {
+  if (process.stdin.isTTY) return '';
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(String(chunk));
+  return chunks.join('');
+}
+
+async function main() {
+  const payload = JSON.parse((await readStdin()) || '{}');
+  const projectRoot = process.env.CLAUDE_PROJECT_DIR || payload.cwd || process.cwd();
+  if (process.argv.includes('--record')) {
+    await recordExecutionReceipt({
+      projectRoot,
+      payload,
+      toolName: payload.tool_name,
+      harness: process.env.UKIT_HARNESS || 'claude-code',
+    });
+    return;
+  }
+  if (process.argv.includes('--evaluate-stop')) {
+    const state = await readRouteState(projectRoot);
+    const ledger = await readExecutionLedger(projectRoot, payload) || {};
+    const result = evaluateCompletion({ state, ledger });
+    if (result.continue) {
+      await incrementContinuation(projectRoot, payload, ledger);
+      process.stdout.write(`${JSON.stringify({ decision: 'block', reason: result.reason })}\n`);
+    } else if (result.capped) {
+      process.stderr.write(`[ukit-completion] ${result.reason}\n`);
+    }
+  }
+}
+
+// Compare real paths: a project under a symlinked root (macOS /tmp -> /private/tmp, or a
+// symlinked work directory) makes import.meta.url resolve to the real path while argv[1]
+// keeps the symlinked spelling. Without realpath the guard silently never runs the CLI.
+function isDirectRun() {
+  const argvPath = process.argv[1];
+  if (!argvPath) return false;
+  const selfPath = fileURLToPath(import.meta.url);
+  const resolved = path.resolve(argvPath);
+  if (selfPath === resolved) return true;
+  try {
+    return fsSync.realpathSync(selfPath) === fsSync.realpathSync(resolved);
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectRun()) {
+  main().catch((error) => {
+    process.stderr.write(`[ukit-execution-ledger] ${error?.message || error}\n`);
+    process.exitCode = 1;
+  });
+}

package/templates/.claude/ukit/runtime/hook-chain-runner.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const FAIL_CLOSED_SCRIPTS = new Set([
+  'protect-files.sh',
+  'stale-spec-guard.sh',
+  'handoff-model-guard.sh',
+  'vision-gate.sh',
+  'context-hardcap-gate.sh',
+  'block-dangerous.sh',
+  'verification-guard.sh',
+]);
+
+const TOTAL_BUDGET_MS = 10000;
+const CHILD_BUDGET_MS = 4000;
+const MAX_BUFFER_BYTES = 2 * 1024 * 1024;
+
+function safeName(value) {
+  return String(value || 'unknown').replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 96) || 'unknown';
+}
+
+function recordTiming(projectRoot, payload, timing) {
+  try {
+    const dir = path.join(projectRoot, '.ukit', 'storage', 'cache', 'hook-latency');
+    fs.mkdirSync(dir, { recursive: true });
+    const filePath = path.join(dir, `${safeName(payload?.session_id)}.jsonl`);
+    fs.appendFileSync(filePath, `${JSON.stringify(timing)}\n`, 'utf8');
+  } catch {
+    // Timing telemetry is advisory and must never delay or block a tool call.
+  }
+}
+
+function run(payloadText, scriptPaths) {
+  const payload = JSON.parse(payloadText || '{}');
+  const firstScript = scriptPaths[0] || '';
+  const projectRoot = firstScript
+    ? path.resolve(path.dirname(firstScript), '../..')
+    : (payload.cwd || process.cwd());
+  const startedAt = Date.now();
+  const deadline = startedAt + TOTAL_BUDGET_MS;
+  const results = [];
+
+  for (const scriptPath of scriptPaths) {
+    const scriptName = path.basename(scriptPath);
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0) {
+      results.push({
+        scriptName,
+        code: 1,
+        stdout: '',
+        stderr: `hook chain exceeded its ${TOTAL_BUDGET_MS}ms total budget`,
+        killed: true,
+        elapsedMs: 0,
+      });
+      break;
+    }
+
+    const childStartedAt = Date.now();
+    const result = spawnSync(scriptPath, [], {
+      cwd: projectRoot,
+      env: { ...process.env, CLAUDE_PROJECT_DIR: projectRoot },
+      input: payloadText,
+      encoding: 'utf8',
+      timeout: Math.min(CHILD_BUDGET_MS, remainingMs),
+      maxBuffer: MAX_BUFFER_BYTES,
+    });
+    const code = Number.isFinite(result.status) ? result.status : 1;
+    const killed = Boolean(result.signal || result.error?.code === 'ETIMEDOUT');
+    const stderr = [result.stderr, result.error?.message].filter(Boolean).join('\n');
+    results.push({
+      scriptName,
+      code,
+      stdout: result.stdout || '',
+      stderr,
+      killed,
+      elapsedMs: Date.now() - childStartedAt,
+    });
+
+    if (code === 2 || killed || (code !== 0 && FAIL_CLOSED_SCRIPTS.has(scriptName))) {
+      break;
+    }
+  }
+
+  const elapsedMs = Date.now() - startedAt;
+  recordTiming(projectRoot, payload, {
+    ts: Date.now(),
+    hookEvent: payload?.hook_event_name || null,
+    toolName: payload?.tool_name || null,
+    toolUseId: payload?.tool_use_id || null,
+    elapsedMs,
+    budgetMs: TOTAL_BUDGET_MS,
+    scripts: results.map(({ scriptName, code, killed, elapsedMs: scriptElapsedMs }) => ({
+      scriptName,
+      code,
+      killed,
+      elapsedMs: scriptElapsedMs,
+    })),
+  });
+
+  return { results, elapsedMs, budgetMs: TOTAL_BUDGET_MS };
+}
+
+try {
+  const [, , payloadText = '{}', ...scriptPaths] = process.argv;
+  process.stdout.write(JSON.stringify(run(payloadText, scriptPaths)));
+} catch (error) {
+  process.stdout.write(JSON.stringify({
+    results: [],
+    wrapperError: error?.message || String(error),
+  }));
+  process.exitCode = 1;
+}

package/templates/.omp/RULES.md

@@ -1,34 +1,62 @@
 # .omp/RULES.md — sticky always-apply rules
 
 omp re-attaches this file near every turn from its native location (`.omp/RULES.md` only, never a
-copy elsewhere). It carries the always-apply subset of root `CLAUDE.md` that omp's claude provider
-cannot see — that provider only reads `~/.claude/CLAUDE.md` and `<cwd>/.claude/CLAUDE.md`, never root
-`CLAUDE.md`. Keep this short: every line here is a per-turn tax.
+copy elsewhere). It carries the always-apply subset of root `AGENTS.md` that must survive even when
+nothing else is loaded. Keep this short: every line here is a per-turn tax.
 
-## 1. Execution Contract
+## 1. Classify first, then act
+
+- **Trivial** (typo, rename, flag, obvious config) — act directly. No doc reads, no index, no agents.
+- **Simple** (1-2 files, existing pattern) — act directly, pull the smallest useful context.
+- **Non-trivial / risky** (auth, migration, shared runtime, data-loss, flaky) — index-first, then
+  activate the matching skill, then verify.
+
+Pick the lane before the first tool call. Skipping this is what turns a direct chat into a
+scattershot one.
+
+## 2. Execution Contract
 
 For implement/apply/fix requests, continue until the actual edit is made or a real blocker is found.
 Do not stop after a read-only inspection step (read/grep/glob/search).
 
-## 2. No "done" after read-only
+## 3. No "done" after read-only
 
 Never say "done", "applied", or "fixed" after a read-only step. Completion wording requires concrete
 edit/write evidence in the current turn, plus verification when the change is risky.
 
-## 3. Index-first loop
+## 4. Index-first loop
 
 Check `.cache/index/` freshness first. Then run
 `node .claude/ukit/index/query-index.mjs "<error|symbol|path>"` and open only the top 1-3 suspect
 files before widening further. These node scripts work unchanged under omp.
 
-## 4. Safe Patch
+## 5. Auto-activate skills
+
+Skills live in `.claude/skills/` and omp reads them through its `claude` discovery provider — no
+mirror under `.omp/`. On any non-trivial task, and again after the first tool calls reveal what the
+work really is, read the matching `SKILL.md` without being asked. Users never name skills.
+
+## 6. Delegate to bind a model tier
+
+Your own model does not change mid-turn. A tier only applies when work is handed to a task-agent in
+`.omp/agents/`, whose `model:` field (`@lite` / `@code` / `@smart` / `@vision`) resolves through
+`modelRoles` in `.omp/config.yml`.
+
+- `tiny-fix` → `@lite` · `local-fix`, `local-build`, `shared-edit`, `find-cause`, `map-impact` →
+  `@code` · `review-release` → `@smart`
+- Images: `@vision` only. `@code`/`@smart` cannot see images on the UNIC gateway and must never
+  guess at their contents — hand every image to `ukit-vision-analyst` first.
+
+Doing everything inline is exactly what makes UKit look like it only has one model. Keep direct
+execution for trivial/simple work; delegate when the tier differs or when a noisy lane would other-
+wise flood this context.
+
+## 7. Safe Patch
 
 Prefer unique current-file anchors over line numbers or stale pasted blocks. Never silently merge a
 stale spec — re-read current source and confirm before applying. Preserve existing BOM and line
 endings.
 
-## Model roles (see `.omp/config.yml`)
-
-`modelRoles` ships UNIC gateway names as the default. A maintainer on a non-UNIC omp provider edits
-only the three cost-tier values — `lite`, `code`, `smart` — never `vision`, which stays `unic-vision`
-because it is a capability lane, not a cost tier.
+> Maintainer note, not a per-turn rule: `modelRoles` in `.omp/config.yml` ships UNIC gateway names.
+> On a non-UNIC provider, edit only the three cost tiers — `lite`, `code`, `smart` — never `vision`,
+> which stays `unic-vision` because it is a capability lane, not a cost tier.

package/templates/.omp/config.yml

@@ -1,5 +1,6 @@
-# UNIC gateway model names are LITERAL model names, not aliases, and they ship as the
-# installed default. Do NOT substitute sonnet/opus/haiku here. See PLAN.md §3 D15.
+# UNIC gateway model names are stable provider-neutral aliases. Their hidden backend
+# models may change during development; orchestration must not branch on vendor names.
+# Do NOT substitute sonnet/opus/haiku here. See PLAN.md §3 D15.
 #
 # Non-UNIC omp provider? A maintainer edits the three cost tiers to the values in
 # orchestration.modelTiers[*].claudeModel (.ukit/storage/config.json) — currently
@@ -79,10 +80,12 @@ memory:
 # Auto-compact must trigger BEFORE context-hardcap-gate.sh starts blocking tool
 # calls (compact.hardCapTokens, default 220000). Mirrors the Claude Code value
 # env.CLAUDE_CODE_AUTO_COMPACT_WINDOW = 180000 in templates/.claude/settings.json.
-# TODO(verify): the omp key name below is UNVERIFIED — omp is not installed on the
-# planning machine and no omp schema is vendored in this repo. If it is wrong, omp
-# ignores the unknown key and the session simply compacts later, with
-# context-hardcap-gate.sh + hardCapGraceCalls still acting as the backstop.
-# Degrades to "later, harder compact", never to "no gate". See PLAN.md §3 D13.
-compact:
-  autoCompactWindow: 180000   # TODO(verify) key name against a real omp install
+#
+# Key VERIFIED against omp v17.4.2 (2026-08-22): `compaction.thresholdTokens` is a
+# fixed token limit for context maintenance and overrides the percentage threshold
+# when set; omp's own default is -1 ("use compaction.thresholdPercent"). The key this
+# file shipped with in 2.2.1 — `compact.autoCompactWindow` — was a plan-time guess and
+# omp rejects it outright (`omp config get compact.autoCompactWindow` → "Unknown
+# setting"), so auto-compact never moved off omp's default. See PLAN.md §3 D13.
+compaction:
+  thresholdTokens: 180000