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; it does not inspect, write, stage, or migrate the PSD authoring repository.

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)

Before any PSD write, provide all of the following to the owner:

• clean ThothII commit and the exact local-gate/acceptance output;
• proposed PSD branch name: codex/evidence-restructuring-psd (proposal only; no external branch has been created);
• the exact, authorized-snapshot list of 36 source files to move;
• the pre-migration PSD commit and the rollback command git -C <authorized-psd-clone> reset --hard <pre-migration-commit>;
• before counts and representative IDs for schema_table, schema_column, memory, and solved_question, plus dense-search samples for Schema and Memory.

The 36-path inventory, PSD commit, and before counts are intentionally blank until the owner authorizes the external repository inspection. Recording or executing them is issue #47, not this issue.

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.