Save this content to: .cursor/rules/schema-contract.mdc

# Laravel Schema Contract — Cursor Project Rules

This repository is the `simba-jirira-source/laravel-schema-contract` Laravel package.

## Authoritative project documents

Before implementing package work, read and follow:

- `@docs/MASTER_SPEC.md`
- `@docs/IMPLEMENTATION_PLAN.md`
- `@docs/IMPLEMENTATION_STATUS.md` when it exists

The master specification defines product scope.
The implementation plan defines phase boundaries.
The current user request defines which phase may be executed.

## Phase discipline

- Implement only the phase explicitly requested by the maintainer.
- Never begin the next phase automatically.
- Inspect the current repository before editing.
- Inspect relevant existing tests before changing behavior.
- Preserve functionality completed in previous phases.
- If the repository differs from the implementation plan, adapt to the actual repository while preserving the intended architecture.
- Record material deviations in `docs/IMPLEMENTATION_STATUS.md`.

## Initial product scope

The `v0.1.0` scope is only:

`Database Schema ↔ Eloquent Model`

Do not prematurely implement:

- FormRequest validation analysis
- API Resource analysis
- Livewire analysis
- baseline generation
- JSON/GitHub annotation output
- automatic fixes

unless a later explicitly requested phase requires them.

## Technology requirements

Target:

- Laravel 13+
- PHP 8.3+
- Composer 2+
- Pest
- Laravel Pint
- Laravel package Testbench appropriate to the installed Laravel version
- PHPStan/Larastan when introduced by the implementation plan

Do not introduce React, Vue, Inertia, Bootstrap, Node UI tooling, or unrelated frontend dependencies.

## Package identity

Prefer:

- Composer package: `simba-jirira-source/laravel-schema-contract`
- Namespace: `SimbaJirira\SchemaContract`
- Service provider: `SchemaContractServiceProvider`
- Primary command: `schema-contract:check`

Do not rename package identity without explicit maintainer instruction.

## Architecture

Keep responsibilities separated.

Prefer dedicated concepts for:

- discovery
- model inspection
- schema inspection
- type normalization
- compatibility
- rules
- analysis
- results
- console rendering

Core analysis must not depend on Artisan output.

Rules must return structured results/violations rather than print directly.

Avoid putting core logic into:

- service providers
- console commands
- config files
- giant utility classes

Do not add interfaces, facades, managers, repositories, events, factories, or extension APIs unless they have a concrete current-phase purpose.

## Types and DTOs

Prefer:

- enums
- readonly/immutable DTOs where practical
- typed properties
- typed return values
- explicit nullability

Avoid unstructured arrays and widespread `mixed` for core analysis state.

Keep raw database-driver strings inside normalization/inspection boundaries.

Keep raw reflection details inside model-inspection boundaries.

## Database behavior

The package is read-only analysis tooling.

Never:

- alter schema
- write application records as part of analysis
- modify model source automatically
- execute destructive migration operations

Support driver differences explicitly.

Unknown metadata should degrade gracefully instead of crashing.

Be conservative where metadata is incomplete.

## False positives

False positives are a product defect.

Use `ERROR` only for high-confidence contract incompatibility.

Use `WARNING` when a condition is suspicious but not conclusively wrong.

Use `INFO` sparingly for non-blocking information.

Do not emit noisy warnings for normal Laravel conventions such as ordinary string columns with no cast or standard timestamp behavior.

## Testing

Every meaningful behavior change requires tests in the same phase.

Use Pest.

Prefer:

- focused unit tests for normalizers, compatibility, DTOs, and rules
- feature tests for commands and discovery
- integration tests for schema/model behavior
- architecture tests where they provide real value

Do not:

- delete meaningful tests to make CI pass
- weaken assertions merely to obtain green tests
- skip failing tests without documenting a genuine environment limitation
- replace real behavior tests with mocks when integration behavior is the subject being tested

When a test fails, fix the underlying problem.

## Quality commands

Use the repository's installed scripts first.

Where available, run the equivalent of:

```bash
composer validate
vendor/bin/pest
vendor/bin/pint --test
vendor/bin/phpstan analyse
```

Do not claim a command passed unless it was actually run successfully.

If a command cannot run because of the local environment, report the exact limitation.

## Configuration

Keep `config/schema-contract.php` minimal.

Do not add settings for hypothetical future functionality.

Initial configuration should focus on model paths and necessary ignore controls.

## Documentation

Documentation must describe implemented behavior accurately.

Roadmap functionality must be clearly labelled as planned.

Do not claim support for a database/feature that has not been verified.

Update documentation when behavior or public usage changes.

## Git and releases

Normal branch strategy:

`development → main`

Do not perform release actions unless the maintainer explicitly asks.

Never automatically:

- create Git tags
- push Git tags
- create GitHub Releases
- publish to Packagist
- merge branches
- force-push
- rewrite public history

Cursor may update `CHANGELOG.md` when a requested phase explicitly calls for it.

Use Keep a Changelog conventions and retain an empty `[Unreleased]` section above released versions.

## Dependencies

Keep production dependencies minimal.

Before adding a new production dependency:

1. confirm Laravel/PHP cannot reasonably provide the capability
2. explain the concrete need
3. prefer maintained, narrow dependencies
4. account for supported Laravel/PHP versions

Do not add packages merely to reduce a small amount of straightforward code.

## Security and privacy

Do not dump database records during analysis.

Reports may include structural metadata such as model, table, column, and types.

Avoid exposing sensitive default values or environment secrets.

Never commit credentials or secrets.

## Completion report

At the end of every requested implementation phase, report:

- phase completed
- files added
- files changed
- architecture decisions
- tests added/changed
- commands executed
- test/quality results
- known limitations
- `docs/IMPLEMENTATION_STATUS.md` updates
- next recommended phase

Then stop.

Do not start the next phase without explicit maintainer instruction.