ADR-0019: Hybrid Capability Namespace Governance
Accepted
Date: 2026-06-10
Context
The Capability namespace defines what features Adapters and Modules can declare and what Archetype Slots can require. Two extremes:
- Strict: all Capability IDs centrally defined upfront. Safe but bottlenecks adoption.
- Permissive: any Manifest can declare any Capability. Scales but namespace fragments.
Almathal needs the registry to be curated (consistent semantics, no collisions) while still growing organically with real Adapter needs.
Decision
Hybrid governance:
- The Capability registry is centrally maintained. Only registered Capabilities can appear in Manifests and Slots.
- New Capabilities can be proposed by Manifest authors (human or agent) when they encounter Adapters that need them.
- Proposals are reviewed (by Human Reviewer for new categories; by automated checks for additions within existing categories) and admitted or rejected with documented reasoning.
This applies identically to the Contract namespace.
Rationale
- Central curation keeps semantics consistent and prevents fragmentation.
- Bottom-up proposals ensure the registry reflects real needs, not top-down speculation.
- The review process is lightweight enough not to slow Manifest authoring substantially.
- Versioning (integer
v1,v2, etc.) handles interface evolution.
Consequences
- A Capability proposal queue and review process is part of the Curation Pipeline.
- New Capability IDs cannot appear in Manifests until admitted.
- Documentation of the registered Capability set is maintained at
/governance/capability-namespace/. - An MVP seed list of ~50 canonical Capabilities is established before broad Manifest authoring begins.