Adopts the v0.9/v1.0 PRD (.ciagent/PRD_v0.9.md) that supersedes the shipped
v0.1-v0.8 architecture. The re-architecture is justified by a six-part
evidence basis recorded in the PROJECT.md Supersession Table:
operational daemon failure, external step-ca mandate, multi-tenancy
requirement, WASM workload requirement, SSH-push deployment target,
and vision correction.
Appends 30 net-new requirements (REQ-061..REQ-090) to REQUIREMENTS.md,
the v0.9 (13 phases) + v1.0 (19 phases) reordered plan to ROADMAP.md,
the AD-series supersession table to PROJECT.md + ARCHITECTURE.md, and
reactivates security-engineer + network-engineer + devops-engineer
personas (implements grill C-05).
---ci---
project: orca
phase: 0
milestone: v0.9
status: specify
---/ci---
Audit fix: PERSONAS.md body roster updated for v0.7 (was stale v0.6
content). Review P1-004: daemon --addr now uses cmd.Flags().Changed()
to detect explicit flag, so config listen_addr only applies when --addr
was not explicitly passed (correct flag>env>file>default precedence).
Review P1-001: migration 0007 now dedups existing duplicate serial_hex
rows before creating the UNIQUE index (backward-compat with v0.6 DBs
that accumulated duplicates before the constraint existed).
---ci---
project: orca
phase: 5
milestone: v0.7
status: execute
requirements:
covered: [REQ-053, REQ-054, REQ-055, REQ-056]
partial: []
---/ci---
---ci---
project: orca
phase: 3
milestone: v0.3
status: complete
requirements:
covered: [REQ-022, REQ-030, REQ-032]
partial: []
---/ci---
v0.3 milestone merged to main. Includes all v0.2 work (P08-P10) that
was previously on the milestone branch but not yet merged to main, plus
the v0.3 completion work (iter.Seq streaming + doctor network/db).
v0.2 phases included: P08 (mTLS), P09 (scheduling), P10 (security scan).
v0.3 phases: P0 (pre-execution), P1 (iter.Seq streaming), P2 (doctor),
P3 (final review+ship).
Total: 40 requirements, all complete. No new go.mod dependencies.
Full test suite passes under -race. gofmt + go vet clean.
v0.2 RESEARCH stage. Synthesizes the 4-phase v0.2 scope (P01-P04) into
updated static docs. No code changes. Decisions are derived from
CLARIFY D-011..D-018 (already on main) and direct investigation of
go.mod, the codebase, and ecosystem docs (Go 1.25+ iter.Seq, govulncheck,
gosec, gitleaks, step-ca).
Key research conclusions logged here:
- ConnectRPC is NOT in go.mod (.ciagent/config.json lists it in
frameworks but the dependency was never added). v0.2 falls back to
stdlib net/http with h2c for the orca.v1.Dispatch service. Zero new
direct deps. (ARCHITECTURE.md AD-014)
- Roll-our-own CA via crypto/x509 (not step-ca/cfssl/vault-pki) keeps
the binary single, dependency-free, and aligned with offline-first
(no external PKI network calls). (ARCHITECTURE.md AD-010)
- govulncheck default mode requires network access to vuln.go.dev. CI
step must use -format json (always exits 0) + a wrapper that gates
on findings via jq/cat, OR pre-mirror the database. Caller to decide
in PLAN. Logged as REQ candidate for IDEATE.
- gosec exit codes: 0 clean, 1 unsuppressed finding. -no-fail always
returns 0. Baseline JSON via -track-suppressions + exclude=. We
adopt -no-fail on initial run, baseline suppressed findings, then
tighten to fail-on-finding once baseline is empty.
- gitleaks default config covers most cases; we extend .gitleaks.toml
with stopwords for our test data paths and CA cert PEM (which would
otherwise trigger the generic-api-key rule).
- iter.Seq: yield func(V) bool, iter.Pull for pull-style, range over
function types since Go 1.25. Cancellation flows through ctx
(consumer-driven backpressure). Single-use vs multi-use semantics
documented in Go spec; we use multi-use for repo.Watch() since
callers can re-iterate.
- mTLS hot-swap via tls.Config.GetCertificate callback enables cert
rotation without daemon restart. tls.Config is read on every
handshake; reload picks up new server.crt/server.key.
ARCHITECTURE.md changes:
- Added Transport Layer (internal/transport) and Dispatcher
(internal/engine/dispatcher.go) components.
- Added Security Manager (internal/security) component with full cert
lifecycle API.
- Added certs table schema (migration 0004) and Cert Go struct.
- Extended Node with NodeCapacity (CPU/memory) for bin-packing.
- Added v0.2 Component Graph ASCII diagram.
- Added 4 named flows: cert issuance, mTLS handshake, job dispatch,
iter.Seq streaming.
- Added 8 new AD-009..AD-016 decisions and AD-014 notes the
ConnectRPC-not-in-go.mod reality.
PERSONAS.md changes:
- Added network-engineer (custom, NEW in v0.2) for transport/dispatcher.
- security-engineer marked phase_specific: [P01, P02] (off after P02).
- network-engineer marked phase_specific: [P02].
- cli-engineer marked phase_specific: [P04] (--watch is a CLI concern).
- data-engineer.territory extended to include
internal/store/migrations/0004_certs.sql.
- security-engineer.territory extended to TLS-config portion of
internal/transport.
- Frontmatter updated: active_personas, phase_specific, reason.
PROJECT.md changes:
- Moved "Multi-node scheduling" out of "Out of Scope" (it ships in P02).
- Added "External PKI / Let's Encrypt / cert transparency logs" to
Out of Scope (per D-011).
- Added "gRPC framework dependency" to Out of Scope (per AD-014).
- Added v0.2 Scope Summary section (4 phases) with cross-refs to
ARCHITECTURE.md flows.
REQ candidates surfaced for IDEATE stage (not added to REQUIREMENTS.md
in this commit — that's the IDEATE stage's job):
- REQ-cand-A: Bounded cert rotation history (retain last N=3 server
certs per node for rollback; documented in ARCHITECTURE.md certs
table as "retention" implication of the schema).
- REQ-cand-B: Trusted-CA fingerprint pinning (D-012 requires operator
to pass --ca-fingerprint at join; the daemon should refuse to start
if the on-disk CA's fingerprint doesn't match a config-pinned value,
to protect against operator typos).
- REQ-cand-C: govulncheck offline mode (CI must not call vuln.go.dev
by default; either pre-mirror the DB or set GOVULNCHECK_DB env to
a local file).
- REQ-cand-D: HCL/YAML schema for NodeCapacity declaration (where
does the operator declare a node's CPU/RAM? Current v0.1 Node model
has no capacity field. P02 will add this — needs a config file
surface, e.g. ~/.orca/node.hcl or flag on `orca node join`).
- REQ-cand-E: gitleaks baseline for pre-existing secrets in history
(the v0.1 .env leak was rotated forward but git history still has
a SHA-1 leak — gitleaks/git filter-repo remediation may need a
baseline file to avoid the same class of false positive recurring).
- REQ-cand-F: --watch output format mode (iter.Seq stream is
table-style by default; users may want --watch --json one-line-per-
event for piping). P04 scope decision; log for IDEATE.
---ci---
project: orca
phase: 0
milestone: v0.2
status: research
---/ci---
Jon Chery
cloudinit-bot