From 854160726ebb83e7d77e18b1592ee08d286a43c7 Mon Sep 17 00:00:00 2001 From: robbond Date: Wed, 26 Aug 2026 14:50:15 +0100 Subject: [PATCH] docs(confidence-engine): define focused finding handoff contract --- docs/current-handoff.md | 190 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 190 insertions(+) diff --git a/docs/current-handoff.md b/docs/current-handoff.md index 9176bf7..ef377c5 100644 --- a/docs/current-handoff.md +++ b/docs/current-handoff.md @@ -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