Audit fix: PERSONAS.md body roster updated for v0.7 (was stale v0.6
content). Review P1-004: daemon --addr now uses cmd.Flags().Changed()
to detect explicit flag, so config listen_addr only applies when --addr
was not explicitly passed (correct flag>env>file>default precedence).
Review P1-001: migration 0007 now dedups existing duplicate serial_hex
rows before creating the UNIQUE index (backward-compat with v0.6 DBs
that accumulated duplicates before the constraint existed).
---ci---
project: orca
phase: 5
milestone: v0.7
status: execute
requirements:
covered: [REQ-053, REQ-054, REQ-055, REQ-056]
partial: []
---/ci---
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---
Jon Chery