@ngockhoale/ukit 3.4.32 → 3.4.33

package/CHANGELOG.md

@@ -9,6 +9,13 @@ All notable changes to UKit are documented here.
 - New `/ukit:ci-check` command + `ci-check.mjs` helper (core pack): prechecks, fail-closed budget guard, local preflight, at most one dispatch per invocation, write-ahead run-id state, `status` (never dispatches), `--ref`, `--dry-run`, per-OS report. Never pushes, merges or publishes.
 - Default-branch bootstrap stub documented in `docs/design/CI-CROSS-PLATFORM-MATRIX.md` (requires separate approval).
 
+## 3.4.33 - 2026-10-11
+
+**OMP token optimization, adaptive task decomposition and Completion Gate reliability.** Verified with the full suite and `yarn release:verify`.
+- **OMP project compaction.** Project `.omp/config.yml` defaults `compaction.thresholdTokens` to 90K; legacy 350K values migrate; install/update merge safely, preserve user overrides and per-agent compaction thresholds; uninstall is ownership-aware. Global OMP config is never touched (OMP 18.8.9 compatible).
+- **Adaptive task decomposition.** Context budget policy, cost-aware decomposition, runtime plan dispatch enforcement for tagged subtasks, dependency handling, resume/progress preservation and parent acceptance criteria; no redundant replanning.
+- **Completion Gate.** Status/result lookups are classified READ_ONLY (no fake write/verification evidence); coding tasks still require write and verification evidence. Contracts are bound to task, session and source snapshot; a read-only or answer-only reroute parks the running implementation contract and a continuation restores it; new task ids never inherit old evidence.
+
 ## 3.4.32 - 2026-10-11
 
 **UNIC-Decision integration P1: safety floors, ordinal score contract, request caps.** Verified with the full suite (566 files) and `yarn release:verify`; no live inference was run (offline fixtures plus an offline run of the Laya server translator).

package/manifests/documentation.yaml

@@ -418,6 +418,17 @@ entries:
     validation: [none]
     archive_policy: immutable
     notes: C99 measurement-only sub-agent cost audit snapshot; registered in 3.4.25 (was unclassified on 3.4.24)
+  - id: docs-analysis-context-threshold-simulation
+    path: docs/analysis/CONTEXT-THRESHOLD-SIMULATION.md
+    class: archive
+    audience: [maintainer]
+    owner: product
+    source_of_truth: docs/analysis/CONTEXT-THRESHOLD-SIMULATION.md
+    merge_strategy: none
+    load_policy: never
+    validation: [none]
+    archive_policy: immutable
+    notes: Corrected compaction-threshold simulation (observed vs hypothetical, LIMITED validity)
   - id: docs-analysis-handoff-root-cause-audit
     path: docs/analysis/HANDOFF-ROOT-CAUSE-AUDIT.md
     class: archive

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.32",
+  "version": "3.4.33",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/src/core/diffPlan.js

@@ -1,7 +1,9 @@
 import fs from 'node:fs/promises';
+import YAML from 'yaml';
 import { isSymlinkTo } from './fileOps.js';
 import { GATEWAY_RESILIENCE_ENV_DEFAULTS } from './gatewayResilienceEnv.js';
 import { isOmpConfigTarget, mergeOmpConfig } from './ompConfigMerge.js';
+import { mergeOmpProjectConfig } from './ompProjectConfig.js';
 import { mergeRuntimeConfigText } from './runtimeConfigMerge.js';
 
 const GATEWAY_RESILIENCE_KEYS = new Set(Object.keys(GATEWAY_RESILIENCE_ENV_DEFAULTS));
@@ -163,13 +165,65 @@ function canonicalize(value) {
   return value;
 }
 
-function resolveFileAction(entry, existingContent) {
+// What UKit itself ensured in the file: the merged text, but with compaction values
+// the user overrode shown as UKit's rendered defaults — so uninstall can tell a
+// user-owned override (differs → kept) from a UKit-installed value (same → removed).
+function ukitInstalledText(mergedText, renderedText) {
+  try {
+    const merged = YAML.parseDocument(mergedText);
+    const defaults = YAML.parse(renderedText)?.compaction;
+    const current = merged.get('compaction');
+    if (!isPlainObject(defaults) || !current || typeof current.get !== 'function') return mergedText;
+    let differs = false;
+    for (const [key, value] of Object.entries(defaults)) {
+      if (current.get(key) !== value) {
+        differs = true;
+        current.set(key, value);
+      }
+    }
+    // Same rule for UKit's per-agent task compaction overrides: a user-set value is
+    // shown as the shipped default so uninstall treats it as user-owned.
+    const defaultOverrides = YAML.parse(renderedText)?.task?.agentCompactionThresholdOverrides;
+    if (isPlainObject(defaultOverrides)) {
+      for (const [agent, value] of Object.entries(defaultOverrides)) {
+        const currentValue = merged.getIn(['task', 'agentCompactionThresholdOverrides', agent]);
+        if (currentValue !== undefined && currentValue !== value) {
+          differs = true;
+          merged.setIn(['task', 'agentCompactionThresholdOverrides', agent], value);
+        }
+      }
+    }
+    // Agents the user added are not UKit's: drop them from the installed view.
+    const userMap = merged.getIn(['task', 'agentCompactionThresholdOverrides']);
+    if (isPlainObject(defaultOverrides) && userMap && typeof userMap.items !== 'undefined') {
+      const extra = userMap.items.filter((p) => !(String(p.key?.value ?? p.key) in defaultOverrides));
+      for (const p of extra) {
+        differs = true;
+        merged.deleteIn(['task', 'agentCompactionThresholdOverrides', String(p.key?.value ?? p.key)]);
+      }
+    }
+    return differs ? String(merged) : mergedText;
+  } catch {
+    return mergedText;
+  }
+}
+
+function resolveFileAction(entry, existingContent, ompOwnership = null) {
   const exists = existingContent !== null;
   const binaryEntry = Buffer.isBuffer(entry.renderedContent);
 
   let action;
   if (!exists) {
     action = 'create';
+    if (isOmpConfigTarget(entry.targetPath) && typeof entry.renderedContent === 'string') {
+      return {
+        ...entry,
+        exists,
+        action,
+        existingContent,
+        ompOwnership: { originalText: null, installedText: entry.renderedContent },
+      };
+    }
   } else if (entry.mergeStrategy === 'append' && !binaryEntry) {
     action = existingContent.endsWith(entry.renderedContent) ? 'unchanged' : 'update';
   } else if (entry.mergeStrategy === 'prepend' && !binaryEntry) {
@@ -184,9 +238,34 @@ function resolveFileAction(entry, existingContent) {
     // SPEC §7 step 9: `.omp/config.yml` gets a semantic, comment-safe migration
     // merge — the action compares the MERGED text against the existing file, so
     // preserved user regions do not count as drift.
-    const merged = mergeOmpConfig(existingContent, entry.renderedContent);
+    // Compaction first (ownership-aware, surgical, comment-preserving); the approval
+    // merge then runs over that text, so user compaction values survive verbatim.
+    let projectMerge = null;
+    try {
+      projectMerge = mergeOmpProjectConfig(existingContent, entry.renderedContent, ompOwnership);
+    } catch {
+      projectMerge = null; // unparsable → mergeOmpConfig reports parseError below
+    }
+    const merged = mergeOmpConfig(projectMerge ? projectMerge.text : existingContent, entry.renderedContent);
+    if (merged.report.parseError) {
+      // Unparseable existing file (or broken template): never replace the user's file
+      // with the template — leave it untouched and let install report it.
+      return { ...entry, renderedContent: existingContent, migrationReport: merged.report, exists, action: 'unchanged', existingContent };
+    }
     action = merged.text === existingContent ? 'unchanged' : 'update';
-    return { ...entry, renderedContent: merged.text, migrationReport: merged.report, exists, action, existingContent };
+    const ownership = projectMerge
+      ? { originalText: projectMerge.ownership.originalText, installedText: ukitInstalledText(merged.text, entry.renderedContent) }
+      : null;
+    return {
+      ...entry,
+      renderedContent: merged.text,
+      migrationReport: merged.report,
+      ompOwnership: ownership,
+      ompOwnershipWarning: projectMerge?.warning ?? null,
+      exists,
+      action,
+      existingContent,
+    };
   } else if (entry.mergeStrategy === 'merge_env_overwrite_with_backup' && typeof existingContent === 'string') {
     // Settings.json: ignore UKit-managed gateway resilience env keys (post-apply written
     // and may carry user overrides). All other top-level keys — and the rest of the env
@@ -222,7 +301,7 @@ function resolveFileAction(entry, existingContent) {
 // write then crashes mid-install on a target that may have been there all along.
 // Existence for skip entries is decided by lstat (no symlink follow, no device open —
 // reading a FIFO would hang).
-async function resolveSkipEntryAction(entry) {
+async function resolveSkipEntryAction(entry, ompOwnership = null) {
   let stat;
   try {
     stat = await fs.lstat(entry.targetPath);
@@ -250,10 +329,10 @@ async function resolveSkipEntryAction(entry) {
     // means present-but-inaccessible. Either way: owner territory, skip it.
     return { ...entry, exists: read.status === 'unreadable', action: 'skip', existingContent: null };
   }
-  return resolveFileAction(entry, read.content);
+  return resolveFileAction(entry, read.content, ompOwnership);
 }
 
-export async function diffInstallPlan(plan) {
+export async function diffInstallPlan(plan, { ompOwnership = null } = {}) {
   // Check all entries in parallel
   const results = await Promise.all(
     plan.entries.map(async (entry) => {
@@ -263,7 +342,7 @@ export async function diffInstallPlan(plan) {
       }
 
       if (entry.mergeStrategy === 'skip') {
-        return resolveSkipEntryAction(entry);
+        return resolveSkipEntryAction(entry, ompOwnership);
       }
 
       const read = await readFileOrStatus(
@@ -273,7 +352,7 @@ export async function diffInstallPlan(plan) {
       if (read.status === 'unreadable') {
         return conflictResult(entry, read.error);
       }
-      return resolveFileAction(entry, read.status === 'ok' ? read.content : null);
+      return resolveFileAction(entry, read.status === 'ok' ? read.content : null, ompOwnership);
     }),
   );
 

package/src/core/executionContracts.js

@@ -179,12 +179,17 @@ export function classifyTaskSemantics({ promptText = '', targetFile = '' } = {})
     && /\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));
   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)
+  // 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 && !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' } } : {}) };
 }
@@ -196,5 +201,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/src/core/metadata.js

@@ -68,6 +68,7 @@ export async function writeInstallMetadata({
   projectRoot,
   managedRelativePaths = null,
   retainedManagedRelativePaths = [],
+  ompConfigOwnership = null,
   lockStaleMs,
   lockMaxWaitMs,
 }) {
@@ -133,6 +134,10 @@ export async function writeInstallMetadata({
       summary,
       files: allFiles,
     };
+    // Ownership record for .omp/config.yml (what UKit installed vs what was there
+    // before) — lets uninstall revert only UKit's changes. Kept across runs.
+    const ownership = ompConfigOwnership ?? (previousData?.tool === 'ukit' ? previousData.ompConfigOwnership : null);
+    if (ownership) metadata.ompConfigOwnership = ownership;
 
     await ensureDir(path.dirname(installMetaPath));
     await writeJson(installMetaPath, metadata);

package/src/core/ompConfigMerge.js

@@ -21,6 +21,8 @@ function emptyReport() {
     coercedPromptPatterns: [],
     preservedModelRoles: false,
     addedModelRoleKeys: [],
+    preservedCompactionKeys: [],
+    migratedCompactionKeys: [],
     preservedTopLevelKeys: [],
     preservedPatterns: [],
     // TASK-002 / FR-002 — every `{{token}}` left in the merged output. A token
@@ -203,6 +205,64 @@ export function mergeOmpConfig(existingText, renderedText) {
     }
   }
 
+  // compaction per-key union: existing keys always win (user overrides, thresholdPercent,
+  // unknown keys). The legacy 350000 migration needs ownership proof and lives in
+  // ompProjectConfig.js (applied before this merge). Absent keys come from the defaults.
+  const renderedCompaction = extractScalarMapSpan(lines, 'compaction');
+  if (renderedCompaction && isPlainObject(existing.compaction) && isPlainObject(rendered?.compaction)) {
+    const merged = { ...rendered.compaction };
+    for (const [key, value] of Object.entries(existing.compaction)) {
+      // A non-scalar/unresolved-token value is never a deliberate user choice.
+      if (value !== null && typeof value === 'object' && key in merged) continue;
+      merged[key] = value;
+      if (key in rendered.compaction && value !== rendered.compaction[key]) {
+        report.preservedCompactionKeys.push(key);
+      }
+    }
+    const renderedKeys = Object.keys(rendered.compaction);
+    const mergedKeys = Object.keys(merged);
+    const identical = mergedKeys.length === renderedKeys.length
+      && mergedKeys.every((k) => merged[k] === rendered.compaction[k]);
+    if (!identical) {
+      const fragment = YAML.stringify(merged, { indent: 2 })
+        .trimEnd()
+        .split('\n')
+        .map((line) => `  ${line}`);
+      lines.splice(renderedCompaction.start, renderedCompaction.end - renderedCompaction.start, 'compaction:', ...fragment);
+    }
+  }
+
+  // task per-key union: the only UKit-shipped task key is the per-agent compaction override
+  // map. User task keys (effort, isolation, …) and user-set agent entries win verbatim;
+  // agents UKit ships but the file lacks are added. A non-map user `task` value is kept.
+  const renderedTask = extractScalarMapSpan(lines, 'task');
+  if (renderedTask && isPlainObject(rendered?.task) && existing.task !== undefined) {
+    const baseTask = rendered.task;
+    const userTask = existing.task === null ? {} : existing.task;
+    let merged;
+    if (isPlainObject(userTask)) {
+      merged = { ...userTask };
+      for (const k of Object.keys(baseTask)) if (!(k in merged)) merged[k] = baseTask[k];
+      const userOverrides = userTask.agentCompactionThresholdOverrides;
+      if (userOverrides !== undefined) {
+        merged.agentCompactionThresholdOverrides = isPlainObject(userOverrides)
+          ? { ...userOverrides, ...Object.fromEntries(Object.entries(baseTask.agentCompactionThresholdOverrides ?? {}).filter(([k]) => !(k in userOverrides))) }
+          : userOverrides === null
+            ? { ...(baseTask.agentCompactionThresholdOverrides ?? {}) }
+            : userOverrides;
+      }
+    } else {
+      merged = userTask;
+    }
+    if (JSON.stringify(merged) !== JSON.stringify(baseTask)) {
+      const fragment = YAML.stringify(merged, { indent: 2 })
+        .trimEnd()
+        .split('\n')
+        .map((line) => `  ${line}`);
+      lines.splice(renderedTask.start, renderedTask.end - renderedTask.start, 'task:', ...fragment);
+    }
+  }
+
   // §7.2 splice — append preserved allow/deny keys to the rendered
   // tools.approval map (before the first line that leaves the map's indent).
   if (extraApprovalEntries.length > 0) {