Runtime Feature Flags

Use this checklist for temporary release toggles and risky features. It is self-contained: do not depend on the agent having read an ADR or public docs. Read apps/backend/AGENTS.md and apps/web/AGENTS.md when the change touches those subtrees.

Invariants

• The backend is authoritative. A disabled feature must not be reachable through HTTP, WebSocket, MCP, agent-tool, or background-job entry points.
• A new release toggle is off in every shipped profile when it is merged. The disabled path preserves the existing behavior and fails closed before deriving data, writing state, dispatching work, or exposing a capability.
• Effective values are ordered: explicit environment variable, SQLite override, then profile default. An explicit environment variable locks the admin UI.
• Use one identity across layers: features.<camelCaseKey>, KANDEV_FEATURES_<UPPER_SNAKE_CASE>, a Go FeaturesConfig field, its JSON tag, and the matching frontend key. Never add a parallel flag map or switch.
• Never reuse an identity recorded in the repository's append-only retired registry. Before relying on retirement, verify that retiredRuntimeFlagIdentities and its collision/completeness test exist; if they do not, add that runtimeflags infrastructure before removing a live flag.

Add a flag

Update these layers in the same change:

1. Profile default: add KANDEV_FEATURES_<NAME> under features: in the root profiles.yaml; use prod: "false", dev: "false", and e2e: "false" for a release toggle unless the task explicitly documents a test-only exception.
2. Backend config: add a bool field with explicit mapstructure and json tags to apps/backend/internal/common/config/config.go.
3. Registry/config binding: add exactly one metadata registration to apps/backend/internal/runtimeflags/registry.go: key, env var, kind, label, description, stability, risk, and restart/mutability metadata. The registry definition is metadata-only; add the key/env constants and update OptionsFromConfig, ValuesFromConfig, and ApplyStatesToConfig in runtimeflags/config.go for typed config wiring.
4. Backend gates: gate construction and every enabled-only entry path at the narrow composition boundary. Do not only hide the frontend; direct callers must receive the legacy behavior or a safe rejection.
5. Frontend contract: add the all-off key to apps/web/lib/state/slices/features/types.ts. Use useFeature() for client surfaces and notFound() from the relevant server layout/page when a route subtree must be unavailable. SSR data must remain fail-closed.
6. Tests: add enabled/disabled behavior tests for each changed backend path and frontend surface. Run the existing registry/profile/frontend contract tests; add focused tests for normalization, route visibility, and disabled side-effect prevention where applicable.

The completeness checks require exact equality between profile keys, typed backend fields/registrations, and frontend default keys. They do not discover semantic call sites, so trace the feature's HTTP, WebSocket, MCP, agent, worker, and startup paths manually.

Roll out and promote

1. Merge with all shipped profile defaults off.
2. Enable one installation through Settings > System > Feature Toggles or an explicit environment variable, restart when metadata requires it, and test real workflows.
3. When ready for everyone, change only the prod profile value to "true" for the next release. Retain the registry entry and backend/frontend gates as a kill switch so operators can still disable the feature.

Graduate and remove the flag

After the feature has proven itself as the default-on behavior, make the new behavior unconditional and remove the live flag end-to-end:

• remove the profile entry and FeaturesConfig field;
• remove the active registry registration;
• remove backend conditionals and legacy branches;
• remove the frontend default, useFeature() checks, and route gates;
• remove flag-specific tests and documentation while keeping permanent behavior coverage.

Before removing the registration, verify the append-only retiredRuntimeFlagIdentities registry and its collision/completeness test exist, then append the exact key and environment variable in registry.go:

{key: "features.example", envVar: "KANDEV_FEATURES_EXAMPLE"},

Do not delete old runtime_flag_overrides rows as part of graduation. Unknown rows are intentionally inert, and the retired identity prevents stale operator state from reactivating a future feature. Never reuse either the key or env var.

Verification and handoff

Run the focused checks appropriate to the change:

• In a fresh worktree, run pnpm install --frozen-lockfile from apps/ before any pnpm-based checks, tests, lint, or commits.
• from apps/backend: go test ./internal/runtimeflags ./internal/common/config ./internal/profiles;
• from the repository root: make -C apps/backend lint;
• from apps: pnpm --filter @kandev/web test -- lib/state/slices/features/features-contract.test.ts;
• from apps/web: pnpm run typecheck and pnpm run lint;
• run affected E2E coverage when the gated surface is user-visible;
• run git diff --check before handoff.

Report the flag key/env identity, profile defaults, every gated entry path, disabled/enabled test evidence, restart requirements, and whether the change is still a kill switch or has been fully graduated.