Jon Chery
285ffee863
RESEARCH_v0.8.md (35KB): per-package coverage strategy for 9 pkgs, SSH trust research (uncovered latent TOFU capture bug + unpopulated HostKeyFingerprint field), verify-reqs Go program approach, 4 ADs, 10 pitfalls. PERSONAS.md updated for v0.8 (3-persona roster retained, connectrpc removed from backend frameworks per AD-014, territory globs aligned to actual file structure). Key findings flagged for PLAN: - proxmox needs sessionRunner seam (~10 LOC) or stalls at ~55% - cert_repo_test.go missing (v0.7 P01 leftover) blocks store 70% - TOFU known_hosts capture broken + HostKeyFingerprint never populated (bootstrap.go:195-198) — P02 fixes both - verify-reqs = Go program at cmd/verify-reqs (~80 LOC, stdlib only) ---ci--- project: orca phase: 0 milestone: v0.8 status: research ---/ci---
219 lines
15 KiB
Markdown
219 lines
15 KiB
Markdown
---
|
|
active:
|
|
- lead-developer
|
|
- backend-engineer
|
|
- data-engineer
|
|
deactivated:
|
|
- cli-engineer
|
|
- security-engineer
|
|
- devops-engineer
|
|
- network-engineer
|
|
- frontend-engineer
|
|
phase_specific: []
|
|
reason: |
|
|
Orca v0.8 is an NFR coverage & trust-hardening milestone. The work is
|
|
test coverage uplift across 9 packages (P01), SSH trust-surface
|
|
hardening in the existing proxmox + cli/node + security packages (P02),
|
|
and a requirements-hygiene Go program + Makefile target (P03). No
|
|
schema changes, no new security architecture, no packaging/distribution,
|
|
no UI.
|
|
|
|
Roster changes vs v0.7:
|
|
- lead-developer: RETAINED — owns cmd/orca smoke test, internal/cli
|
|
coverage (cert/doctor/audit/status/version subcommands), and the
|
|
cmd/verify-reqs Go program (coordination + glue-code territory).
|
|
- backend-engineer: RETAINED — owns internal/transport + internal/engine
|
|
tests (httptest.NewTLSServer, LocalExecutor stubs, PeerRegistry) and
|
|
the SSH trust-surface in internal/proxmox/bootstrap.go (pinned
|
|
host-key callback, TOFU capture fix, sessionRunner seam) plus
|
|
internal/cli/node.go (--host-key-fingerprint flag, key-reset
|
|
subcommand). Frameworks updated: connectrpc REMOVED (not in go.mod
|
|
per AD-014), golang.org/x/crypto/ssh ADDED (direct dep since v0.6).
|
|
- data-engineer: RETAINED — owns internal/store tests (cert_repo_test.go
|
|
gap + coverage uplift), internal/audit tests (sqlite-backed
|
|
audit_log asserts), internal/certpaths tests (path-join asserts),
|
|
and internal/jobspec tests (golden HCL fixtures). Frameworks
|
|
updated: modernc/sqlite + iter (matches actual go.mod).
|
|
- security-engineer: remains DEACTIVATED — v0.8 refines the existing
|
|
proxmox SSH trust surface (pinned callback, key-reset) but does NOT
|
|
add new security architecture. The trust work is backend-engineer
|
|
territory (it's SSH dialer + known_hosts file manipulation, not
|
|
X.509/CA/crypto code).
|
|
- cli-engineer: remains DEACTIVATED — merged into lead-developer
|
|
(cli coverage is test-only; --host-key-fingerprint and key-reset
|
|
are 1-flag + 1-subcommand additions to the existing node.go).
|
|
- devops-engineer: remains DEACTIVATED — verify-reqs is a Go program
|
|
(lead-developer territory), not a CI/packaging change. The
|
|
.coreci.yml edit is a 3-line validate-pipeline hook.
|
|
- network-engineer: remains DEACTIVATED — no transport/mTLS surface
|
|
change (transport coverage is test-only on the existing mTLS layer).
|
|
- frontend-engineer: remains DEACTIVATED — no web UI (unchanged
|
|
from v0.1 onward).
|
|
---
|
|
|
|
# Personas: Orca
|
|
|
|
## v0.8 persona assessment
|
|
|
|
### lead-developer
|
|
- **Domain**: coordination
|
|
- **Frameworks**: `cobra`, `net/http/httptest`, `testing`
|
|
- **Constraints**: `boundary-enforcement`, `offline-first`, `no-redundant-implementations`, `coverage-floor-70`
|
|
- **Territory**: `cmd/**`, `internal/cli/**`, `cmd/verify-reqs/**`, `Makefile`, `.coreci.yml`, `.ciagent/**`
|
|
- **Active**: true
|
|
- **Reason**: Owns P01 coverage for `cmd/orca` (smoke test of `main()`/`cli.Execute()`), `internal/cli` coverage for the non-node, non-daemon subcommands (`cert *`, `doctor *`, `audit list`, `status`, `version`), and the P03 `cmd/verify-reqs/main.go` Go program + `make verify-reqs` Makefile target + `.coreci.yml` validate-pipeline hook. Added `coverage-floor-70` constraint (D-047 tiered floor: 70% for the 6 under-50% packages, 50% for the 3 zero-test packages). Added `testing` + `net/http/httptest` to frameworks (test-only phase).
|
|
|
|
### backend-engineer
|
|
- **Domain**: backend
|
|
- **Frameworks**: `cobra`, `net/http`, `net/http/httptest`, `golang.org/x/crypto/ssh`, `golang.org/x/crypto/ssh/knownhosts`, `testing`
|
|
- **Constraints**: `API-first`, `error-handling`, `minimal-dependencies`, `security-first`, `tofu-host-key-pinning`, `pinned-host-key-fail-closed`, `atomic-file-rewrite`, `coverage-floor-70`
|
|
- **Territory**: `internal/transport/**`, `internal/engine/**`, `internal/proxmox/**`, `internal/cli/node.go`, `internal/daemon/**` (tests only)
|
|
- **Active**: true
|
|
- **Reason**: Owns P01 coverage for `internal/transport` (httptest.NewTLSServer for mTLS + stubDispatcher for DispatchClient) and `internal/engine` (LocalExecutor stubs + PeerRegistry in-memory tests). Owns P02 SSH trust hardening: `--host-key-fingerprint` pinned callback in `internal/proxmox/bootstrap.go` (D-045 OpenSSH SHA256:base64 format, AD-027/AD-028), the TOFU capture-fix (knownhosts.New returns KeyError{Want:[]} on first connect — must capture-and-persist via knownhosts.Line, AD-029 atomic rewrite), the `sessionRunner` seam refactor (P01 enabler for proxmox coverage), and `internal/cli/node.go` `--host-key-fingerprint` flag + `key-reset` subcommand (D-046 local known_hosts only). Frameworks updated: `connectrpc` REMOVED (not in go.mod per AD-014 — config.json still lists it but it's a stale entry), `golang.org/x/crypto/ssh` + `knownhosts` ADDED (direct dep since v0.6 D-030). Added `pinned-host-key-fail-closed` + `atomic-file-rewrite` + `coverage-floor-70` constraints.
|
|
|
|
### data-engineer
|
|
- **Domain**: data
|
|
- **Frameworks**: `modernc/sqlite`, `iter`, `hashicorp/hcl/v2`, `testing`
|
|
- **Constraints**: `schema-first`, `migration-safe`, `local-storage-only`, `no-goroutine-leak`, `nullable-column-handling`, `coverage-floor-70`
|
|
- **Territory**: `internal/store/**`, `internal/audit/**`, `internal/certpaths/**`, `internal/jobspec/**`, `internal/model/**`, `internal/store/migrations/**`
|
|
- **Active**: true
|
|
- **Reason**: Owns P01 coverage for `internal/store` (including the missing `cert_repo_test.go` — a v0.7 P01 leftover; Insert/Get/List/ListByNode/LatestForKind/PruneOlderThan/Delete + N=3 rotation history per REQ-025), `internal/audit` (sqlite-backed audit_log row asserts via `engine.Audit` + `store.AuditRepo`, slog capture via test handler), `internal/certpaths` (path-join asserts with temp dir + ORCA_HOME/ORCA_DB env), and `internal/jobspec` (golden-file HCL fixtures in a new `testdata/` dir + error-path table for Parse/Validate/ParseFile). Frameworks updated: `iter` + `hashicorp/hcl/v2` added (matches actual go.mod — jobspec uses hclsimple; store Watch uses iter.Seq). Added `coverage-floor-70` constraint.
|
|
|
|
### cli-engineer
|
|
- **Active**: false (v0.8)
|
|
- **Reason**: Deactivated — merged into lead-developer. The cli coverage work is test-only; `--host-key-fingerprint` and `key-reset` are a 1-flag and 1-subcommand addition to the existing `internal/cli/node.go`, not a new CLI subsystem.
|
|
|
|
### security-engineer
|
|
- **Active**: false (v0.8)
|
|
- **Reason**: Deactivated — v0.8 refines the existing proxmox SSH trust surface (pinned host-key callback, key-reset known_hosts rewrite) but does NOT add new security architecture (no new CA, no new X.509, no new crypto). The trust work is backend-engineer territory (SSH dialer + known_hosts file manipulation). The `internal/security/sshkey.go` is unchanged in v0.8. Was active in v0.6 (SSH keygen + sudoers), deactivated in v0.7, remains deactivated in v0.8.
|
|
|
|
### devops-engineer
|
|
- **Active**: false (v0.8)
|
|
- **Reason**: Deactivated — `verify-reqs` is a Go program (`cmd/verify-reqs/main.go`), not a CI/packaging change. The `.coreci.yml` edit is a 3-line validate-pipeline hook (lead-developer territory). No install.sh, Dockerfile, or release-pipeline surface in v0.8.
|
|
|
|
### network-engineer
|
|
- **Active**: false (v0.8)
|
|
- **Reason**: Deactivated — no transport/mTLS surface change. `internal/transport` coverage is test-only on the existing mTLS layer (httptest.NewTLSServer, no new TLS config). The SSH trust work is point-to-point bootstrap, not the mTLS mesh network-engineer owns.
|
|
|
|
### frontend-engineer
|
|
- **Active**: false (v0.8)
|
|
- **Reason**: No web UI in Orca (unchanged from v0.1 onward).
|
|
|
|
## Territory Enforcement
|
|
|
|
- **Mode**: `warn` (per `config.json`)
|
|
- **Behavior**: Out-of-territory file changes log a warning but do not block.
|
|
- **Key overlaps in v0.8** (lead-developer adjudicates):
|
|
- `internal/cli/node.go` — backend-engineer (`--host-key-fingerprint` flag + `key-reset` subcommand + proxmox pass-through) vs lead-developer (cli coverage tests). Boundary: backend owns the command implementation; lead owns the test files (`node_test.go`).
|
|
- `internal/proxmox/bootstrap.go` — backend-engineer (pinned callback, TOFU fix, sessionRunner seam) vs data-engineer (no overlap — proxmox has no store/audit code). Clean boundary.
|
|
- `cmd/verify-reqs/main.go` — lead-developer (Go program + Makefile + .coreci.yml) vs data-engineer (no overlap — verify-reqs parses markdown, not DB). Clean boundary.
|
|
- `internal/store/cert_repo_test.go` — data-engineer (test file) vs backend-engineer (no overlap — cert_repo is data territory). Clean boundary.
|
|
|
|
## v0.8 vs v0.7 Persona Diff
|
|
|
|
| Change | Rationale |
|
|
|--------|-----------|
|
|
| `lead-developer` retained | Owns cmd/orca smoke test, internal/cli coverage (non-node subcommands), cmd/verify-reqs Go program. |
|
|
| `backend-engineer` retained | Owns internal/transport + internal/engine tests + SSH trust-surface in proxmox + cli/node. Frameworks corrected: connectrpc removed (not in go.mod), x/crypto/ssh added. |
|
|
| `data-engineer` retained | Owns internal/store (cert_repo gap) + internal/audit + internal/certpaths + internal/jobspec tests. Frameworks corrected: iter + hcl/v2 added. |
|
|
| `security-engineer` remains deactivated | v0.8 refines existing SSH trust surface, no new security architecture. |
|
|
| `cli-engineer` remains deactivated | Merged into lead-developer (test-only + 1 flag + 1 subcommand). |
|
|
| `devops-engineer` remains deactivated | verify-reqs is a Go program, not CI/packaging. |
|
|
| `network-engineer` remains deactivated | No transport/mTLS surface change (test-only). |
|
|
| `frontend-engineer` remains deactivated | No web UI. |
|
|
|
|
---
|
|
|
|
## v0.7 baseline (preserved for traceability)
|
|
|
|
---
|
|
active_personas:
|
|
- lead-developer
|
|
- backend-engineer
|
|
- data-engineer
|
|
deactivated_personas:
|
|
- cli-engineer
|
|
- security-engineer
|
|
- devops-engineer
|
|
- network-engineer
|
|
- frontend-engineer
|
|
phase_specific: []
|
|
reason: |
|
|
Orca v0.7 is an NFR hardening & completion milestone. The work is CLI
|
|
registration (cert command), a new internal/config package, test
|
|
coverage uplift across engine/transport/proxmox/audit, and an opt-in
|
|
pprof endpoint on the daemon. No schema changes, no new security
|
|
surface, no packaging/distribution, no UI.
|
|
|
|
Roster changes vs v0.6:
|
|
- data-engineer: RETAINED — owns cert_repo tests + store coverage.
|
|
- security-engineer: DEACTIVATED — v0.7 adds no new security surface
|
|
(pprof is operator-only, addr-gated; cert registration exposes
|
|
existing security code, does not add new).
|
|
- cli-engineer: DEACTIVATED — merged into lead-developer for v0.7
|
|
(the cert registration is a 1-line AddCommand; config --config flag
|
|
is root-command wiring, not a new CLI subsystem).
|
|
- devops-engineer: DEACTIVATED — no packaging/distribution in v0.7.
|
|
---
|
|
|
|
### lead-developer (v0.7)
|
|
- **Domain**: coordination
|
|
- **Frameworks**: `cobra`
|
|
- **Constraints**: `boundary-enforcement`, `offline-first`, `no-redundant-implementations`
|
|
- **Territory**: `**/*.go`, `cmd/**`, `internal/**`
|
|
- **Active**: true
|
|
- **Reason**: Coordination across P01/P02/P03. SSH/bootstrap touches security + cli + store + doctor — territory overlaps need adjudication (proxmox package boundary, doctor Proxmox check scaffolding).
|
|
|
|
### backend-engineer (v0.7)
|
|
- **Domain**: backend
|
|
- **Frameworks**: `cobra`, `net/http`, `golang.org/x/crypto/ssh`
|
|
- **Constraints**: `API-first`, `error-handling`, `minimal-dependencies`, `security-first`, `idempotent-bootstrap`
|
|
- **Territory**: `**/api/**`, `**/*_handler*`, `**/*_handler.go`, `internal/daemon/**`, `internal/proxmox/**`, `internal/cli/init.go`
|
|
- **Active**: true
|
|
- **Reason**: Owns the `orca init` full-bootstrap orchestration (CA + cert + db + localhost node, idempotent) and the `internal/proxmox/bootstrap.go` SSH session sequence (dial, deploy pubkey, useradd, pveum, sudoers, visudo validate). Added `idempotent-bootstrap` constraint (D-036 — re-run must be skip-and-refresh) and `golang.org/x/crypto/ssh` to frameworks.
|
|
|
|
### data-engineer (v0.7)
|
|
- **Domain**: data
|
|
- **Frameworks**: `modernc/sqlite`, `iter`
|
|
- **Constraints**: `schema-first`, `migration-safe`, `local-storage-only`, `no-goroutine-leak`, `nullable-column-handling`
|
|
- **Territory**: `**/store/**`, `**/model.go`, `**/migration*`, `migrations/**`, `internal/store/migrations/**`, `internal/model/node.go`
|
|
- **Active**: true
|
|
- **Reason**: Reactivated for v0.6. Owns migration `0006_node_kind_os.sql` (REQ-049 — nullable `kind`/`os` columns, backward-compatible) and `NodeRepo` schema extension (Insert/Get/List/Watch/scanNode column additions + new `GetByName`/`UpdateLastSeenAndOS` helpers). Added `nullable-column-handling` constraint (NULL → `""` in Go struct, not nil-deref).
|
|
|
|
### cli-engineer (v0.7)
|
|
- **Domain**: CLI/UX
|
|
- **Frameworks**: `cobra`, `pflag`
|
|
- **Constraints**: `discoverable-help`, `consistent-flag-naming`, `human-readable-output`, `machine-readable-json-flag`, `signal-handling`, `password-flag-redaction`
|
|
- **Territory**: `cmd/**`, `internal/cli/**`, `internal/commands/**`
|
|
- **Active**: true
|
|
- **Reason**: Owns `orca init` multi-step bootstrap output UX (progress lines per step), `orca node join --type/--host/--user/--password/--proxmox-user/--proxmox-role` flag wiring, and `doctor os`/`doctor proxmox` subcommand wiring. Added `password-flag-redaction` constraint (D-031 — `--password` never echoed, prefer `$ORCA_PROXMOX_PASSWORD`, zero after use).
|
|
|
|
### security-engineer (v0.7)
|
|
- **Domain**: security
|
|
- **Frameworks**: `crypto/tls`, `crypto/x509`, `crypto/ed25519`, `golang.org/x/crypto/ssh`, `slog`
|
|
- **Constraints**: `no-panic-in-production`, `structured-audit-logging`, `no-secret-in-logs`, `input-validation`, `least-privilege`, `tofu-host-key-pinning`, `noexec-sudoers`
|
|
- **Territory**: `**/auth/**`, `**/audit/**`, `internal/security/**`, `internal/transport/**` (TLS config only), `internal/proxmox/**` (SSH + sudoers + PVE role)
|
|
- **Active**: true
|
|
- **Reason**: Reactivated for v0.6. Owns `internal/security/sshkey.go` (Ed25519 keygen, 0600/0644 mode enforcement per REQ-033 spirit), TOFU host-key pinning via `knownhosts.New`, sudoers least-privilege design (NOEXEC on pct/qm, exclude pvesh, no NOEXEC on apt-get/dpkg), password redaction (D-031), and audit logging of all bootstrap/join actions (REQ-052). Added `tofu-host-key-pinning` and `noexec-sudoers` constraints. Co-owns `internal/proxmox/**` with backend-engineer (security owns SSH auth + sudoers content; backend owns the session orchestration).
|
|
|
|
### devops-engineer (v0.7)
|
|
- **Active**: false (v0.6)
|
|
- **Reason**: Deactivated — v0.6 has no install.sh, Dockerfile, .coreci.yml, or release-pipeline surface. The Proxmox SSH bootstrap is backend + security work, not devops. Was active in v0.5 (distribution milestone).
|
|
|
|
### network-engineer (v0.7)
|
|
- **Active**: false (v0.6)
|
|
- **Reason**: v0.6 has no transport/mTLS surface. SSH is point-to-point bootstrap, not the mTLS mesh network-engineer owns.
|
|
|
|
### frontend-engineer (v0.7)
|
|
- **Active**: false (v0.6)
|
|
- **Reason**: No web UI in Orca (unchanged from v0.1 onward).
|
|
|
|
### v0.6 vs v0.5 Persona Diff (v0.7 baseline reference)
|
|
|
|
| Change | Rationale |
|
|
|--------|-----------|
|
|
| `data-engineer` reactivated | Owns migration 0006 + NodeRepo schema extension (kind/os columns). |
|
|
| `security-engineer` reactivated | Owns SSH keygen, TOFU host-key, sudoers, PVE role — first-class security surface. |
|
|
| `devops-engineer` deactivated | v0.6 has no packaging/distribution surface. |
|
|
| `network-engineer` remains deactivated | No transport/mTLS surface. |
|
|
| `frontend-engineer` remains deactivated | No web UI. | |