Obsolete code cleanup

Dead Code & Compatibility Cleanup

Unreachable branches, stale feature flags, abandoned v1 adapters and unused exports impose a constant cognitive tax on every developer reading or refactoring the codebase. However, deleting code that only looks unused to static search can break dynamic dispatch, reflection, external consumers or operational runbooks. Verify reachability rigorously before deleting.

1. Why Static Search Alone Is Not Enough

Before concluding that a symbol, file, route or config key is dead, check all non-static reference channels:

1. Static imports and call sites: search across the entire repository (including workspaces, packages, scripts, tests and templates).
2. Dynamic & string-based resolution:
   • Dependency injection containers, service providers, event/command buses, queue job handlers, webhook routers and ORM model/migration registries.
   • Dynamic property access (handlers[actionType]), dynamic import(), template partials, CLI command auto-loaders and localization/i18n keys (data-i18n, dynamic key prefixes).
3. External & cross-version boundaries:
   • Public package exports (package.json exports/main, barrel index.ts files).
   • HTTP/RPC routes still called by mobile/desktop clients, webhooks, cron jobs or third-party integrations.
   • Persisted job payloads or database records that still reference a legacy class/type name.
4. Build, CI & operational scripts: Dockerfiles, CI workflows, package.json scripts, deployment hooks and database seeders.

2. Cleaning Up Feature Flags & Compatibility Shims

Temporary shims and feature flags introduced during migrations or rollouts must be retired cleanly once cutover is complete:

• Determine the active branch: check configuration defaults, environment variables and flag definitions to confirm which branch (true or false, v1 or v2) is permanently active across environments.
• Collapse the conditional: remove the flag check and the dead branch, simplify the control flow, and update tests that were testing the retired branch.
• Retire Expand-and-Contract adapters: once all callers and persisted payloads use the new contract, remove dual-write/dual-read fallback logic, deprecated aliases and translation wrappers.

3. Safe Deletion & Orphan Sweeping

When removing a verified dead entry point, follow the dependency chain inward so you do not leave newly orphaned helpers behind:

1. Remove the dead entry point (unused route, obsolete handler, retired component or deprecated adapter).
2. Sweep newly orphaned internals: check whether private helpers, types, styles, i18n keys, test fixtures, mocks or third-party dependencies were referenced only by the deleted code, and remove them in the same cleanup.
3. Distinguish dead code from unfinished work: if an unreferenced module looks like an intentionally staged or partially implemented feature from a recent task, check git history and task context before deleting it; if uncertain, flag it rather than deleting silently.
4. Verify cleanly: run the full typecheck, linter, test suite and production build to confirm nothing references the removed symbols.