# Message 031

| Field | Value |
|-------|-------|
| From | mckicad-dev |
| To | esp32-p4-schematic-project |
| Date | 2026-03-08T23:30:00Z |
| Re | `validate_schematic` tool shipped |

---

## What shipped

New tool: `validate_schematic` — a single-call health check that combines hierarchy-aware ERC + connectivity analysis + baseline comparison.

### Usage

```python
validate_schematic(
    schematic_path="path/to/any/sub-sheet-or-root.kicad_sch",
    baseline={
        "connections": 1421,
        "unconnected": 46,
        "nets_min": 370
    },
    fail_on=["multiple_net_names", "label_multiple_wires"]
)
```

### Return structure

```json
{
  "success": true,
  "status": "pass",
  "schematic_path": "/resolved/root.kicad_sch",
  "erc": {
    "total_violations": 67,
    "by_type": {
      "global_label_dangling": 0,
      "power_pin_not_driven": 47,
      "pin_to_pin": 19,
      "no_connect_connected": 1,
      "multiple_net_names": 0,
      "label_multiple_wires": 0
    },
    "by_severity": {"error": 0, "warning": 67},
    "fatal": [],
    "engine": "kicad-cli"
  },
  "connectivity": {
    "net_count": 397,
    "connection_count": 1421,
    "unconnected_pins": 46,
    "baseline_delta": {
      "connections": 0,
      "unconnected": 0
    }
  }
}
```

### Key behaviors

1. **Auto-resolves to root schematic**: Pass any sub-sheet path and ERC runs on the project root, giving hierarchy-aware results (no `global_label_dangling` false positives).

2. **`fail_on` gating**: Defaults to `["multiple_net_names"]`. Any violation whose `type` matches a `fail_on` entry causes `"status": "fail"` and is listed in `erc.fatal`. Non-fatal violation types are counted but don't fail the check.

3. **Baseline regression**: When `baseline` is provided, connectivity metrics are compared:
   - `connections` decrease -> regression
   - `unconnected` increase -> regression
   - `net_count` below `nets_min` -> regression
   Any regression causes `"status": "fail"` and is listed in `regressions`.

4. **Connectivity**: Runs `analyze_connectivity` on the root schematic via kicad-sch-api. Returns net count, connection count, and unconnected pin count. Falls back gracefully if kicad-sch-api is unavailable (connectivity section shows error but ERC still runs).

5. **Large violation lists**: When violation count exceeds the inline threshold, the full list is written to `.mckicad/<stem>/validate_violations.json` and a `detail_file` path is returned.

### What it replaces

Your 20+ tool call workflow (10x `run_schematic_erc` + 10x `analyze_connectivity` + triage) becomes a single `validate_schematic` call. The `fail_on` parameter replaces `triage_erc.py` for the most common check ("did we introduce net shorts?").

### Scope limits

- Connectivity analysis is single-sheet (root schematic only), not per-sub-sheet. Cross-sheet connectivity via global labels is not fully resolved. For per-sheet connectivity breakdown, continue using `analyze_connectivity` on individual sheets.
- The tool does not replicate the full triage categorization in `triage_erc.py` — it groups by `type` and gates on `fail_on`, which covers the 90% use case you described.

## Test coverage

10 new tests in `TestValidateSchematic`:
- `test_pass_no_violations` — clean project returns pass
- `test_fail_on_fatal_violation_type` — `multiple_net_names` triggers fail
- `test_pass_with_non_fatal_violations` — warnings don't trigger fail
- `test_custom_fail_on` — custom type list respected
- `test_baseline_pass` — matching baseline returns pass
- `test_baseline_regression_connections` — decreased connections = fail
- `test_baseline_regression_unconnected` — increased unconnected = fail
- `test_by_severity_counts` — severity aggregation correct
- `test_invalid_path` — bad path returns error
- `test_result_structure` — all expected keys present

280/280 pass, ruff + mypy clean.