orca/.ciagent/PLAN_v0.8.md

Phase Plans: Orca v0.8 — Coverage & Trust Hardening

All 4 execution phases + final review with vertical-slice structure, wave ordering, persona assignment, and REQ-ID mapping. v0.8 scope: Coverage & Trust Hardening — round-2 test coverage uplift across 9 packages (tiered floor: ≥70% for 6 retested, ≥50% for 3 zero-test per D-047), SSH trust hardening (--host-key-fingerprint pre-pin + orca node key-reset + latent TOFU capture-fix + Result.HostKeyFingerprint population), and a requirements-hygiene gate (make verify-reqs).

Branching: phase/01-coverage-round2..phase/04-final-review-ship on the milestone/v0.8-coverage-trust-hardening branch (numbering restarts per milestone per branch-strategy.md).

Milestone type: NFR (P01 test, P02 chore on the trust surface per D-043, P03 chore, P04 docs/review). Tags run on the v0.7.x patch line: v0.7.0 (P0) … v0.7.4 (P04 = milestone release).

Vertical-slice integrity: each phase is independently shippable.

• P01 ships tests-only (no production code changes except the proxmox sessionRunner seam, a backward-compatible interface extraction, and the engine peerDispatcher seam per RESEARCH §1.3).
• P02 ships the SSH trust features + TOFI bugfix + Result population.
• P03 ships the hygiene gate (Go program + Makefile + CI hook).
• P04 is review + ship + audit (no new REQs).

Out of scope for v0.8 (candidate for v0.9, noted not added):

• Lifting the 3 zero-test packages from 50% → 70% (D-047 explicitly toes-holds them; v0.9 can raise the floor).
• A peerDispatcher interface seam in engine beyond what P01 needs for 70% coverage (httptest.NewTLSServer suffices; the seam is only added if coverage cannot otherwise hit 70%).
• Pre-populating known_hosts from a remote keyscan API (TOFU + manual --host-key-fingerprint cover the v0.8 trust surface).
• verify-reqs reverse-direction check (REQUIREMENTS Complete ↔ ROADMAP COMPLETE both ways) — forward direction (ROADMAP-shipped → REQUIREMENTS Complete) is the priority per the v0.7 drift that motivated REQ-060.

Carried-forward research findings (RESEARCH_v0.8.md, must incorporate):

• §1.1 per-package coverage strategies + tiered floors (D-047).
• §1.3 injected seams: reuse sshDialer (proxmox), LocalExecutor (engine), Dispatcher (transport), watchInterval (store), openTestDB/withFastWatch/initTestEnv/resetRootFlags/stubDispatcher helpers.
• §1.4 realism flags: cli excludes daemon.go; cmd/orca 50% toe-hold only; proxmox needs the sessionRunner seam to hit 70%.
• §2.1 latent TOFU capture bug (knownhosts.New returns KeyError{Want:[]} on first connect and does NOT auto-write — current BootstrapProxmox treats it as a dial failure).
• §2.2 Result.HostKeyFingerprint is declared but never populated (always ""); P02 must add ssh.FingerprintSHA256 computation.
• §2.3 --host-key-fingerprint plugs in at internal/cli/node.go (flag) + internal/proxmox/bootstrap.go (pinned callback).
• §2.4 key-reset is local-known_hosts-only (D-046), atomic rewrite (AD-029).
• §3 verify-reqs is a Go program at cmd/verify-reqs/main.go (~80 LOC, stdlib only, AD-030) + make verify-reqs + .coreci.yml validate hook.
• §4 AD-025..AD-030 (renumbered AD-027..AD-030 in research for SSH/trust; AD-025/AD-026 from earlier milestones are stable).
• §5 10 pitfalls carried into the risk register at the end of this file.

Dependencies (RESEARCH §6): v0.8 adds zero new direct dependencies. ssh.FingerprintSHA256, knownhosts.Line/Normalize/KeyError are in the existing golang.org/x/crypto v0.54.0 dep. verify-reqs is stdlib-only. go.mod is unchanged by v0.8.

---

Phase 1: Coverage Uplift Round 2 (REQ-057)

Branch: phase/01-coverage-round2 REQ Coverage: REQ-057 Tag: v0.7.1 Depends on: Phase 0 (this plan + clarify + research) Source research: RESEARCH_v0.8.md §1 (per-package strategies, helpers, seams)

Tiered floor (D-047)

Package	Current	Floor	Owner persona
internal/engine	8.3%	≥ 70%	backend-engineer
internal/proxmox	5.1%	≥ 70%	backend-engineer
internal/cli	27.6%	≥ 70% (excluding daemon.go)	lead-developer
internal/transport	26.3%	≥ 70%	backend-engineer
internal/store	47.2%	≥ 70%	data-engineer
internal/jobspec	47.6%	≥ 70%	data-engineer
internal/audit	0% (no tests)	≥ 50% toe-hold	data-engineer
internal/certpaths	0% (no tests)	≥ 50% toe-hold	data-engineer
cmd/orca	0% (no tests)	≥ 50% toe-hold	lead-developer

Wave 1 — Seams + foundational test helpers (no production logic changes)

These are backward-compatible interface extractions that unlock the bulk of coverage in Wave 2. They are the only production-code changes in P01; all other P01 tasks add _test.go files only.

Task ID	Owner	Wave	Must	Title	Files touched	Acceptance criterion
T01.1	backend-engineer	1	Y	Add sessionRunner interface seam to proxmox	internal/proxmox/bootstrap.go	Extract a sessionRunner interface (CombinedOutput(cmd string) ([]byte, error)) ~10 LOC; default impl wraps *ssh.Client.NewSession().CombinedOutput(...); runRemote/deployPubKey/createLinuxUser/createPVERole/createPVEUser/assignPVEACL/writeSudoers/validateSudoers use the seam. Backward compatible: existing callers unchanged. go build ./internal/proxmox PASS. (RESEARCH §1.3 gap #1, §5 pitfall #3)
T01.2	backend-engineer	1	N	Add peerDispatcher seam to engine (only if needed for 70%)	internal/engine/dispatcher.go	Extract a peerDispatcher interface (Submit(ctx, spec, key) (*SubmitResponse, error)) so dispatchToPeer is testable without httptest.NewTLSServer. Only add if T01.5 cannot otherwise hit 70% via httptest.NewTLSServer alone. If added, backward compatible. (RESEARCH §1.3 gap #2, §5 pitfall #8)

Wave 2 — Per-package coverage tests (build on Wave 1 seams)

Task ID	Owner	Wave	Must	Title	Files touched	Acceptance criterion
T01.3	backend-engineer	2	Y	internal/transport tests → ≥ 70%	internal/transport/mtls_test.go (NEW), internal/transport/dispatch_test.go (NEW), internal/transport/handshake_log_test.go (NEW), internal/transport/retry_test.go (NEW, extend)	httptest.NewTLSServer with a test CA (reuse security.CAInit/GenerateCSR/SignCSR per RESEARCH §1.2) for mTLS handshake paths; stubDispatcher (daemon/dispatch_test.go:24) pattern for Dispatch RPC; capture slog via a test slog.Handler for handshake_log. go test -cover ./internal/transport → ≥ 70% (was 26.3%).
T01.4	backend-engineer	2	Y	internal/engine tests → ≥ 70%	internal/engine/executor_test.go (NEW), internal/engine/dispatcher_test.go (NEW), internal/engine/peer_test.go (NEW), internal/engine/scheduler_test.go (extend), internal/engine/registry_test.go (NEW, if registry exists)	Executor.Start/Wait lifecycle (echo/false/ctx-cancel/Env propagation per REQ-021); Dispatcher.Submit with stubbed LocalExecutor + (if T01.2 added) stubbed peerDispatcher OR httptest.NewTLSServer; PeerRegistry in-memory Add/Remove/All/Get. Reuse openTestDB (node_repo_test.go:12). go test -cover ./internal/engine → ≥ 70% (was 8.3%).
T01.5	backend-engineer	2	Y	internal/proxmox tests → ≥ 70%	internal/proxmox/bootstrap_test.go (extend)	Swap sshDialer (existing seam) for a fake returning a mock *ssh.Client; swap sessionRunner (T01.1 seam) for a fake that returns canned CombinedOutput bytes. Assert full bootstrap sequence calls the right shell commands in order; idempotent re-run ("already exists" → no-op); SSH auth failure → wrapped error; no password logged (D-031). go test -cover ./internal/proxmox → ≥ 70% (was 5.1%).
T01.6	lead-developer	2	Y	internal/cli tests → ≥ 70% (excluding daemon.go) with GRILL condition #3 escape valve	internal/cli/node_test.go (NEW), internal/cli/job_test.go (NEW), internal/cli/cert_test.go (NEW), internal/cli/doctor_test.go (NEW), internal/cli/audit_test.go (NEW), internal/cli/status_test.go (NEW), internal/cli/version_test.go (NEW), internal/cli/node_capacity_test.go (NEW)	Table-driven rootCmd.Execute() against temp ORCA_HOME per subcommand (reuse initTestEnv/resetRootFlags/discardWriter per RESEARCH §1.2). Mock the proxmox path via sshDialer + sessionRunner seams. daemon.go is excluded — covered by internal/daemon/server_test.go. go test -cover ./internal/cli → ≥ 70% of non-daemon files (document the exclusion in a test-file comment). GRILL condition #3 escape valve: if 70% is not reached after Wave 2 effort and ≥ 65% is achieved (RESEARCH §1.4 flags 55-65% as realistic for one phase), ship cli at 65% and do NOT block P02/P03 on the last 5%; record the shortfall + rationale in the P01 verification commit.
T01.7	data-engineer	2	Y	internal/store tests → ≥ 70% (incl. missing cert_repo_test.go)	internal/store/cert_repo_test.go (NEW — v0.7 P01 leftover, RESEARCH §1.1), internal/store/node_repo_test.go (extend), internal/store/job_task_repo_test.go (extend), internal/store/audit_repo_test.go (extend), internal/store/capacity_repo_test.go (extend)	cert_repo_test.go: Insert/Get/List/ListByNode/LatestForKind/PruneOlderThan/Delete + N=3 rotation history per REQ-025 + duplicate-serial error. Reuse openTestDB/withFastWatch (RESEARCH §1.2). go test -cover ./internal/store → ≥ 70% (was 47.2%).
T01.8	data-engineer	2	Y	internal/jobspec tests → ≥ 70%	internal/jobspec/spec_test.go (extend), internal/jobspec/testdata/*.hcl (NEW golden fixtures)	Golden-file HCL fixtures (multi-task, env vars, args) + error-path table (missing job, no tasks, missing command, malformed HCL, empty file, nonexistent file for ParseFile). go test -cover ./internal/jobspec → ≥ 70% (was 47.6%).
T01.9	data-engineer	2	Y	internal/audit first tests → ≥ 50% toe-hold	internal/audit/audit_test.go (NEW)	Construct Audit with real engine.Audit backed by :memory: sqlite (via store.NewAuditRepo + engine.NewAudit); assert rows in audit_log table; capture slog via a test slog.Handler for LogHandshakeOK/LogHandshakeFailed. go test -cover ./internal/audit → ≥ 50% (was 0%).
T01.10	data-engineer	2	Y	internal/certpaths first tests → ≥ 50% toe-hold	internal/certpaths/certpaths_test.go (NEW)	Temp dir + t.Setenv("ORCA_HOME", dir) + assert each *Path() returns filepath.Join(dir, <file>); test ORCA_DB override; test default-to-~/.orca fallback. Model on namespace_test.go (cli). go test -cover ./internal/certpaths → ≥ 50% (was 0%).
T01.11	lead-developer	2	Y	cmd/orca smoke test → ≥ 50% toe-hold	cmd/orca/main_test.go (NEW), possibly cmd/orca/main.go (refactor main() into run() int for testability)	Refactor main() to run() int (returns exit code; main() calls os.Exit(run())) so the test can call run() directly with a forced error path and assert non-zero exit + stderr contains "error:". Low-effort toe-hold — do NOT over-invest (RESEARCH §1.1, §5 pitfall #6). go test -cover ./cmd/orca → ≥ 50% (was 0%).

Wave 3 — Coverage gate verification

Task ID	Owner	Wave	Must	Title	Files touched	Acceptance criterion
T01.12	lead-developer	3	Y	Coverage-gate verification (all 9 packages hit tiered floor)	none (verification only)	go test -cover ./internal/engine ./internal/proxmox ./internal/cli ./internal/transport ./internal/store ./internal/jobspec → each ≥ 70%; go test -cover ./internal/audit ./internal/certpaths ./cmd/orca → each ≥ 50%. go test -race ./... PASS. Any races fixed in-phase (not deferred).

Phase 1 Must-Haves (summary)

All 9 packages hit their tiered floor (D-047): T01.1, T01.3, T01.4, T01.5, T01.6, T01.7, T01.8, T01.9, T01.10, T01.11, T01.12. T01.2 is conditional (only if needed for engine 70%).

Phase 1 Verification

• go build ./... PASS
• go vet ./... PASS
• go test -race ./... PASS
• Per-package coverage hits the tiered floor (T01.12)
• The proxmox sessionRunner seam is backward compatible (existing BootstrapProxmox callers unchanged)
• No new direct deps (go.mod unchanged)

---

Phase 2: SSH Trust Hardening (REQ-058, REQ-059)

Branch: phase/02-ssh-trust-hardening REQ Coverage: REQ-058, REQ-059 Tag: v0.7.2 Depends on: Phase 1 (proxmox sessionRunner seam from T01.1 is in place; the trust-surface code is now testable) Source research: RESEARCH_v0.8.md §2 (TOFU bug, fingerprint computation, flag wiring, key-reset atomic rewrite) + §4 AD-027..AD-029 Phase type: chore (trust-surface hardening per D-043 — refines existing orca node join --type proxmox flow + existing TOFU known_hosts store; no new orchestration capability)

Wave 1 — Trust-surface foundations (security helpers + flag declarations)

Task ID	Owner	Wave	Must	Title	Files touched	Acceptance criterion
T02.1	backend-engineer	1	Y	Add security.SSHFingerprintSHA256 helper (AD-027)	internal/security/sshkey.go (extend) OR internal/security/fingerprint.go (extend)	Thin wrapper over ssh.FingerprintSHA256(pubKey ssh.PublicKey) string returning the canonical SHA256:base64 string. Do NOT reuse security.Fingerprint (X.509 hex — different domain per RESEARCH §2.2). Unit test: known Ed25519 pub key → known SHA256: string.
T02.2	backend-engineer	1	Y	Export security.WriteAtomic (AD-029 enabler)	internal/security/ca.go	Rename writeAtomic → WriteAtomic (export) + update existing in-package callers. The key-reset atomic known_hosts rewrite (T02.7) needs it. Alternatively copy the ~20-LOC pattern into proxmox if export is undesirable — recommend export (RESEARCH §5 pitfall #10). go build ./internal/security PASS.
T02.3	backend-engineer	1	Y	Add --host-key-fingerprint flag on orca node join (D-044)	internal/cli/node.go	nodeJoinCmd.Flags().StringVar(&joinHostKeyFP, "host-key-fingerprint", "", "SSH host key SHA256:base64 fingerprint (pre-pin; supersedes TOFU for --type proxmox)") in the flag-registration block (node.go:344-354). Add joinHostKeyFP string to the var block (node.go:47-60). Validation in RunE: if joinHostKeyFP != "" and --type != proxmox, emit a clear error ("--host-key-fingerprint requires --type proxmox today"). Flag is generic for future SSH-joined kinds (D-044).
T02.4	backend-engineer	1	Y	Add HostKeyFingerprint field to proxmox.Options	internal/proxmox/bootstrap.go	Add HostKeyFingerprint string to the Options struct (bootstrap.go:55). Pass-through from internal/cli/node.go joinProxmox (node.go:158-166): HostKeyFingerprint: joinHostKeyFP.

Wave 2 — Trust features + bugfix (build on Wave 1)

Task ID	Owner	Wave	Must	Title	Files touched	Acceptance criterion
T02.5	backend-engineer	2	Y	Implement pinnedHostKeyCallback (REQ-058, AD-028)	internal/proxmox/bootstrap.go	pinnedHostKeyCallback(expectedSHA256Base64 string) (ssh.HostKeyCallback, error): validate SHA256: prefix up front (reject raw hex with a clear error per D-045); callback receives server's ssh.PublicKey, computes ssh.FingerprintSHA256(key) (via T02.1 helper or inline), compares full strings to the operator-supplied value; returns nil on match, error on mismatch (fail closed). In BootstrapProxmox: if opts.HostKeyFingerprint != "" use pinnedHostKeyCallback, else fall back to the TOFU callback (T02.6). Unit test: match → callback returns nil; mismatch → returns error mentioning REQ-058; non-SHA256:-prefixed input → constructor returns error.
T02.6	backend-engineer	2	Y	BUGFIX (v0.6 ship-defect): FIX the latent TOFU capture bug (RESEARCH §2.1, §5 pitfall #1, GRILL condition #1)	internal/proxmox/bootstrap.go	Wrap knownhosts.New(...) with a custom callback that: on *knownhosts.KeyError{Want: []} (host unknown) captures the server-presented ssh.PublicKey, writes a line via knownhosts.Line([]string{knownhosts.Normalize(addr)}, key) to certpaths.KnownHostsPath() using security.WriteAtomic (T02.2, AD-029), and returns nil (allow the dial to proceed). On *knownhosts.KeyError{Want: [knownKey]} (mismatch) returns the error (MITM detection). On nil (host present + match) returns nil. This fixes the v0.6 latent ship-defect where first-connect Proxmox join always failed (verified against golang.org/x/crypto@v0.54.0/ssh/knownhosts/knownhosts.go:370-385). P04 audit must record this as ship-defect closure. Unit test: first-connect captures the key + writes known_hosts; second-connect matches; mismatch-connect fails.
T02.7	backend-engineer	2	Y	Populate Result.HostKeyFingerprint (RESEARCH §2.2, §5 pitfall #2)	internal/proxmox/bootstrap.go	In the capture path (T02.6) and the pinned path (T02.5), set Result.HostKeyFingerprint = ssh.FingerprintSHA256(hostKey) (via T02.1). The field is currently declared (bootstrap.go:83-85) but always "". After T02.7, orca node join --type proxmox output includes the real fingerprint. Unit test: Result.HostKeyFingerprint is non-empty + SHA256:-prefixed after a successful bootstrap.
T02.8	backend-engineer	2	Y	Implement orca node key-reset <node> (REQ-059, D-046, AD-029)	internal/cli/node.go, internal/proxmox/bootstrap.go (new ResetHostKey helper OR inline in cli)	New nodeKeyResetCmd (&cobra.Command{Use: "key-reset <node>", Args: cobra.ExactArgs(1), RunE: ...}) registered via nodeCmd.AddCommand(nodeKeyResetCmd) (node.go:358-360). RunE: (1) resolve <node> arg via nodeRegistry() (node.go:37) → get node row → use node.Name (the host address for proxmox nodes) as the known_hosts match key; (2) call proxmox.ResetHostKey(host) error which reads certpaths.KnownHostsPath(), filters lines whose host field (before first whitespace, normalized via knownhosts.Normalize) matches, rewrites via security.WriteAtomic (T02.2); (3) audit-log event=node.key_reset with actor+node+host via engine.Audit.Record; (4) print ✓ Host key reset for <node> (next connect will re-pin via TOFU or --host-key-fingerprint). Local only — do NOT revoke remote authorized_keys (D-046). Unit test: known_hosts with 2 entries for the target host + 1 for another host → after reset, target's 2 lines removed, other host's line intact; audit row inserted.
T02.9	backend-engineer	2	Y	Apply the TOFU capture-fix to doctor proxmox probe (GRILL condition #2 — doctor parity with bootstrap)	internal/doctor/doctor.go	The doctor proxmox probe (doctor.go:412-415) uses the same knownhosts.New(...) callback pattern as bootstrap. Apply the same capture-fix wrapper (T02.6) so doctor proxmox on a first-connect node doesn't fail. P02 is not complete until both bootstrap (T02.6) and doctor (T02.9) callbacks use the capture-fix wrapper — GRILL condition #2 binding parity check. (If the doctor probe already relies on a prior node join having populated known_hosts, the fix is still correct — it makes the doctor robust to a missing entry.)

Wave 3 — End-to-end integration + verification

Task ID	Owner	Wave	Must	Title	Files touched	Acceptance criterion
T02.10	backend-engineer	3	Y	End-to-end trust-surface integration tests	internal/proxmox/bootstrap_test.go (extend), internal/cli/node_test.go (extend)	(1) --host-key-fingerprint with a correct pin → bootstrap succeeds + Result.HostKeyFingerprint matches the pin; (2) --host-key-fingerprint with a wrong pin → bootstrap fails fast with the REQ-058 mismatch error; (3) no --host-key-fingerprint + first connect (empty known_hosts) → TOFU captures the key + writes known_hosts + bootstrap succeeds; (4) no flag + second connect (known_hosts has the key) → matches + succeeds; (5) no flag + mismatch (known_hosts has a different key) → fails with MITM error; (6) orca node key-reset <node> → known_hosts entry removed + audit row inserted + next connect re-pins; (7) known_hosts pre-populated (v0.6→v0.8 migration path: existing entry from a prior join) → second-connect matches without re-capture, covering the upgrade path.
T02.11	backend-engineer	3	Y	--host-key-fingerprint non-proxmox type validation test	internal/cli/node_test.go (extend)	orca node join --type linux --host-key-fingerprint SHA256:... → clear error ("--host-key-fingerprint requires --type proxmox today"). Validates D-044 RunE check from T02.3.

Phase 2 Must-Haves (summary)

• T02.1, T02.2, T02.3, T02.4 (Wave 1 foundations)
• T02.5 (--host-key-fingerprint pinned callback — REQ-058)
• T02.6 (TOFU capture-fix — latent bug)
• T02.7 (Result.HostKeyFingerprint populated)
• T02.8 (orca node key-reset — REQ-059)
• T02.9 (doctor proxmox TOFU fix)
• T02.10, T02.11 (integration + validation)

Phase 2 Verification

• go build ./... PASS
• go vet ./... PASS
• go test -race ./internal/proxmox/... ./internal/cli/... ./internal/doctor/... ./internal/security/... PASS
• ./bin/orca node join --help shows --host-key-fingerprint flag
• ./bin/orca node key-reset --help shows the key-reset subcommand
• Pinned mismatch → fail closed (T02.10 case 2)
• TOFU first-connect → captures + succeeds (T02.10 case 3)
• Result.HostKeyFingerprint is non-empty after bootstrap (T02.7)
• key-reset removes only the target host's known_hosts lines + audit-logs (T02.8)
• No new direct deps

---

Phase 3: Requirements-Hygiene Gate (REQ-060)

Branch: phase/03-verify-reqs REQ Coverage: REQ-060 Tag: v0.7.3 Depends on: Phase 2 (P03 is independent of P02 code, but ships after per ROADMAP ordering; the verify-reqs program parses the .ciagent/ markdown which is stable by P03) Source research: RESEARCH_v0.8.md §3 (Makefile, .coreci.yml, parsing approach, AD-030) + §4 AD-030

Wave 1 — Go program

Task ID	Owner	Wave	Must	Title	Files touched	Acceptance criterion
T03.1	lead-developer	1	Y	cmd/verify-reqs/main.go — Go program (~80 LOC, stdlib only, AD-030, GRILL condition #4 regex + reverse direction)	cmd/verify-reqs/main.go (NEW)	Parses .ciagent/ROADMAP.md + .ciagent/REQUIREMENTS.md using regexp (stdlib). Forward assertion: for every REQ-ID in REQUIREMENTS.md whose Phase column references a milestone that ROADMAP marks COMPLETE (substring-match COMPLETE within the bold span — NOT exact \*\*COMPLETE\*\* which misses v0.2's **COMPLETE (merged to main via v0.3)** header at ROADMAP.md:23), the REQUIREMENTS Status must be Complete. Reverse assertion (GRILL condition #4): for every REQ-ID in REQUIREMENTS.md marked Complete, the corresponding milestone in ROADMAP.md must be marked COMPLETE. Regex: REQUIREMENTS row ^|\s*(REQ-\d+)\s*|.*?|\s*\*\*(Complete|Pending)\*\*\s*|; ROADMAP milestone-complete ^##\s*Milestone\s+v0\.\d+:.*—\s*\*\*COMPLETE[^\*]*\*\* (substring tolerant); map milestone → REQs via the REQUIREMENTS Phase column (e.g. v0.7 P1 → milestone v0.7). Exit 0 on consistency; exit 1 with a diff listing (REQ-ID + current status + expected status + direction) on drift. CLI: go run ./cmd/verify-reqs .ciagent/ROADMAP.md .ciagent/REQUIREMENTS.md (args optional; defaults to those paths). Scope note (GRILL): REQ-060 catches doc-vs-doc drift only; code-vs-doc drift (e.g. the REQ-053 cert_repo_test.go omission — verified missing) is out of scope for this gate and handled by P04 ciagent-audit.
T03.2	lead-developer	1	Y	cmd/verify-reqs/main_test.go — golden-file tests	cmd/verify-reqs/main_test.go (NEW), cmd/verify-reqs/testdata/ (NEW: roadmap_clean.md, requirements_clean.md, roadmap_drift.md, requirements_drift.md)	(1) Clean pair (ROADMAP v0.X COMPLETE + REQUIREMENTS REQ-XXX Complete) → exit 0, no diff; (2) Drift pair (ROADMAP v0.X COMPLETE + REQUIREMENTS REQ-XXX Pending) → exit 1 + diff lists the stale REQ; (3) Multiple drifts → all reported; (4) Missing args → uses defaults; (5) Malformed markdown → clear error (not a silent pass).

Wave 2 — Makefile + CI hook

Task ID	Owner	Wave	Must	Title	Files touched	Acceptance criterion
T03.3	lead-developer	2	Y	make verify-reqs target	Makefile	Add verify-reqs target: go run ./cmd/verify-reqs .ciagent/ROADMAP.md .ciagent/REQUIREMENTS.md. Add to .PHONY. make verify-reqs exits 0 on the current repo (REQUIREMENTS was corrected during v0.8 SPECIFY).
T03.4	lead-developer	2	Y	.coreci.yml validate-pipeline hook	.coreci.yml	Add a verify-reqs step to the validate pipeline (after go-version, alongside gosec/govulncheck/gitleaks per RESEARCH §3.2): image: golang:1.25, commands: [make verify-reqs]. Pipeline fails on drift.

Wave 3 — Synthetic drift verification

Task ID	Owner	Wave	Must	Title	Files touched	Acceptance criterion
T03.5	lead-developer	3	Y	Synthetic drift verification (REQ-060 acceptance)	none (verification only; temporarily flip a REQUIREMENTS row to Pending in a scratch commit, run make verify-reqs, assert exit 1 + diff, then revert)	(1) make verify-reqs on the current repo → exit 0; (2) flip one v0.7 REQ row to Pending in a scratch edit → make verify-reqs → exit 1 + diff lists that REQ-ID; (3) revert the scratch edit → exit 0. This is the REQ-060 acceptance criterion ("passes on current repo + fails on synthetic drift").

Phase 3 Must-Haves (summary)

T03.1, T03.2, T03.3, T03.4, T03.5 — all must complete for the hygiene gate to ship.

Phase 3 Verification

• go build ./cmd/verify-reqs PASS
• go test ./cmd/verify-reqs/... PASS (golden-file tests)
• make verify-reqs → exit 0 on the current repo
• Synthetic drift → make verify-reqs exit 1 + diff (T03.5)
• .coreci.yml validate pipeline includes the verify-reqs step
• No new direct deps (stdlib only)

---

Phase 4: Final Review + Ship + Audit (no new REQs)

Branch: phase/04-final-review-ship REQ Coverage: all (REQ-057..060) Tag: v0.7.4 (milestone release) Depends on: Phase 1 + Phase 2 + Phase 3 Source: milestone-release checklist (matches PLAN_v0.7 P05 structure)

Wave 1 — Review + audit

Task ID	Owner	Wave	Must	Title	Files touched	Acceptance criterion
T04.1	lead-developer	1	Y	Multi-persona code review across all v0.8 phases	none (review only)	ciagent-review across P01..P03; P0 issues fixed in-phase; P1+ recorded in .ciagent/ for post-hoc.
T04.2	lead-developer	1	Y	Audit: reconstruction test + branch hygiene + commit discipline	none (audit only)	ciagent-audit: git log matches .ciagent/ files; branch hygiene clean; commit discipline enforced.

Wave 2 — Ship

Task ID	Owner	Wave	Must	Title	Files touched	Acceptance criterion
T04.3	lead-developer	2	Y	Merge phase/04 → milestone/v0.8-coverage-trust-hardening	none	Fast-forward merge (or rebase-then-fast-forward per config).
T04.4	lead-developer	2	Y	Merge milestone/v0.8 → main	none	Rebase-then-fast-forward per config.
T04.5	lead-developer	2	Y	Tag v0.7.4 (milestone release)	none	git tag v0.7.4 on the merged main HEAD. Per-phase tags v0.7.0..v0.7.4 all present.
T04.6	lead-developer	2	Y	Create Gitea release v0.7.4 with milestone summary	none	Release notes cover all 4 phases + REQ-057..060 + coverage deltas + trust-surface additions.

Wave 3 — Post-ship bookkeeping

Task ID	Owner	Wave	Must	Title	Files touched	Acceptance criterion
T04.7	lead-developer	3	Y	Update REQUIREMENTS.md — mark REQ-057..060 Complete	.ciagent/REQUIREMENTS.md	All 4 v0.8 REQ rows show **Complete** with phase + ship tag. make verify-reqs still passes (self-consistency).
T04.8	lead-developer	3	Y	Update ROADMAP.md — mark v0.8 COMPLETE	.ciagent/ROADMAP.md	v0.8 milestone section shows **COMPLETE**; all phase checkboxes [x]. make verify-reqs still passes.
T04.9	lead-developer	3	Y	Write + clear checkpoint	.ciagent/ checkpoint	{phase: 4, stage: "complete", phase_role: "final", milestone_complete: true}; then clear checkpoint (milestone complete; next run starts a new milestone).

Phase 4 Must-Haves (summary)

All tasks (T04.1..T04.9) are must-haves — the final-review phase has no optional work.

Phase 4 Verification

• make build PASS
• make test PASS
• make lint PASS
• make verify-reqs PASS
• go vet ./... PASS
• git log on main shows all v0.8 phase commits
• git tag --list 'v0.7.*' shows v0.7.0..v0.7.4
• REQUIREMENTS.md shows REQ-057..060 as Complete
• ROADMAP.md shows v0.8 as COMPLETE
• Gitea release v0.7.4 published with milestone summary

---

Phase 5: Final Review (next milestone, not part of v0.8 execution)

Per the v0.8 ROADMAP, there are 4 execution phases (P01..P04). P04 IS the final review + ship + audit phase. There is no separate P05 in v0.8 (unlike v0.7 which had P05). The orchestrator's next-milestone P0 begins after T04.9 clears the checkpoint.

---

Risk Register (carried forward from RESEARCH_v0.8.md §5)

#	Pitfall	Phase(s) affected	Mitigation
1	TOFU capture is currently BROKEN: knownhosts.New returns KeyError{Want:[]} on first connect and does NOT auto-write; current BootstrapProxmox treats it as a dial failure.	P02	T02.6 wraps the callback to capture-and-persist on KeyError{Want:[]} via knownhosts.Line + security.WriteAtomic. This is a v0.6 latent bug that P02 closes.
2	Result.HostKeyFingerprint is declared but never populated (always ""). D-045's rationale references "existing output" that doesn't exist.	P02	T02.7 adds ssh.FingerprintSHA256(hostKey) computation in both the capture and pinned paths. 1-line addition once the host key is available.
3	No sessionRunner seam in proxmox — testing the SSH command sequence without a real SSH server is impossible.	P01	T01.1 adds a 1-interface ~10-LOC sessionRunner seam in Wave 1. Unlocks ~40% of proxmox coverage. Backward compatible.
4	internal/store/cert_repo.go has NO test — v0.7 P01 REQ-053 was supposed to add cert_repo_test.go but it's missing (v0.7 leftover).	P01	T01.7 adds cert_repo_test.go (Insert/Get/List/ListByNode/LatestForKind/PruneOlderThan/Delete + N=3 rotation). Directly lifts store coverage toward 70%.
5	internal/cli/daemon.go starts a long-running mTLS server — testing it in cli requires a lifecycle harness; it's already covered by internal/daemon/server_test.go.	P01	T01.6 excludes daemon.go from the cli 70% target; documents the exclusion in a test-file comment. Avoids double-testing.
6	cmd/orca 50% toe-hold is low-value (15 LOC of glue; effort:coverage ratio is poor).	P01	T01.11 keeps it at the 50% toe-hold per D-047; does NOT over-invest. A small run() int refactor enables a smoke test.
7	go: no such tool "covdata" for zero-test packages — a Go toolchain quirk when a package has no test files; NOT a real 0% number.	P01	T01.9, T01.10, T01.11 each add a _test.go file, which makes coverage computable. Don't treat the tooling error as a measurement.
8	transport.dispatchToPeer has no seam — testing the remote-dispatch branch requires a new interface OR httptest.NewTLSServer.	P01	T01.3 uses httptest.NewTLSServer (no refactor needed). T01.2 (conditional peerDispatcher seam) is only added if engine cannot otherwise hit 70%.
9	knownhosts.Line + knownhosts.Normalize are the helpers for the TOFU-capture fix and key-reset matching.	P02	T02.6 + T02.8 use Normalize to match host strings consistently (handles host:22 vs host).
10	security.writeAtomic is unexported (ca.go:305); key-reset's atomic known_hosts rewrite needs it.	P02	T02.2 exports WriteAtomic (recommended) OR copies the ~20-LOC pattern. Export is preferred — it's already used across ca.go + sshkey.go.

---

REQ-ID → Task mapping (traceability)

REQ-ID	Phase	Tasks
REQ-057	P01	T01.1, T01.2 (conditional), T01.3, T01.4, T01.5, T01.6, T01.7, T01.8, T01.9, T01.10, T01.11, T01.12
REQ-058	P02	T02.1, T02.3, T02.4, T02.5, T02.7, T02.10, T02.11
REQ-059	P02	T02.2, T02.8, T02.10
REQ-060	P03	T03.1, T03.2, T03.3, T03.4, T03.5
(latent TOFU bug)	P02	T02.6, T02.9 (not a REQ — closes a v0.6 gap surfaced by RESEARCH §2.1)
(milestone release)	P04	T04.1..T04.9

---

Task counts

Phase	Tasks	Must-haves	Waves
P01	12	11 (T01.2 conditional)	3
P02	11	11	3
P03	5	5	3
P04	9	9	3
Total	37	36	—