Add truthful attribution, workspace-wide activity feed, and append-only audit trail

Let me start by exploring the repo structure and understanding the existing codebase. Interesting — I see a test file `spec-activity-feed.test.ts` already exists. Let me dig into the existing activity tracking surface, the data model, and how agent vs human edits are distinguished.

You're right. Here's what the code says — no speculation. ## 1. What's recorded and where it surfaces **Backend (recorded):** There's an `activity_events` table (`activity_events` in Postgres, mapped as `activityEvents` in Zero schema). Schema at `packages/zero/src/schema.ts:562-577`. Fields: - `orgId`, `specId` — scoped to a spec within an org - `targetType` — `"block"` or `"task"` only (no spec-level, no project-level, no org-level events) - `targetId` — UUID of the block or task - `userId` — stores the raw Clerk user ID (optional, see `userId: string().from("user_id").optional()`) - `action` — enum: `"created" | "updated" | "status_changed" | "assigned" | "commented" | "done_toggled" | "deleted" | "priority_changed" | "linked" | "unlinked"` - `previousValue`, `newValue` — string snapshots - `metadata` — JSON blob - `createdAt` — timestamp (no `updatedAt`, it's append-only) The server-mutators at `apps/api/src/zero/server-mutators.ts` call `recordActivity()` after every mutation that creates/updates/deletes blocks, tasks, and comments. There's also a batch threshold (`ACTIVITY_BATCH_SUMMARY_THRESHOLD = 20`) — when a single agent turn touches >20 blocks, it emits a single summary event instead of per-block events. **Frontend (surfaced):** Three UI surfaces consume `activityEvents`: 1. **`collaboration-panel.tsx`** — a "Recent activity" section in the spec editor sidebar showing latest 50 events per spec. Renders `{actor} {action} {targetType}`. 2. **`block-focus-page.tsx`** — a collapsible "Activity" section per block, showing events for that block (capped at 20). 3. **`task-focus-page.tsx`** — same but per task. There is ALSO a separate `agentTurns` table and `AgentActivityRow` in the chat pane (`chat-pane.tsx`) that shows agent activity during the current editing session — but that's session-scoped, not a durable record. ## 2. Org-wide or per-spec? **Per-spec only.** The `activityEvents` table has `orgId` and `specId` columns, and every existing Zero query filters by `specId`. The relationship graph (`activityEventRelationships` at line 1068) links to `specs` but has no org-level query available. The UI surfaces are all inside a single spec editor view. There is no workspace-level or project-level feed. You cannot ask "what happened in my workspace yesterday." ## 3. How is the agent attributed? **Agent edits are attributed to the human user whose Clerk ID was passed in the request.** Looking at the server-mutators and the test in `spec-activity-feed.test.ts`, every mutation carries `x-zenorm-user-id: clerkUserId` as a header, and `recordActivity` writes that same Clerk ID into `activityEvents.userId`. The system does NOT distinguish between a human typing in the editor and an agent executing on behalf of that user. The `recordActivity` function literally receives the raw Clerk user ID from the Zero context — there is no `actorType: "agent"` or `agentTurnId` field in the activity_events table. Agent turns DO get journaled in `agentTurns` with their own table/schema, but that's a separate tracking system for orchestration/recovery, not surfaced in the activity feed. So the answer today: **agent edits are attributed to the user who asked the agent to do it — indistinguishable from a human edit.** ## 4. Immutable record? **No. It's application data — deletable and editable.** The `activityEvents` Zero table is synced to the client. There's no append-only protection, no event sourcing, no archive strategy visible. The 50-event cap in queries (`LIMIT 50`) is purely a query-level window — the table can grow unboundedly. Nothing in the codebase treats activity as an immutable audit trail. A malicious or buggy mutation could delete or insert activity_events rows. --- **My first grill question after reading all that:** The main gap you described is workspace-wide visibility + clear agent attribution. Given the existing per-spec, per-block/per-task feed that already captures human-only-attributed events, which of these do you want to tackle? That's the core framing question. Your move.

Before I write any blocks, let me answer your immutability question honestly — and I need to check how Zero's permission layer interacts with this table to give you a real answer, not a hand-wavy one. Good. Here's the honest answer on immutability based on what the code actually does. **Current state: append-only by convention, not by enforcement.** The `packages/zero/src/mutators.ts` file (the Zero client-side allowed writes) has **no mutator for `activityEvents` at all** — no insert, no update, no delete. The only write path is the server-side `db.insert(activityEvents).values(...)` inside `recordActivity()` in `server-mutators.ts:1441`. No update or delete for activityEvents exists anywhere in the codebase. This means: - **Clients cannot write activity_events through Zero** — the schema exports the table for reads only - **No server-side update/delete mutator exists** despite a very thorough mutator module - **No Postgres-level enforcement** — no trigger, no RLS policy, no `SECURITY DEFINER` wrapper - **Zero's internal replication** is a read-through cache from Postgres; it doesn't add or subtract from Postgres protections - A future PR could add a delete mutator, or someone with direct DB access could `UPDATE activity_events SET userId = 'clerk_someone_else'` — nothing would stop them **What I'd actually claim in the spec:** "Activity events are write-only through the edit pipeline — there is no application code path that updates or deletes them once created. This is enforced at the application layer, not the database layer, so it's not an unbreakable audit guarantee against administrative access." That's a modest true claim rather than an impressive false one. Now let me write the intent blocks based on everything you told me, then score. Now let me insert the intent blocks capturing your five capabilities and the explicit exclusions. The gate rejected the append-only goal because it mentioned deletion/erasure enforcement in a way the gate considers absent from evidence. But the PM *did* explicitly say this. Let me rephrase to match exactly what the PM asked for and remove the constraint that pre-emptively writes off DB-level enforcement (which you said to claim plainly, not write as a constraint).

All three sections scored ≥ 0.9. Let me dismiss the stale question — your prose brief was the answer — then propose and create the task split. Here's the split I'd recommend, based on reading the actual code paths: **Task 1: Wire truthful attribution and extended event coverage into all server mutators** — covers goals a, c, d. This modifies `recordActivity()` in `server-mutators.ts:1427` to accept `actorType` and `agentTurnId`. Every call site gets updated. New call sites get added for spec create/update/archive/delete and collaborator add/remove — same function, same transaction pattern. The `activityEvents` table gets an `actorType` enum column (not just a boolean — `human` vs `agent`), an optional `agentTurnId` FK, and the `targetType` + `action` enums expand. The append-only check (no update/delete mutator exists) is a test assertion, not new code. **Task 2: Build workspace activity page with org-wide feed, filters, and human-readable display** — covers goals b, e. New Zero query (org-wide, filterable), new UI route under `/dashboard/`, filter controls for person/spec/time/action, resolved display names, relative timestamps, descriptive labels. The existing `collaboration-panel.tsx` pattern (display name resolution from Clerk ID, `activityLabel` function) is the template. Two tasks, not one, because they're independently demoable: the write-path changes ship with zero visual change (events get richer, but the existing per-spec feed just shows more detail), and the workspace page ships as a new surface the PM can open and navigate. They do not depend on each other to be useful. Task 1 was rejected as a backend layer — correct. The write-path changes and the UI are the same capability: a user being able to see what happened in their workspace with truthful attribution. One task. Let me delete the staged task and create the merged one. Task created. Now let me build the complete trace graph. The description is too long with AC titles appended. Let me shorten it. Done. The spec is complete with one task, all trace edges committed. Here's the final state: --- **Title:** Add truthful attribution, workspace-wide activity feed, and append-only audit trail **One task:** Add org-wide activity feed with truthful agent attribution and extended event coverage The task owns all 7 acceptance criteria — write-path surgery (actorType/agentTurnId on activity_events, expanded targetType/action enums, new recordActivity calls at spec lifecycle and collaborator write paths) and the read-side (org-wide Zero query, workspace activity page under /dashboard/, resolved display names, filter controls, append-only regression test). **What we're claiming vs not claiming on immutability:** Recorded in the constraint "Append-only by enforceable convention" — no application code path can update or delete an activity event, checked by test, enforced by Zero schema (reads-only exposure). Not claiming tamper-evidence against direct database access. That's a separate spec with hash chaining or an append-only store when you need it. **One question before you go:** You mentioned "history" as an open product decision in the advisory feedback — specifically whether this activity log is just a field-change record (it can tell you who changed what when) or whether it should also support reconstructing/undoing past state. From your brief you seem squarely in the "activity log" camp, not "state reconstruction" — is that right, or is there a replay/undo angle I'm missing?