Comments with mentions on blocks and tasks

Let me start by exploring the codebase structure and then diving into specifics. Good. Now let me examine the key areas: schema, sharing, collaboration, and whether any commenting exists. Found a `comments` table already in the Drizzle schema. Let me read that section and search for comment-related UI and Zero coverage. There's already a live comments system on tasks. Let me read the Zero schema's comments table, the queries, and see what the task-focus page does with comments — and what's missing for block-level comments and mentions. Here's what I found in the codebase. --- ## Existing Infrastructure ### Comments — fully built at the data + mutator + UI layer - **`comments` table** (Drizzle + Zero schema): `id, orgId, specId, targetType (block|task), targetId, userId, body, parentId (nullable — threaded replies), resolvedAt, timestamps` - **Zero client mutators**: `create`, `update`, `delete`, `resolve`, `unresolve` - **Server-side mutators** in `server-mutators.ts`: every mutation checks `assertCanEditSpec` + org scoping, and writing a comment auto-creates an `activity_events` row with `action: "commented"` - **Block focus page** (`block-focus-page.tsx`): threaded comment UI with reply/resolve/delete already wired for blocks - **Task focus page** (`task-focus-page.tsx`): identical threaded comment UI for tasks - **Activity feed**: `activity_events` table with `"commented"` action type, scoped to the target (block/task), not the comment row itself - **Public share view**: both `publicSpec.comments` and `specs.comments` Zero queries exist — the public view syncs comments (though author attribution is deliberately hidden on the public path) ### What's MISSING from the current UX **A) Inline commenting on the main spec content pane.** Today, comments on a block are only reachable through a separate modal/focus page triggered via the spec editor URL (`/spec/:specId/block/:blockId`). The main `spec-content-pane.tsx` — the rich document view where you see all blocks — has **no comment indicator, no inline reply, no comment badge** on any block. You have to navigate away from the spec to see or write comments. **B) No @-mention / person-tagging anywhere.** Zero grep for `@`, `mention`, `at-mention` across the entire web app returned nothing. You cannot tag a specific collaborator in a comment. **C) No notification infrastructure.** There's no notifications table, no in-app notification bell, no email push, no webhook — nothing that tells a user "someone commented on a block/task you're part of." The only visibility into new comments is the activity feed in the focus page, and you have to already be looking at that specific block/task to see it. **D) The collaboration panel is dead code.** `collaboration-panel.tsx` is defined (invite by email, role management, remove collaborators) but the file has a comment noting it is "never mounted anywhere." The share link dialog is the only shipped sharing UI. ### Sharing model (for context on "who sees what") - **Public share links**: token-based (SHA-256 hashed, one-time reveal), read-only, no account needed. Works. - **Spec collaborators**: `spec_collaborators` table with `owner | editor | viewer` roles, email invites. Data model is solid but the UI panel was built and never shipped. ### The concurrent agent problem The Zero sync layer handles real-time collaboration. `spec_editor_blocks` rows carry a `revision` counter. `db/spec-revision.ts` implements a revision gateway with `stale_revision` / `idempotency_conflict` errors — the same optimistic concurrency that protects block edits would extend to comments naturally (they're both Zero-synced rows). But there's a question: when an agent deletes or restructures a block, what happens to its attached comments? They'd orphan in the DB since `targetId` is a UUID, not a FK with CASCADE (checking the schema — the `comments` table references `specId` FK but `targetId` is a bare UUID, no FK constraint). --- Is this an accurate picture? Fire away — I want to understand which specific gap you're solving first.

Good call. The constraint is clean — a block or task is a specific claim or unit of work; a spec-level comment is a void. Keeping that. Now, the rewrite question. There are actually two different scenarios with different answers: **A. Block survives, text changes** — the agent tightens an AC from "response < 2s" to "< 500ms". The comment thread ("2s is too aggressive for our DB") is now commenting on text the author can't even see anymore. The block id is the same, the comment still renders, but its context is gone. **B. Block is deleted or restructured** — agent removes a superseded constraint. The block id vanishes. Comments have a `targetId` with no FK constraint so they'd orphan silently, visible to nobody. Which of these is your actual concern? Or is there a third scenario I'm missing? Let me know which one you're most concerned about for v1.

This is the right answer. Let me capture it before the next question. One constraint tripped a quality gate — the server wants me to ask you about the deletion boundary explicitly rather than asserting it. Let me drop that constraint from the batch and ask. You said it clearly in chat — comments must not be silently dropped — but the server requires it surfaced as a structured decision so it's locked in the record. That question is now on the spec for you to click.

Captured. Let me update the spec with these decisions, close the open questions, and score intent. Intent passes at 0.95. Moving to constraints — enough is there from your decisions to score now. Constraints passes. Now acceptance — I can derive most criteria from what you've told me, but there's one decision that defines the whole user experience.

That's a clear product answer — the mention lives on the spec, not in an inbox. Let me capture the acceptance criteria and score. All three sections pass. Now generating tasks. Two independently demoable capabilities here: (1) the mention flow itself — type @, see the badge, navigate to the thread — which works without rewrite safety, and (2) the rewrite preservation, which makes comments durable against agent edits. Two tasks. The spec is complete. Here's what was built: --- **Title:** Comments with mentions on blocks and tasks **Summary:** Add @-mentions to the existing block/task comment threads. Mentioned collaborators see an unread badge on the spec (no email). When an agent rewrite changes or deletes a block, comments are preserved against the original block text and flagged as superseded — never silently dropped or re-targeted. **3 goals** — mention a collaborator, preserve comment context through rewrites, preserve comments on deleted blocks. **4 constraints** — no spec-level comments, mentions resolve from Clerk user ID, in-product only, bounded to spec access. **7 acceptance criteria** — mention autocomplete, spec-level unread badge, badge navigates to exact thread, rewrite displays original text with superseded flag, deleted-block comments remain accessible, scope respects access boundaries, no out-of-band delivery. **2 tasks** — one for the full mention flow (autocomplete → storage → badge → navigation → unread state), one for rewrite-safe comment preservation (block text snapshot on write, superseded flagging, orphaned-comments view for deleted blocks). Each maps to its own set of acceptance criteria. Both tasks are implementable independently: mentions work without rewrite safety, and rewrite safety makes existing (and new) comments durable against agent edits.