Skip to content

hashgraph-online/awesome-codex-plugins / plugins/aklofas/kicad-happy/skills/kicad

Analyze KiCad projects and PDF schematics: schematics, PCB layouts, Gerbers, footprints, symbols, netlists, and design rules. Reviews designs for bugs, traces nets, cross-references schematic to PCB, extracts BOM data, checks DRC/ERC, DFM, power trees, and regulator circuits. Every finding carries a confidence label and evidence source with trust_summary rollup. Analyzes PDF schematics from dev boards, reference designs, eval kits, and datasheets. Supports KiCad 5–10. Use whenever the user mentions .kicad_sch, .kicad_pcb, .kicad_pro, PCB design review, schematic analysis, PDF schematics, reference designs, Gerber files, DRC/ERC, netlist issues, BOM extraction, signal tracing, power budget, DFM, or wants to understand, debug, compare, or review any hardware design. Also for "check my board", "review before fab", "what's wrong with my schematic", "is this ready to order", "check my power supply", "verify this circuit", OSHWA certification readiness, or any electronics/PCB design question.

FileKindSize
SKILL.mdskill md79.1 KB
references/config-reference.mdmarkdown19.1 KB
references/datasheet-verification.mdmarkdown16.5 KB
references/deep-review.mdmarkdown9.7 KB
references/design-intent.mdmarkdown5.6 KB
references/diff-analysis.mdmarkdown17.6 KB
references/file-formats.mdmarkdown15.1 KB
references/gerber-parsing.mdmarkdown33.5 KB
references/manual-gerber-parsing.mdmarkdown24.5 KB
references/manual-pcb-parsing.mdmarkdown17.2 KB
references/manual-schematic-parsing.mdmarkdown12.8 KB
references/net-tracing.mdmarkdown12.0 KB
references/oshwa-certification.mdmarkdown4.5 KB
references/output-schema.mdmarkdown33.4 KB
references/pcb-layout-analysis.mdmarkdown27.3 KB
references/pdf-schematic-extraction.mdmarkdown15.2 KB
references/report-generation.mdmarkdown56.3 KB
references/schematic-analysis.mdmarkdown63.9 KB
references/standards-compliance.mdmarkdown33.5 KB
references/supplementary-data-sources.mdmarkdown12.5 KB
references/what-if.mdmarkdown19.5 KB
review/README.mdmarkdown4.1 KB
review/fixtures/deep_review.example.jsonconfig1.2 KB
review/fixtures/design_context.example.jsonconfig388 B
review/fixtures/review_annotations.example.jsonconfig707 B
review/prompts/design_context.mdmarkdown4.9 KB
review/schemas/deep_review.schema.jsonconfig3.3 KB
review/schemas/design_context.schema.jsonconfig2.2 KB
review/schemas/review_annotations.schema.jsonconfig1.9 KB
review/scripts/_mini_jsonschema.pyscript6.6 KB
review/scripts/build_review_plan.pyscript2.3 KB
review/scripts/deep_review_gate.pyscript27.3 KB
review/scripts/merge_annotations.pyscript7.0 KB
review/scripts/validate_review.pyscript2.6 KB
scripts/.gitignoreother13 B
scripts/README.mdmarkdown23.4 KB
scripts/analysis_cache.pyscript42.1 KB
scripts/analyze_gerbers.pyscript90.9 KB
scripts/analyze_pcb.pyscript7.4 KB
scripts/analyze_schematic.pyscript6.7 KB
scripts/analyze_thermal.pyscript48.5 KB
scripts/analyzer_envelope.pyscript15.5 KB
scripts/capability_mode.pyscript10.2 KB
scripts/check_report_sections.pyscript10.6 KB
scripts/cross_analysis.pyscript69.4 KB
scripts/cross_verify.pyscript23.1 KB
scripts/design_intent.pyscript13.5 KB
scripts/detection_schema.pyscript26.0 KB
scripts/detector_helpers.pyscript15.2 KB
scripts/diff_analysis.pyscript23.5 KB
scripts/diff_engine.pyscript47.2 KB
scripts/domain_detectors.pyscript260.5 KB
scripts/envelopes/__init__.pyscript0 B
scripts/envelopes/cross_analysis.pyscript5.9 KB
scripts/envelopes/gerber.pyscript16.1 KB
scripts/envelopes/pcb.pyscript25.9 KB
scripts/envelopes/schematic.pyscript23.1 KB
scripts/envelopes/thermal.pyscript7.4 KB
scripts/export_issues.pyscript27.6 KB
scripts/fab_release_gate.pyscript29.8 KB
scripts/finding_schema.pyscript25.7 KB
scripts/gen_output_schema_md.pyscript9.2 KB
scripts/inputs_builder.pyscript4.0 KB
scripts/kicad_core/__init__.pyscript0 B
scripts/kicad_core/classify.pyscript32.5 KB
scripts/kicad_core/cli.pyscript4.2 KB
scripts/kicad_core/coords.pyscript2.0 KB
scripts/kicad_core/diagnostics.pyscript1.9 KB
scripts/kicad_core/executables.pyscript1.0 KB
scripts/kicad_core/fields.pyscript5.9 KB
scripts/kicad_core/fileio.pyscript5.4 KB
scripts/kicad_core/hotloop.pyscript3.1 KB
scripts/kicad_core/instances.pyscript5.7 KB
scripts/kicad_core/model.pyscript4.8 KB
scripts/kicad_core/netnames.pyscript19.1 KB
scripts/kicad_core/netquery.pyscript6.7 KB
scripts/kicad_core/pairing.pyscript1.9 KB
scripts/kicad_core/parts.pyscript28.9 KB
scripts/kicad_core/passives.pyscript10.0 KB
scripts/kicad_core/pdn.pyscript1011 B
scripts/kicad_core/project.pyscript43.2 KB
scripts/kicad_core/render.pyscript2.7 KB
scripts/kicad_core/sexp.pyscript12.6 KB
scripts/kicad_core/textvars.pyscript5.4 KB
scripts/kicad_core/token_cache.pyscript2.2 KB
scripts/kicad_core/values.pyscript14.1 KB
scripts/kicad_types.pyscript15.1 KB
scripts/lifecycle_audit.pyscript6.7 KB
scripts/lifecycle_engine.pyscript52.8 KB
scripts/lookup_detectors.pyscript29.9 KB
scripts/lookup_helpers.pyscript3.0 KB
scripts/methodology_gerbers.mdmarkdown23.1 KB
scripts/methodology_pcb.mdmarkdown22.2 KB
scripts/methodology_schematic.mdmarkdown43.1 KB
scripts/netlist_queries.pyscript4.2 KB
scripts/output_filters.pyscript16.8 KB
scripts/output_io.pyscript5.3 KB
scripts/pcb/__init__.pyscript0 B
scripts/pcb/assembly.pyscript58.3 KB
scripts/pcb/connectivity.pyscript27.7 KB
scripts/pcb/copper.pyscript61.0 KB
scripts/pcb/dfm.pyscript56.9 KB
scripts/pcb/geometry.pyscript59.5 KB
scripts/pcb/pipeline.pyscript30.3 KB
scripts/pcb/presentation.pyscript24.3 KB
scripts/pcb/reader.pyscript87.1 KB
scripts/pcb/routing.pyscript53.5 KB
scripts/project_config.pyscript23.1 KB
scripts/risk_summary.pyscript3.1 KB
scripts/run_id.pyscript1.7 KB
scripts/schema_codec.pyscript5.0 KB
scripts/schematic/__init__.pyscript0 B
scripts/schematic/audits.pyscript56.0 KB
scripts/schematic/bom_stats.pyscript6.1 KB
scripts/schematic/connectivity.pyscript62.9 KB
scripts/schematic/erc_pins.pyscript8.4 KB
scripts/schematic/hierarchy.pyscript21.5 KB
scripts/schematic/ic_analysis.pyscript21.4 KB
scripts/schematic/legacy_reader.pyscript49.4 KB
scripts/schematic/net_analysis.pyscript75.5 KB
scripts/schematic/pipeline.pyscript72.2 KB
scripts/schematic/presentation.pyscript20.9 KB
scripts/schematic/reader.pyscript64.7 KB
scripts/schematic/system_analyses.pyscript126.9 KB
scripts/signal_detectors.pyscript248.0 KB
scripts/summarize_findings.pyexecutablescript17.4 KB
scripts/validation_detectors.pyscript75.3 KB
scripts/what_if.pyscript68.4 KB

scripts/validation_detectors.py

View on GitHub
"""Validation detectors — correctness checks that emit rich findings.

Separated from domain_detectors.py (which discovers circuit topologies).
These detectors check for design errors: missing components, wrong values,
protocol violations, sequencing issues.

Each validator takes an AnalysisContext (and optional detector results) and
returns a list of rich finding dicts via finding_schema.make_finding(
    source=ctx.source,).
"""

from __future__ import annotations

import re

from kicad_types import AnalysisContext
from kicad_core.netnames import is_usb_data_net_name, is_usb_signal_net_name, parse_voltage_from_net_name
from kicad_core.parts import LOAD_SWITCH_KEYWORDS, names_load_switch

try:
    import os as _os, sys as _sys
    _ds_scripts = _os.path.join(_os.path.dirname(_os.path.abspath(__file__)),
                                '..', '..', 'datasheets', 'scripts')
    if _os.path.isdir(_ds_scripts):
        _sys.path.insert(0, _os.path.abspath(_ds_scripts))
    from datasheet_features import get_regulator_features, get_mcu_features
    _HAS_DS = True
except ImportError:
    _HAS_DS = False
    def get_regulator_features(mpn, **kw): return None
    def get_mcu_features(mpn, **kw): return None

from detector_helpers import (
    get_components_by_type, get_pin_net, get_unique_ics, index_two_pin_components,
    is_led_rail, led_forward_voltage, led_string, match_ic_keywords,
)
from finding_schema import make_finding, make_provenance
from lookup_helpers import get_facts, has_data, best


# ---------------------------------------------------------------------------
# Shared pull-up/pull-down detection helpers
# ---------------------------------------------------------------------------

def _find_pullups_on_net(
    ctx: AnalysisContext,
    net_name: str,
    resistor_nets: dict[str, tuple[str, str]],
    net_to_resistors: dict[str, list[str]],
) -> list[dict]:
    """Find pull-up resistors on a net (resistor between net and power rail).

    Returns list of dicts: [{ref, ohms, rail}].
    """
    pullups = []
    for rref in net_to_resistors.get(net_name, []):
        n1, n2 = resistor_nets.get(rref, (None, None))
        if not n1 or not n2:
            continue
        other = n2 if n1 == net_name else n1
        if ctx.is_power_net(other) and not ctx.is_ground(other):
            ohms = ctx.parsed_values.get(rref)
            pullups.append({'ref': rref, 'ohms': ohms, 'rail': other})
    return pullups


# Library / footprint substrings that identify a bridged-by-default solder
# jumper. SolderJumper_2_Bridged (Jumper library) is the canonical KiCad
# symbol; the footprint name carries _Bridged_ too. Without this, I2C buses
# behind bridged jumpers draw false pull-up findings.
_BRIDGED_JUMPER_LIB_SUBSTRINGS = (
    'solderjumper_2_bridged',
    'solderjumper-2_p1.3mm_bridged',  # standard footprint suffix
)


def _bridged_jumper_neighbor_nets(ctx: AnalysisContext, net_name: str) -> list[str]:
    """Return nets reachable from `net_name` via one hop through a
    SolderJumper_2_Bridged. Used to extend pull-up search across
    bridged-by-default jumpers (PR-001 I2C check).
    """
    if not net_name:
        return []
    neighbors: list[str] = []
    seen: set[str] = set()
    for comp in ctx.components:
        lib = (comp.get('lib_id', '') + ' ' + comp.get('footprint', '')).lower()
        if not any(s in lib for s in _BRIDGED_JUMPER_LIB_SUBSTRINGS):
            continue
        ref = comp.get('reference')
        if not ref:
            continue
        # Two-pin jumper; collect nets on its pins
        jumper_nets = set()
        for pnum, (net, _) in (ctx.ref_pins.get(ref, {}) or {}).items():
            if net:
                jumper_nets.add(net)
        if net_name not in jumper_nets or len(jumper_nets) != 2:
            continue
        for n in jumper_nets:
            if n != net_name and n not in seen:
                seen.add(n)
                neighbors.append(n)
    return neighbors


def _find_pullups_on_net_with_bridged(
    ctx: AnalysisContext,
    net_name: str,
    resistor_nets: dict[str, tuple[str, str]],
    net_to_resistors: dict[str, list[str]],
) -> list[dict]:
    """Like `_find_pullups_on_net` but also walks one hop through
    SolderJumper_2_Bridged to find pullups attached on the bridged side
    of the jumper.
    """
    pullups = list(_find_pullups_on_net(ctx, net_name, resistor_nets, net_to_resistors))
    for neighbor in _bridged_jumper_neighbor_nets(ctx, net_name):
        for pu in _find_pullups_on_net(ctx, neighbor, resistor_nets, net_to_resistors):
            if pu not in pullups:
                pullups.append(pu)
    return pullups


def _find_pulldowns_on_net(
    ctx: AnalysisContext,
    net_name: str,
    resistor_nets: dict[str, tuple[str, str]],
    net_to_resistors: dict[str, list[str]],
) -> list[dict]:
    """Find pull-down resistors on a net (resistor between net and ground)."""
    pulldowns = []
    for rref in net_to_resistors.get(net_name, []):
        n1, n2 = resistor_nets.get(rref, (None, None))
        if not n1 or not n2:
            continue
        other = n2 if n1 == net_name else n1
        if ctx.is_ground(other):
            ohms = ctx.parsed_values.get(rref)
            pulldowns.append({'ref': rref, 'ohms': ohms, 'rail': other})
    return pulldowns


def _net_has_driver(ctx: AnalysisContext, net_name: str, exclude_ref: str) -> bool:
    """True when another IC sits on the net. Any IC counts, whatever its pin type: it may drive the line push-pull or hold it with a firmware-enabled internal pull-up, neither of which the schematic shows, so PU-001 does not ask for an external resistor."""
    if not net_name or net_name not in ctx.nets:
        return False
    for p in ctx.nets[net_name]['pins']:
        if p['component'] == exclude_ref:
            continue
        comp = ctx.comp_lookup.get(p['component'])
        if not comp:
            continue
        if comp['type'] == 'ic':
            return True  # Conservative: assume IC outputs can drive
    return False


# ---------------------------------------------------------------------------
# PU-001: Missing pull-ups / pull-downs
# ---------------------------------------------------------------------------

# Pin names that typically require pull-up resistors
_PULLUP_PIN_NAMES = (
    'NRST', 'NRESET', 'RESET', 'RST', 'RESET_N', 'RST_N', 'XRES',
    'EN', 'ENABLE', 'CE', 'SHDN', 'SHUTDOWN', 'nSHDN',
    'INT', 'IRQ', 'ALERT', 'DRDY', 'BUSY', 'RDY',
    'INT1', 'INT2', 'IRQ1', 'IRQ2', 'ALERT1', 'ALERT2',
    'SDA', 'SCL', 'I2C_SDA', 'I2C_SCL',
    'OD', 'OPEN_DRAIN',
    'PG', 'PGOOD', 'POWER_GOOD', 'nPG',
    'FAULT', 'nFAULT', 'FLAG', 'nFLAG',
    'STAT', 'STAT1', 'STAT2', 'CHG', 'nCHG',
    'WDI', 'WDO', 'MR', 'nMR',
)

# Pin names that typically require pull-down resistors
_PULLDOWN_PIN_NAMES = (
    'BOOT0',  # STM32 boot mode selection
    'MODE', 'CFG', 'SEL',
)

# ICs known to have open-drain / open-collector outputs
_OPEN_DRAIN_IC_KEYWORDS = (
    'pca9', 'tca9', 'pcf8574', 'pcf8575',  # I2C GPIO expanders
    'mcp23', 'sx1509',                       # GPIO expanders
    'ina219', 'ina226', 'ina228', 'ina260',  # Current monitors (ALERT)
    'tmp1', 'tmp4', 'lm75', 'ds18b20',       # Temp sensors (ALERT/DQ)
    'max3', 'max1',                           # Supervisors
    'tps38', 'tps386',                        # Voltage supervisors
    'stusb', 'fusb',                          # USB PD controllers
)

# Typical pull-up value range (ohms) — flag if outside
_PULLUP_MIN_OHMS = 1000      # 1k — below this is suspicious
_PULLUP_MAX_OHMS = 100000    # 100k — above this is weak

# Regulators with internal EN pull-up — EN can be left floating (the part
# enables itself by default) without a discrete external pull-up. Per-part
# prefixes from TI/MPS/Microchip; pattern-match against IC value/MPN upper-cased.
_INTERNAL_EN_PULLUP_REGULATOR_PREFIXES = (
    'TPS54302', 'TPS5430',     # TI sync buck (D-CAP2) — internal EN pull-up
    'TPS6213',                 # TI buck with internal soft-start + EN pull-up
    'MCP1727',                 # Microchip LDO
    'MP2315', 'MP2303',        # MPS sync bucks
    'LMR33630',                # TI sync buck
)
_EN_PIN_PATTERN_SET = frozenset((
    'EN', 'ENABLE', 'CE', 'SHDN', 'SHUTDOWN', 'NSHDN', 'ON', 'ONOFF', 'RUN',
))


def _has_internal_en_pullup(ic: dict, pin_name: str) -> bool:
    """True when (ic, pin) matches a regulator whose datasheet says EN may
    be left floating (internal pull-up). Used to suppress PU-001 missing-
    pullup warnings on those parts' EN pins.
    """
    pin_upper = pin_name.upper().replace('-', '').replace('_', '')
    if pin_upper not in _EN_PIN_PATTERN_SET:
        return False
    val_mpn = ((ic.get('mpn') or '') + ' ' + (ic.get('value') or '')).upper()
    return any(prefix in val_mpn for prefix in _INTERNAL_EN_PULLUP_REGULATOR_PREFIXES)


def validate_pullups(ctx: AnalysisContext) -> list[dict]:
    """PU-001: Check for missing pull-up/pull-down resistors on logic pins.

    Scans IC pins with names matching known open-drain, reset, enable, and
    interrupt patterns. For each, checks whether a pull-up or pull-down
    resistor exists on the same net. Emits findings for missing or
    out-of-range resistors.
    """
    findings: list[dict] = []

    resistors = get_components_by_type(ctx, 'resistor')
    resistor_nets, net_to_resistors = index_two_pin_components(ctx, resistors)

    ics = get_unique_ics(ctx)
    checked_nets: set[str] = set()

    cache_dir = getattr(ctx, 'cache_dir', None)

    for ic in ics:
        ref = ic['reference']
        mpn = ic.get('mpn') or ic.get('value') or ''
        facts = get_facts(mpn, cache_dir=cache_dir, diagnostics=getattr(ctx, "diagnostics", None)) if mpn else None
        pins = ctx.ref_pins.get(ref, {})

        for pnum, (net, _) in pins.items():
            if not net or ctx.is_power_net(net) or ctx.is_ground(net):
                continue
            if net in checked_nets:
                continue
            # A no-connect marker on the pin is the designer saying it is
            # unused on purpose (KiCad ERC honours it). Only trust the net
            # flag when the pin is alone on the net, as the pin-level
            # NO_CONNECT logic in analyze_schematic.py does.
            _net_info = ctx.nets.get(net, {})
            if _net_info.get('no_connect') and len(_net_info.get('pins', [])) <= 1:
                continue

            # Get pin name
            pin_name = ''
            for p in ic.get('pins', []):
                if p.get('number') == pnum:
                    pin_name = p.get('name', '')
                    break
            if not pin_name:
                # Try from net info
                for np in ctx.nets.get(net, {}).get('pins', []):
                    if np['component'] == ref and np['pin_number'] == pnum:
                        pin_name = np.get('pin_name', '')
                        break

            pin_upper = pin_name.upper().replace('-', '').replace('_', '')

            # Check if this pin needs a pull-up
            needs_pullup = False
            for pn in _PULLUP_PIN_NAMES:
                if pn.replace('-', '').replace('_', '') == pin_upper or pin_upper.endswith(pn.replace('-', '').replace('_', '')):
                    needs_pullup = True
                    break

            # Also check if IC is a known open-drain type
            if not needs_pullup and match_ic_keywords(ic, _OPEN_DRAIN_IC_KEYWORDS):
                # For OD ICs, check ALERT/INT/OUT pins
                if any(pin_upper.startswith(p) for p in ('INT', 'IRQ', 'ALERT', 'OUT', 'DRDY', 'DQ')):
                    needs_pullup = True

            needs_pulldown = False
            for pn in _PULLDOWN_PIN_NAMES:
                if pn.replace('-', '').replace('_', '') == pin_upper:
                    needs_pulldown = True
                    break

            if not needs_pullup and not needs_pulldown:
                continue

            checked_nets.add(net)

            if needs_pullup:
                # Datasheet path: if facts has recommended_pullup_range, use it.
                # Heuristic path: fall back to _PULLUP_MIN/MAX_OHMS. No extraction
                # schema field is named recommended_pullup_range today, so the
                # datasheet path only runs once a facts block provides one.
                ds_range = None
                if facts is not None:
                    _specs = getattr(
                        getattr(facts, 'base', None), 'recommended_pullup_range', None
                    )
                    if has_data(_specs):
                        ds_range = best(_specs, min_confidence='medium')

                if ds_range is not None:
                    pu_confidence = 'datasheet-backed'
                    pu_evidence = 'datasheet'
                    pu_min = ds_range.min if ds_range.min is not None else _PULLUP_MIN_OHMS
                    pu_max = ds_range.max if ds_range.max is not None else _PULLUP_MAX_OHMS
                else:
                    pu_confidence = 'heuristic'
                    pu_evidence = 'topology'
                    pu_min = _PULLUP_MIN_OHMS
                    pu_max = _PULLUP_MAX_OHMS

                pullups = _find_pullups_on_net(ctx, net, resistor_nets, net_to_resistors)
                if not pullups:
                    # Check if another driver exists (push-pull output driving it)
                    if _net_has_driver(ctx, net, ref):
                        continue  # Net is actively driven, pull-up not strictly required

                    # Skip regulators whose EN pin has an internal pull-up
                    # (TI/MPS/Microchip parts list).
                    if _has_internal_en_pullup(ic, pin_name):
                        continue

                    findings.append(make_finding(
                        detector='validate_pullups',
                        rule_id='PU-001',
                        category='signal_integrity',
                        summary=f'{ref} pin {pin_name} ({net}) missing pull-up resistor',
                        description=(
                            f'Pin {pin_name} on {ref} ({ic.get("value", "")}) is '
                            f'connected to net {net} but has no pull-up resistor. '
                            f'This pin type typically requires an external pull-up '
                            f'to a power rail for correct operation.'
                        ),
                        severity='warning',
                        confidence=pu_confidence,
                        evidence_source=pu_evidence,
                        components=[ref],
                        nets=[net],
                        pins=[{'ref': ref, 'pin': pin_name, 'function': 'open_drain_or_input'}],
                        recommendation=f'Add a 4.7k-10k pull-up resistor from {net} to the appropriate power rail.',
                        fix_params={
                            'type': 'add_component',
                            'components': [{'type': 'resistor', 'value': '10k',
                                            'net_from': net, 'net_to': '<power_rail>'}],
                            'basis': f'Pin {pin_name} is open-drain/input type requiring pull-up',
                        },
                        report_section='Signal Integrity',
                        impact='Pin may float or bus may not function without pull-up',
                        provenance=make_provenance('pu_missing_pullup', 'deterministic'),
                        schema_era='v1.4',
                        source=ctx.source,))
                else:
                    # Check pull-up value range
                    for pu in pullups:
                        if pu['ohms'] is not None:
                            if pu['ohms'] < pu_min:
                                findings.append(make_finding(
                                    detector='validate_pullups',
                                    rule_id='PU-001',
                                    category='signal_integrity',
                                    summary=f'{ref} pin {pin_name}: pull-up {pu["ref"]} value too low ({pu["ohms"]:.0f}R)',
                                    description=(
                                        f'Pull-up {pu["ref"]} on net {net} has value '
                                        f'{pu["ohms"]:.0f} ohms, which is below the typical '
                                        f'minimum of {pu_min} ohms. This draws '
                                        f'excessive current when the output is low.'
                                    ),
                                    severity='info',
                                    confidence=pu_confidence,
                                    evidence_source=pu_evidence,
                                    components=[ref, pu['ref']],
                                    nets=[net],
                                    recommendation=f'Consider increasing {pu["ref"]} to 4.7k-10k.',
                                    provenance=make_provenance('pu_value_check', 'deterministic'),
                                    schema_era='v1.4',
                                    source=ctx.source,))
                            elif pu['ohms'] > pu_max:
                                findings.append(make_finding(
                                    detector='validate_pullups',
                                    rule_id='PU-001',
                                    category='signal_integrity',
                                    summary=f'{ref} pin {pin_name}: pull-up {pu["ref"]} value too high ({pu["ohms"]/1000:.0f}k)',
                                    description=(
                                        f'Pull-up {pu["ref"]} on net {net} has value '
                                        f'{pu["ohms"]/1000:.0f}k ohms, which is above the typical '
                                        f'maximum of {pu_max/1000:.0f}k ohms. The signal '
                                        f'rise time may be too slow for reliable operation.'
                                    ),
                                    severity='info',
                                    confidence=pu_confidence,
                                    evidence_source=pu_evidence,
                                    components=[ref, pu['ref']],
                                    nets=[net],
                                    recommendation=f'Consider decreasing {pu["ref"]} to 4.7k-10k.',
                                    provenance=make_provenance('pu_weak_pullup', 'deterministic'),
                                    schema_era='v1.4',
                                    source=ctx.source,))

            if needs_pulldown:
                pulldowns = _find_pulldowns_on_net(ctx, net, resistor_nets, net_to_resistors)
                if not pulldowns:
                    findings.append(make_finding(
                        detector='validate_pullups',
                        rule_id='PU-001',
                        category='signal_integrity',
                        summary=f'{ref} pin {pin_name} ({net}) missing pull-down resistor',
                        description=(
                            f'Pin {pin_name} on {ref} ({ic.get("value", "")}) is '
                            f'connected to net {net} but has no pull-down resistor. '
                            f'This pin requires a defined logic level at startup.'
                        ),
                        severity='warning',
                        confidence='heuristic',
                        evidence_source='topology',
                        components=[ref],
                        nets=[net],
                        pins=[{'ref': ref, 'pin': pin_name, 'function': 'mode_select'}],
                        recommendation=f'Add a 10k pull-down resistor from {net} to GND.',
                        fix_params={
                            'type': 'add_component',
                            'components': [{'type': 'resistor', 'value': '10k',
                                            'net_from': net, 'net_to': 'GND'}],
                            'basis': f'Pin {pin_name} is a mode/boot selection pin',
                        },
                        report_section='Signal Integrity',
                        impact='Pin floats at startup, undefined behavior',
                        provenance=make_provenance('pu_missing_pullup', 'deterministic'),
                        schema_era='v1.4',
                        source=ctx.source,))

    return findings


# ---------------------------------------------------------------------------
# VM-001: Cross-domain voltage mismatch
# ---------------------------------------------------------------------------

_VOLTAGE_THRESHOLDS = {
    1.8: (0.4, 1.35, 0.63, 1.17, 2.0),
    2.5: (0.4, 2.0, 0.7, 1.7, 2.75),
    3.3: (0.4, 2.4, 0.8, 2.0, 3.6),
    5.0: (0.5, 4.4, 1.5, 3.5, 5.5),
}


def _estimate_rail_voltage_for_ic(ctx: AnalysisContext, ref: str) -> float | None:
    """Estimate IC supply rail voltage. Regulators use VIN pin; others use first power net.

    Returns the magnitude so a +/- supplied IC does not read as a different
    domain depending on pin order.
    """
    return _ic_rail_voltage(ctx, ref)[0]


def _ic_rail_voltage(ctx: AnalysisContext, ref: str) -> tuple[float | None, bool]:
    """``_estimate_rail_voltage_for_ic`` and whether the voltage is a config override."""
    def pin_voltage(net):
        return ctx.rail_voltage_or(net, parse_voltage_from_net_name)

    # A rail known only by its pins is often a core or PLL supply; the first one by pin
    # order is not the IC's I/O level.
    pins = {num: entry for num, entry in ctx.ref_pins.get(ref, {}).items()
            if entry[0] not in ctx.topology_rails}
    # A supply on an ignored rail has an unknown voltage; the IC's other supply does not
    # stand in for it.
    if any(net and ctx.is_power_net(net) and not ctx.is_ground(net) and ctx.rail_ignored(net)
           for net, _ in pins.values()):
        return None, False

    comp = ctx.comp_lookup.get(ref, {})
    mpn = comp.get('mpn') or comp.get('value', '')
    feat = get_regulator_features(mpn, project_dir=ctx.project_dir) if mpn else None
    if feat and not feat.get('quality', {}).get('trusted', True):
        feat = None   # deterministic detectors ignore untrusted extractions
    if feat and feat.get('vin_pin'):
        vin_pin = str(feat['vin_pin'])
        for pnum, (net, _) in pins.items():
            if str(pnum) == vin_pin and net and ctx.is_power_net(net) and not ctx.is_ground(net):
                v = pin_voltage(net)
                if v is not None:
                    return abs(v), ctx.config_rail_voltage(net) is not None

    # The positive supply sets a split-supply IC's logic swing; a negative rail counts
    # only for an IC that has no positive one.
    negative = None
    for pnum, (net, _) in pins.items():
        if net and ctx.is_power_net(net) and not ctx.is_ground(net):
            v = pin_voltage(net)
            if v is not None and v > 0:
                return v, ctx.config_rail_voltage(net) is not None
            if v is not None and negative is None:
                negative = (abs(v), ctx.config_rail_voltage(net) is not None)
    return negative if negative is not None else (None, False)


def _closest_threshold(voltage: float) -> tuple:
    if voltage is None:
        return None
    best = None
    best_dist = float('inf')
    for v, thresh in _VOLTAGE_THRESHOLDS.items():
        dist = abs(v - voltage)
        if dist < best_dist:
            best_dist = dist
            best = thresh
    return best


# Upper-cased pin names of a regulator's enable input and of its open-drain power-good output
# (the pull-up, not the regulator's supply, sets the power-good level).
_EN_PIN_PATTERNS = ('EN', 'ENABLE', 'CE', 'SHDN', 'NSHDN', 'ON', 'ON_OFF', 'RUN')
_PG_PIN_PATTERNS = ('PG', 'PGOOD', 'PWRGD', 'NPG')
# Load-switch families whose symbols often carry no description (Vishay SiP32xxx, TI TPS205x,
# Diodes AP2280x / AP2261x / AP2265x / AP255x, Microchip MIC20xx, onsemi FPFxxxx).
_LOAD_SWITCH_FAMILIES = ('sip32', 'tps205', 'ap2280', 'ap2261', 'ap2265', 'ap255', 'mic20', 'fpf')


def _is_regulator_like(ctx: AnalysisContext, ref: str) -> bool:
    """A regulator-family part by its value or MPN, or typed power_regulator. A load switch
    counts too (by family or by its text): its enable is a logic input rated independently
    of its VIN."""
    comp = ctx.comp_lookup.get(ref, {})
    val_mpn = ((comp.get('mpn') or '') + ' ' + (comp.get('value') or '')).upper()
    if comp.get('type') == 'power_regulator' or any(pfx in val_mpn for pfx in (
            'TPS6', 'TPS5', 'LM25', 'LM33', 'LM317', 'AP21', 'AMS11',
            'MP23', 'MP15', 'XL40', 'RT8', 'SY8', 'MIC29', 'NCP',
            'LDO', 'BOOST', 'BUCK', 'REG')):
        return True
    text = (val_mpn + ' ' + (comp.get('lib_id') or '')).lower()
    return (any(k in text for k in LOAD_SWITCH_KEYWORDS + _LOAD_SWITCH_FAMILIES)
            or names_load_switch(text + ' ' + (comp.get('description') or '')))


def _en_endpoint_compatible(ctx: AnalysisContext, p: dict, net_name: str, v_min: float) -> bool:
    """True when pin *p* on *net_name* is a regulator enable input that tolerates a net
    whose lowest domain is *v_min*: by the datasheet EN threshold when one is extracted,
    else by an EN-named pin on a regulator-family part."""
    comp = ctx.comp_lookup.get(p['ref'], {})
    p_mpn = comp.get('mpn') or comp.get('value', '')
    ds_feat = get_regulator_features(p_mpn, project_dir=ctx.project_dir) if p_mpn else None
    if ds_feat and not ds_feat.get('quality', {}).get('trusted', True):
        ds_feat = None   # deterministic detectors ignore untrusted extractions
    if ds_feat and ds_feat.get('en_pin'):
        for pnum, (net, _) in ctx.ref_pins.get(p['ref'], {}).items():
            if net == net_name and str(pnum) == str(ds_feat['en_pin']):
                en_ih = ds_feat.get('en_v_ih_max')
                if en_ih is not None:
                    return v_min >= 2 * en_ih
                break
    if _is_regulator_like(ctx, p['ref']):
        name = (p.get('pin') or '').upper().strip()
        return name in _EN_PIN_PATTERNS
    return False


# Data-pair prefixes seen on USB and Ethernet pairs (LsD+, TD+, RD+, UD+, U1D+, XUD+, DBGD+);
# a word that merely ends in D (HOLD, MOD, AVDD, SDD) is not one.
_DATA_PAIR_NAME = re.compile(r"(?:^|[^A-Z0-9])(?:LS|[TRQIDU]|U\d|XU|IU|UC|DBG)?D[+-]$")


def _is_usb_dp_dm(net_name: str, nets) -> bool:
    name = net_name.upper()
    if is_usb_data_net_name(name):
        return not is_usb_signal_net_name(name)
    # A D+ / D- pair under another name (LsD+ / LsD-, TD+ / TD-) is differential data too;
    # a lone HOLD- or SPEED- is a logic signal.
    if _DATA_PAIR_NAME.search(name):
        return (net_name[:-1] + ("-" if net_name.endswith("+") else "+")) in nets
    return False


# Charger status outputs are open-drain by convention (STAT, CHG, CHRG); a power-good pin
# is when the part is a regulator.
_OD_STATUS_NAMES = frozenset({'STAT', 'STAT1', 'STAT2', 'CHG', 'CHRG'})


def _bare_pin_name(name: str) -> str:
    """Upper-cased pin name without an active-low marker (~{PG}, nPG, NSTAT)."""
    n = re.sub(r'^~\{(.*)\}$', r'\1', (name or '').upper().strip()).lstrip('~/')
    if n.startswith('N') and (n[1:] in _OD_STATUS_NAMES or n[1:] in _PG_PIN_PATTERNS):
        return n[1:]
    return n


def _is_open_drain_endpoint(ctx: AnalysisContext, p: dict) -> bool:
    """An open-collector / open-drain output: by pin type, a charger status pin by name,
    or a power-good pin on a regulator."""
    if p.get('pin_type') == 'open_collector':
        return True
    if p.get('pin_type') == 'tri_state':
        return False   # MCP73831 STAT drives high to its supply
    name = _bare_pin_name(p.get('pin'))
    if name in _OD_STATUS_NAMES:
        return True
    return name in _PG_PIN_PATTERNS and _is_regulator_like(ctx, p['ref'])


def _pull_up_voltage(ctx: AnalysisContext, net_name: str) -> float | None:
    """The highest rail a resistor on *net_name* ties it to, or None."""
    best = None
    for q in ctx.nets.get(net_name, {}).get('pins', []):
        comp = ctx.comp_lookup.get(q['component'], {})
        if comp.get('type') != 'resistor':
            continue
        n1, n2 = ctx.get_two_pin_nets(q['component'])
        other = n2 if n1 == net_name else n1
        if not other or other == net_name or not ctx.is_power_net(other) or ctx.is_ground(other):
            continue
        v = ctx.rail_voltage_or(other, parse_voltage_from_net_name)
        if v is not None and v > 0 and (best is None or v > best):
            best = v
    return best


def validate_voltage_levels(ctx: AnalysisContext, level_shifters: list[dict] | None = None) -> list[dict]:
    """VM-001: Detect signal nets crossing power domain boundaries without level shifting."""
    findings: list[dict] = []
    cache_dir = getattr(ctx, 'cache_dir', None)

    ic_voltages: dict[str, float] = {}
    config_voltage_ics: set[str] = set()
    for ic in get_unique_ics(ctx):
        v = _estimate_rail_voltage_for_ic(ctx, ic['reference'])
        if v is not None:
            ic_voltages[ic['reference']] = v
            if ctx.rail_overrides and _ic_rail_voltage(ctx, ic['reference'])[1]:
                config_voltage_ics.add(ic['reference'])
            # Lookup probe (informational; the rail estimate is not yet checked
            # against facts.base.recommended_operating.VDD).
            mpn = ic.get('mpn') or ic.get('value') or ''
            facts = get_facts(mpn, cache_dir=cache_dir, diagnostics=getattr(ctx, "diagnostics", None)) if mpn else None
            # facts probe is informational — confidence stays heuristic regardless.

    shifted_nets: set[str] = set()
    if level_shifters:
        for ls in level_shifters:
            for net in ls.get('shifted_nets', []):
                shifted_nets.add(net)
            ref = ls.get('reference', ls.get('ref', ''))
            for pnum, (net, _) in ctx.ref_pins.get(ref, {}).items():
                if net and not ctx.is_power_net(net) and not ctx.is_ground(net):
                    shifted_nets.add(net)

    checked_nets: set[str] = set()

    for net_name, net_info in ctx.nets.items():
        if net_name in checked_nets or ctx.is_power_net(net_name) or ctx.is_ground(net_name):
            continue
        if net_name in shifted_nets:
            continue
        # USB D+/D- swing at most 3.6 V whatever the device supply (USB 2.0, 7.1.1 drivers).
        if _is_usb_dp_dm(net_name, ctx.nets):
            continue

        ic_pins_on_net = []
        for p in net_info.get('pins', []):
            ref = p['component']
            if ref in ic_voltages:
                # A supply pin on a non-power net is a rail feeding a regulator or a
                # regulator output (L7809 OUT -> L7805 IN), not a logic level.
                if p.get('pin_type') in ('power_in', 'power_out'):
                    continue
                ic_pins_on_net.append({
                    'ref': ref, 'pin': p.get('pin_name', ''),
                    'pin_number': p['pin_number'], 'voltage': ic_voltages[ref],
                    'pin_type': p.get('pin_type'),
                })
        # An open-drain output swings to its pull-up, not to its IC's supply; with no
        # pull-up on the net it drives nothing high.
        od = [q for q in ic_pins_on_net if _is_open_drain_endpoint(ctx, q)]
        if od and len(ic_pins_on_net) >= 2:
            v_pu = _pull_up_voltage(ctx, net_name)
            for q in od:
                if v_pu is None:
                    ic_pins_on_net.remove(q)
                else:
                    q['voltage'] = v_pu

        # One part's own pins are not a domain crossing (MC34063 switch collectors tied to
        # its current-sense input).
        if len({p['ref'] for p in ic_pins_on_net}) < 2:
            continue

        voltages = set(p['voltage'] for p in ic_pins_on_net)
        if len(voltages) <= 1:
            continue

        checked_nets.add(net_name)
        v_max = max(voltages)
        v_min = min(voltages)

        # A regulator EN input that tolerates the drive is one compatible endpoint; the
        # other endpoints on the net are still checked against each other.
        en_ok = [p for p in ic_pins_on_net if _en_endpoint_compatible(ctx, p, net_name, v_min)]
        if en_ok:
            ic_pins_on_net = [p for p in ic_pins_on_net if p not in en_ok]
            voltages = set(p['voltage'] for p in ic_pins_on_net)
            if len({p['ref'] for p in ic_pins_on_net}) < 2 or len(voltages) <= 1:
                continue
            v_max = max(voltages)
            v_min = min(voltages)

        # An open-drain output only pulls the net low: it is never the input that a
        # higher domain overdrives.
        readers = [p['voltage'] for p in ic_pins_on_net if p not in od]
        if not readers or min(readers) >= v_max:
            continue
        v_min = min(readers)

        low_thresh = _closest_threshold(v_min)
        if low_thresh is None:
            continue

        abs_max = low_thresh[4]
        if v_max > abs_max:
            severity = 'error'
            desc = (
                f'Net {net_name} connects ICs in {v_max}V and {v_min}V domains. '
                f'The {v_max}V output may exceed the {v_min}V input absolute maximum '
                f'rating of {abs_max}V, risking damage.'
            )
        else:
            high_thresh = _closest_threshold(v_max)
            voh = high_thresh[1] if high_thresh else v_max * 0.7
            vih = low_thresh[3]
            if voh < vih:
                severity = 'warning'
                desc = (
                    f'Net {net_name} connects ICs in {v_max}V and {v_min}V domains. '
                    f'The {v_max}V output VOH ({voh}V) may not meet the {v_min}V '
                    f'input VIH threshold ({vih}V).'
                )
            else:
                continue

        refs = sorted(set(p['ref'] for p in ic_pins_on_net))
        config_extra = ({'rail_voltage_source': 'config'}
                        if config_voltage_ics.intersection(refs) else {})
        findings.append(make_finding(
            detector='validate_voltage_levels',
            rule_id='VM-001',
            category='signal_integrity',
            summary=f'Net {net_name}: {v_max}V / {v_min}V domain crossing without level shifter',
            description=desc,
            severity=severity,
            confidence='heuristic',
            evidence_source='topology',
            components=refs,
            nets=[net_name],
            pins=[{'ref': p['ref'], 'pin': p['pin'], 'function': 'signal_io'}
                  for p in ic_pins_on_net],
            recommendation=(
                f'Add a level shifter between the {v_max}V and {v_min}V domains on net {net_name}, '
                f'or verify that the connected ICs have tolerant inputs.'
            ),
            fix_params={
                'type': 'add_component',
                'components': [{'type': 'level_shifter',
                                'domain_a': f'{v_max}V', 'domain_b': f'{v_min}V',
                                'nets': [net_name]}],
                'basis': f'Net crosses {v_max}V to {v_min}V boundary',
            },
            report_section='Signal Integrity',
            impact='Risk of damage or unreliable logic levels',
            provenance=make_provenance('vm_rail_mismatch', 'heuristic'),
            schema_era='v1.4',
            source=ctx.source,
            **config_extra))

    return findings


# ---------------------------------------------------------------------------
# PR-001..004: Protocol pin validation
# ---------------------------------------------------------------------------

_I2C_IC_KEYWORDS = (
    'pca9', 'tca9', 'pcf8574', 'pcf8575', 'mcp23', 'at24', 'eeprom',
    'ina219', 'ina226', 'ina228', 'ina260', 'ina3221',
    'tmp1', 'tmp4', 'lm75', 'sht3', 'sht4', 'bme280', 'bme680', 'bmp280',
    'mpu6050', 'mpu9250', 'icm20', 'lsm6', 'lis3', 'adxl3',
    'ads1015', 'ads1115', 'mcp4725', 'dac8', 'max517',
    'ds1307', 'ds3231', 'pcf8523', 'rv3028', 'rv8803',
    'si5351', 'pll', 'cdce',
    'tca6408', 'sx1509', 'pca6416',
    'as5600', 'as5048', 'vl53l',
    'is31fl', 'lp5024', 'pca9685',
    'stusb', 'fusb302', 'bq2597',
)
_I2C_SDA_NAMES = ('SDA', 'I2C_SDA', 'TWI_SDA', 'SDAI', 'SDA1', 'SDA2', 'SDATA')
_I2C_SCL_NAMES = ('SCL', 'I2C_SCL', 'TWI_SCL', 'SCLI', 'SCL1', 'SCL2', 'SCLK')
_I2C_PULLUP_RANGES = {
    'standard': (1000, 10000),
    'fast': (1000, 4700),
    'fast_plus': (470, 2200),
}

_SPI_IC_KEYWORDS = (
    'w25q', 'mx25', 'at25', 'sst26', 'is25', 'gd25',
    'mcp3', 'ads8', 'ad7', 'max11',
    'mcp49', 'dac8',
    'sx127', 'rfm9', 'cc1101', 'nrf24', 'si446',
    'enc28j', 'w5500', 'ksz8',
    'max7219', 'apa102', 'dotstar',
    'sd_card', 'sdcard',
    'lis3', 'adxl3', 'bmi160', 'icm42',
)
_SPI_CS_NAMES = ('CS', 'SS', 'NSS', 'SPI_CS', 'SPI_SS', 'CSN', 'NCS', 'CE0', 'CE1')

_CAN_IC_KEYWORDS = (
    'mcp2515', 'mcp2551', 'mcp2562', 'mcp25625',
    'sn65hvd', 'sn65hvd230', 'sn65hvd231', 'sn65hvd232',
    'tja1', 'tja1050', 'tja1051', 'tja1040', 'tja1042', 'tja1043',
    'iso1050', 'iso1042',
    'max3', 'max33',
    'adm3053',
)
_CAN_H_NAMES = ('CANH', 'CAN_H', 'CANHI', 'CAN_HIGH')
_CAN_L_NAMES = ('CANL', 'CAN_L', 'CANLO', 'CAN_LOW')

_USB_DP_NAMES = ('D+', 'DP', 'USB_DP', 'USB_D+', 'USBDP', 'D_P')
_USB_DM_NAMES = ('D-', 'DM', 'USB_DM', 'USB_D-', 'USBDM', 'D_N')


def validate_i2c_bus(ctx: AnalysisContext) -> list[dict]:
    """PR-001: Validate I2C bus integrity — pull-ups, values, address conflicts."""
    findings: list[dict] = []
    resistors = get_components_by_type(ctx, 'resistor')
    resistor_nets, net_to_resistors = index_two_pin_components(ctx, resistors)

    i2c_buses: dict[str, dict] = {}
    for ic in get_unique_ics(ctx):
        ref = ic['reference']
        if not match_ic_keywords(ic, _I2C_IC_KEYWORDS):
            continue
        sda_net = get_pin_net(ctx, ref, _I2C_SDA_NAMES)
        scl_net = get_pin_net(ctx, ref, _I2C_SCL_NAMES)
        if not sda_net or not scl_net:
            continue
        bus_key = f'{sda_net}:{scl_net}'
        bus = i2c_buses.setdefault(bus_key, {'sda_net': sda_net, 'scl_net': scl_net, 'devices': []})
        bus['devices'].append(ref)

    for bus_key, bus in i2c_buses.items():
        sda, scl = bus['sda_net'], bus['scl_net']
        refs = bus['devices']

        sda_pullups = _find_pullups_on_net_with_bridged(ctx, sda, resistor_nets, net_to_resistors)
        if not sda_pullups:
            findings.append(make_finding(
                detector='validate_i2c_bus', rule_id='PR-001', category='protocol_integrity',
                summary=f'I2C bus {sda}/{scl}: SDA missing pull-up',
                description=f'I2C bus with {len(refs)} device(s) ({", ".join(refs)}) has no pull-up on SDA net {sda}.',
                severity='error', confidence='deterministic', evidence_source='topology',
                components=refs, nets=[sda, scl],
                recommendation='Add a 4.7k pull-up resistor from SDA to VDD.',
                fix_params={'type': 'add_component', 'components': [{'type': 'resistor', 'value': '4.7k', 'net_from': sda, 'net_to': '<VDD>'}], 'basis': 'I2C spec requires pull-ups on SDA'},
                standard_ref='I2C specification UM10204 section 3.1.1', impact='I2C bus non-functional',
                provenance=make_provenance('pr_i2c_spec', 'deterministic'),
            
                source=ctx.source, schema_era="v3.0",))

        scl_pullups = _find_pullups_on_net_with_bridged(ctx, scl, resistor_nets, net_to_resistors)
        if not scl_pullups:
            findings.append(make_finding(
                detector='validate_i2c_bus', rule_id='PR-001', category='protocol_integrity',
                summary=f'I2C bus {sda}/{scl}: SCL missing pull-up',
                description=f'I2C bus with {len(refs)} device(s) ({", ".join(refs)}) has no pull-up on SCL net {scl}.',
                severity='error', confidence='deterministic', evidence_source='topology',
                components=refs, nets=[sda, scl],
                recommendation='Add a 4.7k pull-up resistor from SCL to VDD.',
                fix_params={'type': 'add_component', 'components': [{'type': 'resistor', 'value': '4.7k', 'net_from': scl, 'net_to': '<VDD>'}], 'basis': 'I2C spec requires pull-ups on SCL'},
                standard_ref='I2C specification UM10204 section 3.1.1', impact='I2C bus non-functional',
                provenance=make_provenance('pr_i2c_spec', 'deterministic'),
            
                source=ctx.source, schema_era="v3.0",))

        for net_label, pullups in [('SDA', sda_pullups), ('SCL', scl_pullups)]:
            for pu in pullups:
                if pu['ohms'] is not None:
                    low, high = _I2C_PULLUP_RANGES['standard']
                    if pu['ohms'] < low or pu['ohms'] > high:
                        findings.append(make_finding(
                            detector='validate_i2c_bus', rule_id='PR-001', category='protocol_integrity',
                            summary=f'I2C {net_label} pull-up {pu["ref"]} out of range ({pu["ohms"]:.0f}R)',
                            description=f'I2C {net_label} pull-up {pu["ref"]} is {pu["ohms"]:.0f} ohms. Recommended: {low}-{high} ohms for standard-mode.',
                            severity='info', confidence='heuristic', evidence_source='topology',
                            components=[pu['ref']], nets=[bus['sda_net'] if net_label == 'SDA' else bus['scl_net']],
                            recommendation=f'Use a pull-up in the {low}-{high} ohm range.',
                            fix_params={'type': 'resistor_value_change', 'component': pu['ref'], 'current_value': pu['ohms'], 'target_range': [low, high], 'suggested_value': 4700},
                            standard_ref='I2C specification UM10204 Table 10',
                            provenance=make_provenance('pr_i2c_spec', 'deterministic'),
                        
                            source=ctx.source, schema_era="v3.0",))

        # Address conflict: flag multiple same-IC-type on same bus
        if len(refs) >= 2:
            value_counts: dict[str, list[str]] = {}
            for ref in refs:
                comp = ctx.comp_lookup.get(ref)
                if comp:
                    val = comp.get('value', '').lower()
                    value_counts.setdefault(val, []).append(ref)
            for val, refs_with_val in value_counts.items():
                if len(refs_with_val) > 1:
                    findings.append(make_finding(
                        detector='validate_i2c_bus', rule_id='PR-001', category='protocol_integrity',
                        summary=f'I2C bus: possible address conflict — {len(refs_with_val)}x {val}',
                        description=f'Multiple {val} ({", ".join(refs_with_val)}) on same I2C bus. Verify address pins differ.',
                        severity='warning', confidence='heuristic', evidence_source='topology',
                        components=refs_with_val, nets=[bus['sda_net'], bus['scl_net']],
                        recommendation='Verify address pin configurations (A0/A1/A2) differ.',
                        impact='Address conflict causes bus corruption',
                        provenance=make_provenance('pr_i2c_spec', 'deterministic'),
                    
                        source=ctx.source, schema_era="v3.0",))

    return findings


def validate_spi_bus(ctx: AnalysisContext) -> list[dict]:
    """PR-002: Validate SPI bus — CS pull-ups."""
    findings: list[dict] = []
    resistors = get_components_by_type(ctx, 'resistor')
    resistor_nets, net_to_resistors = index_two_pin_components(ctx, resistors)

    for ic in get_unique_ics(ctx):
        ref = ic['reference']
        if not match_ic_keywords(ic, _SPI_IC_KEYWORDS):
            continue
        cs_net = get_pin_net(ctx, ref, _SPI_CS_NAMES)
        if cs_net and not ctx.is_power_net(cs_net) and not ctx.is_ground(cs_net):
            pullups = _find_pullups_on_net(ctx, cs_net, resistor_nets, net_to_resistors)
            if not pullups:
                findings.append(make_finding(
                    detector='validate_spi_bus', rule_id='PR-002', category='protocol_integrity',
                    summary=f'SPI device {ref}: CS pin ({cs_net}) missing pull-up',
                    description=f'SPI CS on {ref} ({ic.get("value", "")}) net {cs_net} has no pull-up. Device may be inadvertently selected during reset.',
                    severity='warning', confidence='heuristic', evidence_source='topology',
                    components=[ref], nets=[cs_net],
                    recommendation=f'Add a 10k pull-up on {cs_net}.',
                    fix_params={'type': 'add_component', 'components': [{'type': 'resistor', 'value': '10k', 'net_from': cs_net, 'net_to': '<VDD>'}], 'basis': 'SPI CS should be pulled high when not driven'},
                    impact='Device may be selected during reset causing bus contention',
                    provenance=make_provenance('pr_spi_spec', 'deterministic'),
                
                    source=ctx.source, schema_era="v3.0",))
    return findings


def validate_can_bus(ctx: AnalysisContext) -> list[dict]:
    """PR-003: Validate CAN bus — termination resistors."""
    findings: list[dict] = []
    resistors = get_components_by_type(ctx, 'resistor')
    resistor_nets, net_to_resistors = index_two_pin_components(ctx, resistors)

    can_transceivers = []
    for ic in get_unique_ics(ctx):
        if match_ic_keywords(ic, _CAN_IC_KEYWORDS):
            ref = ic['reference']
            canh = get_pin_net(ctx, ref, _CAN_H_NAMES)
            canl = get_pin_net(ctx, ref, _CAN_L_NAMES)
            if canh or canl:
                can_transceivers.append({'ref': ref, 'value': ic.get('value', ''), 'canh': canh, 'canl': canl})

    for xcvr in can_transceivers:
        canh, canl = xcvr['canh'], xcvr['canl']
        if not canh or not canl:
            continue
        term_found = False
        for rref in net_to_resistors.get(canh, []):
            n1, n2 = resistor_nets.get(rref, (None, None))
            if not n1 or not n2:
                continue
            other = n2 if n1 == canh else n1
            if other == canl:
                ohms = ctx.parsed_values.get(rref)
                if ohms is not None and 100 <= ohms <= 150:
                    term_found = True
                    break
        if not term_found:
            findings.append(make_finding(
                detector='validate_can_bus', rule_id='PR-003', category='protocol_integrity',
                summary=f'CAN transceiver {xcvr["ref"]}: no 120R termination',
                description=f'CAN transceiver {xcvr["ref"]} ({xcvr["value"]}) has no 120R termination between CANH ({canh}) and CANL ({canl}).',
                severity='warning', confidence='deterministic', evidence_source='topology',
                components=[xcvr['ref']], nets=[n for n in [canh, canl] if n],
                recommendation=f'Add a 120R resistor between {canh} and {canl} if at bus end.',
                fix_params={'type': 'add_component', 'components': [{'type': 'resistor', 'value': '120', 'net_from': canh, 'net_to': canl}], 'basis': 'ISO 11898 requires 120R termination'},
                standard_ref='ISO 11898-2 section 7.3', impact='Bus reflections cause communication errors',
                provenance=make_provenance('pr_can_spec', 'deterministic'),
            
                source=ctx.source, schema_era="v3.0",))
    return findings


def validate_usb_bus(ctx: AnalysisContext) -> list[dict]:
    """PR-004: Validate USB data lines — series resistors."""
    findings: list[dict] = []
    resistors = get_components_by_type(ctx, 'resistor')
    resistor_nets, net_to_resistors = index_two_pin_components(ctx, resistors)

    for comp in ctx.components:
        if comp['type'] != 'connector':
            continue
        val_lib = (comp.get('value', '') + ' ' + comp.get('lib_id', '')).lower()
        if 'usb' not in val_lib:
            continue
        ref = comp['reference']
        dp_net = get_pin_net(ctx, ref, _USB_DP_NAMES)
        dm_net = get_pin_net(ctx, ref, _USB_DM_NAMES)
        if not dp_net and not dm_net:
            continue

        for net_label, net in [('D+', dp_net), ('D-', dm_net)]:
            if not net:
                continue
            series_r = [rref for rref in net_to_resistors.get(net, [])
                        if ctx.parsed_values.get(rref) is not None and 15 <= ctx.parsed_values[rref] <= 33]
            # Check if MCU endpoint has native USB PHY
            mcu_on_net = None
            for p in ctx.nets.get(net, {}).get('pins', []):
                c = ctx.comp_lookup.get(p['component'], {})
                if c.get('type') not in ('connector',) and match_ic_keywords(c, ('esp32', 'stm32', 'rp2040', 'rp2350', 'nrf52', 'samd', 'lpc', 'atm')):
                    mcu_mpn = c.get('mpn') or c.get('value', '')
                    mcu_feat = get_mcu_features(mcu_mpn, project_dir=ctx.project_dir) if mcu_mpn else None
                    if mcu_feat and not mcu_feat.get('quality', {}).get('trusted', True):
                        mcu_feat = None   # deterministic detectors ignore untrusted extractions
                    if mcu_feat and mcu_feat.get('has_native_usb_phy') is True and mcu_feat.get('usb_series_r_required') is False:
                        mcu_on_net = p['component']
                        break
            if mcu_on_net:
                continue
            if not series_r and 'usb_c' not in val_lib and 'usb3' not in val_lib:
                findings.append(make_finding(
                    detector='validate_usb_bus', rule_id='PR-004', category='protocol_integrity',
                    summary=f'USB connector {ref}: {net_label} ({net}) missing series resistor',
                    description=f'USB {net_label} on {ref} has no series resistor (typically 22R for USB 2.0).',
                    severity='info', confidence='heuristic', evidence_source='topology',
                    components=[ref], nets=[net],
                    recommendation=f'Add a 22R series resistor on {net_label} near the connector.',
                    fix_params={'type': 'add_component', 'components': [{'type': 'resistor', 'value': '22', 'net_from': net, 'net_to': f'{net}_MCU'}], 'basis': 'USB 2.0 recommends 22R series termination'},
                    standard_ref='USB 2.0 specification section 7.1.2',
                    provenance=make_provenance('pr_uart_spec', 'deterministic'),
                
                    source=ctx.source, schema_era="v3.0",))
    return findings


# ---------------------------------------------------------------------------
# PS-001: Power sequencing dependency graph
# ---------------------------------------------------------------------------

_ENABLE_PIN_NAMES = ('EN', 'ENABLE', 'CE', 'SHDN', 'ON', 'nSHDN', 'ON_OFF', 'RUN')
# PS-001's power-good names; domain_detectors._PG_PIN_NAMES is a deliberately
# different (wider) set for power-sequencing detection.
_PS_PG_PIN_NAMES = ('PG', 'PGOOD', 'POWER_GOOD', 'nPG', 'PGD', 'POK')

_SEQUENCING_SENSITIVE_KEYWORDS = (
    'stm32', 'esp32', 'nrf52', 'rp2040', 'samd', 'sam3', 'sam4',
    'zynq', 'artix', 'spartan', 'kintex', 'ecp5', 'ice40',
    'ddr', 'lpddr', 'sdram',
    'phy', 'dp83', 'ksz8', 'lan87', 'rtl8',
)


def validate_power_sequencing(
    ctx: AnalysisContext,
    power_regulators: list[dict],
) -> list[dict]:
    """PS-001: Build enable-pin dependency graph and check for sequencing issues."""
    findings: list[dict] = []
    if not power_regulators:
        return findings

    reg_by_output: dict[str, dict] = {}
    reg_by_ref: dict[str, dict] = {}
    for reg in power_regulators:
        ref = reg.get('ref', reg.get('reference', ''))
        output = reg.get('output_rail', '')
        if ref and output:
            reg_by_output[output] = reg
            reg_by_ref[ref] = reg

    enable_edges: list[tuple[str, str]] = []
    for reg in power_regulators:
        ref = reg.get('ref', reg.get('reference', ''))
        en_net = get_pin_net(ctx, ref, _ENABLE_PIN_NAMES)
        if not en_net:
            continue
        if en_net in reg_by_output:
            enabler = reg_by_output[en_net]
            enabler_ref = enabler.get('ref', enabler.get('reference', ''))
            enable_edges.append((enabler_ref, ref))

    adj: dict[str, list[str]] = {}
    for src, dst in enable_edges:
        adj.setdefault(src, []).append(dst)

    def _has_cycle(start: str) -> list[str] | None:
        visited: set[str] = set()
        path: list[str] = []
        def dfs(node: str) -> list[str] | None:
            if node in visited:
                idx = path.index(node) if node in path else -1
                if idx >= 0:
                    return path[idx:] + [node]
                return None
            visited.add(node)
            path.append(node)
            for nxt in adj.get(node, []):
                cycle = dfs(nxt)
                if cycle:
                    return cycle
            path.pop()
            return None
        return dfs(start)

    reported_cycles: set[str] = set()
    for start in adj:
        cycle = _has_cycle(start)
        if cycle:
            cycle_key = '->'.join(sorted(set(cycle)))
            if cycle_key not in reported_cycles:
                reported_cycles.add(cycle_key)
                findings.append(make_finding(
                    detector='validate_power_sequencing', rule_id='PS-001', category='power_integrity',
                    summary=f'Circular enable dependency: {" -> ".join(cycle)}',
                    description=f'Power regulator enable chain forms a cycle: {" -> ".join(cycle)}. No regulator in the cycle can start.',
                    severity='error', confidence='deterministic', evidence_source='topology',
                    components=sorted(set(cycle)),
                    recommendation='Break the cycle by connecting one enable pin to an always-on rail.',
                    impact='System fails to power on', report_section='Power Integrity',
                    provenance=make_provenance('ps_sequence_check', 'heuristic'),
                
                    source=ctx.source, schema_era="v3.0",))

    for reg in power_regulators:
        ref = reg.get('ref', reg.get('reference', ''))
        output_rail = reg.get('output_rail', '')
        if not output_rail:
            continue
        sensitive_loads = []
        for net_name, net_info in ctx.nets.items():
            if net_name != output_rail:
                continue
            for p in net_info.get('pins', []):
                comp = ctx.comp_lookup.get(p['component'])
                if comp and match_ic_keywords(comp, _SEQUENCING_SENSITIVE_KEYWORDS):
                    sensitive_loads.append(p['component'])
        if not sensitive_loads:
            continue
        comp = ctx.comp_lookup.get(ref, {})
        mpn = comp.get('mpn') or comp.get('value', '')
        ds_feat = get_regulator_features(mpn, project_dir=ctx.project_dir) if mpn else None
        if ds_feat and not ds_feat.get('quality', {}).get('trusted', True):
            ds_feat = None   # deterministic detectors ignore untrusted extractions
        if ds_feat and ds_feat.get('has_pg') is False:
            continue
        pg_net = get_pin_net(ctx, ref, _PS_PG_PIN_NAMES)
        if not pg_net:
            if ds_feat is None and mpn:
                findings.append(make_finding(
                    detector='validate_power_sequencing', rule_id='PS-001', category='power_integrity',
                    summary=f'Regulator {ref}: PG status unknown for {mpn} (no datasheet extraction)',
                    description=f'Regulator {ref} ({mpn}) supplies {output_rail} to {", ".join(sensitive_loads[:3])} but PG status is unknown. Run sync_datasheets to verify.',
                    severity='info', confidence='heuristic', evidence_source='topology',
                    components=[ref] + sensitive_loads[:3], nets=[output_rail],
                    recommendation=f'Run sync_datasheets to verify whether {mpn} has a PG pin.',
                    report_section='Power Integrity', impact='Downstream devices may latch up or boot incorrectly',
                    provenance=make_provenance('ps_sequence_check', 'heuristic'),
                
                    source=ctx.source, schema_era="v3.0",))
                continue
            findings.append(make_finding(
                detector='validate_power_sequencing', rule_id='PS-001', category='power_integrity',
                summary=f'Regulator {ref}: no power-good feedback, feeds {", ".join(sensitive_loads[:3])}',
                description=f'Regulator {ref} supplies {output_rail} to sequencing-sensitive device(s) ({", ".join(sensitive_loads[:3])}) but has no PG output connected.',
                severity='warning', confidence='heuristic', evidence_source='topology',
                components=[ref] + sensitive_loads[:3], nets=[output_rail],
                recommendation=f'Connect {ref} PG output to downstream regulator enable pins.',
                report_section='Power Integrity', impact='Downstream devices may latch up or boot incorrectly',
                provenance=make_provenance('ps_sequence_check', 'heuristic'),
            
                source=ctx.source, schema_era="v3.0",))

    return findings


# ---------------------------------------------------------------------------
# LR-001: LED resistor sizing validation
# ---------------------------------------------------------------------------

_LED_IF_MAX_DEFAULT_MA = 20
_LED_IF_RECOMMENDED_MA = 10


def validate_led_resistors(ctx: AnalysisContext) -> list[dict]:
    """LR-001: Check LED current-limiting resistor values."""
    findings: list[dict] = []
    leds = [c for c in ctx.components if c['type'] == 'led']
    if not leds:
        return findings

    resistors = get_components_by_type(ctx, 'resistor')
    resistor_nets, net_to_resistors = index_two_pin_components(ctx, resistors)

    cache_dir = getattr(ctx, 'cache_dir', None)

    for led in leds:
        ref = led['reference']
        mpn = led.get('mpn') or led.get('value') or ''
        facts = get_facts(mpn, cache_dir=cache_dir, diagnostics=getattr(ctx, "diagnostics", None)) if mpn else None

        # Probe diode.vf and diode.if_max from datasheet facts.
        # DatasheetFacts has no diode block, so _vf_specs and _if_specs are
        # always None today and the heuristic always fires. The datasheet
        # path activates once a diode block exists.
        _vf_specs = getattr(getattr(facts, 'diode', None), 'vf', None)
        _if_specs = getattr(getattr(facts, 'diode', None), 'if_max', None)

        ds_vf = best(_vf_specs, min_confidence='medium') if has_data(_vf_specs) else None
        ds_if = best(_if_specs, min_confidence='medium') if has_data(_if_specs) else None

        # If either Vf or If is datasheet-backed, treat the whole finding as datasheet-backed.
        # Per-field fallback is handled below when computing the actual values.
        if ds_vf is not None or ds_if is not None:
            lr_confidence = 'datasheet-backed'
            lr_evidence = 'datasheet'
        else:
            lr_confidence = 'heuristic'
            lr_evidence = 'topology'

        n1, n2 = ctx.get_two_pin_nets(ref)
        if not n1 or not n2:
            continue
        if ctx.rail_ignored(n1) or ctx.rail_ignored(n2):
            continue

        # The series resistor sits on the own node(s) at the ends of the LED's series
        # string, not on a rail or ground (those carry pull-ups and every other part
        # on the supply).
        string, e1, e2 = led_string(ctx, ref)
        if not e1 or not e2:
            continue
        own_nets = [n for n in (e1, e2) if not ctx.is_ground(n) and not is_led_rail(ctx, n)]
        series_resistors = []
        has_series_r = False
        for net in own_nets:
            led_other = e2 if net == e1 else e1
            for rref in net_to_resistors.get(net, []):
                rn1, rn2 = resistor_nets.get(rref, (None, None))
                if not rn1 or not rn2:
                    continue
                other = rn2 if rn1 == net else rn1
                if other in (e1, e2):
                    continue  # a bleeder across the LED or its string
                has_series_r = True
                if ctx.is_power_net(other) and not ctx.is_ground(other):
                    rail = other  # high side: rail -> R -> LED
                elif (ctx.is_ground(other) and ctx.is_power_net(led_other)
                      and not ctx.is_ground(led_other)):
                    rail = led_other  # low side: rail -> LED -> R -> ground
                else:
                    continue  # through a transistor or IC: the current is not computable
                ohms = ctx.parsed_values.get(rref)
                if ohms is not None and ohms > 0:
                    series_resistors.append({'ref': rref, 'ohms': ohms, 'rail': rail})
        if not has_series_r:
            has_series_r = any(ctx.comp_lookup.get(p['component'], {}).get('type') == 'resistor_network'
                               for net in own_nets for p in ctx.nets.get(net, {}).get('pins', []))
        if not series_resistors and has_series_r:
            continue

        if not series_resistors:
            has_driver = False
            for net in (n1, n2):
                for p in ctx.nets.get(net, {}).get('pins', []):
                    comp = ctx.comp_lookup.get(p['component'])
                    if comp and comp['type'] in ('transistor', 'ic'):
                        has_driver = True
                        break
                if has_driver:
                    break
            if not has_driver:
                findings.append(make_finding(
                    detector='validate_led_resistors', rule_id='LR-001', category='component_integrity',
                    summary=f'LED {ref}: no current-limiting resistor found',
                    description=f'LED {ref} ({led.get("value", "")}) has no series current-limiting resistor.',
                    severity='error', confidence=lr_confidence, evidence_source=lr_evidence,
                    components=[ref], nets=[n for n in (n1, n2) if n],
                    recommendation='Add a current-limiting resistor (typically 330R-1k for 3.3V).',
                    fix_params={'type': 'add_component', 'components': [{'type': 'resistor', 'value': '330', 'net_from': n1, 'net_to': n2}], 'basis': 'LED requires series current limiting'},
                    impact='LED overcurrent causes failure',
                    provenance=make_provenance('lr_resistor_check', 'deterministic'),
                    schema_era='v1.4',
                    source=ctx.source,))
            continue

        # Use datasheet Vf (typ) if available; fall back to color-heuristic or default.
        if ds_vf is not None and ds_vf.typ is not None:
            vf = ds_vf.typ
        else:
            vf = led_forward_voltage(led)
        # A string drops every LED's forward voltage.
        vf += sum(led_forward_voltage(ctx.comp_lookup[r]) for r in string if r != ref)
        # Use datasheet If_max (max, else typ) if available; fall back to constant.
        if ds_if is not None and ds_if.max is not None:
            if_max_ma = ds_if.max * 1000  # SpecValue in amps → mA
        elif ds_if is not None and ds_if.typ is not None:
            if_max_ma = ds_if.typ * 1000
        else:
            if_max_ma = _LED_IF_MAX_DEFAULT_MA

        for sr in series_resistors:
            rail_v = ctx.rail_voltage_or(sr['rail'], parse_voltage_from_net_name)
            rail_v = abs(rail_v) if rail_v is not None else None
            if rail_v is None or rail_v <= vf:
                continue
            current_ma = (rail_v - vf) / sr['ohms'] * 1000
            config_extra = ctx.rail_source_fields(sr['rail'])

            if current_ma > if_max_ma * 2:
                findings.append(make_finding(
                    detector='validate_led_resistors', rule_id='LR-001', category='component_integrity',
                    summary=f'LED {ref}: current too high ({current_ma:.0f}mA via {sr["ref"]})',
                    description=f'LED {ref} draws ~{current_ma:.0f}mA through {sr["ref"]} ({sr["ohms"]:.0f}R) from {sr["rail"]} ({rail_v}V). Exceeds typical {if_max_ma:.0f}mA max.',
                    severity='warning', confidence=lr_confidence, evidence_source=lr_evidence,
                    components=[ref, sr['ref']], nets=[n for n in (n1, n2) if n],
                    recommendation=f'Increase {sr["ref"]} to {(rail_v - vf) / (_LED_IF_RECOMMENDED_MA / 1000):.0f}R for ~{_LED_IF_RECOMMENDED_MA}mA.',
                    fix_params={'type': 'resistor_value_change', 'component': sr['ref'], 'current_value': sr['ohms'], 'target_metric': 'led_current_mA', 'target_value': _LED_IF_RECOMMENDED_MA, 'actual_value': current_ma, 'formula': f'R = (Vrail - Vf) / Iled = ({rail_v} - {vf}) / {_LED_IF_RECOMMENDED_MA/1000}'},
                    impact='LED overcurrent reduces lifespan',
                    provenance=make_provenance('lr_resistor_check', 'deterministic'),
                    schema_era='v1.4',
                    source=ctx.source,
                    **config_extra))

            power_w = (current_ma / 1000) ** 2 * sr['ohms']
            if power_w > 0.25 and ref == min(string):  # once per string, whichever LED starts it
                findings.append(make_finding(
                    detector='validate_led_resistors', rule_id='LR-001', category='component_integrity',
                    summary=f'LED resistor {sr["ref"]}: power dissipation {power_w*1000:.0f}mW',
                    description=f'Resistor {sr["ref"]} dissipates {power_w*1000:.0f}mW. Exceeds 250mW typical for small packages.',
                    severity='info', confidence=lr_confidence, evidence_source=lr_evidence,
                    components=[sr['ref']],
                    recommendation='Use a larger package resistor or increase resistance.',
                    provenance=make_provenance('lr_resistor_check', 'deterministic'),
                    schema_era='v1.4',
                    source=ctx.source,
                    **config_extra))

    return findings


# ---------------------------------------------------------------------------
# XT-001: Crystal load capacitance mismatch
# ---------------------------------------------------------------------------

def validate_crystal_load_caps(
    ctx: AnalysisContext,
    crystal_circuits: list[dict],
) -> list[dict]:
    """XT-001: Emit findings when crystal load capacitance is out_of_spec or marginal.

    Reads pre-computed fields from detect_crystal_circuits() output:
    - load_cap_status: 'ok' | 'marginal' | 'unverified' | 'out_of_spec'
    - target_load_source: 'datasheet' | 'parsed_from_value' | 'frequency_default'
    - effective_load_pF, target_load_pF, load_cap_error_pct

    XT-001 fires only for 'out_of_spec' and 'marginal'; 'ok' and 'unverified' are silent.
    Confidence/evidence_source tracks the target_load_source.
    """
    findings: list[dict] = []

    for xc in crystal_circuits:
        status = xc.get('load_cap_status')
        if status not in ('out_of_spec', 'marginal'):
            continue

        ref = xc.get('reference', '')
        target_load_source = xc.get('target_load_source')
        effective_pF = xc.get('effective_load_pF')
        target_pF = xc.get('target_load_pF')
        error_pct = xc.get('load_cap_error_pct')

        if target_load_source == 'datasheet':
            xt_confidence = 'datasheet-backed'
            xt_evidence = 'datasheet'
        else:
            xt_confidence = 'heuristic'
            xt_evidence = 'topology'

        severity = 'warning' if status == 'out_of_spec' else 'info'

        load_caps = xc.get('load_caps', [])
        cap_refs = [lc['ref'] for lc in load_caps]

        error_str = f'{error_pct:+.1f}%' if error_pct is not None else 'unknown'
        eff_str = f'{effective_pF:.1f}pF' if effective_pF is not None else 'unknown'
        tgt_str = f'{target_pF:.1f}pF' if target_pF is not None else 'unknown'
        src_label = {'datasheet': 'datasheet', 'parsed_from_value': 'value string', 'frequency_default': 'frequency default'}.get(target_load_source or '', target_load_source or 'unknown')

        findings.append(make_finding(
            detector='validate_crystal_load_caps',
            rule_id='XT-001',
            category='timing',
            summary=f'Crystal {ref}: load capacitance {status.replace("_", " ")} ({eff_str} vs {tgt_str} target)',
            description=(
                f'Crystal {ref} effective load capacitance is {eff_str} '
                f'({error_str} from {tgt_str} target from {src_label}). '
                f'Mismatched CL shifts oscillation frequency and may cause marginal startup.'
            ),
            severity=severity,
            confidence=xt_confidence,
            evidence_source=xt_evidence,
            components=[ref] + cap_refs,
            nets=[lc['net'] for lc in load_caps],
            recommendation=(
                f'Adjust load capacitors so CL_eff = (C1*C2)/(C1+C2) + C_stray ≈ {tgt_str}. '
                f'Typical C_stray is 3-5pF.'
            ),
            provenance=make_provenance('xtal_load_cap_check', xt_confidence),
            schema_era='v1.4',
            source=ctx.source,
        ))

    return findings


# ---------------------------------------------------------------------------
# FS-001: Feedback network stability pre-check
# ---------------------------------------------------------------------------

# Parts with a compensation pin (COMP) that takes an external network.
_REQUIRES_COMPENSATION_KEYWORDS = (
    'tps54', 'tps40',
    'uc384', 'uc282',
)

# Internally-compensated regulators — no external compensation needed.
# Checked BEFORE _REQUIRES_COMPENSATION_KEYWORDS so wins over broad matches
# like 'tps54' (which catches TPS54302's D-CAP2 part by accident).
_INTERNALLY_COMPENSATED_KEYWORDS = (
    'tps54302',                # TI D-CAP2 (already a more-specific 'tps54' match)
    'tps62',                   # TI TPS62xxx DCS-Control family
    'mpm3833',                 # MPS POL module
    'ap6',                     # Diodes Inc. AP6xxx synchronous buck family
)

# Adjustable linear regulators that need a minimum load: their datasheet divider is
# 120-240 ohm on OUT-ADJ (LM317 datasheet, R1 = 240 ohm), so a low divider impedance is intended.
_MIN_LOAD_ADJ_KEYWORDS = ('lm317', 'lm337', 'lm338', 'lm350', 'lm1117', 'ams1117', 'ld1117',
                          'lm1086', 'lt1083', 'lt1084', 'lt1085', 'lt1086', 'az1117', 'ap1117',
                          'ncp1117', 'spx1117', 'tlv1117', 'lm1084', 'lm1085', 'lt1117',
                          'lt317a', 'lm117', 'lm217', 'ld1085', 'ld1086')

# Simple Switcher bucks whose datasheet R1 (FB to ground) range puts the divider below
# _FB_IMPEDANCE_MIN: LM2596 240 ohm to 1.5 kohm, R1 about 1 kohm (SNVS124); LM2576 1 kohm
# to 5 kohm (SNVS107).
_LOW_DIVIDER_R1_RANGE = (('lm2596', 240, 1500), ('lm2576', 1000, 5000))

_FB_IMPEDANCE_MIN = 1000
_FB_IMPEDANCE_MAX = 1000000


def validate_feedback_stability(
    ctx: AnalysisContext,
    power_regulators: list[dict],
) -> list[dict]:
    """FS-001: Check regulator feedback networks for stability concerns."""
    findings: list[dict] = []
    cache_dir = getattr(ctx, 'cache_dir', None)

    for reg in power_regulators:
        ref = reg.get('ref', reg.get('reference', ''))
        fb_div = reg.get('feedback_divider')
        if not fb_div:
            continue

        r_top = fb_div.get('r_top', {}).get('ohms')
        r_bottom = fb_div.get('r_bottom', {}).get('ohms')
        if r_top is None or r_bottom is None:
            continue

        parallel_impedance = (r_top * r_bottom) / (r_top + r_bottom) if (r_top + r_bottom) > 0 else 0

        # Lookup wiring: probe regulator facts (informational only; validation
        # logic stays heuristic). cout_min and esr_range are not yet compared
        # against the schematic.
        mpn = reg.get('mpn') or ''
        if not mpn:
            comp_entry = ctx.comp_lookup.get(ref)
            mpn = (comp_entry.get('mpn') if comp_entry else '') or ''
        facts = get_facts(mpn, cache_dir=cache_dir, diagnostics=getattr(ctx, "diagnostics", None)) if mpn else None
        # facts probe is informational — confidence stays heuristic regardless.

        comp = ctx.comp_lookup.get(ref)
        min_load_adj = (fb_div.get('reference') == 'out_adj'
                        or bool(comp and match_ic_keywords(comp, _MIN_LOAD_ADJ_KEYWORDS))
                        or bool(comp and any(match_ic_keywords(comp, (kw,)) and lo <= r_bottom <= hi
                                             for kw, lo, hi in _LOW_DIVIDER_R1_RANGE)))
        if parallel_impedance < _FB_IMPEDANCE_MIN and not min_load_adj:
            findings.append(make_finding(
                detector='validate_feedback_stability', rule_id='FS-001', category='power_integrity',
                summary=f'Regulator {ref}: feedback divider impedance too low ({parallel_impedance:.0f}R)',
                description=f'Feedback divider for {ref} has parallel impedance of {parallel_impedance:.0f} ohms. Low impedance wastes quiescent current.',
                severity='info', confidence='heuristic', evidence_source='topology',
                components=[ref, fb_div['r_top'].get('ref', ''), fb_div['r_bottom'].get('ref', '')],
                recommendation=f'Increase divider resistors to achieve >{_FB_IMPEDANCE_MIN} ohm parallel impedance.',
                provenance=make_provenance('fs_stability_check', 'heuristic'),
                schema_era='v1.4',
                source=ctx.source,))

        if parallel_impedance > _FB_IMPEDANCE_MAX:
            findings.append(make_finding(
                detector='validate_feedback_stability', rule_id='FS-001', category='power_integrity',
                summary=f'Regulator {ref}: feedback divider impedance too high ({parallel_impedance/1000:.0f}k)',
                description=f'Feedback divider for {ref} has parallel impedance of {parallel_impedance/1000:.0f}k ohms. High impedance is noise-susceptible.',
                severity='warning', confidence='heuristic', evidence_source='topology',
                components=[ref, fb_div['r_top'].get('ref', ''), fb_div['r_bottom'].get('ref', '')],
                recommendation=f'Decrease divider resistors to below {_FB_IMPEDANCE_MAX/1000:.0f}k parallel impedance.',
                provenance=make_provenance('fs_stability_check', 'heuristic'),
                schema_era='v1.4',
                source=ctx.source,))

        # Only a compensation pin takes an external network; a capacitor on the feedback
        # node of an internally compensated part is not a compensation network.
        if (comp and match_ic_keywords(comp, _REQUIRES_COMPENSATION_KEYWORDS)
                and not match_ic_keywords(comp, _INTERNALLY_COMPENSATED_KEYWORDS)):
            check_net = get_pin_net(ctx, ref, ('COMP', 'CC', 'RC'))
            if check_net:
                # The network may sit behind a bridged-by-default solder jumper.
                comp_nets = [check_net] + _bridged_jumper_neighbor_nets(ctx, check_net)
                caps_on_fb = [p['component'] for n in comp_nets
                              for p in ctx.nets.get(n, {}).get('pins', [])
                              if ctx.comp_lookup.get(p['component'], {}).get('type') == 'capacitor']
                if not caps_on_fb:
                    findings.append(make_finding(
                        detector='validate_feedback_stability', rule_id='FS-001', category='power_integrity',
                        summary=f'Regulator {ref}: missing compensation capacitor',
                        description=f'Regulator {ref} ({comp.get("value", "")}) typically requires external compensation on {check_net}.',
                        severity='warning', confidence='heuristic', evidence_source='heuristic_rule',
                        components=[ref], nets=[check_net],
                        recommendation=f'Add a compensation network per {comp.get("value", "")} datasheet.',
                        impact='Regulator may oscillate or have poor transient response',
                        provenance=make_provenance('fs_stability_check', 'heuristic'),
                        schema_era='v1.4',
                        source=ctx.source,))

    return findings
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 321kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 321kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 321kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 197kUpdated Claude CodeCodexVerifiedInstall