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 a later authorized migration must be undone. It restores the PSD worktree to this pre-migration commit and was not run by this task:

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

• exact migration inventory: 35 moveable source documents listed below, plus the retained psd-clinical/evidence/README.md (36 current evidence files total). The README is not a source document and must remain at psd-clinical/evidence/README.md:

  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 earlier full-payload scroll is out-of-scope and is not evidence for this package; it must not be repeated. The replacement read-only baseline for the psd-clinical collection on the legacy PSD bind 127.0.0.1:6333 used exact filtered counts and three-ID filtered scrolls only, with with_payload:false and with_vector:false. It observed 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 narrow Qdrant baseline is a provisional owner-gate observation 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 replacement inspection used only these read operations; git status --porcelain was empty both before and after, and git diff --quiet succeeded after. Each Qdrant count request carries only the record_kind filter and exact:true; each scroll request returns at most three point IDs, never payloads or vectors:

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 <<'NODE'
const endpoint = "http://127.0.0.1:6333/collections/psd-clinical/points";
const kinds = ["schema_table", "schema_column", "memory", "solved_question"];
const post = (path, body) => fetch(endpoint + path, {
  method: "POST", headers: {"content-type": "application/json"}, body: JSON.stringify(body),
}).then((response) => response.json());
for (const kind of kinds) {
  const filter = {must: [{key: "record_kind", match: {value: kind}}]};
  const count = await post("/count", {filter, exact: true});
  const sample = await post("/scroll", {
    filter, limit: 3, with_payload: false, with_vector: false,
  });
  console.log(kind, count.result.count, sample.result.points.map((point) => point.id));
}
NODE
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 exactly those 35 listed source documents to evidence/source/; retain psd-clinical/evidence/README.md at its current path. 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.