--- name: "journey-e2e-verifier" displayName: "Journey E2E Verifier" description: "Drives end-to-end verification from user journeys so every primary journey is provably exercised against the real interface. Drafts a test-suite specification, primes a Kiro spec to produce and run the suite, and emits a Traceability Matrix. Fails the verification gate whenever any primary journey lacks a passing end-to-end path, even if the build passes." keywords: ["e2e verification", "user journeys", "traceability matrix", "primary journey", "verification gate", "browser tests", "cli tests"] author: "SDLC Agentic Toolkit" --- # Journey E2E Verifier ## Overview The Journey E2E Verifier is the Verify-phase Power of the SDLC Agentic Toolkit. Its job is to close the discovery-to-verify loop: it takes the `user-journeys.md` artifact produced upstream by the User Journey Mapper together with the project's design document, and drives end-to-end (E2E) verification so that **every `Primary_Journey` is provably exercised against the real interface** before a feature is considered complete. It does not merely assert that a build compiles or that unit tests pass. It reasons about the actual user journeys, drafts a test-suite specification with at least one E2E scenario per primary journey, primes a Kiro spec that produces and runs that suite against the running software, and produces a `Traceability_Matrix` that maps each primary journey to its scenarios and their pass/fail results. If any primary journey has no passing E2E path, the verification gate is set to **fail** — even when the build itself passes. Key capabilities: - Reads user journeys and the design document as verification inputs, with fail-fast behavior when either is unavailable. - Derives an E2E test-suite specification (≥1 scenario per `Primary_Journey`) from journeys + design. - Primes a Kiro spec that produces and runs the suite, selecting the right execution interface (browser for web apps; CLI or public API otherwise). - Emits a `Traceability_Matrix` and a derived verification-gate result. ## Onboarding Use this Power during the **Verify** phase, after the Discovery pipeline has produced `user-journeys.md` and after a design document (`design.md`) exists for the software under test. Prerequisites before activation: 1. `user-journeys.md` exists and is readable (produced by the User Journey Mapper). It contains one Mermaid journey per `Primary_Persona`; each such journey is a `Primary_Journey`. 2. A design document exists and is readable (typically the spec's `design.md`), describing the components, interfaces, and — importantly — whether the software under test is a web application or not. You activate the Power on demand with a request such as "verify the primary journeys end-to-end", "drive E2E tests from the user journeys", or "build a traceability matrix". The Power then runs the workflow below, drafts the test-suite specification, primes the E2E Kiro spec, and reports the `Traceability_Matrix` plus the verification-gate result. ## Activation Triggers Activate on demand during Verify when the user asks to verify journeys end-to-end or to build traceability from journeys to tests. Representative queries: - "verify the primary journeys end-to-end" - "drive E2E tests from the user journeys" - "build a traceability matrix" - "check that every primary journey has a passing E2E path" - "run the journey verification gate" ## Inputs The Power reads exactly two inputs (Req 6.1): 1. **`user-journeys.md`** — the user-journeys artifact. Each Mermaid journey diagram corresponds to one `Primary_Journey` (one per `Primary_Persona`). This defines the set of primary journeys that MUST each be covered by at least one E2E scenario. 2. **The design document** (e.g. `design.md`) — describes the system under test, its components and interfaces, and whether it is a web application. Used together with the journeys to derive concrete, realistic scenarios and to select the execution interface. Both inputs are required. Do not attempt verification with only one of them. ## Common Workflows Run the phases in order. Do not skip the fail-fast input check. ### Phase 0 — Read and validate inputs (Req 6.1, 6.2) 1. Read `user-journeys.md` and the design document. 2. **If `user-journeys.md` is missing or cannot be read, OR the design document is missing or cannot be read:** - **Halt verification immediately.** Do not draft a spec, do not prime a Kiro spec, do not run tests. - **Retain any prior verification artifacts unchanged** — do not overwrite, delete, or modify an existing `Traceability_Matrix` or prior test-suite specification. - **Report which required input is unavailable** (name the specific file: `user-journeys.md` and/or the design document), and stop. 3. Only when **both** inputs are present and readable, continue to Phase 1. ### Phase 1 — Enumerate the primary journeys 1. Parse `user-journeys.md` and enumerate every `Primary_Journey` (one per Mermaid journey diagram / `Primary_Persona`). 2. Record the persona and scenario associated with each primary journey; these anchor the scenarios you will draft. ### Phase 2 — Draft the test-suite specification (Req 6.3) 1. For **each** `Primary_Journey`, draft **at least one** end-to-end test scenario, derived from the journey stages (actions, touchpoints, pain points, opportunities) and the design document (components, interfaces, expected behavior). 2. A scenario must describe concrete steps and an expected result that exercises the journey against the real interface — not a stub or a unit-level check. 3. Write the drafted specification following the **Test-Suite Specification** contract below. Ensure every primary journey maps to ≥1 scenario before proceeding. ### Phase 3 — Select the execution interface (Req 6.5, 6.6) Determine the interface from the design document: - **If the software under test is a web application:** select the **browser** interface. E2E scenarios drive the app through a browser (e.g. a browser automation framework appropriate to the stack). - **Otherwise (not a web application):** select the **CLI** or **public API** interface. E2E scenarios drive the software through its command-line interface or its public API. Record the chosen interface (`browser` | `cli` | `api`) on each scenario in the specification. ### Phase 4 — Prime a Kiro spec to produce and run the suite (Req 6.4) 1. Use the drafted test-suite specification to **prime a Kiro spec** whose job is to **produce and run** the E2E test suite against the software using the selected interface. 2. The primed spec is the vehicle that actually generates the test code and executes it; this Power supplies the authoritative scenario definitions and the interface selection so the produced suite exercises every primary journey. 3. Capture each scenario's pass/fail result from the run. ### Phase 5 — Produce the Traceability Matrix and derive the gate (Req 6.7, 6.8) 1. Build a `Traceability_Matrix` mapping **each** `Primary_Journey` to its ≥1 E2E scenario(s) and recording each mapped scenario's **pass/fail** result, following the **Traceability Matrix** contract below. 2. Derive the verification gate: - Determine, for each primary journey, whether it has **at least one passing** E2E scenario (a passing E2E path). - **If any `Primary_Journey` has no passing E2E path, set the verification gate result to `fail` — even when the build result is passing** — and explicitly list which primary journeys lack a passing path. - Only when every primary journey has at least one passing E2E path may the gate be `pass`. 3. Report the matrix, the gate result, and (when failing) the journeys without a passing path. ## Output Artifact Contracts ### Test-Suite Specification Defines at least one E2E scenario per `Primary_Journey`, derived from `user-journeys.md` + the design document (Req 6.3). Each scenario records its execution interface (Req 6.5 / 6.6). ```markdown # E2E Test-Suite Specification ## Scenario: # ≥1 per Primary_Journey (Req 6.3) - Source Journey: - Derived From: user-journeys.md + design.md - Interface: browser | cli | api # browser for web apps (6.5); cli/api otherwise (6.6) - Steps: ... - Expected Result: ... ``` Rules: - Every `Primary_Journey` in `user-journeys.md` MUST appear as the `Source Journey` of at least one scenario. - `Interface` MUST be `browser` when the software under test is a web application, and `cli` or `api` otherwise. ### Traceability Matrix Maps each `Primary_Journey` to ≥1 scenario and records each scenario's pass/fail result (Req 6.7). Encodes the derived verification gate (Req 6.8). ```markdown # Traceability Matrix | Primary Journey | E2E Scenario(s) | Result (pass/fail) | | --------------- | --------------- | ------------------ | | | | pass \| fail | # each Primary_Journey → ≥1 scenario (Req 6.7) ## Verification Gate: pass | fail # fail if any Primary_Journey has no passing E2E path, even when the build passes (Req 6.8) ## Journeys Without Passing Path: [...] # non-empty list names each primary journey lacking a passing E2E path (Req 6.8); empty when gate = pass ``` Rules: - Every `Primary_Journey` MUST have a row mapping it to at least one scenario with a recorded `pass`/`fail` result. - `Verification Gate` MUST be `fail` whenever `Journeys Without Passing Path` is non-empty, regardless of build status. - `Verification Gate` MAY be `pass` only when every primary journey has at least one passing scenario (empty `Journeys Without Passing Path`). ## Best Practices - **Fail fast on inputs.** Never partially verify. If either input is unavailable, halt, preserve prior artifacts, and report the specific missing input. - **One scenario minimum per journey — cover them all.** Do not leave any `Primary_Journey` unmapped. Coverage of every primary journey is the core invariant. - **Exercise the real interface.** Scenarios must drive the running software (browser, CLI, or public API), not mocks. E2E means end-to-end. - **Let the gate be strict.** A passing build is not a passing verification. The gate fails if even one primary journey lacks a passing E2E path. - **Derive, don't invent.** Ground every scenario in a specific journey stage and the design document so scenarios stay traceable and realistic. - **Keep prior artifacts intact on error.** Verification is idempotent-safe: a halted run must leave earlier verification artifacts unchanged. ## Troubleshooting - **"Which input is unavailable?" / verification halted immediately.** Cause: `user-journeys.md` or the design document is missing or unreadable (Req 6.2). Solution: ensure the User Journey Mapper has written `user-journeys.md` and that a readable design document exists, then re-activate. Prior verification artifacts are left unchanged. - **A primary journey has no scenario.** Cause: the test-suite specification omitted a journey (violates Req 6.3/6.7). Solution: enumerate every Mermaid journey in `user-journeys.md` and add at least one scenario per journey before priming the spec. - **Gate is `fail` but the build passed.** This is expected behavior (Req 6.8), not a bug: at least one primary journey lacks a passing E2E path. Check `Journeys Without Passing Path`, fix the failing scenario or the software, and re-run. - **Wrong interface selected.** Cause: the software type was misread from the design. Solution: confirm from the design document whether the system is a web application (→ `browser`) or not (→ `cli`/`api`), and update each scenario's `Interface` field. - **Scenarios exercise stubs, not the real system.** Cause: the primed Kiro spec produced unit-level or mocked tests. Solution: reaffirm in the primed spec that scenarios must run against the running software through the selected interface.