Harden php-transformer release metadata

.github/workflows/php-transformer.yml

@@ -0,0 +1,42 @@
+name: PHP Transformer
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/php-transformer.yml"
+      - "php-transformer/**"
+  push:
+    branches:
+      - trunk
+    paths:
+      - ".github/workflows/php-transformer.yml"
+      - "php-transformer/**"
+
+jobs:
+  validate:
+    name: Composer validate and test
+    runs-on: ubuntu-latest
+
+    defaults:
+      run:
+        working-directory: php-transformer
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: "8.1"
+          coverage: none
+          tools: composer:v2
+
+      - name: Install dependencies
+        run: composer install --no-interaction --prefer-dist --no-progress
+
+      - name: Validate Composer package metadata
+        run: composer validate --strict
+
+      - name: Run package tests
+        run: composer test

php-transformer/README.md

@@ -138,6 +138,8 @@ Run the package contract and parity fixtures with `composer test`. The checked-i
 
 The package lives in a subtree of the Blocks Engine repository. Composer cannot discover a package whose `composer.json` is below the repository root from a plain monorepo VCS tag. After release, consumers need either a subtree-split/Packagist package whose root is `php-transformer/`, or an explicit Composer `package` repository that points at the release archive and maps autoloading to the subtree.
 
+This package intentionally omits `replace` and `provide` declarations for the older downstream package names. Those packages expose their own WordPress plugin bootstraps, functions, hooks, CLI commands, abilities, and product-shaped reports, so the canonical transformer package should not satisfy their Composer requirements directly.
+
 Preferred downstream constraint once the package is published through Packagist or a subtree-split repository:
 
 ```sh
@@ -180,6 +182,16 @@ If the first release is only available as a Blocks Engine monorepo archive, down
 
 Before the first tag is available, review branches may use a Composer VCS or path repository with an inline alias. Merge-ready downstream PRs should replace those review-only constraints with one of the no-local-path release shapes above.
 
+### Release Readiness Checklist
+
+Before tagging the first package release:
+
+- Run `composer validate --strict` and `composer test` from `php-transformer/`.
+- Confirm `VERSION`, `php-transformer.php`, and the intended tag all resolve to `0.1.0`.
+- Confirm Packagist or the subtree split indexes `php-transformer/` as the package root, not the repository root.
+- Confirm downstream merge candidates use `automattic/blocks-engine-php-transformer:^0.1.0` instead of path repositories, unpublished branches, or inline aliases.
+- Keep the transformer metadata free of downstream wrapper package names, `replace`, and `provide` declarations.
+
 Homeboy owns the local release preflight for this package through `php-transformer/homeboy.json`. The only version target is `VERSION`, currently `0.1.0`; release automation should tag from the package subtree after the upstream PRs are merged, without adding wrapper-package names to this package metadata.
 
 Recommended post-merge dry-run:

php-transformer/composer.json

@@ -50,5 +50,10 @@
       "php": "8.1.0"
     },
     "sort-packages": true
+  },
+  "extra": {
+    "branch-alias": {
+      "dev-trunk": "0.1.x-dev"
+    }
   }
 }

php-transformer/docs/consumer-prs/packaging.md

@@ -138,6 +138,8 @@ Downstream wrappers must support their current unprefixed development installs.
 
 The first tagged release should be `0.1.0` unless maintainers choose a repo-wide release scheme before merge.
 
+The package does not declare a Composer `version` field. Composer derives immutable release versions from tags; the checked-in `VERSION` file and plugin header are Homeboy release targets that should match the first tag. The `dev-trunk` branch alias is only a pre-release convenience for review and Packagist metadata, not a substitute for the first `0.1.0` tag.
+
 Release readiness preflight before tagging:
 
 ```sh