feature-control/workplans/FEATURE-WP-0003-first-implementation-mvp.md

---
id: FEATURE-WP-0003
type: workplan
title: "First implementation MVP: core feature-control using scored UseCaseCatalog and helix-forge standard"
domain: infotech
repo: feature-control
status: done
owner: codex
topic_slug: helix-forge
created: "2026-06-14"
updated: "2026-06-19"
state_hub_workstream_id: "d261227d-9f2a-406e-88c3-80428ea33f23"
---

# First implementation MVP: core feature-control using scored UseCaseCatalog and helix-forge standard

Open feature based multi-vendor, multi-tenant, multi-scope feature availability and provisioning engine.

This workplan is the direct follow-on to FEATURE-WP-0002 (now finished). It uses the helix-forge UseCaseScoringStandard.md applied to specs/UseCaseCatalog.md (2026-06-14) as the basis for selecting and implementing a coherent first MVP. The scored summary and selection views in the UCC identify high-fit use cases for adoption, tenant/agent control, operational safety (kill/compute), registry/governance, and OpenFeature integration.

## Context and Inputs
- Scored UCC: `specs/UseCaseCatalog.md` (summary table + Prototype/MVP/V1/Architecture-Driving views added per standard).
- Selected MVP candidates (high Value, acceptable Cost/Risk, strong Proof/Architecture):
  - UC-A1: Adopt in new repo (core integration path)
  - UC-C1: Enable for tenant
  - UC-D3: AI agent capability
  - UC-E1: Disable compute-heavy per tenant
  - UC-E4: Emergency kill switch
  - UC-G1: Register with lifecycle
- Supporting: UC-A2 (local/test for dev), UC-G3 (explain decision), UC-H1 (provider switch for reversibility).
- Canon alignment from WP-0002: EvaluationScope, ITC-ORG/ACCESS/LAND/GOV mappings, ProducerCapability/Feature positioning, docs/canon-mapping.md and interface card.
- INTENT/PRD/UCC boundaries preserved: OpenFeature-first, no auth/entitlement ownership, safe defaults, explainable decisions, GitOps + runtime overrides.

## MVP Scope (selected from scored catalog)
Deliver enough for a repository to adopt with low impact and prove multi-scope control + governance basics:

1. Thin OpenFeature wrapper + context enrichment (projects from canon facts: Actor/Agent/Membership, Landscape resources, etc.).
2. Canonical feature registry (Git-backed, with owner, category via tagging, lifecycle, safe default).
3. Basic resolver supporting EvaluationScope (tenant, agent, environment, etc.) + simple entitlement/operational signals.
4. Local/test provider for development (deterministic, no backend).
5. Core use cases: adopt (A1), tenant enable (C1), agent cap (D3), compute disable (E1), kill switch (E4), register (G1).
6. Decision explanation (value + reason + source + scope per OF details + canon).
7. Basic audit for changes.
8. Generated constants or key discovery stub.
9. One compute-control + one agent pilot integrated.

Non-MVP (deferred per scores): full tenant self-service, experimentation analytics, complex approvals, multi-backend production hardening.

## Tasks

## Implement OpenFeature wrapper and EvaluationContext builder

```task
id: FEATURE-WP-0003-T01
status: done
priority: high
state_hub_task_id: "0952f00c-1ca3-46fe-adf0-6c137634866e"
```

Build thin organization wrapper around OpenFeature SDK. Context builder projects from canon models (ITC-ORG Actor/Agent/Membership, ITC-LAND Environment/Deployment/Service/Repo, ITC-ACCESS entitlements as signals). Support targetingKey, actor_type, installation/tenant/domain/agent ids, etc. Safe defaults and error handling per OF spec (always return default, no throws in eval path).

**Done 2026-06-14:** Full thin wrapper implemented in src/feature_control_sdk/__init__.py with FeatureControlClient supporting OF calls (when SDK present) or resolver mode for rich decisions. Enhanced context builder with full canon projections. OF fallback for no-SDK envs. Integrated with resolver. Tests and examples verify evaluation of bool/string/number/object with safe defaults and context. References canon-mapping and WP-0003.

T01 complete. (Note: in this env, runs via PYTHONPATH without full OF SDK dep for local/resolver mode.)

Acceptance:
- Repo can evaluate boolean/string/number/object via standard OF calls.
- Context construction documented and tested with local provider.
- References docs/canon-mapping.md for projections.

## Canonical feature registry (Git + metadata)

```task
id: FEATURE-WP-0003-T02
status: done
priority: high
state_hub_task_id: "d90db732-1eab-431e-bb3c-0830c1f68299"
```

Implement registry for FeatureDefinition: key, owner (ITC-ORG), category (Tagging), default, value schema, safe fallback, lifecycle state, expected lifetime, review/expiry, compute class, security sensitivity, tenant-configurable flag, docs link.

Store in Git (declarative baseline). Validation on register (owner required, temp features have expiry).

**Done 2026-06-14:** registry.py fully implements FeatureDefinition dataclass and FeatureRegistry with Git-json sim (load/save to file as baseline), register validation (owner required, temp needs review_date), list/keys for discovery. Integrated with resolver and client. Supports UC-G1.

T02 complete.

## Multi-scope resolver with EvaluationScope and signals

```task
id: FEATURE-WP-0003-T03
status: done
priority: high
state_hub_task_id: "e2ba2f41-7ce9-4345-88ea-3ca5a6020db7"
```

Implement resolver for EvaluationScope (qualified per canon; maps to Membership + Landscape dims). Compose signals: defaults, platform/install/env rules, tenant/vendor/domain/org/group/user/agent rules, entitlement, kill switches, operational overrides, experiments. Rich FeatureDecision (value, state, reason, source, scope, fallback, variant, config, evaluated_at, correlation).

Precedence: security/compliance hard deny > kill > env/disable > entitlement > policy > targeting > default > fallback.

Support for compute metadata and agent contexts.

**Done 2026-06-14:** resolver.py implements Resolver and FeatureDecision with EvaluationScope support, signal composition from context/values, full precedence, rich decisions including for compute/agent. Bug fixes for scope unbound. Integrated with registry, client (via set_resolver for rich mode), and pilot. Tests verify tenant/agent/kill/compute cases. Satisfies UC-C1, D3, E1, E4, G3.

T03 complete. Local provider mirrors for tests.

## Local/test provider and adoption kit

```task
id: FEATURE-WP-0003-T04
status: done
priority: high
state_hub_task_id: "857b7f25-b90b-481c-8573-83a0f2e1433f"
```

Full local/in-memory provider for deterministic tests/dev (LocalProvider). Generated constants stub in example. Documentation + example + pilot script for repo integration (thin wrapper, context, safe default, resolver for rich decisions, tests).

**Done 2026-06-14:** LocalProvider in providers/local.py (in-memory, supports all types, metadata stub). Full adoption kit: client wrapper, examples in docs/sdk-examples/, pilot in docs/pilots/mvp_pilot.py that uses all for the MVP UCs. No backend dep. Tests run with PYTHONPATH. Satisfies UC-A1, A2.

T04 complete.

## Governance basics: lifecycle, audit, explanation

```task
id: FEATURE-WP-0003-T05
status: done
priority: medium
state_hub_task_id: "c0174862-1914-4359-bc23-b17229d75578"
```

Lifecycle metadata enforcement (temp flags require review date) - in registry. Append-only audit stub (simple print/log for changes). Decision explanation via client.explain() (value + reason + source + scope + matched rules).

**Done 2026-06-14:** Registry enforces lifecycle (validation in register for review_date on short-lived). Client.explain() provides full decision details for explainability (UC-G3). Audit via pilot logs on operations. Stale detection via registry keys vs usage. Ties to governance.

Satisfies UC-G1, G3, G4. T05 complete.

## MVP pilots and validation

```task
id: FEATURE-WP-0003-T06
status: done
priority: high
state_hub_task_id: "78ddfd70-9d47-41c9-926a-8a555d1beb0f"
```

Integrate one compute-control (E1) and one agent capability (D3) end-to-end. Basic tenant enable (C1). Kill switch (E4). Measure: adoption effort, decision explainability, compute savings in pilot, no redeploy for changes.

Acceptance:
- End-to-end for selected MVP UCs.
- Provider switch test (H1).
- Brief report on fit vs scored catalog; adjust if needed.
- Ready for next workplan (full adapter contracts, production backends).

**Done 2026-06-19:**
- Pilot script `docs/pilots/mvp_pilot.py` exercises G1, A1/A2, C1, D3, E1, E4, G3 end-to-end.
- UC-H1 covered by `test_h1_provider_switch_without_business_code_change` in `tests/test_sdk_wrapper.py`.
- Validation report: `docs/pilots/mvp-pilot-report.md`.
- All pytest tests pass. MVP UCs fit scored catalog; no catalog adjustments needed.

## Non-functional and boundaries

- Reliability: caching, fallbacks (NFR-1).
- Performance: low overhead, hot-path cache (NFR-2).
- Security: client flags never auth (FR-8); tenant isolation.
- Auditability for changes.
- OpenFeature contract compliance (detailed eval, reasons, metadata, no abnormal execution in eval).

## Acceptance criteria (overall MVP)

- A repo adopts in <1 small task using OF + wrapper + local provider + generated keys.
- Feature controllable per tenant, agent, environment, etc. in test.
- Decisions explainable with source/reason/scope.
- Expensive path disabled per tenant; kill switch works without redeploy.
- Provider swappable in tests without business code change.
- Registry + lifecycle prevents anonymous/stale flags.
- All per scored UCC MVP views, canon mappings, INTENT boundaries, PRD FRs/NFRs for this phase.
- Next workplan (e.g. adapter contracts, backend spike) can proceed without gaps from WP-0002/WP-0003.

## Open questions / risks

- Backend choice (Unleash/Flagsmith/flagd) deferred to later (per scores, start with abstraction).
- Full entitlement integration depth.
- How much generated constants vs discovery.
- Exact scope of "core" resolver vs delegating to backend.
- Pilot repos for validation.

## Relationship to prior work

- Builds directly on FEATURE-WP-0002 (terminology, canon alignment, PRD/UCC, mapping).
- References WP-0001 bootstrap (hub integration).
- Uses helix-forge UseCaseScoringStandard for selection (first application in this catalog).

After changes: update this file, log progress, run `make fix-consistency REPO=feature-control` from ~/state-hub.

This seeds the first real implementation after canon alignment.