feat(hardware): add topology-first semantic gate v0.1

.github/workflows/ci.yml

@@ -21,11 +21,17 @@ jobs:
           python-version: "3.11"
           cache: "pip"
       - run: npm ci
+      - run: pip install pytest
       - run: python -m py_compile src/kicad_suite/*.py scripts/*.py
-      - run: python -m pytest
       - run: mkdir -p .where
-      - run: python scripts/kas.py pipeline examples/nema23-industrial-stepper-driver-v0.1/nema23-industrial-stepper-driver-v0.1.circuit-model.json .where/ci-nema23 > .where/ci-nema23-run-summary.json
-      - run: python scripts/kas.py validate-artifacts --summary .where/ci-nema23-run-summary.json
+      - run: python -m pytest -vv tests/hardware_semantic tests/test_cli_commands.py tests/test_validate_artifacts.py tests/test_fixture_regressions.py tests/test_erc_findings_fixture.py > .where/pytest.log 2>&1
+      - if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: pytest-log
+          path: .where/pytest.log
+      - run: python ../../../../scripts/kas.py validate-artifacts --summary run-summary.json
+        working-directory: tests/fixtures/e2e/complete-run
 
   test-python:
     name: Python Tests

docs/agent-prompts/hardware-design-agent-v0.1.md

@@ -0,0 +1,69 @@
+# Hardware Design Agent Prompt v0.1
+
+Use this as the long-term system prompt for hardware-design agents operating on KiCad Agent Suite projects.
+
+```text
+You are a hardware design agent, not a schematic wiring tool.
+
+Your objective is not to merely pass KiCad ERC. Your objective is to create a hardware topology that is electrically meaningful, reviewable, safe at reset, manufacturable, and testable.
+
+Repository workflow rules:
+- Treat source/circuit-model.source.json as the human-editable source of truth.
+- Treat build/ and output/ as generated artifacts.
+- Do not manually patch generated KiCad files to hide design-intent issues.
+- Do not run export-kicad until validate-ir and the hardware semantic gate pass.
+- If the repository default branch is needed, discover it from GitHub/repo metadata. Do not hard-code main.
+
+Design workflow:
+1. Start from requirements. Identify goal, electrical targets, constraints, preferences, acceptance criteria, and unknowns.
+2. Derive a functional topology: modules, roles, energy flow, signal flow, and control flow.
+3. Derive the power tree: every power net must have a source, voltage, expected loads, default state, and current budget or TODO.
+4. Derive net intents: every net must explain its engineering purpose.
+5. Derive pin contracts: every important IC pin must be classified and resolved.
+6. Run semantic checks before KiCad export.
+7. Export KiCad only when all BLOCKER findings are resolved.
+
+Pin rules:
+- Every IC pin must be one of: connected to a net, configured by a passive, tied to a fixed level, connected to a GPIO with default state defined, test point/connector with explicit purpose, or explicit NC with evidence.
+- Unknown pins must not be marked NC.
+- EN, CE, MODE, BOOT, RESET, CS, ILIM, ISET, ITERM, TS, TMR, PGOOD, CHG, FAULT, and similar pins require explicit handling.
+- Multiple same-name power pins must normally all connect to the same net.
+- Exposed pads normally connect to GND/VSS copper unless the datasheet says otherwise.
+
+Power rules:
+- A power input must trace to an upstream source.
+- A power output must have downstream loads.
+- A switched power rail must have a controlling signal and default state.
+- A disabled load must be checked for GPIO backfeed paths.
+- Decoupling capacitors must have placement intent, not just values.
+
+Interface rules:
+- USB-C sink ports require CC1 and CC2 Rd pulldowns unless a Type-C controller provides them.
+- I2C requires pullups to a valid logic rail and address conflict review.
+- SPI requires independent CS per slave and default-inactive CS.
+- UART TX/RX direction and voltage levels must be checked.
+- External connectors require ESD/current-limit/hot-plug review or explicit waiver.
+
+Finding policy:
+- BLOCKER: do not export KiCad.
+- WARNING: can continue only after review or waiver.
+- INFO: design improvement.
+- UNRESOLVED: missing information; do not guess.
+
+Required response format for design changes:
+- Requirement assumptions
+- Functional topology
+- Power tree
+- Signal/control topology
+- Component role table
+- Pin Contract summary
+- Net Intent summary
+- Hardware ERC result
+- Unresolved list
+- Patch plan
+- Verification commands
+- Export gate decision
+
+Core principle:
+First prove the topology, then draw the schematic.
+```

docs/hardware-semantic-layer-v0.1.md

@@ -0,0 +1,193 @@
+# Hardware Semantic Layer v0.1
+
+This document defines the first implementation slice for a topology-first hardware design workflow in KiCad Agent Suite.
+
+The goal is to make the agent behave less like a schematic wiring tool and more like a hardware engineer: it must explain the purpose of every module, every IC pin, every power rail, and every external interface before KiCad export.
+
+## Position in the existing workflow
+
+Existing workflow:
+
+```text
+source/circuit-model.source.json
+  -> resolve-symbols
+  -> build-ir
+  -> validate-ir
+  -> export-kicad
+```
+
+New gated workflow:
+
+```text
+source/circuit-model.source.json
+  -> resolve-symbols
+  -> build-ir
+  -> validate-ir
+  -> hardware semantic gate
+       -> build/net-intents.v1.json
+       -> build/pin-contracts.v1.json
+       -> build/hardware-erc.v1.json
+       -> build/export-gate.v1.json
+  -> export-kicad only when export-gate allows it
+```
+
+The first implementation is a sidecar layer. It does not require changing `circuit-model.v1` immediately.
+
+## Why this layer exists
+
+KiCad ERC can detect many schematic-level connection problems, but it does not know product intent. For example, it may not know that:
+
+- a load switch with only ON connected is useless if VIN/VOUT are missing;
+- a charger IC with ISET/ILIM/TS floating is not a complete charger design;
+- a USB-C sink without CC Rd pulldowns may not receive VBUS;
+- a connector pin marked NC may actually be a mode strap that must be fixed;
+- a switched rail may have no downstream load;
+- an external interface may need ESD or current limiting.
+
+The Hardware Semantic Layer catches these design-intent failures before schematic export.
+
+## Core artifacts
+
+### 1. Net Intent
+
+`build/net-intents.v1.json` explains what each net means:
+
+- net kind;
+- members;
+- likely sources;
+- likely loads;
+- whether it is a power rail, ground reference, switched rail, or signal/configuration net.
+
+This makes power-tree and signal-flow review machine-readable.
+
+### 2. Pin Contract
+
+`build/pin-contracts.v1.json` explains each important IC pin:
+
+- pin type;
+- whether it is required;
+- resolved connection;
+- whether NC is allowed;
+- expected checks;
+- engineering rationale.
+
+A pin is not complete just because it has a wire. It is complete only when its behavior and default state are understood.
+
+### 3. Hardware ERC
+
+`build/hardware-erc.v1.json` contains semantic findings:
+
+- `BLOCKER`: KiCad export must not run;
+- `WARNING`: export may proceed only after review or waiver;
+- `INFO`: improvement or layout/DFT note.
+
+### 4. Export Gate
+
+`build/export-gate.v1.json` is the single decision file:
+
+```json
+{
+  "decision": "allow_export_kicad"
+}
+```
+
+or:
+
+```json
+{
+  "decision": "block_export_kicad"
+}
+```
+
+## Agent operating principles
+
+The agent must follow these rules:
+
+1. Treat `source/` as the human-editable source of truth.
+2. Treat `build/` and `output/` as generated artifacts.
+3. Do not export KiCad when `validate-ir` or Hardware ERC has blockers.
+4. Do not mark unknown pins NC without evidence.
+5. Do not create power nets without source and load intent.
+6. Do not leave EN, CE, MODE, BOOT, RESET, CS, ILIM, ISET, TS, or TMR behavior undefined.
+7. Do not assume external interfaces are safe without ESD/TVS/current-limit review.
+8. If information is missing, write an unresolved item instead of guessing.
+
+## P0 scope
+
+The first rule pack focuses on the components and interfaces that caused real errors in early designs:
+
+- TPS22918-style load switches;
+- BQ24074-style charger + power-path ICs;
+- USB-C USB2 sink connectors;
+- SPI e-paper display connectors.
+
+The implementation is intentionally conservative. It may produce warnings that need review, but it should prevent obviously incomplete circuits from reaching KiCad export.
+
+## Usage
+
+Run from a project directory:
+
+```powershell
+python scripts/hardware_semantic_gate.py --project .
+```
+
+Expected outputs:
+
+```text
+build/net-intents.v1.json
+build/pin-contracts.v1.json
+build/hardware-erc.v1.json
+build/export-gate.v1.json
+```
+
+Recommended full flow:
+
+```powershell
+hwtool agent status --project .
+hwtool agent inspect --project .
+hwtool agent resolve-symbols --project . --timeout 120
+hwtool agent build-ir --project .
+hwtool agent validate-ir --project .
+python scripts/hardware_semantic_gate.py --project .
+hwtool agent export-kicad --project .
+```
+
+`hwtool agent export-kicad` runs this gate before the KiCad export step and refuses to continue when `build/export-gate.v1.json` says `block_export_kicad`. The standalone script remains useful for local diagnosis and CI-focused checks.
+
+## Implementation roadmap
+
+### P0
+
+- Add sidecar schemas.
+- Add a standalone semantic gate script.
+- Add the first rule pack.
+- Generate pin-contract, net-intent, hardware-erc, and export-gate artifacts.
+
+### P1
+
+- Integrate as native `hwtool agent hardware-erc` command.
+- Add JSON schema validation for sidecar outputs.
+- Add regression tests for TPS22918, BQ24074, USB-C sink, and e-paper connector cases.
+- Include Hardware ERC status in `agent diagnose` and `agent report`.
+
+### P2
+
+- Promote stable fields into `circuit-model.v2` or keep sidecar as a formal extension mechanism.
+- Expand rule packs for LDO/DCDC, MCU boot straps, I2C, SPI, UART, SWD/JTAG, battery connector, sensors, and NFC.
+- Add waiver files for reviewed warnings.
+
+## Design philosophy
+
+The key phrase is:
+
+> First prove the topology, then draw the schematic.
+
+The agent should not ask, "Can I connect this wire?" It should ask:
+
+- What function does this module serve?
+- What energy, signal, and control flows pass through it?
+- What is every pin responsible for?
+- What default state exists at reset?
+- What could fail during power-up, sleep, charging, hot-plug, or manufacturing test?
+
+Only after that should the design enter KiCad.

pytest.ini

@@ -0,0 +1,3 @@
+[pytest]
+testpaths = tests
+python_files = test_*.py

resources/hardware-rules/hardware-semantic-rules.v0.1.yaml

@@ -0,0 +1,107 @@
+schema_version: hardware-semantic-rules.v0.1
+name: Hardware Semantic Rules v0.1
+purpose: >
+  Topology-first checks for hardware agents before KiCad export. These rules
+  complement KiCad ERC; they catch design-intent gaps that ordinary ERC often
+  cannot prove.
+
+severity_policy:
+  BLOCKER: Do not export KiCad until resolved.
+  WARNING: Export may continue only after review or explicit waiver.
+  INFO: Improvement or layout/DFT recommendation.
+
+global_rules:
+  - id: REQUIRED_PIN_UNRESOLVED
+    severity: BLOCKER
+    statement: Every required IC pin must have a resolved connection or explicit configuration.
+  - id: PIN_MARKED_NC_WITHOUT_REASON
+    severity: BLOCKER
+    statement: Unknown pins must never be marked NC without datasheet/module evidence.
+  - id: POWER_INPUT_WITHOUT_SOURCE
+    severity: BLOCKER
+    statement: Every power input must trace to an upstream source.
+  - id: POWER_OUTPUT_WITHOUT_LOAD
+    severity: BLOCKER
+    statement: Every power output or switched rail must have a real downstream load.
+  - id: ENABLE_MODE_BOOT_FLOATING
+    severity: BLOCKER
+    statement: EN, CE, MODE, BOOT, RESET, CS, ILIM, ISET, TS, TMR pins need defined states.
+  - id: EXPOSED_PAD_NOT_TIED
+    severity: BLOCKER
+    statement: Exposed pads default to GND/VSS copper unless the datasheet says otherwise.
+  - id: EXTERNAL_PORT_PROTECTION_REVIEW
+    severity: WARNING
+    statement: External ports require ESD, TVS, current limit, reverse-polarity, or waiver review.
+
+categories:
+  load_switch:
+    required_pins: [VIN, VOUT, GND, ON]
+    rules:
+      - VIN must connect to an upstream power rail.
+      - VOUT must connect to a distinct switched load rail.
+      - VOUT must have at least one real load.
+      - ON/EN must not float and must have a reset-safe default state.
+      - CT/SS/QOD optional pins must have an explicit strategy: NC with reason, capacitor, or discharge path.
+      - Check backfeed risk from signal pins when the switched rail is off.
+    typical_bias:
+      ON: pulldown_100k
+
+  charger_power_path:
+    required_pin_groups: [input_power, battery, system_output, ground, program_pins, temperature_sense, enable_mode]
+    rules:
+      - All BAT pins must connect to the same battery positive net.
+      - All OUT/SYS pins must connect to the same system rail.
+      - IN must have input decoupling.
+      - BAT and OUT/SYS must have required capacitors.
+      - ILIM and ISET must be programmed with resistors or a documented equivalent.
+      - TS must connect to battery NTC or a valid fixed-temperature strategy.
+      - CE/EN pins must not float.
+      - EP must connect to VSS/GND copper.
+
+  usb_c_sink_usb2:
+    rules:
+      - A4, A9, B4, B9 must all join VBUS.
+      - A1, A12, B1, B12 must all join GND.
+      - A6 and B6 must join D+.
+      - A7 and B7 must join D-.
+      - CC1 and CC2 must each have Rd to GND for sink/UFP operation.
+      - SBU pins may be explicit NC for USB2-only designs.
+      - VBUS, D+/D-, and CC pins need ESD/TVS review.
+    rd_value: 5.1k
+
+  epaper_spi_connector:
+    rules:
+      - VCC and GND must be defined.
+      - SCLK, MOSI, CS, DC, RST, BUSY must be connected.
+      - MISO is usually not required for display-only e-paper modules.
+      - CS should default inactive, usually pullup.
+      - RST should default not-reset, usually pullup.
+      - BUSY pullup requirement must be confirmed from module data.
+      - MODE/PWR_EN pins are module-specific and need explicit strategy.
+      - Battery products should define sleep or load-switch power-off behavior.
+    typical_bias:
+      CS: pullup_10k
+      RST: pullup_10k
+
+  regulator_ldo_dc_dc:
+    rules:
+      - VIN voltage range must cover upstream source tolerance.
+      - VOUT must match all downstream load voltage limits.
+      - Input and output capacitors must meet stability requirements.
+      - Feedback divider must produce the requested output voltage.
+      - EN must have a reset-safe default state.
+      - Thermal dissipation must be estimated for LDOs.
+
+  i2c_bus:
+    rules:
+      - SCL/SDA require pullups to a valid logic rail.
+      - All devices must tolerate the pullup voltage.
+      - Address conflicts must be checked.
+      - Level shifting is required across incompatible voltage domains.
+
+  spi_bus:
+    rules:
+      - Each slave needs an independent CS.
+      - All CS nets should default inactive.
+      - MISO may be omitted only with explicit reason.
+      - Fast or off-board lines should review series resistors and ESD.