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

id, type, title, domain, repo, status, owner, topic_slug, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
FEATURE-WP-0003	workplan	First implementation MVP: core feature-control using scored UseCaseCatalog and helix-forge standard	helix_forge	feature-control	done	codex	helix-forge	2026-06-14	2026-06-14	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

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)

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

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

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

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

id: FEATURE-WP-0003-T06
status: todo
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).

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.