Follow-up to #104 (ADR 0016), open question 2.
A referenced section produces no planned example in its own document — it runs where it is referenced. Drift (ADR 0002) treats a candidate as live when its span overlaps a planned example, so the consumed section's paragraphs overlap nothing locally.
What happens today
No false drift, because a consumed oath's baseline is derived from its own (empty) plan and so records no live examples. But that means the shared section's paragraphs are no longer in the baseline at all, and two things follow:
- If every referrer is later deleted, the section becomes an ordinary example again with no baseline history — treated as new rather than restored.
- A step definition that stops matching a shared section is caught at the reference site (the reference resolves to zero steps →
reference-empty → the run fails), not as drift. That is arguably better — it fails loudly, once, at the place that depends on it — but it is a different mechanism than the rest of the system, and nothing records that decision.
To decide
- Does a consumed section's baseline entry keep its live examples (widening liveness to "overlaps a planned example or was spliced into one", which means the referencing side must report back)?
- Or is
reference-empty at the reference site the intended and sufficient signal, with the baseline entry meaning only "this file was discovered"?
The second is simpler and is what ships today. If we keep it, say so in reference/examples.mdx under Drift detection, so the asymmetry is documented rather than incidental.
Follow-up to #104 (ADR 0016), open question 2.
A referenced section produces no planned example in its own document — it runs where it is referenced. Drift (ADR 0002) treats a candidate as live when its span overlaps a planned example, so the consumed section's paragraphs overlap nothing locally.
What happens today
No false drift, because a consumed oath's baseline is derived from its own (empty) plan and so records no live examples. But that means the shared section's paragraphs are no longer in the baseline at all, and two things follow:
reference-empty→ the run fails), not as drift. That is arguably better — it fails loudly, once, at the place that depends on it — but it is a different mechanism than the rest of the system, and nothing records that decision.To decide
reference-emptyat the reference site the intended and sufficient signal, with the baseline entry meaning only "this file was discovered"?The second is simpler and is what ships today. If we keep it, say so in
reference/examples.mdxunder Drift detection, so the asymmetry is documented rather than incidental.