Generalize #129 into project rooms for Workboard and external work items

[jjjhenriksen]

What Problem This Solves

#129 describes GitHub PR workrooms as durable threads in project channels. The underlying product need is broader: a project channel should be able to organize durable, linkable threads for work items, including agent-owned Workboard tasks, without inventing a new channel or duplicating provider-specific room logic for every source.

A GitHub-only implementation would make Workboard and future providers build parallel thread lifecycles. This issue proposes a general project-room contract, using #129 as the first concrete GitHub example.

Why This Change Was Made

Generalize #129 around a stable work-item-to-thread relationship:

• An operator maps a project or repository to an existing ClickClack project channel.
• Each linked work item gets one durable root thread in that channel.
• The root is a bounded, editable summary; replies provide the workroom.
• Duplicate, concurrent, out-of-order, and restarted deliveries converge on the same root and semantic replies.
• Provider state remains authoritative in the provider; ClickClack owns the durable conversation and its visibility.

The first adapters would be:

1. GitHub PRs, following Add GitHub PR workrooms as durable threads in project channels #129: GitHub owns PR state, reviews, checks, and merge decisions.
2. OpenClaw Workboard cards: Workboard owns agent assignment, execution lifecycle, sessions, proof, and artifacts; ClickClack provides the shared project-room conversation.

A Workboard card should explicitly create or link a ClickClack thread using stable references. Workboard already supports linked task, run, session, and source-URL references in its card contract: Workboard documentation, Workboard implementation.

User Impact

Operators can follow agent work and external work-item state in one project channel, while still opening the authoritative Workboard card or GitHub source. A single project channel can contain many durable workrooms without creating one channel per task or PR.

The boundaries remain explicit:

• GitHub is authoritative for repository state.
• Workboard is authoritative for local agent execution state.
• ClickClack is authoritative for the durable project-room conversation.
• Provider participants never determine ClickClack channel visibility or access.
• Workboard cards do not automatically create public threads without an explicit project/channel mapping.

Proposed Contract

An adapter supplies:

• a stable provider and work-item identity;
• a canonical source URL;
• a bounded summary and current-state fingerprint;
• an operator-configured destination project/channel;
• deterministic root and semantic-transition nonces;
• optional links between the provider item, Workboard card, and ClickClack thread.

Provider content is untrusted Markdown and must remain sanitized and length-bounded. Any missing or ambiguous destination authorization fails closed before a ClickClack write.

Acceptance Criteria

• One configured work item produces exactly one recoverable root thread.
• Duplicate, concurrent, out-of-order, and restarted deliveries do not create duplicate roots or semantic replies.
• A Workboard card can explicitly create, reopen, and reuse the same ClickClack thread.
• Add GitHub PR workrooms as durable threads in project channels #129 remains a complete first adapter example for GitHub PR lifecycle reconciliation.
• No provider-derived channel creation, renaming, archiving, visibility changes, or GitHub writeback is required.
• The first implementation can remain adapter-side; a ClickClack core change is opened separately only when proof identifies a missing generic primitive.

Related Work

• Extends #129, the GitHub PR workroom example.
• #131 is useful prior design research but is not an implementation dependency; its broad channel lifecycle and authorization model should not be reused.
• Workboard is an OpenClaw-side source of agent-owned work, not a replacement for GitHub Issues, Linear, Jira, or ClickClack project-room history.

Open Questions

• Should the Workboard-to-ClickClack link be implemented entirely in a companion adapter, or should OpenClaw expose a small first-class integration hook?
• Should the first Workboard flow be explicit card action only, or also support an operator-configured dispatch rule?
• Should future providers reuse the same adapter-side work-item contract before any new ClickClack core primitive is added?

Evidence

• #129 defines the thread-first GitHub PR workroom direction and its security boundary.
• OpenClaw Workboard documents local agent-owned cards, linked references, sessions, execution metadata, proof, and artifacts.

[clawsweeper]

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

Summary
This remains a distinct product-direction proposal, not an implemented feature or a narrow existing-behavior bug. Current main supplies the durable-thread primitives it would consume, but no current GitHub/Workboard provider adapter or settled ownership boundary implements the requested work-item contract; keep it open for a maintainer scope decision.

Reproducibility: not applicable. this is a requested capability rather than a report of broken current behavior. Source inspection confirms reusable message and thread primitives, but there is no existing provider/work-item flow to reproduce.

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 the first project-room delivery be a GitHub companion adapter, an explicit Workboard-to-ClickClack card action, or a deliberately minimal shared adapter contract outside ClickClack core?	Prove GitHub first: Keep #129 as the first companion adapter and defer Workboard generalization until its runtime proof identifies a concrete shared gap.

Why: Current main already covers durable thread creation, recovery, editing, replies, routes, and access checks; selecting provider order and the companion-versus-core boundary is a product and security-contract choice rather than a mechanical repair.

Next step
A maintainer must select the first provider and companion-versus-core boundary before any focused implementation can be responsibly scoped.

Security
Needs attention: The proposal is security-sensitive because any adapter must keep provider state separate from destination-channel authorization and fail closed on ambiguous mappings.

Review details

Best possible solution:

Choose one companion-adapter path—beginning with the GitHub reference flow or an explicit Workboard card action—then upstream only a narrowly demonstrated missing ClickClack primitive after end-to-end proof.

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

Not applicable: this is a requested capability rather than a report of broken current behavior. Source inspection confirms reusable message and thread primitives, but there is no existing provider/work-item flow to reproduce.

Is this the best way to solve the issue?

Unclear: an adapter-side first implementation is the narrowest direction supported by current main, but maintainers must choose whether GitHub or an explicit Workboard action proves the contract first.

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

Remaining risk / open question:

• A generic core contract could prematurely commit ClickClack to provider identity, mapping, and lifecycle semantics before the GitHub reference adapter proves which primitive is genuinely missing.
• Workboard and external-provider content must not select or alter ClickClack visibility; the destination authorization and fail-closed behavior need an explicit owner before implementation begins.

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

Label changes

Label changes:

• add clawsweeper:needs-security-review: Current issue advisory state selects this label.

Label justifications:

• P3: This is a speculative but coherent product-direction feature with no established current user-facing regression.
• impact:other: The proposal affects project-work organization and provider-to-conversation integration, which does not fit the more specific issue impact categories.

Evidence reviewed

Security concerns:

• [medium] Preserve destination authorization outside provider state
  A future adapter must require an explicit operator mapping and must not derive ClickClack visibility or access from GitHub or Workboard participants.
  Confidence: 0.93

What I checked:

• Current durable-thread API: Current docs specify idempotent root creation by nonce, recovery through nonce lookup, and author-scoped message editing; these are reusable primitives but do not define provider work-item identity or mapping. (docs/features/messages.md:22, 4ed4de8ae861)
• Current thread contract: Current docs define one flat reply list per root and nonce-idempotent thread replies, which supports the proposed conversation shape without establishing a provider adapter contract. (docs/features/threads.md:14, 4ed4de8ae861)
• Current source has no requested adapter: A current-tree search found no GitHub webhook, Workboard, project-room, work-item, or provider-adapter implementation outside unrelated provider audit fields. (apps/api/internal/httpapi/server.go:974, 4ed4de8ae861)
• Authorization baseline: Thread route tests verify that unauthorized or wrong-workspace resolution fails closed, but this does not decide how a provider adapter establishes an authorized destination channel. (apps/api/internal/store/sqlite/route_ids_test.go:93, 4ed4de8ae861)
• Related work remains distinct: The provided related-item context shows Add GitHub PR workrooms as durable threads in project channels #129 is still open as the GitHub PR reference adapter, while this issue asks whether that adapter model should generalize to Workboard and future providers.
• Feature-history signal: The current conversation and route surfaces trace to commit 60cb6b8 by Shakker; later channel-model work includes commits 961e46f and e455d43. (docs/features/threads.md:17, 60cb6b85e248)

Likely related people:

• Shakker: Current thread documentation attributes the endpoint and nonce-idempotency contract to the baseline commit, and route code still traces to that feature history. (role: introduced the current thread and route baseline; confidence: medium; commits: 60cb6b85e248; files: docs/features/threads.md, apps/api/internal/store/sqlite/route_ids.go)
• Jacqueline Henriksen: Recent current-main history shows adjacent channel-model work in the message and route implementation area. (role: recent channel-model contributor; confidence: medium; commits: 961e46f7f2b0; files: apps/api/internal/store/sqlite/mutations.go, apps/api/internal/store/sqlite/routes.go)
• Peter Steinberger: Recent history includes channel display-title work in the same current channel and message surface relevant to presenting project-room roots. (role: recent channel metadata contributor; confidence: low; commits: e455d43809a0; files: apps/api/internal/httpapi/mutations.go, apps/api/internal/store/sqlite/mutations.go)

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.

[PollyBot13]

Thanks for consolidating #129 into this issue. For continuity, there is already a temporary public draft implementation review here:

PollyBot13/clickclack-integrations#1

This is not an official repository or merge-ready product PR. It is a security-focused GitHub-first foundation slice: immutable provider/destination identities, durable delivery receipts, per-PR cross-process serialization, raw-body webhook verification, origin canonicalization, and inert rendering. It deliberately does not yet include live GitHub/ClickClack adapters, setup UI, deployment, or a generic provider/work-item framework.

That makes it useful evidence for #140 rather than an alternative to it: a concrete first-provider slice can show which durability and authorization mechanics are truly reusable by Workboard, and which should remain provider-specific. The draft intentionally avoids generalizing those semantics before a second provider proves the overlap.

The proposed official home, openclaw/clickclack-integrations, still does not exist. Unless maintainers prefer a different direction, I would treat #140 as canonical, keep this draft unmerged as review material, and use the GitHub slice as the first-provider proof before extracting any shared Workboard/project-room contract.