Cutover, Not Compatibility

When replacing a system, component, or pattern, do a clean cutover. Delete the old code. Update all call sites. Source: AGENTS.md

Two implementations of the same thing is worse than either one alone. It doubles the surface area for bugs and confuses every future reader about which path is canonical.

The Rule

Do not leave backward-compatible shims, feature flags, or "legacy" adapters unless explicitly asked to preserve them. If the old thing needs to exist temporarily, the human co-programmer will say so.

Application

For tooling upgrades like oxlint or oxfmt, apply the cutover uniformly across the monorepo. Do not leave mixed legacy lint paths unless a specific rule gap is documented.

Documented exceptions exist only where a specific technical constraint demands them: the root ESLint config for Nx module boundaries and the apps/cloud linting/runtime configs pending a separate migration.

Why Not Gradual Migration

Gradual migration sounds safer. In practice it means two code paths, two mental models, and ambiguity about which one is "right." Every new contributor asks "which one should I use?" Every bug report requires checking both paths. The migration stalls because the old path "still works." The codebase accumulates permanent dual implementations that nobody cleans up.

A clean cutover is more work upfront. It pays for itself immediately in reduced confusion, fewer bugs, and a single canonical path forward.

Concept Position

---

Timeline

• 2026-07-01 | Concepts category refresh added this page to the Agent harness and runtime primitives family, linked it to Concept System Map, and kept it standalone because it owns this reusable mental model: When replacing a system, component, or pattern, do a clean cutover. Delete the old code. Update all call sites. Source: AGENTS.md. Source: User request, 2026-07-01