fix: retarget Cursor agents at external Proof by tonyketcham · Pull Request #242 · FlatbreadLabs/flatbread

tonyketcham · 2026-08-12T17:49:26Z

Delete the proof-runtime-skeptic agent (runtime no longer lives here).
Point the code-review orchestrator, architecture planner, and major-migration
skill at the external @flatbread/proof CLI. Keep Flatbread-specific DAG
templates under .cursor/dags/flatbread/ with a short README for how to run them.

Co-authored-by: Cursor cursoragent@cursor.com

Depends-On: #241

tonyketcham · 2026-08-12T17:49:30Z

This pull request is part of a Mergify stack:

#	Pull Request	Link
1	release: prepare Flatbread 1.0	#236
2	fix: remove stale release dependencies	#237
3	fix: harden stable package payloads	#238
4	fix: make core declarations portable	#239
5	docs: record upstream release limits	#240
6	chore: move proof to its own repository	#241
7	fix: retarget Cursor agents at external Proof	#242	👈
8	feat: brand agent memory as Proof and the runner as Oven	#244

Delete the proof-runtime-skeptic agent (runtime no longer lives here). Point the code-review orchestrator, architecture planner, and major-migration skill at the external @flatbread/proof CLI. Keep Flatbread-specific DAG templates under .cursor/dags/flatbread/ with a short README for how to run them. Co-authored-by: Cursor <cursoragent@cursor.com> Change-Id: Id40e6118c97414ccc958e4997e52c000ed639291

tonyketcham · 2026-08-12T18:16:37Z

Revision history

#	Type	Changes	Reason	Date
1	initial	`173e300`		2026-08-12 18:16 UTC
2	rebase	`173e300 → 8840cc9` (rebase only)		2026-08-12 18:16 UTC

cursor

Stale comment

Review verdict

BLOCK — any BLOCKER → BLOCK. Two consensus blockers stop the contributor path: the orchestrator pnpm exec proof --help preflight always exits 1 (--dag is required), and .cursor/dags/README.md run examples omit required --canvas-path / --canvas. Consensus HIGH on the registry-only install (@flatbread/proof is npm 404 with no concrete git/file recipe) would independently force REQUEST_CHANGES.

PR range reviewed: 2144c6a...8840cc9 (9 files; not dependency-only). Perspectives: proof-retarget-consistency (MED), docs-and-positioning (LOW), dx-and-examples (LOW); judge HIGH (grok-4.5 effort high / composer-2.5).

Chunk-bound feedback (priority)

BLOCKER .cursor/agents/flatbread-code-review-orchestrator.md:99-102 — pnpm exec proof --help fatals with --dag <path> is required. Replace with a bin-resolution check or a real --init-only --dag … --canvas-path … smoke.

BLOCKER .cursor/dags/README.md — example commands omit --canvas / --canvas-path (CLI exits immediately); primary install is registry-only (npm 404); layout says “21 tasks” while --init-only reports 22 tasks / 8 ranks (pause is its own rank).

HIGH orchestrator install prose (pnpm add -Dw @flatbread/proof) — same registry dead-end; give a concrete git/file recipe until publish.

HIGH .cursor/skills/flatbread-major-migration/SKILL.md:67 — claims “21 tasks across 7 ranks” / what --init-only produces; live shape is 22/8, and the cited flatbread-flow-agentic-workflows.md still points at removed .cursor/skills/proof/examples/ paths.

Coverage plan

none — docs/agent/DAG-only PR.

Reviewer scoreboard

proof-retarget-consistency: 6 findings, 0 coverage gaps, signal:HIGH

dx-and-examples: 6 findings, 0 coverage gaps, signal:HIGH

docs-and-positioning: 3 findings, 0 coverage gaps, signal:MED

Suggested follow-ups

Retarget out-of-diff docs still citing packages/proof / .cursor/skills/proof/ (flatbread-flow-agentic-workflows.md, research docs).

Confirm npm publish timing for @flatbread/proof before demoting the git install path.

Validate DAG JSON model ids against a live Cursor model list.

_{Sent by Cursor Automation: Flatbread PR Review}

cursor · 2026-08-12T18:24:09Z

+pnpm exec proof --help >/dev/null || {
+  echo "Install @flatbread/proof so pnpm exec proof resolves (pnpm add -Dw @flatbread/proof)."
+  exit 1
+}


BLOCKER (consensus: proof-retarget-consistency, dx-and-examples)

pnpm exec proof --help is not a valid smoke. Current Proof parseArgs requires --dag, so this preflight exits 1 even when the CLI is installed correctly (Error: --dag <path> is required).

Minimal fix: Drop --help. Check that the proof bin resolves, or run a real smoke such as pnpm exec proof --init-only --dag <path> --canvas-path <path>.

cursor · 2026-08-12T18:24:09Z


 ### 4. Run the DAG

+Proof is an external package (`@flatbread/proof` from https://github.com/FlatbreadLabs/proof). It is not a workspace package in this monorepo. Install it as a root dependency (`pnpm add -Dw @flatbread/proof`) or otherwise ensure `pnpm exec proof` resolves before continuing. Also set `CURSOR_API_KEY` (or load it from `.env`).


HIGH (proof-retarget-consistency)

pnpm add -Dw @flatbread/proof 404s on the public npm registry today. Fresh contributors hit install failure, then the broken --help guard.

Minimal fix: Lead with a concrete git/file install recipe until the package is published; keep registry as a future path.

cursor · 2026-08-12T18:24:09Z

+```bash
+pnpm exec proof --init-only --dag .cursor/dags/flatbread/dag-schema-migration.json
+pnpm exec proof --dag .cursor/dags/flatbread/dag-schema-migration.json


BLOCKER (consensus: proof-retarget-consistency, dx-and-examples)

These copy-paste commands omit required --canvas-path / --canvas. Verified: Proof exits with Provide either --canvas-path <abs-path> or --canvas <name>.

Minimal fix: Add --canvas <name> (or --canvas-path) to both example lines and document it as required.

cursor · 2026-08-12T18:24:09Z

+   ```bash
+   pnpm add -Dw @flatbread/proof
+   ```
+
+   Or install from the Proof repository if the package is not on the registry
+   you use yet.


HIGH (consensus: proof-retarget-consistency, dx-and-examples)

Primary install is registry-only. npm view @flatbread/proof is 404; the “or install from the Proof repository” sentence is not a worked command.

Minimal fix: Put a concrete git/file recipe first (or demote registry until publish).

cursor · 2026-08-12T18:24:09Z

+## Layout
+
+- `flatbread/` — workspace orchestration templates
+  - `dag-schema-migration.json` — schema-breaking migration (21 tasks)


MED (topology drift)

Layout says “21 tasks”. Live pnpm exec proof --init-only on this file reports 22 tasks across 8 ranks (the kind: pause node is counted and occupies its own rank).

Minimal fix: Say “22 tasks (21 + 1 pause) / 8 ranks” (or match whatever wording you choose in the major-migration skill).

cursor · 2026-08-12T18:24:09Z

 ## Default DAG Shape

-When this skill is run under `proof` (the `@flatbread/proof` package; legacy alias `dag-task-runner`), use the topology in `flatbread-flow-agentic-workflows.md` ("DAG Topology" section). The canonical schema-migration shape — express the DAG via `depends_on` only; the runner computes ranks via Kahn topo-sort. The shape below is what `pnpm exec proof --init-only` produces for the starter template (21 tasks across 7 ranks):
+When this skill is run under the external Proof CLI (`@flatbread/proof` from https://github.com/FlatbreadLabs/proof), use the topology in `flatbread-flow-agentic-workflows.md` ("DAG Topology" section). The canonical schema-migration shape — express the DAG via `depends_on` only; the runner computes ranks via Kahn topo-sort. The shape below is what `pnpm exec proof --init-only` produces for the starter template (21 tasks across 7 ranks):


HIGH (consensus: proof-retarget-consistency, docs-and-positioning, dx-and-examples)

This line asserts the starter is “21 tasks across 7 ranks” and “what pnpm exec proof --init-only produces.” Live --init-only on .cursor/dags/flatbread/dag-schema-migration.json reports 22 tasks / 8 ranks (pause is its own rank). The cited flatbread-flow-agentic-workflows.md “DAG Topology” section still points at removed .cursor/skills/proof/examples/ paths.

Minimal fix: Refresh the task/rank counts and diagram for the pause rank; prefer .cursor/dags/README.md / the inlined rank block over the stale workflows cite.

cursor

Review verdict

BLOCK — the orchestrator install gate (pnpm exec proof --help) always exits 1 with --dag <path> is required even when Proof is installed, so the probe cannot detect a working binary. Consensus HIGH defects also block a clean first-run path: non-resolving pnpm add -Dw @flatbread/proof, README proof commands missing required --canvas-path, stale 21-task/7-rank topology (live template is 22 tasks / 8 ranks), and DAG prompts that still require HTTPS/5058 though flatbread start is HTTP-only on 5057.

Chunk-bound feedback (priority)

BLOCKER .cursor/agents/flatbread-code-review-orchestrator.md:99-102 — replace --help probe with a resolve check that does not require invalid CLI args.
HIGH .cursor/agents/flatbread-code-review-orchestrator.md:94-95 + .cursor/dags/README.md — document an install that actually resolves (npm 404 / public GitHub fetch fails from this environment).
HIGH .cursor/dags/README.md run block — add --canvas-path/--canvas (CLI fatals without it).
HIGH skill + README topology counts — align to proof --init-only (22 / 8), accounting for kind: pause.
HIGH dag-schema-migration.json / dag-codegen-change.json — drop 5058/HTTPS smoke checks (or gate on setup-https.js); fix wrong index.ts:128-135 cites.

Coverage plan

Name a concrete command/artifact for verify-schema-snap.
Either remove HTTPS/5058 verify steps or document the extra setup agents need.
Retarget or stop citing flatbread-flow-agentic-workflows.md until its in-monorepo Proof paths are updated (out of PR range but skill-linked).

Reviewer scoreboard

Perspective	Signal
proof-retarget-contracts (HIGH / grok-4.5)	Sole BLOCKER on `--help` gate; install + topology
docs-and-positioning (LOW / composer-2.5)	HTTPS/5058, wrong CLI cites, missing `arguments.ts`, skill count
dx-and-examples (LOW / composer-2.5)	Missing `--canvas-path`; verify-schema-snap gap; browser depends_on

Models: Cursor Grok 4.5 High / Composer 2.5. Not a dependency-only PR — full adversarial DAG ran.

_{Sent by Cursor Automation: Flatbread PR Review}

cursor · 2026-08-12T18:24:15Z

+pnpm exec proof --help >/dev/null || {
+  echo "Install @flatbread/proof so pnpm exec proof resolves (pnpm add -Dw @flatbread/proof)."
+  exit 1
+}


BLOCKER — pnpm exec proof --help always fails with --dag <path> is required when the binary is present, so this gate cannot tell “missing Proof” from “installed”. Probe with a resolve check that does not need fake --help success (e.g. command -v / package resolve, or a known-valid --init-only noop with --dag + --canvas-path).

cursor · 2026-08-12T18:24:15Z


 ### 4. Run the DAG

+Proof is an external package (`@flatbread/proof` from https://github.com/FlatbreadLabs/proof). It is not a workspace package in this monorepo. Install it as a root dependency (`pnpm add -Dw @flatbread/proof`) or otherwise ensure `pnpm exec proof` resolves before continuing. Also set `CURSOR_API_KEY` (or load it from `.env`).


HIGH — pnpm add -Dw @flatbread/proof 404s on the public npm registry from this environment, and https://github.com/FlatbreadLabs/proof is not publicly fetchable here. Give an install recipe that actually resolves (concrete git/file: URL, or “Proof already on PATH / already linked”).

cursor · 2026-08-12T18:24:15Z

+pnpm exec proof --init-only --dag .cursor/dags/flatbread/dag-schema-migration.json
+pnpm exec proof --dag .cursor/dags/flatbread/dag-schema-migration.json


HIGH (consensus) — copy-paste fails: Proof requires --canvas-path or --canvas (fatal without it). Mirror the orchestrator pattern (CANVAS_PATH=… + --canvas-path "$CANVAS_PATH") on both commands. Also align “21 tasks” on line 11 with proof --init-only (22 tasks / 8 ranks).

cursor · 2026-08-12T18:24:15Z

+1. Install Proof so `pnpm exec proof` resolves from this repo root, for example:
+
+   ```bash
+   pnpm add -Dw @flatbread/proof


HIGH — primary install pnpm add -Dw @flatbread/proof does not resolve on public npm. The fallback (“install from the Proof repository”) needs a concrete, working command, not a vague hint.

cursor · 2026-08-12T18:24:15Z

 ## Default DAG Shape

-When this skill is run under `proof` (the `@flatbread/proof` package; legacy alias `dag-task-runner`), use the topology in `flatbread-flow-agentic-workflows.md` ("DAG Topology" section). The canonical schema-migration shape — express the DAG via `depends_on` only; the runner computes ranks via Kahn topo-sort. The shape below is what `pnpm exec proof --init-only` produces for the starter template (21 tasks across 7 ranks):
+When this skill is run under the external Proof CLI (`@flatbread/proof` from https://github.com/FlatbreadLabs/proof), use the topology in `flatbread-flow-agentic-workflows.md` ("DAG Topology" section). The canonical schema-migration shape — express the DAG via `depends_on` only; the runner computes ranks via Kahn topo-sort. The shape below is what `pnpm exec proof --init-only` produces for the starter template (21 tasks across 7 ranks):


HIGH (consensus) — claims “21 tasks across 7 ranks”; pnpm exec proof --init-only --dag .cursor/dags/flatbread/dag-schema-migration.json reports 22 tasks across 8 rank(s) because wait-contract-approval (kind: pause) adds a rank. Align the text (and the rank diagram below) or document pause accounting. Also: flatbread-flow-agentic-workflows.md still cites in-monorepo Proof paths — retarget that doc or stop treating it as canonical here.

cursor · 2026-08-12T18:24:15Z

+      "id": "verify-cli",
+      "depends_on": ["impl-cli", "verify-codegen"],
+      "complexity": "MED",
+      "subtask_prompt": "You are acting as `flatbread-adversarial-reviewer`. Follow its responsibilities and output schema. Output must lead with these `##` headings verbatim: `## Blockers`, `## High-severity findings`, `## Medium-severity findings`, `## Low-severity findings`, `## Residual risk`, `## Recommended next DAG tasks`.\n\nSmoke-test `pnpm --filter nextjs dev` and the `/graphql` endpoint on port `5057` (HTTP) and `5058` (HTTPS). This task is the sole port-5057 occupant of its rank — no other task may bind that port concurrently. Stop the server before exit so `browser-verify` can take the port. If anything fails, populate `## Recommended next DAG tasks` with `id` + one-line subtask_prompt sketches."


HIGH — instructs HTTPS smoke on port 5058, but flatbread start is HTTP-only on 5057 and --https is an explicit no-op (packages/flatbread/src/cli/index.ts:46-48). Drop the 5058 check or gate it on setup-https.js. Same false contract appears in diag-cli / browser-verify prompts in this file (wrong index.ts:128-135 cite — port is at :44).

cursor · 2026-08-12T18:24:15Z

+      "id": "browser-verify",
+      "depends_on": ["verify-example-build"],
+      "complexity": "MED",
+      "subtask_prompt": "You are acting as `flatbread-browser-verifier`. Follow its responsibilities and output schema. Output must lead with these `##` headings verbatim: `## Commands run`, `## Routes checked`, `## Observed behavior`, `## Mismatches`, `## Screenshots`, `## Residual risk`.\n\nRun `pnpm browser:doctor` first to fail fast if the browser CLI is unavailable. Start the example dev server in the background: `pnpm --filter nextjs dev` (binds port `5057` HTTP, `5058` HTTPS per `packages/flatbread/src/cli/index.ts:128-135`); the upstream `verify-example-build` task already finished and freed the port. Wait for the server to come up before driving `pnpm exec agent-browser`. Verify documented queries and the rendered example pages still match the README. Tear the dev server down before completing the task. If the browser CLI is unavailable, your `## Residual risk` MUST lead with `BROWSER UNAVAILABLE`."


HIGH — browser-verify repeats HTTPS/5058 and index.ts:128-135. Default nextjs/flatbread loop is HTTP 5057 only. Drop 5058 or require setup-https.js. Optional: also depend on verify-codegen-tests so the browser gate cannot pass while codegen tests fail.

cursor · 2026-08-12T18:24:15Z

+      "id": "diag-example-paths",
+      "depends_on": [],
+      "complexity": "LOW",
+      "subtask_prompt": "You are acting as `flatbread-architecture-planner`. Follow its responsibilities and output schema. Output must lead with these `##` headings verbatim: `## Current contract`, `## Proposed contract`, `## Migration impact`, `## Validation plan`, `## Human checkpoints`. Do not edit files.\n\nWalk `examples/nextjs` end-to-end and capture the actual first-success path a developer sees: setup commands, codegen invocation (note `package.json:7` is `--watch`; the docs should point users at the appropriate command), dev command, port (`5057` HTTP, `5058` HTTPS sibling), sample query, sample edit. Compare against what the docs claim."


MED — diag-example-paths documents a 5058 HTTPS sibling the current CLI does not serve. Document HTTP-only on 5057.

cursor

CI Root Cause

Status: third-party-failure

Failing checks:

integration-sveltekit (20.x, windows-latest): sharp@0.31.3 install failed with socket hang up while downloading libvips-8.13.3-win32-x64.tar.br from GitHub Releases

Evidence:

Job 94215237418 failed in pnpm install --frozen-lockfile before any build/test steps.
Log: sharp: Downloading https://github.com/lovell/sharp-libvips/releases/download/v8.13.3/libvips-8.13.3-win32-x64.tar.br → sharp: Installation error: socket hang up → ELIFECYCLE exit 1.
Same SHA 8840cc9 has green siblings, including integration-sveltekit (22.x, windows-latest), integration-sveltekit (20.x, ubuntu-latest|macos-latest), and integration-nextjs (20.x, windows-latest).
This matches known GitHub Releases / sharp-libvips fetch flakes on hosted runners; it is not introduced by the Proof retarget diff.

Resolution steps:

Re-run the failed integration-sveltekit (20.x, windows-latest) job (or the whole Pipeline check suite) on SHA 8840cc9.
If the same libvips download hang persists across retries, check GitHub Releases / Actions egress health and sharp’s install docs; do not change this branch for this signature alone.
No branch code change is warranted while sibling OS/Node cells stay green and the failure remains confined to native binary download.

No code changes were made because this failure is not caused by the branch.

_{Sent by Cursor Automation: Flatbread - Fix CI}

tonyketcham mentioned this pull request Aug 12, 2026

refactor: rename Effort Graph paths to Proof #243

Closed

tonyketcham force-pushed the stack/tonyketcham/toeknee/extract-proof-repo/move-proof-own-repo--915065dc branch from f7e8d82 to 2144c6a Compare August 12, 2026 18:16

tonyketcham force-pushed the stack/tonyketcham/toeknee/extract-proof-repo/retarget-cursor-agents-external-proof--d40e6118 branch from 173e300 to 8840cc9 Compare August 12, 2026 18:16

cursor Bot reviewed Aug 12, 2026

View reviewed changes

Base automatically changed from stack/tonyketcham/toeknee/extract-proof-repo/move-proof-own-repo--915065dc to main August 12, 2026 19:25

tonyketcham merged commit 431b50a into main Aug 12, 2026
38 of 57 checks passed

tonyketcham deleted the stack/tonyketcham/toeknee/extract-proof-repo/retarget-cursor-agents-external-proof--d40e6118 branch August 12, 2026 19:25


		### 4. Run the DAG

		Proof is an external package (`@flatbread/proof` from https://github.com/FlatbreadLabs/proof). It is not a workspace package in this monorepo. Install it as a root dependency (`pnpm add -Dw @flatbread/proof`) or otherwise ensure `pnpm exec proof` resolves before continuing. Also set `CURSOR_API_KEY` (or load it from `.env`).

		pnpm exec proof --init-only --dag .cursor/dags/flatbread/dag-schema-migration.json
		pnpm exec proof --dag .cursor/dags/flatbread/dag-schema-migration.json

Uh oh!

Uh oh!

Conversation

tonyketcham commented Aug 12, 2026

Uh oh!

tonyketcham commented Aug 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tonyketcham commented Aug 12, 2026

Revision history

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Review verdict

Chunk-bound feedback (priority)

Coverage plan

Reviewer scoreboard

Suggested follow-ups

Uh oh!

cursor Bot Aug 12, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Aug 12, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Aug 12, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Aug 12, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Aug 12, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Aug 12, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Review verdict

Chunk-bound feedback (priority)

Coverage plan

Reviewer scoreboard

Uh oh!

cursor Bot Aug 12, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Aug 12, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Aug 12, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Aug 12, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Aug 12, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Aug 12, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Aug 12, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Aug 12, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

CI Root Cause

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

tonyketcham commented Aug 12, 2026 •

edited

Loading

cursor Bot left a comment •

edited

Loading