# 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: [x] Done (trigger captured as late planning input change; implementation entry point added as Story 2.6)
- 1.2 Problem defined: [x] Done
- 1.3 Evidence gathered: [x] Done

### Section 2: Epic Impact

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

### Section 3: Artifact Impact

- 3.1 PRD conflicts reviewed: [x] Done
- 3.2 Architecture conflicts reviewed: [x] Done
- 3.3 UX conflicts reviewed: [x] Done
- 3.4 Other artifacts reviewed: [x] Done

### Section 4: Path Forward

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

### Section 5: Proposal Components

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

### Section 6: Final Review and Handoff

- 6.1 Checklist completeness: [x] Done
- 6.2 Proposal accuracy: [x] Done
- 6.3 User approval obtained: [x] 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: [x] 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: [x] Done
- 2.1–2.5 Epic impact: [x] Done
- 3.1–3.4 Artifact conflicts: [x] Done
- 4.1–4.4 Path forward: [x] Done (Option 1 selected)
- 5.1–5.5 Proposal components: [x] Done
- 6.1 Checklist completeness: [x] Done
- 6.2 Proposal accuracy: [x] Done
- 6.3 User approval: [x] 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: [x] Done — dev team resumes Stories 1.2 and 1.3 with new ACs