diff --git a/registry/README.md b/registry/README.md new file mode 100644 index 0000000..569abe9 --- /dev/null +++ b/registry/README.md @@ -0,0 +1,12 @@ +# Capability Registry + +Markdown-first capability index for federation and reuse planning. + +## Authoring + +1. Copy a capability entry template (see reuse-surface `templates/capability-entry.template.md`). +2. Add the row to `indexes/capabilities.yaml`. +3. Run `reuse-surface validate` from a checkout with the CLI installed. +4. Merge to `main` and verify publish with `reuse-surface establish --publish-check`. + +Federation contract: reuse-surface `docs/RegistryFederation.md`. diff --git a/registry/capabilities/capability.feature-control.evaluate.md b/registry/capabilities/capability.feature-control.evaluate.md new file mode 100644 index 0000000..afa16b7 --- /dev/null +++ b/registry/capabilities/capability.feature-control.evaluate.md @@ -0,0 +1,138 @@ +--- +id: capability.feature-control.evaluate +name: Feature Availability Evaluation +summary: Evaluate whether a feature is active, hidden, disabled, or unavailable for a subject in context. +owner: feature-control +status: draft +domain: helix_forge +tags: + - feature-control + - evaluation + - sdk + +maturity: + discovery: + current: D5 + target: D7 + confidence: medium + rationale: > + Concrete use cases and research references are documented in the maturity + standard example and feature-control domain work. + availability: + current: A4 + target: A6 + confidence: medium + rationale: > + SDK and service API artifacts exist in the feature-control repository. + Managed platform operation is the natural target for multi-tenant reuse. + +external_evidence: + completeness: + level: C3 + name: Functional Core + confidence: medium + basis: scope_vs_intent_and_consumer_expectations + satisfied_expectations: + - tenant-level feature evaluation + - user-level feature evaluation + - machine-readable decision result + broken_expectations: + - no agent-specific rule simulation + - no bulk import/export of rules + out_of_scope_expectations: + - billing entitlement ownership + - authorization policy enforcement + reliability: + level: R3 + name: Usable + confidence: medium + basis: consumer_quality_signals + known_reliability_risks: + - unclear timeout behavior under heavy load + - limited diagnostics for complex tenant rule conflicts + +discovery: + intent: > + Support controlled feature availability across installations, tenants, + domains, groups, users, and agents. + includes: + - feature decision evaluation + - context-aware targeting + - explainable decision result + excludes: + - user authorization + - billing entitlement ownership + - UI rendering + assumptions: + - subject and tenant context can be resolved by adjacent capabilities + use_cases: + - ucc.feature-control.tenant-toggle + - ucc.feature-control.agent-disable + - ucc.feature-control.domain-rollout + research_memos: + - specs/CapabilityMaturityStandard.md + +availability: + current_level: A4 + target_level: A6 + current_artifacts: + - feature-control/packages/feature-control-sdk + - feature-control/services/feature-control-api + target_artifacts: + - feature-control/charts/feature-control + - feature-control/platform/feature-control-service + consumption_modes: + - SDK + - service API + - managed platform service + +relations: + depends_on: + - capability.identity.vocabulary-canonicalize + supports: + - capability.registry.register + related_to: + - capability.feature-control.rollout + - capability.feature-control.visibility + +evidence: + documentation: + - specs/CapabilityMaturityStandard.md + tests: [] + consumer_feedback: [] + bug_reports: [] + incidents: [] + +consumer_guidance: + recommended_for: + - application integration through SDK or service API + - tenant-aware feature gating in helix_forge products + not_recommended_for: + - authorization decisions + - billing entitlement ownership + - assuming agent-specific simulation without checking current scope + known_limitations: + - bulk rule management is not yet covered + - agent-specific simulation remains a known gap +--- + +# Feature Availability Evaluation + +## Overview + +This capability evaluates whether a feature should be available for a subject in +a given context. It is the primary implementation-ready example in the sample +registry and demonstrates a D5/A4/C3/R3 vector. + +## Current reuse mode + +Consumers can integrate through SDK or service API artifacts in the +feature-control repository. This is implementation reuse (A4), not just planning +metadata. + +## Comparison notes + +Compared with `capability.registry.register`, this entry is far stronger on +availability and external evidence. Compared with +`capability.identity.vocabulary-canonicalize`, it is stronger on delivery mode +and weaker on cross-domain generalization. \ No newline at end of file diff --git a/registry/capabilities/capability.feature-control.rollout.md b/registry/capabilities/capability.feature-control.rollout.md new file mode 100644 index 0000000..61bc303 --- /dev/null +++ b/registry/capabilities/capability.feature-control.rollout.md @@ -0,0 +1,111 @@ +--- +id: capability.feature-control.rollout +name: Feature Rollout Control +summary: Gradually expose features to subjects across tenants, domains, groups, or cohorts using rollout rules and staged availability. +owner: feature-control +status: draft +domain: helix_forge +tags: + - feature-control + - rollout + - planning + +maturity: + discovery: + current: D4 + target: D6 + confidence: medium + rationale: > + Rollout is a distinct bounded behavior from single-point evaluation, with + research references in the feature-control domain and maturity standard. + availability: + current: A2 + target: A4 + confidence: low + rationale: > + Rollout logic may exist in source modules but is not yet consistently + exposed as a standalone SDK or API surface distinct from evaluate. + +external_evidence: + completeness: + level: C2 + name: Partial + confidence: low + basis: scope_vs_intent_and_consumer_expectations + satisfied_expectations: + - rollout concepts documented adjacent to feature evaluation + broken_expectations: + - no dedicated rollout artifact called out separately from evaluate + - percentage and cohort rollout variants not indexed independently + out_of_scope_expectations: + - billing-driven entitlements + reliability: + level: R1 + name: Fragile + confidence: low + basis: consumer_quality_signals + known_reliability_risks: + - rollout behavior may be conflated with evaluate in consumer mental models + +discovery: + intent: > + Control how features become available over time and across cohorts without + conflating rollout policy with authorization or billing. + includes: + - staged rollout rules + - cohort and context targeting for rollout + - explainable rollout state + excludes: + - one-time feature evaluation only + - authorization decisions + - billing entitlements + assumptions: + - feature evaluation capability exists for final availability decisions + use_cases: + - ucc.feature-control.domain-rollout + research_memos: + - specs/CapabilityMaturityStandard.md + +availability: + current_level: A2 + target_level: A4 + current_artifacts: + - feature-control/packages/feature-control-sdk + target_artifacts: + - feature-control/services/feature-control-api + consumption_modes: + - source module + - SDK + +relations: + depends_on: + - capability.feature-control.evaluate + supports: [] + related_to: + - capability.feature-control.visibility + +evidence: + documentation: + - specs/CapabilityMaturityStandard.md + tests: [] + consumer_feedback: [] + bug_reports: [] + incidents: [] + +consumer_guidance: + recommended_for: + - planning staged feature exposure separate from binary evaluation + not_recommended_for: + - simple on/off evaluation without rollout semantics + - entitlement or billing ownership + known_limitations: + - distinguish carefully from capability.feature-control.evaluate +--- + +# Feature Rollout Control + +## Overview + +Rollout governs how availability changes over time and across cohorts. It +complements evaluation, which answers whether a feature is available for a +subject in a context right now. \ No newline at end of file diff --git a/registry/capabilities/capability.feature-control.visibility.md b/registry/capabilities/capability.feature-control.visibility.md new file mode 100644 index 0000000..d658b03 --- /dev/null +++ b/registry/capabilities/capability.feature-control.visibility.md @@ -0,0 +1,77 @@ +--- +id: capability.feature-control.visibility +name: Feature Visibility Control +summary: Control whether features are visible or hidden for subjects without changing underlying entitlement or authorization. +owner: feature-control +status: draft +domain: helix_forge +tags: [feature-control, visibility] + +maturity: + discovery: + current: D4 + target: D5 + confidence: medium + rationale: Bounded as distinct from evaluation and rollout in feature-control domain. + availability: + current: A2 + target: A4 + confidence: low + rationale: May share SDK artifacts with evaluate but is not separately exposed as API. + +external_evidence: + completeness: + level: C2 + name: Partial + confidence: low + basis: scope_vs_intent_and_consumer_expectations + satisfied_expectations: + - visibility distinguished from evaluation in registry model + broken_expectations: + - no standalone visibility API documented separately + out_of_scope_expectations: + - authorization policy decisions + reliability: + level: R1 + confidence: low + basis: consumer_quality_signals + known_reliability_risks: + - easily conflated with evaluate capability + +discovery: + intent: Govern feature visibility separately from availability evaluation and rollout staging. + includes: + - hide/show feature UI or capability surfaces + - visibility rules per subject context + excludes: + - entitlement ownership + - rollout percentage control + use_cases: [] + +availability: + current_level: A2 + target_level: A4 + current_artifacts: + - feature-control/packages/feature-control-sdk + consumption_modes: + - source module + +relations: + depends_on: + - capability.feature-control.evaluate + related_to: + - capability.feature-control.rollout + +consumer_guidance: + recommended_for: + - planning visibility behavior separate from on/off evaluation + not_recommended_for: + - authorization or billing gating + known_limitations: + - implementation may be bundled with evaluate SDK today +--- + +# Feature Visibility Control + +Visibility governs whether a feature surface appears, distinct from whether the +feature is enabled for a subject. \ No newline at end of file diff --git a/registry/indexes/capabilities.yaml b/registry/indexes/capabilities.yaml new file mode 100644 index 0000000..bba0bf7 --- /dev/null +++ b/registry/indexes/capabilities.yaml @@ -0,0 +1,50 @@ +version: 1 +updated: '2026-06-16' +domain: helix_forge +capabilities: +- id: capability.feature-control.evaluate + name: Feature Availability Evaluation + summary: Evaluate whether a feature is active, hidden, disabled, or unavailable + for a subject in context. + vector: D5 / A4 / C3 / R3 + domain: helix_forge + status: draft + owner: feature-control + path: registry/capabilities/capability.feature-control.evaluate.md + tags: + - feature-control + - evaluation + - sdk + consumption_modes: + - SDK + - service API +- id: capability.feature-control.rollout + name: Feature Rollout Control + summary: Gradually expose features to subjects across tenants, domains, groups, + or cohorts using rollout rules. + vector: D4 / A2 / C2 / R1 + domain: helix_forge + status: draft + owner: feature-control + path: registry/capabilities/capability.feature-control.rollout.md + tags: + - feature-control + - rollout + - planning + consumption_modes: + - source module + - SDK +- id: capability.feature-control.visibility + name: Feature Visibility Control + summary: Control whether features are visible or hidden for subjects without changing + entitlement or authorization. + vector: D4 / A2 / C2 / R1 + domain: helix_forge + status: draft + owner: feature-control + path: registry/capabilities/capability.feature-control.visibility.md + tags: + - feature-control + - visibility + consumption_modes: + - source module