ADR-004: Incremental migration toward SnapDiff v2 architecture

[pftg]

Vision

Consolidate the comparison pipeline from 25+ files / ~2,000 lines to 16 files / ~1,400 lines with 3 core objects: Comparison, Driver, Reporter.

Full ADR: .ai/adr-004-snap-diff-v2-vision.md
Migration plan: .ai/adr-004-migration-plan.md

Phase 1: Make Things More Alike (internal, no API changes)

• PR 1: Add vocabulary aliases (baseline_path, current_path, Driver#load, Driver#mask)
• PR 2: Merge DifferenceFinder into ImageCompare (delete 1 file)
• PR 3: Unify quick_equal? and different? into lazy evaluation
• PR 4: Merge StableScreenshoter into Screenshoter (delete 1 file)
• PR 5: Move skip_area masking from comparison-time to capture-time
• PR 6: Consolidate mattr_accessor into Config object (keep old API as delegates)

Phase 2: Separate Annotation from Reporting

• PR 7: Extract annotation (draw rectangles, heatmaps) into AnnotationService
• PR 8: Give Reporters::Default the record/finalize interface

Phase 3: Namespace Migration (needs major version)

• PR 9: Add SnapDiff namespace aliases (additive, non-breaking)
• PR 10: v2.0 — Make SnapDiff canonical, old namespace becomes shims

Constraints

• Each PR keeps tests green and public API unchanged (until Phase 3)
• No big-bang rewrite — Flocking Rules: make things more alike, then unify
• Do NOT delete Reporters::Default — it generates annotation images the HTML reporter needs
• Do NOT drop features: screenshot_section/group, median_filter, shift_distance_limit, LFS, delayed validation

Expected Outcome

Metric	Current	After Phase 1-2	After Phase 3
Files	25+	~18	~16
Lines	~2,000	~1,600	~1,400
Namespaces	2	2 (with aliases)	1 (SnapDiff)
Classes to understand pipeline	7	4	3
Config points	24 mattr_accessor	8 in Config + delegates	8 in Config

References

• ADR-004 vision: .ai/adr-004-snap-diff-v2-vision.md
• ADR-004 migration plan: .ai/adr-004-migration-plan.md
• ADR-001 (driver protocol): resolved — BaseDriver sufficient
• ADR-002 (HTML reporter): implemented in PR feat: add HTML reporter for visual diff dashboard #164
• ADR-003 (ComparisonResult): superseded by this issue

[pftg]

Status Update (2026-04-12)

Completed prerequisites

Item	PR	Notes
Driver contract tests (shared examples)	#174	Satisfies "PR 0" prerequisite from cross-review
Dead code removal (3 items)	#174	Cleaner starting point
Reporter record/finalize interface	#175	Thread-safe reporters with mutex; both Default and HTML now share the protocol
Reporter diff cleanup in Snap#delete!	#173	Annotation artifacts cleaned up properly
Test simplification (ADR-006)	#174, #177	Fixtures README, global state guard, test doubles cleanup

Validated cross-review findings

Three independent reviewers (code, architecture, DevXP) agreed on the same ordering:

1. PR 2 first — merge DifferenceFinder into ImageCompare (−1 file, ���80 lines)
2. PR 8 done — record/finalize interface shipped in thread safety: reporters and docs #175
3. PR 7 next ��� extract annotation from Reporters::Default
4. PR 9 — add SnapDiff namespace aliases
5. PR 10 — v2.0 make SnapDiff canonical

Rejected from original plan

PR	Reason
PR 1 (aliases)	Rename-before-extract anti-pattern
PR 3 (unify quick_equal?/different?)	Different semantics and performance characteristics
PR 4 (merge screenshoters)	Already resolved; different concepts
PR 5 (skip_area at capture-time)	Breaks baseline masking in real-world apps
PR 6 (Config object)	Touches every file; defer to after structural work
P1.1 (VIPS sequential)	Benchmarked, no measurable benefit

Next action

PR 2: Merge DifferenceFinder into ImageCompare — 7 micro-steps, all tests exist, independently revertable. Detailed plan in .ai/adr-004-migration-plan.md.