Skip to content

Dev/runtime divergence: migrate BOTH versions, don't pick

The pattern

When production infrastructure has two versions of the same code (a "dev" copy under development and a "runtime" copy actually executing in production), and they've diverged in content, migrate BOTH versions into the new structure in parallel subfolders. Do NOT try to pick one as canonical during migration.

The "pick one" instinct is wrong because you don't yet have enough context to know which is right: - The dev version may be ahead with unfinished work that needs to be completed or abandoned - The runtime version is what's actually running in production — picking the dev version replaces production with unverified code - Neither owner is necessarily around to clarify the divergence - Reconciling the divergence is a separate, non-trivial decision that deserves its own deliberation

Why it matters

On 2026-04-14, chief.staff migrated monday_sync.py from production. The initial assumption was there was one version. Investigation revealed:

  • ~/ecomonetize/Project.Manager/Code.Assistant/monday-sync/ (dev — 15 files)
  • ~/.ecomonetize/scripts/monday-sync/ (hidden runtime — 3 files)

The two versions were not identical: - monday_sync.py content differed - eri_crm_sync.py content differed - monday-sync-launcher.sh differed - Sync state JSON files had different snapshots

The launchd job com.ecomonetize.monday-sync was actually executing from the runtime location. The dev version had newer features (prospect_pipeline_sync.py, eri_lineage_tracer.py, add_crm_sync_fields.py, SKILL.md) that had never been promoted to runtime.

If chief.staff had picked one version during migration: - Picking dev → production runtime would have been replaced with unverified code that may have introduced regressions - Picking runtime → we'd have lost the newer dev features without understanding what they did or why they existed

The actual migration preserved both: - /Claude/scripts/integrations/monday/dev/ — 15 files from Code.Assistant/monday-sync/ - /Claude/scripts/integrations/monday/runtime/ — 3 files from .ecomonetize/scripts/monday-sync/

A README file documents the divergence explicitly and flags reconciliation as deferred work for code.platform when Active. No production state was disturbed. No unverified code was promoted. The decision of which version is canonical moves to a proper context where the reconciler has time to diff the files, understand the intent, and choose deliberately.

When to apply it

  • Any script migration where production and development locations exist in parallel
  • Any vendor migration where the "current version" and "pending version" diverge
  • Any configuration migration where staging and production environments have drifted
  • Any code rewrite where you're replacing a working thing with a new thing — keep the old version as old/ or legacy/ until the new thing is verified

When NOT to apply it

  • When you KNOW the divergence is trivial (whitespace, formatting, minor comment changes) — in those cases, a clean pick with diff review is fine
  • When migration is urgent and you need to reduce surface area, not expand it — flag the divergence as technical debt and pick pragmatically, but document the choice
  • When storage cost is prohibitive — rarely applies for text files, occasionally applies for large binary artifacts

How to apply it

  1. Enumerate the parallel locations — find or ls every candidate source location before deciding
  2. Diff them — diff -rq tells you which files differ and which are identical
  3. Create symmetric subfolders in the destination — dev/ and runtime/, or legacy/ and new/, or whatever names match the source semantics
  4. Copy BOTH versions preserving the structure from each
  5. Write a README documenting what differed and what the reconciliation path is
  6. File a task or ADR for the eventual reconciliation decision, routed to the right owner
  7. Do not touch production runtime until the reconciliation decision is made and tested

Examples

2026-04-14 — monday-sync migration — the canonical instance. Described above in detail.

Hypothetical counter-example: if chief.staff had been asked to migrate 50 scripts under time pressure and picked dev versions for all of them to save time, the migration would have replaced 6 weeks of production-tested code with dev versions that hadn't been verified. Silent failures. Debugging hell.

  • [[/Claude/scripts/integrations/monday/README]] — the README documenting this specific migration
  • /Claude/operations/reports/briefings/task-script-migration-2026-04-14.md — the full script migration task brief for code.platform
  • [[DR-002-per-agent-cwd-memory-isolation]] — similar "preserve both and migrate carefully" pattern applied to memory namespaces

Source

The 2026-04-14 monday-sync migration. chief.staff nearly picked one version but caught the divergence during inventory. The check-twice-cut-once instinct was right.

Status

Guideline — promote to strong-recommendation if a second instance of dev/runtime divergence appears and the pattern produces the same benefit.