Campaign_Tracker/_bmad-output/planning-artifacts/sprint-change-proposal-2026-05-05.md

Sprint Change Proposal

1) Issue Summary

• Trigger: A late source document was added on 2026-05-05: Google Sheet AUGUST 2026 PRIMARY Ballot Envelope Imprinting and Tracking Scheduled .xlsx.
• Context: Current planning artifacts were built from Access schema + initial client database plan artifacts and do not explicitly include this new spreadsheet as an input.
• Evidence:
  • The added sheet includes operational columns not explicitly modeled as named requirements yet (for example: Proof Sent, Proof Approved, Round Trip Y/N, Permit/Meter, MailDate, NP/STD, CRID, contact workflow fields).
  • Existing PRD covers these areas only at a generic level (for example FR6 key dates, FR12 sorting options, FR22-FR26 reporting).

2) Impact Analysis

Epic Impact

• Epic 2 (Election-Cycle Job Creation & Planning): impacted
  • Reason: new source has key date and readiness fields that should be importable or reconcilable.
• Epic 3 (Service Configuration): impacted
  • Reason: envelope, sorting, and tracking detail in the sheet exceeds currently explicit field coverage.
• Epic 5/6 (Reporting): impacted
  • Reason: report parity and traceability need source-to-field reconciliation for spreadsheet-origin values.
• Epic 1 and Epic 4: low-to-medium indirect impact
  • Reason: join-key validation, role controls, and milestone validation rules should include imported sheet data.

Story Impact

• Existing stories needing updates:
  • Story 2.3 (Election-Cycle Key Dates)
  • Story 3.2 (Envelope Service Configuration)
  • Story 3.4 (Sorting Service Configuration)
  • Story 5.6 (Transportation Report)
  • Story 6.4 (Report-to-Source Traceability)
• New stories recommended:
  • Story 2.6 (new): Spreadsheet Import & Column Mapping
  • Story 6.8 (new): Source Reconciliation & Data Quality Queue

Artifact Conflicts

• PRD: requires explicit requirements for spreadsheet import/mapping/provenance and contact/proof workflow coverage.
• Architecture: requires ingestion boundary, mapping registry, validation pipeline, and provenance storage design.
• UX: requires import/review/reconciliation flow and role-safe handling of contact fields.

Technical Impact

• Add ingestion flow (manual upload or Google Sheet export import path).
• Add validation and mapping rules for jurisdiction join-key matching.
• Add provenance metadata and reconciliation flags.
• Add role-based field masking/visibility for contact data.

3) Recommended Approach

• Selected approach: Hybrid (Option 1 Direct Adjustment + Option 3 PRD MVP Review)
• Why:
  • We can preserve current MVP direction and timeline by adjusting existing epics/stories.
  • We should still update PRD scope language so new source-derived capabilities are explicitly testable.
• Rollback: Not recommended (no implementation rollback value at current stage).
• Estimated effort: Medium
• Risk: Medium
• Timeline impact: +1 sprint buffer unless import/reconciliation is phased (recommended phase-in).

4) Detailed Change Proposals

PRD Changes

Change P1
Section: Frontmatter inputDocuments

OLD:

• Initial Description.txt
• Initial Documents/Access_Schema.txt
• Initial Documents/Client Database Plan.xlsx
• _bmad-output/planning-artifacts/client-database-plan-extract.txt

NEW:

• Keep existing entries
• Add: https://docs.google.com/spreadsheets/d/1l77Hvw-vmdE8FnByxr7Ink4zMtp66iAc/edit?gid=1537818588
• Add: docs/source-2026-08-primary-ballot-envelope-tracking.md

Rationale: preserve auditability of late requirements input.

Change P2
Section: Functional Requirements (append after FR34)

OLD:

• FR34: Authorized users can correct extension-layer data issues without direct edits to immutable legacy tables.

NEW:

• FR35: Authorized operations users can import election-cycle operational schedule data from approved spreadsheet templates, map rows to legacy-linked municipality identifiers, and stage changes for review before publish.
• FR36: Authorized users can manage proofing/contact workflow status (Proof Sent, Proof Approved, contact assignments) with full audit history and role-based visibility.

Rationale: explicitly cover newly introduced operational fields and workflow responsibilities.

Change P3
Section: Non-Functional Requirements (append)

OLD:

• No explicit ingestion provenance/validation SLA.

NEW:

• NFR18: 100% of imported spreadsheet rows must store provenance metadata (source file identifier, row reference, import timestamp, importing user).
• NFR19: Import validation must detect join-key mismatches and required-field gaps before publish, with deterministic error output and zero silent drops.

Rationale: prevents hidden data drift and supports regulated traceability expectations.

Epics and Stories Changes

Change E1
Artifact: epics.md
Section: Epic 2

OLD:

• Epic 2 ends at Story 2.5.

NEW:

• Add Story 2.6: Spreadsheet Import & Column Mapping
  • Parse approved sheet template columns
  • Map to extension-layer fields
  • Validate ID/JCode/JurisCode/KitID match rules
  • Stage records and show publish-ready status

Rationale: early ingestion capability prevents manual re-entry and late-cycle errors.

Change E2
Artifact: epics.md
Section: Epic 3 Story 3.2 and Story 3.4 acceptance criteria

OLD:

• Covers envelope and sorting at a generic configuration level.

NEW:

• Add acceptance criteria for explicit support of fields derived from the new source where applicable:
  • proofing status fields
  • daily sort behavior tied to mail date consistency checks
  • permit/meter and related classification flags

Rationale: aligns service-configuration behavior with real operational source detail.

Change E3
Artifact: epics.md
Section: Epic 6

OLD:

• Story 6.4 covers report-to-source traceability generally.

NEW:

• Add Story 6.8: Source Reconciliation & Data Quality Queue
  • Compare imported sheet values versus extension/legacy-joined report outputs
  • Surface mismatches with owner assignment and resolution status

Rationale: operationalizes parity controls for the newly added source.

Architecture Changes

Change A1
Artifact: architecture.md
Section: Integration/Data Flow

OLD:

• No explicit spreadsheet ingestion boundary.

NEW:

• Add import adapter boundary:
  • file intake
  • template-version detection
  • mapping registry
  • validation engine
  • staging store
  • publish service

Rationale: isolates import volatility and protects core domain model integrity.

Change A2
Artifact: architecture.md
Section: Data Integrity & Audit

OLD:

• General discrepancy triage is described.

NEW:

• Add explicit provenance schema and reconciliation event model for spreadsheet-origin rows.

Rationale: makes traceability implementation-ready, not implicit.

UX Changes

Change U1
Artifact: ux-design-specification.md
Section: Operational Workflows

OLD:

• No dedicated import/reconciliation user flow.

NEW:

• Add ImportReviewWorkspace flow:
  • upload/import source
  • mapping preview
  • validation issues
  • staged rows
  • publish confirmation

Rationale: required for safe operational adoption without hidden transformations.

Change U2
Artifact: ux-design-specification.md
Section: Role behavior

OLD:

• generic role-based workflow language.

NEW:

• Add explicit contact-data visibility rules and edit permissions by role.

Rationale: protects sensitive contact data and reduces accidental overexposure.

5) Implementation Handoff

• Scope classification: Moderate
• Handoff recipients:
  • Product Owner / Scrum Master: update backlog and story sequencing
  • Architect: define ingestion + provenance + reconciliation design additions
  • Dev team: implement new/updated stories after readiness check
• Success criteria:
  • Planning artifacts explicitly include the new source
  • Import/reconciliation behavior is defined with acceptance criteria
  • Readiness check passes with updated PRD/epics/architecture/UX alignment

6) Checklist Status

Section 1: Trigger and Context

• 1.1 Trigger story identified: Done (trigger captured as late planning input change; implementation entry point added as Story 2.6)
• 1.2 Problem defined: Done
• 1.3 Evidence gathered: Done

Section 2: Epic Impact

• 2.1 Current epic impact assessed: Done
• 2.2 Epic-level changes identified: Done
• 2.3 Remaining epics reviewed: Done
• 2.4 Future epic invalidation/new epic need: Done
• 2.5 Resequencing/priority check: Done

Section 3: Artifact Impact

• 3.1 PRD conflicts reviewed: Done
• 3.2 Architecture conflicts reviewed: Done
• 3.3 UX conflicts reviewed: Done
• 3.4 Other artifacts reviewed: Done

Section 4: Path Forward

• 4.1 Option 1 Direct Adjustment: Viable
• 4.2 Option 2 Rollback: Not viable
• 4.3 Option 3 MVP Review: Viable
• 4.4 Recommendation selected: Done (Hybrid)

Section 5: Proposal Components

• 5.1 Issue summary: Done
• 5.2 Epic + artifact adjustments: Done
• 5.3 Recommendation rationale: Done
• 5.4 MVP impact + action plan: Done
• 5.5 Handoff plan: Done

Section 6: Final Review and Handoff

• 6.1 Checklist completeness: Done
• 6.2 Proposal accuracy: Done
• 6.3 User approval obtained: Done (approved by user on 2026-05-05)
• 6.4 sprint-status update: [N/A] Skip (no sprint-status artifact found in implementation artifacts)
• 6.5 Next steps confirmed: Done (route to implementation-readiness validation, then backlog execution)

---

Sprint Change Proposal — Change 2: Logout Session Destruction

Date: 2026-05-05 | SM: Bob | Scope: Minor

1) Issue Summary

• Trigger: Logout capability was omitted from the authentication stories (1.2 and 1.3), discovered during sprint review while stories are in review status.
• Context: Without calling the Keycloak end_session_endpoint, the server-side session remains alive after client-side token removal — a security gap, not a cosmetic omission.
• Evidence: OIDC RP-initiated logout requires an explicit end-session call; NFR7 requires auth events (including logout) to be logged within 5 seconds.

2) Impact Analysis

Epic Impact

• Epic 1 (in-progress): minor addition to two review-status stories. No timeline impact.

Story Impact

Story	Status	Change
1.3 — Keycloak OIDC Integration	review	Add ACs 6–8: end-session endpoint call, SESSION_LOGOUT audit event, graceful failure handling
1.2 — Workspace Shell & Ant Design Foundation	review	Add ACs 7–8: accessible logout control in shell header, Popconfirm guard

Artifact Conflicts

Artifact	Change
PRD NFR7	Clarified “authentication events” explicitly includes logout
Architecture	Added OIDC Logout / End-Session section to 2026-05-05 addendum
UX Design Spec	Added logout control placement spec to 2026-05-05 addendum

Technical Impact

• Backend: new /api/auth/logout endpoint calling Keycloak end_session_endpoint with id_token_hint; SESSION_LOGOUT audit event via shared audit service
• Frontend: logout handler in workspace shell header (Ant Design Avatar/Dropdown user menu), Popconfirm guard, token storage clear, redirect to login
• No database schema changes; no legacy table impact

3) Recommended Approach

Option 1 — Direct Adjustment. Both affected stories are in review, not done. Optimal correction window. Effort: Low. Risk: Low. Timeline impact: Zero.

4) Detailed Change Proposals

Applied directly to artifact files — see Change Proposals in the analysis above for before/after text.

Files updated:

• _bmad-output/implementation-artifacts/1-3-keycloak-realm-configuration-oidc-integration.md — ACs 6–8 added, task entries added, change log updated
• _bmad-output/implementation-artifacts/1-2-workspace-shell-ant-design-foundation.md — ACs 7–8 added, task entries added, change log updated
• _bmad-output/planning-artifacts/prd.md — NFR7 clarified
• _bmad-output/planning-artifacts/architecture.md — OIDC end-session section added
• _bmad-output/planning-artifacts/ux-design-specification.md — logout control placement spec added

5) Implementation Handoff

• Scope: Minor — development team handles directly
• Handoff to: Dev team (Amelia — bmad-agent-dev) for Stories 1.2 and 1.3
• Success criteria: Story 1.3 implements end_session_endpoint call + SESSION_LOGOUT audit event; Story 1.2 implements accessible logout control with Popconfirm; neither story marked done until logout ACs pass review

6) Checklist Status

• 1.1–1.3 Trigger & context: Done
• 2.1–2.5 Epic impact: Done
• 3.1–3.4 Artifact conflicts: Done
• 4.1–4.4 Path forward: Done (Option 1 selected)
• 5.1–5.5 Proposal components: Done
• 6.1 Checklist completeness: Done
• 6.2 Proposal accuracy: Done
• 6.3 User approval: Done (approved by Daniel on 2026-05-05)
• 6.4 sprint-status.yaml: [N/A] No status changes required — stories remain review
• 6.5 Next steps: Done — dev team resumes Stories 1.2 and 1.3 with new ACs