gateproof 0.2.4 → 0.5.0

package/README.md

@@ -1,222 +1,1516 @@
-# gateproof
+# Gateproof
 
-Software is built in reverse. You know what you want before you know how to get there. TDD proved the idea: write the test first, then make it pass. Gateproof takes the next step.
+Gateproof runs the proof, sends in the worker, and keeps going until the live claim is true.
 
-Write stories. Attach gates. Let agents iterate until reality matches intent.
+## Tutorial
 
-A **gate** observes real evidence (logs, telemetry), acts (browser, shell, deploy), and asserts outcomes. A **story** is a gate with a name and a place in a plan. A **prd.ts** is a list of stories in dependency order. The agent's only job is to make the next failing gate pass.
+Goal: Start with one tiny gate that is small on purpose and complete on purpose.
 
-## The thesis
+### examples/hello-world/plan.ts
 
-Plans are solid. Implementation is liquid.
+```ts
+import { Effect } from "effect";
+import {
+  Act,
+  Assert,
+  Gate,
+  Plan,
+  createHttpObserveResource,
+  type ScopeFile,
+} from "../../src/index";
+import { HELLO_WORLD_PORT } from "./server";
 
-Any codebase can be scoped down to stories and a `prd.ts`. Multiple agents can work the same plan, falling through the same checkpoints. Once a gate passes, previous work can't break -- the gate proves it. The skill shifts from writing code to defining the right guardrails.
+const baseUrl = `http://127.0.0.1:${HELLO_WORLD_PORT}`;
 
-Gates are checkpoints that keep agents safe. They don't decide intent. They verify reality.
+const scope = {
+  spec: {
+    title: "Hello World",
+    tutorial: {
+      goal: "Prove one tiny thing.",
+      outcome: "The run only passes when the live response says hello world.",
+    },
+    howTo: {
+      task: "Run one complete gate from one file.",
+      done: "The endpoint returns 200 and the body contains hello world.",
+    },
+    explanation: {
+      summary: "Even the smallest run is still a real proof loop.",
+    },
+  },
+  plan: Plan.define({
+    goals: [
+      {
+        id: "hello-world",
+        title: "GET / returns hello world",
+        gate: Gate.define({
+          observe: createHttpObserveResource({
+            url: `${baseUrl}/`,
+          }),
+          act: [Act.exec(`curl -sf ${baseUrl}/`)],
+          assert: [
+            Assert.httpResponse({ status: 200 }),
+            Assert.responseBodyIncludes("hello world"),
+            Assert.noErrors(),
+          ],
+        }),
+      },
+    ],
+    loop: {
+      maxIterations: 1,
+      stopOnFailure: true,
+    },
+  }),
+} satisfies ScopeFile;
 
-## Why this works
+export default scope;
 
-Formal verification research established that the relationship between a specification and its implementation — called **refinement** — is itself a testable property. You don't need a theorem prover to get value from this idea. You can test refinement cheaply by running the system and checking that its behavior satisfies the spec.
+if (import.meta.main) {
+  const result = await Effect.runPromise(Plan.runLoop(scope.plan));
+  console.log(JSON.stringify(result, null, 2));
 
-Gateproof distills this into three primitives:
+  if (result.status !== "pass") {
+    process.exitCode = 1;
+  }
+}
+```
 
-1. **Observe** — collect real evidence (logs, telemetry) from a running system
-2. **Act** — trigger real behavior (browser navigation, shell commands, deploys)
-3. **Assert** — check that the evidence satisfies the specification
+Outcome: The loop only passes when the live response says hello world.
 
-Each gate is a refinement check: does the running system's behavior refine what the story claims? The PRD orders these checks by dependency, so failures localize to the first broken obligation.
+## First Case Study: Cinder
 
-This is a deliberate simplification. We trade random input generation and exhaustive coverage for something an engineer can write in minutes and an agent can iterate against in a loop. The gate is the contract. The loop is the proof search.
+### alchemy.run.ts
 
-> Lineage: the *observe → act → assert* pattern draws on property-based testing ideas from [Chen, Rizkallah et al. — "Property-Based Testing: Climbing the Stairway to Verification" (SLE 2022)](https://doi.org/10.1145/3567512.3567520), which demonstrated that refinement properties can serve as a practical, incremental path toward verified systems.
+```ts
+import alchemy from "alchemy";
+import { Buffer } from "node:buffer";
+import { mkdir } from "node:fs/promises";
+import { R2RestStateStore } from "alchemy/state";
+import {
+  CloudflareApiError,
+  DurableObjectNamespace,
+  KVNamespace,
+  R2Bucket,
+  Worker,
+  createBucket,
+  createCloudflareApi,
+  getBucket,
+} from "alchemy/cloudflare";
 
-## Install
+function requireEnv(name: string): string {
+  const value = process.env[name]?.trim();
 
-```bash
-bun add gateproof
-```
+  if (!value) {
+    throw new Error(`${name} is required for cinder provisioning`);
+  }
 
-## Minimal gate
+  return value;
+}
 
-```ts
-import { Gate, Act, Assert, createHttpObserveResource } from "gateproof";
+const githubPat = requireEnv("GITHUB_PAT");
+const webhookSecret = requireEnv("GITHUB_WEBHOOK_SECRET");
+const internalToken = requireEnv("CINDER_INTERNAL_TOKEN");
+const fixtureRepo = process.env.CINDER_FIXTURE_REPO?.trim() || "acoyfellow/cinder-prd-test";
+const fixtureBranch = process.env.CINDER_FIXTURE_BRANCH?.trim() || "main";
+const fixtureWorkflow =
+  process.env.CINDER_FIXTURE_WORKFLOW?.trim() || "cinder-proof.yml";
+const githubApiBase = "https://api.github.com";
+const stateBucketName = process.env.CINDER_STATE_BUCKET?.trim();
+const stateBucketRegion = process.env.CINDER_STATE_REGION?.trim() || "auto";
 
-const result = await Gate.run({
-  name: "post-deploy",
-  observe: createHttpObserveResource({
-    url: "https://api.example.com/health",
-  }),
-  act: [Act.wait(500)],
-  assert: [Assert.noErrors()],
-  stop: { maxMs: 10_000 },
-});
+const fixtureCargoToml = `[package]
+name = "cinder-proof"
+version = "0.1.0"
+edition = "2021"
 
-if (result.status !== "success") process.exit(1);
-```
+[dependencies]
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+`;
 
-## Stories + PRD
+const fixtureCargoLock = `# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
 
-```ts
-import { definePrd, runPrd } from "gateproof/prd";
+[[package]]
+name = "cinder-proof"
+version = "0.1.0"
+dependencies = [
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "itoa"
+version = "1.0.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92ecc6618181def0457392ccd0ee51198e065e016d1d527a7ac1b6dc7c1f09d2"
+
+[[package]]
+name = "memchr"
+version = "2.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.44"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "21b2ebcf727b7760c461f091f9f0f539b77b8e87f2fd88131e7f1b433b3cece4"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "serde"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.149"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "83fc039473c5595ace860d8c4fafa220ff474b3fc6bfdb4293327f1a37e94d86"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.117"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "zmij"
+version = "1.0.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"
+`;
+
+const fixtureMainRs = `use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize)]
+struct ProofMessage {
+    ok: bool,
+    source: &'static str,
+}
+
+fn main() {
+    let message = ProofMessage {
+        ok: true,
+        source: "cinder-proof",
+    };
+
+    println!("{}", serde_json::to_string(&message).unwrap());
+}
+`;
+
+const fixtureWorkflowContents = `name: cinder-proof
+on:
+  workflow_dispatch:
+jobs:
+  cargo-build:
+    runs-on: [self-hosted, cinder]
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build fixture
+        run: cargo build --locked
+      - name: Run fixture
+        run: cargo run --locked
+`;
+
+function parseFixtureRepository(repoRef: string) {
+  const [owner, name, ...extra] = repoRef.split("/");
+
+  if (!owner || !name || extra.length > 0) {
+    throw new Error(
+      `CINDER_FIXTURE_REPO must be "owner/name" but received "${repoRef}"`,
+    );
+  }
+
+  return { owner, name };
+}
+
+async function githubRequest(
+  path: string,
+  init: RequestInit = {},
+  okStatuses: number[] = [200],
+) {
+  const response = await fetch(`${githubApiBase}${path}`, {
+    ...init,
+    headers: {
+      Accept: "application/vnd.github+json",
+      Authorization: `Bearer ${githubPat}`,
+      "User-Agent": "cinder-provisioner",
+      "X-GitHub-Api-Version": "2022-11-28",
+      ...(init.headers ?? {}),
+    },
+  });
 
-const prd = definePrd({
-  stories: [
+  if (okStatuses.includes(response.status)) {
+    return response;
+  }
+
+  const body = await response.text();
+  throw new Error(
+    `GitHub API ${init.method ?? "GET"} ${path} failed with ${response.status}: ${body}`,
+  );
+}
+
+async function ensureFixtureRepository() {
+  const { owner, name } = parseFixtureRepository(fixtureRepo);
+  const existing = await githubRequest(`/repos/${owner}/${name}`, {}, [200, 404]);
+
+  if (existing.status === 200) {
+    return (await existing.json()) as { default_branch: string; full_name: string };
+  }
+
+  const viewer = (await (
+    await githubRequest("/user")
+  ).json()) as { login: string };
+
+  if (viewer.login !== owner) {
+    throw new Error(
+      `Fixture repo ${fixtureRepo} is missing and cannot be auto-created because PAT owner "${viewer.login}" does not match "${owner}"`,
+    );
+  }
+
+  const created = await githubRequest(
+    "/user/repos",
     {
-      id: "user-signup",
-      title: "User can sign up with email",
-      gateFile: "./gates/signup.gate.ts",
+      method: "POST",
+      body: JSON.stringify({
+        name,
+        description: "Canonical GitHub proof fixture for Cinder",
+        auto_init: true,
+        private: false,
+      }),
     },
+    [201],
+  );
+
+  return (await created.json()) as { default_branch: string; full_name: string };
+}
+
+async function ensureFixtureBranch(repo: { default_branch: string }) {
+  if (fixtureBranch === repo.default_branch) {
+    return;
+  }
+
+  const { owner, name } = parseFixtureRepository(fixtureRepo);
+  const branchResponse = await githubRequest(
+    `/repos/${owner}/${name}/git/ref/heads/${encodeURIComponent(fixtureBranch)}`,
+    {},
+    [200, 404],
+  );
+
+  if (branchResponse.status === 200) {
+    return;
+  }
+
+  const defaultBranchRef = (await (
+    await githubRequest(
+      `/repos/${owner}/${name}/git/ref/heads/${encodeURIComponent(repo.default_branch)}`,
+    )
+  ).json()) as { object: { sha: string } };
+
+  await githubRequest(
+    `/repos/${owner}/${name}/git/refs`,
     {
-      id: "email-verification",
-      title: "User receives verification email",
-      gateFile: "./gates/verify.gate.ts",
-      dependsOn: ["user-signup"],
+      method: "POST",
+      body: JSON.stringify({
+        ref: `refs/heads/${fixtureBranch}`,
+        sha: defaultBranchRef.object.sha,
+      }),
     },
-  ] as const,
-});
+    [201],
+  );
+}
 
-const result = await runPrd(prd);
-if (!result.success) process.exit(1);
-```
+async function upsertFixtureFile(path: string, content: string, message: string) {
+  const { owner, name } = parseFixtureRepository(fixtureRepo);
+  const encodedPath = path
+    .split("/")
+    .map((segment) => encodeURIComponent(segment))
+    .join("/");
+  const existing = await githubRequest(
+    `/repos/${owner}/${name}/contents/${encodedPath}?ref=${encodeURIComponent(fixtureBranch)}`,
+    {},
+    [200, 404],
+  );
+  const sha =
+    existing.status === 200
+      ? ((await existing.json()) as { sha: string }).sha
+      : undefined;
 
-## Assertions
+  await githubRequest(
+    `/repos/${owner}/${name}/contents/${encodedPath}`,
+    {
+      method: "PUT",
+      body: JSON.stringify({
+        message,
+        branch: fixtureBranch,
+        content: Buffer.from(content, "utf8").toString("base64"),
+        sha,
+      }),
+    },
+    [200, 201],
+  );
+}
 
-`Assert.noErrors()`, `Assert.hasAction(name)`, `Assert.hasStage(name)`, `Assert.custom(name, fn)`, `Assert.authority(policy)`.
+async function upsertFixtureWebhook(webhookUrl: string) {
+  const { owner, name } = parseFixtureRepository(fixtureRepo);
+  const hooks = (await (
+    await githubRequest(`/repos/${owner}/${name}/hooks`)
+  ).json()) as Array<{ id: number; name: string; config?: { url?: string } }>;
+  const existing = hooks.find(
+    (hook) => hook.name === "web" && hook.config?.url === webhookUrl,
+  );
+  const body = JSON.stringify({
+    active: true,
+    events: ["workflow_job"],
+    config: {
+      url: webhookUrl,
+      content_type: "json",
+      insecure_ssl: "0",
+      secret: webhookSecret,
+    },
+  });
 
-```ts
-import { Gate, Act, Assert } from "gateproof";
-import { CloudflareProvider } from "gateproof/cloudflare";
+  if (existing) {
+    await githubRequest(
+      `/repos/${owner}/${name}/hooks/${existing.id}`,
+      {
+        method: "PATCH",
+        body,
+      },
+      [200],
+    );
+    return;
+  }
 
-const provider = CloudflareProvider({
-  accountId: process.env.CLOUDFLARE_ACCOUNT_ID!,
-  apiToken: process.env.CLOUDFLARE_API_TOKEN!,
+  await githubRequest(
+    `/repos/${owner}/${name}/hooks`,
+    {
+      method: "POST",
+      body,
+    },
+    [201],
+  );
+}
+
+async function syncFixtureRepository(webhookUrl: string) {
+  const repo = await ensureFixtureRepository();
+  await ensureFixtureBranch(repo);
+
+  await upsertFixtureFile("Cargo.toml", fixtureCargoToml, "chore: sync cinder fixture Cargo.toml");
+  await upsertFixtureFile("Cargo.lock", fixtureCargoLock, "chore: sync cinder fixture Cargo.lock");
+  await upsertFixtureFile("src/main.rs", fixtureMainRs, "chore: sync cinder fixture main.rs");
+  await upsertFixtureFile(
+    `.github/workflows/${fixtureWorkflow}`,
+    fixtureWorkflowContents,
+    "chore: sync cinder fixture workflow",
+  );
+  await upsertFixtureWebhook(webhookUrl);
+}
+
+async function ensureStateBucket(bucketName: string, locationHint: string) {
+  const accountId = requireEnv("CLOUDFLARE_ACCOUNT_ID");
+  const apiToken = requireEnv("CLOUDFLARE_API_TOKEN");
+  const api = await createCloudflareApi({ accountId, apiToken } as any);
+
+  try {
+    await getBucket(api, bucketName);
+    return { accountId, apiToken };
+  } catch (error) {
+    if (!(error instanceof CloudflareApiError) || error.status !== 404) {
+      throw error;
+    }
+  }
+
+  await createBucket(api, bucketName, { locationHint });
+  return { accountId, apiToken };
+}
+
+const stateStoreCredentials = stateBucketName
+  ? await ensureStateBucket(stateBucketName, stateBucketRegion)
+  : null;
+
+export const app = await alchemy("cinder", {
+  stage: process.env.CINDER_STAGE ?? "production",
+  ...(stateBucketName && stateStoreCredentials
+    ? {
+        stateStore: (scope) =>
+          new R2RestStateStore(scope, {
+            accountId: stateStoreCredentials.accountId,
+            apiToken: stateStoreCredentials.apiToken,
+            bucketName: stateBucketName,
+          } as any),
+      }
+    : {}),
 });
 
-const result = await Gate.run({
-  name: "checkout-flow",
-  observe: provider.observe({ backend: "analytics", dataset: "worker_logs" }),
-  act: [Act.browser({ url: "https://app.example.com/checkout" })],
-  assert: [
-    Assert.noErrors(),
-    Assert.hasAction("checkout_started"),
-    Assert.custom("has-total", (logs) => logs.some(l => (l as { data?: { total?: number } }).data?.total > 0)),
-  ],
-  stop: { maxMs: 15_000 },
+export const cacheBucket = await R2Bucket("cinder-cache", {
+  empty: false,
 });
-if (result.status !== "success") process.exit(1);
-```
 
-## Agent gates
+export const runnerState = await KVNamespace("cinder-runner-state");
 
-Spawn an AI agent in an isolated container, observe its NDJSON event stream, and assert what it's allowed to do.
+export const runnerPool = await DurableObjectNamespace("RunnerPool", {
+  className: "RunnerPool",
+  sqlite: true,
+});
 
-```ts
-import { Gate, Act, Assert } from "gateproof";
-import { setFilepathRuntime, CloudflareSandboxRuntime } from "gateproof";
-import { getSandbox } from "@cloudflare/sandbox";
-
-// 1. Wire up your container runtime (once at startup)
-setFilepathRuntime(new CloudflareSandboxRuntime({
-  getSandbox: (config) => getSandbox(env.Sandbox, `agent-${config.name}`),
-}));
-
-// 2. Run the gate
-const container = await runtime.spawn({
-  name: "fix-auth",
-  agent: "claude-code",
-  model: "claude-sonnet-4-20250514",
-  task: "Fix the null pointer in src/auth.ts",
+export const jobQueue = await DurableObjectNamespace("JobQueue", {
+  className: "JobQueue",
+  sqlite: true,
 });
 
-const observe = createFilepathObserveResource(container, "fix-auth");
-
-await Gate.run({
-  name: "fix-auth-bug",
-  observe,
-  act: [Act.wait(300_000)],
-  assert: [
-    Assert.noErrors(),
-    Assert.hasAction("commit"),
-    Assert.hasAction("done"),
-    Assert.authority({
-      canCommit: true,
-      canSpawn: false,
-      forbiddenTools: ["delete_file"],
-    }),
-  ],
-  stop: { idleMs: 5000, maxMs: 300_000 },
+export const cacheWorker = await Worker("cinder-cache-worker", {
+  entrypoint: "./crates/cinder-cache/build/worker/shim.mjs",
+  bindings: {
+    CACHE_BUCKET: cacheBucket,
+    CINDER_INTERNAL_TOKEN: alchemy.secret(internalToken),
+  },
 });
+
+export const orchestrator = await Worker("cinder-orchestrator", {
+  entrypoint: "./crates/cinder-orchestrator/build/worker/shim.mjs",
+  bindings: {
+    CACHE_BUCKET: cacheBucket,
+    RUNNER_STATE: runnerState,
+    RUNNER_POOL: runnerPool,
+    JOB_QUEUE: jobQueue,
+    GITHUB_WEBHOOK_SECRET: alchemy.secret(webhookSecret),
+    CINDER_INTERNAL_TOKEN: alchemy.secret(internalToken),
+    GITHUB_PAT: alchemy.secret(githubPat),
+    CINDER_CACHE_WORKER_URL: cacheWorker.url!,
+    CINDER_FIXTURE_REPO: fixtureRepo,
+    CINDER_FIXTURE_BRANCH: fixtureBranch,
+    CINDER_FIXTURE_WORKFLOW: fixtureWorkflow,
+  },
+});
+
+await app.finalize();
+await syncFixtureRepository(`${orchestrator.url}/webhook/github`);
+
+const runtimeDirectory = new URL("./.gateproof/", import.meta.url);
+const runtimeFile = new URL("./.gateproof/runtime.json", import.meta.url);
+
+await mkdir(runtimeDirectory, { recursive: true });
+
+await Bun.write(
+  runtimeFile,
+  `${JSON.stringify(
+    {
+      generatedAt: new Date().toISOString(),
+      stage: process.env.CINDER_STAGE ?? "production",
+      orchestratorName: orchestrator.name,
+      orchestratorUrl: orchestrator.url,
+      cacheWorkerName: cacheWorker.name,
+      cacheWorkerUrl: cacheWorker.url,
+      fixtureRepo,
+      fixtureBranch,
+      fixtureWorkflow,
+    },
+    null,
+    2,
+  )}\n`,
+);
+
+console.log(`Wrote runtime outputs to ${runtimeFile.pathname}`);
 ```
 
-`Assert.authority()` enforces governance policies against the agent's actual behavior — what it committed, spawned, and which tools it used.
+### plan.ts
 
-## Writing good gates
+```ts
+import { Effect } from "effect";
+import crypto from "node:crypto";
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import type { ScopeFile } from "gateproof";
+import {
+  Act,
+  Assert,
+  Gate,
+  Plan,
+  Require,
+} from "gateproof";
+import { Cloudflare } from "gateproof/cloudflare";
 
-The hardest part of gateproof is not the library — it's writing gates that actually prove what you think they prove.
+type RuntimeState = {
+  orchestratorName?: string;
+  orchestratorUrl?: string;
+  cacheWorkerUrl?: string;
+  fixtureRepo?: string;
+  fixtureBranch?: string;
+  fixtureWorkflow?: string;
+};
 
-**A weak gate passes on silence.** If your system emits no logs and your only assertion is `Assert.noErrors()`, the gate passes vacuously. Nothing was tested. Use `requirePositiveSignal: true` on stories, or assert specific evidence (`Assert.hasAction`, `Assert.hasStage`).
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
 
-**A good gate is falsifiable.** Ask: "what broken implementation would still pass this gate?" If the answer is "many," the gate is too weak. Tighten it until a broken system fails.
+function readOptionalEnv(name: string): string | undefined {
+  const value = process.env[name];
+  if (typeof value !== "string") {
+    return undefined;
+  }
 
-**Start narrow, then widen.** One specific assertion that catches a real failure is worth more than ten vague ones. You can always add assertions later — you can't take back a false pass.
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
 
-## The loop
+function loadRuntimeState(): RuntimeState | null {
+  const runtimeFile = new URL("./.gateproof/runtime.json", import.meta.url);
 
-Gate fails. Agent reads the failure evidence. Agent fixes code. Gate re-runs. Loop until pass.
+  if (!existsSync(runtimeFile)) {
+    return null;
+  }
 
-**Bring your own agent** — the loop takes any async function:
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(runtimeFile, "utf8"));
+    if (!isRecord(parsed)) {
+      return null;
+    }
 
-```ts
-import { runPrdLoop } from "gateproof/prd";
-
-await runPrdLoop("./prd.ts", {
-  agent: async (ctx) => {
-    // ctx.failureSummary — what failed and why
-    // ctx.recentDiff    — recent git changes
-    // ctx.prdContent    — full PRD for context
-    // ctx.failedStory   — the Story object that failed
-    // ctx.signal        — AbortSignal for cancellation
-
-    // Use any agent: Claude Code, Cursor, Codex, custom LLM wrapper
-    const result = await yourAgent.fix(ctx.failureSummary);
-    return { changes: result.files, commitMsg: "fix: resolve failing gate" };
-  },
-  maxIterations: 5,
+    return {
+      orchestratorName:
+        typeof parsed.orchestratorName === "string" ? parsed.orchestratorName : undefined,
+      orchestratorUrl:
+        typeof parsed.orchestratorUrl === "string" ? parsed.orchestratorUrl : undefined,
+      cacheWorkerUrl:
+        typeof parsed.cacheWorkerUrl === "string" ? parsed.cacheWorkerUrl : undefined,
+      fixtureRepo: typeof parsed.fixtureRepo === "string" ? parsed.fixtureRepo : undefined,
+      fixtureBranch:
+        typeof parsed.fixtureBranch === "string" ? parsed.fixtureBranch : undefined,
+      fixtureWorkflow:
+        typeof parsed.fixtureWorkflow === "string" ? parsed.fixtureWorkflow : undefined,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function resolveLocalRunnerId(): string {
+  try {
+    const hostname = readFileSync("/etc/hostname", "utf8").trim();
+    return `cinder-${hostname || "unknown"}`;
+  } catch {
+    return "cinder-unknown";
+  }
+}
+
+const runtimeState = loadRuntimeState();
+const baseUrl = readOptionalEnv("CINDER_BASE_URL") ?? runtimeState?.orchestratorUrl ?? "";
+const cacheWorkerUrl =
+  readOptionalEnv("CINDER_CACHE_WORKER_URL") ?? runtimeState?.cacheWorkerUrl ?? "";
+const workerName =
+  readOptionalEnv("CINDER_WORKER_NAME") ?? runtimeState?.orchestratorName ?? "cinder-orchestrator";
+const fixtureRepo =
+  readOptionalEnv("CINDER_FIXTURE_REPO") ?? runtimeState?.fixtureRepo ?? "acoyfellow/cinder-prd-test";
+const fixtureBranch = readOptionalEnv("CINDER_FIXTURE_BRANCH") ?? runtimeState?.fixtureBranch ?? "";
+const fixtureWorkflow =
+  readOptionalEnv("CINDER_FIXTURE_WORKFLOW") ?? runtimeState?.fixtureWorkflow ?? "";
+const internalToken = readOptionalEnv("CINDER_INTERNAL_TOKEN") ?? "";
+
+const missKey = crypto.randomBytes(32).toString("hex");
+const newKey = crypto.randomBytes(32).toString("hex");
+const speedThresholdMs = Number(process.env.SPEED_THRESHOLD_MS ?? "60000");
+const testRepo = process.env.TEST_REPO ?? "";
+const harnessBaseUrl = "http://127.0.0.1:9000";
+const harnessRunUrl = `${harnessBaseUrl}/test/run`;
+const localRunnerId = resolveLocalRunnerId();
+const agentLogPath = "/tmp/cinder-agent-proof.log";
+const agentPidPath = "/tmp/cinder-agent-proof.pid";
+const runnerJobPath = "/tmp/cinder-proof-runner-job.json";
+const queuePayloadPath = "/tmp/cinder-proof-queue-payload.json";
+
+let managedHarness: ReturnType<typeof Bun.spawn> | null = null;
+
+async function canReachLocalHarness(): Promise<boolean> {
+  try {
+    const response = await fetch(harnessBaseUrl);
+    return response.ok || response.status === 404;
+  } catch {
+    return false;
+  }
+}
+
+async function ensureLocalHarness(): Promise<void> {
+  if (await canReachLocalHarness()) {
+    return;
+  }
+
+  managedHarness = Bun.spawn({
+    cmd: ["bun", "harness.ts"],
+    cwd: process.cwd(),
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+
+  const deadline = Date.now() + 5_000;
+  while (Date.now() < deadline) {
+    if (await canReachLocalHarness()) {
+      return;
+    }
+
+    await Bun.sleep(100);
+  }
+
+  throw new Error("cinder proof harness did not start on 127.0.0.1:9000");
+}
+
+function stopManagedHarness(): void {
+  if (!managedHarness) {
+    return;
+  }
+
+  managedHarness.kill();
+  managedHarness = null;
+}
+
+function stopManagedAgent(): void {
+  if (!existsSync(agentPidPath)) {
+    return;
+  }
+
+  try {
+    const pid = Number.parseInt(readFileSync(agentPidPath, "utf8").trim(), 10);
+    if (Number.isFinite(pid)) {
+      process.kill(pid);
+    }
+  } catch {
+    // Ignore stale proof agent state.
+  }
+
+  try {
+    rmSync(agentPidPath, { force: true });
+  } catch {
+    // Ignore pidfile cleanup failures during shutdown.
+  }
+}
+
+async function ensureColdBuildBaseline(): Promise<void> {
+  if (readOptionalEnv("COLD_BUILD_MS")) {
+    return;
+  }
+
+  if (!testRepo) {
+    return;
+  }
+
+  try {
+    const response = await fetch(harnessRunUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        repo: testRepo,
+        with_cache: false,
+      }),
+    });
+
+    if (!response.ok) {
+      return;
+    }
+
+    const parsed: unknown = await response.json();
+    if (!isRecord(parsed)) {
+      return;
+    }
+
+    const buildDurationMs = parsed.build_duration_ms;
+    if (typeof buildDurationMs !== "number" || !Number.isFinite(buildDurationMs)) {
+      return;
+    }
+
+    process.env.COLD_BUILD_MS = String(buildDurationMs);
+  } catch {
+    // Let the existing prerequisite fail clearly if the harness is unavailable.
+  }
+}
+
+await ensureColdBuildBaseline();
+
+const workerLogs = Cloudflare.observe({
+  accountId: readOptionalEnv("CLOUDFLARE_ACCOUNT_ID") ?? "",
+  apiToken: readOptionalEnv("CLOUDFLARE_API_TOKEN") ?? "",
+  workerName,
+  sinceMs: 120_000,
+  pollInterval: 1_000,
 });
-```
 
-Or use a pre-built agent:
+if (!process.env.CINDER_BASE_URL && baseUrl) {
+  process.env.CINDER_BASE_URL = baseUrl;
+}
 
-```ts
-import { runPrdLoop, createOpenCodeAgent } from "gateproof/prd";
+if (!process.env.CINDER_WORKER_NAME && workerName) {
+  process.env.CINDER_WORKER_NAME = workerName;
+}
+
+if (!process.env.CINDER_FIXTURE_REPO && fixtureRepo) {
+  process.env.CINDER_FIXTURE_REPO = fixtureRepo;
+}
+
+if (!process.env.CINDER_FIXTURE_BRANCH && fixtureBranch) {
+  process.env.CINDER_FIXTURE_BRANCH = fixtureBranch;
+}
+
+if (!process.env.CINDER_FIXTURE_WORKFLOW && fixtureWorkflow) {
+  process.env.CINDER_FIXTURE_WORKFLOW = fixtureWorkflow;
+}
 
-await runPrdLoop("./prd.ts", {
-  agent: createOpenCodeAgent({ apiKey: process.env.OPENCODE_ZEN_API_KEY }),
-  maxIterations: 7,
+const scope = {
+  spec: {
+    title: "Cinder",
+    tutorial: {
+      goal: "Prove cinder on a live deployment, not just deploy it.",
+      outcome:
+        "Webhook intake, queueing, runner registration, cache paths, and the speed claim all go green.",
+    },
+    howTo: {
+      task: "Run the cinder proof loop against already-provisioned infrastructure.",
+      done:
+        "Cinder only exits green when the live system can do the work and the speed claim holds.",
+    },
+    explanation: {
+      summary:
+        "alchemy.run.ts creates the infrastructure once and writes .gateproof/runtime.json. This file is only the acceptance loop for the live product.",
+    },
+  },
+  plan: Plan.define({
+    goals: [
+      {
+        id: "webhook",
+        title: "A GitHub webhook queues a runnable job",
+        gate: Gate.define({
+          observe: workerLogs,
+          prerequisites: [
+            Require.env(
+              "CLOUDFLARE_ACCOUNT_ID",
+              "CLOUDFLARE_ACCOUNT_ID is required for Cloudflare worker log observation.",
+            ),
+            Require.env(
+              "CLOUDFLARE_API_TOKEN",
+              "CLOUDFLARE_API_TOKEN is required for Cloudflare worker log observation.",
+            ),
+            Require.env(
+              "GITHUB_PAT",
+              "GITHUB_PAT is required to dispatch the GitHub proof workflow.",
+            ),
+            Require.env(
+              "CINDER_FIXTURE_BRANCH",
+              "Run bun run provision first or set CINDER_FIXTURE_BRANCH for the GitHub proof fixture.",
+            ),
+            Require.env(
+              "CINDER_FIXTURE_WORKFLOW",
+              "Run bun run provision first or set CINDER_FIXTURE_WORKFLOW for the GitHub proof fixture.",
+            ),
+            Require.env(
+              "CINDER_INTERNAL_TOKEN",
+              "CINDER_INTERNAL_TOKEN is required for internal API access.",
+            ),
+            Require.env(
+              "CINDER_BASE_URL",
+              "Run bun run provision first or set CINDER_BASE_URL to the live orchestrator URL.",
+            ),
+          ],
+          act: [
+            Act.exec(
+              `bun -e 'const repo = ${JSON.stringify(fixtureRepo)};
+const workflow = ${JSON.stringify(fixtureWorkflow)};
+const branch = ${JSON.stringify(fixtureBranch)};
+const token = process.env.GITHUB_PAT;
+if (!token) {
+  throw new Error("GITHUB_PAT is required");
+}
+const headers = {
+  Accept: "application/vnd.github+json",
+  Authorization: "Bearer " + token,
+  "X-GitHub-Api-Version": "2022-11-28",
+};
+const listUrl =
+  "https://api.github.com/repos/" +
+  repo +
+  "/actions/workflows/" +
+  workflow +
+  "/runs?event=workflow_dispatch&branch=" +
+  encodeURIComponent(branch) +
+  "&per_page=20";
+const response = await fetch(listUrl, { headers });
+if (!response.ok) {
+  throw new Error("GitHub workflow run listing failed: " + response.status);
+}
+const payload = await response.json();
+const runs = Array.isArray(payload.workflow_runs) ? payload.workflow_runs : [];
+for (const run of runs) {
+  if (typeof run?.id !== "number" || run.status === "completed") {
+    continue;
+  }
+  const cancelResponse = await fetch(
+    "https://api.github.com/repos/" + repo + "/actions/runs/" + run.id + "/cancel",
+    {
+      method: "POST",
+      headers,
+    },
+  );
+  if (!cancelResponse.ok && cancelResponse.status !== 409) {
+    throw new Error("GitHub workflow cancel failed: " + cancelResponse.status);
+  }
+}'`,
+              {
+                timeoutMs: 60_000,
+              },
+            ),
+            Act.exec(
+              `curl -sf -X POST https://api.github.com/repos/${fixtureRepo}/actions/workflows/${fixtureWorkflow}/dispatches \
+                -H "Accept: application/vnd.github+json" \
+                -H "Authorization: Bearer $GITHUB_PAT" \
+                -H "X-GitHub-Api-Version: 2022-11-28" \
+                -d '${JSON.stringify({ ref: fixtureBranch })}'`,
+            ),
+            Act.exec("sleep 25"),
+          ],
+          assert: [
+            Assert.noErrors(),
+            Assert.hasAction("webhook_received"),
+            Assert.hasAction("signature_verified"),
+            Assert.hasAction("job_queued"),
+          ],
+          timeoutMs: 40_000,
+        }),
+      },
+      {
+        id: "queue",
+        title: "A queued job can be inspected without dequeueing",
+        gate: Gate.define({
+          observe: workerLogs,
+          prerequisites: [
+            Require.env(
+              "CLOUDFLARE_ACCOUNT_ID",
+              "CLOUDFLARE_ACCOUNT_ID is required for Cloudflare worker log observation.",
+            ),
+            Require.env(
+              "CLOUDFLARE_API_TOKEN",
+              "CLOUDFLARE_API_TOKEN is required for Cloudflare worker log observation.",
+            ),
+            Require.env(
+              "CINDER_INTERNAL_TOKEN",
+              "CINDER_INTERNAL_TOKEN is required for queue inspection.",
+            ),
+            Require.env(
+              "CINDER_BASE_URL",
+              "Run bun run provision first or set CINDER_BASE_URL to the live orchestrator URL.",
+            ),
+          ],
+          act: [
+            Act.exec(
+              `sh -c 'curl -sf ${baseUrl}/jobs/peek \
+                -H "Authorization: Bearer ${internalToken}" \
+                | tee "${queuePayloadPath}"'`,
+            ),
+          ],
+          assert: [
+            Assert.noErrors(),
+            Assert.responseBodyIncludes("repo_full_name"),
+            Assert.responseBodyIncludes("repo_clone_url"),
+            Assert.responseBodyIncludes("runner_registration_url"),
+            Assert.responseBodyIncludes("runner_registration_token"),
+            Assert.responseBodyIncludes("cache_key"),
+          ],
+          timeoutMs: 8_000,
+        }),
+      },
+      {
+        id: "runner",
+        title: "A runner can execute a queued GitHub job",
+        gate: Gate.define({
+          observe: workerLogs,
+          prerequisites: [
+            Require.env(
+              "CLOUDFLARE_ACCOUNT_ID",
+              "CLOUDFLARE_ACCOUNT_ID is required for Cloudflare worker log observation.",
+            ),
+            Require.env(
+              "CLOUDFLARE_API_TOKEN",
+              "CLOUDFLARE_API_TOKEN is required for Cloudflare worker log observation.",
+            ),
+            Require.env(
+              "CINDER_INTERNAL_TOKEN",
+              "CINDER_INTERNAL_TOKEN is required for runner registration.",
+            ),
+            Require.env(
+              "CINDER_BASE_URL",
+              "Run bun run provision first or set CINDER_BASE_URL to the live orchestrator URL.",
+            ),
+            Require.env(
+              "GITHUB_PAT",
+              "GITHUB_PAT is required to confirm the queued GitHub run completed.",
+            ),
+          ],
+          act: [
+            Act.exec(
+              `curl -sf ${baseUrl}/jobs/peek \
+                -H "Authorization: Bearer ${internalToken}" \
+                > "${runnerJobPath}"`,
+            ),
+            Act.exec(
+              `bun -e 'import crypto from "node:crypto";
+import { readFileSync } from "node:fs";
+const payload = JSON.parse(readFileSync(${JSON.stringify(runnerJobPath)}, "utf8"));
+if (typeof payload.cache_key !== "string" || payload.cache_key.length === 0) {
+  throw new Error("runner job payload missing cache_key");
+}
+const key = payload.cache_key;
+const token = ${JSON.stringify(internalToken)};
+if (!token) {
+  throw new Error("CINDER_INTERNAL_TOKEN is required for fixture cache reset");
+}
+let base = ${JSON.stringify(cacheWorkerUrl)};
+const restoreProbe = await fetch(
+  ${JSON.stringify(baseUrl)} + "/cache/restore/" + key,
+  {
+    method: "POST",
+    headers: {
+      Authorization: "Bearer " + token,
+    },
+  },
+);
+if (!restoreProbe.ok) {
+  throw new Error("fixture cache reset probe failed: " + restoreProbe.status);
+}
+const restorePayload = await restoreProbe.json();
+if (typeof restorePayload.url === "string" && restorePayload.url.length > 0) {
+  base = new URL(restorePayload.url).origin;
+}
+if (!base) {
+  throw new Error("cache worker base URL is required for fixture cache reset");
+}
+const exp = Math.floor(Date.now() / 1000) + 3600;
+const sig = crypto
+  .createHmac("sha256", token)
+  .update("delete:" + key + ":" + exp)
+  .digest("hex");
+const response = await fetch(
+  base.replace(/\\/$/, "") +
+    "/objects/" +
+    key +
+    "?op=delete&exp=" +
+    exp +
+    "&sig=" +
+    sig,
+  {
+    method: "DELETE",
+  },
+);
+if (!response.ok && response.status !== 404) {
+  throw new Error("fixture cache reset failed: " + response.status);
+}
+console.log("fixture cache reset");'`,
+            ),
+            Act.exec(
+              `sh -c 'if [ -f "${agentPidPath}" ] && kill -0 "$(cat "${agentPidPath}")" 2>/dev/null; then exit 0; fi; : >"${agentLogPath}"; cargo run --quiet -p cinder-agent -- --url "${baseUrl}" --token "${internalToken}" --poll-ms 250 >"${agentLogPath}" 2>&1 & echo $! >"${agentPidPath}"; sleep 5'`,
+            ),
+            Act.exec(
+              `bun -e 'import { existsSync, readFileSync } from "node:fs";
+const payload = JSON.parse(readFileSync(${JSON.stringify(runnerJobPath)}, "utf8"));
+if (typeof payload.run_id !== "number") {
+  throw new Error("queue payload missing run_id");
+}
+if (typeof payload.repo_full_name !== "string" || payload.repo_full_name.length === 0) {
+  throw new Error("queue payload missing repo_full_name");
+}
+const token = process.env.GITHUB_PAT;
+if (!token) {
+  throw new Error("GITHUB_PAT is required");
+}
+const headers = {
+  Accept: "application/vnd.github+json",
+  Authorization: "Bearer " + token,
+  "X-GitHub-Api-Version": "2022-11-28",
+};
+const deadline = Date.now() + 600000;
+let run = null;
+while (Date.now() < deadline) {
+  const response = await fetch(
+    "https://api.github.com/repos/" + payload.repo_full_name + "/actions/runs/" + payload.run_id,
+    { headers },
+  );
+  if (!response.ok) {
+    if (response.status >= 500) {
+      await Bun.sleep(2000);
+      continue;
+    }
+    throw new Error("GitHub workflow run fetch failed: " + response.status);
+  }
+  run = await response.json();
+  if (run.status === "completed") {
+    break;
+  }
+  await Bun.sleep(2000);
+}
+if (!run || run.status !== "completed") {
+  throw new Error("GitHub workflow run did not complete");
+}
+const logNeedle = "completed with exit code 0";
+const logDeadline = Date.now() + 30000;
+while (Date.now() < logDeadline) {
+  if (existsSync(${JSON.stringify(agentLogPath)})) {
+    const logContents = readFileSync(${JSON.stringify(agentLogPath)}, "utf8");
+    if (logContents.includes(logNeedle)) {
+      break;
+    }
+  }
+  await Bun.sleep(500);
+}
+console.log(JSON.stringify(run));
+if (existsSync(${JSON.stringify(agentLogPath)})) {
+  console.log(readFileSync(${JSON.stringify(agentLogPath)}, "utf8"));
+}
+if (run.conclusion !== "success") {
+  process.exit(1);
+}'`,
+              {
+                timeoutMs: 600_000,
+              },
+            ),
+          ],
+          assert: [
+            Assert.noErrors(),
+            Assert.hasAction("runner_registered"),
+            Assert.hasAction("runner_pool_updated"),
+            Assert.hasAction("job_dequeued"),
+            Assert.responseBodyIncludes(`"conclusion":"success"`),
+            Assert.responseBodyIncludes("starting github runner for job"),
+            Assert.responseBodyIncludes("completed with exit code 0"),
+          ],
+          timeoutMs: 600_000,
+        }),
+      },
+      {
+        id: "cache-restore",
+        title: "The fixture cache key currently restores as a cold miss",
+        gate: Gate.define({
+          prerequisites: [
+            Require.env(
+              "CLOUDFLARE_ACCOUNT_ID",
+              "CLOUDFLARE_ACCOUNT_ID is required for Cloudflare worker log observation.",
+            ),
+            Require.env(
+              "CLOUDFLARE_API_TOKEN",
+              "CLOUDFLARE_API_TOKEN is required for Cloudflare worker log observation.",
+            ),
+            Require.env(
+              "CINDER_INTERNAL_TOKEN",
+              "CINDER_INTERNAL_TOKEN is required for cache restore.",
+            ),
+            Require.env(
+              "CINDER_BASE_URL",
+              "Run bun run provision first or set CINDER_BASE_URL to the live orchestrator URL.",
+            ),
+          ],
+          act: [
+            Act.exec(
+              `bun -e 'import { readFileSync } from "node:fs";
+const payload = JSON.parse(readFileSync(${JSON.stringify(runnerJobPath)}, "utf8"));
+if (typeof payload.job_id !== "number") {
+  throw new Error("runner job payload missing job_id");
+}
+const needle = "cache miss for job " + payload.job_id;
+const deadline = Date.now() + 5000;
+while (Date.now() < deadline) {
+  const log = readFileSync(${JSON.stringify(agentLogPath)}, "utf8");
+  if (log.includes(needle)) {
+    console.log(needle);
+    process.exit(0);
+  }
+  await Bun.sleep(250);
+}
+throw new Error("agent log missing cache miss marker for job " + payload.job_id);'`,
+            ),
+          ],
+          assert: [
+            Assert.noErrors(),
+            Assert.responseBodyIncludes("cache miss for job"),
+          ],
+          timeoutMs: 5_000,
+        }),
+      },
+      {
+        id: "cache-push",
+        title: "The cache upload path returns a real cache-worker upload URL",
+        gate: Gate.define({
+          observe: workerLogs,
+          prerequisites: [
+            Require.env(
+              "CLOUDFLARE_ACCOUNT_ID",
+              "CLOUDFLARE_ACCOUNT_ID is required for Cloudflare worker log observation.",
+            ),
+            Require.env(
+              "CLOUDFLARE_API_TOKEN",
+              "CLOUDFLARE_API_TOKEN is required for Cloudflare worker log observation.",
+            ),
+            Require.env(
+              "CINDER_INTERNAL_TOKEN",
+              "CINDER_INTERNAL_TOKEN is required for cache upload.",
+            ),
+            Require.env(
+              "CINDER_BASE_URL",
+              "Run bun run provision first or set CINDER_BASE_URL to the live orchestrator URL.",
+            ),
+          ],
+          act: [
+            Act.exec(
+              `sh -c 'rm -f /tmp/cinder-proof-cache-push.tar.xz /tmp/cinder-proof-cache-push-download.tar.xz /tmp/cinder-proof-cache-push-upload.json /tmp/cinder-proof-cache-push-restore.json /tmp/cinder-proof-cache-push-list.txt; tmpdir="$(mktemp -d)"; printf "proof\\n" > "$tmpdir/proof.txt"; tar -cJf /tmp/cinder-proof-cache-push.tar.xz -C "$tmpdir" proof.txt; rm -rf "$tmpdir"'`,
+            ),
+            Act.exec(
+              `bun -e 'import { writeFileSync } from "node:fs";
+const response = await fetch(
+  ${JSON.stringify(baseUrl)} + "/cache/upload",
+  {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: "Bearer " + ${JSON.stringify(internalToken)},
+    },
+    body: JSON.stringify({
+      key: ${JSON.stringify(newKey)},
+      content_type: "application/x-xz",
+      size_bytes: 1024,
+    }),
+  },
+);
+if (!response.ok) {
+  throw new Error("cache upload failed: " + response.status);
+}
+const upload = await response.json();
+if (typeof upload.url !== "string" || upload.url.length === 0) {
+  throw new Error("cache upload response missing url");
+}
+if (!upload.url.includes("/objects/")) {
+  throw new Error("cache upload returned non-worker url");
+}
+writeFileSync("/tmp/cinder-proof-cache-push-upload.json", JSON.stringify(upload));
+console.log(JSON.stringify(upload));'`,
+            ),
+            Act.exec(
+              `bun -e 'import { readFileSync } from "node:fs";
+const upload = JSON.parse(readFileSync("/tmp/cinder-proof-cache-push-upload.json", "utf8"));
+const archive = readFileSync("/tmp/cinder-proof-cache-push.tar.xz");
+const response = await fetch(upload.url, {
+  method: "PUT",
+  body: archive,
 });
-```
+if (!response.ok) {
+  throw new Error("cache object upload failed: " + response.status);
+}
+console.log("cache object uploaded");'`,
+            ),
+            Act.exec(
+              `bun -e 'import { writeFileSync } from "node:fs";
+const response = await fetch(
+  ${JSON.stringify(baseUrl)} + "/cache/restore/" + ${JSON.stringify(newKey)},
+  {
+    method: "POST",
+    headers: {
+      Authorization: "Bearer " + ${JSON.stringify(internalToken)},
+    },
+  },
+);
+if (!response.ok) {
+  throw new Error("cache restore failed: " + response.status);
+}
+const restore = await response.json();
+if (restore.miss === true) {
+  throw new Error("cache restore returned miss after upload");
+}
+if (typeof restore.url !== "string" || restore.url.length === 0) {
+  throw new Error("cache restore response missing url");
+}
+writeFileSync("/tmp/cinder-proof-cache-push-restore.json", JSON.stringify(restore));
+console.log(JSON.stringify(restore));'`,
+            ),
+            Act.exec(
+              `bun -e 'import { readFileSync, writeFileSync } from "node:fs";
+const restore = JSON.parse(readFileSync("/tmp/cinder-proof-cache-push-restore.json", "utf8"));
+const response = await fetch(restore.url);
+if (!response.ok) {
+  throw new Error("cache object download failed: " + response.status);
+}
+const bytes = new Uint8Array(await response.arrayBuffer());
+writeFileSync("/tmp/cinder-proof-cache-push-download.tar.xz", bytes);
+console.log("cache object downloaded");'`,
+            ),
+            Act.exec(
+              `sh -c 'test -s /tmp/cinder-proof-cache-push-download.tar.xz && tar -tJf /tmp/cinder-proof-cache-push-download.tar.xz > /tmp/cinder-proof-cache-push-list.txt && cat /tmp/cinder-proof-cache-push-list.txt'`,
+            ),
+          ],
+          assert: [
+            Assert.noErrors(),
+            Assert.responseBodyIncludes("proof.txt"),
+          ],
+          timeoutMs: 8_000,
+        }),
+      },
+      {
+        id: "speed-claim",
+        title: "A warm workflow run can complete with a real cache hit",
+        gate: Gate.define({
+          observe: workerLogs,
+          prerequisites: [
+            Require.env(
+              "CLOUDFLARE_ACCOUNT_ID",
+              "CLOUDFLARE_ACCOUNT_ID is required for Cloudflare worker log observation.",
+            ),
+            Require.env(
+              "CLOUDFLARE_API_TOKEN",
+              "CLOUDFLARE_API_TOKEN is required for Cloudflare worker log observation.",
+            ),
+            Require.env(
+              "GITHUB_PAT",
+              "GITHUB_PAT is required to dispatch and confirm the warm workflow run.",
+            ),
+          ],
+          act: [
+            Act.exec(
+              `bun -e 'import { readFileSync } from "node:fs";
+const payload = JSON.parse(readFileSync(${JSON.stringify(runnerJobPath)}, "utf8"));
+if (typeof payload.run_id !== "number") {
+  throw new Error("runner job payload missing run_id");
+}
+console.log(String(payload.run_id));' > /tmp/cinder-proof-speed-before.txt`,
+            ),
+            Act.exec(
+              `curl -sf -X POST https://api.github.com/repos/${fixtureRepo}/actions/workflows/${fixtureWorkflow}/dispatches \
+                -H "Accept: application/vnd.github+json" \
+                -H "Authorization: Bearer $GITHUB_PAT" \
+                -H "X-GitHub-Api-Version: 2022-11-28" \
+                -d '${JSON.stringify({ ref: fixtureBranch })}'`,
+            ),
+            Act.exec("sleep 5"),
+            Act.exec(
+              `bun -e 'import { readFileSync } from "node:fs";
+const repo = ${JSON.stringify(fixtureRepo)};
+const workflow = ${JSON.stringify(fixtureWorkflow)};
+const branch = ${JSON.stringify(fixtureBranch)};
+const token = process.env.GITHUB_PAT;
+if (!token) {
+  throw new Error("GITHUB_PAT is required");
+}
+const previousId = readFileSync("/tmp/cinder-proof-speed-before.txt", "utf8").trim();
+const headers = {
+  Accept: "application/vnd.github+json",
+  Authorization: "Bearer " + token,
+  "X-GitHub-Api-Version": "2022-11-28",
+};
+const listUrl =
+  "https://api.github.com/repos/" +
+  repo +
+  "/actions/workflows/" +
+  workflow +
+  "/runs?event=workflow_dispatch&branch=" +
+  encodeURIComponent(branch) +
+  "&per_page=5";
+const deadline = Date.now() + 600000;
+let run = null;
+while (Date.now() < deadline) {
+  const listResponse = await fetch(listUrl, { headers });
+  if (!listResponse.ok) {
+    throw new Error("GitHub workflow run listing failed: " + listResponse.status);
+  }
+  const listPayload = await listResponse.json();
+  const runs = Array.isArray(listPayload.workflow_runs) ? listPayload.workflow_runs : [];
+  const candidate = runs.find((entry) => typeof entry?.id === "number" && String(entry.id) !== previousId);
+  if (candidate && typeof candidate.id === "number") {
+    const runResponse = await fetch(
+      "https://api.github.com/repos/" + repo + "/actions/runs/" + candidate.id,
+      { headers },
+    );
+    if (!runResponse.ok) {
+      throw new Error("GitHub workflow run fetch failed: " + runResponse.status);
+    }
+    run = await runResponse.json();
+    if (run.status === "completed") {
+      break;
+    }
+  }
+  await Bun.sleep(2000);
+}
+if (!run || run.status !== "completed") {
+  throw new Error("warm GitHub workflow run did not complete");
+}
+console.log(JSON.stringify(run));
+console.log(readFileSync(${JSON.stringify(agentLogPath)}, "utf8"));'`,
+              {
+                timeoutMs: 600_000,
+              },
+            ),
+          ],
+          assert: [
+            Assert.noErrors(),
+            Assert.responseBodyIncludes(`"conclusion":"success"`),
+            Assert.responseBodyIncludes("cache restored for job"),
+          ],
+          timeoutMs: 600_000,
+        }),
+      },
+    ],
+    loop: {
+      maxIterations: 1,
+      stopOnFailure: true,
+    },
+    cleanup: {
+      actions: [
+        Act.exec(
+          `if [ -n "${internalToken}" ] && [ -n "${baseUrl}" ]; then curl -sf -X DELETE ${baseUrl}/runners/${localRunnerId} -H "Authorization: Bearer ${internalToken}" >/dev/null; else exit 0; fi`,
+        ),
+      ],
+    },
+  }),
+} satisfies ScopeFile;
 
-## Generate a PRD from plain language
+export default scope;
 
-```bash
-echo "Build a signup flow with email verification" | npx gateproof prdts --stdout
+if (import.meta.main) {
+  stopManagedAgent();
+
+  if (testRepo) {
+    await ensureLocalHarness();
+  }
+
+  await ensureColdBuildBaseline();
+
+  try {
+    const result = await Effect.runPromise(
+      Plan.runLoop(scope.plan, {
+        maxIterations: scope.plan.loop?.maxIterations,
+      }),
+    );
+
+    console.log(JSON.stringify(result, null, 2));
+
+    if (result.status !== "pass") {
+      process.exitCode = 1;
+    }
+  } finally {
+    stopManagedAgent();
+    stopManagedHarness();
+  }
+
+  process.exit(process.exitCode ?? 0);
+}
 ```
 
-## End-to-end CLI pipeline
+Status: Historical artifacts are available locally
+
+The preserved Cinder files are present and typechecked against the local Gateproof package. Reproducing the live result still requires Cloudflare infrastructure and Cinder environment variables.
+
+## Roadmap
+
+Gateproof is not ready to fully dogfood itself on a case study like Cinder yet. The next phase is about tightening the guardrails, not adding another rewrite.
 
-> Contributed by @grok
+- Save the latest real proof result to disk so the loop always has a concrete last-known truth.
+- Make finalize refuse to ship unless the saved real proof result is fully green.
+- Separate the real proof path from side experiments so exploration can happen without polluting the proof story.
+- Let plans choose direct evidence when log tailing is flaky, so a valid live pass does not fail on observation noise alone.
+- Dogfood Gateproof on Cinder again only after those guardrails are in place.
+
+## How To
+
+Task: Run one complete gate from one file.
+
+Done when: The endpoint returns 200 and the body contains hello world.
+
+Run it:
 
 ```bash
-# Natural language → prd.ts → agent loop
-echo "Build a signup flow with email verification" | npx gateproof prdts --out prd.ts
-npx gateproof smoke ./prd.ts
-bun run prd.ts
+bun run example:hello-world:worker
+bun run alchemy.run.ts
+bun run plan.ts
 ```
 
-## Docs
+## Breaking Changes In 0.4.0
+
+- `Prd.*` is gone
+- `Claim.*` is gone
+- `plan.ts` is the canonical entrypoint
+- `Plan.*` replaces the old front door
+
+## Reference
+
+Files:
+- `examples/hello-world/plan.ts`
+- `alchemy.run.ts`
+- `plan.ts`
+
+Canonical gates:
+- GET / returns hello world
+
+Loop:
+- `maxIterations: 1`
+- `stopOnFailure: true`
 
-Full documentation, tutorials, and API reference: [gateproof.dev/docs](https://gateproof.dev/docs)
+Core API:
+- `Gate.define(...)`
+- `Plan.define(...)`
+- `Plan.run(...)`
+- `Plan.runLoop(...)`
+- `Cloudflare.observe(...)`
+- `Assert.hasAction(...)`
+- `Assert.responseBodyIncludes(...)`
+- `Assert.numericDeltaFromEnv(...)`
 
-## License
+## Explanation
 
-MIT
+Root plan.ts stays small. Gateproof itself is built forward.