# LINTASAI_WORKFLOWS_v1.md -- Rujukan workflow on-demand (di-load saat relevan)

> Versi 1 - 2026-06-09 - Pendamping CLAUDE_universal_v1.md (tiering v1.5.15+).
> Berisi DETAIL section §4.2, §4.3, §4.4, §4.5, §8.3 yang dipindah dari aturan inti supaya tidak membebani token tiap sesi.
> AI membaca file ini HANYA saat task relevan (trigger ada di stub masing-masing section di CLAUDE.md / AGENTS.md).

---
## 4.1 Contoh Tinjauan Multi-Divisi terisi (rujukan on-demand)

> Dipindah dari `CLAUDE_universal_v1.md` §4.1 (hemat token always-load, v1.10.1). Dibaca AI **hanya kalau ragu** cara mengisi tabel — format wajib + 15 lensa + aturan tetap selalu-aktif di §4.1 inti.

Contoh task sederhana — User minta: "Tambahin validasi email di endpoint register."

```markdown
[...kode + penjelasan...]

---

## 🎯 Tinjauan Multi-Divisi (Menggunakan Analogi Non-Programmer)

| Divisi | Catatan |
|---|---|
| 🔧 **Backend** | ✅ Validasi email via regex RFC 5322 di line 28 — mirip **satpam BCA mobile** cek format kartu ATM sebelum tap, kalau format aneh, langsung tolak (kayak ATM error "kartu tidak terbaca"). |
| 🎨 **Frontend** | 💡 Saran: validasi di FE juga (input type="email" di HTML) supaya UX lebih cepat — mirip **WhatsApp** yang tampilin "nomor tidak valid" sebelum kamu tekan kirim, bukan setelah server return error. |
| 🗄️ **Database** | — Tidak ada perubahan struktur lemari data. |
| ☁️ **DevOps/SRE** | — Tidak ada perubahan kirim ke server. |
| 🔒 **Security/AppSec** | ⚠️ Regex format email OK, tapi tambah batas request per detik (rate-limit) supaya orang nggak bisa **brute-force tebak email valid** (mirip Instagram batas 5 login salah / jam baru lock akun). |
| ✅ **QA/Test** | Tambah cek otomatis 4 skenario: email kosong, format salah, ada spasi, panjang >254 huruf. |
| 👥 **UI/UX + a11y** | — Backend only, tidak ada UI change. |
| 📊 **Product** | 💡 Apakah perlu juga blokir email "buang" (mailinator dll yang gampang dibuat anonim untuk spam)? Tanya owner / stakeholder. |
| 📈 **SEO/Marketing** | — Tidak relevan. |
| 💼 **Business** | — Tidak relevan. |
| 🤖 **ML/AI** | — Tidak relevan. |
| ⚖️ **Legal/Compliance** | ⚠️ Email = data pribadi (PII). Pastikan log sistem tidak simpan email **mentah tanpa enkripsi** — mirip mall tidak simpan video CCTV plate nomor mobil tanpa blur, bisa kena UU PDP. |
| 🤔 **Adversarial Reviewer** | 💡 Aku belum verify regex RFC 5322 actually handle email internasional (mis. `中文@gmail.com` atau `テスト@yahoo.co.jp`). Klaim "RFC 5322 100% OK" perlu test concrete dulu. |
| 🔄 **Reversibility** | 🟢 LOW blast radius. Cuma tambah validasi (reject input invalid), tidak ubah data existing user. Rollback = `git revert` (1 menit) — mirip **Ctrl+Z di Google Docs**, balik ke versi sebelumnya tanpa hilang data. |
| 📚 **Knowledge Transfer** | 💡 Tambah komentar di regex: kenapa pilih RFC 5322 vs HTML5 spec (kasih link spec). Tanpa komentar, staff lain mungkin "perbaiki" jadi regex lebih simple yang sebenarnya lebih lemah. Bus factor file: 🟢 small + isolated, mudah handover. |
```

---
## 4.2. Pattern-Driven Workflow untuk Staff Non-Programmer

Tim ini AI-first dengan staff non-programmer. Mereka **TIDAK akan baca file `PROMPT_LIBRARY.md` 700-baris** dan tidak akan paste template prompt - mereka chat AI dengan bahasa natural: *"tolong tambah fitur X"*, *"ada bug di Y"*, *"deploy ke prod dong"*.

**WAJIB**: AI internalize semua pattern dari `./.claude-kit/templates/PROMPT_LIBRARY.md` (atau `docs/PROMPT_LIBRARY.md` kalau sudah di-copy ke project) saat setup awal sesi, lalu **apply OTOMATIS** saat staff brief task. Staff TIDAK perlu paste template prompt - itu tugas AI untuk apply pattern + tanya klarifikasi yang dibutuhkan pattern.

### Mapping Intent Staff → Pattern PROMPT_LIBRARY

| Intent Staff (bahasa natural) | Pattern Apply |
|---|---|
| "tambah fitur...", "buat halaman...", "implement...", "bikin..." | Prompt 1 (Tambah fitur baru, user story format) |
| "ada bug...", "tidak jalan...", "error...", "kenapa...?", "fix bug..." | Prompt 2 (Fix bug dari user report) |
| "cek SEO", "audit SEO", "Core Web Vitals" | Prompt 3 (SEO check sebelum deploy) |
| "deploy ke vercel", "promote ke prod", "naikin ke prod" | Prompt 4 (Vercel deploy + preview test) |
| "review PR teman", "review PR #...", "approve PR" | Prompt 5 (Review PR) |
| "refactor...", "DRY...", "duplikasi", "pecah file ini" | Prompt 6 (Refactor) → **Tangga Refactor Tingkat 1** (default; lihat "Tangga Refactor 3-Tingkat" di bawah) |
| "refactor bertingkat", "rapikan bertingkat", "rapikan bertahap/pelan-pelan", "rapikan dari yang paling aman dulu", "tawarkan refactor satu-satu" | **Mode Refactor Bertingkat** (tawarkan→kerjakan→naik tingkat; lihat "Mode Refactor Bertingkat" di bawah) |
| "pecah jadi banyak repo", "split repo", "multi-repo", "refactor berat" | **Tangga Refactor Tingkat 3** (Repository Split) — `SPLIT_REPO_MIGRATION_PROMPT_v1.md` |
| "konflik git", "merge conflict", "git error gabung" | Prompt 7 (Resolve merge conflict) |
| "setup MCP server X", "tambah MCP" | Prompt 8 (Setup MCP) |
| "migrate dari Vercel ke Railway", "ganti platform" | Prompt 9 (Platform migration) |
| "tulis ADR untuk decision X", "kenapa kita pilih..." | Prompt 10 (Write ADR) |
| "kerjain task ini: [paste pesan task dari chat]" | Prompt 11/12 (Chat-driven task assignment) |
| "PR siap review", "lapor owner PR udah", "minta review" | Prompt 13 (Lapor owner via chat) |
| "EMERGENCY", "rollback prod", "bug parah di prod", "kembalikan versi lama" | Prompt 14 (Emergency rollback via git revert) |
| "aktifkan feature flag", "siap launch", "ready untuk pakai flag" | Prompt 15 (Activate Feature Flag mode post-launch) |
| "aku mau bagian lain lihat cuma [X,Y]", "buka data [X] buat bagian lain" | Pola Lintas-Layanan §4.2 (loket bahasa sehari-hari — default sembunyikan kolom rahasia) |
| "bikin tabel gabungin [A] + [B]", "satukan data dari beberapa bagian/layanan" | Pola Lintas-Layanan §4.2 (penggabung — tampilkan contoh dulu, gabung di backend via API) |

### Tangga Refactor 3-Tingkat (default mulai paling ringan — naik bertahap)

Saat staff minta "refactor" / "rapikan" / "pecah", AI **WAJIB default ke Tingkat 1** dan **naik bertahap** hanya saat pemicu terpenuhi — pola **Strangler Fig** (*cabut/ekstrak satu bagian sekali jalan, sistem lama tetap hidup sampai bagian baru terbukti — BUKAN bongkar-total sekaligus*). JANGAN loncat langsung ke multi-repo.

| Tingkat | Istilah baku IT (nama utama) | Arti awam (glosari) | Pemicu naik |
|---|---|---|---|
| **1** ⭐ **DEFAULT** | **Refactoring** (*in-place*) | Rapikan kode tanpa pindah struktur: nama, hapus duplikat, pecah fungsi gemuk. **Tetap 1 repo.** 🏢 *Kayak merapikan meja kerja — barang sama, lebih rapi.* | Default tiap "refactor"/"DRY"/"pecah file" |
| **2** | **Modular Monolith** | Susun isi 1 repo jadi modul/paket terpisah-jelas. **Masih 1 repo.** 🏢 *Kayak 1 gudang besar diberi rak-rak berlabel.* | 1 repo mulai sesak; modul saling-silang; tim sulit kerja paralel di 1 folder |
| **3** | **Repository Split / Polyrepo** (*Service Extraction*) | Pisah jadi **beberapa repo** (multi-repo). 🏢 *Kayak pindah ke beberapa gudang terpisah per divisi.* | Modul sudah matang + butuh tim/akses(IP) terpisah + compliance. Lihat `SPLIT_REPO_MIGRATION_PROMPT_v1.md` (Mode Selector per-Lapisan/per-Kapabilitas) |

**Aturan keras:**
- **Default = Tingkat 1.** Kalau staff cuma bilang "refactor"/"rapikan", AI kerjakan Tingkat 1 — JANGAN tawarkan split repo kecuali ada pemicu Tingkat 2/3 yang jelas.
- **Naik 1 tingkat per langkah** (1→2→3), bukan loncat 1→3. Tiap kenaikan = keputusan tersendiri + konfirmasi.
- **Tingkat 3 = keputusan besar** (owner/lead, bukan staff sendiri). Multi-repo **BUKAN** microservice (lihat catatan di SPLIT_REPO prompt).
- AI sebut **tingkat + pemicunya** saat menyarankan naik, mis. *"Ini sudah masuk Tingkat 2 (Modular Monolith) karena modul X & Y saling-silang — mau naik?"*

### Mode "Refactor Bertingkat" (tawarkan → kerjakan → naik tingkat, paling aman dulu)

> v1 · 2026-06-16 (v1.29.0) · Lahir dari owner: ingin rapikan-kode (refactor) disajikan seperti **tangga berjalan** — AI tawarkan perbaikan paling ringan (risiko rusak ~nol) → kerjakan → tawarkan yang sedikit lebih berisiko → kerjakan → ... naik terus sampai yang berat (potensi merusak kode), dengan **kotak pilihan (popup) di tiap kenaikan tingkat**. BUKAN satu rencana borongan sekali-setuju.

**Ini menggabungkan 3 mesin yang SUDAH ada** (bukan kode baru): **Tangga Refactor 3-Tingkat** (sumbu naik) + **§4.7 Alur Berpemandu Bertahap** (loop popup info→pilih→lanjut) + **urutan "paling aman dulu" & Safety Net** (pengaman).

**Pemicu (trigger):**
- Frasa staff: "refactor bertingkat", "rapikan kode bertahap / pelan-pelan", "rapikan dari yang paling aman dulu", "tawarkan refactor satu-satu", "rapikan bertingkat".
- Opsi **[3]** di popup penutup audit (`AUDIT_POST_SETUP_PROMPT_v1.md` Bagian 7) → masuk ke mesin yang SAMA ini.
- Kalau staff cuma bilang "refactor"/"rapikan" TANPA kata "bertingkat" → default tetap Tangga Refactor Tingkat 1 biasa; AI boleh **tawarkan** naik ke mode bertingkat ("mau kurapikan bertahap dari yang paling aman? aku tawarkan tingkat demi tingkat").

**Langkah (semua ke user pakai bahasa non-programmer, §2.1):**

1. **Tentukan cakupan (scope) — READ-MINIMAL.** Dari audit → pakai temuan dimensi "🧹 Perapian kode". Standalone → tanya/tentukan area (berkas/folder/modul). Pakai peta proyek (`docs/architecture.md` + `architecture_auto.md`) + `Grep` untuk temukan peluang — JANGAN baca seluruh repo membabi buta (§7.3 READ-MINIMAL).

2. **Scan peluang (CUMA-BACA) → kelompokkan jadi 3 tingkat risiko:**

| Tingkat | Isi khas | Risiko rusak | Tangga Refactor |
|---|---|---|---|
| 🟢 **Ringan** | rename lokal, hapus impor/variabel tak terpakai, hapus duplikat kecil, ekstrak konstanta (magic number), rapikan format | ~nol (perilaku TAK berubah) | Tingkat 1 (*in-place*) |
| 🟡 **Sedang** | pecah fungsi/berkas gemuk (>300 baris), ekstrak helper yang dipakai 3+ tempat, satukan tipe data lintas-modul, rapikan modul | kecil–sedang (perilaku HARUS dijaga sama; butuh test) | Tingkat 1–2 |
| 🔴 **Berat** | ubah struktur/kontrak lintas-modul, pindah ke Modular Monolith (Tingkat 2), atau pisah-repo (Tingkat 3) | tinggi (sentuh perilaku; potensi merusak) | Tingkat 2–3 |

> ⚠️ **Verifikasi "benar-benar 🟢" dulu (jangan asal cap aman):** "rename" hanya 🟢 kalau simbol **privat/lokal** (tidak ter-ekspor) — `Grep` nama simbol di seluruh repo; kalau **dipakai modul lain / ter-ekspor → NAIKKAN ke 🟡** (itu breaking: pemanggil di tempat lain ikut rusak — 🏢 analogi: ganti nama produk di katalog padahal banyak link lama menunjuk nama lama → link mati). Sama: "hapus impor/variabel tak terpakai" pastikan tak dipakai via akses dinamis/refleksi/re-export; "hapus duplikat" pastikan benar-benar identik (bukan sengaja beda).

3. **Tawarkan BERTAHAP — paling aman dulu (§4.7).** Tampilkan ringkasan singkat tingkat 🟢 Ringan (daftar peluang + perkiraan jumlah, **jangan tumpuk semua sekaligus**), LALU **popup klik** (`AskUserQuestion`, §14.1):
   - `[1] Kerjakan semua di tingkat ini (rekomendasi — paling aman, perilaku tak berubah)`
   - `[2] Pilih satu-satu`
   - `[3] Lewati ke tingkat berikut` (di tingkat TERAKHIR 🔴 Berat: ganti jadi `[3] Lewati tingkat ini → ke penutup`, karena tak ada tingkat sesudahnya)
   - `[stop] Cukup sampai sini` (→ apa pun tingkatnya, langsung lompat ke langkah 6 penutup "✅ SELESAI + rekap" — JANGAN berhenti diam)

4. **Kerjakan dengan Jaring Pengaman** (Safety Net — sama dengan `AUDIT_POST_SETUP_PROMPT_v1.md` Bagian 8).
   - **PRASYARAT untuk 🟡 Sedang / 🔴 Berat (refactor yang MENYENTUH perilaku)** — selaras gerbang audit "Test Foundation WAJIB sebelum Tahap 3" (`AUDIT_POST_SETUP_PROMPT_v1.md` Bagian 4):
     - **a. Cek tes dulu (anti rasa-aman-palsu).** `Grep` `*.test.*` / `__tests__` di area target. Kalau **0 tes** → JANGAN andalkan "cek otomatis lulus" (0 dari 0 selalu "lulus" = hijau-palsu). Pilihan: (i) **tulis tes pengunci-perilaku (characterization test) dulu** — rekam perilaku sekarang sebagai "foto sebelum"; ATAU (ii) turunkan ke perubahan paling minimal + tegaskan ke user "perilaku BELUM terverifikasi (tak ada tes yang menjaga fungsi ini)" + minta persetujuan eksplisit. 🟢 Ringan TIDAK perlu langkah ini (perilaku memang tak berubah).
     - **b. Pahami pemanggil dulu.** Sebelum ekstrak/pecah, `Grep` semua pemanggil + pemakai fungsi/tipe target; catat kontrak yang HARUS dijaga (parameter, nilai balik, efek samping, urutan). Ini blast radius §4.6 sebagai **prasyarat**, bukan cek belakangan. Baru lakukan transformasi.
   - **Eksekusi:** salinan kerja terpisah (branch) + **dalam 1 tingkat, kerjakan item dampak-paling-sempit dulu** (blast radius kecil → besar — biar kalau rusak ketahuan saat efeknya masih kecil) + tiap perbaikan = 1 catatan-simpan kecil yang bisa dibalik (atomic commit, reversible `git revert`) + cek otomatis (lint/build/test) **lulus dulu SEBELUM naik tingkat**. Lapor per item bahasa awam — kalau tes area = 0, sebut "cek otomatis hijau TAPI belum ada tes yang menjaga fungsi ini" (JANGAN tulis "aman").

5. **Naik 1 tingkat → popup BARU, ulangi langkah 3-4 untuk 🟡 Sedang, LALU sekali lagi untuk 🔴 Berat.** Tingkat terberat 🔴 WAJIB ikut **DITAWARKAN** (popup borong `[1]/[2]/[3]` yang sama) lalu **DIKERJAKAN** — bukan cuma dideskripsikan (owner minta "hingga refactor berat").
   - **Tingkat KOSONG (0 peluang) → LEWATI tanpa popup.** Sebut singkat ("tidak ada peluang 🟡 Sedang — langsung ke 🔴 Berat"), jangan tampilkan popup kosong. Kalau SEMUA tingkat kosong → langsung ke langkah 6 penutup + lapor "tidak ada yang perlu dirapikan".
   - **Aturan keras:** naik 1 tingkat per langkah (🟢→🟡→🔴), JANGAN loncat 🟢→🔴. Tiap kenaikan = keputusan tersendiri + popup tersendiri.
   - **Di 🔴 Berat:** popup borong `[1]/[2]` TETAP ditampilkan; sub-aturan kehati-hatian ini = TAMBAHAN, bukan pengganti popup. AI WAJIB tegaskan risiko + butuh **persetujuan eksplisit** (untuk yang benar-benar merusak/irreversible → konfirmasi verbatim §8.2 Aturan 5) + **Tahan Penggabungan (HOLD MERGE)**. Tingkat 3 (pisah-repo) = keputusan owner/lead, bukan staff sendiri.
   - Tiap tingkat WAJIB lewat **Gerbang Pra-Rilis §4.6** sebelum dianggap beres (seluruh tes jalan + bukti `berkas:baris`).

6. **Penutup WAJIB (§4.7 aturan 6): "✅ SELESAI + rekap rinci"** — apa yang dikerjakan tiap tingkat, hasil cek otomatis, **apa yang diubah vs TIDAK diubah**, cara membatalkan (`git revert <sha>`), + popup penutup ("simpan laporan / kerjakan lagi / cukup"). JANGAN tinggalkan user menatap layar tanpa popup lanjut.

🏢 Analogi: kayak **tukang renovasi yang tahu diri** — ganti keran dulu (paling aman) → *"beres, lanjut?"* → cat tembok → *"lanjut?"* → baru bongkar dapur (paling berisiko, minta izin tegas). Bukan bongkar seluruh rumah sekaligus lalu kabur.

### Workflow Konversasi (Contoh untuk Staff Non-Programmer)

Staff: "Tolong tambah tombol Export Excel di halaman /admin/users"

AI internally apply Prompt 1 pattern → tanya klarifikasi yang dibutuhkan template:

```
OK, mari saya bantu. Sebelum mulai coding, saya perlu klarifikasi (sesuai standar tim):

1. **Acceptance Criteria** (sukses kapan?):
   - Tombol cuma muncul untuk role admin? (default: ya)
   - Klik = download .xlsx isi apa? (suggest: nama, email, role, last_login, created_at)
   - Loading state saat generate? (default: ya)

2. **Prioritas + Target**: Rendah/Sedang/Tinggi, kapan selesai?

3. **Reuse**: Saya cek `lib/exports.ts` dulu - kalau ada helper Excel, kita reuse. Boleh?

4. **Risk Level** (per CLAUDE_TEAM_GUIDE.md section 7b):
   - 🟢 Low (UI tambahan, tidak sentuh data sensitif) - default untuk task ini
   - 🟡 Medium / 🔴 High?

Konfirmasi semuanya, atau koreksi saya yang salah asumsi.
```

Staff jawab dengan natural language. AI confirm summary + mulai eksekusi sesuai pattern Prompt 1.

### Saat Staff Bingung Mau Apa

Staff: "Aku bingung mau apa hari ini, ada task apa?"

AI auto-respond:
1. **Cek `docs/architecture_auto.md`** - ada pending docs / file CRITICAL belum punya `.md`?
2. **Saran 3-5 task** ringan yang relevan dengan progress proyek (mis. "ada `src/lib/auth.ts` baru tanpa `.md` pendamping, mau LAZY-GENERATE?")
3. **Atau cek chat channel** kalau staff sudah sambungkan link chat di AGENTS.md

### Filosofi

- Staff non-programmer fokus pada **APA** (intent task)
- AI handle **BAGAIMANA** (pattern + sintaks + git commands + commit message format)
- Kurangi friction "harus paste prompt panjang" - staff chat natural, AI auto-translate ke pattern resmi
- **Workflow PROMPT_LIBRARY.md tetap berlaku** - tapi dijalankan AI di belakang layar, transparan untuk staff

### Saat Pattern Tidak Cocok

Kalau staff brief task yang tidak masuk 15 pattern di atas (mis. "rancang database baru untuk modul HR"), AI:
1. Lapor: "Task ini di luar 15 pattern standar PROMPT_LIBRARY. Saya akan handle ad-hoc + dokumentasikan di `docs/decisions/<tanggal>-<slug>.md` (ADR pattern dari Prompt 10)"
2. Tanya klarifikasi yang diperlukan
3. Suggest: kalau pattern ini berulang, PR ke kit untuk tambah Prompt 16

### Fitur Lintas-Layanan (Multi-Repo) dengan Bahasa Sehari-hari

Saat project sudah split multi-repo (dashboard + shared + layanan: data-domain/scraper/seoanalysis/dll), staff non-programmer sering mau fitur yang **menyentuh beberapa layanan sekaligus** (mis. tabel gabungan). **Staff TIDAK boleh dipaksa ketik istilah teknis** ("API", "GET /endpoint", "loket", "schema"). Mereka cukup deskripsi bahasa sehari-hari; AI yang terjemahkan + jaga privasi otomatis.

#### Terjemahan: bahasa sehari-hari → kerja teknis (AI lakukan di balik layar)

| Staff bilang (sehari-hari) | AI kerjakan (teknis, otomatis — JANGAN narasikan istilah ini ke staff) |
|---|---|
| "aku mau bagian lain bisa lihat **cuma** [X, Y]" | Bikin endpoint (loket) yang return **hanya** field X, Y |
| "yang lain (kunci/biaya/catatan) **jangan dibagi**" | Filter privasi — exclude kolom rahasia dari response |
| "bikin **tabel** yang gabungin [A dari bagian-1] + [B dari bagian-2]" | Composition endpoint di backend dashboard yang panggil API tiap layanan + merge |
| "tampilin **contoh dulu** biar aku setujui" | Tunjukkan sample tabel (bahasa sederhana) untuk approval SEBELUM tulis kode |

#### Aturan privasi WAJIB (AI auto-enforce — staff tak perlu tahu mekanismenya)

1. **Default: bagikan SESEDIKIT mungkin.** Loket cuma return field yang staff sebut eksplisit. Kolom lain (apalagi secret: API key, biaya, rumus) **JANGAN PERNAH** masuk response kecuali diminta eksplisit.
2. **AI WAJIB tanya** (bahasa sederhana): *"Kolom mana yang boleh dilihat bagian lain? Sisanya aku sembunyikan."* — jangan asumsi.
3. **Penggabung lewat API, BUKAN baca database mentah** layanan lain (jaga isolasi — "loket bukan gudang": API = jendela kecil yang kasih field terpilih, bukan buka seluruh database).
4. **Cross-service feature = kerja yang punya akses repo terkait** (owner/lead, atau staff-penggabung yang cuma akses dashboard+shared+izin panggil API). Staff 1-layanan tidak perlu/bisa lihat internal layanan lain.

#### Contoh konkret (staff cukup ketik ini — bahasa hasil)

**Buka data (loket):**
> "Di bagian domain, aku mau bagian lain bisa lihat **cuma nama domain sama status redirect**-nya. Yang lain (kunci, biaya, catatan) **jangan dibagi**. Tolong siapkan."

AI apply: bikin endpoint di repo `data-domain` yang return `{domain, redirectStatus}` saja + exclude kolom lain. Lapor ke staff **bahasa hasil**: *"Bagian lain sekarang bisa lihat nama domain + status; sisanya tetap rahasia."*

**Tabel gabungan (penggabung):**
> "Aku mau **tabel di dashboard** yang nunjukin tiap domain: status redirect (dari bagian domain), skor SEO (dari bagian SEO), cek plagiat (dari bagian scraper). **Tampilin contoh dulu** biar aku setujui."

AI apply: (1) tunjukkan sample tabel bahasa sederhana untuk approval, (2) setelah OK → composition endpoint di backend dashboard yang panggil 3 API + merge, (3) tabel shadcn + 4 state (loading/kosong/error/sukses). Staff tak pernah lihat istilah "endpoint/API".

#### Filosofi
Staff fokus **APA yang mau dilihat + apa yang JANGAN dibagi**; AI urus loket + penggabung + filter privasi. Bahasa **hasil** ke staff, bukan istilah dapur. Isolasi & privasi dijaga AI otomatis — staff non-programmer **tak bisa sengaja bocorkan kolom rahasia** karena default-nya "sembunyikan + tanya dulu".

---

## 4.3. Guided Step-by-Step Pattern untuk Staff Baru (Universal First-Time Workflow)

Saat staff IT non-programmer pertama kali pakai lintasAI di project apapun (akses, bigseo, pbn-monitor, dst.), AI WAJIB pandu mereka step-by-step dengan **pattern wait-for-confirm** - tidak overwhelm dengan 14 step sekaligus, fokus 1 step at a time, konfirm progress dulu sebelum lanjut.

### Trigger Conditions (Kapan AI Auto-Apply Guided Pattern)

AI auto-apply 6-phase workflow di bawah kalau detect SALAH SATU:

1. **`docs/architecture.md` baru ter-generate** dari template (= setup fresh)
2. **User di folder yang punya `.claude-kit/` tapi `AGENTS.md` belum ter-fill placeholder** (`<NAMA_PROYEK>`, `<NAMA_KAMU>`, dst. masih ada)
3. **User chat eksplisit**: "halo aku staff baru", "baru pertama kali clone", "belum tau cara pakai", "guide aku dong"
4. **Owner brief eksplisit**: "akan ada staff baru join hari ini, bantu mereka onboarding"

### Wait-For-Confirm Pattern (Cara AI Pandu Step-by-Step)

```
AI: "📋 Step <N>: <deskripsi singkat aksi>
     
     Yang perlu kamu lakukan:
     1. <substep konkret>
     2. <substep konkret>
     
     Saya tunggu kabar kalau sudah selesai. Ketik 'OK' atau 'done' kalau sukses, 
     atau jelaskan kalau ada error / bingung."

User: "OK done" (atau jelasin error)

AI: "✅ Step <N> selesai. Lanjut Step <N+1>?" (kalau OK)
     atau
     "Hmm, error kamu adalah X. Solusi: <fix>. Coba lagi, lapor kalau masih stuck." (kalau error)
```

### Phase 1 - Foundation Verification (AI Auto, ~30 detik)

AI verify struktur tanpa user action:

| Step | Aksi | Wait Konfirm? |
|---|---|---|
| 1.1 | Cek `.claude-kit/` complete (36 file) | ❌ Auto |
| 1.2 | Cek `AGENTS.md` ada di root project + sudah ter-fill (bukan template `<...>`) | ❌ Auto |
| 1.3 | Cek `docs/` skeleton (architecture.md, glossary.md, _PATTERNS.md, _EXAMPLE.md, architecture_auto.md) | ❌ Auto |
| 1.4 | Cek `.github/workflows/ai-review.yml` ada | ❌ Auto |
| 1.5 | **Report ke user**: "Foundation OK ✅. 36 file kit + AGENTS.md + 5 docs skeleton + AI Reviewer aktif. Lanjut Phase 2 (baca panduan dasar)?" | ✅ Tunggu konfirm |

### Phase 2 - Pre-Work Reading (Day 0, sekali pakai)

Skip phase ini kalau user pernah sebelumnya (cek di memory).

| Step | Aksi | Wait Konfirm? |
|---|---|---|
| 2.1 | "Buka file `docs/GLOSSARY_NON_PROGRAMMER.md`. Baca sambil bayangin analogi (Google Drive, Word, IKEA, dst.). **Estimasi 15 menit**. Ketik 'OK' kalau sudah baca habis." | ✅ Tunggu "OK" |
| 2.2 | "Buka file `docs/SECURITY_INCIDENT_PLAYBOOK.md`. Fokus ke section '6-Step Procedure' + '5 Yang TIDAK BOLEH Dilakukan'. **Estimasi 5 menit**. Ketik 'OK' kalau sudah." | ✅ Tunggu "OK" |
| 2.3 | "Quiz singkat (3 pertanyaan, supaya saya yakin kamu paham):<br>1. Apa beda `main` branch sama feature branch?<br>2. Kalau token bocor, langkah pertama yang kamu lakukan apa?<br>3. Apa itu Risk Level dan kenapa penting?" | ✅ Tunggu jawaban (AI verify) |
| 2.4 | "Foundation reading done ✅. Quiz lulus. Lanjut Phase 3 (load project context)?" | ✅ Tunggu konfirm |

### Phase 3 - Project Context Loading (AI Auto, ~30 detik)

AI baca file project, briefing user:

| Step | Aksi | Wait Konfirm? |
|---|---|---|
| 3.1 | Read `AGENTS.md` + relevant section `CLAUDE_universal_v1.md` | ❌ Auto |
| 3.2 | Read `docs/architecture.md` (peta makro project, kalau ada) | ❌ Auto |
| 3.3 | Read `docs/architecture_auto.md` (TOC AI-maintained, kalau ada) | ❌ Auto |
| 3.4 | Read `docs/glossary.md` (kamus istilah domain spesifik project, kalau ada) | ❌ Auto |
| 3.5 | **Briefing 3-5 kalimat** ke user: "Project ini `<nama>`. Stack: `<stack>`. Domain: `<bisnis>`. Status progress: `<X%>`. Focus minggu ini: `<topik>`. Tech stack default: Tailwind + shadcn/ui." | ✅ Tunggu konfirm "OK paham" |

### Phase 4 - Environment Setup (Per project, sesuai stack)

| Step | Aksi | Wait Konfirm? |
|---|---|---|
| 4.1 | "Owner sudah DM kamu password DB + .env values? Kalau belum, lapor owner dulu. Ketik 'OK' kalau sudah terima." | ✅ Tunggu konfirm |
| 4.2 | "Sekarang jalankan: `pnpm install`. Tunggu sampai selesai (3-5 menit). Lapor kalau ada error." | ✅ Tunggu "selesai" |
| 4.3 | "Setup `.env.local`: copy dari template `.env.example`, paste isi yang owner DM. WAJIB cek file extension `.env.local` (bukan `.env.local.txt`)." | ✅ Tunggu konfirm |
| 4.4 | "Generate Prisma client (skip kalau project tidak pakai Prisma): `npx prisma generate`. Tanpa step ini, dev server crash." | ✅ Tunggu "OK" |
| 4.5 | "Run dev server: `pnpm dev`. Buka browser ke `localhost:3000`. Lapor kalau halaman load + tidak ada error merah." | ✅ Tunggu "OK halaman load" |

### Phase 5 - First Task (Test Workflow End-to-End)

Phase 5 punya **2 variant**. AI tanya user dulu sebelum lanjut:

**AI**: *"📋 Phase 5: First Task. Kamu mau:<br>
**(A) Test latihan dulu** - owner kirim micro-task ringan (typo fix, ganti tahun copyright) supaya kamu paham workflow penuh tanpa risk. Cocok kalau ini hari pertama kamu kerja + mau hands-on dulu.<br>
**(B) Langsung kerja task real** - kamu sudah dapat brief task dari owner sebelumnya (verbal/chat/issue). Langsung brief saya, kita execute pakai workflow standar.<br>
Pilih A atau B."*

#### Variant A - Latihan Micro-Task (First Day Hands-On)

| Step | Aksi | Wait Konfirm? |
|---|---|---|
| 5A.1 | "Minta owner kirim micro-task latihan via channel chat (mis. fix typo di README, ganti tahun copyright). Paste task ke saya kalau sudah." | ✅ Tunggu task |
| 5A.2 | Apply Pattern-Driven Workflow (section 4.2): AI tanya AC + risk level + reuse | ✅ Tunggu jawaban |
| 5A.3 | AI eksekusi: `git checkout -b <branch>` → edit file → `git commit` → `git push` → `gh pr create` | ✅ Tunggu konfirm tiap mikro-step |
| 5A.4 | "Tunggu 2-3 menit, Vercel akan kasih preview URL di komentar PR. Buka URL itu, verify perubahan kelihatan." | ✅ Tunggu "OK kelihatan" |
| 5A.5 | "Lapor owner di channel chat: 'PR siap review: <link>, preview: <link>'. Owner akan review + merge." | ✅ Tunggu konfirm "owner merged" |

#### Variant B - Langsung Real Task (Staff Sudah Tau Task)

| Step | Aksi | Wait Konfirm? |
|---|---|---|
| 5B.1 | "OK, brief saya task kamu. Format bebas: bisa paste task dari chat owner, bisa juga ceritain natural language ('owner suruh aku tambah fitur Y di halaman Z')." | ✅ Tunggu brief task |
| 5B.2 | Apply Pattern-Driven Workflow (section 4.2): AI tanya AC + target + reuse + risk level berdasarkan brief | ✅ Tunggu klarifikasi |
| 5B.3 | AI eksekusi workflow standar: branch + code + commit + push + PR (sama seperti Variant A) | ✅ Tunggu tiap mikro-step |
| 5B.4 | Verify Vercel preview URL | ✅ Tunggu "OK kelihatan" |
| 5B.5 | Lapor owner di chat | ✅ Tunggu konfirm |

### Phase 6 - Daily Work Starts (Closing)

| Step | Aksi |
|---|---|
| 6.1 | **AI closing message (neutral, tidak asumsi staff butuh task suggestion)**:<br><br>"🎉 **Onboarding selesai!** Kamu sudah hands-on test workflow lengkap (branch → PR → preview → merge → deploy).<br><br>**Aturan penting harian**:<br>1. Tiap task baru = sesi Claude Code FRESH (jangan campur task lama)<br>2. Chat saya dengan bahasa natural - saya auto-apply pattern dari PROMPT_LIBRARY<br>3. Tiap response substantive saya tutup dengan Tinjauan Multi-Divisi (banyak lensa divisi)<br>4. Kalau ada security alert, baca `docs/SECURITY_INCIDENT_PLAYBOOK.md`<br>5. Kalau bingung istilah, balik baca `docs/GLOSSARY_NON_PROGRAMMER.md`<br><br>Saya standby. **Brief saya kapanpun kamu siap mulai** - bisa task dari owner, bisa juga inisiatif kamu sendiri (mis. 'mau cek N+1 query di Inbox' / 'mau refactor lib/utils.ts'). 🚀" |

### Project Setengah Jadi vs Fresh Project

Pattern 6-phase berlaku UNIVERSAL untuk fresh project ATAU project setengah jadi (clone existing repo dengan code). Bedanya cuma di Phase 3 + 4 + 5:

#### Fresh Project (folder baru, belum ada code)

- **Phase 3** briefing singkat: *"Project baru, belum ada code yang signifikan. Kamu akan mulai dari nol sesuai brief owner."*
- **Phase 4** env setup minimal: cuma `.env.local` + `pnpm install` (mungkin belum ada Prisma schema)
- **Phase 5** Variant A WAJIB (test workflow dengan task latihan dulu - staff belum punya konteks)

#### Project Setengah Jadi (clone existing repo)

- **Phase 3** briefing EKSTENSIVE (5-10 kalimat):
  - Stack lengkap dari `package.json` + framework version
  - Domain bisnis (dari `architecture.md`)
  - Status progress (mis. "5% - fokus auth + landing page")
  - File CRITICAL yang sudah punya `.md` vs belum (dari `architecture_auto.md`)
  - Active focus area minggu ini
- **Phase 4** env setup lengkap: `pnpm install` + `.env.local` + `npx prisma generate` (kalau pakai Prisma) + `pnpm dev` + **verify halaman load di browser**
- **Phase 5** AI tanya user pilih Variant A atau B:
  - **Variant A** kalau staff first time + butuh hands-on dulu
  - **Variant B** kalau staff sudah dapat brief task dari owner (mayoritas kasus di project setengah jadi)

**Aturan tambahan untuk Project Setengah Jadi**:
- Cek `docs/architecture_auto.md` untuk peta file CRITICAL existing
- Briefing termasuk: *"Project ini sudah ada N file CRITICAL dengan docs, M file belum. Mau scan dulu (Phase Bulk-Bootstrap di `PROJECT_LIFECYCLE_PROMPT_v1.md` Stage 2: Bikin Catatan Proyek) atau langsung task?"*
- Kalau staff pilih langsung task → AI lakukan LAZY-GENERATE saat staff sentuh file CRITICAL yang belum punya docs (tetap aktif by default)

### Trigger Detection - Project Setengah Jadi vs Fresh

AI auto-detect berdasarkan:
- **Fresh**: `src/` kosong atau cuma 1-2 file boilerplate, `package.json` minimal
- **Setengah Jadi**: `src/` punya banyak file source, `package.json` extensive dependencies, `prisma/schema.prisma` punya banyak model

Pilih Phase 3-5 variant otomatis, lapor ke user: *"Detect kamu di project setengah jadi (N file source). Phase 3 briefing extensive, Phase 5 default Variant B (real task) - confirm OK?"*

### Aturan Tambahan

- **Skip phase yang sudah selesai**: kalau user re-trigger guided workflow (mis. di project ke-2), AI skip Phase 2 (reading) - straight ke Phase 3.
- **Adapt per stack**: Phase 4 step 4.4 (Prisma generate) skip kalau project tidak pakai Prisma. AI detect dari `package.json`.
- **Bahasa Indonesia ramah**: tone friendly, jangan formal kaku. Anggap kayak mentor senior dev bantu junior pertama kali.
- **Error tolerance**: kalau user error di step manapun, AI guide debug dulu sebelum lanjut. Jangan biarkan user stuck sendiri.
- **Persistence**: kalau sesi ditutup di tengah workflow, sesi berikutnya AI cek progress (mis. cek file ter-update di `.claude-kit/` history) dan resume dari step yang relevan.

### Filosofi

**Staff non-programmer fase awal = butuh hand-holding intentional**. Bukan karena mereka tidak capable - tapi karena cognitive load (paham git + paham task + paham AI workflow sekaligus) terlalu tinggi untuk dipelajari self-service. Guided workflow ini "kursi roda training" untuk Day 0-1, setelah Day 7+ staff lepas guided pattern, kerja independen.

---

## 4.4. Audit Post-Setup Pattern (Otomatis Setelah Stage 1/2 atau Standalone)

Setelah `PROJECT_LIFECYCLE_PROMPT_v1.md` Stage 1 (Proyek Baru) / Stage 2 (Bikin Catatan Proyek) selesai (atau setiap kali user brief task "audit" / "review" / "cek apa yang bisa diperbaiki"), AI WAJIB tawarkan **AUDIT KOMPREHENSIF MULTI-DIMENSIONAL** dengan **ANALOGI NON-PROGRAMMER**. Workflow lengkap di file standalone `./.claude-kit/AUDIT_POST_SETUP_PROMPT_v1.md`.

### Kapan AI auto-trigger audit offer

1. **Setelah Stage 1/2 `PROJECT_LIFECYCLE_PROMPT_v1.md` closing** ATAU **setelah `setup-pola-b.ps1` Phase 5b checklist selesai** (v1.5.7+) - AI tutup workflow dengan offer: *"Setup + bulk-bootstrap selesai. Mau aku lanjut audit komprehensif (read-only, scan multi-dimensional, output ranked low→high risk dengan analogi non-programmer)? Paste `AUDIT_POST_SETUP_PROMPT_v1.md` atau jawab 'ya' di sini."*
2. **User brief eksplisit**: "audit project", "review codebase", "cari bug + refactor opportunity", "apa yang bisa diperbaiki", "scan menyeluruh"
3. **Setelah refactor besar** (mis. extract helper cross-module, schema migration) - AI suggest audit ulang untuk verify behavior unchanged.
4. **Sebelum hire staff** - owner brief: "staff hire 1-2 minggu lagi, project siap belum?" → AI auto-trigger audit + rencana bertahap.

### Format finding WAJIB pakai analogi non-programmer

Tiap finding dari audit HARUS punya 6 field:

```markdown
**[N] <Title teknis singkat>**
- 📖 **Analogi**: <bahasa sehari-hari pakai contoh kantor / lemari arsip / ATM / tukang pos / brankas>
- 🎯 **Kenapa penting**: <1-2 kalimat awam, tanpa jargon>
- 🛠 **Fix**: <pointer cepat, sebut file/line dan langkah kasar>
- ⏱ <effort: 5min / 30min / 2hr / 8hr+ / multi-day>
- 🚦 <severity: critical / high / medium / low>
- ⚠ Risk merusak system: <low / medium / high>
```

### Style guide analogi (mapping jargon → bahasa awam + tools digital populer)

**WAJIB**: tiap finding audit punya 3 layer analogi (tidak cuma 1):

1. **🏢 Sehari-hari**: analogi kantor / dapur / lemari arsip / loket bank - universal, no tools knowledge.
2. **📱 Tools digital populer**: analogi pakai fitur familiar Indonesia-context (Tokopedia, Gojek, WhatsApp, BCA mobile, Excel, Google Drive, dst.) - staff yang familiar dengan tools tersebut langsung paham.
3. **🎯 Contoh konkret**: kapan situasi ini muncul di proyek (1 kalimat).

**AI rule: Saat menggunakan jargon teknis (Prisma, schema, migration, RLS, env var, dll), AUTO-generate 3-layer analogi inline tanpa lookup ke library:**
- Layer 1 (sehari-hari): contoh dari kehidupan rumah/kantor/sekolah
- Layer 2 (tools digital populer Indonesia): Tokopedia, Shopee, Gojek, WhatsApp, BCA mobile, Excel, Google Drive, Notion, Discord, YouTube, iPhone
- Layer 3 (kasus konkret user): apply ke project user

Contoh inline (5 grounding samples, sisanya AI generate):
- Prisma = lemari arsip Gojek (struktur jelas, semua driver punya kotak masing-masing)
- Migration = upgrade WhatsApp Web (data ditarik dari format lama ke format baru)
- RLS = privasi WhatsApp (kamu cuma lihat chat kamu, bukan chat orang lain)
- Schema = template Notion (struktur dulu, isi belakangan)
- Env var = PIN BCA (rahasia, jangan ditulis di kode)

**Library aktif**: rujuk ke `docs/ANALOGI_LIBRARY.md` (auto-deployed via `setup-pola-b.ps1` dari `templates/ANALOGI_LIBRARY.md`) kalau ada jargon yang tidak ke-cover inline. Untuk istilah baru di luar library, AI generate 3-layer kontekstual + suggest tambah via LAZY-GENERATE.

**Style guide tools digital populer Indonesia-context**:

| Kategori | Tools yang sering dipakai sebagai analogi |
|---|---|
| **E-commerce** | Tokopedia, Shopee, Bukalapak (keranjang, checkout, voucher, COD, flash sale) |
| **Transport** | Gojek, Grab (ojek booking, ETA, GoPay e-wallet, GoFood) |
| **Communication** | WhatsApp (read receipt, last seen, archive, broadcast, story), Telegram |
| **Social** | Instagram, TikTok (story 24jam, feed algorithm, hashtag, DM) |
| **Productivity** | Google Drive/Docs/Sheets (shared folder, permission, comment, real-time collab, version history), Excel (formula, filter, pivot, freeze pane, named range), Notion (page, database, template) |
| **Design** | Canva (template duplicate, brand kit, lock layer, version) |
| **Team comm** | Discord (server, role, channel permission, thread), Slack |
| **Video** | YouTube (playlist, watch later, subscribe), Netflix (watchlist, recommendation) |
| **Phone** | iPhone/Android (Do Not Disturb, app permission, biometric, screen lock) |
| **Banking** | BCA mobile, BRI BRImo, Mandiri Livin, Jenius (OTP SMS, daily limit transfer, mutasi rekening, QRIS) |
| **Food delivery** | GoFood, GrabFood, ShopeeFood (booking driver, ETA, status order) |

Untuk istilah BARU yang belum di tabel ini atau di `docs/ANALOGI_LIBRARY.md`, AI bikin analogi konsisten (3 layer: sehari-hari + tools digital + contoh) + suggest tambah ke library via LAZY-GENERATE.

### Filosofi audit dengan analogi

1. **READ-ONLY by default**: audit cuma scan + laporan. Tidak ada `Edit`/`Write` destruktif. User pegang kontrol "fix yang mana".
2. **Ranked low → high risk**: staff non-programmer butuh tahu "mana yang aman dikerjakan dulu". Quick wins dengan `risk_of_introducing_bug=low` jadi prioritas.
3. **Analogi WAJIB**: tiap finding harus punya 📖 baris dengan analogi sehari-hari. **Tanpa analogi = bukan audit lintasAI standard.**
4. **Adversarial verify**: cegah halusinasi inflate jumlah finding. Default `is_real=false` kalau verifier tidak 100% yakin.
5. **Rencana bertahap = guidance, BUKAN auto-execute**. Owner pilih per-finding mau lanjut atau tidak. AI execute dengan safety net pattern.

### Default execution sebagai bagian dari Pattern-Driven Workflow

Per section 4.2, intent staff yang map ke pattern audit:

| Intent staff (bahasa natural) | Pattern apply |
|---|---|
| "audit project", "review codebase", "scan menyeluruh" | `AUDIT_POST_SETUP_PROMPT_v1.md` workflow lengkap |
| "ada bug?", "apa yang salah?", "cari masalah" | `AUDIT_POST_SETUP_PROMPT_v1.md` dengan fokus security + qa dimensi |
| "perbaiki performa", "apa yang lambat?" | `AUDIT_POST_SETUP_PROMPT_v1.md` dengan fokus database + performance dimensi |
| "ready hire staff?", "siap onboarding?" | `AUDIT_POST_SETUP_PROMPT_v1.md` dengan fokus onboarding + docs gap dimensi |
| "refactor codebase", "DRY", "extract helper" | `AUDIT_POST_SETUP_PROMPT_v1.md` dengan fokus refactor dimensi |

Detail lengkap workflow + filosofi + Popup #1 (pilih tier) + Popup #2 (lanjut Tahap 0 / write report / pick item / stop) ada di `./.claude-kit/AUDIT_POST_SETUP_PROMPT_v1.md`.

---

---

## 4.5. Update Strategy Pattern (Otomatis Detect Update Tersedia + Classify Tier)

Saat kit lintasAI rilis versi baru, **AI yang melakukan update analysis + execution**. Staff cuma chat natural ("ada update kit?") + confirm Y/N. PS script (`kit.ps1 update`) tetap ada sebagai **fallback untuk power user / CI** - tapi bukan jalur utama untuk staff non-programmer.

**Filosofi**: staff IT non-programmer tidak akan baca CHANGELOG 200 baris dan tidak akan klasifikasi sendiri "ini breaking apa bukan". Itu tugas AI: parse CHANGELOG → classify tier → ringkas dalam Bahasa Indonesia + analogi tools digital populer → execute setelah user confirm.

### Kapan AI auto-trigger update analysis

AI WAJIB jalan-kan update analysis kalau salah satu trigger ini muncul:

1. **User chat eksplisit**: "ada versi baru?", "update kit", "kit perlu update?", "version check", "lintasAI vX.Y rilis", "cek update".
2. **User brief versi spesifik**: "v1.2.0 rilis", "tolong update ke v1.5.0", paste link release notes GitHub.
3. **Awal sesi baru** (OPSIONAL, low-noise): kalau folder `./.claude-kit/` terdeteksi dan user belum brief task lain, AI boleh silent-check ke `github.com/ojokesusu/lintasAI` (commit `d7284b1` baseline vs HEAD `CHANGELOG.md`). Kalau ada gap >0 entry → AI sebut singkat di akhir greeting: *"Btw, ada N entry CHANGELOG baru sejak versi kit kamu (v1.0.0). Mau aku jelasin + update?"* - JANGAN block task lain dengan ini.

**JANGAN auto-execute update tanpa confirm**. Update = modify file di `./.claude-kit/` = re-clone destruktif (walau ada backup). Wajib popup confirm dulu (lihat section 14 Eksekusi Aksi).

### 4-Tier Classification Algorithm (WAJIB urutan dari atas)

AI baca tiap CHANGELOG entry yang BELUM ada di versi kit user, lalu classify pakai rule ini **urutan dari atas ke bawah** (tier paling restrictive menang kalau ambigu):

| Tier | Pemicu di CHANGELOG entry | Staff action |
|---|---|---|
| **4 [SCAN-REQUIRED]** | Prefix `[SCAN-REQUIRED]` di awal entry | Re-paste `PROJECT_LIFECYCLE_PROMPT_v1.md` Stage 1/2 (re-bootstrap full) |
| **3 [BREAKING]** | Prefix `[BREAKING]` di awal entry | Baca "Migration Steps" inline di CHANGELOG + execute step-by-step |
| **2 (AI auto-sync)** | Tanpa label, tapi entry mengandung kata: "tambah section", "fitur baru", "aturan AI", "rule baru", "section X.Y baru", "expand pattern" | 1 perintah (`kit.ps1 update`), AI auto-pakai aturan baru di sesi berikut |
| **1 (Silent)** | Tanpa label, tapi entry mengandung kata: "fix typo", "perbaikan ringan", "minor fix", "clarify wording", "rephrase" | 1 perintah, no behavior change |

**Edge cases**:
- Entry punya `[BREAKING]` + `[SCAN-REQUIRED]` → pakai Tier 4 (paling restrictive).
- Entry tanpa label tapi ambigu (mis. "refactor section 4.3 jadi 2 file") → AI ESKALASI ke Tier 3 [BREAKING] secara defensif. Lebih baik over-cautious daripada miss-detect breaking.
- Multi-version jump (v1.0 → v1.5, lewat 5 entry) → AI classify TIAP entry, ambil tier TERTINGGI sebagai tier eksekusi. Tapi summary jelaskan per-version (lihat format di bawah).

### Format Summary WAJIB (dengan analogi tools digital)

Setelah AI classify, output summary ke user dalam format ini (BUKAN dump CHANGELOG mentah):

```markdown
## Update lintasAI tersedia: v<X> → v<Y>

**Ringkasan plain Indonesia**: <1-2 kalimat, no jargon>

**Tier <N>**: <analogi tools digital satu kalimat - WAJIB pakai library tools populer>

**File akan berubah** (overwrite dari upstream):
- `./.claude-kit/<file1>`
- `./.claude-kit/<file2>`

**File preserved** (user-modified, di-backup ke `*.bak.<timestamp>`):
- `./.claude-kit/<file3>` (manifest sha256 mismatch dengan upstream baseline)

**Action staff**:
- Tier 1/2: TIDAK ADA - habis confirm, selesai. AI auto-pakai aturan baru.
- Tier 3: Baca "Migration Steps" CHANGELOG entry + execute step-by-step (AI bantu propose tiap step).
- Tier 4: Re-paste `PROJECT_LIFECYCLE_PROMPT_v1.md` Stage 1/2 (AI panduin bulk-bootstrap ulang).

**Confirm**: ketik `ya` untuk execute, atau `nanti` untuk skip (rekomendasi kalau ragu — paling aman, tidak ada file yang ditimpa dulu; update bisa kapan saja).
```

### Library analogi tools digital untuk tier (WAJIB pakai salah satu)

| Tier | Analogi tools digital populer (pilih 1 yang paling relevan dengan jenis perubahan) |
|---|---|
| **Tier 1 (Silent)** | **WhatsApp** 2.23.10 → 2.23.11 auto-update di background, kamu cuma notice icon kuning bentar; **Chrome** silent update di tab background |
| **Tier 2 (AI auto-sync)** | **iPhone iOS 17.3 → 17.4** minor update - restart sekali, fitur baru aktif, app lama tetap jalan; **Notion** rilis fitur AI Q&A baru, otomatis muncul di sidebar |
| **Tier 3 [BREAKING]** | **iPhone iOS 16 → iOS 17** major upgrade - backup wajib, ada migration screen yang minta confirm, beberapa app butuh re-login; **WhatsApp** chat migration Android → iPhone |
| **Tier 4 [SCAN-REQUIRED]** | **Tokopedia Seller** ganti algoritma kategori produk - semua produk lama wajib re-map manual ke kategori baru; **Shopee** migrate sistem variant produk, semua listing lama harus re-create variant |

Kalau jenis perubahan beda dari pattern di tabel (mis. rilis `update-kit.ps1` baru, struktur prompt-library ganti), AI bikin analogi konsisten **harus dari tools digital populer Indonesia-context** (lihat library 4.4: Tokopedia/Shopee/Gojek/WhatsApp/BCA mobile/Excel/Google Drive/Notion/Discord/iPhone/Canva/dll). **Dilarang** pakai analogi programming jargon ("merge commit", "rebase", "diff tree").

### Dual-Mode Execution Flow

#### Mode A: AI Chat Mode (DEFAULT, recommended untuk staff non-programmer)

```
1. Trigger detected (user chat / brief / silent check)
2. AI fetch CHANGELOG.md upstream (via WebFetch ke github.com/ojokesusu/lintasAI/blob/main/CHANGELOG.md, atau curl raw URL)
3. AI parse versi user dari ./.claude-kit/CHANGELOG.md baris pertama (atau AGENTS.md section "Versi kit aktif")
4. AI diff entry baru antara versi user dan HEAD upstream
5. AI classify tier (tiap entry → tier, ambil tertinggi sebagai tier eksekusi)
6. AI compose summary (format wajib di atas)
7. AI tampilkan summary + popup confirm (section 14 - 3-option: ya / nanti / batal)
8. User confirm "ya" → AI execute: `pwsh ./.claude-kit/kit.ps1 update` (atau `./.claude-kit/update-kit.ps1` direct)
9. AI parse output PS script → lapor hasil (success / error / file di-backup)
10. AI update AGENTS.md section "Versi kit aktif" + "Riwayat update kit" (tambah baris baru)
11. Kalau Tier 3 → AI lanjut propose execute Migration Steps dari CHANGELOG inline (per-step confirm)
12. Kalau Tier 4 → AI prompt user re-paste `PROJECT_LIFECYCLE_PROMPT_v1.md` Stage 1/2
```

#### Mode B: PS Script Mode (FALLBACK untuk power user / CI)

Staff/CI run `pwsh ./.claude-kit/kit.ps1 update` direct (tanpa AI mediasi). PS script auto-classify tier + structured terminal output (tabel tier per entry + file changed/preserved + exit code per tier). AI tidak orchestrate - tapi kalau user paste output PS script ke chat dan minta tolong interpret, AI WAJIB klasifikasi ulang + tampilkan summary format wajib.

### Backup Retention Rules (AI WAJIB lapor saat cleanup)

`update-kit.ps1` auto-jaga retention dengan rule:

1. **Hapus `*.bak.<timestamp>` > 30 hari old**.
2. **Keep max 3 backup version terakhir** (per file). Versi ke-4 dst auto-deleted.
3. **TIDAK ADA folder `migrations/` per breaking** (over-engineering untuk tim 5-15 staff). Migration steps **inline di CHANGELOG entry** section "Migration Steps".

Saat AI execute update dan PS script log ada file `.bak` yang dihapus karena rule retention, AI WAJIB sebut di laporan post-update:

```
Update selesai. Cleanup retention:
- 2 file backup > 30 hari dihapus: AGENTS.md.bak.20260301-..., CLAUDE_universal_v1.md.bak.20260315-...
- 1 file backup di-rotate (versi terlama dari 4 backup dihapus, sisakan 3 terbaru): templates/PROMPT_LIBRARY.md.bak.20260418-...
- Total disk reclaimed: <X> KB
```

Tujuan: staff non-programmer **tahu** file lama dihapus (transparansi), bukan silent cleanup yang bikin staff panik "kok file backup-ku ilang?" 2 minggu kemudian.

### Migration Steps untuk Tier 3 [BREAKING] (AI workflow)

Tiap entry `[BREAKING]` di CHANGELOG WAJIB punya section `### Migration Steps` inline dengan PS commands explicit. AI workflow saat Tier 3 detected:

1. **Setelah `kit.ps1 update` selesai** (file baru sudah di-pull), AI baca section "Migration Steps" dari CHANGELOG entry yang relevant.
2. **AI propose execute step-by-step** - JANGAN bulk-execute. Tiap step: tampilkan command + analogi tools digital singkat (kenapa step ini perlu) + confirm Y/N.
3. **Per-step confirm** (section 14 Eksekusi Aksi style): user `ya` lanjut, `lewati` skip, `batal` stop di tengah (AI lapor state: step 3 dari 7 selesai, sisa 4 step belum dijalankan).
4. **Setelah semua step selesai**, AI verify dengan command yang disebut di CHANGELOG Migration Steps section "Verification" (kalau ada), atau scan basic (file exist + section anchor exist).
5. **Update AGENTS.md "Riwayat update kit"** dengan catatan "Tier 3 BREAKING - migration steps N/N selesai".

Kalau user batalin di tengah Tier 3 migration, AI WAJIB lapor di sesi berikut: *"Note: update v<X>→v<Y> di-pause di step 3/7 tanggal <tgl>. Mau lanjut sekarang?"* - JANGAN silent-forget.

### Cross-reference dokumen

- **`docs/UPDATE_GUIDE.md`** (staff-facing): tutorial chat-driven untuk staff non-programmer ("cara update kit lewat AI chat"). AI rujuk kesini kalau user nanya "gimana cara update?" sebelum AI orchestrate.
- **`PROJECT_LIFECYCLE_PROMPT_v1.md` Stage F (Update Kit)** (single-paste): prompt template kalau staff butuh full-control update flow (paste prompt → AI execute structured). Jarang dipakai - AI Chat Mode lebih ringan.
- **`PROMPT_LIBRARY.md` Prompt 17**: mapping intent staff → pattern apply untuk update (mis. "ada versi baru?" → trigger section 4.5 ini).

### Default execution sebagai bagian dari Pattern-Driven Workflow

Per section 4.2, intent staff yang map ke pattern update:

| Intent staff (bahasa natural) | Pattern apply |
|---|---|
| "ada versi baru?", "kit perlu update?", "version check" | Section 4.5 trigger silent check → summary tier |
| "update kit", "tolong update", "naik versi" | Section 4.5 full flow (parse → classify → summary → confirm → execute) |
| "lintasAI vX.Y rilis" + link release | Section 4.5 dengan target versi spesifik |
| "ada breaking change?", "ini bahaya gak update-nya?" | Section 4.5 classify-only mode (tampilkan summary tier, JANGAN auto-execute) |
| "rollback update kit", "balikin versi lama" | Section 4.5 rollback flow (pakai `kit.ps1 rollback` — restore otomatis dari backup `.bak.<ts>` / `.backup-<ts>`) |

---

## 4.8. "lintasAI skill" — 18 kriteria pindai menyeluruh + cara jalan (DETAIL on-demand)

> Dibaca AI saat user mengetik **"lintasAI skill"** (pemicu + inti load-bearing di `CLAUDE_universal_v1.md` §4.8). Asal: owner 2026-06-14 — ingin satu frasa untuk audit menyeluruh lintasAI atas kondisi timnya. Berlaku di SEMUA project yang install lintasAI. Nama lama "scan lintasAI function" = alias sama.

### Cara jalan (urut)
1. **Konfirmasi cakupan singkat** kalau ambigu: full (18 kriteria) atau sebagian (mis. "keamanan saja"). Default = full.
2. **Tampilkan peta langkah** (§4.7): "Pindai ada N bagian, mulai bagian 1."
3. **Mode aman cuma-baca** (§8.2 Aturan 3): Read/Grep/jalankan tes — JANGAN Edit/Write/SQL-ubah selama memindai. Perubahan hanya setelah user setuju.
4. **Periksa per kriteria**, sajikan BERTAHAP (info → popup → lanjut otomatis). Untuk scan besar → `Workflow` multi-sudut paralel (hemat wall-clock, tetap cakupan penuh).
5. **Tiap temuan**: bukti `berkas:baris` + skenario gagal nyata + tingkat GENTING/PENTING/RAPIKAN. "Nol temuan itu sah" — jangan mengarang (§8.2 Aturan 3b).
6. **Tutup**: "✅ SELESAI + rekap rinci" (diperiksa apa, hasil, yang perlu diubah vs aman) + Tinjauan Multi-Divisi (§4.1) + popup penutup: [1] simpan laporan (rekomendasi, default) — paling aman, cuma menyimpan temuan tanpa mengubah kode dulu · [2] perbaiki sekarang · [3] cukup.

### 18 kriteria (checklist owner)
1. Semua isi lintasAI cocok kondisi tim owner (40-50 staff IT non-programmer).
2. SEMUA output Bahasa Indonesia + non-programmer + analogi aplikasi digital populer yang mudah dimengerti.
3. Semua project aman — tidak ada crash/bug/error.
4. Hemat token AI saat eksekusi + analisa (tanpa turunkan kualitas).
5. Tidak mengurangi kualitas faktor apa pun (A-Z).
6. Keamanan kode + DB: tak bisa diretas pihak luar/dalam — KECUALI pihak dalam yang sengaja diberi full control (least-privilege berjenjang).
7. Pengerjaan cocok non-programmer → banyak yang otomatis.
8. Cocok 3 repo atau multi-repo 6-10 repo.
9. Aman bisnis: staff sendiri tak bisa menduplikat/mencuri apa pun (IP defense lewat kontrol-akses teknis, karena tim tak bisa NDA/legal).
10. Anti-halusinasi: tak beri info salah; tiap eksekusi/perubahan berbasis fakta sebenar-benarnya. Alternatif akurat dari beberapa sumber digital.
11. Stack default project = Next.js + Supabase + Tailwind + shadcn + Vercel/Railway/Render.
12. Tiap staff terisolasi TAPI tidak menyulitkan — ada otomatisasi.
13. Staff non-programmer cukup modal prompt; hasil info jitu/akurat/konkret.
14. Keputusan CODING dari standar profesional lintas-divisi: Backend, Frontend, Database, DevOps, CyberSecurity, dll.
15. Keputusan PRODUCT dari standar profesional lintas-divisi: SEO, Marketing, Business Owner, dll. (14+15 = Tinjauan Multi-Divisi §4.1.)
16. Saat lintasAI di project orang lain (jika install) → scan otomatis menganalisa faktor di atas, tetap cepat + hemat token.
17. Bisa bersaing dengan bisnis digital orang lain.
18. AI boleh menambah praktik baik selama tidak menyulitkan ("Claude Code Pintar").

### Catatan
- Untuk repo kit lintasAI sendiri, "lintasAI skill" = Gerbang QA+QC §4.6 penuh + 18 kriteria di atas.
- Kalau project bukan stack default (kriteria 11), sesuaikan — bukan dipaksa ke Next.js/Supabase.

---

## 4.9. Skill kustom per-project — format + langkah (DETAIL on-demand)

> Dibaca AI saat client bikin/panggil skill kustom (inti load-bearing di `CLAUDE_universal_v1.md` §4.9). Asal: owner 2026-06-14 — tiap client punya keahlian beda, harus bisa bikin skill sendiri tanpa terpaku skill bawaan.

### Tempat simpan
- Berkas: **`docs/SKILLS_LOCAL.md`** di project client. AI buat berkas ini saat skill pertama dibuat (jangan paksa buat berkas kosong di awal).
- Tiap skill = satu entri dengan label sumber + tanggal, supaya mudah dibandingkan dengan skill bawaan.

### Format 1 entri skill
```
### skill: <nama-skill>
- Sumber: lokal (dibuat client) · Tanggal: <YYYY-MM-DD>
- Tujuan: <1 kalimat — skill ini buat apa>
- Faktor yang dicakup: <mis. whitehat+blackhat / Ahrefs / ribuan domain / backlink jangka-panjang>
- Instruksi: <langkah/aturan yang AI ikuti saat skill ini dipanggil>
- Catatan: <batasan, hal yang gampang salah>
```

### Langkah saat client BIKIN skill (ngeprompt "skill SEO ...")
1. Konfirmasi singkat nama + tujuan + faktor (kalau ambigu).
2. Tulis/tambah entri ke `docs/SKILLS_LOCAL.md` pakai format di atas.
3. Kalau namanya sama dengan skill bawaan kit → kasih tahu sekarang juga (lihat "bentrok" di bawah).
4. Konfirmasi tersimpan + cara memanggilnya.

### Langkah saat client PANGGIL skill (sebut namanya)
1. Cari entri di `docs/SKILLS_LOCAL.md`.
2. Kalau ADA versi lokal + ADA versi bawaan senama → **bentrok** (lihat di bawah).
3. Jalankan instruksi skill — tetap tunduk §8/§8.1/§8.2 (keamanan + anti-injeksi + anti-halusinasi) + bahasa non-programmer §2.1.

### Saat BENTROK nama (lokal vs bawaan/upstream)
- **Default: lokal menang** (§14 per-proyek menimpa global).
- **WAJIB lapor inline** + tabel perbandingan ringkas:

| | Punyamu (lokal) | Bawaan lintasAI |
|---|---|---|
| Tanggal | `<tgl>` | `<tgl/versi kit>` |
| Fokus | `<...>` | `<...>` |
| Cakupan | `<...>` | `<...>` |

- Tawarkan: [1] pakai lokal (rekomendasi, default) — punyamu sendiri menang sesuai aturan per-proyek, tidak menimpa kerjaanmu · [2] pakai bawaan · [3] gabung (AI usulkan entri gabungan).
- **JANGAN** menyatakan pemenang mutlak — rekomendasi menyesuaikan tujuan project (§1.1 anti-asal-setuju).

### Saat UPDATE kit membawa skill bawaan senama
- Alur update §4.5 WAJIB **lapor**: "skill 'X' ada versi bawaan baru; kamu punya versi lokal."
- Tawarkan: [1] pertahankan lokal (rekomendasi, default) — paling aman, kerjaanmu tidak hilang/ketimpa · [2] lihat beda dulu · [3] gabung. **JANGAN timpa `docs/SKILLS_LOCAL.md` diam-diam.**

### Larangan
- Skill kustom TIDAK menghapus/melonggarkan aturan keamanan + anti-halusinasi. Skill = instruksi tambahan, bukan izin melanggar pagar.
- JANGAN ganti skill lokal client tanpa izinnya (anti-timpa-diam-diam).

---


## 8.3 Trusted Repo Auto-Detect (GPG Verification Skip) + Audit Log

> Versi 1 · 2026-06-08 · ditambahkan v1.5.5

### Konteks: kenapa ini ada

Sebelumnya `update-kit.ps1` selalu jalankan `git verify-tag` untuk validasi GPG signature setiap release. Ini bagus secara teori — tapi di praktek menimbulkan masalah UX kritis untuk staff IT non-programmer:

1. **Pubkey owner belum di-import** di mayoritas mesin staff → `git verify-tag` selalu gagal → warning `[FAIL] Tag bukan GPG-signed valid` muncul tiap update.
2. **Tanpa `-AllowUnsignedTag`** → update aborted fail-closed. Staff stuck, lapor owner, owner debug pubkey setup → friction tinggi.
3. **Dengan `-AllowUnsignedTag`** → bypass aktif, tapi warning tetap muncul → security theater (staff ignore warning karena selalu ada).

### Filosofi: layered trust, bukan single-point

Kit pakai 3-layer source integrity:

| Layer | Purpose | Bypass |
|---|---|---|
| **1. HTTPS + TLS** | Transport integrity (tidak ada MITM saat clone) | Tidak bisa (built-in git) |
| **2. RepoUrl allowlist** (`$allowedRepoUrls`) | Source authenticity (clone dari mana) | `-AllowUntrustedRepo` (warn + audit) |
| **3. GPG verify-tag** | Author authenticity (siapa yang sign release) | `-AllowUnsignedTag` (warn + audit) atau trusted repo auto-skip |

Trusted repo whitelist = **defense-in-depth optimization**, BUKAN trust reduction. Untuk owner repo resmi (`github.com/ojokesusu/lintasAI`), Layer 1 + Layer 2 sudah provide source integrity yang cukup untuk staff IT non-programmer. GPG layer di-skip secara explicit + transparent (audit log).

### Trusted repo whitelist (default + override)

Default whitelist hardcoded di `update-kit.ps1`:

```powershell
$TrustedRepos = @(
    'https://github.com/ojokesusu/lintasAI.git',
    'https://github.com/ojokesusu/lintasAI',           # tanpa .git suffix
    'git@github.com:ojokesusu/lintasAI.git'            # SSH format
)
```

Override via environment variable (comma-separated) untuk fork private atau mirror tepercaya:

```powershell
# Sebelum run update-kit.ps1, set env var:
$env:LINTASAI_TRUSTED_REPOS = 'https://github.com/mycompany/lintasAI-fork.git,https://gitlab.mycompany.com/it/lintasAI.git'
.\.claude-kit\update-kit.ps1
```

URL normalization: case-insensitive, trailing `/` dan `.git` di-strip sebelum compare. Artinya 3 URL ini dianggap sama:
- `https://github.com/ojokesusu/lintasAI.git`
- `https://github.com/ojokesusu/lintasAI/`
- `https://GitHub.com/ojokesusu/lintasAI`

### Workflow eksekusi

```
[1] Step 2b dimulai (GPG verify block)
[2] Test-LintasTrustedRepo -RepoUrl $RepoUrl
    |- TRUE (match whitelist):
    |  → Print "[OK] Repo URL: ... (trusted owner repo, GPG check skipped)"
    |  → Audit log: gpg-check-skipped
    |  → Lanjut ke Step 3
    |
    |- FALSE (di luar whitelist):
       → Jalankan logic GPG verify existing (resolve tag → verify-tag)
       → Sukses: print [OK] + audit log "gpg-check-passed"
       → Gagal + no -AllowUnsignedTag: throw fail-closed + audit log "gpg-check-failed"
       → Gagal + -AllowUnsignedTag: warn + lanjut + audit log "gpg-check-bypassed"
```

### Audit log (`.audit-log`)

Lokasi: `<kitDir>/.audit-log` (di `.claude-kit/.audit-log` dalam project user, atau `.audit-log` di root saat dipakai di kit repo sendiri).

Format per baris (ISO 8601 UTC timestamp):

```
<TIMESTAMP> | <SOURCE> | <ACTION> | <DETAIL>
```

Contoh entries:

```
2026-06-08T14:23:11Z | update-kit.ps1 | gpg-check-skipped | repo=https://github.com/ojokesusu/lintasAI.git branch=main reason=trusted-repo-whitelist
2026-06-08T15:01:42Z | update-kit.ps1 | gpg-check-passed | repo=https://github.com/ojokesusu/lintasAI.git tag=v1.5.1
2026-06-09T09:15:33Z | update-kit.ps1 | gpg-check-bypassed | repo=https://github.com/myfork/lintasAI.git tag=v1.5.2 reason=AllowUnsignedTag-flag UNSAFE=true
```

Append-only, plain text supaya bisa di-grep/parse pakai standard tools. **Tidak di-rotate otomatis** (volume entry kecil, retention manual via owner kalau perlu).

### Catatan keamanan

- **Audit log = local only**. Tidak di-commit (`.audit-log` ditambah ke `.gitignore`).
- **Audit log gagal != fatal**. Kalau disk full / permission issue, write gagal di-warn tapi update flow lanjut (audit transparency != availability requirement).
- **Owner repo paksa GPG verify**: kalau owner mau enforce GPG strict mode walau RepoUrl trusted, set `$env:LINTASAI_TRUSTED_REPOS = ''` (kosongin override) DAN hapus entry default dari `$TrustedRepos` di local fork.
- **Whitelist bukan substitute untuk allowlist** (`$allowedRepoUrls` di line 454). Dua mekanisme jalan paralel — allowlist gate clone source, trusted whitelist gate GPG skip.

### Trade-off divisi

- **Security**: trust shifted dari GPG ke HTTPS+TLS+GitHub branch protection. Acceptable untuk owner repo resmi; RISKY kalau staff salah set `LINTASAI_TRUSTED_REPOS` ke URL fork yang di-compromise.
- **UX (staff IT non-programmer)**: zero warning palsu untuk update normal dari owner repo. Friction turun dari "lapor owner debug pubkey" ke "update mulus".
- **Audit/Compliance**: full transparency via `.audit-log` — setiap skip terdokumentasi dengan timestamp + reason. Owner bisa review periodic.
- **DevOps**: `LINTASAI_TRUSTED_REPOS` env var memungkinkan CI runner pakai fork mirror internal tanpa modify script.

---

## 14.1 Konvensi UI Choice & Popup (UNIFIED) — DETAIL on-demand

> Dipindah dari `CLAUDE_universal_v1.md` §14.1 (tiering hemat token, v1.5.20). Dibaca AI saat **menyusun popup/pilihan** di workflow (JALANKAN_KIT/audit/update/split-repo). Inti load-bearing tetap di stub always-on `CLAUDE_universal_v1.md` §14.1. Format ini JUGA di-enforce di kode `lib/popup-helpers.ps1`.

Tiap kali ada pilihan (Read-Host console, `Show-LintasChoicePopup` GUI, popup interaktif di prompt MD), WAJIB ikuti 8 aturan ini. Tujuan: hilangkan cognitive load buat staff non-programmer dari format yang bervariasi ([1]/[2] square bracket, (1)/(2) parens, [A]/[B] letter, (Y/N) Unix-style, mix bracket dalam same file).

### 8 Aturan Wajib

- **RULE-1 (Numbered choices WAJIB)**: Setiap pilihan utama HARUS pakai angka berurut dalam square bracket `[1] [2] [3] ...`. TIDAK BOLEH skip nomor (mis. `[1] [3] [4]`), TIDAK BOLEH pakai huruf `[A] [B] [C]` untuk pilihan utama, TIDAK BOLEH pakai parenthesis `(1) (2) (3)`. Alasan: konsistensi visual lintas-file + tidak ada gap yang bikin user bingung kayak `[a]/[c]/[d]` tanpa `[b]`.

- **RULE-2 (Default marker eksplisit)**: Pilihan default WAJIB tag `(default)` inline di label. Pilihan yang AI rekomendasikan WAJIB tag `(disarankan)` — **bentuk Indonesia = standar tampilan ke user (v1.12.0)**; bentuk lama `(recommended)` masih DIKENALI sebagai sinonim di file lama, tapi teks-tampil baru/yang diedit WAJIB pakai `(disarankan)`. Boleh combine `(disarankan, default)` untuk pilihan yang sekaligus default + AI rekomendasi. Untuk destructive ops (delete, force-push, schema migration), default WAJIB pilihan paling AMAN (skip/cancel/no), tag `(default, safe choice)`. JANGAN andalkan capitalization Unix-style (Y/n vs y/N) sebagai marker default — terlalu cryptic untuk staff non-programmer.

- **RULE-3 (Special non-numbered options)**: Opsi escape/meta BOLEH pakai text label dalam square bracket BUKAN angka — whitelist: `[skip]` (lewati step ini), `[cancel]` (batalkan flow penuh), `[help]` (jelaskan dulu sebelum pilih), `[back]` (kembali ke step sebelumnya), `[stop]` (hentikan workflow, owner review dulu). Special label SELALU ditaruh di posisi terakhir setelah pilihan bernomor. TIDAK BOLEH pakai `(N)` atau `(X)` sebagai placeholder ambigu.

- **RULE-4 (Format inline single-line)**: Untuk pilihan pendek (label <40 char total), pakai format inline dipisah ` / `: `Pilihan: [1] Option A (rekomendasi) / [2] Option B / [3] Option C / [skip] Lewatkan`. Untuk pilihan panjang (label >40 char atau >4 pilihan), pakai format multi-line dengan indent 2 spasi:
  ```
  Pilihan:
    [1] Option A long description (rekomendasi, default)
    [2] Option B with detailed explanation
    [3] Option C
    [skip] Lewatkan step
  ```

### RULE-4b: Recommended FIRST (Posisi [1] Wajib untuk Default)

**Aturan inti**: Kalau ada option dengan marker `(rekomendasi)`, `(rekomendasi, default)`, `(disarankan)`, `(recommended)`, `⭐ DEFAULT`, atau `RECOMMENDED`, option tersebut WAJIB ditempatkan di posisi `[1]`. Order option lain disusun dari **rekomendasi paling kuat → paling lemah** (bukan urutan historis / alfabetik / arbitrary).

**Pengecualian (safety-by-design)**: Untuk popup destructive operation (auto-flatten folder, supply-chain risk seperti clone repo tidak terdaftar, update tanpa version check, migration plan execution, split repo execution), option "safe choice" / "stop, owner review" SENGAJA ditaruh di posisi `[2]` atau lebih bawah. Tujuannya: paksa user ketik `1` eksplisit untuk lanjut destructive op, sehingga Enter/default = aman (no-op atau stop). Pengecualian ini WAJIB ditandai dengan komentar inline `(default, safe choice)` atau `[RECOMMENDED, default]` di posisi yang sengaja non-[1].

**Special keys**: Token non-numeric seperti `[stop]`, `[skip]`, `[cancel]`, `[help]`, `[back]` WAJIB tetap di posisi terakhir (sesuai konvensi `popup-helpers.ps1` whitelist RULE-3), tidak ikut RULE-4b reorder.

**Dynamic popup (project-context aware)**: Untuk popup yang option-nya berubah sesuai project state (mis. `JALANKAN_KIT.md` Popup #2 Project Type, atau popup yang nawarin Quick Wins items dari hasil audit), AI WAJIB auto-detect project state (size, team count, stack maturity, audit findings) lalu re-order options supaya yang paling relevan untuk konteks user ditempatkan di `[1]`. Hardcoded order di file template hanya jadi fallback kalau auto-detect gagal.

**Alasan**: Staff non-programmer dilatih trust posisi `[1]` sebagai default safe choice — tekan Enter = ikuti rekomendasi senior. Kalau recommended terjebak di `[3]` atau `[4]`, staff yang buru-buru bakal pilih `[1]` yang justru bukan rekomendasi → friction onboarding naik + risiko salah konfigurasi naik. RULE-4b memastikan konvensi "Enter = aman + recommended" konsisten lintas-prompt.

**Audit trail**: Setiap reorder per RULE-4b di file existing WAJIB dicatat di commit message dengan body `RULE-4b: reorder <file>:<line> — '<recommended_label>' [N]→[1]` supaya history transparan.

- **RULE-5 (Confirmation line WAJIB di akhir)**: Setiap popup choice HARUS ditutup dengan baris konfirmasi eksplisit: `Default (Enter/kosong) -> [N] <label_default>`. Tujuan: telegraph default behavior untuk user yang skip respond. Untuk popup tanpa default (mis. security-critical), tulis: `TIDAK ADA default — wajib pilih [1] sampai [N] atau [cancel]`.

- **RULE-6 (Security-sensitive popup wajib RISK telegraph)**: Untuk operasi destructive/security-sensitive (delete, manifest unsigned, force-overwrite, push prod), message body WAJIB include: (a) RESIKO eksplisit dalam 1 kalimat, (b) preview konkret (count + sample nama file kalau bulk), (c) guidance `Kalau ragu, pilih [cancel] / [skip]`. Default WAJIB pilihan paling aman (`[skip]` atau `[cancel]`) dengan tag `(default, safe choice)`.

- **RULE-7 (Konsistensi lintas-medium console + GUI)**: Console `Read-Host` prompt dan GUI popup (`Show-LintasChoicePopup`) WAJIB pakai label string yang IDENTIK — dari single source of truth (array `$Options` dengan Label+SpecialKey+Recommended paired). Jangan ada drift antara console fallback vs GUI popup. Untuk binary Yes/No yang sederhana, BOLEH map ke `Show-LintasYesNoPopup` native (return `'Yes'`/`'No'`) TAPI label dalam message body tetap pakai konvensi nomor: `Lanjut hapus? [1] Yes / [2] No (default, safe choice)`.

- **RULE-8 (Popup klik dulu, teks cadangan — v1.11.0)**: Untuk popup Tipe A (pertanyaan AI ke user di chat), kalau harness menyediakan tool popup-pilihan native (di Claude Code: `AskUserQuestion` — kotak pilihan yang BISA DIKLIK), AI **WAJIB** render lewat tool itu. Sub-aturan:
  - **(a) Bentuk**: 1 pertanyaan per popup; label singkat, detail panjang masuk `description` tiap opsi; **opsi rekomendasi WAJIB di posisi PERTAMA + akhiran `(rekomendasi)`** (sinonim `(disarankan)` = sama makna) — **`description`-nya WAJIB memuat alasan singkat non-programmer KENAPA direkomendasikan** (mis. "paling aman, tidak mengubah apa pun"). JANGAN ganti jadi "(Recommended)" Inggris.
  - **(b) Kapasitas**: maks **4 opsi UTAMA**. Opsi meta (`[skip]`/`[cancel]`/`[help]`) TIDAK dihitung dan JANGAN jadi opsi klik tersendiri — user pakai "Other" (ketik token-nya). Opsi utama >4 → pecah jadi 2 pertanyaan. Multi-pilih → pakai mode multi-pilih tool; daftar terbuka/panjang → tanya teks bebas (bukan popup pilihan).
  - **(c) Tanpa Enter-default**: mode klik tidak punya default — user wajib klik. Opsi default mode-teks dipindah ke posisi PERTAMA + "(rekomendasi)". Khusus **popup destruktif/berisiko** (mode teks sengaja taruh opsi aman bukan di [1]): di mode klik **opsi AMAN yang PERTAMA + "(rekomendasi)"**, opsi berisiko paling bawah — satu klik salah lebih gampang daripada salah ketik.
  - **(d) Default dinamis menang**: kalau popup punya auto-deteksi (RULE-4b dynamic re-order), jalankan deteksi DULU, taruh hasilnya sebagai opsi pertama "(rekomendasi)". Urutan kanonik = cadangan kalau deteksi gagal.
  - **(e) Fallback**: blok teks `[1]/[2]/[3]` di file prompt = isi kanonik + fallback, dipakai HANYA saat tool tak tersedia (harness lain / tool error). **JANGAN render dobel** (popup klik + blok teks sekaligus). RULE-1..7 tetap berlaku untuk ISI opsi di kedua mode.
  - **(f) Bahasa tampilan WAJIB awam (v1.12.0)**: saat merender popup (mode klik MAUPUN teks), AI WAJIB menerjemahkan jargon mentah yang masih nyangkut di blok kanonik ke bahasa non-programmer (per §2.1) — makna, jumlah, dan nomor opsi TIDAK berubah. Blok kanonik = sumber MAKNA, bukan izin menampilkan jargon apa adanya.
  - **Asal-usul**: feedback owner 2026-06-12 — blok teks panjang ketik-angka TIDAK terasa "popup" buat non-programmer; yang diharapkan = klik. (f) menyusul di hari yang sama: "semua output saat lintasAI dipakai wajib bahasa awam".

### Quick Reference Table

| Format | Kapan dipakai | Contoh |
|---|---|---|
| Inline single-line | <=4 opsi, label <=40 char | `Pilihan: [1] Yes / [2] No (default, safe choice)` |
| Multi-line indent 2 | >4 opsi atau label panjang | Format multi-line di RULE-4 |
| Tag `(default)` | Default biasa (non-destructive) | `[1] Yes / [2] No (default)` |
| Tag `(rekomendasi)` | AI rekomendasikan, bukan default | `[1] Yes (rekomendasi) / [2] No` |
| Tag `(rekomendasi, default)` | Default + AI rekomendasi | `[1] Yes (rekomendasi, default) / [2] No` |
| Tag `(default, safe choice)` | Destructive ops, safest default | `[1] Yes / [2] No (default, safe choice)` |

### Special Label Whitelist

| Label | Arti |
|---|---|
| `[skip]` | Lewati step ini, lanjut step berikutnya |
| `[cancel]` | Batalkan flow penuh |
| `[help]` | Jelaskan dulu sebelum pilih |
| `[back]` | Kembali ke step sebelumnya |
| `[stop]` | Hentikan workflow, owner review dulu |

### Contoh CORRECT vs WRONG

| Rule | ❌ WRONG | ✅ CORRECT |
|---|---|---|
| RULE-1 | `Pilih [a]/[c]/[d]` (skip b) | `Pilih [1] / [2] / [3]` |
| RULE-1 | `Pilih (1)(2)(3)` (parens) | `Pilih [1] / [2] / [3]` |
| RULE-2 | `Lanjut? (Y/n)` (cryptic) | `Pilih [1] Yes (default) / [2] No` |
| RULE-3 | `Pilih [N] untuk stop` (ambigu) | `[stop] Stop, owner review dulu` |
| RULE-4 | Inline 6 long options | Multi-line dengan indent 2 spasi |
| RULE-5 | (tidak ada confirmation line) | `Default (Enter/kosong) -> [2] No` |
| RULE-6 | `Hapus? (y/N)` (no risk telegraph) | `RESIKO: ... / Preview: ... / [1] Yes / [2] No (default, safe choice) / Kalau ragu pilih [2]` |
| RULE-7 | Console pakai `(y/N)`, GUI pakai `Yes/No` button | Console + GUI pakai label IDENTIK dari single source |

### Cross-Reference Helper Functions

3 helper function di `lib/popup-helpers.ps1` enforce konvensi ini di level helper sehingga caller TIDAK BISA salah format:

- **`Show-LintasNumberedChoicePopup`** — GUI popup numbered choice dengan auto-tagging default/recommended/special key. Wrapper di atas `Show-LintasChoicePopup`.
- **`Format-LintasChoiceLine`** — console Read-Host helper yang return formatted string (single source of truth). Pasangan untuk `Show-LintasNumberedChoicePopup` supaya console + GUI label IDENTIK (RULE-7).
- **`Show-LintasSecurityChoicePopup`** — specialized wrapper untuk destructive/security ops. Auto-prepend risk statement + preview + guidance per RULE-6. Throw error kalau caller pass DefaultIndex ke option destructive (force safe default).

Fungsi existing (`Show-LintasYesNoPopup`, `Show-LintasInputPopup`, `Show-LintasChoicePopup`, `Show-LintasInfoPopup`) DIPERTAHANKAN untuk backward compat. Call-site baru WAJIB pakai 3 helper baru di atas.

### Migration Tracker

ADR `docs/decisions/2026-06-08-unified-ui-choice-convention.md` (akan dibuat saat fork-able project pakai konvensi ini) track progress 22 call-site refactor (10 PS scripts + 12 MD prompts). Lihat CHANGELOG entry `v1.5.4` untuk daftar file yang sudah ter-update di kit upstream.

---

## 13. Glossary (rujukan on-demand)

> Dipindah dari `CLAUDE_universal_v1.md` §13 (hemat token always-load, v1.21.0). Dibaca AI saat perlu arti sebuah istilah. Istilah ke staff non-programmer: `docs/GLOSSARY_NON_PROGRAMMER.md`.

- **CLAUDE.md / AGENTS.md** - file aturan AI yang auto-load tiap sesi.
- **memory** - catatan internal AI yang auto-load lintas sesi.
- **tie-breaker** - aturan penentu saat dua aturan bentrok.
- **edge case** - kondisi pinggiran (input kosong, 0, null, network putus) yang sering bikin bug.
- **reuse** - pakai ulang kode yang sudah ada, bukan duplikasi.
- **least privilege** - beri akses sesedikit mungkin; default deny.
- **DoD (Definition of Done)** - checklist "selesai" yang harus lulus.
- **a11y** - *accessibility*, ramah disabilitas (label, kontras, keyboard).
- **boundary** - pintu masuk data ke proses (handler route, consumer queue, parser file).
- **atomik** - semua berhasil atau semua dibatalkan (transaction).
- **idempoten** - dijalankan 2x hasilnya sama (pakai unique key / cek dulu sebelum insert).
- **fallback** - rencana cadangan kalau cara utama gagal (mis. popup GUI gagal → otomatis pakai prompt teks console).
- **kontrak** - catatan singkat: data masuk apa, keluar apa, error apa, status code berapa.
- **IDOR** - ganti ID di URL untuk akses data orang lain.
- **XSS / SQLi / SSRF** - injection lewat HTML / SQL / paksa server fetch URL internal.
- **RLS (Row Level Security)** - aturan di DB siapa boleh baca/tulis baris mana.
- **kardinalitas tinggi** - banyak nilai unik (mis. email) - cocok di-index.
- **zero-downtime** - perubahan tanpa memutus user (pola expand-then-contract).
- **expand-then-contract** - tambah baru dulu → migrasi → hapus lama.
- **Refactoring** (*in-place*) - rapikan kode tanpa ubah struktur/perilaku (nama, hapus duplikat, pecah fungsi). Tetap 1 repo. = Tangga Refactor **Tingkat 1** (default). Detail: `LINTASAI_WORKFLOWS_v1.md` §4.2.
- **Modular Monolith** - 1 repo disusun jadi modul/paket terpisah-jelas (masih **1 repo**). Tangga Refactor **Tingkat 2**.
- **Repository Split / Polyrepo** - pisah 1 repo jadi beberapa repo (multi-repo). Tangga Refactor **Tingkat 3**. Lawan dari monorepo. BUKAN otomatis microservice.
- **Strangler Fig** - pola migrasi **bertahap**: cabut/ekstrak satu bagian sekali jalan, sistem lama tetap hidup sampai bagian baru terbukti. Lawan dari bongkar-total sekaligus (*big-bang*).
- **Conventional Commits** - standar pesan commit (`feat:`, `fix:`, dst).
- **OG (Open Graph)** - metadata preview link di WhatsApp/FB/Twitter.
- **CVE** - laporan publik kerentanan library.
- **lockfile** - file kunci versi dependency (`package-lock.json`, `pnpm-lock.yaml`).
- **skeleton** - placeholder abu-abu mirip layout asli saat loading. *(contoh: Tailwind `animate-pulse`)*
- **slug** - bagian URL deskriptif (mis. `/blog/aturan-ai`).
- **runbook** - dokumen langkah-demi-langkah saat insiden/rollback.
- **threat model** - daftar singkat: aset / attacker / mitigasi.
- **halusinasi AI** - AI ngarang fakta dengan confidence tinggi (mis. klaim file/fungsi ada padahal tidak). Mitigasi: seksi 8.2 Anti-Halusinasi Protocol.
- **bus factor** - berapa orang yang tahu cara kerja sesuatu. Bus factor = 1 berbahaya (kalau dia hilang, no one continues). Target sehat: >=2 per file CRITICAL. Detail seksi 7.7.
- **blast radius** - seberapa luas dampak kalau aksi salah (1 user vs 1.000 user kena, reversible vs irreversible).
- **reversibility** - seberapa cepat & mudah balikin ke state sebelumnya. `git revert` = high reversibility. `DROP TABLE` di prod = low reversibility (butuh restore backup).
- **adversarial verify** - sangkal klaim sendiri sebelum kirim. Multi-agent skeptic pattern untuk audit / security review.
- **force citation rule** - "no quote = no claim". Klaim file/fungsi/config WAJIB verify via tool sebelum diutter.
- **humble mode** - default ke "tidak yakin" + hedge language kalau bukti < 100%. Lawan dari "overconfident".

---

## Referensi tambahan — dipindah dari CLAUDE_universal (hemat token always-load, v1.21.0)

### Reference Card — Translasi Jargon Inline Narration (23 jargon tersering)

> Dipindah dari `CLAUDE_universal_v1.md` §2.1. Pakai saat narasikan progress, BUKAN istilah mentah. Kalau jargon tak ada di sini, compose 3-layer analogi inline. Sumber umum: `docs/ANALOGI_LIBRARY.md`.

| ❌ Jargon mentah (jangan dipakai) | ✅ Bahasa non-programmer (pakai ini) |
|---|---|
| "Push GREEN" / "CI green" | "Berhasil kirim ke server pusat — semua test lulus (kayak upload foto ke Instagram sukses, tidak ada error)" |
| "Tag created (v1.2.3)" | "Penanda versi v1.2.3 sudah dibuat (kayak bookmark di browser — bisa balik kapan saja ke titik ini)" |
| "Commit OK" / "committed" | "Catatan perubahan tersimpan (kayak Save di Google Docs — perubahan kamu sekarang aman)" |
| "Pushed to origin/main" | "Sudah dikirim ke server utama tim (kayak upload file ke shared Google Drive tim)" |
| "PR opened" / "PR created" | "Permintaan review sudah dibuat (kayak share Google Docs + minta komen dari rekan kerja)" |
| "PR merged" | "Perubahan sudah disetujui + gabung ke versi utama tim (kayak Accept All Changes di Word)" |
| "Branch checked out" | "Sudah pindah ke versi terpisah (kayak duplicate file di Google Drive supaya bisa edit tanpa ganggu original)" |
| "Migration applied" | "Update struktur database sudah jalan (kayak rapi-rapi laci arsip — kolom baru ditambah, kolom lama dihapus)" |
| "Schema synced" | "Struktur database sekarang sama dengan kode (kayak Excel template sudah sinkron dengan rumus baru)" |
| "Build passed" | "Compile sukses — kode bisa dijalankan (kayak export PDF sukses tanpa error format)" |
| "Tests passed (42/42)" | "Semua 42 cek otomatis lulus (kayak quality control pabrik — semua produk lolos sebelum dikirim)" |
| "Lint OK" | "Cek standar penulisan kode lulus (kayak spell-check di Word — tidak ada tulisan aneh)" |
| "Dependency installed" | "Library tambahan sudah dipasang (kayak install plugin baru di Canva — fitur ekstra siap pakai)" |
| "Cache cleared" | "Memori sementara dibersihkan (kayak Ctrl+F5 di browser — paksa load ulang yang terbaru)" |
| "Server restarted" | "Server dijalankan ulang (kayak restart HP — supaya update kebaca)" |
| "Hot reload triggered" | "Perubahan otomatis muncul tanpa refresh manual (kayak Google Docs auto-update saat partner ngetik)" |
| "Rollback complete" | "Berhasil balik ke versi sebelumnya (kayak Ctrl+Z di Word — undo perubahan terakhir)" |
| "Backup created" | "Salinan cadangan sudah dibuat (kayak Save As + tambah tanggal di nama file)" |
| "Working tree clean / tree bersih" | "Semua perubahan sudah tercatat, tidak ada yang menggantung (kayak Google Docs tulis 'All changes saved' — aman)" |
| "Unpushed / 2 commits ahead" | "Sudah ke-Save di komputermu tapi BELUM dikirim ke server tim (kayak draft WhatsApp ngendon di HP, belum ditekan kirim)" |
| "Branch (jalur kerja terpisah)" | "Salinan kerja terpisah biar tidak ganggu versi utama tim (kayak duplicate file di Drive buat coret-coret dulu sebelum digabung)" |
| "Smoke test PASS" | "Tes cepat 'masih nyala / tidak mogok' lulus (kayak panasin mesin mobil sebentar sebelum jalan jauh)" |
| "Manifest" | "Daftar resmi semua file yang dipasang (kayak nota belanja — tahu apa yang masuk + bisa dikembalikan persis)" |

### Tinjauan Multi-Divisi §4.1 — skeleton format + tabel 15-lensa

> Dipindah dari `CLAUDE_universal_v1.md` §4.1 (aturan inti + 15 nama divisi tetap di sana). Skeleton + pertanyaan-per-lensa dibaca saat menyusun tabel.

Skeleton format wajib:

```markdown
---

## 🎯 Tinjauan Multi-Divisi (Menggunakan Analogi Non-Programmer)

| Divisi | Catatan |
|---|---|
| 🔧 **Backend** | <1-2 baris: temuan/saran + analogi non-programmer 3-layer, atau "-"> |
| 🎨 **Frontend** | ... |
| 🗄️ **Database** | ... |
| ☁️ **DevOps/SRE** | ... |
| 🔒 **Security/AppSec** | ... |
| ✅ **QA/Test** | ... |
| 👥 **UI/UX + a11y** | ... |
| 📊 **Product** | ... |
| 📈 **SEO/Marketing** | ... |
| 💼 **Business** | ... |
| 🤖 **ML/AI** | ... |
| ⚖️ **Legal/Compliance** | ... |
| 🤔 **Adversarial Reviewer** | <WAJIB diisi code change/arch/refactor — sangkal klaim sendiri, bukti konkret yang dibaca, mana asumsi> |
| 🔄 **Reversibility** | <WAJIB — kalau salah, berapa menit rollback + analogi tools, berapa user kena, backup ada> |
| 📚 **Knowledge Transfer** | <WAJIB — staff penulis resign besok, ada docs/komentar cukup? Bus factor >=2?> |
```

Pertanyaan khas per lensa (15):

| Divisi | Pertanyaan Khas |
|---|---|
| **Backend** | "Logika benar? API design konsisten? Idempoten? Edge case ditangani?" |
| **Frontend** | "State management bersih? Render performant? Component reusable? 4 state UI ada?" |
| **Database** | "Query efisien? Index ada? Migration aman? RLS policy benar? N+1 ada?" |
| **DevOps/SRE** | "Deploy aman? Rollback strategy ada? Monitoring/log struktur? Cost terkontrol?" |
| **Security/AppSec** | "Auth+authz benar? Secret leak? OWASP coverage? Input sanitized di boundary?" |
| **QA/Test** | "Happy path + edge case ditest? Regression risk? Manual test alur kritis?" |
| **UI/UX + a11y** | "Flow jelas? Contrast cukup? Keyboard nav? Screen reader friendly? Loading/error state?" |
| **Product** | "User benar-benar butuh ini? Scope creep? Success metric apa? Prioritas masuk akal?" |
| **SEO/Marketing** | "Discoverable? Core Web Vitals OK? Meta tag benar? Copy clear & persuasive?" |
| **Business** | "ROI? Cost vs value? Risk tolerance? Stakeholder buy-in?" |
| **ML/AI** | "Model bias? Data quality? Hallucination risk? Prompt injection? Cost token?" |
| **Legal/Compliance** | "PII handling? GDPR/UU PDP? Audit log? Retention policy? Consent?" |
| **🤔 Adversarial Reviewer** | "Sangkal solusi sendiri. Bukti konkret (file:line)? Mana asumsi? Kalau salah, di mana? Verified atau cuma sounds right?" |
| **🔄 Reversibility** | "Kalau salah, berapa menit rollback? Berapa user/record kena? Backup teruji? Reversible (git revert) atau irreversible (DROP TABLE)?" |
| **📚 Knowledge Transfer** | "Staff penulis resign besok, ada docs cukup? Komentar WHY ditulis? Bus factor >= 2?" |

---