diff --git a/workplans/FEATURE-WP-0003-first-implementation-mvp.md b/workplans/FEATURE-WP-0003-first-implementation-mvp.md new file mode 100644 index 0000000..96bb3ea --- /dev/null +++ b/workplans/FEATURE-WP-0003-first-implementation-mvp.md @@ -0,0 +1,196 @@ +--- +id: FEATURE-WP-0003 +type: workplan +title: "First implementation MVP: core feature-control using scored UseCaseCatalog and helix-forge standard" +domain: helix_forge +repo: feature-control +status: active +owner: codex +topic_slug: helix-forge +created: "2026-06-14" +updated: "2026-06-14" +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: progress +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). + +**Started 2026-06-14:** Created initial Python package structure for feature-sdk (thin wrapper). See new src/, pyproject.toml, tests/, and docs/sdk-examples/. LocalProvider implemented. Wrapper with context builder (projecting canon facts). Basic usage example. Tests pass for all value types + safe defaults. Context projection skeleton references docs/canon-mapping.md. Full OF SDK integration documented (optional dep). + +Verified with: pip install -e ".[dev]" ; pytest tests/test_sdk_wrapper.py ; python docs/sdk-examples/basic_usage.py + +T01 skeleton complete for MVP. Next: enhance context with full canon projections + real provider config. + +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: todo +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). + +Acceptance: +- UC-G1 (register) satisfied. +- Keys discoverable (scanner stub or export). +- Integrates with T03 resolver. + +## Multi-scope resolver with EvaluationScope and signals + +```task +id: FEATURE-WP-0003-T03 +status: todo +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. + +Acceptance: +- UC-C1, D3, E1, E4 satisfied in test scenarios. +- Decisions explainable (UC-G3). +- Tenant isolation enforced; agent vs human distinct. +- Local provider mirrors for tests. + +## Local/test provider and adoption kit + +```task +id: FEATURE-WP-0003-T04 +status: todo +priority: high +state_hub_task_id: "857b7f25-b90b-481c-8573-83a0f2e1433f" +``` + +Full local/in-memory provider for deterministic tests/dev. Generated constants or key registry export stub. Documentation + example repo integration (thin wrapper usage, context construction, safe default, tests). + +Acceptance: +- UC-A1 and UC-A2 fully satisfied. +- No direct backend dep in consuming code. +- Tests run without network. + +## Governance basics: lifecycle, audit, explanation + +```task +id: FEATURE-WP-0003-T05 +status: todo +priority: medium +state_hub_task_id: "c0174862-1914-4359-bc23-b17229d75578" +``` + +Lifecycle metadata enforcement (temp flags require review date). Append-only audit for config changes. Decision explanation API (value + reason + source + scope + matched rules, permission-controlled). + +Acceptance: +- UC-G1, G3, G4 satisfied. +- Stale flag detection stub (compare registry vs code usage). +- Ties to ITC-TASK for remediation. + +## MVP pilots and validation + +```task +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. \ No newline at end of file