feature-control/specs/UseCaseCatalog.md

feature-control — Use Case Catalog

Status: Draft v0.1
Date: 2026-06-14
Owner: feature-control initiative
Conformance target: InfoTechCanon terminology (see docs/canon-mapping.md), OpenFeature SDK manifestation in consuming repositories. This catalog uses InfoTechCanon-style terminology (with explicit ownership notes to ITC-ORG, ITC-ACCESS, ITC-LAND, ITC-GOV, etc.) and introduces complementary terms only where feature availability control requires precision (e.g. qualified EvaluationScope to avoid clash with canon producer-scope / ScopePressure).

---

1. Purpose

feature-control provides a shared feature availability control infrastructure for multi-repository, multi-vendor, multi-tenant deployments.

The infrastructure shall allow repositories to adopt feature control with minimal local implementation effort while enabling platform, vendor, tenant, domain, group, user, and agent-level control over feature availability, visibility, operational safety, rollout, experimentation, and compute consumption.

In consuming repositories, the primary integration surface shall be OpenFeature. Repositories should evaluate feature decisions through standard OpenFeature SDK calls or thin organization-provided wrappers, rather than binding directly to a specific feature management backend.

---

2. Terminology alignment

This catalog uses InfoTechCanon-style terminology where possible (with explicit ITC- ownership) and introduces complementary terms where feature availability needs more precision. **See docs/canon-mapping.md (primary artifact from FEATURE-WP-0002) for full entity/relationship tables, ownership (owned vs consumed vs reference vs extension), read-model projections, gaps, validation hooks, and canon extension candidates (Feature as ProducerCapability specialization, EvaluationScope to resolve Scope clash, etc.).

A canon interface card stub is at docs/canon-interface-card.md.**

Term	Meaning in feature-control	Canon mapping (high-level)
Feature	A named capability, behavior, UI element, workflow path, integration, compute path, or configuration-controlled functional slice.	ProducerCapability (ITC-GOV extension) + Feature (extension candidate); see Scope→Ability→Capability→Feature chain
Feature Key	Stable, canonical identifier used by code and control plane.	Owned (feature-control); relates to ITC-LAND resources + Tagging
Feature Availability	Effective decision whether a feature is available, unavailable, hidden, degraded, read-only, or assigned to a variant.	Owned overlay (rich states composed from decisions)
Feature Decision	The evaluated result for a feature and context, including value, reason, source, and metadata.	ITC-GOV.Decision + Evidence + OpenFeature FlagEvaluationDetails (reason/variant/flagMetadata)
Evaluation Context	Runtime facts used to evaluate a feature: installation, deployment, tenant, vendor, domain, group, user, agent, plan, region, environment, role, etc.	OpenFeature EvaluationContext (targetingKey + custom) projected from ITC-LAND + ITC-ORG (Actor/Agent/Membership) + ITC-ACCESS
EvaluationScope / TargetingScope (qualified replacement for bare "Scope")	The level at which a feature rule or override applies, such as platform, installation, tenant, domain, group, user, or agent. (Avoids clash with canon producer scope / ScopePressure.)	ITC-ORG Membership (scope_type/scope_id) + Assignment + ITC-LAND dimensions (Environment, Deployment, Service, Repository, Tenant patterns from small-saas profile)
Entitlement	Commercial, contractual, or administrative grant that says a tenant or actor may use a feature.	ITC-ACCESS.Entitlement + Grant (consumed/reference only)
Authorization	Security decision whether an actor may perform an operation. Feature-control may inform availability but must not replace authorization.	ITC-ACCESS.AuthorizationDecision / Principal / EnforcementPoint (consumed/reference)
Visibility	UI decision whether a feature is shown, hidden, disabled, or shown as upgrade/preview.	Owned (feature-derived); distinct from availability and ITC-ACCESS AuthorizationDecision (future Landscape/Data reference possible)
Rollout	Controlled gradual exposure of a feature to a selected population.	OpenFeature variant / percentage assignment (consumed) + feature-control governance
Kill Switch	High-priority operational override used to disable or degrade a feature rapidly.	ITC-GOV Control + ITC-ACCESS AccessExceptionReference (high-precedence operational pattern owned by feature-control)
Remote Config	Feature-associated non-boolean value such as limit, threshold, model choice, provider choice, or mode.	OpenFeature structure + variant (consumed); schema governance owned by feature-control
Agent	Non-human actor, such as an AI agent, automation, bot, worker, or tool-using runtime subject.	ITC-ORG.Agent (first-class; distinct from human users)

---

3. Scope model

Feature-control must support decisions across several scope dimensions. These dimensions may be hierarchical, associative, or both.

3.1 Primary evaluation scopes / targeting dimensions (EvaluationScope)

These align to canon via ITC-ORG Membership/Assignment + ITC-LAND resources and tenant patterns (see docs/canon-mapping.md for full details and the rationale for qualifying "Scope").

EvaluationScope / Targeting Dimension	Example use	Canon anchor
Platform	Disable an unsafe feature everywhere.	ITC-GOV Control (high precedence)
Installation	Enable a feature only in a specific deployed installation.	ITC-LAND
Environment	Enable feature in dev/stage but not production.	ITC-LAND.Environment
Vendor	Allow vendor-specific capabilities or integrations.	ITC-ORG (external partner) + scoped grants
Tenant	Enable a feature for a paying customer tenant.	ITC-ORG Tenant patterns (small-saas profile: deployment separates tenants + tenant-isolation policy) + ITC-ACCESS
Domain	Enable feature only in a business or data domain.	ITC-ORG OrganizationalUnit or Tagging
Organization	Apply feature rules to a company, sub-organization, family, community, or group structure.	ITC-ORG Organization / OrganizationalUnit
Group	Beta tester group, admin group, department, support group.	ITC-ORG Group/Team or Tagging (tenant-bound)
User	Individual user preview, support override, blocked user.	ITC-ORG + ITC-ACCESS (via Membership)
Agent	Enable/disable capabilities for AI agents or automation actors.	ITC-ORG.Agent (distinct from human)
Service/Repo	Enable code path only in selected services or repositories.	ITC-LAND.Service / Repository
Deployment/Region	Region-specific or deployment-specific controls.	ITC-LAND.Deployment + Environment

3.2 Example evaluation context

{
  "targetingKey": "user:user-12345",
  "actor_type": "human",
  "installation_id": "inst-prod-eu-1",
  "environment": "production",
  "deployment_id": "k8s-prod-2026-06-14",
  "vendor_id": "vendor-binect",
  "tenant_id": "tenant-acme",
  "domain_id": "mail-dispatch",
  "organization_id": "org-acme-holding",
  "group_ids": ["group-admins", "group-beta-testers"],
  "user_id": "user-12345",
  "agent_id": null,
  "roles": ["tenant-admin"],
  "plan": "enterprise",
  "region": "eu-central",
  "application": "abholportal",
  "service": "download-service",
  "repository": "email-connect"
  // This EvaluationContext projects from ITC-LAND + ITC-ORG + ITC-ACCESS facts.
  // See docs/canon-mapping.md and EvaluationScope section.
}

3.3 Agent context example

{
  "targetingKey": "agent:invoice-classifier-v2",
  "actor_type": "agent",
  "agent_id": "invoice-classifier-v2",
  "tenant_id": "tenant-acme",
  "domain_id": "document-processing",
  "capabilities": ["classify-document", "extract-recipient"],
  "trust_level": "internal-managed",
  "environment": "production",
  "region": "eu-central"
  // Agent (ITC-ORG.Agent) + EvaluationScope; capability feature still requires separate ITC-ACCESS tool authz.
  // See docs/canon-mapping.md.
}

---

4. Decision vocabulary

Feature-control decisions should be richer than boolean values.

4.1 Availability states

State	Meaning
enabled	Feature is available and may be used, subject to authorization.
disabled	Feature is unavailable.
hidden	Feature should not be presented in normal UI.
visible_disabled	Feature is visible but not usable, often for upgrade, preview, or missing precondition.
readonly	Feature can be viewed but not modified or executed.
degraded	Feature is available in reduced mode.
variant	Feature is available with a named variant/treatment.
configured	Feature returns a structured configuration value.
unavailable	Feature cannot currently be evaluated or used.

4.2 Decision reasons

Reason	Typical source
default	No matching rule.
explicit_override	Direct scope-specific override.
entitlement_missing	Commercial/product grant absent.
authorization_denied	Security policy denied access.
kill_switch	Emergency operational disable.
dependency_unavailable	Required backend/provider unavailable.
environment_disabled	Disabled for current environment.
tenant_policy	Tenant-specific rule.
vendor_policy	Vendor-specific rule.
group_targeting	Group/segment rule matched.
user_targeting	User-level rule matched.
agent_policy	Agent/capability rule matched.
experiment_assignment	Experiment or percentage rollout.
configuration_error	Invalid or missing configuration.
fallback	Safe default used because resolver was unavailable.

---

5. Use case groups

Group A — Low-impact repository adoption

UC-A1 — Adopt feature-control in a new repository

Primary actor: Repository maintainer (see ITC-ORG Actor / Ownership)
Goal: Add feature-control without coupling the repository to a specific backend (OpenFeature surface per docs/canon-mapping.md).

Trigger: A repository introduces a capability that should be controlled at runtime (maps to ProducerCapability / Feature extension candidate).

Preconditions:

• OpenFeature SDK is available for the repository language.
• Organization-provided feature SDK wrapper or template exists (standardizes EvaluationContext projection from canon facts + safe defaults).

Main flow:

1. Maintainer adds OpenFeature SDK or organization wrapper.
2. Maintainer declares a canonical feature key (registered against the feature-control registry; owned per ITC-ORG).
3. Maintainer provides default behavior for missing/unavailable provider (fail-closed for security/compute-sensitive per category).
4. Maintainer evaluates feature decision at runtime (receives OF FlagEvaluationDetails with reason/variant; feature-control resolver composes ITC-GOV/ACCESS/LAND signals).
5. Maintainer documents feature key and lifecycle metadata (category via Tagging; temporary items link to ITC-TASK).

Outcome: Repository can evaluate feature availability with minimal local infrastructure.

Acceptance criteria:

• Repository has no direct dependency on Unleash, Flagsmith, flagd, GO Feature Flag, LaunchDarkly, or another backend unless hidden behind a provider.
• Default behavior is explicit.
• Feature key is discoverable by static scan or registry export.
• Local test provider can run without network access.

---

UC-A2 — Use a local/test provider during development

Primary actor: Developer
Goal: Run and test feature-controlled code paths locally.

Main flow:

1. Developer starts repository locally.
2. Feature-control loads local in-memory/file-based/test values.
3. Developer toggles a feature for local test.
4. Automated tests exercise enabled and disabled states.

Outcome: Feature-controlled code is testable without access to production control plane.

Acceptance criteria:

• Tests can override feature values deterministically.
• Local default values are safe.
• No production token is required for local development.

---

UC-A3 — Discover feature keys used by a repository

Primary actor: Platform engineer, architect, agentic coding assistant
Goal: Identify feature keys and metadata used in a repo.

Main flow:

1. Scanner reads repository source, schemas, and feature metadata files.
2. Scanner extracts feature keys, owners, categories, default values, and expiry dates.
3. Scanner compares code usage with control-plane registry.
4. Drift report is generated.

Outcome: Feature inventory remains transparent and governable.

Acceptance criteria:

• Unknown feature keys are detected.
• Declared-but-unused features are detected.
• Expired temporary flags are reported.

---

Group B — Release and rollout control

UC-B1 — Enable a feature for a staging environment

Primary actor: Product owner, developer, release manager
Goal: Enable a new capability in staging without changing code.

Main flow:

1. Feature exists in registry with safe production default disabled.
2. Actor enables the feature for environment staging.
3. Services receive updated evaluation results.
4. QA validates behavior.

Outcome: Feature can be tested before production release.

Acceptance criteria:

• Production remains unaffected.
• Audit log records who changed the setting and why.
• Decision explanation shows environment as source.

---

UC-B2 — Canary rollout by installation or deployment

Primary actor: Release manager, SRE
Goal: Enable a feature only in selected installations or deployments.

Main flow:

1. Actor chooses target installation/deployment.
2. Feature-control applies scoped rule.
3. Monitoring tracks feature-specific metrics.
4. Actor expands or rolls back.

Outcome: Risk is limited to selected installations.

Acceptance criteria:

• Rule scope is explicit.
• Rollback is possible without redeploy.
• Evaluations can be correlated with telemetry.

---

UC-B3 — Percentage rollout within a tenant or segment

Primary actor: Product owner, release manager
Goal: Gradually expose a feature to a fraction of users or agents.

Main flow:

1. Actor configures percentage rollout, constrained by tenant/segment.
2. Resolver assigns stable buckets using targeting key.
3. Users or agents receive deterministic decisions.
4. Rollout percentage is increased, paused, or reverted.

Outcome: Gradual rollout reduces blast radius.

Acceptance criteria:

• Assignment is stable for the same targeting key.
• Rollout can be constrained by tenant, group, environment, or domain.
• Decision reason includes rollout assignment.

---

UC-B4 — Feature variant / treatment rollout

Primary actor: Product owner, experiment owner
Goal: Return variants rather than a boolean decision.

Main flow:

1. Feature has variants such as classic, new, minimal, or llm-assisted.
2. Actor assigns variants by rule, segment, or percentage.
3. Application receives variant value through OpenFeature.
4. Application activates corresponding behavior.

Outcome: Multiple treatments can be compared or targeted.

Acceptance criteria:

• Variants are typed and documented.
• Unknown variant falls back safely.
• Variant assignment is observable.

---

Group C — Tenant, vendor, and domain availability

UC-C1 — Enable feature for one tenant

Primary actor: Platform admin, product operations, tenant admin where delegated
Goal: Make a feature available to a specific tenant.

Main flow:

1. Actor selects tenant and feature.
2. System checks whether actor is allowed to modify that scope.
3. Actor enables feature or attaches entitlement.
4. Tenant users receive feature decisions according to context.

Outcome: Tenant-specific availability is controlled centrally.

Acceptance criteria:

• Tenant A cannot affect Tenant B.
• Entitlement and feature toggle state are distinguishable.
• Audit log includes tenant scope.

---

UC-C2 — Enable vendor-specific integration

Primary actor: Platform admin, vendor admin
Goal: Enable a feature for a vendor or vendor-managed app.

Main flow:

1. Vendor integration is represented as a feature or capability.
2. Actor enables feature for vendor scope.
3. Tenant rules determine where vendor feature is available.
4. Evaluation context combines vendor and tenant information.

Outcome: Multi-vendor platform can control vendor capabilities without hard-coding.

Acceptance criteria:

• Vendor-level decision can be overridden or constrained by tenant policy.
• Feature decision explains vendor and tenant contributions.

---

UC-C3 — Domain-level feature control

Primary actor: Domain owner, platform architect
Goal: Enable feature only within a business or technical domain.

Main flow:

1. Feature is assigned to domain, e.g. mail-dispatch, identity, document-processing.
2. Actor sets domain-level availability.
3. Services include domain_id in context.
4. Resolver applies domain-specific rules.

Outcome: Large systems can control features by domain boundary.

Acceptance criteria:

• Domain membership is explicit.
• Cross-domain features identify all affected domains.
• Domain-level rules do not bypass tenant/security constraints.

---

UC-C4 — Tenant-admin self-service within delegated bounds

Primary actor: Tenant admin
Goal: Allow tenants to activate or hide eligible features for their own users.

Main flow:

1. Platform marks a feature as tenant-configurable.
2. Tenant admin sees available configuration options.
3. Tenant admin enables, disables, hides, or configures feature within limits.
4. Decisions apply only to tenant scope.

Outcome: Platform teams avoid manual tenant configuration work.

Acceptance criteria:

• Tenant admin cannot override platform kill switch, missing entitlement, or compliance restriction.
• Tenant-admin changes are audited.
• UI clearly distinguishes configurable features from locked features.

---

Group D — Group, user, and agent targeting

UC-D1 — Enable feature for a beta tester group

Primary actor: Product owner
Goal: Expose a feature to selected users across one or more tenants.

Main flow:

1. Actor defines or selects group/segment beta-testers.
2. Actor targets feature to that group.
3. Users in group receive enabled state.
4. Feedback and telemetry are collected.

Outcome: Beta features can be tested without global rollout.

Acceptance criteria:

• Group membership source is explicit.
• Tenant boundary rules are respected.
• Users removed from the group stop receiving feature access.

---

UC-D2 — User-level support override

Primary actor: Support engineer
Goal: Temporarily enable or disable a feature for one user during support or diagnosis.

Main flow:

1. Support engineer selects user and feature.
2. System requests reason and optional expiration.
3. Override is applied.
4. Decision reason shows user override.
5. Override expires or is removed.

Outcome: Support can diagnose issues without broad rollout changes.

Acceptance criteria:

• Override requires reason.
• Default expiration is enforced for temporary overrides.
• Support override cannot bypass authorization.

---

UC-D3 — Enable capability for an AI agent

Primary actor: Platform admin, agent operator
Goal: Control whether an agent may use a feature-controlled capability (see docs/canon-mapping.md: ITC-ORG.Agent + feature availability composed with ITC-ACCESS tool authorization).

Main flow:

1. Agent is identified in evaluation context (distinct actor_type: agent + Agent reference; targetingKey projection).
2. Feature represents agent capability or tool exposure (ProducerCapability / Feature extension).
3. Actor enables feature for agent, tenant, or domain EvaluationScope (Membership + ITC-LAND/ORG dimension).
4. Agent runtime evaluates capability feature before offering or invoking behavior (OpenFeature + resolver).
5. Tool authorization still validates execution server-side (ITC-ACCESS; feature availability does not replace it).

Outcome: Agent capabilities can be staged, constrained, and audited.

Acceptance criteria:

• Agent flags are separate from human UI visibility flags.
• Agent capability feature cannot replace tool authorization (ITC-ACCESS).
• Evaluation decisions are logged for sensitive agent capabilities (ITC-GOV Evidence).

---

UC-D4 — Hide feature for selected user populations

Primary actor: Product owner, UX owner
Goal: Hide a feature from users for whom it is not useful or not ready.

Main flow:

1. Actor defines visibility rule.
2. UI evaluates visibility state.
3. Hidden features are omitted from navigation and entry points.
4. Backend still enforces authorization and availability.

Outcome: UI remains simple and low-noise.

Acceptance criteria:

• Hidden does not mean unauthorized.
• Backend remains safe if user calls API directly.
• Decision differentiates hidden from disabled.

---

Group E — Compute efficiency and operational control

UC-E1 — Turn off unused compute-heavy capability for a tenant

Primary actor: Platform admin, tenant admin where delegated
Goal: Reduce compute consumption by disabling expensive features not needed by a tenant.

Main flow:

1. Feature is marked with compute/resource metadata.
2. Actor disables feature for tenant or domain.
3. Applications stop scheduling or exposing expensive compute path.
4. Metrics show reduced usage.

Outcome: Feature-control becomes a cost and sustainability tool.

Acceptance criteria:

• Disabled feature prevents background jobs where applicable.
• Compute savings are measurable.
• No user-visible broken state appears; feature is hidden or clearly unavailable.

---

UC-E2 — Disable background worker capability

Primary actor: SRE, platform admin
Goal: Stop background processing for a feature without shutting down the whole service.

Main flow:

1. Worker checks feature decision before scheduling or executing job.
2. Actor disables feature for installation, tenant, domain, or workload class.
3. Worker drains or pauses work according to safe shutdown policy.
4. Observability shows paused state.

Outcome: Operational load can be reduced granularly.

Acceptance criteria:

• Disable action is safe for in-flight work.
• Queued work is not lost without explicit policy.
• Worker behavior is observable.

---

UC-E3 — Select cheaper provider/model by remote configuration

Primary actor: Platform admin, cost owner
Goal: Use remote config to choose provider, model, or computation mode by scope.

Main flow:

1. Feature returns config such as { "mode": "cheap", "model": "small" }.
2. Service uses config to select implementation.
3. Config can vary by tenant, domain, agent, or load condition.

Outcome: Compute consumption can be actively governed without redeploy.

Acceptance criteria:

• Config values are schema-validated.
• Unknown config falls back safely.
• Decision metadata supports cost analysis.

---

UC-E4 — Emergency kill switch for failing integration

Primary actor: SRE, incident commander
Goal: Disable a failing integration or expensive dependency during an incident.

Main flow:

1. Incident commander activates kill switch.
2. Resolver gives kill switch highest precedence after security/compliance denies.
3. Affected services degrade gracefully or stop calling dependency.
4. Incident log and audit records change.

Outcome: Blast radius and cost escalation are reduced.

Acceptance criteria:

• Kill switch propagation target is defined.
• Activation requires privileged role.
• Re-enable process is explicit and auditable.

---

Group F — Entitlements, product packaging, and visibility

UC-F1 — Map feature to product package

Primary actor: Product manager, commercial owner
Goal: Control availability based on package, plan, or contract.

Main flow:

1. Product package grants entitlements to feature set.
2. Tenant is assigned plan/contract entitlements.
3. Feature decision checks entitlement before availability.
4. UI may show upsell, hidden, or disabled state.

Outcome: Product packaging and runtime availability are aligned.

Acceptance criteria:

• Entitlement missing is distinct from feature disabled.
• Commercial state is auditable.
• Feature-control does not become billing source of truth unless explicitly designed as such.

---

UC-F2 — Preview feature without full entitlement

Primary actor: Product owner, tenant admin
Goal: Show a feature as preview or upgrade path without allowing execution.

Main flow:

1. Feature visibility is set to visible_disabled for tenant.
2. UI shows preview/upgrade entry.
3. Backend rejects execution unless entitlement is granted.

Outcome: Product discovery is possible without unsafe access.

Acceptance criteria:

• API execution remains denied.
• UI reason is understandable.
• Conversion/interest tracking can be associated with feature visibility.

---

UC-F3 — Read-only feature state

Primary actor: Product owner, compliance owner
Goal: Allow viewing data but prevent modification or execution.

Main flow:

1. Feature state is set to readonly for tenant/domain/user.
2. UI exposes read actions and hides write actions.
3. Backend rejects write operations.

Outcome: Transitional, compliance, or migration states are possible.

Acceptance criteria:

• Read/write distinction is explicit.
• Backend enforcement is independent from UI display.

---

Group G — Governance, lifecycle, and architecture hygiene

UC-G1 — Register a new feature with lifecycle metadata

Primary actor: Repository maintainer, architect, product owner (ITC-ORG Ownership/Actor)
Goal: Prevent anonymous and stale flags (governed via ITC-GOV + ITC-TASK).

Main flow:

1. Feature is registered with owner (ITC-ORG), category (ITC-TaggingStandard), description, default, expected lifetime, review date, and cleanup rule.
2. Registry validates naming and required fields (Feature as ProducerCapability specialization per mapping).
3. Feature becomes available for control-plane configuration (EvaluationScope rules via ITC-ORG Membership + ITC-LAND).

Outcome: Feature inventory stays governed.

Acceptance criteria:

• Owner is required (ITC-ORG).
• Type/category is required (Tagging).
• Temporary features require expiry or review date (spawns ITC-TASK).

---

UC-G2 — Detect stale flags

Primary actor: Architect, platform engineer, agentic maintenance workflow
Goal: Avoid feature flag technical debt.

Main flow:

1. Scanner combines control-plane inventory, repository usage, and evaluation telemetry.
2. System identifies expired, unused, permanently-on, or permanently-off flags.
3. Cleanup tasks are generated.

Outcome: Feature-control supports architecture hygiene rather than long-term entropy.

Acceptance criteria:

• Stale flag report exists.
• Each stale flag has proposed action.
• Long-lived flags are justified by type.

---

UC-G3 — Explain effective decision

Primary actor: Developer, support, platform admin, tenant admin
Goal: Understand why a feature is enabled, disabled, hidden, or configured.

Main flow:

1. Actor queries decision explanation for a context.
2. Resolver returns matched rules, precedence, final value, and reason.
3. Actor can identify whether issue is default, entitlement, tenant override, user rule, kill switch, or config error.

Outcome: Multi-scope feature decisions are debuggable.

Acceptance criteria:

• Explanation API does not leak other tenants’ data.
• Production explanation access is permission-controlled.
• Decision reason is available in logs/telemetry.

---

UC-G4 — Audit feature-control changes

Primary actor: Security, compliance, platform admin
Goal: Track changes to feature availability.

Main flow:

1. Actor changes feature configuration.
2. System records actor, timestamp, scope, old value, new value, reason, approval reference, and correlation ID.
3. Audit record is immutable or append-only.

Outcome: Feature-control is suitable for production and regulated environments.

Acceptance criteria:

• Every production change has an audit record.
• Emergency changes are specially marked.
• Audit records can be exported.

---

UC-G5 — Enforce approval workflow for sensitive flags

Primary actor: Security owner, compliance owner, release manager
Goal: Prevent unsafe changes to sensitive flags.

Main flow:

1. Feature is classified as security, compliance, cost-critical, or production-critical.
2. Change request is submitted.
3. Required approvers review.
4. Change is applied after approval.

Outcome: Critical feature switches are controlled.

Acceptance criteria:

• Sensitive categories have configurable approval policy.
• Emergency path exists but is audited.
• Approval record links to change event.

---

Group H — Integration and migration

UC-H1 — Backend-agnostic provider switch

Primary actor: Platform engineer
Goal: Switch from one flag backend to another without changing repository code.

Main flow:

1. Repositories use OpenFeature APIs or wrapper.
2. Platform changes provider configuration.
3. Contract tests validate equivalent decisions.
4. Rollout proceeds by environment or installation.

Outcome: Vendor lock-in is reduced.

Acceptance criteria:

• Repositories require no code change.
• Provider-specific semantics are normalized or documented.
• Migration has verification reports.

---

UC-H2 — Import flags from existing tool

Primary actor: Platform engineer
Goal: Migrate existing flags from LaunchDarkly, Unleash, Flagsmith, static config, or custom code.

Main flow:

1. Importer reads source flags and metadata.
2. Mapping rules convert flags into feature-control schema.
3. Conflicts are reviewed.
4. Imported features are validated and activated.

Outcome: Existing systems can be assimilated.

Acceptance criteria:

• Imported feature keys are canonicalized.
• Unmapped semantics are reported.
• No production behavior changes before verification.

---

UC-H3 — Export canonical feature definitions to repos

Primary actor: Agentic coding workflow, platform engineer
Goal: Provide typed constants and documentation for repository integration.

Main flow:

1. Feature registry exports language-specific constants or generated files.
2. Repo imports generated artifact.
3. Static typing reduces feature-key typos.

Outcome: Low-friction adoption and reduced runtime errors.

Acceptance criteria:

• Generated code is deterministic.
• Feature keys include descriptions and defaults.
• Repos can update definitions through normal dependency process.

---

Group I — Observability and evidence

UC-I1 — Track feature evaluation volume

Primary actor: Platform engineer, cost owner
Goal: Understand how often features are evaluated and where.

Main flow:

1. SDK/provider emits evaluation metrics.
2. Metrics are aggregated by feature, service, environment, tenant, and decision.
3. Dashboards identify hot paths and high-cardinality risks.

Outcome: Feature-control overhead is understood and optimized.

Acceptance criteria:

• Metrics avoid leaking sensitive context values.
• Evaluation overhead is measured.
• Cache hit/miss rates are visible where applicable.

---

UC-I2 — Correlate feature decisions with incidents

Primary actor: SRE, incident commander
Goal: Determine whether a feature caused or mitigated an incident.

Main flow:

1. Incident timeline includes feature-control changes.
2. Evaluation and configuration events are queryable by time and scope.
3. Post-incident review references feature decisions.

Outcome: Feature-control supports operational learning.

Acceptance criteria:

• Changes are timestamped and attributable.
• Correlation IDs can connect deployment, flag change, and incident record.

---

UC-I3 — Track business or product outcomes from feature variants

Primary actor: Product owner, analyst
Goal: Evaluate whether feature variants improve outcomes.

Main flow:

1. Feature variant evaluation is tracked.
2. Application emits outcome event.
3. Analysis joins assignment and outcome.

Outcome: feature-control can support experimentation where needed.

Acceptance criteria:

• Tracking is opt-in and privacy-aware.
• Outcome events can be associated with feature assignment.
• Experimentation does not block core rollout control.

---

6. Cross-cutting requirements from use cases

See docs/canon-mapping.md for the detailed canon mappings that underpin these requirements (ITC-ORG for actors/memberships/agents, ITC-ACCESS for entitlement/authorization, ITC-LAND for environment/deployment/service, ITC-GOV for decisions/controls/evidence/producer-capability, Tagging + Task for categories/lifecycle).

Requirement	Derived from	Canon alignment notes
OpenFeature-first integration	UC-A1, UC-H1	OF EvaluationContext + FlagEvaluationDetails as the repo surface; resolver/composition is feature-control owned
Local/test provider	UC-A2	Supports safe defaults and testing without live canon/control-plane
Canonical feature registry	UC-A3, UC-G1	Owned by feature-control; maps to ProducerCapability + Feature extension candidate
Multi-scope context model	UC-C1, UC-C2, UC-C3, UC-D3	EvaluationScope / TargetingScope via ITC-ORG Membership + ITC-LAND dimensions
Rich decision state	UC-D4, UC-F2, UC-F3	ITC-GOV.Decision + Evidence + OF reason/variant/flagMetadata
Separate entitlement, authorization, visibility	UC-F1, UC-F2, UC-F3	ITC-ACCESS (Entitlement/Grant/AuthzDecision) consumed; visibility treated as derived (distinct from availability)
Operational kill switch	UC-E4	High-precedence ITC-GOV Control + AccessExceptionReference pattern
Compute-aware feature metadata	UC-E1, UC-E2, UC-E3	Feature as ProducerCapability with compute classification; supports cost governance
Decision explanation	UC-G3	ITC-GOV Decision + provenance; explainable via OF details + canon context projection
Audit and approval	UC-G4, UC-G5	ITC-GOV Evidence/Audit/Approval/Review
Stale flag detection	UC-G2	Spawns ITC-TASK for remediation
Provider migration support	UC-H1, UC-H2	Backend-agnostic via OF; canon for the governance/registry layer
Observability and tracking	UC-I1, UC-I2, UC-I3	Ties to ITC-GOV Evidence and ITC-ObservabilityModel

---

7. External research anchors

The following sources informed the catalog and should be reviewed during implementation. See also docs/canon-mapping.md and the local info-tech-canon repo for the semantic foundation.

OpenFeature & feature flag literature (primary repo integration surface):

• OpenFeature overview and specification: https://openfeature.dev/
• OpenFeature flag evaluation API: https://openfeature.dev/specification/sections/flag-evaluation
• OpenFeature evaluation context: https://openfeature.dev/specification/sections/evaluation-context
• OpenFeature providers: https://openfeature.dev/docs/reference/concepts/provider
• OpenFeature hooks: https://openfeature.dev/specification/sections/hooks
• OpenFeature events: https://openfeature.dev/docs/reference/concepts/events
• OpenFeature tracking: https://openfeature.dev/specification/sections/tracking
• OpenFeature SDK architecture patterns: https://openfeature.dev/blog/feature-flags-sdks-architectures
• Unleash feature flags and activation strategies: https://docs.getunleash.io/concepts/feature-flags
• Unleash activation strategies: https://docs.getunleash.io/concepts/activation-strategies
• Unleash segments: https://docs.getunleash.io/concepts/segments
• Flagsmith data model, identities, and segments: https://docs.flagsmith.com/flagsmith-concepts/data-model, https://docs.flagsmith.com/flagsmith-concepts/identities, https://docs.flagsmith.com/flagsmith-concepts/segments
• flagd: https://flagd.dev/
• GO Feature Flag relay proxy: https://gofeatureflag.org/docs/relay-proxy
• Martin Fowler / Pete Hodgson on feature toggles: https://martinfowler.com/articles/feature-toggles.html

InfoTechCanon (terminology, ownership, and integration model):

• info-tech-canon/canon.yaml and kernel (InfoTechCanonCore.md, InfoTechCanonKernelMap.md)
• ITC-ORG: infospace/models/organization/InfoTechCanonOrganizationModel.md (Actor, Agent, Membership, Tenant patterns)
• ITC-ACCESS: infospace/models/access-control/InfoTechCanonAccessControlModel.md (Entitlement, Grant, AuthorizationDecision)
• ITC-LAND: infospace/models/landscape/InfoTechCanonLandscapeModel.md (Environment, Deployment, Service, Repository)
• ITC-GOV + purpose-demand: infospace/models/governance/InfoTechCanonGovernanceModel.md and InfoTechCanonPurposeDemandExtension.md (Decision, Control, Evidence, ProducerCapability, ScopePressure)
• ITC-Tagging and ITC-TASK for categories and lifecycle work
• Relevant evaluations: infospace/evaluations/repo-scoping/comparison-report.md (Capability → Feature chain), small-saas-profile-proof.md (tenant separation examples)
• user-engine/docs/canon-mapping.md (reference alignment pattern)
• ITC workplans: ITC-WP-0006 (purpose-demand), ITC-WP-0011 (canon consumer alignment review kit)

---

8. Open questions

1. Should feature-control be mostly an integration standard first, or immediately include a custom control-plane implementation?
2. Should Unleash, Flagsmith, flagd, or GO Feature Flag be used as the initial backend?
3. Which InfoTechCanon artifact should own the canonical FeatureContext model?
4. Should product entitlements live inside feature-control or in a separate product/contract control plane consumed by feature-control?
5. How far should tenant-admin self-service go in the first version?
6. What is the minimum useful audit format compatible with the broader platform audit/evidence model?
7. Should generated feature constants be mandatory for repos, or only recommended?
8. Which feature categories require approval workflows from day one?
9. How should feature-control decisions be retained for forensic/debugging purposes without creating excessive telemetry volume?
10. How should agent capability flags integrate with future authorization and tool-use governance?