mptyl/ThothII
1
0
Fork 0
Code Issues 25 Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
fa7380b3a32065441ba40cf430eb819588b47ade
ThothII/docs/prd/2026-08-09-workspace-preprocessing-prd.md
T

35 KiB
Raw Blame History

PRD — Preprocessing per-workspace su ThothII (Qdrant + Git workspace registry)

Status: PRD in revisione — decisioni D1–D9 chiuse il 2026-08-09; i piani P1–P10 partiranno solo dopo revisione e conferma del proprietario Data: 2026-08-09 Autore: analisi dello stato attuale (branch codex/git-workspace-registry) + decisioni con il proprietario Uso: riferimento stabile di requisiti e decisioni; da ogni punto nascerà un piano separato in docs/superpowers/plans/ (sez. 11) — questo documento non è un piano di lavoro

Aggiornamento P1.1 (2026-08-11): il layout del repository registry descritto nelle sezioni attive di questo PRD segue il contratto P1.1 accettato: catalogo di root thoth-workspaces.yaml, descriptor <id>/workspace.yaml, evidence embedded <id>/evidence/, annotazioni FK curate <id>/schema/annotations.yaml (P5), docs generate workspace-docs/<id>/. I vecchi percorsi piatti (workspaces/<id>.yaml, workspace-content/<id>/evidence/) sono superseded; le uniche occorrenze rimaste sono storiche (changelog/revisioni). Vedi docs/superpowers/plans/2026-08-11-p2-p6-adaptation-to-p1-1-registry.md.

1. Contesto

ThothII è passato da un indice semantico pgvector sul server PSD (descrizioni di tabelle/colonne, evidence e memory embeddate nella stessa istanza Postgres del DWH, lettura via RPC search_similar, scrittura via REST dedicato o loading diretto) a un'architettura con:

  • infrastruttura semantica interna obbligatoria: Qdrant + Ollama (qwen3-embedding:0.6b, 1024 dim, cosine) come servizi Compose privati; una collection Qdrant per workspace, con schema/evidence/memory separati dal payload kind;
  • workspace definito da un descriptor schema-v3 in un repo Git esterno (id, DWH, collection, LLM policy, diagnostics), con binding DWH locali all'installazione;
  • config harness renderizzata dal backend a runtime (runtime_identity + resources.vector + resources.embeddings + roots sotto <dataRoot>/sessions/<wsId>/).

La macchina di preprocessing (comandi, job a generazioni con publish atomico, adapter Qdrant, corpus evidence, FK, memory) esiste già ed è testata: tht preprocess evidence|dwh, tht vector init|index-schema, tht schema introspect|suggest-fks|check, tht evidence extract|index, tht lsh build, memory/solved. Esistono job Compose fixture (deploy/compose.preprocess.yaml + deploy/workspaces/preprocess-{dwh,evidence}.yaml) e uno smoke (scripts/preprocess-smoke.sh).

Il problema

Il preprocessing non è collegato al workspace reale del registry:

  1. i job fixture usano una collection fissa (preprocess-evidence), un workspace_id derivato dal nome file (preprocess-evidence) e roots sotto /data/workspaces/preprocess-*, che non coincidono con quelli del runtime (<dataRoot>/sessions/<wsId>/);
  2. il backend non espone alcun modo di eseguire tht preprocess contro la config renderizzata di un workspace (nessun endpoint, nessuno script, nessun comando documentato);
  3. il descriptor v3 e la config renderizzata non hanno la sezione evidence: non c'è un posto canonico dove dichiarare da dove arrivano le evidence di un workspace;
  4. l'ammissione sessione (ThtRunner.qdrantEnsure) richiede la collection già esistente con 1024/cosine e 8 payload keyword-index, ma nessuno la crea esplicitamente (tht vector init fallisce se manca);
  5. le generazioni .tht-dwh sono legate a un fingerprint della config completa (OWNER.json: workspace_id + config_fingerprint + input_fingerprint): se il preprocessing non usa la config identica a quella renderizzata dal runtime, a runtime la generazione viene rifiutata;
  6. la cura FK (annotations.yaml) è manuale e vive nel runtime artifacts; il registry non sincronizza file dal repo ai roots runtime;
  7. i vecchi embedding pgvector (nomic 768d) non sono riusabili (modello e dimensioni cambiati): serve re-indicizzare i contenuti PSD.

Sintesi: la parte "motore" è pronta; manca il collegamento per-workspace (config, esecuzione, bootstrap, sorgente evidence) e la documentazione operator.

2. Obiettivo

Rendere l'attuale versione di ThothII (Qdrant + workspace su repo esterno) configurabile e utilizzabile per un workspace reale, inclusa l'intera catena di preprocessing: tabelle/colonne (catalogo + embedding), FK (cura), evidence (sorgente → corpus → embedding), memory/solved, con un flusso operator riproducibile, documentato e verificato da smoke end-to-end.

Obiettivi secondari

  • O1. Un solo modo canonico di eseguire il preprocessing per un workspace (niente più fixture "speciali").
  • O2. Il preprocessing è idempotente e ripristinabile: rerun senza duplicati, publish atomico, GC.
  • O3. Nessun segreto/endpoint entra nel repository registry né nei descriptor (invariante attuale preservato).
  • O4. Il flusso è documentato nei manuali operator (local/server-workspace-registry.md) e coperto da smoke automatici.
  • O5. La migrazione PSD è definita (cosa si riusa, cosa si rigenera, cosa si esporta dal pgvector).
  • O6. Ogni piano tecnico definisce, dove applicabile, un goal automatico di processo completo: da stato pulito costruisce un ambiente isolato, simula il flusso end-to-end entro lo scope del piano e lo porta a successo con un integration test riproducibile.
  • O7. Dopo il successo automatico, un percorso manuale separato permette al reviewer di ripetere il processo attraverso le interfacce reali, comprenderne l'architettura e approvare gli artefatti.

3. Non-obiettivi (fuori scope di questo PRD)

  • Riscrivere il workflow NL→SQL o i gate (F1..F8) — restano invariati.
  • Cambiare modello/architettura semantica (Qdrant/Ollama/1024/cosine) — già deciso e verificato.
  • Rifare la UI di gestione workspace oltre a quanto già esiste.
  • Il deploy reale sul server PSD (VPN, credenziali, portale, auth upstream): è un progetto operativo separato che userà questo PRD come prerequisito tecnico.
  • Supportare di nuovo pgvector o endpoint embedding esterni come percorso operativo.
  • Il comando di preprocessing avviabile dalla GUI: è una release futura (fuori scope della release 0, che è CLI sul host — vedi D2).

4. Utenti

Utente Esigenza
Operatore/amministratore (chi installa e cura un workspace) Configurare DWH+evidence, eseguire il preprocessing, curare le FK, verificare lo stato, fare backup/restore.
Autore ETL / curatore dominio (es. il cliente PSD) Mantenere evidence e annotazioni FK nel namespace del workspace nel repository registry con un flusso semplice.
Reviewer umano (usa l'app) Vede search pack con tabelle/evidence/solved corretti: la qualità del retrieval dipende dal preprocessing.
Sviluppatore ThothII Comandi/endpoint deterministici, testabili, senza sorprese di configurazione.

5. Scenario target (end-to-end)

  1. Setup repo: l'operatore usa un unico repository Git registry per tutti i workspace e crea <id>/workspace.yaml (schema-v3: DWH, collection, LLM policy) insieme al tree curato <id>/evidence/; descriptor e contenuti sono pubblicati nello stesso commit.
  2. Installazione: .env + bindings THT_WS_* + secrets; up dello stack (frontend/core/qdrant/embedding).
  3. Registry: pull → validazione → snapshot attivo; diagnostic DWH verdi.
  4. Preprocessing DWH: introspezione (physical.yaml: tabelle/colonne/descrizioni/esempi/eligibility) + LSH; generazione pubblicata sotto .tht-dwh del workspace.
  5. Cura FK: tht schema suggest-fks → revisione umana → annotations.yaml (check senza orfani); versionata dove deciso (vedi D5).
  6. Indice schema: tht vector index-schema → record schema nella collection del workspace; la collection, se inesistente, viene creata all'ammissione (self-heal) o dal primo write (vedi D4).
  7. Preprocessing evidence: tht preprocess evidence → corpus generation (chunk+embed) nella collection (kind evidence) + manifest ACTIVE nel corpus root del workspace.
  8. Memory/solved: promozioni F8 (memory promote/save-one) e finalize (solved-index) scrivono nella collection (kind memory).
  9. Uso: nuova sessione → admission verde (collection+Ollama) → F1 search pack con tabelle, evidence e solved del workspace; F4/F6 con FK curate.
  10. Operatività: backup/restore volumi (Qdrant, corpus, .tht-dwh, registry), update, ripristino da outage.

6. Requisiti funzionali

RF1 — Configurazione per-workspace

  • RF1.1 Un workspace del registry deve poter dichiarare tutto ciò che serve al preprocessing in un unico posto canonico: DWH (già nel descriptor), sorgente evidence completa (protocollo/tipo, URI, parametri non-secret), eventuali policy di chunk/retention.
  • RF1.2 I segreti (password, API key, CA) restano fuori dal repo e dal descriptor (invariante attuale).
  • RF1.3 La config harness usata dal preprocessing deve essere derivata dalla stessa renderizzazione del runtime (stesso workspace_id, stessi roots, stessa configurazione effettiva).
  • RF1.4 La configurazione (descriptor + bindings + config renderizzata) deve prevedere i tre trasporti DWH: postgres_direct, rest_api, ssh_tunnel. PSD usa rest_api; altri database potranno usare direct o tunnel.
  • RF1.5 Il registry usa un unico repository Git per più workspace. Per una sorgente evidence filesystem, l'URI è relativa alla root del repository ed è confinata lessicalmente a <workspace_id>/; path assoluti, traversal (..) e riferimenti al namespace di un altro workspace sono invalidi. Descriptor e sorgente devono essere risolti dalla stessa revisione Git.

RF2 — Preprocessing DWH (tabelle/colonne)

  • RF2.1 Comando/azione per eseguire introspect + lsh per un workspace del registry, contro la sua config effettiva, con output JSON e resume.
  • RF2.2 La CLI di preprocessing raggiunge il DWH con il trasporto dichiarato dal workspace (direct, REST o tunnel SSH), come il runtime.
  • RF2.3 Il catalogo risultante (physical.yaml) alimenta: cache tht schema introspect, render mschema (F1/F4), record schema per l'embedding (RF4).
  • RF2.4 Refreshing esplicito quando il DWH cambia (--refresh/nuova generazione), senza invalidare le sessioni esistenti (generazioni + ACTIVE pointer, già implementato).

RF3 — FK

  • RF3.1 Flusso curato per-workspace: tht schema suggest-fks (+ --from-sql, --assume, --write), revisione umana, tht schema check (zero orfani).
  • RF3.2 Le FK curate devono essere disponibili a runtime (sezione 【Foreign keys】 del render mschema, usata da F4/F6) e versionate nel repository registry (D5).
  • RF3.3 Nessuna FK derivata dal modello: il modello usa solo la lista curata (contratto SKILL invariato).

RF4 — Indice semantico schema + bootstrap collection

  • RF4.1 tht vector index-schema embedda i record schema (tabella+colonna, con descrizioni/esempi/sinonimi) nella collection del workspace (kind schema), idempotente (hash → upsert solo del cambiato).
  • RF4.2 Bootstrap della collection: se inesistente all'ammissione sessione, il runtime la crea (self-heal) con 1024/cosine + i payload keyword-index richiesti (content_hash, document_id, kind, record_key, record_kind, vector_generation, workspace_id, workspace_revision).
  • RF4.3 La CLI deve poter cancellare e ricreare la collection di un workspace (rebuild esplicito con guardie di sicurezza e conferma).
  • RF4.4 Prima di una sessione, l'ammissione resta invariata (collection compatibile + Ollama).

RF5 — Evidence

  • RF5.1 Sorgente evidence dichiarabile per-workspace nel descriptor (protocollo/tipo + URI). Per PSD è un tree di file .md versionato nell'unico repository registry, sotto psd/evidence/; in generale ogni workspace usa <workspace_id>/evidence/. HTTP manifest e S3 restano opzioni del motore per sorgenti esterne.
  • RF5.2 tht preprocess evidence per-workspace: discover → acquire → normalize/chunk → embed → upsert (kind evidence, payload document_id/vector_generation) → publish ACTIVE nel corpus root del workspace, con resume e dry-run (già implementato nel motore).
  • RF5.3 GC/retention delle generazioni evidence (filesystem + punti Qdrant) con le policy esistenti.
  • RF5.4 A runtime la ricerca evidence è filtrata dalla generazione ACTIVE e dal workspace_id (già implementato: ActiveEvidenceSearcher); il flusso RF5 deve garantire che il corpus ACTIVE appartenga al workspace giusto.

RF6 — Memory e domande risolte

  • RF6.1 memory promote/save-one (F8) e memory solved-index (finalize) scrivono nella collection del workspace (kind memory/solved_question) — verificare end-to-end con Qdrant e risolvere i TODO residui in memory_cmd.py.
  • RF6.2 Il registro JSONL resta la fonte canonica; Qdrant è proiezione di ricerca (invariante attuale).

RF7 — Migrazione PSD

  • RF7.1 Definire cosa si riusa (physical.yaml, annotations.yaml con le ~228 FK curate, le 895 evidence .md), cosa si rigenera (tutti gli embedding, modello diverso) e cosa si esporta dal pgvector del server prima della dismissione.
  • RF7.2 La migrazione è un'operazione documentata e rieseguibile, non un one-shot nel codice.

RF8 — Operatività e documentazione

  • RF8.1 Manuali operator aggiornati con la sequenza completa per-workspace (config → preprocess → cura → verifica → uso → backup/restore).
  • RF8.2 La documentazione di progetto spiega cos'è .tht-dwh (generazioni, OWNER.json, ACTIVE, vincolo di fingerprint) in modo comprensibile per l'operatore (D3).
  • RF8.3 Smoke end-to-end automatico (workspace nuovo → tutto il ciclo → sessione reale → cleanup) che sostituisce/completa preprocess-smoke.sh (oggi solo fixture).
  • RF8.4 Backup/restore coprono Qdrant (già vector-backup.sh/vector-restore.sh), corpus, .tht-dwh e registry.
  • RF8.5 Ogni piano successivo traduce il proprio risultato operativo in un process goal verificabile da un integration test completo per quello scope; eventuali interventi umani iniziali o intermedi sono ammessi solo se inevitabili, espliciti, documentati e riprendibili.
  • RF8.6 Ogni process goal automatico riuscito è seguito, quando utile, da un walkthrough manuale su un ambiente nuovo e separato; automazione e accettazione umana producono evidenze distinte.

7. Requisiti non funzionali

  • RNF1 Sicurezza: nessun segreto in repo/descriptor/config renderizzata/log; la CLI di preprocessing (D2) non espone credenziali, non le logga e non le scrive negli artefatti.
  • RNF2 Determinismo/idempotenza: rerun del preprocessing = zero duplicati (hash content), publish atomico, generazioni immutabili (già nel motore).
  • RNF3 Robustezza: degradazione controllata (workspace senza evidence o senza collection funziona, con warning); errori sanitizzati; nessun fallimento che corrompa la generazione attiva.
  • RNF4 Isolamento per-workspace: ogni filtro Qdrant legato a workspace_id; rifiuto di namespace conflittuali (già implementato nell'adapter).
  • RNF5 Compatibilità: il preprocessing deve funzionare con la config renderizzata dal backend (fingerprint OWNER.json compatibile) — è il vincolo chiave di design (vedi D3).
  • RNF6 Performance: introspezione ~minuti (non nel path di sessione), embedding batch, LSH boundato; il retrieval a runtime non cambia i costi attuali.
  • RNF7 Manutenibilità: nessun fork dei fixture; un solo percorso canonico (O1).
  • RNF8 Integration-first: il successo di un piano tecnico richiede un'esecuzione completa da ambiente pulito, senza retry automatici che mascherino errori; ogni fallimento viene diagnosticato, corretto alla radice e seguito da una nuova esecuzione completa.
  • RNF9 Evidenza e cleanup: ogni ambiente simulato ha identità/ownership esplicita, risorse univoche, segreti fittizi, report machine-readable e leggibile, scansione anti-secret e cleanup confinato alle sole risorse possedute dal run.

8. Standard di esecuzione e verifica — integration-first

Questo standard si applica a P1 e, ovunque sia tecnicamente significativo, a tutti i piani successivi. Un piano che non possa applicarlo deve motivare esplicitamente l'eccezione e definire il verifier più vicino possibile al processo reale.

S1 — Goal automatico di processo

  • Ogni piano definisce il processo completo entro il proprio scope, con punto iniziale pulito, input, componenti attraversati, risultato osservabile e criteri di successo.
  • Il goal non è "far passare alcuni test", ma simulare con successo il processo operativo che la feature deve rendere possibile. Per P1 il confine completo è Git → registry → API → snapshot/docs → render → tht config check; estrazione evidence e Qdrant appartengono ai piani successivi.
  • Durante l'esecuzione il goal resta aperto fino a una prova integrale verde. Se l'ambiente agentico supporta goal persistenti, l'esecutore lo registra all'inizio e lo completa soltanto dopo l'evidenza finale.

S2 — Ambiente di integrazione isolato

  • Il test costruisce dipendenze controllate sotto .artifacts/<plan>/<run-id>/: repository Git simulati, checkout, roots runtime, secret fixture, richieste/risposte, log e output.
  • Ogni run usa identità e nomi univoci e un manifest di ownership; non usa credenziali, repository o dati reali salvo quando il piano dichiara esplicitamente un gate L2.
  • I servizi reali appartenenti allo scope vengono attraversati tramite le loro interfacce normali; quelli esterni o non ancora nello scope sono sostituiti da fixture fedeli e deterministiche.

S3 — Contratto di successo

  • Il test parte da stato pulito, esegue il processo una volta senza retry automatici, termina con exit code zero e produce report.json più un report leggibile.
  • Un fallimento richiede diagnosi della causa, test regressivo/correzione e una nuova esecuzione completa da stato pulito; ripetere alla cieca non costituisce progresso verso il goal.
  • Il gate finale comprende determinismo/idempotenza pertinenti, scansione anti-secret, verifica degli artefatti e prova del cleanup confinato. Gli artefatti possono essere conservati con --keep per review.

S4 — Interventi umani inevitabili

  • Passi umani iniziali o intermedi sono ammessi solo quando non simulabili in modo affidabile (per esempio accesso approvato a un sistema reale o review di contenuto curato).
  • Ogni passo umano dichiara precondizioni, istruzioni, evidenza richiesta, criterio di decisione e checkpoint di ripresa; l'automazione copre e verifica tutto ciò che precede e segue il checkpoint.
  • Un intervento umano non può essere sostituito da un'assunzione silenziosa né rendere non riproducibile il resto del processo.

S5 — Walkthrough manuale successivo

  • Dopo il goal automatico verde, il reviewer ripete il processo in un ambiente nuovo e separato, usando le interfacce reali e una guida passo-passo che spiega componente, stato letto, artefatto prodotto e invariante verificata.
  • Il walkthrough serve a comprensione architetturale e accettazione; non sostituisce l'integration test e non ne riusa lo stato già mutato.
  • Lo stato di consegna distingue almeno automated integration: PASS e manual acceptance: PENDING/PASS. Un piano non è pienamente accettato finché l'eventuale gate manuale richiesto non è stato deciso dal reviewer.

S6 — Contenuto obbligatorio dei piani

Ogni piano tecnico riporta, adattandoli al proprio scope:

  1. Automated process goal e comando unico di esecuzione;
  2. topologia dell'ambiente simulato e confini delle dipendenze;
  3. asserzioni del full integration test e contratto del report;
  4. checkpoint umani inevitabili, oppure dichiarazione esplicita che non ve ne sono;
  5. walkthrough/gate manuale successivo, quando utile;
  6. evidenze di completamento, retention degli artefatti e cleanup esatto.

9. Criteri di accettazione (bozza)

  1. Da un repository registry vuoto si arriva a una sessione funzionante seguendo solo i manuali aggiornati, senza toccare file fixture.
  2. La CLI di preprocessing funziona sia sul PC/Mac dell'utente sia sul server che ospita il DWH (stesso comando, config derivata dal workspace).
  3. La configurazione di un workspace dichiara e usa uno dei tre trasporti DWH (postgres_direct, rest_api, ssh_tunnel); PSD usa rest_api.
  4. Il goal automatico P1 costruisce da zero repository Git simulati e ambiente isolato, attraversa con HTTP reale il processo Git → registry → validate/publish/read/export → snapshot/docs → render → tht config check, supera casi positivi e negativi senza retry e produce report/artefatti secret-free.
  5. Solo dopo il punto 4, un ambiente manuale nuovo avvia il backend su 127.0.0.1:8791 e permette al reviewer di ripetere ogni chiamata e ispezionare commit, snapshot, ZIP e config renderizzate seguendo una guida; il gate resta PENDING finché il reviewer non lo approva.
  6. search pack di una domanda reale restituisce tabelle (con descrizioni), evidence della generazione ACTIVE e solved dello stesso workspace; F4/F6 mostrano le FK curate.
  7. qdrantEnsure/ollamaEnsure verdi all'ammissione; la collection ha esattamente 1024/cosine + gli 8 keyword-index.
  8. Rerun del preprocessing: unchanged (nessun duplicato); modifica di un'evidence → nuova generazione, ACTIVE aggiornato, vecchie generazioni in GC.
  9. Smoke end-to-end automatico verde in CI con cleanup esatto (stile preprocess-smoke.sh).
  10. Migrazione PSD documentata e provata almeno in dry-run (re-introspection o riuso catalogo + re-embedding).
  11. Ogni piano tecnico successivo include un process goal automatico completo per il proprio scope e un walkthrough manuale quando utile, oppure documenta l'inevitabile eccezione umana secondo S4.

10. Decisioni chiuse (2026-08-09)

La sezione nasceva come "punti di discussione"; le decisioni sono state prese con il proprietario del prodotto il 2026-08-09. Ogni punto resta il riferimento del proprio piano (sez. 11). Le opzioni scartate sono omesse; la motivazione della scelta è inclusa in ogni punto.

D1 — Config per-workspace: c) misto, con sorgente completa nel descriptor

  • Il descriptor v3 guadagna una sezione evidence che configura tutta la lettura della sorgente: protocollo/tipo, URI/sorgente, eventuali parametri non-secret.
  • Si usa un unico repository Git registry per tutti i workspace. Ogni workspace possiede il proprio tree versionato sotto <workspace_id>/evidence/; per PSD il path canonico è psd/evidence/.
  • Per filesystem, l'URI del descriptor è repo-relative, confinata al namespace dello stesso workspace e risolta dalla stessa revisione Git del descriptor. Sono vietati path assoluti, traversal e riferimenti al contenuto di un altro workspace; il controllo reale di symlink/containment durante la materializzazione appartiene a P6.
  • Eventuali segreti (HTTP autenticato, S3) restano in overlay d'installazione — invariante: nessun segreto nel repo/descriptor.
  • P1 applica lo standard integration-first: prima persegue un goal automatico Git→registry→HTTP→render→ harness sotto .artifacts/p1-integration/<run-id>/, poi offre un walkthrough manuale separato sotto .artifacts/manual-acceptance/p1/. Non include ancora estrazione, embedding o verifica degli artefatti artifacts/evidence (P2+P6).

D2 — Esecuzione: CLI sul host in release 0; GUI in release futura

  • Release 0: una CLI installata con ThothII sul host — sia il PC/Mac dell'utente sia il server che ospita il DWH — che esegue tutta la catena di preprocessing (DWH introspect+LSH, FK, index-schema, evidence e quanto serve) per un workspace del registry.
  • La CLI deriva la config dal descriptor+bindings con la stessa identità del runtime → soddisfa il vincolo D3 senza dipendere dal backend.
  • Release futura (fuori scope): comando avviabile dalla GUI (endpoint backend da progettare poi).

D3 — Fingerprint .tht-dwh: accettare il vincolo + documentarlo

  • Le generazioni DWH restano legate alla config effettiva (workspace_id + config_fingerprint + input_fingerprint in OWNER.json).
  • La CLI (D2) gira con la config derivata dal descriptor+bindings, quindi identica alla runtime.
  • La documentazione di progetto deve spiegare chiaramente cos'è .tht-dwh (directory delle generazioni catalogo/LSH, OWNER.json, ACTIVE pointer, perché il fingerprint protegge da artefatti di un'altra config) — oggi non è chiaro.

D4 — Bootstrap collection: self-heal all'ammissione + CLI delete/recreate

  • Se la collection non esiste all'ammissione sessione, il runtime la crea (1024/cosine + payload keyword-index) — self-heal.
  • La CLI deve poter cancellare e ricreare le collection (rebuild esplicito, con guardie di sicurezza).

D5 — Versioning artifacts curati: c) misto

  • annotations.yaml (cura FK, cura umana) versionata nel repository registry e sincronizzata ai roots runtime (il registry copia il file negli snapshots → sync).
  • physical.yaml (derivato dall'introspezione) rigenerato localmente, non versionato.

D6 — Evidence: a) nell'unico repository registry, con namespace per-workspace

  • Ogni workspace contiene il proprio tree versionato sotto <workspace_id>/evidence/; le dimensioni non sono un vincolo.
  • P6 materializza il tree dalla stessa revisione Git del descriptor, verifica il containment reale (inclusi i symlink) e lo rende disponibile al preprocessing senza usare un checkout mobile.
  • HTTP/S3 restano opzioni future per sorgenti esterne (il motore le supporta già).

D7 — Migrazione PSD: inclusa, con accesso al server

  • Il piano P7 copre: riuso di physical.yaml + annotations.yaml + evidence .md dal repository registry; export dal pgvector del server PSD (accesso disponibile); re-embedding con qwen3-embedding:0.6b; dry-run documentato.

D8 — Verifica end-to-end: integration-first + walkthrough manuale; remote Git libero; DWH multi-trasporto

  • Ogni fase adotta lo standard della sez. 8: prima un process goal automatico da ambiente pulito, poi — quando utile o richiesto — un walkthrough manuale su stato separato. P1 è il primo riferimento concreto.
  • Il livello finale del PRD resta: smoke automatico su workspace sintetico (CI) + gate manuale L2 su PSD.
  • Il namespace PSD sarà prima alimentato nel repository registry (descriptor + evidence + annotations nello stesso flusso Git), poi usato da ThothII. Accesso al server PSD disponibile.
  • Remote Git: lo creiamo noi, nessun vincolo tecnico (consigliato GitHub via HTTPS; SSH resta possibile se servirà).
  • Trasporto DWH: PSD via REST (come oggi); la configurazione deve prevedere le tre modalità — rest_api, postgres_direct, ssh_tunnel — perché altri database potrebbero richiedere accesso TCP diretto o via tunnel. Oggi ssh_tunnel è solo diagnostico a runtime: va reso operativo dove serve (vedi P10).

D9 — Retention/GC: confermata

  • Default invariati (retain_published_generations: 3, chunk 4000 char), configurabili per-workspace via la sezione evidence/policy del descriptor (D1).

11. Mappa dei piani (uno per punto del PRD)

Questo PRD non diventa un unico piano: ogni decisione/requisito produce un piano separato (P1–P10) in docs/superpowers/plans/, eseguibile in sequenza o come workstream indipendenti. Il PRD resta il riferimento stabile (requisiti + decisioni); ogni piano cita il punto di origine e i criteri di accettazione applicabili (sez. 9) e adotta lo standard integration-first (sez. 8).

Piano Punto PRD Contenuto sintetico Dipende da
P1 D1 Descriptor v3: sezione evidence (protocollo/tipo, URI repo-relative sotto <id>/evidence/) + policy e isolamento namespace; goal automatico Git→registry→HTTP→render→harness, seguito da walkthrough manuale —
P2 D2 CLI di preprocessing sul host (release 0): comando per-workspace che esegue l'intera catena (DWH, FK, index-schema, evidence) con la config derivata da descriptor+bindings; funziona su PC/Mac utente e server DWH P1
P3 D3 Vincolo fingerprint .tht-dwh (test: preprocess con config identica alla runtime) + documentazione di progetto su cos'è .tht-dwh P2
P4 D4 Bootstrap collection: self-heal all'ammissione (creazione 1024/cosine + keyword-index) + comandi CLI delete/recreate con guardie —
P5 D5 annotations.yaml versionata nel repository registry + sync registry → roots runtime P1
P6 D6 Materializzazione del tree <id>/evidence/ dalla revisione Git fissata → preprocess; containment reale e protezione da symlink escape P1
P7 D7 Migrazione PSD: riuso catalogo/annotations/evidence, export pgvector (accesso server), re-embedding, dry-run P1–P6
P8 D8 Verifica end-to-end: smoke CI + gate L2 su PSD (namespace PSD nel repository registry alimentato prima dell'uso; remote Git a scelta) P1–P7
P9 D9 GC/retention per-workspace: policy configurabili, default invariati P1
P10 D8/RF1.4 Trasporti DWH operativi: rendere ssh_tunnel utilizzabile a runtime e nella CLI di preprocessing (oggi solo diagnostico); verifica dei tre trasporti (direct, REST, tunnel) P1, P2

Standard di verifica obbligatorio del futuro piano P1

P1 è il primo piano che applica integralmente la sez. 8 e deve contenere due task/gate distinti e ordinati.

1. Automated integration goal — complete P1 configuration process

Un comando unico (nome definitivo nel piano, interfaccia indicativa ./scripts/p1-acceptance.sh integration --keep) costruisce da zero:

.artifacts/p1-integration/<run-id>/
├── ownership.json
├── remote.git/                   # remote bare locale
├── author/                       # clone curatore + tree evidence
├── installation/                # checkout, snapshot e stato registry
├── runtime-data/
├── fixture-secrets/
├── requests/                     # payload HTTP positivi/negativi
├── responses/
├── rendered/
├── exports/
├── logs/
├── report.json
└── report.md

Il test attraversa le interfacce reali appartenenti a P1: Git reale locale, backend Fastify su una porta loopback temporanea, route HTTP validate/publish/pull/read/export, snapshot/docs/contract, renderer di produzione e tht config check. Verifica anche stessa revisione Git per descriptor/tree, determinismo, path/protocolli/secret fields invalidi, assenza di leak e cleanup confinato. Non usa frontend, Docker, DWH, Qdrant o Ollama perché non appartengono allo scope P1.

L'esecuzione non applica retry automatici. In caso di errore l'esecutore diagnostica, aggiunge la copertura regressiva necessaria, corregge e rilancia l'intero scenario da una nuova root pulita. Il goal è raggiunto solo con exit code zero e report integralmente verde; con --keep le evidenze restano disponibili.

2. Manual acceptance gate — descriptor and rendered configuration artifacts

Dopo il goal automatico verde, il piano prepara uno stato nuovo e indipendente sotto:

.artifacts/manual-acceptance/p1/
├── remote.git/
├── author/
├── installation/
├── runtime-data/
├── requests/
├── responses/
├── output/
├── logs/
└── GUIDE.md

Un helper esegue soltanto prepare/serve/stop/cleanup; serve avvia il backend reale sull'host, senza Docker e senza frontend, vincolato a 127.0.0.1:8791. Il reviewer segue GUIDE.md ed esegue personalmente le chiamate HTTP, i comandi Git, l'export ZIP, il doppio rendering, il confronto e tht config check, poi prova i casi invalidi e decide il gate.

Il gate verifica manualmente: sezione evidence; pubblicazione/rilettura; commit e snapshot immutabile; workspace docs/contract; config harness; assenza di segreti; sicurezza protocollo/path e isolamento cross-workspace; output deterministico. Gli artefatti restano fino alla decisione e il cleanup rimuove solo la root posseduta dal test.

P1 non dichiara di aver generato o validato artifacts/evidence: estrazione e mirroring richiedono P2+P6; record Qdrant, embedding, generazioni ACTIVE e retention appartengono ai piani successivi. Dopo il goal automatico lo stato è automated integration: PASS / manual acceptance: PENDING; P1 diventa pienamente accettato soltanto dopo la decisione del reviewer.

Ordine consigliato: P1 → P2 → P3 (catena config/esecuzione), P4 e P5/P6 in parallelo dopo P1, poi P7 → P8; P9 può essere assorbito in P1 o restare autonomo; P10 dopo P1+P2 (necessario solo se un workspace target richiede davvero il tunnel — per PSD non serve, usa REST).

Ogni piano segue la prassi del repo: TDD, commit scoping, verifica layer (pytest/vitest/tsc/build) e lo standard della sez. 8; gate deployment e smoke Docker si aggiungono quando appartengono allo scope. Lo stato traccia separatamente implementazione, automated integration e manual acceptance.

12. Storico revisioni

Versione Data Contenuto
v0.1 2026-08-09 Bozza da analisi dello stato attuale (gap preprocessing per-workspace)
v0.2 2026-08-09 Decisioni D1–D9 chiuse con il proprietario; mappa piani P1–P10; requisiti RF1–RF8 aggiornati (evidence nel descriptor, CLI sul host, self-heal collection, multi-trasporto DWH)
v0.3 2026-08-09 Revisione di coerenza (numerazioni, riferimenti incrociati, header di stato) — pronto per revisione del proprietario
v0.4 2026-08-09 D1/D6: repository registry unico, namespace workspace-content/<id>/evidence/ (percorso storico P1, superseded da P1.1), pin alla stessa revisione Git e gate manuale P1 con remote locale usa-e-getta sotto .artifacts/
v0.5 2026-08-09 Standard integration-first per P1–P10: process goal automatico completo da ambiente simulato e pulito, gestione esplicita degli interventi umani inevitabili e walkthrough manuale successivo su stato separato

13. Riferimenti

  • Stato attuale: PROJECT_STATE.md (sezioni "Internal Qdrant + Ollama semantic infrastructure", snapshot registry) e AGENTS.md.
  • Design architettura semantica: docs/plans/2026-08-08-internal-qdrant-ollama-design.md e relativo piano.
  • Registry: docs/superpowers/specs/2026-08-03-git-workspace-registry-design.md, manuali docs/install/local-workspace-registry.md / server-workspace-registry.md.
  • Motore preprocessing: harness/tht/cli/preprocess_cmd.py, harness/tht/corpus/pipeline.py, harness/tht/jobs/dwh_pipeline.py, harness/tht/adapters/vector/qdrant.py, harness/tht/vectorstore/records.py, harness/tht/cli/{vector,schema,evidence,memory}_cmd.py.
  • Fixture attuali: deploy/compose.preprocess.yaml, deploy/workspaces/preprocess-{dwh,evidence}.yaml, scripts/preprocess-smoke.sh.
  • Ammissione runtime: backend/src/tht/tht-runner.ts (qdrantEnsure/ollamaEnsure), backend/src/workspaces/runtime-renderer.ts.
Reference in New Issue View Git Blame Copy Permalink