ADR-001: Capability-Based Dependency Resolution

Date: March 2026 Status: Accepted

Context

The pipeline needed a way for stages to auto-connect without hardcoding dependencies. Legacy system required explicit stage ordering.

Decision

Stages declare capabilities (what they provide) and dependencies (what they need). Pipeline resolves dependencies using prefix matching.

class DataSourceStage(Stage):
    capabilities = ["data"]  # provides "data"
    dependencies = []         # no dependencies
    
class FontStage(Stage):
    capabilities = ["rendered"]  # provides "rendered"
    dependencies = ["data"]      # needs "data"

Prefix matching: dependency "source" matches capability "source.headlines", "source.poetry", etc.

Consequences

Positive: New stages integrate automatically without modifying controller
Positive: Flexible composition - swap implementations by changing capabilities
Negative: Debugging dependency chains requires understanding prefix resolution

References

engine/pipeline/core.py: Stage base class
engine/pipeline/controller.py: Resolution logic