opencode-agent-skill 7.7.0 → 9.0.0

package/global-config/plugins/ues-router/router.js

@@ -11,50 +11,167 @@ const PROCESS_SKILLS = new Set([
   "ues-repo-explorer",
 ])
 
-export function routeSkills(text, maxSkills = 4) {
+const DOMAIN_PATTERNS = [
+  ["react-native", /(react native|expo|android|ios|gradle|xcode|metro)/],
+  ["nextjs", /(next\.js|nextjs|app router|server component)/],
+  ["react", /(\breact\b|\bhook\b|useeffect|usestate|\bcomponent\b)/],
+  ["fastapi", /(fastapi|pydantic|uvicorn)/],
+  ["django", /(django|django rest|drf)/],
+  ["python", /(python|pytest|pip|poetry|pyproject)/],
+  ["nestjs", /(nestjs|nest\.js)/],
+  ["nodejs", /(node\.js|nodejs|express|npm|pnpm|yarn)/],
+  ["dotnet", /(asp\.net|\.net|dotnet|nuget|c#)/],
+  ["java-spring", /(spring boot|spring framework|maven|gradle java|\bjava\b)/],
+  ["flutter", /(flutter|dart)/],
+  ["database", /(database|migration|sql|query|index|transaction|schema changes?|cơ sở dữ liệu|truy vấn|chỉ mục|giao dịch|migrate dữ liệu)/],
+  ["auth-security", /(auth|authorization|authentication|permission|role|tenant|idor|token|session|xác thực|phân quyền|quyền|vai trò)/],
+  ["payment", /(payment|checkout|webhook|refund|idempotenc|thanh toán|hoàn tiền)/],
+  ["api-contract", /(api contract|openapi|response schema|request schema|breaking api|public api|hợp đồng api|api công khai)/],
+  ["devops", /(docker|github actions|ci\/cd|pipeline|deploy|kubernetes|container|triển khai|đường ống ci)/],
+  ["performance", /(performance|slow|latency|memory leak|n\+1|bundle size|hiệu năng|chậm|rò rỉ bộ nhớ)/],
+  ["accessibility", /(accessibility|accessible|a11y|screen reader|keyboard navigation|aria|focus management|focus handling)/],
+  ["file-upload", /(upload|file upload|multipart|object storage)/],
+  ["ecommerce", /(ecommerce|marketplace|inventory|cart|catalog|order)/],
+]
+
+const STACK_TO_DOMAIN = new Map([
+  ["react-native", "react-native"],
+  ["react", "react"],
+  ["nextjs", "nextjs"],
+  ["nestjs", "nestjs"],
+  ["express", "nodejs"],
+  ["fastify", "nodejs"],
+  ["node", "nodejs"],
+  ["python", "python"],
+  ["django", "django"],
+  ["java-maven", "java-spring"],
+  ["java-gradle", "java-spring"],
+  ["kotlin-gradle", "java-spring"],
+  ["dotnet", "dotnet"],
+  ["flutter", "flutter"],
+])
+
+export function classifyIntent(text, facts = {}) {
   const value = String(text || "").toLowerCase()
-  const limit = Number.isInteger(maxSkills) ? Math.max(1, Math.min(maxSkills, 6)) : 4
-  const routed = []
-  const risky = /(migration|schema|database|sql|auth|permission|security|payment|webhook|public api|contract|dependency|deploy|ci|production|rollback)/
-  const nonTrivial = value.length > 220 || risky.test(value) || /(implement|feature|refactor|fix|debug|investigate|review|audit|bug|regression|failing|failure|error|exception|broken)/.test(value)
+  const domains = []
+  for (const [domain, pattern] of DOMAIN_PATTERNS) {
+    if (pattern.test(value)) add(domains, domain)
+  }
 
-  if (nonTrivial) add(routed, "ues-engineering-orchestrator")
-  const longHorizon = value.length > 700 || /(large task|big task|long[- ]running|multi[- ]file|cross[- ]module|whole (?:repo|repository|project)|entire (?:repo|repository|project)|full refactor|refactor all|migrate all|resume this work)/.test(value)
-  if (longHorizon) {
-    add(routed, "ues-engineering-orchestrator")
-    add(routed, "ues-long-task-state")
-    add(routed, "ues-task-planner")
+  const repoStacks = [...new Set(
+    (facts.repoStacks || facts.stacks || [])
+      .map((item) => String(item || "").toLowerCase())
+      .filter(Boolean),
+  )]
+  const explicitFramework = domains.some((domain) => [
+    "react-native", "nextjs", "react", "fastapi", "django", "python", "nestjs",
+    "nodejs", "dotnet", "java-spring", "flutter",
+  ].includes(domain))
+  if (!explicitFramework) {
+    for (const stack of repoStacks) add(domains, STACK_TO_DOMAIN.get(stack))
   }
-  if (/(\bfix\b|\bbug\b|crash|regression|failing|failure|error|exception|broken|\bdebug\b)/.test(value)) add(routed, "ues-bug-diagnosis")
-  if (/(latest|current docs|documentation|release notes|version compatibility|dependency|package version|api changed)/.test(value)) add(routed, "ues-research-verification")
 
+  const actions = []
+  if (/(\bfix\b|\bbug\b|crash|regression|failing|failure|error|exception|broken|\bdebug\b|sửa lỗi|lỗi|không chạy|bị hỏng|điều tra lỗi)/.test(value)) add(actions, "debug")
+  if (/(implement|feature|add|build|create|triển khai tính năng|thêm|xây dựng)/.test(value)) add(actions, "implement")
+  if (/(review|audit|kiểm tra code|đánh giá)/.test(value)) add(actions, "review")
+  if (/(investigate|analy[sz]e|profile|optimi[sz]e|điều tra|phân tích|tối ưu)/.test(value)) add(actions, "investigate")
+  if (/(refactor|cleanup|restructure|refactor toàn bộ)/.test(value)) add(actions, "refactor")
+  if (/(latest|current docs|documentation|release notes|version compatibility|dependency|package version|api changed|tài liệu mới nhất|phiên bản mới|tương thích phiên bản|package mới)/.test(value)) add(actions, "research")
+
+  const risky = /(migration|schema|database|sql|auth|permission|security|payment|webhook|public api|contract|dependency|deploy|ci|production|rollback|cơ sở dữ liệu|phân quyền|xác thực|bảo mật|thanh toán|triển khai|phụ thuộc)/.test(value)
+  const longHorizon = value.length > 700 || /(large task|big task|long[- ]running|multi[- ]file|cross[- ]module|whole (?:repo|repository|project)|entire (?:repo|repository|project)|full refactor|refactor all|migrate all|resume this work|toàn bộ (?:repo|repository|dự án)|nhiều file|nhiều module|refactor toàn bộ|tiếp tục công việc)/.test(value)
+  const nonTrivial = value.length > 220 || risky || actions.length > 0
+
+  const feedbackDomains = [...new Set((facts.feedbackDomains || []).filter((item) => domains.includes(item)))]
+  const confidence = Math.min(1, 0.35 + domains.length * 0.08 + actions.length * 0.08 + (repoStacks.length ? 0.08 : 0) + (feedbackDomains.length ? 0.08 : 0))
+
+  return {
+    schemaVersion: 1,
+    actions,
+    domains,
+    repoStacks,
+    feedbackDomains,
+    nonTrivial,
+    risk: risky ? "high" : nonTrivial ? "medium" : "low",
+    scope: longHorizon ? "long-horizon" : nonTrivial ? "standard" : "inline",
+    confidence: Number(confidence.toFixed(2)),
+  }
+}
+
+function addDomainSkills(routed, value, intent) {
   if (/(react native|expo|android|ios|gradle|xcode|metro)/.test(value)) add(routed, "ues-react-native-engineering")
   else if (/(next\.js|nextjs|app router|server component)/.test(value)) add(routed, "ues-nextjs-engineering")
   else if (/(\breact\b|\bhook\b|useeffect|usestate|\bcomponent\b)/.test(value)) add(routed, "ues-react-engineering")
+  else {
+    for (const domain of intent.domains) {
+      if (domain === "react-native") add(routed, "ues-react-native-engineering")
+      else if (domain === "nextjs") add(routed, "ues-nextjs-engineering")
+      else if (domain === "react") add(routed, "ues-react-engineering")
+    }
+  }
 
-  if (/(database|migration|sql|query|index|transaction|schema changes?)/.test(value)) {
+  if (/(fastapi|pydantic|uvicorn)/.test(value)) add(routed, "ues-fastapi-engineering")
+  else if (/(django|django rest|drf)/.test(value)) add(routed, "ues-django-engineering")
+  else if (/(python|pytest|pip|poetry|pyproject)/.test(value)) add(routed, "ues-python-engineering")
+  else {
+    if (intent.domains.includes("fastapi")) add(routed, "ues-fastapi-engineering")
+    else if (intent.domains.includes("django")) add(routed, "ues-django-engineering")
+    else if (intent.domains.includes("python")) add(routed, "ues-python-engineering")
+  }
+
+  if (/(nestjs|nest\.js)/.test(value)) add(routed, "ues-nestjs-engineering")
+  else if (/(node\.js|nodejs|express|npm|pnpm|yarn)/.test(value)) add(routed, "ues-nodejs-engineering")
+  else {
+    if (intent.domains.includes("nestjs")) add(routed, "ues-nestjs-engineering")
+    else if (intent.domains.includes("nodejs")) add(routed, "ues-nodejs-engineering")
+  }
+
+  if (/(asp\.net|\.net|dotnet|nuget|c#)/.test(value) || intent.domains.includes("dotnet")) add(routed, "ues-dotnet-engineering")
+  if (/(spring boot|spring framework|maven|gradle java|\bjava\b)/.test(value) || intent.domains.includes("java-spring")) add(routed, "ues-java-spring-engineering")
+  if (/(flutter|dart)/.test(value) || intent.domains.includes("flutter")) add(routed, "ues-flutter-engineering")
+
+  if (intent.domains.includes("database")) {
     add(routed, "ues-database-engineering")
     add(routed, "ues-change-impact-analysis")
   }
-  if (/(auth|authorization|authentication|permission|role|tenant|idor|token|session)/.test(value)) {
+  if (intent.domains.includes("auth-security")) {
     add(routed, "ues-auth-security")
     add(routed, "ues-change-impact-analysis")
   }
-  if (/(payment|checkout|webhook|refund|idempotenc)/.test(value)) {
+  if (intent.domains.includes("payment")) {
     add(routed, "ues-payment-engineering")
     add(routed, "ues-change-impact-analysis")
   }
-  if (/(api contract|openapi|response schema|request schema|breaking api|public api)/.test(value)) {
+  if (intent.domains.includes("api-contract")) {
     add(routed, "ues-api-contract")
     add(routed, "ues-change-impact-analysis")
   }
-  if (/(docker|github actions|ci\/cd|pipeline|deploy|kubernetes|container)/.test(value)) add(routed, "ues-devops-engineering")
-  if (/(performance|slow|latency|memory leak|n\+1|bundle size)/.test(value)) add(routed, "ues-performance-engineering")
-  if (/(accessibility|accessible|a11y|screen reader|keyboard navigation|aria|focus management|focus handling)/.test(value)) add(routed, "ues-accessibility")
-  if (/(upload|file upload|multipart|object storage)/.test(value)) add(routed, "ues-file-upload-engineering")
-  if (/(ecommerce|marketplace|inventory|cart|catalog|order)/.test(value)) add(routed, "ues-ecommerce-engineering")
+  if (intent.domains.includes("devops")) add(routed, "ues-devops-engineering")
+  if (intent.domains.includes("performance")) add(routed, "ues-performance-engineering")
+  if (intent.domains.includes("accessibility")) add(routed, "ues-accessibility")
+  if (intent.domains.includes("file-upload")) add(routed, "ues-file-upload-engineering")
+  if (intent.domains.includes("ecommerce")) add(routed, "ues-ecommerce-engineering")
+}
+
+export function routeSkills(text, maxSkills = 4, facts = {}) {
+  const value = String(text || "").toLowerCase()
+  const limit = Number.isInteger(maxSkills) ? Math.max(1, Math.min(maxSkills, 6)) : 4
+  const routed = []
+  const intent = classifyIntent(value, facts)
+
+  if (intent.nonTrivial) add(routed, "ues-engineering-orchestrator")
+  if (intent.scope === "long-horizon") {
+    add(routed, "ues-engineering-orchestrator")
+    add(routed, "ues-long-task-state")
+    add(routed, "ues-task-planner")
+  }
+  if (intent.actions.includes("debug")) add(routed, "ues-bug-diagnosis")
+  if (intent.actions.includes("research")) add(routed, "ues-research-verification")
+
+  addDomainSkills(routed, value, intent)
 
-  if (routed.length === 0 && /(code|repository|repo|project|function|class|endpoint|test)/.test(value)) {
+  if (routed.length === 0 && /(code|repository|repo|project|function|class|endpoint|test|dự án|hàm|lớp|kiểm thử)/.test(value)) {
     add(routed, "ues-repo-explorer")
   }
 

package/global-config/skills/engineering-orchestrator/references/long-horizon.md

@@ -12,6 +12,7 @@ When the user explicitly chooses the long-horizon workflow (for example with `/u
   PLAN.json
   STATE.json
   EVIDENCE.json
+  EVENTS.jsonl
   tasks/
   reports/
 ```
@@ -22,9 +23,9 @@ The directory is git-ignored execution state, not hidden reasoning. Store requir
 
 The V6 engine enforces three boundaries:
 
-1. **Plan gate** — `work plan` leaves the item in `awaiting-plan-approval`. `work start` refuses to run until an independent plan checker PASS is recorded with `work approve-plan`.
+1. **Plan gate** — `work plan` leaves the item in `awaiting-plan-approval`. Long/high-risk plans require a structured `plan-verification` receipt bound to the current plan hash before `work approve-plan` succeeds.
 2. **Concurrent state gate** — all mutable `STATE.json` and `EVIDENCE.json` operations use a per-work-item lock plus atomic file replacement, preventing safe-wave executors from losing each other's state.
-3. **Integration gate** — finalization requires a recorded `verify-integration --verdict PASS`. The engine fingerprints the Git workspace at PASS time and rejects finalization if the workspace changes afterward.
+3. **Integration gate** — long/high-risk PASS requires a structured `integration-verification` receipt bound to the current workspace fingerprint. Finalization rejects any later workspace change.
 
 ## Pipeline
 
@@ -32,15 +33,16 @@ The V6 engine enforces three boundaries:
 2. Write observable acceptance criteria into `SPEC.md`.
 3. Initialize state with `ocskill work init`.
 4. Create `PLAN.json` following the plan schema and import it with `ocskill work plan`.
-5. Run `ues-plan-checker`. If it returns PASS, persist that gate with `ocskill work approve-plan`.
+5. Run `ues-plan-checker`. If it returns PASS, create `work gate-receipt <slug> plan` and persist approval with `work approve-plan --receipt-file ...`.
 6. Use `ocskill task-graph` to compute dependency-safe waves.
 7. For each ready task:
    - on OpenCode V2 prefer `ues.dispatch_task`, which performs `work start`, creates a fresh `ues-executor` session, selects the configured attempt-based model tier, prompts it with a bounded context pack and waits for completion;
    - inspect the child diff and verification;
+   - record at least one successful `work verify-command` receipt for long/high-risk work;
    - persist `work complete --evidence ...` or `work fail --reason ...`.
 8. On failure, re-diagnose rather than stacking patches. A later `ues.dispatch_task` attempt can escalate from standard to heavy when configured.
 9. After all tasks complete, run `ues-integration-verifier`.
-10. Persist the verifier's actual result with `ocskill work verify-integration`.
+10. Persist the verifier's actual result with a structured integration receipt plus `ocskill work verify-integration --receipt-file ...`.
 11. Only a recorded PASS with an unchanged workspace can be finalized.
 
 ## Parallelism

package/lib/aci.mjs

@@ -0,0 +1,128 @@
+import { readFile, stat } from "node:fs/promises"
+import path from "node:path"
+import { buildSemanticIndex, querySemanticIndex } from "./semantic-index.mjs"
+
+function safeFull(root, relative) {
+  const base = path.resolve(root)
+  const full = path.resolve(base, relative)
+  if (full !== base && !full.startsWith(base + path.sep)) {
+    throw new Error("path escapes repository root")
+  }
+  return full
+}
+
+export async function aciSearch(root, query, options = {}) {
+  const result = await querySemanticIndex(root, query, {
+    limit: options.limit ?? 20,
+    rebuild: options.rebuild === true,
+  })
+  return {
+    ...result,
+    contract: {
+      evidenceOnly: true,
+      note: "Results are deterministic syntax-aware lexical evidence, not a claim of semantic correctness.",
+    },
+  }
+}
+
+export async function aciReferences(root, symbol, options = {}) {
+  const name = String(symbol || "").trim()
+  if (!/^[A-Za-z_$][A-Za-z0-9_$.-]*$/.test(name)) {
+    throw new Error("reference symbol must be a concrete identifier")
+  }
+  const built = await buildSemanticIndex(root, { rebuild: options.rebuild === true })
+  const results = []
+  for (const [file, entry] of Object.entries(built.index.files)) {
+    const exact = Number(entry.identifiers?.[name] || 0)
+    const folded = exact || Object.entries(entry.identifiers || {}).find(([key]) => key.toLowerCase() === name.toLowerCase())?.[1] || 0
+    const definitions = (entry.symbols || []).filter((item) => String(item.name).toLowerCase() === name.toLowerCase())
+    if (!folded && !definitions.length) continue
+    results.push({
+      path: file,
+      references: Number(folded || 0),
+      definitions: definitions.slice(0, 12),
+      evidence: definitions.length ? "definition+lexical-reference" : "lexical-reference",
+    })
+  }
+  results.sort((a, b) => (b.definitions.length - a.definitions.length) || b.references - a.references || a.path.localeCompare(b.path))
+  return {
+    schemaVersion: 1,
+    symbol: name,
+    evidenceLevel: "syntax-aware-lexical",
+    results: results.slice(0, Math.max(1, Math.min(Number(options.limit || 40), 200))),
+    stats: built.stats,
+  }
+}
+
+export async function aciView(root, relative, options = {}) {
+  root = path.resolve(root)
+  const full = safeFull(root, relative)
+  const info = await stat(full).catch(() => null)
+  if (!info?.isFile()) throw new Error("file does not exist: " + relative)
+  const maxBytes = Math.max(4 * 1024, Math.min(Number(options.maxBytes || 256 * 1024), 1024 * 1024))
+  if (info.size > maxBytes) throw new Error("file exceeds bounded viewer limit; request a smaller generated artifact or use repository-native tooling")
+  const source = await readFile(full, "utf8")
+  if (source.includes("\0")) throw new Error("binary file is not supported by bounded viewer")
+  const lines = source.split(/\r?\n/)
+  const center = Math.max(1, Number(options.line || 1))
+  const count = Math.max(1, Math.min(Number(options.lines || 120), 240))
+  const start = Math.max(1, Math.min(
+    Number(options.startLine || 0) || (center - Math.floor(count / 3)),
+    Math.max(1, lines.length),
+  ))
+  const end = Math.min(lines.length, start + count - 1)
+  const width = String(end).length
+  return {
+    schemaVersion: 1,
+    path: path.relative(root, full).replaceAll("\\", "/"),
+    startLine: start,
+    endLine: end,
+    totalLines: lines.length,
+    truncated: start > 1 || end < lines.length,
+    text: lines.slice(start - 1, end)
+      .map((line, index) => String(start + index).padStart(width, " ") + " | " + line)
+      .join("\n"),
+  }
+}
+
+export async function aciTextSearch(root, query, options = {}) {
+  const value = String(query || "").trim()
+  if (value.length < 2) throw new Error("search query must contain at least two characters")
+  const candidateLimit = Math.max(1, Math.min(Number(options.candidateLimit || 500), 5000))
+  const resultLimit = Math.max(1, Math.min(Number(options.limit || 80), 200))
+  const semantic = await querySemanticIndex(root, value, { limit: Math.min(candidateLimit, 100) })
+  const built = await buildSemanticIndex(root)
+  const allIndexed = Object.entries(built.index.files)
+    .filter(([, entry]) => !entry?.skipped)
+    .map(([file]) => file)
+  const candidates = [...new Set([
+    ...semantic.results.map((item) => item.path),
+    ...allIndexed,
+  ])].slice(0, candidateLimit)
+  const matches = []
+  const needle = options.caseSensitive ? value : value.toLowerCase()
+  for (const file of candidates) {
+    const full = safeFull(root, file)
+    const source = await readFile(full, "utf8").catch(() => "")
+    if (!source) continue
+    const lines = source.split(/\r?\n/)
+    for (let index = 0; index < lines.length; index += 1) {
+      const haystack = options.caseSensitive ? lines[index] : lines[index].toLowerCase()
+      if (!haystack.includes(needle)) continue
+      matches.push({ path: file, line: index + 1, preview: lines[index].trim().slice(0, 300) })
+      if (matches.length >= resultLimit) break
+    }
+    if (matches.length >= resultLimit) break
+  }
+  return {
+    schemaVersion: 1,
+    query: value,
+    evidenceLevel: "exact-text",
+    matches,
+    candidatesScanned: candidates.length,
+    candidatePool: allIndexed.length,
+    candidateTruncated: candidates.length < allIndexed.length,
+    resultsTruncated: matches.length >= resultLimit,
+    semanticStats: built.stats,
+  }
+}

package/lib/benchmark-confidence.mjs

@@ -0,0 +1,135 @@
+function asBool(value) {
+  return value === true
+}
+
+function pairKey(item) {
+  return [item.suite || "", item.task || "", item.trial || 1].join("::")
+}
+
+function exactSignPValue(a, b) {
+  const n = a + b
+  if (n <= 0) return 1
+  const k = Math.min(a, b)
+  let probability = 2 ** (-n)
+  let cumulative = probability
+  for (let i = 1; i <= k; i += 1) {
+    probability *= (n - i + 1) / i
+    cumulative += probability
+  }
+  return Math.min(1, cumulative * 2)
+}
+
+function mean(values) {
+  const usable = values.filter((value) => Number.isFinite(value))
+  return usable.length ? usable.reduce((sum, value) => sum + value, 0) / usable.length : null
+}
+
+export function pairedBenchmarkConfidence(results, options = {}) {
+  const byKey = new Map()
+  for (const item of results || []) {
+    if (!["baseline", "ues"].includes(item?.mode)) continue
+    const key = pairKey(item)
+    const pair = byKey.get(key) || {}
+    pair[item.mode] = item
+    byKey.set(key, pair)
+  }
+  const pairs = [...byKey.entries()]
+    .filter(([, pair]) => pair.baseline && pair.ues)
+    .map(([key, pair]) => ({ key, ...pair }))
+
+  let bothPass = 0
+  let bothFail = 0
+  let baselineOnly = 0
+  let uesOnly = 0
+  for (const pair of pairs) {
+    const b = asBool(pair.baseline.passed)
+    const u = asBool(pair.ues.passed)
+    if (b && u) bothPass += 1
+    else if (!b && !u) bothFail += 1
+    else if (b) baselineOnly += 1
+    else uesOnly += 1
+  }
+  const total = pairs.length
+  const baselinePassed = bothPass + baselineOnly
+  const uesPassed = bothPass + uesOnly
+  const baselinePassRate = total ? baselinePassed / total : 0
+  const uesPassRate = total ? uesPassed / total : 0
+  const delta = uesPassRate - baselinePassRate
+  const pValue = exactSignPValue(uesOnly, baselineOnly)
+
+  const suites = {}
+  for (const pair of pairs) {
+    const suite = pair.baseline.suite || pair.ues.suite || "unknown"
+    suites[suite] ??= { total: 0, baselinePassed: 0, uesPassed: 0 }
+    suites[suite].total += 1
+    if (pair.baseline.passed) suites[suite].baselinePassed += 1
+    if (pair.ues.passed) suites[suite].uesPassed += 1
+  }
+  for (const item of Object.values(suites)) {
+    item.baselinePassRate = item.total ? item.baselinePassed / item.total : 0
+    item.uesPassRate = item.total ? item.uesPassed / item.total : 0
+    item.delta = item.uesPassRate - item.baselinePassRate
+  }
+
+  const baselineDurations = pairs.map((pair) => Number(pair.baseline.durationMs))
+  const uesDurations = pairs.map((pair) => Number(pair.ues.durationMs))
+  const baselineDuration = mean(baselineDurations)
+  const uesDuration = mean(uesDurations)
+  const durationRatio = baselineDuration && uesDuration ? uesDuration / baselineDuration : null
+
+  const baselineCosts = pairs.map((pair) => Number(pair.baseline.telemetry?.cost)).filter((value) => value > 0)
+  const uesCosts = pairs.map((pair) => Number(pair.ues.telemetry?.cost)).filter((value) => value > 0)
+  const baselineCost = mean(baselineCosts)
+  const uesCost = mean(uesCosts)
+  const costRatio = baselineCost && uesCost ? uesCost / baselineCost : null
+
+  const minPairs = Math.max(1, Number(options.minPairs || 20))
+  const alpha = Math.min(0.5, Math.max(0.0001, Number(options.alpha || 0.05)))
+  const minDelta = Math.max(0, Number(options.minDelta || 0))
+  const suiteRegressionTolerance = Math.max(0, Number(options.suiteRegressionTolerance || 0))
+  const maxDurationRatio = Math.max(1, Number(options.maxDurationRatio || 1.75))
+  const noSuiteRegression = Object.values(suites).every((item) => item.delta >= -suiteRegressionTolerance)
+  const speedAcceptable = durationRatio == null || durationRatio <= maxDurationRatio
+
+  const checks = {
+    pairedCoverage: total >= minPairs,
+    positiveDelta: delta > minDelta,
+    moreWinsThanLosses: uesOnly > baselineOnly,
+    statisticallySupported: pValue <= alpha,
+    noSuiteRegression,
+    speedAcceptable,
+  }
+  return {
+    schemaVersion: 1,
+    kind: "ues-paired-benchmark-confidence",
+    pairs: total,
+    bothPass,
+    bothFail,
+    baselineOnly,
+    uesOnly,
+    baselinePassed,
+    uesPassed,
+    baselinePassRate,
+    uesPassRate,
+    delta,
+    pValue,
+    alpha,
+    minPairs,
+    minDelta,
+    suiteRegressionTolerance,
+    duration: {
+      baselineMeanMs: baselineDuration,
+      uesMeanMs: uesDuration,
+      ratio: durationRatio,
+      maxRatio: maxDurationRatio,
+    },
+    cost: {
+      baselineMean: baselineCost,
+      uesMean: uesCost,
+      ratio: costRatio,
+    },
+    suites,
+    checks,
+    promotionEligible: Object.values(checks).every(Boolean),
+  }
+}

package/lib/cli-utils.mjs

@@ -0,0 +1,41 @@
+import { readFileSync } from "node:fs"
+import path from "node:path"
+
+export function clipOutput(value, { head = 8000, tail = 8000 } = {}) {
+  const text = String(value ?? "")
+  if (text.length <= head + tail) return text
+  return text.slice(0, head) + "\n...[truncated]\n" + text.slice(-tail)
+}
+
+export function positionalArg(args, index) {
+  const value = args[index]
+  if (value == null || value === "" || value === "--" || value.startsWith("--")) return null
+  return value
+}
+
+export function readJsonFile(file) {
+  return JSON.parse(readFileSync(path.resolve(file), "utf8"))
+}
+
+export function readTextFile(file) {
+  return readFileSync(path.resolve(file), "utf8")
+}
+
+export function optionInt(args, name, fallback) {
+  const index = args.indexOf(name)
+  const raw = index >= 0 ? args[index + 1] : null
+  return Number.parseInt(raw || String(fallback), 10)
+}
+
+export function optionIntOrUndefined(args, name) {
+  return optionInt(args, name, 0) || undefined
+}
+
+export function optionValue(args, name) {
+  const index = args.indexOf(name)
+  return index >= 0 ? args[index + 1] : null
+}
+
+export function errorMessage(error) {
+  return error instanceof Error ? error.message : error
+}

package/lib/container-sandbox.mjs

@@ -0,0 +1,102 @@
+import { spawnSync } from "node:child_process"
+import path from "node:path"
+
+function probe(engine) {
+  const result = spawnSync(engine, ["--version"], { encoding: "utf8", timeout: 5000 })
+  return {
+    engine,
+    available: result.status === 0,
+    version: result.status === 0 ? String(result.stdout || result.stderr || "").trim() : null,
+    error: result.status === 0 ? null : String(result.stderr || result.stdout || "").trim() || "unavailable",
+  }
+}
+
+export function containerSandboxCapability(preferred = null) {
+  const names = preferred ? [preferred] : ["docker", "podman"]
+  const probes = names.map(probe)
+  const selected = probes.find((item) => item.available) || null
+  return {
+    schemaVersion: 1,
+    available: Boolean(selected),
+    selected,
+    probes,
+    guarantees: selected ? [
+      "network disabled by default",
+      "Linux capabilities dropped",
+      "no-new-privileges",
+      "read-only container root",
+      "bounded pids/memory/cpu",
+      "only requested workspace bind-mounted read-write",
+      "no host environment secrets forwarded by default",
+    ] : [],
+    limitation: "This isolates deterministic verification commands, not the OpenCode model session itself.",
+  }
+}
+
+function validImage(image) {
+  return /^[A-Za-z0-9][A-Za-z0-9._/:@-]{0,240}$/.test(String(image || ""))
+}
+
+export function buildContainerSandboxArgs(root, image, command, commandArgs = [], options = {}) {
+  if (!validImage(image)) throw new Error("container image is required and must be a concrete image reference")
+  if (!command) throw new Error("sandbox command is required")
+  root = path.resolve(root)
+  const memory = String(options.memory || "2g")
+  const cpus = String(options.cpus || "2")
+  const pids = String(options.pids || "256")
+  const args = [
+    "run", "--rm", "--init",
+    "--network", options.network === "bridge" ? "bridge" : "none",
+    "--cap-drop", "ALL",
+    "--security-opt", "no-new-privileges",
+    "--read-only",
+    "--pids-limit", pids,
+    "--memory", memory,
+    "--cpus", cpus,
+    "--tmpfs", "/tmp:rw,noexec,nosuid,size=256m",
+    "--mount", "type=bind,source=" + root + ",target=/workspace",
+    "--workdir", "/workspace",
+    "--env", "CI=true",
+  ]
+  if (process.platform !== "win32" && typeof process.getuid === "function" && typeof process.getgid === "function") {
+    args.push("--user", process.getuid() + ":" + process.getgid())
+  }
+  args.push(image, command, ...commandArgs)
+  return args
+}
+
+export function runContainerSandbox(root, input = {}) {
+  const capability = containerSandboxCapability(input.engine || null)
+  if (!capability.available) {
+    const error = new Error("container sandbox requested but Docker/Podman is unavailable")
+    error.capability = capability
+    throw error
+  }
+  const args = buildContainerSandboxArgs(root, input.image, input.command, input.args || [], input)
+  const started = Date.now()
+  const result = spawnSync(capability.selected.engine, args, {
+    cwd: path.resolve(root),
+    encoding: "utf8",
+    maxBuffer: Math.max(1024 * 1024, Number(input.maxBuffer || 8 * 1024 * 1024)),
+    timeout: Math.max(1000, Number(input.timeoutMs || 10 * 60_000)),
+    env: {
+      SystemRoot: process.env.SystemRoot,
+      WINDIR: process.env.WINDIR,
+      PATH: process.env.PATH,
+      PATHEXT: process.env.PATHEXT,
+      HOME: process.env.HOME,
+      USERPROFILE: process.env.USERPROFILE,
+    },
+  })
+  return {
+    schemaVersion: 1,
+    engine: capability.selected,
+    args,
+    status: result.status ?? 1,
+    signal: result.signal || null,
+    stdout: String(result.stdout || ""),
+    stderr: String(result.stderr || ""),
+    durationMs: Date.now() - started,
+    timedOut: Boolean(result.error?.code === "ETIMEDOUT"),
+  }
+}