docs(confidence-engine): define focused finding handoff contract
This commit is contained in:
@@ -522,3 +522,193 @@ The distinction is clearly useful enough that focused→global integration shoul
|
||||
- reopening triggers
|
||||
- exact focused→global API/payload shape
|
||||
- UI presentation of Finding dispositions
|
||||
|
||||
---
|
||||
|
||||
## Focused → Global Finding Handoff Contract — August 2026
|
||||
|
||||
### Semantic contract (established)
|
||||
|
||||
This section codifies the settled semantic boundaries for moving a Finding from focused reasoning into authoritative case/update reasoning. It is a discovery document, not an implementation plan.
|
||||
|
||||
### Minimum handoff unit: FINDING-WITH-DISPOSITION-AND-PROVENANCE
|
||||
|
||||
The minimum viable object that crosses from focused to global is a **Finding** carrying its current proposition, status, at least one provenance contribution reference, and optionally an explicit user disposition. A Finding with no explicit disposition remains provisional and globally eligible for evaluation; it must not be treated as agreed, confirmed, or user-validated. Raw contributions alone are insufficient (no accumulated support). Full history is over-specified for v1.
|
||||
|
||||
### Required content classification
|
||||
|
||||
| Field | Status |
|
||||
|---|---|
|
||||
| Finding identifier | **REQUIRED** — needed for deduplication/merge/split |
|
||||
| current proposition | **REQUIRED** — the meaningful proposition/theme |
|
||||
| Finding status | **REQUIRED** — drives global eligibility |
|
||||
| Finding relevance | **OPTIONAL** — advisory; case/update may override |
|
||||
| Finding standing/confidence | **OPTIONAL** — advisory |
|
||||
| current user disposition | **OPTIONAL** — explicit semantic signal; silence remains provisional, never agreement |
|
||||
| originating targetNodeId | **ORIGIN-ANCHOR-REQUIRED-WHEN-AVAILABLE** — expected when the Finding came from an existing focused investigation; does not predetermine final graph mapping |
|
||||
| source focused question | **PROVENANCE-ONLY** |
|
||||
| source user answer | **PROVENANCE-ONLY** |
|
||||
| supporting contribution references | **REQUIRED** — minimum provenance chain |
|
||||
| challenging contribution references | **OPTIONAL** |
|
||||
| historical disposition references | **PROVENANCE-ONLY** |
|
||||
| historical wording references | **PROVENANCE-ONLY** |
|
||||
| sequence/timestamp | **OPTIONAL** |
|
||||
| branch/investigation context | **OPTIONAL** |
|
||||
| current unresolved aspect/question | **OPTIONAL** |
|
||||
|
||||
### Minimum provenance sufficiency: C — Finding + originating anchor (when available) + contribution reference(s)
|
||||
|
||||
Finding statement alone is insufficient (no origin). Adding an originating investigation anchor (when the Finding came from existing focused work) gives structural grounding. Adding contribution references establishes a traceable chain to at least one interpreted answer turn. Full question/answer provenance is useful but exceeds *minimum*. An absent originating node does not automatically invalidate a Finding if provenance still establishes where it came from and case/update can evaluate whether it exposes a new graph proposition.
|
||||
|
||||
### Raw provenance crossing rules
|
||||
|
||||
Raw contribution fields are not routine authoritative handoff state. They MAY be available as provenance when case/update needs to inspect source interpretation, and must never become authoritative merely because they cross. Assumptions and relationships remain explicitly untrusted/provisional provenance.
|
||||
|
||||
| Raw field | Crossing rule |
|
||||
|---|---|
|
||||
| raw user answer | **PROVENANCE-ON-DEMAND** — available for conflict resolution when needed |
|
||||
| raw focused question | **PROVENANCE-ON-DEMAND** |
|
||||
| raw observations | **PROVENANCE-ON-DEMAND** — belongs to contribution layer; available when case/update needs source inspection |
|
||||
| raw uncertainties | **PROVENANCE-ON-DEMAND** |
|
||||
| raw assumptions | **PROVENANCE-ON-DEMAND** — explicitly untrusted/provisional; never authoritative |
|
||||
| raw relationships | **PROVENANCE-ON-DEMAND** — explicitly untrusted/provisional; never authoritative |
|
||||
|
||||
### Finding state eligibility in case/update evaluation
|
||||
|
||||
| Status | Eligibility |
|
||||
|---|---|
|
||||
| candidate | ACCEPT-AS-ACTIVE-INPUT — provisional; unconfirmed by explicit user disposition |
|
||||
| provisional | ACCEPT-AS-ACTIVE-INPUT — eligible but unconfirmed by explicit user disposition |
|
||||
| agreed | ACCEPT-AS-ACTIVE-INPUT — explicitly user-supported evidence |
|
||||
| challenged / not quite | ACCEPT-WITH-RESTRICTIONS — eligible with qualification; correction needed |
|
||||
| not relevant | PROVENANCE-ONLY — retained but should not drive current priority |
|
||||
| reopened | ACCEPT-AS-ACTIVE-INPUT — reactivated by new evidence context |
|
||||
| superseded | ACCEPT-WITH-RESTRICTIONS — guides to superseding Finding; don't discard entirely |
|
||||
| resolved | PROVENANCE-ONLY — settled proposition; may still be evidentially relevant |
|
||||
|
||||
### Disposition validation outcomes
|
||||
|
||||
| Scenario | Outcome |
|
||||
|---|---|
|
||||
| Agree but no provenance | ACCEPT-WITH-RESTRICTIONS — valid disposition; standing advisory only without support chain |
|
||||
| Agree with contradictory evidence | ACCEPT-WITH-RESTRICTIONS — disposition accepted; weighed independently against contradicting evidence |
|
||||
| Not quite with no correction | ACCEPT-WITH-RESTRICTIONS — partial support recorded; needs refinement before strong standing |
|
||||
| Not relevant but high confidence | ACCEPT — relevance and confidence are separate dimensions |
|
||||
| No disposition / silence | ACCEPT — provisional Finding; eligible for case/update evaluation; never interpret lack of response as agreement |
|
||||
| Conflicting disposition history | ACCEPT-WITH-RESTRICTIONS — use latest; preserve conflict in provenance |
|
||||
| Disposition on materially changed proposition | REQUIRE-REFINEMENT — user may be responding to old wording |
|
||||
|
||||
### Relevance authority
|
||||
|
||||
**Multi-source with case/update authority.** Case/update **may** override incoming relevance. Focused reasoning proposes relevance from its investigation context; user disposition reflects investigation-fitness judgment; case/update has the broadest situational awareness and is the final arbiter.
|
||||
|
||||
### Standing/confidence authority
|
||||
|
||||
**Advisory.** Focused confidence has no inherent authority over global state. It is an advisory signal reflecting semantic status (provisional/agreed/challenged/not relevant/reopened/superseded/resolved). Case/update **may** independently revise standing after evaluation. Confidence scoring/weighting mechanism remains an unresolved implementation choice.
|
||||
|
||||
### Graph anchor and mapping
|
||||
|
||||
- Originating targetNodeId (when available): **ORIGIN-ANCHOR-REQUIRED-WHEN-AVAILABLE** — useful provenance; normally expected when the Finding came from existing focused work.
|
||||
- Originating targetNodeId does NOT predetermine final graph mapping.
|
||||
- Global graph mapping: **NOT-PREDETERMINED-BY-FOCUSED-LAYER** — case/update evaluates and may map to originating node, multiple nodes, a new unknown, or may reveal unresolved mapping.
|
||||
- Finding exposing a new proposition/unknown/cross-branch connection: **ALLOWED** — case/update evaluates whether this exposes a new graph proposition independent of originating anchor.
|
||||
|
||||
### Handoff rejection boundaries
|
||||
|
||||
| Scenario | Classification |
|
||||
|---|---|
|
||||
| Empty proposition | REJECT |
|
||||
| Duplicate of existing Finding | ACCEPT-WITH-RESTRICTIONS (merge candidate; contradiction ≠ invalidity) |
|
||||
| Contradicts an agreed Finding | ACCEPT-WITH-RESTRICTIONS (evaluate through reconciliation) |
|
||||
| No user disposition / silence | ACCEPT — provisional state; never interpret silence as agreement |
|
||||
| Marked not relevant | PROVENANCE-ONLY (retained but should not drive current priority) |
|
||||
| Target node already resolved | ACCEPT-WITH-RESTRICTIONS (may inform why resolution should be questioned) |
|
||||
| Originating target node no longer exists or unavailable | ACCEPT-WITH-PROVENANCE (origin missing does not invalidate Finding; case/update evaluates whether it exposes a new graph proposition) |
|
||||
| Provenance references stale/deleted contribution | WARN/DEGRADE (partial chain; evaluate remaining) |
|
||||
| Generated from failed assumption provenance | ACCEPT-WITH-RESTRICTIONS — assumptions remain untrusted/provisional; evaluate remaining evidence |
|
||||
| Generated from failed relationship provenance | ACCEPT-WITH-RESTRICTIONS — relationships remain untrusted/provisional; evaluate remaining evidence |
|
||||
| Proposition stronger than source evidence warrants | WARN/DEGRADE (strength claim unsupported; proposition may still be valid) |
|
||||
| No longer matches latest user correction | REQUIRE-REFINEMENT or ACCEPT-WITH-RESTRICTIONS |
|
||||
|
||||
### Allowed case/update outcomes
|
||||
|
||||
All listed below are **ALLOWED** for case/update after a valid handoff: accept as supporting evidence, accept as challenging evidence, store without changing graph priority, add evidence to existing graph proposition, surface new unknown, reopen existing unknown, resolve an unknown, refine/reword an unknown, change graph confidence/status (after independent evaluation), change activeUnknownNodeId, change selectedQuestion, reconstruct Current Understanding, reject Finding influence while retaining provenance, request further focused evidence.
|
||||
|
||||
### Case/update authority scope
|
||||
|
||||
Case/update **owns authoritative global graph reasoning** and may: evaluate Finding influence; accept/challenge/reject its effect on graph state; reconcile Findings against graph state; request refinement or further evidence.
|
||||
|
||||
Merge Findings, split Findings, re-identify Findings remain **FINDING-LAYER RESPONSIBILITY UNRESOLVED**. These decisions are part of the unresolved Finding-layer architecture and are not automatically owned by case/update solely because it owns graph impact evaluation.
|
||||
|
||||
### Prohibited behaviours for case/update
|
||||
|
||||
| Behaviour | Status |
|
||||
|---|---|
|
||||
| Treat user Agree as absolute truth | **PROHIBITED** |
|
||||
| Treat focused assumption as established fact | **PROHIBITED** |
|
||||
| Treat focused relationship as established causal link | **PROHIBITED** |
|
||||
| Promote not-relevant Finding into active priority without reason | **PROHIBITED** |
|
||||
| Discard challenged/superseded Findings from provenance | **PROHIBITED** (preserve in provenance) |
|
||||
| Silently rewrite raw source contribution | **PROHIBITED** (immutable provenance) |
|
||||
| Mutate user disposition history | **PROHIBITED** (immutable provenance) |
|
||||
| Change Finding proposition without retaining provenance/version history | ALLOWED-WITH-PROVENANCE |
|
||||
|
||||
### Idempotency: CONCEPTUALLY-USEFUL
|
||||
|
||||
Identical submissions should not cause double-counting or contradictory state changes. Conceptual identity = same proposition semantics + shared provenance lineage, regardless of wording differences across turns. Full idempotency via exact ID requires defining IDs/schema (out of scope). Semantic deduplication algorithm and Finding merge/identity resolution remain **FINDING-LAYER RESPONSIBILITY UNRESOLVED** — case/update may evaluate influence without a formal identifier contract.
|
||||
|
||||
### Ordering: INDEPENDENT
|
||||
|
||||
Findings are evidence carriers that case/update evaluates independently against global state. Ordering dependencies would create coupling between focused turns and evaluation. Case/update accumulates across all sources and computes authority from the full set. Individual Findings retain provenance sequence for internal traceability, but handoff processing is independent.
|
||||
|
||||
### Finding vs graph conflict: CASE-UPDATE-RECONCILES
|
||||
|
||||
When Finding says X and SituationGraph effectively says not-X, case/update treats this as conflicting evidence. Neither source overrides the other. Reconciliation: assess which Finding(s) have stronger provenance chains → weigh against current graph state through existing reconciliation mechanisms (reconciliation, branch interaction analysis, decision closure protection) → apply authoritative changes only if evaluation justifies them.
|
||||
|
||||
### Correction path: SEMANTIC-CONTINUITY-DECIDES
|
||||
|
||||
Whether a correction revises the same Finding or creates a new one depends on whether the semantic core persists across turns (same targetNodeId + overlapping provenance = revision; materially different assertion about different facts = new). This requires semantic continuity assessment at handoff time, not a predetermined rule.
|
||||
|
||||
### Not relevant path: YES-AS-PROVENANCE-ONLY; MAY REOPEN LATER: YES
|
||||
|
||||
A "not relevant" Finding crosses to case/update as provenance-only (discounted from active reasoning weight) because relevance is not static — new evidence elsewhere may make it material again. case/update **may** reopen its relevance based on later evidence.
|
||||
|
||||
### Validation ownership
|
||||
|
||||
| Stage | Owner |
|
||||
|---|---|
|
||||
| Structural handoff validation | case/update boundary |
|
||||
| Provenance validation | case/update |
|
||||
| Semantic evidence validation | case/update |
|
||||
| Graph-impact validation | case/update |
|
||||
|
||||
**Overall authority: CASE-UPDATE-BOUNDARY.** Focused layer may self-check; none is authoritative for graph state.
|
||||
|
||||
### Minimum v1 handoff contract (8 bullets)
|
||||
|
||||
1. **Object crossing:** A current Finding plus standing/relevance/disposition state and provenance.
|
||||
2. **Provenance:** At least one traceable source contribution; originating investigation anchor retained when available. Missing origin does not invalidate the Finding.
|
||||
3. **Disposition:** Optional explicit user signal. Silence remains provisional, never agreement. Explicit dispositions: Agree (user-supported), Not quite (challenging/corrective), Not relevant (relevance disposition).
|
||||
4. **Standing/relevance:** Semantic advisory state only; no weighting/scoring model assumed. case/update may independently set or override.
|
||||
5. **Mapping:** Originating target does not dictate final graph mapping; case/update determines graph impact/mapping including new propositions, multiple nodes, or unresolved mapping.
|
||||
6. **Authority:** Case/update solely owns graph mutation, Current Understanding and frontier selection. Finding identity (merge/split/identity) remains unresolved at the Finding layer.
|
||||
7. **Validation:** Reject malformed/untraceable evidence; contradiction or lack of explicit disposition alone is not rejection.
|
||||
8. **Retention:** Challenged/not-relevant/superseded/rejected influence remains in provenance and may later become relevant again.
|
||||
|
||||
### Decision gate: FINDING-HANDOFF-CONTRACT-READY
|
||||
|
||||
This contract defines the semantic boundaries needed for implementation to proceed without inventing trust/validation rules in code.
|
||||
|
||||
### Explicitly unresolved (intentionally)
|
||||
|
||||
- JSON/API payload shape
|
||||
- Finding schema and ID system
|
||||
- Storage/persistence implementation
|
||||
- Confidence scoring mechanism / standing representation
|
||||
- Contribution↔Finding clustering/mapping
|
||||
- Finding merge/split ownership
|
||||
- Semantic identity/deduplication algorithm
|
||||
- Final Finding→graph mapping mechanism
|
||||
- Relevance representation details
|
||||
- Automatic reopening triggers/algorithm
|
||||
- UI presentation of dispositions
|
||||
|
||||
Reference in New Issue
Block a user