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

```json
{
  "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

```json
{
  "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?