docs(confidence-engine): record current understanding isolation blocker

2026-08-26 16:30:32 +01:00
parent 3235c35cf0
commit 48b7185176
1 changed files with 56 additions and 0 deletions
@@ -830,3 +830,59 @@ Proof: The v1 code path ensures (a) Findings are typed as a separate schema from

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