obsidian-owl/gate-wiring

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 (grep/glob returns no evidence): WARN "IC-{n} could not be structurally verified" — NOT false PASS.

Evidence output: When cross-unit mode activates, append a ## Cross-Unit Integration section to wiring-report.md after the per-unit findings. When cross-unit mode is inactive, this section does NOT appear.

Hard constraint — no worktree commands: This gate MUST NOT use git worktree commands, worktree creation, or worktree deletion. The full-feature diff approach uses only git diff and git cat-file against the existing working tree.

Protocol References

• protocols/evidence.md#verdict-rendering -- verdict rendering
• protocols/evidence.md -- evidence storage
• protocols/state.md -- gate status updates
• protocols/delegation.md -- architect agent delegation

Failure Modes

| Condition | Action | |-----------|--------| | No changed files detected | Analyze all project source files | | No architecture layers configured | Skip layer violation check | | Wiring tool not installed | Fall back to LLM-based analysis | | Too many files to analyze | Focus on changed files only, note incomplete scope | | Single-unit work (no workUnits) | Skip cross-unit check entirely | | baselineCommit null or unreachable | Skip cross-unit check, WARN | | Not the final unit | Skip cross-unit check (no WARN) | | Feature branch behind baseBranch | WARN, continue with potentially incomplete scope | | Full-feature diff returns empty | WARN, skip cross-unit delegation | | integration-criteria.md missing | WARN, continue structural checks without ICs | | IC file exists but has no entries | WARN, continue structural checks without ICs | | IC not structurally verifiable | WARN per IC (not false PASS) | | Cross-unit import missing | BLOCK with unit attribution | | Interface mismatch across units | BLOCK with unit attribution | | Architect delegation fails (error/timeout) | ERROR for cross-unit section. Cross-unit analysis is not optional once activated. | | Architect returns no findings | PASS — clean integration confirmed | | All non-current units abandoned (none shipped) | WARN, skip cross-unit check |