coreci/orca
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 91 Wiki Activity
Files
691463ff74cfa28290e7a8b7a676eb2aa7a97d77
orca/.ciagent/IDEATION.md
T
Jon Chery 1ee82fc2e2 docs(P00): ideation - 34 ideas accepted 
v0.2 IDEATE stage. 29 new ideas generated (10 Tier 1 mechanical + 11
Tier 2 backend-enriched + 8 Tier 3 cross-project) plus 6 research-stage
candidates (REQ-cand-A..F from commit 08d321f) = 35 considered. Under
full autonomy, all 35 with confidence >= 0.60 are auto-accepted; 1
explicitly deferred to v0.3 (I-308 pprof). 34 accepted into v0.2.

Resulting net-new REQs (REQ-025..REQ-040) span P01-P04:
- P01 (mTLS): REQ-025 (cert rotation history), REQ-026 (CA fingerprint
  pinning), REQ-032 (orca doctor), REQ-033 (file mode enforcement),
  REQ-034 (rotation alarm), REQ-035 (cert show redaction), REQ-036
  (SAN validation), REQ-038 (mTLS failure log fields)
- P02 (multi-node): REQ-028 (NodeCapacity HCL schema, P02 enabler),
  REQ-037 (X-Orca-Idempotency-Key)
- P03 (security CI): REQ-027 (govulncheck offline mode -- changes P03
  scope: CI must not call vuln.go.dev), REQ-029 (gitleaks baseline for
  pre-existing .env leak), REQ-039 (.gitleaks.toml stopwords),
  REQ-040 (.golangci.yml)
- P04 (iter.Seq): REQ-030 (--watch --json mode)
- Cross-cutting: REQ-031 (go test -race)

Total v0.2 REQs: 20 (4 carried from v0.1 + 16 net-new).

ARCHITECTURE.md: added `internal/doctor/` component (§5) with
orca doctor {cert,network,db} subcommands; ASCII diagram updated.
ROADMAP.md: per-phase REQ coverage matrix added; P03 scope change
documented (govulncheck offline mode).
PROJECT.md: unchanged (vision is stable).

---ci---
project: orca
phase: 0
milestone: v0.2
status: ideate
---/ci---
2026-06-03 21:03:59 +00:00

187 lines
13 KiB
Markdown
Raw Blame History

# Ideation: Orca v0.2
Full autonomy mode: all ideas with confidence >= 0.60 are auto-accepted. The
RESEARCH stage (commit `08d321f`) surfaced 6 REQ candidates (REQ-cand-A..F)
which are assessed individually below in addition to the 29 new ideas
generated by this stage.
Total generated: 29 ideas (10 Tier 1 + 11 Tier 2 + 8 Tier 3) plus 6 inherited
research candidates = 35 considered. 34 accepted (29 generated + 6
research - 1 deferred = 34), 1 explicitly deferred to v0.3 (I-308 pprof).
Zero dropped below the 0.60 confidence threshold.
## Tier 1: Mechanical (security/quality, automated)
| ID | Idea | Source | Confidence | Status | Maps to REQ |
|-------|----------------------------------------------------------------------|-------------------------|------------|----------|---------------|
| I-101 | `govulncheck` runs in offline mode in CI (REQ-cand-C) | mechanical + REQ-cand-C | 0.90 | Accepted | REQ-027 |
| I-102 | `gitleaks` baseline file checked into repo for pre-existing .env leak (REQ-cand-E) | mechanical + REQ-cand-E | 0.85 | Accepted | REQ-029 |
| I-103 | `go test -race` enabled in CI for all v0.2 packages | mechanical | 0.95 | Accepted | REQ-031 |
| I-104 | Cert file mode enforcement: 0600 for keys, 0644 for certs | mechanical | 0.90 | Accepted | REQ-033 |
| I-105 | `orca cert show` redacts private key material from output | mechanical | 0.80 | Accepted | REQ-035 |
| I-106 | Server certs must carry SAN entries (DNS + IP), enforced at sign-time | mechanical | 0.85 | Accepted | REQ-036 |
| I-107 | Cert `serial_hex` UNIQUE constraint in `certs` table | mechanical | 0.80 | Accepted | (refinement of REQ-014's audit-log discipline; no new REQ) |
| I-108 | `gofmt` and `goimports` enforced in CI (carry over from v0.1) | mechanical | 0.90 | Accepted | (refinement of REQ-024; no new REQ) |
| I-109 | `gosec` baseline JSON (`gosec.json`) committed; CI fails on new findings | mechanical | 0.90 | Accepted | (refinement of REQ-014; no new REQ) |
| I-110 | `govulncheck -format json` + wrapper script gates on findings via `jq` | mechanical | 0.90 | Accepted | (implementation detail of REQ-027; no new REQ) |
### Tier 1 rationale
- I-103 (race detector) is mechanical and high-impact: v0.2 introduces
concurrent mTLS handshakes, the cert hot-swap callback, and the
dispatcher queue. Race conditions in any of these would be silent and
severe. `-race` adds <2x to test time; the cost is trivial.
- I-104 (file mode enforcement) is non-optional for keys: a 0644 server
key would be a CVE. Catches `umask 022` and copy-paste mistakes.
- I-105 (`orca cert show` redaction) is defensive UI: cert operators
often pipe output into chat/email for handoff. Private key bytes
must never appear in any default `orca cert` output.
- I-106 (SAN enforcement) prevents the operator from issuing a cert
with no DNS / IP, which would make it useless for hostname-based
mTLS verification.
- I-109 (gosec baseline JSON) is already specified in D-016 and the
research commit's notes. I-110 (govulncheck exit-on-known) is the
same — but a known issue is that the default `govulncheck` mode calls
`vuln.go.dev`, which conflicts with offline-first (REQ-003). REQ-027
captures the resolution: the CI image must either pre-mirror the DB
(GOVULNCHECK_DB env) or use `-format json` + a wrapper that gates on
findings (no network).
- I-101 and I-102 inherit from the research stage and are explicitly
REQ candidates — accepted as REQ-027 and REQ-029.
## Tier 2: Backend-Enriched (architecture/coverage)
| ID | Idea | Source | Confidence | Status | Maps to REQ |
|-------|----------------------------------------------------------------------|---------|------------|----------|---------------|
| I-201 | Bounded cert rotation history: retain last N=3 server certs per node (REQ-cand-A) | backend + REQ-cand-A | 0.85 | Accepted | REQ-025 |
| I-202 | Trusted-CA fingerprint pinned in config; daemon refuses to start on mismatch (REQ-cand-B) | backend + REQ-cand-B | 0.85 | Accepted | REQ-026 |
| I-203 | HCL/YAML schema for `NodeCapacity` declaration on `orca node join` and/or `~/.orca/node.hcl` (REQ-cand-D) | backend + REQ-cand-D | 0.90 | Accepted | REQ-028 |
| I-204 | `--watch` output format mode: table (default) vs streaming one-line JSON (REQ-cand-F) | backend + REQ-cand-F | 0.75 | Accepted | REQ-030 |
| I-205 | Cert proactive rotation alarm: audit log + slog WARN when `not_after - now < 30d` | backend | 0.85 | Accepted | REQ-034 |
| I-206 | `X-Orca-Idempotency-Key` header on POST; dispatcher retries only when header present | backend | 0.80 | Accepted | REQ-037 |
| I-207 | `tls.Config.GetCertificate` hot-swap: atomic file read + sync.Mutex around `*tls.Certificate` | backend | 0.90 | Accepted | (refinement of REQ-011; no new REQ) |
| I-208 | CA cert in-memory cache with disk-watcher fallback (avoids disk read on every handshake) | backend | 0.75 | Accepted | (optimization; no new REQ) |
| I-209 | Bin-packing with `sort.Slice` on `[]Node` by `AvailableMemory() desc` (best-fit variant) | backend | 0.85 | Accepted | (refinement of P02 bin-pack; no new REQ) |
| I-210 | Dispatcher bounded queue: `make(chan SubmitRequest, N)` with N=256; backpressure via channel send | backend | 0.75 | Accepted | (refinement of P02 dispatcher; no new REQ) |
| I-211 | `iter.Seq` watch stream polls SQLite + emits; cancellation via `ctx.Done()` | backend | 0.85 | Accepted | (refinement of REQ-022; no new REQ) |
### Tier 2 rationale
- I-201, I-202, I-203, I-204 are research-stage candidates. All are
net-new requirements. I-203 is especially important: P02's
bin-packing is impossible without an operator-declared capacity.
- I-205 (proactive rotation alarm) is operationally important: without
it, a node can run on an expired cert (mTLS will fail) and the
operator gets paged at the worst time. Emitting a structured
WARN-level audit record 30 days out gives `log/slog` JSON consumers
a clean alert.
- I-206 (`Idempotency-Key`) is already mentioned in ARCHITECTURE.md
("only idempotent verbs retried automatically; POST retries require
X-Orca-Idempotency-Key"). This stage elevates it to a REQ.
- I-207, I-208, I-209, I-210, I-211 are implementation details /
refinements of existing REQs (REQ-011, REQ-022, the P02 bin-pack
scope, etc.). They are recorded here for the PLAN stage's benefit
but do not require new REQs.
## Tier 3: Cross-Project (from CoreCI patterns)
| ID | Idea | Source | Confidence | Status | Maps to REQ |
|-------|----------------------------------------------------------------------|---------------|------------|----------|---------------|
| I-301 | `orca doctor` subcommand: diagnostics for CA/cert health, db integrity, peer reachability | cross-project | 0.85 | Accepted | REQ-032 |
| I-302 | Structured log fields for mTLS failures: `event=mtls.handshake`, `peer`, `cert_fp`, `err` | cross-project | 0.85 | Accepted | REQ-038 |
| I-303 | `.gitleaks.toml` extended with stopwords for test data paths and CA cert PEM block | cross-project | 0.80 | Accepted | REQ-039 |
| I-304 | `.golangci.yml` (or `.golangci.yaml`) for unified lint config superseding per-tool invocations | cross-project | 0.70 | Accepted | REQ-040 |
| I-305 | Pre-push hook extended to run `gitleaks protect --staged` and `gosec -no-fail` before push | cross-project | 0.80 | Accepted | (refinement of REQ-013; no new REQ) |
| I-306 | Baseline JSON files for gosec and gitleaks committed to `.ciagent/baselines/` | cross-project | 0.85 | Accepted | (implementation detail of REQ-014 / REQ-029) |
| I-307 | `orca version --json` outputs structured `{version, commit, go_version, build_time}` | cross-project | 0.70 | Accepted | (refinement of REQ-010; no new REQ) |
| I-308 | pprof endpoint on configurable port for `orca daemon` (opt-in via `--pprof :6060`) | cross-project | 0.70 | Deferred (v0.3) | — |
### Tier 3 rationale
- I-301 (`orca doctor`) is high-leverage: every cert/CA/network question
operators ask maps cleanly to a doctor subcommand. Adds
`internal/doctor/` component (see ARCHITECTURE.md update). Examples:
`orca doctor` (all checks), `orca doctor cert`, `orca doctor network`.
- I-302, I-303, I-304 are CoreCI-pattern cross-pollination: coreci's
pipelines all use structured log fields and per-tool config files
with stopwords / allowlists. Mirroring that discipline keeps Orca's
CI output consumable by humans AND by `jq`/`grep` tools.
- I-305 extends the existing v0.1 pre-push hook (REQ-013) with
v0.2-relevant checks. Already in D-016 ("gitleaks in pre-commit
opt-in"), so this is a refinement, not a new REQ.
- I-308 (pprof) is useful for P02 debugging but conflicts with the
"minimalist" pillar: it adds a port, an opt-in flag, and a code
path. Parked for v0.3 unless the PLAN stage finds a 1-line way to
add it. Confidence is 0.70 but the simplicity cost is non-zero.
## Research-stage REQ candidates (assessed)
| Candidate | Idea | Verdict | Maps to |
|-----------|------|---------|---------|
| REQ-cand-A | Bounded cert rotation history (N=3) | **Accepted** (I-201) | REQ-025 (P01) |
| REQ-cand-B | Trusted-CA fingerprint pinning in config | **Accepted** (I-202) | REQ-026 (P01) |
| REQ-cand-C | govulncheck offline mode | **Accepted** (I-101) | REQ-027 (P03) |
| REQ-cand-D | HCL/YAML schema for NodeCapacity | **Accepted** (I-203) | REQ-028 (P02) |
| REQ-cand-E | gitleaks baseline for pre-existing .env leak | **Accepted** (I-102) | REQ-029 (P03) |
| REQ-cand-F | `--watch` output format mode | **Accepted** (I-204) | REQ-030 (P04) |
All 6 candidates assessed on their merits. None were rejected; all map
to net-new REQs (REQ-025..REQ-030) and to specific phases (P01/P02/P03/P04).
## Dropped ideas (confidence < 0.60 or non-requirements)
None. The lowest-confidence accepted idea is I-308 (pprof) at 0.70,
which is auto-accepted under full autonomy but explicitly deferred to
v0.3 to keep v0.2 lean. The lowest-confidence idea that became a
net-new REQ is I-204 (--watch --json mode) at 0.75.
## Accepted Ideas (auto-accepted, full autonomy)
34 ideas accepted (10 Tier 1 + 11 Tier 2 + 8 Tier 3 + 6 research
candidates - 1 deferred = 34). I-308 is recorded as accepted under the
full-autonomy rule but explicitly deferred to v0.3 to keep v0.2 lean
per the simplicity pillar.
## Resulting REQ Additions
| New REQ | Title | Phase | Source ideas |
|----------|------------------------------------------------|-------|--------------|
| REQ-025 | Bounded cert rotation history (N=3) | P01 | I-201 / REQ-cand-A |
| REQ-026 | Trusted-CA fingerprint pinning in config | P01 | I-202 / REQ-cand-B |
| REQ-027 | govulncheck offline mode in CI | P03 | I-101 / REQ-cand-C |
| REQ-028 | HCL/YAML `NodeCapacity` declaration surface | P02 | I-203 / REQ-cand-D |
| REQ-029 | gitleaks baseline for pre-existing .env leak | P03 | I-102 / REQ-cand-E |
| REQ-030 | `--watch --json` streaming output mode | P04 | I-204 / REQ-cand-F |
| REQ-031 | `go test -race` enabled in CI | P01-P04 (cross-cutting) | I-103 |
| REQ-032 | `orca doctor` subcommand for diagnostics | P01 (initial), reusable all phases | I-301 |
| REQ-033 | Cert file mode enforcement (0600 keys, 0644 certs) | P01 | I-104 |
| REQ-034 | Cert proactive rotation alarm (30d before expiry) | P01 | I-205 |
| REQ-035 | `orca cert show` redaction of private key material | P01 | I-105 |
| REQ-036 | Cert SAN validation (DNS + IP entries) | P01 | I-106 |
| REQ-037 | `X-Orca-Idempotency-Key` header on POST | P02 | I-206 |
| REQ-038 | Structured log fields for mTLS failures | P01 | I-302 |
| REQ-039 | `.gitleaks.toml` extension with stopwords | P03 | I-303 |
| REQ-040 | `.golangci.yml` unified lint config | P03 | I-304 |
**Total net-new REQs**: 16 (REQ-025..REQ-040). 16 new requirements on
top of the 4 v0.2 REQs carried over from v0.1 (REQ-011, REQ-014,
REQ-022, REQ-023) = 20 v0.2 requirements total.
## Deferred (recorded but not v0.2)
- I-308: pprof endpoint on `orca daemon` (deferred to v0.3 — keep v0.2 lean).
## Followup notes for PLAN stage
- The PLAN stage should pair REQ-031 (race detector) with the test
scaffolding in P01 — even P01 needs `-race` because the cert hot-swap
path is concurrent.
- REQ-027 (govulncheck offline mode) needs a decision in PLAN: pre-mirror
the DB inside the CoreCI image, or use the `-format json` + `jq`
wrapper. The research notes both are viable; PLAN chooses.
- REQ-028 (NodeCapacity) is a P02 enabler; the PLAN entry for P02 must
land REQ-028's HCL schema before the bin-packing code can be written.
- REQ-032 (orca doctor) is small but touches multiple components; PLAN
should sequence it after P01's cert code lands so the doctor checks
can actually inspect cert state.
Reference in New Issue View Git Blame Copy Permalink