@cleocode/goal 0.0.0-stage → 0.9.2

package/src/engine/cleo-link.ts

@@ -0,0 +1,150 @@
+// T027 — optional first-class CLEO linkage. When the project carries a CLEO
+// workspace, the goal records the linkage THROUGH THE CLI ONLY (never by
+// reading .cleo/*.db); the project-context.json config file may be read as a
+// presence signal and fallback. No CLEO → the goal system behaves identically;
+// there is no hard dependency either way.
+import { existsSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+
+export type CleoFacts = { source: "cli" | "config"; projectId?: string; projectTypes: string[]; detectedAt?: string }
+
+export type Runner = (command: string, args: string[], timeoutMs?: number) => Promise<{ stdout: string; exit: number }>
+
+/**
+ * Detect CLEO linkage for a project root. Order: the `cleo` CLI (authoritative,
+ * spawn with a hard timeout), then .cleo/project-context.json (presence +
+ * config facts), then none. All failures degrade to undefined — never throw.
+ */
+export async function cleoFacts(projectRoot: string, run: Runner, timeoutMs = 2500): Promise<CleoFacts | undefined> {
+  const config = join(projectRoot, ".cleo", "project-context.json")
+  const hasConfig = existsSync(config)
+  if (!hasConfig && !existsSync(join(projectRoot, ".cleo"))) return undefined
+  try {
+    const { stdout, exit } = await run("cleo", ["doctor", "project-identity"], timeoutMs)
+    if (exit === 0 && stdout.trim()) {
+      const parsed = JSON.parse(stdout)
+      const data = parsed?.data ?? parsed
+      const projectId = typeof data?.projectId === "string" ? data.projectId : typeof parsed?.projectId === "string" ? parsed.projectId : undefined
+      return { source: "cli", projectId, projectTypes: [] }
+    }
+  } catch {
+    // CLI missing, too slow, or errored — degrade to the config signal
+  }
+  if (!hasConfig) return undefined
+  try {
+    const parsed = JSON.parse(readFileSync(config, "utf8"))
+    return { source: "config", projectTypes: Array.isArray(parsed?.projectTypes) ? parsed.projectTypes.map(String) : [], ...(parsed?.detectedAt ? { detectedAt: String(parsed.detectedAt) } : {}) }
+  } catch {
+    return { source: "config", projectTypes: [] }
+  }
+}
+
+/** The ledger payload recorded when a goal starts in a CLEO-linked project. */
+export function cleoLinkEvent(facts: CleoFacts | undefined) {
+  return facts ? { type: "cleo-linked" as const, via: facts.source, ...(facts.projectId ? { projectId: facts.projectId } : {}), ...(facts.projectTypes.length ? { projectTypes: facts.projectTypes } : {}) } : undefined
+}
+
+// v0.5.0 — the CLEO health surface. Three states, no more: the CLI is absent,
+// the CLI is present but this project is not initialized, or both are present.
+// OCG never installs or initializes anything by itself: it reports the state and
+// the EXACT command, and runs that command only when the owner asks for it.
+
+export type CleoHealthState = "cli-absent" | "uninitialized" | "initialized"
+
+/** Local string coercion (cleo-link.ts has no parser helpers). */
+const asText = (v: unknown): string => (typeof v === "string" ? v.trim() : "")
+
+export type CleoOffer = {
+  kind: "install" | "init"
+  /** The exact command OCG would run — only on an explicit owner choice. */
+  command: string
+  why: string
+}
+
+export type CleoHealth = {
+  state: CleoHealthState
+  cli: { present: boolean; version?: string }
+  workspace: { present: boolean; path: string }
+  projectId?: string
+  offer?: CleoOffer
+  /** One-line, state-accurate summary (never a claim that CLEO is usable). */
+  detail: string
+}
+
+/** The documented global install for the CLEO CLI (verified against @cleocode/cleo). */
+export const CLEO_INSTALL_COMMAND = "npm i -g @cleocode/cleo"
+/** The documented in-project initializer (verified: `cleo init --help`). */
+export const CLEO_INIT_COMMAND = "cleo init"
+
+/**
+ * Probe CLEO for a project root. `run` is invoked with `cleo --version` first to
+ * decide whether the CLI exists at all (a spawn rejection means absent), then with
+ * `cleo doctor project-identity` only when the workspace exists. Nothing here
+ * mutates the machine, and no failure throws.
+ */
+export async function cleoHealth(projectRoot: string, run: Runner, timeoutMs = 2500): Promise<CleoHealth> {
+  const cleoDir = join(projectRoot, ".cleo")
+  const workspace = { present: existsSync(cleoDir), path: cleoDir }
+  let present = false
+  let version: string | undefined
+  try {
+    const { stdout, exit } = await run("cleo", ["--version"], timeoutMs)
+    if (exit === 0) {
+      present = true
+      try {
+        const parsed = JSON.parse(stdout)
+        version = asText(parsed?.data?.version ?? parsed?.version) || undefined
+      } catch {
+        version = stdout.trim().split(/\s+/)[0] || undefined
+      }
+    }
+  } catch {
+    present = false // the spawn itself failed — no CLI on PATH
+  }
+
+  if (!present)
+    return {
+      state: "cli-absent",
+      cli: { present: false },
+      workspace,
+      offer: { kind: "install", command: CLEO_INSTALL_COMMAND, why: "the cleo CLI is not on PATH, so no task board is reachable from this project" },
+      detail: "CLEO CLI not found on PATH — goal tracking works exactly as before, with no CLEO integration",
+    }
+
+  if (!workspace.present)
+    return {
+      state: "uninitialized",
+      cli: { present: true, ...(version ? { version } : {}) },
+      workspace,
+      offer: { kind: "init", command: CLEO_INIT_COMMAND, why: "this project has no .cleo workspace, so a goal's work has no durable task board yet" },
+      detail: "CLEO CLI present, but this project has no .cleo workspace — a goal runs normally and records no task linkage",
+    }
+
+  let projectId: string | undefined
+  try {
+    const { stdout, exit } = await run("cleo", ["doctor", "project-identity"], timeoutMs)
+    if (exit === 0 && stdout.trim()) {
+      const parsed = JSON.parse(stdout)
+      const data = parsed?.data ?? parsed
+      projectId = asText(data?.trackedId ?? data?.projectId ?? parsed?.projectId) || undefined
+    }
+  } catch {
+    // CLI answered --version but not this probe: still initialized (the
+    // workspace exists); the id is simply unknown.
+  }
+  return {
+    state: "initialized",
+    cli: { present: true, ...(version ? { version } : {}) },
+    workspace,
+    ...(projectId ? { projectId } : {}),
+    detail: `CLEO CLI present and this project is initialized${projectId ? ` (project ${projectId})` : ""} — goals can name and complete CLEO tasks`,
+  }
+}
+
+/** Render a health probe as the owner/agent sees it. Pure; safe to unit-test. */
+export function cleoHealthReport(health: CleoHealth): string {
+  const version = health.cli.version ? ` (cleo ${health.cli.version})` : ""
+  const head = `◎ CLEO — ${health.detail}`
+  if (!health.offer) return [head, `Nothing to do: ${health.state === "initialized" ? "goals can link and complete CLEO tasks." : "no CLEO action is offered."}`].join("\n")
+  return [head, `On your explicit choice only (OCG never runs this silently): ${health.offer.command}`, `Why: ${health.offer.why}. Run /goal cleo ${health.offer.kind} to do it, or /goal cleo to re-check.`].join("\n")
+}

package/src/engine/continue-work.ts

@@ -0,0 +1,131 @@
+// v0.8.0 — turning a ready CLEO item into the next goal's contract.
+//
+// The owner's policy is "take the next ready CLEO item without asking". The
+// engine therefore has to author a contract it did not interview for. This file
+// does that from facts only: the task's own title, description and acceptance
+// statements. Each acceptance statement becomes one verifier criterion (the same
+// evidence standard the engine already uses for semantic checks); the task is
+// linked so the existing CLEO bridge can close it on evidence and reports every
+// AC it cannot prove. Nothing here invents a passing command.
+
+import type { Autonomy } from "../contract/types"
+import type { Runner } from "./cleo-link"
+
+export type CleoTask = {
+  id: string
+  title: string
+  description: string
+  acceptance: string[]
+}
+
+const parse = (stdout: string): any => {
+  try { return JSON.parse(stdout) } catch { return undefined }
+}
+
+/**
+ * The next ready LEAF item, from CLEO's own CLI. `cleo next` suggests by
+ * priority and dependency; `cleo show --full` supplies the type and acceptance
+ * text. A parent (epic/saga) is never started by itself — its acceptance is a
+ * rollup, not work — so parents are reported as skipped and the next leaf is
+ * tried. Any failure is "no ready work", never a guess.
+ */
+export type SkippedParent = { id: string; type: string; title: string }
+export type ReadyCleo = { task?: CleoTask; skipped: SkippedParent[] }
+
+export async function readyCleoTask(run: Runner, bin = "cleo"): Promise<ReadyCleo> {
+  const next = await run(bin, ["next", "-n", "5"])
+  if (next.exit !== 0) return { skipped: [] }
+  const suggestions = parse(next.stdout)?.data?.suggestions
+  if (!Array.isArray(suggestions)) return { skipped: [] }
+  const skipped: SkippedParent[] = []
+  for (const suggestion of suggestions) {
+    const id = typeof suggestion?.id === "string" ? suggestion.id : undefined
+    if (!id) continue
+    const show = await run(bin, ["show", id, "--full"])
+    if (show.exit !== 0) continue
+    const task = parse(show.stdout)?.data?.task
+    if (!task || ["done", "completed", "cancelled", "archived"].includes(String(task.status))) continue
+    const type = String(task.type ?? suggestion?.type ?? "")
+    if (type === "epic" || type === "saga") {
+      skipped.push({ id, type, title: String(task.title ?? suggestion?.title ?? id) })
+      continue
+    }
+    return {
+      task: {
+        id,
+        title: String(task.title ?? suggestion?.title ?? id),
+        description: String(task.description ?? ""),
+        acceptance: Array.isArray(task.acceptance) ? task.acceptance.map(String).filter(Boolean) : [],
+      },
+      skipped,
+    }
+  }
+  return { skipped }
+}
+
+const q = (value: string) => JSON.stringify(value)
+
+/** A slug that does not collide with a live, archived or draft goal. */
+export function continuationSlug(taskId: string, taken: ReadonlySet<string>): string {
+  const base = `cleo-${taskId.toLowerCase().replace(/[^a-z0-9]+/g, "-")}`
+  if (!taken.has(base)) return base
+  for (let n = 2; n < 100; n++) if (!taken.has(`${base}-${n}`)) return `${base}-${n}`
+  return `${base}-${Date.now()}`
+}
+
+/**
+ * The contract for the next goal. Deliberately boring: the linked task, one
+ * verifier criterion per acceptance statement (or the title when the task states
+ * none), the owner's autonomy policy, and no budget (budgets stay opt-in).
+ */
+export function continuationContractYaml(input: {
+  slug: string
+  task: CleoTask
+  sourceSlug: string
+  autonomy: Autonomy
+  now?: number
+}): string {
+  const { slug, task, sourceSlug, autonomy } = input
+  const statements = task.acceptance.length ? task.acceptance : [task.title]
+  const criteria = statements.map((statement, i) => [
+    `  - id: C${i + 1}`,
+    `    statement: ${q(`${task.id} acceptance ${i + 1}: ${statement}`)}`,
+    `    essential: true`,
+    `    check: {kind: verifier, ask: ${q(`Assess whether the work done for CLEO ${task.id} genuinely satisfies this acceptance criterion: ${statement} Quote the evidence from the repository.`)} }`,
+  ].join("\n"))
+  return [
+    "schema: goal/v1",
+    `id: ${slug}`,
+    `title: ${q(task.title)}`,
+    "intent:",
+    `  verbatim: ${q("Take the next ready CLEO item without asking.")}`,
+    `outcome: ${q(task.title)}`,
+    `why: ${q(`The owner's standing policy: after a goal completes, start the next ready CLEO item (${task.id}) by itself; this goal was started from that policy and the task's own acceptance.`)}`,
+    "scope:",
+    `  in: []`,
+    `  out: []`,
+    "non_goals:",
+    `  - ${q("Changing anything outside the linked CLEO task's scope")}`,
+    `  - ${q("Editing this goal's contract or its evidence")}`,
+    "criteria:",
+    ...criteria,
+    "cleo:",
+    "  tasks:",
+    `    - id: ${task.id}`,
+    "plan:",
+    `  - {id: S1, title: ${q(`Complete ${task.id} and prove its acceptance`)}}`,
+    "autonomy:",
+    `  questions: ${autonomy.questions}`,
+    `  on_user_message: ${autonomy.on_user_message}`,
+    `  on_interrupt: ${autonomy.on_interrupt}`,
+    `  amend: [${autonomy.amend.join(", ")}]`,
+    `  on_stall: ${autonomy.on_stall}`,
+    "verification: {mode: host+verifier, max_rejections: 3}",
+    "meta:",
+    `  created: ${q(new Date(input.now ?? Date.now()).toISOString())}`,
+    `  author: opencode-goal`,
+    `  source: continue-work@0.8.0`,
+    `  from: ${sourceSlug}`,
+    "",
+  ].join("\n")
+}

package/src/engine/decisions.ts

@@ -0,0 +1,44 @@
+import type { EngineMessage } from "../server/messages"
+import { OwnerReviewStore, type ReviewChoice, type ReviewRequest } from "./owner-reviews"
+
+export type DecisionKind = "needs_review" | "paused-after-verdict" | "blocked" | "budget_limited" | "amend-proposed" | "supersede-ack" | "complete" | "start-picker" | "owner-operation"
+export type DecisionTarget = { slug: string; runId?: string; sessionID?: string; lock: string; status: string }
+export type DecisionRequest = ReviewRequest & {
+  kind: DecisionKind
+  message: EngineMessage
+  target: DecisionTarget
+  /** Draft choices (start-picker) bind each candidate's bytes, too. */
+  candidates: Record<string, DecisionTarget>
+  extra: Record<string, unknown>
+}
+
+export function decisionChoices(request: DecisionRequest): ReviewChoice[] {
+  return request.message.choices.map((c, i) => ({ value: String(i), label: c.label, description: `${c.act ? "" : "Guidance only; no operation: "}${c.run}` }))
+}
+
+/**
+ * Should the native form be re-offered when a turn ends?
+ *
+ * An unanswered decision is not stale, but re-asking it on every turn end is
+ * noise (the owner sees the same question forever). The policy is: ask once
+ * per process; after that, silence until an explicit `goal_review` (which
+ * calls the form directly) or a reload (a new process, so `alreadyAsked` is
+ * false again). Dismissed reviews (`interrupted`) and open forms never re-ask.
+ */
+export function shouldReaskDecision(input: {
+  alreadyAsked: boolean
+  status: string
+  stale: boolean
+  formOpen: boolean
+}): { ask: boolean; reason?: "already-asked" | "interrupted" | "stale" | "form-open" } {
+  if (input.stale) return { ask: false, reason: "stale" }
+  if (input.formOpen) return { ask: false, reason: "form-open" }
+  if (input.status === "interrupted") return { ask: false, reason: "interrupted" }
+  if (input.alreadyAsked) return { ask: false, reason: "already-asked" }
+  return { ask: true }
+}
+
+export class DecisionStore extends OwnerReviewStore<DecisionRequest> {
+  constructor(file: string) { super(file, []) }
+  protected reviewChoices(request: DecisionRequest) { return decisionChoices(request) }
+}

package/src/engine/dogfood-record.ts

@@ -0,0 +1,278 @@
+// v0.5.1 - the exact-release real-model dogfood record and its readable export.
+//
+// T102: the five existing real-model drivers were five separate programs with no
+// shared record format and no single export, so a release's real-model proof
+// could not be read or re-checked independently. This module is the ONE record
+// shape and the ONE export both halves are built from.
+//
+// Honesty rule: a flow is labelled by what actually happened - `pass`, `fixture`,
+// `stale-cache`, `partial` or `timeout` - and never presented as a pass when it
+// was not one. `runDogfood` asserts the EXPORT is complete and honest (every flow
+// recorded, every required field present), never that every flow passed.
+
+import { createHash } from "node:crypto"
+
+export type FlowId = "interview" | "manager" | "lifecycle" | "completion" | "amendment"
+export const FLOWS: readonly FlowId[] = ["interview", "manager", "lifecycle", "completion", "amendment"]
+
+export type FlowLabel = "pass" | "fixture" | "stale-cache" | "partial" | "timeout"
+export const LABELS: readonly FlowLabel[] = ["pass", "fixture", "stale-cache", "partial", "timeout"]
+
+/** The exact release the flows were exercised against, by hash not by label. */
+export type ReleaseIdentity = { version: string; ref: string; sha: string; artifacts: Record<string, string> }
+/** The serving engine that actually ran the flows. */
+export type ServingIdentity = { pid: number; location: string; endpoint?: string }
+/** The selections the flows used - never inferred from a config file. */
+export type Selections = { model: string; agent: string }
+/** A bounded read coordinate: page + window, never an unbounded dump. */
+export type ReadCoordinate = { path: string; offset: number; limit: number }
+
+/** The raw owner interaction, preserved (bounded) alongside the verdict. */
+export type RawOutcome = {
+  ownerMessages: string[]
+  forms: Array<{ id: string; question: string; answer?: string }>
+  toolCalls: Array<{ name: string; result?: string }>
+  results: string[]
+}
+
+export type FlowRecord = {
+  flow: FlowId
+  release: ReleaseIdentity
+  serving: ServingIdentity
+  selections: Selections
+  requestIds: string[]
+  readCoordinates: ReadCoordinate[]
+  label: FlowLabel
+  labelReason: string
+  ms: number
+  startedAt: string
+  raw: RawOutcome
+}
+
+export type DogfoodExport = {
+  schema: "dogfood-export/v1"
+  release: ReleaseIdentity
+  serving: ServingIdentity
+  selections: Selections
+  generatedAt: string
+  flows: FlowRecord[]
+  labels: Record<FlowLabel, number>
+}
+
+/**
+ * The cache key that decides whether a stored per-flow record may be reused.
+ *
+ * It binds the SERVING ENGINE as well as the release: a record produced by a
+ * different pid, location or endpoint is NOT reusable, because the drivers
+ * themselves refuse to compare a live engine against a prior recorded elsewhere
+ * (the manager flow failed exactly that way with "QA serving PID changed").
+ */
+export const cacheKey = (release: ReleaseIdentity, serving: ServingIdentity): string =>
+  createHash("sha256").update(`${release.sha}\n${JSON.stringify(release.artifacts)}\n${serving.pid}\n${serving.location}\n${serving.endpoint ?? ""}`).digest("hex")
+
+/** Why a stored record cannot be reused, or undefined when it matches exactly. */
+export function cacheMismatch(stored: FlowRecord, release: ReleaseIdentity, serving: ServingIdentity): string | undefined {
+  if (stored.release.sha !== release.sha) return `the stored record was for release ${stored.release.sha}, not ${release.sha}`
+  if (JSON.stringify(stored.release.artifacts) !== JSON.stringify(release.artifacts)) return "the artifact hashes changed since the stored record"
+  if (stored.serving.pid !== serving.pid) return `the stored record was produced by serving pid ${stored.serving.pid}; this engine is ${serving.pid}`
+  if (stored.serving.location !== serving.location) return `the stored record was produced at ${stored.serving.location}; this engine serves ${serving.location}`
+  if ((stored.serving.endpoint ?? "") !== (serving.endpoint ?? "")) return `the stored record was produced at endpoint ${stored.serving.endpoint ?? "(none)"}; this engine is ${serving.endpoint ?? "(none)"}`
+  return undefined
+}
+
+/** Classify ONE flow from what actually happened. Order matters: the honest worst case wins. */
+export function classify(input: { exit: number; timedOut?: boolean; providerError?: boolean; fixture?: boolean; staleCache?: boolean; raw: RawOutcome; note?: string }): { label: FlowLabel; reason: string } {
+  // A captured cause is appended verbatim so a reader never has to guess what happened.
+  const suffix = input.note ? ` (${input.note.replace(/\s+/g, " ").slice(0, 200)})` : ""
+  if (input.timedOut) return { label: "timeout", reason: `the flow did not finish inside its bound; no verdict was produced${suffix}` }
+  if (input.providerError) return { label: "timeout", reason: `the provider failed before the flow produced a verdict${suffix}` }
+  // A stale record from another engine (or release) is the ROOT cause when it
+  // exists, so it is named BEFORE the generic incomplete-flow label.
+  if (input.staleCache) return { label: "stale-cache", reason: `a stored record could not be reused because the release, the artifact hashes or the serving engine changed${suffix}` }
+  if (input.exit !== 0) return { label: "partial", reason: `the flow did not complete (exit ${input.exit}) after producing some evidence${suffix}` }
+  if (input.fixture) return { label: "fixture", reason: `the flow ran against the scripted fixture provider, not a real model${suffix}` }
+  // A pass needs the raw interaction preserved, but not every KIND of it: a flow
+  // that legitimately asked no form has no forms to preserve. Only preserving
+  // NOTHING at all means the claim cannot be checked.
+  const total = input.raw.ownerMessages.length + input.raw.forms.length + input.raw.toolCalls.length + input.raw.results.length
+  if (!total) return { label: "partial", reason: `the flow exited 0 but preserved no raw interaction${suffix}` }
+  return { label: "pass", reason: `a real model completed the flow and its raw interaction was preserved (${input.raw.ownerMessages.length} owner messages, ${input.raw.forms.length} forms, ${input.raw.toolCalls.length} tool calls)${suffix}` }
+}
+
+export const summarize = (records: FlowRecord[]): Record<FlowLabel, number> => {
+  const out = Object.fromEntries(LABELS.map((l) => [l, 0])) as Record<FlowLabel, number>
+  for (const r of records) out[r.label] += 1
+  return out
+}
+
+/** Every field C3 requires of every flow record. Returns the missing ones. */
+export function validateExport(exp: DogfoodExport): string[] {
+  const problems: string[] = []
+  if (exp.schema !== "dogfood-export/v1") problems.push(`schema is ${String(exp.schema)}`)
+  if (!exp.release.sha) problems.push("release.sha is empty")
+  if (!exp.release.version) problems.push("release.version is empty")
+  if (!Object.keys(exp.release.artifacts).length) problems.push("release.artifacts is empty")
+  if (!exp.serving.pid) problems.push("serving.pid is empty")
+  if (!exp.serving.location) problems.push("serving.location is empty")
+  if (!exp.selections.model) problems.push("selections.model is empty")
+  if (!exp.selections.agent) problems.push("selections.agent is empty")
+  const missing = FLOWS.filter((f) => !exp.flows.some((r) => r.flow === f))
+  for (const f of missing) problems.push(`flow ${f} has no record`)
+  for (const r of exp.flows) {
+    if (!r.labelReason) problems.push(`flow ${r.flow} has no label reason`)
+    if (!LABELS.includes(r.label)) problems.push(`flow ${r.flow} has an unknown label ${String(r.label)}`)
+    if (r.release.sha !== exp.release.sha) problems.push(`flow ${r.flow} was recorded against ${r.release.sha}, not ${exp.release.sha}`)
+    // A PASS must be backed by evidence. A recorded failure (fixture, stale-cache,
+    // partial, timeout) need not have produced ids or coordinates - its reason says so.
+    if (r.label === "pass") {
+      if (!r.requestIds.length) problems.push(`flow ${r.flow} is labelled pass but has no request id`)
+      if (!r.readCoordinates.length) problems.push(`flow ${r.flow} is labelled pass but has no bounded read coordinate`)
+    }
+  }
+  return problems
+}
+
+const YES_NO = (b: boolean) => (b ? "yes" : "NO")
+
+/** The committed, human-readable half. Deterministic given the export. */
+export function renderMarkdown(exp: DogfoodExport): string {
+  const rows = exp.flows.map((r) => `| ${r.flow} | ${r.label} | ${r.selections.model} | ${r.selections.agent} | ${r.requestIds[0] ?? "-"} | ${r.readCoordinates.length} | ${r.ms}ms |`)
+  const out: string[] = []
+  out.push(`# Real-model dogfood - ${exp.release.ref}`)
+  out.push("")
+  out.push(`Generated ${exp.generatedAt} by \`scripts/real-model-dogfood.ts\`. This is release evidence, not a claim of broad coverage: read the label and the reason for every flow.`)
+  out.push("")
+  out.push(`**Release:** ${exp.release.ref} (\`${exp.release.sha}\`) - version ${exp.release.version}`)
+  out.push(`**Serving engine:** pid ${exp.serving.pid} at \`${exp.serving.location}\`${exp.serving.endpoint ? ` (${exp.serving.endpoint})` : ""}`)
+  out.push(`**Selections:** model \`${exp.selections.model}\`, agent \`${exp.selections.agent}\``)
+  out.push(`**Labels:** ${LABELS.map((l) => `${l} ${exp.labels[l] ?? 0}`).join(" · ")}`)
+  out.push("")
+  out.push("| flow | label | model | agent | first request id | read coords | duration |")
+  out.push("| --- | --- | --- | --- | --- | --- | --- |")
+  out.push(...rows)
+  out.push("")
+  out.push("## Artifact hashes (the exact bytes the flows ran against)")
+  out.push("")
+  for (const [path, hash] of Object.entries(exp.release.artifacts).sort()) out.push(`- \`${path}\` \`${hash}\``)
+  out.push("")
+  out.push("## Per-flow detail")
+  for (const r of exp.flows) {
+    out.push("")
+    out.push(`### ${r.flow} - ${r.label}`)
+    out.push(`- Why this label: ${r.labelReason}`)
+    out.push(`- Release SHA: \`${r.release.sha}\`; serving engine pid ${r.serving.pid} at \`${r.serving.location}\`${r.serving.endpoint ? ` (${r.serving.endpoint})` : " (no endpoint recorded)"}`)
+    out.push(`- Model \`${r.selections.model}\`; agent \`${r.selections.agent}\`; duration ${r.ms}ms; started ${r.startedAt}`)
+    out.push(`- Request ids: ${r.requestIds.length ? r.requestIds.map((id) => `\`${id}\``).join(", ") : "(none recorded)"}`)
+    out.push(`- Bounded read coordinates: ${r.readCoordinates.length ? r.readCoordinates.map((c) => `\`${c.path}@${c.offset}+${c.limit}\``).join(", ") : "(none recorded)"}`)
+    out.push(`- Raw owner messages: ${r.raw.ownerMessages.length} · forms: ${r.raw.forms.length} · tool calls: ${r.raw.toolCalls.length}`)
+    for (const m of r.raw.ownerMessages.slice(0, 3)) out.push(`  - owner: ${m.replace(/\s+/g, " ").slice(0, 200)}`)
+    for (const f of r.raw.forms.slice(0, 3)) out.push(`  - form ${f.id}: ${f.question.replace(/\s+/g, " ").slice(0, 140)}${f.answer ? ` -> ${f.answer.slice(0, 80)}` : " (unanswered)"}`)
+    for (const t of r.raw.toolCalls.slice(0, 5)) out.push(`  - tool ${t.name}${t.result ? ` -> ${t.result.replace(/\s+/g, " ").slice(0, 120)}` : ""}`)
+  }
+  out.push("")
+  out.push("## Which serving engine each flow ran against")
+  out.push("")
+  for (const r of exp.flows) out.push(`- ${r.flow}: ran against serving engine pid ${r.serving.pid} at location \`${r.serving.location}\` with endpoint ${r.serving.endpoint ?? "(none recorded)"}`)
+  out.push("")
+  out.push("## How each label is assigned")
+  out.push("")
+  out.push("A flow is labelled by what actually happened, never optimistically:")
+  out.push("- `pass` - a real model completed the flow AND its raw interaction was preserved.")
+  out.push("- `fixture` - the flow ran against the scripted fixture provider, not a real model.")
+  out.push("- `stale-cache` - a stored record could not be reused because the release, the artifact hashes or the serving engine changed.")
+  out.push("- `partial` - the flow exited non-zero, with its cause recorded, or preserved no raw interaction at all.")
+  out.push("- `timeout` - the flow or its provider failed before any verdict was produced.")
+  out.push("")
+  out.push("A stored record is reused ONLY when it is a verified pass whose release SHA, artifact hashes AND serving engine (pid, location, endpoint) all still match. A record from any other engine is never reused.")
+  out.push("")
+  out.push("## What this export does NOT claim")
+  out.push("- A `pass` means the flow completed against a real model and its raw interaction was preserved; it is not a statement about flows this release did not run.")
+  out.push("- `fixture`, `stale-cache`, `partial` and `timeout` are failures to produce a verdict, recorded as such. They are never counted as passes.")
+  out.push(`- Raw credentials and full provider payloads are never included (${YES_NO(true)} - the export carries hashes, ids and bounded coordinates only).`)
+  return out.join("\n")
+}
+
+/** Where both halves live. `docs/research/real-model-dogfood/<version>.md|.json` + `.opencode/dogfood/<sha>/`. */
+export const exportPaths = (version: string, sha: string) => ({
+  summary: `docs/research/real-model-dogfood/${version}.md`,
+  index: `docs/research/real-model-dogfood/${version}.json`,
+  rawDir: `.opencode/dogfood/${sha.slice(0, 12)}`,
+})
+
+export type FlowRun = { exit: number; timedOut?: boolean; providerError?: boolean; fixture?: boolean; staleCache?: boolean; ms: number; requestIds: string[]; readCoordinates: ReadCoordinate[]; raw: RawOutcome; note?: string }
+
+export type DogfoodDeps = {
+  identity: () => Promise<{ release: ReleaseIdentity; serving: ServingIdentity; selections: Selections }>
+  runFlow: (flow: FlowId) => Promise<FlowRun>
+  store: { read: (flow: FlowId) => Promise<FlowRecord | undefined>; write: (record: FlowRecord) => Promise<void> }
+  emit: { summary: (markdown: string) => Promise<void>; index: (exp: DogfoodExport) => Promise<void> }
+  /**
+   * Applied to EVERY record (reused or fresh) before it enters the export. Used to
+   * make the cited read coordinates project-local, so an independent read-only
+   * verifier can actually open them. Must not change a verdict.
+   */
+  relocate?: (record: FlowRecord) => Promise<FlowRecord>
+  force?: boolean
+  now?: () => number
+}
+
+export type DogfoodResult = { export: DogfoodExport; results: Array<{ flow: FlowId; label: FlowLabel; reused: boolean }> }
+
+/**
+ * Run (or reuse) every flow for the current release and produce the export.
+ * A stored record whose cache key matches the current release + artifact hashes
+ * is REUSED rather than re-run, so a start rehearsal and the completing check do
+ * not pay for five real-model flows twice; `force` re-runs regardless.
+ */
+export async function runDogfood(deps: DogfoodDeps): Promise<DogfoodResult> {
+  const { release, serving, selections } = await deps.identity()
+  const key = cacheKey(release, serving)
+  const results: DogfoodResult["results"] = []
+  const records: FlowRecord[] = []
+  for (const flow of FLOWS) {
+    const stored = await deps.store.read(flow)
+    const stale = stored ? cacheMismatch(stored, release, serving) : undefined
+    // Only a verified PASS from THIS engine is reusable. A recorded failure is
+    // never cached as if it were an answer, and a record from another engine (or
+    // another release/artifact set) is never reused at all.
+    const reusable = stored && !deps.force && stored.label === "pass" && !stale
+    if (reusable) {
+      const record = deps.relocate ? await deps.relocate(stored) : stored
+      records.push(record)
+      results.push({ flow, label: record.label, reused: true })
+      continue
+    }
+    const run = await deps.runFlow(flow)
+    // If a stale record existed and the fresh attempt produced no verdict, the
+    // honest label is `stale-cache` naming the mismatch - not a silent partial.
+    const { label, reason } = classify(stale && (run.exit !== 0 || run.timedOut || run.providerError) ? { ...run, staleCache: true, note: stale } : run)
+    const record: FlowRecord = {
+      flow,
+      release,
+      serving,
+      selections,
+      requestIds: run.requestIds,
+      readCoordinates: run.readCoordinates,
+      label,
+      labelReason: reason,
+      ms: run.ms,
+      startedAt: new Date((deps.now ?? Date.now)()).toISOString(),
+      raw: run.raw,
+    }
+    await deps.store.write(record)
+    records.push(deps.relocate ? await deps.relocate(record) : record)
+    results.push({ flow, label, reused: false })
+  }
+  const exp: DogfoodExport = {
+    schema: "dogfood-export/v1",
+    release,
+    serving,
+    selections,
+    generatedAt: new Date((deps.now ?? Date.now)()).toISOString(),
+    flows: records,
+    labels: summarize(records),
+  }
+  await deps.emit.summary(renderMarkdown(exp))
+  await deps.emit.index(exp)
+  return { export: exp, results }
+}