The spec layer

The spec layer answers one question for each rung: what we build and how we know it is right. It holds the spec, its user stories, and the agent brief — the precise definition plus its proof. It is the single source of truth, and the only thing that edits it is feedback.

Everything else is downstream. The user stories and the agent brief are derived from the spec; the code and the tests are built to the spec. Nothing edits a derived artifact directly: a change happens in the spec, and the stories, the brief, the code, and the tests are regenerated from it. That is what keeps the spec authoritative — the moment a story or the code is edited in place, it forks from the spec, and the spec becomes a document that lies about the system (the A1.02.1 drift, between the spec and what it specifies).

The roadmap and the spec are not two different things — they are two granularities of the same rung. The roadmap holds the coarse face: one line and a definition of done, enough to order the work and demo against. The spec holds the fine face: the full contract — the precondition, the postcondition, the invariant — enough to build to and prove. One rung, two layers; the spec is the one where correctness lives.

Switch the view to render one rung at both granularities. The line is what the roadmap carries; the contract is what the spec carries. The roadmap line is mutable and re-ordered as priorities move; the contract is fine and authoritative, and it changes only through feedback.

On the Portal — the learning platform this course builds — take the rung “one branded id”. Its spec is the id contract: a 14-character TSK… id, decodes to its type, unique within a node-millisecond. From that one spec everything derives. The user story is its negotiable face: “as a caller I receive a typed id I can decode.” The agent brief tells the Author how to build it. The implementation Portal.ID.generate/1 satisfies it, and the tests accept it.

Now feedback arrives — “also sort by time.” The change lands in one place, the spec; then the story, the brief, the code, and the tests are regenerated from the edited spec. Nothing is patched in isolation, so nothing forks. The spec stays the one fine, authoritative face every other artifact is built from.

# The spec for the rung "one branded id" — the single source of truth.
#   pre:  type ∈ {:user, :event, :session, ...}
#   post: 14 chars · decodes to that type
#   inv:  unique within a node-millisecond

# Derived: the user story (the negotiable face) and the agent brief come FROM the spec;
# the code and tests are built TO it. Nothing edits a derived artifact directly.
id = Portal.ID.generate(:user)        # => "USR0NbAb1xcFCy" (built to the spec)
assert Portal.ID.decode(id).type == :user   # the test accepts to the spec

# Feedback: "also sort by time" → edit the spec, regenerate everything downstream.

The spec layer is where correctness lives: for one rung, the precise definition plus its proof. The user stories and the agent brief are derived from it; the code and the tests are built to it; nothing edits a derived artifact directly. It is the fine face of a rung whose roadmap line is the coarse one — same rung, two granularities — and it is the single source of truth, edited only by feedback. With both layers in hand, the closing dive draws the rule that holds them together.

Primary sources for the spec as the derived-from hub, and where it connects in the course.