feat(opt): three efficiency levers for NL→SQL workflow

Lever 1: Join-graph via FK logics in annotations + suggest-fks command
  - TableAnnotation.foreign_keys field stores curated logical FKs (DWH has no FK constraints)
  - tht schema suggest-fks: mine from approved SQL, heuristics (time_key → dim_time),
    same-name discovery + explicit --assume flag for multi-owner PKs
  - mschema renders 【Foreign keys】 section populated; validation in merge.py
  - SKILL.md F4 now reads FKs from mschema-text, no custom data_time_key logic

Lever 2: Context-pack consolidation at kickoff (tht search pack)
  - Single embedding of question, reused for schema + evidence + solved searches
  - One command: tht search pack <question> --session <id> → retrieval_pack.md
  - Graceful degradation when Ollama/vector store unreachable (exit 0, empty sections)
  - SKILL.md F1 prescribes as first call; reduces model thinking turns via pre-retrieval

Lever 3: Phase-summary recap v2 auto-construction from session ledger
  - tht session show --json includes full decisions ledger
  - tht phase meta --json exports 'emits' (substantive decision types per phase)
  - Gate appends deterministic 【Decisioni registrate in questa fase】 section (appendLedgerSection)
  - Model authors only summary + checks; recap table comes from persisted state (exact by construction)
  - SKILL.md Disciplina 6: brief model output, gate fills the rest

Tests: 358 Python (including 10 FK + 3 pack + 1 session-ledger tests) + 111 JS gate tests, all pass.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

This commit is contained in:

marcopan

2026-07-07 17:43:08 +02:00

co-authored by

Claude Fable 5

parent 87e875bc81

commit e24b41b156

19 changed files with 936 additions and 29 deletions

									
										harness/tht/cli/session_cmd.py
									
		+5
		
												View File
												
				@@ -181,6 +181,11 @@ def show_cmd(

				        data = manifest.model_dump(mode="json", by_alias=True)

				        data["phase"] = phase

				        data["has_schema_linking"] = has_schema_linking

				        # Ledger integrale: il gate lo usa per costruire deterministicamente il

				        # recap delle decisioni nei riepiloghi di fase (v2).

				        data["decisions"] = [

				            d.model_dump(mode="json") for d in list_decisions(sdir)

				        ]

				        typer.echo(json.dumps(data, ensure_ascii=False, indent=2))

				        return