savepoint 1.0.2 → 1.0.4

package/.savepoint/releases/v1.1/epics/E08-board-command/E08-Audit.md

@@ -0,0 +1,333 @@
+---
+type: audit-findings
+audited: 2026-05-03
+---
+# Audit Findings: E08 Board Command
+
+## Main Findings
+
+E08 is closed as audited. The board command surface, non-TTY fallback, Bubble Tea shell, model grouping, detail overlay, keyboard navigation, status writes, filters, theme profile detection, and integration coverage are in place.
+
+The two audit blockers were applied: board task writes now surface mtime conflicts instead of overwriting externally modified task files, and dependency gating now blocks planned tasks from entering `in_progress` until dependencies are done.
+
+Documentation reconciliation was applied to Design.md, AGENTS.md, and the E08 epic detail. Remaining process note: all eight E08 task files were missing the required `## Context Files` section; that was not backfilled because it is a task-authoring process gap rather than an implementation blocker.
+
+## Code Style Review
+
+- [x] One job per file
+- [x] One-sentence functions
+- [x] Test branches
+- [x] Types are documentation
+- [x] Build, don't speculate
+- [x] Errors at boundaries
+- [x] One source of truth
+- [x] Comments explain WHY
+- [x] Content in data files
+- [x] Small diffs
+
+Notes: The applied changes remove the speculative mtime overwrite and add branch coverage for planned-task dependency gating. The broader reducer size remains a known shape of `internal/board/update.go`, but the E08 audit blockers are resolved.
+
+## Proposed Changes
+
+### Target File
+internal/board/update.go
+
+### Replace
+```go
+func writeTaskStatus(task *data.Task, expectedMtime time.Time) error {
+	if err := data.WriteTaskStatus(task.Path, task, expectedMtime); err != nil {
+		if err != data.ErrMtimeConflict {
+			return err
+		}
+		fi, statErr := os.Stat(task.Path)
+		if statErr != nil {
+			return statErr
+		}
+		if retryErr := data.WriteTaskStatus(task.Path, task, fi.ModTime()); retryErr != nil {
+			return retryErr
+		}
+	}
+	fi, err := os.Stat(task.Path)
+	if err != nil {
+		return err
+	}
+	task.Mtime = fi.ModTime()
+	return nil
+}
+```
+
+### With
+```go
+func writeTaskStatus(task *data.Task, expectedMtime time.Time) error {
+	if err := data.WriteTaskStatus(task.Path, task, expectedMtime); err != nil {
+		return err
+	}
+	fi, err := os.Stat(task.Path)
+	if err != nil {
+		return err
+	}
+	task.Mtime = fi.ModTime()
+	return nil
+}
+```
+
+### Target File
+internal/board/integration_test.go
+
+### Replace
+```go
+// TestMtimeConflict_boardRetries verifies the board retries after an mtime conflict and persists the transition.
+func TestMtimeConflict_boardRetries(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "T001.md")
+	content := "---\nid: E01/T001\nstatus: in_progress\nphase: build\n---\n\n# Task\n"
+	if err := os.WriteFile(path, []byte(content), 0644); err != nil {
+		t.Fatal(err)
+	}
+	fi, err := os.Stat(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	task := data.Task{
+		ID:     "E01/T001",
+		Column: data.ColumnInProgress,
+		Stage:  data.StageBuild,
+		Path:   path,
+		Mtime:  fi.ModTime().Add(-time.Minute), // intentionally stale
+	}
+	m := NewModel([]data.Task{task}, "v1", "E01")
+	m.FocusedColumn = data.ColumnInProgress
+
+	got, _ := m.Update(tea.KeyMsg{Type: tea.KeySpace})
+	updated := requireModel(t, got)
+
+	if updated.AllTasks[0].Stage != data.StageTest {
+		t.Errorf("Stage = %q after retry, want test", updated.AllTasks[0].Stage)
+	}
+	if strings.Contains(updated.StatusMessage, "conflict") {
+		t.Errorf("conflict error surfaced to user unexpectedly: %q", updated.StatusMessage)
+	}
+}
+```
+
+### With
+```go
+// TestMtimeConflict_boardWarns verifies the board surfaces an mtime conflict instead of overwriting external edits.
+func TestMtimeConflict_boardWarns(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "T001.md")
+	content := "---\nid: E01/T001\nstatus: in_progress\nphase: build\n---\n\n# Task\n"
+	if err := os.WriteFile(path, []byte(content), 0644); err != nil {
+		t.Fatal(err)
+	}
+	fi, err := os.Stat(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	task := data.Task{
+		ID:     "E01/T001",
+		Column: data.ColumnInProgress,
+		Stage:  data.StageBuild,
+		Path:   path,
+		Mtime:  fi.ModTime().Add(-time.Minute), // intentionally stale
+	}
+	m := NewModel([]data.Task{task}, "v1", "E01")
+	m.FocusedColumn = data.ColumnInProgress
+
+	got, _ := m.Update(tea.KeyMsg{Type: tea.KeySpace})
+	updated := requireModel(t, got)
+
+	if !strings.Contains(updated.StatusMessage, "mtime conflict") {
+		t.Errorf("StatusMessage = %q, want mtime conflict warning", updated.StatusMessage)
+	}
+
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(raw), "phase: build") {
+		t.Errorf("task file was overwritten despite mtime conflict:\n%s", raw)
+	}
+}
+```
+
+### Target File
+internal/board/transitions.go
+
+### Replace
+```go
+	case data.ColumnPlanned:
+		return true, ""
+	case data.ColumnInProgress:
+```
+
+### With
+```go
+	case data.ColumnPlanned:
+		return dependenciesDone(t, allTasks)
+	case data.ColumnInProgress:
+```
+
+### Target File
+internal/board/transitions.go
+
+### Replace
+```go
+		switch stage {
+		case data.StageBuild:
+			return true, ""
+		case data.StageTest:
+			return true, ""
+		case data.StageAudit:
+			for _, depID := range t.DependsOn {
+				dep := findTask(depID, allTasks)
+				if dep == nil {
+					return false, fmt.Sprintf("dependency %q not found", depID)
+				}
+				if dep.Column != data.ColumnDone {
+					return false, fmt.Sprintf("dependency %q is not done", depID)
+				}
+			}
+			return true, ""
+		default:
+```
+
+### With
+```go
+		switch stage {
+		case data.StageBuild:
+			return true, ""
+		case data.StageTest:
+			return true, ""
+		case data.StageAudit:
+			return dependenciesDone(t, allTasks)
+		default:
+```
+
+### Target File
+internal/board/transitions.go
+
+### Replace
+```go
+func findTask(id string, tasks []data.Task) *data.Task {
+	for i := range tasks {
+		if tasks[i].ID == id {
+			return &tasks[i]
+		}
+	}
+	return nil
+}
+```
+
+### With
+```go
+func dependenciesDone(t *data.Task, allTasks []data.Task) (bool, string) {
+	for _, depID := range t.DependsOn {
+		dep := findTask(depID, allTasks)
+		if dep == nil {
+			return false, fmt.Sprintf("dependency %q not found", depID)
+		}
+		if dep.Column != data.ColumnDone {
+			return false, fmt.Sprintf("dependency %q is not done", depID)
+		}
+	}
+	return true, ""
+}
+
+func findTask(id string, tasks []data.Task) *data.Task {
+	for i := range tasks {
+		if tasks[i].ID == id {
+			return &tasks[i]
+		}
+	}
+	return nil
+}
+```
+
+### Target File
+internal/board/transitions_test.go
+
+### Replace
+```go
+func TestCanAdvance_plannedAlwaysAllowed(t *testing.T) {
+	task := data.Task{Column: data.ColumnPlanned}
+	ok, reason := CanAdvance(&task, nil)
+	if !ok {
+		t.Errorf("CanAdvance(planned) = false %q, want true", reason)
+	}
+}
+```
+
+### With
+```go
+func TestCanAdvance_plannedAllowedWhenDependenciesDone(t *testing.T) {
+	allTasks := []data.Task{
+		{ID: "T1", Column: data.ColumnPlanned, DependsOn: []string{"T2"}},
+		{ID: "T2", Column: data.ColumnDone},
+	}
+	ok, reason := CanAdvance(&allTasks[0], allTasks)
+	if !ok {
+		t.Errorf("CanAdvance(planned with done dep) = false %q, want true", reason)
+	}
+}
+
+func TestCanAdvance_plannedBlockedByDependency(t *testing.T) {
+	allTasks := []data.Task{
+		{ID: "T1", Column: data.ColumnPlanned, DependsOn: []string{"T2"}},
+		{ID: "T2", Column: data.ColumnInProgress},
+	}
+	ok, reason := CanAdvance(&allTasks[0], allTasks)
+	if ok {
+		t.Fatal("CanAdvance(planned with unfinished dep) = true, want false")
+	}
+	if reason != "dependency \"T2\" is not done" {
+		t.Errorf("reason = %q, want dependency warning", reason)
+	}
+}
+```
+
+### Target File
+AGENTS.md
+
+### Replace
+```md
+| `cmd/` | Init command arg parsing, dispatch |
+```
+
+### With
+```md
+| `cmd/` | CLI command arg parsing and dispatch for init and board |
+```
+
+### Target File
+.savepoint/releases/v1.1/epics/E08-board-command/E08-Detail.md
+
+### Replace
+```md
+## Boundaries
+```
+
+### With
+```md
+## Implemented As
+
+- `main.go` dispatches `board` and uses the no-arg command path as the board default.
+- `cmd/board.go` owns board-specific flag parsing for `--release`, `--epic`, and `--help`.
+- `internal/board/board.go`, `tui.go`, `model.go`, `plain.go`, `transitions.go`, and related render/update files own project discovery, non-TTY fallback, TUI startup, filtering, detail overlays, keyboard flow, and task status writes.
+- Audit entry-point work is represented as the non-TTY audit proposal signal and the epic Detail/Audit tab flow added around E06.
+
+## Boundaries
+```
+
+### Target File
+.savepoint/Design.md
+
+### Replace
+```md
+- **Board command** (`savepoint board`) reads project state, renders the Atari-Noir TUI board, supports release/epic filtering, detail overlays, task status transitions with mtime-guarded writes, release/epic-scoped router priority markers, fsnotify-based task auto-refresh (epic E06), header Next Activity display, height-aware column/detail viewport scrolling, stable focused/unfocused column border geometry (v1.1 E01), dedicated phase-colored Next Activity line below the header, sentence-boundary checklist rendering in task details, shared status glyph mapping for task cards and the epic sidebar, a forced ANSI256 Lipgloss color profile for board startup (v1.1 E03), a focusable wide-screen epic sidebar with purple epic focus, epic detail overlays, and status glyphs loaded from epic detail frontmatter (v1.1 E04), and an epic Detail/Audit tab switch that renders user-facing audit findings from `{epic}/E##-Audit.md` (v1.1 E06).
+```
+
+### With
+```md
+- **Board command** (`savepoint board`, and bare `savepoint`) reads project state, renders the Atari-Noir TUI board when stdout is a TTY, falls back to a deterministic plain table in non-TTY mode, supports `--release`/`--epic` filtering, detail overlays, task status transitions with mtime-guarded writes, release/epic-scoped router priority markers, fsnotify-based task auto-refresh (epic E06), header Next Activity display, height-aware column/detail viewport scrolling, stable focused/unfocused column border geometry (v1.1 E01), dedicated phase-colored Next Activity line below the header, sentence-boundary checklist rendering in task details, shared status glyph mapping for task cards and the epic sidebar, a forced ANSI256 Lipgloss color profile for board startup (v1.1 E03), a focusable wide-screen epic sidebar with purple epic focus, epic detail overlays, and status glyphs loaded from epic detail frontmatter (v1.1 E04), and an epic Detail/Audit tab switch that renders user-facing audit findings from `{epic}/E##-Audit.md` (v1.1 E06).
+```

package/.savepoint/releases/v1.1/epics/E08-board-command/E08-Detail.md

@@ -0,0 +1,68 @@
+---
+type: epic-design
+status: audited
+---
+
+# E08: Board Command
+
+## Purpose
+
+Implement `savepoint board`, a Bubble Tea terminal UI for viewing and moving tasks through the Savepoint workflow, including audit-review mode entry points.
+
+## Interface
+
+```bash
+savepoint board              # launch TUI
+savepoint                    # alias for board
+savepoint board --release v1 # filter by release
+savepoint board --epic E03   # filter by epic
+```
+
+## What this epic adds
+
+- Ink/Bubble Tea app shell launched by `savepoint board`
+- Three-column Kanban view for planned, in_progress, done
+- Detail pane for selected task
+- Keyboard navigation (arrows, vim-style j/k/h/l)
+- Status transition actions with gate enforcement
+- Manual refresh with `r` key
+- Theme tokens loaded from config.yml
+- Render fallbacks: 24-bit → 256-color → 16-color → NO_COLOR → non-TTY plain table
+- Optimistic mtime conflict detection before writes
+- Audit entry point: signal if proposals exist, exit toward audit
+
+## Components
+
+| Module | Purpose |
+|--------|---------|
+| `cmd/board.go` | CLI registration, arg parsing |
+| `internal/board/cmd.go` | Non-TTY fallback, dispatch |
+| `internal/board/tui.go` | Bubble Tea program setup |
+| `internal/board/model.go` | Board state, columns, cards |
+| `internal/board/detail.go` | Task detail pane |
+| `internal/board/transitions.go` | Status transition gate enforcement |
+| `internal/board/theme.go` | Theme loading, color fallbacks |
+| `internal/board/plain.go` | Non-TTY plain text table |
+
+## Implemented As
+
+- `main.go` dispatches `board` and uses the no-arg command path as the board default.
+- `cmd/board.go` owns board-specific flag parsing for `--release`, `--epic`, and `--help`.
+- `internal/board/board.go`, `tui.go`, `model.go`, `plain.go`, `transitions.go`, and related render/update files own project discovery, non-TTY fallback, TUI startup, filtering, detail overlays, keyboard flow, and task status writes.
+- Audit entry-point work is represented as the non-TTY audit proposal signal and the epic Detail/Audit tab flow added around E06.
+
+## Boundaries
+
+**In scope:**
+- Board navigation and status transitions
+- Gate enforcement for dependencies and status rules
+- Plain table fallback when not in a TTY
+- Manual `r` refresh
+- Initial audit-review mode entry point if proposals exist
+
+**Out of scope:**
+- File watching
+- Search
+- Mouse interaction
+- Drag-and-drop
+- Full audit proposal diff implementation

package/.savepoint/releases/v1.1/epics/E08-board-command/tasks/T001-cli-entrypoint.md

@@ -0,0 +1,26 @@
+---
+id: E08-board-command/T001-cli-entrypoint
+status: done
+objective: "Create CLI entrypoint for savepoint board command"
+depends_on: []
+---
+
+# T001: CLI Entrypoint
+
+## Acceptance Criteria
+
+- `savepoint board --help` shows usage: `board [--release <release>] [--epic <epic>]`
+- `savepoint` (no args) defaults to board
+- `savepoint board` launches TUI
+- `savepoint board --release v1` filters by release
+- `savepoint board --epic E03` filters by epic
+
+## Implementation Plan
+
+- [x] Update main.go dispatch to recognize subcommands
+- [x] Add `cmd/board.go` with CLI arg parsing
+- [x] Wire board command into main.go
+- [x] Implement arg validation (--release, --epic)
+- [x] Default to board when no subcommand given
+- [x] Test `savepoint board --help` output
+- [x] Run `make build && make test`

package/.savepoint/releases/v1.1/epics/E08-board-command/tasks/T002-non-tty-fallback.md

@@ -0,0 +1,27 @@
+---
+id: E08-board-command/T002-non-tty-fallback
+status: done
+objective: "Implement non-TTY plain text table output"
+depends_on: ["E08-board-command/T001-cli-entrypoint"]
+---
+
+# T002: Non-TTY Fallback
+
+## Acceptance Criteria
+
+- When not in a TTY, outputs deterministic plain text
+- Shows three columns: planned, in_progress, done
+- Lists task IDs and objectives in each column
+- Includes warning about non-interactive mode
+- Shows audit-entry signal if audit proposals exist
+
+## Implementation Plan
+
+- [x] Add `internal/board/plain.go`
+- [x] Implement `RenderPlainTable(model) string`
+- [x] Check `termenv.IsTerminal()` for TTY detection
+- [x] Format tasks in three columns with headers
+- [x] Add non-interactive warning banner
+- [x] Check for audit proposals, show entry signal
+- [x] Test non-TTY output
+- [x] Run `make build && make test`

package/.savepoint/releases/v1.1/epics/E08-board-command/tasks/T003-tui-app-shell.md

@@ -0,0 +1,28 @@
+---
+id: E08-board-command/T003-tui-app-shell
+status: done
+objective: "Implement Bubble Tea TUI program shell"
+depends_on: ["E08-board-command/T001-cli-entrypoint"]
+---
+
+# T003: TUI App Shell
+
+## Acceptance Criteria
+
+- Launches Bubble Tea program with alt screen
+- Loads theme from config.yml
+- Initializes model with release/epic filters
+- Handles quit (q, ctrl+c) gracefully
+- Handles window resize
+
+## Implementation Plan
+
+- [x] Add `internal/board/tui.go`
+- [x] Implement `RunTUI(release, epic) error`
+- [x] Create tea.Program with board model
+- [x] Enable alt screen mode
+- [x] Load and apply theme from config
+- [x] Handle quit key (q, ctrl+c)
+- [x] Handle window resize events
+- [x] Test TUI launch in terminal
+- [x] Run `make build && make test`

package/.savepoint/releases/v1.1/epics/E08-board-command/tasks/T004-board-model.md

@@ -0,0 +1,29 @@
+---
+id: E08-board-command/T004-board-model
+status: done
+objective: "Implement TUI board model with 3-column Kanban"
+depends_on: ["E08-board-command/T003-tui-app-shell"]
+---
+
+# T004: Board Model
+
+## Acceptance Criteria
+
+- Three columns: planned, in_progress, done
+- Column headers with task count
+- Task cards showing ID and objective
+- Keyboard navigation: arrows, vim-style j/k/h/l
+- Selection highlighting with accent color
+- Filter by release and epic
+
+## Implementation Plan
+
+- [x] Add `internal/board/model.go` (extend existing or create new)
+- [x] Implement column structure (planned, in_progress, done)
+- [x] Implement card rendering (ID + objective truncated)
+- [x] Implement selection state (current column, current card)
+- [x] Handle key events: Up/Down/Left/Right, j/k/h/l
+- [x] Apply theme colors for focus/accent
+- [x] Implement release/epic filtering from args
+- [x] Test board rendering in TUI
+- [x] Run `make build && make test`

package/.savepoint/releases/v1.1/epics/E08-board-command/tasks/T005-detail-pane.md

@@ -0,0 +1,27 @@
+---
+id: E08-board-command/T005-detail-pane
+status: done
+objective: "Implement task detail pane overlay"
+depends_on: ["E08-board-command/T004-board-model"]
+---
+
+# T005: Detail Pane
+
+## Acceptance Criteria
+
+- Enter key shows selected task detail overlay
+- Displays full task content: ID, objective, status, depends_on, AC
+- Keyboard navigation works (escape/enter to close)
+- Overlay renders with theme styling
+- Closes on q or escape
+
+## Implementation Plan
+
+- [x] Add `internal/board/detail.go` (extend existing or create new)
+- [x] Implement detail overlay state
+- [x] Render selected task full content
+- [x] Add enter key handler to show detail
+- [x] Add escape/q handlers to close detail
+- [x] Apply theme styling to overlay
+- [x] Test detail pane interaction
+- [x] Run `make build && make test`

package/.savepoint/releases/v1.1/epics/E08-board-command/tasks/T006-status-transitions.md

@@ -0,0 +1,29 @@
+---
+id: E08-board-command/T006-status-transitions
+status: done
+objective: "Implement status transitions with gate enforcement"
+depends_on: ["E08-board-command/T005-detail-pane"]
+---
+
+# T006: Status Transitions
+
+## Acceptance Criteria
+
+- Space advances: planned → in_progress → done
+- Backspace retreats: done → in_progress → planned
+- Phase gating: can only reach done after audit phase
+- Dependency gating: cannot advance if depends_on not done
+- mtime conflict detection: warn if task modified since load
+- Write status back to task frontmatter
+
+## Implementation Plan
+
+- [x] Add `internal/board/transitions.go` (extend existing or create new)
+- [x] Implement phase advancement (space key)
+- [x] Implement phase retreat (backspace key)
+- [x] Check phase gating (must reach audit phase before done)
+- [x] Check dependency gating (all depends_on status: done)
+- [x] Implement mtime conflict detection before write
+- [x] Write new status to task frontmatter via data.WriteTaskStatus
+- [x] Test transition behavior in TUI
+- [x] Run `make build && make test`

package/.savepoint/releases/v1.1/epics/E08-board-command/tasks/T007-theme-fallbacks.md

@@ -0,0 +1,29 @@
+---
+id: E08-board-command/T007-theme-fallbacks
+status: done
+objective: "Implement theme loading and color fallbacks"
+depends_on: ["E08-board-command/T003-tui-app-shell"]
+---
+
+# T007: Theme Fallbacks
+
+## Acceptance Criteria
+
+- Load theme tokens from config.yml
+- Support truecolor (24-bit) terminals
+- Fall back to 256-color mode if no truecolor
+- Fall back to 16-color if no 256-color
+- Support NO_COLOR=1 for monochrome
+- Apply theme to all UI elements (columns, cards, detail, overlays)
+
+## Implementation Plan
+
+- [x] Add `internal/board/theme.go` (extend existing or create new)
+- [x] Implement theme loading from config.yml
+- [x] Implement truecolor profile detection
+- [x] Implement 256-color fallback mapping
+- [x] Implement 16-color fallback mapping
+- [x] Support NO_COLOR=1 monochrome mode
+- [x] Apply theme to columns, cards, detail, overlays
+- [x] Test on different terminal profiles
+- [x] Run `make build && make test`

package/.savepoint/releases/v1.1/epics/E08-board-command/tasks/T008-integration-test.md

@@ -0,0 +1,27 @@
+---
+id: E08-board-command/T008-integration-test
+status: done
+objective: "End-to-end integration test of board flow"
+depends_on: ["E06-audit-command/T007-apply-close", "E07-init-command/T007-integration-test"]
+---
+
+# T008: Integration Test
+
+## Acceptance Criteria
+
+- Full board pipeline runs end-to-end
+- TUI navigation, transitions, detail pane work
+- Non-TTY fallback outputs correct table
+- Status writes preserve task content
+- Tests pass on Windows, Linux, macOS
+
+## Implementation Plan
+
+- [x] Add `internal/board/integration_test.go`
+- [x] Test: board launches in TTY mode
+- [x] Test: board falls back to plain table in non-TTY
+- [x] Test: keyboard navigation (arrows, vim keys)
+- [x] Test: status transitions preserve content
+- [x] Test: mtime conflict detection works
+- [x] Test: release/epic filters work
+- [x] Run full test suite: `make build && make test`