docs: reconcile current-state documentation after the v1.229.4-.6 release train - #1282
Merged
Conversation
Contributor
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
…ease train
Two documents made claims that were true when written and are no longer.
REPRODUCIBLE_BUILDS.md declared "Go 1.23.0 or later (as specified in go.mod)"
while go.mod declares 1.25.13, and told readers to expect go1.23.x from a
released binary. It also said nothing about build-tree cleanliness, which is now
a pre-publication requirement rather than an observation.
It now records both +dirty producers and keeps them distinct, because conflating
them would send the next investigation to the wrong build path:
release.yml / nftband __pycache__ fixed v1.229.4 confirmed on the artifact
SLSA builder / nftban-core vendor/ fixed v1.229.6 confirmed on the artifact
The reader-facing commands in that section were run against the published
v1.229.6 nftban-core before being documented.
DESIGN_PRINCIPLES.md gains the evidence-authority principle. Each rule in it was
derived from a measured defect in this release train, not from theory:
DESIGN -> VERIFY -> CONFIRM
A BLOCKING PROPERTY MUST BE VERIFIED BEFORE THE ACTION IT BLOCKS
IMPLEMENTATION LINE IDENTICAL != SUBJECT POPULATION IDENTICAL
ONE AUTHORITY != COMPLETE AUTHORITY OUTPUT
Hygiene pass over the current-state surfaces found no other live declaration
naming a deleted authority. Every remaining mention of slsa-go-releaser.yml is
either a historical comment or a negative guard asserting the file has NOT
returned, and no non-comment workflow reference exists. CHANGELOG history is
deliberately untouched: HISTORICAL REFERENCE != LIVE DECLARATION.
…ples The Evidence Authority section pointed readers at NFTBAN_ROADMAP/V1_229_6_RELEASE_CLOSURE.md. That path is not in this repository — the roadmap register is internal — so a reader following the citation from published documentation finds nothing. The provenance statement itself is kept: these rules were derived from measured defects in the v1.229.4-v1.229.6 release train rather than from theory. Only the unresolvable path is removed. Both factual claims in REPRODUCIBLE_BUILDS.md were re-verified against current main before landing, not merely checked for merge conflicts: go.mod declares go 1.25.13, and "Gate 4: Shipped binary build metadata" in release.yml is a real pre-publication gate that fails on compiler mismatch and treats unreadable metadata as not-pass.
itcmsgr
force-pushed
the
docs/v1229-6-closure-hygiene
branch
from
September 6, 2026 20:33
362e034 to
c71790e
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Docs-only closure hygiene. No VERSION or CHANGELOG change.
Stale current-state claims corrected
docs/REPRODUCIBLE_BUILDS.mddeclared Go 1.23.0 "as specified in go.mod" —go.moddeclares 1.25.13 — and told readers to expectgo1.23.xfrom a released binary.It also documented nothing about build-tree cleanliness, which is now a pre-publication requirement. It now records both
+dirtyproducers, kept distinct:release.yml(nftband)__pycache__/nftban-core)go mod vendorThe reader-facing observation commands were run against the published v1.229.6
nftban-corebefore being documented:Engineering philosophy
docs/DESIGN_PRINCIPLES.mdgains the evidence-authority principle —DESIGN -> VERIFY -> CONFIRM, enforcement vs confirmation, subject-population instability across topology changes, authority uniqueness vs completeness, and separation of authority. Every rule traces to a measured defect in this train.Hygiene pass result
No live declaration names a deleted authority. Every remaining
slsa-go-releaser.ymlmention is a historical comment or a negative guard asserting the file has not returned; no non-comment workflow reference exists. The temporary hourly witness cron is gone (weekly restored). CHANGELOG history untouched — HISTORICAL REFERENCE != LIVE DECLARATION.