Spec review and approval

Now let me look at the review endpoint and the agent workflow phases. Let me check the spec store for task status transitions and the workflow state machine. Here's what I found in the repo: **Task lifecycle** (`specTasks.status`): `planned` → `todo` → `active` → `done`. No "approved" state exists. **Workflow phases**: `intent` → `constraints` → `acceptance` → `tasks` → `review` → `complete`. The `review` phase already exists, but it's entirely automated: - `GET /v1/agent/review/:specId/preflight` — deterministic structural checks (missing goals, unmeasurable ACs, task cycle detection, uncovered criteria). Not a human workflow. - `POST /v1/agent/review/:specId` — an async *LLM agent* review that generates questions about completeness. Also not a human. - The workflow scheduler processes the agent review results and can advance through `review` to `complete` without any human clicking "approved." **The gate for execution**: `startSpecExecution()` checks `workflow.phase === "complete" && workflow.status === "complete" && terminalOutcome === "completed"` before flipping `planned` → `todo` so the CLI daemon can claim tasks. Nothing in that chain requires human sign-off. So your description is accurate: no human approval step exists. The agent writes, the agent reviews itself (preflight + LLM pass), then the workflow advances to complete and tasks unlock for the coding daemon. Given that reality, here's the most scope-defining question: The automated review phase exists but nothing forces a human to actually look at the output before tasks become claimable. The most natural spot to insert a human step is gating the transition from `review` to `complete` in the workflow — that way the automated preflight still catches structural issues first, but a real person must explicitly advance the workflow before the daemon can claim tasks. The three options above cover the main alternatives.

You rejected the blocking-gate framing, and the constraints above capture that cleanly. Now the real question you're inviting. Score clamped to 0.5 because I need 2+ goals. The answer to your question will define what the second goal is. So: The same primitive — a recorded attestation (who, when) — can serve all three motivations. A badge on the spec list gives teams a reason to want it approved. An audit trail satisfies compliance requirements. Notifications turn it into a social workflow. And all three don't gate execution, which matches your constraint. But that's my take — which of these (or what else) is actually driving the need?

This is the key insight. Let me capture it as blocks and close out that question. Scored 0.65 — not clamped, but audience is the weakest dimension. Who can approve? The simplest model that matches "attestation, not gate" is any collaborator can record one. But you may have a different line — owner-only keeps the signal higher quality, named reviewers makes it a request workflow, tiered visibility separates "someone looked at it" from "someone authoritative signed off."

Intent is complete. Moving to acceptance. Before I insert criteria, here's the one question I need answered to make them concrete: While you consider that, here are the acceptance criteria I can already write from locked decisions: Five criteria inserted covering the locked decisions. The remaining open dimension is how approval is initiated (button on spec page, API, or both) — that'll determine criteria about the UI surface and any API contract.

All three sections at 0.9+. Let me update the summary to reflect locked scope, then generate the single capability task. Now for the task. This is one capability — the API, schema, staleness logic, and UI button together deliver one user-visible outcome ("a human can review and approve a spec, and the spec shows its approval state"). Let me verify once more that this shouldn't be two tasks. The acceptance criteria cover: - Non-blocking behavior (AC1) - Staleness display on spec page (AC2) - Re-approval creates new record (AC3) - Self-approval labeling (AC4) - No workflow states (AC5) - API endpoint + server-side auth (AC6) - UI button as API client (AC7) - Approval record fields (AC8) AC6 and AC7 are the same capability — the button calls the API. AC2 and AC4 are the same display surface. One task. Task created. Now building the complete trace graph. Spec complete. Here's what was built: **Title:** Spec review and approval **Summary:** Non-blocking human approval for specs, bound to the spec revision it was granted against. Any org member can record an attestation via API or UI button; stale approvals are visibly marked when the spec changes. No workflow states, no execution gating. **Key decisions your grilling surfaced:** - Approval is a recorded attestation, not a lock — never blocks workflow advancement, task creation, or task claiming - Bound to the existing `specs.revision` column; staleness is derived, not a parallel state - Any org member except the requester can approve; self-approval is allowed but labeled - API is authoritative; the Approve button is a client of the same endpoint with server-side-only authorization - No review workflow states (no "changes requested," no assignments, no reminders) **One task:** `da3720e2-6bc0-4ae4-997f-ffb15e5992e7` — Adds the `spec_approvals` table, the approval API endpoint, and the approval-state badge on the spec page, covering all 8 acceptance criteria.