speexor 0.1.1 → 0.2.1

package/docs/PRD06.md

@@ -0,0 +1,125 @@
+# PRD06: Gap Analysis Menyeluruh & Rencana Pengembangan Lanjutan — Speexor
+
+**Codename:** Speexor — Documentation Integrity & Execution-Readiness Pass
+**Versi:** 6.0 — Audit lintas-dokumen (PRD01–PRD05 + 14 file pendukung) dan rencana pengembangan berikutnya
+**Penulis:** Aditya (dengan bantuan Claude)
+**Tanggal:** 30 Juni 2026
+**Status:** Draft untuk validasi sebelum eksekusi
+
+> Dokumen ini **bukan** PRD fitur baru di atas tumpukan v1–v5. Ini adalah audit generasi-ke-2: PRD05 sudah mengaudit PRD01–04 dan memperbaiki banyak hal (rebrand, sandboxing, approval model, dst). Dokumen ini mengaudit **seluruh repositori dokumentasi** — termasuk PRD05 sendiri dan 14 file pendukung (README, ARCHITECTURE, API-REFERENCE, SECURITY, TESTING, dll) — untuk inkonsistensi yang muncul _setelah_ v5 ditulis, file yang rusak/kosong, dan klaim yang tidak match antar dokumen. Bagian kedua dokumen ini adalah pipeline pengembangan konkret untuk fase berikutnya.
+
+---
+
+## Bagian A — Temuan Audit (Gap & Masalah)
+
+### A.1 Temuan Kritis (blocking, harus diperbaiki sebelum lanjut development)
+
+| #      | Temuan                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Lokasi                                                      | Dampak                                                                                                                                                                                      |
+| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **C1** | **`PRD03.md` kosong (0 byte, 0 baris).** Seluruh rantai dokumen mengasumsikan kontinuitas v1→v2→v3→v4→v5, tapi v3 hilang total. PRD04 dan PRD05 menyebut diri "dibangun di atas v1, v2, dan v3" tanpa pernah menjelaskan apa isi v3.                                                                                                                                                                                                                                                                                                                                                                                                                              | `PRD03.md`                                                  | Tinggi — rantai keputusan produk terputus; tidak ada yang tahu fitur/keputusan apa yang lahir di v3 sebelum v4 dimulai. Semua FR di PRD04 yang merujuk "per v3 §x" tidak bisa diverifikasi. |
+| **C2** | **`SECURITY-DEFAULTS.md` tidak pernah dibuat**, padahal dirujuk sebagai dependency selesai di 5 tempat berbeda (ROADMAP M22c "✅ Done"-adjacent, SUMMARY.md Quick Links, CHANGELOG 0.2.0 "Added", PRD05 FR-94, PRD05 M22c milestone). CHANGELOG bahkan menulis "5 Architecture Decision Records di `docs/adr/`" dan SUMMARY menautkan `./docs/adr/` — folder ini juga tidak ada di upload manapun.                                                                                                                                                                                                                                                                | SUMMARY.md, ROADMAP.md, CHANGELOG.md, PRD05.md              | Tinggi — dokumentasi mengklaim sesuatu sudah selesai (✅ Done) padahal artefaknya tidak eksis. Ini "phantom deliverable".                                                                   |
+| **C3** | **Sandbox model kontradiksi yang belum benar-benar selesai.** PRD05 §"Fix" (sekitar baris 52-53) secara eksplisit mengoreksi PRD04 FR-72 bahwa `worker_threads` BUKAN security boundary, dan merekomendasikan `isolated-vm`/container/VM. CHANGELOG 0.2.0 menulis "IsolatedSandbox reimplemented with `node:vm` (not worker_threads) for true security boundary" — tapi `node:vm` **juga bukan security boundary yang aman** (dokumentasi Node.js sendiri secara eksplisit memperingatkan `vm` module tidak aman untuk menjalankan kode tidak tepercaya). Jadi "perbaikan" di CHANGELOG mengganti satu kesalahan teknis dengan kesalahan teknis lain yang setara. | CHANGELOG.md vs PRD05.md                                    | Tinggi — ini klaim keamanan yang salah, dipakai untuk menjalankan kode AI-generated dari agent pihak ketiga. Berisiko nyata jika diimplementasikan apa adanya.                              |
+| **C4** | **Versi config schema tidak konsisten.** README.md contoh config memakai `version: "1"`. ARCHITECTURE.md juga memakai `version: "1"`. Tapi PRD04 menulis manifest field `"speexorApiVersion": "^4.0.0"`, dan API-REFERENCE.md (dokumen "final"/konsolidasi) menulis skema config dengan `version: "5"`. Tidak ada migration note yang menjelaskan kapan `version: "1"` di README harus jadi `"5"`, padahal FR-90 (config schema migration tooling) justru ada untuk menangani migrasi versi config — tapi README sendiri tidak pernah diperbarui mengikuti FR ini.                                                                                                | README.md, ARCHITECTURE.md, API-REFERENCE.md, PRD04.md      | Sedang-Tinggi — dokumen "cara mulai" (README) akan membuat user generate config yang sudah outdated relatif terhadap schema final.                                                          |
+| **C5** | **Branding/package scope tidak final dan saling tumpang tindih.** PUBLISH.md menyebut org npm `@speexjs` dan repo GitHub `github.com/superdevids/speexjs`. CONTRIBUTING.md juga clone dari `speexjs.git`. Tapi README, CHANGELOG, ROADMAP, PRD04, PRD05 semua memakai scope `@speexor/*` (`@speexor/sdk`, `@speexor/ext-*`). Tidak pernah dijelaskan: apakah `speexjs` adalah nama **monorepo/organisasi**, dan `speexor` adalah nama **package/produk** di dalamnya — atau ini sisa rebrand yang belum dibereskan (mirip kasus Konduktor→Speexor di PRD05 yang sudah diaudit, tapi audit itu sendiri melewatkan layer `speexjs`).                                | PUBLISH.md, CONTRIBUTING.md vs README/CHANGELOG/PRD04/PRD05 | Sedang — risiko publish ke scope npm yang salah, broken link di docs, dan kebingungan kontributor baru.                                                                                     |
+
+### A.2 Temuan Mayor (penting, tapi tidak langsung blocking)
+
+| #      | Temuan                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Lokasi                                                 | Dampak                                                                                                                                      |
+| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| **M1** | **Test count diklaim presisi ("19 test files, ~320 tests") di 3 dokumen berbeda (README, SUMMARY, CHANGELOG) padahal REFACTOR-LOG.md — log historis yang seharusnya jadi sumber kebenaran proses — menyatakan eksplisit "No test files yet (vitest configured but no tests written)" sebagai entri terakhirnya.** Tidak ada entri REFACTOR-LOG susulan yang mencatat _kapan_ 320 tes itu ditulis. Untuk project yang baru "M0.1.0" dirilis di tanggal yang sama (2026-06-30) dengan rebuild dari nol, klaim 320 test yang presisi tanpa jejak proses patut dicurigai sebagai proyeksi/target, bukan fakta terukur.                                                                                                                                                                                                                                                                                               | README.md, SUMMARY.md, CHANGELOG.md vs REFACTOR-LOG.md | Sedang — risiko overclaiming readiness; kalau dipublikasikan sebagai status real, akan menyesatkan kontributor/user yang mengecek coverage. |
+| **M2** | **Tumpang tindih penomoran FR (Functional Requirement).** PRD04 memakai rentang FR-63 s.d. FR-82+ untuk fitur v4-nya. PRD05 lalu memakai FR-83 s.d. FR-97 untuk temuan auditnya sendiri — tapi PRD05 _juga_ memuat referensi balik ke "FR-22" (dari PRD02) dan "FR-39", "FR-72" tanpa namespace versi yang jelas (mis. "v2 FR-22" vs "v4 FR-72"). Karena FR-72 dipakai PRD04 untuk _sandboxing_, sementara dokumen lain merujuk FR-72 secara generik, ada ambiguitas penomoran lintas-versi yang akan menyulitkan traceability begitu jumlah PRD bertambah.                                                                                                                                                                                                                                                                                                                                                      | PRD02, PRD04, PRD05                                    | Sedang — tracing requirement→implementation akan rapuh; butuh ID requirement global yang tidak reset/tumpang tindih per dokumen.            |
+| **M3** | **Tech stack di PRD01 (fondasi yang menurut PRD02 "tetap berlaku") tidak sama dengan apa yang benar-benar dibangun.** PRD01 §10 secara eksplisit memilih **NestJS** untuk dashboard backend dan **Next.js** untuk dashboard frontend, plus **SQLite via Prisma** untuk state. Tapi REFACTOR-LOG.md mendokumentasikan keputusan sebaliknya: "Built-in HTTP Dashboard: Using Node.js built-in `http` module instead of Express/NestJS to keep dependencies minimal" dan "Synchronous File I/O for State: `SessionStore` uses `readFileSync`/`writeFileSync`" (bukan SQLite/Prisma). CHANGELOG 0.2.0 baru memperkenalkan SQLite (lewat Task Graph Persistence) — itu pun cuma untuk task graph, bukan general session store. Tidak ada PRD manapun yang secara eksplisit mencabut keputusan tech stack PRD01 §10; ini adalah _silent architecture drift_ yang hanya tercatat di REFACTOR-LOG, bukan di PRD manapun. | PRD01 §10 vs REFACTOR-LOG.md vs CHANGELOG.md           | Sedang — pembaca yang hanya baca PRD (bukan REFACTOR-LOG) akan punya ekspektasi stack yang salah total.                                     |
+| **M4** | **Monorepo layout di PRD01 §11 (banyak `packages/*` terpisah: `agent-opencode`, `tracker-github`, dst., masing-masing bisa diinstall independen sesuai FR-14) bertentangan dengan keputusan REFACTOR-LOG "Monorepo as Single Package: v1 lives in a single `speexor` package with internal module separation" dan "No Dynamic Plugin Loading: All built-in plugins are hardcoded in `loadAllPlugins()`."** FR-14 PRD01 eksplisit minta adapter sebagai package terpisah yang bisa diinstall independen (`@speexor/agent-opencode`, dst) — ini secara langsung berlawanan dengan desain final "hardcoded in loadAllPlugins()".                                                                                                                                                                                                                                                                                    | PRD01 FR-14 vs REFACTOR-LOG.md                         | Sedang — FR-14 belum pernah secara resmi di-deprecate, padahal implementasinya sudah menyimpang total.                                      |
+| **M5** | **CLI command set tidak sinkron antar dokumen.** API-REFERENCE.md (dianggap sumber kebenaran final, M22c "Documentation Consolidation") mendaftar command `speexor config validate` dan `speexor eval decisions`. ROADMAP.md menyebut command yang sama sebagai bagian M22b ("✅ Done" di SUMMARY milestone table). Tapi FAQ.md — dokumen yang seharusnya menjelaskan command ke pengguna baru — sama sekali tidak menyebut `task submit`, `ext search/install/list/update/remove`, `config validate`, atau `eval decisions`, padahal command-command itu sudah "Done" sejak v2/v4/v5. FAQ.md terlihat membeku di level command-set v1 (start, agent spawn, list, stop, logs, config-help).                                                                                                                                                                                                                      | FAQ.md vs API-REFERENCE.md vs ROADMAP.md               | Sedang — dokumen onboarding utama (FAQ) sudah jauh tertinggal dari fitur nyata produk.                                                      |
+| **M6** | **Dashboard "no telemetry/no cloud dependency, fully local-first" (SECURITY.md) belum direkonsiliasi dengan Extension Marketplace.** SECURITY.md §"Network Security" menulis "No telemetry or tracking" dan "No cloud dependency — fully local-first." Tapi fitur Extension Manager (CHANGELOG 0.2.0, README §"Extension Marketplace") secara desain butuh `marketplaceIndex` (GitHub-based registry) dan `speexor ext search <query>` yang network call ke registry eksternal. SECURITY.md belum diperbarui untuk mencantumkan exception ini sebagai _expected_ network behavior, sehingga klaim "fully local-first" sudah tidak akurat sejak fitur marketplace ditambahkan di 0.2.0, tanpa update SECURITY.md.                                                                                                                                                                                                 | SECURITY.md vs CHANGELOG.md / README.md                | Sedang — klaim keamanan/privasi yang sudah stale berisiko menyesatkan user yang menjadikan SECURITY.md acuan compliance.                    |
+| **M7** | **Approval/governance default belum 100% konsisten penamaan antara GLOSSARY dan API-REFERENCE.** GLOSSARY.md mendefinisikan "Approvals" sebagai _satu_ panel unifikasi (per FR-87) dan eksplisit menandai "Review Queue (deprecated name)". Tapi config schema di API-REFERENCE.md masih punya field terpisah `governance.autoApproveProposedTasks` dan `riskPolicy.autoApprove`/`requireApproval` sebagai dua blok config yang berbeda nama dan struktur (bukan field bersama di bawah satu namespace "approvals"), yang berpotensi membingungkan kontributor yang baru baca GLOSSARY lalu mengharapkan satu blok `approvals:` di YAML.                                                                                                                                                                                                                                                                         | GLOSSARY.md vs API-REFERENCE.md                        | Rendah-Sedang — bukan bug, tapi friksi pemahaman: istilah UI sudah disatukan, tapi representasi config belum mengikuti.                     |
+
+### A.3 Temuan Minor (kebersihan dokumentasi)
+
+| #      | Temuan                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Lokasi                   |
+| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| **m1** | `\r\n` (CRLF) line endings campur dengan `\n` (LF) lintas file — PRD01/02/04/05, CONTRIBUTING, PUBLISH, FAQ, SECURITY, dll memakai CRLF; README, ARCHITECTURE, API-REFERENCE, GLOSSARY, BENCHMARKS memakai LF. Tidak fatal, tapi akan memicu diff noise besar dan masalah lint di CI lintas-OS.                                                                                                                                                                                                                                                             | Hampir semua file        |
+| **m2** | BENCHMARKS.md seluruhnya berisi placeholder `—` (belum ada satupun angka terukur) padahal SUMMARY.md sudah menandai milestone yang relevan (M6 — "Polish & Testing") sebagai ✅ Done, dan ROADMAP juga menempatkan benchmark sebagai bagian Q3 2026 "Done". Target ada, baseline belum pernah dijalankan.                                                                                                                                                                                                                                                   | BENCHMARKS.md            |
+| **m3** | CHANGELOG mencantumkan dua versi `[0.1.0]` dan `[0.2.0]` dengan **tanggal rilis yang sama persis** (2026-06-30) — realistis untuk "all at once" docs generation, tapi tidak realistis sebagai catatan rilis sungguhan (artinya CHANGELOG ini belum pernah dipakai sebagai jurnal rilis asli, hanya backfill).                                                                                                                                                                                                                                               | CHANGELOG.md             |
+| **m4** | SUMMARY.md milestone table mencantumkan `M22a/M22b/M22c` (fix milestones dari v5) **sebelum** `M13 — Hardening & Cost Guard` secara penomoran, tapi keduanya ditandai sejajar tanpa urutan kronologis/dependency yang jelas terhadap M5–M12 yang sudah Done. Penomoran milestone (M0...M13, lalu M22a-c) melompat tanpa M14-M21 — celah penomoran ini tidak dijelaskan di manapun (apakah disengaja untuk reserved future milestones, atau sisa renumbering yang tidak rapi).                                                                               | SUMMARY.md, ROADMAP.md   |
+| **m5** | ROADMAP.md masih mencantumkan milestone M7 ("Recursive Task Decomposition") dan M9 ("Extension Marketplace") sebagai **upcoming** (belum dikerjakan, target Q4 2026/Q1 2027), padahal CHANGELOG 0.2.0 dan SUMMARY.md milestone table menandai kapabilitas yang sama (task decomposition di M7-PRD asli, extension manager) sebagai **sudah selesai** lewat milestone M7-M12 versi SUMMARY yang berbeda penomoran dari versi ROADMAP. ROADMAP dan SUMMARY pakai sistem penomoran M-number yang **berbeda untuk milestone yang sama**, tanpa cross-reference. | ROADMAP.md vs SUMMARY.md |
+| **m6** | GLOSSARY mendefinisikan istilah "Library" tidak konsisten — istilah ini didefinisikan di PRD04 §"Terminologi" (baris 72) sebagai "versioned, installable code dependency... at the Node.js package level", tapi GLOSSARY.md final (hasil konsolidasi M22c) **tidak memuat entri "Library" sama sekali**, padahal PRD04 eksplisit membedakannya dari "Plugin"/"Skill". Istilah hilang di proses konsolidasi.                                                                                                                                                 | PRD04.md vs GLOSSARY.md  |
+| **m7** | CODE-OF-CONDUCT.md dan CONTRIBUTING.md memakai email kontak yang sama (`opensource@superdevids.com`) — domain `superdevids.com` ini konsisten dengan identitas Aditya (`iniadittt`/SuperJS/`@superdevid/*`), tapi PUBLISH.md & CONTRIBUTING.md merujuk repo di organisasi GitHub `superdevids` sementara README tidak pernah menyebut org GitHub secara eksplisit — sebaiknya disamakan eksplisit di satu tempat (mis. README footer) supaya tidak harus disimpulkan dari email domain.                                                                     | Lintas file              |
+
+### A.4 Ringkasan Pola Masalah (root cause, bukan gejala satu-satu)
+
+1. **Tidak ada "source of truth" tunggal yang versioned.** Setiap PRD baru (v1→v5) menambah lapisan baru di atas lapisan sebelumnya secara aditif, tapi tidak ada proses _mandatory sync_ yang memaksa dokumen pendukung (README, ARCHITECTURE, FAQ, SECURITY, GLOSSARY) ikut diperbarui setiap kali sebuah PRD baru mengubah keputusan lama. M22c ("Documentation Consolidation") sudah mencoba ini sekali, tapi hanya menyentuh GLOSSARY + API-REFERENCE — README, FAQ, SECURITY, BENCHMARKS terlewat.
+2. **Klaim status "✅ Done" terlalu murah dipakai.** Banyak milestone ditandai selesai padahal artefak pendukungnya (SECURITY-DEFAULTS.md, docs/adr/, benchmark baseline, test suite yang terverifikasi) tidak benar-benar ada di upload. Ini pola "dokumentasi mendahului implementasi" yang wajar untuk draft PRD, tapi berbahaya begitu CHANGELOG/SUMMARY mulai mengklaimnya sebagai fakta rilis.
+3. **PRD05 sendiri (dokumen audit) tidak mengaudit dirinya sendiri/dokumen pendukung** — fokusnya murni ke PRD01-04, sehingga drift di README/FAQ/SECURITY/BENCHMARKS/PUBLISH/CONTRIBUTING tidak pernah masuk radar sampai audit ini (PRD06).
+4. **Penomoran (FR, milestone M-number) tidak global/append-only** sehingga setiap dokumen baru berisiko tabrakan ID atau loncatan tidak konsisten.
+
+---
+
+## Bagian B — Pipeline Pengembangan Lanjutan
+
+Pipeline ini dirancang untuk **dieksekusi solo oleh Aditya** (vibe coding + agent assistance), sejalan dengan filosofi v1 ("setup cepat, plugin-first, agent-agnostic") dan konsisten dengan apa yang sudah dibangun (bukan rombak total). Difase jadi 4 track yang bisa jalan semi-paralel.
+
+### Track 0 — Dokumentasi & Integritas (wajib duluan, ~1 minggu)
+
+| ID    | Item                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Output                                         |
+| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| T0-1  | Isi ulang `PRD03.md` (rekonstruksi retroaktif) atau **deprecate eksplisit**: tulis 1 paragraf di awal PRD04 yang menyatakan "v3 tidak pernah dipublikasikan terpisah, fitur-fiturnya digabung ke v4 §X" — pilih salah satu, jangan dibiarkan kosong.                                                                                                                                                                                                                       | PRD03.md terisi atau catatan deprecation resmi |
+| T0-2  | Buat `SECURITY-DEFAULTS.md` yang benar-benar berisi 2-layer model (Extension Permissions vs Action Risk Tiers) seperti dijanjikan FR-94.                                                                                                                                                                                                                                                                                                                                   | File baru                                      |
+| T0-3  | Buat `docs/adr/` dengan minimal 5 ADR riil: (1) pilihan worktree isolation, (2) keputusan sandbox model FINAL (lihat T0-4), (3) single-package vs multi-package monorepo, (4) SQLite vs JSON state store, (5) two-axis approval model.                                                                                                                                                                                                                                     | 5 file ADR                                     |
+| T0-4  | **Putuskan sandbox model final secara teknis benar** — bukan `worker_threads` (M22c klaim awal), bukan `node:vm` saja (klaim CHANGELOG 0.2.0). Opsi realistis: `isolated-vm` (V8 isolate sejati) untuk extension ringan, atau `child_process` dengan OS-level user/permission restriction untuk extension yang butuh akses shell. Dokumentasikan trade-off startup latency vs keamanan secara eksplisit, lalu update CHANGELOG dan FR-72/72(v4)/M22a dengan koreksi resmi. | Update CHANGELOG + ADR + FR correction note    |
+| T0-5  | Sinkronkan `version:` di README/ARCHITECTURE config example ke schema final (`"5"` atau apapun versi config schema aktual saat itu), dan jalankan `speexor config validate` sungguhan terhadap contoh tsb sebagai bukti.                                                                                                                                                                                                                                                   | README/ARCHITECTURE update                     |
+| T0-6  | Selesaikan ambiguitas branding `speexjs` (org/monorepo) vs `speexor` (package/produk) vs `speexjs.org` — tulis 1 paragraf definitif di README "Naming" dan terapkan konsisten ke PUBLISH.md & CONTRIBUTING.md.                                                                                                                                                                                                                                                             | README + PUBLISH + CONTRIBUTING update         |
+| T0-7  | Audit ulang FAQ.md supaya mencerminkan command-set aktual (`task submit`, `ext *`, `config validate`, `eval decisions`).                                                                                                                                                                                                                                                                                                                                                   | FAQ.md update                                  |
+| T0-8  | Tambahkan kalimat exception eksplisit di SECURITY.md §Network Security untuk Extension Marketplace (`marketplaceIndex` registry call), supaya klaim "fully local-first" tetap akurat dengan disclaimer jelas.                                                                                                                                                                                                                                                              | SECURITY.md update                             |
+| T0-9  | Normalisasi line ending (LF) lintas semua file `.md` via `.gitattributes` + format pass sekali.                                                                                                                                                                                                                                                                                                                                                                            | `.gitattributes` + reformat                    |
+| T0-10 | Perkenalkan skema penomoran requirement **global** (mis. `SPX-FR-001`, append-only, tidak reset per versi PRD) dan migrasikan referensi FR-1...FR-97 yang ada ke index global ini di dokumen baru `REQUIREMENTS-INDEX.md`.                                                                                                                                                                                                                                                 | File baru + mapping tabel                      |
+
+### Track 1 — Hardening Eksekusi (M13, lanjutan dari SUMMARY "🔄 In Progress")
+
+Fokus: menutup gap antara klaim "production-ready architecture" dan kenyataan implementasi yang masih minim test/benchmark riil.
+
+1. **Cost Guard enforcement nyata** — implementasikan `riskPolicy.budgetLimitUSD` benar-benar menghentikan agent (bukan hanya warning di 80%), dengan test integrasi yang memverifikasi halt di 100%.
+2. **Benchmark baseline riil** — jalankan skrip yang sudah ada di BENCHMARKS.md (`hyperfine`, `wrk`, `node benchmarks/store-throughput.js`) dan isi tabel "Benchmark Results History" dengan angka asli versi 0.2.0, bukan placeholder `—`.
+3. **Test suite audit** — verifikasi klaim "19 file / ~320 test" dengan menjalankan `pnpm test:coverage` sungguhan dan menempelkan output coverage report sebagai lampiran/link CI badge di README, supaya klaim M1 (lihat Bagian A.2) berubah dari "diklaim" jadi "terbukti".
+4. **Session store migrasi dari sync I/O ke async** — REFACTOR-LOG sudah menandai ini sebagai technical debt sejak v0.1.0; selesaikan sebelum jumlah agent paralel bertambah (relevan untuk target "≥10 agent aktif paralel" di NFR PRD01).
+5. **`getLiveStream()` implementasi nyata** — REFACTOR-LOG menandai ini "not implemented" di kedua runtime plugin (tmux & process); ini blocking untuk M8 (Real-Time Terminal) di ROADMAP.
+
+### Track 2 — Fitur Lanjutan (selaras roadmap M7/M8/M9/M10/M11 yang sudah didefinisikan)
+
+Tidak menambah scope baru di luar yang sudah direncanakan — fokus eksekusi prioritas berikut, urut dependency:
+
+1. **M8 — Real-Time Terminal** (WebSocket + xterm.js): bergantung langsung pada penyelesaian Track 1.5 (`getLiveStream`). Tanpa ini, Terminal Plugin (sudah didefinisikan interface-nya di API-REFERENCE) tetap kosong.
+2. **M9 — Extension Marketplace**: lanjutkan dari Plugin SDK yang sudah ada scaffold-nya (CHANGELOG 0.2.0), tapi **wajib menuntaskan T0-4 (sandbox model) dulu** sebelum mengizinkan instalasi extension pihak ketiga — urutan ini penting karena marketplace = permukaan serangan terbesar di seluruh sistem (menjalankan kode tak tepercaya dari registry eksternal).
+3. **Skill/CEO-Orchestrator integration** (Open Question #3 di PRD01, belum pernah dijawab di v2-v5): ini adalah diferensiasi besar yang relevan dengan ekosistem yang sudah dibangun Aditya (66-agent/268-skill CEO Orchestrator). Usulan: jadikan CEO Orchestrator skill-set sebagai _Extension_ resmi pertama di Marketplace (`@speexor/ext-ceo-orchestrator`) begitu T0/M9 selesai — bukan core dependency, supaya Speexor tetap agent-agnostic sesuai G4/non-goals.
+4. **M10 — Advanced Security & Compliance**: secret scanning di output agent (penting karena agent menulis & push kode otomatis — risiko kebocoran API key/token via commit otomatis belum dibahas eksplisit di SECURITY.md manapun).
+5. **M11 — Multi-Host**: tunda sampai Track 1 & 2.1-2.4 stabil; ini paling jauh dari kebutuhan solo-dev saat ini (target user primer di PRD01 §4 tetap "kamu sendiri").
+
+### Track 3 — Refactor Arsitektural (opsional, evaluasi cost/benefit dulu)
+
+| Opsi                                                                                                        | Kapan layak dilakukan                                                                                                                                                                                                                                                                                     |
+| ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Pecah dari single-package `packages/speexor` jadi multi-package sesuai FR-14 asli (per-adapter installable) | Hanya jika benar-benar akan open-source dan komunitas mulai kontribusi adapter baru secara aktif — sebelum itu, single-package lebih murah maintenance untuk solo dev (sejalan keputusan REFACTOR-LOG, M4 di atas tidak perlu "diperbaiki", cukup FR-14 di-deprecate resmi).                              |
+| Migrasi dashboard backend ke NestJS sesuai PRD01 asli                                                       | Tidak direkomendasikan — `http` module built-in sudah terbukti cukup (M4 Dashboard MVP "Done"); NestJS hanya menambah dependency tanpa kebutuhan teknis yang jelas saat ini. Sebaiknya PRD01 §10 di-superscript dengan catatan "superseded by REFACTOR-LOG 2026-06-30" daripada benar-benar dimigrasikan. |
+| SQLite penuh untuk seluruh state (bukan cuma Task Graph)                                                    | Layak setelah Track 1.4 (async I/O) selesai dan jumlah project/agent paralel terbukti butuh concurrency tulis tinggi (>100 writes/sec target di BENCHMARKS belum pernah diuji — uji dulu sebelum migrasi besar).                                                                                          |
+
+---
+
+## Bagian C — Prioritas Eksekusi (Ringkas)
+
+```
+Minggu 1       : Track 0 (T0-1 s.d. T0-10) — WAJIB, semua kerja lain bergantung pada dokumentasi yang konsisten
+Minggu 2-3     : Track 1 (Cost Guard, Benchmark riil, Test audit, Async store, getLiveStream)
+Minggu 4-6     : Track 2.1 (M8 Real-Time Terminal) → 2.2 (M9 Marketplace, gated oleh T0-4) → 2.3 (CEO Orchestrator extension)
+Minggu 7+      : Track 2.4 (M10 Security/Compliance), evaluasi Track 3 opsional
+```
+
+**Definition of Done untuk Track 0** (gate sebelum lanjut Track 1): tidak ada lagi file `.md` yang kosong, tidak ada lagi link mati (`SECURITY-DEFAULTS.md`, `docs/adr/`), tidak ada lagi klaim "✅ Done" tanpa artefak yang bisa diverifikasi, dan satu sumber kebenaran branding/versioning sudah ditulis eksplisit.
+
+---
+
+## Bagian D — Open Questions Baru (untuk Aditya, sebelum eksekusi Track 0)
+
+1. Apakah `PRD03.md` akan direkonstruksi (isi ulang dengan asumsi best-effort dari konteks PRD04), atau cukup dihapus dari rantai referensi dan ditandai "tidak pernah dipublikasikan"?
+2. Untuk sandbox model final (T0-4): apakah startup latency tambahan dari `isolated-vm`/container masih bisa diterima untuk workflow solo-dev kamu, atau prioritas tetap kecepatan dengan risiko keamanan yang didokumentasikan eksplisit (extension marketplace ditunda sampai sandbox benar)?
+3. Apakah nama organisasi final adalah `speexjs` (monorepo/brand payung, sejalan dengan `bjir.tech`/`@superdevid/*` sebagai pola penamaan ekosistem kamu yang lain) dengan `speexor` sebagai satu produk di dalamnya — atau `speexor` berdiri sendiri dan `speexjs` di PUBLISH/CONTRIBUTING adalah sisa nama lama yang harus diganti total?
+4. Integrasi CEO Orchestrator sebagai Extension resmi (Track 2.3) — apakah ini prioritas tinggi (karena jadi diferensiasi besar vs AO) atau tetap dijadikan exploratory setelah M9 stabil?

package/docs/SETUP.md

@@ -1,94 +1,94 @@
-# Speexor Setup Guide
-
-## Prerequisites
-
-- **Node.js** >= 18.0.0
-- **pnpm** (recommended) or npm
-- **Git** >= 2.30 (for `git worktree` support)
-- **GitHub CLI** (`gh`) — for tracker & SCM plugins (optional for local-only mode)
-- **tmux** >= 3.0 — for tmux runtime (macOS/Linux, optional with process fallback)
-- One or more AI coding agent CLIs:
-  - [OpenCode CLI](https://github.com/superdevids/opencode)
-  - [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
-  - [Aider](https://aider.chat/)
-  - [Codex CLI](https://github.com/openai/codex)
-
-## Installation
-
-```bash
-# Via npm
-npm install -g speexor
-
-# Or via pnpm
-pnpm add -g speexor
-
-# Or run from the monorepo
-cd speexjs
-pnpm install
-pnpm --filter speexor build
-```
-
-## Quick Start
-
-### 1. Initialize a project
-
-```bash
-cd /path/to/your/project
-speexor start https://github.com/username/repo.git
-```
-
-This will:
-- Create `speexor.config.yaml` with default configuration
-- Create `.speexor/` directory for worktrees and logs
-- Start the dashboard at `http://localhost:3000`
-
-### 2. Spawn an agent for a task
-
-```bash
-# Using a GitHub issue ID
-speexor agent spawn --task 42 --agent opencode
-
-# Using a custom task ID
-speexor agent spawn --task "feature-auth" --agent claude-code
-```
-
-### 3. Monitor progress
-
-```bash
-# Open dashboard in browser
-open http://localhost:3000
-
-# List active sessions
-speexor list
-
-# View agent logs
-speexor logs <session-id>
-```
-
-### 4. Stop a session
-
-```bash
-speexor stop <session-id>
-```
-
-## Configuration
-
-See `speexor config-help` for full schema reference, or refer to `examples/basic.yaml` in the package.
-
-## Plugin Architecture
-
-Speexor uses a 7-slot plugin architecture:
-
-| Slot | Purpose | Default Plugin |
-|------|---------|---------------|
-| **Agent** | AI coding agent adapter | OpenCode, Claude Code, Aider, Codex |
-| **Runtime** | Process execution environment | tmux (Unix), Process (Windows) |
-| **Workspace** | Code isolation strategy | Git Worktree |
-| **Tracker** | Task/issue source | GitHub Issues |
-| **SCM** | Git/PR operations | GitHub (gh CLI) |
-| **Notifier** | Alert channel | Desktop notifications |
-| **Terminal** | Live session viewer | Web (dashboard) |
-
-## Troubleshooting
-
-See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) for common issues.
+# Speexor Setup Guide
+
+## Prerequisites
+
+- **Node.js** >= 18.0.0
+- **pnpm** (recommended) or npm
+- **Git** >= 2.30 (for `git worktree` support)
+- **GitHub CLI** (`gh`) — for tracker & SCM plugins (optional for local-only mode)
+- **tmux** >= 3.0 — for tmux runtime (macOS/Linux, optional with process fallback)
+- One or more AI coding agent CLIs:
+  - [OpenCode CLI](https://github.com/superdevids/opencode)
+  - [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
+  - [Aider](https://aider.chat/)
+  - [Codex CLI](https://github.com/openai/codex)
+
+## Installation
+
+```bash
+# Via npm
+npm install -g speexor
+
+# Or via pnpm
+pnpm add -g speexor
+
+# Or run from the monorepo
+cd speexjs
+pnpm install
+pnpm --filter speexor build
+```
+
+## Quick Start
+
+### 1. Initialize a project
+
+```bash
+cd /path/to/your/project
+speexor start https://github.com/username/repo.git
+```
+
+This will:
+- Create `speexor.config.yaml` with default configuration
+- Create `.speexor/` directory for worktrees and logs
+- Start the dashboard at `http://localhost:3000`
+
+### 2. Spawn an agent for a task
+
+```bash
+# Using a GitHub issue ID
+speexor agent spawn --task 42 --agent opencode
+
+# Using a custom task ID
+speexor agent spawn --task "feature-auth" --agent claude-code
+```
+
+### 3. Monitor progress
+
+```bash
+# Open dashboard in browser
+open http://localhost:3000
+
+# List active sessions
+speexor list
+
+# View agent logs
+speexor logs <session-id>
+```
+
+### 4. Stop a session
+
+```bash
+speexor stop <session-id>
+```
+
+## Configuration
+
+See `speexor config-help` for full schema reference, or refer to `examples/basic.yaml` in the package.
+
+## Plugin Architecture
+
+Speexor uses a 7-slot plugin architecture:
+
+| Slot | Purpose | Default Plugin |
+|------|---------|---------------|
+| **Agent** | AI coding agent adapter | OpenCode, Claude Code, Aider, Codex |
+| **Runtime** | Process execution environment | tmux (Unix), Process (Windows) |
+| **Workspace** | Code isolation strategy | Git Worktree |
+| **Tracker** | Task/issue source | GitHub Issues |
+| **SCM** | Git/PR operations | GitHub (gh CLI) |
+| **Notifier** | Alert channel | Desktop notifications |
+| **Terminal** | Live session viewer | Web (dashboard) |
+
+## Troubleshooting
+
+See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) for common issues.

package/docs/TROUBLESHOOTING.md

@@ -1,113 +1,113 @@
-# Speexor Troubleshooting Guide
-
-## Common Issues
-
-### "speexor.config.yaml not found"
-
-**Cause:** You ran `speexor list` or `speexor agent spawn` without initializing a project first.
-
-**Fix:** Run `speexor start <repo-url>` to create the config file, or manually create `speexor.config.yaml` in your project root.
-
-### "Not a git repository"
-
-**Cause:** You're running `speexor` outside a git repository.
-
-**Fix:** Navigate to a git repository or run `git init` first.
-
-### "tmux not available"
-
-**Cause:** tmux is not installed on your system.
-
-**Fix (macOS):**
-```bash
-brew install tmux
-```
-
-**Fix (Linux):**
-```bash
-sudo apt install tmux  # Debian/Ubuntu
-sudo dnf install tmux  # Fedora
-```
-
-**Fix (Windows):** Speexor will automatically fall back to the Process runtime on Windows.
-
-### "GitHub CLI (gh) not found"
-
-**Cause:** The `gh` CLI is not installed but required for GitHub tracker/SCM plugins.
-
-**Fix:**
-```bash
-# macOS
-brew install gh
-
-# Linux (Debian/Ubuntu)
-sudo apt install gh
-
-# Windows (winget)
-winget install GitHub.cli
-
-# Or manual: https://cli.github.com/
-```
-
-### Agent spawn fails
-
-**Cause:** The specified agent CLI is not installed or not in PATH.
-
-**Fix:** Ensure the agent CLI is installed and accessible:
-```bash
-# Verify
-opencode --version
-claude --version
-aider --version
-codex --version
-```
-
-### "Worktree already exists"
-
-**Cause:** A worktree for the same branch already exists, possibly from a previous interrupted session.
-
-**Fix:**
-```bash
-# List worktrees
-git worktree list
-
-# Remove stale worktree
-speexor stop <session-id>
-# Or manually:
-git worktree remove --force .speexor/worktrees/<task-id>
-```
-
-### Dashboard not showing
-
-**Cause:** Port 3000 might be in use, or the dashboard was not started.
-
-**Fix:**
-```bash
-# Specify a different port
-speexor start --port 4000
-
-# Or start dashboard only (if already initialized)
-speexor start
-```
-
-## Windows-Specific Issues
-
-### ConPTY Fallback
-
-On Windows, tmux is not available. Speexor automatically uses the Process runtime instead. This works for most cases but lacks live terminal streaming.
-
-### Shell Path
-
-If you use PowerShell, the default shell path detection should work. To customize:
-
-```yaml
-# In speexor.config.yaml
-plugins:
-  runtime: process
-```
-
-## Getting Help
-
-- Open an issue: https://github.com/superdevids/speexjs/issues
-- Check the PRD: [PRD01.md](./PRD01.md)
-- Ask in the SpeexJS community
+# Speexor Troubleshooting Guide
+
+## Common Issues
+
+### "speexor.config.yaml not found"
+
+**Cause:** You ran `speexor list` or `speexor agent spawn` without initializing a project first.
+
+**Fix:** Run `speexor start <repo-url>` to create the config file, or manually create `speexor.config.yaml` in your project root.
+
+### "Not a git repository"
+
+**Cause:** You're running `speexor` outside a git repository.
+
+**Fix:** Navigate to a git repository or run `git init` first.
+
+### "tmux not available"
+
+**Cause:** tmux is not installed on your system.
+
+**Fix (macOS):**
+```bash
+brew install tmux
+```
+
+**Fix (Linux):**
+```bash
+sudo apt install tmux  # Debian/Ubuntu
+sudo dnf install tmux  # Fedora
+```
+
+**Fix (Windows):** Speexor will automatically fall back to the Process runtime on Windows.
+
+### "GitHub CLI (gh) not found"
+
+**Cause:** The `gh` CLI is not installed but required for GitHub tracker/SCM plugins.
+
+**Fix:**
+```bash
+# macOS
+brew install gh
+
+# Linux (Debian/Ubuntu)
+sudo apt install gh
+
+# Windows (winget)
+winget install GitHub.cli
+
+# Or manual: https://cli.github.com/
+```
+
+### Agent spawn fails
+
+**Cause:** The specified agent CLI is not installed or not in PATH.
+
+**Fix:** Ensure the agent CLI is installed and accessible:
+```bash
+# Verify
+opencode --version
+claude --version
+aider --version
+codex --version
+```
+
+### "Worktree already exists"
+
+**Cause:** A worktree for the same branch already exists, possibly from a previous interrupted session.
+
+**Fix:**
+```bash
+# List worktrees
+git worktree list
+
+# Remove stale worktree
+speexor stop <session-id>
+# Or manually:
+git worktree remove --force .speexor/worktrees/<task-id>
+```
+
+### Dashboard not showing
+
+**Cause:** Port 3000 might be in use, or the dashboard was not started.
+
+**Fix:**
+```bash
+# Specify a different port
+speexor start --port 4000
+
+# Or start dashboard only (if already initialized)
+speexor start
+```
+
+## Windows-Specific Issues
+
+### ConPTY Fallback
+
+On Windows, tmux is not available. Speexor automatically uses the Process runtime instead. This works for most cases but lacks live terminal streaming.
+
+### Shell Path
+
+If you use PowerShell, the default shell path detection should work. To customize:
+
+```yaml
+# In speexor.config.yaml
+plugins:
+  runtime: process
+```
+
+## Getting Help
+
+- Open an issue: https://github.com/superdevids/speexjs/issues
+- Check the PRD: [PRD01.md](./PRD01.md)
+- Ask in the SpeexJS community

package/docs/adr/0001-record-architecture-decisions.md

@@ -0,0 +1,44 @@
+# ADR-0001: Use Architecture Decision Records
+
+## Status
+
+Accepted
+
+## Context
+
+Speexor is a plugin-based, agent-agnostic orchestrator for multi-AI coding agents. As the project grows, contributors and maintainers need a clear historical record of why architectural choices were made. Without this, future developers may reverse decisions without understanding the original rationale, leading to inconsistent architecture.
+
+## Decision
+
+We will use Architecture Decision Records (ADRs) in `docs/adr/` to document all significant architectural decisions. Each ADR follows this template:
+
+```markdown
+# ADR-NNNN: Title
+
+## Status
+
+[Proposed | Accepted | Deprecated | Superseded by ADR-NNNN]
+
+## Context
+
+The background, constraints, and forces that led to this decision.
+
+## Decision
+
+The architectural choice we made and how it addresses the context.
+
+## Consequences
+
+The trade-offs, benefits, and costs of this decision.
+```
+
+- ADRs are numbered sequentially (0001, 0002, ...).
+- ADRs are written in the present tense as of the decision date.
+- ADRs are never deleted; deprecated ADRs link to their replacement.
+- ADRs are committed alongside the code changes they describe.
+
+## Consequences
+
+- **Positive:** Clear rationale trail for future contributors; easier onboarding; architectural consistency enforced by explicit record-keeping.
+- **Negative:** Overhead of writing and maintaining ADRs; risk of falling behind if decisions are not documented promptly.
+- **Neutral:** ADRs become a permanent part of the codebase in `docs/adr/`.