A4.7 · The spec layer · capstone
Specifying Portal's engine
Six modules taught one move each. The capstone runs all of them on one real target and produces an artifact you can read — the engine chapter's first spec, closed and acceptable.
A4.1 through A4.6 each taught one part of the spec layer. Here they land on the
Portal's engine, planned in the companion course as F5.1 — Portal's
engine-facade rung — the engine chapter's first rung, the seed of the F6 master
invariant. By-example, the triad, the anatomy, the stories, the invariants, and the
traceability chain run in sequence over its seven deliverables. The worked output reproduces the real
f5.1.md and f5.1.stories.md — including a
Coverage line that closes. Step the sequence on the right.
The workshop sequence · pick a stage
POST /enroll returns 422, an unknown path returns 404),
each doubling as the executable check. · 0 of 7 deliverables covered yet; coverage
closes at stage 6.Six moves, one spec
The spec layer defines what we build and prove for each rung the roadmap orders. The workshop is that layer applied once, end to end, on the Portal's engine — F5.1 — Portal's engine-facade rung, the engine chapter's first rung and the seed of the F6 master invariant. It runs in six moves, and each produces a named part of the spec.
By-example replaces an abstract requirement with worked cases — F5.1-US1's three:
the app boots on port 4000, POST /enroll returns 422 from
the stubbed boundary, an unknown path returns 404. The triad splits
the work across f5.1.md, f5.1.stories.md, and
f5.1.llms.md. The anatomy fills the six sections of the spec —
Goal, Rationale, Scope, Deliverables (D1–D7), Invariants, Definition of Done. The
stories derives five Connextra stories (US1–US5) from the deliverables. The
invariants states the five (INV1–INV5). Traceability closes the chain with a
Coverage line that maps every deliverable to a story.
Over the sequence sits F5.1-INV1, the master-invariant seed, quoted verbatim: “the web layer holds no
domain logic … so F6 can replace Bandit with Phoenix untouched.” The
output is not invented — it reproduces the real f5.1.md and
f5.1.stories.md, including the Coverage line that closes them.
The full spec-layer sequence run once on a chapter reproduces a closed, acceptable spec: examples become checks, the triad splits the work, the anatomy is filled, stories derive from deliverables, invariants are stated, and the chain closes.
The workshop reproduces the real f5.1.md and
f5.1.stories.md. Its Coverage line —
D1→US1 · D2→US2 · … — closes, so the engine
chapter's first rung is acceptable as written.
The workshop is the spec layer applied once on the Portal's engine — the contracts Part V then hands an Author to build.
The three dives
Each dive carries one pass of the workshop on the real F5.1 rung, in the arc read the deliverables → run the sequence → check the spec closes: first read F5.1's seven deliverables and the replaceable-seam invariant; then step the six A4 moves over the triad and watch the spec take shape; then check the produced Coverage line against the real one and confirm it closes. Read them in order — A4.7.1 starts.
The engine deliverables
Read F5.1's seven deliverables D1–D7 section by section, and the master-invariant seed (F5.1-INV1) that holds the web seam thin — the workshop's starting material.
Run the sequence
Step the six A4 moves over the F5.1 triad — by-example, triad, anatomy, stories, invariants, traceability — and watch the spec fill, part by part, with the closure tracked.
The closed spec
Check the produced Coverage line against the real one. The spec is acceptable only when every deliverable maps to a story and the chain closes — correct by definition.
A4.7 is the chapter capstone: it runs A4.1–A4.6 on the Portal, reproducing the real
f5.1.md and f5.1.stories.md. It runs one layer below the
roadmap capstone A3.8 · Workshop: roadmapping
Portal, which planned the delivery this layer now defines. Return to the
A4 chapter navigation to continue.
References
The specification tradition the workshop runs on, and the chapter it applies in sequence.
Sources
- Adzic, G. — Specification by Example — concrete examples as the executable specification, run end to end on one feature.
- Cohn, M. — User Stories Applied — deriving stories and their acceptance from what a slice must deliver.
- Humble & Farley — Continuous Delivery — a thin first slice that is releasable, with the seams to later work named, not built.
Related in this course
- A4 · The spec layer — the chapter whose six modules this capstone runs in sequence.
- A3.8 · Workshop: roadmapping Portal — the roadmap capstone one layer above, which planned this rung's delivery.
- A1.05 · Correct by definition — the closure this workshop's final check makes operational.
- F6 · The Portal on the web (Phoenix) — the web chapter whose master invariant F5.1-INV1 seeds.
- Companion · Functional Programming in Elixir — where the Portal's engine is actually implemented.