3.4: Work Item Notes & Subtasks API

[steilerDev]

As a homeowner, I want to add notes and checklist subtasks to work items so that I can track detailed progress and record important information for each construction task.

Parent Epic: #3
Priority: Must Have

Acceptance Criteria

Notes

• 1. POST /api/work-items/:workItemId/notes creates a new note on a work item and returns 201. Required field: content (text, non-empty). The createdBy field is automatically set to the authenticated user. Returns 404 NOT_FOUND if the work item does not exist.
• 2. GET /api/work-items/:workItemId/notes returns all notes for a work item (200 OK), sorted by created_at descending (newest first). Each note includes id, content, createdBy (user summary: { id, displayName }), createdAt, updatedAt.
• 3. PATCH /api/work-items/:workItemId/notes/:noteId updates a note's content (200 OK). Only the note's author or an admin can edit a note. Returns 403 FORBIDDEN if a non-admin user tries to edit another user's note. Returns 404 NOT_FOUND if the note or work item does not exist.
• 4. DELETE /api/work-items/:workItemId/notes/:noteId deletes a note (204 No Content). Only the note's author or an admin can delete a note. Returns 403 FORBIDDEN if unauthorized. Returns 404 NOT_FOUND if the note or work item does not exist.

Subtasks

• 5. POST /api/work-items/:workItemId/subtasks creates a new subtask and returns 201. Required field: title (text, non-empty). Optional field: sortOrder (integer). If sortOrder is not provided, the subtask is appended to the end (max sort_order + 1). Returns 404 NOT_FOUND if the work item does not exist.
• 6. GET /api/work-items/:workItemId/subtasks returns all subtasks for a work item (200 OK), sorted by sort_order ascending.
• 7. PATCH /api/work-items/:workItemId/subtasks/:subtaskId updates a subtask's title, completion status (isCompleted), and/or sort order (200 OK). Returns 404 NOT_FOUND if the subtask or work item does not exist.
• 8. DELETE /api/work-items/:workItemId/subtasks/:subtaskId deletes a subtask (204 No Content). Returns 404 NOT_FOUND if the subtask or work item does not exist.
• 9. PATCH /api/work-items/:workItemId/subtasks/reorder accepts an ordered array of subtask IDs and updates the sort_order of each subtask to match the array order (200 OK). Returns 400 VALIDATION_ERROR if any subtask ID does not belong to the specified work item.

Cross-cutting

• 10. All endpoints require authentication (401 UNAUTHORIZED without valid session). Both admin and member roles can manage notes and subtasks.
• 11. Validation errors return 400 VALIDATION_ERROR for: empty content/title, non-integer sort_order.

Notes

• Depends on Story 3.2 (work items must be creatable before notes/subtasks can be added).
• Notes are attributed to the user who created them — this enables an activity-log style display.
• Subtask reorder (AC EPIC-09: Dashboard & Project Health Center #9) allows drag-and-drop reordering on the frontend without having to update each subtask individually.
• The createdBy FK uses SET NULL on delete so that notes remain even if the creating user is removed.
• Depends on: 3.2: Work Items CRUD API #88 (Story 3.2)

[steilerDev]

[uat-validator]

UAT Scenarios: Story 3.4 — Work Item Notes & Subtasks API

Preconditions

• Story 3.1 (schema) is complete — notes and subtasks tables exist
• Story 3.2 (work items CRUD) is complete — work items can be created
• Authentication system is functional with test users

---

Scenario Group: Create Note (POST /api/work-items/:workItemId/notes)

UAT-3.4-01: Create note with valid content

Given I am authenticated as user "user-abc"
And a work item exists with ID "work-123"
When I POST to /api/work-items/work-123/notes with body:

{
  "content": "Met with contractor today. Foundation work starts Monday."
}

Then the response status is 201
And the response body contains:

• id (UUID)
• workItemId = "work-123"
• content = "Met with contractor today. Foundation work starts Monday."
• createdBy = { id: "user-abc", displayName: "..." }
• createdAt and updatedAt (ISO 8601 timestamps)
  Verification Method: Automated (integration test)

UAT-3.4-02: Create fails with empty content

Given I am authenticated
And a work item exists
When I POST to /api/work-items/work-123/notes with body:

{
  "content": ""
}

Then the response status is 400
And the error code is VALIDATION_ERROR
Verification Method: Automated (integration test)

UAT-3.4-03: Create fails with content exceeding 10,000 characters

Given I am authenticated
And a work item exists
When I POST to /api/work-items/work-123/notes with content = 10,001-character string
Then the response status is 400
And the error code is VALIDATION_ERROR
Verification Method: Automated (integration test)

UAT-3.4-04: Create fails for non-existent work item

Given I am authenticated
When I POST to /api/work-items/non-existent-uuid/notes with valid body
Then the response status is 404
And the error code is NOT_FOUND
Verification Method: Automated (integration test)

UAT-3.4-05: Create requires authentication

Given I am NOT authenticated
When I POST to /api/work-items/work-123/notes with valid body
Then the response status is 401
And the error code is UNAUTHORIZED
Verification Method: Automated (integration test)

UAT-3.4-06: createdBy is automatically set from session

Given I am authenticated as user "user-xyz"
And a work item exists
When I POST to /api/work-items/work-123/notes with valid body
Then the created note has createdBy.id = "user-xyz"
And the request body does NOT allow overriding createdBy
Verification Method: Automated (integration test)

---

Scenario Group: List Notes (GET /api/work-items/:workItemId/notes)

UAT-3.4-07: List returns all notes sorted newest first

Given I am authenticated
And a work item exists with 3 notes created at different times
When I GET /api/work-items/work-123/notes
Then the response status is 200
And the response is an array of note objects
And notes are sorted by createdAt descending (newest first)
Verification Method: Automated (integration test)

UAT-3.4-08: List returns empty array when no notes exist

Given I am authenticated
And a work item exists with no notes
When I GET /api/work-items/work-123/notes
Then the response status is 200
And the response is an empty array
Verification Method: Automated (integration test)

UAT-3.4-09: List fails for non-existent work item

Given I am authenticated
When I GET /api/work-items/non-existent-uuid/notes
Then the response status is 404
And the error code is NOT_FOUND
Verification Method: Automated (integration test)

UAT-3.4-10: List requires authentication

Given I am NOT authenticated
When I GET /api/work-items/work-123/notes
Then the response status is 401
And the error code is UNAUTHORIZED
Verification Method: Automated (integration test)

---

Scenario Group: Update Note (PATCH /api/work-items/:workItemId/notes/:noteId)

UAT-3.4-11: Author can update their own note

Given I am authenticated as user "user-abc"
And a note exists created by "user-abc" with ID "note-123"
When I PATCH /api/work-items/work-123/notes/note-123 with body:

{
  "content": "Updated note content."
}

Then the response status is 200
And the note's content is updated
And the updatedAt timestamp is updated
Verification Method: Automated (integration test)

UAT-3.4-12: Admin can update any note

Given I am authenticated as an admin user
And a note exists created by another user
When I PATCH the note with valid content
Then the response status is 200
And the note is updated
Verification Method: Automated (integration test)

UAT-3.4-13: Non-author member cannot update note

Given I am authenticated as user "user-xyz" (member, not admin)
And a note exists created by "user-abc" (different user)
When I PATCH the note with valid content
Then the response status is 403
And the error code is FORBIDDEN
Verification Method: Automated (integration test)

UAT-3.4-14: Update fails with empty content

Given I am authenticated as the note's author
When I PATCH the note with content = ""
Then the response status is 400
And the error code is VALIDATION_ERROR
Verification Method: Automated (integration test)

UAT-3.4-15: Update fails for non-existent note

Given I am authenticated
When I PATCH /api/work-items/work-123/notes/non-existent-uuid with valid body
Then the response status is 404
And the error code is NOT_FOUND
Verification Method: Automated (integration test)

UAT-3.4-16: Update requires authentication

Given I am NOT authenticated
When I PATCH /api/work-items/work-123/notes/note-123 with valid body
Then the response status is 401
And the error code is UNAUTHORIZED
Verification Method: Automated (integration test)

---

Scenario Group: Delete Note (DELETE /api/work-items/:workItemId/notes/:noteId)

UAT-3.4-17: Author can delete their own note

Given I am authenticated as user "user-abc"
And a note exists created by "user-abc" with ID "note-123"
When I DELETE /api/work-items/work-123/notes/note-123
Then the response status is 204
And subsequent GET to the notes list does not include note-123
Verification Method: Automated (integration test)

UAT-3.4-18: Admin can delete any note

Given I am authenticated as an admin user
And a note exists created by another user
When I DELETE the note
Then the response status is 204
And the note is deleted
Verification Method: Automated (integration test)

UAT-3.4-19: Non-author member cannot delete note

Given I am authenticated as user "user-xyz" (member, not admin)
And a note exists created by "user-abc"
When I DELETE the note
Then the response status is 403
And the error code is FORBIDDEN
Verification Method: Automated (integration test)

UAT-3.4-20: Delete fails for non-existent note

Given I am authenticated
When I DELETE /api/work-items/work-123/notes/non-existent-uuid
Then the response status is 404
And the error code is NOT_FOUND
Verification Method: Automated (integration test)

UAT-3.4-21: Delete requires authentication

Given I am NOT authenticated
When I DELETE /api/work-items/work-123/notes/note-123
Then the response status is 401
And the error code is UNAUTHORIZED
Verification Method: Automated (integration test)

---

Scenario Group: Create Subtask (POST /api/work-items/:workItemId/subtasks)

UAT-3.4-22: Create subtask with title only

Given I am authenticated
And a work item exists with ID "work-123"
When I POST to /api/work-items/work-123/subtasks with body:

{
  "title": "Order materials"
}

Then the response status is 201
And the response body contains:

• id (UUID)
• workItemId = "work-123"
• title = "Order materials"
• isCompleted = false
• sortOrder = 0 (or next available order)
• createdAt and updatedAt
  Verification Method: Automated (integration test)

UAT-3.4-23: Create subtask with explicit sort order

Given I am authenticated
And a work item exists with 2 subtasks (sort_order 0 and 1)
When I POST to /api/work-items/work-123/subtasks with body:

{
  "title": "New subtask",
  "sortOrder": 1
}

Then the response status is 201
And the new subtask has sortOrder = 1
Verification Method: Automated (integration test)

UAT-3.4-24: Create subtask without sort order appends to end

Given I am authenticated
And a work item exists with 2 subtasks (max sort_order = 1)
When I POST to /api/work-items/work-123/subtasks with body:

{
  "title": "Last subtask"
}

Then the response status is 201
And the new subtask has sortOrder = 2
Verification Method: Automated (integration test)

UAT-3.4-25: Create fails with empty title

Given I am authenticated
And a work item exists
When I POST to /api/work-items/work-123/subtasks with title = ""
Then the response status is 400
And the error code is VALIDATION_ERROR
Verification Method: Automated (integration test)

UAT-3.4-26: Create fails with title exceeding 500 characters

Given I am authenticated
And a work item exists
When I POST to /api/work-items/work-123/subtasks with title = 501-character string
Then the response status is 400
And the error code is VALIDATION_ERROR
Verification Method: Automated (integration test)

UAT-3.4-27: Create fails for non-existent work item

Given I am authenticated
When I POST to /api/work-items/non-existent-uuid/subtasks with valid body
Then the response status is 404
And the error code is NOT_FOUND
Verification Method: Automated (integration test)

UAT-3.4-28: Create requires authentication

Given I am NOT authenticated
When I POST to /api/work-items/work-123/subtasks with valid body
Then the response status is 401
And the error code is UNAUTHORIZED
Verification Method: Automated (integration test)

---

Scenario Group: List Subtasks (GET /api/work-items/:workItemId/subtasks)

UAT-3.4-29: List returns all subtasks sorted by sort order

Given I am authenticated
And a work item exists with 3 subtasks (sort_order 2, 0, 1)
When I GET /api/work-items/work-123/subtasks
Then the response status is 200
And the response is an array of subtask objects
And subtasks are sorted by sortOrder ascending (0, 1, 2)
Verification Method: Automated (integration test)

UAT-3.4-30: List returns empty array when no subtasks exist

Given I am authenticated
And a work item exists with no subtasks
When I GET /api/work-items/work-123/subtasks
Then the response status is 200
And the response is an empty array
Verification Method: Automated (integration test)

UAT-3.4-31: List fails for non-existent work item

Given I am authenticated
When I GET /api/work-items/non-existent-uuid/subtasks
Then the response status is 404
And the error code is NOT_FOUND
Verification Method: Automated (integration test)

UAT-3.4-32: List requires authentication

Given I am NOT authenticated
When I GET /api/work-items/work-123/subtasks
Then the response status is 401
And the error code is UNAUTHORIZED
Verification Method: Automated (integration test)

---

Scenario Group: Update Subtask (PATCH /api/work-items/:workItemId/subtasks/:subtaskId)

UAT-3.4-33: Update subtask title

Given I am authenticated
And a subtask exists with ID "subtask-123"
When I PATCH /api/work-items/work-123/subtasks/subtask-123 with body:

{
  "title": "Updated title"
}

Then the response status is 200
And the subtask's title is updated
And updatedAt is updated
Verification Method: Automated (integration test)

UAT-3.4-34: Update subtask completion status

Given I am authenticated
And a subtask exists with isCompleted = false
When I PATCH the subtask with body:

{
  "isCompleted": true
}

Then the response status is 200
And the subtask's isCompleted is now true
Verification Method: Automated (integration test)

UAT-3.4-35: Update subtask sort order

Given I am authenticated
And a subtask exists with sortOrder = 1
When I PATCH the subtask with body:

{
  "sortOrder": 0
}

Then the response status is 200
And the subtask's sortOrder is now 0
Verification Method: Automated (integration test)

UAT-3.4-36: Update fails with empty title

Given I am authenticated
And a subtask exists
When I PATCH the subtask with title = ""
Then the response status is 400
And the error code is VALIDATION_ERROR
Verification Method: Automated (integration test)

UAT-3.4-37: Update fails for non-existent subtask

Given I am authenticated
When I PATCH /api/work-items/work-123/subtasks/non-existent-uuid with valid body
Then the response status is 404
And the error code is NOT_FOUND
Verification Method: Automated (integration test)

UAT-3.4-38: Update requires authentication

Given I am NOT authenticated
When I PATCH /api/work-items/work-123/subtasks/subtask-123 with valid body
Then the response status is 401
And the error code is UNAUTHORIZED
Verification Method: Automated (integration test)

---

Scenario Group: Delete Subtask (DELETE /api/work-items/:workItemId/subtasks/:subtaskId)

UAT-3.4-39: Delete removes subtask

Given I am authenticated
And a subtask exists with ID "subtask-123"
When I DELETE /api/work-items/work-123/subtasks/subtask-123
Then the response status is 204
And subsequent GET to the subtasks list does not include subtask-123
Verification Method: Automated (integration test)

UAT-3.4-40: Delete fails for non-existent subtask

Given I am authenticated
When I DELETE /api/work-items/work-123/subtasks/non-existent-uuid
Then the response status is 404
And the error code is NOT_FOUND
Verification Method: Automated (integration test)

UAT-3.4-41: Delete requires authentication

Given I am NOT authenticated
When I DELETE /api/work-items/work-123/subtasks/subtask-123
Then the response status is 401
And the error code is UNAUTHORIZED
Verification Method: Automated (integration test)

---

Scenario Group: Reorder Subtasks (PATCH /api/work-items/:workItemId/subtasks/reorder)

UAT-3.4-42: Reorder updates sort order for all subtasks

Given I am authenticated
And a work item has 3 subtasks: ["st-a", "st-b", "st-c"] with sort_order [0, 1, 2]
When I PATCH /api/work-items/work-123/subtasks/reorder with body:

{
  "subtaskIds": ["st-c", "st-a", "st-b"]
}

Then the response status is 200
And the subtasks now have sort_order: st-c=0, st-a=1, st-b=2
Verification Method: Automated (integration test)

UAT-3.4-43: Reorder fails with missing subtask IDs

Given I am authenticated
And a work item has 3 subtasks: ["st-a", "st-b", "st-c"]
When I PATCH reorder with subtaskIds = ["st-a", "st-b"] (missing "st-c")
Then the response status is 400
And the error code is VALIDATION_ERROR
And the error message indicates all subtask IDs must be included
Verification Method: Automated (integration test)

UAT-3.4-44: Reorder fails with subtask ID from different work item

Given I am authenticated
And work item "work-123" has subtasks ["st-a", "st-b"]
And work item "work-456" has subtask "st-x"
When I PATCH /api/work-items/work-123/subtasks/reorder with subtaskIds = ["st-a", "st-b", "st-x"]
Then the response status is 400
And the error code is VALIDATION_ERROR
Verification Method: Automated (integration test)

UAT-3.4-45: Reorder fails for non-existent work item

Given I am authenticated
When I PATCH /api/work-items/non-existent-uuid/subtasks/reorder with valid body
Then the response status is 404
And the error code is NOT_FOUND
Verification Method: Automated (integration test)

UAT-3.4-46: Reorder requires authentication

Given I am NOT authenticated
When I PATCH /api/work-items/work-123/subtasks/reorder with valid body
Then the response status is 401
And the error code is UNAUTHORIZED
Verification Method: Automated (integration test)

---

Scenario Group: Role-Based Access

UAT-3.4-47: Member users can create notes

Given I am authenticated as a member (not admin)
And a work item exists
When I POST a note with valid content
Then the response status is 201
And the note is created
Verification Method: Automated (integration test)

UAT-3.4-48: Member users can create subtasks

Given I am authenticated as a member
And a work item exists
When I POST a subtask with valid title
Then the response status is 201
And the subtask is created
Verification Method: Automated (integration test)

---

Edge Cases

UAT-3.4-49: Note with deleted createdBy user shows gracefully

Given a note exists created by user "user-abc"
And user "user-abc" is deleted (createdBy set to NULL via FK ON DELETE SET NULL)
When I GET the notes list
Then the note still appears
And createdBy is null or shows "Unknown User"
Verification Method: Automated (integration test)

UAT-3.4-50: Subtasks with gaps in sort_order sort correctly

Given I am authenticated
And subtasks exist with sort_order [0, 5, 10]
When I GET the subtasks list
Then the subtasks are returned in order: 0, 5, 10
Verification Method: Automated (integration test)

UAT-3.4-51: Note content with newlines and special characters is preserved

Given I am authenticated
When I POST a note with content containing newlines, quotes, and emojis
Then the response status is 201
And the note content is stored exactly as submitted
And subsequent GET returns the content unchanged
Verification Method: Automated (integration test)

---

Automated Test Mapping

• Integration tests: server/src/routes/work-items/notes/create.test.ts
• Integration tests: server/src/routes/work-items/notes/list.test.ts
• Integration tests: server/src/routes/work-items/notes/update.test.ts
• Integration tests: server/src/routes/work-items/notes/delete.test.ts
• Integration tests: server/src/routes/work-items/subtasks/create.test.ts
• Integration tests: server/src/routes/work-items/subtasks/list.test.ts
• Integration tests: server/src/routes/work-items/subtasks/update.test.ts
• Integration tests: server/src/routes/work-items/subtasks/delete.test.ts
• Integration tests: server/src/routes/work-items/subtasks/reorder.test.ts
• E2E tests: e2e/tests/work-items/notes-subtasks.spec.ts (owned by e2e-test-engineer)

---

Notes for Developers

• createdBy attribution: Always set from req.session.user.id, never accept from request body
• Authorization check for note edit/delete: req.session.user.role === 'admin' || note.createdBy === req.session.user.id
• Reorder validation: Fetch all subtasks for the work item, verify the submitted array contains exactly the same IDs (no more, no less)
• Reorder implementation: Loop through subtaskIds array and UPDATE each subtask's sort_order to its index position
• Note content sanitization: Store as plain text, escape on output if rendering as HTML
• subtask isCompleted: Stored as INTEGER (0 or 1), returned as boolean in JSON
• createdBy user summary: Join on users table to fetch displayName and email for response

[steilerDev]

[e2e-test-engineer]

E2E Feasibility Review: Story #90 — Work Item Notes & Subtasks API

Summary

This story includes UI components for notes and subtasks, with rich interactions (add, edit, delete, reorder). Strong E2E testing candidate.

E2E Coverage Assessment

✅ Suitable for E2E (17 scenarios)

These scenarios involve browser interactions and should be tested with Playwright:

Notes UI (from story #92, referenced here):

• Adding a new note via textarea + submit
• Editing own note (inline edit)
• Deleting own note (with confirmation)
• Admin editing/deleting any note
• Non-admin cannot edit/delete others' notes (UI hides actions)
• Notes displayed in reverse chronological order

Subtasks UI (from story #92, referenced here):

• Adding a new subtask via input + submit
• Checking/unchecking subtask checkbox
• Editing subtask title (inline edit)
• Deleting subtask (with confirmation)
• Drag-and-drop reordering of subtasks
• Progress bar reflects completed percentage

These scenarios will be tested in e2e/tests/work-items/notes-subtasks.spec.ts after story #92 (detail page UI) is implemented.

⚠️ Integration Tests Only (34 scenarios)

API-level validation and error handling:

Create note API (UAT-3.4-01 to UAT-3.4-06): Validation, non-existent work item, authentication, createdBy attribution
List notes API (UAT-3.4-07 to UAT-3.4-10): Sorting, empty state, 404, authentication
Update note API (UAT-3.4-11 to UAT-3.4-16): Author/admin permissions, validation, 404, 403
Delete note API (UAT-3.4-17 to UAT-3.4-21): Author/admin permissions, 403 for non-author members
Create subtask API (UAT-3.4-22 to UAT-3.4-27): Validation, sort_order default
List subtasks API (UAT-3.4-28 to UAT-3.4-30): Sorting by sort_order
Update subtask API (UAT-3.4-31 to UAT-3.4-35): Toggle completion, edit title, validation
Delete subtask API (UAT-3.4-36 to UAT-3.4-38): Delete, 404
Reorder subtasks API (UAT-3.4-39 to UAT-3.4-46): Reorder validation, missing/extra IDs
RBAC (UAT-3.4-47 to UAT-3.4-48): Member can create notes/subtasks
Edge cases (UAT-3.4-49 to UAT-3.4-51): Deleted user handling, gaps in sort_order, special characters

📋 E2E Test Plan

Defer E2E tests until story #92 is complete. Once the detail page UI exists, I will write Playwright tests covering:

1. Notes Section (desktop + mobile):

   • Add note via textarea
   • Edit own note inline
   • Delete own note
   • Admin edits/deletes any note
   • Member cannot edit/delete others' notes (actions hidden)
   • Verify notes sorted newest first

2. Subtasks Section (desktop + mobile):

   • Add subtask via input field
   • Check/uncheck subtask
   • Edit subtask title inline
   • Delete subtask
   • Drag-and-drop reorder (desktop only, >= 1024px viewport)
   • Touch-based reorder (mobile/tablet, < 1024px viewport)
   • Progress bar updates correctly

3. RBAC (already covered in EPIC-01, but will verify):

   • Member can create notes/subtasks
   • Non-admin cannot edit/delete others' notes

🔍 Clarifications Needed

UAT-3.4-13: "Non-author member cannot update note" — should the Edit button be hidden or disabled for non-author members? Hidden is better UX (less confusion).

Drag-and-drop on mobile: Will subtask reordering use native drag-and-drop API or a touch-friendly library? Libraries like @dnd-kit/core support both mouse and touch events. Recommendation: Use @dnd-kit/core for cross-device compatibility.

Subtask reorder API (UAT-3.4-39 to UAT-3.4-46): The API requires submitting the full subtaskIds array in new order. This is testable in E2E by:

1. Dragging a subtask to a new position
2. Verifying the API call sends correct order
3. Reloading the page and verifying order persists

Recommendations for QA

1. qa-integration-tester: Cover all 34 API scenarios with integration tests
2. e2e-test-engineer (me): Cover all 17 UI scenarios with Playwright E2E tests after story 3.6: Work Item Detail & Edit Page #92
3. Test drag-and-drop across all 5 viewport projects (desktop-lg, desktop-md, tablet, mobile-iphone, mobile-android)
4. Verify keyboard accessibility for notes/subtasks (Tab, Enter, Escape)

Page Object Model Considerations

Will extend WorkItemDetailPage POM with:

• addNote(content: string)
• editNote(noteId: string, newContent: string)
• deleteNote(noteId: string)
• addSubtask(title: string)
• toggleSubtask(subtaskId: string)
• editSubtask(subtaskId: string, newTitle: string)
• deleteSubtask(subtaskId: string)
• reorderSubtask(fromIndex: number, toIndex: number)
• getSubtaskOrder() — for verifying order after reorder

[steilerDev]

[qa-integration-tester]

UAT Testability Review — Story 3.4 (Notes & Subtasks API)

Overall Assessment

✅ Highly testable — all 51 scenarios automatable via integration tests

Strengths

• Authorization scenarios are comprehensive (author vs non-author, admin override)
• Reorder subtasks endpoint logic is well-specified (UAT-3.4-42-46)
• Edge cases like deleted createdBy user are covered (UAT-3.4-49)

Clarifications Needed

UAT-3.4-06: createdBy override prevention

• Add integration test: attempt POST with createdBy in request body
• Verify it's ignored and session user ID is used

UAT-3.4-12, UAT-3.4-13: Authorization after user deletion

• If createdBy is NULL after user deletion (ON DELETE SET NULL), who can edit/delete that note?
• Recommendation: allow admin only, or lock the note entirely

UAT-3.4-24: Sort order calculation

• Specify: MAX(sort_order) + 1 or COUNT(*)?
• Recommend MAX(sort_order) + 1 for gap handling

UAT-3.4-43: Duplicate subtask IDs in reorder

• What if the same subtask ID appears twice in the array?
• Add validation: array must contain unique IDs

UAT-3.4-44: Cross-work-item subtask error

• Clarify error message: VALIDATION_ERROR with "Subtask ID 'st-x' does not belong to work item 'work-123'"

UAT-3.4-51: Unicode and special characters

• Add specific test case:
  • Unicode emoji (e.g., 🚀)
  • Newline \n
  • Double quote "
  • Single quote '

Missing Integration Test Scenarios

Note creation performance

• Create 100 notes for a single work item
• Verify list endpoint performance (target: < 1s)

Reorder race condition

• Two users reorder subtasks simultaneously
• Expected behavior: last write wins or return 409 conflict?

95% Test Coverage

✅ Achievable — all API endpoints testable via app.inject(). Authorization logic testable by mocking session user role/ID.

Integration Test Coverage Plan

• server/src/routes/work-items/notes/create.test.ts
• server/src/routes/work-items/notes/list.test.ts
• server/src/routes/work-items/notes/update.test.ts
• server/src/routes/work-items/notes/delete.test.ts
• server/src/routes/work-items/subtasks/create.test.ts
• server/src/routes/work-items/subtasks/list.test.ts
• server/src/routes/work-items/subtasks/update.test.ts
• server/src/routes/work-items/subtasks/delete.test.ts
• server/src/routes/work-items/subtasks/reorder.test.ts

---

Ready to proceed after clarifications above are addressed. No blocking issues for unit/integration test coverage.