From 3e1dc90bf250ada7ac847e310d6102356c143b82 Mon Sep 17 00:00:00 2001 From: Harshit Khemani Date: Tue, 21 Jul 2026 23:06:26 +0530 Subject: [PATCH] fix(execution-policy): final-stage approval terminates the policy instead of rewinding to stage 1 (#7893) (#7936) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Issues can carry an embedded multi-stage `executionPolicy` (e.g. QA → CodeReviewer → CodePusher) driven by `applyIssueExecutionStageTransition` in `server/src/services/issue-execution-policy.ts` > - On approval, the next stage was picked with `nextPendingStage()`, which scans the **whole** stage list from index 0 for the first id not in `completedStageIds` > - Stage ids are regenerated whenever the embedded policy is re-sent or edited mid-flow (a supported operation — the existing "reassigns the active stage when the current participant is removed" test depends on it), so earlier `completedStageIds` can stop matching the current policy; a final-stage approve then "finds" stage 1 pending again and rebuilds a first-stage review (#7893) — an endless re-review loop that can recycle indefinitely against a moving main tip > - This pull request makes approvals advance with a forward-only scan (only stages *after* the one being approved), so approving the last stage always terminates the policy, and adds a guard so an already-completed execution state is terminal for `status=done` > - The benefit is final-stage approvals close the issue as the policy intends, with no behavior change for non-final advancement or reject/changes_requested verdicts ## Linked Issues or Issue Description Fixes #7893 ## What Changed - `server/src/services/issue-execution-policy.ts`: - New `nextPendingStageAfter(policy, completedStage, state)` helper — forward-only scan from the approved stage's index; the approval path uses it instead of `nextPendingStage()`. Approving the final stage therefore always yields `nextStage === null` → completed state → the caller's `done` flows through. - New guard: `requestedStatus === "done"` with an already-`completed` execution state returns without restarting the chain at stage 1 (closes the same loop when a stale completed state lingers). - Reject/`changes_requested` verdicts and intact-state forward advancement are untouched. - `server/src/__tests__/issue-execution-policy.test.ts`: 4 regression tests, including one that reproduces the exact rewind (regenerated stage ids + final-stage approve → previously reassigned QA at `currentStageIndex 0`; now terminal completed) and an explicit final-stage rejection test pinning the unchanged path. ## Verification - `npx vitest run server/src/__tests__/issue-execution-policy.test.ts` → 54 passed (50 pre-existing + 4 new). - `pnpm --filter @paperclipai/server typecheck` → clean. - The rewind was confirmed empirically against unmodified code first (a test asserting the buggy output passed pre-fix and flips post-fix), plus brute-forced realistic operation sequences (checkout dances, status round-trips, interim comments per the agent flow documented around #4889) to verify intact-state flows are unaffected. - Related suites (`issue-execution-policy-routes`, `issue-comment-reopen-routes`, `issues-service`, `issue-thread-interaction-routes`, `issue-agent-mutation-ownership-routes`) also pass locally. ## Risks - Behavior deliberately preserved: non-final approvals (forward scan is identical when state is intact), rejections at any stage, reopen-from-done (state cleared on reopen, fresh chain still starts at stage 1), and explicit `in_review` restarts. - The policy schema has no terminal-state field, so per the issue's Ask the policy simply terminates and the requested `done` status flows through. ## Model Used - Claude Fable 5 (`claude-fable-5`, Anthropic) via Claude Code, agentic mode with tool use (subagent implementation + independent adversarial review subagent), extended thinking enabled. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above (none found for #7893) - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots (N/A — server-only change) - [x] I have updated relevant documentation to reflect my changes (N/A — internal stage-advance semantics) - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green (will confirm once CI runs on this PR) - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups (pending first review) - [x] I will address all Greptile and reviewer comments before requesting merge Co-authored-by: Claude Fable 5 --- .../__tests__/issue-execution-policy.test.ts | 172 ++++++++++++++++++ server/src/services/issue-execution-policy.ts | 26 ++- 2 files changed, 194 insertions(+), 4 deletions(-) diff --git a/server/src/__tests__/issue-execution-policy.test.ts b/server/src/__tests__/issue-execution-policy.test.ts index c66dde8f53..b3f09d295b 100644 --- a/server/src/__tests__/issue-execution-policy.test.ts +++ b/server/src/__tests__/issue-execution-policy.test.ts @@ -1081,6 +1081,178 @@ describe("issue execution policy transitions", () => { }); }); + describe("final stage completion terminates the policy (#7893)", () => { + function threeStagePolicy() { + return makePolicy([ + { type: "review", participants: [{ type: "agent", agentId: qaAgentId }] }, + { type: "review", participants: [{ type: "agent", agentId: ctoAgentId }] }, + { type: "approval", participants: [{ type: "user", userId: ctoUserId }] }, + ]); + } + + it("final-stage approval completes even when earlier completedStageIds are stale", () => { + const policy = threeStagePolicy(); + const approvalStageId = policy.stages[2].id; + // completedStageIds reference stage ids from a previous version of the + // embedded policy (stage ids regenerate when the policy is re-sent or + // edited mid-flow); only the active final stage id still matches. + const staleStageIds = [ + "99999999-9999-4999-8999-999999999991", + "99999999-9999-4999-8999-999999999992", + ]; + const result = applyIssueExecutionPolicyTransition({ + issue: { + status: "in_review", + assigneeAgentId: null, + assigneeUserId: ctoUserId, + executionPolicy: policy, + executionState: { + status: "pending", + currentStageId: approvalStageId, + currentStageIndex: 2, + currentStageType: "approval", + currentParticipant: { type: "user", userId: ctoUserId }, + returnAssignee: { type: "agent", agentId: coderAgentId }, + completedStageIds: staleStageIds, + lastDecisionId: null, + lastDecisionOutcome: "approved", + }, + }, + policy, + requestedStatus: "done", + requestedAssigneePatch: {}, + actor: { userId: ctoUserId }, + commentBody: "Approved, ship it", + }); + + // Must terminate the policy, not wrap around to the first stage. + expect(result.patch.executionState).toMatchObject({ + status: "completed", + completedStageIds: expect.arrayContaining([...staleStageIds, approvalStageId]), + lastDecisionOutcome: "approved", + }); + expect(result.patch.status).toBeUndefined(); + expect(result.patch.assigneeAgentId).toBeUndefined(); + expect(result.decision).toMatchObject({ + stageId: approvalStageId, + stageType: "approval", + outcome: "approved", + }); + }); + + it("non-final stage approval still advances forward to the next stage", () => { + const policy = threeStagePolicy(); + const firstStageId = policy.stages[0].id; + const result = applyIssueExecutionPolicyTransition({ + issue: { + status: "in_review", + assigneeAgentId: qaAgentId, + assigneeUserId: null, + executionPolicy: policy, + executionState: { + status: "pending", + currentStageId: firstStageId, + currentStageIndex: 0, + currentStageType: "review", + currentParticipant: { type: "agent", agentId: qaAgentId }, + returnAssignee: { type: "agent", agentId: coderAgentId }, + completedStageIds: [], + lastDecisionId: null, + lastDecisionOutcome: null, + }, + }, + policy, + requestedStatus: "done", + requestedAssigneePatch: {}, + actor: { agentId: qaAgentId }, + commentBody: "QA pass", + }); + + expect(result.patch.status).toBe("in_review"); + expect(result.patch.assigneeAgentId).toBe(ctoAgentId); + expect(result.patch.executionState).toMatchObject({ + status: "pending", + currentStageId: policy.stages[1].id, + currentStageIndex: 1, + completedStageIds: [firstStageId], + }); + }); + + it("final-stage changes requested still returns to the executor", () => { + const policy = threeStagePolicy(); + const approvalStageId = policy.stages[2].id; + const result = applyIssueExecutionPolicyTransition({ + issue: { + status: "in_review", + assigneeAgentId: null, + assigneeUserId: ctoUserId, + executionPolicy: policy, + executionState: { + status: "pending", + currentStageId: approvalStageId, + currentStageIndex: 2, + currentStageType: "approval", + currentParticipant: { type: "user", userId: ctoUserId }, + returnAssignee: { type: "agent", agentId: coderAgentId }, + completedStageIds: [policy.stages[0].id, policy.stages[1].id], + lastDecisionId: null, + lastDecisionOutcome: "approved", + }, + }, + policy, + requestedStatus: "in_progress", + requestedAssigneePatch: {}, + actor: { userId: ctoUserId }, + commentBody: "Needs rework before release", + }); + + expect(result.patch.status).toBe("in_progress"); + expect(result.patch.assigneeAgentId).toBe(coderAgentId); + expect(result.patch.executionState).toMatchObject({ + status: "changes_requested", + currentStageId: approvalStageId, + lastDecisionOutcome: "changes_requested", + }); + }); + + it("a completed execution state does not restart the workflow on done", () => { + const policy = threeStagePolicy(); + // Completed state whose stage ids no longer match the current policy + // (e.g. policy re-sent with regenerated ids after the chain finished). + const result = applyIssueExecutionPolicyTransition({ + issue: { + status: "in_review", + assigneeAgentId: null, + assigneeUserId: ctoUserId, + executionPolicy: policy, + executionState: { + status: "completed", + currentStageId: null, + currentStageIndex: null, + currentStageType: null, + currentParticipant: null, + returnAssignee: { type: "agent", agentId: coderAgentId }, + completedStageIds: [ + "99999999-9999-4999-8999-999999999991", + "99999999-9999-4999-8999-999999999992", + "99999999-9999-4999-8999-999999999993", + ], + lastDecisionId: null, + lastDecisionOutcome: "approved", + }, + }, + policy, + requestedStatus: "done", + requestedAssigneePatch: {}, + actor: { userId: ctoUserId }, + commentBody: "Closing out", + }); + + // No rewind to the first stage — the caller's done is allowed through. + expect(result.patch).toEqual({}); + }); + }); + describe("changes requested with no return assignee", () => { it("throws when requesting changes with no return assignee", () => { const policy = twoStagePolicy(); diff --git a/server/src/services/issue-execution-policy.ts b/server/src/services/issue-execution-policy.ts index f09f47020e..9fb34e748b 100644 --- a/server/src/services/issue-execution-policy.ts +++ b/server/src/services/issue-execution-policy.ts @@ -441,6 +441,16 @@ function nextPendingStage(policy: IssueExecutionPolicy, state: IssueExecutionSta return policy.stages.find((stage) => !completed.has(stage.id)) ?? null; } +function nextPendingStageAfter( + policy: IssueExecutionPolicy, + completedStage: IssueExecutionStage, + state: IssueExecutionState | null, +) { + const completed = new Set(state?.completedStageIds ?? []); + const completedIndex = policy.stages.findIndex((stage) => stage.id === completedStage.id); + return policy.stages.find((stage, index) => index > completedIndex && !completed.has(stage.id)) ?? null; +} + function selectStageParticipant( stage: IssueExecutionStage, opts?: { @@ -701,10 +711,12 @@ function applyIssueExecutionStageTransition(input: TransitionInput): TransitionR throw unprocessable("Approving a review or approval stage requires a comment"); } const approvedState = buildCompletedState(existingState, activeStage); - const nextStage = nextPendingStage( - input.policy, - { ...approvedState, completedStageIds: approvedState.completedStageIds }, - ); + // Only stages after the stage being approved are advance candidates. + // Scanning the whole policy could wrap back to the first stage when + // earlier completedStageIds no longer match the policy (e.g. stage ids + // were regenerated by a mid-flow policy edit), turning a final-stage + // approval into an endless re-review loop (#7893). + const nextStage = nextPendingStageAfter(input.policy, activeStage, approvedState); if (!nextStage) { patch.executionState = approvedState; @@ -810,6 +822,12 @@ function applyIssueExecutionStageTransition(input: TransitionInput): TransitionR return { patch }; } + // A workflow whose execution already completed is terminal for approve/done: + // closing the issue must not restart the chain at the first stage (#7893). + if (requestedStatus === "done" && existingState?.status === COMPLETED_STATUS) { + return { patch }; + } + let pendingStage = existingState?.status === CHANGES_REQUESTED_STATUS && currentStage ? currentStage