Requirements: analyze-wiring-verification

Requirements: analyze-wiring-verification

Status: APPROVED Feature: Enhance /z:analyze and /zerg:design for full wiring verification Created: 2026-02-02

Problem Statement

Three independent systems handle code quality verification with no overlap:

• /z:analyze --check all — lint, complexity, coverage, security (no wiring, no dead code)
• feature-dev:code-reviewer — AI semantic review (no wiring checks)
• python -m zerg.validate_commands — wiring + Task ecosystem drift (not accessible via analyze)

Result: a module can pass all analyze checks while having zero production callers, circular imports, or broken context engineering splits. --check all doesn't actually check all.

Additionally, /zerg:rush does not validate that blocks/blockedBy/dependencies in task-graph.json reference real task IDs before execution, and /zerg:design doesn't mandate a quality gate as a final task.

Functional Requirements

FR-1: Dead code detection in --check all

• Add DeadCodeChecker wrapping VultureAdapter from performance subsystem
• vulture --min-confidence 80 as default
• Include in --check all (currently dead code only runs under --performance)
• Configurable confidence threshold via .zerg/config.yaml

FR-2: Wiring check via --check wiring

• Add WiringChecker wrapping validate_module_wiring() from validate_commands.py
• Detect orphaned .py modules with zero production imports
• Respect existing exemptions (__init__.py, __main__.py, conftest.py, if __name__)
• Include in --check all

FR-3: Cross-file semantic analysis

• Add CrossFileChecker that walks AST across project
• Collect all exported symbols (functions, classes at module level)
• Collect all imports project-wide
• Report symbols exported but never imported by any other module
• Scope: Python files within zerg/ package (not tests)
• Include in --check all

FR-4: Project convention checking

• Add ConventionsChecker that reads CLAUDE.md rules
• Check: bracketed Task prefixes ([Plan], [L1], etc.) in command files
• Check: snake_case naming for Python modules
• Check: file organization rules (tests in tests/, scripts in scripts/)
• Check: command files have Task ecosystem markers
• Include in --check all

FR-5: Dependency graph validation in /zerg:rush

• Create zerg/graph_validation.py with validate_graph_properties()
• Checks:
  • All dependencies reference existing task IDs → error if not
  • No intra-level circular dependencies → error if found
  • Orphan tasks (L2+ with no dependents) → warning
  • Unreachable tasks (not reachable from L1 roots) → error
  • consumers fields reference real task IDs → error if not
  • Tasks with non-empty consumers must have integration_test set → error if missing
• Integrate into rush.py after load_and_validate_task_graph() — fail-fast on errors, print warnings
• Also wire into validation.py:load_and_validate_task_graph() as 4th validation step

FR-6: Import chain verification

• Add ImportChainChecker with DFS on import graph
• Detect circular imports between modules
• Verify new module exports are consumed by at least one downstream module
• Report import depth (flag deep chains > configurable threshold, default 10)
• Include in --check all

FR-7: Context engineering validation

• Add ContextEngineeringChecker wrapping all 7 validate_commands.py checks:
  1. Task references in command files
  2. Backbone command depth (>= 3 Task refs)
  3. Split pair consistency (.core.md + .details.md)
  4. Split threshold (large files should be split)
  5. State JSON references have TaskList/TaskGet fallback
  6. Engineering rules valid
  7. Module wiring (overlaps FR-2 but includes full suite)
• Include in --check all

FR-8: --check all means everything

• --check all must run every registered checker — no exclusions
• Remove the if k != "performance" filter at analyze.py:261
• Performance check included in all alongside all new checks
• Individual checks still selectable via --check <name>

FR-9: Print CLAUDE_CODE_TASK_LIST_ID

• /zerg:design must print the CLAUDE_CODE_TASK_LIST_ID value whenever it sets or inherits it (so the user can see which task list workers will coordinate on)
• /zerg:rush must print the CLAUDE_CODE_TASK_LIST_ID value at command start before any worker launches
• Format: Task List ID: {value} in console output
• If not set, print Task List ID: (default) to make implicit behavior visible

FR-10: Mandatory final analysis task in /zerg:design

• Every task graph generated by /zerg:design must include a final Level 5 task
• Task runs /z:analyze --check all --format json
• Task parses results and creates GitHub issues via gh issue create for each failure
• Issues labeled quality-gate + category name (e.g., lint, wiring, dead-code)
• Results logged to .zerg/state/final-analysis.json
• design.py validator must reject task graphs missing this final analysis task
• Template task embedded in design.core.md Phase 5 instructions

Non-Functional Requirements

NFR-1: Performance

• All new checkers must complete within 60s for projects with < 200 Python files
• AST-based checkers (cross-file, import-chain) cache parsed ASTs to avoid double-parsing

NFR-2: Configurability

• New .zerg/config.yaml section for analyze settings:

  analyze:
    dead_code:
      min_confidence: 80
    wiring:
      strict: false
      exclude_patterns: []
    cross_file:
      scope: "zerg/"
    conventions:
      naming: snake_case
      require_task_prefixes: true
    import_chain:
      max_depth: 10
    context_engineering:
      auto_split: false
  

NFR-3: Output consistency

• All new checkers return AnalysisResult with same schema as existing checkers
• All support text/json/sarif output formats
• SARIF output includes rule IDs for IDE integration

NFR-4: Testing

• Unit tests for each new checker
• Unit tests for graph validation
• Integration test for rush pre-execution validation
• Integration test for --check all running all 10+ checks

NFR-5: Drift prevention

• New modules must have production callers (enforced by existing validate_commands)
• New modules must have integration tests
• python -m zerg.validate_commands must pass after changes

Scope Boundaries

In scope

• 6 new checker classes in zerg/commands/analyze.py
• 1 new module zerg/graph_validation.py
• Updates to rush.py, validation.py, design.core.md, design.py
• Config schema extension
• Command file updates
• Unit + integration tests
• CHANGELOG.md update

Out of scope

• JavaScript/TypeScript cross-file analysis (Python only for now)
• AI-powered semantic review (that's feature-dev:code-reviewer's domain)
• Modifying feature-dev:code-reviewer agent
• Performance audit refactoring (vulture stays in performance too)

Dependencies

• vulture package (already used by VultureAdapter)
• ast stdlib (for cross-file and import-chain analysis)
• gh CLI (for GitHub issue creation in final analysis task)
• Existing validate_commands.py (wrapping, not rewriting)

Acceptance Criteria

1. /z:analyze --check all runs 10+ checks (lint, complexity, coverage, security, performance, dead-code, wiring, cross-file, conventions, import-chain, context-engineering)
2. /z:analyze --check wiring runs wiring check standalone
3. /z:analyze --check dead-code detects unused Python code
4. /z:analyze --check cross-file reports exported-but-never-imported symbols
5. /z:analyze --check conventions validates CLAUDE.md rules compliance
6. /z:analyze --check import-chain detects circular imports
7. /z:analyze --check context-engineering runs all 7 validate_commands checks
8. /zerg:rush rejects task graphs with invalid dependency references
9. /zerg:rush warns on orphan tasks, errors on unreachable tasks
10. /zerg:design prints Task List ID: {value} when it sets/inherits the ID
11. /zerg:rush prints Task List ID: {value} at command start
12. /zerg:design output always includes L5 final analysis task
13. design.py validator rejects task graphs missing final analysis task
14. python -m zerg.validate_commands passes (no drift)
15. All new modules have production callers and integration tests

Workstream Decomposition

WS1: Expand /z:analyze (parallel with WS2)

Files: zerg/commands/analyze.py, zerg/data/commands/analyze.md, .zerg/config.yaml Tests: tests/unit/test_analyze_new_checks.py

WS2: Rush dependency validation (parallel with WS1)

Files: zerg/graph_validation.py (new), zerg/commands/rush.py, zerg/validation.py Tests: tests/unit/test_graph_validation.py, tests/integration/test_rush_validation.py

WS3: Design mandatory final task (after WS1)

Files: zerg/data/commands/design.core.md, zerg/commands/design.py Tests: validation via existing design.py test suite

Open Questions

None — all requirements specified by user.