ThothII/docs/plans/2026-09-28-installation-ticket-breakdown.md

Scomposizione della specifica di installazione

Data: 2026-09-28. Stato: scomposizione approvata dall'utente («approvo»); pubblicazione /to-tickets completata. Verificati testi, etichetta ready-for-agent e dipendenze native delle issue #43–#54; specifica parent invariata. Parent: Spec: installazione da documenti verificati e distribuzione Docker Hub.

Gli identificatori T01–T12 restano riferimenti della scomposizione; le issue reali sono elencate sotto. Ogni issue usa ready-for-agent e dipendenze native Gitea. La parent non viene modificata né chiusa.

Issue pubblicate

Avanzamento locale, 2026-09-28: T01/#43 implementato sul branch codex/guided-standalone-install. Disponibili tht workspace prepare e tht workspace validate, con helper autonomo che riusa i parser runtime. Guide IT/EN aggiornate; esempi e pubblicazione degli artefatti restano differiti ai ticket previsti. Nessuna chiusura o modifica della parent effettuata.

Verifica: 14 test della CLI passano sia da sorgenti sia con il bundle nativo macOS arm64 e PATH vuoto; artefatti Windows amd64/Linux amd64 cross-compilati, senza attribuire loro un collaudo host. Backend su Node 24.16: 109 file passati, un file saltato, 1.417 test passati e 40 saltati; typecheck e build rigorosa documentazione passati. Suite Go: tutti i pacchetti passati, salvo un primo errore intermittente nel test di concorrenza authstorage; quel test passa in tre ripetizioni e il pacchetto completo passa nella verifica isolata. Le revisioni Standards e Spec non lasciano finding aperti.

T02/#44 implementato sullo stesso branch: tht installation prepare, generazione esplicita delle credenziali tecniche e tht installation validate preparano e controllano documenti privati, modelli, autenticazione e bootstrap dei binding, riusando gli schemi runtime senza avviare servizi. Guide IT/EN aggiornate. Verifica backend completa su Node 24.16: 111 file passati, uno saltato, 1.420 test passati e 40 saltati; le regressioni successive della revisione passano nella suite mirata (quattro test, incluso il percorso con binari nativi e PATH vuoto). Typecheck, build rigorosa documentazione e pacchetti Go passati; il pacchetto CLI è stato ripetuto dopo la correzione rilevata in revisione. Nessun finding residuo delle revisioni Standards/Spec. Il prossimo incremento sequenziale è T03/#45.

Ticket	Issue Gitea	Dipendenze dirette
T01	Preparare e validare un repository workspace senza stack	Nessuna
T02	Preparare e validare i documenti applicativi	#43
T03	Verificare precondizioni e produrre il piano eseguibile	#44
T04	Produrre e pubblicare un rilascio Docker Hub installabile	Nessuna
T05	Installare la piattaforma dal rilascio senza domande	#45, #46
T06	Applicare i binding preparati al Catalog	#47
T07	Portare il workspace alla readiness con controlli runtime	#48
T08	Conservare il percorso esplicito da sorgente	#47
T09	Riprendere dopo correzioni e interruzioni senza perdere stato	#49, #50
T10	Collaudare l'installazione pubblicata su Windows/WSL2	#51
T11	Collaudare l'installazione su Omarchy	#52
T12	Pubblicare e collaudare il percorso macOS Apple Silicon	#53

Ogni ticket comprende verifiche del comportamento e aggiornamenti pertinenti delle guide IT/EN. Le dipendenze elencate sono dirette; non si ripetono quelle transitive. Si riusano il runner dell'operatore e i servizi di dominio esistenti; gli adattamenti necessari sono inclusi nella prima funzionalità che li usa. Non emerge una necessità di refactoring trasversale da pubblicare come lavoro orizzontale separato.

Ticket	Titolo	Bloccato da	Risultato dimostrabile
T01	Preparare e validare un repository workspace senza stack	Nessuno	Template e controllo locale conformi ai contratti, senza Docker attivo.
T02	Preparare e validare i documenti applicativi	T01	Parametri, modelli e binding completi verificati senza avviare servizi.
T03	Verificare precondizioni e produrre il piano eseguibile	T02	Rapporto con errori bloccanti e obblighi runtime, legato agli input.
T04	Produrre e pubblicare un rilascio Docker Hub installabile	Nessuno	Comando manutentore e pacchetto pubblico verificato tramite pull.
T05	Installare la piattaforma dal rilascio senza domande	T03, T04	Pull, inizializzazione e avvio da documenti, con stato e ripresa delle fasi.
T06	Applicare i binding preparati al Catalog	T05	Database dei workspace configurati senza questionari o duplicazioni.
T07	Portare il workspace alla readiness con controlli runtime	T06	Schema, preprocessing e servizi verificati senza aggirare la revisione umana.
T08	Conservare il percorso esplicito da sorgente	T05	Stessi input e contratti, con build scelta esplicitamente.
T09	Riprendere dopo correzioni e interruzioni senza perdere stato	T07, T08	Recupero dell'intero percorso, compresi binding, sync e preprocessing.
T10	Collaudare l'installazione pubblicata su Windows/WSL2	T09	Prima accettazione reale senza sorgenti o compilatori.
T11	Collaudare l'installazione su Omarchy	T10	Seconda accettazione reale su Linux x64, distinta da Windows.
T12	Pubblicare e collaudare il percorso macOS Apple Silicon	T11	Terza accettazione con immagini arm64 e comando host compatibile.

T01 — Preparare e validare un repository workspace senza stack

Parent

Spec: installazione da documenti verificati e distribuzione Docker Hub.

What to build

Un autore prepara un repository ad hoc usando un template documentato e verifica i documenti localmente prima di installare ThothII. Il validatore è fornito come capacità eseguibile senza Node, Docker attivo o checkout dei sorgenti applicativi. Riusa i contratti del runtime, senza creare uno schema workspace alternativo.

Acceptance criteria

• Il template distingue catalogo workspace, descriptor ed Evidence opzionali e non contiene funzionalità degli esempi ancora indisponibili.
• Preparare un template non avvia servizi, non sovrascrive documenti esistenti e non richiede accesso in scrittura al repository originale.
• Il controllo respinge YAML ambiguo o invalido, chiavi duplicate, identificatori duplicati, campi estranei, incoerenze catalogo/directory e riferimenti locali mancanti.
• Le Evidence configurate sono verificate per ciò che è controllabile localmente; assenza lecita e invalidità sono distinte, senza certificare il significato delle regole di dominio.
• Gli esiti identificano documento/campo e correzione; output strutturato e codici di uscita sono verificabili senza esporre segreti.
• Una raccolta condivisa di casi validi/invalidi prova equivalenza con i parser runtime, e il controllo passa senza Docker e senza runtime host aggiuntivi.
• Guide IT/EN mostrano preparazione, correzione e ripetizione del passo 2.

Blocked by

None (can start immediately).

T02 — Preparare e validare i documenti applicativi

Parent

Spec: installazione da documenti verificati e distribuzione Docker Hub.

What to build

L'operatore compila template locali per installazione, modelli, binding database e segreti, e ne verifica completezza e coerenza con i workspace già verificati. Non viene avviata l'applicazione e nessun valore viene richiesto dal futuro setup.

Acceptance criteria

• Template commentati ed esempi completi spiegano obblighi, default e riferimenti ai documenti protetti; i placeholder non superano la validazione.
• Modelli e embedding rispettano l'Installation Model Catalog; generazione metadati opzionale e default sono coerenti con i contratti esistenti.
• Un input bootstrap locale versionato descrive Workspace Database e Database Binding con riferimenti ai segreti; i descriptor workspace restano conformi allo schema v4.
• Validazione incrociata di workspace, binding, engine/trasporto, modelli, percorsi e file ambiente, senza migrare o interrogare in scrittura alcun database.
• La generazione esplicita delle credenziali tecniche produce file protetti prima del setup, senza sovrascritture o segreti nei log/rapporti.
• I test coprono input completi, mancanti, incompatibili e segreti illeggibili; i documenti dell'utente rimangono invariati durante le verifiche.
• Guide IT/EN consentono di raccogliere e preparare tutte le informazioni con calma prima dell'esecuzione.

Blocked by

• T01 — Preparare e validare un repository workspace senza stack.

T03 — Verificare precondizioni e produrre il piano eseguibile

Parent

Spec: installazione da documenti verificati e distribuzione Docker Hub.

What to build

L'operatore verifica host e dipendenze esterne disponibili, quindi ottiene un piano eseguibile riferito ai documenti e al rilascio scelti. Il rapporto distingue errori, avvisi e controlli necessariamente rinviati al runtime, senza creare lo stack.

Acceptance criteria

• I controlli host sono invocabili al passo 3; quelli dipendenti dai parametri finali sono completati o ripetuti al passo 5.
• Sono verificati Docker/Compose, architettura, WSL2 quando pertinente, percorsi/permessi, risorse e disponibilità del rilascio e dei suoi componenti nel registry.
• Le prove sulle dipendenze esterne disponibili sono circoscritte e documentate; un servizio esistente irraggiungibile non viene promosso a semplice controllo differito.
• Pi non è richiesto sull'host; le dipendenze incluse nelle immagini sono riconosciute nel manifest e associate a controlli runtime precisi.
• Il piano registra input non segreti, revisione/contenuti workspace, release e versione del validatore; nessun segreto o fingerprint pubblico non protetto di segreti.
• Ogni controllo differito ha un'identità e un'obbligazione runtime; valori obbligatori mancanti o immagini assenti bloccano il piano.
• Prove con manifest e servizi controllati coprono cambiamento degli input, credenziali, errori di rete e architetture; nessuna creazione di container o mutazione di dati.
• Guide IT/EN spiegano rapporto, errori e verifiche ancora da eseguire. La prova con il rilascio reale verrà completata dal ticket di esecuzione, dopo T04.

Blocked by

• T02 — Preparare e validare i documenti applicativi.

T04 — Produrre e pubblicare un rilascio Docker Hub installabile

Parent

Spec: installazione da documenti verificati e distribuzione Docker Hub.

What to build

Il manutentore esegue un comando riproducibile che costruisce, verifica e pubblica core/frontend su Docker Hub, insieme al pacchetto operatore compatibile, e dimostra che il rilascio pubblicato è scaricabile. La pubblicazione delle immagini oggi mancanti è un risultato concreto del ticket, non un prerequisito lasciato a mano.

Acceptance criteria

• Il comando riceve revisione, versione, namespace e architetture e mantiene fuori da bundle/log le credenziali di pubblicazione.
• Pubblica core/frontend Linux amd64 per la prima tappa; Catalog migration e workspace maintenance risolvono alla stessa immagine core del rilascio.
• Il bundle contiene comando host precompilato, Compose, inizializzazione e risorse di migrazione, senza dipendenze da checkout sorgente durante l'avvio.
• Il processo può includere la capacità di validazione preinstallazione prodotta da T01 nelle revisioni che la contengono; non serve duplicarne l'implementazione per questo ticket.
• Il manifest lega versione/revisione e digest compatibili; una pubblicazione parziale non viene esposta come rilascio completo e una versione immutabile non viene sovrascritta.
• Viene pubblicato un rilascio reale e viene verificato il pull degli artefatti pubblicati, senza affidarsi a immagini presenti soltanto nella cache di build.
• Test automatici verificano orchestrazione, fallimenti e retry senza richiedere una pubblicazione reale a ogni test; la prova reale del ticket resta distinta e registrata.
• Documentazione manutentore IT/EN e istruzioni del bundle distinguono pubblicazione, consumo e futura estensione arm64. Namespace e accessi effettivi sono input del manutentore, non valori inventati.

Blocked by

None (can start immediately).

T05 — Installare la piattaforma dal rilascio senza domande

Parent

Spec: installazione da documenti verificati e distribuzione Docker Hub.

What to build

L'operatore applica un piano verificato, scarica gli artefatti pubblicati e ottiene una piattaforma inizializzata e accessibile senza compilazione o domande. Lo stato registrato permette di ritentare le fasi di piattaforma interrotte; non viene ancora dichiarato pronto un workspace privo delle successive verifiche Catalog.

Acceptance criteria

• Avvio da bundle rilasciato e operatore precompilato, senza checkout applicativo o toolchain; la revisione del bundle include i validatori e i comandi effettivamente utilizzati.
• Il piano viene ricontrollato rispetto a input, release e prerequisiti vivi prima delle mutazioni; un piano mancante o incoerente viene rifiutato.
• Con standard input chiuso il setup esegue pull, configurazione runtime, reti/volumi/container, inizializzazione Catalog/Memory e migrazioni senza richiedere parametri.
• L'accesso amministrativo iniziale deriva da materiale protetto preparato prima; non si introduce un endpoint privilegiato senza autenticazione.
• Un lock impedisce esecuzioni concorrenti; il journal atomico registra le fasi senza segreti e consente di verificare lo stato reale prima di ripetere una fase interrotta.
• Errori di pull non causano build locali; errori di configurazione rimandano ai documenti e alla nuova verifica, senza prompt di riparazione.
• La piattaforma accessibile è distinta dalla Workspace Readiness ancora da verificare; nessun messaggio finale prematuro di piena utilizzabilità.
• Test del runner e prova con artefatti pubblicati coprono successo, stdin chiuso, interruzioni e ripetizione senza cancellare volumi o dati. Guide IT/EN documentano il risultato parziale corretto.

Blocked by

• T03 — Verificare precondizioni e produrre il piano eseguibile.
• T04 — Produrre e pubblicare un rilascio Docker Hub installabile.

T06 — Applicare i binding preparati al Catalog

Parent

Spec: installazione da documenti verificati e distribuzione Docker Hub.

What to build

Il setup rende operativa la configurazione database predisposta nei documenti: registra il repository, crea i Workspace Database e le Database Binding nel Catalog, installa i riferimenti segreti e verifica le connessioni. Il risultato è un binding utilizzabile senza una compilazione manuale dei parametri nell'interfaccia web.

Acceptance criteria

• Identità e revisioni dei workspace corrispondono al piano; il consumo del repository non richiede push e non sostituisce implicitamente una sorgente esistente.
• Creazione e modifica dei binding utilizzano servizi autorizzati, controlli di versione e secret store esistenti; nessuna seconda autorità runtime nei documenti bootstrap.
• La stessa configurazione applicata due volte non duplica record, credenziali o binding.
• Una modifica amministrativa incompatibile produce un rapporto di riconciliazione invece di essere sovrascritta dai file preparatori.
• La connessione viene controllata dall'ambiente applicativo; un esito positivo ottenuto dall'host non basta a dichiararla utilizzabile dai container.
• Un'interruzione dopo il salvataggio ma prima dell'aggiornamento del journal viene riconosciuta alla ripresa, senza duplicazioni o perdita di segreti.
• Test di contratto e integrazione Catalog coprono autorizzazioni, concorrenza, versioni e rerun; guide IT/EN illustrano diagnosi e riconciliazione.

Blocked by

• T05 — Installare la piattaforma dal rilascio senza domande.

T07 — Portare il workspace alla readiness con controlli runtime

Parent

Spec: installazione da documenti verificati e distribuzione Docker Hub.

What to build

Da un binding applicato, il percorso completa sincronizzazione dello schema e preparazione necessaria e rende visibili i risultati dei controlli runtime. Un workspace è pronto solo quando tutti i requisiti applicabili sono verificati; le decisioni umane già previste dai contratti rimangono esplicite.

Acceptance criteria

• La sincronizzazione usa i Catalog Sync Runs durabili con lock, freschezza e transazioni esistenti; non introduce una seconda implementazione.
• Diff distruttive fermano il percorso in attesa della revisione di dominio esistente; ripresa successiva senza auto-conferme né domande sui parametri di setup.
• Preprocessing e consolidamento riusano descrizioni/commenti ed Evidence curate; nessuna generazione AI implicita, nessuna cancellazione di Memory o sovrascrittura di curation.
• Assenza lecita di Evidence non blocca; Evidence configurate ma invalide e indici necessari non pronti restano blocchi reali.
• Pi, modello embedding, trasporto DWH e altri obblighi differiti sono eseguiti a runtime e rendicontati; nessun obbligo scompare o viene considerato superato senza prova.
• Stato piattaforma, Workspace Readiness e collaudo funzionale sono distinti; una domanda reale con revisione rimane la prova funzionale, senza SQL target.
• Test di servizio e integrazione dimostrano esiti, conservazione dati e ripresa dei run; guide IT/EN spiegano le eventuali revisioni umane residue.

Blocked by

• T06 — Applicare i binding preparati al Catalog.

T08 — Conservare il percorso esplicito da sorgente

Parent

Spec: installazione da documenti verificati e distribuzione Docker Hub.

What to build

Un operatore sceglie esplicitamente la build da una revisione sorgente e usa gli stessi documenti, validatori, identità d'installazione e servizi del percorso precompilato. L'alternativa resta praticabile mentre il default diventa Docker Hub.

Acceptance criteria

• Modalità sorgente e prerequisiti aggiuntivi sono espliciti; nessun errore del registry la attiva automaticamente.
• I componenti costruiti sono equivalenti nei contratti di configurazione, migrazione e persistenza; non esistono implementazioni parallele dei binding o della readiness.
• Il piano identifica modalità e revisione e invalida i controlli dipendenti quando cambiano.
• L'esecuzione rimane non interattiva e usa journal/lock comuni; i segreti non entrano nelle immagini di sviluppo.
• Una prova automatizzata dimostra build e avvio espliciti e il mancato fallback da pull; una prova sorgente non chiude l'accettazione del rilascio precompilato.
• Guide IT/EN separano il percorso avanzato da quello ordinario e rendono visibili i prerequisiti aggiuntivi.

Blocked by

• T05 — Installare la piattaforma dal rilascio senza domande.

T09 — Riprendere dopo correzioni e interruzioni senza perdere stato

Parent

Spec: installazione da documenti verificati e distribuzione Docker Hub.

What to build

L'operatore corregge un endpoint, una credenziale o un altro documento dopo un errore e riprende l'intero percorso con verifiche aggiornate. Questo ticket completa il recupero fra stadi e modalità, oltre ai retry locali già consegnati dai singoli ticket.

Acceptance criteria

• Cambiamenti ai documenti, ai contenuti/revisioni workspace o al rilascio invalidano le sole verifiche/fasi dipendenti; le altre vengono riconciliate con lo stato reale.
• La rotazione di una credenziale viene rilevata senza esporla o pubblicarne fingerprint non protetti; si ripetono le prove necessarie.
• Ripresa dopo interruzione nei confini fra pull, inizializzazione, importazione Catalog, sync e preprocessing non duplica operazioni già persistite.
• Il preprocessing interrotto è rieseguito secondo il contratto esistente, senza promettere resume interno; un run in attesa di decisione umana conserva tale stato.
• Interruzioni, errori e concorrenza non corrompono il journal né attivano reset di volumi; diagnosi e stato rimangono privi di segreti.
• Test del percorso pubblico, con guasti controllati e integrazione dove conta la persistenza, dimostrano conservazione di sessioni, Evidence, descrizioni e Memory in entrambe le modalità.
• Le guide IT/EN presentano scenari di correzione/ripresa senza suggerire la cancellazione dei dati come normale rimedio.

Blocked by

• T07 — Portare il workspace alla readiness con controlli runtime.
• T08 — Conservare il percorso esplicito da sorgente.

T10 — Collaudare l'installazione pubblicata su Windows/WSL2

Parent

Spec: installazione da documenti verificati e distribuzione Docker Hub.

What to build

Dimostrare il percorso completo su un PC Windows x64 con Ubuntu WSL2 e Docker Desktop usando il rilascio realmente pubblicato, repository ad hoc e documenti predisposti. Il collaudo include le correzioni necessarie a rendere utilizzabile la prima piattaforma e un rapporto riproducibile.

Acceptance criteria

• Un rilascio della revisione integrata viene pubblicato tramite T04 e consumato tramite pull; le immagini costruite soltanto localmente non soddisfano la prova.
• Il consumer non dispone di sorgenti applicativi o toolchain necessarie a compilare; operatore e validatori sono quelli precompilati nel bundle.
• Tutti i sei passi sono percorsi nell'ordine documentato, con almeno una correzione documentale e una ripresa dopo errore, senza domande durante il setup.
• Primo workspace ad hoc realmente utilizzabile, una domanda con revisione umana e stop/start con stato preservato; nessun uso presunto degli esempi rinviati.
• Rapporto con host/runtime, revisione, digest e risultati distinti di piattaforma/workspace/funzione, senza segreti; problemi esterni non sono nascosti.
• Guide IT/EN sono verificate rispetto ai comandi e agli esiti reali; eventuale assenza di host o credenziali necessarie lascia il collaudo incompleto, non simulato come riuscito.

Blocked by

• T09 — Riprendere dopo correzioni e interruzioni senza perdere stato.

T11 — Collaudare l'installazione su Omarchy

Parent

Spec: installazione da documenti verificati e distribuzione Docker Hub.

What to build

Dopo la tappa Windows, ripetere e rendere funzionante il percorso su Linux Omarchy x64, producendo un'evidenza di accettazione propria e mantenendo il comportamento documentale e non interattivo già consegnato.

Acceptance criteria

• Rilascio pubblico compatibile scaricato da Docker Hub e comando host precompilato; nessuna compilazione nel percorso ordinario.
• Prerequisiti, permessi, percorsi e rete di Omarchy sono verificati su un host reale, senza trasferire automaticamente l'esito Windows.
• Sei passi, input invalido/corretto, ripresa, workspace ad hoc, domanda reale e stop/start superano il collaudo.
• Ogni correzione di portabilità include la relativa verifica e non introduce una divergenza dei contratti rispetto al percorso Windows.
• Rapporto separato con versioni/digest e guide IT/EN coerenti; senza un host disponibile il gate rimane aperto.

Blocked by

• T10 — Collaudare l'installazione pubblicata su Windows/WSL2.

T12 — Pubblicare e collaudare il percorso macOS Apple Silicon

Parent

Spec: installazione da documenti verificati e distribuzione Docker Hub.

What to build

Dopo Omarchy, pubblicare e verificare il set di artefatti compatibile con macOS Apple Silicon, incluse immagini Linux arm64 e comando nativo, e chiudere la terza tappa di accettazione su un Mac reale.

Acceptance criteria

• Il comando di rilascio pubblica immagini arm64 e bundle host compatibile, con manifest/digest coerenti e senza dichiarare supporto prima del collaudo.
• Il consumer usa il rilascio pubblico e non compila; gli script e le risorse di inizializzazione sono presenti nel bundle.
• Tutti i sei passi, correzione/ripresa, workspace ad hoc, domanda reale e stop/start sono verificati sul Mac.
• Le eventuali correzioni conservano compatibilità e contratti delle tappe precedenti; le prove multiarch di build non sostituiscono il collaudo host.
• Rapporto macOS separato e guide IT/EN finalizzate per le tre piattaforme; nessun risultato sintetico viene presentato come prova reale.

Blocked by

• T11 — Collaudare l'installazione su Omarchy.

Verifiche della scomposizione

• I primi ticket lavorabili sono T01 e T04.
• T03 usa manifest e servizi controllati per i propri contratti; non aspetta la pubblicazione reale. T05 è il primo punto che richiede insieme validazione e artefatti realmente pubblicati.
• T06 e T08 possono procedere in parallelo dopo T05. T09 riunisce i percorsi per verificare correzioni e ripresa dell'intera installazione.
• I tre gate host sono sequenziali per scelta esplicita dell'utente, non per una dipendenza architetturale inventata.
• Gli esempi restano esclusi. Il comando di pubblicazione Docker Hub e almeno una pubblicazione reale sono inclusi, non demandati a un futuro progetto.
• Nessun aggiornamento o chiusura della parent è previsto dalla pubblicazione.