119 lines
5.3 KiB
Markdown
119 lines
5.3 KiB
Markdown
# ThothII — Project State
|
||
|
||
Last updated: 2026-08-26.
|
||
|
||
This file is the short operational snapshot. Stable commands and the architecture mental model
|
||
live in `AGENTS.md`; current design and runtime contracts live under `docs/architecture/`,
|
||
`docs/contracts/`, `docs/adr/`, and `docs/evidence.md`. Superseded plans and reports are
|
||
available from Git history rather than duplicated in the working tree.
|
||
|
||
## Current product shape
|
||
|
||
ThothII is a human-in-the-loop datamart builder with three independently built layers:
|
||
|
||
```text
|
||
frontend (React/SSE) → backend (Fastify) → pi --mode rpc → tht/harness → DWH (read-only)
|
||
```
|
||
|
||
The harness owns the deterministic eight-phase NL→SQL workflow and all session persistence.
|
||
The backend is a process/RPC/SSE bridge without a database of its own. The frontend renders the
|
||
review gates and keeps the live transcript in memory. See
|
||
`docs/architecture/components.md` for the detailed component and data-flow map.
|
||
|
||
## Evidence restructuring — accepted
|
||
|
||
The evidence restructuring and PSD migration completed real acceptance on 2026-08-25.
|
||
|
||
- The curated PSD revision contains 35 approved Evidence units and 60 review items.
|
||
- The accepted snapshot is
|
||
`psd-clinical-675990d90eae51da6f2bd51b1ae2609f245772ef-snapshot`.
|
||
- The active generation is `gen:f968b3bd7a553dbfef3cf47093698f2bc7f95f11`.
|
||
- Retrieval acceptance reached 20/20 Hit@10.
|
||
- A real session, `20301df7-cad7-403d-a4c1-9f35c9d07b66`, completed F1–F8 with five
|
||
receipts, three CTEs, and a final result of 78 patients.
|
||
- The durable acceptance record is
|
||
`docs/testing/evidence/evidence-restructuring-psd-acceptance-2026-08-25.md`.
|
||
|
||
The canonical authoring, validation, publication, materialization, and preprocessing flow is
|
||
documented in `docs/evidence.md`. The governing contracts are
|
||
`docs/contracts/workspace-evidence-v3.md` and
|
||
`docs/contracts/workspace-preprocessing-cli.md`.
|
||
|
||
## Workspace preprocessing and configuration
|
||
|
||
The native host CLI `tht` is the operator surface. Workspace preprocessing runs through:
|
||
|
||
```sh
|
||
tht --installation /absolute/path/thothii-installation.yaml workspace preprocess evidence
|
||
tht --installation /absolute/path/thothii-installation.yaml workspace preprocess dwh
|
||
```
|
||
|
||
These commands use the profile-gated `workspace-maintenance` service. The former standalone
|
||
preprocessing Compose fixtures are retired.
|
||
|
||
Workspace descriptors use schema v3. For PSD, workspace content and runtime roots point to the
|
||
separate uncommitted repository `/Users/mp/projects/tht-workspace-psd`. Secrets remain outside
|
||
Git and are supplied only through installation-local protected files.
|
||
|
||
## Active deployment work and manual gates
|
||
|
||
### PSD server deployment program
|
||
|
||
The approved design and executable entry point are:
|
||
|
||
- `docs/plans/2026-08-20-psd-server-deployment-program-design.md`
|
||
- `docs/plans/2026-08-20-psd-server-deployment-program.md`
|
||
- `docs/plans/2026-08-20-psd-server-survey.md`
|
||
- `docs/plans/2026-08-20-psd-server-project-a-standalone.md`
|
||
- `docs/plans/2026-08-20-psd-server-project-b-authentik.md`
|
||
|
||
Last recorded state:
|
||
|
||
- survey: `SURVEY_NO_GO`;
|
||
- Project A: `BLOCKED_BY_SURVEY_AND_MUTATION_GATE`;
|
||
- Project B: `BLOCKED_BY_PROJECT_A_AND_PRE_B_GATE`.
|
||
|
||
The deployment is a clean replacement: legacy sessions, indexes, and application configuration
|
||
are not migration inputs. The existing stack remains intact until its documented mutation and
|
||
rollback gates are explicitly approved. Shared Omics/LocalLLM networks, ETL Evidence, DWH,
|
||
`dwh-auth`, Supabase, Authentik, Superset, and Aritmolab are outside cleanup scope.
|
||
|
||
Human acceptance guides and sanitized report templates live under `docs/testing/` and
|
||
`docs/testing/evidence/`. The remediation checklist is
|
||
`docs/operations/psd-server-survey-remediation-checklist.md`.
|
||
|
||
### Authentication
|
||
|
||
The local/OIDC authentication remediation passed its automated review on 2026-08-18. Release and
|
||
PSD mutation gates remain governed by:
|
||
|
||
- `docs/architecture/authentication.md`;
|
||
- `docs/plans/2026-08-18-thothii-authentication-acceptance-and-psd-deployment.md`;
|
||
- `docs/operations/psd-dwh-auth-rollout.md`;
|
||
- `docs/testing/authentication-manual-acceptance.md`.
|
||
|
||
Do not infer authorization for server, Nginx, Authentik, database, credential, or cutover changes
|
||
from an automated PASS.
|
||
|
||
## Verification status
|
||
|
||
- The P1.1 workspace-directory registry and P2–P6 preprocessing workstreams are implemented and
|
||
have automated coverage.
|
||
- Evidence restructuring has a real PSD acceptance PASS as recorded above.
|
||
- L2 tests requiring real providers or remote databases remain opt-in.
|
||
- Server deployment, release, and owner-operated acceptance steps remain pending wherever the
|
||
referenced runbooks require explicit approval.
|
||
|
||
Run the layer-specific checks documented in `AGENTS.md`. For release-sensitive changes, also run
|
||
the repository contract scripts in `scripts/` and build the MkDocs site.
|
||
|
||
## Operational invariants
|
||
|
||
- `tht`'s `-c`/`--config` option follows the subcommand; it is not a global option.
|
||
- `--json` commands write pristine JSON to stdout.
|
||
- Persisted phase documents and the decision ledger are the source of session truth; chat is not.
|
||
- UI chrome is English; workspace document content retains the workspace language.
|
||
- The backend refuses resume for finalized or archived sessions.
|
||
- A resume must send `/riprendi-sessione <id>`; a new session must send `/nuova-domanda`.
|
||
- DWH access is read-only.
|