savepoint 1.0.1 → 1.0.3

package/.savepoint/releases/v1.1/epics/E09-doctor-command/E09-Audit.md

@@ -0,0 +1,207 @@
+---
+type: audit-findings
+audited: 2026-05-03
+---
+# Audit Findings: E09 Doctor Command
+
+## Main Findings
+
+Applied audit proposals for E09. The `doctor` structure check now validates the active `{release}-PRD.md` layout instead of the obsolete `PRD.md` filename, and the related tests and repair suggestion were updated. During verification, the repair switch was also tightened so the specific release PRD hint is not shadowed by the generic release-directory hint.
+
+Design.md, AGENTS.md, and E09-Detail.md now document the implemented doctor command and `internal/doctor/` module. E09 is marked audited and Design.md `last_audited` points to `v1.1/E09-doctor-command`.
+
+Residual process note: the E09 task files still lack the required `## Context Files` sections. That does not block the applied code fix, but it should be corrected in future task authoring.
+
+Verification after apply: `go build ./...` and `go test ./...` passed. `make build && make test` remains unavailable in this environment because `make` is not installed.
+
+## 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 - the implementation fix was narrowly scoped; the remaining context-section note is process cleanup, not product code risk.
+
+## Proposed Changes
+
+### Target File
+internal/doctor/checks.go
+
+### Replace
+```go
+		for _, release := range releases {
+		checkReleasePRD(release.Path, &problems)
+```
+
+### With
+```go
+	for _, release := range releases {
+		checkReleasePRD(release.Path, release.ID, &problems)
+```
+
+### Target File
+internal/doctor/checks.go
+
+### Replace
+```go
+func checkReleasePRD(releasePath string, problems *[]Problem) {
+	prdPath := filepath.Join(releasePath, "PRD.md")
+```
+
+### With
+```go
+func checkReleasePRD(releasePath string, releaseID string, problems *[]Problem) {
+	prdPath := filepath.Join(releasePath, releaseID+"-PRD.md")
+```
+
+### Target File
+internal/doctor/checks.go
+
+### Replace
+```go
+		*problems = append(*problems, Problem{File: prdPath, Message: "release PRD.md not found"})
+```
+
+### With
+```go
+		*problems = append(*problems, Problem{File: prdPath, Message: "release PRD file not found"})
+```
+
+### Target File
+internal/doctor/repairs.go
+
+### Replace
+```go
+	case contains(p.Message, "PRD.md not found"):
+		return "Create a PRD.md with frontmatter for the release"
+```
+
+### With
+```go
+	case contains(p.Message, "release PRD file not found"):
+		return "Create a {release}-PRD.md file with frontmatter for the release"
+```
+
+### Target File
+internal/doctor/checks_test.go
+
+### Replace
+```go
+	writeFile(t, filepath.Join(releasePath, "PRD.md"), "---\ntype: project-prd\nstatus: active\n---\n\n# Release\n")
+```
+
+### With
+```go
+	writeFile(t, filepath.Join(releasePath, filepath.Base(releasePath)+"-PRD.md"), "---\ntype: project-prd\nstatus: active\n---\n\n# Release\n")
+```
+
+### Target File
+internal/doctor/report_test.go
+
+### Replace
+```go
+	writeFile(t, filepath.Join(releasePath, "PRD.md"), "---\ntype: project-prd\nstatus: active\n---\n\n# Release\n")
+```
+
+### With
+```go
+	writeFile(t, filepath.Join(releasePath, "v1-PRD.md"), "---\ntype: project-prd\nstatus: active\n---\n\n# Release\n")
+```
+
+### Target File
+.savepoint/Design.md
+
+### Replace
+```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).
+```
+
+### 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).
+- **Doctor command** (`savepoint doctor`, `savepoint doctor --epic E##`) runs read-only integrity diagnostics for config, router state, release/epic/task structure, frontmatter validity, acceptance criteria presence, dependencies, duplicate task IDs, stale audit files, orphaned task IDs, and configured quality gates. It prints a human-readable report with repair suggestions and exits 0 when clean, 1 when problems are diagnosed, and 2 for internal or invocation failures.
+```
+
+### Target File
+.savepoint/Design.md
+
+### Replace
+```md
+| `cmd/` | CLI command arg parsing and dispatch for init and board |
+```
+
+### With
+```md
+| `cmd/` | CLI command arg parsing and dispatch for init, board, and doctor |
+```
+
+### Target File
+.savepoint/Design.md
+
+### Replace
+```md
+| `internal/board/` | TUI board, overlays, epic sidebar, Next Activity line, router priority key, detail checklist rendering, status glyphs, forced color profile |
+| `internal/buildtool/` | Makefile helper, cross-compile, archives |
+```
+
+### With
+```md
+| `internal/board/` | TUI board, overlays, epic sidebar, Next Activity line, router priority key, detail checklist rendering, status glyphs, forced color profile |
+| `internal/buildtool/` | Makefile helper, cross-compile, archives |
+| `internal/doctor/` | Read-only project diagnostics, integrity checks, quality gate execution, report formatting, repair suggestions |
+```
+
+### Target File
+AGENTS.md
+
+### Replace
+```md
+| `cmd/` | CLI command arg parsing and dispatch for init and board |
+```
+
+### With
+```md
+| `cmd/` | CLI command arg parsing and dispatch for init, board, and doctor |
+```
+
+### Target File
+AGENTS.md
+
+### Replace
+```md
+| `internal/board/` | TUI board, overlays, epic sidebar, Next Activity line, router priority key, detail checklist rendering, status glyphs, forced color profile |
+| `internal/buildtool/` | Makefile helper, cross-compile, archives |
+```
+
+### With
+```md
+| `internal/board/` | TUI board, overlays, epic sidebar, Next Activity line, router priority key, detail checklist rendering, status glyphs, forced color profile |
+| `internal/buildtool/` | Makefile helper, cross-compile, archives |
+| `internal/doctor/` | Read-only project diagnostics, integrity checks, quality gate execution, report formatting, repair suggestions |
+```
+
+### Target File
+.savepoint/releases/v1.1/epics/E09-doctor-command/E09-Detail.md
+
+### Replace
+```md
+## Boundaries
+```
+
+### With
+```md
+## Implemented As
+
+- `cmd/doctor.go` parses `doctor [--epic <epic>]`, reports help, rejects unsupported arguments, and delegates execution through an injected runner.
+- `main.go` wires `savepoint doctor` to `internal/doctor.RunAllChecks` and preserves the required 0/1/2 exit-code contract.
+- `internal/doctor/checks.go` implements config, router, structure, dependency, duplicate ID, audit-state, and orphan diagnostics.
+- `internal/doctor/gates.go`, `report.go`, and `repairs.go` run configured quality gates, format human-readable reports, and attach repair suggestions.
+- Tests live in `cmd/doctor_test.go` and `internal/doctor/*_test.go`.
+
+## Boundaries
+```

package/.savepoint/releases/v1.1/epics/E09-doctor-command/E09-Detail.md

@@ -0,0 +1,65 @@
+---
+type: epic-design
+status: audited
+---
+
+# E09: Doctor Command
+
+## Purpose
+
+Implement `savepoint doctor`, the diagnostic command for corrupted or inconsistent Savepoint projects. Doctor reports problems and suggested repairs, but does not make destructive changes automatically.
+
+## Interface
+
+```bash
+savepoint doctor                    # run all checks
+savepoint doctor --epic E03          # check specific epic
+```
+
+## What this epic adds
+
+- Integrity checks: config, router state, release/epic/task structure
+- YAML/frontmatter validation: detect corrupt YAML
+- Task acceptance criteria check: verify AC present
+- Dependency checks: missing deps, cycles, duplicate IDs
+- Audit state check: proposals without audit-pending flag
+- Orphan detection: tasks in nonexistent epics
+- Ad-hoc quality gate runner
+- Human-readable diagnostic output
+- Repair suggestions for common failure modes
+- Exit codes: clean (0), diagnosed problems (1), internal failure (2)
+
+## Components
+
+| Module | Purpose |
+|--------|---------|
+| `cmd/doctor.go` | CLI registration, arg parsing |
+| `internal/doctor/checks.go` | Individual integrity checks |
+| `internal/doctor/report.go` | Diagnostic report formatting |
+| `internal/doctor/repairs.go` | Suggested repair text |
+| `internal/doctor/gates.go` | Ad-hoc quality gate runner |
+
+## Implemented As
+
+- `cmd/doctor.go` parses `doctor [--epic <epic>]`, reports help, rejects unsupported arguments, and delegates execution through an injected runner.
+- `main.go` wires `savepoint doctor` to `internal/doctor.RunAllChecks` and preserves the required 0/1/2 exit-code contract.
+- `internal/doctor/checks.go` implements config, router, structure, dependency, duplicate ID, audit-state, and orphan diagnostics.
+- `internal/doctor/gates.go`, `report.go`, and `repairs.go` run configured quality gates, format human-readable reports, and attach repair suggestions.
+- Tests live in `cmd/doctor_test.go` and `internal/doctor/*_test.go`.
+
+## Boundaries
+
+**In scope:**
+- Detect corrupt YAML/frontmatter
+- Detect missing config
+- Detect missing dependencies and dependency cycles
+- Detect duplicate task IDs
+- Detect tasks in nonexistent epics
+- Detect audit proposals without matching audit-pending state
+- Run configured quality gates on demand
+
+**Out of scope:**
+- Auto-moving orphaned tasks without user action
+- Repairing files destructively
+- Launching the TUI
+- Calling AI APIs

package/.savepoint/releases/v1.1/epics/E09-doctor-command/tasks/T001-cli-entrypoint.md

@@ -0,0 +1,24 @@
+---
+id: E09-doctor-command/T001-cli-entrypoint
+status: done
+objective: "Create CLI entrypoint for savepoint doctor command"
+depends_on: []
+---
+
+# T001: CLI Entrypoint
+
+## Acceptance Criteria
+
+- `savepoint doctor --help` shows usage: `doctor [--epic <epic>]`
+- `savepoint doctor` runs all checks
+- `savepoint doctor --epic E03` runs checks for specific epic
+- Exit codes: 0 = clean, 1 = diagnosed problems, 2 = internal error
+
+## Implementation Plan
+
+- [x] Add `cmd/doctor.go` with CLI arg parsing
+- [x] Wire doctor command into main.go dispatch
+- [x] Implement arg validation (--epic)
+- [x] Implement exit code logic (0/1/2)
+- [x] Test `savepoint doctor --help` output
+- [x] Run `make build && make test`

package/.savepoint/releases/v1.1/epics/E09-doctor-command/tasks/T002-config-router-validation.md

@@ -0,0 +1,28 @@
+---
+id: E09-doctor-command/T002-config-router-validation
+status: done
+objective: "Validate config.yml and router state"
+depends_on: ["E09-doctor-command/T001-cli-entrypoint"]
+---
+
+# T002: Config + Router Validation
+
+## Acceptance Criteria
+
+- Config.yml exists and is valid YAML
+- Config has required fields: quality_gates, theme
+- Router state is valid (valid state name, release, epic)
+- Router state matches actual release/epic directories
+
+## Implementation Plan
+
+- [x] Add `internal/doctor/checks.go`
+- [x] Implement `CheckConfig(root) error`
+- [x] Validate config.yml exists and parses
+- [x] Validate required fields present
+- [x] Implement `CheckRouter(root, epicFilter) error`
+- [x] Validate router state is valid YAML
+- [x] Validate state name is one of: pre-implementation, epic-design, epic-task-breakdown, task-building, audit-pending
+- [x] Validate release/epic directories exist
+- [x] Test validation on valid and invalid projects
+- [x] Run `make build && make test`

package/.savepoint/releases/v1.1/epics/E09-doctor-command/tasks/T003-structure-checks.md

@@ -0,0 +1,29 @@
+---
+id: E09-doctor-command/T003-structure-checks
+status: done
+objective: "Validate release/epic/task structure and YAML"
+depends_on: ["E09-doctor-command/T002-config-router-validation"]
+---
+
+# T003: Structure Checks
+
+## Acceptance Criteria
+
+- Release directories exist and contain release PRD
+- Epic directories exist and contain E##-Detail.md
+- Task files are valid markdown with YAML frontmatter
+- Corrupt YAML/frontmatter detected with file:line info
+- Task acceptance criteria present and non-empty
+
+## Implementation Plan
+
+- [x] Add to `internal/doctor/checks.go`
+- [x] Implement `CheckStructure(root, epicFilter)` returning `[]Problem`
+- [x] Walk release directories, validate release PRD
+- [x] Walk epic directories, validate E##-Detail.md
+- [x] Walk task files, parse frontmatter
+- [x] Validate each task has: id, status, objective, depends_on
+- [x] Check acceptance criteria present in task body
+- [x] Detect corrupt YAML with file:line location
+- [x] Test structure validation on valid and invalid projects
+- [x] Run `make build && make test`

package/.savepoint/releases/v1.1/epics/E09-doctor-command/tasks/T004-dependency-checks.md

@@ -0,0 +1,27 @@
+---
+id: E09-doctor-command/T004-dependency-checks
+status: done
+objective: "Validate dependencies for missing deps, cycles, duplicates"
+depends_on: ["E09-doctor-command/T003-structure-checks"]
+---
+
+# T004: Dependency Checks
+
+## Acceptance Criteria
+
+- Missing dependencies detected (depends_on points to non-existent task)
+- Dependency cycles detected (A→B→C→A)
+- Duplicate task IDs detected
+- Clear error messages for each failure
+
+## Implementation Plan
+
+- [x] Add to `internal/doctor/checks.go`
+- [x] Implement `CheckDependencies(root, epicFilter) error`
+- [x] Collect all task IDs from release
+- [x] Check each depends_on references existing task
+- [x] Build dependency graph, detect cycles (DFS)
+- [x] Detect duplicate task IDs (same ID in multiple files)
+- [x] Return clear error messages for each issue
+- [x] Test dependency validation on valid and invalid projects
+- [x] Run `make build && make test`

package/.savepoint/releases/v1.1/epics/E09-doctor-command/tasks/T005-audit-orphan-checks.md

@@ -0,0 +1,28 @@
+---
+id: E09-doctor-command/T005-audit-orphan-checks
+status: done
+objective: "Validate audit state and detect orphaned tasks"
+depends_on: ["E09-doctor-command/T004-dependency-checks"]
+---
+
+# T005: Audit + Orphan Checks
+
+## Acceptance Criteria
+
+- Audit proposals without matching audit-pending state detected
+- Orphaned tasks detected (tasks in nonexistent epics)
+- Orphaned tasks reported with suggestion to move to .savepoint/orphans/
+- Audit log shows previous audit results
+
+## Implementation Plan
+
+- [x] Add to `internal/doctor/checks.go`
+- [x] Implement `CheckAuditState(root) []Problem`
+- [x] Find all audit proposal directories
+- [x] Check router state is audit-pending for corresponding epic
+- [x] Warn if proposals exist without audit-pending state
+- [x] Implement `CheckOrphans(root) []Problem`
+- [x] Find tasks whose epic directory doesn't exist
+- [x] Report orphaned tasks with move suggestion
+- [x] Test audit and orphan detection
+- [x] Run `make build && make test`

package/.savepoint/releases/v1.1/epics/E09-doctor-command/tasks/T006-quality-gates-report.md

@@ -0,0 +1,31 @@
+---
+id: E09-doctor-command/T006-quality-gates-report
+status: done
+objective: "Run quality gates on demand and format diagnostic report"
+depends_on: ["E09-doctor-command/T005-audit-orphan-checks"]
+---
+
+# T006: Quality Gates + Report
+
+## Acceptance Criteria
+
+- Run configured lint, typecheck, test commands from config
+- Report pass/fail status for each gate
+- Format all diagnostics into human-readable report
+- Include file paths and actionable fix suggestions
+- Return appropriate exit code
+
+## Implementation Plan
+
+- [x] Add `internal/doctor/gates.go`
+- [x] Implement `RunQualityGates(root) []GateResult`
+- [x] Read config quality_gates
+- [x] Execute each command, capture output
+- [x] Report pass/fail for each gate
+- [x] Add `internal/doctor/report.go`
+- [x] Collect all check results
+- [x] Format into human-readable report
+- [x] Add repair suggestions from internal/doctor/repairs.go
+- [x] Return exit code: 0 if all clean, 1 if problems found
+- [x] Test doctor on valid and invalid projects
+- [x] Run `make build && make test`

package/.savepoint/releases/v1.1/epics/E11-board-refresh-fix/E11-Detail.md

@@ -0,0 +1,36 @@
+---
+type: epic-design
+status: audited
+---
+
+# E11: Board Auto-Refresh Fix
+
+## Purpose
+
+Fix the TUI board so it auto-refreshes when task files change on disk. The watch mechanism exists but isn't triggering reloads on file changes.
+
+## What this epic adds
+
+- Debug logging to trace where the refresh fails
+- Increased debounce timer for reliable event detection
+- Error handling for silent watcher failures
+- Verified auto-refresh on file changes
+
+## Components
+
+| Module | Purpose |
+|--------|---------|
+| `internal/board/watch.go` | Debug logs, increased debounce, error handling |
+| `internal/board/update.go` | Debug logs for reload flow |
+
+## Boundaries
+
+**In scope:**
+- Debug logging to identify failure point
+- Fix debounce timing
+- Fix error handling
+- Verify refresh works
+
+**Out of scope:**
+- No new UI features
+- No new core functionality

package/.savepoint/releases/v1.1/epics/E11-board-refresh-fix/tasks/T001-debug-logging.md

@@ -0,0 +1,25 @@
+---
+id: E11-board-refresh-fix/T001-debug-logging
+status: done
+objective: Add debug logging to watch.go to trace where refresh fails
+depends_on: []
+---
+
+# T001: Debug Logging
+
+## Acceptance Criteria
+
+- [ ] Print when watchFiles() starts watching
+- [ ] Print when event received from watcher
+- [ ] Print when fileChangeMsg received in update.go
+- [ ] Print any errors from watcher Errors channel
+- [ ] Print when reloadTasks() is called
+
+## Implementation Plan
+
+- [ ] In `watch.go` - add fmt.Printf at start of watchFiles()
+- [ ] In `watch.go` - add fmt.Printf for each event received
+- [ ] In `watch.go` - add fmt.Printf for watcher errors
+- [ ] In `update.go` - add fmt.Printf when fileChangeMsg received
+- [ ] In `watch.go` - add fmt.Printf when reloadTasks() called
+- [ ] Run board, make file change, observe logs

package/.savepoint/releases/v1.1/epics/E11-board-refresh-fix/tasks/T002-increase-debounce.md

@@ -0,0 +1,21 @@
+---
+id: E11-board-refresh-fix/T002-increase-debounce
+status: done
+objective: Increase debounce timer from 100ms to 500ms for reliable detection
+depends_on:
+    - E11-board-refresh-fix/T001-debug-logging
+---
+
+# T002: Increase Debounce
+
+## Acceptance Criteria
+
+- [ ] Change timer from 100ms to 500ms
+- [ ] Verify board still works
+
+## Implementation Plan
+
+- [ ] In `internal/board/watch.go` line 31:
+  - FROM: `timer := time.NewTimer(100 * time.Millisecond)`
+  - TO: `timer := time.NewTimer(500 * time.Millisecond)`
+- [ ] Run `make build` to verify

package/.savepoint/releases/v1.1/epics/E11-board-refresh-fix/tasks/T003-error-handling.md

@@ -0,0 +1,22 @@
+---
+id: E11-board-refresh-fix/T003-error-handling
+status: done
+objective: Add error handling instead of silent returns in watcher
+depends_on:
+    - E11-board-refresh-fix/T001-debug-logging
+---
+
+# T003: Error Handling
+
+## Acceptance Criteria
+
+- [ ] Log instead of silent return on channel close
+- [ ] Log watcher errors that are currently ignored
+- [ ] Log any reload failures
+
+## Implementation Plan
+
+- [ ] In `watch.go` - replace `if !ok { return nil }` with error log
+- [ ] In `watch.go` - add logging for `w.Errors` channel events
+- [ ] In `reloadTasks()` - add error handling for loadBoardData failure
+- [ ] Run tests

package/.savepoint/releases/v1.1/epics/E11-board-refresh-fix/tasks/T004-test-verify.md

@@ -0,0 +1,29 @@
+---
+id: E11-board-refresh-fix/T004-test-verify
+status: done
+objective: Test and verify board refreshes on file change
+depends_on:
+    - E11-board-refresh-fix/T001-debug-logging
+    - E11-board-refresh-fix/T002-increase-debounce
+    - E11-board-refresh-fix/T003-error-handling
+---
+
+# T004: Test & Verify
+
+## Acceptance Criteria
+
+- [ ] Board starts with debug logs visible
+- [ ] Create new task file while board running
+- [ ] Board auto-refreshes within 1 second
+- [ ] New task appears in Planned column
+
+## Implementation Plan
+
+- [ ] Start board from terminal
+- [ ] Verify debug log output shows watchFiles() started
+- [ ] Create test task file: `echo "---" > E06/tasks/T999-test.md`
+- [ ] Wait 2 seconds for debounce + reload
+- [ ] Verify task appears in board
+- [ ] Or: debug log shows fileChangeMsg received
+- [ ] Clean up test file
+- [ ] Run `make build && make test`