@ngockhoale/ukit 3.4.32 → 3.4.33

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