coreci/orca
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 91 Wiki Activity

docs(P00): clarify v0.8 ambiguities (5 decisions, full autonomy)

Browse Source 
D-043 P02 chore vs feat (chore — trust-surface hardening, no new capability)
D-044 --host-key-fingerprint placement (node join root, validated on --type proxmox)
D-045 fingerprint format (OpenSSH SHA256:base64)
D-046 key-reset scope (local known_hosts only, not remote authorized_keys)
D-047 coverage tiered floor (70% for retested, 50% for zero-test packages)

---ci---
project: orca
phase: 0
milestone: v0.8
status: clarify
---/ci---
This commit is contained in:
Jon Chery
2026-08-04 00:38:41 +00:00
parent a052bf20f1
commit a0b3b7439d
3 changed files with 18 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.ciagent/CHECKPOINT.json
+2 -2
View File
@@ -1,11 +1,11 @@
{
"phase": 0,
"stage": "specify",
"stage": "clarify",
"milestone": "v0.8",
"milestone_slug": "coverage-trust-hardening",
"phase_role": "pre_execution",
"attempts": 0,
"updated_at": "2026-08-04T00:40:00Z",
"updated_at": "2026-08-04T00:44:00Z",
"milestone_complete": false,
"next_milestone": null
}
.ciagent/PROJECT.md
+13
View File
@@ -364,3 +364,16 @@ on the trust surface — see CLARIFY D-043 for the `feat` vs `chore`
classification of P02); the final phase's progressive patch IS the
deliverable per `run.md` versioning logic. Tags run on the **v0.7.x**
patch line: `v0.7.0` (P0) … `v0.7.4` (P04 = milestone release).
## v0.8 Clarified Decisions (D-series, full autonomy)
The 5 v0.8 decisions (D-043..D-047) were auto-resolved at full autonomy
within the `clarify_budget` (10):
| ID | Question | Decision | Rationale | Confidence |
|----|----------|----------|-----------|------------|
| D-043 | Is P02 (SSH trust hardening) a `feat` phase or a `chore` phase? It adds a new flag + a new subcommand. | **`chore` (trust-surface hardening), not `feat`** | Both `--host-key-fingerprint` and `orca node key-reset` refine the *existing* `orca node join --type proxmox` flow and the existing TOFU `known_hosts` store (D-035). No new orchestration capability, no new node kind, no new API. They close a security gap explicitly deferred in v0.6, not open new surface area. Per `run.md` versioning logic this keeps v0.8 NFR (all phases fix/test/chore/perf/refactor). | 0.84 |
| D-044 | Where does `--host-key-fingerprint` live — on `orca node join` or only on `--type proxmox`? | **On `orca node join` (root of the join subcommand), validated when `--type proxmox`** | The flag is generic (any future SSH-joined node kind will use it); gating it to `--type proxmox` only would require re-adding it later. Validation (`flag requires --type proxmox today`) happens in `RunE`, not in the flag declaration, so the flag is declared once on `node join` and the type check emits a clear error for non-proxmox types until other SSH-joined kinds exist. | 0.86 |
| D-045 | `--host-key-fingerprint` format — raw hex, `sha256:`-prefixed, or OpenSSH `SHA256:base64`? | **OpenSSH `SHA256:base64` (the format `ssh-keyscan -E sha256 -D -` emits and operators expect)** | Matches the fingerprint format operators already see from `ssh-keyscan` and `orca node join`'s own `Result.HostKeyFingerprint` output. Accept only `SHA256:`-prefixed base64; reject raw hex with a clear error. Internally decode base64 → compare against `ssh.PublicKey` Marshal + sha256. | 0.88 |
| D-046 | Does `orca node key-reset <node>` also revoke the orca pubkey on the remote host, or only clear the local `known_hosts` entry? | **Local `known_hosts` entry only** | Revoking the remote authorized_keys entry would orphan a working node (next dispatch would fail auth). `key-reset` is the local "forget this host's key" operation (mirrors `ssh-keygen -R host`); re-establishing trust is a separate `orca node join` re-run. Audit-log the reset with `actor`, `node`, `event=node.key_reset`. | 0.90 |
| D-047 | Coverage target for P01 — 70% floor or higher? | **70% floor for the 6 under-50% packages; 50% floor for the 3 zero-test packages (`internal/audit`, `internal/certpaths`, `cmd/orca`) as a first-toe-hold** | 70% across the board for the already-tested packages matches D-042's "70% target for new packages" and is achievable without heroic mock effort. For the zero-test packages, going 0→50% is the realistic single-phase step (0→70% risks a coverage rathole on `cmd/orca` which is glue code); a future milestone can lift them to 70%. | 0.82 |
.ciagent/REQUIREMENTS.md
+3 -3
View File
@@ -136,7 +136,7 @@ REQ-047..052 all complete.
| ID | Requirement | Priority | Phase | Status |
|----|-------------|----------|-------|--------|
| REQ-057 | Test coverage uplift round 2: raise `internal/engine` (8.3%), `internal/proxmox` (5.1%), `internal/cli` (27.6%), `internal/transport` (26.3%), `internal/store` (46.7%), `internal/jobspec` (47.6%) to ≥ 70%; add first tests for `internal/audit`, `internal/certpaths`, `cmd/orca` (currently 0% — `go: no such tool "covdata"`) | High | **v0.8 P1** | Pending |
| REQ-058 | `--host-key-fingerprint <sha256>` pre-pin flag on `orca node join --type proxmox`: when supplied, join fails fast if the SSH host key's SHA-256 fingerprint does not match; supersedes TOFU (D-035 future-enhancement hook) for pre-pinned deployments | Medium | **v0.8 P2** | Pending |
| REQ-059 | `orca node key-reset <node>` command: clears the persisted SSH host key for a node from `~/.orca/known_hosts` (or nodes metadata) so the next `doctor proxmox`/dispatch re-pins via TOFU or `--host-key-fingerprint`; closes the D-035 "future" hook from RESEARCH_v0.6 §80 | Low | **v0.8 P2** | Pending |
| REQ-057 | Test coverage uplift round 2: raise `internal/engine` (8.3%), `internal/proxmox` (5.1%), `internal/cli` (27.6%), `internal/transport` (26.3%), `internal/store` (46.7%), `internal/jobspec` (47.6%) to ≥ 70%; add first tests for `internal/audit`, `internal/certpaths`, `cmd/orca` (currently 0%) to ≥ 50% (D-047 tiered floor) | High | **v0.8 P1** | Pending |
| REQ-058 | `--host-key-fingerprint <SHA256:base64>` pre-pin flag on `orca node join` (validated when `--type proxmox`): when supplied, join fails fast if the SSH host key's OpenSSH SHA-256 fingerprint does not match; supersedes TOFU (D-035) for pre-pinned deployments (D-044, D-045) | Medium | **v0.8 P2** | Pending |
| REQ-059 | `orca node key-reset <node>` command: clears the persisted SSH host key entry for the node from `~/.orca/known_hosts` only (local, not remote authorized_keys — D-046); audit-logs `event=node.key_reset`; next `doctor proxmox`/dispatch re-pins via TOFU or `--host-key-fingerprint` | Low | **v0.8 P2** | Pending |
| REQ-060 | Requirement-status hygiene sweep: REQUIREMENTS.md v0.7 rows were stale ("Pending" after ship); add a verify-stage assertion that every REQ listed as `Complete` in ROADMAP.md has a matching `Complete` row in REQUIREMENTS.md, enforced by `make verify-reqs` | Medium | **v0.8 P3** | Pending |