[Feature]: Add project item acceptance, integration PRs, and final delivery

[roomote-community]

Problem

Task completion does not prove that project acceptance criteria passed, and Roomote has no milestone roll-up or integration-to-base delivery flow.

Proposed behavior

Create item delivery branches from integration, target item PRs back to integration, surface validation/proof/PR/check evidence, and add manual accept/reject-with-feedback. Serialize integration merges and create the final integration-to-base PR when required milestones are accepted.

Reuse current draft/ready PR delivery, explicit target branches, task artifacts, visual proof, PR facts, and PR review/fix/conflict workflows. Keep final merge manual in this issue.

Acceptance criteria

• Completed tasks enter Needs review, not Accepted.
• Approvers can accept or reject evidence and send feedback.
• Item PRs merge serially into integration and update the stored SHA.
• The final PR targets the original base and is not auto-merged.
• Reverted/invalidated work appends a reversal and reopens or flags affected items.

Dependency

• [Feature]: Link project plan items to existing Roomote task execution and controls #1041

[roomote-community]

I've analyzed this issue and here's my proposed implementation plan:

1. Build on [Feature]: Add the project planning domain model and authorization foundation #1037's project-planning service and [Feature]: Link project plan items to existing Roomote task execution and controls #1041's durable item-attempt links. Keep three independent projections: task execution state, item acceptance state (pending, needs_review, accepted, rejected, invalidated), and integration-delivery state. A terminal successful attempt should transactionally append an acceptance event and move the item to needs_review; it must never set accepted directly.
2. Make [Feature]: Add project integration branch configuration and preflight #1040's project-repository integration mapping a prerequisite for delivery. Capture the original base branch/SHA, integration branch, and current verified integration SHA per repository. Create each item branch from that stored integration SHA in the existing roomote/<project>/... namespace, and persist the branch/base SHA on the attempt so retries, review, and invalidation are auditable. This issue should formally add [Feature]: Add project integration branch configuration and preflight #1040 as a dependency rather than duplicate branch adoption/preflight logic.
3. Extend the server-only project-planning schema/service (packages/types/src/project-planning.ts, packages/db/src/schema.ts, and packages/db/src/lib/project-planning.ts, as introduced by [Feature]: Add the project planning domain model and authorization foundation #1037) with append-only acceptance and delivery events, reviewer identity/note, item PR links, captured evidence references, integration-merge records, and final-delivery PR state. Use idempotency keys and database constraints so webhook retries cannot accept, reject, or record a merge twice; preserve the N-1 rollback guarantee with additive migrations.
4. Add an evidence roll-up query to the project service that joins [Feature]: Link project plan items to existing Roomote task execution and controls #1041's linked attempts to task result/validation data, retained project-evidence links, task_artifacts metadata (including visual-proof), task_pull_requests, normalized PR reads, and GitHub check/status data. Return explicit available, pending, failed, and unavailable states rather than treating absent provider data as passing; keep captured artifact metadata usable after task/artifact cleanup.
5. Add authorized project tRPC mutations and queries for acceptItemEvidence and rejectItemEvidence in the project-planning router. Both should lock the item, validate that the reviewed evidence belongs to the latest eligible attempt, append the decision event, and record an optional note. Rejection should set the item back to an actionable state and deliver the note through the existing task follow-up/resume path when possible, while retaining the rejected evidence and decision history.
6. Extend the project Work/review UI introduced by the dependency issues with a Needs review queue and item evidence detail. Show validation outcome, proof artifacts, source/target branches, PR state, mergeability, reviews, and checks; expose Accept and Reject-with-feedback only to roles granted the corresponding project action. Keep linked tasks on the normal task transcript and reuse existing artifact viewers and PR links rather than creating parallel viewers.
7. Reuse createOrUpdateSourceControlPullRequestForTaskRun in packages/sdk/src/server/lib/pull-requests/source-control-pull-requests.ts and the manage_source_control worker surface to create/update each item PR with the item branch as sourceBranch and the project integration branch as explicit targetBranch. Persist the returned provider/repository/number/URL/head/base facts on the project item, while preserving the current ambiguity checks and existing draft/ready policy.
8. Add a database-backed integration queue/lease per project repository. When an item is accepted and its PR/check requirements pass, claim exactly one merge operation, re-read the PR and remote integration head, require the stored expected integration SHA to match, and merge through a new scoped source-control mutation. On success, atomically append the merge event and advance the stored integration SHA; on head movement, conflict, failed checks, or provider uncertainty, release/fail the claim without changing the SHA and route the item through the existing review/fix or conflict-resolution workflow. Do not force-push or silently reset the integration branch.
9. After every integration-head advance, mark later unmerged item deliveries stale when their captured base SHA no longer matches and require them to refresh/merge integration before they can enter the serialized merge queue. This keeps item merges ordered without assuming parallel PRs remain mergeable after an earlier item lands.
10. Add a milestone roll-up operation that considers only required items and records why a milestone is blocked. Once all required milestones are accepted and all accepted item PRs are integrated, create or refresh one final integration-to-original-base PR through the same explicit-target PR API. Persist its identity and evidence, preserve the deployment's draft/ready choice, and never call a merge action for this final PR.
11. Handle external reversals from provider webhooks and reconciliation. Extend PR merge/close handling (for GitHub, beginning at apps/api/src/handlers/github/handlePrMerge.ts, with equivalent provider hooks where supported) to identify tracked item/final PRs. If an integration commit is reverted, a merged PR is invalidated, or the integration branch no longer contains the recorded delivery SHA, append a compensating reversal event, invalidate the affected acceptance/delivery projection, and reopen or flag dependent items/milestones; never delete or rewrite the original decision/merge event.
12. Add real-database service tests for authorization, completed-to-needs-review behavior, stale-attempt review rejection, idempotent decisions/webhooks, concurrent merge claims, expected-SHA races, stale item branches, integration SHA advancement, milestone roll-up, final PR deduplication, and reversal propagation. Extend source-control mutation tests for guarded merges and explicit bases, webhook tests for reconciliation, and web tests for evidence rendering, accept/reject permissions, feedback delivery, blocked roll-ups, and final-delivery state.

This approach keeps acceptance as a human, evidence-backed project decision; reuses ordinary tasks, artifacts, proof, PR delivery, and remediation workflows; and adds only the durable orchestration needed to serialize integration delivery and create a manual final PR. The key maintainer-owned scope decision is provider rollout: I recommend keeping the project state machine provider-neutral, implementing guarded merge/check collection first for GitHub, and representing unsupported provider capabilities explicitly rather than weakening acceptance gates.

Please tag @roomote if you'd like me to implement this, or reply with feedback on the plan.