> ### 🚨 Branch strategy — read before opening this PR > > The v2 refactor has merged into `main`, so **`main` is the default branch for active development** (v1 and v2 code currently coexist there — expect large, breaking changes). > > - **Active development** (features, refactors, optimizations, fixes for the current codebase) → target **`main`** (the default base). > - **v1 maintenance** (hotfixes and subsequent v1 releases) → branch from and target **`v1`**, _not_ `main`. > > A v1 fix does **not** auto-carry to `main`: if the same bug exists on `main`, open a separate forward-port PR targeting `main`. Before touching subsystems being replaced, read `docs/references/data/` and watch for `@deprecated` markers — they flag code being deleted. ### What this PR does Before this PR: After this PR: Fixes # ### Why we need it and why it was done in this way The following tradeoffs were made: The following alternatives were considered: Links to places where the discussion took place: ### Breaking changes If this PR introduces breaking changes, please describe the changes and the impact on users. ### Special notes for your reviewer ### Checklist This checklist is not enforcing, but it's a reminder of items that could be relevant to every PR. Approvers are expected to review this list. - [ ] Branch: This PR targets the correct branch — `main` for active development, `v1` for v1 maintenance fixes - [ ] PR: The PR description is expressive enough and will help future contributors - [ ] Code: [Write code that humans can understand](https://en.wikiquote.org/wiki/Martin_Fowler#code-for-humans) and [Keep it simple](https://en.wikipedia.org/wiki/KISS_principle) - [ ] Refactor: You have [left the code cleaner than you found it (Boy Scout Rule)](https://learning.oreilly.com/library/view/97-things-every/9780596809515/ch08.html) - [ ] Upgrade: Impact of this change on upgrade flows was considered and addressed if required - [ ] Documentation: A [user-guide update](https://docs.cherry-ai.com) was considered and is present (link) or not required. Check this only when the PR introduces or changes a user-facing feature or behavior. - [ ] Self-review: I have reviewed my own code (e.g., via [`/gh-pr-review`](/.claude/skills/gh-pr-review/SKILL.md), `gh pr diff`, or GitHub UI) before requesting review from others ### Release note ```release-note ```