docs(P00): research findings — docs gap analysis + release/install root cause
---ci--- project: orca phase: 0 milestone: v0.10 status: research ---/ci---
This commit is contained in:
Jon Chery
@@ -1,6 +1,6 @@
|
|||||||
{
|
{
|
||||||
"phase": 0,
|
"phase": 0,
|
||||||
"stage": "clarify",
|
"stage": "research",
|
||||||
"milestone": "v0.10",
|
"milestone": "v0.10",
|
||||||
"milestone_slug": "docs-cli-examples",
|
"milestone_slug": "docs-cli-examples",
|
||||||
"phase_role": "pre_execution",
|
"phase_role": "pre_execution",
|
||||||
|
|||||||
+50
-69
@@ -137,91 +137,72 @@ enforcement remains in `warn` mode per config.json.
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## v0.7 baseline (preserved for traceability)
|
## v0.10 Docs & Install Milestone — Persona Configuration
|
||||||
|
|
||||||
|
```yaml
|
||||||
---
|
---
|
||||||
active_personas:
|
active:
|
||||||
- lead-developer
|
- lead-developer
|
||||||
- backend-engineer
|
- backend-engineer
|
||||||
|
- docs-engineer
|
||||||
|
deactivated:
|
||||||
- data-engineer
|
- data-engineer
|
||||||
deactivated_personas:
|
|
||||||
- cli-engineer
|
|
||||||
- security-engineer
|
- security-engineer
|
||||||
- devops-engineer
|
|
||||||
- network-engineer
|
- network-engineer
|
||||||
|
- devops-engineer
|
||||||
|
- cli-engineer
|
||||||
- frontend-engineer
|
- frontend-engineer
|
||||||
phase_specific: []
|
phase_specific:
|
||||||
|
- docs-engineer
|
||||||
reason: |
|
reason: |
|
||||||
Orca v0.7 is an NFR hardening & completion milestone. The work is CLI
|
v0.10 is a documentation + install-hardening milestone. It touches two
|
||||||
registration (cert command), a new internal/config package, test
|
territories: scripts/ (release.sh, install.sh — bash, backend-engineer)
|
||||||
coverage uplift across engine/transport/proxmox/audit, and an opt-in
|
and docs/ + examples/ + README.md (markdown, lead-developer +
|
||||||
pprof endpoint on the daemon. No schema changes, no new security
|
docs-engineer). No Go orchestration code changes, no schema/migration
|
||||||
surface, no packaging/distribution, no UI.
|
changes, no UI, no security/crypto surface, no transport/network
|
||||||
|
surface. The data-engineer, security-engineer, network-engineer, and
|
||||||
Roster changes vs v0.6:
|
devops-engineer personas are deactivated for this milestone.
|
||||||
- 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)
|
### lead-developer (v0.10)
|
||||||
- **Domain**: coordination
|
|
||||||
- **Frameworks**: `cobra`
|
|
||||||
- **Constraints**: `boundary-enforcement`, `offline-first`, `no-redundant-implementations`
|
|
||||||
- **Territory**: `**/*.go`, `cmd/**`, `internal/**`
|
|
||||||
- **Active**: true
|
- **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).
|
- **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.7)
|
### backend-engineer (v0.10)
|
||||||
- **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
|
- **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.
|
- **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.
|
||||||
|
|
||||||
### data-engineer (v0.7)
|
### docs-engineer (v0.10 — phase-specific)
|
||||||
- **Domain**: data
|
- **Active**: true (phase-specific: P2, P3, P4)
|
||||||
- **Frameworks**: `modernc/sqlite`, `iter`
|
- **Territory**: `docs/cli.md`, `docs/jobspec.md`, `docs/ingress.md`,
|
||||||
- **Constraints**: `schema-first`, `migration-safe`, `local-storage-only`, `no-goroutine-leak`, `nullable-column-handling`
|
`examples/full-stack/**`
|
||||||
- **Territory**: `**/store/**`, `**/model.go`, `**/migration*`, `migrations/**`, `internal/store/migrations/**`, `internal/model/node.go`
|
- **Frameworks**: markdown, GitHub-flavored markdown
|
||||||
- **Active**: true
|
- **Constraints**: factual-accuracy-against-codebase,
|
||||||
- **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).
|
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.
|
||||||
|
|
||||||
### cli-engineer (v0.7)
|
### Deactivated personas (v0.10)
|
||||||
- **Domain**: CLI/UX
|
- **data-engineer**: no schema/migration work this milestone.
|
||||||
- **Frameworks**: `cobra`, `pflag`
|
- **security-engineer**: no crypto/threat-model work this milestone.
|
||||||
- **Constraints**: `discoverable-help`, `consistent-flag-naming`, `human-readable-output`, `machine-readable-json-flag`, `signal-handling`, `password-flag-redaction`
|
- **network-engineer**: no transport/socket work this milestone.
|
||||||
- **Territory**: `cmd/**`, `internal/cli/**`, `internal/commands/**`
|
- **devops-engineer**: no packaging/distribution work beyond the
|
||||||
- **Active**: true
|
release.sh fix (owned by backend-engineer).
|
||||||
- **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).
|
- **cli-engineer**: no new CLI commands this milestone.
|
||||||
|
- **frontend-engineer**: no web UI (unchanged from v0.1).
|
||||||
### 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 |
|
| Change | Rationale |
|
||||||
|--------|-----------|
|
|--------|-----------|
|
||||||
|
|||||||
@@ -0,0 +1,140 @@
|
|||||||
|
# Research: v0.10 Docs & Install Milestone
|
||||||
|
|
||||||
|
## Documentation landscape in the orca tree
|
||||||
|
|
||||||
|
### What exists today
|
||||||
|
|
||||||
|
The `docs/` directory contains four files:
|
||||||
|
|
||||||
|
- `docs/install.md` — install guide (user-level, system-level, version
|
||||||
|
pinning, in-place update, troubleshooting). Accurate for v0.5-v0.8
|
||||||
|
but does not mention the v0.9 multi-namespace layout, `--config`, or
|
||||||
|
`--no-deprecation-warnings`.
|
||||||
|
- `docs/docker.md` — Docker image guide. Still documents `orca daemon`
|
||||||
|
(deprecated in v0.9).
|
||||||
|
- `docs/namespace.md` — namespace and paths. Documents the **v0.8 flat
|
||||||
|
layout** (`~/.orca/orca.db`, `ca.crt`, `ca.key`, `server.crt`,
|
||||||
|
`server.key`). Does NOT document the v0.9 multi-namespace layout
|
||||||
|
(`cluster/`, `_defaults/`, per-ns `db/jobs/alloc/ns.md`), `orca ns`
|
||||||
|
subcommands, or the `_defaults` implicit root (D-159/D-185/D-187).
|
||||||
|
- `docs/security-scanning.md` — gosec + govulncheck + gitleaks guide.
|
||||||
|
Accurate; no v0.9 drift.
|
||||||
|
|
||||||
|
### What's missing (the gap this milestone closes)
|
||||||
|
|
||||||
|
1. **No CLI reference doc.** The entire CLI command surface (init, job,
|
||||||
|
node, ns, cert, daemon, doctor, status, audit, version) is
|
||||||
|
undocumented in `docs/`. The README subcommand table is stale (lists
|
||||||
|
only version/init/status/node/job with fake "Phase N" statuses,
|
||||||
|
missing cert/daemon/doctor/audit/ns/node-capacity/node-key-reset).
|
||||||
|
2. **No jobspec reference doc.** The markdown frontmatter schema (kinds,
|
||||||
|
blocks, CEL subset, validation rules, body semantics) is
|
||||||
|
undocumented. Operators must read `internal/jobspec/markdown.go` and
|
||||||
|
`internal/spec/schema/schema.go` source.
|
||||||
|
3. **No ingress/Traefik doc.** The service→Traefik mapping, R-007
|
||||||
|
socket-vs-TCP-bind, atomic reload, drain, TLS — all undocumented.
|
||||||
|
4. **No examples directory.** `testdata/` holds legacy HCL fixtures
|
||||||
|
(`hello.hcl`, `fail.hcl`) for Go tests, not operator-facing
|
||||||
|
examples. No worked full-stack demo exists.
|
||||||
|
5. **README is stale.** Status line says "v0.1: Foundation".
|
||||||
|
Subcommand table missing 5 commands. Install `--version` example
|
||||||
|
pins v0.4.2. Update-in-place example references v0.4.1→v0.4.2.
|
||||||
|
Development section omits 4 make targets.
|
||||||
|
|
||||||
|
### Prior art for CLI reference docs
|
||||||
|
|
||||||
|
- **Nomad**: `nomad job` / `nomad node` / `nomad agent` reference pages,
|
||||||
|
one per subcommand, with flag tables and JSON examples. Orca's
|
||||||
|
single-file `docs/cli.md` is simpler (one file vs a subdirectory) but
|
||||||
|
follows the same flag-table + example convention.
|
||||||
|
- **kubectl**: `kubectl reference` + per-command pages. Too heavy for
|
||||||
|
orca; the single-file model fits the minimalist ethos.
|
||||||
|
- **Docker CLI**: `docker run` reference with flag tables. Matches the
|
||||||
|
shape orca's `docs/cli.md` will take.
|
||||||
|
|
||||||
|
### Prior art for example jobspecs
|
||||||
|
|
||||||
|
- **Nomad example jobs**: `nomad-job-spec.example` files in the Nomad
|
||||||
|
repo showing service + job + sysbatch patterns. Orca's
|
||||||
|
`examples/full-stack/` mirrors this with 5 markdown jobspecs covering
|
||||||
|
Service/Job/DaemonSet + task groups + volumes + replication.
|
||||||
|
- **Kubernetes examples**: `examples/` directory with yaml
|
||||||
|
deployments/services/ingress. Orca's equivalent is the 5 jobspecs +
|
||||||
|
rendered Traefik/systemd artifacts.
|
||||||
|
|
||||||
|
## Release/install pipeline research
|
||||||
|
|
||||||
|
### Root cause of the v0.4.5 install
|
||||||
|
|
||||||
|
Verified via the Gitea API:
|
||||||
|
|
||||||
|
```
|
||||||
|
GET /api/v1/repos/coreci/orca/releases/latest
|
||||||
|
→ tag_name: "v0.8.15"
|
||||||
|
|
||||||
|
GET /api/v1/repos/coreci/orca/releases/tags/v0.8.15
|
||||||
|
→ attachments: [] (zero binary assets)
|
||||||
|
```
|
||||||
|
|
||||||
|
The v0.8.x releases (v0.8.0 through v0.8.15) all shipped with **zero
|
||||||
|
binary assets attached**. Only `v0.4.5` carries a tarball
|
||||||
|
(`orca-v0.4.5-linux-amd64.tar.gz`).
|
||||||
|
|
||||||
|
`scripts/install.sh:70-78` resolves "latest" → v0.8.15, then
|
||||||
|
`install.sh:96-104` looks for `orca-v0.8.15-linux-amd64.tar.gz` in
|
||||||
|
v0.8.15's assets. Since the asset is missing, install.sh errors out
|
||||||
|
(`could not find asset ... in release v0.8.15`). The v0.4.5 install
|
||||||
|
came from an earlier run or a pinned `--version`.
|
||||||
|
|
||||||
|
### Why v0.8.x releases have no assets
|
||||||
|
|
||||||
|
`scripts/release.sh:132-136` calls `tea releases create "$VERSION" ...
|
||||||
|
--asset "$TARBALL"`. The script builds the tarball (line 98) and passes
|
||||||
|
it to `tea`. Two likely failure modes:
|
||||||
|
|
||||||
|
1. **Host arch mismatch**: `release.sh:89-95` builds for the host arch
|
||||||
|
(`uname -m`). If the CI runner or dev machine is arm64, it produces
|
||||||
|
`orca-v0.8.15-linux-arm64.tar.gz`, but `install.sh` looks for
|
||||||
|
`linux-amd64`. The `.coreci.yml:121` release step hardcodes
|
||||||
|
`--asset orca-${VERSION}-linux-amd64.tar.gz`, so the CI runner must
|
||||||
|
be amd64 — but `release.sh` run locally on an arm64 dev machine
|
||||||
|
produces the wrong arch.
|
||||||
|
2. **Silent asset drop**: `tea releases create` has been observed to
|
||||||
|
succeed (exit 0) without attaching the asset in some tea versions.
|
||||||
|
The script treats `tea`'s exit code as success without verifying the
|
||||||
|
asset actually appears in the release.
|
||||||
|
|
||||||
|
### Fix approach (REQ-097, REQ-098)
|
||||||
|
|
||||||
|
**release.sh**:
|
||||||
|
- Cross-build `linux-amd64` explicitly via
|
||||||
|
`GOOS=linux GOARCH=amd64 go build`, regardless of host arch.
|
||||||
|
- After `tea releases create`, query
|
||||||
|
`/api/v1/repos/$OWNER/$REPO/releases/tags/$VERSION` and assert the
|
||||||
|
tarball appears in `attachments`. If not, retry once, then fail
|
||||||
|
loudly with a clear error.
|
||||||
|
|
||||||
|
**install.sh**:
|
||||||
|
- Add an asset fallback walk: if the resolved release (latest or
|
||||||
|
pinned) lacks the matching tarball, query
|
||||||
|
`/releases?limit=20`, walk backward, and use the most recent release
|
||||||
|
that carries the `orca-<ver>-<os>-<arch>.tar.gz` asset. Print a
|
||||||
|
clear warning.
|
||||||
|
- Add `--check` dry-run mode (D-194) that prints the version + asset URL
|
||||||
|
+ install path without writing.
|
||||||
|
|
||||||
|
## Persona assessment (PERSONAS.md)
|
||||||
|
|
||||||
|
This milestone touches two territories:
|
||||||
|
|
||||||
|
1. **`scripts/` (release.sh, install.sh)** — bash scripts, not Go.
|
||||||
|
Backend-engineer territory (API-adjacent tooling). The fix is
|
||||||
|
cross-build + API verification + fallback walk.
|
||||||
|
2. **`docs/` + `examples/` + `README.md`** — markdown documentation.
|
||||||
|
Lead-developer territory (coordination + cross-cutting docs).
|
||||||
|
|
||||||
|
No data-engineer work (no schema/migration changes). No
|
||||||
|
frontend-engineer work (no UI). The data-engineer persona is
|
||||||
|
deactivated for this milestone. A docs-engineer custom persona is
|
||||||
|
created for P2/P3/P4 (markdown authoring with codebase-grounded
|
||||||
|
factual claims).
|
||||||
Reference in New Issue
Block a user