@ngockhoale/ukit 2.6.10 → 2.7.0

package/src/core/codeintel/retriever.js

@@ -1,5 +1,7 @@
 import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
 import path from 'node:path';
+import { createHash } from 'node:crypto';
 
 import { getArtifactPath, INDEX_ARTIFACTS, INDEX_SCHEMA_VERSION, normalizeRelative } from '../../index/paths.js';
 import { loadRuntimeConfig } from '../runtimeConfig.js';
@@ -260,6 +262,55 @@ function concatMerge(lanes) {
   return merged;
 }
 
+// FR-202b (TASK-228): fire-and-forget lane telemetry. One JSONL line per
+// retrieval at .ukit/storage/cache/retriever-lanes.jsonl; query persisted as
+// sha256 only (no raw prompts on disk). Failures are swallowed — telemetry
+// must never break retrieve(). Sync writes keep the fire-and-forget contract
+// deterministic for callers/tests.
+const RETRIEVER_LANES_MAX_BYTES = 256 * 1024;
+const RETRIEVER_LANES_KEEP_LINES = 2000;
+
+function emitRetrieverLaneTelemetry(rootDir, { query, mode, lanes, omitted, mergedPaths, merge, weights }) {
+  try {
+    const laneStats = {};
+    for (const laneName of LANE_ORDER) {
+      const lane = lanes.get(laneName);
+      const stat = {
+        hits: lane ? lane.length : 0,
+        weightUsed: weights?.[laneName] ?? 0,
+      };
+      const why = omitted?.find((o) => o?.what === `${laneName}-lane`)?.why;
+      if (!lane && why) stat.omitted = why;
+      if (lane) stat.paths = lane.map((entry) => entry.path).slice(0, 100);
+      laneStats[laneName] = stat;
+    }
+    const event = {
+      ts: Date.now(),
+      query: createHash('sha256').update(String(query ?? '')).digest('hex'),
+      mode,
+      lanes: laneStats,
+      mergedPaths,
+      merge,
+    };
+    const filePath = path.join(rootDir, '.ukit', 'storage', 'cache', 'retriever-lanes.jsonl');
+    fsSync.mkdirSync(path.dirname(filePath), { recursive: true });
+    // Best-effort cap: past 256 KiB keep only the newest ~2000 lines.
+    try {
+      const st = fsSync.statSync(filePath);
+      if (st.size > RETRIEVER_LANES_MAX_BYTES) {
+        const kept = fsSync.readFileSync(filePath, 'utf8').split('\n').filter(Boolean)
+          .slice(-RETRIEVER_LANES_KEEP_LINES);
+        fsSync.writeFileSync(filePath, kept.length ? `${kept.join('\n')}\n` : '');
+      }
+    } catch {
+      // Missing/unreadable file is fine — append below recreates it.
+    }
+    fsSync.appendFileSync(filePath, `${JSON.stringify(event)}\n`);
+  } catch {
+    // Telemetry is advisory; never propagate.
+  }
+}
+
 /**
  * retrieve(projectRoot, query, { mode, limit, snapshot, merge, weights }) →
  *   { anchors, evidence, relations, omitted }
@@ -384,6 +435,20 @@ export async function retrieve(projectRoot, query, { mode = 'search', limit, sna
     omitted.push({ what: 'anchors', why: 'no-match' });
   }
 
+  // FR-202b: emit lane telemetry only when a merge result exists — skipped
+  // entirely on the early no-index return and on empty merges.
+  if (merged.length > 0) {
+    emitRetrieverLaneTelemetry(rootDir, {
+      query: normalizedQuery,
+      mode,
+      lanes,
+      omitted,
+      mergedPaths: anchors.map((a) => a.path),
+      merge: effectiveMerge,
+      weights: effectiveWeights,
+    });
+  }
+
   const relations = [];
 
   // Impact mode — 1-hop reverse imports: who imports each anchor file.

package/src/core/diffPlan.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs/promises';
 import { isSymlinkTo } from './fileOps.js';
 import { GATEWAY_RESILIENCE_ENV_DEFAULTS } from './gatewayResilienceEnv.js';
+import { isOmpConfigTarget, mergeOmpConfig } from './ompConfigMerge.js';
 
 const GATEWAY_RESILIENCE_KEYS = new Set(Object.keys(GATEWAY_RESILIENCE_ENV_DEFAULTS));
 
@@ -116,6 +117,13 @@ function resolveFileAction(entry, existingContent) {
       : entry.mergeStrategy === 'skip'
         ? 'skip'
         : 'update';
+  } else if (isOmpConfigTarget(entry.targetPath) && typeof existingContent === 'string' && typeof entry.renderedContent === 'string') {
+    // 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);
+    action = merged.text === existingContent ? 'unchanged' : 'update';
+    return { ...entry, renderedContent: merged.text, migrationReport: merged.report, 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

package/src/core/memory/store.js

@@ -540,7 +540,8 @@ async function proposePatternCandidateV2(projectRoot, projectId, candidate) {
     .filter((record) => record.provenance === 'pattern-candidate'
       || String(record.provenance ?? '').includes('pattern-candidate'))
     .find((record) => record.meta?.legacyStatus === 'pending'
-      && normalizePatternText(record.text) === normalizedText);
+      && (normalizePatternText(record.text) === normalizedText
+        || (candidate?.signature && record.meta?.signature === candidate.signature)));
   if (existing) {
     return patternCandidateFromRecord(existing);
   }
@@ -553,6 +554,7 @@ async function proposePatternCandidateV2(projectRoot, projectId, candidate) {
     detectedAt: Date.now(),
     status: 'pending',
   };
+  if (candidate?.signature) entry.signature = candidate.signature;
 
   await v2.addRecord(projectRoot, {
     type: 'derived_fact',
@@ -626,7 +628,9 @@ export async function proposePatternCandidate(projectRoot, projectId, candidate)
 
   const patternCandidates = Array.isArray(memory.patternCandidates) ? memory.patternCandidates : [];
   const existingPending = patternCandidates.find(
-    (entry) => entry.status === 'pending' && normalizePatternText(entry.text) === normalizedText,
+    (entry) => entry.status === 'pending'
+      && (normalizePatternText(entry.text) === normalizedText
+        || (candidate?.signature && entry.signature === candidate.signature)),
   );
   if (existingPending) {
     return existingPending;
@@ -640,6 +644,7 @@ export async function proposePatternCandidate(projectRoot, projectId, candidate)
     detectedAt: Date.now(),
     status: 'pending',
   };
+  if (candidate?.signature) entry.signature = candidate.signature;
 
   memory.patternCandidates = [...patternCandidates, entry];
   await persistProjectMemoryWithHygiene(projectRoot, runtimePaths, projectId, filePath, memory);

package/src/core/ompConfigMerge.js

@@ -0,0 +1,222 @@
+import YAML from 'yaml';
+
+// TASK-010 / SPEC §5.2 + §7 (FR-006): semantic, comment-safe migration merge for
+// `.omp/config.yml`. Operates on the rendered template TEXT with surgical splices
+// so the template's load-bearing comments survive — a full YAML round-trip
+// (parse + stringify) would drop every comment.
+
+export const PRESERVED_MARKER = '# Preserved by UKit unattended migration (C35):';
+
+const OMP_CONFIG_SUFFIX = '.omp/config.yml';
+
+export function isOmpConfigTarget(targetPath) {
+  return typeof targetPath === 'string' && targetPath.replace(/\\/g, '/').endsWith(OMP_CONFIG_SUFFIX);
+}
+
+function emptyReport() {
+  return {
+    migrated: false,
+    legacyApprovalMode: null,
+    strippedPromptApprovals: [],
+    coercedPromptPatterns: [],
+    preservedModelRoles: false,
+    preservedTopLevelKeys: [],
+    preservedPatterns: [],
+    parseError: null,
+  };
+}
+
+// Extract a top-level scalar map's value span: the `key:` line plus following
+// lines that are indented or blank. Stops before the next non-indented,
+// non-blank line — comments preceding the next top-level key stay with it.
+function extractScalarMapSpan(lines, key) {
+  const start = lines.findIndex((line) => new RegExp(`^${key}:\\s*$`).test(line) || new RegExp(`^${key}:\\s`).test(line));
+  if (start === -1) return null;
+  let end = start + 1;
+  while (end < lines.length) {
+    const line = lines[end];
+    if (line.trim() === '' || /^\s/.test(line)) {
+      end += 1;
+    } else {
+      break;
+    }
+  }
+  // Trim trailing blank lines out of the span — they belong to the gap before
+  // the next key, not to this block.
+  let blockEnd = end;
+  while (blockEnd > start + 1 && lines[blockEnd - 1].trim() === '') {
+    blockEnd -= 1;
+  }
+  return { start, end: blockEnd, lines: lines.slice(start, blockEnd) };
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+// Indent every line of a YAML fragment by `indent` spaces.
+function indentFragment(fragment, indent) {
+  const pad = ' '.repeat(indent);
+  return fragment
+    .split('\n')
+    .filter((line) => line !== '')
+    .map((line) => pad + line);
+}
+
+export function mergeOmpConfig(existingText, renderedText) {
+  const report = emptyReport();
+
+  let existing;
+  try {
+    existing = YAML.parse(existingText);
+  } catch (error) {
+    report.parseError = error?.message ?? String(error);
+    return { text: renderedText, report };
+  }
+  if (!isPlainObject(existing)) {
+    report.parseError = 'existing .omp/config.yml did not parse to a mapping';
+    return { text: renderedText, report };
+  }
+
+  let rendered;
+  try {
+    rendered = YAML.parse(renderedText);
+  } catch (error) {
+    // A broken template is not a migration problem — surface it as parseError so
+    // the caller falls back to plain overwrite rather than crashing install.
+    report.parseError = `rendered template failed to parse: ${error?.message ?? error}`;
+    return { text: renderedText, report };
+  }
+
+  const existingTools = isPlainObject(existing.tools) ? existing.tools : {};
+  const existingApproval = isPlainObject(existingTools.approval) ? existingTools.approval : {};
+  const renderedApproval = isPlainObject(rendered?.tools?.approval) ? rendered.tools.approval : {};
+
+  report.legacyApprovalMode = typeof existingTools.approvalMode === 'string'
+    ? existingTools.approvalMode
+    : null;
+
+  // §7.2 — user-defined tools.approval.<k> keys absent from the canonical map:
+  // preserved only when allow|deny; every `prompt` value (canonical or custom)
+  // is recorded in strippedPromptApprovals.
+  const extraApprovalEntries = [];
+  for (const [key, value] of Object.entries(existingApproval)) {
+    if (value === 'prompt') {
+      report.strippedPromptApprovals.push(key);
+      continue;
+    }
+    if (!(key in renderedApproval) && (value === 'allow' || value === 'deny')) {
+      extraApprovalEntries.push([key, value]);
+    }
+  }
+
+  // §7.4 — bash.patterns union: existing-only entries (dedupe by match) appended
+  // before the trailing `- match: "*"` allow; `prompt` re-emitted as `deny`.
+  const existingPatterns = Array.isArray(existing?.bash?.patterns) ? existing.bash.patterns : [];
+  const renderedPatterns = Array.isArray(rendered?.bash?.patterns) ? rendered.bash.patterns : [];
+  const renderedMatches = new Set(renderedPatterns.map((p) => p?.match));
+  const extraPatterns = [];
+  for (const pattern of existingPatterns) {
+    if (!isPlainObject(pattern) || typeof pattern.match !== 'string') continue;
+    if (renderedMatches.has(pattern.match)) continue;
+    let approval = pattern.approval;
+    if (approval === 'prompt') {
+      approval = 'deny';
+      report.coercedPromptPatterns.push(pattern.match);
+    }
+    extraPatterns.push({ ...pattern, approval });
+    report.preservedPatterns.push(pattern.match);
+  }
+
+  // §7.6 — extra top-level keys absent from the rendered template.
+  const extraTopLevel = {};
+  if (isPlainObject(rendered)) {
+    for (const [key, value] of Object.entries(existing)) {
+      if (!(key in rendered)) {
+        extraTopLevel[key] = value;
+        report.preservedTopLevelKeys.push(key);
+      }
+    }
+  }
+
+  const lines = renderedText.split('\n');
+
+  // §7.3 — modelRoles block splice: replace the rendered `modelRoles:` scalar
+  // map span with the existing span (maintainer edits for non-UNIC providers).
+  const renderedRoles = extractScalarMapSpan(lines, 'modelRoles');
+  const existingLines = existingText.split('\n');
+  const existingRoles = extractScalarMapSpan(existingLines, 'modelRoles');
+  if (renderedRoles && existingRoles && isPlainObject(existing.modelRoles)) {
+    lines.splice(renderedRoles.start, renderedRoles.end - renderedRoles.start, ...existingRoles.lines);
+    report.preservedModelRoles = true;
+  }
+
+  // §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) {
+    const approvalStart = lines.findIndex((line) => /^\s+approval:\s*$/.test(line));
+    if (approvalStart !== -1) {
+      const baseIndent = lines[approvalStart].match(/^\s*/)[0].length;
+      let insertAt = approvalStart + 1;
+      while (insertAt < lines.length) {
+        const line = lines[insertAt];
+        if (line.trim() === '') {
+          insertAt += 1;
+          continue;
+        }
+        const indent = line.match(/^\s*/)[0].length;
+        if (indent <= baseIndent) break;
+        insertAt += 1;
+      }
+      const fragment = extraApprovalEntries.map(([k, v]) => `${' '.repeat(baseIndent + 2)}${k}: ${v}`);
+      lines.splice(insertAt, 0, ...fragment);
+    }
+  }
+
+  // §7.4 splice — insert preserved patterns before the trailing `- match: "*"`
+  // allow (or at the end of the patterns list if no wildcard exists).
+  if (extraPatterns.length > 0) {
+    // YAML.stringify emits sequence items at column 0; preserve each line's
+    // relative indentation and shift the whole fragment to the list's indent.
+    const rawFragment = YAML.stringify(extraPatterns).trimEnd().split('\n');
+    const wildcardIdx = lines.findIndex((line) => /- match: ["']?\*["']?\s*$/.test(line));
+    if (wildcardIdx !== -1) {
+      const itemIndent = lines[wildcardIdx].match(/^\s*/)[0].length;
+      lines.splice(wildcardIdx, 0, ...rawFragment.map((line) => ' '.repeat(itemIndent) + line));
+    } else {
+      const patternsStart = lines.findIndex((line) => /^\s+patterns:\s*$/.test(line));
+      if (patternsStart !== -1) {
+        const baseIndent = lines[patternsStart].match(/^\s*/)[0].length;
+        let insertAt = patternsStart + 1;
+        while (insertAt < lines.length) {
+          const line = lines[insertAt];
+          if (line.trim() === '') {
+            insertAt += 1;
+            continue;
+          }
+          const indent = line.match(/^\s*/)[0].length;
+          if (indent <= baseIndent) break;
+          insertAt += 1;
+        }
+        const itemIndent = baseIndent + 2;
+        lines.splice(insertAt, 0, ...rawFragment.map((line) => ' '.repeat(itemIndent) + line));
+      }
+    }
+  }
+
+  // §7.6 splice — append extra top-level keys under the preserved marker.
+  if (report.preservedTopLevelKeys.length > 0) {
+    const fragment = YAML.stringify(extraTopLevel).trimEnd().split('\n');
+    let end = lines.length;
+    while (end > 0 && lines[end - 1].trim() === '') end -= 1;
+    lines.splice(end, lines.length - end, '', PRESERVED_MARKER, ...fragment, '');
+  }
+
+  const text = lines.join('\n');
+  // "migrated" = the merge changed anything relative to what is on disk —
+  // includes the approval-surface rewrite itself (legacy approvalMode, prompt
+  // values) even when no user region needed splicing.
+  report.migrated = text !== existingText;
+
+  return { text, report };
+}

package/src/core/runInstallPipeline.js

@@ -310,6 +310,17 @@ export async function runInstallPipeline({
       projectRoot: pathConfig.projectRoot,
     });
 
+    // SPEC §7 step 9: surface the .omp/config.yml unattended migration result.
+    for (const entry of diffResults) {
+      const report = entry?.migrationReport;
+      if (!report?.migrated) continue;
+      const removed = (report.strippedPromptApprovals?.length ?? 0) + (report.coercedPromptPatterns?.length ?? 0);
+      const preserved = (report.preservedModelRoles ? 1 : 0)
+        + (report.preservedTopLevelKeys?.length ?? 0)
+        + (report.preservedPatterns?.length ?? 0);
+      console.log(`[UKit] .omp/config.yml: migrated approval surface (prompt→removed: ${removed}, preserved: ${preserved})`);
+    }
+
     // BUG-C22-19: bound the .bak accumulation — every overwrite_with_backup write
     // adds one and nothing removed them. Advisory: a prune failure must never
     // fail the install.

package/src/core/runtimeConfig.js

@@ -12,6 +12,10 @@ const { version: PACKAGE_VERSION } = require('../../package.json');
 // config.json naming it must not become invalid.
 const VALID_AGENTS = new Set(['claude-code', 'codex', 'antigravity', 'opencode', 'omp']);
 
+// Reserved permission modes for orchestration.permissionMode (single source of truth).
+// 'unattended' is the only mode implemented this cycle; interactive/safe-auto are reserved.
+export const VALID_PERMISSION_MODES = new Set(['interactive', 'safe-auto', 'unattended']);
+
 const BLOCKED_MERGE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
 
 function isPlainObject(value) {
@@ -137,6 +141,7 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       enabled: true,
       orchestratorModel: 'claude-sonnet-5',
       advisorEnabled: true,
+      permissionMode: 'unattended',
       contracts: buildConfigContracts(),
       modelTiers: {
         lite: { claudeModel: 'claude-haiku-4-5', genericModel: 'unic-lite' },
@@ -209,6 +214,14 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       maxRetries: 1,
       confidenceThreshold: 50,
     },
+    // Phase-4 learning loop (SPEC §8a). Advisory only — applyMode 'manual'
+    // means suggestions are computed + persisted, never auto-applied.
+    learning: {
+      feedback: { enabled: true, maxEvents: 200 },
+      proposals: { minCount: 3, minSessions: 2 },
+      episodes: { autoWrite: false },
+      tuning: { enabled: true, applyMode: 'manual' },
+    },
     safePatch: {
       enabled: true,
       strictSharedRisk: true,
@@ -385,6 +398,12 @@ export function validateRuntimeConfig(config) {
     pushBooleanError(errors, config.orchestration.enabled, 'orchestration.enabled');
     pushNonEmptyStringError(errors, config.orchestration.orchestratorModel, 'orchestration.orchestratorModel');
     pushBooleanError(errors, config.orchestration.advisorEnabled, 'orchestration.advisorEnabled');
+    // permissionMode is optional-present: absent → tolerated (pre-C35 configs);
+    // present → must be a reserved mode.
+    if (config.orchestration.permissionMode !== undefined
+      && !VALID_PERMISSION_MODES.has(config.orchestration.permissionMode)) {
+      errors.push(`orchestration.permissionMode must be one of: ${[...VALID_PERMISSION_MODES].join(', ')}.`);
+    }
     if (!isPlainObject(config.orchestration.contracts)) {
       errors.push('orchestration.contracts must be an object.');
     }
@@ -564,6 +583,51 @@ export function validateRuntimeConfig(config) {
     pushPositiveNumberError(errors, config.safePatch.deltaMaxDiffCells, 'safePatch.deltaMaxDiffCells');
   }
 
+  // learning is optional-present: absent → valid (old configs); present but
+  // not an object → error. Per-key checks apply only when the sub-object
+  // exists, so partial learning blocks stay valid via defaults merge.
+  if (config.learning !== undefined) {
+    if (!isPlainObject(config.learning)) {
+      errors.push('learning must be an object.');
+    } else {
+      const learning = config.learning;
+      if (learning.feedback !== undefined) {
+        if (!isPlainObject(learning.feedback)) {
+          errors.push('learning.feedback must be an object.');
+        } else {
+          pushBooleanError(errors, learning.feedback.enabled, 'learning.feedback.enabled');
+          pushPositiveNumberError(errors, learning.feedback.maxEvents, 'learning.feedback.maxEvents');
+        }
+      }
+      if (learning.proposals !== undefined) {
+        if (!isPlainObject(learning.proposals)) {
+          errors.push('learning.proposals must be an object.');
+        } else {
+          pushPositiveNumberError(errors, learning.proposals.minCount, 'learning.proposals.minCount');
+          pushPositiveNumberError(errors, learning.proposals.minSessions, 'learning.proposals.minSessions');
+        }
+      }
+      if (learning.episodes !== undefined) {
+        if (!isPlainObject(learning.episodes)) {
+          errors.push('learning.episodes must be an object.');
+        } else {
+          pushBooleanError(errors, learning.episodes.autoWrite, 'learning.episodes.autoWrite');
+        }
+      }
+      if (learning.tuning !== undefined) {
+        if (!isPlainObject(learning.tuning)) {
+          errors.push('learning.tuning must be an object.');
+        } else {
+          pushBooleanError(errors, learning.tuning.enabled, 'learning.tuning.enabled');
+          const VALID_APPLY_MODES = new Set(['manual', 'off']);
+          if (!VALID_APPLY_MODES.has(learning.tuning.applyMode)) {
+            errors.push(`learning.tuning.applyMode must be one of: ${[...VALID_APPLY_MODES].join(', ')}.`);
+          }
+        }
+      }
+    }
+  }
+
   if (!isPlainObject(config.subagents)) {
     errors.push('subagents must be an object.');
   } else {