docs(planning): archivia v2.1/v2.2/v2.3 e documenta v2.4

.planning/ documentava in dettaglio cio che era vecchio e per niente cio
che e in produzione: le fasi 11-22 (v2.1 e v2.2, chiuse a giugno) erano
ancora in phases/ mentre v1.0 e v2.0 stavano gia in milestones/, e il
lavoro degli ultimi due mesi - gate OTP e ciclo di vita dei retainer, cioe
quello che gira su hub.iamcavalli.net - non aveva nessuna cartella.

- phases/{11,12,14} -> milestones/v2.1-phases/, phases/{18..22} ->
  milestones/v2.2-phases/. Ora phases/ contiene solo la milestone in
  corso, che e quello che state.cjs conta per il progresso
- v2.1-ROADMAP.md ricostruito: era l'unica milestone senza archivio,
  interrotta dal reset del 19/06 e mai chiusa formalmente
- v2.3-ROADMAP.md + v2.3-REQUIREMENTS.md: v2.3 e stata eseguita fuori dal
  ciclo GSD, non esistono PLAN/SUMMARY per fase. L'archivio E la doc
- REQUIREMENTS.md riscritto per v2.4 con il backlog reale
- phases/13 e phases/26: SUMMARY ricostruiti da commit, migration e
  STATUS.md. 26 e il primo numero libero
- research/: cancellate 4 varianti dello stesso PITFALLS e FEATURES/
  SUMMARY, superati da PROJECT.md. Diverse anti-feature erano ormai
  contraddette dai fatti (il Kanban e stato costruito in Phase 19,
  l'email in v2.3, il time tracking esiste)
- cancellati UI-RULES.md e DESIGN-SYSTEM.md (CLAUDE.md li dichiara
  superseded: impongono l'inverso della regola attuale) e HANDOFF.md,
  fermo al 13/06
- SECURITY-*.md -> security/: audit chiuso, ma i report restano la doc di
  cosa e stato ruotato e perche
- PROJECT.md/MILESTONES.md/ROADMAP.md allineati: milestone corrente v2.4,
  sessione OTP 90gg non 30, migrazioni fino alla 0016

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

.planning/REQUIREMENTS.md

@@ -1,69 +1,47 @@
-# Requirements: ClientHub v2.3 Email & Accesso
+# Requirements: ClientHub v2.4 Post-vendita
 
-**Defined:** 2026-06-21
+**Definiti:** 2026-08-08 (ricostruiti a posteriori — v2.4 è partita senza requisiti scritti)
 **Core Value:** Il cliente apre il link e vede esattamente a che punto è il suo progetto, cosa deve ancora succedere e cosa ha già approvato — senza dover scrivere email per chiedere aggiornamenti.
 
-## v2.3 Requirements
+Milestone precedente: [v2.3 Email & Accesso](milestones/v2.3-ROADMAP.md), shipped 2026-07-29.
 
-### Email OTP Gate (AUTH-OTP-01)
+## Consegnati
 
-Portale cliente blindato da email OTP. Nuovo `client_emails` table (whitelist) + `otp_codes` table (codice, email, expires_at, consumed). Resend come provider email. Sessione **90 giorni** con cookie dopo verifica, revocabile dall'admin.
+### Ciclo di vita dei servizi ricorrenti (Phase 13) — ✅ in produzione 2026-08-01
 
-- [x] **OTP-01**: Admin può aggiungere e rimuovere email dalla whitelist di ogni cliente nell'admin UI
-- [x] **OTP-02**: Cliente senza sessione OTP vede una schermata "inserisci email" invece della dashboard
-- [x] **OTP-03**: Sistema invia OTP via Resend solo se l'email inserita è nella whitelist di quel cliente
-- [x] **OTP-04**: Cliente inserisce il codice OTP ricevuto e ottiene sessione autenticata (cookie **90 giorni**)
-- [x] **OTP-05**: Codici OTP scadono dopo 15 minuti dall'invio
-- [x] **OTP-06**: Endpoint OTP è rate-limited per prevenire brute force
-- [x] **OTP-07**: Messaggi di errore OTP non rivelano se l'email è in whitelist o no (no enumeration)
-- [x] **OTP-08**: Admin può revocare in blocco tutte le sessioni attive di un cliente
+- [x] **RET-01**: Un'offerta ricorrente assegnata a un progetto ha uno stato (attivo / sospeso / cessato) e una data di fine opzionale
+- [x] **RET-02**: L'admin può sospendere, riattivare e cessare un retainer dalla tab Offerte del progetto
+- [x] **RET-03**: Il forecast a 12 mesi smette di sommare un retainer sospeso, cessato o oltre la sua `end_date`
+- [x] **RET-04**: Lo storico del venduto (`getOffersSoldBreakdown`) **non** filtra per stato — escludere le cessate riscriverebbe il passato
+- [x] **RET-05**: Il cliente vede stato, "attivo dal / fino al" e "canone mensile"; le offerte cessate non gli arrivano
 
-> **[2026-07-28] Modifiche alla spec del 2026-06-21**, decise in sessione:
-> - Sessione **90 giorni** invece di 30 (rientro più fluido), compensata da OTP-08.
-> - **SEND-01/SEND-02 spostati al backlog v2.4**: il preventivo si invia a mano, l'automazione non serve ora. Phase 23 si è ridotta alla sola infrastruttura Resend, che l'OTP usa comunque.
-> - **Il gate NON sta nel layout** ma in cima a ogni page sotto `/client/[token]/`. Nell'App Router il segmento `page` viene renderizzato in parallelo al layout: gattare nel layout nascondeva la dashboard a schermo ma lasciava fasi, task e pagamenti nel payload RSC dell'HTML (verificato: 46.907 byte con i dati → 17.594 dopo il fix). Helper: `src/lib/client-gate.ts`.
+### Anteprima admin e login (Phase 26) — ✅ in produzione 2026-08-08
 
-## v2.4+ Backlog
+- [x] **PREV-01**: L'admin può aprire il portale di un cliente in sola lettura senza passare dal gate OTP (`?preview=1` + sessione Auth.js valida)
+- [x] **PREV-02**: In anteprima approvazione e composer messaggi sono disattivati a livello di UI
+- [x] **AUTH-09**: Il campo password del login admin ha un toggle mostra/nascondi
 
-### Conversione Commerciale
+## Backlog v2.4+ (non pianificati)
 
-- **PROP-03**: Stripe Payment Link su deck pubblico `/preventivo/[slug]`
-- **PROP-04**: Auto-provisioning cliente/progetto/fasi al "Vinto" nel CRM
-- **SEND-01/SEND-02**: invio del link `/preventivo/[slug]` via email dall'admin UI — *rinviato da v2.3 il 2026-07-28, l'invio si fa a mano. L'infrastruttura Resend (`src/lib/mailer.ts`) è già pronta, manca solo l'azione e il pulsante.*
+Ereditati dalle chiusure di milestone precedenti, nessuno in corso:
 
-### Post-Vendita
+- [ ] **SEND-01 / SEND-02** — Invio del link `/preventivo/[slug]` via email dall'admin. Il mailer (`src/lib/mailer.ts`) è già pronto e in produzione dalla v2.3: manca solo il pulsante e l'action. *Rinviati il 2026-07-28.*
+- [ ] **PROP-03** — Stripe Payment Link sul deck pubblico del preventivo. *Rinviato al kickoff v2.3.*
+- [ ] **PROP-04** — Auto-provisioning di cliente / progetto / fasi al passaggio del lead a "Vinto". *Rinviato al kickoff v2.3.*
+- [ ] **RET-06** — Canoni mensili tracciabili (agosto pagato / settembre no). **Serve una tabella nuova**: `payments` è protetta dai vincoli di Data Safety e la sua riscalatura è pensata per i piani una tantum. *Fuori scope di Phase 13.*
+- [ ] **OFFER-14** — Sezioni analitiche stile Notion sull'offerta. *Rinviato al kickoff v2.1.*
+- [ ] **ARCH-01** — Split del modulo "compartimento stagno" in un deploy separato. *Solo se il modulo cresce.*
+- [ ] **DEBT-01** — Debito design: **~40 file, ~450 occorrenze** di palette Tailwind raw e hex literal al posto dei token semantici. I cluster: `/admin/projects/[id]` e i suoi tab (~182), `/admin/offers/[id]/edit` (~79), `/admin/clients/[id]` (~59), tutto `/quote/[token]` (~48, ed è rivolto al cliente), `ChatPanel` del portale (37), più `ui/dialog.tsx` che propaga il look vecchio a ogni modale. Esclusi perché legittimi: `AdminSidebar` (eccezione brand documentata), `src/lib/mailer.ts` (HTML email, niente CSS var), i colori di stato di `StatusBadge` (sanzionati dal design system, hanno già le varianti `dark:`). *Misurato il 2026-08-08 — la stima precedente di "11 pagine" era sottostimata.*
+- [ ] **DEBT-02** — Tabelle legacy `service_catalog` / `offer_services` / `offer_micro_services` come deadweight; `createService` / `serviceSchema` dead code in `src/app/admin/catalog/actions.ts`.
 
-- **Phase 13**: Gestione servizi attivi/ricorrenti post-vendita nel portale cliente (congelata da v2.1)
+## Aperto, non un requisito
 
-## Out of Scope
+**Whitelist del portale vuota per 3 clienti su 4.** La migration 0015 ha seedato solo
+`mario@test.it` (cliente di test). Protocollo Estetico, Caruso Speaker e Teckell hanno
+whitelist vuota e finché lo è **il loro portale non è accessibile**. Si popola da
+`/admin/clients/<id>` → "Accessi al portale", poi va reinviato il link.
 
-| Feature | Reason |
-|---------|--------|
-| Self-registration cliente | Solo whitelist admin-gestita — nessun accesso senza approvazione esplicita |
-| Magic link senza OTP | OTP è più sicuro e già deciso come design; magic link = scope creep |
-| Email marketing / newsletter | Non pertinente al portale |
-| Multi-admin | Ancora single admin per ora |
+## Fuori scope
 
-## Traceability
-
-| Requirement | Phase | Status |
-|-------------|-------|--------|
-| OTP-01 | Phase 24 | ✅ Done (2026-07-28) |
-| OTP-02 | Phase 25 | ✅ Done (2026-07-28) |
-| OTP-03 | Phase 25 | ✅ Done (2026-07-28) |
-| OTP-04 | Phase 25 | ✅ Done (2026-07-28) |
-| OTP-05 | Phase 25 | ✅ Done (2026-07-28) |
-| OTP-06 | Phase 25 | ✅ Done (2026-07-28) |
-| OTP-07 | Phase 25 | ✅ Done (2026-07-28) |
-| OTP-08 | Phase 24 | ✅ Done (2026-07-28) |
-| SEND-01 | — | ⏭️ Rinviato a v2.4 |
-| SEND-02 | — | ⏭️ Rinviato a v2.4 |
-
-**Coverage:**
-- v2.3 requirements: 8 in scope (OTP-01…08) + 2 rinviati
-- Implementati: 8/8 ✓ — verificati con 9 test E2E in locale contro il DB di produzione
-- **Non ancora in produzione**: il codice è scritto e testato ma NON pushato. Vedi i blocchi in `STATE.md`.
-
----
-*Requirements defined: 2026-06-21*
-*Last updated: 2026-07-28 — sessione 90gg, OTP-08 aggiunto, SEND-01/02 rinviati, OTP-01…08 implementati*
+- File hosting (vincolo LOCKED #5: i documenti restano URL esterni).
+- Tabella utenti / multi-admin: l'auth resta una singola credenziale da env.