@ngockhoale/ukit 2.6.11 → 2.7.1

package/src/cli/commands/doctor.js

@@ -23,6 +23,7 @@ import {
   inspectProjectImportantWiring,
 } from '../../core/projectImportant.js';
 import { runDocContractChecks } from '../../core/docContracts.js';
+import { inspectUnattendedMode } from '../../core/unattendedDoctor.js';
 
 export const DOCTOR_HELP_FLAGS = new Set(['--help', '-h']);
 const KNOWN_FLAGS = new Set([...DOCTOR_HELP_FLAGS, '--skills', '--gateway', '--docs']);
@@ -40,7 +41,7 @@ export function printDoctorHelp() {
   console.log('  --docs          Run doc-contract checks (manifests/documentation.yaml projects only)');
 }
 
-export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir = os.homedir() }) {
+export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir = os.homedir(), ompPath = 'omp' }) {
   const unknownFlags = argv.filter((flag) => !KNOWN_FLAGS.has(flag));
   if (unknownFlags.length > 0) {
     throw new Error(`Unknown option: ${unknownFlags[0]}. Supported: ${SUPPORTED_FLAGS_LIST}`);
@@ -254,6 +255,20 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir =
     console.log(`[UKit]   ${ok(check.passed)}  ${check.label}`);
   }
 
+  // TASK-011 / SPEC §8 (FR-007): unattended-mode checks — same remediation-class
+  // shape as projectChecks; install-repairable/owner-action failures block the
+  // exit code, advisory never does.
+  const unattended = await inspectUnattendedMode({ projectRoot, ompPath });
+  console.log('[UKit] Unattended-mode checks:');
+  for (const check of unattended.checks) {
+    if (check.applicable === false) continue;
+    console.log(`[UKit]   ${ok(check.passed)}  ${check.label}`);
+    if (check.detail) console.log(`[UKit]      detail: ${check.detail}`);
+    if (!check.passed && check.remedy) {
+      console.log(`[UKit]      remedy: ${check.remedy}`);
+    }
+  }
+
   if (runtimeConfigInspection.errors.length > 0) {
     console.log(`[UKit] Runtime config issues: ${runtimeConfigInspection.errors.join(' | ')}`);
   }
@@ -402,13 +417,17 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir =
   const failedProjectChecks = projectChecks.filter(
     (check) => check.applicable !== false && !check.passed,
   );
-  const blockingFailures = failedProjectChecks.filter(
+  const failedUnattendedChecks = unattended.checks.filter(
+    (check) => check.applicable !== false && !check.passed,
+  );
+  const allFailedChecks = [...failedProjectChecks, ...failedUnattendedChecks];
+  const blockingFailures = allFailedChecks.filter(
     (check) => check.remediationClass === 'install-repairable' || check.remediationClass === 'owner-action',
   );
 
-  if (failedProjectChecks.length > 0) {
+  if (allFailedChecks.length > 0) {
     console.log('[UKit] Remedies:');
-    for (const check of failedProjectChecks) {
+    for (const check of allFailedChecks) {
       console.log(`[UKit]   - [${check.remediationClass}] ${check.remedy}`);
     }
   }

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/ompConfigMerge.js

@@ -0,0 +1,251 @@
+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,
+    addedModelRoleKeys: [],
+    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 / FR-004 — modelRoles per-key union: existing entries win verbatim,
+  // rendered keys absent from existing are appended (rendered order) so new
+  // template roles (e.g. smol/default/slow) reach pre-existing installs while
+  // user-owned roles and overrides survive. The block is regenerated via
+  // YAML.stringify under `modelRoles:`; rendered header comments above the
+  // `modelRoles:` line are untouched. Known limitation: comments *inside* the
+  // existing modelRoles block are dropped — values are preserved, comment
+  // text is not (SPEC §10).
+  const renderedRoles = extractScalarMapSpan(lines, 'modelRoles');
+  if (renderedRoles && isPlainObject(existing.modelRoles)) {
+    const merged = { ...existing.modelRoles };
+    const renderedMap = isPlainObject(rendered?.modelRoles) ? rendered.modelRoles : {};
+    for (const [key, value] of Object.entries(renderedMap)) {
+      if (!(key in merged)) {
+        merged[key] = value;
+        report.addedModelRoleKeys.push(key);
+      }
+    }
+    // Skip regeneration when existing contributed nothing the rendered block
+    // doesn't already state — identical keys and values means the rendered
+    // block (interior comments included) already IS the merged result.
+    // Regenerating here would byte-shift installs whose file matches the
+    // template and break install idempotency.
+    const renderedKeys = Object.keys(renderedMap);
+    const mergedKeys = Object.keys(merged);
+    const identicalToRendered =
+      mergedKeys.length === renderedKeys.length &&
+      mergedKeys.every((k) => k in renderedMap && merged[k] === renderedMap[k]);
+    if (!identicalToRendered) {
+      const fragment = YAML.stringify(merged, { indent: 2 })
+        .trimEnd()
+        .split('\n')
+        .map((line) => `  ${line}`);
+      lines.splice(renderedRoles.start, renderedRoles.end - renderedRoles.start, 'modelRoles:', ...fragment);
+      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,14 +141,17 @@ 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' },
-        code: { claudeModel: 'claude-sonnet-5', genericModel: 'unic-code' },
-        smart: { claudeModel: 'claude-opus-5', genericModel: 'unic-smart' },
+        // ompRole is the .omp/config.yml modelRoles key this tier binds to.
+        lite: { claudeModel: 'claude-haiku-4-5', genericModel: 'unic-lite', ompRole: 'smol' },
+        code: { claudeModel: 'claude-sonnet-5', genericModel: 'unic-code', ompRole: 'default' },
+        smart: { claudeModel: 'claude-opus-5', genericModel: 'unic-smart', ompRole: 'slow' },
         vision: {
           claudeModel: 'unic-vision',
           genericModel: 'unic-vision',
+          ompRole: 'vision',
           fallbackModel: 'claude-sonnet-5',
           capabilityTier: true,
           note: 'Capability tier, not a cost tier. Orthogonal to lite/code/smart — never insert into escalation.tierOrder. fallbackModel is used when unicMode is off.',
@@ -393,6 +400,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.');
     }

package/src/core/unattendedDoctor.js

@@ -0,0 +1,227 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { parse } from 'yaml';
+import { pathExists, readJsonIfExists } from './fileOps.js';
+import { VALID_PERMISSION_MODES } from './runtimeConfig.js';
+
+// TASK-011 / SPEC §8 — unattended-mode doctor checks (FR-007).
+// Seven checks, each returning the projectChecks remediation-class shape:
+// { label, passed, applicable?, failed, remediationClass, remedy, detail? }
+// remediationClass ∈ install-repairable | owner-action | advisory.
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const INSTALL_REPAIR = 'Run ukit install';
+const OMP_CONFIG_TIMEOUT_MS = 5000;
+const COMPLETION_LOOP_HEADER = '## Unattended Completion Loop';
+
+async function readOmpConfig(projectRoot) {
+  const configPath = path.join(projectRoot, '.omp', 'config.yml');
+  try {
+    const text = await fs.readFile(configPath, 'utf8');
+    const parsed = parse(text);
+    return { exists: true, parsed: parsed && typeof parsed === 'object' ? parsed : {}, parseError: null };
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { exists: false, parsed: null, parseError: null };
+    return { exists: true, parsed: null, parseError: error?.message ?? String(error) };
+  }
+}
+
+const ANSI_PATTERN = /\u001b\[[0-9;]*m/g;
+
+function execOmpConfigGet(projectRoot, ompPath) {
+  return new Promise((resolve) => {
+    execFile(
+      ompPath,
+      ['config', 'get', 'tools.approvalMode'],
+      { cwd: projectRoot, timeout: OMP_CONFIG_TIMEOUT_MS },
+      (error, stdout) => {
+        if (error) {
+          resolve({ ok: false, value: null });
+          return;
+        }
+        const value = String(stdout ?? '').replace(ANSI_PATTERN, '').trim();
+        resolve({ ok: value.length > 0, value: value || null });
+      },
+    );
+  });
+}
+
+async function readTemplateDenyMatches() {
+  try {
+    const text = await fs.readFile(path.join(PACKAGE_ROOT, 'templates', '.omp', 'config.yml'), 'utf8');
+    const parsed = parse(text);
+    const patterns = parsed?.bash?.patterns;
+    if (!Array.isArray(patterns)) return [];
+    return patterns
+      .filter((entry) => entry && entry.approval === 'deny' && typeof entry.match === 'string')
+      .map((entry) => entry.match);
+  } catch {
+    return [];
+  }
+}
+
+export async function inspectUnattendedMode({ projectRoot, ompPath = 'omp' }) {
+  const runtimeConfig = await readJsonIfExists(
+    path.join(projectRoot, '.ukit', 'storage', 'config.json'),
+  );
+  const permissionModeRaw = runtimeConfig?.orchestration?.permissionMode;
+  const permissionModeValid = permissionModeRaw === undefined
+    || VALID_PERMISSION_MODES.has(permissionModeRaw);
+  const permissionMode = permissionModeRaw === undefined ? 'unattended' : permissionModeRaw;
+
+  const omp = await readOmpConfig(projectRoot);
+  const tools = omp.parsed?.tools ?? {};
+  const approvalMap = tools.approval && typeof tools.approval === 'object' ? tools.approval : {};
+  const bashPatterns = Array.isArray(omp.parsed?.bash?.patterns) ? omp.parsed.bash.patterns : [];
+
+  // Check 2 — effective approvalMode: `omp config get` first (5s timeout), YAML fallback.
+  let effectiveApprovalMode = null;
+  let approvalSource = null;
+  if (omp.exists) {
+    const ompResult = await execOmpConfigGet(projectRoot, ompPath);
+    if (ompResult.ok) {
+      effectiveApprovalMode = ompResult.value;
+      approvalSource = 'omp config get';
+    } else if (tools.approvalMode !== undefined) {
+      effectiveApprovalMode = tools.approvalMode ?? null;
+      approvalSource = '.omp/config.yml (omp binary unavailable)';
+    }
+  }
+
+  const promptValues = [tools.approvalMode, ...Object.values(approvalMap)];
+  for (const entry of bashPatterns) {
+    if (entry && typeof entry === 'object' && 'approval' in entry) promptValues.push(entry.approval);
+  }
+  const promptPolicyCount = promptValues.filter((v) => v === 'prompt').length;
+
+  const bridgePath = path.join(projectRoot, '.omp', 'hooks', 'pre', 'ukit-bridge.js');
+  const bridgeExists = await pathExists(bridgePath);
+  const requiredDenyMatches = await readTemplateDenyMatches();
+  const installedDenyMatches = new Set(
+    bashPatterns
+      .filter((entry) => entry && entry.approval === 'deny' && typeof entry.match === 'string')
+      .map((entry) => entry.match),
+  );
+  const missingDenyMatches = requiredDenyMatches.filter((m) => !installedDenyMatches.has(m));
+  const guardState = !bridgeExists
+    ? 'degraded'
+    : (missingDenyMatches.length > 0 ? 'partial' : 'enabled');
+
+  let loopGuidanceInstalled = false;
+  let instructionDocExists = false;
+  for (const docName of ['CLAUDE.md', 'AGENTS.md']) {
+    try {
+      const text = await fs.readFile(path.join(projectRoot, docName), 'utf8');
+      instructionDocExists = true;
+      if (text.includes(COMPLETION_LOOP_HEADER)) {
+        loopGuidanceInstalled = true;
+        break;
+      }
+    } catch {
+      // file may not exist
+    }
+  }
+
+  const check = (label, passed, remediationClass, remedy, extra = {}) => ({
+    label,
+    passed,
+    failed: !passed,
+    remediationClass,
+    remedy,
+    ...extra,
+  });
+
+  const checks = [
+    // 1 — permissionMode declared
+    check(
+      '`permissionMode` declared',
+      permissionModeValid,
+      'owner-action',
+      `Set orchestration.permissionMode in .ukit/storage/config.json to one of: ${[...VALID_PERMISSION_MODES].join(', ')}.`,
+      permissionModeRaw === undefined ? { detail: 'unattended (default)' } : {},
+    ),
+    // 2 — effective approvalMode is yolo
+    effectiveApprovalMode === null
+      ? check(
+        'effective approvalMode is `yolo`',
+        false,
+        'install-repairable',
+        INSTALL_REPAIR,
+        {
+          applicable: false,
+          detail: omp.exists
+            ? 'no tools.approvalMode readable (omp unavailable and YAML value absent)'
+            : 'no .omp/config.yml project override',
+        },
+      )
+      : check(
+        'effective approvalMode is `yolo`',
+        effectiveApprovalMode === 'yolo',
+        'install-repairable',
+        'Run ukit install to pin tools.approvalMode: yolo in .omp/config.yml.',
+        { detail: `value: ${effectiveApprovalMode} (source: ${approvalSource})` },
+      ),
+    // 3 — eval/bash policy allow
+    check(
+      "eval/bash policy 'allow'",
+      omp.exists && approvalMap.eval === 'allow' && approvalMap.bash === 'allow',
+      'install-repairable',
+      'Run ukit install to restore tools.approval.eval/bash: allow.',
+      omp.exists
+        ? {}
+        : { applicable: false, detail: '.omp/config.yml absent' },
+    ),
+    // 4 — zero prompt policies
+    check(
+      'zero `prompt` policies',
+      promptPolicyCount === 0,
+      'install-repairable',
+      'Run ukit install to strip `prompt` approvals (unattended mode cannot surface prompts).',
+      {
+        ...(omp.exists ? {} : { applicable: false, detail: '.omp/config.yml absent' }),
+        detail: `${promptPolicyCount} prompt policy(ies)`,
+      },
+    ),
+    // 5 — project override active
+    check(
+      'project override active',
+      omp.exists,
+      'advisory',
+      'Run ukit install to materialize the project .omp/config.yml override.',
+      omp.exists ? {} : { applicable: false, detail: '.omp/config.yml absent' },
+    ),
+    // 6 — completion loop guidance installed
+    check(
+      'completion loop guidance installed',
+      loopGuidanceInstalled,
+      'install-repairable',
+      `Run ukit install to add the '${COMPLETION_LOOP_HEADER}' section to CLAUDE.md/AGENTS.md.`,
+      instructionDocExists ? {} : { applicable: false, detail: 'no CLAUDE.md/AGENTS.md' },
+    ),
+    // 7 — safety guard enabled
+    check(
+      'safety guard enabled',
+      guardState === 'enabled',
+      'advisory',
+      !bridgeExists
+        ? 'Restore .omp/hooks/pre/ukit-bridge.js (run ukit install); guard is degraded.'
+        : `Add the missing deny patterns to .omp/config.yml bash.patterns (${missingDenyMatches.length} missing).`,
+      {
+        ...(omp.exists || bridgeExists ? {} : { applicable: false }),
+        detail: `guard state: ${guardState}${missingDenyMatches.length > 0 ? ` (${missingDenyMatches.length} deny pattern(s) missing)` : ''}`,
+      },
+    ),
+  ];
+
+  return {
+    checks,
+    summary: {
+      permissionMode,
+      effectiveApprovalMode,
+      promptPolicyCount,
+      guardState,
+    },
+  };
+}

package/templates/.claude/commands/ukit/handoff-create.md

@@ -6,7 +6,7 @@
 - Read/understand → lite model (haiku · unic-lite · cheapest available)
 - Write plan + tasks → strong model (Opus · unic-smart · strongest available)
 
-> **omp model tiers:** the tiers above map to `.omp/config.yml`'s `modelRoles`, referenced from agent frontmatter as `@lite` / `@code` / `@smart`.
+> **omp model tiers:** the tiers above map to `.omp/config.yml`'s `modelRoles`, referenced from agent frontmatter as `@smol` / `@default` / `@slow`.
 
 ## Problem / feature
 $ARGUMENTS

package/templates/.claude/commands/ukit/handoff-fullstack.md

@@ -13,9 +13,9 @@
 
 > Claude Code: spawn `ukit-small-task-maintainer` (haiku) for light steps; spawn `handoff-planner` (opus) for planning; spawn `feature-implementer` (sonnet) agents for implementation; spawn `code-reviewer` (opus) per task for review.
 >
-> omp: same four agents, launched with the `task` tool (`agent: "<name>"`). They live in `.omp/agents/` and bind their tier through `model: "@lite"` / `"@code"` / `"@smart"`, resolved via `modelRoles` in `.omp/config.yml` — you do not pass a model name.
+> omp: same four agents, launched with the `task` tool (`agent: "<name>"`). They live in `.omp/agents/` and bind their tier through `model: "@smol"` / `"@default"` / `"@slow"`, resolved via `modelRoles` in `.omp/config.yml` — you do not pass a model name.
 
-> **omp model tiers:** the tiers above map to `.omp/config.yml`'s `modelRoles`, referenced from agent frontmatter as `@lite` / `@code` / `@smart`.
+> **omp model tiers:** the tiers above map to `.omp/config.yml`'s `modelRoles`, referenced from agent frontmatter as `@smol` / `@default` / `@slow`.
 
 ---
 

package/templates/.claude/commands/ukit/handoff-implement.md

@@ -4,7 +4,7 @@
 **Tool: any** (Claude Code / Codex / omp / Kilo / OpenCode — your choice)
 **Model: code model** (Sonnet · unic-code · cheap-smart)
 
-> **omp model tiers:** the tiers above map to `.omp/config.yml`'s `modelRoles`, referenced from agent frontmatter as `@lite` / `@code` / `@smart`.
+> **omp model tiers:** the tiers above map to `.omp/config.yml`'s `modelRoles`, referenced from agent frontmatter as `@smol` / `@default` / `@slow`.
 
 ## Target (optional)
 $ARGUMENTS

package/templates/.claude/commands/ukit/handoff-review.md

@@ -4,7 +4,7 @@
 **Tool: any** (Claude Code / Codex / omp / Kilo / OpenCode — your choice)
 **Model: strong model, MUST differ from executor** (Opus · unic-smart · strongest available)
 
-> **omp model tiers:** the tiers above map to `.omp/config.yml`'s `modelRoles`, referenced from agent frontmatter as `@lite` / `@code` / `@smart`.
+> **omp model tiers:** the tiers above map to `.omp/config.yml`'s `modelRoles`, referenced from agent frontmatter as `@smol` / `@default` / `@slow`.
 
 ## Target (optional)
 $ARGUMENTS