/gate-wiring

name: gate-wiring
description: >-
  Detects unused exports, orphaned files, architecture layer violations,
  and circular dependencies across changed files. Delegates to architect
  agent for structural analysis. Internal gate — invoked by verify.
allowed-tools:
  - Read
  - Bash
  - Glob
  - Grep
  - Write
  - Task

Gate: Wiring

Goal

Ensure the codebase is properly connected — no dead code, no orphaned files, no architecture violations. Code that compiles and passes tests can still be wired incorrectly.

Inputs

• `{projectArtifactsRoot}/config.json` -- architecture layers, project structure
• `{repoStateRoot}/work/{selectedWork.id}/workflow.json` -- selected work unit
• Changed files (via `git diff`)

Outputs

• Evidence file at `{workDir}/evidence/wiring-report.md`
• Gate status in the selected work's `workflow.json`
• Findings with specific file:line references and remediation

Constraints

**Scope (MEDIUM freedom):**

• Focus on changed files and their immediate dependents.
• Use `git diff --name-only` against main branch.

**Analysis (HIGH freedom):**

• Delegate to `specwright-architect` for structural analysis.
• The architect checks:
• **Unused exports**: Public functions/types exported but never imported.
• **Orphaned files**: Files not imported by anything in the dependency graph.
• **Layer violations**: Imports crossing architecture layer boundaries (e.g., UI importing directly from database layer). Layers from `config.json` `architecture.layers`.
• **Circular dependencies**: Import cycles that may cause runtime issues.
• Use real tooling when available (e.g., `madge`, `knip`, `ts-prune`).
• Fall back to LLM analysis when tools aren't configured.

**Verdict (LOW freedom):**

• Follow `protocols/evidence.md#verdict-rendering`.
• WARN severity for most findings (wiring issues rarely block functionality).
• BLOCK only for circular dependencies in changed files.
• This gate is advisory — it helps clean up, not block shipping.

**Cross-unit integration (MEDIUM freedom, multi-unit only):**

When verifying the final unit of a multi-unit design, run additional cross-unit wiring checks against the full feature diff. This catches integration issues invisible to per-unit analysis: missing cross-unit imports, interface mismatches, disconnected entry points.

*Activation predicate* — all four conditions must be true: 1. `workUnits` array exists in the selected work's workflow.json (multi-unit work) 2. `selectedWork.baselineCommit` is non-null 3. `git cat-file -t {baselineCommit}` exits 0 (commit is reachable) 4. All `workUnits` entries except the current `unitId` have status `shipped` or `abandoned`, AND at least one non-current unit has status `shipped` (if all non-current units are `abandoned`, skip with WARN "All prior units abandoned — cross-unit integration check skipped")

If condition 1 is false: skip cross-unit check entirely (single-unit — not applicable, no WARN, no output). If condition 2 is false: skip with WARN "No baseline commit recorded — cross-unit integration check skipped." If condition 3 is false: skip with WARN "Baseline commit {sha} unreachable — cross-unit integration check skipped." If condition 4 is false: skip entirely (not the final unit — no WARN, no output).

*Branch freshness pre-check* — before computing the diff: Run `git merge-base --is-ancestor origin/{config.git.baseBranch} HEAD` (default `origin/main`). If non-zero exit: WARN "Feature branch is behind {baseBranch} — cross-unit diff may be incomplete. Consider rebasing." Continue the check.

*Full-feature diff:* Compute the merge base to scope the diff to feature-only changes:

MERGE_BASE=$(git merge-base {baselineCommit} HEAD)
git diff $MERGE_BASE HEAD --name-only

Using the merge base (not `baselineCommit` directly) ensures that after a rebase onto a newer main, the diff includes only files changed on the feature branch — not unrelated files merged to main since design start. If the diff returns empty: WARN "Full-feature diff returned no changed files — cross-unit integration check skipped" and exit without delegating. Filter the file list to only files that exist on HEAD (remove deleted files).

*Architect delegation for cross-unit analysis:* Delegate to `specwright-architect` with: (a) the full-feature file list (HEAD-existing only), (b) the design.md (architect extracts integration-relevant content), (c) `integration-criteria.md` from the design-level directory if present. Instruct the architect to check:

• **Cross-unit imports**: For each unit's exports described in the design, verify

importing code exists in consuming units.

• **Interface compatibility**: Type/interface definitions exported by early units match

what later units import.

• **Entry point wiring**: The feature's entry point imports and connects all constituent

pieces.

• **Dead feature exports**: Exports added across all units that no code in the codebase

imports.

• **Integration criteria**: Verify each IC structurally (grep/glob/type-check, not

semantic analysis).

*Severity calibration:* Cross-unit structural findings (missing cross-unit import, interface mismatch, disconnected entry point) are BLOCK severity. Dead feature exports are WARN severity. This overrides the per-unit default of WARN. Cross-unit wiring failures represent a non-functional feature, not an advisory cleanup suggestion.

*Unit attribution:* Each cross-unit finding must identify which units are involved (e.g., "Interface mismatch between unit-1 export `PaymentRequest` in `src/types.ts:15` and unit-3 import in `src/checkout.ts:8`").

*Integration criteria handling:* If `integration-criteria.md` is absent: WARN "Integration criteria file not found — IC checks skipped" and continue with structural checks. If the file exists but contains zero IC entries (no lines matching `- [ ] IC-`): WARN "Integration criteria file contains no criteria — IC checks skipped" and continue. If an IC cannot be structurally verified (g