feat(domain): seasonal tagging for maintenance items (#733)

## Summary

- Add `Season` string field to `MaintenanceItem` with constants: spring,
summer, fall, winter (empty = no season)
- New "Season" table column with `cellStatus` badge rendering and
pin-filtering support
- Season select field in add/edit forms and inline edit overlay
- "Seasonal" dashboard section showing items tagged with the current
calendar season (Mar-May spring, Jun-Aug summer, Sep-Nov fall, Dec-Feb
winter)
- Short labels in compact mode: spr/sum/fall/win
- Status styles for all four seasons (Wong palette colors)

closes #686

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: cpcloud

AGENTS.md

@@ -236,10 +236,12 @@ details; do not duplicate that detail here.
   model fields directly. Internal/unit tests are permitted only after
   user-interaction tests exist and only when you judge them genuinely
   necessary as supplements.
-- **Regression tests are strict TDD**: Write a test that reproduces the
-  bug first, confirm it fails, then iterate on the fix until the test
-  passes. Do not game this by wildly mutating code just to satisfy the
-  test -- fix the actual root cause.
+- **Test-first for all feature work and bug fixes**: Write tests that
+  fully describe the desired behavior before writing the implementation.
+  Confirm they fail, then implement to make them pass. Tests are the
+  spec -- if the tests pass but the feature is incomplete or the bug
+  still reproduces, the tests are wrong. Do not game this by wildly
+  mutating code just to satisfy the test -- fix the actual root cause.
 - **Use `testify/assert` and `testify/require`**: `require` for
   preconditions, `assert` for assertions. No bare `t.Fatal`/`t.Error`.
 - **Test every error path**: Every function that can fail needs at least

internal/app/compact.go

@@ -27,6 +27,11 @@ var statusLabels = map[string]string{
 	"urgent":   "urg",
 	"soon":     "soon",
 	"whenever": "low",
+	// Seasons.
+	"spring": "spr",
+	"summer": "sum",
+	"fall":   "fall",
+	"winter": "win",
 }
 
 // statusLabel returns the short display label for a status value.

internal/app/dashboard.go

@@ -20,6 +20,7 @@ const (
 	dashSectionIncidents = "Incidents"
 	dashSectionOverdue   = "Overdue"
 	dashSectionUpcoming  = "Upcoming"
+	dashSectionSeasonal  = "Seasonal"
 	dashSectionProjects  = "Active Projects"
 	dashSectionExpiring  = "Expiring Soon"
 )
@@ -41,6 +42,7 @@ func (m *Model) dashboardHeader() string {
 type dashboardData struct {
 	Overdue            []maintenanceUrgency
 	Upcoming           []maintenanceUrgency
+	Seasonal           []data.MaintenanceItem
 	ActiveProjects     []data.Project
 	OpenIncidents      []data.Incident
 	ExpiringWarranties []warrantyStatus
@@ -50,6 +52,7 @@ type dashboardData struct {
 func (d dashboardData) empty() bool {
 	return len(d.Overdue) == 0 &&
 		len(d.Upcoming) == 0 &&
+		len(d.Seasonal) == 0 &&
 		len(d.ActiveProjects) == 0 &&
 		len(d.OpenIncidents) == 0 &&
 		len(d.ExpiringWarranties) == 0 &&
@@ -281,6 +284,13 @@ func (m *Model) loadDashboardAt(now time.Time) error {
 	d.Overdue = capSlice(d.Overdue, 10)
 	d.Upcoming = capSlice(d.Upcoming, 10)
 
+	// Seasonal maintenance (items tagged with the current season).
+	currentSeason := data.SeasonForMonth(now.Month())
+	d.Seasonal, err = m.store.ListMaintenanceBySeason(currentSeason)
+	if err != nil {
+		return fmt.Errorf("load seasonal maintenance: %w", err)
+	}
+
 	// Active projects.
 	d.ActiveProjects, err = m.store.ListActiveProjects()
 	if err != nil {
@@ -380,6 +390,10 @@ func (m *Model) buildDashNav() {
 		d.Upcoming, tabMaintenance, dashSectionUpcoming,
 		func(e maintenanceUrgency) uint { return e.Item.ID },
 	))
+	add(dashSectionSeasonal, dashNavSection(
+		d.Seasonal, tabMaintenance, dashSectionSeasonal,
+		func(item data.MaintenanceItem) uint { return item.ID },
+	))
 	add(dashSectionProjects, dashNavSection(
 		d.ActiveProjects, tabProjects, dashSectionProjects,
 		func(p data.Project) uint { return p.ID },
@@ -475,6 +489,14 @@ func (m *Model) dashboardView(budget, maxWidth int) string {
 		})
 	}
 
+	if seasonalRows := m.dashSeasonalRows(); len(seasonalRows) > 0 {
+		sections = append(sections, dashSection{
+			title:   dashSectionSeasonal,
+			headers: []string{"", "category"},
+			rows:    seasonalRows,
+		})
+	}
+
 	if projRows := m.dashProjectRows(); len(projRows) > 0 {
 		sections = append(sections, dashSection{
 			title:   dashSectionProjects,
@@ -667,6 +689,21 @@ func (m *Model) maintUrgencyRows(
 	return rows
 }
 
+func (m *Model) dashSeasonalRows() []dashRow {
+	d := m.dash.data
+	rows := make([]dashRow, 0, len(d.Seasonal))
+	for _, item := range d.Seasonal {
+		rows = append(rows, dashRow{
+			Cells: []dashCell{
+				{Text: item.Name, Style: m.styles.DashValue()},
+				{Text: item.Category.Name, Style: m.styles.DashLabel()},
+			},
+			Target: &dashNavEntry{Tab: tabMaintenance, ID: item.ID},
+		})
+	}
+	return rows
+}
+
 func (m *Model) dashProjectRows() []dashRow {
 	d := m.dash.data
 	now := time.Now()

internal/app/dashboard_test.go

@@ -247,6 +247,45 @@ func TestDashboardViewWithData(t *testing.T) {
 	assert.Contains(t, view, "overdue")
 }
 
+func TestDashboardViewSeasonalSection(t *testing.T) {
+	t.Parallel()
+	m := newTestModel(t)
+	m.width = 120
+	m.height = 40
+
+	m.dash.data = dashboardData{
+		Seasonal: []data.MaintenanceItem{
+			{ID: 1, Name: "Clean Gutters", Season: data.SeasonSpring},
+			{ID: 2, Name: "Service AC", Season: data.SeasonSpring},
+		},
+	}
+	m.dash.expanded = map[string]bool{
+		dashSectionSeasonal: true,
+	}
+	m.prepareDashboardView()
+
+	view := m.dashboardView(50, 120)
+	assert.Contains(t, view, "Clean Gutters")
+	assert.Contains(t, view, "Service AC")
+	assert.Contains(t, view, "Seasonal")
+}
+
+func TestDashboardSeasonalEmpty(t *testing.T) {
+	t.Parallel()
+	m := newTestModel(t)
+	m.width = 120
+	m.height = 40
+
+	m.dash.data = dashboardData{
+		Seasonal: nil,
+	}
+	m.prepareDashboardView()
+
+	view := m.dashboardView(50, 120)
+	assert.NotContains(t, view, "Seasonal",
+		"seasonal section should not appear when there are no seasonal items")
+}
+
 func TestDashboardViewIncidentsFirst(t *testing.T) {
 	t.Parallel()
 	m := newTestModel(t)

internal/app/form_save_test.go

@@ -488,6 +488,159 @@ func TestUserEditsMaintenanceFromIntervalToNone(t *testing.T) {
 	assert.Empty(t, cells[int(maintenanceColEvery)].Value)
 }
 
+// User creates a maintenance item with a season tag.
+func TestUserCreatesMaintenanceWithSeason(t *testing.T) {
+	t.Parallel()
+	m := newTestModelWithStore(t)
+	m.active = tabIndex(tabMaintenance)
+	openAddForm(m)
+
+	values, ok := m.fs.formData.(*maintenanceFormData)
+	require.True(t, ok)
+	values.Name = "Clean Gutters"
+	values.Season = data.SeasonSpring
+	sendKey(m, "ctrl+s")
+	sendKey(m, "esc")
+
+	// Verify persisted to DB.
+	items, err := m.store.ListMaintenance(false)
+	require.NoError(t, err)
+	require.Len(t, items, 1)
+	assert.Equal(t, data.SeasonSpring, items[0].Season)
+
+	// Verify table column renders the season.
+	m.reloadAll()
+	require.NoError(t, m.reloadActiveTab())
+	tab := m.activeTab()
+	require.NotEmpty(t, tab.CellRows)
+	seasonCell := tab.CellRows[0][int(maintenanceColSeason)]
+	assert.Equal(t, data.SeasonSpring, seasonCell.Value)
+	assert.Equal(t, cellStatus, seasonCell.Kind)
+}
+
+// User edits a maintenance item to change its season.
+func TestUserEditsMaintenanceSeason(t *testing.T) {
+	t.Parallel()
+	m := newTestModelWithStore(t)
+	m.active = tabIndex(tabMaintenance)
+
+	// Create with spring.
+	openAddForm(m)
+	values, ok := m.fs.formData.(*maintenanceFormData)
+	require.True(t, ok)
+	values.Name = "Service AC"
+	values.Season = data.SeasonSpring
+	sendKey(m, "ctrl+s")
+	sendKey(m, "esc")
+
+	m.reloadAll()
+	require.NoError(t, m.reloadActiveTab())
+	tab := m.activeTab()
+	require.NotEmpty(t, tab.Rows)
+	tab.Table.SetCursor(0)
+	id := tab.Rows[0].ID
+
+	// Open full edit form via ID column.
+	sendKey(m, "i")
+	tab.ColCursor = int(maintenanceColID)
+	sendKey(m, "e")
+	require.Equal(t, modeForm, m.mode)
+
+	editValues, ok := m.fs.formData.(*maintenanceFormData)
+	require.True(t, ok)
+	assert.Equal(t, data.SeasonSpring, editValues.Season,
+		"edit form should pre-fill existing season")
+
+	// Change to fall.
+	editValues.Season = data.SeasonFall
+	sendKey(m, "ctrl+s")
+	sendKey(m, "esc")
+
+	item, err := m.store.GetMaintenance(id)
+	require.NoError(t, err)
+	assert.Equal(t, data.SeasonFall, item.Season)
+}
+
+// User creates a maintenance item without a season (defaults to none).
+func TestUserCreatesMaintenanceWithoutSeason(t *testing.T) {
+	t.Parallel()
+	m := newTestModelWithStore(t)
+	m.active = tabIndex(tabMaintenance)
+	openAddForm(m)
+
+	values, ok := m.fs.formData.(*maintenanceFormData)
+	require.True(t, ok)
+	values.Name = "General Checkup"
+	// Season left empty (default).
+	sendKey(m, "ctrl+s")
+	sendKey(m, "esc")
+
+	items, err := m.store.ListMaintenance(false)
+	require.NoError(t, err)
+	require.Len(t, items, 1)
+	assert.Empty(t, items[0].Season)
+
+	// Table cell should be null.
+	m.reloadAll()
+	require.NoError(t, m.reloadActiveTab())
+	tab := m.activeTab()
+	require.NotEmpty(t, tab.CellRows)
+	seasonCell := tab.CellRows[0][int(maintenanceColSeason)]
+	assert.True(t, seasonCell.Null, "empty season should produce a null cell")
+}
+
+// User inline-edits the Season column on a maintenance item.
+func TestUserInlineEditsMaintenanceSeason(t *testing.T) {
+	t.Parallel()
+	m := newTestModelWithStore(t)
+	m.active = tabIndex(tabMaintenance)
+
+	// Create with spring season.
+	openAddForm(m)
+	values, ok := m.fs.formData.(*maintenanceFormData)
+	require.True(t, ok)
+	values.Name = "Service AC"
+	values.Season = data.SeasonSpring
+	sendKey(m, "ctrl+s")
+	sendKey(m, "esc")
+
+	// Reload and position on the maintenance tab.
+	m.reloadAll()
+	require.NoError(t, m.reloadActiveTab())
+	tab := m.activeTab()
+	require.NotEmpty(t, tab.Rows)
+	tab.Table.SetCursor(0)
+	id := tab.Rows[0].ID
+
+	// Enter edit mode, position on the Season column, press 'e'.
+	sendKey(m, "i")
+	tab.ColCursor = int(maintenanceColSeason)
+	sendKey(m, "e")
+	require.Equal(t, modeForm, m.mode, "Season inline edit should open form overlay")
+
+	// The form data should reflect the current season.
+	fd, ok := m.fs.formData.(*maintenanceFormData)
+	require.True(t, ok)
+	assert.Equal(t, data.SeasonSpring, fd.Season)
+
+	// Change to winter and save.
+	fd.Season = data.SeasonWinter
+	sendKey(m, "ctrl+s")
+
+	// Verify DB was updated.
+	item, err := m.store.GetMaintenance(id)
+	require.NoError(t, err)
+	assert.Equal(t, data.SeasonWinter, item.Season)
+
+	// Verify table cell updated after reload.
+	m.reloadAll()
+	require.NoError(t, m.reloadActiveTab())
+	tab = m.activeTab()
+	require.NotEmpty(t, tab.CellRows)
+	seasonCell := tab.CellRows[0][int(maintenanceColSeason)]
+	assert.Equal(t, data.SeasonWinter, seasonCell.Value)
+}
+
 // When ScheduleType is "due_date", stale IntervalMonths values are ignored.
 func TestScheduleTypeDueDateIgnoresStaleInterval(t *testing.T) {
 	t.Parallel()