58 lines
5.0 KiB
Markdown
58 lines
5.0 KiB
Markdown
# 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.
|