81 lines
4.5 KiB
Markdown
81 lines
4.5 KiB
Markdown
# 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
|
|
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.
|