orca/.ciagent/ROADMAP.md

Roadmap: Orca

Milestone v0.1: Foundation — COMPLETE

• Phase 0: Project Initialization & Specification
• Phase 1: Core CLI Skeleton & Command Parsing
• Phase 2: Basic Node Management (Join/Leave)
• Phase 3: Simple Task Execution Engine
• Phase 4: Local State Persistence
• Phase 5: Basic Health Checking
• Phase 6: CoreCI Full Release Flow

Tagged v0.2.0 (next-minor per feature-milestone promotion rule).

Deferred to v0.2 (out of scope for v0.1)

• Multi-node scheduling (D-004 decision: single-node only in v0.1)
• mTLS for inter-node communication (REQ-011, REQ-023)
• gosec + govulncheck in CI pipeline (REQ-014)
• iter.Seq streaming job lists (REQ-022)
• Frontend / devops personas (no web UI; CoreCI handles release)

Milestone v0.2: Networking, Observability, Security Hardening — COMPLETE (merged to main via v0.3)

Scope: extend v0.1 with secure cross-node transport, multi-node scheduling, richer CI security scanning, and streaming I/O.

• Phase 8: mTLS handshake + internal CA with CSR join (Wave 1) — shipped v0.2.1
• Phase 9: Multi-node scheduling & job dispatch (Wave 1) — shipped v0.2.2
• Phase 10: gosec + govulncheck + gitleaks in CI (Wave 2) — shipped v0.2.3
• Phase 11: iter.Seq streaming job/node lists (Wave 2) — completed in v0.3 P01 (shipped v0.3.1)

Milestone tag: v0.4.0 (shipped — v0.2 work merged to main via v0.3 milestone).

Per-phase tags: v0.2.1 (P01), v0.2.2 (P02), v0.2.3 (P03) — all shipped.

Milestone v0.3: Scheduling & Streaming Completion — COMPLETE

Scope: complete the two work items deferred from v0.2 that were not already shipped in P08-P10. A re-init SPECIFY codebase audit confirmed that REQ-014/027/028/029/031/037/039/040 all shipped in P08-P10 despite stale REQUIREMENTS.md marking them Pending. The remaining work is lean:

• Phase 0: Pre-execution (specify → clarify → research → plan → grill) — shipped v0.3.0
• Phase 1: iter.Seq streaming for --watch flags (REQ-022, REQ-030) — shipped v0.3.1
• Phase 2: orca doctor network + db full implementation (REQ-032 completion) — shipped v0.3.2
• Phase 3: Final review + ship + audit (milestone release) — shipped v0.3.3

Milestone tag: v0.4.0 (next-minor per feature-milestone promotion rule).

Per-phase tags: v0.3.0 (P0), v0.3.1 (P01), v0.3.2 (P02), v0.3.3 (P03 final = milestone release). Per .ciagent/RELEASE_POLICY.md, every phase tag produces a Gitea release.

Per-phase REQ coverage

• P01 — iter.Seq streaming for --watch flags

  • REQ-022 (iter.Seq for streaming job lists, Go 1.25+)
  • REQ-030 (--watch output format mode: table default vs streaming JSON per event)
  • Applies to both orca job list --watch and orca node list --watch (D-024, per ARCHITECTURE.md CLI layer + D-017)

• P02 — orca doctor network + db full implementation

  • REQ-032 (completion: network reachability via mTLS /healthz probe, db integrity via PRAGMA integrity_check + migration version)
  • Replaces NetworkStub and DBStub from v0.2 P01

v0.3 is a completion milestone, not a direction change

The vision ("minimalist, offline-first, CLI-first orchestration engine") is unchanged. v0.3 closes out the v0.2 deferrals and merges the accumulated v0.2 work to main.

Milestone v0.5: Distribution — COMPLETE

Scope: make Orca installable, distributable, and containerized. The engine functionality from v0.1–v0.3 is unchanged; this milestone is purely about delivery surface.

• Phase 0: Pre-execution (specify → clarify → research → plan) — shipped v0.4.1 (+ repo public)
• Phase 1: Namespace unification (ORCA_HOME + --system) (REQ-041, REQ-042) — shipped v0.4.2
• Phase 2: install.sh + in-place update + README quickstart (REQ-043, REQ-044) — shipped v0.4.3
• Phase 3: Docker release (Dockerfile + Gitea container registry) (REQ-046) — shipped v0.4.4
• Phase 4: Final review + ship + audit (milestone release) — shipped v0.4.5

Operational prerequisite (P0 ship): repo + org visibility flipped to public (REQ-045) — unauth releases API + asset download + docker pull all verified HTTP 200.

Milestone tag: v0.4.5 (final phase patch = milestone release per feature-milestone promotion rule). Per-phase tags: v0.4.1…v0.4.5.

Milestone v0.6: Node Bootstrap & Proxmox

Milestone v0.6: Node Bootstrap & Proxmox — COMPLETE

Scope: make orca init produce a fully working single-node cluster (CA + server cert + DB + localhost node registered with auto-detected OS), and add Proxmox 8 & 9 as a first-class remote node type joined over SSH with least-privilege role delegation.

• Phase 0: Pre-execution (specify → clarify → research → plan → grill) — tag v0.5.0
• Phase 1: orca init full bootstrap + localhost node + schema 0006 (REQ-047, REQ-048, REQ-049) — tag v0.5.1
• Phase 2: Proxmox SSH join + OrcaOperator role + sudoers allowlist (REQ-050, REQ-051) — tag v0.5.2
• Phase 3: doctor os + doctor proxmox SSH probe + audit logging (REQ-052) — tag v0.5.3
• Phase 4: Final review + ship + audit (milestone release) — tag v0.5.4

Milestone type: feature (P1/P2/P3 ship feat phases). Milestone tag: v0.5.4 (final phase patch = milestone release per feature-milestone promotion rule). Per-phase tags: v0.5.0…v0.5.4.

Tags run on the previous minor's patch line (v0.5.x) per branch-strategy.md. The milestone branch label uses the milestone number (milestone/v0.6-node-bootstrap-proxmox); no separate minor tag is created.

Milestone v0.7: Hardening & Completion — COMPLETE

Scope: NFR milestone closing gaps surfaced by the v0.7 IDEATE stage — an unreachable command tree, a missing config file layer, low test coverage in core packages, and the long-deferred pprof endpoint.

• Phase 0: Pre-execution (specify → clarify → research → ideate → plan) — tag v0.6.0 (shipped)
• Phase 1: Register orca cert command tree + cert_repo tests (REQ-053) — tag v0.6.1 (shipped)
• Phase 2: HCL config file parsing — internal/config package (REQ-054) — tag v0.6.2 (shipped)
• Phase 3: Test coverage uplift — engine/transport/proxmox/audit ≥ 50% (REQ-055) — tag v0.6.3 (shipped)
• Phase 4: --pprof opt-in on orca daemon (REQ-056) — tag v0.6.4 (shipped)
• Phase 5: Final review + ship + audit (milestone release) — tag v0.6.5 (shipped)

Milestone type: NFR (all phases are fix/test/chore; no feat phases). Milestone tag: v0.6.5 (final phase patch = milestone release per NFR-milestone progressive-patch rule). Per-phase tags: v0.6.0…v0.6.5. Tags run on the previous minor's patch line (v0.6.x) per branch-strategy.md. The milestone branch label uses the milestone number (milestone/v0.7-hardening-completion); no separate minor tag.

Milestone v0.8: Coverage & Trust Hardening — COMPLETE

Scope: continue the v0.7 hardening theme. v0.7 P03's ≥ 50% floor left six packages still under 50% (engine 8.3%, proxmox 5.1%, cli 27.6%, transport 26.3%, store 46.7%, jobspec 47.6%) and three packages with no tests at all (internal/audit, internal/certpaths, cmd/orca). v0.8 also closes the two SSH-trust "future enhancement" hooks deferred in v0.6 (D-035 --host-key-fingerprint pre-pin, RESEARCH_v0.6 §80 orca node key-reset) and adds a requirements-hygiene gate to prevent the stale-REQ-status drift seen after v0.7 ship.

• Phase 0: Pre-execution (specify → clarify → research → plan → grill) — tag v0.7.0 (shipped)
• Phase 1: Test coverage uplift round 2 — 6 packages to ≥ 70%, 3 zero-test packages to first tests (REQ-057) — tag v0.7.1 (shipped)
• Phase 2: SSH trust hardening — --host-key-fingerprint pre-pin + orca node key-reset + TOFU bugfix + HostKeyFingerprint population (REQ-058, REQ-059) — tag v0.7.2 (shipped)
• Phase 3: Requirements-hygiene gate — make verify-reqs + verify assertion (REQ-060) — tag v0.7.3 (shipped)
• Phase 4: Final review + ship + audit (milestone release) — tag v0.7.4 (shipped)

Milestone type: NFR (P01 test, P02 chore on trust surface per D-043, P03 chore, P04 docs/review). Final phase patch IS the milestone release per NFR-milestone progressive-patch rule. Per-phase tags: v0.7.0…v0.7.4. Tags run on the previous minor's patch line (v0.7.x) per branch-strategy.md. The milestone branch label uses the milestone number (milestone/v0.8-coverage-trust-hardening); no separate minor tag.

Per-phase REQ coverage

• P01 — Coverage uplift round 2

  • REQ-057 (raise internal/engine, internal/proxmox, internal/cli, internal/transport, internal/store, internal/jobspec to ≥ 70%; add first tests for internal/audit, internal/certpaths, cmd/orca)

• P02 — SSH trust hardening

  • REQ-058 (--host-key-fingerprint <sha256> pre-pin flag on orca node join --type proxmox; fail fast on mismatch; supersedes TOFU for pre-pinned deployments)
  • REQ-059 (orca node key-reset <node> clears persisted SSH host key so next doctor proxmox/dispatch re-pins via TOFU or --host-key-fingerprint)

• P03 — Requirements-hygiene gate

  • REQ-060 (make verify-reqs target + verify-stage assertion: every REQ Complete in ROADMAP.md has matching Complete row in REQUIREMENTS.md; enforced in CI validate pipeline)

v0.8 is a continuation milestone, not a direction change

The vision ("minimalist, offline-first, CLI-first orchestration engine") is unchanged. v0.8 closes the coverage debt left by v0.7's 50% floor and the trust-surface gaps explicitly deferred in v0.6.