From bc7ce1caf672e87774455a6cd6cc0db986cd09b3 Mon Sep 17 00:00:00 2001 From: Jon Chery Date: Wed, 3 Jun 2026 12:07:28 +0000 Subject: [PATCH] docs(P00): clarify ambiguities (full autonomy, 10 decisions) ---ci--- project: orca phase: 0 milestone: v0.1 status: clarify decisions: - id: D-001 decision: Single binary distribution rationale: Simpler distribution; subcommands baked into one orca binary confidence: 0.95 - id: D-002 decision: modernc/sqlite for state store rationale: CGO-free, cross-compile friendly, single file confidence: 0.92 - id: D-003 decision: net/http for inter-node comms rationale: No external RPC framework for v0.1 confidence: 0.85 - id: D-004 decision: Single-node only for v0.1 rationale: Multi-node scheduling is out of scope confidence: 0.90 - id: D-005 decision: Human-readable default, --json for machine rationale: Serves both humans and AI agents confidence: 0.95 - id: D-006 decision: HCL/YAML job specs rationale: Familiar to Nomad users, simpler than JSON confidence: 0.88 - id: D-007 decision: mTLS for v0.1 rationale: Most secure default confidence: 0.80 - id: D-008 decision: Direct process execution (no containers) rationale: Avoids Docker dependency confidence: 0.85 - id: D-009 decision: ~/.orca/config.hcl and /etc/orca/orca.hcl rationale: XDG-style paths confidence: 0.90 - id: D-010 decision: Structured JSON via log/slog rationale: Native Go slog, no external dep confidence: 0.95 ---/ci--- --- .ciagent/PROJECT.md | 19 +++++++++++++++++++ .ciagent/REQUIREMENTS.md | 21 ++++++++++++++------- 2 files changed, 33 insertions(+), 7 deletions(-) diff --git a/.ciagent/PROJECT.md b/.ciagent/PROJECT.md index 07e9e3a..0f7f216 100644 --- a/.ciagent/PROJECT.md +++ b/.ciagent/PROJECT.md @@ -21,7 +21,26 @@ Build a lightweight system to manage and execute workloads across a set of nodes - Only CI system allowed: CoreCI (git.cloudinit.dev/coreci/coreci). - Gitea remote: git.cloudinit.dev/coreci/orca. +## Clarified Decisions (D-series, full autonomy) + +| ID | Question | Decision | Rationale | Confidence | +|----|----------|----------|-----------|------------| +| D-001 | Single binary or multi-binary distribution? | **Single binary** | Simpler distribution; subcommands baked into one `orca` binary. Aligns with simplicity pillar. | 0.95 | +| D-002 | Local state store technology? | **modernc/sqlite (pure Go, CGO-free)** | Cross-compile friendly, no CGO dependency, single file on disk, mature. | 0.92 | +| D-003 | Inter-node communication? | **Embedded HTTP (net/http) over loopback, mTLS for cross-node** | No external RPC framework needed for v0.1. HTTP suffices. | 0.85 | +| D-004 | Scheduling algorithm for v0.1? | **Single-node only (no scheduling)** | Multi-node scheduling is out of scope for v0.1. Tasks run on the node they're submitted to. | 0.90 | +| D-005 | CLI output format? | **Human-readable by default, `--json` flag for machine consumption** | Serves both humans and AI agents. | 0.95 | +| D-006 | Job/task definition format? | **HCL or YAML in `.hcl`/`.yaml` files** | Familiar to Nomad/HashiCorp users; simpler than JSON for humans. | 0.88 | +| D-007 | Authentication? | **mTLS for v0.1, token-based deferred** | mTLS is the most secure default. Tokens can be added later if needed. | 0.80 | +| D-008 | Container runtime? | **Direct process execution (no container runtime) for v0.1** | Avoids the Docker/container dependency. Pure process management. | 0.85 | +| D-009 | Configuration file location? | **`~/.orca/config.hcl` and `/etc/orca/orca.hcl`** | Standard XDG-style paths. | 0.90 | +| D-010 | Logging format? | **Structured JSON via `log/slog`** | Native Go 1.21+ slog, no external dependency. | 0.95 | + ## Out of Scope - Full-blown Kubernetes-compatible API. - Complex cloud-provider integrations. - GUI-based management consoles. +- Multi-node scheduling. +- Container runtime integration. +- Service mesh / sidecar injection. +- Auto-scaling / horizontal pod autoscaler. diff --git a/.ciagent/REQUIREMENTS.md b/.ciagent/REQUIREMENTS.md index f154ea7..e2216f3 100644 --- a/.ciagent/REQUIREMENTS.md +++ b/.ciagent/REQUIREMENTS.md @@ -1,12 +1,19 @@ # Requirements: Orca ## Milestone v0.1: Foundation + | ID | Requirement | Priority | Status | |----|-------------|----------|--------| -| REQ-001 | Go 1.25+ Toolchain Support | High | Pending | -| REQ-002 | CLI-first interface for all operations | High | Pending | -| REQ-003 | Offline-first operational mode | High | Pending | -| REQ-004 | Basic task deployment (single node) | Medium | Pending | -| REQ-005 | Local state storage without external DB | Medium | Pending | -| REQ-006 | Security-first audit logging | High | Pending | -| REQ-007 | CoreCI full release flow integration | High | Pending | +| REQ-001 | Go 1.25+ toolchain support | High | Pending | +| REQ-002 | CLI-first interface for all operations (single binary) | High | Pending | +| REQ-003 | Offline-first operational mode (no cloud deps) | High | Pending | +| REQ-004 | Basic task deployment (single-node process execution) | Medium | Pending | +| REQ-005 | Local state storage via modernc/sqlite (CGO-free) | Medium | Pending | +| REQ-006 | Security-first audit logging via `log/slog` | High | Pending | +| REQ-007 | CoreCI full release flow integration via `.coreci.yml` | High | Pending | +| REQ-008 | Structured JSON logging (slog) | High | Pending | +| REQ-009 | HCL/YAML job spec parsing | Medium | Pending | +| REQ-010 | `--json` output flag for machine consumption | High | Pending | +| REQ-011 | mTLS for inter-node communication | Medium | Deferred (v0.2) | +| REQ-012 | `~/.orca/config.hcl` and `/etc/orca/orca.hcl` config locations | Low | Pending | +| REQ-013 | Pre-push git hook triggers CoreCI on every push | High | Pending |