Skip to content

docs: lead the README with the problem, not the machinery - #2

Merged
shitianfang merged 1 commit into
mainfrom
docs/en-readme-problem-first
Sep 11, 2026
Merged

shitianfang merged 1 commit into
mainfrom
docs/en-readme-problem-first

Conversation

@shitianfang

Copy link
Copy Markdown
Owner

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 exists

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 that checker is free: the compiler says it type-checks, and it is proved. […] build2me asks the obvious follow-up: in software, what plays the part of the compiler? The answer it commits to: every unit of work carries its own acceptance command.

Stale count fixed

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, so changing it would introduce a new error rather than fix one.

Structure

  • 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; the lock-free consequences are now a list.
  • Security and Known limits moved below the sections a new reader needs first.

Checks

No links dropped and no sections dropped (diffed the heading and link sets against HEAD). Locally verify.mjs exits 0 at 13 done / 0 open, and l4-english, l5-tool-size, l6-status-honest all exit 0.

🤖 Generated with Claude Code

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>
@shitianfang
shitianfang merged commit 651ecd3 into main Sep 11, 2026
2 checks passed
@shitianfang
shitianfang deleted the docs/en-readme-problem-first branch September 11, 2026 16:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant