diff --git a/docs/releases/effort-graph-alpha-READINESS.md b/docs/releases/effort-graph-alpha-READINESS.md new file mode 100644 index 00000000..b65d8ac8 --- /dev/null +++ b/docs/releases/effort-graph-alpha-READINESS.md @@ -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. diff --git a/docs/releases/effort-graph-alpha-RELEASE_NOTES.md b/docs/releases/effort-graph-alpha-RELEASE_NOTES.md new file mode 100644 index 00000000..3aaf5624 --- /dev/null +++ b/docs/releases/effort-graph-alpha-RELEASE_NOTES.md @@ -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 '' +flatbread effort list +flatbread codegen +``` + +Optional agent runner (separate package): + +```bash +npm i @flatbread/proof +proof # or proof-supervisor +```