Come si lavora su CATPIT

Questa skill non descrive com'e' fatto CATPIT: quello sta in
Agente Residente openclaw\catpit\CONTEXT_FOR_AGENTS.md (mappa delle stanze, dove stanno i
dati, come parte un agente, file chiave). Leggilo prima, sempre.

Qui ci sono le regole di metodo: cosa si verifica, come si consegna, e le trappole che
abbiamo gia' pagato almeno una volta. Se una di queste regole viene saltata, un difetto gia'
corretto ricompare — e' successo.

0. Coordinate minime

1. Prima di toccare il codice: nomina la causa

Non partire dal fix. Prima si riproduce il difetto e si dice qual e' la causa, con la prova.
Un fix applicato a una causa immaginata non chiude niente e maschera quella vera.

Se la causa non e' quella che diceva il brief, dillo. E' successo il 2026-08-09: il brief
parlava di bottoni tagliati fuori schermo, la causa vera era il contrasto del bottone. Aver
nominato la differenza ha risparmiato un intervento inutile sul layout.

2. Le prove si fanno sul vivo, non nei test

I test verdi non sono una verifica: dicono che il codice fa quello che il test si aspetta.
La verifica e' sul server acceso:

• la rotta risponde 200;
• la stringa attesa e' nel markup vivo (non "il componente la renderizza");
• la prova negativa: quello che deve essere rifiutato viene davvero rifiutato, con lo stato HTTP giusto, e senza mutare niente (ricontrolla il dato dopo il rifiuto).

Un rifiuto a meta' che lascia in giro una riga nata per sbaglio e' peggio di un fallimento
pulito: valida tutto prima di scrivere, mai a meta' strada.

3. Il mobile non si giudica a occhio su uno screenshot

⚠️ Chrome headless su questa macchina clampa il viewport a 500px. Se chiedi
--window-size=390, il layout viene renderizzato a 500 e il PNG viene ritagliato a 390:
tutto cio' che e' allineato a destra sembra fuori schermo e non lo e'.
Misure verificate: 390 → innerWidth 500, 430 → 500, 600 → 584.

Quindi:

• mobile mai con --window-size. Usa l'emulazione device (CDP Emulation.setDeviceMetricsOverride, mobile: true) — vedi scripts/gate-mobile.mjs;
• si giudica a numeri: document.scrollWidth === document.clientWidth e getBoundingClientRect().right <= innerWidth. Mai a occhio sul PNG;
• per gli screenshot desktop, larghezza ≥ 500;
• se la pagina carica dati lato client, --virtual-time-budget, altrimenti scatti il vuoto.

Scheda completa: materiale condiviso\KB_Fix_Tecnici\FIX_chrome-headless_larghezza-minima-500.md.
(Nota: CONTEXT_FOR_AGENTS.md §5 consiglia lo screenshot headless senza questo avvertimento —
qui vale questa regola.)

4. Leggibilita': e' una richiesta aperta, non un dettaglio

Richiesta di Ettore del 02/08, ancora aperta: **su fondo scuro tutte le scritte devono essere
luminose**, vicine alla resa del titolo "MISSION CONTROL". Testi secondari grigi che si perdono
sono un difetto, non uno stile.

Caso reale: il bottone «modifica» del Quaderno era border-line/text-faint a 11px — Ettore
ha creduto che la scheda fosse in sola lettura e ha segnalato un bug che non esisteva.
Un comando che sembra disattivato e' un comando rotto.

Fai girare npm run contrasto su quello che tocchi e non aggiungere testo sotto la soglia.

5. Modello dati: riferimenti, mai copie

Lo stato di una cosa vive in un posto solo:

• task → attivita.csv
• richieste e bisogni → richieste.json
• voci del Quaderno → RICHIESTE\indice.json + i .md

Le stanze leggono e mostrano; non ricopiano. Ogni copia diventa una seconda verita' entro
una settimana: e' gia' successo col registro Riferimenti.

Se una stanza deve mostrare un task, prende l'id e rilegge il CSV. Se l'id non esiste,
lo dichiara a schermo — non lo nasconde.

6. Fail-closed a whitelist

Le regole di permesso si scrivono al contrario: non si elenca cio' che e' vietato, si
elenca cio' che e' permesso. Un valore sconosciuto ricade nel caso piu' restrittivo.

Esempio vivo: eModificabile() in lib/quaderno.ts — un tipo che la libreria non conosce
viene trattato come sorgente, quindi sola lettura. E' cio' che protegge
RICHIESTA_02_08_2026.md, che e' copia unica di un brainstorm senza archivio di sessione.

Conseguenza operativa, importante: se introduci un tipo nuovo (es. checkpoint), la
whitelist va aggiornata prima che il dato lo usi, nello stesso commit. Se cambia prima
il dato, quelle voci diventano non modificabili in silenzio e nessuno se ne accorge.

Il divieto sta nella libreria, non nel componente: togliere un bottone non e' una regola.

7. Scritture sul vault

• .bak a ogni scrittura; snapshot datato in _storico\ prima di modificare un .md;
• nomi di file che arrivano da un indice passano da path.basename (niente traversal);
• schema del vault e openclaw.json → conferma di Ettore, sempre;
• agents_registry.json → conferma di Ettore;
• se cambia la struttura delle cartelle → aggiorna 00_MAPPA_CARTELLE.md.

8. Trappole delle API interne

• `/api/tasks` action `update` legge il campo `data`, non `patch`. Passando patch la risposta e' {"ok":true} ma non cambia niente: un no-op silenzioso. Dopo ogni scrittura via API, rileggi il dato su disco e verifica che sia cambiato davvero.
• /api/richieste action add: se non passi destinatario, per la corsia agente_a_ettore resta il default e finisce sbagliato. Passalo esplicito.
• modifica funziona sulla corsia bisogni (b###), non sulle richieste q###.
• Le risposte alle richieste passano solo da /api/richieste: nessun'altra rotta scrive su richieste.json.

9. Testi dentro CATPIT: corti, o non li legge nessuno

Regola di casa (SOUL.md, dal 2026-08-15): richieste, task e sottotask si scrivono con
due o tre righe di contesto, ogni opzione una riga piu' una riga di conseguenza,
raccomandazione in una frase. Se un testo supera il mezzo schermo, il posto giusto non e'
la scheda ma un documento collegato.

Vale anche per i campi: prossima_azione e' una riga che dice cosa si fa dopo. Il verbale
di un giro autonomo non va li' dentro — e' il difetto che ha reso le pagine dei task
illeggibili ad agosto.

10. Protocollo di consegna

1. npm run test verde, npm run build ok.
2. Avvisa Romeo PRIMA di riavviare la 3010. Ettore potrebbe essere dentro il riquadro sessione a rispondere: un riavvio nel momento sbagliato gli perde la risposta.
3. Dopo la build riavvia il server, o gli asset danno 500 (HTML senza stile). Rilancio in processo staccato via cmd, non Start-Process npm.
4. Verifica sul vivo (§2) + gate mobile e contrasto sulle rotte toccate.
5. Commit piccoli con messaggio parlante catpit: ... su master.
6. Report in #archimede-build con screenshot e prove negative, non solo l'elenco di cosa hai scritto.
7. Se hai deviato dal brief o preso una decisione non richiesta, dillo nel report, punto per punto.

11. Onesta' delle fonti

Non citare la propria memoria di sessione come se fosse un documento condiviso. Se una scheda
KB "esiste", deve esistere sul disco: verificalo prima di citarla. Se la conoscenza e' solo
tua, scrivi la scheda — altrimenti muore con la sessione.

Vale anche per i numeri: se dici "verificato", dev'esserci la misura, non l'impressione.

12. Costi

Gli avvii reali di agenti costano token: mai avvii automatici senza un'azione esplicita di
Ettore (spunta «VOGLIO LANCIARE» o job che ha programmato lui).

Checklist rapida prima di dire "fatto"

• [ ] causa nominata, non solo fix applicato
• [ ] test verdi e verifica sul server vivo (markup, non componente)
• [ ] prova negativa fatta, e il dato non e' mutato dopo il rifiuto
• [ ] gate mobile con emulazione device (mai --window-size sotto 500)
• [ ] contrasto: nessun comando che sembra disattivato
• [ ] nessuna copia di stato: solo riferimenti alla fonte
• [ ] whitelist aggiornata prima del dato, se hai introdotto un tipo nuovo
• [ ] .bak su ogni scrittura nel vault
• [ ] Romeo avvisato prima del riavvio della 3010
• [ ] build + riavvio fatti, rotta 200
• [ ] report con screenshot, prove negative e deviazioni dichiarate