docs(adr): add ADR 0086 for conversation surface participation

docs/ADRs/0076-slash-command-entity-context-separation.md

@@ -17,6 +17,9 @@ Date: 2026-07-28
 
 Accepted
 
+Extends entity-context rules for conversation surfaces in
+[ADR 0086](0086-conversation-surface-for-agent-participation.md).
+
 Refines [ADR 0002](0002-initial-fullsend-design.md) (initial design) and
 reinforces [ADR 0020](0020-composable-single-responsibility-agents-with-individual-sandboxes.md)
 (single-responsibility agents).

docs/ADRs/0086-conversation-surface-for-agent-participation.md

@@ -0,0 +1,136 @@
+---
+title: "86. Conversation surface for agent participation"
+status: Accepted
+relates_to:
+  - agent-architecture
+  - agent-infrastructure
+  - security-threat-model
+topics:
+  - discussions
+  - dispatch
+  - conversation
+  - tracker
+  - portability
+  - slash-commands
+---
+
+# 86. Conversation surface for agent participation
+
+Date: 2026-08-11
+
+## Status
+
+Accepted
+
+Builds on [ADR 0005](0005-forge-abstraction-layer.md),
+[ADR 0017](0017-credential-isolation-for-sandboxed-agents.md) /
+[ADR 0046](0046-host-side-api-server-design.md),
+[ADR 0054](0054-require-authorization-on-all-agent-dispatch-paths.md),
+[ADR 0058](0058-agent-registration.md),
+[ADR 0061](0061-harness-cel-dispatch.md),
+[ADR 0063](0063-polling-based-work-discovery.md), and
+[ADR 0076](0076-slash-command-entity-context-separation.md).
+Aligns with the `tracker.Client` split
+([#5988](https://github.com/fullsend-ai/fullsend/issues/5988)): domain
+interfaces stay narrow; `forge.Client` remains git-hosting only.
+
+## Context
+
+Agents already act on forge **work items** and **change proposals** via slash
+commands and host/post-script comments. GitHub Discussions (and later Slack,
+Discord, Matrix, GitLab discussions) are a different surface: threaded community
+conversation that must not be shoehorned into `work_item` without breaking
+entity-context rules ([ADR 0076](0076-slash-command-entity-context-separation.md)).
+
+`forge.Client` is scoped to git-hosting. Issue content for non-forge backends
+(Jira) already moves to `tracker.Client` rather than expanding the forge
+interface. Slack/Discord/Matrix are likewise not forges — conversation
+read/write must not grow `forge.Client`.
+
+Discussions also introduce **categories** (partition + optional format hints)
+distinct from **labels** (multi-tag triage). The event model must expose both
+without collapsing them.
+
+## Options
+
+### A. Special-case GitHub Discussions in workflows
+
+Fastest for GitHub; GitHub-centric and duplicates auth/writeback.
+
+### B. Always-on chat bot outside the execution stack
+
+Low latency; bypasses unidirectional control, mint/OIDC identity, and harness
+registration ([ADR 0016](0016-unidirectional-control-flow.md)).
+
+### C. Extend `forge.Client` with Conversation/Message methods
+
+Pulls non-forge chat into the forge package and fights the `tracker.Client`
+split.
+
+### D. Portable Conversation surface via `conversation.Client` (chosen)
+
+Parallel to `tracker.Client`: narrow domain interface + dispatch/event reuse,
+with per-backend adapters.
+
+## Decision
+
+Adopt **Option D**.
+
+### Domain model
+
+| Relation | Cardinality | Notes |
+|----------|-------------|--------|
+| Category → Conversation | **1:M** | Every conversation has exactly one category (GitHub requires it; Slack/Discord map channel → category). |
+| Conversation ↔ Label | **M:M** | Same triage tags as issues when the backend supports them (GitHub Discussions do). |
+| Conversation → Message | **1:M** | Messages (comments/replies) belong to one conversation. |
+| Message → Category / Label | **none** | Messages inherit routing context from their parent conversation; they are not categorized or labeled independently. |
+
+**Category ≠ label.** Categories are a single exclusive partition. Some
+backends expose category *format* hints (open discussion, Q&A, announcement,
+poll); those are optional routing metadata, not labels. Labels are additive
+tags on the conversation. Adapters must not encode the category name as a
+synthetic label.
+
+**Permissions.** Platform authorization remains
+[ADR 0054](0054-require-authorization-on-all-agent-dispatch-paths.md) (effective
+repo/collaborator role on `actor`). Category name/slug/format are **routing
+metadata** for harness CEL (e.g. only vouch agents match
+`category.slug == "vouch-request"`), not a second auth system. Backends may
+still reject creates/replies the actor cannot perform; that is adapter error
+handling.
+
+GitHub's public GraphQL `DiscussionCategory` exposes `isAnswerable` but no
+announcement/poll/discussion format field. Adapters MUST map
+`isAnswerable == true` to `format: question_answer` and SHOULD omit `format`
+otherwise unless they document an explicit heuristic. UI-only create
+restrictions (e.g. Announcements limited to maintain/admin) are not queryable
+via that API and MUST NOT be treated as enforceable from `format` alone.
+
+### Architecture seams
+
+1. **`conversation.Client`:** `internal/conversation` with Conversation/Message
+   APIs (and category metadata on Conversation). GitHub Discussions first;
+   Slack/peers implement directly. **Not** on `forge.Client` or
+   `tracker.Client`.
+2. **`NormalizedEvent`:** `entity.kind: conversation`. Require
+   `state.conversation.category` (`name` required; `id`/`slug`/`format`
+   optional). Reuse `state.labels` for conversation labels only. Message
+   events use `transition.kind: comment_added` with `transition.comment`;
+   category and labels still describe the **parent conversation**. See
+   [normative v1](../normative/normalized-event/v1/).
+3. **Ingress / egress / identity / security:** shim + dispatch drivers;
+   host-mediated writeback via `conversation.Client` (tier 1 default, host API
+   for mid-run); least-privilege Discussions/chat scopes; conversation bodies
+   untrusted. Entity-context separation keeps code-mutating slash commands off
+   conversations; enforcement is harness CEL `trigger` expressions over
+   `entity.kind` (target state in
+   [ADR 0076](0076-slash-command-entity-context-separation.md)).
+
+## Consequences
+
+- Harnesses route with CEL on both `state.conversation.category` and
+  `state.labels` (e.g. category selects the agent; labels refine).
+- Slack becomes input-driver + `conversation.Client` adapter work; channel maps
+  to category, thread maps to conversation.
+- Domain split: `forge.Client` / `tracker.Client` / `conversation.Client`.
+- Linking a conversation to a work item for `/fs-code` remains a follow-on.

docs/architecture.md

@@ -42,6 +42,7 @@ the dedicated org-level `<org>/.fullsend` config repo is deprecated
 **Decided:**
 
 - Forge abstraction: all forge operations go through the `forge.Client` interface, keeping the rest of the codebase forge-agnostic ([ADR 0005](ADRs/0005-forge-abstraction-layer.md)).
+- Conversation surface: agents participate in GitHub Discussions and later other chat systems through a narrow `conversation.Client` (parallel to `tracker.Client` for issue content), not by extending `forge.Client`. Conversations have exactly one category (1:M) and optional M:M labels; messages inherit that context and are not labeled ([ADR 0086](ADRs/0086-conversation-surface-for-agent-participation.md)).
 - Installation model: ordered layer stack (install forward, uninstall reverse, analyze for status reporting) with idempotent operations. Current stack: config-repo → workflows → vendor-binary → secrets → inference → dispatch → enrollment ([ADR 0006](ADRs/0006-ordered-layer-model.md)).
 - Cross-repo dispatch: enrolled repos call `.fullsend` via `workflow_call`; a dispatch workflow mints OIDC tokens exchanged at a central token mint (GCP Cloud Function or Cloudflare Worker) for scoped GitHub App installation tokens per agent role. App PEM secrets are stored in Secret Manager (GCF mint), Worker secrets (CF mint), or the local filesystem (standalone mint), not the config repo ([ADR 0008](ADRs/0008-workflow-dispatch-for-cross-repo-dispatch.md)).
 - Shim workflow security: `pull_request_target` prevents PR authors from modifying the shim workflow. No long-lived secrets flow through the shim — OIDC tokens are issued by the GitHub runtime and scoped to the workflow run ([ADR 0009](ADRs/0009-pull-request-target-in-shim-workflows.md)).
@@ -210,6 +211,7 @@ One concrete implementation option is [`oidcx`](https://github.com/oxidecomputer
 - How are credentials rotated and revoked, and who has authority to do that?
 - Does the identity provider integrate with existing secrets management, or is it a new system?
 - How will per-role identity work on GitLab and Forgejo, which lack GitHub's app manifest flow? GitLab uses a bot PAT credential model (via OIDC/WIF or protected CI/CD variable) — see [ADR 0067](ADRs/0067-gitlab-cron-polling-event-dispatch.md).
+- Which agent roles need Discussions (or other chat) write scopes, and how do those scopes map onto named mint privilege levels? Conversation participation requires least-privilege identity deltas per [ADR 0086](ADRs/0086-conversation-surface-for-agent-participation.md).
 
 ## Agent Dispatch and Coordination Layer
 
@@ -230,6 +232,12 @@ The existing design principle is that [the repo is the coordinator](problems/age
   as webhooks ([ADR 0063](ADRs/0063-polling-based-work-discovery.md)). Initial
   scope is per-repo mode only.
 - GitLab dispatch uses cron-polled scheduled pipelines for issue/comment/label events and native `merge_request_event` for MR events. No webhook bridge required (see [ADR 0067](ADRs/0067-gitlab-cron-polling-event-dispatch.md)).
+- Conversation participation: GitHub Discussions (and future chat systems) enter
+  dispatch as `NormalizedEvent` entities with `entity.kind: conversation`, reuse
+  CEL harness triggers and ADR 0054 authorization, and write back through
+  host/post-script or host-side API servers via `conversation.Client` — not a
+  separate always-on chat bot and not an extension of `forge.Client`
+  ([ADR 0086](ADRs/0086-conversation-surface-for-agent-participation.md)).
 
 **Open questions:**
 
@@ -240,6 +248,10 @@ The existing design principle is that [the repo is the coordinator](problems/age
 - How does work assignment interact with the backlog/priority agent described in [agent-architecture.md](problems/agent-architecture.md)?
 - What happens when work needs to be cancelled, retried, or reassigned?
 - Does the coordinator need state (a queue, a lock, a claim system), or can it be stateless and event-driven?
+- When should a conversation be linked to a work item (e.g. Discussion → issue)
+  so a conversation-native agent can hand off to `/fs-code` without violating
+  entity-context separation ([ADR 0076](ADRs/0076-slash-command-entity-context-separation.md),
+  [ADR 0086](ADRs/0086-conversation-surface-for-agent-participation.md))?
 
 ## Policy Store
 
@@ -333,7 +345,7 @@ ADR 0002: [Building block 1](ADRs/0002-initial-fullsend-design.md#1-webhook--dis
 
 ### 2. Slash-command parser + ACL
 
-Parses `/fs-triage`, `/fs-code`, `/fs-review`, and related commands and enforces who is allowed to invoke each. Commands are restricted to the entity context where their agent's inputs exist — `/fs-code` dispatches only from issues (no associated PR), `/fs-fix` and `/fs-review` only from PRs ([ADR 0076](ADRs/0076-slash-command-entity-context-separation.md)).
+Parses `/fs-triage`, `/fs-code`, `/fs-review`, and related commands and enforces who is allowed to invoke each. Commands are restricted to the entity context where their agent's inputs exist — `/fs-code` dispatches only from issues (no associated PR), `/fs-fix` and `/fs-review` only from PRs ([ADR 0076](ADRs/0076-slash-command-entity-context-separation.md)). Conversation surfaces (GitHub Discussions and future chat systems) are a separate entity context: conversation-native agents may listen there, but code-mutating slash commands do not ([ADR 0086](ADRs/0086-conversation-surface-for-agent-participation.md)).
 ADR 0002: [Building block 2](ADRs/0002-initial-fullsend-design.md#2-slash-command-parser--acl).
 
 ### 3. Label state machine guard

docs/normative/normalized-event/v1/README.md

@@ -29,6 +29,15 @@ input, and **Jira poll** input:
   is the production GitLab adapter ([ADR 0067](../../../ADRs/0067-gitlab-cron-polling-event-dispatch.md));
   `jira-poll` is the production Jira poll adapter; `json` supports tests and
   replay.
+- `entity.kind: conversation` covers GitHub Discussions and future chat
+  systems ([ADR 0086](../../../ADRs/0086-conversation-surface-for-agent-participation.md)).
+  GitHub Discussion adapters are planned under `gha-event`; additional
+  `source.system` values (e.g. Slack) are non-breaking enum additions when
+  those drivers land.
+- Conversations carry **`state.conversation.category`** (exactly one; 1:M
+  category→conversation) separately from **`state.labels`** (M:M tags on the
+  conversation). Messages have neither; `comment_added` events still snapshot
+  the parent conversation's category and labels.
 
 ## Versioning
 
@@ -48,14 +57,17 @@ Input drivers map native forge events into this struct:
 
 | Driver | Source | v1 status |
 |--------|--------|-----------|
-| `gha-event` | `GITHUB_EVENT_PATH` + `gh` snapshot for labels and change-proposal metadata | Production |
+| `gha-event` | `GITHUB_EVENT_PATH` + `gh` snapshot for labels and change-proposal metadata | Production; Discussions → `entity.kind: conversation` planned ([ADR 0086](../../../ADRs/0086-conversation-surface-for-agent-participation.md)) |
 | `gitlab-poll` | GitLab CI event payload (cron-polled; [ADR 0067](../../../ADRs/0067-gitlab-cron-polling-event-dispatch.md)) | Production (poll) |
 | `jira-poll` | Jira issue search + changelog/comments since `lastCheck` ([jira-poll-adapter.md](jira-poll-adapter.md), [ADR 0063](../../../ADRs/0063-polling-based-work-discovery.md)) | Production (poll) |
 | `json` | stdin or `--input-file` | Tests, replay |
 
 Adapters must populate:
 
 - `state.labels` when routing guards or label-based triggers apply.
+- `state.conversation` (with `category.name` at minimum) whenever
+  `entity.kind` is `conversation` — including message/`comment_added` events.
+  Do not encode the category as a synthetic label.
 - `state.change_proposal` (including `head_ref`, `base_ref`, and `head_sha` when
   known) whenever a matched harness needs change-proposal execution context.
   Webhook payloads are often incomplete — adapters should fill gaps via GitHub
@@ -168,6 +180,14 @@ event.transition.kind == "review_submitted"
 event.transition.kind == "comment_added"
   && event.transition.comment.command == "/fs-fix"
   && !event.state.change_proposal.is_fork
+
+// Conversation-native agent on Discussion slash command (ADR 0086)
+event.entity.kind == "conversation"
+  && event.transition.kind == "comment_added"
+  && has(event.transition.comment.command)
+  && event.transition.comment.command == "/fs-vouch"
+  && has(event.state.conversation.category.slug)
+  && event.state.conversation.category.slug == "vouch-request"
 ```
 
 See [`examples/`](examples/) for matching `NormalizedEvent` fixtures.

docs/normative/normalized-event/v1/examples/discussion-fs-vouch-comment.json

@@ -0,0 +1,37 @@
+{
+  "repo": "fullsend-ai/fullsend",
+  "entity": {
+    "kind": "conversation",
+    "id": 5182,
+    "url": "https://github.com/fullsend-ai/fullsend/discussions/5182"
+  },
+  "actor": {
+    "id": "contributor",
+    "kind": "human",
+    "role": "write",
+    "is_entity_author": true
+  },
+  "transition": {
+    "kind": "comment_added",
+    "comment": {
+      "command": "/fs-vouch",
+      "body": "/fs-vouch please review my request",
+      "instruction": "please review my request"
+    }
+  },
+  "state": {
+    "labels": ["needs-triage"],
+    "conversation": {
+      "category": {
+        "id": "DIC_kwDOExample",
+        "name": "Vouch Request",
+        "slug": "vouch-request"
+      }
+    }
+  },
+  "source": {
+    "system": "github",
+    "raw_type": "discussion_comment",
+    "raw_action": "created"
+  }
+}