[architecture] Extract code-standards: formatting, PHPDoc policy and explicit refactoring #379

Proposal / validation gate: this issue records an extraction design for maintainer validation. Repository/package names are candidates. Approve the boundary and migration plan before implementation; this task does not authorize creating repositories, implementing the extraction, releases or consumer rollout.

Problem and proposal

Formatting, PHPDoc source cleanup and behavior-changing Rector transformations are bundled with tests, docs rendering and dependency tooling. Propose php-fast-forward/code-standards / fast-forward/code-standards, rather than code-style (too narrow for Rector) or code-quality (too broad). Names are design proposals, not created repositories.

Inspected source and ownership

• CodeStyleCommand: ECS + Composer Normalize, currently even a lock refresh. PR feat!: distribute DevTools through CPX and portable skills #376 removes that refresh; do not preserve it as a formatting requirement.
• ECSConfig, RectorConfig, resources/ecs, ecs.php, rector.php, .php-cs-fixer.dist.php, src/Rector/* and PhpDocCommand define policy/config/custom rules.
• Source PHPDoc cleanup belongs here; rendered API docs/Wiki belong to [RFC / Architecture] Extract Wiki and docs into a standalone PHP package, CLI, skill and automation #367. Combined standards/reports composition stays with DevTools, not this package.

Comparison with coisa/php-cs-fixer

Inspected fdee71bc63d4846463d7715afbc515d63ef2c537: a PHP ^8.3 / PHP-CS-Fixer ^3.95 preset library with HeaderExtractor, Config, Finder, per-config overrides and changed-file PR workflow. It is not an ECS/Rector/test/docs orchestrator. Its @auto/PER and risky migration policy differs from DevTools' Symfony/PSR-12/Symplify/ECS and Rector sets. Reuse an adapter or shared preset only after fixture-based equivalence; do not silently adopt risky rules or claim either preset supersedes the other.

Concrete tasks / acceptance

• Produce rule-by-rule comparison including headers, Finder exclusions, PHP minimum, rule precedence, risky policies and custom Rector PHPDoc rules; select canonical policy without duplicating competing fixer passes.
• Define separate check/style-fix and semantic-refactor commands/profiles; explicit opt-in for behavior-changing rules, consumer target PHP from configuration, no dependency upgrades or unrelated file mutation in check mode.
• Preserve local config imports and unscoped public config APIs. Compare library/preset reuse against isolated CLI where feasible.
• Migrate phpdoc-code-style skill/procedure with one owner; PR feat!: distribute DevTools through CPX and portable skills #376 proposed portable skill layout must not become a second copy.
• Add golden fixtures, second-pass idempotency, check-no-write, supported PHP/runtime matrices, malformed config/path cases and failure propagation. Full scans when rules/config/dependencies change; changed-file workflow is only an optimization.
• Map optional Twig Evaluate Twig-CS-Fixer + twigcs + twig-linter integration for template quality #269 and magic-value Evaluate phpmnd integration for magic value quality checks #268 evaluations here only if selected; keep capability decisions open, not completed by extraction.

Alternatives

Pure code-style would understate semantic risk; one quality mega-package would retain docs/tests coupling. Do not replace ECS with PHP-CS-Fixer solely to reduce dependency count. Composer metadata normalization ownership is coordinated with repository-metadata; exactly one writer, with a compatibility alias if needed.

Delivery and migration gates

• One domain owner for library/CLI, relevant reusable workflow/Action, portable skill, tests and versioned docs; adapters call the same implementation. Do not create a surface solely for symmetry.
• No production dependency back to DevTools; no generic Actions repository as mandatory runtime. CPX/external execution does not isolate PHPUnit/config classes loaded in the same PHP process.
• Preserve project overrides, exit codes, JSON contracts, working directory/cache/color options, and PHP consumer compatibility. Distinguish tool runtime from application minimum.
• Validate Composer archives, runtime resources and skill provenance outside the source checkout; no host-cache absolute paths in consumer files.
• Release availability, exact workflow/runtime/skill compatibility, then pilot consumer PRs and rollback are separate gates. Never point consumers at a not-yet-published version. No release/merge/deploy/repository creation is performed by this planning issue.
• Root architecture tracking: [architecture] Plan domain-owned tooling extraction and DevTools orchestration #240; release-safe refs Define release-safe refs for consumer workflow wrappers and checked-out actions #238; open distribution redesign PR feat!: distribute DevTools through CPX and portable skills #376 must be revalidated before implementation. Evidence baseline: DevTools main 35d27ee (2026-10-21), not an assertion that PR feat!: distribute DevTools through CPX and portable skills #376 is merged.

Architectural / Isolation Criteria

• MUST: Core logic MUST live in dedicated services; commands/controllers only orchestrate.
• MUST: Separate input resolution, domain transformations and rendering; keep CLI/framework I/O out of reusable behavior.
• MUST: Support reuse/extensibility without major refactoring and deterministic, testable exits/output.
• MUST: Separate gathering/transformation from writes/publishing; repeated execution MUST be idempotent or explicitly bounded.
• MUST: Update README, command/config docs, skill references and synchronized consumer examples with the actual new ownership.