Proof. Request demo

Change and defect lineage

Every change should carry its proof.

Proof records why behavior changed, what it affected, how it was verified, and what remains uncertain—across features, refactors, and defect fixes.

01 / The comparison

A commit is not an explanation.

A commit says what text moved. A change record says why the behavior moved, what it affected, which evidence made the result acceptable, and what the change left unsettled.

GIT

  • what changed

PROOF

  • why it changed
  • what intent moved
  • what was affected
  • what evidence was required
  • who approved it
  • what remains uncertain

The sixth line

A change record that only prints good news is not evidence. Proof writes down what the change did not settle: obligations that still need to run, sibling cases nobody has swept, a class that is still open.

The rest of this page is that record, field by field.

02 / The change record

Features and fixes use the same record.

A feature, a refactor and a defect fix are the same object with a different type field. The fields stay the same. The evidence each type is held to does not.

CHG-260728-H6ER Active

TYPEfeature

TITLE

v1.5.0: Config, name aliases, streaming ReaderParser.

INTENT

opt-in parser Config, package-level name aliases, and a streaming ReaderParser over a bounded window

REQUIREMENTS

SYS-REQ-115 · SYS-REQ-116 · both approved, and both name this record as what moved them

IMPACT REVIEW

19 requirements re-read across 4 files, every row fingerprinted against a named revision

READINESS POLICY

requirements reviewed · no suspect links · tests and documents not demanded by this record

OWNER

human:buger · target release v1.5.0

Public audit evidence Read off proof/changes/CHG-260728-H6ER.yaml on jsonparser master, including the readiness policy, which is printed exactly as the record sets it.

A change record carries

  1. its type: feature, fix, refactor, migration, deprecation, security, performance or docs
  2. why the behavior is changing
  3. who owns it, and which release it is aimed at
  4. which requirements it introduces or moves
  5. the readiness policy it has to satisfy before it ships
  6. its status, and a history of who changed it when

The evidence itself hangs off the requirements the record names, and off the impact review that re-reads them. That is why the record above can be checked without taking a word of this page on faith.

The term

CHANGE RECORD is the evidence-bearing model Proof keeps for every change: features, refactors and defect fixes. A commit is not one, and an unresolved problem is not one either.

EVIDENCE, IN THREE STATES
The record model
Every change record names its type, the requirements it moves, and the readiness policy it has to satisfy.
Enforced today
A record’s type and status are checked against a fixed vocabulary when it is written, the requirements it names are walked by the impact review, and its title and intent are held to the same controlled-English lint the requirements are. Every approval has to name the record behind it, and a run fails when one does not; that is the check that holds the link, and it is why the two requirements above cite their record. The opposite direction, a record whose requirements have to cite it back, is only a warning, and it reads a record at all only when that record declares an explicit list of what it affects. The v1.5.0 record above declares none. A requirement reworded while its formal meaning and its evidence hold still blocks until somebody reviews that delta. Approvals and trace links stop counting when the code or the requirement under them moves.
Optional, configured
The check that reads a record’s declared type and looks for the evidence that type requires: for a fix, a defect record that resolves and that covers the changed file; for a feature, a change record whose requirement list covers the requirement under review. It warns when that evidence is missing; it does not block. Proof switches it on for every project it sets up, and the jsonparser corpus above runs with it on. Our own repository predates that default and has never turned it on, which is why this page does not claim it everywhere.

03 / Unresolved

Open issues arrive ready to reproduce.

A known issue is an unresolved problem. It stays open until the problem is resolved, and it carries what the next person needs to reproduce it and what Proof needs to judge the fix.

KNOWN ISSUE Open

STATEunresolved

WHAT IS WRONG

the problem, in one statement

VIOLATED REQUIREMENT

the intent this breaks

SEVERITY AND HAZARD

what it can cause downstream

AFFECTED COMPONENT

who owns the behavior

EXECUTABLE REPRODUCER

a test that pins the break today

RELEVANT CODE

where the behavior lives

EXPECTED AND OBSERVED

what the requirement promises, and what the code does today

REQUIRED BEFORE IT CAN CLOSE

agreed on the record before anybody writes the fix

Blank form Every value here is a slot, not a claim. This is the shape an open issue has to fill. A real one, filled in, is on the landing page.

Why the reproducer is the point

An issue without an executable reproducer is a report. An issue with one is a measurement: the same test decides later whether the fix worked, and it is kept after closure, so the case can never quietly come back.

Counting rule

A known issue is not a defect record. Proof never mixes unresolved issues and verified defect records into one number, because the two say opposite things about the software.

04 / The defect record

A verified fix becomes durable defect history.

When the issue is fixed, Proof writes a verified defect record: the same change record, plus the issue it came from and the evidence that settled it. The issue closes; the proof stays.

DEFECT-260726-MFPA Covered by requirement

RECORDverified defect record

TITLE

Set with array-index path component under an object parent produces malformed JSON output.

ORIGIN

Known issue KI-3

VIOLATED INTENT

SYS-REQ-009

REPRODUCER

set_spec_test.go · pins the break on the affected revision

FIX

parser.go · Set

INSTANCE

fixed

DISPOSITION

covered_by_requirement · reviewed by human:buger

DEFECT CLASS

obligation attached to SYS-REQ-009 / not declared closed

REGRESSION

two tests retained, permanently

Public audit evidence Read off proof/problem-reports/DEFECT-260726-MFPA.yaml on jsonparser master, with the same record opened field by field.

A verified defect record adds

  1. the originating issue
  2. the original reproducer
  3. the fixing change
  4. root cause
  5. the evidence proving the individual instance is fixed
  6. any evidence supporting closure of the wider defect class
  7. sibling-defect analysis
  8. permanent regression evidence
  9. human or policy approval

The instance and the class are two different claims. The record keeps them apart, and so does the next section.

The record beside this list is one of ours, so it is shown in the state it is actually in. The instance is fixed and the reproducer is kept. The record does not say the class is closed, and neither do we.

It stays on the requirement, so the next person or coding agent starts from what was learned. What the agent receives

05 / Closure

One green test does not close a defect class.

One passing reproducer can prove the known instance is gone. Closing the whole defect class takes broader evidence.

Rung 1

  • REPRODUCER PASSES

INDIVIDUAL INSTANCE FIXED

The reproducer that pinned the break passes after the fix. That settles the case in front of you, and only that case. The test is kept forever.

Rung 2

  • BROADER OBLIGATIONS PASS
  • SIBLING SWEEP
  • HAZARD EVIDENCE
  • BLAST-RADIUS VERIFICATION

DEFECT CLASS CLOSED

The class is every case that shares this root cause. Proof records it as closed only when all four are in. Until then, the record says what is attached and what is still open.

A passing reproducer is not a closed class. The two rungs stay on the record as two separate statements, so nobody has to guess which one was earned.

06 / Reach

Blast radius is measured before and after.

Every change record carries its reach. See it before you touch the code, and see it again, measured, after the change lands.

IF THIS CHANGES

  • 5 files
  • 13 tests
  • 1 parent requirement
  • related obligations
The reach is read from the dependency graph, not from a folder. Illustrative counts, drawn to shape; a real record lists every file and test by name.

Two readings, one record

Before the work, the reach is a warning: this is what the change can touch. After the work, the same list is a checklist: this is what was re-proven, and this is what was not.

The gap between the two readings is the honest part of the change, and it is written into the record where a reviewer sees it.

How the graph answers this

07 / Staleness

Changed evidence becomes stale automatically.

A change record does not only say what it proved. It says what it put in doubt.

  1. VERIFIED

    the obligation ran and passed on a known revision

  2. EVIDENCE STALE

    the code, the requirement, or the document under it moved

  3. VERIFIED

    confidence is restored against the new revision

Proof does not declare the requirement false. It withdraws yesterday’s confidence until the affected obligations are reviewed or rerun. The record carries the list, marked EVIDENCE REQUIRED, until somebody clears it.

This is why a change record is worth more than a green pipeline. A pipeline reports the tests that ran. The record also names the ones that should have run and did not.

08 / Release

What a release receipt is designed to contain.

A release is a set of change records. The receipt is what they add up to, with a route from every line back to the record that produced it. Part of this is computed today; the document itself is not written yet, and the panel below is the design for it.

RELEASE RECEIPT
CHANGE RECORDS
every change in the release, by type
REQUIREMENTS
introduced, changed, affected
EVIDENCE
what ran, and on which revision
KNOWN ISSUES OPEN
listed, never folded into the defect count
DEFECT RECORDS
instance and class stated separately
STALE OBLIGATIONS
what must be proven again
APPROVALS
who accepted the result, and when
WHAT REMAINS UNCERTAIN
stated, never omitted

Illustrative example Drawn to explain the shape a receipt is meant to have. This is not a record you can open, and no release has been rendered in this form yet.

What is computed today

A release is already a named object that lists the change records inside it, and Proof reads it back and reports where the release stands: which records are ready and what blocks the rest, the verification state of every requirement they touch, the known issues and accepted risks still open, and the evidence the plan still expects. The changelog is rendered straight off the records too.

What is not written yet is the single document, with the approvals and the defect records beside all of that. Every line it needs already exists as a record, so what is missing is the assembly, and we would rather say that than print a receipt nobody can open.

What we publish on our own work

How the evidence is produced

One record, from the reason to the receipt.

See a change move through Proof Request demo →

The short version is on the landing page · our public register →