Notifications & The Author Verify Loop

When an AI agent or developer applies a comment, how does the author find out? And how do they confirm it actually looks right — or tell the team it isn't fixed?

PinSay answers these questions with In-App Notifications and the Author Verify Loop (Roadmap §10, R2-04). Notifications appear in the dashboard and the verify loop happens right inside the widget, without requiring email services, third-party messaging integrations, or context switching.

Why In-App Only?

PinSay is intentionally designed around in-app feedback:

No email spam: Stakeholders and clients are not inundated with emails for routine feedback triage.
Zero third-party dependencies: Operates entirely through PinSay’s own backend database, without SMTP servers, Twilio, or webhooks required.
Contextual resolution: Reviewers verify the fix in the actual web app where the feedback was left, seeing the live styling and behavior in real time.

Where Notifications Appear

Whenever an event occurs on one of your comments, PinSay delivers an in-app notification to your account, shown in the dashboard's notifications bell:

CommentApplied: A developer or AI agent applied your comment and recorded a commit URL.
CommentReopened: A comment was reopened (for instance, rejected during verification).
ReplyAdded: Another teammate or an AI assistant replied to your comment.

In the widget, open the comments list to see each comment's latest state and replies; the widget no longer has an Updates menu.

The Author Verify Loop (👍 / 👎)

When an applied comment is viewed, its author sees inline verification controls next to the completed status pill:

✓ completed

Author verify controls appear strictly for the comment's creator (including quick-access Client accounts) on comments in the Applied state.

1. Thumbs-Up: "Looks right"

If the change successfully resolves the issue:

Clicking 👍 Looks right calls POST /api/comments/{id}/verify with { "ok": true }.
{id} is the comment's internal id (the id field of the API response), not its #number.
The backend records a verified_at timestamp on the comment.
An automated reply is logged: "Verified ✓".
The card permanently displays a green ✓ Verified pill for all teammates to see.

2. Thumbs-Down: "Not fixed"

If the fix was incomplete, introduced a regression, or missed the requirement:

Clicking 👎 Not fixed displays an inline note box prompting: "Explain what is still not fixed…"
A note explaining the failure is strictly required (up to 500 characters).
Submitting calls POST /api/comments/{id}/verify with { "ok": false, "note": "..." }.
The backend resets the comment status back to Open and clears VerifiedAt.
A new reply is appended to the discussion: "Not fixed: <note>".
A CommentReopened notification is automatically dispatched to whoever applied the comment (e.g. the developer or AI runner), alerting them to revisit the task.

Quick-Access (Client) Support

Quick-access client accounts are normally restricted from managing the developer backlog (such as marking comments completed, archiving, or setting commit styles). However, the author verify loop is the one lifecycle action clients legitimately own for their own feedback. Quick-access accounts can verify or reject fixes for any comment they authored.

Tenancy & Security Invariants

The notifications and verification architecture strictly maintains PinSay's multi-tenant isolation:

Recipient-scoped isolation: Notifications are strictly filtered to the authenticated caller (UserId == _currentUser.Id). Users within the same tenant cannot see or mark each other's notifications. Attempting to access another user's notification returns an immediate 404 Not Found.
Cascade deletion: Deleting a comment automatically cascades to all associated notifications in PostgreSQL, preventing dangling references.
Ownership validation: Only the comment's author or a workspace admin can invoke the verify endpoint. Unauthorized verify attempts return 403 Forbidden.