opencode-agent-skill 7.7.0 → 10.0.0

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 }
+}

package/lib/installer.mjs

@@ -11,7 +11,8 @@ export { SKILL_PREFIX } from "./ids.mjs"
 
 export const PACKAGE_NAME = "opencode-agent-skill"
 export const LEGACY_PACKAGE_NAME = "@laivannha0202/opencode-agent-skill"
-export const MANAGED_MARKER = "<!-- managed-by: @laivannha0202/opencode-agent-skill -->"
+export const MANAGED_MARKER = "<!-- managed-by: opencode-agent-skill -->"
+export const LEGACY_MANAGED_MARKER = "<!-- managed-by: @laivannha0202/opencode-agent-skill -->"
 export const AGENTS_BEGIN = "<!-- BEGIN OCSKILL UNIVERSAL ENGINEERING SYSTEM -->"
 export const AGENTS_END = "<!-- END OCSKILL UNIVERSAL ENGINEERING SYSTEM -->"
 
@@ -26,6 +27,15 @@ function isOwnedPackageName(value) {
   return !value || value === PACKAGE_NAME || value === LEGACY_PACKAGE_NAME
 }
 
+function hasManagedMarker(source) {
+  const text = String(source || "")
+  return text.includes(MANAGED_MARKER) || text.includes(LEGACY_MANAGED_MARKER)
+}
+
+function normalizeManagedMarker(source) {
+  return String(source || "").replaceAll(LEGACY_MANAGED_MARKER, MANAGED_MARKER)
+}
+
 export function getConfigDir() {
   return process.env.OPENCODE_CONFIG_DIR
     ? path.resolve(process.env.OPENCODE_CONFIG_DIR)
@@ -47,8 +57,10 @@ async function packageVersion() {
 }
 
 function installSkillName(source, name) {
-  const next = source.replace(/^name:\s*[^\r\n]+/m, `name: ${SKILL_PREFIX}${name}`)
-  return next.includes(MANAGED_MARKER)
+  const next = normalizeManagedMarker(
+    source.replace(/^name:\s*[^\r\n]+/m, `name: ${SKILL_PREFIX}${name}`),
+  )
+  return hasManagedMarker(next)
     ? next
     : `${next.trimEnd()}\n\n${MANAGED_MARKER}\n`
 }
@@ -69,7 +81,7 @@ function removeManagedBlock(source) {
 async function writeManagedFile(file, content, warnings) {
   if (existsSync(file)) {
     const current = await readText(file)
-    if (!current.includes(MANAGED_MARKER)) {
+    if (!hasManagedMarker(current)) {
       warnings.push(`Skipped existing unmanaged file: ${file}`)
       return false
     }
@@ -121,7 +133,7 @@ async function cleanupStaleManaged(configDir, previousState, installed, warnings
     const dir = path.join(configDir, "skills", id)
     const markerFile = path.join(dir, "SKILL.md")
     const current = await readText(markerFile)
-    if (current.includes(MANAGED_MARKER)) {
+    if (hasManagedMarker(current)) {
       await rm(dir, { recursive: true, force: true })
     } else if (existsSync(dir)) {
       warnings.push(`Preserved stale skill without UES marker: ${dir}`)
@@ -132,7 +144,7 @@ async function cleanupStaleManaged(configDir, previousState, installed, warnings
     if (currentCommands.has(name) || !validManagedMarkdown(name)) continue
     const file = path.join(configDir, "commands", name)
     const current = await readText(file)
-    if (current.includes(MANAGED_MARKER)) {
+    if (hasManagedMarker(current)) {
       await rm(file, { force: true })
     } else if (existsSync(file)) {
       warnings.push(`Preserved stale command without UES marker: ${file}`)
@@ -143,7 +155,7 @@ async function cleanupStaleManaged(configDir, previousState, installed, warnings
     if (currentAgents.has(name) || !validManagedMarkdown(name)) continue
     const file = path.join(configDir, "agents", name)
     const current = await readText(file)
-    if (current.includes(MANAGED_MARKER)) {
+    if (hasManagedMarker(current)) {
       await rm(file, { force: true })
     } else if (existsSync(file)) {
       warnings.push(`Preserved stale subagent without UES marker: ${file}`)
@@ -154,7 +166,7 @@ async function cleanupStaleManaged(configDir, previousState, installed, warnings
     if (currentPlugins.has(name) || !validManagedPlugin(name)) continue
     const file = path.join(configDir, "plugins", name)
     const current = await readText(file)
-    if (current.includes(MANAGED_MARKER)) {
+    if (hasManagedMarker(current)) {
       await rm(path.dirname(file), { recursive: true, force: true })
     } else if (existsSync(file)) {
       warnings.push(`Preserved stale plugin without UES marker: ${file}`)
@@ -169,7 +181,7 @@ async function scanUntrackedManaged(configDir) {
   for (const entry of await readdir(skillsDir, { withFileTypes: true }).catch(() => [])) {
     if (!entry.isDirectory() || !validSkillID(entry.name)) continue
     const current = await readText(path.join(skillsDir, entry.name, "SKILL.md"))
-    if (current.includes(MANAGED_MARKER)) found.skills.push(entry.name)
+    if (hasManagedMarker(current)) found.skills.push(entry.name)
   }
 
   for (const [targetDir, key] of [
@@ -179,13 +191,13 @@ async function scanUntrackedManaged(configDir) {
     for (const entry of await readdir(targetDir, { withFileTypes: true }).catch(() => [])) {
       if (!entry.isFile() || !validManagedMarkdown(entry.name)) continue
       const current = await readText(path.join(targetDir, entry.name))
-      if (current.includes(MANAGED_MARKER)) found[key].push(entry.name)
+      if (hasManagedMarker(current)) found[key].push(entry.name)
     }
   }
 
   const routerFile = path.join(configDir, "plugins", ROUTER_PLUGIN_STATE)
   const routerCurrent = await readText(routerFile)
-  if (routerCurrent.includes(MANAGED_MARKER)) found.plugins.push(ROUTER_PLUGIN_STATE)
+  if (hasManagedMarker(routerCurrent)) found.plugins.push(ROUTER_PLUGIN_STATE)
 
   return found
 }
@@ -239,7 +251,7 @@ async function installSkillDirectory(sourceDir, targetDir, sourceName, warnings)
     }
 
     const current = await readText(targetSkill)
-    if (!current.includes(MANAGED_MARKER)) {
+    if (!hasManagedMarker(current)) {
       warnings.push(`Skipped existing unmanaged skill: ${targetSkill}`)
       return false
     }
@@ -265,7 +277,7 @@ async function installPluginDirectory(sourceDir, targetDir, warnings) {
     }
 
     const current = await readText(targetEntry)
-    if (!current.includes(MANAGED_MARKER)) {
+    if (!hasManagedMarker(current)) {
       warnings.push(`Skipped existing unmanaged plugin: ${targetEntry}`)
       return false
     }
@@ -276,10 +288,10 @@ async function installPluginDirectory(sourceDir, targetDir, warnings) {
   await mkdir(path.dirname(targetDir), { recursive: true })
   await cp(sourceDir, targetDir, { recursive: true })
 
-  const copiedEntry = await readFile(targetEntry, "utf8")
+  const copiedEntry = normalizeManagedMarker(await readFile(targetEntry, "utf8"))
   await writeFile(
     targetEntry,
-    copiedEntry.includes(MANAGED_MARKER)
+    hasManagedMarker(copiedEntry)
       ? copiedEntry
       : `${copiedEntry.trimEnd()}\n\n// ${MANAGED_MARKER}\n`,
     "utf8",
@@ -366,9 +378,10 @@ export async function installResources(options = {}) {
     const targetName = `${SKILL_PREFIX}${id}.md`
     const targetFile = path.join(commandsTarget, targetName)
     const source = await readFile(path.join(sourceCommands, entry.name), "utf8")
-    const content = source.includes(MANAGED_MARKER)
-      ? source
-      : `${source.trimEnd()}\n\n${MANAGED_MARKER}\n`
+    const normalizedSource = normalizeManagedMarker(source)
+    const content = hasManagedMarker(normalizedSource)
+      ? normalizedSource
+      : `${normalizedSource.trimEnd()}\n\n${MANAGED_MARKER}\n`
 
     if (await writeManagedFile(targetFile, content, warnings)) {
       installed.commands.push(targetName)
@@ -396,9 +409,10 @@ export async function installResources(options = {}) {
       id,
       modelPolicy,
     )
-    const content = source.includes(MANAGED_MARKER)
-      ? source
-      : `${source.trimEnd()}\n\n${MANAGED_MARKER}\n`
+    const normalizedSource = normalizeManagedMarker(source)
+    const content = hasManagedMarker(normalizedSource)
+      ? normalizedSource
+      : `${normalizedSource.trimEnd()}\n\n${MANAGED_MARKER}\n`
 
     if (await writeManagedFile(targetFile, content, warnings)) {
       installed.agents.push(targetName)
@@ -529,7 +543,7 @@ export async function removeResources(options = {}) {
     const dir = path.join(configDir, "skills", id)
     const file = path.join(dir, "SKILL.md")
     const current = await readText(file)
-    if (current.includes(MANAGED_MARKER)) {
+    if (hasManagedMarker(current)) {
       await rm(dir, { recursive: true, force: true })
       removed.skills += 1
     }
@@ -539,7 +553,7 @@ export async function removeResources(options = {}) {
     if (!validManagedMarkdown(name)) continue
     const file = path.join(configDir, "commands", name)
     const current = await readText(file)
-    if (current.includes(MANAGED_MARKER)) {
+    if (hasManagedMarker(current)) {
       await rm(file, { force: true })
       removed.commands += 1
     }
@@ -549,7 +563,7 @@ export async function removeResources(options = {}) {
     if (!validManagedMarkdown(name)) continue
     const file = path.join(configDir, "agents", name)
     const current = await readText(file)
-    if (current.includes(MANAGED_MARKER)) {
+    if (hasManagedMarker(current)) {
       await rm(file, { force: true })
       removed.agents += 1
     }
@@ -559,7 +573,7 @@ export async function removeResources(options = {}) {
     if (!validManagedPlugin(name)) continue
     const file = path.join(configDir, "plugins", name)
     const current = await readText(file)
-    if (current.includes(MANAGED_MARKER)) {
+    if (hasManagedMarker(current)) {
       await rm(path.dirname(file), { recursive: true, force: true })
       removed.plugins += 1
     }

package/lib/learning-engine.mjs

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs"
 import { mkdir, readFile, readdir, writeFile } from "node:fs/promises"
 import { createHash } from "node:crypto"
 import path from "node:path"
+import { pairedBenchmarkConfidence } from "./benchmark-confidence.mjs"
 
 const LEARNING_DIR = ".ues-learning"
 const STATE_FILE = "LEARNINGS.json"
@@ -26,8 +27,46 @@ async function walkJson(dir, limit = 500) {
   return files
 }
 
+function failureReasons(item) {
+  const reasons = []
+  if (item.timedOut) reasons.push("hard-timeout")
+  if (item.idleTimedOut) reasons.push("idle-timeout")
+  if (Number(item.agentExit) !== 0) reasons.push("agent-exit")
+  if (Number(item.graderExit) !== 0) reasons.push("grader-failure")
+  if (item.orchestration?.required && !item.orchestration?.valid) reasons.push("orchestration-failure")
+  if ((item.telemetry?.parseErrors || 0) > 0) reasons.push("telemetry-parse-errors")
+  return reasons
+}
+
+function recommendationFor(key) {
+  const recommendations = {
+    "hard-timeout": "Split oversized execution units or justify a larger bounded timeout; preserve cancellation and stale-run recovery.",
+    "idle-timeout": "Inspect tool/session deadlocks and add observable progress boundaries or recovery paths.",
+    "agent-exit": "Classify provider/process failures before retrying; avoid blind model escalation.",
+    "grader-failure": "Mine the failed contract for missing context, routing or verification guidance and add a regression before promotion.",
+    "orchestration-failure": "Strengthen durable workflow gates/runtime support; direct patches must not count as long-horizon success.",
+    "telemetry-parse-errors": "Update telemetry parsing against the observed event shape with fixture-backed tests.",
+  }
+  return recommendations[key] || "Add a regression, test the candidate rule in shadow evaluation, and promote only on measured improvement."
+}
+
 function proposal(type, key, title, evidence, recommendation) {
-  return { id: idFor(type, key), type, key, title, evidence, recommendation, status: "proposed" }
+  return {
+    id: idFor(type, key),
+    type,
+    key,
+    title,
+    evidence,
+    recommendation,
+    candidateRule: recommendation,
+    shadowRequired: true,
+    status: "proposed",
+  }
+}
+
+function clampRate(value) {
+  const number = Number(value)
+  return Number.isFinite(number) && number >= 0 && number <= 1 ? number : null
 }
 
 export async function analyzeEvalTraces(evalDir) {
@@ -36,60 +75,91 @@ export async function analyzeEvalTraces(evalDir) {
   for (const file of files) {
     try {
       const payload = JSON.parse(await readFile(file, "utf8"))
-      for (const item of payload.results || []) results.push({ ...item, source: file })
+      for (const item of payload.results || []) {
+        results.push({ ...item, source: file })
+      }
     } catch {}
   }
 
-  const counters = new Map()
-  const bump = (key, item) => {
-    const value = counters.get(key) || { count: 0, tasks: new Set(), modes: new Set() }
+  const reasonCounters = new Map()
+  const clusters = new Map()
+
+  const bump = (map, key, item) => {
+    const value = map.get(key) || {
+      count: 0,
+      tasks: new Set(),
+      modes: new Set(),
+      suites: new Set(),
+      sources: new Set(),
+    }
     value.count += 1
     if (item.task) value.tasks.add(item.task)
     if (item.mode) value.modes.add(item.mode)
-    counters.set(key, value)
+    if (item.suite) value.suites.add(item.suite)
+    if (item.source) value.sources.add(item.source)
+    map.set(key, value)
   }
 
   for (const item of results) {
-    if (item.timedOut) bump("hard-timeout", item)
-    if (item.idleTimedOut) bump("idle-timeout", item)
-    if (Number(item.agentExit) !== 0) bump("agent-exit", item)
-    if (Number(item.graderExit) !== 0) bump("grader-failure", item)
-    if (item.orchestration?.required && !item.orchestration?.valid) bump("orchestration-failure", item)
-    if ((item.telemetry?.parseErrors || 0) > 0) bump("telemetry-parse-errors", item)
+    const reasons = failureReasons(item)
+    for (const reason of reasons) bump(reasonCounters, reason, item)
+    if (reasons.length) {
+      const clusterKey = reasons.sort().join("+")
+      bump(clusters, clusterKey, item)
+    }
   }
 
   const proposals = []
-  for (const [key, value] of counters) {
-    if (value.count < 1) continue
-    const details = {
+  for (const [key, value] of reasonCounters) {
+    const evidence = {
       count: value.count,
       tasks: [...value.tasks].sort(),
       modes: [...value.modes].sort(),
+      sources: [...value.sources].sort().slice(0, 20),
       samples: results.length,
-    }
-    const recommendations = {
-      "hard-timeout": "Inspect task decomposition and model/runtime latency; shorten tasks or raise a justified hard timeout.",
-      "idle-timeout": "Inspect tool/session deadlocks and add progress-producing boundaries or recovery.",
-      "agent-exit": "Classify process/provider failures before retrying; avoid blind model escalation.",
-      "grader-failure": "Mine failing task contracts for missing domain guidance or context selection, then add a regression before changing skills.",
-      "orchestration-failure": "Strengthen durable workflow instructions/gates or runtime support; do not count direct patches as UES success.",
-      "telemetry-parse-errors": "Update telemetry parsing against the observed OpenCode event shape with a fixture-backed test.",
+      confidence: results.length ? value.count / results.length : 0,
     }
     proposals.push(proposal(
       "eval-pattern",
       key,
       "Recurring evaluation pattern: " + key,
-      details,
-      recommendations[key] || "Review the repeated pattern and add a regression before promoting a reusable lesson.",
+      evidence,
+      recommendationFor(key),
+    ))
+  }
+
+  for (const [key, value] of clusters) {
+    if (value.count < 2) continue
+    const primary = key.split("+")[0]
+    const evidence = {
+      count: value.count,
+      tasks: [...value.tasks].sort(),
+      modes: [...value.modes].sort(),
+      sources: [...value.sources].sort().slice(0, 20),
+      samples: results.length,
+      confidence: results.length ? value.count / results.length : 0,
+      signature: key,
+    }
+    proposals.push(proposal(
+      "root-cause-cluster",
+      key,
+      "Repeated failure cluster: " + key,
+      evidence,
+      recommendationFor(primary),
     ))
   }
 
   return {
-    schemaVersion: 1,
+    schemaVersion: 2,
     analyzedAt: new Date().toISOString(),
     files: files.length,
     results: results.length,
-    proposals: proposals.sort((a, b) => b.evidence.count - a.evidence.count || a.key.localeCompare(b.key)),
+    clusters: [...clusters.entries()]
+      .map(([key, value]) => ({ key, count: value.count, tasks: [...value.tasks].sort() }))
+      .sort((a, b) => b.count - a.count || a.key.localeCompare(b.key)),
+    proposals: proposals.sort((a, b) =>
+      b.evidence.count - a.evidence.count || a.key.localeCompare(b.key),
+    ),
   }
 }
 
@@ -99,17 +169,19 @@ export function learningFile(root) {
 
 export async function readLearningState(root) {
   const file = learningFile(root)
-  if (!existsSync(file)) return { schemaVersion: 1, updatedAt: null, proposals: [], accepted: [] }
+  if (!existsSync(file)) {
+    return { schemaVersion: 2, updatedAt: null, proposals: [], accepted: [] }
+  }
   try {
     const parsed = JSON.parse(await readFile(file, "utf8"))
     return {
-      schemaVersion: 1,
+      schemaVersion: 2,
       updatedAt: parsed.updatedAt || null,
       proposals: Array.isArray(parsed.proposals) ? parsed.proposals : [],
       accepted: Array.isArray(parsed.accepted) ? parsed.accepted : [],
     }
   } catch {
-    return { schemaVersion: 1, updatedAt: null, proposals: [], accepted: [], invalid: true }
+    return { schemaVersion: 2, updatedAt: null, proposals: [], accepted: [], invalid: true }
   }
 }
 
@@ -118,9 +190,16 @@ export async function saveLearningAnalysis(root, analysis) {
   await mkdir(dir, { recursive: true })
   const current = await readLearningState(root)
   const acceptedIDs = new Set(current.accepted.map((item) => item.id))
-  const proposals = analysis.proposals.filter((item) => !acceptedIDs.has(item.id))
+  const existing = new Map(current.proposals.map((item) => [item.id, item]))
+  const proposals = analysis.proposals
+    .filter((item) => !acceptedIDs.has(item.id))
+    .map((item) => ({
+      ...item,
+      firstProposedAt: existing.get(item.id)?.firstProposedAt || new Date().toISOString(),
+      lastAnalyzedAt: analysis.analyzedAt,
+    }))
   const next = {
-    schemaVersion: 1,
+    schemaVersion: 2,
     updatedAt: new Date().toISOString(),
     proposals,
     accepted: current.accepted,
@@ -129,13 +208,19 @@ export async function saveLearningAnalysis(root, analysis) {
   return next
 }
 
+// Backward-compatible manual acceptance. Shadow-required proposals remain excluded
+// from retrieval until they are promoted with measured benchmark improvement.
 export async function acceptLearning(root, id) {
   const current = await readLearningState(root)
   const item = current.proposals.find((entry) => entry.id === id)
   if (!item) throw new Error("unknown learning proposal: " + id)
-  const accepted = { ...item, status: "accepted", acceptedAt: new Date().toISOString() }
+  const accepted = {
+    ...item,
+    status: item.shadowRequired ? "accepted-awaiting-shadow" : "accepted",
+    acceptedAt: new Date().toISOString(),
+  }
   const next = {
-    schemaVersion: 1,
+    schemaVersion: 2,
     updatedAt: accepted.acceptedAt,
     proposals: current.proposals.filter((entry) => entry.id !== id),
     accepted: [...current.accepted.filter((entry) => entry.id !== id), accepted],
@@ -145,14 +230,127 @@ export async function acceptLearning(root, id) {
   return accepted
 }
 
+async function benchmarkValidationFromArtifact(root, reportPath) {
+  const value = String(reportPath || "").trim()
+  if (!value) {
+    throw new Error("learning promotion requires --report pointing to a benchmark matrix artifact")
+  }
+
+  root = path.resolve(root)
+  const file = path.isAbsolute(value) ? value : path.resolve(root, value)
+  const raw = await readFile(file, "utf8").catch(() => null)
+  if (!raw) throw new Error("learning promotion benchmark report could not be read: " + value)
+
+  let report
+  try {
+    report = JSON.parse(raw)
+  } catch {
+    throw new Error("learning promotion benchmark report is not valid JSON: " + value)
+  }
+
+  if (report.kind !== "ues-benchmark-matrix" || report.schemaVersion !== 1) {
+    throw new Error("learning promotion requires a ues-benchmark-matrix schemaVersion 1 artifact")
+  }
+  if (report.coverageComplete !== true) {
+    throw new Error("learning promotion requires a benchmark artifact with complete baseline/UES coverage")
+  }
+
+  const baseline = report.summary?.modes?.baseline
+  const candidate = report.summary?.modes?.ues
+  const baselinePassRate = clampRate(baseline?.passRate)
+  const candidatePassRate = clampRate(candidate?.passRate)
+  const baselineTotal = Number.parseInt(String(baseline?.total ?? "0"), 10)
+  const candidateTotal = Number.parseInt(String(candidate?.total ?? "0"), 10)
+  const samples = Math.min(baselineTotal, candidateTotal)
+
+  if (baselinePassRate === null || candidatePassRate === null || samples < 1) {
+    throw new Error("learning promotion benchmark artifact is missing valid pass-rate/sample evidence")
+  }
+  if (baselineTotal !== candidateTotal) {
+    throw new Error("learning promotion requires equal baseline and UES sample counts")
+  }
+  if (candidatePassRate <= baselinePassRate) {
+    throw new Error("learning promotion requires measured shadow benchmark improvement")
+  }
+  if (!Array.isArray(report.pairedResults) || report.pairedResults.length < 2) {
+    throw new Error("learning promotion requires embedded paired baseline/UES benchmark evidence")
+  }
+  const confidence = pairedBenchmarkConfidence(report.pairedResults)
+  if (confidence.promotionEligible !== true) {
+    throw new Error("learning promotion requires statistically supported improvement without suite regression")
+  }
+
+  return {
+    baselinePassRate,
+    candidatePassRate,
+    delta: candidatePassRate - baselinePassRate,
+    samples,
+    report: path.relative(root, file).replaceAll("\\", "/"),
+    reportHash: createHash("sha256").update(raw).digest("hex"),
+    model: report.model || null,
+    suites: Array.isArray(report.suites) ? report.suites : [],
+    finishedAt: report.finishedAt || null,
+    confidence,
+  }
+}
+
+export async function promoteLearning(root, id, validation = {}) {
+  const current = await readLearningState(root)
+  const item = current.accepted.find((entry) => entry.id === id)
+  if (!item) {
+    if (current.proposals.some((entry) => entry.id === id)) {
+      throw new Error("learning proposal must be explicitly accepted before shadow promotion: " + id)
+    }
+    throw new Error("unknown learning proposal: " + id)
+  }
+
+  const shadowValidation = await benchmarkValidationFromArtifact(root, validation.report)
+  const promotedAt = new Date().toISOString()
+  const promoted = {
+    ...item,
+    status: "promoted",
+    promotedAt,
+    shadowValidation,
+  }
+  const next = {
+    schemaVersion: 2,
+    updatedAt: promotedAt,
+    proposals: current.proposals.filter((entry) => entry.id !== id),
+    accepted: [...current.accepted.filter((entry) => entry.id !== id), promoted],
+  }
+  await mkdir(path.dirname(learningFile(root)), { recursive: true })
+  await writeFile(learningFile(root), JSON.stringify(next, null, 2) + "\n", "utf8")
+  return promoted
+}
+
+function retrievalTerms(text) {
+  return [...new Set(
+    String(text || "")
+      .toLowerCase()
+      .split(/[^\p{L}\p{N}_-]+/u)
+      .filter((term) => term.length >= 4),
+  )]
+}
+
 export async function relevantAcceptedLearnings(root, text, limit = 5) {
   const state = await readLearningState(root)
-  const terms = new Set(String(text || "").toLowerCase().split(/[^a-z0-9_-]+/).filter((term) => term.length >= 4))
+  const terms = retrievalTerms(text)
   return state.accepted
+    .filter((item) => !item.shadowRequired || item.status === "promoted" || item.shadowValidation?.delta > 0)
     .map((item) => {
-      const haystack = JSON.stringify(item).toLowerCase()
-      const score = [...terms].reduce((sum, term) => sum + (haystack.includes(term) ? 1 : 0), 0)
-      return { item, score }
+      const title = String(item.title || "").toLowerCase()
+      const rule = String(item.candidateRule || item.recommendation || "").toLowerCase()
+      const tasks = JSON.stringify(item.evidence?.tasks || []).toLowerCase()
+      const score = terms.reduce((sum, term) => {
+        if (title.includes(term)) sum += 4
+        if (rule.includes(term)) sum += 3
+        if (tasks.includes(term)) sum += 2
+        return sum
+      }, 0)
+      const validationBoost = item.shadowValidation?.delta > 0
+        ? Math.min(5, item.shadowValidation.delta * 20)
+        : 0
+      return { item, score: score + validationBoost }
     })
     .filter((entry) => entry.score > 0)
     .sort((a, b) => b.score - a.score)

package/lib/model-policy.mjs

@@ -58,11 +58,17 @@ export function resolveAdaptiveModel(role, attempt, taskPolicy = {}, config = {}
     ...config,
     roleTiers: { ...(config.roleTiers || {}), [role]: baseTier },
   })
+  const normalizedAttempt = Math.max(1, Number(attempt || 1))
   return {
     ...resolved,
+    recoveryStage:
+      normalizedAttempt <= 1 ? "initial" :
+      normalizedAttempt === 2 ? "diagnose" :
+      "deep-recovery",
     policy: {
       mode: taskPolicy.mode || null,
       risk: taskPolicy.risk || null,
+      executionProfile: taskPolicy.executionProfile || null,
       score: Number(taskPolicy.score || 0),
       maxAttempts: Number(taskPolicy.maxAttempts || 0) || null,
       contextBudget: Number(taskPolicy.contextBudget || 0) || null,