periscope/docs/piano-pcb-review.md

# Piano — PCB review (esame geometria + stesso motore finding)

Specifica finding: [`motore-finding.md`](motore-finding.md). Schema e PCB usano **lo stesso oggetto**. Questo file è il job layout.

**Non** è un auto-placer. PCB-only = geometria (mm, width, copper, via, pour, return stitch, pad-net). Validazione netlist / mux / LED resta schema.

Contratto:

| | Schema | PCB review | Placement F2 (fuori) |
| --- | --- | --- | --- |
| Promessa | Netlist vs libreria datasheet | Layout vs libreria + geometria | xy nuovi |
| Motore finding | FACT / REQUIREMENT / INFERENCE | uguale | — |
| Deep exam PDF | **Una volta** → `library/extracted` | Consuma cache, `pdf_path=None` | — |
| Job | `MODE=run` | `MODE=pcb` | `MODE=placement` |
| Output | `report.json` | `pcb_report.json` (merge in GET /report) | pack json |

Senza `.kicad_pcb` il progetto è schema-completo. Il report schema non si riempie di PE-PLC/PE-SI.

---

## Motore (schema + PCB)

Vedi `motore-finding.md`. Invarianti:

1. Non mescolare FACT / REQUIREMENT / INFERENCE.
2. Provenance **MANDATORY | RECOMMENDED | TYPICAL | EXAMPLE** nel rule DB. **Recommended ≠ ERROR**.
3. Classi **RULE | RISK | REVIEW | INFO**. LLM = REVIEW, mai RULE.
4. `decisions.json` + fingerprint: rescan non ri-naga (PSEL low intenzionale, ecc.).
5. `status`, `confidence`, `evidence_status` indipendenti.
6. Evidenza insufficiente → lo si dice, niente 1 oz / 10 °C / 50 Ω / IEC inventati.
7. Oggetto riproducibile: facts, requirement, source, calculation, assumptions, confidence, severity, action.

UI report (schema e layout): stessa `FindingCard` — Fact / Requirement / Inference, badge classe e provenance.

Libreria: `library/extracted/{safe_mpn}.json` ∪ extracted/ progetto. PDF in `library/datasheets/blobs/`.

---

## Job PCB (invariato nello stack)

```
                    ┌─ MODE=run        → status           → report.json
  Project files  ───┼─ MODE=placement  → placement_status → placement_plan.json
                    └─ MODE=pcb        → pcb_status       → pcb_report.json
```

Stages: `ensure_graph` → `parse_pcb` → `classify` → `inventory` → `checks` → `ai_review` (layout vs library, no PDF) → `write_report`.

Mutex vs analisi e vs placement. SSE `pcb_*`. IDs `PCB-{ref}-{001}`. KiCad `/net` vs net schema: **PE-LAY-003** una volta, non per-pad (`kicad_nets_match`).

### Check PCB (geometria) — gated

| ID | Gate |
| --- | --- |
| PE-LAY-001…003 | pad/ref/hierarchy nets |
| PE-PLC-001…004 | `layout_rules` numerici |
| PE-SI-001 | `length_match` mm on USB/HDMI/PCIe/ETH/LVDS/DDR nets (not I2C/GPIO/CC) |
| PE-SI-002 | ImpedenceFinder Zavg/min/max vs `impedance` window |
| PE-SI-003…009 | max length, spacing, ref plane, vias, return, series R — each a datasheet number |
| PE-SI-010 | HS bus measured, library has no SI FACT (not 90 Ω folklore) |
| PE-PWR-001 | I_load + width; IPC solo con thickness e Tjmax |
| PE-DRT-001 | Vop e Vrated, Vop > Vr → RULE ERROR |
| PE-DRT-002 | 0.8 < Vop/Vr ≤ 1 → RISK MARGIN |
| PE-DRT-003 | Vop/Vr ≤ 0.8 → PASS summary INFO |
| PE-HIER-001 | pin IC senza net |
| PE-TIM-001/002 | RC / strap solo con numeri |
| PE-PI-001/002 | local vs bulk; mm solo da layout_rules |
| PE-ESD-001 / PE-RET-001 | REVIEW unless mandatory FACT |
| PE-VIA-001 | via count + I_load (INFO, no tabella inventata) |
| PE-THM-001 | P=I_load×drop, courtyard senza pour/via |
| PE-THM-002 | Tj=Ta+P·θJA solo con P, θJA, area rame, conteggio via |
| PE-BOM-010…014 | package / pinout / V / T / I quando BOM, PCB e datasheet hanno i numeri |
| PE-SPOF-001 | un regolatore (o un XTAL condiviso) — REVIEW |
| PE-EMI-001 | filtro EMI solo se `layout_rules` cita choke/ferrite/shield |
| PE-KEL-001 | sense/Kelvin pintable + ≥2 altri sul net |
| PE-STCH-001 | pour GND + segnale senza via GND nel bbox |
| Creepage | **skip** senza numero datasheet/IEC |
| Crystal keepout | PE-PLC-004 se kind=keepout |

AI PCB: skip IC senza pintable (`run schematic review first`).

---

## Fasi

**A — shipped:** oggetto finding condiviso, clamp provenance/class (**ERROR solo RULE+MANDATORY**), decisions, UI, libreria unica, geometria gated, net-slash, Action on card, geometria in contesto AI.

**B — questa slice (shipped, gated):**

| ID | Cosa | Gate |
| --- | --- | --- |
| Gerarchia | `hierarchy.json` component→pin→net→block | grafo (+ domains se `classify`) |
| PE-HIER-001 | pin IC senza net | FACT net='' |
| PE-DRT-001/002/003 | RISK / MARGIN / PASS | Vop **e** Vrated; niente % dielettrico inventato |
| PE-TIM-001/002 | RC reset / strap | R, C e t_reset o Vih/Vil numerici |
| PE-PI-001/002 | local vs bulk, I se noto | cap valorizzati; distanza solo con `max_distance_mm` |
| PE-ESD-001 | ESD connettore/USB | REVIEW se manca parte ESD |
| PE-RET-001 | return HS senza via GND | REVIEW, non ERROR |

**B — SI (shipped, gated):** ImpedenceFinder is **in the checks**, not only the impedance tab dump. Each datasheet SI requirement is one finding: PASS / FAIL / MARGIN + FACT / REQUIREMENT / source. A rule applies only to the **quoted bus**. **Skip** I2C, GPIO, EN, analog REGN, USB CC, strap/EN RC (not USB/DDR/PHY pairs). No invented 50/90 Ω.

### Coverage matrix (bus × requirement)

Gate: library `layout_rules` kind + `net_class`/quote on that bus. Empty cell = PE-SI-010 INFO (measurement only) if the bus is on the board; never a folklore 90 Ω ERROR.

| Bus | Z (002) | skew (001) | max L (003) | spacing (004) | ref/layer (005) | vias (006) | return (008) | series R (009) | no-Z (010) |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| USB2 D+/D− | gated | gated | gated | gated | gated | gated | gated | gated; **not** EN RC | measurement-only if no Z FACT |
| USB3 SuperSpeed | gated | gated | gated | gated | gated | gated | gated | gated | per-bus |
| ETH MDI / PHY+RJ45 | gated | gated | gated | gated | gated | gated | gated | gated | per-bus |
| RGMII MAC–PHY | gated | gated | gated | gated | gated | gated | gated | gated | per-bus |
| SGMII | gated | gated | gated | gated | gated | gated | gated | gated | per-bus |
| DDR3 CLK/DQS/DQ/ADDR | gated | gated | gated | gated | gated | gated | gated | gated | per-subclass if no Z |
| HDMI / PCIe / LVDS | gated | gated | gated | gated | gated | gated | gated | gated | per-bus |
| I2C / GPIO / EN / CC | skip | skip | skip | skip | skip | skip | skip | skip | skip |

Emmaforo USB: extract with **no Z number** → Zavg ~88 Ω is **PE-SI-010** INFO (insufficient), **not** a 90 Ω FAIL. If library later has 90 Ω ±10% (81–99), Zavg ~88 Ω **PASS** on average and **MARGIN/FAIL** if min is outside the window; ~2.5 mm intra-pair skew **FAIL** only when `length_match` mm exists. PE-SI-009 must not fire on USB from ESP32 EN RC 10 kΩ / 1 µF p.28.

Pintable skill **1.13.0** (`net_class` required on SI kinds). Older extracts with ungated `series_resistor` refresh on schematic re-run (`si_extract_needed.json` on PCB).

**B — still missing (true leftovers):**

| Gap | Why it stays out |
| --- | --- |
| Thermal FEM / energy | PE-THM-002 is Tj=Ta+P·θJA with measured copper/vias; no spreading/FEM |
| CPWG / OpenEMS | Field-solver export excluded from the ImpedenceFinder vendor snapshot |
| ImpedenceFinder license | Upstream has **no LICENSE** (UNKNOWN). Not invented in-tree. See `vendor/impedancefinder/SOURCE.md` |
| Auto-place / pcbnew write-back | Fase C |
| Fork detach | GitHub parent Faradworks/Pinscope stays; identity Fase A does not unfork |

Shipped PCB close-out (2.35.0): BOM↔PCB↔datasheet (`PE-BOM-010`…`014`); SPOF REVIEW; EMI with datasheet FACT; gated θJA Tj; SI re-extract when library `layout_rules` lack SI kinds (`model_version` 1.12.0, `si_extract_needed.json`). Shared `library/extracted` + one PDF exam.

Shipped identity Fase A (2.36.0): operator Michele Bigi; TOS/privacy/contact/metadata; PinScope identifier fence. `validate.py` untouched.

**C — fuori:** auto-place, write-back pcbnew, unire i job, sshd/keys, fork detach / PinScope engine rewrite.

Deploy: `ssh periscope` + `/root/periscope/scripts/update-periscope.sh`.