[Feature]: Add project integration branch configuration and preflight

[roomote-community]

Problem

Tasks can select existing branches and delivery can target an explicit PR base, but Roomote cannot create or safely adopt a shared project integration branch.

Proposed behavior

Add a base branch, user-named integration branch, captured base SHA, and create/adopt workflow per project repository. Preflight branch existence, divergence, protection, open PRs, and permissions; create the remote ref atomically or adopt it explicitly.

Reuse shared Git branch validation, branch listing, source-control credentials, worker remote checkout behavior, and explicit PR target branches. Item branches use a separate roomote/<project>/... namespace.

Acceptance criteria

• A user can configure develop to feat/something-main and verify the remote branch.
• Existing branches require explicit adoption with divergence details.
• Invalid or ref-colliding names are rejected.
• No flow force-pushes or silently resets an adopted integration branch.
• Multi-repository projects keep independent branch mappings.

Dependencies

• [Feature]: Add the project planning domain model and authorization foundation #1037
• [Feature]: Create structured project plans from existing Roomote plan artifacts #1039

[roomote-community]

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

1. Build this after [Feature]: Add the project planning domain model and authorization foundation #1037 and [Feature]: Create structured project plans from existing Roomote plan artifacts #1039, extending the project-repository entity introduced by [Feature]: Add the project planning domain model and authorization foundation #1037 rather than overloading environment checkout configuration in packages/types/src/environment-config.ts or environment_repository_mappings. Store baseBranch, integrationBranch, the base commit SHA captured when the mapping is confirmed, and create/adopt audit metadata on each project-repository row so multi-repository projects remain independent. Add the additive Drizzle migration and relations in packages/db/src/schema.ts, preserving the N-1 rollback contract.
2. Strengthen the shared ref validation in packages/types/src/git-ref.ts to match git check-ref-format --branch semantics, reject the reserved item-branch namespace, and detect remote prefix collisions such as foo versus foo/bar. Reuse that schema in project commands and add table/command constraints so invalid names cannot bypass the UI.
3. Add a server-only, provider-aware integration-branch service alongside the existing repository and pull-request helpers in packages/sdk/src/server/lib/. Its preflight result should include resolved base SHA, whether the candidate ref exists, candidate head SHA, ahead/behind divergence, ref collisions, branch protection, relevant open PRs, and the caller's create/push permissions. Reuse provider/host-aware repository lookup and existing source-control credential resolution rather than looking repositories up by full name alone.
4. Extend the provider adapters (starting from GitHub's current branch listing in packages/github/src/api.ts and the existing GitLab/Gitea/Bitbucket/Azure DevOps packages) with normalized branch/ref inspection and compare/create operations. Creation should use an atomic create-ref API with the preflight base SHA and fail if the ref appeared or the base changed; it must never force-update an existing ref.
5. Expose separate authorized project commands for preflight, create, and adopt through the project service/router introduced by [Feature]: Add the project planning domain model and authorization foundation #1037. Require an explicit adoption flag plus the preflight candidate head/base SHAs, re-check both before committing the mapping to avoid TOCTOU races, and return fresh divergence details when either changed. Adoption records the existing remote head without resetting or pushing it.
6. Add the workflow to the project repository settings UI introduced by [Feature]: Create structured project plans from existing Roomote plan artifacts #1039: select/type the base branch, enter the integration branch, show blocking checks and divergence/protection/open-PR warnings, and present distinct Create branch and Adopt existing branch confirmations. Reuse the existing branch selector patterns in apps/web/src/components/tasks/SelectBranch.tsx, but move branch access behind the provider-neutral API because the current github.branches route is GitHub-only.
7. Propagate the confirmed mapping into project-item task launch/runtime contracts. The worker should check out the configured integration ref using the existing provider-aware path in apps/worker/src/workspace/workspace-manager.ts; generated item branches should use a separately reserved namespace. Delivery should continue passing the integration branch explicitly as targetBranch through apps/worker/src/mcp/roomote-mcp-server/source-control.ts and packages/sdk/src/server/lib/pull-requests/source-control-pull-requests.ts, without changing adopted refs.
8. Add focused tests for shared ref validation and prefix collisions; project-repository authorization and per-repository persistence; every preflight outcome; stale-preflight races; atomic create conflict; explicit adoption; protected/no-permission cases; no-force-push behavior; multi-repository mappings; worker checkout; and PR creation against the configured target. Add UI tests for create/adopt confirmation and divergence rendering, then document integration-branch setup and its safety guarantees in apps/docs/.

This keeps integration-branch policy in the project domain, reuses the current checkout and explicit PR-base paths, and makes both creation and adoption race-safe without silently modifying remote history.

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