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.

### 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/`.