The single source of truth

Two layers sit over the same work: a roadmap that plans how we deliver and a spec that defines what we build and how we prove it. One rule keeps them stable. The spec is the single source of truth, and only feedback edits it. The roadmap points at the spec; the user stories and the agent brief derive from it. Nothing edits the derived artifacts directly — change the spec and the rest re-derives.

That one rule sets two cadences. Because everything downstream depends on the spec, it must change rarely and only for a real reason: feedback from a built rung. The roadmap depends on nothing downstream, so it changes often and cheaply — re-order it whenever delivery should re-prioritise. Different rates, different reasons. The discipline is to keep each change on its own layer.

Separate, both layers are cheap to change: delivery can be re-planned without touching what any rung means, and a spec can be sharpened without re-planning delivery. That independence is exactly orthogonality (A1.02.3) applied to the plan itself — two decisions that move on their own. Collapse the layers and the independence goes with them: a change to one drags the other, and the cheap moves become expensive ones.

There are two ways to collapse, and each lands on a failure already named. Bake the full specs into the roadmap and the roadmap becomes a frozen up-front specification — the big-bang spec from A1.01.2, where re-ordering now means rewriting contracts. Bake delivery order into the specs and a rung can no longer be re-planned without editing what it means — coupling from A1.02.3, now between the plan and the definition. Switch the stack to see which failure each collapse becomes.

On the Portal — the learning platform this course builds — the roadmap is re-ordered weekly as the loop learns: promote the read model, split the dashboard rung. Not one spec moves. Separately, feedback on the id rung (“also sort ids by time”) edits the id spec once, and the roadmap order is untouched. Two cadences, two reasons — and the id spec stays the one place the id contract lives, with the stories and the brief derived from it.

The wrong moves are the two collapses. Write the full id contract into the roadmap and re-ordering delivery now means rewriting specs — big-bang. Encode “ship the id before the event” inside the id spec and that spec can no longer be re-planned — coupling. Keeping the contract in the spec, and only the order in the roadmap, keeps both cheap.

# The spec is the single source of truth — the id contract lives here, nowhere else.
#   spec: a branded id; 14 chars; decodes to its type; unique within a node-ms.
id = Portal.ID.generate(:user)        # the code derives from the spec
Portal.ID.decode(id).type            # => :user — checked against the spec

# roadmap (often, cheap): re-order delivery — the spec above is untouched.
#   …id, event, read-model, dashboard…  →  …id, event, dashboard, read-model…

# feedback (rarely, only here): "also sort ids by time" edits the id spec once.
#   the stories and the brief re-derive; the roadmap order does not change.

A1.04 in one move. Two layers sit over the work: a roadmap that plans how we deliver and a spec that defines what we build and prove. One rule keeps them apart — the spec is the single source of truth, edited only by feedback. The roadmap points at it; the stories and the brief derive from it; the two run at their own cadence, the roadmap often and cheap, the spec rarely and only for a reason. Separate, they are both cheap to change; conflated, neither is — and the conflations land on failures already named, big-bang (A1.01.2) and coupling (A1.02.3).

Primary sources for the single source of truth and the two separable layers, and where it connects in the course.