feat: add annotations, undo system, and schema updates

Add annotations as JSON column on tasks table with Annotate/Denotate
methods and CLI commands. Add undo system backed by change_log with
lightweight undo_stack table (capped at 10 entries). All mutating CLI
commands (add, done, delete, modify, start, stop) now record undo
entries. Undo restores prior task state from change_log data.

Schema changes (in v1 migration):
- annotations TEXT column on tasks
- undo_stack table
- annotations field in change_log triggers

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

opal-task/cmd/add.go

@@ -63,6 +63,8 @@ func addTask(args []string) error {
 		return fmt.Errorf("failed to create task: %w", err)
 	}
 
+	engine.RecordUndo("add", task.UUID)
+
 	displayID, err := engine.AppendTask(task)
 	if err != nil {
 		// Non-fatal: task was created, just can't assign display ID
@@ -113,6 +115,8 @@ func addRecurringTask(description string, mod *engine.Modifier) error {
 		return err
 	}
 
+	engine.RecordUndo("add", instance.UUID)
+
 	displayID, err := engine.AppendTask(instance)
 	if err != nil {
 		fmt.Printf("Created recurring task %s\n", *instance.ParentUUID)

opal-task/cmd/annotate.go

@@ -0,0 +1,80 @@
+package cmd
+
+import (
+	"fmt"
+	"os"
+	"strings"
+
+	"git.jnss.me/joakim/opal/internal/engine"
+	"github.com/spf13/cobra"
+)
+
+var annotateCmd = &cobra.Command{
+	Use:   "annotate [filter...] [text]",
+	Short: "Add an annotation to a task",
+	Long: `Add a timestamped annotation to a task.
+
+Examples:
+  opal 2 annotate Traced to token expiry in middleware
+  opal annotate +bug Found root cause in auth handler`,
+	Run: func(cmd *cobra.Command, args []string) {
+		parsed := getParsedArgs(cmd)
+		if err := annotateTask(parsed.Filters, parsed.Modifiers); err != nil {
+			fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+			os.Exit(1)
+		}
+	},
+}
+
+func annotateTask(filterArgs, textArgs []string) error {
+	if len(filterArgs) == 0 {
+		return fmt.Errorf("no task specified")
+	}
+
+	if len(textArgs) == 0 {
+		return fmt.Errorf("annotation text is required")
+	}
+
+	text := strings.Join(textArgs, " ")
+
+	filter, err := engine.ParseFilter(filterArgs)
+	if err != nil {
+		return fmt.Errorf("failed to parse filter: %w", err)
+	}
+
+	ws, err := engine.LoadWorkingSet()
+	if err != nil {
+		return fmt.Errorf("failed to load working set: %w", err)
+	}
+
+	var task *engine.Task
+
+	if len(filter.IDs) > 0 {
+		if len(filter.IDs) != 1 {
+			return fmt.Errorf("annotate requires exactly one task")
+		}
+		task, err = ws.GetTaskByDisplayID(filter.IDs[0])
+		if err != nil {
+			return err
+		}
+	} else {
+		tasks, err := engine.GetTasks(filter)
+		if err != nil {
+			return fmt.Errorf("failed to get tasks: %w", err)
+		}
+		if len(tasks) == 0 {
+			return fmt.Errorf("no tasks matched filter")
+		}
+		if len(tasks) > 1 {
+			return fmt.Errorf("annotate requires exactly one task (filter matched %d)", len(tasks))
+		}
+		task = tasks[0]
+	}
+
+	if err := task.Annotate(text); err != nil {
+		return fmt.Errorf("failed to annotate task: %w", err)
+	}
+
+	fmt.Printf("Annotated task %s\n", engine.FormatTaskSummary(task, ws))
+	return nil
+}

opal-task/cmd/delete.go

@@ -72,6 +72,7 @@ func deleteTasks(args []string) error {
 
 	for _, task := range tasks {
 		task.Delete(false) // Soft delete
+		engine.RecordUndo("delete", task.UUID)
 	}
 
 	if len(tasks) == 1 {

opal-task/cmd/denotate.go

@@ -0,0 +1,74 @@
+package cmd
+
+import (
+	"fmt"
+	"os"
+
+	"git.jnss.me/joakim/opal/internal/engine"
+	"github.com/spf13/cobra"
+)
+
+var denotateCmd = &cobra.Command{
+	Use:   "denotate [filter...]",
+	Short: "Remove the most recent annotation from a task",
+	Long: `Remove the most recent annotation from a task.
+
+Examples:
+  opal 2 denotate
+  opal denotate +bug`,
+	Run: func(cmd *cobra.Command, args []string) {
+		parsed := getParsedArgs(cmd)
+		if err := denotateTask(parsed.Filters); err != nil {
+			fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+			os.Exit(1)
+		}
+	},
+}
+
+func denotateTask(filterArgs []string) error {
+	if len(filterArgs) == 0 {
+		return fmt.Errorf("no task specified")
+	}
+
+	filter, err := engine.ParseFilter(filterArgs)
+	if err != nil {
+		return fmt.Errorf("failed to parse filter: %w", err)
+	}
+
+	ws, err := engine.LoadWorkingSet()
+	if err != nil {
+		return fmt.Errorf("failed to load working set: %w", err)
+	}
+
+	var task *engine.Task
+
+	if len(filter.IDs) > 0 {
+		if len(filter.IDs) != 1 {
+			return fmt.Errorf("denotate requires exactly one task")
+		}
+		task, err = ws.GetTaskByDisplayID(filter.IDs[0])
+		if err != nil {
+			return err
+		}
+	} else {
+		tasks, err := engine.GetTasks(filter)
+		if err != nil {
+			return fmt.Errorf("failed to get tasks: %w", err)
+		}
+		if len(tasks) == 0 {
+			return fmt.Errorf("no tasks matched filter")
+		}
+		if len(tasks) > 1 {
+			return fmt.Errorf("denotate requires exactly one task (filter matched %d)", len(tasks))
+		}
+		task = tasks[0]
+	}
+
+	removed, err := task.Denotate()
+	if err != nil {
+		return err
+	}
+
+	fmt.Printf("Removed annotation: %s\n", removed.Text)
+	return nil
+}

opal-task/cmd/done.go

@@ -89,6 +89,7 @@ func completeTasks(args []string) error {
 		if _, err := task.Complete(); err != nil {
 			fmt.Fprintf(os.Stderr, "Warning: failed to complete task %s: %v\n", task.UUID, err)
 		} else {
+			engine.RecordUndo("done", task.UUID)
 			completed++
 		}
 	}

opal-task/cmd/edit.go

@@ -198,6 +198,17 @@ func generateEditableContent(task *engine.Task) string {
 		sb.WriteString("tags: \n")
 	}
 
+	// Annotations
+	sb.WriteString("\n# Annotations (add/remove/modify lines below)\n")
+	if len(task.Annotations) > 0 {
+		for i, ann := range task.Annotations {
+			ts := time.Unix(ann.Timestamp, 0).Format("2006-01-02 15:04")
+			sb.WriteString(fmt.Sprintf("annotation.%d: %s | %s\n", i+1, ts, ann.Text))
+		}
+	}
+	sb.WriteString("# To add: annotation.N: YYYY-MM-DD HH:MM | text\n")
+	sb.WriteString("# To remove: delete the line\n")
+
 	return sb.String()
 }
 
@@ -362,6 +373,32 @@ func applyNonStatusFields(task *engine.Task, fields map[string]string) error {
 		}
 	}
 
+	// Annotations - rebuild from annotation.N fields
+	var newAnnotations []engine.Annotation
+	for key, value := range fields {
+		if strings.HasPrefix(key, "annotation.") && value != "" {
+			parts := strings.SplitN(value, " | ", 2)
+			if len(parts) == 2 {
+				ts, err := time.Parse("2006-01-02 15:04", strings.TrimSpace(parts[0]))
+				if err != nil {
+					// If we can't parse the timestamp, use current time
+					ts = time.Now()
+				}
+				newAnnotations = append(newAnnotations, engine.Annotation{
+					Timestamp: ts.Unix(),
+					Text:      strings.TrimSpace(parts[1]),
+				})
+			} else {
+				// No timestamp separator, treat entire value as text
+				newAnnotations = append(newAnnotations, engine.Annotation{
+					Timestamp: time.Now().Unix(),
+					Text:      strings.TrimSpace(value),
+				})
+			}
+		}
+	}
+	task.Annotations = newAnnotations
+
 	// Tags - replace all tags
 	if tagsStr, ok := fields["tags"]; ok {
 		// Remove all existing tags

opal-task/cmd/modify.go

@@ -114,6 +114,7 @@ func modifyTasks(filterArgs, modifierArgs []string) error {
 		if err := mod.Apply(task); err != nil {
 			fmt.Fprintf(os.Stderr, "Warning: failed to modify task %s: %v\n", task.UUID, err)
 		} else {
+			engine.RecordUndo("modify", task.UUID)
 			modified++
 		}
 	}

opal-task/cmd/root.go

@@ -34,7 +34,7 @@ var commandNames = []string{
 	"add", "done", "modify", "delete",
 	"start", "stop", "count", "projects", "tags",
 	"info", "edit", "server", "sync", "reports", "setup",
-	"version",
+	"version", "annotate", "denotate", "undo",
 }
 
 // Report names (dynamically populated)
@@ -47,6 +47,7 @@ var reportNames = []string{
 var commandsWithModifiers = map[string]bool{
 	"add":      true,
 	"modify":   true,
+	"annotate": true,
 }
 
 var rootCmd = &cobra.Command{
@@ -235,6 +236,9 @@ func init() {
 	rootCmd.AddCommand(editCmd)
 	rootCmd.AddCommand(reportsCmd)
 	rootCmd.AddCommand(versionCmd)
+	rootCmd.AddCommand(annotateCmd)
+	rootCmd.AddCommand(denotateCmd)
+	rootCmd.AddCommand(undoCmd)
 
 	// Enable --version flag on root command
 	rootCmd.Version = Version

opal-task/cmd/start.go

@@ -55,6 +55,7 @@ func startTasks(args []string) error {
 
 	for _, task := range tasks {
 		task.StartTask()
+		engine.RecordUndo("start", task.UUID)
 		fmt.Printf("Started task: %s\n", task.Description)
 	}
 

opal-task/cmd/stop.go

@@ -55,6 +55,7 @@ func stopTasks(args []string) error {
 
 	for _, task := range tasks {
 		task.StopTask()
+		engine.RecordUndo("stop", task.UUID)
 		fmt.Printf("Stopped task: %s\n", task.Description)
 	}
 

opal-task/cmd/undo.go

@@ -0,0 +1,28 @@
+package cmd
+
+import (
+	"fmt"
+	"os"
+
+	"git.jnss.me/joakim/opal/internal/engine"
+	"github.com/spf13/cobra"
+)
+
+var undoCmd = &cobra.Command{
+	Use:   "undo",
+	Short: "Undo the last action",
+	Long: `Undo the most recent mutating action (add, done, delete, modify, start, stop).
+
+The undo stack keeps the last 10 operations. Each undo pops one operation.
+
+Examples:
+  opal undo`,
+	Run: func(cmd *cobra.Command, args []string) {
+		description, err := engine.PopUndo()
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+			os.Exit(1)
+		}
+		fmt.Println(description)
+	},
+}

opal-task/internal/engine/annotate.go

@@ -0,0 +1,27 @@
+package engine
+
+import "fmt"
+
+// Annotate appends a timestamped annotation to the task and saves.
+func (t *Task) Annotate(text string) error {
+	annotation := Annotation{
+		Timestamp: timeNow().Unix(),
+		Text:      text,
+	}
+	t.Annotations = append(t.Annotations, annotation)
+	return t.Save()
+}
+
+// Denotate removes the most recent annotation from the task and saves.
+// Returns the removed annotation, or an error if there are none.
+func (t *Task) Denotate() (*Annotation, error) {
+	if len(t.Annotations) == 0 {
+		return nil, fmt.Errorf("task has no annotations")
+	}
+	removed := t.Annotations[len(t.Annotations)-1]
+	t.Annotations = t.Annotations[:len(t.Annotations)-1]
+	if err := t.Save(); err != nil {
+		return nil, err
+	}
+	return &removed, nil
+}

opal-task/internal/engine/database.go

@@ -112,6 +112,7 @@ func runMigrations() error {
 					
 					recurrence_duration INTEGER,
 					parent_uuid TEXT,
+					annotations TEXT DEFAULT NULL,
 
 					FOREIGN KEY (parent_uuid) REFERENCES tasks(uuid) ON DELETE CASCADE
 				);
@@ -209,6 +210,15 @@ func runMigrations() error {
 				CREATE INDEX idx_refresh_tokens_hash ON refresh_tokens(token_hash);
 				CREATE INDEX idx_refresh_tokens_user ON refresh_tokens(user_id);
 
+				-- Undo stack (local-only, references change_log entries)
+				CREATE TABLE undo_stack (
+					id              INTEGER PRIMARY KEY AUTOINCREMENT,
+					created_at      INTEGER NOT NULL,
+					op_type         TEXT NOT NULL,
+					task_uuid       TEXT NOT NULL,
+					change_log_id   INTEGER NOT NULL
+				);
+
 				-- Triggers to populate change_log
 				CREATE TRIGGER track_task_create AFTER INSERT ON tasks
 				BEGIN
@@ -241,6 +251,7 @@ func runMigrations() error {
 						CASE WHEN NEW.until_date IS NOT NULL THEN 'until: ' || NEW.until_date || CHAR(10) ELSE '' END ||
 						CASE WHEN NEW.recurrence_duration IS NOT NULL THEN 'recurrence: ' || NEW.recurrence_duration || CHAR(10) ELSE '' END ||
 						CASE WHEN NEW.parent_uuid IS NOT NULL THEN 'parent_uuid: ' || NEW.parent_uuid || CHAR(10) ELSE '' END ||
+						CASE WHEN NEW.annotations IS NOT NULL THEN 'annotations: ' || NEW.annotations || CHAR(10) ELSE '' END ||
 						(SELECT CASE WHEN COUNT(*) > 0
 							THEN 'tags: ' || GROUP_CONCAT(tag, ',') || CHAR(10)
 							ELSE ''
@@ -280,6 +291,7 @@ func runMigrations() error {
 						CASE WHEN NEW.until_date IS NOT NULL THEN 'until: ' || NEW.until_date || CHAR(10) ELSE '' END ||
 						CASE WHEN NEW.recurrence_duration IS NOT NULL THEN 'recurrence: ' || NEW.recurrence_duration || CHAR(10) ELSE '' END ||
 						CASE WHEN NEW.parent_uuid IS NOT NULL THEN 'parent_uuid: ' || NEW.parent_uuid || CHAR(10) ELSE '' END ||
+						CASE WHEN NEW.annotations IS NOT NULL THEN 'annotations: ' || NEW.annotations || CHAR(10) ELSE '' END ||
 						(SELECT CASE WHEN COUNT(*) > 0
 							THEN 'tags: ' || GROUP_CONCAT(tag, ',') || CHAR(10)
 							ELSE ''

opal-task/internal/engine/display.go

@@ -175,6 +175,18 @@ func FormatTaskDetail(task *Task) string {
 		t.AppendRow(table.Row{"Tags", formatTags(task.Tags)})
 	}
 
+	if len(task.Annotations) > 0 {
+		t.AppendSeparator()
+		for i, ann := range task.Annotations {
+			label := ""
+			if i == 0 {
+				label = "Annotations"
+			}
+			ts := time.Unix(ann.Timestamp, 0).Format("2006-01-02 15:04")
+			t.AppendRow(table.Row{label, fmt.Sprintf("%s  %s", ts, ann.Text)})
+		}
+	}
+
 	return t.Render()
 }
 

opal-task/internal/engine/task.go

@@ -44,6 +44,12 @@ const (
 	PriorityHigh    Priority = 3
 )
 
+// Annotation represents a timestamped note on a task
+type Annotation struct {
+	Timestamp int64  `json:"timestamp"`
+	Text      string `json:"text"`
+}
+
 type Task struct {
 	// Identity
 	UUID uuid.UUID `json:"uuid"`
@@ -69,6 +75,9 @@ type Task struct {
 	RecurrenceDuration *time.Duration `json:"recurrence_duration,omitempty"`
 	ParentUUID         *uuid.UUID     `json:"parent_uuid,omitempty"`
 
+	// Annotations (stored as JSON in DB)
+	Annotations []Annotation `json:"annotations,omitempty"`
+
 	// Derived fields (not stored in DB)
 	Tags    []string `json:"tags"`
 	Urgency float64  `json:"urgency"`
@@ -93,6 +102,7 @@ func (t Task) MarshalJSON() ([]byte, error) {
 		Until              *int64       `json:"until,omitempty"`
 		RecurrenceDuration *int64       `json:"recurrence_duration,omitempty"`
 		ParentUUID         *uuid.UUID   `json:"parent_uuid,omitempty"`
+		Annotations        []Annotation `json:"annotations,omitempty"`
 		Tags               []string     `json:"tags"`
 		Urgency            float64      `json:"urgency"`
 	}
@@ -128,6 +138,7 @@ func (t Task) MarshalJSON() ([]byte, error) {
 		Until:              toUnix(t.Until),
 		RecurrenceDuration: recurDur,
 		ParentUUID:         t.ParentUUID,
+		Annotations:        t.Annotations,
 		Tags:               t.Tags,
 		Urgency:            t.Urgency,
 	})
@@ -152,6 +163,7 @@ func (t *Task) UnmarshalJSON(data []byte) error {
 		Until              *int64       `json:"until,omitempty"`
 		RecurrenceDuration *int64       `json:"recurrence_duration,omitempty"`
 		ParentUUID         *uuid.UUID   `json:"parent_uuid,omitempty"`
+		Annotations        []Annotation `json:"annotations,omitempty"`
 		Tags               []string     `json:"tags"`
 		Urgency            float64      `json:"urgency"`
 	}
@@ -184,6 +196,7 @@ func (t *Task) UnmarshalJSON(data []byte) error {
 	t.Wait = fromUnix(raw.Wait)
 	t.Until = fromUnix(raw.Until)
 	t.ParentUUID = raw.ParentUUID
+	t.Annotations = raw.Annotations
 	t.Tags = raw.Tags
 	t.Urgency = raw.Urgency
 
@@ -263,6 +276,32 @@ func uuidPtrToSQL(u *uuid.UUID) interface{} {
 	return u.String()
 }
 
+func annotationsToSQL(annotations []Annotation) interface{} {
+	if len(annotations) == 0 {
+		return nil
+	}
+	data, err := json.Marshal(annotations)
+	if err != nil {
+		return nil
+	}
+	return string(data)
+}
+
+func sqlToAnnotations(v interface{}) []Annotation {
+	if v == nil {
+		return nil
+	}
+	str, ok := v.(string)
+	if !ok {
+		return nil
+	}
+	var annotations []Annotation
+	if err := json.Unmarshal([]byte(str), &annotations); err != nil {
+		return nil
+	}
+	return annotations
+}
+
 func sqlToUUIDPtr(v interface{}) *uuid.UUID {
 	if v == nil {
 		return nil
@@ -337,7 +376,7 @@ func GetTask(taskUUID uuid.UUID) (*Task, error) {
 	query := `
 		SELECT id, uuid, status, description, project, priority,
 		       created, modified, start, end, due, scheduled, wait, until_date,
-		       recurrence_duration, parent_uuid
+		       recurrence_duration, parent_uuid, annotations
 		FROM tasks
 		WHERE uuid = ?
 	`
@@ -356,6 +395,7 @@ func GetTask(taskUUID uuid.UUID) (*Task, error) {
 		until          interface{}
 		recurDuration  interface{}
 		parentUUIDStr  interface{}
+		annotationsStr interface{}
 	)
 
 	err := db.QueryRow(query, taskUUID.String()).Scan(
@@ -375,6 +415,7 @@ func GetTask(taskUUID uuid.UUID) (*Task, error) {
 		&until,
 		&recurDuration,
 		&parentUUIDStr,
+		&annotationsStr,
 	)
 
 	if err != nil {
@@ -401,6 +442,7 @@ func GetTask(taskUUID uuid.UUID) (*Task, error) {
 	task.Until = sqlToTime(until)
 	task.RecurrenceDuration = sqlToDuration(recurDuration)
 	task.ParentUUID = sqlToUUIDPtr(parentUUIDStr)
+	task.Annotations = sqlToAnnotations(annotationsStr)
 
 	// Load tags
 	tags, err := task.GetTags()
@@ -429,7 +471,7 @@ func GetTasks(filter *Filter) ([]*Task, error) {
 	query := fmt.Sprintf(`
 		SELECT id, uuid, status, description, project, priority,
 		       created, modified, start, end, due, scheduled, wait, until_date,
-		       recurrence_duration, parent_uuid
+		       recurrence_duration, parent_uuid, annotations
 		FROM tasks
 		WHERE %s
 		ORDER BY
@@ -461,6 +503,7 @@ func GetTasks(filter *Filter) ([]*Task, error) {
 			until          interface{}
 			recurDuration  interface{}
 			parentUUIDStr  interface{}
+			annotationsStr interface{}
 		)
 
 		err := rows.Scan(
@@ -480,6 +523,7 @@ func GetTasks(filter *Filter) ([]*Task, error) {
 			&until,
 			&recurDuration,
 			&parentUUIDStr,
+			&annotationsStr,
 		)
 
 		if err != nil {
@@ -506,6 +550,7 @@ func GetTasks(filter *Filter) ([]*Task, error) {
 		task.Until = sqlToTime(until)
 		task.RecurrenceDuration = sqlToDuration(recurDuration)
 		task.ParentUUID = sqlToUUIDPtr(parentUUIDStr)
+		task.Annotations = sqlToAnnotations(annotationsStr)
 
 		// Load tags
 		tags, err := task.GetTags()
@@ -543,7 +588,7 @@ func (t *Task) Save() error {
 				status = ?, description = ?, project = ?, priority = ?,
 				modified = ?, start = ?, end = ?, due = ?,
 				scheduled = ?, wait = ?, until_date = ?,
-				recurrence_duration = ?, parent_uuid = ?
+				recurrence_duration = ?, parent_uuid = ?, annotations = ?
 			WHERE uuid = ?
 		`
 
@@ -561,6 +606,7 @@ func (t *Task) Save() error {
 			timeToSQL(t.Until),
 			durationToSQL(t.RecurrenceDuration),
 			uuidPtrToSQL(t.ParentUUID),
+			annotationsToSQL(t.Annotations),
 			t.UUID.String(),
 		)
 
@@ -573,8 +619,8 @@ func (t *Task) Save() error {
 			INSERT INTO tasks (
 				uuid, status, description, project, priority,
 				created, modified, start, end, due, scheduled, wait, until_date,
-				recurrence_duration, parent_uuid
+				recurrence_duration, parent_uuid, annotations
-			) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+			) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
 		`
 
 		result, err := db.Exec(query,
@@ -593,6 +639,7 @@ func (t *Task) Save() error {
 			timeToSQL(t.Until),
 			durationToSQL(t.RecurrenceDuration),
 			uuidPtrToSQL(t.ParentUUID),
+			annotationsToSQL(t.Annotations),
 		)
 
 		if err != nil {

opal-task/internal/engine/undo.go

@@ -0,0 +1,347 @@
+package engine
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/google/uuid"
+)
+
+const undoStackLimit = 10
+
+// RecordUndo records a CLI operation as undoable.
+// Called AFTER the mutation so the change_log entry exists.
+func RecordUndo(opType string, taskUUID uuid.UUID) error {
+	db := GetDB()
+	if db == nil {
+		return fmt.Errorf("database not initialized")
+	}
+
+	// Find the change_log entry just created by this mutation
+	var changeLogID int64
+	err := db.QueryRow(
+		"SELECT MAX(id) FROM change_log WHERE task_uuid = ?",
+		taskUUID.String(),
+	).Scan(&changeLogID)
+	if err != nil {
+		return fmt.Errorf("failed to find change_log entry: %w", err)
+	}
+
+	// Insert into undo_stack
+	_, err = db.Exec(
+		"INSERT INTO undo_stack (created_at, op_type, task_uuid, change_log_id) VALUES (?, ?, ?, ?)",
+		timeNow().Unix(), opType, taskUUID.String(), changeLogID,
+	)
+	if err != nil {
+		return fmt.Errorf("failed to record undo: %w", err)
+	}
+
+	// Evict old entries beyond the limit
+	_, err = db.Exec(
+		"DELETE FROM undo_stack WHERE id NOT IN (SELECT id FROM undo_stack ORDER BY id DESC LIMIT ?)",
+		undoStackLimit,
+	)
+	if err != nil {
+		return fmt.Errorf("failed to evict old undo entries: %w", err)
+	}
+
+	return nil
+}
+
+// PopUndo pops the most recent undo entry and reverts the task.
+// Returns a description of what was undone.
+func PopUndo() (string, error) {
+	db := GetDB()
+	if db == nil {
+		return "", fmt.Errorf("database not initialized")
+	}
+
+	// Get the most recent undo entry
+	var (
+		undoID      int64
+		opType      string
+		taskUUIDStr string
+		changeLogID int64
+	)
+	err := db.QueryRow(
+		"SELECT id, op_type, task_uuid, change_log_id FROM undo_stack ORDER BY id DESC LIMIT 1",
+	).Scan(&undoID, &opType, &taskUUIDStr, &changeLogID)
+	if err != nil {
+		return "", fmt.Errorf("nothing to undo")
+	}
+
+	taskUUID, err := uuid.Parse(taskUUIDStr)
+	if err != nil {
+		return "", fmt.Errorf("invalid task UUID in undo stack: %w", err)
+	}
+
+	// Remove the entry from the stack
+	_, err = db.Exec("DELETE FROM undo_stack WHERE id = ?", undoID)
+	if err != nil {
+		return "", fmt.Errorf("failed to pop undo entry: %w", err)
+	}
+
+	// Perform the revert based on op type
+	switch opType {
+	case "add":
+		return undoAdd(taskUUID)
+	case "done", "delete", "modify", "start", "stop":
+		return undoRestore(opType, taskUUID, changeLogID)
+	default:
+		return "", fmt.Errorf("unknown undo operation: %s", opType)
+	}
+}
+
+// undoAdd reverts an add by hard-deleting the task.
+// For recurring tasks, also deletes the template.
+func undoAdd(taskUUID uuid.UUID) (string, error) {
+	db := GetDB()
+
+	task, err := GetTask(taskUUID)
+	if err != nil {
+		return "", fmt.Errorf("failed to load task for undo: %w", err)
+	}
+
+	desc := task.Description
+
+	// If this is a recurring instance, also delete the template
+	if task.ParentUUID != nil {
+		_, err = db.Exec("DELETE FROM tasks WHERE uuid = ?", task.ParentUUID.String())
+		if err != nil {
+			return "", fmt.Errorf("failed to delete recurring template: %w", err)
+		}
+	}
+
+	// Hard delete the task
+	_, err = db.Exec("DELETE FROM tasks WHERE uuid = ?", taskUUID.String())
+	if err != nil {
+		return "", fmt.Errorf("failed to delete task: %w", err)
+	}
+
+	return fmt.Sprintf("Undid add: removed \"%s\"", desc), nil
+}
+
+// undoRestore reverts a mutation by restoring the prior state from change_log.
+func undoRestore(opType string, taskUUID uuid.UUID, changeLogID int64) (string, error) {
+	db := GetDB()
+
+	// Find the change_log entry BEFORE this one for the same task
+	var priorData string
+	err := db.QueryRow(
+		"SELECT data FROM change_log WHERE task_uuid = ? AND id < ? ORDER BY id DESC LIMIT 1",
+		taskUUID.String(), changeLogID,
+	).Scan(&priorData)
+	if err != nil {
+		return "", fmt.Errorf("no prior state found in change_log (cannot undo)")
+	}
+
+	// Parse the prior state
+	task, err := GetTask(taskUUID)
+	if err != nil {
+		return "", fmt.Errorf("failed to load task: %w", err)
+	}
+
+	// Apply the prior state from change_log data
+	if err := applyChangeLogData(task, priorData); err != nil {
+		return "", fmt.Errorf("failed to restore prior state: %w", err)
+	}
+
+	// Save the restored task
+	if err := task.Save(); err != nil {
+		return "", fmt.Errorf("failed to save restored task: %w", err)
+	}
+
+	// Reconcile tags
+	if err := reconcileTagsFromChangeLog(task, priorData); err != nil {
+		return "", fmt.Errorf("failed to reconcile tags: %w", err)
+	}
+
+	return fmt.Sprintf("Undid %s: restored \"%s\"", opType, task.Description), nil
+}
+
+// applyChangeLogData parses change_log data and applies it to a task.
+// The data format is "key: value\n" lines (same format used by sync).
+func applyChangeLogData(task *Task, data string) error {
+	lines := strings.Split(data, "\n")
+	for _, line := range lines {
+		line = strings.TrimSpace(line)
+		if line == "" {
+			continue
+		}
+
+		parts := strings.SplitN(line, ": ", 2)
+		if len(parts) != 2 {
+			continue
+		}
+
+		key := parts[0]
+		value := parts[1]
+
+		switch key {
+		case "description":
+			task.Description = value
+		case "status":
+			switch value {
+			case "pending":
+				task.Status = StatusPending
+			case "completed":
+				task.Status = StatusCompleted
+			case "deleted":
+				task.Status = StatusDeleted
+			case "recurring":
+				task.Status = StatusRecurring
+			}
+		case "priority":
+			switch value {
+			case "H":
+				task.Priority = PriorityHigh
+			case "M":
+				task.Priority = PriorityMedium
+			case "L":
+				task.Priority = PriorityLow
+			default:
+				task.Priority = PriorityDefault
+			}
+		case "project":
+			task.Project = &value
+		case "created":
+			if ts, err := strconv.ParseInt(value, 10, 64); err == nil {
+				task.Created = time.Unix(ts, 0)
+			}
+		case "modified":
+			// Don't restore modified — it'll be set by Save()
+		case "start":
+			if ts, err := strconv.ParseInt(value, 10, 64); err == nil {
+				t := time.Unix(ts, 0)
+				task.Start = &t
+			}
+		case "end":
+			if ts, err := strconv.ParseInt(value, 10, 64); err == nil {
+				t := time.Unix(ts, 0)
+				task.End = &t
+			}
+		case "due":
+			if ts, err := strconv.ParseInt(value, 10, 64); err == nil {
+				t := time.Unix(ts, 0)
+				task.Due = &t
+			}
+		case "scheduled":
+			if ts, err := strconv.ParseInt(value, 10, 64); err == nil {
+				t := time.Unix(ts, 0)
+				task.Scheduled = &t
+			}
+		case "wait":
+			if ts, err := strconv.ParseInt(value, 10, 64); err == nil {
+				t := time.Unix(ts, 0)
+				task.Wait = &t
+			}
+		case "until":
+			if ts, err := strconv.ParseInt(value, 10, 64); err == nil {
+				t := time.Unix(ts, 0)
+				task.Until = &t
+			}
+		case "recurrence":
+			if ns, err := strconv.ParseInt(value, 10, 64); err == nil {
+				d := time.Duration(ns)
+				task.RecurrenceDuration = &d
+			}
+		case "parent_uuid":
+			if u, err := uuid.Parse(value); err == nil {
+				task.ParentUUID = &u
+			}
+		case "annotations":
+			// Annotations are stored as JSON in the change_log
+			task.Annotations = sqlToAnnotations(value)
+		case "tags":
+			// Tags are handled separately by reconcileTagsFromChangeLog
+		}
+	}
+
+	// Clear fields that aren't present in the change_log data (they were NULL)
+	fieldPresent := make(map[string]bool)
+	for _, line := range lines {
+		parts := strings.SplitN(strings.TrimSpace(line), ": ", 2)
+		if len(parts) == 2 {
+			fieldPresent[parts[0]] = true
+		}
+	}
+	if !fieldPresent["project"] {
+		task.Project = nil
+	}
+	if !fieldPresent["start"] {
+		task.Start = nil
+	}
+	if !fieldPresent["end"] {
+		task.End = nil
+	}
+	if !fieldPresent["due"] {
+		task.Due = nil
+	}
+	if !fieldPresent["scheduled"] {
+		task.Scheduled = nil
+	}
+	if !fieldPresent["wait"] {
+		task.Wait = nil
+	}
+	if !fieldPresent["until"] {
+		task.Until = nil
+	}
+	if !fieldPresent["recurrence"] {
+		task.RecurrenceDuration = nil
+	}
+	if !fieldPresent["parent_uuid"] {
+		task.ParentUUID = nil
+	}
+	if !fieldPresent["annotations"] {
+		task.Annotations = nil
+	}
+
+	return nil
+}
+
+// reconcileTagsFromChangeLog restores tags from change_log data.
+func reconcileTagsFromChangeLog(task *Task, data string) error {
+	// Parse desired tags from change_log
+	var desiredTags []string
+	for _, line := range strings.Split(data, "\n") {
+		line = strings.TrimSpace(line)
+		if strings.HasPrefix(line, "tags: ") {
+			tagStr := strings.TrimPrefix(line, "tags: ")
+			for _, tag := range strings.Split(tagStr, ",") {
+				tag = strings.TrimSpace(tag)
+				if tag != "" {
+					desiredTags = append(desiredTags, tag)
+				}
+			}
+		}
+	}
+
+	// Get current tags
+	currentTags, _ := task.GetTags()
+
+	// Remove tags not in desired set
+	desired := make(map[string]bool)
+	for _, t := range desiredTags {
+		desired[t] = true
+	}
+	for _, tag := range currentTags {
+		if !desired[tag] {
+			task.RemoveTag(tag)
+		}
+	}
+
+	// Add missing tags
+	current := make(map[string]bool)
+	for _, t := range currentTags {
+		current[t] = true
+	}
+	for _, tag := range desiredTags {
+		if !current[tag] {
+			task.AddTag(tag)
+		}
+	}
+
+	return nil
+}