MWSE/CLAUDE.md

# CLAUDE.md — Otonom Ajan Operating Contract (MWSE)

Bu dosya, MWSE issue'larını otonom (durmadan) bitirmek için çalışan AI ajanına aittir. **Önce `todo.md`'yi oku** (tam bağlam + yol haritası + studio UI vizyonu). Sonra bu kurallarla çalış.

## Yetki (önceden verildi — SORMA)

Aşağıdakiler için **izin isteme, onay bekleme**:
- Bu repo içinde dosya okuma/yazma/oluşturma/silme.
- Shell, build, test, `go`, `npm` komutları çalıştırma.
- `git.saqut.com/saqut/MWSE` API'sini kullanma (issue okuma/kapatma/yorum, commit).
- Yeni branch açma, commit atma.

## Gitea ile etkileşim — `tools/gitea` CLI KULLAN

git.saqut.com için curl yazma ya da kendi script'ini kurma; **`./tools/gitea`** CLI'ını kullan. Cloudflare-safe (tarayıcı UA) ve kimlik `.gitea-auth.json`'dan otomatik gelir (gitignore'lu) — bu yüzden **şifre/erişim sorma, doğrudan çalıştır.**

- Oku: `./tools/gitea issue list --state open` · `issue view <num>` · `milestone list` · `label list`
- Bittiğinde kapat: `./tools/gitea issue close <num> --comment "tamamlandı, go test -race yeşil"`
- Yorum / etiket: `./tools/gitea issue comment <num> --body "..."` · `issue label <num> --add go --remove docs`
- Wiki: `./tools/gitea wiki view <sayfa>` · `wiki edit <sayfa> --content-file f.md`
- PR (insan-onayı gereken işler için): `./tools/gitea pr create --title "..." --head go-rewrite --base stable --body-file PR.md` · `pr list`
- Tüm komutlar: `./tools/gitea --help`

**Kod göndermek** API değil, normal `git`: `git checkout -b go-rewrite` → commit → `git push origin go-rewrite`. (origin ayarlı, default branch `stable`.) Auth sorarsa token'lı remote / credential helper kur, ama `.gitea-auth.json`'ı ASLA commit etme.

## Durma & soru protokolü (EN ÖNEMLİ)

- **Asla kullanıcıya soru sorup beklemeye geçme.** "Buraya yazayım mı / şuraya erişeyim mi / git'e atayım mı" diye sorma — cevap **evet, yap**.
- Bir karar noktasıyla karşılaşınca: aşağıdaki kısıtlara göre **en makul seçeneği kendin seç**, gerekçesini `decisions.md`'ye yaz, **DEVAM ET**.
- Çözemediğin sert bir engel olursa: `BLOCKERS.md`'ye yaz, o issue'yu atla, **bir sonrakine geç.** Durma.
- Turn'ü bitirmenin TEK kabul edilebilir nedeni: tüm açık issue'lar kapandı.

## İş döngüsü

1. `git.saqut.com/saqut/MWSE` açık issue'larından **en düşük milestone'daki** (önce 0.1.0) başlanmamış olanı seç.
2. Tamamen uygula.
3. Testlerini yaz ve çalıştır. Engine için **`go test -race` ZORUNLU.**
4. Yalnızca testler yeşilse: commit at + issue'yu API ile kapat.
5. Bir sonraki issue'ya geç. Tekrar.

## Bitti tanımı (global)

- Kod derleniyor, testler geçiyor, issue'nun kabul kriteri karşılanıyor.
- **Testi kırık ya da `skip`'li hiçbir şey "bitti" sayılmaz.** Issue'yu öyle kapatma.

## Teknik kısıtlar (KATI — ihlal etme)

- **Engine = Go.** Concurrency: goroutine + channel + `sync.RWMutex`, ya da room/peer başına owner-goroutine (actor). Node'daki "ayrılırken-yazma" race'i bir daha oluşmamalı.
- **Frontend = saf vanilla ES module JavaScript.** Yüzlerce dosya birbirini native `import` ile çağırsın. **React YOK. Parcel/Webpack/Vite YOK (bundler yok).** jQuery/moment gibi bağımlılıklar serbest. TypeScript opsiyonel ve kaldırılabilir — şüphedeysen düz JS tercih et.
- **SDK giriş/çıkış sözleşmesi DONDURULDU.** Public API'yi değiştirme; sadece sunucu içi yapı değişir.

## İnsan-onayına bırakılacaklar (uygula ama KAPATMA, deploy ETME)

Şunları branch'te uygula, `REVIEW.md`'ye "incelenmeli" diye yaz, kapatma ve canlıya alma:
- **#22 concurrency modeli** (asıl kritik tasarım).
- Akış proxy/relay mimarisi, sanal-IP çakışma algoritması.
- `stable` branch'e merge ve `ws.saqut.com` deploy'una dokunan hiçbir şey.

## Güvenlik

- `go-rewrite` gibi **özel bir branch'te** çalış. `stable`'a doğrudan dokunma.
- Force-push yok, veri silme yok, prod deploy yok.