docs(readme): v1.7 row → shipped (BM25F default-on; others opt-in) per #154

[yoshi280]

Task 4 of the #403/#154 v2.0 push workflow. Updated to reflect the post-flip state.

Updates README.md's roadmap table to reflect the actual v1.7 ship state — including the BM25F default-on flip from PR #430.

What's stale on main

The current row says v1.7 is planned, but components #149/#150/#152/#153/#216 are all merged on main and reachable via opt-in feature flags. With PR #428 (Porter stemming) + PR #430 (default-on flip) landing, BM25F (#148) becomes the default L1 lane.

What ships in this PR

• v1.7 row → shipped with the actual flag state:
  • use_bm25f_anchors — default-on (per feat(bm25): Porter stemming on the BM25F lane (#154) #428 + feat(retrieval): flip use_bm25f_anchors default-on at v1.7.0 (#154) #430)
  • use_signed_laplacian, use_heat_kernel, use_hrr_structural — opt-in (placeholder lanes pending wiring)
• v2.0 row tightened — drops the "default-on flip is prereq" note since v1.7 is now shipped.

Bench evidence reflected

Per #154 comment 4380967901: post-stemming uplift was +0.6650 NDCG@k on the v0.1 retrieve_uplift fixture (30 rows, 6 categories) with no regressions. The bench-gate test_retrieve_per_flag_no_regression passes.

Sequencing

This PR is logically downstream of #428 and #430. If they merge first, this lands cleanly as documentation. If this lands first, it'll briefly say "default-on" while main still has it default-off — a 1-day window at most. Coordinate via the merge order on the operator side.

Test plan

• README diff: 1 file changed, 2 lines net.
• Visual review: roadmap table renders cleanly on GitHub.

Summary by CodeRabbit

• Documentation
  • Marked v1.7 as shipped.
  • BM25F anchor-text retrieval set as default-on with a cited NDCG@k uplift.
  • Remaining structural retrieval lanes described as opt-in via feature flags (pending activation wiring).
  • v2.0 remains unchanged.

[sourcery-ai]

Reviewer's guide (collapsed on small PRs)

Reviewer's Guide

Updates the README roadmap table to mark v1.7 as shipped behind opt-in feature flags and clarifies that v2.0 is gated on the v1.7 default-on flip deferred by stemming-related concerns in #154.

Flow diagram for v1_7 opt_in flags and v2_0 default_on flip prerequisites

flowchart TD
  A[Start query execution] --> B{Is_v1_7_default_on_flip_enabled}
  B -- Yes --> C[Use_structural_retrieval_lane_with_BM25F_anchors]
  C --> D[Apply_BM25F_tokenization_no_stemming]
  D --> E[Return_results]

  B -- No --> F{Are_opt_in_flags_set_in_retrieval_section}
  F -- use_signed_laplacian_true --> G[Enable_signed_Laplacian_and_eigenbasis]
  F -- use_heat_kernel_true --> H[Enable_heat_kernel_authority]
  F -- use_hrr_structural_true --> I[Enable_HRR_structural_primitives]

  G --> J[Compose_structural_retrieval_lane]
  H --> J
  I --> J
  J --> K[Execute_query_with_opt_in_structural_features]
  K --> L[Return_results]

  F -- No_flags_set --> M[Use_legacy_FTS5_lane_with_stemming]
  M --> E

  N[Bench_harness_results] --> O{Stemming_gap_resolved_and_BM25F_competitive}
  O -- Yes --> P[Allow_enabling_v1_7_default_on_flip]
  O -- No --> Q[Keep_default_on_flip_deferred_per_issue_154]

  P --> B
  Q --> B

Loading

File-Level Changes

Change	Details	Files
Update v1.7 roadmap entry to reflect shipped status behind opt-in feature flags and document the BM25F uplift plus stemming gap rationale for deferring the default-on flip.	Change v1.7 status from planned to shipped (opt-in). List the specific retrieval feature flags controlling the v1.7 graph signal and structural retrieval components in .aelfrice.toml. Explain that the benchmark harness showed positive NDCG@k uplift for use_bm25f_anchors while exposing a stemming regression versus FTS5. Note that the default-on flip for BM25F is deferred pending stemming evidence and link it to the relevant tracking issues.	README.md
Clarify v2.0 roadmap entry to explicitly depend on the v1.7 default-on flip and reference its deferral per #154.	Keep v2.0 described as planned with feature parity and reproducibility goals. Add that the final v2.0 tag is gated on the v1.7 default-on flip. Note that this flip is currently deferred per issue [retrieval] Pipeline composition tracker — unified retrieve() with feature-flag gate #154 to align roadmap wording with the actual state.	README.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[coderabbitai]

Warning

Rate limit exceeded

@robotrocketscience has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 58 minutes and 37 seconds before requesting another review.

To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: dee976c6-e163-4028-a339-bf5ec9977f91

📥 Commits

Reviewing files that changed from the base of the PR and between 5827f49 and 5e2810f.

📒 Files selected for processing (1)

• README.md

📝 Walkthrough

Walkthrough

README Roadmap updated: the v1.7 row is changed from "planned" to "shipped", documents BM25F anchor-text retrieval as default-on at v1.7.0 (Porter-stemming benchmark cited), and marks other v1.7 structural retrieval lanes as opt-in via [retrieval] flags in .aelfrice.toml. v2.0 unchanged.

Changes

Roadmap Documentation

Layer / File(s)	Summary
Roadmap Text Update README.md (lines 143)	v1.7 status changed from planned to shipped and text expanded to list structural retrieval components.
Feature Flag / Default-on Details README.md (lines 143)	BM25F anchor-text retrieval documented as default-on at v1.7.0 with Porter-stemming NDCG@k uplift noted; other lanes marked opt-in and tied to [retrieval] flags in .aelfrice.toml.
Pending Wiring Note README.md (lines 143)	Text indicates remaining v1.7 retrieval lanes are pending wiring and therefore opt-in.
v2.0 Context README.md (nearby lines)	v2.0 entry remains to emphasize reproducibility; no substantive changes to implementation details.

🎯 1 (Trivial) | ⏱️ ~2 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately reflects the main change: v1.7 roadmap row updated to 'shipped' with BM25F marked default-on and other components opt-in, as referenced in issue #154.
Description check	✅ Passed	The PR description provides comprehensive context: it includes a summary of changes, linked issues (#154, #428, #430, #149-#153, #216), identifies the change type as documentation, explains the rationale with bench evidence, and includes sequencing notes.
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.

_{✏️ 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/v1.7-shipped-opt-in

---

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 and usage tips.}

[sourcery-ai]

Hey - I've left some high level feedback:

• The v1.7 table row is quite long and dense for a single README cell; consider moving the detailed bench/stemming explanation into ROADMAP.md or the linked issue and keeping the table summary more concise with a short note and link for details.
• In the v1.7 row you reference #403/#425 and #154 inline; for consistency and easier navigation, consider turning these into proper links or aligning the referencing style with how other rows link to issues/PRs.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The v1.7 table row is quite long and dense for a single README cell; consider moving the detailed bench/stemming explanation into ROADMAP.md or the linked issue and keeping the table summary more concise with a short note and link for details.
- In the v1.7 row you reference `#403/#425` and `#154` inline; for consistency and easier navigation, consider turning these into proper links or aligning the referencing style with how other rows link to issues/PRs.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[yoshi280]

[claim:review:Kulili:2026-05-05T16:17:18Z]

[github-actions]

This PR is now behind main. Rebase locally so your commit signatures stay intact:

git fetch origin && git checkout 'docs/v1.7-shipped-opt-in' && git rebase origin/main
# resolve conflicts if any, then
git push --force-with-lease

Auto-rebase was removed because the bot has no signing key; rebasing as the bot strips author signatures and the required_signatures rule on main then blocks the merge. See #341.