docs: create milestone v1.2 roadmap (4 phases)

.planning/REQUIREMENTS.md

@@ -222,16 +222,32 @@ Which phases cover which requirements. Updated during roadmap creation.
 | TXTF-01 | Phase 12.1 | Complete |
 | TXTF-02 | Phase 12.1 | Complete |
 | TXTF-03 | Phase 12.1 | Complete |
-| AI-01 | Phase 13 | Complete |
-| AI-02 | Phase 13 | Complete |
+| AI-01 | Phase 13 | In Progress |
+| AI-02 | Phase 13 | In Progress |
+| MSIGN-08 | Phase 14 | Pending |
+| MSIGN-05 | Phase 15 | Pending |
+| MSIGN-06 | Phase 15 | Pending |
+| MSIGN-07 | Phase 15 | Pending |
+| MSIGN-10 | Phase 15 | Pending |
+| MSIGN-11 | Phase 15 | Pending |
+| MSIGN-01 | Phase 16 | Pending |
+| MSIGN-02 | Phase 16 | Pending |
+| MSIGN-03 | Phase 16 | Pending |
+| MSIGN-04 | Phase 16 | Pending |
+| MSIGN-09 | Phase 16 | Pending |
+| DEPLOY-01 | Phase 17 | Pending |
+| DEPLOY-02 | Phase 17 | Pending |
+| DEPLOY-03 | Phase 17 | Pending |
+| DEPLOY-04 | Phase 17 | Pending |
+| DEPLOY-05 | Phase 17 | Pending |
 
 **Coverage:**
 - v1.0 requirements: 28 total — mapped to phases 1-7 — all Complete
-- v1.1 requirements: 17 total — mapped to phases 8-13 — 13 Complete, 4 Pending (INIT-01 through INIT-04)
-- v1.2 requirements: 16 total — mapped to phases 14+ — all Pending
+- v1.1 requirements: 17 total — mapped to phases 8-13 — 15 Complete, 2 In Progress (AI-01, AI-02)
+- v1.2 requirements: 16 total — mapped to phases 14-17 — all Pending
 - Total mapped: 61
-- Unmapped: 16 (v1.2 — roadmap pending)
+- Unmapped: 0
 
 ---
 *Requirements defined: 2026-03-19*
-*Last updated: 2026-04-03 — v1.2 requirements added (MSIGN-01–11, DEPLOY-01–05)*
+*Last updated: 2026-04-03 — v1.2 traceability added (MSIGN-01–11 → Phases 14–16, DEPLOY-01–05 → Phase 17)*

.planning/ROADMAP.md

@@ -6,10 +6,13 @@ A dual-product build: a public real estate marketing site for a solo Utah agent
 
 v1.1 extends the platform with AI-assisted field placement, expanded field types (text, checkbox, initials, date, agent signature), agent saved signature with draw-once-reuse workflow, and a filled document preview before sending.
 
+v1.2 extends the platform to multiple signers in parallel and ships a production-ready Docker Compose deployment with correct SMTP and secret injection.
+
 ## Milestones
 
 - ✅ **v1.0 Core Document Signing Platform** - Phases 1-7 (shipped 2026-03-21)
 - 🚧 **v1.1 Smart Document Preparation** - Phases 8-13 (in progress)
+- 📋 **v1.2 Multi-Signer and Deployment Hardening** - Phases 14-17 (planned)
 
 ## Phases
 
@@ -167,6 +170,15 @@ Plans:
 - [x] **Phase 12.1: Per-Field Text Editing and Quick-Fill (INSERTED)** - Agent clicks a text field box to edit its value inline; PreparePanel shows quick-fill suggestions (client name, address, etc.) when a field is selected; text fill data is keyed by field ID (completed 2026-03-21)
 - [ ] **Phase 13: AI Field Placement and Pre-fill** - One-click AI auto-placement of all field types plus pre-fill of text fields from client profile data
 
+### 📋 v1.2 Multi-Signer and Deployment Hardening (Planned)
+
+**Milestone Goal:** A single document can be sent to multiple signers in parallel, each receiving their own link and seeing only their own fields, with automatic completion notifications — plus a production-ready Docker Compose setup that correctly passes secrets so email works reliably.
+
+- [ ] **Phase 14: Multi-Signer Schema** - Additive DB migration enabling multi-signer field routing, per-signer token identity, and race-safe completion detection
+- [ ] **Phase 15: Multi-Signer Backend** - Token creation loop, signer-aware signing flow, atomic completion detection, parallel email dispatch and final PDF delivery
+- [ ] **Phase 16: Multi-Signer UI** - PreparePanel signer list, FieldPlacer signer assignment and color-coding, send-block validation, per-signer dashboard status
+- [ ] **Phase 17: Docker Deployment** - Three-stage Dockerfile, docker-compose.yml with named uploads volume and env_file secrets, health endpoint, SMTP fix
+
 ## Phase Details
 
 ### Phase 8: Schema Foundation and Signing Page Safety
@@ -295,10 +307,60 @@ Plans:
 - [ ] 13-03-PLAN.md — UI wiring: aiPlacementKey prop in FieldPlacer + PdfViewerWrapper thread-through; "AI Auto-place Fields" button (violet) in PreparePanel; DocumentPageClient handleAiAutoPlace with textFillData merge and preview reset
 - [ ] 13-04-PLAN.md — Integration test with full 20-page Utah REPC + full Phase 13 human verification checkpoint
 
+### Phase 14: Multi-Signer Schema
+**Goal**: The database schema is ready for multi-signer documents — signers are first-class records on documents, tokens carry signer identity, and the completion guard column prevents race conditions — with zero breakage to existing single-signer documents
+**Depends on**: Phase 13
+**Requirements**: MSIGN-08
+**Success Criteria** (what must be TRUE):
+  1. Drizzle migration applies cleanly to the production Neon database with no data loss on existing documents or signing tokens
+  2. Existing single-signer documents continue to prepare, send, and sign exactly as before — the new nullable columns are invisible to the legacy code paths
+  3. `SignatureFieldData` TypeScript interface has an optional `signerEmail` field; `signingTokens` table has a nullable `signerEmail` TEXT column; `documents` table has `signers` JSONB and `completionTriggeredAt` TIMESTAMP columns
+  4. The `completionTriggeredAt` guard column is present and its purpose is verified: an `UPDATE ... WHERE completionTriggeredAt IS NULL RETURNING` query atomically claims it exactly once per document
+**Plans**: TBD
+**UI hint**: no
+
+### Phase 15: Multi-Signer Backend
+**Goal**: The server correctly creates one signing token per signer, filters each signer's signing page to their own fields, and detects completion atomically — all signers receive their links at once, and when the last signer signs all parties get the final PDF
+**Depends on**: Phase 14
+**Requirements**: MSIGN-05, MSIGN-06, MSIGN-07, MSIGN-10, MSIGN-11
+**Success Criteria** (what must be TRUE):
+  1. When the agent sends a two-signer document, both signers receive their unique signing links in a single send operation (parallel email dispatch, no sequential dependency)
+  2. Each signer's GET /api/sign/[token] response contains only the fields tagged to that signer's email — fields belonging to other signers are absent from the response
+  3. The POST /api/sign/[token] handler rejects any field submission where the field's signerEmail does not match the token's signerEmail (server-enforced ownership)
+  4. When the last signer submits, `completionTriggeredAt` is claimed atomically — only one handler triggers final PDF assembly regardless of concurrent submissions
+  5. Agent receives a notification email and all signers receive the final merged PDF link when all signing tokens for the document are claimed
+**Plans**: TBD
+**UI hint**: no
+
+### Phase 16: Multi-Signer UI
+**Goal**: Agent can name and add multiple signers from PreparePanel, assign each field to a specific signer in FieldPlacer with color-coded visual distinction, and cannot accidentally send a document with unassigned client-facing fields
+**Depends on**: Phase 15
+**Requirements**: MSIGN-01, MSIGN-02, MSIGN-03, MSIGN-04, MSIGN-09
+**Success Criteria** (what must be TRUE):
+  1. Agent can add two or more signer email addresses in PreparePanel before sending — signers are saved to the document record and the list is editable until send
+  2. Each field placed in FieldPlacer has a signer assignment dropdown; selecting a signer changes the field's color to that signer's assigned color
+  3. If the agent clicks Send with any client-facing field (signature, initials, date, text) having no signer assigned, the send is blocked and a clear error message identifies the unassigned fields
+  4. The dashboard document detail view shows a per-signer completion row for each signer (who has signed, who hasn't, with timestamps)
+**Plans**: TBD
+**UI hint**: yes
+
+### Phase 17: Docker Deployment
+**Goal**: The application runs reliably in a Docker container on the production server — secrets are injected at runtime, email delivers correctly, uploaded files survive container restarts, and a health check confirms database connectivity
+**Depends on**: Phase 16
+**Requirements**: DEPLOY-01, DEPLOY-02, DEPLOY-03, DEPLOY-04, DEPLOY-05
+**Success Criteria** (what must be TRUE):
+  1. `docker compose up` starts the application and `GET /api/health` returns 200 OK with a successful database ping
+  2. SMTP credentials are read from `.env.production` via `env_file:` in docker-compose.yml — a signing link email and a completion notification email both deliver successfully from the running container
+  3. The `APP_BASE_URL` variable (renamed from `NEXT_PUBLIC_BASE_URL`) is injected at container runtime — signing link URLs in emails contain the correct production domain, not localhost
+  4. Uploaded PDF files written inside the container persist after `docker compose down && docker compose up` (named Docker volume mounted at /app/uploads)
+  5. The Docker image uses `node:20-slim` (Debian-based) — `@napi-rs/canvas` native binary loads without errors at container startup
+**Plans**: TBD
+**UI hint**: no
+
 ## Progress
 
 **Execution Order:**
-Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11 → 11.1 → 12 → 13
+Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11 → 11.1 → 12 → 12.1 → 13 → 14 → 15 → 16 → 17
 
 | Phase | Milestone | Plans Complete | Status | Completed |
 |-------|-----------|----------------|--------|-----------|
@@ -309,11 +371,15 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 →
 | 5. PDF Fill and Field Mapping | v1.0 | 4/4 | Complete | 2026-03-21 |
 | 6. Signing Flow | v1.0 | 6/6 | Complete | 2026-03-21 |
 | 7. Audit Trail and Download | v1.0 | 3/3 | Complete | 2026-03-21 |
-| 8. Schema Foundation and Signing Page Safety | 2/2 | Complete   | 2026-03-21 | - |
-| 9. Client Property Address | 1/1 | Complete    | 2026-03-21 | - |
+| 8. Schema Foundation and Signing Page Safety | v1.1 | 2/2 | Complete | 2026-03-21 |
+| 9. Client Property Address | v1.1 | 1/1 | Complete | 2026-03-21 |
 | 10. Expanded Field Types End-to-End | v1.1 | 3/3 | Complete | 2026-03-21 |
-| 11. Agent Saved Signature and Signing Workflow | 3/3 | Complete    | 2026-03-21 | - |
-| 11.1. Agent and Client Initials (INSERTED) | 3/3 | Complete    | 2026-03-21 | - |
-| 12. Filled Document Preview | 2/2 | Complete    | 2026-03-21 | - |
-| 12.1. Per-Field Text Editing and Quick-Fill (INSERTED) | 2/2 | Complete    | 2026-03-21 | - |
-| 13. AI Field Placement and Pre-fill | 3/4 | In Progress|  | - |
+| 11. Agent Saved Signature and Signing Workflow | v1.1 | 3/3 | Complete | 2026-03-21 |
+| 11.1. Agent and Client Initials (INSERTED) | v1.1 | 3/3 | Complete | 2026-03-21 |
+| 12. Filled Document Preview | v1.1 | 2/2 | Complete | 2026-03-21 |
+| 12.1. Per-Field Text Editing and Quick-Fill (INSERTED) | v1.1 | 2/2 | Complete | 2026-03-21 |
+| 13. AI Field Placement and Pre-fill | v1.1 | 3/4 | In Progress | - |
+| 14. Multi-Signer Schema | v1.2 | 0/TBD | Not started | - |
+| 15. Multi-Signer Backend | v1.2 | 0/TBD | Not started | - |
+| 16. Multi-Signer UI | v1.2 | 0/TBD | Not started | - |
+| 17. Docker Deployment | v1.2 | 0/TBD | Not started | - |

.planning/STATE.md

@@ -1,14 +1,17 @@
 ---
 gsd_state_version: 1.0
-milestone: v1.2
-milestone_name: Multi-Signer and Deployment Hardening
-status: defining requirements
-last_updated: "2026-04-03"
+milestone: v1.1
+milestone_name: Smart Document Preparation
+status: executing
+stopped_at: Completed 13-ai-field-placement-and-pre-fill/13-03-PLAN.md — AI Auto-place button wired; Plan 03 of 4 done; ready for Plan 04 (E2E verification)
+last_updated: "2026-04-03T20:30:14.113Z"
+last_activity: 2026-04-03 -- v1.2 roadmap created (Phases 14-17 planned)
 progress:
-  total_phases: 0
-  completed_phases: 0
-  total_plans: 0
-  completed_plans: 0
+  total_phases: 8
+  completed_phases: 7
+  total_plans: 20
+  completed_plans: 19
+  percent: 100
 ---
 
 # Project State
@@ -21,25 +24,38 @@ See: .planning/PROJECT.md (updated 2026-04-03)
 
 ## Current Position
 
-Phase: Not started (defining requirements)
-Plan: —
-Status: Defining requirements
-Last activity: 2026-04-03 — Milestone v1.2 started
+Phase: 13 (ai-field-placement-and-pre-fill) — EXECUTING
+Plan: 1 of 4
+Status: Executing Phase 13 (v1.1 final phase); v1.2 roadmap created and ready
+Last activity: 2026-04-03 -- v1.2 roadmap created (Phases 14-17 planned)
 
 ## Note on v1.1
 
 v1.1 (Smart Document Preparation) is complete except Phase 13 Plan 04 (E2E verification checkpoint). All feature code is implemented. Run `/gsd:plan-phase 13` to execute that final verification plan if needed.
 
+## Note on v1.2
+
+v1.2 (Multi-Signer and Deployment Hardening) roadmap is defined. Four phases planned:
+- Phase 14: Multi-Signer Schema — additive DB migration, enables Phases 15+16
+- Phase 15: Multi-Signer Backend — token loop, signer-aware signing flow, atomic completion
+- Phase 16: Multi-Signer UI — PreparePanel signer list, FieldPlacer color-coding, send validation
+- Phase 17: Docker Deployment — three-stage Dockerfile, env_file secrets, health endpoint
+
+Start v1.2 after Phase 13 Plan 04 completes: `/gsd:plan-phase 14`
+
 ## Accumulated Context
 
 ### Roadmap Evolution
-- Phase 11.1 inserted after Phase 11: Agent and Client Initials (URGENT)
 
-Progress: [█████████████] 100% (13/13 phases complete)
+- Phase 11.1 inserted after Phase 11: Agent and Client Initials (URGENT)
+- v1.2 roadmap created 2026-04-03: Phases 14-17 (Multi-Signer + Docker Deployment)
+
+Progress: [█████████████] 100% (13/13 phases complete — v1.1 scope)
 
 ## Performance Metrics
 
 **Velocity:**
+
 - Total plans completed: 30 (v1.0 complete + Phase 8 complete)
 - Average duration: ~4 min/plan
 - Total execution time: ~2 hours
@@ -51,6 +67,7 @@ Progress: [█████████████] 100% (13/13 phases complete)
 | v1.0 phases 1-7 | 28 | ~4 min |
 
 **Recent Trend:**
+
 - Trend: Stable
 
 *Updated after each plan completion*
@@ -135,17 +152,28 @@ Recent decisions affecting v1.1 work:
 - [Phase 13-03]: textFillData is MERGED not replaced — preserves manually typed values while AI values take precedence
 - [Phase 13-03]: AI button uses violet bg-violet-600 to visually distinguish from gray Preview and blue Prepare-and-Send
 
+### v1.2 Pre-decisions (from research)
+
+- [v1.2 Research]: Schema-first approach — Phase 14 schema deploys before any multi-signer app code to avoid hard-to-unwind bugs
+- [v1.2 Research]: signerEmail on signingTokens is nullable (TEXT) — legacy tokens have no signer; backfill via JOIN to client email in migration
+- [v1.2 Research]: completionTriggeredAt guard column uses UPDATE WHERE IS NULL RETURNING pattern — same as existing token claim; zero rows returned means another handler won
+- [v1.2 Research]: Per-signer PDF accumulation via pg_advisory_xact_lock(hashtext(documentId)) — existing embedSignatureInPdf() unchanged
+- [v1.2 Research]: NEXT_PUBLIC_BASE_URL renamed to APP_BASE_URL before Docker image build — prevents localhost being baked into signing link URLs
+- [v1.2 Research]: node:20-slim (Debian) required for @napi-rs/canvas glibc compatibility — do NOT use Alpine (musl libc incompatible)
+- [v1.2 Research]: Neon connection pool set to max:5 — prevents connection exhaustion on free tier
+- [v1.2 Research]: @vercel/blob is a dead dependency — remove before Phase 17 to prevent accidental use in Docker deployment
+
 ### Pending Todos
 
 None yet.
 
 ### Blockers/Concerns
 
-- [Phase 12 - CARRY FORWARD]: Deployment target (Vercel serverless vs. self-hosted container) must be confirmed before production deploy — write-to-disk preview pattern silently fails on Vercel serverless (ephemeral filesystem)
+- [Phase 12 - CARRY FORWARD]: Deployment target confirmed as Docker (Phase 17 addresses this) — write-to-disk preview pattern is valid for self-hosted container
 - [Phase 13]: AI coordinate accuracy on real Utah forms is untested — integration test with full 20-page Utah REPC required before Phase 13 ships
 
 ## Session Continuity
 
-Last session: 2026-03-21
-Stopped at: Completed 13-ai-field-placement-and-pre-fill/13-03-PLAN.md — AI Auto-place button wired; Plan 03 of 4 done; ready for Plan 04 (E2E verification)
+Last session: 2026-04-03
+Stopped at: v1.2 roadmap created — Phases 14-17 defined; ready to complete Phase 13 Plan 04 then begin Phase 14
 Resume file: None