fix(release): set useCommitScope to true to prevent global major bumps

CLAUDE.md

@@ -29,6 +29,19 @@ Husky is configured:
 - `npm ci` is used in CI (not `npm install`)
 - Only affected packages are linted/tested/built (`nx affected`)
 
+## Nx Release Configuration
+
+**CRITICAL: Do not change `useCommitScope` in `nx.json`**
+
+`nx.json` has `"conventionalCommits": { "useCommitScope": true }` (line 73). This controls how breaking changes affect version bumps:
+
+- `useCommitScope: true` (current, REQUIRED) — Breaking changes only bump packages named in commit scope. Example: `feat(rbac)!: breaking change` bumps rbac to major, other packages get patch for dependency update.
+- `useCommitScope: false` (DANGEROUS) — Breaking changes bump ALL packages with modified files to major, regardless of commit scope. Causes `preserveMatchingDependencyRanges` failures when shared package jumps major but clients depend on `^2.x`.
+
+**Why this matters:** Shared package is a dependency of all clients. With `useCommitScope: false`, any breaking change touching shared's files triggers major bumps across all 15 packages, breaking semver ranges and failing releases.
+
+See: Nx source `packages/nx/src/command-line/release/utils/semver.ts:44`
+
 ## Working with This Repo
 
 - Never directly call CLI tools (`jest`, `eslint`, `tsc`). Use npm scripts.

CONTRIBUTING.md

@@ -86,3 +86,19 @@ See [docs/testing-guidelines.md](docs/testing-guidelines.md) for details on test
 ## Release Process
 
 Releases are automated via Nx Release on the `main` branch. Each package is independently versioned based on conventional commit history. Do not manually bump versions.
+
+### Critical Configuration: `useCommitScope`
+
+**Do not change `"useCommitScope": true` in `nx.json` (line 73).**
+
+This setting controls how breaking changes affect version bumps:
+
+- **`true` (current)**: Breaking changes only bump packages named in commit scope
+  - Example: `feat(rbac)!: breaking change` → rbac gets major bump, other packages get patch for dependency update
+  - Prevents cascading major bumps across unrelated packages
+
+- **`false` (dangerous)**: Breaking changes bump ALL packages with modified files to major
+  - Causes `preserveMatchingDependencyRanges` failures when shared package jumps major but clients still depend on `^2.x`
+  - Results in failed releases
+
+Since `packages/shared/` is a dependency of all 15 client packages, setting `useCommitScope: false` would cause any breaking change touching shared files to trigger major bumps across the entire monorepo.

nx.json

@@ -70,7 +70,7 @@
       "manifestRootsToUpdate": ["{projectRoot}", "{projectRoot}/dist"]
     },
     "conventionalCommits": {
-      "useCommitScope": false
+      "useCommitScope": true
     },
     "changelog": {
       "workspaceChangelog": false,
@@ -138,5 +138,6 @@
         "ciTargetName": "e2e-ci"
       }
     }
-  ]
+  ],
+  "analytics": false
 }