feat(evidence): contribute to semantic stages (#42)

2026-08-24 22:05:30 +02:00
parent 3420c57c8b
commit f1a9b567ba
17 changed files with 619 additions and 23 deletions
@@ -167,6 +167,33 @@ persisted state is your only context. Bootstrap before doing anything else:
 If `status` is `finalized`, the session is read-only — do not resume; tell the reviewer
 it is complete. (The backend already refuses resume for finalized/archived sessions.)

+## Evidence runtime contributor
+
+Evidence contributes to existing semantic stages; it is never a visible phase and does
+not write decisions, canonical artifacts, or workflow state. Candidates are not truth:
+show their provenance and let the reviewer decide. A formula is `kind=formula`, not a
+separate store.
+
+Use the phase-appropriate Evidence purpose, and make every mapped stage search
+independently:
+
+- `clarification` → `disambiguation`;
+- `rewriting` → `rewriting`;
+- `schema_linking` → `schema_linking`;
+- `cte` and `final_sql` → `sql_generation`.
+
+After consuming the F1 retrieval pack, and before making a proposal in every other
+mapped stage, call `tht search evidence "<current stage context>"
+--stage <semantic-stage> --session <id> --json` before making the stage proposal. Add
+only the available approved context (`--concept`, `--table`, `--column`) and use
+`--require-*` only for a mandatory constraint. In `final_sql`, include the approved CTE
+plan in the current stage context. The command records only its minimal receipt.
+
+An `available` outcome with zero results is visible but does not block the stage. An
+`unavailable` outcome blocks the calling stage: report the sanitized failure and retry
+the same stage later. Never use a stale generation or retry with another purpose.
+Never call Evidence from `memory` or `synthesis`.
+
 ## Phase 1 — Clarification

 Prerequisite: you must already be in Phase 1.
@@ -0,0 +1,26 @@
+## Evidence runtime contributor
+
+Evidence contributes to existing semantic stages; it is never a visible phase and does
+not write decisions, canonical artifacts, or workflow state. Candidates are not truth:
+show their provenance and let the reviewer decide. A formula is `kind=formula`, not a
+separate store.
+
+Use the phase-appropriate Evidence purpose, and make every mapped stage search
+independently:
+
+- `clarification` → `disambiguation`;
+- `rewriting` → `rewriting`;
+- `schema_linking` → `schema_linking`;
+- `cte` and `final_sql` → `sql_generation`.
+
+After consuming the F1 retrieval pack, and before making a proposal in every other
+mapped stage, call `tht search evidence "<current stage context>"
+--stage <semantic-stage> --session <id> --json` before making the stage proposal. Add
+only the available approved context (`--concept`, `--table`, `--column`) and use
+`--require-*` only for a mandatory constraint. In `final_sql`, include the approved CTE
+plan in the current stage context. The command records only its minimal receipt.
+
+An `available` outcome with zero results is visible but does not block the stage. An
+`unavailable` outcome blocks the calling stage: report the sanitized failure and retry
+the same stage later. Never use a stale generation or retry with another purpose.
+Never call Evidence from `memory` or `synthesis`.
@@ -165,6 +165,8 @@ persisted state is your only context. Bootstrap before doing anything else:
 If `status` is `finalized`, the session is read-only — do not resume; tell the reviewer
 it is complete. (The backend already refuses resume for finalized/archived sessions.)

+{{EVIDENCE_RUNTIME_SEARCH}}
+
 {{DISAMBIGUATION_INSTRUCTIONS}}

 {{MEMORY_INSTRUCTIONS}}