opencode-agent-skill 11.0.0 → 13.0.0-beta.0

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

@@ -0,0 +1,271 @@
+function normalizePath(value) {
+  return String(value || "").replaceAll("\\", "/").replace(/^\.\/+/, "")
+}
+
+function taskFiles(task, keys) {
+  const files = task?.files
+  if (Array.isArray(files)) return [...new Set(files.map(normalizePath).filter(Boolean))]
+  if (!files || typeof files !== "object") return []
+  return [...new Set(keys.flatMap((key) => Array.isArray(files[key]) ? files[key] : []).map(normalizePath).filter(Boolean))]
+}
+
+function claimMap(task) {
+  const writes = taskFiles(task, ["create", "modify", "test", "delete"])
+  const reads = taskFiles(task, ["read"])
+  const claims = new Map()
+  const add = (resource, mode) => {
+    const current = claims.get(resource)
+    if (!current || mode === "write") claims.set(resource, mode)
+  }
+
+  for (const file of reads) add("file:" + file, "read")
+  for (const file of writes) add("file:" + file, "write")
+
+  const explicit = Array.isArray(task?.resources) ? task.resources : []
+  for (const resource of explicit) add("resource:" + String(resource), "write")
+
+  if (writes.length) add("@writers", "read")
+  const sharedSurface = writes.some((file) =>
+    /(^|\/)(package(?:-lock)?\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb?|tsconfig(?:\.[^/]+)?\.json|schema\.prisma|.*\.csproj|pom\.xml|gradle\.properties)$/i.test(file) ||
+    /(^|\/)(migrations?|generated|config)\//i.test(file)
+  )
+  if (sharedSurface) add("@writers", "write")
+
+  if (!writes.length && !reads.length && explicit.length === 0) {
+    add("@unknown-scope", "write")
+    add("@writers", "write")
+  }
+
+  return [...claims].map(([resource, mode]) => ({ resource, mode }))
+}
+
+export function taskResourceClaims(task) {
+  return claimMap(task)
+}
+
+export class ResourceLeaseTable {
+  constructor() {
+    this.resources = new Map()
+    this.byOwner = new Map()
+  }
+
+  canAcquire(owner, claims) {
+    for (const claim of claims) {
+      const holders = this.resources.get(claim.resource) || []
+      for (const holder of holders) {
+        if (holder.owner === owner) continue
+        if (claim.mode === "write" || holder.mode === "write") return false
+      }
+    }
+    return true
+  }
+
+  acquire(owner, claims) {
+    if (!this.canAcquire(owner, claims)) return false
+    this.byOwner.set(owner, claims)
+    for (const claim of claims) {
+      const holders = this.resources.get(claim.resource) || []
+      holders.push({ owner, mode: claim.mode })
+      this.resources.set(claim.resource, holders)
+    }
+    return true
+  }
+
+  release(owner) {
+    const claims = this.byOwner.get(owner) || []
+    this.byOwner.delete(owner)
+    for (const claim of claims) {
+      const remaining = (this.resources.get(claim.resource) || []).filter((holder) => holder.owner !== owner)
+      if (remaining.length) this.resources.set(claim.resource, remaining)
+      else this.resources.delete(claim.resource)
+    }
+  }
+
+  snapshot() {
+    return [...this.resources.entries()].map(([resource, holders]) => ({ resource, holders }))
+  }
+}
+
+export function adaptiveWorkerCount(input = {}) {
+  const requested = Math.max(1, Math.min(16, Number(input.requested || 4)))
+  const readyCount = Math.max(0, Number(input.readyCount || 0))
+  let limit = Math.min(requested, Math.max(1, readyCount || 1))
+  const recentFailures = Math.max(0, Number(input.recentFailures || 0))
+  const conflictRate = Math.max(0, Math.min(1, Number(input.conflictRate || 0)))
+  if (recentFailures >= 2) limit = Math.max(1, Math.ceil(limit / 2))
+  if (conflictRate >= 0.35) limit = Math.max(1, Math.ceil(limit / 2))
+  return limit
+}
+
+export function parallelRootBaseline(workingTree = {}) {
+  if (workingTree?.git !== true) {
+    throw new Error("ues.dispatch_parallel requires a Git repository")
+  }
+  return {
+    head: workingTree.head || null,
+    branch: workingTree.branch || null,
+    clean: workingTree.clean === true,
+    inheritedDirtyRoot: workingTree.clean !== true,
+    changes: Array.isArray(workingTree.changes) ? [...workingTree.changes] : [],
+  }
+}
+
+function validateGraph(tasks, completed) {
+  const byID = new Map()
+  for (const task of tasks) {
+    const id = String(task?.id || "")
+    if (!id || byID.has(id)) throw new Error("parallel DAG requires unique non-empty task ids")
+    byID.set(id, task)
+  }
+  for (const task of tasks) {
+    for (const dep of task.dependsOn || task.dependencies || []) {
+      if (!byID.has(dep) && !completed.has(dep)) {
+        throw new Error("parallel DAG task " + task.id + " has missing dependency " + dep)
+      }
+    }
+  }
+  return byID
+}
+
+function errorRecord(error) {
+  return {
+    message: String(error?.message || error),
+    code: error?.code || null,
+  }
+}
+
+export async function runEventDrivenDAG(tasks = [], options = {}) {
+  if (typeof options.worker !== "function") throw new Error("parallel DAG requires a worker function")
+  const completed = new Set(options.completedTaskIds || [])
+  const byID = validateGraph(tasks, completed)
+  const pending = new Set(tasks.map((task) => task.id))
+  const running = new Map()
+  const failed = new Map()
+  const blocked = new Map()
+  const results = new Map()
+  const leases = options.leases || new ResourceLeaseTable()
+  const events = []
+  let integrationTail = Promise.resolve()
+  let conflictDeferrals = 0
+  let schedulingChecks = 0
+
+  const emit = (type, payload = {}) => {
+    const event = { type, at: new Date().toISOString(), ...payload }
+    events.push(event)
+    options.onEvent?.(event)
+  }
+
+  const enqueueIntegration = (task, result, context) => {
+    if (typeof options.integrate !== "function") return Promise.resolve(null)
+    const job = integrationTail.then(() => options.integrate(task, result, context))
+    integrationTail = job.catch(() => {})
+    return job
+  }
+
+  const launch = (task) => {
+    const claims = taskResourceClaims(task)
+    if (!leases.acquire(task.id, claims)) return false
+    pending.delete(task.id)
+    const context = {
+      model: options.singleModel === false ? null : (options.model || null),
+      singleModel: options.singleModel !== false,
+      claims,
+    }
+    emit("task.started", { task: task.id, model: context.model, claims })
+    const promise = (async () => {
+      try {
+        const result = await options.worker(task, context)
+        const integration = await enqueueIntegration(task, result, context)
+        return { ok: true, result, integration }
+      } catch (error) {
+        return { ok: false, error }
+      } finally {
+        leases.release(task.id)
+      }
+    })()
+    running.set(task.id, promise)
+    return true
+  }
+
+  while (pending.size || running.size) {
+    for (const id of [...pending]) {
+      const task = byID.get(id)
+      const badDep = (task.dependsOn || task.dependencies || []).find((dep) => failed.has(dep) || blocked.has(dep))
+      if (badDep) {
+        pending.delete(id)
+        blocked.set(id, { dependency: badDep })
+        emit("task.blocked", { task: id, dependency: badDep })
+      }
+    }
+
+    const ready = [...pending]
+      .map((id) => byID.get(id))
+      .filter((task) => (task.dependsOn || task.dependencies || []).every((dep) => completed.has(dep)))
+      .sort((a, b) => String(a.id).localeCompare(String(b.id)))
+
+    schedulingChecks += Math.max(1, ready.length)
+    const conflictRate = schedulingChecks ? conflictDeferrals / schedulingChecks : 0
+    const limit = adaptiveWorkerCount({
+      requested: options.maxConcurrent || 4,
+      readyCount: ready.length + running.size,
+      recentFailures: failed.size,
+      conflictRate,
+    })
+
+    for (const task of ready) {
+      if (running.size >= limit) break
+      const claims = taskResourceClaims(task)
+      if (!leases.canAcquire(task.id, claims)) {
+        conflictDeferrals += 1
+        continue
+      }
+      launch(task)
+    }
+
+    if (!running.size) {
+      if (pending.size) {
+        for (const id of pending) {
+          blocked.set(id, { dependency: null, reason: "no-runnable-task" })
+          emit("task.blocked", { task: id, reason: "no-runnable-task" })
+        }
+        pending.clear()
+      }
+      break
+    }
+
+    const settled = await Promise.race(
+      [...running.entries()].map(([id, promise]) => promise.then((value) => ({ id, ...value }))),
+    )
+    running.delete(settled.id)
+    if (settled.ok) {
+      completed.add(settled.id)
+      results.set(settled.id, { result: settled.result, integration: settled.integration })
+      emit("task.completed", { task: settled.id })
+    } else {
+      failed.set(settled.id, errorRecord(settled.error))
+      emit("task.failed", { task: settled.id, error: errorRecord(settled.error) })
+      if (options.failFast === true) {
+        for (const id of pending) {
+          blocked.set(id, { dependency: settled.id, reason: "fail-fast" })
+          emit("task.blocked", { task: id, dependency: settled.id, reason: "fail-fast" })
+        }
+        pending.clear()
+      }
+    }
+  }
+
+  await integrationTail
+  return {
+    schemaVersion: 1,
+    model: options.singleModel === false ? null : (options.model || null),
+    singleModel: options.singleModel !== false,
+    requestedConcurrency: Math.max(1, Number(options.maxConcurrent || 4)),
+    completed: [...completed].filter((id) => byID.has(id)),
+    failed: Object.fromEntries(failed),
+    blocked: Object.fromEntries(blocked),
+    results: Object.fromEntries(results),
+    conflictDeferrals,
+    events,
+    leaseSnapshot: leases.snapshot(),
+  }
+}

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

@@ -0,0 +1,115 @@
+import { readFileSync, realpathSync } from "node:fs"
+import path from "node:path"
+
+function swapUtf16(buffer) {
+  const evenLength = buffer.length - (buffer.length % 2)
+  const swapped = Buffer.allocUnsafe(evenLength)
+  for (let index = 0; index < evenLength; index += 2) {
+    swapped[index] = buffer[index + 1]
+    swapped[index + 1] = buffer[index]
+  }
+  return swapped.toString("utf16le")
+}
+
+function utf16Guess(buffer) {
+  if (buffer.length < 4) return null
+  let evenNull = 0
+  let oddNull = 0
+  let even = 0
+  let odd = 0
+  for (let index = 0; index < buffer.length; index += 1) {
+    if (index % 2 === 0) {
+      even += 1
+      if (buffer[index] === 0) evenNull += 1
+    } else {
+      odd += 1
+      if (buffer[index] === 0) oddNull += 1
+    }
+  }
+  const er = even ? evenNull / even : 0
+  const or = odd ? oddNull / odd : 0
+  if (or >= 0.25 && er <= 0.05) return "utf16le"
+  if (er >= 0.25 && or <= 0.05) return "utf16be"
+  return null
+}
+
+function decode(buffer) {
+  if (buffer.length >= 3 && buffer[0] === 0xef && buffer[1] === 0xbb && buffer[2] === 0xbf) {
+    return { text: buffer.subarray(3).toString("utf8"), encoding: "utf8-bom" }
+  }
+  if (buffer.length >= 2 && buffer[0] === 0xff && buffer[1] === 0xfe) {
+    return { text: buffer.subarray(2).toString("utf16le"), encoding: "utf16le" }
+  }
+  if (buffer.length >= 2 && buffer[0] === 0xfe && buffer[1] === 0xff) {
+    return { text: swapUtf16(buffer.subarray(2)), encoding: "utf16be" }
+  }
+  const guess = utf16Guess(buffer)
+  if (guess === "utf16le") return { text: buffer.toString("utf16le"), encoding: guess }
+  if (guess === "utf16be") return { text: swapUtf16(buffer), encoding: guess }
+
+  let nul = 0
+  for (const byte of buffer) if (byte === 0) nul += 1
+  if (nul > Math.max(2, Math.floor(buffer.length * 0.01))) {
+    const error = new Error("file appears to be binary rather than UTF text")
+    error.code = "UES_BINARY_TEXT"
+    throw error
+  }
+  return { text: buffer.toString("utf8"), encoding: "utf8" }
+}
+
+export function readProjectText(root, relative, options = {}) {
+  const raw = String(relative || "").trim()
+  if (!raw) {
+    const error = new Error("text_read requires a non-empty file path")
+    error.code = "UES_USAGE"
+    throw error
+  }
+  root = path.resolve(root)
+  const file = path.resolve(root, raw)
+  if (file !== root && !file.startsWith(root + path.sep)) {
+    throw new Error("text_read path must stay inside the project root")
+  }
+  const realRoot = realpathSync(root)
+  const realFile = realpathSync(file)
+  if (realFile !== realRoot && !realFile.startsWith(realRoot + path.sep)) {
+    const error = new Error("text_read refuses a symlink that escapes the project root")
+    error.code = "UES_PATH_ESCAPE"
+    throw error
+  }
+  const buffer = readFileSync(realFile)
+  const decoded = decode(buffer)
+  const start = Math.max(0, Number(options.start || 0))
+  const maxChars = Math.max(256, Math.min(Number(options.maxChars || 12000), 1_000_000))
+  const text = decoded.text.slice(start, start + maxChars)
+  return {
+    schemaVersion: 1,
+    file: path.relative(root, file).replaceAll("\\", "/") || ".",
+    encoding: decoded.encoding,
+    bytes: buffer.length,
+    chars: decoded.text.length,
+    start,
+    returnedChars: text.length,
+    truncated: start + text.length < decoded.text.length,
+    text,
+  }
+}
+
+export function readProjectJson(root, relative, options = {}) {
+  const result = readProjectText(root, relative, {
+    start: 0,
+    maxChars: Math.max(1024, Math.min(Number(options.maxChars || 1_000_000), 1_000_000)),
+  })
+  if (result.truncated) {
+    const error = new Error("JSON file exceeds the bounded V13 project reader limit")
+    error.code = "UES_TEXT_TRUNCATED"
+    throw error
+  }
+  try {
+    return { ...result, value: JSON.parse(result.text) }
+  } catch (cause) {
+    const error = new Error("invalid JSON in " + result.file + ": " + String(cause?.message || cause))
+    error.code = "UES_INVALID_JSON"
+    throw error
+  }
+}
+

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

@@ -0,0 +1,33 @@
+function assistantTextParts(message) {
+  const role = String(message?.info?.role || message?.role || "").toLowerCase()
+  if (role !== "assistant") return []
+  const values = []
+  for (const part of message?.parts || []) {
+    if (part?.type === "text" && typeof part.text === "string") values.push(part.text)
+  }
+  if (values.length === 0 && typeof message?.content === "string") values.push(message.content)
+  return values
+}
+
+export function extractVerifierVerdict(messages) {
+  const list = Array.isArray(messages) ? messages : []
+  for (let messageIndex = list.length - 1; messageIndex >= 0; messageIndex -= 1) {
+    const parts = assistantTextParts(list[messageIndex])
+    for (let partIndex = parts.length - 1; partIndex >= 0; partIndex -= 1) {
+      const lines = parts[partIndex].split(/\r?\n/).map((line) => line.trim()).filter(Boolean)
+      for (let lineIndex = lines.length - 1; lineIndex >= 0; lineIndex -= 1) {
+        const line = lines[lineIndex]
+        if (!line.startsWith("UES_VERDICT_JSON:")) continue
+        const raw = line.slice("UES_VERDICT_JSON:".length).trim()
+        try {
+          const parsed = JSON.parse(raw)
+          const verdict = String(parsed.verdict || "").toUpperCase()
+          const evidence = String(parsed.evidence || "").trim().slice(0, 4000)
+          if (verdict === "PASS" && evidence.length < 3) continue
+          if (["PASS", "FAIL"].includes(verdict)) return { verdict, evidence }
+        } catch {}
+      }
+    }
+  }
+  return null
+}

package/global-config/skills/dynamic-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dynamic-workflow
-description: Plan large fan-out engineering campaigns into bounded dependency-safe waves, separating deterministic work from LLM judgment, limiting concurrency, isolating writers and verifying integrated results before the next wave.
+description: Execute large fan-out engineering campaigns with an event-driven dependency DAG, bounded same-model workers, resource leases, isolated writers and transactional verification/integration.
 ---
 
 # Dynamic Workflow
@@ -9,10 +9,11 @@ Do not spawn agents for work a deterministic script/tool can do. Do not fan out
 
 For a large task:
 1. classify each unit as deterministic, LLM judgment, or visual judgment;
-2. build dependency-safe waves;
-3. serialize overlapping writers and isolate independent writers;
-4. bound concurrency by provider/machine capacity;
-5. keep large intermediate results on disk/evidence references;
-6. integrate and verify each wave before later waves branch from it.
+2. build an explicit dependency DAG and declare read/write file scope;
+3. use one shared model across fresh worker sessions unless the user explicitly requests otherwise;
+4. serialize resource conflicts and isolate independent writers in worktrees;
+5. bound/adapt concurrency instead of spawning as many agents as possible;
+6. integrate one verified result at a time and immediately unlock newly ready dependencies;
+7. keep large intermediate results on disk/evidence references instead of relaying them through parent chat context.
 
 Read [workflow.md](references/workflow.md) for campaign and recovery rules.

package/global-config/skills/dynamic-workflow/references/workflow.md

@@ -1,6 +1,6 @@
 # Dynamic workflow
 
-Use ocskill workflow-plan PLAN.json to produce a bounded schedule.
+Use `ocskill workflow-plan PLAN.json` for deterministic preview, but on OpenCode V2 prefer `ues.dispatch_parallel` for actual event-driven execution when multiple dependency-ready tasks can run safely.
 
 Good fan-out units have independent inputs/outputs and clear ownership. Mechanical indexing, parsing, formatting, builds and test commands stay deterministic.
 
@@ -10,10 +10,12 @@ For LLM/vision units:
 - do not depend on sibling conversational output;
 - verify task ownership before integration.
 
-After each wave:
-- ensure every expected result exists;
-- integrate verified branches/worktrees;
-- run combined verification;
-- branch the next wave from the integrated state.
+During execution:
+- keep one shared model across worker/verifier sessions unless explicitly overridden;
+- isolate writers and hold resource leases until verification plus integration completes;
+- independently verify each task result;
+- integrate one accepted worktree transactionally;
+- record deterministic verification commands when the plan provides them;
+- immediately schedule dependencies unlocked by that completed task rather than waiting for unrelated siblings.
 
 On restart, resume from .ues-work, evidence references and the last verified integrated state rather than replaying the entire conversation.

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

@@ -17,7 +17,7 @@ When the user explicitly chooses the long-horizon workflow (for example with `/u
   reports/
 ```
 
-The directory is git-ignored execution state, not hidden reasoning. Store requirements, decisions, task status, reports and fresh verification evidence. Never store secrets or chain-of-thought.
+The directory is git-ignored execution state, not hidden reasoning. Store requirements, decisions, task status, reports and fresh verification evidence. Never store secrets or chain-of-thought. Never substitute a top-level `ues-work/` directory for `.ues-work/<slug>/`; old/manual `ues-work/` files are non-canonical unless explicitly migrated.
 
 ## Machine-enforced gates
 
@@ -36,7 +36,8 @@ The V6 engine enforces three boundaries:
 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;
+   - on OpenCode V2, if two or more approved tasks are independent, prefer `ues.dispatch_parallel` so one shared model can execute them concurrently with isolated worktrees, leases, independent verifier sessions and serialized integration;
+   - otherwise 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 ...`.
@@ -49,10 +50,11 @@ The V6 engine enforces three boundaries:
 
 Parallel execution is allowed only when:
 - dependencies are satisfied;
-- safe-wave analysis does not detect declared-file overlap;
-- executors do not write shared implicit files or interfaces.
+- declared file/resource scopes are independent or protected by leases;
+- the runtime exposes the fresh-dispatch capability surface;
+- the root state satisfies the parallel runtime safety preconditions.
 
-UES serializes durable state writes, but it cannot make conflicting source-code edits safe. When write-surface independence is uncertain, execute sequentially.
+V13 uses event-driven scheduling rather than fixed wave barriers: a dependency may start as soon as its prerequisite has been independently verified, integrated and durably completed. Shared configuration surfaces and unknown scopes serialize conservatively. When write-surface independence is uncertain, execute sequentially.
 
 ## Resume
 

package/lib/cli-utils.mjs

@@ -1,5 +1,5 @@
-import { readFileSync } from "node:fs"
 import path from "node:path"
+import { readTextAuto } from "./text-encoding.mjs"
 
 export function clipOutput(value, { head = 8000, tail = 8000 } = {}) {
   const text = String(value ?? "")
@@ -14,11 +14,11 @@ export function positionalArg(args, index) {
 }
 
 export function readJsonFile(file) {
-  return JSON.parse(readFileSync(path.resolve(file), "utf8"))
+  return JSON.parse(readTextAuto(path.resolve(file)))
 }
 
 export function readTextFile(file) {
-  return readFileSync(path.resolve(file), "utf8")
+  return readTextAuto(path.resolve(file))
 }
 
 export function optionInt(args, name, fallback) {
@@ -38,4 +38,17 @@ export function optionValue(args, name) {
 
 export function errorMessage(error) {
   return error instanceof Error ? error.message : error
-}
+}
+export function cliErrorPayload(error, options = {}) {
+  const message = error instanceof Error ? error.message : String(error)
+  const code = String(error?.code || (message.startsWith("Usage:") ? "UES_USAGE" : "UES_ERROR"))
+  const exitCode = Number.isInteger(error?.exitCode) ? error.exitCode : code === "UES_USAGE" ? 2 : 1
+  return { ok: false, error: { code, message, command: options.command || null, usage: options.usage || (message.startsWith("Usage:") ? message : null), hint: options.hint || null, recoverable: options.recoverable ?? (code === "UES_USAGE" || code === "UES_BINARY_TEXT") }, exitCode }
+}
+
+export function usageError(message) {
+  const error = new Error(String(message || "invalid command usage"))
+  error.code = "UES_USAGE"
+  error.exitCode = 2
+  return error
+}

package/lib/context-engine-v11.mjs

@@ -3,6 +3,7 @@ import { planEvidenceBudget, evidenceValueScore } from "./evidence-budget.mjs"
 import { putEvidence } from "./evidence-store.mjs"
 import { inferTaskCapabilities } from "./capability-registry.mjs"
 import { buildPromptEnvelope, comparePromptEnvelopes } from "./prompt-cache.mjs"
+import { measureContextQuality } from "./context-quality.mjs"
 
 function taskText(task = {}) {
   return [
@@ -118,6 +119,8 @@ export async function buildAdaptiveTaskContext(root, task, options = {}) {
     recentMessages: options.recentMessages || [],
   })
 
+  const contextQuality = measureContextQuality(task, externalized.manifest, { minRequiredRecall: options.minRequiredRecall })
+
   const cache = options.previousPromptEnvelope
     ? comparePromptEnvelopes(options.previousPromptEnvelope, promptEnvelope)
     : null
@@ -128,6 +131,7 @@ export async function buildAdaptiveTaskContext(root, task, options = {}) {
     capabilities,
     evidenceBudget,
     contextManifest: externalized.manifest,
+    contextQuality,
     evidenceStore: {
       refs: externalized.externalized.length,
       externalizedBytes: externalized.externalizedBytes,

package/lib/context-quality.mjs

@@ -0,0 +1,59 @@
+function normalizePath(value) {
+  return String(value || "").replaceAll("\\", "/").replace(/^\.\//, "")
+}
+
+function declaredTaskFiles(task = {}) {
+  const files = task.files
+  const values = []
+  if (Array.isArray(files)) values.push(...files)
+  else if (files && typeof files === "object") {
+    for (const [kind, list] of Object.entries(files)) {
+      if (kind === "create") continue
+      if (Array.isArray(list)) values.push(...list)
+      else if (typeof list === "string") values.push(list)
+    }
+  }
+  if (Array.isArray(task.requiredFiles)) values.push(...task.requiredFiles)
+  return [...new Set(values.map(normalizePath).filter(Boolean))]
+}
+
+function manifestPaths(manifest = {}) {
+  const values = []
+  for (const item of manifest.excerpts || []) if (item?.path) values.push(item.path)
+  for (const item of manifest.rankedReferences || []) if (item?.path) values.push(item.path)
+  for (const item of manifest.instructions || []) {
+    if (typeof item === "string") values.push(item)
+    else if (item?.path) values.push(item.path)
+  }
+  return [...new Set(values.map(normalizePath).filter(Boolean))]
+}
+
+export function measureContextQuality(task = {}, manifest = {}, options = {}) {
+  const required = declaredTaskFiles(task)
+  const included = manifestPaths(manifest)
+  const includedSet = new Set(included)
+  const hits = required.filter((file) => includedSet.has(file))
+  const requiredFileRecall = required.length ? hits.length / required.length : null
+  const relevant = new Set(required)
+  for (const item of manifest.instructions || []) {
+    if (typeof item === "string") relevant.add(normalizePath(item))
+    else if (item?.path) relevant.add(normalizePath(item.path))
+  }
+  for (const item of manifest.excerpts || []) {
+    if (["declared", "test", "instruction"].includes(item?.role) && item?.path) relevant.add(normalizePath(item.path))
+  }
+  const irrelevant = included.filter((file) => !relevant.has(file))
+  const irrelevantRatio = included.length ? irrelevant.length / included.length : 0
+  const minRequiredRecall = Number.isFinite(Number(options.minRequiredRecall))
+    ? Math.max(0, Math.min(1, Number(options.minRequiredRecall))) : 1
+  return {
+    schemaVersion: 1,
+    requiredFiles: required,
+    includedFiles: included,
+    requiredFileHits: hits,
+    requiredFileRecall,
+    irrelevantFiles: irrelevant,
+    irrelevantRatio,
+    checks: { requiredRecallAcceptable: requiredFileRecall == null ? true : requiredFileRecall >= minRequiredRecall },
+  }
+}

package/lib/decision-policy.mjs

@@ -0,0 +1,23 @@
+const HIGH_RISK = /(npm publish|publish package|deploy|production|git push|force push|reset --hard|git clean|delete branch|drop table|truncate|rotate secret|credential|api key|purchase|payment|irreversible|public api break)/i
+const MEDIUM_RISK = /(migration|schema|dependency upgrade|lockfile|generated code|shared config|auth|permission|security)/i
+const REVERSIBLE = /(local|test|rename|format|refactor|temporary|fixture|internal|reversible)/i
+
+export function classifyDecisionPolicy(text = "", facts = {}) {
+  const value = String(text || "").trim()
+  const explicitlyIrreversible = facts.irreversible === true
+  const externalSideEffect = facts.externalSideEffect === true
+  const destructive = facts.destructive === true || HIGH_RISK.test(value)
+  const medium = MEDIUM_RISK.test(value)
+  const reversible = facts.reversible === true || (!destructive && REVERSIBLE.test(value))
+  const risk = destructive || explicitlyIrreversible || externalSideEffect ? "high" : medium ? "medium" : "low"
+  const requiresUser = risk === "high" || facts.productDecision === true
+  return {
+    schemaVersion: 1, risk, reversible, destructive, externalSideEffect, requiresUser,
+    autoResolvable: !requiresUser && (reversible || risk === "low"),
+    reason: requiresUser ? "human-approval-required" : reversible ? "reversible-local-decision" : "bounded-engineering-decision",
+  }
+}
+
+export function canAutoResolveDecision(text = "", facts = {}) {
+  return classifyDecisionPolicy(text, facts).autoResolvable
+}