A repo's scaffold stamp says paved-road template 3.2.0 but the files were later rewritten - what does gating on that stamp prove?
answer
- who wrote the field, and when
- a claim about creation, not about now
- provenance versus measurement
- re-render and diff, or checksum managed paths
basics
~20 sA scaffold stamp records origin, not current state: this repo was created from that template version. Later edits never change it, so gating on the stamp certifies history and says nothing about whether the files still conform.
solid answer
~50 sIt proves provenance and only provenance. The stamp is a claim written once, by the scaffolder, at creation; every edit afterwards leaves it untouched, so "created from the paved road" and "still on the paved road" are different assertions and the stamp only supports the first. To make the gate mean the second, conformance has to become a measurement: re-render the template at the stamped version and diff the paths the template declares it owns, or have the scaffolder record checksums of those managed files in the stamp so a later edit is detectable. Treat the version number itself as a separate and weaker signal - lag behind the current template belongs on a scorecard, not on a blocking gate. Above all, name the check honestly, because a rule called `conformance` that only reads a self-written origin field will be trusted for something it never verified.
code
yaml · 7 lines# .paved-road.yaml - written by the scaffolder when the repo was created
template: backend-service
templateVersion: "3.2.0"
scaffoldedAt: "2026-01-14T09:22:10Z"
# no record of which paths the template owns, and no checksums,
# so any later edit to those paths is invisible to a rule reading this file
...go deeper
Understand the basic distinction: a field saying where a repository came from is written once at creation, and editing the repository afterwards does not change it.
Be able to explain why the check passes despite drift, and describe at least one way to make conformance measurable - comparing against a re-rendered template, or checksums of the paths the template owns.
Show the tradeoff you would actually make: which properties you block on, which divergence you merely report, and how you keep the diff from drowning teams in paths they were always meant to own.
Own the honesty of the estate's reporting. Decide what each check is allowed to be called, and what you would say when someone quotes a green conformance number as assurance it was never built to give.
## Provenance and conformance are different assertions A scaffold stamp is a small file the generator writes into a new repository recording what it generated the repository from. It is a **provenance claim about a moment in the past**. Conformance is a **property of the current files**. Nothing connects the two after creation day, because nothing rewrites the stamp when someone edits a file. This is the single most common design error in paved-road gating, and it is attractive precisely because the stamp is so cheap to read: one field, no rendering, no diffing, evaluates in milliseconds on every change. It also produces a very high pass rate, which everyone enjoys until someone asks what the passes mean. ## What the gate is actually asserting With a stamp-only rule, the honest statement is: *at some point in this repository's history, a generator created it from template 3.2.0, and someone has not deleted the record.* That is worth something. It is not worth blocking on, and it is definitely not evidence that the pipeline definition, the release step or the base image configuration still look the way the template intended. There is a second, quieter problem: the stamp lives in the repository, so the team that owns the repository can edit it. A file that asserts compliance and is writable by the party being assessed is self-assertion. In practice most teams never touch it, which is why the failure is not malice but drift - and drift is invisible to the check by construction. ## Three ways to turn it into a measurement **1. Re-render and diff.** Fetch the template at the version the stamp names, render it with the repository's own parameters, and compare the result against the current files. This makes conformance a real measurement. Its costs are real too: the template at that version must still exist and render deterministically, the gate needs a rendering step, and the template must declare **which paths it owns**, or the diff is noise everywhere the team was always expected to write its own code. **2. Checksums of managed files.** Have the scaffolder record, in the stamp, the set of paths the template owns plus a hash of each. A later edit to a managed file is then detectable by reading the repository alone, with no rendering. This is much cheaper than re-rendering and catches the common case. It does not catch a change to the stamp itself, which is why some teams also keep a copy of what the scaffolder wrote in a central record and reconcile against it. **3. Check the invariants directly.** Rather than asserting the repository still matches a template, assert the handful of properties the paved road exists to guarantee, each read from the file that carries it. This decouples the rule from template churn - a team that reorganised its layout but kept every guarantee passes, which is the correct outcome and one that a whole-tree diff would get wrong. In a mature estate you usually run (3) as the blocking rule and (1) or (2) as the reporting signal, because invariants are what you can defend blocking someone over, while whole-repository divergence is a conversation. ## The version number is a third, separate signal "Stamped 3.2.0 while the current template is 3.9.0" is not non-conformance; it is lag. It is genuinely useful - it tells you how much of the estate would move if you changed the template, and which services are furthest from what new services get - but blocking a bug fix because the template moved on is how a gate loses its constituency. Version lag belongs on a scorecard. ## Naming the check honestly Whatever you build, name it for what it measures. `scaffolded-from-paved-road` and `matches-paved-road-template` are different checks with different strengths, and a dashboard that shows one under the other's name will eventually be quoted at someone as evidence. The cheap check is not wrong to have. It is wrong to let people believe it is the expensive one.
- What does re-rendering the template at gate time actually cost you?The template at the stamped version has to still exist and render deterministically, and the gate needs a rendering step with the repository's parameters. The bigger cost is noise: unless the template declares which paths it owns, every service fails on the files teams were always meant to write themselves.
- The scaffolder writes the stamp into the repo, where the team can edit it. Is that acceptable?It is acceptable as long as you do not call the result verified. The scaffolder is the only thing that knows the answer at creation, so it writes it. If the assertion needs to survive an editing team, keep the record centrally when the scaffolder runs and reconcile the repository's copy against it.
- Is a version stamp worth keeping at all if it proves so little?Yes. It names which template version to compare against, which is what makes re-rendering or checksum comparison possible at all, and it makes estate-wide lag visible. It only becomes a lie when the rule consuming it describes itself as a conformance check.
It is the date on a building's plaque: it tells you honestly what year the place was built, and nothing whatsoever about the state of the wiring today.
saying these in an interview costs you the question
- Treats the stamp as proof the files still match
- Assumes only the scaffolder can write that file
- Blocks a change on template version lag alone
- Calls a provenance claim a conformance measurement