Set stricter versions for internal packages depending on each other

agents/dependencies.md

@@ -32,7 +32,7 @@ Reverse edges (e.g. `utils` importing from `cnpj-fmt`) are forbidden.
 
 ### When developer approval is NOT needed
 
-Bumping an **already-declared internal dependency** to a new published semver range that mirrors what a sibling package uses (e.g. upgrading `lacus/utils: ^1.0` to `^1.1` across all packages) is safe to replicate without explicit approval. Verify the existing declaration before updating.
+Bumping an **already-declared internal dependency** to a new published semver range that mirrors what a sibling package uses (e.g. upgrading `lacus/cnpj-dv: ~1.1.0` to `~1.2.0` across all packages) is safe to replicate without explicit approval. Verify the existing declaration before updating.
 
 ## Before changing dependencies
 
@@ -43,17 +43,34 @@ Bumping an **already-declared internal dependency** to a new published semver ra
 
 ## Internal dependencies (Packagist versioning)
 
-PHP packages depend on each other via published Packagist semver constraints — not path repositories or workspace symlinks:
+PHP packages depend on each other via published Packagist semver constraints — not path repositories or workspace symlinks.
+
+### Version constraint convention
+
+Use **tilde notation** (`~X.Y.Z`) for BR Utils monorepo packages (`lacus/cpf-*`, `lacus/cnpj-*`, `lacus/br-utils`):
 
 ```json
 {
   "require": {
     "php": "^8.2",
+    "lacus/cnpj-dv": "~1.1.0",
     "lacus/utils": "^1.0"
   }
 }
 ```
 
+Tilde notation allows only patch-level updates within the pinned minor line (`~1.1.0` accepts `>=1.1.0 <1.2.0`). This prevents unexpected minor-version feature additions from propagating between BR Utils packages without explicit constraint bumps and changelog visibility.
+
+**Exception — `lacus/utils`:** Use **caret notation** (`^X.Y`). `lacus/utils` is a standalone foundation package (planned to detach from this monorepo) with its own release roadmap. BR Utils packages should accept minor-version updates from `lacus/utils` — bug fixes and new features alike — while still excluding major versions (`^1.0` accepts `>=1.0.0 <2.0.0`).
+
+When bumping a **tilde-constrained** internal dependency, specify the **full `X.Y.Z` version** based on the currently published release — look up the latest tag with:
+
+```bash
+cd php && git tag -l 'lacus/<pkg>@*' | sort -V | tail -n 1
+```
+
+Strip the `lacus/<pkg>@` prefix to get the bare SemVer (e.g. `1.1.0`), then write `~1.1.0`. For `lacus/utils`, bump the caret minor line instead (e.g. `^1.0` → `^1.1`) when a new minor release should be adopted.
+
 After editing any `composer.json` dependency field, install and regenerate the lockfile:
 
 ```bash

packages/br-utils/CHANGELOG.md

@@ -1,5 +1,11 @@
 # lacus/br-utils
 
+## 2.0.1
+
+### Patch Changes
+
+- **Dependency constraints** — Changed internal dependency version constraints from caret to tilde notation for more predictable feature propagation.
+
 ## 2.0.0
 
 ### 🎉 v2 at a glance 🎊

packages/br-utils/composer.json

@@ -65,8 +65,8 @@
   },
   "require": {
     "php": "^8.2",
-    "lacus/cnpj-utils": "^2.0",
-    "lacus/cpf-utils": "^1.1"
+    "lacus/cnpj-utils": "~2.0.0",
+    "lacus/cpf-utils": "~1.1.0"
   },
   "require-dev": {
     "pestphp/pest": "^3.8",

packages/cnpj-gen/CHANGELOG.md

@@ -1,5 +1,11 @@
 # lacus/cnpj-gen
 
+## 2.1.1
+
+### Patch Changes
+
+- **Dependency constraints** — Changed internal dependency version constraints from caret to tilde notation for more predictable feature propagation.
+
 ## 2.1.0
 
 ### Improvements

packages/cnpj-gen/composer.json

@@ -54,7 +54,7 @@
   },
   "require": {
     "php": "^8.2",
-    "lacus/cnpj-dv": "^1.1",
+    "lacus/cnpj-dv": "~1.1.0",
     "lacus/utils": "^1.0"
   },
   "require-dev": {

packages/cnpj-utils/CHANGELOG.md

@@ -1,5 +1,11 @@
 # lacus/cnpj-utils
 
+## 2.0.1
+
+### Patch Changes
+
+- **Dependency constraints** — Changed internal dependency version constraints from caret to tilde notation for more predictable feature propagation.
+
 ## 2.0.0
 
 ### 🎉 v2 at a glance 🎊

packages/cnpj-utils/composer.json

@@ -58,9 +58,9 @@
   },
   "require": {
     "php": "^8.2",
-    "lacus/cnpj-fmt": "^2.0",
-    "lacus/cnpj-gen": "^2.1",
-    "lacus/cnpj-val": "^2.0"
+    "lacus/cnpj-fmt": "~2.0.0",
+    "lacus/cnpj-gen": "~2.1.0",
+    "lacus/cnpj-val": "~2.0.0"
   },
   "require-dev": {
     "pestphp/pest": "^3.8"

packages/cnpj-val/CHANGELOG.md

@@ -1,5 +1,11 @@
 # lacus/cnpj-val
 
+## 2.0.1
+
+### Patch Changes
+
+- **Dependency constraints** — Changed internal dependency version constraints from caret to tilde notation for more predictable feature propagation.
+
 ## 2.0.0
 
 ### 🎉 v2 at a glance 🎊

packages/cnpj-val/composer.json

@@ -53,7 +53,7 @@
   },
   "require": {
     "php": "^8.2",
-    "lacus/cnpj-dv": "^1.1",
+    "lacus/cnpj-dv": "~1.1.0",
     "lacus/utils": "^1.0"
   },
   "require-dev": {

packages/cpf-utils/CHANGELOG.md

@@ -1,5 +1,11 @@
 # lacus/cpf-utils
 
+## 1.1.1
+
+### Patch Changes
+
+- **Dependency constraints** — Changed internal dependency version constraints from caret to tilde notation for more predictable feature propagation.
+
 ## 1.1.0
 
 ### Improvements

packages/cpf-utils/composer.json

@@ -50,9 +50,9 @@
   },
   "require": {
     "php": ">=8.1",
-    "lacus/cpf-fmt": "^1.0",
-    "lacus/cpf-gen": "^1.0",
-    "lacus/cpf-val": "^1.0"
+    "lacus/cpf-fmt": "~1.0.0",
+    "lacus/cpf-gen": "~1.0.1",
+    "lacus/cpf-val": "~1.0.0"
   },
   "require-dev": {
     "phpunit/phpunit": "^10.5",

packages/cpf-val/CHANGELOG.md

@@ -1,5 +1,11 @@
 # lacus/cpf-val
 
+## 1.0.1
+
+### Patch Changes
+
+- **Dependency constraints** — Changed internal dependency version constraints from caret to tilde notation for more predictable feature propagation.
+
 ## 1.0.0
 
 ### Stable v1 API

packages/cpf-val/composer.json

@@ -45,7 +45,7 @@
   },
   "require": {
     "php": ">=8.1",
-    "lacus/cpf-gen": "^1.0"
+    "lacus/cpf-gen": "~1.0.1"
   },
   "require-dev": {
     "phpunit/phpunit": "^10.5",