Indeks yang diperintah sinkron: lint DONE-INDEX

Papan status internal menampilkan kartu Done untuk pembaruan satu modul. Saat isi indeks commit dibuka, hash yang tertera di kartu itu tidak ada di daftar. Yang membuatnya licik: tidak ada satu pun lapisan yang protes. Papan merasa sudah bekerja sesuai alurnya, indeks merasa isinya benar, dan pengguna yang mencari "sudah dikerjakan apa, commit berapa" mendapat dua jawaban yang tidak saling menopang.

Gunanya indeks commit memang untuk pertanyaan itu: pintu pertama saat menelusuri pekerjaan lewat ID atau hash. Asal muasalnya sederhana, baris-baris di dalamnya disalin tangan dari riwayat git. Dugaan pertama mengikuti logika itu: lalai disiplin. Seseorang lupa memperbarui indeks setelah menutup kartu, atau salah salin hash. Resep umum untuk dugaan semacam itu juga sudah matang, tambah checklist dan tegur proses.

Teori itu tidak bertahan lama. Penelusuran ke belakang menunjukkan polanya berulang: indeks adalah snapshot, dibuat sekali pada satu momen, lalu dunia berjalan. Kartu Done baru tidak pernah dikawinkan kembali ke snapshot itu. Akar masalahnya bukan kelalaian, melainkan arsitektur data: dokumen status yang di-maintain tangan akan melenceng dari keadaan sebenarnya, hanya soal waktu. Pertanyaan "apakah dokumen ini masih segar" yang oleh buku Software Engineering at Google dicatat sebagai keluhan klasik para insinyur, adalah gejala dari arsitektur yang salah, bukan dari orang yang lalai. Tim Google menyimpulkan sendiri bahwa upaya mereka paling berhasil justru ketika dokumentasi diperlakukan layaknya kode dan diikat ke alur kerja rekayasa biasa [3].

Menghapus tangan dari persamaan

Perbaikan pertama bukan memperketat disiplin, melainkan menghapus salinan tangan. Indeks kini diregenerasi mekanis dari git log, perintah yang tugasnya memang menampilkan commit log, lengkap dengan jejak parent yang bisa dijangkau dari sebuah commit [1]. Tidak ada lagi transkripsi manual yang bisa melenceng: isi indeks adalah turunan data, bukan klaim.

Detail kecil di skrip regenerasi ini justru pelajaran paling berguna. Header berkas dipertahankan verbatim, hanya placeholder jumlah commit dan tanggal yang diganti. Versi pertama skrip diam saja bila header tidak cocok dengan dugaan, tanpa pesan, tanpa perubahan. Versi perbaikannya berlaku sebaliknya: gagal keras dengan pesan eksplisit bila placeholder tidak terganti. Alasannya, alat yang diam saat gagal itu jebakan; kegagalan senyap dikira keberhasilan.

Lapisan kedua adalah lint di sisi papan status. Setiap kartu Done yang membawa hash wajib punya hash itu di indeks; kartu Done tanpa diff kode wajib menulis literal "(tak ada diff)". Dengan itu, kondisi "selesai tapi jejaknya hilang" berhenti jadi kejadian yang menunggu ditemukan seseorang, dan mulai jadi galat yang ditolak mesin. Polanya sama dengan saran dari dokumentasi pre-commit: masalah sederhana ditangkap otomatis sebelum masuk review, supaya pemeriksa manusia menyisihkan waktunya untuk arsitektur, bukan untuk nitpick administratif [2].

Celah format yang lolos dari invariant pertama

Lint versi pertama hanya memindai hash yang dibungkus backtick. Review menemukan celahnya dalam hitungan jam: tiga belas baris legacy memakai hash telanjang tanpa backtick, dan semuanya lolos dari keanggotaan. Perbaikannya bukan memaksa semua baris memakai backtick, melainkan mengganti pola pencocokan ke plain-hex sehingga kedua format terbaca sama. Invariant pertama hampir selalu punya celah format; review adversarial yang menemukannya, bukan niat baik.

Sisi pengujian juga diikat. Selftest lint menerima path yang bisa disuntikkan, sehingga kasus DONE-FOOTPRINT dan DONE-INDEX bisa diuji pada data temp tanpa menyentuh berkas asli. Penutup trio ini satu baris keputusan: mandat pemilik proyek berbunyi indeks commit tidak boleh pincang, lalu diturunkan jadi invariant mekanis, bukan jadi sumpah di dokumen proses.

Keadaan akhirnya mengubah makna kata Done. Status itu bukan lagi klaim yang perlu dipercaya, melainkan keadaan yang bisa diverifikasi: hash di kartu ada di indeks, dan indeks isinya cocok dengan git log. Dokumen "sudah dikerjakan apa" berhenti menjadi dokumen yang perlu ditanya segarnya atau tidak.

Sumber

1. git-log documentation, git-scm.com (diakses 2026-10-12): "Show commit logs"; "List commits that are reachable by following the parent links from the given commit(s)".
2. pre-commit.com documentation (diakses 2026-10-12): "Git hook scripts are useful for identifying simple issues before submission to code review"; reviewer fokus ke arsitektur, bukan nitpick trivial.
3. Software Engineering at Google, ch. 10 Documentation, abseil.io (diakses 2026-10-12): "our most successful efforts have been when documentation is treated like code and incorporated into the traditional engineering workflow"; "Is this document up to date?".