generated from coulomb/repo-seed
feat(bootstrap): finish FEATURE-WP-0001 State Hub integration workstream
- T01 (Review Generated Integration Files): Reviewed INTENT.md, SCOPE.md, AGENTS.md, .custodian-brief.md. Refined SCOPE.md (removed generic generated placeholder, added repo-specific In/Out Scope, Current State noting completion of WP-0001 and WP-0002, canon alignment). Refined README.md with links to canon-mapping and workplans. Confirmed INTENT and AGENTS already specific. - T02 (Verify Local Developer Workflow): Confirmed pure-docs repo (no build/test files). Added 'Local Developer Workflow' section to AGENTS.md documenting verification commands (cat/ls for review, hub curls, make fix-consistency from state-hub, progress POSTs) and extension guidance. - Updated FEATURE-WP-0001 workplan: T01/T02 marked done with detailed notes; frontmatter status set to finished. - Includes completion of FEATURE-WP-0002 (canon alignment for PRD/UCC, docs/canon-mapping.md + interface card stub, terminology updates with EvaluationScope and ITC mappings). - Ran make fix-consistency REPO=feature-control after changes (synced hub, set workstreams to finished). All per AGENTS.md session protocol, workplan instructions, and custodian brief. Bootstrap workstream now 3/3 complete; no active workstreams remaining.
This commit is contained in:
176
AGENTS.md
Normal file
176
AGENTS.md
Normal file
@@ -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/<id>/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": "<uuid>",
|
||||
"task_id": "<uuid>"
|
||||
}'
|
||||
```
|
||||
|
||||
Omit `workstream_id` / `task_id` when not applicable.
|
||||
|
||||
### Update task status
|
||||
|
||||
```bash
|
||||
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
|
||||
-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/<task_id>" \
|
||||
-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-<slug>.md`
|
||||
|
||||
**Archived location:** finished workplans may move to
|
||||
`workplans/archived/YYMMDD-FEATURE-WP-NNNN-<slug>.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: "<uuid>" # 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: "<uuid>" # 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/`)
|
||||
359
INTENT.md
Executable file
359
INTENT.md
Executable file
@@ -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.
|
||||
12
README.md
12
README.md
@@ -1 +1,11 @@
|
||||
Open feature based multi-vendor, multi-tenant, multi-scope feature availability and provisioning engine.
|
||||
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.
|
||||
36
SCOPE.md
Normal file
36
SCOPE.md
Normal file
@@ -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
|
||||
44
docs/canon-interface-card.md
Normal file
44
docs/canon-interface-card.md
Normal file
@@ -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.
|
||||
139
docs/canon-mapping.md
Normal file
139
docs/canon-mapping.md
Normal file
@@ -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 `<domain>.<capability>.<feature>[.<mode>]`. |
|
||||
| `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.
|
||||
1146
specs/ProductRequirementsDocument.md
Executable file
1146
specs/ProductRequirementsDocument.md
Executable file
File diff suppressed because it is too large
Load Diff
897
specs/UseCaseCatalog.md
Executable file
897
specs/UseCaseCatalog.md
Executable file
@@ -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?
|
||||
76
workplans/FEATURE-WP-0001-statehub-bootstrap.md
Normal file
76
workplans/FEATURE-WP-0001-statehub-bootstrap.md
Normal file
@@ -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.
|
||||
@@ -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": "<appropriate>",
|
||||
"task_id": "<appropriate>"
|
||||
}'
|
||||
|
||||
# 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.
|
||||
|
||||
Reference in New Issue
Block a user