Files

T

simone 817a8cd5d1 chore(claude): architettura base .claude — skill preventivo e audit, hook di guardia, piani nel repo

La cartella aveva dentro solo rules/ e i settings: nessun posto dove mettere una
skill, un hook o un piano. Ora ha lo scheletro completo e un .claude/CLAUDE.md che
spiega cosa va dove — non duplica CLAUDE.md di progetto, che resta quello che comanda.

Due skill locali (le altre restano globali in ~/.claude/skills/):
- /preventivo — la catena agent.ts → schema.ts → assemble.ts → ProposalDeck e i tre
  modi di romperla, di cui uno solo fa rumore. Nessun prompt di generazione qui
  dentro: quello vive in agent.ts ed e' l'unico. Porta check-profilo.sh.
- /audit — guida scripts/audit-fonti.ts, nuovo, che mette in moto le cinque fonti di
  src/lib/audit/sources/, in prod dal 2026-08-19 ma mai chiamate da nessuno. Provate
  su giojello.com: 5 su 5, 42,7 s, PageSpeed mobile 58 / desktop 93.

Due hook, provati a mano (6 casi il primo, 5 il secondo):
- guardia-migration.sh BLOCCA l'SQL distruttivo sulle entita' protette — il vincolo
  Data Safety (LOCKED) fatto rispettare dalla macchina invece che dalla memoria.
- guardia-token.sh AVVISA sulle classi Tailwind grezze. Non blocca: con ~450
  occorrenze di debito, bloccare lo renderebbe un ostacolo da disattivare.

I tre piani di v2.5 entrano nel repo: stavano solo in ~/.claude/plans/ e STATE.md
avvertiva che senza quelli la milestone non era ricostruibile. Passati al setaccio
per credenziali prima di committarli.

Corretta in rules/memory-discipline.md la chiave della memoria persistente: e'
…-Vault-IAMCAVALLI-hub, non quella del workspace. Sedici file stavano nella prima,
la regola indicava la seconda.

Impeccable resta abilitato solo a livello globale: fuori da settings.json locale.

Nessun tocco al prodotto. Build e lint verdi, lint identico al baseline.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-08-26 16:09:14 +02:00

4.4 KiB

Raw Blame History

name, description

name	description
audit	Far girare le fonti di rilevazione dell'audit sito di ClientHub su un URL e capire cosa e' stato misurato e cosa no. Da usare quando si lavora al motore audit v2.5, quando serve una rilevazione su un sito reale, quando si vuole sapere se una fonte risponde, o prima di scrivere qualsiasi pezzo del documento di audit.

Audit — le rilevazioni, e cosa vale come misura

Il motore v2.5 non e' scritto. Quello che esiste, e che questa skill mette in moto, sono le fonti di rilevazione: nessun LLM, nessun database, nessun browser headless.

Due attrezzi, due domande diverse

Comando	Cosa fa	Quando
`npx tsx scripts/audit-fonti.ts <url>`	Le cinque fonti di `src/lib/audit/sources/` — pagine, CrUX, PageSpeed, storico Wayback, segnali. Puramente meccanico	«Cosa si riesce a misurare su questo sito?»
`npx tsx scripts/spike-audit.ts <url>`	Verifica le 264 voci di checklist con Sonnet 5, poi sintetizza con Opus 5. Volutamente isolato da `src/`: non importa nulla, non tocca il DB	«Cosa c'e' che non va, in parole?»

Opzioni comuni: --profilo=servizi|ecommerce, --no-psi (salta PageSpeed, che da solo vale meta' del tempo). Riferimento misurato il 2026-08-26 su giojello.com: cinque fonti su cinque, 42,7 s in tutto, PageSpeed 34,2 s. Se una fonte tace, quella e' la notizia — va riportata, non aggirata.

PAGESPEED_API_KEY viene letta dall'ambiente o da .env.local. Senza, PageSpeed e CrUX rispondono a vuoto senza errore: lo script lo dice in testa, leggerlo.

Il grezzo finisce in audit-fonti-<dominio>.json (gitignorato). E' li' che ogni numero del documento dovra' essere rintracciabile.

Le tre regole che il motore erediterà

Non sono preferenze. Sono gia' costate, e stanno per esteso in STATUS.md § Lezioni operative.

Un numero entra solo se e' stato misurato. Rintracciabile nel grezzo, e nel motore in audit_runs.raw. Nessun numero dedotto, arrotondato o ricordato.
Laboratorio e campo non si fondono — la differenza e' il risultato. Su giojello.com Lighthouse dava server-response-time 7 ms e CrUX TTFB p75 3.553 ms con l'1% nel verde: il server risponde in fretta al datacenter Google e lento a tutti gli altri. Due numeri con lo stesso nome verrebbero fusi in uno solo — per questo il campo si chiama risposta_server_ms e non ttfb_ms.
Un punteggio va sempre con la sua data. Performance mobile 52, poi 64 sullo stesso sito mezz'ora dopo. Mai presentato come una costante del sito.

E una regola di metodo che vale per ogni fonte nuova: ogni estrazione da un'API di terzi va vista funzionare, non dedotta dai docs. Scrivendo sources/, due estrazioni prese dalla documentazione hanno restituito valori vuoti senza errore — largest-contentful-paint-element non esiste piu' e configSettings.screenEmulation non esiste affatto nelle risposte pubbliche. Trovate solo perche' le fonti sono state fatte girare su un sito vero.

Perche' niente browser headless

Misurato il 2026-08-17 sul VPS: 1,5 GB di RAM liberi su 3,8, Chromium ne prende 500 MB–1 GB → OOM kill sui servizi con dati reali. Verificato il 2026-08-18 che non serve comunque: 153 voci si verificano sul DOM renderizzato che PageSpeed restituisce, e lo screenshot buono e' final-screenshot, non fullPageScreenshot.

Lo stato di v2.5, per non ripartire dal posto sbagliato

In pausa dal 2026-08-19 per scelta: prima le modifiche all'hub, poi il motore.

Pezzo	Dove	Stato
Schema, 7 tabelle + rubrica 264 voci	`0017_audits.sql`, `checklist_items`	in produzione
Le cinque fonti	`src/lib/audit/sources/`	in prod ma inerti: nessuna route le chiama
Agent, sintetizzatore, pipeline, editor, pagina	`src/lib/audit/`, `src/app/{admin/audit,audit}`	da scrivere

I piani stanno in ../../plans/: v2.5-audit-documento.md (i tre livelli Radiografia / Prima-Dopo / Rotta come configurazioni di un unico documento) e v2.5-audit-motore.md (raccolta in parallelo → quattro sub-agent → sintetizzatore che incrocia le osservazioni in massimo 10 finding).

L'agente, quando lo progetteremo

Va in .claude/agents/audit-*.md, non qui. Non esiste ancora e non va abbozzato: il design dei quattro sub-agent cambiera' scrivendo il motore. Quando nascera' eredita le tre regole qui sopra — sono il perimetro, non il contorno.

4.4 KiB Raw Blame History Unescape Escape