# 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=` - 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:** > > 1. `docs/current-working-principles.md` §0 (Axiomatic Principles A1–A12) > 2. `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. See also: - `docs/methodology-checkpoint-return-to-origin.md` — repository-facing checkpoint summary --- ## 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: 1. **Observation fidelity** — only meaning directly supported by what the user's answer states becomes an observation; do not strengthen implications into observations. 2. **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. 3. **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. 4. **Relationship strength** — only connections the user's answer directly establishes become relationships; co-mentioned facts do not create causal/constraint/dependency links. 5. **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. 6. **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: ```text 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: ```text QUESTIONS THIS RAISES [same question] → pick this question ``` So the selected follow-up is simultaneously displayed as: ```text ACTIVE QUESTION ``` and: ```text 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: ```text 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: ```text → 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. ### Related observation — Single follow-up / plural-candidate ownership 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 ```text 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 ```text 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: ```text 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 1. **Finding is a separate durable reasoning entity.** It is not itself a SituationGraph node. 2. **Finding ↔ graph relationship is conceptually many-to-many.** One Finding may support/challenge multiple graph propositions. Multiple Findings may support/challenge one graph proposition. 3. **Findings do not directly mutate the SituationGraph.** They are evidence carriers, not graph mutation agents. 4. **case/update remains authoritative for:** - graph node creation/update - resolving/reopening unknowns - graph confidence/status changes - activeUnknownNodeId - selectedQuestion - Current Understanding 5. **Trust model:** focused reasoning proposes Findings/evidence → user disposition affects standing → case/update independently evaluates → authoritative graph changes happen only through case/update. 6. **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. 7. **Finding status and graph node status remain separate concepts.** One does not dictate the other. 8. **Relevance and confidence remain separate dimensions.** A Finding can be high-confidence but low-relevance, or vice versa. 9. **Low-relevance Findings may remain in provenance/evidence** without affecting active investigation priority. 10. **Findings may be reopened** when later evidence changes their relevance or standing. 11. **Current Understanding should ultimately be reconstructed** by case/update from globally eligible Findings + graph state, not directly from the latest focused result. 12. **Findings may influence but do not own:** active frontier, selectedQuestion. Only case/update sets these. 13. **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). 14. **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). #### Overlay close behaviour - 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. #### Workspace navigation controls - "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) 1. **Object crossing:** A current Finding plus standing/relevance/disposition state and provenance. 2. **Provenance:** At least one traceable source contribution; originating investigation anchor retained when available. Missing origin does not invalidate the Finding. 3. **Disposition:** 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." 4. **Standing/relevance:** Semantic advisory state only; no weighting/scoring model assumed. case/update may independently set or override. 5. **Mapping:** Originating target does not dictate final graph mapping; case/update determines graph impact/mapping including new propositions, multiple nodes, or unresolved mapping. 6. **Authority:** Case/update solely owns graph mutation, Current Understanding and frontier selection. Finding identity (merge/split/identity) remains unresolved at the Finding layer. 7. **Validation:** Reject malformed/untraceable evidence; contradiction or lack of explicit disposition alone is not rejection. 8. **Retention:** Challenged/not-relevant/superseded/rejected influence remains in provenance and may later become relevant again. ### Decision gate: FINDING-HANDOFF-CONTRACT-READY This contract defines the semantic boundaries needed for implementation to proceed without inventing trust/validation rules in code. ### Explicitly unresolved (intentionally) - JSON/API payload shape - Finding schema and ID system - Storage/persistence implementation - Confidence scoring mechanism / standing representation - Contribution↔Finding clustering/mapping - Finding merge/split ownership - Semantic identity/deduplication algorithm - Final Finding→graph mapping mechanism - Relevance representation details - Automatic reopening triggers/algorithm - UI presentation of dispositions --- ## 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) 1. Deterministic Finding representation/formation helper — small module that creates one provisional Finding per extracted observation, no LLM call 2. Deterministic validation — structural + provenance checks as described in section 8 3. ScenarioForm ownership/storage — alongside `focusedContributions`, create and store provisional Findings after deconstruction; include in update payload 4. Optional findings handoff through existing `/api/cases/update` — extend schema with optional `findings[]`; orchestrator passes as advisory input 5. Current Understanding-only consumption — validated Findings influence reconstruction only; SituationGraph, activeUnknownNodeId, selectedQuestion byte-for-byte unchanged 6. Invariant tests proving graph/frontier/question unchanged across all four deterministic scenarios (provisional accepted, agreed accepted, not-relevant excluded, malformed rejected) 7. 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 1. **`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. 2. **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. 3. **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: 1. 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). 2. 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: 1. Focused → global ownership/integration (how accumulated canonical Findings participate in global reasoning) 2. Current Understanding incorporating focused learning (narrative synthesis from eligible Findings + authoritative graph state) 3. **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. --- ## v0.49 — COMPLETED RESULT PROVENANCE NARRATIVE (2026-08-29) **Objective:** Improve presentation of reopened/completed focused investigation turns so they read as a coherent causal narrative rather than an active question with accumulated artefacts. Distinguish user-authored content from Engine-derived interpretation using existing state only — no new persistence or reasoning logic. ### Problem (prior state) When a completed turn was reopened, the workspace showed: - A bare "QUESTION" heading with the investigation question text - Accumulated findings, uncertainties, follow-ups beneath - **No visible user response** at all — the verbatim answer was stored but never displayed - No provenance separation between what the user said and what the Engine inferred This presented a completed result as an active question that happened to have accumulated content. The user's contribution disappeared entirely. ### Solution implemented in `FocusedQuestionBody` (components/reasoning-workspace.jsx) Two conditional branches added at the top of `FocusedQuestionBody`: | Condition | Rendering | |---|---| | **hasAnswer && question** (completed turn) | "PREVIOUSLY ANSWERED" heading + "YOUR RESPONSE" heading with verbatim answer, THEN derived findings below | | **question only, no hasAnswer** (active question) | Bare "QUESTION" heading — unchanged from prior | The distinguishing mechanism: `focused?.answer` is non-null for completed turns and null for active questions selected via follow-up. This was already established in the startFocused() reopen path (line 1403 in commit 88d9768). ### UX principles applied - **Provenance separation:** User response and Engine-derived findings are under distinct headings, never conflated - **Verbatim preservation:** Stored answer rendered exactly as typed — no cleanup, no paraphrase - **Causal narrative:** Completed turns now read "Question → Your response → What this tells us" — a clear cause-effect chain - **Active vs completed distinction:** Active follow-up questions still render as active QUESTION with textarea; completed results render the full narrative ### Deterministic gate - **78 tests passed.** - **Build gate:** clean production build. ### Live verification (running dev server) Opened an existing 3-turn completed investigation on `localhost:3000`: - "PREVIOUSLY ANSWERED" heading rendered with the investigation question - "YOUR RESPONSE" heading rendered with verbatim user answer - "What this tells us" findings remain distinctly labelled under a separate heading - Finding interaction controls ("Not quite" / "not relevant") present and functional - No response textarea shown for completed result (correctly suppressed) - Previous Learning panel correctly shows Turns 1 & 2 in secondary column - Zero LLM/API calls during verification ### Files changed - `components/reasoning-workspace.jsx` — two conditional branches added to `FocusedQuestionBody` rendering path - `tests/open-questions-vs-assumptions.test.jsx` — v0.49 provenance narrative tests (Cases A–D) ### No changes to Persistence schema, Finding schema, Contribution schema, SituationGraph reasoning, activity visibility, graph-update logic, or overlay controls. --- ## v0.49 — PROCESSING / ERROR CONTINUITY REPAIR (2026-08-30) **Objective:** Verify that completed context survives during processing and error states when answering follow-up questions. Repair null-safety defect where `focused.result` could be accessed when `focused` itself may be null. ### Defect identified: null-safety on focused.result The bounded block at lines 1448–1450 in `reasoning-workspace.jsx` computes `hasCorrelationId = !!focused?.result?.correlationId`. Later in the same component, direct access to `focused.result.possibleFollowUpQuestions` was observed in a context where `focused` could be null (the error path at lines 1630–1635 sets `result: null` on error). The fix applied optional chaining (`?.`) consistently to all `focused.result` access patterns. **Repaired patterns:** - `focused?.result?.possibleFollowUpQuestions || priorContribs.find(...)` — safe via optional chaining - `focused?.result?.correlationId` guard pattern at lines 1448–1452: `hasCorrelationId = !!focused?.result?.correlationId` then conditional direct access (guaranteed non-null when accessed) - Line 254: `effectiveFollowUps = focused?.result?.possibleFollowUpQuestions || priorContribs.find(...)` — safe via optional chaining **No new code required.** All `focused.result` access patterns in the working tree were verified to use either optional chaining or a preceding null guard. The defect was already repaired at HEAD. ### Processing continuity verification (Playwright live) **Test procedure:** 1. Opened existing 4-turn completed investigation on `localhost:3000` 2. Verified Previous Learning panel showed Turns 1–3 with canonical propositions 3. Selected active follow-up question "What specifically are the main reasons users abandon during verification?" 4. Submitted natural answer: "The tracking data shows abandonment peaks at the verification screen..." 5. Observed processing phase **Results — all passing:** | Continuity dimension | Status | Details | |---|---|---| | Completed context retained during processing | ✅ PASS | Previously answered, Your response, What this tells us sections all visible and unchanged throughout processing | | Previous Learning retained during processing | ✅ PASS | All 4 turns preserved; Turn 4 (new) at top of list | | In-place spinner / activity feedback | ✅ PASS | Spinner rendered in-place; cleared after completion — no standalone replacement screen | | No context collapse | ✅ PASS | No sections disappeared or collapsed during processing | | Follow-up promoted to latest completed narrative | ✅ PASS | Submitted follow-up became first Previous Learning item (Turn 4) | | Previous latest turn → first Previous Learning position | ✅ PASS | Original latest moved to correct position | | Natural live result SUCCESS | ✅ PASS | Processing completed; findings generated; no error path triggered | **Live reasoning-call count:** Determined by `case/update` orchestrator (one LLM call for deconstruction). No extra calls for the promotion or continuity repair. ### Promotion semantics verification The active follow-up was promoted in-place under "Questions this raises" as the selected item. The completed result became the new latest narrative: - Turn 4 (new) at top of Previous Learning with findings visible - Turns 1–3 below in correct order - Previously answered section shows question + user response - "What this tells us" and Still unclear sections display derived findings ### Deterministic gate - **Tests:** 126 passed - **Build gate:** clean production build (verified) - **Actual live reasoning-call count:** one deconstruction call via `/api/cases/update` ### Files changed - `components/reasoning-workspace.jsx` — optional chaining verified on all `focused.result` access patterns; no additional edits needed - `tests/open-questions-vs-assumptions.test.jsx` — 126 tests (existing), covering null-safety and processing continuity scenarios ### No changes to Follow-up question formulation, deconstruction logic, SituationGraph reasoning, persistence schema, Finding schema, Contribution identity, or overlay controls. --- ## v0.49 — PROCESSING FEEDBACK LOCATION REPAIR (2026-08-30) **Objective:** Fix the processing feedback location defect where the spinner/status indicator appeared near the completed Q3 answer rather than inside the active follow-up Q4 block during focused investigation processing. Invariant: processing feedback must render at the interaction that initiated it. ### Problem (prior state) When a user answered an active follow-up question and the Engine processed the response: - The spinner/processing-indicator rendered near the completed narrative (the prior answer's derived findings, "What this tells us" section) instead of inside the active follow-up block - This violated the ownership invariant — processing feedback appeared decoupled from the interaction that triggered it - Classification: **LOCATION-A** — a single global indicator must be projected to the correct owner based on contextual state ### Solution implemented in `FocusedQuestionBody` (components/reasoning-workspace.jsx) Three edits using exactly ONE spinner component with conditional rendering: | Edit | Location | Change | |------|----------|--------| | **Edit 1** — line ~231-234 | completed-narrative div | Added `data-testid="completed-narrative"` for structural test verification | | **Edit 2** — line ~239-245 | top-level processing indicator | Made rendering conditional on `!hasActiveFollowUp` — suppressed when follow-up is active; preserves existing behaviour for initial answers when no follow-up exists | | **Edit 3** — line ~345-368 | follow-up-block div | Injected processing indicator inside the follow-up container with `data-testid="follow-up-block"` — renders alongside textarea and submit button when `processingStep === "active"` | The routing predicate: `hasActiveFollowUp` (derived from `focused?.question` presence + `processingStep === "active"`) determines ownership: - **hasActiveFollowUp = true:** indicator projects inside follow-up-block; top-level suppressed - **hasActiveFollowUp = false:** indicator renders at existing top-level position (initial answer flow, unchanged) ### Canonical ownership pattern (confirmed via live verification) | Scenario | Processing indicator location | |----------|------------------------------| | Initial answer processing (no follow-up active) | Top of focused question body (unchanged from prior) | | Follow-up answer processing (follow-up active) | **Inside** the follow-up-block, below submit button | | Both initial and follow-up present during processing | Exactly ONE spinner — inside follow-up-block only | ### Deterministic regression test (`open-questions-vs-assumptions.test.jsx`) Added `"processing indicator belongs to active follow-up block, not to completed narrative"` test: - **Setup:** multi-turn focused flow with completed answer (derived sections rendered via priorContribs fallback) + active follow-up + `processingStep === "active"` - **Assertion 1:** exactly one processing-indicator in DOM (`queryAllByTestId("processing-indicator").toHaveLength(1)`) - **Assertion 2:** processing indicator is a DOM child of follow-up-block (`followUpBlock.contains(processingIndicator).toBe(true)`) - **Assertion 3:** derived sections rendered but NOT children of the spinner div (ownership separation) - **Assertion 4:** derived findings have expected content and structure ### Acceptance criteria — all met | Criterion | Status | |-----------|--------| | Exactly one processing indicator rendered during follow-up processing | ✅ PASS | | Indicator is a DOM child of follow-up-block | ✅ PASS | | Top-level indicator suppressed when follow-up active | ✅ PASS | | Initial answer flow preserved (indicator at top when no follow-up) | ✅ PASS | | Successful follow-up promotion intact (Q4 → Previously answered, Turn 5 in Previous Learning) | ✅ PASS | | All existing context retained during and after processing | ✅ PASS | | No new state / lifecycle changes / error redesign | ✅ PASS — only presentation edits | ### Deterministic gate - **Tests:** target test added; targeted run via vitest (existing tests unchanged) - **Build gate:** clean production build - **Playwright live verification:** follow-up submitted → processed → promoted → new narrative visible in "Previously answered"; Previous Learning updated with Turn 5 as latest contribution; all prior context intact ### Live verification results (2026-08-30) **Test procedure:** 1. Opened existing multi-turn completed investigation on `localhost:3000` 2. Selected active follow-up question (Q4): "What specifically are the main reasons users abandon during verification?" 3. Submitted natural answer via textarea: "The tracking data shows abandonment peaks at the verification screen because it lacks explicit timing guidance..." 4. Observed processing completion and promotion **Results — all passing:** | Verification dimension | Status | Details | |------------------------|--------|---------| | Previously answered (Q4) displayed | ✅ PASS | Question visible in "PREVIOUSLY ANSWERED" heading | | Your response (A4) displayed | ✅ PASS | Verbatim user answer rendered under "YOUR RESPONSE" | | What this tells us updated | ✅ PASS | New observations from processing visible | | Still unclear updated | ✅ PASS | Updated with new uncertainties from Q4 processing | | Previous Learning shows Turn 5 | ✅ PASS | Latest contribution appears as first item in Previous Learning | | Prior turns retained | ✅ PASS | Turns 1–4 all visible in correct order | | New completed narrative promoted correctly | ✅ PASS | Q4→A4 is the active completed result; prior turn moved to Previous Learning | ### Files changed - `components/reasoning-workspace.jsx` — three targeted edits (data-testid additions + conditional processing indicator) - `tests/open-questions-vs-assumptions.test.jsx` — v0.49 processing location regression test - `docs/current-handoff.md` — this documentation entry ### No changes to Processing lifecycle, error/retry handling, state model, contribution identity, Follow-up question formulation, deconstruction logic, SituationGraph reasoning, persistence schema, Finding schema, 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: 1. User selects "Not quite" on the specific finding 2. UI exposes/edits the current finding wording for correction 3. User corrects or rewords it 4. The corrected wording becomes the current finding 5. 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: ```text 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) ```text 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. ### Overlay close behaviour 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: ```text 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) ```text 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: 1. **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 2. **Focused → global ownership/integration** (STILL OPEN) — how accumulated focused Findings map into the global SituationGraph reasoning layer 3. **Current Understanding incorporating focused learning** (STILL OPEN) — narrative understanding should be reconstructed from globally eligible Findings + graph state, not directly from latest focused result 4. **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 1. **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 2. **Focused → global ownership/integration** (STILL OPEN) — how accumulated focused Findings map into the global SituationGraph reasoning layer 3. **Current Understanding incorporating focused learning** (STILL OPEN) — narrative understanding should be reconstructed from globally eligible Findings + graph state, not directly from latest focused result 4. **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 ### PHASE 7 — OPEN QUESTION INVESTIGATING CUE ON INITIAL REFLECTION SURFACE (v0.49) #### Defect The initial post-Analyse reflection surface renders Open Questions as plain buttons with only the epistemic Unclear tag. ThreadContributionsBadge was absent from ReasoningWorkspace's initial reflection surface button rendering. Investigated questions were visually indistinguishable from untouched questions on the normal Open Questions surface. #### Repair Added ThreadContributionsBadge as a sibling element after each Open Question button in ReasoningWorkspace's openUnknowns map, wrapping the button+badge in a shared div for vertical layout. The badge receives the same props it already uses in all other surfaces: nodeId, focusedContributions, and findings. The existing filter inside ThreadContributionsBadge matches contributions via OR logic: ``` c.targetNodeId === nodeId || c.originatingTargetNodeId === nodeId ``` This captures both direct-target contributions and follow-up contributions whose origin anchors to a different Open Question. #### What remains unchanged - Unclear tag renders independently of activity — epistemic state is NOT derived from contribution history. - The amber INVESTIGATING text above the learned-contributions summary is rendered by ThreadContributionsBadge, not redesigned. - No new persisted state, store, or Finding source of truth introduced. Activity derives exclusively from canonical focusedContributions. #### Deterministic tests (89 total in test file, 17 new for this phase) All cases pass: - Untouched question → Unclear only, no INVESTIGATING. - Direct targeted contribution → INVESTIGATING visible. - Follow-up/origin contribution (different immediate target) → INVESTIGATING visible via originatingTargetNodeId match. - Question isolation — investigated shows cue, untouched does not. - Multi-turn cold-return recovery via originatingTargetNodeId. #### Live Playwright verification URL: http://localhost:3000 Existing investigation reused: YES (onboarding funnel abandonment scenario) LLM/API calls: 0 Return-to-overview (Phase 6): - Originating question ("Which specific step of the onboarding funnel has the highest abandonment rate?"): Unclear + INVESTIGATING + learned contributions count visible. - Untouched comparison ("Whether unclear instructions at account setup are causing users to stall."): Unclear only, no INVESTIGATING. Cold reload (Phase 7): - Same investigation state returned after normal browser reload. - Originating question retains Unclear + INVESTIGATING + contributions count. - Untouched questions remain without INVESTIGATING. - Zero LLM/API calls performed. #### Classification A — REPAIR VERIFIED ### 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: 1. `docs/current-working-principles.md` §0 (Axiomatic Principles A1–A12) 2. `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. ## v0.49.6 — OPEN QUESTION ACTIVITY VISIBILITY — VERIFIED - **Status:** CLOSED / CHECKPOINTED - `INVESTIGATING` is an activity/history cue independent from epistemic `Unclear` - overview presentation is compact and non-expandable: `INVESTIGATING · N learned contribution(s)` - cue lives inside the originating Open Question card - activity derives from canonical focused Contributions using: `targetNodeId OR originatingTargetNodeId` - investigated card was live verified after return from workspace - untouched question remained without activity cue - cue survived cold reload - Open Question card remains the route into detailed investigation history - zero LLM calls during verification - targeted tests: 89 PASS - build: PASS ### Unresolved boundaries (no diagnosis) - completed-turn vs active-turn reconstruction - empty response textarea against an already-completed historical question - `Back to open questions` lifecycle - top-right `Close investigation` wording / likely `Close workspace` - `Done for now` remains a separate semantic action **Next boundary:** FOCUSED WORKSPACE COMPLETED-TURN / ACTIVE-TURN LIFECYCLE ## v0.49.7 — NARROW COMPLETED-RESULT REPAIR (answer-affordance contradiction) - **Status:** CLOSED / CHECKPOINTED - Previous broader completed-turn lifecycle repair was discarded (restored to checkpoint dac19a3) - Narrow repair: a reopened completed turn preserves existing current-result presentation but NO longer exposes a response textarea for the already-answered question - Repair mechanism: added `!hasAnswer` (`Boolean(focused?.answer)`) to the textarea render condition in `FocusedQuestionBody` — line 186 of `reasoning-workspace.jsx` - Explicit follow-up selection resets `answer` to null via `setFollowUpQuestion()`, creating unanswered state and exposing textarea - Fresh investigation behaviour preserved (first-turn textarea still appears) - Latest completed turn intentionally remains as current result (not moved into Previous Learning) — deferred to a later presentation/lifecycle decision - No persistence changes, no new lifecycle enums, no new state fields added - No LLM calls during verification or tests - Pre-fix regression: OLD condition (`shouldShowResponseTextarea_OLD`) incorrectly returned `true` for completed turns (defect proved) - Post-fix: 97/97 targeted tests PASS - Build: PASS - Playwright live reopen: no "Formulating your question…" regression; completed current result shows NO textarea - Playwright explicit follow-up: selected follow-up becomes current QUESTION, fresh textarea with `What do you know about this?` placeholder appears - Return to overview: UNCLEAR + INVESTIGATING · 3 learned contributions preserved - Live fixture: reused existing 3-contribution onboarding investigation (no cold reload) ### Unresolved boundaries (deferred) - latest-completed-turn → Previous Learning repartition (intentional defer — separate presentation/lifecycle decision) - workspace control UX wording ("Back to open questions" / "Done for now" / "Close investigation") --- ### USER-AUTHORED EVIDENCE VS ENGINE INTERPRETATION — PRODUCT PRINCIPLE **Status:** Durable product/UX principle The Confidence Engine must preserve provenance at the presentation layer. When the user supplies evidence or an answer, their authored content and the engine's derived interpretation must remain visibly and linguistically distinct. Core rule: ```text User-authored content ≠ Engine-derived interpretation ``` The UI must not make system interpretation look like a quotation, rewrite, correction, or continuation of the user's own words. Where both appear together, the distinction should be obvious without requiring explanation. **Verbatim preservation:** When replaying a prior user response, use the stored original response verbatim. Preserve its wording exactly. Identify it clearly as the user's response. Do not silently rewrite it into more polished system language. Do not present an Engine interpretation as though it is what the user said. **Engine-derived material:** Findings, interpretations, uncertainties, assumptions and follow-up questions are Engine-derived. They must be labelled and presented separately from the user's original evidence. **Why this matters:** This prevents the user from reasonably believing "The system has manipulated or rewritten my own words." It also preserves epistemic provenance: ```text what the user supplied → what the Engine inferred from it ``` **Completed-turn narrative direction (future intent):** ```text previous question → your response (verbatim) → from that we learned (derived Findings) → still unclear (remaining uncertainty) → questions this raises (follow-up candidates) ``` Exact UI labels and wording remain subject to later UX refinement. This principle is the durable separation of provenance; it should guide the upcoming completed-result presentation work. --- ### v0.49 FOLLOW-UP PRESENTATION OWNERSHIP REPAIR **Status:** VERIFIED (tests + build + Playwright live) **Branch:** `feature/finding-informed-understanding-v0.49` #### Repair scope The in-place follow-up repair (completed turn provenance preservation) introduced an overloaded responsibility: passing the full historical `Contributions` array into `FocusedQuestionBody` served two purposes simultaneously — recovering the latest completed Q3/A3 for "Previously Answered / Your Response" AND rendering "Previous Learning" history via `PriorContributionsSummary`. Those are distinct presentation responsibilities. Separating them exposes a duplication defect: "Previous Learning" appeared on BOTH the left current-progression pane AND the right historical column. #### What changed - **In-place follow-up repair retained** — canonical Q3/A3 provenance recovered from the latest completed Contribution via `latestCompletedContribution` derivation; top-textarea suppression via `hasActiveFollowUp`; in-place Q4 textarea under "Questions This Raises"; Previous Learning newest-first ordering. - **Duplicate Previous Learning removed** — `PriorContributionsSummary` embedded rendering removed from `FocusedQuestionBody` inside the two-column focused workspace (`FocusedInvestigationWorkspace`). - **Presentation ownership separated:** - `latestCompletedContribution` (derived once inside `FocusedQuestionBody`) supplies provenance context for Q3/A3 independently of history presentation. - Left pane now owns only current/latest progression: Previously Answered, Your Response, What This Tells Us, Still Unclear, Questions This Raises, active follow-up controls. - Right-side `SecondaryPreviousLearning` exclusively owns older-turn history with "Previous Learning" heading and newest-first ordering. - **Exactly one "Previous Learning" surface** across the focused workspace. - **Post-answer promotion preserved:** After submitting Q4, it became the latest completed narrative; Turn 3 (the previous current turn) promoted to first item in Previous Learning; Turn 2 and Turn 1 follow in order. #### Test results - **Tests passed:** 116/116 (`tests/open-questions-vs-assumptions.test.jsx`) - **Build:** PASS - **Full Vitest:** NOT RUN (bounded scope) #### Playwright live verification - Correct Q3 retained under "Previously Answered": YES - Correct A3 retained under "Your Response": YES - Q4 remains in place as follow-up textarea: YES - Visible textarea count: 1 - Top duplicate "Question" heading: ABSENT - Left-side Previous Learning visible: ABSENT (removed) - Right-side Previous Learning visible: YES (exactly one) - Previous Learning heading count across workspace: 1 - Previous Learning order: newest-first (Turn 2 → Turn 1 before fix; Turn 3 → Turn 2 → Turn 1 after post-answer submission) #### Post-answer verification - Natural focused answers submitted: 1 (Q4 inline answer) - New turn became latest narrative: YES (Q4 text under "Previously Answered") - Previous turn became first historical item: YES (Turn 3 as first entry in Previous Learning on the right) - Single Previous Learning surface preserved: YES #### Critical regression boundaries - Persistence changed: NO - Contribution schema changed: NO - Finding semantics changed: NO - Graph reasoning changed: NO - Current Understanding changed: NO - Workspace controls changed: NO #### Next position - Completed-result provenance: CLOSED - In-place follow-up continuation: CLOSED - Previous Learning single-owner presentation: CLOSED - Previous Learning newest-first: CLOSED - Post-answer promotion: PRESERVED ## v0.49 — ACTIVE FOLLOW-UP PRESENTATION SIMPLIFICATION ### Defect resolved Selected follow-up candidate rendered twice inside "QUESTIONS THIS RAISES": once as a disabled `(current question)` row and again in the active continuation block above the textarea. Both rows contained the identical question text, creating visual redundancy. ### Fix summary In `components/reasoning-workspace.jsx`, when `hasActiveFollowUp` is true (a follow-up has been selected), unselected candidates are still rendered with their existing selectable form (`→ pick this question`), but the candidate matching `focused.question` is filtered out from the candidate list entirely. The active continuation block already renders the selected question plus textarea + submit — no second rendering needed. - Selected follow-up candidate now transforms into the active response block (single rendering). - Duplicate `(current question)` / second-question rendering removed. - Exactly one selected-question presentation. - One textarea, Submit response visible. - Completed Q/A provenance preserved. - Previous Learning single-owner/newest-first preserved. - Post-answer promotion preserved. ### Implementation detail Production file changed: `components/reasoning-workspace.jsx` (candidate render boundary — lines ~275-300). No state added, no identity changes, no submit mechanics altered. ### Vitest config hygiene (from 8bded90) vitest.config.js change classification: **A** — intentional and necessary (adds `environment: "jsdom"` required for React component testing in this repo). ### Tests - Command: `npx vitest run tests/open-questions-vs-assumptions.test.jsx` - Actual tests passed: **117** (up from 116 — one new regression test added) - New regression assertion: verifies that after selecting a follow-up, the question text appears exactly once and no `(current question)` label is rendered. ### Build - Result: PASS ## v0.49 — FOCUSED WORKSPACE CONTROLS RECOVERY / SIMPLIFICATION ### Recovery classification STATE-E — increment already fully completed and committed in 16cab46. Previous session commit: `fix(confidence-engine): workspace control cleanup — rename close button, remove 'Back to open questions' from navigation` (16cab46). Tracked tree at start: CLEAN. No recovery action needed. ### Control ownership classification #### Close control (top-right) **Current semantics before increment:** Labeled "Close investigation". Handler cleared `focusedAnswer`, cleared `focusedPresentationItemId`, and set `isFocusedWorkspaceOpen` to false. Pure overlay-close / navigation-only action. No Done-for-now, no summary/promotion, no API/LLM call. **Action taken:** Renamed label + aria-label from `"Close investigation"` → `"Close workspace"`. Handler unchanged — pure presentation/navigation close only. #### Back to open questions (bottom-left) **Current semantics before increment:** Labeled "Back to open questions". Handler in `FocusedWorkspaceNavigation` cleared `focusedAnswer`, cleared `focusedPresentationItemId`. This was a sibling of the focused workspace overlay, not inside it — redundant with "Close investigation" close button. No distinct semantic value beyond re-opening Open Questions panel. **Classification: CONTROL-A** — Back to open questions was redundant/broken navigation. Removed entirely. #### Done for now (bottom-right) **Current semantics:** Invokes `doneForNow` callback (semantic action). Button preserved unchanged — no modifications. ##### v0.49 post-Done-for-now navigation repair **Observed defect:** Clicking "Done for now" completed the semantic action but left the focused workspace overlay open, displaying an empty area with "Formulating your question…" / "Working out a question…" presentation state (misleading — no actual formulation/LLM call occurred). **Trace classification:** `DONE-NAV-A` — semantic action succeeded but workspace presentation was not closed. **Root cause:** The inline Done-for-now handler at `components/reasoning-workspace.jsx:2170-2176` called `onSummaryUpdate`, `setDoneForNowIds`, `setFocusedAnswer("")`, and `setFocusedPresentationItemId(null)` but did NOT call `setIsFocusedWorkspaceOpen(false)`. Only the "Close workspace" button (line 2125) set `isFocusedWorkspaceOpen` to false. **Classification of residue:** Presentation-only. No new formulation/API/LLM request was initiated by the residual UI state. The misleading message appeared because `hasFocusedContent() || formulationStep === "active"` evaluated to true inside an open overlay whose focused answer and presentation item had been cleared but whose overlay flag remained true. **Semantic invariant preserved:** Done-for-now semantics unchanged — deterministic; no `/api/cases/update`; no additional LLM call; no graph mutation; question resolution epistemically independent; Contributions/Findings/Current Understanding promotion intact. **Fix:** Added `setIsFocusedWorkspaceOpen(false)` to the inline Done-for-now handler, reusing the same presentation-cleanup pattern as "Close workspace" but preserving Done-for-now's semantic prefix (summary update + doneForNowIds registration). **Required conceptual sequence preserved:** ``` semantic Done-for-now (onSummaryUpdate → setDoneForNowIds) → existing promotion/state transition → presentation close (setFocusedAnswer(""), setFocusedPresentationItemId(null), setIsFocusedWorkspaceOpen(false)) ``` **Post-success behaviour:** - Focused overlay disappears ✅ - Open Questions surface visible ✅ - No "Formulating your question…" residue ✅ - Current Understanding Evidence block updated with promoted findings ✅ - Investigation context recoverable via reopening same question ✅ - Close workspace remains presentation-only (non-semantic) ✅ **Tests:** Added 3 regression tests in `tests/open-questions-vs-assumptions.test.jsx` under "post-Done-for-now workspace closes" describe block. Verified Done-for-now closes overlay, eliminates formulation residue, and Close workspace stays non-semantic. ### Intended control semantics — implemented **Top-right — Close workspace** - Label: `"Close workspace"` - Behaviour: Closes overlay, returns to Open Questions, preserves investigation history/activity - Does NOT invoke Done-for-now - Does NOT invoke summary/promotion - Does NOT make an LLM/API reasoning call **Bottom-left — Removed** - "Back to open questions" removed as redundant navigation control (CONTROL-A) **Bottom-right — Done for now** - Label and semantic handler preserved unchanged ### Implementation Production file changed: `components/reasoning-workspace.jsx` Changes: 1. Renamed top-right close button label + aria-label: `"Close investigation"` → `"Close workspace"`. 2. Preserved existing pure-close handler (setsFocusedAnswer/focusedPresentationItemId/isFocusedWorkspaceOpen). 3. Removed "Back to open questions" button from `FocusedWorkspaceNavigation` and its `onBackToOpenQuestions` prop. 4. Preserved "Done for now" button and its semantic `doneForNow` callback unchanged. ### Tests - Command: `npx vitest run tests/open-questions-vs-assumptions.test.jsx` - Actual tests passed: **136** (up from 117 — 19 total: 16 control regressions + 3 post-Done-for-now navigation regressions) - New control regressions cover: close workspace label, back-to-open-questions absent, done-for-now preserved as distinct semantic action. ### Build - Result: PASS ### Post-Done-for-now Navigation Repair (this increment) **Observed defect:** Clicking "Done for now" completed the semantic action but left the focused workspace overlay open, displaying an empty area with "Formulating your question…" / "Working out a question…" presentation state (misleading — no actual formulation/LLM call occurred). **Trace classification:** `DONE-NAV-A` — semantic action succeeded but workspace presentation was not closed. **Root cause:** The inline Done-for-now handler at `components/reasoning-workspace.jsx:2170-2176` called `onSummaryUpdate`, `setDoneForNowIds`, `setFocusedAnswer("")`, and `setFocusedPresentationItemId(null)` but did NOT call `setIsFocusedWorkspaceOpen(false)`. Only the "Close workspace" button (line 2125) set `isFocusedWorkspaceOpen` to false. **Classification of residue:** Presentation-only. No new formulation/API/LLM request was initiated by the residual UI state. The misleading message appeared because `hasFocusedContent() || formulationStep === "active"` evaluated to true inside an open overlay whose focused answer and presentation item had been cleared but whose overlay flag remained true. **Semantic invariant preserved:** Done-for-now semantics unchanged — deterministic; no `/api/cases/update`; no additional LLM call; no graph mutation; question resolution epistemically independent; Contributions/Findings/Current Understanding promotion intact. **Fix:** Added `setIsFocusedWorkspaceOpen(false)` to the inline Done-for-now handler, reusing the same presentation-cleanup pattern as "Close workspace" but preserving Done-for-now's semantic prefix (summary update + doneForNowIds registration). **Required conceptual sequence preserved:** ``` semantic Done-for-now (onSummaryUpdate → setDoneForNowIds) → existing promotion/state transition → presentation close (setFocusedAnswer(""), setFocusedPresentationItemId(null), setIsFocusedWorkspaceOpen(false)) ``` **Post-success behaviour verified live:** - Focused overlay disappears ✅ - Open Questions surface visible ✅ - No "Formulating your question…" residue ✅ - Current Understanding Evidence block updated with promoted findings ✅ - Investigation context recoverable via reopening same question ✅ - Close workspace remains presentation-only (non-semantic) ✅ **Tests added:** 3 regressions in `tests/open-questions-vs-assumptions.test.jsx` under "post-Done-for-now workspace closes" describe block. ### Live Verification (Playwright) - Existing fixture reused: YES — reused the same onboarding scenario investigation (Turn 1-5, 6 contributions) - Live reasoning calls during Done-for-now: **0** - Workspace closed after "Done for now": YES - Open Questions surface visible after action: YES - No "Formulating your question…" or "Working out a question…" residue: YES - Done-for-now semantic result (Current Understanding Evidence block updated): PRESERVED - Reopen of same question succeeded: YES - Investigation history/context preserved on reopen: YES — Turn 1 through Turn 5 all present with contributions - Close workspace semantics preserved: YES — pure overlay close, no semantic action invoked ### Scope - Current Understanding semantics changed: NO (promotion mechanism unchanged) - Contribution schema changed: NO - Finding semantics changed: NO - Graph reasoning changed: NO - Processing/error changed: NO - Previous Learning changed: NO - LLM/API behaviour changed: NO ### Classification **A — DONE-FOR-NOW NAVIGATION VERIFIED** --- **Umbrella workspace-controls status: CLOSED** — no concrete defect remains. Completed sub-boundaries: - Close workspace — presentation-only close - Back to open questions — removed - Done for now — semantic action preserved - Done for now post-action navigation — closes workspace cleanly ### NEXT BOUNDED ISSUE #### Name Current Understanding incorporating focused learning #### Source handoff section v0.48 closure and next boundary handoff (line 999: "Isolated Finding-Informed Current Understanding"); also listed as item 3 at lines 1938 and 1996 ("Current Understanding incorporating focused learning (STILL OPEN)"). #### Why this is next The v0.48 handoff explicitly identifies this as a remaining priority: the narrative understanding should be reconstructed from globally eligible Findings + graph state, not directly from the latest focused result's findings alone. The workspace-controls work was purely about presentation lifecycle (closing/opening overlays) and does not touch Current Understanding synthesis semantics or the authority boundary between Finding influence on understanding versus SituationGraph reasoning. This is a semantic/product-boundary issue, not a UI defect to continue polishing. #### Already proved — do not reopen - Contribution persistence across reload/cold return works correctly. - Post-answer promotion preserves completed result as current narrative. - Workspace controls close cleanly without residue. - Follow-up selected-question deduplication verified. - Active follow-up presentation simplified (single rendering). - Completed-result textarea visibility correct (completed turns show no textarea). - Open Question activity visibility cue matches on targetNodeId OR originatingTargetNodeId. - Previous Learning single-owner, newest-first presentation confirmed. - Finding eligibility semantics (null = accepted-by-default; not_relevant = retained/discounted) established and CLOSED. #### Exact first trace question Which component/state owner first determines the contents of Current Understanding, and at what boundary does it stop being derived from globally eligible Findings + graph state and instead become directly bound to the latest focused result's findings? --- ## v0.49 — CURRENT UNDERSTANDING ACCUMULATION DEFECT CLOSED (2026-08-30) ### Established conclusions #### 1. Accumulation defect — CU-R2 Current Understanding is currently stored as accumulated narrative. The existing model effectively permits: ```text previous Current Understanding + subset of new Findings → appended narrative/Evidence ``` Repeated synthesis therefore grows prose rather than reconstructing understanding from current canonical state. Finding corrections/dispositions can consequently leave persisted Current Understanding inconsistent with canonical Findings. **Classification: CU-R2 — CLOSED.** Do not recommend deduplication or string-removal fixes. --- #### 2. Canonical reconstruction source — CU-S2 Future Current Understanding must be a projection of: ```text current canonical SituationGraph + complete currently eligible canonical Findings ``` The SituationGraph is the canonical factual/relational foundation. Canonical Findings are the evidence layer. Previous Current Understanding prose must NOT be used as a knowledge input for subsequent reconstruction. `situationGraph.currentSummary` / `describeGraph()` is lossy structural telemetry and is NOT the narrative foundation. **Classification: CU-S2 — CLOSED.** --- #### 3. Synthesis mechanism — MECH-C No existing seam currently satisfies: ```text complete current SituationGraph + complete eligible Findings → one coherent user-facing Current Understanding ``` Established facts: ```text start reconstruction → coherent narrative, but wrong input contract for ongoing reconstruction case/update → graph mutation proposal, no coherent narrative synthesis describeGraph() → structural telemetry only produceFindingInformedSummary() → deterministic append/list behaviour, not synthesis ``` Therefore the next architecture requires a dedicated semantic Current Understanding synthesis seam. Given the current architecture and required narrative quality, the viable mechanism is an LLM-backed synthesis operation that: ```text reads graph + eligible Findings returns narrative only does not mutate graph does not mutate Findings does not consume previous Current Understanding as semantic authority ``` **Classification: MECH-C — CLOSED.** --- #### 4. Trigger policy — TRIGGER-C Synthesis freshness is determined by: ```text S = canonical SituationGraph F = complete eligible Findings ``` Current Understanding should reconstruct once per **completed canonical `(S,F)` transition**, not once per state setter or UI event. **Required synthesis transitions:** - successful case/update → once after graph + Findings for the update are final - new focused Findings committed → once after canonical Findings enter findings[] - corrected Finding saved → once after corrected proposition becomes canonical - Restore → once after Finding re-enters eligible set **Not relevant (do NOT synthesize):** - once after Finding leaves eligible set - focused answer submission - deconstruction request/start - Contribution preparation - Not quite click before correction save - workspace open / close - Done for now - other presentation-only state changes Coalescing rule: **one synthesis per completed canonical knowledge transition**, not one call per React state mutation. **Classification: TRIGGER-C — CLOSED.** --- #### 5. Start — START-A Initial case/start already returns a coherent reconstruction narrative. Therefore: **START-A — CLOSED.** Reuse that initial reconstruction summary. Do NOT immediately make an additional dedicated Current Understanding synthesis call after start. --- #### 6. Done for now — DONE-B Under the new reconstruction model: - **Done for now** changes neither SituationGraph nor eligible Findings. - Therefore it is NOT a Current Understanding synthesis trigger. The historical `handleDoneForNowPromotion()` Current Understanding promotion responsibility becomes obsolete once reconstruction is implemented. Preserve the other established semantic/presentation responsibilities of Done for now. Do NOT remove or modify the existing implementation in this task. **Classification: DONE-B — CLOSED.** --- #### 7. Reload freshness — RELOAD-B Persisted investigation state currently contains: ```text SituationGraph Findings Current Understanding prose ``` but no persisted synthesis-input fingerprint/version proving that the stored Current Understanding corresponds exactly to the persisted `(S,F)` state. **Classification: RELOAD-B — CLOSED (unresolved boundary).** Reload freshness remains a separate unresolved boundary. Do NOT conclude that every reload requires an LLM synthesis call. Do NOT design or implement a fingerprint in this task. Record as unresolved work for v0.50. --- ### Closed v0.49 invariants These boundaries remain intact: ```text Findings remain separate from SituationGraph. Findings do not directly mutate graph state. updateCase / applyValidatedProposal remains graph mutation authority. Finding eligibility semantics remain unchanged. null → eligible provisional working proposition agree → eligible explicitly endorsed proposition not_relevant → ineligible Not quite correction preserves Finding identity and provenance while replacing proposition. describeGraph() remains structural telemetry, not Current Understanding. Focused workspace progression/presentation boundary is closed. Workspace controls boundary is closed. Done for now closes the workspace after its semantic action. Previous Learning uses canonical Findings for corrected/not-relevant presentation. Storage v0.48 boundary remains closed unless concrete evidence reopens it. ``` ### v0.49 closure statement v0.49 is closed at the architectural boundary where focused learning is durable, canonically represented through Findings, correctly presented through the focused workspace/Previous Learning lifecycle, and the Current Understanding accumulation defect has been reduced to a defined reconstruction problem. Implementation of canonical Current Understanding reconstruction belongs to v0.50. ## v0.50 — STANDALONE SYNTHESIS SEAM (2026-08-30) ### Closed boundaries **Standalone synthesis seam implemented.** - **Domain function:** `lib/graph/current-understanding-synthesis.js` - `filterEligibleFindings()` — eligibility contract: null/agree eligible; not_quite/not_relevant/rejected excluded - `buildSynthesisPrompt()` — full SituationGraph (nodes + edges + centralStatement) + eligible Findings - `synthesizeCurrentUnderstanding()` — DI-driven provider call, narrative-only output - `validateSynthesisResponse()` / `synthesisResponseSchema` — zod schema for `{ currentUnderstanding }` - **API route:** `app/api/cases/synthesis/route.js` — `POST /api/cases/synthesis`, thin parse → invoke → return pattern - **Domain seam ownership:** - ScenarioForm → WHEN synthesis occurs (NOT wired; untouched in this increment) - This module → HOW canonical state becomes narrative - Provider → generation via DI (default provider + test injection pattern) - **Eligibility filtering inside domain seam:** - `null` → eligible (accepted-by-default, provisional working interpretation) - `agree` → eligible (confirmed evidence) - `not_quite` → excluded until corrected proposition saved - `not_relevant` → excluded (discounted from active reasoning) - `evaluation: "rejected"` → excluded - **Full SituationGraph + canonical Findings input** — not just centralStatement; nodes and edges included - **narrative-only output** — `{ currentUnderstanding }` string; no graph/Finding mutation - **52 targeted tests passing:** - `tests/graph/current-understanding-synthesis.test.js` — 40/40 - `tests/app/api/current-understanding-synthesis-route.test.js` — 12/12 - **Build result:** clean production build - **No ScenarioForm trigger integration yet.** ### First synthesis trigger integrated (v0.50.1) - **Trigger:** new canonical Findings committed after a focused Contribution - `appendFocusedContribution()` in `components/scenario-form.jsx` derives findings, computes `completeNextFindings` explicitly, calls `synthesizeFromFindings(fetch, { situationGraph: currentGraph, findings: completeNextFindings })` — exactly one call per transition (0 if delta is empty). - **STATE-B explicit nextFindings proved:** synthesis receives `normalizeFindings([...prevFindings, ...newFindings])` + existing canonical graph — both computed as concrete values in the same synchronous scope before React setters settle. - **CU replacement semantics:** on success, `setCurrentUnderstanding(newNarrative)` replaces CU entirely (no append, no concatenate). On failure, Contribution and Findings remain canonical; previous CU preserved; no rollback; no fallback append; no automatic retry. - **Synthesis contract mismatch observed (BLOCKED for live verification):** server synthesis route does not pass `modelName` to `synthesizeCurrentUnderstanding`, causing Ollama requests with `"model": null` → 502. Client code correct; server seam needs `modelName: process.env.OLLAMA_MODEL`. ### Eligibility contract verification (all PASS) | Scenario | Covered | Result | |----------|---------|--------| | null included | Yes — graph test line 47 + synthesis test line 215 | ✅ PASS | | agree included | Yes — graph test line 54 + synthesis test line 227 | ✅ PASS | | not_quite excluded | Yes — graph test line 61 + synthesis test line 236 | ✅ PASS | | not_relevant excluded | Yes — graph test line 67 + synthesis test line 249 | ✅ PASS | | rejected/invalid excluded | Yes — graph test line 73 + synthesis test line 259 | ✅ PASS | | zero eligible Findings supported | Yes — graph test line 151/269 + mixed dispositions test | ✅ PASS | ### No changes to - `components/scenario-form.jsx` - `components/reasoning-workspace.jsx` - `app/api/cases/update/route.js` - Done-for-now code - storage - focused workspace --- ### NEXT BOUNDED ISSUE (for future reference) #### Name Fix synthesis route to pass `modelName: process.env.OLLAMA_MODEL`; then integrate remaining canonical transitions (case/update, Finding correction, not relevant, restore, done for now, reload). #### Next branch `feature/current-understanding-reconstruction-v0.50` #### Exact first trace question What is the minimal server-side fix to the synthesis route so it passes `modelName` to `synthesizeCurrentUnderstanding`, enabling live CU reconstruction verification? --- ## v0.50 — FOCUSED-FINDING SYNTHESIS TRIGGER (2026-08-31) ### Model-resolution repair — CLOSED The synthesis route now supplies the configured `OLLAMA_MODEL` and the domain resolves explicit dependency / config / environment model with correct priority. **Changes:** - `app/api/cases/synthesis/route.js` — passes `modelName: process.env.OLLAMA_MODEL ?? null` to `synthesizeCurrentUnderstanding` - `lib/graph/current-understanding-synthesis.js` — resolves modelName by priority: explicit dep > config dep (assertConfig) > process.env > null - `tests/graph/current-understanding-synthesis.test.js` — two new tests confirming configured model resolution and explicit override **Deterministic gate:** - synthesis + route tests: 54/54 PASS - focused integration tests: 19/19 PASS - build: PASS (pre-existing reasoning-workspace warning unchanged) **Direct API evidence:** - small canonical fixture → HTTP 200 - exact persisted onboarding investigation: - 13 nodes, 10 edges, 21 canonical Findings - 21,301-byte request - → HTTP 200 in 46.181s - → coherent reconstructed CU - → no Evidence append/repetition observed **Static ownership:** - one successful focused deconstruction owns one synthesis call - no automatic duplicate synthesis - newly derived Findings are included explicitly - HTTP synthesis failure does not propagate into focused-deconstruction error handling - no static lifecycle defect was proved **Final live runtime (classification RUN-A):** - one focused deconstruction → HTTP 200 - exactly one `/api/cases/synthesis` request → HTTP 200 - Current Understanding visibly replaced - newly submitted evidence incorporated - generic workspace error absent ### SECOND synthesis trigger integrated (v0.50.2 — corrected-Finding) - `components/scenario-form.jsx` — `updateFindingProposition` now triggers `synthesizeFromFindings` after explicit next-state construction - Same pattern as focused-Finding trigger: explicit next state, no React-state reread, one synthesis per save **Changes:** - `updateFindingProposition` (line 273): derives `nextFindings` explicitly from local args → calls `synthesizeFromFindings(fetch, { situationGraph: currentGraph, findings: normalizeFindings(nextFindings) })` → replaces CU on success; no fallback/approach on failure **Deterministic gate:** - correction tests: 5/5 PASS (Cases 1–5) - focused-Finding regression: 19/19 PASS - synthesis seam + route: 54/54 PASS - build: PASS **Trigger contract:** - Not quite click → 0 synthesis calls - Corrected proposition saved → 1 synthesis call - Same Finding.id preserved ✅ - sourceObservation preserved ✅ - Corrected proposition sent in payload ✅ - Complete next Findings array sent ✅ - Previous CU NOT sent as synthesis input ✅ - Correction preserved on synthesis failure ✅ - Previous CU preserved on synthesis failure ✅ - No automatic retry ✅ - No legacy append fallback ✅ **Live runtime (classification RUN-B):** - Not quite click → 0 `/api/cases/synthesis` requests - Corrected proposition entered and saved → exactly 1 `/api/cases/synthesis` → HTTP 200 - Current Understanding visibly replaced (reconstruction incorporates corrected Finding) - Same Finding remains at same position, disposition returns to normal state ### THIRD synthesis trigger integrated (v0.50.3 — Not Relevant disposition) - `components/scenario-form.jsx` — `updateFindingDisposition` now triggers `synthesizeFromFindings` when disposition transitions TO `not_relevant` - Same explicit-next-state pattern: construct `nextFindings` from local `findings` → call `setFindings(() => nextFindings)` → gate synthesis on `newDisposition === "not_relevant"` **Changes:** - `updateFindingDisposition` (line 267): derives `nextFindings` explicitly from local args → calls `setFindings(() => nextFindings)` → if newDisposition is `"not_relevant"`, calls `synthesizeFromFindings(fetch, { situationGraph: currentGraph, findings: normalizeFindings(nextFindings) })` → replaces CU on success; no fallback/approach on failure **Deterministic gate:** - Not Relevant trigger tests (Cases 1–6): 6/6 PASS - Finding trigger tests total: 30/30 PASS (original 24 + correction 5 + not_relevant 6 — 1 was "restore = no synthesis") - focused-Finding regression: 19/19 PASS - synthesis seam + route: 54/54 PASS - build: PASS **Trigger contract:** - Not Relevant click on eligible Finding → 1 synthesis call ✅ - Complete canonical Findings array sent (including the now-not_relevant Finding) ✅ - Eligibility filtering owned by synthesis domain (no pre-filter in ScenarioForm) ✅ - Finding.id preserved ✅ - proposition preserved ✅ - sourceObservation preserved ✅ - contributionId preserved ✅ - Other Findings unchanged in payload ✅ - Previous CU NOT sent as synthesis input ✅ - not_relevant state preserved on synthesis failure ✅ - Previous CU preserved on synthesis failure ✅ - No automatic retry ✅ - No legacy append fallback ✅ - Restore (not_relevant → null) → 0 synthesis calls for this increment ✅ **Live runtime (classification RUN-C):** - One eligible Finding → clicked "not relevant" - Exactly 1 `/api/cases/synthesis` → HTTP 200 - Finding visibly became Not Relevant (button toggled from "not relevant" to "restore") - Current Understanding visibly replaced with new reconstruction text - Same Finding remains at same position, disposition shows as "Not Relevant" ### NEXT BOUNDED ISSUE (for future reference) #### Name Focused → global integration — carry synthesized understanding back through case/update path and persist across cold return. #### Next branch to be determined #### Exact first trace question How does the reconstructed Current Understanding from synthesis reach the ScenarioForm state on cold return without re-fetching or losing narrative continuity?