periscope/docs/development/PINSCOPE_INDEPENDENCE_PLAN.md

# Piano — indipendenza architettonica e di licenza da PinScope

**Stato:** solo piano. Nessuna modifica a source di prodotto, remotes, `LICENSE`, né git history.  
**Base:** [PINSCOPE_AUDIT.md](./PINSCOPE_AUDIT.md) (snapshot prodotto `facbaa2` / `cursor/pcb-review-plan-44dd`).  
**Intento di Michele:** *lasciare* il codice PinScope e le sue licenze; **isolare** l’albero ereditato; disegnare dipendenze; marcare cosa **deve** essere riscritto. Non cancellare ogni riga ereditata.

Questo piano **non** stacca il fork GitHub (`manvalan/periscope` ← `Faradworks/Pinscope`). Lo stacco è un passo legale successivo, fuori da queste fasi di lavoro, salvo decisione esplicita.

---

## 1. Obiettivo

Due indipendenze distinte, nello stesso prodotto:

| Asse | Cosa significa | Cosa *non* significa |
| --- | --- | --- |
| **Architetturale** | Periscope evolve identity, auth, LLM, contratto finding, job PCB/placement **senza** fingere di essere Faradworks/Pinscope e senza che il nuovo codice importi il loop PinScope come se fosse “nostro” | Cancellare `graph.py`, i parser, o il 79% di linee lineage |
| **Licenza / identità** | Operatore, TOS, privacy, metadata, vendor terzi con licenza **nota**; AGPL del fork **resta visibile** e attribuita | Relicenziare l’albero PinScope, togliere AGPL, o chiedere a Faradworks una licenza commerciale come se fossimo noi l’upstream |

**Criterio di fatto:** un modulo è “nativo Periscope” se può cambiare contratto (finding, PCB, auth locale, DeepSeek) senza patchare il recinto PinScope. Un modulo è “ereditato” se un `git blame`/Jaccard da audit lo lega a `pinscopex` / UI OSS Faradworks.

L’audit già dice: l’indipendenza **non** è bloccata dalle stringhe `pinscope`; è bloccata da pipeline, identità legale, `main` stantio, seam Clerk/Anthropic, ImpedenceFinder senza licenza.

---

## 2. Confine di isolamento (fence)

### 2.1 Recinto — albero ereditato (resta, non si “ripulisce”)

Trattare come **una dipendenza in-tree**, non come prodotto Periscope:

| Pacchetto logico | Path odierni | Licenza da audit |
| --- | --- | --- |
| Core schematico PinScope | `backend/periscopex/{graph,models,parsers,parsers_edif,validate,validation_tools,resolve_passives,derating,bom_summary,taxonomy,pin_mux_check,led_current_check,pin_function_tokens}.py` | AGPL-3.0 del fork (blob `LICENSE` identico a upstream) |
| Orchestrazione review | `backend/services/pipeline.py`, `pipeline_worker.py`, `services/validation.py`, `services/extraction.py` (parte DIRECT) | stessa |
| Skills Anthropic/Console | `skills/extract-pattern`, `skills/extract-specs`, `skills/extract-pintable/{schema.json,validate.py}`, `scripts/upload_skills.py`, `backend/skills_manifest.json` | stessa + contratto Claude |
| UI OSS / marketing shell | gran parte di `frontend/src` UPSTREAM/DERIVED, `frontend/public`, `frontend/content/terms.md` + `privacy.md` (testo Faradworks) | AGPL + TOS Faradworks **nel contenuto** |
| Gateway seams | `billing_hook.py`, `proxy.ts`, `clerk-theme-provider.tsx`, `use-optional-auth.ts`, analytics, CSP hosts | stub open-core PinScope |
| Fixture upstream | `simple_project/` (asc/csv/pdf/`design_graph.json`), `docs/how-it-works.svg` | AGPL / contenuto upstream |

**Regola del recinto (quando si implementerà, non ora):**

- Import **solo** da una facciata stretta (es. `build_graph`, `parse_bom`, `parse_netlist_any`, `Finding` Pydantic, `validate_design_async`).
- Nessun nuovo check PCB/schema scrive dentro `validate.py`.
- Nessun file nativo assume Clerk, Anthropic Console, `pinscope.ai`, Faradworks Inc.
- Il recinto **conserva** `LICENSE` AGPL e l’attribuzione “derived from Faradworks/Pinscope”.

Implementazione fisica futura (non in fase identità): directory tipo `vendor/pinscope/` **oppure** package `backend/pinscope_legacy/` con shim `periscopex` — solo dopo che i consumer nativi non importano più path sparsi. Non è un rename cosmetico (`pinscopex` → `periscopex` è già successo e **non** è un recinto).

### 2.2 Nativo Periscope (fuori recinto)

| Area | Path | Perché è nativo |
| --- | --- | --- |
| Contratto finding | `finding_engine.py`, `docs/motore-finding.md` | NEW; clamp FACT/REQUIREMENT/INFERENCE |
| PCB exam | `pcb_pipeline.py`, `pcb_*.py`, `parsers_kicad_pcb.py`, UI `pcb/` | NEW; INDIRECT sul grafo |
| Placement F2 | `placement_pipeline.py`, `placement_pack.py`, `functional_groups.py` | NEW |
| RF / antenna | `antenna_*.py`, parte Impedance UI | NEW |
| Facade Z0 | `periscopex/impedance.py` | NEW; il solver è terzi |
| Auth self-host | `local_jwt.py`, `local_users.py`, `routers/auth.py` | REPLACEMENT |
| LLM DeepSeek | `deepseek_provider.py`, `local_skill.py`, `pdf_ingest.py` | NEW |
| Deploy | `scripts/update-periscope.sh`, `docker-compose.yml` | NEW (nomi `pinscope_*` ancora WEAK) |
| Plugin KiCad | `plugins/kicad/` | NEW |
| Check deterministici fork | `dnp_check`, `sequencing_check`, `layout_rules`, … | NEW ma **INDIRECT**: usano `models` / graph |

### 2.3 Terzi (né PinScope né “nostro motore”)

`vendor/impedancefinder/` — commit `a0c8d0ec`, licenza **UNKNOWN** (audit §6.4). Resta dietro `impedance.py` + `vendor_path.py`. Non mescolare con AGPL PinScope né con il finding engine.

---

## 3. Albero delle dipendenze

Forza: **DIRECT** = stesso control flow / blob lineage PinScope; **INDIRECT** = codice nativo che importa DIRECT; **WEAK** = alias, brand, reti Docker.

```
Faradworks/Pinscope (AGPL-3.0)
│
├─ DIRECT  periscopex.graph / parsers* / taxonomy / models
│     ├─ INDIRECT  pipeline MODE=run (Parse → extract → build_graph → review)
│     ├─ INDIRECT  pcb_pipeline.ensure_graph + pintable cache
│     ├─ INDIRECT  placement / functional_groups
│     └─ INDIRECT  cad_bridge, parsers_kicad*, pcb_inventory
│
├─ DIRECT  validate.py + validation_tools + extraction skills
│     ├─ INDIRECT  finding_engine.complete_findings  (graft, non sostituisce il loop)
│     ├─ INDIRECT  pcb AI  (_parse_review)
│     └─ WEAK      anthropic SDK, upload_skills.py, CLAUDE.md Console
│
├─ DIRECT  models.Finding + normalize_findings + dedupe_findings
│     └─ INDIRECT  finding_engine (PE-*, provenance clamp) + FindingCard
│
├─ DIRECT  Next.js app (wizard, report, admin, legal pages)
│     ├─ INDIRECT  pcb-exam-section, impedance-panel, topology-panel, local sign-in
│     └─ WEAK      Faradworks metadata, pinscopex localStorage, ClerkThemeProvider
│
├─ DIRECT  Clerk / billing_hook seams
│     └─ INDIRECT  local JWT (parallel stack, non ha spento Clerk)
│
└─ (non PinScope) vendor/impedancefinder
      └─ INDIRECT  periscopex.impedance → tab RF
```

### 3.1 Consumer Periscope × sottosistema PinScope

| Sottosistema PinScope | Consumer Periscope | Forza | Se si riscrive il PinScope… |
| --- | --- | --- | --- |
| Graph + parsers BOM/netlist | `pipeline.py`, PCB, placement, tutti i check | DIRECT / INDIRECT | Cade tutto il prodotto |
| `validate.py` review loop | report schema, PCB AI | DIRECT | Serve un reviewer nativo **prima** di spegnere PinScope |
| `Finding` Pydantic | `finding_engine`, UI card, cad-bridge | DIRECT | Mappare al contratto `motore-finding.md` |
| Skills pintable/pattern/specs | extraction, library | DIRECT | Già in parte sostituiti da `local_skill.py` |
| UI shell | ogni pagina | DIRECT | Identità e finding card prima; wizard dopo |
| Clerk/billing | `main.py`, admin, email | DIRECT + WEAK | Auth locale già c’è |
| Legal Faradworks | `/terms` `/privacy` layout | DIRECT contenuto | Non è codice motore |

**Cosa deve essere riscritto** (per indipendenza vera, fasi tarde — non per “pulizia”):

1. **Identità legale/UI** — obbligatorio e **primo**; non è il motore.
2. **Seam Clerk + Anthropic** — obbligatorio per non dipendere dal cloud Faradworks.
3. **Loop `validate.py` / `_parse_review` / tool graph** — obbligatorio per un motore *Periscope*, **dopo** identità; oggi `finding_engine` è solo un clamp.
4. **IR `Finding`** — allineare il tipo Pydantic al contratto FACT/REQUIREMENT/INFERENCE (oggi campi doppi `finding`/`why`).
5. **UI report/wizard** — quando il contratto finding è nativo; non nella fase identità.
6. **Parsers/graph** — *non* obbligatori per identità; rewrite solo se si vuole un CAD layer Periscope senza AGPL PinScope (programma XL, ultimo).

---

## 4. Mappa licenze — cosa blocca una licenza Periscope “pulita”

“Pulita” = *Periscope come opera dell’operatore Michele, con dipendenze dichiarate*, **non** “Periscope senza AGPL”. L’albero PinScope **resta AGPL**; toglierlo richiederebbe rewrite totale del recinto (fase ultima) **e** comunque rispetto dei diritti sul codice già pubblicato.

| Pezzo | Evidenza audit | Blocca identità Periscope? | Blocca relicenza non-AGPL del binario combinato? |
| --- | --- | --- | --- |
| `LICENSE` AGPL-3.0 identico a upstream | KEEP | No, se attribuito | **Sì**, finché il recinto è nel tree/servizio |
| TOS/privacy Faradworks, Inc. + `dev@faradworks.com` | REPLACE | **Sì** (operatore sbagliato) | No (non è la GPL) |
| Metadata `layout.tsx` authors/publisher Faradworks, `@getFaradWorks` | REPLACE | **Sì** | No |
| README “commercial licensing of the original → Faradworks” | tenere come *attribuzione upstream*, non come offerta nostra | Parziale | No |
| Fork GitHub ancora `parent: Faradworks/Pinscope` | non staccare in questo piano | No (fatto) | No |
| `anthropic` in `requirements.txt` + `upload_skills.py` | ISOLATE | Policy prodotto / ToS Anthropic vs DeepSeek | No |
| Clerk JWKS / API | ISOLATE | ToS Clerk se usato in prod | No |
| ImpedenceFinder `license: null`, no LICENSE file | INVESTIGATE | Distribuzione RF tab | **Sì** per *quel* vendor (sconosciuta) |
| PyMuPDF dual AGPL *or* Artifex commercial | INVESTIGATE | Quale grant in VPS | AGPL già dal root; commerciale Artifex è altro contratto |
| Transitive Python | no lockfile | Audit incompleto | Possibile gap |
| npm MPL/LGPL (lightningcss, sharp-libvips) | lock fields | Attribuzione frontend | Copyleft diverso, non Faradworks |
| `xlsx@0.18.5` Apache-2.0 nel lock | OK dichiarato | No | No |

**Bloccanti identità (fase A):** testi Faradworks nel prodotto.  
**Bloccanti “SaaS Periscope senza AGPL”:** l’intero recinto PinScope + PyMuPDF se si usa il grant AGPL. **Questo piano non promette relicenza.**  
**Bloccante vendor:** ImpedenceFinder senza licenza — non distribuire come “Periscope MIT/Apache”.

---

## 5. KEEP / ISOLATE / REWRITE / REMOVE

Sforzo: **S** (file/config), **M** (un sottosistema, test esistenti), **L** (contratto + UI + pipeline), **XL** (nuovo CAD/IR). Non è calendario.

| Area | Azione | Sforzo | Fase |
| --- | --- | --- | --- |
| Blob `LICENSE` AGPL + attribuzione PinScope | **KEEP** | — | tutte |
| Graph, parsers, taxonomy, BOM, derating, EDIF | **KEEP** nel recinto | — | A–C; **REWRITE** solo E (XL) |
| `simple_project`, how-it-works.svg | **KEEP** | — | |
| Changelog storico Pinscope/`PS-*` | **KEEP** | — | |
| PCB, placement, antenna, plugin, `finding_engine` come clamp | **KEEP** nativo | — | non toccare in A |
| TOS, privacy, contact, footer ©, `layout.tsx` authors, Twitter | **REWRITE** (identità) | S–M | **A** |
| `storage-keys.ts` write `pinscopex:` | **REWRITE** write path; dual-read | S | A |
| Alias `pinscope_version`, JWT `pinscope-local`, CORS host, Docker `pinscope_*` | **ISOLATE** poi scadere | S | A |
| Clerk stack | **ISOLATE**; **REMOVE** quando JWT locale è l’unico modo | M | B |
| `anthropic`, `upload_skills.py`, CLAUDE.md Console | **ISOLATE**; **REMOVE** se DeepSeek-only | M | B |
| `billing_hook` / proxy stubs | **ISOLATE** (firme); non Faradworks in copy | S | B |
| `validate.py` + `validation_tools` + `_parse_review` | **KEEP** in A–B; **REWRITE** reviewer nativo | L | **C** |
| `models.Finding` vs `motore-finding.md` | **REWRITE** IR (compat shim) | M–L | C |
| `normalize_findings` / `dedupe_findings` | **KEEP** o reimplementare sul nuovo IR | M | C |
| Skills extraction (schema) | **ISOLATE**; prompt già in parte REPLACEMENT | M | C |
| FindingCard / report UI | **REWRITE** quando IR nativo | M–L | **D** |
| Wizard upload / admin Clerkisms | **REWRITE** / pulizia | M | D |
| `vendor/impedancefinder` | **ISOLATE** + licenza esplicita | S legale + M se drop | B (licenza), non engine |
| Parsers/graph nativi Periscope | **REWRITE** solo se si esce da AGPL PinScope | XL | **E** |
| Stacco fork GitHub | **non in questo piano** | legale | dopo E o mai |

**REMOVE** in A: niente codice motore. Solo copy Faradworks *dopo* TOS Periscope pronti.

---

## 6. Sequenza per fasi

### Fase A — Identità e recinto documentale (**non** rewriting del finding engine)

Allineato all’audit §11 punti 1–4: `finding_engine` / `validate.py` **non** si riscrivono qui.

1. Pubblicare audit + questo piano (solo docs).
2. Decidere `origin/main` vs `cursor/pcb-review-plan-44dd` **senza** staccare il fork (merge prodotto su `main` *oppure* `main` dichiarato archivio).
3. TOS/privacy/contact/metadata/Twitter/footer operatore Periscope; una riga di attribuzione AGPL PinScope/Faradworks (non “siamo Faradworks”).
4. Compatibility fence: un modulo/doc per chiavi `pinscope_*`; smettere di **scrivere** `pinscopex:` in `localStorage`.
5. Dichiarare a codice (commento/ADR) il recinto §2 — ancora senza muovere file.

**Done quando:** UI e legal non dicono Faradworks Inc.; AGPL e fork parent invariati; PCB/schema invariati.

### Fase B — Seam runtime (Clerk, Anthropic, vendor license)

Audit §11 punti 5–6, 8–9.

- JWT locale default documentato; Clerk dietro seam nominato (`use_clerk`).
- DeepSeek unico provider supportato; Anthropic + Console skills = optional/legacy; CLAUDE.md = README.
- Licenza scritta per ImpedenceFinder **o** non distribuire `vendor/`.
- Lockfile Python per transitive.

**Done quando:** boot produzione non richiede Clerk; nessun path “devi uploadare skill Anthropic”; vendor RF ha SPDX o è fuori tree.

### Fase C — Motore review PinScope-derived (**rewrite map**, dopo A–B)

Qui sì si riscrive l’engine ereditato. Ordine interno:

| Step | Oggetto | Perché |
| --- | --- | --- |
| C0 | Spec freeze `motore-finding.md` = unico IR | Già nativo; non diluire in `validate.py` |
| C1 | Adapter: `validate.py` emette solo `Finding` grezzi → `complete_finding` | Già parziale; chiudere i campi doppi |
| C2 | **REWRITE** loop per-IC: tool `find_connected_components` / `get_pintable` / excerpt su provider DeepSeek **senza** copiare `validation_tools.py` | Cuore DIRECT da sostituire |
| C3 | Extraction: `local_skill.py` + schemi JSON (KEEP schema se identici; REWRITE orchestrazione Anthropic) | |
| C4 | Spegnere import da `validate.py` nel PCB (`_parse_review` → parser finding nativo) | Toglie INDIRECT PCB→PinScope reviewer |
| C5 | Test golden `simple_project` + Emmaforo: parity FACT/REQUIREMENT, non parity prose | |

**Non in C:** riscrivere `graph.py` / parser KiCad.

**Done quando:** `validate.py` PinScope può restare nel recinto **non chiamato** dal job schema/PCB, oppure ridotto a wrapper deprecato.

### Fase D — UI

FindingCard, filtri Layout, wizard, admin senza Clerk copy, `package-lock` version drift. Dopo C1 almeno (stesso oggetto finding).

### Fase E — Parsers / graph (opzionale, XL)

Solo se l’obiettivo diventa *opera senza codice AGPL PinScope*. Sostituire BOM/netlist/graph/taxonomy è un secondo prodotto. PCB nativo resta INDIRECT finché `ensure_graph` chiama PinScope.

**Stacco fork GitHub:** solo dopo consiglio legale, **non** in A–D.

---

## 7. Rischi e sconosciuti

| Rischio | Impatto |
| --- | --- |
| Clone di default `main` ≠ prodotto 2.32.1 | Ogni PR “solo docs” su `main` descrive un altro tree |
| Rewrite `validate.py` in A | Rompe schema+PCB; l’audit lo vieta come primo passo |
| Recinto solo rename di cartella | Falso recinto (già successo con `periscopex`) |
| TOS Periscope scritti male | Resta il testo Faradworks *o* si perde AGPL attribution |
| ImpedenceFinder | Distribuzione RF senza grant |
| PyMuPDF grant in VPS | Dual license; non verificato a runtime |
| Clerk rimasto in `ENVIRONMENT=production` | Deploy script vs JWT locale |
| Anthropic ancora importabile se c’è la key | README ≠ runtime |
| Trademark Pinscope/Periscope/Faradworks | Audit: solo *use*, nessuna registrazione |
| Relicenza “Periscope MIT” | Impossibile finché il recinto è servito (AGPL §13 network) |
| Gateway privato Faradworks | Non è nel repo; non auditabile |

---

## 8. Non-obiettivi (espliciti)

- Non modificare source prodotto, remotes, `LICENSE`, git history **in questa consegna** (piano only).
- Non staccare il fork GitHub in queste fasi (**passo legale successivo**, se mai).
- Non cancellare il codice PinScope “perché è PinScope”.
- Non riscrivere `finding_engine` / `validate.py` / PCB nella **fase A**.
- Non auto-placer, non write-back pcbnew (già fuori da `piano-pcb-review.md`).
- Non promettere una licenza Periscope non-AGPL.
- Non mescolare mbparks/pinscope (Arduino) — progetto altro.
- Non usare questo piano come licenza a refactor su `cursor/pcb-review-plan-44dd` oltre un eventuale **solo** file docs su **nuovo** branch.

---

## 9. Priorità di rewrite (lista operativa)

1. **Identità** — TOS, privacy, contact, `layout.tsx`, `site.ts` Twitter, footer ©  
2. **Fence compat** — stop write `pinscopex:`; isolare alias versione/JWT/CORS/Docker  
3. **`main` vs product branch** — topologia git, fork attaccato  
4. **Clerk seam** — default JWT locale  
5. **Anthropic/Console seam** — DeepSeek-only di fatto  
6. **Licenza ImpedenceFinder** — grant o drop vendor  
7. **Lockfile Python** — transitive  
8. **IR finding** — `Finding` ≡ `motore-finding.md` (fase C, non A)  
9. **Loop `validate.py` / `validation_tools`** — reviewer nativo (C)  
10. **PCB/schema smettono di chiamare `_parse_review` PinScope** (C4)  
11. **UI FindingCard/wizard** (D)  
12. **Parsers/graph** solo se si vuole uscire da AGPL PinScope (E)  
13. **Stacco fork** — legale, fuori piano  

---

## 10. Riferimenti

- Audit: [PINSCOPE_AUDIT.md](./PINSCOPE_AUDIT.md)  
- Contratto finding nativo: [`docs/motore-finding.md`](../motore-finding.md) (store) / `docs/motore-finding.md` nel repo prodotto  
- Job PCB: [`docs/piano-pcb-review.md`](../piano-pcb-review.md)