ADR-011: Agent Task Packets, Ownership And Handoffs

• Status: Accepted
• Date: 2026-08-18
• Roadmap task: F1-028
• Decision owners: project architecture and integration maintainers

Context

Münderecat’ın corpus, schema, frontend, documentation ve release işleri aynı stable kimlikleri ve kaynak zincirini etkiler. Bir sohbet oturumu, agent process state’i veya sözlü görev paylaşımı; kimin neyi yazabileceğini, hangi sonucu teslim ettiğini ve neyin onaylandığını kalıcı olarak ispatlayamaz.

Repository halihazırda task packet, completion, evidence ve acceptance artifact’ları kullanır. Ancak author, integrator ve reviewer yetkileri; lease’in kanonik kaydı; handoff’un yeterli sayılması ve review sonrasında hangi değişikliklerin merge edilebileceği tek accepted kararda kesinleştirilmelidir. Mekanik schema, registry ve CI enforcement bu kararı izleyen görevlerindir.

Decision

Durable authority

Git tarafından izlenen packet, lease registry, completion, evidence ve acceptance artifact’ları otoritatiftir. Chat özeti, agent belleği, process ID, yerel branch adı veya CI log’u tek başına yetki ya da handoff değildir.

Her yazma işi bir roadmap task’ına bağlı packet ID, exact integration base, allowed/forbidden path, concurrency key, acceptance kriteri, required test, dependency/handoff ve contract hash seti taşır. Packet yeni ürün kapsamı yaratamaz; kapsam değişikliği integrator tarafından yeni veya superseding packet olarak kaydedilir.

Authority matrix

Rol	Yetki	Yasak
Integrator	Packet açar, scope ve base’i sabitler, lease verir/yeniler/iptal eder, disposition’ı kaydeder, merge sırasını ve roadmap durumunu yönetir	Reviewer oyunu üretmek veya değiştirmek, kabul edilmemiş işi merge etmek, packet kabulünü production yetkisi saymak
Author	Kendi aktif lease’i ve worktree’sinde allowed path’leri değiştirir, test/evidence/completion teslim eder, belirsizliği escalate eder	Kendi review/approval’ını vermek, protected branch’e merge etmek, lease/scope/acceptance kararını tek taraflı genişletmek
Reviewer	Exact commit ve bağlı contract/dependency setini semantik, mimari, domain veya güvenlik açısından inceler; approve, changes requested veya reject kararı verir	Reviewed branch’i düzeltmek, author olmak, kanıtsız approval vermek, komut replay’ini semantik review gibi sunmak
Independent verifier	Reviewer’ın özel bir türü olarak temiz checkout/DB’de açıkça istenen evidence replay ve bağımsız doğrulama yapar	Author branch’inde fix yapmak veya rutin reviewer’ın yerine her komutu tekrar etmek
Release operator	Accepted merge ve release gate’lerinden sonra protected publish/deploy işlemini yürütür	Packet acceptance’ı production mutation izni saymak veya kendi release’inin tek approver’ı olmak

Integrator düşük ve orta riskli sıradan bir packet’ın author’ı da olabilir. Bu durum reviewer ayrılığını kaldırmaz: author_id hiçbir required approval’ı karşılayamaz. Kritik riskli production mutation, canonical data release veya protected migration publication işinde author ve integrator da ayrı kimlikler olur; ilgili gate birden fazla bağımsız reviewer rolü isteyebilir.

Packet lifecycle and disposition

Packet yaşam döngüsü şudur:

draft -> ready -> claimed -> active -> review -> accepted -> closed
                          |          \-> changes_requested -> claimed
                          |          \-> rejected -> closed
                          \-> blocked -> ready | cancelled | superseded
ready | claimed | active -> cancelled | superseded
cancelled | superseded -> closed

Author active işini completion.md ve evidence.json ile review durumuna teslim eder. accepted, changes_requested ve rejected reviewer quorum’una; cancelled ve superseded integrator’a aittir. Integrator reviewer kararını mekanik olarak kaydeder, içeriğini yeniden yorumlayamaz. Yalnız accepted packet parent roadmap task’ının tamamlanmasına katkıda bulunur.

Lease model

F1-029 ile eklenecek Git-backed lease registry aktif yazma yetkisinin kanonik kaynağıdır; packet içindeki lease alanı o kaydın hash-bound snapshot’ıdır. Her aktif lease en az şu alanları taşır:

• lease ID ve monoton artan epoch,
• packet, holder ve integrator kimliği,
• exact base commit, branch ve worktree kimliği,
• allowed path özeti ve concurrency key’ler,
• verilme, sona erme ve kapanma zamanı,
• active, expired, released, cancelled veya superseded durumu.

Integrator lease’i author yazmaya başlamadan önce serial olarak kaydeder. Aktif iki lease aynı protected path veya exclusive concurrency key’i paylaşamaz. Dosya tabanlı yerel lock yarış penceresini azaltabilir ama otorite değildir; Git kaydı ve integration validator belirleyicidir.

Expiry işi otomatik kabul etmez, silmez veya başka agent’a yazma yetkisi vermez. Renewal/reassignment epoch’i artırır. Eski epoch, farklı holder, farklı base ya da kapanmış lease ile gelen commit ve completion stale sayılır ve merge edilemez. Önceki deneme audit kaydı olarak korunur.

Handoffs

Bir packet yalnız şu koşullarda dependency handoff’u sağlar:

1. disposition accepted ve lifecycle closed durumundadır,
2. acceptance exact reviewed commit, dependency set ve contract setini taşır,
3. completion ve evidence artifact’ları çözülebilir ve hash-bound’dur,
4. successor packet handoff ID ile exact acceptance hash’ini girdisine bağlar.

Chat özeti, branch HEAD’i, partial, blocked, no-change, changes requested veya rejected sonuç dependency’yi karşılamaz. Partial çıktı kullanılacaksa integrator onu ayrı, sınırları açık bir packet’a dönüştürür ve normal review’dan geçirir. Superseded artifact silinmez; yerine geçen packet’a bağlanır.

Review binding and re-review

İlk bağımsız reviewer author context’ini miras almayan dar bir context packet’i ile başlar. Review kararı şunlara birlikte bağlanır:

• exact implementation commit,
• dependency set hash,
• contract set hash,
• incelenen evidence ID’leri ve required reviewer rolü.

Reviewer author branch’inde değişiklik yapmaz. Aynı reviewer yalnız kendi açık bulgularına ait dar delta’yı re-review edebilir; yeni alan, yeni risk veya genel ikinci inceleme gerekirse taze reviewer atanır. Deterministik test/lint/build lead veya CI tarafından evidence’a bir kez bağlanır. Independent replay ancak packet gate’i, evidence çelişkisi veya somut bulgu gerektiriyorsa yapılır.

Reviewed output, source, test veya contract değişirse approval geçersiz olur ve yeni review gerekir. Approval sonrasında integrator yalnız şu kapanış bookkeeping’ini ekleyebilir: reviewer kararını taşıyan acceptance.yaml, packet state değişimi, execution index kaydı ve roadmap işareti. Bu commit reviewed çıktıları, completion/evidence anlamını veya contract hashlerini değiştiremez; değiştirirse bookkeeping istisnası biter ve approval yenilenir.

Merge authority

Protected integration branch’ine yalnız integrator merge eder. Merge için:

• packet ve lease identity/epoch geçerli,
• branch yalnız allowed path’leri değiştiriyor,
• required completion/evidence çözülebilir,
• reviewer quorum exact implementation commit’i kabul etmiş,
• reviewed commit integration HEAD üzerine temiz uygulanabiliyor,
• integration-head testleri ve concurrency/write-set kontrolleri geçiyor,
• approval sonrası değişiklik yalnız izinli kapanış bookkeeping’i

olmalıdır. Integrator implementation’ı değiştirirse yeni implementation commit ve review gerekir. Merge acceptance’ı production credential, DB migration veya release publication yetkisi vermez; bunlar ayrı operator ve gate’lere aittir.

Successor implementation boundary

F1-029 bu karardan packet/completion/evidence/acceptance schema’larını, lifecycle transition validator’ını, lease registry’yi ve generated execution indexini uygular. F1-030 ayrı worktree provisioning, allowed-path/write-set collision kontrolü, protected-path ownership ve kontrollü merge queue’yu uygular. Bu ADR bu mekanizmaların davranış sözleşmesidir; onların çalıştığını iddia etmez.

Consequences

Benefits

• Yetki agent belleğinden ve uzun sohbet context’inden bağımsız hale gelir.
• Stale lease ve stale approval sessizce merge edilemez.
• Author ile integrator aynı kişi olduğunda bile review bağımsızlığı ölçülebilir kalır; kritik işlerde daha güçlü separation uygulanabilir.
• Bounded re-review ve closure bookkeeping rutin işi gereksiz tekrar etmeden reviewed implementation bütünlüğünü korur.
• Accepted handoff yeni agent tarafından yalnız repository artifact’larıyla yeniden anlaşılabilir.

Costs

• Her write packet için lease, evidence, completion ve acceptance kaydı gerekir.
• Integration branch ve registry güncellemeleri serial bir otorite gerektirir.
• Material rebase veya küçük görünen reviewed-output değişikliği approval’ı düşürebilir.
• Public remote açılana kadar protected branch ve required review enforcement repository artifact’larıyla tanımlı fakat hosting tarafında etkin değildir.

Alternatives Considered

Chat Or Agent State As Authority

Hızlıdır fakat restart, context compaction ve farklı agent’lar arasında denetlenebilir değildir. Stable ID ve release zinciri için reddedildi.

Author Self-Approval

Küçük işlerde akışı kısaltır fakat authoring hatasını kabul mekanizmasına taşır. Integrator-author birleşmesine izin verilirken reviewer ayrılığı korunarak reddedildi.

Every Reviewer Replays Every Command

Bağımsızlık görünümü üretir fakat semantik review kapasitesini tüketir ve CI’ı insan/AI proxy üzerinden tekrarlar. Yalnız explicit independent-verifier gate’i ve somut evidence şüphesi için replay kabul edildi.

Network Lease Service From The First Release

Gerçek zamanlı locking sağlar fakat henüz tek repository ve kontrollü integrator için ayrı servis, credential ve availability yükü getirir. Git-backed registry ve serialized integrator yeterli ilk sınır olarak seçildi; birden fazla bağımsız orchestrator gerektiğinde yeniden değerlendirilir.

References

• ORCHESTRATION_PLAN.md sections 7 through 12
• PROJECT_PLAN.md tasks F1-028 through F1-030
• docs/project/execution/templates/packet.yaml
• docs/project/execution/templates/acceptance.yaml

Revisit Conditions

• Birden fazla bağımsız integrator aynı anda lease vermek zorunda kalır.
• Hosted branch protection Git-backed registry ile atomik doğrulanamaz.
• Critical release için author/integrator separation sürdürülemez.
• Closure bookkeeping reviewed artifact’ı değiştirmeden sınırlandırılamaz.