Update the roadmap_plan.md

docs/roadmap_plan.md

@@ -69,30 +69,104 @@ Status: **Completed**
    - compose maps Postgres container init values from `DATABASE__*`,
    - env contract drift tests now guard `.env.production.example`.
 
-## V6.2 - Reporting Features
+## V6.2 - GEDCOM Data Layer
 
-[ *More thoughts on additional features:*
-* *Ability to search within a document to find potential users to add to the People table.*
-* *Ability to search within a document to find dates to associate with people (e.g., John Smith was born on July 7, 1899; or "In February 1942, Martha and I drove to Wisconsin", "We took a vacation to Alaska in the summer of 1987", etc* ]
-
-Objective: improve research value with person-centric outputs.
+Objective: introduce a genealogical data layer sourced from GEDCOM exports, bridged to
+existing `Person` records via FamilySearch ID, without disrupting document-focused Person
+workflows.
 
 ### Scope
-1. Person timeline views using document dates and linked records.
-2. AI-assisted biography/family-history generation from curated sources.
-3. Exportable report views (human-readable, print-oriented).
+1. Manual `.ged` file upload only. No FamilySearch credentials are stored or used by the
+   app; the user runs the third-party `getmyancestors` tool themselves and uploads the
+   resulting export.
+2. Four new tables: `genealogy_person`, `genealogy_family`, `genealogy_family_child`, and
+   `genealogy_citation` (raw GEDCOM `SOUR` citations, reusable in a later version to record
+   when a transcribed document itself becomes citation evidence for FamilySearch).
+3. Upsert-based import keyed on FamilySearch ID (`fs_id`) so repeat imports update existing
+   records in place without breaking existing `Person.family_search_id` links or duplicating
+   surrogate keys.
+4. Reuse the existing V6.1 worker-backed `maintenance_run` pattern for import runs (run
+   history, status, summary, log view/download) rather than new infrastructure.
 
 ### Deliverables
-- Timeline UI and service queries with clear ordering/filters.
-- Prompted narrative generation workflow using existing evidence-safe patterns.
-- Saved/printable report presentation for review and sharing.
+- GEDCOM parser/importer producing the four genealogy tables.
+- `MaintenanceJobType` entry for GEDCOM import with upsert semantics and a run summary
+  (records added/updated).
+- Settings UI entry to upload a `.ged` file, trigger an import run, and view history.
 
 ### Exit Criteria
+- Importing the same `.ged` file twice does not duplicate or orphan data.
+- Existing `Person.family_search_id` values continue to resolve to the correct
+  `genealogy_person` row after import.
+- Import run history is visible with status, duration, and summary, consistent with other
+  maintenance runs.
+
+## V6.3 - Reporting and Genealogy-Enriched Features
+
+Objective: improve research value with person-centric outputs, grounded in both archival
+documents and the V6.2 genealogical data layer.
+
+This version is broken into five sequential sub-versions because of real dependency
+ordering: entity linking must exist before GEDCOM data can be targeted per-person; the
+Facts/Events mechanism must exist before timelines or reconciliation have anything
+meaningful to consume.
+
+### V6.3.1 - Manual Entity Linking
+
+- Search/browse UI over `genealogy_person` to find and link a candidate match to an
+  application `Person`, setting `family_search_id`. Linking is reversible (unlink).
+- Once linked, GEDCOM vitals display alongside the `Person` record without requiring any
+  schema change to `Person`.
+
+### V6.3.2 - Person Facts and Events
+
+- New fact/event table capturing: person, fact type (birth/death/event/free-form), date
+  (+raw), place, free-text description, and a link to the source document as evidence.
+- Manual tagging UI while reviewing a transcribed document: select a passage, choose the
+  person and fact type, record the date/description.
+- One-time migration of existing `Person.birth_date`/`birth_date_raw`/`birth_place`/
+  `death_date`/`death_date_raw`/`death_place` values into fact/event rows (tagged as
+  legacy/no-document-evidence where no source document is known), followed by retiring those
+  six columns from `Person`. Birth/death become Facts/Events like any other locally-known
+  fact, for both linked and unlinked people. `Person` permanently keeps `last_name`,
+  `given_names`, `biography`, `family_search_id`, `metadata_`, tags, photos, and document
+  associations.
+
+### V6.3.3 - Person Timelines
+
+- Timeline query merging GEDCOM milestones (birth, marriage, children's births, death) for
+  linked persons with locally recorded Facts/Events.
+- Timeline UI on Person Detail with clear ordering/filters; entries link back to their
+  originating document or GEDCOM record.
+
+### V6.3.4 - Reconciliation
+
+- Compares Facts/Events (the real, document-evidenced local signal) against corresponding
+  `genealogy_person` fields for linked persons.
+- Persisted reconciliation record: person, field, local value with evidence-document link,
+  GEDCOM value, and status (open / submitted / dismissed).
+- Re-evaluated automatically as part of each GEDCOM import maintenance run: opens new
+  discrepancies, auto-resolves ones where GEDCOM now matches, leaves others unchanged.
+- Reconciliation review UI functions as a manual to-do list for updating FamilySearch; the
+  app does not write back to FamilySearch itself.
+
+### V6.3.5 - AI-Assisted Biography Generation
+
+- Prompted narrative generation grounded in GEDCOM facts, Facts/Events, and relevant
+  document snippets as structured input, using existing evidence-safe prompting patterns.
+- Output cites back to source documents and FamilySearch records.
+- Saved/printable report presentation for review; reports do not modify archival source
+  data.
+
+### Exit Criteria (applies across V6.3.1-V6.3.5)
+- Entity links are reversible and do not alter document associations.
 - Timelines are reproducible from persisted records.
+- Reconciliation items always carry a link to the document evidence justifying the local
+  value, and re-running GEDCOM import correctly opens, resolves, or leaves items unchanged.
 - Narrative generation is traceable to source records and prompts.
 - Reports can be reviewed without modifying archival source data.
 
-## V6.3 - Access Control and Multi-User Readiness
+## V6.4 - Access Control and Multi-User Readiness
 
 [ *More thoughts on user accounts:*
 * *Create a generic "view only" user that does not have the rights to alter any of the data*
@@ -115,26 +189,22 @@ Objective: prepare for managed collaboration beyond single-user operation.
 - Role policies are enforced by deterministic tests.
 - User-attributed changes are visible for audit/review.
 
-## V7 or later - Scalability and Multi-Tenant Direction (Optional)
+## Deferred / Future Ideas (not committed scope)
 
-Objective: keep architecture ready for broader deployment footprints.
-
-### Scope
-1. Evaluate per-tenant or per-user data partitioning strategy.
-2. Formalize connection/runtime strategy for tenant-aware DB selection.
-3. Expand operational telemetry for throughput and cost monitoring.
-
-### Deliverables
-- Decision document for tenancy model and migration strategy.
-- Prototype-safe runtime boundary for selecting data targets.
-- Monitoring baseline for queue depth, job latency, and provider cost trends.
-
-### Exit Criteria
-- Selected tenancy strategy is documented and testable.
-- Operational metrics support capacity planning.
+Captured for later consideration, not yet scheduled to a version:
+* AI-assisted entity disambiguation (kinship co-occurrence, chronological plausibility
+  filtering) when linking document mentions to people.
+* Kinship-aware `@mention` tagging while transcribing.
+* Relationship-calculator badges (e.g., "3rd Great-Grandmother") in the document viewer.
+* Interactive migration/geography mapping from GEDCOM and document place mentions.
+* AI-suggested document discovery by date/location overlap with known persons.
+* Ability to search within a document to find potential people to add to the People table.
 
 ## Planning Notes
 
 - Keep architecture, schema, and UI contracts synchronized in `docs/` as each version lands.
 - Prefer explicit schema migration over runtime compatibility write paths.
 - Preserve evidence/provenance guarantees when adding new AI-powered features.
+- GEDCOM/FamilySearch data is external, collaborative, and mutable; treat it as a managed
+  cache bridged via `fs_id`, never as a replacement for archival evidence recorded from
+  transcribed documents.