# MASTER_RULES.md — Habib Cables ERP

Hard, actionable rules. These apply to **every** component. Violations should block a PR.

## Code operation rules
1. **Read before write.** Open and understand a file before editing it.
2. **Beware legacy duplicates.** This repo contains `*Controller copy.php`, `* copy 2.php`,
   `*_backup.php`, and an `app/Http/Controllers/Api/Backup/` folder. These are **NOT live**.
   Confirm the real file via `routes/web.php` / `routes/api.php` before editing.
3. **Never create new `copy`/`backup` files.** Use git branches and history instead.
4. **Never edit `vendor/`.** Change composer deps or publish/override properly.
5. Use absolute paths in tooling; match surrounding code style (Pint/PSR-12).

## Git workflow rules
6. Branch from `main` (e.g. `fix/…`, `feature/…`); open a PR into `main`.
7. One logical change per PR. Cleanup of legacy files goes in its own commit/PR.
8. Do not commit or push unless explicitly asked. Never `--no-verify`.

## Security rules
9. **Every route is gated.** Web routes use `check.active.user` + `check.role`;
   API uses `auth:sanctum`; desktop uses its token flow. No open mutation endpoints.
10. Authorize with **Spatie Permission** (`hasAnyRole`, `can`) — see `App\Http\Middleware\CheckRole`
    and `App\Helpers\RoleHelper`. Do not hand-roll role checks.
11. CSRF applies to all web routes; the **only** documented exemption is `api/desktop/*`
    (see `bootstrap/app.php`). Do not add exemptions without documenting why.
12. Validate & sanitize all input via FormRequests (`app/Http/Requests/*`). No raw `$request->all()`
    into `create()`/`update()` without a validated array.
13. Secrets live in `.env`. Never hardcode credentials, tokens, or license keys.

## Data & migration rules
14. **One concern per migration**, always with a working `down()`. Enum/status changes get their own
    migration (this repo has many `update_*_status_enum` migrations — follow that precedent).
15. Wrap multi-table writes in `DB::transaction()`.
16. Never mutate a computed balance directly — post a correcting stock/ledger entry.

## Testing rules
17. New behaviour ships with a Pest feature test. Run `php artisan test` before opening a PR.
18. Keep the `Test*` artisan integration commands passing.

## Documentation rules
19. New module or endpoint → update the owning component `CLAUDE.md` and, if it crosses a boundary,
    `docs/MASTER_INTEGRATION.md`.
20. Every mutation is audited via `spatie/laravel-activitylog` — do not remove logging.

## Review / Definition of Done
- [ ] Pint clean, Pest green.
- [ ] Route gated; FormRequest validation present; activitylog intact.
- [ ] Migration reversible; multi-table writes transactional.
- [ ] No new `copy`/`backup` files; touched legacy files verified as live.
- [ ] Docs updated if a contract or module changed.