docs(P00): v0.8 research findings + persona assessment
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---
This commit is contained in:
Jon Chery
+166
-44
@@ -1,3 +1,131 @@
|
||||
---
|
||||
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
|
||||
@@ -28,70 +156,64 @@ reason: |
|
||||
- devops-engineer: DEACTIVATED — no packaging/distribution in v0.7.
|
||||
---
|
||||
|
||||
# Personas: Orca
|
||||
|
||||
## Roster
|
||||
|
||||
### lead-developer
|
||||
### 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/P03/P04. Owns cert command registration (P01), engine/transport/audit test coverage (P03), and pprof daemon integration (P04). Adjudicates territory overlaps between config (backend) and CLI wiring (lead).
|
||||
- **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
|
||||
### backend-engineer (v0.7)
|
||||
- **Domain**: backend
|
||||
- **Frameworks**: `cobra`, `hashicorp/hcl/v2`
|
||||
- **Constraints**: `API-first`, `error-handling`, `minimal-dependencies`, `no-package-level-state`
|
||||
- **Territory**: `**/config/**`, `**/api/**`, `**/*_handler*`, `internal/daemon/**` (non-pprof), `internal/cli/root.go` (config flag wiring)
|
||||
- **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 `internal/config` package (P02 — HCL config file parsing, Load + MergeOverrides with flag>env>file>default precedence per D-039). No package-level state (AD-023). Config is a pure function passed explicitly to consumers.
|
||||
- **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
|
||||
### data-engineer (v0.7)
|
||||
- **Domain**: data
|
||||
- **Frameworks**: `modernc/sqlite`, `iter`
|
||||
- **Constraints**: `schema-first`, `migration-safe`, `local-storage-only`
|
||||
- **Territory**: `**/store/**`, `**/model.go`, `**/migration*`, `migrations/**`, `internal/store/migrations/**`
|
||||
- **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**: Owns `cert_repo_test.go` (P01 companion — 11 tests covering Insert/Get/List/ListByNode/LatestForKind/PruneOlderThan/Delete + duplicate serial) and migration 0007 (UNIQUE index on `certs.serial_hex`). Co-owns `internal/proxmox/ssh_session_test.go` + `bootstrap_test.go` extension (P03 — transport/proxmox coverage).
|
||||
- **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
|
||||
- **Active**: false (v0.7)
|
||||
- **Reason**: Deactivated — merged into lead-developer for v0.7. The cert registration is a 1-line AddCommand; the `--config` flag is root-command wiring; pprof is a daemon flag. No new CLI subsystem requiring a dedicated CLI persona.
|
||||
### 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
|
||||
- **Active**: false (v0.7)
|
||||
- **Reason**: Deactivated — v0.7 adds no new security surface. pprof is operator-only, addr-gated (AD-024); cert registration exposes existing security code, does not add new. The config package handles paths only (no secrets). Existing security constraints (file modes, redaction) are exercised by P01 smoke tests but not extended.
|
||||
### 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
|
||||
- **Active**: false (v0.7)
|
||||
- **Reason**: Deactivated — v0.7 has no packaging/distribution/release surface. Was active in v0.5 (distribution milestone).
|
||||
### 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
|
||||
- **Active**: false (v0.7)
|
||||
- **Reason**: Deactivated — v0.7 has no transport/mTLS surface changes. P03 adds tests for existing transport code but no new network surface.
|
||||
### 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
|
||||
- **Active**: false (v0.7)
|
||||
### frontend-engineer (v0.7)
|
||||
- **Active**: false (v0.6)
|
||||
- **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.7** (lead-developer adjudicates):
|
||||
- `internal/cli/root.go` — backend-engineer (config flag + context wiring) + lead-developer (existing root command). Boundary: backend owns `--config` flag + `configFromCtx`; lead owns all other root command behavior.
|
||||
- `internal/cli/daemon.go` — lead-developer (pprof flag + config listen_addr wiring) + backend-engineer (config consumption). Boundary: lead owns the daemon command; backend's config package is consumed, not modified.
|
||||
- `internal/store/migrations/` — data-engineer owns all migrations. No overlap in v0.7.
|
||||
|
||||
## v0.7 vs v0.6 Persona Diff
|
||||
### v0.6 vs v0.5 Persona Diff (v0.7 baseline reference)
|
||||
|
||||
| Change | Rationale |
|
||||
|--------|-----------|
|
||||
| `data-engineer` retained | Owns cert_repo tests + migration 0007 + proxmox/transport test coverage. |
|
||||
| `security-engineer` deactivated | v0.7 adds no new security surface (pprof is operator-only, cert registration exposes existing code). |
|
||||
| `cli-engineer` deactivated | Merged into lead-developer (cert registration is 1-line; config flag is root wiring). |
|
||||
| `devops-engineer` remains deactivated | No packaging/distribution in v0.7. |
|
||||
| `network-engineer` remains deactivated | No transport/mTLS surface changes. |
|
||||
| `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. |
|
||||
Reference in New Issue
Block a user