13 — Traceability Matrix
Companion: 07 Epics & User Stories · 03 Microservices · Journeys · Frontend Workflows · Roadmap → Service Readiness Gates · Standards → Definition of Done
This matrix is the single backlinked view that connects business outcomes (epics, stories, journeys, workflows) to implementation surfaces (services, BFFs, frontend apps, packages) and to evidence (tests, ADRs, runbooks, audits). It is consumed by humans (review, refinement, auditing) and by AI agents (epic-spec-implementation-audit, ghasi-service-readiness-audit, commands/jira-sprint-plan.md).
The matrix is derived, not authored: it summarizes facts already established in the linked source docs. When a row conflicts with a source doc, the source doc wins and the matrix row must be regenerated.
1. Structure overview
The matrix has eight panels, each with a defined direction (rows × columns) and a defined source of truth.
| # | Panel | Source of truth | Rows | Columns |
|---|---|---|---|---|
| 1 | Epic ↔ Service | 07-epics-and-user-stories.md §2 Epic Index + 03 Microservices | 20 epics (EP-MEL-01..20) | 22 services |
| 2 | Epic ↔ Frontend Surface | 07 Epics §2 + frontend specs | 20 epics | 4 surfaces |
| 3 | Epic ↔ Journey | 07 Epics per-epic header + journeys | 20 epics | 22 journeys (J-01..J-22) |
| 4 | Epic ↔ Workflow | 07 Epics + frontend/05 workflows | 20 epics | 12 workflows (WF-01..WF-12) |
| 5 | Story ↔ Test types | 07 Epics per-story Test types | 161 stories | 8 test types |
| 6 | Story ↔ DoD section | 07 Epics per-story DoD refs + DoD | 161 stories | 8 DoD sections |
| 7 | Service ↔ Readiness phase | Service Readiness Gates §5 | 22 services | 5 phases |
| 8 | Story ↔ Wave | 07 Epics §25 | 161 stories | 3 waves |
Conventions:
✓= covered.+= covered with extension in a later wave (carry-over).-= not in scope.(o)= owning service / primary surface (when only one cell can be marked owner).
2. Panel 1 — Epic ↔ Service
The owning service is marked (o); participating services are marked ✓.
| Epic | iam | tenant | property | theme-config | staff | file-storage | notification | search-aggregation | bff-consumer | bff-tenant-booking | bff-backoffice | reservation | inventory | pricing | payment-gateway | billing | lock-integration | housekeeping | maintenance | ai-orchestrator | reporting | analytics |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| EP-MEL-01 Tenant Onboarding | ✓ | (o) | ✓ | ✓ | ✓ | ✓ | ✓ | |||||||||||||||
| EP-MEL-02 Consumer Meta Search | ✓ | ✓ | (o) | ✓ | ✓ | |||||||||||||||||
| EP-MEL-03 Tenant Booking Web/Mobile | ✓ | ✓ | (o) | ✓ | ✓ | ✓ | ✓ | |||||||||||||||
| EP-MEL-04 Reservation Lifecycle | ✓ | (o) | ✓ | ✓ | ✓ | ✓ | ||||||||||||||||
| EP-MEL-05 Payment Gateway | ✓ | ✓ | (o) | ✓ | ||||||||||||||||||
| EP-MEL-06 Front-Desk Desktop | ✓ | ✓ | (o) | ✓ | ✓ | ✓ | ✓ | |||||||||||||||
| EP-MEL-07 Housekeeping | ✓ | ✓ | ✓ | (o) | ✓ | ✓ | ||||||||||||||||
| EP-MEL-08 Maintenance | ✓ | ✓ | ✓ | (o) | ||||||||||||||||||
| EP-MEL-09 Lock & Key | ✓ | ✓ | (o) | ✓ | ||||||||||||||||||
| EP-MEL-10 Offline Sync | (o) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ||||||||||||
| EP-MEL-11 AI-Assisted Ops | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | (o) | |||||||||||||||
| EP-MEL-12 Theming Config | (o) | ✓ | ✓ | ✓ | ✓ | |||||||||||||||||
| EP-MEL-13 Reporting | ✓ | ✓ | ✓ | ✓ | ✓ | (o) | ✓ | |||||||||||||||
| EP-MEL-14 Analytics Pipeline | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | (o) | ||||||||||||
| EP-MEL-15 Notification | ✓ | (o) | ✓ | ✓ | ✓ | ✓ | ||||||||||||||||
| EP-MEL-16 File Storage | (o) | ✓ | ✓ | ✓ | ||||||||||||||||||
| EP-MEL-17 IAM & Auth | (o) | ✓ | ✓ | ✓ | ✓ | |||||||||||||||||
| EP-MEL-18 i18n & RTL | ✓ | ✓ | ✓ | ✓ | ✓ | |||||||||||||||||
| EP-MEL-19 Compliance | ✓ | ✓ | ✓ | ✓ | ✓ | |||||||||||||||||
| EP-MEL-20 Observability | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
Findings (auto-recomputed):
- Every epic has at least one
(o)owner. ✅ - Every R1 service appears as
(o)in at least one epic. ✅ analytics-serviceis(o)only for EP-MEL-14 (R2). Expected; analytics is R2.ai-orchestrator-serviceis(o)only for EP-MEL-11 (R2). Expected.staff-serviceis not(o)anywhere — embedded across multiple epics. Acceptable: staff is a foundational primitive owned by the Operations squad and consumed widely.
3. Panel 2 — Epic ↔ Frontend Surface
Surfaces: CW Consumer Web (meta) · TBW Tenant Booking Web · TBM Tenant Booking Mobile · DB Desktop Back-Office · CP Control Plane (internal admin).
| Epic | CW | TBW | TBM | DB | CP |
|---|---|---|---|---|---|
| EP-MEL-01 | ✓ | ✓ | ✓ | ||
| EP-MEL-02 | (o) | ||||
| EP-MEL-03 | (o) | (o) | |||
| EP-MEL-04 | ✓ | ✓ | ✓ | ||
| EP-MEL-05 | ✓ | ✓ | ✓ | ||
| EP-MEL-06 | (o) | ||||
| EP-MEL-07 | ✓ | (o) | |||
| EP-MEL-08 | ✓ | ✓ | |||
| EP-MEL-09 | ✓ | (o) | |||
| EP-MEL-10 | ✓ | (o) | |||
| EP-MEL-11 | ✓ | ✓ | ✓ | ||
| EP-MEL-12 | ✓ | (o) | |||
| EP-MEL-13 | (o) | ✓ | |||
| EP-MEL-14 | (o) | ||||
| EP-MEL-15 | ✓ | ✓ | ✓ | ✓ | ✓ |
| EP-MEL-16 | ✓ | ✓ | ✓ | ✓ | |
| EP-MEL-17 | ✓ | ✓ | ✓ | ✓ | |
| EP-MEL-18 | ✓ | ✓ | ✓ | ✓ | ✓ |
| EP-MEL-19 | ✓ | (o) | |||
| EP-MEL-20 | (o) |
4. Panel 3 — Epic ↔ Journey
Journeys are owned by docs/journeys/01-core-user-journeys.md. An epic can realize multiple journeys; a journey can be realized by multiple epics.
| Epic | Realizes journeys |
|---|---|
| EP-MEL-01 | J-13, J-14 |
| EP-MEL-02 | J-01 |
| EP-MEL-03 | J-02, J-03 |
| EP-MEL-04 | J-02, J-03, J-04, J-05, J-06, J-07 |
| EP-MEL-05 | J-04, J-05, J-08 |
| EP-MEL-06 | J-05, J-06, J-07, J-15 |
| EP-MEL-07 | J-15, J-16 |
| EP-MEL-08 | J-17 |
| EP-MEL-09 | J-06, J-09, J-10 |
| EP-MEL-10 | J-19, J-20 |
| EP-MEL-11 | J-11, J-21 |
| EP-MEL-12 | J-13, J-22 |
| EP-MEL-13 | J-12 |
| EP-MEL-14 | J-12, J-21 |
| EP-MEL-15 | J-04, J-08, J-15 |
| EP-MEL-16 | J-22 |
| EP-MEL-17 | J-13, J-14 |
| EP-MEL-18 | All consumer-facing journeys |
| EP-MEL-19 | J-12, J-19 |
| EP-MEL-20 | All journeys (telemetry coverage) |
Coverage check: every J-NN (1..22) has at least one realizing epic. ✅
5. Panel 4 — Epic ↔ Frontend Workflow
Workflows owned by docs/frontend/05-frontend-workflows.md. Workflow IDs WF-01 .. WF-12 correspond to the 12 sections of that document (1–12). Verify per workflow doc.
| Epic | Workflows |
|---|---|
| EP-MEL-01 | WF-11, WF-12 |
| EP-MEL-02 | WF-01 |
| EP-MEL-03 | WF-01, WF-02, WF-03 |
| EP-MEL-04 | WF-02, WF-03, WF-04 |
| EP-MEL-05 | WF-03 |
| EP-MEL-06 | WF-04, WF-05, WF-06 |
| EP-MEL-07 | WF-06, WF-07 |
| EP-MEL-08 | WF-07 |
| EP-MEL-09 | WF-04, WF-08 |
| EP-MEL-10 | WF-09 |
| EP-MEL-11 | WF-10 |
| EP-MEL-12 | WF-11 |
| EP-MEL-13 | WF-12 |
| EP-MEL-14 | WF-12 |
| EP-MEL-15 | WF-04 |
| EP-MEL-16 | WF-11 |
| EP-MEL-17 | WF-12 |
| EP-MEL-18 | All |
| EP-MEL-19 | WF-12 |
| EP-MEL-20 | All (observability is cross-cutting) |
When
frontend/05-frontend-workflows.mdsections are renumbered, this panel must be regenerated; CI lint warns on stale references.
6. Panel 5 — Story ↔ Test types (summary by epic)
Per-story rows live in the source doc; this matrix shows the count per epic of stories requiring each test type. Recomputed when stories are added.
| Epic | Unit | Integration | Contract | E2E | Offline | AI-eval | Perf | Security |
|---|---|---|---|---|---|---|---|---|
| EP-MEL-01 (12 stories) | 12 | 11 | 8 | 9 | 0 | 0 | 1 | 6 |
| EP-MEL-02 (8) | 8 | 8 | 5 | 6 | 0 | 0 | 4 | 1 |
| EP-MEL-03 (9) | 9 | 9 | 7 | 9 | 0 | 0 | 3 | 2 |
| EP-MEL-04 (12) | 12 | 12 | 9 | 12 | 0 | 0 | 4 | 3 |
| EP-MEL-05 (8) | 8 | 8 | 8 | 6 | 0 | 0 | 1 | 8 |
| EP-MEL-06 (9) | 9 | 9 | 5 | 9 | 5 | 0 | 1 | 3 |
| EP-MEL-07 (8) | 8 | 8 | 5 | 6 | 0 | 1 | 1 | 1 |
| EP-MEL-08 (6) | 6 | 6 | 3 | 4 | 0 | 0 | 0 | 0 |
| EP-MEL-09 (8) | 8 | 8 | 4 | 6 | 4 | 0 | 1 | 5 |
| EP-MEL-10 (8) | 8 | 8 | 4 | 6 | 8 | 0 | 2 | 1 |
| EP-MEL-11 (8) | 8 | 8 | 6 | 4 | 0 | 8 | 1 | 1 |
| EP-MEL-12 (6) | 6 | 6 | 4 | 4 | 0 | 0 | 0 | 1 |
| EP-MEL-13 (6) | 6 | 6 | 4 | 4 | 0 | 0 | 1 | 0 |
| EP-MEL-14 (5) | 5 | 5 | 3 | 2 | 0 | 0 | 1 | 1 |
| EP-MEL-15 (6) | 6 | 6 | 6 | 4 | 0 | 0 | 1 | 1 |
| EP-MEL-16 (4) | 4 | 4 | 2 | 2 | 0 | 0 | 0 | 2 |
| EP-MEL-17 (7) | 7 | 7 | 5 | 5 | 0 | 0 | 1 | 7 |
| EP-MEL-18 (6) | 6 | 6 | 3 | 6 | 0 | 0 | 0 | 0 |
| EP-MEL-19 (5) | 5 | 5 | 4 | 3 | 0 | 0 | 0 | 5 |
| EP-MEL-20 (16) | 16 | 14 | 5 | 8 | 0 | 0 | 8 | 4 |
| Total (161) | 161 | 154 | 100 | 115 | 17 | 9 | 30 | 52 |
Numbers above are derived from the per-story
Test typesfield. They are seeded heuristically from the master 07 doc; CI lint regenerates them when the master changes.
7. Panel 6 — Story ↔ DoD section (summary by epic)
DoD sections per standards/DEFINITION_OF_DONE.md: U Universal · D Data · A API · E Events · S Security · AI AI · F Frontend · O Observability.
| Epic | U | D | A | E | S | AI | F | O |
|---|---|---|---|---|---|---|---|---|
| EP-MEL-01 | 12 | 12 | 12 | 11 | 8 | 0 | 6 | 12 |
| EP-MEL-02 | 8 | 7 | 8 | 5 | 1 | 0 | 4 | 8 |
| EP-MEL-03 | 9 | 8 | 9 | 7 | 2 | 0 | 9 | 9 |
| EP-MEL-04 | 12 | 12 | 12 | 12 | 3 | 0 | 6 | 12 |
| EP-MEL-05 | 8 | 8 | 8 | 8 | 8 | 0 | 4 | 8 |
| EP-MEL-06 | 9 | 9 | 9 | 7 | 3 | 0 | 9 | 9 |
| EP-MEL-07 | 8 | 8 | 8 | 7 | 1 | 1 | 4 | 8 |
| EP-MEL-08 | 6 | 6 | 6 | 4 | 0 | 0 | 4 | 6 |
| EP-MEL-09 | 8 | 8 | 8 | 6 | 5 | 0 | 4 | 8 |
| EP-MEL-10 | 8 | 8 | 6 | 6 | 1 | 0 | 6 | 8 |
| EP-MEL-11 | 8 | 7 | 7 | 6 | 1 | 8 | 4 | 8 |
| EP-MEL-12 | 6 | 5 | 6 | 4 | 1 | 0 | 6 | 6 |
| EP-MEL-13 | 6 | 6 | 6 | 4 | 0 | 0 | 4 | 6 |
| EP-MEL-14 | 5 | 5 | 5 | 5 | 1 | 1 | 1 | 5 |
| EP-MEL-15 | 6 | 6 | 6 | 6 | 1 | 0 | 4 | 6 |
| EP-MEL-16 | 4 | 4 | 4 | 4 | 2 | 0 | 2 | 4 |
| EP-MEL-17 | 7 | 7 | 7 | 5 | 7 | 0 | 4 | 7 |
| EP-MEL-18 | 6 | 5 | 6 | 4 | 0 | 0 | 6 | 6 |
| EP-MEL-19 | 5 | 5 | 5 | 4 | 5 | 0 | 1 | 5 |
| EP-MEL-20 | 16 | 12 | 14 | 12 | 4 | 0 | 4 | 16 |
| Total | 161 | 148 | 156 | 127 | 54 | 10 | 96 | 161 |
Sanity: Universal and Observability apply to all stories (161). Security applies broadest to EP-MEL-01, 05, 09, 17, 19. AI applies only where AI affordances exist (EP-MEL-07, 11, 14).
8. Panel 7 — Service ↔ Readiness phase
Live readiness per roadmap/service-readiness-gates.md §5. Updated at every wave checkpoint.
| Service | Current | R1-S06 target | R1 end target | R2 end target | R3 end target |
|---|---|---|---|---|---|
| iam-service | P0 | P2 | P3 | P4 | P4 |
| tenant-service | P0 | P2 | P3 | P4 | P4 |
| property-service | P0 | P1 | P2 | P3 | P4 |
| theme-config-service | P0 | P1 | P2 | P3 | P4 |
| staff-service | P0 | P2 | P3 | P4 | P4 |
| file-storage-service | P0 | P1 | P2 | P3 | P4 |
| notification-service | P0 | P2 | P3 | P4 | P4 |
| search-aggregation-service | P0 | P1 | P2 | P3 | P4 |
| bff-consumer-service | P0 | P1 | P2 | P3 | P4 |
| bff-tenant-booking-service | P0 | P2 | P3 | P4 | P4 |
| bff-backoffice-service | P0 | P2 | P3 | P4 | P4 |
| reservation-service | P0 | P2 | P3 | P4 | P4 |
| inventory-service | P0 | P2 | P3 | P4 | P4 |
| pricing-service | P0 | P1 | P2 | P3 | P4 |
| payment-gateway-service | P0 | P2 | P3 | P4 | P4 |
| billing-service | P0 | P1 | P2 | P3 | P4 |
| lock-integration-service | P0 | P1 | P2 | P3 | P4 |
| housekeeping-service | P0 | P1 | P2 | P3 | P4 |
| maintenance-service | P0 | — | — | P2 | P3 |
| ai-orchestrator-service | P0 | — | P1 | P3 | P4 |
| reporting-service | P0 | P1 | P2 | P3 | P4 |
| analytics-service | P0 | — | — | P2 | P3 |
"—" indicates the service is not in scope for that wave checkpoint. R1 explicitly does not target P4 (see Service Readiness Gates §5).
9. Panel 8 — Story ↔ Wave
Counts per epic per wave. Source: 07 Epics §25 Wave-to-epic matrix.
| Epic | R1 | R2 carry/extend | R3 carry/extend |
|---|---|---|---|
| EP-MEL-01 | 12 | — | — |
| EP-MEL-02 | 8 | — | — |
| EP-MEL-03 | 9 | — | — |
| EP-MEL-04 | 12 | — | + OTA channel |
| EP-MEL-05 | 8 | + MFS expansion | — |
| EP-MEL-06 | 9 | + multi-property | — |
| EP-MEL-07 | 8 | — | — |
| EP-MEL-08 | — | 6 | — |
| EP-MEL-09 | 8 | + Salto, Assa Abloy production | — |
| EP-MEL-10 | 8 | — | — |
| EP-MEL-11 | — | 8 | — |
| EP-MEL-12 | 6 | + per-property overrides | — |
| EP-MEL-13 | 6 | — | + jurisdiction add-ons |
| EP-MEL-14 | — | 5 | — |
| EP-MEL-15 | 6 | — | + additional channels |
| EP-MEL-16 | 4 | — | — |
| EP-MEL-17 | 7 | + chain SSO | — |
| EP-MEL-18 | 6 | — | + new locales |
| EP-MEL-19 | 5 | — | + jurisdiction matrix |
| EP-MEL-20 | 16 | — | + multi-region |
| Story totals | 138 | +19 net new (EP-08, EP-11, EP-14) plus extensions | net new only via extensions |
10. Coverage and gap findings
The matrix's purpose is to surface gaps. Findings as of this revision:
| # | Finding | Severity | Owner | Action |
|---|---|---|---|---|
| 1 | analytics-service and ai-orchestrator-service are R2-only — no R1 stories. | Info | AI & Analytics squad | Confirmed by wave plan; no action. |
| 2 | staff-service is not the (o) of any epic but participates in 5. | Low | Operations squad | Acceptable; clarify in component README that staff is a primitive. |
| 3 | EP-MEL-08 Maintenance has 0 R1 stories. | Info | Operations squad | R2 entry; verify backlog reflects this. |
| 4 | EP-MEL-18 i18n applies to all surfaces but Panel 5 shows 0 perf tests. | Medium | Surfaces squad | Add 1 perf story for RTL bundle-size impact. |
| 5 | EP-MEL-20 Observability counts 16 stories but no contract tests. | Low | Platform & SRE | Add contract tests for OTel exporter format. |
| 6 | Workflow WF-09 Offline Sync has only EP-MEL-10 mapping; ensure EP-MEL-06 desktop offline UI is also linked. | Low | Surfaces squad | Verify and add cross-link in frontend/05. |
| 7 | No epic has (o) ownership of tax-service. | Medium | Reservations & Inventory | Confirm ownership in EP-MEL-04 or EP-MEL-19; update epic header. |
Findings track in the Cross-cutting Jira component as Tasks (type:tech-debt, wave:r1).
11. Regeneration
This matrix is regeneratable from the source documents. The agent commands/refresh-traceability-matrix.md (planned in Wave 2) will:
- Parse
07-epics-and-user-stories.mdfor each story'sServices,Frontend Surfaces,DoD refs,Test types,Complexity, and per-epic Journey set. - Parse
frontend/05-frontend-workflows.mdfor theEP-MEL-NNIDs cited in each workflow. - Parse
roadmap/service-readiness-gates.mdfor current readiness phases. - Emit Panels 1–8 above.
- Diff against the previous matrix; fail CI if a panel changed without an accompanying explanation entry under §10.
Until the agent is implemented, this document is hand-maintained at every wave checkpoint and after each backlog change with > 5 stories.
12. Cross-references
- 07 Epics & User Stories — source of truth for every story-level cell.
- 03 Microservices — service ownership.
- Journeys —
J-NNsource of truth. - Frontend Workflows —
WF-NNsource of truth. - Standards → DoD — DoD section IDs.
- Roadmap → Service Readiness Gates — phase source of truth.
- Roadmap → Sprint Distribution Rules — capacity planner consumes Panel 7.
13. Versioning
Same governance as docs/standards/CODING_STANDARDS.md §19. Treat this document as a derived report; reviewers are not asked to validate every cell — only to validate the regeneration script and the gap findings.