İterasyon döngüsü mimarisi

PinAppAI’nin inceleme omurgası v2 itibarıyla iterasyon-öncelikli: bir projenin change request’lerinin sadece bir admin durumu yok, iterasyonlara aitler — dondurulmuş manifest, eleştirmen rosteri snapshot’ı ve her durum değişikliğini izleyen olay günlüğü ile gelen ayrı inceleme turları. Bu sayfa, modeli belgeler ki bir projenin geçmişini doğru okuyabilesin, MCP’den iterasyon sürebilesin veya yeni endpoint’ler üzerinde entegrasyonlar inşa edebilesin.

Eski durum-öncelikli dashboard’u (Open / Processing / Done / Wontfix çipleri) kullandıysan, yeni model bunun üzerine temiz şekilde haritalanır ve geçiş penceresi boyunca onunla yan yana çalışır.

Döngü

[setup-project]                     ← widget + reviewer'ları yükle
   │
   ▼
eleştirmenler canlı sitede change request'ler bırakır
   │
   ▼
admin triyaj yapar → schedule eder → iterasyon N'i açar     ← manifest burada donar
   │                                                            (CR id'leri + reviewer roster)
   ▼
AI ajan paketi uygular                                       ← /pinappai:apply-decisions
   │                                                            durum scheduled → applied
   ▼
eleştirmenler her CR için karar verir                        ← durum applied → in_review
   │
   ▼
admin CR başına onaylar
   │
   ├── accept → closed_accepted (terminal)
   │
   └── reopen → scheduled (geri döner; iterations_traversed += 1)
                    │
                    ▼
              [iterasyon N+1] devralır

Döngü, admin accept ile onayladığında (veya doğrudan wontfix yaptığında — o da terminal) CR başına biter. İterasyonların kendisi “kapanmaz” — sadece uygulanır; CR’lerinin dolaşmaya devam edip etmediği CR-başına bir sorudur.

Bir iterasyon ne yakalar

Her iterasyon satırı şunları tutar:

• seq_no — 1, 2, 3, … proje başına
• opened_at / applied_at — duvar saati zamanı; applied_at IS NULL = açık
• manifest_cr_ids_json — açılış anında dondurulmuş CR id listesi
• manifest_reviewer_ids_json — açılış anındaki reviewer rosteri (snapshot)
• bundle_summary — apply anında eklenen kısa metin, History’de görünür
• source — admin, mcp veya backfill (eski veriden sentezlenmiş)

Manifest açılışta donar: o andan sonra reviewer veya CR eklemek geriye dönük olarak iterasyon N’in rosterini değiştirmez — onlar iterasyon N+1’de görünür. “Bu turun reddedilen 14 tanesi” sorgusunun kararlı bir şekilde cevaplanabilmesini sağlayan şey budur.

Durum makinesi

Her change request, olay günlüğünün fold’u olan önbelleklenmiş bir state sütunu taşır:

   triage → scheduled → applied → in_review →
                ↑                              ├── accept → closed_accepted (terminal)
                │                              └── reopen → scheduled (döngü)
   wontfix ←───┘     (terminal — in_review'dan tekrar girilmez)

Önbellek var çünkü her dashboard read’inde olayları fold etmek D1’de proje başına birkaç yüz CR’ın üzerinde fazla yavaş kalır. Gecelik bir drift-tespit cron’u her CR’ı dolaşır, olaylardan durumu yeniden türetir ve uyumsuzlukları cr_state_drift_log’a yazar — önbelleği dürüst tutan ve gözden kaçan dual-write hook’larını çığ olmadan yüzeye çıkaran şey budur.

Coverage — manşet metriği

Manifest’inde N CR olan bir iterasyon için:

• items_decided = N’in kaç tanesinin en az bir reviewer_decided olayı var
• items_undecided = N − items_decided
• disagreement_count = N’in kaç tanesinde reviewer’lar arasında çelişen kararlar var
• reviewers[] = reviewer başına karara bağlanan item sayısı

“Manşet coverage” = items_decided / manifest_size — admin dashboard’unun coverage bar’ı bunu görselleştirir, pinappai_get_iteration_coverage AI ajanına bunu döner. Reviewer-başına döküm tanılayıcıdır (“yigit 30/50, maya 20/50, tom 0/50, %80 item dokunmuş”).

MCP’den iterasyon sürmek

@pinappai/[email protected] atomik primitif’lere 1:1 eşlenen 5 tool ekler:

• pinappai_open_iteration — dondurulmuş manifest’le iterasyon N+1’i açar
• pinappai_mark_iteration_applied — manifest CR’larını applied’a taşır
• pinappai_acknowledge_change_request — CR başına accept/reopen
• pinappai_get_iteration_coverage — salt-okunur coverage snapshot
• pinappai_list_iterations — sayfalı geçmiş

Tipik bir AI-sürücülü döngü:

# Claude Code veya MCP-uyumlu bir ajanda:
/pinappai:apply-decisions   # içeride pinappai_open_iteration kullanır,
                            #   manifest'i dolaşır, kaynak kodu düzenler,
                            #   sonra pinappai_mark_iteration_applied çağırır

Slash komutu daha önce olduğu gibi .pinappai/last-applied.json marker’ını yazar — o dosya artık sunucu-tarafı iterasyon id’sine işaret eden 1-satırlık bir önbellek, kaynak değil. Eski @pinappai/mcp versiyonları (≤ 0.4.0) eski uyumluluk shim’i üzerinden 6-haftalık deprecation penceresi boyunca çalışmaya devam eder.

Hangi yüzeyi seçmeli

Yüzey	Şuna uygun
app.pinappai.com/dashboard-v2	Manuel inceleme, coverage’a bir bakış, ad-hoc CR-başına onay
Claude Code / Cursor’dan @pinappai/mcp	AI-sürücülü apply + onay, büyük iterasyonlar, programatik akışlar
Eski durum-öncelikli dashboard	Mevcut kas hafızası; geçiş penceresi boyunca tam destekleniyor

Yeni dashboard, workspace’inin dashboard_version bayrağı 'new'’e çevrilene kadar topbar bağlantısıyla opt-in — o noktada projenin varsayılan iniş sayfası iterasyon-öncelikli olur. Her iki düzen de aynı temel veriyi okur, ileri geri çevirmek tahripkar değil.

İmplementasyona el-uzatma

Uygulama şuralarda yaşar:

• API: apps/api/src/lib/iterations.ts (atomik primitifler), apps/api/src/routes/admin-iterations.ts (session auth), apps/api/src/routes/me-iterations.ts (API key auth)
• Şema: migration 0030–0034 (iterations, change_requests, change_request_events, workspaces.dashboard_version, cr_state_drift_log)
• Drift cron: apps/api/src/lib/cr-state-drift.ts her gün 03:00 UTC’de çalışır
• MCP tool’ları: apps/mcp/src/tools/{open-iteration,mark-iteration-applied,acknowledge-change-request,get-iteration-coverage,list-iterations}.ts

Bu şekli tetikleyen tasarım gerekçesi ve takas tartışması için tasarım planına bak: docs/superpowers/plans/2026-05-07-iteration-loop-v2.md.