orca/.ciagent/PERSONAS.md

---
active:
  - lead-developer
  - backend-engineer
  - data-engineer
  - security-engineer
  - network-engineer
  - devops-engineer
deactivated:
  - cli-engineer
  - frontend-engineer
phase_specific: []
reason: |
  Orca v0.9 is the first DIRECTION-CHANGE milestone in the project's
  history. It supersedes the shipped v0.1–v0.8 architecture per the adopted
  PRD (.ciagent/PRD_v0.9.md). The re-architecture deprecates the daemon/
  transport/internal-CA/HCL/single-namespace stack and builds a CLI-only/
  SSH-push/step-ca/Markdown-frontmatter/multi-namespace stack plus 8
  net-new subsystems. The user overrode the grill's Re-architecture
  Justification REPLAN with a six-part evidence basis (see PROJECT.md
  Supersession Table). The ci-griller's 19 binding conditions (C-01..C-19)
  and 10 phase challenges (PC-01..PC-10) are adopted as execution gates
  (see GRILL_v0.9.md).

  Roster changes vs v0.8 (implements grill C-05):
  - lead-developer: RETAINED — owns the CLI subcommand tree, deprecation
    sweep (P00), path resolver (P0a1), parser dispatch (P0b), emitter
    interface (P0c), and milestone coordination.
  - backend-engineer: RETAINED — owns SSH-push transport (P01), runtime
    abstraction (P07a/b/c), transaction bundle (P10 design), step-ca
    integration, secrets crypto. Frameworks updated: golang.org/x/crypto/ssh
    (existing), golang.org/x/crypto/ssh/knownhosts (existing); pending
    deps: bytecodealliance/wasmtime-go (C-01 gate), smallstep/cli (I-B-004).
  - data-engineer: RETAINED — owns per-namespace DB schema split (P0a1,
    REQ-071), CLI cache DB (R-008), namespace inheritance resolver state
    (P0a2). Frameworks: modernc/sqlite.
  - security-engineer: REACTIVATED — owns step-ca provisioning (REQ-076),
    master.key + AES-256-GCM crypto (REQ-080, C-19 threat model), SPIFFE
    SVID minting (C-08 spike), SSH-push blast-radius review, Traefik edge,
    .env.secrets threat model. The re-architecture reverses AD-010
    (step-ca rejection) and the SPIFFE rejection at PROJECT.md:94; both
    reversals are justified in the Supersession Table.
  - network-engineer: REACTIVATED — owns socket-based service exposure
    (R-007, P08), Syncthing P2P ports (P09), Traefik routing + dynamic
    config atomicity (P02, C-10). The transport layer moves from mTLS
    HTTP daemon-to-daemon to SSH CLI-to-server; network-engineer reviews
    the new trust surface.
  - devops-engineer: REACTIVATED — owns bash scripts (scripts/orca-*.sh,
    C-15..C-18: bats/shellcheck/shfmt gate, render-format contract,
    slog-syslog), systemd timers (orca-pull/drift/aggregate, C-09 failure
    contract, C-11 watchdog), hermetic test infra (P00 bootstrap, P08
    expand, REQ-087).
  - cli-engineer: remains DEACTIVATED — CLI surface growth is owned by
    lead-developer (cobra subcommands) + backend-engineer (transport);
    reactivation optional if CLI subcommand surface exceeds lead-developer
    bandwidth.
  - frontend-engineer: remains DEACTIVATED — no web UI (unchanged from
    v0.1 onward; R-014 makes Markdown canonical, not a web UI).
---

# Personas: Orca

## v0.9 persona assessment (supersedes v0.8)

The v0.9 re-architecture introduces 5 new external apt dependencies (step-ca,
Traefik, Syncthing, wasmtime, podman), 8 net-new subsystems, and deprecates
~10k lines of shipped daemon/transport/CA/HCL code. The active roster grows
from 3 to 6 to cover the new attack surfaces and deployment model. Territory
enforcement remains in `warn` mode per config.json.

### 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.10 Docs & Install Milestone — Persona Configuration

```yaml
---
active:
  - lead-developer
  - backend-engineer
  - docs-engineer
deactivated:
  - data-engineer
  - security-engineer
  - network-engineer
  - devops-engineer
  - cli-engineer
  - frontend-engineer
phase_specific:
  - docs-engineer
reason: |
  v0.10 is a documentation + install-hardening milestone. It touches two
  territories: scripts/ (release.sh, install.sh — bash, backend-engineer)
  and docs/ + examples/ + README.md (markdown, lead-developer +
  docs-engineer). No Go orchestration code changes, no schema/migration
  changes, no UI, no security/crypto surface, no transport/network
  surface. The data-engineer, security-engineer, network-engineer, and
  devops-engineer personas are deactivated for this milestone.
---
```

### lead-developer (v0.10)
- **Active**: true
- **Territory**: `docs/**/*.md`, `examples/**`, `README.md`,
  `.ciagent/**/*.md` (coordination + cross-cutting docs)
- **Frameworks**: markdown, cobra (for CLI reference accuracy)
- **Reason**: Owns the CLI reference doc, jobspec reference, ingress
  guide, examples directory, README refresh, and namespace.md update.
  Coordinates factual accuracy against the live codebase.

### backend-engineer (v0.10)
- **Active**: true
- **Territory**: `scripts/release.sh`, `scripts/install.sh`,
  `scripts/tests/*.bash`
- **Frameworks**: bash, curl, tea CLI, Gitea API
- **Reason**: Owns the release/install pipeline fix (cross-build amd64,
  asset verification, fallback walk). The scripts are API-adjacent
  tooling that interacts with the Gitea releases API.

### docs-engineer (v0.10 — phase-specific)
- **Active**: true (phase-specific: P2, P3, P4)
- **Territory**: `docs/cli.md`, `docs/jobspec.md`, `docs/ingress.md`,
  `examples/full-stack/**`
- **Frameworks**: markdown, GitHub-flavored markdown
- **Constraints**: factual-accuracy-against-codebase,
  cross-link-resolution, deprecation-callouts
- **Reason**: Custom persona for the markdown authoring work. Ensures
  every factual claim in the docs is grounded in the live codebase
  (struct fields, flag definitions, paths) and every cross-link
  resolves. Removed after P4.

### Deactivated personas (v0.10)
- **data-engineer**: no schema/migration work this milestone.
- **security-engineer**: no crypto/threat-model work this milestone.
- **network-engineer**: no transport/socket work this milestone.
- **devops-engineer**: no packaging/distribution work beyond the
  release.sh fix (owned by backend-engineer).
- **cli-engineer**: no new CLI commands this milestone.
- **frontend-engineer**: no web UI (unchanged from v0.1).

| 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. |
## v0.11 Update (Production Hardening)

The v0.9 persona roster carries forward to v0.11 with these additions:

### Roster changes

- **lead-developer**: RETAINED — owns `orca cluster rotate-lead` (P14b),
  `orca upgrade` (P14a), README framing (P15, Q5=A Nomad-inspired),
  milestone coordination.
- **backend-engineer**: RETAINED — owns `internal/drift/` (P10, ~500 LoC
  greenfield), `internal/emitter/nft.go` (P15.5, ~200 LoC greenfield),
  `orca drift` CLI tree (P10), `orca nft` CLI (P15.5), `orca job migrate`
  (P05), `orca logs --all-nodes` (P06), `orca doctor mTLS`/`orca doctor nft`
  (P15.5), `scripts/orca-drift-notify.sh` + `orca-remediate.sh` (P10).
  Frameworks: cobra, `iter.Seq2` (D-017 extension), `signal.NotifyContext`
  (D-023), golang.org/x/crypto/ssh (existing).
- **data-engineer**: REACTIVATED for P14a — owns v0.8→v1.0 data migration
  (REQ-066), schema migration for `orca upgrade` binding cutover. Was
  deactivated in v0.10 (docs-only milestone); reactivated for the
  migration phase.
- **security-engineer**: RETAINED — owns threat model (P15.5, C-19),
  secrets subsystem (P03), `orca doctor mTLS` (P15.5), ingress-hybrid
  trust-boundary review (R-017), drift-detection threat model (R-020
  deadlock, secret exclusion D-234).
- **network-engineer**: RETAINED — owns nftables emitter (P15.5, R-017),
  Traefik binding cutover (P14a/P15.5), cross-node cluster mesh (D-219,
  unchanged private IP), drift-detection network paths (NFS detection
  D-233, SSH fanout for aggregator).
- **devops-engineer**: RETAINED — owns `scripts/orca-aggregate.sh`
  extension (P09, D-237), `scripts/orca-drift-notify.sh` (P10),
  `scripts/orca-remediate.sh` (P10), systemd Path unit emitter (P10),
  drift-detection integration tests (P08: auto-remediation, NFS fallback,
  cooldown, secret exclusion), `orca` system user setup (P10, REQ-111).
- **docs-engineer**: PHASE-SPECIFIC (P15) — owns README refresh (Q5=A
  Nomad-inspired framing, honest-trade-offs table from research doc 3).
  Created for P15; removed after phase completes.
- **cli-engineer**: remains DEACTIVATED — CLI surface growth is owned by
  lead-developer + backend-engineer.
- **frontend-engineer**: remains DEACTIVATED — no web UI.

### Phase-specific personas

- `docs-engineer`: active for P15 only (README refresh). Removed after
  phase completes.