@ngockhoale/ukit 3.0.3 → 3.0.5

package/template_project/.claude/ukit/index/verify-context.mjs

@@ -195,6 +195,17 @@ async function deriveVerificationPlan({
       reasons.push('highRiskFallback');
       commands.push(buildScriptCommand(packageManager, 'test'));
     }
+
+    // Non-empty floor (RULES.md test-selection §3): when nothing targeted and
+    // no fallback resolved, the plan must still route the broadest test
+    // script the project declares — an empty selection is never permitted.
+    if (commands.length === 0 && fallbackCommands.length === 0) {
+      const floorScript = scripts['test:release-core'] ? 'test:release-core' : (scripts.test ? 'test' : null);
+      if (floorScript) {
+        reasons.push('nonEmptyFloor');
+        fallbackCommands.push(buildScriptCommand(packageManager, floorScript));
+      }
+    }
   }
 
   if (commands.length === 0 && fallbackCommands.length === 0) {

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

@@ -8,13 +8,10 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { withAsyncLock, LOCK_MAX_SLICE_MS } from './async-lock.mjs';
 
-// Hook-context self-deadline (2.4.1 orphan-leak class): wrapper hooks pass
-// UKIT_HOOK_DEADLINE_MS so a wedged read can never orphan this process past the
-// hook budget. CLI usage never sets it and is never self-killed.
-const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10);
-if (Number.isFinite(HOOK_DEADLINE_MS) && HOOK_DEADLINE_MS > 0) {
-  setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
-}
+// Hook-context self-deadline (2.4.1 orphan-leak class): armed ONLY on direct
+// CLI invocation (see isDirectRun below) — never at import time. An import-time
+// process.exit timer races the importer's own §8-announcing deadline and exits
+// the host hook silently (BUG-C23-04 class regression).
 
 const LEDGER_VERSION = 1;
 const RESUME_INTENT_VERSION = 1;
@@ -973,7 +970,7 @@ const JOURNAL_VERSION = 1;
 const MAX_JOURNAL_SEEN = 64;
 const MAX_JOURNAL_RECORDS = 128;
 const MAX_JOURNAL_QUARANTINE_LINES = 32;
-const LEDGER_EVENT_TYPES = new Set(['receipt', 'continuation', 'notified', 'stop-progress']);
+const LEDGER_EVENT_TYPES = new Set(['receipt', 'continuation', 'notified', 'stop-progress', 'resumable-run']);
 const RECEIPT_KINDS = new Set(['source', 'write', 'verification']);
 
 function journalPathFor(target) {
@@ -1090,6 +1087,28 @@ function sanitizeReceiptForJournal(receipt) {
   return clean;
 }
 
+// TASK-007 (M04.1, FR-015): the resumable-run event carries a bounded pointer to
+// the C10 record — never the record itself (it lives under .ukit/storage/runs/).
+// Whitelisted fields only, each coerced to a bounded string/number so a journal
+// record can never carry prompt text or unbounded payloads.
+const JOURNAL_RUN_FIELDS = ['taskId', 'taskBoundary', 'stage', 'status', 'updatedAt'];
+const JOURNAL_RUN_FIELD_MAX = 160;
+
+function sanitizeRunForJournal(run) {
+  if (!run || typeof run !== 'object' || Array.isArray(run)) return null;
+  const clean = {};
+  for (const key of JOURNAL_RUN_FIELDS) {
+    const value = run[key];
+    if (value === undefined || value === null || value === '') continue;
+    if (typeof value === 'number') {
+      if (Number.isFinite(value)) clean[key] = value;
+      continue;
+    }
+    clean[key] = String(value).slice(0, JOURNAL_RUN_FIELD_MAX);
+  }
+  return typeof clean.taskId === 'string' && clean.taskId ? clean : null;
+}
+
 function buildJournalRecord({ event, eventId, payload, routeState }) {
   return {
     v: JOURNAL_VERSION,
@@ -1102,7 +1121,9 @@ function buildJournalRecord({ event, eventId, payload, routeState }) {
     type: event.type,
     event: event.type === 'receipt'
       ? { receipt: sanitizeReceiptForJournal(event.receipt), vibecode: event.vibecode === true }
-      : { ...event, type: undefined },
+      : event.type === 'resumable-run'
+        ? { run: sanitizeRunForJournal(event.run) }
+        : { ...event, type: undefined },
   };
 }
 
@@ -1160,6 +1181,12 @@ function parseJournalRecord(line, expectedSessionKey) {
     const receipt = record.event.receipt;
     if (!receipt || typeof receipt !== 'object' || !RECEIPT_KINDS.has(receipt.kind)) return null;
   }
+  if (record.type === 'resumable-run') {
+    const run = record.event.run;
+    if (!run || typeof run !== 'object' || typeof run.taskId !== 'string' || !run.taskId) {
+      return null;
+    }
+  }
   return record;
 }
 
@@ -1195,6 +1222,9 @@ function applyJournalRecord(ledger, record) {
   if (record.type === 'notified') {
     return { ledger: { ...ledger, notified: true, updatedAt: Date.now() }, value: null };
   }
+  if (record.type === 'resumable-run') {
+    return { ledger: applyResumableRunToLedger(ledger, record.event?.run), value: null };
+  }
   if (record.type === 'stop-progress') {
     return applyStopProgressToLedger(ledger);
   }
@@ -1424,6 +1454,25 @@ function applyStopProgressToLedger(ledger) {
   };
 }
 
+// TASK-007 (FR-015): the resumable-run event lands as a bounded pointer on the
+// ledger — newest updatedAt wins so a journaled replay can never resurrect a
+// superseded record pointer.
+function applyResumableRunToLedger(ledger, run) {
+  if (!run || typeof run !== 'object' || typeof run.taskId !== 'string' || !run.taskId) {
+    return ledger;
+  }
+  const incomingAt = Number.isFinite(run.updatedAt) ? run.updatedAt : Date.now();
+  const currentAt = Number.isFinite(ledger?.resumableRun?.updatedAt)
+    ? ledger.resumableRun.updatedAt
+    : -Infinity;
+  if (incomingAt < currentAt) return ledger;
+  return {
+    ...ledger,
+    resumableRun: { ...run, updatedAt: incomingAt },
+    updatedAt: Date.now(),
+  };
+}
+
 function liveBaseLedger(event, current, payload, routeState, harness, fallbackLedger) {
   if (event.type === 'receipt') {
     // A missing/foreign route state must never blank the evidence this session already
@@ -1481,6 +1530,8 @@ export async function recordLedgerEvent(event, {
       ledger = applyContinuationToLedger(ledger, event);
     } else if (event.type === 'notified') {
       ledger = { ...ledger, notified: true, updatedAt: Date.now() };
+    } else if (event.type === 'resumable-run') {
+      ledger = applyResumableRunToLedger(ledger, event.run);
     } else if (event.type === 'stop-progress') {
       if (!current && drained.applied === 0) {
         // A stop with no ledger at all creates nothing (historic noteStopProgress shape).
@@ -2175,6 +2226,57 @@ export async function appendDecision(projectRoot, {
   }
 }
 
+// --- M07 decision-plane receipts (TASK-005, SPEC §5 FR-008/FR-011) -----------
+// Typed wrapper over appendDecision for shadow/applied/fallback decision
+// receipts. The receipt contract is codes and bands only — never prompts,
+// state text, raw probabilities, or secrets — so every cell is coerced to a
+// bounded code string before it reaches the TSV. `kind` is the receipt class:
+// 'shadow' (advisory run, deterministic policy stayed authoritative),
+// 'applied' (canary/default accepted answer), 'fallback' (adapter failed and
+// the deterministic baseline stayed in force).
+const DECISION_RECEIPT_KINDS = new Set(['shadow', 'applied', 'fallback']);
+const DECISION_RECEIPT_CELL_MAX = 160;
+
+function receiptCell(value) {
+  return String(value ?? 'none')
+    .replace(/[\t\n\r]+/g, ' ')
+    .trim()
+    .slice(0, DECISION_RECEIPT_CELL_MAX) || 'none';
+}
+
+export async function appendDecisionReceipt(projectRoot, {
+  kind = 'shadow',
+  boundary = '',
+  stage = '',
+  outcomeClass = '',
+  checkpoint = null,
+  latencyClass = 'unknown',
+  decisionKeys = [],
+  agreement = 'unknown',
+  fallbackCode = null,
+  now = Date.now(),
+} = {}) {
+  if (!DECISION_RECEIPT_KINDS.has(kind)) {
+    return { appended: false, reason: 'invalid-receipt-kind' };
+  }
+  const keys = (Array.isArray(decisionKeys) ? decisionKeys : [])
+    .map((k) => receiptCell(k))
+    .join(',');
+  return appendDecision(projectRoot, {
+    phase: 'decision-plane',
+    decision: `${receiptCell(boundary || 'unknown')}-${kind}`,
+    why: `stage=${receiptCell(stage)}`,
+    evidence: [
+      receiptCell(checkpoint ?? 'no-checkpoint'),
+      receiptCell(latencyClass),
+      `keys=${keys || 'none'}`,
+    ].join(' '),
+    result: `${receiptCell(outcomeClass)} agree=${receiptCell(agreement)}`
+      + (fallbackCode ? ` fallback=${receiptCell(fallbackCode)}` : ''),
+    now,
+  });
+}
+
 function isDirectRun() {
   const argvPath = process.argv[1];
   if (!argvPath) return false;
@@ -2194,6 +2296,11 @@ function isDirectRun() {
 }
 
 if (isDirectRun()) {
+  // Self-deadline for direct hook/CLI invocation only (see note at top).
+  const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10);
+  if (Number.isFinite(HOOK_DEADLINE_MS) && HOOK_DEADLINE_MS > 0) {
+    setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
+  }
   main().catch((error) => {
     process.stderr.write(`[ukit-execution-ledger] ${error?.message || error}\n`);
     process.exitCode = 1;

package/template_project/.claude/ukit/runtime/project-important.mjs

@@ -35,13 +35,10 @@ import {
   loadSensitiveAllowlist,
 } from './sensitive-value-scanner.mjs';
 
-// Hook-context self-deadline (2.4.1 orphan-leak class): a hook wrapper passes
-// UKIT_HOOK_DEADLINE_MS so a wedged read can never orphan this process past
-// the hook budget. CLI usage never sets it and is never self-killed.
-const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10);
-if (Number.isFinite(HOOK_DEADLINE_MS) && HOOK_DEADLINE_MS > 0) {
-  setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
-}
+// Hook-context self-deadline (2.4.1 orphan-leak class): armed ONLY on direct
+// CLI invocation (see the argv[1] guard at the bottom) — never at import time.
+// An import-time process.exit timer races the importer's own §8-announcing
+// deadline and exits the host hook silently (BUG-C23-04 class).
 
 export const PROJECT_IMPORTANT_FILENAME = 'PROJECT_IMPORTANT.md';
 export const PROJECT_IMPORTANT_CODEPOINT_LIMIT = 6000;
@@ -372,6 +369,11 @@ if (
   process.argv[1]
   && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)
 ) {
+  // Self-deadline for direct hook invocation only (see note at top).
+  const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10);
+  if (Number.isFinite(HOOK_DEADLINE_MS) && HOOK_DEADLINE_MS > 0) {
+    setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
+  }
   try {
     const projectRoot = process.env.UKIT_PROJECT_ROOT
       || process.env.CLAUDE_PROJECT_DIR

package/template_project/.claude/ukit/runtime/reinject-context.mjs

@@ -20,6 +20,10 @@ import {
   writeCompactPressureState,
   writeThresholdCompactPlan,
 } from './compact-threshold.mjs';
+import {
+  readResumableRun,
+  resumableRunSourceFingerprint,
+} from './resumable-run.mjs';
 
 // Hook-context self-deadline (2.4.1 orphan-leak class): the reinject-context hook passes
 // UKIT_HOOK_DEADLINE_MS so a wedged read can never orphan this process past the hook
@@ -66,6 +70,46 @@ const INLINE_SUMMARY_TAIL_PATTERNS = [
   /\b(Duration|Start at)\b/i,
 ];
 
+
+// TASK-007 (M04.1, FR-015): on compaction resume, consume the SAME C10 record
+// route-task persisted (no second format, no master-doc reread). The shared
+// route state carries the bounded pointer (routeSummary.resumableRun); the
+// record under .ukit/storage/runs/ supplies phase/nextAction/hypotheses.
+// Stage 'off' (or absent/malformed) → no read at all. A stale record still
+// reinjects its surviving sections — the invalidation already dropped the
+// dependent plans. Never throws: resume is advisory.
+async function buildResumableRunLines(projectRoot, state, config) {
+  try {
+    const stage = config?.continuity?.resumableRun?.stage;
+    if (typeof stage !== 'string' || stage === 'off') return [];
+    const pointer = state?.routeSummary?.resumableRun;
+    if (!pointer || typeof pointer.taskId !== 'string' || !pointer.taskId) return [];
+    const sourceFingerprint = await resumableRunSourceFingerprint(projectRoot);
+    const resumed = await readResumableRun(projectRoot, {
+      taskId: pointer.taskId,
+      taskBoundary: typeof pointer.taskBoundary === 'string' ? pointer.taskBoundary : undefined,
+      sourceFingerprint,
+    });
+    if (resumed.status === 'absent' || resumed.status === 'invalid') return [];
+    const record = resumed.record;
+    if (!record) return [];
+    const lines = [];
+    if (resumed.status === 'stale') {
+      lines.push('- Resumed run: stale — source/index changed since persist; dependent plans were invalidated, completed receipts kept.');
+    }
+    const phase = String(record.workflow?.phase ?? '').trim();
+    if (phase) lines.push(`- Resumed run phase: ${phase}`);
+    const nextAction = typeof record.nextAction === 'string' ? record.nextAction.trim() : '';
+    if (nextAction) lines.push(`- Resumed next action: ${nextAction}`);
+    for (const hypothesis of (Array.isArray(record.hypotheses) ? record.hypotheses : []).slice(0, 3)) {
+      const text = String(hypothesis ?? '').trim();
+      if (text) lines.push(`- Resumed hypothesis: ${text}`);
+    }
+    return lines;
+  } catch {
+    return [];
+  }
+}
 async function main() {
   const projectRoot = process.env.CLAUDE_PROJECT_DIR && path.isAbsolute(process.env.CLAUDE_PROJECT_DIR)
     ? process.env.CLAUDE_PROJECT_DIR
@@ -109,6 +153,7 @@ async function main() {
     ...await buildPreviousContextLines(projectRoot, state, config),
     ...await buildRecentOutputLines(projectRoot, config),
     ...await buildResolverHintLines(projectRoot, state),
+    ...await buildResumableRunLines(projectRoot, state, config),
     ...await buildDuraOneHintLines(projectRoot),
     // Post-compact discipline: the host summary keeps whatever it kept — the fastest way to
     // re-inflate a just-compacted session is re-reading old files/logs to "recover" detail
@@ -141,6 +186,9 @@ async function main() {
     || line.startsWith('- Decision rule:')
     || line.startsWith('- Previous context:')
     || line.startsWith('- Recent command output:')
+    || line.startsWith('- Resumed run')
+    || line.startsWith('- Resumed next action:')
+    || line.startsWith('- Resumed hypothesis:')
     || line.startsWith('- Recent delegation hint:')
   ));
   const maxTokens = Math.max(160, Math.min(640, Number(config.memory?.maxInjectionTokens) || 320));