Add GitHub PR workrooms as durable threads in project channels

[PollyBot13]

Direction

A pull request is more than a diff. It accumulates intent, checks, review
findings, decisions, agent work, and the reason the final code exists. Those
facts are currently split between GitHub, chat, local agent sessions, and CI
logs.

The desired experience is:

A ClickClack channel represents a project or repository. Each GitHub pull
request gets one durable thread in that channel where humans and agents can
work with its current state and important transitions close at hand.

The thread root is a live PR card. Its replies form the workroom. Merge, close,
and reopen update the same workroom instead of creating, archiving, or replacing
channels.

GitHub remains authoritative for repository state, reviews, checks, and merge
decisions. ClickClack owns the durable conversation and its visibility. The
adapter is a deliberately thin, read-only bridge.

This direction is inspired by the open-source
Buzz “branch as room” product story. It adapts
that user experience to ClickClack's existing API-first architecture; it does
not add Git hosting, a workflow engine, or provider authority to ClickClack.

Why this issue was reframed

The original proposal used one managed ClickClack channel per pull request.
That made external channel identity, reconciliation, naming, archive behavior,
and visibility part of the required core contract.

PR #131 explored a richer GitHub Projects room subsystem. Maintainer review
closed it because the approximately 11,000-line patch combined too many product
surfaces while leaving a central authorization boundary unresolved: private
repository content could reach workspace-public ClickClack channels, and source
participants are not an access-control list for the destination channel.
Maintainer guidance explicitly kept the narrower product and security decision
in this issue.

A thread-first model preserves the useful product idea while removing the two
largest risks:

• one configured ClickClack project channel can organize many PR workrooms;
• the adapter does not create channels or derive ClickClack visibility from
  GitHub membership;
• existing message nonce recovery provides durable external identity without a
  new provider-identity schema;
• existing message editing keeps the root PR card current;
• existing flat threads, idempotent replies, and public routes provide the
  collaboration and linking surface;
• closing or reopening a PR changes the workroom state without changing the
  channel lifecycle.

PR #131 remains useful design research, but a successor should start from
current main and should not reuse its subsystem as an implementation base.

Product behavior

For each explicitly configured public GitHub repository:

1. An operator maps the repository to an existing ClickClack project channel.
   Provider payloads cannot create a channel, choose its kind, or change its
   visibility.
2. A supported PR webhook is verified, then treated as a hint to fetch current
   authoritative GitHub state.
3. The adapter finds or creates one root message using a deterministic nonce
   such as github:<repository-id>:pr:<number>:root.
4. The root message is a concise PR card containing title, author, base/head,
   draft/open/merged/closed state, review/check summary, and the canonical
   GitHub link. Later reconciliation edits that same bot-authored root.
5. Meaningful state transitions become bounded, idempotent thread replies.
   Ordinary human and agent discussion remains untouched in the same thread.
6. Merge or close updates the card and adds one final transition reply. Reopen
   restores the same root and history.

Every delivery reconciles current state rather than applying an assumed event
order. Duplicate and out-of-order deliveries therefore converge instead of
rolling the workroom backward. The adapter recovers roots and replies through
ClickClack's public nonce APIs and keeps no second authoritative copy of PR or
conversation state.

Implementation boundary

The GitHub App/webhook runtime should live in a small companion adapter rather
than in the ClickClack server. This follows the repository precedent of keeping
provider connectors outside core while upstreaming only reusable, generic
primitives.

The implementation PRs below are intended for that companion adapter and will
be linked from this issue when opened. Each PR will reference this issue and
include its own focused tests and real-behavior proof. No implementation has
started as part of this reframe.

Current main appears to provide the required core surface already:

• create a channel root with a deterministic nonce;
• recover a root by nonce after interruption or restart;
• edit the bot-authored root;
• create idempotent thread replies;
• fetch the bounded thread;
• resolve a canonical route for the thread root;
• consume durable workspace events when ClickClack-side observation is useful.

No ClickClack core PR is assumed. If an end-to-end proof identifies a concrete
missing generic primitive, that gap should receive its own narrowly scoped issue
and PR rather than expanding the adapter patch.

Proposed delivery sequence

Working titles are listed now so related work can be coordinated and automation
can track the intended sequence. Links and exact titles will be updated when a
PR opens.

• PR A — feat(github): create public PR workrooms in configured channels

  • GitHub App/webhook skeleton, raw-body signature verification, installation
    and repository allowlist, and explicit repository-to-channel mapping.
  • Public repositories only; private, unknown, or visibility-ambiguous sources
    fail before any ClickClack write.
  • Read-only authoritative PR fetch.
  • Deterministic root nonce, interrupted-create recovery, root-card creation
    and update for opened/synchronize events.
  • Duplicate delivery, invalid signature, restart recovery, and physical local
    ClickClack proof included in the same PR.

• PR B — feat(github): reconcile PR lifecycle in existing workrooms

  • Draft/ready, merged/closed, and reopened transitions.
  • Deterministic transition-reply nonces and current-state fingerprints.
  • Out-of-order delivery convergence without modifying human replies.
  • Exact-head proof that close and reopen retain the root ID, route, and thread
    history.

• PR C — feat(github): summarize reviews and checks in PR workrooms

  • Bounded review and completed-check summaries.
  • No job-by-job, commit-by-commit, comment, or full timeline mirroring.
  • Deduplication and supersession rules that keep the thread useful under CI
    churn.
  • Exact-head noisy-event and bounded-rendering proof.

Possible later providers—issues, deployments, incidents, tickets, or agent
assignments—should reuse the adapter-side work-item model only after the PR
workroom proves the contract. Dedicated per-item channels can remain a later
option for work that genuinely needs a separate audience or lifecycle.

V1 scope

• One reference GitHub App adapter deployed outside the ClickClack server.
• Public repositories only.
• Explicit installation, repository, ClickClack workspace, and destination
  channel configuration.
• Read-only GitHub permissions for repository metadata, pull requests, reviews,
  and checks as required by the delivered phase.
• pull_request first, followed by bounded pull_request_review and
  check_suite handling in the staged sequence above.
• Deterministic ClickClack nonces for the root and semantic lifecycle replies;
  GitHub delivery IDs are diagnostic correlation values, not identity.
• Sanitized and length-bounded Markdown, validated GitHub URLs, and secret-safe
  logs.
• Fake-provider tests plus real local ClickClack lifecycle proof.

Non-goals

• Creating one ClickClack channel per PR.
• Creating, renaming, archiving, or reconciling ClickClack channels from GitHub
  payloads.
• Private-repository synchronization before ClickClack has a separately agreed
  destination authorization contract.
• Treating GitHub participants or project members as ClickClack ACLs.
• Reusing ClickClack's GitHub OAuth login credentials.
• Posting ClickClack discussion back to GitHub, or approving, merging, rebasing,
  closing, or otherwise modifying a PR.
• Mirroring every comment, commit, label, workflow job, or timeline event.
• A generic connector runtime, provider schema, work-item database, queue
  service, or new ClickClack room type.
• Requiring Reconcile externally managed channels by provider identity #125/feat: reconcile externally managed channels #126 managed-channel reconciliation, Add copyable links for channel messages and thread roots #127/feat: add copyable message citation links #128 citations, or
  the closed feat: add GitHub project rooms #131 implementation.

Security and privacy contract

• The destination ClickClack channel is operator-configured and already exists.
  A webhook cannot select or downgrade visibility.
• V1 verifies from authoritative GitHub state that a configured repository is
  public before writing any provider-derived content.
• Private, unknown, removed, or visibility-ambiguous repositories fail closed.
• Webhook signatures are checked over the raw request body with constant-time
  comparison before JSON processing.
• Invalid signatures, oversized bodies, unsupported events, and unconfigured
  installations fail before ClickClack writes.
• GitHub App credentials, webhook secrets, ClickClack tokens, and raw payloads
  are never posted into channels or emitted in logs.
• Provider text is untrusted Markdown: fields are bounded, control characters
  are normalized or rejected, and links are accepted only from validated GitHub
  URLs.
• GitHub remains authoritative. The adapter is read-only and cannot turn a
  ClickClack reaction or message into repository authority.

Acceptance criteria

• Opening a configured public PR creates exactly one root card in the configured
  channel and exposes one linkable thread workroom.
• Replay, concurrent duplicate delivery, and restart between ClickClack write
  and acknowledgement do not create a second root or semantic reply.
• Title, head, draft, review, check, and lifecycle changes update the same
  workroom without replacing its human discussion.
• Out-of-order deliveries reconcile current GitHub state rather than rolling the
  card backward.
• Merge and ordinary close are distinct; reopen retains root ID, canonical
  route, and thread history.
• Invalid signatures, unknown repositories, private repositories, wrong
  workspace/channel bindings, revoked credentials, and missing ClickClack scope
  fail without leaking provider content.
• The adapter uses documented public ClickClack API/SDK contracts and needs no
  server database or plugin access.
• Each staged PR carries focused automated tests and inspectable exact-head
  runtime proof for the behavior it introduces.

Related work disposition

• feat: externally managed channels, sidebar sections, archive hiding, embed channel view #102 supplies useful managed-channel metadata but channel reconciliation is
  no longer required for this thread-first MVP.
• Reconcile externally managed channels by provider identity #125 remains a separate product decision for provider-owned channels; closed
  PR feat: reconcile externally managed channels #126 is not a dependency.
• Add copyable links for channel messages and thread roots #127 remains an independent citation proposal; closed PR feat: add copyable message citation links #128 is not a
  dependency because thread routes already resolve lazily.
• Add an optional purpose line to channel headers #118/feat: add channel purpose lines #119 and Expose message topics in the web composer and channel timeline #120/feat: expose message topics in the web app #121 are independent presentation and organization ideas,
  not MVP blockers.
• feat: add CLI reaction commands #123, fix: let the thread panel shrink below its 370px content floor #124, existing message editing, nonce recovery, threads, and thread
  routes are complementary existing primitives.
• feat: add GitHub project rooms #131 provides useful UX and webhook lessons, but its code and private-content
  authorization model are not the foundation of this implementation.

Remaining coordination question

The recommended path is to begin with PR A in a companion adapter repository,
link it here, and let its end-to-end proof reveal whether any ClickClack core
change is actually necessary. If maintainers prefer an examples/ location in
this repository, the same staged contract can move without changing the product
or security boundary.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed August 2, 2026, 7:14 AM ET / 11:14 UTC.

Summary
Keep this issue open for a maintainer security-boundary decision. Current main provides the ClickClack message, thread, idempotency, edit, and route primitives the proposal would consume, but it does not implement the requested GitHub App webhook adapter or establish its supported deployment and authorization contract.

Reproducibility: not applicable. this is a proposal for a new GitHub App integration rather than a report of broken current behavior. Source inspection does confirm that the underlying ClickClack message and thread primitives already exist.

Root-cause cluster
Relationship: canonical
Canonical: #129
Summary: This issue is the canonical narrowed thread-first direction; the earlier project-room pull request was closed and its managed-channel approach is not the implementation path for this remaining decision.

Members:

• superseded: feat: add GitHub project rooms #131 - The issue body records that this larger GitHub Projects room implementation was closed after authorization concerns and that its code is not the foundation for the narrowed thread-first direction.
• adjacent_distinct: Reconcile externally managed channels by provider identity #125 - That issue concerns provider-identity reconciliation for dedicated externally managed channels, while this issue deliberately avoids provider-created channels and uses threads in an operator-selected existing channel.
• adjacent_distinct: Add copyable links for channel messages and thread roots #127 - Stable thread-root links are a complementary primitive, but the requested GitHub App lifecycle and authorization contract remain separate work.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.

Maintainer decision needed

Question	Recommendation
Should ClickClack endorse a reference GitHub App companion adapter that is limited to explicitly mapped public repositories and existing destination channels, with no private-repository synchronization or provider-derived channel visibility?	Endorse public-only companion adapter: Approve a separately deployed, operator-configured adapter that verifies signatures, fetches authoritative public GitHub state, and writes only through a scoped ClickClack bot.

Why: Current core APIs can support the thread-first design, but source and docs do not define the deployment owner, credential boundary, or repository-to-channel authorization policy for such an adapter.

Next step
A maintainer must choose the supported GitHub App deployment and authorization boundary before a safe implementation PR can be scoped.

Security
Needs attention: This security-sensitive feature proposal needs an explicit destination authorization and public-repository verification contract before implementation can be reviewed as safe.

Review details

Best possible solution:

Adopt a maintainer-approved companion-adapter contract limited initially to operator-mapped public repositories, then deliver the staged GitHub App implementation with real lifecycle and failure-mode proof outside the ClickClack server.

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

Not applicable: this is a proposal for a new GitHub App integration rather than a report of broken current behavior. Source inspection does confirm that the underlying ClickClack message and thread primitives already exist.

Is this the best way to solve the issue?

Unclear: the thread-first companion-adapter direction reuses current primitives and avoids per-PR channel lifecycle, but a maintainer must first confirm the deployment and authorization boundary before it is the best supported solution.

AGENTS.md: found, but no applicable review policy affected this item.

Remaining risk / open question:

• Without an explicit operator-controlled deployment and authorization contract, a GitHub App adapter could write public-repository content into an unintended ClickClack channel or later expand toward private-repository data exposure.
• The proposal spans an external service, GitHub credential handling, webhook verification, repository visibility checks, and ClickClack bot configuration; starting implementation before the supported boundary is endorsed would create a competing integration model.

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

Label changes

Label justifications:

• P2: This is a bounded but substantial integration proposal whose security and product contract must be settled before implementation.
• impact:security: The requested behavior explicitly governs webhook authentication, provider content handling, repository visibility, credentials, and destination-channel authorization.

Evidence reviewed

Security concerns:

• [medium] Define adapter authorization before implementation
  The proposed adapter would ingest provider-controlled events and write durable content into ClickClack; maintainers must approve the operator mapping, public-repository verification, credential storage, and failure-closed rules first.
  Confidence: 0.94

What I checked:

• Current core message primitives: Current API documentation confirms idempotent root-message creation by nonce, interrupted-create recovery by nonce, author-only message editing, and durable message update events; these are reusable adapter-facing primitives, not a GitHub synchronization implementation. (docs/features/messages.md:35, 72931b10f083)
• Current core thread primitives: Current documentation defines flat threads with nonce-idempotent replies, matching the proposed durable workroom shape while leaving provider lifecycle handling outside this API contract. (docs/features/threads.md:9, 72931b10f083)
• Authorization boundary is implementation-sensitive: The existing integration model binds an installation and bot user to a workspace and explicitly says it is metadata rather than a runtime plugin loader; a GitHub App adapter therefore needs an approved deployment and operator-configuration boundary before implementation starts. (docs/features/integrations.md:9, 72931b10f083)
• No GitHub App webhook implementation on main: The current GitHub server surface is OAuth configuration and login behavior, while a repository-wide search found no source implementation for a GitHub webhook or GitHub App ingestion path. (apps/api/internal/httpapi/github.go:23, 72931b10f083)
• Feature-history routing: Local history identifies retry-safe messaging work as commit 718ddb1 by Shakker and initial product/GitHub-auth work as commits by Peter Steinberger. Some older promised objects are unavailable in this partial checkout, so ownership confidence remains medium. (apps/api/internal/httpapi/server.go:1135, 718ddb1408fb)
• Repository review policy: The full repository AGENTS.md was read; its sqlc instruction is not triggered because this item has no proposed schema or query change. (AGENTS.md:1, 72931b10f083)

Likely related people:

• Peter Steinberger: Local history attributes initial ClickClack application work and GitHub organization-auth work to Peter Steinberger, and the remaining decision concerns the product boundary around the existing GitHub-auth surface. (role: initial product and GitHub-auth contributor; confidence: medium; commits: 5cea1a52cbf8, c11251f31358; files: apps/api/internal/httpapi/github.go, docs/features/integrations.md)
• Shakker: The nonce and recovery behavior proposed for root and lifecycle replies is closely related to Shakker's retry-safe optimistic messaging history. (role: retry-safe messaging contributor; confidence: medium; commits: 718ddb1408fb; files: apps/api/internal/httpapi/server.go, docs/features/messages.md, docs/features/threads.md)

How this review workflow works

• 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.