Doc consistency sweep after bug-killing campaign (ROADMAP / HISTORY / SKILL.md)#581
Merged
Merged
Conversation
…ntegration push The bug-killing campaign that ran v0.0.120-v0.0.134 closed twelve runtime/codegen bugs and is over. The 'What's next — short-term priorities' section was anchored entirely in that campaign's framing — three paragraphs of justification preceded a one-row priority table that was a leftover after the last batch shipped. Replace with 'What's next — agent-integration push'. Three priorities pulled from later-milestone phases that share the characteristic of being independent of compiler internals (unlike the bug-killing work, which was deep in the runtime): * #222 LSP server — single highest-leverage adoption enabler. * #523 vera context — token-budgeted project export. * #370 Inference max_tokens / temperature — smallest of the Inference-hardening items, blocks the most user requests. Drop: * The 'ordering principle / bug-killing campaign' paragraphs (the campaign is in HISTORY.md / CHANGELOG.md now). * The agent self-observation quote about runtime bugs vs the type system (was specific to the campaign motivation). * The reference to 'the campaign queue' in the Speculative section's framing. #507 (Eq/Ord-dispatched array ops) was the single entry left in the priority table at v0.0.134. Drops out of the priority queue because it was lower-urgency than the agent-integration items; stays on the milestone list under Phase 4c (stdlib phase 2) where it belongs. Co-Authored-By: Claude <noreply@anthropic.invalid>
The pre-#573 cleanup pass already trimmed ROADMAP, but HISTORY's Stage 11 release table accumulated parallel bloat as each campaign release added implementation details, parenthetical asides, metric examples, and cross-references that don't appear in earlier-stage entries. Established density for HISTORY is 'feature/fix description + issue link, optional one-clause qualifier' — every entry pre-v0.0.119 fits that. Compact eight entries to match: * v0.0.119 (JSON typed accessors) — was 4 sentences listing all 11 functions; now 1 sentence with the why. * v0.0.120 (Crash-debugging UX) — was 5 sentences; now title + issue links. * v0.0.121 (Nested closures) — drop parenthetical CVE noise. * v0.0.122 (GC bounds-checked) — drop Layer-1/Layer-2 detail (lives in CHANGELOG); keep the user-visible outcome. * v0.0.123 (IO.print live flush) — keep the outcome, drop the trap-preservation detail. * v0.0.131 (GC infrastructure batch) — drop heap-base shift metric and follow-up cross-reference. * v0.0.132 (Opaque-handle GC-rooting) — drop the #346 superseded-by-#573 parenthetical. * v0.0.133 (Iterative array builders) — drop the per-callsite WAT detail. * v0.0.134 (heap-wrap-as-ADT) — drop the Phase-2c mechanism description and the 10K-iter store-size metric. Add #579 to the closes list (was missed in the previous compact pass). CHANGELOG keeps the long form for each (the 'long lists belong in CHANGELOG' rule from the earlier doc-cleanup feedback). Co-Authored-By: Claude <noreply@anthropic.invalid>
The agent-facing doc was carrying three stale 'Known Bugs' table rows for issues closed in the v0.0.129-v0.0.131 batch: * #475 (WASM call translator bugs) — closed v0.0.129. * #487 (Large single allocations) — closed v0.0.131. * #535 (Pair-type closure capture) — closed v0.0.130. Plus an entire pre-#535 closure-capture subsection (~50 lines) warning agents that pair-type captures silently corrupt their length field and instructing them to 'lift the closure body to a top-level private fn' as a workaround. All of that is counterproductive now — agents writing Vera against this doc were generating convoluted code to work around a bug that no longer exists. This is a structural risk that the limitations-sync script doesn't catch (SKILL.md isn't in its purview). The user-facing KNOWN_ISSUES.md has been clean throughout because it's part of every release-doc sync; the agent-facing layer accumulated stale entries silently across the campaign. Changes: * Closures section: rewrite 'What you cannot capture' → 'Capturing a pair-typed value', showing the natural capture pattern with an Array<Int> example. Drop the workaround section entirely. Update the nested-closures parenthetical to drop the pair-type caveat. * Known Bugs table: remove the three closed-issue rows. Add the still-open #568 (url_parse leading-colon drop) for parity with KNOWN_ISSUES.md. Trim the post-table 'shapes to recognize' paragraph. * Body: drop one stale 'No helper, no lifting workaround needed' comment in the nested-closures example (was meaningful pre-#535, now leftover phrasing). scripts/check_skill_examples.py: line-shift fix for the allowlisted FRAGMENT entries that moved when SKILL.md contracted. Includes a new comment documenting the v0.0.134 reframe of the pair-type capture example from BROKEN to working. Allowlist now reports 62/62 entries up to date, 55 Vera blocks parse cleanly, 0 failures. docs/SKILL.md and docs/llms-full.txt regenerated from SKILL.md via scripts/build_site.py (auto-derived; site-assets check passes). Co-Authored-By: Claude <noreply@anthropic.invalid>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #581 +/- ##
=======================================
Coverage 90.98% 90.98%
=======================================
Files 59 59
Lines 22884 22884
Branches 259 259
=======================================
Hits 20821 20821
Misses 2056 2056
Partials 7 7
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughDocumentation and validation updates across version history, roadmap, language semantics, and example allowlist. HISTORY.md receives Stage 11 version entries; ROADMAP.md restructures near-term priorities toward agent integration; SKILL.md expands closure capture semantics and nested-closure examples; scripts/check_skill_examples.py extends allowlist entries to validate new examples. ChangesClosure Capture Semantics & Example Validation
Documentation & Roadmap Updates
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested labels
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
CI lint failed on PR #581 because SKILL.md was modified without a matching CHANGELOG entry — the check_changelog_updated.py gate considers SKILL.md substantive. The doc cleanup IS user-visible (agents reading SKILL.md will see the cleaned content with no closed-bug workarounds), so a brief Unreleased entry under ### Documentation is the right call here over the Skip-Changelog escape hatch. Single-paragraph entry covering all three commits in this PR (ROADMAP rework, HISTORY compaction, SKILL.md cleanup). Co-Authored-By: Claude <noreply@anthropic.invalid>
There was a problem hiding this comment.
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 `@HISTORY.md`:
- Around line 256-271: The HISTORY.md release ledger was edited in this
no-version-bump housekeeping PR—undo any modifications to existing release rows
(e.g., the Stage 11 rows touched for v0.0.119..v0.0.134) and remove the appended
close-link on v0.0.134 so HISTORY.md remains unchanged; instead record the
housekeeping notes in CHANGELOG [Unreleased], the ROADMAP tracker, or a GitHub
issue per project policy. Ensure you revert edits that touch the existing
release entries and only add housekeeping metadata to the designated non-ledger
locations.
🪄 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: 6cc8e16a-0f73-4b61-b415-d708df58383a
⛔ Files ignored due to path filters (2)
docs/SKILL.mdis excluded by!docs/**docs/llms-full.txtis excluded by!docs/**
📒 Files selected for processing (4)
HISTORY.mdROADMAP.mdSKILL.mdscripts/check_skill_examples.py
This PR's contents land in v0.0.134 via tag-move-to-HEAD, not a version-bump release. The earlier commit added the entry under [Unreleased] to satisfy CI's check_changelog_updated.py gate (which assumes the standard version-bump workflow); now that the gate has fired and we know the PR's substantiveness is recorded, move the entry to its semantically-correct section. Skip-changelog: tag-move-to-HEAD workflow — the entry is now under [0.0.134], which is a released-section position the gate doesn't recognise. The previous commit (3193200) already satisfied the gate, this one just relocates the bullet. Co-Authored-By: Claude <noreply@anthropic.invalid>
This was referenced May 6, 2026
Merged
This was referenced May 26, 2026
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
Doc-layer consistency sweep after the bug-killing campaign closed in v0.0.134. Three focused commits:
What's next — short-term priorities(anchored entirely in the now-closed campaign, with a one-row priority table after it) withWhat's next — agent-integration push. Three priorities pulled from later-milestone phases that share the property of being independent of compiler internals: LSP server #222 LSP,vera context— token-budgeted project context export for LLM agents #523vera context, Inference effect: configurable max_tokens / temperature #370Inference.completemax_tokens / temperature.$allocgrows memory by only 1 page — large single allocations trap #487, Pair-type captures (String, Array<T>) silently drop the len field #535) and rewrite the closure-capture subsection that was telling agents to use a now-obsolete "lift to a helper" workaround for pair-type captures (Pair-type captures (String, Array<T>) silently drop the len field #535 closed in v0.0.130). Add the still-open url_parse / url_join drops leading colon — ":foo" round-trips as "foo" #568 (url_parse leading-colon drop) for parity with KNOWN_ISSUES.md.Why this matters
The user-facing KNOWN_ISSUES.md has stayed clean throughout the campaign because it's part of every release-doc sync. The agent-facing layer (SKILL.md) accumulated stale "Known Bugs" rows silently because no validation gate watches it line-by-line. Agents writing Vera against this doc were generating convoluted code to work around bugs that no longer exist.
Net delta: −108 lines across the three commits. Net signal-to-noise improvement is much larger because the deleted lines were specifically the ones leading agents wrong.
Test plan
pytest tests/ -q— 3,702 passed, 14 skippedpython scripts/check_doc_counts.py— consistentpython scripts/check_limitations_sync.py— 27 KNOWN_ISSUES / 15 vera/README / 2 spec, consistentpython scripts/check_skill_examples.py— 55 Vera blocks parse, 62 allowlisted, 0 failurespython scripts/build_site.py && python scripts/check_site_assets.py— site assets up-to-date (docs/SKILL.md+docs/llms-full.txtregenerated as part of commit 3)python scripts/fix_allowlists.py— all up to date (line-shift fix included in commit 3)Notes for reviewers
This is doc-only. No code changes, no behavior changes, no version bump. After merge, retag
v0.0.134to HEAD so the released artefact reflects the cleaned SKILL.md (the currentv0.0.134tag points at a commit where SKILL.md still listed three closed issues as Known Bugs and had a stale closure-capture workaround).Companion PR: #580 (already open) is a tiny hotfix for a stale visible version on
docs/index.htmlplus a hardening ofcheck_version_sync.py. Independent of this sweep; can merge in either order.🤖 Generated with Claude Code
Summary by CodeRabbit
Documentation
Tests