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

---

Phase Plans: Orca v0.2

All 4 phases with vertical-slice structure, wave ordering, and REQ-ID mapping. v0.2 scope: Networking, Observability, Security Hardening — extends v0.1 with secure cross-node transport, multi-node scheduling, richer CI security scanning, and streaming I/O.

Branching convention: branches are numbered after v0.2's milestone branch milestone/v0.2-networking-observability-security. v0.2's P01 uses phase number 08, P02 uses 09, etc., to avoid colliding with v0.1's phase/01..07 branches (see RELEASE_POLICY.md and run.md for tag hygiene). Milestone branch name in heading reflects the v0.1 retcon where P00-P07 are the v0.1 work; v0.2's first phase is the eighth phase of the project overall.

---

Phase 8: mTLS Handshake + Internal CA with CSR Join (Wave 1)

Branch: phase/08-mtls REQ Coverage: REQ-011, REQ-023, REQ-025, REQ-026, REQ-032, REQ-033, REQ-034, REQ-035, REQ-036, REQ-038

Must-Haves

• internal/security/ca.go — CA init, sign CSR, CA cert persistence to ~/.orca/ca.crt (0644) and ~/.orca/ca.key (0600) per REQ-033
• internal/security/csr.go — CSR generation from a private key with SANs populated (REQ-036)
• internal/security/certgen_test.go — round-trip test: CA-init → build CSR → sign → verify the chain programmatically
• internal/security/fingerprint.go — Fingerprint(certPath) (sha256hex, error) (used by orca cert join --ca-fingerprint)
• internal/security/tls_config.go — ServerTLSConfig() and ClientTLSConfig(caPath) builders, with MinVersion = tls.VersionTLS13 and AEAD cipher allowlist
• internal/security/rotation.go — proactive rotation alarm: returns WARN 30d before not_after (REQ-034); history table bounded at 10 generations per cert kind (REQ-025)
• internal/security/redact.go — orca cert show redaction: strips private key material from default and --json output (REQ-035)
• internal/store/migrations/0004_certs.sql — certs table (id, kind, node_id, serial_hex, subject_cn, issuer_cn, not_before, not_after, fingerprint, source_path, created_at) plus indexes
• internal/store/cert_repo.go — CRUD for the certs table; rotation history pruning helper (REQ-025)
• internal/daemon/tls.go — mTLS server bootstrap; GetCertificate hot-swap callback so orca cert renew takes effect without daemon restart
• internal/transport/mtls.go — mTLS client with cipher allowlist; SAN validation against the pinned peer identity (REQ-036)
• internal/transport/handshake_log.go — structured slog fields on mTLS failure: event=mtls.handshake, peer, cert_fp, err (REQ-038)
• internal/audit/audit.go — emit cert.issued, cert.renewed, cert.joined, node.handshake_ok, node.handshake_failed entries
• internal/cli/cert.go — orca cert {gen,ca-init,csr,show,renew} subcommands
• internal/cli/node_join.go (extend v0.1 stub) — orca node join --ca-fingerprint <sha256> verifies on-disk CA matches the pinned value (REQ-026); refuses to start the daemon on mismatch
• internal/cli/doctor.go (NEW package internal/doctor) — orca doctor, orca doctor cert, orca doctor network, orca doctor db subcommands (REQ-032; network and db checks may stub in P01, full impl in later phases)
• Config surface: ~/.orca/orca.hcl gains a trusted_ca_fingerprint field consumed at daemon start (REQ-026)
• Unit tests for: file mode enforcement (REFUSE on wrong mode, REQ-033), rotation alarm firing at 30d, redaction in cert show, fingerprint mismatch at node join
• Integration test: two-node mTLS handshake — node A signs node B's CSR; node B dials node A and /healthz returns 200; cross-signed with a non-matching CA returns a structured mtls.handshake failure log line

Verification

• go build ./... PASS
• go test ./internal/security/... ./internal/store/... ./internal/transport/... PASS
• go test -race ./... PASS (REQ-031 cross-cutting)
• orca cert ca-init produces a valid CA; ca.crt is 0644, ca.key is 0600; daemon refuses to start if either is wrong (REQ-033)
• orca cert gen produces a server cert signed by the CA, with DNS and IP SANs present (REQ-036); CSR without SANs is rejected at sign-time
• orca node join --ca-fingerprint <sha> dials over mTLS; handshake succeeds when CA matches, fails (and logs event=mtls.handshake peer=... cert_fp=... err=...) when it does not (REQ-026, REQ-038)
• orca cert renew rotates the cert without daemon restart (hot-swap via GetCertificate); new connections use the new cert
• orca cert show (default and --json) never prints private key material (REQ-035)
• Cert rotation history is bounded: inserting an 11th cert per (node_id, kind) prunes the oldest (REQ-025)
• Proactive rotation alarm: a cert with not_after 30d from now triggers a structured WARN at daemon start (REQ-034)
• orca doctor cert reports PASS/WARN/FAIL for CA, server cert, expiry window, and fingerprint pin match (REQ-032)
• Every cert issuance produces an audit_log row with event and cert_fp

---

Phase 9: Multi-Node Scheduling & Job Dispatch (Wave 1)

Branch: phase/09-scheduling REQ Coverage: REQ-004 (expansion), REQ-017, REQ-021, REQ-028, REQ-037

Must-Haves

• internal/transport/dispatch.go — JSON-over-HTTP orca.v1.Dispatch service via stdlib h2c (no ConnectRPC — not in go.mod per research); routes POST /orca.v1.Dispatch/Submit and POST /orca.v1.Dispatch/Status
• internal/transport/idempotency.go — X-Orca-Idempotency-Key header parsing; server-side dedupe store (REQ-037); client-side retry only when header is present
• internal/transport/retry.go — exponential backoff with jitter (100ms, x2, cap 5s, max 5 attempts); only idempotent verbs auto-retry without the key
• internal/engine/dispatcher.go — Submit(peerID, spec) (jobID, error) blocking call; bin-pack selector falls through to remote peer when local node cannot fit
• internal/engine/scheduler.go (extend v0.1) — best-fit bin-packing by available_cpu and available_memory; within-node FIFO queue
• internal/engine/peer.go — peer registry: in-memory map plus SQLite-persisted; records last_seen, address, capacity snapshot
• internal/store/migrations/0005_node_capacity.sql — node_capacity table (node_id, cpu_millicores, memory_mib, disk_mib, updated_at)
• internal/store/capacity_repo.go — capacity CRUD
• HCL schema for NodeCapacity (REQ-028): cpu_millicores, memory_mib, disk_mib; loaded from ~/.orca/node.hcl at orca node join and CLI flags
• internal/cli/node_capacity.go — orca node capacity --set and orca node capacity subcommands
• internal/cli/job_run.go (extend v0.1) — orca job run --target <node-id> explicit target (overrides bin-pack); orca job run (no target) lets the dispatcher pick best-fit
• internal/daemon/dispatch_handler.go — mTLS-protected endpoints for Submit and Status; honors X-Orca-Idempotency-Key for dedupe
• Cancellation propagation: context.Context flows from CLI → daemon → executor → transport → peer; ctrl-c aborts the local task AND the in-flight dispatch call (REQ-017)
• Unit tests: bin-pack scoring (3 jobs across 2 nodes picks the node with the most free capacity each time); idempotency dedupe; retry only on transient errors; cancellation teardown
• Integration test: two-node dispatch — job submitted to node A with no local capacity, dispatched to node B over mTLS, returns the job ID issued by node B; ctrl-c mid-run aborts both sides cleanly

Verification

• go build ./... PASS
• go test ./internal/engine/... ./internal/transport/... ./internal/store/... PASS
• go test -race ./... PASS (REQ-031 cross-cutting)
• Two-node integration test: orca job run spec.hcl on node A with insufficient local capacity dispatches to node B and returns node B's job ID
• Cancellation: Ctrl-C during a dispatched job aborts the local call AND the in-flight POST /orca.v1.Dispatch/Submit; no orphan goroutines (assert with goleak)
• Idempotency: same X-Orca-Idempotency-Key submitted twice within the dedupe window returns the same job ID and does NOT create a duplicate row
• Bin-packing: 3 jobs across 2 nodes, each picks the node with the most free capacity (deterministic test)
• orca node capacity --set updates the persisted node_capacity row; subsequent dispatches see the new value
• X-Orca-Idempotency-Key header is REQUIRED for POST /orca.v1.Dispatch/Submit retries; absent header + transient error → no retry

---

Phase 10: gosec + govulncheck + gitleaks in CI (Wave 2)

Branch: phase/10-security-scan REQ Coverage: REQ-014, REQ-027, REQ-029, REQ-031, REQ-039, REQ-040

Must-Haves

• .coreci.yml validate pipeline: add gosec, govulncheck, gitleaks stages in this order; make security-scan is the local equivalent
• scripts/security_scan.sh — wrapper that runs all three tools, exits non-zero on any unsuppressed finding
• gosec.json baseline: initial run via gosec -fmt json -no-fail > gosec.json; committed to the repo; empty baseline (clean repo) so any new G101 (hardcoded credentials) finding fails the build
• govulncheck invocation: runs in offline mode per REQ-027 — use GOFLAGS=-mod=mod and GOVULNDB=offline (or pre-mirrored DB via GOVULNCHECK_DB); the chosen mechanism is documented in docs/security-scanning.md
• govulncheck output gate: govulncheck -format json ./... piped through a small Go program (or jq) that exits non-zero on any unsuppressed finding
• .gitleaks.toml (REQ-039) — allowlist -----BEGIN CERTIFICATE----- PEM blocks; flag -----BEGIN RSA PRIVATE KEY-----; stopwords for internal/security/testdata/ paths
• .gitleaks-baseline.json (REQ-029) — baseline file committed to suppress the pre-existing .env SHA-1 leak from v0.1 history (rotated forward; baseline gates future re-leaks)
• .golangci.yml (REQ-040) — unified lint config: gosec, govet, gofmt, ineffassign, misspell linters; supersedes any per-tool invocations
• .githooks/pre-commit — gitleaks protect; commits remain allowed when gitleaks is not installed (gate, not block)
• Makefile — add make test-race target that runs go test -race ./... (REQ-031); wire into .coreci.yml validate pipeline
• Makefile — add make security-scan target that invokes scripts/security_scan.sh
• docs/security-scanning.md — operator-facing doc: what each tool checks, how the offline mode is achieved, how to add a baseline entry

Verification

• .coreci.yml parses (yaml validation) and make validate is green locally
• make security-scan runs all three tools and returns 0 on a clean working tree
• gosec: introducing a new G101 (hardcoded credential) finding in a Go file causes make security-scan to fail
• govulncheck: with GOFLAGS=-mod=mod, the run completes without network access (offline mode) — verified by running the CI step under a network namespace that blocks outbound HTTPS to vuln.go.dev; unsuppressed CVE in a dep still fails the build
• gitleaks: a sample secret injected into a test file is detected; a -----BEGIN CERTIFICATE----- PEM block in internal/security/testdata/ is allowed (not flagged)
• make test-race passes against the current test suite (REQ-031 cross-cutting)
• .gitleaks-baseline.json round-trips: re-running the gitleaks pre-commit hook does not re-flag the historical .env SHA-1
• .golangci.yml make lint is green against the current code

---

Phase 11: iter.Seq Streaming Job/Node Lists (Wave 2)

Branch: phase/11-iter-seq REQ Coverage: REQ-022, REQ-030, REQ-032 (expansion)

Must-Haves

• internal/store/iter.go — Watch(ctx, query) iter.Seq[T] for jobs and nodes; poll-based at 500ms initially, with an internal notify channel hook so a future event-driven source can replace the poll without API churn
• internal/store/iter_test.go — round-trip: insert N rows, range over Watch, assert all N are yielded; cancel mid-stream and assert the seq stops cleanly with no goroutine leak (goleak or runtime.NumGoroutine snapshot)
• internal/cli/job_list.go (extend v0.1) — orca job list --watch returns iter.Seq[Job]; default output is a human-readable table that updates; orca job list --watch --json outputs one JSON object per line for piping (REQ-030)
• internal/cli/node_list.go (extend v0.1) — orca node list --watch returns iter.Seq[Node]; same table/JSON split as jobs
• Cancellation wiring: signal.NotifyContext(parent, os.Interrupt) — ctrl-c stops the stream cleanly without orphan goroutines
• internal/doctor/ (extend P01 stub) — orca doctor jobs, orca doctor nodes, orca doctor certs stream results as iter.Seq[DoctorResult]; each row carries a status (PASS|WARN|FAIL) and a human-readable message (REQ-032 expansion)
• Unit tests: --watch mode yields on insert; --watch --json produces one JSON object per line (line-by-line parse); orca doctor certs lists all certs with expiry and rotation status
• Integration test: start orca job list --watch as a subprocess, insert a new job, assert the subprocess output contains the new job's ID

Verification

• go build ./... PASS
• go test ./internal/store/... ./internal/cli/... ./internal/doctor/... PASS
• go test -race ./... PASS (REQ-031 cross-cutting)
• orca job list --watch streams and updates on new job insertion (integration test, two-process or two-goroutine)
• orca job list --watch --json produces one JSON object per line (NDJSON); validatable by piping through jq -c .
• orca doctor certs lists every cert with its not_after, days-until-expiry, and rotation status (REQ-032 expansion; ties into P01's cert health checks)
• Ctrl-C during a watch cleanly cancels the seq; runtime.NumGoroutine() returns to the pre-watch baseline (asserted in tests via goleak.VerifyNone or a manual snapshot diff)
• orca node list --watch --json behaves identically to the jobs variant

---

Wave Ordering

• Wave 1 (Phases 8-9): Networking & scheduling — mTLS handshake and internal CA (P01) is a hard prerequisite for cross-node dispatch (P02), since the dispatch endpoints are mTLS-protected. Both phases run sequentially because parallelization.enabled=false.
• Wave 2 (Phases 10-11): Security scan & streaming I/O — security scanning (P03) and iter.Seq streaming (P04) are independent; parallelization.enabled=false so they run sequentially, but either order is technically viable. P03 first keeps the security baseline in place while P04 lands the new CLI surface.

Phases within a wave can be parallelized if parallelization.enabled=true. For v0.2, parallelization.enabled=false — phases run sequentially.

Versioning

• Milestone type: feature (all 4 phases ship features)
• Patch per phase: v0.2.1 (P01 mTLS), v0.2.2 (P02 scheduling), v0.2.3 (P03 security scan), v0.2.4 (P04 iter.Seq)
• Final tag on COMPLETE: v0.3.0 (next minor per run.md versioning logic; per RELEASE_POLICY.md, every per-phase tag also produces a Gitea release)