# Repository change rules

- Every schema change requires a NEW timestamped Phinx migration. Never rely on editing an applied migration or on manual SQL on the local database.
- Applied migrations are immutable. Do not roll back/rebuild a populated environment to deliver an upgrade. Use additive changes/backfills; assess data compatibility explicitly.
- A historical migration may only receive a narrowly scoped fresh-install execution repair if the chain cannot reach a later migration. Document it and provide a new forward migration for any installed-database effect.
- Shared reference data belongs in an idempotent Phinx seeder (DeploymentReferenceSeeder for routine deployments). Insert missing keys only; preserve customized/archived definitions, role assignments, module assignments, and user records.
- Never run all seeders as part of deployment. UserSeeder and account/bootstrap/demo scripts are not deployment seeders.
- scripts/ is private and ignored. Never track scripts from that folder, especially personal account provisioning scripts. Never embed account details, credentials, or local database content in migrations/seeders/tests.
- Write text files explicitly as UTF-8. PHP class references must use top-level use imports.
- Test migrations on an isolated database, both fresh and upgrade paths; rerun migrations and deployment seeds to verify no-op/idempotent behavior and data preservation.
- Update db/migrations/manifest.json for NEW migrations only; do not change recorded hashes of applied migrations to conceal edits.
