Jon Chery
c2038952c7
---ci--- project: orca phase: 0 milestone: v0.1 status: plan phases_planned: 6 waves: 4 ---/ci---
166 lines
5.8 KiB
Markdown
166 lines
5.8 KiB
Markdown
# 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, REQ-002, REQ-013, REQ-015, REQ-016, REQ-019, REQ-024
|
|
|
|
### 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 <id>` removes node
|
|
- Restart daemon, node state persists
|
|
|
|
---
|
|
|
|
## Phase 3: Task Execution Engine (Wave 2)
|
|
|
|
**Branch**: `phase/03-task-exec`
|
|
**REQ Coverage**: REQ-004, REQ-009, REQ-021, REQ-022
|
|
|
|
### 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 <spec.hcl>` to executor
|
|
- [ ] Wire `orca job list` to repository
|
|
- [ ] Wire `orca job stop <id>` to executor
|
|
- [ ] Wire `orca job logs <id>` 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)
|