Evidence-Backed Software Changes

01 / The comparison

A commit is not an explanation.

A commit says which text moved. A change record says why the behavior moved, what it can affect, which evidence ran against this revision, and what is still unresolved. That evidence can be a check, a scenario, or a narrated demo. A green check is readiness. Acceptance is a separate decision.

GIT

what changed

PROOF

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

Still unresolved

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.

02 / The change record

Features and fixes use the same record.

A feature, a refactor, and a fix share one record shape. The type changes. So does the evidence that type is held to.

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 Taken from proof/changes/CHG-260728-H6ER.yaml on jsonparser master. The readiness policy is printed as the record sets it.

A change record carries

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

The evidence sits on the requirements the record names, and on the impact review that re-reads them. You can check the record above without taking this page on faith.

The term

A change record is the evidence Proof keeps for a feature, a refactor, or a fix. A commit is not one. 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: Proof checks a record’s type and status against a fixed vocabulary when the record is written. The impact review walks the requirements it names. Title and intent use the same controlled-English lint as the requirements. Every approval has to name the record behind it. A run fails when one does not. That check holds the link, which is why the two requirements above cite their record. The reverse check reports at warning severity; whether it fails the audit depends on the effective threshold. It reads a record only when that record declares 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: One check reads a record’s declared type and looks for matching evidence. For a fix, that is a defect record that resolves and covers the changed file. For a feature, that is a change record whose requirement list covers the requirement under review. It reports missing evidence at warning severity. The audit defaults to failing at warning severity unless the effective configuration changes that threshold. Repository protection determines whether that failed run blocks a merge. Proof switches it on for every project it sets up. The jsonparser corpus above runs with it on. Our own repository predates that default and has never turned it on. This page does not claim the check 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. It is 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 Taken from proof/problem-reports/DEFECT-260726-MFPA.yaml on jsonparser master. The same record is on the jsonparser page.

A verified defect record adds

the originating issue
the original reproducer
the fixing change
root cause
the evidence proving the individual instance is fixed
any evidence supporting closure of the wider defect class
sibling-defect analysis
permanent regression evidence
human or policy approval

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

This record is shown as it actually stands. 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. Retain the regression check and review its applicability as the product changes.

Rung 2

BROADER OBLIGATIONS PASS
SIBLING SWEEP
HAZARD EVIDENCE
BLAST-RADIUS VERIFICATION

CLASS CLOSURE REVIEW

Define the root cause, the paths reviewed and the exclusions. These four evidence categories support a class-closure review; their presence alone does not prove every related failure impossible. Record the conclusion and any unresolved sibling risks.

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

Illustrative counts, not a folder listing. Recorded links identify candidate files and tests. Missing links limit that reach; it is not a measurement of every runtime effect.

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

Evidence has a basis. Changes can break it.

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
a change lands
EVIDENCE STALE

a recorded input changed and the applicable check marked the result stale
obligations rerun
VERIFIED

the rerun supports its stated claim on the new revision

Stale evidence does not make the requirement false. It means the old result no longer establishes the claim on the recorded current basis. Inspect the relevant inputs and renew the evidence. Unknown dependencies and inputs outside the configured freshness checks remain gaps.

The change record connects required evidence to observed results, including missing or failed work. CI executes and enforces configured checks. Inspect a runnable change example and see which parts are supplied by the fixture.

08 / Release

What a release receipt is designed to contain.

A release is a set of change records. The receipt would trace every line back to the record that produced it. That document is not written yet. The panel below is the design.

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 A design for the shape, not a record you can open. No release has been rendered in this form yet.

What is computed today

A release is already a named object that lists its change records. Proof reads it back and reports where the release stands: which records are ready, 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 from those records.

The single document is not written yet. It would place the approvals and the defect records beside that report. Every line already exists as a record. What is missing is the assembly. This page will not print a receipt nobody can open.

What we publish on our own work

How the evidence is produced

A change carries its intent, its reach, the evidence, and what is still unresolved.

See a change move through Proof Bring one real change →

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

Every change should carry its proof.