release: v2.1.0

[robotrocketscience]

Summary

Cuts v2.1.0 from current main. Skips the deferred off-main release/v2.0.2 hotfix branch — its #522 fix already merged to main directly, so v2.1.0 supersedes it.

What lands

Changed (default flips)

• [retrieval] Pipeline composition tracker — unified retrieve() with feature-flag gate #154 — use_heat_kernel and use_hrr_structural flip to default-on after the calibrated reproducibility-harness gate cleared at 11/11 (PR feat(bench-canonical): calibrate v2.0.0 from 3-run pass (#437) #489 / [v2.0] Reproducibility harness — benchmarks/results/v2.0.0.json is canonical, uv sync && aelf bench all #437).
• Aelf isn't really recording things without me prompting it to. #529 — aelf setup wires the auto-capture pipeline by default (transcript-ingest + commit-ingest + session-start). Closes the gap between README v1.2.0 marketing and what fresh installs actually wired. Opt-out flags ship; aelf unsetup mirrors symmetrically. INSTALL.md gains a six-row hook table + privacy note.

Added (bench gates)

• Rebuild redesign: query understanding (entity extraction, intent, term-weighting) #291 / [v2.1] query-strategy uplift runner — implement run_query_strategy_uplift for #291 bench gate #527 — run_query_strategy_uplift driver + bench-gate scaffold.
• [v2.0] Document / semantic linker — recovery-inventory placeholder #435 — run_doc_linker_uplift driver.

Fixed

• /aelf:upgrade doesn't actually upgrade to the latest #530 — /aelf:upgrade slash uses no-flag aelf upgrade-cmd form for cross-CLI parse safety.
• aelf upgrade-cmd --check missing 'run:' line breaks /aelf:upgrade slash on pre-2.0.1 CLIs #522 — aelf upgrade-cmd --check emits run: line on update-available (CLI side of the same regression class).
• Bug reporting should be rich text for the first question #531 — bug-report issue template what-happened field accepts inline screenshots.

Verification

• pyproject.toml bumped 2.0.1 → 2.1.0
• uv lock re-resolved (120 packages, only aelfrice self-version updated)
• CHANGELOG.md [Unreleased] section folded into [2.1.0] - 2026-05-09
• Both commits SSH-signed (G)
• Discretion grep clean on added lines

Test plan

• Staging-gate runs (pytest 3.12/3.13, secrets-scan, history-scan, pattern-scan, etc.)
• Reviewer: confirm README roadmap rows for any v2.1.0-marketed lines flip to shipped post-tag (no roadmap edits in this PR — README is unchanged)
• After merge: git tag v2.1.0 <merge-sha> && git push github v2.1.0 triggers .github/workflows/publish.yml → PyPI

What this does NOT include

• The off-main release/v2.0.2 hotfix branch (rooted at v2.0.1, contains only the aelf upgrade-cmd --check missing 'run:' line breaks /aelf:upgrade slash on pre-2.0.1 CLIs #522 cherry-pick) is now obsolete. Recommend deleting release/v2.0.2 post-merge to avoid future confusion.

Summary by Sourcery

Cut the v2.1.0 release, updating versioning and changelog while enabling newly gated functionality and improving the upgrade and reporting flows.

New Features:

• Introduce query-strategy uplift and doc-linker uplift benchmark drivers behind bench-gate scaffolding.

Bug Fixes:

• Harden the /aelf:upgrade slash command flow across CLI versions by relying on the no-flag aelf upgrade-cmd form and consistent run: output.
• Ensure aelf upgrade-cmd --check emits the run: line on update-available so automated upgrade helpers can function correctly.
• Allow the bug-report issue template’s main description field to support inline screenshots instead of shell-rendered code blocks.

Enhancements:

• Flip use_heat_kernel and use_hrr_structural retrieval flags to default-on now that their reproducibility gates have cleared.
• Enable the auto-capture pipeline (transcript, commit, session-start hooks) by default on aelf setup, with symmetric opt-out and aelf unsetup behavior.

Build:

• Bump the project version from 2.0.1 to 2.1.0 and refresh the dependency lockfile.

Documentation:

• Document the v2.1.0 release in the changelog and expand INSTALL guidance with a hook summary table and privacy note for default-on transcript capture.

[coderabbitai]

Important

Review skipped

Ignore keyword(s) in the title.

⛔ Ignored keywords (2)

• docs:
• release:

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: b6831f3a-7a43-4137-be98-701f26f038f0

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch release/v2.1.0

---

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]

🧙 Sourcery has finished reviewing your pull request!

---

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.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

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.}

[github-actions]

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

git fetch origin && git checkout 'release/v2.1.0' && 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.

[robotrocketscience]

v2.1 roll-in coordination

Operator-side check before tag/cut. Three follow-ups landed today that should ride v2.1 (or be acknowledged as out-of-scope for it):

1. [v2.0] HRR vocabulary bridge — close vocabulary-gap-recovery claim #433 disposition comment posted (#433#issuecomment-4414384380). Recommends close-as-done-via-structural-lane. Tagged attn:decisions-needed. If approved, no code change ships in v2.1; just an issue close + CHANGELOG line under "Documentation / closure."
2. [v2.1] Re-spec VocabBridge._harvest — produce surface↔canonical pairs (follow-up to #433 evidence) #536 disposition comment posted (#536#issuecomment-4414385202). Recommends Option A: close wontfix + remove vocab_bridge.py. If approved, that's a separate PR (touches retrieve_v2, tests/, docs/); whether it lands in v2.1 vs v2.2 depends on appetite for a code-removal change in this cut.
3. [v2.1] hrr.DEFAULT_DIM drift — flip 2048 → 512 to match lab R4 verdict #538 (new) — hrr.DEFAULT_DIM drift, 2048 → 512 to match the lab R4 verdict. Single-constant change + benchmark rerun. Could ride v2.1 if rebasable; otherwise v2.2.

If any of (1) / (2) / (3) lands before tag, this branch needs another rebase. If they all defer to v2.2, this branch is good as-is on its current rebase state.

Releasing the PR back to operator.

[robotrocketscience]

v2.1 roll-in update — both follow-up PRs are open and ready for review

Per the operator dispositions, two PRs landed today against main:

• PR perf(hrr): default dim 2048 -> 512 per lab R4 verdict (#538) #539 — perf(hrr): default dim 2048 -> 512 per lab R4 verdict (#538). Two atomic signed commits + CHANGELOG line. Required CI green; full pytest 3090/53 skipped at the new default.
• PR feat(vocab-bridge): remove vocab_bridge.py module (closes #536, #433) #540 — feat(vocab-bridge): remove vocab_bridge.py module (closes #536, #433). Six atomic signed commits walking tests → uplift driver → retrieve_v2 wiring + use_hrr alias → module → docs → CHANGELOG. Pytest 3055/51 skipped after removal.

Both pass discretion grep on diff and ride aelf-pr-open.sh's rebase + pytest gate.

If both land before tag, this branch needs one more rebase before cut. The new CHANGELOG entries (§ Removed for #536/#433, § Performance for #538) merge cleanly under [Unreleased] without conflicting with the v2.1.0 block already on this branch — the v2.1.0 block can fold them in on rebase, or they can stay under [Unreleased] and slip to v2.2.

Releasing back to operator for tag/cut decision.

[robotrocketscience]

[claim:review:rogue1:2026-05-10T04:42:19Z]

[robotrocketscience]

[claim:review:rogue1:2026-05-10T04:43:37Z]

[robotrocketscience]

Rebased branch ready for review

Pushed to rebase/release-v2.1.0-2026-05-10. Diff vs main: 6 signed commits, 3 files changed (CHANGELOG.md +17 / -1, pyproject.toml +1 / -1, uv.lock +1 / -1).

Compare: main...rebase/release-v2.1.0-2026-05-10

What changed vs the prior local rebase (4b0fe0b)

The prior local rebase was based on deb59cd, behind 6 commits that had since landed on main (#538 perf trio, #433 bench-gate trio, #541). Per the "anything merged on main rides v2.1" rule, this rebase replays the 4 release commits on top of current main and adds 2 new CHANGELOG-only commits for the merged-but-undocumented work:

Commit	Subject	Diff
143bd67	release: v2.1.0	pyproject + uv.lock version bump
f7b7d5e	release: v2.1.0 changelog entry	full v2.1.0 block; folds #538 Performance entry up from [Unreleased] and updates the intro to mention it
c9927c3	docs(changelog): #439 aelf core α+β==0 crash fix in 2.1.0 Fixed section	(replayed from prior rebase)
856c089	docs(changelog): MCP tool_lock structured-error fix in 2.1.0 Fixed section	(replayed from prior rebase)
6c55e7b	docs(changelog): #433 vocab_bridge bench gate in 2.1.0 Added section	new
4e0f03e	docs(changelog): #541 vocab_bridge docstring update in 2.1.0 Fixed section	new

Drafted entries (please review wording)

Added — #433 vocab_bridge bench gate scaffold + driver:

New run_vocab_bridge_uplift driver in tests/retrieve_uplift_runner.py mirroring run_doc_linker_uplift / run_query_strategy_uplift, plus the strict-NDCG ship-gate scaffold in tests/bench_gate/test_vocab_bridge_uplift.py (skip-if-runner-absent + skip-if-no-row-has-expected_top_k). Measures NDCG@k uplift from use_vocab_bridge=True on the labelled corpus. Skip-on-no-corpus pattern; no operator action required absent AELFRICE_CORPUS_ROOT.

Fixed — #541 vocab_bridge docstring (cites PR #543):

After #538 flipped DEFAULT_DIM 2048→512, the VocabBridge storage-cost docstring at src/aelfrice/vocab_bridge.py:113 still cited dim=2048 as the implied default for the (N_surfaces, dim) storage estimate. Updated to cite dim=512 (~40 MB at N=10k) as the primary number with dim=2048 (~160 MB) shown as the escape-hatch path, mirroring the format used in hrr_index.py:107-110.

Verification

• All 6 commits signed (G G G G G G).
• Discretion grep on main...rebase/release-v2.1.0-2026-05-10 clean.
• Rebase descended from current github/main (64f767a); no missing commits.

Next step

Approve the wording and I (or you) force-push rebase/release-v2.1.0-2026-05-10 to release/v2.1.0. After the release branch tip moves, this PR's attn:merge-conflict clears and it routes back to attn:review. Tag/cut remains your call.

[robotrocketscience]

[release:review:rogue1:2026-05-10T04:56:24Z]