name: opensrc-graphify-agent-tooling-2026-06-06 description: Task da eseguire dal PC nel repo CODICE · adottare opensrc (sorgente delle dipendenze) e consolidare/finire il grafo della conoscenza (graphify) per dare all'agente AI il contesto reale invece dei "si presume" last_update: 2026-06-06 owner: gregorio status: done pr: Multiverbe#306

Task · Stack tooling per l'agente AI · opensrc + graphify

Dove si esegue: NON in questo repo (il BOS). Si esegue nel repo del codice del prodotto, D:\Desktop\Multiverbe\, aprendo lì una sessione di Claude Code. Questo documento è la "scheda di lavoro": lo leggi sul BOS e lo incolli/segui da PC.

In una riga: diamo all'agente che scrive il nostro codice gli occhi giusti — il codice vero delle librerie su cui costruiamo (opensrc) e una mappa interrogabile del nostro stesso codice (graphify) — così sbaglia molto meno e lavora più in fretta.

Perché questa task (in parole semplici, anche per Loris)

Quando un'intelligenza artificiale scrive codice usando una libreria esterna (per esempio React, Supabase, Three.js), nella maggior parte dei casi non legge il codice vero della libreria: si affida solo alla documentazione o ai "tipi" (una specie di indice). Risultato: a volte indovina come funziona una cosa e sbaglia, soprattutto sulle versioni nuovissime dove la documentazione online è ancora indietro. Il nostro stack è proprio così, all'avanguardia: React 19, React Three Fiber v9, Next.js 16, Tailwind v4, Supabase. Sono i casi in cui l'AI sbaglia di più.

Due strumenti open source gratuiti risolvono due lati diversi dello stesso problema:

opensrc (di Vercel) — scarica nel progetto il codice sorgente reale delle dipendenze, così l'agente sviluppa contro il codice vero della libreria, non contro un riassunto.
graphify — trasforma il nostro codice in una mappa interrogabile (un "grafo della conoscenza"): l'agente, invece di leggere a tappeto migliaia di file, chiede alla mappa "dove sta questa cosa, chi la usa, cosa rompo se la tocco" e risponde con pochissimo sforzo.

⚠️ Nota importante prima di partire · una metà è già fatta

Attenzione a non reinventare la ruota. Secondo il BOS (decisione v74 del 2026-06-04, e la pagina Cantiere → metodo/grafo) un grafo della conoscenza del codice esiste già nel repo del prodotto:

3.811 nodi, 7.942 archi, 181 gruppi, git-hook che lo ricostruisce a ogni commit, e le sessioni Claude lì lo interrogano prima di rispondere (circa 17 volte meno "token", cioè molto più economico e veloce).
Restano "da cablare" due pezzi: dare nomi leggibili ai 181 gruppi (serve una chiave AI) e completare lo strato semantico + la vista locale tipo Obsidian.

Quei due pezzi mancanti sono esattamente ciò che graphify offre pronto. Quindi la prima cosa da fare è capire cosa costruisce oggi quel grafo: se è già graphify, basta finirlo; se è uno script fatto in casa, valutare se consolidare su graphify (strumento mantenuto, multi-formato, con lo strato semantico già pronto) per non mantenere codice nostro inutilmente. La regola interna "una via di uscita / no lock-in" gioca a favore: graphify è open source e i dati restano locali.

opensrc invece è nuovo del tutto e complementare: non riguarda il nostro codice ma quello delle dipendenze. È la parte più semplice e a guadagno immediato.

Cosa ci danno · le potenzialità concrete

opensrc (npx opensrc <pacchetto>):

Scarica il sorgente vero di un pacchetto npm, PyPI (Python), crate (Rust) o di un repo GitHub dentro una cartella opensrc/, alla versione esatta che usiamo (legge il lockfile). Cache globale in ~/.opensrc/.
Esempi utili per noi: npx opensrc @react-three/fiber, npx opensrc @supabase/supabase-js, npx opensrc next, npx opensrc tailwindcss, npx opensrc vercel/ai.
Effetto: quando l'agente deve usare un'API di R3F v9 o Next 16, legge l'implementazione reale e smette di inventare comportamenti. Meno bug, meno giri a vuoto.
Confronto: fa una cosa diversa da Context7 (che dà solo la documentazione) e da Repomix/GitIngest (che impacchettano un repo per incollarlo). opensrc è il più adatto quando serve capire come funziona dentro una dipendenza.

graphify (mappa interrogabile del nostro codice):

Analizza il codice in locale con tree-sitter (33 linguaggi, zero chiamate ad API per la parte di codice), raggruppa per comunità (è il "181 gruppi" che già vediamo) e salva il risultato in pochi file che tutto il team può interrogare.
L'agente preferisce graphify query "<domanda>" al posto di leggere file alla cieca: trova le cose per struttura, non per somiglianza di testo. Questo è ciò che ci fa già risparmiare ~17x di token oggi.
Lo strato semantico (i nomi leggibili dei gruppi + relazioni "spiega perché") è la parte ancora da accendere: serve una chiave di un modello AI consentito (vedi guardrail sotto).

Guardrail (vincoli interni da rispettare)

Provider AI: lo strato semantico di graphify richiede un modello. Usare solo provider consentiti — Anthropic o Gemini (già nel nostro stack). VIETATI DeepSeek e OpenRouter (regola stack). La parte di codice (tree-sitter) resta comunque locale.
PII / sovranità dati: per la parte semantica non dare in pasto al modello dati sensibili o segreti. Tenere lo scope al codice (il nostro codice non contiene PII di clienti). Niente chiavi/.env nel grafo.
Niente file pesanti nel git: aggiungere al .gitignore del repo codice le cartelle generate — opensrc/, l'output del grafo (es. graphify-out/ o .graphify/) — così non gonfiano il repository.
Non rompere il git-hook esistente: c'è già un hook che ricostruisce il grafo a ogni commit. Se si passa a graphify, sostituirlo in modo pulito, non affiancarne due.
Una via di uscita: preferire strumenti che lasciano i dati in locale e si possono rimuovere senza danni (entrambi lo fanno).

Passi operativi (da fare nel repo codice, in PR atomiche)

Ricognizione (10 min): nel repo D:\Desktop\Multiverbe\, capire cosa costruisce oggi il grafo (cercare lo script/hook citato nella v74). Stabilire: è graphify o è fatto in casa?
opensrc (guadagno immediato):
- npx opensrc @react-three/fiber · npx opensrc next · npx opensrc tailwindcss · npx opensrc @supabase/supabase-js (e ogni dipendenza critica dove l'agente sbaglia spesso).
- Aggiungere opensrc/ al .gitignore. Annotare in AGENTS.md/CLAUDE.md del repo codice che l'agente deve consultare opensrc/ per le dipendenze.
graphify:
- Installazione CLI: uv tool install graphifyy oppure pipx install graphifyy (nota: il pacchetto su PyPI è graphifyy con due "y", ma il comando resta graphify).
- graphify install (registra la skill per Claude Code e aggiorna il CLAUDE.md del repo codice con l'istruzione "usa graphify query prima di leggere a tappeto").
- Se il grafo era fatto in casa: valutare la migrazione a graphify e rimuovere il vecchio script + sostituire il git-hook. Se era già graphify: completare lo strato semantico con un provider consentito (nomi dei 181 gruppi + relazioni).
- Verifica: aprire Claude Code, digitare / e controllare che compaiano i comandi graphify; lanciare una graphify query di prova.
Aggiornare il BOS (nello stesso loop): riportare l'esito nel Cantiere (source/_meta/cantiere.json → graph_method: i due passi "wire" passano a "live") e in canon/05-stack.md (sezione Tooling agente). Bump _meta.last_verified.

Criteri di accettazione ("fatto bene" significa)

opensrc/ popolato con almeno R3F v9, Next 16, Tailwind v4, Supabase, ignorato dal git, e citato nelle istruzioni dell'agente del repo codice.
Un solo sistema di grafo attivo (no doppioni), interrogabile con graphify query, con strato semantico acceso (nomi leggibili dei gruppi) usando un provider consentito.
Git-hook unico e funzionante (il grafo si aggiorna a ogni commit).
.gitignore aggiornato (nessun artefatto pesante committato).
BOS aggiornato: Cantiere graph_method riflette lo stato reale, canon Tooling aggiornato.

Nord: l'agente che scrive il nostro codice sviluppa contro il codice vero delle dipendenze e su una mappa reale del nostro codice — meno allucinazioni, più velocità, qualità da grande azienda verso il gate.

Riferimenti

opensrc (Vercel Labs): https://github.com/vercel-labs/opensrc
graphify (safishamsi): https://github.com/safishamsi/graphify · https://graphify.net
Storia interna del grafo: execution/decisions-log.md v74 (2026-06-04) · source/_meta/cantiere.json → graph_method

✅ Esito · completamento (2026-06-06)

FATTO · PR codice Multiverbe#306 · eseguito da sessione Claude.

Ricognizione: il grafo era già graphify (graphifyy su PyPI, comando graphify), non fatto in casa — output graphify-out/ (gitignored), hook post-commit+post-checkout installati da graphify hook install, interprete C:\Python314. Lo scope però era regredito a tutto il repo (~9.300 nodi, di cui ~3.700 documenti da n8n-skills/+docs/+.md di root, + la libreria vendata supabase-py/ ~3.000 nodi): query restituiva rumore. Gruppi senza nome (Community N).

A) opensrc — adottato. Cache globale ~/.opensrc (non una cartella opensrc/ nel repo, come ipotizzava il brief). 7 pacchetti pre-fetchati alle versioni reali: @react-three/fiber@9, three@0.171, @react-three/drei@10, zustand@4, @supabase/supabase-js@2, tailwindcss@4 (sites-runtime), next@16 (sites-runtime). Workflow: npx opensrc path <pkg> --cwd <dir>. opensrc/ nel .gitignore. (@tanstack/react-query non scaricato per un errore lato opensrc, non bloccante; tailwind@3 dell'app non scaricabile per un bug del tag del branch v3.)

B) graphify — scope ristretto + strato semantico acceso.

Creato .graphifyignore (committato): grafo ristretto al codice app. Nota: un .graphifyignore di root sostituisce il .gitignore per graphify → mirati anche gli exclude di codice (supabase-py/).
Rebuild code-only: ~6.222 nodi · ~11.892 archi · 321 gruppi (solo frontend/multiverbe-app, sites-runtime, packages, database, supabase, config, scripts).
Strato semantico ACCESO: tutti i 321 gruppi con nome leggibile in graphify-out/.graphify_labels.json (+ GRAPH_REPORT.md rigenerato). Provider = sessione Claude (Anthropic) — graphify usa il session host come LLM senza chiave esterna. I rebuild dell'hook preservano le etichette (solo i gruppi nuovi nascono Community N).
CLAUDE.md del repo codice: sezione "Tooling agente" (graphify query + opensrc path, con le versioni reali).

Differenze dal brief (chiarite): opensrc non crea una cartella opensrc/ (cache globale); lo scope reale è 321 gruppi (non 181 — il grafo è cresciuto); il grafo era già graphify, quindi nessuna migrazione/rimozione di script fatto-in-casa e un solo hook già presente; la chiave Gemini non è servita (provider = sessione Claude/Anthropic, anch'esso consentito dal guardrail).

Accettazione: ✅ opensrc popolato (R3F9/Next16/Tailwind4/Supabase) + ignorato + citato · ✅ un solo sistema grafo, graphify query ok, strato semantico acceso · ✅ git-hook unico e funzionante · ✅ .gitignore aggiornato · ✅ BOS aggiornato (cantiere graph_method: 3 step wire→live; canon Tooling; status.json done).

Follow-up opzionali (post-gate): lente Obsidian (graphify export obsidian, on-demand) · semantica LLM ai documenti (oggi code-only by-design) · ri-tentare opensrc per @tanstack/react-query · rinominare i gruppi nuovi (l'hook li marca Community N) · nota founder: .git/config del repo codice ha una chiave vscode-merge-base duplicata (warning di graphify hook status; gli hook funzionano comunque).