---
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>
