robbond/confidence-engine

Fork 0

Files

T

robbond 0f4dfcbb17 fix(confidence-engine): show canonical findings in previous learning

2026-08-29 14:38:04 +01:00

114 KiB

Raw Blame History

Confidence Engine — Current Handoff

Repository position

v0.47 and earlier work is preserved below for historical continuity. v0.48 investigation-storage architecture begins after the Return-to-Origin checkpoint section (line 132+).

branch: feature/investigation-storage-provider-v0.48
checkpoint commit: d55f179d37dc1ec45e18a2b858b90f2aa22e6580

Current green reasoning state

substantive-tie active ownership: In complete unresolved ties among top-scoring candidates, the currently active node is preserved as the selection winner rather than falling through to stable label/display-order ordering. This only applies when the active node is eligible and remains substantively tied at the structural level.
question-rejection active ownership: When a selected candidate's graph-backed question formulation is rejected as too complex (decomposition-required), the selected target node retains its ownership — it is not reseated to another candidate via reseatSelectionAfterQuestionRejection. Instead, the selection remains on the original node with selectedQuestion = null and an explicit rejection reason.
QUESTION_CONTINUATION: Existing question continuation logic remains intact and functional after the question-rejection fix.
60B.84: State B guard correctly does not fire for specific factor nodes merely because they are inside a decision context.
State B: Sufficiency question path reaches expected terminal state without unintended firings.
captured product-launch replay: The live product-launch start graph replays deterministically: ntpt9ki remains the active investigation target with no question selected after formulation rejection.

Latest resolved reasoning boundaries

1. Complete substantive selection tie

previous behaviour: When all leading structural candidates were tied, the system always fell through to stable label/display-order as the final deterministic tie-breaker, regardless of which node was currently active in the investigation.
corrected invariant: If the active node is among the tied structural candidates and remains eligible (unresolved, not contradicted), it is preserved as the winner. The stable label/display-order fallback is only used when there is no active candidate or when the active candidate does not remain among the top structural ties.
regression location: lib/graph/utils.js — classifyCandidateOrdering() now accepts an activeNodeId parameter and checks for active-tied candidates within the leading structural set before using display-order fallback. Callers in selectActiveUnknownCandidate() and explainUnknownSelection() pass graph.activeUnknownNodeId.
regression test location: tests/graph/utils.test.js — tests: "preserves the active candidate when it remains eligible and substantively tied", "transfers ownership when the active candidate substantively loses on score", "transfers ownership when the active candidate is resolved or ineligible"

2. Question-formulation rejection

previous behaviour: When a selected candidate's question formulation was rejected (decomposition required), determineGraphBackedQuestion called reseatSelectionAfterQuestionRejection with excludedNodeIds that excluded the current target, causing investigation ownership to transfer to another candidate — even though the original target remained the strongest unresolved unknown.
corrected invariant: The selected node keeps its status and selection identity. selectedQuestion is set to null and questionSuppressedReason records the rejection explanation. No reseating occurs.
regression/captured fixture location: tests/graph/orchestrator.test.js — "retains ownership when the strongest target's formulated question is rejected"; captured replay via tests/fixtures/live-product-launch-start-response.json

Current deterministic product-launch evidence

deterministicSelection.nodeId = ntpt9ki (active investigation target preserved)
selectedQuestion = null after rejected formulation
explicit noQuestionReason: "The selected investigation target remains active, but its current graph-backed question formulation was rejected as too complex."
nxmeiab is not substituted in place of ntpt9ki

Current product meaning

activeUnknownNodeId represents ongoing investigation ownership — it tracks which unknown candidate the system has committed to investigating.
Wording/formulation failure (question complexity / decomposition-required) does not itself invalidate the target. The target remains selected even when its formulated question cannot be answered in one step.
Stable label ordering remains only a final fallback after substantive scoring, structural comparison, semantic signature checks, and tie/ownership handling are all exhausted.

Not yet proved

live behavioural validation after these fixes (requires an actual product-launch run through the dev server)
whether same-target reformulation is better than no-question (system currently uses no-question approach)
broader/full-suite state beyond the six verified guards
correctness of the question-complexity heuristic itself (that is a separate design concern)

Canonical live apparatus for next validation

scripts/reproduce-multi-turn-investigation.mjs
existing healthy dev server
.env.local authoritative for:
- OLLAMA_BASE_URL
- OLLAMA_MODEL
no model discovery
no supplementary harnesses
no direct Ollama calls

Next recommended step

one observation-only live product-launch validation using the fixed scenario from the recorded journey
no production changes during the experiment
verify that the live LLM responds consistently to the null-question state and continues investigation on ntpt9ki

Apparatus correction: 60B.101 — null-question start capture

The canonical startOnly harness was corrected to accept successful Start responses with selectedQuestion = null. Previously, any successful Start returning no graph-backed question (legitimate outcome meaning "target remains active but no askable question available") caused the harness to block and fail.

Change: The harness now checks success === true + valid situationGraph as the sole gate for startOnly success. selectedQuestion is preserved exactly (including null) in the continuation state file without coercion.

Impact on 60B.100: The evidence from 60B.100 was captured via direct curl because the harness blocked on null-question Start. That evidence is now marked as apparatus-contaminated and provisional observation only.

Canonical harness gated apparatus (60B.99)

The canonical harness (scripts/reproduce-multi-turn-investigation.mjs) now supports a two-phase gated investigation pattern:

startOnly — FIXTURE_MODE=startOnly

Makes exactly one /api/cases/start request
Writes the captured Start state (graph + selectedQuestion) to .evidence-temp/continuation-start-only.json (or path set by CONTINUATION_FILE)
Issues zero Update requests
Exits successfully

continueOneUpdate — FIXTURE_MODE=continueOneUpdate CONTINUATION_ANSWER=<answer>

Loads the persisted Start continuation state
Requires explicit answer (blocks with exit code 1 if missing)
Makes exactly one /api/cases/update using preserved Start state + explicit answer
Issues zero Start requests
Exits

Normal mode (FIXTURE_MODE unset) — unchanged. Start → configured Update loop still works identically to pre-60B.99.

This apparatus corrects the apparatus defect proven in 60B.98: the canonical harness can now stop after Start, allow external semantic inspection of the returned question, and later continue from that exact captured state with an explicitly chosen answer.

Experiment 60B.95 result (2026-08-17)

Classification: E — LIVE PATH DIVERGED

The live model selected nk6eyn2 ("exact monetary value of potential enterprise contract relative to £300k launch cost") as the investigation target, not npzfx36 ("likelihood, negotiation stage, and targeted signing date for the large enterprise customer"). Both are unresolved unknowns in the same scenario. An acceptable question was produced ("What outcome would demonstrate enough value to justify launching a software product now?"), so the question-rejection boundary was not reached.

What this establishes: The live engine can produce an acceptable graph-backed question on a fresh product-launch start without requiring decomposition.

What this does NOT prove: Whether investigation ownership is preserved when a selected target's formulation is rejected (the core invariant from checkpoint 60B.93). The question-rejection boundary was not reached because the live model chose a different investigation target with an acceptable question path.

Experiment 60B.97 result (2026-08-18)

Classification: E — START PATH DIVERGED

The live model again selected a non-financial-comparison target on the product-launch scenario. The Start selected enterprise-customer signing probability ("What evidence would clarify probability or likelihood that the enterprise customer will sign within the current launch window?") rather than the expected cash-flow / NPV comparison.

Valid evidence retained: Start = S2 — DIFFERENT START (the live model diverged from the expected financial-comparison path).

Update 1 evidence: DISCARDED. The canonical harness auto-continued with its preconfigured answers[0], so the Update occurred outside the experiment's semantic gate. This was an apparatus defect (60B.98) — the harness did not provide a post-Start stop gate at that time. The HTTP 500 is NOT established as a reasoning defect from 60B.97.

Apparatus correction: See section "Canonical harness gated apparatus (60B.99)" above for the fix.

Experiment 60B.100 result (2026-08-18)

Classification: B — DETERMINISTIC SELECTOR OVERRIDES MODEL QUESTION

On a fresh product-launch Start, the LLM reconstruction question targeted one uncertainty ("What is the estimated probability that the large enterprise customer will sign?") while the deterministic graph-backed selector chose another ("What evidence would clarify the exact percentage of total projected revenue attributable to the enterprise customer?"). These are materially different: one asks about deal timing/commitment probability, the other asks about financial proportion/magnitude.

The override was produced by fixed actor_match keyword scoring: node n65sgyd's label contained "enterprise customer" which matched the actor dictionary (+10 delta), giving it a decisive score of 10 vs 4 for both competitors. No tie/fallback was involved — the winner was determined entirely by keyword rule weighting.

What this establishes: On fresh Start calls, deterministic keyword signals can override model-inferred investigation priority when node labels differ in dictionary-match patterns. The final investigation target is not the model's contextual judgment but the highest-scoring candidate under fixed scoring rules.

What this does NOT prove: Whether the deterministic selection is better or worse than the model's suggestion; consistency across scenario types; or downstream investigation quality impact.

RETURN-TO-ORIGIN CHECKPOINT

selector-led compulsory next-question optimisation is PAUSED

semantic-selector replacement is also PAUSED

Recent work is preserved as valuable experimental learning. The graph/reconstruction/decomposition/invariant work remains potentially reusable. No replacement architecture has been selected.

The next phase starts from the workspace/methodology question, not from a preselected technical solution.

Required methodology-continuity context (read first)

Before continuing any Confidence Engine reasoning development, load these in order:

docs/current-working-principles.md §0 (Axiomatic Principles A1–A12)

docs/Confidence_Engine_Return_to_Origin_Methodology_Context_2026-08-18.md

The axiomatic principles in current-working-principles.md are now the durable methodological anchor. They codify delivery-platform independence, meaning-over-dictionary reasoning, user-directed non-linear investigation, provisional closure, and progressive disclosure. All future work must be evaluated against these 12 axioms.

The RTO methodology context document covers:

What Confidence Engine is (reasoning method, not software or LLM)
What it is not
The granular answer-fragment hypothesis (working — not architecture)
RTO.14–17 learning and why they did not define the next architecture
Memory/graph separation principle
Optional capability: "Help me answer" / "Answer for me"
Methodology test for future development
Recent experimental evidence (RTO.18, RTO.20–RTO.22) supporting durable principles

Do not begin reasoning development from the latest experiment apparatus. Always load this methodology continuity context first. Without it, a new session will reconstruct the project from recent technical experiments and lose sight of the method the application is meant to embody.

Current Git checkpoint

Branch: feature/decision-closure-ownership-v0.47
HEAD: e1b54e407389c7f1c25ba20645540d404b9e9df9
Latest commit: e1b54e4 test(experiment): checkpoint granular answer fragment apparatus

Status of RTO.14–17

RTO.14–17 experiments proved that an LLM can retain focused knowledge and carry coherent reasoning across turns inside a single investigation. This was valuable evidence.

However, they also revealed that the cumulative reconstruction pattern was reproduced at a lower scope. Do not treat RTO.14–17 as the automatic architecture direction to continue. The next reasoning direction is the granular answer-fragment hypothesis: independent user-chosen question/answer deconstruction without accumulated focused state being passed between LLM calls.

Prohibition: Do not automatically continue into cumulative-state compression or fourth-turn experiments without first revisiting the methodology continuity document above.

Focused Semantic Deconstruction — Reasoning Status (2026-08-24)

Current state

Branch: feature/decision-closure-ownership-v0.47
HEAD: 2c108df5a92ec4cb0c4fa7878002cb7eb0aea4fd

Working tree:

 M lib/graph/focused-investigation.js
?? tests/graph/live-focused-deconstruct-experiment-helper.mjs

No unexpected temporary files or evidence directories.

Canonical focused helper

tests/graph/live-focused-deconstruct-experiment-helper.mjs

Exports runLiveFocusedDeconstructExperiment. Future focused semantic experiments should: import it directly; use the real production buildFocusedDeconstructPrompt; use the production validator/provider through the helper; configure .env.local for OLLAMA_BASE_URL and OLLAMA_MODEL; make the explicitly budgeted number of live calls; never inline prompt/provider/schema logic; never replace the helper ad hoc.

Product flow context

initial scenario → initial/global SituationGraph → user selects original open question/thread → focused formulate → user answer → focused deconstruct → contribution retained against original targetNodeId → subsequent focused formulate/deconstruct rounds

Focused deconstruction accumulates focused contributions rather than rewriting the initial global SituationGraph. Reuse/integration of accumulated focused learning is a later question, not part of this checkpoint.

Semantic rules currently under review (validated in the cumulative diff)

The production buildFocusedDeconstructPrompt encodes six semantic principles:

Observation fidelity — only meaning directly supported by what the user's answer states becomes an observation; do not strengthen implications into observations.
Uncertainty fidelity — preserve uncertainty at the narrowest scope justified by evidence; when one factor is established but nothing else is, keep remaining uncertainty broad rather than inventing specific additional factors/deficits/causes/interventions.
Assumption attribution — attribute only propositions that the user's answer would cease to make sense if false; do not import plausible interpretations from investigation context or model analysis into the assumptions field; return assumptions: [] when no genuine assumption exists.
Relationship strength — only connections the user's answer directly establishes become relationships; co-mentioned facts do not create causal/constraint/dependency links.
Proposition ownership — track who owns each proposition (user's comfort, willingness, threshold, belief, judgement, etc.); do not elevate subjective stance into objective requirement or situational constraint.
Evidence-first / action-appropriate follow-ups — before formulating follow-ups, check whether the question tests a proposition against current epistemic state; if an explanation/deficit/cause/intervention has not been established by evidence, phrase the question to test whether that proposition is true rather than assuming it; do not jump to implementation details until intervention is the relevant next issue.

A supporting negative principle also holds: Do not solve semantic interpretation with an ever-growing deterministic dictionary/regex system. Structure may be deterministic; meaning remains semantic/LLM-based.

Validated learning (bounded evidence)

Bounded focused experiments on this branch showed:

The original real UI failure was reproduced on the actual focused-deconstruct path.
Observations could remain faithful while assumptions/relationships were weakened beyond what the user stated.
Tightening the assumptions contract materially reduced model-generated assumptions being attributed to the user, supported by bounded contrast.
Genuine implicit dependencies can still be preserved through the tightened boundary.
Proposition ownership preserves subjective criteria without weakening genuine factual reports.
Tentative factual reports can retain their uncertainty.
Evidence-first follow-ups avoid premature remedy; practical follow-ups remain possible once a blocker is established.
Uncertainty specificity follows user-supplied evidence rather than defaulting to generic broadness.

Do not treat these as generalisation: each finding is supported by the bounded contrast of tested cases only.

EXP13 status: CONTAMINATED

EXP13 - CONTAMINATED — excluded from evidence

Reasons: iterative production prompt refinement; best-supported live-call count = 4; not valid bounded experiment evidence; tuned EXP13 uncertainty wording was removed during the diff. EXP13 must not be cited as proof of uncertainty behaviour.

EXP13R / EXP14 (valid but conservative)

EXP13R: materially reduced invented uncertainty specificity but retained some residual operational specialisation.
EXP14: showed the same rule could preserve explicit user-supplied BACS/failed-payment specificity while leaving unidentified additional gaps broad.

Do not conclude that the uncertainty boundary is fully solved. The contrast between these two cases does not establish generalisation.

Current restart point

The immediate semantic pass has established a coherent working principle:

The Engine should preserve what was said, how certain it was, who owns the proposition, and how strongly evidence supports relationships; then investigate missing evidence before inventing explanations or remedies.

Deterministic tests (22/22) verify the structural boundaries. Live-call evidence is bounded. No new experiment is run in this checkpoint.

LIVE MANUAL WALKTHROUGH FINDING — Focused Progression UI (2026-08-26)

Verified during repaired Run A multi-turn focused-investigation flow

The following was established by live manual walkthrough:

Run A presentation entry routing: FIXED
Run A focused lifecycle continuity: FIXED
focused question/form/response rendering inside Run A: FIXED
same-node completed result reopen: FIXED
multi-turn focused continuation: WORKING

KNOWN UI PROGRESSION / OWNERSHIP DEFECT — Follow-up Selected-Question Duplication

During the repaired Run A multi-turn focused-investigation flow:

focused answer
→ deconstruction
→ "Questions this raises"
→ user clicks the single proposed follow-up
→ that follow-up becomes the active QUESTION above the textarea

The UI then continues to show the same previous proposal below under:

QUESTIONS THIS RAISES
[same question] → pick this question

So the selected follow-up is simultaneously displayed as:

ACTIVE QUESTION

and:

STILL-AVAILABLE ACTIONABLE FOLLOW-UP

This is visibly duplicated and demonstrates that the proposal state and active-question state are disconnected.

Product interpretation: This is a KNOWN UI PROGRESSION / OWNERSHIP DEFECT, not merely a styling issue. The useful semantic progression is:

answer → what this tells us → still unclear → proposed next question → user selects it → selected question becomes active

Once selected, its old representation must not continue to invite:

→ pick this question

The old proposal should either become non-actionable provenance/history or cease being displayed as a candidate. Do not decide the final UI treatment in this checkpoint.

Record also that possibleFollowUpQuestions currently contains exactly one proposed question, while the user-facing heading says "Questions this raises" and presents it as a selectable candidate. This raises a later product/ownership question:

Is this genuinely a menu of candidate questions, or is it the engine's proposed continuation of the current investigation?

Do not resolve that question now.

Status of remaining items after this walkthrough

follow-up selected-question duplication:
OPEN UI ISSUE

focused → global ownership/integration:
STILL OPEN

Current Understanding incorporating focused learning:
STILL OPEN

Important separation note

The latest second-turn semantic output exposed a separate reasoning issue around assumption attribution/frontier prioritisation. This must not be conflated with the UI duplication defect described above. They are orthogonal concerns — one is presentation state management, the other is semantic reasoning fidelity.

CONTRIBUTIONS → FINDINGS DOMAIN MODEL (2026-08-26)

Discovery scope

This section records a domain model discovery based on live manual walkthrough evidence across multiple focused deconstruction turns. It determines whether the Confidence Engine needs an explicit distinction between Contribution, Finding, and Investigation for use in the eventual focused→global handoff.

Key finding: Contribution ≠ Finding

Contribution:
  immutable provenance from one answer interpretation.
  Captures: what the model observed about what the user said at one turn.
  Contains: observations, uncertainties, assumptions, relationships, follow-ups.
  Mutated: NO — it is a record of one interpretation event.

Finding:
  living conceptual proposition/theme in the investigation.
  Accumulates support from multiple contributions across turns and branches.
  Carries user disposition (agreed / challenged / not relevant).
  Can change standing; can be reopened by new evidence.

Why contributions alone are insufficient

Evidence from live walkthrough:

Same idea across turns: Same conceptual themes emerge in different wording across multiple focused deconstruction turns. Without higher-level grouping, these appear as disconnected observations.
Latest-result replacement: focusedInvestigations[nodeId].result only holds the latest result. Older findings disappear even when still conceptually valid.
Cross-branch evidence: A previous finding may gain or lose significance when new evidence appears on a different branch. The turn-based model has no mechanism to express this cross-branch linkage.
User validation gap: Users need lightweight exception disposition controls — only "Not quite" and "Not relevant" are needed as explicit actions. All others default to accepted-by-default (still revisable). These have no semantic home under a contribution-only model.

Note (2026-08-26): Earlier exploration treated "Agree / Not quite / Not relevant" as three equally explicit user actions. The current product direction supersedes this: the UI presents findings under "What this tells us," which establishes accepted-by-default interpretation. Only two exception actions are needed — see Findings Interaction + Attention Model below.
Reopening needed: A previously "not relevant" finding may become material again when later evidence connects to it. No durable entity exists to carry this state across turns.

Truth vs relevance must be separate dimensions

true but irrelevant — supported by evidence, does not drive current investigation
relevant but uncertain — important question with limited supporting evidence
agreed and highly relevant — user confirmed; strong global reasoning input
challenged but still important — imprecise but guides investigation direction
previously irrelevant, reopened by new evidence — status changed, weight restored

These cannot be combined into a single score without losing critical investigation state.

User dispositions are semantic, not UI-only

Accepted by default (no explicit action required) → user treats as working premise for the current investigation (not absolute proof; still revisable if later evidence or the user challenges it)
Not quite → interpretation needs correction (partially supported); user may reword/correct the finding; original engine wording retained in provenance
Not relevant → may be true but should not drive this investigation (discounted from active reasoning weight, preserved in provenance); not permanently excluded — may be reopened by later evidence

Default state terminology: prefer accepted-by-default / corrected-by-user / not-relevant. Existing runtime values (null, agree, not_quite, not_relevant) may remain temporarily for compatibility, but the product contract does NOT require an explicit agreement interaction. Final runtime enum/state representation is unresolved implementation detail.

These dispositions carry semantic weight that the reasoning system should consume for confidence and handoff decisions.

Reopening principle

A finding should be durable, but its standing and relevance should remain revisable when new evidence appears elsewhere.

Reopening = new evidence has made a previously settled / discounted / irrelevant proposition material to the investigation again. The previous disposition is preserved in provenance; the finding gains new weight with explicit status indicating why it was reopened.

Contribution → Finding relationship

Cardinality: Many-to-one (multiple contributions converge on one evolving conceptual finding)
Provenance: Essential — every finding must track which contributions support it, which dispositions were applied, and what later evidence supports or challenges it

SituationGraph relationship

A Finding is a user-facing grouping over one or more graph propositions. It is not simply another name for an existing graph node, nor is it unnecessary — it is the conceptual layer the user reasons about, built on top of graph nodes as structural anchors.

Impact on focused → global handoff

Material change: The handoff question shifts from "copy raw focused fields into global reasoning" to:

focused contribution
  → candidate / evolving finding
  → user disposition + provenance + later evidence
  → finding standing changes
  → eligible global reasoning input

Blindly converting observations/uncertainties/assumptions/relationships into graph mutations would be unsafe because:

Assumptions may be wrong (model misattribution)
Relationships may overreach (co-mention ≠ causation)
Relevance may change across investigation branches
Tentative language may have been strengthened in a later turn
Findings may later be reopened — their status is not final at handoff time

Global eligibility matrix

Item	Eligibility
Raw contribution	LOCAL/PROVENANCE-ONLY (unless no finding exists)
Provisional finding	GLOBAL-ELIGIBLE-WITH-STATUS (reduced weight)
Agreed finding	GLOBAL-ELIGIBLE (strong support)
Challenged / not-quite	GLOBAL-ELIGIBLE-WITH-STATUS (partial support)
Not-relevant finding	LOCAL/PROVENANCE-ONLY (discounted, preserved)
Reopened finding	GLOBAL-ELIGIBLE-WITH-STATUS (weight restored by new evidence)
Superseded finding	GLOBAL-ELIGIBLE-WITH-STATUS (use superseding finding)
Unresolved finding	GLOBAL-ELIGIBLE-WITH-STATUS (triggers further investigation)

Primary user-facing reasoning object

Findings, not contributions or turn history. Contributions and turns are provenance underneath; findings are what the user actually reasons about. The investigation is conceptually about building understanding, not collecting answer-interpreters.

Product principle alignment

"The Engine's primary job is to progressively build a trustworthy representation of the situation. Questions are the mechanism used to improve that representation."

STRONGLY-ALIGNS. Confirmed by both the Return-to-Origin methodology and live walkthrough evidence. The engine's product is the trustworthy representation (findings + confidence), not the graph structure or question sequence.

Confidence emerges from:

Confirmed findings (agreed)
Provisional findings (accumulating support)
Challenged findings (partial, needs refinement)
Irrelevant/discounted findings (understood, not driving)
Contradictions between findings
Unresolved gaps
Evidence provenance (how many contributions support each finding)
Stability under new evidence
Ability to reopen findings when relevance changes

Decision: FINDINGS-DOMAIN-MODEL-JUSTIFIED

The distinction is clearly useful enough that focused→global integration should be designed around findings/provenance rather than raw turn outputs. The semantic gap between "what one answer contributed" and "what the investigation has found so far" is real and material.

Finding ↔ SituationGraph Reasoning Contract — August 2026

Finding is a separate durable reasoning entity. It is not itself a SituationGraph node.
Finding ↔ graph relationship is conceptually many-to-many. One Finding may support/challenge multiple graph propositions. Multiple Findings may support/challenge one graph proposition.
Findings do not directly mutate the SituationGraph. They are evidence carriers, not graph mutation agents.
case/update remains authoritative for:
- graph node creation/update
- resolving/reopening unknowns
- graph confidence/status changes
- activeUnknownNodeId
- selectedQuestion
- Current Understanding
Trust model: focused reasoning proposes Findings/evidence → user disposition affects standing → case/update independently evaluates → authoritative graph changes happen only through case/update.
User dispositions — The current product direction uses accepted-by-default as the normal state and only two explicit exception actions (Not quite, Not relevant). Earlier versions documented these as three equally explicit actions (Agree / Not quite / Not relevant); that exploration phase is superseded by the accepted-by-default model. Dispositions are semantic signals that INFORM global reasoning. They do not directly bind graph truth.
Finding status and graph node status remain separate concepts. One does not dictate the other.
Relevance and confidence remain separate dimensions. A Finding can be high-confidence but low-relevance, or vice versa.
Low-relevance Findings may remain in provenance/evidence without affecting active investigation priority.
Findings may be reopened when later evidence changes their relevance or standing.
Current Understanding should ultimately be reconstructed by case/update from globally eligible Findings + graph state, not directly from the latest focused result.
Findings may influence but do not own: active frontier, selectedQuestion. Only case/update sets these.
Raw focused fields must not be blindly copied into graph mutations. Case/update evaluates accumulated evidence through authoritative reasoning paths (reconciliation, branch interaction analysis, decision closure protection).
Minimum conceptual handoff object is approximately: Finding + disposition + provenance + relevance/standing + graph anchor. API/schema design is NOT yet settled.

Unresolved implementation choices

Finding schema
Finding IDs
contribution↔Finding mapping/clustering
confidence representation/scoring
reopening triggers
exact focused→global API/payload shape
UI presentation of Finding dispositions

Focused Investigation Overlay Workspace — Checkpoint (2026-08-26)

Implemented workspace state (settled, post-commit `abeb3fc`)

The focused investigation overlay workspace has been built and committed. The following describe the actual implemented behaviour:

Case overview = orientation / index surface

The case overview is the primary orientation and navigation surface.
It displays Current Understanding, Situation, and Open Questions.
Open Questions serve as top-level investigation entry points.

Investigation opens as an overlay

Selecting an Open Question opens a focused investigation workspace as a large overlay.
The case overview remains visible but dimmed behind the overlay.
Background interaction is locked while investigating.
Page scrolling is locked while investigating.
The workspace itself owns its own scrolling.
Close investigation is persistently available (top-right).

Closing preserves all investigation state — it does not complete the branch.
Reopening restores accumulated investigation context.
Investigation state persists across open/close cycles.

Two-column layout on wide screens

The workspace uses a two-column layout:
- Primary prominence: active investigation (current question, response, "What this tells us", Still unclear)
- Supporting context: Previous Learning beneath the primary column
Narrow screens collapse to a single column naturally — responsive presentation does not alter reasoning semantics.

"Back to open questions" and "Done for now" appear only in appropriate states as workspace-level navigation.

Attention model (implemented)

The UI should progressively reflect the reasoning state.

The thing currently being investigated receives prominence.

Accumulated learning remains available as context without competing equally for attention.

The interface should not display every reasoning artifact with equal prominence simultaneously.

LLM call boundary

No additional LLM calls were introduced by the workspace itself.
All reasoning output volume from a focused turn (findings, uncertainties, assumptions, relationships, follow-ups) remains within the existing deconstruction call.

Next direction: Findings validation surface

"Do not implement it." Record this as the next product/reasoning interaction to explore:

"What this tells us" is the user-facing validation surface for Findings.

Default acceptance / exception pattern

A displayed Finding under "What this tells us" is accepted by default — no explicit Agree action is required.
The user intervenes only on exception.
Two exception actions:
- "Not quite" → correct/reword the Finding; original engine wording must be preserved in provenance (never silently overwritten).
- "Not relevant" → removes the Finding from active relevance while preserving its provenance.

Unresolved items to carry forward

The following remain unresolved — do not attempt to answer them in the next iteration:

Exact "Not quite" editing interaction — how correction is triggered, presented, and confirmed
Exact Finding persistence/update mechanics — runtime storage schema, identity model
How corrected wording relates to original Finding identity — same Finding revised vs. new Finding with lineage
When Findings become eligible for later global synthesis — eligibility criteria are undefined
Exact "learned enough" condition — no fixed threshold; synthesis remains a deliberate workshop-style checkpoint, not an automatic trigger

Global synthesis constraint (preserved from prior handoff)

Cumulative Findings should NOT automatically be injected into every graph-update LLM call.

A later global synthesis should occur at a natural workshop checkpoint, likely when useful questioning is exhausted or the user explicitly indicates they have enough information.

This remains an intentional constraint — not an oversight. The reasoning pipeline and the validation/synthesis surfaces serve different purposes and must remain architecturally separable.

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 exception disposition (Not quite or Not relevant). A Finding with no explicit disposition is accepted by default (not treated as agreed/confirmed/user-validated in the strong sense — it remains provisional to challenge but is accepted as working interpretation for the current investigation). 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 — only needed for exception actions (`Not quite`, `Not relevant`); absence means accepted-by-default (still revisable)
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 — accepted-by-default; eligible for case/update evaluation as working interpretation (still revisable; not treated as absolute confirmation)
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 — accepted-by-default (working interpretation, still revisable); not absolute confirmation
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)

Object crossing: A current Finding plus standing/relevance/disposition state and provenance.
Provenance: At least one traceable source contribution; originating investigation anchor retained when available. Missing origin does not invalidate the Finding.
Disposition: Only needed for exception actions. Default is accepted-by-default (working interpretation, still revisable — not absolute confirmation). Exception dispositions: Not quite (challenging/corrective) and Not relevant (relevance discount, retained in provenance). All other findings are accepted by default under "What this tells us."
Standing/relevance: Semantic advisory state only; no weighting/scoring model assumed. case/update may independently set or override.
Mapping: Originating target does not dictate final graph mapping; case/update determines graph impact/mapping including new propositions, multiple nodes, or unresolved mapping.
Authority: Case/update solely owns graph mutation, Current Understanding and frontier selection. Finding identity (merge/split/identity) remains unresolved at the Finding layer.
Validation: Reject malformed/untraceable evidence; contradiction or lack of explicit disposition alone is not rejection.
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

Minimum v1 Finding Handoff Implementation Slice — August 2026

Design decisions (design-only, not implementation)

1. Runtime owner

ScenarioForm state beside focusedContributions. focusedInvestigations lives in the SituationGraph as authoritative graph state. Findings are a separate reasoning-layer concept that the user reasons about. The ScenarioForm component already maintains focusedContributions (line 256) as parallel client-side state beside graph state. v1 Findings live alongside this: a transient, client-side reasoning array created from contributions and passed through to case/update when an update is submitted.

2. Creation seam

After focused deconstruction — the same path that creates and stores a Contribution. The existing appendFocusedContribution callback (scenario-form.jsx line 258) receives the model's deconstruction result. A new Finding is created from the same deconstruction output in the same turn, before or alongside contribution storage. The seam: after the focused-deconstruct LLM returns its result, each extracted observation becomes one provisional Finding with status provisional.

3. v1 formation rule

ONE-CONTRIBUTION-MULTIPLE-OBSERVATION-FINDINGS. Each extracted observation in a focused deconstruction produces one provisional Finding whose proposition is derived from that observation alone. This is a v1 simplification only — it does not constrain the domain model. Long-term Contribution↔Finding cardinality remains unresolved and may be many-to-many. No clustering, merging, embedding, semantic merge, or additional LLM call in v1. Each observation yields one deterministic Finding.

4. Handoff trigger

On completed contribution, provisional unless explicitly disposed. A Finding is created immediately when a focused deconstruction completes and contributes its result. It enters case/update alongside the normal update payload. Exception disposition (Not quite or Not relevant) is optional — absence means accepted-by-default (working interpretation, still revisable) which is globally eligible for evaluation.

5. Best case/update seam

ScenarioForm → /api/cases/update → orchestrator → applyValidatedProposal. The smallest insertion point is: ScenarioForm sends findings[] as an optional field in the Update request body. The orchestrator passes these into the evaluation phase of the update cycle before or alongside proposal application, but never as a direct graph mutation trigger. The Finding enters case/update as advisory input; case/update decides its relevance during Current Understanding reconstruction independently.

6. Request evolution

Extend existing /api/cases/update with optional findings. Add an optional findings array to updateCaseRequestSchema. No separate endpoint. Each Finding in the array carries: { id, proposition, status, disposition, contributingContributionIds, originatingTargetNodeId }. The schema addition is a zod extension with findings: z.array(findingSchema).optional() — backward-compatible.

7. Required v1 validation

Three separate concerns:

STRUCTURAL VALIDATION

Non-empty proposition (string with trimmed length > 0)
At least one valid contributingContributionId reference
If disposition present, must be one of: agreed, challenged, not relevant
No direct graph-mutation fields (the Finding carries advisory data only)

PROVENANCE VALIDATION

Referenced contribution exists
Selected source observation exists within referenced contribution

SEMANTIC AUTHORITY

Source observation remains evidence/provenance
case/update does not treat proposition as truth merely because validation passed

Failing any structural or provenance check → reject that single Finding from active consideration (retain in provenance). No additional LLM validation call in v1. Semantic authority is a boundary contract, not an automated check.

8. Minimum global effect

OPTION-1. Finding reaches case/update → validated → can influence Current Understanding reconstruction only → graph structure unchanged.

This is the smallest, most conservative slice: Findings affect only what gets reported back to the user as "current understanding." They do not attach evidence to existing graph nodes or mutate any graph topology in v1. Graph mutations remain exclusively controlled by applyValidatedProposal from the LLM proposal path.

9. Evaluation response

RETURN-EVALUATION-V1. v1 includes minimal per-Finding evaluation status in the orchestrator's internal response: considered, used, not_used, or rejected. This is developer/provenance-oriented only — not a final API schema. It supports tests, manual debugging, and future UI decisions by proving case/update actually evaluated each Finding rather than silently accepting or ignoring it.

10. Graph-authority invariant

Exact invariant:

"Findings are advisory inputs to case/update. In v1, case/update may use a validated Finding only when reconstructing Current Understanding. The SituationGraph, activeUnknownNodeId and selectedQuestion must remain byte-for-byte unchanged as a consequence of Finding handoff."

Proof: The v1 code path ensures (a) Findings are typed as a separate schema from graph-update proposals, (b) Finding evaluation runs in a read-only phase of case/update that has no side effects on the graph object, and (c) applyValidatedProposal is never called with Finding-derived mutation instructions.

11. File scope

File	Classification
components/scenario-form.jsx	LIKELY-CHANGE
components/reasoning-workspace.jsx	MAY-CHANGE
/api/cases/update route	MAY-CHANGE
case/update orchestrator (orchestrator.js)	LIKELY-CHANGE
lib/graph/apply-proposal.js	DO-NOT-CHANGE
lib/graph/utils.js	DO-NOT-CHANGE
lib/graph/schema.js	LIKELY-CHANGE
new Finding helper/module	MAY-CHANGE (or inline in orchestrator for v1)
tests	LIKELY-CHANGE

12. Four deterministic v1 scenarios

provisional Finding (valid, no explicit disposition)

Boundary result: passes structural and provenance validation; status = provisional
Eligibility: eligible as unconfirmed evidence/context for Current Understanding evaluation
Must remain represented as provisional/unconfirmed
Graph mutation: none

agreed Finding (valid, explicit user support is available to case/update)

Boundary result: passes structural and provenance validation; disposition = agreed
Eligibility: eligible with explicit user support
May be represented differently in Current Understanding reconstruction if semantically appropriate — no numerical/ordinal weighting exists
Graph mutation: none

not-relevant Finding (valid provenance, disposition = not relevant)

Boundary result: passes structural and provenance validation; disposition = not relevant
Eligibility: eligible with qualification — must NOT affect Current Understanding for the current investigation context
Retained but excluded from current active relevance
Graph mutation: none

malformed/untraceable Finding (empty proposition or missing contribution reference)

Boundary result: fails handoff validation
Effect: does not affect Current Understanding; no graph effect
Retained in provenance with warning

13. Implementation order (max 7 steps)

Deterministic Finding representation/formation helper — small module that creates one provisional Finding per extracted observation, no LLM call
Deterministic validation — structural + provenance checks as described in section 8
ScenarioForm ownership/storage — alongside focusedContributions, create and store provisional Findings after deconstruction; include in update payload
Optional findings handoff through existing /api/cases/update — extend schema with optional findings[]; orchestrator passes as advisory input
Current Understanding-only consumption — validated Findings influence reconstruction only; SituationGraph, activeUnknownNodeId, selectedQuestion byte-for-byte unchanged
Invariant tests proving graph/frontier/question unchanged across all four deterministic scenarios (provisional accepted, agreed accepted, not-relevant excluded, malformed rejected)
Manual walkthrough of the complete handoff path

Decision gate

MINIMUM-V1-FINDING-HANDOFF-DESIGN-READY

Finding → Current Understanding Integration Seam — August 2026

Summary producer

Authoritative location: lib/graph/builder.js line 285, exported function describeGraph(graph)
Called by: lib/graph/apply-proposal.js lines 2981, 3079, 4636 — all inside applyValidatedProposal()
Classification: Deterministic helper. Produces structural summary (node counts by kind, edge count, unresolved unknown count). Returns string of format: Nodes: X kindA, Y kindB | Edges: N total | Unknowns: M unresolved
NOT LLM-produced. No narrative/meaningful Current Understanding text is generated during the case/update flow.

Existing-call / no-extra-call result

YES — the normal /api/cases/update path already makes exactly one provider call (provider.generateReconstruction(prompt, modelName)) at lib/graph/orchestrator.js line 647. This call can accept additional context without increasing attempt count if findings are added to the existing prompt.

Safe seam

A — Pass validated Findings into the existing case/update LLM prompt, only in a clearly bounded "advisory evidence for summary" section, with deterministic guards.

The smallest insertion point: extend buildGraphUpdatePrompt() at lib/graph/prompt-builder.js line 28 to accept an optional findings parameter. Append findings as a new prompt section between the existing "User Answer" block and the "Allowed Node Kinds" header. This does not change any existing field in the required JSON contract — it only adds advisory context the model can reference when reasoning about graph updates and producing its proposal.

If the LLM output schema is extended to include an optional currentUnderstanding text field (in addition to the existing graph-update JSON fields), the validated Findings would be consumed by this EXISTING call with zero additional provider attempts. If no new output field is added, findings still influence the model's structural reasoning which indirectly supports better Current Understanding reconstruction downstream.

Graph-authority risk

HIGH / COUPLED-BLOCKER. Adding findings to the existing graph-update prompt couples finding evidence to every output field produced by the same model: graph mutations (added/updated nodes, edges), activeUnknownNodeId, selectedQuestion, and all resolution proposals. There is no code-level boundary that prevents the model from reasoning about findings when producing any of these fields. Prompt instructions ("advisory evidence for summary only") are behavioral nudes shared in the same attention context as graph-mutation instructions; they do not provide architectural isolation.

Why CURRENT-UNDERSTANDING-SEAM-READY is incorrect

describeGraph() does NOT produce narrative Current Understanding. It returns deterministic structural metadata only: "Nodes: X kindA, Y kindB | Edges: N total | Unknowns: M unresolved". During Update, the response summary field (orchestrator.js line 869) traces back to this function stored on the graph object. No narrative synthesis of investigation state exists in the current update path.
No separate Current Understanding producer exists during update. During Start, analysis.reconstruction?.summary provides narrative understanding via a provider call. During Update, that narrative channel is absent — only structural counts exist. Adding findings to the graph prompt does not create a narrative producer; it only gives the existing graph-proposal model access to finding context.
Single-call architecture couples all outputs. The model produces both graph-update JSON and (potentially) Current Understanding text in one generation. Whatever context influences one field can influence all fields. There is no mechanism to restrict finding-influenced reasoning to only one output field while protecting the others.

A/B invariant assessment

What must remain identical:

updatedSituationGraph (byte-for-byte node/edge topology)
activeUnknownNodeId
selectedQuestion
All proposal graph-mutation fields (addedNodes, updatedNodes, addedEdges, etc.)
Provider attempt count (must remain exactly 1)

What alone may differ:

Summary / Current Understanding text
Per-Finding evaluation metadata (considered, used, not_used, rejected)
Diagnostics fields tracking which findings were consumed by reasoning

Limitation of A/B equality tests: Demonstrating identical structural outputs across runs does not prove architectural isolation. The model may use finding context during reasoning while producing the same graph output in those specific instances. Output comparison verifies behavioral equivalence, not the absence of semantic influence on the reasoning process.

Decision gate

CURRENT-UNDERSTANDING-COUPLED-BLOCKER

The seam is NOT ready for implementation as described. The current architecture couples all graph-update fields to whatever context appears in the update prompt. Before proceeding:

A separate narrative Current Understanding producer must exist (either a second provider call consuming validated Findings + graph state, or a deterministic summary engine replacing describeGraph() with findings-aware synthesis).
The graph-update prompt must remain free of finding context until isolation is verified at the architectural level — not just via output comparison.

Without this separation, any attempt to add findings to the existing update path risks coupling the full graph reasoning pipeline to finding evidence that has not yet been validated through the authoritative case/update evaluation gate.

v0.48 CLOSURE AND NEXT BOUNDARY HANDOFF (2026-08-28)

PERSISTENCE — COMPLETE

feature/investigation-storage-provider-v0.48 has satisfied its bounded objective: generic investigation storage abstraction, LocalStorageProvider-backed canonical storage, and longitudinal investigation persistence are sufficiently established.

Closed items:

Generic storage contract (loadInvestigation, saveInvestigation, clearInvestigation) — COMPLETE
ScenarioForm canonical hydration/persistence/clear ownership — COMPLETE (only owner; ReasoningWorkspace has no competing path)
Autosave persists: scenario, situationGraph, selectedQuestion, summary/Current Understanding state, focusedContributions, findings, updatedAt — COMPLETE
Legacy ReasoningWorkspace investigation persistence removed — COMPLETE
No competing production investigation persistence path remains — VERIFIED
Cold-return continuity proved via live multi-turn browser close/reopen experiment — VERIFIED
Contribution persistence across reload/cold return proven by latest bounded runtime experiment — VERIFIED (earlier focusedContributions=[] observation not reproduced, treated as technical debt)

FINDING ELIGIBILITY — RESOLVED (NOT REOPENABLE)

Dispositions:

userDisposition === null → accepted-by-default → eligible as working interpretation for current investigation → NOT explicit user endorsement → still revisable. CLOSED.
not_relevant → retained canonically/provenance → NOT eligible to drive current investigation reasoning. CLOSED.

Finding role: Advisory evidence carriers, NOT direct SituationGraph mutation agents. Authority boundary: only case/update owns graph mutation and frontier selection. CLOSED.

NEXT BOUNDARY — ISOLATED FINDING-INFORMED CURRENT UNDERSTANDING

The remaining boundaries are NOT persistence issues. They belong to the next feature:

Focused → global ownership/integration (how accumulated canonical Findings participate in global reasoning)
Current Understanding incorporating focused learning (narrative synthesis from eligible Findings + authoritative graph state)
CURRENT-UNDERSTANDING-COUPLED-BLOCKER (adding Findings to buildGraphUpdatePrompt() exposes them to authoritative outputs — graph mutations, activeUnknownNodeId, selectedQuestion, resolution proposals — which violates the established authority boundary)

Recommended branch: feature/finding-informed-understanding-v0.49 Branch from: b215846 (current HEAD on feature/investigation-storage-provider-v0.48) Objective: Establish the smallest isolated path by which globally eligible canonical Findings can influence Current Understanding WITHOUT changing authoritative SituationGraph reasoning outputs.

INTENTIONALLY DEFERRED FINDING-SYSTEM QUESTIONS (NOT v0.49)

Richer Finding schema
Final Finding ID system
Contribution ↔ Finding clustering
Semantic Finding deduplication
Finding merge/split ownership
Final Finding → graph mapping mechanism

v0.49 — MULTI-TURN / COLD-RETURN ACTIVITY VISIBILITY REPAIR (2026-08-28)

Checkpointed: Single-turn visibility: passed. Multi-turn identity regression: repaired at 10cbcbd. Cold-return activity visibility: checkpointed subject to the canonical identity rule (c.targetNodeId === nodeId || c.originatingTargetNodeId === nodeId).

This repair does NOT solve restored workspace lifecycle or reopened Finding interaction controls (see RESTORE / PRESENTATION FINDINGS section below).

Root cause: ThreadContributionsBadge, PriorContributionsSummary, and SecondaryPreviousLearning all filtered contributions via c.targetNodeId === nodeId. Multi-turn follow-up Contributions carry a different immediate targetNodeId while the canonical origin remains on Findings (originatingTargetNodeId). When only the follow-up turn survives cold return, the filter finds zero matches.

Repaired identity rule: All contribution filters now match on EITHER c.targetNodeId === nodeId || c.originatingTargetNodeId === nodeId. This captures both direct-target contributions and follow-up contributions whose origin anchors to a different Open Question.

New persisted field on Contribution: originatingTargetNodeId — set from focusedPresentationItemId at deconstruct submit time. It is NOT a new investigation flag; it is provenance that lets existing discovery surfaces recover multi-turn history.

Files changed:

components/reasoning-workspace.jsx — patched 4 filter sites + handleDeconstructSubmit to carry originatingTargetNodeId
tests/open-questions-vs-assumptions.test.jsx — added v0.49 multi-turn regression tests and repaired getThreadContribs helper

No changes to: Finding eligibility, Finding disposition, Current Understanding, Done-for-now promotion, SituationGraph, persistence provider, or graph reasoning.

v0.49.5 — CANONICAL PREVIOUS LEARNING PROPOSITION REPAIR (2026-08-29)

Objective: Ensure Previous Learning surfaces on focused investigation cards resolve canonical historical propositions through the Finding→Contribution identity chain rather than showing stale or missing content.

Resolver semantics implemented in reasoning-workspace.jsx:

Matching canonical Findings for a Contribution	Behaviour
ZERO matching canonical Findings	Fallback to `Contribution.observations`
ONE OR MORE matching canonical Findings	Canonical Findings are authoritative; use `Finding.proposition`
Matching Findings exist but all are `not_relevant`	Render nothing for that Contribution; DO NOT resurrect old observations
Each Contribution's findings filtered by	`Finding.contributionId === Contribution.id` (one-to-one ownership)

Applied to historical-learning surfaces: PriorContributionsSummary, SecondaryPreviousLearning, ThreadContributionsBadge.

Files changed:

components/reasoning-workspace.jsx — canonical proposition resolver in Previous Learning panel
tests/open-questions-vs-assumptions.test.jsx — 78 tests covering legacy fallback, empty fallback, corrected canonical proposition, all-not_relevant suppression, turn ownership, mixed dispositions, null/undefined findings

Deterministic gate: 78 tests passed. Build gate: clean production build.

Live verification (canonical onboarding fixture):

Persisted Finding finding-5rf99h carries corrected proposition "Approximately 62% of users abandoning the verification step report no problem receiving their code. [previous-learning-check]" with contributionId: "contrib-0002"
Workspace opened without crash or ReferenceError
Turn 2 → canonical proposition with [previous-learning-check] marker rendered in Previous Learning "What this tells us"
No stale original wording shown; no duplication of old+corrected text
Correct turn ownership confirmed (Turn 2 = contrib-0002, matching Finding scoped to that contribution)
Zero LLM/API calls during verification
Persistence/schema/reasoning paths unchanged

No changes to: Persistence schema, Finding schema, Contribution schema, SituationGraph reasoning, activity visibility, completed-turn lifecycle, or overlay controls.

RESTORE / PRESENTATION FINDINGS — MANUAL USER-PATH (2026-08-28)

Open restore / focused-workspace presentation issue

The following findings were established by manual user-path testing after the v0.49 multi-turn activity visibility repair at 10cbcbd. They are separate and additional to that repair; the identity fix for INVESTIGING cue on Open Question cards remains valid and unimpaired.

A. Cold return can land on underlying investigation surface rather than focused-overlay

After manually completing focused investigation work, closing the browser, and returning later:

The application can hydrate into the underlying/main investigation surface (case overview + situation + open questions with INVESTIGING cues) rather than automatically reopening the focused-investigation overlay.
The main/restored surface includes: Open Questions (with INVESTIGING cues), Situation, persisted investigation content, and a saved-state message/banner stating that previous investigation state is still saved and can continue or restart.
No focused overlay is automatically reopened.

This indicates there appear to be distinct presentation states:

A. Restored underlying investigation surface (case overview) B. Focused-investigation overlay (opened per Open Question)

The ownership / lifecycle relationship between A and B has NOT yet been traced or resolved.

B. Restored surface + saved-state banner presents semantically odd signal

The main investigation is already visibly restored when the UI simultaneously presents messaging equivalent to:

"Your previous investigation state is still saved. You can continue where you left off or start fresh."

This may indicate a restored/resumed workspace-state distinction that is not currently obvious to the user.

Do not conclude persistence is broken. Persistence remains demonstrated working. This is a presentation / workspace-lifecycle observation.

C. Reopened focused stream loses Finding interaction controls

After returning to the restored investigation and manually reopening the previously investigated focused stream:

Prior Finding proposition(s) are visible under "What this tells us"
The Finding text itself survives
The controls "Not quite" / "Not relevant" are absent

This differs from the live current-turn focused surface where canonical Findings display those controls.

REOPENED CANONICAL FINDING CONTROLS — REPAIRED (v0.49)

Repaired currentFindings derivation in reasoning-workspace.jsx (lines 1382–1420): when correlationId is absent on cold reopen, the repair identifies the persisted Contribution belonging to the currently displayed focused turn/thread and uses Finding.contributionId === Contribution.id to recover the canonical Finding objects. correlationId is not required for cold reopen. Deterministic tests pass (70/70). Live Playwright verification deferred — see next constraint note.

Separation from prior repair

The recent activity-visibility repair at 10cbcbd:

Repaired INVESTIGATING cue identity for direct/originating focused-thread identity via c.targetNodeId === nodeId || c.originatingTargetNodeId === nodeId
Does NOT solve restored workspace lifecycle (section A)
Does NOT solve reopened Finding interaction controls (section C)

These are distinct issues with distinct boundary surfaces.

What remains proved (unchanged from prior handoff)

post-authoritative Current Understanding isolation was proved
Done-for-now promotion was deterministically and live verified
promotion survives reload
no case/update or extra LLM call is required for Done-for-now promotion

The new manual observations are presentation/lifecycle issues downstream of persisted state, not evidence that the promotion seam failed. Do NOT reopen those completed v0.49 findings.

What remains unresolved

Item	Status
Cold-return can land on underlying surface rather than focused overlay	MANUALLY OBSERVED — unproven presentation/lifecycle gap
Saved-state banner + already-restored investigation signal	MANUALLY OBSERVED — semantic oddity of workspace state
Reopened Finding proposition survives	PROVED (text persists)
Reopened Not quite / not relevant controls absent	REPAIRED — Contribution.id → contributionId path verified; correlationId no longer required for cold reopen

NEXT BOUNDARY — REOPENED FOCUSED FINDING PRESENTATION / RESTORE WORKSPACE OWNERSHIP

Do NOT implement this trace now. Record as next bounded investigation.

The immediate next trace should compare:

LIVE CURRENT-TURN FOCUSED RENDERING	versus	COLD-RESTORED / REOPENED FOCUSED RENDERING
canonical Finding objects present	vs	whether same objects survive reopen
Finding.id available	vs	identity continuity
proposition	vs	wording continuity
userDisposition available	vs	disposition survival
onUpdateFindingDisposition	vs	callback availability
onUpdateFindingProposition	vs	rewording availability

The trace must identify the first boundary where any of the fields above stop being available or stop being rendered.

Also trace whether:

the main restored surface (A) and the focused overlay (B) are driven by distinct lifecycle/presentation state, and if so, what governs the transition between them;
the reopened Finding controls gap is a rendering-path difference or a data-model gap.

BRANCH CLEAN STATE

This branch has NO tracked working tree changes at HEAD b215846. Documentation closure recorded in this section only. No production or test modifications required.

Findings Interaction + Attention Model — August 2026

What this tells us = accepted by default

When findings are presented under "What this tells us," the normal default interpretation is:

the Engine currently accepts each finding as its working interpretation for the current investigation

The user does NOT need to explicitly click "Agree" for every finding. Silence or absence of an exception action is interpreted as acceptance-by-default — not as absolute truth, but as a working premise that remains revisable if later evidence or the user challenges it.

No explicit Agree interaction required

The earlier exploration model treated Agree / Not quite / Not relevant as three equally explicit user actions. That phase is superseded by the accepted-by-default direction:

Only two exception actions are needed per finding
Explicit agreement is not a prerequisite for progression
Existing runtime values (including null, agree) may remain temporarily for compatibility, but the product contract does not require an explicit agree interaction

Not quite = user correction / rewording

Not quite means:

the finding is not an accurate enough representation of what the user meant

Expected interaction:

User selects "Not quite" on the specific finding
UI exposes/edits the current finding wording for correction
User corrects or rewords it
The corrected wording becomes the current finding
The original engine wording remains in provenance/history

Exact component design is not yet decided — this describes the semantic contract only.

Not relevant = retained but discounted from current investigation

Not relevant means:

the finding may be true, but should not drive the current investigation

Semantic effect:

Retained in provenance
Discounted from current investigative relevance
Can be reopened later if new evidence makes it material

Do NOT delete a "not relevant" finding.

Actions attach per finding

The exception actions attach to each individual finding bullet, not the whole section:

What this tells us

• Team member handles supplier payments independently
  [Not quite] [Not relevant]

• Exceptions are escalated
  [Not quite] [Not relevant]

• Remaining routine work has not been fully mapped
  [Not quite] [Not relevant]

This is conceptual only — not yet a component design.

Default state terminology

Preferred conceptual states:

accepted-by-default (no action taken — still revisable)
corrected-by-user (via Not quite path)
not-relevant (discounted from current relevance)

Existing implementation values (null, agree, not_quite, not_relevant) may remain temporarily for compatibility. Final runtime enum/state representation is an unresolved implementation detail.

Silence / default ≠ absolute truth

Silence or absence of action does NOT mean the finding is permanently settled:

It remains a working interpretation for the current investigation
It can be challenged or reopened if later evidence contradicts it
It differs from explicit confirmation in strength, not from being revisable

Attention model — prominence follows current activity

The interface should primarily show what the user is working on now. Previous reasoning remains persistent and recoverable, but should recede unless relevant to the current task.

While answering a question:

Prominent: current question, response field
Previous learning: collapsed / secondary

Immediately after deconstruction:

Prominent: "What this tells us" findings with Not quite / Not relevant actions, Still unclear, next useful question
Previous turn detail: available but secondary

When the next question is selected:

Prominent: new current question, response field
Prior findings recede again

When "Not quite" is selected:

Prominent: that one finding with editable corrected wording
Other material recedes

All reasoning should NOT be shown simultaneously. The current UI accumulates too many overlapping sections (Current Understanding, Situation, Open Questions, active focused question, response, What this tells us, Still unclear, Questions this raises, Previous learning, assumptions, relationships, future Findings/dispositions). Showing all at once overloads the user.

Synthesis model — natural workshop checkpoints

Cumulative Finding synthesis should NOT happen:

After every answer
After a fixed number of findings
Automatically whenever a threshold is crossed

Preferred product model: investigate → accumulate findings → reach natural workshop checkpoint → offer synthesis → user explicitly chooses whether to run it.

Natural workshop checkpoints include:

Current branch has run out of materially useful questions
Next questions are becoming narrow / repetitive
The user says they have enough information
The user explicitly chooses to step back and review

Useful facilitator wording:

"We've covered the main useful questions in this part of the investigation. It may be worth stepping back now and seeing what the evidence adds up to."

For v1: synthesis is user-triggered (explicit / user-led). Automatic detection of workshop checkpoints is a later optimisation. No fixed finding-count threshold is defined at this time.

Synthesis sequence (future intent)

answer
→ What this tells us findings
→ user only intervenes on exceptions: Not quite, Not relevant

→ findings accumulate

→ natural workshop checkpoint reached

→ user chooses to analyse what has been learned

→ cumulative synthesis uses: current findings, user corrections, relevance decisions, provenance, relevant graph context

→ refreshed Current Understanding

This synthesis is separate from routine focused deconstruction. The synthesis API is not designed in this contract.

Findings remain reopenable

Not relevant today does NOT mean irrelevant forever — later evidence may make an old finding material again
Accepted-by-default does NOT mean permanently settled — a finding may later be challenged or reopened
Both states are revisable with explicit status indicating why they were reopened

Progressive Investigation UI + Notebook Workspace Model — August 2026

Core principle: investigation depth shapes the interface

The interface should progressively reveal the structure of the investigation as that structure emerges, while keeping the user's current reasoning task visually dominant.

The UI should NOT be a fixed shell that shows every available reasoning artefact at once. As the investigation evolves:

simple case                      → simple overview
focused branch                  → focused investigation workspace
findings accumulate              → validation/correction becomes available
branch matures                  → synthesis/review becomes appropriate
later evidence reopens old       → previously secondary material becomes prominent again

The relationship is reciprocal: reasoning state shapes the UI, and UI structure guides the user toward the appropriate reasoning activity.

Case overview = orientation / index surface

The main screen acts as a notebook index or case summary view.

Prominent elements:

Current Understanding
Situation
Open Questions

This screen is for orientation, choosing where to investigate, and seeing the main unresolved areas. It should NOT expand into an ever-growing full reasoning transcript.

Open Questions remain the top-level navigation entry point into deeper investigation.

Focused investigation opens as a workspace overlay

Selecting a top-level Open Question opens a focused investigation workspace as a large overlay. The underlying case overview remains visible but dimmed/greyed; background content becomes inactive.

The overlay should feel like opening a page in a notebook rather than navigating to a completely separate application page. It should occupy enough of the viewport to function as a genuine reasoning workspace, not a small modal dialog.

This supersedes earlier directions that treated inline accordion expansion as the primary long-term pattern. The current product direction is overlay-first for focused investigation.

Notebook interaction model (conceptual, not decorative)

CASE OVERVIEW        = notebook index / case summary
OPEN QUESTION        = investigation page/topic
FOCUSED OVERLAY      = opened investigation page
FINDINGS             = notes learned on that page
PREVIOUS LEARNING    = earlier notes/history available beneath current work
SYNTHESIS            = step back and review what the notebook now adds up to

Do NOT prescribe decorative notebook styling, paper textures, or tabs. The analogy is about information hierarchy and navigation.

The workspace overlay has a prominent, persistent close control in the top-right (e.g., × Close investigation).

Closing means:

Leave this focused workspace
Return to the Open Questions overview
Preserve all investigation state

Closing does NOT mean:

Finish the branch
Discard work
Mark resolved
Run synthesis
Restart investigation

Attention hierarchy inside the workspace

Content prominence follows current activity.

While answering a question:

Primary: current question, response field, submit action
Secondary (collapsed): previous learning, older findings, assumptions, relationships, other branch history

Immediately after deconstruction:

Primary: "What this tells us", Still unclear, next useful question
Each finding under "What this tells us" exposes exception actions: Not quite, Not relevant

When "Not quite" is selected:

Primary: the affected finding with editable/rewordable correction
Other workspace content recedes visually; original Engine wording remains in provenance

When next question is selected:

Primary focus returns to new current question and response
Prior findings remain persistent but recede

Finding interaction model

"What this tells us" presents findings accepted by default as the Engine's current working interpretation. Accepted by default does NOT mean absolute truth — it means a working premise for the current investigation, still revisable if later evidence or the user challenges it.

The user intervenes only by exception:

Not quite → correct/reword the finding; original wording retained in provenance
Not relevant → retain the finding but discount it from the current investigation

Actions apply per finding, not to the entire section. No explicit Agree action is required.

Progressive disclosure

The UI will increasingly hold: questions, answers, findings, corrections, relevance decisions, previous learning, uncertainties, assumptions, relationships, provenance, and future synthesis. Therefore:

Persistent does not mean permanently visible.

Older material should remain recoverable without competing with the current task. Not all reasoning artefacts need to remain expanded simultaneously.

Natural synthesis checkpoint

Cumulative synthesis is separate from routine investigation. Do NOT trigger synthesis after every turn, after a fixed number of findings, or automatically just because data volume grows.

Preferred flow:

investigate branch → accumulate findings → reach natural workshop checkpoint → offer review → user explicitly chooses synthesis

Natural checkpoints include:

Useful questions are running out
Remaining questions are becoming narrow/repetitive
The user says they have enough information
The user chooses to step back and review

Facilitator-style concept (wording not final):

"We've covered the main useful questions in this part of the investigation. It may be worth stepping back now and seeing what the evidence adds up to."

For v1: synthesis is user-triggered (explicit / user-led). Automatic detection of workshop checkpoints is a later optimisation.

UI attention modes (conceptual)

1. ORIENT     — case overview, orientation
2. INVESTIGATE — focused workspace overlay
3. VALIDATE   — review/correct findings from the current answer
4. SYNTHESISE  — explicit cumulative review at a natural checkpoint

These are conceptual attention modes, not implemented routing/state machines. Separate pages are not assumed to be required.

Explicitly unresolved

Overlay dimensions / layout
Animation
Mobile behaviour
Exact close-control styling
Exact finding-control styling
Previous-learning collapse design
Synthesis visual design
Automatic checkpoint detection
Final facilitator wording

INVESTIGATION-STORAGE PROVIDER — v0.48 ARCHITECTURE CHECKPOINT (2026-08-27)

Architectural Direction: Build → Break → Learn

v0.48 emerged from the build → break → learn process driven by a practical operational problem:

Repeated Playwright and live investigations were continually starting from fresh scenarios because investigation state was not durable across page reloads and browser close/reopen cycles. This meant:

Wasted LLM calls — every session restart consumed a full Start call.
Non-reproducible results — generated questions and findings differed every run, making wording-dependent Playwright assertions brittle.
Broken product exercise — the Confidence Engine could not be exercised as a real longitudinal investigation. It was impossible to leave an investigation, return later, and continue accumulated reasoning.
Exposed fundamental need — genuine leave-and-return continuity is a core product requirement, not a nice-to-have.

The resulting architectural direction was deliberately chosen:

canonical application state (ScenarioForm)
  → generic storage abstraction (investigation-storage API)
  → provider implementation (LocalStorageProvider)

rather than coupling ScenarioForm directly to localStorage. This design allows the current LocalStorageProvider to be replaced or extended later with an API/database-backed provider without changing investigation ownership or persistence responsibility.

Current Production Architecture at This Checkpoint

Canonical state owner: ScenarioForm

Owns canonical investigation state as source of truth.
Hydrates from storage via loadInvestigation().
Persists via canonical autosave through saveInvestigation() plus currently retained explicit start/update saves.
Clears via clearInvestigation().

Storage provider abstraction: investigation-storage API

Contract: loadInvestigation(), saveInvestigation(), clearInvestigation().
Current provider: LocalStorageProvider.
Schema version: 1.
Canonical key: confidence-engine-investigation.
Legacy fallback: confidence-engine-session (sessionStorage).

ReasoningWorkspace: No direct investigation persistence responsibility. It was the previous owner; that has been intentionally removed.

Implementation Checkpoints Completed at HEAD `d55f179`

A. Generic Storage Provider Introduced

Contract methods:

loadInvestigation() — returns persisted snapshot or null.
saveInvestigation(snapshot) — writes canonical snapshot to storage.
clearInvestigation() — removes both canonical and legacy keys.

Current provider: localStorage (implements the generic contract).

B. ScenarioForm Migrated to Generic Storage API

ScenarioForm no longer knows investigation storage keys or storage mechanics. All persistence interaction flows through the storage abstraction layer.

C. Canonical Autosave in ScenarioForm

Autosave follows canonical state changes once result?.situationGraph exists. The persisted snapshot includes the canonical investigation fields currently used by the implementation:

scenario
situationGraph
selectedQuestion
summary / current understanding
focusedContributions
findings
updatedAt

No additional fields are assumed. This list reflects actual autosave content, not aspirational schema.

D. Intentional Clear Removes Both Keys

clearInvestigation() removes both:

canonical localStorage key (confidence-engine-investigation)
legacy sessionStorage key (confidence-engine-session)

This prevents stale legacy state from being resurrected by migration fallback on subsequent page loads.

E. Legacy ReasoningWorkspace Investigation Persistence Removed

At current HEAD (d55f179), ReasoningWorkspace has no independent investigation persistence responsibility. There is ONE investigation persistence ownership path:

ScenarioForm → investigation-storage abstraction → LocalStorageProvider

The unrelated ce-facilitator-dismissed UI preference remains outside this architecture and should not be conflated with investigation persistence.

First Live Continuity Proof (Prior Experiment)

An earlier live Playwright experiment proved the basic leave-return-continue journey:

Existing investigation → reload → canonical hydration
Continue same investigation → normal focused LLM turn
Accumulate new Contribution + Findings → autosave
Reload again → recovered expanded investigation

Observed:

Same scenario recovered.
SituationGraph recovered.
Current Understanding recovered.
Unresolved/open-question frontier recovered.
Existing focused Contribution recovered, correlation identity intact.
New focused Contribution produced successfully.
Three canonical Findings produced.
Second reload recovered the expanded state.
Finding identity/provenance survived across reloads.

This established that the basic leave → return → continue → accumulate → return journey worked under page reload. This is a proven baseline, not an overstatement of every persistence path.

Multi-Turn Cold-Return Experiment (Most Recent Evidence)

The SAME existing investigation was reused throughout this experiment. No fresh scenario was created. Two additional real focused turns were completed between browser close/reopen cycles. There were three genuine browser close/reopen continuity checks across the full experiment — Playwright fully closed and reopened the browser rather than merely performing page.reload().

Observed durable behaviour across cold browser return:

Same scenario recovered.
Situation graph recovered.
Current Understanding recovered.
Canonical Findings recovered.
Investigation did NOT return to scenario-entry/start state.
Additional Findings accumulated (not replaced) previous Findings.
Finding IDs/provenance remained stable.
localStorage successfully supported cold browser return in this environment.

Finding accumulation observed during experiment:

3 Findings → 7 Findings → 11 Findings

These counts are evidence from one particular live investigation, not permanent product expectations.

CONTRADICTORY / UNREPRODUCED: Earlier `focusedContributions=[]` Observation

During an earlier multi-turn cold-return experiment, canonical localStorage was observed with:

focusedContributions: []

while canonical Findings referenced Contribution IDs including:

contrib-0002
contrib-0003
contrib-0004

Current status: THIS OBSERVATION WAS NOT REPRODUCED BY LATER EVIDENCE.

A subsequent bounded runtime experiment (documented below) ran the identical investigation persistence path and did NOT reproduce focusedContributions=[]. The earlier observation is now contradictory evidence, not an active primary defect. Its cause remains UNKNOWN — it may have been conditional to the earlier runtime state, an inspection/timing issue, or another path not currently identified.

Important discipline: Do NOT convert this observation into a new speculative defect (cold-hydration, schema migration, provider stripping, cold-start-only). The reproducing experiment began with four existing Contributions already recovered from canonical storage — materially weakening those hypotheses. Until the failure reproduces again under controlled conditions, it should NOT drive implementation work.

PROVEN: Stale Intermediate Explicit Save in `handleUpdate`

Source inspection proved a real but narrower issue:

During handleUpdate, an explicit saveInvestigation() can use the existing render-closure value of focusedContributions before the newly appended Contribution has committed.

STALE INTERMEDIATE EXPLICIT SAVE = PROVED.

However, focusedContributions is also a dependency of the canonical ScenarioForm autosave. The source path predicts that the later autosave should repair the stale intermediate write — and the latest bounded runtime experiment confirmed this prediction.

LATEST BOUNDED RUNTIME EXPERIMENT — Contribution Persistence Proves Working

The same existing investigation was reused throughout. No fresh scenario was created. One natural focused turn was completed between cold-return checks.

Before turn:

focusedContributions = 4 (IDs: contrib-0001, contrib-0002, contrib-0003, contrib-0004)
findings = 11

After the new turn:

New Contribution: contrib-0005
New Findings: 3

Canonical storage observations across timed settling checkpoints:

Time	focusedContributions	findings
T0	5	14
T+500ms	5	14
T+2s	5	14
T+5s	5	14
T+10s	5	14

After page reload:

focusedContributions = 5
findings = 14

Investigation recovered normally.

Evidence proves:

A newly completed Contribution reaches canonical persistence.
Canonical autosave persists it (reairs the stale intermediate explicit save).
It remains stable through timed settling.
Reload/hydration restores it.
The known stale explicit save does NOT explain the final durable state in this normal flow.

No production fix is currently justified for Contribution persistence. Do NOT pursue speculative cold-hydration/schema/provider fixes unless the focusedContributions=[] failure reproduces again.

Previous Learning / History UI Observation (Evidence — Not Next Fix)

During the multi-turn experiment, incomplete historical presentation was also observed:

Current active focused turn remained visually dominant.
Previous Learning/history presentation was incomplete; only limited prior Contribution/history material appeared.
Prior/historical Findings did not expose the same "Not quite" / "Not relevant" controls as current-turn canonical Findings.
Current-turn Findings do expose those controls.

IMPORTANT: Do NOT classify this yet as an independent UI defect requiring repair. The missing focusedContributions[] from persistence may be responsible for some or all of the incomplete Previous Learning presentation. Do not change Previous Learning rendering, add historical Finding controls, or redesign the right-hand/multi-turn UI until the Contribution persistence discrepancy has been traced. The UI behaviour is currently evidence, not the next implementation target.

Secondary Observations (Keep as Context — Not Immediate Tasks)

Active/highlighted question presentation may not restore identically after reload/cold return even though frontier data survives.
Unsent textarea/draft persistence has NOT been established as required canonical state.
Storage quota behaviour has not been tested.
Very long investigations have not been tested.
Multi-device/server persistence is not part of the current localStorage provider scope.

NEXT BOUNDARY: Contribution Persistence Status Resolved

Contribution persistence no longer qualifies as the active primary defect. The latest bounded runtime experiment proved it works correctly in the observed normal flow (autosave repairs stale intermediate explicit saves; Contributions survive reload and settle stable).

Treat the earlier focusedContributions=[] observation as technical debt requiring reproduction before implementation work. It is a known unexplained data point, not a justified engineering task.

Next Genuine Boundary (Post-Persistence Resolution)

With Contribution persistence demonstrated working, the remaining unresolved boundaries from the handoff are:

Follow-up selected-question duplication (OPEN UI ISSUE) — proposed follow-up appears simultaneously as ACTIVE QUESTION and STILL-AVAILABLE FOLLOW-UP; proposal state vs active-question state disconnect
Focused → global ownership/integration (STILL OPEN) — how accumulated focused Findings map into the global SituationGraph reasoning layer
Current Understanding incorporating focused learning (STILL OPEN) — narrative understanding should be reconstructed from globally eligible Findings + graph state, not directly from latest focused result
Reopened focused Finding presentation / restore workspace ownership (NEW — MANUAL OBSERVATION) — cold return can land on underlying surface; reopened Finding controls absent

Selected next boundary: Focused → global Finding integration / Previous Learning presentation.

PHASE 6 — UNCLEAR + INVESTIGATING CUE ON OPEN QUESTION CARDS

What was done

Added an amber INVESTIGATING cue to the ThreadContributionsBadge component (line ~583-590 of reasoning-workspace.jsx). The cue renders above the "📝 N learned contribution" detail element whenever the node has one or more matching contributions identified by c.targetNodeId === nodeId.

The cue is also visible on Done-for-now cards (same ThreadContributionsBadge component).

UNCLEAR (epistemic state tag) and INVESTIGATING (activity indicator) are independent — both render on the same card simultaneously. One does not suppress or replace the other.

Deterministic tests added (11 new)

File: tests/open-questions-vs-assumptions.test.jsx — describe block "Focused investigation history cue"

Test	What it verifies
investigated question matches contributions by targetNodeId	identity rule correctness
uninvestigated question gets zero threadContribs	no false-positive cue
unrelated contributions do not contaminate another node	isolation
1+ contributions → cue shows	visibility logic
UNCLEAR and INVESTIGATING coexist on same node	epistemic vs activity independence
Done-for-now retains cue when contributions exist	persistent indicator state
identity rule distinguishes contributed from uninvestigated	discrimination test
multiple contributions on same node still show single cue	idempotent cue, not count-dependent
null/undefined contributions → no cue	guard against falsy
empty array → no cue	boundary value
mismatched targetNodeId → no match	selector correctness

All 57 tests pass.

Live Playwright verification (2026-08-28)

Canonical scenario: e-commerce checkout abandonment, targetNode = n58lwnx. State: 1 contribution targeting n58lwnx, 3 findings.

Observed on first Open Question card ("Relative contribution..."):

INVESTIGATING (amber text) visible above the card content
📝 1 learned contribution badge visible below INVESTIGATING
Both UNCLEAR and INVESTIGATING present simultaneously — coexist, no suppression

Observed on other two Open Question cards:

No INVESTIGATING cue — correct (zero matching contributions by targetNodeId)

What is OUT OF SCOPE for this phase

The cue does NOT render in the initial reflection surface (plain buttons). It only renders inside OpenQuestionsPanel → ThreadContributionsBadge. This is by design; the panel appears during focused workspace operation, not the initial scenario entry.
No CSS animation, transition, or expansion behavior — just a static indicator.
Does NOT affect which cards are clickable/investigable (UNCLEAR handles that).

Remaining open boundaries

Follow-up selected-question duplication (OPEN UI ISSUE) — proposed follow-up appears simultaneously as ACTIVE QUESTION and STILL-AVAILABLE FOLLOW-UP; proposal state vs active-question state disconnect
Focused → global ownership/integration (STILL OPEN) — how accumulated focused Findings map into the global SituationGraph reasoning layer
Current Understanding incorporating focused learning (STILL OPEN) — narrative understanding should be reconstructed from globally eligible Findings + graph state, not directly from latest focused result
Reopened focused Finding presentation / restore workspace ownership (NEW — MANUAL OBSERVATION) — cold return can land on underlying surface; reopened Finding controls absent

Selected next boundary: Focused → global Finding integration / Previous Learning presentation.

Why this is now the strongest next boundary:

The Contribution persistence blocker that prevented assessing previous-learning completeness has been removed. If Contributions persist correctly to canonical storage and survive reload, then the Previous Learning panel should be able to render them without a persistence defect obscuring the UI question.
This is a product-semantic/user-facing progression (not internal cleanup). It directly tests whether the findings domain model established in the handoff can be exercised end-to-end: accumulated focused evidence → visible to user as usable context.
The previous-learning presentation observation was recorded specifically as "evidence, not the next implementation target" because persistence looked suspect. With that suspicion now resolved, the UI question becomes assessable on its own merits.

What remains explicitly OUT OF SCOPE for this next boundary:

Revisiting Contribution persistence (it is proven working)
The stale explicit save cleanup — a known technical debt item, but not a demonstrated user-visible failure in current flow
Follow-up selected-question duplication (separate UI issue; orthogonal to integration semantics)
Current Understanding narrative reconstruction (lower priority after integration is established)
Any speculative cold-hydration/schema/provider fixes

BUILD → BREAK → LEARN

Do not invent architecture ahead of evidence. Every architectural direction should emerge from live behaviour, not from design speculation. Use small bounded increments. Trace before changing unclear ownership paths. Do not broaden scope — keep focused on what the current evidence demands.

PREFER LIVE BEHAVIOUR OVER DICTIONARY ASSUMPTIONS

Prefer live semantic behaviour over dictionary/wording-dependent assumptions. Natural product LLM calls are allowed when required by a genuine live experiment. Do not make extra LLM calls merely to manufacture predictable test fixtures.

PLAYWRIGHT / WORDING DISCIPLINE

Do not make Playwright assertions depend on exact LLM wording. Use Playwright MCP for live UI verification when visual/runtime behaviour is the uncertainty. Use focused Vitest tests for bounded code behaviour. Do not automatically run the full Vitest suite — only targeted tests relevant to the current trace or fix.

GIT WORKFLOW POLICY

Keep git branches/checkpoints bounded and working tree clean. Do not modify production code during trace-only experiments. Commit with clear, scoped messages when work is validated. Prefer small atomic commits over broad sweeping changes. If the current handoff says "do not touch X" — honour that until the boundary is explicitly changed by review.

SCOPE CONTROL

Do not allow automated tooling (Claude/Codex) to broaden scope beyond what the current task and evidence demand. If a discovered issue is related but out of scope, record it as an observation and continue on the primary trace/fixed-path task.

Tooling Context

ChatGPT Role

Use ChatGPT for broad architectural reasoning, contract documentation, and semantic boundary discussions. It can help explore design-space before committing to implementation.

Claude / Local-Network-LLM Prompting Constraints

Claude with local-network-LLM access has specific prompting constraints — it may produce variable outputs for identical prompts, so Playwright assertions must not depend on exact wording. When using Claude for live experiments, accept the natural LLM output and trace behaviour rather than expecting deterministic text matches.

Codex Usage

Codex can be used for focused code changes within established scope boundaries. Always verify that produced changes match the documented contract before accepting them. Codex should not modify production ownership paths (e.g., persistence ownership) without explicit direction in this handoff.

Playwright MCP

Use for live UI/runtime verification when the uncertainty is visual, behavioural, or timing-related. The multi-turn cold-return experiment demonstrated that full browser close/reopen via Playwright provides higher-fidelity evidence than page-level reload alone. Use it for:

Cold-return continuity checks (close + reopen cycle).
Visual state verification of persisted vs recovered state.
Finding/contribution accumulation tracking across turns.

Confidence Engine Experiment Methodology / Skill

The experiment methodology established at the Return-to-Origin phase remains the durable methodological anchor: evaluate all future work against the 12 axioms in docs/current-working-principles.md. Before continuing any development, load:

docs/current-working-principles.md §0 (Axiomatic Principles A1–A12)
docs/Confidence_Engine_Return_to_Origin_Methodology_Context_2026-08-18.md

Git Ownership Policies

Branch feature/investigation-storage-provider-v0.48 owns the investigation-storage provider work. Do not merge or rebase from main without explicit instruction. The branch HEAD (d55f179) represents the canonical checkpoint for this architecture — legacy ReasoningWorkspace persistence removed, ScenarioForm canonical ownership established.

Repository Access Limitations

This is a live repository with active investigation work. Only modify files explicitly documented in the current handoff. The working tree should remain clean except for:

docs/current-handoff.md (this document).
Untracked screenshot/Playwright artifacts (already ignored per repo policy).

Context Documents

Refer to existing context documents before making architectural decisions:

docs/current-working-principles.md — axiomatic principles anchor.
docs/Confidence_Engine_Return_to_Origin_Methodology_Context_2026-08-18.md — RTO methodology.
docs/methodology-checkpoint-return-to-origin.md — repository-facing checkpoint summary.

Canonical Playwright Investigation (v0.49 live run 2026-08-28)

Scenario:

E-commerce checkout abandonment

Situation text: "Our e-commerce checkout page has a high abandonment rate of 72%. Users report confusion about shipping costs appearing only at the final step."

Mobile defects: overlapping buttons and tiny text fields.

Purpose:

Longitudinal live UI verification for current Confidence Engine increments — specifically focused → global Finding handoff and Done-for-now promotion behavior.

Identity:

E-commerce checkout abandonment scenario (72% rate + late shipping disclosure + mobile UX defects). Distinguished from the product-launch enterprise-customer scenario used in v0.48 experiments.

Canonical focused thread:

"Relative contribution of delayed shipping cost disclosure versus mobile UI defects to the overall abandonment rate, as these are presented as distinct dimensions affecting user behavior" Target node: n58lwnx

Current minimum live state (post-run):

focusedContributions: 1
findings: 3 (all originatingTargetNodeId = n58lwnx, userDisposition = null)
promoted Current Understanding: YES (includes Evidence citation from eligible Findings)
Done-for-now promotion verified: YES

Live-test policy:

reuse this investigation for subsequent Playwright checks on this branch;
confirm scenario identity before every live run (inspect localStorage["confidence-engine-investigation"] + rendered Current Understanding);
do not silently continue against another scenario;
do not create a fresh scenario unless an experiment explicitly requires one;
if this investigation is absent, report TEST-STATE MISSING rather than diagnosing persistence failure;
structural/relative assertions only for LLM output — no exact prose dependency.

114 KiB Raw Blame History Unescape Escape

Confidence Engine — Current Handoff

Repository position

Current green reasoning state

Latest resolved reasoning boundaries

1. Complete substantive selection tie

2. Question-formulation rejection

Current deterministic product-launch evidence

Current product meaning

Not yet proved

Canonical live apparatus for next validation

Next recommended step

Apparatus correction: 60B.101 — null-question start capture

Canonical harness gated apparatus (60B.99)

Experiment 60B.95 result (2026-08-17)

Experiment 60B.97 result (2026-08-18)

Experiment 60B.100 result (2026-08-18)

RETURN-TO-ORIGIN CHECKPOINT

Required methodology-continuity context (read first)

Current Git checkpoint

Status of RTO.14–17

Focused Semantic Deconstruction — Reasoning Status (2026-08-24)

Current state

Canonical focused helper

Product flow context

Semantic rules currently under review (validated in the cumulative diff)

Validated learning (bounded evidence)

EXP13 status: CONTAMINATED

EXP13R / EXP14 (valid but conservative)

Current restart point

LIVE MANUAL WALKTHROUGH FINDING — Focused Progression UI (2026-08-26)

Verified during repaired Run A multi-turn focused-investigation flow

KNOWN UI PROGRESSION / OWNERSHIP DEFECT — Follow-up Selected-Question Duplication

Related observation — Single follow-up / plural-candidate ownership

Status of remaining items after this walkthrough

Important separation note

CONTRIBUTIONS → FINDINGS DOMAIN MODEL (2026-08-26)

Discovery scope

Key finding: Contribution ≠ Finding

Why contributions alone are insufficient

Truth vs relevance must be separate dimensions

User dispositions are semantic, not UI-only

Reopening principle

Contribution → Finding relationship

SituationGraph relationship

Impact on focused → global handoff

Global eligibility matrix

Primary user-facing reasoning object

Product principle alignment

Confidence emerges from:

Decision: FINDINGS-DOMAIN-MODEL-JUSTIFIED

Finding ↔ SituationGraph Reasoning Contract — August 2026

Unresolved implementation choices

Focused Investigation Overlay Workspace — Checkpoint (2026-08-26)

Implemented workspace state (settled, post-commit abeb3fc)

Case overview = orientation / index surface

Investigation opens as an overlay

Overlay close behaviour

Two-column layout on wide screens

Workspace navigation controls

Attention model (implemented)

LLM call boundary

Next direction: Findings validation surface

Default acceptance / exception pattern

Unresolved items to carry forward

Global synthesis constraint (preserved from prior handoff)

Focused → Global Finding Handoff Contract — August 2026

Semantic contract (established)

Minimum handoff unit: FINDING-WITH-DISPOSITION-AND-PROVENANCE

Required content classification

Minimum provenance sufficiency: C — Finding + originating anchor (when available) + contribution reference(s)

Raw provenance crossing rules

Finding state eligibility in case/update evaluation

Disposition validation outcomes

Relevance authority

Standing/confidence authority

Graph anchor and mapping

Handoff rejection boundaries

Allowed case/update outcomes

Case/update authority scope

114 KiB

Raw Blame History

Implemented workspace state (settled, post-commit `abeb3fc`)