marcopanandClaude Fable 5
3ad93cd02f
The tht-gate.js reviewer_confirm now builds structured v2 artifacts before the
widget so the reviewer approves gate-derived data, not raw model text:
- new pure modules gate/artifact-contracts.js (soft validators, {ok,errors},
legacy-passthrough) and gate/enrich.js (index/description enrichment,
buildCteResultV2 fusing thin model data with `tht cte info`, phase enrichment)
- cte_plan v2: validate + enrich + persist via `tht cte plan --name … --doc -`
(names derived from data.ctes[]); legacy `names` param kept as fallback
- cte_result v2: rebuild from `tht cte next`/`tht cte info` (sql + preview from
the persisted test record); null/error last_test -> actionable textResult
- phase v2: soft-validate + fill phase from meta + catalog descriptions
- prepareReviewerArguments coerces artifact.data too (GLM double-stringify);
legacy markdown strings pass through unchanged
- SKILL.md: Phase 6 cte_plan payload A + thin cte_result guidance; Discipline 6
payload C example; Discipline 7 reworded for gate-rebuilt cte_result
Legacy (non-v2) paths unchanged. TypeBox stays Type.Any() for artifact.data;
validation is soft (textResult) so models self-correct instead of looping.
All 102 gate JS tests green.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
ThothII harness — tht
The self-contained Pi layer of ThothII: a deterministic Python CLI (tht) + a Pi gate
extension (.pi/extensions/tht-gate.js) that runs the 8-phase NL→SQL workflow,
emitting and consuming widget-descriptor JSON. Derived from the reference implementation as a validated
starting point, adapted (not assumed reliable) to the ThothII contract.
Install
cd harness
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
The tht command is now on PATH. Node ≥ 20 is needed for the gate JS tests
(npm test).
Configure
.env (gitignored — secrets live ONLY here)
cp .env.example .env
# fill in: THT_PROFILE, THT_DB_*, THT_DWH_API_KEY, THT_VEC_API_KEY,
# THT_VEC_WRITE_API_KEY, THT_SSL_CA, THT_OLLAMA_URL, ...
Keys are never logged; URLs are fine. Rotate any key that appeared in chat.
workspaces/<name>.yaml
A workspace wires the relational DWH + the pgvector (dual-key) + embeddings + evidence.
See workspaces/tht.example.yaml. ${THT_*}} tokens expand from .env.
DB support (MVP): the
directtransport supports PostgreSQL only (psycopg2 driver,pg_*catalog introspection, postgres-dialect sqlcheck/EXPLAIN). The central production DWH is reached via theresttransport. Multi-dialectdirectsupport (sqlserver/mariadb/informix, cf.Thoth/thoth_sqldb2) is separate future work.
Per-customer workspace repo (deployment shape)
ThothII is generic; evidence content and LSH indexes are per-customer and live in a
separate repo, not copied into harness/. The deployment is two checkouts + one .env:
ThothII/ generic harness (this repo)
└── harness/ tht CLI + .env (THT_* secrets, points at the customer repo)
tht-workspace-<customer>/ per-customer workspace repo (separate git repo)
├── <customer>.yaml workspace YAML (paths ABSOLUTE, anchored here)
├── evidence/ curated evidence markdown (frontmatter-structured, by domain)
├── artifacts/ derived artifacts (gitignored; regenerated by tht)
├── indexes/ LSH index (gitignored; regenerated by `tht lsh build`)
└── sessions/ per-session artifacts (gitignored)
THT_DOCS_ROOT in .env points at the root of the customer repo
(evidence.source_root + evidence.evidence_dir resolve the curated folder).
All tht commands take the customer workspace via -c:
tht schema introspect -c /path/to/tht-workspace-<customer>/<customer>.yaml
tht lsh build -c /path/to/tht-workspace-<customer>/<customer>.yaml
tht session new -c /path/to/tht-workspace-<customer>/<customer>.yaml
The workflow
workflow.yaml is the single source of workflow truth (spec F2). Eight phases
(F1 chiarimento → F8 datamart). Edit it to change the workflow; phase.py, the gate,
and the skill all read from it — no mirrored constants to drift.
tht phase meta --json # the gate reads workflow facts from here
tht phase meta # human-readable
Run
The harness runs inside Pi (pi --mode rpc, cwd = harness/):
pi --mode rpc
# in Pi: /nuova-domanda "<your question in natural language>"
The gate (tht-gate.js) presents reviewer widgets (widget-descriptor), the reviewer
decides, and tht persists decisions to the append-only ledger (review_decisions.jsonl).
See docs/testing.md for what each interaction level validates.
Test
pytest # L0 (testcontainers, real Postgres) + L1 (pure logic + gate builders)
npm test # gate widget-builder golden + fuzzy tests (JS)
pytest -m l2 # L2: real GLM 5.2 + remote DWH (pre-release; needs .env + VPN + CA bundle)
L0 needs Docker (present on the dev machine). L2 is manual, non-deterministic, and
skips cleanly without .env. See docs/testing.md for the honest split of what each
level covers and — crucially — does not cover.
Layout
tht/ Python package (CLI + workflow + phase + decisions + db/rest/mschema/
vectorstore/evidence/search/session + memory)
.pi/ Pi project (settings, prompts, themes, extensions/tht-gate.js + gate/)
workflow.yaml single source of workflow truth (F2)
workspaces/ workspace YAML definitions (D3)
scripts/ reader/writer RPC SQL for pgvector (D11)
tests/ L0 (testcontainers), L1 (logic + builders), L2 (real model + DB)
docs/ testing guide + workflow editing
Reference
- Architecture spec:
docs/superpowers/specs/2026-06-25-thothii-architecture-design.md - Implementation plan:
docs/superpowers/plans/2026-06-25-harness-implementation.md