Deliverable to story

A spec's Deliverables section is a list of the concrete artifacts a rung produces — the endpoint, the router, the controller, the view, the liveness route, the verification. The .stories.md realizes each one with at least one user story: as a… I want… so that…, with Given/When/Then acceptance. The rule is one-directional and total: for every deliverable there is a story that realizes it.

A deliverable with no story is something the rung produces that no one asked for and that nothing accepts. It is built without a reason and shipped without a check — the kind of thing that drifts into a codebase and is never verified. Writing the stories so that each deliverable is realized is what keeps the rung honest: the Coverage line at the end of the file is the audit that proves no deliverable was left behind.

The hero figure read the map from the story side. The figure below reads it from the deliverable side: pick a deliverable and see the stories that realize it. F6.1's seven deliverables are all covered, so the map is closed. To see what a gap looks like, drop a story: removing US2 leaves D3 and D5 — realized only by US2 — with no covering story, and the covered count falls from seven to five.

That fall is the whole point. The map is not a decoration; it is a check. A deliverable that drops out of coverage is a deliverable the rung cannot accept as done, because nothing exercises it. The two figures teach different moves: the hero reads one story's reach, this one proves that every deliverable is reached — and shows the gap when one is not.

On the Portal — the learning platform this course builds — the real stories file belongs to F6.1 · Bootstrap the Phoenix PortalThe first web rung: stand the F5 engine up as a Phoenix app, with one facade-backed route and a liveness route.View the spec ladder →, the rung “bootstrap the Phoenix Portal”. Its spec lists seven deliverables; the stories file realizes them with five stories. Each story states the deliverables it implements on its own line, so the map can be read from either end. The markdown below carries one story's framing — the “Implements deliverables” line is the realization, read verbatim.

One caution on that fragment: it is the F6.1 draft wording. US2 was first drafted as “see a user's courses” at a /courses/:user_id page. The reframing happened at F6.5 · Views with HEExThe HEEx rung that server-renders the catalog and reconciles the learner route into the protected /my/courses.View the spec ladder →, which renamed the surface to the protected /my/courses — a learner's own enrollments, read from the authenticated session, never another learner's. The deliverable→story map is unchanged by the rename.

# f6.1 stories — one story realizes one or more deliverables (markdown, not code; F6.1 draft).
## F6.1-US2 — See my courses
#  As a signed-in learner, I want to open my own courses page,
#  so that I can see the courses I am enrolled in.

# Acceptance: Given a signed-in learner with enrollments, when GET /my/courses (protected),
#             then the page renders their own courses. (and the empty + not-signed-in cases)
# Note: the F6.1 draft named /courses/:user_id; F6.5 reconciled it to the protected /my/courses.

# The realization line — what this story covers:
Implements deliverables: F6.1-D3, F6.1-D4, F6.1-D5

# Read across all five stories, every deliverable D1…D7 is realized by at least one.

A spec lists deliverables; the stories file realizes each one with at least one story, and the mapping is many-to-many. From a story, read the deliverables it implements; from a deliverable, read the stories that realize it — the same map, read from each end. A deliverable with no story is a gap, visible the moment a covering story is removed. The next dive reads the single line that records this map for the whole rung.

Sources for stories as the derived, covering face of a requirement, and where this connects in the course.