Architectural Decision Record: Automated CI Coverage Aggregation & Duplication Elimination Gate
Status
Accepted
Context
The ZQK Continuous Integration pipeline previously ran unit tests in two distinct workflows:
unit-tests: A matrix of 7 partitioned parallel shards covering the entire repository (core-kernel,storage,cli-commands,objects-and-specs,agent-and-orchestration,validation-and-tpm,scheduler).extended-unit-tests: A redundant non-matrix job that re-executed over 80% of all package suites previously executed in the matrix shards.
This duplication introduced several critical systemic issues:
- Redundant Compute & Execution Lag: Running tests twice on the same commit consumed excessive GitHub Actions runner minutes and prolonged PR feedback cycles by over 13 minutes per run.
- Coverage Disparity: Matrix shards and extended unit tests generated separate coverage outputs (
coverage-<suite>.outvscoverage-extended.out), creating confusion over which gate governed release certification. - Flake Amplification: Duplicative execution of identical test suites doubled the probability of transient timing flakes on CI runners without providing any additional static or dynamic coverage proof.
Decision
-
Single Source of Truth for Test Execution: - The 7 partitioned shards in the
unit-testsmatrix are the exclusive and canonical execution harness for all unit and package verification suites. - The separateextended-unit-testsjob is completely deprecated and removed from the CI workflow. -
Shard-Based Coverage Rollup: - Each matrix shard produces an isolated coverage profile (
coverage-${{ matrix.suite }}.out). - Theconsolidate-coveragejob aggregates all shard profiles usingscripts/open-core/coverage-rollup. - Merged coverage is compiled into a singlecoverage.outartifact, generating cryptographic verification telemetry (package-coverage-rollup.jsonand.sha256sidecar). -
Gated Dependency Topology: - The
buildstep depends directly on[lint-and-format, unit-tests, consolidate-coverage], guaranteeing that binaries are only compiled and staged after all test shards and coverage consolidation gates pass.
Consequences
- Positive:
- 100% elimination of redundant test executions across CI workflows.
- Reduction of PR CI turnaround times by ~13-15 minutes per run.
- Unified coverage accounting across all packages and tools.
- Negative / Risks:
- Shard package mappings must remain strictly exhaustive across
pkg/andcmd/so no newly added packages are orphaned. Enforced by repository hygiene policies.