orca/.ciagent/IDEATION.md

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.