red/.planning/phases/05-pdf-fill-and-field-mapping/05-04-PLAN.md

phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, must_haves

phase	plan	type	wave	depends_on	files_modified	autonomous	requirements	must_haves
05-pdf-fill-and-field-mapping	04	execute	3	05-02 05-03		false	DOC-04 DOC-05 DOC-06	truths artifacts key_links Agent can drag and drop a Signature Field token onto a PDF page and the blue rectangle appears at the correct location Placed signature fields persist across page reload Agent can remove a placed signature field using the × button Agent can fill in text fields (label + value pairs) in the Prepare Document panel Agent can select a client from the dropdown and click Prepare and Send After Prepare and Send, document status shows Sent in both the document page and the dashboard The prepared PDF file exists at uploads/clients/{clientId}/{docId}_prepared.pdf and contains the blue signature rectangle path provides teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/FieldPlacer.tsx Drag-and-drop field placement UI path provides teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/PreparePanel.tsx Text fill + client assign + Prepare and Send workflow path provides teressa-copeland-homes/uploads/clients/ Prepared PDF files on disk ({docId}_prepared.pdf) from to via human tester PDF signature field overlay drag-and-drop interaction in browser from to via human tester uploads/ directory ls command to verify prepared PDF file exists

Human verification checkpoint for Phase 5. Agent (Teressa) tests the complete field mapping and document preparation workflow in the browser: dragging signature fields, filling text fields, assigning a client, and triggering document preparation.

Purpose: Confirm all three Phase 5 requirements (DOC-04, DOC-05, DOC-06) are met end-to-end before Phase 6 begins.

Output: Human sign-off or specific issues to address.

<execution_context> @/Users/ccopeland/.claude/get-shit-done/workflows/execute-plan.md @/Users/ccopeland/.claude/get-shit-done/templates/summary.md </execution_context>

@.planning/ROADMAP.md @.planning/phases/05-pdf-fill-and-field-mapping/05-02-SUMMARY.md @.planning/phases/05-pdf-fill-and-field-mapping/05-03-SUMMARY.md Complete Phase 5 PDF fill and field mapping workflow: - Drag-and-drop signature field placement on any PDF page (DOC-04) - Text fill form with key-value pairs for AcroForm fields (DOC-05) - Client assignment and Prepare and Send action that writes a prepared PDF and transitions status to Sent (DOC-06) Run the app if not already running: ``` cd teressa-copeland-homes && npm run dev ```

Perform these verification steps in order:

1. Open any document detail page (navigate to a client profile, click a document name)
   Expected: Document page has two columns — PDF viewer on the left, "Prepare Document" panel on the right

2. Drag-and-drop test — drag the "Signature Field" token from the palette onto the PDF page
   Expected: A blue-bordered semi-transparent rectangle appears where you dropped it

3. Reload the page
   Expected: The blue signature field rectangle is still visible (persisted to DB)

4. Click the × button on the placed signature field
   Expected: The rectangle disappears from the overlay and from the DB (reload to confirm)

5. Place at least one signature field — drag a new one onto the document

6. In the "Prepare Document" panel on the right:
   - Select a client from the dropdown
   - Add one text fill row: label = "test" (or any AcroForm field name from the PDF), value = "Test Value"
   - Click "Prepare and Send"
   Expected: Loading state ("Preparing..."), then success message ("Document prepared successfully...")

7. After success, check the document status
   Expected: Status shows "Sent" on the document page (the heading area) and on the portal dashboard

8. Verify the prepared PDF was created on disk:
   ```
   ls uploads/clients/
   ```
   Expected: A file named `{docId}_prepared.pdf` exists in uploads/clients/{clientId}/

9. Verify the prepared PDF is readable — open it with a PDF viewer:
   ```
   open uploads/clients/{clientId}/{docId}_prepared.pdf
   ```
   Expected: PDF opens and shows a blue rectangle with "Sign Here" label at the position where you placed the field

10. Verify a document that is already "Sent" shows the locked message in PreparePanel
    (Navigate to the document you just prepared)
    Expected: "Document status is Sent — preparation is only available for Draft documents."

Type "approved" if all 10 steps pass, or describe which step(s) failed and what you observed. Human tester confirms all 10 verification steps pass.

<success_criteria> All 10 verification steps pass as confirmed by human tester. Phase 5 declared complete.

Requirements covered:

• DOC-04: Drag-and-drop signature field placement — confirmed in steps 2-5
• DOC-05: Text fill fields — confirmed in step 6
• DOC-06: Assign to client + initiate signing request (status → Sent) — confirmed in steps 6-8 </success_criteria>

After completion, create `.planning/phases/05-pdf-fill-and-field-mapping/05-04-SUMMARY.md`