Jon Chery
27f2abf8fb
REQ-053 complete. Tag + merge + Gitea release succeeded. ---ci--- project: orca phase: 1 milestone: v0.7 status: complete requirements: covered: [REQ-053] partial: [] ---/ci---
12 KiB
12 KiB
Requirements: Orca
The canonical requirements table. Each row carries the REQ-ID, the milestone it belongs to, the requirement summary, priority, the phase that addresses it, and the current status. This single table is the source of truth — superseded any per-milestone status tables in earlier versions of this file.
| ID | Requirement | Priority | Phase | Status |
|---|---|---|---|---|
| REQ-001 | Go 1.25+ toolchain support | High | v0.1 P01 | Complete |
| REQ-002 | CLI-first interface for all operations (single binary) | High | v0.1 P01 | Complete |
| REQ-003 | Offline-first operational mode (no cloud deps) | High | v0.1 | Complete |
| REQ-004 | Basic task deployment (single-node process execution) | Medium | v0.1 P03 | Complete (single-node); multi-node dispatch in v0.2 P02 |
| REQ-005 | Local state storage via modernc/sqlite (CGO-free) | Medium | v0.1 P02 | Complete |
| REQ-006 | Security-first audit logging via log/slog |
High | v0.1 P04 | Complete |
| REQ-007 | CoreCI full release flow integration via .coreci.yml |
High | v0.1 P06 | Complete (per-phase releases) |
| REQ-008 | Structured JSON logging (slog) | High | v0.1 P05 | Complete |
| REQ-009 | HCL/YAML job spec parsing | Medium | v0.1 P03 | Complete |
| REQ-010 | --json output flag for machine consumption |
High | v0.1 P01 | Complete |
| REQ-011 | mTLS for inter-node communication | Medium | v0.2 P01 | Complete (P01 shipped v0.2.1) |
| REQ-012 | ~/.orca/config.hcl and /etc/orca/orca.hcl config locations |
Low | v0.1 P01 | Complete (CLI uses ~/.orca/ + ORCA_DB env) |
| REQ-013 | Pre-push git hook triggers CoreCI on every push | High | v0.1 P01 | Complete |
| REQ-014 | gosec + govulncheck in CI pipeline |
High | v0.2 P03 | Complete (P10 shipped v0.2.3) |
| REQ-015 | MIT LICENSE | Low | v0.1 P01 | Complete |
| REQ-016 | README.md with quickstart | Medium | v0.1 P01 | Complete |
| REQ-017 | context.Context propagation in all I/O |
High | v0.1 | Complete |
| REQ-018 | Error wrapping with fmt.Errorf("...: %w", err) |
High | v0.1 | Complete |
| REQ-019 | Cobra CLI framework | High | v0.1 P01 | Complete |
| REQ-020 | HCL parser integration (hashicorp/hcl) |
Medium | v0.1 P03 | Complete |
| REQ-021 | os/exec with WaitDelay (Go 1.25+) |
Medium | v0.1 P03 | Complete |
| REQ-022 | iter.Seq for streaming job lists (Go 1.25+) |
Low | v0.3 P01 | Complete (v0.3 P01 shipped v0.3.1) |
| REQ-023 | Self-signed mTLS cert generation | Medium | v0.2 P01 | Complete (P01 shipped v0.2.1) |
| REQ-024 | Makefile with standard targets |
High | v0.1 P01 | Complete |
| REQ-025 | Bounded cert rotation history: retain last N=3 server certs per node for rollback | Medium | v0.2 P01 | Complete (P01 shipped v0.2.1) |
| REQ-026 | Trusted-CA fingerprint pinned in config; daemon refuses to start on mismatch | High | v0.2 P01 | Complete (P01 shipped v0.2.1) |
| REQ-027 | govulncheck runs in offline mode in CI (no vuln.go.dev calls; pre-mirrored DB or -format json + jq gate) |
High | v0.2 P03 | Complete (P10 shipped v0.2.3) |
| REQ-028 | HCL/YAML schema for NodeCapacity declaration (orca node join flag and/or ~/.orca/node.hcl) |
High | v0.2 P02 | Complete (P09 shipped v0.2.2; orca node capacity CLI) |
| REQ-029 | gitleaks baseline file committed to repo to suppress pre-existing .env SHA-1 leak in git history |
Medium | v0.2 P03 | Complete (P10 shipped v0.2.3) |
| REQ-030 | --watch output format mode: table (default) vs streaming one-line JSON per event |
Low | v0.3 P01 | Complete (v0.3 P01 shipped v0.3.1) |
| REQ-031 | go test -race enabled in CI for all v0.2 packages |
High | v0.2 P01–P04 | Complete (P10; .coreci.yml test pipeline runs -race) |
| REQ-032 | orca doctor subcommand for diagnostics (CA/cert health, db integrity, peer reachability) |
Medium | v0.2 P01 / v0.3 P02 | Complete (cert checks P01 v0.2.1; network + db P02 v0.3.2) |
| REQ-033 | Cert file mode enforcement: 0600 for keys, 0644 for certs (refuses to start on violation) | High | v0.2 P01 | Complete (P01 shipped v0.2.1) |
| REQ-034 | Cert proactive rotation alarm: structured slog WARN 30 days before not_after |
Medium | v0.2 P01 | Complete (P01 shipped v0.2.1) |
| REQ-035 | orca cert show redacts private key material from default and --json output |
High | v0.2 P01 | Complete (P01 shipped v0.2.1) |
| REQ-036 | Server cert SAN validation: SAN entries (DNS + IP) populated at sign-time; refuses to sign a CSR without them | High | v0.2 P01 | Complete (P01 shipped v0.2.1) |
| REQ-037 | X-Orca-Idempotency-Key header on cross-node POST; dispatcher retries only when header is present |
Medium | v0.2 P02 | Complete (P09 shipped v0.2.2; internal/transport/idempotency.go) |
| REQ-038 | Structured slog fields for mTLS failures: event=mtls.handshake, peer, cert_fp, err |
Medium | v0.2 P01 | Complete (P01 shipped v0.2.1) |
| REQ-039 | .gitleaks.toml extended with stopwords for test data paths and CA cert PEM blocks |
Medium | v0.2 P03 | Complete (P10 shipped v0.2.3) |
| REQ-040 | .golangci.yml unified lint config superseding per-tool invocations |
Low | v0.2 P03 | Complete (P10 shipped v0.2.3) |
| REQ-041 | Unified namespace root via ORCA_HOME for all components (db, certs, init, daemon) |
High | v0.5 P1 | Complete (P1 shipped v0.4.2) |
| REQ-042 | --system flag selects system-level namespace root /root/.orca |
High | v0.5 P1 | Complete (P1 shipped v0.4.2) |
| REQ-043 | install.sh 1-liner pulling release binary from public Gitea URL; user-level default, --system for system-level |
High | v0.5 P2 | Complete (P2 shipped v0.4.3) |
| REQ-044 | install.sh in-place update preserves config/state; idempotent re-run |
High | v0.5 P2 | Complete (P2 shipped v0.4.3) |
| REQ-045 | Gitea repo + releases publicly accessible (unauthenticated download) | High | v0.5 P0 | Complete (P0 ship: repo + org visibility public) |
| REQ-046 | Docker image published to Gitea container registry per release | Medium | v0.5 P3 | Complete (P3 shipped v0.4.4) |
v0.1 Milestone Summary
Status: Complete — all 6 phases shipped (P00–P06) plus P07 backfill,
4-layer verification passed at every phase, tagged v0.2.0 per
run.md versioning logic (next-minor after all feature-patches
v0.1.1..v0.1.7 ship).
Coverage: 21/24 v0.1-declared requirements complete by v0.1 ship; the 3 deferred (REQ-011, REQ-014, REQ-022, REQ-023) all moved to v0.2. Plus REQ-025..REQ-040 (16 net-new) added by v0.2 IDEATE stage.
v0.2 Milestone Summary
Status: Functionally Complete (pending merge to main) — P08 (mTLS),
P09 (scheduling), P10 (security scan) all shipped to the
milestone/v0.2-networking-observability-security branch as v0.2.1,
v0.2.2, v0.2.3. The milestone branch has NOT been merged to main yet.
REQ-022/030 (iter.Seq streaming) and REQ-032 (doctor network/db) were
deferred to v0.3.
v0.3 Milestone Summary
Status: Complete — P01 (iter.Seq streaming, v0.3.1) and P02 (doctor network+db, v0.3.2) both shipped. REQ-022, REQ-030, REQ-032 all complete. Re-init SPECIFY audit confirmed all other v0.2-deferred REQs (014, 027, 028, 029, 031, 037, 039, 040) already shipped in P08-P10.
Deferred to v0.4
- pprof endpoint on
orca daemon(idea I-308, 0.70 confidence): deferred to keep v0.2 lean; revisit in v0.3 once P02's dispatcher is stable.
v0.5 Milestone Summary
Status: Complete — all 3 execution phases + final review shipped. P0 (v0.4.1), P1 (v0.4.2), P2 (v0.4.3), P3 (v0.4.4), P4 final (v0.4.5). REQ-041..046 all complete. Repo + releases publicly accessible (REQ-045). Docker image published to Gitea container registry (REQ-046).
- P0 (v0.4.1): pre-execution + repo visibility flipped to public (REQ-045).
- P1 (v0.4.2): namespace unification —
ORCA_HOME+--system(REQ-041/042). - P2 (v0.4.3):
install.sh1-liner + in-place update (REQ-043/044) + README quickstart (REQ-016). - P3 (v0.4.4): Docker release — distroless image + Gitea container registry (REQ-046).
- P4 (v0.4.5): final review + audit + milestone release.
v0.6 Requirements — Node Bootstrap & Proxmox
| ID | Requirement | Priority | Phase | Status |
|---|---|---|---|---|
| REQ-047 | orca init auto-provisions CA + server cert + DB migrations + localhost node (idempotent; safe re-run) |
High | v0.6 P1 | Complete (P1 shipped v0.5.1) |
| REQ-048 | orca init registers a default localhost node with auto-detected OS via /etc/os-release ID |
High | v0.6 P1 | Complete (P1 shipped v0.5.1) |
| REQ-049 | Node schema extension: nodes.kind (localhost|linux|proxmox) + nodes.os columns (migration 0006, backward-compatible) |
High | v0.6 P1 | Complete (P1 shipped v0.5.1) |
| REQ-050 | orca node join --type proxmox SSH bootstrap via golang.org/x/crypto/ssh (new direct dep); password auth, deploy orca pubkey, create orca user (config-overridable), assign PVE role, drop sudoers allowlist; idempotent |
High | v0.6 P2 | Complete (P2 shipped v0.5.2) |
| REQ-051 | Proxmox least-privilege OrcaOperator PVE role (VM.Audit, Datastore.AllocateSpace, SDN.Use) + orca user + /etc/sudoers.d/orca allowlist (pct, qm, pvesh, apt-get, dpkg); config-overridable user/role names |
High | v0.6 P2 | Complete (P2 shipped v0.5.2; refined: pvesh excluded per AD-020, orca@pam per AD-019) |
| REQ-052 | orca doctor extensions: doctor os (verify localhost OS detection matches stored node row) + doctor proxmox (SSH-probe each kind=proxmox node with pveversion/pvecmd status, 3s timeout, PASS/WARN/FAIL); audit log all bootstrap + join actions |
Medium | v0.6 P3 | Complete (P3 shipped v0.5.3) |
v0.6 Milestone Summary
Status: Complete — all 3 execution phases + final review shipped. P0 (v0.5.0), P1 (v0.5.1), P2 (v0.5.2), P3 (v0.5.3), P4 final (v0.5.4). REQ-047..052 all complete.
- P0 (v0.5.0): pre-execution (specify → clarify → research → plan). 8 decisions (D-030..D-037).
- P1 (v0.5.1):
orca initfull bootstrap + schema 0006 (REQ-047/048/049). - P2 (v0.5.2): Proxmox SSH join + OrcaOperator role + sudoers (REQ-050/051).
- P3 (v0.5.3):
doctor os+doctor proxmox+ audit logging (REQ-052). - P4 (v0.5.4): final review + audit + milestone release.
v0.7 Requirements — Hardening & Completion
| ID | Requirement | Priority | Phase | Status |
|---|---|---|---|---|
| REQ-053 | orca cert command tree registered on root command (cert ca-init, cert gen, cert show, cert renew, cert fingerprint) — code exists in internal/cli/cert.go but is never AddCommand'd; unreachable today |
High | v0.7 P1 | Complete (P1 shipped v0.6.1) |
| REQ-054 | HCL config file parsing: internal/config package loads ~/.orca/config.hcl / /etc/orca/orca.hcl (keys: db_path, listen_addr, ca_path, server_cert_path, server_key_path, node_capacity); merge precedence flag > env > file > default; --config flag on root command |
High | v0.7 P2 | Pending |
| REQ-055 | Test coverage uplift: every package ≥ 50% — adds tests for internal/engine (executor, dispatcher, peer), internal/transport (mtls, dispatch, handshake_log), internal/proxmox (bootstrap SSH path), internal/audit |
Medium | v0.7 P3 | Pending |
| REQ-056 | --pprof <addr> opt-in flag on orca daemon (default disabled); net/http/pprof mounted on a separate mux, never on the mTLS daemon listener |
Low | v0.7 P4 | Pending |