fix(sync): keep a human reviewer when parking an issue in maintainer wait

[alvarosanchez]

Why

updatePaperclipIssueState treats clearAssignee as "unassign everything": it patches both assigneeAgentId and assigneeUserId to null. But that flag is only ever set from one place — shouldClearTransitionAssignee, which is nextStatus === 'in_review' && (nextTransitionAssignee === null || shouldPreserveMaintainerWaitRouting), i.e. parking an issue in maintainer wait.

In that situation the intent is "no agent owns this any more". A person deliberately assigned to the issue is the reviewer the work is waiting on, and today sync wipes them on the next pass — and, because the wiped state no longer matches the patch, re-wipes on every pass after that.

This blocks using assigneeUserId as the human-reviewer signal for PRs that are green and waiting on maintainers.

What

• clearAssignee now clears the agent assignee and carries the issue's existing human assignee through in the same patch.
• The preserved value is written into issuePatch explicitly rather than omitting the key, so isPaperclipIssuePatchApplied still recognises the settled state and a parked issue is not re-patched (and re-ledgered) on every sync pass — the regression class fix(sync): repeated no-op status decisions reuse their settled attempt #209 fixed.
• SPEC.md / README.md updated: "leave unassigned" now reads "clear the agent assignee, keep a human assignee".

Tests

Two new cases in tests/issue-interactions-integration.spec.ts:

• parking with a human assignee keeps assigneeUserId, drops assigneeAgentId, issues exactly one issues.update, and a second identical pass performs no further update and appends no extra ledger pair;
• parking with only an agent assignee still unassigns the issue completely.

npm test 361/361 green, npm run typecheck clean.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

The current preservation logic and the new test setup can diverge from the worker’s real syncContext derivation when an agent assignee is present, risking continued clearing of assigneeUserId in the production path.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

This PR adjusts GitHub Sync’s updatePaperclipIssueState behavior so “parking” an issue in in_review (maintainer wait) clears only the agent assignee while preserving any existing human assignee, preventing repeated re-patching and ledger churn on subsequent sync passes. It also updates the written spec/docs and adds integration coverage for the parking scenarios.

Changes:

• Update updatePaperclipIssueState to avoid wiping a human assignee when clearAssignee is used for maintainer-wait parking.
• Add integration tests to ensure parking is idempotent (no repeated issues.update and no repeated update_issue ledger pairs).
• Update SPEC.md and README.md to reflect the “clear agent, keep human” semantics for maintainer wait.

File summaries

File	Description
src/worker.ts	Changes clearAssignee patching logic to preserve a human assignee when parking in maintainer wait.
tests/issue-interactions-integration.spec.ts	Adds integration tests for maintainer-wait parking idempotency and assignee preservation.
SPEC.md	Updates normative behavior for maintainer-wait unassignment to preserve human assignee while clearing agent.
README.md	Updates documentation to match the new maintainer-wait assignee semantics.

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.