From caf9acf0c2458b3e6177a61da931fc317b2660e9 Mon Sep 17 00:00:00 2001 From: Chandler Copeland Date: Mon, 6 Apr 2026 12:05:21 -0600 Subject: [PATCH] docs: create milestone v1.3 roadmap (3 phases, 16 requirements) --- .planning/REQUIREMENTS.md | 21 ++++++++++++-- .planning/ROADMAP.md | 58 +++++++++++++++++++++++++++++++++++---- .planning/STATE.md | 45 ++++++++++++++++++++++-------- 3 files changed, 106 insertions(+), 18 deletions(-) diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index c16e94a..7ede89f 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -270,14 +270,31 @@ Which phases cover which requirements. Updated during roadmap creation. | DEPLOY-03 | Phase 17 | Complete | | DEPLOY-04 | Phase 17 | Complete | | DEPLOY-05 | Phase 17 | Complete | +| TMPL-01 | Phase 18 | Pending | +| TMPL-02 | Phase 18 | Pending | +| TMPL-03 | Phase 18 | Pending | +| TMPL-04 | Phase 18 | Pending | +| TMPL-05 | Phase 19 | Pending | +| TMPL-06 | Phase 19 | Pending | +| TMPL-07 | Phase 19 | Pending | +| TMPL-08 | Phase 19 | Pending | +| TMPL-09 | Phase 19 | Pending | +| TMPL-10 | Phase 20 | Pending | +| TMPL-11 | Phase 20 | Pending | +| TMPL-12 | Phase 20 | Pending | +| TMPL-13 | Phase 20 | Pending | +| TMPL-14 | Phase 20 | Pending | +| TMPL-15 | Phase 20 | Pending | +| TMPL-16 | Phase 20 | Pending | **Coverage:** - v1.0 requirements: 28 total — mapped to phases 1-7 — all Complete - 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 +- v1.3 requirements: 16 total — mapped to phases 18-20 — all Pending +- Total mapped: 77 - Unmapped: 0 --- *Requirements defined: 2026-03-19* -*Last updated: 2026-04-03 — v1.2 traceability added (MSIGN-01–11 → Phases 14–16, DEPLOY-01–05 → Phase 17)* +*Last updated: 2026-04-06 — v1.3 traceability added (TMPL-01–04 → Phase 18, TMPL-05–09 → Phase 19, TMPL-10–16 → Phase 20)* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index c2a9e56..7734184 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -8,11 +8,14 @@ v1.1 extends the platform with AI-assisted field placement, expanded field types v1.2 extends the platform to multiple signers in parallel and ships a production-ready Docker Compose deployment with correct SMTP and secret injection. +v1.3 adds a document template system — agent creates reusable field layouts with signer role labels and text hints, then applies them when starting new client documents so the same PDF never needs to be field-mapped from scratch. + ## 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) +- 📋 **v1.3 Document Templates** - Phases 18-20 (planned) ## Phases @@ -179,6 +182,14 @@ Plans: - [x] **Phase 16: Multi-Signer UI** - PreparePanel signer list, FieldPlacer signer assignment and color-coding, send-block validation, per-signer dashboard status (completed 2026-04-03) - [x] **Phase 17: Docker Deployment** - Three-stage Dockerfile, docker-compose.yml with named uploads volume and env_file secrets, health endpoint, SMTP fix (completed 2026-04-03) +### 📋 v1.3 Document Templates (Planned) + +**Milestone Goal:** Agent creates reusable document templates with pre-placed fields (including AI auto-placement) so the same PDF never needs to be field-mapped from scratch for every client. + +- [ ] **Phase 18: Template Schema and CRUD API** - New `document_templates` table with Drizzle migration; list, create, rename, and soft-delete API routes +- [ ] **Phase 19: Template Editor UI** - FieldPlacer `onPersist` abstraction, template editor page at `/portal/templates/[id]`, AI auto-place wired to template context, signer role label support, save template +- [ ] **Phase 20: Apply Template and Portal Nav** - "Start from template" option in AddDocumentModal, apply operation with field snapshot and role-to-email mapping, text hint quick-fill, Templates portal nav section and list page + ## Phase Details ### Phase 8: Schema Foundation and Signing Page Safety @@ -359,10 +370,6 @@ Plans: - [ ] 16-04-PLAN.md — Dashboard N/M signed badge (signingTokens count query, DocumentsTable badge rendering) **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 @@ -380,10 +387,48 @@ Plans: - [x] 17-02-PLAN.md — Dockerfile (three-stage, node:20-slim, linux/amd64), docker-compose.yml (env_file, DNS fix, named volume), .dockerignore, .env.production.example **UI hint**: no +### Phase 18: Template Schema and CRUD API +**Goal**: The `document_templates` table exists in the database and agents can create, rename, list, and soft-delete templates via API — every subsequent template feature depends on this foundation +**Depends on**: Phase 17 +**Requirements**: TMPL-01, TMPL-02, TMPL-03, TMPL-04 +**Success Criteria** (what must be TRUE): + 1. Agent can create a new template by selecting a PDF from the forms library — a `document_templates` row is inserted with the chosen `formTemplateId` FK and an empty field layout + 2. Agent can rename a template and the new name is persisted and reflected immediately in the template list + 3. Agent can delete a template — the row is soft-deleted (`archivedAt` set, not removed from DB) and disappears from the active list; no `ON DELETE CASCADE` touches any documents created from it + 4. Agent can retrieve a list of all active templates showing form name and field count — archived templates are filtered out +**Plans**: TBD +**UI hint**: no + +### Phase 19: Template Editor UI +**Goal**: Agent can open any template in a full field-placement editor, use AI auto-place, assign signer role labels instead of real emails, set text hints on text fields, and save the template — reusing the existing FieldPlacer component without duplication +**Depends on**: Phase 18 +**Requirements**: TMPL-05, TMPL-06, TMPL-07, TMPL-08, TMPL-09 +**Success Criteria** (what must be TRUE): + 1. Agent can open a template at `/portal/templates/[id]` and see the source PDF rendered with any previously saved fields overlaid — the editor uses the existing FieldPlacer drag-drop interface unchanged + 2. Agent can click "AI Auto-place" in the template editor and fields are placed on the template (routed through a `/api/templates/[id]/ai-prepare` route, not the document route) + 3. Signer assignment in the template editor accepts role labels ("Buyer", "Seller", "Agent") rather than email addresses — role strings are stored in the `signerEmail` slot and the editor does not reject them as invalid emails + 4. Agent can set a text hint on any text field — the hint is stored in the template and is visible as a placeholder label in the editor + 5. Agent can click Save and the current field layout (with role labels and text hints) is persisted to `document_templates.signatureFields` — a subsequent page reload shows the saved state +**Plans**: TBD +**UI hint**: yes + +### Phase 20: Apply Template and Portal Nav +**Goal**: Agent can start any new client document from a saved template — all fields are pre-loaded with fresh IDs, roles map to real signer emails, text hints appear as quick-fill suggestions — and "Templates" is a top-level portal destination +**Depends on**: Phase 19 +**Requirements**: TMPL-10, TMPL-11, TMPL-12, TMPL-13, TMPL-14, TMPL-15, TMPL-16 +**Success Criteria** (what must be TRUE): + 1. "Start from template" tab is available in AddDocumentModal; agent can pick a template from the list and create a document with all template fields pre-loaded at their saved positions + 2. Every field copied from the template has a freshly generated UUID — none of the template's original field IDs appear in the new document; editing the template afterward does not change the document's fields + 3. Template signer roles are automatically pre-mapped to the client's contacts (first role to primary contact, second role to co-buyer if present); agent can override any mapping before sending + 4. Text hints from the template appear as quick-fill suggestion buttons in the new document's PreparePanel + 5. "Templates" appears in the portal top nav and `/portal/templates` lists all active templates with form name, field count, and last-updated date +**Plans**: TBD +**UI hint**: yes + ## Progress **Execution Order:** -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 +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 → 18 → 19 → 20 | Phase | Milestone | Plans Complete | Status | Completed | |-------|-----------|----------------|--------|-----------| @@ -406,3 +451,6 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → | 15. Multi-Signer Backend | v1.2 | 3/3 | Complete | 2026-04-03 | | 16. Multi-Signer UI | v1.2 | 1/4 | Complete | 2026-04-03 | | 17. Docker Deployment | v1.2 | 2/2 | Complete | 2026-04-03 | +| 18. Template Schema and CRUD API | v1.3 | 0/TBD | Not started | - | +| 19. Template Editor UI | v1.3 | 0/TBD | Not started | - | +| 20. Apply Template and Portal Nav | v1.3 | 0/TBD | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index e7c4989..dbbe65c 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,16 +2,16 @@ gsd_state_version: 1.0 milestone: v1.3 milestone_name: Document Templates -status: defining requirements -stopped_at: Milestone v1.3 started — Document Templates +status: roadmap defined +stopped_at: v1.3 roadmap created — Phases 18-20 defined, ready for plan-phase 18 last_updated: "2026-04-06T00:00:00.000Z" last_activity: 2026-04-06 progress: - total_phases: 19 + total_phases: 22 completed_phases: 18 total_plans: 58 completed_plans: 57 - percent: 100 + percent: 82 --- # Project State @@ -24,10 +24,10 @@ See: .planning/PROJECT.md (updated 2026-04-03) ## Current Position -Phase: 17 (docker-deployment) — EXECUTING -Plan: 2 of 2 -Status: Phase complete — ready for verification -Last activity: 2026-04-03 +Phase: 18 (template-schema-and-crud-api) — NOT STARTED +Plan: 0 of TBD +Status: Roadmap defined — awaiting plan-phase 18 +Last activity: 2026-04-06 ## Note on v1.1 @@ -44,14 +44,25 @@ v1.2 (Multi-Signer and Deployment Hardening) roadmap is defined. Four phases pla Start v1.2 after Phase 13 Plan 04 completes: `/gsd:plan-phase 14` +## Note on v1.3 + +v1.3 (Document Templates) roadmap created 2026-04-06. Three phases planned: + +- Phase 18: Template Schema and CRUD API — `document_templates` table (Drizzle migration), GET/POST/PATCH/DELETE API routes, soft-delete pattern +- Phase 19: Template Editor UI — FieldPlacer `onPersist` abstraction, template editor page, AI auto-place via `/api/templates/[id]/ai-prepare`, signer role label support, save +- Phase 20: Apply Template and Portal Nav — "Start from template" in AddDocumentModal, field snapshot with fresh UUIDs, role-to-email mapping, text hint quick-fill, Templates nav + list page + +Start v1.3 with: `/gsd:plan-phase 18` + ## Accumulated Context ### Roadmap Evolution - 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) +- v1.3 roadmap created 2026-04-06: Phases 18-20 (Document Templates) -Progress: [█████████████] 100% (13/13 phases complete — v1.1 scope) +Progress: [████████████░░░] 82% (18/22 phases complete — counting v1.3 scope) ## Performance Metrics @@ -189,6 +200,17 @@ Recent decisions affecting v1.1 work: - [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 +### v1.3 Pre-decisions (from research) + +- [v1.3 Research]: `document_templates` is a separate table from `form_templates` — form_templates is read-only seeded catalog; document_templates is agent-authored field layouts; FK from new to old +- [v1.3 Research]: Template fields carry signer role labels ("Buyer", "Seller") in the signerEmail slot — the apply operation enforces a complete role-to-email map before DB INSERT; email format validation must not run during template editing +- [v1.3 Research]: Field ID collision prevention is mandatory — stamp fresh crypto.randomUUID() on every field at apply time; template field IDs must never appear in documents +- [v1.3 Research]: `hint` vs `textFillData` distinction — hint is a placeholder label stored in template; textFillData holds values burned into PDFs; never store hints in textFillData +- [v1.3 Research]: Soft-delete only (`archivedAt` column) — no hard deletes; list API filters `archivedAt IS NULL`; documents.formTemplateId is lineage metadata only, no ON DELETE CASCADE +- [v1.3 Research]: FieldPlacer `onPersist` callback is a non-breaking addition — existing document consumers pass no prop, behavior unchanged; template editor passes the callback to save to document_templates +- [v1.3 Research]: `updatedAt` must be set explicitly in update queries — no DB trigger; follows existing pattern in all current tables +- [v1.3 Research]: Single non-agent signer role auto-maps to assigned client email — reduces friction for solo-agent single-signer templates; agent can override + ### Pending Todos None yet. @@ -197,9 +219,10 @@ None yet. - [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 +- [Phase 19 - PRE-DECISION NEEDED]: Confirm whether FieldPlacer has any `z.string().email()` or similar validation on `signerEmail` before Phase 19 begins — if so, introduce `mode: "template" | "document"` prop alongside `onPersist` ## Session Continuity -Last session: 2026-04-03T22:58:03.579Z -Stopped at: Completed 17-02-PLAN.md — Dockerfile, docker-compose.yml, .dockerignore, .env.production.example, DEPLOYMENT.md +Last session: 2026-04-06T00:00:00.000Z +Stopped at: v1.3 roadmap created — Phases 18-20 defined; ROADMAP.md, STATE.md, REQUIREMENTS.md updated Resume file: None