From e6f22494130cc29eb94d20d99d70deb28d2290d8 Mon Sep 17 00:00:00 2001 From: robbond Date: Fri, 4 Sep 2026 12:19:20 +0100 Subject: [PATCH] docs(confidence-engine): close v0.60 multi-investigation work --- docs/current-handoff.md | 86 ++++++++++++++++++++++++++++++++++- docs/current-project-state.md | 23 +++++----- 2 files changed, 96 insertions(+), 13 deletions(-) diff --git a/docs/current-handoff.md b/docs/current-handoff.md index 073e3ed..4e7b027 100644 --- a/docs/current-handoff.md +++ b/docs/current-handoff.md @@ -711,12 +711,94 @@ v0.60h: Migrate Report route to use route `[id]` for all identity operations (in - No localStorage used, no provider imported, no module-cache manipulation - All mocks at application-facing boundary only -### Live verification pending +### Live verification (accepted) ---- +- same Portfolio card remained +- same durable ID remained +- same scenario remained +- second Investigation unaffected +- old reasoning state absent +- clean Analyse state visible +- no model call caused by Restart + +## v0.60 is structurally complete + +No remaining current production identity migration is known. v0.60 is structurally complete. + +The established multi-Investigation architecture: + +``` +Portfolio +→ durable-ID Investigation collection + +Create New +→ allocate crypto.randomUUID() +→ navigate to /investigations/{id} +→ no empty Investigation persisted + +Investigation route +→ route [id] owns Investigation identity + +ScenarioForm +→ hydrates by durable ID +→ saves identified snapshots + +Report route +→ loads/saves by route [id] + +Restart +→ preserves Investigation container/id/scenario +→ clears reasoning/Report state +→ leaves other Investigations untouched +``` + +v0.60 result: **STRUCTURALLY COMPLETE**. + +### Acceptance evidence + +- case-1 production dependencies: 0 +- current production unscoped load dependencies: 0 +- current production unidentified save dependencies: 0 +- current user-facing clear/delete Restart callers: 0 +- Portfolio navigation: durable-ID owned +- Report navigation/persistence: durable-ID owned +- legacy singleton compatibility: still present internally, unused by current product, non-blocking deferred cleanup + +### Investigation culmination semantics + +Report is the point-in-time culmination of an Investigation. + +The flow: + +``` +Open Questions investigated +→ user chooses Done for now +→ question parked +→ graph reconsidered +→ Current Understanding regenerated +→ user chooses what to investigate next +→ eventually zero Open Questions +→ milestone invitation +→ "Review current understanding" +→ /investigations/{id}/report +``` + +There is NO active intermediate overview/review surface between "Review current understanding" and Report. The control performs direct route navigation. + +Report represents: Situation, What we understand, What remains plausible when applicable. It does NOT represent a decision recommendation, confidence score, readiness judgement, or proof that the user should act. + +The user retains ownership of whether the understanding is sufficient, whether to act, whether to return to the Investigation, whether to re-open and investigate further. + +Report provenance remains: `generatedFromRevision` against `investigationRevision`, so a Report can later become "Update available" without ceasing to be the valid point-in-time Report generated from its earlier Investigation revision. + +Zero Open Questions ("You've now worked through all of the questions we surfaced") means: the currently surfaced Open Questions have been worked through. It does NOT mean: the user's decision is complete, sufficient confidence, or ready to act. The Engine facilitates the culmination. The user owns what that culmination means for their decision/action. + +Report is the established Investigation culmination. No further product boundary is selected. ## Next restart point +> v0.60 is complete. Report is established as the culmination of an Investigation. No next product boundary is currently selected. Begin the next session by choosing the next unresolved user/product reasoning boundary from current product behaviour and founding principles, rather than continuing storage migration or assuming an old backlog item is next. + Consult `docs/design-evolution/README.md` for progressive loading of product reasoning and provenance chronology; load the relevant chapter only when a specific historical question requires it. The current handoff captures all operational facts needed to resume today. For historical decisions, experiment evidence, or methodology evolution — consult the design evolution archive index or task-context packs as appropriate. diff --git a/docs/current-project-state.md b/docs/current-project-state.md index c21c49a..8c75d70 100644 --- a/docs/current-project-state.md +++ b/docs/current-project-state.md @@ -24,11 +24,11 @@ The product direction is a **facilitated investigation** presented across three ``` / → Portfolio (investigator notebook index) -/investigations/case-1 → Investigation (working case / pages) -/investigations/case-1/report → Investigation Report (readable derived summary) +/investigations/{id} → Investigation (working case / pages) +/investigations/{id}/report → Investigation Report (readable derived summary) ``` -**Portfolio:** Shows the single canonical persisted investigation card. Actions: *View report*, *Continue investigation*, *Restart investigation*. Below the card: *+ Create new investigation*. Restart is confirmation-gated and destructive. +**Portfolio:** Shows the persisted investigation collection. Actions on each card: *View report*, *Continue investigation*, *Restart investigation*. Below the cards: *+ Create new investigation* (allocates durable ID via `crypto.randomUUID()` + navigates to `/investigations/{id}`). Restart is confirmation-gated and preserves container while clearing reasoning/Report state. **Investigation:** Contains `ScenarioForm` + `ReasoningWorkspace`. Handles graph reasoning, focused investigation turns, Done/Re-open semantics, Current Understanding synthesis. Report presentation is NOT part of this route — owned by the dedicated Report page. @@ -61,16 +61,17 @@ Three distinct routes, each with clear ownership: | Route | Owner | Presentation | |---|---|---| -| `Portfolio` (`/`) | Portfolio page + storage | Card with actions; no Report presentation | -| `Investigation` (`/investigations/case-1`) | `ScenarioForm` + `ReasoningWorkspace` | Focused investigation turn cycle | -| `Report` (`/investigations/case-1/report`) | Report page (standalone) | Persisted derived artefact; on-demand generation | +| `Portfolio` (`/`) | Portfolio page + storage | List of Investigation summaries; no Report presentation | +| `Investigation` (`/investigations/{id}`) | `ScenarioForm` + `ReasoningWorkspace` | Focused investigation turn cycle | +| `Report` (`/investigations/{id}/report`) | Report page (standalone) | Persisted derived artefact; on-demand generation | **Key invariants:** ReasoningWorkspace no longer owns Report presentation. The Report is a distinct route/page, not an internal state of the Investigation. ### Persistence and report lifecycle -- Single canonical persisted investigation via localStorage (`confidence-engine-investigation` key). +- Multi-Investigation collection via localStorage (key prefix `confidence-engine-investigation:`). Legacy singleton path retained for backward compatibility (unused by current product). - `saveInvestigation()` / `loadInvestigation()` are the canonical storage seams. +- `listInvestigations()` returns lightweight summaries for Portfolio rendering. - Report generation: first visit → one synthesis call + persist; subsequent visits → zero calls, renders persisted snapshot. - Restart is destructive and confirmation-gated (dialog → explicit second confirmation → `clearInvestigation()`). @@ -108,11 +109,11 @@ The following were built during Experiments 18–25B. They are isolated diagnost ### Not yet implemented (product capabilities) -- Multi-investigation portfolio (search/tag/archive/group behaviour) -- Durable investigation identities beyond `case-1` -- Report freshness / versioning after investigation changes +Multi-investigation storage and portfolio are structurally complete in v0.60. Deferred feature work beyond MVP scope: +- Search, tag, archive, group behaviour within Portfolio - Export/copy of Reports to Jira or external document -- Portfolio expansion beyond one canonical investigation + +Multi-investigation identity is durable (`uuidv4`). Legacy singleton compatibility remains internally (unused by current product). Report freshness / versioning after investigation changes uses `generatedFromRevision` vs `investigationRevision`. ### Methodological unresolved