catpit-dev — lavorare sull'app che tiene i dati di tutti

CATPIT non è un'app qualsiasi: dal 2026-07-01 è il master dei dati strutturati su progetti
e task. Se rompi lo store, rompi la fonte-verità del sistema, non una pagina.

Usa questa skill prima di toccare catpit/, e per ogni rilascio.

1. Dov'è cosa

catpit/                      app Next.js (App Router)
  app/                       pagine: tasks, projects, richieste, crew, office, sessions, docs...
  app/api/                   route server-only: tasks, projects, subtasks, richieste,
                             sessions, skills, artefatti, crew, cron, usage, github
  lib/                       la logica vera (store, richieste, subtasks, csv, locks,
                             vault-schema, security, launch, wake...)
  tests/                     24 file vitest
CATPIT_vault/                lo STORE: i dati veri, fuori dall'app

Porta 3010 = CATPIT (next dev / next start). La 3000 è Metabase (Docker): non usarla
mai per verificare una rotta — risponderebbe qualcos'altro e crederesti di aver verificato.

2. Il contratto dello store (la parte da non violare)

I file del vault e le loro colonne, come le scrive lib/store.ts:

Regole strutturali, tutte già implementate — non aggirarle, non reimplementarle a lato:

1. Backup `.bak` a ogni scrittura. writeTable copia il file su <file>.bak prima di riscriverlo. Chi scrive fuori da lib/store.ts salta il backup.
2. Soft-delete, mai `DELETE` vero. La colonna archiviato vale "1" o "". Archiviare un progetto archivia a cascata i suoi task.
3. Un solo mutex sulle mutazioni CSV (withLock("store:vault-csv", …)): progetti e attività condividono la chiave perché una singola operazione può scrivere entrambi i file.
4. Gli id li genera lo store (nextId: p##, a##). Non inventarli a mano.
5. EOL preservato: si rilegge il file per capire se usa CRLF o LF. Non normalizzare.
6. Schema validato al parse (lib/vault-schema.ts): file assente = vault vuoto legittimo; file presente con colonne mancanti = VaultSchemaError subito, invece di garbage a valle.

Le API di scrittura

POST /api/tasks con {action, id?, data} — action: `create | update | detail | archive |
restore. Solo POST: un GET` risponde 405, per leggere si leggono i file.
Stesso schema per /api/projects e /api/subtasks.

Lo stato "Bloccato su Ettore" è gestito dall'API delle richieste, non dall'UI e non a mano:
lo mette sui task citati da una richiesta aperta e lo toglie alla risposta. Non scavalcarlo.

3. Verificare prima di committare

La test suite esiste ed è la rete di sicurezza principale:

cd "C:\Users\Ettore\Claude\Agente Residente openclaw\catpit"
npm test        # vitest run — 24 file, 343 test (stato al 2026-08-02, tutti verdi in ~6s)

Regole:

• Gira la suite prima e dopo ogni modifica: "prima" ti dice se eri già rotto, "dopo" se hai rotto tu. Una modifica che lascia la suite rossa non si committa.
• Se tocchi lib/, il test corrispondente esiste quasi sempre (store.test.ts, richieste.test.ts — 33 KB, subtasks.test.ts, security.test.ts, vault-schema.test.ts). Aggiornalo insieme al codice, non "dopo".
• I test che toccano il vault devono lavorare su file temporanei. Non far girare test contro CATPIT_vault/ vero.
• I percorsi positivi delle rotte con dipendenza esterna (webhook, copie su disco) restano verificati a mano: è un rischio dichiarato in CATPIT_HARDENING.md, non una svista.

4. Rilascio — la procedura che è già costata un incidente

cd "C:\Users\Ettore\Claude\Agente Residente openclaw\catpit"
npm test                     # 1. verde, altrimenti fermati qui
npm run build                # 2. next build
# 3. RIAVVIA il processo sulla 3010  <-- il passo che si dimentica
# 4. smoke test delle rotte principali
# 5. commit su master

Il passo 3 non è opzionale. Dopo un next build, il processo next start già in esecuzione
serve asset vecchi: la pagina arriva come HTML senza stile e gli asset danno 500. Sembra un
bug di CSS, è un processo da riavviare. Rilancia detached via `cmd`, non con
Start-Process npm (che si porta dietro la shell e muore con la sessione).

Smoke test minimo dopo il riavvio — non fidarti di una sola pagina:

foreach ($p in @("/", "/tasks", "/richieste", "/projects")) {
  (Invoke-WebRequest "http://127.0.0.1:3010$p" -UseBasicParsing).StatusCode
}

Il trunk del repo è `master`, non `main`. Un push su main non arriva dove pensi.

5. Checklist "cosa non rompere"

• POST /api/richieste — ci scrivono tutti e tre gli agenti dai loop; cambiare i campi significa rompere richieste già in coda. Il contratto di scrittura sta in CATPIT_vault\COME_SI_SCRIVE_UNA_RICHIESTA.md ed è retrocompatibile per scelta: i campi nuovi si aggiungono opzionali, non si rinominano quelli vecchi.
• /hooks/wake e la rotta di lancio task (app/api/tasks/launch) — è il bottone "Avvia" che sveglia un agente. Va provato davvero, non solo compilato.
• Lo stato "Bloccato su Ettore" gestito dall'API (§2).
• Il backup .bak: se una tua modifica scrive nel vault senza passare da lib/store.ts, hai tolto la rete a tutti.

6. Coordinamento

CATPIT è condiviso: quando ci lavori, **la cartella catpit/ è tua e gli altri agenti stanno
fuori** finché non chiudi i task in carico. Simmetricamente: se un altro agente ha task aperti
su catpit/, non entrarci — i conflitti di merge su un'app Next.js costano più del lavoro.
Dichiaralo nella prossima_azione del task, che è dove gli altri guardano.