orca/.ciagent/CLARIFY_v0.13.md

CLARIFY v0.13: Production Hardening Round 2 + UAT Plan

Status: resolved (full autonomy, 2026-08-07). All 7 clarifications resolved with the operator's locked decisions (D-248..D-254). No open questions remain for Phase 0. The --ideate flag was passed; three deep codebase sweeps drove the requirements.

Resolved clarifications

C1 — Milestone version (resolved)

Question: v0.12 is complete; the v1.0.0 tag is deferred for UAT. Is this hardening round v1.0 (the UAT gate) or a minor v0.13?

Decision: v0.13 (minor, not v1.0). The v1.0.0 production-ready tag stays deferred for post-v0.13 UAT signoff, exactly as v0.12's PRD specified. v0.13 is a minor feature milestone. Per-phase tags run on the previous minor's patch line (v0.12.x): P0 -> v0.12.0, P01 -> v0.12.1, ..., final phase patch = v0.12.13 = the v0.13 milestone release (no separate v0.13.0 tag, per feature-milestone rule).

Affected: config.json milestone field, all tag computation.

C2 — UAT validation mechanism (resolved)

Question: How should the "final command/script for validation and signoff" work? This is the v1.0 gate artifact.

Decision: Operator-driven docs/uat.md + scripts/uat-signoff.sh assertions. docs/uat.md walks the operator through building the cluster by hand (fresh Ubuntu server -> Proxmox host -> Ubuntu worker -> full stack -> migrate between hosts). scripts/uat-signoff.sh then queries the live cluster and asserts each claim (nodes, jobs, drift, audit chain, ACL enforcement, seal, metrics, etc.) — exit 0 only if all ~35 assertions pass. The operator runs it, pastes output back to the CI agent, which verifies and cuts v1.0.0.

Affected REQs: REQ-162, REQ-163.

C3 — Hardening phase scope (resolved)

Question: I found 24 concrete gaps grouped into 8 themes. Which scope?

Decision: All 8 themes, 14 phases. "No limit on phases" per operator. Three deep sweeps (security, reliability, feature/doc) expanded the gap count to ~60. The plan covers all critical/high/medium findings. 9 low-severity residual risks are documented and accepted.

Affected: 15 new requirements (REQ-149..REQ-163), 14 phases.

C4 — Ubuntu worker onboarding (resolved)

Question: The UAT plan must onboard a Proxmox host AND another Ubuntu worker. The codebase has --type linux reserved but unimplemented. How should Ubuntu worker onboarding work?

Decision: Implement --type linux SSH-join as part of hardening. Proxmox stays --type proxmox. Worker onboarding becomes first-class. peer-setup.go is kept as a documented fallback.

Affected REQs: REQ-161.

C5 — job stop semantics (resolved)

Question: job stop is currently a soft-stop (DB status update only, doesn't signal the process). Implement real systemctl stop via SSH, or rename to job mark-stopped?

Decision: Implement real systemctl stop via SSH. Honest semantics matching the job restart pattern. The UAT plan assumes stop actually stops.

Affected REQs: REQ-158.

C6 — UAT cluster topology (resolved)

Question: What 3-host shape should the UAT plan use?

Decision: 3 hosts: lead Ubuntu 22.04 + pve01 (Proxmox VE 8/9) + worker01 (Ubuntu 22.04). The lead is where orca init runs (operator laptop or VM). Minimal topology covering both node types + migrate- between-hosts.

Affected REQs: REQ-162.

C7 — UAT signoff script re-runnable? (resolved)

Question: Should scripts/uat-signoff.sh be idempotent/re-runnable or single-shot?

Decision: Idempotent — read + non-mutating assertions only. Safe to run multiple times against the same cluster. Only doctor, list, --dry-run, and similar read-only operations. The operator can iterate.

Affected REQs: REQ-163.

No open questions remain

All 7 clarifications resolved at full autonomy (autonomy.level=full, workflow.no_hitl=true). The operator confirmed decisions D-248..D-254 during the planning conversation. Proceed to RESEARCH.