opencode-agent-skill 7.7.0 → 9.0.0

package/lib/context-manifest.mjs

@@ -1,10 +1,22 @@
 import { existsSync } from "node:fs"
 import { readFile, stat } from "node:fs/promises"
+import { spawnSync } from "node:child_process"
 import path from "node:path"
 import { buildRepoGraph } from "./repo-graph.mjs"
 import { taskFiles } from "./task-graph.mjs"
+import { querySemanticIndex } from "./semantic-index.mjs"
 
-const INSTRUCTION_FILES = ["AGENTS.md", "package.json", "pyproject.toml", "Cargo.toml", "go.mod", "pom.xml", "build.gradle", "build.gradle.kts"]
+const ROOT_INSTRUCTIONS = [
+  "AGENTS.md",
+  "package.json",
+  "pyproject.toml",
+  "Cargo.toml",
+  "go.mod",
+  "pom.xml",
+  "build.gradle",
+  "build.gradle.kts",
+]
+const SOURCE_EXT = /\.(?:[cm]?[jt]sx?|py|rb|php|java|kt|kts|cs|go|rs|swift|dart|vue|svelte|sql)$/i
 
 function rel(root, file) {
   return path.relative(root, file).replaceAll("\\", "/")
@@ -14,31 +26,248 @@ function unique(values) {
   return [...new Set(values.filter(Boolean))]
 }
 
+function safeFull(root, relative) {
+  const base = path.resolve(root)
+  const full = path.resolve(base, relative)
+  if (full !== base && !full.startsWith(base + path.sep)) return null
+  return full
+}
+
 async function fileInfo(root, relative) {
-  const full = path.resolve(root, relative)
-  if (!full.startsWith(path.resolve(root) + path.sep) && full !== path.resolve(root)) return null
+  const full = safeFull(root, relative)
+  if (!full) return null
   const info = await stat(full).catch(() => null)
   if (!info?.isFile()) return null
   return { path: rel(root, full), bytes: info.size }
 }
 
-async function excerpt(root, relative, limit) {
-  const full = path.resolve(root, relative)
+function centeredSlice(source, terms, limit) {
+  if (source.length <= limit) return { text: source, startOffset: 0, centerTerm: null }
+  const lower = source.toLowerCase()
+  let matchIndex = -1
+  let centerTerm = null
+  for (const term of terms || []) {
+    const index = lower.indexOf(term.toLowerCase())
+    if (index >= 0 && (matchIndex < 0 || index < matchIndex)) {
+      matchIndex = index
+      centerTerm = term
+    }
+  }
+  if (matchIndex < 0) return { text: source.slice(0, limit) + "\n...[truncated]", startOffset: 0, centerTerm: null }
+  const start = Math.max(0, Math.min(matchIndex - Math.floor(limit / 3), source.length - limit))
+  const prefix = start > 0 ? "...[truncated]\n" : ""
+  const suffix = start + limit < source.length ? "\n...[truncated]" : ""
+  return {
+    text: prefix + source.slice(start, start + limit) + suffix,
+    startOffset: start,
+    centerTerm,
+  }
+}
+
+async function excerpt(root, relative, limit, terms = []) {
+  const full = safeFull(root, relative)
+  if (!full) return null
   const source = await readFile(full, "utf8").catch(() => "")
   if (!source) return null
+  const slice = centeredSlice(source, terms, limit)
   return {
     path: rel(root, full),
-    text: source.length <= limit ? source : source.slice(0, limit) + "\n...[truncated]",
+    ...slice,
   }
 }
 
+function taskTerms(task) {
+  const source = [
+    task?.title,
+    task?.summary,
+    ...(task?.acceptance || []),
+    ...(task?.verification || []),
+  ].filter(Boolean).join(" ").toLowerCase()
+
+  const stop = new Set([
+    "this","that","with","from","into","then","than","when","where","what","your",
+    "task","test","tests","file","files","code","change","changes","should","must",
+    "được","các","cho","với","trong","này","một","những","không","theo","sau",
+  ])
+  return unique(
+    source
+      .split(/[^\p{L}\p{N}_$.-]+/u)
+      .map((item) => item.replace(/^[-.$]+|[-.$]+$/g, ""))
+      .filter((item) => item.length >= 4 && !stop.has(item)),
+  ).slice(0, 24)
+}
+
+function tokenCounts(text, wantedTerms) {
+  const counts = new Map()
+  const wanted = new Set(wantedTerms)
+  const tokens = String(text || "")
+    .toLowerCase()
+    .split(/[^\p{L}\p{N}_$.-]+/u)
+    .filter(Boolean)
+  for (const token of tokens) {
+    if (!wanted.has(token)) continue
+    counts.set(token, (counts.get(token) || 0) + 1)
+  }
+  return { counts, length: tokens.length }
+}
+
+function symbolHits(source, terms, limit = 12) {
+  const hits = []
+  const lines = String(source || "").split(/\r?\n/)
+  const patterns = [
+    /(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/,
+    /(?:export\s+)?class\s+([A-Za-z_$][\w$]*)/,
+    /(?:export\s+)?interface\s+([A-Za-z_$][\w$]*)/,
+    /(?:export\s+)?type\s+([A-Za-z_$][\w$]*)/,
+    /(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)/,
+    /^\s*(?:async\s+)?def\s+([A-Za-z_][\w]*)/,
+    /^\s*class\s+([A-Za-z_][\w]*)/,
+    /^\s*(?:public|private|protected|internal|static|final|virtual|override|async|synchronized|abstract|sealed|partial|readonly|\s)+[\w<>,?\[\].:]+\s+([A-Za-z_$][\w$]*)\s*\(/,
+  ]
+  for (let index = 0; index < lines.length && hits.length < limit; index += 1) {
+    const line = lines[index]
+    let symbol = null
+    for (const pattern of patterns) {
+      const match = line.match(pattern)
+      if (match?.[1]) {
+        symbol = match[1]
+        break
+      }
+    }
+    if (!symbol) continue
+    const haystack = (symbol + " " + line).toLowerCase()
+    const matches = terms.filter((term) => haystack.includes(term.toLowerCase()))
+    if (!matches.length) continue
+    hits.push({ symbol, line: index + 1, matches: unique(matches).slice(0, 6), preview: line.trim().slice(0, 240) })
+  }
+  return hits
+}
+
+function gitChangedFiles(root) {
+  const result = spawnSync(
+    "git",
+    ["status", "--porcelain=v1", "--untracked-files=all"],
+    { cwd: root, encoding: "utf8", maxBuffer: 4 * 1024 * 1024 },
+  )
+  if (result.status !== 0) return []
+  return unique(
+    result.stdout
+      .split(/\r?\n/)
+      .filter(Boolean)
+      .map((line) => line.slice(3).trim())
+      .map((value) => value.includes(" -> ") ? value.split(" -> ").at(-1) : value)
+      .map((value) => value.replaceAll("\\", "/")),
+  )
+}
+
+async function nearbyInstructions(root, declared) {
+  const found = new Set()
+  for (const name of ROOT_INSTRUCTIONS) {
+    if (existsSync(path.join(root, name))) found.add(name)
+  }
+
+  for (const file of declared) {
+    let dir = path.dirname(file)
+    while (dir && dir !== ".") {
+      for (const name of ["AGENTS.md", "package.json", "pyproject.toml", "Cargo.toml", "go.mod"]) {
+        const candidate = path.posix.join(dir.replaceAll("\\", "/"), name)
+        if (existsSync(path.join(root, candidate))) found.add(candidate)
+      }
+      const next = path.dirname(dir)
+      if (next === dir) break
+      dir = next
+    }
+  }
+  return [...found]
+}
+
+async function rankedReferences(root, nodes, terms, declared, changed, limit = 24) {
+  if (!terms.length) return []
+  const declaredSet = new Set(declared)
+  const changedSet = new Set(changed)
+  const candidates = nodes
+    .map((node) => node.path)
+    .filter((file) => SOURCE_EXT.test(file))
+    .filter((file) => !declaredSet.has(file))
+    .slice(0, 500)
+
+  const docs = []
+  const documentFrequency = new Map(terms.map((term) => [term, 0]))
+  for (const file of candidates) {
+    const full = safeFull(root, file)
+    const info = full ? await stat(full).catch(() => null) : null
+    if (!info?.isFile() || info.size > 512 * 1024) continue
+    const source = await readFile(full, "utf8").catch(() => "")
+    if (!source) continue
+    const stats = tokenCounts(source, terms)
+    for (const term of terms) {
+      if ((stats.counts.get(term) || 0) > 0) {
+        documentFrequency.set(term, (documentFrequency.get(term) || 0) + 1)
+      }
+    }
+    docs.push({ file, source, stats })
+  }
+
+  const population = Math.max(1, docs.length)
+  const scored = []
+  for (const doc of docs) {
+    const lowerPath = doc.file.toLowerCase()
+    let score = changedSet.has(doc.file) ? 8 : 0
+    const matches = []
+    for (const term of terms) {
+      if (lowerPath.includes(term)) score += 6
+      const tf = doc.stats.counts.get(term) || 0
+      if (tf > 0) {
+        const df = documentFrequency.get(term) || 0
+        const idf = Math.log((population + 1) / (df + 1)) + 1
+        score += (1 + Math.log(tf)) * idf * 3
+        if (matches.length < 8) matches.push(term)
+      }
+    }
+    const symbols = symbolHits(doc.source, terms)
+    score += symbols.length * 4
+    if (score > 0) {
+      scored.push({
+        path: doc.file,
+        score: Number(score.toFixed(3)),
+        matches,
+        symbolHits: symbols,
+      })
+    }
+  }
+
+  return scored
+    .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path))
+    .slice(0, limit)
+}
+
 export async function buildContextManifest(root, task, options = {}) {
   root = path.resolve(root)
   const budget = Math.max(4_000, Number(options.budget ?? 24_000))
   const declared = taskFiles(task)
-  const graph = await buildRepoGraph(root, { maxFiles: options.maxFiles ?? 2500 })
+  const terms = taskTerms(task)
+  const changed = gitChangedFiles(root)
+  const strategy = String(options.strategy || "semantic+graph+git")
+  const queryText = [
+    task?.title,
+    task?.summary,
+    ...(task?.acceptance || []),
+    ...(task?.verification || []),
+  ].filter(Boolean).join(" ")
+
+  const semantic = await querySemanticIndex(root, queryText, {
+    limit: 32,
+    maxFiles: options.semanticMaxFiles ?? 6000,
+  }).catch(() => null)
+  const semanticPaths = semantic?.results?.map((item) => item.path) || []
+
+  const useGraph = strategy.includes("graph")
+  const graph = useGraph
+    ? await buildRepoGraph(root, { maxFiles: options.maxFiles ?? 2500 })
+    : { nodes: [], edges: [], hotspots: [], scannedFiles: 0, truncated: false }
   const nodeMap = new Map(graph.nodes.map((node) => [node.path, node]))
   const incoming = new Map()
+
   for (const edge of graph.edges) {
     const list = incoming.get(edge.to) || []
     list.push(edge.from)
@@ -52,45 +281,93 @@ export async function buildContextManifest(root, task, options = {}) {
   }
 
   const baseNames = declared.map((file) => path.basename(file, path.extname(file)).toLowerCase())
-  const tests = graph.nodes
-    .map((node) => node.path)
+  const graphTestCandidates = graph.nodes.map((node) => node.path)
+  const semanticTestCandidates = semanticPaths
+  const tests = unique([...graphTestCandidates, ...semanticTestCandidates])
     .filter((file) => /(^|\/)(test|tests|__tests__|spec)(\/|$)|\.(test|spec)\./i.test(file))
-    .filter((file) => baseNames.some((name) => name && file.toLowerCase().includes(name)))
-    .slice(0, 20)
+    .map((file) => ({
+      file,
+      score: baseNames.reduce((sum, name) => sum + (name && file.toLowerCase().includes(name) ? 2 : 0), 0) +
+        terms.reduce((sum, term) => sum + (file.toLowerCase().includes(term) ? 1 : 0), 0),
+    }))
+    .filter((item) => item.score > 0 || semanticPaths.includes(item.file))
+    .sort((a, b) => b.score - a.score || a.file.localeCompare(b.file))
+    .slice(0, 24)
+    .map((item) => item.file)
 
-  const instructions = []
-  for (const name of INSTRUCTION_FILES) {
-    if (existsSync(path.join(root, name))) instructions.push(name)
-  }
+  const instructions = await nearbyInstructions(root, declared)
+  const ranked = semantic?.results?.length
+    ? semantic.results.map((item) => ({
+        path: item.path,
+        score: item.score,
+        matches: item.reasons || [],
+        symbolHits: item.definitions || [],
+        evidenceLevel: semantic.evidenceLevel,
+      }))
+    : useGraph
+      ? await rankedReferences(root, graph.nodes, terms, declared, changed)
+      : []
+  const changedRelevant = changed
+    .filter((file) =>
+      declared.includes(file) ||
+      semanticPaths.includes(file) ||
+      graph.nodes.some((node) => node.path === file),
+    )
+    .slice(0, 30)
+
+  const priority = unique([
+    ...declared,
+    ...tests,
+    ...related.slice(0, 20),
+    ...ranked.map((item) => item.path),
+    ...changedRelevant,
+    ...instructions,
+  ])
 
-  const candidates = unique([...declared, ...related.slice(0, 30), ...tests, ...instructions])
   const files = []
-  for (const file of candidates) {
+  for (const file of priority) {
     const info = await fileInfo(root, file)
     if (info) files.push(info)
   }
 
   let remaining = budget
   const excerpts = []
-  for (const file of unique([...declared, ...tests, ...related.slice(0, 12), ...instructions])) {
+  for (const file of priority) {
     if (remaining <= 0) break
-    const perFile = Math.min(4_000, remaining)
-    const item = await excerpt(root, file, perFile)
+    const isDeclared = declared.includes(file)
+    const isTest = tests.includes(file)
+    const isInstruction = instructions.includes(file)
+    const desired = isDeclared ? 6_000 : isTest ? 4_000 : isInstruction ? 3_000 : 2_500
+    const perFile = Math.min(desired, remaining)
+    const item = await excerpt(root, file, perFile, terms)
     if (!item) continue
     remaining -= item.text.length
-    excerpts.push(item)
+    excerpts.push({
+      ...item,
+      role: isDeclared ? "declared" : isTest ? "test" : isInstruction ? "instruction" : "reference",
+    })
   }
 
   return {
-    schemaVersion: 1,
+    schemaVersion: 4,
     task: task?.id || null,
+    strategy,
+    queryTerms: terms,
     declared,
     related: unique(related).filter((file) => !declared.includes(file)).slice(0, 30),
     tests,
     instructions,
+    changed: changedRelevant,
+    rankedReferences: ranked,
     files,
     excerpts,
+    semantic: semantic ? {
+      evidenceLevel: semantic.evidenceLevel,
+      resultCount: semantic.results.length,
+      stats: semantic.stats,
+    } : null,
     graph: {
+      enabled: useGraph,
       scannedFiles: graph.scannedFiles,
       truncated: graph.truncated,
       hotspots: graph.hotspots.slice(0, 12),
@@ -99,3 +376,4 @@ export async function buildContextManifest(root, task, options = {}) {
     used: budget - remaining,
   }
 }
+

package/lib/control-center.mjs

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs"
 import { mkdir, readFile, readdir, writeFile } from "node:fs/promises"
 import path from "node:path"
 import { readLearningState } from "./learning-engine.mjs"
+import { readRuntimeEvents } from "./runtime-events.mjs"
 
 function escapeHtml(value) {
   return String(value ?? "")
@@ -22,10 +23,11 @@ async function collectWork(root) {
   for (const entry of entries) {
     if (!entry.isDirectory()) continue
     const dir = path.join(workRoot, entry.name)
-    const [state, plan, evidence] = await Promise.all([
+    const [state, plan, evidence, events] = await Promise.all([
       readJson(path.join(dir, "STATE.json"), {}),
       readJson(path.join(dir, "PLAN.json"), {}),
       readJson(path.join(dir, "EVIDENCE.json"), {}),
+      readRuntimeEvents(path.join(dir, "EVENTS.jsonl"), { limit: 30 }),
     ])
     items.push({
       slug: entry.name,
@@ -39,7 +41,8 @@ async function collectWork(root) {
         risk: task.risk || "medium",
         state: state.tasks?.[task.id] || {},
       })),
-      receipts: (evidence.receipts || []).length,
+      receipts: evidence.receipts || [],
+      recentEvents: events,
       updatedAt: state.updatedAt || null,
     })
   }
@@ -92,12 +95,15 @@ h1{margin:0;font-size:30px}.muted{color:#9da9bd}.grid{display:grid;grid-template
 .task{display:grid;grid-template-columns:1fr auto;gap:8px;border-top:1px solid #243049;padding:9px 0}.ok{color:#7ee787}.warn{color:#f2cc60}.bad{color:#ff7b72}
 table{width:100%;border-collapse:collapse;margin-top:10px}th,td{text-align:left;padding:8px;border-bottom:1px solid #26324a;font-size:13px}
 pre{white-space:pre-wrap;word-break:break-word;background:#0a0f1c;padding:10px;border-radius:10px}.section{margin-top:28px}
+button{margin-top:10px;border:1px solid #3b4966;border-radius:8px;background:#18233a;color:#e7ecf5;padding:7px 10px;cursor:pointer}button:disabled{opacity:.55;cursor:wait}
+details{margin-top:10px;border-top:1px solid #243049;padding-top:8px}summary{cursor:pointer;color:#c9d4e7}
 </style>
 </head>
 <body><div class="shell">
 <div class="top"><div><h1>UES Control Center</h1><div class="muted" id="root"></div></div><div class="muted" id="generated"></div></div>
 <div class="section"><h2>Long-horizon work</h2><div class="grid" id="work"></div></div>
 <div class="section"><h2>Learning loop</h2><div class="grid" id="learning"></div></div>
+<div class="section"><h2>Recent runtime events</h2><div class="card"><table><thead><tr><th>Work</th><th>Event</th><th>Task</th><th>Time</th></tr></thead><tbody id="events"></tbody></table></div></div>
 <div class="section"><h2>Recent evaluations</h2><div class="card"><table><thead><tr><th>Suite</th><th>Model</th><th>Baseline</th><th>UES</th></tr></thead><tbody id="evals"></tbody></table></div></div>
 </div>
 <script>
@@ -111,11 +117,22 @@ function render(next){
  work.innerHTML="";
  for(const item of data.work){
   const tasks=item.tasks.map(t=>'<div class="task"><span>'+esc(t.id)+' · '+esc(t.title||'')+'</span><span class="pill">'+esc(t.state.status||'pending')+'</span></div>').join('');
-  work.insertAdjacentHTML("beforeend",'<div class="card"><div><span class="pill">'+esc(item.status)+'</span></div><h3>'+esc(item.slug)+'</h3><div class="muted">'+esc(item.goal)+'</div><p>'+esc(item.nextAction)+'</p>'+tasks+'<div class="muted">receipts: '+item.receipts+' · blockers: '+item.blockers.length+'</div></div>');
+  const recover=(item.tasks||[]).some(t=>t.state?.status==="running")?'<button data-recover="'+esc(item.slug)+'">Recover stale</button>':'';
+  const receipts=(item.receipts||[]).length
+    ? '<details><summary>Inspect receipts ('+item.receipts.length+')</summary><pre>'+esc(JSON.stringify(item.receipts,null,2))+'</pre></details>'
+    : '';
+  work.insertAdjacentHTML("beforeend",'<div class="card"><div><span class="pill">'+esc(item.status)+'</span></div><h3>'+esc(item.slug)+'</h3><div class="muted">'+esc(item.goal)+'</div><p>'+esc(item.nextAction)+'</p>'+tasks+'<div class="muted">receipts: '+item.receipts.length+' · blockers: '+item.blockers.length+'</div>'+recover+receipts+'</div>');
  }
  if(!data.work.length) work.innerHTML='<div class="card muted">No .ues-work items found.</div>';
  const learning=document.querySelector("#learning");
  learning.innerHTML='<div class="card"><h3>Accepted lessons</h3><strong>'+data.learning.accepted.length+'</strong></div><div class="card"><h3>Proposals</h3><strong>'+data.learning.proposals.length+'</strong></div>';
+ const eventBody=document.querySelector("#events");
+ eventBody.innerHTML="";
+ for(const item of data.work){
+  for(const event of (item.recentEvents||[]).slice(-10).reverse()){
+   eventBody.insertAdjacentHTML("beforeend",'<tr><td>'+esc(item.slug)+'</td><td>'+esc(event.type)+'</td><td>'+esc(event.task||"—")+'</td><td>'+esc(event.at||"")+'</td></tr>');
+  }
+ }
  const tbody=document.querySelector("#evals");
  tbody.innerHTML="";
  for(const row of data.evals){
@@ -123,6 +140,22 @@ function render(next){
   tbody.insertAdjacentHTML("beforeend",'<tr><td>'+esc(row.suite)+'</td><td>'+esc(row.model)+'</td><td>'+fmt(row.summary.baseline)+'</td><td>'+fmt(row.summary.ues)+'</td></tr>');
  }
 }
+document.addEventListener("click",async(event)=>{
+ const button=event.target.closest?.("[data-recover]");
+ if(!button) return;
+ button.disabled=true;
+ try{
+  const response=await fetch("/api/recover",{
+   method:"POST",
+   headers:{"content-type":"application/json"},
+   body:JSON.stringify({slug:button.dataset.recover})
+  });
+  if(!response.ok) throw new Error(await response.text());
+  const refreshed=await fetch("/data.json",{cache:"no-store"});
+  if(refreshed.ok) render(await refreshed.json());
+ }catch(error){ alert(String(error?.message||error)); }
+ finally{ button.disabled=false; }
+});
 render(data);
 if(location.protocol==="http:" || location.protocol==="https:"){
  setInterval(async()=>{

package/lib/eval-order.mjs

@@ -0,0 +1,9 @@
+export function evalModeOrder(requestedMode, taskIndex = 0, trial = 1) {
+  if (requestedMode === "baseline" || requestedMode === "ues") return [requestedMode]
+  if (requestedMode !== "both") throw new Error("requestedMode must be baseline, ues, or both")
+
+  const normalizedTaskIndex = Number.isInteger(taskIndex) && taskIndex >= 0 ? taskIndex : 0
+  const normalizedTrial = Number.isInteger(trial) && trial > 0 ? trial : 1
+  const baselineFirst = (normalizedTaskIndex + normalizedTrial) % 2 === 1
+  return baselineFirst ? ["baseline", "ues"] : ["ues", "baseline"]
+}

package/lib/eval-telemetry.mjs

@@ -19,8 +19,11 @@ function visit(value, callback, path = []) {
 }
 
 function usageFromObject(object) {
-  const usage = object?.usage
-  if (!usage || typeof usage !== "object") return null
+  const usage =
+    object?.usage && typeof object.usage === "object" ? object.usage :
+    object?.tokens && typeof object.tokens === "object" ? object.tokens :
+    null
+  if (!usage) return null
 
   const input =
     asNumber(usage.inputTokens) ||

package/lib/gate-receipt.mjs

@@ -0,0 +1,52 @@
+import { createHash, randomUUID } from "node:crypto"
+
+const KINDS = new Set(["plan-verification", "integration-verification"])
+const VERDICTS = new Set(["PASS", "FAIL", "PARTIAL"])
+
+function digest(value) {
+  return createHash("sha256").update(String(value || "")).digest("hex")
+}
+
+export function createGateReceipt(input = {}) {
+  const kind = String(input.kind || "")
+  const verdict = String(input.verdict || "").toUpperCase()
+  const evidence = String(input.evidence || "").trim()
+  const report = input.report == null ? null : String(input.report)
+  return {
+    schemaVersion: 1,
+    id: randomUUID(),
+    kind,
+    slug: String(input.slug || ""),
+    verdict,
+    verifier: String(input.verifier || ""),
+    sessionID: input.sessionID ? String(input.sessionID) : null,
+    runId: input.runId ? String(input.runId) : null,
+    planHash: input.planHash ? String(input.planHash) : null,
+    workspaceFingerprint: input.workspaceFingerprint ? String(input.workspaceFingerprint) : null,
+    evidence,
+    reportHash: report == null ? null : digest(report),
+    createdAt: input.createdAt || new Date().toISOString(),
+  }
+}
+
+export function validateGateReceipt(receipt) {
+  const errors = []
+  if (!receipt || typeof receipt !== "object" || Array.isArray(receipt)) {
+    return { valid: false, errors: ["receipt must be an object"] }
+  }
+  if (receipt.schemaVersion !== 1) errors.push("schemaVersion must be 1")
+  if (!KINDS.has(receipt.kind)) errors.push("invalid gate receipt kind")
+  if (!VERDICTS.has(receipt.verdict)) errors.push("invalid gate receipt verdict")
+  if (!String(receipt.id || "").trim()) errors.push("receipt id is required")
+  if (!String(receipt.slug || "").trim()) errors.push("slug is required")
+  if (!String(receipt.verifier || "").trim()) errors.push("verifier is required")
+  if (!String(receipt.evidence || "").trim()) errors.push("evidence is required")
+  if (!Number.isFinite(Date.parse(receipt.createdAt || ""))) errors.push("createdAt must be an ISO timestamp")
+  if (receipt.kind === "plan-verification" && !String(receipt.planHash || "").trim()) {
+    errors.push("plan verification receipt requires planHash")
+  }
+  if (receipt.kind === "integration-verification" && !String(receipt.workspaceFingerprint || "").trim()) {
+    errors.push("integration verification receipt requires workspaceFingerprint")
+  }
+  return { valid: errors.length === 0, errors }
+}