[FBumann]

docs/ROADMAP.md goes from 203 lines to 88: why the project exists and where
it is going. No work items. Those are issues now, grouped under three parents
— #470, #471, #472 — with 21 sub-issues between them.

Why the index had to go

The page carried a table per track, and it lost to the tracker it duplicated.
Found while triaging:

• Two rows described shipped work. Track 1 item 5 (defined(v), defined(v): component-aware where over variables (Track 1 item 5) #219) and
  Degree 2: what "reachable" would actually require #84 in Track 3 are both closed/completed, still listed as open.
• Two items had no issue at all — Track 1 items 4 and 6. Gutting the page
  would have dropped them silently, so they are filed first as Window sum: sum_next_n(x, over=dim, n=N) — the bounded-halo member of the window family #468 and A where predicate cannot reduce over a dimension the foreach does not span #469.
• Four references pointed at sections that never existed or no longer did.
  chunking.py and tests/oracle.py cite ROADMAP Track 5; test_api.py
  cites ROADMAP 2c; test_validation.py cites ROADMAP 5c; degree.py
  cites "The degree axis" — in two user-facing error messages. There is
  no Track 5, no lettered subsection and no degree-axis section.

That last one is the sharp end: a LanguageError a user actually reads was
sending them to a heading that does not exist. All four are fixed here.

Where the content went

was	now
Tracks 1–3, tables + prose	#470 / #471 / #472, framing preserved in the parent bodies
Track 4, the memory axis (named no issues)	a paragraph under Where it is going — it is an end state, not a work item
Deliberate non-primitives	docs/design/ceiling.md, which already owns what may enter the language; the refusals are its negative half
The ceiling summary	deleted — it was a summary of ceiling.md with a pointer to it
Honest snapshot	kept, with the track references removed

Moving the refusals also removes a two-hop answer: CLAUDE.md sent feature triage
to ceiling.md for the admissibility test and to ROADMAP.md for the refusals.
One question, one page. Both pointers repointed.

References repointed

Every deep ROADMAP.md#track-N anchor — benchmarks.md, ARCHITECTURE.md (x2),
SPEC.md, ceiling.md (x2), sinks/README.md — now links the parent issue.
grep -rn "ROADMAP.md#track" returns nothing.

Verified

mkdocs build --strict clean (it validates every internal anchor, which is what
would have caught a bad repoint). ruff check / format --check clean,
pyrefly 0 errors, 764 passed.

One golden moved: examples/walkthrough.out captures the degree-2 error text
verbatim, so changing the pointer inside it failed test_walkthrough_matches_golden
until regenerated — the test working as designed on a user-facing string.

Summary by CodeRabbit

• Documentation
  • Refreshed the project roadmap with its thesis, work tracks, planned capabilities, constraints, and explicit non-goals.
  • Updated architecture, specification, benchmark, and design documentation links to current issue-based references.
  • Added guidance documenting deliberate non-primitive decisions and permitted alternatives.
  • Aligned contributor and language guidance with the updated design documentation.
  • Cleaned up outdated roadmap references across technical documentation, error guidance, and test descriptions.

[coderabbitai]

Warning

Review limit reached

@FBumann, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 55 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

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: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 79a1de32-456a-4d0e-938b-c5d40790bf61

📥 Commits

Reviewing files that changed from the base of the PR and between b92153a and db01f3b.

📒 Files selected for processing (1)

• docs/models/monthly_budget.md

📝 Walkthrough

Walkthrough

The PR replaces the detailed roadmap with a concise project-direction document, adds deliberate non-primitives guidance, and updates roadmap references across documentation, source comments, validation messages, and tests. No runtime behavior changes.

Changes

Roadmap and capability-boundary governance

Layer / File(s)	Summary
Project direction and capability boundaries docs/ROADMAP.md, docs/design/ceiling.md	The roadmap now defines project direction, tracks, capabilities, memory constraints, and non-goals. The ceiling document records deliberate non-primitives and permitted escape: islands.
Documentation reference migration CLAUDE.md, CONTRIBUTING.md, docs/ARCHITECTURE.md, docs/SPEC.md, docs/benchmarks.md, docs/design/ceiling.md, src/lpspec/relational/sinks/README.md	References now target ceiling sections, descriptive roadmap sections, or issue-based tracks.
Source and test annotation updates src/lpspec/language/degree.py, src/lpspec/language/validation.py, src/lpspec/relational/chunking.py, tests/oracle.py, tests/test_api.py, tests/test_resolution_parity.py, tests/test_validation.py	Obsolete roadmap annotations and links are replaced. Runtime behavior remains unchanged.

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

Possibly related PRs

• FBumann/lpspec#87: Revises the same roadmap, architecture, and language-boundary documentation.
• FBumann/lpspec#333: Reorganizes the ceiling document and related roadmap references.
• FBumann/lpspec#388: Redefines roadmap tracks and deliberate non-primitives in the same documentation areas.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: the roadmap now focuses on motivation and end state while detailed work moves to issues.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

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

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[read-the-docs-community]

Documentation build overview

📚 lpspec | 🛠️ Build #33980921 | 📁 Comparing db01f3b against latest (ab8d71f)

  🔍 Preview build  

7 files changed · ± 7 modified

± Modified

• ARCHITECTURE/index.html
• ROADMAP/index.html
• SPEC/index.html
• benchmarks/index.html
• changelog/index.html
• design/ceiling/index.html
• models/monthly_budget/index.html

[codspeed]

Merging this PR will not alter performance

✅ 14 untouched benchmarks
⏩ 10 skipped benchmarks¹

---

_{Comparing docs/roadmap-motivation (db01f3b) with main (603a406)}

Footnotes

1. 10 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩