ADR — PR #982

2026-05-18 10:00 — Validate UUID path parameters

Comments:
- https://github.com/dboone31/erp-unlocked/pull/982#discussion_r3252849671 (mark-ready)
- https://github.com/dboone31/erp-unlocked/pull/982#discussion_r3252849675 (unmark-ready)
Priority: must-fix
Decision: accept
Rationale: Reject malformed IDs before reaching the database using Zod validation (the project’s standard for type-safe validation). Error message is endpoint-specific (“Work item ID must be a valid UUID”) for clearer client feedback.

Comment: https://github.com/dboone31/erp-unlocked/pull/982#discussion_r3255557873
Priority: must-fix
Decision: accept
Rationale: Verifies that both mark-ready and unmark-ready endpoints correctly reject malformed UUIDs with a 400 status code, ensuring API contract compliance.

Comments:
- https://github.com/dboone31/erp-unlocked/pull/982#discussion_r3255557876 (assert on set(…))
- https://github.com/dboone31/erp-unlocked/pull/982#discussion_r3255557878 (assert manuallyReadyAt: null on unmark)
Priority: must-fix
Decision: accept
Rationale: Implemented more precise assertions for the database update payload (specifically the version bump expression), the manuallyReadyAt: null clear on unmark, and the capability-guard argument shape. Verifies both mutation intent and authorization for the success path.

Decision: accept
Rationale: Verified that all CodeRabbit findings (UUID validation, strengthened assertions, and malformed-UUID test cases) are correctly implemented and passing tests. This final review confirms the API contract is robust and the implementation follows project standards.

Comment: N/A (CI fix)
Priority: must-fix
Decision: accept
Rationale: Updated the Turborepo filter in .github/workflows/validate.yml from webapp to @erp-unlocked/webapp. The previous filter caused the “Test Web Service” job to fail because Turborepo requires the full package name, unlike pnpm which can filter by directory name.

Priority: nice-to-have
Decision: accept
Rationale: Standardized the error message across mark-ready and unmark-ready endpoints to “Work item ID must be a valid UUID” for a more consistent API experience. Updated tests to reflect this change.