# Phase 1 Verification: Namespace Unification (v0.5 P1)

**Phase**: 1 (namespace unification)
**Milestone**: v0.5 Distribution
**Requirements covered**: REQ-041, REQ-042
**Date**: 2026-08-03

## Structural Layer

- `gofmt -l .` → clean (no files need formatting).
- `go vet ./...` → clean (no warnings).
- `go build ./...` → succeeds.
- New files: `internal/cli/namespace_test.go`, `docs/namespace.md`.
- Modified files: `internal/cli/root.go`, `internal/cli/init.go`, `internal/store/store.go`.

## Behavioral Layer

### Unit tests (new)
- `TestNamespaceDefaultsToUserHome` ✓ — empty `ORCA_HOME` → `~/.orca`.
- `TestNamespaceHonorsORCAHOME` ✓ — `ORCA_HOME=/tmp/x` → `Dir()=/tmp/x`, `DBPath()=/tmp/x/orca.db`.
- `TestInitHonorsORCAHOME` ✓ — `init` creates `$ORCA_HOME` dir.
- `TestSystemFlagSetsORCAHOME` ✓ — `--system` sets `ORCA_HOME=/root/.orca`.
- `TestSystemFlagConflictsWithORCAHOME` ✓ — `--system` + `ORCA_HOME=/custom` → error.
- `TestInitJSONOutput` ✓ — `init --json` returns `{"path":"...","status":"initialized"}`.
- `TestSystemFlagIsPersistent` ✓ — `--system` registered as persistent flag on `rootCmd`.

### Unit tests (regression — all pass)
- `internal/cli/` (9.8s) ✓
- `internal/store/` ✓
- `internal/doctor/` ✓
- `internal/daemon/` ✓
- `internal/security/` ✓
- `internal/engine/` ✓
- `internal/jobspec/` ✓
- `internal/transport/` ✓

### Manual e2e
- `ORCA_HOME=/tmp/orca-test-user ./bin/orca init` → creates `/tmp/orca-test-user` ✓
- `./bin/orca --system init` → creates `/root/.orca` ✓
- `ORCA_HOME=/custom ./bin/orca --system init` → error "conflicts with ORCA_HOME" ✓
- `./bin/orca version --json` → `{"version":"v0.4.1",...}` ✓

## Security Layer

- No new secret handling. The namespace unification moves path resolution
  but does not change cert/key file modes (0600/0644 per REQ-033 unchanged).
- `--system` flag does not escalate privileges — it only changes the
  namespace root path. Running as non-root with `--system` will fail at
  `os.MkdirAll("/root/.orca")` with a permission error (expected).
- No new network surface.

## Quality Layer

- **Backward compatibility**: empty `ORCA_HOME` + no `--system` → `~/.orca`
  (identical to pre-v0.5 behavior). All existing tests pass unmodified.
- **Single source of truth**: `certpaths.Dir()` is the only namespace root
  resolver. `store.Open("")` and `init` both route through it.
- **No redundant implementations**: the `--system` flag maps to `ORCA_HOME`
  rather than introducing a parallel path mechanism.
- **Documentation**: `docs/namespace.md` covers default, `ORCA_HOME`, and
  `--system` with examples and resolution order.

## Must-Haves Checklist

- [x] `go test ./...` passes (including new namespace_test.go).
- [x] `ORCA_HOME=/tmp/x orca init` creates `/tmp/x` (not `~/.orca`).
- [x] `orca --system init` creates `/root/.orca` (when run as root).
- [x] Empty `ORCA_HOME` + no `--system` → `~/.orca` (backward compat).
- [x] `orca version --json` works (needed by install.sh in P2).

## Verdict

**PASS** — all 4 verification layers pass. REQ-041 and REQ-042 are
satisfied. Ready to ship as `v0.4.2`.