docs: converge operator guidance on tht
This commit is contained in:
+26
-26
@@ -4,7 +4,7 @@
|
||||
> **Requisito finale del progetto (owner, 2026-08-11):** al termine dell'ultima fase tecnica deve
|
||||
> essere prodotto un documento unico che guidi l'utente passo-passo su (1) come preparare il
|
||||
> repository dei workspace su Git secondo le regole del progetto, (2) come usare gli strumenti di
|
||||
> ThothII per il repository (app + CLI `thothctl`), (3) come usare l'applicazione ThothII di base
|
||||
> ThothII per il repository (app + CLI `tht`), (3) come usare l'applicazione ThothII di base
|
||||
> (sessioni, domande, gate). Il documento userà parole semplici ed esempi; i dettagli tecnici
|
||||
> resteranno nei contratti esistenti. Esempio pratico completo: Policlinico San Donato.
|
||||
> Last updated: 2026-08-18 (final-review fix round 2 recorded; native Windows authentication gate
|
||||
@@ -14,8 +14,8 @@
|
||||
### Authentication final-review fix round 2 — remediation PASS, release gates remain (2026-08-18)
|
||||
|
||||
- Frozen source is `2a9359071257f9b8a71d36ec2bbb25b161003f81` on `feat/thoth-auth`.
|
||||
Source and evidence are separate commits; `.playwright-cli/` and `.thothctl/` remain the only
|
||||
untracked paths.
|
||||
Source and evidence are separate commits; generated local runtime-state directories remain
|
||||
untracked and must not be staged.
|
||||
- Local PASS on the frozen source: exact `safeio`/`backup`/`authstorage` tests, full Go race suite,
|
||||
`go vet`, macOS host build, Windows amd64 package cross-compiles, and Windows CLI build.
|
||||
- The lifecycle tests now use context-aware gate publication/release, bounded waits for stages,
|
||||
@@ -60,7 +60,7 @@
|
||||
lock and fails closed on conflicts.
|
||||
- **Revision-scoped records:** schema and Evidence Qdrant point IDs, payloads and queries include
|
||||
`workspace_revision`; memory/solved stay workspace-wide.
|
||||
- **Operator contract:** `thothctl` now carries `effectiveConfigIdentity`/`configFingerprint`/
|
||||
- **Operator contract:** `tht` now carries `effectiveConfigIdentity`/`configFingerprint`/
|
||||
`inputFingerprint` in results; the operator config lease path is deterministic for the same
|
||||
revision+identity.
|
||||
- **Retained evidence:** `.artifacts/p3-integration/p3-da9428d84f152fe059d41a89436496b7/`
|
||||
@@ -75,8 +75,8 @@
|
||||
the 8 required keyword payload indexes) and adds missing indexes, but never mutates an
|
||||
incompatible collection (`semantic_index_incompatible`); the operator path keeps
|
||||
`require_existing` semantics.
|
||||
- **Host CLI:** `thothctl workspace vector inspect` (read-only contract report) and
|
||||
`thothctl workspace vector rebuild --workspace <id> --collection <name> --confirm <name> --destroy`
|
||||
- **Host CLI:** `tht workspace vector inspect` (read-only contract report) and
|
||||
`tht workspace vector rebuild --workspace <id> --collection <name> --confirm <name> --destroy`
|
||||
(guarded delete/recreate of only the descriptor-owned collection, with durable state before
|
||||
deletion and verification after recreation; mismatched confirmation or missing `--destroy`
|
||||
→ exit 2).
|
||||
@@ -84,7 +84,7 @@
|
||||
(`qdrantEnsure` self-heal for admission; default `require_existing` elsewhere),
|
||||
`backend/src/workspaces/runtime-config-lease.ts` (lease exposes `semanticQdrantUrl`),
|
||||
`backend/src/workspace-maintenance.ts` + `preprocessing-service.ts` (`vector-inspect`/`vector-rebuild`
|
||||
operator commands), `tools/thothctl/internal/workspaceops/operations.go` (+tests).
|
||||
operator commands), `tools/tht/internal/workspaceops/operations.go` (+tests).
|
||||
- **Automated acceptance:** PASS 11/11 (run `p4-466bbfdea9ef3111f36baa99fc2d64aa`,
|
||||
report `.artifacts/p4-integration/p4-466bbfdea9ef3111f36baa99fc2d64aa/` retained via `--keep`,
|
||||
bound to clean source commit `e056c19e6214254a9e3b2390e24c389920b84e95`): preflight, clean_state,
|
||||
@@ -111,7 +111,7 @@
|
||||
`paths.artifacts`/`indexes`/`memory`/`sessions` stay workspace-global (the binding-keyed DWH cache
|
||||
at `artifacts.parent` is untouched); the harness resolves annotations from `annotations_root` with a
|
||||
legacy fallback.
|
||||
- **Review primitive:** `thothctl ... workspace schema accept --run <id> --yes` is the only human FK
|
||||
- **Review primitive:** `tht ... workspace schema accept --run <id> --yes` is the only human FK
|
||||
review path. It validates the current synced Git blob with the harness parser and records
|
||||
`{ reviewedCandidatesDigest, annotationsDigest, workspaceRevision, blobId }`. Missing `--yes`, an
|
||||
unknown run, an empty/malformed blob, or a non-matching candidate fails closed (`annotation_invalid`)
|
||||
@@ -124,7 +124,7 @@
|
||||
annotations.ts`, `backend/src/workspaces/git-repository.ts` (`annotationsObject`),
|
||||
`backend/src/workspaces/registry.ts` (activation validation + sync), `backend/src/workspaces/
|
||||
preprocessing-service.ts` (`acceptSchema` + continuation gate), `backend/src/workspace-maintenance.ts`
|
||||
(`schema-accept`), `tools/thothctl/internal/workspaceops/operations.go` (+tests), `harness/tht/
|
||||
(`schema-accept`), `tools/tht/internal/workspaceops/operations.go` (+tests), `harness/tht/
|
||||
config.py` + `cli/schema_cmd.py` (`paths.annotations_root`), `docs/contracts/
|
||||
workspace-preprocessing-cli.md`.
|
||||
- **Gates:** backend **689/689** + tsc clean; Go build+test 9/9; harness focused schema/annotations
|
||||
@@ -188,12 +188,12 @@
|
||||
`deploy/psd/secrets/`). Real operator config is wired (gitignored): `deploy/psd/operator.env`,
|
||||
`workspace-bindings.env`, `thothii-installation.yaml`, `connector-secrets.yaml` + `secrets/`
|
||||
(DWH X-API-Key reused from the legacy `.env`; no CA — the DWH REST is public HTTPS).
|
||||
- **Stack live:** started via `thothctl start` (project `thothii-70417a3e30ea`), all services
|
||||
- **Stack live:** started via `tht start` (project `thothii-70417a3e30ea`), all services
|
||||
healthy, `qwen3-embedding:0.6b` present; the registry cloned + activated `psd-clinical`
|
||||
(`ready`); `thothctl workspace inspect` returns `ok` with descriptor/catalog/runtime identities.
|
||||
Gotcha recorded: `thothctl` uses a per-descriptor Compose project name, so the stack must be
|
||||
started with `thothctl start` (not a raw `compose-with-preflight.sh up`).
|
||||
- **Preprocessing live (2026-08-13):** with VPN active, `thothctl workspace preprocess run
|
||||
(`ready`); `tht workspace inspect` returns `ok` with descriptor/catalog/runtime identities.
|
||||
Gotcha recorded: `tht` uses a per-descriptor Compose project name, so the stack must be
|
||||
started with `tht start` (not a raw `compose-with-preflight.sh up`).
|
||||
- **Preprocessing live (2026-08-13):** with VPN active, `tht workspace preprocess run
|
||||
--workspace psd-clinical` **succeeded** against the real PSD DWH — DWH introspection + LSH
|
||||
(163 tables / 2275 columns), FK review (no new candidates: the 42 KB curated annotations are
|
||||
authoritative), schema index (2438 records) and filesystem Evidence index (36 docs / 43 chunks).
|
||||
@@ -213,7 +213,7 @@
|
||||
### Final aggregate P2–P6 verification — automated PASS, manual PENDING (2026-08-13)
|
||||
|
||||
- **Aggregate process goal:** one clean-state run exercises the complete DWH → FK → schema →
|
||||
filesystem Evidence chain through `thothctl`/the operator surface, proves idempotency and
|
||||
filesystem Evidence chain through `tht`/the operator surface, proves idempotency and
|
||||
revision isolation, proves a second installation consumes the same Git workspace with its own
|
||||
state, exercises unsafe-tree and bound negatives, and cleans only owned resources.
|
||||
- **Automated acceptance:** PASS 12/12 (run `p2p6-ee542112c526ef0d4c25ddf6c8bc164b`, report
|
||||
@@ -224,7 +224,7 @@
|
||||
`scripts/p2p6-acceptance.sh` / `backend/scripts/p2p6-acceptance.mjs` (+unit test).
|
||||
- **Full suites + builds (design §10):** harness **873 passed / 4 deselected** (with color disabled;
|
||||
the forced-color environment splits `--help` flags and trips the gate-CLI consistency test only);
|
||||
backend **698/698** + tsc + build; frontend **364/364** + `tsc -b` + build; `thothctl` Go
|
||||
backend **698/698** + tsc + build; frontend **364/364** + `tsc -b` + build; `tht` Go
|
||||
build+test **9/9**; `git diff --check` clean.
|
||||
- **Manual acceptance:** PENDING — "Final aggregate P2–P6 verification" in
|
||||
`docs/testing/p2-p6-manual-verification.md`.
|
||||
@@ -233,14 +233,14 @@
|
||||
|
||||
- **`docs/guida-utente.md`** (Italian, simple words + examples) covers: (1) preparing the workspace
|
||||
Git repository (catalog + schema-v3 descriptor + Evidence + curated annotations), (2) using the
|
||||
ThothII tools for the repository (`thothctl` commands + read-only workspace management), and (3)
|
||||
ThothII tools for the repository (`tht` commands + read-only workspace management), and (3)
|
||||
using the base ThothII application (sessions, questions, gates). It ends with a complete
|
||||
Policlinico San Donato walkthrough and links to the technical contracts.
|
||||
- Registered in the MkDocs nav (`mkdocs.yml`). Owner review PENDING.
|
||||
|
||||
### P2 host preprocessing CLI — implementation complete, automated PASS, manual PENDING (2026-08-11)
|
||||
|
||||
- **Scope:** P2 (PRD D2, based on the P1.1 registry contract): the installed native `thothctl`
|
||||
- **Scope:** P2 (PRD D2, based on the P1.1 registry contract): the installed native `tht`
|
||||
binary is the only host interface for workspace preprocessing. Commands: `workspace inspect`,
|
||||
`preprocess dwh`, `schema suggest-fks`, `schema check`, `index-schema`, `preprocess evidence`,
|
||||
`preprocess run`, with the exact grammar, file-ingress bounds, result contract and exit codes in
|
||||
@@ -378,7 +378,7 @@ P1.1 manual acceptance: PASS (owner approval 2026-08-11)
|
||||
and proves exact cleanup of compose containers, volumes, networks, and only that smoke image.
|
||||
Unified deployment smoke passed in **125.57s**; update-only rollback smoke
|
||||
passed in **85.40s**; Linux server deployment smoke passed in **55.99s**. The previously
|
||||
observed `thothctl` rollback failure did not recur.
|
||||
observed `tht` rollback failure did not recur.
|
||||
- **Task 13 image and manual-gate notes.** Verified pinned runtime images:
|
||||
`qdrant/qdrant:v1.18.2@sha256:75eab8c4ba42096724fdcfde8b4de0b5713d529dde32f285a1f86fdcb2c9e50c`
|
||||
and
|
||||
@@ -397,12 +397,12 @@ P1.1 manual acceptance: PASS (owner approval 2026-08-11)
|
||||
embedding endpoint coupling.
|
||||
- **Final review fix verification.** Backend Vitest passed **477/477** plus TypeScript and build;
|
||||
harness pytest passed **827 passed / 4 deselected** with the existing 74 warnings; touched Python
|
||||
files are Ruff-clean. The complete `thothctl` Go suite, deterministic backup/restore safety test,
|
||||
files are Ruff-clean. The complete `tht` Go suite, deterministic backup/restore safety test,
|
||||
internal semantic Compose contract, no-deployment-coupling gate, CPU/offline semantic smoke, and
|
||||
unified deployment smoke all pass after the final fix. The intermittent `thothctl` rollback failure was
|
||||
unified deployment smoke all pass after the final fix. The intermittent `tht` rollback failure was
|
||||
traced to Docker Desktop alternating equivalent bind sources between `/private/...` and
|
||||
`/host_mnt/private/...`. Exact state-v4 source hashes remain unchanged; only fresh bind
|
||||
observations made by a Darwin `thothctl` carry non-serialized aliases for the rollback
|
||||
observations made by a Darwin `tht` carry non-serialized aliases for the rollback
|
||||
comparison, so pre-fix recovery state remains readable and Linux `/host_mnt` paths remain
|
||||
distinct. The rollback-only smoke passed twice consecutively after each fix revision, and the
|
||||
subsequent full unified smoke passed with exact cleanup.
|
||||
@@ -414,7 +414,7 @@ P1.1 manual acceptance: PASS (owner approval 2026-08-11)
|
||||
|
||||
- **Release coverage.** `scripts/unified-deployment-smoke.sh` gates the two-service render/build,
|
||||
frontend-to-core routing, embedded pinned Pi, Git registry bootstrap, offline recreation, valid
|
||||
update, invalid-update retention, and the four persistent stores. `scripts/thothctl-update-smoke.sh`
|
||||
update, invalid-update retention, and the four persistent stores. `scripts/tht-update-smoke.sh`
|
||||
independently exercises the bad-Pi update and automatic rollback path.
|
||||
`scripts/server-deployment-smoke.sh` starts the server plus required session overlays with the
|
||||
same smoke-built core/frontend images, disposable bind roots/secrets/session configuration,
|
||||
@@ -422,7 +422,7 @@ P1.1 manual acceptance: PASS (owner approval 2026-08-11)
|
||||
- **Isolation and disclosure boundary.** Every run generates a unique temporary root, Compose
|
||||
project, container/image names, transaction image tags, and run label. The rollback fixture uses
|
||||
an immutable `hello-world` digest whose preflight exits successfully, guaranteeing the stopped
|
||||
core state required by `thothctl` compensation. Cleanup includes stopped project containers in
|
||||
core state required by `tht` compensation. Cleanup includes stopped project containers in
|
||||
its final ownership check immediately before teardown and removes only exact containers,
|
||||
Compose resources, image references, control state, and temporary files. There is no global
|
||||
prune. Failure diagnostics are bounded and sanitized, and all credentials/endpoints used by the
|
||||
@@ -431,7 +431,7 @@ P1.1 manual acceptance: PASS (owner approval 2026-08-11)
|
||||
- **Cross-platform CI contract.** `.github/workflows/deployment.yml` uses immutable action commits,
|
||||
pinned supported Node and Go versions, runs LF/Compose/secret/coupling/docs/TypeScript gates on
|
||||
Linux, runs each Linux Docker smoke once under its own outer timeout, and copies the Windows
|
||||
source into a path containing spaces before building/invoking native `thothctl` and rendering
|
||||
source into a path containing spaces before building/invoking native `tht` and rendering
|
||||
Compose. The optional `windows_docker_startup` dispatch targets a labelled self-hosted Windows
|
||||
Docker Desktop/WSL2 runner and performs bounded two-service startup and exact cleanup. No local
|
||||
Windows or Windows Docker execution is claimed until that manual job is recorded.
|
||||
@@ -439,7 +439,7 @@ P1.1 manual acceptance: PASS (owner approval 2026-08-11)
|
||||
frontend **386/386** plus TypeScript, and harness **862 passed / 5 L2 deselected** are green.
|
||||
Review round 1 ran each Docker smoke exactly once without retry. Unified (`103.86s`) and
|
||||
update-only (`46.45s`) passed build/start, core/Pi/registry/persistence setup and the stopped
|
||||
candidate preflight, but `thothctl` stopped before mutation at its active-session inventory gate.
|
||||
candidate preflight, but `tht` stopped before mutation at its active-session inventory gate.
|
||||
Round 2 replaces presence-only fixture checks with generated Compose renders plus the production
|
||||
workspace resolver; this found and fixed missing explicit direct transport selections. The
|
||||
clean-server preflight now atomically initializes the three hidden Pi-agent targets under the
|
||||
|
||||
Reference in New Issue
Block a user