From 4d69253a94b4bcd9676f73ec9be0f9668114fd6a Mon Sep 17 00:00:00 2001 From: Chandler Copeland Date: Fri, 3 Apr 2026 14:59:31 -0600 Subject: [PATCH] docs: create milestone v1.2 roadmap (4 phases) --- .planning/REQUIREMENTS.md | 28 ++++++++++--- .planning/ROADMAP.md | 82 +++++++++++++++++++++++++++++++++++---- .planning/STATE.md | 62 +++++++++++++++++++++-------- 3 files changed, 141 insertions(+), 31 deletions(-) diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 59c5317..238e83f 100644 --- a/.planning/REQUIREMENTS.md +++ b/.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)* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index eb51368..4c7f625 100644 --- a/.planning/ROADMAP.md +++ b/.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 | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index 72fab58..4701539 100644 --- a/.planning/STATE.md +++ b/.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