diff --git a/docs/current-handoff.md b/docs/current-handoff.md index 9e90970..113836c 100644 --- a/docs/current-handoff.md +++ b/docs/current-handoff.md @@ -2541,3 +2541,260 @@ The v0.48 handoff explicitly identifies this as a remaining priority: the narrat #### 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 — NEXT BOUNDARY + +The first bounded question for the next branch: + +> **What minimal synthesis API/helper boundary should own the dedicated `SituationGraph + eligible Findings → Current Understanding` LLM operation?** + +Do not answer that question in this task. + +Subsequent v0.50 work will need to resolve: + +1. synthesis API/helper ownership +2. deterministic input normalization / eligible-Finding selection +3. synthesis prompt/schema contract +4. completed-transition integration points +5. removal/replacement of append semantics +6. retirement of Done-for-now CU promotion +7. reload/cache freshness strategy +8. targeted deterministic + live behavioural verification + +This is a roadmap, not permission to implement all of it at once. +v0.50 must continue using bounded increments. + +--- + +### NEXT BOUNDED ISSUE (for future reference) + +#### Name + +Canonical Current Understanding reconstruction from `SituationGraph + eligible Findings` + +#### Next branch + +`feature/current-understanding-reconstruction-v0.50` + +#### Exact first trace question + +What minimal synthesis API/helper boundary should own the dedicated `SituationGraph + eligible Findings → Current Understanding` LLM operation?