docs(12): create phase plan

Phase 12: Attachment Research & Backend Validation
- 2 plan(s) in 1 wave(s)
- 2 parallel, 0 sequential
- Ready for execution

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.planning/ROADMAP.md

@@ -214,8 +214,8 @@ Plans:
 5. Integration points identified (chat window, WebSocket, Redux)
 
 Plans:
-- [ ] 12-01: Document legacy attachment implementation and backend API surface
-- [ ] 12-02: Validate backend infrastructure and design React integration strategy
+- [ ] 12-01-PLAN.md — Document legacy AttachmentStore and backend API contract
+- [ ] 12-02-PLAN.md — Validate backend infrastructure and design React integration strategy
 
 #### Phase 13: File Upload Infrastructure
 **Goal**: Users can select files from OS dialog and upload to S3 with validation and progress feedback
@@ -318,7 +318,7 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 →
 | 9. Message Composition & Sending | v1.1 | 2/2 | Complete | 2026-01-27 |
 | 10. Read/Unread Status Management | v1.1 | 1/1 | Complete | 2026-01-27 |
 | 11. Chat Finalization | v1.1 | 2/2 | Complete | 2026-01-31 |
-| 12. Attachment Research & Backend Validation | v1.2 | 0/2 | Not started | - |
+| 12. Attachment Research & Backend Validation | v1.2 | 0/2 | Planned | - |
 | 13. File Upload Infrastructure | v1.2 | 0/3 | Not started | - |
 | 14. Chat Integration & Display | v1.2 | 0/2 | Not started | - |
 | 15. Real-time Synchronization | v1.2 | 0/1 | Not started | - |

.planning/phases/12-attachment-research-&-backend-validation/12-01-PLAN.md

@@ -0,0 +1,186 @@
+---
+phase: 12-attachment-research-&-backend-validation
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - .planning/phases/12-attachment-research-&-backend-validation/docs/ATTACHMENT_LEGACY.md
+  - .planning/phases/12-attachment-research-&-backend-validation/docs/ATTACHMENT_API.md
+autonomous: true
+
+must_haves:
+  truths:
+    - "Legacy AttachmentStore upload flow is documented with code examples"
+    - "Backend API contract is documented with endpoints, payloads, and responses"
+    - "File validation rules are documented (types, sizes, error responses)"
+  artifacts:
+    - path: ".planning/phases/12-attachment-research-&-backend-validation/docs/ATTACHMENT_LEGACY.md"
+      provides: "Legacy implementation patterns and CoffeeScript code analysis"
+      min_lines: 150
+    - path: ".planning/phases/12-attachment-research-&-backend-validation/docs/ATTACHMENT_API.md"
+      provides: "Backend API contract documentation"
+      min_lines: 200
+  key_links:
+    - from: "ATTACHMENT_LEGACY.md"
+      to: "ATTACHMENT_API.md"
+      via: "API calls reference"
+      pattern: "POST.*music_notations"
+---
+
+<objective>
+Document legacy attachment implementation patterns and backend API surface for file uploads.
+
+Purpose: Provide comprehensive reference documentation for Phase 13-16 implementation. This ensures the React port accurately replicates working patterns from the legacy CoffeeScript implementation.
+
+Output: Two documentation files (ATTACHMENT_LEGACY.md, ATTACHMENT_API.md) that serve as the definitive reference for attachment functionality.
+</objective>
+
+<execution_context>
+@/Users/nuwan/.claude/get-shit-done/workflows/execute-plan.md
+@/Users/nuwan/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/12-attachment-research-&-backend-validation/12-RESEARCH.md
+
+# Source files to analyze
+@web/app/assets/javascripts/react-components/stores/AttachmentStore.js.coffee
+@web/app/controllers/api_music_notations_controller.rb
+@ruby/lib/jam_ruby/models/music_notation.rb
+@ruby/lib/jam_ruby/uploaders/music_notation_uploader.rb
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Document Legacy AttachmentStore Implementation</name>
+  <files>.planning/phases/12-attachment-research-&-backend-validation/docs/ATTACHMENT_LEGACY.md</files>
+  <action>
+Create comprehensive documentation of the legacy CoffeeScript AttachmentStore:
+
+1. **File Structure Section:**
+   - Document file location and purpose
+   - List all public methods and their signatures
+   - Document Reflux store pattern used
+
+2. **Upload Flow Section:**
+   - Step-by-step breakdown of uploadFiles() method
+   - FormData construction (files[], session_id, attachment_type)
+   - Ajax request configuration (processData: false, contentType: false)
+   - Success/error callback handling
+
+3. **Client-Side Validation Section:**
+   - File size check implementation (10 MB limit)
+   - File type validation (extension whitelist)
+   - Error message generation
+   - How validation errors are surfaced to UI
+
+4. **Attachment Type Detection Section:**
+   - How 'notation' vs 'audio' type is determined
+   - File extension to type mapping logic
+
+5. **Integration Points Section:**
+   - How AttachmentStore connects to ChatStore
+   - Event emission patterns (trigger)
+   - How UI components consume attachment state
+
+Include actual CoffeeScript code snippets translated to JavaScript for clarity.
+  </action>
+  <verify>
+File exists and contains:
+- grep "Upload Flow" ATTACHMENT_LEGACY.md
+- grep "FormData" ATTACHMENT_LEGACY.md
+- grep "10.*MB" ATTACHMENT_LEGACY.md
+- grep -c "```" ATTACHMENT_LEGACY.md shows 5+ code blocks
+  </verify>
+  <done>
+ATTACHMENT_LEGACY.md exists with 150+ lines covering all five sections, including translated code examples.
+  </done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Document Backend API Contract</name>
+  <files>.planning/phases/12-attachment-research-&-backend-validation/docs/ATTACHMENT_API.md</files>
+  <action>
+Create comprehensive API documentation for the attachment endpoints:
+
+1. **Endpoint Overview Table:**
+   - POST /api/music_notations (upload)
+   - GET /api/music_notations/:id (signed URL)
+   - DELETE /api/music_notations/:id (remove)
+   - Include HTTP methods, auth requirements, response codes
+
+2. **POST /api/music_notations - Upload:**
+   - Request format: multipart/form-data
+   - Required fields: files[], session_id, attachment_type
+   - Optional fields: any additional params
+   - Response 201: JSON array of created attachments [{id, file_name, file_url}]
+   - Response 413: File too large
+   - Response 422: Validation errors
+   - Include curl example command
+
+3. **GET /api/music_notations/:id - Download URL:**
+   - Request: Just the ID in path
+   - Response 200: JSON with signed S3 URL
+   - URL expiration time (from CarrierWave config)
+   - Include curl example
+
+4. **DELETE /api/music_notations/:id - Remove:**
+   - Request: ID in path
+   - Response 204: Success (no content)
+   - Response 403: Not authorized
+   - Response 404: Not found
+
+5. **File Validation Rules:**
+   - Server-side extension whitelist (from MusicNotationUploader)
+   - Size limits (server-side vs client-side)
+   - Content-type handling
+
+6. **Chat Message Integration:**
+   - How upload automatically creates ChatMessage
+   - ChatMessage fields populated (purpose, attachment_id, attachment_type, attachment_name)
+   - WebSocket broadcast triggered after upload
+
+Include actual code references from api_music_notations_controller.rb.
+  </action>
+  <verify>
+File exists and contains:
+- grep "POST /api/music_notations" ATTACHMENT_API.md
+- grep "GET /api/music_notations" ATTACHMENT_API.md
+- grep "DELETE /api/music_notations" ATTACHMENT_API.md
+- grep "curl" ATTACHMENT_API.md
+- grep "ChatMessage" ATTACHMENT_API.md
+  </verify>
+  <done>
+ATTACHMENT_API.md exists with 200+ lines covering all six sections, including curl examples and code references.
+  </done>
+</task>
+
+</tasks>
+
+<verification>
+Both documentation files created in docs/ subdirectory:
+- ls .planning/phases/12-attachment-research-&-backend-validation/docs/
+Should show: ATTACHMENT_LEGACY.md, ATTACHMENT_API.md
+
+Content verification:
+- wc -l docs/*.md shows 150+ lines for LEGACY, 200+ lines for API
+- Both files contain working code examples
+- API documentation includes all three endpoints
+</verification>
+
+<success_criteria>
+1. ATTACHMENT_LEGACY.md documents complete upload flow from legacy CoffeeScript
+2. ATTACHMENT_API.md documents all three endpoints with request/response formats
+3. File validation rules (types, sizes) are clearly specified in both documents
+4. Code examples are included and accurate
+5. Documentation is sufficient for implementing React port without referencing legacy code directly
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/12-attachment-research-&-backend-validation/12-01-SUMMARY.md`
+</output>

.planning/phases/12-attachment-research-&-backend-validation/12-02-PLAN.md

@@ -0,0 +1,219 @@
+---
+phase: 12-attachment-research-&-backend-validation
+plan: 02
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - .planning/phases/12-attachment-research-&-backend-validation/docs/BACKEND_VALIDATION.md
+  - .planning/phases/12-attachment-research-&-backend-validation/docs/REACT_INTEGRATION_DESIGN.md
+autonomous: true
+
+must_haves:
+  truths:
+    - "MusicNotation model S3 integration is validated (CarrierWave, signed URLs)"
+    - "WebSocket attachment metadata fields are documented (attachment_id, attachment_type, attachment_name)"
+    - "React integration points are identified with specific file paths and modifications"
+  artifacts:
+    - path: ".planning/phases/12-attachment-research-&-backend-validation/docs/BACKEND_VALIDATION.md"
+      provides: "Backend infrastructure validation report"
+      min_lines: 150
+    - path: ".planning/phases/12-attachment-research-&-backend-validation/docs/REACT_INTEGRATION_DESIGN.md"
+      provides: "React integration strategy and component design"
+      min_lines: 200
+  key_links:
+    - from: "REACT_INTEGRATION_DESIGN.md"
+      to: "sessionChatSlice.js"
+      via: "Redux state extensions"
+      pattern: "upload.*state"
+    - from: "REACT_INTEGRATION_DESIGN.md"
+      to: "JKChatComposer.js"
+      via: "Attach button integration"
+      pattern: "attach.*button"
+---
+
+<objective>
+Validate backend infrastructure capabilities and design the React integration strategy for attachments.
+
+Purpose: Confirm zero backend changes are needed and create a concrete integration plan that maps exactly how attachment functionality will be added to existing jam-ui components.
+
+Output: Two documentation files (BACKEND_VALIDATION.md, REACT_INTEGRATION_DESIGN.md) that validate infrastructure readiness and provide implementation blueprints.
+</objective>
+
+<execution_context>
+@/Users/nuwan/.claude/get-shit-done/workflows/execute-plan.md
+@/Users/nuwan/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/12-attachment-research-&-backend-validation/12-RESEARCH.md
+
+# Backend validation sources
+@ruby/lib/jam_ruby/models/music_notation.rb
+@ruby/lib/jam_ruby/models/chat_message.rb
+@ruby/lib/jam_ruby/uploaders/music_notation_uploader.rb
+@ruby/lib/jam_ruby/message_factory.rb
+
+# React integration targets
+@jam-ui/src/components/client/chat/JKChatComposer.js
+@jam-ui/src/components/client/chat/JKChatMessage.js
+@jam-ui/src/components/client/JKSessionScreen.js
+@jam-ui/src/store/features/sessionChatSlice.js
+@jam-ui/src/services/rest.js
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Validate Backend Infrastructure</name>
+  <files>.planning/phases/12-attachment-research-&-backend-validation/docs/BACKEND_VALIDATION.md</files>
+  <action>
+Create a validation report confirming backend readiness:
+
+1. **MusicNotation Model Validation:**
+   - Confirm CarrierWave mount_uploader configuration
+   - Verify S3 storage configuration (fog_credentials pattern)
+   - Document signed URL generation method
+   - Confirm file_name and file attributes exist
+   - Include actual code snippets from music_notation.rb
+
+2. **MusicNotationUploader Validation:**
+   - Document extension_white_list (exact list)
+   - Confirm store_dir configuration
+   - Note any size limits at uploader level
+   - Compare against requirements whitelist:
+     Requirements: .pdf, .xml, .mxl, .txt, .png, .jpg, .jpeg, .gif, .mp3, .wav
+     Backend: pdf png jpg jpeg gif xml mxl txt wav flac ogg aiff aifc au
+   - FLAG MISMATCH: .mp3 in requirements but NOT in backend
+   - Recommendation: Backend update needed OR requirements clarification
+
+3. **ChatMessage Attachment Integration:**
+   - Confirm attachment_id, attachment_type, attachment_name fields exist
+   - Document how ChatMessage is created after MusicNotation upload
+   - Verify send_chat_msg includes attachment fields in WebSocket broadcast
+   - Include code snippet from chat_message.rb showing field usage
+
+4. **WebSocket Message Structure:**
+   - Document chat_message Protocol Buffer fields for attachments
+   - Show exact field names: purpose, attachment_id, attachment_type, attachment_name
+   - Confirm these are populated in message_factory.rb
+   - Include the chat_message method signature and attachment params
+
+5. **Validation Summary:**
+   - Checklist of all validated capabilities
+   - List of any gaps or issues found
+   - Recommendation: "Zero backend changes needed" OR list required changes
+  </action>
+  <verify>
+File exists and contains:
+- grep "CarrierWave" BACKEND_VALIDATION.md
+- grep "extension_white_list" BACKEND_VALIDATION.md
+- grep "attachment_id" BACKEND_VALIDATION.md
+- grep "WebSocket" BACKEND_VALIDATION.md
+- grep -i "validation summary" BACKEND_VALIDATION.md
+  </verify>
+  <done>
+BACKEND_VALIDATION.md exists with 150+ lines, confirms backend infrastructure status, and clearly states whether backend changes are needed.
+  </done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Design React Integration Strategy</name>
+  <files>.planning/phases/12-attachment-research-&-backend-validation/docs/REACT_INTEGRATION_DESIGN.md</files>
+  <action>
+Create detailed integration design for React implementation:
+
+1. **Component Modifications Overview Table:**
+   | Component | Current State | Modifications Needed | Phase |
+   | JKChatComposer.js | Text + Send | Add attach button | 13 |
+   | JKChatMessage.js | Text display | Handle attachment messages | 14 |
+   | JKSessionScreen.js | WebSocket handler | Add attachment fields | 14-15 |
+   | sessionChatSlice.js | Chat state | Add upload state | 13 |
+   | rest.js | API helpers | Add upload function | 13 |
+
+2. **New Component: JKChatAttachButton**
+   - Purpose: Hidden file input + visible button trigger
+   - Props: onFileSelect(file), disabled, isUploading
+   - File input accept attribute value (from requirements)
+   - Reset input value after selection (allow re-selecting same file)
+   - Include component skeleton code
+
+3. **Redux State Extensions (sessionChatSlice.js):**
+   - New state: uploadState { status: 'idle'|'uploading'|'error', progress: number, error: string|null }
+   - New reducer: setUploadStatus(status, progress, error)
+   - New reducer: clearUploadError()
+   - New async thunk: uploadAttachment(file, sessionId)
+   - Include state shape and reducer signatures
+
+4. **REST Helper Addition (rest.js):**
+   - uploadMusicNotation(formData): Uses native fetch, NOT apiFetch (FormData needs browser headers)
+   - getMusicNotationUrl(id): Uses apiFetch for signed URL
+   - Include function signatures with JSDoc comments
+
+5. **WebSocket Handler Updates (JKSessionScreen.js):**
+   - Current handleChatMessage transformation
+   - Additional fields to extract: purpose, attachment_id, attachment_type, attachment_name
+   - Updated message object shape
+   - Include code diff showing additions
+
+6. **JKChatMessage Attachment Display:**
+   - Condition: message.attachmentId exists
+   - Render: "[UserName] attached: [FileName]" with link
+   - Click handler: Fetch signed URL, open in new tab
+   - Include component modification sketch
+
+7. **File Validation Service:**
+   - New file: services/attachmentValidation.js (optional - could be inline)
+   - validateFileSize(file, maxSizeBytes): returns { valid, error }
+   - validateFileType(file, allowedTypes): returns { valid, error }
+   - getAttachmentType(filename): returns 'notation' | 'audio'
+   - Include function implementations
+
+8. **Implementation Sequence:**
+   - Phase 13: Attach button, validation, upload, progress (REQ-1.*, REQ-6.*, REQ-7.1)
+   - Phase 14: Message display, download links, history (REQ-2.*, REQ-4.*, REQ-7.2-3)
+   - Phase 15: WebSocket sync, deduplication (REQ-3.*)
+   - Phase 16: Error handling, edge cases, UAT (REQ-5.*)
+  </action>
+  <verify>
+File exists and contains:
+- grep "JKChatAttachButton" REACT_INTEGRATION_DESIGN.md
+- grep "sessionChatSlice" REACT_INTEGRATION_DESIGN.md
+- grep "uploadMusicNotation" REACT_INTEGRATION_DESIGN.md
+- grep "handleChatMessage" REACT_INTEGRATION_DESIGN.md
+- grep "Phase 13" REACT_INTEGRATION_DESIGN.md
+  </verify>
+  <done>
+REACT_INTEGRATION_DESIGN.md exists with 200+ lines, provides concrete component designs, Redux state shape, and clear implementation sequence for Phases 13-16.
+  </done>
+</task>
+
+</tasks>
+
+<verification>
+Both documentation files created in docs/ subdirectory:
+- ls .planning/phases/12-attachment-research-&-backend-validation/docs/
+Should show: BACKEND_VALIDATION.md, REACT_INTEGRATION_DESIGN.md (plus files from Plan 01)
+
+Content verification:
+- wc -l docs/*.md shows 150+ lines for VALIDATION, 200+ lines for DESIGN
+- Backend validation includes clear "changes needed" or "no changes needed" statement
+- React design includes code examples for all integration points
+</verification>
+
+<success_criteria>
+1. BACKEND_VALIDATION.md confirms MusicNotation model works with S3 (CarrierWave validated)
+2. BACKEND_VALIDATION.md documents WebSocket attachment metadata fields
+3. BACKEND_VALIDATION.md clearly states backend change requirements (if any)
+4. REACT_INTEGRATION_DESIGN.md identifies all 5 integration points with file paths
+5. REACT_INTEGRATION_DESIGN.md includes component/Redux code sketches
+6. REACT_INTEGRATION_DESIGN.md maps requirements to implementation phases
+7. Documentation is sufficient to begin Phase 13 implementation without additional research
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/12-attachment-research-&-backend-validation/12-02-SUMMARY.md`
+</output>