docs(11-agent-saved-signature-and-signing-workflow): create phase plan

.planning/phases/11-agent-saved-signature-and-signing-workflow/11-03-PLAN.md

@@ -0,0 +1,124 @@
+---
+phase: 11-agent-saved-signature-and-signing-workflow
+plan: "03"
+type: execute
+wave: 3
+depends_on:
+  - "11-01"
+  - "11-02"
+files_modified: []
+autonomous: false
+requirements:
+  - AGENT-01
+  - AGENT-02
+  - AGENT-03
+  - AGENT-04
+
+must_haves:
+  truths:
+    - "Agent can draw, save, and see a thumbnail of their signature from /portal/profile"
+    - "Agent can update (replace) their saved signature"
+    - "Agent can place an Agent Signature token on a PDF document in the FieldPlacer"
+    - "Preparing a document with agent-signature fields embeds the saved PNG in the correct position in the prepared PDF"
+    - "Opening the client signing link for the prepared document does NOT show any agent-signature overlay"
+  artifacts:
+    - path: "teressa-copeland-homes/src/app/portal/(protected)/profile/page.tsx"
+      provides: "Accessible profile page with draw/save/thumbnail signature flow"
+    - path: "teressa-copeland-homes/src/lib/pdf/prepare-document.ts"
+      provides: "preparePdf with agent PNG embedding at agent-sig field coordinates"
+  key_links:
+    - from: "Agent saves signature at /portal/profile"
+      to: "Prepared PDF"
+      via: "PUT /api/agent/signature → users.agentSignatureData → preparePdf() → pdfDoc.embedPng + drawImage"
+      pattern: "full pipeline"
+---
+
+<objective>
+Human verification of the complete Phase 11 agent signature workflow: draw once at profile, place fields on a document, prepare the document, verify the signature is embedded in the correct position in the PDF, and confirm the client signing session is unaffected.
+
+Purpose: All four AGENT requirements are verified end-to-end by a human using the portal.
+Output: Phase 11 marked complete; AGENT-01 through AGENT-04 confirmed working.
+</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/STATE.md
+@.planning/phases/11-agent-saved-signature-and-signing-workflow/11-01-SUMMARY.md
+@.planning/phases/11-agent-saved-signature-and-signing-workflow/11-02-SUMMARY.md
+</context>
+
+<tasks>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <name>Task 1: Human verification — full Phase 11 agent signature end-to-end</name>
+  <action>Run the dev server and execute the 5-step verification below. There are no code changes in this plan — all code was delivered in Plans 01 and 02.</action>
+  <what-built>
+    Complete Phase 11 agent signature workflow:
+    - /portal/profile page with signature draw canvas and thumbnail
+    - "Agent Signature" token in FieldPlacer palette (red, draggable)
+    - preparePdf() embeds saved PNG at agent-signature field coordinates
+    - Prepare route fetches agentSignatureData and passes 422 guard
+    - Client signing session filters out agent-signature fields (unchanged from Phase 8)
+  </what-built>
+  <how-to-verify>
+    Start the dev server: `cd /Users/ccopeland/temp/red/teressa-copeland-homes && npm run dev`
+
+    **Step 1 — Save your signature (AGENT-01):**
+    - Visit http://localhost:3000/portal/profile
+    - Confirm "Profile" appears in the portal nav
+    - Draw a distinctive signature on the canvas
+    - Click "Save Signature"
+    - Expected: Canvas is replaced by a thumbnail image of your signature
+
+    **Step 2 — Update signature (AGENT-02):**
+    - Click "Update Signature" on the profile page
+    - Draw a slightly different signature
+    - Click "Save Updated Signature"
+    - Expected: New thumbnail replaces the old one
+
+    **Step 3 — Place agent-signature field (AGENT-03):**
+    - Open any document in the portal and go to the prepare tab
+    - Confirm the FieldPlacer palette shows a red "Agent Signature" token
+    - Drag the "Agent Signature" token and drop it onto the document (any page, any position)
+    - Expected: A red field box appears on the PDF where you dropped it
+
+    **Step 4 — Prepare with embedded signature (AGENT-04):**
+    - Assign the document to a client, fill any required text fields
+    - Click Prepare
+    - Expected: Prepare succeeds (no error, document status changes)
+    - Download the prepared PDF from the portal
+    - Open the downloaded PDF and navigate to the page where you placed the agent-signature field
+    - Expected: Your saved signature image appears at that position in the PDF
+
+    **Step 5 — Client signing session is unaffected:**
+    - Send the prepared document to a client (or use a test signing link)
+    - Open the signing link in the browser
+    - Expected: The client signing page does NOT show any overlay or prompt for the agent-signature position
+    - Expected: Client-signature and initials overlays (if placed) still appear normally for the client
+  </how-to-verify>
+  <resume-signal>Type "approved" if all 5 steps pass. Describe any issues found if not.</resume-signal>
+  <verify>All 5 steps pass and human types "approved"</verify>
+  <done>Full end-to-end round-trip confirmed: agent draws, saves, places field, prepares, and embedded signature appears in prepared PDF; client signing session is unaffected</done>
+</task>
+
+</tasks>
+
+<verification>
+Human verification approved — all four AGENT requirements confirmed by live testing:
+- AGENT-01: Agent drew and saved signature; thumbnail visible at /portal/profile
+- AGENT-02: "Update Signature" replaced saved signature with a new one
+- AGENT-03: Red "Agent Signature" token visible and usable in FieldPlacer palette
+- AGENT-04: Prepared PDF contains agent signature PNG at the placed field coordinates; client signing session shows no agent-signature overlay
+</verification>
+
+<success_criteria>
+Human approves all 5 verification steps. Phase 11 is complete and all AGENT requirements are satisfied.
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/11-agent-saved-signature-and-signing-workflow/11-03-SUMMARY.md`
+</output>