diff --git a/docs/current-handoff.md b/docs/current-handoff.md index 27f7a2e..9176bf7 100644 --- a/docs/current-handoff.md +++ b/docs/current-handoff.md @@ -474,3 +474,51 @@ focused contribution ### Decision: FINDINGS-DOMAIN-MODEL-JUSTIFIED The distinction is clearly useful enough that focused→global integration should be designed around findings/provenance rather than raw turn outputs. The semantic gap between "what one answer contributed" and "what the investigation has found so far" is real and material. + +--- + +## Finding ↔ SituationGraph Reasoning Contract — August 2026 + +1. **Finding is a separate durable reasoning entity.** It is not itself a SituationGraph node. + +2. **Finding ↔ graph relationship is conceptually many-to-many.** One Finding may support/challenge multiple graph propositions. Multiple Findings may support/challenge one graph proposition. + +3. **Findings do not directly mutate the SituationGraph.** They are evidence carriers, not graph mutation agents. + +4. **case/update remains authoritative for:** + - graph node creation/update + - resolving/reopening unknowns + - graph confidence/status changes + - activeUnknownNodeId + - selectedQuestion + - Current Understanding + +5. **Trust model:** focused reasoning proposes Findings/evidence → user disposition affects standing → case/update independently evaluates → authoritative graph changes happen only through case/update. + +6. **User dispositions** (Agree / Not quite / Not relevant) are semantic signals that INFORM global reasoning. They do not directly bind graph truth. + +7. **Finding status and graph node status remain separate concepts.** One does not dictate the other. + +8. **Relevance and confidence remain separate dimensions.** A Finding can be high-confidence but low-relevance, or vice versa. + +9. **Low-relevance Findings may remain in provenance/evidence** without affecting active investigation priority. + +10. **Findings may be reopened** when later evidence changes their relevance or standing. + +11. **Current Understanding should ultimately be reconstructed** by case/update from globally eligible Findings + graph state, not directly from the latest focused result. + +12. **Findings may influence but do not own:** active frontier, selectedQuestion. Only case/update sets these. + +13. **Raw focused fields must not be blindly copied into graph mutations.** Case/update evaluates accumulated evidence through authoritative reasoning paths (reconciliation, branch interaction analysis, decision closure protection). + +14. **Minimum conceptual handoff object is approximately:** Finding + disposition + provenance + relevance/standing + graph anchor. API/schema design is NOT yet settled. + +### Unresolved implementation choices + +- Finding schema +- Finding IDs +- contribution↔Finding mapping/clustering +- confidence representation/scoring +- reopening triggers +- exact focused→global API/payload shape +- UI presentation of Finding dispositions