diff --git a/doc/SPEC-implementation.md b/doc/SPEC-implementation.md index 2c43e572add..6dc4d4316e4 100644 --- a/doc/SPEC-implementation.md +++ b/doc/SPEC-implementation.md @@ -482,6 +482,7 @@ V1 non-terminal liveness rule: - agent-owned `todo`, `in_progress`, `in_review`, and `blocked` issues must have a live execution path, an explicit waiting path, or an explicit recovery path - `in_review` is healthy only when a typed execution participant, pending issue-thread interaction or approval, user owner, active run, queued wake, or explicit recovery action owns the next action - a blocked chain is covered only when each unresolved leaf issue is live or explicitly waiting +- blocker edges release from the blocker issue's own `done` state and required terminal finalization evidence, not from the latest operation recorded on a reused execution workspace - when Paperclip cannot safely infer the next action, it surfaces the problem through visible blocked/recovery work instead of silently completing or reassigning work - explicit recovery actions are the liveness primitive; source-scoped actions are the default form, issue-backed recovery is a fallback for independent repair work or safety boundaries, and comments alone are evidence rather than a healthy liveness path diff --git a/doc/execution-semantics.md b/doc/execution-semantics.md index 72acb2f442c..ae0e8b8ec6d 100644 --- a/doc/execution-semantics.md +++ b/doc/execution-semantics.md @@ -152,6 +152,20 @@ Blocked issues should stay idle while blockers remain unresolved. Paperclip shou If a parent is truly waiting on a child, model that with blockers. Do not rely on the parent/child relationship alone. +#### Blocker release and finalization + +A blocker edge is released by the blocker issue's own completion state and required finalization evidence. + +For dependency purposes, the resolved fact is about the blocker issue itself: + +- the blocker issue is `done` +- the blocker issue has completed any required terminal finalization for that status, such as durable status/activity persistence and any required post-run disposition evidence +- every unresolved blocker leaf in the chain satisfies the same issue-local completion contract + +The resolved fact is not derived from the latest operation on a reused execution workspace. A later workspace operation may prove that a specific queued wake cannot be delivered coherently, but it must not make an already-completed blocker look unresolved again. Workspace coherence failures belong to adapter delivery and liveness recovery; they should repair, retry once where safe, or surface an explicit recovery action for the dependent issue instead of cancelling the dependent run as dependency-blocked. + +`cancelled` blockers are terminal but not dependency completion. If a cancelled issue should no longer block downstream work, the blocker edge must be explicitly removed or replaced with the real remaining dependency. + ## 7. Accepted-Plan Decomposition An accepted plan confirmation is permission to decompose one specific accepted plan revision into child issues.