task-d.5.1

docs/implementation/task-d51-lead-foundation-stabilization.md

@@ -0,0 +1,140 @@
+# Task D.5.1: Lead Foundation Stabilization & Output Completion
+
+## Objective
+
+Audit the existing D.5 phase-1 lead foundation work, avoid duplicate schema creation, complete missing registration outputs, and confirm current CRM compatibility before D.5.2 lead API work begins.
+
+## Review Completed
+
+- `AGENTS.md`
+- `docs/standards/project-foundations.md`
+- `docs/standards/task-catalog.md`
+- `docs/adr/0018-lead-enquiry-domain-separation.md`
+- `docs/implementation/task-d5-lead-enquiry-domain-separation.md`
+- `src/db/schema.ts`
+- `src/db/seeds/foundation.seed.ts`
+- `drizzle/0020_lead_foundation_schema.sql`
+- `drizzle/0021_worried_nebula.sql`
+- `drizzle/meta/_journal.json`
+- `src/features/foundation/master-options/types.ts`
+- `src/features/foundation/document-sequence/service.ts`
+
+## Existing Foundation
+
+Verified present in the repository:
+
+- `crm_leads` exists in [schema.ts](C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/db/schema.ts)
+- `crm_enquiries.lead_id` exists in [schema.ts](C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/db/schema.ts)
+- ADR-0018 exists at [0018-lead-enquiry-domain-separation.md](C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/adr/0018-lead-enquiry-domain-separation.md)
+- lead seed categories already exist in [foundation.seed.ts](C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/db/seeds/foundation.seed.ts):
+  - `crm_lead_awareness`
+  - `crm_lead_status`
+  - `crm_lead_followup_status`
+  - `crm_lead_lost_reason`
+- document sequence defaults already include:
+  - `crm_lead`
+  - `crm_enquiry`
+
+## Missing Foundation Found
+
+The missing outputs were not schema objects. They were governance and contract gaps:
+
+- no dedicated Lead Foundation entry in `project-foundations.md`
+- no Task D.5 or Task D.5.1 registration in `task-catalog.md`
+- master-option category type registry did not include the new lead option categories, which made the seed data harder to discover and reuse from foundation settings code
+- no D.5.1 implementation summary existed
+
+## Partial / Compatibility Findings
+
+### Migration history duplication risk
+
+Lead schema work appears twice in migration history:
+
+- [0020_lead_foundation_schema.sql](C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/drizzle/0020_lead_foundation_schema.sql)
+- [0021_worried_nebula.sql](C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/drizzle/0021_worried_nebula.sql)
+
+Compatibility status:
+
+- `0020` is idempotent with `IF NOT EXISTS`
+- `0021` is a later non-idempotent generated migration for the same structural slice
+- D.5.1 did not create any additional migration, in line with task rules
+
+This is recorded as a migration-history cleanup risk for future maintenance, not changed by this task.
+
+### Sequence compatibility
+
+The foundation now includes both legacy and future-facing enquiry sequence types:
+
+- legacy active enquiry service still generates `documentType = enquiry`
+- lead split foundation seed also registers `crm_enquiry`
+
+That means the seed layer is ready for split-domain work, but production enquiry creation is still compatible with the older enquiry document-type contract until D.5.2+ refactors the service layer.
+
+### Active production model
+
+Current CRM production behavior is still primarily driven by the old shared enquiry foundation:
+
+- lead and enquiry workspace separation still relies on `crm_enquiries.pipeline_stage`
+- no lead API, lead UI, or lead assignment flow exists yet
+- dashboard and reports still rely on the pre-split data model
+
+This is expected and remains in scope for later D.5 phases.
+
+## Changes Completed In D.5.1
+
+- added Lead Foundation registration to `docs/standards/project-foundations.md`
+- added Task D.5 and Task D.5.1 to `docs/standards/task-catalog.md`
+- extended `CRM_MASTER_OPTION_CATEGORIES` to include the new lead option categories in `src/features/foundation/master-options/types.ts`
+- added this implementation note
+
+## No Duplicate Creation Performed
+
+D.5.1 intentionally did not:
+
+- recreate `crm_leads`
+- recreate `crm_enquiries.lead_id`
+- generate a new migration
+- rename existing schema objects
+- create lead APIs or UI
+
+## Compatibility Verification
+
+Verification executed:
+
+- `npm exec tsc --noEmit`
+
+Result:
+
+- current Customer, Contact, Enquiry, Quotation, Dashboard, and Reports code continues to typecheck after the D.5.1 stabilization changes
+
+## Output Summary
+
+### Existing Foundation
+
+- `crm_leads`
+- `crm_enquiries.lead_id`
+- `ADR-0018`
+
+### Missing Foundation
+
+- Lead Foundation registry entry
+- Task catalog registration for D.5 and D.5.1
+- master-option category contract coverage for lead option seeds
+- D.5.1 implementation summary
+
+### Completed Foundation
+
+- Lead schema and seed presence verified
+- lead option categories registered in foundation type contracts
+- Lead Foundation registered in the standards registry
+- Task D.5 and D.5.1 registered in task history
+- compatibility state documented for D.5.2 planning
+
+## Ready For Next Task
+
+The repo is now better prepared for `Task D.5.2 Lead API Foundation` because:
+
+- the foundation state is discoverable
+- duplicate schema creation was avoided
+- lead option categories are registered in the shared master-option contract
+- current compatibility boundaries are explicitly documented