feat(proof): add setup artifact refresh#197
Open
tonyketcham wants to merge 37 commits into
Open
Conversation
Summary of changes - Reframe Flatbread as a Git-native relational content layer for TypeScript apps. - Add docs/positioning.md as the canonical statement of ICP, jobs, non-goals, and GraphQL's role as an interface. - Update package README intros so source and transformer packages describe their role in the relational content model instead of positioning GraphQL as the product. Testing - pnpm build - pnpm lint - proof DAG: dag-flatbread-142-positioning completed 4/4 tasks Closes #142 Change-Id: Icc64caae46e919e9eca7a42f7659bc39f20386e3
Summary of changes - Add docs/glossary.md with practical definitions for collection, record, ID, relation, cardinality, validation, and query interface. - Link the glossary from the positioning page, package README, and Next.js example docs so onboarding has a shared vocabulary. - Keep definitions scoped to Flatbread's Git-native content graph and explicitly avoid database/CMS replacement implications. Testing - pnpm lint - proof DAG: dag-flatbread-143-glossary completed 4/4 tasks Closes #143 Change-Id: I5e4396421ccb1b837b7c49428e54a0d72db82877
Summary of changes - Add a PMF decision rubric comparing Flatbread with SQLite-style database workflows, hosted/headless CMS workflows, Contentlayer-like content workflows, and agent artifact/Effort Graph workflows. - Include setup time, type safety, relation modeling, reference integrity, portability, local dev loop quality, and agent query ergonomics as explicit criteria. - Link the rubric from positioning and PMF audit docs and state go/no-go signals for agent artifacts as a primary wedge. Testing - pnpm lint - proof DAG: dag-flatbread-144-pmf-rubric completed 4/4 tasks Closes #144 Change-Id: I6582bf947f99e327d1d36e4c4f2a3d6a92b320ea
Summary of changes - Align root, contributor, package, and Next.js example docs around the current pnpm workspace workflow. - Document `flatbread start` as the valid CLI command, clarify that `flatbread dev` is not a subcommand, and distinguish one-shot codegen from watch-only codegen. - Update example generated paths, ports, package names, and onboarding guidance to match the current repository layout. Testing - pnpm lint - proof DAG: dag-flatbread-146-readme-command-drift completed 4/4 tasks Closes #146 Change-Id: I6baf6285ac0c2bd74a4e5b9c6d43a85d1e1cbc45
Summary of changes - Add an issue #167 experiment report mapping the in-repo Cursor proof skill layout to Effort Graph collections. - Add representative Effort, Plan, Session, and Decision markdown fixtures that preserve the harness layout while exposing queryable frontmatter refs. - Include a single GraphQL retrieval surface for blocking decisions with linked plan/session context and concrete follow-up issue drafts for friction points. Testing - pnpm lint - proof DAG: dag-flatbread-167-effort-graph-wire-up completed 4/4 tasks Closes #167 Change-Id: I07075abaab8248babc58df421dc6d3eeb9aad64b
Summary of changes - Add an issue #168 adversarial schema report covering Claude-oriented, Cursor-oriented, and GCC-style harness layouts. - Add representative layout snippets and an acceptance matrix to pressure-test one Effort Graph schema against three artifact conventions. - Identify stable entities/fields, tool-specific mapping requirements, and recommend one canonical schema plus explicit layout profiles as viable. Testing - pnpm lint - proof DAG: dag-flatbread-168-adversarial-effort-graph completed 4/4 tasks Closes #168 Change-Id: I40a33f70c93e4e89b931293b7d972a5767d57238
Summary of changes - Rewrite the root quickstart around the Next.js example as the canonical first-success path from the monorepo root. - Lead with the posts/authors/tags content model, then introduce GraphQL codegen as the current read interface that produces a typed query result. - Update contributing, example, glossary, positioning, and content docs so commands and terminology point back to the same onboarding path. Testing - pnpm lint - proof DAG: dag-flatbread-145-root-quickstart completed 4/4 tasks Closes #145 Change-Id: I72c4fb6e4d60345b6dc8ea867dd0120bb2ff6741
Summary of changes - Expand the canonical quickstart into a relation-first trace from backing files to config to generated GraphQL/codegen output. - Add glossary terms for tag facets versus Tag collections and generated schema/operation types. - Update example content and Next.js docs so posts, authors, and tags point to one shared model and visible query-result shape. Testing - pnpm lint - proof DAG: dag-flatbread-147-relation-first-narrative completed 4/4 tasks Closes #147 Change-Id: I82bbc51a53766270ab783cedeb4386ad9a3ea95d
Summary of changes - Add shared ID normalization helpers and use them across find-by-id, find-many, relation resolution, and top-level ID equality/membership filters. - Switch GraphQL lookup arguments to the ID scalar so string and integer ID literals normalize through the same resolver path. - Validate invalid and duplicate normalized record IDs before schema use, with aggregated diagnostics that include source paths. - Document the current ID normalization rules and add AVA fixtures for accepted, rejected, and duplicate ID shapes. Testing - pnpm --filter @flatbread/core build - pnpm test:ava -- --match='*ID*' - pnpm test:ava -- --match='*Sift*' - pnpm test:ava - pnpm lint - proof DAG: dag-flatbread-148-id-semantics-review-r3 completed 3/3 tasks Closes #148 Change-Id: Iaf137000630587edc0b50908315207efcac97b62
Summary of changes - Add collection reference validation during schema generation so missing refs fail before query-time relation surprises. - Aggregate diagnostics with source collection, record context, ref field path, target collection, and missing/invalid target ID details. - Add posts/authors/tags-style AVA fixtures covering missing array refs, missing tag refs, invalid scalar ref shapes, and clean successful refs. - Correct bundled example content refs that the new validation surfaced as broken. Testing - pnpm --filter @flatbread/core build - pnpm test:ava -- --match='*reference*' - pnpm test:ava - pnpm lint - proof DAG: dag-flatbread-149-missing-reference-validation reached implementation before being terminated after runner stall - proof DAG: dag-flatbread-149-reference-validation-review completed 3/3 tasks Closes #149 Change-Id: I754093e78f1c1609557377a60cefb98701a0245c
Summary of changes - Validate content IDs before returning cached schemas so content-only duplicate regressions cannot bypass pre-schema validation. - Reset graphql-compose's global schema composer before fresh schema builds and serialize AVA files to avoid schema-building test races. - Preserve source VFile paths after transformation so duplicate-ID diagnostics include stable source locations even if parsed content contains reserved context keys. - Add a cache-regression test that proves duplicate IDs still fail after a warm schema generation. Testing - pnpm --filter @flatbread/core build - pnpm test:ava -- --match='*duplicate*' - pnpm test:ava - pnpm lint - proof DAG: dag-flatbread-150-duplicate-id-review-r3 completed 3/3 tasks Closes #150 Change-Id: Ibeb96f5e9555b72c8ef0bf6da633a65f67543f47
Summary of changes - Document supported relation cardinality shapes in the glossary: scalar one-to-one refs, list one-to-many refs, explicit reciprocal-list many-to-many modeling, and unsupported shapes. - Add AVA coverage for scalar refs, list refs, explicit many-to-many list refs, object ref values, and nested-array ref values. - Reuse missing-reference validation so unsupported cardinality shapes fail before schema use instead of resolving as nulls. Testing - pnpm --filter @flatbread/core build - pnpm test:ava -- --match='*cardinality*' - pnpm test:ava -- --match='*reference*' - pnpm test:ava - pnpm lint - proof DAG: dag-flatbread-151-relation-cardinality-review-r2 completed 3/3 tasks Closes #151 Change-Id: Ia6e0ecca5787ee252a6ddaf4b15ac78dfdd69648
Summary of changes - Add validation diagnostic snapshot tests for missing references, unknown target collections, duplicate IDs, invalid relation shapes, and required ID errors. - Add a required-field fixture for missing record IDs. - Sort aggregated validation diagnostics before throwing so snapshot output remains deterministic. Testing - pnpm --filter @flatbread/core build - pnpm exec ava packages/core/src/providers/test/validationSnapshots.test.ts --update-snapshots - pnpm exec ava packages/core/src/providers/test/validationSnapshots.test.ts - pnpm test:ava - pnpm lint - proof DAG: dag-flatbread-152-validation-snapshots-review-r2 completed 3/3 tasks Closes #152 Change-Id: I85369f9faa10f5851f74e8bc143ca50725f30b21
Summary of changes - Append generated Flatbread content-model helper types to codegen output using the configured collections and refs. - Emit collection-name, record-by-collection, relation-target collection, relation cardinality, and related-record helper types without requiring handwritten GraphQL documents. - Keep the generated helper block idempotent across cache hits and add compile assertions proving the generated types match the representative config. Testing - pnpm --filter @flatbread/codegen build - pnpm -F @flatbread/codegen exec vitest run - pnpm lint - proof DAG: dag-flatbread-153-ts-schema-types-review-r6 completed 3/3 tasks Closes #153 Change-Id: I7205a76b8cc8c579c95e91dd5d5471dbf30a8621
Summary of changes - Generate a prototype TypeScript read API alongside GraphQL codegen output, including collection readers, default schema-derived selections, relation metadata, and cache-versioned output. - Regenerate the Next.js example types and add a read API helper that queries posts, authors, and tags through createFlatbreadReadApi while keeping the existing GraphQL path available. - Exercise the generated read API from the Next.js home page, document the prototype, and fix example content refs surfaced by validation. - Add compile/runtime-oriented codegen tests for generated content model/read API types, cache behavior, relation cardinality, and cache-busting output versioning. Testing - pnpm --filter @flatbread/codegen build - pnpm -F @flatbread/codegen exec vitest run - pnpm build - pnpm --filter nextjs exec flatbread codegen --clear-cache --verbose - pnpm --filter nextjs build - pnpm lint - proof DAG: dag-flatbread-154-ts-read-api-review-r8 completed 4/4 tasks Closes #154 Change-Id: Ie93611adaef1dcc3b1b90bec40dfc7d7e30d57c3
Summary of changes - Clarify when to use GraphQL operations versus the prototype generated TypeScript read API. - Tie both read interfaces back to the typed content model and canonical posts/authors/tags quickstart. - Align codegen and example docs with the prototype status and the current pnpm exec flatbread command style. Testing - pnpm --filter @flatbread/codegen build - pnpm -F @flatbread/codegen exec vitest run - pnpm --filter nextjs build - pnpm lint - proof DAG: dag-flatbread-155-graphql-interface-docs completed 3/3 tasks Closes #155 Change-Id: I68a3c0dfd8e224a4765659bcb86206532156afe7
Summary of changes - Narrow core public content surfaces from broad any types toward unknown, typed ContentEntry refs, typed Source fetch inputs, and typed Override resolve boundaries. - Tighten resolver argument handling, sort typing, deep entry traversal, field overrides, transformKeys, and schema generation boundaries without changing valid content behavior. - Add compile-time AVA type assertions for common record/relation/source/override paths and expand sift coverage for ID and array string filters. Testing - pnpm --filter @flatbread/core build - pnpm test:ava -- --match='*content types*' - pnpm test:ava -- --match='*Sift*' - pnpm test:ava - pnpm lint - proof DAG: dag-flatbread-156-final-review completed 2/2 tasks Closes #156 Change-Id: I66ef0a4af96378d3d92e90361bb0bb4c9bb13c8d
Summary of changes - Add local dev loop documentation covering loader reload, schema rebuild, codegen refresh, and framework restart boundaries. - Document the canonical Next.js two-terminal happy path and current manual restart requirements. - Add a current reload matrix, failure semantics, draft unified watch design, known limitations, and implementation follow-up seams. - Link the dev-loop contract from the root/package README and Next.js example docs. Testing - pnpm lint - proof DAG: dag-flatbread-157-watch-loop-review-r2 completed 2/2 tasks Closes #157 Change-Id: I3de62d3fdc3bbcb248ebbd4a449ad443fc15aa49
Summary of changes - Add a reproducible edit-file-see-query-update demo for the canonical posts/authors/tags flow. - Add a focused Next.js watcher script that rebuilds the Flatbread graph per file event and prints updated Markdown post plus YAML author relation query results without a manual restart. - Add edit/restore helper scripts and document the clean-checkout commands and current limitations. Testing - pnpm build - pnpm --filter nextjs exec flatbread codegen --verbose - pnpm lint - pnpm --filter nextjs run demo:watch-query with demo:edit/demo:restore; verified original, live-edit, and restored Markdown/YAML query output in /tmp/flatbread-watch-demo.log - proof DAG: dag-flatbread-158-final-review-r3 completed 2/2 tasks Closes #158 Change-Id: Id8909a3bf87bf5cb5f8de176e69123727ee39201
Summary of changes - Add exportCollectionsAsJson to @flatbread/core for selected collection JSON snapshots. - Normalize exported record IDs and configured relation fields with Flatbread ID semantics, sort collections/records/object keys deterministically, and emit source paths relative to pathRoot. - Reuse schema validation before exporting so duplicate IDs and missing refs fail before output is returned. - Add representative AVA coverage for selected exports, unknown collections, and validation failures, plus JSON export documentation. Testing - pnpm --filter @flatbread/core build - pnpm test:ava -- --match='*export*' - pnpm test:ava - pnpm lint - proof DAG: dag-flatbread-159-json-export-review-r2 completed 2/2 tasks Closes #159 Change-Id: Ie21000ebbed3d35e6fe2ae66d260d3c92465f553
Summary of changes - Add exportCollectionsAsCsv to @flatbread/core for flat selected collection CSV views. - Include scalar fields and scalar arrays, keep relation fields as normalized reference IDs joined by a configurable separator, and omit nested object fields by design. - Support comma, semicolon, and tab delimiters with CSV escaping. - Document CSV behavior alongside JSON snapshots and add AVA coverage for headers, rows, escaping, relation IDs, and custom delimiters/separators. Testing - pnpm --filter @flatbread/core build - pnpm test:ava -- --match='*CSV*' - pnpm test:ava - pnpm lint - proof DAG: dag-flatbread-160-csv-export-review completed 2/2 tasks Closes #160 Change-Id: I29485ae56de6c80be6ea31db1abe5a3790c7caf3
Summary of changes - Add a data ownership and exit story that frames raw files and Git history as the source of truth. - Document JSON and CSV snapshots, GraphQL introspection, and generated TypeScript artifacts as portability surfaces with current limitations. - Cross-link ownership guidance from positioning, snapshot export docs, and the main README. Testing - pnpm lint - proof DAG: dag-flatbread-161-data-ownership-review-r2 completed 2/2 tasks Closes #161 Change-Id: Ie01aa41c5b809005e5ee7cf194ba57035d9021e0
Summary of changes - Add the relational starter benchmark report for the canonical posts/authors/tags path. - Record a fresh-worktree install/build/codegen/demo query run completing in 49 seconds and a generated TypeScript read API build verification completing in 18 seconds. - Capture observed friction and follow-up issue drafts for a network-cold benchmark and Next.js ESLint plugin warning. Testing - pnpm lint - timed fresh-worktree benchmark: pnpm install, pnpm build, nextjs codegen, demo:watch-query - timed read API verification: pnpm --filter nextjs build - proof DAG: dag-flatbread-162-starter-benchmark-review-r4 completed 2/2 tasks Closes #162 Change-Id: Ia44b7d6f5efcff6d303959acc0039a1c330d0972
Summary of changes - Add a TypeScript safety experiment report for generated Flatbread model/read API types. - Capture what works today, inference gaps, confusing helper names, nullability limitations, and PMF implications. - Convert findings into follow-up issue drafts for typed selections, relation helper naming, and nullability alignment. Testing - pnpm --filter @flatbread/codegen build - pnpm -F @flatbread/codegen exec vitest run - pnpm --filter @flatbread/core build - pnpm test:ava -- --match='*content types*' - pnpm --filter nextjs build - pnpm lint - proof DAG: dag-flatbread-163-ts-safety-review completed 2/2 tasks Closes #163 Change-Id: I9584a9ea1aece110cf32900dfd8afdcdddd8829b
Summary of changes - Add an export trust experiment report with a JSON/CSV demo prompt for the posts/authors/tags ownership story. - Include a product self-review table for raw files, JSON snapshots, CSV flat views, GraphQL introspection, generated types, and ownership docs. - Add a verification transcript showing JSON and CSV export output from the Next.js example and follow-up issue drafts for CLI export, exit fixtures, and external interviews. Testing - pnpm lint - Node export transcript using loadConfig and exportCollectionsAsJson/exportCollectionsAsCsv from the flatbread package - proof DAG: dag-flatbread-164-export-trust-review-r2 completed 2/2 tasks Closes #164 Change-Id: I60fd0a34d028a1e45f1d52adb78f013848097424
Summary of changes - Add a cold-start versus Flatbread-mediated agent artifact retrieval benchmark for the Effort Graph validation track. - Compare full-context artifact stuffing with filtered retrieval of blocking decision, plan, and session rows. - Record payload size reduction, continuity tradeoffs, recommendation, and follow-up issue drafts for MCP query, broader benchmark, and expansion policy. Testing - wc -c over full artifact set and filtered Effort Graph rows - pnpm lint - proof DAG: dag-flatbread-169-artifact-retrieval-review completed 2/2 tasks Closes #169 Change-Id: I8370996c72f1ccefd8829f7e59ca956baa399218
Summary of changes - Add a validation-driven roadmap with keep/kill/iterate decisions across content layer, validation, TypeScript APIs, GraphQL, watch loop, exports, Effort Graph, CMS UI, and database-replacement scope. - Explicitly decide Effort Graph should remain a secondary vertical with a path to primary wedge after MCP, token benchmark, and external validation gates. - Add updated priorities, follow-up issue drafts, maintainer action checklist, and per-issue traceability for the project-board stack. Testing - pnpm lint - proof DAG: dag-flatbread-165-roadmap-review-r2 completed 2/2 tasks Closes #165 Change-Id: I6aa7d2cb865b8a54c261169b1c3db214c6b1b8a0
Captures the design rationale for moving the existing --converge-on/--max-iterations CLI singleton into a DAG-native `loops` array. Decision recap: - DAG `depends_on` edges stay acyclic (causality + parallelism). - Bounded refinement (research → critique → refine, fix → test → fix) becomes an explicit DAG.loops[] config instead of a back-edge. - The CLI flag stays valid; loops just lift the same shape into the JSON file so multiple convergence tasks can stack in one run and reproducible runs do not depend on remembered flags. Out of scope (this proposal): new stopWhen predicates beyond 'no-blockers', nested loops, cross-loop coordination. Co-authored-by: Tony <tonyketcham@users.noreply.github.com>
Adds DAG.loops[] — an optional array of bounded convergence loops
that runs after the main rank loop completes. Generalizes the legacy
--converge-on/--max-iterations CLI singleton:
- Multiple loops per run (one per convergence task).
- Optional explicit `reexecute.tasks` allow-list, validated to lie
inside the convergence ancestor cone (off-cone tasks would break
filtered topological ordering).
- Default `reexecute: { kind: 'ancestors' }` matches the CLI
behavior bit-for-bit.
- `stopWhen: 'no-blockers'` is the only predicate today; the
schema is open for future predicates without further churn.
Schema, parsing, and re-execution id resolution all live in
dag.ts/converge_loop.ts; the runner consumes a single canonical
ResolvedConvergenceLoop list whether the user supplied DAG.loops or
the CLI flag (the two cannot be combined — the runner errors at
startup to avoid silent precedence rules).
DAG.budget.maxIterations continues to apply per-loop. Loops execute
sequentially in declaration order; each loop's BUDGET-EXCEEDED is
independent and surfaces via the existing per-task tally.
Tests (AVA, packages/proof/src/__tests__/loops.test.ts):
- 18 cases covering parser acceptance, validation rejections,
default-filling, ancestor-cone enforcement, multi-loop ids, and
reexecute selector resolution.
- Smoke verified end-to-end via the proof CLI: --init-only with a
loops-bearing DAG renders the canvas, and combining --converge-on
with DAG.loops fails fast with the expected message.
Co-authored-by: Tony <tonyketcham@users.noreply.github.com>
Change-Id: I403c6326709e508e20b776782e36e2debd462da5
…ersal, harden tests
validateLoops(): replace seenIds with seenResolvedIds so explicit ids cannot collide with another loop's default id (loop-${convergeOn}); detected case: { convergeOn: 'review' } + { id: 'loop-review', convergeOn: 'impl' }
Export transitiveAncestorIds from dag.ts; make transitiveAncestors in converge_loop.ts delegate to it, eliminating the duplicate DFS implementation
loops.test.ts: strengthen reexecute.tasks membership check to deepEqual; add collision regression test, dedup test, pause-as-convergeOn doc test
flatbread: bump @types/express to 5.x for Express 5 so AVA/ts-node can load graphql server tests without TS2769 overload errors
Co-authored-by: Cursor <cursoragent@cursor.com>
Change-Id: I6b82b728f0427bd7ef6480ae5e7cdec97039faa3
Change-Id: I195746d1fac4e58f9730f8d79a0becc2d07847cc
Co-authored-by: Cursor <cursoragent@cursor.com> Change-Id: I098b327217160ba9695494dae748834ee654d214
Co-authored-by: Cursor <cursoragent@cursor.com> Change-Id: I8bceec6e5149869cfa0cd11f63b22b9b826c5639
Align the example and package docs with the canonical Flatbread README, clarify the core export entrypoints, and narrow the starter benchmark wording to the scope actually measured. This preserves the project-board audit outcomes without mixing in unrelated proof UI work. Co-authored-by: Cursor <cursoragent@cursor.com> Change-Id: Ic716b186bec43bca0b8e997289d11e25c5b46ac1
Change-Id: Idc1a1243b294d29cf4016aef86e06b877c62211b
Summary: - Add a `proof setup` CLI path that refreshes owned Proof guidance, writes setup DAG artifacts, and can delegate to the existing DAG runner. - Document the Proof setup maintenance contract in the package README, skill, workspace rule, and generated setup artifacts. - Expand the focused Proof test script to cover setup tests alongside loop coverage. Test plan: - pnpm -F @flatbread/proof build - pnpm exec proof setup - pnpm lint:fix:fast - pnpm -F @flatbread/proof test Co-authored-by: Cursor <cursoragent@cursor.com> Change-Id: I85f90e296d8cc65c74d8c118b95aa4bfd2ffe3db
Base automatically changed from
toeknee/flatbread-task-dag-instances-18a9
to
main
May 12, 2026 08:31
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary:
proof setupCLI path that refreshes owned Proof guidance, writes setup DAG artifacts, and can delegate to the existing DAG runner.Test plan:
Made with Cursor