ci: better release and PR checks

.brv/context-tree/_index.md

@@ -1,85 +1,56 @@
 ---
-children_hash: 1884cbea8d2f11b66747698ac7b5ea0d2d8fc007df3d34746f7353b47e0b1079
-compression_ratio: 0.8890429958391124
+children_hash: 0cf4b966b45eb109ac6789464cee4ffdb21086c83a4ba499466ee665e29d8965
+compression_ratio: 0.9044776119402985
 condensation_order: 3
 covers: [release_management/_index.md]
-covers_token_total: 721
+covers_token_total: 670
 summary_level: d3
-token_count: 641
+token_count: 606
 type: summary
 ---
 # Release Management / CI
 
-This area describes the repo’s release automation and local quality gates. It is organized as a two-layer safety model: **`husky_pre_commit_checks.md`** handles pre-commit validation, while **`changesets_and_github_actions_ci.md`** manages the post-merge Changesets release and npm publish flow.
+This level-3 view organizes the repository’s automation into two linked areas: **release publishing via Changesets + GitHub Actions** and **local quality gates via Husky pre-commit checks**. Across both, the repo relies on tooling, workflow configuration, and generated-state boundaries rather than manual release or commit discipline.
 
-## Core structure
+## Release publishing and workflow automation
+See **changesets_and_github_actions_ci.md** and **changesets_release_pr_convention.md** for the full release path.
 
-- **Local-first validation, then automated release**
-  - Husky blocks commits until formatting, linting, and typechecking pass.
-  - GitHub Actions + Changesets handle release PR creation and publishing after merge.
-
-- **Generated workspace state is excluded**
-  - `.brv/` is treated as local/generated state.
-  - It is excluded from Git and formatting to avoid false failures in checks.
-
-## `changesets_and_github_actions_ci.md`
-
-Covers the Changesets-driven release pipeline and GitHub Actions publish setup.
-
-- **Release sequence**
+- Publishing is **Changesets-driven** and runs through **GitHub Actions** using `NPM_TOKEN`.
+- The standard flow is:
   - `pnpm changeset`
   - merge to `main`
-  - GitHub opens a Changesets release PR
+  - GitHub opens a release PR
   - merge the release PR
-  - npm publish using `NPM_TOKEN`
-
-- **Operational requirements**
-  - GitHub Actions must be enabled
-  - workflow permissions must allow read/write, or workflows must declare explicit permissions
-  - `NPM_TOKEN` must be an npm automation token with publish access
-  - if release PR creation fails, enable **Allow GitHub Actions to create and approve pull requests**
-
-- **Verification checks**
+  - npm publish runs via `NPM_TOKEN`
+- Required setup includes:
+  - GitHub Actions enabled
+  - workflow permissions for read/write or explicit permissions in workflow files
+  - `NPM_TOKEN` with publish access
+- If release PR creation fails, enable **“Allow GitHub Actions to create and approve pull requests.”**
+- Relevant files: `.changeset/config.json`, `.github/workflows/ci.yml`, `.github/workflows/release.yml`, `package.json`, `README.md`, `tsconfig.json`, `.oxlintrc.json`
+
+### Release PR convention
+See **changesets_release_pr_convention.md** for naming and version handling.
+
+- Release PRs use the conventional commit style: `chore(release): v{version}`
+- The workflow reads the bumped version after `changeset version` / `version-packages`
+- That version is reused for both the PR title and commit message
+- If no changesets exist, the workflow still falls back to `changesets/action@v1` for trusted-publishing release publish
+
+## Pre-commit checks with Husky
+See **husky_pre_commit_checks.md** for the local commit gate.
+
+- Husky is wired through `package.json` via `prepare: husky`
+- `.husky/pre-commit` runs:
   - `pnpm format:check`
   - `pnpm lint`
   - `pnpm typecheck`
-  - `pnpm build`
-  - `pnpm pack --dry-run`
-
-- **Related files**
-  - `.changeset/config.json`
-  - `.github/workflows/ci.yml`
-  - `.github/workflows/release.yml`
-  - `package.json`
-  - `README.md`
-  - `tsconfig.json`
-  - `.oxlintrc.json`
-
-## `husky_pre_commit_checks.md`
-
-Covers the repo-local Husky pre-commit enforcement.
-
-- **Hook flow**
-  - install Husky
-  - run `prepare: husky`
-  - pre-commit executes:
-    - `pnpm format:check`
-    - `pnpm lint`
-    - `pnpm typecheck`
-
-- **Behavior and constraints**
-  - relies on existing format, lint, and typecheck scripts
-  - no `pnpm test` hook is used because no test script exists
-  - `.brv/` is excluded from Git and from `oxfmt`
-
-- **Related files**
-  - `package.json`
-  - `.husky/pre-commit`
-  - `.gitignore`
-  - `.oxfmtrc.json`
-
-## Relationship between the child entries
-
-- **`husky_pre_commit_checks.md`** protects changes before they enter the repo.
-- **`changesets_and_github_actions_ci.md`** governs release and publish after merge.
-- Together they form a release process that is locally validated, CI-driven, credential-gated, and insulated from generated `.brv/` noise.
+- `pnpm test` is not used because no test script exists
+- Local ByteRover state in `.brv/` is treated as generated state:
+  - ignored in `.gitignore`
+  - excluded from `oxfmt` via `.oxfmtrc.json`
+- Relevant files: `package.json`, `.husky/pre-commit`, `.gitignore`, `.oxfmtrc.json`
+
+## Shared pattern
+- Both areas formalize repository behavior through configuration and scripts.
+- Both enforce boundaries around generated/local state and rely on explicit permissions or tooling gates to control behavior.

.brv/context-tree/_manifest.json

@@ -3,19 +3,19 @@
     {
       "order": 3,
       "path": "_index.md",
-      "tokens": 641,
+      "tokens": 606,
       "type": "summary"
     },
     {
       "order": 2,
       "path": "release_management/_index.md",
-      "tokens": 660,
+      "tokens": 610,
       "type": "summary"
     },
     {
       "order": 1,
       "path": "release_management/ci/_index.md",
-      "tokens": 685,
+      "tokens": 680,
       "type": "summary"
     },
     {
@@ -26,6 +26,14 @@
       "tokens": 79,
       "type": "context"
     },
+    {
+      "abstractPath": "release_management/ci/changesets_release_pr_convention.abstract.md",
+      "abstractTokens": 47,
+      "importance": 50,
+      "path": "release_management/ci/changesets_release_pr_convention.md",
+      "tokens": 47,
+      "type": "context"
+    },
     {
       "abstractPath": "release_management/ci/husky_pre_commit_checks.abstract.md",
       "abstractTokens": 67,
@@ -35,13 +43,13 @@
       "type": "context"
     }
   ],
-  "generated_at": "2026-04-24T13:24:29.436Z",
+  "generated_at": "2026-04-24T15:50:46.847Z",
   "lane_tokens": {
-    "contexts": 146,
+    "contexts": 193,
     "stubs": 0,
-    "summaries": 1986
+    "summaries": 1896
   },
-  "source_fingerprint": "f3bd467b1078e8717bfebf5e848ced38dcf75f294d733223f555dc7d28db0672",
-  "total_tokens": 2132,
+  "source_fingerprint": "2d72d81af571d7caee694c6b26e9b5cff54cd98cb2e3c08d5e58ff3e1761e91b",
+  "total_tokens": 2089,
   "version": 1
 }

.brv/context-tree/release_management/_index.md

@@ -1,89 +1,56 @@
 ---
-children_hash: bbb6813e6a175d94092eb92c8b5ebba9b0601f56568bc64b20ac107627f155be
-compression_ratio: 0.8695652173913043
+children_hash: 0c970e81d042036723d5a22364ed01d05c71ac83d7e4ac0bb6c759160fa042dc
+compression_ratio: 0.799475753604194
 condensation_order: 2
 covers: [ci/_index.md]
-covers_token_total: 759
+covers_token_total: 763
 summary_level: d2
-token_count: 660
+token_count: 610
 type: summary
 ---
 # Release Management / CI
 
-This area documents the repo’s release automation and pre-commit quality gates. The child entries show a two-layer safety model: **`husky_pre_commit_checks.md`** enforces local commit-time validation, while **`changesets_and_github_actions_ci.md`** handles the post-merge release and npm publish pipeline.
+This d2 summary condenses the repo’s automation into two linked controls: **Changesets + GitHub Actions release publishing** and **Husky pre-commit quality gates**. The core pattern is consistent: repository behavior is enforced through tooling, workflow configuration, and generated-state boundaries rather than manual release steps.
 
-## Core structural themes
+## Release publishing and workflow automation
+See **changesets_and_github_actions_ci.md** and **changesets_release_pr_convention.md** for the full release path.
 
-- **Local-first validation, then automated release**
-  - Husky runs checks before commits are accepted.
-  - GitHub Actions + Changesets manage the release PR and publish flow after merge.
-
-- **Generated workspace state is excluded**
-  - `.brv/` is treated as local/generated state.
-  - It is excluded from Git and formatting to avoid false failures in checks.
-
-## `changesets_and_github_actions_ci.md`
-
-Covers the **Changesets-driven release flow** and GitHub Actions publish setup.
-
-- **Release sequence**
+- Publishing is **Changesets-driven** and runs through **GitHub Actions** using `NPM_TOKEN`.
+- Required setup includes:
+  - GitHub Actions enabled
+  - workflow permissions allowing read/write or explicit permissions in workflow files
+  - `NPM_TOKEN` as an npm automation token with publish access
+- Standard flow:
   - `pnpm changeset`
   - merge to `main`
-  - GitHub opens a Changesets release PR
+  - GitHub opens a release PR
   - merge the release PR
-  - npm publish using `NPM_TOKEN`
+  - npm publish runs via `NPM_TOKEN`
+- If release PR creation fails, enable **“Allow GitHub Actions to create and approve pull requests.”**
+- Relevant files: `.changeset/config.json`, `.github/workflows/ci.yml`, `.github/workflows/release.yml`, `package.json`, `README.md`, `tsconfig.json`, `.oxlintrc.json`
+
+### Release PR convention
+See **changesets_release_pr_convention.md** for naming and version handling.
 
-- **Operational requirements**
-  - GitHub Actions must be enabled
-  - workflow permissions must allow read/write, or workflows must declare explicit permissions
-  - `NPM_TOKEN` must be an npm automation token with publish access
-  - if release PR creation fails, enable **Allow GitHub Actions to create and approve pull requests**
+- Release PRs use conventional commit style: `chore(release): v{version}`
+- The workflow reads the bumped version after `changeset version` / `version-packages`
+- That version is reused for both PR title and commit message
+- If no changesets exist, the workflow still falls back to `changesets/action@v1` for trusted-publishing release publish
 
-- **Related files**
-  - `.changeset/config.json`
-  - `.github/workflows/ci.yml`
-  - `.github/workflows/release.yml`
-  - `package.json`
-  - `README.md`
-  - `tsconfig.json`
-  - `.oxlintrc.json`
+## Pre-commit checks with Husky
+See **husky_pre_commit_checks.md** for the local commit gate.
 
-- **Verification checks**
+- Husky is wired through `package.json` via `prepare: husky`
+- `.husky/pre-commit` runs:
   - `pnpm format:check`
   - `pnpm lint`
   - `pnpm typecheck`
-  - `pnpm build`
-  - `pnpm pack --dry-run`
-
-## `husky_pre_commit_checks.md`
-
-Covers the **repo-local pre-commit enforcement** added with Husky.
-
-- **Hook flow**
-  - install Husky
-  - run `prepare: husky`
-  - pre-commit executes:
-    - `pnpm format:check`
-    - `pnpm lint`
-    - `pnpm typecheck`
-
-- **Behavior and constraints**
-  - relies on existing format, lint, and typecheck scripts
-  - no test script exists, so the hook uses these checks instead of `pnpm test`
-  - `.brv/` is excluded from Git and from `oxfmt`
-
-- **Related files**
-  - `package.json`
-  - `.husky/pre-commit`
-  - `.gitignore`
-  - `.oxfmtrc.json`
-
-## Relationship between the child entries
-
-- **`husky_pre_commit_checks.md`** guards changes before they enter the repo.
-- **`changesets_and_github_actions_ci.md`** governs the automated release path after merges.
-- Together they form a release process that is:
-  - locally validated,
-  - CI-driven,
-  - gated by npm publishing credentials,
-  - and protected from generated-state noise in `.brv/`.
+- `pnpm test` is not used because no test script exists
+- Local ByteRover state in `.brv/` is treated as generated state:
+  - ignored in `.gitignore`
+  - excluded from `oxfmt` via `.oxfmtrc.json`
+- Relevant files: `package.json`, `.husky/pre-commit`, `.gitignore`, `.oxfmtrc.json`
+
+## Shared pattern
+- Both areas formalize automation through repo configuration and scripts.
+- Both preserve boundaries around generated/local state and rely on explicit permissions or tooling gates to control behavior.