feat: Comments & @Mentions — social collaboration layer for issues

[OneStepAt4time]

Comments & @Mentions — Social Collaboration Layer

Priority: P2 (depends on Agent Profiles #3971 + Inbox #3974)
Reference: multica/server/internal/handler/comment.go, multica/server/pkg/db/queries/comment.sql, multica/server/internal/mention/

---

Overview

Issues have comment threads. Members and agents can post comments. @mentioning an agent in a comment enqueues a task for them (lighter than assignment — no assignee/status change). This is the collaboration glue.

Database Schema

CREATE TABLE comment (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    workspace_id UUID NOT NULL REFERENCES workspace(id),
    issue_id UUID NOT NULL REFERENCES issue(id),
    
    -- Author
    author_type TEXT NOT NULL,  -- 'member' | 'agent'
    author_id UUID NOT NULL,
    
    -- Content
    content TEXT NOT NULL,        -- markdown body
    content_html TEXT,            -- rendered HTML
    
    -- Mentions (extracted from content)
    mentions JSONB DEFAULT '[]',  -- [{type: 'member'|'agent'|'squad', id: uuid}]
    
    -- Lifecycle
    resolved BOOLEAN NOT NULL DEFAULT false,
    resolved_by UUID,
    resolved_at TIMESTAMPTZ,
    
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE issue_reaction (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    workspace_id UUID NOT NULL REFERENCES workspace(id),
    issue_id UUID NOT NULL REFERENCES issue(id),
    
    -- Reactor
    reactor_type TEXT NOT NULL,  -- 'member' | 'agent'
    reactor_id UUID NOT NULL,
    
    -- Target
    target_type TEXT NOT NULL,    -- 'issue' | 'comment'
    target_id UUID NOT NULL,
    emoji TEXT NOT NULL,
    
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    
    UNIQUE(workspace_id, reactor_type, reactor_id, target_type, target_id, emoji)
);

@Mention Behavior

When a comment is posted:

1. Parse content for @mentions (member, agent, squad)
2. For each mentioned agent: enqueue a task (lighter than assignment)
3. For each mentioned member: create inbox notification
4. Store mentions in comment.mentions JSONB

Assignment vs @Mention

Dimension	Assign	@Mention
Changes assignee	✅	❌
Changes status	❌	❌
Enqueues task	✅ (non-Backlog)	✅ (always)
Trigger comment	Optional	Always
Multiple agents	1 (one assignee)	Many (@multiple)
Priority	From issue	From issue

Reactions

• React to issues or comments with emoji
• One reaction per user per target per emoji
• Reaction events create inbox notifications for the target's author
• Supports standard Unicode emoji

API Endpoints

GET    /api/issues/:id/comments              — list comments (paginated)
POST   /api/issues/:id/comments              — create comment
PATCH  /api/issues/:id/comments/:commentId   — update comment
DELETE /api/issues/:id/comments/:commentId   — delete comment
POST   /api/issues/:id/comments/:commentId/resolve    — resolve comment
POST   /api/issues/:id/comments/:commentId/unresolve  — unresolve comment

POST   /api/issues/:id/reactions             — add reaction
DELETE /api/issues/:id/reactions/:reactionId — remove reaction

Comment-Triggered Tasks

When @mention triggers a task for an agent:

• Task carries the comment as trigger context
• Agent reads: full issue (description + all comments) + trigger comment
• Agent can post a reply comment
• No assignee change, no status change
• Multiple @mentions in one comment → parallel tasks for each agent

Acceptance Criteria

1. CRUD for comments works on issues
2. @mention parsing extracts member/agent/squad mentions
3. @mentioning agent enqueues task with comment context
4. @mentioning member creates inbox notification
5. Reactions work (add/remove, dedup per user+target+emoji)
6. Comment resolve/unresolve works
7. npm run gate passes

E2E Test Requirements

1. Post comment with @agent mention → verify task created
2. Post comment with @member mention → verify inbox notification
3. Post comment with multiple @mentions → verify parallel tasks
4. Add/remove reaction → verify state
5. Resolve comment → verify resolved state

Multica Source Reference

• server/internal/handler/comment.go — comment handlers
• server/internal/mention/ — mention parsing and triggering
• server/pkg/db/queries/comment.sql — DB queries