# Phase Plans: Orca v0.1 All 6 phases with vertical-slice structure, wave ordering, and REQ-ID mapping. --- ## Phase 1: CLI Skeleton (Wave 1) **Branch**: `phase/01-cli-skeleton` **REQ Coverage**: REQ-001 (Go 1.25), REQ-002 (CLI-first single binary), REQ-003 (offline-first — no network deps in CLI), REQ-008 (slog structured logging), REQ-010 (`--json` output flag), REQ-013 (pre-push hook), REQ-015 (MIT LICENSE), REQ-016 (README quickstart), REQ-019 (Cobra), REQ-024 (Makefile) ### Must-Haves - [ ] `go.mod` with `go 1.25` - [ ] `cmd/orca/main.go` — entry point - [ ] `internal/cli/root.go` — Cobra root command with `--json` global flag - [ ] `internal/cli/version.go` — `orca version` subcommand - [ ] `internal/cli/init.go` — `orca init` subcommand (stub) - [ ] `internal/cli/status.go` — `orca status` subcommand (stub) - [ ] `internal/cli/node.go` — `orca node {join,leave,list}` stubs - [ ] `internal/cli/job.go` — `orca job {run,list,stop,logs}` stubs - [ ] `Makefile` with `build`, `test`, `lint`, `fmt` targets - [ ] `LICENSE` (MIT) - [ ] `README.md` with quickstart - [ ] `.gitignore` for `bin/`, `coverage.out`, `*.test` - [ ] `.githooks/pre-push` → `scripts/trigger_coreci.sh` - [ ] `scripts/trigger_coreci.sh` — curl-based CoreCI trigger ### Verification - `go build ./cmd/orca` succeeds - `orca --help` lists all subcommands - `orca version` prints version - `orca --json version` prints JSON - `make build`, `make test`, `make lint`, `make fmt` all succeed --- ## Phase 2: Node Management (Wave 2) **Branch**: `phase/02-node-mgmt` **REQ Coverage**: REQ-002, REQ-005, REQ-012, REQ-017, REQ-018 ### Must-Haves - [ ] `internal/store/sqlite.go` — SQLite connection (modernc/sqlite) - [ ] `internal/store/migrations/0001_nodes.sql` — nodes table schema - [ ] `internal/store/node_repo.go` — Node repository (CRUD) - [ ] `internal/engine/registry.go` — In-memory node registry with SQLite persistence - [ ] Wire `orca node join` to registry - [ ] Wire `orca node leave` to registry - [ ] Wire `orca node list` to registry - [ ] Audit log on all node operations - [ ] Config loading from `~/.orca/config.hcl` ### Verification - `orca node join --name test --addr localhost:8443` adds node - `orca node list` shows added node - `orca node leave ` removes node - Restart daemon, node state persists --- ## Phase 3: Task Execution Engine (Wave 2) **Branch**: `phase/03-task-exec` **REQ Coverage**: REQ-004 (task execution), REQ-009 (HCL/YAML parsing), REQ-020 (hashicorp/hcl parser), REQ-021 (os/exec with WaitDelay), REQ-022 (iter.Seq streaming — deferred) ### Must-Haves - [ ] `internal/store/migrations/0002_jobs_tasks.sql` — jobs + tasks tables - [ ] `internal/store/job_repo.go` — Job repository - [ ] `internal/store/task_repo.go` — Task repository - [ ] `internal/engine/executor.go` — `os/exec` with `WaitDelay` (Go 1.25+) - [ ] `internal/engine/scheduler.go` — Single-node FIFO scheduler - [ ] `internal/jobspec/hcl.go` — HCL job spec parser - [ ] Wire `orca job run ` to executor - [ ] Wire `orca job list` to repository - [ ] Wire `orca job stop ` to executor - [ ] Wire `orca job logs ` to task output ### Verification - `orca job run` with valid HCL spec executes command - Task status transitions: pending → running → complete - `orca job list` shows job history - `orca job stop` kills running process cleanly (WaitDelay) --- ## Phase 4: Local State Persistence Hardening (Wave 3) **Branch**: `phase/04-state-persistence` **REQ Coverage**: REQ-005, REQ-018 ### Must-Haves - [ ] `internal/store/migrate.go` — Migration runner - [ ] `internal/store/audit_repo.go` — Audit log repository - [ ] `internal/store/migrations/0003_audit_log.sql` — audit_log table - [ ] Embed migrations via `//go:embed` - [ ] Transaction wrapping for all writes - [ ] Connection pool tuning - [ ] Graceful shutdown flushes pending writes ### Verification - Migrations apply on first run - Audit log entries persist across restarts - Concurrent writes don't corrupt state (test with `go test -race`) --- ## Phase 5: Health Checks (Wave 3) **Branch**: `phase/05-health-checks` **REQ Coverage**: REQ-006, REQ-017 ### Must-Haves - [ ] `internal/daemon/server.go` — `net/http` server with `http.ServeMux` - [ ] `internal/daemon/health.go` — `/healthz` and `/readyz` handlers - [ ] `internal/daemon/jobs_handler.go` — `/v1/jobs/*` handlers - [ ] `internal/daemon/nodes_handler.go` — `/v1/nodes/*` handlers - [ ] `internal/daemon/tasks_handler.go` — `/v1/tasks/*` handlers - [ ] Graceful shutdown via `signal.NotifyContext` - [ ] Health endpoint checks SQLite connectivity - [ ] Wire CLI subcommands to daemon API ### Verification - `curl http://localhost:8080/healthz` returns 200 - `curl http://localhost:8080/readyz` returns 200 when ready - `curl http://localhost:8080/v1/jobs` returns job list as JSON - Daemon shuts down cleanly on SIGTERM --- ## Phase 6: CoreCI Full Release Flow (Wave 4) **Branch**: `phase/06-coreci-release` **REQ Coverage**: REQ-007, REQ-014 ### Must-Haves - [ ] `.coreci.yml` — validate, build, test, release pipelines - [ ] `scripts/release.sh` — `tea releases create` wrapper - [ ] `Makefile` `release` target invokes release script - [ ] Tarball generation in release pipeline - [ ] Version injection via `-ldflags` - [ ] `CHANGELOG.md` (auto-generated from `---ci---` blocks) ### Verification - `make release` creates Gitea release with tarball - Tarball contains `orca` binary - Release notes include phase summary - CoreCI `validate`, `build`, `test`, `release` pipelines all green --- ## Wave Ordering - **Wave 1** (Phase 1): Foundation — CLI skeleton, build system, hooks - **Wave 2** (Phases 2-3): Core functionality — node registry, task execution - **Wave 3** (Phases 4-5): Hardening — state persistence, health checks - **Wave 4** (Phase 6): Release — CoreCI integration Phases within a wave can be parallelized if `parallelization.enabled=true`. For v0.1, `parallelization.enabled=false` — phases run sequentially. ## Versioning - **Milestone type**: `feature` (Phases 1-6 all produce features) - **Patch per phase**: `v0.1.1`, `v0.1.2`, ..., `v0.1.6` - **Final tag on COMPLETE**: `v0.2.0` (next minor per `run.md` versioning logic)