PSA/docs/plans/2026-05-13-threaded-comments/PRD.md

# PRD — Threaded Comment Responses

- Slug: `2026-05-13-threaded-comments`
- Date: `2026-05-13`
- Status: Draft

## Summary

Add replies to comments on tickets and project tasks. Replies render as an inline indented tree under their root (hybrid "Nested + collapsible drawer" model from the design handoff). Any reply can spawn its own sub-thread; visual indent caps at depth 4, data depth is unlimited. Every top-level comment becomes the head of a first-class `comment_threads` record that carries the email-thread identity (RFC `Message-ID` + `References` chain) so inbound and outbound email can flow correctly into and out of individual threads instead of being collapsed at the ticket level.

## Problem

1. Comments on tickets/tasks are a single chronological list. Two simultaneous conversations on a ticket (e.g. an internal investigation + a client-facing correspondence) interleave, which makes it hard to follow context.
2. The ticket is currently the email "thread": every inbound email matching a ticket becomes a flat comment, with no way to route subsequent emails to the specific sub-conversation they answer.
3. Outbound emails from comments use reply tokens but don't set RFC `In-Reply-To`/`References`, so mail clients can't thread our messages.

## Goals

- Reply to any comment on a ticket or project task; replies indent under the parent.
- Recursive sub-threads with a per-thread collapse and "Open in drawer" action.
- Internal/client visibility, resolution markers, edit/delete, reactions all continue to work.
- Inbound email lands in the **specific thread** it answers (via reply token, then `In-Reply-To`, then `References`, then provider thread id; falls back to a new top-level thread on the matched ticket).
- Outbound emails from a thread carry proper RFC threading headers, accumulate `References`, and reissue a thread-scoped reply token.
- Existing comments migrate cleanly (each becomes a single-comment thread; UI unchanged for them).

## Non-goals

- Notification UI changes (Slack / email templates).
- @mention picker upgrades.
- New resolution-state UI (e.g. "Mark thread resolved").
- The other reply modes from the prototype (Flat, Single-level only, Deep nesting only, Quote-reply, Side-panel-only) — those were design exploration; production ships the Hybrid model only. The Tweaks panel is prototype-only and is not part of production.
- Density toggle (always "comfortable").
- Project-task email integration (tasks don't accept inbound email today; out of scope here).
- Thread-level resolution semantics, "mark thread answered", and any thread state beyond what's needed for the UI.

## Users and Primary Flows

**Personas:**
- Internal MSP technician (full read/write across internal + client-facing comments).
- Client contact (read/write own client-facing comments).

**Primary flows:**
1. **Reply inline.** Tech hovers a comment → clicks **Reply** → inline composer opens beneath the comment → submits → reply renders indented under the parent. A small thread bar appears above the children: `"2 replies · Collapse"`.
2. **Collapse / Expand.** Tech clicks **Collapse** → children hide; bar now shows `"2 replies · last May 12, 9:24 AM"` with **Expand** and **Open in drawer**.
3. **Open in drawer.** Clicking **Open in drawer** opens a side panel with the root + all replies, focused composer at the bottom. Closing returns to inline view.
4. **Reply to a reply (sub-thread).** Replies can themselves be replied to; each gains its own thread bar with dashed border. Indent caps at depth 4 visually.
5. **Inbound email.** Client replies to our outbound email; the email matches the originating thread by `In-Reply-To`; a new comment lands as a child of the latest comment in that thread.
6. **Outbound email.** When a tech replies in a thread, the outgoing email sets `In-Reply-To: <latest outbound Message-ID for this thread>`, appends to `References`, and issues a fresh reply token tied to the new comment.

## UX / UI Notes

Source of truth: `/tmp/design_extract/comment-responses/` handoff bundle (saved from Claude Design). Key visual decisions copied verbatim:

- **Comments card chrome unchanged** from today's `TicketConversation` (24px card radius, indigo tabs, "Add Comment" purple button, BlockNote composer with Mark-as-Internal / Mark-as-Resolution switches).
- **Reply button** added to the per-comment hover action row (`Pencil`, `Trash`, now also `CornerUpLeft` "Reply").
- **Thread bar** is a pill at left-margin 24px above the children. Background `#F9FAFB`, indigo text `#4F46E5` for `Collapse` / `Open in drawer`. Sub-thread bars (depth ≥ 1) use a dashed border and white background.
- **Drawer** uses the existing Radix-based `Drawer` component from `packages/ui`; width 480px; slides from right; overlay `rgba(15, 23, 42, 0.25)`.
- **Internal visibility** indicators remain: amber `Lock` icon + amber 3px edge stripe. No tint mode.
- **Tab counts** are recomputed at the *thread* level (a thread shows up in "Internal" if its root is internal; in "Resolution" if any of its comments is a resolution).
- **Sort order** (oldest/newest first) toggles thread order by `last_activity_at`, not within-thread reply order — replies inside a thread are always chronological.
- **Depth cap**: CSS class `depth-4` stops increasing `margin-left`. Data is unlimited.

## Requirements

### Functional Requirements

1. New `comment_threads` table (polymorphic between ticket / project task, exactly one of `ticket_id`/`project_task_id` set).
2. `comments` and `project_task_comments` gain `thread_id` (NOT NULL after backfill) and `parent_comment_id` (nullable).
3. Backfill: every existing comment becomes its own single-comment thread with `parent_comment_id = NULL`.
4. Creating a comment without `parent_comment_id` creates a new `comment_threads` row; the new comment is its root.
5. Creating a comment with `parent_comment_id` inherits `thread_id` from the parent and increments `reply_count` + bumps `last_activity_at` on that thread.
6. Deleting a leaf comment hard-deletes and decrements thread `reply_count`. Deleting a root with children soft-deletes (`note` replaced with "[deleted]", a `deleted_at` set) so the tree stays well-formed.
7. Tab filtering operates on threads:
   - **All** — all threads.
   - **Client** — threads whose root is non-internal.
   - **Internal** — threads whose root is internal.
   - **Resolution** — threads containing any `is_resolution` comment.
8. Internal flag of a reply defaults to the parent's `is_internal` value in the inline composer.
9. "Mark as Resolution" is shown only at the top-level composer, not in inline reply composer.
10. **Inbound email resolution** (in order; first match wins):
    1. Reply token (`email_reply_tokens` → derive thread from token's `comment_id`)
    2. `In-Reply-To` header → look up in `email_sending_logs.rfc_message_id` → derive `comment_thread_id`
    3. `References[]` chain — walk from end to start
    4. `email_provider_thread_id` exact match on `comment_threads`
    5. Ticket-level fallback: existing `tickets.email_metadata` match → create a **new top-level thread** on that ticket (preserves today's behavior)
11. **Outbound email**:
    - New top-level reply: generate fresh RFC `Message-ID`, store in `comment_threads.email_message_id`; no `In-Reply-To`.
    - In-thread reply: `In-Reply-To: <latest outbound RFC Message-ID for this thread>`; append same to `References`.
    - Issue a reply token scoped to the new outbound comment.
    - Persist row in `email_sending_logs` with `comment_thread_id`, `rfc_message_id`, `reply_token_hash`.
12. Project tasks support the same UI threading, no email logic. `comment_threads.is_internal = false` for tasks (no internal/client distinction in task comments today).
13. Visual indent depth caps at 4; data has no cap.
14. Existing reactions, edit, delete, internal/resolution markers continue to work per comment.

### Non-functional Requirements

- Migrations safe on Citus (match patterns used by neighbors in `server/migrations/`).
- Backfill is idempotent and chunked so it runs cleanly on large tenants.
- Thread-level queries hit indexes: `(tenant, ticket_id, last_activity_at)`, `(tenant, project_task_id, last_activity_at)`, `(tenant, email_message_id)`.
- All comment writes remain inside `withTransaction()`; `reply_count` and `last_activity_at` are maintained in the same transaction.

## Data / API / Integrations

### Schema

```sql
CREATE TABLE comment_threads (
  tenant uuid NOT NULL,
  thread_id uuid NOT NULL DEFAULT gen_random_uuid(),
  ticket_id uuid NULL,
  project_task_id uuid NULL,
  root_comment_id uuid NOT NULL,
  is_internal boolean NOT NULL DEFAULT false,
  reply_count integer NOT NULL DEFAULT 0,
  last_activity_at timestamptz NOT NULL DEFAULT now(),
  email_message_id text NULL,
  email_references text[] NOT NULL DEFAULT '{}',
  email_provider_thread_id text NULL,
  created_at timestamptz NOT NULL DEFAULT now(),
  created_by uuid NULL,
  PRIMARY KEY (tenant, thread_id),
  CHECK ((ticket_id IS NOT NULL)::int + (project_task_id IS NOT NULL)::int = 1),
  FOREIGN KEY (tenant, ticket_id) REFERENCES tickets (tenant, ticket_id) ON DELETE CASCADE,
  FOREIGN KEY (tenant, project_task_id) REFERENCES project_tasks (tenant, task_id) ON DELETE CASCADE
);
CREATE INDEX comment_threads_ticket_idx ON comment_threads (tenant, ticket_id, last_activity_at DESC);
CREATE INDEX comment_threads_task_idx ON comment_threads (tenant, project_task_id, last_activity_at DESC);
CREATE INDEX comment_threads_email_msgid_idx ON comment_threads (tenant, email_message_id) WHERE email_message_id IS NOT NULL;
```

`comments` adds:
- `thread_id uuid NOT NULL` (after backfill)
- `parent_comment_id uuid NULL`
- FK `(tenant, thread_id) → comment_threads`
- FK `(tenant, parent_comment_id) → comments` (self-FK)
- `deleted_at timestamptz NULL` (for soft-delete of roots-with-children)

`project_task_comments` adds the same set.

`email_sending_logs` (already has `thread_id` — rename to `email_provider_thread_id` for clarity if safe; add new column `comment_thread_id uuid NULL` → `comment_threads.thread_id`).

### TypeScript Interfaces

- New: `ICommentThread` in `packages/types/src/interfaces/commentThread.interface.ts`.
- Extend `IComment` and `IProjectTaskComment` with `thread_id`, `parent_comment_id`, `deleted_at`.

### Server Actions (signatures)

`createComment(comment: IComment & { parent_comment_id?: string })` — resolves thread, increments counters, publishes event with `thread_id` + `parent_comment_id` in payload. Same for `createTaskComment`.

## Security / Permissions

- Reply visibility inherits root: a reply on a client-visible root cannot have `is_internal = true` at the data layer (model rejects). UI inherits parent's flag as default but allows toggling within rules. Conversely a reply on an internal root must be internal.
- Project-task `assertOwnCommentOrInternalUser` rule applies to replies (client can edit/delete own replies; internal users can do anything).
- Inbound-email-derived comments inherit the thread's `is_internal` flag (clients can only reply to client-visible threads).

## Observability

Out of scope per project conventions for this PR (no new metrics/logging beyond what the existing comment system already does).

## Rollout / Migration

1. Ship migrations behind a single deploy.
2. Backfill runs as part of the migration sequence. Chunked over `comments` and `project_task_comments`.
3. `NOT NULL` enforcement migration runs **after** backfill (separate migration file for safer rollout).
4. No feature flag — the UI change is rendered for everyone post-deploy. Existing comments render as single-comment threads (no thread bar, no visual change).

## Open Questions

- Exact name to use for the existing `email_sending_logs.thread_id` (which today refers to provider thread id). Decide on rename vs. add new column during implementation.
- Whether `comment_threads.email_references` should be capped in length (long mail clients can produce dozens of References entries).

## Acceptance Criteria (Definition of Done)

- All migrations apply cleanly on a fresh DB and on a copy of a production-shape dataset.
- Existing tickets and project tasks render identically to today (single-comment threads, no thread bar).
- Replying to a comment in a ticket produces an indented child + thread bar; collapse / expand / open-in-drawer all work.
- Sub-thread (reply to a reply) renders dashed-bordered sub-thread bar.
- Tab counts at the thread granularity match the rules in Functional Requirements §7.
- Inbound email lands in the right thread for each of the 5 resolution paths.
- Outbound email from a thread carries correct `In-Reply-To` and `References` headers.
- Mirror behaviors verified on project tasks (excluding email).
- Unit + integration + Playwright e2e tests in `tests.json` pass.