coreci/orca
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 91 Wiki Activity
Files
efdbd2a61dcc3d325e2957d30c73abc8ef836d2b
orca/.ciagent/PERSONAS.md
T
Jon Chery 08d321f57f docs(P00): research findings 
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---
2026-06-03 20:59:32 +00:00

127 lines
5.4 KiB
Markdown
Raw Blame History

---
active_personas:
- lead-developer
- backend-engineer
- data-engineer
- cli-engineer
- security-engineer
- network-engineer
deactivated_personas:
- frontend-engineer
- devops-sre
phase_specific:
- security-engineer
- network-engineer
- cli-engineer
reason: |
Orca is a CLI-first, offline-first orchestration engine with no web UI and
a single-binary distribution model. The persona roster reflects this:
- lead-developer: coordination and task decomposition
- backend-engineer: core engine and API handlers
- data-engineer: SQLite state store and migrations
- cli-engineer: Cobra subcommands and CLI UX
- security-engineer: mTLS, cert lifecycle, audit logging, input validation
- network-engineer: transport layer, dispatcher, peer-to-peer resilience
Deactivated:
- frontend-engineer: no web UI in v0.1
- devops-sre: no container/cloud integrations; release flow is
handled by CoreCI (not a persona territory)
Phase-specific (v0.2):
- security-engineer: P01 (mTLS/CA) + P02 (peer transport hardening)
- network-engineer: P02 only (multi-node scheduling & dispatch)
- cli-engineer: P04 only (--watch flag is a CLI concern)
---
# Personas: Orca
## Roster
### lead-developer
- **Domain**: coordination
- **Frameworks**: `cobra`
- **Constraints**: `boundary-enforcement`, `offline-first`, `no-redundant-implementations`
- **Territory**: `**/*.go`, `cmd/**`, `internal/**`
- **Active**: true
### backend-engineer
- **Domain**: backend
- **Frameworks**: `cobra`, `net/http`
- **Constraints**: `API-first`, `error-handling`, `minimal-dependencies`, `security-first`
- **Territory**: `**/api/**`, `**/*_handler*`, `**/*_handler.go`, `internal/daemon/**`
- **Active**: true
### data-engineer
- **Domain**: data
- **Frameworks**: `modernc/sqlite`
- **Constraints**: `schema-first`, `migration-safe`, `local-storage-only`
- **Territory**: `**/store/**`, `**/model.go`, `**/migration*`, `migrations/**`, `internal/store/migrations/0004_certs.sql`
- **Active**: true
### cli-engineer (custom)
- **Domain**: CLI/UX
- **Frameworks**: `cobra`, `pflag`
- **Constraints**: `discoverable-help`, `consistent-flag-naming`, `human-readable-output`, `machine-readable-json-flag`
- **Territory**: `cmd/**`, `internal/cli/**`, `internal/commands/**`
- **Active**: true
- **Reason**: Orca is CLI-first; this persona ensures CLI quality and discoverability.
### security-engineer (custom)
- **Domain**: security
- **Frameworks**: `crypto/tls`, `crypto/x509`, `slog`
- **Constraints**: `no-panic-in-production`, `structured-audit-logging`, `no-secret-in-logs`, `input-validation`, `least-privilege`
- **Territory**: `**/auth/**`, `**/audit/**`, `internal/security/**`, `internal/transport/**` (TLS config only)
- **Active**: true
- **Reason**: mTLS, audit logging, and input validation are first-class concerns.
- **Phase scope**: P01 (mTLS + internal CA), P02 (transport hardening for peer handshakes). Deactivates after P02 ships — P03/P04 have lighter security needs.
### network-engineer (custom, NEW in v0.2)
- **Domain**: networking
- **Frameworks**: `net/http`, `crypto/tls` (via `internal/security`), `iter`
- **Constraints**: `connection-resilience`, `retry-with-backoff`, `graceful-disconnect`, `context-propagation`
- **Territory**: `**/transport/**`, `**/engine/dispatcher*`, `**/engine/peer*`, `internal/engine/dispatcher.go`, `internal/transport/**`
- **Active**: true
- **Reason**: v0.2 introduces cross-node dispatch and peer-to-peer transport. This persona owns the transport layer, dispatcher, and peer lifecycle concerns that are distinct from the API-handler territory of `backend-engineer`.
- **Phase scope**: P02 only. Deactivates after P02 ships.
### frontend-engineer
- **Active**: false
- **Reason**: No web UI in v0.1.
### devops-sre
- **Active**: false
- **Reason**: No container/cloud integrations. Release flow is handled by CoreCI.
## Territory Enforcement
- **Mode**: `warn` (per `config.json`)
- **Behavior**: Out-of-territory file changes log a warning but do not block.
- **Rationale**: Allows flexibility during early development; tighten to `strict` post-v0.1.
## Phase-Specific Personas (v0.2)
| Persona | Active in | Reason |
|---------|-----------|--------|
| `security-engineer` | P01, P02 | mTLS/CA in P01, transport hardening in P02. Lighter security needs in P03 (CI scanning) and P04 (streaming UX). |
| `network-engineer` | P02 | Multi-node dispatch is a P02 concern only. P01 builds the transport primitives but P02 wires them into cross-node scheduling. |
| `cli-engineer` | P04 | The `--watch` flag is a CLI surface; P01-P03 don't add new CLI commands. |
In full-autonomy mode, all personas are auto-accepted and the phase-scope
assignments are applied automatically when a phase is committed.
## Migration from v0.1
- `backend-engineer` territory unchanged: `internal/daemon/**` still owns HTTP
handlers. The new `internal/transport/**` package is shared with
`network-engineer` but `transport` owns the *connection lifecycle* (dial,
retry, close) while `daemon` owns the *request handlers*.
- `data-engineer` territory expanded to include the new
`internal/store/migrations/0004_certs.sql` migration in P01.
- `security-engineer` territory extended from `internal/security/**` to
include the TLS-config portion of `internal/transport/**` (the
`NewServerTLSConfig` / `NewClientTLSConfig` helpers).
- `cli-engineer` territory unchanged; the new `orca cert` subcommands in P01
fall under the existing `internal/cli/**` glob.
Reference in New Issue View Git Blame Copy Permalink