release: prepare Flatbread 1.0 by tonyketcham · Pull Request #236 · FlatbreadLabs/flatbread

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

Move all public packages to 1.0.0, align package metadata, and add the release license.\n\nLead the public docs with Effort Graph agent memory while keeping static relational content and GraphQL read paths clear. Add concise release notes and record the positioning decision in the Effort Graph.\n\nTest plan: pnpm verify; package tarball and clean-install smoke tests.

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

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

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

Move all public packages to 1.0.0, align package metadata, and add the release license.\n\nLead the public docs with Effort Graph agent memory while keeping static relational content and GraphQL read paths clear. Add concise release notes and record the positioning decision in the Effort Graph.\n\nTest plan: pnpm verify; package tarball and clean-install smoke tests. Change-Id: I3b53d7e244cc251ce9968b3578fabeabcc96298f Co-authored-by: Cursor <cursoragent@cursor.com>

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

Revision history

#	Type	Changes	Reason	Date
1	initial	`2e82c87`		2026-08-12 18:16 UTC
2	content	`2e82c87 → fda484c` (raw)	Fix the release commit by prefixing every Proof CLI command in positioning docs and replacing pre-tag v1.0.0 install literals with and placeholders.	2026-08-12 18:16 UTC

cursor

Stale comment

Review verdict

BLOCK — Multiple consensus BLOCKER findings: @flatbread/proof README and docs/positioning.md document a non-existent Proof agent-memory / flatbread proof * surface while the shipped package and CLI are the DAG runner and Effort Graph (flatbread effort, .flatbread-efforts/). Rule: any BLOCKER → BLOCK.

Blocking findings (priority order)

packages/proof/README.md — Rewritten as Effort Graph–style memory (proofContent(), .flatbread-proof/, flatbread proof *, skills/proof/). @flatbread/proof is a DAG task runner (proof / proof-supervisor); proofContent() and packages/proof/skills/ do not exist. package.json description still correctly says “Bounded DAG task runner.”

docs/positioning.md:17-41 — Lead use case names Proof, .flatbread-proof/, and flatbread proof write|list|…. Shipped memory product is Effort Graph with flatbread effort * and .flatbread-efforts/ (see packages/flatbread/README.md and CLI tests).

Missing Proof skill install tree — README points at packages/proof/skills/proof, release.json, setup.md, and .agents/skills/proof/; none exist. Root skills:sync only covers effort-graph.

What looks fine

Coordinated 1.0.0 bumps + engines.node: ">=20.19" across packages.

@flatbread/core moved to runtime dependencies in config/effort-graph (not blocking).

LICENSE via pnpm pack path is fine; no chase for files:["LICENSE"].

Coverage plan: n/a (no packages/*/src in this release/docs/deps diff).

Minimal fix before 1.0

Restore @flatbread/proof README to DAG-runner docs (entrypoint, --dag, canvas, supervisor).

Rewrite docs/positioning.md lead use case to Effort Graph; link packages/effort-graph/README.md; use flatbread effort * / .flatbread-efforts/.

Align CHANGELOG.md “Docs” bullet with the fixed positioning text.

Perspectives

release-discipline · docs-and-positioning · dx-and-examples · dependency-runtime-surface → judge

Models: grok-4.5 (high) / composer-2.5. Not dependency-only (docs + release metadata + package.json).

_{Sent by Cursor Automation: Flatbread PR Review}

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

+The [Proof](../packages/proof/README.md) is a Flatbread content
+model for what a coding agent works out along the way. An agent records an
+Effort and then writes Issues, Findings, Decisions, Constraints, Risks,
+Citations, and Blobs against it. Each record is a markdown file under
+`.flatbread-proof/`, so it is committed, diffed, reviewed, and reverted like
+source. Writes go through `flatbread proof write`; reads come back as bounded
+digests from `flatbread proof list`, `flatbread proof records`,
+`flatbread proof relations`, `flatbread proof blocking-decisions`, and
+`flatbread proof get`.


BLOCKER (consensus) — Lead use case documents Proof / .flatbread-proof/ / flatbread proof *, but the shipped memory product is Effort Graph (effortGraphContent(), flatbread effort *, .flatbread-efforts/). There is no proof CLI subcommand in packages/flatbread; CLI tests cover effort only.

Minimal fix: Rewrite this section for Effort Graph and link packages/effort-graph/README.md (same story already in packages/flatbread/README.md).

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

+Git-native memory for coding agents. Installing this package gives you three
+things:
+
+- **Record types.** An agent records the work it is doing as an **Effort**,
+  then writes what it learns against that Effort: **Issues**, **Findings**,
+  **Decisions**, **Constraints**, **Risks**, **Citations**, and **Blobs**.
+- **Write operations.** A typed mutation turns into Markdown files on disk, and
+  the writer checks the links between records before it commits them.
+- **A Flatbread content model.** `proofContent()` adds those eight record
+  types to a Flatbread configuration, so the same files come back as a typed
+  graph you can query and page through.


BLOCKER (consensus) — This README describes Git-native agent memory and proofContent(). @flatbread/proof is the DAG task runner (proof / proof-supervisor). proofContent() does not exist in the repo; the real preset is effortGraphContent() in @flatbread/effort-graph. The package description still correctly says “Bounded DAG task runner.”

Minimal fix: Restore DAG-runner documentation; keep memory docs on Effort Graph only.

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

+`flatbread proof bootstrap` reports what is still missing — the config entry
+or either ignore rule. `flatbread proof bootstrap --verify` reports the same
+and exits nonzero when anything is missing, which makes it usable in CI.


BLOCKER (consensus) — Documents flatbread proof bootstrap / --verify. No proof subcommand is registered on the flatbread CLI; bootstrap lives under flatbread effort bootstrap.

Minimal fix: Remove these commands; document real entrypoints (pnpm exec proof, proof-supervisor).

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

+Read [`skills/proof/glossary.md`](./skills/proof/glossary.md) for
+the portable Proof domain model.


BLOCKER (consensus) — Links to ./skills/proof/glossary.md, but packages/proof/skills/ does not exist. The DAG skill lives under .cursor/skills/proof/.

Minimal fix: Point at the real skill path or drop the link until a packaged tree ships.

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

+npx skills add https://github.com/FlatbreadLabs/flatbread/tree/<gitTag>/packages/proof/skills/proof --skill proof
+npm install --save-dev flatbread@<flatbreadVersion>


BLOCKER (consensus) — npx skills add …/packages/proof/skills/proof is a dead GitHub path (packages/proof/skills/ missing). npm install --save-dev flatbread@… also installs the wrong package for a DAG-runner README (@flatbread/proof).

Minimal fix: Document @flatbread/proof install, or retarget skill install to an existing tree (effort-graph owns the packaged skill today).

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

+The tag and version come from `gitTag` and `flatbreadVersion` in
+`skills/proof/release.json`. See `skills/proof/setup.md` for the
+equivalent `pnpm`, `yarn`, and `bun` commands.


BLOCKER (consensus) — Cites skills/proof/release.json and skills/proof/setup.md; neither exists (only packages/effort-graph/skills/effort-graph/ has release.json / setup.md).

Minimal fix: Add a real proof skill tree, or drop version-pin instructions from this README.

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

+
+### Docs
+
+- The READMEs and `docs/positioning.md` now lead with the Effort Graph: an


MED — Docs note claims READMEs and docs/positioning.md lead with the Effort Graph, but docs/positioning.md in this PR still leads with Proof memory / flatbread proof *.

Minimal fix: Fix positioning (preferred), then keep this changelog line accurate.

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


-**GraphQL:** GraphQL is a common way to read Flatbread data. It does not define
-the product. For more detail, see
+**GraphQL:** GraphQL is one read interface over the graph. For more detail, see


MED — This README correctly describes Effort Graph / flatbread effort *, but it points readers at docs/positioning.md, which currently describes Proof memory / flatbread proof *.

Minimal fix: Align positioning with Effort Graph before 1.0 ships.

cursor

Review verdict

BLOCK — Any BLOCKER rule: @flatbread/proof’s npm README and docs/positioning.md document a non-existent Proof memory product (proofContent(), flatbread proof *, .flatbread-proof/, packaged skills/proof/) while the shipped package is a DAG runner and the accepted 1.0 lead is Effort Graph (flatbread effort *, .flatbread-efforts/).

Confirmed against tree: no packages/proof/skills/, no proofContent export, CLI registers only flatbread effort bootstrap, and package.json description correctly says “Bounded DAG task runner…”.

Blocking fixes (priority order)

Rewrite docs/positioning.md lead to Effort Graph (.flatbread-efforts/, flatbread effort *).
Restore packages/proof/README.md to DAG-runner docs matching bins/description/src/.
Delete invented flatbread proof * / skill-install URLs from Proof docs.
Fix CHANGELOG Docs claim so it matches the rewritten positioning lead.

Coverage plan

packages/proof/README.md — negative — after rewrite, assert documented exports/bins/description match package.json and cited skill/install paths exist in the pack tarball or are absent from the README.
docs/positioning.md — positive — smoke that every documented CLI string (flatbread effort …) is registered on the built flatbread CLI.
Optional post-tag smoke — Effort Graph npx skills add succeeds; no Proof skill URL remains unless the tree exists.

Reviewer scoreboard

release-discipline: 5 findings, 0 coverage gaps, signal:HIGH
docs-and-positioning: 9 findings, 0 coverage gaps, signal:HIGH
dependency-runtime-surface: 6 findings, 2 coverage gaps, signal:HIGH
dx-and-examples: 6 findings, 0 coverage gaps, signal:HIGH

Models: grok-4.5 (HIGH) / composer-2.5 (MED/LOW). Not dependency-only (docs/LICENSE/CHANGELOG/READMEs beyond package.json+lockfile).

_{Sent by Cursor Automation: Flatbread PR Review}

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

+## The lead use case: memory for coding agents
+
+The [Proof](../packages/proof/README.md) is a Flatbread content
+model for what a coding agent works out along the way. An agent records an
+Effort and then writes Issues, Findings, Decisions, Constraints, Risks,
+Citations, and Blobs against it. Each record is a markdown file under
+`.flatbread-proof/`, so it is committed, diffed, reviewed, and reverted like
+source. Writes go through `flatbread proof write`; reads come back as bounded
+digests from `flatbread proof list`, `flatbread proof records`,
+`flatbread proof relations`, `flatbread proof blocking-decisions`, and
+`flatbread proof get`.


BLOCKER (consensus: release-discipline, docs-and-positioning, dependency-runtime-surface, dx-and-examples)

Lead use case names Proof and invents flatbread proof write|list|records|relations|blocking-decisions|get under .flatbread-proof/. The accepted 1.0 decision and shipped CLI lead with Effort Graph (.flatbread-efforts/, flatbread effort *). Only flatbread effort bootstrap is registered.

Minimal fix: Rewrite this lead to Effort Graph; link ../packages/effort-graph/README.md. Keep Proof out of the memory lead (workflow/DAG tooling only).

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

+# `@flatbread/proof`
+
+Git-native memory for coding agents. Installing this package gives you three
+things:
+
+- **Record types.** An agent records the work it is doing as an **Effort**,
+  then writes what it learns against that Effort: **Issues**, **Findings**,
+  **Decisions**, **Constraints**, **Risks**, **Citations**, and **Blobs**.
+- **Write operations.** A typed mutation turns into Markdown files on disk, and
+  the writer checks the links between records before it commits them.
+- **A Flatbread content model.** `proofContent()` adds those eight record
+  types to a Flatbread configuration, so the same files come back as a typed
+  graph you can query and page through.


BLOCKER (consensus: all four perspectives)

This npm README describes Git-native agent memory (proofContent(), eight record types, journal/cache). @flatbread/proof does not export proofContent; package.json correctly describes a bounded DAG task runner (proof / proof-supervisor).

Minimal fix: Restore DAG-runner docs (bins, DAG shape, canvas, oracles/loops, artifacts) matching package.json description and src/ / bin/.

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

+`flatbread proof bootstrap` reports what is still missing — the config entry
+or either ignore rule. `flatbread proof bootstrap --verify` reports the same
+and exits nonzero when anything is missing, which makes it usable in CI.


BLOCKER (consensus: all four perspectives)

Documents flatbread proof bootstrap [--verify], but the flatbread CLI has no proof subcommand (only flatbread effort bootstrap).

Minimal fix: Delete these commands; document real proof / proof-supervisor usage. Leave memory bootstrap solely in Effort Graph docs.

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

+Read [`skills/proof/glossary.md`](./skills/proof/glossary.md) for
+the portable Proof domain model.

-```bash
-export CURSOR_API_KEY=crsr_...
+The packaged Agent Skill is in `skills/proof/`. The repository copy in
+`.agents/skills/proof/` is generated from those files. Run
+`pnpm skills:sync` from the repository root after changing the skill.


BLOCKER (docs-and-positioning, dependency-runtime-surface, dx-and-examples)

Links skills/proof/glossary.md and claims a packaged skill at skills/proof/ / generated .agents/skills/proof/. Neither tree exists under packages/proof/ (Proof skill lives at .cursor/skills/proof/).

Minimal fix: Drop broken skill/glossary links until a real packages/proof/skills/proof tree ships.

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

 ```bash
-pnpm exec proof --dag /tmp/my.json --canvas-path /tmp/my.canvas.tsx --no-artifacts
-```
-
-To write artifacts to a custom path:
-
-```bash
-pnpm exec proof --dag /tmp/my.json --canvas-path /tmp/my.canvas.tsx \
-  --full-output-dir /path/to/my-artifacts/
-```
-
-## Project Skill
-
-The canonical Cursor skill entrypoint lives at:
-
-```text
-.cursor/skills/proof/SKILL.md
-```
-
-Use that skill when a request asks to decompose work, run subagents in parallel, or execute a task as a dependency graph. The legacy `.cursor/skills/dag-task-runner/SKILL.md` entry remains as a compatibility handoff and points to Proof.
-
-## Self-Hosting Mode
-
-When the DAG may edit Proof itself, use the supervisor:
-
-```bash
-pnpm exec proof-supervisor \
-  --dag /tmp/example-dag.json \
-  --canvas-path /tmp/example-dag.canvas.tsx \
-  --state-path /tmp/example-dag-state.json
-```
-
-The supervisor adds `--restart-on-runner-change`. If runtime files change after a rank, Proof persists state, exits with code `75`, and the supervisor resumes from the state file under the rebuilt runtime.
-
-Each supervisor-spawned runner picks a **new default** `.flatbread/artifacts/dag-<slug>-<timestamp>/` directory unless you pin **`--full-output-dir <path>` on the supervisor command** so every child inherits the same path.
-
-After editing `packages/proof/src/**`, rebuild before resuming packaged CLI runs:
-
-```bash
-pnpm -F @flatbread/proof build
-```
-
-## Useful Commands
-
-```bash
-pnpm -F @flatbread/proof typecheck
-pnpm -F @flatbread/proof build
-pnpm -F @flatbread/proof test
-pnpm test
-pnpm -F @flatbread/proof models:list
-pnpm exec proof --dry-check-cmds --dag .cursor/skills/proof/examples/example_dag.json
-```
-
-`pnpm -F @flatbread/proof test` is the focused bounded-loop suite. Root `pnpm test` also reaches that AVA file through `ava.config.js`.
-
-## Library API
-
-Proof also exposes helpers for tooling:
-
-```ts
-import {
-  computeRanks,
-  createModelSelectionResolver,
-  parseDAG,
-  resolveModelSelectionFromCatalog,
-  runDryCheck,
-  type DAG,
-  type TaskState,
-} from '@flatbread/proof';
+npx skills add https://github.com/FlatbreadLabs/flatbread/tree/<gitTag>/packages/proof/skills/proof --skill proof
+npm install --save-dev flatbread@<flatbreadVersion>
 ```

-The public API includes DAG parsing and rank computation, model resolution, canvas state types, convergence helpers, dry command checks, oracle and pause helpers, and self-hosting state utilities.
+The tag and version come from `gitTag` and `flatbreadVersion` in
+`skills/proof/release.json`. See `skills/proof/setup.md` for the
+equivalent `pnpm`, `yarn`, and `bun` commands.


BLOCKER (consensus on install URL)

npx skills add …/packages/proof/skills/proof and refs to skills/proof/release.json / setup.md target paths absent from the repo and pack tarball — install fails on any real tag.

Minimal fix: Delete the skill-install block; replace with working package install (pnpm add -D @flatbread/proof) and optional .cursor/skills/proof/ pointer.

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

+
+### Docs
+
+- The READMEs and `docs/positioning.md` now lead with the Effort Graph: an


HIGH (release-discipline, docs-and-positioning, dependency-runtime-surface)

Docs section claims READMEs and docs/positioning.md lead with Effort Graph, but positioning (and the Proof README) still lead with Proof memory APIs that do not exist.

Minimal fix: Fix positioning + Proof README first so this Effort Graph claim is true.

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

  "name": "@flatbread/proof",
-  "version": "0.1.0-alpha.0",
-  "description": "Decompose a task into a DAG of subagents and prove they did the work — live canvas, oracles, pause gates, and convergence loops.",
+  "version": "1.0.0",


HIGH (dependency-runtime-surface)

npm description correctly says “Bounded DAG task runner…” while the README body says “Git-native memory…”, so search snippet and package page disagree.

Minimal fix: Keep this DAG description; restore the README so both surfaces describe the same product.

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

+    "@flatbread/config": "workspace:^",
+    "@flatbread/core": "workspace:^",


MED (dependency-runtime-surface)

workspace:^ peers publish as ^1.0.0, allowing @flatbread/core/config 1.0.x drift while root CHANGELOG headlines absolute lockstep.

Minimal fix: Pin peers to 1.0.0 on publish, or document codegen as the intentional semver-widened exception next to the lockstep claim.

cursor

CI Root Cause

Status: third-party-failure

Failing checks:

integration-sveltekit (20.x, windows-latest): pnpm install --frozen-lockfile failed while sharp@0.31.3 downloaded libvips (socket hang up)

Evidence:

Job 94215231643 (run 31626822386 on SHA fda484c) failed in Run pnpm install --frozen-lockfile; Build SvelteKit Integration did not start.
Log: sharp: Downloading https://github.com/lovell/sharp-libvips/releases/download/v8.13.3/libvips-8.13.3-win32-x64.tar.br then sharp: Installation error: socket hang up → ELIFECYCLE exit 1.
Same SHA: sibling cells passed, including integration-sveltekit on ubuntu/macos (20.x and 22.x) and windows-latest (22.x), plus lint/build/test/integration-nextjs.
This stack step is a release prepare commit (version bumps, docs, LICENSE, lockfile metadata). It does not change SvelteKit app code or sharp install wiring.

Resolution steps:

Re-run failed jobs for run 31626822386 (or push an empty re-trigger) once GitHub Releases downloads for lovell/sharp-libvips are healthy.
If the same socket hang up / 503 / timeout on sharp-libvips repeats across many matrix cells, treat it as a GitHub Releases / runner egress outage, not a branch defect.
Do not amend this release commit for this failure; no package or test change is indicated.

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

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

mergify · 2026-08-12T18:50:29Z

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

Queue this pull request

tonyketcham mentioned this pull request Aug 12, 2026

fix: remove stale release dependencies #237

Merged

tonyketcham force-pushed the stack/tonyketcham/toeknee/extract-proof-repo/prepare-flatbread-1-0--3b53d7e2 branch from 2e82c87 to fda484c Compare August 12, 2026 18:16

cursor Bot reviewed Aug 12, 2026

View reviewed changes

tonyketcham merged commit 9842c89 into main Aug 12, 2026
38 of 57 checks passed

tonyketcham deleted the stack/tonyketcham/toeknee/extract-proof-repo/prepare-flatbread-1-0--3b53d7e2 branch August 12, 2026 19:24

		Read [`skills/proof/glossary.md`](./skills/proof/glossary.md) for
		the portable Proof domain model.

		npx skills add https://github.com/FlatbreadLabs/flatbread/tree/<gitTag>/packages/proof/skills/proof --skill proof
		npm install --save-dev flatbread@<flatbreadVersion>


		### Docs

		- The READMEs and `docs/positioning.md` now lead with the Effort Graph: an

		"@flatbread/config": "workspace:^",
		"@flatbread/core": "workspace:^",

Uh oh!

Uh oh!

Conversation

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 • 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

Blocking findings (priority order)

What looks fine

Minimal fix before 1.0

Perspectives

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

Review verdict

Blocking fixes (priority order)

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!

tonyketcham commented Aug 12, 2026 •

edited

Loading

tonyketcham commented Aug 12, 2026 •

edited

Loading

cursor Bot left a comment •

edited

Loading