@ngockhoale/ukit 2.6.9 → 2.6.10

package/package.json

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

package/src/cli/commands/metrics.js

@@ -0,0 +1,127 @@
+// `ukit metrics` — read-only telemetry roll-up (SPEC §6, SI-102).
+// Route outcomes + failure patterns (lazy, degrade to n/a) + v2 memory count.
+// Never exits non-zero on missing telemetry; unknown flag → exit 1.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { collectRouteOutcomes } from '../../diagnostics/routeOutcomes.js';
+import { buildRuntimePaths } from '../../core/runtimePaths.js';
+
+const HELP_FLAGS = new Set(['--help', '-h', 'help']);
+const KNOWN_FLAGS = new Set(['--json']);
+
+const MODE_FIELDS = ['routes', 'joined', 'writeOk', 'writeFail', 'verifyAttempted', 'verifyOk', 'verifyFail', 'rescue', 'stalled'];
+
+function printUsage() {
+  console.log('Usage: ukit metrics [--json]');
+  console.log('');
+  console.log('Print a read-only roll-up of UKit telemetry:');
+  console.log('  route-outcomes    route-audit ↔ exec-ledger join stats per mode/taskType');
+  console.log('  failure-patterns  mined failure signatures (n/a when unavailable)');
+  console.log('  memory            v2 record count by status');
+  console.log('');
+  console.log('Options:');
+  console.log('  --json   Print the full roll-up object as JSON');
+}
+
+async function collectMemorySummary(projectRoot) {
+  try {
+    const { memoryV2RecordsPath } = buildRuntimePaths(projectRoot);
+    const raw = await fs.readFile(memoryV2RecordsPath, 'utf8');
+    const doc = JSON.parse(raw);
+    const records = Array.isArray(doc) ? doc : (Array.isArray(doc?.records) ? doc.records : []);
+    const byStatus = {};
+    for (const record of records) {
+      const status = record?.status ?? 'unknown';
+      byStatus[status] = (byStatus[status] ?? 0) + 1;
+    }
+    return { total: records.length, byStatus };
+  } catch {
+    return { total: 0, byStatus: {} };
+  }
+}
+
+async function collectFailurePatterns(projectRoot) {
+  try {
+    const mod = await import('../../diagnostics/failurePatterns.js');
+    if (typeof mod?.mineFailurePatterns !== 'function') return null;
+    return await mod.mineFailurePatterns(projectRoot);
+  } catch {
+    return null;
+  }
+}
+
+function printRouteOutcomes(routeOutcomes) {
+  console.log('route-outcomes');
+  console.log(`  ledgers: ${routeOutcomes.ledgersScanned}  audit rows: ${routeOutcomes.auditRowsScanned}  joined: ${routeOutcomes.joined}  coverage: ${(routeOutcomes.joinCoverage * 100).toFixed(1)}%  unmatched audit: ${routeOutcomes.unmatchedAudit}  unmatched ledger: ${routeOutcomes.unmatchedLedger}`);
+  const header = ['mode', ...MODE_FIELDS];
+  console.log(`  ${header.join('\t')}`);
+  for (const [mode, bucket] of Object.entries(routeOutcomes.byMode)) {
+    console.log(`  ${[mode, ...MODE_FIELDS.map((field) => bucket[field] ?? 0)].join('\t')}`);
+  }
+  if (Object.keys(routeOutcomes.byMode).length === 0) {
+    console.log('  (no route-audit data)');
+  }
+}
+
+function printFailurePatterns(failurePatterns) {
+  console.log('failure-patterns');
+  if (!failurePatterns) {
+    console.log('  n/a');
+    return;
+  }
+  const patterns = Array.isArray(failurePatterns.patterns) ? failurePatterns.patterns : [];
+  if (patterns.length === 0) {
+    console.log('  (none)');
+    return;
+  }
+  for (const pattern of patterns) {
+    console.log(`  ${pattern.count}× ${pattern.signature}  sessions=${pattern.sessions}`);
+  }
+}
+
+function printMemory(memory) {
+  const statusPairs = Object.entries(memory.byStatus).map(([status, count]) => `${status}=${count}`).join(' ');
+  console.log(`memory: v2 records=${memory.total}${statusPairs ? `  (${statusPairs})` : ''}`);
+}
+
+export async function runMetrics({ projectRoot, argv = [] }) {
+  if (argv.some((flag) => HELP_FLAGS.has(flag))) {
+    printUsage();
+    return;
+  }
+  const unknown = argv.filter((flag) => !KNOWN_FLAGS.has(flag));
+  if (unknown.length > 0) {
+    console.error(`[UKit] Unknown metrics flag(s): ${unknown.join(', ')}`);
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
+
+  const routeOutcomes = await collectRouteOutcomes(projectRoot).catch((error) => ({
+    ledgersScanned: 0,
+    auditRowsScanned: 0,
+    joined: 0,
+    unmatchedAudit: 0,
+    unmatchedLedger: 0,
+    byMode: {},
+    byTaskType: {},
+    joinCoverage: 0,
+    error: error?.message ?? String(error),
+  }));
+  const failurePatterns = await collectFailurePatterns(projectRoot);
+  const memory = await collectMemorySummary(projectRoot);
+
+  const rollup = { routeOutcomes, failurePatterns, memory };
+
+  if (argv.includes('--json')) {
+    console.log(JSON.stringify(rollup, null, 2));
+    return;
+  }
+
+  printRouteOutcomes(routeOutcomes);
+  console.log('');
+  printFailurePatterns(failurePatterns);
+  console.log('');
+  printMemory(memory);
+}

package/src/cli/index.js

@@ -7,6 +7,7 @@ import { runStatus } from './commands/status.js';
 import { runMemory } from './commands/memory.js';
 import { runUpdate } from './commands/update.js';
 import { runCode } from './commands/code.js';
+import { runMetrics } from './commands/metrics.js';
 
 const GLOBAL_FLAGS = new Set(['--help', '-h', '--version', '-v']);
 
@@ -65,6 +66,11 @@ export async function runCli({ argv, packageRoot, projectRoot, packageVersion })
     return;
   }
 
+  if (command === 'metrics') {
+    await runMetrics({ projectRoot, argv: commandArgv });
+    return;
+  }
+
   if (command === 'update') {
     await runUpdate({ packageVersion, argv: commandArgv });
     return;
@@ -98,6 +104,7 @@ export async function runCli({ argv, packageRoot, projectRoot, packageVersion })
     console.log('  code               Context compiler surface (peek/search/context/impact)');
     console.log('  status             Show UKit runtime status');
     console.log('  memory             Inspect shared UKit memory');
+    console.log('  metrics            Telemetry roll-up (route outcomes, failure patterns, memory)');
     console.log('  update             Upgrade the global UKit CLI to the latest version');
     console.log('  version            Show UKit version');
     console.log('');

package/src/diagnostics/failurePatterns.js

@@ -0,0 +1,187 @@
+// failurePatterns.js — advisory failure-pattern mining over exec-ledger receipts (SI-103).
+//
+// What this is for: ledgers already record every verification receipt, but nothing
+// distilled "which commands keep failing". This module scans
+// `.ukit/storage/cache/exec-ledger/*.json`, extracts failed verification receipts,
+// normalizes each command into a deterministic two-token signature, and persists the
+// top patterns to `.ukit/storage/cache/failure-patterns.json` for `ukit metrics`.
+//
+// Contracts (asserted by tests/core/failurePatterns.test.js):
+//   * NEVER THROWS. Missing dir, malformed JSON, unreadable files → zeroed/partial
+//     result, no exception escapes. Artifact write failure is non-fatal: the computed
+//     object is still returned.
+//   * EVIDENCE-ONLY / ADVISORY. Zero writes to memory store, MEMORY.md, or routing
+//     inputs — the only side effect is the last-result cache artifact.
+//   * Deterministic normalization: first two whitespace tokens, lowercased;
+//     path-like and numeric tokens collapse to `<arg>`.
+//   * Same ledger-dir discipline as SPEC §4: glob `*.json`, skip
+//     `gate-crash-counter.json`, `*.journal*`, `*.quarantine*`, bound by mtime.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const LEDGER_DIR_REL = path.join('.ukit', 'storage', 'cache', 'exec-ledger');
+const ARTIFACT_REL = path.join('.ukit', 'storage', 'cache', 'failure-patterns.json');
+const NON_LEDGER_FILES = new Set(['gate-crash-counter.json']);
+const MAX_PATTERNS = 10;
+const MAX_EXAMPLES = 3;
+
+// Receipt kinds that count as verification-ish evidence.
+const VERIFY_KINDS = new Set(['verify', 'verification']);
+
+function isObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isLedgerFilename(name) {
+  if (typeof name !== 'string' || !name.endsWith('.json')) return false;
+  if (NON_LEDGER_FILES.has(name)) return false;
+  if (name.includes('.journal')) return false;
+  if (name.includes('.quarantine')) return false;
+  return true;
+}
+
+// First two whitespace tokens, lowercased; path-like or numeric tokens become `<arg>`.
+function normalizeSignature(command) {
+  if (typeof command !== 'string') return null;
+  const tokens = command.trim().toLowerCase().split(/\s+/).filter(Boolean);
+  if (tokens.length === 0) return null;
+  const head = tokens.slice(0, 2).map((token) => {
+    if (/^\d+(\.\d+)?$/.test(token)) return '<arg>';
+    if (token.includes('/') || token.includes('\\') || token.endsWith('.js')
+      || token.endsWith('.ts') || token.endsWith('.json')) {
+      return '<arg>';
+    }
+    return token;
+  });
+  return head.join(' ');
+}
+
+// Extract failure events from one parsed ledger. A failure event is a receipt with
+// `success === false` on a verification-ish kind carrying a `command`, OR (when the
+// ledger declares `verificationFailed === true`) any receipt carrying a `command`.
+function failureCommands(ledger) {
+  if (!isObject(ledger) || !Array.isArray(ledger.receipts)) return [];
+  const out = [];
+  for (const receipt of ledger.receipts) {
+    if (!isObject(receipt) || typeof receipt.command !== 'string') continue;
+    const verifyFail = receipt.success === false && VERIFY_KINDS.has(receipt.kind);
+    const ledgerFlagged = ledger.verificationFailed === true && receipt.success === false;
+    if (verifyFail || ledgerFlagged) {
+      out.push({ command: receipt.command, file: receipt.file });
+    }
+  }
+  return out;
+}
+
+async function listLedgerFiles(dir, limit) {
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !isLedgerFilename(entry.name)) continue;
+    files.push(entry.name);
+  }
+  const withMtime = await Promise.all(files.map(async (name) => {
+    try {
+      const stat = await fs.stat(path.join(dir, name));
+      return { name, mtimeMs: stat.mtimeMs };
+    } catch {
+      return { name, mtimeMs: 0 };
+    }
+  }));
+  withMtime.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return withMtime.slice(0, limit).map((f) => f.name);
+}
+
+async function writeArtifact(filePath, result) {
+  const dir = path.dirname(filePath);
+  const tmp = path.join(dir, `.failure-patterns-${process.pid}.tmp`);
+  try {
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(tmp, JSON.stringify(result, null, 2));
+    await fs.rename(tmp, filePath);
+  } catch {
+    // Non-fatal: artifact is advisory; the computed result is still returned.
+    await fs.rm(tmp, { force: true }).catch(() => {});
+  }
+}
+
+/**
+ * Mine verification-failure patterns from exec-ledger receipts.
+ *
+ * @param {string} projectRoot repository root containing `.ukit/storage/cache/exec-ledger/`.
+ * @param {{ limitLedgers?: number, minCount?: number }} [options]
+ * @returns {Promise<{generatedAt: string, ledgersScanned: number,
+ *   ledgersWithFailures: number,
+ *   patterns: Array<{signature: string, count: number, sessions: number,
+ *     commands: string[], files: string[]}>}>} never throws.
+ */
+export async function mineFailurePatterns(projectRoot, { limitLedgers = 500, minCount = 2 } = {}) {
+  const result = {
+    generatedAt: new Date().toISOString(),
+    ledgersScanned: 0,
+    ledgersWithFailures: 0,
+    patterns: [],
+  };
+
+  try {
+    const dir = path.join(projectRoot, LEDGER_DIR_REL);
+    const names = await listLedgerFiles(dir, limitLedgers);
+    const groups = new Map();
+
+    for (const name of names) {
+      let ledger;
+      try {
+        ledger = JSON.parse(await fs.readFile(path.join(dir, name), 'utf8'));
+      } catch {
+        continue; // malformed/unreadable ledger — skip, never throw
+      }
+      result.ledgersScanned += 1;
+
+      const failures = failureCommands(ledger);
+      if (failures.length === 0) continue;
+      result.ledgersWithFailures += 1;
+      const sessionId = typeof ledger.sessionId === 'string' ? ledger.sessionId : null;
+
+      for (const { command, file } of failures) {
+        const signature = normalizeSignature(command);
+        if (!signature) continue;
+        let group = groups.get(signature);
+        if (!group) {
+          group = { signature, count: 0, sessions: new Set(), commands: [], files: [] };
+          groups.set(signature, group);
+        }
+        group.count += 1;
+        if (sessionId) group.sessions.add(sessionId);
+        if (group.commands.length < MAX_EXAMPLES && !group.commands.includes(command)) {
+          group.commands.push(command);
+        }
+        if (typeof file === 'string' && group.files.length < MAX_EXAMPLES && !group.files.includes(file)) {
+          group.files.push(file);
+        }
+      }
+    }
+
+    result.patterns = [...groups.values()]
+      .filter((g) => g.count >= minCount)
+      .sort((a, b) => b.count - a.count || a.signature.localeCompare(b.signature))
+      .slice(0, MAX_PATTERNS)
+      .map((g) => ({
+        signature: g.signature,
+        count: g.count,
+        sessions: g.sessions.size,
+        commands: g.commands,
+        files: g.files,
+      }));
+  } catch {
+    // Any unexpected failure → return whatever was computed so far.
+  }
+
+  await writeArtifact(path.join(projectRoot, ARTIFACT_REL), result);
+  return result;
+}

package/src/diagnostics/routeOutcomes.js

@@ -0,0 +1,146 @@
+// Route-outcome join (SPEC §4, SI-102): joins route-audit.json entries to
+// per-request exec-ledger ledgers on requestKey and aggregates outcome stats
+// per executionMode / taskType. Read-only; never throws.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const UNCLASSIFIED = '(unclassified)';
+const LEDGER_EXCLUDE = new Set(['gate-crash-counter.json']);
+
+function zeroedResult(extra = {}) {
+  return {
+    generatedAt: new Date().toISOString(),
+    ledgersScanned: 0,
+    auditRowsScanned: 0,
+    joined: 0,
+    unmatchedAudit: 0,
+    unmatchedLedger: 0,
+    byMode: {},
+    byTaskType: {},
+    joinCoverage: 0,
+    ...extra,
+  };
+}
+
+function emptyBucket() {
+  return {
+    routes: 0,
+    joined: 0,
+    writeOk: 0,
+    writeFail: 0,
+    verifyAttempted: 0,
+    verifyOk: 0,
+    verifyFail: 0,
+    rescue: 0,
+    stalled: 0,
+  };
+}
+
+async function listLedgerFiles(ledgerDir, limitLedgers) {
+  let dirents;
+  try {
+    dirents = await fs.readdir(ledgerDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const candidates = [];
+  for (const dirent of dirents) {
+    if (!dirent.isFile()) continue;
+    const name = dirent.name;
+    if (!name.endsWith('.json')) continue;
+    if (LEDGER_EXCLUDE.has(name)) continue;
+    if (name.includes('.journal') || name.includes('.quarantine')) continue;
+    candidates.push(name);
+  }
+  const withMtime = await Promise.all(candidates.map(async (name) => {
+    try {
+      const stat = await fs.stat(path.join(ledgerDir, name));
+      return { name, mtimeMs: stat.mtimeMs };
+    } catch {
+      return { name, mtimeMs: 0 };
+    }
+  }));
+  withMtime.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return withMtime.slice(0, Math.max(0, limitLedgers)).map((entry) => entry.name);
+}
+
+async function readJson(filePath) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function bump(bucket, ledger, auditEntry) {
+  bucket.joined += 1;
+  if (ledger.writeSucceeded === true) bucket.writeOk += 1;
+  else if (ledger.writeAttempted === true) bucket.writeFail += 1;
+  if (ledger.verificationAttempted === true) bucket.verifyAttempted += 1;
+  if (ledger.verificationSucceeded === true) bucket.verifyOk += 1;
+  if (ledger.verificationFailed === true) bucket.verifyFail += 1;
+  if (auditEntry.rescueMode != null) bucket.rescue += 1;
+  if ((auditEntry.repeatCount ?? 0) >= 2 && ledger.writeSucceeded !== true) {
+    bucket.stalled += 1;
+  }
+}
+
+export async function collectRouteOutcomes(projectRoot, { limitLedgers = 500 } = {}) {
+  try {
+    const cacheDir = path.join(projectRoot, '.ukit', 'storage', 'cache');
+    const auditDoc = await readJson(path.join(cacheDir, 'route-audit.json'));
+    const auditEntries = Array.isArray(auditDoc?.entries) ? auditDoc.entries : [];
+
+    const ledgerDir = path.join(cacheDir, 'exec-ledger');
+    const ledgerFiles = await listLedgerFiles(ledgerDir, limitLedgers);
+    const ledgers = [];
+    for (const name of ledgerFiles) {
+      const doc = await readJson(path.join(ledgerDir, name));
+      if (doc && typeof doc === 'object') ledgers.push(doc);
+    }
+
+    const result = zeroedResult();
+    result.ledgersScanned = ledgers.length;
+    result.auditRowsScanned = auditEntries.length;
+
+    const auditByKey = new Map();
+    for (const entry of auditEntries) {
+      if (entry && typeof entry.requestKey === 'string' && entry.requestKey) {
+        auditByKey.set(entry.requestKey, entry);
+      }
+    }
+    const ledgerKeys = new Set();
+    for (const ledger of ledgers) {
+      if (ledger && typeof ledger.requestKey === 'string' && ledger.requestKey) {
+        ledgerKeys.add(ledger.requestKey);
+      }
+    }
+
+    for (const entry of auditByKey.values()) {
+      const modeKey = entry.executionMode ?? UNCLASSIFIED;
+      const taskKey = entry.taskType ?? UNCLASSIFIED;
+      const modeBucket = result.byMode[modeKey] ??= emptyBucket();
+      const taskBucket = result.byTaskType[taskKey] ??= emptyBucket();
+      modeBucket.routes += 1;
+      taskBucket.routes += 1;
+      const ledger = ledgers.find((candidate) => candidate.requestKey === entry.requestKey);
+      if (!ledger) continue;
+      result.joined += 1;
+      bump(modeBucket, ledger, entry);
+      bump(taskBucket, ledger, entry);
+    }
+
+    result.unmatchedAudit = auditByKey.size - result.joined;
+    const matchedLedgerKeys = new Set(
+      ledgers
+        .filter((ledger) => auditByKey.has(ledger?.requestKey))
+        .map((ledger) => ledger.requestKey),
+    );
+    result.unmatchedLedger = ledgerKeys.size - matchedLedgerKeys.size;
+    result.joinCoverage = result.joined / Math.max(1, auditByKey.size);
+    return result;
+  } catch (error) {
+    return zeroedResult({ error: error?.message ?? String(error) });
+  }
+}

package/templates/.claude/hooks/block-dangerous.sh

@@ -52,9 +52,13 @@ else
     # path's ukit_emit_input_degraded.
     rm -f "$UKIT_INPUT_FILE"
     UKIT_INPUT_FILE=""
+    # TASK-223: same emit shape as ukit_emit_permission_decision — under a
+    # direct host the JSON only reaches the permission pipeline on exit 0; the
+    # omp chain needs exit 2 (marker exported by hook-chain-runner.mjs).
     printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"UKit could not fully read this tool-call payload (stdin staging was cut at the deadline/size bound), so dangerous-command gate cannot prove it safe. UKit defers this to a human decision."}}'
     echo "BLOCKED: dangerous-command gate could not inspect a truncated/stalled payload; deferred to human." >&2
-    exit 2
+    if [ -n "${UKIT_HOOK_CHAIN_RUNNER:-}" ]; then exit 2; fi
+    exit 0
   fi
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
 fi
@@ -115,15 +119,35 @@ DANGEROUS_PATTERNS=(
   "dd if=/dev/"
 )
 
-# Dangerous detections surface as a structured `ask` decision (stdout JSON) so a human
-# decides; exit 2 still refuses the call for harnesses that ignore structured output.
+# Dangerous detections surface as a structured decision (stdout JSON). TASK-223:
+# emission is centralized in ukit_emit_permission_decision — exit 0 on the direct
+# host (where a non-zero exit would discard the JSON as a bare "hook error"),
+# exit 2 inside the omp chain (whose bridge only parses stdout on code 2).
+# Probe verdict (2026-09-20, spec step 4): this repo runs
+# permissions.defaultMode=bypassPermissions, where an exit-0 `ask` auto-approves —
+# dead for refusals. So the direct host gets `deny` (a proper denied surface, still
+# fail-closed); the omp chain keeps `ask` (the host boundary prompts the human).
 # The raw command and the matched pattern are NEVER echoed — arguments and comments can
 # carry secrets, and the pattern text itself restates the dangerous command.
 emit_dangerous_decision() {
   REASON="$1"
-  printf '%s\n' "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"$REASON\"}}"
+  if command -v ukit_emit_permission_decision >/dev/null 2>&1; then
+    if [ -n "${UKIT_HOOK_CHAIN_RUNNER:-}" ]; then
+      ukit_emit_permission_decision ask "$REASON"
+    else
+      ukit_emit_permission_decision deny "$REASON"
+    fi
+  fi
+  # Helper unavailable (pre-install tree): keep the safe inline parity — the
+  # direct host gets deny + exit 0, the chain gets ask + exit 2.
+  if [ -n "${UKIT_HOOK_CHAIN_RUNNER:-}" ]; then
+    printf '%s\n' "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"$REASON\"}}"
+    echo "BLOCKED: $REASON" >&2
+    exit 2
+  fi
+  printf '%s\n' "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"$REASON\"}}"
   echo "BLOCKED: $REASON" >&2
-  exit 2
+  exit 0
 }
 
 for pattern in "${DANGEROUS_PATTERNS[@]}"; do

package/templates/.claude/hooks/context-hardcap-gate.sh

@@ -80,9 +80,12 @@ else
     # path's ukit_emit_input_degraded.
     rm -f "$UKIT_INPUT_FILE"
     UKIT_INPUT_FILE=""
+    # TASK-223: same emit shape as ukit_emit_permission_decision — exit 0 on the
+    # direct host (non-zero discards stdout there), exit 2 inside the omp chain.
     printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"UKit could not fully read this tool-call payload (stdin staging was cut at the deadline/size bound), so context hard-cap gate cannot prove it safe. UKit defers this to a human decision."}}'
     echo "BLOCKED: context hard-cap gate could not inspect a truncated/stalled payload; deferred to human." >&2
-    exit 2
+    if [ -n "${UKIT_HOOK_CHAIN_RUNNER:-}" ]; then exit 2; fi
+    exit 0
   fi
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
 fi

package/templates/.claude/hooks/protect-files.sh

@@ -52,9 +52,12 @@ else
     # path's ukit_emit_input_degraded.
     rm -f "$UKIT_INPUT_FILE"
     UKIT_INPUT_FILE=""
+    # TASK-223: same emit shape as ukit_emit_permission_decision — exit 0 on the
+    # direct host (non-zero discards stdout there), exit 2 inside the omp chain.
     printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"UKit could not fully read this tool-call payload (stdin staging was cut at the deadline/size bound), so protected-file gate cannot prove it safe. UKit defers this to a human decision."}}'
     echo "BLOCKED: protected-file gate could not inspect a truncated/stalled payload; deferred to human." >&2
-    exit 2
+    if [ -n "${UKIT_HOOK_CHAIN_RUNNER:-}" ]; then exit 2; fi
+    exit 0
   fi
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
 fi
@@ -112,9 +115,29 @@ if [ -n "$PROTECTED_MATCH" ]; then
   # A stderr-only refusal can look like a silent stall when the host does not render
   # hook stderr. Do not expose the path/pattern on stdout: the generic explanation is
   # enough for the user and avoids leaking a potentially sensitive filename.
-  printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"UKit protected-file guard blocked this edit. Ask the user to modify the protected file manually."}}'
+  # TASK-223: emit through the centralized helper — exit 0 on the direct host so the
+  # structured decision survives (non-zero discards stdout there), exit 2 in the omp
+  # chain whose bridge parses stdout only on code 2. Probe verdict (2026-09-20):
+  # under bypassPermissions an exit-0 `ask` auto-approves — dead for a protected-file
+  # refusal — so the direct host emits `deny`; the chain keeps `ask` for the human.
+  __ukit_protect_reason='UKit protected-file guard blocked this edit. Ask the user to modify the protected file manually.'
+  echo "BLOCKED: Cannot modify '$FILE_PATH' — matches protected pattern '$PROTECTED_MATCH'. Ask the user to modify this file manually." >&2
+  if command -v ukit_emit_permission_decision >/dev/null 2>&1; then
+    if [ -n "${UKIT_HOOK_CHAIN_RUNNER:-}" ]; then
+      ukit_emit_permission_decision ask "$__ukit_protect_reason"
+    else
+      ukit_emit_permission_decision deny "$__ukit_protect_reason"
+    fi
+  fi
+  # Helper unavailable (pre-install tree): same decision/exit matrix inline.
+  if [ -n "${UKIT_HOOK_CHAIN_RUNNER:-}" ]; then
+    printf '%s\n' "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"$__ukit_protect_reason\"}}"
+    echo "BLOCKED: Cannot modify '$FILE_PATH' — matches protected pattern '$PROTECTED_MATCH'. Ask the user to modify this file manually." >&2
+    exit 2
+  fi
+  printf '%s\n' "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"$__ukit_protect_reason\"}}"
   echo "BLOCKED: Cannot modify '$FILE_PATH' — matches protected pattern '$PROTECTED_MATCH'. Ask the user to modify this file manually." >&2
-  exit 2
+  exit 0
 fi
 
 exit 0

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

@@ -3872,6 +3872,13 @@ function getMemoryTimestamp(item) {
 
 function buildMemorySegments(item) {
   const content = item.content ?? {};
+  if (item.type === 'record') {
+    return [
+      { text: content.recordType, weight: 1 },
+      { text: content.text, weight: 3 },
+    ];
+  }
+
   if (item.type === 'project') {
     return [
       { text: content.name, weight: 2 },
@@ -3964,6 +3971,7 @@ async function listMemoryItems(rootDir) {
   const userMemory = (await readJson(path.join(runtimeRoot, 'user.json'), null)) ?? { preferences: {}, rules: [] };
   const projectMemories = await readDirectoryJsonItems(path.join(runtimeRoot, 'projects'));
   const sessionMemories = await readDirectoryJsonItems(path.join(runtimeRoot, 'sessions'));
+  const recordMemories = await listMemoryV2RecordItems(runtimeRoot);
 
   return [
     {
@@ -3981,11 +3989,47 @@ async function listMemoryItems(rootDir) {
       type: 'session',
       content: item.content,
     })),
+    ...recordMemories,
   ];
 }
 
+const MEMORY_V2_RECORD_POOL_LIMIT = 20;
+
+// v2 lane (SI-101): approved records live in a single records.json document.
+// Missing/malformed store → [] (same never-throw discipline as
+// readDirectoryJsonItems). Candidates: status 'active' AND (valid_until == null
+// OR valid_until > now), capped at 20 newest by created_at.
+async function listMemoryV2RecordItems(runtimeRoot) {
+  const doc = await readJson(path.join(runtimeRoot, 'v2', 'records.json'), null);
+  const records = Array.isArray(doc?.records) ? doc.records : [];
+  const now = Date.now();
+
+  return records
+    .filter((record) => record && typeof record === 'object')
+    .filter((record) => record.status === 'active')
+    .filter((record) => record.valid_until == null || record.valid_until > now)
+    .sort((left, right) => (right.created_at ?? 0) - (left.created_at ?? 0))
+    .slice(0, MEMORY_V2_RECORD_POOL_LIMIT)
+    .map((record) => ({
+      id: `record:${record.id}`,
+      type: 'record',
+      content: {
+        recordType: record.type,
+        text: record.text,
+        projectId: record.project_id,
+        updatedAt: record.created_at,
+      },
+    }));
+}
+
 function buildPreviousContextSnippet(item) {
   const content = item.content ?? {};
+  if (item.type === 'record') {
+    const text = String(content.text ?? '').trim();
+    const truncated = text.length > 120 ? `${text.slice(0, 117)}...` : text;
+    return `[${content.recordType ?? 'record'}] ${truncated}`;
+  }
+
   if (item.type === 'project') {
     const decisions = compactPhraseList((content.decisions ?? []).map((decision) => decision.what), { limit: 1 });
     const rules = compactPhraseList(content.activeRules ?? [], { limit: 1 });
@@ -4036,11 +4080,18 @@ async function buildPreviousContextSnapshot({ rootDir = process.cwd(), routingCo
   const queryTokens = tokenize(taskQuery);
   const rankedItems = items
     .filter((item) => item.type !== 'user')
-    .filter((item) => (
-      item.type === 'project'
-        ? (item.content?.id === projectId)
-        : (item.type === 'session' ? item.content?.projectId === projectId : true)
-    ))
+    .filter((item) => {
+      if (item.type === 'project') {
+        return item.content?.id === projectId;
+      }
+      if (item.type === 'session') {
+        return item.content?.projectId === projectId;
+      }
+      if (item.type === 'record') {
+        return item.content?.projectId == null || item.content?.projectId === projectId;
+      }
+      return true;
+    })
     .map((item) => ({
       item,
       score: scoreMemoryItem(item, queryTokens),
@@ -4060,7 +4111,7 @@ async function buildPreviousContextSnapshot({ rootDir = process.cwd(), routingCo
   return {
     line: rankedItems.map((item) => buildPreviousContextSnippet(item)).join(' | '),
     selectedIds: rankedItems.map((item) => item.id),
-    fingerprint: buildCompactMachineKey('route-memory-v1', {
+    fingerprint: buildCompactMachineKey('route-memory-v2', {
       taskQuery: normalize(taskQuery),
       projectId,
       items: rankedItems.map((item) => ({

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

@@ -102,7 +102,15 @@ async function run(payloadText, scriptPaths) {
       deadlineMs: Math.min(childBudgetMs, remainingMs),
       maxBuffer: MAX_BUFFER_BYTES,
       cwd: projectRoot,
-      env: { ...process.env, CLAUDE_PROJECT_DIR: projectRoot },
+      // TASK-223 (HK-401): mark chain-spawned children so their structured
+      // permission decisions keep the omp contract (stdout parsed on exit 2).
+      // Direct Claude Code invocations carry no marker and exit 0 instead —
+      // a non-zero exit there discards stdout, killing the decision JSON.
+      env: {
+        ...process.env,
+        CLAUDE_PROJECT_DIR: projectRoot,
+        UKIT_HOOK_CHAIN_RUNNER: '1',
+      },
     });
     const failureKind = chainFailureKind(result);
     const code = Number.isFinite(result.code) ? result.code : 1;

package/templates/.claude/ukit/runtime/hook-input.sh

@@ -135,12 +135,35 @@ ukit_input_degraded() {
   [ "${UKIT_INPUT_TRUNCATED:-0}" = "1" ] || [ "${UKIT_HOOK_INPUT_STALLED:-0}" = "1" ]
 }
 
+# TASK-223 (HK-401): ALL PreToolUse structured permission decisions emit through
+# this one helper. The JSON shape is harness-agnostic, but the exit code is NOT:
+#   direct Claude Code (UKIT_HOOK_CHAIN_RUNNER unset) — a non-zero exit means the
+#     harness DISCARDS stdout, so a decision JSON + exit 2 is dead text rendered
+#     as a bare "hook error" with no human-approval path. Emit the JSON and exit 0
+#     so `deny`/`ask` actually reaches the permission pipeline. Under
+#     permissions.defaultMode=bypassPermissions `ask` is auto-approved (probe
+#     verdict 2026-09-20), so refusal call sites pass `deny` directly — the host
+#     surfaces a proper "denied" instead of a hook error, still fail-closed.
+#   omp chain (UKIT_HOOK_CHAIN_RUNNER=1, exported by hook-chain-runner.mjs) — the
+#     bridge parses hookSpecificOutput ONLY when the child exits 2; exit 0
+#     short-circuits to {block:false} and would turn every gate fail-open. Emit
+#     the JSON and exit 2 exactly as before.
+# stderr still carries the BLOCKED line on every path — the model needs the
+# block reason regardless of which stdout contract the harness honors.
+ukit_emit_permission_decision() {
+  local decision="${1:-ask}" reason="${2:-UKit deferred this tool call to a human decision.}"
+  printf '%s\n' "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"${decision}\",\"permissionDecisionReason\":\"${reason}\"}}"
+  echo "BLOCKED: ${reason}" >&2
+  if [ -n "${UKIT_HOOK_CHAIN_RUNNER:-}" ]; then
+    exit 2
+  fi
+  exit 0
+}
+
 ukit_emit_input_degraded() {
   local posture="${1:-advisory}" hook_name="${2:-hook}"
   if [ "$posture" = "failclosed" ]; then
-    printf '%s\n' "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"UKit could not fully read this tool-call payload (stdin staging was cut at the deadline/size bound), so ${hook_name} cannot prove it safe. UKit defers this to a human decision.\"}}"
-    echo "BLOCKED: ${hook_name} could not inspect a truncated/stalled payload; deferred to human." >&2
-    exit 2
+    ukit_emit_permission_decision ask "UKit could not fully read this tool-call payload (stdin staging was cut at the deadline/size bound), so ${hook_name} cannot prove it safe. UKit defers this to a human decision."
   fi
   printf '%s\n' "{\"systemMessage\":\"UKit ${hook_name}: tool-call payload was truncated or stalled during stdin staging; skipped this pass rather than act on incomplete input.\"}"
   exit 0