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

package/lib/installer.mjs

@@ -23,6 +23,15 @@ function validManagedPlugin(value) {
   return value === ROUTER_PLUGIN_STATE
 }
 
+function validPromptAlias(value) {
+  if (typeof value !== "string" || !value.startsWith(SKILL_PREFIX)) return false
+  return validResourceID(value.slice(SKILL_PREFIX.length))
+}
+
+function promptAliasTemplateName(value) {
+  return value.slice(SKILL_PREFIX.length) + ".md"
+}
+
 function isOwnedPackageName(value) {
   return !value || value === PACKAGE_NAME || value === LEGACY_PACKAGE_NAME
 }
@@ -94,7 +103,7 @@ async function writeManagedFile(file, content, warnings) {
 
 async function readManagedState(file, warnings = []) {
   const raw = await readText(file)
-  if (!raw) return { kind: "empty", state: { skills: [], commands: [], agents: [], plugins: [] } }
+  if (!raw) return { kind: "empty", state: { skills: [], commands: [], promptAliases: [], agents: [], plugins: [] } }
 
   try {
     const parsed = JSON.parse(raw)
@@ -103,7 +112,7 @@ async function readManagedState(file, warnings = []) {
       return {
         kind: "foreign",
         package: parsed.package,
-        state: { skills: [], commands: [], agents: [], plugins: [] },
+        state: { skills: [], commands: [], promptAliases: [], agents: [], plugins: [] },
       }
     }
     return {
@@ -112,13 +121,14 @@ async function readManagedState(file, warnings = []) {
         ...parsed,
         skills: Array.isArray(parsed.skills) ? parsed.skills.filter(validSkillID) : [],
         commands: Array.isArray(parsed.commands) ? parsed.commands.filter(validManagedMarkdown) : [],
+        promptAliases: Array.isArray(parsed.promptAliases) ? parsed.promptAliases.filter(validPromptAlias) : [],
         agents: Array.isArray(parsed.agents) ? parsed.agents.filter(validManagedMarkdown) : [],
         plugins: Array.isArray(parsed.plugins) ? parsed.plugins.filter(validManagedPlugin) : [],
       },
     }
   } catch {
     warnings.push(`Invalid UES state file; run 'ocskill install' to rebuild it: ${file}`)
-    return { kind: "invalid", state: { skills: [], commands: [], agents: [], plugins: [] } }
+    return { kind: "invalid", state: { skills: [], commands: [], promptAliases: [], agents: [], plugins: [] } }
   }
 }
 
@@ -310,7 +320,7 @@ export async function installResources(options = {}) {
   const stateFile = path.join(stateDir, "state.json")
   const warnings = []
   const openCodeMajor = options.openCodeMajor ?? detectOpenCodeMajor()
-  const installed = { skills: [], commands: [], agents: [], plugins: [] }
+  const installed = { skills: [], commands: [], promptAliases: [], agents: [], plugins: [] }
   const previous = await readManagedState(stateFile, warnings)
   const previousState = previous.state
   const modelPolicy = await readModelPolicy(configDir)
@@ -366,25 +376,31 @@ export async function installResources(options = {}) {
 
   const sourceCommands = path.join(sourceRoot, "global-config", "commands")
   const commandEntries = await readdir(sourceCommands, { withFileTypes: true })
-
+  const validCommandEntries = []
   for (const entry of commandEntries) {
     if (!entry.isFile() || !entry.name.endsWith(".md")) continue
-
     const id = entry.name.slice(0, -3)
     if (!validResourceID(id)) {
       warnings.push(`Skipped command with invalid resource ID: ${id}`)
       continue
     }
-    const targetName = `${SKILL_PREFIX}${id}.md`
-    const targetFile = path.join(commandsTarget, targetName)
-    const source = await readFile(path.join(sourceCommands, entry.name), "utf8")
-    const normalizedSource = normalizeManagedMarker(source)
-    const content = hasManagedMarker(normalizedSource)
-      ? normalizedSource
-      : `${normalizedSource.trimEnd()}\n\n${MANAGED_MARKER}\n`
+    validCommandEntries.push(entry)
+  }
 
-    if (await writeManagedFile(targetFile, content, warnings)) {
-      installed.commands.push(targetName)
+  if (openCodeMajor < 2) {
+    for (const entry of validCommandEntries) {
+      const id = entry.name.slice(0, -3)
+      const targetName = `${SKILL_PREFIX}${id}.md`
+      const targetFile = path.join(commandsTarget, targetName)
+      const source = await readFile(path.join(sourceCommands, entry.name), "utf8")
+      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)
+      }
     }
   }
 
@@ -425,6 +441,14 @@ export async function installResources(options = {}) {
     if (existsSync(path.join(sourcePluginDir, "index.js"))) {
       if (await installPluginDirectory(sourcePluginDir, targetPluginDir, warnings)) {
         installed.plugins.push(ROUTER_PLUGIN_STATE)
+
+        const promptAliasDir = path.join(targetPluginDir, "command-templates")
+        await mkdir(promptAliasDir, { recursive: true })
+        for (const entry of validCommandEntries) {
+          const id = entry.name.slice(0, -3)
+          await cp(path.join(sourceCommands, entry.name), path.join(promptAliasDir, entry.name))
+          installed.promptAliases.push(`${SKILL_PREFIX}${id}`)
+        }
       }
     }
 
@@ -457,7 +481,7 @@ export async function installResources(options = {}) {
   }
 
   const state = {
-    schemaVersion: 2,
+    schemaVersion: 3,
     package: PACKAGE_NAME,
     version: await packageVersion(),
     configDir,
@@ -465,6 +489,7 @@ export async function installResources(options = {}) {
     openCodeMajor,
     skills: installed.skills.sort(),
     commands: installed.commands.sort(),
+    promptAliases: installed.promptAliases.sort(),
     agents: installed.agents.sort(),
     plugins: installed.plugins.sort(),
   }
@@ -611,11 +636,13 @@ export async function getStatus() {
 
   state.skills = Array.isArray(state.skills) ? state.skills.filter(validSkillID) : []
   state.commands = Array.isArray(state.commands) ? state.commands.filter(validManagedMarkdown) : []
+  state.promptAliases = Array.isArray(state.promptAliases) ? state.promptAliases.filter(validPromptAlias) : []
   state.agents = Array.isArray(state.agents) ? state.agents.filter(validManagedMarkdown) : []
   state.plugins = Array.isArray(state.plugins) ? state.plugins.filter(validManagedPlugin) : []
 
   let skillsPresent = 0
   let commandsPresent = 0
+  let promptAliasesPresent = 0
   let agentsPresent = 0
   let pluginsPresent = 0
 
@@ -625,6 +652,11 @@ export async function getStatus() {
   for (const name of state.commands || []) {
     if (existsSync(path.join(configDir, "commands", name))) commandsPresent += 1
   }
+  for (const name of state.promptAliases || []) {
+    if (existsSync(path.join(configDir, "plugins", "ues-router", "command-templates", promptAliasTemplateName(name)))) {
+      promptAliasesPresent += 1
+    }
+  }
   for (const name of state.agents || []) {
     if (existsSync(path.join(configDir, "agents", name))) agentsPresent += 1
   }
@@ -639,6 +671,7 @@ export async function getStatus() {
     ...state,
     skillsPresent,
     commandsPresent,
+    promptAliasesPresent,
     agentsPresent,
     pluginsPresent,
     workflowPresent: agents.includes(AGENTS_BEGIN),

package/lib/model-config.mjs

@@ -3,6 +3,7 @@ import { mkdir, readFile, writeFile } from "node:fs/promises"
 import path from "node:path"
 import { defaultModelPolicy, resolveModel } from "./model-policy.mjs"
 import { normalizeCapabilityProfile } from "./capability-registry.mjs"
+import { normalizePerformanceHistory, recordPerformanceOutcome } from "./model-performance.mjs"
 
 const TIERS = new Set(["light", "standard", "heavy"])
 
@@ -29,8 +30,10 @@ function normalize(policy) {
     if (validModelID(model)) capabilities[model] = normalizeCapabilityProfile(profile)
   }
 
+  const performance = normalizePerformanceHistory(input.performance || {})
+
   return {
-    schemaVersion: 2,
+    schemaVersion: 3,
     enabled: input.enabled === true,
     maxEscalations: Number.isInteger(input.maxEscalations)
       ? Math.max(0, Math.min(input.maxEscalations, 2))
@@ -38,6 +41,8 @@ function normalize(policy) {
     tiers,
     roleTiers,
     capabilities,
+    performance,
+    performanceMinSamples: Number.isInteger(input.performanceMinSamples) ? Math.max(1, Math.min(input.performanceMinSamples, 20)) : base.performanceMinSamples,
   }
 }
 
@@ -64,6 +69,7 @@ export async function writeModelPolicy(configDir, patch = {}) {
     tiers: { ...current.tiers, ...(patch.tiers || {}) },
     roleTiers: { ...current.roleTiers, ...(patch.roleTiers || {}) },
     capabilities: { ...(current.capabilities || {}), ...(patch.capabilities || {}) },
+    performance: patch.performance || current.performance || {},
   })
   const file = modelPolicyFile(configDir)
   await mkdir(path.dirname(file), { recursive: true })
@@ -94,3 +100,9 @@ export function applyConfiguredModel(source, role, policy) {
   }
   return lines.join("\n")
 }
+
+export async function recordModelPerformance(configDir, outcome = {}) {
+  const current = await readModelPolicy(configDir)
+  const performance = recordPerformanceOutcome(current.performance || {}, outcome)
+  return writeModelPolicy(configDir, { performance })
+}

package/lib/model-performance.mjs

@@ -0,0 +1,113 @@
+export const MODEL_TASK_CLASSES = Object.freeze([
+  "general", "repo-scale", "debugging", "architecture", "security",
+  "migration", "frontend", "backend", "visual", "browser",
+])
+const KNOWN_TASK_CLASSES = new Set(MODEL_TASK_CLASSES)
+
+function boundedNumber(value, fallback = 0, min = 0, max = Number.MAX_SAFE_INTEGER) {
+  const number = Number(value)
+  if (!Number.isFinite(number)) return fallback
+  return Math.max(min, Math.min(max, number))
+}
+
+export function inferTaskClass(text = "", facts = {}) {
+  const explicit = String(facts.taskClass || "").trim().toLowerCase()
+  if (KNOWN_TASK_CLASSES.has(explicit)) return explicit
+  const value = String(text || "").toLowerCase()
+  if (/(whole repo|entire project|large monorepo|repo[- ]scale|cross[- ]module|toàn bộ dự án|nhiều module)/.test(value)) return "repo-scale"
+  if (/(prompt injection|security|auth|authorization|permission|secret|credential|bảo mật|phân quyền)/.test(value)) return "security"
+  if (/(migration|schema|database|sql|backfill|migrate)/.test(value)) return "migration"
+  if (/(screenshot|visual|figma|pixel|responsive|storybook)/.test(value)) return "visual"
+  if (/(browser|playwright|e2e|web page|click flow)/.test(value)) return "browser"
+  if (/(root cause|debug|regression|crash|failing|bug|lỗi)/.test(value)) return "debugging"
+  if (/(architecture|architect|design decision|system design|kiến trúc)/.test(value)) return "architecture"
+  if (/(react|next\.js|vue|svelte|css|frontend|ui\b)/.test(value)) return "frontend"
+  if (/(api|service|node|python|java|dotnet|backend|server)/.test(value)) return "backend"
+  return "general"
+}
+
+export function normalizePerformanceRecord(record = {}) {
+  record = record && typeof record === "object" ? record : {}
+  const samples = Math.floor(boundedNumber(record.samples, 0, 0))
+  const successes = Math.floor(boundedNumber(record.successes, Math.round(samples * boundedNumber(record.passRate, 0, 0, 1)), 0, samples))
+  return {
+    samples,
+    successes,
+    passRate: samples ? successes / samples : 0,
+    avgRetries: boundedNumber(record.avgRetries, 0, 0, 100),
+    avgTokens: boundedNumber(record.avgTokens, 0, 0),
+    avgLatencyMs: boundedNumber(record.avgLatencyMs, 0, 0),
+    updatedAt: typeof record.updatedAt === "string" ? record.updatedAt : null,
+  }
+}
+
+export function normalizePerformanceHistory(history = {}) {
+  const output = {}
+  for (const [model, classes] of Object.entries(history || {})) {
+    if (!model || !classes || typeof classes !== "object") continue
+    const normalizedClasses = {}
+    for (const [taskClass, record] of Object.entries(classes)) {
+      if (!KNOWN_TASK_CLASSES.has(taskClass) && taskClass !== "overall") continue
+      normalizedClasses[taskClass] = normalizePerformanceRecord(record)
+    }
+    if (Object.keys(normalizedClasses).length) output[model] = normalizedClasses
+  }
+  return output
+}
+
+function mergeAverage(previousAverage, previousSamples, value) {
+  return previousSamples <= 0 ? value : ((previousAverage * previousSamples) + value) / (previousSamples + 1)
+}
+
+export function recordPerformanceOutcome(history = {}, outcome = {}) {
+  const model = String(outcome.model || "").trim()
+  if (!model) throw new Error("model performance outcome requires model")
+  const taskClass = inferTaskClass(outcome.text || "", { taskClass: outcome.taskClass })
+  const normalized = normalizePerformanceHistory(history)
+  const current = normalizePerformanceRecord(normalized[model]?.[taskClass] || {})
+  const samples = current.samples
+  const passed = outcome.passed === true
+  const next = {
+    samples: samples + 1,
+    successes: current.successes + (passed ? 1 : 0),
+    passRate: 0,
+    avgRetries: mergeAverage(current.avgRetries, samples, boundedNumber(outcome.retries, 0, 0, 100)),
+    avgTokens: mergeAverage(current.avgTokens, samples, boundedNumber(outcome.tokens, 0, 0)),
+    avgLatencyMs: mergeAverage(current.avgLatencyMs, samples, boundedNumber(outcome.latencyMs, 0, 0)),
+    updatedAt: new Date().toISOString(),
+  }
+  next.passRate = next.successes / next.samples
+  return { ...normalized, [model]: { ...(normalized[model] || {}), [taskClass]: next } }
+}
+
+function performanceAdjustment(record, minSamples) {
+  const normalized = normalizePerformanceRecord(record)
+  if (normalized.samples <= 0) return { adjustment: 0, confidence: 0, record: normalized }
+  const confidence = Math.min(1, normalized.samples / Math.max(1, minSamples))
+  if (normalized.samples < minSamples) return { adjustment: 0, confidence, record: normalized }
+  const correctness = (normalized.passRate - 0.5) * 80
+  const retryPenalty = Math.min(20, normalized.avgRetries * 5)
+  const latencyPenalty = normalized.avgLatencyMs > 0 ? Math.min(10, Math.max(0, Math.log10(Math.max(1, normalized.avgLatencyMs / 1000)) * 3)) : 0
+  return { adjustment: (correctness - retryPenalty - latencyPenalty) * confidence, confidence, record: normalized }
+}
+
+export function rerankCapabilitySelection(selection = {}, history = {}, options = {}) {
+  const taskClass = inferTaskClass(options.text || "", { taskClass: options.taskClass })
+  const minSamples = Math.max(1, Number(options.minSamples || 3))
+  const normalized = normalizePerformanceHistory(history)
+  const candidates = (selection.candidates || []).map((candidate) => {
+    const record = normalized[candidate.id]?.[taskClass] || normalized[candidate.id]?.overall || null
+    const evidence = performanceAdjustment(record, minSamples)
+    return {
+      ...candidate,
+      baseScore: Number(candidate.score || 0),
+      empiricalTaskClass: taskClass,
+      empiricalEvidence: evidence.record,
+      empiricalConfidence: Number(evidence.confidence.toFixed(4)),
+      adjustedScore: Number((Number(candidate.score || 0) + evidence.adjustment).toFixed(6)),
+    }
+  })
+  const eligible = candidates.filter((candidate) => candidate.eligible)
+    .sort((a, b) => b.adjustedScore - a.adjustedScore || b.baseScore - a.baseScore)
+  return { ...selection, selected: eligible[0] || null, candidates, taskClass, empirical: true }
+}

package/lib/model-policy.mjs

@@ -1,4 +1,5 @@
 import { inferTaskCapabilities, modelCandidatesFromPolicy, selectCapabilityCandidate } from "./capability-registry.mjs"
+import { inferTaskClass, rerankCapabilitySelection } from "./model-performance.mjs"
 
 const ROLE_TIERS = {
   "codebase-mapper": "standard",
@@ -45,12 +46,14 @@ export function resolveModel(role, attempt, config = {}) {
 
 export function defaultModelPolicy() {
   return {
-    schemaVersion: 2,
+    schemaVersion: 3,
     enabled: false,
     maxEscalations: 2,
     tiers: { light: null, standard: null, heavy: null },
     roleTiers: { ...ROLE_TIERS },
     capabilities: {},
+    performance: {},
+    performanceMinSamples: 3,
   }
 }
 
@@ -90,10 +93,14 @@ export function resolveCapabilityModel(role, attempt, taskText = "", taskPolicy
   })
   const candidates = modelCandidatesFromPolicy(config)
     .filter((candidate) => tierIndex(candidate.tier) >= tierIndex(base.tier))
-  const selection = selectCapabilityCandidate(requirements, candidates, {
+  const staticSelection = selectCapabilityCandidate(requirements, candidates, {
     role,
     preferredTier: base.tier,
   })
+  const taskClass = inferTaskClass(taskText, facts)
+  const selection = rerankCapabilitySelection(staticSelection, config.performance || {}, {
+    taskClass, text: taskText, minSamples: config.performanceMinSamples || 3,
+  })
   const capabilityEnforced = config.enabled === true && candidates.length > 0
   if (capabilityEnforced && !selection.selected) {
     return {

package/lib/repo-scale-fixture.mjs

@@ -0,0 +1,45 @@
+import { mkdir, writeFile } from "node:fs/promises"
+import path from "node:path"
+
+function moduleSource(packageIndex, moduleIndex) {
+  const previous = moduleIndex > 0
+    ? 'import { value as previous } from "./mod' + String(moduleIndex - 1).padStart(3, "0") + '.mjs"\n'
+    : ""
+  return previous + "export const value = " + (moduleIndex > 0 ? "previous + 1" : packageIndex * 1000) +
+    "\nexport function compute(input) { return value + Number(input || 0) }\n"
+}
+
+export async function generateRepoScaleFixture(root, options = {}) {
+  const packageCount = Math.max(2, Number(options.packageCount || 6))
+  const modulesPerPackage = Math.max(5, Number(options.modulesPerPackage || 50))
+  await mkdir(root, { recursive: true })
+  await writeFile(path.join(root, "package.json"), JSON.stringify({
+    name: "ues-repo-scale-fixture", private: true, type: "module", workspaces: ["packages/*", "apps/*"],
+  }, null, 2) + "\n")
+
+  let generatedModules = 0
+  for (let p = 0; p < packageCount; p += 1) {
+    const pkgRoot = path.join(root, "packages", "pkg-" + p)
+    const src = path.join(pkgRoot, "src")
+    await mkdir(src, { recursive: true })
+    await writeFile(path.join(pkgRoot, "package.json"), JSON.stringify({
+      name: "@fixture/pkg-" + p, private: true, type: "module", exports: "./src/index.mjs",
+    }, null, 2) + "\n")
+    for (let m = 0; m < modulesPerPackage; m += 1) {
+      await writeFile(path.join(src, "mod" + String(m).padStart(3, "0") + ".mjs"), moduleSource(p, m))
+      generatedModules += 1
+    }
+    await writeFile(path.join(src, "index.mjs"),
+      'export { value, compute } from "./mod' + String(modulesPerPackage - 1).padStart(3, "0") + '.mjs"\n')
+  }
+
+  const apiRoot = path.join(root, "apps", "api", "src")
+  const webRoot = path.join(root, "apps", "web", "src")
+  const contracts = path.join(root, "contracts")
+  await mkdir(apiRoot, { recursive: true }); await mkdir(webRoot, { recursive: true }); await mkdir(contracts, { recursive: true })
+  await writeFile(path.join(contracts, "public-api.json"), JSON.stringify({ version: 1, fields: ["id", "name", "status"] }, null, 2) + "\n")
+  await writeFile(path.join(apiRoot, "service.mjs"), 'export function serialize(row) { return { id: row.id, name: row.name, status: row.status } }\n')
+  await writeFile(path.join(webRoot, "consumer.mjs"), 'export function render(item) { return item.name + ":" + item.status }\n')
+  await writeFile(path.join(root, "AGENTS.md"), "# Fixture instructions\n\nPreserve public contracts and update focused tests.\n")
+  return { root, packageCount, modulesPerPackage, generatedModules, totalPrimaryFiles: generatedModules + packageCount + 5 }
+}

package/lib/task-engine.mjs

@@ -1,9 +1,9 @@
 import { closeSync, existsSync, openSync, readFileSync, readSync, readdirSync, statSync } from "node:fs"
-import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises"
+import { mkdir, rename, rm, stat, writeFile } from "node:fs/promises"
 import { spawnSync } from "node:child_process"
 import { createHash, randomUUID } from "node:crypto"
 import path from "node:path"
-import { analyzePlan, taskFiles, validatePlan } from "./task-graph.mjs"
+import { analyzePlan, taskFiles, taskVerificationCommands, validatePlan } from "./task-graph.mjs"
 import { buildContextManifest } from "./context-manifest.mjs"
 import { relevantAcceptedLearnings } from "./learning-engine.mjs"
 import { validateVerificationReceipt } from "./evidence-receipt.mjs"
@@ -15,6 +15,9 @@ import { putEvidence } from "./evidence-store.mjs"
 import { inferTaskCapabilities } from "./capability-registry.mjs"
 import { buildPromptEnvelope } from "./prompt-cache.mjs"
 import { externalizeContextExcerpts } from "./context-engine-v11.mjs"
+import { assertActivePlanScope, persistPlanScope } from "./work-plan-scope.mjs"
+import { classifyDecisionPolicy } from "./decision-policy.mjs"
+import { readTextAuto } from "./text-encoding.mjs"
 
 const WORK_DIR = ".ues-work"
 const STATE_SCHEMA = 4
@@ -49,13 +52,15 @@ export function workPaths(root, slug) {
     events: path.join(dir, "EVENTS.jsonl"),
     tasks: path.join(dir, "tasks"),
     reports: path.join(dir, "reports"),
+    plans: path.join(dir, "plans"),
+    activePlan: path.join(dir, "ACTIVE_PLAN.json"),
     lock: path.join(dir, ".state-lock"),
   }
 }
 
 async function readJson(file, fallback = null) {
   try {
-    return JSON.parse(await readFile(file, "utf8"))
+    return JSON.parse(readTextAuto(file))
   } catch (error) {
     if (error?.code === "ENOENT") return fallback
     throw error
@@ -268,6 +273,7 @@ export async function initWork(root, slug, goal) {
 
   await mkdir(paths.tasks, { recursive: true })
   await mkdir(paths.reports, { recursive: true })
+  await mkdir(paths.plans, { recursive: true })
   const createdAt = now()
   const cleanGoal = String(goal || "").trim() || "Define the requested engineering outcome."
 
@@ -285,6 +291,7 @@ export async function initWork(root, slug, goal) {
     planImportedAt: null,
     planHash: null,
     planApproval: null,
+    planScope: null,
     integrationVerification: null,
     tasks: {},
     decisions: [],
@@ -334,7 +341,7 @@ function currentEvidencePolicy(state, plan) {
 
 function taskBrief(task) {
   const files = taskFiles(task)
-  return `# ${task.id}: ${task.title}\n\n## Summary\n\n${task.summary || "No summary provided."}\n\n## Dependencies\n\n${(task.dependsOn || []).map((id) => `- ${id}`).join("\n") || "- None"}\n\n## Files\n\n${files.map((file) => `- ${file}`).join("\n") || "- Scope must be established before editing."}\n\n## Acceptance criteria\n\n${(task.acceptance || []).map((item) => `- ${item}`).join("\n")}\n\n## Verification\n\n${(task.verification || []).map((item) => `- ${item}`).join("\n")}\n\n## Risk\n\n${task.risk || "medium"}\n`
+  return `# ${task.id}: ${task.title}\n\n## Summary\n\n${task.summary || "No summary provided."}\n\n## Dependencies\n\n${(task.dependsOn || []).map((id) => `- ${id}`).join("\n") || "- None"}\n\n## Files\n\n${files.map((file) => `- ${file}`).join("\n") || "- Scope must be established before editing."}\n\n## Acceptance criteria\n\n${(task.acceptance || []).map((item) => `- ${item}`).join("\n")}\n\n## Verification\n\n${(task.verification || []).map((item) => `- ${item}`).join("\n")}\n\n## Structured verification commands\n\n${taskVerificationCommands(task).map((item) => `- ${[item.command, ...item.args].join(" ")}`).join("\n") || "- None declared"}\n\n## Risk\n\n${task.risk || "medium"}\n`
 }
 
 function planIsApproved(state, plan) {
@@ -345,7 +352,7 @@ function planIsApproved(state, plan) {
 
 export async function importPlan(root, slug, planInput) {
   const plan = typeof planInput === "string"
-    ? JSON.parse(await readFile(path.resolve(planInput), "utf8"))
+    ? JSON.parse(readTextAuto(path.resolve(planInput)))
     : planInput
 
   const validation = validatePlan(plan)
@@ -383,6 +390,7 @@ export async function importPlan(root, slug, planInput) {
     }
 
     const updatedAt = now()
+    const planScope = await persistPlanScope(loaded.paths, hash, plan, { importedAt: updatedAt, previousPlanHash: loaded.state.planHash || null })
     const state = {
       ...loaded.state,
       schemaVersion: STATE_SCHEMA,
@@ -392,6 +400,7 @@ export async function importPlan(root, slug, planInput) {
       planImportedAt: updatedAt,
       planHash: hash,
       planApproval: { status: "pending", planHash: hash, at: updatedAt, evidence: null },
+      planScope,
       integrationVerification: null,
       checkpoint: null,
       evidencePolicy: evidencePolicyForPlan(plan),
@@ -414,6 +423,7 @@ export async function approvePlan(root, slug, evidence, options = {}) {
     const loaded = await loadWork(root, slug)
     if (!loaded.plan) throw new Error("PLAN.json is missing")
     const hash = planHash(loaded.plan)
+    await assertActivePlanScope(loaded.paths, loaded.state.planHash || hash)
     if (loaded.state.planHash && loaded.state.planHash !== hash) {
       throw new Error("PLAN.json changed after import; re-import it before approval")
     }
@@ -525,7 +535,9 @@ export async function workStatus(root, slug) {
       leaseExpiresAt: value.leaseExpiresAt || null,
     }))
   const taskEntries = Object.values(loaded.state.tasks || {})
-  const receiptBacked = taskEntries.filter((value) => value.evidenceStrength === "receipt-backed").length
+  const receiptBacked = taskEntries.filter((value) =>
+    ["receipt-backed", "command-receipt-backed", "independent-agent-receipt-backed"].includes(value.evidenceStrength)
+  ).length
   const completed = taskEntries.filter((value) => value.status === "completed").length
 
   return {
@@ -540,6 +552,7 @@ export async function workStatus(root, slug) {
     blockers: loaded.state.blockers || [],
     planApproval: loaded.state.planApproval || null,
     integrationVerification: loaded.state.integrationVerification || null,
+    planScope: loaded.state.planScope || null,
     evidence: {
       receiptBacked,
       completed,
@@ -557,6 +570,7 @@ export async function startTask(root, slug, taskID, options = {}) {
   const result = await withWorkLock(root, slug, async () => {
     const loaded = await loadWork(root, slug)
     if (!loaded.plan) throw new Error("PLAN.json is missing; import a valid plan first")
+    await assertActivePlanScope(loaded.paths, loaded.state.planHash || planHash(loaded.plan))
     if (!planIsApproved(loaded.state, loaded.plan)) {
       throw new Error("plan is not approved; run ues-plan-checker and 'ocskill work approve-plan' first")
     }
@@ -812,7 +826,13 @@ export async function completeTask(root, slug, taskID, options = {}) {
     record.status = "completed"
     record.completedAt = timestamp
     record.report = path.relative(loaded.paths.root, reportPath).replaceAll("\\", "/")
-    record.evidenceStrength = acceptedReceipts.length ? "receipt-backed" : "narrative"
+    const commandReceipts = acceptedReceipts.filter((item) => item.kind !== "agent-verifier")
+    const agentVerifierReceipts = acceptedReceipts.filter((item) => item.kind === "agent-verifier")
+    record.evidenceStrength = commandReceipts.length
+      ? "command-receipt-backed"
+      : agentVerifierReceipts.length
+        ? "independent-agent-receipt-backed"
+        : "narrative"
     record.runId = null
     record.owner = null
     record.heartbeatAt = null
@@ -888,16 +908,19 @@ export async function failTask(root, slug, taskID, reason, options = {}) {
 }
 
 export async function addDecision(root, slug, decision) {
-  const text = String(decision || "").trim()
+  const input = decision && typeof decision === "object" ? decision : { text: decision }
+  const text = String(input.text || "").trim()
   if (!text) throw new Error("decision text is required")
-
+  const policy = classifyDecisionPolicy(text, input.facts || input)
+  if (input.auto === true && !policy.autoResolvable) throw new Error("decision requires human approval before automatic resolution")
   return withWorkLock(root, slug, async () => {
     const loaded = await loadWork(root, slug)
     loaded.state.decisions ??= []
     const timestamp = now()
-    loaded.state.decisions.push({ at: timestamp, text })
+    loaded.state.decisions.push({ at: timestamp, text, policy, source: input.source || (input.auto === true ? "auto-ruling" : "human-or-agent") })
     loaded.state.updatedAt = timestamp
     await writeJson(loaded.paths.state, loaded.state)
+    await journal(loaded.paths, "decision.recorded", { text, policy })
     return loaded.state
   })
 }
@@ -1071,14 +1094,15 @@ export async function finalizeWork(root, slug, evidence) {
 async function buildContextPack(loaded, taskID) {
   if (!loaded.plan) throw new Error("PLAN.json is missing")
   const task = taskByID(loaded.plan, taskID)
-  const spec = await readFile(loaded.paths.spec, "utf8").catch(() => "")
+  let spec = ""
+  try { spec = readTextAuto(loaded.paths.spec) } catch {}
   const dependencyReports = {}
   const dependencyReportRefs = {}
 
   for (const dep of task.dependsOn || []) {
     const file = path.join(loaded.paths.reports, `${dep}.md`)
     if (!existsSync(file)) continue
-    const report = await readFile(file, "utf8")
+    const report = readTextAuto(file)
     dependencyReports[dep] = report.slice(0, 6000)
     const stored = await putEvidence(loaded.paths.root, report, {
       kind: "dependency-report",

package/lib/task-graph.mjs

@@ -48,6 +48,20 @@ export function taskReadFiles(task) {
   return [...new Set((files.read || []).map(normalizeFile).filter(Boolean))].sort()
 }
 
+
+export function taskVerificationCommands(task) {
+  if (!Array.isArray(task?.verificationCommands)) return []
+  return task.verificationCommands
+    .map((item) => {
+      if (!item || typeof item !== "object" || Array.isArray(item)) return null
+      const command = String(item.command || "").trim()
+      if (!command) return null
+      const args = Array.isArray(item.args) ? item.args.map((value) => String(value)) : []
+      return { command, args }
+    })
+    .filter(Boolean)
+}
+
 function taskMap(plan) {
   return new Map((plan?.tasks || []).map((task) => [task.id, task]))
 }
@@ -97,6 +111,24 @@ export function validatePlan(plan) {
       errors.push(`${id || prefix}: verification must contain at least one concrete check`)
     }
 
+    if (task.verificationCommands !== undefined) {
+      if (!Array.isArray(task.verificationCommands)) {
+        errors.push(`${id || prefix}.verificationCommands must be an array when provided`)
+      } else {
+        for (const [commandIndex, commandSpec] of task.verificationCommands.entries()) {
+          const commandPrefix = `${id || prefix}.verificationCommands[${commandIndex}]`
+          if (!commandSpec || typeof commandSpec !== "object" || Array.isArray(commandSpec)) {
+            errors.push(`${commandPrefix} must be an object`)
+            continue
+          }
+          if (!String(commandSpec.command || "").trim()) errors.push(`${commandPrefix}.command is required`)
+          if (commandSpec.args !== undefined && !Array.isArray(commandSpec.args)) {
+            errors.push(`${commandPrefix}.args must be an array when provided`)
+          }
+        }
+      }
+    }
+
     const risk = task.risk ?? "medium"
     if (!VALID_RISKS.has(risk)) errors.push(`${id || prefix}: invalid risk '${risk}'`)