feat: add GitHub project rooms

[Solvely-Colin]

What Problem This Solves

ClickClack workspaces have channels and integrations, but no durable project boundary that links repositories, collaborators, and GitHub activity. Teams must manually reconstruct project context across GitHub and chat, while pull requests, issues, reviews, comments, and checks do not form shared collaboration threads.

Why This Change Was Made

This adds GitHub-linked project rooms: workspace managers can group one or more repositories and participants into a project, with a public collaboration channel created automatically. Signed GitHub webhooks turn pull requests and issues into channel threads, then route reviews, comments, updates, and checks into replies with delivery deduplication and retry-safe processing.

The project context API is intentionally read-only. This is a communications and context layer, not an agent harness, and it does not write back to GitHub.

User Impact

• Owners and moderators can create projects linked to multiple GitHub repositories.
• Projects appear in a dedicated workspace view and sidebar section.
• Each project receives a collaboration channel and a project-scoped GitHub identity.
• New pull requests and issues create rich thread roots.
• PR reviews, issue and PR comments, commits, merges, issue changes, and CI checks appear as replies.
• Humans and bots can retrieve repositories, participants, and channel context through the project API.
• Webhook setup presents the payload URL, one-time secret, JSON content type, and required event subscriptions.

Evidence

These are unannotated runtime screenshots from the live ClickClack deployment.

Pull request activity grouped into one collaboration thread

Project list with linked repositories and participants

Project creation with multiple repositories and human or bot participants

Live validation used real GitHub webhook deliveries. ClickClack created the rich PR root and added review and CI activity as thread replies. After deploying the issue handler, redelivering issue #2 returned 202 Accepted with updates: 1 and created a rich issue root in the project channel. Issue comments and delivery idempotency are covered by the same end-to-end webhook test.

Checks run:

• go test ./apps/api/internal/store ./apps/api/internal/store/sqlite ./apps/api/internal/store/postgres ./apps/api/internal/httpapi
• go test ./apps/api/internal/... -coverprofile=coverage.out with the repository coverage filter (85.1%)
• pnpm --filter @clickclack/web typecheck
• pnpm --filter @clickclack/sdk-ts typecheck
• pnpm --filter @clickclack/web test
• pnpm lint
• Production web and SDK builds
• Linux Docker build, cloned-production migration smoke test, and live deployment health checks

Webhook failure and redelivery proof

Inspect the redacted runtime evidence for existing-database migration, invalid-signature rejection, explicit failed-delivery recovery, duplicate suppression, and single-thread preservation on the live deployment.

Retry coverage includes SQLite and Postgres lifecycle and upgrade tests, stale-processing lease reclaim in both backends, and an HTTP handler test that injects a failure after claim and successfully processes the same delivery ID on redelivery.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 27, 2026, 1:26 PM ET / 17:26 UTC.

ClawSweeper review

What this changes

Adds GitHub-linked project rooms with workspace UI and APIs, SQLite/Postgres project storage, and signed GitHub webhooks that group repository activity into ClickClack channel threads.

Merge readiness

⚠️ Ready for maintainer review - 4 items remain

Keep this PR open for maintainer product review. The patch is a substantial, coherent new ClickClack capability with real runtime evidence and no remaining discrete correctness finding, but it introduces a durable project data model, public project APIs, and webhook-driven message delivery that need explicit long-term ownership and upgrade support approval before merge.

Priority: P2
Reviewed head: 4b1b30e39df3154a7d0d11511e15caacac06df6b
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	The implementation and proof are strong, while the remaining gate is maintainer acceptance of the durable product, API, migration, and delivery contract.
Proof confidence	🦞 diamond lobster (5/6)	Sufficient (logs): The PR includes visible project-room screenshots and redacted live evidence for existing-database upgrade, signature rejection, failed-delivery recovery, duplicate suppression, and thread preservation.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (logs): The PR includes visible project-room screenshots and redacted live evidence for existing-database upgrade, signature rejection, failed-delivery recovery, duplicate suppression, and thread preservation.
Evidence reviewed	5 items	Feature surface: The branch adds workspace project list/create routes, project/context reads, and a GitHub project webhook route; the central capability is not a small isolated UI adjustment. Persistent upgrade surface: The patch adds paired SQLite and Postgres migrations for projects, repository/member relations, webhook delivery state, and pull-request thread mapping. SQLite also includes a follow-up table-rebuild migration for delivery retry state. Retry behavior: The supplied patch includes lifecycle coverage for failed and stale GitHub delivery claims in both database backends and HTTP handler coverage for redelivery after a post-claim failure.
Findings	None	None.
Security	None	None.

How this fits together

Project rooms extend ClickClack workspaces by linking repositories and participants to an automatically created collaboration channel. GitHub webhook events enter through a signed endpoint, are deduplicated and retried in persistent storage, and become thread roots or replies in that channel.

flowchart LR
  Managers[Workspace managers] --> Project[GitHub project room]
  Project --> Database[Project and delivery storage]
  Project --> Channel[Collaboration channel]
  GitHub[GitHub webhook delivery] --> Verify[Signature and retry check]
  Verify --> Routing[Issue and PR thread routing]
  Routing --> Channel

Loading

Decision needed

Question	Recommendation
Should ClickClack adopt GitHub-linked project rooms, their public project/context API, and their persistent webhook-delivery model as supported core product surface?	Sponsor core project rooms: Approve the durable project and webhook contract, then continue normal maintainer review toward merging this feature.

Why: The implementation is broad and proof-backed, but deciding whether these durable APIs, migrations, and GitHub integration semantics belong in the supported core cannot be resolved from patch correctness alone.

Before merge

• Resolve merge risk (P1) - Merging creates four database migrations across SQLite and Postgres, including a SQLite table rewrite for webhook-delivery state; maintainers need to accept the permanent upgrade and recovery contract.
• Resolve merge risk (P1) - The new public project/context endpoints and webhook event-to-thread mapping become long-term compatibility and message-delivery commitments, including retry, duplicate suppression, and repository event coverage.
• Complete next step (P2) - The remaining blocker is explicit maintainer product and upgrade-contract approval, not a narrow mechanical repair.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Patch surface	98 files affected; 5,731 additions and 162 deletions	The feature spans API, storage, migrations, generated SQL bindings, SDK contract, web UI, tests, and embedded assets rather than a narrow integration change.
Persistent migrations	4 new migrations across 2 database backends	Upgrade behavior and durable delivery state are material merge decisions even with passing tests.
Validation evidence	3 runtime screenshots plus redacted webhook recovery proof	The contributor supplied both visible UI evidence and live signed-webhook/upgrade evidence beyond unit and CI checks.

Merge-risk options

Maintainer options:

1. Approve the durable contract before merge (recommended)
   Confirm that the project API, dual-backend migrations, and webhook retry behavior are supported upgrade commitments, then merge after normal maintainer review.
2. Narrow the initial contract
   Require a smaller first release if maintainers do not want to support all project endpoints and GitHub event routing semantics immediately.
3. Pause pending product sponsorship
   Leave the PR open but do not merge until a maintainer explicitly sponsors GitHub project rooms as core functionality.

Technical review

Best possible solution:

If maintainers want GitHub project rooms as a supported core capability, accept the project API and migration contract explicitly, then merge this implementation with ongoing ownership for webhook compatibility and delivery semantics.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a feature request rather than a report of broken current behavior. The contributor nevertheless supplied high-confidence live evidence for the new UI, signed webhook handling, upgrade, retry, and duplicate-suppression paths.

Is this the best way to solve the issue?

Unclear. The patch is internally coherent and evidence-backed, but its broad durable API and storage contract needs maintainer product acceptance before it can be called the best long-term solution.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against f59e3aa96064.

Labels

Label changes:

• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• remove rating: 🦐 gold shrimp: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.

Label justifications:

• P2: This is a substantial but non-emergency feature proposal whose merge decision is primarily product and upgrade-contract review.
• merge-risk: 🚨 compatibility: New SQLite/Postgres migrations and public project/context endpoints create supported upgrade and API contracts for existing deployments.
• merge-risk: 🚨 message-delivery: Signed GitHub webhook events are persisted, retried, deduplicated, and routed into channel threads, so delivery semantics must remain stable after merge.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (logs): The PR includes visible project-room screenshots and redacted live evidence for existing-database upgrade, signature rejection, failed-delivery recovery, duplicate suppression, and thread preservation.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR includes visible project-room screenshots and redacted live evidence for existing-database upgrade, signature rejection, failed-delivery recovery, duplicate suppression, and thread preservation.

Evidence

What I checked:

• Feature surface: The branch adds workspace project list/create routes, project/context reads, and a GitHub project webhook route; the central capability is not a small isolated UI adjustment. (apps/api/internal/httpapi/server.go:169, 4b1b30e39df3)
• Persistent upgrade surface: The patch adds paired SQLite and Postgres migrations for projects, repository/member relations, webhook delivery state, and pull-request thread mapping. SQLite also includes a follow-up table-rebuild migration for delivery retry state. (apps/api/internal/store/sqlite/migrations/0039_projects.sql:1, 4b1b30e39df3)
• Retry behavior: The supplied patch includes lifecycle coverage for failed and stale GitHub delivery claims in both database backends and HTTP handler coverage for redelivery after a post-claim failure. (apps/api/internal/store/postgres/projects_test.go:12, 4b1b30e39df3)
• Real runtime proof: The PR body and follow-up comment provide redacted live-deployment evidence for an existing SQLite upgrade, invalid-signature rejection, failed-delivery recovery, completed-delivery suppression, and preservation of a single issue thread. (docs/proof/github-project-rooms/webhook-runtime-proof.md:1, 4b1b30e39df3)
• Repository SQL policy: The project policy requires SQL changes to originate in schema/query sources and sqlc generation; the patch updates both backend SQL schema/query files together with their generated storedb outputs. (AGENTS.md:1, 4b1b30e39df3)

Likely related people:

• shakkernerd: Merged prior ClickClack work on chat composer and thread/media behavior, making them the closest identifiable current-history routing candidate from the supplied repository context; ownership of the new project API is otherwise not established. (role: adjacent channel and thread contributor; confidence: low; commits: 6a306ae8cf7c; files: apps/web/src/ChatApp.svelte, apps/web/src/components/navigation/Sidebar.svelte)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Obtain explicit maintainer sponsorship for the core project-room and webhook contract.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (5 earlier review cycles)

• reviewed 2026-07-27T16:08:14.913Z sha 8f4178a :: needs real behavior proof before merge. :: none
• reviewed 2026-07-27T16:25:17.388Z sha 2df52a3 :: needs real behavior proof before merge. :: [P1] Reclaim failed webhook deliveries before ignoring retries
• reviewed 2026-07-27T16:33:25.732Z sha 2df52a3 :: needs real behavior proof before merge. :: [P1] Reclaim failed webhook deliveries before ignoring retries
• reviewed 2026-07-27T17:12:37.833Z sha 5a77781 :: needs real behavior proof before merge. :: none
• reviewed 2026-07-27T17:21:25.818Z sha 4b1b30e :: needs maintainer review before merge. :: none

[Solvely-Colin]

@clawsweeper re-review

Added the requested webhook and upgrade evidence at docs/proof/github-project-rooms/webhook-runtime-proof.md, and linked it from the PR body.

The redacted live proof now covers:

• existing populated SQLite database upgrade and public health check;
• invalid signature rejection (401) with no delivery row;
• controlled failed delivery followed by successful signed replay (202 accepted) and transition back to complete;
• completed-delivery replay (202 duplicate);
• one issue thread before and after recovery and duplicate replay.

Automated coverage at head 4b1b30e includes SQLite and Postgres lifecycle, stale-processing reclaim, pre-migration upgrade fixtures, and an HTTP post-claim failure followed by successful redelivery of the same delivery ID.

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Review in progress
• Detail: The exact-review queue leased this run; Codex is reviewing the item.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/30289090834
• Updated: 2026-07-27T17:24:53.482Z

[PollyBot13]

This is excellent and overlaps strongly with #126 and #129. I think this may be the faster route: use this PR’s native project configuration, webhook handling and delivery machinery, then add dedicated work-item rooms as a focused follow-up.

GitHub should be the first connector, but the underlying pattern is broader:

external work item → durable ClickClack room → bounded updates and collaboration → archive/reopen

Examples include one channel per pull request, security incident, deployment, support escalation or Jira/Linear issue. The external system remains authoritative; ClickClack owns the durable collaboration record.

The main presentation difference is that this PR creates one project channel with a thread per PR or issue, while #129 proposes one managed channel per work item. Could we treat that as a configurable strategy—current thread behavior as the default, with a later channel_per_work_item mode?

That follow-up could reuse this PR’s project and delivery plumbing while:

• identifying items by connector, resource type and stable external identity;
• creating or restoring the same channel on open/reopen;
• routing bounded status updates into that channel;
• archiving it when the work item closes or resolves;
• tolerating duplicate and out-of-order deliveries through state reconciliation and semantic nonces.

I am not suggesting turning this PR into a general connector framework. It would be useful, however, to preserve an extension seam so the core project model and target-routing concept do not become unnecessarily GitHub-specific. GitHub-specific payloads, credentials and delivery tables can remain inside the GitHub connector.

One point that may need resolving now: project channels appear to be hard-coded as public. Could project creation accept an explicit channel kind so private repositories—and future security incidents—cannot inadvertently become workspace-public?

If this direction fits, I’m happy to reshape #129 into the focused reusable work-item-room follow-up and narrow or retire overlapping parts of #126 rather than maintain a competing architecture.

#126
#129

[PollyBot13]

One concrete extension seam may preserve both this PR’s approach and future connectors.

The current durable mapping—(project_id, repository_id, pull_number) → root_message_id—works well for GitHub thread mode. Could it be represented or wrapped internally as:

(connector, resource_type, external_id) → (target_type, target_id, canonical_route)

This need not turn #131 into a connector framework. GitHub can remain the only implementation and thread the only initial target type. It would simply allow a later channel target for pull requests, security incidents, deployments or tickets without replacing the project and delivery machinery.

Two related details seem worth preserving now:

• allocate a canonical linkable route when the work-item target is created;
• make channel visibility explicit rather than hard-coding public.

#126 and #128 contain reconciliation, migration and canonical-link tests that may be reusable rather than reimplemented. I’m happy to contribute a focused follow-up once the preferred boundary is clear.

#126
#128