@ngockhoale/ukit 2.7.1 → 2.7.3

package/src/core/ompConfigMerge.js

@@ -23,10 +23,25 @@ function emptyReport() {
     addedModelRoleKeys: [],
     preservedTopLevelKeys: [],
     preservedPatterns: [],
+    // TASK-002 / FR-002 — every `{{token}}` left in the merged output. A token
+    // survives when renderTemplateString could not resolve it (unknown variable)
+    // or when it was spliced in verbatim from the existing file. The merge never
+    // fabricates a value; it reports the token so install can warn.
+    unresolvedTokens: [],
     parseError: null,
   };
 }
 
+const UNRESOLVED_TOKEN_PATTERN = /\{\{\s*([a-zA-Z0-9_.-]+)\s*\}\}/g;
+
+function recordUnresolvedTokens(text, report) {
+  for (const match of text.matchAll(UNRESOLVED_TOKEN_PATTERN)) {
+    if (!report.unresolvedTokens.includes(match[1])) {
+      report.unresolvedTokens.push(match[1]);
+    }
+  }
+}
+
 // 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.
@@ -72,10 +87,12 @@ export function mergeOmpConfig(existingText, renderedText) {
     existing = YAML.parse(existingText);
   } catch (error) {
     report.parseError = error?.message ?? String(error);
+    recordUnresolvedTokens(renderedText, report);
     return { text: renderedText, report };
   }
   if (!isPlainObject(existing)) {
     report.parseError = 'existing .omp/config.yml did not parse to a mapping';
+    recordUnresolvedTokens(renderedText, report);
     return { text: renderedText, report };
   }
 
@@ -86,6 +103,7 @@ export function mergeOmpConfig(existingText, renderedText) {
     // 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}`;
+    recordUnresolvedTokens(renderedText, report);
     return { text: renderedText, report };
   }
 
@@ -242,6 +260,7 @@ export function mergeOmpConfig(existingText, renderedText) {
   }
 
   const text = lines.join('\n');
+  recordUnresolvedTokens(text, report);
   // "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.

package/src/core/opencodeSteer.js

@@ -0,0 +1,37 @@
+// SPEC FR-004 — OpenCode support was removed. Any leftover artifact is a user
+// file: UKit never installs, repairs, merges, or deletes it (only `ukit
+// uninstall` may). This helper is the single source of truth for detection and
+// the canonical steer message shared by projectImportant, status, and doctor.
+
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+// Extensible list — detection is one existsSync per known filename, no parsing.
+const OPENCODE_ARTIFACT_NAMES = ['opencode.json'];
+
+/**
+ * @param {string} projectRoot
+ * @returns {string[]} absolute paths of detected OpenCode artifacts
+ */
+export function findOpencodeArtifacts(projectRoot) {
+  return OPENCODE_ARTIFACT_NAMES
+    .map((name) => path.join(projectRoot, name))
+    .filter((candidate) => existsSync(candidate));
+}
+
+/**
+ * Canonical steer copy. Callers must print this verbatim so every surface
+ * (status line, doctor WARN row, stderr warning) reads identically.
+ *
+ * @param {string[]} paths detected artifact paths from findOpencodeArtifacts
+ * @returns {string}
+ */
+export function opencodeSteerMessage(paths = []) {
+  const names = (Array.isArray(paths) ? paths : [])
+    .map((entry) => path.basename(String(entry)))
+    .filter(Boolean);
+  const fileList = names.length > 0 ? names.join(' ') : 'opencode.json';
+  return `[ukit] ${fileList} detected — OpenCode is no longer supported. `
+    + `ukit will not install, repair, or merge this file. `
+    + `Remove it manually: rm ${fileList}`;
+}

package/src/core/permissionDoctor.js

@@ -0,0 +1,319 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { parse } from 'yaml';
+import { pathExists, readJsonIfExists } from './fileOps.js';
+import { VALID_PERMISSION_MODES } from './runtimeConfig.js';
+import {
+  compilePermissionPolicy,
+  PERMISSION_HOSTS,
+  CANONICAL_DENY,
+} from './permissionPolicy.js';
+import { findOpencodeArtifacts, opencodeSteerMessage } from './opencodeSteer.js';
+
+// TASK-006 / SPEC §5 FR-006 — unified permission report across claude/omp/codex
+// UKit-managed surfaces. Reads the live surfaces, compiles the semantic policy
+// (single source of truth — drift between render and doctor is impossible), and
+// emits { declared, effective, hosts, checks, failures } for both the human
+// doctor section and `--json`.
+//
+// FAIL classes (each → named failing check + report.failures entry + exit 1):
+//   unattended-prompt      prompt/ask reachable while permissionMode=unattended
+//   deny-loss              canonical deny entry missing from a host surface
+//   unsafe-eval-mismatch   surface eval approval ≠ compiled evalPosture
+//   unrendered-token       literal {{token}} left in a rendered artifact
+// INFO: reachable prompts under interactive/safe-auto. SKIP: absent host surface.
+
+const UNRESOLVED_TOKEN_PATTERN = /\{\{\s*([a-zA-Z0-9_.-]+)\s*\}\}/g;
+
+// Bounded scan list — UKit-managed rendered artifacts only (SPEC §6 perf).
+const RENDERED_ARTIFACTS = [
+  '.omp/config.yml',
+  '.claude/settings.json',
+  '.claude/settings.local.json',
+  '.codex/settings.json',
+  '.codex/settings.local.json',
+];
+
+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) };
+  }
+}
+
+async function readClaudeSurface(projectRoot) {
+  const settingsPath = path.join(projectRoot, '.claude', 'settings.json');
+  const settings = await readJsonIfExists(settingsPath);
+  const permissions = settings?.permissions;
+  if (!permissions || typeof permissions !== 'object') {
+    return { present: false, deny: [], allow: [], ask: [] };
+  }
+  const list = (key) => (Array.isArray(permissions[key]) ? permissions[key].filter((e) => typeof e === 'string') : []);
+  return {
+    present: true,
+    deny: list('deny'),
+    allow: list('allow'),
+    ask: list('ask'),
+  };
+}
+
+async function scanUnresolvedTokens(projectRoot) {
+  const hits = [];
+  for (const relPath of RENDERED_ARTIFACTS) {
+    let text;
+    try {
+      text = await fs.readFile(path.join(projectRoot, relPath), 'utf8');
+    } catch {
+      continue; // absent artifact — not a token hit
+    }
+    for (const match of text.matchAll(UNRESOLVED_TOKEN_PATTERN)) {
+      hits.push({ file: relPath, token: match[1] });
+    }
+  }
+  return hits;
+}
+
+export async function inspectPermissions({ projectRoot, ompPath = 'omp' }) {
+  const runtimeConfig = await readJsonIfExists(
+    path.join(projectRoot, '.ukit', 'storage', 'config.json'),
+  );
+  const declaredRaw = runtimeConfig?.orchestration?.permissionMode;
+  const declared = declaredRaw === undefined ? 'unattended' : declaredRaw;
+  const modeValid = VALID_PERMISSION_MODES.has(declared);
+  const allowUnsafeEval = runtimeConfig?.orchestration?.allowUnsafeEval === true;
+
+  // --- Surface reads ---------------------------------------------------------
+  const omp = await readOmpConfig(projectRoot);
+  const ompTools = omp.parsed?.tools ?? {};
+  const approvalMap = ompTools.approval && typeof ompTools.approval === 'object' ? ompTools.approval : {};
+  const bashPatterns = Array.isArray(omp.parsed?.bash?.patterns) ? omp.parsed.bash.patterns : [];
+
+  const ompDeny = bashPatterns
+    .filter((e) => e && e.approval === 'deny' && typeof e.match === 'string')
+    .map((e) => e.match);
+  const ompAllow = bashPatterns
+    .filter((e) => e && e.approval === 'allow' && typeof e.match === 'string')
+    .map((e) => e.match);
+  // Reachable prompt/ask entries on the omp surface — named so the report can
+  // point at the offending key instead of a bare count.
+  const ompPromptEntries = [];
+  if (ompTools.approvalMode === 'prompt' || ompTools.approvalMode === 'ask') {
+    ompPromptEntries.push('tools.approvalMode');
+  }
+  for (const [key, value] of Object.entries(approvalMap)) {
+    if (value === 'prompt' || value === 'ask') ompPromptEntries.push(`tools.approval.${key}`);
+  }
+  for (const entry of bashPatterns) {
+    if (entry && (entry.approval === 'prompt' || entry.approval === 'ask')) {
+      ompPromptEntries.push(`bash.patterns:${entry.match ?? '?'}`);
+    }
+  }
+  const ompEvalSurface = approvalMap.eval;
+
+  const claude = await readClaudeSurface(projectRoot);
+  const codexPresent = await pathExists(path.join(projectRoot, '.codex'));
+
+  // --- Per-host compiled policy ---------------------------------------------
+  const hosts = {};
+  const policies = {};
+  const surfaceInput = {
+    omp: omp.exists
+      ? {
+          deny: ompDeny,
+          allow: ompAllow,
+          ask: ompPromptEntries,
+          // compile throws on non-allow/deny values — prompt/ask eval is already
+          // counted as a reachable prompt, so only feed the compiler a real
+          // posture value.
+          ...(ompEvalSurface === 'allow' || ompEvalSurface === 'deny'
+            ? { evalApproval: ompEvalSurface }
+            : {}),
+        }
+      : null,
+    claude: claude.present
+      ? { deny: claude.deny, allow: claude.allow, ask: claude.ask }
+      : null,
+    codex: codexPresent ? {} : null,
+  };
+
+  for (const host of PERMISSION_HOSTS) {
+    const present = surfaceInput[host] !== null;
+    if (!present) {
+      hosts[host] = { present: false, enforcement: host === 'codex' ? 'report-only' : 'enforced' };
+      continue;
+    }
+    let policy = null;
+    let compileError = null;
+    if (modeValid) {
+      try {
+        policy = compilePermissionPolicy({
+          permissionMode: declared,
+          allowUnsafeEval,
+          host,
+          surfaces: surfaceInput[host],
+        });
+      } catch (error) {
+        compileError = error?.message ?? String(error);
+      }
+    }
+    policies[host] = policy;
+
+    const surfaceDeny = surfaceInput[host]?.deny ?? [];
+    const denySet = new Set(surfaceDeny);
+    const denyMissing = CANONICAL_DENY
+      .map((c) => c[host])
+      .filter((entry) => typeof entry === 'string' && !denySet.has(entry));
+
+    const promptCount = host === 'omp'
+      ? ompPromptEntries.length
+      : (surfaceInput[host]?.ask ?? []).length;
+
+    hosts[host] = {
+      present: true,
+      enforcement: policy?.enforcement ?? (host === 'codex' ? 'report-only' : 'enforced'),
+      effectiveMode: policy?.effectiveMode ?? declared,
+      allowsPrompts: policy?.allowsPrompts ?? null,
+      promptCount,
+      promptEntries: surfaceInput[host]?.ask ?? [],
+      denyCount: surfaceDeny.length,
+      denyMissing,
+      evalPosture: policy?.evalPosture ?? null,
+      evalSurface: host === 'omp' ? (ompEvalSurface ?? null) : null,
+      warnings: policy?.warnings ?? [],
+      ...(compileError ? { compileError } : {}),
+    };
+  }
+
+  const unresolvedTokens = await scanUnresolvedTokens(projectRoot);
+  const legacyArtifacts = findOpencodeArtifacts(projectRoot);
+
+  // --- Checks ----------------------------------------------------------------
+  const failures = [];
+  const anySurface = PERMISSION_HOSTS.some((h) => hosts[h].present);
+  const totalPrompts = PERMISSION_HOSTS.reduce((n, h) => n + (hosts[h].promptCount ?? 0), 0);
+  const promptsFail = declared === 'unattended' && totalPrompts > 0;
+  // Report-only hosts (codex) have no permission surface by design — counting
+  // their canonical deny set as "missing" would make deny-loss FAIL permanent
+  // with an impossible remedy. Only enforced surfaces feed deny-loss.
+  const denyMissingAll = PERMISSION_HOSTS
+    .filter((h) => hosts[h].enforcement === 'enforced')
+    .flatMap((h) => (hosts[h].denyMissing ?? []).map((entry) => `${h}:${entry}`));
+  const evalMismatch = PERMISSION_HOSTS.some((h) =>
+    (hosts[h].warnings ?? []).includes('unsafe-eval-mismatch'));
+  const driftWarnings = PERMISSION_HOSTS.flatMap((h) =>
+    (hosts[h].warnings ?? [])
+      .filter((w) => w !== 'unsafe-eval-mismatch' && w !== 'prompt-reachable-under-unattended')
+      .map((w) => `${h}:${w}`));
+
+  if (promptsFail) failures.push('unattended-prompt');
+  if (denyMissingAll.length > 0) failures.push('deny-loss');
+  if (evalMismatch) failures.push('unsafe-eval-mismatch');
+  if (unresolvedTokens.length > 0) failures.push('unrendered-token');
+  if (!modeValid) failures.push('invalid-permission-mode');
+
+  const check = (label, passed, remediationClass, remedy, extra = {}) => ({
+    label,
+    passed,
+    failed: !passed,
+    remediationClass,
+    remedy,
+    ...extra,
+  });
+
+  const checks = [
+    check(
+      'permission mode declared and valid',
+      modeValid,
+      'owner-action',
+      `Set orchestration.permissionMode in .ukit/storage/config.json to one of: ${[...VALID_PERMISSION_MODES].join(', ')}.`,
+      { detail: `declared: ${declared}${declaredRaw === undefined ? ' (default)' : ''} → effective: ${modeValid ? declared : 'unknown'}` },
+    ),
+    check(
+      'no prompts reachable under unattended mode',
+      !promptsFail,
+      'owner-action',
+      'Run ukit install to strip prompt/ask approvals, or switch orchestration.permissionMode to interactive/safe-auto.',
+      {
+        ...(anySurface ? {} : { applicable: false, detail: 'no host permission surfaces installed' }),
+        ...(anySurface && !promptsFail && totalPrompts > 0
+          ? { severity: 'info' }
+          : {}),
+        detail: anySurface
+          ? `${totalPrompts} reachable prompt/ask entr(ies)${declared === 'unattended' ? '' : ` (mode ${declared} allows prompts)`}`
+          : 'no host permission surfaces installed',
+      },
+    ),
+    check(
+      'deny coverage vs canonical set',
+      denyMissingAll.length === 0,
+      'install-repairable',
+      'Run ukit install to restore the canonical deny entries on host surfaces.',
+      {
+        ...(anySurface ? {} : { applicable: false }),
+        detail: denyMissingAll.length === 0
+          ? 'all canonical deny entries present'
+          : `missing: ${denyMissingAll.join(', ')}`,
+      },
+    ),
+    check(
+      'eval posture matches allowUnsafeEval',
+      !evalMismatch,
+      'install-repairable',
+      `Run ukit install to re-render eval approval (compiled posture: ${allowUnsafeEval ? 'allow' : 'deny'}), or flip orchestration.allowUnsafeEval.`,
+      {
+        ...(hosts.omp.present ? {} : { applicable: false, detail: '.omp/config.yml absent' }),
+        detail: hosts.omp.present
+          ? `knob=${allowUnsafeEval} → expected ${allowUnsafeEval ? 'allow' : 'deny'}, surface eval=${ompEvalSurface ?? 'absent'}`
+          : '.omp/config.yml absent',
+      },
+    ),
+    check(
+      'no unresolved {{token}} in rendered artifacts',
+      unresolvedTokens.length === 0,
+      'install-repairable',
+      'Run ukit install to re-render and heal literal {{tokens}}; unknown tokens are reported, never fabricated.',
+      {
+        detail: unresolvedTokens.length === 0
+          ? 'no {{...}} literals in managed artifacts'
+          : unresolvedTokens.map((t) => `${t.file}:{{${t.token}}}`).join(', '),
+      },
+    ),
+    check(
+      'no drift vs compiled policy',
+      driftWarnings.length === 0,
+      'advisory',
+      'Review the flagged surface entries against compilePermissionPolicy output.',
+      {
+        ...(driftWarnings.length > 0 ? { severity: 'warning' } : {}),
+        detail: driftWarnings.length === 0 ? 'surfaces consistent with compiled policy' : driftWarnings.join(', '),
+      },
+    ),
+  ];
+
+  if (legacyArtifacts.length > 0) {
+    checks.push({
+      label: opencodeSteerMessage(legacyArtifacts),
+      passed: true,
+      failed: false,
+      severity: 'warning',
+      remediationClass: 'advisory',
+      remedy: 'Remove it manually: rm opencode.json',
+    });
+  }
+
+  return {
+    declared,
+    effective: modeValid ? declared : 'unknown',
+    allowUnsafeEval,
+    hosts,
+    checks,
+    failures,
+    unresolvedTokens,
+    legacyArtifacts,
+  };
+}

package/src/core/permissionPolicy.js

@@ -0,0 +1,179 @@
+// UKIT_EPOLICY — pure compiler: orchestration.permissionMode +
+// orchestration.allowUnsafeEval → deterministic per-host semantic policy for
+// claude/omp/codex. No I/O: callers pass parsed surfaces (doctor reads files,
+// tests pass fixtures). Consumed by doctor (FR-006) and the no-freeze matrix
+// (FR-007) as the single semantic source of truth so host surfaces cannot
+// drift. SPEC §5 FR-005 / §8 / §14.
+import { VALID_PERMISSION_MODES } from './runtimeConfig.js';
+
+export const PERMISSION_HOSTS = Object.freeze(['claude', 'omp', 'codex']);
+export const PERMISSION_MODES = VALID_PERMISSION_MODES;
+
+// Precedence — higher tier always wins over a lower one for the same entry.
+export const PERMISSION_PRECEDENCE = Object.freeze([
+  'hard-deny',        // catastrophic commands — deny regardless of any surface
+  'protected-guard',  // hook-guarded files/tools — outranks host-deny
+  'host-deny',        // surface deny rules (settings.json deny, bash.patterns deny)
+  'explicit-allow',   // surface allow rules
+  'mode-fallback',    // mode default action for unclassified entries
+]);
+
+// Canonical deny set — semantic ids + per-host surface strings. Templates,
+// doctor, and the matrix all assert against this so surfaces cannot lose an
+// entry without detection. `hardDeny: true` entries are catastrophic-class
+// (root/home/parent recursive deletes, dd/mkfs/fork-bomb) and are denied in
+// every mode on every host, even report-only codex.
+export const CANONICAL_DENY = Object.freeze([
+  { id: 'git-reset-hard', claude: 'Bash(git reset --hard:*)', omp: 'git reset --hard*', codex: 'git reset --hard' },
+  { id: 'git-push-force', claude: 'Bash(git push --force:*)', omp: 'git push --force*', codex: 'git push --force' },
+  { id: 'git-push-force-short', claude: 'Bash(git push -f:*)', omp: 'git push -f *', codex: 'git push -f' },
+  { id: 'git-push-force-with-lease', claude: 'Bash(git push --force-with-lease:*)', omp: 'git push --force-with-lease*', codex: 'git push --force-with-lease' },
+  { id: 'git-clean-fd', claude: 'Bash(git clean -fd:*)', omp: 'git clean -fd*', codex: 'git clean -fd' },
+  { id: 'git-checkout-dot', claude: 'Bash(git checkout .:*)', omp: 'git checkout .*', codex: 'git checkout .' },
+  { id: 'git-restore-dot', claude: 'Bash(git restore .:*)', omp: 'git restore .*', codex: 'git restore .' },
+  { id: 'rm-rf-root', claude: 'Bash(rm -rf /:*)', omp: 'rm -rf /*', codex: 'rm -rf /', hardDeny: true },
+  { id: 'rm-rf-home', claude: 'Bash(rm -rf ~:*)', omp: 'rm -rf ~*', codex: 'rm -rf ~', hardDeny: true },
+  { id: 'rm-rf-parent', claude: 'Bash(rm -rf ..:*)', omp: 'rm -rf ..', codex: 'rm -rf ..', hardDeny: true },
+  { id: 'rm-rf-dot', claude: 'Bash(rm -rf .:*)', omp: 'rm -rf .', codex: 'rm -rf .', hardDeny: true },
+  { id: 'rm-rf-any', claude: 'Bash(rm -rf:*)', omp: 'rm -rf *', codex: 'rm -rf' },
+  { id: 'dd-raw-device', claude: 'Bash(dd if=/dev/:*)', omp: 'dd if=/dev/*', codex: 'dd if=/dev/', hardDeny: true },
+  { id: 'write-raw-device', claude: 'Bash(*> /dev/sda:*)', omp: '*> /dev/sda*', codex: '> /dev/sda', hardDeny: true },
+  { id: 'mkfs', claude: 'Bash(mkfs:*)', omp: 'mkfs.*', codex: 'mkfs', hardDeny: true },
+  { id: 'fork-bomb', claude: 'Bash(:(){ :|:& };::*)', omp: ':(){ :|:& };:*', codex: ':(){ :|:& };:', hardDeny: true },
+]);
+
+// Canonical protected-guard set — hook-enforced paths/tools that outrank any
+// surface deny/allow. Semantic ids only; hook scripts remain the authority.
+export const CANONICAL_PROTECTED = Object.freeze([
+  'release-credentials',   // npm tokens, signing keys, .env secrets
+  'protected-files',       // protect-files.sh guarded paths
+  'stale-spec-guard',      // spec/source drift guard on edits
+]);
+
+const TIER_RANK = new Map(PERMISSION_PRECEDENCE.map((tier, i) => [tier, i]));
+
+// Mode fallback for unclassified entries. `prompt` fallback is what makes a
+// mode prompt-reachable; unattended never falls back to a prompt.
+const MODE_FALLBACK = Object.freeze({
+  interactive: 'prompt',
+  'safe-auto': 'prompt',
+  unattended: 'allow',
+});
+
+const MODE_PROMPT_CAPABLE = Object.freeze({
+  interactive: true,
+  'safe-auto': true,
+  unattended: false,
+});
+
+// codex carries no UKit-managed permission block today — the compiler still
+// returns a shaped policy so doctor/matrix can report it (SPEC §14).
+const HOST_ENFORCEMENT = Object.freeze({
+  claude: 'enforced',
+  omp: 'enforced',
+  codex: 'report-only',
+});
+
+function policyError(message) {
+  return new Error(`UKIT_EPOLICY ${message}`);
+}
+
+/**
+ * compilePermissionPolicy({ permissionMode, allowUnsafeEval, host, surfaces? })
+ * → { mode, effectiveMode, host, enforcement, allowsPrompts, promptReachable,
+ *     deny, allow, protections, evalPosture, rules, warnings }
+ *
+ * `surfaces` is an optional caller-parsed host surface:
+ *   { deny: [...], allow: [...], protect: [...], ask: [...], evalApproval }
+ * Entries appearing in several tiers resolve to the highest precedence tier.
+ */
+export function compilePermissionPolicy(input = {}) {
+  const { permissionMode, allowUnsafeEval = false, host, surfaces = {} } = input;
+
+  if (!VALID_PERMISSION_MODES.has(permissionMode)) {
+    throw policyError(`unknown permissionMode: ${JSON.stringify(permissionMode)} (expected one of: ${[...VALID_PERMISSION_MODES].join(', ')})`);
+  }
+  if (!PERMISSION_HOSTS.includes(host)) {
+    throw policyError(`unknown host: ${JSON.stringify(host)} (expected one of: ${PERMISSION_HOSTS.join(', ')})`);
+  }
+  if (allowUnsafeEval !== undefined && typeof allowUnsafeEval !== 'boolean') {
+    throw policyError(`allowUnsafeEval must be boolean, got: ${JSON.stringify(allowUnsafeEval)}`);
+  }
+  if (surfaces === null || typeof surfaces !== 'object' || Array.isArray(surfaces)) {
+    throw policyError('surfaces must be an object when provided');
+  }
+
+  const mode = permissionMode;
+  const effectiveMode = mode;
+  const enforcement = HOST_ENFORCEMENT[host];
+  const promptCapable = MODE_PROMPT_CAPABLE[mode];
+  const warnings = [];
+
+  // --- eval posture: allow iff the knob is explicitly true (fail closed). ---
+  const evalPosture = allowUnsafeEval === true ? 'allow' : 'deny';
+  if (surfaces.evalApproval !== undefined
+    && surfaces.evalApproval !== 'allow'
+    && surfaces.evalApproval !== 'deny') {
+    throw policyError(`surfaces.evalApproval must be 'allow' or 'deny', got: ${JSON.stringify(surfaces.evalApproval)}`);
+  }
+  if (surfaces.evalApproval !== undefined && surfaces.evalApproval !== evalPosture) {
+    warnings.push('unsafe-eval-mismatch');
+  }
+
+  // --- Tier collection. Each rule: { entry, tier, action, source }. ---
+  const byEntry = new Map();
+  const addRule = (entry, tier, action, source) => {
+    if (typeof entry !== 'string' || entry.length === 0) return;
+    const existing = byEntry.get(entry);
+    if (!existing || TIER_RANK.get(tier) < TIER_RANK.get(existing.tier)) {
+      byEntry.set(entry, { entry, tier, action, source });
+    }
+  };
+
+  for (const canonical of CANONICAL_DENY) {
+    const tier = canonical.hardDeny === true ? 'hard-deny' : 'host-deny';
+    addRule(canonical[host], tier, 'deny', `canonical:${canonical.id}`);
+  }
+  for (const guard of CANONICAL_PROTECTED) {
+    addRule(guard, 'protected-guard', 'deny', 'canonical-guard');
+  }
+
+  for (const entry of surfaces.protect ?? []) addRule(entry, 'protected-guard', 'deny', 'surface:protect');
+  for (const entry of surfaces.deny ?? []) addRule(entry, 'host-deny', 'deny', 'surface:deny');
+  for (const entry of surfaces.allow ?? []) addRule(entry, 'explicit-allow', 'allow', 'surface:allow');
+
+  // ask/prompt surface entries: reachable prompts only when the mode can prompt.
+  const askEntries = [...new Set(surfaces.ask ?? [])];
+  const promptReachable = [];
+  for (const entry of askEntries) {
+    if (promptCapable) {
+      addRule(entry, 'explicit-allow', 'prompt', 'surface:ask');
+      promptReachable.push(entry);
+    } else {
+      // Under unattended an ask entry is unreachable — flagged for doctor.
+      addRule(entry, 'host-deny', 'deny', 'surface:ask-unreachable');
+      warnings.push('prompt-reachable-under-unattended');
+    }
+  }
+
+  const rules = [...byEntry.values()];
+  const deny = rules.filter((r) => r.action === 'deny').map((r) => r.entry);
+  const allow = rules.filter((r) => r.action === 'allow').map((r) => r.entry);
+  const protections = rules.filter((r) => r.tier === 'protected-guard').map((r) => r.entry);
+
+  return {
+    mode,
+    effectiveMode,
+    host,
+    enforcement,
+    allowsPrompts: promptCapable,
+    promptReachable,
+    deny,
+    allow,
+    protections,
+    evalPosture,
+    rules,
+    warnings: [...new Set(warnings)],
+    fallback: MODE_FALLBACK[mode],
+  };
+}

package/src/core/projectImportant.js

@@ -25,6 +25,7 @@ import {
   isSensitiveDataGateEnabled,
   loadSensitiveAllowlist,
 } from './sensitiveValueScanner.js';
+import { findOpencodeArtifacts, opencodeSteerMessage } from './opencodeSteer.js';
 
 export const PROJECT_IMPORTANT_FILENAME = 'PROJECT_IMPORTANT.md';
 export const PROJECT_IMPORTANT_CODEPOINT_LIMIT = 6000;
@@ -338,12 +339,14 @@ export async function renderProjectImportantForProject(projectRoot, options = {}
  * TASK-044 — adapter wiring facts for status/doctor (spec §13/§14).
  *
  * Returns install + wiring facts only — never file bodies. Claude wiring is
- * always expected; omp/Codex/OpenCode are checked only when installed, and an
- * absent adapter is `installed:false`, never a failure.
+ * always expected; omp/Codex are checked only when installed, and an
+ * absent adapter is `installed:false`, never a failure. A leftover
+ * `opencode.json` is no longer an adapter signal — it is detected and
+ * reported via `opencodeArtifacts` + a steer warning, never wired.
  *
  * @param {string} projectRoot
  * @param {{ trackedPaths?: string[] }} [options] install.json file list, if known
- * @returns {Promise<{claude: object, omp: object, codex: object, opencode: object, agentsFallback: boolean}>}
+ * @returns {Promise<{claude: object, omp: object, codex: object, opencodeArtifacts: string[], agentsFallback: boolean}>}
  */
 export async function inspectProjectImportantWiring(projectRoot, options = {}) {
   const trackedPaths = Array.isArray(options.trackedPaths) ? options.trackedPaths : [];
@@ -397,7 +400,7 @@ export async function inspectProjectImportantWiring(projectRoot, options = {}) {
     wired: runtimeModule && hookInstalled && hookExecutable && settingsWired,
   };
 
-  // --- AGENTS.md owner-instructions pointer (shared Codex/OpenCode fallback) ---
+  // --- AGENTS.md owner-instructions pointer (shared Codex fallback) ---
   let agentsFallback = false;
   try {
     const agents = await readFile(agentsPath, 'utf8');
@@ -425,9 +428,12 @@ export async function inspectProjectImportantWiring(projectRoot, options = {}) {
   const codexInstalled = tracked('.codex/') || await exists(path.join(projectRoot, '.codex', 'settings.json'));
   const codex = { installed: codexInstalled, wired: codexInstalled && agentsFallback };
 
-  // --- OpenCode fallback (only when opencode.json tracked/installed) ---
-  const opencodeInstalled = tracked('opencode.json') || await exists(path.join(projectRoot, 'opencode.json'));
-  const opencode = { installed: opencodeInstalled, wired: opencodeInstalled && agentsFallback };
+  // --- OpenCode steer (SPEC FR-005) — a leftover opencode.json is a user file:
+  // never wired, never installed/repaired. Detect it and steer toward removal.
+  const opencodeArtifacts = findOpencodeArtifacts(projectRoot);
+  if (opencodeArtifacts.length > 0) {
+    console.warn(opencodeSteerMessage(opencodeArtifacts));
+  }
 
-  return { claude, omp, codex, opencode, agentsFallback };
+  return { claude, omp, codex, opencodeArtifacts, agentsFallback };
 }