@cleocode/goal 0.0.0-stage → 0.9.0

package/src/contract/parse.ts

@@ -0,0 +1,454 @@
+// Parses and validates goal.yaml. Every rule here is one the write-goal skill
+// relies on to tell a loop-verifiable goal from a wish.
+import { createHash } from "node:crypto"
+import { parse as parseYamlPortable } from "yaml"
+import {
+  AMEND_CLASSES,
+  CHECK_KINDS,
+  CLEO_GATES,
+  type AmendClass,
+  type CleoGate,
+  type CleoTaskLink,
+  type GoalAcRef,
+  HOST_KINDS,
+  PRIORITIES,
+  SCHEMA,
+  type Assumption,
+  type Autonomy,
+  type Budget,
+  type Check,
+  type Contract,
+  type Criterion,
+  type Issue,
+  type Priority,
+  type Step,
+  type VerificationMode,
+} from "./types"
+
+export type ParseResult = { contract?: Contract; issues: Issue[]; lock: string }
+
+const VAGUE = [
+  "fast",
+  "faster",
+  "quick",
+  "quickly",
+  "robust",
+  "clean",
+  "cleaner",
+  "better",
+  "properly",
+  "proper",
+  "nice",
+  "good",
+  "efficient",
+  "scalable",
+  "intuitive",
+  "user-friendly",
+  "seamless",
+  "seamlessly",
+  "optimal",
+  "optimized",
+  "improved",
+  "reasonable",
+  "appropriate",
+  "correctly",
+  "works",
+]
+const ACTIVITY = /^(keep|continue|improve|investigate|explore|work on|look into|try to|help|refactor as needed|clean up)\b/i
+/**
+ * v0.5.1 - the three CLEO `satisfies:` AC-reference forms a `proves:` entry may
+ * take: `T123#AC2`, `T123#<uuid>` and `T123#AC2@<14-digit pin>`.
+ */
+export const AC_REF = /^T\d+#(?:AC\d{1,4}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})(?:@\d{14})?$/
+
+export const lockOf = (text: string) => createHash("sha256").update(text).digest("hex")
+
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+const str = (v: unknown) => (typeof v === "string" ? v.trim() : typeof v === "number" ? String(v) : "")
+const strings = (v: unknown): string[] => (Array.isArray(v) ? v.map(str).filter(Boolean) : typeof v === "string" && v.trim() ? [v.trim()] : [])
+
+/** "90m", "3h", "1h30m", "45s", "2d" → ms. A bare number means minutes. */
+export function parseDuration(value: unknown): number | undefined {
+  if (typeof value === "number") return value > 0 ? value * 60_000 : undefined
+  const text = str(value).toLowerCase().replace(/\s+/g, "")
+  if (!text) return undefined
+  const units: Record<string, number> = { d: 86_400_000, h: 3_600_000, m: 60_000, s: 1000 }
+  let total = 0
+  let matched = ""
+  for (const part of text.matchAll(/(\d+(?:\.\d+)?)([dhms])/g)) {
+    total += Number(part[1]) * units[part[2]!]!
+    matched += part[0]
+  }
+  return matched === text && total > 0 ? Math.round(total) : undefined
+}
+
+/** "3M", "400k", "1.5m", 250000 → tokens. */
+export function parseCount(value: unknown): number | undefined {
+  if (typeof value === "number") return value > 0 ? Math.round(value) : undefined
+  const match = /^(\d+(?:\.\d+)?)\s*([kmb])?$/i.exec(str(value))
+  if (!match) return undefined
+  const scale = { k: 1e3, m: 1e6, b: 1e9 }[(match[2] ?? "").toLowerCase() as "k" | "m" | "b"] ?? 1
+  const n = Math.round(Number(match[1]) * scale)
+  return n > 0 ? n : undefined
+}
+
+function vagueWords(text: string): string[] {
+  if (/\d/.test(text)) return []
+  const lower = ` ${text.toLowerCase()} `
+  return VAGUE.filter((word) => new RegExp(`[^a-z-]${word.replace("-", "\\-")}[^a-z-]`).test(lower))
+}
+
+function parseCheck(raw: unknown, path: string, issues: Issue[]): Check | undefined {
+  if (!isRecord(raw)) {
+    issues.push({ level: "error", path, message: "check is required: say how this criterion is proven (a command, a file test, a search, or a verifier question)" })
+    return undefined
+  }
+  const kind = str(raw.kind)
+  if (!(CHECK_KINDS as readonly string[]).includes(kind)) {
+    issues.push({ level: "error", path: `${path}.kind`, message: `unknown check kind "${kind}"; use one of ${CHECK_KINDS.join(", ")}` })
+    return undefined
+  }
+  const need = (field: string, value: string) => {
+    if (!value) issues.push({ level: "error", path: `${path}.${field}`, message: `${kind} check needs ${field}` })
+    return value
+  }
+  switch (kind) {
+    case "command": {
+      const expect = isRecord(raw.expect) ? raw.expect : {}
+      // v0.8.0 D6: an unimplemented expectation key is an ERROR, never silently
+      // dropped. `stderr_contains` used to collapse a criterion to bare
+      // `exit: 0`, which passes while proving nothing.
+      const supported = ["exit", "stdout_contains", "stdout_regex"] as const
+      for (const key of Object.keys(expect))
+        if (!(supported as readonly string[]).includes(key))
+          issues.push({ level: "error", path: `${path}.expect.${key}`, message: `unknown expectation "${key}"; supported: ${supported.join(", ")}` })
+      const out: Check = {
+        kind,
+        run: need("run", str(raw.run)),
+        expect: {
+          ...(expect.exit !== undefined ? { exit: Number(expect.exit) } : {}),
+          ...(str(expect.stdout_contains) ? { stdout_contains: str(expect.stdout_contains) } : {}),
+          ...(str(expect.stdout_regex) ? { stdout_regex: str(expect.stdout_regex) } : {}),
+        },
+        ...(raw.timeout !== undefined ? { timeout: Number(raw.timeout) } : {}),
+        ...(raw.runs !== undefined ? { runs: Math.max(1, Math.min(10, Number(raw.runs) || 1)) } : {}),
+        ...(raw.live === true ? { live: true } : {}),
+      }
+      // T021: a newline in a command check is usually a YAML folded-scalar
+      // accident (>- keeps literal newlines before more-indented lines), which
+      // made run 0ffe5ac6e001 C3 unrunnable — the host shell executed the
+      // skill directory as a command. Intentional multi-line shell is legal,
+      // so warn, and always rehearse the exact stored command before claiming.
+      if (typeof out.run === "string" && out.run.includes("\n"))
+        issues.push({ level: "warning", path: `${path}.run`, message: "command check spans lines: YAML folded scalars (>-) keep literal newlines before more-indented lines, and the host shell will execute each line separately — keep the command on one line unless the newlines are intentional, and rehearse the stored command before claiming" })
+      if (out.expect && out.expect.exit === undefined && !out.expect.stdout_contains && !out.expect.stdout_regex) out.expect.exit = 0
+      if (out.expect?.stdout_regex) {
+        try {
+          new RegExp(out.expect.stdout_regex)
+        } catch {
+          issues.push({ level: "error", path: `${path}.expect.stdout_regex`, message: "not a valid regular expression" })
+        }
+      }
+      if (out.timeout !== undefined && !(out.timeout > 0)) issues.push({ level: "error", path: `${path}.timeout`, message: "timeout must be a positive number of seconds" })
+      return out
+    }
+    case "file":
+      return { kind, path: need("path", str(raw.path)), exists: raw.exists !== false }
+    case "contains": {
+      const text = str(raw.text)
+      const regex = str(raw.regex)
+      if (!text && !regex) issues.push({ level: "error", path, message: "contains check needs text or regex" })
+      return { kind, path: need("path", str(raw.path)), ...(text ? { text } : {}), ...(regex ? { regex } : {}) }
+    }
+    case "absent":
+      return { kind, pattern: need("pattern", str(raw.pattern)), ...(strings(raw.paths).length ? { paths: strings(raw.paths) } : {}) }
+    case "diff": {
+      const paths = strings(raw.paths)
+      if (!paths.length) issues.push({ level: "error", path: `${path}.paths`, message: "diff check needs at least one path" })
+      return { kind, paths }
+    }
+    default:
+      return { kind: kind as "verifier" | "human", ask: need("ask", str(raw.ask)) }
+  }
+}
+
+function parseCriteria(raw: unknown, path: string, prefix: "C" | "I", issues: Issue[]): Criterion[] {
+  if (!Array.isArray(raw)) return []
+  return raw.flatMap((item, index) => {
+    const at = `${path}[${index}]`
+    if (!isRecord(item)) {
+      issues.push({ level: "error", path: at, message: "must be a mapping with id, statement and check" })
+      return []
+    }
+    const id = str(item.id)
+    if (!new RegExp(`^${prefix}\\d+$`).test(id)) issues.push({ level: "error", path: `${at}.id`, message: `id must look like ${prefix}1, ${prefix}2, …` })
+    const statement = str(item.statement)
+    if (!statement) issues.push({ level: "error", path: `${at}.statement`, message: "statement is required" })
+    const vague = vagueWords(statement)
+    if (vague.length) issues.push({ level: "warning", path: `${at}.statement`, message: `vague without a number: ${vague.join(", ")} — state the threshold that proves it` })
+    const check = parseCheck(item.check, `${at}.check`, issues)
+    if (prefix === "I" && check && !(HOST_KINDS as readonly string[]).includes(check.kind))
+      issues.push({ level: "error", path: `${at}.check.kind`, message: "invariants must be host-checkable (command, file, contains, absent or diff)" })
+    if (!check) return []
+    // v0.5.1 - the precise per-criterion CLEO binding: any of the three
+    // satisfies forms (bare AC, uuid, or pinned AC).
+    const provesRaw = strings(item.proves)
+    for (const ref of provesRaw) if (!AC_REF.test(ref)) issues.push({ level: "error", path: `${at}.proves`, message: `AC reference must be one of T123#AC2, T123#<uuid> or T123#AC2@<14-digit pin> (got "${ref}")` })
+    const proves = provesRaw.filter((ref) => AC_REF.test(ref))
+    return [{ id, statement, essential: prefix === "I" ? true : item.essential !== false, check, ...(proves.length ? { proves: proves as GoalAcRef[] } : {}) }]
+  })
+}
+
+type YamlParse = (text: string) => unknown
+/** Bun's built-in parser inside OpenCode (unchanged behaviour); the portable `yaml` package on plain Node (the npm bin). */
+const bunYaml = (globalThis as { Bun?: { YAML?: { parse: YamlParse } } }).Bun?.YAML
+const parseYaml: YamlParse = (text) => (bunYaml ? bunYaml.parse(text) : parseYamlPortable(text))
+
+export function parseContract(text: string, options: { slug?: string } = {}): ParseResult {
+  const issues: Issue[] = []
+  const lock = lockOf(text)
+  let raw: unknown
+  try {
+    raw = parseYaml(text)
+  } catch (error) {
+    issues.push({ level: "error", path: "", message: `not valid YAML: ${error instanceof Error ? error.message : String(error)}${yamlHint(text)}` })
+    return { issues, lock }
+  }
+  if (!isRecord(raw)) {
+    issues.push({ level: "error", path: "", message: "goal.yaml must be a mapping" })
+    return { issues, lock }
+  }
+
+  const err = (path: string, message: string) => issues.push({ level: "error", path, message })
+  const warn = (path: string, message: string) => issues.push({ level: "warning", path, message })
+
+  if (raw.schema !== SCHEMA) err("schema", `schema must be "${SCHEMA}"`)
+  const id = str(raw.id)
+  if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(id)) err("id", "id must be a kebab-case slug (a-z, 0-9, hyphens)")
+  else if (options.slug && id !== options.slug) err("id", `id "${id}" must match its directory name "${options.slug}"`)
+  const title = str(raw.title)
+  if (!title) err("title", "title is required")
+  else if (title.length > 80) warn("title", "keep the title under 80 characters; it is shown in the sidebar")
+
+  const intent = isRecord(raw.intent) ? str(raw.intent.verbatim) : str(raw.intent)
+  if (!intent) err("intent.verbatim", "record the owner's own words verbatim; they stay the authoritative source")
+
+  const outcome = str(raw.outcome)
+  if (!outcome) err("outcome", "outcome is required: one end state that will be true when the goal is done")
+  else {
+    if (ACTIVITY.test(outcome)) warn("outcome", "reads as an activity; state the end state that becomes true instead")
+    const vague = vagueWords(outcome)
+    if (vague.length) warn("outcome", `vague without a number: ${vague.join(", ")}`)
+  }
+
+  const nonGoals = strings(raw.non_goals)
+  if (!nonGoals.length) err("non_goals", "list at least one non-goal so the loop does not fill the vacuum")
+
+  const criteria = parseCriteria(raw.criteria, "criteria", "C", issues)
+  if (!Array.isArray(raw.criteria) || !raw.criteria.length) err("criteria", "at least one criterion is required")
+  else if (!criteria.some((c) => c.essential)) err("criteria", "at least one criterion must be essential")
+  else if (!criteria.some((c) => c.essential && (HOST_KINDS as readonly string[]).includes(c.check.kind)))
+    warn("criteria", "no essential criterion is host-checkable; completion will rest on the verifier and the owner")
+  const invariants = parseCriteria(raw.invariants, "invariants", "I", issues)
+
+  const ids = new Set<string>()
+  for (const item of [...criteria, ...invariants]) {
+    if (ids.has(item.id)) err(item.id, `duplicate id ${item.id}`)
+    ids.add(item.id)
+  }
+
+  const assumptions: Assumption[] = (Array.isArray(raw.assumptions) ? raw.assumptions : []).flatMap((item: unknown, index: number) => {
+    if (!isRecord(item)) return []
+    const aid = str(item.id) || `A${index + 1}`
+    if (!/^A\d+$/.test(aid)) err(`assumptions[${index}].id`, "id must look like A1, A2, …")
+    const status = str(item.status) || "assumed"
+    if (!["assumed", "confirmed", "vetoed"].includes(status)) err(`assumptions[${index}].status`, "status must be assumed, confirmed or vetoed")
+    return [{ id: aid, text: str(item.text), ...(str(item.rationale) ? { rationale: str(item.rationale) } : {}), ...(typeof item.reversible === "boolean" ? { reversible: item.reversible } : {}), status: status as Assumption["status"] }]
+  })
+
+  const plan: Step[] = (Array.isArray(raw.plan) ? raw.plan : []).flatMap((item: unknown, index: number) => {
+    if (!isRecord(item)) return []
+    const sid = str(item.id)
+    if (!/^S\d+$/.test(sid)) err(`plan[${index}].id`, "id must look like S1, S2, …")
+    return [{ id: sid, title: str(item.title), proves: strings(item.proves), depends_on: strings(item.depends_on) }]
+  })
+  const stepIds = new Set(plan.map((s) => s.id))
+  for (const step of plan) {
+    for (const ref of step.proves) if (!criteria.some((c) => c.id === ref)) err(`plan.${step.id}.proves`, `unknown criterion ${ref}`)
+    for (const ref of step.depends_on) if (!stepIds.has(ref)) err(`plan.${step.id}.depends_on`, `unknown step ${ref}`)
+    if (!step.title) err(`plan.${step.id}.title`, "step title is required")
+  }
+  if (hasCycle(plan)) err("plan", "step dependencies form a cycle")
+
+  const budgetRaw = isRecord(raw.budget) ? raw.budget : {}
+  const budget: Budget = {}
+  if (budgetRaw.turns !== undefined) {
+    const turns = Number(budgetRaw.turns)
+    if (Number.isInteger(turns) && turns > 0) budget.turns = turns
+    else err("budget.turns", "turns must be a positive integer")
+  }
+  if (budgetRaw.wall !== undefined) {
+    const wallMs = parseDuration(budgetRaw.wall)
+    if (wallMs) budget.wallMs = wallMs
+    else err("budget.wall", 'wall must be a duration such as "90m" or "3h"')
+  }
+  if (budgetRaw.tokens !== undefined) {
+    const tokens = parseCount(budgetRaw.tokens)
+    if (tokens) budget.tokens = tokens
+    else err("budget.tokens", 'tokens must be a count such as 400k or "3M"')
+  }
+  if (budgetRaw.cost_usd !== undefined) {
+    const cost = Number(budgetRaw.cost_usd)
+    if (cost > 0) budget.cost_usd = cost
+    else err("budget.cost_usd", "cost_usd must be a positive number")
+  }
+
+  const autonomyRaw = isRecord(raw.autonomy) ? raw.autonomy : {}
+  const pick = <T extends string>(path: string, value: unknown, allowed: readonly T[], fallback: T): T => {
+    const v = str(value)
+    if (!v) return fallback
+    if ((allowed as readonly string[]).includes(v)) return v as T
+    err(path, `must be one of ${allowed.join(", ")}`)
+    return fallback
+  }
+  const autonomy: Autonomy = {
+    questions: pick("autonomy.questions", autonomyRaw.questions, ["defer", "allow"] as const, "defer"),
+    on_user_message: pick("autonomy.on_user_message", autonomyRaw.on_user_message, ["steer", "pause"] as const, "steer"),
+    on_interrupt: pick("autonomy.on_interrupt", autonomyRaw.on_interrupt, ["pause", "resume-on-message"] as const, "pause"),
+    amend: [],
+    on_stall: pick("autonomy.on_stall", autonomyRaw.on_stall, ["pause", "continue"] as const, "pause"),
+    ...(autonomyRaw.visit_new_projects === true ? { visit_new_projects: true } : {}),
+    ...(autonomyRaw.continue_past_budget === true ? { continue_past_budget: true } : {}),
+  }
+  if (autonomyRaw.amend !== undefined) {
+    if (!Array.isArray(autonomyRaw.amend)) err("autonomy.amend", `amend must be a list of ${AMEND_CLASSES.join(", ")}`)
+    else for (const value of autonomyRaw.amend) {
+      const v = str(value)
+      if (v && (AMEND_CLASSES as readonly string[]).includes(v)) { if (!autonomy.amend.includes(v as AmendClass)) autonomy.amend.push(v as AmendClass) }
+      else err("autonomy.amend", `unknown change class "${String(value)}"; allowed: ${AMEND_CLASSES.join(", ")}`)
+    }
+  }
+  const verificationRaw = isRecord(raw.verification) ? raw.verification : {}
+  const mode = pick<VerificationMode>("verification.mode", verificationRaw.mode, ["host", "host+verifier", "strict"] as const, "host+verifier")
+  const maxRejections = verificationRaw.max_rejections === undefined ? 3 : Number(verificationRaw.max_rejections)
+  if (!(Number.isInteger(maxRejections) && maxRejections >= 1 && maxRejections <= 10)) err("verification.max_rejections", "max_rejections must be an integer from 1 to 10")
+  const verifierRead = strings(verificationRaw.read)
+  if (verificationRaw.read !== undefined && !Array.isArray(verificationRaw.read)) err("verification.read", "read must be a list of folders the verifier may read")
+  for (const path of verifierRead) if (/[*?[\]{}]/.test(path)) err("verification.read", `"${path}" must be a plain folder or file path, not a glob`)
+  // T107: the contract may name the verifier child's model and effort. The
+  // strings are kept verbatim; the engine decides validity at run time and
+  // falls back with a recorded reason, so a bad value never blocks a launch.
+  const verifierModel = str(verificationRaw.model)
+  const verifierEffort = str(verificationRaw.effort)
+  // T100: an optional exact-run execution workspace (root-relative). A plain
+  // directory inside the project — no absolute path, no "..", no glob. The host
+  // additionally requires it to be a git work tree before the run starts.
+  const workspace = str(raw.workspace)
+  if (workspace && (workspace.startsWith("/") || workspace.split("/").includes("..") || /[*?[\]{}]/.test(workspace)))
+    err("workspace", `"${workspace}" must be a plain folder inside the project (no absolute path, ".." or glob)`)
+
+  const scopeRaw = isRecord(raw.scope) ? raw.scope : {}
+  const stopRaw = isRecord(raw.stop) ? raw.stop : {}
+  const executionRaw = isRecord(raw.execution) ? raw.execution : {}
+
+  if (issues.some((i) => i.level === "error")) return { issues, lock }
+  // T031: supersession pointer — "<slug>@<lock-prefix>", validated but only
+  // enforced at /goal start (existence, lock match, mid-flight admission).
+  const supersedes = str(raw.supersedes)
+  if (supersedes && !/^[a-z0-9][a-z0-9-]{0,63}@[0-9a-f]{8,64}$/.test(supersedes))
+    err("supersedes", "must look like \"<slug>@<lock-prefix>\" (the predecessor slug and the first bytes of its run lock)")
+  // T061: optional priority, low/medium/high; absent is valid (sorts last).
+  const rawPriority = str((raw as Record<string, unknown>).priority)
+  if (rawPriority && !PRIORITIES.includes(rawPriority as Priority))
+    err("priority", `priority must be one of low, medium, high (or omitted) — got "${rawPriority}"`)
+
+  // v0.5.0 — the optional CLEO linkage. `cleo.tasks` is a list whose entries are
+  // either a bare task id (link for reporting) or `{id, acs}` declaring which
+  // gate's evidence proves which AC alias. Absent ⇒ no CLEO behaviour change.
+  const cleoTasks: CleoTaskLink[] = []
+  if (raw.cleo !== undefined) {
+    if (!isRecord(raw.cleo)) err("cleo", "cleo must be a mapping with a tasks list")
+    else {
+      const tasksRaw = raw.cleo.tasks
+      if (tasksRaw !== undefined && !Array.isArray(tasksRaw)) err("cleo.tasks", "tasks must be a list of task ids")
+      const seen = new Set<string>()
+      for (const [index, entry] of (Array.isArray(tasksRaw) ? tasksRaw : []).entries()) {
+        const at = `cleo.tasks[${index}]`
+        const taskId = str(typeof entry === "string" ? entry : isRecord(entry) ? entry.id : "")
+        if (!/^[A-Z]{1,4}\d+$/.test(taskId)) { err(at, `task id must look like T123 (got "${taskId}")`); continue }
+        if (seen.has(taskId)) { err(at, `duplicate task ${taskId}`); continue }
+        seen.add(taskId)
+        const acsRaw = isRecord(entry) && isRecord((entry as Record<string, unknown>).acs) ? (entry as Record<string, unknown>).acs as Record<string, unknown> : undefined
+        const acs: Partial<Record<CleoGate, string[]>> = {}
+        if (acsRaw) {
+          // v0.5.1 - `acs` is legacy: the precise per-criterion `proves:` binding
+          // replaces it. Still read for compatibility, but warned as deprecated.
+          warn(`${at}.acs`, "cleo.tasks[].acs is deprecated - declare the binding on the criterion instead, e.g. proves: [\"T123#AC2\"]; the acs map is still read for compatibility")
+          for (const [gate, value] of Object.entries(acsRaw)) {
+            if (!(CLEO_GATES as readonly string[]).includes(gate)) { err(`${at}.acs.${gate}`, `unknown gate "${gate}"; allowed: ${CLEO_GATES.join(", ")}`); continue }
+            const aliases = strings(value).map((a) => a.toUpperCase())
+            if (!aliases.length) { err(`${at}.acs.${gate}`, "list at least one AC alias (AC1, AC2, …)"); continue }
+            for (const alias of aliases) if (!/^AC\d+$/.test(alias)) err(`${at}.acs.${gate}`, `AC alias must look like AC1 (got "${alias}")`)
+            acs[gate as CleoGate] = aliases
+          }
+        }
+        cleoTasks.push({ id: taskId, ...(Object.keys(acs).length ? { acs } : {}) })
+      }
+    }
+  }
+
+  const contract: Contract = {
+    schema: SCHEMA,
+    id,
+    title,
+    ...(rawPriority ? { priority: rawPriority as Priority } : {}),
+    ...(supersedes ? { supersedes } : {}),
+    intent: { verbatim: intent },
+    outcome,
+    ...(str(raw.why) ? { why: str(raw.why) } : {}),
+    scope: { in: strings(scopeRaw.in), out: strings(scopeRaw.out) },
+    non_goals: nonGoals,
+    constraints: strings(raw.constraints),
+    criteria,
+    invariants,
+    ...(workspace ? { workspace } : {}),
+  ...(cleoTasks.length ? { cleo: { tasks: cleoTasks } } : {}),
+    protect: strings(raw.protect),
+    assumptions,
+    plan,
+    budget,
+    stop: { ...(str(stopRaw.when) ? { when: str(stopRaw.when) } : {}), escalate_when: strings(stopRaw.escalate_when) },
+    autonomy,
+    verification: { mode, max_rejections: maxRejections, read: verifierRead, ...(verifierModel ? { model: verifierModel } : {}), ...(verifierEffort ? { effort: verifierEffort } : {}) },
+    execution: str(executionRaw.agent) ? { agent: str(executionRaw.agent) } : {},
+    meta: isRecord(raw.meta) ? raw.meta : {},
+  }
+  return { contract, issues, lock }
+}
+
+function hasCycle(plan: Step[]): boolean {
+  const deps = new Map(plan.map((s) => [s.id, s.depends_on]))
+  const state = new Map<string, 1 | 2>()
+  const visit = (id: string): boolean => {
+    if (state.get(id) === 2) return false
+    if (state.get(id) === 1) return true
+    state.set(id, 1)
+    for (const next of deps.get(id) ?? []) if (deps.has(next) && visit(next)) return true
+    state.set(id, 2)
+    return false
+  }
+  return plan.some((s) => visit(s.id))
+}
+
+/** Bun's YAML errors carry no position; point at the likeliest culprit. */
+function yamlHint(text: string): string {
+  const lines = text.split("\n")
+  for (let i = 0; i < lines.length; i++) {
+    const value = /^\s*(?:- )?[A-Za-z_][\w-]*:\s+([^'"\[{|>#].*)$/.exec(lines[i]!)?.[1]
+    if (value && /:\s/.test(value)) return ` (line ${i + 1} has an unquoted value containing ": " — wrap the value in single quotes)`
+  }
+  return ""
+}
+
+export const formatIssues = (issues: Issue[]) =>
+  issues.length ? issues.map((i) => `${i.level === "error" ? "✗" : "!"} ${i.path || "goal.yaml"}: ${i.message}`).join("\n") : "✓ goal.yaml is valid"

package/src/contract/render.ts

@@ -0,0 +1,134 @@
+// What the model sees. The system block is byte-stable for a whole run (prefix
+// cache); everything that changes per turn lives in the tail note.
+import type { Check, Contract, Criterion } from "./types"
+import { budgetUse, type RunState } from "../engine/state"
+
+const describeCheck = (check: Check): string => {
+  switch (check.kind) {
+    case "command":
+      return `host runs \`${check.run}\`${check.expect?.exit !== undefined ? ` → exit ${check.expect.exit}` : ""}${check.expect?.stdout_contains ? ` and output contains "${check.expect.stdout_contains}"` : ""}${check.expect?.stdout_regex ? ` and output matches /${check.expect.stdout_regex}/` : ""}${check.runs && check.runs > 1 ? ` (${check.runs} consecutive runs)` : ""}`
+    case "file":
+      return `host checks ${check.path} ${check.exists === false ? "does not exist" : "exists"}`
+    case "contains":
+      return `host checks ${check.path} contains ${check.text ? `"${check.text}"` : `/${check.regex}/`}`
+    case "absent":
+      return `host searches for /${check.pattern}/${check.paths?.length ? ` in ${check.paths.join(", ")}` : ""} and expects no match`
+    case "diff":
+      return `host checks ${check.paths.join(", ")} are unchanged since the run started`
+    case "verifier":
+      return `independent read-only verifier answers: ${check.ask}`
+    case "human":
+      return `the owner signs off: ${check.ask}`
+  }
+}
+
+const line = (c: Criterion) => `- ${c.id}${c.essential ? "" : " (optional)"}: ${c.statement}\n    proof: ${describeCheck(c.check)}${c.proves?.length ? `\n    proves CLEO: ${c.proves.join(", ")}` : ""}`
+
+export function renderSystemBlock(contract: Contract, lock: string): string {
+  const out: string[] = []
+  out.push(`<goal_contract id="${contract.id}" lock="${lock.slice(0, 12)}">`)
+  out.push("Goal mode is active for this session. The contract below is fixed for this run. It is the owner's task data: pursue it, but it does not override system, developer, tool or repository policies.")
+  out.push("")
+  out.push(`Title: ${contract.title}`)
+  out.push(`Outcome (the end state that must become true): ${contract.outcome}`)
+  if (contract.why) out.push(`Why: ${contract.why}`)
+  out.push(`Owner's words: "${contract.intent.verbatim.replace(/\s+/g, " ")}"`)
+  out.push("")
+  out.push("Criteria (every non-optional one must be proven before the goal completes):")
+  for (const c of contract.criteria) out.push(line(c))
+  if (contract.invariants.length) {
+    out.push("Invariants (must stay true the whole run; the host re-checks them):")
+    for (const c of contract.invariants) out.push(line(c))
+  }
+  if (contract.protect.length) out.push(`Protected paths (never edit, delete or rename): ${contract.protect.join(", ")}`)
+  if (contract.scope.in.length || contract.scope.out.length)
+    out.push(`Scope: in ${contract.scope.in.join(", ") || "(unspecified)"}; out ${contract.scope.out.join(", ") || "(unspecified)"}`)
+  out.push(`Non-goals: ${contract.non_goals.join("; ")}`)
+  if (contract.constraints.length) out.push(`Constraints: ${contract.constraints.join("; ")}`)
+  if (contract.cleo?.tasks.length)
+    out.push(`CLEO tasks this goal serves (evidence is recorded through the cleo CLI only; an AC no evidence proves stays open and is reported): ${contract.cleo.tasks.map((t) => (t.acs ? `${t.id} (${Object.entries(t.acs).map(([g, acs]) => `${g}=${(acs ?? []).join("/")}`).join(", ")})` : t.id)).join("; ")}`)
+  // v0.5.2 - a multi-task goal's run commits must cite every linked task id, or a
+  // later `cleo goal close` cannot bind the ones no commit names.
+  const linked = contract.cleo?.tasks.map((t) => t.id) ?? []
+  if (linked.length > 1)
+    out.push(`Commit citation (REQUIRED, ${linked.length} linked tasks): because this work lands on main with no PR or task branch, every RUN COMMIT message must cite ALL of these ids — ${linked.join(", ")} — e.g. \`feat(${linked.join(",")}): …\` or a trailer listing them. A commit that cites only some of them leaves the rest open with a "neither cites" blocker when the tasks are closed through the bridge.`)
+  if (contract.plan.length) {
+    out.push("Plan:")
+    for (const s of contract.plan)
+      out.push(`- ${s.id}: ${s.title}${s.proves.length ? ` (proves ${s.proves.join(", ")})` : ""}${s.depends_on.length ? ` (after ${s.depends_on.join(", ")})` : ""}`)
+  }
+  const assumed = contract.assumptions.filter((a) => a.status !== "vetoed")
+  if (assumed.length) out.push(`Assumptions (binding until the owner vetoes them): ${assumed.map((a) => `${a.id} ${a.text}`).join("; ")}`)
+  if (contract.stop.when) out.push(`Done when: ${contract.stop.when}`)
+  if (contract.stop.escalate_when.length) out.push(`Stop and call goal_block when: ${contract.stop.escalate_when.join("; ")}`)
+  out.push(`Contract file: .opencode/goals/${contract.id}/goal.yaml`)
+  out.push("</goal_contract>")
+  out.push("")
+  out.push("<goal_protocol>")
+  out.push("- Work from current evidence. Inspect files and run commands; earlier conversation helps you find things but proves nothing.")
+  out.push("- Keep the full outcome. Never narrow success to what is easy, what already exists, or what makes a check pass.")
+  out.push("- Every turn, take concrete actions with tools. A turn that only talks or restates status counts as no progress.")
+  out.push("- Record progress with goal_progress: the step you are on, one line on what changed, and the next action.")
+  out.push("- When you believe every criterion holds, call goal_claim with evidence per criterion, then end your turn. The host runs the checks itself and an independent verifier reviews the rest; you never grade your own work.")
+  out.push("- If a criterion is contradictory, impossible or unsafe as written, call goal_flag. Do not edit tests or checks to make them pass.")
+  out.push("- If you are blocked on something only the owner can provide, call goal_block with a short stable key. Hard, slow or uncertain work is not blocked.")
+  out.push("- To wait on an external process, call goal_wait with the seconds and the reason instead of polling in a loop.")
+  out.push("- Never edit the contract or anything under .opencode/goals/, and never touch protected paths.")
+  if (contract.autonomy.questions === "defer")
+    out.push("- Do not ask the owner questions during the run. Make the most reasonable reversible choice and note it in goal_progress as an assumption, or call goal_block if it truly needs an owner decision.")
+  out.push("</goal_protocol>")
+  return out.join("\n")
+}
+
+const pct = (used: number, limit: number) => `${Math.round((used / limit) * 100)}%`
+const fmtMs = (ms: number) => {
+  const m = Math.round(ms / 60000)
+  return m < 60 ? `${m}m` : `${Math.floor(m / 60)}h${m % 60 ? ` ${m % 60}m` : ""}`
+}
+export const fmtTokens = (n: number) => (n >= 1e6 ? `${(n / 1e6).toFixed(1)}M` : n >= 1e3 ? `${Math.round(n / 1e3)}k` : String(n))
+
+export function boardLine(state: RunState, contract: Contract): string {
+  return [...contract.criteria, ...contract.invariants]
+    .map((c) => {
+      const s = state.criteria[c.id]
+      const mark = s?.status === "pass" ? "✓" : s?.status === "fail" ? "✗" : s?.status === "claimed" ? "◐" : "·"
+      return `${mark} ${c.id}${s?.by ? ` (${s.by})` : ""}`
+    })
+    .join("  ")
+}
+
+export type TailKind = "kickoff" | "continue" | "verdict" | "recovery" | "wrapup" | "resume"
+
+export function renderTailNote(state: RunState, contract: Contract, kind: TailKind, now = Date.now()): string {
+  const out: string[] = []
+  const use = budgetUse(state, contract, now)
+  const budget = use.parts.length
+    ? use.parts.map((p) => `${p.name} ${p.name === "wall" ? `${fmtMs(p.used)}/${fmtMs(p.limit)}` : p.name === "tokens" ? `${fmtTokens(p.used)}/${fmtTokens(p.limit)}` : p.name === "cost" ? `$${p.used.toFixed(2)}/$${p.limit}` : `${p.used}/${p.limit}`}`).join(" · ")
+    : "no budget set"
+  out.push(`<goal_status turn="${state.turn}" run="${state.runId}">`)
+  const header: Record<TailKind, string> = {
+    kickoff: `Start the goal "${contract.title}". Read the contract above, inspect the current state of the repository, then begin with the first unfinished plan step. Take concrete actions now.`,
+    continue: "Continue the goal from its current state. Choose the next concrete action toward the outcome and take it with tools.",
+    verdict: "The host checked your completion claim and it did not pass. Fix what the verdict below names, then claim again with fresh evidence.",
+    recovery: "Your recent turns did not change anything the host can see. Do not restate status. Write down the 1-3 next concrete actions for yourself, then execute the first one with tools now. If you are truly blocked, call goal_block.",
+    wrapup: "The goal's budget is used up. Do not start new substantive work. Record where things stand with goal_progress (what is done, what remains, the exact next step), then end your turn.",
+    resume: "The owner resumed this goal. Re-read the contract and the current repository state, then continue from the first unfinished step.",
+  }
+  out.push(header[kind])
+  out.push(`Budget: ${budget}`)
+  if (use.ratio >= 0.8 && use.ratio < 1 && kind !== "wrapup") out.push(`Budget warning: ${pct(use.ratio, 1)} used. Finish the current step and move toward a claim or a clean handoff.`)
+  out.push(`Criteria: ${boardLine(state, contract)}`)
+  if (contract.plan.length) out.push(`Plan: ${contract.plan.map((s) => `${s.id} ${state.steps[s.id] ?? "pending"}`).join(" · ")}`)
+  if (state.progress) out.push(`Last progress (turn ${state.progress.turn}): ${state.progress.note}${state.progress.next ? ` → next: ${state.progress.next}` : ""}`)
+  if (state.verdict && !state.verdict.passed && (kind === "verdict" || state.verdict.turn >= state.turn - 1)) {
+    out.push(`HOST VERDICT (turn ${state.verdict.turn}):`)
+    for (const l of state.verdict.lines) out.push(`  ${l}`)
+  }
+  if (state.blocker && state.blocker.count > 0) out.push(`Reported blocker "${state.blocker.key}" ×${state.blocker.count}: ${state.blocker.reason}. Look for independent work that does not depend on it before reporting it again.`)
+  if (state.compacted) out.push(`Context was compacted. Before acting, re-read .opencode/goals/${contract.id}/goal.yaml and the recent entries of .opencode/goals/${contract.id}/ledger.jsonl; do not redo finished work.`)
+  out.push("</goal_status>")
+  return out.join("\n")
+}
+
+export const triggerText = (state: RunState, contract: Contract, kind: TailKind) =>
+  kind === "kickoff" ? `◎ goal started: ${contract.title}` : kind === "wrapup" ? `◎ goal budget reached — wrap up (turn ${state.turn})` : `↻ goal turn ${state.turn}${kind === "verdict" ? " — host verdict" : kind === "recovery" ? " — recovery" : kind === "resume" ? " — resumed" : ""}`