docs(confidence-engine): update v0.48 storage handoff
This commit is contained in:
@@ -42,3 +42,9 @@ tests-results/
|
||||
|
||||
# Local Playwright MCP runtime output
|
||||
.playwright-mcp/
|
||||
|
||||
# Playwright experiment screenshots (live-run artifacts, not repo content)
|
||||
*.png
|
||||
|
||||
# Evidence/temp directories from live experiments
|
||||
.evidence-temp/
|
||||
|
||||
+291
-2
@@ -1,8 +1,12 @@
|
||||
# Confidence Engine — Current Handoff
|
||||
|
||||
## Repository position
|
||||
- branch: `feature/decision-closure-ownership-v0.47`
|
||||
- checkpoint commit: `772ae49`
|
||||
|
||||
> **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.
|
||||
@@ -1279,3 +1283,288 @@ These are conceptual attention modes, not implemented routing/state machines. Se
|
||||
- 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.
|
||||
|
||||
### PRIMARY UNRESOLVED ISSUE: Missing `focusedContributions[]` Persistence
|
||||
|
||||
During the multi-turn cold-return experiment, canonical localStorage was observed with:
|
||||
|
||||
```
|
||||
focusedContributions: []
|
||||
```
|
||||
|
||||
while canonical Findings referenced Contribution IDs including:
|
||||
|
||||
```
|
||||
contrib-0002
|
||||
contrib-0003
|
||||
contrib-0004
|
||||
```
|
||||
|
||||
**Therefore the persisted state observed at runtime contained durable Findings whose provenance pointed to Contribution records that were NOT present in the persisted `focusedContributions[]` array.**
|
||||
|
||||
This is structurally important. The distinction must be carefully preserved:
|
||||
|
||||
**PROVED:**
|
||||
- Canonical Findings persist correctly.
|
||||
- Their `contributionId` values persist correctly.
|
||||
- Canonical `focusedContributions[]` was observed empty during the multi-turn experiment.
|
||||
- Persisted Finding provenance references Contributions absent from that canonical array.
|
||||
|
||||
**NOT YET PROVED (unknown mechanisms):**
|
||||
- Why `focusedContributions[]` is empty.
|
||||
- Whether `appendFocusedContribution` fails to reach ScenarioForm state.
|
||||
- Whether ScenarioForm state contains Contributions but autosave writes stale state.
|
||||
- Whether another lifecycle/state transition clears the array.
|
||||
- Whether the issue is persistence, mutation timing, hydration, or another ownership boundary.
|
||||
|
||||
**Do NOT write "Contributions are never persisted" as a settled root cause.** The live evidence proves the persisted canonical snapshot was missing them at the point of observation. The mechanism causing that is still unknown.
|
||||
|
||||
### 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 PRIMARY TASK: Contribution Persistence Trace
|
||||
|
||||
The next boundary for investigation is unmistakable:
|
||||
|
||||
**TRACE ONLY why canonical `focusedContributions[]` is empty in persisted localStorage during real multi-turn use even though Findings reference the corresponding `contributionId` values.**
|
||||
|
||||
Trace must follow actual runtime/source ownership:
|
||||
|
||||
```
|
||||
focused investigation response
|
||||
→ Contribution construction
|
||||
→ callback from ReasoningWorkspace
|
||||
→ ScenarioForm appendFocusedContribution
|
||||
→ setFocusedContributions
|
||||
→ React state
|
||||
→ canonical autosave effect
|
||||
→ saveInvestigation(snapshot)
|
||||
→ LocalStorageProvider
|
||||
→ stored focusedContributions[]
|
||||
```
|
||||
|
||||
Identify the FIRST boundary where the Contribution disappears. Do not assume the answer. The repository previously suggested:
|
||||
|
||||
```
|
||||
ReasoningWorkspace → onFocusedContribution → ScenarioForm → focusedContributions state → autosave
|
||||
```
|
||||
|
||||
but live browser evidence contradicts the expected persisted result. SOURCE ASSUMPTION vs LIVE RUNTIME EVIDENCE must now be reconciled. The browser evidence wins until the discrepancy is explained.
|
||||
|
||||
---
|
||||
|
||||
## Development Principles
|
||||
|
||||
### 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.
|
||||
|
||||
Reference in New Issue
Block a user