Technical Design: phase-2-ci-quality

Metadata

• Feature: phase-2-ci-quality
• Status: DRAFT
• Created: 2026-02-07
• Author: Factory Design Mode
• Parent Epic: #179 (ZERG Public Release)
• Issues: #189, #190

---

1. Overview

1.1 Summary

Add CI security scanning (CodeQL), type checking enforcement (mypy), Python 3.13 test coverage, code ownership (CODEOWNERS), a MkDocs documentation site with GitHub Pages deployment, and structured GitHub Discussions categories. All changes are configuration/workflow files — no Python source code modifications.

1.2 Goals

• Automate security vulnerability detection in PRs via CodeQL
• Enforce mypy strict type checking in CI (block merge on failure)
• Verify compatibility with Python 3.12 and 3.13
• Enable automatic code review assignment via CODEOWNERS
• Provide a searchable, navigable documentation site
• Structure community engagement through GitHub Discussions categories

1.3 Non-Goals

• Changing the coverage floor (stays at 50)
• Terminal demo or social preview (Phase 3)
• Making repo public
• Link checker workflow
• Secret scanning

---

2. Architecture

2.1 High-Level Design

This feature adds 5 new files and modifies 3 existing files. No new Python modules, no runtime changes.

.github/workflows/
├── ci.yml          ← MODIFY: add mypy step, expand matrix to 3.12+3.13
├── codeql.yml      ← CREATE: CodeQL security scanning
├── docs.yml        ← CREATE: MkDocs build + GitHub Pages deploy
└── release.yml     (unchanged)

root/
├── CODEOWNERS      ← CREATE: code ownership rules
├── mkdocs.yml      ← CREATE: MkDocs Material configuration
├── pyproject.toml  ← MODIFY: add 3.13 classifier, docs optional deps
├── README.md       ← MODIFY: add Discussions link, coverage badge
├── CHANGELOG.md    ← MODIFY: add Phase 2 entries
└── docs/
    └── index.md    ← CREATE: docs site landing page

2.2 Component Breakdown

2.3 Data Flow

No runtime data flow — all components are CI/CD configuration:

1. PR opened → ci.yml runs quality (lint + mypy + validate), smoke, test (3.12 + 3.13), audit
2. PR opened → codeql.yml runs Python security analysis (advisory, non-blocking)
3. PR opened → CODEOWNERS auto-assigns @rocklambros
4. Push to main → docs.yml builds mkdocs and deploys to GitHub Pages

---

3. Detailed Design

3.1 CodeQL Workflow (.github/workflows/codeql.yml)

# Triggers: push to main, PRs, weekly schedule (Monday 9am)
# Language: Python
# Query suite: security-and-quality
# Non-blocking (advisory only — not a required check)

3.2 CI Enhancement (.github/workflows/ci.yml)

Changes to existing file:

1. quality job: Add mypy zerg/ step after lint check
2. test job: Expand matrix from [1, 2] shards to python-version: ['3.12', '3.13'] × shard: [1, 2] (4 combinations)
3. All other jobs (quality, smoke, audit) stay on Python 3.12

3.3 CODEOWNERS

# Default
* @rocklambros

# Core orchestrator
/zerg/ @rocklambros

# CI/CD
/.github/ @rocklambros

# Documentation
/docs/ @rocklambros

3.4 MkDocs Configuration (mkdocs.yml)

• Theme: Material for MkDocs
• Navigation tabs enabled
• Search enabled
• Content from existing docs/ folder
• Navigation structure mapping all 8+ existing doc files

3.5 Docs Landing Page (docs/index.md)

Adapted from README.md — overview, quick start, key concepts. Links to other docs pages.

3.6 Docs Deployment (.github/workflows/docs.yml)

# Trigger: push to main (docs/** or mkdocs.yml changes)
# Steps: checkout → setup python → install mkdocs-material → mkdocs build --strict → deploy to gh-pages
# Uses: actions/deploy-pages

3.7 pyproject.toml Changes

# Add classifier
"Programming Language :: Python :: 3.13",

# Add optional deps
docs = ["mkdocs>=1.6", "mkdocs-material>=9.5"]

3.8 README.md Changes

1. Add coverage badge after CI badge
2. Add Discussions link in Documentation table

---

4. Key Decisions

4.1 CodeQL as Advisory (Non-Blocking)

Context: CodeQL can be a required check or advisory. Decision: Advisory only (not added to required checks initially). Rationale: Per Q-001 resolution in requirements. Avoids blocking PRs on false positives during initial rollout. Can be promoted to required after tuning.

4.2 Test Matrix Strategy

Context: Could add 3.13 as a separate job or expand existing matrix. Decision: Expand existing test job matrix to python-version × shard. Rationale: Reuses existing test infrastructure. 4 jobs (2 versions × 2 shards) is manageable. No duplication of configuration.

4.3 MkDocs over Other Doc Generators

Context: Could use Sphinx, Docusaurus, or MkDocs. Decision: MkDocs with Material theme. Rationale: Specified in requirements (FR-005). Material is the most popular MkDocs theme, has search built-in, and works well with existing markdown docs.

---

5. Implementation Plan

5.1 Phase Summary

5.2 File Ownership

5.3 Consumer Matrix

Note: No integration tests needed — all tasks produce static config/workflow files verified by yamllint, mkdocs build --strict, or syntax checks.

5.4 Dependency Graph

graph TD
    T001["TASK-001: CodeQL workflow"] --> T008["TASK-008: CHANGELOG"]
    T002["TASK-002: CODEOWNERS"] --> T008
    T003["TASK-003: MkDocs config + index"] --> T006["TASK-006: Docs deploy workflow"]
    T004["TASK-004: pyproject.toml updates"] --> T005["TASK-005: CI mypy + matrix"]
    T005 --> T008
    T006 --> T008
    T007["TASK-007: README updates"] --> T008

---

6. Risk Assessment

---

7. Testing Strategy

7.1 Verification Commands

Each task has a local verification command (no CI needed):

• CodeQL: YAML syntax validation
• CODEOWNERS: File exists with correct format
• MkDocs: pip install mkdocs-material && mkdocs build --strict
• ci.yml: YAML syntax validation
• pyproject.toml: pip install -e ".[docs]" succeeds

7.2 Integration Verification

After all tasks merge:

• Push to feature branch → CI runs with mypy + 3.13 matrix
• mkdocs build --strict passes
• CodeQL workflow is present

---

8. Parallel Execution Notes

8.1 Safe Parallelization

• Level 1: 4 independent tasks (codeql.yml, CODEOWNERS, mkdocs config, pyproject.toml)
• Level 2: 3 tasks depending on L1 outputs (ci.yml depends on pyproject.toml; docs.yml depends on mkdocs config; README is independent but logically L2)
• Level 3: 1 task (CHANGELOG) depending on all others

8.2 Recommended Workers

• Minimum: 1 worker (sequential)
• Optimal: 4 workers (widest level is L1 with 4 tasks)
• Maximum: 4 workers (no benefit beyond L1 width)

8.3 Estimated Duration

• Single worker: ~35 min
• With 4 workers: ~15 min
• Speedup: ~2.3x

---

9. Approval