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)
@@ -45,8 +45,9 @@ var reportNames = []string{
 }
 
 var commandsWithModifiers = map[string]bool{
-	"add":    true,
-	"modify": true,
+	"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)
+	},
+}