feat: add opt-in Composer metadata normalization

.changelog/composer-metadata-normalization.md

@@ -0,0 +1,10 @@
+---
+category: added
+type: minor
+---
+
+Add opt-in `normalize-composer` metadata checking and explicit `--apply`, using the composer-normalize library while retaining literal dependency constraints and significant ordering. Keep PHP check/fix unchanged; never execute Composer scripts/plugins or update locks, and report stale hashes before/after explicit manifest writes.
+
+Declare the added runtime libraries with compatible caret constraints while retaining the verified locked package versions.
+
+Keep rejected metadata contents out of invalid-JSON diagnostics, including verbose output.

AGENTS.md

@@ -26,6 +26,9 @@ reusables under `.github/workflows/code-standards*.yml`, own event workflows use
 - `check` MUST NOT pass `--fix`, update dependencies, execute application tests,
   publish or change source. Tool caches may live in the system temporary directory.
 - `fix` is explicit, local and potentially partial on failure; inspect its diff.
+- `normalize-composer` is opt-in metadata checking; only `--apply` writes
+  `composer.json`. Never maintain locks, activate plugins or run Composer scripts
+  from normalization. Preserve literal constraints and significant ordering.
 - No implicit risky migration, PHP-version migration or semantic refactor profile.
   Future semantic work requires an explicit consumer target PHP and opt-in.
 - PR checks use `pull_request`, exact head/base, merge-base comparison and Git's
@@ -75,6 +78,7 @@ for the exact local base/head before publication; do not claim remote CI evidenc
 - [Policy comparison](docs/policy.rst): evidence, rule differences and extraction gates.
 - [Explicit Rector](docs/rector.rst): opt-in native semantic preview/application; executable configuration owns target PHP, rules, source paths and caches.
 - [Magic-number analysis](docs/magic-numbers.rst): opt-in native PHPMND selection, policy options, output and exit contracts; separate from check/fix.
+- [Composer normalization](docs/composer-normalization.rst): opt-in metadata check/application, constraint preservation and lock-hash diagnostics; separate from PHP check/fix.
 - [Resolved preset](docs/resolved-preset.rst): compiled rules, golden contracts and dependency-update review.
 - [Legacy fixer comparison](docs/legacy-fixer-comparison.rst): fixed-source inventory, loaded dependencies and remaining profile decisions.
 - [PHPDoc comparison](docs/phpdoc-comparison.rst): actual custom-rule registration, source contracts and remaining golden decisions.

README.md

@@ -205,11 +205,13 @@ its input contract independently of Composer package constraints.
 | --- | --- |
 | `code-standards check` | Parse selected PHP and check style without changing source. |
 | `code-standards fix` | Explicitly format selected source, then verify; failures may leave partial changes. |
+| [`code-standards normalize-composer`](docs/composer-normalization.rst) | Check Composer metadata without writing; `--apply` changes only `composer.json` and reports stale lock hashes. |
 | `code-standards refactor --config=rector.php` | Preview native semantic rules; only `--apply` permits writes, followed by verification. |
 | [`code-standards magic-numbers`](docs/magic-numbers.rst) | Analyze selected source with opt-in PHPMND, independently of check/fix; findings keep a nonzero status. |
 | `code-standards refactor --config=rector.php --format=json` | Emit native JSON for preview only; JSON cannot be combined with `--apply`. |
 | `ECSConfig::configure(?callable $customize)` | Return the native ECS builder; apply the optional callback last. |
 | `help check` / `help fix` / `help refactor` / `help magic-numbers` | Show the installed Symfony option definitions. |
+| `help normalize-composer` | Show metadata normalization options and explicit write authority. |
 
 Internal CLI services are implementation details. Supported configuration uses
 native ECS rule imports, skips and configured rules; there is no second DSL.

composer.json

@@ -39,7 +39,11 @@
     "require": {
         "php": "^8.3",
         "composer-runtime-api": "^2.2",
+        "composer/composer": "^2.10.3",
         "container-interop/service-provider": "^0.4.1",
+        "ergebnis/json": "^1.7.0",
+        "ergebnis/json-normalizer": "^4.11.0",
+        "ergebnis/json-printer": "^3.9.1",
         "fast-forward/container": "~1.10.1",
         "phpstan/phpstan": "~2.1.51",
         "povils/phpmnd": "^3.6.1",