REQ-041: ORCA_HOME is now the single namespace root for all components
(db, certs, init, daemon). store.Open("") and init command both
route through certpaths.Dir()/DBPath() instead of hardcoding ~/.orca.
Backward compatible: empty ORCA_HOME -> ~/.orca.
REQ-042: --system persistent flag on rootCmd sets ORCA_HOME=/root/.orca
via PersistentPreRunE. Errors on conflict with pre-set ORCA_HOME.
Tests: 7 new tests in namespace_test.go (default, ORCA_HOME override,
--system sets root, conflict detection, init --json, flag registered).
Full suite passes (no regressions).
Docs: docs/namespace.md covers default, ORCA_HOME, --system, ORCA_DB,
resolution order, and path layout tables.
---ci---
project: orca
phase: 1
milestone: v0.5
status: verify
---/ci---
---ci---
project: orca
phase: 3
milestone: v0.3
status: complete
requirements:
covered: [REQ-022, REQ-030, REQ-032]
partial: []
---/ci---
v0.3 milestone merged to main. Includes all v0.2 work (P08-P10) that
was previously on the milestone branch but not yet merged to main, plus
the v0.3 completion work (iter.Seq streaming + doctor network/db).
v0.2 phases included: P08 (mTLS), P09 (scheduling), P10 (security scan).
v0.3 phases: P0 (pre-execution), P1 (iter.Seq streaming), P2 (doctor),
P3 (final review+ship).
Total: 40 requirements, all complete. No new go.mod dependencies.
Full test suite passes under -race. gofmt + go vet clean.
CIAgent audit (.ciagent/AUDIT_v0.2_P01.md) surfaced 3 .ciagent/ file
discipline issues. This commit addresses all 3:
1. config.json: re-add the 'workflow' top-level block. It was added in
d10f89d (v0.1 milestone) and lost from main during the parallel-
history resolution that produced origin/main's be9afa2 PR-#1 merge.
The 4 standing rules (no_hitl, release_flow_per_phase, merge_strategy,
branching) are restored.
2. PROJECT.md: add literal '## What This Is' and '## Key Decisions'
section headers. The v0.1 audit-fix (f1c55ca) added the content
inline but without the explicit headers, so the audit check missed
them. The Key Decisions section summarizes D-011..D-018.
3. REQUIREMENTS.md: consolidate two overlapping REQ tables (the v0.1
status table and the v0.2 traceability table) into a single
canonical table covering all 40 REQs (REQ-001..REQ-040). Each row
has REQ-ID, summary, priority, phase, status. v0.1 REQs show
'Complete'; v0.2 REQs show 'Complete' (P01 shipped) or 'Pending
(P##)'. The v0.1 Milestone Summary and v0.2 Milestone Summary
sections are preserved below the table.
4. AUDIT_v0.2_P01.md: the audit report itself, with reconstruction
state, file discipline table, branch hygiene, commit discipline,
and the 3 findings above (plus non-blocking observations). The
report's verdict: 'v0.2 P01 ship is healthy; 3 issues are
paper-cleanup items addressed in this commit. None block P02
EXECUTE.'
---ci---
project: orca
phase: 0
milestone: v0.2
status: fix
---/ci---
v0.2 RESEARCH stage. Synthesizes the 4-phase v0.2 scope (P01-P04) into
updated static docs. No code changes. Decisions are derived from
CLARIFY D-011..D-018 (already on main) and direct investigation of
go.mod, the codebase, and ecosystem docs (Go 1.25+ iter.Seq, govulncheck,
gosec, gitleaks, step-ca).
Key research conclusions logged here:
- ConnectRPC is NOT in go.mod (.ciagent/config.json lists it in
frameworks but the dependency was never added). v0.2 falls back to
stdlib net/http with h2c for the orca.v1.Dispatch service. Zero new
direct deps. (ARCHITECTURE.md AD-014)
- Roll-our-own CA via crypto/x509 (not step-ca/cfssl/vault-pki) keeps
the binary single, dependency-free, and aligned with offline-first
(no external PKI network calls). (ARCHITECTURE.md AD-010)
- govulncheck default mode requires network access to vuln.go.dev. CI
step must use -format json (always exits 0) + a wrapper that gates
on findings via jq/cat, OR pre-mirror the database. Caller to decide
in PLAN. Logged as REQ candidate for IDEATE.
- gosec exit codes: 0 clean, 1 unsuppressed finding. -no-fail always
returns 0. Baseline JSON via -track-suppressions + exclude=. We
adopt -no-fail on initial run, baseline suppressed findings, then
tighten to fail-on-finding once baseline is empty.
- gitleaks default config covers most cases; we extend .gitleaks.toml
with stopwords for our test data paths and CA cert PEM (which would
otherwise trigger the generic-api-key rule).
- iter.Seq: yield func(V) bool, iter.Pull for pull-style, range over
function types since Go 1.25. Cancellation flows through ctx
(consumer-driven backpressure). Single-use vs multi-use semantics
documented in Go spec; we use multi-use for repo.Watch() since
callers can re-iterate.
- mTLS hot-swap via tls.Config.GetCertificate callback enables cert
rotation without daemon restart. tls.Config is read on every
handshake; reload picks up new server.crt/server.key.
ARCHITECTURE.md changes:
- Added Transport Layer (internal/transport) and Dispatcher
(internal/engine/dispatcher.go) components.
- Added Security Manager (internal/security) component with full cert
lifecycle API.
- Added certs table schema (migration 0004) and Cert Go struct.
- Extended Node with NodeCapacity (CPU/memory) for bin-packing.
- Added v0.2 Component Graph ASCII diagram.
- Added 4 named flows: cert issuance, mTLS handshake, job dispatch,
iter.Seq streaming.
- Added 8 new AD-009..AD-016 decisions and AD-014 notes the
ConnectRPC-not-in-go.mod reality.
PERSONAS.md changes:
- Added network-engineer (custom, NEW in v0.2) for transport/dispatcher.
- security-engineer marked phase_specific: [P01, P02] (off after P02).
- network-engineer marked phase_specific: [P02].
- cli-engineer marked phase_specific: [P04] (--watch is a CLI concern).
- data-engineer.territory extended to include
internal/store/migrations/0004_certs.sql.
- security-engineer.territory extended to TLS-config portion of
internal/transport.
- Frontmatter updated: active_personas, phase_specific, reason.
PROJECT.md changes:
- Moved "Multi-node scheduling" out of "Out of Scope" (it ships in P02).
- Added "External PKI / Let's Encrypt / cert transparency logs" to
Out of Scope (per D-011).
- Added "gRPC framework dependency" to Out of Scope (per AD-014).
- Added v0.2 Scope Summary section (4 phases) with cross-refs to
ARCHITECTURE.md flows.
REQ candidates surfaced for IDEATE stage (not added to REQUIREMENTS.md
in this commit — that's the IDEATE stage's job):
- REQ-cand-A: Bounded cert rotation history (retain last N=3 server
certs per node for rollback; documented in ARCHITECTURE.md certs
table as "retention" implication of the schema).
- REQ-cand-B: Trusted-CA fingerprint pinning (D-012 requires operator
to pass --ca-fingerprint at join; the daemon should refuse to start
if the on-disk CA's fingerprint doesn't match a config-pinned value,
to protect against operator typos).
- REQ-cand-C: govulncheck offline mode (CI must not call vuln.go.dev
by default; either pre-mirror the DB or set GOVULNCHECK_DB env to
a local file).
- REQ-cand-D: HCL/YAML schema for NodeCapacity declaration (where
does the operator declare a node's CPU/RAM? Current v0.1 Node model
has no capacity field. P02 will add this — needs a config file
surface, e.g. ~/.orca/node.hcl or flag on `orca node join`).
- REQ-cand-E: gitleaks baseline for pre-existing secrets in history
(the v0.1 .env leak was rotated forward but git history still has
a SHA-1 leak — gitleaks/git filter-repo remediation may need a
baseline file to avoid the same class of false positive recurring).
- REQ-cand-F: --watch output format mode (iter.Seq stream is
table-style by default; users may want --watch --json one-line-per-
event for piping). P04 scope decision; log for IDEATE.
---ci---
project: orca
phase: 0
milestone: v0.2
status: research
---/ci---
v0.2 CLARIFY stage. Resolves 8 ambiguities introduced by the deferred
v0.2 scope (mTLS, scheduling, scanning, streaming). All decisions taken
under full autonomy (config.json autonomy.level: full) at confidence
>= 0.85, which is above the decision_confidence_threshold of 0.60.
- D-011: Internal CA with CSR join (vs. self-signed per-node or SPIFFE).
- D-012: Operator-mediated CA cert distribution with fingerprint verify
(no automated secret distribution — matches offline-first principle).
- D-013: 90d server certs, 10y CA cert, 30d pre-expiry rotation.
- D-014: Eager mTLS handshake at time.
- D-015: TLS 1.3 minimum, AEAD cipher allowlist (no TLS 1.2 fallback).
- D-016: gosec+govulncheck in pipeline of .coreci.yml;
gitleaks in pre-commit hook (opt-in).
- D-017: iter.Seq for and .
- D-018: Bin-packing by CPU/memory with FIFO within node; ConnectRPC
orca.v1.Dispatch for cross-node.
RESEARCH and IDEATE follow.
---ci---
project: orca
phase: 0
milestone: v0.2
status: clarify
---/ci---
Validates the v0.2 milestone specification against the deferred-v0.2
requirements in ROADMAP.md and the requirement status table. Updates:
- ROADMAP.md: v0.2 marked in-progress with 4 phases (P01 mTLS, P02
multi-node scheduling, P03 gosec+govulncheck, P04 iter.Seq). Adds
target milestone tag (v0.3.0) and per-phase tags (v0.2.1..v0.2.4)
per the feature-milestone promotion rule and the RELEASE_POLICY.md
standing rule on per-phase releases.
- REQUIREMENTS.md: flips REQ-011, REQ-014, REQ-022, REQ-023 from
'Deferred (v0.2)' to 'Pending (v0.2 PXX)'. Adds a v0.2 summary
section.
No code or schema changes. Pure SPECIFY output per run.md Step 3.
CLARIFY and RESEARCH follow.
---ci---
project: orca
phase: 0
milestone: v0.2
status: specify
---/ci---
Layer-3 security audit during P07 EXECUTE found that .env (containing
GITEA_TOKEN) was committed in 0cba1aa during P00 and remained in git
history. The pre-P07 .gitignore only excluded .env.local, not .env.
This commit:
1. Adds .env to .gitignore alongside .env.local (forward fix — prevents
future re-tracking).
2. Documents the pre-existing leak in .ciagent/PHASE7_SECURITY_AUDIT.md
with mitigation steps and required human actions (token rotation,
history rewrite, access-log audit, CI secret scanning).
The backfill script itself (commit de69788) does not leak the secret: it
sources .env from disk and never echoes or passes it on the command line.
The leak is upstream of P07 and is documented as P0 for the human to
remediate out-of-band.
---ci---
project: orca
phase: 7
milestone: v0.1
status: execute
version: v0.1.7
requirements:
covered: [REQ-007]
partial: []
---/ci---
Jon Chery
cloudinit-bot