# Instructions for AI coding agents This file is for AI agents (and agent swarms) working on the Cordon Modulith codebase. ## Project in one paragraph Cordon Modulith is a Laravel dev-dependency that verifies boundaries between modules. It statically parses PHP files (nikic/php-parser, never loading code), maps class references to modules, and runs rules (`internal_access`, `undeclared_dependency`, `cycles`). Entry points: `php artisan cordon:verify` (and `cordon:docs`), the Pest expectation `toRespectBoundaries()` and the PHPStan rule. Pipeline: `ModuleResolver` → `FileCollector` → `DependencyExtractor` → `Analyzer` (cross-module edges) → `Rule`s → `Baseline` → `Reporter`. ## Hard rules 1. **Contracts are frozen.** Do not change interfaces in `src/Contracts`, value objects in `src/Analysis` and `src/Module`, the config shape, the baseline JSON format or command options without an accepted ADR in `docs/adr`. If you believe a change is needed, stop and write the ADR proposal instead. 2. **Tests first.** Write or update the acceptance test before the implementation. Every detection change needs a fixture in `tests/Fixtures`. 3. **Never load analysed code.** No `class_exists`, `require`, reflection or autoloading of user code in `src/`. 4. **Zero false positives.** When unsure whether something is a dependency, don't report it and document the limitation. 5. **Do not edit `tests/Fixtures` line layout** without updating the tests that assert line numbers. 6. **Stay in your lane.** Agents only touch the files their task names. Integration across tasks is done by the maintainer. 7. **Quality gate:** `composer check` (Pint, PHPStan, Pest) must pass before you open a pull request. ## Conventions - PHP 8.3, `declare(strict_types=1)`, `final` classes, `readonly` value objects. - The analysis core (`src/Analysis`, `src/Module`, `src/Rules`, `src/Resolvers`, `src/Reporters`, `src/Baseline`, `src/Support`, `src/Documentation`) must stay framework-agnostic. Only the integration layers (`src/Laravel`, `src/Testing`, `src/PHPStan`) may use Laravel. - User-facing messages: one sentence stating the problem plus one stating the fix.

Instructions for AI coding agents

This file is for AI agents (and agent swarms) working on the Cordon Modulith codebase.

Project in one paragraph

Cordon Modulith is a Laravel dev-dependency that verifies boundaries between modules. It statically parses PHP files (nikic/php-parser, never loading code), maps class references to modules, and runs rules (internal_access, undeclared_dependency, cycles). Entry points: php artisan cordon:verify (and cordon:docs), the Pest expectation toRespectBoundaries() and the PHPStan rule. Pipeline: ModuleResolver → FileCollector → DependencyExtractor → Analyzer (cross-module edges) → Rules → Baseline → Reporter.

Hard rules

Contracts are frozen. Do not change interfaces in src/Contracts, value objects in src/Analysis and src/Module, the config shape, the baseline JSON format or command options without an accepted ADR in docs/adr. If you believe a change is needed, stop and write the ADR proposal instead.
Tests first. Write or update the acceptance test before the implementation. Every detection change needs a fixture in tests/Fixtures.
Never load analysed code. No class_exists, require, reflection or autoloading of user code in src/.
Zero false positives. When unsure whether something is a dependency, don't report it and document the limitation.
Do not edit tests/Fixtures line layout without updating the tests that assert line numbers.
Stay in your lane. Agents only touch the files their task names. Integration across tasks is done by the maintainer.
Quality gate: composer check (Pint, PHPStan, Pest) must pass before you open a pull request.

Conventions

PHP 8.3, declare(strict_types=1), final classes, readonly value objects.
The analysis core (src/Analysis, src/Module, src/Rules, src/Resolvers, src/Reporters, src/Baseline, src/Support, src/Documentation) must stay framework-agnostic. Only the integration layers (src/Laravel, src/Testing, src/PHPStan) may use Laravel.
User-facing messages: one sentence stating the problem plus one stating the fix.