77KB
stepsCompleted:
- step-01-validate-prerequisites
- step-02-design-epics
- step-03-create-stories inputDocuments:
- _bmad-output/planning-artifacts/prd.md
- _bmad-output/planning-artifacts/architecture.md
- _bmad-output/planning-artifacts/ux-design-specification.md
Campaign_Tracker App - Epic Breakdown
Overview
This document provides the complete epic and story breakdown for Campaign_Tracker App, decomposing the requirements from the PRD, UX Design, and Architecture into implementable stories.
Requirements Inventory
Functional Requirements
FR1: Client services staff can create and maintain municipality account profiles linked to existing jurisdiction identifiers. FR2: Client services staff can store and update municipality operational mailing and delivery addresses for election services. FR3: Client services staff can manage municipality service-contact records, including primary and secondary contacts. FR4: Client services staff can view municipality-specific service defaults from prior election cycles. FR5: Client services staff can create a new election-cycle job for a municipality without altering legacy Access tables. FR6: Client services staff can define election-cycle key dates for data files, proofing, pickups, deliveries, and mail activities. FR7: Client services staff can copy configurable planning defaults from the municipality's prior election-cycle job. FR8: Operations users can mark required planning fields complete and see readiness status for each election-cycle job. FR9: Client services staff can configure addressing service for an election-cycle job, including quantities and dependency fields. FR10: Client services staff can configure envelope service options including purple and blue envelope scenarios. FR11: Client services staff can configure office-copy requirements and related production details. FR12: Client services staff can configure sorting service options including quantity, class, permit/meter, and daily-sort flags. FR13: Users can record transportation-relevant service events tied to configured services. FR14: Operations users can schedule and update milestone dates for all configured service events. FR15: Operations users can view milestone timelines by municipality and by date across active election-cycle jobs. FR16: Operations users can detect missing or conflicting required milestones before execution cutoffs. FR17: Operations users can reassign milestone ownership and due dates across teams. FR18: Production users can update job status at defined process checkpoints. FR19: Support and operations users can log exceptions, blockers, and resolution notes against an election-cycle job. FR20: Users can record status transitions with timestamped history for key operational events. FR21: Users can view current and historical process state for a municipality's election-cycle jobs. FR22: Users can generate a transportation report grouped by date and sorted by county and municipality context. FR23: Users can generate a sorting report by municipality for all jobs with sorting enabled. FR24: Users can generate a sorting report by mail date for all jobs with sorting enabled. FR25: Users can export operational reports for downstream consumption in spreadsheet-compatible formats. FR26: Users can filter reports by date ranges, municipality, county, and service-status criteria. FR27: Administrators can manage user roles and permissions for client services, production, transportation, support, and admin functions. FR28: Administrators can manage extension-layer reference values used by planning and status workflows. FR29: Administrators can define required-field rules for election-cycle readiness checks. FR30: Administrators can configure notification/escalation rules for missed or at-risk milestones. FR31: System users can link extension records to existing legacy identifiers (ID, JCode/JurisCode, KitID) for unified workflows. FR32: Administrators can run compatibility validation checks that confirm legacy-table schemas remain unchanged. FR33: Support users can trace report values back to source records across legacy and extension datasets. FR34: Authorized users can correct extension-layer data issues without direct edits to immutable legacy tables.
NonFunctional Requirements
NFR1: 95% of authenticated page loads for core workflows complete in 2 seconds or less under normal operating load. NFR2: 95% of create/update operations for election-cycle records complete with user confirmation in 1 second or less. NFR3: Transportation and sorting report generation completes in 30 seconds or less for standard daily/weekly filters. NFR4: 100% of application traffic is encrypted in transit using TLS 1.2+ and verified by quarterly transport-security scans. NFR5: 100% of sensitive stored operational data is encrypted at rest with platform-managed AES-256 controls, verified by monthly configuration audits. NFR6: 100% of privileged operations enforce role-based authorization checks, and unauthorized requests are blocked and logged. NFR7: Security-relevant actions (authentication events and permission-sensitive updates) are logged within 5 seconds and retained for at least 365 days. NFR8: The system supports at least 10x growth in active election-cycle job volume without requiring legacy schema changes. NFR9: The system supports at least 150 concurrent operational users with p95 response time under 2 seconds and error rate under 1% during peak-period load testing. NFR10: MVP screens for forms, tables, and reports meet WCAG 2.1 AA-aligned criteria relevant to keyboard access, labeling, contrast, and focus visibility. NFR11: 100% of critical workflows are operable by keyboard-only interaction and validated against an accessibility test checklist in each release. NFR12: Legacy Access tables are treated as immutable dependencies, and release gates fail on any unauthorized schema delta against the approved baseline. NFR13: Extension-table joins to legacy identifiers maintain at least 99.9% referential consistency, verified by nightly integrity checks and pre-release validation runs. NFR14: Exported report datasets preserve required field parity for existing operational consumers. NFR15: Planned system availability target is 99.5% monthly during operational hours. NFR16: Every key milestone/status update is stored with audit history sufficient for operational reconstruction. NFR17: Recovery procedures ensure no committed extension-record updates are lost for the previous 24 hours of operations.
Additional Requirements
- Starter Template (Epic 1, Story 1): ASP.NET Core 10 Web API + Vite React TypeScript. Initialization commands:
dotnet new sln -n campaign-tracker,dotnet new webapi -n Campaign_Tracker.Server -f net10.0 --use-controllers,dotnet sln add,npm create vite@latest campaign-tracker-client -- --template react-ts. - Anti-corruption data access layer required between modern services and immutable legacy Access structures.
- Separate operational write path (extension tables) from report read path (join/materialized/query layer) to reduce coupling.
- Join-key integrity (ID, JCode/JurisCode, KitID) is a platform concern requiring scheduled validation jobs and release-gate checks.
- Pre-commit validation orchestration as a shared capability: required-field checks, dependency checks, and policy checks before any sensitive state transition.
- Parity governance workflow: run legacy and modern reports in parallel during transition; define parity acceptance thresholds per report type; require parity evidence as a formal cutover gate.
- Compliance evidence model: generate and bind evidence artifacts (security events, data residency, accessibility) to release gates, not post-release documentation.
- Discrepancy triage workflow with owner assignment, resolution status tracking, and closure audit trail.
- Performance strategy under peak election windows: query shaping, caching strategy, and export throughput optimization for concurrent report generation.
UX Design Requirements
UX-DR1: Implement Ant Design v5 as base component library with custom token configuration — colorPrimary (#1F4E79), teal secondary (#0F766E), interactive accent (#2563EB), semantic status palette (success/warning/error/info/overdue), compact density profile, and Public Sans / IBM Plex Sans typography stack. UX-DR2: Build tri-pane workspace shell as primary application layout — left context/navigation pane (municipality and saved views), center dense editable operations grid, right risk queue + inspector/provenance panel; collapsible secondary pane at 1280–1599px. UX-DR3: Implement MunicipalityCycleWorkspaceGrid custom component — sticky header, column controls, inline editable cells, row status chips, provenance quick-view trigger; states: default, sorted, filtered, inline-editing, validation-error, loading, empty; keyboard row/cell navigation with ARIA sort state. UX-DR4: Implement SafeCommitRail custom component — pre-commit dependency/policy gate; anatomy: validation summary, blocking reasons, corrective links, reason-code selector, commit action; variants: inline rail (grid), drawer rail (detail mode); commit disabled until all checks and reason codes satisfied. UX-DR5: Implement CutoffRiskQueuePanel custom component — persistent urgency queue; anatomy: prioritized cards, countdown/due state, severity badges, owner, quick-open action; always-visible in right pane; reorders deterministically after updates; severity announced with text labels not color alone. UX-DR6: Implement BlockerResolutionDrawer custom component — in-context recovery workspace; anatomy: blocker details, dependency links, assignment, due-by edit, resolution note, save controls; writes exception history on save; returns user to previous context. UX-DR7: Implement DispatchRunBuilder custom component — date range controls, filter set, results grouped by date/county/municipality, quantity notes, export actions; next-day quick mode and 7-day lookahead mode; deep-links to corrective records on data gaps. UX-DR8: Implement ProvenanceTimelinePanel custom component — timestamped events, actor, reason code, changed fields, source link; compact inline preview and full audit view variants; semantic timeline structure for screen readers. UX-DR9: Implement keyboard-first interaction across all operational surfaces: visible 2px focus indicators, logical tab order in grids/forms/drawers/modals, standardized focus management for modal/drawer open/close flows. UX-DR10: Implement role-based workspace entry — distinct default views and saved filter presets for Client Services, Production, Transportation, Support, and Admin roles. UX-DR11: Implement “Next Best Action” prompt system per record to reduce decision latency in operations views. UX-DR12: Implement accessible status semantics — pair all status colors with text labels and icons; WCAG 2.2 AA minimum contrast (4.5:1 normal text, 3:1 large text/UI components); respect reduced-motion preferences. UX-DR13: Implement deterministic filtering/sorting with always-visible active filter chips, saved presets per user role/workspace, and predictable default sort (urgency then due date). UX-DR14: Implement progressive required-field validation — validate inline during edit; hard-block validation at publish/commit checkpoints only; show inline field-level errors plus top-level summary for multi-error states. UX-DR15: Implement desktop-first responsive strategy — minimum supported width 1280px; full tri-pane at 1600px+; compact tri-pane with collapsible secondary at 1280–1599px; reduced read mode with support notice below 1280px.
FR Coverage Map
FR1: Epic 1 - Municipality account profile creation and management FR2: Epic 1 - Municipality operational mailing/delivery addresses FR3: Epic 1 - Municipality service-contact records FR4: Epic 1 - Prior-cycle service defaults FR5: Epic 2 - Election-cycle job creation FR6: Epic 2 - Election-cycle key dates definition FR7: Epic 2 - Prior-cycle planning defaults copy FR8: Epic 2 - Required-field readiness status FR9: Epic 3 - Addressing service configuration FR10: Epic 3 - Purple/blue envelope service configuration FR11: Epic 3 - Office-copy requirements FR12: Epic 3 - Sorting service configuration FR13: Epic 3 - Transportation-relevant service events FR14: Epic 4 - Milestone scheduling and updates FR15: Epic 4 - Milestone timeline views FR16: Epic 4 - Missing/conflicting milestone detection FR17: Epic 4 - Milestone ownership reassignment FR18: Epic 5 - Job status updates at checkpoints FR19: Epic 5 - Exception, blocker, and resolution logging FR20: Epic 5 - Timestamped status transition history FR21: Epic 5 - Current and historical process state view FR22: Epic 5 - Transportation report (early municipality proof point) FR23: Epic 6 - Sorting report by municipality FR24: Epic 6 - Sorting report by mail date FR25: Epic 6 - Report export (spreadsheet-compatible) FR26: Epic 6 - Report filtering by date/municipality/county/status FR27: Epic 1 - Role and permission management foundation FR28: Epic 1 (seed/engine) + Epic 6 (admin UI) - Extension-layer reference value management FR29: Epic 1 (seed/engine) + Epic 6 (admin UI) - Required-field rules for readiness checks FR30: Epic 1 (seed/engine) + Epic 6 (admin UI) - Notification/escalation rule configuration FR31: Epic 1 - Legacy identifier linking (ID, JCode, KitID) FR32: Epic 1 - Legacy schema compatibility validation FR33: Epic 6 - Report-to-source record traceability FR34: Epic 6 - Extension-layer data correction FR35: Epic 2 - Spreadsheet import and column mapping (Story 2.6) FR36: Epic 3 - Proof/contact workflow status handling (Story 3.2 additions)
Epic List
Epic 1: Foundation, Auth, Municipality Profiles & Admin Seed
Users can authenticate and access their role-specific workspace. Municipality account profiles, addresses, contacts, and service defaults are immediately available linked to legacy jurisdiction identifiers. Seed data makes the system operationally functional from day one. Audit logging runs as a shared infrastructure-level service across all epics.
FRs covered: FR1, FR2, FR3, FR4, FR27, FR28 (seed+engine), FR29 (seed+engine), FR30 (seed+engine), FR31, FR32 Architecture: ASP.NET Core 10 + Vite React TS starter template initialization, anti-corruption data access layer, RBAC setup, legacy join-key integrity validation, compatibility check release gates, NFR7 shared audit logging infrastructure UX: Ant Design v5 token setup (UX-DR1), tri-pane workspace shell (UX-DR2), role-based workspace entry (UX-DR10), keyboard-first foundation (UX-DR9), desktop-first responsive strategy (UX-DR15) Implementation note: FR1–FR4 are CRUD-weight stories; FR27–FR32 carry infrastructure weight. Stories can be developed in parallel within the epic by splitting backend and frontend tracks. Adoption target: Epic 2 must begin within 6 weeks of Epic 1 delivery to preserve coordinator adoption momentum.
Epic 2: Election-Cycle Job Creation & Planning
Client services staff can create election-cycle jobs, define key dates, apply prior-cycle defaults, and track required-field readiness status to production-ready publication — with a kanban entry-point that assigns municipalities to cycle lanes (multiple concurrent cycle support included).
FRs covered: FR5, FR6, FR7, FR8 UX: Municipality-to-Cycle Kanban Entry Point (UX-DR16) — municipality cards in multiple cycle lanes; SafeCommitRail component (UX-DR4) built as reusable module for Epic 3 and Epic 5 consumption; progressive required-field validation (UX-DR14) Metric: Epics 2+3 together are the primary delivery point for the 40% election job setup-time reduction KPI (PRD Success Criteria)
Epic 3: Service Configuration
Client services staff can configure all election services on a job: addressing (quantities and dependency fields), purple and blue envelope scenarios, office-copy requirements, sorting options (quantity, class, permit/meter, daily-sort flags), and transportation-relevant service events.
FRs covered: FR9, FR10, FR11, FR12, FR13 UX: MunicipalityCycleWorkspaceGrid (UX-DR3) — inline editable cells, row status chips, deterministic filtering; SafeCommitRail reused from Epic 2 Metric: Epics 2+3 together = 40% setup-time reduction measurement checkpoint; post-Epic 3 coordinator survey recommended
Epic 4: Milestone Scheduling & Timeline Management
Operations teams can schedule and update milestone dates for all configured service events, view milestone timelines by municipality and date across active jobs, detect missing or conflicting required milestones before execution cutoffs, and reassign milestone ownership and due dates across teams.
FRs covered: FR14, FR15, FR16, FR17 UX: CutoffRiskQueuePanel (UX-DR5) — persistent urgency queue, always-visible in right pane; Next Best Action prompts (UX-DR11); deterministic filtering/sorting with saved presets (UX-DR13)
Epic 5: Production Tracking, Exception Management, Audit History & Transportation Report
Production teams can update job statuses at checkpoints, log exceptions and blockers with resolution notes, record timestamped status transitions, and view complete process history. Transportation coordinators receive the first external-facing report — a date-sorted transportation dispatch report grouped by county and municipality — giving municipality clients an early proof point before the full reporting suite.
FRs covered: FR18, FR19, FR20, FR21, FR22 UX: ProvenanceTimelinePanel (UX-DR8) — timestamped events, actor, reason code, changed fields; BlockerResolutionDrawer (UX-DR6) — in-context recovery workspace; accessible status semantics (UX-DR12) External proof point: FR22 transportation report provides municipality clients visible evidence of modernization before Epic 6
Epic 6: Full Reporting Suite, Admin Management UIs & Governance
All remaining operational reports with deterministic filtering and spreadsheet-compatible export. Admin management UIs for reference values, required-field rules, and escalation rules (completing FR28/FR29/FR30 from seed-only to fully configurable). Support analysts get report-to-source traceability and extension-layer data correction tools. Parity governance closes with a defined sunset criteria, named owner, and municipality sign-off before legacy report deprecation.
FRs covered: FR23, FR24, FR25, FR26, FR33, FR34 Admin UIs: FR28 reference value management UI, FR29 required-field rules management UI, FR30 escalation rule configuration UI UX: DispatchRunBuilder (UX-DR7); deterministic filtering with saved presets (UX-DR13) Parity governance: Must include sunset trigger threshold, named operational owner, and municipality client sign-off criteria before legacy report stack is deprecated
Epic 1: Foundation, Auth, Municipality Profiles & Admin Seed
Users can authenticate and access their role-specific workspace. Municipality account profiles are immediately available linked to legacy jurisdiction identifiers. Seed data makes the system operationally functional. Audit logging runs as a shared infrastructure-level service across all epics.
Story 1.1: Project Initialization & Solution Scaffold
As a developer, I want the solution scaffolded with ASP.NET Core 10 Web API and Vite React TypeScript, So that the team has a working, runnable baseline with the correct project structure for all subsequent stories.
Acceptance Criteria:
Given the initialization commands are run (dotnet new sln, dotnet new webapi, npm create vite@latest --template react-ts)
When the solution builds
Then both Campaign_Tracker.Server and campaign-tracker-client compile without errors
Given the solution is running locally When the Vite dev server starts Then the React app loads at the configured local URL with no console errors
Given the server is running When GET /health is called Then it returns 200 OK with a status payload
Given the solution structure is created When reviewed against the architecture decision Then the .sln file, server project folder, and client project folder exist at expected paths and .gitignore excludes node_modules, bin, obj, and .env files
Story 1.2: Workspace Shell & Ant Design Foundation
As any authenticated user, I want a consistent tri-pane application layout with the Ant Design visual system applied, So that I have a predictable, accessible, and keyboard-navigable operational environment from day one.
Acceptance Criteria:
Given the app loads after authentication When an authenticated user enters the application Then the tri-pane layout renders with a left navigation pane, center content area, and collapsible right panel
Given the Ant Design token configuration is applied When the UI renders Then colorPrimary is #1F4E79, teal secondary is #0F766E, semantic status colors (success/warning/error/info/overdue) match the UX spec, and compact density profile is active (UX-DR1)
Given a user interacts with any focusable element When tabbing through the interface Then visible 2px focus indicators are present on all interactive elements with logical tab order (UX-DR9)
Given the viewport is 1280–1599px When the layout renders Then the right panel is collapsible and the tri-pane adapts to compact mode (UX-DR15)
Given the viewport is below 1280px When the layout renders Then a reduced read mode with a support notice is displayed and full editing is not available
Given any status indicator renders When viewed Then status is conveyed with both color and a text label or icon — never color alone (UX-DR12)
Story 1.3: Keycloak Realm Configuration & OIDC Integration
As any team member, I want to authenticate using Keycloak single sign-on via OpenID Connect, So that I can securely access the application with my organizational credentials.
Acceptance Criteria:
Given a user navigates to the application while unauthenticated When they load any protected route Then they are redirected to the Keycloak login page for the configured realm
Given a user enters valid Keycloak credentials When authentication succeeds Then they receive a JWT access token, are redirected to their role-specific workspace, and the authentication event is logged to the audit service within 5 seconds (NFR7)
Given a user's access token expires When they make an authenticated request Then the refresh token flow silently renews the session or redirects to login if the refresh token is also expired
Given an invalid or expired token is presented to the API When the request is processed Then the API returns 401 Unauthorized and the failed authentication attempt is captured in the audit log
Given the application is deployed When traffic is inspected Then all communication is over TLS 1.2+ (NFR4) and sensitive token data is not exposed in URLs or logs
Story 1.4: Keycloak Role Mapping & Application Authorization
As a developer, I want Keycloak roles mapped to application permission policies enforced on API routes and frontend features, So that each user sees only the capabilities appropriate to their operational role.
Acceptance Criteria:
Given a Keycloak user has the ClientServices role When they authenticate and navigate Then they can access municipality profile and election-cycle creation routes and cannot access admin-only or production-only routes
Given a Keycloak user has the Admin role When they authenticate Then they can access all application routes including admin-sensitive functions
Given a user without a recognized application role authenticates When they access any protected route Then they receive 403 Forbidden and the unauthorized access attempt is logged with actor identity
Given a privileged operation is performed When it completes Then the authorization check result, actor, and resource are captured by the audit logging service within 5 seconds (NFR6, NFR7)
And roles ClientServices, Production, Transportation, Support, and Admin are managed entirely in Keycloak Admin Console — FR27 is satisfied without a custom role management UI
Story 1.5: Shared Audit Logging Infrastructure
As a system, I want all security-relevant and operational events captured by a shared logging service, So that audit history is uniformly available across all application features from day one without per-feature implementation.
Acceptance Criteria:
Given any security-relevant action occurs (auth event, permission check, privileged update) When the action completes Then the event is written to the audit log within 5 seconds including actor identity, timestamp (UTC), action type, resource identifier, and outcome (NFR7)
Given audit records are persisted When the retention policy is evaluated Then records are retained for at least 365 days and are not purgeable by standard application operations (NFR7)
Given any application feature calls the audit logging service When the call is made Then it succeeds using the shared service contract — the calling feature does not implement its own audit persistence
Given an audit record is written When retrieved for review Then it is append-only — no update or delete operations are available on audit records
Given the audit service is unavailable When an auditable action occurs Then the action is blocked or queued — auditable operations must not silently proceed without capture
Story 1.6: Legacy Anti-Corruption Data Access Layer
As a developer, I want a dedicated read-only data access layer for legacy Access-derived entities using fixed join keys, So that legacy data is available to all features without any risk of schema mutation or direct table coupling.
Acceptance Criteria:
Given a feature requests municipality or jurisdiction data When the anti-corruption layer is called Then it returns data joined by ID, JCode/JurisCode, or KitID without modifying any legacy table structure or content (NFR12)
Given the anti-corruption layer executes any query When the operation is inspected Then only SELECT operations are permitted — INSERT, UPDATE, and DELETE on legacy entities are blocked at the layer boundary
Given legacy data is returned through the layer When mapped to the application domain Then it is converted to strongly-typed domain model objects before being returned to any calling feature
Given any application code outside the layer attempts to query legacy tables directly When reviewed in code Then no such direct access exists — the anti-corruption layer is the sole access point for legacy data
Story 1.7: Legacy Schema Compatibility Validation Gate
As an administrator, I want to run a compatibility check that confirms legacy table schemas are unchanged against the approved baseline, So that every release can be gated on legacy integrity before deployment.
Acceptance Criteria:
Given the compatibility check is triggered When it runs against the live database Then it compares all legacy table structures (column names, types, constraints) against the approved schema baseline stored at initialization
Given a structural change is detected on any legacy table When the check completes Then it returns a failure status with a detailed report identifying the affected table, column, and change type (NFR12)
Given no schema drift is detected When the check completes Then it returns a pass confirmation with timestamp, number of tables verified, and zero drift count
Given the check is integrated into the release pipeline When it fails Then the release is blocked automatically and a failure report is surfaced to the administrator
Given an administrator is logged in When they navigate to the compatibility check feature Then they can trigger the check manually and view the most recent check history with timestamps
Story 1.8: Legacy Identifier Linking for Extension Records
As a system user, I want extension records to store and validate legacy identifier references on creation, So that all new capabilities join deterministically to legacy Access records in workflows and reports.
Acceptance Criteria:
Given a new extension record is created (municipality profile, election job, service config) When it is saved Then it stores the appropriate legacy identifier (ID, JCode/JurisCode, or KitID) as a required foreign reference
Given an extension record references a legacy identifier When the anti-corruption layer executes a join Then it returns the correct legacy record with no ambiguity across all active records
Given an extension record is submitted with an invalid or non-existent legacy identifier When validation runs before save Then the save is rejected with a descriptive validation error identifying the invalid reference
Given the nightly integrity check runs When it evaluates all extension-to-legacy joins Then it reports referential consistency and flags any records that fail to resolve, targeting 99.9% consistency (NFR13)
Story 1.9: Seed System Reference Values & Rule Defaults
As a developer, I want the system seeded with default reference values, required-field rules, and escalation rule defaults, So that Epics 2–5 are immediately functional without requiring administrator configuration before use.
Acceptance Criteria:
Given the application initializes for the first time When the seed operation runs Then operational status sets, service template defaults, and extension-layer reference values are populated in the database
Given the seed runs When required-field rules are evaluated Then default readiness fields for election-cycle jobs are defined and evaluable by Epic 2's readiness status feature (FR29)
Given the seed runs When escalation rule defaults are checked Then at least one default rule exists covering overdue milestone alert scenarios (FR30)
Given the seed operation is run multiple times When it completes Then no duplicate records are created — the operation is fully idempotent
Given Epic 6 admin UIs update reference values or rules When the changes are saved Then they persist independently of the seed — rerunning the seed does not overwrite admin-managed values
Story 1.10: Municipality Account Profile
As a client services staff member, I want to create and maintain municipality account profiles linked to legacy jurisdiction identifiers, So that permanent municipality data is managed in the extension layer without modifying legacy Access tables.
Acceptance Criteria:
Given a client services user navigates to municipality management When they create a new municipality profile Then it is saved to the extension layer with a required link to a valid legacy jurisdiction identifier (ID/JCode)
Given a municipality profile is created When the profile is loaded Then the anti-corruption layer resolves the legacy join and displays combined extension and legacy data together in the workspace grid
Given a profile field is updated When saved Then the change is recorded in the audit log with actor identity and timestamp
Given a user attempts to create a profile without a valid legacy jurisdiction identifier When the form is submitted Then the save is rejected with a clear validation message identifying the required legacy link
And no INSERT, UPDATE, or DELETE operations are performed on legacy Access tables at any point
Story 1.11: Municipality Operational Addresses
As a client services staff member, I want to store and update municipality operational mailing and delivery addresses, So that election services reference current address information without depending on legacy records.
Acceptance Criteria:
Given a municipality profile exists When a client services user adds an address Then they can specify mailing or delivery address type, and the record is saved to the extension address table linked to the municipality profile
Given an address is updated When saved Then the previous address is preserved in history, the new address is marked as current, and the change is logged with actor and timestamp
Given an address record is saved When retrieved Then it includes address type, street, city, state, zip, and effective date fields
Given a municipality profile is viewed When addresses are displayed Then mailing and delivery addresses are shown with clear type labels and current/historical status
Story 1.12: Municipality Service Contacts
As a client services staff member, I want to manage municipality service-contact records including primary and secondary contacts, So that the right people can be reached during election operations without consulting legacy records.
Acceptance Criteria:
Given a municipality profile exists When a client services user adds a contact Then they can designate it as primary or secondary contact and save name, role/title, phone, and email
Given a municipality has both a primary and secondary contact When the profile is viewed Then both contacts are displayed with clear primary/secondary designation labels
Given a contact is updated or removed When the change is saved Then it is recorded in the audit log with actor identity and timestamp
Given a user attempts to save a contact without required fields (name, contact type) When the form is submitted Then the save is rejected with inline validation errors identifying the missing fields
Story 1.13: Municipality Prior-Cycle Service Defaults View
As a client services staff member, I want to view municipality-specific service defaults from prior election cycles as a read-only reference, So that I can reference proven configurations when setting up new election-cycle jobs in Epic 2.
Acceptance Criteria:
Given a municipality has at least one completed election-cycle job When a client services user views the prior-cycle defaults panel Then the most recent cycle's service configurations are displayed as read-only reference data
Given a municipality has multiple prior cycles When the defaults panel is viewed Then the most recent cycle is shown by default with a cycle selector control to navigate older cycles
Given no prior cycles exist for a municipality When defaults are requested Then the system displays a clear “No prior cycle defaults available” state with guidance to create the first cycle
And all data in this view is read-only — the apply-to-new-job action is out of scope for this story and delivered in Epic 2 (Story 2.4)
Epic 2: Election-Cycle Job Creation & Planning
Client services staff can create election-cycle jobs, define key dates, apply prior-cycle defaults, and track required-field readiness through to production-ready publication — with a kanban entry point showing municipalities across cycle lanes.
Story 2.1: Municipality-to-Cycle Kanban Entry Point
As a client services staff member, I want a kanban board showing municipalities as cards organized by election cycle lanes, So that I can see at a glance which municipalities are assigned to which cycles and initiate new cycle jobs from a familiar planning view.
Acceptance Criteria:
Given a client services user navigates to the election cycle workspace When the kanban loads Then municipalities with active cycle jobs appear as cards in their respective cycle lane columns, and municipalities with no active jobs appear in an “Unassigned” lane
Given a municipality has jobs in multiple concurrent election cycles When the kanban renders Then the municipality card appears in each relevant cycle lane independently (UX-DR16 multi-lane support)
Given a user views a municipality card When displayed in a cycle lane Then the card shows municipality name, jurisdiction code, cycle job status badge, and a quick-open action
Given a cycle lane contains many municipality cards When the user scrolls within the lane Then the lane column header remains visible and performance is maintained
Given a user interacts with the kanban via keyboard When navigating cards and lanes Then all card actions are reachable without a mouse and focus indicators are visible (UX-DR9)
Story 2.2: Create Election-Cycle Job
As a client services staff member, I want to create a new election-cycle job for a municipality from the kanban board, So that the municipality is assigned to an election cycle without altering any legacy Access tables.
Acceptance Criteria:
Given a municipality card is in the Unassigned lane When a client services user initiates job creation Then they can select an existing cycle or name a new cycle, and a new election-cycle extension record is created linked to the municipality's legacy identifier (ID/JCode)
Given an election-cycle job is created When saved Then it is stored in the extension table with the municipality's legacy identifier as a required join key and the municipality card moves to the selected cycle lane on the kanban
Given an election-cycle job is created When the job record is inspected Then it includes municipality reference, cycle name, creation actor, creation timestamp, and a status of “In Setup”
Given a job creation is attempted without selecting or naming a cycle When the form is submitted Then the save is rejected with a clear inline validation message
And no INSERT, UPDATE, or DELETE operations are performed on legacy Access tables at any point
Story 2.3: Election-Cycle Key Dates
As a client services staff member, I want to define election-cycle key dates for data files, proofing, pickups, deliveries, and mail activities, So that the election timeline is established and visible to all operational teams.
Acceptance Criteria:
Given an election-cycle job exists When a client services user opens the key dates section Then they can enter dates for: data file receipt, proofing, customer envelope pickup, customer envelope delivery, purple envelope pickup, purple envelope delivery, blue envelope pickup, blue envelope delivery, sort dates, mail dates, and tray delivery
Given a key date is entered and saved When the job is reloaded Then all entered dates persist and are visible in the job's date summary view
Given a key date entry would create a logical conflict (e.g., mail date before sort date) When the conflicting date is entered Then an inline warning identifies the conflict with specific field names — the save is not blocked but the warning is persistent until resolved
Given a key date is updated When saved Then the change is recorded in the audit log with actor identity and timestamp
Given a user enters dates via keyboard When using the date picker controls Then dates are enterable via keyboard without requiring mouse interaction (UX-DR9)
Story 2.4: Prior-Cycle Defaults Application
As a client services staff member, I want to copy configurable planning defaults from a municipality's prior election-cycle job into a new cycle, So that I can apply proven configurations without re-entering all details from scratch.
Acceptance Criteria:
Given an election-cycle job exists and the municipality has at least one prior completed cycle When a client services user selects “Apply Prior-Cycle Defaults” Then the prior cycle's service configurations and key date offsets are pre-populated into the new job's fields
Given prior-cycle defaults are applied When pre-populated fields are displayed Then each inherited field is visibly marked as “Inherited from [cycle name/year]” to distinguish it from manually entered data
Given a user applies defaults and then manually edits an inherited field When the edit is saved Then the “Inherited” marker is removed from that field and it is treated as a manually entered value going forward
Given a municipality has multiple prior cycles When applying defaults Then the user can select which prior cycle to use as the source from a list ordered most-recent first
Given a municipality has no prior cycles When the defaults action is viewed Then the option is disabled with a clear “No prior cycle available” message — no error state is triggered
Story 2.5: Election-Cycle Readiness Status & Publication
As a client services staff member, I want to see required-field readiness status for my election-cycle job and publish it to production readiness through a pre-commit validation rail, So that I can confirm the plan is complete and provide the team with a verified production-ready job.
Acceptance Criteria:
Given an election-cycle job has missing required fields (as defined by seeded rules from Story 1.9) When a client services user views readiness status Then each missing required field is identified by name with a jump-link that navigates directly to the field
Given all required fields are complete When readiness status is evaluated Then the job shows a “Ready to Publish” state and the Publish action becomes enabled
Given a user initiates the Publish action When the SafeCommitRail activates Then it runs dependency and policy checks and displays: overall pass/fail status, a list of any blocking reasons with one-click corrective action links, and a reason-code selector where audit policy requires it (UX-DR4)
Given the SafeCommitRail shows all checks passed When the user confirms the publish with a required reason code Then the job status transitions to “Production Ready” and actor, timestamp, and reason code are captured in the audit log
Given the SafeCommitRail shows one or more blocking issues When displayed Then the Publish confirm button remains disabled until all blocking issues are resolved
Given the publish action succeeds When the confirmation is shown Then a “Next Best Action” prompt guides the user to the recommended following step (e.g., configure services) (UX-DR11)
And the SafeCommitRail is built as a reusable shared module — it is independently consumable by Epic 3 service configuration commits and Epic 5 production status commits without duplication or modification
Story 2.6: Spreadsheet Import & Column Mapping
As a client services or operations user, I want to import approved election-cycle spreadsheet data and map it to the extension model, So that key schedule and service fields can be staged and reviewed without manual re-entry.
Acceptance Criteria:
Given an approved import file is provided When the import workflow starts Then the system parses required columns and validates expected template headers before staging data
Given staged rows include jurisdiction references
When mapping runs
Then each row is matched to legacy-linked identifiers (ID, JCode/JurisCode, KitID where applicable) or flagged as unresolved
Given a staged row fails validation When the review screen is displayed Then deterministic error output identifies the row, failing field, and corrective action needed before publish
Given a staged row passes validation When it is included in publish Then provenance metadata is recorded: source file identifier, source row reference, import timestamp, and importing user
Epic 3: Service Configuration
Client services staff can configure all election services on a job — addressing, envelopes, sorting, office copies, and transportation events — with inline editing in the operational workspace grid and SafeCommitRail validation on commits.
Story 3.1: Addressing Service Configuration
As a client services staff member, I want to configure addressing service for an election-cycle job including quantities and dependency fields, So that the addressing workflow has all required production parameters before execution begins.
Acceptance Criteria:
Given an election-cycle job exists When a client services user opens the addressing service section Then they can enter addressing quantity, addressing type, dependency fields, and addressing-specific notes
Given an addressing field is edited inline in the workspace grid When the cell is activated Then it enters edit mode with explicit commit and cancel controls visible and keyboard-accessible (UX-DR3)
Given addressing configuration is ready to commit When the user saves via the SafeCommitRail Then dependency and policy checks run, the configuration is stored against the election-cycle job on pass, and actor and timestamp are captured in the audit log
Given the MunicipalityCycleWorkspaceGrid renders a service configuration row When displayed Then a status chip shows current configuration completeness state (e.g., incomplete, configured, confirmed)
And the MunicipalityCycleWorkspaceGrid is built as a reusable shared component with: sticky column header, column visibility controls, inline editable cells, row status chips, and provenance quick-view trigger — consumable across all service configuration stories in this epic (UX-DR3)
Story 3.2: Envelope Service Configuration — Purple & Blue
As a client services staff member, I want to configure purple and blue envelope service options with quantities and scenario details, So that production teams know exactly what envelope materials and quantities to prepare for the election.
Acceptance Criteria:
Given an election-cycle job exists When a client services user opens envelope service configuration Then purple envelope and blue envelope scenarios are presented as independently configurable sections each with quantity and service-specific option fields
Given both envelope types are configured When saved via SafeCommitRail Then purple and blue configurations are stored as separate service records against the election-cycle job
Given a purple or blue envelope scenario is not applicable to this election When the user marks it as “Not Used” Then the service is recorded as Not Used, no quantity validation is required, and no downstream transportation events are generated for that envelope type
Given envelope configuration is committed When confirmed Then actor, timestamp, and any reason code are captured in the audit log
Given envelope proof workflow fields are tracked for the election-cycle job
When the user updates proof status values
Then Proof Sent and Proof Approved values are persisted with actor/timestamp provenance and surfaced to downstream reporting
Story 3.3: Office-Copy Service Configuration
As a client services staff member, I want to configure office-copy requirements and related production details for an election-cycle job, So that office copy preparation is tracked and visible alongside other election services.
Acceptance Criteria:
Given an election-cycle job exists When a client services user opens office-copy configuration Then they can enter office copy quantity, production details, and any special handling requirements
Given office-copy configuration is saved When committed via SafeCommitRail Then the configuration is stored against the election-cycle job and appears in the service summary view
Given office copies are not required for this election When the user marks the service as “Not Required” Then it is recorded as Not Required with no quantity validation triggered and the service is clearly labelled as excluded in the service summary
Given office-copy configuration is committed When confirmed Then actor, timestamp, and reason code are captured in the audit log
Story 3.4: Sorting Service Configuration
As a client services staff member, I want to configure sorting service options including quantity, mail class, permit or meter designation, and daily-sort flags, So that the sort team has all parameters needed to plan and execute sorting operations.
Acceptance Criteria:
Given an election-cycle job exists When a client services user opens sorting service configuration Then they can enter: sort quantity, mail class, permit or meter designation, and a daily-sort flag toggle
Given sorting configuration is saved via SafeCommitRail When committed Then all sort parameters are stored against the election-cycle job and the sort service appears as configured in the service summary
Given the daily-sort flag is enabled When configuration is saved Then the sort service is marked for daily sort operations and this flag is visible in Epic 4 milestone scheduling for sort milestone generation
Given sorting is not applicable to this election When the user marks it as “Not Used” Then sorting is excluded from service summary and no sort milestones are generated in Epic 4
Given sorting configuration is committed When confirmed Then actor, timestamp, and reason code are captured in the audit log
Given sorting configuration includes permit/meter and mail-date-sensitive settings When the user commits the configuration Then deterministic validation checks ensure daily-sort and mail-date dependencies are coherent before save is allowed
Story 3.5: Transportation Service Events
As a client services staff member, I want to record transportation-relevant service events tied to configured election services, So that transportation coordinators have accurate event data to build dispatch plans in Epic 5.
Acceptance Criteria:
Given at least one service is configured on an election-cycle job (addressing, envelopes, sorting, or office copies) When a client services user opens transportation events Then they can record pickup and delivery events linked to each configured service type
Given a transportation event is created When saved Then it stores: event type (pickup or delivery), service reference, expected date, quantity, and pickup/delivery location
Given a transportation event is linked to a service configuration When that service configuration is subsequently updated Then related transportation events are flagged as “Needs Review” rather than silently deleted or auto-updated
Given multiple services are configured When the transportation events list is viewed Then events from all service types are consolidated in a single list sortable by date and filterable by service type
Given a transportation event is saved When confirmed Then actor and timestamp are captured in the audit log and the event is available to Epic 5 report generation
Epic 4: Milestone Scheduling & Timeline Management
Operations teams can schedule and update milestone dates across all configured services, view timelines by municipality and date, detect missing or conflicting milestones before cutoffs, and assign or reassign ownership — with a persistent risk queue surfacing deadline pressure in real time.
Story 4.1: Schedule & Update Milestone Dates
As an operations user, I want to schedule and update milestone dates for all configured service events on an election-cycle job, So that each service has a date-driven execution plan tied to the election timeline.
Acceptance Criteria:
Given an election-cycle job has configured services When an operations user opens milestone scheduling Then milestone date fields are presented for each active service type (addressing, envelopes, sorting, office copies, transportation events)
Given a service was marked “Not Used” in Epic 3 When milestones are displayed Then that service's milestone fields are excluded from the scheduling view entirely
Given the daily-sort flag is set on a sorting service (Story 3.4) When sort milestones are generated Then daily sort milestone entries are created for each day within the configured sort date range
Given a milestone date is entered and saved When the job is reloaded Then the date persists and is visible in the milestone timeline view
Given a milestone date is updated When saved Then the change is captured in the audit log with actor identity and timestamp
Story 4.2: Milestone Timeline Views & CutoffRiskQueuePanel
As an operations user, I want to view milestone timelines by municipality and by date across active election-cycle jobs with at-risk and overdue items surfaced in a persistent right-pane risk queue, So that I can see the full operational schedule and identify where urgent attention is needed before cutoffs.
Acceptance Criteria:
Given active election-cycle jobs have scheduled milestones When an operations user opens the timeline view Then milestones are displayed organized by municipality with date-sorted order and filterable by date range, county, and municipality
Given the timeline view is filtered When two users apply identical filters Then both see the same deterministic sort order — no per-user result variation (UX-DR13)
Given multiple municipalities share milestones on the same date When viewed in date mode Then milestones are grouped by date then sorted by county then municipality name
Given the CutoffRiskQueuePanel renders in the right pane When it loads Then it displays prioritized urgency cards each showing: milestone name, job reference, due date countdown, severity badge (on-track/at-risk/overdue/critical), and assigned owner name (UX-DR5)
Given a milestone transitions to at-risk or overdue status When the queue re-evaluates Then it reorders with the most urgent items at the top and each severity badge is accompanied by a text label — never color alone (UX-DR12)
Given a user selects a card in the risk queue When clicked or activated via keyboard Then the center pane navigates to the relevant job and milestone without losing queue context
And the CutoffRiskQueuePanel is built as a reusable shared component — consumable by Epic 5 production tracking without modification
Story 4.3: Missing & Conflicting Milestone Detection
As an operations user, I want the system to detect missing required milestones and logically conflicting date sequences before execution cutoffs, So that I can resolve gaps before they block production operations.
Acceptance Criteria:
Given an election-cycle job has required milestones not yet scheduled When an operations user views the job or runs detection Then each missing required milestone is identified by name with its service context displayed
Given two milestone dates create a logical conflict (e.g., delivery date before pickup date, mail date before sort date) When the conflict is detected Then both conflicting milestones are flagged with a plain-language explanation identifying the conflict type and the affected dates
Given a missing or conflicting milestone is flagged When the flag is displayed Then a one-click jump link navigates directly to the scheduling field for that specific milestone
Given all required milestones are scheduled without conflicts When the job is evaluated Then it displays a “Milestones Complete” status and this clears any related items from the CutoffRiskQueuePanel
Given a user resolves flagged issues and re-evaluates When detection re-runs Then resolved items are cleared from the detection list and a Next Best Action prompt guides the user to the recommended following step (UX-DR11)
Story 4.4: Milestone Ownership & Reassignment
As an operations user, I want to assign and reassign milestone ownership and due dates across teams, So that each milestone has a clear accountable owner responsible for its timely completion.
Acceptance Criteria:
Given a milestone exists on an election-cycle job When an operations user opens milestone details Then they can assign an owner from the list of active application users and set or update the milestone due date
Given a milestone is reassigned to a new owner When saved Then the previous owner, new owner, reassigning actor identity, and timestamp are all captured in the audit log
Given a milestone due date is updated When saved Then the CutoffRiskQueuePanel re-evaluates the milestone's urgency and reorders the queue to reflect the new due date
Given a user is assigned as milestone owner When they access their role workspace Then their assigned milestones appear in their workspace prioritized by due date with severity indicators
Given a milestone is reassigned to a new owner When they next view their workspace Then newly assigned milestones are visually distinguished (e.g., “New Assignment” badge) until acknowledged
Epic 5: Production Tracking, Exception Management, Audit History & Transportation Report
Production teams can update job statuses, log and resolve exceptions, view complete timestamped status history, and see current and historical process state. Transportation coordinators receive the first external-facing report — a date-sorted dispatch report — as an early municipality proof point.
Story 5.1: Production Status Updates at Checkpoints
As a production user, I want to update election-cycle job status at defined process checkpoints, So that the team has an accurate current view of where each job stands in the production workflow.
Acceptance Criteria:
Given an election-cycle job is in production When a production user opens the status panel Then available status transitions from the current checkpoint are presented (e.g., In Setup → Configured → Scheduled → In Production → Complete) — only valid next states are selectable
Given a status update is initiated When the SafeCommitRail activates (reused from Story 2.5) Then it validates the transition is permitted from the current status and all required fields for the new status are present before enabling the commit action
Given a valid status transition passes all SafeCommitRail checks When the user confirms with a reason code Then the new status is saved with actor identity, timestamp, and reason code captured in the audit log
Given an invalid status transition is attempted (e.g., skipping a required checkpoint) When the SafeCommitRail evaluates Then the commit is blocked with a plain-language explanation identifying the constraint and the required preceding step
Given a status update is committed When confirmed Then the change is immediately reflected in the CutoffRiskQueuePanel and milestone timeline views
Story 5.2: Exception & Blocker Logging
As a support or operations user, I want to log exceptions, blockers, and resolution notes against an election-cycle job, So that issues are tracked with accountability and visible to all relevant team members without leaving the operations workspace.
Acceptance Criteria:
Given an election-cycle job exists When a user creates an exception record Then they can enter: exception type, description, blocking impact, assigned owner, and due-by timestamp
Given an exception is logged with blocking impact When saved Then it appears in the CutoffRiskQueuePanel with a severity badge matching its impact level (reused from Epic 4, UX-DR5)
Given an open exception passes its due-by timestamp without resolution When the CutoffRiskQueuePanel evaluates urgency Then the exception's severity escalates automatically and the updated priority is reflected immediately in the queue ordering
Given an exception is resolved When the resolution note is saved Then the exception status transitions to Resolved with resolution note, resolving actor identity, and timestamp captured in the audit log
And exception records are available as input to the BlockerResolutionDrawer in Story 5.3 for in-context resolution workflows
Story 5.3: Blocked-Job Resolution with BlockerResolutionDrawer
As a production or operations user, I want to resolve blocked election-cycle jobs through an in-context recovery drawer without losing my current workspace position, So that I can address blockers quickly and maintain operational momentum under deadline pressure.
Acceptance Criteria:
Given a blocked job or open exception exists When a user opens the BlockerResolutionDrawer from the risk queue, a blocked status indicator, or a validation failure Then a right-side drawer opens in context — the user's current workspace view remains visible and no navigation occurs
Given the BlockerResolutionDrawer is open When displayed Then it shows: blocker details, dependency links to affected milestones, assignee field, due-by date control, resolution note field, and save and escalate actions (UX-DR6)
Given a user updates assignment and due-by date and saves When committed Then the exception history is updated with the new values, actor identity, and timestamp, and the drawer closes returning keyboard focus to the previous context
Given a blocker cannot be resolved in the available time When the user selects Escalate Then the exception's severity escalates in the CutoffRiskQueuePanel and the escalation event is appended to the exception audit trail
Given the drawer has unsaved changes When the user attempts to close it Then a confirmation prompt prevents accidental data loss before dismissal
And the BlockerResolutionDrawer is built as a reusable shared component with standard and escalation mode variants — consumable across all operational views without modification (UX-DR6)
Story 5.4: Status Transition History & ProvenanceTimelinePanel
As any operational user, I want to view a complete timestamped history of status transitions and key operational events on an election-cycle job, So that I can trace what changed, when, by whom, and why at any point in the job lifecycle.
Acceptance Criteria:
Given any status transition or key operational event occurs on an election-cycle job When committed Then previous value, new value, actor identity, timestamp, event type, and reason code are appended to the immutable event history
Given the ProvenanceTimelinePanel is opened for a job When loaded Then it displays a chronological timeline of events each showing: actor, timestamp, event type, changed field, previous value, new value, and reason code (UX-DR8)
Given a user filters the timeline by event type (status change, exception logged, milestone updated) When the filter is applied Then the timeline updates deterministically showing only matching events in the same chronological order
Given the timeline renders event type indicators When displayed Then each event type is conveyed with both a text label and an icon — never color alone (UX-DR12)
And the ProvenanceTimelinePanel is built as a reusable shared component with compact inline preview and full audit view variants — consumable by Epic 6 traceability features without modification (UX-DR8)
Story 5.5: Current & Historical Process State View
As any operational user, I want to view current and historical process state for a municipality's election-cycle jobs, So that I can understand where each job stands today and how it progressed through the full production lifecycle.
Acceptance Criteria:
Given a municipality has one or more election-cycle jobs When a user opens the process state view Then the current job displays: status, milestone completion summary, count of open exceptions, and last-updated timestamp
Given the current job has open blockers When the process state view is displayed Then a BlockerResolutionDrawer quick-launch action is available directly from the view for immediate in-context resolution (reused from Story 5.3)
Given prior completed election-cycle jobs exist for the municipality When the user accesses job history Then historical jobs are listed with final status, completion date, and a link to their full ProvenanceTimelinePanel audit view
Given a user navigates to a historical job's provenance timeline When the timeline loads Then the complete event history for that cycle is displayed in chronological order with all actor, timestamp, and reason code data intact
Story 5.6: Transportation Report — Date-Sorted Dispatch
As a transportation coordinator, I want to generate a date-sorted transportation report grouped by county and municipality, So that I can prepare accurate next-day and week-lookahead dispatch runs tied directly to election job milestones.
Acceptance Criteria:
Given active election-cycle jobs have transportation events and milestones scheduled When a transportation coordinator generates the report Then pickup and delivery events are aggregated from extension records joined to legacy identifiers and sorted by date then county then municipality (FR22)
Given the report is generated When displayed Then each row shows: event date, county, municipality name, event type (pickup or delivery), service type, quantity, and location
Given a filter is applied (date range, county, municipality, or service status) When the report refreshes Then only matching events are shown in the same deterministic sort order for all users applying identical filters (UX-DR13)
Given a report row has missing critical event data When detected during generation Then the row is flagged with a data-gap indicator and a direct deep-link to the source job record for correction
Given the report is ready for dispatch planning When the user exports Then a spreadsheet-compatible file (CSV or XLSX-equivalent) is generated preserving all visible columns and sort order (FR25)
And report generation completes in 30 seconds or less for standard daily and weekly date range filters under normal operating load (NFR3)
Epic 6: Full Reporting Suite, Admin Management UIs & Governance
All remaining operational reports with deterministic filtering and export. Admin management UIs complete the FR28/FR29/FR30 configuration layer from seed-only to fully managed. Support analysts get report-to-source traceability and data correction tools. Parity governance closes the brownfield migration with a defined sunset gate.
Story 6.1: Sorting Report by Municipality
As an operations user, I want to generate a sorting report organized by municipality for all election-cycle jobs with sorting enabled, So that the sort team can review all sorting requirements per municipality in a single operational view.
Acceptance Criteria:
Given active election-cycle jobs have sorting services configured and enabled When a user generates the sorting report by municipality Then all jobs with sorting enabled are aggregated and displayed grouped by municipality name
Given the report is generated When displayed Then each row shows: municipality name, jurisdiction code, sort quantity, mail class, permit or meter designation, daily-sort flag, and current job status
Given filters are applied (date range, county, service status) When the report refreshes Then only matching jobs are shown in deterministic municipality-sorted order
Given the report is exported When downloaded Then a spreadsheet-compatible file is generated preserving all visible columns, sort order, and active filter context (FR25)
And report generation completes in 30 seconds or less for standard filter ranges (NFR3)
Story 6.2: Sorting Report by Mail Date
As an operations user, I want to generate a sorting report organized chronologically by mail date for all election-cycle jobs with sorting enabled, So that the sort team can plan operations across all active municipalities in date-priority order.
Acceptance Criteria:
Given active election-cycle jobs have sorting enabled and mail dates scheduled When a user generates the sorting report by mail date Then jobs are displayed sorted by mail date ascending then by municipality name within each date group
Given the report is generated When displayed Then each row shows: mail date, municipality name, sort quantity, mail class, permit or meter designation, and daily-sort flag
Given multiple municipalities share the same mail date When grouped Then they appear together under the shared date header in municipality-sorted order
Given the report is exported When downloaded Then a spreadsheet-compatible file is generated preserving all columns, grouping, and sort order (FR25)
And report generation completes in 30 seconds or less for standard filter ranges (NFR3)
Story 6.3: Report Filtering, Saved Presets & Unified Export
As an operations user, I want to apply consistent filters across all operational reports and save presets for recurring use, So that I can reproduce the same report view instantly without re-entering filter criteria each session.
Acceptance Criteria:
Given any operational report is open (transportation, sorting by municipality, sorting by mail date) When a user applies filters (date range, municipality, county, service status) Then only matching records are shown in deterministic sort order identical for all users with the same active filters (UX-DR13, FR26)
Given a user configures a useful filter set When they save it as a named preset Then the preset is stored per user role and available from a preset selector dropdown in future sessions
Given a saved preset is selected When applied Then all filter values are restored exactly and the report regenerates with the same deterministic output
Given any report is ready for export When the user triggers export Then a spreadsheet-compatible file (CSV or XLSX-equivalent) is generated preserving column labels, sort order, grouping, and all applied filter values (FR25)
And exported files preserve required field parity for existing operational consumers — column names and data types match the legacy report output schema where mandated (NFR14)
Story 6.4: Report-to-Source Traceability
As a support analyst, I want to trace any report value back to its source records across legacy and extension datasets, So that I can investigate and resolve report discrepancies with full visibility into how the value was produced.
Acceptance Criteria:
Given a report row or field value is under investigation When a support analyst activates the trace action for that row Then the system displays the source extension record(s) and legacy join record(s) that produced the value, including join path and field-level mapping (FR33)
Given the trace is opened When displayed using the ProvenanceTimelinePanel (reused from Story 5.4) Then source record identifiers, field values, last-updated actor, timestamp, and join keys are all visible in the audit view
Given a discrepancy exists between a report output value and its source record When the trace is reviewed Then the analyst can identify the exact field, record, and value mismatch causing the discrepancy
Given a trace is run on any operational report When the result is shown Then traceability is available for transportation reports and all sorting reports — not limited to a single report type
Given a traced value originated from spreadsheet import When trace details are expanded Then source file identifier, source row reference, import timestamp, and importing user are visible in the provenance panel
Story 6.5: Extension-Layer Data Correction
As an authorized support or admin user, I want to correct erroneous extension-layer data with a mandatory reason and full audit trail, So that data issues can be resolved with accountability while preserving immutable legacy schema integrity.
Acceptance Criteria:
Given an extension record contains erroneous data When an authorized user (Support or Admin role) opens the correction workflow Then they can edit the extension record fields with a mandatory correction reason field that must be completed before saving
Given a correction is submitted When saved Then the corrected values, previous values, correction reason, actor identity, and timestamp are all captured in the audit log as an immutable correction event (FR34)
Given the correction workflow displays a record that joins to legacy data When legacy fields are shown Then they are rendered read-only with no edit affordance — no modification path to legacy tables exists in this workflow (NFR12)
Given a user without the Support or Admin role attempts to access the correction workflow When they navigate to it Then they receive 403 Forbidden and the unauthorized access attempt is captured in the audit log (NFR6)
Given a correction saves successfully When the corrected record is used in a subsequent report Then the report reflects the corrected value and the correction event is visible via report-to-source traceability (Story 6.4)
Story 6.6: Admin Configuration UIs — Reference Values, Required-Field Rules & Escalation Rules
As an administrator, I want management interfaces for extension-layer reference values, required-field rules, and escalation rule configurations, So that operational defaults established in Epic 1 can be updated as business needs evolve without requiring code changes.
Acceptance Criteria:
Given an administrator navigates to reference value management When the UI loads Then they can view, add, edit, and deactivate status sets, service template defaults, and other extension-layer reference values across all operational domains (FR28)
Given a reference value is updated When saved Then the change is immediately available to all operational workflows and captured in the audit log with actor and timestamp
Given an administrator navigates to required-field rules management When the UI loads Then they can view and modify which fields are required for election-cycle readiness checks and set effective dates for rule changes (FR29)
Given an administrator navigates to escalation rule configuration When the UI loads Then they can configure notification triggers, escalation thresholds, due-date offsets, and recipient rules for missed or at-risk milestones (FR30)
Given any admin configuration change is about to be committed When the SafeCommitRail activates (reused from Story 2.5) Then it validates the change does not break active workflows or produce orphaned records before enabling the save action
Story 6.7: Parity Governance & Legacy Report Sunset
As an operations administrator and parity governance owner, I want a structured parity validation workflow with a defined sunset checklist, So that the legacy report stack can be formally decommissioned only after proven equivalence is documented and signed off.
Acceptance Criteria:
Given modern reports are generating output alongside legacy reports When a parity validation run is initiated Then modern and legacy report outputs are compared field-by-field across a defined validation set of active election jobs and a comparison report is produced
Given a parity comparison report is generated When discrepancies are found Then the report identifies: affected report type, field name, legacy value, modern value, discrepancy severity, and an assignable owner field for triage
Given a discrepancy is assigned to an owner When the owner resolves it and updates closure status Then the resolution is recorded with actor identity, timestamp, and resolution notes in the parity audit trail
Given parity validation shows zero critical discrepancies across the full validation set When reviewed by the named parity governance owner Then the sunset criteria checklist becomes available for formal sign-off review
Given all sunset criteria are satisfied (zero critical discrepancies, named parity owner sign-off, municipality client acknowledgment) When the final gate is passed and recorded Then the legacy report stack is eligible for decommission and the gate completion event is captured with all sign-off actors and timestamps
And the named parity governance owner is a required system configuration field — parity validation cannot be initiated until this field is populated
Story 6.8: Source Reconciliation & Data Quality Queue
As a support analyst or operations owner, I want a reconciliation queue for imported source data versus report output, So that data mismatches are triaged with clear ownership before they impact operational decisions.
Acceptance Criteria:
Given imported spreadsheet-origin records and report outputs exist When a reconciliation run is executed Then mismatches are surfaced with report type, affected field, source value, system value, and severity
Given a mismatch is identified When triage begins Then an owner can be assigned with due date, status, and resolution notes tracked in an auditable trail
Given a reconciliation issue is resolved When the resolution is saved Then closure metadata (actor, timestamp, reason) is captured and linked to report traceability records
Given unresolved high-severity mismatches remain When operational export is attempted for affected scope Then the system displays a blocking warning with a direct link to the reconciliation queue