1545 Requirements 761c7dfe

# 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:
  ```yaml
  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.