Proof Walkthrough

Proof Walkthrough

The proof repositories show runnable step-by-step stories for generated, maintained, brownfield, recreated, and workflow-native app maps.

Status: current Audience: evaluators and maintainers inspecting proof repositories Use when: you need runnable proof/demo steps and what each checkpoint proves.

Topogram has current public proof repositories organized into focused product stories. They are tutorial-style demos, not fixtures. Use them when you want to see how the app map supports real work: branches, tags, README notes, SDLC records, agent packets, emitted contracts, and verification commands.

Five-Minute Demo Path

Use the brownfield proof when you want the shortest product demo:

git clone https://github.com/attebury/topogram-proof-content-approval-brownfield-v3.git
cd topogram-proof-content-approval-brownfield-v3
git checkout proof-03-adopt-app-map
npm install
npm run verify

Then inspect:

• proof/STEP.md for what the checkpoint proves;
• proof/artifacts/ for the extract/adopt plan, receipts, agent packets, and validation output;
• topo/ for the adopted app map.

That checkpoint shows the core Topogram move: existing React/Express/Prisma code becomes reviewed topo/ source, extraction evidence stays separate, and agents get focused packets before maintained-code changes.

If you have only a few minutes, do not read every file. Read proof/STEP.md, open the latest agent packet under proof/artifacts/, then compare the current tag with the previous proof tag. The useful question is: what did Topogram know before the code changed?

Beta Evaluation Path

For beta evaluation, read the proof repos as product demos:

1. Run the five-minute brownfield path above.
2. Open proof/artifacts/ and inspect the extract plan, adoption list, agent brief, and focused query packets.
3. Compare proof-03-adopt-app-map to proof-04-feature-from-slice to see how a maintained feature is planned from topo/ instead of rediscovering source.
4. Compare proof-06-recreate-other-stack and proof-07-parity-proof to see where Topogram can recreate a stack and where parity is only reported.
5. Use the focused XState or Step Functions proof when you want to inspect workflow-native extraction without the larger UI/API/DB proof story.
6. Use the focused widget design proof when you want to inspect semantic design mappings, component refs, and designer/developer review rows.
7. Use the Storybook design proof when you want to see Storybook metadata become review-only design realization candidates before explicit adoption.
8. Use the generated-to-maintained proof second to see how generate fits the same app-map model.

The demo claim is intentionally narrow: Topogram provides a reviewable map, focused agent context, contracts, and proof commands. It does not promise full runtime equivalence or pixel-perfect UI parity.

Proof Repos

Story	Repository	What It Proves
Brownfield extract/adopt	topogram-proof-content-approval-brownfield-v3	Start with a maintained app, extract candidates, adopt curated specs, implement a maintained feature from agent context, refresh drift, recreate another stack, and compare parity.
Generated to maintained	topogram-proof-content-approval-v3	Start from an initialized Topogram, generate an app, graduate output to maintained ownership, then use Topogram for maintained feature and DB migration guidance.
Widget design realization	topogram-proof-widget-design-realization	Map one semantic widget to web, iOS, and Android component refs; prove rendered, contract-only, implementation-owned, unsupported, and review states through JSON coverage, a designer-readable Markdown matrix, ui-realization-report, and a widget slice. See Map A Design System.
Storybook design extraction	topogram-proof-storybook-design-realization	Start with static CSF Storybook stories, extract explicit parameters.topogram metadata as review-only design_realizations, adopt the mapping into a canonical design_realization_set, then prove coverage, realization report, and widget slice output.
Workflow-native extraction	topogram-proof-xstate-workflow	Start with an XState app, extract workflow candidates through a package-backed extractor, adopt a workflow map, use compact slices for a maintained source change, then refresh and adopt workflow drift.
Workflow-native extraction	topogram-proof-step-functions-workflow	Start with a local Step Functions ASL definition, extract workflow candidates through a package-backed extractor, adopt a workflow map, use compact slices for a maintained source change, then refresh and adopt workflow drift.

The brownfield proof is the fastest way to understand Topogram’s main differentiator: it turns existing code into reviewable app-map evidence, then uses that map to guide agent-safe maintained changes. The generated-to-maintained proof shows the same map starting from a template instead of an existing app.

The proof repos expose a Proof Verification workflow, npm run proof:audit, and npm run verify. They also use SDLC to show the recommended habit, but SDLC is not required for ordinary Topogram users.

topogram release status --strict tracks these repos as proofConsumers, not as normal package rollout consumers. A release is considered current when proof repos meet the configured proof baseline, expose the audit/verify scripts, and have green Proof Verification workflows. The current v3 content-approval proof baseline is @topogram/[email protected]; the focused XState proof is pinned to @topogram/[email protected] and @topogram/[email protected]. The focused Step Functions proof is pinned to @topogram/[email protected] and @topogram/[email protected]. The widget design proof is current on @topogram/[email protected] because the designer-readable design matrix changed the demo story. The Storybook design proof is pinned to @topogram/[email protected] and uses the package-backed Storybook extractor from its GitHub repo until the npm package is published. Proof repos do not need to be repinned for every CLI patch; refresh them when the product demo story changes. The v2 repos remain public historical demos.

When a proof repo is created or materially refreshed, close the work with a learning review. Promote what the proof taught into current docs, llms.txt, journeys, glossary, agent guidance, release/proof tracking, or backlog records. If the proof revealed no product-facing gaps, record that explicitly in the linked plan before marking the proof task done.

How To Read A Proof

1. Open the repo and confirm the Proof Verification badge is green.

2. Read proof/README.md for the step map.

3. Check out a proof tag:

   git fetch --tags
   git checkout proof-03-ui-i18n-aria-proof
   cat proof/STEP.md
   npm install
   npm run verify

4. Inspect proof/artifacts/ for the machine-readable proof.

5. Compare the current tag with the previous tag when you want to see exactly what changed.

npm run verify is intentionally the only command a reader needs to trust at a checkpoint. In the v3 repos it runs the proof audit, path-hygiene audit, Topogram validation when topo/ exists, SDLC validation when adopted, app verification, recreated-stack compilation when present, and a final clean worktree check.

What Agents Should Read

The proof repos intentionally commit agent-facing artifacts. These are the files an implementation agent would normally read instead of loading the whole repo:

• agent-brief.json: read order, edit boundaries, workflow commands, and trust or policy state.
• *-task-slice.json: focused SDLC/task context for one implementation slice.
• *-single-agent-plan.json: implementation plan for maintained app edits.
• ui-surface-contract.json, ui-widget-contract.json, and widget reports: UI contracts and conformance checks.
• DB snapshots, migration plans, and SQL migration artifacts: generated or maintained migration evidence.
• extract/adopt plans and receipts: brownfield candidate review and adoption proof.

For current engine UI work, also inspect ui-realization-report and generated generation-coverage.json outputs. For design-system work, inspect ui-design-coverage --format markdown first; it is the widget-first matrix a designer or front-end lead can read without parsing JSON. The v3 proof repos are pinned baseline stories; they do not move for every patch-level generator improvement.

Story 1: Generated To Maintained

The generated proof walks through:

Step	Checkpoint	What To Notice
01 init SDLC baseline	proof-01-init-sdlc-baseline	topogram init --adopt-sdlc creates an empty app map with enforced SDLC guidance.
02 generated content approval	proof-02-generated-content-approval	The app map generates a content approval app and verifies compile.
03 UI i18n/ARIA proof	proof-03-ui-i18n-aria-proof	Widgets, screen bindings, behavior, i18n/ARIA contracts, and UI realization reports become the development guide.
04 generated DB migration	proof-04-generated-db-migration	DB snapshots and SQL migration output are generated while app output is still generated-owned.
05 graduate maintained	proof-05-graduate-maintained	topogram generate refuses to overwrite maintained output.
06 maintained feature from slice	proof-06-maintained-feature-from-slice	Agent/query packets guide direct maintained app edits.
07 maintained DB migration	proof-07-maintained-db-migration	Topogram emits migration proposals; humans/agents adapt maintained DB files directly.

Use this story when you want to understand the greenfield path: start with a generated project, keep the generated loop while it is useful, then graduate the app to maintained ownership without throwing away the topo/ contract.

Story 2: Brownfield Extract/Adopt

The brownfield proof walks through:

Step	Checkpoint	What To Notice
01 brownfield baseline	proof-01-brownfield-baseline	A working React/Express/Prisma app exists with no topo/.
02 extract with packages	proof-02-extract-with-packages	Package-backed extractors create review-only candidates and provenance.
03 adopt app map	proof-03-adopt-app-map	Curated candidates become canonical topo/; extraction output remains evidence.
04 feature from slice	proof-04-feature-from-slice	A maintained feature is implemented from Topogram context packets.
05 refresh drift	proof-05-refresh-drift	Source/spec drift is detected and reviewed without silent adoption.
06 recreate other stack	proof-06-recreate-other-stack	The adopted Topogram generates a SvelteKit/Hono/Postgres recreation beside maintained source.
07 parity proof	proof-07-parity-proof	Contracts and verification reports compare maintained and generated stacks.

Use this story when you want to understand the brownfield path: extract candidates from existing source, review and adopt only the useful contracts, keep the original app maintained, then use the adopted topo/ to guide features or recreate another stack.

Story 3: Workflow-Native Extraction

The XState proof walks through:

Step	Checkpoint	What To Notice
01 XState baseline	proof-01-xstate-baseline	A working XState review workflow exists with no topo/.
02 extract workflow candidates	proof-02-extract-workflow-candidates	The package-backed XState extractor emits review-only workflow candidates and provenance.
03 adopt workflow map	proof-03-adopt-workflow-map	Curated workflow evidence becomes canonical topo/, SDLC is enabled, and agent packets are emitted.
04 workflow slice guides change	proof-04-workflow-slice-guides-change	A compact workflow slice guides a maintained source change without manually editing canonical workflow records.
05 refresh and review drift	proof-05-refresh-and-review-drift	Extraction refresh surfaces workflow drift, then selected updates are reviewed and adopted.

Use this story when you want the smallest proof of package-backed workflow extraction. It isolates the workflow-native path from broader brownfield DB/API/UI concerns.

The Step Functions proof walks through the same shape with local Amazon States Language source:

Step	Checkpoint	What To Notice
01 Step Functions baseline	proof-01-step-functions-baseline	A working local ASL review workflow exists with no topo/.
02 extract workflow candidates	proof-02-extract-workflow-candidates	The package-backed Step Functions extractor emits review-only workflow candidates and provenance.
03 adopt workflow map	proof-03-adopt-workflow-map	Curated workflow evidence becomes canonical topo/, SDLC is enabled, and agent packets are emitted.
04 workflow slice guides change	proof-04-workflow-slice-guides-change	A compact workflow slice guides a maintained ASL source change without manually editing canonical workflow records.
05 refresh and review drift	proof-05-refresh-and-review-drift	Extraction refresh surfaces workflow drift, then selected updates are reviewed and adopted.

Use this story when you want the same workflow-native proof against an infrastructure/orchestration format instead of an application state-machine library.

Story 4: Storybook Design Extraction

The Storybook proof walks through:

Step	Checkpoint	What To Notice
01 Storybook baseline	proof-01-storybook-baseline	A component library has static CSF stories with explicit parameters.topogram metadata and no adopted topo/.
02 extract candidates	proof-02-extract-candidates	The package-backed Storybook extractor emits review-only design_realizations candidates plus provenance and adoption plan output.
03 adopt realization	proof-03-adopt-realization	Curated Storybook evidence becomes a canonical design_realization_set.
04 report and slice	proof-04-report-and-slice	ui-design-coverage, ui-realization-report, and a widget slice expose the adopted component ref and remaining design review work.

Use this story when you want to see how a design/component registry can propose widget-to-component mappings without becoming the source of truth.

What The Proofs Are Not

The proof repos are not release consumers that must move on every patch and they are not a promise that every stack has identical runtime behavior. They are known-good product stories pinned to a CLI baseline. Refresh them when a command workflow changes, a breaking change lands, or the committed artifacts would teach stale behavior.

Current Limits

The proofs show contract, compile, and workflow parity. They do not claim pixel parity, full production deployment readiness, or exhaustive runtime equivalence. When a proof cannot establish something, it should say so in the step result or parity report.