asepharyana
80daa9f045
getPendingMessagesByConversation() flips every fetched pending row to 'processing', then pickBatchWithinBudget() may stop early on the token budget. The tail rows that did NOT make the batch were never un-claimed, so they stayed 'processing' forever — the recovery worker reverted them (120s) only for the next wave to re-claim them, an infinite loop of stuck messages that never get analyzed (saw 22 rows, some recycled for 40+ minutes). - add computeBudgetOverflowMessages() pure helper (batchBudget.ts) - batchScheduler un-claims overflow rows back to 'pending' before dispatching the trimmed batch - recovery-worker now reverts stuck processing unconditionally (the old 'conversationProcessing.size > 0' guard skipped the revert when the in-memory lock map was empty, e.g. fresh boot — exactly when stranded rows from a previous process need rescuing) - 3 regression tests for the overflow helper
docs/ — Spec-Driven Development Hub
Direktori ini adalah pusat dari workflow spec-driven development di GMW.
Semua perubahan signifikan dimulai dari satu spec, sebelum kode ditulis,
dan setiap tugas yang berjalan dilacak lewat todo.md.
Struktur
docs/
├── README.md # Dokumen ini
├── spec-template.md # Template standar untuk semua spec
├── todo-template.md # Template todo list
└── specs/ # Semua spec dan implementation plan
├── YYYY-MM-DD_<slug>-spec.md # Spec (apa & mengapa)
└── YYYY-MM-DD_<slug>.md # Plan/fix (bisa langsung spec+plan)
Naming convention
YYYY-MM-DD_<slug>-spec.md # Spec baru untuk fitur/fix
YYYY-MM-DD_<slug>.md # Plan yang sudah include spec di dalamnya
Contoh:
2026-08-30_recordings-v2-features-spec.md— spec untuk Recordings v22026-08-24-attachment-delay-fix.md— spec + plan untuk attachment delay fix
Service-specific docs
services/<service>/docs/specs/ # Spec yang spesifik untuk 1 service
Workflow: Spec-Driven Development
Prinsip utama
No code without a spec. Semua perubahan signifikan harus punya spec terlebih dahulu. Spec adalah kontrak: apa yang akan dibangun, mengapa, dan bagaimana memverifikasinya.
Todo list (todo.md) — WAJIB
Setiap tugas berjalan (implementasi fitur/fix) harus punya todo.md:
# Todo — <judul tugas>
## Task
- [ ] Tulis spec
- [ ] Verifikasi facts (baca kode: file:line)
- [ ] Implementasi tahap 1: ...
- [ ] Implementasi tahap 2: ...
- [ ] Verifikasi: pnpm typecheck / lint / build / test
- [ ] Commit + push
Aturan todo.md:
- Task konkret & verifiable — "ubah X di file Y", bukan "fix bug".
- Satu task
[in_progress]pada satu waktu; ceklis[x]segera setelah selesai. - Gunakan
docs/todo-template.mdsebagai template. - Simpan
todo.mddidocs/(tugas lintas-service) atau diservices/<service>/docs/(tugas satu service).
Kapan perlu spec + todo
| Perlu spec + todo | Tidak perlu |
|---|---|
| Fitur baru | Typo fix |
| Bug fix non-trivial | Dependency bump (dependabot) |
| Refactor yang mengubah behavior | Format/lint auto-fix |
| Perubahan DB schema | Test-only change |
| Perubahan API contract | README/doc update |
| Perubahan arsitektur | Variable rename |
Workflow step-by-step
-
Tulis spec — Salin
docs/spec-template.md, isi semua section yang relevan.- Verified facts: baca kode yang terpengaruh, catat temuan dengan file:line.
- Root cause: analisis sebab (jangan hanya describe symptom).
- Decisions: pilih pendekatan, jelaskan alternatif yang ditolak.
- Verification: command executable, bukan "should work".
- Simpan sebagai
docs/specs/YYYY-MM-DD_<slug>-spec.md.
-
Tulis
todo.md— Pecah spec jadi task konkret yang bisa diceklis (gunakandocs/todo-template.md), dengan urutan implementasi yang logis. -
Review spec — Baca ulang spec sendiri. Cek:
- Apakah verified facts benar-benar verified (bukan asumsi)?
- Apakah file changes lengkap (tidak ada yang terlewat)?
- Apakah verification steps executable?
- Jika spec untuk user request: pastikan user setuju dengan approach.
-
Implement — Ikuti spec + todo step-by-step. Ceklis
[x]setiap task yang selesai. Jika menemukan sesuatu yang berubah dari asumsi spec, update spec dulu, baru implement. -
Verify — Jalankan semua verification steps di spec. Catat hasilnya.
-
Commit — Reference spec di commit message:
feat(module): deskripsi singkat Ref: docs/specs/YYYY-MM-DD_<slug>-spec.md
Tips menulis spec yang baik
- Evidence-based: setiap klaim harus ada sumbernya (file:line, log, error).
- Actionable: orang lain (atau AI agent) harus bisa implementasi dari spec saja.
- Verifiable: setiap requirement harus bisa di-test secara eksplisit.
- Scoped: satu spec = satu perubahan terfokus. Jangan campur 3 fitur dalam 1 spec.
- Bahasa campuran: narrative boleh Indonesia/English, istilah teknis pakai English.
Role of AI agents
AI coding agents (Shiro Neko / Hermes) harus:
- Membaca spec sebelum menulis kode
- Membuat & meng-update
todo.mduntuk setiap tugas berjalan - Verifikasi fakta dari kode aktual (bukan dari asumsi training data)
- Update spec jika temuan baru mengubah approach
- Jalankan verification steps setelah implementasi
- Reference spec di commit message
AI agents tidak boleh:
- Langsung implement tanpa membaca/menulis spec
- Mengabaikan verified facts yang bertentangan dengan asumsi
- Skip verification steps
- Mengerjakan tugas tanpa todo list yang jelas