docs: add the README diagrams and contribution guidance - #2
Merged
Merged
Conversation
Three diagrams carry what prose was doing badly. The architecture diagram shows one wright, four pinned lanes and a fresh reader in a single glance. The proof diagram puts a verified run beside a refused one so the difference between exit 0 and exit 69 is visible before anyone reads a paragraph. The routes diagram is the cheapest-first decision table, with solo marked as the default and ensemble as the exception. verify.sh now fails if the README references an image that does not exist, and if any of the three diagrams stops being used. A README that renders a broken icon in its first screen is a defect, so it is checked rather than remembered. The verify badge no longer states a check count. Nothing could enforce that number without a fixed-point problem - adding the guard would change the count it guards - and an unenforced number is exactly the kind of claim this project argues against. The test count stays, because the verifier does check it. The contributing section states the flow plainly: main is protected, every change arrives as a pull request, CI must be green on both runners, and the maintainer merges. Contributors are pointed at the traps section first, since the code carries no inline commentary and that is where the reasoning lives.
Makes review assignment automatic rather than remembered, which matters once the repository is public and changes arrive from people who have never seen it before.
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.
What this changes
Adds the three README diagrams, enforces that they exist, and states the contribution
flow now that the repository is public.
Why
The README referenced three images that did not exist, so the first screen rendered
three broken-image icons. It also stated a verify check count that nothing enforced, and
said nothing about how a contributor is meant to propose a change.
What is in it
The diagrams. Architecture (one wright, four pinned lanes, one fresh reader), proof
(a verified run beside a refused one, so the difference between
exit 0andexit 69isvisible before anyone reads a paragraph), and routes (the cheapest-first decision table,
solomarked as the default andensembleas the exception). All three losslesslyre-encoded and verified pixel-identical to the originals.
Enforcement.
verify.shnow fails if the README references an image that does notexist, or if any of the three diagrams stops being used. Proven by removing one and
watching the gate fail.
One claim removed. The verify badge no longer states a check count. Nothing could
enforce that number without a fixed-point problem — adding the guard would change the
count it guards — and an unenforced number is precisely what this project argues against.
The test count stays, because the verifier does check it.
Contribution flow.
mainis protected, every change arrives as a pull request, CImust be green on both runners, and the maintainer merges. Contributors are pointed at the
traps section first, since the code carries no inline commentary and that is where the
reasoning lives.
CODEOWNERS, so review assignment is automatic rather than remembered.
Evidence
Both gates are offline and pass identically on a runner with neither model CLI installed.
Risk
Documentation and one verifier addition. No script that dispatches a lane, proves routing,
or installs a profile is touched.
Note for review
docs/images/proof.pnghas a minor rendering artifact in its caption — it reads"runtimie s own" rather than "runtime's own". Everything else in all three images is
correct. Worth a regeneration at some point; not worth blocking this.