feat: add scheduled changes with calendar view

Pre-register planned changes before execution. Scheduled changes appear
in the change log (with a status filter) and on a new /calendar page
showing upcoming changes by month. Past-due scheduled changes are
surfaced as "overdue" and require explicit confirmation to close out.

Schema: split created_at (insert time) from event_at (semantic when),
add status ENUM('executed','scheduled') with idempotent migration.

Backend:
- ConfirmChange handler (PATCH /api/changes/:id/confirm), 409 on replay
- status= filter including virtual overdue (status=scheduled AND event_at < NOW())
- MCP confirm_change tool; register_change and list_changes updated for status

Frontend:
- Mode toggle (Already happened / Schedule for later) on AddChange and EditChangeDialog
- Scheduled/Overdue badges and Mark as Done on ChangeItem
- Status filter select in FilterBar
- Calendar page with overdue section, month grid, day detail panel

Tests: 67 frontend tests, 136 backend unit tests, all passing.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: jmartin82

README.md

@@ -22,8 +22,11 @@ OpsLedger provides a single source of truth for all changes made to your infrast
 
 ### Change Management
 - **Register Changes** - Log infrastructure, deployment, and configuration changes with rich metadata including system, environment, change type, and detailed descriptions
-- **Real-time Filtering** - Filter changes by system, environment, user, change type, and time range
+- **Scheduled Changes** - Pre-register planned changes before they happen. Scheduled changes appear in the change log and on a dedicated calendar view. Past-due scheduled changes are flagged as **overdue** and require explicit confirmation to close out
+- **Confirm Changes** - Mark a scheduled change as executed (via the change log, calendar, or API), optionally overriding the execution timestamp
+- **Real-time Filtering** - Filter changes by system, environment, user, change type, status (executed / scheduled / overdue), and time range
 - **Search & Autocomplete** - Quickly find changes with full-text search and intelligent autocomplete for systems, environments, and users
+- **Calendar View** - Visual month grid at `/calendar` showing upcoming scheduled changes with overdue highlighting and day-level detail
 
 ### Authentication & Authorization
 - **Role-Based Access Control** - Three roles with distinct permissions:
@@ -66,7 +69,7 @@ Teams can see what changes others are making, reducing duplicate work and improv
 
 ### Agent vs Human Change Tracking
 Track changes made by different sources to understand automation impact:
-- **MCP Agents** - Log changes from AI agents and automation tools (e.g., Claude Code, custom MCP servers)
+- **MCP Agents** - Log changes from AI agents and automation tools (e.g., Claude Code, custom MCP servers). Available MCP tools: `register_change`, `confirm_change`, `update_change`, `list_changes`, `delete_change`
 - **REST API** - Track changes made via direct API calls from external systems
 - **UI Changes** - Record changes made by humans through the web interface
 
@@ -152,13 +155,39 @@ VITE_API_URL=http://localhost:8081/api
 |--------|----------|-------------|
 | GET | `/api/changes` | List changes (supports filtering) |
 | POST | `/api/changes` | Create a new change |
+| PUT | `/api/changes/:id` | Update an existing change |
+| DELETE | `/api/changes/:id` | Delete a change |
+| PATCH | `/api/changes/:id/confirm` | Confirm a scheduled change as executed |
 
 **Supported Filters:**
 - `system` - Filter by system name
 - `environment` - Filter by environment (prod, staging, dev, etc.)
-- `type` - Filter by change type (infrastructure, deployment, configuration)
-- `user_id` - Filter by user
-- `from` / `to` - Date range filtering
+- `type` - Filter by change type (`infrastructure`, `deployment`, `configuration`)
+- `status` - Filter by status (`executed`, `scheduled`, `overdue`)
+- `user` - Filter by user
+- `from` / `to` - Date range filtering (ISO 8601)
+- `search` - Full-text search across description and system
+
+**Creating a scheduled change:**
+```json
+POST /api/changes
+{
+  "system": "api-gateway",
+  "type": "deployment",
+  "description": "Upgrade to v3.0",
+  "status": "scheduled",
+  "timestamp": "2026-06-15T10:00:00Z"
+}
+```
+When `status` is `"scheduled"`, `timestamp` is required and must be in the future.
+When `status` is `"executed"` (default), `timestamp` is optional and defaults to now.
+
+**Confirming a scheduled change:**
+```json
+PATCH /api/changes/:id/confirm
+{ "timestamp": "2026-06-15T10:05:00Z" }   // optional — defaults to now
+```
+Returns `409 Conflict` if the change is already executed.
 
 ### Admin API Keys
 

backend/database/migrations.go

@@ -1,6 +1,19 @@
 package database
 
-import "database/sql"
+import (
+	"database/sql"
+	"strings"
+)
+
+// isMySQLDupErr returns true for MySQL "duplicate column" (1060) or "duplicate key name" (1061).
+func isMySQLDupErr(err error) bool {
+	if err == nil {
+		return false
+	}
+	s := err.Error()
+	return strings.Contains(s, "Error 1060") || strings.Contains(s, "Duplicate column") ||
+		strings.Contains(s, "Error 1061") || strings.Contains(s, "Duplicate key name")
+}
 
 func Migrate(db *sql.DB) error {
 	_, err := db.Exec(`
@@ -49,16 +62,44 @@ func Migrate(db *sql.DB) error {
 			user        VARCHAR(255) NULL,
 			type        ENUM('infrastructure', 'deployment', 'configuration') NOT NULL,
 			description TEXT NOT NULL,
+			status      ENUM('executed', 'scheduled') NOT NULL DEFAULT 'executed',
+			event_at    DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
 			created_at  DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+			INDEX idx_changes_event_at   (event_at DESC),
 			INDEX idx_changes_created_at (created_at DESC),
 			INDEX idx_changes_system     (system),
-			INDEX idx_changes_type       (type)
+			INDEX idx_changes_type       (type),
+			INDEX idx_changes_status     (status)
 		)
 	`)
 	if err != nil {
 		return err
 	}
 
+	// Idempotent schema upgrades for existing deployments.
+	migrations := []string{
+		`ALTER TABLE changes ADD COLUMN status ENUM('executed','scheduled') NULL`,
+		`ALTER TABLE changes ADD COLUMN event_at DATETIME NULL`,
+		`UPDATE changes SET event_at = created_at WHERE event_at IS NULL`,
+		`UPDATE changes SET status = 'executed' WHERE status IS NULL`,
+		`ALTER TABLE changes MODIFY COLUMN status ENUM('executed','scheduled') NOT NULL DEFAULT 'executed'`,
+		`ALTER TABLE changes MODIFY COLUMN event_at DATETIME NOT NULL`,
+		`ALTER TABLE changes ADD INDEX idx_changes_event_at (event_at DESC)`,
+		`ALTER TABLE changes ADD INDEX idx_changes_status (status)`,
+	}
+	for _, m := range migrations {
+		if _, merr := db.Exec(m); merr != nil && !isMySQLDupErr(merr) {
+			// UPDATE and MODIFY statements won't trigger dup errors; only ADD COLUMN/INDEX can.
+			// Re-check: skip dup errors only for structural DDL, propagate data errors.
+			if strings.HasPrefix(m, "UPDATE ") || strings.HasPrefix(m, "ALTER TABLE changes MODIFY") {
+				return merr
+			}
+			if !isMySQLDupErr(merr) {
+				return merr
+			}
+		}
+	}
+
 	_, err = db.Exec(`
 		CREATE TABLE IF NOT EXISTS audit_log (
 			id          BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,

backend/handlers/changes.go

@@ -24,7 +24,12 @@ type createChangeRequest struct {
 	User        *string `json:"user"`
 	Type        string  `json:"type"`
 	Description string  `json:"description"`
-	Timestamp   *string `json:"timestamp"`
+	Status      string  `json:"status"`    // "executed" (default) | "scheduled"
+	Timestamp   *string `json:"timestamp"` // event_at: when it happened or when it's planned
+}
+
+type confirmChangeRequest struct {
+	Timestamp *string `json:"timestamp"` // actual execution time (optional)
 }
 
 type listChangesResponse struct {
@@ -53,7 +58,13 @@ func (h *ChangeHandler) Create(c echo.Context) error {
 		return c.JSON(http.StatusBadRequest, map[string]string{"error": "type must be infrastructure, deployment, or configuration"})
 	}
 
-	// Normalize empty strings to nil for nullable fields
+	if req.Status == "" {
+		req.Status = "executed"
+	}
+	if req.Status != "executed" && req.Status != "scheduled" {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "status must be executed or scheduled"})
+	}
+
 	env := req.Environment
 	if env != nil && *env == "" {
 		env = nil
@@ -72,7 +83,16 @@ func (h *ChangeHandler) Create(c echo.Context) error {
 		ts = &parsed
 	}
 
-	change, err := models.CreateChange(h.DB, req.System, env, user, req.Type, req.Description, ts)
+	if req.Status == "scheduled" {
+		if ts == nil {
+			return c.JSON(http.StatusBadRequest, map[string]string{"error": "timestamp is required for scheduled changes"})
+		}
+		if !ts.After(time.Now()) {
+			return c.JSON(http.StatusBadRequest, map[string]string{"error": "scheduled timestamp must be in the future"})
+		}
+	}
+
+	change, err := models.CreateChange(h.DB, req.System, env, user, req.Type, req.Description, req.Status, ts)
 	if err != nil {
 		return c.JSON(http.StatusInternalServerError, map[string]string{"error": "Failed to create change"})
 	}
@@ -108,6 +128,13 @@ func (h *ChangeHandler) Update(c echo.Context) error {
 		return c.JSON(http.StatusBadRequest, map[string]string{"error": "type must be infrastructure, deployment, or configuration"})
 	}
 
+	if req.Status == "" {
+		req.Status = "executed"
+	}
+	if req.Status != "executed" && req.Status != "scheduled" {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "status must be executed or scheduled"})
+	}
+
 	env := req.Environment
 	if env != nil && *env == "" {
 		env = nil
@@ -126,7 +153,11 @@ func (h *ChangeHandler) Update(c echo.Context) error {
 		ts = &parsed
 	}
 
-	change, err := models.UpdateChange(h.DB, id, req.System, env, user, req.Type, req.Description, ts)
+	if req.Status == "scheduled" && ts == nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "timestamp is required for scheduled changes"})
+	}
+
+	change, err := models.UpdateChange(h.DB, id, req.System, env, user, req.Type, req.Description, req.Status, ts)
 	if err != nil {
 		if err == sql.ErrNoRows {
 			return c.JSON(http.StatusNotFound, map[string]string{"error": "Change not found"})
@@ -141,6 +172,48 @@ func (h *ChangeHandler) Update(c echo.Context) error {
 	return c.JSON(http.StatusOK, change)
 }
 
+func (h *ChangeHandler) Confirm(c echo.Context) error {
+	if err := h.requireWriteAccess(c); err != nil {
+		return err
+	}
+
+	id := c.Param("id")
+	if _, err := uuid.Parse(id); err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "Invalid change ID"})
+	}
+
+	var req confirmChangeRequest
+	if err := c.Bind(&req); err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "Invalid request body"})
+	}
+
+	var executedAt *time.Time
+	if req.Timestamp != nil && *req.Timestamp != "" {
+		parsed, err := time.Parse(time.RFC3339, *req.Timestamp)
+		if err != nil {
+			return c.JSON(http.StatusBadRequest, map[string]string{"error": "Invalid timestamp format, use RFC3339"})
+		}
+		executedAt = &parsed
+	}
+
+	change, err := models.ConfirmChange(h.DB, id, executedAt)
+	if err != nil {
+		if err == sql.ErrNoRows {
+			return c.JSON(http.StatusNotFound, map[string]string{"error": "Change not found"})
+		}
+		if err == models.ErrAlreadyExecuted {
+			return c.JSON(http.StatusConflict, map[string]string{"error": "Change is already marked as executed"})
+		}
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": "Failed to confirm change"})
+	}
+
+	auditLog(h.DB, c, "change.confirm", "change", nil, strPtr(change.ID), strPtr(change.System+": "+change.Description))
+	if h.Hub != nil {
+		h.Hub.Publish(SSEEvent{Type: "change.updated", Data: change})
+	}
+	return c.JSON(http.StatusOK, change)
+}
+
 func (h *ChangeHandler) Delete(c echo.Context) error {
 	if err := h.requireWriteAccess(c); err != nil {
 		return err
@@ -151,7 +224,6 @@ func (h *ChangeHandler) Delete(c echo.Context) error {
 		return c.JSON(http.StatusBadRequest, map[string]string{"error": "Invalid change ID"})
 	}
 
-	// Fetch change first for audit log details
 	change, err := models.GetChangeByID(h.DB, id)
 	if err != nil {
 		if err == sql.ErrNoRows {
@@ -181,9 +253,14 @@ func (h *ChangeHandler) List(c echo.Context) error {
 		Environment: c.QueryParam("environment"),
 		User:        c.QueryParam("user"),
 		Type:        c.QueryParam("type"),
+		Status:      c.QueryParam("status"),
 		Search:      c.QueryParam("search"),
 	}
 
+	if c.QueryParam("sort") == "asc" {
+		f.SortAsc = true
+	}
+
 	if v := c.QueryParam("limit"); v != "" {
 		if n, err := strconv.Atoi(v); err == nil {
 			f.Limit = n
@@ -195,7 +272,6 @@ func (h *ChangeHandler) List(c echo.Context) error {
 		}
 	}
 
-	// Time range: explicit from/to take precedence over shorthand
 	if v := c.QueryParam("from"); v != "" {
 		if t, err := time.Parse(time.RFC3339, v); err == nil {
 			f.From = &t
@@ -273,6 +349,5 @@ func (h *ChangeHandler) requireReadAccess(c echo.Context) error {
 		return c.JSON(http.StatusForbidden, map[string]string{"error": "API key missing changes:read scope"})
 	}
 
-	// JWT: any authenticated user can read
 	return nil
 }