ThothII/PROJECT_STATE.md

# 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 PSD authoring repository published all 35 units using Curated unit schema v2. A schema v3
  table-free presentation is now available in the authoring flow: hidden canonical metadata,
  wrapping Markdown scope lists, list-based enum values, and collapsed technical provenance.
  `tht evidence migrate <workspace-root>` performs the deterministic v1/v2-to-v3 rewrite without
  model calls. The 35-unit PSD v3 migration is currently local and pending commit/publication.
- 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.