feat(ADM-018): completed feature

legacy/specs-old/F-004-config-flags/SPEC.md

@@ -0,0 +1,41 @@
+# SPEC — F-004 Typed config and feature flags
+
+## Problem
+Risky features need activation separate from deployment; env access must be typed.
+Today env access is ad-hoc (`process.env.X ?? fallback` scattered in entrypoints)
+and there is no activation mechanism distinct from deploy.
+
+## Goal
+Fail-fast typed config plus a simple feature flag module behind an interface.
+
+## Scope IN
+- Typed env config loader in `src/infrastructure/config`, fail fast on missing/invalid required vars (all problems reported in one clear message)
+- `FeatureFlagProvider` interface with simple in-memory store implementation (`src/modules/flags`)
+- Deployment ≠ activation: flags seed from `FLAG_*` env vars at boot and can be mutated at runtime without redeploy
+- DB pool refactor to consume config instead of sniffing env itself
+
+## Scope OUT
+- No external flag service
+- No per-user segmentation
+- No admin HTTP endpoint for flags yet (first consumer decides shape; store API is runtime-mutable already)
+
+## Required vs optional vars
+| Var | Required | Default |
+|---|---|---|
+| DATABASE_URL | yes | — |
+| PORT | no | 3000 (valid: integer 1–65535) |
+| HOST | no | 0.0.0.0 |
+| LOG_LEVEL | no | info |
+| NODE_ENV | no | development (valid: development/test/production) |
+| REDIS_URL | no | undefined |
+| FLAG_<NAME> | no | parsed as true/false |
+
+## Acceptance criteria
+1. Given a missing required env var When the app starts Then startup fails with a clear message naming the var.
+2. Given flag off When a code path guarded by the flag runs Then the path is skipped.
+3. Flag state change does not require redeploy (runtime `setEnabled` on the store).
+4. `./scripts/verify.sh` green.
+
+## Non-functional
+- No new dependencies: hand-rolled validation is small, explicit and boring.
+- Config loader is a pure function of an env object (testable without touching process.env).