The roadmap layer

A1.04 drew the line between two layers: the roadmap is how we deliver, the spec is what we build and prove. This dive gives that line its motive. The two layers exist apart because they answer different questions and change on different cadences. Definition answers “what is this rung, and how do we know it is right” — it is the single source of truth, and only feedback edits it. Delivery answers “in what order, at what size, to what milestone do the rungs ship” — and that order moves constantly as the loop learns.

Put both in one artifact and every re-order risks editing a definition. Promote a rung, and a careless edit rewrites what “done” meant; the spec stops being trustworthy. Keep them in separate layers and the order can change under feedback without ever touching the definition of a rung. That is the whole reason for a delivery layer: the spec stays the single source of truth while the plan above it stays cheap to re-order. The roadmap points at the specs; it never holds them.

A roadmap.md is an ordered set of thin-but-robust increments — rungs — grouped into milestones. Each rung is one line: an intent, a demo, and a definition of done, with the contract living one layer down in the spec the line points at. A milestone is a group of rungs that together ship something a real role can use end to end. Over the whole file sits a single master invariant — the architectural rule every rung must hold — and a delivery arc that names the order.

The defining property is what a line is not. A roadmap line names a rung, a milestone, and a spec; it defines no behaviour of its own. Cram the full contract into the line and the slot stops being a plan you re-order and becomes a definition you would have to re-negotiate to move. So re-ordering is decoupled from redefining: the order can change while not one spec the lines point at changes with it. Switch the ordering below to watch the delivery order move while the spec-edit count stays pinned at zero.

The Portal's web chapter — the companion course's F6 — ships from a real phoenix.roadmap.md. It carries nine rungs, f6.1 through f6.9, grouped into three milestones: ship the catalog (f6.1–f6.5), make it live (f6.6–f6.7), and ship to users (f6.8–f6.9). Each line names a rung, its demo, and the spec triad it points at — and defines no behaviour of its own.

Over all nine sits one master invariant: the web layer calls only the Portal facade. That single rule is what makes the ladder cheap — every rung adds web surface without reaching below the facade, so the engine under all nine rungs never changes. The Operator re-orders the rungs as feedback arrives; the Author builds each against the spec its line points at. Re-order the plan, and not one f6.N.md spec moves with it.

# F6 · phoenix.roadmap.md — the Portal on the web. Order only; each rung points at its spec.
#
# master invariant: the web layer calls only the Portal facade and renders only %Portal.Error{}.

## Milestone 1 · Ship the catalog
  f6.1  endpoint      → f6.1.md     # done: GET / renders a page over the facade
  f6.2  routing       → f6.2.md     # done: read/write/live routes + pipelines
  f6.3  Postgres      → f6.3.md     # done: catalog survives a restart
  f6.4  contexts      → f6.4.md     # done: the web reads and writes real domain
  f6.5  catalog view  → f6.5.md     # done: browse and create with inline errors

## Milestone 2 · Make it live
  f6.6  interactivity → f6.6.md     # done: search and create without a reload
  f6.7  PubSub        → f6.7.md     # done: two clients update live; a viewer count

## Milestone 3 · Ship to users
  f6.8  auth & deploy → f6.8.md     # done: sign in; a deployed clustered release
  f6.9  dashboard     → f6.9.md     # done: an operations dashboard, live, under auth
#
# Re-order within the master invariant; not one f6.N.md spec changes when the order does.

Delivery deserves its own layer because delivery and definition change on different cadences: the order moves with every loop, the definition only with feedback. A roadmap.md holds the delivery side — an ordered set of thin-but-robust increments grouped into milestones, each a line that points at a spec and defines no behaviour, all under one master invariant. Because the lines point at the specs rather than holding them, re-ordering the plan never edits a spec. The Portal's phoenix.roadmap.md proves it: nine rungs, three milestones, an unchanged engine. The next dive walks the road ahead — the eight A3 modules that turn this artifact into a practised discipline.

Primary sources for delivery as its own discipline, small re-orderable batches, and keeping the plan independent of the definition — and where the layers this dive sits between are defined in the course.