@ngockhoale/ukit 2.3.19 → 2.3.21

package/CHANGELOG.md

@@ -2,6 +2,55 @@
 
 All notable changes to UKit are documented here.
 
+## 2.3.21 - 2026-09-13
+
+C16 release — the prompt-caching ruleset turns from research into shipped guidance, and the
+prompt-assembly surfaces that inject into model context are made deterministic. No new commands
+and no default runtime behavior changes: the tool-call policy ships as guidance only, pending the
+A/B required before any behavior change.
+
+- **Canonical prompt-caching ruleset (`docs/PROMPT_CACHING.md`, repo-local).** Distills the UNIC
+  caching roadmap into CTX-01..10 (MUST), the SHOULD set, and the never-do list, with
+  evidence-labeled vendor sections (Anthropic, OpenAI, DeepSeek, GLM, MiniMax) and an
+  adopt/adapt/reject matrix. Upstream vendor docs are reference only — never UNIC guarantees
+  (UNIC behavior is labeled `unknown`/`inferred`). Repo-local by design; not shipped.
+- **Shipped caching guidance (`templates/docs/PROMPT_CACHING.md`).** The distilled CTX rules,
+  never-do list, and short tool-call policy now ship with UKit installs through a new manifest
+  item `docs-prompt-caching` (`mergeStrategy: overwrite_with_backup`, so `ukit update` refreshes
+  it). `templates/CLAUDE.md` and `templates/AGENTS.md` gain a matching `## Prompt Caching`
+  pointer section, and the repo-local `CLAUDE.md`/`AGENTS.md` carry a minimal pointer too.
+- **Deterministic prompt assembly.** `templates/.claude/hooks/skill-router.sh` ordered
+  model-visible memory-recall output by volatile `updatedAt` timestamps, so the same state could
+  assemble different prompt bytes across runs and defeat prompt caching (CTX-01/CTX-04). Ordering
+  is now a stable sort with a deterministic tiebreak and no volatile timestamps in model-visible
+  output; the live `.claude/hooks/` twin is byte-identical. Locked by the new
+  `tests/hooks/promptAssemblyDeterminism.test.js` plus an ordering regression in
+  `tests/hooks/skillRouterHook.test.js`.
+
+## 2.3.20 - 2026-09-13
+
+C15 bug-fix release record — this release completes the silent-stop class on top of the
+already-published 2.3.19 (published to npm 2026-09-13, registry verified, carrying the C14
+valve removal); it adds no new features. npm is the distribution channel and `ukit update`
+pulls from npm, so an install on 2.3.19 (or older) needs an update to receive these fixes.
+
+- **`--evaluate-stop` never releases a routed stop silently.**
+  `templates/.claude/ukit/runtime/execution-ledger.mjs` had a final dispatch with no `else`, so any
+  evaluation result of `{continue:false, notify:false}` that was not `capped` wrote nothing at all
+  — the Stop was allowed and the session idled with no visible reason. That default path is now a
+  loud release: an invisible blocker and a route with empty/short completion evidence both emit a
+  `systemMessage` naming the cause and how to resume, instead of silence. Malformed stdin no longer
+  crashes the hook into a silent stderr exit — it blocks with the crash detail, bounded by a crash
+  counter that loudly releases after the threshold and resets on a clean evaluate.
+- **Fail-loud completion-gate wrappers.**
+  `templates/.claude/hooks/completion-gate.sh` and `templates/.claude/hooks/record-execution.sh`
+  exited 0 silently when the runtime script was missing or failed; both now emit a
+  `systemMessage` naming the missing/failing runtime and the `ukit install` remedy.
+- **omp reentrant stop gets the same never-silent contract as the CLI.**
+  `templates/.omp/hooks/pre/ukit-bridge.js` released a reentrant stop with a non-blocking notice
+  and no continuation; it now blocks with the actionable reason like any other stop, stays bounded
+  by the ledger's continuation cap, and releases loudly at the cap.
+
 ## 2.3.19 - 2026-09-12
 
 C14 bug-fix release record — one correctness fix is shipped; this release adds no new features.

package/manifests/platform.full.yaml

@@ -218,6 +218,20 @@ items:
     packs:
       - core
 
+  # Shipped prompt-caching guidance (CTX-01..10 + never-do + tool-call policy + vendor cheat
+  # sheet). `overwrite_with_backup` so `ukit update` refreshes the ruleset — deliberately NOT
+  # `docs/PROJECT.md`, which is `mergeStrategy: skip` and must never be auto-overwritten.
+  - id: docs-prompt-caching
+    type: config
+    sourceTemplate: docs/PROMPT_CACHING.md
+    targetPath: docs/PROMPT_CACHING.md
+    requires: []
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: core-skill-delivery
     type: skill
     sourceTemplate: .claude/skills/delivery/SKILL.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.3.19",
+  "version": "2.3.21",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex, OpenCode, and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/scripts/release/verify-release.mjs

@@ -1,10 +1,35 @@
 import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
 const rootDir = process.cwd();
 const npmCacheDir = path.join(os.tmpdir(), 'ukit-npm-cache');
 
+// Opt-in post-publish registry-parity check (Release Policy invariant: npm and git always hold
+// the same latest version). Only meaningful AFTER `npm publish` — before publish the registry is
+// behind by definition — so it is gated behind --post-publish and never runs by default.
+const postPublish = process.argv.includes('--post-publish');
+
+if (postPublish) {
+  const localVersion = JSON.parse(readFileSync(path.join(rootDir, 'package.json'), 'utf8')).version;
+  const registryVersion = await readRegistryVersion();
+
+  console.log(`[release:verify] Registry parity (post-publish)`);
+  console.log(`[release:verify] package.json   = ${localVersion}`);
+  console.log(`[release:verify] npm registry   = ${registryVersion}`);
+
+  if (registryVersion !== localVersion) {
+    console.error(
+      `[release:verify] FAILED: registry version ${registryVersion} !== package.json ${localVersion}`,
+    );
+    process.exit(1);
+  }
+
+  console.log('\n[release:verify] All release checks passed.');
+  process.exit(0);
+}
+
 const steps = [
   {
     label: 'Artifact smoke',
@@ -54,3 +79,23 @@ function runStep({ command, args, env }) {
     child.on('error', () => resolve(1));
   });
 }
+
+function readRegistryVersion() {
+  return new Promise((resolve) => {
+    const child = spawn('npm', ['view', '@ngockhoale/ukit', 'version'], {
+      cwd: rootDir,
+      env: { ...process.env, npm_config_cache: npmCacheDir },
+      stdio: ['ignore', 'pipe', 'inherit'],
+    });
+
+    let stdout = '';
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk;
+    });
+    child.on('close', () => {
+      const version = stdout.trim();
+      resolve(version.length > 0 ? version : '<unavailable>');
+    });
+    child.on('error', () => resolve('<unavailable>'));
+  });
+}

package/templates/.claude/hooks/completion-gate.sh

@@ -1,12 +1,24 @@
 #!/bin/bash
 # Stop hook: block premature terminal stops while routed completion evidence is missing.
+# ADVISORY ONLY — always exit 0. A missing or failing runtime must be loud, not a silent pass.
 
 INPUT=$(cat)
 PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
 SCRIPT="$PROJECT_ROOT/.claude/ukit/runtime/execution-ledger.mjs"
 
 if [ ! -f "$SCRIPT" ]; then
+  printf '%s\n' '{"systemMessage":"UKit completion gate: runtime script missing — run: ukit install"}'
   exit 0
 fi
 
-printf '%s' "$INPUT" | UKIT_HARNESS=claude-code node "$SCRIPT" --evaluate-stop
+OUTPUT=$(printf '%s' "$INPUT" | UKIT_HARNESS=claude-code node "$SCRIPT" --evaluate-stop)
+STATUS=$?
+
+if [ "$STATUS" -ne 0 ]; then
+  printf '%s\n' '{"systemMessage":"UKit completion gate: runtime script failed — run: ukit install"}'
+  exit 0
+fi
+
+if [ -n "$OUTPUT" ]; then
+  printf '%s\n' "$OUTPUT"
+fi

package/templates/.claude/hooks/record-execution.sh

@@ -1,12 +1,24 @@
 #!/bin/bash
 # PostToolUse hook: persist session-scoped source/write/verification receipts.
+# ADVISORY ONLY — always exit 0. A missing or failing runtime must be loud, not a silent pass.
 
 INPUT=$(cat)
 PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
 SCRIPT="$PROJECT_ROOT/.claude/ukit/runtime/execution-ledger.mjs"
 
 if [ ! -f "$SCRIPT" ]; then
+  printf '%s\n' '{"systemMessage":"UKit record execution: runtime script missing — run: ukit install"}'
   exit 0
 fi
 
-printf '%s' "$INPUT" | UKIT_HARNESS=claude-code node "$SCRIPT" --record
+OUTPUT=$(printf '%s' "$INPUT" | UKIT_HARNESS=claude-code node "$SCRIPT" --record)
+STATUS=$?
+
+if [ "$STATUS" -ne 0 ]; then
+  printf '%s\n' '{"systemMessage":"UKit record execution: runtime script failed — run: ukit install"}'
+  exit 0
+fi
+
+if [ -n "$OUTPUT" ]; then
+  printf '%s\n' "$OUTPUT"
+fi

package/templates/.claude/hooks/skill-router.sh

@@ -961,8 +961,12 @@ const { pathToFileURL } = require('url');
       return 0;
     }
 
-    const recencyBonus = getMemoryTimestamp(item) > 0 ? Math.min(1, getMemoryTimestamp(item) / Date.now()) : 0;
-    return score + recencyBonus;
+    // TASK-027 CTX-01/CTX-04: the ranking must be a pure function of the logical memory
+    // content. A recency bonus scaled by Date.now() made the score — and therefore the
+    // injected previous-context block, its persisted order, and the PreCompact reinjection —
+    // shift on every wall-clock tick. Eligibility is unchanged (still score > 0); only the
+    // volatile ordering signal is dropped.
+    return score;
   }
 
   function buildPreviousContextSnippet(item) {
@@ -1017,9 +1021,12 @@ const { pathToFileURL } = require('url');
         score: scoreMemoryItem(item, queryTokens),
       }))
       .filter((entry) => entry.score > 0)
+      // CTX-01: ties break on the stable logical id (never on a volatile timestamp), so the
+      // same memory set always yields the same injected order regardless of when the
+      // entries were last written/ended.
       .sort((left, right) => (
         right.score - left.score
-        || getMemoryTimestamp(right.item) - getMemoryTimestamp(left.item)
+        || left.item.id.localeCompare(right.item.id)
       ))
       .slice(0, 2)
       .map((entry) => entry.item);

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

@@ -13,6 +13,12 @@ const RESUME_INTENT_TTL_MS = 30 * 60 * 1000;
 const MAX_RECEIPTS = 24;
 const MAX_SOURCE_FILES = 16;
 const MAX_CONTINUATIONS = 6;
+// A malformed stdin payload crashes `--evaluate-stop` before a route/session can be read, so
+// the only identity available is the project root. Count consecutive crashes there and, once
+// this bounded budget is exhausted, release LOUD (naming the crash + `ukit install`) instead of
+// blocking forever on a corrupt hook input. A successful evaluate resets the count. Mirrors
+// MAX_CONTINUATIONS style — a hard-coded module const, deliberately not a config knob.
+const MAX_GATE_CRASHES = 3;
 // Two adjacent identical failed verifications (no edit attempt between them) are a loop;
 // vibecode routes — which bypass the cap and every reentrant valve — additionally get a
 // cumulative escape after the same verification failed this many times across edits.
@@ -82,6 +88,17 @@ function ledgerPath(projectRoot, payload = {}) {
   );
 }
 
+function crashCounterPath(projectRoot) {
+  return path.join(
+    projectRoot,
+    '.ukit',
+    'storage',
+    'cache',
+    'exec-ledger',
+    'gate-crash-counter.json',
+  );
+}
+
 function resumeIntentPath(projectRoot, sessionId) {
   return path.join(
     projectRoot,
@@ -727,10 +744,32 @@ export function evaluateCompletion({ state = {}, ledger = {} } = {}) {
         reason: `UKit stopped automatic recovery: ${ledger.blocker.detail || 'a recorded blocker ended this run.'}`,
       };
     }
+    // An invisible blocker (e.g. a permission decision the model already named in its own
+    // reply) must not loop — but it must not end silent either. Release loud so the user can
+    // tell a deliberate stop from a stall.
+    return {
+      continue: false,
+      notify: true,
+      missingEvidence: [],
+      reason: `UKit stopped automatic recovery: ${ledger.blocker.detail || 'a recorded blocker ended this run.'}`,
+    };
+  }
+  if (!state || !state.routeSummary) {
+    // No routable state at all: a never-routed session (or a foreign-owned one) is silent
+    // success — there is nothing to report. The CLI's lost-route path handles the case where
+    // THIS session has ledger activity but the state vanished; callers that pass no state
+    // (e.g. the omp bridge for a session it does not own) must not be force-notified.
     return { continue: false, notify: false, missingEvidence: [] };
   }
   if (evidence.length === 0) {
-    return { continue: false, notify: false, missingEvidence: [] };
+    // A route with no completion evidence has no actionable block reason — blocking would
+    // loop unboundedly. Release loud instead of ending indistinguishable from a stall.
+    return {
+      continue: false,
+      notify: true,
+      missingEvidence: [],
+      reason: 'UKit completion gate: this route carries no completion evidence to verify, so the stop released without checking unfinished work. Send the task again in a new message to re-route it with a completion contract.',
+    };
   }
 
   // Request identity is the prompt (see evidencePromptKey): the router re-keys requestKey on
@@ -742,7 +781,10 @@ export function evaluateCompletion({ state = {}, ledger = {} } = {}) {
   const effectiveLedger = sameRequest ? ledger : {};
   const missingEvidence = evidence.filter((item) => !evidenceSatisfied(item, effectiveLedger, routeSummary));
   if (missingEvidence.length === 0) {
-    return { continue: false, notify: false, missingEvidence: [] };
+    // Silent success: the route is present and every required evidence is satisfied. Marked
+    // `complete` so the CLI dispatch recognizes it BEFORE the loud final else — otherwise a
+    // bare loud else would turn a clean stop into user-visible noise.
+    return { continue: false, notify: false, complete: true, missingEvidence: [] };
   }
 
   // `find-cause` can validly end clean: an investigation may establish that no actionable
@@ -907,7 +949,121 @@ async function readStdin() {
   return chunks.join('');
 }
 
+// Malformed hook input crashes the evaluate BEFORE any route/session can be read, so the only
+// stable identity is the project root. Count consecutive crashes there; past MAX_GATE_CRASHES,
+// release LOUD naming the crash and the remedy instead of blocking a corrupt hook forever. Any
+// counter I/O failure fails SAFE to block (still loud, never silent). A successful evaluate
+// resets the count.
+async function handleEvaluateCrash(projectRoot, error) {
+  const detail = `malformed hook input crashed the completion gate (${error?.message || error})`;
+  const blockReason = () => `${detail}. This is the UKit completion gate, not the task — re-send the task in a new message so the hook payload is regenerated.`;
+  let count = 0;
+  try {
+    const current = await readJson(crashCounterPath(projectRoot), null);
+    count = Number(current?.count) || 0;
+  } catch {
+    count = 0;
+  }
+  const next = count + 1;
+  try {
+    await writeJsonAtomic(crashCounterPath(projectRoot), { count: next, updatedAt: Date.now() });
+  } catch {
+    // Counter unwritable: we cannot bound the crash loop, but silence is never an option.
+    process.stdout.write(`${JSON.stringify({ decision: 'block', reason: blockReason() })}\n`);
+    return;
+  }
+  if (next >= MAX_GATE_CRASHES) {
+    const message = `UKit completion gate: ${detail}. This recurred ${next} times and cannot be bounded, so the stop is releasing loudly instead of blocking again. The hook payload is corrupt — run: ukit install to refresh the runtime, then re-send the task in a new message.`;
+    process.stderr.write(`[ukit-completion] ${message}\n`);
+    process.stdout.write(`${JSON.stringify({ systemMessage: message })}\n`);
+    return;
+  }
+  process.stdout.write(`${JSON.stringify({ decision: 'block', reason: blockReason() })}\n`);
+}
+
+async function resetGateCrashCounter(projectRoot) {
+  // Only touch disk when a crash was actually counted — a clean stop on a healthy project
+  // must not create/rewrite a crash-counter file.
+  try {
+    await fs.access(crashCounterPath(projectRoot));
+  } catch {
+    return;
+  }
+  try {
+    await writeJsonAtomic(crashCounterPath(projectRoot), { count: 0, updatedAt: Date.now() });
+  } catch {
+    // Best-effort: an unwritable counter only means the next crash blocks again, which is safe.
+  }
+}
+
+async function runEvaluateStop() {
+  const projectRoot = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  let payload;
+  try {
+    payload = JSON.parse((await readStdin()) || '{}');
+  } catch (error) {
+    await handleEvaluateCrash(projectRoot, error);
+    return;
+  }
+  // A parse that reached here is a functioning evaluate — reset the crash budget so the next
+  // malformed payload starts blocking again.
+  await resetGateCrashCounter(projectRoot);
+
+  const state = await readRouteState(projectRoot, payload);
+  const ledger = await readExecutionLedger(projectRoot, payload) || {};
+
+  // A session ledger with activity proves this session was routed and accumulating evidence.
+  // If the route state is now missing or unreadable (router crashed/timed out before
+  // persisting it, or the session stamp was lost), the gate cannot evaluate completion — and
+  // ending silently there is indistinguishable from a mid-run stall. Surface the loss so the
+  // user sees WHY the run released. Sessions that were never routed (no ledger activity at
+  // all) stay silent: there is nothing to report (silent-success carve-out).
+  if (!state) {
+    const hasActivity = ledger.sourceSucceeded || ledger.writeAttempted
+      || ledger.verificationAttempted || (ledger.receipts || []).length > 0;
+    if (!hasActivity) return;
+    process.stdout.write(`${JSON.stringify({
+      systemMessage: 'UKit completion gate: route state for this session was lost before the stop was evaluated (router did not persist it), so unfinished work could not be verified. Send the task again in a new message to re-route and finish it.',
+    })}\n`);
+    return;
+  }
+
+  const result = evaluateCompletion({ state, ledger });
+
+  // A reentrant Stop (Claude Code re-fires Stop after this hook already blocked once) is
+  // gated exactly like any other Stop: while evidence is still missing it blocks again with
+  // the actionable reason instead of silently releasing the recovery turn. Loop termination
+  // is guaranteed elsewhere — non-vibecode routes end at the continuation cap (final-notice
+  // block -> capped visible release), and vibecode ends on the visible verification-loop
+  // blocker.
+  if (result.continue) {
+    if (result.finalNotice) await markNotified(projectRoot, payload, ledger);
+    else await incrementContinuation(projectRoot, payload, ledger, state?.requestKey || null, evidencePromptKey(state));
+    process.stdout.write(`${JSON.stringify({ decision: 'block', reason: result.reason })}\n`);
+    return;
+  }
+  if (result.capped || result.notify) {
+    // Non-blocking endings (non-gated modes, an invisible blocker, an evidence-less route, or
+    // cap reached after the final notice) must still tell the user what is unfinished — a
+    // silent end is indistinguishable from a stall.
+    process.stderr.write(`[ukit-completion] ${result.reason}\n`);
+    process.stdout.write(`${JSON.stringify({ systemMessage: result.reason })}\n`);
+    return;
+  }
+  if (result.complete) return; // silent success: route present, all evidence satisfied
+  // Defensive final else: no evaluation result may ever end a routed stop silently.
+  const fallback = `UKit completion gate: the stop was evaluated without a decision (missing evidence: ${(result.missingEvidence || []).join(', ') || 'none'}). If work is unfinished, re-send the task in a new message.`;
+  process.stderr.write(`[ukit-completion] ${fallback}\n`);
+  process.stdout.write(`${JSON.stringify({ systemMessage: fallback })}\n`);
+}
+
 async function main() {
+  // Dispatch the stop flag BEFORE parsing stdin: a malformed payload used to throw out of
+  // main(), hit the .catch (stderr + exit 1) with no decision, and release the stop silently.
+  if (process.argv.includes('--evaluate-stop')) {
+    await runEvaluateStop();
+    return;
+  }
   const payload = JSON.parse((await readStdin()) || '{}');
   const projectRoot = process.env.CLAUDE_PROJECT_DIR || payload.cwd || process.cwd();
   if (process.argv.includes('--record')) {
@@ -917,44 +1073,6 @@ async function main() {
       toolName: payload.tool_name,
       harness: process.env.UKIT_HARNESS || 'claude-code',
     });
-    return;
-  }
-  if (process.argv.includes('--evaluate-stop')) {
-    const state = await readRouteState(projectRoot, payload);
-    const ledger = await readExecutionLedger(projectRoot, payload) || {};
-    const result = evaluateCompletion({ state, ledger });
-
-    // A session ledger with activity proves this session was routed and accumulating
-    // evidence. If the route state is now missing or unreadable (router crashed/timed out
-    // before persisting it, or the session stamp was lost), the gate cannot evaluate
-    // completion — and ending silently there is indistinguishable from a mid-run stall.
-    // Surface the loss so the user sees WHY the run released. Sessions that were never
-    // routed (no ledger activity at all) stay silent: there is nothing to report.
-    if (!state && (ledger.sourceSucceeded || ledger.writeAttempted
-      || ledger.verificationAttempted || (ledger.receipts || []).length > 0)) {
-      process.stdout.write(`${JSON.stringify({
-        systemMessage: 'UKit completion gate: route state for this session was lost before the stop was evaluated (router did not persist it), so unfinished work could not be verified. Send the task again in a new message to re-route and finish it.',
-      })}\n`);
-      return;
-    }
-
-    // A reentrant Stop (Claude Code re-fires Stop after this hook already blocked once) is
-    // gated exactly like any other Stop: while evidence is still missing it blocks again
-    // with the actionable reason instead of silently releasing the recovery turn. Loop
-    // termination is guaranteed elsewhere — non-vibecode routes end at the continuation cap
-    // (final-notice block -> capped visible release), and vibecode ends on the visible
-    // verification-loop blocker.
-
-    if (result.continue) {
-      if (result.finalNotice) await markNotified(projectRoot, payload, ledger);
-      else await incrementContinuation(projectRoot, payload, ledger, state?.requestKey || null, evidencePromptKey(state));
-      process.stdout.write(`${JSON.stringify({ decision: 'block', reason: result.reason })}\n`);
-    } else if (result.capped || result.notify) {
-      // Non-blocking endings (non-gated modes, or cap reached after the final notice) must
-      // still tell the user what is unfinished — a silent end is indistinguishable from a stall.
-      process.stderr.write(`[ukit-completion] ${result.reason}\n`);
-      process.stdout.write(`${JSON.stringify({ systemMessage: result.reason })}\n`);
-    }
   }
 }
 

package/templates/.omp/hooks/pre/ukit-bridge.js

@@ -14,7 +14,6 @@ import {
   evidencePromptKey,
   incrementContinuation,
   markNotified,
-  noteStopProgress,
   readExecutionLedger,
   readRouteState,
   recordExecutionReceipt,
@@ -634,23 +633,6 @@ export async function runSessionStop(
   }
 
   if (suppliedLedger === undefined) {
-    // Claude Code flags reentrant stops with stop_hook_active and the ledger CLI releases on
-    // them; omp's session_stop carries no such field. Detect the equivalent from the ledger:
-    // when the recovery turn produced no new receipts since the stop that blocked it,
-    // blocking again would only burn another turn in a self-sustaining loop — release with a
-    // visible reason instead. Vibecode autonomy keeps pushing (same as the CLI valve).
-    let reentrantStop = false;
-    try {
-      reentrantStop = (await noteStopProgress(projectRoot, payload)).reentrant === true;
-    } catch {
-      reentrantStop = false;
-    }
-    if (reentrantStop && state?.routeSummary?.autonomyLevel !== 'vibecode') {
-      const notice = `UKit stopped automatic recovery after one continuation: ${evaluation.reason}`;
-      pi.logger?.warn?.(`[UKit] ${notice}`);
-      sendContext(pi, [notice], 'nextTurn', { display: true });
-      return undefined;
-    }
     try {
       if (evaluation.finalNotice) await markNotified(projectRoot, payload, ledger);
       else await incrementContinuation(projectRoot, payload, ledger, state?.requestKey || null, evidencePromptKey(state));

package/templates/AGENTS.md

@@ -106,6 +106,14 @@ For clearly non-code specialist lanes (docs-only, status, task queue), skip the
 - Threshold-based compact pressure is internal orchestration; do not expose it to users.
 - For Codex Desktop long sessions, UKit can use soft auto-compact handoffs. Default `compact.codexContext.compactTarget=150` means about 150 compact handoff lines (120-150 preferred, hard max 170), not 150 tokens.
 
+## Prompt Caching
+
+- Deterministic, stable context lets a provider reuse a prompt prefix — and it is worth doing even when no caching is guaranteed.
+- Full ruleset: `docs/PROMPT_CACHING.md` (read on demand; it is not loaded into every session).
+- CTX-01 deterministic segment bytes · CTX-02 keep roles and order · CTX-03 keep tool IDs and continuation state · CTX-04 no clock/random IDs in static blocks · CTX-05 compaction starts a new epoch · CTX-06 never change data to match a cache · CTX-07 no unconfirmed cache fields · CTX-08 tool-result reuse needs valid freshness · CTX-09 missing usage is unknown, not zero · CTX-10 never cut a required check to reduce calls.
+- Never sort messages, trim meaningful whitespace, rewrite reasoning fields, or move a user request into system context.
+- Upstream vendor docs are reference only — never a guarantee about the route you actually use.
+
 ## Safe Patch Protocol
 
 - Safe Patch is internal orchestration: normal users still only need `ukit install` and natural language.

package/templates/CLAUDE.md

@@ -106,6 +106,14 @@ For clearly non-code specialist lanes (docs-only, status, task queue), skip the
 - Threshold-based compact pressure is internal orchestration; do not expose it to users.
 - For Codex Desktop long sessions, UKit can use soft auto-compact handoffs. Default `compact.codexContext.compactTarget=150` means about 150 compact handoff lines (120-150 preferred, hard max 170), not 150 tokens.
 
+## Prompt Caching
+
+- Deterministic, stable context lets a provider reuse a prompt prefix — and it is worth doing even when no caching is guaranteed.
+- Full ruleset: `docs/PROMPT_CACHING.md` (read on demand; it is not loaded into every session).
+- CTX-01 deterministic segment bytes · CTX-02 keep roles and order · CTX-03 keep tool IDs and continuation state · CTX-04 no clock/random IDs in static blocks · CTX-05 compaction starts a new epoch · CTX-06 never change data to match a cache · CTX-07 no unconfirmed cache fields · CTX-08 tool-result reuse needs valid freshness · CTX-09 missing usage is unknown, not zero · CTX-10 never cut a required check to reduce calls.
+- Never sort messages, trim meaningful whitespace, rewrite reasoning fields, or move a user request into system context.
+- Upstream vendor docs are reference only — never a guarantee about the route you actually use.
+
 ## Safe Patch Protocol
 
 - Safe Patch is internal orchestration: normal users still only need `ukit install` and natural language.

package/templates/docs/PROMPT_CACHING.md

@@ -0,0 +1,127 @@
+# Prompt Caching — guidance for UKit projects
+
+Prompt caching is a **prefix match**: a provider can reuse the computation of an input prefix
+when a later request reproduces that prefix byte-for-byte. UKit cannot control the transport or
+the provider cache engine, but it *does* control the instruction, skill, tool and hook-injected
+content it renders. This file ships with UKit so every installed project gets the same rules for
+keeping that content deterministic and stable. Read it on demand — it is deliberately not loaded
+into every session.
+
+## Why stable context matters
+
+- Cache reuse is **reported**, not controllable. A `cache_read` counter (or a vendor equivalent)
+  proves the provider *reported* a reuse; it never proves which layer served it.
+- Three mechanisms must never be conflated: the **provider prompt cache** (reuses input
+  computation), a **local tool-result cache** (the host reuses a still-valid result), and a
+  **response cache** (the application replays a stored answer).
+- Three counts must never be conflated: a **logical model turn**, a **client HTTP attempt**, and a
+  **tool execution**.
+- The rules below hold even if no cache capability exists behind your provider, because they
+  govern content UKit itself renders.
+
+## CTX rules — MUST
+
+| ID | Rule | What it means in practice |
+|---|---|---|
+| CTX-01 | Same logical input and config produce the same segment bytes | Render owned blocks deterministically; no ordering that varies run-to-run |
+| CTX-02 | Preserve instruction/user/tool roles and conversation order | Never move a user ask into system or reorder history to lengthen a prefix |
+| CTX-03 | Keep all tool IDs and required native continuation state intact | Never strip tool-call IDs or reasoning/continuation fields to shrink a request |
+| CTX-04 | Do not inject clock/random IDs into static instructions | Static blocks carry no date, UUID or counter; volatile values go in the tail |
+| CTX-05 | Every summary/compaction creates a new context epoch | Compaction is a decision with a cost; when it happens it starts a new epoch |
+| CTX-06 | Never change data or code to match the cache | Cache optimization never edits content semantics — correctness over prefix |
+| CTX-07 | Do not self-send a field the adapter has not confirmed as supported | Optional cache params only when capability is verified; HTTP 200 is not proof |
+| CTX-08 | Tool-result cache reuse only when freshness/dependency is valid | Local reuse needs a freshness predicate and dependency fingerprint, not just a query match |
+| CTX-09 | Never treat missing usage as zero | Missing cache counters are unknown plus lowered coverage, never a reported miss |
+| CTX-10 | Never exceed existing instructions/permissions to cut calls | Reducing tool calls never means skipping a required check or test |
+
+## Never do
+
+- Never sort messages or reasoning blocks alphabetically.
+- Never trim code literals, signed content, or data where whitespace is meaningful.
+- Never rewrite native reasoning/signature/encrypted continuation fields.
+- Never move a user request into system to lengthen the stable prefix.
+- Never promote untrusted documents or tool output to the developer/system role.
+- Never hash one text and assume every occurrence shares the provider cache.
+- Never add a timestamp just to log — keep log metadata outside model-visible content.
+
+## Runtime tool-call policy (condensed, guidance only)
+
+This is guidance for how an assistant should decide when to call tools. It is **not** a rigid
+"always at least N tools" or "max N tools" rule, and UKit does not change any default behavior
+on its basis.
+
+1. Before calling a tool, decide which data is still missing to finish the request.
+2. Reuse evidence you already hold if it is still valid; check the version before reuse.
+3. Batch independent reads when the interface supports it.
+4. For dependent actions, wait for the needed result before deciding the next step.
+5. Prefer scoped queries with enough output to verify.
+6. If a result was truncated or insufficient, widen deliberately.
+7. On tool error, distinguish parameter error, transient error, and unknown state.
+8. After a change, run the check appropriate to the risk and the repo's requirements.
+9. When the completion condition is met, return the result — check further only for specific
+   remaining risk.
+
+## Vendor cheat sheet
+
+The sections below describe how each upstream vendor documents its own caching. They are
+**reference material only** — see "Upstream docs are not provider guarantees" below. Provider
+minimums and rates change; treat the shapes here as orientation and **verify against the current
+official docs** (links in each section) before relying on a number.
+
+### Anthropic
+
+- **Mechanism:** explicit cache breakpoints (`cache_control: {"type": "ephemeral"}`) on cacheable
+  content blocks; a single top-level marker enables automatic caching on the last eligible block.
+- **Minimum cacheable size:** model-dependent, roughly 512 to 4096 input tokens; shorter prompts
+  are silently not cached.
+- **Discount shape:** cache reads are billed at a small fraction of the normal input rate; cache
+  writes carry a premium; an optional longer TTL costs more to write.
+- **Docs:** https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching ·
+  https://docs.anthropic.com/en/docs/about-claude/pricing
+
+### OpenAI
+
+- **Mechanism:** implicit (automatic) caching; recent models also accept explicit cache markers,
+  and a prompt cache key can steer routing or cache accounting.
+- **Minimum cacheable size:** roughly 1024 visible input tokens on recent models; varies with
+  request settings on older ones.
+- **Discount shape:** cached reads are heavily discounted relative to input; cache writes are
+  billed at a modest premium on recent models and carry no extra write charge on older ones.
+- **Docs:** https://developers.openai.com/api/docs/guides/prompt-caching
+
+### DeepSeek
+
+- **Mechanism:** automatic, best-effort prefix caching; a cached prefix is an indivisible unit, so
+  partial overlap does not hit.
+- **Minimum cacheable size:** not documented.
+- **Discount shape:** a separate lower per-model cache-hit rate versus the cache-miss rate.
+- **Note:** with tools present, reasoning content must be passed back on every later request.
+- **Docs:** https://api-docs.deepseek.com/guides/kv_cache
+
+### GLM
+
+- **Mechanism:** implicit caching triggered by content similarity; no explicit create or
+  invalidate API is documented.
+- **Minimum cacheable size:** not documented.
+- **Discount shape:** a separate per-model cached-input rate, not a universal ratio — do not
+  assume a fixed percentage.
+- **Docs:** https://docs.z.ai/guides/capabilities/cache
+
+### MiniMax
+
+- **Mechanism:** passive automatic prefix caching, plus explicit Anthropic-compatible
+  `cache_control` breakpoints on cacheable blocks.
+- **Minimum cacheable size:** caching applies from roughly 512 tokens upward.
+- **Discount shape:** explicit cache writes are billed at a premium and reads at a fraction of
+  input; passive cache writes carry no additional charge.
+- **Docs:** https://platform.minimax.io/docs/api-reference/text-prompt-caching.md
+
+## Upstream docs are not provider guarantees
+
+A vendor documenting a cache feature does **not** mean the gateway or route you actually use
+forwards it, returns the same usage fields, or bills it the same way. Treat every statement about
+cache behavior behind a gateway as a hypothesis, not a guarantee: verify cache parameters and
+usage counters against the raw response of the exact endpoint you call, and against the current
+official docs linked above. If a usage counter is absent, it is **unknown** — never a reported
+zero (CTX-09). When project information changes mid-session, prefer correctness over a preserved
+prefix: send the new version and accept whatever cache invalidation follows.