gateproof 0.2.2 → 0.5.0

package/README.md

@@ -1,440 +1,1516 @@
-# gateproof
+# Gateproof
 
-Build software in reverse. PRD defines what should exist. Gates verify reality. Agent iterations refine until gates pass.
+Gateproof runs the proof, sends in the worker, and keeps going until the live claim is true.
 
-## What gateproof does
+## Tutorial
 
-gateproof enables **agent iterations** with minimal context overhead.
+Goal: Start with one tiny gate that is small on purpose and complete on purpose.
 
-**The workflow:**
-1. PRD defines stories (what should exist)
-2. Gates verify reality (does it work?)
-3. Agent gets PRD + gate failure (minimal context)
-4. Agent fixes, gates re-run
-5. Iterate until all gates pass
+### examples/hello-world/plan.ts
 
-**Why this works:**
-- PRD is single source of truth (clear intent, minimal context)
-- Gates provide concrete feedback (not vague requirements)
-- Agent gets context only when needed (efficient)
-- Iteration ensures correctness (converges to working code)
+```ts
+import { Effect } from "effect";
+import {
+  Act,
+  Assert,
+  Gate,
+  Plan,
+  createHttpObserveResource,
+  type ScopeFile,
+} from "../../src/index";
+import { HELLO_WORLD_PORT } from "./server";
 
-gateproof **executes gates**. It does not define intent, plans, or workflows. A gate is a test specification: observe logs, run actions, assert results. gateproof runs it and returns evidence.
+const baseUrl = `http://127.0.0.1:${HELLO_WORLD_PORT}`;
 
-**Authority chain:**
-- **PRD (`prd.ts`)** — authority on intent, order, and dependencies (if you use the PRD runner)
-- **Gate implementations** — authority on how reality is observed
-- **gateproof runtime** — authority on enforcement only
-
-gateproof never decides *what* to build. It returns results; your CI/CD decides whether you are allowed to proceed.
-
-## Agent skill: prdts-maker
-
-This repo is agent-first. Use the `prdts-maker` skill to turn a prompt into a working `prd.ts`.
-
-**How to use it:**
-- Provide a prompt (big blob of text is fine).
-- Ask the agent to run the `prdts-maker` skill and output a complete `prd.ts`.
-- Save and run: `bun run prd.ts`.
-
-**Example prompt:**
-```text
-@prdts-maker Create prd.ts for:
-- User can sign up
-- Email verification works (depends on signup)
-- User can log in (depends on verification)
-Include gate files under ./gates/.
-```
+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;
 
-## CLI: npx gateproof prdts
+export default scope;
 
-Generate a `prd.ts` from a prompt without opening the repo.
+if (import.meta.main) {
+  const result = await Effect.runPromise(Plan.runLoop(scope.plan));
+  console.log(JSON.stringify(result, null, 2));
 
-```bash
-echo "Build a signup flow with email verification and login" | npx gateproof prdts --stdout
-npx gateproof prdts --in stories.txt --out prd.ts
+  if (result.status !== "pass") {
+    process.exitCode = 1;
+  }
+}
 ```
 
-This calls Opencode directly. Set `OPENCODE_ZEN_API_KEY` (or pass `--api-key`).
+Outcome: The loop only passes when the live response says hello world.
+
+## First Case Study: Cinder
+
+### alchemy.run.ts
+
+```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";
+
+function requireEnv(name: string): string {
+  const value = process.env[name]?.trim();
+
+  if (!value) {
+    throw new Error(`${name} is required for cinder provisioning`);
+  }
 
-Paste mode (interactive stdin):
+  return value;
+}
 
-```bash
-npx gateproof prdts
-# paste a prompt, then Ctrl-D
-```
+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 fixtureCargoToml = `[package]
+name = "cinder-proof"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+`;
+
+const fixtureCargoLock = `# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[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,
+}
 
-To target a different Opencode base URL or model:
+fn main() {
+    let message = ProofMessage {
+        ok: true,
+        source: "cinder-proof",
+    };
 
-```bash
-npx gateproof prdts --endpoint https://opencode.ai/zen/v1 --model big-pickle --in stories.txt --out prd.ts
-```
+    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}"`,
+    );
+  }
 
-## Agent Iterations: The Loop
+  return { owner, name };
+}
 
-The core innovation: agents work from PRD only, gates verify, iterate until correct.
+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 ?? {}),
+    },
+  });
 
-**The iteration loop:**
-1. Run PRD → executes gates in dependency order
-2. Gate fails → agent gets: codebase context (e.g., `AGENTS.md`) + failure output
-3. Agent fixes → makes changes to codebase
-4. Loop repeats → re-run PRD, check if gates pass
-5. All gates pass → done
+  if (okStatuses.includes(response.status)) {
+    return response;
+  }
 
-**Why minimal context:**
-- Agent starts with PRD only (no full codebase upfront)
-- Agent gets context only when gates fail (just-in-time)
-- PRD stays as authority (what to build)
-- Gates provide concrete feedback (what's wrong)
+  const body = await response.text();
+  throw new Error(
+    `GitHub API ${init.method ?? "GET"} ${path} failed with ${response.status}: ${body}`,
+  );
+}
 
-**Example loop script:**
-```bash
-# patterns/prd/agent-iteration-loop.sh
-while true; do
-  bun run prd.ts || {
-    # Gate failed - agent gets PRD + failure output
-    agent --context prd.ts --failure "$(cat gate-output.txt)"
-    # Agent fixes, loop continues
-  }
-  break  # All gates passed
-done
-```
+async function ensureFixtureRepository() {
+  const { owner, name } = parseFixtureRepository(fixtureRepo);
+  const existing = await githubRequest(`/repos/${owner}/${name}`, {}, [200, 404]);
 
-**The guardrails:**
-- Max failures (default: 5) → auto-pause if stuck
-- Git diff check → agent must make changes
-- Pause file → manual control
+  if (existing.status === 200) {
+    return (await existing.json()) as { default_branch: string; full_name: string };
+  }
 
-This solves the context management problem: agents don't need full codebase context upfront. They get minimal context (PRD), concrete feedback (gate failures), and iterate until correct.
+  const viewer = (await (
+    await githubRequest("/user")
+  ).json()) as { login: string };
 
-## Anatomy of a prd.ts (1 list)
+  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}"`,
+    );
+  }
 
-1. **Instructions**: each story title encodes behavior + evidence + scope (the agent's marching orders).
-2. **Stories**: `stories[]` holds `{ id, title, gateFile, dependsOn?, progress? }` in execution order.
-3. **Gates**: `gateFile` points at a gate script that observes logs, acts, and asserts evidence.
-4. **Loop state**: `runPrd(...)` returns success or the `failedStory` plus gate evidence (actions/stages/errors).
-5. **Loop instructions**: on failure, feed the agent `prd.ts` + gate output, fix code, re-run PRD until pass.
+  const created = await githubRequest(
+    "/user/repos",
+    {
+      method: "POST",
+      body: JSON.stringify({
+        name,
+        description: "Canonical GitHub proof fixture for Cinder",
+        auto_init: true,
+        private: false,
+      }),
+    },
+    [201],
+  );
 
-## Stories as gates
+  return (await created.json()) as { default_branch: string; full_name: string };
+}
 
-A PRD (Product Requirements Document) defines stories. Stories are gates. Each story references a gate file. The gate file verifies the story against reality.
+async function ensureFixtureBranch(repo: { default_branch: string }) {
+  if (fixtureBranch === repo.default_branch) {
+    return;
+  }
 
-Reality is the source of truth; gates make it enforceable in CI.
+  const { owner, name } = parseFixtureRepository(fixtureRepo);
+  const branchResponse = await githubRequest(
+    `/repos/${owner}/${name}/git/ref/heads/${encodeURIComponent(fixtureBranch)}`,
+    {},
+    [200, 404],
+  );
 
-### prd.ts example
+  if (branchResponse.status === 200) {
+    return;
+  }
 
-```typescript
-// prd.ts
-import { definePrd } from "gateproof/prd";
+  const defaultBranchRef = (await (
+    await githubRequest(
+      `/repos/${owner}/${name}/git/ref/heads/${encodeURIComponent(repo.default_branch)}`,
+    )
+  ).json()) as { object: { sha: string } };
 
-export const prd = definePrd({
-  stories: [
+  await githubRequest(
+    `/repos/${owner}/${name}/git/refs`,
     {
-      id: "user-signup",
-      title: "User can sign up",
-      gateFile: "./gates/user-signup.gate.ts",
-      progress: ["signup_page_live", "user_created"],
+      method: "POST",
+      body: JSON.stringify({
+        ref: `refs/heads/${fixtureBranch}`,
+        sha: defaultBranchRef.object.sha,
+      }),
     },
+    [201],
+  );
+}
+
+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;
+
+  await githubRequest(
+    `/repos/${owner}/${name}/contents/${encodedPath}`,
     {
-      id: "email-verification",
-      title: "User receives verification email",
-      gateFile: "./gates/email-verification.gate.ts",
-      dependsOn: ["user-signup"],
-      progress: ["email_sent", "verification_link_valid"],
+      method: "PUT",
+      body: JSON.stringify({
+        message,
+        branch: fixtureBranch,
+        content: Buffer.from(content, "utf8").toString("base64"),
+        sha,
+      }),
     },
-  ] as const, // keep story IDs as literal types
-});
-
-// Make it executable
-if (import.meta.main) {
-  const { runPrd } = await import("gateproof/prd");
-  const result = await runPrd(prd);
-  if (!result.success) {
-    if (result.failedStory) console.error(`Failed at: ${result.failedStory.id}`);
-    process.exit(1);
-  }
-  process.exit(0);
+    [200, 201],
+  );
 }
-```
-
-Each story references a gate file. The gate file uses gateproof's API:
-
-```typescript
-// gates/user-signup.gate.ts
-import { Gate, Act, Assert } from "gateproof";
-import { CloudflareProvider } from "gateproof/cloudflare";
 
-export async function run() {
-  const provider = CloudflareProvider({
-    accountId: process.env.CLOUDFLARE_ACCOUNT_ID!,
-    apiToken: process.env.CLOUDFLARE_API_TOKEN!,
+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,
+    },
   });
 
-  const result = await Gate.run({
-    name: "user-signup",
-    observe: provider.observe({ backend: "analytics", dataset: "worker_logs" }),
-    act: [Act.browser({ url: "https://app.example.com/signup" })],
-    assert: [
-      Assert.noErrors(),
-      Assert.hasAction("user_created"),
-    ],
-  });
+  if (existing) {
+    await githubRequest(
+      `/repos/${owner}/${name}/hooks/${existing.id}`,
+      {
+        method: "PATCH",
+        body,
+      },
+      [200],
+    );
+    return;
+  }
 
-  return { status: result.status };
+  await githubRequest(
+    `/repos/${owner}/${name}/hooks`,
+    {
+      method: "POST",
+      body,
+    },
+    [201],
+  );
 }
-```
 
-**gateproof does not own your PRD’s intent or state.** If you choose to use `gateproof/prd`, your PRD must match a small capsule shape (`stories[]` with `id/title/gateFile/dependsOn?/progress?`). The optional `progress` list is for your own tracking (or agent guidance); gateproof does not interpret or mutate it. Otherwise, orchestrate gates however you want — gateproof only cares about executing gate files.
+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);
+}
 
-Stories execute in dependency order. The runner stops on first failure. Progress is not declared. It is proven.
+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;
+    }
+  }
 
-## How it works
+  await createBucket(api, bucketName, { locationHint });
+  return { accountId, apiToken };
+}
 
-The PRD defines stories. Stories reference gate files. Gate files use gateproof's API. Gates can be enforced in CI before merge/deploy.
+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),
+      }
+    : {}),
+});
 
-**The sequence:** PRD story → gate file → gate execution → story marked "done" only when gate passes.
+export const cacheBucket = await R2Bucket("cinder-cache", {
+  empty: false,
+});
 
-**For agent iterations:** PRD → gate fails → agent fixes → gate re-runs → loop until pass.
+export const runnerState = await KVNamespace("cinder-runner-state");
 
-Run your PRD:
+export const runnerPool = await DurableObjectNamespace("RunnerPool", {
+  className: "RunnerPool",
+  sqlite: true,
+});
 
-```bash
-bun run prd.ts
-```
+export const jobQueue = await DurableObjectNamespace("JobQueue", {
+  className: "JobQueue",
+  sqlite: true,
+});
 
-Run agent iteration loop:
+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),
+  },
+});
 
-```bash
-bash patterns/prd/agent-iteration-loop.sh
-```
+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,
+  },
+});
 
-## Hardening `prd.ts` (recommended)
+await app.finalize();
+await syncFixtureRepository(`${orchestrator.url}/webhook/github`);
 
-Treat `prd.ts` like code: typecheck + validate before push + enforce in CI.
+const runtimeDirectory = new URL("./.gateproof/", import.meta.url);
+const runtimeFile = new URL("./.gateproof/runtime.json", import.meta.url);
 
-- **Validate PRD**:
+await mkdir(runtimeDirectory, { recursive: true });
 
-```bash
-bun run prd:validate
+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}`);
 ```
 
-- **Pre-push (default for everyone on your team)**: add to your `prepush` script (Husky calls it).
+### plan.ts
+
+```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";
+
+type RuntimeState = {
+  orchestratorName?: string;
+  orchestratorUrl?: string;
+  cacheWorkerUrl?: string;
+  fixtureRepo?: string;
+  fixtureBranch?: string;
+  fixtureWorkflow?: string;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
 
-```json
-{
-  "scripts": {
-    "prepush": "bun run typecheck && bun run prd:validate && bun test"
+function readOptionalEnv(name: string): string | undefined {
+  const value = process.env[name];
+  if (typeof value !== "string") {
+    return undefined;
   }
-}
-```
 
-- **CI**: run the validator before running PRD/tests.
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
 
-```yaml
-- name: Validate PRD
-  run: bun run prd:validate
-```
+function loadRuntimeState(): RuntimeState | null {
+  const runtimeFile = new URL("./.gateproof/runtime.json", import.meta.url);
 
-- **Monorepo**: validate any PRD file by path.
+  if (!existsSync(runtimeFile)) {
+    return null;
+  }
 
-```bash
-bun run scripts/prd-validate.ts packages/api/prd.ts
-```
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(runtimeFile, "utf8"));
+    if (!isRecord(parsed)) {
+      return null;
+    }
+
+    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;
+  }
+}
 
-## Design notes
+function resolveLocalRunnerId(): string {
+  try {
+    const hostname = readFileSync("/etc/hostname", "utf8").trim();
+    return `cinder-${hostname || "unknown"}`;
+  } catch {
+    return "cinder-unknown";
+  }
+}
 
-- [Effect and Schema: Gateproof's Foundation](docs/effect-and-schema.md)
+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;
+  }
+}
 
-## Writing good gates (agent-first)
+async function ensureLocalHarness(): Promise<void> {
+  if (await canReachLocalHarness()) {
+    return;
+  }
 
-Gates can fail loudly. They can also pass on silence if you write weak assertions.
+  managedHarness = Bun.spawn({
+    cmd: ["bun", "harness.ts"],
+    cwd: process.cwd(),
+    stdout: "inherit",
+    stderr: "inherit",
+  });
 
-- **Always assert at least one positive signal**: `Assert.hasAction(...)` and/or `Assert.hasStage(...)`. If your backend can be silent, add an explicit “evidence must exist” custom assertion.
-- **Don’t rely on absence-only checks**: `Assert.noErrors()` alone can pass if you collect no logs.
-- **Treat observability as part of the system**: your confidence is bounded by what you can observe.
+  const deadline = Date.now() + 5_000;
+  while (Date.now() < deadline) {
+    if (await canReachLocalHarness()) {
+      return;
+    }
 
-## Limits / Non-goals
+    await Bun.sleep(100);
+  }
 
-- **Not a planner or orchestrator**: gateproof executes gates; your PRD (or CI) decides what to run and in what context.
-- **Not a truth oracle**: if your backend drops logs, a gate can be wrong. Gateproof can’t fix missing telemetry.
-- **Enforcement is external**: gateproof returns results; CI/CD decides whether to block merge/deploy.
+  throw new Error("cinder proof harness did not start on 127.0.0.1:9000");
+}
 
-## Common objections (and answers)
+function stopManagedHarness(): void {
+  if (!managedHarness) {
+    return;
+  }
 
-- **"Isn't this just E2E tests?"** Similar goal, different anchor. Gates are evidence-first (logs/telemetry + explicit assertions), not DOM-only. The contract is: observe → act → assert → evidence.
+  managedHarness.kill();
+  managedHarness = null;
+}
 
-- **"What about flaky telemetry?"** Gates don't fix missing telemetry. They make the dependency explicit. If your backend drops logs, a gate can be wrong — but you'll know immediately, not in production.
+function stopManagedAgent(): void {
+  if (!existsSync(agentPidPath)) {
+    return;
+  }
 
-- **"Isn't this overhead?"** It can be. The pitch isn't "gate everything." It's "gate the few transitions that are expensive to get wrong." Start with one critical path.
+  try {
+    const pid = Number.parseInt(readFileSync(agentPidPath, "utf8").trim(), 10);
+    if (Number.isFinite(pid)) {
+      process.kill(pid);
+    }
+  } catch {
+    // Ignore stale proof agent state.
+  }
 
-- **"Will this lock us in?"** Gates are just TypeScript files. If you stop using gateproof, you keep the scripts and the intent. No vendor lock-in.
+  try {
+    rmSync(agentPidPath, { force: true });
+  } catch {
+    // Ignore pidfile cleanup failures during shutdown.
+  }
+}
 
-## Quick Start
+async function ensureColdBuildBaseline(): Promise<void> {
+  if (readOptionalEnv("COLD_BUILD_MS")) {
+    return;
+  }
 
-The API is minimal: three concepts (Gate, Act, Assert). Here's a gate:
+  if (!testRepo) {
+    return;
+  }
 
-```typescript
-import { Gate, Act, Assert } from "gateproof";
-import { CloudflareProvider } from "gateproof/cloudflare";
+  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.
+  }
+}
 
-const provider = CloudflareProvider({
-  accountId: process.env.CLOUDFLARE_ACCOUNT_ID!,
-  apiToken: process.env.CLOUDFLARE_API_TOKEN!,
-});
+await ensureColdBuildBaseline();
 
-const result = await Gate.run({
-  name: "api-health-check",
-  observe: provider.observe({ backend: "analytics", dataset: "worker_logs" }),
-  act: [Act.browser({ url: "https://my-worker.workers.dev" })],
-  assert: [Assert.noErrors(), Assert.hasAction("request_received")],
+const workerLogs = Cloudflare.observe({
+  accountId: readOptionalEnv("CLOUDFLARE_ACCOUNT_ID") ?? "",
+  apiToken: readOptionalEnv("CLOUDFLARE_API_TOKEN") ?? "",
+  workerName,
+  sinceMs: 120_000,
+  pollInterval: 1_000,
 });
 
-if (result.status !== "success") process.exit(1);
-```
-
-This gate is a story verification. The PRD points at it.
+if (!process.env.CINDER_BASE_URL && baseUrl) {
+  process.env.CINDER_BASE_URL = baseUrl;
+}
 
-## Core API
+if (!process.env.CINDER_WORKER_NAME && workerName) {
+  process.env.CINDER_WORKER_NAME = workerName;
+}
 
-### Gate.run(spec)
-Run a gate. Returns a result with status, logs, and evidence.
-`spec.name` is optional metadata for labeling a gate.
+if (!process.env.CINDER_FIXTURE_REPO && fixtureRepo) {
+  process.env.CINDER_FIXTURE_REPO = fixtureRepo;
+}
 
-### Actions
-```typescript
-Act.exec("command")              // Run shell command
-Act.browser({ url, headless? })  // Browser automation (needs playwright)
-Act.wait(ms)                     // Sleep
-Act.deploy({ worker })           // Deploy marker
-```
+if (!process.env.CINDER_FIXTURE_BRANCH && fixtureBranch) {
+  process.env.CINDER_FIXTURE_BRANCH = fixtureBranch;
+}
 
-### Assertions
-```typescript
-Assert.noErrors()                // No error logs
-Assert.hasAction("name")         // Action was logged
-Assert.hasStage("worker")        // Stage was seen
-Assert.custom("name", fn)        // Custom: (logs) => boolean
-```
+if (!process.env.CINDER_FIXTURE_WORKFLOW && fixtureWorkflow) {
+  process.env.CINDER_FIXTURE_WORKFLOW = fixtureWorkflow;
+}
 
-### Result
-```typescript
-{
-  status: "success" | "failed" | "timeout",
-  durationMs: number,
-  logs: Log[],
-  evidence: {
-    requestIds: string[],
-    stagesSeen: string[],
-    actionsSeen: string[],
-    errorTags: string[]
+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.",
+    },
   },
-  error?: Error
+  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");
 }
-```
-
-## PRD Runner
-
-gateproof provides a PRD runner that executes stories in dependency order:
-
-```typescript
-import { definePrd, runPrd } from "gateproof/prd";
-
-const prd = definePrd({
-  stories: [
+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",
     {
-      id: "story-1",
-      title: "First story",
-      gateFile: "./gates/story-1.gate.ts",
+      method: "POST",
+      headers,
     },
-    {
-      id: "story-2",
-      title: "Second story",
-      gateFile: "./gates/story-2.gate.ts",
-      dependsOn: ["story-1"],
+  );
+  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,
     },
-  ] as const, // keep story IDs as literal types
-});
-
-const result = await runPrd(prd);
-if (!result.success) {
-  console.error(`Failed at: ${result.failedStory?.id}`);
+  },
+);
+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;
+
+export default scope;
+
+if (import.meta.main) {
+  stopManagedAgent();
+
+  if (testRepo) {
+    await ensureLocalHarness();
+  }
 
-The runner:
-- Validates dependencies (unknown IDs and cycles throw)
-- Topologically sorts stories by `dependsOn`
-- Executes gates in order
-- **Stops on first failure**
+  await ensureColdBuildBaseline();
 
-## Plug Your Backend
+  try {
+    const result = await Effect.runPromise(
+      Plan.runLoop(scope.plan, {
+        maxIterations: scope.plan.loop?.maxIterations,
+      }),
+    );
 
-gateproof works with any observability backend. Just implement the `Backend` interface:
+    console.log(JSON.stringify(result, null, 2));
 
-```typescript
-interface Backend {
-  start(): Effect.Effect<LogStream, ObservabilityError>;
-  stop(): Effect.Effect<void, ObservabilityError>;
+    if (result.status !== "pass") {
+      process.exitCode = 1;
+    }
+  } finally {
+    stopManagedAgent();
+    stopManagedHarness();
+  }
+
+  process.exit(process.exitCode ?? 0);
 }
 ```
 
-See `patterns/` for examples including:
-- Cloudflare Analytics Engine
-- Cloudflare Workers Logs API
-- CLI Stream (local dev)
-- Custom backends
+Status: Historical artifacts are available locally
 
-## Cloudflare Backends
+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.
 
-```typescript
-const provider = CloudflareProvider({ accountId, apiToken });
+## Roadmap
 
-// Analytics Engine
-provider.observe({ backend: "analytics", dataset: "worker_logs" })
+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.
 
-// Workers Logs API
-provider.observe({ backend: "workers-logs", workerName: "my-worker" })
+- 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.
 
-// CLI Stream (local dev)
-provider.observe({ backend: "cli-stream", workerName: "my-worker" })
-```
+## How To
 
-## Examples
+Task: Run one complete gate from one file.
 
-See `patterns/` for complete examples:
-- `patterns/basic/` - Basic usage patterns
-- `patterns/cloudflare/` - Cloudflare-specific patterns
-- `patterns/ci-cd/` - CI/CD integration
-- `patterns/advanced/` - Advanced patterns
-- `patterns/prd/` - PRD-as-code + agent iteration loop examples
-- `patterns/agent-first/` - Spec interview → PRD stories (agent-first)
-- `examples/hello-world-agent/` - Minimal agent with 5 tools + end-to-end gates
+Done when: The endpoint returns 200 and the body contains hello world.
 
-Run the hello-world agent example (requires `OPENCODE_ZEN_API_KEY` and network access to `opencode.ai`):
+Run it:
 
 ```bash
-export OPENCODE_ZEN_API_KEY="your_key_here"
-bun run examples/hello-world-agent/prd.ts
+bun run example:hello-world:worker
+bun run alchemy.run.ts
+bun run plan.ts
 ```
 
-## CI/CD
+## Breaking Changes In 0.4.0
 
-gateproof enforces gates in CI/CD. See `patterns/ci-cd/github-actions.ts` for examples.
+- `Prd.*` is gone
+- `Claim.*` is gone
+- `plan.ts` is the canonical entrypoint
+- `Plan.*` replaces the old front door
 
-Run your PRD in CI:
+## Reference
 
-```yaml
-- name: Run PRD
-  run: bun run prd.ts
-```
+Files:
+- `examples/hello-world/plan.ts`
+- `alchemy.run.ts`
+- `plan.ts`
+
+Canonical gates:
+- GET / returns hello world
 
-## Requirements
+Loop:
+- `maxIterations: 1`
+- `stopOnFailure: true`
 
-- Node.js 18+ or Bun
-- `playwright` (optional, for Act.browser)
-- Cloudflare credentials (for CloudflareProvider, or bring your own backend)
+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.