confidence-engine/docs/current-handoff.md

Current Handoff — Confidence Engine

Role: Concise operational snapshot for resuming work today. Not a historical diary. See docs/design-evolution-log.md for v0.51–v0.58 progression and provenance.

Repository checkpoint

• Branch: feature/investigation-report-v0.55
• HEAD: 7db28c8 — first Report generation lifecycle verified
• Working tree: clean (documented)

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.

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
• Report freshness/versioning after investigation changes
• Export/copy of Reports to Jira or external document
• Portfolio expansion beyond one canonical investigation

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

Read docs/design-evolution-log.md section "v0.51–v0.58 progress" for the full product reasoning and provenance chronology.

The current handoff captures all operational facts needed to resume today. For historical decisions, experiment evidence, or methodology evolution — consult the design-evolution log or task-context packs as appropriate.

Provenance pointers

Need	Read
Product evolution v0.51–v0.58	docs/design-evolution-log.md
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-log.md § named section only