Skip to main content
The MERIDIAN specification referenced Automerge for the CRDT layer, but the implementation used Yjs because it was lighter-weight and already had 35 passing tests when CLI integration time came (TASKSET 11). The question was: migrate to Automerge to match the spec, or update the spec to match reality? Decision: Update the spec. Yjs already worked with 7 merge strategies (last_write_wins, manual_resolution, union_merge, append_wins, highest_restriction_wins, recompute_post_merge, immutable). Migrating to Automerge would mean rewriting the entire CRDT package for zero user-facing improvement. The spec is text — changing it costs minutes. The code is tested infrastructure — changing it costs weeks. Applicable pattern: When a spec and an implementation diverge, evaluate which is more expensive to change. Specs should describe what the system does, not prescribe library choices. If the abstraction boundary is correct (field-level merge strategies, conflict detection, resolution), the underlying CRDT engine is an implementation detail. Document the divergence explicitly (we added a “Yjs, not Automerge” note to CLAUDE.md and CRDT.skill.md) so future developers understand it was a deliberate choice, not an oversight.