@ngockhoale/ukit 3.4.31 → 3.4.33

package/template_project/.claude/ukit/index/sidecar-decision.mjs

@@ -296,67 +296,12 @@ export function buildStatePacket(decision, context) {
   return packet;
 }
 
-// ---------------------------------------------------------------------------
-// Adapter spawn — one bounded single-question batch to unic-decision.mjs.
-// Never throws: every failure resolves to a typed 'unavailable' result.
-// ---------------------------------------------------------------------------
-
-function runAdapterBatch({ spec, context, rootDir, config, batchId }) {
-  const cliPath = process.env.UKIT_DECISION_CLI_PATH || UNIC_DECISION_CLI_PATH;
-  const timeoutMs = Math.min(
-    (isFiniteNumber(config?.decisionPlane?.timeoutMs)
-      ? config.decisionPlane.timeoutMs
-      : ADAPTER_TIMEOUT_CAP_MS) + 1000,
-    ADAPTER_TIMEOUT_CAP_MS + 1000,
-  );
-  const batch = {
-    batchId,
-    boundary: 'sidecar',
-    deadlineMs: Math.max(500, timeoutMs - 1000),
-    statePacket: buildStatePacket(spec.decision, context),
-    questions: [spec.question],
-  };
-  let result = null;
-  try {
-    const spawned = spawnSync(
-      process.execPath,
-      [cliPath, '--root', rootDir],
-      {
-        cwd: rootDir,
-        input: JSON.stringify(batch),
-        encoding: 'utf8',
-        timeout: timeoutMs,
-      },
-    );
-    if (spawned && !spawned.error && spawned.status === 0 && spawned.stdout) {
-      result = JSON.parse(spawned.stdout);
-    } else {
-      result = { status: 'unavailable', fallbackCode: 'adapter-spawn-failed' };
-    }
-  } catch {
-    result = { status: 'unavailable', fallbackCode: 'adapter-spawn-failed' };
-  }
-  if (!result || typeof result !== 'object') {
-    result = { status: 'unavailable', fallbackCode: 'malformed-response' };
-  }
-  return result;
-}
-
-function validModelAnswer(result, decisionKey) {
-  const answers = Array.isArray(result?.answers) ? result.answers : [];
-  const answer = answers.find(
-    (a) => a?.decisionKey === decisionKey && a.validationStatus === 'valid',
-  );
-  return typeof answer?.value === 'string' ? answer.value : null;
-}
-
 /**
  * Resolve one sidecar decision. Returns a typed result; never throws.
  *   {decision, decisionKey, stage, answer, deterministic, source,
- *    outcomeClass, modelAnswer?, agreement?, fallbackCode}
- * `answer` is the authoritative value: the deterministic rule at 'off' and
- * 'shadow', the model's valid answer at 'canary'/'default', and the
- * deterministic rule again on any adapter failure (outcomeClass 'unavailable').
+ *    outcomeClass, fallbackPolicy}
+ * `answer` is always the deterministic rule at every stage: no model call is
+ * made, so there is no model answer, agreement or adapter fallback to report.
  */
 export async function runSidecarDecision({ decision, context = {}, rootDir, homeDir, config } = {}) {
   // Own-property lookup (W3-SD1): `SIDECAR_DECISIONS[name]` would also resolve

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/execution-ledger.mjs

@@ -740,10 +740,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 +836,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 +854,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 +869,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);
@@ -3073,7 +3087,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 +3281,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.

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}`);

package/template_project/.omp/config.yml

@@ -124,18 +124,34 @@ bash:
 memory:
   backend: off
 
-# Auto-compact must trigger BEFORE context-hardcap-gate.sh starts blocking tool
-# calls (compact.hardCapTokens, default 500000). Rendered at install time from the
-# same derived number as env.CLAUDE_CODE_AUTO_COMPACT_WINDOW in
-# template_project/.claude/settings.json (70% of hardCapTokens), so omp and Claude Code
-# cannot drift apart and retuning both is a single edit to
-# template_project/ukit/storage/config.json.
-#
-# Key VERIFIED against omp v17.4.2 (2026-08-22): `compaction.thresholdTokens` is a
-# fixed token limit for context maintenance and overrides the percentage threshold
-# when set; omp's own default is -1 ("use compaction.thresholdPercent"). The key this
-# file shipped with in 2.2.1 — `compact.autoCompactWindow` — was a plan-time guess and
-# omp rejects it outright (`omp config get compact.autoCompactWindow` → "Unknown
-# setting"), so auto-compact never moved off omp's default. See PLAN.md §3 D13.
+# omp-side auto-compaction, project-scoped (omp reads <project>/.omp/config.yml and it
+# takes precedence over ~/.omp/agent/config.yml, which UKit never touches).
+# Keys VERIFIED against omp v18.8.9 (`omp config get compaction.<key>`):
+# thresholdTokens is a fixed token limit that overrides thresholdPercent when > 0
+# (omp default -1).
+# thresholdTokens = min(90000, Claude Code auto-compact window), so a small-context
+# budget is never exceeded by the omp threshold. Starting default, not a hard limit:
+# edit any value here and `ukit update` keeps it. The legacy shipped 350000 is migrated
+# only when UKit's install ledger proves UKit wrote it; `ukit uninstall` reverts just
+# UKit's own additions and keeps your edits. Auto-compact must still trigger BEFORE
+# context-hardcap-gate blocks tool calls.
 compaction:
-  thresholdTokens: {{compact.autoCompactWindow}}
+  enabled: true
+  thresholdTokens: {{omp.compactionThresholdTokens}}
+  midTurnEnabled: true
+  keepRecentTokens: 20000
+
+# Per-agent native compaction thresholds (omp v18.8.9 `task.agentCompactionThresholdOverrides`,
+# keyed by agent name, positive integer tokens). SOFT targets for scoped subagent context:
+# omp compacts the agent's session when it grows past the value — this is NOT a request
+# hard cap (one step can still jump past it). Per-key merge: any agent key you set stays;
+# your other `task:` settings are never touched; `ukit uninstall` removes only these keys
+# when they still carry the shipped value.
+task:
+  agentCompactionThresholdOverrides:
+    feature-implementer: 80000
+    bug-debugger: 80000
+    code-reviewer: 80000
+    handoff-planner: 60000
+    ukit-small-task-maintainer: 40000
+    ukit-vision-analyst: 40000