stack/docs/scratchpads/756-official-discord-plugin.md

Scratchpad — #756 Official Discord channel plugin

• Task / issue: Official Discord channel plugin / #756
• Branch: feat/756-official-discord-plugin
• Worktree: /home/hermes/agent-work/stack-discord-plugin
• Base: origin/main at 49e8a54105eddf41e8e0e44603ded616ee76044f
• Objective: Deliver harness-neutral Discord routing, native mention-to-thread behavior, untagged in-channel interaction, fail-closed channel/user authorization, and transport-neutral contracts for future official channel plugins.
• Collision boundary: Do not modify orchestrator-to-Pi migration, logical-agent lease/fencing (#754/#755), runtime provider implementations, or orchestrator-owned docs/TASKS.md.
• Working budget: 55K tokens for requirements, implementation, tests, documentation, independent review, and delivery. No user-specified hard cap. Reduce optional refactoring before reducing acceptance coverage.

Assumptions

1. ASSUMPTION: Every configured Discord channel is intentionally agent-bound, so an authorized human's untagged message is agent input and receives an in-channel response. Rationale: this satisfies the requested no-tag behavior without activating the bot in arbitrary channels.
2. ASSUMPTION: Mentioning the bot in a parent channel creates or reuses a public Discord thread; messages already in a thread remain in that thread without repeated mentions. Rationale: Discord does not support nested threads and the request describes tags as the thread-selection signal.
3. ASSUMPTION: One bot process may host multiple configured channel-to-logical-agent bindings. Rationale: bindings are already configuration-owned and this avoids per-agent Discord credentials.
4. ASSUMPTION: Static guild/channel/user allowlists and paired-user roles remain the administration surface for this slice. Rationale: dynamic admin UI is larger and can be added without changing adapter contracts.
5. ASSUMPTION: The stable conversation handle contains logical agent plus Discord channel/thread identity and never a harness/provider identifier. Rationale: runtime re-enrollment and the active lease work can change Claude/Codex/Pi/OpenCode behind the same channel connection.
6. ASSUMPTION: Canonical documentation remains in-repository for this slice; no external publishing is performed.

Plan

1. Update docs/PRD.md before code with #756 scope, constraints, assumptions, and acceptance criteria.
2. Add failing Discord behavior and authorization tests first.
3. Add transport-neutral channel DTO/contracts in @mosaicstack/types.
4. Implement mention-to-thread, untagged in-channel, existing-thread, stable conversation, and adapter health behavior without runtime-specific imports.
5. Update admin/developer/channel protocol docs and documentation checklist.
6. Run focused tests, typecheck, lint, formatting, full applicable baseline, and coverage.
7. Run independent code and security review; remediate and re-review.
8. Commit, queue-guard, push, open PR to main, wait for green CI, squash merge, verify merged CI, and close #756.

Progress

• 2026-07-14: Loaded mission state (none active), global/project guidance, current origin/main, existing Discord/Tess/fleet connector architecture, issue #709 history, and active portability issues #754/#755.
• 2026-07-14: Created issue #756 through the Mosaic wrapper.
• 2026-07-14: Created isolated worktree/branch from current origin/main; the stale root checkout and unrelated QA artifacts remain untouched.

TDD decision

Required and applied. This change modifies authorization-sensitive remote ingress and routing behavior. Failing permission and routing tests will be captured before implementation.

Risks / blockers

• Active logical-agent lease work may later add stronger fencing fields. This slice must expose a clean, harness-neutral seam without duplicating that schema.
• Discord thread creation is an external side effect. Unit tests use a typed fake; live credential smoke testing is out of scope and must not use committed secrets.
• Repository-wide checks may expose unrelated baseline debt; changed-scope evidence and CI remain mandatory.

Verification evidence

• pnpm format:check — passed.
• git diff --check — passed.
• pnpm typecheck — passed (42 Turbo tasks).
• pnpm lint — passed (23 Turbo tasks).
• pnpm build — passed (23 Turbo tasks).
• pnpm --filter @mosaicstack/discord-plugin test — passed: 44 tests; V8 coverage 92.18% statements/lines, 86.55% branches, 100% functions (all configured thresholds ≥85%).
• Focused gateway verification passed: Discord ingress/security, cross-surface, ownership, redaction/concurrency, and agent attachment tests.
• pnpm test — changed-scope suites passed; repository baseline remains blocked by apps/gateway/src/__tests__/cross-user-isolation.test.ts requiring PostgreSQL at localhost port 5433 (ECONNREFUSED). The failure is unrelated to this change.
• Independent code/security re-reviews requested after final remediation; reports are stored under ignored docs/reports/ evidence paths.