Org-scoped API keys, spec read API, and verifiable outbound webhooks

Let me start by exploring the repo to understand what exists todayLet me understand the existing webhook/webhook-related code to understand what's already builtThis is a specification-writing tool called ZeNorm. There are no existing webhook endpoints for user-facing integrations. Let me also check if there's any gallery or API export mechanism. No existing webhook infrastructure for third-party integrations. Let me understand what ZeNorm is and how spec data flows. Good. ZeNorm is a spec-writing tool — it manages "specs" (product specifications). Teams want to hook ZeNorm into their own tools, likely meaning they want webhooks or an API so external tools can react to spec events. Let me look at the specs route and data model to understand what events could be meaningfulGood. Now I have a solid picture. ZeNorm is a spec-writing tool. The spec system has: activity events (`created`, `updated`, `status_changed`, etc.), collaborators, versions. No outgoing webhook infrastructure exists. Let me ask the key opening question. ZeNorm currently has no webhook or public API for external tools. The collaboration panel shows the app already tracks activity events internally (created, updated, status_changed, etc.), so the data layer for spec events exists. The question is what integration pattern the teams actually need — are they looking to push events out, pull data in, or both? I've asked: **what specific gap do teams hit today that makes them want to hook ZeNorm into their own tools?** Push-only (webhook), pull-only (API), both, or something else entirely.

Let me read the auth layer, the activity events schema, and check for any existing API-key or machine-credential concept. Now let me read the activity_events schema and check the db package more carefullyNow let me read the full activity_events table definition and check the spec store for how it reads dataLet me find the activity_events table definition and see how events are written in the mutators The file is very large and the grep tells me the activityEvents table is at line 2097 but the snippet keeps being truncated before that. Let me read exactly the right lines. The file keeps being truncated because schema/index.ts is 88658 bytes. Let me read the exact activityEvents table definition. Now I have a complete picture. Let me capture everything into intent blocks and update the metadata. The quality gate rejected the first block for specifying credential lifecycle mechanics without PM evidence. You explicitly stated: "issue a key, scope it to an org, show it once, let someone revoke it." That's not invented — it's your stated constraint. But to pass the gate, let me retry without over-specifying the lifecycle and with just your stated outcomesGood, blocks are in. The auth layer is Clerk-only today, with no concept of a non-human caller. Now let me ask about the open credential design choices before I can score intentHere's what I found in the repo: **Auth layer** — Clerk-session-only. The `resolveAuthContext` function in `apps/api/src/auth.ts` handles Clerk JWTs, dev headers (`x-zenorm-user-id`, `x-zenorm-org-id`), and OAuth access tokens (`oat_` prefixed for the CLI). Every path produces a `{ orgId, userId, isAdmin }` context. There is zero notion of a non-human, machine-only credential anywhere in the codebase. **activity_events table** (`db/schema/index.ts:2097`) — Already exists and is in active use. Schema: `id`, `orgId`, `specId`, `targetType` (block or task), `targetId`, `userId` (nullable text), `action` (enum: created, updated, status_changed, assigned, commented, done_toggled, deleted, priority_changed, linked, unlinked), `previousValue`, `newValue`, `metadata` (jsonb), `createdAt`. Indexed on (targetType, targetId, createdAt) and on specId. The `server-mutators.ts` already writes to this table during mutations. Using this as the webhook event spine means no new events table — you hook into the same insert path. **Auth routes** — `apps/api/src/routes/` has Hono router files. The spec store at `apps/api/src/spec-store.ts` handles reads. The question I'm asking now: you said "org-scoped" — keys at the org level or per-spec?

Let me also check what activity_events looks like, and look for existing API routes or webhook infrastructure. Good — I've read the schema thoroughly. Let me answer your schema exposure question directly, then update the blocks with all the decisions captured. **Schema hazard analysis**: Yes, there are two version-shaped hazards in direct serialization: 1. **`spec_versions.content`** is a `json<ReadonlyJSONValue>` with no schema enforcement. The seed data shows it as `{format: "markdown", body: "..."}` but this is an internal shape that will evolve as the editor does — exposing it raw means the first consumer who depends on its structure becomes a permanent drag on internal refactoring. Any change to how the editor serializes content becomes a breaking change. 2. **`spec_editor_blocks.attrs`** is another untyped JSON blob carrying editor-internal metadata (cursor positions, formatting hints, block-specific state). Exposing this directly publishes an undocumented internal shape the editor team needs freedom to change. Neither is fatal — the fix is to define a **stable view model** for the API responses that decouples the public contract from the storage schema. For spec content, return blocks as a typed array (type, text, order) and omit `attrs`. For spec metadata, flatten the relevant columns into a response object and omit internal FKs like `currentVersionId`. Now let me capture all the confirmed decisions as blocks and update the spec. Two issues: summary exceeds 400 chars (I tried to summarize the blocks instead of writing an elevator pitch) and I asserted "3 attempts" when the PM only said "a bounded number of attempts." Let me fix both. I'll update existing blocks with the richer content from your decisions and add new constraint blocks for the decisions that don't have a home yet.

Your grouping matches what the code suggests. The credentials+read API are tightly coupled — you can't demo one without the other, and they share the auth middleware surface. Webhooks are a separate runtime concern (a delivery worker with retry queue, separate from the request-response path). Two tasks is right. Let me insert the remaining constraints (stable view model, 5-attempt retry, no ordering, immediate revocation), then all six acceptance criteria, then score through and generate tasks. The "test receiver" phrasing tripped the validation-block gate. Let me fix AC3 to describe only observable product behavior, then retry the batch. The PM authorized 5 attempts in the message that arrived before I submitted — the advisory is stale relative to that. The blocks committed successfully. Let me score the sections now and then create tasks per your directive. All three sections complete. Now creating the two tasks — credentials+read API and webhook registration+delivery — exactly as you outlined. Task 2 created. Task 1 rejected because I invented HTTP status codes the PM didn't specify. The PM said "a refusal" for cross-org, not "403." Let me fix the descriptions and remove the invented protocol mechanics. Both tasks staged. Now I need to build the complete trace graph. Let me trace every constraint and AC to its goal, and every task to its ACs. Spec is complete. Here's the final state: **Title**: Org-scoped API keys, spec read API, and verifiable outbound webhooks **3 goal blocks** — org-scoped machine auth, read-only spec REST API, verifiable outbound webhooks **8 constraint blocks** — org isolation, read-only v1, signed payloads, activity_events spine, stable view model, 5-attempt retry with backoff, no ordering guarantees, immediate key revocation **6 acceptance criteria** — API-key read without Clerk session, cross-org isolation (refusal, not empty list), signed webhook delivery to registered endpoint, 5-retry with permanent-failure visibility, immediate revocation, no internal JSON blobs in responses **2 tasks**: 1. **Add API key auth and GET endpoints for specs, blocks, and tasks** — API key management (create/revoke per org), Hono auth middleware accepting API keys alongside Clerk JWTs, GET endpoints returning a stable view model, cross-org refusal, immediate revocation 2. **Add webhook registration and signed delivery with retry** — endpoints for managing webhook URLs per org, delivery worker reading from activity_events, HMAC-signed payloads, 5-attempt exponential backoff with permanent failure and inspectable delivery history, no ordering guarantees Trace graph connects every constraint and AC to its goal, and both tasks to their ACs — complete coverage.