@ngockhoale/ukit 3.4.32 → 3.4.34

package/template_project/.claude/ukit/runtime/context-budget-policy.mjs

@@ -0,0 +1,309 @@
+// Context budget + adaptive decomposition policy — PURE decision functions, no fs,
+// no LLM call. Advisory only: nothing here truncates context or blocks a tool call.
+//
+// Soft budgets are planning targets per role. The 100K figure is a COST BOUNDARY
+// that only applies when pricing metadata says the model has a tier above it;
+// with no metadata the boundary is `unknown` and is never assumed to be a cliff.
+import crypto from 'node:crypto';
+import { estimateTokenCount } from './token-utils.mjs';
+
+export const COST_BOUNDARY_TOKENS = 100_000;
+
+export const ROLE_SOFT_BUDGETS = Object.freeze({
+  'simple-subagent': 40_000,
+  subagent: 60_000,
+  'implement-subagent': 80_000,
+  'review-subagent': 80_000,
+  orchestrator: 90_000,
+});
+
+export const DECOMPOSITION_LIMITS = Object.freeze({ maxDepth: 2, maxAttempts: 2, minSavingsRatio: 0.15 });
+
+const num = (v) => (Number.isFinite(v) && v >= 0 ? v : null);
+
+/**
+ * Uncached (fresh) vs cached input are separate: cache reads are not counted
+ * against the boundary's fresh-input pressure, but the prompt window still is.
+ */
+export function summarizeUsage({ inputTokens = 0, cacheReadTokens = 0, cacheWriteTokens = 0 } = {}) {
+  const input = num(inputTokens) ?? 0;
+  const read = num(cacheReadTokens) ?? 0;
+  const write = num(cacheWriteTokens) ?? 0;
+  return { promptTokens: input + read + write, uncachedTokens: input + write, cachedTokens: read };
+}
+
+/** Soft-budget status for a role. Never a hard limit. */
+export function evaluateContextBudget({ role = 'orchestrator', promptTokens, pricing = null } = {}) {
+  const tokens = num(promptTokens);
+  const softBudget = ROLE_SOFT_BUDGETS[role] ?? ROLE_SOFT_BUDGETS.subagent;
+  if (tokens === null) return { status: 'unknown', softBudget, boundary: 'unknown', hardLimit: false };
+  const cliff = num(pricing?.longContextThresholdTokens);
+  const boundary = cliff === null ? 'unknown' : cliff;
+  const overBoundary = cliff !== null && tokens > cliff;
+  let status = 'ok';
+  if (overBoundary) status = 'over-cost-boundary';
+  else if (tokens > softBudget) status = 'over-soft-budget';
+  else if (tokens > softBudget * 0.8) status = 'near-soft-budget';
+  return { status, softBudget, boundary, overBoundary, hardLimit: false };
+}
+
+function fingerprintOf(parentId, subtasks) {
+  const body = subtasks.map((s) => [s.id, [...(s.files ?? [])].sort(), [...(s.deps ?? [])].sort()]);
+  return crypto.createHash('sha256').update(JSON.stringify([parentId, body])).digest('hex').slice(0, 16);
+}
+
+/**
+ * Decide whether an at-risk task should be split. Inputs are plain data from the
+ * existing plan/ledger; `state` carries {depth, attempts, seenFingerprints}.
+ * Returns {decompose, reason, fingerprint?, costs?}; fallback is always the orchestrator.
+ */
+export function shouldDecompose({
+  parentId = 'task',
+  estimatedTokens,
+  pricing = null,
+  subtasks = [],
+  coupled = false,
+  overheadPerSubtask = 4_000,
+  integrationTokens = 6_000,
+  reworkRisk = 0.1,
+  state = {},
+} = {}) {
+  const limits = DECOMPOSITION_LIMITS;
+  const est = num(estimatedTokens);
+  if (est === null) return { decompose: false, reason: 'unknown-size' };
+  const cliff = num(pricing?.longContextThresholdTokens) ?? COST_BOUNDARY_TOKENS;
+  if (est <= cliff) return { decompose: false, reason: 'within-boundary' };
+  if ((state.depth ?? 0) >= limits.maxDepth) return { decompose: false, reason: 'depth-limit' };
+  if ((state.attempts ?? 0) >= limits.maxAttempts) return { decompose: false, reason: 'attempt-limit' };
+  if (coupled) return { decompose: false, reason: 'tightly-coupled' };
+  if (!Array.isArray(subtasks) || subtasks.length < 2) return { decompose: false, reason: 'no-clear-boundaries' };
+  if (subtasks.some((s) => !s?.id || num(s.scopeTokens) === null)) {
+    return { decompose: false, reason: 'incomplete-subtasks' };
+  }
+  const fingerprint = fingerprintOf(parentId, subtasks);
+  if ((state.seenFingerprints ?? []).includes(fingerprint)) {
+    return { decompose: false, reason: 'unchanged-decomposition', fingerprint };
+  }
+  const biggest = Math.max(...subtasks.map((s) => s.scopeTokens));
+  if (biggest > cliff) return { decompose: false, reason: 'subtask-still-over-boundary', fingerprint };
+  const decomposed =
+    subtasks.reduce((sum, s) => sum + s.scopeTokens + overheadPerSubtask, 0) + integrationTokens;
+  // A request above the boundary may bill the WHOLE prompt at the higher tier; the
+  // premium is a planning weight (pricing.longContextPremium, default 1.5), not a price.
+  const premium = num(pricing?.longContextPremium) ?? 1.5;
+  const original = est * premium;
+  const decomposedCost = decomposed * (1 + reworkRisk);
+  const savings = (original - decomposedCost) / original;
+  const costs = { original, decomposed: decomposedCost, savingsRatio: Number(savings.toFixed(3)) };
+  if (savings < limits.minSavingsRatio) return { decompose: false, reason: 'not-cost-effective', fingerprint, costs };
+  return { decompose: true, reason: 'cost-effective-split', fingerprint, costs };
+}
+
+/** Estimate a context's tokens with the shared estimator (no LLM, no tokenizer). */
+export function estimateContextTokens(parts = []) {
+  return parts.reduce((sum, p) => sum + estimateTokenCount(p), 0);
+}
+
+const HANDOFF_TOKENS = 6_000;
+const MAX_SUBTASKS = 4;
+
+/**
+ * Turn the route's resolved targets into a task graph and run shouldDecompose on it.
+ * Pure: file sizes arrive as `fileTokens` ({path: tokens}); no fs, no LLM. The result
+ * is bounded plain data for the resumable-run record. Parent acceptance criteria are
+ * kept whole on the plan and checked in full by the integration step; each subtask
+ * only receives the criteria that concern its own files/tests (see splitAcceptance), so
+ * splitting can never drop a requirement nor bloat every handoff. Fallback is always "main orchestrator continues".
+ */
+export function buildDecompositionPlan({
+  parentId = 'task',
+  goal = '',
+  contextTokens,
+  primaryTargets = [],
+  relatedTests = [],
+  fileTokens = {},
+  acceptance = [],
+  coupled = false,
+  pricing = null,
+  previous = null,
+} = {}) {
+  const state = {
+    depth: previous?.depth ?? 0,
+    attempts: previous?.attempts ?? 0,
+    seenFingerprints: previous?.seenFingerprints ?? [],
+  };
+  const groups = new Map();
+  for (const file of primaryTargets) {
+    const parts = String(file).split('/');
+    const key = parts.length > 2 ? parts.slice(0, 2).join('/') : parts.length > 1 ? parts[0] : '.';
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(file);
+  }
+  const subtasks = [...groups.entries()].slice(0, MAX_SUBTASKS).map(([key, files], i) => {
+    const tests = relatedTests.filter((t) => files.some((f) => t.includes(String(f).split('/').pop().replace(/\.[^.]+$/, ''))));
+    const scopeTokens = [...files, ...tests].reduce((s, f) => s + (num(fileTokens[f]) ?? 2_000), 0) + HANDOFF_TOKENS;
+    return { id: `${parentId}.${i + 1}`, key, files, tests, deps: [], scopeTokens };
+  });
+  const decision = shouldDecompose({
+    parentId, estimatedTokens: contextTokens, pricing, subtasks, coupled, state,
+  });
+  if (!decision.decompose) {
+    return { decompose: false, reason: decision.reason, fingerprint: decision.fingerprint ?? null, estimatedTokens: num(contextTokens), depth: state.depth, attempts: state.attempts, seenFingerprints: state.seenFingerprints };
+  }
+  const accept = acceptance.slice(0, 8).map((a) => String(a).slice(0, 200));
+  const split = splitAcceptance(accept, subtasks);
+  const tasks = subtasks.map((s, i) => ({
+    id: s.id,
+    goal: `${String(goal).slice(0, 200)} [scope: ${s.key}]`.slice(0, 400),
+    files: s.files.slice(0, 12),
+    tests: s.tests.slice(0, 6),
+    deps: s.deps,
+    scopeTokens: s.scopeTokens,
+    acceptance: split.perTask[i],
+    handoff: `Scoped context only (${s.files.length} file(s)); return changed files + verification result, not history.`,
+  }));
+  tasks.push({
+    id: `${parentId}.integrate`,
+    goal: 'Integrate subtask results and run parent verification',
+    files: [],
+    tests: [],
+    deps: tasks.map((t) => t.id),
+    scopeTokens: HANDOFF_TOKENS,
+    acceptance: accept, // integration verifies EVERY parent criterion
+    handoff: 'Main orchestrator merges handoffs and verifies parent acceptance.',
+  });
+  return {
+    decompose: true,
+    reason: decision.reason,
+    fingerprint: decision.fingerprint,
+    estimatedTokens: num(contextTokens),
+    costs: decision.costs,
+    depth: state.depth + 1,
+    attempts: state.attempts + 1,
+    seenFingerprints: [...state.seenFingerprints, decision.fingerprint].slice(-4),
+    parentAcceptance: accept,
+    tasks,
+  };
+}
+
+const basenameOf = (f) => String(f).split('/').pop().replace(/\.[^.]+$/, '').toLowerCase();
+
+/**
+ * Distribute parent criteria: a criterion that names a subtask's file/dir (or its
+ * basename) goes to that subtask; test-ish criteria go to subtasks that own tests;
+ * `shared:`/`contract:` criteria go to every subtask (shared contract); anything else
+ * is parent-level and only checked at integration. Nothing is lost: integration holds all.
+ */
+export function splitAcceptance(accept, subtasks) {
+  const perTask = subtasks.map(() => []);
+  for (const c of accept) {
+    const lc = c.toLowerCase();
+    const shared = /^(shared|contract):/.test(lc);
+    subtasks.forEach((s, i) => {
+      const names = [s.key, ...s.files, ...s.files.map(basenameOf)].map((n) => String(n).toLowerCase()).filter((n) => n.length > 2 && n !== '.');
+      const direct = names.some((n) => lc.includes(n));
+      const testy = /\btests?\b/.test(lc) && s.tests.length > 0;
+      if (shared || direct || testy) perTask[i].push(c);
+    });
+  }
+  return { perTask };
+}
+
+// ---- task-graph execution (pure) -------------------------------------------------
+// Progress lives on the stored decomposition entry as `done`/`running` id arrays so the
+// existing resumable-run record carries it across resume. Bounded: <= 5 ids each.
+
+export const SUBTASK_MARKER_RE = /\[ukit-subtask\s+([A-Za-z0-9_-]+\.(?:\d+|integrate))\]/;
+
+export function planProgress(plan) {
+  return { done: new Set(plan?.done ?? []), running: new Set(plan?.running ?? []) };
+}
+
+/** Tasks whose deps are all done and that are neither done nor running. */
+export function nextDispatchable(plan) {
+  if (!plan?.decompose) return [];
+  const { done, running } = planProgress(plan);
+  return plan.tasks.filter((t) => !done.has(t.id) && !running.has(t.id) && t.deps.every((d) => done.has(d)));
+}
+
+/** Gate for dispatching one task id. */
+export function checkDispatch(plan, taskId) {
+  const task = plan?.tasks?.find((t) => t.id === taskId);
+  if (!task) return { ok: false, reason: 'unknown-subtask' };
+  const { done, running } = planProgress(plan);
+  if (done.has(taskId)) return { ok: false, reason: 'already-done' };
+  if (running.has(taskId)) return { ok: false, reason: 'already-running' };
+  const missing = task.deps.filter((d) => !done.has(d));
+  if (missing.length) return { ok: false, reason: 'deps-pending', missing };
+  return { ok: true, task };
+}
+
+/** Pure status transition: 'running' | 'done' | 'pending' (failed → retryable). */
+export function applySubtaskStatus(plan, taskId, status) {
+  const { done, running } = planProgress(plan);
+  running.delete(taskId);
+  if (status === 'done') done.add(taskId);
+  if (status === 'running') running.add(taskId);
+  return { ...plan, done: [...done], running: [...running] };
+}
+
+/** Carry finished work over a replan when the subtask is unchanged. */
+export function carryProgress(oldPlan, newPlan) {
+  if (!oldPlan?.decompose || !newPlan?.decompose) return newPlan;
+  const same = (a) => {
+    const b = oldPlan.tasks.find((t) => t.id === a.id);
+    return b && JSON.stringify(b.files) === JSON.stringify(a.files);
+  };
+  const done = (oldPlan.done ?? []).filter((id) => newPlan.tasks.some((t) => t.id === id && same(t)));
+  return { ...newPlan, done };
+}
+
+/** The scoped dispatch text for one subtask: its own files/criteria only, no parent history. */
+export function buildSubtaskPrompt(task) {
+  return [
+    `[ukit-subtask ${task.id}]`,
+    `Goal: ${task.goal}`,
+    task.files.length ? `Files: ${task.files.join(', ')}` : null,
+    task.tests.length ? `Tests: ${task.tests.join(', ')}` : null,
+    task.acceptance.length ? `Acceptance: ${task.acceptance.join(' | ')}` : null,
+    task.handoff,
+  ].filter(Boolean).join('\n');
+}
+
+// ---- layered context-size estimate -------------------------------------------------
+// Priority: (1) actual provider usage on the newest main-chain assistant turn (Claude Code
+// `message.usage`, OMP `usage`/`message.usage`) = prompt of that request, confidence HIGH;
+// (2) a caller-supplied window metric (MEDIUM); (3) transcript bytes/4 = UNRELIABLE upper
+// bound (LOW: JSON/tool-output overhead inflates it). LOW never triggers an automatic split.
+
+function promptFromUsage(u) {
+  if (!u || typeof u !== 'object') return null;
+  const input = num(u.input_tokens ?? u.input) ?? 0;
+  const read = num(u.cache_read_input_tokens ?? u.cacheRead) ?? 0;
+  const write = num(u.cache_creation_input_tokens ?? u.cacheWrite) ?? 0;
+  const total = input + read + write;
+  return total > 0 ? total : null;
+}
+
+export function contextFromUsageLines(lines = []) {
+  for (let i = lines.length - 1; i >= 0; i--) {
+    let row;
+    try { row = JSON.parse(lines[i]); } catch { continue; }
+    if (!row || typeof row !== 'object' || row.isSidechain === true) continue;
+    const tokens = promptFromUsage(row.message?.usage ?? row.usage);
+    if (tokens !== null) return tokens;
+  }
+  return null;
+}
+
+export function estimateContextWindow({ tailLines = [], windowTokens = null, transcriptBytes = null } = {}) {
+  const used = contextFromUsageLines(tailLines);
+  if (used !== null) return { tokens: used, source: 'provider-usage', confidence: 'high' };
+  const win = num(windowTokens);
+  if (win !== null && win > 0) return { tokens: win, source: 'window-metric', confidence: 'medium' };
+  const bytes = num(transcriptBytes);
+  if (bytes !== null) return { tokens: Math.ceil(bytes / 4), source: 'transcript-bytes', confidence: 'low' };
+  return { tokens: null, source: 'unknown', confidence: 'unknown' };
+}
+
+export const MIN_AUTO_SPLIT_CONFIDENCE = new Set(['high', 'medium']);

package/template_project/.claude/ukit/runtime/cron-operation-adapter.mjs

@@ -41,3 +41,70 @@ export function cronOperationReceipt(toolName, input, response, transportSuccess
     transportSuccess: transportSuccess === true, harness,
     operation: { domain: capability.domain, role: capability.role, scope, ...state } };
 }
+
+// R2/R3: non-source operations (git integrity, service restart + HTTP check). A Bash command is
+// proof only when it IS the checked command (not text inside echo/quotes) and its exit status
+// is the command's own: no pipe without pipefail, no `;`/newline/`||` chain that can mask it.
+// The goal names WHAT was ordered (verbs, services, probe path/status): a receipt for another
+// verb, service, repo or endpoint never discharges it, and a dry run is not the operation.
+const GIT_MUTATION = /^git\s+(?:push|commit|clean|reset|merge|rebase|stash|tag|checkout|restore|pull|cherry-pick|branch)\b/;
+const GIT_VERB = /^git\s+(push|commit|clean|reset|merge|rebase|stash|tag|checkout|restore|pull|cherry-pick|branch)\b/;
+const GIT_STATE = /^git\s+(?:fsck\b|diff\s+(?:--check|--exit-code|--quiet)\b|status\s+(?:--porcelain|-s|--short)\b)/;
+const SERVICE_MUTATION = /^(?:docker(?:\s+compose)?|docker-compose)\s+(?:restart|up|down|stop|start|build)\b|^(?:sudo\s+)?systemctl\s+(?:restart|start|stop|reload)\b|^pm2\s+(?:restart|reload|start)\b|^kubectl\s+(?:rollout|apply)\b|^launchctl\s+kickstart\b|^(?:\.\/)?(?:scripts\/)?deploy[\w.-]*(?:\s|$)|^(?:npm|yarn|pnpm)\s+(?:run\s+)?deploy\b/;
+const DRY_RUN = /(?:^|\s)(?:--dry-run|--check|--no-act|-n)(?:\s|=|$)/;
+const CURL = /^curl\s/;
+function requiredTargetOf(segment, required) {
+  if (!required.length) return null;
+  const tokens = segment.split(/\s+/);
+  return required.find((name) => tokens.some((tok) => tok === name || tok.endsWith(`/${name}`))) || '(other)';
+}
+export function bashOperationReceipt(command, response, transportSuccess, goal, { sessionId, harness } = {}) {
+  const domain = goal?.domain;
+  const scope = typeof sessionId === 'string' && sessionId.trim() ? `session:${sessionId.trim()}` : null;
+  if (!['git-integrity', 'service-runtime'].includes(domain) || typeof command !== 'string') return null;
+  const required = Array.isArray(goal.requiredTargets) ? goal.requiredTargets : [];
+  const bare = command.replace(/'[^']*'|"[^"]*"/g, '""');
+  const masked = /;|\n|\|\|/.test(bare) || (/\|/.test(bare) && !/\bpipefail\b/.test(command));
+  const real = command.split('&&').map((seg) => seg.trim());
+  const text = responseText(response);
+  const hasOutputField = typeof response === 'string' || typeof response?.stdout === 'string' || typeof response?.output === 'string';
+  let role = null; let proven = false; let target = null;
+  for (const seg of real) {
+    if (!seg || /^cd\s+\S+$/.test(seg) || DRY_RUN.test(seg.replace(/'[^']*'|"[^"]*"/g, '""'))) continue;
+    if (domain === 'git-integrity') {
+      if (GIT_STATE.test(seg)) {
+        const wanted = goal.check;
+        const kind = /\bfsck\b/.test(seg) ? 'fsck' : /\bdiff\b/.test(seg) ? 'diff-check' : 'status';
+        // `-- <pathspec>` / extra paths narrow the check; only a whole-tree status proves a clean tree.
+        const wholeTree = kind !== 'status' || !/\s--\s|\s--porcelain=\S*\s+\S|(?:--porcelain|-s|--short)\s+[^\s-]/.test(seg);
+        if (!wholeTree || (wanted && kind !== wanted)) continue;
+        role = 'state';
+        proven = kind === 'status' ? hasOutputField && text === '' : true;
+      } else if (GIT_VERB.test(seg) && role !== 'state') {
+        role = 'mutation';
+        target = seg.match(GIT_VERB)[1];
+      }
+    } else if (SERVICE_MUTATION.test(seg) && role !== 'state') {
+      role = 'mutation';
+      target = requiredTargetOf(seg, required);
+    } else if (CURL.test(seg)) {
+      const url = seg.match(/https?:\/\/\S+/)?.[0];
+      if (!url) continue;
+      let pathname = null;
+      try { pathname = new URL(url.replace(/["']/g, '')).pathname; } catch { continue; }
+      const probe = goal.probe || {};
+      if (probe.path && pathname.replace(/\/$/, '') !== probe.path.replace(/\/$/, '')) continue;
+      const code = /%\{http_code\}/.test(seg) ? text.match(/(\d{3})\s*$/)?.[1] || null : null;
+      const failFlag = /(?:^|\s)(?:-[a-zA-Z]*f[a-zA-Z]*|--fail(?:-with-body)?)(?:\s|$)/.test(seg);
+      role = 'state';
+      if (code) proven = probe.status ? code === probe.status : /^2/.test(code);
+      else proven = failFlag && (!probe.status || probe.status.startsWith('2'));
+    }
+  }
+  if (!role) return null;
+  const ok = transportSuccess === true && !masked && Boolean(scope) && (role === 'mutation' || proven);
+  return { kind: 'operation', success: ok, transportSuccess: transportSuccess === true, harness,
+    ...(masked ? { exitStatusUnproven: true } : {}),
+    operation: { domain, role, scope, target: role === 'state' ? null : target,
+      ...(role === 'state' ? { state: 'verified', complete: ok } : {}) } };
+}

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

@@ -7,7 +7,7 @@ import fsSync from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { withAsyncLock, LOCK_MAX_SLICE_MS } from './async-lock.mjs';
-import { cronOperationReceipt } from './cron-operation-adapter.mjs';
+import { cronOperationReceipt, bashOperationReceipt } from './cron-operation-adapter.mjs';
 import { operationCompletionPolicy, foldOperationEvidence, compactOperation } from './operation-evidence.mjs';
 
 // Hook-context self-deadline (2.4.1 orphan-leak class): armed ONLY on direct
@@ -693,6 +693,15 @@ function gitOutput(args, cwd) {
 // so the session root's fingerprint never moves for work done there. Only a LEADING `cd <dir>`
 // that lands in a checkout sharing this repo's git common dir redirects the fingerprint; an
 // unrelated repo, a missing dir or any git failure keeps the session root (fail-closed).
+// The router stamps CODE_IMPLEMENTATION on every mutating lane, so the read-only valves must
+// treat it like an absent kind; MIXED/OPERATIONAL/CONFIGURATION keep their own evidence.
+// A stamped CODE_IMPLEMENTATION only opens a valve when the prompt carried no mutation order.
+function plainCodeContract(contract, state) {
+  if (!contract?.taskKind) return true;
+  return contract.taskKind === 'CODE_IMPLEMENTATION'
+    && (state?.routingContext?.mutationOrder === false || state?.routingContext?.planOnly === true);
+}
+
 function bashWorkspaceScope(command, projectRoot, shellCwd) {
   const here = { root: projectRoot, foreign: false };
   const match = String(command || '').match(/^\s*cd\s+(?:"([^"]+)"|'([^']+)'|([^\s;&|<>$`~]+))\s*(?:&&|;)/);
@@ -740,10 +749,22 @@ function workspaceFingerprint(cwd) {
   }
 }
 
-// Verification currency excludes UKit's mutable receipts/router state, not source files.
+// Verification currency excludes UKit's mutable receipts/router state and the living
+// bookkeeping docs (never test inputs; the project rules REQUIRE agents to update them after
+// work, so counting them made every wrap-up edit invalidate a still-valid verdict). Source,
+// tests and every other doc stay in the fingerprint.
+const VERIFICATION_FINGERPRINT_EXCLUDES = [
+  ':(exclude).ukit/storage/**',
+  ':(exclude).claude/ukit/skill-router-state.json',
+  ':(exclude)docs/WORKLOG.md',
+  ':(exclude)docs/STATUS.md',
+  ':(exclude)docs/TASKS.md',
+  ':(exclude)docs/MEMORY.md',
+];
+
 function verificationDirtyFingerprint(cwd) {
   try {
-    const paths = ['.', ':(exclude).ukit/storage/**', ':(exclude).claude/ukit/skill-router-state.json'];
+    const paths = ['.', ...VERIFICATION_FINGERPRINT_EXCLUDES];
     const options = { cwd, stdio: ['ignore', 'pipe', 'ignore'], timeout: 1500, maxBuffer: 16 * 1024 * 1024 };
     const diff = execFileSync('git', ['diff', 'HEAD', '--no-ext-diff', '--', ...paths], options);
     const untracked = execFileSync('git', ['ls-files', '--others', '--exclude-standard', '-z', '--', ...paths], options);
@@ -824,6 +845,8 @@ function gitPatchId(diffText) {
 // SPEC §2.2 — is this verdict still valid at the current head?
 // Returns { status, current, headSha } where status is one of:
 //   'current' | 'stale' | 'stale-recoverable' | 'untracked' (no git / no sha data).
+// `reason` names WHY a stale verdict is stale: 'workspace-changed' (same HEAD, tracked/untracked
+// content differs from what was verified) vs 'head-moved'.
 // Cost: rev-parse plus a bounded diff/untracked snapshot for new verdicts;
 // when head moved, the existing diff/patch-id comparison also applies.
 export function verdictCurrent(verdict, { cwd = process.cwd() } = {}) {
@@ -840,7 +863,7 @@ export function verdictCurrent(verdict, { cwd = process.cwd() } = {}) {
   }
   const currentHead = gitOutput(['rev-parse', 'HEAD'], cwd);
   if (verdict.headSha && Object.hasOwn(verdict, 'dirtyFp') && (!verdict.dirtyFp || verificationDirtyFingerprint(cwd) !== verdict.dirtyFp)) {
-    return { status: 'stale', current: false, headSha: currentHead };
+    return { status: 'stale', current: false, headSha: currentHead, reason: 'workspace-changed' };
   }
   if (!currentHead) {
     // No git repo (or git unavailable): currency cannot be proven either way —
@@ -855,7 +878,7 @@ export function verdictCurrent(verdict, { cwd = process.cwd() } = {}) {
   }
   // Head moved. With no base/patch-id recorded there is nothing to compare — stale.
   if (!verdict.baseSha || !verdict.patchId) {
-    return { status: 'stale', current: false, headSha: currentHead };
+    return { status: 'stale', current: false, headSha: currentHead, reason: 'head-moved' };
   }
   const diff = gitOutput(['diff', `${verdict.baseSha}..${currentHead}`], cwd);
   const patchId = gitPatchId(diff);
@@ -2778,7 +2801,12 @@ export async function recordExecutionReceipt({
     exitCode,
   };
 
-  const operationReceipt = cronOperationReceipt(toolName, toolInput, payload.tool_response ?? payload.tool_output ?? payload.tool_result, success, { sessionId: explicitSessionId(payload), harness });
+  const toolResponse = payload.tool_response ?? payload.tool_output ?? payload.tool_result;
+  const nativeGoal = routeState?.routeSummary?.executionContract?.operationGoal;
+  const operationReceipt = cronOperationReceipt(toolName, toolInput, toolResponse, success, { sessionId: explicitSessionId(payload), harness })
+    || (toolName === 'Bash' && !bashScope.foreign
+      ? bashOperationReceipt(toolInput.command, toolResponse, success, nativeGoal, { sessionId: explicitSessionId(payload), harness })
+      : null);
   if (operationReceipt) {
     Object.assign(receipt, operationReceipt);
   } else if (toolName === 'Read' || toolName === 'Grep' || toolName === 'Glob') {
@@ -3073,7 +3101,10 @@ function recoveryInstruction(missingEvidence, ledger = {}, routeSummary = {}, {
         const currency = verdictCurrent(ledger.verdict, { cwd });
         if (currency.current !== true) {
           const sha = ledger.verdict.headSha ? String(ledger.verdict.headSha).slice(0, 12) : 'unknown';
-          instruction = `Verification verdict is stale (head moved since ${sha}). Re-run the routed verification at current head.`;
+          const cause = currency.reason === 'workspace-changed'
+            ? `source/test files changed since it ran at ${sha} (HEAD unchanged or not the cause)`
+            : `head moved since ${sha}`;
+          instruction = `Verification verdict is stale (${cause}). Re-run the routed verification at current head.`;
         }
       }
     }
@@ -3264,6 +3295,12 @@ function evaluateCompletionContract({ state = {}, ledger = {}, cwd, phase = null
   ) {
     return { continue: false, notify: false, complete: true, missingEvidence: [] };
   }
+  // A status/result lookup (READ_ONLY + statusReport) orders no change: there is no write or
+  // verification debt to enforce, and exiting here must not hide a mutation contract —
+  // statusReport is only ever stamped when the request carried no mutation vocabulary.
+  if (routeSummary.executionContract?.taskKind === 'READ_ONLY' && routeSummary.executionContract.statusReport === true) {
+    return { continue: false, notify: false, complete: true, missingEvidence: [] };
+  }
   if (evidence.length === 0) {
     // A route with no completion evidence has no actionable block reason — blocking would
     // loop unboundedly. Release loud instead of ending indistinguishable from a stall.
@@ -3354,7 +3391,7 @@ function evaluateCompletionContract({ state = {}, ledger = {}, cwd, phase = null
       || routeSummary.executionContract.completionRule === 'never-claim-fixed-without-write-and-verification');
   if (
     findCauseNoMutationContract
-    && !routeSummary.executionContract?.taskKind
+    && plainCodeContract(routeSummary.executionContract, state)
     && playbookId !== BUGFIX_PLAYBOOK_ID
     && !effectiveLedger.writeAttempted
     && !effectiveLedger.verificationFailed
@@ -3377,7 +3414,7 @@ function evaluateCompletionContract({ state = {}, ledger = {}, cwd, phase = null
   // satisfied), no mutation was attempted, and no verification failed; anything less has
   // concrete unfinished work and keeps recovering.
   if (
-    !routeSummary.executionContract?.taskKind
+    plainCodeContract(routeSummary.executionContract, state)
     && mode === 'map-impact'
     && !missingEvidence.includes('impact-evidence')
     && effectiveLedger.writeAttempted !== true
@@ -3405,7 +3442,7 @@ function evaluateCompletionContract({ state = {}, ledger = {}, cwd, phase = null
   const readOnlyPrompt = state?.routingContext?.mutationOrder === false
     || state?.routingContext?.planOnly === true;
   if (
-    !routeSummary.executionContract?.taskKind
+    plainCodeContract(routeSummary.executionContract, state)
     && readOnlyPrompt
     && !effectiveLedger.writeAttempted
     && missingEvidence.some((item) => item === 'write-evidence' || item === 'verification-evidence')

package/template_project/.claude/ukit/runtime/operation-evidence.mjs

@@ -61,7 +61,11 @@ export function operationEvidenceStatus(goal, ledger = {}) {
   const matches = (r) => r?.taskInstanceId === ledger.taskInstanceId && r.sessionKey === ledger.sessionKey
     && r.operation?.domain === goal.domain && r.operation.scope === goal.scope;
   const attempts = entries.map((e) => e.mutation).filter(matches);
-  const attempt = attempts.filter((r) => r.operation.target === goal.target).sort((a, b) => b.sequence - a.sequence)[0];
+  // Named verbs/services are ALL required: a receipt for another target never stands in for one.
+  const requiredTargets = Array.isArray(goal.requiredTargets) && goal.requiredTargets.length > 0 ? goal.requiredTargets : [goal.target];
+  const latestFor = (target) => attempts.filter((r) => r.operation.target === target).sort((a, b) => b.sequence - a.sequence)[0];
+  const proofs = requiredTargets.map(latestFor);
+  const attempt = proofs[0];
   const observation = entries.map((e) => e.state).filter(matches).sort((a, b) => b.sequence - a.sequence)[0];
   const op = observation?.operation;
   const absent = goal.desiredState === 'absent' && Array.isArray(op?.presentTargets)
@@ -74,8 +78,8 @@ export function operationEvidenceStatus(goal, ledger = {}) {
   if (goal.completionSemantics === 'ensure-state' && attempts.length === 0) {
     return { complete: true, operationProof: 'desired-state-only' };
   }
-  if (!attempt?.success || !attempt.toolUseId || !observation.toolUseId
-    || !(observation.sequence > attempt.sequence)) return incomplete;
+  if (!proofs.every((proof) => proof?.success && proof.toolUseId && observation.toolUseId
+    && observation.sequence > proof.sequence)) return incomplete;
   return { complete: true, operationProof: 'executed-and-verified' };
 }
 

package/template_project/.claude/ukit/runtime/plan-dispatch.mjs

@@ -0,0 +1,74 @@
+// Thin IO over the stored decomposition plan: dependency-gated dispatch + completion of
+// subtasks. Reuses the resumable-run record (no second store) and is called from the
+// existing Agent|Task PreToolUse/PostToolUse hooks. Fail-open on IO trouble, fail-closed
+// on an explicit dependency/duplicate violation.
+import {
+  readResumableRun, writeResumableRun,
+} from './resumable-run.mjs';
+import { evaluateContextBudget, SUBTASK_MARKER_RE, checkDispatch, applySubtaskStatus } from './context-budget-policy.mjs';
+
+const ROLE_BY_AGENT = { 'feature-implementer': 'implement-subagent', 'bug-debugger': 'implement-subagent', 'code-reviewer': 'review-subagent', 'handoff-planner': 'subagent', 'ukit-small-task-maintainer': 'simple-subagent', 'ukit-vision-analyst': 'simple-subagent' };
+
+/** Advisory soft-budget check of a subtask's scoped context for the dispatched agent role. Never blocks. */
+export function subtaskBudgetAdvice(task, toolInput) {
+  const agent = String(toolInput?.subagent_type ?? toolInput?.agent ?? '').toLowerCase();
+  const role = ROLE_BY_AGENT[agent] ?? 'subagent';
+  const verdict = evaluateContextBudget({ role, promptTokens: task?.scopeTokens });
+  return { role, ...verdict };
+}
+
+export function subtaskIdFromInput(toolInput) {
+  const input = toolInput && typeof toolInput === 'object' ? toolInput : {};
+  const texts = [input.prompt, input.description, input.task, ...(Array.isArray(input.tasks) ? input.tasks.flatMap((t) => [t?.task, t?.prompt, t?.description]) : [])];
+  for (const t of texts) {
+    const m = typeof t === 'string' ? SUBTASK_MARKER_RE.exec(t) : null;
+    if (m) return m[1];
+  }
+  return null;
+}
+
+const parentOf = (subtaskId) => subtaskId.replace(/\.(?:\d+|integrate)$/, '');
+
+async function load(projectRoot, subtaskId) {
+  const taskId = parentOf(subtaskId);
+  const read = await readResumableRun(projectRoot, { taskId });
+  if (!read.record) return null;
+  const decisions = read.record.decisions ?? [];
+  const index = decisions.findIndex((d) => d && d.type === 'decomposition');
+  return index < 0 ? null : { record: read.record, decisions, index };
+}
+
+async function save(projectRoot, loaded, plan) {
+  const decisions = loaded.decisions.slice();
+  decisions[loaded.index] = { type: 'decomposition', ...plan };
+  return writeResumableRun(projectRoot, { ...loaded.record, decisions, updatedAt: Date.now() });
+}
+
+/** PreToolUse: `{ok:true}` (marks running) or `{ok:false, reason, missing?}`. */
+export async function dispatchSubtask(projectRoot, subtaskId, toolInput = null) {
+  try {
+    const loaded = await load(projectRoot, subtaskId);
+    if (!loaded) return { ok: true, tracked: false };
+    const plan = loaded.decisions[loaded.index];
+    const verdict = checkDispatch(plan, subtaskId);
+    if (!verdict.ok) return verdict;
+    const saved = await save(projectRoot, loaded, applySubtaskStatus(plan, subtaskId, 'running'));
+    return { ok: true, tracked: saved.ok === true, budget: subtaskBudgetAdvice(verdict.task, toolInput) };
+  } catch {
+    return { ok: true, tracked: false };
+  }
+}
+
+/** PostToolUse: done on success, back to pending (retryable) on failure. */
+export async function completeSubtask(projectRoot, subtaskId, { success }) {
+  try {
+    const loaded = await load(projectRoot, subtaskId);
+    if (!loaded) return { ok: false, reason: 'no-plan' };
+    const plan = loaded.decisions[loaded.index];
+    if (!plan.tasks?.some((t) => t.id === subtaskId)) return { ok: false, reason: 'unknown-subtask' };
+    const saved = await save(projectRoot, loaded, applySubtaskStatus(plan, subtaskId, success ? 'done' : 'pending'));
+    return { ok: saved.ok === true };
+  } catch {
+    return { ok: false, reason: 'io' };
+  }
+}

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

@@ -115,6 +115,13 @@ async function buildResumableRunLines(projectRoot, state, config) {
     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}`);
+    const plan = (Array.isArray(record.decisions) ? record.decisions : []).find((d) => d && d.type === 'decomposition');
+    if (plan && Array.isArray(plan.tasks)) {
+      lines.push(`- Resumed decomposition plan (${plan.tasks.length} steps, parent acceptance preserved): dispatch scoped subtasks, do not replan unless sources change`);
+      for (const t of plan.tasks.slice(0, 6)) {
+        lines.push(`  - ${t.id}: ${(t.files ?? []).join(', ') || 'integration'} deps=[${(t.deps ?? []).join(',')}]`);
+      }
+    }
     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}`);