docs: split ROADMAP into milestone roadmap + HISTORY build narrative by aallan · Pull Request #405 · aallan/vera

aallan · 2026-03-27T22:27:08Z

Summary

ROADMAP.md replaced with a four-milestone structure (Prove the thesis → Verified agent orchestration → Tooling for adoption → Language maturity) plus a continuous quality/security hardening section. All 73 open issues are referenced in at least one authoritative location (ROADMAP or README bugs/limitations).
HISTORY.md is a new file containing the full build narrative — how the compiler was constructed across 29 development days from initial commit to v0.0.101, stage by stage with version tables.
README.md references both files from the project structure listing and the Project Roadmap section.

Background

The previous ROADMAP.md mixed completed-phase history with forward-looking milestones. The split mirrors what was done to the compiler itself in Stage 5: monolithic files decomposed into focused modules. HISTORY.md is essentially append-only (past does not change); ROADMAP.md is where active editing happens.

Also filed 27 new GitHub issues (#378-#404) covering Inference hardening, CI/security tooling, testing gaps, discoverability improvements, and developer experience items surfaced by an independent assessment of the project at v0.0.101.

Test plan

All pre-commit hooks pass (doc counts, limitations sync, readme examples)
All 73 open GitHub issues appear in at least one of ROADMAP.md or README.md
HISTORY.md contains the full C1-C9 build narrative previously in ROADMAP.md

Generated with Claude Code

Summary by CodeRabbit

Documentation
- Added HISTORY.md documenting Vera’s development timeline, staged compiler milestones, tooling/editoring progress and release-to-release metrics through v0.0.101.
- Updated README.md to improve the documentation index, add cross-links to ROADMAP and HISTORY, and remove an outdated roadmap paragraph.
- Rewrote ROADMAP.md into a milestone-based narrative with phased checklists, consolidated progress metrics, and a new continuous quality and security section.

ROADMAP.md is replaced with a four-milestone structure (Prove the thesis → Verified agent orchestration → Tooling for adoption → Language maturity) plus a continuous quality/security hardening section. All 73 open issues are referenced in at least one authoritative location. HISTORY.md is a new file containing the full build narrative — how the compiler was constructed across 29 development days from initial commit to v0.0.101, stage by stage with version tables. README.md references both files from the project structure listing and the Project Roadmap section. Also files 27 new GitHub issues (#378–#404) covering Inference hardening, CI/security tooling, testing gaps, discoverability improvements, and developer experience items surfaced by an independent assessment of the project. Co-Authored-By: Claude <noreply@anthropic.invalid>

coderabbitai · 2026-03-27T22:27:21Z

📝 Walkthrough

Walkthrough

This PR adds HISTORY.md documenting Vera’s development through v0.0.101, updates README.md with cross-links to HISTORY.md and ROADMAP.md, and rewrites ROADMAP.md into four audience-oriented milestones with updated metrics and a continuous quality/security section.

Changes

Cohort / File(s)	Summary
Project history documentation `HISTORY.md`	Added a comprehensive project history covering staged compiler development (parser, AST, type checking, contract verification, WASM codegen), codegen completion and cleanup, multi-file module system, refactor/polish, WASM mark‑sweep GC, stdlib/runtime growth, constrained generics and prelude, and algebraic effects; includes release-to-release metrics.
Documentation index and cross-links `README.md`	Updated README to reference the new `HISTORY.md` and `ROADMAP.md`, removed the interleaved spiral paragraph, and directed readers to `ROADMAP.md` for milestone details.
Roadmap restructure `ROADMAP.md`	Replaced the prior tiered/interleaved roadmap and detailed per‑phase collapsibles with four audience‑oriented milestones, compacted completed phases into a table, added aggregate repo/testing/spec metrics, and introduced a “Continuous: quality and security hardening” section.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

Add VS Code extension for Vera syntax highlighting #365: Modifies README editor/tooling documentation sections.

Suggested labels

docs

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 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: splitting ROADMAP documentation into a milestone-focused roadmap and a new HISTORY file documenting the build narrative from initial commit to v0.0.101.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs/roadmap-history-split

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

codecov · 2026-03-27T22:27:55Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.30%. Comparing base (97dd37d) to head (d528652).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #405   +/-   ##
=======================================
  Coverage   90.30%   90.30%           
=======================================
  Files          49       49           
  Lines       19100    19100           
  Branches      220      220           
=======================================
  Hits        17248    17248           
  Misses       1848     1848           
  Partials        4        4

Flag	Coverage Δ
javascript	`50.58% <ø> (ø)`
python	`95.31% <ø> (ø)`

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

☔ View full report in Codecov by Sentry.
📢 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 the current code and only fix it if needed.

Inline comments:
In `@ROADMAP.md`:
- Line 87: The ROADMAP.md mentions issue `#237` twice with conflicting WASI
targets; resolve by deciding whether `#237` is for WASI 0.2 (Phase 2b) or WASI 0.3
(Phase 4a), then update the two entries so they either reference two distinct
issue numbers (e.g., split the Phase 2b and Phase 4a work into separate issues)
or make both entries consistently describe the same scope and WASI version;
specifically edit the lines that reference "#237", the phrases "WASI 0.2" and
"WASI 0.3", and the phase labels "Phase 2b"/"Phase 4a" so the issue number,
version, and phase all match.

🪄 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

Run ID: ba24552c-9bec-4371-9557-7e95239e505b

📥 Commits

Reviewing files that changed from the base of the PR and between 97dd37d and 198bd8b.

📒 Files selected for processing (3)

HISTORY.md
README.md
ROADMAP.md

#237 covers WASI 0.2 compliance (Phase 2b prerequisite for HttpServer). WASI 0.3 native async I/O is now tracked separately as #406 (Phase 4a prerequisite for true concurrency. Fixes duplicate #237 reference flagged in code review. Co-Authored-By: Claude <noreply@anthropic.invalid> EOF )

coderabbitai

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@ROADMAP.md`:
- Line 3: The roadmap's opening sentence omits the compiler "transform" stage;
update the pipeline phrasing in the first paragraph (the sentence listing parse,
type-check, verify, compile, execute) to include "transform" and, if possible,
adopt the canonical sequence "parse → transform → typecheck → verify → compile →
execute" so the sentence reads accurately and matches the later suggested
summary about single-responsibility stages.
- Line 11: The narrative in ROADMAP.md referencing "**v0.0.101** — the reference
compiler is complete through ten development phases (C1–C9)" is inconsistent
with the completed-phase table (which includes C6.5 and C8.5); update that
sentence to reflect the table (e.g., "eleven development phases (C1–C9, plus
C6.5 and C8.5)") and make the same change for the other occurrences noted
(around the lines referencing the phase count at 202 and 206–216) so the textual
summary and the table are aligned.

🪄 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

Run ID: 27c49ded-416f-4cb3-8f93-eaf3524a9aa0

📥 Commits

Reviewing files that changed from the base of the PR and between 198bd8b and c078f8c.

📒 Files selected for processing (1)

ROADMAP.md

- Add missing transform stage to pipeline description (parse → transform → type-check → verify → compile → execute) - Correct phase count from "ten" to "eleven" (C6.5 and C8.5 are both in the completed-phase table, making 11 entries not 10) Co-Authored-By: Claude <noreply@anthropic.invalid>

coderabbitai

♻️ Duplicate comments (1)

ROADMAP.md (1)

202-202: ⚠️ Potential issue | 🟡 Minor

Inconsistent phase count: line 202 says "ten" but should say "eleven".

Line 11 correctly states "eleven development phases (C1–C9, including C6.5 and C8.5)", and the table at lines 204-216 lists 11 entries, but line 202 still says "ten development phases."

Proposed fix

-The compiler was built through ten development phases from February to March 2026. Each phase added a complete compiler layer with tests, documentation, and working examples. See [HISTORY.md](HISTORY.md) for the full narrative.
+The compiler was built through eleven development phases from February to March 2026. Each phase added a complete compiler layer with tests, documentation, and working examples. See [HISTORY.md](HISTORY.md) for the full narrative.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@ROADMAP.md` at line 202, Update the sentence that currently reads "The
compiler was built through ten development phases..." to read "eleven
development phases" so it matches the rest of the document (the earlier sentence
referencing "eleven development phases (C1–C9, including C6.5 and C8.5)" and the
11-entry table). Locate and edit the exact phrase "ten development phases" in
the ROADMAP sentence and replace "ten" with "eleven" to ensure consistency.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Duplicate comments:
In `@ROADMAP.md`:
- Line 202: Update the sentence that currently reads "The compiler was built
through ten development phases..." to read "eleven development phases" so it
matches the rest of the document (the earlier sentence referencing "eleven
development phases (C1–C9, including C6.5 and C8.5)" and the 11-entry table).
Locate and edit the exact phrase "ten development phases" in the ROADMAP
sentence and replace "ten" with "eleven" to ensure consistency.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 49081e71-6b71-4408-921e-f449a100b065

📥 Commits

Reviewing files that changed from the base of the PR and between c078f8c and d528652.

📒 Files selected for processing (1)

ROADMAP.md

coderabbitai Bot reviewed Mar 27, 2026

View reviewed changes

Comment thread ROADMAP.md

coderabbitai Bot reviewed Mar 27, 2026

View reviewed changes

Comment thread ROADMAP.md Outdated

Comment thread ROADMAP.md Outdated

coderabbitai Bot reviewed Mar 27, 2026

View reviewed changes

aallan merged commit c11b246 into main Mar 28, 2026
17 checks passed

aallan deleted the docs/roadmap-history-split branch March 28, 2026 00:48

This was referenced Apr 17, 2026

Add "What's next" section to ROADMAP (Stage 11 implementation order) #483

Merged

Add IO.sleep, IO.time, IO.stderr (closes #463, v0.0.114) #491

Merged

Close #466 and remove stale ergonomic framing from ROADMAP #521

Merged

This was referenced Apr 27, 2026

ROADMAP: add doc-consolidation side issues (#538, #539, #540) #541

Merged

HISTORY: freshen Editor & tooling and By the numbers (post-v0.0.123) #545

Merged

ROADMAP: split #170 row into bookmark + active features (#562) #563

Merged

coderabbitai Bot mentioned this pull request May 26, 2026

Docs cleanup: KNOWN_ISSUES reclassification + ROADMAP vera shape entry #697

Merged

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: split ROADMAP into milestone roadmap + HISTORY build narrative#405

docs: split ROADMAP into milestone roadmap + HISTORY build narrative#405
aallan merged 3 commits into
mainfrom
docs/roadmap-history-split

aallan commented Mar 27, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Mar 27, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Uh oh!

codecov Bot commented Mar 27, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

aallan commented Mar 27, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Background

Test plan

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Uh oh!

codecov Bot commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

aallan commented Mar 27, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Mar 27, 2026 •

edited

Loading

codecov Bot commented Mar 27, 2026 •

edited

Loading