docs: rewrite README + ROADMAP + EXPLAINME for outside readers#113
Merged
Conversation
Refactors the three top-level overview documents around the actual post-2026-05-20 state of the project and around an "outside reader" audience that needs to navigate from "what is this?" to the specific proofs / files / tests in a few clicks. ## README.adoc - New opening positioning: dyadic linear+affine, compile-time WASM safety, no GC. Concrete enough to evaluate at a glance. - Sections reorganised: Why "Ephapax" / What this is / What this isn't / Hello-world / Quickstart / Project structure / Formal foundations / Surface syntax / Component status / Documentation map / Quickstart files by audience / Related work / Contributing. - "Documentation map" table links every other top-level .adoc/.md with one-line "what it covers" — collapses the previous flat list. - "Quickstart files by audience" routes outside observers, end users, developers, and maintainers to the right file. - Component status table replaces ad-hoc emoji status — adds "Notes" column with the actual blocking work per component. - Formal foundations: separates Coq (dynamic side) from Idris2 (structural side), names the actual lemmas Qed/Admitted, links PRESERVATION-HANDOFF for picking up the preservation work. ## ROADMAP.adoc - Replaces the stale "all Coq Admitted proofs closed 2026-04-27" v1.0 entry with the honest reduction-story state: preservation 22 open / 910 closed. - New "Formal-proof status" section per-theorem table for both Coq and Idris2 — single source of truth for what's Qed/Admitted/total/ covering and why. - v0.1 blocker explicitly named: close preservation to Qed. - v1.0 explicitly requires the Idris2 Parse/Parser.idr covering→total upgrade. - Cross-links to README/EXPLAINME/PROOF-NEEDS/PRESERVATION-HANDOFF at the bottom so a reader landing on ROADMAP first can navigate outward. ## EXPLAINME.adoc - Quotes the new README opener (was the older "dyadic language — one part affine, the other linear" line). - New §"Claim: Mechanically Proved Soundness" section walks through the actual per-theorem status with file:line citations and the reduction story for preservation. - §"Test Evidence" updated to "~229 tests across ~19 crates" with explicit crate names per category. - §"Design Documents" links the new PRESERVATION-HANDOFF.md + PROOF-NEEDS.md + the vision document. No proof or code changes; documentation only. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
hyperpolymath
added a commit
that referenced
this pull request
May 21, 2026
…122) Closure sweep after PR #116 took preservation from 22 → 12 open goals and PR #121 landed Phase 1 scaffold. Updates the preservation-count claims across docs to reflect 12, and adds a CHANGELOG entry summarising the full 2026-05-20 → 2026-05-21 reduction campaign. ## Files updated | File | What changed | |---|---| | `README.adoc` | Coq formal-foundations paragraph; reduction chain now lists all 8 PRs through #121; clear pointer to ROADMAP closure plan | | `ROADMAP.adoc` | Formal-proof status table row (`12 open goals`); v0.1 blocker entry; v1.0 status; 97.6% → 98.7% reduction figure | | `EXPLAINME.adoc` | Coq theorem table; reduction-story bullets extended through #114, #116, #121 | | `CHANGELOG.md` | New "Proof state" + "Documentation" sections under `[Unreleased]` tracking the full PR chain (#92, #102, #104, #106, #114, #115, #116, #117, #121) + the Idris2 totality campaign (#89–#100) + doc/wiki refresh (#113 + wiki) | ## Companion wiki update `Home.md`, `Proof-status.md`, `What-can-go-wrong.md` updated in the wiki repo with the same 22 → 12 figures + extended reduction story. Pushed separately to wiki master. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.7 (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
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.
Summary
Refreshes the three top-level overview documents (
README.adoc,ROADMAP.adoc,EXPLAINME.adoc) around:%default total), the honest "Admitted" status replacing the stale "all proofs closed 2026-04-27" claim.What changed
README.adoc
.adoc/.mdwith a one-line "what it covers" — collapses the previous flat list of links into a navigable index.PRESERVATION-HANDOFF.mdfor picking up the preservation work.ROADMAP.adoc
preservationto Qed.Parse/Parser.idrcovering→total upgrade.EXPLAINME.adoc
PRESERVATION-HANDOFF.md+PROOF-NEEDS.md+ the vision document.Out of scope
agda/idris2/webassembly/formal-verification/affine-types/region-calculus/compiler/operational-semantics/programming-language)Test plan
🤖 Generated with Claude Code