coreci/orca
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 91 Wiki Activity
Files
cd07e435d936ecd9decc931b20f874f18d0fbafc
orca/.ciagent/REQUIREMENTS.md
T
Jon Chery 27f2abf8fb docs(P01): complete cert-register phase — shipped v0.6.1 
REQ-053 complete. Tag + merge + Gitea release succeeded.

---ci---
project: orca
phase: 1
milestone: v0.7
status: complete
requirements:
  covered: [REQ-053]
  partial: []
---/ci---
2026-08-04 00:05:45 +00:00

134 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.sh` 1-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 init` full 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 |
Reference in New Issue View Git Blame Copy Permalink