From 7f8241c3b0ba3a8b8a152be9d6ec6f952a9f85ac Mon Sep 17 00:00:00 2001 From: Tony Ketcham Date: Tue, 25 Aug 2026 08:19:18 +0000 Subject: [PATCH] docs(proof): record Explorer change-review decisions ## Describe Record the accepted host-neutral model for revision-aware graph review in the Explorer: complete snapshots, distinct Changed and Affected overlays, and private review progress. The graph also captures the current product gap and the read-only V1 boundary. ## Test Plan - Run `pnpm exec flatbread proof bootstrap --verify`. - Strict-read the six new records at generation 9; verify all three Decisions are accepted and the implementation gap remains open. - Scan every new record for host-specific or private deployment details; confirm no matches. Change-Id: I2af0c045d2f11ae69961c395d4c6ee7448a7ee5b --- ...dditive-and-read-only--p7h7wrvwf3s10ykm.md | 9 ++++++ ...ioned-graph-snapshots--027nken1pmrw9byv.md | 28 +++++++++++++++++++ ...-private-and-explicit--gnanzqbpkvdwk1pv.md | 25 +++++++++++++++++ ...ditive-review-overlay--tgp2rv0mj4wvwmct.md | 21 ++++++++++++++ ...on-aware-change-model--bqpg99cfmx25f8fe.md | 17 +++++++++++ ...nges-across-revisions--q4s8qjapczttpa9y.md | 12 ++++++++ 6 files changed, 112 insertions(+) create mode 100644 .flatbread-proof/constraints/con-change-review-stays-additive-and-read-only--p7h7wrvwf3s10ykm.md create mode 100644 .flatbread-proof/decisions/dec-compare-complete-versioned-graph-snapshots--027nken1pmrw9byv.md create mode 100644 .flatbread-proof/decisions/dec-keep-review-progress-private-and-explicit--gnanzqbpkvdwk1pv.md create mode 100644 .flatbread-proof/decisions/dec-show-changes-as-an-additive-review-overlay--tgp2rv0mj4wvwmct.md create mode 100644 .flatbread-proof/findings/fnd-explorer-has-no-revision-aware-change-model--bqpg99cfmx25f8fe.md create mode 100644 .flatbread-proof/issues/iss-explorer-cannot-review-changes-across-revisions--q4s8qjapczttpa9y.md diff --git a/.flatbread-proof/constraints/con-change-review-stays-additive-and-read-only--p7h7wrvwf3s10ykm.md b/.flatbread-proof/constraints/con-change-review-stays-additive-and-read-only--p7h7wrvwf3s10ykm.md new file mode 100644 index 00000000..f3228b68 --- /dev/null +++ b/.flatbread-proof/constraints/con-change-review-stays-additive-and-read-only--p7h7wrvwf3s10ykm.md @@ -0,0 +1,9 @@ +--- +id: con-change-review-stays-additive-and-read-only--p7h7wrvwf3s10ykm +effort: eff-effort-graph-memory-and-agent-wedge--szeqvmgqjqnhd002 +title: Change review stays additive and read-only +kind: hard +created_at: '2026-08-25T08:08:28.344Z' +--- + +Change review is an overlay on the complete graph. Users must be able to leave the changed subgraph, inspect any record, and return. V1 reads source data only. It stores review progress outside Proof and keeps exact source anchors for later integrations. diff --git a/.flatbread-proof/decisions/dec-compare-complete-versioned-graph-snapshots--027nken1pmrw9byv.md b/.flatbread-proof/decisions/dec-compare-complete-versioned-graph-snapshots--027nken1pmrw9byv.md new file mode 100644 index 00000000..f476a6cf --- /dev/null +++ b/.flatbread-proof/decisions/dec-compare-complete-versioned-graph-snapshots--027nken1pmrw9byv.md @@ -0,0 +1,28 @@ +--- +id: dec-compare-complete-versioned-graph-snapshots--027nken1pmrw9byv +effort: eff-effort-graph-memory-and-agent-wedge--szeqvmgqjqnhd002 +title: Compare complete versioned graph snapshots +state: accepted +created_at: '2026-08-25T08:08:30.713Z' +derives_from: + - con-change-review-stays-additive-and-read-only--p7h7wrvwf3s10ykm + - dec-bridge-committed-generations-into-live-reads--mc3728t4w1kyqcqq + - dec-canonical-forward-edges-and-journaled-save-or-un--sv9x93svkfz4a98r + - dec-ship-citation-collection-with-optional-blob--fyga3x876n7rcnmn + - fnd-explorer-has-no-revision-aware-change-model--bqpg99cfmx25f8fe + - iss-explorer-cannot-review-changes-across-revisions--q4s8qjapczttpa9y +--- + +## Context + +The current feed exposes only the latest graph. Partial patches make reconnect and ordering behavior depend on missed events, and text diffs cannot distinguish graph meaning from Markdown layout. + +## Decision + +Define one host-neutral source-session JSON contract for static, paired, and live sources. Each complete snapshot names its source and revision and contains normalized nodes, relations, and source anchors. A pair identifies base and head. A live publisher sends a complete snapshot for every accepted revision; it does not send partial patches. + +Compute changes semantically by stable record IDs, normalized field values, and authored relations. Preserve exact spans for each record, frontmatter field, body, and authored relation. The canonical forward relation owns the authored span; derived reverse relations point to that change. Render Citation records as nodes and Blob records as attachments. + +## Consequences + +The Explorer can recompute the same diff after reconnect and can use one client model for stored comparisons and live work. Snapshot payloads are larger than patches. Revisit patch transport only if measured snapshot cost becomes a limit while complete-state recovery remains deterministic. diff --git a/.flatbread-proof/decisions/dec-keep-review-progress-private-and-explicit--gnanzqbpkvdwk1pv.md b/.flatbread-proof/decisions/dec-keep-review-progress-private-and-explicit--gnanzqbpkvdwk1pv.md new file mode 100644 index 00000000..fee0a2d3 --- /dev/null +++ b/.flatbread-proof/decisions/dec-keep-review-progress-private-and-explicit--gnanzqbpkvdwk1pv.md @@ -0,0 +1,25 @@ +--- +id: dec-keep-review-progress-private-and-explicit--gnanzqbpkvdwk1pv +effort: eff-effort-graph-memory-and-agent-wedge--szeqvmgqjqnhd002 +title: Keep review progress private and explicit +state: accepted +created_at: '2026-08-25T08:08:40.442Z' +derives_from: + - con-change-review-stays-additive-and-read-only--p7h7wrvwf3s10ykm + - dec-compare-complete-versioned-graph-snapshots--027nken1pmrw9byv + - iss-explorer-cannot-review-changes-across-revisions--q4s8qjapczttpa9y +--- + +## Context + +Graph lifecycle state is shared project knowledge. Review progress is personal and depends on which comparison a user has seen. + +## Decision + +Store Seen and Reviewed per user outside Proof. Mark Seen automatically when the user opens a change. Mark Reviewed only through an explicit action. Key progress to a change fingerprint, so a later change creates a new pending item without erasing earlier history. + +Support two scopes: PR changes compares the selected base and head; Since your review compares the current head with the user’s last reviewed snapshot. New live snapshots add pending changes without moving the graph. + +## Consequences + +V1 never writes personal state into the shared graph. A separate store may later synchronize progress across browsers, but the snapshot and diff contract does not depend on that store. diff --git a/.flatbread-proof/decisions/dec-show-changes-as-an-additive-review-overlay--tgp2rv0mj4wvwmct.md b/.flatbread-proof/decisions/dec-show-changes-as-an-additive-review-overlay--tgp2rv0mj4wvwmct.md new file mode 100644 index 00000000..aceaef06 --- /dev/null +++ b/.flatbread-proof/decisions/dec-show-changes-as-an-additive-review-overlay--tgp2rv0mj4wvwmct.md @@ -0,0 +1,21 @@ +--- +id: dec-show-changes-as-an-additive-review-overlay--tgp2rv0mj4wvwmct +effort: eff-effort-graph-memory-and-agent-wedge--szeqvmgqjqnhd002 +title: Show changes as an additive review overlay +state: accepted +created_at: '2026-08-25T08:08:35.603Z' +derives_from: + - con-change-review-stays-additive-and-read-only--p7h7wrvwf3s10ykm + - dec-compare-complete-versioned-graph-snapshots--027nken1pmrw9byv + - iss-explorer-cannot-review-changes-across-revisions--q4s8qjapczttpa9y +--- + +## Decision + +Mark a node Changed when its normalized content differs. Mark an added, removed, or modified relation Changed. Mark an otherwise unchanged endpoint of a changed relation Affected. Keep Changed and Affected as distinct labels. Keep removed records as selectable ghosts that show their base values. + +Frame the changed subgraph once when review opens. After that, camera and selection remain user-owned. New live changes enter a review rail and never move the camera. Keep the full graph selectable. Drawers open on the semantic diff and offer Base and Head views. + +## Consequences + +Review focus stays clear without turning the Explorer into a locked filtered graph. Large change sets need rail grouping and deterministic ordering, but they do not change navigation rules. diff --git a/.flatbread-proof/findings/fnd-explorer-has-no-revision-aware-change-model--bqpg99cfmx25f8fe.md b/.flatbread-proof/findings/fnd-explorer-has-no-revision-aware-change-model--bqpg99cfmx25f8fe.md new file mode 100644 index 00000000..edb2c771 --- /dev/null +++ b/.flatbread-proof/findings/fnd-explorer-has-no-revision-aware-change-model--bqpg99cfmx25f8fe.md @@ -0,0 +1,17 @@ +--- +id: fnd-explorer-has-no-revision-aware-change-model--bqpg99cfmx25f8fe +effort: eff-effort-graph-memory-and-agent-wedge--szeqvmgqjqnhd002 +title: Explorer has no revision-aware change model +kind: retrospective +created_at: '2026-08-25T08:08:23.538Z' +--- + +## Evidence + +- `packages/explorer/src/web/presets/proof/useProofLive.ts` fetches one graph and replaces the current node and edge arrays after each accepted generation. +- `packages/explorer/src/web/presets/proof/types.ts` has no revision, source-span, or change-state fields. +- `packages/explorer/src/web/app/components/GraphCanvas.tsx` clears focus when a selected record leaves the live graph. + +## Implication + +Revision review needs an explicit snapshot, diff, and review-state model. It cannot be inferred from lifecycle state or the latest node array. diff --git a/.flatbread-proof/issues/iss-explorer-cannot-review-changes-across-revisions--q4s8qjapczttpa9y.md b/.flatbread-proof/issues/iss-explorer-cannot-review-changes-across-revisions--q4s8qjapczttpa9y.md new file mode 100644 index 00000000..d5d7224e --- /dev/null +++ b/.flatbread-proof/issues/iss-explorer-cannot-review-changes-across-revisions--q4s8qjapczttpa9y.md @@ -0,0 +1,12 @@ +--- +id: iss-explorer-cannot-review-changes-across-revisions--q4s8qjapczttpa9y +effort: eff-effort-graph-memory-and-agent-wedge--szeqvmgqjqnhd002 +title: Explorer cannot review changes across revisions +kind: gap +status: open +created_at: '2026-08-25T08:08:25.921Z' +derives_from: + - fnd-explorer-has-no-revision-aware-change-model--bqpg99cfmx25f8fe +--- + +The Explorer reads one current graph. It cannot compare two revisions, preserve removed records for inspection, or track which changes a user has reviewed. Live updates replace the displayed graph without a durable review queue.