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