@ngockhoale/ukit 3.4.32 → 3.4.33

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

@@ -1799,16 +1799,27 @@ function classifyTaskSemantics({ promptText = '', targetFile = '' } = {}) {
     && !/^\s*(?:audit|inspect|review|analyze|analyse|explain|read|kiem tra|phan tich)\b/.test(clause));
   const sourceOrder = actionable.some((clause) => /\b(?:implement|fix|refactor|modify|edit|write|update|sua|viet|chinh)\b/.test(clause)
     && /\b(?:source|code|logic|scheduler|implementation|ma nguon)\b|\.[cm]?[jt]sx?\b/.test(clause));
+  const codeChangeVerb = actionable.some((clause) => /\b(?:implement|fix|refactor|modify|edit|write|update|sua|viet|chinh)\b/.test(clause));
+  const hasOperationId = /\b[a-f0-9]{8}(?:[a-f0-9-]{0,28})\b/.test(text);
+  // A cron/job MENTION is not an operation: with a code-change verb in the request, an
+  // operation needs a concrete target id; otherwise it is a coding task about scheduling.
   const operation = actionable.some((clause) => /\b(?:delete|remove|cancel|xoa|huy|ensure|dam bao)\b/.test(clause)
-    && /\bcron\b|scheduled\s+(?:cron\s+)?(?:task|job)|tac vu\s+(?:cron|dinh ky)/.test(clause));
-  const config = actionable.some((clause) => /\b(?:configuration|config|toggle|cau hinh)\b/.test(clause));
+    && /\bcron\b|scheduled\s+(?:cron\s+)?(?:task|job)|tac vu\s+(?:cron|dinh ky)/.test(clause))
+    && (!codeChangeVerb || hasOperationId);
+  const config = !sourceOrder && actionable.some((clause) => /\b(?:configuration|config|toggle|cau hinh)\b/.test(clause)
+    && /\b(?:set|change|toggle|enable|disable|switch|turn|configure|modify|update|edit|doi|bat|tat|chinh)\b/.test(clause));
   const repository = Boolean(targetFile) || /[\w.-]+\.(?:json|ya?ml|toml|ini)\b/.test(text);
-  const readOnly = /\b(?:audit|inspect|review|analyze|analyse|explain|read|kiem tra|phan tich)\b/.test(text)
-    && !sourceOrder && !operation && !config;
+  // A status/result lookup ("check the suite output and report") orders no change: it needs a
+  // lookup verb AND no mutation vocabulary anywhere in the request (fail-closed otherwise).
+  const mutationWord = /\b(?:implement|fix|refactor|modify|edit|write|update|add|create|build|make|install|deploy|remove|delete|rename|replace|change|sua|viet|chinh|them|tao|xoa|doi|cai|cap nhat)\b/.test(text);
+  const statusReport = !mutationWord && !operation && !config
+    && /\b(?:check|status|report|show|summari[sz]e|result|results|kiem tra|bao cao|trang thai|ket qua)\b/.test(text);
+  const readOnly = (/\b(?:audit|inspect|review|analyze|analyse|explain|read|kiem tra|phan tich)\b/.test(text) || statusReport)
+    && !sourceOrder && !codeChangeVerb && !operation && !config;
   const taskKind = operation ? (sourceOrder ? 'MIXED' : 'OPERATIONAL')
     : config ? 'CONFIGURATION' : readOnly ? 'READ_ONLY' : 'CODE_IMPLEMENTATION';
   const id = text.match(/\b[a-f0-9]{8}(?:[a-f0-9-]{0,28})\b/)?.[0] || null;
-  return { taskKind, ...(config ? { configurationScope: repository ? 'repository' : 'external' } : {}),
+  return { taskKind, ...(taskKind === 'READ_ONLY' && statusReport ? { statusReport: true } : {}), ...(config ? { configurationScope: repository ? 'repository' : 'external' } : {}),
     ...(operation ? { operationGoal: { domain: 'scheduled-job', target: id, desiredState: /\b(?:delete|remove|cancel|xoa|huy|absent|removed|deleted|no longer|khong con)\b/.test(actionable.join(' ')) ? 'absent' : 'present',
       completionSemantics: /\b(?:ensure|dam bao)\b/.test(text) ? 'ensure-state' : 'execute-and-verify' } } : {}) };
 }
@@ -1820,6 +1831,7 @@ function applyTaskSemantics(contract, semantic) {
   return { ...(contract || {}), ...semantic,
     completionEvidence: operationOnly ? ['operation-verification']
       : semantic.taskKind === 'MIXED' ? [...new Set([...evidence, 'write-evidence', 'operation-verification'])]
+        : semantic.taskKind === 'READ_ONLY' && semantic.statusReport ? []
         : semantic.taskKind === 'READ_ONLY' ? (evidence.length === 1 && evidence[0] === 'verification-evidence' ? evidence : ['impact-evidence']) : evidence };
 }
 
@@ -3626,17 +3638,48 @@ function applyTaskSemantics(contract, semantic) {
       persisted.routingContext ||= {};
       persisted.routingContext.lastExplicitUserPromptText = previous.routingContext.lastExplicitUserPromptText;
     }
+    if (continuingTask && !persisted.suspendedContract && previous.suspendedContract) {
+      persisted.suspendedContract = previous.suspendedContract;
+    }
     const semantic = continuingTask && previous.routeSummary?.executionContract?.taskKind
       ? previous.routeSummary.executionContract
       : classifyTaskSemantics({ promptText: extractPrompt(payload) || persisted.routingContext?.lastExplicitUserPromptText, targetFile: persisted.routingContext?.targetFile });
     const informationalTurn = !continuingTask && persisted.routingContext?.executionMode === 'informational'
       && semantic.taskKind === 'CODE_IMPLEMENTATION';
     if (informationalTurn) {
+      // An answer-only turn must not enforce carried write debt, but it must not ERASE the
+      // contract either: park it (session- and task-bound) so a continuation or the next
+      // tool event of the same session restores it instead of finding "no contract routed".
+      const parked = previous.routeSummary?.executionContract?.completionEvidence?.length
+        ? { sessionId, taskInstanceId: previous.taskInstanceId, requestKey: previous.requestKey,
+            routeSummary: previous.routeSummary, routingContext: previous.routingContext, ts: Date.now() }
+        : previous.suspendedContract;
+      if (parked) persisted.suspendedContract = parked;
       delete persisted.routeSummary;
       delete persisted.requestKey;
-    } else if (semantic.taskKind !== 'CODE_IMPLEMENTATION' || persisted.routeSummary) {
+    } else if (semantic.statusReport && !continuingTask) {
+      // A status/result lookup is a read-only turn with its own task id: it carries no write
+      // debt, but it must not erase a running implementation's contract — park it for `continue`.
+      const prior = previous.routeSummary?.executionContract;
+      const parked = prior && !prior.statusReport && prior.completionEvidence?.length
+        ? { sessionId, taskInstanceId: previous.taskInstanceId, requestKey: previous.requestKey,
+            routeSummary: previous.routeSummary, routingContext: previous.routingContext, ts: Date.now() }
+        : previous.suspendedContract;
+      if (parked) persisted.suspendedContract = parked;
       persisted.routeSummary ||= { executionMode: 'local-build' };
       persisted.routeSummary.executionContract = applyTaskSemantics(
+        persisted.routeSummary.executionContract || buildExecutionContract('local-build'), semantic);
+      delete persisted.routeSummary.completionState;
+      delete persisted.routeSummary.continuationState;
+    } else if (semantic.taskKind !== 'CODE_IMPLEMENTATION' || persisted.routeSummary) {
+      persisted.routeSummary ||= { executionMode: 'local-build' };
+      // A carried status-report contract must not leak its empty evidence / flag onto a
+      // turn that is not itself a status lookup: rebuild the base contract instead.
+      const carriedStatus = persisted.routeSummary.executionContract?.statusReport === true && !semantic.statusReport;
+      if (carriedStatus && persisted.routingContext?.mutationOrder === true) {
+        delete persisted.routeSummary.executionContract;
+      }
+      if (!carriedStatus || persisted.routingContext?.mutationOrder === true) persisted.routeSummary.executionContract = applyTaskSemantics(
         persisted.routeSummary.executionContract || buildExecutionContract(persisted.routeSummary.executionMode === 'informational' ? 'local-build' : persisted.routeSummary.executionMode), semantic);
       if (semantic.taskKind === 'OPERATIONAL' || semantic.taskKind === 'READ_ONLY'
         || (semantic.taskKind === 'CONFIGURATION' && semantic.configurationScope === 'external')) {
@@ -3647,6 +3690,12 @@ function applyTaskSemantics(contract, semantic) {
         persisted.routeSummary.continuationState = buildContinuationState({ completionState: persisted.routeSummary.completionState });
       }
     }
+    // Keep a parked implementation contract alive across further answer/status turns of the
+    // same session (previous is already session-scoped); a fresh implementation route drops it.
+    if (!persisted.suspendedContract && previous.suspendedContract
+      && (!persisted.routeSummary || persisted.routeSummary.executionContract?.statusReport)) {
+      persisted.suspendedContract = previous.suspendedContract;
+    }
     text = JSON.stringify(persisted);
     await writeJsonFileAtomic(statePath, text);
     if (!sessionId) return;
@@ -3668,11 +3717,22 @@ function applyTaskSemantics(contract, semantic) {
   const sidecarPrevious = sessionId && String(storedPrevious?.sessionId || '').trim() !== sessionId
     ? await readJson(path.join(projectRoot, '.ukit', 'storage', 'cache', 'route-state', `${sessionId.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 96) || 'default'}.json`), {})
     : {};
-  const previous = sessionId
+  let previous = sessionId
     ? [storedPrevious, sidecarPrevious].find((state) => String(state?.sessionId || '').trim() === sessionId) || {}
     : storedPrevious;
   const continuationPrompt = /^(?:continue|resume|keep going|proceed|tiep tuc)(?:\s+(?:the task|this task|previous task))?[.!]?$/i.test(
     extractPrompt(payload).normalize('NFD').replace(/[̀-ͯ]/g, '').trim());
+  // Restore a contract parked by an informational turn: only for the SAME session, and only
+  // on an explicit continuation or a mutating tool event (never a fresh prompt, which routes on its own,
+  // and never a read during an answer/status turn: that must not resurrect write debt).
+  const parkedContract = previous.suspendedContract;
+  if ((!previous.routeSummary || previous.routeSummary?.executionContract?.statusReport) && parkedContract?.routeSummary && parkedContract.taskInstanceId
+    && sessionId && parkedContract.sessionId === sessionId
+    && (continuationPrompt || /^(?:Edit|Write|MultiEdit|NotebookEdit)$/.test(String(payload.tool_name || '')))) {
+    previous = { ...previous, taskInstanceId: parkedContract.taskInstanceId, routeSummary: parkedContract.routeSummary,
+      requestKey: parkedContract.requestKey, routingContext: parkedContract.routingContext || previous.routingContext };
+    delete previous.suspendedContract;
+  }
   const continuingTask = Boolean(previous.taskInstanceId && (payload.tool_name || continuationPrompt));
   const taskInstanceId = continuingTask
     ? previous.taskInstanceId

package/template_project/.claude/ukit/index/route-resolver.mjs

@@ -1071,16 +1071,29 @@ export function classifyTaskSemantics({ promptText = '', targetFile = '' } = {})
     && !/^\s*(?:audit|inspect|review|analyze|analyse|explain|read|kiem tra|phan tich)\b/.test(clause));
   const sourceOrder = actionable.some((clause) => /\b(?:implement|fix|refactor|modify|edit|write|update|sua|viet|chinh)\b/.test(clause)
     && /\b(?:source|code|logic|scheduler|implementation|ma nguon)\b|\.[cm]?[jt]sx?\b/.test(clause));
+  const codeChangeVerb = actionable.some((clause) => /\b(?:implement|fix|refactor|modify|edit|write|update|sua|viet|chinh)\b/.test(clause));
+  const hasOperationId = /\b[a-f0-9]{8}(?:[a-f0-9-]{0,28})\b/.test(text);
+  // A cron/job MENTION is not an operation: with a code-change verb in the request, an
+  // operation needs a concrete target id; otherwise it is a coding task about scheduling.
   const operation = actionable.some((clause) => /\b(?:delete|remove|cancel|xoa|huy|ensure|dam bao)\b/.test(clause)
-    && /\bcron\b|scheduled\s+(?:cron\s+)?(?:task|job)|tac vu\s+(?:cron|dinh ky)/.test(clause));
-  const config = actionable.some((clause) => /\b(?:configuration|config|toggle|cau hinh)\b/.test(clause));
+    && /\bcron\b|scheduled\s+(?:cron\s+)?(?:task|job)|tac vu\s+(?:cron|dinh ky)/.test(clause))
+    && (!codeChangeVerb || hasOperationId);
+  // A config MENTION is not a config change: the same clause needs a mutation verb, and a
+  // request that also changes source/code is a coding task (config is part of its tests/fixtures).
+  const config = !sourceOrder && actionable.some((clause) => /\b(?:configuration|config|toggle|cau hinh)\b/.test(clause)
+    && /\b(?:set|change|toggle|enable|disable|switch|turn|configure|modify|update|edit|doi|bat|tat|chinh)\b/.test(clause));
   const repository = Boolean(targetFile) || /[\w.-]+\.(?:json|ya?ml|toml|ini)\b/.test(text);
-  const readOnly = /\b(?:audit|inspect|review|analyze|analyse|explain|read|kiem tra|phan tich)\b/.test(text)
-    && !sourceOrder && !operation && !config;
+  // A status/result lookup ("check the suite output and report") orders no change: it needs a
+  // lookup verb AND no mutation vocabulary anywhere in the request (fail-closed otherwise).
+  const mutationWord = /\b(?:implement|fix|refactor|modify|edit|write|update|add|create|build|make|install|deploy|remove|delete|rename|replace|change|sua|viet|chinh|them|tao|xoa|doi|cai|cap nhat)\b/.test(text);
+  const statusReport = !mutationWord && !operation && !config
+    && /\b(?:check|status|report|show|summari[sz]e|result|results|kiem tra|bao cao|trang thai|ket qua)\b/.test(text);
+  const readOnly = (/\b(?:audit|inspect|review|analyze|analyse|explain|read|kiem tra|phan tich)\b/.test(text) || statusReport)
+    && !sourceOrder && !codeChangeVerb && !operation && !config;
   const taskKind = operation ? (sourceOrder ? 'MIXED' : 'OPERATIONAL')
     : config ? 'CONFIGURATION' : readOnly ? 'READ_ONLY' : 'CODE_IMPLEMENTATION';
   const id = text.match(/\b[a-f0-9]{8}(?:[a-f0-9-]{0,28})\b/)?.[0] || null;
-  return { taskKind, ...(config ? { configurationScope: repository ? 'repository' : 'external' } : {}),
+  return { taskKind, ...(taskKind === 'READ_ONLY' && statusReport ? { statusReport: true } : {}), ...(config ? { configurationScope: repository ? 'repository' : 'external' } : {}),
     ...(operation ? { operationGoal: { domain: 'scheduled-job', target: id, desiredState: /\b(?:delete|remove|cancel|xoa|huy|absent|removed|deleted|no longer|khong con)\b/.test(actionable.join(' ')) ? 'absent' : 'present',
       completionSemantics: /\b(?:ensure|dam bao)\b/.test(text) ? 'ensure-state' : 'execute-and-verify' } } : {}) };
 }
@@ -1092,5 +1105,6 @@ export function applyTaskSemantics(contract, semantic) {
   return { ...(contract || {}), ...semantic,
     completionEvidence: operationOnly ? ['operation-verification']
       : semantic.taskKind === 'MIXED' ? [...new Set([...evidence, 'write-evidence', 'operation-verification'])]
+        : semantic.taskKind === 'READ_ONLY' && semantic.statusReport ? []
         : semantic.taskKind === 'READ_ONLY' ? (evidence.length === 1 && evidence[0] === 'verification-evidence' ? evidence : ['impact-evidence']) : evidence };
 }

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

@@ -73,6 +73,7 @@ import {
 import { applyMeasuredTier, loadTierMap } from './tier-selection.mjs';
 import { resolvePlaybookRoute, loadRegistry, deriveRouteOrchestrationSignals } from './playbook-registry.mjs';
 import { extractHistorySignalsAsync } from './session-history-extractor.mjs';
+import { carryProgress, buildDecompositionPlan, estimateContextWindow, MIN_AUTO_SPLIT_CONFIDENCE } from '../runtime/context-budget-policy.mjs';
 import {
   applyFixLoopEscalation,
   isFixLoopEscalationDue,
@@ -1060,6 +1061,7 @@ export async function routeTask(input = {}, { signal = null, deadlineMs = null,
     preparedRoute,
     projectVerification,
     cachedContextResult: helperCacheSnapshot.contextResult,
+    transcriptPath: normalizedInput.transcriptPath ?? process.env.UKIT_TRANSCRIPT_PATH ?? null,
     cachedVerificationPlan: helperCacheSnapshot.verificationPlan,
     useIndexedContext,
     previousContextSnapshot,
@@ -1390,6 +1392,7 @@ async function main() {
     commandNamespace,
     preparedRoute,
     projectVerification,
+    transcriptPath,
     cachedContextResult: helperCacheSnapshot.contextResult,
     cachedVerificationPlan: helperCacheSnapshot.verificationPlan,
     useIndexedContext,
@@ -2116,12 +2119,26 @@ function resumableTaskId({ sessionId = null, taskBoundary }) {
 // (hypotheses/decisions/failures) and completed receipts carry forward; a new
 // boundary starts a fresh record. The phase that just completed is appended to
 // completedBlocks when it changes.
+// The adaptive-decomposition plan rides the record as ONE `decisions` entry
+// (type 'decomposition'), replaced in place so replans never accumulate. Loop
+// state (depth/attempts/seenFingerprints) lives in it, so a re-route of the same
+// task reads it back and shouldDecompose refuses an unchanged split.
+export function findDecompositionDecision(decisions) {
+  return (Array.isArray(decisions) ? decisions : []).find((d) => d && typeof d === 'object' && d.type === 'decomposition') ?? null;
+}
+function mergeDecompositionDecision(decisions, decomposition) {
+  if (!decomposition?.decompose) return decisions;
+  const rest = decisions.filter((d) => !(d && typeof d === 'object' && d.type === 'decomposition'));
+  return [...rest, { type: 'decomposition', ...decomposition }].slice(-12);
+}
+
 function buildResumableRunRecord({
   taskId,
   taskBoundary,
   routeSummary,
   previousRecord = null,
   sourceSnapshot,
+  decomposition = null,
 }) {
   const previous = previousRecord && previousRecord.taskBoundary === taskBoundary
     ? previousRecord
@@ -2162,7 +2179,7 @@ function buildResumableRunRecord({
     },
     invariants: previous?.invariants ?? [],
     hypotheses: previous?.hypotheses ?? [],
-    decisions: previous?.decisions ?? [],
+    decisions: mergeDecompositionDecision(previous?.decisions ?? [], decomposition),
     evidenceRefs: previous?.evidenceRefs ?? [],
     escalationHistory: previous?.escalationHistory ?? [],
     unresolvedFailures: previous?.unresolvedFailures ?? [],
@@ -2186,6 +2203,7 @@ export async function emitResumableRun({
   projectVerification = null,
   signal = null,
   deadlineMs = null,
+  decomposition = null,
 } = {}) {
   const stage = resolveResumableRunStage(config);
   if (stage === 'off') return null;
@@ -2212,6 +2230,7 @@ export async function emitResumableRun({
       routeSummary,
       previousRecord,
       sourceSnapshot,
+      decomposition,
     });
     const write = await writeResumableRun(rootDir, record, {
       signal,
@@ -2251,6 +2270,63 @@ export async function emitResumableRun({
   }
 }
 
+// Runtime caller of the decomposition policy. Context size = newest provider usage in the
+// transcript tail (high confidence); bytes/4 is only a LOW-confidence fallback that never
+// auto-splits (no LLM, no tokenizer). Runs only when the stage is on and a transcript
+// pointer exists; returns null otherwise. Pricing metadata comes from
+// config.contextBudget.pricing when present — without it the 100K boundary is still
+// used as the planning threshold (shouldDecompose default) but nothing is claimed
+// about billing. Never throws.
+export async function planAdaptiveDecomposition({ rootDir, config, routeSummary, routingContext, contextRecommendation, transcriptPath, sessionId }) {
+  try {
+    if (resolveResumableRunStage(config) === 'off' || routingContext?.greetingFastPath || !transcriptPath) return null;
+    const st = await fs.stat(transcriptPath).catch(() => null);
+    if (!st?.isFile()) return null;
+    const preview = contextRecommendation?.preview ?? contextRecommendation ?? {};
+    const primaryTargets = (preview.primaryTargets ?? []).filter((f) => typeof f === 'string').slice(0, 24);
+    const relatedTests = (preview.relatedTests ?? []).filter((f) => typeof f === 'string').slice(0, 24);
+    const fileTokens = {};
+    for (const f of [...primaryTargets, ...relatedTests]) {
+      const fst = await fs.stat(path.resolve(rootDir, f)).catch(() => null);
+      if (fst?.isFile()) fileTokens[f] = Math.ceil(fst.size / 4);
+    }
+    let tailLines = [];
+    try {
+      const fh = await fs.open(transcriptPath, 'r');
+      try {
+        const len = Math.min(st.size, 512 * 1024);
+        const buf = Buffer.alloc(len);
+        await fh.read(buf, 0, len, st.size - len);
+        tailLines = buf.toString('utf8').split('\n').filter(Boolean).slice(-200);
+      } finally { await fh.close(); }
+    } catch { /* fall back to the byte estimate */ }
+    const estimate = estimateContextWindow({ tailLines, transcriptBytes: st.size });
+    const taskBoundary = resumableTaskBoundary(routingContext);
+    const taskId = resumableTaskId({ sessionId, taskBoundary });
+    const resumed = await readResumableRun(rootDir, { taskId, taskBoundary });
+    const previous = findDecompositionDecision(resumed.record?.decisions);
+    const sharedFiles = new Set(primaryTargets).size < primaryTargets.length;
+    const plan = buildDecompositionPlan({
+      parentId: taskId,
+      goal: String(routingContext?.lastExplicitUserPromptText ?? routingContext?.promptText ?? '').slice(0, 200),
+      contextTokens: MIN_AUTO_SPLIT_CONFIDENCE.has(estimate.confidence) ? estimate.tokens : null,
+      primaryTargets,
+      relatedTests,
+      fileTokens,
+      acceptance: routeSummary?.executionContract?.completionEvidence ?? [],
+      coupled: sharedFiles || primaryTargets.length < 2,
+      pricing: config?.contextBudget?.pricing ?? null,
+      previous,
+    });
+    if (!plan.decompose && plan.reason === 'unknown-size') {
+      return { ...plan, reason: `low-confidence-estimate:${estimate.source}`, estimatedTokens: estimate.tokens };
+    }
+    return carryProgress(previous, { ...plan, estimateSource: estimate.source, estimateConfidence: estimate.confidence });
+  } catch {
+    return null;
+  }
+}
+
 async function finalizeTaskRoute({
   rootDir = process.cwd(),
   commandNamespace = '.claude',
@@ -2275,6 +2351,7 @@ async function finalizeTaskRoute({
   // BL-013: precomputed bounded history struct from the caller's transcript
   // extraction — merged into the route record additively + decisions.tsv.
   historySignals = null,
+  transcriptPath = null,
 } = {}) {
   const absoluteRoot = path.resolve(rootDir);
   const activeSkills = preparedRoute?.activeSkills ?? [];
@@ -2537,7 +2614,20 @@ async function finalizeTaskRoute({
   // persisted/updated under .ukit/storage/runs/ and a bounded pointer lands on
   // the execution ledger. The pointer rides routeSummary.resumableRun so the
   // shared route state carries the taskId reinject-context resumes from.
+  const decomposition = await planAdaptiveDecomposition({
+    rootDir: absoluteRoot,
+    config: escalationConfig,
+    routeSummary,
+    routingContext,
+    contextRecommendation,
+    transcriptPath,
+    sessionId,
+  });
+  if (decomposition?.decompose) {
+    routeSummary.decompositionPlan = decomposition;
+  }
   const resumableRun = await emitResumableRun({
+    decomposition,
     rootDir: absoluteRoot,
     config: escalationConfig,
     routeSummary,
@@ -2593,6 +2683,12 @@ function printRouteState(state) {
     );
   }
   console.log(`summary: ${compactSummary}`);
+  const plan = state.routeSummary?.decompositionPlan;
+  if (plan?.decompose) {
+    console.log(`plan: decomposed into ${plan.tasks.length} steps (est ${plan.estimatedTokens} tok, savings ${plan.costs?.savingsRatio}) — dispatch each scoped subtask to a subagent with only its files + handoff, then integrate`);
+    const doneIds = new Set(plan.done ?? []);
+    for (const t of plan.tasks) console.log(`  - ${t.id}: ${t.files.join(', ') || 'integration'} deps=[${t.deps.join(',')}]${doneIds.has(t.id) ? ' DONE' : ''} — start the Agent prompt with "[ukit-subtask ${t.id}]"`);
+  }
   if (state.routeSummary?.executionContract?.modelTier) {
     console.log(`modelTier: ${state.routeSummary.executionContract.modelTier}`);
   }

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']);