suaveplan/openspec/archive/2026-04-19-enterprise-feature-flags/tasks.md

Tasks: enterprise-feature-flags

1. Scaffold

• 1.1 Create universal/config/feature-flags/ skeleton; 100/100/100/100 coverage; istanbul.
• 1.2 Cross-cutting guard tests; add to CLAUDE.md/README/FOLDERS.yml.

2. Errors + schemas

• 2.1 src/errors/feature-flags-error.ts — FeatureFlagsError extends SuaveplanError; codes FEATURE_FLAGS.*.
• 2.2 Auto-register codes via side-effect import.
• 2.3 Zod schemas for FlagDefinition, EvaluationContext, JsonFlagConfig, FlagEvaluationResult.

3. Core types + utilities

• 3.1 src/types/common.ts — all preserved type exports.
• 3.2 src/utils/hash.ts — hashToPercentage, combineKeys (FNV-1a or xxhash32 over combineKeys(flagKey, userKey)).
• 3.3 Co-located .md + property tests for uniformity.

4. Strategies

• 4.1 src/strategies/percentage-strategy/* — PercentageStrategy; deterministic bucketing.
• 4.2 src/strategies/user-target-strategy/*.
• 4.3 src/strategies/attribute-strategy/* — compareValues, getNestedValue, AttributeOperator, AttributeRule.
• 4.4 src/strategies/schedule-strategy/* — time-windowed rollout.
• 4.5 src/strategies/composite-strategy/* — AND/OR over child strategies.
• 4.6 Co-located .md + unit tests each.

5. Providers

• 5.1 src/providers/provider-interface/* — BaseFlagProvider abstract class.
• 5.2 src/providers/memory-provider/* — MemoryProvider.
• 5.3 src/providers/json-provider/* — JsonProvider, parseJsonFlags.
• 5.4 Co-located .md + tests; provider contract test suite reused across implementations.

6. Core evaluator

• 6.1 src/core/flag-registry/* — FlagRegistry; validates definitions via Zod.
• 6.2 src/core/evaluator/* — Evaluator; OTel histogram + counter.
• 6.3 src/core/flag-manager/* — FlagManager façade.
• 6.4 Emits FlagChangeEvent via @suaveplan/events.

7. Index + exports

• 7.1 Barrel src/index.ts — re-exports only.
• 7.2 Subpath exports per feature module.

8. Docs

• 8.1 Root README.md.
• 8.2 Co-located .md per .ts.

9. Benchmarks

• 9.1 src/__benchmarks__/evaluate.bench.ts — 1 / 5 / 25 strategy chain depth.

10. Ship gate

• 10.1 Verification sequence green.
• 10.2 Fold spec + archive.