Change and defect lineage
A Proof change record connects the reason for a change to what actually moved, what it affected, how it was tested, and why the result was accepted.
01 / The comparison
A commit says what text moved. A Proof change record says why the behavior moved, which components and requirements were affected, what code and documentation changed, and which evidence made the result acceptable.
GIT
PROOF
The sixth line
A change record that only prints good news is not evidence. Proof writes down what the change did not settle: the obligations that still need to run, the sibling cases nobody has swept yet, the class that is still open.
The rest of this page is the shape of that record, field by field. The short version is on the landing page.
02 / Kind: feature
A feature change is a change record with the kind set to feature. It is the same object as a fix, and it answers the same questions: what new behavior was intended, which requirements moved, and what made the result acceptable.
KINDfeature
INTENT
Support nested array updates.
COMPONENTS
parser
REQUIREMENTS
2 added · 3 affected
IMPLEMENTATION
4 files
DOCUMENTATION
1 document updated
EVIDENCE
8 tests · 2 properties · hazard review
APPROVED BY
maintainer
Worked exampleAn illustrative record, drawn to shape. The fields are the schema every feature change fills in; a real one is opened field by field in section 04.
A feature change records
A refactor and a behavior change use the same record with a different kind. The fields do not change; the evidence the record demands does.
03 / Unresolved
A known issue is an unresolved problem. It carries everything the next person needs to reproduce it and everything Proof needs to judge the fix. An issue remains open while the problem remains unresolved.
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 BEHAVIOR
what the requirement promises
CURRENT OBSERVED BEHAVIOR
what the code does instead
Blank formEvery value here is a slot, not a claim. This is the shape an open issue has to fill, so no identifier and no values are filled in.
Why the reproducer is the point
An issue without an executable reproducer is a report. An issue with one is a measurement, and the same test decides later whether the fix worked.
The reproducer 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 / Kind: defect fix
When the issue is fixed, Proof creates a verified defect record that preserves the fix and its evidence. It uses the same evidence-bearing model as any other change. The issue closes; the proof stays.
KINDdefect fix
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
Real recordRead off proof/problem-reports/DEFECT-260726-MFPA.yaml on our public project, with the same record opened field by field.
A verified defect record records
Two of those lines are different claims: the instance and the class. 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.
05 / Closure
One passing reproducer can prove the known instance is gone. Closing the whole defect class takes broader evidence.
Rung 1
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, so this instance cannot return unseen.
Rung 2
DEFECT CLASS CLOSED
The class is every case that shares this root cause. Proof records it as closed only when the wider obligations pass, the sibling cases are swept, the hazard has evidence against it, and the blast radius is verified again. Until all four are in, 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
Every change record carries its reach. See the blast radius before you touch the code, and see it again, measured, after the change lands.
IF THIS CHANGES
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. It is written into the record instead of being left for a reviewer to notice.
07 / Staleness
Software knowledge becomes dangerous when it silently goes stale. A change record does not only say what it proved. It says what it put in doubt.
VERIFIED
the obligation ran and passed on a known revision
EVIDENCE STALE
the code, the requirement, or the document under it moved
VERIFIED
confidence is restored against the new revision
Proof does not automatically 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, and it stays there 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 / Retained
None of this is written for an archive. The history is the working context for the next change, and it is read the same way by a person and by a coding agent.
The history is the context
Ask the record what a component promises, what broke it last time, which test proves it, and which obligations are still stale. The answer is retrieved, not remembered by whoever happened to be there.
Your coding agent gets the same model of the software that your engineers use. It reads the same requirements, the same reproducers, and the same open questions.
09 / Release
A release is a set of change records. The receipt is what they add up to, in one document, with a route from every line back to the record that produced it.
A receipt nobody has to write
No line here is a summary somebody typed at the end of the quarter. Each one is assembled from records that already exist, and each one can be opened.
That is also what makes it safe to show outside the team. A receipt that can be checked is worth reading; a status report is not.
One record, from the reason to the receipt.
The short version is on the landing page · our public register →