generated from coulomb/repo-seed
chore(consistency): renormalize lifecycle state [auto]
Updated by fix-consistency on 2026-06-14: - workplan status: proposed → active
This commit is contained in:
196
workplans/FEATURE-WP-0003-first-implementation-mvp.md
Normal file
196
workplans/FEATURE-WP-0003-first-implementation-mvp.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user