# 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.