Skip to content

docs(releases): Effort Graph alpha readiness check and release notes #234

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
tonyketcham wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs(releases): Effort Graph alpha readiness check and release notes #234

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 73 additions & 0 deletions docs/releases/effort-graph-alpha-READINESS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
# Release readiness report — Effort Graph alpha

**Date:** 2026-07-28
**Candidate gate:** [#233](https://github.com/FlatbreadLabs/flatbread/pull/233) (supersedes closed [#230](https://github.com/FlatbreadLabs/flatbread/pull/230)–[#232](https://github.com/FlatbreadLabs/flatbread/pull/232); CI green; merge blocked on approving review / Mergify queue)
**Checked tree:** PR #233 tip (`9fde89a`), not yet on `main`
**Audience:** release operators

## Overall verdict: **NOT READY**

Build, skills gates, pack dry-runs, `workspace:*` rewrite, and focused tests all **pass** on the #233 tip. Publish of the Effort Graph feature is **blocked** by version collisions: `publish:ci` would skip `flatbread` and `@flatbread/core` (and other drifted packages) at versions already on npm that lack this work. Merge #233 to `main`, bump those packages, first-publish the three new packages, refresh skill pins, then publish.

---

## Package publish matrix

| Package | Local version | npm status | Action needed |
| --------------------------------- | ---------------- | ---------------------------------------------------------- | --------------------------------------- |
| `@flatbread/effort-graph` | `0.1.0-alpha.0` | **404** (never published) | **First publish** |
| `@flatbread/explorer` | `0.1.0-alpha.0` | **404** (never published) | **First publish** |
| `@flatbread/proof` | `0.1.0-alpha.0` | **404** (never published) | **First publish** (confirm intentional) |
| `flatbread` | `1.0.0-alpha.22` | Same version on npm **without** explorer/effort-graph deps | **Bump**, then publish |
| `@flatbread/core` | `1.0.0-alpha.16` | Same version on npm; missing live watch/schema APIs | **Bump**, then publish |
| `@flatbread/codegen` | `1.0.0-alpha.2` | Same version; unpublished commits + peer pins | **Bump**, then publish |
| `@flatbread/config` | `1.0.0-alpha.9` | Same version; unpublished commits | **Bump**, then publish |
| `@flatbread/source-filesystem` | `1.0.0-alpha.9` | Same version; unpublished commits | **Bump**, then publish |
| `@flatbread/transformer-markdown` | `1.0.0-alpha.8` | Same version; unpublished commits | **Bump**, then publish |
| `@flatbread/transformer-yaml` | `1.0.0-alpha.8` | Same version; unpublished commits | **Bump**, then publish |
| `@flatbread/utils` | `1.0.0-alpha.2` | Same version; toolchain-only delta | Bump if included in release set |
| `@flatbread/resolver-svimg` | `1.0.0-alpha.0` | On npm; idle since 2022 | **No bump** |

`publish:ci` topo order ends with codegen → **flatbread last**. Skips when `npm view name@version` matches; otherwise `pnpm publish --access public`.

---

## Blockers (must fix before publish)

1. **Merge [#233](https://github.com/FlatbreadLabs/flatbread/pull/233) to `main`.** Auto-merge is enabled; GitHub still requires an approving review or `@mergifyio queue` from a write-permission account.
2. **Bump `flatbread` past `1.0.0-alpha.22`.** Registry tarball lacks `@flatbread/explorer` / `@flatbread/effort-graph`. Same version → skip → CLI never ships Effort Graph wiring.
3. **Bump `@flatbread/core` past `1.0.0-alpha.16`.** Local API adds `createLiveSchemaReloader` / `createWatchCoordinator` (and more). Skip leaves a new CLI resolving to old core → broken runtime.
4. **First-publish `@flatbread/effort-graph` and `@flatbread/explorer`** in the same train as bumped `flatbread` (hard deps). `@flatbread/proof` publishes at `0.1.0-alpha.0` unless marked private.
5. **Bump remaining drifted packages** (`codegen`, `config`, `source-filesystem`, transformers; optionally `utils`) so skip semantics do not leave half the feature set on stale registry tarballs. Align codegen **exact peers** with new config/core versions.
6. **Refresh skills `release.json`** (`flatbreadVersion` / `gitTag`) to the new versions and create the matching git tag. Current pins target `1.0.0-alpha.22` / missing `v1.0.0-alpha.22` — skill install path is broken for Effort Graph.

---

## Warnings (should fix or consciously accept)

- **`@flatbread/proof` `files`** ships `src` (incl. tests) and `scripts` — over-broad; tighten unless supervisor needs published source.
- **CLI / routing changes:** new `effort *` commands; `--watch`; `--open` → `/` for Effort Graph; `/events` SSE; `/` claimed by SPA — update proxies, health checks, automation.
- **Schema / codegen growth** from Effort Graph collections; `CODEGEN_OUTPUT_VERSION=2` forces cache invalidation.
- **Stricter TS** on core plugin contracts; dropped `graphql-compose-json` / `lru-cache` — re-codegen and diff schema.
- **`effort-graph` `.d.ts` imports `@flatbread/core` types** but core is only a devDependency — declare peer or document “install with flatbread/core”.
- **Node ≥ 20.19**; `@parcel/watcher` for watch; prefer Node 20 LTS over 22 for production watch until EINVAL teardown is proven clean.
- **Explorer tarball** must include prebuilt `dist/static` (full `pnpm build` before publish — `build:types` alone is insufficient).
- **Dist-tag `alpha` lags `latest`** — retag or document “use latest / exact”; do not advertise `@alpha`.
- **Confirm product intent** to publish `@flatbread/proof` in this train.

---

## Notes

| Gate | Status |
| -------------------------------------------------------- | --------------------------------------- |
| `pnpm install --frozen-lockfile` | PASS |
| `pnpm build` | PASS (explorer SPA in `dist/static`) |
| `pnpm skills:check` / `skills:pack-check` | PASS |
| Pack dry-run (all 12 public packages on #233 tip) | PASS |
| `workspace:*` → concrete versions on pack | PASS |
| Focused tests (effort-graph, explorer, flatbread, proof) | PASS |
| Version readiness for feature publish | **FAIL** |
| #233 merged to `main` | **PENDING** (blocked on review / queue) |

**Suggested publish order:** utils (if bumping) → config → transformers / source-filesystem → **core** → codegen → **first-publish effort-graph + proof** → **first-publish explorer** → **bumped flatbread last** → retag skills / docs → leave resolver-svimg alone.
94 changes: 94 additions & 0 deletions docs/releases/effort-graph-alpha-RELEASE_NOTES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
# Flatbread alpha — Effort Graph release

> **Status (2026-07-28):** Draft against PR [#233](https://github.com/FlatbreadLabs/flatbread/pull/233) (supersedes [#232](https://github.com/FlatbreadLabs/flatbread/pull/232)). Not yet merged to `main`. See also [readiness report](./effort-graph-alpha-READINESS.md).

Flatbread is a filesystem-backed GraphQL content layer. This alpha ships **Effort Graph**: Git-tracked agent memory (efforts, issues, findings, decisions, and related records) with a journaled writer, a live explorer UI on `flatbread start`, typed codegen, JSON/CSV export, and a Proof DAG runner for Cursor agents. Nothing in this feature set is on npm yet at matching package versions — existing alphas must be bumped and three new packages first-published together.

---

## Highlights

1. **Effort Graph** — journaled semantic mutations over markdown under Git; preset `effortGraphContent()`; agent skills for journaling, modeling, and review.
2. **Explorer SPA** — content-relation visualizer (Effort Graph preset) served at `/` by `flatbread start` when the preset is active; `--open` lands on the SPA.
3. **Live watch + SSE** — `flatbread start --watch` hot-swaps schema/content; clients get generation frames on `/events`.
4. **`flatbread effort *` CLI** — write, get, list, records, relations, blocking-decisions, bootstrap, cache prune.
5. **Codegen & typed reads** — content-model TypeScript types + generated read API; stricter ID/ref validation.
6. **Export** — `exportCollectionsAsJson` and CSV export from `@flatbread/core`.
7. **`@flatbread/proof`** — DAG task runner (`proof` / `proof-supervisor`) for Cursor subagents.

---

## What's new

- **`@flatbread/effort-graph`** (new): journaled writer, Citation/Blob records, digests/reads, `effortGraphContent()`, packaged skills (`effort-graph`, `effort-modeling`, `grill-with-efforts`).
- **`@flatbread/explorer`** (new): prebuilt SPA under `dist/static`; Node helpers; mounted by the CLI when Effort Graph is configured.
- **`flatbread effort write|get|list|records|relations|blocking-decisions|bootstrap|cache prune`** — Effort Graph CLI surface.
- **`flatbread start --watch`** — unified watch coordinator + live schema swap; **`/events`** SSE.
- **`flatbread start --open`** — with Effort Graph + explorer assets, opens `/` (SPA), not Apollo `/graphql`.
- **`@flatbread/core`**: `createLiveSchemaReloader`, `createWatchCoordinator`, record production / path classification, ID/ref validation, JSON/CSV export helpers.
- **`@flatbread/codegen`**: `CODEGEN_OUTPUT_VERSION=2`; content-model types + TypeScript read API generation.
- **`@flatbread/config`**: `loadConfig` returns initialized `LoadedFlatbreadConfig`.
- **`@flatbread/proof`** (new): DAG runner with loops, artifacts, Cursor model handling; bins `proof`, `proof-supervisor`.
- Source/transformer alignment for `**` path captures and record production (`@flatbread/source-filesystem`, transformers).

---

## Packages in this release

| Package | Version intent | New vs bump |
| --------------------------------- | ---------------------------------------------------- | ------------------------ |
| `@flatbread/effort-graph` | `0.1.0-alpha.0` (first publish) | **new** |
| `@flatbread/explorer` | `0.1.0-alpha.0` (first publish) | **new** |
| `@flatbread/proof` | `0.1.0-alpha.0` (first publish) | **new** |
| `flatbread` | bump past `1.0.0-alpha.22` | **bump** (required) |
| `@flatbread/core` | bump past `1.0.0-alpha.16` | **bump** (required) |
| `@flatbread/codegen` | bump past `1.0.0-alpha.2` | **bump** |
| `@flatbread/config` | bump past `1.0.0-alpha.9` | **bump** |
| `@flatbread/source-filesystem` | bump past `1.0.0-alpha.9` | **bump** |
| `@flatbread/transformer-markdown` | bump past `1.0.0-alpha.8` | **bump** |
| `@flatbread/transformer-yaml` | bump past `1.0.0-alpha.8` | **bump** |
| `@flatbread/utils` | bump past `1.0.0-alpha.2` (optional; toolchain only) | **bump** if republishing |
| `@flatbread/resolver-svimg` | `1.0.0-alpha.0` unchanged | idle — no bump |

---

## Breaking / migration notes

- **Install as a set.** A new `flatbread` hard-depends on `@flatbread/effort-graph` and `@flatbread/explorer`. Publish those before or with the CLI. Bump `@flatbread/core` in the same train — published `alpha.16` lacks live-schema/watch APIs the CLI needs.
- **`flatbread start --open`** with `effortGraphContent()` opens `/` (explorer), not `/graphql`. GraphQL remains at `/graphql`; new SSE at `/events`. Do not health-check `/` as GraphQL.
- **`--watch` is opt-in.** Without it, start stays closer to a single schema load.
- **Server-only `start`** (no corunner) is intentional; omit dummy secondary processes.
- **Codegen:** re-run after upgrade; Effort Graph injects many collections (name collisions possible). Cache hash includes `CODEGEN_OUTPUT_VERSION=2` — expect a one-time full regen. Align codegen peers with bumped config/core.
- **Custom sources/transformers:** tighter TypeScript (`ContentEntry`, optional `fetchPaths`); path matching for `**`/captures changed.
- **Core deps dropped:** `graphql-compose-json`, `lru-cache` — re-codegen and diff schema shapes.
- **Node:** use **≥ 20.19** for this stack (stale plugin `engines` / README “Node 16+” are outdated). Watch adds `@parcel/watcher`.
- **Skills:** refresh `release.json` pins to the new `flatbread` version and a real `gitTag` before advertising skill install (current pins point at pre–Effort Graph `alpha.22` / missing tag).
- **Dist-tag `alpha` lags `latest`** on several packages — install `@latest` or exact versions, not `@alpha`.
- **`examples/effort-viz` removed** — use packaged explorer via `flatbread start --watch --open` (or `pnpm play:efforts` in-repo).

---

## Getting started

```bash
# After publish (use the bumped versions, not the stale alphas below as pins)
npm i flatbread@latest

# Config: spread Effort Graph content into your Flatbread config
# ...effortGraphContent()

flatbread effort bootstrap --verify
flatbread start --watch --open

# Mutations / reads
flatbread effort write '<json>'
flatbread effort list
flatbread codegen
```

Optional agent runner (separate package):

```bash
npm i @flatbread/proof
proof # or proof-supervisor
```
Loading