# Requirements and Design Traceability

## Purpose

Provide a business analyst trace from business need to implemented design, verification evidence, risks, and validation needs for the Odin to Lunchtab Balance Transfer project.

## Inputs

- User request: "business analyst deliverable for requirements and design tracability" with heavy alignment.
- Product documentation: `README.md`.
- Core implementation: `src/odin_lunchtab/workflow.py`, `managed.py`, `manual_reconciliation.py`, `initial_balances.py`, `profiles.py`, `exception_candidates.py`, `candidate_viewer.py`, `gui_controller.py`, `run_reports.py`, `audit_control.py`.
- Verification evidence: `tests/test_workflow.py`, `tests/test_managed.py`, `tests/test_manual_reconciliation.py`, `tests/test_initial_balances.py`, `tests/test_matching_profiles.py`, `tests/test_exception_candidates.py`, `tests/test_candidate_viewer.py`, `tests/test_gui_controller.py`, `tests/test_sandbox_data.py`.

## BA Activities

- Plan and monitor analysis work: scoped this artifact to current implementation traceability, not solution redesign.
- Elicit and collaborate: captured the user-provided need for requirements and design traceability.
- Manage requirements lifecycle: assigned stable requirement, design, rule, risk, and test-reference IDs.
- Analyze requirements and define design options: mapped observable behavior to design choices and validation needs.
- Evaluate solution: compared implemented behavior and tests against trace coverage.

## Techniques Applied

- Document analysis: used README, code, and tests as evidence.
- Interface analysis: traced file inputs, CSV/XLSX contracts, generated artifacts, manifests, and GUI controller states.
- Business rules analysis: identified validation, matching, quarantine, audit, and publication rules.
- Data modeling: traced key data objects such as Odin records, Lunchtab users, transfer rows, InitialBalances rows, profiles, candidates, manifests, and audit summaries.
- Acceptance criteria: derived testable criteria from observed tests and business rules.
- Risk analysis: linked high-risk operational behaviors to existing controls and validation needs.

## Requirement Trace Catalog

| Requirement ID | Requirement Statement | Evidence Quality | Business Rule Links | Design Links | Verification Links | Risk Links | Lifecycle Status |
| --- | --- | --- | --- | --- | --- | --- | --- |
| REQ-001 | The system shall transfer Odin account balances into a copy of the Lunchtab users export without changing the selected source files. | Observed | BR-001, BR-008 | DES-001, DES-010 | TEST-001, TEST-002, TEST-017 | RISK-001, RISK-006 | Draft |
| REQ-002 | The system shall preserve every Lunchtab user row and add `OdinBalanceAmount` immediately after `DefaultFamilyBalanceAmount`. | Observed | BR-002 | DES-001 | TEST-002, TEST-009 | RISK-001 | Draft |
| REQ-003 | The system shall quarantine unsafe, ambiguous, malformed, duplicate, stale, unmatched, or name-validation-failed records instead of guessing. | Observed | BR-003, BR-004, BR-005 | DES-002, DES-003, DES-004 | TEST-003, TEST-004, TEST-010, TEST-011, TEST-012 | RISK-002, RISK-003 | Draft |
| REQ-004 | The system shall support venue-specific matching profiles with ordered rules, transforms, crosswalks, account-type scope, email username matching, and optional name fallback. | Observed | BR-004, BR-006 | DES-003, DES-005 | TEST-010, TEST-011, TEST-012, TEST-013 | RISK-002, RISK-007 | Draft |
| REQ-005 | The system shall require surname and first/preferred-name compatibility for identifier and crosswalk matches. | Observed | BR-004 | DES-002, DES-003 | TEST-003, TEST-011, TEST-012 | RISK-002 | Draft |
| REQ-006 | The system shall provide accepted-match audit evidence for automated reconciliation without adding matching metadata to the Lunchtab import CSV. | Observed | BR-008 | DES-006, DES-010 | TEST-009, TEST-017 | RISK-004 | Draft |
| REQ-007 | The system shall provide reconciliation audit-control totals that prove valid Odin dollars equal matched dollars plus valid exception dollars. | Observed | BR-007 | DES-006 | TEST-005 | RISK-004, RISK-005 | Draft |
| REQ-008 | The system shall create manual-review exception and candidate-match artifacts for unresolved reconciliation cases. | Observed | BR-003, BR-009 | DES-004, DES-007 | TEST-014, TEST-015, TEST-016 | RISK-003 | Draft |
| REQ-009 | The candidate viewer shall support filtering, ambiguity awareness, actionable selection, proposed transfer generation, and decision audit output while preserving the original transfer file. | Observed | BR-009, BR-010 | DES-007 | TEST-016 | RISK-003, RISK-006 | Draft |
| REQ-010 | The manual reconciliation review shall compare original and edited transfer files, classify edits by severity, and block invalid manual amounts. | Observed | BR-011 | DES-008 | TEST-006, TEST-007 | RISK-003, RISK-005 | Draft |
| REQ-011 | The InitialBalances workflow shall validate the reconciled transfer and target InitialBalances schema before writing a processed import. | Observed | BR-012, BR-013 | DES-009 | TEST-018, TEST-019 | RISK-005, RISK-006 | Draft |
| REQ-012 | The InitialBalances workflow shall aggregate populated `OdinBalanceAmount` values by case-sensitive `DefaultFamilyCode`, add them to target `Amount`, and preserve target rows. | Observed | BR-013, BR-014 | DES-009 | TEST-018 | RISK-001, RISK-005 | Draft |
| REQ-013 | The InitialBalances workflow shall omit the processed import when blocking exceptions exist while still writing audit evidence. | Observed | BR-015 | DES-009, DES-010 | TEST-019, TEST-020 | RISK-005, RISK-006 | Draft |
| REQ-014 | Managed desktop workflows shall publish completed run folders atomically after staging all outputs and manifests. | Observed | BR-016 | DES-010 | TEST-017, TEST-020, TEST-023 | RISK-006 | Draft |
| REQ-015 | Run manifests shall record filenames, hashes, summary counts, profile details where applicable, generated artifact hashes, and avoid absolute source paths or row-level private data. | Observed | BR-017 | DES-010 | TEST-017, TEST-020, TEST-023 | RISK-004, RISK-008 | Draft |
| REQ-016 | The desktop GUI shall enforce validation before processing and reset prior validation/results when inputs or profiles change. | Observed | BR-018 | DES-011 | TEST-021 | RISK-003, RISK-006 | Draft |
| REQ-017 | The application shall decode supported CSV encodings safely and reject unsupported, ambiguous, or binary-looking content. | Observed | BR-019 | DES-012 | TEST-022 | RISK-008 | Draft |
| REQ-018 | The sandbox generator shall create deterministic synthetic data packs and verify production reconciliation and InitialBalances workflows. | Observed | BR-020 | DES-013 | TEST-023 | RISK-009 | Draft |
| REQ-019 | Windows packaging shall support a per-user installer, Start Menu entries, uninstall support, and release checks. | Observed | BR-021 | DES-014 | TEST-024 | RISK-010 | Draft |

## Business Rule Trace

| Rule ID | Rule Statement | Evidence | Enforcement Point | Related Requirements | Evidence Strength |
| --- | --- | --- | --- | --- | --- |
| BR-001 | Source files are selected as inputs and are not changed, moved, or deleted by the normal workflow. | `README.md`; `run_workflow`; `run_managed_workflow` writes to output/staging directories. | `src/odin_lunchtab/workflow.py`; `src/odin_lunchtab/managed.py` | REQ-001 | Strong |
| BR-002 | Transfer output preserves Lunchtab headers and inserts `OdinBalanceAmount` after `DefaultFamilyBalanceAmount`. | `workflow.py` builds `final_headers` using the position of `DefaultFamilyBalanceAmount`. | `run_workflow` | REQ-002 | Strong |
| BR-003 | Non-safe reconciliation outcomes are reported as exceptions rather than applied to transfer rows. | README exception language; `match_balances_detailed` exception branches. | `workflow.py` | REQ-003, REQ-008 | Strong |
| BR-004 | Identifier and crosswalk matches require compatible names. | `names_compatible`; crosswalk and rule branches reject failed validation. | `workflow.py` | REQ-003, REQ-005 | Strong |
| BR-005 | Duplicate Odin identities and multiple Odin records targeting one Lunchtab user are quarantined. | `odin_id_counts`; `target_counts`. | `workflow.py` | REQ-003 | Strong |
| BR-006 | Profiles support approved target fields, transforms, email-domain filters, scoped rules, crosswalks, and protected legacy default behavior. | `MatchingRule`, `TransformStep`, `CrosswalkEntry`, `MatchingProfile`, `LEGACY_DEFAULT_PROFILE`. | `profiles.py`; `workflow.py`; `profile_gui.py` | REQ-004 | Strong |
| BR-007 | Reconciliation control totals must pass before workflow completion. | `write_reconciliation_audit_control` status checked for `PASS`. | `workflow.py`; `audit_control.py` | REQ-007 | Strong |
| BR-008 | Matching metadata belongs in audit outputs, not the upload CSV. | README; accepted match audit headers; transfer schema test. | `workflow.py` | REQ-006 | Strong |
| BR-009 | Candidate reports are advisory and ranked by evidence; actionable candidates require unique transfer trace and blank current balance. | `exception_candidates.py`; `candidate_viewer.py`. | Candidate report and viewer services | REQ-008, REQ-009 | Strong |
| BR-010 | Proposed transfer creation from candidate selections writes a copy and audit; it does not mutate the original transfer. | `write_proposed_transfer_from_selections`. | `candidate_viewer.py` | REQ-009 | Strong |
| BR-011 | Manual reconciliation review distinguishes normal manual resolutions from risky or blocking edits. | Severity classification in `manual_reconciliation.py`. | `audit_manual_reconciliation` | REQ-010 | Strong |
| BR-012 | InitialBalances input must be exactly `FamilyName,FamilyCode,Amount`; reconciled transfer must include `DefaultFamilyCode` and `OdinBalanceAmount`. | `INITIAL_BALANCE_HEADERS`; `TRANSFER_HEADERS`. | `inspect_initial_balances_inputs` | REQ-011 | Strong |
| BR-013 | Populated transfer balances are aggregated by trimmed, case-sensitive family code. | `amounts_by_code`; `target_indexes`; README count definitions. | `_analyze_initial_balances` | REQ-012 | Strong |
| BR-014 | Blank InitialBalances `Amount` values are treated as zero; invalid target amounts block affected rows. | `_decimal(blank_as_zero=True)`; exception path for invalid target amount. | `_analyze_initial_balances` | REQ-012, REQ-013 | Strong |
| BR-015 | A blocked InitialBalances run writes audit, exception, control, summary, and manifest evidence but omits the processed import. | `processed = None` when blocked. | `process_initial_balances`; `run_initial_balances_workflow` | REQ-013 | Strong |
| BR-016 | Managed workflows publish output only after staging succeeds, and staging is removed after failure. | Staging directory creation, rename, and exception cleanup. | `managed.py`; `manual_reconciliation.py`; `initial_balances.py` | REQ-014 | Strong |
| BR-017 | Manifests use filenames and hashes, not absolute input paths or row-level data. | Manifest builders; README privacy statement. | `managed.py`; `manual_reconciliation.py`; `initial_balances.py` | REQ-015 | Strong |
| BR-018 | GUI state must require validation before processing and invalidate stale validation when inputs/profile change. | Controller state transitions. | `gui_controller.py` | REQ-016 | Strong |
| BR-019 | CSV decoding accepts UTF-8, Windows-1252, and BOM-marked UTF-16; unsafe text is rejected. | `_decode_csv_bytes`; `_validate_csv_text`. | `workflow.py` | REQ-017 | Strong |
| BR-020 | Sandbox data must be deterministic and must verify against production workflows. | Sandbox README and tests. | `sandbox_data.py`; `sandbox_gui.py` | REQ-018 | Strong |
| BR-021 | Windows installer supports per-user install and uninstall behavior. | README release guidance; packaging tests. | `packaging/installer.iss`; `scripts/build-release.ps1` | REQ-019 | Moderate |

## Design Element Trace

| Design ID | Design Element | Design Purpose | Evidence | Related Requirements | Evidence Strength |
| --- | --- | --- | --- | --- | --- |
| DES-001 | Transfer CSV generation with inserted `OdinBalanceAmount`. | Produce Lunchtab-compatible copy carrying Odin balances. | `workflow.py` output path and header construction. | REQ-001, REQ-002 | Strong |
| DES-002 | Name normalization and compatibility functions. | Reduce false positives while allowing preferred names, initials, accents, and punctuation variance. | `normalize_name`, `first_names_compatible`, `names_compatible`. | REQ-003, REQ-005 | Strong |
| DES-003 | Profile-driven matching engine. | Support venue-specific matching without code changes. | `profiles.py`; `match_balances_detailed`. | REQ-003, REQ-004, REQ-005 | Strong |
| DES-004 | Exception and manual-review report partitioning. | Route unresolved and high-risk cases to operational review. | `EXCEPTION_HEADERS`; `MANUAL_REVIEW_EXCEPTIONS_OUTPUT_NAME`. | REQ-003, REQ-008 | Strong |
| DES-005 | Profile editor and preview model. | Let operators configure and compare profile effects before processing. | `preview_profile`; `profile_gui.py`; tests. | REQ-004, REQ-016 | Moderate |
| DES-006 | Audit-control summaries. | Provide control-total traceability for financial reconciliation. | `audit_control.py`; `run_reports.py`. | REQ-006, REQ-007, REQ-013 | Strong |
| DES-007 | Candidate review services and viewer state. | Support guided manual resolution of exception accounts. | `exception_candidates.py`; `candidate_viewer.py`; `candidate_viewer_gui.py`. | REQ-008, REQ-009 | Strong |
| DES-008 | Manual reconciliation delta audit. | Detect whether staff edits are normal, risky, or blocking before InitialBalances. | `manual_reconciliation.py`. | REQ-010 | Strong |
| DES-009 | InitialBalances preflight and processor. | Validate, aggregate, block, audit, and produce final import. | `initial_balances.py`. | REQ-011, REQ-012, REQ-013 | Strong |
| DES-010 | Managed staging, timestamped run folders, manifests, and hashes. | Protect output integrity and support auditability. | `managed.py`; manifest builders in workflow modules. | REQ-001, REQ-014, REQ-015 | Strong |
| DES-011 | GUI controllers with explicit workflow phases. | Prevent invalid operations and stale results in desktop tabs. | `gui_controller.py`. | REQ-016 | Strong |
| DES-012 | Shared CSV reader with encoding metadata. | Make ingestion safer across Windows/Excel exports. | `read_csv_with_metadata`; `_decode_csv_bytes`. | REQ-017 | Strong |
| DES-013 | Sandbox data generator and verifier. | Provide synthetic test packs for non-live validation. | `sandbox_data.py`; `sandbox_gui.py`. | REQ-018 | Strong |
| DES-014 | Windows packaging and release scripts. | Distribute the app without requiring Python or admin install. | `packaging/installer.iss`; `scripts/build-release.ps1`; README. | REQ-019 | Moderate |

## Verification Trace

| Test ID | Verification Evidence | Protects | Notes |
| --- | --- | --- | --- |
| TEST-001 | `tests/test_managed.py::test_inspect_inputs_reports_counts` | REQ-001, REQ-016 | Validates input inspection and counts. |
| TEST-002 | `tests/test_workflow.py::test_end_to_end_writes_expected_files_columns_and_rows` | REQ-001, REQ-002, REQ-006 | Confirms key output files, columns, and rows. |
| TEST-003 | `tests/test_workflow.py::test_quarantines_conflicts_ambiguous_names_and_unmatched_records` | REQ-003, REQ-005 | Confirms ambiguous and unmatched paths. |
| TEST-004 | `tests/test_workflow.py::test_quarantines_duplicate_odin_ids` and `test_quarantines_multiple_odin_records_targeting_one_lunchtab_user` | REQ-003 | Confirms duplicate safety behavior. |
| TEST-005 | `tests/test_workflow.py::test_reconciliation_audit_control_reconciles_matched_exceptions_and_malformed` | REQ-007 | Confirms control totals and operator summary. |
| TEST-006 | `tests/test_manual_reconciliation.py::test_audit_records_manual_resolutions_without_flagging_unchanged_matches` | REQ-010 | Confirms normal manual-resolution classification. |
| TEST-007 | `tests/test_manual_reconciliation.py::test_audit_flags_risky_balance_family_and_identity_edits` and `test_audit_blocks_invalid_manual_amount` | REQ-010 | Confirms high-risk and blocking classifications. |
| TEST-008 | `tests/test_manual_reconciliation.py::test_audit_rejects_structural_mismatches` | REQ-010 | Confirms edited transfer structure must match. |
| TEST-009 | `tests/test_matching_profiles.py::test_workflow_writes_match_audit_without_changing_transfer_schema` | REQ-002, REQ-006 | Confirms metadata separation. |
| TEST-010 | `tests/test_matching_profiles.py::test_custom_rule_supports_arbitrary_mixed_identifier_and_external_id` | REQ-004 | Confirms non-barcode identifier support. |
| TEST-011 | `tests/test_matching_profiles.py::test_crosswalk_has_precedence_and_does_not_fall_through_when_stale` and `test_name_validation_is_mandatory_for_rules_and_crosswalks` | REQ-003, REQ-004, REQ-005 | Confirms crosswalk and name-validation controls. |
| TEST-012 | `tests/test_matching_profiles.py::test_email_username_matching_is_case_insensitive_and_preserves_plus_tag` and domain/malformed email tests | REQ-004, REQ-005 | Confirms email username semantics. |
| TEST-013 | `tests/test_profiles.py` profile storage, validation, migration, protection, and crosswalk tests | REQ-004 | Confirms profile lifecycle behavior. |
| TEST-014 | `tests/test_exception_candidates.py::test_candidate_report_ranks_preferred_name_and_identifier_evidence` | REQ-008 | Confirms candidate ranking evidence. |
| TEST-015 | `tests/test_exception_candidates.py::test_candidate_report_traces_candidates_to_transfer_rows` | REQ-008 | Confirms candidate transfer trace fields. |
| TEST-016 | `tests/test_candidate_viewer.py` candidate viewer filtering, grouping, selection, proposed transfer, and decision audit tests | REQ-009 | Confirms candidate review workflow behavior. |
| TEST-017 | `tests/test_managed.py::test_managed_run_publishes_complete_folder_and_private_manifest` | REQ-014, REQ-015 | Confirms managed publication and manifest privacy. |
| TEST-018 | `tests/test_initial_balances.py::test_process_aggregates_adds_and_preserves_target_rows` | REQ-011, REQ-012 | Confirms aggregation, row preservation, and audit totals. |
| TEST-019 | `tests/test_initial_balances.py::test_process_blocks_import_and_writes_exception_reports` | REQ-011, REQ-013 | Confirms blocked-run output behavior. |
| TEST-020 | `tests/test_initial_balances.py::test_managed_run_publishes_clean_or_blocked_run_atomically` | REQ-013, REQ-014, REQ-015 | Confirms clean and blocked managed publication. |
| TEST-021 | `tests/test_gui_controller.py` controller validation, invalidation, and phase tests | REQ-016 | Confirms workflow gating. |
| TEST-022 | `tests/test_workflow.py::test_read_csv_accepts_supported_encodings` and `test_read_csv_rejects_unsafe_or_unsupported_content` | REQ-017 | Confirms CSV encoding behavior. |
| TEST-023 | `tests/test_sandbox_data.py` deterministic generation, presets, manifests, and production workflow round trips | REQ-018 | Confirms synthetic test-pack behavior. |
| TEST-024 | `tests/test_packaging.py` installer and release-builder tests | REQ-019 | Confirms packaging checks at repository level. |

## Risk Trace

| Risk ID | Risk Statement | Related Requirements | Current Mitigations | Evidence Quality | Validation Need |
| --- | --- | --- | --- | --- | --- |
| RISK-001 | A balance could be applied to the wrong Lunchtab row or family. | REQ-001, REQ-002, REQ-012 | Name validation, duplicate quarantine, transfer row preservation, InitialBalances family audit. | Observed | Confirm residual risk acceptance. |
| RISK-002 | Venue-specific identifier differences could produce false matches or excessive exceptions. | REQ-003, REQ-004, REQ-005 | Matching profiles, transforms, crosswalks, preview, mandatory name validation. | Observed | Confirm profile ownership and approval process. |
| RISK-003 | Manual review could introduce incorrect or unaudited changes. | REQ-003, REQ-008, REQ-009, REQ-010, REQ-016 | Candidate audit, proposed transfer copy, manual reconciliation delta audit, GUI state gates. | Observed | Confirm manual approval workflow. |
| RISK-004 | Audit evidence may be insufficient for financial or operational review. | REQ-006, REQ-007, REQ-015 | Accepted-match audit, audit-control summaries, run summaries, manifests, hashes. | Observed | Confirm audit evidence expectations. |
| RISK-005 | Financial totals could fail to reconcile across source, exceptions, and import files. | REQ-007, REQ-010, REQ-011, REQ-012, REQ-013 | Reconciliation and InitialBalances control totals; blocked invalid/manual amounts. | Observed | Confirm control-total review ownership. |
| RISK-006 | Partial or stale outputs could be used by operators. | REQ-001, REQ-009, REQ-013, REQ-014, REQ-016 | Staging folders, timestamped run folders, original-file preservation, controller invalidation. | Observed | Confirm output retention and naming policy. |
| RISK-007 | Profile changes could alter matching behavior without business approval. | REQ-004 | Protected Legacy Default, import/export, validation, preview comparison. | Observed | Define profile change control. |
| RISK-008 | Source data privacy could be weakened by logs, manifests, or encoding failures. | REQ-015, REQ-017 | Manifests use names/hashes/counts; logs are operational; unsafe CSV content rejected. | Observed | Validate against data-handling policy. |
| RISK-009 | Synthetic testing could miss real operational edge cases. | REQ-018 | Multiple deterministic presets and production workflow verification. | Observed | Compare presets to known historical exceptions. |
| RISK-010 | Release packaging could fail in clean operator environments. | REQ-019 | Release script, installer configuration, packaging tests, README checklist. | Moderate | Capture install/upgrade/uninstall acceptance evidence. |

## Traceability

- REQ-001 through REQ-003 form the primary reconciliation safety chain: source input protection, transfer output preservation, and exception quarantine.
- REQ-004 through REQ-006 form the matching-governance chain: configurable matching, mandatory name validation, and metadata separation.
- REQ-007, REQ-014, and REQ-015 form the auditability chain: control totals, staged publication, manifests, and artifact hashes.
- REQ-008 through REQ-010 form the manual-resolution chain: candidate recommendations, selection audit, and edited-transfer audit.
- REQ-011 through REQ-013 form the InitialBalances import-control chain: schema validation, aggregation, and blocked-run evidence.
- REQ-016 through REQ-019 form the operational enablement chain: desktop state control, robust CSV ingestion, sandbox validation, and Windows packaging.

## Validation Needs

| Validation ID | Item Needing Validation | Why It Matters | Suggested Validation Owner | Current Status |
| --- | --- | --- | --- | --- |
| VAL-001 | Whether all listed requirements are business-approved, not just implementation-observed. | Code proves behavior, not stakeholder approval. | Product owner or operations lead | Unknown |
| VAL-002 | Whether `no Lunchtab match` should continue to be excluded from manual-review exceptions. | This shapes staff workload and unresolved-account handling. | Operations lead | Observed behavior, business approval unknown |
| VAL-003 | Whether candidate score thresholds and evidence weights match staff confidence expectations. | Candidate ranking affects manual review prioritization. | Reconciliation staff lead | Inferred intent |
| VAL-004 | Whether blocked InitialBalances runs should always omit processed import even for partial safe rows. | This is a strong safety posture with operational tradeoffs. | Finance/operations approver | Observed behavior, business approval unknown |
| VAL-005 | Whether manifest privacy controls satisfy internal data-handling policy. | Manifests include hashes and filenames but not row-level details. | Data owner or compliance reviewer | Unknown |
| VAL-006 | Whether Windows packaging requirements include formal install/upgrade/uninstall acceptance evidence beyond current tests. | Packaging tests inspect files but do not prove clean-machine install behavior. | Release owner | Unknown |