fix(approvals): reject contentless approval payloads at create

[claudegoogl-sudo]

Thinking Path

• Paperclip is the open source app people use to manage AI agents for work
• The board queues approval cards for an operator to decide. Agents file cards over POST /api/companies/{companyId}/approvals.
• A create with an empty payload ({}) passed validation and returned 201. The blank card then sat in the operator queue next to real, irreversible decisions.
• A pending approval cannot be cancelled or edited by its author. The author could not fix the card, and the operator could not tell it apart from a real request.
• This pull request rejects a contentless payload at the create boundary with 422 and a clear error, so a blank card never reaches the queue.
• The benefit is a queue where every card carries at least some content, with no change to any existing approval flow.

Linked Issues or Issue Description

No public GitHub issue exists for this. In-PR problem statement:

• What happened: an approval created with payload: {} was accepted and queued.
• Expected behavior: the create is rejected before any row is written.
• Steps to reproduce: POST /api/companies/{companyId}/approvals with {"type": "request_board_approval", "payload": {}} on master returns 201.
• Paperclip version/commit: master at c4b3c00de.
• Deployment mode: self-hosted single instance.

Related in-flight PR: #296 (feat/approval-request-integrity) also hardens approval payloads, with a different, larger shape: per-type required fields (title + summary) returning 400, plus a new withdraw route. This PR is the deliberately smaller complement: one type-agnostic rule (payload must have at least one key) returning 422, and no new routes. The two compose: #296 tightens per-type content at the validator; this PR guarantees no type can queue a fully empty card.

What Changed

• packages/shared/src/validators/approval.ts: add isEmptyApprovalPayload(payload) helper. It returns true for a payload with no keys.
• server/src/routes/approvals.ts: POST /companies/:companyId/approvals returns 422 with code: "approval_payload_empty" and a clear message when the payload is empty. The check runs after run-context authorization and before any persistence, so no approval row, issue link, or activity-log entry is written.
• Export the helper through the shared validators barrel and the shared package index.
• server/src/__tests__/approval-routes-empty-payload.test.ts: new route suite. It drives real requests through an express app, asserts 422 plus no persistence for {}, and pins the boundaries (one key accepted, valid create unchanged, missing payload still 400).

Rule choice: the guard is "payload must have at least one key" only. It is the smallest rule that catches the observed defect. A per-type or non-empty-string-value rule would invent payload schemas this change deliberately avoids. Any card with a key at least declares content; {"note": null} is accepted, which the new test pins.

Verification

Local, from server/ (fork master base c4b3c00de, Node on this host needed NODE_OPTIONS=--max-old-space-size=4096):

pnpm exec vitest run src/__tests__/approval-routes-empty-payload.test.ts \
  src/__tests__/approval-routes-idempotency.test.ts \
  src/__tests__/approvals-service.test.ts
# 3 files, 21 tests: 20 passed + 1 pre-existing flake (see Risks)

• New suite: 4/4 passed, stable across 5 consecutive runs (isolated and batched).
• pnpm exec tsc --noEmit in packages/shared and in server: both clean.
• The guard test fails without the change: on master the same request returns 201 and calls the create service.

Flake note: approval-routes-idempotency.test.ts > does not emit duplicate approval side effects when approve is already resolved timed out once per multi-file batch on this loaded host. A/B on a pristine c4b3c00de worktree reproduces the same timeout (2-file batch, no change from this PR involved), and the file passes 11/11 in isolation. Pre-existing load flake, unrelated to this change; single rerun per the CI rerun policy.

Risks

• Low risk by construction. The only behavior change: a create whose payload has zero keys now returns 422 instead of 201. Previously such creates produced an unfixable card, so no known caller depends on them.
• All approval types keep working; hire_agent secret normalization runs only after the guard, so valid hires are unchanged. Reject/approve/request-revision/resubmit paths are untouched.
• Layering with feat(approvals): require usable request payloads and add agent withdraw #296: if that PR merges first, its per-type validator rejects request_board_approval empties with 400 at the validate middleware, before this guard runs. This guard remains the type-agnostic backstop for every other type. No semantic conflict; whoever lands second rebases on the same route file.
• Documentation: docs/api/approvals.md describes create generally and does not enumerate per-route error codes today (matching the other route-level 422s in the codebase). feat(approvals): require usable request payloads and add agent withdraw #296 already extends that doc for its scope; this PR adds no doc surface to update beyond it.

Model Used

Claude (Anthropic) via the Paperclip agent runtime (JSON event-stream CLI driven by a local Paperclip adapter), extended thinking + tool use + code execution. Exact model id not exposed to this session; operating as agent "Coder" under the Paperclip runtime.

Checklist

• I have included a thinking path that traces from project context to this change
• I have specified the model used (with version and capability details)
• I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work (small targeted bug fix, Path 1; approval flow is not a roadmap feature area)
• I have searched GitHub for duplicate or related PRs and linked them above (feat(approvals): require usable request payloads and add agent withdraw #296 found and cross-linked)
• I have either (a) linked existing issues with Fixes: # / Closes # / Refs # OR (b) described the issue in-PR following the relevant issue template (path b, bug template fields)
• I have not referenced internal/instance-local Paperclip issues or links (only public GitHub #NNN / github.com/paperclipai/paperclip URLs)
• My branch name describes the change (e.g. docs/..., fix/...) and contains no internal Paperclip ticket id or instance-derived details
• I have run tests locally and they pass
• I have added or updated tests where applicable
• I have updated relevant documentation to reflect my changes (N/A beyond what exists: the API doc does not enumerate per-route validation error codes anywhere, including for the existing route-level 422s; error shape is self-describing in the response)
• I have considered and documented any risks above
• All Paperclip CI gates are green (pending on push; required verify check will be confirmed before merge)
• Greptile is 5/5 with no open P2s, recommendations, or follow-ups (N/A here: Greptile does not engage on this fork's PRs, so the gate is vacuous on this repo)
• I will address all Greptile and reviewer comments before requesting merge

Compliance statement: Follows CONTRIBUTING.md PR template — sections present: Thinking Path, Linked Issues or Issue Description, What Changed, Verification, Risks, Model Used, Checklist. Path-1 (small, focused) change: 5 files, one logical change, no bundled cleanups. No internal issue references in branch, title, description, or commits.