Context
docs/ARCHITECTURE.md opens with:
Status: Home is at 88% completion (43/49 tasks complete)
No serious programming language is "88% complete" — languages evolve forever. This kind of framing in public docs hurts credibility with the audience we're trying to attract (systems / web devs evaluating Home seriously).
The same pattern shows up in the *-COMPLETE.md files (SESSION-STDLIB-COMPLETE.md, TESTING_COMPLETE.md, TOOLING_COMPLETE.md, BUN-FEATURES-IMPLEMENTED.md) — they read like internal milestone reports rather than user-facing documentation.
Proposal
Remove the "88% complete" line from
ARCHITECTURE.mdAdd a capability matrix to docs (or README) that's honest about what works and what doesn't:
Feature Status Closures ✅ Stable Pattern matching ✅ Stable Trait objects 🚧 In progress Const generics ❌ Not yet arm64 codegen 🚧 Partial wasm codegen 🚧 Stub … … Add a real
CHANGELOG.mdat repo root, going forward (Keep a Changelog format). Past changes can be reconstructed lazily fromgit log.Demote the
*-COMPLETE.mdfiles into either internal-only notes (e.g.docs/internal/) or fold their useful content into the user-facing docs and delete the rest.
Why this matters
- Honest "🚧 in progress" reads as confident; "88% complete" reads as overclaim
- A capability matrix lets evaluators decide if Home is ready for their use case in 30 seconds
- A CHANGELOG lets users decide whether to upgrade
Related
Part of broader docs cleanup — the 43-file flat docs/ layout could use restructuring (see separate issue if filed).