@@ -0,0 +1,20 @@
+# Milestones
+
+Applies whenever an issue or a pull request is created or edited, for instance with `gh issue create`,
+`gh issue edit` or `gh pr create`.
+
+## Set a milestone on issues only, never on pull requests
+
+A milestone is named after the version it ships in, such as `0.26.0`, and tracks what that release contains. That is
+the work item, so it belongs to the issue. The pull request implementing it is only the change, and the issue it closes
+already carries the release.
+
+- When creating or editing an issue, propose a milestone along with the labels and the issue type.
+- When creating or editing a pull request, set labels only, and do not offer a milestone, even when the branch clearly
+  targets a given release or adds a `@since` tag naming its version.
+- An issue fixed by a pull request gets the milestone of the first release containing that pull request, also when the
+  issue is closed long after, or by its author.
+
+The release process relies on it: before a release, the maintainer looks for the issues closed as completed without a
+milestone, so a missing one shows up there, see the
+[release how-to](../../../packages/website/docs/development/release.md).
@@ -43,7 +43,7 @@ This document provides essential knowledge for AI coding agents to be productive
 - **Mixins/Plugins**: Add new features via mixins or plugins, not by modifying core classes directly.
 - **Registries**: Register only required shapes/styles for tree-shaking (see `ts-example-selected-features`).
 - **Testing**: Use Jest. Test patterns in `.claude/rules/testing/conventions.md`.
-- **Commits/PRs**: Follow `.claude/rules/git/commit-conventions.md` for commit messages and `.claude/rules/git/pull-requests.md` when updating a PR description. PRs should run full CI.
+- **Commits/PRs**: Follow `.claude/rules/git/commit-conventions.md` for commit messages, `.claude/rules/git/pull-requests.md` when updating a PR description, and `.claude/rules/git/milestones.md` before setting a milestone (issues only, never PRs). PRs should run full CI.
 - **Documentation**: Update `README.md` and `CLAUDE.md` for major changes. Use concise, accurate docs.
 
 ### 4. Examples & Integration
 
@@ -59,6 +59,7 @@ Key patterns:
 - See `.claude/rules/documentation/guides-structure.md` for the structure of the website guides (prerequisites, titles)
 - See `.claude/rules/git/commit-conventions.md` for commit message style
 - See `.claude/rules/git/pull-requests.md` for updating a pull request description (keep the blocks added by bots)
+- See `.claude/rules/git/milestones.md` before setting a milestone (issues only, never pull requests)
 
 ## References