@ngockhoale/ukit 3.4.32 → 3.4.33

package/src/core/ompProjectConfig.js

@@ -0,0 +1,462 @@
+import YAML, { Alias, Pair, Scalar, YAMLMap, YAMLSeq, parseDocument } from 'yaml';
+
+// OMP project config lifecycle (.omp/config.yml compaction block) — pure text
+// module, no fs. Callers own reading/writing files and persisting the ownership
+// record in install.json.
+//
+// mergeOmpProjectConfig(existingText, defaultsText, ownership):
+//   Surgically adds missing `compaction` defaults using yaml CST ranges so every
+//   other byte (comments, BOM, CRLF, unrelated keys) survives untouched. The
+//   only value ever REWRITTEN is a legacy `thresholdTokens: 350000`, and only
+//   when the ownership record proves ukit itself installed that same value
+//   (ownership.installedText parses to the same thresholdTokens). Everything
+//   else the user set stays.
+//
+// cleanupOmpProjectConfig(currentText, ownership):
+//   Uninstall counterpart. Unchanged file → restore originalText (delete, i.e.
+//   text null, when the file was fresh). User-edited file → keep every user
+//   modification and only remove/revert the owned scalar compaction keys that
+//   still carry the installed value AND were originally absent or different.
+//
+// Conservative no-write: if the compaction subtree uses flow collections,
+// anchors, aliases or merge keys (`<<`), the functions refuse to splice and
+// return the original text plus a warning — surgical edits are only proven
+// safe on plain block mappings. Invalid YAML throws instead.
+
+// The scalar compaction keys ukit owns and may remove on cleanup. Extra keys
+// the user added under compaction are never owned, only these four.
+export const OWNED_COMPACTION_KEYS = ['enabled', 'thresholdTokens', 'midTurnEnabled', 'keepRecentTokens'];
+
+// Pre-90000 ukit default. Migrating it requires ownership proof; a hand-set
+// 350000 (no ownership record, or installedText disagrees) is preserved.
+export const LEGACY_THRESHOLD_TOKENS = 350000;
+
+const COMPACTION_KEY = 'compaction';
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function firstError(doc) {
+  return doc.errors[0]?.message ?? 'unknown parse error';
+}
+
+// parseDocument keeps CST ranges pointing into the ORIGINAL string (BOM
+// inclusive), which is what makes byte-exact splicing possible. Parse errors
+// are collected on the document instead of thrown, so we reject them here.
+function parseDocOrThrow(text, label) {
+  const doc = parseDocument(text);
+  if (doc.errors.length > 0) {
+    throw new Error(`${label}: invalid YAML — ${firstError(doc)}`);
+  }
+  return doc;
+}
+
+function parseDataOrThrow(text, label) {
+  try {
+    return YAML.parse(text);
+  } catch (error) {
+    throw new Error(`${label}: invalid YAML — ${error?.message ?? error}`);
+  }
+}
+
+function detectEol(text) {
+  return text.includes('\r\n') ? '\r\n' : '\n';
+}
+
+// Render a value the way it is spliced into the document: block YAML, trailing
+// newline trimmed. Scalars render single-line; collections render nested lines.
+function formatYamlValue(value) {
+  return YAML.stringify(value).replace(/\n+$/, '');
+}
+
+function lineStartBefore(text, offset) {
+  const i = text.lastIndexOf('\n', Math.max(offset - 1, 0));
+  return i + 1;
+}
+
+// Index just past the newline that terminates the line containing `offset`
+// (or text length at EOF without a trailing newline).
+function lineEndAfter(text, offset) {
+  const i = text.indexOf('\n', offset);
+  return i === -1 ? text.length : i + 1;
+}
+
+function indentOfLine(text, offset) {
+  const start = lineStartBefore(text, offset);
+  const match = /^[ ]*/.exec(text.slice(start));
+  return match ? match[0] : '';
+}
+
+function findCompactionPair(mapNode) {
+  return mapNode.items.find(
+    (pair) => pair.key instanceof Scalar && pair.key.value === COMPACTION_KEY,
+  );
+}
+
+// Reason string when the subtree carries a construct we refuse to edit
+// surgically: flow collections, anchors, aliases, merge keys.
+function unsafeReason(node, depth = 0) {
+  if (!node || depth > 64) return null;
+  if (node instanceof Alias) return 'an alias';
+  if (node.anchor) return 'an anchor';
+  if (node instanceof YAMLMap || node instanceof YAMLSeq) {
+    if (node.flow) return 'flow style';
+    for (const item of node.items) {
+      if (item instanceof Pair) {
+        if (item.key instanceof Scalar && item.key.value === '<<') return 'a merge key';
+        const reason = unsafeReason(item.key, depth + 1) ?? unsafeReason(item.value, depth + 1);
+        if (reason) return reason;
+      } else {
+        const reason = unsafeReason(item, depth + 1);
+        if (reason) return reason;
+      }
+    }
+  }
+  return null;
+}
+
+function noWrite(text, ownership, warning) {
+  return { text, ownership: ownership ?? null, warning };
+}
+
+function applyEdits(text, edits) {
+  let out = text;
+  for (const edit of [...edits].sort((a, b) => b.start - a.start)) {
+    out = out.slice(0, edit.start) + edit.replacement + out.slice(edit.end);
+  }
+  return out;
+}
+
+// One `key: value` line (or block for collection values) at the given indent.
+function renderEntry(key, value, indent, eol) {
+  const parts = formatYamlValue(value).split('\n');
+  const lines = [`${indent}${key}: ${parts[0]}`, ...parts.slice(1).map((line) => (line === '' ? '' : indent + line))];
+  return lines.join(eol);
+}
+
+// Edit appending the full compaction block at end of file.
+function appendBlockEdit(text, compaction, eol) {
+  const lines = [
+    `${COMPACTION_KEY}:`,
+    ...Object.entries(compaction).map(([k, v]) => renderEntry(k, v, '  ', eol)),
+  ];
+  const prefix = text.length > 0 && !text.endsWith('\n') ? eol : '';
+  return { start: text.length, end: text.length, replacement: prefix + lines.join(eol) + eol };
+}
+
+// Edit inserting entries after the compaction map's last item (or right after
+// the `compaction:` line when the map is empty), matching existing indent.
+function insertEntriesEdit(text, pair, entries, eol) {
+  const map = pair.value;
+  let insertAt;
+  let indent;
+  if (map.items.length > 0) {
+    insertAt = map.range[1];
+    indent = indentOfLine(text, map.range[0]);
+  } else {
+    insertAt = lineEndAfter(text, pair.key.range[0]);
+    indent = `${indentOfLine(text, pair.key.range[0])}  `;
+  }
+  const lines = entries.map(([k, v]) => renderEntry(k, v, indent, eol));
+  // When the insertion point does not start a fresh line (EOF without a
+  // trailing newline), open one first.
+  const prefix = insertAt > 0 && text[insertAt - 1] !== '\n' ? eol : '';
+  return { start: insertAt, end: insertAt, replacement: prefix + lines.join(eol) + eol };
+}
+
+// Proof that ukit itself installed `value` as compaction.thresholdTokens: the
+// ownership record's installedText (latest content ukit ensured) must parse to
+// that same value.
+function ownershipProvesThreshold(ownership, value) {
+  if (!isPlainObject(ownership) || typeof ownership.installedText !== 'string') return false;
+  try {
+    const data = YAML.parse(ownership.installedText);
+    return isPlainObject(data?.compaction) && data.compaction.thresholdTokens === value;
+  } catch {
+    return false;
+  }
+}
+
+export function mergeOmpProjectConfig(existingText, defaultsText, ownership) {
+  if (typeof defaultsText !== 'string') {
+    throw new TypeError('mergeOmpProjectConfig: defaultsText must be a string');
+  }
+  if (existingText != null && typeof existingText !== 'string') {
+    throw new TypeError('mergeOmpProjectConfig: existingText must be a string or null');
+  }
+
+  const defaultsData = parseDataOrThrow(defaultsText, 'defaultsText');
+  const defaultsCompaction = defaultsData?.compaction;
+  if (!isPlainObject(defaultsCompaction)) {
+    throw new Error('defaultsText: must define a top-level `compaction` mapping');
+  }
+
+  // Fresh install — nothing to preserve; the defaults text ships verbatim.
+  if (existingText == null) {
+    return {
+      text: defaultsText,
+      ownership: { originalText: null, installedText: defaultsText },
+      warning: null,
+    };
+  }
+
+  const doc = parseDocOrThrow(existingText, 'existing omp project config');
+
+  // Empty file: appending the block keeps it valid YAML, so treat it as
+  // "no compaction" rather than refusing.
+  if (doc.contents != null && !(doc.contents instanceof YAMLMap)) {
+    return noWrite(existingText, ownership, 'merge skipped: top-level YAML document is not a mapping');
+  }
+  const pair = doc.contents ? findCompactionPair(doc.contents) : undefined;
+  const eol = detectEol(existingText);
+  const edits = [];
+  let warning = null;
+
+  if (!pair) {
+    edits.push(appendBlockEdit(existingText, defaultsCompaction, eol));
+  } else {
+    const unsafe = unsafeReason(pair.key) ?? unsafeReason(pair.value);
+    if (unsafe) {
+      return noWrite(existingText, ownership, `merge skipped: compaction uses ${unsafe} — surgical edit refused`);
+    }
+    if (!(pair.value instanceof YAMLMap)) {
+      return noWrite(existingText, ownership, 'merge skipped: compaction is not a block mapping');
+    }
+
+    const missing = [];
+    for (const [defaultKey, defaultValue] of Object.entries(defaultsCompaction)) {
+      const existingPair = pair.value.items.find(
+        (item) => item.key instanceof Scalar && item.key.value === defaultKey,
+      );
+      if (!existingPair) {
+        // Missing key: added. Present keys are user state and never touched
+        // (with the single legacy exception below).
+        missing.push([defaultKey, defaultValue]);
+        continue;
+      }
+      if (
+        defaultKey === 'thresholdTokens' &&
+        existingPair.value instanceof Scalar &&
+        existingPair.value.value === LEGACY_THRESHOLD_TOKENS &&
+        defaultValue !== LEGACY_THRESHOLD_TOKENS
+      ) {
+        if (ownershipProvesThreshold(ownership, LEGACY_THRESHOLD_TOKENS)) {
+          edits.push({
+            start: existingPair.value.range[0],
+            end: existingPair.value.range[1],
+            replacement: formatYamlValue(defaultValue),
+          });
+        } else {
+          // Unknown old config: ukit cannot prove 350000 was installed, so the
+          // value may be deliberate — preserved with a warning.
+          warning = `compaction.thresholdTokens=${LEGACY_THRESHOLD_TOKENS} kept — ownership does not prove ukit installed this value (legacy migration skipped)`;
+        }
+      }
+    }
+    if (missing.length > 0) {
+      edits.push(insertEntriesEdit(existingText, pair, missing, eol));
+    }
+  }
+
+  const text = applyEdits(existingText, edits);
+  const changed = text !== existingText;
+  return {
+    text,
+    ownership: {
+      // originalText is recorded exactly once — the first merge that sees the
+      // file captures it; later merges keep the original provenance.
+      originalText: isPlainObject(ownership) && 'originalText' in ownership ? ownership.originalText : existingText,
+      // installedText always reflects the latest content this module ensured.
+      installedText: changed ? text : isPlainObject(ownership) && ownership.installedText != null ? ownership.installedText : text,
+    },
+    warning,
+  };
+}
+
+function sameValue(a, b) {
+  return a === b;
+}
+
+function originalCompactionOf(ownership) {
+  if (!isPlainObject(ownership) || typeof ownership.originalText !== 'string') return null;
+  try {
+    const data = YAML.parse(ownership.originalText);
+    return isPlainObject(data?.compaction) ? data.compaction : null;
+  } catch {
+    // Unparseable original: no per-key provenance — owned keys are treated as
+    // originally absent (they are only removed when they still match what
+    // ukit installed, so user values remain safe either way).
+    return null;
+  }
+}
+
+function cleanupCompaction(currentText, ownership) {
+  if (currentText == null) {
+    return { text: null, ownership: ownership ?? null, warning: null };
+  }
+  if (typeof currentText !== 'string') {
+    throw new TypeError('cleanupOmpProjectConfig: currentText must be a string or null');
+  }
+  if (!isPlainObject(ownership)) {
+    return noWrite(currentText, ownership, 'cleanup skipped: no ownership record — cannot prove which settings ukit installed');
+  }
+  if (typeof ownership.installedText !== 'string') {
+    return noWrite(currentText, ownership, 'cleanup skipped: ownership record has no installedText');
+  }
+
+  // Unchanged since install: hand the file back exactly as ukit found it
+  // (null = the file did not exist before ukit created it → delete).
+  if (currentText === ownership.installedText) {
+    return { text: ownership.originalText ?? null, ownership, warning: null };
+  }
+
+  // User edited the file: keep every modification, surgically remove/revert
+  // only what ukit owns.
+  const doc = parseDocOrThrow(currentText, 'current omp project config');
+  if (!(doc.contents instanceof YAMLMap)) {
+    return noWrite(currentText, ownership, 'cleanup skipped: top-level YAML document is not a mapping');
+  }
+  const pair = findCompactionPair(doc.contents);
+  if (!pair) {
+    return { text: currentText, ownership, warning: null };
+  }
+  const unsafe = unsafeReason(pair.key) ?? unsafeReason(pair.value);
+  if (unsafe) {
+    return noWrite(currentText, ownership, `cleanup skipped: compaction uses ${unsafe} — surgical edit refused`);
+  }
+  if (!(pair.value instanceof YAMLMap)) {
+    return noWrite(currentText, ownership, 'cleanup skipped: compaction is not a block mapping');
+  }
+
+  let installedCompaction;
+  try {
+    const data = YAML.parse(ownership.installedText);
+    if (!isPlainObject(data?.compaction)) {
+      return noWrite(currentText, ownership, 'cleanup skipped: installedText has no compaction mapping');
+    }
+    installedCompaction = data.compaction;
+  } catch (error) {
+    return noWrite(currentText, ownership, `cleanup skipped: installedText is not valid YAML — ${error?.message ?? error}`);
+  }
+
+  const originalCompaction = originalCompactionOf(ownership);
+  const eol = detectEol(currentText);
+  const edits = [];
+  let removedCount = 0;
+
+  for (const key of OWNED_COMPACTION_KEYS) {
+    if (!(key in installedCompaction)) continue;
+    const ownedPair = pair.value.items.find(
+      (item) => item.key instanceof Scalar && item.key.value === key,
+    );
+    if (!ownedPair || !(ownedPair.value instanceof Scalar)) continue;
+
+    const installedValue = installedCompaction[key];
+    if (!sameValue(ownedPair.value.value, installedValue)) continue; // user changed it — keep
+
+    const hasOriginal = originalCompaction !== null && key in originalCompaction;
+    if (!hasOriginal) {
+      // ukit added this key (fresh file or key absent pre-install): remove the
+      // whole line — from line start (node ranges begin after the indent) to
+      // the end of the value's line, including any trailing comment/break.
+      const start = lineStartBefore(currentText, ownedPair.key.range[0]);
+      const end = Math.max(ownedPair.value.range[2], lineEndAfter(currentText, ownedPair.value.range[1]));
+      edits.push({ start, end, replacement: '' });
+      removedCount += 1;
+    } else if (!sameValue(originalCompaction[key], installedValue)) {
+      // ukit changed a pre-existing value: restore the original one in place.
+      edits.push({
+        start: ownedPair.value.range[0],
+        end: ownedPair.value.range[1],
+        replacement: formatYamlValue(originalCompaction[key]),
+      });
+    }
+    // Originally present with the installed value: ukit never altered it — keep.
+  }
+
+  // If every remaining compaction entry was ukit-added and got removed, the
+  // `compaction:` parent line goes too (fresh files end up compaction-free
+  // again). Only the key's own line is removed — the child lines above were
+  // spliced by their own edits, and the map's range end already sits past the
+  // last child's newline, so extending further would swallow foreign lines.
+  if (removedCount > 0 && removedCount === pair.value.items.length) {
+    edits.push({
+      start: lineStartBefore(currentText, pair.key.range[0]),
+      end: lineEndAfter(currentText, pair.key.range[0]),
+      replacement: '',
+    });
+  }
+
+  if (edits.length === 0) {
+    return { text: currentText, ownership, warning: null };
+  }
+  return { text: applyEdits(currentText, edits), ownership, warning: null };
+}
+
+// --- task.agentCompactionThresholdOverrides (per-agent soft compaction targets) ---
+// Same ownership rule as the compaction keys: an agent entry is removed (or restored)
+// only when it still carries the value UKit installed; user-set values and every other
+// `task` key stay. Empty parents UKit created are removed with their last child.
+function taskOverridesOf(text) {
+  try {
+    const data = YAML.parse(text);
+    const map = data?.task?.agentCompactionThresholdOverrides;
+    return isPlainObject(map) ? map : null;
+  } catch {
+    return null;
+  }
+}
+
+function cleanupTaskOverrides(currentText, ownership) {
+  const installed = taskOverridesOf(ownership.installedText);
+  if (!installed) return currentText;
+  let doc;
+  try {
+    doc = parseDocOrThrow(currentText, 'current omp project config');
+  } catch {
+    return currentText;
+  }
+  if (!(doc.contents instanceof YAMLMap)) return currentText;
+  const taskPair = doc.contents.items.find((p) => p.key instanceof Scalar && p.key.value === 'task');
+  if (!taskPair || !(taskPair.value instanceof YAMLMap) || unsafeReason(taskPair)) return currentText;
+  const ovPair = taskPair.value.items.find((p) => p.key instanceof Scalar && p.key.value === 'agentCompactionThresholdOverrides');
+  if (!ovPair || !(ovPair.value instanceof YAMLMap)) return currentText;
+  const original = taskOverridesOf(typeof ownership.originalText === 'string' ? ownership.originalText : '') ?? {};
+  const edits = [];
+  let removed = 0;
+  for (const [agent, value] of Object.entries(installed)) {
+    const entry = ovPair.value.items.find((p) => p.key instanceof Scalar && p.key.value === agent);
+    if (!entry || !(entry.value instanceof Scalar) || entry.value.value !== value) continue;
+    if (!(agent in original)) {
+      const start = lineStartBefore(currentText, entry.key.range[0]);
+      const end = Math.max(entry.value.range[2], lineEndAfter(currentText, entry.value.range[1]));
+      edits.push({ start, end, replacement: '' });
+      removed += 1;
+    } else if (original[agent] !== value) {
+      edits.push({ start: entry.value.range[0], end: entry.value.range[1], replacement: formatYamlValue(original[agent]) });
+    }
+  }
+  if (removed > 0 && removed === ovPair.value.items.length) {
+    edits.push({ start: lineStartBefore(currentText, ovPair.key.range[0]), end: lineEndAfter(currentText, ovPair.key.range[0]), replacement: '' });
+    if (taskPair.value.items.length === 1) {
+      edits.push({ start: lineStartBefore(currentText, taskPair.key.range[0]), end: lineEndAfter(currentText, taskPair.key.range[0]), replacement: '' });
+    }
+  }
+  return edits.length > 0 ? applyEdits(currentText, edits) : currentText;
+}
+
+export function cleanupOmpProjectConfig(currentText, ownership) {
+  const result = cleanupCompaction(currentText, ownership);
+  if (
+    typeof currentText !== 'string'
+    || !isPlainObject(ownership)
+    || typeof ownership.installedText !== 'string'
+    || currentText === ownership.installedText
+    || typeof result.text !== 'string'
+  ) {
+    return result;
+  }
+  const text = cleanupTaskOverrides(result.text, ownership);
+  return text === result.text ? result : { ...result, text };
+}

package/src/core/runInstallPipeline.js

@@ -432,7 +432,14 @@ export async function runInstallPipeline({
     });
   }
 
-  const diffResults = await diffInstallPlan(plan);
+  // Ownership proof for .omp/config.yml: the ledger record, or — for installs that
+  // predate it — a synthetic proof that UKit shipped the legacy 350000 default
+  // (only when UKit tracked the file). Never touches the user's other values.
+  const trackedOmpConfig = (Array.isArray(installMetaData?.files) ? installMetaData.files : [])
+    .some((e) => (typeof e === 'string' ? e : e?.p) === '.omp/config.yml');
+  const ompOwnership = installMetaData?.ompConfigOwnership
+    ?? (trackedOmpConfig ? { originalText: null, installedText: 'compaction:\n  thresholdTokens: 350000\n' } : null);
+  const diffResults = await diffInstallPlan(plan, { ompOwnership });
   const plannedSummary = summarizeDiff(diffResults);
 
   if (!dryRun) {
@@ -441,6 +448,22 @@ export async function runInstallPipeline({
       projectRoot: pathConfig.projectRoot,
     });
 
+    for (const entry of diffResults) {
+      const parseError = entry?.migrationReport?.parseError;
+      if (!parseError || !/\.omp\/config\.yml$/.test(String(entry.targetPath).replace(/\\/g, '/'))) continue;
+      console.warn(`[UKit] Warning: .omp/config.yml was left untouched (cannot merge: ${parseError}). Fix the YAML and rerun \`ukit install\` to apply UKit's OMP settings.`);
+    }
+
+    let ompConfigOwnership = null;
+    for (const entry of diffResults) {
+      if (!entry.ompOwnership) continue;
+      if (entry.ompOwnershipWarning) console.warn(`[UKit] .omp/config.yml: ${entry.ompOwnershipWarning}`);
+      if (entry.action === 'create' || entry.action === 'update' || entry.action === 'unchanged') {
+        const written = writes.some((w) => w.targetPath === entry.targetPath);
+        if (written || entry.action === 'unchanged') ompConfigOwnership = entry.ompOwnership;
+      }
+    }
+
     // SPEC §7 step 9: surface the .omp/config.yml unattended migration result.
     for (const entry of diffResults) {
       const report = entry?.migrationReport;
@@ -522,6 +545,7 @@ export async function runInstallPipeline({
       projectRoot: pathConfig.projectRoot,
       managedRelativePaths: [...trackedManagedRelativePaths],
       retainedManagedRelativePaths,
+      ompConfigOwnership,
     });
 
     // 3.3.0: hooks spawn the CLI (episodes, self-improve) from a GUI-launched

package/src/core/uninstall.js

@@ -9,6 +9,7 @@ import {
   resolveProjectRelativePath,
 } from './fileOps.js';
 import { readInstallMetadata } from './metadata.js';
+import { cleanupOmpProjectConfig } from './ompProjectConfig.js';
 import { removeGitignoreBlock } from './ensureGitignore.js';
 import { PROJECT_IMPORTANT_FILENAME } from './projectImportant.js';
 
@@ -424,6 +425,29 @@ export async function uninstallUkit({ projectRoot, dryRun = false }) {
   }
 
 
+  // .omp/config.yml is user-shared: revert only what UKit owns instead of deleting it.
+  const ompConfigAbs = path.join(projectRoot, '.omp', 'config.yml');
+  let ompConfigRewrite = null;
+  const ompIdx = regularPaths.findIndex((p) => p.abs === ompConfigAbs);
+  if (ompIdx !== -1) {
+    const currentText = await fs.readFile(ompConfigAbs, 'utf8').catch(() => null);
+    if (currentText !== null) {
+      let outcome;
+      try {
+        outcome = cleanupOmpProjectConfig(currentText, installData.ompConfigOwnership ?? null);
+      } catch (error) {
+        outcome = { text: currentText, warning: `cleanup skipped: ${error?.message ?? error}` };
+      }
+      if (outcome.warning) {
+        console.warn(`[UKit] .omp/config.yml kept: ${outcome.warning}`);
+      }
+      if (outcome.text !== null) {
+        regularPaths.splice(ompIdx, 1); // not deleted: rewritten (or kept) below
+        if (outcome.text !== currentText) ompConfigRewrite = outcome.text;
+      }
+    }
+  }
+
   const allEntries = [
     ...regularPaths.map(({ abs, recursive }) => ({ abs, useLink: false, recursive })),
     ...linkPaths.map((abs) => ({ abs, useLink: true, recursive: false })),
@@ -485,7 +509,10 @@ export async function uninstallUkit({ projectRoot, dryRun = false }) {
     backupPaths.push(importantPlan.backupPath); // existing byte-identical backup
   }
 
-  // Remove all paths in parallel
+  if (ompConfigRewrite !== null) {
+    await fs.writeFile(ompConfigAbs, ompConfigRewrite, 'utf8');
+  }
+
   // Remove all paths in parallel. Tracked file entries use removeFileOrLinkOnly:
   // a real directory at a tracked path is user content (the user replaced the
   // managed file) and is refused — same protection link entries already had.

package/src/render/buildVariables.js

@@ -1,5 +1,8 @@
 import { loadShippedCompactBudget } from '../core/compact/contextBudget.js';
 
+// Starting omp compaction threshold; capped by the shared auto-compact window above.
+const OMP_COMPACTION_THRESHOLD_TOKENS = 90_000;
+
 const CODEGRAPH_SECTION = `
 ## CodeGraph Integration (active)
 
@@ -76,6 +79,7 @@ export function buildTemplateVariables({ projectContext, stackContext, packageVe
     },
     omp: {
       evalApproval,
+      compactionThresholdTokens: String(Math.min(OMP_COMPACTION_THRESHOLD_TOKENS, autoCompactWindow)),
     },
     codegraphSection: withCodegraph ? CODEGRAPH_SECTION : '',
   };

package/template_project/.claude/hooks/handoff-model-guard.sh

@@ -135,6 +135,12 @@ if printf '%s' "$INPUT" | grep -qE '"tool_name"[[:space:]]*:[[:space:]]*"(Agent|
   && printf '%s' "$INPUT" | grep -qE 'TASK-([Cc][0-9]+-)?[0-9]+'; then
   TASK_CLAIM_RUN=1
 fi
+# Adaptive task-graph pre-filter: a delegation tagged [ukit-subtask <id>] needs the dependency gate.
+SUBTASK_RUN=0
+if printf '%s' "$INPUT" | grep -qE '"tool_name"[[:space:]]*:[[:space:]]*"(Agent|Task)"' \
+  && printf '%s' "$INPUT" | grep -qF '[ukit-subtask '; then
+  SUBTASK_RUN=1
+fi
 # Main-agent ownership pre-filter: a source Edit/Write only needs the node gate while a
 # handoff-fullstack run sits in an implement phase (cheap RUN.md grep, no node spawn otherwise).
 MAIN_OWNER_RUN=0
@@ -142,11 +148,11 @@ if printf '%s' "$INPUT" | grep -qE '"tool_name"[[:space:]]*:[[:space:]]*"(Edit|W
   && grep -qE '^Phase:[[:space:]]*I[1-4]\b' "$PROJECT_ROOT/docs/AI_HANDOFF/RUN.md" 2>/dev/null; then
   MAIN_OWNER_RUN=1
 fi
-if [ "$CREATE_SCOPE_RUN" != 1 ] && [ "$TASK_CLAIM_RUN" != 1 ] && [ "$MAIN_OWNER_RUN" != 1 ] && ! printf '%s' "$INPUT" | grep -qE 'AI_HANDOFF|git[[:space:]]+push'; then
+if [ "$CREATE_SCOPE_RUN" != 1 ] && [ "$TASK_CLAIM_RUN" != 1 ] && [ "$SUBTASK_RUN" != 1 ] && [ "$MAIN_OWNER_RUN" != 1 ] && ! printf '%s' "$INPUT" | grep -qE 'AI_HANDOFF|git[[:space:]]+push'; then
   exit 0
 fi
 
-INPUT_FILE="$UKIT_INPUT_FILE" PROJECT_ROOT="$PROJECT_ROOT" CREATE_SCOPE_RUN="$CREATE_SCOPE_RUN" TASK_CLAIM_RUN="$TASK_CLAIM_RUN" HOOK_DIR="$SCRIPT_DIR" node <<'NODE'
+INPUT_FILE="$UKIT_INPUT_FILE" PROJECT_ROOT="$PROJECT_ROOT" CREATE_SCOPE_RUN="$CREATE_SCOPE_RUN" TASK_CLAIM_RUN="$TASK_CLAIM_RUN" SUBTASK_RUN="$SUBTASK_RUN" HOOK_DIR="$SCRIPT_DIR" node <<'NODE'
 const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10) || 3000;
 // SPEC §8: a timed-out gate silently passes work it never evaluated — announce the
 // degrade (fail-open posture kept: still exit 0).
@@ -793,6 +799,35 @@ async function taskClaimGate() {
 }
 await taskClaimGate();
 
+// Adaptive-decomposition task graph: a delegation tagged `[ukit-subtask <id>]` is dispatched only
+// when its dependencies are done and it is neither running nor already done (resume never
+// re-dispatches finished work). Untagged delegations and IO trouble pass through untouched.
+async function subtaskGate() {
+  if (process.env.SUBTASK_RUN !== '1' || toolName !== 'Agent' && toolName !== 'Task') return;
+  try {
+    const dispatch = await import(require('url').pathToFileURL(path.resolve(process.env.HOOK_DIR || '.', '../ukit/runtime/plan-dispatch.mjs')).href);
+    const subtaskId = dispatch.subtaskIdFromInput(input);
+    if (!subtaskId) return;
+    const verdict = await dispatch.dispatchSubtask(projectRoot, subtaskId, input);
+    if (verdict.ok) {
+      const b = verdict.budget;
+      if (b && (b.status === 'over-soft-budget' || b.status === 'over-cost-boundary')) {
+        process.on('exit', (code) => {
+          if (code !== 0) return;
+          try { fs.writeSync(1, `${JSON.stringify({ systemMessage: `UKit: subtask ${subtaskId} scoped context (over the ${b.role} soft budget of ${b.softBudget} tokens) — consider splitting it further. Advisory only; dispatch proceeds.` })}\n`); } catch {}
+        });
+      }
+      return;
+    }
+    const why = verdict.reason === 'deps-pending' ? `dependencies not done yet: ${(verdict.missing || []).join(', ')}`
+      : verdict.reason === 'already-done' ? 'it is already done (resume never re-dispatches completed subtasks)'
+        : verdict.reason === 'already-running' ? 'it is already running'
+          : verdict.reason;
+    block(`Subtask ${subtaskId} not dispatched: ${why}. Dispatch the ready subtasks first (see the route "plan:" lines); integrate last.`);
+  } catch { /* fail-open on IO trouble */ }
+}
+await subtaskGate();
+
 // Main-agent task ownership. handoff-fullstack contracts implementation to claim-bearing
 // executor subagents ("Do NOT implement the tasks yourself in the current session"). The
 // delegation path is claim-gated above; this closes the direct path: while a run is in an

package/template_project/.claude/hooks/record-execution.mjs

@@ -53,6 +53,15 @@ async function releaseDelegatedClaims(payload, projectRoot) {
       await mod.renewSessionClaims(projectRoot, String(payload.session_id));
     }
     if (payload.tool_name !== 'Agent' && payload.tool_name !== 'Task') return;
+    try {
+      const dispatch = await import(pathToFileURL(path.join(MODULE_DIR, '..', 'ukit', 'runtime', 'plan-dispatch.mjs')).href);
+      const subtaskId = dispatch.subtaskIdFromInput(payload.tool_input);
+      if (subtaskId) {
+        const r = payload.tool_response ?? payload.tool_output ?? payload.tool_result ?? {};
+        const failed = [payload.is_error, r?.is_error, r?.isError, payload.tool_response?.isError].some((v) => v === true);
+        await dispatch.completeSubtask(projectRoot, subtaskId, { success: !failed });
+      }
+    } catch { /* advisory */ }
     const owner = mod.delegatedClaimOwner(payload);
     if (!owner) return;
     for (const { taskId } of mod.delegatedClaimTargets(payload.tool_input)) {