Feature Requirements: phase-2-ci-quality

Feature Requirements: phase-2-ci-quality

Metadata

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

1. Problem Statement

1.1 Background

ZERG is preparing for public release. Phase 0 (blockers) and Phase 1 (community governance) are complete. The repo has basic CI (ci.yml with quality, smoke, test, audit jobs) but lacks security scanning, type checking in CI, Python 3.13 coverage, a documentation site, and structured GitHub Discussions.

1.2 Problem

• No automated security scanning (CodeQL) — vulnerabilities in PRs go undetected
• mypy runs locally but is not enforced in CI — type regressions can merge
• CI only tests Python 3.12 — no 3.13 verification despite >=3.12 requirement
• Documentation exists as raw markdown in docs/ — no searchable, navigable site
• GitHub Discussions enabled but has no categories or README link

1.3 Impact

Without Phase 2:

• Security vulnerabilities merge undetected
• Type errors regress silently
• Contributors on Python 3.13 hit untested issues
• Users can't easily browse documentation
• Community questions end up as issues instead of discussions

2. Users

2.1 Primary Users

• Open-source contributors submitting PRs (benefit from CI checks)
• Developers evaluating ZERG (benefit from docs site)

2.2 Secondary Users

• Maintainer (rocklambros) — benefits from automated security scanning and type enforcement
• Community members — benefit from structured Discussions categories

3. Functional Requirements

3.1 Core Capabilities

3.2 Inputs

• Existing ci.yml workflow (add mypy step, expand matrix)
• Existing pyproject.toml mypy config (strict mode, py312)
• Existing docs/ folder content (8 markdown files)
• GitHub API for Discussions categories

3.3 Outputs

• 3 new files: codeql.yml, docs.yml, CODEOWNERS
• 2 new files: mkdocs.yml, docs/index.md
• 2 modified files: ci.yml (mypy + matrix), pyproject.toml (classifiers + docs deps)
• 1 modified file: README.md (Discussions link, coverage badge)
• 1 modified file: CHANGELOG.md (Phase 2 entries)
• GitHub API: Discussions categories

3.4 Business Rules

• CodeQL must scan on push to main, PRs, and weekly cron
• mypy failure must block merge (required check)
• Python 3.13 tests use same test suite — no special handling
• Docs site uses Material for MkDocs theme
• Docs site deploys automatically on push to main
• CODEOWNERS uses @rocklambros as default owner

4. Non-Functional Requirements

4.1 Performance

• CodeQL scan should complete within 10 minutes
• Docs build should complete within 2 minutes
• Adding mypy to quality job should add <60s to CI

4.2 Security

• CodeQL provides automated vulnerability detection (SAST)
• CODEOWNERS ensures review for sensitive paths

4.3 Reliability

• Docs deployment should not block CI (separate workflow)
• CodeQL failure should not block merge (advisory only initially)

5. Scope

5.1 In Scope

• CodeQL workflow (.github/workflows/codeql.yml)
• mypy added to CI quality job
• Python 3.12 + 3.13 test matrix
• CODEOWNERS file
• mkdocs configuration and docs site
• GitHub Pages deployment workflow
• GitHub Discussions categories
• README updates (Discussions link, coverage badge)

5.2 Out of Scope

• Coverage floor change (keeping at 50 per user decision)
• Terminal demo / social preview (Phase 3, #191)
• Making repo public (separate decision)
• FUNDING.yml (Phase 3)
• Link checker workflow (Phase 3)
• Secret scanning (requires public repo or Advanced Security)

5.3 Assumptions

• Repo stays private during Phase 2 (docs site won't be publicly visible until repo is public)
• GitHub Discussions is already enabled (confirmed — linked in issue template)
• All current dependencies support Python 3.13
• mkdocs build --strict should pass with existing docs content

5.4 Constraints

• Must not break existing 5 required CI checks (quality, smoke, test (1), test (2), audit)
• mypy must use existing pyproject.toml config (strict mode)
• Docs site must build from existing docs/ content without major rewrites

6. Dependencies

6.1 Internal Dependencies

6.2 External Dependencies

7. Acceptance Criteria

7.1 Definition of Done

• CodeQL workflow runs on PRs and weekly
• mypy passes in CI quality job
• Tests pass on Python 3.12 and 3.13
• CODEOWNERS assigns @rocklambros as default reviewer
• mkdocs build --strict passes
• Docs workflow deploys on push to main
• Discussions has 4 categories (Q&A, Ideas, Show and Tell, General)
• README links to Discussions
• CI passes on PR
• CHANGELOG.md updated

7.2 Test Scenarios

8. Open Questions

9. Approval

10. Documentation

After implementation:

• CHANGELOG.md updated with Phase 2 entries (ALWAYS required)
• README.md updated with Discussions link + coverage badge
• pyproject.toml updated with 3.13 classifier + docs deps

11. Documentation Impact Analysis

11.1 Files Requiring Documentation Updates

11.2 Documentation Tasks for Design Phase

• CHANGELOG.md update task (ALWAYS required)
• README.md update (badge + link)
• pyproject.toml updates (classifiers + deps)