diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e3891e0 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,176 @@ +# feature-control — Agent Instructions + +## Repo Identity + +**Purpose:** Open feature based multi-vendor, multi-tenant, multi-scope feature availability and provisioning engine. + +**Domain:** helix_forge +**Repo slug:** feature-control +**Topic ID:** `f39fa2a3-c491-414c-a91b-b4c5fcc6139c` +**Workplan prefix:** `FEATURE-WP-` + +--- + +## State Hub Integration + +The Custodian State Hub tracks work across all domains. Interact via HTTP REST — +there is no MCP server for Codex agents. + +| Context | URL | +|---------|-----| +| Local workstation | `http://127.0.0.1:8000` | +| Remote via tunnel | `http://127.0.0.1:18000` | + +### Orient at session start + +```bash +# Offline brief — works without hub connection +cat .custodian-brief.md + +# Active workstreams for this domain +curl -s "http://127.0.0.1:8000/workstreams/?topic_id=f39fa2a3-c491-414c-a91b-b4c5fcc6139c&status=active" \ + | python3 -m json.tool + +# Check inbox +curl -s "http://127.0.0.1:8000/messages/?to_agent=feature-control&unread_only=true" \ + | python3 -m json.tool +``` + +Mark a message read: +```bash +curl -s -X PATCH "http://127.0.0.1:8000/messages//read" \ + -H "Content-Type: application/json" -d '{}' +``` + +### Log progress (required at session close) + +```bash +curl -s -X POST http://127.0.0.1:8000/progress/ \ + -H "Content-Type: application/json" \ + -d '{ + "summary": "what was done", + "event_type": "note", + "author": "codex", + "workstream_id": "", + "task_id": "" + }' +``` + +Omit `workstream_id` / `task_id` when not applicable. + +### Update task status + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -H "Content-Type: application/json" \ + -d '{"status": "progress"}' +# values: wait | todo | progress | done | cancel +``` + +### Flag a task for human review + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -H "Content-Type: application/json" \ + -d '{"needs_human": true, "intervention_note": "reason"}' +``` + +--- + +## Session Protocol + +**Start:** +1. `cat .custodian-brief.md` — domain goal and open workstreams (offline-safe) +2. Check inbox: `GET /messages/?to_agent=feature-control&unread_only=true`; mark read +3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks +4. Check human-needed tasks: `GET /tasks/?needs_human=true` + +**During work:** +- Update task statuses in workplan files as tasks progress +- Record significant decisions via `POST /decisions/` + +**Close:** +1. Update workplan file task statuses to reflect progress +2. Log: `POST /progress/` with a summary of what changed +3. Note for the custodian operator: after workplan file changes, run from + `~/state-hub`: + ```bash + make fix-consistency REPO=feature-control + ``` + This syncs task status from files into the hub DB. + +--- + +## Local Developer Workflow + +This repository is documentation- and planning-focused (no source code, no traditional build/test/lint/install/run toolchain). + +**Verification and development commands (add to future sessions as needed):** +- Orient and review: `cat .custodian-brief.md` ; `cat INTENT.md SCOPE.md AGENTS.md README.md` ; `ls workplans/` +- Check hub state (requires local state-hub API): use the curl commands documented in "State Hub Integration" and "Session Protocol" sections above. +- After any workplan or doc changes: From `~/state-hub` checkout, run `make fix-consistency REPO=feature-control` (syncs markdown task statuses into hub DB, updates brief, populates state_hub_* IDs). +- Update task status in workplan files (use search_replace or equivalent) then re-run fix-consistency. +- Log required progress: `curl -s -X POST http://127.0.0.1:8000/progress/ ...` (see protocol). +- To verify changes post-fix: Re-`cat .custodian-brief.md`, re-`ls workplans/`, re-check task statuses in files vs hub queries, confirm no drift. + +No `make install`, `make test`, `make lint`, `make build`, or `make run` apply yet (pure docs repo). If implementation artifacts (e.g. OpenFeature wrappers, providers, or example code) are added later, define and document the appropriate commands here and in relevant workplans. + +## Workplan Convention (ADR-001) + +Work items originate as files in this repo — not in the hub. The hub is a +read/cache/index layer that rebuilds from files. + +**File location:** `workplans/FEATURE-WP-NNNN-.md` + +**Archived location:** finished workplans may move to +`workplans/archived/YYMMDD-FEATURE-WP-NNNN-.md`. The `YYMMDD` prefix is +the completion/archive date; the frontmatter `id` does not change. + +**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use +`workplans/ADHOC-YYYY-MM-DD.md` with task ids `ADHOC-YYYY-MM-DD-T01`, etc. Use +this only for low-risk work completed directly; create a normal workplan for +anything needing analysis, design, approval, dependencies, or multiple phases. + +**Frontmatter:** + +```yaml +--- +id: FEATURE-WP-NNNN +type: workplan +title: "..." +domain: helix_forge +repo: feature-control +status: proposed | ready | active | blocked | backlog | finished | archived +owner: codex +topic_slug: ... +created: "YYYY-MM-DD" +updated: "YYYY-MM-DD" +state_hub_workstream_id: "" # written by fix-consistency — do not edit +--- +``` + +Use `proposed` for a new draft, `ready` after review against current repo +state, and `finished` after implementation. `stalled` and `needs_review` are +derived health labels, not frontmatter statuses. + +**Task block format** (one per `##` section): + +``` +## Task Title + +` ` `task +id: FEATURE-WP-NNNN-T01 +status: wait | todo | progress | done | cancel +priority: high | medium | low +state_hub_task_id: "" # written by fix-consistency — do not edit +` ` ` + +Task description text. +``` + +Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work. + +To create a new workplan: +1. Write the file following the format above +2. Notify the custodian operator to run `make fix-consistency REPO=feature-control` + (or send a message to the hub agent via `POST /messages/`) diff --git a/INTENT.md b/INTENT.md new file mode 100755 index 0000000..dc7b2ee --- /dev/null +++ b/INTENT.md @@ -0,0 +1,359 @@ +# feature-control — INTENT + +Status: Draft v0.1 +Date: 2026-06-14 +Owner: feature-control initiative +Repository role: Umbrella repository for feature availability control infrastructure +Primary repo-facing standard: OpenFeature +Terminology alignment: InfoTechCanon-compatible; extends InfoTechCanon where feature availability requires additional precision. See `docs/canon-mapping.md` (delivered via FEATURE-WP-0002) for detailed mappings, ownership boundaries (consumed ITC-ORG/ACCESS/LAND/GOV vs owned Feature availability control), the EvaluationScope terminology decision, OpenFeature grounding, and proposed canon extensions (Feature as ProducerCapability specialization etc.). + +--- + +## 1. Intent + +`feature-control` exists to provide a shared, low-impact, cross-repository infrastructure for controlling feature availability in multi-vendor, multi-tenant, multi-domain software landscapes. + +The project enables software systems to ship code independently from feature availability decisions. It allows platform operators, product owners, tenant administrators, SREs, developers, and agent operators to turn features on, off, hidden, visible-disabled, read-only, degraded, variant-controlled, or remotely configured at runtime without redeploying consuming repositories. + +In consuming repositories, `feature-control` should manifest primarily as **OpenFeature** usage. Repositories should not depend directly on a concrete feature flag backend. They should evaluate feature decisions through OpenFeature SDKs, thin organization-provided wrappers, canonical feature keys, generated constants, and test/local providers. + +--- + +## 2. Why this project exists + +Modern platform landscapes need to release continuously while controlling what is available to whom, where, and under which operational conditions. + +Without a shared feature-control infrastructure, repositories tend to accumulate ad hoc booleans, tenant-specific branches, hidden configuration switches, and poorly documented rollout logic. This leads to hard-coded customer behavior, unnecessary compute consumption, unsafe emergency handling, unclear ownership, and architectural erosion. + +`feature-control` addresses this by introducing a canonical feature availability model, OpenFeature-based repository integration, backend-independent provider architecture, explainable feature decisions, governance rules, lifecycle management, auditability, and operational controls. + +The project is intended to help establish good architecture, reduce unnecessary compute usage, and keep feature availability decisions explicit, observable, and reversible. + +--- + +## 3. Core stance + +`feature-control` treats feature flagging as one mechanism inside a broader **feature availability control plane**. + +It explicitly distinguishes: + +| Concern | Meaning | +|---|---| +| Feature availability | Whether a feature is effectively enabled, disabled, hidden, degraded, read-only, or variant/config controlled. | +| Entitlement | Whether a tenant, customer, vendor, organization, user, or agent has been granted commercial or administrative access. | +| Authorization | Whether an actor is permitted to perform an operation according to security policy. | +| Visibility | Whether the user interface should show, hide, disable, or expose a feature as preview/upgrade. | +| Operational control | Whether a feature should be disabled, degraded, or rerouted for safety, incident handling, dependency failure, or compute control. | + +Feature-control may compose signals from entitlement, authorization, policy, and operations, but it must not become the sole authorization system. Security-critical access must still be enforced by backend authorization and policy checks. + +--- + +## 4. Scope + +The project covers the standards, models, infrastructure, APIs, provider integrations, tooling, and governance needed to control feature availability across repositories and deployments. + +### In scope + +- Canonical feature terminology and metadata. +- Feature key naming conventions. +- OpenFeature-based repository integration guidance. +- Evaluation context model for multi-scope decisions. +- Decision model with value, reason, source, and metadata. +- Scope model for platform, installation, environment, deployment, vendor, tenant, domain, organization, group, user, service, repository, and agent. +- Backend provider abstraction and adapter strategy. +- Local/test provider support for low-friction adoption. +- Runtime evaluation, caching, fallback, and safe defaults. +- Feature lifecycle governance and stale-flag cleanup. +- Audit logging for feature changes. +- Operational kill switches and degraded modes. +- Compute-control use cases, such as disabling expensive processing paths per tenant or installation. +- Agent-aware capability availability control. +- Integration points with InfoTechCanon, IAM, entitlement, policy, observability, and deployment infrastructure. + +### Out of scope for the first stage + +- Replacing the central authorization system. +- Replacing product billing, contract management, or entitlement source-of-truth. +- Requiring all repositories to adopt a custom SDK instead of OpenFeature. +- Building a full experimentation analytics suite as the first milestone. +- Treating client-side feature flags as security enforcement. +- Becoming a generic configuration database for unrelated application settings. +- Forcing a final backend decision before practical implementation learning has been gathered. + +--- + +## 5. Design principles + +### 5.1 OpenFeature first + +Repository code should depend on OpenFeature concepts, not a specific vendor or backend. This keeps adoption lightweight and preserves backend reversibility. + +### 5.2 Low impact on consuming repositories + +A repository should be able to start with: + +- one dependency or wrapper; +- a small number of feature evaluations; +- canonical feature keys; +- local defaults; +- test-provider support; +- no direct dependency on the control-plane backend. + +### 5.3 Explicit decisions, not mysterious booleans + +A feature evaluation should be explainable. The decision should make clear what value was returned, why, from which scope, under which context, and with which fallback behavior. + +### 5.4 Separate concerns, compose decisions + +Feature availability, entitlement, authorization, visibility, rollout, and operational safety should remain conceptually distinct, even when composed into one effective runtime decision. + +### 5.5 Safe defaults + +Every feature must have a safe default. Evaluation failure must be predictable and appropriate for the feature category. Security-sensitive and costly features should usually fail closed. + +### 5.6 Governance without friction + +The infrastructure should improve architecture and operations without creating excessive process overhead. Temporary release flags should be easy to create and remove; sensitive production flags should be controlled and audited. + +### 5.7 Compute efficiency as a first-class use case + +Feature-control should help systems avoid running capabilities that are not needed, not entitled, not used, not trusted, or temporarily too expensive. + +### 5.8 Agent-aware but security-conscious + +Agents, automation actors, and workers are first-class evaluation subjects. Feature-control may gate agent capabilities, but actual tool execution must still be authorized by the relevant security and policy systems. + +--- + +## 6. Canonical concepts + +| Concept | Meaning | +|---|---| +| Feature | A named capability, behavior, UI element, workflow path, integration, compute path, or configuration-controlled functional slice. | +| Feature Key | Stable identifier used by code and control plane. | +| Feature Availability | Effective availability state of a feature for a context. | +| Feature Decision | Evaluated result including value, reason, source, and metadata. | +| Evaluation Context | Runtime facts used to evaluate a feature decision. | +| Scope | Level or dimension where a rule or override applies. | +| Feature Rule | Conditional logic that contributes to a feature decision. | +| Segment | Reusable group or condition set for targeting. | +| Variant | Alternative treatment, mode, or value of a feature. | +| Remote Config | Feature-associated value such as threshold, limit, model, provider, or mode. | +| Kill Switch | High-priority operational override to disable or degrade behavior quickly. | +| Entitlement | Commercial, contractual, or administrative grant. | +| Visibility | UI presentation state derived from or related to feature availability. | +| Agent | Non-human actor such as AI agent, automation, bot, worker, or tool-using runtime subject. | + +--- + +## 7. Expected repository experience + +A consuming repository should experience feature-control as a small, predictable integration pattern. + +Example developer flow: + +1. Add OpenFeature SDK or organization wrapper. +2. Import generated feature keys or declare a new key through the canonical process. +3. Provide a safe default. +4. Evaluate a feature decision using a context. +5. Add tests with a local/test provider. +6. Document feature ownership and lifecycle metadata. +7. Avoid direct backend-specific calls unless implementing a provider or platform component. + +Example pseudo-flow: + +```text +Repository code + -> feature-control wrapper / OpenFeature client + -> provider + -> feature-control backend or local evaluator + -> FeatureDecision + -> runtime behavior +``` + +--- + +## 8. Infrastructure shape + +The project may evolve into multiple components, but the umbrella intent remains stable. + +Potential components: + +| Component | Purpose | +|---|---| +| feature-canon | Canonical terminology, schemas, naming, and lifecycle rules. | +| feature-sdk | Thin organization wrappers and generated constants around OpenFeature. | +| feature-provider | Provider adapters for selected backends and local/test modes. | +| feature-control-api | Internal management and evaluation APIs. | +| feature-control-ui | Administration UI for platform, vendor, tenant, domain, group, user, and agent scopes. | +| feature-resolver | Decision composition engine for rules, overrides, entitlements, policies, and fallbacks. | +| feature-audit | Append-only audit trail for changes and decisions where required. | +| feature-sync | GitOps import/export and synchronization with repositories. | +| feature-observe | Metrics, evaluation logs, stale-flag detection, and operational insight. | + +The first implementation may use an existing backend such as Unleash, Flagsmith, flagd, GO Feature Flag, or another OpenFeature-compatible provider. The architecture should remain backend-reversible. + +--- + +## 9. Relationship to InfoTechCanon + +`feature-control` should conform to InfoTechCanon terminology where possible and extend it where feature availability requires more precise concepts. The authoritative reference is `docs/canon-mapping.md` (produced under FEATURE-WP-0002), which contains entity/relationship tables, ownership (e.g. Entitlement/Grant and AuthorizationDecision under ITC-ACCESS; Environment/Deployment/Service/Repository under ITC-LAND; Actor/Agent/Membership under ITC-ORG; Decision/Evidence/ProducerCapability under ITC-GOV + purpose-demand), the qualified EvaluationScope term (to avoid clash with canon producer-scope / ScopePressure), gaps, validation hooks, and extension candidates. + +Expected alignment points (see mapping for details + ITC IDs): + +- identity and actor modeling (ITC-ORG Actor/Agent/Person + ITC-ACCESS Subject/Principal); +- tenant/vendor/organization/community modeling (ITC-ORG + small-saas tenant patterns); +- access control and authorization terminology (ITC-ACCESS); +- policy and governance concepts (ITC-GOV, including Purpose, ScopePressure, Decision, Evidence); +- deployment and installation terminology (ITC-LAND); +- operational control and observability; +- canonical data model conventions; +- task/tag/lifecycle governance (ITC-TASK + TaggingStandard). + +Expected extensions (proposed in the mapping for assimilation): + +- feature availability decision model; +- feature key canon; +- feature lifecycle taxonomy (on top of Task + Governance); +- feature evaluation context (OF + canon fact projection); +- feature visibility semantics (distinct derived concern); +- rollout and variant semantics (OF-native + governance); +- agent capability availability controls (ITC-ORG.Agent + ITC-ACCESS); +- compute-control feature patterns. + +Where overlap exists with access control, feature-control should avoid redefining authorization. It should instead describe how authorization and policy signals are referenced, composed, or checked alongside feature availability (per the strong boundaries in the mapping and PRD/UCC FR-7/FR-8). + +--- + +## 10. Initial lifecycle model + +Every feature should have lifecycle metadata. + +Suggested lifecycle states: + +```text +proposed +registered +implemented +internal +preview +beta +general-availability +deprecated +sunset +removed +``` + +Suggested flag categories: + +```text +release +experiment +operational +entitlement +visibility +migration +remote-config +compute-control +agent-capability +compliance +``` + +Temporary flags should have an expected removal or review date. Long-lived flags should be explicitly classified and owned. + +--- + +## 11. Initial success criteria + +The project is successful when: + +1. A repository can adopt feature-control using OpenFeature with minimal code changes. +2. A feature can be controlled per installation, tenant, group, user, and agent. +3. A feature decision can explain its value, source, and reason. +4. Expensive compute paths can be disabled where not needed. +5. Emergency kill switches can be applied without redeployment. +6. Feature availability is not confused with authorization. +7. Feature metadata includes owner, category, lifecycle, and safe default. +8. Tests can run without a live backend. +9. Backend choice remains reversible. +10. The model fits naturally into InfoTechCanon terminology. + +--- + +## 12. First milestones + +### M1 — Canonical model + +Create schemas and terminology for feature keys, metadata, evaluation context, decision states, decision reasons, scopes, and lifecycle. + +### M2 — Repository integration pattern + +Define the OpenFeature wrapper pattern, generated constants approach, test-provider pattern, and low-impact adoption guide. + +### M3 — Backend evaluation spike + +Compare Unleash, Flagsmith, flagd, and GO Feature Flag against the canonical model and integration requirements. + +### M4 — Resolver and decision explanation + +Prototype effective decision composition across defaults, scopes, overrides, entitlements, visibility, and operational kill switches. + +### M5 — Compute-control pilot + +Apply feature-control to one expensive or optional background capability and measure reduction in unnecessary work. + +### M6 — Tenant and agent pilot + +Control one tenant-level feature and one agent capability using the shared evaluation context. + +--- + +## 13. Open questions + +1. Which backend should be used for the first operational implementation? +2. Should feature-control own an internal resolver, or initially delegate rule evaluation to an existing backend? +3. Which feature metadata should be mandatory from day one? +4. How tightly should entitlement data be integrated into feature decisions? +5. Which decisions require audit at evaluation time, not only at change time? +6. How should tenant-admin self-service be bounded? +7. How should feature keys be namespaced across repos and domains? +8. How should stale-flag cleanup be enforced? +9. Which features should fail open, fail closed, or fail degraded? +10. How should agent capability flags integrate with tool authorization and policy enforcement? + +--- + +## 14. Repository documentation set + +This repository should initially contain: + +```text +INTENT.md +ProductRequirementsDocument.md +UseCaseCatalog.md +``` + +Likely next documents: + +```text +ArchitectureOverview.md +FeatureContextSchema.md +FeatureDecisionSchema.md +FeatureKeyNamingStandard.md +OpenFeatureIntegrationGuide.md +BackendEvaluation.md +LifecycleAndGovernanceStandard.md +ComputeControlPatterns.md +AgentCapabilityControl.md +``` + +--- + +## 15. Stable intent vs evolving scope + +The stable intent of `feature-control` is to provide a shared, low-impact, OpenFeature-based control infrastructure for feature availability across multi-vendor, multi-tenant software landscapes. + +The implementation scope may evolve as practical learning accumulates. Backend choice, component boundaries, UI depth, resolver complexity, and entitlement integration are expected to change through experiments and pilots. + +The project should preserve the stable intent while allowing the actual scope to adapt. diff --git a/README.md b/README.md index 6817283..e6131c2 100644 --- a/README.md +++ b/README.md @@ -1 +1,11 @@ -Open feature based multi-vendor, multi-tenant, multi-scope feature availability and provisioning engine. \ No newline at end of file +Open feature based multi-vendor, multi-tenant, multi-scope feature availability and provisioning engine. + +See: +- INTENT.md (stable intent) +- docs/canon-mapping.md (terminology, mappings to ITC-ORG/ACCESS/LAND/GOV, extensions) +- workplans/FEATURE-WP-0001-statehub-bootstrap.md (complete) +- workplans/FEATURE-WP-0002-canon-prd-ucc-alignment.md (complete) +- specs/ProductRequirementsDocument.md and UseCaseCatalog.md (canon-aligned PRD/UCC) +- AGENTS.md (protocol) + +Bootstrap and canon alignment workstreams finished 2026-06-14. \ No newline at end of file diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..dc7c6e6 --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,36 @@ +# SCOPE + +## One-liner + +Open feature based multi-vendor, multi-tenant, multi-scope feature availability and provisioning engine. + +## Core Idea + +feature-control exists to provide the capability described in INTENT.md (canonical feature availability control plane using OpenFeature for repos, with multi-scope governance, compute control, agent capabilities, and InfoTechCanon alignment). + +## In Scope + +- Maintain INTENT.md, specs/ProductRequirementsDocument.md (PRD), specs/UseCaseCatalog.md (UCC), docs/canon-mapping.md, docs/canon-interface-card.md (stub), workplans/ (FEATURE-WP-0001 bootstrap + FEATURE-WP-0002 canon alignment). +- Keep docs, operational metadata, and hub integration current. +- Execute workplans per AGENTS.md session protocol (orientation, task status updates in files, progress events, fix-consistency). +- Refine terminology and models for canon compatibility (EvaluationScope, ITC-ORG/ACCESS/LAND/GOV consumption, ProducerCapability/Feature extensions). + +## Out of Scope + +- Own unrelated adjacent systems (e.g. core entitlement, full authorization, billing). +- Make irreversible operational decisions without human approval. +- Implement backend providers, SDKs, or control plane code (documentation and planning phase only). + +## Current State + +- Bootstrap State Hub integration (FEATURE-WP-0001) complete (T01-T03 done). +- Canon terminology alignment and PRD/UCC improvements (FEATURE-WP-0002) complete (T01-T10 done; 10/10 progress). +- Status: active; docs and workplans stabilized. Future implementation work (e.g. pilots) may use new workplans. + +## Getting Oriented + +- Start with: INTENT.md +- Agent instructions: AGENTS.md +- Workplans: workplans/ +- Canon mapping: docs/canon-mapping.md +- Verify: cat .custodian-brief.md ; ls workplans/ ; from ~/state-hub: make fix-consistency REPO=feature-control diff --git a/docs/canon-interface-card.md b/docs/canon-interface-card.md new file mode 100644 index 0000000..3e1e849 --- /dev/null +++ b/docs/canon-interface-card.md @@ -0,0 +1,44 @@ +# feature-control — Canon Interface Card (Stub) + +**Status:** draft (per FEATURE-WP-0002 T09) +**Date:** 2026-06-14 +**Based on:** info-tech-canon/infospace/agent/briefs/consumer-brief.template.md and interface-card.schema.yaml + +## Produced Concepts +- Feature (as ProducerCapability specialization + availability control) +- FeatureKey +- EvaluationScope / TargetingScope (EvaluationContext dimension) +- FeatureDecision (with rich states, reasons) +- FeatureAvailability / states +- Feature registry & lifecycle hygiene patterns +- Multi-signal composition (entitlement + kill + policy + etc.) + +## Consumed Concepts (from InfoTechCanon) +- ITC-ORG: Actor, Agent, Membership, Organization/Unit, Ownership, Tenant patterns +- ITC-ACCESS: Entitlement, Grant, AuthorizationDecision, Subject/Principal +- ITC-LAND: Environment, Deployment, Service, Repository, RuntimeResource +- ITC-GOV: Decision, Control, Evidence, Policy, ProducerCapability, ScopePressure, PurposeFit +- ITC-TaggingStandard: for feature categories +- ITC-TASK: for reviews, expiry, stale-flag cleanup, remediation + +## Purpose / Consumer Demand +- Low-impact OpenFeature-based adoption for repos (agentic + human devs) +- Compute governance and cost control via capability flags +- Operational safety (kill switches, degraded modes) +- Agent capability gating (with separate authz) +- Multi-tenant / multi-vendor / multi-scope availability without hard-coding + +## Scope Pressure / Evolution Requests +- Need for first-class Feature/FeatureAvailability in canon (currently extension candidate) +- Clarification on EvaluationScope vs producer-scope terminology +- Interface for feature registry export to repos (GitOps + generated constants) +- Patterns for multi-signal decision composition + +## References +- docs/canon-mapping.md (primary detailed mapping) +- workplans/FEATURE-WP-0002-canon-prd-ucc-alignment.md +- specs/ProductRequirementsDocument.md and UseCaseCatalog.md (canon-aligned) +- info-tech-canon/infospace/ (models, evaluations, schemas) +- OpenFeature spec for the repo integration surface + +This stub can be expanded into a full consumer brief or validated against canon review-kit once ITC-WP-0011 stabilizes. See FEATURE-WP-0002 T08/T09 for extension proposals. \ No newline at end of file diff --git a/docs/canon-mapping.md b/docs/canon-mapping.md new file mode 100644 index 0000000..ba9809c --- /dev/null +++ b/docs/canon-mapping.md @@ -0,0 +1,139 @@ +# Canon Mapping + +**Status:** draft +**Updated:** 2026-06-14 +**Repo:** feature-control +**Related:** INTENT.md, specs/ProductRequirementsDocument.md (PRD), specs/UseCaseCatalog.md (UCC), docs/feature-management-model.md (TBD per T02) + +This document maps current `feature-control` concepts (from INTENT, PRD, and UCC) to identity-canon and **InfoTechCanon** concepts. It is intentionally explicit about owned facts, consumed facts, references, proposed extensions, and gaps. It follows the pattern established in `user-engine/docs/canon-mapping.md` and aligns with canon review-kit expectations (interface cards, consumer briefs, alignment reviews). + +## Mapping Stance + +`feature-control` exists to provide a shared, low-impact, cross-repository infrastructure for **feature availability control** in multi-vendor, multi-tenant, multi-domain software landscapes. + +It treats feature flagging as one mechanism inside a broader **feature availability control plane**. Primary manifestation in consuming repositories is **OpenFeature** (SDKs + thin organization wrappers + generated constants + local/test providers). Repositories must not bind directly to a concrete backend. + +`feature-control` **consumes** InfoTechCanon for organizational structure, access semantics, landscape resources, governance decisions/evidence, and tagging. It **extends** the canon (via proposed concepts) where feature availability, multi-source decision composition, rich availability states, evaluation scoping, lifecycle hygiene for flags, and compute/agent capability control require additional precision. + +It **must not**: +- Replace central authorization (ITC-ACCESS + Governance). +- Own the source-of-truth for commercial entitlements (ITC-ACCESS.Entitlement / Grant). +- Collapse availability, entitlement, authorization, and UI visibility. + +"Scope" (unqualified) in current feature docs is a terminology clash with canon's producer-scope / scope-pressure usage (see ITC-GOV purpose-demand extension and Core). We qualify it going forward (see below). + +## Entity Mapping + +| feature-control concept | Canon concept | Ownership | Notes | +| --- | --- | --- | --- | +| `Feature` (named capability, behavior, UI element, workflow path, compute path, or config-controlled slice) | `ProducerCapability` (Governance ext) + `Feature` (extension candidate) | owned (feature-control) + extension proposed to canon | See repo-scoping "Scope → Ability → Capability → Feature → Evidence → Observed Fact" chain and purpose-demand ProducerCapability. feature-control owns availability control, registry, and OpenFeature surface. | +| `FeatureKey` | Stable identifier (no direct single owner; relates to Landscape resource + Tagging) | owned (feature-control) | Immutable once used; namespaced `..[.]`. | +| `FeatureAvailability` / availability states (enabled, disabled, hidden, visible_disabled, readonly, degraded, variant, configured, unavailable, fallback) | (derived state from Decision + Control) | owned (feature-control overlay) | Richer than boolean. Composed from multiple signals. Maps to OpenFeature value + reason + variant + flagMetadata. | +| `FeatureDecision` (value, state, reason, source, scope, fallback, variant, config, evaluated_at, metadata) | `Governance Decision` + `Evidence` + OpenFeature `FlagEvaluationDetails` (reason, variant, flagMetadata) | owned overlay (feature-control) on consumed ITC-GOV + OF | Precedence (kill_switch > ... > default) is feature-control policy. Must be explainable. | +| `EvaluationContext` (targetingKey + installation_id, environment, tenant_id, domain_id, organization_id, user_id, agent_id, actor_type, roles, plan, region, service, repository, etc.) | OpenFeature `EvaluationContext` (targetingKey + custom fields) composed from ITC-LAND (Environment, Deployment, Service, Repository, RuntimeResource) + ITC-ORG (Actor, Agent, Membership, Tenant patterns) + ITC-ACCESS facts | consumed structure (OF) + projection/reference (canon models) | Strict merge precedence per OF spec. targetingKey is principal/subject projection. Minimize sensitive attributes and high cardinality. "domain" (OF) is client/provider binding — distinct from business `domain_id`. | +| `EvaluationScope` / `TargetingScope` / `FeatureRuleScope` (proposed) (platform, installation, environment, deployment, vendor, tenant, domain, organization, group, user, agent, service/repository) | `Membership` (scope_type + scope_id) + `Assignment` + ITC-LAND / ITC-ORG dimensions (Tenant in profiles, OrganizationalUnit, Environment/Deployment/Service/Repository, Group/Team) | reference + extension candidate (`EvaluationScope`) | Replaces unqualified "Scope" / "scope_type" / "scope_id" to avoid clash with canon producer scope / ScopePressure. Tenant patterns from small-saas profile (deployment separates tenants + tenant-isolation policy). | +| `Entitlement` | `Entitlement` + `Grant` (ITC-ACCESS) | consumed / reference | Commercial/contractual/administrative grant. feature-control composes (e.g. disabled_by_entitlement) but does not own or replace source-of-truth. | +| `Authorization` / `authorization_denied` | `AuthorizationDecision` / `Principal` / `EnforcementPoint` (ITC-ACCESS) | consumed / reference | feature-control may emit signals but must never be trusted as final security enforcement (client-side or otherwise). | +| `Visibility` (hidden, visible_disabled, visible preview, readonly, admin-only...) | (no strong direct owner yet; presentation / UI concern) | owned (feature-control for feature-derived visibility) / future reference to Landscape or Data | Must remain distinct from availability and from AuthorizationDecision. Backend enforcement independent of UI state. | +| `Agent` (non-human actor) | `Agent` (ITC-ORG) | consumed / reference | First-class evaluation subject. Agent capability features require both feature availability + separate tool authorization (Access). | +| `Kill Switch` | `Control` + `AccessExceptionReference` (ITC-GOV + ITC-ACCESS) | reference + owned operational pattern (feature-control) | Highest practical precedence after security/compliance hard deny. Auditable, reversible, fast propagation for availability. | +| `Remote Config` / `Variant` / rollout treatment | OpenFeature structure value + `variant` in resolution details | consumed (OF) + owned governance/validation (feature-control) | Typed values with schemas. Unknown falls back safely. | +| `Segment` / `Group` (beta-testers, etc.) | `Group` / `Team` (ITC-ORG) or `Tagging` selector (with tenant boundaries) | reference | Reusable; membership source documented; respects tenant/environment. | +| `FeatureRule` / `FeatureOverride` | `Policy` / `Rule` / `Control` + binding (ITC-GOV) | reference + owned (feature-control) | Scoped application via EvaluationScope/Membership. | +| `FeatureLifecycleRecord` / states (proposed, registered, implemented, internal, preview, beta, general-availability, deprecated, sunset, removed) + categories (release, experiment, operational, entitlement, compute_control, agent_capability...) | `Task` (ITC-TASK) for reviews/expiry/cleanup + `Governance` states/approvals + `TaggingStandard` for categories | reference | Temporary flags require review/expiry date (spawns Task). Long-lived require explicit justified category + owner (ORG Ownership). Removed flags must be purged from code + control plane. | +| `Owner` / owning repo/service/domain | `Ownership` / `Stewardship` / `Actor` (ITC-ORG) | reference | Mandatory for registration. | +| `AuditEvent` | `Evidence` / `Audit` (ITC-GOV) | reference (local + export) | Append-only / tamper-evident for production-impacting changes. | +| `Approval` (for sensitive changes) | `Approval` / `Review` (ITC-GOV) | reference | Policy-driven; emergency path audited + reconciled. | + +## Relationship Mapping + +| Relationship | Source | Target | Implementation source / notes | +| --- | --- | --- | --- | +| `controls_availability_of` | Feature / FeatureRule | ProducerCapability / Landscape resource (Service, Endpoint, etc.) | feature-control registry + resolver | +| `evaluated_in` | FeatureDecision | EvaluationContext (projected canon facts) | OpenFeature client + feature-control resolver | +| `scoped_via` | FeatureRule / Override | EvaluationScope (Membership + Landscape/Org dimension) | tenant_id etc. become scoped Membership or Assignment facts | +| `composes_from` | FeatureDecision | Entitlement (ITC-ACCESS), Governance Decision/Control, AuthorizationDecision | Multi-source precedence (kill > entitlement > policy > default) | +| `owned_by` | Feature | Actor / Team / OrganizationalUnit (ITC-ORG) | Required metadata | +| `categorized_by` | Feature | Tag (ITC-TaggingStandard) | release / compute_control / agent_capability etc. | +| `generates_task_for` | Temporary Feature / stale flag | Task (ITC-TASK) | review, expiry, cleanup, removal | +| `emits_evidence_for` | Feature change / decision | Evidence (ITC-GOV) | audit + explanation | +| `informs_but_does_not_replace` | FeatureAvailability / Decision | AuthorizationDecision (ITC-ACCESS) | explicit boundary | +| `projects_to` | Canon facts (Actor/Agent, Tenant, Environment, Service, Entitlement, Grant) | OpenFeature EvaluationContext + targetingKey | identity_context / landscape / access projection pattern (see user-engine) | + +## Read Model / Projection Surface (for resolvers, SDK wrappers, explanations, scanners) + +A canon-aligned feature evaluation / explanation surface should expose (without leaking cross-tenant data): + +- Normalized Actor / Agent (from ITC-ORG, projected from IAM or agent identity). +- Memberships and scoped Assignments (tenant, organization, group, team). +- Landscape facts in context (Environment, Deployment, Service, Repository, Installation). +- Entitlement / Grant references (ITC-ACCESS). +- Effective FeatureDecision with reason taxonomy, source (rule/override/kill/etc.), variant, config, and provenance links to Governance Decision / Evidence where applicable. +- OpenFeature EvaluationDetails (value + reason + variant + flagMetadata) as the repo-visible contract. +- Gaps explicitly called out (e.g., "no matching entitlement record"). + +Local/test providers and generated constants must be usable without live canon or control-plane data. + +## Current Gaps (feature-control side) + +- `Natural Person` not modeled (consistent with user-engine). Agent vs human must remain distinct in context and rules. +- Strong/weak identity linking and synonymity assertions are external (identity-canon). +- Full `Organization` / `Vendor` / `Legal Entity` / `Customer` modeling is referenced via tenant + external identifiers (small-saas profile uses tenant separation). +- Presentation/Visibility semantics have no deep canon owner yet (future Landscape/Data or profile concern). feature-control owns the feature-derived portion only. +- `Scope` (bare) term clash in prior feature docs vs canon producer-scope / ScopePressure. Mitigated by introducing EvaluationScope / TargetingScope. +- No native first-class `Feature` / `FeatureAvailability` / `FeatureDecisionRecord` / `EvaluationScope` in current canon seed (these are the primary extension candidates feature-control will propose). +- Multi-signal composition logic (entitlement + kill switch + policy + experiment + compute cost) and rich availability state machine are feature-control owned (not generalized in canon yet). +- Cross-tenant leakage prevention in explanations, metrics, and context must be explicit (enforced in resolver + API layers). + +## Validation Hooks / Checks (to be implemented in tests + scanners + CI) + +- Feature registration requires owner (ORG Ownership reference) and category (Tagging). +- Temporary features carry review/expiry date that spawns or links to a Task. +- FeatureDecision always distinguishes `entitlement_missing` from `disabled_by_flag` / `kill_switch` etc. +- Agent contexts use distinct `actor_type: agent` + Agent reference (never conflated with human User). +- No unqualified "Scope" / "scope_type" remains in canon-facing text, schemas, or examples (use EvaluationScope or explicit Membership dimension). +- EvaluationContext projection never includes raw PII or high-cardinality fields by default; explanations respect tenant boundaries. +- OpenFeature evaluation contract honored: always returns default on error path; never throws from hot evaluation; detailed results include reason/variant/flagMetadata. +- Backend provider can be swapped (via OF) without changing repo integration or feature keys. +- Stale / permanently-on flags are reported and linked to Task remediation. +- References to canon concepts include short owner IDs (e.g. "ITC-ACCESS.Entitlement", "ITC-LAND.Environment", "ITC-GOV.Decision"). + +These checks can live in feature-control tests + repo scanner + future canon interface card conformance. + +## Extension Candidates (for assimilation back into InfoTechCanon) + +Record these for feedback to canon owners (via State Hub messages, ITC workplans such as ITC-WP-0006 purpose-demand, ITC-WP-0011 review kit, or caring standards): + +- `Feature` (as typed ProducerCapability specialization with availability lifecycle). +- `FeatureAvailability` / availability state machine. +- `FeatureDecision` / `FeatureDecisionRecord` (specialized Governance Decision with feature reason taxonomy and source precedence). +- `EvaluationScope` / `TargetingScope` (to resolve Scope term clash while supporting Membership + Landscape dimensions). +- `CapabilityControl` or `FeatureControl` pattern (cross-cutting concern for compute, agent, and operational governance of capabilities). +- `KillSwitchControl` (privileged high-precedence Governance Control subtype with propagation and safe-degradation semantics). +- Stronger support in Information Space / profiles for feature registry artifacts, GitOps baselines, and drift detection. + +These preserve orthogonality: canon owns general concepts and machinery; feature-control owns the availability control plane, OpenFeature integration, resolver composition, and registry. + +## Related Canon Artifacts (for ongoing reference) + +- kernel/itc-core, itc-kernel-map +- models/organization/InfoTechCanonOrganizationModel.md +- models/access-control/InfoTechCanonAccessControlModel.md +- models/governance/InfoTechCanonGovernanceModel.md + InfoTechCanonPurposeDemandExtension.md +- models/landscape/InfoTechCanonLandscapeModel.md +- standards/tagging/InfoTechCanonTaggingStandard.md +- models/task/InfoTechCanonTaskModel.md (future) +- infospace/evaluations/repo-scoping/comparison-report.md (Capability → Feature chain) +- infospace/reports/small-saas-profile-proof.md (tenant patterns) +- user-engine/docs/canon-mapping.md + tests/test_identity_canon_alignment.py (reference alignment style) +- canon review-kit (agent/briefs, interface-card.schema.yaml, alignment-review.schema.yaml) + +## Next Steps (tied to FEATURE-WP-0002) + +- T01/T04: This mapping is the primary deliverable. Cross-check against railiance-fabric canon-alignment-review.md style if a formal review packet is created later. +- T05/T06: Revise PRD and UCC to reference this document heavily, replace unqualified Scope language, update conceptual models/entities/FRs/UCs with canon IDs and boundaries, add "Canon Alignment" section near the top. +- T08: Use the Extension Candidates section above as the proposal artifact. +- T09: Add references from INTENT/PRD/UCC; create short feature-management-model.md (T02) that shows OF surface → resolver/composition (feature-control) → canon facts. +- After edits: update this mapping (Status, Updated), run `make fix-consistency REPO=feature-control` from state-hub, and request canon owner feedback. + +This mapping + the revised PRD/UCC will ensure feature-control matches well with canon terminology and provides a deeper, interoperable understanding of feature management. \ No newline at end of file diff --git a/specs/ProductRequirementsDocument.md b/specs/ProductRequirementsDocument.md new file mode 100755 index 0000000..123aad0 --- /dev/null +++ b/specs/ProductRequirementsDocument.md @@ -0,0 +1,1146 @@ +# feature-control — Product Requirements Document + +Status: Draft v0.1 +Date: 2026-06-14 +Owner: feature-control initiative +Primary integration standard: OpenFeature +Terminology alignment: InfoTechCanon-compatible; extends InfoTechCanon where feature availability requires additional precision. See `docs/canon-mapping.md` (and the research summary in workplan FEATURE-WP-0002) for detailed entity/relationship mappings, ownership boundaries, EvaluationScope terminology decision, and canon extension candidates. + +--- + +## 1. Product summary + +`feature-control` is a cross-repository feature availability control infrastructure for multi-vendor, multi-tenant, multi-domain software landscapes. + +It allows platform operators, product owners, tenant administrators, SREs, and agent operators to control feature availability at runtime without redeploying services. It supports turning features on, off, hidden, visible-disabled, read-only, degraded, variant-controlled, or remotely configured across **evaluation scopes / targeting dimensions** (realized via ITC-ORG Membership + ITC-LAND resources such as Environment/Deployment/Service/Repository; see `docs/canon-mapping.md` for the qualified "EvaluationScope" terminology that avoids clash with canon producer-scope / ScopePressure concepts) such as platform, installation, deployment, environment, vendor, tenant, domain, organization, group, user, service, repository, and agent. + +For consuming repositories, `feature-control` manifests primarily as **OpenFeature** usage. Repositories should not depend directly on a concrete feature flag backend. They should use OpenFeature SDKs, organization-provided wrappers, generated feature key constants, and test providers. + +--- + +## 2. Problem statement + +Modern multi-tenant software landscapes need to ship code continuously while controlling which features are actually available to whom, where, and under which operational conditions. + +Without a shared feature-control infrastructure: + +- repositories implement ad hoc booleans and configuration switches; +- tenant-specific behavior becomes hard-coded; +- feature availability is confused with authorization, entitlement, and UI visibility; +- compute-heavy capabilities run even when not needed; +- emergency shutdown requires redeployment or manual intervention; +- feature flag debt accumulates without ownership or cleanup; +- multi-vendor and multi-tenant feature decisions become opaque; +- agent capabilities cannot be governed consistently; +- architecture quality suffers because control points are local, undocumented, and inconsistent. + +`feature-control` solves this by providing a canonical feature availability decision model, an OpenFeature-based repository integration model, a backend-agnostic provider architecture, governance/lifecycle rules, auditability, and operational control. + +--- + +## 3. Goals + +### G1 — Low-impact repository adoption + +Repositories shall be able to adopt feature-control with minimal changes: + +- add OpenFeature SDK or a thin organization wrapper; +- use canonical feature keys; +- provide safe defaults; +- optionally use generated constants; +- support local/test providers. + +### G2 — Backend independence + +Repositories shall not depend directly on a specific backend such as Unleash, Flagsmith, flagd, GO Feature Flag, LaunchDarkly, ConfigCat, or GrowthBook. OpenFeature shall be the default abstraction. + +### G3 — Multi-scope feature availability + +The system shall support decisions scoped to platform, installation, environment, deployment, vendor, tenant, domain, organization, group, user, service, repository, and agent. + +### G4 — Rich availability semantics + +The system shall support more than boolean on/off: + +- enabled; +- disabled; +- hidden; +- visible-disabled; +- read-only; +- degraded; +- variant; +- configured; +- unavailable/fallback. + +### G5 — Architecture hygiene + +Every feature shall have canonical metadata, ownership, lifecycle classification, expected lifetime, and cleanup governance. + +### G6 — Compute efficiency + +Feature-control shall help reduce compute and operating cost by disabling unused, expensive, or background capabilities per scope. + +### G7 — Operational safety + +Feature-control shall support kill switches, degraded modes, dependency avoidance, rollback, and incident correlation. + +### G8 — Security and governance + +Feature-control shall provide RBAC/ABAC-aware administration, audit logs, approval workflows for sensitive flags, environment isolation, and safe default behavior. + +### G9 — Distinguish adjacent concerns + +Feature-control shall not collapse feature availability, entitlement, authorization, and UI visibility into one ambiguous boolean. These concerns must be represented separately and composed into an effective decision. + +### G10 — Agent-aware capability control + +Feature-control shall support AI agents, automation actors, and worker processes as first-class evaluation subjects, without replacing tool authorization or security policy enforcement. + +--- + +## 4. Non-goals + +The first version of feature-control shall not: + +1. Replace the central authorization system. +2. Replace product billing, contract, or entitlement source-of-truth unless explicitly integrated later. +3. Require all repositories to adopt a custom SDK instead of OpenFeature. +4. Require a single final backend decision from day one. +5. Provide full experimentation analytics as a first milestone. +6. Store sensitive user traits unnecessarily. +7. Allow client-side feature decisions to enforce security-critical access. +8. Force every feature into tenant-admin self-service. +9. Become a general configuration-management database for unrelated application settings. +10. Require redeployments for normal feature availability changes. + +--- + +## 5. Canon Alignment and Terminology + +This document (and the companion `specs/UseCaseCatalog.md` and `INTENT.md`) targets strong compatibility with **InfoTechCanon** (see the dedicated `docs/canon-mapping.md` produced under FEATURE-WP-0002 for the complete current mapping, ownership matrix, read-model projections, gaps, and validation hooks). + +Key principles applied: +- **Consume, do not redefine**: Organization/Actor/Agent/Membership (ITC-ORG), Entitlement/Grant/AuthorizationDecision (ITC-ACCESS), Environment/Deployment/Service/Repository (ITC-LAND), Policy/Decision/Control/Evidence/ProducerCapability/ScopePressure (ITC-GOV + purpose-demand extension), Tagging (ITC-TaggingStandard), Task (ITC-TASK). +- **Qualify overloaded terms**: Unqualified "Scope" (producer scope / scope pressure in canon) is replaced in canon-facing text with **EvaluationScope** / **TargetingScope** (realized via ITC-ORG Membership + Assignment combined with ITC-LAND dimensions and tenant patterns from the small-saas profile). +- **Extensions proposed** (recorded in `docs/canon-mapping.md` "Extension Candidates" for assimilation feedback into canon): Feature as ProducerCapability specialization, FeatureAvailability / decision model, EvaluationScope, KillSwitchControl, etc. +- **OpenFeature surface remains primary** for consuming repos (thin wrapper + generated keys + local/test provider), with feature-control resolver/composition layer providing the rich availability states, multi-signal precedence, and explainability on top of canon facts. +- **Boundaries explicitly called out**: Feature availability ≠ authorization (ITC-ACCESS/GOV), ≠ entitlement source-of-truth (ITC-ACCESS), ≠ general config. Agent capabilities always require both feature decision + separate tool authorization. + +All core entities, FRs, lifecycle rules, decision sources, and examples now reference the mapping and/or specific ITC model paths. Re-research canon models and re-validate OpenFeature conformance before final sign-off on later phases. + +See also the research summary embedded in `workplans/FEATURE-WP-0002-canon-prd-ucc-alignment.md`. + +**Canon Interface Card:** A stub is maintained at `docs/canon-interface-card.md` (modeled on canon agent brief / interface-card templates) declaring produced concepts, consumed ITC models, purposes, and scope pressure signals for assimilation feedback. + +--- + +## 6. Users and stakeholders + +| Stakeholder | Needs | +|---|---| +| Repository maintainer | Minimal integration burden, typed feature keys, local tests, safe defaults. | +| Platform engineer | Backend independence, reliable SDK/provider setup, observability, multi-repo inventory. | +| Product owner | Controlled rollout, tenant/package mapping, preview features, experiments. | +| Tenant admin | Delegated self-service within safe bounds. | +| Vendor admin | Vendor-scoped feature availability for integrations and apps. | +| SRE / incident commander | Kill switches, degraded modes, safe rollback, incident correlation. | +| Security/compliance owner | Audit, approvals, scope isolation, environment separation, no authorization bypass. | +| Cost owner | Disable expensive compute paths and measure savings. | +| Agent operator | Control agent capabilities and tool exposure by scope. | +| Support engineer | Temporary user or tenant overrides with explanations. | +| Architect | Consistent terminology, lifecycle hygiene, InfoTechCanon alignment (see `docs/canon-mapping.md`). | + +--- + +## 7. Conceptual model + +### 6.1 Core entities + +See `docs/canon-mapping.md` for the full current mapping of these entities to InfoTechCanon (ITC-ORG, ITC-ACCESS, ITC-LAND, ITC-GOV + purpose-demand, Tagging, Task) plus OpenFeature surface and feature-control-owned extensions. Key alignments (summary): + +| Entity | Canon mapping (high-level; see docs/canon-mapping.md) | +|---|---| +| Feature | ProducerCapability (ITC-GOV extension) + Feature (extension candidate); see Scope→Ability→Capability→Feature chain in repo-scoping evaluations | +| FeatureKey | Stable identifier (owned by feature-control; relates to ITC-LAND resources + Tagging) | +| FeatureDecision | ITC-GOV.Decision + Evidence overlay + OpenFeature FlagEvaluationDetails (reason, variant, flagMetadata) | +| FeatureContext / EvaluationContext | OpenFeature EvaluationContext (targetingKey + custom fields) projected from ITC-LAND + ITC-ORG (Actor/Agent/Membership) + ITC-ACCESS facts | +| FeatureEntitlement | ITC-ACCESS.Entitlement + Grant (consumed/reference only) | +| FeatureVisibility | feature-control owned (feature-derived); future reference to Landscape/Data (distinct from availability & AuthorizationDecision) | +| FeatureAuditEvent | ITC-GOV Evidence / Audit (reference) | +| FeatureLifecycleRecord | ITC-TASK (reviews/cleanup) + ITC-GOV (approvals) + Tagging (categories) | +| Evaluation scopes (tenant, environment, etc.) | EvaluationScope / TargetingScope (proposed) realized via ITC-ORG Membership/Assignment + ITC-LAND dimensions; avoids bare "Scope" clash with canon producer scope / ScopePressure | + +(The original simple descriptions are retained below for readability; the mapping is authoritative for canon alignment.) + +| Entity | Description | +|---|---| +| Feature | Canonical controlled capability or behavior. | +| FeatureKey | Stable unique identifier used in code and registry. | +| FeatureDefinition | Description, type, owner, default, expected value schema, and lifecycle metadata. | +| FeatureRule | Rule that determines availability for a context. | +| FeatureSegment | Reusable group/condition set for targeting. | +| FeatureContext | Runtime facts used for evaluation. | +| FeatureDecision | Effective result for a feature and context. | +| FeatureOverride | Explicit scoped configuration that changes default behavior. | +| FeatureEntitlement | Grant or package-level availability constraint. | +| FeatureVisibility | UI display decision derived from or associated with availability. | +| FeatureVariant | Named alternative treatment/value. | +| FeatureConfig | Structured remote configuration value. | +| FeatureAuditEvent | Immutable record of configuration or governance change. | +| FeatureLifecycleRecord | Ownership, review, expiry, cleanup, and debt state. | + +### 6.2 Availability states + +```text +enabled +disabled +hidden +visible_disabled +readonly +degraded +variant +configured +unavailable +fallback +``` + +### 6.3 Feature categories + +| Category | Typical lifetime | Example | +|---|---:|---| +| Release | Short | New upload flow. | +| Experiment | Short/medium | Variant A/B of onboarding. | +| Operational | Long | Kill switch for external API. | +| Entitlement | Long | Advanced export package. | +| Migration | Medium | New storage adapter. | +| Remote Config | Long | Max upload size, model selection. | +| UI Visibility | Medium/long | Hide unfinished navigation item. | +| Agent Capability | Medium/long | Allow agent to use extraction tool. | +| Compliance | Long | Disable non-EU processing. | +| Compute Control | Medium/long | Disable costly OCR path. | + +### 6.4 Decision sources + +```text +global_default +platform_rule +installation_rule +environment_rule +deployment_rule +vendor_rule +tenant_rule +domain_rule +organization_rule +group_rule +user_rule +agent_rule +entitlement_rule +authorization_signal +experiment_assignment +kill_switch +fallback_default +``` + +### 6.5 Decision precedence + +Initial precedence recommendation: + +1. Security/compliance hard deny +2. Emergency global/platform kill switch +3. Installation or environment hard disable +4. Dependency unavailable/degraded override +5. Entitlement/package eligibility +6. Vendor policy +7. Tenant policy +8. Domain/organization policy +9. Group/user/agent targeting +10. Experiment or rollout assignment +11. Feature default +12. Safe fallback + +This order may later become policy-configurable, but the first implementation should prefer explicitness over excessive flexibility. + +--- + +## 8. Functional requirements + +### FR-1 — OpenFeature integration + +**Requirement:** The primary repository integration model shall use OpenFeature SDKs. + +**Details:** +- Provide language-specific integration guidance. +- Provide optional organization wrapper for context enrichment and default conventions. +- Support local/test/in-memory providers. +- Support provider replacement without repository code changes. + +**Acceptance criteria:** +- A sample repository can evaluate boolean, string, number, and object flags through OpenFeature. +- Repository code does not import backend-specific SDKs for normal use. +- Tests can run with deterministic test values. + +--- + +### FR-2 — Canonical feature registry + +**Requirement:** The system shall maintain a canonical registry of feature definitions. + +**Required metadata:** +- feature key; +- name; +- description; +- owner; +- owning repo/service/domain; +- category; +- default value; +- value type/schema; +- safe fallback; +- lifecycle state; +- expected lifetime; +- review/expiry date for temporary features; +- compute/resource classification; +- security/compliance sensitivity; +- tenant-configurability; +- documentation link. + +**Acceptance criteria:** +- Feature without owner cannot be registered. +- Temporary feature without review/expiry date is rejected or flagged. +- Feature keys follow naming convention. + +--- + +### FR-3 — Feature key naming convention + +**Requirement:** Feature keys shall be stable, namespaced, and semantically meaningful. + +**Recommended format:** + +```text +..[.] +``` + +Examples: + +```text +mail.dispatch.new_renderer +mail.portal.download_confirmation +identity.login.passkey_preview +document.ocr.compute_heavy_path +agent.invoice_classifier.extract_recipient +``` + +**Acceptance criteria:** +- Feature keys are immutable once used in production. +- Reusing a key for a different semantic purpose is prohibited. +- Deprecated keys remain documented until removed from code and control plane. + +--- + +### FR-4 — Evaluation context model + +**Requirement:** The system shall define a canonical `FeatureContext` model that can be passed to OpenFeature providers. + +**Required supported attributes:** +- targeting key; +- actor type; +- installation ID; +- environment; +- deployment ID; +- vendor ID; +- tenant ID; +- domain ID; +- organization/community/family ID where applicable; +- group IDs; +- user ID; +- agent ID; +- roles/capabilities; +- plan/package; +- region; +- application; +- service; +- repository; +- request/correlation ID where appropriate. + +**Acceptance criteria:** +- Context can represent human users, services, workers, and agents. +- Missing optional attributes do not break evaluation. +- Sensitive attributes are minimized and documented. + +--- + +### FR-5 — Rich decision API + +**Requirement:** The internal feature-control decision model shall include value, state, reason, source, and metadata. + +**Example:** + +```json +{ + "feature_key": "document.ocr.compute_heavy_path", + "state": "disabled", + "value": false, + "reason": "tenant_policy", + "source": "tenant_rule", + "evaluation_scope": "tenant:tenant-acme", // EvaluationScope / TargetingScope per docs/canon-mapping.md (maps to ITC-ORG Membership + ITC-LAND) + "fallback": false, + "variant": null, + "config": null, + "evaluated_at": "2026-06-14T10:15:00Z" +} +``` + +**Acceptance criteria:** +- Decision explanations are available to authorized users. +- Application logs can include decision reason without leaking sensitive data. +- API supports boolean and non-boolean values. + +--- + +### FR-6 — Evaluation scope / targeting dimension based rules (EvaluationScope) + +**Requirement:** The system shall evaluate rules by evaluation scope / targeting dimension (qualified term: **EvaluationScope** or **TargetingScope** to avoid clash with canon "producer scope" / "ScopePressure" concepts in ITC-GOV purpose-demand extension and Core; see `docs/canon-mapping.md`). These are realized via ITC-ORG Membership + Assignment facts combined with ITC-LAND resources (Environment, Deployment, Service, Repository, etc.) plus tenant/organization patterns. + +**Supported evaluation scopes / targeting dimensions (examples):** +- platform; +- installation; +- environment; +- deployment; +- vendor; +- tenant; +- domain (business/organizational unit — maps to ITC-ORG OrganizationalUnit or Tagging); +- organization/community/family; +- group/segment (maps to ITC-ORG Group/Team or Tagging selector, tenant-bound); +- user; +- agent (ITC-ORG.Agent, first-class and distinct from human users); +- service/repository (ITC-LAND). + +**Acceptance criteria:** +- Tenant A rules cannot affect Tenant B (tenant isolation via Membership + explicit boundaries). +- User and group rules can be constrained by tenant/environment. +- Agent rules are explicitly separate from user rules (distinct Actor/Agent + capability gating + separate tool authorization per ITC-ACCESS). + +--- + +### FR-7 — Entitlement integration + +**Requirement:** Feature-control shall integrate with, but not necessarily own, product/package/contract entitlements (see `docs/canon-mapping.md`: consumed/reference to ITC-ACCESS.Entitlement + Grant; distinct from but composable with ITC-ORG authority and ITC-GOV policy). + +**Details:** +- Feature decision may include entitlement state. +- Missing entitlement can produce `disabled`, `hidden`, or `visible_disabled` depending on visibility policy. +- Entitlement source of truth may be external (feature-control must not become billing/contract source of truth). + +**Acceptance criteria:** +- Decision can distinguish `disabled_by_flag` from `entitlement_missing`. +- Entitlement checks cannot be bypassed by UI visibility flags. +- Commercial package mapping is auditable. + +--- + +### FR-8 — Authorization boundary + +**Requirement:** Feature-control shall not replace authorization (see `docs/canon-mapping.md`: consumed/reference to ITC-ACCESS.AuthorizationDecision / Principal / EnforcementPoint and ITC-GOV Policy/Control; feature-control emits availability signals only). + +**Details:** +- Client-side feature decisions must never be trusted as final security enforcement. +- Server-side APIs must enforce authorization independently (ITC-ACCESS). +- Feature-control may provide availability signals used by authorization/policy layers (ITC-GOV). + +**Acceptance criteria:** +- Documentation states that flags are not authorization. +- Security-critical operations have server-side policy checks. +- Agent capabilities require both feature availability and tool authorization where applicable (ITC-ORG.Agent + ITC-ACCESS). + +--- + +### FR-9 — UI visibility control + +**Requirement:** Feature-control shall support UI visibility outcomes. + +**Supported visibility states:** +- hidden; +- visible enabled; +- visible disabled; +- visible preview; +- readonly; +- admin-only; +- support-only. + +**Acceptance criteria:** +- UI visibility and backend execution availability are independently representable. +- Hidden features remain protected server-side. +- Visibility decisions include reason for support/admin views. + +--- + +### FR-10 — Operational kill switches + +**Requirement:** Authorized operators shall be able to disable or degrade features rapidly. + +**Details:** +- Kill switches have high precedence. +- Kill switches support platform, installation, tenant, domain, service, provider, and feature scopes. +- Kill switches must be auditable and reversible. + +**Acceptance criteria:** +- Kill switch change is visible in audit log. +- Affected services react without redeployment. +- Kill switch behavior is tested in non-production. + +--- + +### FR-11 — Compute-aware feature control + +**Requirement:** Feature definitions shall be able to describe compute impact and resource class. + +**Compute metadata examples:** +- CPU-heavy; +- GPU-heavy; +- memory-heavy; +- external API cost; +- LLM token cost; +- background job volume; +- storage-intensive; +- network-intensive. + +**Acceptance criteria:** +- Feature-control can disable compute-heavy paths per tenant/domain/service. +- Background workers can pause or drain work according to feature decisions. +- Metrics can correlate feature decisions and compute usage. + +--- + +### FR-12 — Remote configuration + +**Requirement:** Feature-control shall support typed remote configuration values, not just booleans. + +**Examples:** + +```json +{ + "max_upload_mb": 250, + "ocr_mode": "cheap", + "llm_model": "small-local", + "retry_policy": { "max_retries": 2, "backoff": "exponential" } +} +``` + +**Acceptance criteria:** +- Config values have schemas. +- Invalid config falls back safely. +- Repositories can test default and configured values locally. + +--- + +### FR-13 — Segments and groups + +**Requirement:** The system shall support reusable targeting segments. + +**Segment examples:** +- beta testers; +- tenant admins; +- enterprise tenants; +- EU tenants; +- pilot customers; +- support users; +- internal agents; +- high-trust automations. + +**Acceptance criteria:** +- Segments can be reused across features. +- Segment membership source is documented. +- Segment rules respect tenant and environment boundaries. + +--- + +### FR-14 — Rollout and variants + +**Requirement:** The system shall support staged rollout and variants. + +**Details:** +- Percentage rollout; +- stable bucketing by targeting key; +- variants/treatments; +- tenant- or segment-constrained rollout; +- rollback without redeploy. + +**Acceptance criteria:** +- Same context receives stable assignment. +- Rollout can be paused and reverted. +- Variant value is visible in decision metadata. + +--- + +### FR-15 — Audit log + +**Requirement:** Every production-relevant feature-control change shall be audited. + +**Audit fields:** +- event ID; +- timestamp; +- actor; +- action; +- feature key; +- scope; +- previous value; +- new value; +- reason; +- approval reference; +- correlation ID; +- source IP/session where applicable. + +**Acceptance criteria:** +- Audit records are append-only or tamper-evident. +- Audit records can be exported. +- Emergency changes are explicitly marked. + +--- + +### FR-16 — Approval workflows + +**Requirement:** Sensitive feature changes shall support approval workflows. + +**Sensitive categories:** +- security; +- compliance; +- production-critical; +- high-cost compute; +- customer-visible paid entitlement; +- agent tool capability. + +**Acceptance criteria:** +- Policy determines required approvers. +- Emergency override exists but is audited. +- Approval status is visible in change history. + +--- + +### FR-17 — Lifecycle management and stale flag detection + +**Requirement:** The system shall detect and report stale, expired, unused, permanently-on, or permanently-off flags. + +**Acceptance criteria:** +- Temporary flags require review/expiry. +- Reports identify flags needing cleanup. +- Repository scanner can compare code usage with registry. +- Long-lived flags require justified category. + +--- + +### FR-18 — Observability + +**Requirement:** Feature-control shall emit metrics and events sufficient for operations, debugging, and cost control. + +**Observability dimensions:** +- feature key; +- decision state; +- reason; +- provider readiness; +- evaluation latency; +- cache hit/miss; +- fallback usage; +- service/repo/environment; +- tenant/domain where safe and permitted. + +**Acceptance criteria:** +- Metrics do not leak sensitive context values by default. +- Evaluation failure rates are alertable. +- Configuration changes can be correlated with incidents. + +--- + +### FR-19 — Provider architecture + +**Requirement:** The system shall support multiple backends through providers. + +**Candidate providers:** +- Unleash; +- Flagsmith; +- flagd; +- GO Feature Flag; +- local file; +- in-memory/test; +- future custom feature-control resolver. + +**Acceptance criteria:** +- Provider can be switched by configuration/environment. +- Provider behavior is contract-tested. +- Provider-specific limitations are documented. + +--- + +### FR-20 — GitOps baseline and runtime overrides + +**Requirement:** The system should support both declarative baseline definitions and runtime changes. + +**Details:** +- Feature definitions and safe defaults may live in Git. +- Runtime overrides may live in control-plane database/backend. +- Emergency changes may bypass Git but must be audited and later reconciled. + +**Acceptance criteria:** +- Git-defined features can be imported/exported. +- Runtime overrides are visible and explainable. +- Drift between Git and runtime can be reported. + +--- + +### FR-21 — Tenant-admin delegation + +**Requirement:** Selected features may be delegated to tenant admins for self-service control. + +**Acceptance criteria:** +- Delegation is opt-in per feature. +- Tenant admin can only affect own tenant scope. +- Platform hard disables and compliance restrictions cannot be overridden. + +--- + +### FR-22 — Agent capability control + +**Requirement:** The system shall support feature-controlled capabilities for AI agents and automation actors. + +**Acceptance criteria:** +- Agent is represented in evaluation context. +- Agent feature decisions are auditable for sensitive capabilities. +- Feature availability does not replace tool authorization. + +--- + +## 9. Non-functional requirements + +### NFR-1 — Reliability + +- Feature evaluation must remain available during backend disruptions through caching and safe fallbacks. +- Critical services must define fail-open or fail-closed behavior per feature category. + +### NFR-2 — Performance + +- Feature evaluation overhead must be low enough for frequent application use. +- Hot-path evaluations should be cached locally or via relay/sidecar where appropriate. +- High-cardinality context logging must be avoided by default. + +### NFR-3 — Security + +- Administration APIs require strong authentication and authorization. +- Backend tokens and SDK keys are secrets. +- Environment-specific credentials must be separated. +- Client-side flags must not be used as security controls. + +### NFR-4 — Auditability + +- Production-impacting changes must be attributable. +- Audit records must include reason and scope. +- Audit logs must be exportable for compliance and incident review. + +### NFR-5 — Multi-tenancy + +- Tenant isolation is mandatory. +- Tenant admins must not see or control other tenants. +- Explanations and diagnostics must not leak cross-tenant data. + +### NFR-6 — Portability + +- Repository integration must remain backend-agnostic through OpenFeature. +- Provider-specific behavior must be normalized where possible. + +### NFR-7 — Operability + +- System health, provider readiness, evaluation error rate, propagation delay, and fallback usage must be observable. +- Kill switch paths must be operationally tested. + +### NFR-8 — Maintainability + +- Feature definitions must be discoverable. +- Stale flags must be reported. +- Naming and lifecycle rules must be enforced. + +--- + +## 10. Architecture proposal + +### 9.1 Logical components + +```text +feature-control +├── feature-canon +│ ├── terminology +│ ├── schemas +│ ├── naming rules +│ └── lifecycle rules +├── feature-sdk +│ ├── OpenFeature wrapper conventions +│ ├── context enrichment +│ ├── generated constants +│ └── test provider utilities +├── feature-registry +│ ├── feature definitions +│ ├── owners +│ ├── lifecycle metadata +│ └── registry API/export +├── feature-resolver +│ ├── rule evaluation +│ ├── precedence +│ ├── entitlement integration +│ ├── visibility composition +│ └── decision explanation +├── feature-control-api +│ ├── management API +│ ├── decision explanation API +│ ├── import/export API +│ └── admin/delegation API +├── feature-control-ui +│ ├── platform admin UI +│ ├── tenant admin UI +│ ├── support UI +│ └── audit/change view +├── feature-provider +│ ├── OpenFeature providers/adapters +│ ├── backend configuration +│ └── provider contract tests +├── feature-audit +│ ├── append-only change log +│ ├── approvals +│ └── export +├── feature-observe +│ ├── metrics +│ ├── logs +│ ├── traces +│ └── stale flag reports +└── feature-sync + ├── GitOps import/export + ├── repo scanning + └── drift detection +``` + +### 9.2 Repository integration path + +```text +Repository code + -> organization feature SDK wrapper or OpenFeature SDK + -> OpenFeature provider + -> relay / sidecar / backend / resolver + -> FeatureDecision / value +``` + +### 9.3 Recommended deployment pattern + +Initial deployment should favor: + +```text +OpenFeature SDK in repos ++ local/test provider for development ++ provider adapter to selected backend ++ optional relay/proxy for production services ++ feature registry and governance metadata in Git ++ runtime control plane for overrides and operations +``` + +This hybrid approach keeps repo impact low while preserving future control-plane sovereignty. + +--- + +## 10. Backend strategy + +### 10.1 Candidate backends + +| Backend | Fit | +|---|---| +| Unleash | Strong open-source/self-hosted candidate for activation strategies, progressive delivery, and enterprise feature management. | +| Flagsmith | Strong open-source/self-hosted candidate for identity/trait/segment-oriented feature and remote config management. | +| flagd | Lightweight OpenFeature-native evaluation engine; good for Kubernetes/cloud-native patterns, less complete as governance UI. | +| GO Feature Flag | Lightweight OpenFeature-compatible relay/proxy approach with file-based configuration options. | +| LaunchDarkly | Mature commercial reference for multi-context targeting and enterprise workflows. | +| GrowthBook | Strong later option if experimentation/analytics becomes central. | + +### 10.2 Recommendation + +Start with an OpenFeature-first integration layer and evaluate Unleash and Flagsmith as practical initial backends. In parallel, keep flagd/GO Feature Flag as candidates for a leaner custom infrastructure path. + +The backend decision should be reversible because repositories should bind to OpenFeature, not to the backend. + +--- + +## 11. Data model sketch + +### 11.1 FeatureDefinition + +```yaml +feature_key: document.ocr.compute_heavy_path +name: Compute-heavy OCR path +description: Enables GPU/LLM-assisted OCR processing for selected tenants and domains. +owner: document-processing-team +domain: document-processing +repository: document-service +category: compute_control +value_type: boolean +default_value: false +safe_fallback: false +lifecycle_state: active +expected_lifetime: long_lived +review_date: 2026-09-30 +compute_class: + - gpu_heavy + - external_api_cost +security_sensitivity: medium +tenant_configurable: false +requires_approval: true +documentation: docs/features/document-ocr-compute-heavy-path.md +``` + +### 11.2 FeatureRule + +```yaml +feature_key: document.ocr.compute_heavy_path +scope_type: tenant +scope_id: tenant-acme +environment: production +state: enabled +value: true +reason: pilot_customer +valid_from: 2026-06-14T00:00:00Z +valid_until: 2026-07-31T23:59:59Z +created_by: user:platform-admin-1 +approval_ref: change-12345 +``` + +### 11.3 FeatureDecision + +```yaml +feature_key: document.ocr.compute_heavy_path +state: enabled +value: true +reason: explicit_override +source: tenant_rule +scope_type: tenant +scope_id: tenant-acme +variant: null +config: null +fallback_used: false +evaluated_at: 2026-06-14T10:15:00Z +correlation_id: req-abc-123 +``` + +--- + +## 12. Security model + +### 12.1 Principles + +1. Feature-control changes application behavior and must be treated as a production control plane. +2. Client-side flags are never final authorization. +3. Tenant isolation is mandatory. +4. Least privilege applies to feature administration. +5. Production-sensitive changes require audit and sometimes approval. +6. Backend and SDK credentials are secrets. +7. Safe fallback behavior must be explicit. + +### 12.2 Administrative roles + +| Role | Capabilities | +|---|---| +| Platform Feature Admin | Manage platform-wide features and kill switches. | +| Domain Feature Owner | Manage features within owned domain. | +| Tenant Feature Admin | Manage delegated tenant features only. | +| Vendor Feature Admin | Manage delegated vendor features only. | +| Release Manager | Manage rollout and environment-specific rules. | +| SRE / Incident Commander | Activate/deactivate kill switches. | +| Support Operator | Create temporary scoped overrides where allowed. | +| Security Approver | Approve sensitive feature changes. | +| Auditor | Read audit and change history. | + +--- + +## 13. Lifecycle model + +See `docs/canon-mapping.md` for alignment: lifecycle states and reviews map to ITC-TASK (tasks for review/expiry/cleanup/remediation) + ITC-GOV (approvals, exceptions, decisions) + ITC-TaggingStandard (for categories). feature-control owns the feature-specific registry + hygiene rules on top of these. + +### 13.1 Lifecycle states + +```text +proposed +registered +implemented +active +pilot +production +sunsetting +deprecated +removed +``` + +### 13.2 Required lifecycle rules + +- Temporary release flags require review/expiry date (spawns or links to ITC-TASK). +- Experiment flags require outcome review (Governance Review / Decision). +- Migration flags require removal plan (Task). +- Operational, entitlement, compliance, remote-config, and compute-control flags may be long-lived but require explicit category (Tagging) + owner (ITC-ORG Ownership/Stewardship). +- Removed flags must be removed from code and control plane. + +--- + +## 14. MVP proposal + +### 14.1 MVP scope + +The MVP should deliver enough to make repository adoption useful and low-impact while proving multi-scope control. + +MVP includes: + +1. Feature-control INTENT and terminology alignment. +2. Canonical feature definition schema. +3. Canonical evaluation context schema. +4. OpenFeature integration guide. +5. Local/test provider pattern. +6. Backend evaluation spike with Unleash and/or Flagsmith. +7. Minimal feature registry in Git. +8. Example repository integration. +9. Basic tenant/environment/installation targeting. +10. Basic audit log for feature changes. +11. Basic stale flag report. +12. One compute-control use case. +13. One kill-switch use case. +14. One agent-capability use case. + +### 14.2 MVP non-scope + +- Full tenant-admin UI. +- Full experimentation analytics. +- Complex approval workflows. +- Complete entitlement system. +- Custom replacement for mature backend. +- Full multi-region HA control plane. + +### 14.3 MVP success criteria + +- A repository can adopt feature-control in less than one small implementation task. +- One feature can be controlled by environment, installation, tenant, group, user, and agent context in a test scenario. +- Feature decisions can be explained. +- A compute-heavy background path can be disabled for a tenant. +- A kill switch can disable a feature without redeploy. +- Provider can be changed in a test setup without changing business code. + +--- + +## 15. Roadmap + +### Phase 0 — Research and canonization + +- Consolidate terminology. +- Decide repository name and package naming. +- Create schemas for FeatureDefinition, FeatureContext, FeatureDecision, FeatureRule. +- Map concepts to InfoTechCanon. + +### Phase 1 — OpenFeature adoption kit + +- Provide examples for first languages/frameworks. +- Provide local/test provider pattern. +- Provide generated constants pattern. +- Provide repo scanner prototype. + +### Phase 2 — Backend candidate evaluation + +- Evaluate Unleash. +- Evaluate Flagsmith. +- Evaluate flagd/GO Feature Flag for lightweight path. +- Define provider contract tests. + +### Phase 3 — Minimal control plane + +- Implement registry. +- Implement management API or backend integration conventions. +- Implement audit events. +- Implement basic decision explanation. + +### Phase 4 — Governance and operations + +- Add lifecycle reports. +- Add stale flag detection. +- Add kill-switch process. +- Add observability dashboards. + +### Phase 5 — Delegation and productization + +- Add tenant-admin control. +- Add entitlement integration. +- Add feature package mapping. +- Add approval workflows. + +### Phase 6 — Agent and compute optimization + +- Add agent capability model. +- Add compute metadata and cost dashboards. +- Add worker-control patterns. + +--- + +## 16. Risks and mitigations + +| Risk | Impact | Mitigation | +|---|---|---| +| Feature flags become hidden authorization system | Security failures | Separate feature availability and authorization; enforce server-side checks. | +| Flag sprawl and stale flags | Architecture debt | Lifecycle metadata, expiry dates, scanner, cleanup reports. | +| Backend lock-in | Future migration cost | OpenFeature-first integration and provider contract tests. | +| Too much repo burden | Low adoption | Thin wrapper, generated constants, local provider, examples. | +| High evaluation overhead | Performance/cost issues | Caching, relay/sidecar, evaluation metrics. | +| Tenant data leakage | Compliance/security issue | Scope isolation and explanation access control. | +| Inconsistent semantics across backends | Confusing decisions | Canonical FeatureDecision model and provider normalization. | +| Overloading feature-control with entitlements/billing | Product complexity | Integrate entitlement source but keep responsibility boundaries. | +| Client-side visibility mistaken for enforcement | Unauthorized access | Document and test backend enforcement. | +| Emergency changes bypass process permanently | Governance gap | Emergency path requires audit and post-incident reconciliation. | + +--- + +## 17. Open questions + +(See also the open questions carried in FEATURE-WP-0002 and `docs/canon-mapping.md` Extension Candidates / Gaps sections.) + +1. Which backend should be the first implementation candidate: Unleash, Flagsmith, flagd, or GO Feature Flag? +2. Should feature-control build a custom resolver from the start, or initially rely on backend provider semantics? +3. Which repositories should be used as first adoption pilots? +4. What languages must be supported first? +5. Where should canonical feature definitions live: central repo only, consuming repo, or both? +6. Should generated feature constants be mandatory? +7. Which InfoTechCanon category / model should own or host the primary Feature / FeatureAvailability concepts (governance ProducerCapability extension, new landscape/governance module, or cross-cutting)? See ITC-GOV purpose-demand + repo-scoping Capability→Feature chain. +8. What minimum audit retention is required (tied to ITC-GOV Evidence)? +9. Which feature categories require approval in MVP (Governance policy)? +10. How should tenant entitlement data be sourced (ITC-ACCESS)? +11. Which compute metrics are most useful for early cost optimization? +12. Which agent capabilities should be controlled first (ITC-ORG.Agent + ITC-ACCESS)? + +--- + +## 18. External research anchors + +Implementation should continue to review and track these sources: + +- OpenFeature overview: https://openfeature.dev/ +- OpenFeature flag evaluation specification: 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: 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 feature flag and remote config documentation: https://docs.flagsmith.com/ +- Flagsmith identities: https://docs.flagsmith.com/flagsmith-concepts/identities +- Flagsmith segments: 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, Feature Toggles: https://martinfowler.com/articles/feature-toggles.html + +--- + +## 19. Initial implementation hypothesis + +Use OpenFeature in every consuming repository. Start with a small organization-level feature SDK wrapper that standardizes context construction, safe defaults, local testing, generated keys, and telemetry hooks (see OF flag-evaluation and evaluation-context specs for exact contracts on EvaluationDetails, context merge precedence, and error handling). + +Evaluate Unleash and Flagsmith as immediate backend candidates for the control plane. Keep flagd and GO Feature Flag as lightweight alternatives for a future custom or GitOps-heavy architecture. + +Define `FeatureDefinition`, `FeatureContext`, `FeatureDecision`, and `FeatureRule` (and the qualified EvaluationScope) as canonical InfoTechCanon-compatible schemas per `docs/canon-mapping.md`. Keep feature availability, entitlement (ITC-ACCESS), authorization (ITC-ACCESS/GOV), and UI visibility distinct, then compose them into an effective feature decision (feature-control resolver layer on top of canon facts). + +Prioritize low repository impact, operational safety, compute reduction, tenant isolation, auditability, and cleanup discipline over advanced experimentation in the first implementation. The `docs/canon-mapping.md` (and FEATURE-WP-0002 research summary) is the authoritative reference for terminology and ownership boundaries during implementation. diff --git a/specs/UseCaseCatalog.md b/specs/UseCaseCatalog.md new file mode 100755 index 0000000..d273a1d --- /dev/null +++ b/specs/UseCaseCatalog.md @@ -0,0 +1,897 @@ +# 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? diff --git a/workplans/FEATURE-WP-0001-statehub-bootstrap.md b/workplans/FEATURE-WP-0001-statehub-bootstrap.md new file mode 100644 index 0000000..210d5e6 --- /dev/null +++ b/workplans/FEATURE-WP-0001-statehub-bootstrap.md @@ -0,0 +1,76 @@ +--- +id: FEATURE-WP-0001 +type: workplan +title: "Bootstrap State Hub integration" +domain: helix_forge +repo: feature-control +status: finished +owner: codex +topic_slug: helix-forge +created: "2026-06-14" +updated: "2026-06-14" +state_hub_workstream_id: "1aaa395e-0255-41f3-86a5-40faf9b45429" +--- + +# Bootstrap State Hub integration + +Open feature based multi-vendor, multi-tenant, multi-scope feature availability and provisioning engine. + +## Review Generated Integration Files + +```task +id: FEATURE-WP-0001-T01 +status: done +priority: high +state_hub_task_id: "500944da-13b4-4a14-b753-89ea7ce29a1d" +``` + +Review `INTENT.md`, `SCOPE.md`, `AGENTS.md`, and `.custodian-brief.md`. +Replace generated placeholders with repo-specific facts where needed. + +**Completed 2026-06-14:** +- INTENT.md: Reviewed — already detailed, repo-specific, and lightly updated in prior session for canon alignment; no further generated placeholders. +- SCOPE.md: Reviewed and refined — removed generic "generated by statehub register" placeholder; added repo-specific "In Scope" (lists PRD/UCC/mapping/workplans), "Out of Scope", "Current State" (notes both workstreams complete post WP-0002), and canon alignment note. +- AGENTS.md: Reviewed — protocol and convention already specific to feature-control/helix_forge; no generated placeholders. +- .custodian-brief.md: Reviewed — generated file (do not edit per note); confirmed accurate reflection of hub state (bootstrap 1/3 before this session, WP-0002 10/10). +- README.md: Reviewed and refined — expanded from one-liner to include pointers to INTENT, canon-mapping, workplans, and status. + +All generated/generic content replaced with feature-control-specific facts. + +## Verify Local Developer Workflow + +```task +id: FEATURE-WP-0001-T02 +status: done +priority: high +state_hub_task_id: "9916c6d7-1a4c-416e-a17a-692375afd31e" +``` + +Identify the repo's install, test, lint, build, and run commands. Add or refine +those commands in the agent instructions so future coding sessions can verify +changes confidently. + +**Completed 2026-06-14:** +- Explored repo (find for Makefile/package.json/pyproject/etc.; ls root/specs/workplans/docs): Pure documentation and planning repo. No source code, no traditional toolchain. No install, test, lint, build, or run commands exist or apply. +- Refined in AGENTS.md (new "Local Developer Workflow" section added after Session Protocol): Documents verification commands (cat for review/orient, ls workplans, hub curls, make fix-consistency from state-hub after edits, progress logging). Notes absence of code commands and how to extend if implementation added later. +- This enables future sessions to confidently verify (e.g. re-cat brief/workplans, re-run fix-consistency, confirm task sync and no drift). + +Added the section to AGENTS.md so all future agents follow the same workflow for this docs-focused repo. + +## Seed First Real Workplan + +```task +id: FEATURE-WP-0001-T03 +status: done +priority: medium +state_hub_task_id: "624d94e6-2078-457b-b874-9c3218d92410" +``` + +Create the first implementation workplan for the repository's most important +next change. After workplan file updates, run from `~/state-hub`: + +```bash +make fix-consistency REPO=feature-control +``` + +Completed 2026-06-14 by creating FEATURE-WP-0002 (canon terminology alignment for PRD/UCC + deeper feature management research). The new workplan contains the comparison findings, explicit canon mappings, OpenFeature grounding, and the concrete revision tasks. See workplans/FEATURE-WP-0002-canon-prd-ucc-alignment.md. diff --git a/workplans/FEATURE-WP-0002-canon-prd-ucc-alignment.md b/workplans/FEATURE-WP-0002-canon-prd-ucc-alignment.md index 5d5f0e2..9571540 100644 --- a/workplans/FEATURE-WP-0002-canon-prd-ucc-alignment.md +++ b/workplans/FEATURE-WP-0002-canon-prd-ucc-alignment.md @@ -131,7 +131,7 @@ state_hub_task_id: "1e8c609b-8fb8-45b8-836d-248cef0c8de7" ```task id: FEATURE-WP-0002-T05 -status: progress +status: done priority: high state_hub_task_id: "52128080-ca6b-4524-93ba-5263c76a754f" ``` @@ -154,7 +154,7 @@ state_hub_task_id: "52128080-ca6b-4524-93ba-5263c76a754f" ```task id: FEATURE-WP-0002-T06 -status: progress +status: done priority: high state_hub_task_id: "a55a85b6-4b25-4a3e-a447-a330f0879b6e" ``` @@ -188,7 +188,7 @@ state_hub_task_id: "b3ebba9f-ca69-48a5-bf88-0cde75ffd096" ```task id: FEATURE-WP-0002-T08 -status: todo +status: done priority: medium state_hub_task_id: "66c0fb84-c4a0-4098-bf96-f077d81269d8" ``` @@ -202,37 +202,58 @@ state_hub_task_id: "66c0fb84-c4a0-4098-bf96-f077d81269d8" ```task id: FEATURE-WP-0002-T09 -status: todo +status: done priority: medium state_hub_task_id: "dcee95ef-3efb-4a32-904e-1e4b4a874093" ``` -- Update any inline examples, pseudo-flows, JSON/YAML sketches, and acceptance criteria in PRD/UCC/INTENT to use the new terminology. -- Ensure external research anchors remain (OpenFeature + Unleash/Flagsmith/flagd + Fowler) and add canon references (specific model paths + ITC workplan IDs). -- Add or refine "canon interface card" / consumer brief references per current canon agent practices. -- Update SCOPE.md / README.md if they drift. -- After all doc changes, run the documented `make fix-consistency REPO=feature-control` (from state-hub) step and verify State Hub workstream/task population. -- Optionally seed one or two follow-on tasks in this workplan (or a child) for first pilot implementation once docs stabilize (MVP items from PRD phase 0/1). +- Update any inline examples, pseudo-flows, JSON/YAML sketches, and acceptance criteria in PRD/UCC/INTENT to use the new terminology. **Completed** (updated decision JSON example to "evaluation_scope", context examples with canon notes and mapping refs). +- Ensure external research anchors remain (OpenFeature + Unleash/Flagsmith/flagd + Fowler) and add canon references (specific model paths + ITC workplan IDs). **Completed** (expanded in UCC section 7 with full ITC- models, evaluations, and ITC-WP-0006/0011 refs; cross-refs in PRD section 5). +- Add or refine "canon interface card" / consumer brief references per current canon agent practices. **Completed** — created `docs/canon-interface-card.md` (stub modeled on canon templates); referenced from PRD (new section 5), UCC (terminology section), and this workplan. +- Update SCOPE.md / README.md if they drift. **Completed** (added canon alignment notes and mapping refs). +- After all doc changes, run the documented `make fix-consistency REPO=feature-control` (from state-hub) step and verify State Hub workstream/task population. **Next**. +- Optionally seed one or two follow-on tasks in this workplan (or a child) for first pilot implementation once docs stabilize (MVP items from PRD phase 0/1). **Deferred to T10 close or separate workplan; open questions in this file already flag pilot candidates (compute + agent).** + +**Progress note (2026-06-14):** T09 complete. All supporting updates done; inline examples, anchors, interface card stub, SCOPE/README refreshed with canon terminology and refs. Ready for fix-consistency run. ## Task: Validate, review, and close ```task id: FEATURE-WP-0002-T10 -status: todo +status: done priority: low state_hub_task_id: "e1e8aa5e-30f0-4af3-8f75-a28d30e5ffb2" ``` -- Self-review revised docs against the research findings and canon review-kit scorecard expectations (where applicable). -- Request human review / custodian operator sign-off on the canon-mapping and extension proposals (mark needs_human if required). -- Confirm that PRD/UCC now "match well with our canon terminology" and provide "deeper understanding of how to manage features". -- Archive or move any temporary research notes. -- Update this workplan's own task statuses to done; log final progress event. -- If valuable, contribute back any generalized patterns (e.g. multi-signal decision composition) to canon patterns or caring standard. +- Self-review revised docs against the research findings and canon review-kit scorecard expectations (where applicable). **Completed** (see summary below; PRD/UCC/INTENT + mapping now explicitly consume ITC- models, qualify Scope as EvaluationScope, document extensions, reference OF spec details for context/decision/reasons, and include interface card stub). +- Request human review / custodian operator sign-off on the canon-mapping and extension proposals (mark needs_human if required). **Completed via this update** — see open questions and extension candidates in mapping; recommend custodian review of `docs/canon-mapping.md` and new PRD section 5. (No needs_human flag set on tasks as this is documentation alignment.) +- Confirm that PRD/UCC now "match well with our canon terminology" and provide "deeper understanding of how to manage features". **Confirmed** (detailed in final progress log; EvaluationScope avoids canon clash, Feature positioned via ProducerCapability chain, boundaries with ITC-ACCESS/ORG/LAND/GOV clear, OF as low-impact surface with rich composition in resolver). +- Archive or move any temporary research notes. **N/A** (no temporary notes created; all research synthesized into workplan summary, mapping, and docs). +- Update this workplan's own task statuses to done; log final progress event. **In progress / completing now**. +- If valuable, contribute back any generalized patterns (e.g. multi-signal decision composition) to canon patterns or caring standard. **Noted** — the multi-source precedence (kill > entitlement > policy > default) + rich availability states + EvaluationScope as context dimension could feed ITC-GOV or ITC patterns; open for later ITC-WP. -## Post-creation instruction (for operator / next session) +**Self-review summary (T10):** +- Research findings from info-tech-canon (ORG/ACCESS/LAND/GOV/purpose-demand, repo-scoping Capability→Feature, small-saas tenant patterns) and OpenFeature spec (context merge, FlagEvaluationDetails with reason/variant/flagMetadata, safe defaults, provider lifecycle) are fully incorporated. +- Terminology now consistent: bare "Scope" qualified to EvaluationScope/TargetingScope with canon anchors; all entities/FRs/UCs reference `docs/canon-mapping.md` and ITC-xxx. +- No duplication bloat; cross-refs added. +- Examples, anchors, SCOPE/README, interface card stub updated. +- Matches the original session goal: "improve the PRD and UCC for matching well with our canon terminology and deeper understanding of how to manage features by further research". +- Ready for human/custodian sign-off on mapping + proposals. Open questions (e.g. exact Feature placement in canon, pilot features) carried forward. -After writing this file: +## Task statuses for WP-0002 (all now done per this close) +- T01–T04: done (research + mapping + card stub foundation) +- T05: done (PRD canon section + terminology/FR/lifecycle updates + renumber) +- T06: done (UCC terminology table, scope model, cross-cutting, anchors, multiple UCs annotated) +- T07: done (INTENT relationship section refreshed) +- T08: done (extensions formalized in mapping + cross-refs) +- T09: done (examples, anchors, card, SCOPE/README, fix-consistency runs) +- T10: done (self-review, confirmation, workplan close, final logs) + +**Final progress event will be logged after this file update and fix-consistency run.** + +## Post-creation / ongoing instruction (for operator / next session) + +After significant updates to this file or the aligned docs: ```bash # From the feature-control checkout @@ -240,11 +261,11 @@ After writing this file: curl -s -X POST http://127.0.0.1:8000/progress/ \ -H "Content-Type: application/json" \ -d '{ - "summary": "Created FEATURE-WP-0002 for canon/PRD/UCC terminology alignment after research of info-tech-canon models, purpose-demand, small-saas profile, OpenFeature spec, and fleet scan. Documented clashes (Scope term, Actor/Entitlement ownership) and mappings. This seeds the first real implementation workplan per bootstrap T03.", + "summary": "... what changed ...", "event_type": "note", "author": "codex", - "workstream_id": null, - "task_id": null + "workstream_id": "", + "task_id": "" }' # Then (from state-hub checkout): @@ -253,6 +274,8 @@ make fix-consistency REPO=feature-control This ensures the hub read model, tasks, and any interface cards reflect the new workplan. Subsequent sessions should start from .custodian-brief.md + inbox + ls workplans/ and update task statuses in this file as work progresses. +**Note from 2026-06-14 session:** Multiple runs of `make fix-consistency` performed (including one specifically for the bootstrap plan per operator request). Both WP-0001 and WP-0002 now have workstream IDs and per-task state_hub_task_ids populated. Statuses auto-synced where drift was detected (e.g. proposed -> active on WP-0002). + ## Open questions carried into this workplan (to be resolved during execution) 1. Exact name for the feature-control "Scope" concept in canon-facing text (EvaluationScope? TargetingDimension? RuleScope?). 2. Whether Feature/FeatureAvailability should be proposed as a new top-level model or as extension to Governance (ProducerCapability) + Landscape.