AGENTS.md · git:20260911.ea46a7f · 2026-09-11 · sha256 c25cb85eb256f347
AGENTS.md git:20260911.ea46a7fA
Immutable. This exact content is served forever at /api/v1/blob/c25cb85eb256f347.
# Agent Guide — php-modernization-skill ## Repo Structure ``` . ├── skills/php-modernization/ │ ├── SKILL.md # Agent contract (router + guardrails) │ ├── checkpoints.yaml # Mechanical + LLM-review checkpoints │ ├── references/ # Lazy-loaded detail docs │ │ ├── php8-features.md # PHP 8.0–8.3 baseline │ │ ├── php-8.4.md # PHP 8.4 (hooks, asymmetric vis., lazy) │ │ ├── php-8.5.md # PHP 8.5 (pipe, array_first/last, NoDiscard) │ │ ├── static-analysis-tools.md # PHPStan / PHPat / Rector / PHP-CS-Fixer │ │ ├── phpstan-compliance.md # Levels, baseline, extensions │ │ ├── php-cs-fixer-deprecations.md # Renamed / removed rules │ │ ├── psr-per-compliance.md # Active PSR + PER-CS │ │ ├── psr15-middleware-architecture.md # Middleware stacking │ │ ├── type-safety.md # Generics, unions, intersections │ │ ├── request-dtos.md # DTO / VO patterns │ │ ├── adapter-registry-pattern.md # Registries from DB config │ │ ├── multi-version-adapters.md # Cross-version compatibility │ │ ├── symfony-patterns.md # PSR exemplar patterns │ │ ├── doctrine-modernization-edges.md # Doctrine 2.x/3.x edges │ │ ├── api-platform-edges.md # API Platform resource separation │ │ ├── immutability-boundaries.md # readonly vs. hooks vs. mutable │ │ ├── mutation-testing.md # Infection diff-mode │ │ ├── migration-strategies.md # Upgrade planning │ │ └── core-rules.md # Core modernization rules │ ├── scripts/ │ │ ├── verify_php_project.py # Primary verifier (PEP 723) │ │ ├── modernize_loop.py # Fix orchestrator │ │ ├── introspect.py # Cheap profiler │ │ ├── _common.py # Shared helpers │ │ └── verify-php-project.sh # Backward-compatible Bash wrapper │ └── templates/ │ ├── composer-scripts.json # Drop-in scripts block │ ├── README.md # Template consumption guide │ └── github-actions/php-modernization.yml # Copy-and-modify CI workflow ├── schemas/ │ ├── verification-result.schema.json # Verifier output contract │ └── project-profile.schema.json # Introspector output contract ├── fixtures/ # Synthetic-project regression suite │ ├── generic-composer-minimal/ │ ├── symfony-app-minimal/ │ ├── typo3-extension-minimal/ │ ├── monorepo-minimal/ │ ├── fully-modern/ # Positive control (all checks pass) │ └── README.md ├── scripts/ │ ├── test_fixtures.py # Golden-snapshot diff runner │ └── verify-harness.sh # AGENTS.md/docs harness check ├── docs/ │ ├── ARCHITECTURE.md # Architecture overview │ └── php-rules.md # PHP coding rules (scoped to **/*.php) ├── evals/evals.json # Skill evaluation suite ├── .claude-plugin/plugin.json # Plugin manifest ├── composer.json # Composer package manifest ├── sonar-project.properties # SonarCloud config (excludes fixtures) └── .github/workflows/ # CI workflows ``` ## Commands `uv` is required for the Python tools; the Bash wrapper falls back to `python3` when `uv` is missing. - `composer install` — install Composer dependencies (requires [composer-agent-skill-plugin](https://github.com/netresearch/composer-agent-skill-plugin)). - `bash skills/php-modernization/scripts/verify-php-project.sh [path]` — backward-compatible wrapper for the verifier. - `bash skills/php-modernization/scripts/verify-php-project.sh introspect [path]` — wrapper for the introspector. - `uv run skills/php-modernization/scripts/introspect.py --root .` — emit the project profile (cheap, no subprocesses). - `uv run skills/php-modernization/scripts/verify_php_project.py --root . --format json --summary` — full mechanical verification with `agent_actions[]`. - `uv run skills/php-modernization/scripts/verify_php_project.py --root . --format sarif` — SARIF output for GitHub code scanning. - `uv run skills/php-modernization/scripts/modernize_loop.py --mode dry-run` — orchestrated fix preview (no mutations). - `uv run scripts/test_fixtures.py` — regression suite for the verifier itself. - `bash scripts/verify-harness.sh` — agent-harness consistency check (this file, docs, refs). ## Hard Guardrails The agent contract in [SKILL.md](skills/php-modernization/SKILL.md#hard-guardrails) is binding. Five refusal cases: 1. No `readonly` on Doctrine entities or mapped-superclasses (embeddables are nuanced — see references). 2. Never run Rector without `--dry-run` first. 3. Raising the PHPStan level requires regenerating + committing the baseline in the same change. Shrink, never delete. 4. No blanket `final` on mock targets or extension points without confirmation. 5. Do not edit `@generated` files or files under `var/cache/`, `vendor/`, `node_modules/`, `.Build/`. ## Rules The PHP coding rules live in [docs/php-rules.md](docs/php-rules.md), scoped to `**/*.php` via `.coderabbit.yaml`. They are not repeated here: this file is supplied to reviews for every path, and a PHP rule stated here is evaluated against Markdown and YAML changes too (#116). ## References - [SKILL.md](skills/php-modernization/SKILL.md) — agent contract and reference-routing table - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — architecture overview - [docs/php-rules.md](docs/php-rules.md) — PHP coding rules, scoped to `**/*.php` - [CHANGELOG.md](CHANGELOG.md) — release history - [fixtures/README.md](fixtures/README.md) — regression-suite layout and snapshot rules - [skills/php-modernization/templates/README.md](skills/php-modernization/templates/README.md) — template consumption guide - [schemas/verification-result.schema.json](schemas/verification-result.schema.json) — verifier output contract - [schemas/project-profile.schema.json](schemas/project-profile.schema.json) — introspector output contract