opencode-agent-skill 15.0.0 → 15.1.1

package/lib/evidence-store.mjs

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto"
 import { existsSync } from "node:fs"
-import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises"
+import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises"
 import path from "node:path"
 
 const STORE_VERSION = 1
@@ -12,6 +12,82 @@ const AUTO_GC_EVERY_WRITES = 8
 const AUTO_GC_LARGE_ITEM_BYTES = 16 * 1024 * 1024
 const PUT_COUNTS = new Map()
 
+const STORE_MUTATION_TAILS = new Map()
+const STORE_LOCK_STALE_MS = 30_000
+const STORE_LOCK_WAIT_MS = 40_000
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+function storeLockPath(root) {
+  return path.join(evidenceStoreRoot(root), ".mutation.lock")
+}
+
+async function withCrossProcessStoreLock(root, fn) {
+  const lockDir = storeLockPath(root)
+  await mkdir(path.dirname(lockDir), { recursive: true })
+  const deadline = Date.now() + STORE_LOCK_WAIT_MS
+  let delayMs = 8
+  while (true) {
+    try {
+      await mkdir(lockDir)
+      break
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error
+      const info = await stat(lockDir).catch(() => null)
+      if (info && Date.now() - info.mtimeMs > STORE_LOCK_STALE_MS) {
+        const confirmed = await stat(lockDir).catch(() => null)
+        if (
+          confirmed &&
+          confirmed.ino === info.ino &&
+          confirmed.mtimeMs === info.mtimeMs
+        ) {
+          await rm(lockDir, { recursive: true, force: true }).catch(() => {})
+          continue
+        }
+      }
+      if (Date.now() >= deadline) throw new Error("Timed out waiting for evidence-store mutation lock")
+      await sleep(delayMs)
+      delayMs = Math.min(100, delayMs * 2)
+    }
+  }
+  try {
+    return await fn()
+  } finally {
+    await rm(lockDir, { recursive: true, force: true }).catch(() => {})
+  }
+}
+
+async function withStoreMutationLock(root, fn) {
+  const key = path.resolve(root)
+  const previous = STORE_MUTATION_TAILS.get(key) || Promise.resolve()
+  let release
+  const barrier = new Promise((resolve) => { release = resolve })
+  const tail = previous.catch(() => {}).then(() => barrier)
+  STORE_MUTATION_TAILS.set(key, tail)
+
+  await previous.catch(() => {})
+  try {
+    return await withCrossProcessStoreLock(root, fn)
+  } finally {
+    release()
+    if (STORE_MUTATION_TAILS.get(key) === tail) STORE_MUTATION_TAILS.delete(key)
+  }
+}
+
+async function atomicWrite(file, value, encoding) {
+  await mkdir(path.dirname(file), { recursive: true })
+  const temp = file + "." + process.pid + "." + Date.now() + ".tmp"
+  await writeFile(temp, value, encoding)
+  try {
+    await rename(temp, file)
+  } catch (error) {
+    await rm(temp, { force: true }).catch(() => {})
+    throw error
+  }
+}
+
 function boundedNumber(value, fallback, min, max) {
   const parsed = Number(value)
   if (!Number.isFinite(parsed)) return fallback
@@ -104,42 +180,50 @@ export async function putEvidence(root, value, options = {}) {
   const encoded = toBytes(value, options)
   const hash = createHash("sha256").update(encoded.bytes).digest("hex")
   const target = evidencePaths(root, hash)
-  await mkdir(target.dir, { recursive: true })
 
-  const now = new Date().toISOString()
-  const existing = existsSync(target.meta)
-    ? JSON.parse(await readFile(target.meta, "utf8").catch(() => "{}"))
-    : null
+  const mutation = await withStoreMutationLock(root, async () => {
+    await mkdir(target.dir, { recursive: true })
+    const now = new Date().toISOString()
+    const existing = existsSync(target.meta)
+      ? JSON.parse(await readFile(target.meta, "utf8").catch(() => "{}"))
+      : null
 
-  if (!existsSync(target.data)) await writeFile(target.data, encoded.bytes)
+    if (!existsSync(target.data)) {
+      await atomicWrite(target.data, encoded.bytes)
+    }
 
-  const preview = encoded.encoding === "utf8"
-    ? encoded.bytes.toString("utf8", 0, Math.min(encoded.bytes.length, 600))
-    : null
+    const preview = encoded.encoding === "utf8"
+      ? encoded.bytes.toString("utf8", 0, Math.min(encoded.bytes.length, 600))
+      : null
 
-  const metadata = {
-    schemaVersion: STORE_VERSION,
-    ref: evidenceReference(hash),
-    sha256: hash,
-    bytes: encoded.bytes.length,
-    encoding: encoded.encoding,
-    mediaType: encoded.mediaType,
-    kind: options.kind || existing?.kind || "tool-output",
-    source: options.source || existing?.source || null,
-    summary: options.summary || existing?.summary || null,
-    createdAt: existing?.createdAt || now,
-    lastSeenAt: now,
-    preview,
-  }
-  await writeFile(target.meta, JSON.stringify(metadata, null, 2) + "\n", "utf8")
+    const metadata = {
+      schemaVersion: STORE_VERSION,
+      ref: evidenceReference(hash),
+      sha256: hash,
+      bytes: encoded.bytes.length,
+      encoding: encoded.encoding,
+      mediaType: encoded.mediaType,
+      kind: options.kind || existing?.kind || "tool-output",
+      source: options.source || existing?.source || null,
+      summary: options.summary || existing?.summary || null,
+      createdAt: existing?.createdAt || now,
+      lastSeenAt: now,
+      preview,
+    }
+    await atomicWrite(target.meta, JSON.stringify(metadata, null, 2) + "\n", "utf8")
 
-  const writes = (PUT_COUNTS.get(root) || 0) + 1
-  PUT_COUNTS.set(root, writes)
-  if (writes % AUTO_GC_EVERY_WRITES === 0 || encoded.bytes.length >= AUTO_GC_LARGE_ITEM_BYTES) {
+    const writes = (PUT_COUNTS.get(root) || 0) + 1
+    PUT_COUNTS.set(root, writes)
+    return {
+      metadata,
+      shouldGc: writes % AUTO_GC_EVERY_WRITES === 0 || encoded.bytes.length >= AUTO_GC_LARGE_ITEM_BYTES,
+    }
+  })
+
+  if (mutation.shouldGc) {
     await gcEvidenceStore(root, defaultStoreLimits()).catch(() => null)
   }
-
-  return metadata
+  return mutation.metadata
 }
 
 export async function getEvidence(root, ref, options = {}) {
@@ -275,7 +359,7 @@ export async function evidenceStoreStatus(root = process.cwd()) {
   }
 }
 
-export async function gcEvidenceStore(root = process.cwd(), options = {}) {
+async function gcEvidenceStoreUnlocked(root = process.cwd(), options = {}) {
   root = path.resolve(root)
   const files = await metadataFiles(root)
   const defaults = defaultStoreLimits()
@@ -332,6 +416,12 @@ export async function gcEvidenceStore(root = process.cwd(), options = {}) {
   }
 }
 
+
+export async function gcEvidenceStore(root = process.cwd(), options = {}) {
+  root = path.resolve(root)
+  return withStoreMutationLock(root, () => gcEvidenceStoreUnlocked(root, options))
+}
+
 export async function evidenceExists(root, ref) {
   try {
     const target = evidencePaths(root, normalizeHash(ref))

package/lib/executable-probe.mjs

@@ -0,0 +1,69 @@
+import { accessSync, constants as fsConstants } from "node:fs"
+import path from "node:path"
+
+const DEFAULT_TTL_MS = 60_000
+const commandProbeCache = new Map()
+
+function executableFile(target) {
+  try {
+    accessSync(target, process.platform === "win32" ? fsConstants.F_OK : fsConstants.X_OK)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function probeKey(name) {
+  return [
+    name,
+    String(process.env.PATH || ""),
+    process.platform === "win32" ? String(process.env.PATHEXT || ".COM;.EXE;.BAT;.CMD") : "",
+  ].join("\u0000")
+}
+
+export function commandExists(command, options = {}) {
+  if (!command) return false
+  const name = String(command).trim()
+  if (!name) return false
+
+  const ttlMs = Math.max(0, Number(options.ttlMs ?? DEFAULT_TTL_MS))
+  const key = probeKey(name)
+  const now = Date.now()
+  const cached = commandProbeCache.get(key)
+  if (cached && now - cached.checkedAt < ttlMs) return cached.available
+
+  const hasPath = path.isAbsolute(name) || name.includes("/") || name.includes("\\")
+  let available = false
+  if (hasPath) {
+    available = executableFile(path.resolve(name))
+  } else {
+    const dirs = String(process.env.PATH || "")
+      .split(path.delimiter)
+      .map((item) => item.trim().replace(/^"|"$/g, ""))
+      .filter(Boolean)
+    const extension = path.extname(name)
+    const suffixes = process.platform === "win32" && !extension
+      ? String(process.env.PATHEXT || ".COM;.EXE;.BAT;.CMD")
+          .split(";")
+          .map((item) => item.trim())
+          .filter(Boolean)
+      : [""]
+
+    outer:
+    for (const dir of dirs) {
+      for (const suffix of suffixes) {
+        if (executableFile(path.join(dir, name + suffix))) {
+          available = true
+          break outer
+        }
+      }
+    }
+  }
+
+  commandProbeCache.set(key, { available, checkedAt: now })
+  return available
+}
+
+export function clearExecutableProbeCache() {
+  commandProbeCache.clear()
+}

package/lib/execution-contract.mjs

@@ -174,26 +174,39 @@ export function detectInheritedDirtyViolations(root, snapshot, approvedPaths = [
   }
 }
 
-export function captureInheritedDirtyState(root) {
+export function captureInheritedDirtyState(root, options = {}) {
   const resolved = path.resolve(root)
-  const probe = spawnSync("git", ["status", "--porcelain=v1", "-z", "--untracked-files=all"], {
-    cwd: resolved,
-    encoding: "utf8",
-    maxBuffer: 16 * 1024 * 1024,
-  })
-  if (probe.status !== 0) {
-    return {
-      schemaVersion: 1,
-      available: false,
-      clean: false,
-      root: resolved,
-      entries: [],
-      paths: [],
-      error: String(probe.stderr || probe.stdout || "git status failed").trim(),
+  let statusOutput = ""
+  const workspaceState = options.workspaceState || null
+  if (
+    workspaceState &&
+    typeof workspaceState === "object" &&
+    workspaceState.root &&
+    path.resolve(workspaceState.root) === resolved &&
+    typeof workspaceState.statusOutput === "string"
+  ) {
+    statusOutput = workspaceState.statusOutput
+  } else {
+    const probe = spawnSync("git", ["status", "--porcelain=v1", "-z", "--untracked-files=all"], {
+      cwd: resolved,
+      encoding: "utf8",
+      maxBuffer: 16 * 1024 * 1024,
+    })
+    if (probe.status !== 0) {
+      return {
+        schemaVersion: 1,
+        available: false,
+        clean: false,
+        root: resolved,
+        entries: [],
+        paths: [],
+        error: String(probe.stderr || probe.stdout || "git status failed").trim(),
+      }
     }
+    statusOutput = String(probe.stdout || "")
   }
 
-  const tokens = String(probe.stdout || "").split("\0").filter(Boolean)
+  const tokens = statusOutput.split("\0").filter(Boolean)
   const entries = []
   for (let index = 0; index < tokens.length; index += 1) {
     const token = tokens[index]

package/lib/hierarchical-context.mjs

@@ -3,6 +3,7 @@ import { buildSemanticIndex } from "./semantic-index.mjs"
 
 const DEFAULT_L0 = 256
 const DEFAULT_L1 = 4000
+let HIERARCHY_RUNTIME_CACHE = new WeakMap()
 const STOP = new Set([
   "this","that","with","from","into","then","than","when","where","what","your","have","will",
   "task","code","file","files","fix","update","change","changes","được","các","cho","với","trong","này","một","những","không","theo",
@@ -84,6 +85,20 @@ export async function buildContextHierarchy(root = process.cwd(), options = {})
     maxFiles: options.maxFiles ?? 6000,
     maxDepth: options.maxDepth ?? 14,
   })
+  const l0Limit = Math.max(96, Number(options.l0Chars || DEFAULT_L0))
+  const l1Limit = Math.max(512, Number(options.l1Chars || DEFAULT_L1))
+  const indexObject = built?.index && typeof built.index === "object" ? built.index : null
+  const cacheKey = [root, l0Limit, l1Limit].join("\u0000")
+  const cachedBucket = indexObject ? HIERARCHY_RUNTIME_CACHE.get(indexObject) : null
+  const cached = cachedBucket?.get(cacheKey)
+  if (cached) {
+    return {
+      ...cached,
+      stats: built.stats,
+      runtimeCacheHit: true,
+    }
+  }
+
   const nodes = new Map()
   const children = new Map()
   const ensure = (dir) => {
@@ -122,19 +137,27 @@ export async function buildContextHierarchy(root = process.cwd(), options = {})
     .map((node) => buildNodeSummary(node, children, options))
     .sort((a, b) => a.path.localeCompare(b.path))
 
-  return {
+  const result = {
     schemaVersion: 1,
     kind: "ues-context-hierarchy",
     root,
     generatedAt: new Date().toISOString(),
     levels: {
-      L0: { maxChars: Math.max(96, Number(options.l0Chars || DEFAULT_L0)), purpose: "routing abstract" },
-      L1: { maxChars: Math.max(512, Number(options.l1Chars || DEFAULT_L1)), purpose: "scope overview" },
+      L0: { maxChars: l0Limit, purpose: "routing abstract" },
+      L1: { maxChars: l1Limit, purpose: "scope overview" },
       L2: { purpose: "source excerpts loaded on demand by the context manifest" },
     },
     nodes: summaries,
     stats: built.stats,
+    runtimeCacheHit: false,
   }
+
+  if (indexObject) {
+    const bucket = cachedBucket || new Map()
+    bucket.set(cacheKey, result)
+    if (!cachedBucket) HIERARCHY_RUNTIME_CACHE.set(indexObject, bucket)
+  }
+  return result
 }
 
 function containsFile(scope, file) {
@@ -211,5 +234,10 @@ export async function queryContextHierarchy(root, query, options = {}) {
     levels: hierarchy.levels,
     scopes,
     stats: hierarchy.stats,
+    runtimeCacheHit: hierarchy.runtimeCacheHit === true,
   }
+}
+
+export function clearContextHierarchyRuntimeCache() {
+  HIERARCHY_RUNTIME_CACHE = new WeakMap()
 }

package/lib/learning-engine.mjs

@@ -1,11 +1,88 @@
 import { existsSync } from "node:fs"
-import { mkdir, readFile, readdir, writeFile } from "node:fs/promises"
+import { mkdir, readFile, readdir, rename, rm, stat, 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"
+const LEARNING_WRITE_TAILS = new Map()
+const LEARNING_LOCK_STALE_MS = 15_000
+const LEARNING_LOCK_WAIT_MS = 20_000
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+function learningLockPath(root) {
+  return path.join(path.resolve(root), LEARNING_DIR, ".learning-write.lock")
+}
+
+async function withCrossProcessLearningLock(root, fn) {
+  const lockDir = learningLockPath(root)
+  await mkdir(path.dirname(lockDir), { recursive: true })
+  const deadline = Date.now() + LEARNING_LOCK_WAIT_MS
+  let delayMs = 8
+
+  while (true) {
+    try {
+      await mkdir(lockDir)
+      break
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error
+      const info = await stat(lockDir).catch(() => null)
+      if (info && Date.now() - info.mtimeMs > LEARNING_LOCK_STALE_MS) {
+        const confirmed = await stat(lockDir).catch(() => null)
+        if (
+          confirmed &&
+          confirmed.ino === info.ino &&
+          confirmed.mtimeMs === info.mtimeMs
+        ) {
+          await rm(lockDir, { recursive: true, force: true }).catch(() => {})
+          continue
+        }
+      }
+      if (Date.now() >= deadline) throw new Error("Timed out waiting for learning write lock")
+      await sleep(delayMs)
+      delayMs = Math.min(100, delayMs * 2)
+    }
+  }
+
+  try {
+    return await fn()
+  } finally {
+    await rm(lockDir, { recursive: true, force: true }).catch(() => {})
+  }
+}
+
+async function withLearningWriteLock(root, fn) {
+  const key = path.resolve(root)
+  const previous = LEARNING_WRITE_TAILS.get(key) || Promise.resolve()
+  let release
+  const barrier = new Promise((resolve) => { release = resolve })
+  const tail = previous.catch(() => {}).then(() => barrier)
+  LEARNING_WRITE_TAILS.set(key, tail)
+
+  await previous.catch(() => {})
+  try {
+    return await withCrossProcessLearningLock(root, fn)
+  } finally {
+    release()
+    if (LEARNING_WRITE_TAILS.get(key) === tail) LEARNING_WRITE_TAILS.delete(key)
+  }
+}
+
+async function atomicJson(file, value) {
+  await mkdir(path.dirname(file), { recursive: true })
+  const temp = file + "." + process.pid + "." + Date.now() + ".tmp"
+  await writeFile(temp, JSON.stringify(value, null, 2) + "\n", "utf8")
+  try {
+    await rename(temp, file)
+  } catch (error) {
+    await rm(temp, { force: true }).catch(() => {})
+    throw error
+  }
+}
 
 function idFor(type, key) {
   return createHash("sha256").update(type + ":" + key).digest("hex").slice(0, 16)
@@ -27,6 +104,22 @@ async function walkJson(dir, limit = 500) {
   return files
 }
 
+async function mapLimit(items, limit, worker) {
+  if (!items.length) return []
+  const output = new Array(items.length)
+  let cursor = 0
+  const width = Math.min(items.length, Math.max(1, Number(limit || 1)))
+  const runners = Array.from({ length: width }, async () => {
+    while (true) {
+      const index = cursor++
+      if (index >= items.length) return
+      output[index] = await worker(items[index], index)
+    }
+  })
+  await Promise.all(runners)
+  return output
+}
+
 function failureReasons(item) {
   const reasons = []
   if (item.timedOut) reasons.push("hard-timeout")
@@ -71,15 +164,15 @@ function clampRate(value) {
 
 export async function analyzeEvalTraces(evalDir) {
   const files = await walkJson(path.resolve(evalDir))
-  const results = []
-  for (const file of files) {
+  const batches = await mapLimit(files, 12, async (file) => {
     try {
       const payload = JSON.parse(await readFile(file, "utf8"))
-      for (const item of payload.results || []) {
-        results.push({ ...item, source: file })
-      }
-    } catch {}
-  }
+      return (payload.results || []).map((item) => ({ ...item, source: file }))
+    } catch {
+      return []
+    }
+  })
+  const results = batches.flat()
 
   const reasonCounters = new Map()
   const clusters = new Map()
@@ -186,48 +279,49 @@ export async function readLearningState(root) {
 }
 
 export async function saveLearningAnalysis(root, analysis) {
-  const dir = path.dirname(learningFile(root))
-  await mkdir(dir, { recursive: true })
-  const current = await readLearningState(root)
-  const acceptedIDs = new Set(current.accepted.map((item) => 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: 2,
-    updatedAt: new Date().toISOString(),
-    proposals,
-    accepted: current.accepted,
-  }
-  await writeFile(learningFile(root), JSON.stringify(next, null, 2) + "\n", "utf8")
-  return next
+  return withLearningWriteLock(root, async () => {
+    const current = await readLearningState(root)
+    const acceptedIDs = new Set(current.accepted.map((item) => 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: 2,
+      updatedAt: new Date().toISOString(),
+      proposals,
+      accepted: current.accepted,
+    }
+    await atomicJson(learningFile(root), next)
+    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: item.shadowRequired ? "accepted-awaiting-shadow" : "accepted",
-    acceptedAt: new Date().toISOString(),
-  }
-  const next = {
-    schemaVersion: 2,
-    updatedAt: accepted.acceptedAt,
-    proposals: current.proposals.filter((entry) => entry.id !== id),
-    accepted: [...current.accepted.filter((entry) => entry.id !== id), accepted],
-  }
-  await mkdir(path.dirname(learningFile(root)), { recursive: true })
-  await writeFile(learningFile(root), JSON.stringify(next, null, 2) + "\n", "utf8")
-  return accepted
+  return withLearningWriteLock(root, async () => {
+    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: item.shadowRequired ? "accepted-awaiting-shadow" : "accepted",
+      acceptedAt: new Date().toISOString(),
+    }
+    const next = {
+      schemaVersion: 2,
+      updatedAt: accepted.acceptedAt,
+      proposals: current.proposals.filter((entry) => entry.id !== id),
+      accepted: [...current.accepted.filter((entry) => entry.id !== id), accepted],
+    }
+    await atomicJson(learningFile(root), next)
+    return accepted
+  })
 }
 
 async function benchmarkValidationFromArtifact(root, reportPath) {
@@ -295,32 +389,37 @@ async function benchmarkValidationFromArtifact(root, reportPath) {
 }
 
 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)) {
+  const initial = await readLearningState(root)
+  const initialItem = initial.accepted.find((entry) => entry.id === id)
+  if (!initialItem) {
+    if (initial.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
+  return withLearningWriteLock(root, async () => {
+    const current = await readLearningState(root)
+    const item = current.accepted.find((entry) => entry.id === id)
+    if (!item) throw new Error("learning proposal changed during promotion: " + id)
+
+    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 atomicJson(learningFile(root), next)
+    return promoted
+  })
 }
 
 function retrievalTerms(text) {