From 518f16460b1b5cfade2eae2cefcaa76c503f41a7 Mon Sep 17 00:00:00 2001 From: Dotta Date: Sun, 2 Aug 2026 01:22:30 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20address=20review=20=E2=80=94=20allow=20?= =?UTF-8?q?in=5Freview=20->=20todo=20in=20the=20status=20contract,=20stabl?= =?UTF-8?q?e=20recovery=20fingerprint?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add in_review -> todo to the allowed transitions in doc/SPEC-implementation.md with the resume-intent wake side effect, and define a fingerprint fallback (finalizing run / status-change event id) for pathless in_review that never had a consumed path. Co-Authored-By: Claude Fable 5 --- doc/SPEC-implementation.md | 3 ++- doc/execution-semantics.md | 4 ++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/SPEC-implementation.md b/doc/SPEC-implementation.md index 1065ea17274..0b2fe34896e 100644 --- a/doc/SPEC-implementation.md +++ b/doc/SPEC-implementation.md @@ -477,7 +477,7 @@ Allowed transitions: - `backlog -> todo | cancelled` - `todo -> in_progress | blocked | cancelled` - `in_progress -> in_review | blocked | done | cancelled` -- `in_review -> in_progress | done | cancelled` +- `in_review -> in_progress | todo | done | cancelled` - `blocked -> todo | in_progress | cancelled` - terminal: `done`, `cancelled` @@ -486,6 +486,7 @@ Side effects: - entering `in_progress` sets `started_at` if null - entering `done` sets `completed_at` - entering `cancelled` sets `cancelled_at` +- a user or board transition of an agent-assigned issue from `in_review` to `todo` is a send-back that expresses resume intent; it enqueues the `issue_status_changed` dispatch wake, subject to the normal rewake throttle V1 non-terminal liveness rule: diff --git a/doc/execution-semantics.md b/doc/execution-semantics.md index 24b75bfb4a9..06e30035f6e 100644 --- a/doc/execution-semantics.md +++ b/doc/execution-semantics.md @@ -469,7 +469,7 @@ An `in_review` issue is stalled when it has no typed participant, no pending int When the last review path of an agent-owned `in_review` issue is consumed and nothing restores or replaces it, recovery is bounded and idempotent: -1. Paperclip queues at most one `issue_review_path_lost` recovery wake for the assignee, fingerprinted on the consumed path id (the interaction, approval, monitor, or participant run that evaporated), so repeated evaluation of the same loss cannot fan out into a wake loop. The wake payload tells the assignee it must restore a waiting path or choose a disposition. +1. Paperclip queues at most one `issue_review_path_lost` recovery wake for the assignee, fingerprinted on the consumed path id (the interaction, approval, monitor, or participant run that evaporated), so repeated evaluation of the same loss cannot fan out into a wake loop. When the issue became pathless without a consumed path — for example, it entered `in_review` and no review path was ever created — the fingerprint is the id of the finalizing run or status-change event that left it pathless, so the recovery key is always stable. The wake payload tells the assignee it must restore a waiting path or choose a disposition. 2. If that recovery run also finishes with the issue `in_review` and zero paths, no further wakes are queued for that fingerprint. The issue enters a visible stalled-review state: surfaced as needs-attention on the issue page and fed to the decisions desk as a decide-now item, rather than drifting silently. 3. A new consumed-path fingerprint — a later interaction, approval, or monitor that itself evaporates — may start one new bounded cycle; unchanged evidence must not. @@ -583,7 +583,7 @@ Run finalization must validate the review disposition, not just the run's own ex Recovery rule: -- Paperclip queues one bounded `issue_review_path_lost` recovery wake for the assignee, fingerprinted on the consumed path id (§8 `in_review`) +- Paperclip queues one bounded `issue_review_path_lost` recovery wake for the assignee, fingerprinted on the consumed path id or, when no path was consumed, on the id of the finalizing run that left the issue pathless (§8 `in_review`) - if that recovery run also finalizes with the issue `in_review` and zero paths, no further wakes are queued for that fingerprint; the issue surfaces as a stalled review on the issue page and the decisions desk This is a review-handoff continuity recovery. It mirrors §9.1 and §9.2: one bounded wake per fingerprint, then visible escalation instead of a requeue loop.