periscope/docs/piano-pcb-review.md

Piano — PCB review (esame AI + check deterministici)

Fonte di verità per Periscope Layout review. Non è un auto-placer.

Delta vs revisione precedente: l’esame del board è agentico come la pipeline schema (datasheet + neighborhood + tool, findings ERROR/WARNING/INFO con sempre una recommendation). Restano i check numerici gated. Auto-placement / pack / write-back pcbnew restano fuori.

Prodotto: esaminare un .kicad_pcb già (parzialmente) sbrogliato — placement, routing, impedenze, lunghezze, decoupling, filtri, derating, compliance datasheet — e dire cosa è sbagliato e come sistemarlo. Non si spostano footprint e non si scrive rame.

Contratto rispetto a docs/piano-implementazione.md:

	Schema (già in produzione)	PCB review (questo piano)	Placement F2 pack (fuori)
Promessa	Lo schema rispetta il datasheet	Il layout esistente rispetta datasheet + geometria	Proporre xy nuovi
Metodo	Check deterministici + review LLM per-IC	Stesso spirito: check + review LLM per-IC sul PCB	Skeleton placement_pack.json
Trigger	BOM + netlist / .kicad_sch	+ .kicad_pcb	PCB + layout_rules numerici
Output	Finding pin/net, derating, review	Finding mm / net / Z0 / skew / via EP / layout AI; PE-PLC* PE-SI* PE-LAY* PE-Z0*	Proposte xy
Job	MODE=run (status)	MODE=pcb (pcb_status)	MODE=placement (placement_status)

Senza .kicad_pcb il progetto resta uno schema completo. Il report schema non si riempie di finding layout.

---

0. Postura: esame AI, non progettazione

Stesso spirito della Direct Datasheet Review: il modello legge datasheet + contesto del circuito e geometria del footprint/net, usa tool sul grafo, sottomette finding. Non progetta il board.

Domains e functional Groups

Obbligatori come contesto dell’esame (non come packing):

• Domains = isole sulle power net (functional_groups.py / placement_plan.json).
• Groups = IC + satelliti con role_hint (decoupling, bulk, filter, crystal, …).

Il job PCB classifica (riusa build_placement_plan) e passa domains/groups al reviewer e all’inventory. Non propone coordinate.

La pipeline Placement (POST …/placement/start) resta topologia routing-first. F2 pack/export parcheggiati.

Placement = verifica (deterministico + AI)

Misura ciò che è già sul board: distanza pad-cap, layer, via EP, keepout, crystal load caps. placement_check (PE-PLC-001…004) è il nucleo numerico. L’AI copre note di layout del datasheet senza mm strutturato (citazione + Unverified: se la quote non verifica), sempre con recommendation.

Routing = la stessa postura

Lunghezze, coppie, bus, Z0, pad-net vs schema. si_check (PE-SI-001) solo con length_match mm. L’AI può flaggare crossing/loop evidenti solo se il contesto geometria lo mostra; niente 3W/IEC inventati.

Findings (come parte 1 / schema)

Ogni finding PCB:

• status: ERROR | WARNING | INFO
• recommendation obbligatoria anche per INFO (cosa fare: spostare, allungare/accorciare, cambiare rating, verificare stackup, …)
• rule_id sui check automatici; review AI: source=pcb_review
• IDs PCB-{designator}-{001} per non collidere con lo schema

Normalization resta downgrade-only.

---

1. Job parallelo (riuso stack)

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

Riuso

Pezzo	Path	Ruolo PCB
Workspace / SSE	pipeline.py	PipelineWorkspace, broker
Dispatch	job_runner.py, pipeline_worker.py	MODE=pcb
API	routers/pipeline.py	pcb/start, cancel, events, inventory
Meta	projects.py	pcb_status, pcb_state, pcb_execution_name, pcb_cancel_requested
Parser	parsers_kicad_pcb.py	LayoutGraph
Groups	functional_groups.py	domains + groups
Placement	placement_check.py	PE-PLC-*
SI	si_check.py	PE-SI-001
Filtri	filter_check.py	contesto; proximity solo con mm
Derating	derating.py	Vop vs Vrated se entrambi noti
Impedenza	impedance_traces.py	inventory Z0; finding se target numerico
Review LLM	services/validation.py + prompt PCB	per-IC, stesso loop tool/submit_review
Cad bridge	cad_bridge.py	target: pcb
UI	report finding-card, sidebar, types.ts, api.ts	tab Layout, merge findings

Contratto job

• Non tocca status schema.
• Soft-cancel pcb_cancel_requested.
• Mutex vs analisi e vs placement (event log condiviso).
• SSE pcb_step_update / pcb_complete / pcb_error / pcb_cancelled.
• Locale: local/pcb/{id}.
• Heal zombie come placement.
• LLM: stesso provider DeepSeek della review schema; ApiLogger stage pcb_review; billing via get_billing() (NullBilling in OSS).
• Senza API key in test: skip AI, check deterministici restano.

Stages

1. ensure_graph — design_graph.json o graph_build.
2. parse_pcb — layout_graph.json / parse_kicad_pcb. Fail → error.
3. classify — domains + groups (build_placement_plan); scrive functional_groups.json se manca.
4. inventory — tracce, bus, lunghezze, Z0 → pcb_inventory.json.
5. checks — deterministici fail-soft (run_pcb_checks).
6. ai_review — per-IC come schema, contesto layout + group/domain + inventory del vicinato.
7. write_report — pcb_report.json, cad-bridge, IDs PCB-*.

---

2. Ingressi

Ingresso	Obbligatorio v1
.kicad_pcb (has_pcb)	Sì
design_graph.json	Sì
extracted/ + layout_rules / pintable	Per check numerici e AI
Shared library library/extracted/{safe_mpn}.json	Unico store schema+PCB. Deep exam PDF una volta (pipeline schema).
PDF datasheet	Solo per estrazione / review schema. PCB non riattacca il PDF.
Stackup nel PCB	Per Z0 e ampacity; skip se assente

---

3. Check (deterministici) + AI

3.1 Inventario (non finding)

Net con rame: lunghezza, layer, width min/max, via, coppia, bus, Z0 se stackup. Domains/groups elencati.

3.2 Deterministici

ID	Cosa	Gate
PE-LAY-001	Pad net ≠ pin net schema	entrambi noti
PE-LAY-002	Ref schema senza footprint (skip #PWR)	graph + PCB
PE-PLC-001…004	decoupling / via / same_layer / keepout	layout_rules numerici
PE-SI-001	skew coppia	length_match mm
PE-DRT-001	Vop > Vrated sul cap (derating.py)	entrambe le tensioni
PE-Z0-001	Z0 fuori target	target in regola o netclass; mai 50 Ω default
PE-PWR-001	Larghezza × spessore rame vs I_load	I_load + width; IPC-2221 solo con copper_thickness_mm e Tjmax (ΔT=Tjmax−25 °C)
PE-VIA-001	I_load / N via	geometria via + I_load; INFO (niente tabella via inventata)
PE-THM-001	P=I_load×(Vin−Vout) senza pour/via courtyard	I_load, Vin/Vout, courtyard
PE-KEL-001	Pin sense/Kelvin su net di carico	nome pintable + ≥2 altri sul net
PE-STCH-001	Segnale sopra pour GND senza via GND nel bbox	zone GND + segmenti; INFO
Creepage	—	skip senza numero datasheet/IEC
Crystal keepout	PE-PLC-004	layout_rules kind=keepout

Filtri: check_filters non duplicato nel report PCB (resta schema). L’AI e i groups usano role_hint=filter per proximity se c’è mm.

3.3 AI exam (layout-only, shared library)

Per ogni IC con pintable in library/extracted o extracted/ di progetto (stesso JSON):

• Non si ri-legge il PDF. L’esame datasheet profondo è quello della pipeline schema.
• System prompt PCB: layout vs JSON di libreria.
• User: format_library_extraction + build_pcb_layout_context.
• review_ic_async(..., pdf_path=None) — niente attach, niente quote-verify PDF.
• Skip: no library extraction — run schematic review first.
• Recommendation obbligatoria; isolation per-IC.

UI: sezione report PCB exam (pcb-exam-section.tsx) — findings source=pcb_review e PE-PWR/THM/VIA/KEL/STCH. Nascosta con ?domain=schema.

3.4 Skip (no folklore)

3W, creepage IEC senza numero, CPWG, HV isolation, length-match USB spec, confronto foto TI vs gerber, 1 oz / 10 °C / 50 Ω di default.

---

4. UI

Superficie	Comportamento
Hub	Run PCB review se hasPcb
/project/[id]/pcb	Stepper SSE (include ai_review)
Sidebar	Layout → /pcb
Report	Merge + sezione PCB exam; ?domain=layout; badge Layout; recommendation sempre visibile
Inventory	Traces/buses/Z0 + domains/groups

---

5. Fasi di implementazione

Dopo ogni fase: test delle funzioni toccate, commit, push. Dopo ogni macro-fase operativa: deploy ssh periscope + scripts/update-periscope.sh (niente chiavi/sshd).

Fase 0 — Split schema / layout

Togliere placement_check / si_check da _run_deterministic_checks schema. Eval schema: layout=None resta no-op.

Done when: schema senza PCB = zero PE-PLC/PE-SI.

Fase 1 — Job + deterministici + UI (macro operativa)

Meta pcb_*, worker, router, run_pcb_checks, inventory, report merge, UI start/progress/filtro.

Done when: upload PCB → start → finding nel report. Deploy.

Fase 2 — AI exam + domains/groups (macro operativa)

classify + ai_review per-IC, prompt PCB, recommendation obbligatoria, changelog Layout.

Done when: con API key, IC con libreria producono finding source=pcb_review o coverage vuota; senza key, skip loggato. Deploy.

Fase 3 — Plugin + eval PCB

Cad-bridge pcbnew; golden fixture. Packing resta fuori.

Fase 4 — Libreria unica + sezione PCB exam (macro operativa)

Un store library/extracted (più extracted/ di progetto). PCB non duplica l’esame PDF. Sezione report PCB exam + PE-PWR/THM/VIA/KEL/STCH.

Done when: IC senza pintable skipped; con libreria, AI layout-only; check IPC solo con stackup+Tjmax. Deploy.

---

6. Fuori scope

• Auto-placement, packing mm, write-back pcbnew.
• Autore di sbroglio / change width.
• SPICE / IBIS / EM.
• Inventare mm, Ω, V/mm.
• EasyEDA, Gerber come ingresso, PADS layout.
• Unire il job PCB nella run schema.
• Toccare ssh keys / sshd.

---

7. Done (fixture)

1. Decoupling 15 mm vs regola 2 mm → PE-PLC-001 + recommendation.
2. 1 mm → niente proximity.
3. Skew coppia > length_match → PE-SI-001.
4. Pad net mismatch → PE-LAY-001.
5. Senza PCB → 400 sul start.
6. AI: contesto contiene domain/group; finding senza recommendation rifiutati/completati dal parser.

---

8. Relazione

Wave G di piano-implementazione.md = questo job di esame (ora anche LLM). F2 pack non entra.