docs: rework ROADMAP into staged sprints (Stages 19–24)

[aallan]

Reworks ROADMAP.md from the tier/milestone mix into a staged sprint plan — six themed stages continuing HISTORY.md's numbering (which closed Stage 18), on the model the Stage 17 bug burndown proved: pick a coherent class of issues, drive it to zero as one campaign, release, move the stage to HISTORY.

Synthesised from four inputs: DESIGN.md's principles, KNOWN_ISSUES.md's limitation tables, the old ROADMAP, and all 100 open issues (each placed exactly once — staged, horizon arc, ongoing, not-doing-now, or speculative — verified mechanically against gh issue list).

The stages

Stage	Theme	Why this order
19	Verification completeness — vera verify tells the whole truth	The last correctness debt. The KNOWN_ISSUES verification-limitation family (obligation walkers #764/#779/#909, guard deferrals #754/#757/#758/#765/#820, shadow-stack hardening #860, the §11.8 decision #958) previously had no roadmap home at all. #769 leads: the one open class where a program silently does the wrong thing. One architectural enabler (per-component type metadata) unlocks four issues. 11 issues — the same size the burndown was.
20	Single source of truth — one fact, one home, drift caught by a gate	Stage 18 fixed drift by hand; this makes the classes structural (generate the E001 mirrors, gate the homepage numbers, gates that check their own premises — #955/#956 from the external contributions). Release automation (#481/#737) rides as process single-sourcing.
21	Effect hardening — production controls for the headline effects	Http auth/status/timeouts/verbs + Inference config/handlers/embed/providers. Strict prerequisite for the flagship — an agent tool server that can't send an Authorization header or mock its model calls isn't credible.
22	The verified tool server — the flagship	<McpServer> (#306) plus the rails a server on untrusted input needs (#239 resource limits, #235 crypto, #233 date/time) and #440 ADT input generation (tool payloads are ADTs). Exit criterion: a working MCP server serving contract-verified tools to a real agent.
23	Agent experience — the loop the model lives in	LSP seams, vera context/vera shape, REPL, 50+ examples, discoverability — and the VeraBench pass@k re-run as the stage's measurement: did all of the above move the number?
24	Browser — demos that move	Respects the June 2026 demotion; comes due after the flagship. One JSPI suspend mechanism unblocks three of five items — #355 (sync XHR) moves here from Http hardening because every fix option in the issue is an async-to-sync bridge.

Structural changes

• Stages replace tiers + milestones. The horizon keeps the milestone-scale arcs (verification depth, concurrency/WASI, modules/ecosystem, stdlib, internals) grouped with explicit pull-forward triggers. Ongoing threads, not-doing-now, and speculative survive.
• Every stage carries a rationale and an exit criterion (the burndown's "live label query returns empty" pattern, generalised).
• The forecast disclaimer is explicit: stages beyond the next one or two reorder freely, and a new bug class becomes its own burndown, as Stage 17 did.
• The stale Implement Tier 2 verification (Z3-guided with hints from assert/lemma) #427 note is corrected: per-monomorphization shipped, so Tier 2's differential oracle exists — it is outranked now, not blocked.

Rides along

DESIGN.md's technical-decisions table claimed modules ship "with explicit re-exports" — re-exports don't exist (#127 is open). The row now says explicit public/private visibility and points at #127. Found while auditing the roadmap against DESIGN.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Reworked the roadmap into a staged sprint plan with clear stages, exit criteria, and issue groupings.
  • Updated the changelog to reflect the new planning structure and related notes.
  • Refined design documentation wording around module visibility for clearer guidance.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 45 minutes

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 30b06aad-2851-49f7-ba4d-5f39fdff12c9

📥 Commits

Reviewing files that changed from the base of the PR and between 8364910 and 71f009c.

📒 Files selected for processing (3)

• CHANGELOG.md
• HISTORY.md
• ROADMAP.md

📝 Walkthrough

Walkthrough

ROADMAP.md is restructured from a tier/milestone model into a six-stage sprint plan (Stages 19–24), each with rationale, exit criteria, and issue tables, plus a reorganised horizon/outlook section. CHANGELOG.md documents this change, and DESIGN.md's Modules row wording is corrected.

Changes

Roadmap Restructuring

Layer / File(s)	Summary
Roadmap framing intro ROADMAP.md	Adds a "How this file works" section and rewrites "Where we are" intro to introduce the stage-driven model.
Stage 19–24 sprint sections ROADMAP.md	Replaces prior tier/milestone content with six numbered stages, each with description, exit criterion, and issue table (verification, single-source, effect hardening, tool server, agent experience, browser).
Horizon and outlook reorganisation ROADMAP.md	Reworks "The horizon" into arc-grouped items and updates "Ongoing threads", "Not doing now", and "Speculative" sections.
Changelog entry and design wording fix CHANGELOG.md, DESIGN.md	Adds a Changed entry describing the roadmap rework and corrects the Modules row wording to reference explicit public/private visibility.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• aallan/vera#405: Both PRs directly rewrite ROADMAP.md's structure, with #405 introducing an earlier milestone-based framing that this PR further reworks into staged sprints.
• aallan/vera#613: Both PRs extensively rewrite ROADMAP.md's tables and structure, overlapping heavily on the same roadmap sections.
• aallan/vera#483: Both PRs modify ROADMAP.md, with this PR's stage-based rewrite superseding earlier "What's next"/milestone-era content.

Suggested labels: docs

🚥 Pre-merge checks | ✅ 8

✅ Passed checks (8 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarises the main change: ROADMAP.md was reworked into staged sprints for Stages 19–24.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Changelog Covers Public-Surface Changes	✅ Passed	Only CHANGELOG.md, DESIGN.md and ROADMAP.md changed; no public-surface files were touched, and the changelog entry describes those doc updates.
Spec And Implementation Move Together	✅ Passed	Only CHANGELOG.md, DESIGN.md and ROADMAP.md changed; no vera/ or spec/ files moved, so there is no spec/implementation drift to check.
Diagnostics Carry An Error Code	✅ Passed	Only markdown docs changed; no diagnostic definitions were added or edited, and all diagnostic mentions keep stable EW### codes.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/roadmap-stages

---

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.29%. Comparing base (6b31396) to head (71f009c).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #963   +/-   ##
=======================================
  Coverage   93.29%   93.29%           
=======================================
  Files          96       96           
  Lines       31448    31448           
  Branches      456      456           
=======================================
  Hits        29339    29339           
  Misses       2096     2096           
  Partials       13       13           

Flag	Coverage Δ
javascript	78.41% <ø> (ø)
python	95.08% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@ROADMAP.md`:
- Around line 66-85: Update the Stage 21 intro in ROADMAP.md so it only claims
the rows are current KNOWN_ISSUES limitations for Http and Inference; the issue
is that `#379` and `#380` are example deliverables, not limitations. Edit the stage
summary text near the issue table to exclude or qualify the Example rows, while
keeping the limitation list focused on the Http and Inference items identified
by the linked issue numbers.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: c0575069-8e73-4b3a-aff5-1552d689b09b

📥 Commits

Reviewing files that changed from the base of the PR and between 6b31396 and 8364910.

📒 Files selected for processing (3)

• CHANGELOG.md
• DESIGN.md
• ROADMAP.md

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• aallan/vera-bench (manual)