From f0e9fcfba5f3746d535dde73025b152045aee140 Mon Sep 17 00:00:00 2001 From: Davide Grilli Date: Thu, 15 Oct 2026 12:19:12 +0200 Subject: [PATCH] Documentazione: stato del progetto (stadio MVP) Aggiunge docs/PROJECT_STATE.md: stadio MVP, stato per area, criteri di accettazione con verifica manuale e automatica, debiti noti (soprattutto i test), tabella degli ADR e proposta di cosa manca per chiudere l'MVP. Collegato da indice dei doc, README, ROADMAP e CLAUDE.md, che chiede di aggiornarlo a ogni cambio di stadio, funzione, ADR o debito. Co-Authored-By: Claude Sonnet 5.5 --- CLAUDE.md | 2 +- README.md | 2 ++ docs/PROJECT_STATE.md | 56 +++++++++++++++++++++++++++++++++++++++++++ docs/README.md | 3 ++- docs/ROADMAP.md | 2 +- 5 files changed, 62 insertions(+), 3 deletions(-) create mode 100644 docs/PROJECT_STATE.md diff --git a/CLAUDE.md b/CLAUDE.md index ebb282d..6b3f7e9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -8,7 +8,7 @@ agent-wiki-ui (già `LlmRun`; il nome ha un'unica sorgente, vedi [docs/README.md ## Workflow doc-first (obbligatorio) -- Specifica e criteri di accettazione: [docs/MVP.md](docs/MVP.md). Fasi e stato: [docs/ROADMAP.md](docs/ROADMAP.md). Indice dei doc e regole (SSOT, ADR): [docs/README.md](docs/README.md); una decisione architetturale si scrive solo nel suo ADR, gli altri doc la richiamano con un link. Uso: [README.md](README.md). +- Stato attuale, stadio (MVP), debiti e cosa manca: [docs/PROJECT_STATE.md](docs/PROJECT_STATE.md); aggiornarlo nello stesso commit di ogni cambio di stadio, funzione, ADR o debito. Specifica e criteri di accettazione: [docs/MVP.md](docs/MVP.md). Fasi e stato: [docs/ROADMAP.md](docs/ROADMAP.md). Indice dei doc e regole (SSOT, ADR): [docs/README.md](docs/README.md); una decisione architetturale si scrive solo nel suo ADR, gli altri doc la richiamano con un link. Uso: [README.md](README.md). - **Test obbligatori** ([docs/TESTING.md](docs/TESTING.md), [ADR-0003](docs/adr/0003-strategia-di-test.md)): ogni nuova funzione, correzione o cambio di comportamento va coperta da test nello stesso commit; prima si aggiunge la riga (con ID) alla matrice in TESTING.md, poi i test, poi il codice. Un bug si corregge partendo da un test che fallisce. - Ad ogni richiesta di modifica: aggiornare prima i doc interessati (MVP.md, ROADMAP.md con le spunte, README.md se cambia l'uso; un nuovo ADR in `docs/adr/` per ogni scelta architetturale), poi il codice, poi questo file se cambiano comandi, design o vincoli. Nessuna modifica deve lasciare i doc disallineati. diff --git a/README.md b/README.md index 6c4c420..58ae372 100644 --- a/README.md +++ b/README.md @@ -64,4 +64,6 @@ Verificato: da Linux/WSL entrambi gli eseguibili; da Windows nativo (PowerShell ## Piattaforme Windows e Linux con lo stesso codice ([ADR-0001](docs/adr/0001-gui-multipiattaforma-avalonia.md)). Motori supportati: Claude Code e Codex CLI, già installati da terminale; Antigravity CLI è pianificato: [ADR-0002](docs/adr/0002-motori-cli-claude-codex-antigravity.md). +> **Stato: MVP** (prima della 1.0): la parte funzionale c'è, i test automatici e alcune verifiche su macchine reali mancano. Dettagli in [docs/PROJECT_STATE.md](docs/PROJECT_STATE.md). + Documentazione: [docs/README.md](docs/README.md) (indice, regole, decisioni), [docs/MVP.md](docs/MVP.md), [docs/ROADMAP.md](docs/ROADMAP.md). diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md new file mode 100644 index 0000000..4d219cb --- /dev/null +++ b/docs/PROJECT_STATE.md @@ -0,0 +1,56 @@ +# Stato del progetto + +> **Stadio: MVP** (prima di una versione 1.0). Ultimo aggiornamento: 2026-10-15. +> Questo documento è la fotografia dello stato, non la fonte di dettagli: i passi sono in [ROADMAP.md](ROADMAP.md), i requisiti in [MVP.md](MVP.md), le decisioni negli ADR (indice in [README.md](README.md)), i test in [TESTING.md](TESTING.md). Qui si legge a colpo d'occhio dove siamo; per il resto si segue il collegamento. + +## In una frase +`agent-wiki-ui` è un eseguibile C# (.NET 10) per Windows e Linux che inoltra prompt a Claude Code e Codex già installati, da riga di comando o da una GUI di chat. La parte funzionale dell'MVP c'è; mancano i test automatici e alcune verifiche su macchine reali. + +## Stato per area +| Area | Stato | Note | +|---|---|---| +| CLI (`agent-wiki-ui "prompt"`, `--engine`) | Funzionante | Exit code e 127 provati su Linux; su Windows l'exit code arriva solo se il chiamante attende il processo ([ADR-0005](adr/0005-windows-senza-console.md)). | +| GUI di chat (Avalonia) | Funzionante | Barra laterale, cronologia su disco, markdown, tema chiaro/scuro, Impostazioni. Provata con screenshot headless e su WSLg; non su Windows nativo. | +| Motori | Claude Code e Codex | Una chat = un motore; sessione di Codex letta dall'output. Antigravity non iniziato ([ADR-0002](adr/0002-motori-cli-claude-codex-antigravity.md)). | +| Aggiornamento dei CLI | Funzionante, non provato in reale | Controllo preventivo e pulsante evidenziato; l'`update` vero non è mai stato lanciato dall'app ([ADR-0004](adr/0004-aggiornamento-dei-cli.md)). | +| Eseguibili standalone | Funzionanti | `win-x64` e `linux-x64` creati da entrambi i sistemi con `scripts/publish.sh` / `.ps1` (circa 47 MB). Windows senza console al doppio clic. | +| Test automatici | **Non iniziati** | Piano e matrice pronti ([ADR-0003](adr/0003-strategia-di-test.md)); nessun test scritto. Vedi debiti. | +| Documentazione | Allineata al codice | Doc-first; ogni funzione ha le righe della matrice in TESTING.md. | + +## Criteri di accettazione dell'MVP +Da [MVP.md](MVP.md). Restano non spuntati finché non hanno test automatici (regola di [TESTING.md](TESTING.md)). + +| Criterio | Verifica a mano | Test automatico | +|---|---|---| +| `claude` parte nella cartella dell'exe | Sì: Linux e Windows (da `C:\Windows` il motore vede la cartella dell'exe) | No (CL-04) | +| Output in streaming nella CLI | Output ereditato dal motore; non misurato | No (CL-08) | +| Exit code propagato | Linux sì; Windows solo con attesa del processo | No (CL-06) | +| Prompt con virgolette e spazi intatto | Sì, con un `claude` finto su Linux | No (CL-01) | + +## Debiti noti +- **Test automatici assenti** (Fase 6): contraddice la regola "nuova funzione = nuovi test" per tutto il codice scritto finora. È il debito principale. +- **Verifiche su macchine reali**: GUI su Windows nativo e su una distribuzione Linux pulita; doppio clic senza console e riaggancio al terminale (ADR-0005); tema che segue il sistema su Linux; `update` reale dei CLI. +- **Impostazioni non salvate su disco**: modello, effort e motore tornano ai valori iniziali a ogni avvio (si parte dal modello più piccolo con effort `low`). +- **Nessuno streaming nella GUI**: la risposta compare a fine generazione. +- **Elenchi dei modelli fissi** (Claude Code e Codex): da aggiornare a mano; il "modello più piccolo" di Codex è un'assunzione (GPT-5.6 Luna). + +## Decisioni +| ADR | Stato | +|---|---| +| [0001](adr/0001-gui-multipiattaforma-avalonia.md) GUI Avalonia multipiattaforma | Accettata | +| [0002](adr/0002-motori-cli-claude-codex-antigravity.md) Più motori CLI | Accettata (Claude Code, Codex) | +| [0003](adr/0003-strategia-di-test.md) Strategia di test | Proposta | +| [0004](adr/0004-aggiornamento-dei-cli.md) Aggiornamento dei CLI | Proposta | +| [0005](adr/0005-windows-senza-console.md) Windows senza console | Proposta | + +## Per chiudere l'MVP +Proposta, derivata dai punti aperti sopra; da confermare. +1. Test automatici per `Core/` e `MainViewModel` e per i quattro criteri di accettazione (Fase 6, prime righe di CL, ST, VM, CX). +2. Gli ADR 0003, 0004 e 0005 passati ad "Accettata" dopo le loro verifiche. +3. GUI provata su Windows nativo e su Linux pulito. +4. Criteri di accettazione di MVP.md spuntati. + +Oltre l'MVP (non bloccanti): Antigravity, impostazioni persistite, streaming nella GUI, rinomina e ricerca delle chat, CI con matrice Windows e Linux, firma dell'eseguibile Windows. + +## Come tenere aggiornato questo file +Si aggiorna nello stesso commit di ogni cambio di stadio, di funzione, di ADR o di debito: stato per area, criteri, debiti, tabella delle decisioni, data. Se una riga qui contraddice ROADMAP.md o un ADR, vale quello e questa pagina va corretta. diff --git a/docs/README.md b/docs/README.md index ce6e8a7..c394aad 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,6 +5,7 @@ Indice e regole. Ogni informazione vive in **un solo documento**; gli altri la r | Documento | Contenuto (sorgente di verità per…) | |---|---| | [../README.md](../README.md) | Uso, requisiti, build e publish | +| [PROJECT_STATE.md](PROJECT_STATE.md) | Stato del progetto a colpo d'occhio: stadio (MVP), stato per area, debiti, decisioni, cosa manca per chiudere l'MVP | | [MVP.md](MVP.md) | Specifica funzionale, design UI/UX, criteri di accettazione | | [INSTALL.md](INSTALL.md) | Come installare e autenticare i motori (Claude Code, Codex), verifica e problemi comuni | | [TESTING.md](TESTING.md) | Piano dei test: regola "nuova funzione = nuovi test", soglie di copertura, matrice requisito → test | @@ -22,7 +23,7 @@ Se il nome cambia di nuovo, aggiornare solo questi punti: - [ ] Titolo di [../README.md](../README.md) e riga iniziale di [../CLAUDE.md](../CLAUDE.md) (nome del csproj nei comandi) ## Flusso (doc-first, doc-as-code) -1. Prima i doc, poi i test, poi il codice: ADR (se c'è una scelta architetturale) → MVP → matrice in [TESTING.md](TESTING.md) → test → codice → ROADMAP → README → CLAUDE.md. +1. Prima i doc, poi i test, poi il codice: ADR (se c'è una scelta architetturale) → MVP → matrice in [TESTING.md](TESTING.md) → test → codice → ROADMAP → PROJECT_STATE → README → CLAUDE.md. Nessuna funzione è finita senza test che la coprono, nello stesso commit. 2. I doc stanno nel repo e cambiano con lo stesso commit del codice a cui si riferiscono. 3. Una modifica non deve lasciare i doc disallineati. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 7d71c4f..57b7b1b 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -1,6 +1,6 @@ # Roadmap -Dettagli dell'MVP in [MVP.md](MVP.md). +Dettagli dell'MVP in [MVP.md](MVP.md). Stadio attuale e debiti: [PROJECT_STATE.md](PROJECT_STATE.md) (siamo in fase di **MVP**). ## Fase 0 — Doc-first - [x] Scrivere MVP.md e ROADMAP.md