[Feature]: Mirror Roomote projects to GitHub Project V2, issues, and milestones

[roomote-community]

Problem

Teams need GitHub visibility, but Roomote's current GitHub management does not create and populate a complete Project V2 mirror for a native Roomote project.

Proposed behavior

Optionally create or adopt one organization Project V2, create one issue per executable plan item, add issues and linked PRs, create repository milestones where items exist, map status fields, persist provider IDs/URLs, and read back every write.

Reuse scoped GitHub App credentials, current milestone/Project V2 discovery and update behavior, permission checks, and task PR facts. Keep Roomote authoritative and synchronization one-way initially.

Acceptance criteria

• Retries create no duplicate projects, issues, milestones, or Project items.
• Multi-repository work uses one Project V2 and repository-local milestones.
• Missing organization-project permissions block only the mirror.
• Destructive mutations follow project role/policy confirmation.
• Roomote remains usable during GitHub outages.

Dependencies

• [Feature]: Add the project planning domain model and authorization foundation #1037
• [Feature]: Add the project event timeline and audited control commands #1043

[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]: Add the project event timeline and audited control commands #1043. Extend the project domain with an optional GitHub mirror configuration plus bindings for the organization Project V2, each plan-item issue, each repository-local milestone, and each Project item. Persist GitHub node IDs, numbers, URLs, last-applied fingerprints, sync state, and errors with uniqueness constraints keyed by the local resource so retries converge instead of creating duplicates.
2. Add a server-only GitHub mirror adapter in packages/github using the existing installation-token path from packages/github/src/api.ts, never linked-user OAuth. Support organization-project discovery/create/adopt, issue and milestone reconciliation, Project item insertion, single-select field discovery/update, and mandatory read-back after every write. Treat missing organization_projects: write approval as a mirror-only permission failure.
3. Make mirror setup an authorized project command: verify all mirrored repositories are active GitHub repositories covered by the organization installation; allow either explicit adoption by Project V2 node ID or creation of one marked Roomote-owned project; discover the selected single-select status field and persist an explicit mapping from [Feature]: Add the project planning domain model and authorization foundation #1037's item states to option IDs. Never silently adopt an unmarked title match.
4. Reconcile the current published plan into one issue per executable item in its owning repository. Put stable Roomote project/plan/item markers and canonical links in a generated body section, preserve user-authored content outside that section, and create one copy of each Roomote milestone in every repository containing member items. Assign each issue to its repository-local milestone and never create milestones in repositories without items.
5. Add both item issues and linked Roomote-created PRs to the single Project V2. Resolve PRs through the [Feature]: Link project plan items to existing Roomote task execution and controls #1041 project item-attempt/task links and the existing provider-aware task_pull_requests records, dedupe by GitHub content node ID, and apply the owning plan item's mapped status to every mirrored Project item. GitHub edits remain informational only and never mutate Roomote.
6. Drive synchronization asynchronously from [Feature]: Add the project event timeline and audited control commands #1043's append-only project events through a dedicated BullMQ reconciliation queue. Each job should recompute desired state from Roomote, reconcile remote state, record read-back results, and retry with exponential backoff; add a periodic/manual repair pass so a lost enqueue or GitHub outage cannot block project mutations or leave the mirror permanently stale.
7. Apply destructive-policy boundaries explicitly: routine creation and saved status updates may run under the authorized mirror policy, but project replacement, adoption changes, milestone reassignment/closure, issue closure, or removal of Project items requires the corresponding [Feature]: Add the project planning domain model and authorization foundation #1037 role grant and explicit confirmation. Never delete GitHub resources automatically; when a plan version supersedes an item, mark or close the mirror only when the saved policy permits it, otherwise report drift.
8. Expose mirror setup, status, retry, and disable controls through the project settings/router introduced by the project UI work. Show the Project URL, per-resource links, last successful attempt, pending/error state, and the concrete permission remediation while leaving the native Roomote project fully usable.
9. Add real-database tests for binding uniqueness, concurrent retries, event deduplication, plan-version supersession, and authorization; mocked GitHub adapter tests for create/adopt discovery, marker recovery after a post-write crash, read-back verification, status mapping, multi-repository milestones, linked PR insertion, permission failures, outages, and drift; queue tests for retry/repair behavior; and UI tests for setup, confirmation, status, and retry. Document the one-way authority model, required GitHub App permissions, and recovery behavior in apps/docs/.

This keeps Roomote authoritative, uses the existing scoped GitHub App and task/PR facts, and isolates eventual-consistency or permission failures to the optional mirror.

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