diff --git a/.planning/phases/01-semantic-position-model/01-CONTEXT.md b/.planning/phases/01-semantic-position-model/01-CONTEXT.md new file mode 100644 index 0000000..4dbefae --- /dev/null +++ b/.planning/phases/01-semantic-position-model/01-CONTEXT.md @@ -0,0 +1,68 @@ +# Phase 1: Semantic Position Model - Context + +**Gathered:** 2026-01-18 +**Status:** Ready for planning + + +## Phase Boundary + +All movable items have a persistent semantic position `(day: Int, sortOrder: Double)` that survives data reloads. Games are immovable anchors ordered by game time. Travel segments and custom items can be repositioned. This phase establishes the data model only — constraint validation, flattening, and drag interaction are separate phases. + + + + +## Implementation Decisions + +### sortOrder assignment +- Use integer spacing (1, 2, 3...) for initial sortOrder values +- Midpoint insertion (1.5, 1.25, etc.) when placing between items +- Claude's discretion on threshold/rebalancing strategy when gaps get very small +- Claude's discretion on negative vs positive sortOrder for "before games" items +- Claude's discretion on Double vs Decimal storage type + +### Day boundaries +- Day = trip day backed by calendar date (Day 1 = trip.startDate, Day 2 = startDate + 1, etc.) +- Day number derived as: `calendar_days_since(trip.startDate) + 1` +- Games belong to their start date, even if they run past midnight +- Show all days including empty ones (no skipping gaps in the trip) + +### Travel segment identity +- Each travel segment has a unique UUID (not keyed by route) +- Same route (e.g., Chicago→Boston) can appear multiple times in a trip +- Travel carries: from city, to city, estimated distance, estimated duration +- Moving travel to different day just updates the day property (no recalculation) + +### Position initialization +- Games get sortOrder assigned by Claude based on game time +- Auto-generated travel appears after the origin city's games +- Custom items added via "+" button on day headers, inserted at top of that day +- Claude's discretion on handling position updates when trip is edited + +### Claude's Discretion +- Exact sortOrder rebalancing threshold and strategy +- Whether to use negative sortOrder or offset games to higher values for "before" positioning +- Double vs Decimal for sortOrder storage +- Initial sortOrder derivation for games (time-based or sequential) +- Position preservation vs recomputation on trip edits + + + + +## Specific Ideas + +- Day headers should have a "+" button for adding custom items +- When user taps "+", item is added to top of that day (lowest sortOrder) + + + + +## Deferred Ideas + +None — discussion stayed within phase scope + + + +--- + +*Phase: 01-semantic-position-model* +*Context gathered: 2026-01-18*