coreci/orca
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 91 Wiki Activity

docs(audit): fix .ciagent/ file discipline findings from v0.2 P01 audit

Browse Source 
CIAgent audit (.ciagent/AUDIT_v0.2_P01.md) surfaced 3 .ciagent/ file
discipline issues. This commit addresses all 3:

1. config.json: re-add the 'workflow' top-level block. It was added in
   d10f89d (v0.1 milestone) and lost from main during the parallel-
   history resolution that produced origin/main's be9afa2 PR-#1 merge.
   The 4 standing rules (no_hitl, release_flow_per_phase, merge_strategy,
   branching) are restored.

2. PROJECT.md: add literal '## What This Is' and '## Key Decisions'
   section headers. The v0.1 audit-fix (f1c55ca) added the content
   inline but without the explicit headers, so the audit check missed
   them. The Key Decisions section summarizes D-011..D-018.

3. REQUIREMENTS.md: consolidate two overlapping REQ tables (the v0.1
   status table and the v0.2 traceability table) into a single
   canonical table covering all 40 REQs (REQ-001..REQ-040). Each row
   has REQ-ID, summary, priority, phase, status. v0.1 REQs show
   'Complete'; v0.2 REQs show 'Complete' (P01 shipped) or 'Pending
   (P##)'. The v0.1 Milestone Summary and v0.2 Milestone Summary
   sections are preserved below the table.

4. AUDIT_v0.2_P01.md: the audit report itself, with reconstruction
   state, file discipline table, branch hygiene, commit discipline,
   and the 3 findings above (plus non-blocking observations). The
   report's verdict: 'v0.2 P01 ship is healthy; 3 issues are
   paper-cleanup items addressed in this commit. None block P02
   EXECUTE.'

---ci---
project: orca
phase: 0
milestone: v0.2
status: fix
---/ci---
This commit is contained in:
ciagent
2026-06-03 22:19:45 +00:00
parent f31bed2dc3
commit f503404dda
4 changed files with 218 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.ciagent/REQUIREMENTS.md
+64 -70
View File
@@ -1,80 +1,74 @@
# Requirements: Orca
## Milestone v0.1: Foundation
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 | Status |
|----|-------------|----------|--------|
| REQ-001 | Go 1.25+ toolchain support | High | **Complete** |
| REQ-002 | CLI-first interface for all operations (single binary) | High | **Complete** |
| REQ-003 | Offline-first operational mode (no cloud deps) | High | **Complete** |
| REQ-004 | Basic task deployment (single-node process execution) | Medium | **Complete** |
| REQ-005 | Local state storage via modernc/sqlite (CGO-free) | Medium | **Complete** |
| REQ-006 | Security-first audit logging via `log/slog` | High | **Complete** |
| REQ-007 | CoreCI full release flow integration via `.coreci.yml` | High | **Complete** |
| REQ-008 | Structured JSON logging (slog) | High | **Complete** |
| REQ-009 | HCL/YAML job spec parsing | Medium | **Complete** |
| REQ-010 | `--json` output flag for machine consumption | High | **Complete** |
| REQ-011 | mTLS for inter-node communication | Medium | Pending (v0.2 P01) |
| REQ-012 | `~/.orca/config.hcl` and `/etc/orca/orca.hcl` config locations | Low | **Complete** (CLI uses ~/.orca/ + ORCA_DB env) |
| REQ-013 | Pre-push git hook triggers CoreCI on every push | High | **Complete** |
| REQ-014 | `gosec` + `govulncheck` in CI pipeline | High | Pending (v0.2 P03) |
| REQ-015 | MIT LICENSE | Low | **Complete** |
| REQ-016 | README.md with quickstart | Medium | **Complete** |
| REQ-017 | `context.Context` propagation in all I/O | High | **Complete** |
| REQ-018 | Error wrapping with `fmt.Errorf("...: %w", err)` | High | **Complete** |
| REQ-019 | Cobra CLI framework | High | **Complete** |
| REQ-020 | HCL parser integration (`hashicorp/hcl`) | Medium | **Complete** |
| REQ-021 | `os/exec` with `WaitDelay` (Go 1.25+) | Medium | **Complete** |
| REQ-022 | `iter.Seq` for streaming job lists (Go 1.25+) | Low | Pending (v0.2 P04) |
| REQ-023 | Self-signed mTLS cert generation | Medium | Pending (v0.2 P01, paired with REQ-011) |
| REQ-024 | `Makefile` with standard targets | High | **Complete** |
## Milestone v0.1: Summary
**Status: Complete** — all 6 phases shipped (P00–P06), 4-layer verification passed at every phase, tagged `v0.2.0` for next-minor promotion per `run.md` versioning logic.
**Coverage**: 21/24 requirements complete; 4 deferred to v0.2 (REQ-011, REQ-014, REQ-022, REQ-023) — all paired with multi-node networking, richer I/O scanning, or streaming I/O which are explicitly out of scope for v0.1.
## Milestone v0.2: Networking, Observability, Security Hardening
**Status: In Progress** — IDEATE stage complete on `main`. 4 phases (P01–P04) covering mTLS, multi-node scheduling, security scanning, and streaming I/O.
### v0.2 requirements (carried over from v0.1 deferral)
| ID | Requirement | Priority | Phase | Source |
| ID | Requirement | Priority | Phase | Status |
|----|-------------|----------|-------|--------|
| REQ-011 | mTLS for inter-node communication | Medium | P01 | v0.1 deferral |
| REQ-014 | `gosec` + `govulncheck` in CI pipeline | High | P03 | v0.1 deferral |
| REQ-022 | `iter.Seq` for streaming job lists (Go 1.25+) | Low | P04 | v0.1 deferral |
| REQ-023 | Self-signed mTLS cert generation | Medium | P01 (paired with REQ-011) | v0.1 deferral |
| 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 | Pending (P03) |
| 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.2 P04 | Pending (P04) |
| 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 | Pending (P03) |
| REQ-028 | HCL/YAML schema for `NodeCapacity` declaration (`orca node join` flag and/or `~/.orca/node.hcl`) | High | v0.2 P02 | Pending (P02) |
| REQ-029 | `gitleaks` baseline file committed to repo to suppress pre-existing `.env` SHA-1 leak in git history | Medium | v0.2 P03 | Pending (P03) |
| REQ-030 | `--watch` output format mode: table (default) vs streaming one-line JSON per event | Low | v0.2 P04 | Pending (P04) |
| REQ-031 | `go test -race` enabled in CI for all v0.2 packages | High | v0.2 P01–P04 | **Complete** for P01 (cross-cutting, verified P01); P02–P04 ongoing |
| REQ-032 | `orca doctor` subcommand for diagnostics (CA/cert health, db integrity, peer reachability) | Medium | **v0.2 P01** | **Complete** for cert checks (P01); network/db are stubs, full impl in P02 |
| 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 | Pending (P02) |
| 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 | Pending (P03) |
| REQ-040 | `.golangci.yml` unified lint config superseding per-tool invocations | Low | v0.2 P03 | Pending (P03) |
### v0.2 requirements (added by IDEATE stage, commit pending)
## v0.1 Milestone Summary
| ID | Requirement | Priority | Phase | Source idea |
|----|-------------|----------|-------|-------------|
| REQ-025 | Bounded cert rotation history: retain last N=3 server certs per node for rollback | Medium | P01 | I-201 (REQ-cand-A) |
| REQ-026 | Trusted-CA fingerprint pinned in config; daemon refuses to start on mismatch | High | P01 | I-202 (REQ-cand-B) |
| REQ-027 | `govulncheck` runs in offline mode in CI (no `vuln.go.dev` calls; pre-mirrored DB or `-format json` + `jq` gate) | High | P03 | I-101 (REQ-cand-C) |
| REQ-028 | HCL/YAML schema for `NodeCapacity` declaration (`orca node join` flag and/or `~/.orca/node.hcl`) | High | P02 | I-203 (REQ-cand-D) |
| REQ-029 | `gitleaks` baseline file committed to repo to suppress pre-existing `.env` SHA-1 leak in git history | Medium | P03 | I-102 (REQ-cand-E) |
| REQ-030 | `--watch` output format mode: table (default) vs streaming one-line JSON per event | Low | P04 | I-204 (REQ-cand-F) |
| REQ-031 | `go test -race` enabled in CI for all v0.2 packages | High | P01–P04 (cross-cutting) | I-103 |
| REQ-032 | `orca doctor` subcommand for diagnostics (CA/cert health, db integrity, peer reachability) | Medium | P01 (initial) | I-301 |
| REQ-033 | Cert file mode enforcement: 0600 for keys, 0644 for certs (refuses to start on violation) | High | P01 | I-104 |
| REQ-034 | Cert proactive rotation alarm: structured slog WARN 30 days before `not_after` | Medium | P01 | I-205 |
| REQ-035 | `orca cert show` redacts private key material from default and `--json` output | High | P01 | I-105 |
| REQ-036 | Server cert SAN validation: SAN entries (DNS + IP) populated at sign-time; refuses to sign a CSR without them | High | P01 | I-106 |
| REQ-037 | `X-Orca-Idempotency-Key` header on cross-node POST; dispatcher retries only when header is present | Medium | P02 | I-206 |
| REQ-038 | Structured slog fields for mTLS failures: `event=mtls.handshake`, `peer`, `cert_fp`, `err` | Medium | P01 | I-302 |
| REQ-039 | `.gitleaks.toml` extended with stopwords for test data paths and CA cert PEM blocks | Medium | P03 | I-303 |
| REQ-040 | `.golangci.yml` unified lint config superseding per-tool invocations | Low | P03 | I-304 |
**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).
### v0.2 totals
**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.
- 4 carried over from v0.1 (REQ-011, REQ-014, REQ-022, REQ-023)
- 16 net-new from IDEATE (REQ-025..REQ-040)
- **20 total v0.2 requirements**
## v0.2 Milestone Summary
### v0.2 deferred to v0.3
**Status: In Progress** — P01 (mTLS) shipped (v0.2.1). 3 phases remain
(P02 multi-node scheduling, P03 gosec+govulncheck+gitleaks, P04 iter.Seq).
P01 covered REQ-011, REQ-023, REQ-025, REQ-026, REQ-031, REQ-032 (partial),
REQ-033, REQ-034, REQ-035, REQ-036, REQ-038 (10 REQs complete; REQ-032
complete for cert checks only).
- 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.
## Deferred to v0.3
- 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.