docs(05-pdf-fill-and-field-mapping): create phase plan

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

@@ -0,0 +1,131 @@
+---
+phase: 05-pdf-fill-and-field-mapping
+plan: 04
+type: execute
+wave: 3
+depends_on: [05-02, 05-03]
+files_modified: []
+autonomous: false
+requirements: [DOC-04, DOC-05, DOC-06]
+
+must_haves:
+  truths:
+    - "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"
+  artifacts:
+    - path: "teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/FieldPlacer.tsx"
+      provides: "Drag-and-drop field placement UI"
+    - path: "teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/PreparePanel.tsx"
+      provides: "Text fill + client assign + Prepare and Send workflow"
+    - path: "teressa-copeland-homes/uploads/clients/"
+      provides: "Prepared PDF files on disk ({docId}_prepared.pdf)"
+  key_links:
+    - from: "human tester"
+      to: "PDF signature field overlay"
+      via: "drag-and-drop interaction in browser"
+    - from: "human tester"
+      to: "uploads/ directory"
+      via: "ls command to verify prepared PDF file exists"
+---
+
+<objective>
+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.
+</objective>
+
+<execution_context>
+@/Users/ccopeland/.claude/get-shit-done/workflows/execute-plan.md
+@/Users/ccopeland/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<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
+</context>
+
+<tasks>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>
+    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)
+  </what-built>
+  <how-to-verify>
+    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."
+  </how-to-verify>
+  <resume-signal>Type "approved" if all 10 steps pass, or describe which step(s) failed and what you observed.</resume-signal>
+</task>
+
+</tasks>
+
+<verification>
+Human tester confirms all 10 verification steps pass.
+</verification>
+
+<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>
+
+<output>
+After completion, create `.planning/phases/05-pdf-fill-and-field-mapping/05-04-SUMMARY.md`
+</output>