5.5 KiB
ADR 0009: Select named configuration scopes with declared inspection capabilities
Status
Proposed
Date
2026-10-06
Context
An application can expose its own configuration, PromptKit engine configuration,
and other independently meaningful configurations through the config family.
A scope identifies the configuration targeted by an operation. Different
providers may support different inspection operations.
Configuration scopes and command families are distinct: a future feedkit
family can inspect feeds through its own verbs, independently of whether FeedKit
configuration is also exposed as a configuration scope.
ADR 0004 defines initial operation purposes. ADR 0001 records installation from declared capabilities.
Decision
Use stable semantic scope identifiers. The app scope describes application
configuration; an optional promptkit scope describes captured engine
configuration. Registration also accepts additional independently meaningful
configuration scopes with unique identifiers.
Each scope declares its available inspection operations and their providers. Capabilities can include validation, native effective YAML, source inventory, path explanation, and safe semantic comparison data. Scope metadata describes identity, supported operations, applicable selectors, and dependencies. CommandKit checks the wiring needed by each declared capability. Additional operations can be supported as their upstream data becomes available.
Expose scope operations through CommandKit-owned public provider contracts. Adapters preserve supported upstream values, provenance, and confidentiality. Exact Go declarations remain API design work under ADR 0003. Separate capability contracts allow new operations to evolve independently of existing provider implementations.
--scope NAME selects one configuration. all denotes all registered scopes for
config validate and config show; sources, explain, and diff select one.
An aggregate selection retains its all-scope meaning. CommandKit checks operation
availability across the requested selection before acquiring views. An unavailable
operation yields a usage diagnostic identifying the scope and available choices,
so an aggregate result accurately describes the requested coverage.
show, sources, explain, and diff default to app; validate defaults to
all. Explicit selection remains available for narrower validation. These
selection defaults operate against the registered inventory and capabilities.
Scope order is app first when registered, promptkit next when registered,
then additional scopes sorted by identifier. config scopes and combined YAML
show use that order. The inventory reports identity, description, supported
operations, and selection defaults entirely from metadata. Discovery is available
independently of file loading.
CommandKit validates scope collisions, operation wiring, selector applicability, and supported selections. It registers the standard operations supplied by at least one scope, alongside metadata discovery. Help identifies their applicable scopes; selection of an unsupported scope-operation pair yields a usage diagnostic.
Declared dependencies are coordinated under ADR 0008. An inspection operation acquires its selected scope and required prerequisites through that provider boundary.
A command family defines its own resources, supported verbs, and data contracts. The configuration provider contract applies to configuration inspection. FeedKit resource listing or display, for example, can use separate capabilities with meanings consistent with shared verbs. A library integration can expose a command family, configuration scope, or both, according to the provided capabilities.
Alternatives considered
| Alternative | Analysis |
|---|---|
| Require every configuration inspection operation per scope | Gives one capability set. Missing comparison or provenance blocks other useful inspection operations. |
| A separate command tree for each configuration | Makes the target part of the path. Repeats common operations and help. |
| One verb set for every library family | Gives a uniform inventory. Resource domains acquire operations with little useful meaning. |
| Executable names as scope identifiers | Relates scopes to application branding. Shared scripts need application-specific identifiers. |
Every operation defaults to app |
Gives one selection default. Integrated validation becomes an explicit aggregate request. |
| Skip unsupported scopes during aggregate inspection | Produces available reports. The meaning and coverage of all become less apparent. |
| Public upstream result types as the provider API | Simplifies direct wiring. CommandKit acquires those type identities and release dependencies. |
Consequences
A shared configuration family serves multiple configurations while help and inventory make operation availability explicit. Individual capabilities can be integrated before other upstream inspection APIs exist. Default and ordering rules remain observable CommandKit behavior.
Scoped operations validate availability before loading. An all request can
report unsupported coverage; an explicit supported scope remains available.
The same verb purpose can serve different families with different operation sets.
Selection inputs define parsing and propagation; native YAML reporting defines combined presentation.