# Traceability Matrix

## Purpose

Provide a consolidated requirements-to-design traceability matrix for the Odin to Lunchtab Balance Transfer project.

## Inputs

- `traceability/requirements-design-traceability.md`
- `traceability/design-decision-map.md`
- `traceability/coverage-and-gap-analysis.md`
- Repository source code, tests, and README evidence cited by those artifacts.

## BA Activities

- Manage requirements lifecycle.
- Analyze requirements and define design options.
- Evaluate solution.

## Techniques Applied

- Traceability matrix: links requirements, rules, design, tests, risks, and gaps.
- Requirements analysis: organizes observed capabilities into requirement statements.
- Risk analysis: exposes high-control areas needing validation.

## Matrix

| ID | Type | Statement | Evidence | Related Rule | Related Requirement | Related Design | Related Test | Related Risk or Gap | Status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| TR-001 | Requirement | Transfer balances into a copy of Lunchtab users without mutating source files. | README; `workflow.py`; `managed.py` | BR-001 | REQ-001 | DES-001, DES-010 | TEST-001, TEST-002, TEST-017 | RISK-001, RISK-006 | Draft |
| TR-002 | Requirement | Preserve Lunchtab rows and insert `OdinBalanceAmount` after `DefaultFamilyBalanceAmount`. | README; `workflow.py` | BR-002 | REQ-002 | DES-001 | TEST-002, TEST-009 | RISK-001 | Draft |
| TR-003 | Requirement | Quarantine unsafe, ambiguous, malformed, duplicate, stale, unmatched, or name-validation-failed records. | README; `workflow.py` | BR-003, BR-004, BR-005 | REQ-003 | DES-002, DES-003, DES-004 | TEST-003, TEST-004, TEST-011 | GAP-002 | Draft |
| TR-004 | Requirement | Support configurable venue matching profiles. | README; `profiles.py`; `profile_gui.py`; `workflow.py` | BR-006 | REQ-004 | DES-003, DES-005 | TEST-010, TEST-012, TEST-013 | GAP-008 | Draft |
| TR-005 | Requirement | Require name validation for identifier and crosswalk matches. | `workflow.py` | BR-004 | REQ-005 | DES-002, DES-003 | TEST-003, TEST-011, TEST-012 | RISK-002 | Draft |
| TR-006 | Requirement | Provide accepted-match audit evidence without polluting import CSV. | README; `workflow.py` | BR-008 | REQ-006 | DES-006, DES-010 | TEST-009 | RISK-004 | Draft |
| TR-007 | Requirement | Reconcile valid Odin source dollars to matched plus valid exception dollars. | `audit_control.py`; `workflow.py` | BR-007 | REQ-007 | DES-006 | TEST-005 | RISK-004, RISK-005 | Draft |
| TR-008 | Requirement | Produce manual-review exceptions and candidate-match artifacts. | README; `workflow.py`; `exception_candidates.py` | BR-003, BR-009 | REQ-008 | DES-004, DES-007 | TEST-014, TEST-015 | GAP-002, GAP-003 | Draft |
| TR-009 | Requirement | Candidate viewer supports filters, actionable selection, proposed transfer copy, and decision audit. | README; `candidate_viewer.py` | BR-009, BR-010 | REQ-009 | DES-007 | TEST-016 | GAP-003 | Draft |
| TR-010 | Requirement | Manual reconciliation review classifies edited transfer changes and blocks invalid manual amounts. | README; `manual_reconciliation.py` | BR-011 | REQ-010 | DES-008 | TEST-006, TEST-007, TEST-008 | RISK-003, RISK-005 | Draft |
| TR-011 | Requirement | InitialBalances validates transfer and target schema before writing import output. | README; `initial_balances.py` | BR-012 | REQ-011 | DES-009 | TEST-018, TEST-019 | RISK-005 | Draft |
| TR-012 | Requirement | InitialBalances aggregates populated balances by family code and preserves target rows. | README; `initial_balances.py` | BR-013, BR-014 | REQ-012 | DES-009 | TEST-018 | RISK-001, RISK-005 | Draft |
| TR-013 | Requirement | Blocked InitialBalances runs omit processed import but retain audit evidence. | README; `initial_balances.py` | BR-015 | REQ-013 | DES-009, DES-010 | TEST-019, TEST-020 | GAP-004 | Draft |
| TR-014 | Requirement | Managed workflows publish complete timestamped run folders atomically. | `managed.py`; `manual_reconciliation.py`; `initial_balances.py` | BR-016 | REQ-014 | DES-010 | TEST-017, TEST-020 | RISK-006 | Draft |
| TR-015 | Requirement | Manifests record filenames, hashes, summary counts, profile/audit details, and generated artifact hashes without row-level private data. | README; manifest builders | BR-017 | REQ-015 | DES-010 | TEST-017, TEST-020, TEST-023 | GAP-005 | Draft |
| TR-016 | Requirement | GUI controllers enforce validation before processing and invalidate stale results. | `gui_controller.py` | BR-018 | REQ-016 | DES-011 | TEST-021 | GAP-006 | Draft |
| TR-017 | Requirement | CSV reader safely accepts supported encodings and rejects unsafe content. | README; `workflow.py` | BR-019 | REQ-017 | DES-012 | TEST-022 | RISK-008 | Draft |
| TR-018 | Requirement | Sandbox generator produces deterministic synthetic packs and verifies production workflows. | README; `sandbox_data.py`; `sandbox_gui.py` | BR-020 | REQ-018 | DES-013 | TEST-023 | RISK-009 | Draft |
| TR-019 | Requirement | Windows packaging supports per-user installer and release checks. | README; `packaging/installer.iss`; `scripts/build-release.ps1` | BR-021 | REQ-019 | DES-014 | TEST-024 | GAP-007 | Draft |
| TR-020 | Gap | Requirements are not yet stakeholder-approved. | Requirements review | N/A | All | All | N/A | GAP-001 | Open |
| TR-021 | Gap | Manual-review exclusion policy for `no Lunchtab match` needs confirmation. | README; `workflow.py` | BR-003 | REQ-003, REQ-008 | DES-004 | TEST-002 | GAP-002 | Open |
| TR-022 | Gap | Candidate score thresholds need operational validation. | `exception_candidates.py`; tests | BR-009 | REQ-008, REQ-009 | DES-007 | TEST-014, TEST-016 | GAP-003 | Open |
| TR-023 | Gap | All-or-nothing InitialBalances blocking needs explicit policy approval. | README; `initial_balances.py` | BR-015 | REQ-013 | DES-009 | TEST-019, TEST-020 | GAP-004 | Open |
| TR-024 | Gap | Manifest privacy controls need data-policy validation. | README; manifest builders | BR-017 | REQ-015 | DES-010 | TEST-017, TEST-020 | GAP-005 | Open |
| TR-025 | Gap | Release packaging needs clean-machine acceptance evidence. | README release checklist; packaging tests | BR-021 | REQ-019 | DES-014 | TEST-024 | GAP-007 | Open |

## Traceability

The matrix links requirement statements to business rules, implementation design, test evidence, and unresolved gaps. Each requirement remains `Draft` pending stakeholder approval.

## Validation Needs

- Assign owner and approval status for each REQ item.
- Decide whether gaps should become formal requirements, risks, or action items.
- Revisit this matrix after stakeholder review and update statuses.