# AGENTS.md Instruksi ini berlaku untuk seluruh repository Real-Time Monitoring Dashboard "Banten Merebut Garuda" kecuali terdapat `AGENTS.md` yang lebih dekat pada subdirectory tertentu. Dokumen sumber yang wajib dibaca sebelum mengubah domain behavior: 1. [`prd.md`](./prd.md) 2. [`srs.md`](./srs.md) Jika source code, issue, atau prompt bertentangan dengan invariant di bawah, jangan menebak. Hentikan perubahan yang irreversible, jelaskan konflik, dan minta keputusan product owner. --- ## 1. Product context Produk adalah web application untuk mengoperasikan program mentorship beasiswa global selama enam bulan dengan baseline resmi 110 siswa Banten. Jumlah aktual tetap configurable per cohort. Sistem harus: - mengumpulkan progress/evidence; - mengelola roadmap, session, milestone, document, dan application; - menghitung SRS; - mendeteksi risk; - mengelola intervention dan escalation; - melacak funnel sampai scholarship award dan study abroad; - mendukung pre-departure dan alumni pada release berikutnya. Target utama program: 55 siswa memperoleh beasiswa dan mulai studi luar negeri pada 2027. --- ## 2. Fixed technology decisions - Backend: Laravel. - Reactive UI: Livewire. - Local UI behavior: Alpine.js. - Styling: Tailwind CSS. - Database: relational database. - Background work: Laravel Queue dan Scheduler. - File: private storage dengan authorized expiring access. - Real-time Release 1: immediate after-save state dan Livewire polling 30-60 detik. - WebSocket/Reverb bersifat optional dan tidak boleh ditambahkan tanpa kebutuhan operasional yang jelas. - React tidak dibutuhkan untuk scope saat ini. Gunakan versi dependency yang sudah dikunci repository. Jangan melakukan upgrade framework/package besar sebagai bagian task fitur biasa. --- ## 3. Role dan authorization invariants Tepat empat login-level role: - `student` - `mentor` - `admin` - `spectator` Mentor assignment type: - `co_mentor` - `facilitator` Admin permission set: - `super_admin` - `coordinator` - `program_director` - `steering_viewer` Spectator type: - `dinas` - `sekolah` - `orang_tua` Rules: - Authorization wajib ditegakkan dengan Laravel Policies/Gates. - Menu visibility bukan authorization. - Mentor hanya dapat mengakses active assignment. - Student hanya dapat mengakses data miliknya. - Spectator selalu read-only dan dibatasi server: `dinas` ke seluruh siswa aktif, `sekolah` ke siswa aktif di sekolah terkait, dan `orang_tua` ke satu siswa terkait. - Spectator hanya dapat mengakses dokumen privat milik siswa dalam scope melalui policy dan authorized expiring access. - `steering_viewer` read-only. - Private document access harus need-to-know dan logged. - Admin override wajib mempunyai reason dan audit event. Setiap feature baru wajib mempunyai allow dan deny tests. --- ## 4. Domain invariants ### 4.1 Jangan hardcode struktur program PDF mempunyai konflik jumlah siswa per kelompok dan jumlah mentor. Jangan hardcode: - baseline resmi 110 siswa sebagai topologi hardcoded; - 10 kelompok; - 5/10 siswa per kelompok; - 20/22 mentor; - jumlah pod; - assignment overlap. Semua harus configurable per cohort. ### 4.2 Pisahkan empat axis Jangan satukan atau saling menggantikan: 1. SRS. 2. Health Status. 3. Application Stage. 4. Final Sprint Support Band. Masing-masing harus mempunyai source, rule, history, dan UI label sendiri. ### 4.3 Application bersifat one-to-many - Student memiliki banyak application. - Status application tidak boleh disimpan pada student profile. - Requirement, deadline, document mapping, submission, interview, dan outcome terhubung ke application. - Funnel siswa menggunakan unique student count. - Total application dilaporkan sebagai metric terpisah. ### 4.4 Versioning dan immutability - ISR menyimpan version history. - Submission revision tidak menimpa version lama. - Document replacement membuat version baru. - Published SRS immutable. - SRS correction membuat superseding version. - Configuration/rubric changes versioned dan berlaku prospektif secara default. ### 4.5 Official outcome Submitted, LoA, Scholarship Award, dan Study Abroad official state memerlukan: - evidence; - date; - source; - authorized verifier; - audit trail. Student claim yang belum diverifikasi tidak boleh masuk official funnel. --- ## 5. Suggested application boundaries Pertahankan domain logic di luar Livewire component. Suggested boundaries: ```text app/ Domain/ Identity/ Program/ Students/ Roadmaps/ Sessions/ Milestones/ Applications/ Readiness/ EarlyWarning/ Interventions/ Outcomes/ Reporting/ Actions/ Events/ Jobs/ Livewire/ Student/ Mentor/ Admin/ Policies/ Support/ ``` Ini adalah arah, bukan kewajiban reorganisasi massal. Ikuti struktur repository yang sudah ada dan lakukan perubahan sekecil yang diperlukan. Livewire component bertanggung jawab untuk: - input/output UI; - authorization call; - validation orchestration; - memanggil action/service; - loading/error/empty state. Livewire component tidak boleh menjadi tempat utama untuk: - SRS formula; - health/alert rule; - funnel calculation; - permission logic; - multi-record transaction; - file authorization; - report aggregation kompleks. --- ## 6. Coding conventions ### 6.1 PHP/Laravel - Gunakan strict, typed code sesuai style repository. - Gunakan Form Request atau Livewire validation rules yang reusable. - Gunakan Enum/value object untuk finite state bila sesuai pola repository. - Gunakan database transaction untuk perubahan multi-record. - Gunakan eager loading untuk mencegah N+1. - Hindari query langsung dari Blade view. - Gunakan domain action/service untuk calculation dan state transition. - Gunakan event setelah transaction commit untuk side effect yang membutuhkan committed data. - Jangan menyimpan business-critical configuration hanya di frontend. ### 6.2 Naming - Database/table/column: English `snake_case`. - PHP class: English `PascalCase`. - Method/property: English `camelCase`. - User-facing copy: Bahasa Indonesia, kecuali istilah resmi program. - Status key bersifat stable English key; label dapat diterjemahkan. ### 6.3 State transition State transition harus eksplisit dan tervalidasi. Contoh: ```text application: not_ready -> in_progress -> ready -> submitted -> downstream outcome alert: open -> acknowledged -> in_progress -> waiting -> resolved -> reopened assessment: draft -> ready_for_review -> published -> superseded submission: draft -> submitted -> pending_review -> needs_revision/approved/validated ``` Jangan mengizinkan arbitrary status update melalui mass assignment. --- ## 7. Database dan migration rules - Gunakan foreign key dan index untuk relationship/filter utama. - Tambahkan unique constraint yang melindungi business invariant. - Gunakan decimal untuk SRS/weighted score, bukan float. - Simpan UTC pada database; tampilkan Asia/Jakarta dan pertahankan source timezone deadline. - Gunakan soft delete hanya bila sesuai retention policy; jangan menggunakannya sebagai pengganti audit/versioning. - Migration harus forward-safe dan mempunyai rollback yang wajar. - Data backfill besar dijalankan dalam chunk/job, bukan migration request yang berisiko timeout. - Jangan menghapus atau rename production column tanpa migration plan dan compatibility window. Suggested constraints: - satu current ISR per student/cohort; - satu current published SRS per student/cohort/checkpoint; - component score 0-100; - active rubric total weight 100; - unique open alert key per student/rule/source bila berlaku; - mentor assignment mempunyai valid date range; - application outcome mempunyai verifier ketika official. --- ## 8. SRS implementation rules `srs.md` adalah sumber utama scoring behavior. Hard requirements: - delapan komponen dan bobot mengikuti `srs.md`; - gunakan decimal precision; - category memakai raw final score; - missing tidak sama dengan 0; - draft incomplete tidak dapat dipublish; - published assessment immutable; - rubric version tersimpan pada assessment; - evidence dan assessor note wajib; - calculation harus deterministic dan unit-tested. Jangan duplikasi formula di banyak Livewire component. Sediakan satu calculation service/action yang pure dan dapat diuji. --- ## 9. Early warning dan scheduler rules Rule awal mencakup: - dua consecutive unexcused absence; - missed weekly check-in; - overdue milestone; - threatened application deadline; - no response terhadap mentor; - manual staff alert. Requirements: - threshold configurable; - scheduled evaluation idempotent; - relevant write boleh memicu immediate evaluation; - duplicate active alert harus dicegah; - rule result harus menjelaskan alasan dan source record; - manual override mempunyai reason dan expiry; - alert resolution tidak menghapus source evidence; - SLA/escalation event tercatat. Gunakan lock atau unique constraint untuk mencegah duplicate saat scheduler overlap. --- ## 10. Queue dan side effects Gunakan queue untuk: - email/notification delivery; - export generation; - file processing/scanning; - bulk import; - deadline reminder; - alert escalation; - reconciliation berat. Job requirements: - idempotent; - safe retry; - mempunyai timeout/retry policy; - tidak mengirim duplicate notification setelah retry; - menyimpan failure context yang tidak membocorkan data sensitif; - dapat dimonitor operator. Jangan menjalankan export atau file processing berat dalam Livewire request. --- ## 11. File dan privacy rules - Semua student evidence private by default. - Jangan membuat permanent public URL. - Gunakan temporary authorized URL/stream. - Validasi extension, MIME, dan size. Pemeriksaan yang tersedia adalah verifikasi integritas deterministik atas keberadaan serta ukuran file, bukan malware atau antivirus scanning. - Nama file/path tidak boleh membocorkan data sensitif lebih dari yang diperlukan. - Enforce document access dengan policy sebelum URL dibuat. - Log sensitive view/download bila diwajibkan `prd.md`. - Broad export tidak boleh membawa private document link. - Jangan menulis document contents atau PII ke application log. - Consent, guardian, school contact, retention, dan deletion mengikuti configuration/policy yang disetujui. --- ## 12. UI dan accessibility rules - Student dan Mentor flow mobile-first mulai 360 px. - Admin dashboard desktop-first tetapi tetap usable pada tablet. - Color bukan satu-satunya pembeda status. - Sediakan text label/icon untuk On Track, Need Attention, At Risk, Green, Yellow, dan Red. - Semua form mempunyai label, error summary, focus state, dan keyboard support. - Berikan loading, empty, error, offline/retry, dan success feedback. - Jangan membuat tabel baseline 110 siswa menjadi satu DOM payload yang tidak terkontrol; gunakan pagination/virtualization/efficient query sesuai kebutuhan. - Filter harus mempertahankan context saat drill-down/back. - Tampilkan last-updated timestamp pada data operasional. --- ## 13. Performance rules - Hindari N+1 melalui query tests atau inspection. - Dashboard aggregation tidak boleh menghitung seluruh history di request tanpa index/cache/materialization yang sesuai. - Cache hanya boleh menyimpan data yang aman terhadap permission scope. - Invalidate cache setelah relevant write atau gunakan short TTL yang terdokumentasi. - Jangan cache private document authorization decision lintas user. - Target: ordinary action p95 <=2.5 detik dan dashboard p95 <=4 detik untuk baseline cohort 110 siswa. - Benchmark p95 produksi belum dijalankan atau dibuktikan. Jangan menyatakan target performance telah tercapai tanpa evidence produksi. - Encrypted daily backup dengan target RPO 24 jam dan RTO 8 jam tetap menjadi target. Implementasi dan drill backup/restore produksi ditunda serta belum dibuktikan. --- ## 14. Testing requirements Gunakan test runner yang sudah dikonfigurasi repository. Command baseline: ```bash php artisan test npm run build ``` Tambahkan formatter/static analysis command yang memang tersedia di repository. Jangan mengarang dependency baru hanya untuk memenuhi satu task. ### 14.1 Test layers - Unit test untuk SRS formula, category, health rule, support band, dan funnel. - Feature test untuk policy, state transition, Livewire action, upload, dan export authorization. - Queue test untuk idempotency dan retry. - Scheduler test untuk duplicate prevention. - Database test untuk constraint dan transaction behavior. - Browser/UI test untuk critical student/mentor/admin journeys jika infrastructure tersedia. ### 14.2 Mandatory scenarios - Student cannot view another student. - Mentor cannot access unassigned student. - Steering viewer cannot mutate data. - Spectator Dinas, Sekolah, dan Orang Tua cannot mutate data or read students/private documents outside their server scope. - Published SRS cannot be edited. - Multiple applications stay independent. - Funnel does not double count a student. - Consecutive absence creates one alert. - Retried notification job does not duplicate delivery. - Unauthorized private file access fails. - Broad export omits sensitive links. - SRS category boundaries follow `srs.md`. - Excused absence does not lower Engagement denominator. ### 14.3 Panduan & Optimasi Pengujian (Testing Guidelines) 1. **Gunakan Filter untuk Pengujian Cepat & Terfokus**: Jangan selalu menjalankan seluruh suite 450+ test saat mengerjakan satu modul. Jalankan targeted tests: ```bash php artisan test tests/Feature/AdminInfrastructurePagesTest.php php artisan test --filter=test_method_name php artisan test --filter=ClassNameTest ``` 2. **Profiling Test Terlambat**: Gunakan flag `--profile` untuk mengidentifikasi bottleneck eksekusi test: ```bash php artisan test --profile ``` 3. **Konfigurasi Environment Testing Terisolasi (`phpunit.xml`)**: - Database: SQLite `:memory:` (menghindari I/O disk lambat). - `BCRYPT_ROUNDS = 4` (mempercepat pembuatan password user test). - Driver array/sync: `CACHE_STORE=array`, `SESSION_DRIVER=array`, `QUEUE_CONNECTION=sync`, `MAIL_MAILER=array`. - Matikan extension berat (Xdebug dimatikan saat test biasa). 4. **Wajib Membaca Seeder Sebelum Tes Login / E2E**: Selalu baca `database/seeders/DemoCohortSeeder.php` untuk memastikan email dan password akun demo (`password123`). Dilarang menebak kredensial. --- ## 15. Working commands Gunakan command yang tersedia di repository. Untuk Laravel/TALL scaffold standar: ```bash composer install npm install php artisan migrate php artisan test php artisan test --filter=TargetTest npm run build php artisan queue:work php artisan schedule:work ``` Sebelum menjalankan migration atau destructive command: - pastikan environment bukan production kecuali task secara eksplisit memintanya; - periksa target database; - jangan menghapus user data untuk memperbaiki test; - gunakan factory/seed khusus test. --- ## 16. Agent workflow Untuk setiap task: 1. Baca `prd.md`, `srs.md`, dan `AGENTS.md` yang berlaku. 2. Inspect repository dan perubahan user yang sudah ada. 3. **Sebelum melakukan tes login atau pengujian browser/E2E**: Wajib membaca file seeder (`database/seeders/DemoCohortSeeder.php`, `DatabaseSeeder.php`, dll.) untuk mengetahui persis kredensial demo (`admin@banten-supercamp.id`, `mentor@banten-supercamp.id`, `student@banten-supercamp.id`, `spectator@banten-supercamp.id`, password `password123`) dan topologi data yang aktif. Jangan menebak email/password. 4. Identifikasi domain invariant, policy, migration, side effect, dan test yang terpengaruh. 5. Implement perubahan terkecil yang menyelesaikan requirement. 6. Tambahkan/ubah test sebelum menyatakan selesai. 7. Jalankan targeted tests, lalu broader relevant suite. 8. Jalankan formatter/static analysis/build yang tersedia. 9. Periksa authorization, privacy, audit, responsive state, dan accessibility. 10. Laporkan file berubah, keputusan penting, test result, dan blocker/open decision. Jangan melakukan refactor luas, dependency upgrade, schema redesign, atau scope expansion tanpa kebutuhan langsung. --- ## 17. Prohibited shortcuts Jangan: - menebak kredensial login atau email saat pengujian browser tanpa membaca seeder terlebih dahulu; - hardcode jumlah siswa/kelompok/mentor; - mengandalkan UI untuk authorization; - menyimpan application status pada student profile; - menyatukan SRS, Health, Application Stage, dan Support Band; - mengubah published SRS in-place; - overwrite submission/document history; - membuat permanent public file URL; - menghitung funnel dari total application ketika metric meminta unique student; - membuat duplicate alert/notification akibat retry; - menaruh domain formula di Blade/Alpine; - log PII atau private document content; - mengklaim SRS "scientifically validated"; - menganggap data missing sebagai score 0; - menandai outcome official tanpa evidence dan verifier. --- ## 18. Definition of Done for agents Task belum selesai jika salah satu hal berikut belum dipenuhi: - requirement dan acceptance criteria terpetakan; - policy allow/deny test lulus; - business rule test lulus; - migration/constraint aman; - audit event ditambahkan bila material mutation; - queue/scheduler idempotent bila relevan; - responsive/loading/empty/error/accessibility state tersedia; - data sensitif tetap private; - documentation diperbarui; - test/build command relevan lulus; - open decision tidak disembunyikan sebagai asumsi hardcoded.