ThothII/docs/testing/evidence-restructuring-manual.md

Evidence restructuring: owner migration gate

Status: PENDING OWNER AUTHORIZATION. This guide records the manual work that must occur only after the owner authorizes a migration window and exact PSD target branch. The automated runner is hermetic: it uses a fake restructurer and temporary inputs. The owner-gate inventory below is a separately authorized, read-only PSD snapshot; it did not write, stage, branch, commit, migrate, activate, push, or read secrets.

Recorded automated boundary

Run from ThothII:

bash scripts/evidence-restructuring-acceptance.sh

It proves the local contracts with an intentionally badly structured fixture: typed splitting, review-item blocking, one-source membership, Git-visible proposals and recoverability, no-op reruns, dirty-state refusal, pipeline-version refusal plus full --upgrade, and orphan blocking. It also runs the hermetic authoring, canonical-kind, formula, chunking, candidate-evaluation, hybrid-query/fail-closed, and pinned-Qdrant L0 suites. The runner supplies only a mktemp workspace and asserts the ThothII worktree is unchanged; consequently it performs no external PSD write.

The real Pi invocation is deliberately not automated here. A reviewer must run it once per changed source after the authorization gate and examine every proposed curated file.

Owner-gate package (issue #46)

Read-only snapshot collected 2026-08-25:

• PSD repository: /Users/mp/projects/tht-workspace-psd, clean before and after the inspection; immutable pre-migration commit 47516f85b4db4a67cfa8a86cea4cb2e7b98c5813.

• proposed PSD branch name: codex/evidence-restructuring-psd (proposal only; no external branch has been created);

• rollback command for the owner to use only if the later authorized migration must be undone:

  git -C /Users/mp/projects/tht-workspace-psd reset --hard 47516f85b4db4a67cfa8a86cea4cb2e7b98c5813
  

• exact source inventory (36 files; evidence/README.md is not a source):

  psd-clinical/evidence/00-glossario/coorti-universi-pazienti.md
  psd-clinical/evidence/00-glossario/glossario-termini-analitici.md
  psd-clinical/evidence/00-glossario/glossario-termini-clinici.md
  psd-clinical/evidence/00-glossario/glossario-termini-dwh.md
  psd-clinical/evidence/00-glossario/note-di-lettura.md
  psd-clinical/evidence/00-glossario/tassonomia-eventi.md
  psd-clinical/evidence/10-domini-clinici/ablazione.md
  psd-clinical/evidence/10-domini-clinici/anagrafica-paziente.md
  psd-clinical/evidence/10-domini-clinici/cardioversione-elettrica.md
  psd-clinical/evidence/10-domini-clinici/chiusura-auricola.md
  psd-clinical/evidence/10-domini-clinici/documenti-clinici.md
  psd-clinical/evidence/10-domini-clinici/genetica-clinica.md
  psd-clinical/evidence/10-domini-clinici/icd.md
  psd-clinical/evidence/10-domini-clinici/ilr.md
  psd-clinical/evidence/10-domini-clinici/pacemaker.md
  psd-clinical/evidence/10-domini-clinici/pm-icd-altro.md
  psd-clinical/evidence/10-domini-clinici/visite-cardiologiche-genetiche.md
  psd-clinical/evidence/20-valori-enum/enum-flag-booleani.md
  psd-clinical/evidence/20-valori-enum/enum-flag-note-sn.md
  psd-clinical/evidence/20-valori-enum/enum-innesto.md
  psd-clinical/evidence/20-valori-enum/enum-isteresi.md
  psd-clinical/evidence/20-valori-enum/enum-tipo-intervento.md
  psd-clinical/evidence/30-esempi-nlq/nlq-ablazione.md
  psd-clinical/evidence/30-esempi-nlq/nlq-cardioversione.md
  psd-clinical/evidence/30-esempi-nlq/nlq-device-pacemaker-icd.md
  psd-clinical/evidence/30-esempi-nlq/nlq-percorso-paziente.md
  psd-clinical/evidence/30-esempi-nlq/nlq-studio-elettrofisiologico.md
  psd-clinical/evidence/40-mapping-semantico/catena-staging-integration-dwh.md
  psd-clinical/evidence/40-mapping-semantico/matrice-viewpoint-dominio.md
  psd-clinical/evidence/40-mapping-semantico/registry-testo-clinico-fact-clinical-event-text.md
  psd-clinical/evidence/40-mapping-semantico/regole-classificazione-fact-dim-bridge.md
  psd-clinical/evidence/40-mapping-semantico/trasformazioni-valori-mapping-colonne.md
  psd-clinical/evidence/50-metadati-normalizzazione/normalizzatori-valori-dwh.md
  psd-clinical/evidence/50-metadati-normalizzazione/normalizzazione-codici-paziente-medici.md
  psd-clinical/evidence/50-metadati-normalizzazione/normalizzazione-device-cied.md
  

The read-only Qdrant observation for the psd-clinical collection on the legacy PSD bind 127.0.0.1:6333 was 163 schema_table, 2,275 schema_column, 2 memory, and 1 solved_question point. Representative IDs are:

Kind	Sample IDs
schema_table	01bc2535-24d6-5722-a58b-64a122b90b36, 024ddf60-c80d-5223-ac06-9247e7de7027, 086e00c8-b4a9-5063-b82d-e5a67add29cd
schema_column	00126cc1-7564-521a-a084-c2d670263258, 00365200-2c55-5bb4-86bb-87dd2d1bb529, 004304bc-b543-5b2d-8b40-f18da8e82af7
memory	8d5cd772-563a-5e22-b764-2ca76cf6efca, db74457a-3de8-5b95-9a31-d28a1ecf8141
solved_question	2b6bb7d2-1a35-5f49-bd8d-b0cdcb98459a

tht ... workspace vector inspect --json was attempted read-only but was blocked by the local maintenance image's missing production auth.yaml / AUTH_MODE=upstream. The counts above therefore come from the Qdrant read-only scroll endpoint and must be repeated through the successful vector inspect command immediately before the future authorized preprocessing action. No secret was read to bypass that guard.

Reproducible no-write record

The inspection used only these read operations; git status --porcelain was empty both before and after, and git diff --quiet succeeded after:

git -C /Users/mp/projects/tht-workspace-psd rev-parse HEAD
git -C /Users/mp/projects/tht-workspace-psd status --porcelain
git -C /Users/mp/projects/tht-workspace-psd ls-tree -r --name-only HEAD -- psd-clinical/evidence
node -e 'fetch("http://127.0.0.1:6333/collections/psd-clinical/points/scroll", {method:"POST", headers:{"content-type":"application/json"}, body:JSON.stringify({limit:4096,with_payload:true,with_vector:false})}).then(r => r.json()).then(x => console.log(x.result.points.length))'
git -C /Users/mp/projects/tht-workspace-psd diff --quiet

Before any PSD write, provide the owner this inventory, SHA, rollback command, baseline counts/IDs, clean ThothII commit, and exact local-gate output. Issue #47 still owns all external mutations and manual acceptance.

Manual acceptance after authorization (issue #47)

Record a separate PASS/FAIL and evidence for each item; never substitute an automated test for a human Git review.

1. Authoring and Git review. In the authorized PSD clone, move only the approved 36 source paths to evidence/source/, run tht evidence prepare, verify exactly one no-tool/no-session Pi call per changed source, inspect the Git diff, correct every review_item, run tht evidence validate, and obtain the normal human Git review. Confirm source renames/reclassifications retain IDs, semantic splits receive new IDs, IDs use evidence:<slug>, and no orphan is deleted automatically.
2. Additive BM25 schema upgrade. Before preprocessing, run vector inspect and save configuration, counts, and IDs. Run workspace preprocess evidence; verify the unnamed dense vector remains and only bm25 with IDF is added. Do not accept a destructive rebuild, vector rename, or fallback engine.
3. Schema and Memory non-regression. Compare before/after counts and the saved representative IDs for schema_table, schema_column, memory, and solved_question; repeat dense Schema and Memory searches and attach the results.
4. Preprocessing publication. Confirm a validated corpus builds an inactive candidate, evaluates that exact generation, and switches active generation only after every evaluation query has an expected ID in the first ten fused hits. Attach dense, BM25, and fused ranks for lexical, semantic, and mixed queries.
5. Hybrid and formula retrieval. Check dense and BM25 receive the identical NFC / newline / outer-trim-only query text. Confirm Formula Evidence accepts a PostgreSQL expression but rejects a full query, and retrieve one approved formula by its typed Evidence path.
6. Empty versus blocking unavailable. Record one available empty retrieval and one controlled Qdrant failure. The first may continue; the second must block the stage without stale generation or purpose fallback.
7. Complete session behavior. Walk through clarification, rewriting, schema_linking, cte, and final_sql; confirm independently persisted minimal receipts. Confirm neither memory nor synthesis invokes Evidence search and that session formula proposals remain unpublished.

Write the reviewer identity, UTC time, commit IDs, command output locations, and one final manual acceptance: PASS or manual acceptance: FAIL line when (and only when) the authorized walkthrough is complete.