Technical Design: Quality Gate Fixes

Technical Design: Quality Gate Fixes

Metadata

• Feature: quality-gate-fixes
• Status: APPROVED
• Created: 2026-02-04
• GitHub Issues: #106, #107

1. Overview

1.1 Summary

Fix quality gate failures by documenting existing TYPE_CHECKING guards and adding explicit __all__ exports to clarify public APIs. The circular imports are already correctly mitigated at runtime.

1.2 Goals

• Document the lazy import pattern in zerg/verify.py
• Add __all__ to zerg/config.py and zerg/types.py
• Verify import-chain quality gate score improves

1.3 Non-Goals

• Fix deep import chains (depth >10) — deferred
• Remove unused exports — requires manual review
• Restructure module hierarchy

2. Architecture

2.1 Current State Analysis

Three potential circular imports were detected by the quality gate:

2.2 Changes Required

1. Document lazy import pattern (verify.py)

def store_artifact(self, ...):
    # Lazy import to avoid circular dependency with verification_gates
    from zerg.verification_gates import ArtifactStore

2. Add __all__ to config.py Export configuration classes explicitly.

3. Add __all__ to types.py Export type definitions explicitly.

3. Detailed Design

3.1 verify.py Changes

Lines 297 and 320 contain lazy imports of ArtifactStore. Add comments documenting the pattern:

def store_artifact(
    self,
    result: VerificationExecutionResult,
    artifact_dir: Path | None = None,
) -> Path:
    """Store verification result as artifact."""
    # Lazy import to avoid circular dependency with verification_gates
    from zerg.verification_gates import ArtifactStore

    store = ArtifactStore(base_dir=artifact_dir)
    return store.store("verification", result.task_id, result)

3.2 config.py all Definition

__all__ = [
    # Main config
    "ZergConfig",
    # Sub-configs
    "ProjectConfig",
    "WorkersConfig",
    "PortsConfig",
    "QualityGate",
    "ResourcesConfig",
    "LoggingConfig",
    "SecurityConfig",
    "ResilienceConfig",
    "EfficiencyConfig",
    "RulesConfig",
    "CircuitBreakerConfig",
    "BackpressureConfig",
    "ErrorRecoveryConfig",
    "LoopConfig",
    "VerificationConfig",
    "ModeConfig",
    "MCPRoutingConfig",
    "TDDConfig",
    "HeartbeatConfig",
    "EscalationConfig",
    "VerificationTiersConfig",
    "RepoMapConfig",
    "TokenMetricsConfig",
    "PlanningConfig",
    "RushConfig",
]

3.3 types.py all Definition

__all__ = [
    # Task types
    "FileSpec",
    "VerificationSpec",
    "VerificationResult",
    "TaskExecution",
    "Task",
    "LevelSpec",
    "TaskGraph",
    # Worker types
    "WorkerState",
    # Level types
    "LevelStatus",
    # Gate types
    "GateConfig",
    "GateRunResult",
    # Merge types
    "MergeResult",
    # Orchestrator types
    "LevelCompleteResult",
    "ExecutionEvent",
    "OrchestratorState",
    # Assignment types
    "WorkerAssignmentEntry",
    "WorkerAssignments",
    # Metrics types
    "WorkerMetrics",
    "TaskMetrics",
    "LevelMetrics",
    "FeatureMetrics",
]

4. Key Decisions

4.1 Document Rather Than Restructure

Context: The circular imports are already mitigated at runtime but detected by static analysis.

Options Considered:

1. Restructure modules to eliminate cycles: High effort, risk of breaking changes
2. Document existing patterns: Low effort, clarifies intent
3. Do nothing: Risk of future regressions

Decision: Document existing patterns with comments.

Rationale: The code works correctly. Documentation preserves knowledge for future maintainers without introducing risk.

4.2 Add all to Core Modules Only

Context: 318 unused exports detected, but many are false positives (CLI commands, public API).

Options Considered:

1. Add all to all modules: High effort, maintenance burden
2. Add all to core modules only: Low effort, clarifies main API
3. Skip entirely: Misses opportunity to clarify public API

Decision: Add all to config.py and types.py.

Rationale: These are the most-imported modules. Explicit exports clarify the public API without affecting runtime behavior.

5. Implementation Plan

5.1 Phase Summary

5.2 File Ownership

5.3 Dependency Graph

Level 1 (Foundation):
  TASK-001 ─┐
  TASK-002 ─┼─> TASK-004 (Verification)
  TASK-003 ─┘

6. Risk Assessment

7. Testing Strategy

7.1 Verification Commands

Each task has a verification command:

• TASK-001: python -c "from zerg.verify import VerificationExecutor"
• TASK-002: python -c "from zerg.config import ZergConfig"
• TASK-003: python -c "from zerg.types import Task"
• TASK-004: pytest tests/ -x && python -m zerg.validate_commands

8. Parallel Execution Notes

8.1 Safe Parallelization

• Level 1 tasks modify separate files, fully parallel
• Level 2 verification depends on all level 1 tasks

8.2 Recommended Workers

• Minimum: 1 worker
• Optimal: 3 workers (one per file)
• Maximum: 3 workers

8.3 Estimated Duration

• Single worker: ~25 minutes
• With 3 workers: ~15 minutes
• Speedup: 1.7x

9. Approval