# Current Handoff — Confidence Engine

> **Role:** Concise operational snapshot for resuming work today. Not a historical diary.
> The design evolution archive index at `docs/design-evolution/README.md` provides progressive loading of experiment history; load the relevant chapter only when a specific historical question requires it.

## Repository checkpoint

- **Branch:** `feature/investigation-report-v0.55`
- **HEAD:** `37a9a12` — route design evolution provenance through archive index
- **Working tree:** will be clean after v0.59a commit

## Current product architecture

Three distinct routes, not a single page:

```
/                              → Portfolio (notebook index)
/investigations/case-1          → Investigation (working case/pages)
/investigations/case-1/report   → Investigation Report (readable derived summary)
```

**Portfolio = investigator notebook index.** Shows the single canonical persisted investigation card with actions: *View report*, *Continue investigation*, *Restart investigation*. Below the card: *+ Create new investigation* (portfolio-level, not inside the card).

**Investigation = working case.** Contains `ScenarioForm` + `ReasoningWorkspace`. Handles graph reasoning, focused investigation turns, Done/Re-open semantics, Current Understanding synthesis. No Report presentation — that is owned by the dedicated Report route.

**Report = derived artefact.** Renders persisted `investigationReport` snapshot. Generation is on-demand, triggered by the Report page itself (not ReasoningWorkspace). Exactly one `/api/cases/overview` call on first visit; zero calls on subsequent visits. The Report is not canonical reasoning evidence — it is a derived summary for review/export/use.

## Current working product journey

```
Portfolio (/)
  → "Continue investigation"
    → Investigation page (/investigations/case-1)
      → Focused question asked → user answers → Done for now
      → Current Understanding synthesizes
      → If zero Open Questions: "Review current understanding" appears
        OR → "Review current understanding"
          → Report page (/investigations/case-1/report)
            → Generates via /api/cases/overview (once)
            → Persists investigationReport
            → Subsequent visits render persisted snapshot (zero calls)
```

### Restart flow

Portfolio card *Restart investigation* → confirmation dialog (title: "Restart this investigation?") → destructive second confirmation → `clearInvestigation()` (canonical localStorage clear seam). No direct storage-key manipulation.

## Current reasoning / ownership invariants

**Evidence discipline:**
```
RAW USER EVIDENCE
≠ MODEL-DERIVED CONTRIBUTION SEMANTICS
≠ CURRENT CANONICAL FINDING
≠ IMMUTABLE SOURCE OBSERVATION
≠ USER DISPOSITION / AUTHORITY
≠ TURN CONTEXT / PROVENANCE
```

**Finding dispositions:** `null` (eligible working premise), `agree` (user-endorsed), `not_relevant` (excluded from eligible reasoning, provenance retained), corrected Finding. User disposition never directly mutates authoritative graph state.

**Evidence distinctions preserved by the persistence layer.** Contributions preserve: question/context, verbatim answer, model observations, uncertainties, assumptions, relationships, follow-ups, target/provenance, sequence/order. Findings preserve: canonical proposition, sourceObservation, contributionId, originatingTargetNodeId, userDisposition.

### Focused investigation presentation ownership (v0.52)

`FocusedQuestionBody` derives a thread-local subset (`targetNodeId || originatingTargetNodeId`) for every presentation surface. Previously answered content does NOT bleed from one question to another. Verified manually and by targeted Vitest.

### Empty Done + Re-open semantics (v0.53)

- Empty Done is valid: parks/resolves the question locally, does NOT invoke episode processing, does NOT produce `no_episodic_content` 400.
- Re-open returns the question to Open Questions and removes from `doneForNowIds`.
- Older stale development localStorage states (pre-v0.53 shape) may be discarded during current dev phase. No migration required.

### v0.59a — Investigation revision provenance rule

- Investigation has a semantic revision (`investigationRevision`).
- Meaningful persisted Investigation changes advance it by exactly 1.
- Persistence activity itself (autosave, save) does NOT advance revision.
- Report generation records `generatedFromRevision: investigationRevision`.
- Report generation advances revision by 0.
- Equal revisions mean Report reflects current Investigation.
- Different revisions mean the Investigation has changed since Report generation.
- Existing Report remains available (not invalidated).
- Report update/regeneration remains manual (user-triggered).
- Restart clears Investigation + Report via `clearInvestigation()` + `setInvestigationRevision(0)`.
- Report history/comparison remains deferred beyond MVP.

**Semantic transitions that advance revision:**
```
Episode Done (with content)          → +1
Re-open (resolved → unknown)         → +1
Finding proposition correction       → +1
Eligible → not_relevant              → +1
not_relevant → eligible (restore)    → +1
First meaningful change              → =1 (from initial 0)
```

**Transitions that do NOT advance revision:**
```
Autosave                             → 0
Report generation                    → 0
Hydration                            → 0 (reads value)
Empty proposition correction (no-op) → 0
null → null disposition (no-op)      → 0
```

### Zero Open Questions milestone (v0.51)

When all unknowns are resolved and clarified questions exist: "You've now worked through all of the questions we surfaced. Would you like to see an overview of what we understand so far?" with "Review current understanding" button. This occupies the former Open Questions position. The invitation is a milestone, not a readiness/completion judgement.

### Current Understanding refresh invariants

Reconstruct CU when canonical meaning or eligible evidence set changes — NOT when investigation/question status changes alone. Re-open ≠ change what we understand; Finding correction / Not Relevant / completed episode = change what we understand.

## Persistence and Report ownership

- **Canonical persistence owner:** `lib/storage/providers/local-storage.js` (`saveInvestigation` / `loadInvestigation`). All routes read from the same snapshot.
- **Report generation owner:** Report page only (NOT ReasoningWorkspace, NOT Investigation page).
- **localStorage key:** `confidence-engine-investigation` (single canonical key — multi-investigation not yet implemented).
- **Temporary identity:** `case-1`. True multi-investigation persistence/identity is future work.
- **Portfolio client hydration:** Portfolio page uses `'use client'` — initial pre-hydration empty state ≠ absence of persisted data. Always wait for hydrated semantic controls before classifying state.

## Current development / verification constraints

- Canonical dev server at `http://localhost:3000`. Never start/stop/restart/probe it. If unavailable → BLOCKED and stop.
- Playwright MCP: use **Run Playwright code** with semantic locators for known controls. Snapshot refs (`[ref=...]`) are observational only.
- For async/hydration states: use `waitFor({ state: 'visible', timeout })` — not arbitrary sleeps.
- If a prescribed semantic locator cannot find its control → STOP. No fallback to CSS/XPath/DOM traversal.
- Live freeze: once Playwright verification begins, no production file edits until evidence is captured and classified.
- **Tests are instruments, not product truth.** At first deterministic failure: classify PRODUCT vs APPARATUS failure, then stop. Do not enter test-harness repair loops.
- Mocked boundary ownership: if a lower-layer function is mocked, test the value crossing the seam — do not require the mock to reproduce real implementation.

## Current limitations / genuinely open boundaries

**Not yet implemented:**

- Multi-investigation portfolio (search/tag/archive/group)
- Durable investigation identities beyond `case-1`
- Visible Report freshness UI (revision comparison display — backend tracking in place)
- "Update report" action (manual regeneration only)
- Export/copy of Reports to Jira or external document
- Portfolio expansion beyond one canonical investigation
- Report history / comparison

**Known boundaries:**

- Current Understanding and Investigation Report are architecturally distinct artefacts. Plausible interpretations in the Report remain explicitly interpretive, not evidence.
- The `≤5` processing bound observed during development was an experimental apparatus constraint, NOT a product requirement. Six Open Questions surfacing is legitimate product output, not a formulation defect.
- Evidence discipline: what proves useful in live experimentation must be captured at provenance level, not as test diary entries that become operational constraints.

## Next restart point

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.

## Provenance pointers

| Need | Read |
|---|---|
| Product evolution v0.51–v0.58 | `docs/design-evolution/README.md` (progressive loading) |
| Methodology / Return-to-Origin axioms | `docs/current-working-principles.md` §0 (A1–A12) |
| Architecture guardrails | `.claude/architecture-guardrails.md` |
| Task routing by work type | `docs/task-context-packs.md` |
| Broader architectural intent | `docs/architectural-principles.md` |
| Experiment history (specific) | `docs/design-evolution/README.md` → relevant chapter |