orca/.ciagent/PLANS.md

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 <id> 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 <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)