opencode-agent-skill 14.4.0 → 15.1.0

package/lib/execution-contract.mjs

@@ -0,0 +1,592 @@
+import { createHash } from "node:crypto"
+import { spawnSync } from "node:child_process"
+import { lstatSync, readFileSync, readlinkSync } from "node:fs"
+import path from "node:path"
+import { sourceFacingPaths } from "./runtime-artifacts.mjs"
+
+const PHASE_HEADING = /^\s*(?:=+\s*)?PHASE\s+(\d+)\s*(?:[—–:-]+)\s*(.+?)\s*$/i
+const LOCAL_ENV_BASENAME = /^\.env(?:\.[^/\\]+)?$/i
+const ENV_TEMPLATE_BASENAME = /^\.env\.(?:example|sample|template)$/i
+
+function normalizePath(value) {
+  return String(value || "").trim().replaceAll("\\", "/").replace(/^\.\//, "")
+}
+
+function slugify(value) {
+  return String(value || "phase")
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48) || "phase"
+}
+
+function sha256(value) {
+  return createHash("sha256").update(String(value || "")).digest("hex")
+}
+
+export function isLocalEnvPath(value) {
+  const normalized = normalizePath(value)
+  const base = normalized.split("/").pop() || ""
+  if (ENV_TEMPLATE_BASENAME.test(base)) return false
+  return LOCAL_ENV_BASENAME.test(base)
+}
+
+export function crossToolTempPathRisk(value, platform = process.platform) {
+  const raw = String(value || "").trim().replaceAll("\\", "/")
+  if (!raw || String(platform || "").toLowerCase() !== "win32") {
+    return { risky: false, id: null, path: raw || null }
+  }
+  const risky = /^\/(?:tmp|var\/tmp)(?:\/|$)/i.test(raw)
+  return {
+    risky,
+    id: risky ? "cross-tool-posix-temp-path" : null,
+    path: raw || null,
+  }
+}
+
+export function taskExplicitlyAllowsLocalEnvWrite(task) {
+  const value = String(task || "")
+  const mentionsEnv = /(?:^|[\s"'\x60/])\.env(?:\.[\w.-]+)?(?=$|[\s"'\x60,;:.)/])/i.test(value)
+  if (!mentionsEnv) return false
+  const denied =
+    /(?:do\s+not|don't|never|must\s+not|không|khong|cấm|cam).{0,80}(?:modify|edit|update|write|create|set|change|sửa|chỉnh sửa|cập nhật|ghi|tạo|thay đổi)?[^\n.]*\.env|\.env[^\n.]*.{0,40}(?:do\s+not|must\s+not|không|khong|cấm|cam)/i.test(value)
+  if (denied) return false
+  return /(?:modify|edit|update|write|create|set|change|sửa|chỉnh sửa|cập nhật|ghi|tạo|thay đổi).{0,80}\.env|\.env.{0,80}(?:modify|edit|update|write|create|set|change|sửa|chỉnh sửa|cập nhật|ghi|tạo|thay đổi)/i.test(value)
+}
+
+export function localEnvWriteRisk(command) {
+  const value = String(command || "")
+  if (!value.trim()) return { risky: false, id: null }
+  const localEnv = String.raw`\.env(?!\.(?:example|sample|template)\b)(?:\.[\w.-]+)?\b`
+  const patterns = [
+    new RegExp(String.raw`(?:>|>>)[^\n;&|]*${localEnv}`, "i"),
+    new RegExp(String.raw`\b(?:sed|perl)\b[^\n;&|]*\s-i\b[^\n;&|]*${localEnv}`, "i"),
+    new RegExp(String.raw`\b(?:set-content|add-content|out-file|copy-item|move-item|rename-item)\b[^\n;&|]*${localEnv}`, "i"),
+    new RegExp(String.raw`\b(?:cp|mv|install)\b[^\n;&|]*\s${localEnv}`, "i"),
+    new RegExp(String.raw`\b(?:writeFileSync|writeFile|appendFileSync|appendFile)\s*\([^\n)]*["']${localEnv}["']`, "i"),
+    new RegExp(String.raw`\bopen\s*\([^\n)]*["']${localEnv}["'][^\n)]*["'](?:w|a|x)[+b]?["']`, "i"),
+  ]
+  return patterns.some((pattern) => pattern.test(value))
+    ? { risky: true, id: "local-env-write" }
+    : { risky: false, id: null }
+}
+
+function inheritedPathState(root, relative) {
+  const normalized = normalizePath(relative)
+  const full = path.resolve(root, normalized)
+  const rel = normalizePath(path.relative(path.resolve(root), full))
+  if (!normalized || rel === ".." || rel.startsWith("../") || path.isAbsolute(rel)) {
+    return { exists: false, kind: "outside", hash: null, size: 0 }
+  }
+  try {
+    const info = lstatSync(full)
+    if (info.isSymbolicLink()) {
+      const target = readlinkSync(full)
+      return {
+        exists: true,
+        kind: "symlink",
+        hash: sha256("symlink\0" + target),
+        size: Buffer.byteLength(target),
+      }
+    }
+    if (!info.isFile()) {
+      return {
+        exists: true,
+        kind: info.isDirectory() ? "directory" : "other",
+        hash: sha256(info.isDirectory() ? "directory" : "other"),
+        size: Number(info.size || 0),
+      }
+    }
+    const bytes = readFileSync(full)
+    return {
+      exists: true,
+      kind: "file",
+      hash: createHash("sha256").update(bytes).digest("hex"),
+      size: bytes.length,
+    }
+  } catch (error) {
+    if (error?.code === "ENOENT") return { exists: false, kind: "missing", hash: null, size: 0 }
+    return {
+      exists: false,
+      kind: "unreadable",
+      hash: sha256(String(error?.code || error?.message || error)),
+      size: 0,
+    }
+  }
+}
+
+function pathMentionedWithMutationIntent(task, relative) {
+  const text = String(task || "").replaceAll("\\", "/")
+  const needle = normalizePath(relative)
+  if (!needle) return false
+  const lower = text.toLowerCase()
+  const target = needle.toLowerCase()
+  let index = lower.indexOf(target)
+  while (index >= 0) {
+    const start = Math.max(0, index - 140)
+    const end = Math.min(text.length, index + target.length + 140)
+    const window = text.slice(start, end)
+    const denied =
+      /(?:do\s+not|don't|never|must\s+not|without|không|khong|cấm|cam).{0,100}(?:edit|modify|change|write|create|delete|remove|update|fix|sửa|chỉnh sửa|thay đổi|ghi|tạo|xóa|xoá|cập nhật)[^\n.]{0,100}/i.test(window) ||
+      /(?:edit|modify|change|write|create|delete|remove|update|fix|sửa|chỉnh sửa|thay đổi|ghi|tạo|xóa|xoá|cập nhật)[^\n.]{0,100}(?:do\s+not|don't|never|must\s+not|without|không|khong|cấm|cam)/i.test(window)
+    const mutation =
+      /(?:fix|repair|implement|edit|modify|change|write|create|delete|remove|update|refactor|migrate|rename|sửa|chỉnh sửa|thay đổi|ghi|tạo|xóa|xoá|cập nhật|đổi tên)/i.test(window)
+    if (mutation && !denied) return true
+    index = lower.indexOf(target, index + target.length)
+  }
+  return false
+}
+
+export function explicitlyAuthorizedInheritedDirtyPaths(task, dirtyPaths = []) {
+  return [...new Set((dirtyPaths || [])
+    .map(normalizePath)
+    .filter(Boolean)
+    .filter((item) => pathMentionedWithMutationIntent(task, item)))]
+}
+
+export function detectInheritedDirtyViolations(root, snapshot, approvedPaths = []) {
+  if (!snapshot?.available || !Array.isArray(snapshot.entries)) {
+    return { safe: false, violations: [], reason: "inherited-dirty-snapshot-unavailable" }
+  }
+  const approved = new Set((approvedPaths || []).map(normalizePath).filter(Boolean))
+  const violations = []
+  for (const entry of snapshot.entries) {
+    const relative = normalizePath(entry.path)
+    if (!relative || approved.has(relative)) continue
+    const before = entry.state || null
+    const after = inheritedPathState(root, relative)
+    if (
+      !before ||
+      before.exists !== after.exists ||
+      before.kind !== after.kind ||
+      before.hash !== after.hash ||
+      Number(before.size || 0) !== Number(after.size || 0)
+    ) {
+      violations.push({ path: relative, before, after })
+    }
+  }
+  return {
+    safe: violations.length === 0,
+    violations,
+    reason: violations.length ? "inherited-dirty-work-modified" : null,
+  }
+}
+
+export function captureInheritedDirtyState(root, options = {}) {
+  const resolved = path.resolve(root)
+  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 = statusOutput.split("\0").filter(Boolean)
+  const entries = []
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index]
+    if (token.length < 3) continue
+    const status = token.slice(0, 2)
+    const separator = token[2]
+    if (separator !== " ") continue
+    const currentPath = normalizePath(token.slice(3))
+    let originalPath = null
+    if (/[RC]/.test(status) && index + 1 < tokens.length) {
+      originalPath = normalizePath(tokens[index + 1])
+      index += 1
+    }
+    if (!currentPath) continue
+    entries.push({ status, path: currentPath, originalPath })
+  }
+
+  const generatedArtifact = /(?:^|\/)(?:node_modules|\.next(?:-desktop)?|dist|build|coverage|\.turbo|\.cache)(?:\/|$)/i
+  const paths = sourceFacingPaths(
+    entries.flatMap((entry) => [entry.path, entry.originalPath].filter(Boolean)),
+  ).filter((item) => !generatedArtifact.test(item)).sort()
+  const pathSet = new Set(paths)
+  const sourceEntries = entries
+    .filter((entry) =>
+      pathSet.has(entry.path) || (entry.originalPath && pathSet.has(entry.originalPath))
+    )
+    .map((entry) => ({
+      ...entry,
+      state: inheritedPathState(resolved, entry.path),
+      ...(entry.originalPath ? { originalState: inheritedPathState(resolved, entry.originalPath) } : {}),
+    }))
+  return {
+    schemaVersion: 1,
+    available: true,
+    clean: paths.length === 0,
+    root: resolved,
+    entries: sourceEntries,
+    paths,
+  }
+}
+
+export function extractExplicitPhases(task) {
+  const lines = String(task || "").split(/\r?\n/)
+  const phases = []
+  let current = null
+
+  const flush = () => {
+    if (!current) return
+    const body = current.lines.join("\n").trim()
+    const number = Number(current.number)
+    const title = current.title.trim()
+    const slug = slugify(title)
+    const constraintOnly =
+      /(?:do not|không được làm|tuyệt đối không|guardrail|constraint|prohibited)/i.test(title) ||
+      /(?:TUYỆT ĐỐI KHÔNG|MUST NOT|DO NOT)\s*:/i.test(body)
+    phases.push({
+      number,
+      title,
+      slug,
+      kind: constraintOnly ? "constraint" : "execution",
+      body,
+      bodyHash: sha256(body),
+      artifact: `phases/phase-${String(number).padStart(2, "0")}-${slug}.json`,
+    })
+    current = null
+  }
+
+  for (const line of lines) {
+    const match = line.match(PHASE_HEADING)
+    if (match) {
+      flush()
+      current = { number: match[1], title: match[2], lines: [] }
+      continue
+    }
+    if (current) current.lines.push(line)
+  }
+  flush()
+
+  phases.sort((a, b) => a.number - b.number)
+  return phases
+}
+
+function taskPhaseNumber(task) {
+  const explicit = Number(task?.phase)
+  if (Number.isInteger(explicit) && explicit >= 0) return explicit
+  const text = [task?.id, task?.title, task?.summary].filter(Boolean).join(" ")
+  const match = text.match(/\bphase\s*[-_:]?\s*(\d+)\b/i)
+  return match ? Number(match[1]) : null
+}
+
+export function enforcePhaseGates(plan, contract) {
+  if (!contract?.phases?.length) {
+    return { valid: true, plan, errors: [], assignments: {} }
+  }
+  if (!plan || !Array.isArray(plan.tasks)) {
+    return { valid: false, plan, errors: ["phase-gated plan must contain tasks"], assignments: {} }
+  }
+
+  const executionPhases = contract.phases.filter((phase) => phase.kind !== "constraint")
+  const allowed = new Set(executionPhases.map((phase) => Number(phase.number)))
+  const assignments = {}
+  const errors = []
+  const byPhase = new Map()
+  const taskById = new Map(plan.tasks.map((task) => [String(task.id), task]))
+
+  for (const task of plan.tasks) {
+    const phase = taskPhaseNumber(task)
+    if (phase == null) {
+      errors.push(`task ${task.id} is missing an explicit phase number`)
+      continue
+    }
+    if (!allowed.has(phase)) {
+      errors.push(`task ${task.id} declares unknown phase ${phase}`)
+      continue
+    }
+    assignments[String(task.id)] = phase
+    if (!byPhase.has(phase)) byPhase.set(phase, [])
+    byPhase.get(phase).push(String(task.id))
+  }
+
+  for (const phase of executionPhases) {
+    if (!(byPhase.get(Number(phase.number)) || []).length) {
+      errors.push(`explicit PHASE ${phase.number} has no planned task`)
+    }
+  }
+
+  for (const task of plan.tasks) {
+    const taskPhase = assignments[String(task.id)]
+    if (taskPhase == null) continue
+    for (const dep of Array.isArray(task.dependsOn) ? task.dependsOn : []) {
+      const depPhase = assignments[String(dep)]
+      if (depPhase != null && depPhase > taskPhase) {
+        errors.push(`task ${task.id} in phase ${taskPhase} depends on later phase ${depPhase} task ${dep}`)
+      }
+      if (!taskById.has(String(dep))) {
+        errors.push(`task ${task.id} depends on missing task ${dep}`)
+      }
+    }
+  }
+
+  if (errors.length) return { valid: false, plan, errors, assignments }
+
+  const orderedPhases = executionPhases.map((phase) => Number(phase.number)).sort((a, b) => a - b)
+  const tasks = plan.tasks.map((task) => ({
+    ...task,
+    phase: assignments[String(task.id)],
+    dependsOn: [...new Set(Array.isArray(task.dependsOn) ? task.dependsOn.map(String) : [])],
+  }))
+
+  for (let index = 1; index < orderedPhases.length; index += 1) {
+    const previous = byPhase.get(orderedPhases[index - 1]) || []
+    const current = new Set(byPhase.get(orderedPhases[index]) || [])
+    for (const task of tasks) {
+      if (!current.has(String(task.id))) continue
+      task.dependsOn = [...new Set([...task.dependsOn, ...previous])].filter((id) => id !== String(task.id))
+    }
+  }
+
+  return {
+    valid: true,
+    plan: {
+      ...plan,
+      tasks,
+      phaseGate: {
+        schemaVersion: 1,
+        orderedPhases,
+        barrierStrategy: "previous-phase-all-tasks",
+      },
+    },
+    errors: [],
+    assignments,
+  }
+}
+
+export function dataCleanupSafetyRequired(task) {
+  const value = String(task || "")
+  return /(?:cleanup|clean up|dọn|don dep|dọn dẹp|xóa fixture|xoá fixture)/i.test(value) &&
+    /(?:database|\bdb\b|fixture|seed|catalog|dữ liệu|du lieu|prisma|sql)/i.test(value)
+}
+
+export function deviceVerificationRequired(task) {
+  return /(?:expo go|real device|physical device|manual mobile acceptance|test thiết bị|thiết bị thật|device verification)/i.test(String(task || ""))
+}
+
+export function runtimeVerificationRequired(task) {
+  return /(?:runtime|smoke|e2e|integration|api thật|api real|real api|endpoint|build|typecheck|lint|tests?|jest|vitest|pytest|playwright|gradle|maven|cargo test|go test)/i.test(String(task || ""))
+}
+
+export function buildExecutionContract(task, inheritedDirty = null) {
+  const phases = extractExplicitPhases(task)
+  const dirty = inheritedDirty || {
+    schemaVersion: 1,
+    available: false,
+    clean: false,
+    entries: [],
+    paths: [],
+  }
+  const dbCleanup = dataCleanupSafetyRequired(task)
+  const device = deviceVerificationRequired(task)
+  const runtime = runtimeVerificationRequired(task)
+
+  const approvedInheritedDirtyPaths = explicitlyAuthorizedInheritedDirtyPaths(
+    task,
+    dirty.paths || [],
+  )
+
+  return {
+    schemaVersion: 1,
+    taskHash: sha256(task),
+    inheritedDirty: dirty,
+    approvedInheritedDirtyPaths,
+    localEnvWriteExplicitlyAllowed: taskExplicitlyAllowsLocalEnvWrite(task),
+    phases,
+    gates: {
+      source: true,
+      runtime,
+      dbClean: dbCleanup,
+      device,
+    },
+    invariants: [
+      "Preserve pre-existing dirty work. Never restore, checkout-away, clean, stash, or overwrite inherited changes unless the file is explicitly in the approved task write scope.",
+      "Treat .env and .env.* as local runtime inputs. Do not modify them unless the user explicitly requested that exact local env mutation. Prefer .env.example/sample/template and docs for repository changes.",
+      "Never claim cleanup success from frontend filtering or hidden presentation logic; prove cleanup at the data/source layer.",
+      "Do not cross an explicit PHASE boundary without verified evidence for prerequisite work represented in the approved plan.",
+    ],
+    databaseCleanupGate: dbCleanup
+      ? {
+          requireProductionRefusal: true,
+          requireDryRun: true,
+          requireExactIds: true,
+          requirePrePostCounts: true,
+          requireDeterministicMarkers: true,
+          requireCanonicalPreservation: true,
+          requireIdempotencyProof: true,
+          preferTransactionRollback: true,
+        }
+      : null,
+  }
+}
+
+export function executionContractPrompt(contract) {
+  if (!contract) return ""
+  const dirtyPaths = Array.isArray(contract.inheritedDirty?.paths)
+    ? contract.inheritedDirty.paths.slice(0, 120)
+    : []
+  const phaseSummary = Array.isArray(contract.phases)
+    ? contract.phases.map((phase) => `PHASE ${phase.number} [${phase.kind}]: ${phase.title} -> ${phase.artifact}`)
+    : []
+  const approvedDirty = Array.isArray(contract.approvedInheritedDirtyPaths)
+    ? contract.approvedInheritedDirtyPaths.slice(0, 120)
+    : []
+  const lines = [
+    "## UES deterministic execution contract",
+    "These constraints are controller-owned and must not be weakened by the model.",
+    ...contract.invariants.map((item) => "- " + item),
+    dirtyPaths.length
+      ? "\nInherited dirty paths present before this UES run (preserve unless explicitly approved in task write scope):\n" +
+        dirtyPaths.map((item) => "- " + item).join("\n") +
+        (approvedDirty.length
+          ? "\nExplicitly approved inherited dirty mutation scope:\n" + approvedDirty.map((item) => "- " + item).join("\n")
+          : "\nExplicitly approved inherited dirty mutation scope: none.")
+      : "\nInherited dirty paths: none detected.",
+    contract.localEnvWriteExplicitlyAllowed
+      ? "\nLocal .env mutation: explicitly requested by the user for this task."
+      : "\nLocal .env mutation: NOT authorized. Do not edit .env/.env.local/.env.development/etc.; use templates/docs or report NEEDS_USER_ENV.",
+    phaseSummary.length
+      ? "\nExplicit phase contract:\n" + phaseSummary.map((item) => "- " + item).join("\n")
+      : "",
+  ]
+
+  if (contract.databaseCleanupGate) {
+    lines.push(
+      "",
+      "Database cleanup gate:",
+      "- refuse production targets;",
+      "- perform a dry-run before deletion;",
+      "- record exact candidate IDs and pre/post entity counts;",
+      "- delete only fixtures linked to deterministic audited markers/source;",
+      "- preserve canonical seed and user history;",
+      "- prove idempotency with a second cleanup pass;",
+      "- use transaction/rollback protection when the stack supports it.",
+    )
+  }
+
+  lines.push(
+    "",
+    "Final verdict markers:",
+    "- SOURCE_PASS only after source/task verification and integration gates pass.",
+    contract.gates.runtime
+      ? "- RUNTIME_PASS only with fresh executable/runtime evidence; otherwise RUNTIME_NOT_VERIFIED."
+      : "- RUNTIME_NOT_REQUIRED.",
+    contract.gates.dbClean
+      ? "- DB_CLEAN_PASS only with data-layer cleanup/public-data evidence; otherwise DB_CLEAN_NOT_VERIFIED."
+      : "- DB_CLEAN_NOT_REQUIRED.",
+    contract.gates.device
+      ? "- DEVICE_PASS only after a real requested device check; otherwise DEVICE_NOT_VERIFIED."
+      : "- DEVICE_NOT_REQUIRED.",
+  )
+
+  return lines.filter(Boolean).join("\n")
+}
+
+export function buildFinalVerdictMatrix(task, evidence = {}) {
+  const contract = evidence.contract || buildExecutionContract(task)
+  const text = [
+    evidence.primaryOutput,
+    evidence.integrationOutput,
+    evidence.visualOutput,
+  ].filter(Boolean).join("\n")
+
+  const sourcePass = evidence.primaryPass === true && evidence.integrationPass !== false
+  const runtimeCheckText = [
+    evidence.primaryChecks,
+    evidence.integrationChecks,
+    evidence.visualChecks,
+  ].filter(Boolean).join("\n")
+  const executableRuntimeEvidence =
+    evidence.primaryPass === true &&
+    evidence.integrationPass !== false &&
+    /(?:\b(?:npm|pnpm|yarn|node|pytest|jest|vitest|gradle|mvn|dotnet|cargo|go)\b|runtime:smoke|e2e|typecheck|lint|curl\s|http:\/\/|https:\/\/)/i.test(runtimeCheckText)
+  const runtime = !contract.gates.runtime
+    ? "RUNTIME_NOT_REQUIRED"
+    : executableRuntimeEvidence
+      ? "RUNTIME_PASS"
+      : "RUNTIME_NOT_VERIFIED"
+  const dbCleanupEvidence =
+    evidence.primaryPass === true &&
+    evidence.integrationPass !== false &&
+    /\bDB_CLEAN_PASS\b/i.test(text) &&
+    /(?:dry[- ]?run|cleanup|fixture|seed|catalog|prisma|sql|dữ liệu|du lieu)/i.test(text + "\n" + runtimeCheckText) &&
+    /(?:idempotent|second\s+(?:cleanup|run|pass)|lần\s+(?:2|hai)|repeat(?:ed)?\s+run)/i.test(text) &&
+    /(?:count|removed|deleted|records?|xóa|xoá|đã dọn|pre[- ]?count|post[- ]?count|before|after|trước|sau)/i.test(text)
+  const dbClean = !contract.gates.dbClean
+    ? "DB_CLEAN_NOT_REQUIRED"
+    : dbCleanupEvidence
+      ? "DB_CLEAN_PASS"
+      : "DB_CLEAN_NOT_VERIFIED"
+  const deviceEvidence =
+    /\bDEVICE_PASS\b/i.test(text) &&
+    /(?:adb\s+(?:devices|shell)|expo\s+go|physical\s+device|thiết\s+bị\s+thật)/i.test(runtimeCheckText)
+  const device = !contract.gates.device
+    ? "DEVICE_NOT_REQUIRED"
+    : deviceEvidence
+      ? "DEVICE_PASS"
+      : "DEVICE_NOT_VERIFIED"
+
+  const source = sourcePass ? "SOURCE_PASS" : "SOURCE_NOT_VERIFIED"
+  const sourceRuntimeDataPass =
+    sourcePass &&
+    (!contract.gates.runtime || runtime === "RUNTIME_PASS") &&
+    (!contract.gates.dbClean || dbClean === "DB_CLEAN_PASS")
+  const requiredPass =
+    sourceRuntimeDataPass &&
+    (!contract.gates.device || device === "DEVICE_PASS")
+
+  return {
+    schemaVersion: 1,
+    source,
+    runtime,
+    dbClean,
+    device,
+    final: requiredPass
+      ? "PASS"
+      : sourceRuntimeDataPass && device === "DEVICE_NOT_VERIFIED"
+        ? "SOURCE_RUNTIME_PASS_DEVICE_NOT_VERIFIED"
+        : "PARTIAL_OR_NOT_VERIFIED",
+  }
+}
+
+export function phaseArtifactPayloads(contract) {
+  return (contract?.phases || []).map((phase) => ({
+    file: phase.artifact,
+    value: {
+      schemaVersion: 1,
+      phase: phase.number,
+      title: phase.title,
+      sourceBodyHash: phase.bodyHash,
+      sourceBody: phase.body,
+      status: "PENDING",
+      evidence: [],
+    },
+  }))
+}

package/lib/leaf-runtime-optimizer.mjs

@@ -0,0 +1,76 @@
+import { classifyEngineeringTask } from "./task-policy.mjs"
+
+function strings(value) {
+  if (!value) return []
+  return (Array.isArray(value) ? value : [value]).map(String).map((item) => item.trim()).filter(Boolean)
+}
+
+function declaredWriteFiles(task = {}) {
+  const files = task?.files || {}
+  return [...new Set([
+    ...strings(files.create),
+    ...strings(files.modify),
+    ...strings(files.test),
+    ...strings(files.delete),
+  ].map((item) => item.replaceAll("\\", "/")))]
+}
+
+export function leafTaskPolicy(task = {}, rootPolicy = {}) {
+  const writeFiles = declaredWriteFiles(task)
+  const readFiles = strings(task?.files?.read)
+  const text = [
+    task?.title,
+    task?.summary,
+    ...strings(task?.acceptance),
+    ...strings(task?.verification),
+    task?.riskNotes,
+    writeFiles.length ? "Declared write files: " + writeFiles.join(", ") : "",
+    readFiles.length ? "Declared read files: " + readFiles.join(", ") : "",
+  ].filter(Boolean).join("\n")
+
+  const policy = classifyEngineeringTask(text, {
+    declaredFiles: writeFiles,
+    changedFiles: writeFiles.length,
+    risk: task?.risk,
+    longHorizon: false,
+    failureEvidence: false,
+  })
+
+  // The root may be DEEP because the overall project is large; do not force an
+  // independent low-risk leaf to pay that cost. Root safety is preserved by the
+  // final integration/completion gates and by leaf-declared risk.
+  return {
+    ...policy,
+    requireFreshEvidence: true,
+    rootExecutionProfile: rootPolicy?.executionProfile || null,
+    rootRisk: rootPolicy?.risk || null,
+    localEnvWriteExplicitlyAllowed: rootPolicy?.localEnvWriteExplicitlyAllowed === true,
+    leafOptimized: true,
+  }
+}
+
+const FAILURE_SIGNAL = /(?:\bFAIL(?:ED|URE)?\b|\bERROR\b|AssertionError|TypeError|ReferenceError|SQLSTATE|ECONN\w*|EADDRINUSE|expected|actual|exit(?:Code| code)?\s*[:=]?\s*[1-9]|timed?\s*out|timeout|not found|cannot|unable|mismatch|regression|✖|×)/i
+const FILE_SIGNAL = /(?:^|\s)(?:[A-Za-z]:)?[^\s:]+\.(?:[cm]?[jt]sx?|py|go|rs|java|kt|cs|sql|json|yaml|yml)(?::\d+(?::\d+)?)?/i
+
+export function failureDelta(output, options = {}) {
+  const maxChars = Math.max(1200, Math.min(8000, Number(options.maxChars || 4200)))
+  const raw = String(output || "").trim()
+  if (!raw) return ""
+
+  const lines = raw.split(/\r?\n/)
+  const selected = []
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (!FAILURE_SIGNAL.test(line) && !FILE_SIGNAL.test(line)) continue
+    if (i > 0 && lines[i - 1].trim()) selected.push(lines[i - 1])
+    selected.push(line)
+    if (i + 1 < lines.length && lines[i + 1].trim()) selected.push(lines[i + 1])
+  }
+
+  const compact = [...new Set(selected.map((line) => line.trim()).filter(Boolean))].join("\n")
+  if (compact) return compact.slice(0, maxChars)
+
+  // Fail closed on unknown output shape: keep a bounded tail, which usually
+  // contains the final verdict/error without replaying the entire previous turn.
+  return raw.slice(Math.max(0, raw.length - maxChars))
+}