opencode-agent-skill 15.1.0 → 15.1.1

package/lib/code-intelligence/lsp-provider.mjs

@@ -1,6 +1,10 @@
-import { spawn, spawnSync } from "node:child_process"
+import { spawn } from "node:child_process"
+import { existsSync } from "node:fs"
 import { lstat, readFile, realpath } from "node:fs/promises"
 import path from "node:path"
+import { commandExists } from "../executable-probe.mjs"
+import { resolveWindowsCommand } from "../windows-shim.mjs"
+import { lspPoolStatus as managedLspPoolStatus, shutdownLspPool as shutdownManagedLspPool, withManagedLspSession } from "./lsp-pool.mjs"
 import { fileURLToPath, pathToFileURL } from "node:url"
 
 const PROVIDERS = [
@@ -22,19 +26,6 @@ export const LSP_OPERATIONS = Object.freeze([
   "outgoing-calls",
 ])
 
-const commandCache = new Map()
-const COMMAND_TTL_MS = 60_000
-
-function commandExists(command) {
-  const now = Date.now()
-  const cached = commandCache.get(command)
-  if (cached && now - cached.at < COMMAND_TTL_MS) return cached.available
-  const finder = process.platform === "win32" ? "where" : "which"
-  const available = spawnSync(finder, [command], { stdio: "ignore", windowsHide: true }).status === 0
-  commandCache.set(command, { available, at: now })
-  return available
-}
-
 function inside(root, target) {
   return target === root || target.startsWith(root + path.sep)
 }
@@ -50,18 +41,73 @@ async function safeFile(root, relative) {
   return { base, file: actual, info }
 }
 
+export function resolveTypeScriptTsserverFallback(options = {}) {
+  const explicit = String(options.explicitPath ?? process.env.UES_TYPESCRIPT_TSSERVER_PATH ?? "").trim()
+  if (explicit && existsSync(path.resolve(explicit))) return path.resolve(explicit)
+
+  const platform = String(options.platform || process.platform)
+  if (platform !== "win32") return null
+
+  const execution = options.execution || resolveWindowsCommand("tsserver")
+  const candidates = [
+    execution?.entry,
+    ...(Array.isArray(execution?.argsPrefix) ? execution.argsPrefix : []),
+  ].filter(Boolean)
+
+  for (const value of candidates) {
+    const entry = path.resolve(String(value))
+    const binDir = path.dirname(entry)
+    const packageRoot = path.basename(binDir).toLowerCase() === "bin"
+      ? path.dirname(binDir)
+      : null
+    const preferred = packageRoot ? path.join(packageRoot, "lib", "tsserver.js") : null
+    if (preferred && existsSync(preferred)) return preferred
+    if (existsSync(entry)) return entry
+  }
+  return null
+}
+
+function providerRuntimeOptions(provider) {
+  if (provider?.id !== "typescript-language-server") return {}
+  const fallbackPath = resolveTypeScriptTsserverFallback()
+  return fallbackPath
+    ? { initializationOptions: { tsserver: { fallbackPath } } }
+    : {}
+}
+
 function providerFor(file) {
   const ext = path.extname(file).toLowerCase()
   for (const provider of PROVIDERS) {
     if (!provider.extensions.has(ext)) continue
     for (const [command, args] of provider.commands) {
-      if (commandExists(command)) return { ...provider, command, args, languageId: provider.languageId(ext) }
+      if (commandExists(command)) {
+        return {
+          ...provider,
+          ...providerRuntimeOptions(provider),
+          command,
+          args,
+          languageId: provider.languageId(ext),
+        }
+      }
     }
     return { ...provider, command: null, args: [], languageId: provider.languageId(ext) }
   }
   return null
 }
 
+export function lspPersistencePolicy(options = {}) {
+  if (typeof options.persistent === "boolean") {
+    return { enabled: options.persistent, source: "explicit-option" }
+  }
+  const env = String(process.env.UES_LSP_PERSISTENT || "").trim()
+  if (env === "0") return { enabled: false, source: "env-disabled" }
+  if (env === "1") return { enabled: true, source: "env-enabled" }
+  if (process.env.UES_CHILD_PROCESS === "1") {
+    return { enabled: true, source: "pi-child-runtime" }
+  }
+  return { enabled: false, source: "short-lived-default" }
+}
+
 export function lspProviderStatus(file = "") {
   const ext = path.extname(String(file || "")).toLowerCase()
   const providers = PROVIDERS
@@ -75,6 +121,13 @@ export function lspProviderStatus(file = "") {
     extension: ext,
     available: providers.some((row) => row.available),
     operations: [...LSP_OPERATIONS],
+    persistentPool: {
+      ...managedLspPoolStatus({
+        includeSessions: false,
+        persistent: lspPersistencePolicy().enabled,
+      }),
+      policy: lspPersistencePolicy(),
+    },
     providers,
   }
 }
@@ -199,7 +252,7 @@ function sanitizeHierarchyCalls(base, values, direction, limit = 120) {
   })
 }
 
-async function withLspSession(root, relative, options, operation) {
+async function withEphemeralLspSession(root, relative, options, operation) {
   const target = await safeFile(root, relative)
   const provider = providerFor(target.file)
   const relativeFile = path.relative(target.base, target.file).replaceAll("\\", "/")
@@ -222,8 +275,26 @@ async function withLspSession(root, relative, options, operation) {
   const rootUri = pathToFileURL(target.base + path.sep).href
   const timeoutMs = Math.max(500, Math.min(15_000, Number(options.timeoutMs || 5000)))
 
+  const execution = process.platform === "win32"
+    ? resolveWindowsCommand(provider.command)
+    : { executable: provider.command, argsPrefix: [] }
+  if (!execution?.executable) {
+    return {
+      schemaVersion: 2,
+      file: relativeFile,
+      available: true,
+      provider: provider.id,
+      command: provider.command,
+      operation: options.operation || null,
+      reason: "spawn-error",
+      result: null,
+      stderr: null,
+      error: "unable to resolve LSP executable: " + provider.command,
+    }
+  }
+
   return await new Promise((resolve) => {
-    const child = spawn(provider.command, provider.args, {
+    const child = spawn(execution.executable, [...(execution.argsPrefix || []), ...provider.args], {
       cwd: target.base,
       stdio: ["pipe", "pipe", "pipe"],
       windowsHide: true,
@@ -364,6 +435,7 @@ async function withLspSession(root, relative, options, operation) {
             workspace: { workspaceFolders: true, applyEdit: false },
           },
           workspaceFolders: [{ uri: rootUri, name: path.basename(target.base) || "workspace" }],
+          initializationOptions: provider.initializationOptions || undefined,
         })
         notify("initialized", {})
         notify("textDocument/didOpen", {
@@ -388,13 +460,35 @@ async function withLspSession(root, relative, options, operation) {
 export async function lspOperation(root, relative, operation, options = {}) {
   const op = String(operation || "")
   if (!LSP_OPERATIONS.includes(op)) throw new Error("unsupported LSP operation: " + op)
+
+  const target = await safeFile(root, relative)
+  const provider = providerFor(target.file)
+  const relativeFile = path.relative(target.base, target.file).replaceAll("\\", "/")
+  if (!provider?.command) {
+    return {
+      schemaVersion: 2,
+      file: relativeFile,
+      available: false,
+      provider: provider?.id || null,
+      operation: op,
+      reason: provider ? "lsp-command-unavailable" : "unsupported-extension",
+      result: null,
+      persistent: false,
+    }
+  }
+
   const maxResults = Math.max(1, Math.min(500, Number(options.maxResults || 120)))
-  return withLspSession(root, relative, { ...options, operation: op }, async (session) => {
+  const execute = async (session) => {
     const pos = position(options)
     const textDocument = { uri: session.uri }
 
     if (op === "diagnostics") {
-      const params = await session.waitForNotification("textDocument/publishDiagnostics")
+      const params = await session.waitForNotification("textDocument/publishDiagnostics", {
+        predicate: (value) =>
+          (!value?.uri || value.uri === session.uri) &&
+          (value?.version == null || Number(value.version) >= Number(session.documentSync?.version || 0)),
+        afterAt: session.documentSync?.changed ? session.documentSync.syncedAt : 0,
+      })
       const values = Array.isArray(params?.diagnostics) ? params.diagnostics : []
       return { diagnostics: values.slice(0, maxResults).map(sanitizeDiagnostic) }
     }
@@ -450,7 +544,53 @@ export async function lspOperation(root, relative, operation, options = {}) {
       }
     }
     return null
-  })
+  }
+
+  const persistence = lspPersistencePolicy(options)
+  const managed = await withManagedLspSession(
+    target,
+    provider,
+    { ...options, persistent: persistence.enabled, operation: op },
+    execute,
+  ).catch((error) => ({
+    ok: false,
+    reason: "managed-lsp-exception",
+    error: String(error instanceof Error ? error.message : error).slice(0, 1200),
+  }))
+
+  if (managed?.ok) {
+    return {
+      schemaVersion: 2,
+      file: relativeFile,
+      available: true,
+      provider: provider.id,
+      command: provider.command,
+      operation: op,
+      reason: "ok",
+      result: managed.result,
+      stderr: managed.stderr || null,
+      error: null,
+      persistent: true,
+      pool: { ...managed.meta, policy: persistence },
+    }
+  }
+
+  const fallback = await withEphemeralLspSession(root, relative, { ...options, operation: op }, execute)
+  return {
+    ...fallback,
+    persistent: false,
+    fallbackFrom: managed?.reason || "managed-lsp-unavailable",
+    managedError: managed?.error || null,
+    persistencePolicy: persistence,
+  }
+}
+
+export function lspPoolStatus(options = {}) {
+  return managedLspPoolStatus(options)
+}
+
+export async function shutdownLspPool(root = null) {
+  return shutdownManagedLspPool(root)
 }
 
 export async function diagnoseCode(root, relative, options = {}) {

package/lib/compaction-resume-guard.mjs

@@ -153,6 +153,72 @@ function stateSummary(state) {
   }
 }
 
+function buildInstructionEpoch(state, tasks, receipts, gateReceipts) {
+  const rows = Array.isArray(tasks) ? tasks : []
+  const passedTaskReceipts = new Set(
+    (Array.isArray(receipts) ? receipts : [])
+      .filter((item) => item?.passed === true && item?.task)
+      .map((item) => String(item.task)),
+  )
+  const completedTaskIds = rows.filter((row) => row.status === "completed").map((row) => row.id)
+  const activeTaskIds = rows.filter((row) => row.status === "running").map((row) => row.id)
+  const failedTaskIds = rows.filter((row) => row.status === "failed").map((row) => row.id)
+  const pendingTaskIds = rows
+    .filter((row) => !["completed", "failed"].includes(String(row.status || "").toLowerCase()))
+    .map((row) => row.id)
+  const tasksWithoutPassingReceipt = completedTaskIds.filter((id) => !passedTaskReceipts.has(String(id)))
+  const decisions = (Array.isArray(state?.decisions) ? state.decisions : [])
+    .slice(-8)
+    .map((item) => ({
+      at: item?.at || null,
+      text: item?.text ? String(item.text).slice(0, 600) : null,
+      source: item?.source || null,
+      risk: item?.policy?.risk || null,
+      autoResolvable: item?.policy?.autoResolvable === true,
+      confidence: Number.isFinite(Number(item?.policy?.decision?.confidence))
+        ? Number(item.policy.decision.confidence)
+        : null,
+    }))
+
+  const body = {
+    schemaVersion: 1,
+    source: "durable-state-fold",
+    objective: state?.goal ? String(state.goal).slice(0, 1200) : null,
+    status: state?.status || null,
+    planHash: state?.planHash || null,
+    planApproved: state?.planApproved === true,
+    activeTaskIds,
+    pendingTaskIds,
+    completedTaskIds,
+    failedTaskIds,
+    blockers: (Array.isArray(state?.blockers) ? state.blockers : []).slice(-12).map((item) => String(item).slice(0, 500)),
+    recentDecisions: decisions,
+    checkpoint: state?.checkpoint ? {
+      id: state.checkpoint.id || null,
+      currentTaskId: state.checkpoint.currentTaskId || null,
+      runId: state.checkpoint.runId || null,
+      workspaceFingerprint: state.checkpoint.workspaceFingerprint || null,
+      nextAction: state.checkpoint.nextAction || null,
+    } : null,
+    nextAction: state?.nextAction || null,
+    verification: {
+      tasksWithoutPassingReceipt,
+      passingReceiptIds: (Array.isArray(receipts) ? receipts : [])
+        .filter((item) => item?.passed === true && item?.id)
+        .slice(-20)
+        .map((item) => item.id),
+      passingGateReceiptIds: (Array.isArray(gateReceipts) ? gateReceipts : [])
+        .filter((item) => String(item?.verdict || "").toUpperCase() === "PASS" && item?.id)
+        .slice(-12)
+        .map((item) => item.id),
+    },
+  }
+  return {
+    ...body,
+    epochHash: digest(JSON.stringify(body)),
+  }
+}
+
 export async function checkpointDurableWorkBeforeCompaction(root, options = {}) {
   const reason = String(options.reason || "unknown")
   const rows = await activeWorkspaces(root, options.maxWorkspaces || MAX_WORKSPACES)
@@ -197,6 +263,10 @@ export async function buildCompactionResumeGuard(root, options = {}) {
         ? path.relative(root, path.join(row.dir, "phases", "MANIFEST.json")).replaceAll("\\", "/")
         : null,
     }
+    const tasks = taskRows(plan, row.state)
+    const receipts = receiptRows(evidence)
+    const gateReceipts = gateRows(evidence)
+    const instructionEpoch = buildInstructionEpoch(row.state, tasks, receipts, gateReceipts)
     workspaces.push({
       slug: row.slug,
       sources,
@@ -208,9 +278,10 @@ export async function buildCompactionResumeGuard(root, options = {}) {
         phaseManifest: manifest ? digest(JSON.stringify(manifest)) : null,
       },
       state: stateSummary(row.state),
-      tasks: taskRows(plan, row.state),
-      receipts: receiptRows(evidence),
-      gateReceipts: gateRows(evidence),
+      instructionEpoch,
+      tasks,
+      receipts,
+      gateReceipts,
       executionContract: contract ? {
         schemaVersion: contract.schemaVersion || null,
         taskHash: contract.taskHash || null,
@@ -243,7 +314,8 @@ export function renderCompactionResumeGuard(packet, options = {}) {
     "## UES Durable Compaction Resume Guard",
     "Authoritative durable state was rebuilt from filesystem artifacts after Pi compaction.",
     "The model-generated compaction summary is advisory only for durable execution state.",
-    "If the summary conflicts with STATE.json, PLAN.json, EXECUTION_CONTRACT.json, phase artifacts, or evidence receipts below, the deterministic artifacts win.",
+    "If the summary conflicts with STATE.json, PLAN.json, EXECUTION_CONTRACT.json, phase artifacts, instructionEpoch, or evidence receipts below, the deterministic artifacts win.",
+    "Treat instructionEpoch as the compact deterministic control-plane fold: objective, active work, blockers, decisions, receipt gaps and next action.",
     "Do not mark a task/phase complete unless the rebuilt state and fresh receipts support it.",
     "Follow checkpoint.nextAction/state.nextAction and re-read the referenced artifact when more detail is required.",
     "",

package/lib/completion-auditor.mjs

@@ -42,6 +42,17 @@ function receiptPassed(row = {}) {
   return Boolean(receipt?.passed === true && Number(receipt?.exitCode) === 0)
 }
 
+function claimEvidenceStatus(value) {
+  const lines = text(value).split(/\r?\n/).map((line) => line.trim()).filter(Boolean)
+  const counts = { verified: 0, inferred: 0, unknown: 0 }
+  for (const line of lines) {
+    if (/^(?:[-*]\s*)?VERIFIED\s*:/i.test(line)) counts.verified += 1
+    else if (/^(?:[-*]\s*)?INFERRED\s*:/i.test(line)) counts.inferred += 1
+    else if (/^(?:[-*]\s*)?UNKNOWN\s*:/i.test(line)) counts.unknown += 1
+  }
+  return counts
+}
+
 export function auditCompletion(input = {}) {
   const failures = []
   const warnings = []
@@ -67,6 +78,14 @@ export function auditCompletion(input = {}) {
   }
   if (Object.hasOwn(sections, "checks-not-run") && !benignEmptySection(sections["checks-not-run"])) warnings.push("verification-reports-checks-not-run")
 
+  const claimStatus = claimEvidenceStatus(sections["acceptance-criteria-proven"])
+  const claimStatusCount = claimStatus.verified + claimStatus.inferred + claimStatus.unknown
+  if (input.requireClaimEvidenceStatus === true && claimStatusCount === 0) {
+    failures.push("acceptance-criteria-evidence-status-missing")
+  }
+  if (claimStatus.inferred > 0) failures.push("acceptance-criteria-inferred-not-proven")
+  if (claimStatus.unknown > 0) failures.push("acceptance-criteria-unknown-not-proven")
+
   const snapshot = input.workspaceSnapshot || null
   if (snapshot) {
     if (snapshot.cacheable === true && !text(snapshot.fingerprint)) failures.push("workspace-fingerprint-missing")
@@ -95,6 +114,7 @@ export function auditCompletion(input = {}) {
       visual: requireVisual ? passRun(visual) : null,
       reportSections: Object.keys(sections).sort(),
       passingReceiptCount: passingReceipts.length,
+      claimEvidenceStatus: claimStatus,
       workspaceFingerprint: snapshot?.fingerprint || null,
       changedFiles: Array.isArray(snapshot?.changedFiles) ? snapshot.changedFiles.slice(0, 200) : [],
     },

package/lib/context-manifest.mjs

@@ -7,6 +7,7 @@ import { taskFiles } from "./task-graph.mjs"
 import { buildSemanticIndexCached, querySemanticIndex } from "./semantic-index.mjs"
 import { queryContextHierarchy } from "./hierarchical-context.mjs"
 import { rankContextGraph } from "./context-graph-rank.mjs"
+import { runtimeWorkspaceSnapshot } from "./workspace-fingerprint.mjs"
 
 const ROOT_INSTRUCTIONS = [
   "AGENTS.md",
@@ -249,9 +250,20 @@ export async function buildContextManifest(root, task, options = {}) {
   const evidenceBudget = options.evidenceBudget || null
   const declared = taskFiles(task)
   const terms = taskTerms(task)
+  let workspaceSnapshot = null
+  const suppliedFingerprint = String(options.workspaceFingerprint || "").trim()
+  if (!Array.isArray(options.changedFiles) || !suppliedFingerprint) {
+    try {
+      workspaceSnapshot = runtimeWorkspaceSnapshot(root, { workspaceState: options.workspaceState })
+    } catch {}
+  }
+  const reusableWorkspaceFingerprint = suppliedFingerprint ||
+    (workspaceSnapshot?.cacheable ? String(workspaceSnapshot.fingerprint || "") : "")
   const changed = Array.isArray(options.changedFiles)
     ? options.changedFiles.map((file) => String(file || "").replaceAll("\\", "/")).filter(Boolean)
-    : gitChangedFiles(root)
+    : Array.isArray(workspaceSnapshot?.changedFiles)
+      ? workspaceSnapshot.changedFiles
+      : gitChangedFiles(root)
   const strategy = String(options.strategy || "semantic+graph+git")
   const queryText = [
     task?.title,
@@ -263,22 +275,32 @@ export async function buildContextManifest(root, task, options = {}) {
   const semanticSnapshot = await buildSemanticIndexCached(root, {
     maxFiles: options.semanticMaxFiles ?? 6000,
     maxDepth: options.semanticMaxDepth ?? 14,
-    workspaceFingerprint: options.workspaceFingerprint,
+    workspaceFingerprint: reusableWorkspaceFingerprint,
   }).catch(() => null)
 
-  const hierarchy = await queryContextHierarchy(root, queryText, {
-    declaredFiles: declared,
-    maxScopes: options.hierarchyMaxScopes ?? 6,
-    maxFiles: options.semanticMaxFiles ?? 6000,
-    builtIndex: semanticSnapshot || undefined,
-  }).catch(() => null)
+  const useGraph = strategy.includes("graph")
+  const [hierarchy, semantic, graph, instructions] = await Promise.all([
+    queryContextHierarchy(root, queryText, {
+      declaredFiles: declared,
+      maxScopes: options.hierarchyMaxScopes ?? 6,
+      maxFiles: options.semanticMaxFiles ?? 6000,
+      builtIndex: semanticSnapshot || undefined,
+    }).catch(() => null),
+    querySemanticIndex(root, queryText, {
+      limit: 32,
+      maxFiles: options.semanticMaxFiles ?? 6000,
+      builtIndex: semanticSnapshot || undefined,
+    }).catch(() => null),
+    useGraph
+      ? buildRepoGraphCached(root, {
+          maxFiles: options.maxFiles ?? 2500,
+          workspaceFingerprint: reusableWorkspaceFingerprint,
+        }).catch(() => ({ nodes: [], edges: [], hotspots: [], scannedFiles: 0, truncated: false }))
+      : Promise.resolve({ nodes: [], edges: [], hotspots: [], scannedFiles: 0, truncated: false }),
+    nearbyInstructions(root, declared).catch(() => []),
+  ])
   const hierarchyScopes = hierarchy?.scopes?.map((item) => item.path) || []
 
-  const semantic = await querySemanticIndex(root, queryText, {
-    limit: 32,
-    maxFiles: options.semanticMaxFiles ?? 6000,
-    builtIndex: semanticSnapshot || undefined,
-  }).catch(() => null)
   const scopedSemanticResults = (semantic?.results || []).map((item) => {
     const scopeRank = hierarchyScopes.findIndex((scope) =>
       scope === "." || item.path === scope || item.path.startsWith(scope + "/"),
@@ -293,13 +315,6 @@ export async function buildContextManifest(root, task, options = {}) {
   }).sort((a, b) => b.score - a.score || a.path.localeCompare(b.path))
   const semanticPaths = scopedSemanticResults.map((item) => item.path)
 
-  const useGraph = strategy.includes("graph")
-  const graph = useGraph
-    ? await buildRepoGraphCached(root, {
-        maxFiles: options.maxFiles ?? 2500,
-        workspaceFingerprint: options.workspaceFingerprint,
-      })
-    : { nodes: [], edges: [], hotspots: [], scannedFiles: 0, truncated: false }
   const nodeMap = new Map(graph.nodes.map((node) => [node.path, node]))
   const incoming = new Map()
 
@@ -330,7 +345,6 @@ export async function buildContextManifest(root, task, options = {}) {
     .slice(0, 24)
     .map((item) => item.file)
 
-  const instructions = await nearbyInstructions(root, declared)
   const graphRanked = useGraph
     ? rankContextGraph(graph, {
         semanticResults: scopedSemanticResults,
@@ -437,6 +451,7 @@ export async function buildContextManifest(root, task, options = {}) {
     excerpts,
     hierarchy: hierarchy ? {
       schemaVersion: hierarchy.schemaVersion,
+      runtimeCacheHit: hierarchy.runtimeCacheHit === true,
       levels: hierarchy.levels,
       scopes: hierarchy.scopes.slice(0, 6).map((item) => ({
         path: item.path,
@@ -450,6 +465,8 @@ export async function buildContextManifest(root, task, options = {}) {
     semantic: semantic ? {
       evidenceLevel: semantic.evidenceLevel,
       resultCount: semantic.results.length,
+      runtimeCacheHit: semanticSnapshot?.runtimeCacheHit === true,
+      runtimeCacheCoalesced: semanticSnapshot?.runtimeCacheCoalesced === true,
       stats: semantic.stats,
     } : null,
     graph: {

package/lib/decision-policy.mjs

@@ -2,6 +2,21 @@ const HIGH_RISK = /(npm publish|publish package|deploy|production|git push|force
 const MEDIUM_RISK = /(migration|schema|dependency upgrade|lockfile|generated code|shared config|auth|permission|security)/i
 const REVERSIBLE = /(local|test|rename|format|refactor|temporary|fixture|internal|reversible)/i
 
+function confidenceForDecision(input = {}) {
+  if (input.requiresUser === true && (input.destructive === true || input.externalSideEffect === true || input.explicitlyIrreversible === true)) return 0.99
+  if (input.reversible === true && input.risk === "low") return 0.96
+  if (input.risk === "medium") return 0.82
+  if (input.requiresUser === true) return 0.90
+  return 0.74
+}
+
+function confidenceBand(value) {
+  const score = Number(value || 0)
+  if (score >= 0.90) return "high"
+  if (score >= 0.72) return "medium"
+  return "low"
+}
+
 export function classifyDecisionPolicy(text = "", facts = {}) {
   const value = String(text || "").trim()
   const explicitlyIrreversible = facts.irreversible === true
@@ -11,10 +26,33 @@ export function classifyDecisionPolicy(text = "", facts = {}) {
   const reversible = facts.reversible === true || (!destructive && REVERSIBLE.test(value))
   const risk = destructive || explicitlyIrreversible || externalSideEffect ? "high" : medium ? "medium" : "low"
   const requiresUser = risk === "high" || facts.productDecision === true
+  const autoResolvable = !requiresUser && (reversible || risk === "low")
+  const confidence = confidenceForDecision({
+    requiresUser,
+    destructive,
+    externalSideEffect,
+    explicitlyIrreversible,
+    reversible,
+    risk,
+  })
   return {
-    schemaVersion: 1, risk, reversible, destructive, externalSideEffect, requiresUser,
-    autoResolvable: !requiresUser && (reversible || risk === "low"),
+    schemaVersion: 1,
+    risk,
+    reversible,
+    destructive,
+    externalSideEffect,
+    requiresUser,
+    autoResolvable,
     reason: requiresUser ? "human-approval-required" : reversible ? "reversible-local-decision" : "bounded-engineering-decision",
+    decision: {
+      schemaVersion: 1,
+      kind: String(facts.decisionKind || "engineering-choice"),
+      source: "deterministic",
+      value: requiresUser ? "escalate-to-user" : autoResolvable ? "auto-resolve" : "bounded-review",
+      confidence,
+      confidenceBand: confidenceBand(confidence),
+      crossCheckRecommended: confidence < 0.72 || risk === "medium",
+    },
   }
 }