Catch breaking API changes before a release ships
Usually the architect or tech lead signing off a release, with the shipping team
Compare the app as released with the branch about to ship, and see which endpoints, events and tables the release changes for the systems that call them.
The problem
The release notes say what the team meant to change. They do not say which endpoint lost a parameter on the way, which event's type list shrank, or which table dropped a column another system reads. Those turn up as the first incident after the deploy, raised by the team that calls you.
Contract tests catch what someone thought to test. A beta environment catches what someone thought to click. Neither lines the branch up against what runs today and lists every contract that differs, with who depends on it.
How it goes
The same steps the product’s playbook walks. Each one shows the screen at that moment.
Name the branch
On the root board, declare a release check: the app as it runs today on one side, a branch of the same app on the other, named by its branch. The app keeps following the branch it deploys from; the check follows the one about to ship.
Extract from the branch
On the branch the app deploys from, run the extraction and let it read the release branch too, without switching. Its tables, endpoints and event channels land in the check; the app's own map stays as released. A checkout of the release branch stops every command, so the map and weekly diary follow what is live.
Read what the release changes
One table: every contract the live app serves, read kept, changed, gone or new on the branch. A changed row names what differs, a parameter lost or a response status gone. A flag marks a change under a critical rule, or a gone contract another system calls, and names that system.
Accept or fix
A change you meant is accepted with a reason and leaves the count. A change you did not mean becomes a work item on the app, with the contract attached, for the team to fix before the merge. The app's hub says a breaking change is on the way to release while either is open.
Ship, then close the check
A release check stays open until you close it. Each extraction replaces the branch's side in full, so the table always reads the branch as it is now. When the branch ships and the released branch catches up, the table reads every contract kept, and you close the check.
- Done
End proofDone when every contract the release changes or drops is accepted with a reason or has a work item, before the branch merges.
Works with
- Code
- The repository read by the code plugin on two branches, locally inside Claude Code, Codex or Cursor; derived metadata is pushed, never your source.
- Contracts
- Tables, endpoints, event channels, pages and outbound calls, each with the file and line it was read from on each branch.
- Branches
- One release or beta branch per check. The app's own map keeps following the branch it deploys from; the check's side is replaced on every push from the tracked branch.
- Change rules
- Your organization's rules say which contracts are compared and whether a type spelled differently reads as a note or as a change.
- Plans
- Every step runs on the Free plan.
Where it stops
- A check compares contracts: what the branch serves to callers. The branch's structure, its services and their dependencies, is not compared, and the branch records no weekly diary of its own.
- A type or schema spelled differently reads as a note on a kept row unless the rule is set to read shapes. A field the extraction could not cite reads as not read, never as a change.
- The table is as fresh as the last extraction on the branch. Nothing watches the branch for you; the team runs the extraction before the release review.
- The branch's contracts land in the check and nowhere else. A sync or a diary run from that branch is refused and names the check, so the app's map never shows what has not shipped.
Why not a diagram, or a code browser
A diagram shows
The architecture as drawn, the same before and after the release. Nothing in it knows that the branch about to merge drops a column or renames a parameter.
A code browser shows
The diff, line by line, in one repository. It shows every file that changed and leaves you to work out which lines are a contract another system depends on.
ProvenMap shows
The released app and the branch read into one table of contracts, each kept, changed, gone or new, with the system that calls each changed one named from its own code. What you accept and what you fix sit on the same table, and the check stays for the next release.
Walk through it
- The docs walkthrough of this job is being written.
The features behind it
Start with one system
Map a real system and see the architecture around it.
Open one repository and run the code plugin. No migration, no rollout, no diagramming.
No credit card · Analysis runs locally in your own session · Self-hosted available
See the four commands to your first board →
Or for writing on architecture that stays connected across systems.