fix(harness): remediation difetti review — gate↔CLI, D15, D7/D6, D14, robustezza

Implementazione del piano di remediation progressiva sui difetti emersi
dall'analisi dell'harness. Tutto verificato: 214 test Python (incl. L0 su
Postgres reale), 14 test JS del gate, ruff pulito.

Blocco 1 (CRITICA, integrazione gate↔CLI):
- phase advance: gate usa --auto + exit 6; reviewer_confirm kind:phase fa
  advance esplicito che applica i prerequisiti (prima non avanzava per le
  fasi a conferma umana).
- cte plan riceve i --name dal gate (param names); set-question con id
  posizionale; skill `tht search find`; nuovo comando `tht memory save-one`
  con dedup hash client-side in save_one_memory.

Blocco 2 (D15, stato post-rollback):
- campo `phase` su DecisionRecord + effective_decisions phase-aware per i
  subject "a nome" (cte_approved ecc.); _compute_promotions e finalize sulla
  vista effective; finalize confronta col piano CTE effettivo, non glob;
  `decision add --retracts` + comando `decision retract`.

Blocco 3 (D7 read-only + D6 manifest):
- assert_read_only su tutti e quattro i codepath (direct + REST);
- manifest author/summary/updated_at/updated_by/schema_version popolati +
  helper touch_manifest sulle mutazioni.

Blocco 4-5 (D14a/D14b):
- decision_min_phase data-driven via `emits:` in workflow.yaml;
- formula evidence: status auto, search_formulas, gruppo CLI `tht formula`,
  `search find --kind formula`, load_evidence_dir salta i .sql.md.

Blocco 6 (robustezza):
- taskdoc slice promoted_tables + bound enforced; report escaping/bound +
  rsplit note; filtro kind reader REST/direct; conteggio upserted robusto;
  guard REST run_query non-list; LSH disallineato -> LshIndexError.

Blocco 7 (pulizia):
- dead code gate e KIND_TO_TABLE morto rimossi; doc Postgres-only
  (README + connection.py).

Blocco 0 (parziale): test di compatibilità firma gate↔CLI
(tests/integration). Rinviati: fake-Pi runtime completo, artifact-gate da
disco (#23), parità eligibility REST/direct (#28), unificazione
reserved-labels (#30), memory_rejected da deselezione (#33).

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

harness/tht/cli/__init__.py

@@ -42,6 +42,7 @@ from tht.cli.datamart_cmd import datamart_app  # noqa: E402
 from tht.cli.db_cmd import db_app  # noqa: E402
 from tht.cli.decision_cmd import decision_app  # noqa: E402
 from tht.cli.evidence_cmd import evidence_app  # noqa: E402
+from tht.cli.formula_cmd import formula_app  # noqa: E402
 from tht.cli.lsh_cmd import lsh_app  # noqa: E402
 from tht.cli.memory_cmd import memory_app  # noqa: E402
 from tht.cli.phase_cmd import phase_app  # noqa: E402
@@ -59,6 +60,7 @@ app.add_typer(vector_app, name="vector")
 app.add_typer(memory_app, name="memory")
 app.add_typer(search_app, name="search")
 app.add_typer(evidence_app, name="evidence")
+app.add_typer(formula_app, name="formula")
 app.add_typer(db_app, name="db")
 app.add_typer(decision_app, name="decision")
 app.add_typer(sql_app, name="sql")

harness/tht/cli/decision_cmd.py

@@ -17,6 +17,10 @@ def add_cmd(
     subject: str = typer.Option(..., "--subject", help="Oggetto (tabella, colonna, concetto)."),
     detail: str = typer.Option("", "--detail"),
     rationale: str = typer.Option("", "--rationale"),
+    retracts: int = typer.Option(
+        None, "--retracts",
+        help="Solo per type=decision_retracted: seq della decisione da ritirare (D15).",
+    ),
     config: Path = CONFIG_OPT,
 ) -> None:
     """Registra una decisione del reviewer nella sessione."""
@@ -31,6 +35,12 @@ def add_cmd(
             fg=typer.colors.RED, err=True,
         )
         raise typer.Exit(code=1)
+    if type == "decision_retracted" and retracts is None:
+        typer.secho(
+            "ERRORE: decision_retracted richiede --retracts <seq> (la decisione da ritirare).",
+            fg=typer.colors.RED, err=True,
+        )
+        raise typer.Exit(code=1)
     from tht.cli.phase_cmd import require_phase_or_exit
     from tht.workflow import load_workflow
 
@@ -60,12 +70,53 @@ def add_cmd(
             raise typer.Exit(code=5)
     record = append_decision(
         sdir, type=type, subject=subject,
-        detail=detail, rationale=rationale,
+        detail=detail, rationale=rationale, retracts=retracts,
     )
     typer.secho(f"OK: decisione [{record.seq}] {record.type}: {record.subject}",
                 fg=typer.colors.GREEN)
 
 
+@decision_app.command("retract")
+def retract_cmd(
+    session: str = typer.Option(..., "--session", help="Id della sessione."),
+    config: Path = CONFIG_OPT,
+) -> None:
+    """Ritira l'ultima decisione sostanziale della fase corrente (D15 granularita' step).
+
+    Granularita' (a) del rollback §4.8: 'rispondi di nuovo a questa domanda'. Scrive un
+    marker decision_retracted (append-only, l'audit resta) che effective_decisions onora;
+    il widget corrente puo' essere riproposto. Non cambia la fase."""
+    from tht.decisions import append_decision
+    from tht.phase import effective_decisions
+
+    cfg = _load_config_or_exit(config)
+    load_session_or_exit(cfg, session)
+    sdir = session_dir(cfg, session)
+
+    # Ultima decisione NON-meta della vista effective = quella associata al widget corrente.
+    meta = {
+        "phase_approved", "phase_auto_approved", "phase_reopened",
+        "phase_skipped", "decision_retracted",
+    }
+    substantive = [d for d in effective_decisions(sdir) if d.type not in meta]
+    if not substantive:
+        typer.secho(
+            "Nessuna decisione sostanziale da ritirare nella fase corrente.",
+            fg=typer.colors.YELLOW, err=True,
+        )
+        raise typer.Exit(code=6)
+    target = substantive[-1]
+    record = append_decision(
+        sdir, type="decision_retracted", subject=target.subject,
+        rationale=f"ritira [{target.seq}] {target.type}", retracts=target.seq,
+    )
+    typer.secho(
+        f"OK: ritirata decisione [{target.seq}] {target.type}: {target.subject} "
+        f"(marker #{record.seq}).",
+        fg=typer.colors.GREEN,
+    )
+
+
 @decision_app.command("list")
 def list_cmd(
     session: str = typer.Option(..., "--session"),

harness/tht/cli/formula_cmd.py

@@ -0,0 +1,81 @@
+"""tht formula -- concept->SQL formula evidence store (spec D14b, §4.7.2).
+
+Authoring + listing of reusable concept formulas. Retrieval for the workflow is via
+`tht search find --kind formula "<concept>"`. The reviewer approves/rejects a candidate
+formula in F4 (decisions concept_formula_approved / concept_formula_rejected), and the
+approved one is reflected in schema_linking.json (SchemaLinking.concept_formulas).
+"""
+from pathlib import Path
+
+import typer
+
+from tht.cli.config_cmd import CONFIG_OPT
+from tht.cli.evidence_cmd import evidence_root
+from tht.cli.schema_cmd import _load_config_or_exit
+
+formula_app = typer.Typer(help="Formule di concetto (concept -> SQL) riusabili (D14b)")
+
+
+@formula_app.command("save")
+def save_cmd(
+    concept: str = typer.Option(..., "--concept", help="Il concetto, es. 'fascia pediatrica'."),
+    sql_file: Path = typer.Option(
+        None, "--sql-file", help="File con l'espressione SQL della formula."
+    ),
+    sql: str = typer.Option(None, "--sql", help="Espressione SQL inline (alternativa a --sql-file)."),
+    column: list[str] = typer.Option(None, "--column", help="Colonna usata (ripetibile)."),
+    status: str = typer.Option("draft", "--status", help="auto | draft | reviewed."),
+    source: list[str] = typer.Option(None, "--source", help="Fonte/evidence (ripetibile)."),
+    config: Path = CONFIG_OPT,
+) -> None:
+    """Salva una formula di concetto sotto artifacts/evidence/formulas/."""
+    from tht.evidence.formula_store import ConceptFormula, save_formula
+
+    cfg = _load_config_or_exit(config)
+    if sql_file is None and not sql:
+        typer.secho("ERRORE: indica --sql-file <path> oppure --sql \"<espr>\".",
+                    fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+    body = sql_file.read_text() if sql_file else sql
+    try:
+        formula = ConceptFormula(
+            concept=concept, columns=column or [], sql=body.strip(),
+            status=status, sources=source or [],
+        )
+    except ValueError as e:
+        typer.secho(f"ERRORE: formula non valida: {e}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+    path = save_formula(evidence_root(cfg), formula)
+    typer.secho(f"OK: formula '{concept}' salvata in {path}.", fg=typer.colors.GREEN)
+
+
+@formula_app.command("list")
+def list_cmd(
+    concept: str = typer.Option(None, "--concept", help="Filtra per concetto (substring)."),
+    json_out: bool = typer.Option(False, "--json"),
+    config: Path = CONFIG_OPT,
+) -> None:
+    """Elenca le formule salvate (tutte, o filtrate per concetto)."""
+    import json as _json
+
+    from rich.console import Console
+    from rich.table import Table
+
+    from tht.evidence.formula_store import _load_all, search_formulas
+
+    cfg = _load_config_or_exit(config)
+    root = evidence_root(cfg)
+    formulas = search_formulas(root, concept) if concept else _load_all(root)
+    if json_out:
+        typer.echo(_json.dumps([f.model_dump(mode="json") for f in formulas],
+                               ensure_ascii=False, indent=2))
+        return
+    if not formulas:
+        typer.secho("Nessuna formula salvata.", fg=typer.colors.YELLOW)
+        return
+    t = Table(title="Formule di concetto")
+    for col in ("Concetto", "Status", "Colonne"):
+        t.add_column(col)
+    for f in formulas:
+        t.add_row(f.concept, f.status, ", ".join(f.columns))
+    Console().print(t)

harness/tht/cli/memory_cmd.py

@@ -12,7 +12,11 @@ from sqlalchemy.exc import OperationalError, ProgrammingError
 
 from tht.cli.config_cmd import CONFIG_OPT
 from tht.cli.schema_cmd import _load_config_or_exit
-from tht.cli._guards import require_server_profile, require_vector_write_allowed
+from tht.cli._guards import (
+    has_vector_write_rest,
+    require_server_profile,
+    require_vector_write_allowed,
+)
 from tht.cli.session_cmd import load_session_or_exit, session_dir
 from tht.cli.vector_cmd import require_vector_cfg
 
@@ -132,6 +136,60 @@ def promote_cmd(
         typer.secho(f"ATTENZIONE: {warning}", fg=typer.colors.YELLOW)
 
 
+@memory_app.command("save-one")
+def save_one_cmd(
+    session: str = typer.Option(..., "--session"),
+    decision: int = typer.Option(
+        ..., "--decision", help="decision_seq della decisione da salvare come memoria."
+    ),
+    json_out: bool = typer.Option(False, "--json", help="Output JSON (per Pi)."),
+    config: Path = CONFIG_OPT,
+) -> None:
+    """Upsert mirato (una riga) della memoria di una decisione su pgvector via writer key (D11).
+
+    Promuove la decisione nel registro locale (idempotente) e fa un singolo upsert
+    remoto con dedup hash client-side -- niente full-resync. Abilita il salvataggio
+    di una memoria da postazione remota (workstation) con la sola writer key.
+    """
+    import json as _json
+
+    from tht.cli.vector_cmd import make_embedder
+    from tht.memory import load_registry, promote, save_one_memory
+    from tht.vectorstore.rest_client import VectorRestClient
+
+    cfg = _load_config_or_exit(config)
+    manifest = load_session_or_exit(cfg, session)
+    require_vector_write_allowed(cfg, "memory save-one")
+    if not has_vector_write_rest(cfg):
+        typer.secho(
+            "ERRORE: `memory save-one` richiede la sezione `vector_write_rest` con una "
+            "API key di upsert nel workspace yaml (upsert remoto via writer key).",
+            fg=typer.colors.RED, err=True,
+        )
+        raise typer.Exit(code=4)
+
+    sdir = session_dir(cfg, session)
+    # Promuove la decisione scelta nel registro locale (idempotente: salta se gia' presente
+    # o se stale post-rollback, perche' _compute_promotions usa la vista effective).
+    promote(sdir, manifest, seqs=[decision], registry_path=registry_path(cfg))
+    records = [r for r in load_registry(registry_path(cfg)) if r.session_id == manifest.id]
+
+    writer = VectorRestClient(cfg.vector_write_rest)
+    embedder = make_embedder(cfg.embeddings)
+    count = save_one_memory(records, decision, writer=writer, embedder=embedder)
+
+    msg = (
+        f"{count} memoria salvata su pgvector (decision_seq {decision})."
+        if count
+        else f"Nessun upsert (decisione {decision} assente/stale o memoria gia' aggiornata)."
+    )
+    if json_out:
+        typer.echo(_json.dumps(
+            {"upserted": count, "decision_seq": decision, "message": msg}, ensure_ascii=False))
+        return
+    typer.secho(f"OK: {msg}", fg=typer.colors.GREEN if count else typer.colors.YELLOW)
+
+
 @memory_app.command("clear")
 def clear_cmd(
     yes: bool = typer.Option(False, "--yes", "-y", help="Salta la richiesta di conferma."),

harness/tht/cli/search_cmd.py

@@ -10,6 +10,7 @@ KIND_MAP = {
     "evidence": ["evidence"],
     "schema": ["schema_table", "schema_column"],
     "values": [],  # solo LSH
+    "formula": [],  # solo formula store (D14b), niente LSH/vector
 }
 
 # Default di `--top` per le famiglie diverse da `schema` (numero di risultati). Per `schema`
@@ -30,7 +31,7 @@ def search_cmd(
              "(default: 12 tabelle per schema, 10 altrimenti).",
     ),
     kind: str = typer.Option(
-        None, "--kind", help="Filtra per famiglia: evidence | schema | values."
+        None, "--kind", help="Filtra per famiglia: evidence | schema | values | formula."
     ),
     explain: bool = typer.Option(False, "--explain", help="Mostra anche il testo matchato."),
     json_out: bool = typer.Option(
@@ -57,6 +58,30 @@ def search_cmd(
     if top is None:
         top = cfg.search.top_schema_tables if kind == "schema" else DEFAULT_TOP_FALLBACK
 
+    if kind == "formula":
+        # D14b: recupero formule di concetto dallo store locale (niente LSH/vector).
+        from tht.cli.evidence_cmd import evidence_root
+        from tht.evidence.formula_store import search_formulas
+
+        formulas = search_formulas(evidence_root(cfg), keyword)[:top]
+        if json_out:
+            typer.echo(json.dumps(
+                [f.model_dump(mode="json") for f in formulas], ensure_ascii=False, indent=2))
+            return
+        if not formulas:
+            typer.secho(f"Nessuna formula per '{keyword}'.", fg=typer.colors.YELLOW)
+            return
+        table = Table(title=f"Formule per '{keyword}'")
+        table.add_column("Concetto")
+        table.add_column("Status")
+        table.add_column("Colonne")
+        table.add_column("SQL")
+        for f in formulas:
+            sql_preview = (f.sql[:80] + "…") if len(f.sql) > 80 else f.sql
+            table.add_row(f.concept, f.status, ", ".join(f.columns), sql_preview)
+        Console().print(table)
+        return
+
     lsh_hits = None
     try:
         lsh, minhashes, meta = load_index(

harness/tht/cli/session_cmd.py

@@ -163,7 +163,8 @@ def finalize_cmd(session_id: str = typer.Argument(...), config: Path = CONFIG_OP
     from tht.execute.warnings import plan_warnings, runtime_warnings, static_warnings
     from tht.report import extract_reviewer_notes, render_validation_report
     from tht.session.artifacts import build_evidence_entries
-    from tht.decisions import list_decisions
+    from tht.phase import cte_plan as effective_cte_plan
+    from tht.phase import effective_decisions
     from tht.session.models import SchemaLinking
     from tht.sqlcheck import validate_sql
 
@@ -186,8 +187,9 @@ def finalize_cmd(session_id: str = typer.Argument(...), config: Path = CONFIG_OP
         raise typer.Exit(code=5)
 
     # --- gate di ingresso ---
+    # Vista effective (D15): un sql_approved/cte ritirato o stale post-rollback non conta.
     problems = session_problems(cfg, session_id)
-    decisions = list_decisions(sdir)
+    decisions = effective_decisions(sdir)
     sql_file = sdir / "sql_final.sql"
     if not sql_file.exists():
         problems.append("sql_final.sql assente")
@@ -196,8 +198,10 @@ def finalize_cmd(session_id: str = typer.Argument(...), config: Path = CONFIG_OP
             "decisione sql_approved assente: la validazione semantica del reviewer "
             "e' obbligatoria prima del finalize"
         )
-    cte_dir = sdir / "ctes"
-    if cte_dir.is_dir():
+    # I CTE richiesti sono quelli del PIANO effettivo, non i file glob su disco: un
+    # ctes/*.sql orfano lasciato da un teardown incompleto non deve bloccare il finalize.
+    plan = effective_cte_plan(sdir)
+    if plan:
         try:
             tested = {r.name for r in load_cte_tests(sdir)}
         except CteError as e:
@@ -206,9 +210,9 @@ def finalize_cmd(session_id: str = typer.Argument(...), config: Path = CONFIG_OP
                 fg=typer.colors.RED, err=True,
             )
             raise typer.Exit(code=3)
-        for cte_file in sorted(cte_dir.glob("*.sql")):
-            if cte_file.stem not in tested:
-                problems.append(f"CTE mai testato: {cte_file.stem}")
+        for name in plan:
+            if name not in tested:
+                problems.append(f"CTE mai testato: {name}")
     if problems:
         typer.secho(f"Finalize rifiutato per {session_id}:", fg=typer.colors.YELLOW)
         for p in problems:
@@ -258,9 +262,13 @@ def finalize_cmd(session_id: str = typer.Argument(...), config: Path = CONFIG_OP
     (sdir / "evidence.json").write_text(json.dumps(entries, ensure_ascii=False, indent=2))
 
     # --- manifest + riepilogo ---
-    from tht.session.store import MANIFEST
+    from datetime import UTC, datetime
+
+    from tht.session.store import MANIFEST, current_author
 
     manifest.status = "finalized"
+    manifest.updated_at = datetime.now(UTC)
+    manifest.updated_by = current_author()
     manifest.to_yaml(sdir / MANIFEST)
     typer.secho(f"OK: sessione {session_id} finalizzata. Artefatti:", fg=typer.colors.GREEN)
     for name in ARTIFACT_FILES: