docs: address review — allow in_review -> todo in the status contract, stable recovery fingerprint

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 <noreply@anthropic.com>
This commit is contained in:
DottaandClaude Fable 5 committed 2026-08-02 01:22:35 +00:00
1 parent 804b906a99
commit 518f16460b
2 files changed
+4 -3

No files matched your search

+2 -1
View File
@@ -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:
+2 -2
View File
@@ -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.