Problem
The choice of an ordered-stage pipeline (with exactly-one pillar enforcement) over nested HttpClient decorators is deliberate, but the rationale — and its one cost — isn't captured. The cost: HttpStep.process's copy()-to-re-drive contract is more error-prone than a decorator's plain inner.execute(); a step author who forgets next.copy() can silently resume past visited steps.
Proposed change
Add a "Why stages, not decorators" section to docs/pipelines.md, noting the ordering / exactly-one guarantees we gain (which the nested-decorator approach can't enforce) and the re-drive contract authors must honour.
Acceptance
Priority: low · Effort: small
Problem
The choice of an ordered-stage pipeline (with exactly-one pillar enforcement) over nested HttpClient decorators is deliberate, but the rationale — and its one cost — isn't captured. The cost:
HttpStep.process'scopy()-to-re-drive contract is more error-prone than a decorator's plaininner.execute(); a step author who forgetsnext.copy()can silently resume past visited steps.Proposed change
Add a "Why stages, not decorators" section to
docs/pipelines.md, noting the ordering / exactly-one guarantees we gain (which the nested-decorator approach can't enforce) and the re-drive contract authors must honour.Acceptance
docs/pipelines.mdPriority: low · Effort: small