ADR-023: Write Agent Readiness

• Status: Accepted
• Date: 2026-08-18
• Roadmap task: F1-033
• Decision owners: execution security and repository governance maintainers

Context

Bootstrap boyunca tek integrator yazma yetkisine sahiptir. Paralel yazma lane’lerini yalnız plan metnine veya geçmiş komut beyanlarına dayanarak açmak; packet, review, worktree, lease, protected path, DB isolation ve context kontrollerinin birlikte tamamlandığını kanıtlamaz. Öte yandan bütün geçmiş dış komutları tekrar çalıştırmak da çoğu zaman mümkün değildir ve bağımsız semantik review yerine pahalı bir komut tekrarına dönüşür.

F1-033 bu geçişi version-controlled fakat tek başına yetkisiz bir certificate ile protected Git common-dir receipt’i arasında iki aşamaya ayırır.

Decision

Açık önkoşul kümesi

config/governance/write-agent-readiness.yml, gerekli roadmap task’larını ve onların kabul edilmiş packet ID’lerini açıkça listeler. Generator listedeki kümenin generated execution index’teki bütün closed/accepted packet’larla birebir aynı olduğunu doğrular. Önkoşul seçimi sezgisel değildir ve bir AI kararına bırakılmaz.

Genesis acceptance; BOOT-006, BOOT-007, initial commit ve review bağını taşır. Her standart önkoşul için packet, acceptance, evidence ve completion dosyaları; accepted durum, review sözleşmesi, implementation-to-review-to-source Git ancestry’si ve Git’te saklanan evidence artifact hashleri doğrulanır. Eski üç completion belgesi structured frontmatter’dan önce üretildiği için exact dosya hashiyle bağlanır; frontmatter varsa packet/head/evidence alanları ayrıca doğrulanır. Bu uyumluluk kabul veya evidence denetimini gevşetmez.

Certificate ve replay

docs/project/execution/write-agent-readiness.json belirli bir source commit’ten deterministik üretilir. Schema, canonical JSON byte’ları, içerik digest’i ve source commit’ten exact yeniden üretim birlikte doğrulanır. Sonradan düzenlenen, farklı serialize edilen veya kaynak Git kayıtlarıyla uyuşmayan certificate reddedilir.

Certificate şu kalıcı kararları ilan eder:

• Bootstrap sole-writer yalnız accepted trusted receipt sonrasında kapanır.
• Yazma lane’leri packet, worktree, lease, path ownership ve disposable DB kapılarına tabi kalır.
• /Volumes/2026/dev/apps/archive/** kalıcı olarak salt okunurdur.

Aktivasyon

Committed certificate yetki vermez. Receipt yalnız aşağıdaki koşullarda üretilebilir:

1. İşlem temiz ve exact main üzerinde çalışır.
2. Certificate byte’ları maindeki configured path ile aynıdır ve source commit mainin ancestor’ıdır.
3. F1-033 packet’ı closed, acceptance kararı accepted ve reviewed commit maindedir.
4. Acceptance exact persistent review receipt’iyle bağlıdır ve çağıran kimlik hem receipt’i üreten hem acceptance içindeki approving execution-security-reviewerdır.
5. Merge queue sözleşmesi ve event hashleri geçerlidir; candidate acceptance hash’i eşleşir ve result, integration ile exact candidate’ı bu sırada taşıyan iki parentlı merge commit’idir.
6. Reviewed packet’tan candidate packet’a yalnız review durumunun closed olması kabul edilir; packet’ın diğer bütün alanları ile evidence, completion ve released lease snapshot’ları byte düzeyinde aynı kalır.
7. Result tree, enqueue event hash’i ve merge parent’ından yeniden kurulan authorization digest’i landed olayındaki değerle aynıdır.

Receipt certificate SHA-256, integration commit, reviewer ve zamanı protected trusted receipt store’da bağlar. DB agent hazırlığı bu receipt’i doğrulamadan credential üretmez veya container başlatmaz.

Review iş bölümü

Lead test, build, hash ve Git doğrulamalarını doğrudan çalıştırıp evidence’a kaydeder. Reviewer’ın görevi bu deterministik komutları aktarmak değil; exact ve bounded diff üzerinde semantik tutarlılık, yetki yükseltme ihtimali, fail-open durumlar ve trust-boundary kusurlarını değerlendirmektir. Yalnız bağımsız yeniden üretim kabul kriterinin kendisiyse reviewer komut çalıştırır.

Consequences

• Bootstrap’tan paralel yazma düzenine geçiş tek ve denetlenebilir bir olaydır.
• Candidate branch kendi certificate’ini etkinleştiremez ve kendi receipt’ini üretemez.
• Geçmiş kanıtlar exact Git hashleriyle yeniden denetlenir; dış sistemlerdeki geçici komut çıktılarının eksiksiz yeniden üretildiği iddia edilmez.
• Normal execution güvenlik kapıları readiness sonrasında da zorunludur.
• Eski unstructured completion belgeleri hash-bound uyumluluk istisnası taşır; yeni completion belgeleri structured sözleşmeye uymalıdır.

Alternatives Considered

Certificate commit edildiğinde otomatik aktivasyon

Author’ın kendi candidate çıktısıyla yetki açmasına izin verir. Bağımsız kabul ve controlled landing sınırını kaldırdığı için reddedildi.

Bütün geçmiş komutları reviewer’ın tekrar çalıştırması

Geçici dış bağımlılıkları yeniden üretme iddiası güvenilir değildir ve AI reviewer’ı komut yürütücüsüne indirger. Exact retained artifact, contract ve Git ancestry doğrulaması ile bounded semantik review daha doğrudan kanıt sağlar.

Readiness sonrasında genel yazma yetkisi

Bir bootstrap kısıtını kaldırırken bütün packet ve isolation kapılarını da kaldırır. Readiness yalnız sole-writer geçişini kontrol ettiği için reddedildi.

Revisit Conditions

• Trusted receipt store veya merge queue trust boundary’si değişirse.
• Hosted identity, signed attestation ya da remote execution broker eklenirse.
• Legacy completion belgeleri versioned structured kayıtlara migrate edilirse.
• Önkoşul task kümesine yeni bir bootstrap güvenlik kontrolü eklenirse.