confidence-engine/docs/current-handoff.md

Confidence Engine — Current Handoff

Repository Position

• Branch: feature/current-understanding-reconstruction-v0.50
• Trusted checkpoint: 0624bc2 fix(confidence-engine): gate focused completion during processing
• Working tree: clean

Current Reasoning Loop

understand situation
→ identify uncertainty
→ focused investigation
→ capture/deconstruct evidence
→ canonical Findings
→ complete focused episode
→ reconsider authoritative SituationGraph
→ regenerate Current Understanding
→ expose what matters next

Done for now is the semantic completion boundary of the focused investigation. The processing gate at 0624bc2 prevents completion while the latest focused deconstruction is still processing. Done does NOT mean the parent decision is closed — only that no further immediate evidence capture is warranted.

Current Canonical State

Evidence is sufficient

No new evidence-capture mechanism is required. A minimum lossless completed-episode state consists of:

SituationGraph
+ target-scoped ordered Contributions
+ associated canonical Findings

Contributions preserve the focused interaction including: question/context, verbatim user answer, model-derived observations, uncertainties, assumptions, relationships, follow-up questions, target/provenance, sequence/order.

Findings preserve: current canonical proposition, sourceObservation, contributionId, originatingTargetNodeId, userDisposition.

Evidence distinctions (must be preserved by future reasoning)

RAW USER EVIDENCE
≠ MODEL-DERIVED CONTRIBUTION SEMANTICS
≠ CURRENT CANONICAL FINDING
≠ IMMUTABLE SOURCE OBSERVATION
≠ USER DISPOSITION / AUTHORITY
≠ TURN CONTEXT / PROVENANCE

Finding semantics

Disposition	Meaning
null	Eligible working premise — NOT explicit endorsement
agree	Explicitly user-endorsed canonical proposition
not_relevant	Excluded from eligible current reasoning; provenance retained
corrected Finding	Corrected proposition becomes current canonical proposition; sourceObservation immutable; disposition resets to null

Critical: Finding.userDisposition does NOT establish parent-decision closure authority. User disposition is evidence for global reasoning — it never directly mutates authoritative graph state.

Completed Focused Episode

A focused episode is complete when:

1. Deconstruction LLM returns and Contribution(s) are stored
2. Processing gate is satisfied (no in-flight deconstruction)
3. Done for now has been emitted as the completion boundary

The processed state contains:

• SituationGraph — authoritative graph (may reflect pre-investigation state at the moment of Done)
• Ordered Contributions — target-scoped, preserving provenance and semantic fields
• Canonical Findings — derived from contributions with user dispositions

Authoritative Graph Reconsideration Architecture (CURRENT)

This is the current redesign target for graph-update input.

The preferred architecture:

SituationGraph
+ deterministically structured completed episode
        ↓
ONE expanded graph-update reasoning operation
        ↓
GraphUpdateProposal
        ↓
independent deterministic safeguards/application
        ↓
updated authoritative SituationGraph

Not required / not justified:

• Separate episode model call for internal reconciliation
• Persistent EpisodeSemanticResult entity

The provider/model may reconcile episode meaning and graph implications in the same graph-reasoning operation.

Deterministic episode preparation (before reasoning)

Existing state should be classified so the model does not receive an undifferentiated evidence bag:

eligible canonical Findings
excluded not_relevant Findings
ordered raw Q/A
Contribution semantic fields
provenance/context
SituationGraph

This establishes classification and precedence. It does NOT itself perform cross-turn semantic synthesis.

GraphUpdateProposal

The existing typed GraphUpdateProposal remains the conceptual boundary between evidence reasoning and authoritative graph application. It is not inherently single-turn — it may carry multi-turn episode content. Do not introduce a replacement proposal type merely because the evidence is multi-turn.

Independent safeguards

Provider/model reasoning may: interpret evidence, reconcile episode meaning, reason about graph implications, propose graph changes.

It must NOT become sole authority for:

• explicit user closure authority
• evidence fidelity
• comparability establishment
• graph sufficiency
• canonical Finding eligibility
• canonical correction precedence

Explicit parent-decision closure authority must remain grounded independently in retained actual user evidence/context. Comparability may need episode-aware derivation because SituationGraph/reasoningState can still reflect the pre-focused-investigation state at Done.

Current Understanding

Current Understanding is a separate presentation concern, architecturally distinct from graph reasoning:

canonical graph + eligible/corrected Findings
        ↓
dedicated Current Understanding synthesis
        ↓
coherent user-facing explanation

A separate LLM call here remains appropriate because this operation serves presentation/coherence, not authoritative episode interpretation. Desired presentation direction: short, clear, scannable, plain language, minimal repetition. Do not redesign or tune the CU prompt now.

Done-for-now interaction (current bounded contract)

Done for now is user-owned and has immediate visible effect — the engine does not decide whether enough evidence has been gathered.

On clicking Done for now:

1. Question parks immediately under "Questions we have clarified" with Clarified status + Re-open button
2. Focused investigation workspace closes without waiting for async pipeline
3. Current Understanding loading begins immediately — skeleton overlay appears while the async pipeline runs
4. Skeleton spans: episode reconsideration → graph application → CU synthesis
5. CU refresh completes the investigation checkpoint — new CU replaces skeleton when ready

The skeleton overlay uses strong paragraph-style bars with varied widths and a left→right shimmer, centred status message ("Clarifying your current understanding…"), and an opaque background that fully obscures old CU content until synthesis succeeds or fails.

Current Understanding refresh invariant

Reconstruct Current Understanding when canonical meaning or the eligible evidence set changes. Do not reconstruct it merely because investigation/question status changes.

Transition	Canonical meaning/evidence changes?	CU synthesis
Re-open clarified question	No	No
Not quite click before correction is saved	No canonical corrected meaning yet	No
Save corrected Finding proposition	Yes	Yes
Mark eligible Finding Not Relevant	Yes	Yes
Restore previously Not Relevant Finding	Yes	Yes
Complete focused episode / Done	Yes	Yes

Key distinction: Re-open = change what we are willing to question. Finding correction / Not Relevant / completed new evidence = change what we currently understand.

A Current Understanding may legitimately say that the evidence currently makes an explanation less likely while the corresponding question is Open again for further investigation. Do not prescribe special Re-open wording in generated Current Understanding prose, and do not add a requirement to mention "reopened", "previously resolved", or "reconsidered" inside generated Current Understanding. The Current Understanding should describe what the evidence currently supports, not narrate workflow status.

Closed Boundaries — Do Not Reopen

These are settled and must not be revisited in future work:

• Finding canonical model and dispositions (null/agree/not_relevant/corrected)
• focused Contribution → Finding derivation
• Finding correction semantics
• not_relevant / restore behaviour
• async investigation persistence provider
• focused investigation workspace lifecycle
• Done processing gate (0624bc2)
• dedicated Current Understanding synthesis seam
• Finding-side CU synthesis triggers
• GraphUpdateProposal as reasoning/application boundary
• existing evidence sufficiency (no new capture mechanism needed)
• no separate episode semantic model stage currently justified

Where deeper history is required, reference: docs/design-evolution-log.md, docs/archive/experiments/, docs/methodology-checkpoint-return-to-origin.md. Do not reproduce that history here.

Context / Execution Route

For normal Confidence Engine work, use the existing routing system:

• docs/task-context-packs.md — task routing
• docs/current-working-principles.md — durable methodology (axiomatic principles A1–A12)
• docs/Confidence_Engine_Return_to_Origin_Methodology_Context_2026-08-18.md — Return-to-Origin methodology
• .claude/architecture-guardrails.md — architecture guardrails
• .claude/working-rules.md — executor process rules

Historical material is read only when a specific unresolved fact requires it.

Immediate Next Implementation Target

Replace/adapt the old single-turn graph-update input boundary so authoritative reconsideration can consume the deterministically structured completed focused episode — target-scoped ordered Contributions + associated canonical Findings + SituationGraph — while reusing the existing graph-update reasoning and GraphUpdateProposal machinery and preserving independent safeguards.

Narrow first increment

The first implementation should be scoped to wiring the deterministic episode preparation (classification, ordering, provenance extraction) into the existing graph-update prompt builder. The output path already exists via GraphUpdateProposal. Do not:

• redesign GraphUpdateProposal
• add new LLM calls
• introduce EpisodeSemanticResult
• begin with RELOAD-B or cold-return CU freshness
• tune Current Understanding presentation

History of old restart points removed as current authority:

case/update synthesis integration          → historical experiment (v0.50)
RELOAD-B / cold-return CU freshness      → historical checkpoint
60B experiments                            → apparatus-contaminated evidence
v0.48–v0.49 persistence/recovery work     → completed closed boundaries
Contributions→Findings domain discovery    → captured in canonical state above
Finding↔SituationGraph reasoning contract  → captured in authoritative graph section

These architectural decisions are preserved as settled current state, not as historical narrative. Detailed experiment evidence remains in docs/archive/experiments/.