💬 Comment
Permanent, append-only audit trail. Think GitHub issue comments — once written, always there.
Schema
D1 comments table
Immutable history. No UPDATE, no DELETE by design.
idTEXT PK — UUID
target_typeTEXT NOT NULL — task |
report | job
target_idTEXT NOT NULL — e.g. A66,
A82
authorTEXT NOT NULL — adrian |
clara | system | agent-name
contentTEXT NOT NULL — Markdown
content
created_atTEXT — Auto-set via
datetime('now'). Immutable.
Design Philosophy
Append-only by design: Comments have no
status field, no
updated_at, and the API only supports GET and POST. Once a comment is created, it exists forever.
This is the opposite of Feedback's lifecycle model.
Comments are backward-looking — they record what happened. "Task A66 was deployed at 3pm." "Clara created sub-task A67." They form an immutable audit trail that any agent or human can trust.
Comment vs Feedback
| Aspect | 💬 Comment | 📥 Feedback |
|---|---|---|
| Intent | "Record what happened" | "Please consider this" |
| Direction | Backward-looking, historical | Forward-looking, proactive |
| Mutability | Append-only (no edit/delete) | Full lifecycle with state transitions |
| Scoping | Scoped to entities (target_type + target_id) | Global inbox (optional workspace filter) |
| Who writes | Anyone (agents, Clara, Adrian, system) | Adrian (portal) or agents (as parked) |
| Visibility | Task modal "Comments" tab, Job detail "Comments" tab, Report viewer annotations drawer | Inbox page + Task modal "Feedback" tab + Report viewer annotations drawer |
API
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/comments?target_type=task&target_id=A82 |
List comments for an entity. Optional: &limit=N |
POST |
/api/comments |
Create. Body: { target_type, target_id, author, content } |
PATCH |
/api/comments?id=xxx |
Edit content (author-only). Body: { content, author } |
DELETE |
/api/comments?id=xxx&author=yyy |
Delete (author-only). Only the original author can delete. |
Author-only edits: PATCH and DELETE verify original authorship. Agents and humans can only
modify their own comments. The audit trail remains trustworthy because authorship is enforced.
Use Cases
| Who | When | Example |
|---|---|---|
| System | Auto-generated on workflow events | "Status changed to active by /task start" |
| Clara | After processing feedback | "Processed feedback fb-123: Created task A87" |
| Adrian | Manual notes in TaskModal | "Decided to defer this until after Surfstek demo" |
| Agent | Session context | "Completed Phase 2 implementation. 3 files modified." |