feat(github-projects): trigger and synchronize Rascal runs from GitHub Projects v2 board status #209

Summary

Add a GitHub Projects v2 integration that lets users control Rascal from a project board and reflect Rascal run state back into the board.

The intended UX is:

• issues become Rascal-eligible via existing rascal / rascal:<runtime> labels
• eligible issues are auto-added to a GitHub Project
• moving a project card to a specific board column or changing a project status field triggers Rascal
• Rascal updates project fields as the run progresses so the board can act as a live operational surface, not just a planning tool

This should feel like a self-completing to-do list: users steer work from GitHub, while Rascal advances the task and keeps the board current.

Why this is separate work

Rascal already supports GitHub-native issue/PR automation and runtime selection from labels.

What is missing is a project-level control surface:

• GitHub Projects v2 item events as triggers
• project field reads/writes
• status synchronization between project items and Rascal runs
• loop prevention and reconciliation when both humans and Rascal can change status

Outcome

A user can manage Rascal work from a GitHub Project board.

At minimum:

• dragging a card or updating a designated project field can queue or control a Rascal run
• Rascal can write back run progress to project fields
• the integration is explicit about which fields are user-controlled intent and which fields are system-controlled execution state

Recommended model

Do not use one status field for both user intent and Rascal-observed state.

Use two project fields:

• Workflow Status: human intent, e.g. Inbox, Ready, In Progress, Review, Done, Blocked
• Rascal Status: system state, e.g. queued, running, review, succeeded, failed, canceled

Suggested ownership:

• users update Workflow Status
• Rascal updates Rascal Status
• optional later: Rascal may also advance Workflow Status on selected milestones

This avoids feedback loops and makes the board understandable.

MVP scope

1. Support one organization-owned GitHub Project v2.
2. Resolve a project item back to its underlying issue or PR.
3. Require existing Rascal eligibility on the issue via rascal / rascal:<runtime> label.
4. Define one configurable project field transition that triggers a run, e.g. Workflow Status=Ready.
5. Update a dedicated Rascal Status field from Rascal run lifecycle events.
6. Record project item identity in Rascal state so updates are idempotent and do not require repeated lookups.
7. Add reconciliation so missed or out-of-order webhook deliveries do not leave board state stale.

Technical notes

GitHub Projects v2 appears to support the needed primitives, but the integration should be designed around API reality:

• board drag-and-drop is represented as a project item field change
• project automation uses Projects v2 APIs rather than normal repo issue webhooks alone
• project access is organization-scoped and likely requires a GitHub App or token with the right project permissions
• Projects webhook handling should be treated as eventually consistent and backed by reconciliation

Open questions

• Should GitHub Project status be the source of truth, or should Rascal run state be the source of truth with board write-back?
• Which project field transition should trigger work?
• What should happen if a user moves a card backwards while a run is active?
• Should Done mean Rascal succeeded, the issue was closed, or both?
• Should environment, product, and cloud be labels, project fields, or both?
• Do we want one task per issue, or can a project workflow create multiple distinct tasks over time?
• Is the first version single-project only, or should it support multiple projects / multiple repos immediately?

Acceptance criteria

• Rascal can identify a configured GitHub Project v2 item's backing issue or PR.
• Rascal can detect when a configured project field changes to a configured trigger value.
• Rascal queues work only for items whose backing issue is Rascal-eligible.
• Rascal writes run lifecycle changes into a dedicated project field without creating update loops.
• Rascal persists enough project metadata to reconcile and retry updates safely.
• Documentation explains the recommended board design, field ownership, permissions, and failure modes.

Explicit non-goals for MVP

• full arbitrary project automation rules engine
• replacing existing issue/PR webhook triggers
• multi-project synchronization policies
• bi-directional syncing of every board field
• automatic inference of environment/product/cloud semantics without explicit mapping