# GovOPlaN Distribution Lists Implementation Plan

## Milestone 0: Module Seed

Goal: establish repository identity, module boundary, and installable manifest.

Tasks:

- [x] initialize repository type and package metadata
- [x] document boundary between address lists, distribution lists, and Umlauf
- [x] add a no-op module manifest with durable documentation topics
- [x] create Gitea issues for the implementation milestones

## Milestone 1: Contract And DTOs

Goal: define mixed recipient entries without implementing every provider.

Tasks:

- [x] define distribution-list, entry, expansion-plan, and expansion-result DTOs
- [x] define source reference formats for address contacts, IDM identities/typed
  groups, organization units/functions, effective incumbents, Dataflow results,
  raw targets, and nested-list entries
- [x] define policy/read-only explanation payloads
- [x] define snapshot evidence shape
- [x] add cycle detection and expansion-limit semantics

## Milestone 2: Local Distribution Lists

Goal: implement local, manually maintained distribution lists.

Tasks:

- [x] add database tables and migrations
- [x] add CRUD routes and permissions
- [x] add local raw email/postal entries
- [x] add references to address contacts and address lists via capabilities
- [x] expose `dist_lists.source` and `dist_lists.expand`
- [x] add tests for expansion and snapshots

## Milestone 3: Provider Integrations

Goal: allow distribution lists to resolve through installed modules.

Tasks:

- [x] integrate with `addresses.lookup` and address-list source capability
- [x] integrate with IDM identity and effective function-assignment resolution
- [ ] resolve typed IDM groups once `govoplan-idm#7` exposes the provider contract;
  until then the selector and expansion return an explicit unavailable outcome
- [x] integrate with Organizations unit/function resolution
- [x] consume governed Datasource/Connector states through pinned Dataflow outputs
- [x] apply Addresses preference/consent facts and explainable Policy decisions
- [x] preserve module independence when optional providers are absent

## Milestone 4: UI

Goal: make distribution lists practical for administrators and operators.

Tasks:

- [x] add list management UI
- [x] add mixed entry editor with provider-specific search
- [x] show disabled/read-only entries with explanations
- [x] show expansion preview and stale-source warnings
- [x] expose picker components to Campaign, Templates, Reporting, and Workflow
  consumers

## Milestone 5: AdreMa Dynamic Audiences

Goal: replace hard-coded AdreMa query branches with reusable governed
definitions.

Tasks:

- [x] add immutable static, parameterized, and dynamic definition revisions
- [x] support include/exclude/manual-override sets with bounded policy constraints
- [x] pin Datasource states, Connector revisions, and Dataflow definitions
- [x] provide preview, counts, samples, and `why included/excluded` diagnostics
- [x] freeze exact expansion and channel-decision evidence
- [x] validate with a synthetic AdreMa golden flow

## Milestone 6: Campaign, Reporting, And Workflow Integration

Goal: support administrative circulation workflows without confusing list
definition with execution.

Tasks:

- let Campaign consume snapshots for explicit hybrid-channel routing
- let Reporting consume snapshots for parameterized tables and exports
- let Workflow consume distribution-list expansion snapshots
- support ordered participant sequences where workflow owns state
- add escalation and substitution hooks through workflow, not distribution lists
- preserve immutable recipient evidence for every execution