fix(doctor): add sqlite3 availability check (#575)

- Add sqlite3 to README.md prerequisites section
- Add gt doctor check that warns if sqlite3 CLI is not found
- Documents that sqlite3 is required for convoy database queries

Fixes #534

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

README.md

@@ -86,6 +86,7 @@ Git-backed issue tracking system that stores work state as structured data.
 - **Go 1.23+** - [go.dev/dl](https://go.dev/dl/)
 - **Git 2.25+** - for worktree support
 - **beads (bd) 0.44.0+** - [github.com/steveyegge/beads](https://github.com/steveyegge/beads) (required for custom type support)
+- **sqlite3** - for convoy database queries (usually pre-installed on macOS/Linux)
 - **tmux 3.0+** - recommended for full experience
 - **Claude Code CLI** (default runtime) - [claude.ai/code](https://claude.ai/code)
 - **Codex CLI** (optional runtime) - [developers.openai.com/codex/cli](https://developers.openai.com/codex/cli)

internal/cmd/doctor.go

@@ -118,6 +118,7 @@ func runDoctor(cmd *cobra.Command, args []string) error {
 
 	// Register built-in checks
 	d.Register(doctor.NewStaleBinaryCheck())
+	d.Register(doctor.NewSqlite3Check())
 	d.Register(doctor.NewTownGitCheck())
 	d.Register(doctor.NewTownRootBranchCheck())
 	d.Register(doctor.NewPreCheckoutHookCheck())

internal/doctor/sqlite3_check.go

@@ -0,0 +1,52 @@
+package doctor
+
+import (
+	"os/exec"
+)
+
+// Sqlite3Check verifies that sqlite3 CLI is available.
+// sqlite3 is required for convoy-related database queries including:
+// - gt convoy status (tracking issue progress)
+// - gt sling duplicate convoy detection
+// - TUI convoy panels
+// - Daemon convoy completion detection
+type Sqlite3Check struct {
+	BaseCheck
+}
+
+// NewSqlite3Check creates a new sqlite3 availability check.
+func NewSqlite3Check() *Sqlite3Check {
+	return &Sqlite3Check{
+		BaseCheck: BaseCheck{
+			CheckName:        "sqlite3-available",
+			CheckDescription: "Check sqlite3 CLI is installed (required for convoy features)",
+			CheckCategory:    CategoryInfrastructure,
+		},
+	}
+}
+
+// Run checks if sqlite3 is available in PATH.
+func (c *Sqlite3Check) Run(ctx *CheckContext) *CheckResult {
+	path, err := exec.LookPath("sqlite3")
+	if err != nil {
+		return &CheckResult{
+			Name:    c.Name(),
+			Status:  StatusWarning,
+			Message: "sqlite3 CLI not found",
+			Details: []string{
+				"sqlite3 is required for convoy features:",
+				"  - gt convoy status (shows 0 tracked issues without it)",
+				"  - gt sling duplicate convoy detection",
+				"  - TUI convoy panels",
+				"  - Daemon convoy completion detection",
+			},
+			FixHint: "Install sqlite3: apt install sqlite3 (Debian/Ubuntu) or brew install sqlite3 (macOS)",
+		}
+	}
+
+	return &CheckResult{
+		Name:    c.Name(),
+		Status:  StatusOK,
+		Message: "sqlite3 found at " + path,
+	}
+}