AGENTS.md · diff

git:20260507.1f612dc to git:20260911.13694e1

7 added, 1 removed. Audit A to A.

# 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

├── 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

+ These govern the PHP this skill guides people to write — `**/*.php`. They do not

+ apply to Markdown, YAML, JSON or shell in this repository. Stated because a

+ reviewer reading this file as repository-wide guidance has no other way to tell:

+ `knowledge_base.code_guidelines` applies a guidelines document to every path, and

+ nothing in that setting can scope it.

1. **PHP 8.1+ required** — promotion, readonly, enums, match, attributes, union types.

- 2. **Strict types** — `declare(strict_types=1)` in every file.

+ 2. **Strict types** — `declare(strict_types=1)` in every PHP file.

3. **DTOs over arrays** — typed objects for structured data, never raw arrays.

4. **Backed enums** — replace string/int constants for fixed value sets.

5. **PHPStan ≥ 9** — level 9 minimum, level 10 for new projects, `treatPhpDocTypesAsCertain: false`.

6. **Static analysis stack** — PHPStan + PHPat + Rector + PHP-CS-Fixer (`@PER-CS`).

7. **PSR / PER-CS compliance** — see `references/psr-per-compliance.md`.

8. **Type-hint against PSR interfaces**, not implementations.

## References

- [SKILL.md](skills/php-modernization/SKILL.md) — agent contract and reference-routing table

- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — architecture overview

- [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