From d857004f47218d6071aaec89c16b996ab0f07616 Mon Sep 17 00:00:00 2001 From: mptyl Date: Sat, 27 Jun 2026 12:52:58 +0200 Subject: [PATCH] docs(plan): allinea piano alle 3 correzioni spec (drop registry, repo workspace, LSH) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Task 3.2: nuovo Step 1b — drop funzioni registry da memory_cmd + tht/memory.py (load/save/update/delete/promote/reusable_promotions); promotion (F5) riscritta come upsert batch al vectordb; memory list/delete su vectordb (no registry). - Skill F2/F5: drop riferimenti a 'memory promote + memory index' con registry. - Onda 0b riscritta: repo workspace per-cliente separato (no copia in harness/), LSH scarica-tutti-i-valori-distinti (no 'campiona'), indice nel repo workspace cliente. --- .../plans/2026-06-27-tht-porting-cli-skill.md | 75 +++++++++---------- 1 file changed, 36 insertions(+), 39 deletions(-) diff --git a/docs/superpowers/plans/2026-06-27-tht-porting-cli-skill.md b/docs/superpowers/plans/2026-06-27-tht-porting-cli-skill.md index 0e201600..ee8b3a40 100644 --- a/docs/superpowers/plans/2026-06-27-tht-porting-cli-skill.md +++ b/docs/superpowers/plans/2026-06-27-tht-porting-cli-skill.md @@ -820,6 +820,16 @@ for cmd in memory_cmd search_cmd evidence_cmd db_cmd decision_cmd; do done ``` +- [ ] **Step 1b: Drop funzioni registry da memory_cmd + tht/memory.py (decisione spec 5)** + +Le memory vivono SOLO nel vectordb; il `registry.jsonl` è vestigiale e droppato. In `tht/memory.py` NON portare le 6 funzioni che lo gestiscono: `load_registry`, `save_registry`, `update_record`, `delete_record`, `promote(registry_path)`, `reusable_promotions`. In `memory_cmd.py` i comandi che le usavano (`memory promote`, `memory list`, `memory delete` con il vecchio modello) vanno riscritti o droppati: +- `memory promote` → riscritto come upsert batch al vectordb (usa `memory_vector_records` + `writer.upsert_records`, analogo a `save_one_memory` ma su una lista). La skill F5 chiama questo. +- `memory list` → scan del vectordb (reader). +- `memory delete` → upsert con `metadata.status="superseded"` (il writer è upsert-only, niente DELETE fisico). +- `memory search` → invariato (legge dal vectordb, l'hit ha già metadata completo grazie al Task 3.1). + +**Conservare in `tht/memory.py`:** `MemoryRecord`, `memory_vector_records`, `memory_vector_record_for_decision`, `save_one_memory`. Le decisioni restano nel ledger di sessione (`review_decisions.jsonl`, per-sessione, gestito da `tht/decisions.py` — separato dalle memory). + - [ ] **Step 2: Fix drift costanti phase (manuale, per file)** Per ciascun file che le usa (verifica con `grep -nE "MAX_PHASE|PHASE_NAMES|SCHEMA_LINKING_PHASE|DECISION_MIN_PHASE" tht/cli/*_cmd.py`), correggi: @@ -1011,7 +1021,7 @@ Adatta F1 da ChironeWp3 (righe 93-119). Cambi: nomi Thoth, vocabolario widget. S - [ ] **Step 3: Scrivi F2 (Memorie) con save-one D11** -Adatta F2. Cambi chiave: in `profile=workstation`, la promozione di UNA memoria usa `tht memory save-one` (D11). La skill guida: una memoria → `save-one`, molte → `memory promote + memory index`. `tht memory search` ritorna hit con metadata completo (subject/detail/rationale grazie al Task 3.1), quindi il modello ricostruisce la decisione direttamente dall'hit senza lookup registro. +Adatta F2. **Cambio chiave (drop registry, decisione spec 5):** le memory vivono SOLO nel vectordb. La skill F2 usa `tht memory search` per trovare memorie; l'hit ha metadata completo (subject/detail/rationale grazie al Task 3.1), quindi il modello ricostruisce la decisione direttamente dall'hit. **Niente `memory promote` + `memory index` con registry** (vestigiale, droppato): la promotion (F5) è upsert diretto a vectordb (`save-one` per una memoria, batch per molte). - [ ] **Step 4: Scrivi F3 (Riscrittura)** @@ -1027,7 +1037,7 @@ Mantieni i tipi esistenti (table_promoted/excluded/column_corrected/join_modifie - [ ] **Step 6: Scrivi F5 (Sintesi) + F6 (CTE) + F7 (SQL) + F8 (Datamart)** -Adatta F5-F8 da ChironeWp3 (righe 198-358). Praticamente invariate nella sostanza (schema_linking.json, session check, memory promote, reviewer_confirm kind:phase; CTE plan/test/result; SQL validate/explain/preview/save/export; datamart sì/no stub). Solo vocabolario widget + nomi Thoth + `nsp`→`tht`. +Adatta F5-F8 da ChironeWp3 (righe 198-358). Praticamente invariate nella sostanza (schema_linking.json, session check, **promotion memory = upsert batch diretto a vectordb** [drop registry, vedi decisione spec 5], reviewer_confirm kind:phase; CTE plan/test/result; SQL validate/explain/preview/save/export; datamart sì/no stub). Solo vocabolario widget + nomi Thoth + `nsp`→`tht`. - [ ] **Step 7: Verifica coerenza cmd** @@ -1066,45 +1076,36 @@ sql-generation adattati. Nessun riferimento chirone/psd." --- -## Onda 0b — Setup pre-sessione (evidence + LSH build) +## Onda 0b — Setup pre-sessione (repo workspace per-cliente + LSH build) -### Task 0b.1: Copia evidence dentro ThothII +**Principio (decisioni spec 7+8):** ThothII è generico. Il contenuto evidence e gli indici LSH sono **per-cliente**, in un repo workspace separato. Niente copia in `harness/`. -- [ ] **Step 1: Verifica la cartella sorgente esiste** +### Task 0b.1: Prepara il repo workspace per-cliente -Run: `ls -d /Users/mp/Chirone/chirone/etl/docs && du -sh /Users/mp/Chirone/chirone/etl/docs` -Expected: la cartella esiste, ~11M. +Per il test L2, il cliente è PSD (aritmologia @ policlinico). Il contenuto evidence esiste già sul disco del dev (`/Users/mp/Chirone/chirone/etl/docs`). -- [ ] **Step 2: Revisione PII (prima di committare)** - -Run (cerca dati che sembrano PII — codici fiscali, nomi+date, ecc.): -```bash -grep -rniE "codice fiscale|fiscal|[A-Z]{6}\d{2}[A-Z]\d{2}[A-Z]\d{3}[A-Z]" /Users/mp/Chirone/chirone/etl/docs 2>/dev/null | head -``` -Se trova PII → NON committare; metti `harness/evidence/` in `.gitignore` e distribuisci fuori banda. Se pulito → procedi. - -- [ ] **Step 3: Copia la cartella** +- [ ] **Step 1: Crea la struttura del repo workspace cliente** ```bash -cp -r /Users/mp/Chirone/chirone/etl/docs harness/evidence +# Il repo workspace è SEPARATO da ThothII. Per il test locale lo si crea accanto. +mkdir -p /Users/mp/projects/tht-workspace-psd/evidence +# Collega/copialo l'evidence esistente (curata a mano, 229 markdown, ~11M) +cp -r /Users/mp/Chirone/chirone/etl/docs/* /Users/mp/projects/tht-workspace-psd/evidence/ +# Workspace YAML cliente (copia del template, parametrizzato per PSD) +cp /Users/mp/projects/ThothII/harness/workspaces/tht.example.yaml \ + /Users/mp/projects/tht-workspace-psd/psd.yaml ``` +> Il repo `tht-workspace-psd/` va git-init separatamente (è per-cliente, non parte di ThothII). Per il test locale si usa così com'è. -- [ ] **Step 4: Aggiorna THT_DOCS_ROOT nel .env + tht-test.yaml** +- [ ] **Step 2: Configura il .env per puntare al repo workspace cliente** ```bash cd /Users/mp/projects/ThothII/harness -# .env: imposta THT_DOCS_ROOT al path dentro ThothII -sed -i '' -E 's|^THT_DOCS_ROOT=.*|THT_DOCS_ROOT=harness/evidence|' .env +# THT_DOCS_ROOT punta all'evidence del repo cliente (NON a harness/evidence) +sed -i '' -E 's|^THT_DOCS_ROOT=.*|THT_DOCS_ROOT=/Users/mp/projects/tht-workspace-psd/evidence|' .env ``` -In `workspaces/tht-test.yaml`, aggiungi/verifica il blocco evidence: -```yaml -evidence: - source_root: ${THT_DOCS_ROOT} - evidence_dir: evidence -``` - -- [ ] **Step 5: Verifica tht search --kind evidence funziona** +- [ ] **Step 3: Verifica tht search --kind evidence funziona** Run (dopo Onda 3 che porta search_cmd): ```bash @@ -1113,17 +1114,13 @@ set -a; . ./.env; set +a ``` Expected: risultati non vuoti. -- [ ] **Step 6: Commit (se PII-pulito)** +- [ ] **Step 4: Documenta il deploy nel README** -```bash -git add harness/evidence/ .env # .env è gitignored normalmente; verificare -git add -f .env 2>/dev/null || echo "(.env gitignored, salto)" -git commit -m "feat(harness): evidence dentro ThothII (Onda 0b) — self-contained" -``` +Il README ThothII deve spiegare la struttura deploy: `checkout ThothII + checkout tht-workspace- + .env punta al repo cliente`. Aggiorna la sezione "Configure" del README. -> **Attenzione:** `.env` è gitignored. NON committarlo con `-f` se contiene chiavi reali. Il default `THT_DOCS_ROOT=harness/evidence` va invece in `.env.example`. +### Task 0b.2: Build indice LSH (scarica TUTTI i valori distinti, per-cliente) -### Task 0b.2: Build indice LSH sul workspace tht-test +**Principio (decisione spec 8):** `tht lsh build` scarica tutti i valori distinti scaricabili delle colonne di testo dal DWH (NON "campiona"), costruisce MinHash+LSH, serializza nel path `indexes/` del **repo workspace cliente**. - [ ] **Step 1: Verifica prerequisiti (VPN + Ollama + lsh_cmd portato)** @@ -1132,13 +1129,13 @@ curl -s --max-time 2 http://localhost:11434/api/tags >/dev/null && echo "ollama .venv/bin/tht lsh --help >/dev/null 2>&1 && echo "lsh_cmd OK" || echo "lsh_cmd NON portato (verifica Onda 4)" ``` -- [ ] **Step 2: Build indice (one-shot)** +- [ ] **Step 2: Build indice (one-shot, per il workspace cliente PSD)** ```bash set -a; . ./.env; set +a -.venv/bin/tht lsh build --workspace workspaces/tht-test.yaml +.venv/bin/tht lsh build --workspace /Users/mp/projects/tht-workspace-psd/psd.yaml ``` -Expected: indice costruito in `indexes/`, nessun errore. Richiede VPN (DWH raggiungibile). +Expected: indice costruito in `/indexes/`, nessun errore. Richiede VPN (DWH raggiungibile). - [ ] **Step 3: Verifica tht search ritorna match LSH multi-colonna**