@hybridlabor-api/bdb-hardware-pcb 0.1.0

package/scripts/test_mcp_connection.sh

@@ -0,0 +1,168 @@
+#!/usr/bin/env bash
+# ==============================================================================
+# AOS MCP Verification Test Suite Runner
+# ==============================================================================
+# Companion bash script to execute scripts/test_mcp_connection.py against
+# KiCad and OpenSCAD MCP servers, individual configs, and harnesses.
+# ==============================================================================
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+PYTHON="${PYTHON:-python3}"
+VERIFIER="${SCRIPT_DIR}/test_mcp_connection.py"
+
+# Ensure all scripts have executable permissions
+chmod +x "${SCRIPT_DIR}/"*.sh 2>/dev/null || true
+
+print_usage() {
+    echo "Usage: $0 [OPTIONS]"
+    echo ""
+    echo "Options:"
+    echo "  --all              Run complete test suite across runners and all config files"
+    echo "  --kicad            Test KiCad MCP server runner only"
+    echo "  --openscad         Test OpenSCAD MCP server runner only"
+    echo "  --antigravity      Test config/mcp/antigravity.json"
+    echo "  --claude           Test config/mcp/claude.json"
+    echo "  --codex            Test config/mcp/codex.toml"
+    echo "  --configs          Test all three multi-harness config files"
+    echo "  --export-schemas   Export Antigravity lazy schemas into ~/.gemini/antigravity-cli/mcp/"
+    echo "  --report PATH      Generate a machine-readable JSON verification report"
+    echo "  --help             Show this help message"
+}
+
+REPORT_FILE=""
+MODE="default"
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --all)
+            MODE="all"
+            shift
+            ;;
+        --kicad)
+            MODE="kicad"
+            shift
+            ;;
+        --openscad)
+            MODE="openscad"
+            shift
+            ;;
+        --antigravity)
+            MODE="antigravity"
+            shift
+            ;;
+        --claude)
+            MODE="claude"
+            shift
+            ;;
+        --codex)
+            MODE="codex"
+            shift
+            ;;
+        --configs)
+            MODE="configs"
+            shift
+            ;;
+        --export-schemas)
+            MODE="export"
+            shift
+            ;;
+        --report)
+            REPORT_FILE="$2"
+            shift 2
+            ;;
+        --help|-h)
+            print_usage
+            exit 0
+            ;;
+        *)
+            echo "Unknown option: $1" >&2
+            print_usage
+            exit 1
+            ;;
+    esac
+done
+
+EXTRA_ARGS=()
+if [[ -n "${REPORT_FILE}" ]]; then
+    EXTRA_ARGS+=("--json-report" "${REPORT_FILE}")
+fi
+
+# config/mcp/*.json|.toml are portable reference templates (placeholder
+# __INSTALL_DIR__, no machine-specific path baked in — see their header
+# comments). installer.js never reads them; it generates real configs at
+# install time. For local verification only, resolve the placeholder to this
+# checkout's actual path in a throwaway temp copy.
+RESOLVED_TMP_FILES=()
+cleanup_resolved_configs() {
+    for f in "${RESOLVED_TMP_FILES[@]+"${RESOLVED_TMP_FILES[@]}"}"; do
+        rm -f "$f"
+    done
+}
+trap cleanup_resolved_configs EXIT
+
+resolve_config() {
+    local src="$1"
+    local ext="${src##*.}"
+    local tmp
+    tmp="$(mktemp "${TMPDIR:-/tmp}/mcp_config.XXXXXX")"
+    mv "${tmp}" "${tmp}.${ext}"
+    tmp="${tmp}.${ext}"
+    sed "s#__INSTALL_DIR__#${REPO_DIR}#g" "${src}" > "${tmp}"
+    RESOLVED_TMP_FILES+=("${tmp}")
+    echo "${tmp}"
+}
+
+case "${MODE}" in
+    default)
+        echo "Running default MCP connection verification..."
+        "${PYTHON}" "${VERIFIER}" ${EXTRA_ARGS[@]+"${EXTRA_ARGS[@]}"}
+        ;;
+    kicad)
+        echo "Testing KiCad MCP Server Runner..."
+        "${PYTHON}" "${VERIFIER}" --command "${SCRIPT_DIR}/run_kicad_mcp.sh" ${EXTRA_ARGS[@]+"${EXTRA_ARGS[@]}"}
+        ;;
+    openscad)
+        echo "Testing OpenSCAD MCP Server Runner..."
+        "${PYTHON}" "${VERIFIER}" --command "${SCRIPT_DIR}/run_openscad_mcp.sh" ${EXTRA_ARGS[@]+"${EXTRA_ARGS[@]}"}
+        ;;
+    antigravity)
+        echo "Testing Antigravity MCP Config (config/mcp/antigravity.json)..."
+        "${PYTHON}" "${VERIFIER}" --config "$(resolve_config "${REPO_DIR}/config/mcp/antigravity.json")" ${EXTRA_ARGS[@]+"${EXTRA_ARGS[@]}"}
+        ;;
+    claude)
+        echo "Testing Claude Code MCP Config (config/mcp/claude.json)..."
+        "${PYTHON}" "${VERIFIER}" --config "$(resolve_config "${REPO_DIR}/config/mcp/claude.json")" ${EXTRA_ARGS[@]+"${EXTRA_ARGS[@]}"}
+        ;;
+    codex)
+        echo "Testing Codex MCP Config (config/mcp/codex.toml)..."
+        "${PYTHON}" "${VERIFIER}" --config "$(resolve_config "${REPO_DIR}/config/mcp/codex.toml")" ${EXTRA_ARGS[@]+"${EXTRA_ARGS[@]}"}
+        ;;
+    configs)
+        echo "Testing all multi-harness configuration files..."
+        echo "--- 1. Testing Antigravity Configuration ---"
+        "${PYTHON}" "${VERIFIER}" --config "$(resolve_config "${REPO_DIR}/config/mcp/antigravity.json")"
+        echo "--- 2. Testing Claude Code Configuration ---"
+        "${PYTHON}" "${VERIFIER}" --config "$(resolve_config "${REPO_DIR}/config/mcp/claude.json")"
+        echo "--- 3. Testing OpenAI Codex Configuration ---"
+        "${PYTHON}" "${VERIFIER}" --config "$(resolve_config "${REPO_DIR}/config/mcp/codex.toml")" ${EXTRA_ARGS[@]+"${EXTRA_ARGS[@]}"}
+        ;;
+    export)
+        TARGET_DIR="${HOME}/.gemini/antigravity-cli/mcp"
+        echo "Exporting lazy tool JSON schemas to ${TARGET_DIR}..."
+        "${PYTHON}" "${VERIFIER}" --export-antigravity "${TARGET_DIR}" ${EXTRA_ARGS[@]+"${EXTRA_ARGS[@]}"}
+        ;;
+    all)
+        echo "Executing Full MCP Verification Suite..."
+        TARGET_DIR="${HOME}/.gemini/antigravity-cli/mcp"
+        "${PYTHON}" "${VERIFIER}" --export-antigravity "${TARGET_DIR}"
+        echo "--- Testing Antigravity Config ---"
+        "${PYTHON}" "${VERIFIER}" --config "$(resolve_config "${REPO_DIR}/config/mcp/antigravity.json")"
+        echo "--- Testing Claude Code Config ---"
+        "${PYTHON}" "${VERIFIER}" --config "$(resolve_config "${REPO_DIR}/config/mcp/claude.json")"
+        echo "--- Testing OpenAI Codex Config ---"
+        "${PYTHON}" "${VERIFIER}" --config "$(resolve_config "${REPO_DIR}/config/mcp/codex.toml")" ${EXTRA_ARGS[@]+"${EXTRA_ARGS[@]}"}
+        ;;
+esac

package/skills/code-first-hardware-design/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: code-first-hardware-design
+description: "Programmatic schematic capture, circuit synthesis (SKiDL, text netlists, S-expressions), and parametric 3D CAD enclosure co-design (OpenSCAD/BOSL2). Use when generating circuits in code, exporting netlists, scripting KiCad schematics, or designing 3D enclosures."
+category: engineering-hardware
+compatibility: "Python 3.10+, SKiDL, OpenSCAD 2024+, BOSL2, mcp:openscad"
+---
+
+# Code-First Hardware & Circuit Design
+
+## 1. Overview and Core Philosophy
+
+In the AOS autonomous engineering architecture, hardware design is treated as code. Graphical schematic and mechanical CAD entry are prone to hallucinated coordinates, misaligned pins, and drift between PCB and enclosure models.
+
+This skill governs two tightly integrated code-first workflows:
+1. **Programmatic Circuit Synthesis (SKiDL / S-Expressions)**: Generating electronic schematics, hierarchical sheets, and netlists via type-safe, reviewable Python code with built-in Electrical Rules Checks (ERC).
+2. **Parametric Mechanical Co-Design (OpenSCAD / BOSL2)**: Generating production-ready 3D enclosures driven directly by exported PCB physical outlines, mounting hole centroids, and connector coordinates.
+
+---
+
+## 2. Programmatic Circuit Synthesis via SKiDL
+
+SKiDL allows circuits to be designed as Python programs. Components are instantiated from KiCad symbol libraries, connected via pythonic operator overloading, and compiled to netlists or KiCad schematic files.
+
+### 2.1 The SKiDL Connection Paradigm
+- **Nets**: Created as `Net('NAME')`.
+- **Buses**: Created as `Bus('DATA', 8)`.
+- **Connections**: Handled using the `+=` operator or list indexing:
+  ```python
+  vcc = Net('VCC')
+  gnd = Net('GND')
+  r1 = Part('Device', 'R', value='10k', footprint='Resistor_SMD:R_0603_1608Metric')
+  c1 = Part('Device', 'C', value='100nF', footprint='Capacitor_SMD:C_0603_1608Metric')
+  # Connect in parallel across power rail
+  vcc += r1[1], c1[1]
+  gnd += r1[2], c1[2]
+  ```
+
+### 2.2 Production Reference Circuit: Microcontroller Node with Power & USB
+Below is a complete, executable SKiDL circuit module (`hardware_design.py`) that instantiates power regulation, an RP2040 MCU, crystal oscillator, decoupling, and USB-C protection:
+
+```python
+#!/usr/bin/env python3
+"""
+Production-grade Code-First Hardware Circuit Synthesis using SKiDL.
+Generates KiCad netlist with built-in ERC validation.
+"""
+from skidl import *
+
+# Set target EDA tool to KiCad
+set_default_tool(KICAD)
+
+# 1. Global Power & Ground Nets
+vbus = Net('VBUS')
+v3v3 = Net('+3V3')
+gnd  = Net('GND')
+
+# 2. USB-C Input & ESD Protection
+usbc = Part('Connector', 'USB_C_Receptacle_USB2.0', footprint='Connector_USB:USB_C_Receptacle_GCT_USB4105')
+tvs  = Part('Power_Protection', 'USBLC6-2SC6', footprint='Package_TO_SOT_SMD:SOT-23-6')
+
+# Ground receptacle shield and GND pins
+gnd += usbc['GND*'], usbc['SHIELD'], tvs['GND']
+vbus += usbc['VBUS*'], tvs['VBUS']
+
+# CC Pull-Down Resistors (5.1k for standard 5V/3A UFP mode)
+r_cc1 = Part('Device', 'R', value='5.1k', footprint='Resistor_SMD:R_0402_1005Metric')
+r_cc2 = Part('Device', 'R', value='5.1k', footprint='Resistor_SMD:R_0402_1005Metric')
+usbc['CC1'] += r_cc1[1]
+usbc['CC2'] += r_cc2[1]
+gnd += r_cc1[2], r_cc2[2]
+
+# USB Data Lines through TVS
+usb_dp = Net('USB_DP')
+usb_dn = Net('USB_DN')
+usbc['DP*'] += tvs['I/O1']
+tvs['I/O1'] += usb_dp
+usbc['DN*'] += tvs['I/O2']
+tvs['I/O2'] += usb_dn
+
+# 3. LDO Voltage Regulator (5V -> 3.3V, AP2112K-3.3)
+ldo = Part('Regulator_Linear', 'AP2112K-3.3', footprint='Package_TO_SOT_SMD:SOT-23-5')
+cin  = Part('Device', 'C', value='4.7uF', footprint='Capacitor_SMD:C_0603_1608Metric')
+cout = Part('Device', 'C', value='4.7uF', footprint='Capacitor_SMD:C_0603_1608Metric')
+
+vbus += ldo['VIN'], ldo['EN'], cin[1]
+gnd  += ldo['GND'], cin[2], cout[2]
+v3v3 += ldo['VOUT'], cout[1]
+
+# 4. RP2040 Microcontroller
+mcu = Part('MCU_RaspberryPi_RP2040', 'RP2040', footprint='Package_DFN_QFN:QFN-56-1EP_7x7mm_P0.4mm_EP3.2x3.2mm')
+gnd += mcu['GND*'], mcu['EP']
+v3v3 += mcu['IOVDD*'], mcu['USB_VDD'], mcu['VREG_IN']
+
+# Connect USB Data
+mcu['USB_DP'] += usb_dp
+mcu['USB_DM'] += usb_dn
+
+# Decoupling Array: 100nF per IOVDD pin
+for pin in mcu.get_pins():
+    if 'IOVDD' in pin.name or 'VREG_IN' in pin.name:
+        c_dec = Part('Device', 'C', value='100nF', footprint='Capacitor_SMD:C_0402_1005Metric')
+        v3v3 += c_dec[1]
+        gnd  += c_dec[2]
+
+# 5. Execute Electrical Rules Check (ERC)
+print("--> Running SKiDL Electrical Rules Check (ERC)...")
+ERC()
+
+# 6. Generate Netlist for KiCad
+print("--> Compiling KiCad Netlist: board.net")
+generate_netlist(file_='board.net')
+```
+
+---
+
+## 3. Parametric Mechanical Enclosure Co-Design (OpenSCAD / BOSL2)
+
+Hardware enclosure design must strictly depend on exported PCB physical measurements:
+1. **Board Outline**: Ingested via `kicad-cli pcb export dxf --layers Edge.Cuts`.
+2. **Mounting Hole Coordinates**: Ingested from the Centroid placement file (`board_positions.csv`).
+3. **Connector Boundaries**: Aligned to exact component coordinates with manufacturing tolerances.
+
+### 3.1 Tolerance Standards for Enclosure Fit
+- **FDM 3D Printing (PLA / PETG)**:
+  - Internal cavity clearance around PCB perimeter: $+0.4\text{mm}$ per side.
+  - Connector cutouts (USB-C, HDMI): $+0.4\text{mm}$ height and width.
+  - Screw hole clearance: $+0.3\text{mm}$ (e.g., $3.3\text{mm}$ hole for M3 screw).
+  - Minimum wall thickness: $2.0\text{mm}$ for structural rigidity.
+- **Heat-Set Threaded Inserts (Brass)**:
+  - M2 Insert: Hole diameter $3.2\text{mm}$, depth $4.0\text{mm}$, boss outer diameter $\ge 6.0\text{mm}$.
+  - M3 Insert: Hole diameter $4.0\text{mm}$, depth $5.7\text{mm}$, boss outer diameter $\ge 7.5\text{mm}$.
+
+### 3.2 Production BOSL2 Enclosure Code (`enclosure.scad`)
+The following script utilizes the **BOSL2** library for analytical rounding (avoiding `minkowski()`) and builds a parametric snap-together / screw-down enclosure with standoff bosses and port cutouts:
+
+```openscad
+// Production Parametric PCB Enclosure using BOSL2
+// Run with: openscad -o enclosure.stl --backend=Manifold enclosure.scad
+
+include <BOSL2/std.scad>
+
+$fn = 64;
+
+// --- Parametric Dimensions (Derived from PCB constraints.yaml) ---
+pcb_w         = 75.0;     // PCB width in X
+pcb_l         = 45.0;     // PCB length in Y
+pcb_t         = 1.6;      // PCB thickness
+xy_clearance  = 0.4;      // Tolerance per side
+wall_t        = 2.0;      // Outer wall thickness
+standoff_h    = 5.0;      // Clearance below PCB
+ceiling_h     = 12.0;     // Component height ceiling above PCB
+
+// Computed internal dimensions
+int_w = pcb_w + (2 * xy_clearance);
+int_l = pcb_l + (2 * xy_clearance);
+int_h = standoff_h + pcb_t + ceiling_h;
+
+// Outer dimensions
+out_w = int_w + (2 * wall_t);
+out_l = int_l + (2 * wall_t);
+out_h = int_h + (2 * wall_t);
+
+// Mounting Hole Locations relative to PCB center [X, Y]
+mounting_holes = [
+    [-34.0, -19.0],
+    [ 34.0, -19.0],
+    [-34.0,  19.0],
+    [ 34.0,  19.0]
+];
+
+// --- Subassembly: Lower Enclosure Half ---
+module bottom_case() {
+    difference() {
+        // Outer rounded shell
+        cuboid([out_w, out_l, out_h/2], rounding=3, edges="Z", anchor=BOTTOM) {
+            // Internal cavity cutout
+            attach(TOP, TOP, inside=true)
+                cuboid([int_w, int_l, (out_h/2) - wall_t], anchor=TOP);
+        }
+        
+        // USB-C Connector Cutout (centered at X = -out_w/2, Z = standoff_h + pcb_t)
+        translate([-out_w/2, 0, standoff_h + pcb_t + 1.6])
+            cube([wall_t * 2, 9.6, 3.8], center=true);
+    }
+
+    // Standoff Bosses with M3 Heat-Set Insert Pockets
+    for (pos = mounting_holes) {
+        translate([pos[0], pos[1], wall_t]) {
+            difference() {
+                // Cylindrical standoff boss
+                cylinder(h=standoff_h, r=3.8, center=false);
+                // Heat-set brass insert pocket (M3: dia 4.0mm, depth 5.0mm)
+                translate([0, 0, standoff_h - 4.8])
+                    cylinder(h=5.0, r=2.0, center=false);
+            }
+        }
+    }
+}
+
+// --- Subassembly: Top Lid ---
+module top_case() {
+    translate([0, out_l + 15, 0]) {
+        difference() {
+            cuboid([out_w, out_l, out_h/2], rounding=3, edges="Z", anchor=BOTTOM) {
+                attach(TOP, TOP, inside=true)
+                    cuboid([int_w, int_l, (out_h/2) - wall_t], anchor=TOP);
+            }
+            // Ventilation slots
+            for (i = [-3:3]) {
+                translate([i * 6, 0, 0])
+                    cube([2.5, int_l - 10, wall_t * 3], center=true);
+            }
+        }
+    }
+}
+
+// Render complete assembly for 3D printing
+bottom_case();
+top_case();
+```
+
+---
+
+## 4. Automated Execution & Verification CLI Workflow
+
+1. **Synthesize Circuit Netlist via SKiDL**:
+   ```bash
+   python3 hardware_design.py
+   # Confirms ERC passes with 0 errors and writes board.net
+   ```
+
+2. **Ingest Physical Features from PCB via `kicad-cli`**:
+   ```bash
+   # Export board outline DXF
+   kicad-cli pcb export dxf -o cad/board_outline.dxf --layers Edge.Cuts board.kicad_pcb
+   # Export mounting hole centroids
+   kicad-cli pcb export pos --format csv -o cad/board_positions.csv board.kicad_pcb
+   ```
+
+3. **Validate and Compile 3D Enclosure via OpenSCAD Manifold**:
+   ```bash
+   # Fast syntax validation
+   openscad -o /dev/null --check-parameters true cad/enclosure.scad
+
+   # High-speed mesh compilation using the Manifold C++ engine
+   openscad -o cad/enclosure.stl --backend=Manifold cad/enclosure.scad
+
+   # Generate high-resolution perspective preview PNG
+   openscad -o cad/enclosure_preview.png --camera=0,0,0,55,0,25,180 --imgsize=1024,768 cad/enclosure.scad
+   ```
+
+---
+
+## 5. Negative Constraints (Anti-Slop Directives)
+
+- **DO NOT** use OpenSCAD's `minkowski()` function to generate rounded edges on production enclosures. It is computationally intractable and will cause agent timeouts. Always use BOSL2's analytical `cuboid(..., rounding=..., edges=...)`.
+- **DO NOT** guess mounting hole or connector positions. Coordinates must be read directly from `constraints.yaml` or exported from `kicad-cli pcb export pos`.
+- **DO NOT** generate SKiDL circuits without running `ERC()` before netlist export. An unverified netlist is prohibited from passing to layout.
+- **DO NOT** design 3D printable enclosures with wall thickness $<1.6\text{mm}$ or standoff bosses with wall thickness $<1.5\text{mm}$ around heat-set insert pockets (causes layer splitting upon insert press).
+- **DO NOT** omit the $+0.4\text{mm}$ mechanical tolerance margin around PCB board edges when modeling internal enclosure cavities.

package/skills/pcb-constraint-definition/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: pcb-constraint-definition
+description: "Translates high-level hardware requirements into formal engineering constraints, layer stackup calculations, netclasses, and custom DRC rules for KiCad. Use when defining board constraints, stackup, impedance matching, power budgeting, or netclasses."
+category: engineering-hardware
+compatibility: "Python 3.10+, kicad-cli 8+, mcp:kicad"
+---
+
+# PCB Constraint & Specification Definition
+
+## 1. Overview and Core Philosophy
+
+In the AOS hardware engineering pipeline, constraints are not informal recommendations; they are formal, machine-executable boundary conditions. An AI hardware agent must never begin schematic capture or board layout with unconstrained nets or default 0.25mm trace widths. 
+
+This skill provides the mathematical models, layer stackup architectures, netclass definitions, and custom Design Rule Check (DRC) constraint files required to translate product specifications into production-ready physical parameters.
+
+---
+
+## 2. Mathematical and Physical Foundations
+
+All physical trace geometry and thermal boundaries must be derived from first principles and IPC standards:
+
+### 2.1 Trace Current Capacity (IPC-2152)
+The current carrying capacity $I$ (Amperes) for a given allowable temperature rise $\Delta T$ ($^\circ\text{C}$) and conductor cross-sectional area $A$ ($\text{mils}^2$) is calculated as:
+
+$$I = k \cdot \Delta T^{0.44} \cdot A^{0.725}$$
+
+Where:
+- $k = 0.048$ for external surface microstrip traces (convective cooling).
+- $k = 0.024$ for internal stripline traces (conductive cooling through dielectric only).
+- $A = w \cdot t$, with trace width $w$ ($\text{mils}$) and copper thickness $t$ ($1\text{ oz} \approx 1.37\text{ mils} = 35\mu\text{m}$, $2\text{ oz} \approx 2.74\text{ mils} = 70\mu\text{m}$).
+
+**Minimum Trace Width Calculation for DC Power Rails:**
+To support a continuous current of $2.5\text{A}$ with $\Delta T = 10^\circ\text{C}$ on $1\text{ oz}$ external copper:
+$$A = \left( \frac{I}{0.048 \cdot \Delta T^{0.44}} \right)^{\frac{1}{0.725}} = \left( \frac{2.5}{0.048 \cdot 10^{0.44}} \right)^{1.379} \approx 42.5\text{ mils}^2$$
+$$w = \frac{A}{t} = \frac{42.5}{1.37} \approx 31.0\text{ mils} \approx 0.79\text{ mm}$$
+
+### 2.2 Controlled Impedance Modeling (IPC-2141)
+
+#### Single-Ended Microstrip (Surface Layer over Solid GND Plane)
+Characteristic impedance $Z_0$ ($\Omega$):
+$$Z_0 = \frac{87}{\sqrt{\varepsilon_r + 1.41}} \ln\left( \frac{5.98 h}{0.8 w + t} \right)$$
+Valid for $0.1 < \frac{w}{h} < 3.0$ and $1 < \varepsilon_r < 15$.
+- Standard FR-4 dielectric constant: $\varepsilon_r \approx 4.3 - 4.5$.
+- For standard $h = 0.2\text{mm}$ (7.87 mils), $t = 35\mu\text{m}$ (1.37 mils), target $Z_0 = 50\Omega \implies w \approx 0.36\text{mm}$ (14.2 mils).
+
+#### Edge-Coupled Differential Microstrip (USB 90Ω, Ethernet/PCIe 100Ω)
+Differential impedance $Z_{diff}$ ($\Omega$):
+$$Z_{diff} \approx 2 Z_0 \left( 1 - 0.48 e^{-0.96 \frac{s}{h}} \right)$$
+Where $s$ is the edge-to-edge separation between the two complementary conductors, and $h$ is the dielectric height to the nearest solid reference plane.
+
+### 2.3 Thermal Budgeting & Junction Temperature
+For any active linear regulator or power switch:
+$$T_J = T_A + P_D \cdot \theta_{JA}$$
+$$P_D = (V_{in} - V_{out}) \cdot I_{load} + V_{in} \cdot I_Q$$
+If $T_J > 105^\circ\text{C}$ at $T_A = 40^\circ\text{C}$ (maximum ambient), the agent must constrain:
+1. Addition of a dedicated copper thermal pad connected via an array of thermal vias ($0.3\text{mm}$ drill, $0.6\text{mm}$ pitch).
+2. Minimum copper plane area: $A_{Cu} \ge \frac{P_D \cdot 1000}{35}\text{ mm}^2$.
+
+---
+
+## 3. Standard Layer Stackups
+
+The agent must select one of the following industry-standard stackups based on circuit frequency and density:
+
+### 3.1 4-Layer Standard Controlled-Impedance Stackup (JLC04161H-7628)
+Total nominal thickness: $1.6\text{mm}$.
+- **Layer 1 (Top Signal / High-Speed)**: $35\mu\text{m}$ Copper ($1\text{ oz}$)
+  - *Prepreg 7628*: $0.2104\text{mm}$, $\varepsilon_r = 4.6$
+- **Layer 2 (Internal GND Plane)**: $17.5\mu\text{m}$ Copper ($0.5\text{ oz}$) - Continuous reference
+  - *Core FR-4*: $1.065\text{mm}$, $\varepsilon_r = 4.6$
+- **Layer 3 (Internal Power Plane)**: $17.5\mu\text{m}$ Copper ($0.5\text{ oz}$) - Power split planes
+  - *Prepreg 7628*: $0.2104\text{mm}$, $\varepsilon_r = 4.6$
+- **Layer 4 (Bottom Signal / Power Return)**: $35\mu\text{m}$ Copper ($1\text{ oz}$)
+
+### 3.2 6-Layer Advanced High-Density Stackup
+For dense microcontrollers (BGA/QFN) with mixed RF and high-speed memory:
+- **L1 (Top Signal)**: $35\mu\text{m}$ - Microstrip signals & RF
+- **L2 (GND 1)**: $17.5\mu\text{m}$ - Solid ground plane directly below L1
+- **L3 (Inner Signal 1)**: $17.5\mu\text{m}$ - Stripline high-speed routing
+- **L4 (Power / GND 2)**: $17.5\mu\text{m}$ - Power distribution
+- **L5 (GND 3)**: $17.5\mu\text{m}$ - Solid ground plane directly above L6
+- **L6 (Bottom Signal)**: $35\mu\text{m}$ - Low-speed signals, testpoints, connectors
+
+---
+
+## 4. Formal Constraint Manifest Schema (`constraints.yaml`)
+
+Every hardware project must emit a validated `constraints.yaml` prior to schematic or PCB routing. The schema is specified below:
+
+```yaml
+schema_version: "1.0.0"
+project_name: "iot-telemetry-node"
+target_fabricator: "JLCPCB"
+
+operating_conditions:
+  ambient_temp_min_c: -20
+  ambient_temp_max_c: 65
+  max_allowable_temp_rise_c: 15
+  v_in_nominal: 5.0
+  v_in_max: 5.5
+  peak_current_a: 2.2
+
+board_envelope:
+  outline_type: "rectangular"
+  width_mm: 75.0
+  length_mm: 45.0
+  corner_radius_mm: 2.5
+  pcb_thickness_mm: 1.6
+  copper_layers: 4
+  mounting_holes:
+    diameter_mm: 3.2 # M3 screw clearance
+    keepout_diameter_mm: 6.5 # Screw head + washer clearance
+    locations_mm:
+      - [3.5, 3.5]
+      - [71.5, 3.5]
+      - [3.5, 41.5]
+      - [71.5, 41.5]
+
+stackup:
+  profile: "JLC04161H-7628"
+  dielectric_er: 4.6
+  copper_outer_oz: 1.0
+  copper_inner_oz: 0.5
+  layer_assignments:
+    1: "TOP_SIGNAL"
+    2: "GND_PLANE"
+    3: "PWR_PLANE"
+    4: "BOTTOM_SIGNAL"
+
+netclasses:
+  Default:
+    track_width_mm: 0.20
+    clearance_mm: 0.20
+    via_drill_mm: 0.30
+    via_size_mm: 0.60
+    description: "Standard low-speed digital GPIO and logic nets"
+
+  PWR_HIGH_CURRENT:
+    track_width_mm: 0.80 # Sized via IPC-2152 for 2.5A, 10C rise
+    clearance_mm: 0.30
+    via_drill_mm: 0.40
+    via_size_mm: 0.80
+    nets: ["+5V", "VBUS", "+3V3_REG"]
+
+  GND:
+    track_width_mm: 0.40
+    clearance_mm: 0.25
+    via_drill_mm: 0.30
+    via_size_mm: 0.60
+    nets: ["GND", "GND_PWR"]
+
+  USB_DIFF_90:
+    impedance_target_ohms: 90
+    impedance_tolerance_pct: 10
+    track_width_mm: 0.38
+    diff_pair_gap_mm: 0.18
+    clearance_mm: 0.30
+    max_unmatched_length_mm: 0.10
+    nets: ["USB_DP", "USB_DN"]
+
+  ANALOG_SENSITIVE:
+    track_width_mm: 0.25
+    clearance_mm: 0.35
+    guard_ring: true
+    nets: ["ADC_IN0", "ADC_IN1", "VREF"]
+
+manufacturing_limits:
+  min_track_width_mm: 0.127 # 5 mil
+  min_clearance_mm: 0.127 # 5 mil
+  min_drill_diameter_mm: 0.20 # 8 mil
+  min_annular_ring_mm: 0.15
+  min_solder_mask_bridge_mm: 0.10
+  board_edge_clearance_mm: 0.35
+```
+
+---
+
+## 5. KiCad Custom Design Rules (`.kicad_dru`) Generation
+
+The agent must translate the netclasses and clearance constraints into KiCad's native custom rules syntax (`project.kicad_dru`):
+
+```lisp
+(version 1)
+
+# Ensure high voltage nets have adequate physical clearance
+(rule "High_Voltage_Clearance"
+   (constraint clearance (min 1.2mm))
+   (condition "A.NetClass == 'MAINS_AC' && B.NetClass != 'MAINS_AC'"))
+
+# Prevent high-speed signals from getting close to board edges
+(rule "Board_Edge_Clearance_HighSpeed"
+   (constraint edge_clearance (min 1.0mm))
+   (condition "A.NetClass == 'USB_DIFF_90' || A.NetClass == 'RF_50'"))
+
+# Enforce minimum drill hole-to-hole clearance to prevent drill wander shorts
+(rule "Hole_To_Hole_Clearance"
+   (constraint hole_to_hole (min 0.25mm)))
+
+# Guard sensitive analog nets from digital switching noise
+(rule "Analog_Clearance_To_Digital"
+   (constraint clearance (min 0.40mm))
+   (condition "A.NetClass == 'ANALOG_SENSITIVE' && B.NetClass == 'Default'"))
+
+# Require thermal reliefs on ground plane connection
+(rule "Plane_Thermal_Reliefs"
+   (constraint thermal_spoke_width (min 0.35mm))
+   (condition "A.NetClass == 'GND'"))
+```
+
+---
+
+## 6. Execution Workflow & Tool Invocations
+
+1. **Parameter Ingestion**:
+   - Extract power requirements, communication interfaces, and mechanical form factors from the user brief.
+2. **IPC-2152 & IPC-2141 Synthesis**:
+   - Calculate trace widths for every power net based on peak expected current.
+   - Calculate trace width ($W$) and differential gap ($S$) based on stackup dielectric height ($h$).
+3. **Artifact Generation**:
+   - Write `pcb_constraints.yaml` in the project root.
+   - Write `board.kicad_dru` in the project root.
+4. **Validation via `kicad-cli`**:
+   - Verify that the generated rule syntax compiles cleanly against `kicad-cli`:
+     ```bash
+     kicad-cli pcb drc --exit-code-violations --rules board.kicad_dru board.kicad_pcb
+     ```
+
+---
+
+## 7. Negative Constraints (Anti-Slop Directives)
+
+- **DO NOT** use default KiCad trace widths (0.25mm) for power rails carrying $>0.5\text{A}$. Every power rail must be sized using the IPC-2152 formula.
+- **DO NOT** specify 2-layer stackups for designs containing high-speed USB (480 Mbps+), Ethernet, or microcontrollers running $>100\text{ MHz}$ core clocks without an explicit solid ground flood on Layer 2.
+- **DO NOT** define mounting hole clearances that only cover the drill hole. Mounting keepouts must encompass the bolt head plus standard socket tool clearance ($\ge 6.5\text{mm}$ for M3).
+- **DO NOT** place annular rings below $0.15\text{mm}$ ($6\text{ mils}$) unless the project explicitly targets advanced laser micro-via processes ($>10\times$ fabrication cost).
+- **DO NOT** define differential pairs without an explicit intra-pair skew tolerance (maximum allowable length mismatch $\le 0.1\text{mm}$).