Repository navigation
docs: lead the README with the problem, not the machinery - #2
Merged
Merged
Conversation
The README opened on immutable contracts, a ranked frontier, a verifier and cascade — four terms before a reader knew what any of it was for. The two failures that motivate the whole protocol (agents collide on files, PRs stall on human review) were a subordinate clause two thirds of the way down the Prove2Me paragraph. New "Why this exists" section puts them first, then the Prove2Me answer (move trust from review to immutable statements plus a checker), then the bridge the README never spelled out: in Lean the checker is free, so what plays the compiler's part in software? Every unit of work carries its own acceptance command. Mirrors the structure README.zh-CN.md now uses. Also: - Fixes the stale count. "all twelve contracts are Done / 12 done / 0 open" predated declared-laws, which was published after root closed and is imported by no decomposition. verify.mjs derives 13 done / 0 open; the badge was already right. The seven-session cost paragraph keeps its twelve — that run genuinely covered twelve contracts. - Race 001 and the self-reference lesson become subsections. They are the receipts for "the kernel judges admissibility, not quality" and "run a gate red before publishing it", and were easy to skim past as prose. - Architecture renamed "How it runs" and moved next to the agent loop it describes; Security and Known limits moved below the sections a new reader needs first. No links dropped, no sections dropped. verify.mjs and all three law checks exit 0. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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
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.
Companion to #1 — the same treatment applied to the English README, so the two files now mirror each other section for section.
The README opened on immutable contracts, a ranked frontier, a verifier and cascade: four terms before a reader knew what any of it was for. The two failures that motivate the whole protocol — agents collide on files, PRs stall on human review — were a subordinate clause two thirds of the way down the Prove2Me paragraph.
New
## Why this existsPuts them first, then the Prove2Me answer (move trust from review to immutable statements plus a checker), then the bridge the README never spelled out:
Stale count fixed
all twelve contracts are Done / 12 done / 0 openpredateddeclared-laws, which was published after root closed and is imported by no decomposition.verify.mjsderives 13 done / 0 open; the badge was already right.The seven-session cost paragraph keeps its twelve — that run genuinely covered twelve contracts, so changing it would introduce a new error rather than fix one.
Structure
###subsections. They are the receipts for the kernel judges admissibility, not quality and run a gate red before publishing it, and were easy to skim past as prose.## Architecturerenamed## How it runsand moved next to the agent loop it describes; the lock-free consequences are now a list.Checks
No links dropped and no sections dropped (diffed the heading and link sets against HEAD). Locally
verify.mjsexits 0 at 13 done / 0 open, andl4-english,l5-tool-size,l6-status-honestall exit 0.🤖 Generated with Claude Code